Add the module navigation contract: manifest v9, module routes, return-to-origin

Stage 1 PR 7 (ADR 0063). A module becomes a first-class part of the Dashboard.

- Manifest v9 = v8 plus optional `navigation`: a Lucide icon from the curated
  MODULE_NAVIGATION_ICONS set, and up to 12 primary pages (stable id, safe
  label, kebab-case path relative to the module root; no traversal, schemes,
  queries, duplicates, or nesting). Validated before activation.
- Version 8 stays accepted beside version 9, each read strictly as itself
  (discriminated union); no released manifest is rewritten. The template
  moves to v9; the released Signage 0.1.5 manifest is a test fixture.
- Real module routes: /<id> is the landing view, /<id>/<page> a declared
  page, anything beneath a page a module-owned detail route; anything else
  is not-found and mounts nothing. api/assets/display are never pages.
- Sidebar: declared icons, pages nested under an open module, one
  aria-current, collapsed and drawer behaviour; v8 modules unchanged.
- module-ui-sdk: ModuleUiHostContext.navigation (location, subscribe,
  navigate, link, settings), refusing anything outside the module's routes;
  undefined on the display host. Mount ABI unchanged.
- Return-to-origin: one `?return=` carrier on Settings URLs, validated by
  parseReturnTarget and against running modules' declared routes; Settings
  Back returns to exactly the originating module page, across refreshes.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

apps/api/tests/dashboard-routes.test.ts

@@ -55,6 +55,8 @@ interface ModuleFixture {
   readonly id: string;
   readonly name: string;
   readonly withUi?: boolean;
+  /** Present, the fixture is a manifest v9 module declaring this navigation (ADR 0063). */
+  readonly navigation?: unknown;
 }
 
 async function createModule(modulesDirectory: string, fixture: ModuleFixture): Promise<void> {
@@ -78,8 +80,9 @@ async function createModule(modulesDirectory: string, fixture: ModuleFixture): P
         ...(fixture.withUi === false ? {} : { ui: "./dist/ui/index.js" }),
       },
       id: fixture.id,
-      manifestVersion: 8,
+      manifestVersion: fixture.navigation === undefined ? 8 : 9,
       name: fixture.name,
+      ...(fixture.navigation === undefined ? {} : { navigation: fixture.navigation }),
       version: "1.0.0",
     }),
   );
@@ -170,6 +173,14 @@ function signedIn(): EkklesiaPrincipal {
 
 interface NavigationEntry {
   readonly name: string;
+  readonly navigation: {
+    readonly icon: string | null;
+    readonly pages: readonly {
+      readonly id: string;
+      readonly label: string;
+      readonly path: string;
+    }[];
+  };
   readonly module: {
     readonly id: string;
     readonly version: string;
@@ -284,7 +295,68 @@ describe("Dashboard navigation — reading", () => {
       ui: { url: "/api/v1/module-ui/livestream/1.0.0" },
       version: "1.0.0",
     });
-    expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name"]);
+    expect(Object.keys(livestream ?? {}).sort()).toEqual(["module", "name", "navigation"]);
+    // A module that declares no navigation — this manifest v8 fixture — is drawn with the generic
+    // icon and has its root as its only page (ADR 0063). Never a group or an order.
+    expect(livestream?.navigation).toEqual({ icon: null, pages: [] });
+  });
+
+  it("carries a manifest v9 module's own icon and pages beside its descriptor, in declared order", async () => {
+    const { app } = await install({
+      fixtures: [
+        {
+          id: "signage",
+          name: "Signage",
+          navigation: {
+            icon: "monitor-play",
+            pages: [
+              { id: "playback", label: "Playback", path: "playback" },
+              { id: "timelines", label: "Timelines", path: "timelines" },
+              { id: "media", label: "Media", path: "media" },
+            ],
+          },
+        },
+        { id: "calendar", name: "Calendar" },
+      ],
+      principal: signedIn(),
+    });
+
+    const navigation = await navigationOf(app);
+    const signage = navigation.ungrouped.find((entry) => entry.module.id === "signage");
+    const calendar = navigation.ungrouped.find((entry) => entry.module.id === "calendar");
+
+    expect(signage?.navigation).toEqual({
+      icon: "monitor-play",
+      pages: [
+        { id: "playback", label: "Playback", path: "playback" },
+        { id: "timelines", label: "Timelines", path: "timelines" },
+        { id: "media", label: "Media", path: "media" },
+      ],
+    });
+    // The host-neutral descriptor is untouched by navigation: it lives beside it, never inside.
+    expect(Object.keys(signage?.module ?? {}).sort()).toEqual(
+      Object.keys(calendar?.module ?? {}).sort(),
+    );
+    // A manifest v8 module beside it keeps the generic icon and its single root page.
+    expect(calendar?.navigation).toEqual({ icon: null, pages: [] });
+  });
+
+  it("refuses at discovery a v9 module whose navigation is unsafe, so it never reaches the sidebar", async () => {
+    const { app } = await install({
+      fixtures: [
+        { id: "calendar", name: "Calendar" },
+        {
+          id: "escape",
+          name: "Escape",
+          navigation: { pages: [{ id: "out", label: "Out", path: "../settings" }] },
+        },
+      ],
+      principal: signedIn(),
+    }).catch((error: unknown) => ({ app: undefined, error }));
+
+    // Discovery is atomic (ADR 0005): an invalid manifest fails the whole inventory rather than
+    // quietly dropping one module, exactly as for any other manifest error.
+    expect(app).toBeUndefined();
   });
 
   it("agrees exactly with the generic inventory about what is mountable", async () => {