feat(shell): give every Dashboard page a real URL

The Dashboard had one address. The API served the page only at `/`, both
reference proxies forwarded only `/`, and the open module lived in React
state, so a refresh went back to the first module, nothing could be
bookmarked, and Back left the Dashboard (DESIGN.md §2.7).

ADR 0057 makes the address bar the source of truth:

- `/` is a host-owned Overview, now the landing page; `/modules/<id>`
  mounts that module. An id the server's navigation does not list shows
  "This page isn't available" and loads nothing; any other Dashboard
  address is a host-owned "Page not found".
- `/modules`, `/settings`, and `/account` are reserved whole, from one
  list (`@ekklesia/shell/dashboard-routes`) that the shell's router and
  the API's page routes both read. The API serves the same frozen page,
  ETag, and security headers anywhere inside them; look-alikes and other
  methods stay the sanitized 404.
- A small host-owned history replaces the selected-module state, built in
  the entry point so it stays the only file touching `window`. Navigation
  items are real links; modified clicks are left to the browser. Focus
  moves to the page after an in-place change, and the tab is named after
  the page.
- Sign-in still happens in place with no return value (ADR 0034), so a
  deep link opens its own page after sign-in.
- Both reference Caddyfiles forward the new paths; the deploy smoke now
  reloads a module's address through the real proxy and requires it to
  mount again.

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

surfaces/shell/tests/dashboard-routes.test.ts

@@ -0,0 +1,144 @@
+// @vitest-environment node
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { describe, expect, it } from "vitest";
+import {
+  DASHBOARD_PAGE_PREFIXES,
+  dashboardPath,
+  isDashboardPagePath,
+  parseDashboardPath,
+} from "../src/dashboard-routes.js";
+
+const packageDirectory = path.dirname(path.dirname(fileURLToPath(import.meta.url)));
+
+describe("the Dashboard URL space", () => {
+  it("reserves exactly the platform's page namespaces, frozen", () => {
+    expect(Object.isFrozen(DASHBOARD_PAGE_PREFIXES)).toBe(true);
+    expect(DASHBOARD_PAGE_PREFIXES).toEqual(["/modules", "/settings", "/account"]);
+  });
+
+  it("never reserves a namespace the API, display host, or host assets already own", () => {
+    for (const prefix of DASHBOARD_PAGE_PREFIXES) {
+      for (const owned of ["/api", "/display", "/assets"]) {
+        expect(prefix === owned || prefix.startsWith(`${owned}/`), prefix).toBe(false);
+        expect(owned.startsWith(`${prefix}/`), prefix).toBe(false);
+      }
+    }
+  });
+
+  it("recognizes the root and every path inside a reserved namespace as a Dashboard page", () => {
+    for (const pathname of [
+      "/",
+      "/modules",
+      "/modules/",
+      "/modules/signage",
+      "/modules/signage/timelines/abc",
+      "/settings",
+      "/settings/displays/add",
+      "/account",
+      "/account/appearance",
+    ]) {
+      expect(isDashboardPagePath(pathname), pathname).toBe(true);
+    }
+  });
+
+  it("does not claim anything outside them, including look-alike prefixes", () => {
+    for (const pathname of [
+      "",
+      "/api/v1/principal",
+      "/display/signage",
+      "/assets/ekklesia-dashboard/app.js",
+      "/modulesx",
+      "/settings-old",
+      "/accounts",
+      "/index.html",
+      "/login",
+      "modules/signage",
+    ]) {
+      expect(isDashboardPagePath(pathname), pathname).toBe(false);
+    }
+  });
+});
+
+describe("parseDashboardPath", () => {
+  it("makes the root the Overview", () => {
+    expect(parseDashboardPath("/")).toEqual({ kind: "overview" });
+  });
+
+  it("names a module page by its id, tolerating one trailing slash", () => {
+    expect(parseDashboardPath("/modules/signage")).toEqual({
+      kind: "module",
+      moduleId: "signage",
+    });
+    expect(parseDashboardPath("/modules/signage/")).toEqual({
+      kind: "module",
+      moduleId: "signage",
+    });
+  });
+
+  it("decodes a percent-encoded segment, so an id is compared as the server spells it", () => {
+    expect(parseDashboardPath("/modules/sign%61ge")).toEqual({
+      kind: "module",
+      moduleId: "signage",
+    });
+  });
+
+  it("treats every other shape as not found rather than guessing", () => {
+    for (const pathname of [
+      "",
+      "/modules",
+      "/modules/",
+      "/modules//",
+      "//modules/signage",
+      "/modules/signage//",
+      // A module's own sub-pages need a contract that does not exist yet (ADR 0057).
+      "/modules/signage/timelines",
+      "/modules/%E0%A4%A",
+      "/settings",
+      "/settings/displays",
+      "/account",
+      "/overview",
+      "/index.html",
+    ]) {
+      expect(parseDashboardPath(pathname), pathname).toEqual({ kind: "not-found" });
+    }
+  });
+});
+
+describe("dashboardPath", () => {
+  it("spells each route canonically", () => {
+    expect(dashboardPath({ kind: "overview" })).toBe("/");
+    expect(dashboardPath({ kind: "module", moduleId: "signage" })).toBe("/modules/signage");
+  });
+
+  it("encodes a module id so it can never escape its own segment", () => {
+    expect(dashboardPath({ kind: "module", moduleId: "a/../b" })).toBe("/modules/a%2F..%2Fb");
+    expect(parseDashboardPath(dashboardPath({ kind: "module", moduleId: "a/../b" }))).toEqual({
+      kind: "module",
+      moduleId: "a/../b",
+    });
+  });
+
+  it("round-trips through the parser", () => {
+    for (const route of [
+      { kind: "overview" } as const,
+      { kind: "module", moduleId: "example" } as const,
+    ]) {
+      expect(parseDashboardPath(dashboardPath(route))).toEqual(route);
+      expect(isDashboardPagePath(dashboardPath(route))).toBe(true);
+    }
+  });
+});
+
+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(
+      await readFile(path.join(packageDirectory, "package.json"), "utf8"),
+    ) as { exports?: Record<string, unknown> };
+    expect(manifest.exports?.["./dashboard-routes"]).toEqual({
+      import: "./dist/dashboard-routes.js",
+      types: "./dist/dashboard-routes.d.ts",
+    });
+  });
+});