Files
clean-architecture-frontend…/docs/architecture/starter-experience.md
DongHyeonka 06ffafa25e docs: 살아 있는 문서의 낡은 문장을 지금 코드와 정본에 맞춘다
2026-11-07~08의 정리(문서 이동, 참조 기능 삭제, CI 재편) 뒤 살아 있는
문서가 지금 코드와 다른 말을 한다.

- 현재 계약 문서 둘과 스타터 문서가 기록(docs/design/)을 정본으로
  가리킨다. 정본을 frontend-application-foundation.md·src/bootstrap/,
  패턴 표·계층 규칙으로 바꾸고 설계서는 배경으로 둔다(1112/02-06).
- 실시간 대응표 둘(짝 백엔드 출구, poll attempt 결과)이 기록에만 있었다.
  optional-adapter-recipes.md로 옮기고 코드 주석·매뉴얼 03·설계서 머리
  블록이 옮긴 곳을 가리킨다(1112/09-02).
- 실행 격리 변수 목록을 설계 기록이 아니라 scripts/lib/run-isolation.ts로
  가리킨다(1112/08-17).
- 계약 소유 절 이름(「판단 규칙」), pin 대조 시험의 게이트(005·007),
  drift 검사 범위(1112/02-07). INVENTORY 머리의 손 숫자와 지킬 수 없는
  꼬리 문장(1112/02-08).
- 검증 안내: 검사기를 바꾸면 FE-GATE-029, 문서면 desktop
  verify:documentation(1112/08-05, 08-04). FE-GATE-012는 merge 단계다
  (08-16). N6이 알리는 파일을 좁혀 적는다(08-10). 한 파일 시험은
  verify.sh exec(08-11). 문서 검사 범위의 손 사본을 정본 한 곳으로(08-07).
- create:feature 참조의 Next: 3과 되돌리기(08-08), 손으로 옮긴 숫자
  (08-19), 라운드 없는 리뷰 ID 17곳에 0925를 붙인다(08-15).
- secret scan 범위 설명(1112/07-03), lab이 기능 라우트를 읽는 문장
  (1103/16-06), README 동기화 기준점·제품 소유 파일·선택 기능 결함 몫
  (0929/14-02, 14-03, 13-10), 커밋을 다시 지은 모든 통합의 해시 대조
  (1106/14-02).

고른 방법: 문장을 코드에 맞춘다. 표는 옮기고 숫자는 정본을 가리킨다.
버린 대안: 기록 문서 본문 고치기(기록은 머리 블록만 고친다).

위험·한계: 문서 검사 범위 목록을 지운 ci-quality-gates.md는 이제
docs/README.md 5절과 gates.md 7절을 읽어야 한다. 매뉴얼 02 7절 업로드
예의 declare module 문제(1112/09-01)는 고치는 방향이 check:architecture
규칙과 부딪쳐 결정 대기로 남긴다.

검증: scripts/verify.sh docs(노트북) 통과. desktop verify:documentation과
FE-GATE-005(문서를 읽는 시험)는 PR 본문에 적는다.

Refs: 1112/02-06, 1112/02-07, 1112/02-08, 1112/07-03, 1112/08-04,
 1112/08-05, 1112/08-07, 1112/08-08, 1112/08-10, 1112/08-11, 1112/08-15,
 1112/08-16, 1112/08-17, 1112/08-19, 1112/09-02, 1103/16-06, 0929/14-02,
 0929/14-03, 0929/13-10, 1106/14-02
2026-11-12 23:36:14 +09:00

24 KiB

스타터 경험 계약

이 repo는 인프라 계약만 주지 않는다. 바로 실행되는 앱을 준다. 이 앱은 특정 도메인에 묶이지 않는다. 스타터 경험(starter experience)은 일부러 페이지 단위로 갈아 끼울 수 있게 만들었다. 셸, provider, 경계, UI primitive, 상태 화면(state surface)은 그대로 다시 쓴다.

runtime 조립

validated config + coherent release manifest
  -> concrete adapters
  -> QueryClientProvider
  -> ApplicationProvider
  -> RouterProvider
  -> ThemeProvider
  -> SessionProvider
  -> AppShell
  -> lazy route boundary

설정 검증이나 release 정합성 검사가 실패하면 부팅은 제품 화면을 마운트하기 전에 멈춘다. 지연 로드(lazy) 페이지는 각각 Suspense와 telemetry를 남기는 라우트 경계 안에서 렌더링된다. 라우트가 바뀌면 포커스가 새 페이지 제목으로 옮겨진다. 건너뛰기 링크(skip link)와 랜드마크는 셸에 고정되어 바뀌지 않는다.

등록된 라우트

라우트 목록은 ROUTE_REGISTRY(src/features/installed-feature-contracts.ts)다. src/contracts/routes.ts의 플랫폼 라우트에, 설치된 모든 feature의 라우트를 더한 것이다. 플랫폼 개요 페이지(/examples/platform)가 조립된 목록을 실행 중에 보여 준다. 그래서 이 문서는 목록을 따로 복사해 두지 않는다.

내비게이션의 이름과 순서는 ROUTE_REGISTRY에서 온다. 사이드바는 라우트 목록을 따로 두지 않는다. 클라이언트가 내리는 접근 판단은 어디서도 인가(authorization)라고 내세우지 않는다.

인증 연결 지점

세션 port가 제공하는 것은 상태 구독, 로그인 시작, 로그아웃, 자격 증명(credential) 붙이기, 세션 복구, 미인증 알림이다. application 계층과 presentation 계층은 자격 증명의 내용을 들여다보지 않는다.

  • demo: 로컬·개발 환경에서만 쓰는 상태 전환이다. 자격 증명이 없다.
  • external: globalThis.__CA_FRONTEND_AUTH_OWNER__에 맡긴다.
  • 외부 owner가 없거나 잘못됐을 때: integration-failed로 막고 실패한다(fail closed).

외부 owner는 readState, readSubject, subscribe, beginSignIn, signOut, attachCredential, recoverSession, notifyUnauthenticated를 구현한다. 토큰을 받아 오고 저장하는 일은 owner가 맡는다. 이 메서드 중 하나라도 빠진 owner는 거부된다. 그러면 세션은 integration-failed로 막힌다(fail closed).

owner가 일으키는 상태 전환과, 응답마다 recover()가 남기는 상태는 src/application/ports/auth-session-port.ts의 SessionState와 SessionGateway.recover에 적혀 있다. 짝 백엔드(paired backend)의 두 인증 모드에는 새로 쓰지 않고 복사하면 되는 owner가 있다. JWT 모드는 recipes/session-owners/oidc-pkce-session-owner.ts다(Keycloak, PKCE를 쓰는 authorization code, EXTERNAL_BEARER). Redis 세션 모드는 recipes/session-owners/cookie-session-owner.ts다(세션 쿠키, 그리고 SESSION_COOKIE_* 프로필과 X-XSRF-TOKEN provider). docs/manual/04-paired-backend-session.md가 이 둘을 연결한다. 백엔드 템플릿이 주지 않는 것도 이 문서에 적혀 있다. realm 안의 브라우저 클라이언트, 그리고 로그인·로그아웃·세션 endpoint다.

readSubject()는 필수다. subject는 로그인한 사용자를 가리키는 식별자다. 서버 상태 캐시는 세션 상태나 subject가 바뀔 때만 비운다. 그래서 같은 사용자의 토큰을 갱신해도 캐시된 데이터는 남는다. readSubject()는 다음을 돌려줘야 한다.

  • 내용을 해석하지 않는 빈 값이 아닌 문자열. 한 사용자는 토큰을 갱신해도 값이 같고, 사용자끼리는 값이 달라야 한다. 예: OIDC sub claim, Supabase session.user.id, Firebase user.uid
  • 아무도 로그인하지 않았으면 null
  • access token, refresh token, 그 밖의 어떤 자격 증명도 돌려주지 않는다

owner가 authenticated를 알리는데 readSubject()가 null이나 ""를 돌려주면, runtime은 토큰 갱신과 계정 전환을 구별하지 못한다. 이때는 막힌 쪽으로 실패한다(fail closed). 그런 알림이 올 때마다 서버 상태를 비운다. 그리고 매번 cache.operation.failed 진단을 operation: SCOPE_FENCE, reason: SUBJECT_MISSING과 함께 남긴다. 이 진단이 보이면 owner가 subject를 알려 주지 않는다는 뜻이다. demo adapter는 고정된 데모 사용자 하나를 subject로 알린다.

마이그레이션: 예전에는 readSubject()가 선택이었다. 이전 release에 맞춰 쓴 owner는 이 메서드를 더해야 한다. 없으면 시작할 때 owner가 거부된다(세션이 integration-failed가 된다). TypeScript로 쓴 owner는 ExternalSessionOwner에 맞춰 더는 컴파일되지 않는다. AuthSessionPort나 SessionGateway를 직접 구현한 코드도 같은 식으로 getSubject()를 더해야 한다.

스타터 확장

새 플랫폼 작업은 따로 노는 라우트 규칙이나 데이터 로딩 규칙을 하나 더 만들지 않는다. 대신 지금 규칙인 기능 매뉴얼의 패턴 표와 계층 규칙을 따른다. 설계 배경(기록)은 라우팅, 페이지 템플릿, 재사용 패턴과 TypeScript, 상태, 데이터 흐름 목표다.

스타터 화면 바꾸기

/(src/presentation/pages/home-page.tsx)는 플랫폼의 APP_HOME이다. feature가 그 route id를 선언하면 이 자리를 넘겨받는다("제품 홈과 레이아웃" 참고). 홈에 있는 스타터 링크는 내비게이션의 처음 세 화면이다.

템플릿은 예제 feature를 주지 않는다. 예제 화면(/examples/ui, /examples/states, /examples/auth)과 참조 샘플은 2026-11-07에 지웠다. 디자인 시스템 갤러리와 화면 상태 갤러리는 workshop story (src/presentation/design-system/galleries.stories.tsx)다. feature를 만드는 방법은 매뉴얼(docs/manual/)과 create:feature가 보여 준다. 제품이 한동안 남겨 두는 샘플은 scripts/lib/removable-template-features.ts에 적는다. verify:documentation은 샘플이 설치돼 있는 동안 그 경로를 검사한다. 샘플의 feature-module.ts가 없어지면 그 경로를 받아들인다(1105/14-01). corepack pnpm test:sample-removal은 repo 복사본에서 샘플을 지우고 그 복사본에서 gate를 돌린다.

플랫폼 개요(/examples/platform, src/presentation/examples/platform-overview-page.tsx)는 플랫폼 라우트로 남는다. 이 페이지는 설치된 registry를 보여 준다. lab gate(FE-GATE-026)는 이 페이지에 들어가는 시간을 잰다. feature 라우트라면 처음 들어갈 때 페이지보다 먼저 그 context의 routes 모듈도 불러온다. 이 두 번째 요청 왕복은 200 ms budget 안에 들어가지 않는다. 이 페이지의 테스트는 tests/component/starter-*.test.tsx 파일들이다.

플랫폼의 component 테스트(router, 경계, 셸, runtime 트리)는 tests/helpers/fixture-feature.tsx에 있는 테스트 전용 feature의 페이지에서 돈다. tests/e2e와 tests/visual의 브라우저 수준 검사는 홈 페이지, 플랫폼 개요, 갤러리 story를 쓴다. feature가 있어야 하는 검사(tests/e2e/generated-feature.spec.ts, chunk 복구 spec)는 create:feature가 쓰는 feature를 넣은 repo 복사본을 만든다(scripts/lib/generated-feature.ts).

소유 선언

scripts/generate-product-feature-index.ts가 feature, context, app을 찾아낸다. 각 경계는 자기 부모만 선언한다. 선언은 생성기가 읽는, export된 문자열 리터럴이나 정수 리터럴이다.

파일 export
src/apps/<app>/app-module.ts APP_MODULE_ID, APP_MAX_CONTEXTS
src/contexts/<context>/context-module.ts CONTEXT_MODULE_ID, CONTEXT_APP_ID, CONTEXT_ROUTE_PATH, CONTEXT_MAX_FEATURES
src/features/<feature>/feature-module.ts FEATURE_MODULE_ID, FEATURE_CONTEXT_ID, FEATURE_MODULE
src/features/<feature>/feature-runtime.ts FEATURE_RUNTIME (feature-module.ts만 동적으로 import한다)
src/features/<feature>/context-routes.ts FEATURE_CONTEXT_ROUTES
src/contexts/<context>/context-layout.tsx (선택) CONTEXT_LAYOUT, 그 context 고유의 레이아웃("제품 홈과 레이아웃")

생성기는 src/.generated/(git이 무시한다)에 세 가지를 쓴다. 설치 카탈로그가 import하는 feature 색인, router가 지연 로드하는 context 색인, 선택된 app이다. 모든 빌드·검사 script가 생성기를 먼저 돌린다. 직접 돌리려면 corepack pnpm generate:feature-index를 쓴다. 다음 경우에 생성기는 해당 파일 이름을 대며 실패한다.

  • src/features/ 아래 디렉터리에 feature-module.ts가 없을 때. feature가 아닌 코드 (테스트가 조립하는 IndexedDB 소비자, tests/fixtures/indexeddb-consumer)는 src/features/ 밖에 둔다.
  • feature가 선언되지 않은 context를 가리키거나, context가 선언되지 않은 app을 가리킬 때.
  • context나 app이 선언한 budget을 넘을 때.
  • VITE_PRODUCT_FEATURES가 app이 선언하지 않은 feature를 가리킬 때. 이 변수는 무엇이든 컴파일하기 전에, 여기서 설치할 feature 집합을 줄인다.

feature 추가

  1. src/features/<feature>/feature-module.ts를 만든다. defineFeatureModule (src/features/feature-module.ts)로 FEATURE_MODULE을 만든다. 이 파일은 feature의 선언이고 초기 chunk에 들어간다. 그래서 데이터만 담는다. 담는 것은 셋이다. 첫째, 선언 계약이다(라우트, 라우트 runtime 계약, 무효화(invalidation), topic 버전, 부팅 때 release manifest와 맞춰 보는 외부 contractPackages). 둘째, message 카탈로그다. 셋째, feature-runtime.ts를 동적으로 import하는 loadRuntime이다. create:feature가 완성된 파일을 써 준다.
  2. defineFeatureRuntime으로 src/features/<feature>/feature-runtime.ts를 만든다. 담는 것은 셋이다. schemas(feature의 라우트 schema와 API schema에 대한 FE-REG-SCHEMA 행), adapter contribution(defineFeatureAdapterContribution. needs에 받을 플랫폼 capability를 적는다), contract contribution(HTTP operation)이다. feature의 라우트 하나에 들어갈 때 router가 이 파일을 불러온다(application.features.load). 어디에서도 이 파일을 정적으로 import하지 않는다. 그러면 feature마다 실행 코드 전체가 다시 초기 chunk에 들어간다. 대략 gzip 3.9 KB다 (tests/unit/feature-shape-growth.test.ts는 feature 하나의 상한을 1 KiB로 둔다). HTTP API는 contract contribution descriptor로 한 번만 쓴다. 이 descriptor가 실제로 실행된다. 그리고 여기서 뽑아낸 FE-REG-API 행을 check:registries가 관리한다 (src/contracts/api-operations.ts의 projectApiOperationRows). 제품 feature의 contract contribution은 EXTERNAL_PACKAGE source를 쓴다. TEMPLATE_FIXTURE는 템플릿의 참조 샘플이 쓰던 source다. 이 source는 release 계약 집합에 절대 들어가지 않는다. composer는 어느 제품 feature에서든 이 source를 거부한다.
  3. FEATURE_CONTEXT_ROUTES를 export하는 src/features/<feature>/context-routes.ts를 만든다. 페이지 컴포넌트는 여기서 지연 import한다. 각 route handle은 그 라우트의 params/search codecs를 갖는다. 소유 context는 자기 route root에 들어갈 때만 이 파일을 불러온다 (예: create:feature <id> --with-create로 만든 feature의 context-routes.ts). 각 handle의 routeId는 같은 context에 있는 feature 계약의 라우트여야 한다. 아니면 context가 라우트를 불러올 때 거부하고, 라우트·context·feature 이름을 댄다 (src/contexts/bounded-context-module.ts).
  4. FEATURE_CONTEXT_ID에 소유 context를 적는다. 있는 context를 쓰거나, app이 소유하는 src/contexts/<context>/context-module.ts를 더한다. feature 계약의 라우트 경로는 모두 그 context의 CONTEXT_ROUTE_PATH이거나 그 아래여야 한다. 또 다른 context의 같은 root나 더 구체적인 root 아래에 들어가면 안 된다. router는 feature 라우트를 소유 context 안에서만 렌더링하기 때문이다. 플랫폼 라우트가 그 경로에 응답해서도 안 된다. router는 AppShell의 플랫폼 라우트를 먼저 시도한다. 그래서 다음 경로에서는 feature가 렌더링되지 않는다. 플랫폼 라우트와 같은 경로, APP_HOME이 아닌 id로 쓴 /, 레이아웃 없는 * root(찾을 수 없음 라우트가 모든 URL을 가져간다)다. 이 규칙을 어긴 라우트는 app 모듈이 불러올 때 거부하고, 라우트·feature·context 이름을 댄다 (src/apps/deployable-app-module.ts). 플랫폼 홈을 넘겨받는 라우트는 예외다 ("제품 홈과 레이아웃").
  5. feature에 application 입력이 있으면 feature 쪽에서 ApplicationFeatureInputs를 확장(augment)한다(IndexedDB 소비자 fixture가 tests/fixtures/indexeddb-consumer/application/local-draft-api.ts에서 이렇게 한다).
  6. corepack pnpm check:architecture, corepack pnpm check:types, corepack pnpm check:registries와 테스트를 돌린다. tests/unit/two-feature-install-typecheck.test.ts는 feature가 둘 이상일 때도 설치 카탈로그가 컴파일되는지 지킨다.
  7. corepack pnpm test:sample-removal -- --feature=<feature id>를 돌린다. 이 feature를 빼도 제품이 빌드되고 gate를 통과하는지 확인한다.

feature 디렉터리 밖 파일은 아래 표에 있다. feature에 필요한 나머지는 모두 src/features/<feature>/와 tests/features/<feature>/ 안에 있다.

파일 언제 없으면 실패하는 것
src/.generated/* 손으로 고치지 않는다. 모든 빌드·검사 script가 다시 만든다 —
public/release-manifest.json (추적 파일, dev server의 manifest) feature를 더하거나 뺄 때마다. create:feature가 다시 쓴다(node scripts/write-dev-release-manifest.ts). feature와 같은 커밋에 넣는다. 두 feature 브랜치가 모두 이 파일의 setDigest 줄을 바꾼다. 병합 충돌이 나면 아무 쪽이나 고르고 명령을 다시 돌린다(1105/16-01) test:unit(tests/unit/dev-release-manifest.test.ts)이 실패하며 이 명령을 알려 준다. dev server가 부팅하지 못한다(CONTRACT_SET_PACKAGE_MISSING)
config/scale/feature-shape-ceilings.json initialJavascript (추적 파일) feature를 더하거나 뺄 때마다, 그리고 초기 JavaScript를 바꾸는 템플릿 변경마다: node scripts/scale/measure-feature-shape-growth.ts --initial-baseline --write. 그 변경과 같은 커밋에 넣는다. 병합 충돌이 나면 명령을 다시 돌린다 test:unit(feature-shape growth 테스트가 이 값을 빌드 결과와 비교한다)
src/contexts/<context>/context-module.ts feature에 새 context가 필요할 때 generate:feature-index: Feature <id> belongs to undeclared context <context>
src/contexts/<context>/context-layout.tsx context에 AppShell 대신 자기 틀이 필요할 때(아래 "제품 홈과 레이아웃" 참고) 없음. 파일이 없으면 context는 AppShell 안에서 렌더링된다
docs/accessibility/route-reviews/<ROUTE_ID>.md feature가 더하는 라우트마다. 기록 하나를 복사해 Status: pending-manual-review로 되돌린다 test:unit(tests/unit/manual-a11y-evidence.test.ts), verify:documentation(route ID를 댄다), FE-GATE-009(review:a11y-manual -- --format-only). release 때는 FE-GATE-028이 서명된 검토를 요구한다
tests/e2e/accessibility.spec.ts feature마다 고치지 않는다(1103/16-03). 이 파일은 모든 경로 파라미터를 한 값으로 채우고, 각 API 요청에 설치된 descriptor로 응답한다. 목록 읽기에는 responseEnvelope 틀에 담은 빈 목록으로 응답한다. 보호된 페이지가 렌더링 전에 설치된 GET이 아닌 요청을 보낼 때만 고친다 test:a11y(FE-GATE-009): 설치된 GET 어디에도 선언되지 않은 요청이 오면 그 라우트가 실패한다. 목록만 읽은 페이지에 경고 상자(role="alert")가 떠도 실패한다
src/features/product-capabilities.ts (제품 소유) needs가 템플릿이 만들지 않는 capability를 가리킬 때: ProductFeaturePlatformCapabilities에 그 타입을 적는다. FeaturePlatformCapabilities가 이를 확장하므로 app, scripts, tests의 타입 검사 프로그램이 모두 그 키를 본다(product-composition.ts 안에 둔 augmentation은 scripts의 프로그램이 보지 못한다) check:types: feature에서 Type '"<capability>"' is not assignable to type 'keyof FeaturePlatformCapabilities'
src/bootstrap/product-composition.ts (제품 소유) needs가 템플릿이 만들지 않는 capability를 가리킬 때: 여기서 그 capability를 돌려준다. 타입은 product-capabilities.ts에 적는다. indexedDb는 recipes/frontend-capabilities/indexeddb-feature-capability.ts처럼 만든다. 제품 인증 프로필의 자격 증명도 여기서 돌려준다. 세션을 직접 소유하는 제품(BFF의 httpOnly 쿠키)은 부팅 전에 host 전역에 세션 owner를 설치하지 않는다. 대신 composeProductSessionOwner에서 돌려준다 check:types. 실행 중에는 feature <id> needs <capability>, which the host did not provide. 세션 owner가 없으면 AUTH_MODE: "external"은 세션이 integration-failed인 채로 부팅한다
src/contracts/product-contracts.ts (제품 소유) 제품 인증 프로필, 또는 제품 runtime 설정 키와 그 FE-REG-ENV 행(PRODUCT_ENV_REGISTRY) 인증 프로필: 그 operation을 불러오는 모든 gate가 Installed contract contribution is not composable: <featureId>/<operationId>: unknown authProfileId <id>로 실패한다. 설정 키: 키를 읽는 곳에서 check:types가 실패한다. 키에는 .default()를 주거나 .optional()로 만든다. 템플릿 테스트는 tests/helpers/runtime-config.ts로 설정을 만들고, 이 helper는 제품의 기본값을 채운다. 그래서 기본값 없는 필수 키는 이 테스트를 실패시킨다. FE-REG-ENV 행: check:registries가 행의 필드를 검사한다. tests/unit/env-registry-coverage.test.ts(test:unit)는 키마다 행이 있고, 그 행에 schema의 required와 defaultValue가 적혀 있기를 요구한다
config/runtime/<profile>.json 선택: FEATURE_OVERRIDES 항목으로 feature를 끈다 없음
package.json, lockfile, config/security/dependency-change-evidence.json contract contribution이 생성된 @org-contracts/* 패키지를 운영 의존성(production dependency)으로 import할 때 generate:supply-chain(check:bundle 안에서 돈다): high-risk dependency missing review: add:<package>

중앙 카탈로그(src/features/installed-*.ts)와 registry governance 파일은 바뀌지 않는다. 거기 적힌 소비자 디렉터리는 모든 feature를 덮는 glob이다 (src/features/*/adapters, config/contracts/registry-governance.json). 라우트의 params/search schema id는 feature가 등록한 schema와 맞춰 본다. loadingSurface는 kebab-case 이름이기만 하면 된다. 그래서 자기 schema와 loading surface를 가진 라우트도 governance를 고칠 필요가 없다. registry baseline도 바뀌지 않는다. 새 라우트, API operation, schema, 무효화 topic, namespace, edge는 registry에 더하기만 하는 변경이다. update:registry-baseline이나 breaking 증거는 행이나 그래프 항목을 지우거나 바꿀 때만 필요하다. tests/unit/second-api-feature-registries.test.ts는 이런 feature(API operation 하나, 자기 search schema와 loading surface를 가진 라우트 하나, 무효화 topic 하나)를 repo 복사본에 더하고 check:registries를 돌린다.

schema, operation, mapper, 라우트, chunk의 id와 무효화 topic은 전역이다. 앞에 feature 이름을 붙인다. create:feature는 <Pascal>NoRequest를 쓴다. 맨 NoRequest를 쓰면 feature끼리 이름이 겹친다. feature 자기 operation의 MSW 시나리오는 feature의 설치된 계약을 넣은 createHttpScenarioHandler(tests/mocks/handlers/http-scenarios.ts)로 만든다. 공유 시나리오 카탈로그는 바뀌지 않는다.

제품 홈과 레이아웃

홈이 feature 화면인 제품이나, 화면이 AppShell이 아닌 다른 틀을 쓰는 제품은 그것을 선언한다. router와 카탈로그는 바뀌지 않는다.

  • 홈. feature는 계약에 id가 APP_HOME인 라우트를 선언해 플랫폼 홈을 넘겨받는다. feature가 넘겨받을 수 있는 라우트는 플랫폼이 정한다 (src/contracts/routes.ts의 FEATURE_REPLACEABLE_PLATFORM_ROUTE_IDS). 그 밖의 플랫폼 route id를 쓰면 여전히 중복이다. 두 feature가 APP_HOME을 선언하면 카탈로그를 불러올 때 둘의 이름을 대며 실패한다. router는 소유 context의 route root가 무엇이든, 그 라우트를 소유 context와 함께 자기 경로에 마운트한다. 빌드에서 feature를 빼면(VITE_PRODUCT_FEATURES) 플랫폼 홈이 돌아온다. 실행 중에 feature를 끄면 그 경로에 비활성 feature 페이지가 뜬다.
  • 레이아웃. CONTEXT_LAYOUT(컴포넌트)을 export하는 src/contexts/<context>/context-layout.tsx가 있는 context는 AppShell 대신 그 레이아웃 아래에서 렌더링된다. 생성된 색인은 그 context의 라우트 하나에 들어갈 때 이 파일을 지연 로드한다. router는 context를 그 feature들이 등록한 경로마다 레이아웃 아래에 마운트한다. 그래서 모르는 URL은 여전히 AppShell 안의 찾을 수 없음 페이지로 간다. 레이아웃 파일이 같은 컴포넌트를 export하는 context끼리는, 사용자가 그 사이를 옮겨 다녀도 레이아웃 인스턴스 하나를 유지한다. 그래서 여러 route root가 레이아웃 하나를 함께 쓸 수 있다.
  • 접근성. 레이아웃은 #main-content로 가는 건너뛰기 링크를 렌더링한다. 그리고 <Outlet />을 감싸는 <main id="main-content" tabIndex={-1}>을 정확히 하나 렌더링한다. router는 라우트가 바뀔 때마다 포커스를 그곳으로 옮긴다. 레이아웃 라우트는 AppShell의 형제이고, 절대 그 안에 들어가지 않는다. tests/component/layout-landmarks.test.tsx는 AppShell과 설치된 모든 context의 레이아웃을 렌더링하고, 이 둘이 없는 레이아웃을 실패시킨다.
  • 실패. 배포로 사라진 레이아웃 chunk도 라우트 chunk처럼 한 번 새로고침해 복구한다. 라우트 경계와 feature 경계는 AppShell에서와 똑같이 동작한다.
  • 4단계의 route root 규칙은 모든 레이아웃에 걸쳐 적용된다. 두 context가 어떤 레이아웃을 갖든, root는 그 아래 URL을 가져간다.

tests/component/context-layouts.test.tsx는 이렇게 선언한 제품 (tests/helpers/fixture-layout-product.tsx)을 설치해 본다.

출시 전에

  • 프로젝트 전용 변형을 더하기 전에 의미 토큰(semantic token), UI primitive, 상태 화면을 먼저 쓴다.
  • component 동작 테스트, 모든 브라우저 엔진 E2E, 자동 axe 검사, 서명된 수동 라우트 증거를 더한다.

테마 선택은 공개된 COLOR_SCHEME 저장소 계약이다. 인증 토큰과 그 밖의 비밀 값은 계속 저장 금지 키다.