Zayin/Ekklesia
3
0
Fork 0
Code Issues 6 Pull Requests 1 Actions Packages Projects Releases 9 Wiki Activity

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

Browse Source 
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]>
This commit is contained in:
ekklesia
2026-10-15 08:21:50 -05:00
co-authored by Claude Opus 5.5
parent 7447381c8f
commit 4671622b9d
69 changed files with 4221 additions and 372 deletions
Download Patch File Download Diff File Expand all files Collapse all files
surfaces/shell/tests/dashboard-routes.test.ts
+118 -12
View File
@@ -6,6 +6,10 @@ import { describe, expect, it } from "vitest";
import {
ACCOUNT_SECTIONS,
DASHBOARD_PLATFORM_PAGES,
dashboardPathReturningTo,
HOST_NAMESPACES,
parseModuleRoute,
returnTargetFromSearch,
dashboardPath,
parseDashboardPath,
DISCOVER_VIEWS,
@@ -27,13 +31,25 @@ describe("parseDashboardPath", () => {
});
it("names a module page by its id at the top level, tolerating one trailing slash", () => {
expect(parseDashboardPath("/signage")).toEqual({ kind: "module", moduleId: "signage" });
expect(parseDashboardPath("/signage/")).toEqual({ kind: "module", moduleId: "signage" });
expect(parseDashboardPath("/people")).toEqual({ kind: "module", moduleId: "people" });
expect(parseDashboardPath("/signage")).toEqual({
kind: "module",
moduleId: "signage",
path: "",
});
expect(parseDashboardPath("/signage/")).toEqual({
kind: "module",
moduleId: "signage",
path: "",
});
expect(parseDashboardPath("/people")).toEqual({ kind: "module", moduleId: "people", path: "" });
});
it("decodes a percent-encoded segment, so an id is compared as the server spells it", () => {
expect(parseDashboardPath("/sign%61ge")).toEqual({ kind: "module", moduleId: "signage" });
expect(parseDashboardPath("/sign%61ge")).toEqual({
kind: "module",
moduleId: "signage",
path: "",
});
});
it("never reads a platform page as a module page", () => {
@@ -65,7 +81,9 @@ describe("parseDashboardPath", () => {
"/accounts",
]) {
expect(parseDashboardPath(pathname), pathname).toEqual(
pathname === "/accounts" ? { kind: "module", moduleId: "accounts" } : { kind: "not-found" },
pathname === "/accounts"
? { kind: "module", moduleId: "accounts", path: "" }
: { kind: "not-found" },
);
}
});
@@ -76,10 +94,13 @@ describe("parseDashboardPath", () => {
"//",
"//signage",
"/signage//",
// A module's own sub-pages need a contract that does not exist yet (ADR 0057).
"/signage/timelines",
"/signage/timelines/abc",
"/signage/a//b",
"/%E0%A4%A",
// The host's non-Dashboard namespaces are never pages, however deep (ADR 0063).
"/api",
"/api/v1/principal",
"/assets/ekklesia-dashboard/app.js",
"/display/signage",
// Deeper Settings pages are reserved for later (ADR 0061).
"/settings/displays/add",
"/settings/signage/timelines",
@@ -166,27 +187,112 @@ describe("Settings routes (ADR 0061)", () => {
describe("dashboardPath", () => {
it("spells each route canonically, with no implementation prefix", () => {
expect(dashboardPath({ kind: "overview" })).toBe("/");
expect(dashboardPath({ kind: "module", moduleId: "signage" })).toBe("/signage");
expect(dashboardPath({ kind: "module", moduleId: "signage", path: "" })).toBe("/signage");
});
it("encodes a module id so it can never escape its own segment", () => {
expect(dashboardPath({ kind: "module", moduleId: "a/../b" })).toBe("/a%2F..%2Fb");
expect(parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b" }))).toEqual({
expect(dashboardPath({ kind: "module", moduleId: "a/../b", path: "" })).toBe("/a%2F..%2Fb");
expect(
parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b", path: "" })),
).toEqual({
kind: "module",
moduleId: "a/../b",
path: "",
});
});
it("round-trips through the parser", () => {
for (const route of [
{ kind: "overview" } as const,
{ kind: "module", moduleId: "example" } as const,
{ kind: "module", moduleId: "example", path: "" } as const,
{ kind: "module", moduleId: "example", path: "records" } as const,
{ kind: "module", moduleId: "media", path: "sermons/2026-10-11_service~1.mp4" } as const,
]) {
expect(parseDashboardPath(dashboardPath(route))).toEqual(route);
}
});
});
describe("module routes (ADR 0063)", () => {
it("reads everything beneath a module's root as that module's own route", () => {
expect(parseDashboardPath("/signage/timelines")).toEqual({
kind: "module",
moduleId: "signage",
path: "timelines",
});
expect(parseDashboardPath("/signage/timelines/")).toEqual({
kind: "module",
moduleId: "signage",
path: "timelines",
});
expect(parseDashboardPath("/media/sermons/123")).toEqual({
kind: "module",
moduleId: "media",
path: "sermons/123",
});
});
it("spells a module route canonically, its path beneath the encoded module id", () => {
expect(dashboardPath({ kind: "module", moduleId: "signage", path: "timelines" })).toBe(
"/signage/timelines",
);
expect(dashboardPath({ kind: "module", moduleId: "signage", path: "" })).toBe("/signage");
});
it.each([
["", ""],
["/", ""],
["timelines", "timelines"],
["/timelines", "timelines"],
["media/sermons/123", "media/sermons/123"],
["a.b_c~d-e", "a.b_c~d-e"],
])("accepts the module route %j as %j", (input, expected) => {
expect(parseModuleRoute(input)).toBe(expected);
});
it.each([
"../calendar",
"media/../../settings",
"./timelines",
"media/.",
"//evil.example.test",
"https://evil.example.test",
"javascript:alert(1)",
"timelines?x=1",
"timelines#top",
"media%2F..%2Fapi",
"media\\library",
"media//library",
"timelines/",
"time lines",
"a/b/c/d/e/f/g/h/i",
`${"a".repeat(513)}`,
])("refuses the module route %j", (input) => {
expect(parseModuleRoute(input)).toBeUndefined();
});
it("refuses anything that is not a string", () => {
for (const value of [undefined, null, 1, ["timelines"], { path: "timelines" }]) {
expect(parseModuleRoute(value)).toBeUndefined();
}
});
it("names exactly the host's non-Dashboard namespaces", () => {
expect(HOST_NAMESPACES).toEqual(["api", "assets", "display"]);
});
it("carries a return target on its own query parameter, readable only as a raw value", () => {
const href = dashboardPathReturningTo(
{ kind: "module-settings", moduleId: "signage" },
{ kind: "module", moduleId: "signage", path: "timelines" },
);
expect(href).toBe("/settings/signage?return=%2Fsignage%2Ftimelines");
expect(returnTargetFromSearch("?return=%2Fsignage%2Ftimelines")).toBe("/signage/timelines");
expect(returnTargetFromSearch("")).toBeUndefined();
expect(returnTargetFromSearch("?other=1")).toBeUndefined();
});
});
describe("the route locator is published for the API that serves the page", () => {
it("is a narrow package subpath, not the shell root barrel", async () => {
const manifest = JSON.parse(