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/src/dashboard-routes.ts

@@ -21,7 +21,11 @@ import {
   requireTrustedOrigin,
 } from "./authorization-middleware.js";
 import { CORE_MUTATION_MAX_BODY_BYTES, platformBodyLimit } from "./body-limits.js";
-import { describeMountableModules, type HostModuleUiDescriptor } from "./module-ui-inventory.js";
+import {
+  describeMountableModules,
+  type HostModuleUiDescriptor,
+  type MountableModuleDescription,
+} from "./module-ui-inventory.js";
 
 export const DASHBOARD_NAVIGATION_PATH = "/api/v1/dashboard/navigation";
 const DASHBOARD_GROUPS_PATH = `${DASHBOARD_NAVIGATION_PATH}/groups`;
@@ -41,6 +45,20 @@ const DASHBOARD_PLACEMENTS_PATH = `${DASHBOARD_NAVIGATION_PATH}/placements`;
 export interface DashboardNavigationModuleView {
   readonly name: string;
   readonly module: HostModuleUiDescriptor;
+  /**
+   * What the module declares about its own pages (manifest v9, ADR 0063): the Lucide icon the
+   * Dashboard draws it with (`null` for the generic one) and its primary pages, in declared order —
+   * empty for a single-page module, which every manifest v8 module is. The module's identity, never
+   * its placement: where it sits in the sidebar stays the administrator's (ADR 0027).
+   */
+  readonly navigation: {
+    readonly icon: string | null;
+    readonly pages: readonly {
+      readonly id: string;
+      readonly label: string;
+      readonly path: string;
+    }[];
+  };
 }
 
 export interface DashboardNavigationGroupView {
@@ -203,10 +221,18 @@ export function createDashboardRoutes(options: CreateDashboardRoutesOptions): Ho
         configuration,
         descriptors.map((entry) => ({ id: entry.descriptor.id, ...entry })),
       );
-      const present = (entry: {
-        readonly descriptor: HostModuleUiDescriptor;
-        readonly name: string;
-      }): DashboardNavigationModuleView => ({ module: entry.descriptor, name: entry.name });
+      const present = (entry: MountableModuleDescription): DashboardNavigationModuleView => ({
+        module: entry.descriptor,
+        name: entry.name,
+        navigation: {
+          icon: entry.navigation.icon ?? null,
+          pages: entry.navigation.pages.map((page) => ({
+            id: page.id,
+            label: page.label,
+            path: page.path,
+          })),
+        },
+      });
       return c.json(
         {
           groups: view.groups.map((group) => ({