feat: establish TypeScript-aware frontend tooling

merge: frontend platform capability review
docs: audit frontend platform capabilities
2026-07-26 13:41:23 +09:00 · 2026-07-26 02:09:38 +09:00 · 2026-07-26 02:09:06 +09:00 · 2026-07-26 00:32:50 +09:00 · 2026-07-26 00:32:50 +09:00 · 2026-07-26 00:28:17 +09:00
95 changed files with 9997 additions and 216 deletions
@@ -45,5 +45,8 @@ module.exports = {
      exportsFields: ["exports"],
      conditionNames: ["import", "require", "node", "default"],
    },
+    tsConfig: {
+      fileName: "tsconfig.app.json",
+    },
  },
 };
@@ -53,9 +53,9 @@ jobs:
        run: |
          corepack enable
          corepack pnpm install --frozen-lockfile
-      - name: Install Chromium
+      - name: Install Playwright browsers
        if: ${{ matrix.browser }}
-        run: corepack pnpm exec playwright install --with-deps chromium
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
      - name: Run blocking gate
        run: corepack pnpm ci:gate -- ${{ matrix.gate }}
      - name: Upload gate evidence
@@ -91,9 +91,9 @@ jobs:
        run: |
          corepack enable
          corepack pnpm install --frozen-lockfile
-      - name: Install Chromium
+      - name: Install Playwright browsers
        if: ${{ matrix.browser }}
-        run: corepack pnpm exec playwright install --with-deps chromium
+        run: corepack pnpm exec playwright install --with-deps chromium firefox webkit
      - name: Run blocking gate
        run: corepack pnpm ci:gate -- ${{ matrix.gate }}
      - name: Upload gate evidence
@@ -6,7 +6,8 @@ operations are executable contracts rather than conventions.

 ## Start locally

-Requirements: Node 24 and Corepack. The repository pins pnpm in `package.json`.
+Requirements: Node 24.11 or newer and Corepack. The repository pins pnpm in
+`package.json`.

 ```bash
 corepack pnpm install --frozen-lockfile
@@ -16,6 +17,27 @@ corepack pnpm dev
 Runtime-public settings live in `public/config.json` and are validated before
 the product tree mounts. Client secrets are forbidden.

+## Included starter experience
+
+The default build mounts a domain-neutral application shell with a header,
+responsive sidebar, route focus management, session integration status, and a
+persistent `system` / `light` / `dark` theme selector.
+
+| Route | Purpose |
+| --- | --- |
+| `/` | implementation readiness and starter links |
+| `/examples/ui` | buttons, fields, cards, alerts, badges, modal, and tokens |
+| `/examples/states` | loading, refresh, empty, error, auth, forbidden, and not-found states |
+| `/examples/auth` | reactive external-auth integration seam |
+| `/sample/resources` | protected, domain-neutral integration route |
+
+`AUTH_MODE=demo` is credential-free and accepted only in local/development
+environments. Deployments use `AUTH_MODE=external` and provide the opaque auth
+owner described in
+[`docs/architecture/starter-experience.md`](docs/architecture/starter-experience.md).
+The client route policy is user experience only; server authorization remains
+authoritative.
+
 ## Architecture

 Dependencies point inward:
@@ -27,9 +49,30 @@ bootstrap composes concrete adapters
 contracts own cross-cutting registries
 ```

-See `docs/architecture/overview.md` and `docs/architecture/layers.md`. The
-removable sample slice is under `src/sample/contract-fixture`; product code is
-not allowed to import it.
+See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and
+`docs/architecture/starter-experience.md`. The removable sample slice is under
+`src/sample/contract-fixture`; product code is not allowed to import it. The
+visible starter routes do not depend on that fixture and continue to build
+after it is removed.
+
+### Platform capability review
+
+The starter shell is implemented, but the repository review also records the
+remaining work required before feature teams can use every declared contract
+through one end-to-end application path:
+
+- [platform capability review](docs/architecture/frontend-platform-capability-review.md)
+- [ports, adapters, and feature boundaries](docs/architecture/frontend-ports-adapters-and-boundaries.md)
+- [TypeScript, state ownership, and data flow](docs/architecture/typescript-state-and-data-flow.md)
+- [routing, page templates, and reusable patterns](docs/architecture/routing-pages-and-patterns.md)
+- [design-system platform](docs/styling/design-system-platform.md)
+- [frontend platform testing strategy](docs/testing/frontend-platform-testing-strategy.md)
+- [implementation roadmap](docs/architecture/frontend-platform-implementation-roadmap.md)
+
+These documents distinguish repository defaults from opt-in adapters and
+project-owned integrations. They are target designs and review findings; a
+capability is not treated as implemented until its branch acceptance criteria
+and executable gates pass.

 ## Verification

@@ -38,6 +81,9 @@ Common local checks:
 ```bash
 corepack pnpm lint
 corepack pnpm check:types
+corepack pnpm check:types:app
+corepack pnpm check:types:node
+corepack pnpm check:types:test
 corepack pnpm check:architecture
 corepack pnpm test:all
 corepack pnpm test:e2e
@@ -52,9 +98,24 @@ corepack pnpm drill:runbooks
 corepack pnpm check:ci
 ```

+`check:types`는 source, Node scripts/config와 tests를 분리된 TypeScript
+project로 모두 검사한다. type/architecture/security/registry의 invalid
+fixture는 `config/ci/gates.json`에서 “실패해야 통과”하는 negative gate로
+실행된다. 도구 호환성 결정은
+[VD-01](docs/architecture/decisions/VD-01-typescript-lint-tooling.md)에 기록돼
+있다.
+
+Install the pinned Playwright browser engines before the first cross-browser
+run:
+
+```bash
+corepack pnpm exec playwright install --with-deps chromium firefox webkit
+```
+
 Two gates intentionally need external evidence:

- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review.
+- `review:a11y-manual` needs a signed human keyboard/focus/screen-reader review
+  for all six registered routes.
 - `collect:web-vitals-evidence` stays `FAIL_UNVERIFIED` until a reviewed minimum
  eligible-sample threshold and 28 days of production data exist.

@@ -0,0 +1,18 @@
+# EXAMPLES_AUTH accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_AUTH
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review session state announcements and unavailable external-integration behavior.
@@ -0,0 +1,18 @@
+# EXAMPLES_STATES accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_STATES
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review loading, refresh, empty, error, authentication, forbidden, and not-found announcements.
@@ -0,0 +1,18 @@
+# EXAMPLES_UI accessibility review
+
+Status: pending-manual-review
+Route ID: EXAMPLES_UI
+Release ID:
+Reviewer:
+Reviewed at:
+Signature:
+Attestation: pending
+M1 Keyboard: pending
+M2 Visible focus: pending
+M3 Route focus: pending
+M4 Modal focus: pending
+M5 Error association: pending
+M6 Color signal: pending
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Review the text-field error association and modal focus containment/restoration.
@@ -74,7 +74,9 @@
      "name": "typecheck",
      "steps": [
        { "script": "check:types", "expect": "pass" },
-        { "script": "check:types:fixture", "expect": "fail" }
+        { "script": "check:types:fixture", "expect": "fail" },
+        { "script": "check:types:fixture:ts-port", "expect": "fail" },
+        { "script": "check:types:fixture:ts-result", "expect": "fail" }
      ],
      "logPath": "artifacts/quality/check-types.txt",
      "evidence": ["artifacts/quality/check-types.txt"],
@@ -125,6 +127,9 @@
      "evidence": [
        "artifacts/tests/a11y.json",
        "artifacts/tests/a11y-manual/APP_HOME.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_UI.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_STATES.md",
+        "artifacts/tests/a11y-manual/EXAMPLES_AUTH.md",
        "artifacts/tests/a11y-manual/SAMPLE_RESOURCE_LIST.md",
        "artifacts/tests/a11y-manual/NOT_FOUND.md",
        "artifacts/tests/a11y-manual/report.json"
@@ -133,9 +138,17 @@
    },
    "FE-GATE-010": {
      "name": "architecture",
-      "steps": [{ "script": "check:architecture", "expect": "pass" }],
+      "steps": [
+        { "script": "check:architecture", "expect": "pass" },
+        { "script": "check:registries", "expect": "pass" },
+        { "script": "check:registries:fixture", "expect": "fail" }
+      ],
      "logPath": "artifacts/quality/gates/FE-GATE-010.txt",
-      "evidence": ["artifacts/quality/dependency-report.json"],
+      "evidence": [
+        "artifacts/quality/dependency-report.json",
+        "artifacts/quality/registries.json",
+        "artifacts/quality/registry-fixture.json"
+      ],
      "retentionClass": "merge-cycle"
    },
    "FE-GATE-011": {
@@ -1,10 +1,12 @@
 # Manual accessibility review checklist

 Automated axe checks do not establish WCAG conformance. A human reviewer must
-review all three route records in `artifacts/tests/a11y-manual/` against one
-release candidate and sign them. Copy the template fields exactly; the gate
-rejects blank identity/timestamp/signature fields, pending verdicts, mismatched
-release IDs, or missing routes.
+review all six route records in `artifacts/tests/a11y-manual/` against one
+release candidate and sign them. The required scope is derived from the route
+registry: `APP_HOME`, `EXAMPLES_UI`, `EXAMPLES_STATES`, `EXAMPLES_AUTH`,
+`SAMPLE_RESOURCE_LIST`, and `NOT_FOUND`. Copy the template fields exactly; the
+gate rejects blank identity/timestamp/signature fields, pending verdicts,
+mismatched release IDs, or missing routes.

 Allowed item verdicts:

@@ -43,5 +45,7 @@ The reviewer must verify:
 - M7: non-essential motion is suppressed with reduced-motion preference
 - Screen reader: headings, live regions, errors, and actions are announced once

-Passing automated evidence means only that tested pages had no critical or
-serious axe findings under the recorded browser run.
+`EXAMPLES_UI` requires real M4 modal and M5 field-error review; those items must
+not be marked not-applicable on that route. Passing automated evidence means
+only that tested pages had no critical or serious axe findings under the
+recorded Chromium, Firefox, and WebKit runs.
@@ -0,0 +1,54 @@
+# VD-01: TypeScript 7과 ESLint 10의 점진적 전환 도구
+
+- 상태: Accepted
+- 결정일: 2026-07-26
+- 적용 브랜치: `feature-frontend-typescript-tooling-foundation`
+
+## 배경
+
+저장소는 TypeScript `7.0.2`와 ESLint `10.8.0`을 고정하고 있다. 첫 전환
+브랜치는 compiler를 변경하거나 production source를 일괄 변환하지 않고
+JS/JSX/TS/TSX가 같은 품질 게이트를 통과하게 해야 한다.
+
+결정 시점의 package peer contract는 다음과 같다.
+
+- `typescript-eslint@8.65.0`과 canary는 TypeScript `<6.1.0`을 요구한다.
+- `eslint-plugin-jsx-a11y@6.10.2`는 ESLint `<=9`를 요구한다.
+- `eslint-plugin-react-hooks@7.1.1`은 ESLint 10을 지원한다.
+- Babel 8 ESLint parser는 ESLint 10을 지원하고 Node `>=24.11.0`을 요구한다.
+
+호환되지 않는 peer dependency를 강제 설치하면 lockfile 검증은 통과하더라도
+지원되지 않는 parser와 rule 조합을 플랫폼 계약으로 만들게 된다.
+
+## 결정
+
+1. TypeScript `7.0.2`와 ESLint `10.8.0`을 유지한다.
+2. TypeScript/TSX의 ESLint syntax parsing에는
+   `@babel/eslint-parser`와 TypeScript/JSX syntax plugin을 사용한다.
+3. TypeScript의 이름 해석, unused 진단과 type semantics는 `tsc`가 소유한다.
+   Babel parser가 TypeScript scope manager를 제공하지 않으므로 TS 파일의
+   core `no-undef`와 `no-unused-vars`는 끄고 분리된 app/node/test TypeScript
+   project를 필수 게이트로 실행한다.
+4. React Hook 규칙은 호환되는 `eslint-plugin-react-hooks`로 즉시 적용한다.
+5. JSX 접근성은 현재의 semantic component contract, Testing Library,
+   axe 기반 cross-browser gate와 수동 검토 계약이 계속 담당한다. 호환되지 않는
+   `eslint-plugin-jsx-a11y`는 설치하지 않는다.
+6. Babel 8의 지원 범위에 맞춰 Node engine 하한을 `24.11.0`으로 명시한다.
+7. production source의 대량 rename은 이 결정에 포함하지 않는다.
+
+## 검증
+
+- `check:types`는 app, Node scripts/config, tests project를 모두 검사한다.
+- JS invalid-call, TS invalid port, TS discriminated-union fixture는 실패해야 한다.
+- ESLint와 dependency-cruiser는 TS/TSX architecture fixture를 검사한다.
+- registry scanner는 TS registry의 required field, uniqueness와 reference를
+  검증한다.
+- browser security gate는 TSX의 금지된 raw HTML fixture를 거절한다.
+
+## 후속 검토와 제거
+
+`typescript-eslint`가 TypeScript 7을, JSX 접근성 plugin이 ESLint 10을 공식
+지원하면 별도 dependency 브랜치에서 peer metadata와 전체 negative fixture를
+재검증한다. 교체할 때는 Babel parser package와 TS 전용 ESLint override를
+함께 제거한다. compiler downgrade나 `--force` 설치는 이 ADR의 rollback
+방법이 아니다.
@@ -0,0 +1,447 @@
+# 프론트엔드 플랫폼 역량 재검토
+
+## 1. 문서 목적
+
+이 문서는 도메인 기능과 실제 운영 환경의 배포 증적을 제외하고, 이 저장소가 새
+프론트엔드 제품의 출발점으로 제공해야 하는 공통 역량을 다시 평가한다. 평가
+기준은 다음과 같다.
+
+- 코드나 설정 파일이 존재하는지만 보지 않는다.
+- 부트스트랩부터 화면까지 실제 호출 경로가 연결되는지 확인한다.
+- 선언한 레지스트리와 정책이 런타임 및 CI에서 집행되는지 확인한다.
+- 기본 번들에 포함할 역량과 필요할 때 설치할 확장 역량을 구분한다.
+- 특정 벤더를 채택하더라도 제품 코드가 벤더 API에 직접 결합되지 않는지 확인한다.
+
+검토 기준 브랜치는 `develop`, 기준 커밋은 `cb195f8`이다. 이후 구현으로 경로나
+세부 내용이 달라질 수 있으므로, 각 항목은 문서의 경로뿐 아니라 해당 테스트와
+아키텍처 게이트로 계속 검증해야 한다.
+
+## 2. 결론
+
+현재 저장소는 다음 기반이 강하다.
+
+- 런타임 설정과 릴리스 매니페스트 검증
+- 도메인, 애플리케이션, 프레젠테이션, outbound adapter의 의존 방향
+- 공통 HTTP 실패 형태와 제한된 retry 정책
+- 앱 셸, 반응형 내비게이션, 테마, 비동기 상태 표면
+- Vitest, Testing Library, MSW, Playwright, axe를 이용한 테스트 계층
+- CI 게이트 taxonomy와 호환성·보안·성능·릴리스 계약 문서
+
+그러나 “도메인 기능을 바로 추가할 수 있는 프론트엔드 플랫폼” 기준으로는 아직
+중요한 연결부가 빠져 있다. 가장 큰 문제는 공통 기능이 없다는 것보다 이미 있는
+기능이 실제 기능 화면의 표준 호출 경로로 조립되지 않았다는 점이다.
+
+특히 다음은 선행 해결이 필요하다.
+
+1. React 화면이 호출할 application input API와 런타임 주입 경계
+2. TanStack Query를 사용하는 표준 query/mutation inbound adapter
+3. TypeScript 전환 전에 TS 파일까지 검사하도록 만드는 도구 안전망
+4. path/query/body projection과 runtime timeout/retry가 정확히 연결된 HTTP 계층
+5. 선언과 실행이 일치하는 typed route 계약
+6. 전체를 제거할 수 있는 실제 reference feature
+7. 폼, 페이지 템플릿, 확장된 디자인 시스템과 컴포넌트 워크벤치
+
+따라서 현재 상태를 “프론트 공통부가 모두 구현됐다”고 표현하면 범위가 과장된다.
+더 정확한 표현은 다음과 같다.
+
+> 운영·안전 계약과 범용 앱 셸은 갖춰졌지만, 기능 개발자가 사용하는 application
+> API, 서버 상태, 폼, 라우팅, 페이지 패턴의 표준 수직 경로는 아직 보강이
+> 필요하다.
+
+## 3. 판정 기준
+
+| 판정 | 의미 |
+| --- | --- |
+| 준비됨 | 구현, 실제 조립, 자동 검증이 모두 존재한다. |
+| 부분 준비 | 핵심 구현은 있으나 실제 호출 경로, 정책 집행, 예제가 불완전하다. |
+| 미제공 | 새 기능을 만들 때 팀이 직접 선택·설계해야 한다. |
+| 프로젝트 선택 | 기본 번들에 강제하면 비용이 더 크며, 경계와 recipe만 제공한다. |
+
+## 4. 역량 매트릭스
+
+| 영역 | 현재 판정 | 근거 | 필요한 다음 상태 |
+| --- | --- | --- | --- |
+| 부트·런타임 설정 | 준비됨 | `src/bootstrap`, runtime schema, release 검사 | 현 상태 유지, TS 전환 시 동일 게이트 유지 |
+| 계층 의존 방향 | 부분 준비 | `.dependency-cruiser.cjs`, `src/application/ports` | inbound/outbound 명명과 `contracts` 소유권까지 집행 |
+| application facade | 부분 준비 | `create-application.js`는 있으나 `main.jsx`에서 우회 | UI에는 input API만 주입 |
+| HTTP client | 부분 준비 | timeout, abort, retry, auth, envelope, Zod가 존재 | path/query, parsed body, runtime 설정, 정리 로직 보완 |
+| retry | 부분 준비 | safe/keyed 요청 정책 존재 | retry 소유자 단일화, 설정 연결, telemetry |
+| 오류 모델 | 부분 준비 | error registry와 normalization 존재 | typed discriminated union과 계층별 mapper |
+| 검증 | 부분 준비 | runtime/API Zod 존재 | route/form/domain 경계를 분리하고 실제 parse 결과 사용 |
+| 인증 연동 | 준비됨/프로젝트 선택 | opaque auth owner와 demo seam 존재 | 인증 방식별 recipe; 기본 token 저장소는 추가하지 않음 |
+| 서버 상태 | 미제공에 가까운 부분 준비 | QueryClientProvider와 cache port는 존재 | query/mutation hook과 화면 reference flow |
+| 클라이언트 상태 | 부분 준비 | local state, theme context, session external store | 상태 소유권 표와 typed external-store 예제 |
+| 범용 global store | 프로젝트 선택 | 별도 라이브러리 없음 | 필요 조건에 따라 Zustand/Redux Toolkit/state machine 선택 |
+| 라우팅 | 부분 준비 | lazy route, access hint, registry 존재 | typed runtime map, codec, recovery, metadata 집행 |
+| 앱 셸·반응형 | 부분 준비 | header/sidebar/content/theme 구현 | 접근 가능한 mobile drawer와 focus 복원 |
+| 페이지 템플릿 | 미제공 | 각 페이지가 직접 레이아웃 조립 | list/detail/form/status 등 슬롯 기반 템플릿 |
+| 디자인 토큰 | 부분 준비 | semantic color/theme 토큰 존재 | typography, spacing, motion, layer 등 3단계 토큰 |
+| 공통 UI | 부분 준비 | Button, TextField, Card, Alert, Badge, Dialog | form/navigation/overlay/data/layout primitives 확장 |
+| 아이콘 | 미제공 | 문자 기호를 직접 사용 | Lucide를 로컬 icon facade 뒤에서 사용 |
+| 폼 | 미제공 | 수동 문자열 검증 예제만 존재 | schema 기반 form facade와 422/dirty/pending 정책 |
+| 국제화 | 미제공 | 한국어 문자열·locale이 하드코딩 | typed message/formatter/locale/RTL 경계 |
+| logging/diagnostics | 미제공 | telemetry port는 있으나 logger 없음 | redaction이 적용된 diagnostics/logging 경계 |
+| telemetry | 부분 준비 | registry, queue, redaction 존재 | HTTP·boot·cache·storage·route 사건에 실제 연결 |
+| 비동기 상태 불변식 | 부분 준비 | 공통 model/surface는 있으나 일부 모순 상태를 허용 | query/mutation 상태 조합과 action latch를 닫음 |
+| 단위·통합·E2E | 준비됨 | Vitest, RTL, MSW, Playwright 3엔진 | TS 테스트 검사, 실제 bootstrap 통합, 위험 시나리오 보강 |
+| UI 회귀 검증 | 미제공 | axe/reflow는 있으나 visual baseline 없음 | Storybook 또는 동급 workshop과 시각 회귀 |
+| 샘플 제거 | 부분 준비 | fixture 제거 테스트 존재 | sample domain/registry/runtime 전체 제거 검증 |
+| registry·compatibility 집행 | 부분 준비 | registry와 gate는 있으나 실제 before/after 및 orphan 검사가 제한적 | type/reference/orphan/diff/migration을 자동 검증 |
+| 공급망 검사 | 부분 준비 | lockfile·문서·gate는 있으나 실제 transitive 취약점/license/SBOM 깊이가 부족 | pinned scanner와 policy exception/증적 연결 |
+| realtime·offline·file 등 | 프로젝트 선택 | 현재 없음 | port/adapter recipe와 선택 기준 제공 |
+
+## 5. 우선순위별 발견 사항
+
+### 5.1 P0: 기능 개발을 막는 항목
+
+#### application 계층이 런타임에서 우회된다
+
+`src/bootstrap/composition-root.js`는 application을 생성하지만
+`src/bootstrap/main.jsx`는 이를 라우터에 주입하지 않는다. UI에는 auth, storage,
+telemetry 같은 raw outbound dependency와 concrete QueryClient가 전달된다.
+`src/application/create-application.js`도 use case 중심 input API보다 outbound
+capability를 다시 노출하는 형태다.
+
+목표 상태:
+
+- `Application`은 UI가 호출할 query/command use case를 제공한다.
+- `ApplicationProvider`는 이 API만 React tree에 제공한다.
+- 페이지는 HTTP, storage, auth SDK, telemetry sink를 직접 호출하지 않는다.
+- bootstrap만 concrete outbound adapter를 알고 조합한다.
+- 실제 bootstrap부터 reference page까지 연결한 통합 테스트가 있다.
+
+#### 서버 상태 라이브러리는 마운트됐지만 사용할 수 없다
+
+`QueryClientProvider`는 존재하지만 저장소의 제품 코드에서 `useQuery`와
+`useMutation`을 사용하지 않는다. 동시에 presentation의 `@tanstack/**` import는
+금지돼 있다. 현재 `QueryCachePort`는 명령형 read/write/invalidate만 제공하여
+React 구독, 요청 상태, cancellation, optimistic update를 대신할 수 없다.
+
+목표 상태:
+
+- canonical target인 `src/adapters/inbound/react/platform/query`에 벤더 연동을
+  한정한다. 마이그레이션 중에는 기존 `presentation`을 같은 inbound 경계로
+  취급하되 새 대체 경로를 만들지 않는다.
+- `useApplicationQuery`, `useApplicationMutation` 또는 같은 역할의 typed
+  controller hook을 제공한다.
+- HTTP retry와 query retry 중 한 계층만 재시도 책임을 갖는다.
+- loading, empty, refreshing, stale, offline, error, conflict, optimistic rollback을
+  reference feature에서 보여 준다.
+
+#### TypeScript 전환 전에 검사 도구가 TS를 인식해야 한다
+
+현재 source는 모두 JS/JSX이고 `strict + allowJs + checkJs`를 사용한다. 이는 좋은
+중간 안전망이지만 다음 도구는 TS migration을 그대로 따라가지 못한다.
+
+- ESLint의 계층·보안 glob은 JS/JSX 중심이다.
+- registry scanner는 `.ts`와 `.tsx`를 찾지 않는다.
+- registry governance 경로가 `.js` 확장자로 고정되어 있다.
+- tests는 현재 `tsconfig.json` 검사 범위에서 빠진다.
+
+따라서 파일 확장자를 먼저 바꾸면 새 TS 코드가 일부 자동 검사에서 빠질 수 있다.
+TypeScript 전환은
+[TypeScript의 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
+처럼 점진적으로 진행하되, 이 저장소에서는 tooling glob과 CI를 먼저 고쳐야 한다.
+
+#### HTTP 계약에 선언과 실행의 차이가 있다
+
+현재 HTTP 계층은 공통화 수준이 높지만 다음 정확성 문제가 남아 있다.
+
+- runtime config의 `REQUEST_TIMEOUT_MS`, `MAX_RETRY_ATTEMPTS`가 client 생성에
+  전달되지 않는다.
+- operation path에 path parameter와 search parameter를 투영하는 표준 builder가
+  없다.
+- sample filter는 cache key에만 반영되고 실제 요청 URL에는 반영되지 않는다.
+- Zod의 parsed/transformed request body 대신 원본 body를 전송한다.
+- request validation의 조기 반환 경로에서 timeout/listener 정리가 늦어진다.
+- HTTP failure, retry, recovery가 telemetry 사건과 이어지지 않는다.
+
+client를 거대한 범용 함수로 계속 확장하지 말고 transport, request builder, auth,
+timeout, retry, decoder, mapper 책임을 분리해야 한다. application에는 범용 HTTP
+메서드보다 feature가 요구하는 gateway interface를 노출한다.
+
+#### route registry가 실행 계약이 아니다
+
+route registry에는 `paramsSchema`, `searchSchema`, `loadingSurface`,
+`errorSurface`, `chunkId`가 있지만 실제 router tree, lazy module, navigation
+목록은 별도로 작성된다. 여러 필드는 선언만 되고 런타임에 사용되지 않는다.
+chunk recovery use case와 redirect loop guard도 실제 route flow에 연결되지 않는다.
+
+목표 상태:
+
+- serializable contract와 executable runtime map을 분리한다.
+- `satisfies Record<RouteId, RouteRuntime>`로 양방향 완전성을 검사한다.
+- params/search는 Zod codec으로 경계에서 parse하고 URL builder도 같은 codec을
+  사용한다.
+- loading/error/chunk/access/title/navigation metadata를 실제 route object에
+  연결한다.
+- route change 시 boundary reset, focus, scroll, navigation cancellation을
+  검증한다.
+
+#### reference feature가 완전히 제거되지 않는다
+
+현재 sample removal gate는 `src/sample/contract-fixture`만 삭제한다. sample API
+operation, schema, mapper, domain model, query key는 다른 production 경로에 남는다.
+반면 화면에 노출된 `/sample/resources`는 실제 query 수직 흐름을 실행하지 않는다.
+
+reference feature는 domain, application input/output, schemas, operation,
+mapper, query controller, pages, tests를 한 소유 경계 아래 모아야 한다. 해당 모듈과
+registry contribution을 제거한 뒤 typecheck, architecture, test, build가 모두
+통과해야 “제거 가능”으로 판정한다.
+
+#### 비동기·복구 상태의 불변식이 닫혀 있지 않다
+
+공통 async model과 gallery가 있지만 선언 가능한 상태 조합 중 일부는 사용자
+행동과 모순될 수 있다. stale data가 있는 degraded 상태와 refreshing, mutation
+pending과 conflict, retry button과 실제 handler 존재 여부를 typed state로
+닫아야 한다. 상태를 boolean 여러 개로 조합하지 않고 다음과 같은 discriminated
+state와 action capability로 표현한다.
+
+```text
+initial-loading
+ready
+refreshing-with-data
+empty
+degraded-with-data
+terminal-error
+mutation-pending
+mutation-conflict
+```
+
+chunk recovery와 release coherence도 policy 함수가 존재하는 것으로 완료되지
+않는다. 실제 lazy import failure가 manifest 재확인, build 비교, 단 한 번의 guarded
+reload, 반복 실패 지원 표면까지 이어지고 E2E로 검증되어야 한다.
+
+#### telemetry, registry, 공급망 gate의 실행 깊이가 부족하다
+
+telemetry registry에는 여러 사건이 있지만 실제 production producer는 제한적이다.
+boot, API attempt/final failure, auth recovery, storage/cache degradation, release/chunk
+recovery를 registry 사건에 연결해야 한다.
+
+registry/compatibility 검사는 다음까지 확장한다.
+
+- ID와 enum/type의 양방향 완전성
+- referenced schema/message/token의 존재
+- 실행 코드에서 소비되지 않는 orphan 항목
+- 기준 commit과 현재 commit 사이의 실제 contract diff
+- breaking change의 version/migration/rollback metadata
+
+공급망 검사는 단순 문자열 secret 탐지에 머물지 않고 transitive dependency,
+known vulnerability, license policy, SBOM/provenance를 pinned tool로 검사해야 한다.
+도구 장애와 취약점 발견을 구분하고, 예외에는 owner·사유·만료일을 요구한다.
+
+### 5.2 P1: 공통 플랫폼 기본 제공 항목
+
+- schema 기반 form facade와 field/error/pending/dirty/422 정책
+- standard, collection, detail, form, status page template
+- 접근 가능한 drawer, menu, popover, select 같은 interaction primitive
+- token → primitive → pattern → template로 이어지는 디자인 시스템
+- Lucide를 감싼 local icon registry와 `IconButton`
+- typed message key, locale provider, formatter, pseudo-locale/RTL smoke
+- redacted structured diagnostics/logger와 telemetry wiring
+- Storybook 또는 동급 isolated UI workshop
+- Playwright visual baseline, shared MSW scenarios, built-dist E2E
+- React Hooks, JSX accessibility, TanStack Query 관련 lint
+- source와 tests를 모두 포함하는 TypeScript project references
+- registry/compatibility의 실제 diff와 orphan reference 검사
+- transitive vulnerability, license, SBOM/provenance 공급망 gate
+
+### 5.3 P2: 경계와 recipe를 제공할 선택 항목
+
+다음 기능을 모든 앱의 초기 번들에 설치할 필요는 없다. 대신 port 또는 local
+vendor facade, 선택 조건, 실패 정책, 테스트 fixture를 문서로 제공한다.
+
+| capability | 대표 기술 | 기본 제공할 경계 | 실제 설치 조건 |
+| --- | --- | --- | --- |
+| realtime | WebSocket, SSE | subscribe/unsubscribe, reconnect, resume, heartbeat | 서버가 push event를 제공할 때 |
+| offline storage | IndexedDB | versioned repository, migration, quota failure | offline read/write가 제품 요구일 때 |
+| background/cache | Service Worker, PWA | cache ownership, update, rollback recipe | installable/offline 앱일 때 |
+| file transfer | presigned HTTP, multipart | progress, cancel, size/type validation | 업로드·대용량 다운로드가 있을 때 |
+| generated API | OpenAPI, GraphQL, gRPC-Web | generated client를 gateway 뒤에 감싸는 규칙 | 서버 계약 형식이 확정됐을 때 |
+| feature flag | local/remote flag provider | typed flag key, default, stale behavior | staged rollout가 필요할 때 |
+| worker | Web Worker | request/result/cancel protocol | UI thread를 막는 CPU 작업이 있을 때 |
+| multi-tab | BroadcastChannel | event versioning, source ID, conflict policy | 탭 간 동기화가 필요할 때 |
+| browser capability | clipboard, notification, media | permission/result port | 해당 UX가 있을 때 |
+| client workflow | Zustand, Redux Toolkit, state machine | state ownership decision과 local facade | cross-feature workflow가 실제로 생길 때 |
+| large data UI | virtualization, data grid | owned component facade | 데이터 규모가 측정 기준을 넘을 때 |
+| analytics/error sink | vendor SDK, OpenTelemetry | redaction, consent, sampling adapter | 운영 provider와 정책이 정해졌을 때 |
+
+서버의 Redis, MongoDB, PostgreSQL, MinIO를 브라우저가 직접 연결하는 구조는 기본
+frontend adapter catalog에 넣지 않는다. 브라우저는 권한 있는 backend API/BFF를
+통해 이 자원에 접근해야 한다. 프론트에서 대응되는 변화 지점은 데이터베이스
+vendor가 아니라 HTTP/GraphQL/gRPC-Web, realtime, file transfer, cache, storage,
+worker, browser capability 같은 프로토콜·런타임 capability다.
+
+### 성능 최적화는 모두 adapter 문제인가
+
+아니다. 먼저 측정하고 병목의 소유 계층에 맞는 수단을 적용한다.
+
+| 문제 | 기본 제공할 수단 | adapter/facade가 필요한 경우 |
+| --- | --- | --- |
+| 초기 JS가 큼 | route/feature lazy loading, bundle budget, dependency inventory | remote module이나 별도 delivery 전략이 있을 때 |
+| 중복 네트워크 | TanStack deduplication/cache, abort, bounded retry | offline cache나 generated client를 교체할 때 |
+| 느린 화면 전환 | prefetch policy, stable shell, cached-data surface | route별 prefetch provider가 필요할 때 |
+| 긴 main-thread task | profiler 기준으로 계산 분리 | Web Worker message adapter |
+| 대량 목록 | pagination과 server filter를 우선 | virtualizer/data-grid facade |
+| 이미지 전송량 | width/height, lazy loading, responsive source 규칙 | Image CDN URL builder adapter |
+| 재방문/offline | HTTP cache contract | Service Worker/IndexedDB adapter |
+| 불필요한 render | 상태 소유권 축소와 component boundary | 보통 adapter가 아니며 측정 후 memoization |
+
+기본 skeleton은 bundle budget, lazy route, query cancellation/cache, responsive
+image 규칙, stable layout, lab performance test를 제공한다. Web Worker,
+virtualization, Image CDN, Service Worker는 실제 병목과 제품 요구가 확인될 때
+설치한다. 라이브러리를 미리 많이 넣는 것은 최적화가 아니라 초기 번들·공급망
+표면을 늘리는 일이 될 수 있다.
+
+## 6. 질문별 직접 답변
+
+### 프론트도 inbound/outbound로 나누는가
+
+나눈다. 현재 구조에서는 `presentation`이 사실상 inbound adapter이고
+`src/adapters`가 outbound adapter다. 이름과 문서가 이 역할을 명확히 드러내지
+않아 모두 같은 adapter처럼 보인 것이다.
+
+| 역할 | 프론트 예 |
+| --- | --- |
+| input/inbound port | `ListResources`, `CreateResource` 같은 application API |
+| inbound adapter | React page/controller, router, form event, push-event translator |
+| output/outbound port | resource gateway, session, storage, clock, diagnostics |
+| outbound adapter | HTTP, auth SDK, browser storage, TanStack cache, telemetry sink |
+
+React, router, form library, icon library마다 application port를 만들 필요는 없다.
+UI 내부 교체만 필요한 라이브러리는 React inbound adapter 내부 vendor facade로
+충분하다. port는 application 정책과 외부 소유권 사이의 경계에 둔다.
+
+### 왜 현재 모두 `adapters` 아래에 있는가
+
+실제로 모두 있지는 않다. UI driver가 `presentation`이라는 이름으로 분리돼 있고,
+`adapters`에는 주로 outbound 구현이 있다. 다만 다음 두 대안 중 하나를 명시적으로
+선택해야 한다.
+
+1. 변경량을 줄여 `presentation = inbound adapter`로 문서화하고
+   `adapters/outbound`만 명시한다.
+2. TypeScript/feature migration과 함께 `adapters/inbound/react`와
+   `adapters/outbound`로 재구성한다.
+
+이 저장소는 input API 부재와 flat contracts 문제도 함께 고쳐야 하므로 두 번째
+구조가 장기적으로 더 명확하다. 단, 대규모 rename 자체를 기능 개선으로 세지 말고
+architecture gate와 수직 reference feature가 먼저 또는 같은 브랜치에서
+증명되어야 한다.
+
+### TypeScript로 바꾸는 것이 좋은가
+
+좋다. 특히 registry ID, Result/error union, port generic, route params/search,
+component variant를 컴파일 시점에 닫을 수 있다. 다만 일괄 rename은 권장하지
+않는다. tooling → core contracts → application ports/use cases → outbound →
+bootstrap → React TSX → tests 순서로 이동한다.
+
+### store 기본 설정이 필요한가
+
+상태 전략은 기본 제공해야 하지만 범용 global store dependency는 필수로 넣지
+않는다.
+
+- local interaction: `useState`/`useReducer`
+- shareable navigation state: URL
+- server state: TanStack Query
+- form state: form facade
+- low-frequency cross-cutting state: context 또는 typed external store
+- complex cross-feature workflow: Zustand/Redux Toolkit/state machine 중 선택
+- persistence: `StoragePort`
+
+서버 데이터를 global store에 복사하지 않는 규칙이 중요하다.
+[TanStack Query](https://tanstack.com/query/latest/docs/framework/react/overview),
+[Redux Toolkit](https://redux-toolkit.js.org/introduction/getting-started),
+[Zustand](https://zustand.docs.pmnd.rs/)의 역할은 서로 같지 않다.
+
+### retry, API client, logger, token manager, error, validation은 어디에 있는가
+
+- retry: `src/adapters/http/retry-policy.js`, 부분 준비
+- API client: `src/adapters/http/client.js`, 부분 준비
+- logger: 없음. telemetry와 분리하거나 diagnostics port로 합치는 결정 필요
+- token manager: 의도적으로 없음. opaque external auth owner가 credential을 소유
+- error: `src/contracts/errors.js`와 HTTP normalization, 부분 준비
+- validation: runtime/API Zod는 존재, route/form/domain 분리는 미완성
+
+token manager를 기본으로 추가하지 않는 이유는 token lifecycle이 인증 방식마다
+다르고 localStorage token을 일반 해법으로 만들면 보안 위험이 커지기 때문이다.
+BFF HttpOnly cookie 또는 OIDC/Auth SDK가 credential을 소유하도록 두고, SPA
+memory token이 필요한 프로젝트만 auth adapter를 추가한다.
+
+### Lucide React를 쓰면 디자인 시스템이 되는가
+
+아니다. [Lucide React](https://lucide.dev/guide/packages/lucide-react)는
+tree-shakable SVG icon source로 적절하지만 select, dialog, menu, focus management
+같은 UI behavior는 제공하지 않는다. Lucide는 local icon facade 뒤에 두고,
+복잡한 interaction은 [Radix Primitives](https://www.radix-ui.com/primitives/docs/overview/introduction)
+또는 React Aria 계열과 같은 headless primitive를 owned wrapper 뒤에서 선택한다.
+
+### 테스트는 현재 어떤 상태인가
+
+테스트 도구 구성은 강한 편이다. 다만 다음이 빠져 있다.
+
+- TS source와 test 전체 typecheck
+- 실제 composition root부터 page까지의 통합
+- query/mutation controller와 optimistic rollback
+- route registry/runtime map 정합성
+- runtime timeout/retry와 path/query/parsed body
+- shared MSW scenario catalog
+- isolated component stories와 interaction test
+- stable-environment visual regression
+- built `dist` 대상 release E2E
+- 위험 기반 coverage gate
+
+### 라우팅 전략은 무엇이 적절한가
+
+현재 client-only clean architecture와 TanStack Query 조합은 유지하되, 목표
+skeleton은 React Router Data Mode의 route object, blocker, scroll restoration,
+route error 경계를 사용한다. 서버 상태의 소유자는 계속 application input과
+TanStack Query이며 loader/action이 같은 데이터를 별도로 요청하지 않는다.
+[React Router 공식 mode 설명](https://reactrouter.com/start/modes)에 따라
+Framework Mode는 SSR/static generation, route module, framework-owned data
+loading을 실제 요구할 때만 선택한다.
+
+### 바로 쓸 수 있는 디자인 패턴은 무엇을 제공해야 하는가
+
+패턴 이름만 나열하지 않고 다음 executable blueprint를 제공해야 한다.
+
+- page controller: route/form event를 application input으로 변환
+- query/mutation adapter: server state lifecycle을 React에 연결
+- command/query use case: 읽기와 상태 변경 의도를 분리
+- gateway: application이 외부 데이터 소유자를 추상화
+- mapper/anti-corruption layer: transport DTO를 core model로 변환
+- Result + failure mapper: throw와 사용자 메시지 경계를 통제
+- strategy: retry, cache, auth recovery, feature flag 정책 교체
+- observer/external store: session/theme/realtime 구독
+- state machine: 복잡한 workflow에만 선택적으로 사용
+- compound component/headless wrapper: 접근 가능한 복합 UI를 소유
+- page template: layout과 상태 표면을 데이터 소유권에서 분리
+
+## 7. 실전 투입 준비 완료 기준
+
+막연한 백분율 대신 아래 조건을 모두 자동 또는 명시적 검토로 확인한다.
+
+1. reference feature가 route → controller → input use case → output gateway →
+   adapter → mapper → query cache → UI 상태 표면을 통과한다.
+2. application input API 외에는 UI에서 outbound dependency에 접근할 수 없다.
+3. TypeScript source와 tests가 strict 검사되고 JS 우회 경로가 없다.
+4. HTTP path/query/body/auth/timeout/retry/cancel/decode 실패가 계약 테스트된다.
+5. typed route registry와 runtime map이 양방향 완전성을 가진다.
+6. list/detail/form/status page template과 form error 정책이 준비돼 있다.
+7. 디자인 시스템 primitive/pattern이 isolated workshop, interaction, a11y,
+   visual test를 가진다.
+8. sample/reference feature 전체 삭제 후 typecheck/test/build가 통과한다.
+9. optional adapter는 설치 조건, 보안 경계, 실패 정책, 테스트 recipe가 있다.
+10. 새 feature 추가 문서가 파일 경로, 금지 의존, 실패 상태, 테스트, 검증 명령까지
+    안내한다.
+
+이 기준은 배포 provider, 실제 인증 tenant, 운영 telemetry vendor, production field
+data 같은 프로젝트별 외부 작업을 포함하지 않는다.
+
+## 8. 관련 상세 문서
+
+- [프론트 포트·어댑터와 기능 경계](./frontend-ports-adapters-and-boundaries.md)
+- [TypeScript·상태·데이터 흐름](./typescript-state-and-data-flow.md)
+- [라우팅·페이지·재사용 패턴](./routing-pages-and-patterns.md)
+- [프론트 플랫폼 구현 로드맵](./frontend-platform-implementation-roadmap.md)
+- [디자인 시스템 플랫폼](../styling/design-system-platform.md)
+- [프론트 플랫폼 테스트 전략](../testing/frontend-platform-testing-strategy.md)
@@ -0,0 +1,954 @@
+# 프론트엔드 플랫폼 구현 로드맵
+
+## 1. 목적과 준비 완료의 의미
+
+이 문서는 `develop`의 `cb195f8`을 계획 기준선으로 삼아, 현재 저장소에 선언된
+프론트엔드 계약을 실제 런타임과 자동 검증까지 연결하는 구현 순서를 정의한다.
+기준 커밋은 출발점일 뿐이며 각 구현 브랜치는 직전 브랜치가 병합된 최신
+`develop`에서 시작한다.
+
+구현 단계는 다음처럼 구분한다.
+
+| 단계 | 목적 | exit 상태 |
+| --- | --- | --- |
+| P0 | 새 기능이 사용할 input/output, HTTP/query, route/recovery 수직 경로 완성 | `LOCAL_CORE_READY` |
+| P1 | form/page/design/i18n, diagnostics, test, 공급망까지 템플릿 품질 완성 | `LOCAL_TEMPLATE_READY` |
+| P2 | 실제 요구가 생겼을 때 선택할 adapter recipe 제공 | 선택 항목만 `RECIPE_READY` |
+
+P0와 P1은 사용자가 요청한 높은 수준의 저장소 내부 준비도를 판단하기 전에 모두
+끝내야 한다. 이를 정밀한 백분율 점수로 표현하지 않고 다음 세 조건으로
+판정한다.
+
+1. 계약과 레지스트리의 모든 필드에 실제 consumer가 있다.
+2. 정상 경로와 실패 경로가 자동 테스트로 증명된다.
+3. 각 변경이 독립적으로 되돌릴 수 있고 feature branch와 evidence가 보존된다.
+
+P2는 제품 번들에 모든 기술을 미리 넣는 단계가 아니다. 선택 조건, port/facade,
+fake adapter, 실패 정책과 제거 절차를 준비하는 단계다.
+
+## 2. 명시적인 범위 밖
+
+다음 항목은 저장소가 seam, fail-closed 기본값, 검증 명령과 증거 형식을 제공할
+수는 있지만 실제 완료는 외부 프로젝트 또는 운영 환경의 책임이다.
+
+- 실제 hosting/CDN의 atomic deploy, cache purge, 응답 헤더와 rollback 실행
+- 실제 OAuth/OIDC/기업 IdP tenant, client, redirect URI와 token lifecycle
+- production telemetry, RUM, analytics, error-reporting vendor와 consent 정책
+- 실제 사용자에게서 수집한 28일 field Web Vitals와 최소 표본 결정
+- 저장소 호스팅 서비스의 required check, branch protection과 evidence retention
+- 운영용 CSP allowlist, signing key, provenance attestation과 비밀 관리
+- 실제 브랜드, 업무 문구, 번역 승인, 지원 locale와 법적 고지
+- 도메인 API, 권한 모델, 제품별 form schema와 업무 규칙
+- 운영 release 승인
+
+이 항목이 준비되지 않아도 demo, fake, no-op, unavailable adapter를 사용해
+P0/P1의 저장소 내부 구현과 테스트를 끝낼 수 있어야 한다. 반대로 외부 증거가
+없는데 `PRODUCTION_READY`, `WCAG_READY`, `FIELD_SLO_READY`를 주장해서는 안 된다.
+상위 promotion gate는 임의의 값을 만들어 PASS하지 않고 `FAIL_UNVERIFIED`를
+유지한다.
+
+## 3. 공통 구현 원칙
+
+- `.ts`나 `.tsx`를 만들기 전에 lint, architecture, registry, typecheck와 test
+  검색 범위가 해당 확장자를 검사한다.
+- React는 application input port를 호출하고, application은 output port만 안다.
+  구체 adapter 조립은 bootstrap만 담당한다.
+- route, API, error, query, storage, telemetry와 release registry는 문서용 목록이
+  아니라 실행과 검증의 단일 소스다.
+- path, search, body, response와 external event는 경계에서 parse하며 parse된
+  결과를 다음 계층으로 전달한다.
+- retry, cache, redirect, reload, submission과 redaction에는 각각 한 명확한
+  정책 소유자만 둔다.
+- 정상 테스트와 함께 invalid import, schema, URL, mutation, chunk, secret 같은
+  negative fixture가 실제 gate에 의해 거절돼야 한다.
+- vendor SDK type과 import는 local facade/adapter 밖으로 노출하지 않는다.
+- 선택 gate가 닫히지 않은 라이브러리는 lockfile에 추가하지 않는다.
+- 대규모 rename과 여러 capability를 한 merge에 섞지 않는다.
+
+## 4. Gitflow 브랜치 보존 규칙
+
+현재 저장소는 `main`과 `develop`을 사용하고 feature prefix가 비어 있다. 아래
+표의 `feature-...` 이름을 그대로 `git flow feature start`에 전달한다.
+
+```text
+최신 develop 확인
+  -> git flow feature start <정확한 feature-... 이름>
+  -> 작은 검증 가능한 commit
+  -> git flow feature publish <정확한 feature-... 이름>
+  -> 자동 gate와 review
+  -> develop에 --no-ff merge
+  -> develop과 feature branch를 모두 push
+  -> local/origin feature branch 보존
+```
+
+`git flow feature finish`는 feature branch를 삭제할 수 있으므로 사용하지 않는다.
+병합 후에도 로컬 브랜치와 `origin/feature-...`를 제거하지 않는다. merge commit
+SHA, feature tip, 실행한 gate와 artifact 위치를 PR 또는 merge evidence에
+기록한다.
+
+후속 브랜치는 미병합 feature branch에서 시작하지 않는다. 선행 브랜치를 먼저
+`develop`에 병합하고 최신 `develop`에서 새 브랜치를 시작한다. 병합 순서를
+바꾸려면 dependency와 acceptance를 다시 검토해야 한다.
+
+rollback은 reset이나 branch 삭제로 수행하지 않는다.
+
+1. 관련 promotion을 중단한다.
+2. 보존된 feature branch와 merge commit으로 정확한 변경 범위를 찾는다.
+3. `develop`에서 별도 `hotfix/...` 또는 revert branch를 만든다.
+4. `git revert -m 1 <merge-commit>`으로 merge를 되돌린다.
+5. rollback gate 후 revert branch와 원래 feature branch를 모두 보존한다.
+6. 수정은 최신 `develop`에서 새 feature branch로 다시 진행한다.
+
+## 5. 12개 브랜치와 병합 순서
+
+```mermaid
+flowchart TD
+  B01["01 P0 TypeScript tooling"]
+  B02["02 P0 input/output boundary"]
+  B03["03 P0 HTTP and query"]
+  B04["04 P0 routing and recovery"]
+  B05["05 P0 reference feature"]
+  B06["06 P1 forms and pages"]
+  B07["07 P1 design system"]
+  B08["08 P1 i18n"]
+  B09["09 P1 diagnostics"]
+  B10["10 P1 tests and registry evidence"]
+  B11["11 P1 supply chain"]
+  B12["12 P2 optional recipes"]
+
+  B01 --> B02 --> B03 --> B04 --> B05
+  B05 --> B06 --> B07 --> B08 --> B09 --> B10 --> B11
+  B11 -. "요구가 확인된 recipe만" .-> B12
+```
+
+| 순서 | 보존할 Gitflow feature branch | 단계 | 직접 선행조건 | rollback point |
+| --- | --- | --- | --- | --- |
+| 01 | `feature-frontend-typescript-tooling-foundation` | P0 | 기준선, VD-01 | RP-01 |
+| 02 | `feature-frontend-application-boundary-runtime` | P0 | 01 | RP-02 |
+| 03 | `feature-frontend-http-query-contract-execution` | P0 | 02 | RP-03 |
+| 04 | `feature-frontend-routing-release-recovery-runtime` | P0 | 03, VD-03 | RP-04 |
+| 05 | `feature-frontend-reference-feature-vertical-slice` | P0 | 04 | RP-05 |
+| 06 | `feature-frontend-form-page-platform` | P1 | 05, VD-04 | RP-06 |
+| 07 | `feature-frontend-design-system-platform` | P1 | 06, VD-05 | RP-07 |
+| 08 | `feature-frontend-i18n-message-formatting-contract` | P1 | 07, VD-06 | RP-08 |
+| 09 | `feature-frontend-diagnostics-telemetry-runtime` | P1 | 08, VD-07 | RP-09 |
+| 10 | `feature-frontend-test-registry-evidence-hardening` | P1 | 09, VD-08 | RP-10 |
+| 11 | `feature-frontend-supply-chain-verification` | P1 | 10, VD-09 | RP-11 |
+| 12 | `feature-frontend-optional-adapter-recipes` | P2 | 11, VD-10 | RP-12 |
+
+## 6. 브랜치별 구현과 acceptance
+
+### 01. `feature-frontend-typescript-tooling-foundation`
+
+**목표**
+
+점진적 TypeScript 전환 전에 JS, JSX, TS, TSX와 테스트가 모두 같은 정적 분석과
+CI gate를 통과하게 한다. 애플리케이션 전체를 일괄 변환하지 않는다.
+
+**선행조건과 decision**
+
+- 기준선의 `pnpm ci:gate` 결과를 보존한다.
+- TypeScript compiler와 기존 dependency 버전은 별도 dependency review 없이는
+  변경하지 않는다.
+- 공식 JavaScript migration 방식처럼 점진적으로 전환한다.
+  [TypeScript JavaScript migration](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)
+
+**구체 변경 범위**
+
+- root, application/source, tests용 TypeScript project/reference를 분리한다.
+- `src`, `tests`, `scripts`의 허용 확장자와 build output 제외 범위를 명시한다.
+- ESLint, dependency-cruiser, registry scanner와 architecture script의 JS-only
+  glob 및 `.js` 고정 경로를 JS/TS 양쪽으로 확장한다.
+- Vite, Vitest와 Playwright config가 TS source/test 오류를 우회하지 않게 한다.
+- 기존 JS에는 `checkJs`, 새 TS에는 strict 정책을 적용한다.
+- port, registry와 forbidden import용 `.ts`/`.tsx` fixture를 추가한다.
+
+**자동 테스트와 negative test**
+
+- JS와 TS source/test를 함께 typecheck하는 smoke
+- TSX presentation의 concrete HTTP adapter import를 architecture gate가 거절
+- 잘못된 port 구현과 discriminated union 사용이 typecheck 실패
+- TS registry row의 누락 필드, 중복 ID와 unknown reference가 gate 실패
+- 기존 JS invalid-call fixture도 계속 실패
+- `pnpm lint`, `pnpm check:types`, `pnpm check:architecture`,
+  `pnpm check:registries`, `pnpm test:all`, `pnpm build`
+
+**Acceptance**
+
+- 허용된 모든 source/test 확장자가 typecheck, lint, architecture, registry gate
+  중 필요한 검색 범위에 포함된다.
+- JS 안전망이 약해지지 않은 상태에서 TS fixture가 CI에 의해 차단된다.
+- 광범위한 unchecked cast나 임시 `any`로 통과시키지 않는다.
+- production source 대량 변환 없이 독립적으로 revert할 수 있다.
+
+**Rollback**
+
+RP-01에서 merge를 revert하면 기존 JS 기준선으로 돌아간다. 후속 TS 작업은
+RP-01이 복구될 때까지 병합하지 않는다.
+
+### 02. `feature-frontend-application-boundary-runtime`
+
+**목표**
+
+UI가 호출할 input port와 application이 외부에 요구할 output port를 분리하고,
+composition root가 생성한 `Application`을 실제 React tree에 주입한다.
+
+**선행조건과 decision**
+
+- 01의 TS-aware architecture gate가 병합돼 있어야 한다.
+- 범용 client store는 추가하지 않는다. local interaction은 React state, 공유
+  navigation state는 URL, server state는 query adapter가 소유한다.
+- 실제 IdP 없이 demo/external/unavailable session adapter를 유지한다.
+
+**구체 변경 범위**
+
+- application input API를 query/command use case 중심으로 정의한다.
+- gateway, session, cache, storage, clock, diagnostics와 release capability를
+  output port로 분류한다.
+- `createApplication`이 raw adapter를 다시 노출하지 않고 input API만 반환한다.
+- `ApplicationProvider`와 `useApplication` 역할의 inbound React adapter를 둔다.
+- bootstrap이 concrete output adapter를 선택하고 application을 router/page에
+  전달한다.
+- presentation의 fetch, browser storage, concrete QueryClient와 outbound adapter
+  직접 접근을 금지한다.
+- inbound/outbound ownership을 architecture gate와 type fixture에 반영한다.
+
+**자동 테스트와 negative test**
+
+- fake output ports를 이용한 application use-case 단위 테스트
+- runtime config → composition root → provider → smoke page 통합 테스트
+- presentation의 `adapters/outbound`, `fetch`, concrete QueryClient import 거절
+- application의 React, router, browser storage, vendor SDK import 거절
+- 잘못된 output port 구현과 누락 input이 typecheck 실패
+- bootstrap 이외 계층의 concrete adapter 조립 거절
+
+**Acceptance**
+
+- visible page가 raw outbound dependency 대신 application input API를 사용한다.
+- 조립됐지만 사용되지 않는 application, HTTP와 release-info 객체가 없다.
+- fake adapter만으로 application과 presentation의 정상·실패 경로를 테스트한다.
+- vendor type이 application public API에 나타나지 않는다.
+
+**Rollback**
+
+RP-02는 기존 provider wiring을 한 merge로 되돌릴 수 있어야 한다. 임시
+compatibility wrapper는 05 reference feature 완료 전에 제거한다.
+
+### 03. `feature-frontend-http-query-contract-execution`
+
+**목표**
+
+API operation registry의 path/search/body/schema/timeout/retry가 실제 요청에
+반영되게 하고, TanStack Query를 application input과 React 사이의 제한된 inbound
+adapter로 연결한다.
+
+**선행조건과 decision**
+
+- 02의 application error와 gateway 경계가 고정돼 있어야 한다.
+- shared HTTP가 network retry를 소유하고 query adapter의 중복 retry는 끈다.
+  다른 결정을 원하면 이 브랜치 전에 ADR을 남긴다.
+- TanStack Query를 server-state adapter로 유지하되 Zustand/Redux Toolkit에
+  server state를 복사하지 않는다.
+
+**구체 변경 범위**
+
+- request input을 operation/route ID, path params, search params, body, signal과
+  idempotency key로 분리한다.
+- operation registry에서 method, path, request/response schema, timeout과 retry
+  eligibility를 찾는다.
+- deterministic path/search builder를 만들고 parse/transform된 query/body를
+  실제 URL/payload에 사용한다.
+- runtime config의 timeout과 max attempts를 client factory에 주입한다.
+- abort, timeout, retry delay와 listener cleanup을 injectable clock/scheduler
+  경계로 통제한다.
+- TanStack import를 허용할 local query adapter 경계를 하나만 둔다.
+- `useApplicationQuery`, `useApplicationMutation` 역할의 controller API를
+  정의하고 query key, cancellation, invalidation과 optimistic rollback을
+  연결한다.
+- base state를 loading/success/empty/terminal로, overlay를
+  refreshing/stale-degraded/pending/conflict로 닫는다.
+- refreshing/stale 및 pending/conflict의 배타성과 stale-failure latch를
+  명시적으로 구현한다.
+- stale retry, duplicate-submit 방지와 conflict action을 실제 callback에
+  연결한다.
+
+**자동 테스트와 negative test**
+
+- path escaping, optional/array search, stable ordering 및 query key/request URL 일치
+- query/body transform 결과 전송, invalid input에서 `fetch` 0회
+- runtime timeout과 max attempts 0/1/N의 실제 호출 횟수
+- validation 실패, abort, success, exhausted retry의 timer/listener cleanup
+- caller abort와 timeout의 서로 다른 typed failure
+- unsafe mutation, non-retryable status와 schema failure retry 0회
+- 네 base state, 네 overlay와 허용 transition
+- refreshing 실패의 stale latch 및 성공/재시도 후 해제
+- pending/conflict 동시 상태 fixture 거절
+- duplicate submit 1회, optimistic success/rejection rollback/conflict resolution
+- unmount/navigation abort가 terminal error로 오인되지 않음
+- local adapter 밖의 `@tanstack/**` import 거절
+
+**Acceptance**
+
+- cache key에 포함된 request 입력이 실제 URL/body에서도 동일하게 사용된다.
+- runtime timeout/retry 설정이 실제 동작을 바꾼다.
+- 모든 종료 경로의 cleanup과 한계 횟수를 fake clock으로 결정적으로 증명한다.
+- QueryClientProvider가 단순 마운트 객체가 아니며 reference controller가 사용할
+  표준 API를 제공한다.
+- `AsyncSurface`의 모든 action이 실제 command와 검증된 state transition을 가진다.
+
+**Rollback**
+
+RP-03은 application port를 유지하면서 이전 HTTP compatibility adapter 또는
+imperative controller로 되돌릴 수 있어야 한다. request builder와 query adapter
+commit을 구분해 부분 revert가 가능하게 한다.
+
+### 04. `feature-frontend-routing-release-recovery-runtime`
+
+**목표**
+
+route registry를 executable router의 단일 계약으로 만들고 params/search/access/
+surface/chunk metadata를 route flow에 연결한다. lazy chunk 실패도 release
+manifest와 bounded recovery에 실제 연결한다.
+
+**선행조건과 decision**
+
+- 03의 controller가 parsed route input을 받을 수 있어야 한다.
+- VD-03 기본값은 React Router Data Mode다. route object, blocker, scroll
+  restoration과 route error 경계를 사용하되 server state는 application input과
+  TanStack Query가 계속 소유한다.
+  [React Router modes](https://reactrouter.com/start/modes),
+  [Data Mode custom setup](https://reactrouter.com/start/data/custom)
+- 고정된 `7.18.1` API로 전환하고 router version upgrade는 별도 dependency
+  브랜치로 분리한다.
+- 실제 hosting cache/purge는 범위 밖이며 test manifest server/browser adapter를
+  사용한다.
+
+**구체 변경 범위**
+
+- 직렬화 가능한 route contract와 component/codec runtime map을 분리한다.
+- route ID의 contract/runtime 양방향 완전성을 TypeScript와 registry gate로
+  검사한다.
+- registry에서 route objects, navigation, access hint, title, loading/error
+  surface와 chunk ID를 조립한다.
+- params/search를 application 호출 전에 Zod codec으로 parse하고 URL builder도
+  같은 codec을 사용한다.
+- unknown/authentication-required/forbidden/not-found/error surface의 소유자를
+  하나씩 정한다.
+- route change의 boundary reset, document title, main focus와 scroll 정책을
+  적용한다.
+- redirect-loop guard와 최대 hop을 실제 자동 redirect flow에 연결한다.
+- build의 Vite asset manifest와 route chunk ID를 release manifest의 검증 가능한
+  map으로 연결하고 `runtime-config.schema.json`을 artifact로 생성한다.
+- config/release/build/asset mismatch 오류 kind를 정확히 나눈다.
+- lazy rejection → no-store manifest refetch → active build/release pair 비교 →
+  guarded reload 1회 → 반복 실패 support/rollback surface를 연결한다.
+- 일반 render error는 chunk reload 경로에 들어가지 않고 local reset을 유지한다.
+- `FeatureBoundary`, `ReleaseInfoPort`와 chunk recovery controller를 production
+  call graph에 연결한다.
+
+**자동 테스트와 negative test**
+
+- registry row 추가 시 route tree/navigation 동시 추가
+- runtime 누락/orphan, duplicate path/ID, unknown schema/surface/chunk 거절
+- invalid params/search, unknown route와 access rejection에서 application/API 0회
+- URL parse/build round-trip과 canonical search
+- redirect cycle이 최대 hop에서 종료
+- route 전환 후 error reset, main heading focus와 중복 surface 없음
+- stale chunk + manifest mismatch에서 no-store refetch 후 reload 정확히 1회
+- 같은 build/release pair의 두 번째 실패에서 reload 0회와 support surface
+- manifest malformed/offline/storage unavailable의 fail-closed 동작
+- 일반 component throw가 chunk failure로 오분류되지 않음
+- build/config/release/asset mismatch의 정확한 error kind
+- built `dist`의 route chunk map, runtime schema와 release artifact set 검증
+
+**Acceptance**
+
+- 수동 route 열거와 registry가 서로 어긋날 수 없다.
+- route metadata 중 consumer 없는 token이 0개다.
+- invalid/unknown/access-rejected URL에서 product API 0회를 증명한다.
+- chunk recovery 결정이 production call graph에 있으며 무한 reload가 불가능하다.
+- 실제 CDN 없이 저장소 내부 recovery matrix가 결정적으로 통과한다.
+
+**Rollback**
+
+RP-04는 이전 수동 router와 generic route failure surface로 한 merge를 되돌릴 수
+있어야 한다. URL shape는 바꾸지 않으며 불가피한 변경은 compatibility redirect와
+migration이 있어야 한다. 실제 CDN purge는 rollback 범위에 포함하지 않는다.
+
+### 05. `feature-frontend-reference-feature-vertical-slice`
+
+**목표**
+
+route에서 실제 HTTP/query/application/presentation까지 연결되며 전체를 제거해도
+generic platform이 정상 부팅되는 하나의 reference feature를 만든다.
+
+**선행조건과 decision**
+
+- 01~04가 모두 병합돼 있어야 한다.
+- 실제 backend와 IdP 대신 MSW/fake gateway와 demo auth를 사용한다.
+- reference 업무 용어를 제품 도메인 계약으로 승격하지 않는다.
+
+**구체 변경 범위**
+
+- 흩어진 sample route, operation, schema, mapper, domain, query key, controller,
+  page와 tests를 canonical `src/features/reference-feature` 한 ownership 경계로
+  이동한다.
+- feature 내부에 domain, application input/output, outbound gateway, DTO/schema,
+  mapper, query/mutation controller와 presentation page를 둔다.
+- list filter가 URL codec, query key와 실제 HTTP request에 동일하게 반영된다.
+- safe mutation으로 pending, duplicate prevention, optimistic state, conflict와
+  rollback을 보여 준다.
+- registry/application에는 removable contribution contract를 사용하고 generic
+  source에는 fixture-specific ID를 하드코딩하지 않는다.
+- production bootstrap과 같은 composition 경로에 fake adapter를 주입한다.
+- `src/features/reference-feature` 전체를 제거한 ephemeral copy에서
+  typecheck/test/build/home smoke를 실행하도록 sample-removal gate를 다시
+  작성한다.
+
+**자동 테스트와 negative test**
+
+- bootstrap → router → controller → input use case → gateway → HTTP/MSW →
+  response schema → mapper → cache → page의 수직 통합
+- loading/success/empty/terminal/refreshing/stale/pending/conflict/recovery UI
+- invalid search에서 gateway/fetch 0회
+- invalid DTO가 domain/view model로 전파되지 않음
+- backend forbidden을 client access hint와 무관하게 최종 반영
+- duplicate/unsafe mutation 전송 횟수
+- `src/features/reference-feature` 삭제 후 typecheck, architecture, registry,
+  unit/integration, home smoke와 build
+- 삭제 후 sample route 부재와 `src`/`tests`의 fixture-specific ID 잔여 0개
+- generic home/examples route가 sample 없이 계속 작동
+
+**Acceptance**
+
+- static page와 분리된 fixture가 아니라 실제 수직 경로 하나가 존재한다.
+- reference feature를 삭제할 때 central registry를 수작업으로 수정하는 숨은
+  단계가 없거나 제거 명령이 이를 결정적으로 수행한다.
+- feature 존재/제거 두 모드에서 P0 gate가 모두 통과한다.
+- 01~04를 함께 revert해야만 sample을 제거할 수 있는 숨은 결합이 없다.
+
+**Rollback**
+
+RP-05는 P0 최종 지점이다. reference feature merge만 revert해도 generic platform은
+정상이어야 한다.
+
+## 7. P0 exit gate
+
+- JS/TS source와 tests가 동일한 정적 gate에 포함된다.
+- UI는 application input API만 호출하고 concrete outbound adapter를 모른다.
+- HTTP path/search/body/auth/timeout/retry/cancel/decode가 실행 계약과 일치한다.
+- query/mutation controller와 모든 async state transition이 작동한다.
+- route registry/runtime map과 route chunk map이 양방향 완전성을 가진다.
+- lazy chunk failure가 bounded release recovery에 연결된다.
+- reference feature가 실제 수직 경로를 실행하고 전체 삭제 gate를 통과한다.
+- `pnpm ci:gate`와 P0에서 추가한 모든 negative fixture가 통과한다.
+
+위 조건이 모두 충족돼야 `LOCAL_CORE_READY`다. RP-05 증거를 보존한 뒤 P1을
+시작한다.
+
+## 8. P1 브랜치
+
+### 06. `feature-frontend-form-page-platform`
+
+**목표**
+
+Zod schema와 application command를 연결하는 form controller 및
+standard/collection/detail/form/status page template를 제공한다.
+
+**선행조건과 decision**
+
+- 05의 mutation과 async state가 실제 reference flow에서 작동해야 한다.
+- VD-04에서 React Hook Form + Zod resolver 사용 여부를 정한다. 복합 form 요구가
+  확정되면 local facade 뒤에 추가하고, 거절되면 native form + local controller가
+  같은 public API와 tests를 충족한다.
+  [React Hook Form resolvers](https://github.com/react-hook-form/resolvers),
+  [Zod](https://zod.dev/)
+- vendor 결정 전에 dependency/lockfile을 변경하지 않는다.
+
+**구체 변경 범위**
+
+- presentation form schema와 domain invariant를 분리한다.
+- field registration, parse/error map, dirty/touched/reset/pending/result를 local
+  form API로 감싼다.
+- `422` field/form/unknown-server-field/global error mapping을 정의한다.
+- 첫 오류 focus, error summary, field ID와 live-region을 연결한다.
+- duplicate submit, cancel/leave와 unsaved-change 정책을 적용한다.
+- `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage`, `StatusPage`의 slot
+  계약을 정의한다.
+- heading, breadcrumb, actions, filters, content, aside와 feedback의 소유 위치를
+  표준화한다.
+- reference list/detail/create-edit/status page를 controller와 template로
+  전환한다.
+- template가 application use case나 query vendor를 직접 선택하지 않게 한다.
+
+**자동 테스트와 negative test**
+
+- client validation 실패에서 command 0회와 첫 invalid field focus
+- transformed/defaulted data가 command에 전달됨
+- field/form/unknown server error와 conflict 후 입력 보존
+- pending 중 연속 submit에도 command 1회
+- reset 후 dirty 해제와 navigation confirmation/focus restore
+- secret-like input이 URL/storage/log/telemetry에 나타나면 실패
+- 각 template의 최소/전체 slot 및 async/error variation
+- 320px, zoom, 긴 heading/action과 wide layout
+- heading/landmark/accessibility-name/axe
+- template가 application/HTTP/query vendor를 import하면 gate 실패
+- action callback 없이 활성 버튼을 렌더링하면 실패
+
+**Acceptance**
+
+- form engine을 바꿔도 page와 application API가 변하지 않는다.
+- multi-field form의 validation/pending/dirty/422/conflict가 실행된다.
+- 새 feature가 layout CSS를 복사하지 않고 다섯 page 유형을 조립한다.
+- template는 layout/state slot만 소유하고 데이터 정책은 소유하지 않는다.
+
+**Rollback**
+
+RP-06은 기존 reference controls/layout으로 돌아가도 controller/application
+경계가 유지돼야 한다. vendor adapter, form contract와 template commit을 구분해
+부분 revert가 가능하게 한다.
+
+### 07. `feature-frontend-design-system-platform`
+
+**목표**
+
+기존 theme와 primitive를 token → primitive → pattern → template 계층으로
+확장하고, 모바일 drawer와 복합 interaction을 접근 가능한 local API로 제공한다.
+
+**선행조건과 decision**
+
+- 06의 page/form에서 반복되는 실제 token/primitive 요구를 수집한다.
+- VD-05에서 icon source와 headless interaction 방식을 결정한다.
+- Lucide를 선택하면 static named import만 local icon facade에서 허용한다.
+  [Lucide React](https://lucide.dev/guide/react),
+  [Lucide accessibility](https://lucide.dev/guide/react/advanced/accessibility)
+- headless vendor가 미결정이면 native dialog/disclosure/control 범위만 완료하며,
+  미지원 widget을 임의 구현해 완료로 표시하지 않는다.
+
+**구체 변경 범위**
+
+- primitive/semantic/component token을 분리한다.
+- color, typography, spacing, size, radius, elevation, z-layer, motion, breakpoint와
+  opacity 계약을 정의한다.
+- light/dark/system, forced-colors와 reduced-motion을 닫는다.
+- design-system public entry와 deep-import 금지 규칙을 만든다.
+- 기존 Button/TextField/Card/Alert/Badge/Dialog를 호환 가능한 public API로
+  이동한다.
+- LinkButton/IconButton/Field/TextArea/Select/Checkbox/RadioGroup/Switch/
+  Spinner/Skeleton/VisuallyHidden을 기본 제공한다.
+- Drawer/Popover/Tooltip/Menu/Tabs/Breadcrumbs/Pagination/Toast/ProgressBar 및
+  필요한 focus/portal utility를 추가한다.
+- 모바일 navigation을 Drawer로 전환해 focus 이동, modal/background 정책,
+  Escape/scrim/link dismiss와 trigger focus restore를 구현한다.
+- 앱 셸의 문자 glyph/raw control을 local icon/primitive로 교체한다.
+- `/examples/ui`와 `/examples/states`에서 interactive state를 실제 동작으로
+  노출한다.
+
+**자동 테스트와 negative test**
+
+- 필수 semantic token의 light/dark/forced-colors 정의
+- undefined CSS variable/raw palette 사용 거절
+- interactive icon의 accessible name 누락 거절, decorative icon tree 제외
+- product code의 direct icon/headless vendor 또는 deep import 거절
+- disabled/pending/focus/invalid와 reduced-motion/theme persistence
+- keyboard-only open/move/select/dismiss/focus restore
+- Drawer open 시 background interaction 차단과 compact reflow
+- Menu/Tabs arrow key, typeahead와 activation 정책
+- Tooltip만으로 필수 정보를 제공하는 fixture 거절
+- Toast queue 상한/duplicate collapse/timeout pause
+- Chromium/Firefox/WebKit component/E2E/axe
+
+**Acceptance**
+
+- shell, templates와 reference feature가 public design-system API를 사용한다.
+- product code의 raw palette, vendor icon/headless import가 0개다.
+- mobile navigation이 검증된 focus/dismiss contract를 따른다.
+- gallery action이 handler 없는 장식이 아니라 실행 가능한 상태를 시연한다.
+- token 누락과 접근 불가능한 interaction을 자동 gate가 차단한다.
+
+**Rollback**
+
+RP-07은 compatibility export로 기존 primitive import를 복구할 수 있어야 한다.
+token rename은 alias/migration 기간을 두고, vendor adapter와 local API commit을
+분리한다.
+
+### 08. `feature-frontend-i18n-message-formatting-contract`
+
+**목표**
+
+사용자 문구, 날짜, 숫자, 상대 시간과 direction을 typed message/formatter 경계로
+옮겨 특정 언어 literal과 locale 가정을 공통 UI에서 제거한다.
+
+**선행조건과 decision**
+
+- 07까지의 common user-facing string 목록이 확보돼 있어야 한다.
+- VD-06 기본값은 browser `Intl` + typed local catalog다. extraction/plural 등
+  요구가 이를 넘을 때만 vendor를 선택한다.
+- 실제 번역 승인과 지원 locale은 외부 프로젝트 범위다.
+
+**구체 변경 범위**
+
+- typed message key와 interpolation parameter 계약을 정의한다.
+- locale provider, fallback locale, direction과 date/number/relative-time
+  formatter를 제공한다.
+- shell, route, async/form error와 design-system 기본 copy를 catalog로 이동한다.
+- backend raw message를 번역 key로 신뢰하지 않고 error registry로 매핑한다.
+- pseudo-locale와 RTL smoke locale을 테스트 전용으로 제공한다.
+- unknown key/locale, formatter failure와 missing interpolation의 fallback을
+  정의한다.
+
+**자동 테스트와 negative test**
+
+- 모든 등록 locale의 key parity와 interpolation 정합성
+- unknown locale/key에서 raw key/stack을 노출하지 않는 fallback
+- pseudo-locale 확장에 대한 layout/reflow
+- RTL shell/drawer/breadcrumb와 directional icon
+- 날짜/숫자/timezone의 결정적 test
+- untrusted HTML interpolation 및 backend message 직접 렌더링 거절
+- common UI의 금지된 hardcoded user-facing literal 검출
+
+**Acceptance**
+
+- shell/state/form/error copy가 typed catalog를 통과한다.
+- pseudo-locale와 RTL E2E가 통과한다.
+- 실제 제품 번역 없이도 locale 교체 지점과 실패 정책이 검증된다.
+- key rename에는 compatibility alias 또는 migration이 있다.
+
+**Rollback**
+
+RP-08은 기존 기본 언어 catalog를 fallback으로 유지한다. 번역 catalog를
+파괴적으로 덮어쓰지 않는다.
+
+### 09. `feature-frontend-diagnostics-telemetry-runtime`
+
+**목표**
+
+structured diagnostics와 telemetry를 구분하고 boot, HTTP, cache, storage, route,
+render와 release 사건을 실제 producer에 연결한다.
+
+**선행조건과 decision**
+
+- route/HTTP/query/form/release failure kind가 안정돼 있어야 한다.
+- VD-07에서 외부 exporter를 선택하지 않아도 된다. no-op 또는 기존
+  best-effort HTTP sink를 기본으로 하고 실제 vendor SDK는 외부 adapter다.
+
+**구체 변경 범위**
+
+- diagnostics/logger output port와 telemetry event port의 책임을 분리한다.
+- level, event ID, timestamp, correlation/request/route/release context와 redaction
+  정책을 정의한다.
+- `app.boot.failed`, `api.request.failed`, `ui.render.failed`,
+  `release.mismatch.detected`, `telemetry.delivery.dropped`를 production path에
+  연결한다.
+- retry attempt마다 terminal failure를 중복 발행하지 않고 bounded summary만
+  남긴다.
+- route/path/query/body/error에서 고카디널리티와 민감 값을 제거한다.
+- queue 상한, drop reason bucket, sink failure와 nonrecursive fallback을
+  구현한다.
+- reference feature에서 route → application → HTTP outcome correlation을
+  증명한다.
+
+**자동 테스트와 negative test**
+
+- registry event가 production path에서 필요한 횟수만 발행
+- success/retry recovery/terminal failure event 차이
+- Authorization/cookie/token/raw form/body/PII-like fixture redaction
+- large/circular/unknown error에서도 serializer가 throw하지 않음
+- queue full/sink failure가 app failure나 재귀 폭주를 만들지 않음
+- unknown/high-cardinality event context 거절
+- mount 전 boot failure도 안전한 evidence 생성
+- no-op adapter에서도 동일 application behavior
+
+**Acceptance**
+
+- 필수 telemetry event 중 producer 없는 항목이 0개다.
+- sink/vendor가 없어도 기능이 정상이며 failure evidence가 제한된다.
+- credential/raw user input이 queue, console과 artifact에 남지 않는다.
+- exporter wiring만 독립적으로 제거할 수 있다.
+
+**Rollback**
+
+RP-09는 exporter를 제거하고 즉시 no-op adapter로 전환할 수 있어야 한다.
+diagnostics port와 redaction test는 유지한다.
+
+### 10. `feature-frontend-test-registry-evidence-hardening`
+
+**목표**
+
+registry의 구조/참조/consumer/호환성을 실제 diff로 검증하고, P0/P1 위험 경로를
+실제 bootstrap과 built artifact에서 증명한다.
+
+**선행조건과 decision**
+
+- 09까지의 public contract와 registry field가 안정돼 있어야 한다.
+- VD-08 기본값은 dev-only Storybook workshop과 local Playwright visual
+  baseline이다. cloud review service는 선택이다.
+- `/examples/ui`, `/examples/states`는 실제 앱 composition의 통합 smoke로
+  유지하며 isolated story의 SSOT를 대신하지 않는다.
+  [Storybook documentation](https://storybook.js.org/docs)
+
+**구체 변경 범위**
+
+- route/API/schema/error/query/storage/telemetry/config/release registry의 field
+  type/enum/unique/cross-reference/consumer/orphan을 machine-readable하게 검사한다.
+- 직전 승인 snapshot과 현재 snapshot의 actual diff로 additive/behavioral/
+  breaking/removal을 계산한다.
+- breaking에는 version bump, migration, compatibility window와 rollback
+  evidence를 요구한다.
+- hardcoded `current: additive`, empty high-risk review와 self-asserted PASS를
+  제거한다.
+- source와 tests를 모두 포함하는 TypeScript check를 CI 필수 gate로 만든다.
+- MSW handler를 operation/schema 기반 shared scenario catalog로 통합한다.
+- 실제 `main` composition과 built `dist`의 integration/release E2E를 추가한다.
+- Playwright compact/mobile project와 risk-based coverage threshold를 추가한다.
+- deterministic clock/random/fetch/storage helper, unexpected console/unhandled
+  rejection 실패 정책을 제공한다.
+- 선택된 workshop interaction 또는 안정 환경의 visual baseline을 추가한다.
+- JUnit/screenshot/trace/evidence naming과 CI gate registry를 맞춘다.
+
+**자동 테스트와 negative test**
+
+- duplicate ID/path, invalid enum/type, missing field/reference와 orphan 거절
+- actual removal/type narrowing/path change를 additive로 표시하면 실패
+- breaking diff의 version/migration/rollback 누락 실패
+- ordering-only diff는 semantic change가 아님
+- 승인 baseline digest 변조 실패
+- unexpected network/operation, provider 누락과 unhandled error 실패
+- critical policy coverage threshold 미달 실패
+- built artifact의 source map, config schema 누락과 broken chunk 실패
+- compact viewport와 Chromium/Firefox/WebKit navigation/a11y smoke
+- reference feature 제거 모드의 generic E2E/build
+- screenshot mask가 전체 UI를 가려 false PASS를 만들면 실패
+
+**Acceptance**
+
+- route 선언/실행 불일치와 telemetry producer 누락을 registry gate가 잡는다.
+- compatibility impact가 하드코딩 상수가 아니라 actual diff다.
+- 테스트가 source module만이 아니라 real composition과 `dist`를 증명한다.
+- 모든 P0/P1 high-risk policy에 negative fixture가 하나 이상 있다.
+- CI artifact로 browser/release/fixture 실패를 재현할 수 있다.
+
+**Rollback**
+
+RP-10은 직전 승인 registry snapshot과 test evidence다. flaky visual/browser
+infrastructure commit은 product behavior와 분리한다. 장기 skip으로 PASS하지 않고
+owner와 만료 시한이 있는 quarantine만 허용한다.
+
+### 11. `feature-frontend-supply-chain-verification`
+
+**목표**
+
+직접·전이 dependency, vulnerability, license, secret, SBOM/inventory와 provenance를
+검증 가능한 release gate로 만든다.
+
+**선행조건과 decision**
+
+- 10까지 최종 build/test dependency 구조가 안정돼 있어야 한다.
+- VD-09에서 vulnerability source, license policy, SBOM format과 attestation
+  provider를 선택한다.
+- provider가 미결정이면 임의 PASS를 만들지 않고 promotion을
+  `FAIL_UNVERIFIED`로 유지한다. local inventory/fixture 검증은 완료할 수 있다.
+
+**구체 변경 범위**
+
+- frozen lockfile에서 direct/transitive dependency inventory를 생성한다.
+- name/version, direct/transitive, resolved integrity와 license를 deterministic하게
+  기록한다.
+- actual baseline/lockfile diff에서 new/removed/changed dependency와
+  reviewer-required risk를 계산한다.
+- secret scan 범위를 source/dist/tracked config/generated manifest와 artifact
+  metadata에 맞게 확장한다.
+- 선택된 vulnerability/license adapter가 severity, exception owner/expiry를
+  machine-readable evidence로 남기게 한다.
+- SBOM 또는 동등 inventory, build digest와 provenance statement를 coherent
+  release artifact set에 연결한다.
+- frozen install과 동일 source/lock/config의 reproducible build를 검증한다.
+
+**자동 테스트와 negative test**
+
+- transitive dependency inventory 누락 실패
+- lockfile integrity/digest 변조와 unfrozen install 실패
+- high-risk dependency의 self-approval 실패
+- 금지 license, threshold vulnerability와 만료 exception 실패
+- source/dist/config secret fixture 검출 및 test-secret allowlist 통제
+- SBOM/inventory와 release manifest digest 불일치 실패
+- provenance subject와 artifact digest 불일치 실패
+- dependency ordering만 달라도 deterministic output 유지
+
+**Acceptance**
+
+- dependency diff와 high-risk review가 하드코딩 빈 배열이 아니다.
+- transitive inventory, license와 vulnerability 결과가 release evidence에
+  포함된다.
+- provider/organization decision이 없으면 상위 promotion이 명시적으로
+  `FAIL_UNVERIFIED`다.
+- 위험 dependency upgrade만 독립적으로 revert할 수 있다.
+
+**Rollback**
+
+RP-11은 P1 최종 저장소 기준선이다. scanner outage를 무검증 승인으로 우회하지
+않고 promotion을 보류한다.
+
+## 9. P1 exit gate
+
+- 현실적인 form의 validation/dirty/pending/422/conflict가 작동한다.
+- collection/detail/form/status를 포함한 page template가 reference feature에서
+  사용된다.
+- token → primitive → pattern → template 경계가 자동 보호된다.
+- compact navigation과 interaction의 keyboard/focus 계약이 검증된다.
+- typed message, pseudo-locale와 RTL smoke가 존재한다.
+- 필수 telemetry event가 실제 producer에 연결되고 secret/PII가 redaction된다.
+- registry/compatibility가 actual diff와 cross-reference로 검증된다.
+- bootstrap과 built `dist`를 포함한 risk-based test/evidence가 남는다.
+- transitive dependency, vulnerability, license와 local SBOM가 선택된 정책에
+  따라 검증된다. 외부 signing/provenance provider가 미결정이면 해당 promotion만
+  `FAIL_UNVERIFIED`다.
+- 현재 merge gate가 요구하는 등록 route의 signed manual accessibility evidence가
+  갱신된다.
+- P0/P1 feature branch와 merge evidence가 local/origin에 모두 보존된다.
+
+위 조건이 모두 충족되면 `LOCAL_TEMPLATE_READY`다. 실제 hosting, IdP,
+production sink와 field data 없이도 저장소 내부 상태는 달성할 수 있지만, 외부
+gate 없이는 production promotion을 통과했다고 보지 않는다.
+
+## 10. P2 브랜치
+
+### 12. `feature-frontend-optional-adapter-recipes`
+
+**목표**
+
+모든 프로젝트에 dependency를 미리 설치하지 않고, 실제 요구가 확인된 capability의
+선택 기준, port/facade, fake adapter, failure policy와 test recipe를 제공한다.
+
+**선행조건과 decision**
+
+- P0/P1 public boundary가 안정돼 있어야 한다.
+- VD-10에서 실제 소비 요구, owner, 보안 영향, bundle 예산과 제거 조건이
+  승인된 recipe만 구현한다.
+- 승인되지 않은 recipe의 runtime dependency는 추가하지 않는다.
+
+**구체 변경 범위**
+
+| recipe | 기본 경계 | 반드시 다룰 실패 |
+| --- | --- | --- |
+| realtime | subscribe/unsubscribe, reconnect, resume, heartbeat | disconnect, duplicate/out-of-order, auth expiry |
+| offline/IndexedDB | versioned repository와 migration | quota, corruption, migration rollback |
+| Service Worker/PWA | cache ownership와 update controller | stale worker, update loop, offline fallback |
+| file transfer | upload/download, progress, cancel | size/type rejection, abort, expired URL |
+| generated API | generated client를 gateway 뒤에 감싸는 facade | contract drift, unsupported field |
+| feature flag | typed key, default와 stale policy | provider unavailable, unknown flag |
+| Web Worker | request/result/cancel protocol | crash, stale result, transfer failure |
+| multi-tab | versioned BroadcastChannel event | self-echo, duplicate, conflict |
+| browser permission | clipboard/notification/media result port | denied, dismissed, unsupported |
+| client workflow | Zustand/Redux Toolkit/state-machine local facade | reset, mismatch, server-state duplication |
+| large data UI | virtualizer/data-grid facade | focus loss, stale row, scale limit |
+| analytics/error sink | consent/redaction/sampling adapter | denied consent, queue full, unavailable |
+
+- 각 recipe에 설치/금지 조건, ownership, security/privacy, bundle 영향, fallback과
+  제거 절차를 기록한다.
+- runnable fixture는 production entry에서 제외한 opt-in example/test entry에
+  둔다.
+- Zustand와 Redux Toolkit을 동시에 기본 설치하지 않는다.
+- browser가 DB/object store에 직접 접속하는 recipe는 만들지 않고 권한 있는
+  backend/BFF protocol adapter를 사용한다.
+
+**자동 테스트와 negative test**
+
+- 선택 recipe의 fake adapter contract 및 unavailable fallback
+- unsubscribe/cancel/cleanup 누락 fixture 실패
+- local adapter 밖의 vendor SDK direct import 실패
+- credential을 localStorage/telemetry/URL에 저장하는 fixture 실패
+- server state를 client workflow store에 복제하는 fixture 실패
+- recipe 제거 후 base typecheck/test/build 통과
+- opt-in하지 않은 recipe가 production bundle에 없음을 검증
+
+**Acceptance**
+
+- 선택 capability는 port/facade, fake adapter, failure matrix, tests와 제거
+  절차를 가진다.
+- 선택하지 않은 capability는 dependency와 production code를 늘리지 않는다.
+- recipe 하나의 도입/제거가 다른 recipe와 P0/P1 runtime을 변경하지 않는다.
+
+**Rollback**
+
+RP-12는 recipe별 merge commit이다. optional adapter 문제 시 해당 recipe commit만
+revert하고 RP-11을 유지한다. 여러 vendor를 되돌릴 수 없는 한 commit에 묶지
+않는다.
+
+## 11. Vendor decision gate
+
+| ID | 시점 | 결정 | 기본값 또는 미결정 시 처리 | 차단 범위 |
+| --- | --- | --- | --- | --- |
+| VD-01 | 01 전 | TypeScript migration 범위와 compiler 변경 | 기존 compiler 고정, tooling-first 점진 전환 | compiler upgrade와 source 변환 |
+| VD-02 | 02 전 | 범용 client store | 추가하지 않음. local/URL/query/context 사용 | 실제 cross-feature workflow만 |
+| VD-03 | 04 전 | React Router mode | Data Mode; server state는 TanStack/application 유지 | Framework/SSR 전환만 |
+| VD-04 | 06 전 | form engine | 복합 form이면 RHF+Zod facade, 아니면 local/native | form 구현체 |
+| VD-05 | 07 전 | icon/headless UI | local facade, native 우선; 미지원 behavior는 미완료 | icon/복합 primitive |
+| VD-06 | 08 전 | i18n engine | `Intl` + typed local catalog | extraction/plural 고급 기능 |
+| VD-07 | 09 전 | diagnostics/telemetry exporter | no-op/best-effort HTTP | production sink만 |
+| VD-08 | 10 전 | Storybook/visual 방식 | dev-only Storybook + local Playwright baseline | cloud review/별도 배포 |
+| VD-09 | 11 전 | vulnerability/license/SBOM/provenance | 임의 PASS 금지, `FAIL_UNVERIFIED` | release promotion |
+| VD-10 | 12 전 | optional capability 요구 | 설치하지 않음 | 해당 recipe만 |
+
+각 decision에는 실제 요구, bundle/runtime/a11y/security 영향, local facade 방식,
+대안, fallback/migration/removal, owner와 재검토 시점을 기록한다.
+
+결정이 지연될 때 vendor-neutral port와 no-op/fake/unavailable adapter를 먼저
+완성한다. 다만 vendor가 있어야 충족되는 behavior를 구현하지 않은 채 완료로
+표시해서는 안 된다.
+
+## 12. Rollback과 promotion
+
+| checkpoint | 포함 범위 | 다음 단계 진입 조건 | 대표 rollback 사유 |
+| --- | --- | --- | --- |
+| RP-01 | tooling | TS/JS fixture와 gate 통과 | TS 파일이 검사에서 누락 |
+| RP-02 | application boundary | composition integration 통과 | UI가 raw adapter에 의존 |
+| RP-03 | HTTP/query | request/state negative matrix 통과 | query 손실, retry/submit 폭주 |
+| RP-04 | routing/recovery | registry와 reload-loop drill 통과 | invalid URL API 호출, reload loop |
+| RP-05 | P0 reference | feature 존재/제거 gate 통과 | hidden sample coupling |
+| RP-06 | form/page | form/page/a11y gate 통과 | 입력 손실, template 결합 |
+| RP-07 | design system | token/interaction gate 통과 | focus/theme/vendor 회귀 |
+| RP-08 | i18n | catalog/pseudo/RTL gate 통과 | missing key, locale 회귀 |
+| RP-09 | diagnostics | producer/redaction gate 통과 | PII 노출, event 폭주 |
+| RP-10 | test/registry | actual diff와 evidence gate 통과 | false PASS, flaky blocker |
+| RP-11 | P1 supply chain | `LOCAL_TEMPLATE_READY` | 위험 dependency/검증 공백 |
+| RP-12 | optional recipe | recipe별 opt-in gate | vendor 격리 실패 |
+
+```text
+RP-05 + P0 exit
+  = LOCAL_CORE_READY
+
+RP-11 + P1 exit
+  = LOCAL_TEMPLATE_READY
+
+LOCAL_TEMPLATE_READY
+  + 실제 hosting/IdP/보안/접근성/운영 증거
+  = PROJECT_INTEGRATION_READY
+
+PROJECT_INTEGRATION_READY
+  + production promotion과 eligible field data
+  = PRODUCTION/FIELD READY
+```
+
+저장소 내부와 외부 증거를 하나의 백분율로 숨기지 않는다. P0/P1의 모든
+acceptance가 자동 검증되고 외부 항목이 명확히 분리된
+`LOCAL_TEMPLATE_READY`를 높은 저장소 내부 준비도의 실질 기준으로 사용한다.
+
+## 13. 브랜치 공통 인수 체크리스트
+
+각 feature branch는 병합 전에 다음을 evidence에 남긴다.
+
+- 목표와 변경하지 않는 범위
+- 시작한 `develop` SHA와 선행 merge SHA
+- 변경한 public contract, registry와 compatibility 영향
+- positive/negative fixture
+- 실행한 typecheck, lint, architecture, unit, integration, E2E와 build 명령
+- artifact와 browser/runtime 환경
+- dependency/lockfile 변경 및 vendor decision ID
+- fake/no-op/unavailable adapter로 검증한 범위
+- external blocker와 `FAIL_UNVERIFIED` promotion
+- merge commit과 보존된 local/origin feature tip
+- rollback 대상 merge와 복구 확인 gate
+
+acceptance를 만족하지 못한 브랜치는 후속 브랜치의 기반으로 사용하지 않는다.
+test를 skip하거나 문서상 예외로 바꾸는 것은 완료가 아니다.
@@ -22,6 +22,14 @@ The following edges are forbidden:
 `bootstrap` contains composition only. Business rules and page-specific
 orchestration belong to domain/application.

+This table is the current coarse-grained rule. The
+[ports, adapters, and feature-boundary target](./frontend-ports-adapters-and-boundaries.md)
+defines the missing application input boundary, explains that `presentation`
+acts as the inbound adapter, and separates current outbound adapters from
+project-selected capabilities. The
+[platform capability review](./frontend-platform-capability-review.md) records
+where the current composition still bypasses this intended rule.
+
 Architecture reports use this shape:

 ```json
@@ -8,6 +8,8 @@ in `review-ledger.json`, not automatically to edits in this file.
 flowchart LR
  Bootstrap[bootstrap / composition root] --> Presentation[presentation]
  Bootstrap --> Adapters[adapters]
+  Presentation --> Shell[app shell and route surfaces]
+  Shell --> Providers[session and theme providers]
  Presentation --> Application[application]
  Adapters --> Application
  Application --> Domain[domain]
@@ -16,8 +18,43 @@ flowchart LR
  Contracts --> Presentation
 ```

-Dependencies point inward. Presentation calls application use cases, adapters
-implement application ports, and only the composition root selects concrete
-adapters. Contract registries are the single named source for routes, API
-operations, environment values, storage keys, errors, queries, telemetry, and
-release tokens.
+The intended dependency rule points inward: presentation calls application use
+cases, adapters implement application ports, and only the composition root
+selects concrete adapters. Contract registries are the intended named source
+for routes, API operations, environment values, storage keys, errors, queries,
+telemetry, and release tokens. The platform review below records where the
+current runtime still bypasses that target or duplicates registry metadata.
+
+In ports-and-adapters terms, `presentation` is the current inbound adapter and
+`adapters` contains the current outbound implementations. The target design
+makes this role explicit, introduces application input ports, and prevents the
+React tree from receiving raw outbound dependencies:
+
+```mermaid
+flowchart LR
+  Driver[User, route, browser event] --> Inbound[React inbound adapter]
+  Inbound --> Input[Application input API]
+  Input --> UseCase[Use cases]
+  UseCase --> Output[Application output ports]
+  Output --> Outbound[HTTP, auth, storage, query, telemetry adapters]
+  Bootstrap2[Composition root] -. selects and injects .-> Input
+  Bootstrap2 -. selects and injects .-> Outbound
+```
+
+The current executable route tree is mounted only after runtime configuration
+and release-manifest coherence pass. It receives the composed query client,
+credential-opaque session port, storage port, telemetry port, and immutable
+build ID. Visible starter pages do not depend on the removable sample fixture.
+
+This describes the current starter composition, not the completed target. The
+capability review found that raw outbound capabilities still reach the React
+tree, the composed application facade is not yet its entry point, and several
+route, HTTP, recovery, telemetry, and sample-removal contracts are only
+partially connected. Use the following documents for the evidence and migration
+plan:
+
+- [Frontend platform capability review](./frontend-platform-capability-review.md)
+- [Frontend ports, adapters, and boundaries](./frontend-ports-adapters-and-boundaries.md)
+- [TypeScript, state, and data flow](./typescript-state-and-data-flow.md)
+- [Routing, pages, and patterns](./routing-pages-and-patterns.md)
+- [Frontend platform implementation roadmap](./frontend-platform-implementation-roadmap.md)
@@ -0,0 +1,492 @@
+# 라우팅, 페이지 템플릿, 재사용 패턴
+
+## 1. 목적
+
+이 문서는 도메인과 무관하게 다음을 바로 구현할 수 있는 기준을 제공한다.
+
+- typed route와 안전한 URL
+- session, permission, feature flag guard
+- lazy chunk의 loading/error/recovery
+- route 이동 시 focus, scroll, 취소, dirty form 처리
+- list, detail, form, status 등 공통 page template
+- page controller와 application input use case의 연결
+- 프론트엔드에서 반복 사용하는 설계 패턴
+
+## 2. 현재 상태와 문제
+
+현재 구현에는 다음 장점이 있다.
+
+- route registry가 path와 access policy를 소유한다.
+- route component를 lazy import한다.
+- 앱 셸과 보호 route, not-found surface가 있다.
+- route heading focus와 비동기/render error boundary가 있다.
+- redirect loop와 chunk recovery에 대한 policy 함수가 일부 존재한다.
+
+하지만 `src/contracts/routes.js`의 metadata와
+`src/presentation/routes/app-router.jsx`의 executable route tree가 별도 수동 목록이다.
+그 결과 다음 필드는 선언돼도 실제 행동을 보장하지 않는다.
+
+- params/search schema
+- loading/error surface
+- chunk ID
+- route title/navigation label
+- redirect loop guard
+- chunk recovery policy
+
+페이지도 공통 `PageHeader` 외에는 각자 section과 class를 직접 조립한다. 목록,
+상세, 편집, 오류 페이지의 반복되는 접근성·반응형·상태 표면을 기능 팀이 다시
+구현해야 한다.
+
+## 3. React Router mode 결정
+
+[React Router 공식 mode 설명](https://reactrouter.com/start/modes)과
+[Data Mode custom setup](https://reactrouter.com/start/data/custom)은
+Declarative, Data, Framework Mode를 구분한다.
+
+저장소에는 현재 React Router `7.18.1`이 고정돼 있다. 구현 브랜치는 공식 문서의
+동일 버전 API를 기준으로 하고 router version upgrade를 Data Mode 구조 변경과
+같은 브랜치에 섞지 않는다. 위 공식 링크의 기본 표시 버전이 바뀌면 version
+selector를 `7.18.1`로 맞춰 확인한다.
+
+| mode | 선택 조건 | 이 저장소에서의 판단 |
+| --- | --- | --- |
+| Declarative | React composition과 외부 data layer가 route data를 소유 | 현재 구현이 사용 중인 기준선 |
+| Data | route object, blocker, scroll restoration, pending/navigation state가 필요 | 목표 skeleton의 navigation lifecycle에 적합 |
+| Framework | route module, type-safe href, code splitting, SSR/static 전략을 framework가 소유 | client-only skeleton 기본값으로는 범위가 큼 |
+
+목표 결정:
+
+- client-only SPA와 TanStack Query/application use case를 유지한다.
+- 현재 `BrowserRouter` 기반 Declarative Mode에서 `createBrowserRouter`와
+  `RouterProvider` 기반 Data Mode로 이동한다.
+- Data Mode를 선택하는 이유는 route object, navigation blocker, scroll
+  restoration, route error 경계를 일관되게 소유하기 위해서다. loader/action으로
+  서버 상태를 다시 소유하기 위해서가 아니다.
+- loader/action을 추가할 때는 TanStack Query/application input을 prefetch하거나
+  호출하는 한 가지 소유 경로만 사용한다.
+- 같은 데이터를 route loader와 TanStack Query가 각각 가져오지 않는다.
+- SSR/static generation을 선택하기 전에는 Framework Mode를 기본값으로 만들지
+  않는다.
+
+전환 브랜치 전까지 현재 Declarative router에 새 custom scroll/blocker
+implementation을 추가하지 않는다. 전환할 수 없는 프로젝트만 별도 ADR과
+`NavigationLifecycleAdapter`를 구현한다.
+
+## 4. route 계약과 runtime map
+
+### 4.1 두 종류의 레지스트리
+
+직렬화 가능한 contract와 React implementation을 분리한다.
+
+```ts
+export const routeContracts = {
+  home: {
+    id: "home",
+    path: "/",
+    access: "public",
+    navigation: "primary",
+    titleKey: "route.home.title",
+    loadingSurface: "page",
+    errorSurface: "page",
+    chunkId: "home",
+  },
+  resourceDetail: {
+    id: "resourceDetail",
+    path: "/examples/resources/:resourceId",
+    access: "authenticated",
+    navigation: "hidden",
+    titleKey: "route.resourceDetail.title",
+    loadingSurface: "detail",
+    errorSurface: "detail",
+    chunkId: "reference-resource-detail",
+  },
+} as const satisfies RouteContractRegistry;
+```
+
+```tsx
+export const routeRuntime = {
+  home: {
+    Component: lazy(() => import("../pages/home-page")),
+    paramsCodec: emptyParamsCodec,
+    searchCodec: emptySearchCodec,
+  },
+  resourceDetail: {
+    Component: lazy(() => import("../features/resources/resource-detail-page")),
+    paramsCodec: resourceDetailParamsCodec,
+    searchCodec: resourceDetailSearchCodec,
+  },
+} satisfies Record<RouteId, RouteRuntime>;
+```
+
+요구 사항:
+
+- contract key와 `id`가 다르면 typecheck 실패
+- contract에는 함수, component, schema instance처럼 직렬화 불가능한 값을 넣지 않음
+- runtime map에는 실제 lazy component와 codec/guard만 둠
+- contract의 모든 route가 runtime에 있고 runtime의 모든 key가 contract에 있음
+- navigation은 contract에서 파생
+- build chunk manifest와 `chunkId` 대응을 검증
+- public runtime config나 server가 route component 이름을 임의 지정할 수 없음
+
+### 4.2 params와 search codec
+
+URL은 외부 입력이다. page에서 `useParams()` 결과를 cast하지 않는다.
+
+```ts
+const resourceDetailParamsSchema = z.object({
+  resourceId: z.string().trim().min(1).max(100),
+});
+
+const resourceListSearchSchema = z.object({
+  q: z.string().trim().max(100).catch(""),
+  page: z.coerce.number().int().min(1).catch(1),
+  sort: z.enum(["updated-desc", "name-asc"]).catch("updated-desc"),
+});
+```
+
+path params와 search params는 입력 형태와 serialization 규칙이 다르므로 같은
+interface로 뭉치지 않는다. 각각 parse와 serialize를 제공한다.
+
+```ts
+interface PathParamsCodec<T> {
+  parse(
+    input: Readonly<Record<string, string | undefined>>,
+  ): Result<T, RouteInputFailure>;
+  serialize(value: T): Readonly<Record<string, string>>;
+}
+
+interface SearchParamsCodec<T> {
+  parse(input: URLSearchParams): Result<T, RouteInputFailure>;
+  serialize(value: T): URLSearchParams;
+}
+```
+
+규칙:
+
+- route input parse 실패와 backend 404를 구분한다.
+- 알 수 없는 search key를 보존할지 제거할지 route별로 선언한다.
+- default value를 URL에 항상 쓸지 생략할지 codec이 결정한다.
+- array/date/boolean encoding을 feature마다 다르게 만들지 않는다.
+- navigation link도 codec 기반 builder를 사용한다.
+- query key에는 parsed value만 사용한다.
+- 검색어·식별자를 telemetry에 기록하기 전에 sensitivity policy를 적용한다.
+
+### 4.3 route object 생성
+
+하나의 factory가 다음을 조합한다.
+
+```text
+route contract
+  + runtime component/codecs
+  + access guard
+  + feature flag guard
+  + suspense surface
+  + render/chunk error surface
+  + title/focus/scroll behavior
+  -> executable route object/tree
+```
+
+JSX에서 route별 `<Route>`를 다시 나열하지 않는다. nested layout이 필요한 경우
+contract에 parent ID를 두고 cycle/orphan/duplicate path를 registry gate에서
+검사한다.
+
+## 5. guard와 권한
+
+### 5.1 guard 순서
+
+권장 순서:
+
+1. runtime/bootstrap readiness
+2. route 존재와 URL parse
+3. feature flag
+4. session readiness
+5. authentication
+6. coarse client permission hint
+7. route component
+8. server authorization result
+
+client guard는 UX 최적화일 뿐 보안 경계가 아니다. API/BFF가 항상 최종 권한을
+검사한다.
+
+### 5.2 guard 결과
+
+```ts
+type GuardDecision =
+  | { kind: "allow" }
+  | { kind: "redirect"; to: SafeLocation; reason: RedirectReason }
+  | { kind: "render"; surface: "auth-required" | "forbidden" | "not-found" };
+```
+
+- redirect에는 origin route와 bounded return URL을 사용한다.
+- 외부 redirect는 allowlist를 거친다.
+- 동일한 route 쌍을 반복하는 redirect loop를 차단한다.
+- session이 아직 resolving이면 forbidden으로 단정하지 않는다.
+- server가 403을 반환하면 client claim을 신뢰해 화면을 계속 보여 주지 않는다.
+
+## 6. navigation lifecycle
+
+### 6.1 loading
+
+loading surface를 route metadata에 연결한다.
+
+| surface | 사용 |
+| --- | --- |
+| shell | 초기 앱 셸 진입 |
+| page | 새로운 전체 페이지 |
+| collection | table/list 구조 유지 |
+| detail | metadata/content 구조 유지 |
+| form | 필드 layout 구조 유지 |
+| inline | 부분 action |
+
+cached data가 있으면 full-page skeleton으로 교체하지 않고 refreshing indicator를
+사용한다. `prefers-reduced-motion`에서 skeleton animation을 줄인다.
+
+### 6.2 error와 lazy chunk recovery
+
+route error boundary는 다음을 구분한다.
+
+- render/programmer error
+- dynamic import/chunk load error
+- application `AppFailure`
+- URL parse failure
+- not found
+
+chunk recovery 순서:
+
+1. 현재 build ID와 release manifest를 확인한다.
+2. 새 manifest가 확인되고 같은 build에 대해 reload하지 않았다면 한 번만 reload한다.
+3. 같은 failure가 반복되면 reload loop를 막는다.
+4. 안전한 support surface와 trace/build ID를 표시한다.
+5. recovery 결과를 redacted diagnostics에 기록한다.
+
+custom fallback을 넘겨 retry/reset 기능을 잃지 않게 한다. boundary는
+`location.key` 또는 route ID가 바뀌면 적절히 reset된다.
+
+### 6.3 focus와 scroll
+
+- route 성공 후 `main`의 page heading에 programmatic focus
+- mouse 사용자가 불필요한 focus ring을 보지 않게 할 수는 있지만 keyboard focus
+  indication을 전역으로 제거하지 않음
+- modal/drawer가 닫히면 opener에 focus 복원
+- backward/forward navigation은 저장한 scroll 복원
+- 새 primary route는 top으로 이동
+- hash target은 fixed header offset과 focus 가능 여부를 처리
+- screen reader용 route title/live announcement는 중복 발표를 피함
+
+### 6.4 취소와 dirty form
+
+- route 이동 시 진행 중 query signal을 취소한다.
+- mutation은 취소 안전성이 명확할 때만 취소한다.
+- dirty form blocker는 browser unload와 in-app navigation을 구분한다.
+- 성공 저장 후 blocker를 해제한 다음 이동한다.
+- autosave가 있는 form은 pending/failed 상태를 별도로 알린다.
+- confirm dialog는 공통 accessible primitive를 사용한다.
+
+## 7. 페이지 템플릿
+
+template은 데이터를 가져오거나 application을 호출하지 않는다. 슬롯, landmark,
+focus target, responsive layout, 상태 위치만 소유한다.
+
+### 7.1 `StandardPageTemplate`
+
+슬롯:
+
+- breadcrumb 또는 back link
+- title, description, status badge
+- primary/secondary actions
+- notices
+- content
+- contextual aside
+
+작은 화면에서 action wrapping 순서와 heading hierarchy를 보장한다.
+
+### 7.2 `CollectionPageTemplate`
+
+슬롯과 상태:
+
+- title/actions
+- search/filter/sort toolbar
+- active filter summary와 reset
+- result count
+- table/list/card view
+- pagination 또는 load-more
+- initial loading, refreshing, empty-first-use, empty-filtered, error
+- bulk selection/action
+
+URL이 filter, sort, page를 소유한다. template은 query 상태를 직접 읽지 않는다.
+
+### 7.3 `DetailPageTemplate`
+
+- breadcrumb/back
+- title/status/actions
+- summary metadata
+- main sections
+- related/context aside
+- loading/not-found/forbidden/error
+- destructive action confirmation 위치
+
+식별자가 바뀔 때 이전 entity 내용과 새 loading 상태를 혼동하지 않게 key/reset
+정책을 명시한다.
+
+### 7.4 `FormPageTemplate`
+
+- title/description
+- error summary
+- field groups
+- optional aside/help
+- sticky 또는 normal action bar
+- submit/cancel
+- submitting/saved/conflict/unavailable
+- dirty navigation confirmation
+
+template은 특정 form vendor를 import하지 않는다.
+
+### 7.5 `StatusPageTemplate`
+
+다음 변형을 제공한다.
+
+- unauthenticated
+- forbidden
+- not found
+- unavailable
+- offline
+- maintenance
+- unexpected
+
+각 변형은 heading, 짧은 설명, 안전한 primary/secondary action, 선택적 trace ID를
+갖는다. raw stack/response를 표시하지 않는다.
+
+### 7.6 선택 template
+
+다음은 project 필요가 있을 때 추가한다.
+
+- `SettingsPageTemplate`
+- `DashboardGridTemplate`
+- `SplitPaneTemplate`
+- `WizardTemplate`
+- `FullScreenTaskTemplate`
+
+## 8. page controller 패턴
+
+page를 세 부분으로 나눈다.
+
+```text
+route adapter
+  parses URL and guard context
+      ↓
+controller hook
+  invokes application query/mutation and maps UI events
+      ↓
+page view
+  renders template and design-system components
+```
+
+예:
+
+```tsx
+export function ResourceListRoute() {
+  const input = useRouteInput(resourceListRoute);
+  if (!input.ok) return <InvalidRouteSurface failure={input.error} />;
+
+  return <ResourceListController input={input.value} />;
+}
+
+function ResourceListController({ input }: ResourceListControllerProps) {
+  const controller = useResourceListController(input);
+  return <ResourceListPage controller={controller} />;
+}
+```
+
+route parse boundary와 controller component를 분리하므로 controller hook은
+조건부로 호출되지 않는다.
+
+controller가 소유하는 것:
+
+- parsed route input을 application input으로 변환
+- query/mutation state
+- pagination/filter/navigation event
+- retry/refresh/action callbacks
+- view model projection
+
+view가 소유하는 것:
+
+- semantic markup
+- template/component 조립
+- focus target
+- 사용자의 local-only interaction
+
+controller가 소유하지 않는 것:
+
+- HTTP URL 조립
+- credential
+- transport DTO parse
+- 도메인 invariant
+- raw vendor SDK
+
+## 9. 권장 패턴 카탈로그
+
+| 패턴 | 적용 위치 | 쓰는 이유 | 오용 |
+| --- | --- | --- | --- |
+| Ports and Adapters | application 외부 경계 | 정책과 기술 교체 분리 | 모든 작은 UI library에 port 생성 |
+| Command/Query | application input | 읽기/변경 의도와 정책 분리 | CQRS 인프라를 필요 없이 도입 |
+| Gateway | output port | 외부 데이터 capability 표현 | `get/post` 범용 HTTP를 application에 노출 |
+| Anti-Corruption Mapper | outbound feature adapter | DTO 변화가 core로 전파되지 않게 함 | 단순 object spread로 타입만 바꿈 |
+| Result | 예상 실패 | 실패 종류와 처리 경로를 닫음 | programmer error까지 모두 Result로 숨김 |
+| Controller/View | inbound React | data lifecycle과 markup 분리 | 거대한 hook 하나에 모든 feature 로직 집중 |
+| Strategy | retry/cache/auth recovery | 정책 교체와 테스트 가능성 | 설정 한 줄도 interface로 과도 추상화 |
+| Observer/External Store | session/theme/realtime | React 외부 소유 상태 구독 | server state를 다시 external store에 복제 |
+| State Machine | 복잡한 workflow | 유효 전이와 보상 명시 | 단순 modal open에 도입 |
+| Headless/Compound Component | 복합 UI | behavior와 style/slot 분리 | vendor primitive를 제품 전역에 직접 노출 |
+| Adapter Facade | icon/form/i18n vendor | React inbound 내부 vendor 교체 경계 | application port로 승격 |
+| Page Template | 반복 layout/state | 접근성과 반응형 구조 재사용 | data fetching을 template에 포함 |
+| Registry + Runtime Map | route/operation/event | 선언과 실행 완전성 | 모든 설정을 하나의 거대 전역 파일에 집중 |
+
+패턴은 추상화 파일만 만든 것으로 완료되지 않는다. reference usage, negative
+architecture test, 실패 상태 test가 있어야 제공된 패턴으로 본다.
+
+## 10. 새 route/page 추가 recipe
+
+1. feature public 경계와 route ID를 정한다.
+2. serializable route contract를 등록한다.
+3. params/search Zod schema와 bidirectional codec을 작성한다.
+4. safe URL builder를 export한다.
+5. lazy page module과 runtime map entry를 추가한다.
+6. session/permission/flag guard를 선언한다.
+7. 적절한 page template을 선택한다.
+8. controller hook을 application input API에 연결한다.
+9. loading, empty, refreshing, error, auth, forbidden, not-found를 결정한다.
+10. title/message key, focus, scroll, chunk ID를 연결한다.
+11. 다음 검증을 추가한다.
+    - contract/runtime map type completeness
+    - codec round-trip/property cases
+    - guard decision unit
+    - page component state
+    - query/mutation integration
+    - keyboard/focus/axe
+    - direct URL, back/forward, refresh E2E
+    - chunk failure recovery가 필요한 route의 E2E
+12. registry, type, architecture, component, integration, E2E gate를 실행한다.
+
+## 11. 금지 패턴
+
+- page 안에서 raw `fetch`, storage, auth SDK, telemetry SDK 호출
+- `useParams()`/`URLSearchParams` 값을 cast만 하고 사용
+- route contract와 JSX route tree를 각각 수동 관리
+- protected route를 server authorization 대체 수단으로 취급
+- 모든 실패를 redirect 또는 full-page error로 처리
+- query data가 있는데 background error 때문에 내용을 제거
+- chunk load error에서 제한 없는 `location.reload`
+- route heading focus outline을 CSS로 무조건 제거
+- template이 data fetching 또는 feature-specific copy를 소유
+- generic `BasePage` prop 하나에 모든 layout variation을 boolean으로 추가
+
+## 12. 완료 기준
+
+- 모든 route ID가 contract와 runtime map에서 compile-time 완전성을 가진다.
+- params/search parse와 URL serialize가 같은 codec을 사용한다.
+- route metadata가 loading/error/chunk/title/navigation 행동에 실제 연결된다.
+- redirect와 chunk reload loop가 차단된다.
+- route 이동 시 query 취소, focus, scroll, dirty policy가 검증된다.
+- collection/detail/form/status reference page가 template을 사용한다.
+- page view가 application input 외의 외부 capability를 직접 호출하지 않는다.
+- 새 route recipe와 테스트만으로 별도 라우터 내부 지식 없이 기능을 추가할 수 있다.
@@ -0,0 +1,77 @@
+# Starter experience contract
+
+The repository provides a runnable, domain-neutral application rather than
+only infrastructure contracts. The starter experience is intentionally
+replaceable at the page level while the shell, providers, boundaries,
+primitives, and state surfaces remain reusable.
+
+## Runtime composition
+
+```text
+validated config + coherent release manifest
+  -> concrete adapters
+  -> QueryClientProvider
+  -> BrowserRouter
+  -> ThemeProvider
+  -> SessionProvider
+  -> AppShell
+  -> lazy route boundary
+```
+
+Boot stops before product mount when configuration or release coherence fails.
+Each lazy page renders inside Suspense and a telemetry-aware route boundary.
+Route changes move focus to the new page heading; the skip link and landmarks
+remain stable in the shell.
+
+## Registered routes
+
+| ID | Path | Access | Surface |
+| --- | --- | --- | --- |
+| `APP_HOME` | `/` | public | readiness dashboard |
+| `EXAMPLES_UI` | `/examples/ui` | public | interactive primitives and tokens |
+| `EXAMPLES_STATES` | `/examples/states` | public | async and access state matrix |
+| `EXAMPLES_AUTH` | `/examples/auth` | public | session integration controls |
+| `SAMPLE_RESOURCE_LIST` | `/sample/resources` | integration-defined | protected integration seam |
+| `NOT_FOUND` | `*` | public | safe navigation recovery |
+
+Navigation labels and order come from `ROUTE_REGISTRY`; the sidebar does not
+maintain a second route list. The client access decision never claims to be
+authorization.
+
+## Authentication seam
+
+The session port exposes state subscription, sign-in start, sign-out,
+credential attachment, recovery, and unauthenticated notification. Credentials
+remain opaque to the application and presentation layers.
+
+- `demo`: local/development-only state transition with no credentials
+- `external`: delegates to `globalThis.__CA_FRONTEND_AUTH_OWNER__`
+- missing/invalid external owner: fails closed as `integration-failed`
+
+An external owner implements `readState`, `subscribe`, `beginSignIn`,
+`signOut`, `attachCredential`, `recoverSession`, and
+`notifyUnauthenticated`. It owns token acquisition and storage.
+
+## Extending the starter
+
+The steps below describe the current extension path. The platform review found
+that several route metadata fields and the composed application facade are not
+yet connected end to end. New platform work should follow
+[routing, page templates, and reusable patterns](./routing-pages-and-patterns.md)
+and the
+[TypeScript, state, and data-flow target](./typescript-state-and-data-flow.md)
+rather than adding another independent route or data-loading convention.
+
+1. Register the route path, access hint, title, chunk, loading surface, error
+   surface, and optional navigation metadata in `src/contracts/routes.js`.
+2. Add a lazy page in `src/presentation/` and render it through `RouteSurface`.
+3. Use application ports or use cases; do not import concrete adapters.
+4. Use the semantic tokens, UI primitives, and state surfaces before adding a
+   project-specific variant.
+5. Add component behavior, all-engine E2E, automated axe, and signed manual
+   route evidence.
+6. Run `test:sample-removal` to prove the visible starter still builds without
+   `src/sample/contract-fixture`.
+
+Theme preference is the public `COLOR_SCHEME` storage contract. Authentication
+tokens and other secrets remain forbidden storage keys.
@@ -0,0 +1,557 @@
+# TypeScript, 상태 소유권, 데이터 흐름
+
+## 1. 목적
+
+이 문서는 다음 질문에 대한 저장소 표준을 정의한다.
+
+- JavaScript를 어떤 순서로 TypeScript로 전환하는가.
+- local, URL, server, form, global, persisted 상태를 어디에 둬야 하는가.
+- React 화면이 application use case와 TanStack Query를 어떻게 사용해야 하는가.
+- HTTP, retry, auth, error, validation, logging의 책임을 어떻게 나누는가.
+- 새 query, mutation, form을 추가할 때 어떤 파일과 테스트가 필요한가.
+
+이 문서는 목표 설계다. 현재 구현 상태는
+[프론트엔드 플랫폼 역량 재검토](./frontend-platform-capability-review.md)를 따른다.
+
+## 2. TypeScript 전환 원칙
+
+### 2.1 왜 전환하는가
+
+현재 `strict + allowJs + checkJs`는 JavaScript 상태에서 유용한 안전망이다. 그러나
+JSDoc cast가 늘어나면 다음 계약을 정확히 닫기 어렵다.
+
+- `RouteId`, `OperationId`, `ErrorCode`, `StorageKey`, `TelemetryEvent`
+- `Result<T, E>`와 discriminated failure union
+- use case input/output와 gateway generic
+- route별 params/search type
+- query key tuple
+- component variant와 slot prop
+- runtime registry의 key와 executable implementation의 완전성
+
+TypeScript 전환 목적은 확장자 변경이 아니라 이 계약을 컴파일 단계에서
+검증하는 것이다.
+
+### 2.2 전환 전에 고칠 도구
+
+다음 변경이 첫 브랜치에서 완료되기 전에는 source rename을 시작하지 않는다.
+
+1. ESLint가 `js`, `jsx`, `mjs`, `ts`, `tsx`, `mts`를 모두 검사한다.
+2. React Hooks 규칙을 추가하고 TypeScript/ESLint parser와 JSX accessibility
+   도구는 설치된 compiler/linter의 공식 peer 범위 안에서 선택한다.
+3. dependency-cruiser의 extension과 resolver가 TS/TSX를 포함한다.
+4. `scripts/check-registries.mjs`가 TS/TSX를 검색한다.
+5. `config/contracts/registry-governance.json`의 경로 갱신 절차를 만든다.
+6. Vite, Vitest, Playwright, scripts, source, tests를 각각 typecheck한다.
+7. invalid type fixture가 TS migration 후에도 “실패해야 통과”하는지 확인한다.
+8. architecture/security/registry gate가 TS fixture 위반을 실제로 잡는 negative test를
+   추가한다.
+
+권장 project 구성:
+
+```text
+tsconfig.base.json
+tsconfig.app.json
+tsconfig.node.json
+tsconfig.test.json
+tsconfig.json          # project references only
+```
+
+`tsconfig.base.json`의 초기 핵심 옵션:
+
+```json
+{
+  "compilerOptions": {
+    "strict": true,
+    "noEmit": true,
+    "noUncheckedIndexedAccess": true,
+    "exactOptionalPropertyTypes": true,
+    "useUnknownInCatchVariables": true,
+    "noImplicitOverride": true,
+    "noFallthroughCasesInSwitch": true,
+    "verbatimModuleSyntax": true,
+    "isolatedModules": true
+  }
+}
+```
+
+실제 TypeScript 7/Vite 호환 옵션은 설치된 공식 문서와 빌드 결과를 기준으로
+확정한다. 옵션을 한꺼번에 켜서 수백 개 예외를 만들지 말고, 각 단계에서 새
+예외를 금지한다.
+
+현재 저장소의 VD-01 결정은
+[TypeScript 7과 ESLint 10의 점진적 전환 도구](./decisions/VD-01-typescript-lint-tooling.md)에
+기록돼 있다. app, Node scripts/config, tests는 각각 독립된 project로
+typecheck하며 JS에는 `checkJs`, TS에는 `strict`를 적용한다. TypeScript 7을
+아직 지원하지 않는 parser plugin을 강제 설치하지 않고 Babel parser는 lint
+syntax/import/security 검사, `tsc`는 type semantics를 소유한다.
+
+### 2.3 전환 순서
+
+| 단계 | 대상 | 이유 | 종료 조건 |
+| --- | --- | --- | --- |
+| 0 | lint/typecheck/scanner/architecture tooling | TS 코드가 검사를 우회하지 않게 함 | TS 위반 fixture가 각 게이트에서 실패 |
+| 1 | result, failure, ID, registry types | 이후 모든 계층의 언어가 됨 | stringly typed public ID 제거 |
+| 2 | application input/output ports와 use case | 중심 계약을 먼저 고정 | input/output compile fixture 통과 |
+| 3 | domain model과 mapper boundary | DTO와 core model 혼합 차단 | mapper contract test 통과 |
+| 4 | outbound adapters | 외부 `unknown`을 경계에서 좁힘 | HTTP/storage/auth failure type 통과 |
+| 5 | bootstrap/composition | 누락 dependency를 컴파일로 검출 | 실제 composition type test 통과 |
+| 6 | React providers/controllers/routes | typed application API 소비 | route/runtime map 완전성 검사 |
+| 7 | primitives/pages/templates | component API와 variant를 닫음 | stories/component tests typecheck |
+| 8 | tests/scripts/config | 우회 없는 전체 저장소 | source `allowJs` 제거 가능 |
+
+각 단계는 빌드 가능한 작은 커밋으로 유지한다. JavaScript와 TypeScript가 공존하는
+동안에는 [공식 JavaScript migration 가이드](https://www.typescriptlang.org/docs/handbook/migrating-from-javascript.html)의
+점진적 방식을 사용한다.
+
+### 2.4 기본 type 계약
+
+다음 형태를 core application에 둔다.
+
+```ts
+export type Ok<T> = Readonly<{ ok: true; value: T }>;
+export type Err<E> = Readonly<{ ok: false; error: E }>;
+export type Result<T, E> = Ok<T> | Err<E>;
+
+export type AppFailure =
+  | Readonly<{ kind: "unauthenticated"; code: "AUTH_REQUIRED"; traceId?: string }>
+  | Readonly<{ kind: "forbidden"; code: "FORBIDDEN"; traceId?: string }>
+  | Readonly<{ kind: "not-found"; code: "NOT_FOUND"; traceId?: string }>
+  | Readonly<{ kind: "conflict"; code: "CONFLICT"; traceId?: string }>
+  | Readonly<{
+      kind: "validation";
+      code: "VALIDATION_FAILED";
+      fields: Readonly<Record<string, readonly string[]>>;
+      traceId?: string;
+    }>
+  | Readonly<{ kind: "rate-limited"; code: "RATE_LIMITED"; retryAt?: Date }>
+  | Readonly<{ kind: "unavailable"; code: "UNAVAILABLE"; retryable: boolean }>
+  | Readonly<{ kind: "unexpected"; code: "UNEXPECTED"; traceId?: string }>;
+```
+
+원칙:
+
+- adapter에서 받은 `unknown`은 adapter 경계에서 parse한다.
+- application은 `Response`, `AxiosError`, Zod 내부 오류 같은 vendor type을
+  노출하지 않는다.
+- UI copy는 failure에 저장하지 않고 message key mapper에서 결정한다.
+- 예상 가능한 실패는 `Result`; programmer bug와 render crash는 error boundary로
+  보낸다.
+- `as`, non-null assertion, `any`는 경계에서 근거가 있을 때만 사용하고 lint
+  예외에 사유를 기록한다.
+
+## 3. 상태 소유권
+
+### 3.1 상태 분류표
+
+상태를 만들기 전에 아래 순서로 소유자를 결정한다.
+
+| 질문 | 상태 종류 | 기본 도구 | 저장 위치 |
+| --- | --- | --- | --- |
+| 한 컴포넌트 상호작용에만 필요한가 | local UI | `useState`, `useReducer` | component/controller |
+| URL로 공유·복원되어야 하는가 | navigation | router params/search + codec | URL |
+| 서버가 진실의 원천인가 | server state | TanStack Query inbound adapter | Query cache |
+| 입력 중이고 제출 전인가 | form | local form facade | form controller |
+| 앱 전체에서 낮은 빈도로 바뀌는가 | cross-cutting | Context 또는 typed external store | provider/store |
+| 여러 feature의 복잡한 workflow인가 | client workflow | reducer, Zustand, Redux Toolkit, state machine | feature-owned store |
+| 새로고침 후 남아야 하는가 | persisted preference | `StoragePort` | versioned browser storage |
+| 인증 credential인가 | auth secret | external auth owner | SDK memory 또는 HttpOnly cookie |
+
+금지:
+
+- server response를 global client store에 복사하지 않는다.
+- URL에 있어야 할 filter/sort/page를 숨은 store에만 두지 않는다.
+- component 내부에 머물 수 있는 modal open 상태를 전역화하지 않는다.
+- access token을 localStorage, sessionStorage, 일반 Redux/Zustand store에 넣지
+  않는다.
+- 모든 상태를 추상화하는 범용 `StorePort`를 만들지 않는다.
+
+### 3.2 범용 store 선택 기준
+
+기본 skeleton에는 빈 Zustand/Redux store를 만들지 않는다. 실제 요구가 생기면
+다음 기준을 적용한다.
+
+| 조건 | 권장 |
+| --- | --- |
+| feature 한 곳의 단순 shared client state | feature reducer 또는 작은 Zustand store |
+| 여러 팀이 action/state 규약, devtools, middleware, audit를 공유 | Redux Toolkit |
+| 명시적 상태 전이, 병렬 상태, 취소/보상 workflow | state machine |
+| session/theme처럼 저빈도 cross-cutting | `useSyncExternalStore` 또는 Context |
+
+vendor를 선택하더라도 feature 외부에는 hook/facade만 export한다. 제품 코드가
+store instance의 `getState`와 `setState`를 임의 호출하지 않게 한다.
+
+### 3.3 persistence
+
+persisted state는 다음 metadata를 가져야 한다.
+
+```ts
+type PersistedRecord<T> = Readonly<{
+  version: number;
+  writtenAt: string;
+  value: T;
+}>;
+```
+
+- key는 typed registry가 소유한다.
+- read 시 schema parse와 migration을 거친다.
+- quota, unavailable, corrupt, version mismatch를 구분한다.
+- 민감정보와 credential을 저장하지 않는다.
+- server state persistence와 offline mutation queue는 별도 project-selected
+  adapter다.
+
+## 4. 표준 데이터 호출 경로
+
+```mermaid
+sequenceDiagram
+  actor User
+  participant Page as React page
+  participant Controller as inbound query/mutation controller
+  participant App as application input use case
+  participant Gateway as output gateway
+  participant Adapter as HTTP/generated client adapter
+  participant API as Backend/BFF
+
+  User->>Page: route or event
+  Page->>Controller: typed input
+  Controller->>App: query/command + AbortSignal
+  App->>Gateway: capability request
+  Gateway->>Adapter: DTO request
+  Adapter->>API: path/query/body/auth
+  API-->>Adapter: envelope or failure
+  Adapter-->>Gateway: parsed DTO Result
+  Gateway-->>App: mapped model Result
+  App-->>Controller: view data or AppFailure
+  Controller-->>Page: query/mutation state
+```
+
+페이지는 controller hook이 제공하는 상태만 렌더링한다. controller는 React,
+TanStack Query와 application input interface를 알 수 있지만 use case의 concrete
+구현과 outbound adapter는 모른다.
+
+### 4.1 Application API
+
+```ts
+export interface Application {
+  readonly resources: {
+    list(
+      input: ListResourcesInput,
+      context: Readonly<{ signal: AbortSignal }>,
+    ): Promise<Result<readonly ResourceSummary[], AppFailure>>;
+    create(
+      command: CreateResourceCommand,
+      context?: Readonly<{ signal?: AbortSignal }>,
+    ): Promise<Result<Resource, AppFailure>>;
+  };
+}
+```
+
+`ApplicationProvider`는 이 API를 immutable value로 제공한다. controller 외의
+presentation 코드에서 raw HTTP/storage/telemetry port를 가져오는 hook은 만들지
+않는다. theme, locale 같은 UI platform provider는 별도다.
+
+### 4.2 query adapter
+
+```ts
+export function useResourcesQuery(input: ListResourcesInput) {
+  const application = useApplication();
+
+  return useQuery({
+    queryKey: resourceKeys.list(input),
+    queryFn: async ({ signal }) =>
+      unwrapResult(await application.resources.list(input, { signal })),
+    retry: false,
+    staleTime: resourceQueryPolicy.list.staleTime,
+  });
+}
+```
+
+실제 구현 규칙:
+
+- query key는 readonly tuple factory로만 만든다.
+- key에 들어간 filter는 실제 gateway request에도 동일하게 투영한다.
+- `AbortSignal`을 application과 HTTP transport까지 전달한다.
+- HTTP 계층이 bounded retry를 소유하면 query retry는 끈다.
+- background error와 initial error의 UI를 구분한다.
+- placeholder와 cached stale data가 있을 때 전체 화면 error로 교체하지 않는다.
+- `select`는 view-only projection에 쓰고 도메인 규칙을 넣지 않는다.
+- query hook은 feature public API에서 export한다.
+
+### 4.3 mutation adapter
+
+```ts
+export function useCreateResourceMutation() {
+  const application = useApplication();
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (command: CreateResourceCommand) =>
+      application.resources.create(command).then(unwrapResult),
+    onSuccess: () =>
+      queryClient.invalidateQueries({ queryKey: resourceKeys.all }),
+  });
+}
+```
+
+기본 mutation은 navigation만으로 취소됐다고 가정하지 않는다. 서버 작업의 취소가
+안전한 operation만 controller가 보관한 `AbortController`와 명시적 cancel action을
+사용한다. idempotency key는 UI 입력으로 받지 않고 application use case가
+`IdGeneratorPort`로 만들며, 같은 논리 요청의 bounded HTTP retry와 auth replay는
+동일한 key를 재사용한다.
+
+실제 구현에서는 mutation마다 다음을 명시한다.
+
+- double-submit 방지와 idempotency key 소유자
+- cancel 가능 여부
+- optimistic update 적용 여부와 rollback snapshot
+- 성공 후 invalidate/update/navigation 순서
+- 409 conflict와 422 field validation mapping
+- offline 시 queue할지 즉시 실패할지
+- analytics/telemetry event와 redaction
+
+optimistic update는 기본값이 아니다. 서버 규칙을 확실히 재현할 수 있고 rollback이
+안전한 mutation에만 사용한다.
+
+## 5. HTTP client 책임
+
+### 5.1 목표 파이프라인
+
+```text
+operation registry
+  -> path/search/body builder
+  -> credential attachment
+  -> timeout and external cancellation
+  -> bounded retry
+  -> fetch transport
+  -> status/envelope decoder
+  -> response schema decoder
+  -> feature DTO mapper
+  -> AppFailure mapper
+```
+
+각 단계의 입력과 출력은 typed result다. feature-specific model mapper를 공통 HTTP
+client 안에 넣지 않는다.
+
+### 5.2 request projection
+
+operation definition은 최소 다음 계약을 갖는다.
+
+```ts
+type OperationDefinition<
+  TPath,
+  TSearch,
+  TBody,
+  TResponse,
+> = Readonly<{
+  id: OperationId;
+  method: HttpMethod;
+  pathTemplate: string;
+  pathSchema: Schema<TPath>;
+  searchSchema: Schema<TSearch>;
+  bodySchema: Schema<TBody>;
+  responseSchema: Schema<TResponse>;
+  timeoutMs?: number;
+  retryClass: "never" | "safe" | "idempotency-keyed";
+}>;
+```
+
+규칙:
+
+- path segment는 `encodeURIComponent`에 해당하는 안전한 builder를 통과한다.
+- query의 array/null/undefined/boolean/date serialization을 한 곳에서 정의한다.
+- Zod parse 결과의 trim/default/coercion을 실제 request에 사용한다.
+- GET/HEAD에는 body를 보내지 않는다.
+- JSON content type은 body가 있을 때만 붙인다.
+- base URL과 path를 문자열 덧붙이기로 조립하지 않는다.
+- external URL은 별도 allowlist policy를 거친다.
+
+### 5.3 timeout, cancellation, retry
+
+소유권:
+
+- 사용자 navigation/unmount 취소: query/controller가 signal 생성
+- operation timeout: HTTP adapter
+- retry: HTTP adapter 또는 query adapter 중 하나
+- 인증 복구 후 단 한 번 replay: auth decorator
+- mutation idempotency: application/controller가 key 생성, operation이 허용 여부 선언
+
+retry 조건:
+
+- safe method 또는 idempotency key가 있는 허용 operation만 대상
+- timeout, network, 명시된 429/5xx만 정책 대상
+- validation, auth denial, forbidden, not found, conflict는 자동 재시도하지 않음
+- `Retry-After`와 bounded exponential backoff/jitter 지원
+- tab hidden/offline 상태를 고려
+- 최대 횟수와 전체 elapsed budget을 함께 제한
+- 각 attempt와 final failure를 redacted telemetry로 기록
+
+timer와 event listener는 성공, 실패, validation 조기 반환, external abort 모든
+경로에서 정리되어야 한다.
+
+## 6. 인증과 token 소유권
+
+기본 skeleton은 token manager를 제공하지 않는다.
+
+지원 profile:
+
+| profile | credential 소유자 | frontend 역할 |
+| --- | --- | --- |
+| BFF/HttpOnly cookie | browser cookie + backend | `credentials`, CSRF 정책, session probe |
+| external OIDC/Auth SDK | SDK memory/cache | attach/recover/login/logout를 auth adapter로 감쌈 |
+| SPA memory token | auth adapter memory | 프로젝트가 명시적으로 선택할 때만 |
+
+공통 `AuthSessionReader`와 HTTP 전용 `CredentialProvider`를 분리한다.
+
+```ts
+interface AuthSessionReader {
+  getSnapshot(): SessionSnapshot;
+  subscribe(listener: () => void): () => void;
+}
+
+interface CredentialProvider {
+  attach(request: RequestInit): Promise<RequestInit>;
+  recover(failure: AuthFailure): Promise<"recovered" | "not-recovered">;
+}
+```
+
+UI는 credential을 읽지 않는다. HTTP adapter는 UI session action을 호출하지
+않는다. logout/login/redirect는 application input 또는 auth UI facade를 통해
+실행한다.
+
+## 7. 오류, 검증, logging
+
+### 7.1 검증 계층
+
+| 경계 | 책임 | 예 |
+| --- | --- | --- |
+| runtime config | 앱을 안전하게 시작할 수 있는가 | URL, timeout, auth mode |
+| route codec | URL을 typed input으로 읽고 쓸 수 있는가 | page, sort, ID |
+| transport DTO | 외부 응답/요청 형식이 계약과 맞는가 | envelope, date string |
+| form | 사용자가 수정 가능한 입력 형태가 유효한가 | required, length, format |
+| application | use case precondition이 맞는가 | command 조합 |
+| domain | 항상 지켜야 할 불변식인가 | valid state transition |
+
+같은 Zod schema를 무조건 모든 계층에서 재사용하지 않는다. transport DTO, form
+value, application command, domain model이 우연히 같은 모양이어도 소유권과
+변경 이유가 다르다. 필요한 경우 mapper로 연결한다.
+
+### 7.2 사용자 오류 표면
+
+`AppFailure`를 다음 UI 상태로 매핑한다.
+
+| failure | 기본 표면 | 자동 행동 |
+| --- | --- | --- |
+| unauthenticated | auth required 또는 login transition | auth policy에 따른 1회 복구 |
+| forbidden | 권한 없음 | 없음 |
+| not-found | route/detail not-found | 없음 |
+| validation | error summary + field errors | 첫 오류 focus |
+| conflict | 현재 데이터 유지 + conflict action | 자동 overwrite 금지 |
+| rate-limited | inline retry time | 허용된 query만 지연 재시도 |
+| unavailable | cached data 또는 retry surface | policy 범위 내 retry |
+| unexpected | safe generic copy + trace ID | diagnostics emit |
+
+raw response body, stack, token, URL query, PII를 사용자 copy나 일반 log에 노출하지
+않는다.
+
+### 7.3 diagnostics와 telemetry
+
+현재 telemetry event contract와 별도로 개발·진단용 structured logger가 필요하다.
+다음 두 설계 중 하나를 ADR로 결정한다.
+
+1. `DiagnosticsPort`가 log/event/span을 내부 method로 구분
+2. `LoggerPort`와 `TelemetryPort`를 분리
+
+공통 요구:
+
+- log level과 event key는 닫힌 union
+- attribute allowlist와 중앙 redaction
+- dev adapter는 console을 사용하되 동일 redaction 적용
+- production adapter는 provider SDK를 감싸며 앱 코드는 SDK를 import하지 않음
+- 오류 객체 전체를 그대로 serialize하지 않음
+- trace ID/build ID/route ID/operation ID를 허용된 범위에서 연결
+- logging failure가 제품 flow를 실패시키지 않음
+- consent가 필요한 analytics와 essential diagnostics를 분리
+
+## 8. 폼 표준
+
+form vendor는 React Hook Form 또는 TanStack Form 등을 평가하되 local facade 뒤에
+둔다. vendor 선택과 무관하게 다음 API를 제공한다.
+
+- `Form`
+- `FormField`
+- `Label`
+- `Description`
+- `FieldError`
+- `ErrorSummary`
+- `useAppForm`
+- `mapValidationFailureToFields`
+- `useDirtyNavigationGuard`
+
+필수 동작:
+
+1. label, description, error를 stable ID와 `aria-describedby`로 연결
+2. submit 시 error summary와 첫 오류 focus
+3. submitting 중 중복 제출 방지
+4. 422 응답의 알려진 field만 표시하고 나머지는 form-level failure로 처리
+5. 409 conflict는 validation error로 위장하지 않음
+6. 취소와 route 이탈 시 dirty policy 적용
+7. form value → application command mapper를 별도 함수로 둠
+8. browser autofill, IME composition, paste, password manager를 방해하지 않음
+9. loading skeleton으로 사용자의 입력을 덮지 않음
+10. form schema와 server contract mismatch를 integration test로 검증
+
+## 9. 새 query 추가 recipe
+
+1. feature-owned input type과 application query use case를 추가한다.
+2. 필요한 output gateway를 `ports/out`에 추가한다.
+3. transport DTO schema와 mapper를 outbound feature adapter에 추가한다.
+4. operation registry에 path/search/response/retry class를 등록한다.
+5. readonly tuple query key factory를 추가한다.
+6. inbound query controller hook을 추가한다.
+7. page template에서 loading/empty/error/refreshing/success를 렌더링한다.
+8. 다음 테스트를 추가한다.
+   - use case unit
+   - DTO mapper/schema contract
+   - path/search projection
+   - MSW success/empty/401/403/429/500/schema mismatch
+   - cancellation과 retry ownership
+   - component state
+   - route E2E
+9. registry, type, architecture, unit, integration, E2E gate를 실행한다.
+
+금지:
+
+- page에서 `fetch`
+- page에서 raw QueryClient
+- cache key와 request filter의 별도 수동 조립
+- response DTO를 domain/application model로 사용
+- initial loading과 background refreshing을 같은 full-page skeleton으로 표시
+
+## 10. 새 mutation/form 추가 recipe
+
+1. form value schema와 application command type을 분리한다.
+2. value → command mapper를 작성한다.
+3. input command use case와 output gateway method를 추가한다.
+4. operation의 idempotency/retry 정책을 선언한다.
+5. mutation controller에 invalidation/update/rollback 순서를 작성한다.
+6. `FormPageTemplate`과 공통 field primitive로 화면을 구성한다.
+7. 422, 409, unauthenticated, unavailable, abort를 각각 처리한다.
+8. dirty navigation과 double-submit을 검증한다.
+9. 다음 테스트를 추가한다.
+   - form schema와 mapper unit
+   - keyboard/label/error summary component
+   - MSW success/422/409/network-lost
+   - optimistic rollback을 쓰는 경우 cache snapshot
+   - 브라우저 navigation blocker와 성공 후 이동
+
+## 11. 완료 기준
+
+- TS/TSX가 lint, type, architecture, registry, security 검사를 우회하지 않는다.
+- source와 test가 strict typecheck된다.
+- UI는 application input API만 호출한다.
+- reference query와 mutation이 TanStack adapter를 통해 동작한다.
+- retry 책임이 단일 계층에 있고 cancellation/timeout과 충돌하지 않는다.
+- path/search/parsed body가 실제 전송값과 일치한다.
+- 상태 종류별 소유권이 테스트와 문서에서 확인된다.
+- token은 UI와 일반 storage/store에 노출되지 않는다.
+- failure와 validation의 각 계층이 typed mapper로 분리된다.
+- query/mutation/form recipe만으로 새 기능을 만들 수 있다.
@@ -30,6 +30,11 @@ registry: merge evidence through the PR decision, coherent release evidence
 through the next release promotion, drill evidence through the next production
 promotion, and field evidence through aggregation.

+Browser-backed merge gates install and execute the pinned Chromium, Firefox,
+and WebKit engines. This makes route behavior, reflow, native dialog semantics,
+theme persistence, and automated accessibility a cross-engine contract rather
+than a Chromium-only smoke check.
+
 Repository variables required by higher tiers:

 - `HOSTING_BASE_URL` for live header verification
@@ -0,0 +1,868 @@
+# 디자인 시스템 플랫폼 계약
+
+이 문서는 도메인 기능을 추가하기 전에 프론트엔드 스켈레톤이 제공해야 하는
+디자인 시스템의 소유권, 계층, 기본 구성요소, 외부 라이브러리 경계, 검증 방법을
+정의한다. 목표는 특정 제품의 시각 언어를 미리 결정하는 것이 아니라, 제품 팀이
+접근성·반응형·국제화·테스트 규칙을 다시 발명하지 않고 기능 화면을 만들 수 있게
+하는 것이다.
+
+이 문서에서 `필수`는 모든 제품이 기반으로 사용할 계약을 뜻한다. `선택`은
+컴포넌트의 경계와 도입 기준은 제공하지만 실제 의존성이나 구현은 제품 요구가
+생긴 뒤 추가해도 되는 항목을 뜻한다.
+
+## 1. 현재 기준선과 확인된 공백
+
+현재 저장소에는 다음 기반이 이미 있다.
+
+- `src/presentation/styles/theme.css`
+  - 의미 기반 light/dark 색상 토큰
+  - focus indicator
+  - 반응형 앱 셸
+  - reduced-motion 처리
+- `src/presentation/providers/theme-provider.jsx`
+  - `system`, `light`, `dark` 선호도
+  - 저장소 포트를 통한 선호도 영속화
+  - 운영체제 색상 변경 구독
+- `src/presentation/components/ui/`
+  - `Button`
+  - `TextField`
+  - `Card`
+  - `Alert`
+  - `Badge`
+  - `Dialog`
+- `src/presentation/components/async-surface.jsx`
+  - 초기 로딩, 빈 화면, terminal error, background 상태
+- `src/presentation/components/state-surfaces.jsx`
+  - 인증 필요, 권한 없음, 찾을 수 없음
+- `/examples/ui`, `/examples/states`
+  - 실행 가능한 primitive와 상태 예제
+- component/E2E/axe 테스트
+  - 필드 설명과 오류 연결
+  - native dialog 닫기와 trigger focus 복원
+  - 320px reflow
+  - Chromium, Firefox, WebKit
+  - 등록 라우트의 자동 접근성 검사
+
+이 기반은 유효하지만 아직 디자인 시스템 플랫폼 전체는 아니다.
+
+1. 토큰이 색상 중심이며 typography, elevation, motion, z-layer, control size,
+   breakpoint가 계약으로 닫혀 있지 않다.
+2. 공통 입력은 `TextField` 하나뿐이어서 일반적인 폼을 공통 규칙으로 만들 수
+   없다.
+3. 앱 셸과 예제 화면에서 공용 primitive 대신 raw `button`, `select`, 링크
+   class를 다시 작성하는 곳이 있다.
+4. `☰`, `×` 같은 문자 glyph를 직접 사용하며 아이콘 공급자 경계가 없다.
+5. `theme.css` 하나가 token, layout, primitive, pattern 스타일을 모두 소유한다.
+6. runtime gallery는 있지만 격리된 story, interaction story, 시각 회귀 기준선이
+   없다.
+7. 사용자 문구가 한국어 literal로 고정되어 locale과 RTL 계약이 없다.
+8. `StandardPage`, `CollectionPage`, `DetailPage`, `FormPage` 같은 공통 페이지
+   템플릿이 없다.
+9. 모바일 sidebar는 표시 전환은 되지만 modal drawer 수준의 focus 이동, focus
+   복원, 배경 비활성화 계약은 없다.
+
+따라서 기존 구성요소는 폐기하지 않고 아래 목표 계층으로 이동·확장한다.
+
+## 2. 소유권과 의존성 원칙
+
+디자인 시스템은 `presentation` 계층이 소유한다. 색상, 아이콘, 키보드 상호작용,
+포커스, 화면 배치와 같은 문제는 도메인 규칙이 아니다.
+
+```text
+product page
+  -> template
+  -> pattern
+  -> primitive
+  -> token
+```
+
+외부 UI 라이브러리를 사용하는 경우 흐름은 다음과 같다.
+
+```text
+product page
+  -> local design-system API
+  -> local vendor facade
+  -> Lucide / React Aria / Radix
+```
+
+다음 규칙은 필수다.
+
+- 제품 페이지는 `lucide-react`, `react-aria-components`, `@radix-ui/*`를 직접
+  import하지 않는다.
+- 외부 UI 라이브러리 type을 공용 컴포넌트 API로 그대로 노출하지 않는다.
+- 도메인과 application 계층은 React component, CSS class, icon name을 알지
+  않는다.
+- primitive는 API 요청, query cache, 인증 상태와 같은 외부 상태를 직접 읽지
+  않는다.
+- pattern과 template도 application use case를 직접 선택하지 않는다. 필요한
+  상태와 command callback을 props/slot으로 받는다.
+- 제품별 색상이나 명칭을 primitive 내부에 하드코딩하지 않는다.
+- 같은 의미의 접근성·키보드 동작을 페이지마다 다시 구현하지 않는다.
+- 세 번째 사용 사례가 확인되기 전에는 제품 전용 조합을 무리하게 primitive로
+  승격하지 않는다.
+
+아이콘과 headless UI는 React inbound adapter의 vendor facade로 충분하다.
+이들을 위한 application port를 만들지 않는다. HTTP, storage, telemetry처럼
+런타임 외부 자원을 교체하는 capability와 UI 구현 라이브러리를 구분한다.
+
+## 3. 목표 디렉터리
+
+TypeScript 전환 이후의 목표 구조는 다음과 같다. 마이그레이션 중에는 기존
+경로에서 같은 소유권 규칙을 지키고, 한 번에 전체 경로를 이동하지 않아도 된다.
+
+```text
+src/adapters/inbound/react/design-system/
+  index.ts
+  tokens/
+    primitive.css
+    semantic.css
+    component.css
+    token-contract.ts
+  primitives/
+    button/
+    field/
+    checkbox/
+    dialog/
+    ...
+  patterns/
+    async-surface/
+    form/
+    data-table/
+    confirmation/
+    ...
+  templates/
+    standard-page/
+    collection-page/
+    detail-page/
+    form-page/
+    status-page/
+  icons/
+    icon.tsx
+    icon-button.tsx
+    semantic-icons.tsx
+    vendors/
+      lucide.tsx
+  vendors/
+    react-aria/
+  testing/
+    story-decorators.tsx
+    render-design-system.tsx
+```
+
+`index.ts`는 제품의 React inbound 코드가 사용할 public API다. 내부 파일 deep
+import는 디자인 시스템 자체와 테스트에만 허용한다. 이 경계는 ESLint의
+`no-restricted-imports`로 검사한다.
+
+현재 `src/presentation`은 React inbound adapter 역할을 한다. TypeScript
+마이그레이션 동안 기존 경로를 유지할 수 있지만, 최종 canonical target은 위
+경로다. 같은 컴포넌트를 `presentation`과 `adapters/inbound/react` 양쪽에
+복제하지 않고 feature 단위로 이동한다.
+
+## 4. 계층 계약
+
+### 4.1 Tokens
+
+토큰은 시각적 결정을 이름으로 표현한다. 토큰은 세 계층으로 관리한다.
+
+```text
+primitive token -> semantic token -> component token
+```
+
+예:
+
+```css
+--palette-blue-600: ...;
+--color-action: var(--palette-blue-600);
+--button-primary-background: var(--color-action);
+```
+
+#### Primitive tokens
+
+원시 palette와 scale이다. 제품 코드에서 직접 소비하지 않는다.
+
+- palette
+- spacing scale
+- font size와 line height scale
+- radius scale
+- shadow scale
+- duration과 easing scale
+- fixed size scale
+
+#### Semantic tokens
+
+제품 코드와 대부분의 primitive가 소비하는 이름이다.
+
+- `surface`, `surface-muted`, `surface-elevated`
+- `content`, `content-muted`, `content-inverse`
+- `border`, `border-strong`
+- `action`, `action-hover`, `action-pressed`
+- `danger`, `warning`, `success`, `info`
+- `focus-ring`
+- `disabled-content`, `disabled-surface`
+
+#### Component tokens
+
+특정 primitive가 여러 semantic token을 조합할 때만 사용한다.
+
+- `button-primary-background`
+- `field-border-invalid`
+- `dialog-elevation`
+- `navigation-active-background`
+
+컴포넌트 토큰은 제품별 variant를 만들기 위한 우회 경로가 아니다. 두 개 이상의
+컴포넌트가 같은 의미를 공유한다면 semantic token으로 승격한다.
+
+#### 필수 토큰 범주
+
+| 범주 | 필수 내용 |
+| --- | --- |
+| Color | surface/content/border/action/status/focus, light/dark |
+| Typography | family, size, line-height, weight, letter-spacing |
+| Spacing | inset, inline, stack, section, page spacing scale |
+| Size | control height, icon size, touch target, container width |
+| Border | width, style, semantic border |
+| Radius | control, surface, modal, full |
+| Elevation | panel, popover, dialog, sticky shell |
+| Z-layer | base, sticky, navigation, popover, modal, toast |
+| Motion | fast/normal/slow duration, standard/emphasized easing |
+| Breakpoint | compact, medium, wide와 container 계약 |
+| Opacity | disabled, scrim, skeleton |
+
+토큰의 완료 조건은 다음과 같다.
+
+- light와 dark에서 모든 semantic token이 정의된다.
+- `forced-colors`에서도 focus와 control 경계가 사라지지 않는다.
+- 상태는 색상만으로 구분하지 않는다.
+- 같은 raw value가 반복되면 named token으로 승격한다.
+- 사용자 입력으로 CSS class나 CSS variable 이름을 조립하지 않는다.
+- token contract test가 필수 token의 누락을 차단한다.
+- chart나 canvas처럼 JavaScript 값이 필요한 경우에만 typed token accessor를
+  제공한다.
+
+## 5. 기본 컴포넌트 카탈로그
+
+### 5.1 Primitives
+
+Primitive는 하나의 접근 가능한 상호작용 또는 작은 시각 단위를 제공한다.
+
+| 그룹 | 기본 제공 | 우선순위 | 핵심 계약 |
+| --- | --- | --- | --- |
+| Action | `Button` | 필수 | intent, size, disabled, pending, native semantics |
+| Action | `LinkButton` | 필수 | navigation은 anchor/router link semantics 유지 |
+| Action | `IconButton` | 필수 | accessible name 필수, 44px 권장 target |
+| Form | `Field` | 필수 | label, description, error ID 조립 |
+| Form | `TextField` | 필수 | text/email/password/search/autocomplete |
+| Form | `TextArea` | 필수 | resize와 글자 수 안내 |
+| Form | `Select` | 필수 | native 우선, 복합 선택은 headless 구현 |
+| Form | `Checkbox` | 필수 | checked/indeterminate |
+| Form | `RadioGroup` | 필수 | arrow-key와 group label |
+| Form | `Switch` | 필수 | boolean setting 전용 |
+| Form | `SearchField` | 필수 | clear action, submit semantics |
+| Feedback | `Alert` | 필수 | inline feedback와 live-region 정책 분리 |
+| Feedback | `Badge` | 필수 | color-only 금지 |
+| Feedback | `Spinner` | 필수 | accessible label 또는 decorative |
+| Feedback | `ProgressBar` | 필수 | determinate/indeterminate |
+| Feedback | `Skeleton` | 필수 | 실제 layout과 유사한 크기, reduced motion |
+| Feedback | `Toast` | 필수 | queue, 중복 방지, timeout pause |
+| Surface | `Card` | 필수 | heading level 강제 금지, label 선택 가능 |
+| Surface | `Separator` | 필수 | decorative/semantic 구분 |
+| Overlay | `Dialog` | 필수 | modal semantics, focus trap/restore, Escape |
+| Overlay | `Drawer` | 필수 | compact navigation과 side sheet |
+| Overlay | `Popover` | 필수 | anchor, dismiss, collision |
+| Overlay | `Tooltip` | 필수 | hover와 keyboard, 중요한 정보 단독 보유 금지 |
+| Overlay | `Menu` | 필수 | roving focus, typeahead, Escape |
+| Navigation | `Breadcrumbs` | 필수 | 현재 위치와 overflow |
+| Navigation | `Tabs` | 필수 | manual/automatic activation 정책 |
+| Navigation | `Pagination` | 필수 | current page, previous/next label |
+| Utility | `VisuallyHidden` | 필수 | screen-reader-only content |
+| Utility | `Portal` | 필수 | overlay root와 SSR-safe fallback |
+| Utility | `FocusRing` | 필수 | input modality 인식 |
+| Advanced | date/time picker | 선택 | locale/time zone 요구가 있을 때 |
+| Advanced | file upload/dropzone | 선택 | upload adapter 요구가 있을 때 |
+| Advanced | virtualizer/tree | 선택 | 실제 데이터 규모가 입증될 때 |
+
+Primitive API는 다음 규칙을 지킨다.
+
+- 기본 HTML semantics를 보존한다.
+- `div onClick`로 button이나 link를 흉내 내지 않는다.
+- `variant`, `size`, `tone`은 closed union과 정적 class map을 사용한다.
+- pending은 focus를 잃게 하는 무조건적인 `disabled`와 구분한다.
+- controlled와 uncontrolled 지원 여부를 문서화한다.
+- ref 전달과 focus contract를 테스트한다.
+- `className`은 escape hatch이지 public variant를 대체하지 않는다.
+- 임의의 polymorphic `as`보다 `Button`과 `LinkButton`처럼 semantics가 명확한
+  API를 우선한다.
+- visual-only prop이 도메인 의미를 표현하지 않도록 한다.
+
+### 5.2 Patterns
+
+Pattern은 여러 primitive를 조합해 반복되는 사용자 문제를 해결한다.
+
+| Pattern | 필수 내용 |
+| --- | --- |
+| `AsyncSurface` | loading, success, empty, terminal error, stale, refresh |
+| `AccessSurface` | auth required, forbidden, not found |
+| `Form` | submit, error summary, first-invalid focus, pending |
+| `ConfirmationDialog` | destructive action 설명과 명시적 확인 |
+| `ToastRegion` | queue, announcement, dismiss, focus policy |
+| `SearchFilterToolbar` | search, filter, reset, result count |
+| `DataTable` | caption, sorting, selection, responsive fallback |
+| `PaginationBar` | result range와 page navigation |
+| `NavigationDrawer` | mobile focus scope와 background inert |
+| `DisclosureGroup` | help/settings section |
+
+Pattern은 application failure object 전체를 렌더링하지 않는다. 안전한 message key,
+사용자 action, 표시 가능한 metadata만 받는다.
+
+### 5.3 Templates
+
+Template은 페이지 레이아웃과 상태 slot을 제공한다. API 호출과 도메인 use case는
+소유하지 않는다.
+
+#### `StandardPageTemplate`
+
+- breadcrumb 또는 back navigation
+- eyebrow
+- `h1`
+- description
+- status/metadata
+- primary/secondary actions
+- main content와 aside slot
+
+#### `CollectionPageTemplate`
+
+- page header
+- search/filter/sort toolbar
+- result count
+- loading/empty/error slot
+- table/list/card-grid slot
+- pagination slot
+- compact viewport에서의 대체 배치
+
+#### `DetailPageTemplate`
+
+- breadcrumb/back
+- title과 entity status
+- page actions
+- description list/section slot
+- loading/not-found/forbidden/error 상태
+
+#### `FormPageTemplate`
+
+- heading과 설명
+- error summary
+- field section
+- sticky 또는 inline action bar
+- submit/cancel
+- submitting, success, conflict
+- unsaved-change navigation blocker 연결 지점
+
+#### `StatusPageTemplate`
+
+- 401, 403, 404, 500, offline, maintenance
+- safe description
+- primary recovery action
+- optional support reference
+- raw endpoint, stack, token 노출 금지
+
+Template의 heading 순서는 slot 소비자가 임의로 깨뜨리지 못하게 예제와 테스트로
+고정한다. 다만 `Card` 같은 하위 primitive가 무조건 `h3`를 생성해서도 안 된다.
+
+## 6. Lucide 아이콘 facade
+
+[Lucide for React 공식 문서](https://lucide.dev/guide/react)는 각 아이콘을 독립
+React component로 제공하며 명시적으로 import한 아이콘만 번들에 포함될 수 있는
+tree-shaking 구조를 제공한다. 기본 아이콘 공급자로 사용하기에 적합하지만 제품
+코드가 공급자 API에 결합되면 안 된다.
+
+### 6.1 필수 규칙
+
+1. `lucide-react` import는 `icons/vendors/lucide.tsx`에서만 허용한다.
+2. 제품 코드에는 Lucide component type, icon name, stroke prop을 노출하지 않는다.
+3. 디자인 시스템이 승인한 작은 아이콘 집합만 명시적으로 import한다.
+4. 모든 아이콘을 이름으로 동적 import하는 범용 `DynamicIcon`은 기본 제공하지
+   않는다.
+5. 아이콘 색은 기본적으로 `currentColor`를 사용한다.
+6. 크기와 stroke는 `--icon-size-*`, `--icon-stroke-*` 토큰을 사용한다.
+7. 장식 아이콘은 기본적으로 `aria-hidden="true"`와 `focusable="false"`다.
+8. 정보를 단독으로 전달하는 아이콘은 local `Icon` API의 `label`을 통해
+   `role="img"`와 accessible name을 가진다.
+9. 버튼 안의 아이콘은 장식으로 처리하고 버튼 자체에 visible label 또는
+   `aria-label`을 둔다.
+10. 상태를 아이콘이나 색상 하나만으로 전달하지 않는다.
+
+### 6.2 목표 API 예시
+
+아래 예시는 방향을 설명한다. 실제 type과 경로는 TypeScript 전환 작업에서
+확정한다.
+
+```tsx
+import { MenuIcon } from "@/presentation/design-system/icons";
+import { IconButton } from "@/presentation/design-system";
+
+<IconButton accessibleName="메뉴 열기" onPress={openNavigation}>
+  <MenuIcon />
+</IconButton>
+```
+
+vendor 파일은 의미 이름과 공급자 이름을 분리한다.
+
+```tsx
+import {
+  Menu as LucideMenu,
+  X as LucideClose,
+  AlertTriangle as LucideWarning,
+} from "lucide-react";
+
+export const MenuGlyph = LucideMenu;
+export const CloseGlyph = LucideClose;
+export const WarningGlyph = LucideWarning;
+```
+
+`MenuGlyph` 같은 vendor export는 `semantic-icons.tsx` 밖으로 다시 노출하지
+않는다. 제품 코드는 `MenuIcon`, `CloseIcon`, `WarningIcon`만 사용한다.
+
+### 6.3 아이콘 추가 완료 조건
+
+- 기존 semantic icon으로 표현할 수 없는지 먼저 확인했다.
+- 서로 다른 제품 기능이 같은 의미 아이콘을 공유한다.
+- accessible name과 decorative 여부를 결정했다.
+- light/dark/high-contrast에서 보인다.
+- 200% zoom과 compact viewport에서 잘리지 않는다.
+- 신규 import 후 bundle budget을 통과한다.
+- 공급자 교체 시 제품 코드 수정이 필요하지 않다.
+
+## 7. Headless UI 선택 기준
+
+복잡한 overlay, collection, focus management를 직접 구현하기 전에 native
+platform과 검증된 headless UI를 평가한다.
+
+- [React Aria 공식 시작 문서](https://react-aria.adobe.com/getting-started)
+- [Radix Primitives 공식 소개](https://www.radix-ui.com/primitives/docs/overview/introduction)
+
+### 7.1 선택 순서
+
+1. native HTML만으로 요구 semantics와 모든 지원 브라우저 동작을 충족하는지
+   확인한다.
+2. native 구현이 불충분하면 React Aria와 Radix를 평가한다.
+3. 한 프로젝트에서 같은 문제를 해결하는 headless 공급자를 둘 이상 기본값으로
+   사용하지 않는다.
+4. 선택 결과와 버전·라이선스·bundle 영향을 ADR에 기록한다.
+5. 공급자 component를 local primitive로 감싼 뒤에만 제품 코드에 노출한다.
+
+### 7.2 평가표
+
+| 기준 | 확인 질문 |
+| --- | --- |
+| Semantics | WAI-ARIA pattern과 native semantics를 올바르게 사용하는가 |
+| Keyboard | roving focus, typeahead, Escape, arrow key가 완전한가 |
+| Focus | trap, restore, initial focus, nested overlay가 안전한가 |
+| Input modality | mouse, touch, keyboard, screen reader가 동일하게 동작하는가 |
+| i18n | RTL, locale number/date, IME를 지원하는가 |
+| Styling | semantic token과 Tailwind/CSS layer에 결합 가능한가 |
+| Bundle | component 단위 import와 tree shaking이 가능한가 |
+| React/Vite | 현재 React와 Vite 조합을 공식 지원하는가 |
+| SSR | future SSR profile에서 hydration ID가 안정적인가 |
+| Testing | 접근성·상호작용 테스트 자료와 utility가 있는가 |
+| Maintenance | release cadence, security 대응, license가 허용 가능한가 |
+
+현재 스켈레톤의 접근성·국제화 목표에는 React Aria Components가 우선 후보다.
+Radix는 overlay와 primitive composition을 중심으로 평가할 수 있다. 최종 선택은
+실제 prototype으로 `Select`, `Menu`, `Drawer` 세 가지를 구현해 다음을 비교한 뒤
+확정한다.
+
+- keyboard matrix
+- screen reader announcement
+- RTL
+- mobile touch
+- dark/high-contrast
+- gzip 증가량
+- local API로 감쌀 때 필요한 코드량
+
+공급자를 선택하더라도 `SelectProps = AriaSelectProps`처럼 vendor type alias를
+그대로 공용 API로 만들지 않는다. 제품이 실제로 지원하는 의미만 local prop으로
+닫는다.
+
+## 8. 접근성 계약
+
+목표는 WCAG 2.2 AA에 맞춘 기본 동작이다. 자동 도구 통과는 적합성 선언이 아니며,
+키보드와 보조기술 검토를 함께 수행한다.
+
+### 8.1 모든 컴포넌트의 공통 기준
+
+- 올바른 native element와 role을 사용한다.
+- visible label 또는 accessible name이 있다.
+- keyboard만으로 모든 action을 실행할 수 있다.
+- focus 순서가 DOM과 시각 순서에 맞는다.
+- focus indicator를 제거하지 않는다.
+- disabled와 readonly를 구분한다.
+- 상태는 색상만으로 전달하지 않는다.
+- 오류는 해당 control과 programmatically 연결한다.
+- 필요한 변경만 live region으로 한 번 알린다.
+- `prefers-reduced-motion`에서 불필요한 motion을 제거한다.
+- 200% text zoom과 400% page zoom에서 정보가 손실되지 않는다.
+- 320 CSS px reflow에서 양방향 scroll을 강요하지 않는다.
+- touch target은 기본 44x44 CSS px를 목표로 한다.
+- forced-colors에서 border, focus, selected state가 사라지지 않는다.
+- RTL에서 logical direction과 key behavior를 검증한다.
+- 한글·일본어·중국어 IME composition 중 입력을 조기에 검증하거나 제출하지
+  않는다.
+
+### 8.2 Overlay 기준
+
+- 열기 trigger를 기록한다.
+- 열릴 때 의미 있는 initial focus를 둔다.
+- modal일 때 focus가 내부를 벗어나지 않는다.
+- 배경 content를 `inert` 또는 동등한 방식으로 비활성화한다.
+- Escape와 명시적 닫기 action을 제공한다.
+- 닫은 뒤 trigger 또는 안전한 대체 위치로 focus를 복원한다.
+- nested overlay와 route transition 중 orphan portal을 남기지 않는다.
+
+### 8.3 Form 기준
+
+- label, description, error가 동일한 field ID 체계로 연결된다.
+- required는 시각적 기호와 programmatic 상태를 함께 가진다.
+- submit 실패 시 error summary로 focus를 이동한다.
+- error summary 항목은 해당 field로 이동한다.
+- async validation은 현재 입력보다 오래된 결과를 폐기한다.
+- pending 상태를 screen reader에 알리되 같은 문구를 반복하지 않는다.
+- 서버 오류의 raw body, stack, 내부 field path를 출력하지 않는다.
+
+## 9. 국제화 계약
+
+디자인 시스템 primitive는 한국어 문구를 내부 기본값으로 숨기지 않는다.
+접근성 label이나 오류 문구가 필요하면 명시적인 prop 또는 message key를 받는다.
+
+필수 국제화 기반:
+
+- `LocaleProvider`
+- typed message key
+- fallback locale
+- `<html lang>`과 `dir` 갱신
+- `Intl.DateTimeFormat`
+- `Intl.NumberFormat`
+- `Intl.ListFormat`
+- plural/select message
+- locale별 validation message
+- pseudo-locale
+- RTL story와 E2E smoke
+
+금지 패턴:
+
+- 번역 문장 중간에 JSX 문자열을 연결한다.
+- 날짜를 `substring`이나 고정 구분자로 조립한다.
+- icon direction을 locale 확인 없이 좌/우 이름으로 고정한다.
+- route title, navigation label, toast message를 JSX literal로 분산한다.
+- 번역 누락 시 빈 문자열을 렌더링한다.
+
+Storybook toolbar에서 최소한 다음 조합을 전환할 수 있어야 한다.
+
+- `ko-KR`, light
+- `en-US`, light
+- `en-US`, dark
+- pseudo-locale
+- 대표 RTL locale
+
+## 10. Storybook과 시각 검증
+
+현재 `/examples/ui`는 실행 중인 앱 셸과 primitive 통합을 확인하는 데 유지한다.
+그러나 runtime gallery는 isolated component workshop을 대체하지 않는다.
+
+[Storybook 공식 UI 테스트 문서](https://storybook.js.org/docs/writing-tests)는
+story를 기반으로 interaction, accessibility, visual test를 구성하는 방법을
+제공한다.
+
+### 10.1 Storybook 필수 구성
+
+- Vite 기반 Storybook
+- TypeScript CSF story
+- global theme toolbar
+- locale/RTL toolbar
+- compact/wide viewport
+- Router, Theme, Locale, Session, Query decorator
+- `@storybook/addon-a11y`
+- a11y 결과를 CI에서 error로 처리
+- interaction `play` test
+- story build gate
+
+### 10.2 각 컴포넌트의 필수 story
+
+- default
+- 모든 semantic variant
+- disabled와 readonly
+- pending/loading
+- 오류
+- 긴 문구
+- 빈 값
+- light/dark
+- compact viewport
+- keyboard interaction
+- 해당되는 경우 open/closed, controlled/uncontrolled
+
+Form과 overlay는 다음 story를 추가한다.
+
+- submit 실패와 error summary
+- async pending
+- server field error
+- Escape close
+- outside interaction
+- initial focus
+- focus restoration
+- nested content와 long content
+
+### 10.3 시각 회귀
+
+기본 시각 회귀는 Playwright `toHaveScreenshot()`을 사용해 저장소 안에서 실행할
+수 있게 한다. Chromatic 같은 외부 서비스는 선택 사항이다.
+
+필수 안정화:
+
+- 동일한 Linux image, browser version, font
+- animation과 caret 비활성화
+- 시간·랜덤·network 응답 고정
+- 동적 ID와 민감 데이터 mask
+- light/dark baseline
+- compact/wide baseline
+- 변경된 baseline은 코드 리뷰 대상
+
+failure screenshot은 시각 회귀가 아니다. 의도된 baseline과 실제 렌더링을
+비교하는 assertion이 있어야 한다.
+
+### 10.4 테스트 계층
+
+| 계층 | 검증 대상 |
+| --- | --- |
+| Type check | prop union, ref, event와 slot type |
+| Unit | token/variant map, pure formatter와 state reducer |
+| Component | native semantics, keyboard, focus, callback |
+| Story interaction | 실제 browser의 isolated behavior |
+| Story a11y | 모든 주요 state의 axe |
+| Visual | pixel/layout/theme regression |
+| E2E | 앱 셸, route, form/query integration |
+| Manual | screen reader, zoom, touch, forced-colors |
+
+DOM snapshot은 보이는 UI를 보장하지 않으므로 public markup contract가 꼭 필요한
+경우에만 사용한다.
+
+## 11. 컴포넌트 추가 Recipe
+
+새 component를 추가할 때 다음 순서를 생략하지 않는다.
+
+### Step 1. 문제와 계층을 결정한다
+
+다음 질문을 issue 또는 설계 메모에 기록한다.
+
+- 단일 control인가, 반복되는 조합인가, 페이지 구조인가?
+- primitive, pattern, template 중 어디에 속하는가?
+- 기존 component의 variant로 해결할 수 있는가?
+- 제품 전용 의미를 공통 디자인 시스템으로 잘못 올리는 것은 아닌가?
+- native HTML로 충분한가?
+
+### Step 2. 상태 행렬을 작성한다
+
+최소 상태:
+
+```text
+default
+hover
+focus-visible
+active/pressed
+disabled
+pending
+invalid
+light
+dark
+compact
+long-content
+```
+
+선택/overlay component는 open, selected, indeterminate, empty, loading도 포함한다.
+
+### Step 3. 접근성 명세를 작성한다
+
+- element/role
+- accessible name
+- keyboard table
+- focus entry/exit/restore
+- announcement
+- error association
+- reduced motion
+- touch와 screen reader
+
+명세가 불명확하면 구현보다 먼저 native, React Aria, Radix prototype으로 검증한다.
+
+### Step 4. API를 닫는다
+
+- TypeScript public props를 정의한다.
+- semantic `variant`를 사용하고 raw color prop을 노출하지 않는다.
+- callback 이름과 payload를 domain-neutral하게 정한다.
+- controlled/uncontrolled 정책을 정한다.
+- `className` escape hatch의 범위를 정한다.
+- vendor prop과 type을 public API에 노출하지 않는다.
+
+### Step 5. 필요한 토큰을 추가한다
+
+- 기존 semantic token으로 표현 가능한지 확인한다.
+- raw 값 반복을 추가하지 않는다.
+- light/dark/forced-colors 값을 함께 정의한다.
+- token contract test를 갱신한다.
+
+### Step 6. 구현한다
+
+- native semantics 우선
+- local vendor facade만 import
+- static variant map
+- ref/focus 지원
+- DOM 구조 최소화
+- render 중 전역 상태 변경 금지
+- 제품 API나 application service import 금지
+
+### Step 7. Story를 작성한다
+
+- 상태 행렬을 모두 story로 표현한다.
+- interaction test를 작성한다.
+- dark, compact, long-content를 포함한다.
+- a11y test를 error mode로 실행한다.
+
+### Step 8. 자동 테스트를 작성한다
+
+- role/name 중심 query
+- keyboard와 focus
+- disabled/pending
+- callback
+- controlled state
+- 오류와 live region
+- 필요한 visual baseline
+
+구현 class나 내부 DOM 순서만 확인하는 brittle test는 피한다.
+
+### Step 9. 통합 예제를 추가한다
+
+- `/examples/ui`에는 primitive를 추가한다.
+- `/examples/states`에는 새로운 공통 상태를 추가한다.
+- pattern/template은 domain-neutral fixture로 실제 조합을 보여 준다.
+- production profile에서 예제 route를 제외할 수 있는 계약을 유지한다.
+
+### Step 10. 문서와 public export를 갱신한다
+
+- 사용 목적
+- 사용하지 말아야 할 경우
+- props와 variant
+- keyboard
+- 접근성 책임
+- i18n
+- 예제
+- public `index.ts` export
+- 변경 로그
+
+### Step 11. 게이트를 실행한다
+
+최소 실행 범위:
+
+```bash
+corepack pnpm check:types
+corepack pnpm lint
+corepack pnpm check:architecture
+corepack pnpm test:component
+corepack pnpm test:e2e
+corepack pnpm test:a11y
+corepack pnpm build
+corepack pnpm check:bundle
+```
+
+Storybook과 visual gate가 도입된 뒤에는 story build, interaction, story a11y,
+visual comparison도 필수로 추가한다.
+
+## 12. Definition of Done
+
+컴포넌트는 아래 항목 중 자신의 state/capability matrix에 해당하는 항목을
+충족해야 `완료`다. 적용되지 않는 항목은 체크를 생략하지 말고 `N/A`와 이유를
+component contract에 기록한다. 예를 들어 `Separator`에는 pending/error/IME가,
+읽기 전용 `Card`에는 controlled state와 field error가 적용되지 않는다.
+
+### API와 아키텍처
+
+- [ ] primitive/pattern/template 소유권이 명확하다.
+- [ ] public TypeScript API가 closed union으로 정의되었다.
+- [ ] 제품 코드가 vendor package를 직접 import하지 않는다.
+- [ ] domain/application dependency가 없다.
+- [ ] public barrel을 통해 소비할 수 있다.
+- [ ] 상태를 소유하는 경우 controlled/uncontrolled 계약이 문서화되었고, focus
+      target이 있는 경우 ref 계약이 문서화되었다.
+
+### Styling
+
+- [ ] raw 색상과 반복되는 임의 값이 없다.
+- [ ] semantic token을 사용한다.
+- [ ] light/dark가 완성되었다.
+- [ ] compact/wide reflow가 된다.
+- [ ] long text와 번역 확장을 견딘다.
+- [ ] forced-colors에서도 의미가 유지된다.
+- [ ] bundle budget을 통과한다.
+
+### 접근성
+
+- [ ] native semantics와 accessible name이 있다.
+- [ ] keyboard 동작이 명세와 일치한다.
+- [ ] focus indicator, 이동, 복원이 올바르다.
+- [ ] 상태가 색상에만 의존하지 않는다.
+- [ ] 오류나 설명을 제공하는 component는 이들을 programmatically 연결한다.
+- [ ] reduced-motion을 존중한다.
+- [ ] 200%/400% zoom과 320px reflow를 확인했다.
+- [ ] screen reader 수동 검토 항목이 정의되었다.
+
+### 국제화
+
+- [ ] 사용자 문구를 소유하는 component는 이를 내부 literal로 고정하지 않는다.
+- [ ] 날짜·숫자·목록을 표시하는 component는 locale formatter를 사용한다.
+- [ ] pseudo-locale에서 잘리지 않는다.
+- [ ] RTL에서 배치와 키보드가 올바르다.
+- [ ] 문자 입력을 받는 component는 IME 입력을 깨뜨리지 않는다.
+
+### 테스트와 문서
+
+- [ ] component behavior test가 있다.
+- [ ] 모든 주요 상태 story가 있다.
+- [ ] story interaction test가 있다.
+- [ ] automated a11y가 통과한다.
+- [ ] 필요한 visual baseline이 있다.
+- [ ] runtime gallery 또는 pattern fixture가 있다.
+- [ ] 사용법, 금지 사례, 접근성 책임이 문서화되었다.
+- [ ] 전체 품질·아키텍처·bundle gate가 통과한다.
+
+## 13. 금지 패턴
+
+- 제품 페이지에서 `lucide-react` 직접 import
+- 제품 페이지에서 React Aria/Radix 직접 import
+- `div`와 keyboard handler로 native button을 재구현
+- icon-only button에 accessible name 누락
+- 문자열 icon name으로 전체 icon package를 동적 로딩
+- 사용자 값으로 Tailwind/CSS class 조립
+- raw hex/OKLCH 값을 JSX나 component CSS에 반복
+- `as="div"`처럼 semantics를 무제한 변경하는 public API
+- primitive에서 API/query/auth/storage를 직접 호출
+- 모든 상태를 하나의 전역 store에 저장
+- 오류 raw body, URL, header, token, stack 표시
+- locale 문장을 문자열 덧셈으로 구성
+- axe 통과만으로 접근성 완료 선언
+- failure screenshot만으로 시각 회귀 완료 선언
+- Storybook story 없이 runtime gallery 하나로 모든 variant를 대표
+
+## 14. 단계별 도입 순서
+
+1. TypeScript public API와 디자인 시스템 public barrel을 만든다.
+2. token을 primitive/semantic/component 계층으로 분리한다.
+3. 기존 Button, TextField, Card, Alert, Badge, Dialog를 새 계약으로 이동한다.
+4. Lucide local facade와 `IconButton`을 추가하고 문자 glyph를 제거한다.
+5. Field foundation과 필수 form primitives를 추가한다.
+6. React Aria와 Radix prototype을 비교하고 headless ADR을 확정한다.
+7. Drawer, Select, Menu, Popover, Tooltip을 local facade로 구현한다.
+8. pattern과 page template을 추가한다.
+9. locale provider, pseudo-locale, RTL 검증을 추가한다.
+10. Storybook, story a11y, interaction test를 추가한다.
+11. pinned browser 환경의 visual regression gate를 추가한다.
+12. `/examples/ui`와 `/examples/states`를 통합 smoke gallery로 유지한다.
+
+이 순서는 라이브러리 수를 늘리는 것이 목표가 아니다. 각 단계가 제품 개발자가
+중복 구현할 문제를 하나씩 제거하고, 외부 공급자를 교체할 수 있는 로컬 계약과
+검증 증거를 남기는 것이 목표다.
@@ -1,8 +1,32 @@
 # Design-token styling contract

 `src/presentation/styles/theme.css` is the styling SSOT. Components consume
-semantic color, spacing, typography, and radius tokens through static Tailwind
-classes.
+semantic color, spacing, typography, status, and radius tokens through static
+classes. `/examples/ui` is the executable token and primitive gallery.
+
+## Theme contract
+
+The supported public preference is the closed set `system`, `light`, and
+`dark`. `ThemeProvider` reads and writes `COLOR_SCHEME` through the application
+storage port; it does not access a raw storage key. `system` subscribes to
+`prefers-color-scheme` changes. Bootstrap applies the persisted preference
+before React paints.
+
+Components use semantic tokens such as `--color-panel`, `--color-content`,
+`--color-border`, `--color-action`, and status surface/content/border triples.
+They must not hard-code a light-only panel or text color. Both light and dark
+surfaces are included in automated axe checks.
+
+## Included primitives
+
+- `Button`: primary, secondary, danger, and ghost intent
+- `TextField`: label, help text, required state, and associated validation error
+- `Card`: labelled surface with optional footer
+- `Alert` and `Badge`: non-color-only status feedback
+- `Dialog`: native modal semantics, Escape/backdrop close, and trigger focus
+  restoration
+- async and access state surfaces: loading, refresh, empty, terminal error,
+  auth required, forbidden, and not found

 Arbitrary-value policy:

@@ -13,5 +37,12 @@ Arbitrary-value policy:
 - user-controlled or runtime-composed class strings are forbidden
 - class variants must be selected from a closed static map

-The removable sample may demonstrate tokens, but product modules must not
-import from `src/sample/contract-fixture`.
+The removable sample may demonstrate tokens, but production starter modules do
+not import from `src/sample/contract-fixture`.
+
+This file documents the currently implemented token and primitive baseline.
+The [design-system platform contract](./design-system-platform.md) defines the
+target token layers, component catalog, local Lucide/headless-library
+facades, page patterns, accessibility and internationalization rules, isolated
+workshop, and component-authoring recipe. Items in that target document are not
+treated as implemented until their acceptance tests pass.
@@ -12,6 +12,13 @@ Each gate is blocking in its declared scope. Failures are not downgraded with
 | end-to-end | `pnpm test:e2e` | `artifacts/tests/e2e/` |
 | accessibility | `pnpm test:a11y` | `artifacts/tests/a11y.json` |

+End-to-end and automated accessibility scenarios run on the pinned Chromium,
+Firefox, and WebKit engines. The responsive contract explicitly exercises
+320px reflow, a mobile navigation drawer, and a wide two-column gallery.
+Theme scenarios verify persistence, operating-system changes, and dark-surface
+axe results. Native modal focus and validation association are exercised in
+both component and browser tests.
+
 A control is verified only when a positive fixture passes and its deliberately
 failing negative fixture is rejected. Generated evidence is retained by CI;
 the repository tracks only the evidence directory structure.
@@ -22,3 +29,10 @@ Promotion is an AND graph:
 2. merge gates plus release gates
 3. release gates plus rollback/runbook drills
 4. production promotion plus eligible field Web Vitals evidence
+
+This file describes the currently registered taxonomy. The
+[frontend platform testing strategy](./frontend-platform-testing-strategy.md)
+documents the target additions: test TypeScript projects, real bootstrap
+composition tests, shared MSW scenarios, query/mutation/form/router coverage,
+Storybook interaction and accessibility checks, visual regression, and a
+built-output Playwright profile.
@@ -1,6 +1,10 @@
+import babelParser from "@babel/eslint-parser";
 import eslint from "@eslint/js";
+import reactHooks from "eslint-plugin-react-hooks";
 import globals from "globals";

+const sourceExtensions = "{js,jsx,mjs,ts,tsx,mts}";
+
 const layerPatterns = {
  domain: [
    "**/application/**",
@@ -27,6 +31,38 @@ function restrictedImports(patterns) {
  return ["error", { patterns }];
 }

+const commonLanguageOptions = {
+  ecmaVersion: "latest",
+  sourceType: "module",
+  globals: {
+    ...globals.browser,
+    ...globals.node,
+  },
+};
+
+const commonSecurityRules = {
+  "no-eval": "error",
+  "no-new-func": "error",
+  "no-script-url": "error",
+  "no-restricted-syntax": [
+    "error",
+    {
+      selector: "JSXAttribute[name.name='dangerouslySetInnerHTML']",
+      message: "Raw HTML injection is prohibited by FE-OC-019.",
+    },
+    {
+      selector:
+        "CallExpression[callee.object.name='document'][callee.property.name='createElement'][arguments.0.value='script']",
+      message: "Runtime script construction is prohibited by FE-OC-019.",
+    },
+  ],
+};
+
+const hookRules = {
+  "react-hooks/rules-of-hooks": "error",
+  "react-hooks/exhaustive-deps": "error",
+};
+
 export default [
  {
    ignores: [
@@ -40,47 +76,103 @@ export default [
  },
  eslint.configs.recommended,
  {
-    files: ["**/*.{js,jsx,mjs}"],
+    files: [`**/*.${sourceExtensions}`],
    languageOptions: {
-      ecmaVersion: "latest",
-      sourceType: "module",
-      globals: {
-        ...globals.browser,
-        ...globals.node,
-      },
+      ...commonLanguageOptions,
      parserOptions: {
        ecmaFeatures: { jsx: true },
      },
    },
+    plugins: {
+      "react-hooks": reactHooks,
+    },
+    rules: {
+      ...commonSecurityRules,
+      ...hookRules,
+    },
  },
  {
-    files: ["src/domain/**/*.{js,jsx}"],
+    files: ["**/*.{ts,mts}"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            ["@babel/plugin-syntax-typescript", { isTSX: false }],
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
+  {
+    files: ["**/*.tsx"],
+    languageOptions: {
+      ...commonLanguageOptions,
+      parser: babelParser,
+      parserOptions: {
+        requireConfigFile: false,
+        babelOptions: {
+          plugins: [
+            [
+              "@babel/plugin-syntax-typescript",
+              { allExtensions: true, isTSX: true },
+            ],
+            "@babel/plugin-syntax-jsx",
+          ],
+        },
+      },
+    },
+    rules: {
+      "no-undef": "off",
+      "no-unused-vars": "off",
+    },
+  },
+  {
+    files: [`src/domain/**/*.${sourceExtensions}`],
    rules: {
      "no-restricted-imports": restrictedImports(layerPatterns.domain),
-      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
    },
  },
  {
-    files: ["src/application/**/*.{js,jsx}"],
+    files: [`src/application/**/*.${sourceExtensions}`],
    rules: {
      "no-restricted-imports": restrictedImports(layerPatterns.application),
-      "no-restricted-globals": ["error", "window", "document", "localStorage", "fetch"],
+      "no-restricted-globals": [
+        "error",
+        "window",
+        "document",
+        "localStorage",
+        "fetch",
+      ],
    },
  },
  {
-    files: ["src/presentation/**/*.{js,jsx}"],
+    files: [`src/presentation/**/*.${sourceExtensions}`],
    rules: {
      "no-restricted-imports": restrictedImports(layerPatterns.presentation),
    },
  },
  {
-    files: ["src/adapters/**/*.{js,jsx}"],
+    files: [`src/adapters/**/*.${sourceExtensions}`],
    rules: {
      "no-restricted-imports": restrictedImports(layerPatterns.adapters),
    },
  },
  {
-    files: ["tests/**/*.{js,jsx}"],
+    files: [`tests/**/*.${sourceExtensions}`],
    languageOptions: {
      globals: {
        ...globals.browser,
@@ -89,7 +181,9 @@ export default [
    },
  },
  {
-    files: ["tests/fixtures/architecture/forbidden/**/*.{js,jsx}"],
+    files: [
+      `tests/fixtures/architecture/forbidden/**/*.${sourceExtensions}`,
+    ],
    rules: {
      "no-restricted-imports": restrictedImports([
        "**/adapters/**",
@@ -99,24 +193,4 @@ export default [
      ]),
    },
  },
-  {
-    files: ["**/*.{js,jsx}"],
-    rules: {
-      "no-eval": "error",
-      "no-new-func": "error",
-      "no-script-url": "error",
-      "no-restricted-syntax": [
-        "error",
-        {
-          selector: "JSXAttribute[name.name='dangerouslySetInnerHTML']",
-          message: "Raw HTML injection is prohibited by FE-OC-019.",
-        },
-        {
-          selector:
-            "CallExpression[callee.object.name='document'][callee.property.name='createElement'][arguments.0.value='script']",
-          message: "Runtime script construction is prohibited by FE-OC-019.",
-        },
-      ],
-    },
-  },
 ];
@@ -5,7 +5,7 @@
  "type": "module",
  "packageManager": "pnpm@11.17.0",
  "engines": {
-    "node": ">=24.0.0 <25.0.0",
+    "node": ">=24.11.0 <25.0.0",
    "pnpm": ">=11.0.0 <12.0.0"
  },
  "scripts": {
@@ -15,8 +15,13 @@
    "preview": "vite preview",
    "lint": "eslint src scripts tests vite.config.js vitest.config.js playwright.config.js --max-warnings=0",
    "check:architecture": "node scripts/check-architecture.mjs",
-    "check:types": "tsc --allowJs --checkJs --noEmit",
+    "check:types": "corepack pnpm check:types:app && corepack pnpm check:types:node && corepack pnpm check:types:test",
+    "check:types:app": "tsc --project tsconfig.app.json",
+    "check:types:node": "tsc --project tsconfig.node.json",
+    "check:types:test": "tsc --project tsconfig.test.json",
    "check:types:fixture": "tsc --ignoreConfig --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
+    "check:types:fixture:ts-port": "tsc --ignoreConfig --strict --noEmit --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-port-implementation.ts",
+    "check:types:fixture:ts-result": "tsc --ignoreConfig --strict --noEmit --target ES2022 --module ESNext --moduleResolution Bundler tests/fixtures/typecheck/invalid-result-narrowing.ts",
    "test:runtime-schema": "vitest run tests/runtime-schema --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/runtime-schema.xml --passWithNoTests",
    "test:unit": "vitest run tests/unit --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/unit.xml",
    "test:component": "vitest run tests/component --reporter=default --reporter=junit --outputFile.junit=artifacts/tests/component.xml",
@@ -31,6 +36,7 @@
    "scan:security": "node scripts/security-scan.mjs",
    "check:browser-security": "node scripts/check-browser-security.mjs",
    "check:registries": "node scripts/check-registries.mjs",
+    "check:registries:fixture": "node scripts/check-registries.mjs --governance tests/fixtures/registry/forbidden/governance.json --artifact artifacts/quality/registry-fixture.json",
    "verify:compatibility": "node scripts/check-compatibility.mjs",
    "verify:release": "node scripts/verify-release.mjs",
    "verify:hosting-headers": "node scripts/verify-hosting-headers.mjs",
@@ -52,18 +58,23 @@
  },
  "devDependencies": {
    "@axe-core/playwright": "4.12.1",
+    "@babel/core": "8.0.1",
+    "@babel/eslint-parser": "8.0.1",
+    "@babel/plugin-syntax-jsx": "8.0.1",
+    "@babel/plugin-syntax-typescript": "8.0.3",
    "@eslint/js": "10.0.1",
    "@playwright/test": "1.62.0",
+    "@tailwindcss/vite": "4.3.3",
    "@testing-library/jest-dom": "7.0.0",
    "@testing-library/react": "16.3.2",
    "@testing-library/user-event": "14.6.1",
-    "@tailwindcss/vite": "4.3.3",
    "@types/node": "24.13.3",
    "@types/react": "19.2.8",
    "@types/react-dom": "19.2.3",
    "@vitejs/plugin-react": "6.0.4",
    "dependency-cruiser": "18.1.0",
    "eslint": "10.8.0",
+    "eslint-plugin-react-hooks": "7.1.1",
    "globals": "17.7.0",
    "jsdom": "29.1.1",
    "msw": "2.15.0",
@@ -19,5 +19,7 @@ export default defineConfig({
  },
  projects: [
    { name: "chromium", use: { ...devices["Desktop Chrome"] } },
+    { name: "firefox", use: { ...devices["Desktop Firefox"] } },
+    { name: "webkit", use: { ...devices["Desktop Safari"] } },
  ],
 });
@@ -27,6 +27,18 @@ importers:
      '@axe-core/playwright':
        specifier: 4.12.1
        version: 4.12.1(playwright-core@1.62.0)
+      '@babel/core':
+        specifier: 8.0.1
+        version: 8.0.1
+      '@babel/eslint-parser':
+        specifier: 8.0.1
+        version: 8.0.1(@babel/core@8.0.1)(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))
+      '@babel/plugin-syntax-jsx':
+        specifier: 8.0.1
+        version: 8.0.1(@babel/core@8.0.1)
+      '@babel/plugin-syntax-typescript':
+        specifier: 8.0.3
+        version: 8.0.3(@babel/core@8.0.1)
      '@eslint/js':
        specifier: 10.0.1
        version: 10.0.1(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))
@@ -63,6 +75,9 @@ importers:
      eslint:
        specifier: 10.8.0
        version: 10.8.0(jiti@2.7.0)(supports-color@7.2.0)
+      eslint-plugin-react-hooks:
+        specifier: 7.1.1
+        version: 7.1.1(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0)
      globals:
        specifier: 17.7.0
        version: 17.7.0
@@ -114,14 +129,155 @@ packages:
    resolution: {integrity: sha512-Aup7aUOfpbAUg2ROOJN6Iw5f9DMBlzu0mIkm/malLQFN/YQgO48wCj0Kxa3sEHJvPVFg7siR+qRInwXd2qhQKw==}
    engines: {node: '>=6.9.0'}

+  '@babel/code-frame@8.0.0':
+    resolution: {integrity: sha512-dYYg153EyN2Ekbqw2zAsbd6/JR+9N2SEoC7YV2GyyqMM7x9bLDTjBD6XBhSMLH0wtIVyJj03jWNriQhaN+eoCw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/compat-data@7.29.7':
+    resolution: {integrity: sha512-locTkQyKvwIEgBzVrn8693ebc97F2U8ZHjbXwDXJ5Fn2TCpNwTlKcaKLkdHop5c/icOFE7qt7Q9JC5hnKNa6Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/compat-data@8.0.0':
+    resolution: {integrity: sha512-DOjnob/cXOUgDOozCDeq/aK2p5y8dUIVdf6tNhEV1HQRd6I8aQ4f4fbtHRVEvb6lP3BGomrKHiS8ICAASSVQSw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/core@7.29.7':
+    resolution: {integrity: sha512-RgHBCvtjbOK2gXSNBNIkNoEc9qoVEtau3hj8gEqKQuL3HZAibKarWFEI3Lfm6EYKkLalOh8eSrj9b+ch9H/VBA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/core@8.0.1':
+    resolution: {integrity: sha512-5FgxM4dLQpMJHSiVATk8foW263dVHQHBVpXYiimNECVWG01f4nFyEbQixeT6Mwvg7TayREJ2gpKl3o2RoMdnqw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/eslint-parser@8.0.1':
+    resolution: {integrity: sha512-2javO8pAQv/ld6sS6OcxoLAlzZEZy+xm99bnoAfMhzKSumKhdF5wylpbZB7XTorWr3KLPtx5K95eduJPOy1mzA==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    peerDependencies:
+      '@babel/core': ^8.0.0
+      eslint: ^9.0.0 || ^10.0.0
+
+  '@babel/generator@7.29.7':
+    resolution: {integrity: sha512-DkXD5OJQaAQIdZ1bt3UZdEnHAn9Imd3IVBdX03UFe+ony9Ojw5pzr9YVKGDY1jt+Gcn/FnGkNf8r+Vj5NOJWtQ==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/generator@8.0.0':
+    resolution: {integrity: sha512-NT9NrVwJsbSV6Y2FSstWa71EETOnzrjkL5/wX3D2mYHtKM+qvqB1DvR4D0Setb/gDBsHzRICifwEWMO8CnTF6g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-compilation-targets@7.29.7':
+    resolution: {integrity: sha512-wem6WaBj4NaVYVdNhLPPVacES6ZJ+KBBfSkTMD3YZxbP3rm3Di85tJU5ljaUNhaOynt+Aj0xruhYuzQBt8n71g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-compilation-targets@8.0.0':
+    resolution: {integrity: sha512-JwculLABZvyPvyLBpwU/E/IbH2uM3mnxNtIJpxnIfb24y1PrdVxK5Dqjle4DpgqpGRnwgC7G8IkzPdSXZrO1Ew==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-globals@7.29.7':
+    resolution: {integrity: sha512-3nQVUAtvkKH9zahfWgw96Jc/uFOmjACE1kQz82E2lqWmHBgjzbNlsC22nuQTfahmWeQtTq5nQ/4Nnd2A1wj4zA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-globals@8.0.0':
+    resolution: {integrity: sha512-lLozHOM6sWWlxNo8CYqHy4MBZeTvHXNgVPBfPOGsjPKUzHC2Az9QwB6gxdQmpwHl6GlQtbGgS+lj5887guDiLw==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-module-imports@7.29.7':
+    resolution: {integrity: sha512-ejHwrQQYcm9xnTivShn2IDOlIzInN34AXskvq9QicvCtEzq1Vzclu/tKF8Jq1Cg8JG2GL6/EmjgsCT7lXepE3g==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-module-transforms@7.29.7':
+    resolution: {integrity: sha512-UPUVSyXbOh627KiCIGQSgwWzGeBKLkaJ9PJEdrngIwMSzxLR4jS4+f1f1jb7VzBbg8nFLaYotvVPFCTqdrmTAg==}
+    engines: {node: '>=6.9.0'}
+    peerDependencies:
+      '@babel/core': ^7.0.0
+
+  '@babel/helper-plugin-utils@8.0.1':
+    resolution: {integrity: sha512-3PKFgjTyPlhFhorfP+SjKQxLViIL++zWjFOO4hGriYU+Bsm983DxEM1JmDRJVWXV0O9npu+xXRqz7Pbd3mh70g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    peerDependencies:
+      '@babel/core': ^8.0.0
+
+  '@babel/helper-string-parser@7.29.7':
+    resolution: {integrity: sha512-Pb5ijPrZ89GDH8223L4UP8i6QApWxs04RbPQJTeWDV0/keR2E36MeKnyr6LYmUUvqRRI+Iv87SuF1W6ErINzYw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-string-parser@8.0.0':
+    resolution: {integrity: sha512-6mJgmFFFIIO82vvoLt9XtRC7/TkzXfts1t/SpRX4IHSzMgqoPYCWesVu1udUPUWioAE/2fcG6WuI8zrkE1gwrg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
  '@babel/helper-validator-identifier@7.29.7':
    resolution: {integrity: sha512-qehxGkRj55h/ff8EMaJ+cYhyaKlHIxqYDn682wQD7RNp9UujOQsHog2uS0r2vzr4pW+sXf90NeeayjcNaX3fFg==}
    engines: {node: '>=6.9.0'}

+  '@babel/helper-validator-identifier@8.0.4':
+    resolution: {integrity: sha512-4wFaiLd0bVo4cIoTXI3zKI038NIWE/cr3jvBjejOVYVxV/m8Ltav1USiGzG1fmS5J2RhgEOgXNNK46cRPnRsrg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helper-validator-option@7.29.7':
+    resolution: {integrity: sha512-N9ZErrD+yW5geCDtBqnOoxmR8+tNKiGuxKlDpuJxfsqpa2dFcexaziGAE/qoHLiDDreVNMupxGmSoNlyvsA3gw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helper-validator-option@8.0.0':
+    resolution: {integrity: sha512-U4Dybxh4WESWHt5XhBeExi4DrY0/DNK1aHpQbsrQXCUbFHuMweT0TpLEWKvaraV2Y6fS+ZXunsZ8zIuZIgvF2Q==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/helpers@7.29.7':
+    resolution: {integrity: sha512-1k2lAGRMfHTcwuNYcCNUmaUffmQv8KWMfh2iJUUeRlwlwH4FdNG7mfPI10NPfLHJFThE4Tyr4mv7kTNZOiPuBg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/helpers@8.0.0':
+    resolution: {integrity: sha512-wfbi91pM3py96oIiJEz7qIpyXDytgr9zQC1HEWwlGNVRAEmItuU/0a41ZUKu1sJGyhhOIpc4t5vk4PYzt8wpsg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/parser@7.29.7':
+    resolution: {integrity: sha512-hnORnjP/1P/zFEndoeX+n+t1RwWRJiJpM/jO7FW32Kn9r5+sJB2JWOdYo4L6k78j15eCwY3Gm/7364B1EMwtNg==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
+  '@babel/parser@8.0.4':
+    resolution: {integrity: sha512-srpptsAkEbbNIC/q8nT7o+m6CQe8CJUTV/t7MYc9NnWlgYVtHOb7JH6SorxMhN0kuRJjVqXbKClG6xSbPtzz+g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    hasBin: true
+
+  '@babel/plugin-syntax-jsx@8.0.1':
+    resolution: {integrity: sha512-n0jtCOxEovhU7METqSQjcZO9pX53nu9uNIjMS+hEt+Nt9jA7oOZoBIgbCxhhASmF6T6rPDGge5UAvh6Z4eFz/g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    peerDependencies:
+      '@babel/core': ^8.0.0
+
+  '@babel/plugin-syntax-typescript@8.0.3':
+    resolution: {integrity: sha512-jmTPwps7oSQSZaV1SxkQ3C12UWyufGysGc5OzDpZzvPAIX4mO7dJT3hoqkWVrSImvkcMiknir1iLN1SNV/CZzg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+    peerDependencies:
+      '@babel/core': ^8.0.0
+
  '@babel/runtime@7.29.7':
    resolution: {integrity: sha512-Nq8OhGWiZIZGV6hLHoyAKLLcJihP/xFeBMGJoUrxTX2psI8dCifzLhZISFb+VWS3wFMRDmCGw5R+dOySCqPLhw==}
    engines: {node: '>=6.9.0'}

+  '@babel/template@7.29.7':
+    resolution: {integrity: sha512-puq+Gf35oI24FeN11LkoUQFqv9uwNeWpxXZi/Ji3rRIoKAzKnxRaZ+Gkj0vKS9ZCiTESfng1N9LyOyXvo+m+Gg==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/template@8.0.0':
+    resolution: {integrity: sha512-eAD0QW/AlbamBbw0FeGiwasbCVPq5ncW0HNVyLP3B9czqLyh4gvw+5JTSNt6le9+ziAU7mqDZsKTHf3jTb4chQ==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/traverse@7.29.7':
+    resolution: {integrity: sha512-EhlfNQtZ+NK22w5BM61ciuiq1m58ed33Wr1Xan//ZRTy6hgjnwyCffRYwzsGXdASJSUJ1guZILsErh1eQcl+zw==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/traverse@8.0.4':
+    resolution: {integrity: sha512-bZnmqzGG8UZneG1lLxBoWIH0G6Gr1D846Yu4/3XnY6FhCndMR49u26nTY08u/dAxWmLWF9vGQOuC+84FfIUoeg==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
+  '@babel/types@7.29.7':
+    resolution: {integrity: sha512-4zBIxpPzowiZpusoFkyGVwakdRJUyuH5PxQ/PrqghfdFWWasvnCdPfQXHrenDai+gyLARulZjZowCOj6fjT4pA==}
+    engines: {node: '>=6.9.0'}
+
+  '@babel/types@8.0.4':
+    resolution: {integrity: sha512-eY+Yn3dCqTGmyiq2QRU66lA5FL8lqqqvecHt0fF3uHONIa7ToYsaCiWV8lOKqAs0Rb2SjixiKFROngnulPtt2g==}
+    engines: {node: ^22.18.0 || >=24.11.0}
+
  '@bramus/specificity@2.4.2':
    resolution: {integrity: sha512-ctxtJ/eA+t+6q2++vj5j7FYX3nRu311q1wfYH3xjlLOsczhlhxAg2FWNUXhpGvAw3BWo1xBcvOV6/YLc2r5FJw==}
    hasBin: true
@@ -572,6 +728,12 @@ packages:
  '@types/estree@1.0.9':
    resolution: {integrity: sha512-GhdPgy1el4/ImP05X05Uw4cw2/M93BCUmnEvWZNStlCzEKME4Fkk+YpoA5OiHNQmoS7Cafb8Xa3Pya8m1Qrzeg==}

+  '@types/gensync@1.0.5':
+    resolution: {integrity: sha512-MbsRCT7mTikHwKZ0X+LVUTLRrZZRLipTuXEO9qOYO+zmjMVk81axyClMROf6uoPD9MRVu46bx8zoR0Ad9q3NAg==}
+
+  '@types/jsesc@2.5.1':
+    resolution: {integrity: sha512-9VN+6yxLOPLOav+7PwjZbxiID2bVaeq0ED4qSQmdQTdjnXJSaCVKTR58t15oqH1H5t8Ng2ZX1SabJVoN9Q34bw==}
+
  '@types/json-schema@7.0.15':
    resolution: {integrity: sha512-5+fP8P8MFNC+AyZCDxrB2pkZFPGzqQWUzpSeuuVLvm8VMcorNYavBqoFcxK8bQz4Qsbn4oUEEem4wDLfcysGHA==}

@@ -809,6 +971,11 @@ packages:
    resolution: {integrity: sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==}
    engines: {node: 18 || 20 || >=22}

+  baseline-browser-mapping@2.11.1:
+    resolution: {integrity: sha512-HYXq73DDpCtNzOmrFsm9eSwCvWCql0RzqjpDzXN9EadiLJ4DNat0nsZ/Bzmy+Ud12mb4/zKDY0cQ805ZzN+i0A==}
+    engines: {node: '>=6.0.0'}
+    hasBin: true
+
  bidi-js@1.0.3:
    resolution: {integrity: sha512-RKshQI1R3YQ+n9YJz2QQ147P66ELpa1FQEg20Dk8oW9t2KgLbpDLLp9aGZ7y8WHSshDknG0bknqGw5/tyCs5tw==}

@@ -816,6 +983,14 @@ packages:
    resolution: {integrity: sha512-JZyDyq3D4AUifKTPOB7DELf6XsB3WdPuNxCtob1vFXPsSXhdAiHBWJ/tJ8HAc9aH84BK+5JFZLNkJKx3G9kzQg==}
    engines: {node: 20 || >=22}

+  browserslist@4.28.7:
+    resolution: {integrity: sha512-JxV13hNrFxqjOc8alRbq9dK1MM79NEXYpma2B2J4wAtpWS5zIEIKqWPGCl7N4o7Uc7B7itylh7SuDujATRyyTw==}
+    engines: {node: ^6 || ^7 || ^8 || ^9 || ^10 || ^11 || ^12 || >=13.7}
+    hasBin: true
+
+  caniuse-lite@1.0.30001806:
+    resolution: {integrity: sha512-72Cuvd95zbSYPKq6Fhg8eDJRlzgWDf7/mtoZv6Qe/DYNCEBdNxoA3+rZAU2ZhGCpZlns3EssFavaZomckT5Uuw==}
+
  chai@6.2.2:
    resolution: {integrity: sha512-NUPRluOfOiTKBKvWPtSD4PhFvWCqOi0BGStNWs57X9js7XGTprSmFoz5F0tWhR4WPjNeR9jXqdC7/UpSJTnlRg==}
    engines: {node: '>=18'}
@@ -902,9 +1077,16 @@ packages:
  dom-accessibility-api@0.6.3:
    resolution: {integrity: sha512-7ZgogeTnjuHbo+ct10G9Ffp0mif17idi0IyWNVA/wcwcm7NPOD/WEHVP3n7n3MhXqxoIYm8d6MuZohYWIZ4T3w==}

+  electron-to-chromium@1.5.396:
+    resolution: {integrity: sha512-yHiw2Y3C3H9U6TMbOfoWK/BPreiOPXRfTWPBwQBoZG6/8TB6eOPnsy5oaRYuatR7Fw2SJ4kKforgufeo7fq0EQ==}
+
  emoji-regex@8.0.0:
    resolution: {integrity: sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==}

+  empathic@2.0.1:
+    resolution: {integrity: sha512-YGRs8knHhKHVShLkFET/rWAU8kmHbOV5LwN938RHI0pljAJ1Gf6SzXsSmRaEzcXTtOOmVqJ5+WtQPL5uigY50Q==}
+    engines: {node: '>=14'}
+
  enhanced-resolve@5.24.2:
    resolution: {integrity: sha512-rpsZEGT1jFuve6QlpyRp9ckQ+kN61hvF9BzCPyMdaKTm8UJce96KBn3sorXOFXlzjPrs3Vc4T1NsSroZ3PxlFw==}
    engines: {node: '>=10.13.0'}
@@ -928,6 +1110,12 @@ packages:
    resolution: {integrity: sha512-TtpcNJ3XAzx3Gq8sWRzJaVajRs0uVxA2YAkdb1jm2YkPz4G6egUFAyA3n5vtEIZefPk5Wa4UXbKuS5fKkJWdgA==}
    engines: {node: '>=10'}

+  eslint-plugin-react-hooks@7.1.1:
+    resolution: {integrity: sha512-f2I7Gw6JbvCexzIInuSbZpfdQ44D7iqdWX01FKLvrPgqxoE7oMj8clOfto8U6vYiz4yd5oKu39rRSVOe1zRu0g==}
+    engines: {node: '>=18'}
+    peerDependencies:
+      eslint: ^3.0.0 || ^4.0.0 || ^5.0.0 || ^6.0.0 || ^7.0.0 || ^8.0.0-0 || ^9.0.0 || ^10.0.0
+
  eslint-scope@9.1.2:
    resolution: {integrity: sha512-xS90H51cKw0jltxmvmHy2Iai1LIqrfbw57b79w/J7MfvDfkIkFZ+kj6zC3BjtUwh150HsSSdxXZcsuv72miDFQ==}
    engines: {node: ^20.19.0 || ^22.13.0 || >=24}
@@ -1032,6 +1220,10 @@ packages:
  function-bind@1.1.2:
    resolution: {integrity: sha512-7XHNxH7qX9xG5mIwxkhumTox/MIRNcOgDrxWsMt2pAr23WHp6MrRlN7FBSFpCpr+oVO0F744iUgR82nJMfG2SA==}

+  gensync@1.0.0-beta.2:
+    resolution: {integrity: sha512-3hN7NaskYvMDLQY55gnW3NQ+mesEAepTqlg+VEbj7zzqEMBVNhzcGYYeqFo/TlYz6eQiFcp1HcsCZO+nGgS8zg==}
+    engines: {node: '>=6.9.0'}
+
  get-caller-file@2.0.5:
    resolution: {integrity: sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==}
    engines: {node: 6.* || 8.* || >= 10.*}
@@ -1066,6 +1258,12 @@ packages:
  headers-polyfill@5.0.1:
    resolution: {integrity: sha512-1TJ6Fih/b8h5TIcv+1+Hw0PDQWJTKDKzFZzcKOiW1wJza3XoAQlkCuXLbymPYB8+ZQyw8mHvdw560e8zVFIWyA==}

+  hermes-estree@0.25.1:
+    resolution: {integrity: sha512-0wUoCcLp+5Ev5pDW2OriHC2MJCbwLwuRx+gAqMTOkGKJJiBCLjtrvy4PWUGn6MIVefecRpzoOZ/UV6iGdOr+Cw==}
+
+  hermes-parser@0.25.1:
+    resolution: {integrity: sha512-6pEjquH3rqaI6cYAXYPcz9MS4rY6R4ngRgrgfDshRptUZIc3lw0MCIJIGDj9++mfySOuPTHB4nrSW99BCvOPIA==}
+
  html-encoding-sniffer@6.0.0:
    resolution: {integrity: sha512-CV9TW3Y3f8/wT0BRFc1/KAVQ3TUHiXmaAb6VW9vtiMFf7SLoMd1PdAc4W3KFOFETBJUb90KatHqlsZMWV+R9Gg==}
    engines: {node: ^20.19.0 || ^22.12.0 || >=24.0.0}
@@ -1078,6 +1276,9 @@ packages:
    resolution: {integrity: sha512-BAg6QkE8W+TuQLrrw0Ugr7HegXduRuuj8/ti2kSOc+jz1dmx8/WNcjr6XGnq5YpDWxFwwaavqD0+jIUOKelTsw==}
    engines: {node: '>= 4'}

+  import-meta-resolve@4.2.0:
+    resolution: {integrity: sha512-Iqv2fzaTQN28s/FwZAoFq0ZSs/7hMAHJVX+w8PZl3cY19Pxk6jFFalxQoIfW2826i/fDLXv8IiEZRIT0lDuWcg==}
+
  imurmurhash@0.1.4:
    resolution: {integrity: sha512-JmXMZ6wuvDmLiHEml9ykzqO6lwFbof0GG4IkcGaENdCRDDmMVnny7s5HsIgHCbaq0w2MyPhDqkhTUgS2LU2PHA==}
    engines: {node: '>=0.8.19'}
@@ -1131,6 +1332,9 @@ packages:
    resolution: {integrity: sha512-AC/7JofJvZGrrneWNaEnJeOLUx+JlGt7tNa0wZiRPT4MY1wmfKjt2+6O2p2uz2+skll8OZZmJMNqeke7kKbNgQ==}
    hasBin: true

+  js-tokens@10.0.0:
+    resolution: {integrity: sha512-lM/UBzQmfJRo9ABXbPWemivdCW8V2G8FHaHdypQaIy523snUjog0W71ayWXTjiR+ixeMyVHN2XcpnTd/liPg/Q==}
+
  js-tokens@4.0.0:
    resolution: {integrity: sha512-RdJUflcE3cUzKiMqQgsCu06FPu9UdIJO0beYbPhHN4k6apgJtifcoCtT9bcxOpYBtpD2kCM6Sbzg4CausW/PKQ==}

@@ -1143,6 +1347,11 @@ packages:
      canvas:
        optional: true

+  jsesc@3.1.0:
+    resolution: {integrity: sha512-/sM3dO2FOzXjKQhJuo0Q173wf2KOo8t4I8vHy6lF9poUp7bKT0/NHE8fPX23PwfhnykfqnC2xRxOnVw5XuGIaA==}
+    engines: {node: '>=6'}
+    hasBin: true
+
  json-buffer@3.0.1:
    resolution: {integrity: sha512-4bV5BfR2mqfQTJm+V5tPPdf+ZpuhiIvTuAB5g8kcrXOZpTT/QwwVRWBywX1ozr6lEuPdbHxwaJlm9G6mI2sfSQ==}

@@ -1324,6 +1533,9 @@ packages:
    resolution: {integrity: sha512-4pfM1Ff0x50o0tQwb5ucw/RzNyD0/YJME6IVcStalZuMWxdt3sR3huStTtxz4PUmvZfRguvDejasvQ2kifR11g==}
    engines: {node: 20 || >=22}

+  lru-cache@5.1.1:
+    resolution: {integrity: sha512-KpNARQA3Iwv+jTA0utUVVbrh+Jlrr1Fv0e56GGzAFOXN7dk/FviaDW8LHmK52DlcH4WP2n6gI8vN1aesBFgo9w==}
+
  lz-string@1.5.0:
    resolution: {integrity: sha512-h5bgJWpxJNswbU7qCrV0tIKQCaS3blPDrqKWx+QxzuzL1zGUzij9XCWLrSLsJPu5t+eWA/ycetzYAO5IOMcWAQ==}
    hasBin: true
@@ -1370,6 +1582,10 @@ packages:
  natural-compare@1.4.0:
    resolution: {integrity: sha512-OWND8ei3VtNC9h7V60qff3SVobHr996CTwgxubgyQYEpg290h9J0buyECNNJexkFm5sOajh5G116RYA1c8ZMSw==}

+  node-releases@2.0.51:
+    resolution: {integrity: sha512-wRNIrw4DmVLKQlbgOMdkMx27Wrpzes2hh5Jtbi2bjPd+4wJstWIqP5A+lscnqbm0xxmT5Bpg8Lec5ItEBwx6BQ==}
+    engines: {node: '>=18'}
+
  obug@2.1.4:
    resolution: {integrity: sha512-4a+OsYv9UktOJKE+l1A4OufDgdRF9PifWj+tJnHURo/P+WOxpG4GzUFL9qCalmWauao6ogiG+QvnCovwPoyAWA==}
    engines: {node: '>=12.20.0'}
@@ -1518,6 +1734,10 @@ packages:
  scheduler@0.27.0:
    resolution: {integrity: sha512-eNv+WrVbKu1f3vbYJT/xtiF5syA5HPIMtf9IgY/nKg0sWqzAUEvqY/xm7OcZc/qafLx/iO9FgOmeSAp4v5ti/Q==}

+  semver@6.3.1:
+    resolution: {integrity: sha512-BR7VvDCVHO+q2xBEWskxS6DJE1qRnb7DxzUrogb71CWoSficBxYsiAGd+Kl0mmq/MprG9yArRkyrQxTO6XjMzA==}
+    hasBin: true
+
  semver@7.8.5:
    resolution: {integrity: sha512-Y7/KDsb8LjooZpwaqGyulO6DQlksgCncchHGk+sZIY4SBvUocMBEFH5Ur1fI4dV+Jvl0w6cjvucaIi40puRioA==}
    engines: {node: '>=10'}
@@ -1666,6 +1886,12 @@ packages:
  until-async@3.0.2:
    resolution: {integrity: sha512-IiSk4HlzAMqTUseHHe3VhIGyuFmN90zMTpD3Z3y8jeQbzLIq500MVM7Jq2vUAnTKAFPJrqwkzr6PoTcPhGcOiw==}

+  update-browserslist-db@1.2.3:
+    resolution: {integrity: sha512-Js0m9cx+qOgDxo0eMiFGEueWztz+d4+M3rGlmKPT+T4IS/jP4ylw3Nwpu6cpTTP8R1MAC1kF4VbdLt3ARf209w==}
+    hasBin: true
+    peerDependencies:
+      browserslist: '>= 4.21.0'
+
  uri-js@4.4.1:
    resolution: {integrity: sha512-7rKUyy33Q1yc98pQ1DAmLtwX109F7TIfWlW1Ydo8Wl1ii1SeHieeh0HHfPeL2fMXK6z0s8ecKs9frCuLJvndBg==}

@@ -1803,6 +2029,9 @@ packages:
    resolution: {integrity: sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==}
    engines: {node: '>=10'}

+  yallist@3.1.1:
+    resolution: {integrity: sha512-a4UGQaWPH59mOXUYnAG2ewncQS4i4F43Tv3JoAM+s2VDAmS9NsK8GpDMLrCHPksFT7h3K6TOoUNn2pb7RoXx4g==}
+
  yargs-parser@21.1.1:
    resolution: {integrity: sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==}
    engines: {node: '>=12'}
@@ -1815,6 +2044,12 @@ packages:
    resolution: {integrity: sha512-rVksvsnNCdJ/ohGc6xgPwyN8eheCxsiLM8mxuE/t/mOVqJewPuO1miLpTHQiRgTKCLexL4MeAFVagts7HmNZ2Q==}
    engines: {node: '>=10'}

+  zod-validation-error@4.0.2:
+    resolution: {integrity: sha512-Q6/nZLe6jxuU80qb/4uJ4t5v2VEZ44lzQjPDhYJNztRQ4wyWc6VF3D3Kb/fAuPetZQnhS3hnajCf9CsWesghLQ==}
+    engines: {node: '>=18.0.0'}
+    peerDependencies:
+      zod: ^3.25.0 || ^4.0.0
+
  zod@4.4.3:
    resolution: {integrity: sha512-ytENFjIJFl2UwYglde2jchW2Hwm4GJFLDiSXWdTrJQBIN9Fcyp7n4DhxJEiWNAJMV1/BqWfW/kkg71UDcHJyTQ==}

@@ -1853,10 +2088,205 @@ snapshots:
      js-tokens: 4.0.0
      picocolors: 1.1.1

+  '@babel/code-frame@8.0.0':
+    dependencies:
+      '@babel/helper-validator-identifier': 8.0.4
+      js-tokens: 10.0.0
+
+  '@babel/compat-data@7.29.7': {}
+
+  '@babel/compat-data@8.0.0': {}
+
+  '@babel/core@7.29.7(supports-color@7.2.0)':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-compilation-targets': 7.29.7
+      '@babel/helper-module-transforms': 7.29.7(@babel/core@7.29.7(supports-color@7.2.0))(supports-color@7.2.0)
+      '@babel/helpers': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@7.2.0)
+      '@babel/types': 7.29.7
+      '@jridgewell/remapping': 2.3.5
+      convert-source-map: 2.0.0
+      debug: 4.4.3(supports-color@7.2.0)
+      gensync: 1.0.0-beta.2
+      json5: 2.2.3
+      semver: 6.3.1
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/core@8.0.1':
+    dependencies:
+      '@babel/code-frame': 8.0.0
+      '@babel/generator': 8.0.0
+      '@babel/helper-compilation-targets': 8.0.0
+      '@babel/helpers': 8.0.0
+      '@babel/parser': 8.0.4
+      '@babel/template': 8.0.0
+      '@babel/traverse': 8.0.4
+      '@babel/types': 8.0.4
+      '@types/gensync': 1.0.5
+      convert-source-map: 2.0.0
+      empathic: 2.0.1
+      gensync: 1.0.0-beta.2
+      import-meta-resolve: 4.2.0
+      json5: 2.2.3
+      obug: 2.1.4
+      semver: 7.8.5
+
+  '@babel/eslint-parser@8.0.1(@babel/core@8.0.1)(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))':
+    dependencies:
+      '@babel/core': 8.0.1
+      eslint: 10.8.0(jiti@2.7.0)(supports-color@7.2.0)
+      eslint-scope: 9.1.2
+      eslint-visitor-keys: 5.0.1
+      semver: 7.8.5
+
+  '@babel/generator@7.29.7':
+    dependencies:
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      jsesc: 3.1.0
+
+  '@babel/generator@8.0.0':
+    dependencies:
+      '@babel/parser': 8.0.4
+      '@babel/types': 8.0.4
+      '@jridgewell/gen-mapping': 0.3.13
+      '@jridgewell/trace-mapping': 0.3.31
+      '@types/jsesc': 2.5.1
+      jsesc: 3.1.0
+
+  '@babel/helper-compilation-targets@7.29.7':
+    dependencies:
+      '@babel/compat-data': 7.29.7
+      '@babel/helper-validator-option': 7.29.7
+      browserslist: 4.28.7
+      lru-cache: 5.1.1
+      semver: 6.3.1
+
+  '@babel/helper-compilation-targets@8.0.0':
+    dependencies:
+      '@babel/compat-data': 8.0.0
+      '@babel/helper-validator-option': 8.0.0
+      browserslist: 4.28.7
+      lru-cache: 11.5.2
+      semver: 7.8.5
+
+  '@babel/helper-globals@7.29.7': {}
+
+  '@babel/helper-globals@8.0.0': {}
+
+  '@babel/helper-module-imports@7.29.7(supports-color@7.2.0)':
+    dependencies:
+      '@babel/traverse': 7.29.7(supports-color@7.2.0)
+      '@babel/types': 7.29.7
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-module-transforms@7.29.7(@babel/core@7.29.7(supports-color@7.2.0))(supports-color@7.2.0)':
+    dependencies:
+      '@babel/core': 7.29.7(supports-color@7.2.0)
+      '@babel/helper-module-imports': 7.29.7(supports-color@7.2.0)
+      '@babel/helper-validator-identifier': 7.29.7
+      '@babel/traverse': 7.29.7(supports-color@7.2.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/helper-plugin-utils@8.0.1(@babel/core@8.0.1)':
+    dependencies:
+      '@babel/core': 8.0.1
+
+  '@babel/helper-string-parser@7.29.7': {}
+
+  '@babel/helper-string-parser@8.0.0': {}
+
  '@babel/helper-validator-identifier@7.29.7': {}

+  '@babel/helper-validator-identifier@8.0.4': {}
+
+  '@babel/helper-validator-option@7.29.7': {}
+
+  '@babel/helper-validator-option@8.0.0': {}
+
+  '@babel/helpers@7.29.7':
+    dependencies:
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/helpers@8.0.0':
+    dependencies:
+      '@babel/template': 8.0.0
+      '@babel/types': 8.0.4
+
+  '@babel/parser@7.29.7':
+    dependencies:
+      '@babel/types': 7.29.7
+
+  '@babel/parser@8.0.4':
+    dependencies:
+      '@babel/types': 8.0.4
+
+  '@babel/plugin-syntax-jsx@8.0.1(@babel/core@8.0.1)':
+    dependencies:
+      '@babel/core': 8.0.1
+      '@babel/helper-plugin-utils': 8.0.1(@babel/core@8.0.1)
+
+  '@babel/plugin-syntax-typescript@8.0.3(@babel/core@8.0.1)':
+    dependencies:
+      '@babel/core': 8.0.1
+      '@babel/helper-plugin-utils': 8.0.1(@babel/core@8.0.1)
+
  '@babel/runtime@7.29.7': {}

+  '@babel/template@7.29.7':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/types': 7.29.7
+
+  '@babel/template@8.0.0':
+    dependencies:
+      '@babel/code-frame': 8.0.0
+      '@babel/parser': 8.0.4
+      '@babel/types': 8.0.4
+
+  '@babel/traverse@7.29.7(supports-color@7.2.0)':
+    dependencies:
+      '@babel/code-frame': 7.29.7
+      '@babel/generator': 7.29.7
+      '@babel/helper-globals': 7.29.7
+      '@babel/parser': 7.29.7
+      '@babel/template': 7.29.7
+      '@babel/types': 7.29.7
+      debug: 4.4.3(supports-color@7.2.0)
+    transitivePeerDependencies:
+      - supports-color
+
+  '@babel/traverse@8.0.4':
+    dependencies:
+      '@babel/code-frame': 8.0.0
+      '@babel/generator': 8.0.0
+      '@babel/helper-globals': 8.0.0
+      '@babel/parser': 8.0.4
+      '@babel/template': 8.0.0
+      '@babel/types': 8.0.4
+      obug: 2.1.4
+
+  '@babel/types@7.29.7':
+    dependencies:
+      '@babel/helper-string-parser': 7.29.7
+      '@babel/helper-validator-identifier': 7.29.7
+
+  '@babel/types@8.0.4':
+    dependencies:
+      '@babel/helper-string-parser': 8.0.0
+      '@babel/helper-validator-identifier': 8.0.4
+
  '@bramus/specificity@2.4.2':
    dependencies:
      css-tree: 3.2.1
@@ -2213,6 +2643,10 @@ snapshots:

  '@types/estree@1.0.9': {}

+  '@types/gensync@1.0.5': {}
+
+  '@types/jsesc@2.5.1': {}
+
  '@types/json-schema@7.0.15': {}

  '@types/node@24.13.3':
@@ -2383,6 +2817,8 @@ snapshots:

  balanced-match@4.0.4: {}

+  baseline-browser-mapping@2.11.1: {}
+
  bidi-js@1.0.3:
    dependencies:
      require-from-string: 2.0.2
@@ -2391,6 +2827,16 @@ snapshots:
    dependencies:
      balanced-match: 4.0.4

+  browserslist@4.28.7:
+    dependencies:
+      baseline-browser-mapping: 2.11.1
+      caniuse-lite: 1.0.30001806
+      electron-to-chromium: 1.5.396
+      node-releases: 2.0.51
+      update-browserslist-db: 1.2.3(browserslist@4.28.7)
+
+  caniuse-lite@1.0.30001806: {}
+
  chai@6.2.2: {}

  chalk@4.1.2:
@@ -2479,8 +2925,12 @@ snapshots:

  dom-accessibility-api@0.6.3: {}

+  electron-to-chromium@1.5.396: {}
+
  emoji-regex@8.0.0: {}

+  empathic@2.0.1: {}
+
  enhanced-resolve@5.24.2:
    dependencies:
      graceful-fs: 4.2.11
@@ -2496,6 +2946,17 @@ snapshots:

  escape-string-regexp@4.0.0: {}

+  eslint-plugin-react-hooks@7.1.1(eslint@10.8.0(jiti@2.7.0)(supports-color@7.2.0))(supports-color@7.2.0):
+    dependencies:
+      '@babel/core': 7.29.7(supports-color@7.2.0)
+      '@babel/parser': 7.29.7
+      eslint: 10.8.0(jiti@2.7.0)(supports-color@7.2.0)
+      hermes-parser: 0.25.1
+      zod: 4.4.3
+      zod-validation-error: 4.0.2(zod@4.4.3)
+    transitivePeerDependencies:
+      - supports-color
+
  eslint-scope@9.1.2:
    dependencies:
      '@types/esrecurse': 4.3.1
@@ -2612,6 +3073,8 @@ snapshots:

  function-bind@1.1.2: {}

+  gensync@1.0.0-beta.2: {}
+
  get-caller-file@2.0.5: {}

  glob-parent@6.0.2:
@@ -2639,6 +3102,12 @@ snapshots:
      '@types/set-cookie-parser': 2.4.10
      set-cookie-parser: 3.1.2

+  hermes-estree@0.25.1: {}
+
+  hermes-parser@0.25.1:
+    dependencies:
+      hermes-estree: 0.25.1
+
  html-encoding-sniffer@6.0.0:
    dependencies:
      '@exodus/bytes': 1.15.1
@@ -2649,6 +3118,8 @@ snapshots:

  ignore@7.0.6: {}

+  import-meta-resolve@4.2.0: {}
+
  imurmurhash@0.1.4: {}

  indent-string@4.0.0: {}
@@ -2684,6 +3155,8 @@ snapshots:

  jiti@2.7.0: {}

+  js-tokens@10.0.0: {}
+
  js-tokens@4.0.0: {}

  jsdom@29.1.1:
@@ -2712,6 +3185,8 @@ snapshots:
    transitivePeerDependencies:
      - '@noble/hashes'

+  jsesc@3.1.0: {}
+
  json-buffer@3.0.1: {}

  json-schema-traverse@0.4.1: {}
@@ -2835,6 +3310,10 @@ snapshots:

  lru-cache@11.5.2: {}

+  lru-cache@5.1.1:
+    dependencies:
+      yallist: 3.1.1
+
  lz-string@1.5.0: {}

  magic-string@0.30.21:
@@ -2884,6 +3363,8 @@ snapshots:

  natural-compare@1.4.0: {}

+  node-releases@2.0.51: {}
+
  obug@2.1.4: {}

  optionator@0.9.4:
@@ -3030,6 +3511,8 @@ snapshots:

  scheduler@0.27.0: {}

+  semver@6.3.1: {}
+
  semver@7.8.5: {}

  set-cookie-parser@2.7.2: {}
@@ -3166,6 +3649,12 @@ snapshots:

  until-async@3.0.2: {}

+  update-browserslist-db@1.2.3(browserslist@4.28.7):
+    dependencies:
+      browserslist: 4.28.7
+      escalade: 3.2.0
+      picocolors: 1.1.1
+
  uri-js@4.4.1:
    dependencies:
      punycode: 2.3.1
@@ -3251,6 +3740,8 @@ snapshots:

  y18n@5.0.8: {}

+  yallist@3.1.1: {}
+
  yargs-parser@21.1.1: {}

  yargs@17.7.3:
@@ -3265,4 +3756,8 @@ snapshots:

  yocto-queue@0.1.0: {}

+  zod-validation-error@4.0.2(zod@4.4.3):
+    dependencies:
+      zod: 4.4.3
+
  zod@4.4.3: {}
@@ -2,12 +2,53 @@ import { access, mkdir, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { pathToFileURL } from "node:url";

+/** @param {string} name @param {string} fallback */
+function argumentValue(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+
+const governancePath = argumentValue(
+  "--governance",
+  "config/contracts/registry-governance.json",
+);
+const artifactPath = argumentValue(
+  "--artifact",
+  "artifacts/quality/registries.json",
+);
 const governance = JSON.parse(
-  await readFile("config/contracts/registry-governance.json", "utf8"),
+  await readFile(governancePath, "utf8"),
 );
 const failures = [];
 const owners = new Map();
 const snapshots = [];
+const rowsByRegistry = new Map();
+const registryExtensions = [".js", ".jsx", ".mjs", ".ts", ".tsx", ".mts"];
+
+/** @param {string} declaredPath */
+async function resolveRegistrySource(declaredPath) {
+  const extension = path.extname(declaredPath);
+  const basePath = extension
+    ? declaredPath.slice(0, -extension.length)
+    : declaredPath;
+  const candidates = [];
+  for (const candidateExtension of registryExtensions) {
+    const candidate = `${basePath}${candidateExtension}`;
+    try {
+      await access(candidate);
+      candidates.push(candidate);
+    } catch {
+      // A migration may legitimately replace the declared extension.
+    }
+  }
+  if (candidates.length > 1) {
+    failures.push(
+      `ambiguous registry source ${declaredPath}: ${candidates.join(", ")}`,
+    );
+    return null;
+  }
+  return candidates[0] ?? null;
+}

 for (const specification of governance.registries) {
  if (owners.has(specification.registryId)) {
@@ -16,10 +57,11 @@ for (const specification of governance.registries) {
  owners.set(specification.registryId, specification.owner);

  let rows = specification.declaredRows;
+  const sourcePath = await resolveRegistrySource(specification.path);
  try {
-    await access(specification.path);
+    if (!sourcePath) throw new Error("missing registry source");
    const module = await import(
-      `${pathToFileURL(path.resolve(specification.path)).href}?registry-check=${Date.now()}`
+      `${pathToFileURL(path.resolve(sourcePath)).href}?registry-check=${Date.now()}`
    );
    rows = module[specification.exportName];
  } catch {
@@ -31,6 +73,8 @@ for (const specification of governance.registries) {
    continue;
  }

+  rowsByRegistry.set(specification.registryId, rows);
+
  for (const [rowName, row] of Object.entries(rows)) {
    if (!row || typeof row !== "object" || Array.isArray(row)) {
      failures.push(`${specification.registryId}.${rowName} is not an object`);
@@ -43,16 +87,61 @@ for (const specification of governance.registries) {
    }
  }

+  for (const field of specification.uniqueFields ?? []) {
+    const values = new Map();
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const value = row[field];
+      if (value === undefined) continue;
+      if (values.has(value)) {
+        failures.push(
+          `${specification.registryId}.${rowName} duplicates ${field}=${String(value)} from ${values.get(value)}`,
+        );
+      } else {
+        values.set(value, rowName);
+      }
+    }
+  }
+
  snapshots.push({
    registryId: specification.registryId,
    owner: specification.owner,
-    source: specification.path,
+    source: sourcePath ?? specification.path,
    rowCount: Object.keys(rows).length,
    rows,
  });
 }

-const sourceFiles = [
+for (const specification of governance.registries) {
+  const rows = rowsByRegistry.get(specification.registryId);
+  if (!rows) continue;
+  for (const reference of specification.references ?? []) {
+    const targetRows = rowsByRegistry.get(reference.registryId);
+    if (!targetRows) {
+      failures.push(
+        `${specification.registryId} references unknown registry ${reference.registryId}`,
+      );
+      continue;
+    }
+    const targetValues = new Set(
+      Object.values(targetRows)
+        .filter((row) => row && typeof row === "object" && !Array.isArray(row))
+        .map((row) => row[reference.targetField])
+        .filter((value) => value !== undefined),
+    );
+    for (const [rowName, row] of Object.entries(rows)) {
+      if (!row || typeof row !== "object" || Array.isArray(row)) continue;
+      const value = row[reference.field];
+      if (value !== undefined && !targetValues.has(value)) {
+        failures.push(
+          `${specification.registryId}.${rowName}.${reference.field} references unknown ${reference.registryId}.${reference.targetField}=${String(value)}`,
+        );
+      }
+    }
+  }
+}
+
+const sourceFiles = governance.sourceDirectories ?? [
  "src/application",
  "src/presentation",
  "src/domain",
@@ -75,7 +164,7 @@ async function scanDirectory(directory) {
      await scanDirectory(target);
      continue;
    }
-    if (!/\.(js|jsx|mjs)$/.test(entry.name)) continue;
+    if (!/\.(js|jsx|mjs|ts|tsx|mts)$/.test(entry.name)) continue;
    const content = await readFile(target, "utf8");
    for (const pattern of adHocPatterns) {
      if (pattern.expression.test(content)) {
@@ -91,7 +180,7 @@ for (const sourceDirectory of sourceFiles) {

 await mkdir("artifacts/quality", { recursive: true });
 await writeFile(
-  "artifacts/quality/registries.json",
+  artifactPath,
  `${JSON.stringify(
    {
      schemaVersion: 1,
@@ -1,5 +1,8 @@
 export const MANUAL_A11Y_ROUTE_IDS = Object.freeze([
  "APP_HOME",
+  "EXAMPLES_UI",
+  "EXAMPLES_STATES",
+  "EXAMPLES_AUTH",
  "SAMPLE_RESOURCE_LIST",
  "NOT_FOUND",
 ]);
@@ -6,6 +6,7 @@ import process from "node:process";
 import { chromium } from "@playwright/test";

 import { evaluateLabBudget } from "../src/application/policies/performance-budgets.js";
+import { ROUTE_REGISTRY } from "../src/contracts/routes.js";

 const server = spawn(
  "corepack",
@@ -66,8 +67,13 @@ try {
      }).observe({ type: "layout-shift", buffered: true });
    });
    await page.goto(baseUrl, { waitUntil: "networkidle" });
+    const targetLabel =
+      ROUTE_REGISTRY.SAMPLE_RESOURCE_LIST.navigationLabel;
+    if (!targetLabel) {
+      throw new Error("Performance route must be present in navigation.");
+    }
    const interactionStarted = performance.now();
-    await page.getByRole("link", { name: "샘플 리소스" }).click();
+    await page.getByRole("link", { name: targetLabel }).click();
    await page.getByRole("heading", { name: "세션이 필요합니다." }).waitFor();
    const namedInteractionMs = performance.now() - interactionStarted;
    const paint = await page.evaluate(
@@ -1,5 +1,7 @@
 import { mkdir, writeFile } from "node:fs/promises";

+import { MANUAL_A11Y_ROUTE_IDS } from "./lib/manual-a11y-evidence.mjs";
+
 await mkdir("artifacts/tests", { recursive: true });
 await writeFile(
  "artifacts/tests/a11y.json",
@@ -7,7 +9,7 @@ await writeFile(
    {
      schemaVersion: 1,
      generatedAt: new Date().toISOString(),
-      scope: ["APP_HOME", "SAMPLE_RESOURCE_LIST", "NOT_FOUND"],
+      scope: MANUAL_A11Y_ROUTE_IDS,
      threshold: { critical: 0, serious: 0 },
      automatedStatus: "passed",
      manualReview: "see artifacts/tests/a11y-manual/report.json",
@@ -21,21 +21,7 @@ const noAuthSession =
  onUnauthenticated: () => {},
 });

-/**
- * @typedef {{
- *   kind: string,
- *   code: string,
- *   retryable: boolean,
- *   operationId: string,
- *   attemptCount: number,
- *   httpStatus?: number,
- *   requestId?: string,
- *   traceId?: string,
- *   retryAfterMs?: number,
- *   userMessageKey: string,
- *   action: string
- * }} HttpFailure
- */
+/** @typedef {import("../../contracts/errors.js").ApiFailure} HttpFailure */

 /**
 * @typedef {{ ok: true, value: unknown, meta: Record<string, string> } |
@@ -74,6 +60,7 @@ export function createHttpClient(dependencies) {
   *   signal?: AbortSignal,
   *   idempotencyKey?: string
   * }} [input]
+   * @returns {Promise<HttpResult>}
   */
  async function execute(operationId, input = {}) {
    const operation = getApiOperation(operationId);
@@ -0,0 +1,21 @@
+export const COLOR_SCHEME_PREFERENCES = Object.freeze([
+  "system",
+  "light",
+  "dark",
+]);
+
+/** @param {unknown} value */
+export function normalizeColorSchemePreference(value) {
+  return COLOR_SCHEME_PREFERENCES.includes(/** @type {string} */ (value))
+    ? /** @type {"system" | "light" | "dark"} */ (value)
+    : "system";
+}
+
+/**
+ * @param {"system" | "light" | "dark"} preference
+ * @param {boolean} systemPrefersDark
+ */
+export function resolveColorScheme(preference, systemPrefersDark) {
+  if (preference === "system") return systemPrefersDark ? "dark" : "light";
+  return preference;
+}
@@ -0,0 +1,36 @@
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../application/policies/color-scheme.js";
+
+/**
+ * Applies the persisted public preference before React paints.
+ *
+ * @param {import("../application/ports/storage-port.js").StoragePort} storage
+ * @param {{
+ *   documentElement?: HTMLElement,
+ *   matchMedia?: (query: string) => MediaQueryList
+ * }} [browser]
+ */
+export function initializeColorScheme(storage, browser = {}) {
+  const documentElement = browser.documentElement ?? document.documentElement;
+  const matchMedia =
+    browser.matchMedia ??
+    (typeof window.matchMedia === "function"
+      ? window.matchMedia.bind(window)
+      : () => /** @type {MediaQueryList} */ ({ matches: false }));
+  const stored = storage.read("COLOR_SCHEME");
+  const preference = normalizeColorSchemePreference(
+    stored.ok ? stored.value : undefined,
+  );
+  const resolved = resolveColorScheme(
+    preference,
+    matchMedia("(prefers-color-scheme: dark)").matches,
+  );
+
+  documentElement.dataset.theme = resolved;
+  documentElement.dataset.themePreference = preference;
+  documentElement.style.colorScheme = resolved;
+
+  return Object.freeze({ preference, resolved });
+}
@@ -1,9 +1,11 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+import { QueryClientProvider } from "@tanstack/react-query";

 import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.jsx";
 import { AppRouter } from "../presentation/routes/app-router.jsx";
 import { createRuntimeComposition } from "./create-runtime-composition.js";
+import { initializeColorScheme } from "./initialize-color-scheme.js";
 import { BootConfigError } from "./load-runtime-config.js";
 import { ReleaseManifestError } from "./load-release-manifest.js";
 import "../presentation/styles/theme.css";
@@ -19,12 +21,18 @@ const root = createRoot(rootElement);
 async function boot() {
  try {
    const composition = await createRuntimeComposition();
+    initializeColorScheme(composition.ports.storage);
    root.render(
      <StrictMode>
-        <AppRouter
-          authSession={composition.ports.authSession}
-          basename={composition.config.build.routerBasePath}
-        />
+        <QueryClientProvider client={composition.ports.queryClient}>
+          <AppRouter
+            authSession={composition.ports.authSession}
+            basename={composition.config.build.routerBasePath}
+            buildId={composition.release.buildId}
+            storage={composition.ports.storage}
+            telemetry={composition.ports.telemetry}
+          />
+        </QueryClientProvider>
      </StrictMode>,
    );
  } catch (error) {
@@ -7,7 +7,10 @@
 *   access: "public" | "session-required" | "integration-defined",
 *   loadingSurface: string,
 *   errorSurface: string,
- *   chunkId: string
+ *   chunkId: string,
+ *   title: string,
+ *   navigationLabel: string | null,
+ *   navigationOrder: number | null
 * }} RouteDefinition
 */

@@ -24,6 +27,48 @@ export const ROUTE_REGISTRY = Object.freeze({
    loadingSurface: "app-shell",
    errorSurface: "route-boundary",
    chunkId: "route-home",
+    title: "시작",
+    navigationLabel: "시작",
+    navigationOrder: 10,
+  }),
+  EXAMPLES_UI: route({
+    routeId: "EXAMPLES_UI",
+    path: "/examples/ui",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "example-page",
+    errorSurface: "route-boundary",
+    chunkId: "route-examples-ui",
+    title: "UI 구성요소",
+    navigationLabel: "UI 구성요소",
+    navigationOrder: 20,
+  }),
+  EXAMPLES_STATES: route({
+    routeId: "EXAMPLES_STATES",
+    path: "/examples/states",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "example-page",
+    errorSurface: "route-boundary",
+    chunkId: "route-examples-states",
+    title: "화면 상태",
+    navigationLabel: "화면 상태",
+    navigationOrder: 30,
+  }),
+  EXAMPLES_AUTH: route({
+    routeId: "EXAMPLES_AUTH",
+    path: "/examples/auth",
+    paramsSchema: null,
+    searchSchema: null,
+    access: "public",
+    loadingSurface: "example-page",
+    errorSurface: "route-boundary",
+    chunkId: "route-examples-auth",
+    title: "인증 연동",
+    navigationLabel: "인증 연동",
+    navigationOrder: 40,
  }),
  SAMPLE_RESOURCE_LIST: route({
    routeId: "SAMPLE_RESOURCE_LIST",
@@ -34,6 +79,9 @@ export const ROUTE_REGISTRY = Object.freeze({
    loadingSurface: "sample-resource-list",
    errorSurface: "feature-boundary",
    chunkId: "route-sample-resources",
+    title: "보호된 연동 지점",
+    navigationLabel: "보호된 연동 지점",
+    navigationOrder: 50,
  }),
  NOT_FOUND: route({
    routeId: "NOT_FOUND",
@@ -44,9 +92,22 @@ export const ROUTE_REGISTRY = Object.freeze({
    loadingSurface: "none",
    errorSurface: "not-found",
    chunkId: "route-not-found",
+    title: "페이지를 찾을 수 없음",
+    navigationLabel: null,
+    navigationOrder: null,
  }),
 });

+export const NAVIGATION_ROUTES = Object.freeze(
+  Object.values(ROUTE_REGISTRY)
+    .filter((definition) => definition.navigationOrder !== null)
+    .sort(
+      (left, right) =>
+        /** @type {number} */ (left.navigationOrder) -
+        /** @type {number} */ (right.navigationOrder),
+    ),
+);
+
 /** @param {string} routeId */
 export function getRoute(routeId) {
  const registry = /** @type {Record<string, Readonly<RouteDefinition>>} */ (
@@ -1,23 +1,40 @@
+import { useId } from "react";
+
+import { errorMessage } from "./error-copy.js";
+import { Button } from "./ui/button.jsx";
+
 /** @param {{ label?: string }} props */
 export function LoadingSurface({ label = "불러오는 중" }) {
  return (
    <section
+      className="state-surface state-surface--loading"
      aria-busy="true"
      aria-label={label}
      aria-live="polite"
      aria-atomic="true"
    >
      <div className="ui-skeleton" aria-hidden="true" />
-      <span className="sr-only">{label}</span>
+      <span className="visually-hidden">{label}</span>
    </section>
  );
 }

-/** @param {{ title?: string, action?: React.ReactNode }} props */
-export function EmptySurface({ title = "표시할 항목이 없습니다.", action }) {
+/**
+ * @param {{
+ *   title?: string,
+ *   description?: string,
+ *   action?: React.ReactNode
+ * }} props
+ */
+export function EmptySurface({
+  title = "표시할 항목이 없습니다.",
+  description,
+  action,
+}) {
  return (
-    <section className="ui-empty" aria-live="polite">
-      <p>{title}</p>
+    <section className="ui-empty state-surface" aria-live="polite">
+      <h2>{title}</h2>
+      {description ? <p>{description}</p> : null}
      {action}
    </section>
  );
@@ -32,17 +49,24 @@ export function EmptySurface({ title = "표시할 항목이 없습니다.", acti
 * }} props
 */
 export function TerminalErrorSurface({ userMessageKey, action, onAction }) {
+  const messageId = useId();
+  const actionLabels = Object.freeze({
+    retry: "다시 시도",
+    reauth: "로그인",
+    navigate: "안전한 화면으로 이동",
+    "reload-once": "한 번 새로고침",
+    "contact-support": "지원 정보 확인",
+  });
  return (
    <section
-      className="ui-terminal-error"
+      className="ui-terminal-error state-surface state-surface--danger"
      role="alert"
-      aria-labelledby="terminal-error-message"
+      aria-labelledby={messageId}
+      data-message-key={userMessageKey}
    >
-      <p id="terminal-error-message">{userMessageKey}</p>
+      <h2 id={messageId}>{errorMessage(userMessageKey)}</h2>
      {action !== "none" && (
-        <button className="ui-button" type="button" onClick={onAction}>
-          {action}
-        </button>
+        <Button onClick={onAction}>{actionLabels[action]}</Button>
      )}
    </section>
  );
@@ -0,0 +1,21 @@
+const ERROR_MESSAGES = Object.freeze({
+  "error.network_unreachable": "네트워크에 연결할 수 없습니다.",
+  "error.request_timeout": "요청 시간이 초과되었습니다.",
+  "error.auth_required": "계속하려면 로그인이 필요합니다.",
+  "error.auth_integration_failure": "로그인 연동을 사용할 수 없습니다.",
+  "error.forbidden": "이 작업을 수행할 권한이 없습니다.",
+  "error.not_found": "요청한 항목을 찾을 수 없습니다.",
+  "error.rate_limited": "요청이 많습니다. 잠시 후 다시 시도해 주세요.",
+  "error.server_failure": "요청을 완료하지 못했습니다.",
+  "error.chunk_load_failure": "새 화면 파일을 불러오지 못했습니다.",
+  "error.render_failure": "화면을 표시하지 못했습니다.",
+  "error.unknown_failure": "예상하지 못한 문제가 발생했습니다.",
+});
+
+/** @param {string} messageKey */
+export function errorMessage(messageKey) {
+  const messages = /** @type {Readonly<Record<string, string>>} */ (
+    ERROR_MESSAGES
+  );
+  return messages[messageKey] ?? "요청을 완료하지 못했습니다.";
+}
@@ -0,0 +1,27 @@
+import { useEffect, useRef } from "react";
+
+/**
+ * @param {{
+ *   title: string,
+ *   description?: string,
+ *   eyebrow?: string
+ * }} props
+ */
+export function PageHeader({ title, description, eyebrow }) {
+  const headingRef = useRef(/** @type {HTMLHeadingElement | null} */ (null));
+
+  useEffect(() => {
+    document.title = `${title} · Frontend Skeleton`;
+    headingRef.current?.focus();
+  }, [title]);
+
+  return (
+    <header className="page-header">
+      {eyebrow ? <p className="page-header__eyebrow">{eyebrow}</p> : null}
+      <h1 ref={headingRef} tabIndex={-1} data-route-heading>
+        {title}
+      </h1>
+      {description ? <p className="page-header__description">{description}</p> : null}
+    </header>
+  );
+}
@@ -0,0 +1,69 @@
+import { Button } from "./ui/button.jsx";
+
+/**
+ * @param {{
+ *   eyebrow: string,
+ *   title: string,
+ *   description: string,
+ *   actionLabel?: string,
+ *   onAction?: () => void,
+ *   tone?: "neutral" | "danger" | "warning"
+ * }} props
+ */
+function StateSurface({
+  eyebrow,
+  title,
+  description,
+  actionLabel,
+  onAction,
+  tone = "neutral",
+}) {
+  return (
+    <section className={`state-surface state-surface--${tone}`}>
+      <p className="state-surface__eyebrow">{eyebrow}</p>
+      <h2>{title}</h2>
+      <p>{description}</p>
+      {actionLabel ? <Button onClick={onAction}>{actionLabel}</Button> : null}
+    </section>
+  );
+}
+
+/** @param {{ onSignIn?: () => void }} props */
+export function AuthRequiredSurface({ onSignIn }) {
+  return (
+    <StateSurface
+      eyebrow="401 · 인증 필요"
+      title="로그인이 필요합니다."
+      description="세션을 시작한 뒤 이전 작업을 안전하게 계속할 수 있습니다."
+      actionLabel="로그인 시작"
+      onAction={onSignIn}
+    />
+  );
+}
+
+/** @param {{ onNavigate?: () => void }} props */
+export function ForbiddenSurface({ onNavigate }) {
+  return (
+    <StateSurface
+      eyebrow="403 · 권한 없음"
+      title="접근할 수 없습니다."
+      description="권한을 확인하거나 접근 가능한 화면으로 이동하세요."
+      actionLabel="안전한 화면으로 이동"
+      onAction={onNavigate}
+      tone="warning"
+    />
+  );
+}
+
+/** @param {{ onNavigate?: () => void }} props */
+export function NotFoundSurface({ onNavigate }) {
+  return (
+    <StateSurface
+      eyebrow="404 · 찾을 수 없음"
+      title="요청한 화면이 없습니다."
+      description="주소를 확인하거나 시작 화면으로 돌아가세요."
+      actionLabel="시작 화면으로 이동"
+      onAction={onNavigate}
+    />
+  );
+}
@@ -0,0 +1,36 @@
+/**
+ * @param {{
+ *   title: string,
+ *   children?: React.ReactNode,
+ *   variant?: "info" | "success" | "warning" | "danger",
+ *   onDismiss?: () => void
+ * }} props
+ */
+export function Alert({
+  title,
+  children,
+  variant = "info",
+  onDismiss,
+}) {
+  return (
+    <section
+      className={`ui-alert ui-alert--${variant}`}
+      role={variant === "danger" ? "alert" : "status"}
+    >
+      <div>
+        <strong>{title}</strong>
+        {children ? <div className="ui-alert__content">{children}</div> : null}
+      </div>
+      {onDismiss ? (
+        <button
+          className="ui-alert__dismiss"
+          type="button"
+          aria-label={`${title} 알림 닫기`}
+          onClick={onDismiss}
+        >
+          ×
+        </button>
+      ) : null}
+    </section>
+  );
+}
@@ -0,0 +1,9 @@
+/**
+ * @param {{
+ *   children: React.ReactNode,
+ *   variant?: "neutral" | "info" | "success" | "warning" | "danger"
+ * }} props
+ */
+export function Badge({ children, variant = "neutral" }) {
+  return <span className={`ui-badge ui-badge--${variant}`}>{children}</span>;
+}
@@ -0,0 +1,24 @@
+/**
+ * @param {React.ButtonHTMLAttributes<HTMLButtonElement> & {
+ *   variant?: "primary" | "secondary" | "danger" | "ghost",
+ *   size?: "default" | "compact"
+ * }} props
+ */
+export function Button({
+  variant = "primary",
+  size = "default",
+  className = "",
+  type = "button",
+  ...props
+}) {
+  const classes = [
+    "ui-button",
+    `ui-button--${variant}`,
+    size === "compact" ? "ui-button--compact" : "",
+    className,
+  ]
+    .filter(Boolean)
+    .join(" ");
+
+  return <button {...props} className={classes} type={type} />;
+}
@@ -0,0 +1,28 @@
+import { useId } from "react";
+
+/**
+ * @param {{
+ *   title: string,
+ *   description?: string,
+ *   children?: React.ReactNode,
+ *   footer?: React.ReactNode,
+ *   className?: string
+ * }} props
+ */
+export function Card({ title, description, children, footer, className = "" }) {
+  const titleId = useId();
+
+  return (
+    <article
+      className={`ui-card ${className}`.trim()}
+      aria-labelledby={titleId}
+    >
+      <div className="ui-card__header">
+        <h3 id={titleId}>{title}</h3>
+        {description ? <p>{description}</p> : null}
+      </div>
+      {children ? <div className="ui-card__content">{children}</div> : null}
+      {footer ? <footer className="ui-card__footer">{footer}</footer> : null}
+    </article>
+  );
+}
@@ -0,0 +1,88 @@
+import { useEffect, useId, useRef } from "react";
+
+/**
+ * @param {{
+ *   open: boolean,
+ *   onClose: () => void,
+ *   title: string,
+ *   description?: string,
+ *   children?: React.ReactNode,
+ *   actions?: React.ReactNode
+ * }} props
+ */
+export function Dialog({
+  open,
+  onClose,
+  title,
+  description,
+  children,
+  actions,
+}) {
+  const dialogRef = useRef(/** @type {HTMLDialogElement | null} */ (null));
+  const previousFocusRef = useRef(/** @type {HTMLElement | null} */ (null));
+  const titleId = useId();
+  const descriptionId = useId();
+
+  useEffect(() => {
+    const dialog = dialogRef.current;
+    if (!dialog) return;
+
+    if (open) {
+      previousFocusRef.current =
+        document.activeElement instanceof HTMLElement
+          ? document.activeElement
+          : null;
+      if (!dialog.open) {
+        if (typeof dialog.showModal === "function") dialog.showModal();
+        else dialog.setAttribute("open", "");
+      }
+      const firstFocusable = dialog.querySelector(
+        "[autofocus], button, [href], input, select, textarea, [tabindex]:not([tabindex='-1'])",
+      );
+      if (firstFocusable instanceof HTMLElement) firstFocusable.focus();
+      return;
+    }
+
+    if (dialog.open) {
+      if (typeof dialog.close === "function") dialog.close();
+      else dialog.removeAttribute("open");
+    }
+    previousFocusRef.current?.focus();
+    previousFocusRef.current = null;
+  }, [open]);
+
+  return (
+    <dialog
+      className="ui-dialog"
+      ref={dialogRef}
+      aria-labelledby={titleId}
+      aria-describedby={description ? descriptionId : undefined}
+      onCancel={(event) => {
+        event.preventDefault();
+        onClose();
+      }}
+      onClick={(event) => {
+        if (event.target === event.currentTarget) onClose();
+      }}
+    >
+      <div className="ui-dialog__surface">
+        <header className="ui-dialog__header">
+          <div>
+            <h2 id={titleId}>{title}</h2>
+            {description ? <p id={descriptionId}>{description}</p> : null}
+          </div>
+          <button
+            className="ui-dialog__close"
+            type="button"
+            aria-label={`${title} 닫기`}
+            onClick={onClose}
+          >
+            ×
+          </button>
+        </header>
+        {children ? <div className="ui-dialog__content">{children}</div> : null}
+        {actions ? <footer className="ui-dialog__actions">{actions}</footer> : null}
+      </div>
+    </dialog>
+  );
+}
@@ -0,0 +1,52 @@
+import { useId } from "react";
+
+/**
+ * @param {Omit<React.InputHTMLAttributes<HTMLInputElement>, "id"> & {
+ *   id?: string,
+ *   label: string,
+ *   description?: string,
+ *   error?: string
+ * }} props
+ */
+export function TextField({
+  id,
+  label,
+  description,
+  error,
+  className = "",
+  required,
+  ...inputProps
+}) {
+  const generatedId = useId();
+  const inputId = id ?? `field-${generatedId}`;
+  const descriptionId = description ? `${inputId}-description` : undefined;
+  const errorId = error ? `${inputId}-error` : undefined;
+  const describedBy = [descriptionId, errorId].filter(Boolean).join(" ");
+
+  return (
+    <div className={`ui-field ${className}`.trim()}>
+      <label className="ui-field__label" htmlFor={inputId}>
+        {label}
+        {required ? <span aria-hidden="true"> *</span> : null}
+      </label>
+      {description ? (
+        <p className="ui-field__description" id={descriptionId}>
+          {description}
+        </p>
+      ) : null}
+      <input
+        {...inputProps}
+        className="ui-field__input"
+        id={inputId}
+        required={required}
+        aria-describedby={describedBy || undefined}
+        aria-invalid={error ? "true" : undefined}
+      />
+      {error ? (
+        <p className="ui-field__error" id={errorId}>
+          {error}
+        </p>
+      ) : null}
+    </div>
+  );
+}
@@ -0,0 +1,80 @@
+import { useState } from "react";
+import { useLocation } from "react-router-dom";
+
+import { PageHeader } from "../components/page-header.jsx";
+import { useSession } from "../providers/session-provider.jsx";
+
+export default function AuthExamplePage() {
+  const location = useLocation();
+  const { sessionState, beginSignIn, signOut, recover } = useSession();
+  const [pending, setPending] = useState(false);
+  const [failed, setFailed] = useState(false);
+
+  /** @param {() => Promise<unknown>} action */
+  async function execute(action) {
+    setPending(true);
+    setFailed(false);
+    try {
+      await action();
+    } catch {
+      setFailed(true);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="예제"
+        title="인증 연동"
+        description="스켈레톤은 자격 증명을 소유하지 않고 외부 인증 구현이 연결될 포트와 화면 상태만 제공합니다."
+      />
+      <section className="ui-panel auth-example" aria-labelledby="auth-state-title">
+        <div>
+          <h2 id="auth-state-title">현재 세션 상태</h2>
+          <output className="session-status" data-state={sessionState}>
+            {sessionState}
+          </output>
+        </div>
+        <div className="button-row">
+          <button
+            className="ui-button"
+            type="button"
+            disabled={pending || sessionState === "integration-failed"}
+            onClick={() =>
+              void execute(() =>
+                beginSignIn(`${location.pathname}${location.search}`),
+              )
+            }
+          >
+            로그인 시작
+          </button>
+          <button
+            className="ui-button ui-button--secondary"
+            type="button"
+            disabled={pending || sessionState !== "authenticated"}
+            onClick={() => void execute(signOut)}
+          >
+            로그아웃
+          </button>
+          <button
+            className="ui-button ui-button--secondary"
+            type="button"
+            disabled={pending || sessionState !== "recovery-pending"}
+            onClick={() => void execute(recover)}
+          >
+            세션 복구
+          </button>
+        </div>
+        {sessionState === "integration-failed" ? (
+          <p role="status">
+            외부 인증 소유자가 연결되지 않았습니다. 런타임 호스트의 인증
+            계약을 연결하세요.
+          </p>
+        ) : null}
+        {failed ? <p role="alert">인증 작업을 완료하지 못했습니다.</p> : null}
+      </section>
+    </section>
+  );
+}
@@ -0,0 +1,98 @@
+import { useState } from "react";
+
+import { deriveAsyncState } from "../../application/view-models/async-state.js";
+import { createFailure } from "../../contracts/errors.js";
+import {
+  AsyncSurface,
+  EmptySurface,
+  LoadingSurface,
+  TerminalErrorSurface,
+} from "../components/async-surface.jsx";
+import { PageHeader } from "../components/page-header.jsx";
+import {
+  AuthRequiredSurface,
+  ForbiddenSurface,
+  NotFoundSurface,
+} from "../components/state-surfaces.jsx";
+import { Button } from "../components/ui/button.jsx";
+import { Card } from "../components/ui/card.jsx";
+
+export default function StateGalleryPage() {
+  const [lastAction, setLastAction] = useState(
+    "상태 화면의 작업을 선택하면 결과가 여기에 표시됩니다.",
+  );
+  const refreshingState = deriveAsyncState({
+    data: ["기존 데이터"],
+    isFetching: true,
+  });
+
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="예제"
+        title="화면 상태"
+        description="로딩, 빈 화면, 오류, 인증 필요와 권한 없음 상태가 다음 행동까지 일관되게 안내합니다."
+      />
+
+      <section className="gallery-section" aria-labelledby="async-states-title">
+        <header className="gallery-section__header">
+          <h2 id="async-states-title">비동기 데이터 상태</h2>
+          <p>초기 로딩과 백그라운드 갱신을 구분해 기존 콘텐츠를 보존합니다.</p>
+        </header>
+        <div className="component-grid component-grid--two">
+          <Card title="초기 로딩">
+            <LoadingSurface label="예제 데이터를 불러오는 중" />
+          </Card>
+          <Card title="백그라운드 갱신">
+            <AsyncSurface state={refreshingState}>
+              <div className="state-preview-content">기존 콘텐츠는 계속 표시됩니다.</div>
+            </AsyncSurface>
+          </Card>
+          <Card title="빈 화면">
+            <EmptySurface
+              title="아직 표시할 항목이 없습니다."
+              description="첫 항목을 추가하거나 필터를 초기화할 수 있습니다."
+              action={
+                <Button onClick={() => setLastAction("빈 화면 작업을 실행했습니다.")}>
+                  첫 작업 시작
+                </Button>
+              }
+            />
+          </Card>
+          <Card title="복구 가능한 오류">
+            <TerminalErrorSurface
+              userMessageKey={
+                createFailure("NETWORK_UNREACHABLE", "EXAMPLE", 0)
+                  .userMessageKey
+              }
+              action="retry"
+              onAction={() => setLastAction("오류 요청을 다시 시도했습니다.")}
+            />
+          </Card>
+        </div>
+      </section>
+
+      <section className="gallery-section" aria-labelledby="access-states-title">
+        <header className="gallery-section__header">
+          <h2 id="access-states-title">접근과 탐색 상태</h2>
+          <p>인증 여부와 서버 권한 결과를 서로 다른 상태로 전달합니다.</p>
+        </header>
+        <div className="component-grid component-grid--three">
+          <AuthRequiredSurface
+            onSignIn={() => setLastAction("로그인 연동 작업을 시작했습니다.")}
+          />
+          <ForbiddenSurface
+            onNavigate={() => setLastAction("접근 가능한 화면으로 이동합니다.")}
+          />
+          <NotFoundSurface
+            onNavigate={() => setLastAction("시작 화면으로 이동합니다.")}
+          />
+        </div>
+      </section>
+
+      <output className="gallery-notice" aria-live="polite">
+        {lastAction}
+      </output>
+    </section>
+  );
+}
@@ -0,0 +1,185 @@
+import { useState } from "react";
+
+import { PageHeader } from "../components/page-header.jsx";
+import { Alert } from "../components/ui/alert.jsx";
+import { Badge } from "../components/ui/badge.jsx";
+import { Button } from "../components/ui/button.jsx";
+import { Card } from "../components/ui/card.jsx";
+import { Dialog } from "../components/ui/dialog.jsx";
+import { TextField } from "../components/ui/text-field.jsx";
+
+const COLOR_TOKENS = Object.freeze([
+  ["Surface", "--color-surface"],
+  ["Muted surface", "--color-surface-muted"],
+  ["Content", "--color-content"],
+  ["Muted content", "--color-content-muted"],
+  ["Action", "--color-action"],
+  ["Danger", "--color-danger"],
+  ["Focus", "--color-focus"],
+]);
+
+export default function UiGalleryPage() {
+  const [projectName, setProjectName] = useState("");
+  const [fieldTouched, setFieldTouched] = useState(false);
+  const [dialogOpen, setDialogOpen] = useState(false);
+  const [notice, setNotice] = useState(
+    "구성요소를 조작하면 결과가 여기에 표시됩니다.",
+  );
+  const [alertVisible, setAlertVisible] = useState(true);
+  const fieldError =
+    fieldTouched && projectName.trim().length === 0
+      ? "프로젝트 이름을 입력해 주세요."
+      : undefined;
+
+  /** @param {React.FormEvent<HTMLFormElement>} event */
+  function submitExample(event) {
+    event.preventDefault();
+    setFieldTouched(true);
+    if (projectName.trim().length === 0) {
+      setNotice("입력값을 확인해 주세요.");
+      return;
+    }
+    setNotice(`“${projectName.trim()}” 입력을 확인했습니다.`);
+  }
+
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="예제"
+        title="UI 구성요소"
+        description="제품 도메인과 독립적인 공통 컨트롤, 피드백, 표면과 디자인 토큰을 직접 조작할 수 있습니다."
+      />
+
+      <section className="gallery-section" aria-labelledby="controls-title">
+        <header className="gallery-section__header">
+          <h2 id="controls-title">버튼과 입력</h2>
+          <p>키보드, 비활성 상태, 오류 설명을 포함한 기본 상호작용입니다.</p>
+        </header>
+        <div className="component-grid component-grid--two">
+          <Card title="버튼" description="의미와 위험도에 따라 변형을 선택합니다.">
+            <div className="button-row">
+              <Button onClick={() => setNotice("기본 작업을 실행했습니다.")}>
+                기본 작업
+              </Button>
+              <Button
+                variant="secondary"
+                onClick={() => setNotice("보조 작업을 실행했습니다.")}
+              >
+                보조 작업
+              </Button>
+              <Button
+                variant="danger"
+                onClick={() => setNotice("위험 작업 예제를 선택했습니다.")}
+              >
+                위험 작업
+              </Button>
+              <Button disabled>사용 불가</Button>
+            </div>
+          </Card>
+          <Card title="입력창" description="레이블과 도움말, 오류가 입력에 연결됩니다.">
+            <form className="example-form" noValidate onSubmit={submitExample}>
+              <TextField
+                label="프로젝트 이름"
+                description="새 도메인을 연결할 때 사용할 중립적인 예제입니다."
+                error={fieldError}
+                value={projectName}
+                required
+                onChange={(event) => setProjectName(event.currentTarget.value)}
+              />
+              <Button type="submit">입력 확인</Button>
+            </form>
+          </Card>
+        </div>
+      </section>
+
+      <section className="gallery-section" aria-labelledby="feedback-title">
+        <header className="gallery-section__header">
+          <h2 id="feedback-title">피드백과 모달</h2>
+          <p>상태 전달은 색에만 의존하지 않으며, 모든 제어에는 이름이 있습니다.</p>
+        </header>
+        <div className="component-grid component-grid--two">
+          <Card title="알림과 배지" description="짧은 상태와 문맥형 피드백입니다.">
+            <div className="component-stack">
+              {alertVisible ? (
+                <Alert
+                  title="설정이 저장되었습니다."
+                  variant="success"
+                  onDismiss={() => setAlertVisible(false)}
+                >
+                  <p>운영 환경에는 실제 저장 포트를 연결하세요.</p>
+                </Alert>
+              ) : (
+                <Button
+                  variant="secondary"
+                  onClick={() => setAlertVisible(true)}
+                >
+                  알림 다시 표시
+                </Button>
+              )}
+              <div className="badge-row" aria-label="배지 변형">
+                <Badge>중립</Badge>
+                <Badge variant="info">정보</Badge>
+                <Badge variant="success">준비됨</Badge>
+                <Badge variant="warning">확인 필요</Badge>
+                <Badge variant="danger">실패</Badge>
+              </div>
+            </div>
+          </Card>
+          <Card title="모달" description="배경과 키보드 Esc로 닫고 포커스를 복원합니다.">
+            <Button onClick={() => setDialogOpen(true)}>모달 열기</Button>
+            <Dialog
+              open={dialogOpen}
+              onClose={() => setDialogOpen(false)}
+              title="연동 확인"
+              description="도메인 작업을 실행하기 전 확인 화면의 기본 구조입니다."
+              actions={
+                <>
+                  <Button
+                    variant="secondary"
+                    onClick={() => setDialogOpen(false)}
+                  >
+                    취소
+                  </Button>
+                  <Button
+                    onClick={() => {
+                      setNotice("모달의 확인 작업을 실행했습니다.");
+                      setDialogOpen(false);
+                    }}
+                  >
+                    확인
+                  </Button>
+                </>
+              }
+            >
+              <p>민감한 값이나 구현 세부정보는 확인 문구에 포함하지 않습니다.</p>
+            </Dialog>
+          </Card>
+        </div>
+      </section>
+
+      <section className="gallery-section" aria-labelledby="tokens-title">
+        <header className="gallery-section__header">
+          <h2 id="tokens-title">디자인 토큰</h2>
+          <p>구성요소가 사용하는 의미 기반 색상과 형태 토큰입니다.</p>
+        </header>
+        <div className="token-grid">
+          {COLOR_TOKENS.map(([label, token]) => (
+            <article className="token-swatch" key={token}>
+              <span
+                className="token-swatch__color"
+                style={{ backgroundColor: `var(${token})` }}
+                aria-hidden="true"
+              />
+              <strong>{label}</strong>
+              <code>{token}</code>
+            </article>
+          ))}
+        </div>
+      </section>
+
+      <output className="gallery-notice" aria-live="polite">
+        {notice}
+      </output>
+    </section>
+  );
+}
@@ -0,0 +1,160 @@
+import { useEffect, useState } from "react";
+import { NavLink, Outlet, useLocation } from "react-router-dom";
+
+import { NAVIGATION_ROUTES, routePath } from "../../contracts/routes.js";
+import { useSession } from "../providers/session-provider.jsx";
+import { useTheme } from "../providers/theme-provider.jsx";
+
+const SESSION_LABELS = Object.freeze({
+  authenticated: "인증됨",
+  unauthenticated: "로그인 전",
+  "recovery-pending": "복구 대기",
+  "integration-failed": "연동 필요",
+});
+
+export function AppShell() {
+  const location = useLocation();
+  const { sessionState, beginSignIn, signOut, recover } = useSession();
+  const { preference, setPreference } = useTheme();
+  const [navigationOpen, setNavigationOpen] = useState(false);
+  const [sessionActionPending, setSessionActionPending] = useState(false);
+  const [sessionActionFailed, setSessionActionFailed] = useState(false);
+
+  useEffect(() => {
+    setNavigationOpen(false);
+  }, [location.pathname]);
+
+  useEffect(() => {
+    if (!navigationOpen) return undefined;
+    /** @param {KeyboardEvent} event */
+    const closeOnEscape = (event) => {
+      if (event.key === "Escape") setNavigationOpen(false);
+    };
+    window.addEventListener("keydown", closeOnEscape);
+    return () => window.removeEventListener("keydown", closeOnEscape);
+  }, [navigationOpen]);
+
+  async function runSessionAction() {
+    setSessionActionPending(true);
+    setSessionActionFailed(false);
+    try {
+      if (sessionState === "authenticated") {
+        await signOut();
+      } else if (sessionState === "recovery-pending") {
+        await recover();
+      } else {
+        await beginSignIn(
+          `${location.pathname}${location.search}${location.hash}`,
+        );
+      }
+    } catch {
+      setSessionActionFailed(true);
+    } finally {
+      setSessionActionPending(false);
+    }
+  }
+
+  const sessionActionLabel =
+    sessionState === "authenticated"
+      ? "로그아웃"
+      : sessionState === "recovery-pending"
+        ? "세션 복구"
+        : "로그인";
+  const integrationAvailable = sessionState !== "integration-failed";
+
+  return (
+    <div className="app-shell">
+      <a className="skip-link" href="#main-content">
+        본문으로 건너뛰기
+      </a>
+      <header className="app-shell__header">
+        <button
+          className="app-shell__menu-button"
+          type="button"
+          aria-controls="primary-navigation"
+          aria-expanded={navigationOpen}
+          onClick={() => setNavigationOpen((open) => !open)}
+        >
+          <span aria-hidden="true">☰</span>
+          <span>메뉴</span>
+        </button>
+        <NavLink className="app-shell__brand" to={routePath("APP_HOME")}>
+          Frontend Skeleton
+        </NavLink>
+        <div className="app-shell__session">
+          <label className="visually-hidden" htmlFor="theme-preference">
+            색상 테마
+          </label>
+          <select
+            className="theme-selector"
+            id="theme-preference"
+            value={preference}
+            onChange={(event) =>
+              setPreference(
+                /** @type {"system" | "light" | "dark"} */ (
+                  event.currentTarget.value
+                ),
+              )
+            }
+          >
+            <option value="system">시스템 테마</option>
+            <option value="light">라이트 테마</option>
+            <option value="dark">다크 테마</option>
+          </select>
+          <span className="session-status" data-state={sessionState}>
+            {SESSION_LABELS[sessionState]}
+          </span>
+          {integrationAvailable ? (
+            <button
+              className="ui-button ui-button--compact"
+              type="button"
+              disabled={sessionActionPending}
+              onClick={() => void runSessionAction()}
+            >
+              {sessionActionPending ? "처리 중…" : sessionActionLabel}
+            </button>
+          ) : null}
+        </div>
+        {sessionActionFailed ? (
+          <p className="app-shell__session-error" role="alert">
+            세션 작업을 완료하지 못했습니다.
+          </p>
+        ) : null}
+      </header>
+      <aside
+        className="app-shell__sidebar"
+        data-open={navigationOpen}
+        aria-label="사이드바"
+      >
+        <nav id="primary-navigation" aria-label="주요 탐색">
+          <ul className="app-navigation">
+            {NAVIGATION_ROUTES.map((definition) => (
+              <li key={definition.routeId}>
+                <NavLink
+                  className={({ isActive }) =>
+                    `app-navigation__link${isActive ? " is-active" : ""}`
+                  }
+                  end={definition.path === "/"}
+                  to={definition.path}
+                >
+                  {definition.navigationLabel}
+                </NavLink>
+              </li>
+            ))}
+          </ul>
+        </nav>
+      </aside>
+      {navigationOpen ? (
+        <button
+          className="app-shell__scrim"
+          type="button"
+          aria-label="메뉴 닫기"
+          onClick={() => setNavigationOpen(false)}
+        />
+      ) : null}
+      <main className="app-shell__content" id="main-content" tabIndex={-1}>
+        <Outlet />
+      </main>
+    </div>
+  );
+}
@@ -0,0 +1,56 @@
+import { Link } from "react-router-dom";
+
+import { routePath } from "../../contracts/routes.js";
+import { PageHeader } from "../components/page-header.jsx";
+
+const READINESS_ITEMS = Object.freeze([
+  {
+    title: "실행 계약",
+    description: "런타임 설정, 릴리스 정합성, 오류 경계가 마운트 전에 검증됩니다.",
+  },
+  {
+    title: "교체 가능한 연동",
+    description: "인증, HTTP, 캐시, 저장소, 텔레메트리가 포트 뒤에 분리되어 있습니다.",
+  },
+  {
+    title: "접근 가능한 화면",
+    description: "키보드 탐색, 포커스 이동, 반응형 앱 셸의 기본 동작이 준비되어 있습니다.",
+  },
+]);
+
+export default function HomePage() {
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="프로젝트 시작점"
+        title="Clean Architecture Frontend"
+        description="도메인을 추가하기 전에 실행 구조와 범용 사용자 경험을 확인할 수 있는 중립적인 스켈레톤입니다."
+      />
+      <div className="readiness-grid" aria-label="구현 준비 상태">
+        {READINESS_ITEMS.map((item) => (
+          <article className="ui-panel" key={item.title}>
+            <h2>{item.title}</h2>
+            <p>{item.description}</p>
+          </article>
+        ))}
+      </div>
+      <section className="ui-panel starter-actions" aria-labelledby="starter-title">
+        <div>
+          <h2 id="starter-title">준비된 화면 살펴보기</h2>
+          <p>공통 구성요소와 비동기 화면 상태를 예제 라우트에서 확인하세요.</p>
+        </div>
+        <div className="button-row">
+          <Link className="ui-button" to={routePath("EXAMPLES_UI")}>
+            UI 구성요소 보기
+          </Link>
+          <Link
+            className="ui-button ui-button--secondary"
+            to={routePath("EXAMPLES_STATES")}
+          >
+            화면 상태 보기
+          </Link>
+        </div>
+      </section>
+    </section>
+  );
+}
@@ -0,0 +1,20 @@
+import { Link } from "react-router-dom";
+
+import { routePath } from "../../contracts/routes.js";
+import { PageHeader } from "../components/page-header.jsx";
+
+export default function NotFoundPage() {
+  return (
+    <section className="ui-page">
+      <PageHeader
+        title="페이지를 찾을 수 없습니다."
+        description="주소를 확인하거나 준비된 시작 화면으로 돌아가세요."
+      />
+      <div>
+        <Link className="ui-button" to={routePath("APP_HOME")}>
+          홈으로 이동
+        </Link>
+      </div>
+    </section>
+  );
+}
@@ -0,0 +1,23 @@
+import { PageHeader } from "../components/page-header.jsx";
+import { useSession } from "../providers/session-provider.jsx";
+
+export default function SampleContractPage() {
+  const { sessionState } = useSession();
+
+  return (
+    <section className="ui-page">
+      <PageHeader
+        eyebrow="보호 라우트"
+        title="보호된 연동 지점"
+        description="실제 도메인 기능이 인증된 세션과 연결되는 위치를 보여주는 중립적인 계약 화면입니다."
+      />
+      <section className="ui-panel" aria-labelledby="protected-state-title">
+        <h2 id="protected-state-title">라우트 접근 허용</h2>
+        <p>
+          현재 세션 상태는 <strong>{sessionState}</strong>입니다. 서버의
+          권한 검증은 이 클라이언트 라우트 정책과 별도로 유지해야 합니다.
+        </p>
+      </section>
+    </section>
+  );
+}
@@ -0,0 +1,50 @@
+import { createContext, useContext, useMemo, useSyncExternalStore } from "react";
+
+/**
+ * @typedef {{
+ *   sessionState: import("../../application/ports/auth-session-port.js").SessionState,
+ *   beginSignIn: import("../../application/ports/auth-session-port.js").AuthSessionPort["beginSignIn"],
+ *   signOut: import("../../application/ports/auth-session-port.js").AuthSessionPort["signOut"],
+ *   recover: import("../../application/ports/auth-session-port.js").AuthSessionPort["recover"]
+ * }} SessionContextValue
+ */
+
+const SessionContext = createContext(
+  /** @type {SessionContextValue | null} */ (null),
+);
+
+/**
+ * @param {{
+ *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort,
+ *   children: React.ReactNode
+ * }} props
+ */
+export function SessionProvider({ authSession, children }) {
+  const sessionState = useSyncExternalStore(
+    authSession.subscribe,
+    authSession.getState,
+    authSession.getState,
+  );
+  const value = useMemo(
+    () =>
+      Object.freeze({
+        sessionState,
+        beginSignIn: authSession.beginSignIn,
+        signOut: authSession.signOut,
+        recover: authSession.recover,
+      }),
+    [authSession, sessionState],
+  );
+
+  return (
+    <SessionContext.Provider value={value}>{children}</SessionContext.Provider>
+  );
+}
+
+export function useSession() {
+  const session = useContext(SessionContext);
+  if (!session) {
+    throw new Error("SessionProvider is required");
+  }
+  return session;
+}
@@ -0,0 +1,86 @@
+import {
+  createContext,
+  useContext,
+  useEffect,
+  useLayoutEffect,
+  useMemo,
+  useState,
+} from "react";
+
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../../application/policies/color-scheme.js";
+
+/**
+ * @typedef {{
+ *   preference: "system" | "light" | "dark",
+ *   resolvedTheme: "light" | "dark",
+ *   setPreference: (preference: "system" | "light" | "dark") => void
+ * }} ThemeContextValue
+ */
+
+const ThemeContext = createContext(/** @type {ThemeContextValue | null} */ (null));
+
+function systemPrefersDark() {
+  return (
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-color-scheme: dark)").matches
+  );
+}
+
+/**
+ * @param {{
+ *   storage?: import("../../application/ports/storage-port.js").StoragePort,
+ *   children: React.ReactNode
+ * }} props
+ */
+export function ThemeProvider({ storage, children }) {
+  const [preference, updatePreference] = useState(() => {
+    const result = storage?.read("COLOR_SCHEME");
+    return normalizeColorSchemePreference(
+      result?.ok ? result.value : undefined,
+    );
+  });
+  const [darkSystemTheme, setDarkSystemTheme] = useState(systemPrefersDark);
+  const resolvedTheme = resolveColorScheme(preference, darkSystemTheme);
+
+  useEffect(() => {
+    if (typeof window.matchMedia !== "function") return undefined;
+    const query = window.matchMedia("(prefers-color-scheme: dark)");
+    /** @param {MediaQueryListEvent} event */
+    const update = (event) => setDarkSystemTheme(event.matches);
+    setDarkSystemTheme(query.matches);
+    query.addEventListener("change", update);
+    return () => query.removeEventListener("change", update);
+  }, []);
+
+  useLayoutEffect(() => {
+    document.documentElement.dataset.theme = resolvedTheme;
+    document.documentElement.dataset.themePreference = preference;
+    document.documentElement.style.colorScheme = resolvedTheme;
+  }, [preference, resolvedTheme]);
+
+  const value = useMemo(
+    () =>
+      Object.freeze({
+        preference,
+        resolvedTheme,
+        /** @param {"system" | "light" | "dark"} next */
+        setPreference(next) {
+          const normalized = normalizeColorSchemePreference(next);
+          updatePreference(normalized);
+          storage?.write("COLOR_SCHEME", normalized);
+        },
+      }),
+    [preference, resolvedTheme, storage],
+  );
+
+  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
+}
+
+export function useTheme() {
+  const theme = useContext(ThemeContext);
+  if (!theme) throw new Error("ThemeProvider is required");
+  return theme;
+}
@@ -1,81 +1,272 @@
+import { lazy, Suspense, useState } from "react";
 import {
  BrowserRouter,
-  Link,
  Route,
  Routes,
+  useLocation,
 } from "react-router-dom";

-import { routePath } from "../../contracts/routes.js";
+import { getRoute, routePath } from "../../contracts/routes.js";
+import { RouteBoundary } from "../boundaries/render-error-boundary.jsx";
+import { AppShell } from "../layouts/app-shell.jsx";
+import { PageHeader } from "../components/page-header.jsx";
+import { SessionProvider, useSession } from "../providers/session-provider.jsx";
+import { ThemeProvider } from "../providers/theme-provider.jsx";
 import { decideRouteAccess } from "./navigation-policy.js";

-function HomePage() {
+const HomePage = lazy(() => import("../pages/home-page.jsx"));
+const UiGalleryPage = lazy(() => import("../examples/ui-gallery-page.jsx"));
+const StateGalleryPage = lazy(
+  () => import("../examples/state-gallery-page.jsx"),
+);
+const AuthExamplePage = lazy(
+  () => import("../examples/auth-example-page.jsx"),
+);
+const SampleContractPage = lazy(
+  () => import("../pages/sample-contract-page.jsx"),
+);
+const NotFoundPage = lazy(() => import("../pages/not-found-page.jsx"));
+
+/** @param {{ routeId: string }} props */
+function RouteLoadingSurface({ routeId }) {
+  const definition = getRoute(routeId);
  return (
-    <main className="ui-page">
-      <h1>Clean Architecture Frontend</h1>
-      <p>런타임 계약이 검증되었습니다.</p>
-      <Link to={routePath("SAMPLE_RESOURCE_LIST")}>샘플 리소스</Link>
-    </main>
+    <section className="ui-page route-loading" aria-live="polite" aria-busy="true">
+      <div className="ui-skeleton" aria-hidden="true" />
+      <p>화면을 준비하고 있습니다.</p>
+      <span className="visually-hidden">{definition.title} 로딩 중</span>
+    </section>
  );
 }

-function SamplePlaceholder() {
+function RouteFailureSurface() {
  return (
-    <main className="ui-page">
-      <h1>샘플 리소스</h1>
-      <p>계약 fixture를 준비하고 있습니다.</p>
-    </main>
-  );
-}
-
-function NotFoundPage() {
-  return (
-    <main className="ui-page">
-      <h1>페이지를 찾을 수 없습니다.</h1>
-      <Link to={routePath("APP_HOME")}>홈으로 이동</Link>
-    </main>
+    <section className="ui-page">
+      <PageHeader
+        title="화면을 표시하지 못했습니다."
+        description="잠시 후 페이지를 새로고침해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
+      />
+    </section>
  );
 }

 /**
 * @param {{
- *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort
+ *   routeId: string,
+ *   buildId: string,
+ *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort,
+ *   children: React.ReactNode
 * }} props
 */
-function GuardedSampleRoute({ authSession }) {
-  const decision = decideRouteAccess(
-    "SAMPLE_RESOURCE_LIST",
-    authSession.getState(),
+function RouteSurface({ routeId, buildId, telemetry, children }) {
+  return (
+    <RouteBoundary
+      routeId={routeId}
+      buildId={buildId}
+      telemetry={telemetry}
+      fallback={<RouteFailureSurface />}
+    >
+      <Suspense fallback={<RouteLoadingSurface routeId={routeId} />}>
+        {children}
+      </Suspense>
+    </RouteBoundary>
  );
-  if (!decision.allowed) {
+}
+
+/**
+ * @param {{
+ *   routeId: string,
+ *   children: React.ReactNode
+ * }} props
+ */
+function ProtectedRoute({ routeId, children }) {
+  const location = useLocation();
+  const { sessionState, beginSignIn, recover } = useSession();
+  const [pending, setPending] = useState(false);
+  const [failed, setFailed] = useState(false);
+  const decision = decideRouteAccess(routeId, sessionState);
+
+  async function continueSession() {
+    setPending(true);
+    setFailed(false);
+    try {
+      if (decision.action === "wait-for-session") {
+        await recover();
+      } else {
+        await beginSignIn(
+          `${location.pathname}${location.search}${location.hash}`,
+        );
+      }
+    } catch {
+      setFailed(true);
+    } finally {
+      setPending(false);
+    }
+  }
+
+  if (decision.allowed) return children;
+
+  if (sessionState === "integration-failed") {
    return (
-      <main className="ui-page">
-        <h1>세션이 필요합니다.</h1>
-        <button className="ui-button" type="button">
-          로그인
-        </button>
-      </main>
+      <section className="ui-page">
+        <PageHeader
+          title="로그인 연동이 필요합니다."
+          description="외부 인증 소유자가 런타임에 연결되면 이 보호 라우트를 사용할 수 있습니다."
+        />
+      </section>
    );
  }
-  return <SamplePlaceholder />;
+
+  const recovering = decision.action === "wait-for-session";
+  return (
+    <section className="ui-page">
+      <PageHeader
+        title={recovering ? "세션을 복구하고 있습니다." : "세션이 필요합니다."}
+        description={
+          recovering
+            ? "기존 세션 확인을 계속하려면 복구를 실행하세요."
+            : "이 화면은 인증 연동 지점을 확인하기 위한 보호 라우트입니다."
+        }
+      />
+      <div>
+        <button
+          className="ui-button"
+          type="button"
+          disabled={pending}
+          onClick={() => void continueSession()}
+        >
+          {pending
+            ? "처리 중…"
+            : recovering
+              ? "세션 복구"
+              : "로그인 시작"}
+        </button>
+      </div>
+      {failed ? (
+        <p className="ui-terminal-error" role="alert">
+          세션 작업을 완료하지 못했습니다.
+        </p>
+      ) : null}
+    </section>
+  );
+}
+
+/**
+ * @param {{
+ *   routeId: string,
+ *   buildId: string,
+ *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort,
+ *   children: React.ReactNode
+ * }} props
+ */
+function PublicRoute({ routeId, buildId, telemetry, children }) {
+  return (
+    <RouteSurface routeId={routeId} buildId={buildId} telemetry={telemetry}>
+      {children}
+    </RouteSurface>
+  );
 }

 /**
 * @param {{
 *   authSession: import("../../application/ports/auth-session-port.js").AuthSessionPort,
- *   basename?: string
+ *   basename?: string,
+ *   buildId?: string,
+ *   storage?: import("../../application/ports/storage-port.js").StoragePort,
+ *   telemetry?: import("../../application/ports/telemetry-port.js").TelemetryPort
 * }} props
 */
-export function AppRouter({ authSession, basename = "/" }) {
+export function AppRouter({
+  authSession,
+  basename = "/",
+  buildId = "local-build",
+  storage,
+  telemetry,
+}) {
  return (
    <BrowserRouter basename={basename}>
-      <Routes>
-        <Route path={routePath("APP_HOME")} element={<HomePage />} />
-        <Route
-          path={routePath("SAMPLE_RESOURCE_LIST")}
-          element={<GuardedSampleRoute authSession={authSession} />}
-        />
-        <Route path={routePath("NOT_FOUND")} element={<NotFoundPage />} />
-      </Routes>
+      <ThemeProvider storage={storage}>
+        <SessionProvider authSession={authSession}>
+          <Routes>
+            <Route element={<AppShell />}>
+            <Route
+              index
+              element={
+                <PublicRoute
+                  routeId="APP_HOME"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <HomePage />
+                </PublicRoute>
+              }
+            />
+            <Route
+              path={routePath("EXAMPLES_UI")}
+              element={
+                <PublicRoute
+                  routeId="EXAMPLES_UI"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <UiGalleryPage />
+                </PublicRoute>
+              }
+            />
+            <Route
+              path={routePath("EXAMPLES_STATES")}
+              element={
+                <PublicRoute
+                  routeId="EXAMPLES_STATES"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <StateGalleryPage />
+                </PublicRoute>
+              }
+            />
+            <Route
+              path={routePath("EXAMPLES_AUTH")}
+              element={
+                <PublicRoute
+                  routeId="EXAMPLES_AUTH"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <AuthExamplePage />
+                </PublicRoute>
+              }
+            />
+            <Route
+              path={routePath("SAMPLE_RESOURCE_LIST")}
+              element={
+                <RouteSurface
+                  routeId="SAMPLE_RESOURCE_LIST"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <ProtectedRoute routeId="SAMPLE_RESOURCE_LIST">
+                    <SampleContractPage />
+                  </ProtectedRoute>
+                </RouteSurface>
+              }
+            />
+            <Route
+              path={routePath("NOT_FOUND")}
+              element={
+                <PublicRoute
+                  routeId="NOT_FOUND"
+                  buildId={buildId}
+                  telemetry={telemetry}
+                >
+                  <NotFoundPage />
+                </PublicRoute>
+              }
+            />
+            </Route>
+          </Routes>
+        </SessionProvider>
+      </ThemeProvider>
    </BrowserRouter>
  );
 }
@@ -3,12 +3,28 @@
@theme {
  --color-surface: oklch(0.985 0.003 247);
  --color-surface-muted: oklch(0.94 0.01 247);
+  --color-panel: oklch(1 0 0);
+  --color-border: oklch(0.87 0.015 247);
  --color-content: oklch(0.25 0.025 247);
  --color-content-muted: oklch(0.48 0.025 247);
  --color-action: oklch(0.55 0.18 255);
  --color-action-hover: oklch(0.48 0.2 255);
  --color-danger: oklch(0.55 0.2 25);
+  --color-danger-hover: oklch(0.47 0.2 25);
+  --color-on-action: oklch(1 0 0);
  --color-focus: oklch(0.72 0.16 225);
+  --color-info-content: oklch(0.38 0.16 255);
+  --color-info-surface: oklch(0.95 0.03 255);
+  --color-info-border: oklch(0.75 0.08 250);
+  --color-success-content: oklch(0.35 0.12 155);
+  --color-success-surface: oklch(0.95 0.04 155);
+  --color-success-border: oklch(0.72 0.1 155);
+  --color-warning-content: oklch(0.38 0.12 70);
+  --color-warning-surface: oklch(0.96 0.05 80);
+  --color-warning-border: oklch(0.75 0.12 80);
+  --color-danger-content: oklch(0.42 0.18 25);
+  --color-danger-surface: oklch(0.96 0.035 25);
+  --color-danger-border: oklch(0.72 0.12 25);
  --radius-control: 0.5rem;
  --radius-surface: 0.75rem;
  --spacing-page: 1.5rem;
@@ -22,8 +38,64 @@
    font-family: var(--font-sans);
  }

+  :root[data-theme="dark"] {
+    --color-surface: oklch(0.16 0.02 255);
+    --color-surface-muted: oklch(0.25 0.025 255);
+    --color-panel: oklch(0.205 0.022 255);
+    --color-border: oklch(0.36 0.025 255);
+    --color-content: oklch(0.94 0.012 255);
+    --color-content-muted: oklch(0.74 0.025 255);
+    --color-action: oklch(0.7 0.14 250);
+    --color-action-hover: oklch(0.79 0.12 245);
+    --color-danger: oklch(0.68 0.19 25);
+    --color-danger-hover: oklch(0.76 0.16 25);
+    --color-on-action: oklch(0.16 0.02 255);
+    --color-focus: oklch(0.82 0.15 220);
+    --color-info-content: oklch(0.83 0.09 250);
+    --color-info-surface: oklch(0.27 0.045 255);
+    --color-info-border: oklch(0.55 0.09 250);
+    --color-success-content: oklch(0.83 0.1 155);
+    --color-success-surface: oklch(0.27 0.045 155);
+    --color-success-border: oklch(0.53 0.1 155);
+    --color-warning-content: oklch(0.88 0.1 80);
+    --color-warning-surface: oklch(0.29 0.045 80);
+    --color-warning-border: oklch(0.58 0.11 80);
+    --color-danger-content: oklch(0.84 0.11 25);
+    --color-danger-surface: oklch(0.28 0.055 25);
+    --color-danger-border: oklch(0.56 0.13 25);
+  }
+
  body {
    margin: 0;
+    min-width: 20rem;
+    min-height: 100vh;
+  }
+
+  button,
+  input,
+  textarea,
+  select {
+    font: inherit;
+  }
+
+  a {
+    color: inherit;
+  }
+
+  h1,
+  h2,
+  p {
+    margin-block-start: 0;
+  }
+
+  h1 {
+    font-size: clamp(2rem, 5vw, 3.5rem);
+    line-height: 1.05;
+    letter-spacing: -0.04em;
+  }
+
+  h2 {
+    line-height: 1.25;
  }

  :focus-visible {
@@ -33,22 +105,245 @@
 }

@layer components {
+  .visually-hidden {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    padding: 0;
+    margin: -1px;
+    overflow: hidden;
+    clip: rect(0, 0, 0, 0);
+    white-space: nowrap;
+    border: 0;
+  }
+
+  .skip-link {
+    position: fixed;
+    z-index: 100;
+    top: 0.75rem;
+    left: 0.75rem;
+    padding: 0.75rem 1rem;
+    border-radius: var(--radius-control);
+    color: var(--color-panel);
+    background: var(--color-content);
+    transform: translateY(-200%);
+  }
+
+  .skip-link:focus {
+    transform: translateY(0);
+  }
+
+  .app-shell {
+    display: grid;
+    min-height: 100vh;
+    grid-template-rows: 4.5rem 1fr;
+    grid-template-columns: 15rem minmax(0, 1fr);
+    grid-template-areas:
+      "header header"
+      "sidebar content";
+  }
+
+  .app-shell__header {
+    position: sticky;
+    z-index: 30;
+    top: 0;
+    grid-area: header;
+    display: flex;
+    align-items: center;
+    gap: 1rem;
+    min-width: 0;
+    padding: 0.75rem 1.25rem;
+    border-bottom: 1px solid var(--color-surface-muted);
+    background: color-mix(in oklch, var(--color-panel) 92%, var(--color-surface));
+    box-shadow: 0 1px 8px color-mix(in oklch, var(--color-content) 8%, transparent);
+  }
+
+  .app-shell__brand {
+    overflow: hidden;
+    font-size: 1.05rem;
+    font-weight: 800;
+    text-decoration: none;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .app-shell__menu-button {
+    display: none;
+    align-items: center;
+    gap: 0.4rem;
+    border: 1px solid var(--color-surface-muted);
+    border-radius: var(--radius-control);
+    padding: 0.55rem 0.75rem;
+    color: var(--color-content);
+    background: var(--color-panel);
+    cursor: pointer;
+  }
+
+  .app-shell__session {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    margin-inline-start: auto;
+  }
+
+  .theme-selector {
+    min-height: 2.25rem;
+    max-width: 8.5rem;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-control);
+    padding: 0.35rem 2rem 0.35rem 0.65rem;
+    color: var(--color-content);
+    background: var(--color-panel);
+    cursor: pointer;
+  }
+
+  .app-shell__session-error {
+    position: absolute;
+    top: calc(100% + 0.25rem);
+    right: 1rem;
+    padding: 0.5rem;
+    color: var(--color-danger);
+    background: var(--color-panel);
+  }
+
+  .session-status {
+    display: inline-flex;
+    width: fit-content;
+    align-items: center;
+    border-radius: 999px;
+    padding: 0.3rem 0.65rem;
+    color: var(--color-content-muted);
+    background: var(--color-surface-muted);
+    font-size: 0.8rem;
+    font-weight: 700;
+  }
+
+  .session-status[data-state="authenticated"] {
+    color: var(--color-success-content);
+    background: var(--color-success-surface);
+  }
+
+  .session-status[data-state="integration-failed"] {
+    color: var(--color-danger);
+  }
+
+  .app-shell__sidebar {
+    position: sticky;
+    top: 4.5rem;
+    grid-area: sidebar;
+    height: calc(100vh - 4.5rem);
+    padding: 1.25rem 0.75rem;
+    border-right: 1px solid var(--color-border);
+    background: var(--color-panel);
+  }
+
+  .app-navigation {
+    display: flex;
+    flex-direction: column;
+    gap: 0.25rem;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+
+  .app-navigation__link {
+    display: block;
+    border-radius: var(--radius-control);
+    padding: 0.75rem 0.9rem;
+    color: var(--color-content-muted);
+    font-weight: 650;
+    text-decoration: none;
+  }
+
+  .app-navigation__link:hover {
+    color: var(--color-content);
+    background: var(--color-surface);
+  }
+
+  .app-navigation__link.is-active {
+    color: var(--color-action-hover);
+    background: color-mix(
+      in oklch,
+      var(--color-action) 14%,
+      var(--color-panel)
+    );
+    font-weight: 800;
+  }
+
+  .app-shell__content {
+    grid-area: content;
+    min-width: 0;
+  }
+
  .ui-page {
-    @apply mx-auto flex min-h-screen max-w-4xl flex-col gap-6 p-page;
+    @apply mx-auto flex max-w-6xl flex-col gap-6 p-page;
+    width: 100%;
+    box-sizing: border-box;
  }

  .ui-panel {
-    @apply rounded-surface border border-surface-muted bg-white p-6 shadow-sm;
+    @apply rounded-surface p-6 shadow-sm;
+    border: 1px solid var(--color-border);
+    background: var(--color-panel);
  }

  .ui-button {
-    @apply rounded-control bg-action px-4 py-2 font-semibold text-white;
+    @apply rounded-control bg-action px-4 py-2 font-semibold;
+    display: inline-flex;
+    min-height: 2.75rem;
+    align-items: center;
+    justify-content: center;
+    border: 0;
+    color: var(--color-on-action);
+    text-decoration: none;
+    cursor: pointer;
  }

  .ui-button:hover {
    @apply bg-action-hover;
  }

+  .ui-button:disabled {
+    cursor: not-allowed;
+    opacity: 0.55;
+  }
+
+  .ui-button--secondary {
+    border: 1px solid var(--color-surface-muted);
+    color: var(--color-content);
+    background: var(--color-panel);
+  }
+
+  .ui-button--secondary:hover {
+    color: var(--color-action);
+    background: var(--color-surface);
+  }
+
+  .ui-button--danger {
+    color: var(--color-on-action);
+    background: var(--color-danger);
+  }
+
+  .ui-button--danger:hover {
+    background: var(--color-danger-hover);
+  }
+
+  .ui-button--ghost {
+    color: var(--color-content);
+    background: transparent;
+  }
+
+  .ui-button--ghost:hover {
+    color: var(--color-action);
+    background: var(--color-surface-muted);
+  }
+
+  .ui-button--compact {
+    min-height: 2.25rem;
+    padding: 0.4rem 0.75rem;
+    font-size: 0.85rem;
+  }
+
  .ui-skeleton {
    @apply h-24 animate-pulse rounded-surface bg-surface-muted;
  }
@@ -57,6 +352,486 @@
  .ui-terminal-error {
    @apply rounded-surface border border-surface-muted p-6;
  }
+
+  .ui-field {
+    display: grid;
+    gap: 0.45rem;
+  }
+
+  .ui-field__label {
+    font-weight: 750;
+  }
+
+  .ui-field__description,
+  .ui-field__error {
+    margin: 0;
+    font-size: 0.875rem;
+    line-height: 1.5;
+  }
+
+  .ui-field__description {
+    color: var(--color-content-muted);
+  }
+
+  .ui-field__error {
+    color: var(--color-danger);
+    font-weight: 650;
+  }
+
+  .ui-field__input {
+    width: 100%;
+    min-height: 2.75rem;
+    box-sizing: border-box;
+    border: 1px solid
+      color-mix(in oklch, var(--color-content-muted) 55%, var(--color-panel));
+    border-radius: var(--radius-control);
+    padding: 0.65rem 0.8rem;
+    color: var(--color-content);
+    background: var(--color-panel);
+  }
+
+  .ui-field__input[aria-invalid="true"] {
+    border-color: var(--color-danger);
+  }
+
+  .ui-card {
+    display: flex;
+    min-width: 0;
+    flex-direction: column;
+    gap: 1.25rem;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-surface);
+    padding: 1.25rem;
+    background: var(--color-panel);
+    box-shadow: 0 8px 28px color-mix(in oklch, var(--color-content) 6%, transparent);
+  }
+
+  .ui-card__header h3,
+  .ui-card__header p {
+    margin-block-end: 0;
+  }
+
+  .ui-card__header p {
+    margin-block-start: 0.4rem;
+    color: var(--color-content-muted);
+    line-height: 1.55;
+  }
+
+  .ui-card__content {
+    flex: 1;
+  }
+
+  .ui-card__footer {
+    padding-block-start: 1rem;
+    border-top: 1px solid var(--color-surface-muted);
+  }
+
+  .ui-alert {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 1rem;
+    border: 1px solid var(--color-surface-muted);
+    border-radius: var(--radius-control);
+    padding: 1rem;
+    background: var(--color-surface);
+  }
+
+  .ui-alert--info {
+    border-color: var(--color-info-border);
+    background: var(--color-info-surface);
+  }
+
+  .ui-alert--success {
+    border-color: var(--color-success-border);
+    background: var(--color-success-surface);
+  }
+
+  .ui-alert--warning {
+    border-color: var(--color-warning-border);
+    background: var(--color-warning-surface);
+  }
+
+  .ui-alert--danger {
+    border-color: var(--color-danger-border);
+    background: var(--color-danger-surface);
+  }
+
+  .ui-alert__content,
+  .ui-alert__content p {
+    margin-block: 0.35rem 0;
+    color: var(--color-content-muted);
+  }
+
+  .ui-alert__dismiss,
+  .ui-dialog__close {
+    display: inline-grid;
+    width: 2rem;
+    height: 2rem;
+    flex: 0 0 auto;
+    place-items: center;
+    border: 0;
+    border-radius: var(--radius-control);
+    color: var(--color-content);
+    background: transparent;
+    font-size: 1.35rem;
+    cursor: pointer;
+  }
+
+  .ui-alert__dismiss:hover,
+  .ui-dialog__close:hover {
+    background: color-mix(in oklch, var(--color-content) 8%, transparent);
+  }
+
+  .ui-badge {
+    display: inline-flex;
+    border-radius: 999px;
+    padding: 0.3rem 0.65rem;
+    color: var(--color-content);
+    background: var(--color-surface-muted);
+    font-size: 0.8rem;
+    font-weight: 750;
+  }
+
+  .ui-badge--info {
+    color: var(--color-info-content);
+    background: var(--color-info-surface);
+  }
+
+  .ui-badge--success {
+    color: var(--color-success-content);
+    background: var(--color-success-surface);
+  }
+
+  .ui-badge--warning {
+    color: var(--color-warning-content);
+    background: var(--color-warning-surface);
+  }
+
+  .ui-badge--danger {
+    color: var(--color-danger-content);
+    background: var(--color-danger-surface);
+  }
+
+  .ui-dialog {
+    width: min(34rem, calc(100vw - 2rem));
+    max-height: calc(100vh - 2rem);
+    box-sizing: border-box;
+    overflow: auto;
+    border: 0;
+    border-radius: var(--radius-surface);
+    padding: 0;
+    color: var(--color-content);
+    background: var(--color-panel);
+    box-shadow: 0 24px 70px color-mix(in oklch, var(--color-content) 25%, transparent);
+  }
+
+  .ui-dialog::backdrop {
+    background: color-mix(in oklch, var(--color-content) 55%, transparent);
+    backdrop-filter: blur(2px);
+  }
+
+  .ui-dialog__surface {
+    padding: 1.5rem;
+  }
+
+  .ui-dialog__header {
+    display: flex;
+    align-items: flex-start;
+    justify-content: space-between;
+    gap: 1rem;
+  }
+
+  .ui-dialog__header h2 {
+    margin-block-end: 0.35rem;
+  }
+
+  .ui-dialog__header p,
+  .ui-dialog__content p {
+    color: var(--color-content-muted);
+    line-height: 1.6;
+  }
+
+  .ui-dialog__content {
+    padding-block: 1rem;
+  }
+
+  .ui-dialog__actions {
+    display: flex;
+    flex-wrap: wrap;
+    justify-content: flex-end;
+    gap: 0.75rem;
+    padding-block-start: 1rem;
+    border-top: 1px solid var(--color-surface-muted);
+  }
+
+  .page-header {
+    max-width: 50rem;
+    padding-block: clamp(1rem, 5vw, 3.5rem) 0.5rem;
+  }
+
+  [data-route-heading]:focus {
+    outline: none;
+  }
+
+  .page-header__eyebrow {
+    margin-block-end: 0.75rem;
+    color: var(--color-action);
+    font-size: 0.8rem;
+    font-weight: 800;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+  }
+
+  .page-header__description {
+    max-width: 45rem;
+    color: var(--color-content-muted);
+    font-size: 1.05rem;
+    line-height: 1.7;
+  }
+
+  .readiness-grid {
+    display: grid;
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+    gap: 1rem;
+  }
+
+  .readiness-grid p,
+  .starter-actions p {
+    margin-block-end: 0;
+    color: var(--color-content-muted);
+    line-height: 1.65;
+  }
+
+  .starter-actions,
+  .auth-example {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 1.5rem;
+  }
+
+  .button-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.75rem;
+  }
+
+  .route-loading {
+    padding-block-start: 4rem;
+  }
+
+  .gallery-section {
+    display: grid;
+    gap: 1rem;
+    padding-block: 0.5rem;
+  }
+
+  .gallery-section__header {
+    max-width: 45rem;
+  }
+
+  .gallery-section__header h2,
+  .gallery-section__header p {
+    margin-block-end: 0;
+  }
+
+  .gallery-section__header p {
+    margin-block-start: 0.4rem;
+    color: var(--color-content-muted);
+    line-height: 1.6;
+  }
+
+  .component-grid {
+    display: grid;
+    gap: 1rem;
+  }
+
+  .component-grid--two {
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+  }
+
+  .component-grid--three {
+    grid-template-columns: repeat(3, minmax(0, 1fr));
+  }
+
+  .component-stack,
+  .example-form {
+    display: grid;
+    gap: 1rem;
+  }
+
+  .badge-row {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+  }
+
+  .token-grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(10rem, 1fr));
+    gap: 0.75rem;
+  }
+
+  .token-swatch {
+    display: grid;
+    gap: 0.45rem;
+    min-width: 0;
+    border: 1px solid var(--color-border);
+    border-radius: var(--radius-control);
+    padding: 0.75rem;
+    background: var(--color-panel);
+  }
+
+  .token-swatch__color {
+    height: 4rem;
+    border: 1px solid color-mix(in oklch, var(--color-content) 15%, transparent);
+    border-radius: calc(var(--radius-control) / 1.5);
+  }
+
+  .token-swatch code {
+    overflow: hidden;
+    color: var(--color-content-muted);
+    font-size: 0.75rem;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  .gallery-notice {
+    display: block;
+    width: fit-content;
+    max-width: 100%;
+    box-sizing: border-box;
+    border: 1px solid var(--color-surface-muted);
+    border-radius: 999px;
+    padding: 0.65rem 1rem;
+    color: var(--color-content);
+    background: var(--color-panel);
+    box-shadow: 0 8px 28px color-mix(in oklch, var(--color-content) 10%, transparent);
+    font-size: 0.875rem;
+    font-weight: 650;
+  }
+
+  .state-surface {
+    display: flex;
+    min-height: 12rem;
+    box-sizing: border-box;
+    flex-direction: column;
+    align-items: flex-start;
+    justify-content: center;
+    border: 1px solid var(--color-surface-muted);
+    border-radius: var(--radius-surface);
+    padding: 1.25rem;
+    background: var(--color-surface);
+  }
+
+  .state-surface h2,
+  .state-surface p {
+    margin-block-end: 0.75rem;
+  }
+
+  .state-surface > p:not(.state-surface__eyebrow) {
+    color: var(--color-content-muted);
+    line-height: 1.55;
+  }
+
+  .state-surface__eyebrow {
+    color: var(--color-action-hover);
+    font-size: 0.75rem;
+    font-weight: 800;
+    letter-spacing: 0.04em;
+  }
+
+  .state-surface--warning {
+    border-color: var(--color-warning-border);
+    background: var(--color-warning-surface);
+  }
+
+  .state-surface--danger,
+  .ui-terminal-error {
+    border-color: var(--color-danger-border);
+    background: var(--color-danger-surface);
+  }
+
+  .state-surface--loading {
+    gap: 0.75rem;
+  }
+
+  .state-surface--loading .ui-skeleton {
+    width: 100%;
+  }
+
+  .state-preview-content {
+    border-radius: var(--radius-control);
+    padding: 1rem;
+    background: var(--color-surface);
+  }
+
+  .app-shell__scrim {
+    display: none;
+  }
+}
+
+@media (max-width: 47.999rem) {
+  .app-shell {
+    grid-template-columns: minmax(0, 1fr);
+    grid-template-areas:
+      "header"
+      "content";
+  }
+
+  .app-shell__header {
+    padding-inline: 0.75rem;
+  }
+
+  .app-shell__menu-button {
+    display: inline-flex;
+  }
+
+  .app-shell__sidebar {
+    position: fixed;
+    z-index: 50;
+    top: 4.5rem;
+    bottom: 0;
+    left: 0;
+    display: none;
+    width: min(18rem, 85vw);
+    height: auto;
+    box-sizing: border-box;
+    box-shadow: 10px 0 30px color-mix(in oklch, var(--color-content) 15%, transparent);
+  }
+
+  .app-shell__sidebar[data-open="true"] {
+    display: block;
+  }
+
+  .app-shell__scrim {
+    position: fixed;
+    z-index: 40;
+    inset: 4.5rem 0 0;
+    display: block;
+    border: 0;
+    background: color-mix(in oklch, var(--color-content) 35%, transparent);
+    cursor: pointer;
+  }
+
+  .app-shell__session .session-status {
+    display: none;
+  }
+
+  .app-shell__brand {
+    display: none;
+  }
+
+  .readiness-grid {
+    grid-template-columns: minmax(0, 1fr);
+  }
+
+  .component-grid--two,
+  .component-grid--three {
+    grid-template-columns: minmax(0, 1fr);
+  }
 }

@media (prefers-reduced-motion: reduce) {
@@ -59,8 +59,14 @@ describe("async UI state matrix", () => {
    const state = deriveAsyncState({ failure });
    render(<AsyncSurface state={state} />);

-    expect(screen.getByRole("alert")).toHaveTextContent(failure.userMessageKey);
-    expect(screen.getByRole("button")).toHaveTextContent("retry");
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "요청을 완료하지 못했습니다.",
+    );
+    expect(screen.getByRole("alert")).toHaveAttribute(
+      "data-message-key",
+      failure.userMessageKey,
+    );
+    expect(screen.getByRole("button")).toHaveTextContent("다시 시도");
    expect(screen.getByRole("alert")).not.toHaveTextContent("stack");
  });

@@ -10,6 +10,7 @@ import { AsyncSurface } from "../../src/presentation/components/async-surface.js
 import { BootErrorShell } from "../../src/presentation/boundaries/boot-error-shell.jsx";
 import { FeatureBoundary } from "../../src/presentation/boundaries/render-error-boundary.jsx";

+/** @returns {import("react").ReactNode} */
 function Defect() {
  throw new Error("raw render stack");
 }
@@ -44,7 +45,13 @@ describe("render recovery boundaries", () => {
        <AsyncSurface state={state} />
      </FeatureBoundary>,
    );
-    expect(screen.getByRole("alert")).toHaveTextContent("error.server_failure");
+    expect(screen.getByRole("alert")).toHaveTextContent(
+      "요청을 완료하지 못했습니다.",
+    );
+    expect(screen.getByRole("alert")).toHaveAttribute(
+      "data-message-key",
+      "error.server_failure",
+    );
  });

  it("renders a safe boot shell with no endpoint or stack", () => {
@@ -1,24 +1,72 @@
 // @vitest-environment jsdom

 import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
 import { describe, expect, it } from "vitest";

-import { createAnonymousSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
+import {
+  createAnonymousSessionAdapter,
+  createDemoSessionAdapter,
+} from "../../src/adapters/auth/external-session-adapter.js";
 import { AppRouter } from "../../src/presentation/routes/app-router.jsx";

 describe("application router", () => {
-  it("renders not-found without making an API request", () => {
+  it("renders the app shell and not-found route without an API request", async () => {
    window.history.pushState({}, "", "/missing");
    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+
    expect(
-      screen.getByRole("heading", { name: "페이지를 찾을 수 없습니다." }),
+      await screen.findByRole("heading", {
+        name: "페이지를 찾을 수 없습니다.",
+      }),
    ).toBeVisible();
+    expect(screen.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
+    expect(screen.getByRole("main")).toBeVisible();
  });

-  it("shows session-required UX without claiming authorization", () => {
+  it("navigates between registry-backed example routes", async () => {
+    const user = userEvent.setup();
+    window.history.pushState({}, "", "/");
+    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
+
+    await user.click(
+      await screen.findByRole("link", { name: "UI 구성요소" }),
+    );
+
+    expect(
+      await screen.findByRole("heading", { name: "UI 구성요소", level: 1 }),
+    ).toBeVisible();
+    expect(window.location.pathname).toBe("/examples/ui");
+  });
+
+  it("reacts to demo sign-in and opens the protected integration route", async () => {
+    const user = userEvent.setup();
+    const authSession = createDemoSessionAdapter();
+    window.history.pushState({}, "", "/sample/resources");
+    render(<AppRouter authSession={authSession} />);
+
+    expect(
+      await screen.findByRole("heading", { name: "세션이 필요합니다." }),
+    ).toBeVisible();
+    await user.click(screen.getByRole("button", { name: "로그인 시작" }));
+
+    expect(
+      await screen.findByRole("heading", { name: "보호된 연동 지점" }),
+    ).toBeVisible();
+    expect(screen.getByText("인증됨")).toBeVisible();
+  });
+
+  it("fails closed when the auth integration does not change state", async () => {
+    const user = userEvent.setup();
    window.history.pushState({}, "", "/sample/resources");
    render(<AppRouter authSession={createAnonymousSessionAdapter()} />);
-    expect(screen.getByRole("heading", { name: "세션이 필요합니다." })).toBeVisible();
-    expect(screen.getByRole("button", { name: "로그인" })).toBeVisible();
+
+    await user.click(
+      await screen.findByRole("button", { name: "로그인 시작" }),
+    );
+
+    expect(
+      screen.getByRole("heading", { name: "세션이 필요합니다." }),
+    ).toBeVisible();
  });
 });
@@ -7,9 +7,10 @@ import { SampleResourcePage } from "../../src/sample/contract-fixture/sample-res

 describe("removable sample feature page", () => {
  it("renders the API-to-view-model result through AsyncSurface", async () => {
+    /** @type {Parameters<typeof SampleResourcePage>[0]["facade"]} */
    const facade = {
      listResources: async () => ({
-        ok: true,
+        ok: /** @type {const} */ (true),
        value: [
          {
            resourceId: "resource-1",
@@ -18,7 +19,14 @@ describe("removable sample feature page", () => {
          },
        ],
      }),
-      createResource: async () => ({ ok: true, value: {} }),
+      createResource: async () => ({
+        ok: /** @type {const} */ (true),
+        value: {
+          resourceId: "resource-created",
+          title: "Created",
+          createdAtLabel: null,
+        },
+      }),
    };
    render(<SampleResourcePage facade={facade} />);

@@ -27,9 +35,10 @@ describe("removable sample feature page", () => {
  });

  it("renders normalized terminal errors without raw DTO fields", async () => {
+    /** @type {Parameters<typeof SampleResourcePage>[0]["facade"]} */
    const facade = {
      listResources: async () => ({
-        ok: false,
+        ok: /** @type {const} */ (false),
        error: {
          kind: "SERVER_FAILURE",
          code: "SERVER_FAILURE",
@@ -40,10 +49,22 @@ describe("removable sample feature page", () => {
          action: "retry",
        },
      }),
-      createResource: async () => ({ ok: true, value: {} }),
+      createResource: async () => ({
+        ok: /** @type {const} */ (true),
+        value: {
+          resourceId: "resource-created",
+          title: "Created",
+          createdAtLabel: null,
+        },
+      }),
    };
    render(<SampleResourcePage facade={facade} />);

-    expect(await screen.findByRole("alert")).toHaveTextContent("error.server_failure");
+    const alert = await screen.findByRole("alert");
+    expect(alert).toHaveTextContent("요청을 완료하지 못했습니다.");
+    expect(alert).toHaveAttribute(
+      "data-message-key",
+      "error.server_failure",
+    );
  });
 });
@@ -0,0 +1,20 @@
+// @vitest-environment jsdom
+
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+type StatusProps = Readonly<{
+  label: string;
+  tone: "neutral" | "positive";
+}>;
+
+function Status({ label, tone }: StatusProps) {
+  return <output data-tone={tone}>{label}</output>;
+}
+
+describe("TSX test tooling", () => {
+  it("parses, lints, type-checks, and renders TSX", () => {
+    render(<Status label="ready" tone="positive" />);
+    expect(screen.getByText("ready")).toHaveAttribute("data-tone", "positive");
+  });
+});
@@ -0,0 +1,108 @@
+// @vitest-environment jsdom
+
+import { render, screen, waitFor } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { useState } from "react";
+import { describe, expect, it, vi } from "vitest";
+
+import { Alert } from "../../src/presentation/components/ui/alert.jsx";
+import { Badge } from "../../src/presentation/components/ui/badge.jsx";
+import { Button } from "../../src/presentation/components/ui/button.jsx";
+import { Card } from "../../src/presentation/components/ui/card.jsx";
+import { Dialog } from "../../src/presentation/components/ui/dialog.jsx";
+import { TextField } from "../../src/presentation/components/ui/text-field.jsx";
+
+describe("domain-neutral UI primitives", () => {
+  it("connects field help and validation errors to the input", () => {
+    render(
+      <TextField
+        label="이름"
+        description="표시할 이름입니다."
+        error="이름을 입력해 주세요."
+        required
+      />,
+    );
+
+    const field = screen.getByRole("textbox", { name: "이름" });
+    expect(field).toBeRequired();
+    expect(field).toHaveAccessibleDescription(
+      "표시할 이름입니다. 이름을 입력해 주세요.",
+    );
+    expect(field).toHaveAttribute("aria-invalid", "true");
+  });
+
+  it("exposes semantic variants without changing native button behavior", async () => {
+    const user = userEvent.setup();
+    const onClick = vi.fn();
+    render(
+      <>
+        <Button variant="danger" onClick={onClick}>
+          제거
+        </Button>
+        <Button disabled>사용 불가</Button>
+      </>,
+    );
+
+    await user.click(screen.getByRole("button", { name: "제거" }));
+    expect(onClick).toHaveBeenCalledOnce();
+    expect(screen.getByRole("button", { name: "제거" })).toHaveClass(
+      "ui-button--danger",
+    );
+    expect(screen.getByRole("button", { name: "사용 불가" })).toBeDisabled();
+  });
+
+  it("labels cards, alerts, and badges with visible content", async () => {
+    const user = userEvent.setup();
+    const dismiss = vi.fn();
+    render(
+      <Card title="상태 카드" footer={<Badge variant="success">준비됨</Badge>}>
+        <Alert title="저장됨" variant="success" onDismiss={dismiss}>
+          안전하게 반영했습니다.
+        </Alert>
+      </Card>,
+    );
+
+    expect(screen.getByRole("article", { name: "상태 카드" })).toBeVisible();
+    expect(screen.getByRole("status")).toHaveTextContent(
+      "저장됨안전하게 반영했습니다.",
+    );
+    expect(screen.getByText("준비됨")).toHaveClass("ui-badge--success");
+    await user.click(screen.getByRole("button", { name: "저장됨 알림 닫기" }));
+    expect(dismiss).toHaveBeenCalledOnce();
+  });
+
+  it("closes a modal and restores focus to its trigger", async () => {
+    const user = userEvent.setup();
+
+    function DialogHarness() {
+      const [open, setOpen] = useState(false);
+      return (
+        <>
+          <Button onClick={() => setOpen(true)}>모달 열기</Button>
+          <Dialog
+            open={open}
+            onClose={() => setOpen(false)}
+            title="연동 확인"
+            actions={<Button onClick={() => setOpen(false)}>확인</Button>}
+          >
+            안전한 설명
+          </Dialog>
+        </>
+      );
+    }
+
+    render(<DialogHarness />);
+    const trigger = screen.getByRole("button", { name: "모달 열기" });
+    await user.click(trigger);
+
+    expect(screen.getByRole("dialog", { name: "연동 확인" })).toHaveAttribute(
+      "open",
+    );
+    await user.click(screen.getByRole("button", { name: "확인" }));
+
+    await waitFor(() => expect(trigger).toHaveFocus());
+    expect(screen.getByRole("dialog", { hidden: true })).not.toHaveAttribute(
+      "open",
+    );
+  });
+});
@@ -1,7 +1,14 @@
 import AxeBuilder from "@axe-core/playwright";
 import { expect, test } from "@playwright/test";

-for (const route of ["/", "/sample/resources", "/not-found"]) {
+for (const route of [
+  "/",
+  "/examples/ui",
+  "/examples/states",
+  "/examples/auth",
+  "/sample/resources",
+  "/not-found",
+]) {
  test(`@a11y ${route} has no critical or serious axe violations`, async ({
    page,
  }) => {
@@ -21,7 +28,7 @@ test("@a11y keyboard reaches the primary route action with visible focus", async
  page,
 }) => {
  await page.goto("/");
-  const action = page.getByRole("link", { name: "샘플 리소스" });
+  const action = page.getByRole("link", { name: "UI 구성요소 보기" });
  await expect(action).toBeVisible();
  await page.keyboard.press("Tab");
  await expect(action).toBeFocused();
@@ -5,4 +5,51 @@ test("boots the public app shell", async ({ page }) => {
  await expect(page.getByRole("heading", { level: 1 })).toHaveText(
    "Clean Architecture Frontend",
  );
+  await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
+  await expect(page.getByRole("main")).toBeVisible();
+});
+
+test("navigates to a registry-backed example without a page reload", async ({
+  page,
+}) => {
+  await page.goto("/");
+  await page
+    .getByRole("navigation", { name: "주요 탐색" })
+    .getByRole("link", { name: "화면 상태" })
+    .click();
+
+  await expect(page).toHaveURL(/\/examples\/states$/);
+  await expect(
+    page.getByRole("heading", { level: 1, name: "화면 상태" }),
+  ).toBeFocused();
+});
+
+test("opens the protected integration route through the local demo seam", async ({
+  page,
+}) => {
+  await page.goto("/sample/resources");
+  await expect(
+    page.getByRole("heading", { name: "세션이 필요합니다." }),
+  ).toBeVisible();
+
+  await page.getByRole("button", { name: "로그인 시작" }).click();
+
+  await expect(
+    page.getByRole("heading", { name: "보호된 연동 지점" }),
+  ).toBeVisible();
+  await expect(page.getByText("인증됨")).toBeVisible();
+});
+
+test("provides an escape-dismissible mobile navigation", async ({ page }) => {
+  await page.setViewportSize({ width: 390, height: 844 });
+  await page.goto("/");
+  const menu = page.getByRole("button", { name: "메뉴", exact: true });
+
+  await menu.click();
+  await expect(menu).toHaveAttribute("aria-expanded", "true");
+  await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
+
+  await page.keyboard.press("Escape");
+  await expect(menu).toHaveAttribute("aria-expanded", "false");
+  await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeHidden();
 });
@@ -0,0 +1,36 @@
+import { expect, test } from "@playwright/test";
+
+test("reflows the UI gallery at the 320px minimum without horizontal overflow", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 320, height: 720 });
+  await page.goto("/examples/ui");
+  await expect(
+    page.getByRole("heading", { level: 1, name: "UI 구성요소" }),
+  ).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "메뉴", exact: true }),
+  ).toBeVisible();
+
+  const viewport = await page.evaluate(() => ({
+    clientWidth: document.documentElement.clientWidth,
+    scrollWidth: document.documentElement.scrollWidth,
+  }));
+  expect(viewport.scrollWidth).toBeLessThanOrEqual(viewport.clientWidth);
+});
+
+test("keeps desktop navigation and two-column examples at wide viewports", async ({
+  page,
+}) => {
+  await page.setViewportSize({ width: 1440, height: 900 });
+  await page.goto("/examples/ui");
+
+  await expect(page.getByRole("navigation", { name: "주요 탐색" })).toBeVisible();
+  await expect(
+    page.getByRole("button", { name: "메뉴", exact: true }),
+  ).toBeHidden();
+  await expect(page.locator(".component-grid--two").first()).toHaveCSS(
+    "grid-template-columns",
+    /.+px .+px/,
+  );
+});
@@ -0,0 +1,38 @@
+import AxeBuilder from "@axe-core/playwright";
+import { expect, test } from "@playwright/test";
+
+test("persists an explicit color scheme through the storage contract", async ({
+  page,
+}) => {
+  await page.goto("/");
+  const selector = page.getByRole("combobox", { name: "색상 테마" });
+
+  await selector.selectOption("dark");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+  await expect(page.locator("html")).toHaveCSS("color-scheme", "dark");
+  const results = await new AxeBuilder({ page })
+    .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
+    .analyze();
+  expect(
+    results.violations.filter((violation) =>
+      ["critical", "serious"].includes(violation.impact ?? ""),
+    ),
+  ).toEqual([]);
+
+  await page.reload();
+  await expect(selector).toHaveValue("dark");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+});
+
+test("tracks operating-system changes while system preference is selected", async ({
+  page,
+}) => {
+  await page.emulateMedia({ colorScheme: "dark" });
+  await page.goto("/");
+  const selector = page.getByRole("combobox", { name: "색상 테마" });
+  await selector.selectOption("system");
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "dark");
+
+  await page.emulateMedia({ colorScheme: "light" });
+  await expect(page.locator("html")).toHaveAttribute("data-theme", "light");
+});
@@ -0,0 +1,34 @@
+import { expect, test } from "@playwright/test";
+
+test("validates and reports the common text-field flow", async ({ page }) => {
+  await page.goto("/examples/ui");
+  await page.getByRole("button", { name: "입력 확인" }).click();
+
+  const field = page.getByRole("textbox", { name: "프로젝트 이름" });
+  await expect(field).toHaveAttribute("aria-invalid", "true");
+  await expect(field).toHaveAccessibleDescription(
+    /프로젝트 이름을 입력해 주세요/,
+  );
+
+  await field.fill("Starter");
+  await page.getByRole("button", { name: "입력 확인" }).click();
+  await expect(page.getByText("“Starter” 입력을 확인했습니다.")).toBeVisible();
+});
+
+test("traps modal interaction and restores focus to the trigger", async ({
+  page,
+}) => {
+  await page.goto("/examples/ui");
+  const trigger = page.getByRole("button", { name: "모달 열기" });
+  await trigger.click();
+
+  const dialog = page.getByRole("dialog", { name: "연동 확인" });
+  await expect(dialog).toBeVisible();
+  await expect(
+    dialog.getByRole("button", { name: "연동 확인 닫기" }),
+  ).toBeFocused();
+
+  await page.keyboard.press("Escape");
+  await expect(dialog).toBeHidden();
+  await expect(trigger).toBeFocused();
+});
@@ -0,0 +1,7 @@
+import { createApplication } from "../../../../src/application/create-application.js";
+
+export const applicationFactory = createApplication;
+
+export function AllowedPresentationFixture() {
+  return <p>allowed</p>;
+}
@@ -0,0 +1,5 @@
+import "../../../../src/adapters/http/client.js";
+
+export function InvalidPresentationFixture() {
+  return <p>invalid</p>;
+}
@@ -0,0 +1,33 @@
+{
+  "schemaVersion": 1,
+  "sourceDirectories": [],
+  "registries": [
+    {
+      "registryId": "FIXTURE-SOURCE",
+      "path": "tests/fixtures/registry/forbidden/invalid-registry.js",
+      "exportName": "INVALID_REGISTRY",
+      "owner": "fixture",
+      "requiredFields": ["id", "target"],
+      "uniqueFields": ["id"],
+      "references": [
+        {
+          "field": "target",
+          "registryId": "FIXTURE-TARGET",
+          "targetField": "id"
+        }
+      ]
+    },
+    {
+      "registryId": "FIXTURE-TARGET",
+      "path": "tests/fixtures/registry/forbidden/invalid-registry.js",
+      "exportName": "TARGET_REGISTRY",
+      "owner": "fixture",
+      "requiredFields": ["id"],
+      "uniqueFields": ["id"]
+    }
+  ],
+  "compatibilityImpact": {
+    "allowed": ["none", "additive", "behavior-change", "breaking"],
+    "current": "breaking"
+  }
+}
@@ -0,0 +1,13 @@
+type InvalidRow = Readonly<{
+  id: string;
+  target?: string;
+}>;
+
+export const INVALID_REGISTRY: Record<string, InvalidRow> = {
+  FIRST: { id: "duplicate", target: "missing" },
+  SECOND: { id: "duplicate" },
+};
+
+export const TARGET_REGISTRY = {
+  KNOWN: { id: "known" },
+} as const;
@@ -0,0 +1,3 @@
+export function SafeTextFixture({ value }: Readonly<{ value: string }>) {
+  return <p>{value}</p>;
+}
@@ -0,0 +1,3 @@
+export function UnsafeHtmlFixture({ value }: Readonly<{ value: string }>) {
+  return <div dangerouslySetInnerHTML={{ __html: value }} />;
+}
@@ -0,0 +1,7 @@
+interface ClockPort {
+  now(): number;
+}
+
+export const invalidClock: ClockPort = {
+  now: () => "not-a-number",
+};
@@ -0,0 +1,7 @@
+type Result<T, E> =
+  | Readonly<{ ok: true; value: T }>
+  | Readonly<{ ok: false; error: E }>;
+
+export function invalidUnwrap(result: Result<number, string>): number {
+  return result.value;
+}
@@ -5,6 +5,7 @@ import { afterAll, afterEach, beforeAll, describe, expect, it, vi } from "vitest
 import { createExternalAuthSessionAdapter } from "../../src/adapters/auth/external-session-adapter.js";
 import { createHttpClient } from "../../src/adapters/http/client.js";

+/** @type {number[]} */
 let responseStatuses = [];
 const server = setupServer(
  http.get("https://api.test/api/sample/resources", () => {
@@ -36,16 +37,32 @@ afterAll(() => server.close());

 const clock = { now: () => 0, sleep: async () => {} };

+/**
+ * @param {Partial<Parameters<typeof createExternalAuthSessionAdapter>[0]>} overrides
+ * @returns {Parameters<typeof createExternalAuthSessionAdapter>[0]}
+ */
+function createOwner(overrides = {}) {
+  return {
+    readState: () => "authenticated",
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
+    attachCredential: async (request) => request,
+    recoverSession: async () => "restored",
+    notifyUnauthenticated: () => {},
+    ...overrides,
+  };
+}
+
 describe("bounded 401 session recovery", () => {
  it("calls recovery once and replays a safe request once", async () => {
    responseStatuses = [401, 200];
-    const recoverSession = vi.fn(async () => "restored");
-    const authSession = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const recoverSession = vi.fn(async () => /** @type {const} */ ("restored"));
+    const authSession = createExternalAuthSessionAdapter(createOwner({
      attachCredential: async (request) => request,
      recoverSession,
      notifyUnauthenticated: vi.fn(),
-    });
+    }));
    const client = createHttpClient({
      baseUrl: "https://api.test",
      authSession,
@@ -61,12 +78,11 @@ describe("bounded 401 session recovery", () => {
  it("stops after a second 401 and notifies unauthenticated once", async () => {
    responseStatuses = [401, 401];
    const notifyUnauthenticated = vi.fn();
-    const authSession = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const authSession = createExternalAuthSessionAdapter(createOwner({
      attachCredential: async (request) => request,
      recoverSession: async () => "restored",
      notifyUnauthenticated,
-    });
+    }));
    const client = createHttpClient({
      baseUrl: "https://api.test",
      authSession,
@@ -81,14 +97,13 @@ describe("bounded 401 session recovery", () => {
  });

  it("normalizes attach and invalid recovery failures", async () => {
-    const attachFailure = createExternalAuthSessionAdapter({
-      readState: () => "authenticated",
+    const attachFailure = createExternalAuthSessionAdapter(createOwner({
      attachCredential: async () => {
        throw new Error("credential detail");
      },
      recoverSession: async () => "restored",
      notifyUnauthenticated: vi.fn(),
-    });
+    }));
    const client = createHttpClient({
      baseUrl: "https://api.test",
      authSession: attachFailure,
@@ -31,6 +31,7 @@ describe("HTTP runtime schema boundary", () => {
      success: true,
      data: [{ id: "resource-1", additive: "accepted" }],
    });
+    if (!result.success) throw new Error("expected valid sample payload");
    expect(result.data).not.toBe(source);
  });

@@ -25,7 +25,8 @@ describe("runtime configuration boundary", () => {
    [{ ...validConfig, TELEMETRY_ENABLED: "false" }, "ambiguous boolean"],
    [{ ...validConfig, CONFIG_SCHEMA_VERSION: "next" }, "version"],
    [{ ...validConfig, UNKNOWN_KEY: true }, "unknown key"],
-  ])("rejects invalid config: %s (%s)", (candidate) => {
+  ])("rejects invalid config: %s (%s)", (candidate, _reason) => {
+    void _reason;
    expect(validateRuntimeConfig(candidate).success).toBe(false);
  });

@@ -36,6 +36,7 @@ describe("external AuthSessionPort adapter", () => {
      beginSignIn: async () => {},
      signOut: async () => {},
      attachCredential: async (request) => request,
+      // @ts-expect-error Deliberately violates the external-owner contract.
      recoverSession: async () => "unexpected",
      notifyUnauthenticated: vi.fn(),
    });
@@ -57,7 +58,7 @@ describe("external AuthSessionPort adapter", () => {
    });

    expect(adapter.getState()).toBe("unauthenticated");
-    await adapter.beginSignIn("/");
+    await adapter.beginSignIn();
    expect(adapter.getState()).toBe("authenticated");
    await adapter.signOut();
    expect(adapter.getState()).toBe("unauthenticated");
@@ -3,15 +3,16 @@ import { describe, expect, it } from "vitest";
 import { decideChunkRecovery } from "../../src/application/use-cases/decide-chunk-recovery.js";

 function memoryStorage() {
+  /** @type {unknown} */
  let value;
-  return {
-    read: () => ({ ok: true, value }),
+  return /** @type {import("../../src/application/ports/storage-port.js").StoragePort} */ ({
+    read: () => ({ ok: /** @type {const} */ (true), value }),
    write: (_key, next) => {
      value = next;
-      return { ok: true };
+      return { ok: /** @type {const} */ (true) };
    },
-    remove: () => ({ ok: true }),
-  };
+    remove: () => ({ ok: /** @type {const} */ (true) }),
+  });
 }

 describe("controlled chunk recovery", () => {
@@ -0,0 +1,48 @@
+// @vitest-environment jsdom
+
+import { describe, expect, it } from "vitest";
+
+import {
+  normalizeColorSchemePreference,
+  resolveColorScheme,
+} from "../../src/application/policies/color-scheme.js";
+import { initializeColorScheme } from "../../src/bootstrap/initialize-color-scheme.js";
+
+describe("color scheme policy", () => {
+  it("normalizes unknown persisted values to the safe system default", () => {
+    expect(normalizeColorSchemePreference("sepia")).toBe("system");
+    expect(normalizeColorSchemePreference("dark")).toBe("dark");
+  });
+
+  it("resolves system and explicit preferences deterministically", () => {
+    expect(resolveColorScheme("system", true)).toBe("dark");
+    expect(resolveColorScheme("system", false)).toBe("light");
+    expect(resolveColorScheme("light", true)).toBe("light");
+  });
+
+  it("applies a persisted preference before application paint", () => {
+    const storage =
+      /** @type {import("../../src/application/ports/storage-port.js").StoragePort} */ ({
+        read: () => ({
+          ok: /** @type {const} */ (true),
+          value: "system",
+        }),
+        write: () => ({ ok: /** @type {const} */ (true) }),
+        remove: () => ({ ok: /** @type {const} */ (true) }),
+      });
+
+    const result = initializeColorScheme(storage, {
+      documentElement: document.documentElement,
+      matchMedia: () =>
+        /** @type {MediaQueryList} */ ({ matches: true }),
+    });
+
+    expect(result).toEqual({ preference: "system", resolved: "dark" });
+    expect(document.documentElement).toHaveAttribute("data-theme", "dark");
+    expect(document.documentElement).toHaveAttribute(
+      "data-theme-preference",
+      "system",
+    );
+    expect(document.documentElement.style.colorScheme).toBe("dark");
+  });
+});
@@ -39,14 +39,20 @@ describe("frontend failure classification", () => {
  });

  it("projects only allowlisted safe fields", () => {
-    const result = createFailure("SERVER_FAILURE", "LIST_SAMPLE_RESOURCES", 0, {
+    const untrustedDetails = {
      code: "TEMPORARY",
      httpStatus: 503,
      requestId: "request-1",
      stack: "must not leak",
      body: "must not leak",
      authorization: "Bearer secret",
-    });
+    };
+    const result = createFailure(
+      "SERVER_FAILURE",
+      "LIST_SAMPLE_RESOURCES",
+      0,
+      untrustedDetails,
+    );

    expect(result).toMatchObject({
      kind: "SERVER_FAILURE",
@@ -1,6 +1,10 @@
 import { describe, expect, it } from "vitest";

-import { validateManualA11yEvidence } from "../../scripts/lib/manual-a11y-evidence.mjs";
+import {
+  MANUAL_A11Y_ROUTE_IDS,
+  validateManualA11yEvidence,
+} from "../../scripts/lib/manual-a11y-evidence.mjs";
+import { ROUTE_REGISTRY } from "../../src/contracts/routes.js";

 const reviewed = `Status: reviewed
 Route ID: APP_HOME
@@ -20,6 +24,12 @@ Screen reader: pass
 Notes: no defects`;

 describe("manual accessibility evidence", () => {
+  it("requires evidence for every registered user-visible route", () => {
+    expect([...MANUAL_A11Y_ROUTE_IDS].sort()).toEqual(
+      Object.keys(ROUTE_REGISTRY).sort(),
+    );
+  });
+
  it("accepts a complete signed human review record", () => {
    expect(validateManualA11yEvidence(reviewed)).toMatchObject({
      failures: [],
@@ -4,7 +4,10 @@ import {
  createRedirectLoopGuard,
  decideRouteAccess,
 } from "../../src/presentation/routes/navigation-policy.js";
-import { ROUTE_REGISTRY } from "../../src/contracts/routes.js";
+import {
+  NAVIGATION_ROUTES,
+  ROUTE_REGISTRY,
+} from "../../src/contracts/routes.js";

 describe("route registry", () => {
  it("matches the stable registry snapshot", () => {
@@ -15,35 +18,93 @@ describe("route registry", () => {
          "chunkId": "route-home",
          "errorSurface": "route-boundary",
          "loadingSurface": "app-shell",
+          "navigationLabel": "시작",
+          "navigationOrder": 10,
          "paramsSchema": null,
          "path": "/",
          "routeId": "APP_HOME",
          "searchSchema": null,
+          "title": "시작",
+        },
+        "EXAMPLES_AUTH": {
+          "access": "public",
+          "chunkId": "route-examples-auth",
+          "errorSurface": "route-boundary",
+          "loadingSurface": "example-page",
+          "navigationLabel": "인증 연동",
+          "navigationOrder": 40,
+          "paramsSchema": null,
+          "path": "/examples/auth",
+          "routeId": "EXAMPLES_AUTH",
+          "searchSchema": null,
+          "title": "인증 연동",
+        },
+        "EXAMPLES_STATES": {
+          "access": "public",
+          "chunkId": "route-examples-states",
+          "errorSurface": "route-boundary",
+          "loadingSurface": "example-page",
+          "navigationLabel": "화면 상태",
+          "navigationOrder": 30,
+          "paramsSchema": null,
+          "path": "/examples/states",
+          "routeId": "EXAMPLES_STATES",
+          "searchSchema": null,
+          "title": "화면 상태",
+        },
+        "EXAMPLES_UI": {
+          "access": "public",
+          "chunkId": "route-examples-ui",
+          "errorSurface": "route-boundary",
+          "loadingSurface": "example-page",
+          "navigationLabel": "UI 구성요소",
+          "navigationOrder": 20,
+          "paramsSchema": null,
+          "path": "/examples/ui",
+          "routeId": "EXAMPLES_UI",
+          "searchSchema": null,
+          "title": "UI 구성요소",
        },
        "NOT_FOUND": {
          "access": "public",
          "chunkId": "route-not-found",
          "errorSurface": "not-found",
          "loadingSurface": "none",
+          "navigationLabel": null,
+          "navigationOrder": null,
          "paramsSchema": null,
          "path": "*",
          "routeId": "NOT_FOUND",
          "searchSchema": null,
+          "title": "페이지를 찾을 수 없음",
        },
        "SAMPLE_RESOURCE_LIST": {
          "access": "integration-defined",
          "chunkId": "route-sample-resources",
          "errorSurface": "feature-boundary",
          "loadingSurface": "sample-resource-list",
+          "navigationLabel": "보호된 연동 지점",
+          "navigationOrder": 50,
          "paramsSchema": null,
          "path": "/sample/resources",
          "routeId": "SAMPLE_RESOURCE_LIST",
          "searchSchema": "SampleResourceListQuery",
+          "title": "보호된 연동 지점",
        },
      }
    `);
  });

+  it("derives visible navigation in explicit order", () => {
+    expect(NAVIGATION_ROUTES.map(({ routeId }) => routeId)).toEqual([
+      "APP_HOME",
+      "EXAMPLES_UI",
+      "EXAMPLES_STATES",
+      "EXAMPLES_AUTH",
+      "SAMPLE_RESOURCE_LIST",
+    ]);
+  });
+
  it("treats client access as a UX hint, not authorization", () => {
    expect(decideRouteAccess("APP_HOME", "unauthenticated")).toEqual({
      allowed: true,
@@ -6,7 +6,10 @@ import {
 } from "../../src/application/policies/promotion-readiness.js";

 const allGateIds = Object.values(PROMOTION_FORMULA).flat();
-const passing = Object.fromEntries(allGateIds.map((gateId) => [gateId, "PASS"]));
+const passing =
+  /** @type {Record<string, "PASS" | "FAIL" | "UNVERIFIED">} */ (
+    Object.fromEntries(allGateIds.map((gateId) => [gateId, "PASS"]))
+  );

 describe("promotion readiness formula", () => {
  it("requires every upstream tier before downstream readiness", () => {
@@ -30,7 +33,11 @@ describe("promotion readiness formula", () => {
      ...passing,
      [failedGate]: "FAIL",
    });
-    expect(result[readiness]).toBe(false);
+    const readinessKey =
+      /** @type {keyof ReturnType<typeof evaluatePromotionReadiness>} */ (
+        readiness
+      );
+    expect(result[readinessKey]).toBe(false);
  });

  it("does not treat missing or unverified gates as pass", () => {
@@ -6,11 +6,15 @@ describe("registry governance manifest", () => {
    const governance = JSON.parse(
      await readFile("config/contracts/registry-governance.json", "utf8"),
    );
+    const registries =
+      /** @type {Array<{registryId: string, owner: string}>} */ (
+        governance.registries
+      );
    expect(governance.registries).toHaveLength(8);
-    expect(new Set(governance.registries.map((entry) => entry.registryId)).size).toBe(
+    expect(new Set(registries.map((entry) => entry.registryId)).size).toBe(
      8,
    );
-    expect(governance.registries.every((entry) => entry.owner)).toBe(true);
+    expect(registries.every((entry) => entry.owner)).toBe(true);
    expect(governance.compatibilityImpact.allowed).toEqual([
      "none",
      "additive",
@@ -10,7 +10,7 @@ const runtime = {
    AUTH_MODE: "demo",
  },
 };
-const release = {
+const release = /** @type {const} */ ({
  schemaVersion: 1,
  appVersion: "0.1.0",
  buildId: "build-a",
@@ -20,7 +20,7 @@ const release = {
  assetManifestHash: "hash-a",
  releaseId: "release-a",
  builtAt: "2026-07-25T00:00:00Z",
-};
+});

 describe("runtime adapter composition", () => {
  it("constructs the local demo seam and infrastructure adapters", async () => {
@@ -7,8 +7,12 @@ import {
  defineStorageKey,
 } from "../../src/contracts/storage-keys.js";

+/**
+ * @param {{quota?: boolean}} [options]
+ * @returns {Storage}
+ */
 function createStorage({ quota = false } = {}) {
-  const values = new Map();
+  const values = /** @type {Map<string, string>} */ (new Map());
  return {
    getItem: (key) => values.get(key) ?? null,
    setItem: (key, value) => {
@@ -56,7 +56,7 @@ describe("telemetry registry and redaction", () => {

 describe("best-effort telemetry adapter", () => {
  it("bounds the queue using oldest-drop without blocking callers", () => {
-    const scheduled = [];
+    const scheduled = /** @type {Array<() => void>} */ ([]);
    const adapter = createTelemetryAdapter({
      enabled: true,
      endpoint: "https://telemetry.test/events",
@@ -0,0 +1,16 @@
+import { describe, expect, it } from "vitest";
+
+type Result<T, E> =
+  | Readonly<{ ok: true; value: T }>
+  | Readonly<{ ok: false; error: E }>;
+
+function summarize(result: Result<number, string>): string {
+  return result.ok ? String(result.value) : result.error;
+}
+
+describe("TypeScript test tooling", () => {
+  it("type-checks and executes discriminated unions in the test project", () => {
+    expect(summarize({ ok: true, value: 42 })).toBe("42");
+    expect(summarize({ ok: false, error: "failed" })).toBe("failed");
+  });
+});
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["vite/client"]
+  },
+  "include": ["src"],
+  "exclude": ["dist", "node_modules", "tests"]
+}
@@ -0,0 +1,18 @@
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "module": "ESNext",
+    "moduleResolution": "Bundler",
+    "resolveJsonModule": true,
+    "allowImportingTsExtensions": false,
+    "jsx": "react-jsx",
+    "strict": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "isolatedModules": true
+  }
+}
@@ -1,20 +1,8 @@
 {
-  "compilerOptions": {
-    "allowJs": true,
-    "checkJs": true,
-    "noEmit": true,
-    "target": "ES2022",
-    "useDefineForClassFields": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
-    "moduleResolution": "Bundler",
-    "resolveJsonModule": true,
-    "allowImportingTsExtensions": false,
-    "jsx": "react-jsx",
-    "strict": true,
-    "skipLibCheck": true,
-    "types": ["vite/client", "node"]
-  },
-  "include": ["src", "scripts", "vite.config.js"],
-  "exclude": ["dist", "node_modules", "tests/fixtures"]
+  "files": [],
+  "references": [
+    { "path": "./tsconfig.app.json" },
+    { "path": "./tsconfig.node.json" },
+    { "path": "./tsconfig.test.json" }
+  ]
 }
@@ -0,0 +1,9 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node"]
+  },
+  "include": ["scripts", "vite.config.js"],
+  "exclude": ["dist", "node_modules", "tests"]
+}
@@ -0,0 +1,20 @@
+{
+  "extends": "./tsconfig.base.json",
+  "compilerOptions": {
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "types": ["node", "vite/client"]
+  },
+  "include": [
+    "tests/**/*.js",
+    "tests/**/*.jsx",
+    "tests/**/*.ts",
+    "tests/**/*.tsx",
+    "vitest.config.js",
+    "playwright.config.js"
+  ],
+  "exclude": [
+    "dist",
+    "node_modules",
+    "tests/fixtures"
+  ]
+}
Author	SHA1	Message	Date
donghyeon-ka	0fed35586a	feat: establish TypeScript-aware frontend tooling	2026-07-26 13:41:23 +09:00
donghyeon-ka	1a1747c737	merge: frontend platform capability review	2026-07-26 02:09:38 +09:00
donghyeon-ka	68342e25ce	docs: audit frontend platform capabilities	2026-07-26 02:09:06 +09:00
donghyeon-ka	cb195f8773	merge: frontend performance route contract	2026-07-26 00:32:50 +09:00
donghyeon-ka	5a7a6c4ae5	test(performance): derive navigation target from route registry	2026-07-26 00:32:50 +09:00
donghyeon-ka	8ea825a8a1	merge: harden starter experience quality contract	2026-07-26 00:28:17 +09:00
donghyeon-ka	236909be64	test: harden starter experience quality contract	2026-07-26 00:28:09 +09:00
donghyeon-ka	68d9efbda3	merge: add persistent responsive color themes	2026-07-26 00:06:56 +09:00
donghyeon-ka	4cfbe5a29e	feat: add persistent responsive color themes	2026-07-26 00:06:49 +09:00
donghyeon-ka	bee5c158c6	merge: provide reusable UI and state galleries	2026-07-25 23:59:20 +09:00
donghyeon-ka	3581ead595	feat: provide reusable UI and state galleries	2026-07-25 23:59:12 +09:00
donghyeon-ka	a8e3db1aec	merge: assemble responsive app shell navigation	2026-07-25 23:52:41 +09:00
donghyeon-ka	baeda39057	feat: assemble responsive app shell navigation	2026-07-25 23:52:34 +09:00
donghyeon-ka	0925d252d9	merge: compose executable frontend runtime	2026-07-25 23:42:39 +09:00