feat: add Dashboard navigation as presentation configuration

Phase 6D pass 1. The shell's navigation was a flat list of module ids, which
is not a usable experience — and the obvious fix carries an obvious trap.
Letting a module declare its folder, or modelling "Media" as something
Livestream and Video belong to, turns a rendering preference into
architecture: a folder becomes an owner, membership starts to look like a
dependency, and the flat module graph acquires a hierarchy nobody decided on.

So the rule comes first: a Dashboard group is a label on a rendering bucket.
No manifest, no version, no artifact, no API, no lifecycle; nothing depends on
it. Livestream depends on Video because it calls Video's functionality, and
that orders startup. Livestream is shown under Media, and that orders nothing.
No parent module, child module, owning module, or group-derived dependency
appears anywhere in the contracts.

No manifest change and no version 5. `manifest.name` has been required since
version 1 and already is the module's product identity, so the shell renders
"Livestream" instead of `livestream` with nothing added. `suggestedGroup` is
deliberately deferred rather than shipped: it would force a hard
manifest-version cutover for a hint, and its only correct semantics needs
initialization logic that risks a suggestion overwriting an administrator's
decision. Defaulting and ownership are different things.

Two Core tables (migration 0003) hold groups and placements — server-side,
because a church configures its Dashboard rather than one browser;
platform-global, because no organization model exists to scope them to.
`group_id` is `on delete set null`, so deleting a group ungroups its modules
and a dangling reference is impossible. `module_id` carries no foreign key,
because modules are packages rather than rows, so a placement for an
uninstalled module is retained and restores its position on reinstall.

`resolveDashboardNavigation` is a pure function of configuration plus the
mountable set: an unplaced module is ungrouped and visible with no
initialization write, an absent module renders nothing, empty groups are kept,
and ordering is total with the module id as final tie-break.

`GET /api/v1/dashboard/navigation` returns the resolved view, layered on top of
the host-neutral module UI inventory rather than merged into it — each generic
descriptor is embedded untouched, so a standalone host never inherits Dashboard
semantics. Reading needs the permission the inventory already needs; organizing
needs the new platform permission `core.dashboard.navigation.manage` through a
narrow, idempotent, closed-validation mutation contract. No editor UI.

The flatness rule is executable: a test discovers real fixtures with a genuine
dependency, arranges them four ways including both in one folder and the
dependency inverted in presentation, and asserts discovery order, dependency
declarations, and the module set stay byte-identical. The end-to-end test
organizes a real installation through the real API, mounts a module from inside
a group, moves it, and asserts the navigation entry is byte-identical across the
move and still mounts the same artifact.

The shell's client for the generic inventory became dead code and was removed
rather than kept speculatively; the endpoint itself is unchanged.

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

surfaces/shell/tests/host-app.test.tsx

@@ -34,25 +34,36 @@ afterEach(async () => {
   consoleError.mockRestore();
 });
 
-function descriptor(id: string, version = "0.1.0", permissions: readonly string[] = []) {
+/** One navigation entry, in the wire shape the Dashboard navigation endpoint produces: the module's
+ * display name beside the untouched mount descriptor. */
+function entry(id: string, name: string, version = "0.1.0", permissions: readonly string[] = []) {
   return {
-    api: { baseUrl: `/api/v1/modules/${id}` },
-    id,
-    permissions,
-    ui: { url: `/api/v1/module-ui/${id}/${version}` },
-    version,
+    module: {
+      api: { baseUrl: `/api/v1/modules/${id}` },
+      id,
+      permissions,
+      ui: { url: `/api/v1/module-ui/${id}/${version}` },
+      version,
+    },
+    name,
   };
 }
 
+function group(id: string, label: string, modules: ReturnType<typeof entry>[], order = 10) {
+  return { id, label, modules, order };
+}
+
 interface PlatformStub {
-  readonly modules?: ReadonlyArray<ReturnType<typeof descriptor>>;
+  readonly groups?: ReadonlyArray<ReturnType<typeof group>>;
+  readonly ungrouped?: ReadonlyArray<ReturnType<typeof entry>>;
   readonly principal?: unknown;
-  readonly inventoryStatus?: number;
-  readonly inventoryThrows?: boolean;
+  readonly navigationStatus?: number;
+  readonly navigationThrows?: boolean;
 }
 
 function platformFetch(stub: PlatformStub = {}): typeof fetch {
-  const modules = stub.modules ?? [descriptor("example")];
+  const groups = stub.groups ?? [];
+  const ungrouped = stub.ungrouped ?? (stub.groups ? [] : [entry("example", "Example Module")]);
   return vi.fn(async (input: RequestInfo | URL) => {
     const url = String(input);
     if (url.endsWith("/api/v1/principal")) {
@@ -61,13 +72,13 @@ function platformFetch(stub: PlatformStub = {}): typeof fetch {
         { headers: { "content-type": "application/json" }, status: 200 },
       );
     }
-    if (url.endsWith("/api/v1/module-ui")) {
-      if (stub.inventoryThrows) {
+    if (url.endsWith("/api/v1/dashboard/navigation")) {
+      if (stub.navigationThrows) {
         throw new TypeError("network down");
       }
-      return new Response(JSON.stringify({ modules }), {
+      return new Response(JSON.stringify({ groups, ungrouped }), {
         headers: { "content-type": "application/json" },
-        status: stub.inventoryStatus ?? 200,
+        status: stub.navigationStatus ?? 200,
       });
     }
     return new Response("{}", { status: 404 });
@@ -123,10 +134,12 @@ function query(testId: string): Element | null {
 }
 
 describe("Ekklesia shell — bootstrap", () => {
-  it("renders the module list the inventory returned", async () => {
+  it("renders the module list the navigation returned", async () => {
     await render({
       apiBaseUrl,
-      fetch: platformFetch({ modules: [descriptor("example"), descriptor("calendar", "2.0.0")] }),
+      fetch: platformFetch({
+        ungrouped: [entry("example", "Example Module"), entry("calendar", "Calendar", "2.0.0")],
+      }),
     });
 
     expect(query("select-example")).not.toBeNull();
@@ -140,26 +153,174 @@ describe("Ekklesia shell — bootstrap", () => {
     expect(query("module-container")).toBeNull();
   });
 
-  it("treats a refused inventory as signed out rather than as a crash", async () => {
-    await render({ apiBaseUrl, fetch: platformFetch({ inventoryStatus: 403 }) });
+  it("treats refused navigation as signed out rather than as a crash", async () => {
+    await render({ apiBaseUrl, fetch: platformFetch({ navigationStatus: 403 }) });
 
     expect(query("host-signed-out")).not.toBeNull();
   });
 
   it("renders a host-owned error when the platform cannot be reached", async () => {
-    await render({ apiBaseUrl, fetch: platformFetch({ inventoryThrows: true }) });
+    await render({ apiBaseUrl, fetch: platformFetch({ navigationThrows: true }) });
 
     expect(query("host-error")).not.toBeNull();
     expect(text()).not.toContain("network down");
   });
 
   it("says so plainly when no installed module provides a UI", async () => {
-    await render({ apiBaseUrl, fetch: platformFetch({ modules: [] }) });
+    await render({ apiBaseUrl, fetch: platformFetch({ groups: [], ungrouped: [] }) });
 
     expect(query("host-empty")).not.toBeNull();
   });
 });
 
+describe("Ekklesia shell — Dashboard navigation", () => {
+  const mediaGroup = () =>
+    group("media", "Media", [entry("video", "Video"), entry("livestream", "Livestream", "2.0.0")]);
+  const planningGroup = () => group("planning", "Planning", [entry("calendar", "Calendar")], 20);
+
+  it("renders groups with their labels and the modules' display names", async () => {
+    await render({
+      apiBaseUrl,
+      fetch: platformFetch({ groups: [mediaGroup(), planningGroup()] }),
+    });
+
+    expect(query("group-media")?.textContent).toBe("MediaVideoLivestream");
+    expect(query("group-planning")?.textContent).toBe("PlanningCalendar");
+    // The module id is never shown; the manifest name is.
+    expect(text()).not.toContain("livestream");
+  });
+
+  it("renders groups and modules in exactly the server's order", async () => {
+    // The shell sorts nothing: whatever order arrives is the order shown, so the server stays the
+    // single authority on arrangement.
+    await render({
+      apiBaseUrl,
+      fetch: platformFetch({
+        groups: [
+          group("planning", "Planning", [entry("calendar", "Calendar")]),
+          group("media", "Media", [
+            entry("livestream", "Livestream", "2.0.0"),
+            entry("video", "Video"),
+          ]),
+        ],
+      }),
+    });
+
+    const labels = [...container.querySelectorAll("h2")].map((heading) => heading.textContent);
+    expect(labels).toEqual(["Planning", "Media"]);
+    const buttons = [...container.querySelectorAll("button")].map((button) => button.textContent);
+    expect(buttons).toEqual(["Calendar", "Livestream", "Video"]);
+  });
+
+  it("renders ungrouped modules alongside groups, under a heading", async () => {
+    await render({
+      apiBaseUrl,
+      fetch: platformFetch({
+        groups: [mediaGroup()],
+        ungrouped: [entry("roster", "Roster")],
+      }),
+    });
+
+    expect(query("group-ungrouped")?.textContent).toBe("OtherRoster");
+  });
+
+  it("omits the heading when nothing is grouped, so an unconfigured install reads as a list", async () => {
+    await render({
+      apiBaseUrl,
+      fetch: platformFetch({ ungrouped: [entry("roster", "Roster"), entry("video", "Video")] }),
+    });
+
+    expect(query("group-ungrouped")?.textContent).toBe("RosterVideo");
+    expect(container.querySelectorAll("h2")).toHaveLength(0);
+  });
+
+  it("keeps an empty group visible", async () => {
+    await render({
+      apiBaseUrl,
+      fetch: platformFetch({
+        groups: [group("media", "Media", [])],
+        ungrouped: [entry("video", "Video")],
+      }),
+    });
+
+    // The administrator created it; hiding it would look like it had been deleted.
+    expect(query("group-media")?.textContent).toBe("Media");
+  });
+
+  it("selects the first module in the arranged order and marks it active", async () => {
+    await render(
+      { apiBaseUrl, fetch: platformFetch({ groups: [mediaGroup(), planningGroup()] }) },
+      async (url) => artifact(url.includes("/video/") ? "video" : "other", "0.1.0"),
+    );
+
+    expect(query("select-video")?.getAttribute("aria-current")).toBe("page");
+    expect(query("select-livestream")?.getAttribute("aria-current")).toBeNull();
+  });
+
+  it("mounts a module selected from inside a group, using the descriptor the group carried", async () => {
+    const requested: string[] = [];
+    await render(
+      { apiBaseUrl, fetch: platformFetch({ groups: [mediaGroup(), planningGroup()] }) },
+      async (url) => {
+        requested.push(url);
+        return artifact(url.includes("/calendar/") ? "calendar" : "video", "0.1.0");
+      },
+    );
+
+    await act(async () => {
+      (query("select-calendar") as HTMLButtonElement).click();
+    });
+
+    // The nested descriptor is used unchanged: grouping altered nothing about the artifact URL.
+    expect(requested).toEqual([
+      `${apiBaseUrl}/api/v1/module-ui/video/0.1.0`,
+      `${apiBaseUrl}/api/v1/module-ui/calendar/0.1.0`,
+    ]);
+    expect(query("module-container")?.textContent).toBe("calendar mounted");
+  });
+
+  it("mounts the identical artifact whichever group a module is presented in", async () => {
+    const requestedWhenGrouped: string[] = [];
+    await render(
+      {
+        apiBaseUrl,
+        fetch: platformFetch({
+          groups: [group("media", "Media", [entry("livestream", "Livestream")])],
+        }),
+      },
+      async (url) => {
+        requestedWhenGrouped.push(url);
+        return artifact("livestream", "0.1.0");
+      },
+    );
+    await act(async () => {
+      root.unmount();
+    });
+
+    // The same module, presented somewhere else entirely.
+    root = createRoot(container);
+    const requestedWhenMoved: string[] = [];
+    await render(
+      {
+        apiBaseUrl,
+        fetch: platformFetch({
+          groups: [
+            group("sunday-production", "Sunday Production", [entry("livestream", "Livestream")], 5),
+          ],
+        }),
+      },
+      async (url) => {
+        requestedWhenMoved.push(url);
+        return artifact("livestream", "0.1.0");
+      },
+    );
+
+    // Presentation changed; the module did not.
+    expect(requestedWhenMoved).toEqual(requestedWhenGrouped);
+    expect(query("group-sunday-production")?.textContent).toBe("Sunday ProductionLivestream");
+  });
+});
+
 describe("Ekklesia shell — mount lifecycle", () => {
   it("mounts the first module into the host's own container", async () => {
     const mountedInto: Element[] = [];
@@ -175,7 +336,7 @@ describe("Ekklesia shell — mount lifecycle", () => {
     expect(mountedInto[0]).not.toBe(document.body);
   });
 
-  it("imports exactly the URL the inventory published, resolved against the API origin", async () => {
+  it("imports exactly the URL the navigation published, resolved against the API origin", async () => {
     const requested: string[] = [];
     await render({ apiBaseUrl, fetch: platformFetch() }, async (url) => {
       requested.push(url);
@@ -229,7 +390,9 @@ describe("Ekklesia shell — mount lifecycle", () => {
     await render(
       {
         apiBaseUrl,
-        fetch: platformFetch({ modules: [descriptor("example"), descriptor("calendar", "2.0.0")] }),
+        fetch: platformFetch({
+          ungrouped: [entry("example", "Example Module"), entry("calendar", "Calendar", "2.0.0")],
+        }),
       },
       importModule,
     );
@@ -275,7 +438,9 @@ describe("Ekklesia shell — mount lifecycle", () => {
     await render(
       {
         apiBaseUrl,
-        fetch: platformFetch({ modules: [descriptor("example"), descriptor("calendar", "2.0.0")] }),
+        fetch: platformFetch({
+          ungrouped: [entry("example", "Example Module"), entry("calendar", "Calendar", "2.0.0")],
+        }),
       },
       importModule,
     );
@@ -352,7 +517,9 @@ describe("Ekklesia shell — failure is host-owned", () => {
     await render(
       {
         apiBaseUrl,
-        fetch: platformFetch({ modules: [descriptor("example"), descriptor("calendar", "2.0.0")] }),
+        fetch: platformFetch({
+          ungrouped: [entry("example", "Example Module"), entry("calendar", "Calendar", "2.0.0")],
+        }),
       },
       importModule,
     );
@@ -389,7 +556,9 @@ describe("Ekklesia shell — failure is host-owned", () => {
     await render(
       {
         apiBaseUrl,
-        fetch: platformFetch({ modules: [descriptor("example"), descriptor("calendar", "2.0.0")] }),
+        fetch: platformFetch({
+          ungrouped: [entry("example", "Example Module"), entry("calendar", "Calendar", "2.0.0")],
+        }),
       },
       importModule,
     );