Pair displays at the platform's own /display/setup, with or without modules

Displays are platform-owned, but a screen could only start pairing on a
module's display page: every pairing request named a module, so an
installation with no module that uses displays could not set one up.

- /display/setup is the platform's own display page, served whenever
  the deployment has device support, whatever is installed. It pairs a
  platform display with no module. Once paired, it opens the module it
  is set to show; with none set, it shows its name and waits, rechecking
  so it stays alive and notices revocation. "setup" is now a reserved
  module id.
- Migration core:0009_platform_display_pairing lets a pairing request
  name no module. It relaxes module_id and permission_id and adds a
  both-or-neither check. It is additive and destroys nothing.
- POST /api/v1/device-pairing/requests accepts {} for a platform
  display. Approval accepts an optional moduleId, so the administrator
  can choose an installed display module and the device gets that
  module's declared permission. A module display's own request can't be
  redirected.
- GET /api/v1/device-pairing/self lets a paired device describe itself:
  its name and the module displays it may show. It renews the device's
  cookie.
- GET /api/v1/devices/setup is replaced by
  GET /api/v1/devices/display-modules: the modules a display can be set
  to show.
- Settings -> Displays always offers the /display/setup address, Copy
  setup link and Add display. Add display has an optional "Show on this
  screen" choice, and each paired display says what it shows.
- /display/<module-id> is unchanged, so released Signage 0.1.5 works as
  before.

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

surfaces/shell/tests/displays-settings.test.tsx

@@ -41,10 +41,16 @@ function json(body: unknown, status = 200): Response {
 interface ServerOptions {
   readonly devices?: unknown[];
   readonly denied?: boolean;
-  /** What `GET /api/v1/devices/setup` answers: the display pages, or a failure. */
-  readonly setup?: unknown[] | "fails";
+  /** What `GET /api/v1/devices/display-modules` answers: the installed display modules (by
+   * default Signage), none, or a failure. */
+  readonly modules?: unknown[] | "fails";
 }
 
+/** A screen that asked from Signage's own display page. */
+const MODULE_CODE = "123456";
+/** A screen that asked from the platform's `/display/setup`, with no module (ADR 0065). */
+const PLATFORM_CODE = "654321";
+
 function server(options: ServerOptions = {}) {
   let devices: unknown[] = options.devices ?? [
     {
@@ -61,13 +67,13 @@ function server(options: ServerOptions = {}) {
     const path = new URL(String(input)).pathname;
     const body = init?.body === undefined ? undefined : JSON.parse(String(init.body));
     requests.push({ body, path });
-    if (path === "/api/v1/devices/setup") {
-      if (options.setup === "fails") {
+    if (path === "/api/v1/devices/display-modules") {
+      if (options.modules === "fails") {
         return json({ code: "DEVICE_LOOKUP_UNAVAILABLE" }, 503);
       }
       return json({
-        displays: options.setup ?? [
-          { moduleId: "signage", name: "Signage", url: "/display/signage" },
+        modules: options.modules ?? [
+          { moduleId: "signage", name: "Signage", permissionId: "signage.display" },
         ],
       });
     }
@@ -79,27 +85,35 @@ function server(options: ServerOptions = {}) {
       return new Response(null, { status: 204 });
     }
     if (path === "/api/v1/device-pairing/lookups") {
-      return (body as { code: string }).code === "123456"
-        ? json({
-            expiresAt: "2026-10-15T12:10:00.000Z",
-            moduleId: "signage",
-            permissionId: "signage.display",
-            requestedAt: "2026-10-15T11:59:00.000Z",
-          })
-        : json({ code: "DEVICE_PAIRING_NOT_FOUND" }, 404);
+      const code = (body as { code: string }).code;
+      if (code !== MODULE_CODE && code !== PLATFORM_CODE) {
+        return json({ code: "DEVICE_PAIRING_NOT_FOUND" }, 404);
+      }
+      const module = code === MODULE_CODE;
+      return json({
+        expiresAt: "2026-10-15T12:10:00.000Z",
+        moduleId: module ? "signage" : null,
+        permissionId: module ? "signage.display" : null,
+        requestedAt: "2026-10-15T11:59:00.000Z",
+      });
     }
     if (path === "/api/v1/device-pairing/approvals") {
+      const approval = body as { code: string; deviceName: string; moduleId?: string };
+      const shows = approval.code === MODULE_CODE ? "signage" : approval.moduleId;
       devices = [
         ...devices,
         {
           createdAt: "2026-10-15T12:00:00.000Z",
           id: "device-2",
-          name: (body as { deviceName: string }).deviceName,
-          permissions: [],
+          name: approval.deviceName,
+          permissions: shows === "signage" ? ["signage.display"] : [],
           revoked: false,
         },
       ];
-      return json({ moduleId: "signage", permissionId: "signage.display" });
+      return json({
+        moduleId: shows ?? null,
+        permissionId: shows === undefined ? null : `${shows}.display`,
+      });
     }
     return json({ code: "NOT_FOUND" }, 404);
   }) as unknown as typeof globalThis.fetch;
@@ -140,6 +154,15 @@ async function type(testId: string, value: string): Promise<void> {
   });
 }
 
+async function choose(testId: string, value: string): Promise<void> {
+  const select = required(testId) as HTMLSelectElement;
+  await act(async () => {
+    const setter = Object.getOwnPropertyDescriptor(HTMLSelectElement.prototype, "value")?.set;
+    setter?.call(select, value);
+    select.dispatchEvent(new Event("change", { bubbles: true }));
+  });
+}
+
 async function submit(testId: string): Promise<void> {
   const form = (required(testId) as HTMLButtonElement).form;
   await act(async () => {
@@ -173,12 +196,13 @@ describe("Settings → Displays", () => {
     expect(card.textContent).toContain("Foyer TV");
     expect(card.textContent).toContain("Paired");
     expect(card.textContent).toContain("Last seen within the last hour");
+    expect(card.textContent).toContain("Not showing a module yet");
     expect(container.querySelector("h1")?.textContent).toBe("Displays");
-    // How to set up a new screen comes first, in one place: the platform display page on the API
-    // origin, then Add display right under it, with the step-by-step version folded away.
+    // How to set up a new screen comes first, in one place: the platform's own setup page on the
+    // API origin, then Add display right under it, with the step-by-step version folded away.
     const setup = required("display-setup");
     expect(setup.textContent).toContain("Open this address on the new screen");
-    expect(required("display-setup-url").textContent).toBe(`${apiBaseUrl}/display/signage`);
+    expect(required("display-setup-url").textContent).toBe(`${apiBaseUrl}/display/setup`);
     expect(setup.contains(required("add-display"))).toBe(true);
     const steps = required("display-setup-steps");
     expect(steps.tagName).toBe("DETAILS");
@@ -216,9 +240,11 @@ describe("Settings → Displays", () => {
     await submit("device-pairing-lookup");
     expect(required("device-pairing-error").textContent).toContain("not waiting for approval");
 
-    await type("device-pairing-code-input", "123456");
+    await type("device-pairing-code-input", MODULE_CODE);
     await submit("device-pairing-lookup");
+    // A screen that asked from a module's own display already shows that module: no choice.
     expect(required("device-pairing-found").textContent).toContain("Signage");
+    expect(query("device-pairing-shows")).toBeNull();
     expect(document.activeElement).toBe(required("device-pairing-name"));
 
     await type("device-pairing-name", "Sanctuary left");
@@ -227,10 +253,13 @@ describe("Settings → Displays", () => {
     expect(query("add-display-dialog")).toBeNull();
     expect(
       platform.requests.find((r) => r.path === "/api/v1/device-pairing/approvals")?.body,
-    ).toEqual({ code: "123456", deviceName: "Sanctuary left" });
+    ).toEqual({ code: MODULE_CODE, deviceName: "Sanctuary left" });
     // The new display appears without a page refresh, and the page says so.
     expect(required("device-device-2").textContent).toContain("Sanctuary left");
-    expect(required("device-pairing-success").textContent).toContain("Sanctuary left is paired");
+    expect(required("device-pairing-success").textContent).toContain(
+      "Sanctuary left is paired and shows Signage.",
+    );
+    expect(required("device-device-2").textContent).toContain("Shows Signage");
     // Focus is back on the control that opened the flow.
     expect(document.activeElement).toBe(required("add-display"));
   });
@@ -243,67 +272,99 @@ describe("Settings → Displays", () => {
     expect(query("add-display-dialog")).toBeNull();
     expect(platform.requests.map((r) => r.path).sort()).toEqual([
       "/api/v1/devices",
-      "/api/v1/devices/setup",
+      "/api/v1/devices/display-modules",
     ]);
     expect(document.activeElement).toBe(required("add-display"));
   });
 });
 
 describe("setting up a new screen (ADR 0065)", () => {
-  it("copies the setup address, and says so when the browser cannot", async () => {
+  it("copies the platform setup address, and says so when the browser cannot", async () => {
     const writeText = vi.fn(async () => undefined);
     Object.defineProperty(window.navigator, "clipboard", {
       configurable: true,
       value: { writeText },
     });
     await renderPage();
-    await click("display-setup-copy-signage");
-    expect(writeText).toHaveBeenCalledWith(`${apiBaseUrl}/display/signage`);
+    await click("display-setup-copy");
+    expect(writeText).toHaveBeenCalledWith(`${apiBaseUrl}/display/setup`);
     expect(required("display-setup").textContent).toContain("Link copied.");
 
     Object.defineProperty(window.navigator, "clipboard", { configurable: true, value: undefined });
-    await click("display-setup-copy-signage");
+    await click("display-setup-copy");
     expect(required("display-setup").textContent).toContain("couldn't copy it");
   });
 
-  it("names each module's page when more than one module uses displays", async () => {
-    await renderPage({
-      setup: [
-        { moduleId: "signage", name: "Signage", url: "/display/signage" },
-        { moduleId: "parent-call", name: "Parent Call", url: "/display/parent-call" },
-      ],
-    });
-    expect(required("display-setup-signage").textContent).toContain("For Signage");
-    expect(required("display-setup-parent-call").textContent).toContain(
-      `For Parent Call${apiBaseUrl}/display/parent-call`,
-    );
-  });
+  it("offers the same setup and Add display with zero display modules installed", async () => {
+    const platform = await renderPage({ modules: [] });
 
-  it("makes sense with no module that uses displays installed, Signage included", async () => {
-    await renderPage({ setup: [] });
-    expect(required("display-setup-none").textContent).toContain(
+    // The generic platform address, and nothing that names a module.
+    expect(required("display-setup-url").textContent).toBe(`${apiBaseUrl}/display/setup`);
+    expect(required("display-setup").textContent).not.toContain("Signage");
+    expect(query("add-display")).not.toBeNull();
+
+    // A screen from /display/setup pairs as a platform display with no module.
+    await click("add-display");
+    await type("device-pairing-code-input", PLATFORM_CODE);
+    await submit("device-pairing-lookup");
+    expect(required("device-pairing-found").textContent).toContain(
+      "A new screen is waiting to be paired",
+    );
+    expect(query("device-pairing-shows")).toBeNull();
+    expect(required("device-pairing-no-modules").textContent).toContain(
       "No installed module shows content on screens yet",
     );
-    expect(query("display-setup-url")).toBeNull();
-    // No Add display that could only fail, and nothing names Signage.
-    expect(query("add-display")).toBeNull();
-    expect(required("display-setup").textContent).not.toContain("Signage");
+    await type("device-pairing-name", "Foyer TV 2");
+    await submit("device-pairing-approve");
+
+    expect(
+      platform.requests.find((r) => r.path === "/api/v1/device-pairing/approvals")?.body,
+    ).toEqual({ code: PLATFORM_CODE, deviceName: "Foyer TV 2" });
+    expect(required("device-pairing-success").textContent).toContain(
+      "Foyer TV 2 is paired. It shows its name until a module is set to show on it.",
+    );
+    expect(required("device-device-2").textContent).toContain("Not showing a module yet");
   });
 
-  it("keeps the rest of the page working when the setup address cannot be read", async () => {
-    await renderPage({ setup: "fails" });
-    expect(required("display-setup-failed").textContent).toContain("couldn't be loaded");
-    expect(required("device-device-1").textContent).toContain("Foyer TV");
+  it("lets the administrator choose which installed module a new platform display shows", async () => {
+    const platform = await renderPage();
     await click("add-display");
-    expect(query("add-display-dialog")).not.toBeNull();
+    await type("device-pairing-code-input", PLATFORM_CODE);
+    await submit("device-pairing-lookup");
+
+    const shows = required("device-pairing-shows") as HTMLSelectElement;
+    expect([...shows.options].map((option) => option.textContent)).toEqual([
+      "Nothing yet",
+      "Signage",
+    ]);
+    expect(shows.value).toBe("");
+    await choose("device-pairing-shows", "signage");
+    await type("device-pairing-name", "Lobby screen");
+    await submit("device-pairing-approve");
+
+    expect(
+      platform.requests.find((r) => r.path === "/api/v1/device-pairing/approvals")?.body,
+    ).toEqual({ code: PLATFORM_CODE, deviceName: "Lobby screen", moduleId: "signage" });
+    expect(required("device-pairing-success").textContent).toContain(
+      "Lobby screen is paired and shows Signage.",
+    );
+    expect(required("device-device-2").textContent).toContain("Shows Signage");
   });
 
-  it("refuses a setup answer that is not a plain root-relative page", async () => {
-    await renderPage({
-      setup: [{ moduleId: "signage", name: "Signage", url: "https://elsewhere.example/display" }],
-    });
-    expect(query("display-setup-failed")).not.toBeNull();
-    expect(query("display-setup-url")).toBeNull();
+  it("still pairs, showing nothing yet, when the display modules cannot be read", async () => {
+    const platform = await renderPage({ modules: "fails" });
+    expect(required("display-setup-url").textContent).toBe(`${apiBaseUrl}/display/setup`);
+    await click("add-display");
+    await type("device-pairing-code-input", PLATFORM_CODE);
+    await submit("device-pairing-lookup");
+    expect(query("device-pairing-shows")).toBeNull();
+    await type("device-pairing-name", "Hall");
+    await submit("device-pairing-approve");
+    expect(
+      platform.requests.find((r) => r.path === "/api/v1/device-pairing/approvals")?.body,
+    ).toEqual({ code: PLATFORM_CODE, deviceName: "Hall" });
+    // Without the module list the card does not guess what the display shows.
+    expect(required("device-device-1").textContent).not.toContain("showing");
   });
 });