Explain display setup in Settings, stop iOS form zoom, lock the page behind the drawer

A second real-iPhone review of the Stage 1 Dashboard found three
defects. This fixes them, and ADR 0065 records the decisions.

- Settings -> Displays now sets up a screen in one place. A "Set up a
  new screen" panel shows the platform display page to open on the
  screen, a Copy link button, and Add display directly beneath it; the
  step-by-step version is folded into a <details>. The addresses come
  from a new GET /api/v1/devices/setup, which requires
  core.devices.manage and lists each running display module's
  /display/<module-id> page. Nothing names Signage. With no display
  module installed, the panel says so and offers no Add display.
- iOS Safari zoomed into the pairing field because the shared
  .ek-control rendered at 14px. On phones and touch screens it now
  renders at max(1rem, 16px). The viewport is untouched, so zoom stays
  available, and a test guards that. The shared focus trap now returns
  focus with preventScroll, so closing a dialog no longer moves the page
  under the phone header.
- While the phone drawer is open, the page behind it no longer scrolls.
  The root's overflow is hidden, a non-passive touchmove listener
  cancels drags outside the drawer's list and overscroll past its ends,
  and root overscroll is turned off. The list itself still scrolls.
  Closing restores the exact scroll position unless another page opened.

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

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

@@ -41,6 +41,8 @@ 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";
 }
 
 function server(options: ServerOptions = {}) {
@@ -59,6 +61,16 @@ 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") {
+        return json({ code: "DEVICE_LOOKUP_UNAVAILABLE" }, 503);
+      }
+      return json({
+        displays: options.setup ?? [
+          { moduleId: "signage", name: "Signage", url: "/display/signage" },
+        ],
+      });
+    }
     if (path === "/api/v1/devices") {
       return options.denied ? json({ code: "AUTHORIZATION_DENIED" }, 403) : json({ devices });
     }
@@ -162,6 +174,19 @@ describe("Settings → Displays", () => {
     expect(card.textContent).toContain("Paired");
     expect(card.textContent).toContain("Last seen within the last hour");
     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.
+    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(setup.contains(required("add-display"))).toBe(true);
+    const steps = required("display-setup-steps");
+    expect(steps.tagName).toBe("DETAILS");
+    expect((steps as HTMLDetailsElement).open).toBe(false);
+    expect(steps.querySelector("summary")?.textContent).toBe("Step-by-step instructions");
+    expect(steps.textContent).toContain("six-digit pairing code");
+    // Not a second Add display up in the header.
+    expect(container.querySelectorAll('[data-testid="add-display"]')).toHaveLength(1);
     // No pairing form until someone asks for one, and nothing grabbed focus.
     expect(container.querySelector("input")).toBeNull();
     expect(document.activeElement).toBe(before);
@@ -216,11 +241,72 @@ describe("Settings → Displays", () => {
     await click("add-display-cancel");
 
     expect(query("add-display-dialog")).toBeNull();
-    expect(platform.requests.map((r) => r.path)).toEqual(["/api/v1/devices"]);
+    expect(platform.requests.map((r) => r.path).sort()).toEqual([
+      "/api/v1/devices",
+      "/api/v1/devices/setup",
+    ]);
     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 () => {
+    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`);
+    expect(required("display-setup").textContent).toContain("Link copied.");
+
+    Object.defineProperty(window.navigator, "clipboard", { configurable: true, value: undefined });
+    await click("display-setup-copy-signage");
+    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("makes sense with no module that uses displays installed, Signage included", async () => {
+    await renderPage({ setup: [] });
+    expect(required("display-setup-none").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");
+  });
+
+  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");
+    await click("add-display");
+    expect(query("add-display-dialog")).not.toBeNull();
+  });
+
+  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();
+  });
+});
+
 /**
  * Revoking a display strands that screen until someone re-pairs it in person, so the page explains
  * the consequence in its own dialog first — never with a browser-native confirm (DESIGN §21).