feat: assemble responsive app shell navigation

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

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