Make the module navigation capability an optional context member

ModuleUiHostContext.navigation is now `navigation?: ModuleUiNavigation | undefined`, so the public context change is source-compatible: a context built before navigation existed (without the member) still compiles unchanged, as 0.x patch releases require. The Dashboard supplies navigation; hosts without addressable pages, including the display host, omit the member; modules feature-detect it. Existing hosts' tests are restored to their pre-PR shape, and a module-ui-sdk test proves a pre-navigation context still satisfies ModuleUiHostContext (and fails if the member is ever made required). Runtime behaviour, manifest v8/v9 compatibility, and security rules are unchanged. ADR 0063 and the module development guide say so. Co-Authored-By: Claude Opus 5.5 <[email protected]>
2026-10-15 09:13:03 -05:00
parent ae360ef318
commit c78f1318b4
13 changed files with 60 additions and 37 deletions
@@ -176,8 +176,14 @@ The shell parses both strictly.
 ### The module's navigation capability

 `ModuleUiHostContext.navigation` (`@ekklesia/module-ui-sdk`) is a narrow host capability, not a
-router. It is `undefined` where a host has no addressable pages: the display host, and a standalone
-host without routes.
+router, and an **optional** member (`navigation?: ModuleUiNavigation`). A host with addressable
+module pages (Ekklesia's Dashboard) supplies it. A host without them (the display host, and a
+standalone host without routes) omits it, and may also set it to `undefined`.
+
+The member is optional so that adding it breaks no one. Ekklesia's 0.x versioning makes patch
+releases compatible, and a context built before navigation existed must stay a complete, valid
+context that compiles unchanged. A `@ekklesia/module-ui-sdk` test holds exactly that, and fails if
+the member is ever made required.

 ```ts
 interface ModuleUiNavigation {
@@ -208,7 +214,7 @@ interface ModuleUiNavigation {
  rebuilt against the new SDK can already link to its Settings page.

 Adding a context member changes nothing about how an artifact is mounted, so the mount ABI stays at
-version 2. A module that uses `navigation` checks for it, exactly as it checks `display`.
+version 2. A module that uses `navigation` feature-detects it (`context.navigation?.navigate(…)`).

 ### Return-to-origin: one carrier, the `return` query parameter

@@ -262,8 +268,8 @@ parameter from it.
 - **Packages.** `@ekklesia/contracts` gains `module-navigation.ts`, the v8/v9 manifest union, and
  `moduleManifestNavigation`. `@ekklesia/module-ui-sdk` gains `navigation.ts` and
  `ModuleUiHostContext.navigation`. `@ekklesia/module-sdk` re-exports the navigation helpers and
-  types. All changes are additive for module code. A host that builds a context itself must now say
-  `navigation: undefined`.
+  types. Every change is additive at the source level as well as at run time: existing module code,
+  and an existing host that builds a context itself, compile and run unchanged.
 - **Core** publishes each module's navigation beside its name. The navigation response gains a
  `navigation` member per module.
 - **The shell** reads module routes at any depth, draws icons and pages, and supplies the
@@ -720,7 +720,8 @@ artifact is the role selection.

 ### What the host gives you

-`mount` receives exactly eight members, and nothing else is available:
+`mount` receives these members, and nothing else is available. `navigation` is optional: a host that
+has no addressable pages leaves it out, so feature-detect it.

 | Member | What it is |
 | --- | --- |
@@ -731,7 +732,7 @@ artifact is the role selection.
 | `realtime` | `subscribe(channel, handlers)` against **your own** module's live state — see [Realtime state](#realtime-state) |
 | `contributions` | Renderers other modules contributed to capabilities **you** provide — see [Browser contributions](#browser-contributions) |
 | `display` | Your display page's URL, or `undefined` when you publish none |
-| `navigation` | Where your module is, and how it moves between its own pages and to its Settings page — see [Module navigation](#module-navigation). `undefined` on the display host |
+| `navigation` | Where your module is, and how it moves between its own pages and to its Settings page — see [Module navigation](#module-navigation). Optional: absent on the display host |

 Module configuration, organization context, and diagnostics reporting are **not** in the contract.
 They need designs that do not exist, and a speculative field frozen into a public contract is harder
@@ -795,7 +796,7 @@ A refresh, a bookmark, and Back and Forward all land on the same route.
 never build a Dashboard URL yourself:

 ```tsx
-const { navigation } = context;            // undefined on the display host
+const { navigation } = context;            // optional: absent on the display host
 navigation?.location();                    // { path: "media/sermons/123", page: "media" }
 navigation?.subscribe(() => rerender());   // every move: yours, the sidebar's, Back and Forward
 navigation?.navigate("timelines");         // or { replace: true } to respell the current entry