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

apps/api/src/dashboard-host-routes.ts

@@ -1,13 +1,15 @@
+import { DASHBOARD_PAGE_PREFIXES } from "@ekklesia/shell/dashboard-routes";
 import { Hono } from "hono";
 import { etagMatches } from "./conditional-request.js";
 import { createDashboardHostAssets, type DashboardHostAssets } from "./dashboard-host-assets.js";
 
 /**
- * The Dashboard's two host-owned routes (ADR 0044). Neither can collide with anything else the API
- * serves: `/` is the only page the Dashboard has — it has no client router, and every emailed
- * verification or reset link lands on `/` with a query (ADR 0038) — and the script lives beside, never
+ * The Dashboard's host-owned routes (ADR 0044, ADR 0057). None can collide with anything else the API
+ * serves: the page answers at `/` and inside the Dashboard's reserved namespaces, which the shell
+ * exports so this server and the shell's router read one list, and the script lives beside, never
  * inside, the display host's `/assets/ekklesia-display/` namespace. Module routes all live under
- * `/api/v1/modules/<module-id>`.
+ * `/api/v1/modules/<module-id>`, and every emailed verification or reset link still lands on `/` with
+ * a query (ADR 0038).
  */
 export const DASHBOARD_HOST_PAGE_PATH = "/";
 export const DASHBOARD_HOST_SCRIPT_PATH = "/assets/ekklesia-dashboard/app.js";
@@ -89,25 +91,34 @@ function fixedAsset(
  * Serves the built Dashboard from the same origin as `/api`, so the identity system keeps its
  * default same-origin shape.
  *
- * Two exact literal routes over one frozen snapshot: never a static directory, never a path or file
- * name taken from the request, and never the source map. Any other path — `/index.html`, `/app.js`,
- * the `.map`, a traversal spelling — has no route and falls through to the application's ordinary
- * sanitized `404`. Like the display host's code, these bytes grant no authority: the page renders
- * the sign-in form until `/api/v1/principal` says otherwise.
+ * Fixed routes over one frozen snapshot: never a static directory, never a path or file name taken
+ * from the request, and never the source map. The page answers at `/` and anywhere inside a reserved
+ * Dashboard namespace — `/settings/displays/add` as much as `/settings` — with the **same** bytes and
+ * the same validator, because the path selects a page inside the shell rather than a file here; that
+ * is what lets a refreshed or bookmarked deep link stay where it was. Any other path — `/index.html`,
+ * `/app.js`, the `.map`, a look-alike such as `/settings-old`, a traversal spelling — has no route
+ * and falls through to the application's ordinary sanitized `404`. Like the display host's code,
+ * these bytes grant no authority: the page renders the sign-in form until `/api/v1/principal` says
+ * otherwise.
  */
 export function createDashboardHostRoutes(assets: DashboardHostAssets): Hono {
   const snapshot = snapshotAssets(assets);
   const routes = new Hono();
 
-  routes.get(DASHBOARD_HOST_PAGE_PATH, (c) =>
+  const page = (ifNoneMatch: string | undefined): Response =>
     fixedAsset(
-      c.req.header("if-none-match"),
+      ifNoneMatch,
       snapshot.html,
       snapshot.htmlEtag,
       "text/html; charset=utf-8",
       DASHBOARD_PAGE_SECURITY_HEADERS,
-    ),
-  );
+    );
+
+  routes.get(DASHBOARD_HOST_PAGE_PATH, (c) => page(c.req.header("if-none-match")));
+  for (const prefix of DASHBOARD_PAGE_PREFIXES) {
+    routes.get(prefix, (c) => page(c.req.header("if-none-match")));
+    routes.get(`${prefix}/*`, (c) => page(c.req.header("if-none-match")));
+  }
 
   routes.get(DASHBOARD_HOST_SCRIPT_PATH, (c) =>
     fixedAsset(

apps/api/tests/dashboard-host-routes.test.ts

@@ -34,6 +34,7 @@ import {
   DASHBOARD_HOST_SCRIPT_PATH,
   DashboardHostConfigurationError,
 } from "../src/dashboard-host-routes.js";
+import { DASHBOARD_PAGE_PREFIXES } from "@ekklesia/shell/dashboard-routes";
 import { DISPLAY_HOST_SCRIPT_PATH } from "../src/module-display-routes.js";
 import { createInMemoryDashboardStore } from "./support/in-memory-dashboard-store.js";
 import { emptyModuleConfiguration } from "./support/in-memory-module-configuration.js";
@@ -193,6 +194,78 @@ describe("GET / (the Dashboard page)", () => {
   });
 });
 
+describe("Dashboard deep links (ADR 0057)", () => {
+  const deepLinks = [
+    "/modules",
+    "/modules/",
+    "/modules/signage",
+    "/modules/signage/timelines/a1b2",
+    "/modules/not-installed",
+    "/settings",
+    "/settings/displays/add",
+    "/account",
+    "/account/appearance",
+  ];
+
+  it("reserves exactly the namespaces the shell interprets, from the shell's own list", () => {
+    expect(DASHBOARD_PAGE_PREFIXES).toEqual(["/modules", "/settings", "/account"]);
+  });
+
+  it("serves the identical page, validator, and security headers anywhere inside them, so a refresh stays put", async () => {
+    const { app } = buildApp();
+
+    for (const path of deepLinks) {
+      const response = await app.request(path);
+      expect(response.status, path).toBe(200);
+      expect(await response.text(), path).toBe(PAGE_HTML);
+      expect(response.headers.get("content-type"), path).toBe("text/html; charset=utf-8");
+      expect(response.headers.get("cache-control"), path).toBe("no-cache");
+      expect(response.headers.get("etag"), path).toBe(PAGE_ETAG);
+      expectPageSecurityHeaders(response);
+    }
+    expect(readFileMock).not.toHaveBeenCalled();
+  });
+
+  it("revalidates a deep link with the page's one validator", async () => {
+    const { app } = buildApp();
+
+    const response = await app.request("/settings/displays", {
+      headers: { "If-None-Match": PAGE_ETAG },
+    });
+
+    expect(response.status).toBe(304);
+    expect(await response.text()).toBe("");
+    expectPageSecurityHeaders(response);
+  });
+
+  it("serves the page and never the script, whatever a deep link's last segment looks like", async () => {
+    const { app } = buildApp();
+
+    for (const path of [
+      "/modules/app.js",
+      "/settings/assets/ekklesia-dashboard/app.js",
+      "/account/index.html",
+    ]) {
+      const response = await app.request(path);
+      expect(await response.text(), path).toBe(PAGE_HTML);
+    }
+  });
+
+  it("claims no look-alike prefix and no other method", async () => {
+    const { app } = buildApp();
+
+    for (const path of ["/modulesx", "/settings-old", "/accounts", "/Modules/signage"]) {
+      await expectSanitizedNotFound(await app.request(path), path);
+    }
+    for (const method of ["POST", "PUT", "PATCH", "DELETE"]) {
+      await expectSanitizedNotFound(
+        await app.request("/settings/displays", { method }),
+        `${method} /settings/displays`,
+      );
+    }
+  });
+});
+
 describe("GET /assets/ekklesia-dashboard/app.js (the Dashboard script)", () => {
   it("serves the exact startup script bytes as JavaScript with revalidation and a strong ETag", async () => {
     const { app } = buildApp();