test(performance): derive navigation target from route registry

# Conflicts:
#	package.json

.gitea/workflows/quality-gates.yml

@@ -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

README.md

@@ -16,6 +16,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 +48,11 @@ bootstrap composes concrete adapters
 contracts own cross-cutting registries
 ```
 
-See `docs/architecture/overview.md` and `docs/architecture/layers.md`. The
+See `docs/architecture/overview.md`, `docs/architecture/layers.md`, and
-removable sample slice is under `src/sample/contract-fixture`; product code is
+`docs/architecture/starter-experience.md`. The removable sample slice is under
-not allowed to import it.
+`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.
 
 ## Verification
 
@@ -52,9 +75,17 @@ corepack pnpm drill:runbooks
 corepack pnpm check:ci
 ```
 
+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.
 

artifacts/performance/.gitkeep

@@ -1 +0,0 @@
-

artifacts/quality/.gitkeep

@@ -1 +0,0 @@
-

artifacts/release/.gitkeep

@@ -1 +0,0 @@
-

artifacts/security/.gitkeep

@@ -1 +0,0 @@
-

artifacts/tests/a11y-manual/APP_HOME.md

@@ -1,15 +1,18 @@
 # APP_HOME accessibility review
 
 Status: pending-manual-review
-
+Route ID: APP_HOME
+Release ID:
 Reviewer:
-
+Reviewed at:
-Keyboard: automated tab-order fixture passed; human review pending.
+Signature:
-
+Attestation: pending
-Focus: automated visible-focus fixture passed; route-change review pending.
+M1 Keyboard: pending
-
+M2 Visible focus: pending
-Screen reader: pending.
+M3 Route focus: pending
-
+M4 Modal focus: not-applicable (no modal on this route)
-Reduced motion: automated media-query fixture passed; human review pending.
+M5 Error association: not-applicable (no form error on this route)
-
+M6 Color signal: pending
-Color signal: pending.
+M7 Reduced motion: pending
+Screen reader: pending
+Notes: Automated axe, keyboard-focus, and reduced-motion evidence is available; human review pending.

artifacts/tests/a11y-manual/EXAMPLES_AUTH.md

@@ -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.

artifacts/tests/a11y-manual/EXAMPLES_STATES.md

@@ -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.

artifacts/tests/a11y-manual/EXAMPLES_UI.md

@@ -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.

artifacts/tests/a11y-manual/NOT_FOUND.md

@@ -0,0 +1,18 @@
+# NOT_FOUND accessibility review
+
+Status: pending-manual-review
+Route ID: NOT_FOUND
+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: Human review pending.

artifacts/tests/a11y-manual/SAMPLE_RESOURCE_LIST.md

@@ -0,0 +1,18 @@
+# SAMPLE_RESOURCE_LIST accessibility review
+
+Status: pending-manual-review
+Route ID: SAMPLE_RESOURCE_LIST
+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: Human review pending.

config/ci/gates.json

@@ -125,6 +125,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"

config/hosting/cache-policy.json

@@ -4,21 +4,25 @@
     "index": {
       "path": "/",
       "cacheControl": "no-cache",
+      "contentTypes": ["text/html"],
       "securityHeaders": true
     },
     "runtimeConfig": {
       "path": "/config.json",
       "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
       "securityHeaders": true
     },
     "releaseManifest": {
       "path": "/release-manifest.json",
       "cacheControl": "no-store",
+      "contentTypes": ["application/json"],
       "securityHeaders": true
     },
     "hashedAsset": {
       "pathPattern": "/assets/*",
       "cacheControl": "public, max-age=31536000, immutable",
+      "contentTypes": ["text/javascript", "application/javascript"],
       "securityHeaders": false
     },
     "sourceMap": {

config/hosting/response-headers.fixture.json

@@ -3,6 +3,7 @@
   "responses": {
     "index": {
       "cache-control": "no-cache",
+      "content-type": "text/html; charset=utf-8",
       "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
       "strict-transport-security": "max-age=31536000; includeSubDomains",
       "x-frame-options": "DENY",
@@ -12,6 +13,7 @@
     },
     "runtimeConfig": {
       "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
       "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
       "strict-transport-security": "max-age=31536000; includeSubDomains",
       "x-frame-options": "DENY",
@@ -21,6 +23,7 @@
     },
     "releaseManifest": {
       "cache-control": "no-store",
+      "content-type": "application/json; charset=utf-8",
       "content-security-policy": "default-src 'self'; base-uri 'self'; object-src 'none'; frame-ancestors 'none'; form-action 'self'; script-src 'self'; style-src 'self'; img-src 'self' data:; connect-src 'self' https:; font-src 'self'; upgrade-insecure-requests",
       "strict-transport-security": "max-age=31536000; includeSubDomains",
       "x-frame-options": "DENY",
@@ -29,7 +32,8 @@
       "permissions-policy": "camera=(), microphone=(), geolocation=()"
     },
     "hashedAsset": {
-      "cache-control": "public, max-age=31536000, immutable"
+      "cache-control": "public, max-age=31536000, immutable",
+      "content-type": "text/javascript; charset=utf-8"
     }
   }
 }

config/performance/field-input.example.json

@@ -1,5 +1,25 @@
 {
   "schemaVersion": 1,
   "releaseId": "local-release",
+  "environment": "replace-with-production",
+  "source": {
+    "system": "",
+    "exportId": ""
+  },
+  "privacy": {
+    "approved": false,
+    "approvalRef": ""
+  },
+  "window": {
+    "start": "2026-06-01T00:00:00Z",
+    "end": "2026-06-29T00:00:00Z"
+  },
+  "thresholdDecision": {
+    "status": "pending",
+    "minimumEligibleSamples": null,
+    "owner": "",
+    "reviewedAt": "",
+    "evidenceRef": ""
+  },
   "samples": []
 }

config/schemas/field-web-vitals.schema.json

@@ -8,6 +8,7 @@
     "window",
     "context",
     "metrics",
+    "thresholds",
     "eligibility",
     "status",
     "passed"
@@ -18,12 +19,55 @@
     "window": { "type": "object", "required": ["days", "start", "end"] },
     "context": {
       "type": "object",
-      "required": ["source", "network", "routeAggregation", "releaseId"]
+      "required": [
+        "source",
+        "sourceSystem",
+        "exportId",
+        "network",
+        "routeAggregation",
+        "releaseId",
+        "privacyApprovalRef",
+        "thresholdDecisionRef",
+        "validationFailures"
+      ],
+      "properties": {
+        "source": { "type": "string" },
+        "sourceSystem": { "type": ["string", "null"] },
+        "exportId": { "type": ["string", "null"] },
+        "network": { "const": "production-real-user" },
+        "routeAggregation": { "const": "route-id-only" },
+        "releaseId": { "type": ["string", "null"] },
+        "privacyApprovalRef": { "type": ["string", "null"] },
+        "thresholdDecisionRef": { "type": ["string", "null"] },
+        "validationFailures": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      },
+      "additionalProperties": false
+    },
+    "thresholds": {
+      "type": "object",
+      "required": [
+        "p75LcpMs",
+        "p75Cls",
+        "p75InpMs",
+        "minimumEligibleSamples"
+      ]
+    },
+    "metrics": {
+      "type": "object",
+      "required": ["p75LcpMs", "p75Cls", "p75InpMs"]
     },
-    "metrics": { "type": "object" },
     "eligibility": {
       "type": "object",
-      "required": ["consentRequired", "eligibleSamples", "minimumEligibleSamples"]
+      "required": [
+        "consentRequired",
+        "totalSamples",
+        "eligibleSamples",
+        "minimumEligibleSamples",
+        "routeSamples"
+      ]
     },
     "status": {
       "enum": ["PASS", "FAIL_THRESHOLD", "FAIL_UNVERIFIED"]

docs/accessibility/manual-checklist.md

@@ -1,17 +1,51 @@
 # Manual accessibility review checklist
 
 Automated axe checks do not establish WCAG conformance. A human reviewer must
-copy this checklist to `artifacts/tests/a11y-manual/<route-id>.md`, execute it
+review all six route records in `artifacts/tests/a11y-manual/` against one
-on the release candidate, and sign it.
+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.
 
-- Status: `pending` or `reviewed`
+Allowed item verdicts:
-- Reviewer and reviewed-at timestamp
-- Keyboard: all actions reachable in logical order
-- Focus: visible, route changes deterministic, modal restore verified
-- Screen reader: headings, live regions, errors, and actions announced once
-- Reduced motion: non-essential animation suppressed
-- Color signal: every state has text/icon/structure in addition to color
-- Notes and linked defect IDs
 
-Passing the automated threshold means only that the tested pages had zero
+- `pass`
-critical/serious axe findings under the recorded browser run.
+- `not-applicable (<specific reason>)`
+
+Required record:
+
+```text
+Status: reviewed
+Route ID: APP_HOME
+Release ID: <immutable release ID>
+Reviewer: <human reviewer identity>
+Reviewed at: <RFC 3339 timestamp>
+Signature: <reviewer identity or approved signature reference>
+Attestation: accepted
+M1 Keyboard: pass
+M2 Visible focus: pass
+M3 Route focus: pass
+M4 Modal focus: not-applicable (no modal on this route)
+M5 Error association: not-applicable (no form error on this route)
+M6 Color signal: pass
+M7 Reduced motion: pass
+Screen reader: pass
+Notes: <observations and linked defect IDs>
+```
+
+The reviewer must verify:
+
+- M1: every action works without a pointing device
+- M2: every focused element has a visible indicator
+- M3: route transitions move focus to a deterministic target
+- M4: modal focus is trapped and restored, when a modal exists
+- M5: errors are programmatically associated with their controls, when present
+- M6: state never relies on color alone
+- M7: non-essential motion is suppressed with reduced-motion preference
+- Screen reader: headings, live regions, errors, and actions are announced once
+
+`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.

docs/architecture/overview.md

@@ -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]
@@ -21,3 +23,9 @@ 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 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 depend on those ports and contracts, never on a
+concrete adapter or the removable sample fixture.

docs/architecture/starter-experience.md

@@ -0,0 +1,69 @@
+# 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
+  -> ThemeProvider
+  -> SessionProvider
+  -> BrowserRouter
+  -> 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
+
+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.

docs/operations/ci-quality-gates.md

@@ -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

docs/operations/performance-evidence.md

@@ -13,5 +13,10 @@ Performance evidence is deliberately split by measurement context:
 The field minimum eligible-sample threshold is intentionally unresolved until
 a privacy-approved telemetry baseline exists. Therefore the field command
 fails closed with `FAIL_UNVERIFIED` when run against the example input. Provide
-`FIELD_WEB_VITALS_INPUT` and a reviewed `MIN_ELIGIBLE_SAMPLES` only after that
+`FIELD_WEB_VITALS_INPUT` and `MIN_ELIGIBLE_SAMPLES` only after that decision is
-decision is recorded.
+recorded. The external input must identify a production release and an exact
+28-day export window, name the source/export, carry privacy-approval and
+threshold-decision references, and contain only non-negative route-ID samples.
+The environment threshold must be a positive integer equal to the approved
+decision embedded in the input. Invalid metadata fails as `FAIL_UNVERIFIED`;
+the example can never serve as production evidence.

docs/operations/release-cache-rollback.md

@@ -20,6 +20,13 @@ The provider-independent cache defaults are:
 - public source maps: disabled
 - service worker/offline cache: disabled
 
+HTML, JSON config/manifest, and hashed JavaScript MIME types are also compared
+to the declared allowlist; a cache-correct response with a mismatched
+`Content-Type` still fails the hosting gate.
+
 `corepack pnpm verify:hosting-headers` uses a deterministic fixture locally.
 Set `HOSTING_BASE_URL` to probe deployed responses; production promotion
-requires the artifact to report `mode: "live"`.
+requires the artifact to report `mode: "live"`. The live target must be its
+canonical, non-loopback HTTPS root URL. Each required surface must return HTTP
+200 without leaving that origin before its cache, content-type, and security
+headers can count as deployment evidence.

docs/styling/design-tokens.md

@@ -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
+semantic color, spacing, typography, status, and radius tokens through static
-classes.
+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,5 @@ 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
+The removable sample may demonstrate tokens, but production starter modules do
-import from `src/sample/contract-fixture`.
+not import from `src/sample/contract-fixture`.

docs/testing/taxonomy.md

@@ -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.

package.json

@@ -16,7 +16,7 @@
     "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:fixture": "tsc --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
+    "check:types:fixture": "tsc --ignoreConfig --allowJs --checkJs --noEmit --target ES2022 --module NodeNext --moduleResolution NodeNext tests/fixtures/typecheck/invalid-port-call.js",
     "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",

playwright.config.js

@@ -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"] } },
   ],
 });

public/config.json

@@ -4,7 +4,7 @@
   "REQUEST_TIMEOUT_MS": 10000,
   "MAX_RETRY_ATTEMPTS": 2,
   "TELEMETRY_ENABLED": false,
-  "AUTH_MODE": "external",
+  "AUTH_MODE": "demo",
   "CONFIG_SCHEMA_VERSION": "1",
   "API_CONTRACT_VERSION": "1",
   "RELEASE_MANIFEST_URL": "/release-manifest.json",

scripts/check-bundle.mjs

@@ -1,6 +1,7 @@
 import { readFile, writeFile } from "node:fs/promises";
 
 import { evaluateBundleBudget } from "../src/application/policies/performance-budgets.js";
+import { classifyViteJavascript } from "./lib/classify-vite-bundle.mjs";
 
 const report =
   /** @type {{
@@ -10,7 +11,7 @@ const report =
     JSON.parse(await readFile("artifacts/performance/bundle.json", "utf8"))
   );
 const viteManifest =
-  /** @type {Record<string, { file: string, isEntry?: boolean }>} */ (
+  /** @type {Record<string, { file: string, isEntry?: boolean, imports?: string[] }>} */ (
     JSON.parse(await readFile("dist/.vite/manifest.json", "utf8"))
   );
 const budgets =
@@ -21,24 +22,19 @@ const budgets =
 const outputByPath = new Map(
   report.outputs.map((output) => [output.path.replace(/^dist\//, ""), output]),
 );
-const initialFiles = new Set(
+const classification = classifyViteJavascript(viteManifest);
-  Object.values(viteManifest)
+const initialJsGzipBytes = classification.initialFiles.reduce(
-    .filter((entry) => entry.isEntry)
-    .map((entry) => entry.file),
-);
-const lazyFiles = new Set(
-  Object.values(viteManifest)
-    .filter((entry) => !entry.isEntry && entry.file.endsWith(".js"))
-    .map((entry) => entry.file),
-);
-const initialJsGzipBytes = [...initialFiles].reduce(
   (total, file) => total + (outputByPath.get(file)?.gzipBytes ?? 0),
   0,
 );
-const lazyChunks = [...lazyFiles].map((file) => ({
+const lazyChunks = classification.lazyFiles.map((file) => ({
   path: file,
   gzipBytes: outputByPath.get(file)?.gzipBytes ?? 0,
 }));
+const missingOutputs = [
+  ...classification.initialFiles,
+  ...classification.lazyFiles,
+].filter((file) => !outputByPath.has(file));
 const measurements = { initialJsGzipBytes, lazyChunks };
 const result = evaluateBundleBudget(measurements, budgets);
 const fixtures = [
@@ -70,10 +66,16 @@ const fixtures = [
       ).passed,
   },
 ];
-const passed = result.passed && fixtures.every((fixture) => fixture.passed);
+const passed =
+  result.passed &&
+  fixtures.every((fixture) => fixture.passed) &&
+  classification.missingImports.length === 0 &&
+  missingOutputs.length === 0;
 const completedReport = {
   ...report,
   measurements,
+  classification,
+  missingOutputs,
   thresholds: budgets,
   results: result,
   fixtures,
@@ -85,7 +87,12 @@ await writeFile(
   `${JSON.stringify(completedReport, null, 2)}\n`,
 );
 if (!passed) {
-  process.stderr.write("Bundle budget exceeded.\n");
+  process.stderr.write(
+    `Bundle budget or manifest integrity failed: ${[
+      ...classification.missingImports,
+      ...missingOutputs,
+    ].join(", ")}\n`,
+  );
   process.exit(1);
 }
 process.stdout.write(

scripts/collect-web-vitals-evidence.mjs

@@ -4,23 +4,19 @@ import {
   evaluateFieldBudget,
   percentile75,
 } from "../src/application/policies/performance-budgets.js";
+import { validateFieldEvidenceInput } from "./lib/field-vitals-evidence.mjs";
 
 const inputPath =
   process.env.FIELD_WEB_VITALS_INPUT ||
   "config/performance/field-input.example.json";
-const input =
+const rawInput = JSON.parse(await readFile(inputPath, "utf8"));
-  /** @type {{
+const now = new Date();
-   *   releaseId: string,
+const validation = validateFieldEvidenceInput(
-   *   samples: Array<{
+  rawInput,
-   *     timestamp: string,
+  process.env.MIN_ELIGIBLE_SAMPLES,
-   *     consent: boolean,
+  now,
-   *     releaseId: string,
+);
-   *     routeId: string,
+const input = validation.data;
-   *     lcpMs: number,
-   *     cls: number,
-   *     inpMs: number
-   *   }>
-   * }} */ (JSON.parse(await readFile(inputPath, "utf8")));
 const configured =
   /** @type {{
    *   p75LcpMs: number,
@@ -30,17 +26,17 @@ const configured =
    * }} */ (
     JSON.parse(await readFile("config/performance/budgets.json", "utf8")).field
   );
-const minimumEligibleSamples = process.env.MIN_ELIGIBLE_SAMPLES
+const minimumEligibleSamples = validation.minimumEligibleSamples;
-  ? Number(process.env.MIN_ELIGIBLE_SAMPLES)
+const fallbackEnd = now;
-  : configured.minimumEligibleSamples;
+const fallbackStart = new Date(fallbackEnd);
-const end = new Date();
+fallbackStart.setUTCDate(fallbackStart.getUTCDate() - 28);
-const start = new Date(end);
+const start = input ? new Date(input.window.start) : fallbackStart;
-start.setUTCDate(start.getUTCDate() - 28);
+const end = input ? new Date(input.window.end) : fallbackEnd;
-const eligible = input.samples.filter((sample) => {
+const eligible = (input?.samples ?? []).filter((sample) => {
   const timestamp = new Date(sample.timestamp);
   return (
     sample.consent === true &&
-    sample.releaseId === input.releaseId &&
+    sample.releaseId === input?.releaseId &&
     timestamp >= start &&
     timestamp <= end
   );
@@ -55,6 +51,8 @@ const result = evaluateFieldBudget(
   { metrics, eligibleSamples: eligible.length },
   thresholds,
 );
+const passed = validation.passed && result.passed;
+const status = validation.passed ? result.status : "FAIL_UNVERIFIED";
 const routeSamples = Object.fromEntries(
   Object.entries(
     eligible.reduce(
@@ -68,24 +66,30 @@ const routeSamples = Object.fromEntries(
 );
 const report = {
   schemaVersion: 1,
-  generatedAt: end.toISOString(),
+  generatedAt: now.toISOString(),
   window: { days: 28, start: start.toISOString(), end: end.toISOString() },
   context: {
     source: inputPath,
+    sourceSystem: input?.source.system ?? null,
+    exportId: input?.source.exportId ?? null,
     network: "production-real-user",
     routeAggregation: "route-id-only",
-    releaseId: input.releaseId,
+    releaseId: input?.releaseId ?? null,
+    privacyApprovalRef: input?.privacy.approvalRef ?? null,
+    thresholdDecisionRef: input?.thresholdDecision.evidenceRef ?? null,
+    validationFailures: validation.failures,
   },
   metrics,
   thresholds,
   eligibility: {
     consentRequired: true,
+    totalSamples: input?.samples.length ?? 0,
     eligibleSamples: eligible.length,
     minimumEligibleSamples,
     routeSamples,
   },
-  status: result.status,
+  status,
-  passed: result.passed,
+  passed,
 };
 
 await mkdir("artifacts/performance", { recursive: true });
@@ -93,9 +97,9 @@ await writeFile(
   "artifacts/performance/field-web-vitals.json",
   `${JSON.stringify(report, null, 2)}\n`,
 );
-if (!result.passed) {
+if (!passed) {
   process.stderr.write(
-    `Field Web Vitals: ${result.status} (minimum eligible sample threshold and 28-day production data are required)\n`,
+    `Field Web Vitals: ${status} (approved threshold decision and valid 28-day production evidence are required)\n`,
   );
   process.exit(1);
 }

scripts/lib/classify-vite-bundle.mjs

@@ -0,0 +1,49 @@
+/**
+ * @typedef {{
+ *   file: string,
+ *   isEntry?: boolean,
+ *   imports?: string[]
+ * }} ViteManifestEntry
+ */
+
+/**
+ * Static imports of an entry are part of initial JavaScript. Every remaining
+ * JavaScript output is governed by the lazy-chunk budget.
+ *
+ * @param {Record<string, ViteManifestEntry>} manifest
+ */
+export function classifyViteJavascript(manifest) {
+  const initialFiles = new Set();
+  const visitedKeys = new Set();
+  const pendingKeys = Object.entries(manifest)
+    .filter(([, entry]) => entry.isEntry)
+    .map(([key]) => key);
+  const missingImports = [];
+
+  while (pendingKeys.length > 0) {
+    const key = /** @type {string} */ (pendingKeys.pop());
+    if (visitedKeys.has(key)) continue;
+    visitedKeys.add(key);
+    const entry = manifest[key];
+    if (!entry) {
+      missingImports.push(key);
+      continue;
+    }
+    if (entry.file.endsWith(".js")) initialFiles.add(entry.file);
+    pendingKeys.push(...(entry.imports ?? []));
+  }
+
+  const allJavaScript = new Set(
+    Object.values(manifest)
+      .map((entry) => entry.file)
+      .filter((file) => file.endsWith(".js")),
+  );
+  const lazyFiles = [...allJavaScript].filter(
+    (file) => !initialFiles.has(file),
+  );
+  return Object.freeze({
+    initialFiles: Object.freeze([...initialFiles].sort()),
+    lazyFiles: Object.freeze(lazyFiles.sort()),
+    missingImports: Object.freeze(missingImports.sort()),
+  });
+}

scripts/lib/field-vitals-evidence.mjs

@@ -0,0 +1,122 @@
+import { z } from "zod";
+
+const WINDOW_MILLISECONDS = 28 * 24 * 60 * 60 * 1000;
+const nonEmptyString = z.string().trim().min(1);
+const timestamp = nonEmptyString.refine(
+  (value) => Number.isFinite(Date.parse(value)),
+  "must be an RFC 3339 timestamp",
+);
+const sampleSchema = z
+  .object({
+    timestamp,
+    consent: z.boolean(),
+    releaseId: nonEmptyString,
+    routeId: nonEmptyString.regex(/^[A-Z][A-Z0-9_]*$/),
+    lcpMs: z.number().finite().nonnegative(),
+    cls: z.number().finite().nonnegative(),
+    inpMs: z.number().finite().nonnegative(),
+  })
+  .strict();
+
+const fieldEvidenceInputSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    environment: z.literal("production"),
+    releaseId: nonEmptyString.refine(
+      (value) => value !== "local-release",
+      "must identify an immutable production release",
+    ),
+    source: z
+      .object({
+        system: nonEmptyString,
+        exportId: nonEmptyString,
+      })
+      .strict(),
+    privacy: z
+      .object({
+        approved: z.literal(true),
+        approvalRef: nonEmptyString,
+      })
+      .strict(),
+    window: z
+      .object({
+        start: timestamp,
+        end: timestamp,
+      })
+      .strict(),
+    thresholdDecision: z
+      .object({
+        status: z.literal("approved"),
+        minimumEligibleSamples: z.number().int().positive(),
+        owner: nonEmptyString,
+        reviewedAt: timestamp,
+        evidenceRef: nonEmptyString,
+      })
+      .strict(),
+    samples: z.array(sampleSchema),
+  })
+  .strict()
+  .superRefine((input, context) => {
+    const start = Date.parse(input.window.start);
+    const end = Date.parse(input.window.end);
+    if (end - start !== WINDOW_MILLISECONDS) {
+      context.addIssue({
+        code: "custom",
+        path: ["window"],
+        message: "must cover exactly 28 days",
+      });
+    }
+  });
+
+/**
+ * @param {unknown} input
+ * @param {string | undefined} configuredMinimum
+ * @param {Date} [now]
+ */
+export function validateFieldEvidenceInput(
+  input,
+  configuredMinimum,
+  now = new Date(),
+) {
+  const parsed = fieldEvidenceInputSchema.safeParse(input);
+  const failures = parsed.success
+    ? []
+    : parsed.error.issues.map(
+        (issue) => `${issue.path.join(".") || "input"}: ${issue.message}`,
+      );
+  const minimumEligibleSamples = Number(configuredMinimum);
+  if (
+    configuredMinimum === undefined ||
+    !Number.isInteger(minimumEligibleSamples) ||
+    minimumEligibleSamples <= 0
+  ) {
+    failures.push("MIN_ELIGIBLE_SAMPLES: must be a positive integer");
+  }
+
+  if (parsed.success) {
+    if (
+      parsed.data.thresholdDecision.minimumEligibleSamples !==
+      minimumEligibleSamples
+    ) {
+      failures.push(
+        "MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
+      );
+    }
+    if (Date.parse(parsed.data.window.end) > now.getTime()) {
+      failures.push("window.end: must not be in the future");
+    }
+    if (Date.parse(parsed.data.thresholdDecision.reviewedAt) > now.getTime()) {
+      failures.push("thresholdDecision.reviewedAt: must not be in the future");
+    }
+  }
+
+  return Object.freeze({
+    data: parsed.success ? parsed.data : null,
+    failures: Object.freeze(failures),
+    minimumEligibleSamples:
+      Number.isInteger(minimumEligibleSamples) && minimumEligibleSamples > 0
+        ? minimumEligibleSamples
+        : null,
+    passed: parsed.success && failures.length === 0,
+  });
+}

scripts/lib/hosting-probe.mjs

@@ -0,0 +1,68 @@
+const LOOPBACK_IPV4 = /^127(?:\.\d{1,3}){3}$/;
+
+/**
+ * A release gate must not promote a local preview server as live hosting
+ * evidence.
+ *
+ * @param {string} value
+ * @returns {
+ *   | { passed: true; reason: null; url: URL; observedOrigin: string }
+ *   | { passed: false; reason: string; url: URL | null; observedOrigin: string | null }
+ * }
+ */
+export function classifyLiveHostingBaseUrl(value) {
+  /** @type {URL} */
+  let url;
+  try {
+    url = new URL(value);
+  } catch {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be an absolute URL",
+      url: null,
+      observedOrigin: null,
+    };
+  }
+
+  const observedOrigin = url.origin;
+  const hostname = url.hostname.toLowerCase().replace(/^\[|\]$/g, "");
+  if (url.protocol !== "https:") {
+    return {
+      passed: false,
+      reason: "live hosting evidence requires HTTPS",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.username || url.password) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must not contain credentials",
+      url,
+      observedOrigin,
+    };
+  }
+  if (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    hostname === "::1" ||
+    hostname === "0.0.0.0" ||
+    LOOPBACK_IPV4.test(hostname)
+  ) {
+    return {
+      passed: false,
+      reason: "local or loopback hosts are not live deployment evidence",
+      url,
+      observedOrigin,
+    };
+  }
+  if (url.pathname !== "/" || url.search || url.hash) {
+    return {
+      passed: false,
+      reason: "HOSTING_BASE_URL must be the canonical root URL",
+      url,
+      observedOrigin,
+    };
+  }
+  return { passed: true, reason: null, url, observedOrigin };
+}

scripts/lib/manual-a11y-evidence.mjs

@@ -0,0 +1,61 @@
+export const MANUAL_A11Y_ROUTE_IDS = Object.freeze([
+  "APP_HOME",
+  "EXAMPLES_UI",
+  "EXAMPLES_STATES",
+  "EXAMPLES_AUTH",
+  "SAMPLE_RESOURCE_LIST",
+  "NOT_FOUND",
+]);
+
+const REVIEW_FIELDS = Object.freeze([
+  "M1 Keyboard",
+  "M2 Visible focus",
+  "M3 Route focus",
+  "M4 Modal focus",
+  "M5 Error association",
+  "M6 Color signal",
+  "M7 Reduced motion",
+  "Screen reader",
+]);
+
+/** @param {string} content */
+export function validateManualA11yEvidence(content) {
+  const fields = Object.fromEntries(
+    content
+      .split(/\r?\n/)
+      .map((line) => /^([^:]+):\s*(.*)$/.exec(line))
+      .filter(Boolean)
+      .map((match) => [
+        /** @type {RegExpExecArray} */ (match)[1].trim(),
+        /** @type {RegExpExecArray} */ (match)[2].trim(),
+      ]),
+  );
+  const failures = [];
+  if (fields.Status !== "reviewed") failures.push("Status");
+  if (!fields["Route ID"]) failures.push("Route ID");
+  if (!fields["Release ID"]) failures.push("Release ID");
+  if (!fields.Reviewer) failures.push("Reviewer");
+  if (!fields.Signature) failures.push("Signature");
+  if (fields.Attestation !== "accepted") failures.push("Attestation");
+  if (
+    !fields["Reviewed at"] ||
+    !Number.isFinite(Date.parse(fields["Reviewed at"]))
+  ) {
+    failures.push("Reviewed at");
+  }
+
+  for (const field of REVIEW_FIELDS) {
+    const result = fields[field];
+    if (
+      result !== "pass" &&
+      !/^not-applicable \(.+\)$/.test(result ?? "")
+    ) {
+      failures.push(field);
+    }
+  }
+  return Object.freeze({
+    fields: Object.freeze(fields),
+    failures: Object.freeze(failures),
+    passed: failures.length === 0,
+  });
+}

scripts/test-performance.mjs

@@ -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(

scripts/verify-a11y-manual.mjs

@@ -1,25 +1,71 @@
-import { readFile } from "node:fs/promises";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
 
-const evidence = await readFile(
+import {
-  "artifacts/tests/a11y-manual/APP_HOME.md",
+  MANUAL_A11Y_ROUTE_IDS,
-  "utf8",
+  validateManualA11yEvidence,
+} from "./lib/manual-a11y-evidence.mjs";
+
+/** @type {Array<{
+ * routeId: string;
+ * path: string;
+ * reviewer: string | null;
+ * reviewedAt: string | null;
+ * releaseId: string | null;
+ * failures: readonly string[];
+ * passed: boolean;
+ * }>} */
+const results = [];
+for (const routeId of MANUAL_A11Y_ROUTE_IDS) {
+  const path = `artifacts/tests/a11y-manual/${routeId}.md`;
+  const evidence = await readFile(path, "utf8");
+  const validation = validateManualA11yEvidence(evidence);
+  const failures =
+    validation.fields["Route ID"] === routeId
+      ? validation.failures
+      : Object.freeze([...validation.failures, "Route ID mismatch"]);
+  results.push({
+    routeId,
+    path,
+    reviewer: validation.fields.Reviewer ?? null,
+    reviewedAt: validation.fields["Reviewed at"] ?? null,
+    releaseId: validation.fields["Release ID"] ?? null,
+    failures,
+    passed: validation.passed && failures.length === 0,
+  });
+}
+const releaseIds = new Set(results.map((result) => result.releaseId));
+const passed =
+  results.every((result) => result.passed) &&
+  releaseIds.size === 1 &&
+  results.every((result) => Boolean(result.releaseId));
+
+await mkdir("artifacts/tests/a11y-manual", { recursive: true });
+await writeFile(
+  "artifacts/tests/a11y-manual/report.json",
+  `${JSON.stringify(
+    {
+      schemaVersion: 1,
+      generatedAt: new Date().toISOString(),
+      scope: MANUAL_A11Y_ROUTE_IDS,
+      results,
+      coherentRelease: releaseIds.size === 1,
+      passed,
+    },
+    null,
+    2,
+  )}\n`,
 );
 
-const required = [
+if (!passed) {
-  "Status: reviewed",
+  const failures = results
-  "Reviewer:",
+    .filter((result) => !result.passed)
-  "Keyboard:",
+    .map((result) => `${result.routeId}: ${result.failures.join(", ")}`);
-  "Focus:",
+  if (releaseIds.size !== 1) failures.push("release IDs do not match");
-  "Screen reader:",
-  "Reduced motion:",
-  "Color signal:",
-];
-
-const missing = required.filter((marker) => !evidence.includes(marker));
-if (missing.length > 0) {
   process.stderr.write(
-    `Manual accessibility evidence is incomplete: ${missing.join(", ")}\n`,
+    `Manual accessibility evidence is incomplete:\n${failures.join("\n")}\n`,
   );
   process.exit(1);
 }
-process.stdout.write("Manual accessibility evidence: PASS\n");
+process.stdout.write(
+  `Manual accessibility evidence: PASS (${results.length} routes)\n`,
+);

scripts/verify-hosting-headers.mjs

@@ -1,5 +1,7 @@
 import { mkdir, readFile, readdir, writeFile } from "node:fs/promises";
 
+import { classifyLiveHostingBaseUrl } from "./lib/hosting-probe.mjs";
+
 const cachePolicy = JSON.parse(
   await readFile("config/hosting/cache-policy.json", "utf8"),
 );
@@ -7,32 +9,85 @@ const securityPolicy = JSON.parse(
   await readFile("config/hosting/security-headers.json", "utf8"),
 );
 const baseUrl = process.env.HOSTING_BASE_URL;
+const liveTarget = baseUrl ? classifyLiveHostingBaseUrl(baseUrl) : null;
+const distFiles = (await readdir("dist", { recursive: true })).map(String);
+const publicSourceMaps = distFiles.filter((file) => file.endsWith(".map"));
+const publicServiceWorkers = distFiles.filter((file) =>
+  /(?:^|\/)(?:service-worker|sw)(?:[.-][^/]*)?\.js$/i.test(file),
+);
 
 /** @type {Record<string, Record<string, string>>} */
-let responses;
+let responses = {};
 let mode;
+/** @type {Array<{
+ * surface: string;
+ * header: string;
+ * expected: unknown;
+ * observed: unknown;
+ * reason?: string;
+ * passed: boolean;
+ * }>} */
+const probeResults = [];
 
-if (baseUrl) {
+if (liveTarget?.passed) {
   mode = "live";
   const assets = await readdir("dist/assets");
-  const hashedAsset = assets.find((file) => !file.endsWith(".map"));
+  const hashedJavaScript = assets.find((file) => file.endsWith(".js"));
-  if (!hashedAsset) throw new Error("No built hashed asset found.");
+  if (!hashedJavaScript) throw new Error("No built hashed JavaScript found.");
   const paths = {
     index: "/",
     runtimeConfig: "/config.json",
     releaseManifest: "/release-manifest.json",
-    hashedAsset: `/assets/${hashedAsset}`,
+    hashedAsset: `/assets/${hashedJavaScript}`,
   };
   responses = {};
   for (const [surface, pathname] of Object.entries(paths)) {
-    const response = await fetch(new URL(pathname, baseUrl));
+    const requestedUrl = new URL(pathname, liveTarget.url);
-    responses[surface] = Object.fromEntries(
+    try {
-      [...response.headers.entries()].map(([name, value]) => [
+      const response = await fetch(requestedUrl, { redirect: "follow" });
-        name.toLowerCase(),
+      const finalUrl = new URL(response.url);
-        value,
+      probeResults.push(
-      ]),
+        {
-    );
+          surface,
+          header: "http-status",
+          expected: 200,
+          observed: response.status,
+          passed: response.status === 200,
+        },
+        {
+          surface,
+          header: "final-origin",
+          expected: liveTarget.url.origin,
+          observed: finalUrl.origin,
+          passed: finalUrl.origin === liveTarget.url.origin,
+        },
+      );
+      responses[surface] = Object.fromEntries(
+        [...response.headers.entries()].map(([name, value]) => [
+          name.toLowerCase(),
+          value,
+        ]),
+      );
+    } catch (error) {
+      probeResults.push({
+        surface,
+        header: "transport",
+        expected: "reachable",
+        observed: error instanceof Error ? error.name : "UnknownError",
+        passed: false,
+      });
+    }
   }
+} else if (liveTarget) {
+  mode = "invalid-live";
+  probeResults.push({
+    surface: "deployment",
+    header: "base-url",
+    expected: "canonical non-loopback HTTPS root URL",
+    observed: liveTarget.observedOrigin,
+    reason: liveTarget.reason,
+    passed: false,
+  });
 } else {
   mode = "fixture";
   responses = JSON.parse(
@@ -40,7 +95,7 @@ if (baseUrl) {
   ).responses;
 }
 
-const results = [];
+const results = [...probeResults];
 for (const [surface, policy] of Object.entries(cachePolicy.surfaces)) {
   if (!("cacheControl" in policy)) continue;
   const observed = responses[surface]?.["cache-control"];
@@ -51,6 +106,18 @@ for (const [surface, policy] of Object.entries(cachePolicy.surfaces)) {
     observed,
     passed: observed === policy.cacheControl,
   });
+  const observedContentType = responses[surface]?.["content-type"];
+  const observedMime = observedContentType
+    ?.split(";", 1)[0]
+    .trim()
+    .toLowerCase();
+  results.push({
+    surface,
+    header: "content-type",
+    expected: policy.contentTypes,
+    observed: observedContentType,
+    passed: policy.contentTypes.includes(observedMime),
+  });
   if (policy.securityHeaders) {
     for (const [header, expected] of Object.entries(securityPolicy.headers)) {
       const observedSecurity = responses[surface]?.[header.toLowerCase()];
@@ -69,15 +136,19 @@ results.push({
   surface: "sourceMap",
   header: "public",
   expected: false,
-  observed: cachePolicy.surfaces.sourceMap.public,
+  observed: publicSourceMaps.length > 0,
-  passed: cachePolicy.surfaces.sourceMap.public === false,
+  passed:
+    cachePolicy.surfaces.sourceMap.public === false &&
+    publicSourceMaps.length === 0,
 });
 results.push({
   surface: "serviceWorker",
   header: "enabled",
   expected: false,
-  observed: cachePolicy.surfaces.serviceWorker.enabled,
+  observed: publicServiceWorkers.length > 0,
-  passed: cachePolicy.surfaces.serviceWorker.enabled === false,
+  passed:
+    cachePolicy.surfaces.serviceWorker.enabled === false &&
+    publicServiceWorkers.length === 0,
 });
 
 const passed = results.every((result) => result.passed);
@@ -89,7 +160,7 @@ await writeFile(
       schemaVersion: 1,
       generatedAt: new Date().toISOString(),
       mode,
-      baseUrl: baseUrl ?? null,
+      baseUrl: liveTarget?.observedOrigin ?? null,
       providerVerificationRequired: mode !== "live",
       results,
       passed,
@@ -100,7 +171,9 @@ await writeFile(
 );
 
 if (!passed) {
-  process.stderr.write("Hosting cache/security header verification failed.\n");
+  process.stderr.write(
+    "Hosting cache/content-type/security header verification failed.\n",
+  );
   process.exit(1);
 }
 process.stdout.write(

scripts/verify-release.mjs

@@ -2,7 +2,10 @@ import { createHash } from "node:crypto";
 import { mkdir, readFile, writeFile } from "node:fs/promises";
 
 import { verifyCompatibilityTuple } from "../src/application/policies/compatibility.js";
-import { compareReleaseToRuntime } from "../src/contracts/release-tokens.js";
+import {
+  compareReleaseToRuntime,
+  RELEASE_TOKEN_REGISTRY,
+} from "../src/contracts/release-tokens.js";
 
 const fixturesDocument =
   /** @type {{
@@ -38,6 +41,14 @@ const actualAssetManifestHash = createHash("sha256")
 
 const artifactComparison = compareReleaseToRuntime(release, runtimeConfig);
 const artifactMismatches = [...artifactComparison.mismatches];
+for (const token of Object.keys(RELEASE_TOKEN_REGISTRY)) {
+  if (typeof release[token] !== "string" || release[token].length === 0) {
+    artifactMismatches.push(`releaseToken:${token}`);
+  }
+}
+if (!Number.isFinite(Date.parse(release.builtAt))) {
+  artifactMismatches.push("releaseToken:builtAtFormat");
+}
 if (release.assetManifestHash !== actualAssetManifestHash) {
   artifactMismatches.push("assetManifestContent");
 }

scripts/write-a11y-report.mjs

@@ -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,10 +9,10 @@ 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/APP_HOME.md",
+      manualReview: "see artifacts/tests/a11y-manual/report.json",
     },
     null,
     2,

src/adapters/auth/external-session-adapter.js

@@ -4,6 +4,9 @@
  *
  * @param {{
  *   readState(): import("../../application/ports/auth-session-port.js").SessionState,
+ *   subscribe(listener: () => void): () => void,
+ *   beginSignIn(returnTo?: string): Promise<void>,
+ *   signOut(): Promise<void>,
  *   attachCredential(request: Request): Promise<Request>,
  *   recoverSession(): Promise<"restored" | "no-session">,
  *   notifyUnauthenticated(): void
@@ -15,6 +18,16 @@ export function createExternalAuthSessionAdapter(owner) {
     getState() {
       return owner.readState();
     },
+    subscribe(listener) {
+      return owner.subscribe(listener);
+    },
+    async beginSignIn(returnTo) {
+      await owner.beginSignIn(returnTo);
+    },
+    async signOut() {
+      await owner.signOut();
+    },
+    /** @param {Request} request */
     async attach(request) {
       const attached = await owner.attachCredential(request);
       if (!(attached instanceof Request)) {
@@ -38,8 +51,74 @@ export function createExternalAuthSessionAdapter(owner) {
 export function createAnonymousSessionAdapter() {
   return createExternalAuthSessionAdapter({
     readState: () => "unauthenticated",
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
     attachCredential: async (request) => request,
     recoverSession: async () => "no-session",
     notifyUnauthenticated: () => {},
   });
 }
+
+/**
+ * Local/test-only session seam. It never creates or stores credentials.
+ *
+ * @param {import("../../application/ports/auth-session-port.js").SessionState} [initialState]
+ */
+export function createDemoSessionAdapter(initialState = "unauthenticated") {
+  let state = initialState;
+  const listeners = new Set();
+
+  function notify() {
+    for (const listener of listeners) listener();
+  }
+
+  /** @param {import("../../application/ports/auth-session-port.js").SessionState} next */
+  function setState(next) {
+    state = next;
+    notify();
+  }
+
+  return Object.freeze({
+    getState: () => state,
+    /** @param {() => void} listener */
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    async beginSignIn() {
+      setState("authenticated");
+    },
+    async signOut() {
+      setState("unauthenticated");
+    },
+    /** @param {Request} request */
+    async attach(request) {
+      return request;
+    },
+    async recover() {
+      if (state === "recovery-pending") {
+        setState("authenticated");
+        return /** @type {const} */ ("restored");
+      }
+      return /** @type {const} */ ("no-session");
+    },
+    onUnauthenticated() {
+      setState("unauthenticated");
+    },
+    setState,
+  });
+}
+
+export function createUnavailableSessionAdapter() {
+  return Object.freeze({
+    getState: () => /** @type {const} */ ("integration-failed"),
+    subscribe: () => () => {},
+    beginSignIn: async () => {},
+    signOut: async () => {},
+    /** @param {Request} request */
+    attach: async (request) => request,
+    recover: async () => /** @type {const} */ ("no-session"),
+    onUnauthenticated: () => {},
+  });
+}

src/application/create-application.js

@@ -2,7 +2,7 @@
  * Application facade factory. Concrete dependencies are supplied by bootstrap.
  *
  * @param {{
- *   resources: {
+ *   resources?: {
  *     query: import("./ports/resource-ports.js").ResourceQueryPort<unknown, unknown>,
  *     command: import("./ports/resource-ports.js").ResourceCommandPort<unknown, unknown>
  *   },
@@ -17,7 +17,9 @@ export function createApplication(ports) {
    * @param {import("./ports/resource-ports.js").RequestContext} [context]
    */
   function queryResources(query, context) {
-    return ports.resources.query.execute(query, context);
+    return /** @type {NonNullable<typeof ports.resources>} */ (
+      ports.resources
+    ).query.execute(query, context);
   }
 
   /**
@@ -25,14 +27,18 @@ export function createApplication(ports) {
    * @param {import("./ports/resource-ports.js").RequestContext} [context]
    */
   function commandResources(command, context) {
-    return ports.resources.command.execute(command, context);
+    return /** @type {NonNullable<typeof ports.resources>} */ (
+      ports.resources
+    ).command.execute(command, context);
   }
 
   return Object.freeze({
-    resources: Object.freeze({
+    resources: ports.resources
-      query: queryResources,
+      ? Object.freeze({
-      command: commandResources,
+          query: queryResources,
-    }),
+          command: commandResources,
+        })
+      : null,
     cache: ports.cache,
     storage: ports.storage,
     telemetry: ports.telemetry,

src/application/policies/color-scheme.js

@@ -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;
+}

src/application/ports/auth-session-port.js

@@ -7,6 +7,9 @@
  *
  * @typedef {{
  *   getState(): SessionState,
+ *   subscribe(listener: () => void): () => void,
+ *   beginSignIn(returnTo?: string): Promise<void>,
+ *   signOut(): Promise<void>,
  *   attach(request: Request): Promise<Request>,
  *   recover(): Promise<"restored" | "no-session">,
  *   onUnauthenticated(): void

src/bootstrap/composition-root.js

@@ -4,14 +4,23 @@ import { createApplication } from "../application/create-application.js";
  * This is the only module allowed to join concrete adapters to application
  * ports. Boot phases are explicit so failures can stop before product mount.
  *
+ * @template Config
+ * @template Release
+ * @template {Parameters<typeof createApplication>[0]} Ports
  * @param {{
- *   loadConfig(): Promise<Record<string, unknown>>,
+ *   loadConfig(): Promise<Config>,
- *   loadRelease(config: Record<string, unknown>): Promise<Record<string, unknown>>,
+ *   loadRelease(config: Config): Promise<Release>,
  *   createAdapters(context: {
- *     config: Record<string, unknown>,
+ *     config: Config,
- *     release: Record<string, unknown>
+ *     release: Release
- *   }): Promise<Parameters<typeof createApplication>[0]>
+ *   }): Promise<Ports>
  * }} factories
+ * @returns {Promise<Readonly<{
+ *   config: Config,
+ *   release: Release,
+ *   ports: Ports,
+ *   application: ReturnType<typeof createApplication>
+ * }>>}
  */
 export async function createCompositionRoot(factories) {
   const config = await factories.loadConfig();

src/bootstrap/create-runtime-composition.js

@@ -0,0 +1,32 @@
+import { createCompositionRoot } from "./composition-root.js";
+import { loadReleaseManifest } from "./load-release-manifest.js";
+import { loadRuntimeConfig } from "./load-runtime-config.js";
+import { createRuntimeAdapters } from "./runtime-adapters.js";
+
+/**
+ * @param {{
+ *   fetcher?: typeof fetch,
+ *   host?: Record<string, unknown>
+ * }} [dependencies]
+ */
+export function createRuntimeComposition(dependencies = {}) {
+  return createCompositionRoot({
+    loadConfig: () => loadRuntimeConfig({ fetcher: dependencies.fetcher }),
+    loadRelease: (runtime) =>
+      loadReleaseManifest(
+        /** @type {Awaited<ReturnType<typeof loadRuntimeConfig>>} */ (runtime),
+        { fetcher: dependencies.fetcher },
+      ),
+    createAdapters: ({ config: runtime, release }) =>
+      createRuntimeAdapters({
+        runtime:
+          /** @type {Awaited<ReturnType<typeof loadRuntimeConfig>>} */ (runtime),
+        release:
+          /** @type {Awaited<ReturnType<typeof loadReleaseManifest>>} */ (
+            release
+          ),
+        fetcher: dependencies.fetcher,
+        host: dependencies.host,
+      }),
+  });
+}

src/bootstrap/initialize-color-scheme.js

@@ -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 });
+}

src/bootstrap/load-release-manifest.js

@@ -0,0 +1,107 @@
+import { z } from "zod";
+
+const version = z.string().regex(/^\d+(?:\.\d+){0,2}$/);
+const releaseManifestSchema = z
+  .object({
+    schemaVersion: z.literal(1),
+    appVersion: z.string().min(1),
+    buildId: z.string().min(1),
+    commitSha: z.string().min(1),
+    configSchemaVersion: version,
+    apiContractVersion: version,
+    assetManifestHash: z.string().min(1),
+    releaseId: z.string().min(1),
+    builtAt: z.string().min(1),
+  })
+  .strict();
+
+export class ReleaseManifestError extends Error {
+  /** @param {string} code @param {{buildId: string, releaseId?: string}} safe */
+  constructor(code, safe) {
+    super("Release manifest could not be loaded");
+    this.name = "ReleaseManifestError";
+    this.kind = "RELEASE_MANIFEST_FAILURE";
+    this.code = code;
+    this.safe = Object.freeze({
+      kind: this.kind,
+      code,
+      buildId: safe.buildId,
+      releaseId: safe.releaseId,
+      supportReference: `${safe.buildId}:${code}`,
+    });
+  }
+}
+
+/**
+ * @param {Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>} runtime
+ * @param {{fetcher?: typeof fetch}} [options]
+ */
+export async function loadReleaseManifest(runtime, options = {}) {
+  const fetcher = options.fetcher ?? fetch;
+  let response;
+  try {
+    response = await fetcher(runtime.config.RELEASE_MANIFEST_URL, {
+      cache: "no-store",
+      headers: { Accept: "application/json" },
+    });
+  } catch {
+    throw new ReleaseManifestError("MANIFEST_FETCH_FAILED", {
+      buildId: runtime.build.buildId,
+      releaseId: runtime.config.RELEASE_ID,
+    });
+  }
+  if (!response.ok) {
+    throw new ReleaseManifestError("MANIFEST_HTTP_FAILED", {
+      buildId: runtime.build.buildId,
+      releaseId: runtime.config.RELEASE_ID,
+    });
+  }
+
+  let raw;
+  try {
+    raw = await response.json();
+  } catch {
+    throw new ReleaseManifestError("MANIFEST_JSON_INVALID", {
+      buildId: runtime.build.buildId,
+      releaseId: runtime.config.RELEASE_ID,
+    });
+  }
+  const parsed = releaseManifestSchema.safeParse(raw);
+  if (!parsed.success) {
+    throw new ReleaseManifestError("MANIFEST_SCHEMA_INVALID", {
+      buildId: runtime.build.buildId,
+      releaseId: runtime.config.RELEASE_ID,
+    });
+  }
+
+  const manifest = parsed.data;
+  const mismatches = [];
+  if (manifest.buildId !== runtime.build.buildId) mismatches.push("buildId");
+  if (
+    runtime.config.BUILD_ID &&
+    manifest.buildId !== runtime.config.BUILD_ID
+  ) {
+    mismatches.push("runtimeBuildId");
+  }
+  if (
+    manifest.configSchemaVersion !== runtime.config.CONFIG_SCHEMA_VERSION
+  ) {
+    mismatches.push("configSchemaVersion");
+  }
+  if (manifest.apiContractVersion !== runtime.config.API_CONTRACT_VERSION) {
+    mismatches.push("apiContractVersion");
+  }
+  if (
+    runtime.config.RELEASE_ID &&
+    manifest.releaseId !== runtime.config.RELEASE_ID
+  ) {
+    mismatches.push("releaseId");
+  }
+  if (mismatches.length > 0) {
+    throw new ReleaseManifestError("MANIFEST_RUNTIME_MISMATCH", {
+      buildId: runtime.build.buildId,
+      releaseId: runtime.config.RELEASE_ID,
+    });
+  }
+  return Object.freeze(structuredClone(manifest));
+}

src/bootstrap/main.jsx

@@ -1,10 +1,13 @@
 import { StrictMode } from "react";
 import { createRoot } from "react-dom/client";
+import { QueryClientProvider } from "@tanstack/react-query";
 
-import { createAnonymousSessionAdapter } from "../adapters/auth/external-session-adapter.js";
 import { BootErrorShell } from "../presentation/boundaries/boot-error-shell.jsx";
 import { AppRouter } from "../presentation/routes/app-router.jsx";
-import { BootConfigError, loadRuntimeConfig } from "./load-runtime-config.js";
+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";
 
 const rootElement = document.getElementById("root");
@@ -17,18 +20,24 @@ const root = createRoot(rootElement);
 
 async function boot() {
   try {
-    const runtime = await loadRuntimeConfig();
+    const composition = await createRuntimeComposition();
+    initializeColorScheme(composition.ports.storage);
     root.render(
       <StrictMode>
-        <AppRouter
+        <QueryClientProvider client={composition.ports.queryClient}>
-          authSession={createAnonymousSessionAdapter()}
+          <AppRouter
-          basename={runtime.build.routerBasePath}
+            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) {
     const safe =
-      error instanceof BootConfigError
+      error instanceof BootConfigError || error instanceof ReleaseManifestError
         ? error.safe
         : { supportReference: "boot:unknown" };
 

src/bootstrap/runtime-adapters.js

@@ -0,0 +1,94 @@
+import {
+  createDemoSessionAdapter,
+  createExternalAuthSessionAdapter,
+  createUnavailableSessionAdapter,
+} from "../adapters/auth/external-session-adapter.js";
+import { createHttpClient } from "../adapters/http/client.js";
+import {
+  createQueryCacheAdapter,
+  createQueryClient,
+} from "../adapters/query-cache/tanstack-query-cache.js";
+import { createBrowserStorageAdapter } from "../adapters/storage/browser-storage-adapter.js";
+import { createTelemetryAdapter } from "../adapters/telemetry/best-effort-telemetry.js";
+
+/**
+ * @param {Record<string, unknown>} host
+ * @returns {Parameters<typeof createExternalAuthSessionAdapter>[0] | null}
+ */
+function externalOwnerFrom(host) {
+  const candidate = host.__CA_FRONTEND_AUTH_OWNER__;
+  if (!candidate || typeof candidate !== "object") return null;
+  const owner = /** @type {Record<string, unknown>} */ (candidate);
+  const required = [
+    "readState",
+    "subscribe",
+    "beginSignIn",
+    "signOut",
+    "attachCredential",
+    "recoverSession",
+    "notifyUnauthenticated",
+  ];
+  return required.every((name) => typeof owner[name] === "function")
+    ? /** @type {Parameters<typeof createExternalAuthSessionAdapter>[0]} */ (
+        candidate
+      )
+    : null;
+}
+
+/** @param {unknown} value */
+function storageOrUndefined(value) {
+  return typeof Storage !== "undefined" && value instanceof Storage
+    ? value
+    : undefined;
+}
+
+/**
+ * @param {{
+ *   runtime: Awaited<ReturnType<typeof import("./load-runtime-config.js").loadRuntimeConfig>>,
+ *   release: Awaited<ReturnType<typeof import("./load-release-manifest.js").loadReleaseManifest>>,
+ *   host?: Record<string, unknown>,
+ *   fetcher?: typeof fetch
+ * }} context
+ */
+export async function createRuntimeAdapters(context) {
+  const host = context.host ?? /** @type {Record<string, unknown>} */ (globalThis);
+  const config = context.runtime.config;
+  const externalOwner = externalOwnerFrom(host);
+  const authSession =
+    config.AUTH_MODE === "demo"
+      ? createDemoSessionAdapter()
+      : externalOwner
+        ? createExternalAuthSessionAdapter(externalOwner)
+        : createUnavailableSessionAdapter();
+  const queryClient = createQueryClient();
+  const cache = createQueryCacheAdapter(queryClient);
+  const storage = createBrowserStorageAdapter({
+    localStorage: storageOrUndefined(host.localStorage),
+    sessionStorage: storageOrUndefined(host.sessionStorage),
+  });
+  const telemetry = createTelemetryAdapter({
+    enabled: config.TELEMETRY_ENABLED,
+    endpoint: config.TELEMETRY_ENDPOINT,
+    fetcher: context.fetcher,
+  });
+  const http = createHttpClient({
+    baseUrl: config.API_BASE_URL,
+    authSession,
+    fetcher: context.fetcher,
+  });
+  const releaseInfo = Object.freeze({
+    async getCurrent() {
+      return structuredClone(context.release);
+    },
+  });
+
+  return Object.freeze({
+    authSession,
+    cache,
+    http,
+    queryClient,
+    releaseInfo,
+    storage,
+    telemetry,
+  });
+}

src/bootstrap/runtime-config-schema.js

@@ -10,7 +10,7 @@ export const runtimeConfigSchema = z
     MAX_RETRY_ATTEMPTS: z.int().min(0).max(2).default(2),
     TELEMETRY_ENABLED: z.boolean(),
     TELEMETRY_ENDPOINT: z.url().optional(),
-    AUTH_MODE: z.literal("external"),
+    AUTH_MODE: z.enum(["external", "demo"]),
     CONFIG_SCHEMA_VERSION: version,
     API_CONTRACT_VERSION: version,
     RELEASE_MANIFEST_URL: z.string().min(1).default("/release-manifest.json"),
@@ -28,6 +28,13 @@ export const runtimeConfigSchema = z
     }
 
     const local = config.APP_ENV === "local" || config.APP_ENV === "development";
+    if (!local && config.AUTH_MODE === "demo") {
+      context.addIssue({
+        code: "custom",
+        path: ["AUTH_MODE"],
+        message: "demo authentication is limited to local environments",
+      });
+    }
     const endpointEntries =
       /** @type {Array<[string, string | undefined]>} */ ([
         ["API_BASE_URL", config.API_BASE_URL],

src/contracts/routes.js

@@ -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>>} */ (

src/presentation/components/async-surface.jsx

@@ -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">
+    <section className="ui-empty state-surface" aria-live="polite">
-      <p>{title}</p>
+      <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}>
+        <Button onClick={onAction}>{actionLabels[action]}</Button>
-          {action}
-        </button>
       )}
     </section>
   );

src/presentation/components/error-copy.js

@@ -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] ?? "요청을 완료하지 못했습니다.";
+}

src/presentation/components/page-header.jsx

@@ -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>
+  );
+}

src/presentation/components/state-surfaces.jsx

@@ -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}
+    />
+  );
+}

src/presentation/components/ui/alert.jsx

@@ -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>
+  );
+}

src/presentation/components/ui/badge.jsx

@@ -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>;
+}

src/presentation/components/ui/button.jsx

@@ -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} />;
+}

src/presentation/components/ui/card.jsx

@@ -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>
+  );
+}

src/presentation/components/ui/dialog.jsx

@@ -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>
+  );
+}

src/presentation/components/ui/text-field.jsx

@@ -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>
+  );
+}

src/presentation/examples/auth-example-page.jsx

@@ -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>
+  );
+}

src/presentation/examples/state-gallery-page.jsx

@@ -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>
+  );
+}

src/presentation/examples/ui-gallery-page.jsx

@@ -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>
+  );
+}

src/presentation/layouts/app-shell.jsx

@@ -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>
+  );
+}

src/presentation/pages/home-page.jsx

@@ -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>
+  );
+}

src/presentation/pages/not-found-page.jsx

@@ -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>
+  );
+}

src/presentation/pages/sample-contract-page.jsx

@@ -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>
+  );
+}

src/presentation/providers/session-provider.jsx

@@ -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;
+}

src/presentation/providers/theme-provider.jsx

@@ -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;
+}

src/presentation/routes/app-router.jsx

@@ -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">
+    <section className="ui-page route-loading" aria-live="polite" aria-busy="true">
-      <h1>Clean Architecture Frontend</h1>
+      <div className="ui-skeleton" aria-hidden="true" />
-      <p>런타임 계약이 검증되었습니다.</p>
+      <p>화면을 준비하고 있습니다.</p>
-      <Link to={routePath("SAMPLE_RESOURCE_LIST")}>샘플 리소스</Link>
+      <span className="visually-hidden">{definition.title} 로딩 중</span>
-    </main>
+    </section>
   );
 }
 
-function SamplePlaceholder() {
+function RouteFailureSurface() {
   return (
-    <main className="ui-page">
+    <section className="ui-page">
-      <h1>샘플 리소스</h1>
+      <PageHeader
-      <p>계약 fixture를 준비하고 있습니다.</p>
+        title="화면을 표시하지 못했습니다."
-    </main>
+        description="잠시 후 페이지를 새로고침해 주세요. 문제가 계속되면 운영 지원 참조 정보를 확인하세요."
-  );
+      />
-}
+    </section>
-
-function NotFoundPage() {
-  return (
-    <main className="ui-page">
-      <h1>페이지를 찾을 수 없습니다.</h1>
-      <Link to={routePath("APP_HOME")}>홈으로 이동</Link>
-    </main>
   );
 }
 
 /**
  * @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 }) {
+function RouteSurface({ routeId, buildId, telemetry, children }) {
-  const decision = decideRouteAccess(
+  return (
-    "SAMPLE_RESOURCE_LIST",
+    <RouteBoundary
-    authSession.getState(),
+      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">
+      <section className="ui-page">
-        <h1>세션이 필요합니다.</h1>
+        <PageHeader
-        <button className="ui-button" type="button">
+          title="로그인 연동이 필요합니다."
-          로그인
+          description="외부 인증 소유자가 런타임에 연결되면 이 보호 라우트를 사용할 수 있습니다."
-        </button>
+        />
-      </main>
+      </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>
+      <ThemeProvider storage={storage}>
-        <Route path={routePath("APP_HOME")} element={<HomePage />} />
+        <SessionProvider authSession={authSession}>
-        <Route
+          <Routes>
-          path={routePath("SAMPLE_RESOURCE_LIST")}
+            <Route element={<AppShell />}>
-          element={<GuardedSampleRoute authSession={authSession} />}
+            <Route
-        />
+              index
-        <Route path={routePath("NOT_FOUND")} element={<NotFoundPage />} />
+              element={
-      </Routes>
+                <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>
   );
 }

src/presentation/styles/theme.css

@@ -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) {

tests/component/async-surface.test.jsx

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

tests/component/render-boundary.test.jsx

@@ -44,7 +44,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", () => {

tests/component/router.test.jsx

@@ -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 구성요소", exact: true }),
+    );
+
+    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();
   });
 });

tests/component/sample-resource-page.test.jsx

@@ -44,6 +44,11 @@ describe("removable sample feature page", () => {
     };
     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",
+    );
   });
 });

tests/component/ui-primitives.test.jsx

@@ -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",
+    );
+  });
+});

tests/e2e/accessibility.spec.js

@@ -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,8 +28,9 @@ test("@a11y keyboard reaches the primary route action with visible focus", async
   page,
 }) => {
   await page.goto("/");
+  const action = page.getByRole("link", { name: "UI 구성요소 보기" });
+  await expect(action).toBeVisible();
   await page.keyboard.press("Tab");
-  const action = page.getByRole("link", { name: "샘플 리소스" });
   await expect(action).toBeFocused();
   await expect(action).toHaveCSS("outline-style", "solid");
 });

tests/e2e/app-shell.spec.js

@@ -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();
 });

tests/e2e/responsive.spec.js

@@ -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/,
+  );
+});

tests/e2e/theme.spec.js

@@ -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");
+});

tests/e2e/ui-gallery.spec.js

@@ -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();
+});

tests/runtime-schema/release-manifest.test.js

@@ -0,0 +1,51 @@
+import { describe, expect, it } from "vitest";
+
+import {
+  loadReleaseManifest,
+  ReleaseManifestError,
+} from "../../src/bootstrap/load-release-manifest.js";
+
+const runtime = {
+  build: { buildId: "build-a" },
+  config: {
+    RELEASE_MANIFEST_URL: "/release-manifest.json",
+    BUILD_ID: "build-a",
+    RELEASE_ID: "release-a",
+    CONFIG_SCHEMA_VERSION: "1",
+    API_CONTRACT_VERSION: "1",
+  },
+};
+const manifest = {
+  schemaVersion: 1,
+  appVersion: "0.1.0",
+  buildId: "build-a",
+  commitSha: "abc123",
+  configSchemaVersion: "1",
+  apiContractVersion: "1",
+  assetManifestHash: "hash-a",
+  releaseId: "release-a",
+  builtAt: "2026-07-25T00:00:00Z",
+};
+
+describe("release manifest boot boundary", () => {
+  it("loads a coherent release tuple", async () => {
+    await expect(
+      loadReleaseManifest(
+        /** @type {Parameters<typeof loadReleaseManifest>[0]} */ (runtime),
+        { fetcher: async () => new Response(JSON.stringify(manifest)) },
+      ),
+    ).resolves.toMatchObject({ releaseId: "release-a" });
+  });
+
+  it("fails before mount when release and runtime differ", async () => {
+    await expect(
+      loadReleaseManifest(
+        /** @type {Parameters<typeof loadReleaseManifest>[0]} */ (runtime),
+        {
+          fetcher: async () =>
+            new Response(JSON.stringify({ ...manifest, buildId: "build-b" })),
+        },
+      ),
+    ).rejects.toBeInstanceOf(ReleaseManifestError);
+  });
+});

tests/runtime-schema/runtime-config.test.js

@@ -35,6 +35,20 @@ describe("runtime configuration boundary", () => {
     );
   });
 
+  it("allows demo authentication only for local runtime configuration", () => {
+    expect(
+      validateRuntimeConfig({ ...validConfig, AUTH_MODE: "demo" }).success,
+    ).toBe(true);
+    expect(
+      validateRuntimeConfig({
+        ...validConfig,
+        APP_ENV: "production",
+        API_BASE_URL: "https://api.example.test",
+        AUTH_MODE: "demo",
+      }).success,
+    ).toBe(false);
+  });
+
   it("validates a fetched config under the 500ms budget excluding network", async () => {
     let current = 100;
     const result = await loadRuntimeConfig({

tests/unit/auth-session-adapter.test.js

@@ -2,6 +2,7 @@ import { describe, expect, it, vi } from "vitest";
 
 import {
   createAnonymousSessionAdapter,
+  createDemoSessionAdapter,
   createExternalAuthSessionAdapter,
 } from "../../src/adapters/auth/external-session-adapter.js";
 
@@ -9,6 +10,9 @@ describe("external AuthSessionPort adapter", () => {
   it("attaches opaque credentials without exposing a token-shaped session", async () => {
     const adapter = createExternalAuthSessionAdapter({
       readState: () => "authenticated",
+      subscribe: () => () => {},
+      beginSignIn: async () => {},
+      signOut: async () => {},
       attachCredential: async (request) => {
         const headers = new Headers(request.headers);
         headers.set("X-Session-Attached", "true");
@@ -28,6 +32,9 @@ describe("external AuthSessionPort adapter", () => {
   it("fails invalid recovery states closed", async () => {
     const adapter = createExternalAuthSessionAdapter({
       readState: () => "authenticated",
+      subscribe: () => () => {},
+      beginSignIn: async () => {},
+      signOut: async () => {},
       attachCredential: async (request) => request,
       recoverSession: async () => "unexpected",
       notifyUnauthenticated: vi.fn(),
@@ -41,4 +48,20 @@ describe("external AuthSessionPort adapter", () => {
     expect(adapter.getState()).toBe("unauthenticated");
     await expect(adapter.recover()).resolves.toBe("no-session");
   });
+
+  it("provides a reactive credential-free demo seam", async () => {
+    const adapter = createDemoSessionAdapter();
+    let notifications = 0;
+    const unsubscribe = adapter.subscribe(() => {
+      notifications += 1;
+    });
+
+    expect(adapter.getState()).toBe("unauthenticated");
+    await adapter.beginSignIn("/");
+    expect(adapter.getState()).toBe("authenticated");
+    await adapter.signOut();
+    expect(adapter.getState()).toBe("unauthenticated");
+    expect(notifications).toBe(2);
+    unsubscribe();
+  });
 });

tests/unit/bundle-classification.test.js

@@ -0,0 +1,40 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyViteJavascript } from "../../scripts/lib/classify-vite-bundle.mjs";
+
+describe("Vite bundle classification", () => {
+  it("counts transitive static imports as initial and keeps dynamic chunks lazy", () => {
+    expect(
+      classifyViteJavascript({
+        "index.html": {
+          file: "assets/entry.js",
+          isEntry: true,
+          imports: ["_shared.js"],
+        },
+        "_shared.js": { file: "assets/shared.js", imports: ["_runtime.js"] },
+        "_runtime.js": { file: "assets/runtime.js" },
+        "src/lazy.js": { file: "assets/lazy.js" },
+      }),
+    ).toEqual({
+      initialFiles: [
+        "assets/entry.js",
+        "assets/runtime.js",
+        "assets/shared.js",
+      ],
+      lazyFiles: ["assets/lazy.js"],
+      missingImports: [],
+    });
+  });
+
+  it("reports a manifest import that cannot be resolved", () => {
+    expect(
+      classifyViteJavascript({
+        "index.html": {
+          file: "assets/entry.js",
+          isEntry: true,
+          imports: ["_missing.js"],
+        },
+      }).missingImports,
+    ).toEqual(["_missing.js"]);
+  });
+});

tests/unit/color-scheme.test.js

@@ -0,0 +1,44 @@
+// @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 = {
+      read: () => ({ ok: true, value: "system" }),
+      write: () => ({ ok: true }),
+      remove: () => ({ ok: 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");
+  });
+});

tests/unit/field-vitals-evidence.test.js

@@ -0,0 +1,94 @@
+import { describe, expect, it } from "vitest";
+
+import { validateFieldEvidenceInput } from "../../scripts/lib/field-vitals-evidence.mjs";
+
+const input = {
+  schemaVersion: 1,
+  environment: "production",
+  releaseId: "release-2026-06-29",
+  source: {
+    system: "privacy-approved-rum-export",
+    exportId: "export-2026-06-29",
+  },
+  privacy: {
+    approved: true,
+    approvalRef: "PRIVACY-42",
+  },
+  window: {
+    start: "2026-06-01T00:00:00Z",
+    end: "2026-06-29T00:00:00Z",
+  },
+  thresholdDecision: {
+    status: "approved",
+    minimumEligibleSamples: 25,
+    owner: "performance-owner",
+    reviewedAt: "2026-06-30T00:00:00Z",
+    evidenceRef: "PERF-BASELINE-7",
+  },
+  samples: [
+    {
+      timestamp: "2026-06-20T00:00:00Z",
+      consent: true,
+      releaseId: "release-2026-06-29",
+      routeId: "APP_HOME",
+      lcpMs: 1200,
+      cls: 0.01,
+      inpMs: 80,
+    },
+  ],
+};
+
+describe("field Web Vitals evidence input", () => {
+  it("accepts reviewed, coherent 28-day production metadata", () => {
+    expect(
+      validateFieldEvidenceInput(
+        input,
+        "25",
+        new Date("2026-07-01T00:00:00Z"),
+      ),
+    ).toMatchObject({
+      failures: [],
+      minimumEligibleSamples: 25,
+      passed: true,
+    });
+  });
+
+  it("rejects a threshold that does not match the owner decision", () => {
+    expect(
+      validateFieldEvidenceInput(
+        input,
+        "10",
+        new Date("2026-07-01T00:00:00Z"),
+      ),
+    ).toMatchObject({
+      failures: [
+        "MIN_ELIGIBLE_SAMPLES: does not match the approved threshold decision",
+      ],
+      passed: false,
+    });
+  });
+
+  it("rejects local, unapproved, malformed, or impossible measurements", () => {
+    const invalid = {
+      ...input,
+      environment: "local",
+      releaseId: "local-release",
+      privacy: { approved: false, approvalRef: "" },
+      window: { ...input.window, end: "2026-06-28T00:00:00Z" },
+      samples: [{ ...input.samples[0], lcpMs: -1 }],
+    };
+    const validation = validateFieldEvidenceInput(
+      invalid,
+      "-1",
+      new Date("2026-07-01T00:00:00Z"),
+    );
+    expect(validation.passed).toBe(false);
+    expect(validation.failures.join("\n")).toContain("environment");
+    expect(validation.failures.join("\n")).toContain("releaseId");
+    expect(validation.failures.join("\n")).toContain("privacy");
+    expect(validation.failures.join("\n")).toContain("lcpMs");
+    expect(validation.failures.join("\n")).toContain(
+      "MIN_ELIGIBLE_SAMPLES: must be a positive integer",
+    );
+  });
+});

tests/unit/hosting-probe.test.js

@@ -0,0 +1,27 @@
+import { describe, expect, it } from "vitest";
+
+import { classifyLiveHostingBaseUrl } from "../../scripts/lib/hosting-probe.mjs";
+
+describe("live hosting evidence target", () => {
+  it("accepts a canonical production HTTPS root", () => {
+    expect(
+      classifyLiveHostingBaseUrl("https://frontend.example.test/"),
+    ).toMatchObject({
+      passed: true,
+      observedOrigin: "https://frontend.example.test",
+    });
+  });
+
+  it.each([
+    ["http://frontend.example.test/", "requires HTTPS"],
+    ["https://localhost:4173/", "not live deployment evidence"],
+    ["https://127.0.0.1/", "not live deployment evidence"],
+    ["https://frontend.example.test/app/", "canonical root URL"],
+    ["https://user:secret@frontend.example.test/", "must not contain credentials"],
+  ])("rejects %s", (url, reason) => {
+    expect(classifyLiveHostingBaseUrl(url)).toMatchObject({
+      passed: false,
+      reason: expect.stringContaining(reason),
+    });
+  });
+});

tests/unit/manual-a11y-evidence.test.js

@@ -0,0 +1,67 @@
+import { describe, expect, it } from "vitest";
+
+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
+Release ID: release-1
+Reviewer: reviewer@example.test
+Reviewed at: 2026-07-25T12:00:00Z
+Signature: review-record-1
+Attestation: accepted
+M1 Keyboard: pass
+M2 Visible focus: pass
+M3 Route focus: pass
+M4 Modal focus: not-applicable (no modal)
+M5 Error association: not-applicable (no form error)
+M6 Color signal: pass
+M7 Reduced motion: pass
+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: [],
+      passed: true,
+    });
+  });
+
+  it("rejects pending, unsigned, or incomplete evidence", () => {
+    expect(
+      validateManualA11yEvidence(
+        reviewed
+          .replace("Status: reviewed", "Status: pending-manual-review")
+          .replace("Signature: review-record-1", "Signature:")
+          .replace("Screen reader: pass", "Screen reader: pending"),
+      ),
+    ).toMatchObject({
+      failures: ["Status", "Signature", "Screen reader"],
+      passed: false,
+    });
+  });
+
+  it("does not treat an unexplained not-applicable verdict as evidence", () => {
+    expect(
+      validateManualA11yEvidence(
+        reviewed.replace(
+          "M4 Modal focus: not-applicable (no modal)",
+          "M4 Modal focus: not-applicable",
+        ),
+      ),
+    ).toMatchObject({
+      failures: ["M4 Modal focus"],
+      passed: false,
+    });
+  });
+});

tests/unit/navigation-policy.test.js

@@ -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,

tests/unit/runtime-adapters.test.js

@@ -0,0 +1,57 @@
+import { describe, expect, it } from "vitest";
+
+import { createRuntimeAdapters } from "../../src/bootstrap/runtime-adapters.js";
+
+const runtime = {
+  config: {
+    APP_ENV: "local",
+    API_BASE_URL: "http://localhost:8080",
+    TELEMETRY_ENABLED: false,
+    AUTH_MODE: "demo",
+  },
+};
+const release = {
+  schemaVersion: 1,
+  appVersion: "0.1.0",
+  buildId: "build-a",
+  commitSha: "abc123",
+  configSchemaVersion: "1",
+  apiContractVersion: "1",
+  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 () => {
+    const adapters = await createRuntimeAdapters({
+      runtime:
+        /** @type {Parameters<typeof createRuntimeAdapters>[0]["runtime"]} */ (
+          runtime
+        ),
+      release,
+      host: {},
+    });
+
+    expect(adapters.authSession.getState()).toBe("unauthenticated");
+    expect(adapters.cache.read(["missing"])).toEqual({
+      ok: true,
+      value: undefined,
+    });
+    await expect(adapters.releaseInfo.getCurrent()).resolves.toMatchObject({
+      releaseId: "release-a",
+    });
+  });
+
+  it("fails closed when an external auth owner was not installed", async () => {
+    const adapters = await createRuntimeAdapters({
+      runtime:
+        /** @type {Parameters<typeof createRuntimeAdapters>[0]["runtime"]} */ ({
+          config: { ...runtime.config, AUTH_MODE: "external" },
+        }),
+      release,
+      host: {},
+    });
+    expect(adapters.authSession.getState()).toBe("integration-failed");
+  });
+});