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

surfaces/shell/src/host-protocol.ts

@@ -6,6 +6,11 @@ import {
 } from "@ekklesia/design-tokens";
 import type { ModuleUiPrincipal } from "@ekklesia/module-ui-sdk";
 import { SETTINGS_SECTIONS, type SettingsSection } from "./dashboard-routes.js";
+import {
+  type DashboardModulePage,
+  isDashboardModulePage,
+  isModuleIconName,
+} from "./module-navigation.js";
 
 /**
  * How this shell reaches the Ekklesia API.
@@ -640,6 +645,11 @@ export function moduleDisplayDescriptorPath(moduleId: string): string {
 export interface DashboardNavigationEntry {
   readonly name: string;
   readonly descriptor: HostModuleUiDescriptor;
+  /** The Lucide name the module declared (manifest v9, ADR 0063), or `undefined` for the generic
+   * module icon. */
+  readonly icon: string | undefined;
+  /** Its primary pages, in its declared order; empty for a single-page module. */
+  readonly pages: readonly DashboardModulePage[];
 }
 
 export interface DashboardNavigationGroup {
@@ -662,12 +672,48 @@ export interface DashboardNavigation {
   readonly ungrouped: readonly DashboardNavigationEntry[];
 }
 
-function parseNavigationEntry(entry: unknown): DashboardNavigationEntry {
-  const name = nestedString(entry, "name");
-  if (name === undefined || !isRecord(entry)) {
+/** Strict: the module's declared icon (`null` for none) and pages, each in the manifest's grammar,
+ * with no repeated page id or path. */
+function parseModuleNavigation(value: unknown): {
+  readonly icon: string | undefined;
+  readonly pages: readonly DashboardModulePage[];
+} {
+  if (
+    !hasExactKeys(value, ["icon", "pages"]) ||
+    (value.icon !== null && !isModuleIconName(value.icon)) ||
+    !Array.isArray(value.pages) ||
+    value.pages.length > 12 ||
+    !value.pages.every(isDashboardModulePage)
+  ) {
     throw new HostProtocolError("HOST_RESPONSE_INVALID");
   }
-  return Object.freeze({ descriptor: parseDescriptor(entry.module), name });
+  const pages = value.pages as readonly DashboardModulePage[];
+  if (
+    new Set(pages.map((page) => page.id)).size !== pages.length ||
+    new Set(pages.map((page) => page.path)).size !== pages.length
+  ) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  return Object.freeze({
+    icon: value.icon === null ? undefined : (value.icon as string),
+    pages: Object.freeze(
+      pages.map((page) => Object.freeze({ id: page.id, label: page.label, path: page.path })),
+    ),
+  });
+}
+
+function parseNavigationEntry(entry: unknown): DashboardNavigationEntry {
+  const name = nestedString(entry, "name");
+  if (name === undefined || !hasExactKeys(entry, ["module", "name", "navigation"])) {
+    throw new HostProtocolError("HOST_RESPONSE_INVALID");
+  }
+  const navigation = parseModuleNavigation(entry.navigation);
+  return Object.freeze({
+    descriptor: parseDescriptor(entry.module),
+    icon: navigation.icon,
+    name,
+    pages: navigation.pages,
+  });
 }
 
 /** Strict, total validation, exactly like the inventory parser: a malformed group or entry fails