Deploy main 5e572ce to prod (#198)

main's tree, with next merged on 26 October, as one commit onto prod, on sneak's order.

Model: opus-5-5
Co-authored-by: clawbot <clawbot@noreply.example.org>

test/viewport/README.md

@@ -1,112 +1,146 @@
-# Responsive-layout harness
+# The viewport test
 
-Automated verification of the responsive layout that landed in #5. Run it with:
+`make frontend-viewport-test` checks the page's layout at several window widths
+in a real browser:
 
 ```bash
 make frontend-viewport-test
 ```
 
-It builds `dist/`, serves it from the same digest-pinned `nginx` image and the
-same `nginx.conf` the shipping container uses, drives a digest-pinned headless
-Chrome against it over CDP, and asserts on computed layout at every viewport
-width derived from the app's own CSS. Screenshots land in `tmp/viewport/`
-alongside a `results.json`; they are artifacts for a human to look at when
-something fails, not the evidence. The assertions are the evidence.
+First it runs the unit tests. Then it builds the page into `dist/`. It serves
+`dist/` with the nginx image and the `configs/nginx.conf` that the Docker image
+ships. Before the browser starts, it fetches `/` and `/no-such-page`, which
+nginx answers with the page. Both must carry `Cache-Control: no-cache` and a
+`Content-Security-Policy` header. Then it starts a headless Chrome in a
+container and opens the page in it at each width. For each width it measures the
+layout inside the page and checks the measurements in Node. The checks decide
+pass or fail. Screenshots and a `results.json` land in `tmp/viewport/`, for a
+person to look at when a check fails.
 
-The target is deliberately outside `make check`: it needs Docker and takes
-minutes, and `make test` has to stay under 20 seconds.
+The test is not part of `make check`: it takes minutes, and `make test` has to
+finish in under 60 seconds.
 
-## How the widths are chosen
+## The widths
 
-Not from a list of phone models. `viewports.js` parses the `@media` conditions
-out of `src/styles.css` and scans `src/main.js` and `index.html` for Tailwind
-responsive prefixes, then tests every breakpoint it finds at one pixel below it,
-exactly on it, and one pixel above it. A generic 375px "phone" test sails
-straight past an off-by-one at a media query boundary; `max-width: 768px`
-matches _at_ 768, and the sweep pins down which side of that line each layout is
-on.
+The breakpoints are read from the page's own files. `viewports.js` reads the
+`min-width` and `max-width` conditions out of the `@media` blocks in
+`web/src/styles.css`. It also looks in `web/src/main.js` and `web/index.html`
+for Tailwind's responsive class prefixes, such as `md:`, and takes their
+breakpoints. Each breakpoint is tested at one pixel below it, exactly on it, and
+one pixel above it. Today the CSS has one breakpoint, `max-width: 768px`, and no
+responsive prefix is used.
 
-Nothing hardcodes 768. Add a second media block or start using `md:` classes and
-the new breakpoint is covered without this directory being touched. The app is
-desktop-first today (all narrow rules live in `max-width` blocks); a
-`min-width`-only, mobile-first set is handled as its inverse, and a set that
-mixes the two makes the run fail loudly rather than test the right widths with
-the wrong expectation. Four further viewports are fixed anchors, each with a
-stated reason: a 320px floor, a 1280px desktop baseline, and two phone-landscape
-sizes straddling the breakpoint for the rotation case.
+A `max-width: 768px` block matches at 768 pixels. Testing both sides of each
+breakpoint catches a layout that switches one pixel too early or too late. A
+second media block, or a first `md:` class, is covered without a change to this
+directory.
 
-## What it asserts
+The page is desktop-first: the wide layout is the default, and every narrow rule
+is in a `max-width` block. So a width is expected to show the narrow layout when
+one of those blocks matches it. A page with only `min-width` blocks would be
+read the other way round. A page that mixes the two kinds fails the run with a
+message, because the right expectation for each width can no longer be read from
+the breakpoints alone.
 
-- **app-rendered** — enough host rows exist and enough of them show a numeric
-  latency. This one exists so the rest cannot pass vacuously against a blank
-  page.
-- **no-horizontal-overflow** — `documentElement.scrollWidth` fits the layout
-  viewport, with the widest offending element named.
-- **nothing-past-viewport-edge** — no visible element's box extends past the
-  viewport edge.
-- **no-clipped-text** — nothing hides text behind `overflow: hidden`. Deliberate
-  ellipsis truncation (Tailwind's `truncate`, used on host names and URLs) is
-  excluded: it is a design choice, not breakage.
-- **tap-targets-44px** — every interactive control is at least 44x44 CSS px on
-  touch viewports, _and_ each selector in the control list matched at least the
-  number of visible elements it declares. The second half is what stops the
-  check passing vacuously: with size alone, a renamed class would take its
-  controls out of the measured set and the check would report "all 0 controls
-  are at least 44x44" and pass. See below.
-- **host-rows-stacked / host-rows-side-by-side** — the rows genuinely reflow.
-  Computed `flex-direction` _and_ the actual geometry are checked, and in the
-  narrow layout the info block and the sparkline must each occupy essentially
-  the full row width. A row that merely shrank its 420px column would fail.
-- **probing-still-runs / gateway-detection-still-runs** — narrow viewports keep
-  probing and keep detecting the gateway. The mobile early-return path proposed
-  in #8 was rejected; this is what would catch it coming back.
+Four more widths are fixed, each for a stated reason:
 
-### The tap-target threshold
+- 320 by 568 pixels: the narrowest width still in common use
+- 667 by 375 pixels: a phone in landscape, inside the narrow layout
+- 844 by 390 pixels: a large phone in landscape, in the wide layout but still a
+  touch device
+- 1280 by 800 pixels: a desktop window
 
-44x44 CSS px. That is the figure in Apple's Human Interface Guidelines and in
-WCAG 2.2 SC 2.5.5 "Target Size (Enhanced)". WCAG 2.2 SC 2.5.8 (level AA) sets a
-lower 24x24 floor, but that floor comes with a spacing exception these controls
-do not qualify for — the pin buttons sit directly against the host name they
-belong to.
+Every width but 1280 by 800 is tested as a touch device.
 
-## Determinism
+## The checks
 
-The browser container runs on an `--internal` docker network and has no route to
-the internet, so the app's latency probes cannot reach anything real. The
-harness answers them itself from a fixed delay table, with a deterministic
-fraction failed outright, so the rows render a realistic spread of one-, two-
-and three-digit latencies plus some unreachable rows. That spread is what the
-layout has to survive; 24 identical `---` placeholders would not exercise it.
+A failed check does not stop the others.
 
-## What this cannot verify
+- `app-rendered`: at least 10 WAN host rows exist, and at least 5 rows show a
+  number as their latency. Without this, the other checks could pass against a
+  blank page.
+- `no-horizontal-overflow`: the document is no wider than the window. On a
+  failure, the widest content is named.
+- `nothing-past-viewport-edge`: no visible element extends past the window's
+  edge.
+- `no-clipped-text`: no element hides its text behind `overflow: hidden` or
+  `overflow: clip`. Text cut with an ellipsis is allowed: that cut is a design
+  choice, not a defect. Tailwind's `truncate` cuts host names and URLs that way.
+- `tap-targets-44px`, on touch widths: each measured control is at least 44 by
+  44 CSS pixels. The controls are `#pause-btn`, `#interval-select`,
+  `#debug-toggle` and the `.pin-btn` in each WAN host row. The check also
+  demands that each selector matches enough visible elements: one of each single
+  control, and one pin button per WAN host row. A renamed class would otherwise
+  take its controls out of the measured set, and the check would pass on
+  nothing.
+- `host-rows-stacked` or `host-rows-side-by-side`: each host row shows the
+  layout expected at that width. In the narrow layout, the row's
+  `flex-direction` is `column`, the graph sits below the host's details, and
+  each takes at least 90% of the row's width. In the wide layout, the direction
+  is `row` and the graph sits to the right of the details. A row that only
+  shrank its fixed 420-pixel column fails.
+- `probing-still-runs`: the page sent at least one check to a target at this
+  width. The narrow layout must not skip the checks.
+- `gateway-detection-still-runs`: the `Local Gateway` row is present at this
+  width, so the gateway was looked for and found. The narrow layout must not
+  skip that search.
 
-Real limits, so nobody re-parks this issue as needing hardware:
+### The tap-target size
 
-- **Non-Chromium engines.** This is Chrome. iOS Safari is WebKit and cannot be
-  emulated by it; Safari-specific bugs (viewport units under a collapsing URL
-  bar, `-webkit-fill-available`, form control metrics) will not show up here.
-- **Real touch input.** `hasTouch` emulation changes what the page is told, not
-  how a finger behaves. Gesture handling, scroll momentum, double-tap zoom and
-  hover-state fallbacks on touch are out of scope.
-- **Physical pixel density and rendering.** `deviceScaleFactor` is set, but
-  subpixel antialiasing, OLED colour rendering and actual legibility at a given
-  physical size are not measurable here.
-- **Fonts.** The container has DejaVu, not the platform's own UI monospace. Text
-  metrics are therefore close to, but not identical to, a real device — a layout
-  that fits here by a few pixels might not there.
-- **On-device performance.** Canvas sparkline redraw cost, battery, and
-  behaviour on a slow radio are not measured.
-- **Browser chrome.** The address bar, safe-area insets and notch cutouts are
-  not simulated.
+44 by 44 CSS pixels is the figure in Apple's Human Interface Guidelines and in
+WCAG 2.2 success criterion 2.5.5, "Target Size (Enhanced)". WCAG 2.2 criterion
+2.5.8 sets a lower minimum of 24 by 24 pixels, with an exception that depends on
+the space around a control. The pin buttons sit against the host name they
+belong to, so the test keeps 44.
 
-Everything else this issue was actually about — does the layout reflow, does
-anything overflow, is content clipped, are the controls big enough — is a
-function of viewport width and CSS, and is covered above.
+## The browser's network
 
-## Relation to the unit test framework (#21)
+The browser container runs on an internal Docker network with no route to the
+internet, so the page's checks reach no real host. The test answers them itself
+from a fixed table of delays: 2, 45, 123, 456 and 780 milliseconds. Which delay
+a target gets depends on its URL, and about one target in seven fails outright.
+So the rows show one-, two- and three-digit latencies and some unreachable rows,
+and the layout is tested against that spread. The request to
+`http://192.168.1.1` is answered after 5 milliseconds, so the `Local Gateway`
+row appears.
 
-Complementary layers, not two stacks. `vitest` (#21) will exercise module-level
-logic in-process with no browser. This harness exercises rendered layout in a
-real engine and is the only thing here that can see a media query. Neither
-replaces the other; assertions about computed styles and element geometry belong
-here, assertions about functions belong in `vitest`.
+At each width, the test sets the interval to 1 second and waits until at least 5
+rows show a latency before it measures. The page discards its first round, so
+this reaches a filled page without waiting out two rounds at 3 seconds.
+
+## What the test cannot check
+
+- Other browser engines. The test runs Chrome. Safari uses WebKit, and bugs that
+  only WebKit has do not show up here.
+- Real touch input. Touch emulation changes what the page is told, not how a
+  finger behaves. Gestures, scroll momentum, double-tap zoom and hover states on
+  touch are not tested.
+- Physical pixels. The device pixel ratio is set, but antialiasing, colour
+  rendering and legibility at a given physical size are not measured.
+- Fonts. The container has DejaVu, not a phone's own monospace font. Text is
+  about as wide as on a real device, but not exactly. A layout that fits here by
+  a few pixels might not fit there.
+- Performance. The cost of redrawing the graphs, battery use and behaviour on a
+  slow connection are not measured.
+- The browser's own frame. The address bar, safe-area insets and notch cutouts
+  are not simulated.
+
+## The files
+
+- `viewports.js` derives the widths from the sources.
+- `facts.js` is run inside the page and measures the layout. It only measures;
+  it decides nothing.
+- `checks.js` turns the measurements into the pass or fail of each check, with
+  the numbers that decided it.
+- `harness.js` connects to the browser, runs each width, writes the screenshots
+  and `results.json`, and prints the results. `script/frontend-viewport-test`
+  starts it; every input it needs arrives in the environment.
+
+## Relation to the unit tests
+
+The unit tests in `test/unit/` call the functions that `web/src/main.js`
+exports, with no browser. `make test` runs them with Node's built-in test
+runner. This test runs the built page in a real browser engine and is the only
+test here that can see a media query. Neither replaces the other. Checks on
+computed styles and element geometry belong here; checks on functions belong in
+`test/unit/`.

test/viewport/checks.js

@@ -15,7 +15,8 @@ export const MIN_TAP_TARGET_PX = 44;
 
 // The controls named in the definition of done, plus the pause button.
 // Each carries the smallest number of *visible* instances the page has to
-// contain for the tap-target oracle to be measuring anything at all.
+// contain, worked out from the facts gathered from that page, for the
+// tap-target oracle to be measuring every control it should.
 //
 // Without those floors the check is inert: `undersized` is empty both when
 // every control is large enough and when the selectors have gone stale and
@@ -24,13 +25,12 @@ export const MIN_TAP_TARGET_PX = 44;
 // for all three singleton controls vanishing at once — so the floor is per
 // selector, and one stale selector out of four fails the check.
 export const INTERACTIVE_CONTROLS = [
-    { selector: "#pause-btn", minCount: 1 },
-    { selector: "#interval-select", minCount: 1 },
-    // One per pinnable host row. `app-rendered` already requires at least
-    // 10 host rows, so a count below that means the pin buttons stopped
-    // being rendered per row rather than that there were fewer hosts.
-    { selector: ".pin-btn", minCount: 10 },
-    { selector: "#debug-toggle", minCount: 1 },
+    { selector: "#pause-btn", minCount: () => 1 },
+    { selector: "#interval-select", minCount: () => 1 },
+    // One per WAN host row, so pin buttons missing from even one row fail
+    // the check rather than only a drop below some fixed number.
+    { selector: ".pin-btn", minCount: (facts) => facts.wanRowCount },
+    { selector: "#debug-toggle", minCount: () => 1 },
 ];
 
 export const INTERACTIVE_SELECTORS = INTERACTIVE_CONTROLS.map(
@@ -105,8 +105,8 @@ export function evaluateChecks(facts, viewport, probes) {
     // never rendered. Everything below is only meaningful if this holds.
     check(
         "app-rendered",
-        facts.rowCount >= 10 && facts.numericLatencies >= 5,
-        `${facts.rowCount} host rows, ${facts.numericLatencies} showing a numeric latency`,
+        facts.wanRowCount >= 10 && facts.numericLatencies >= 5,
+        `${facts.wanRowCount} WAN host rows, ${facts.numericLatencies} showing a numeric latency`,
     );
 
     const viewportWidth = Math.min(facts.innerWidth, facts.documentClientWidth);
@@ -162,7 +162,8 @@ export function evaluateChecks(facts, viewport, probes) {
             seen.set(target.selector, (seen.get(target.selector) ?? 0) + 1);
         }
         const missing = INTERACTIVE_CONTROLS.filter(
-            (control) => (seen.get(control.selector) ?? 0) < control.minCount,
+            (control) =>
+                (seen.get(control.selector) ?? 0) < control.minCount(facts),
         );
 
         const undersized = facts.tapTargets.filter(
@@ -184,11 +185,11 @@ export function evaluateChecks(facts, viewport, probes) {
         const detail = [];
         if (missing.length > 0) {
             detail.push(
-                "oracle is not measuring the page: " +
+                "oracle is not measuring every control: " +
                     summarise(
                         missing,
                         (c) =>
-                            `${c.selector} matched ${seen.get(c.selector) ?? 0} visible element(s), expected at least ${c.minCount}`,
+                            `${c.selector} matched ${seen.get(c.selector) ?? 0} visible element(s), expected at least ${c.minCount(facts)}`,
                         4,
                     ),
             );

test/viewport/facts.js

@@ -173,7 +173,9 @@ export function collectLayoutFacts(options) {
         clipped,
         tapTargets,
         rows,
-        rowCount: document.querySelectorAll(".host-row").length,
+        // WAN host rows only: each has a pin button, and the tap-target
+        // check expects one per row. The local host rows have none.
+        wanRowCount: document.querySelectorAll("#wan-hosts .host-row").length,
         numericLatencies: Array.from(
             document.querySelectorAll(".latency-value"),
         ).filter((el) => /\d/.test(el.textContent)).length,

test/viewport/harness.js

@@ -16,6 +16,10 @@ import { collectLayoutFacts } from "./facts.js";
 import { evaluateChecks, INTERACTIVE_SELECTORS } from "./checks.js";
 import { deriveViewports } from "./viewports.js";
 
+// page.waitForFunction and page.evaluate run the functions given them in
+// the page, where these are defined.
+/* global document, requestAnimationFrame */
+
 function required(name) {
     const value = process.env[name];
     if (!value) {
@@ -47,7 +51,8 @@ const PROBE_DELAYS_MS = [2, 45, 123, 456, 780];
 // offline row rendering is exercised too.
 const UNREACHABLE_MODULUS = 7;
 // The gateway candidate that "answers", so gateway detection succeeds and
-// the Local Gateway row renders. Matches GATEWAY_CANDIDATES in src/main.js.
+// the Local Gateway row renders. Matches GATEWAY_CANDIDATES in
+// web/src/main.js.
 const RESPONSIVE_GATEWAY = "http://192.168.1.1";
 
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
@@ -62,7 +67,6 @@ function stableHash(text) {
 
 async function connectBrowser() {
     const deadline = Date.now() + BROWSER_TIMEOUT_MS;
-    let lastError;
     for (;;) {
         try {
             const response = await fetch(`${CDP_URL}/json/version`);
@@ -77,9 +81,10 @@ async function connectBrowser() {
             });
             return { browser, version: info.Browser };
         } catch (error) {
-            lastError = error;
             if (Date.now() > deadline) {
-                throw new Error(`browser never came up: ${lastError}`);
+                throw new Error(`browser never came up: ${error}`, {
+                    cause: error,
+                });
             }
             await sleep(250);
         }

test/viewport/viewports.js

@@ -161,26 +161,27 @@ const ANCHOR_VIEWPORTS = [
 export function deriveViewports(root) {
     const conditions = [
         ...mediaConditionsFromCss(
-            readFileSync(join(root, "src/styles.css"), "utf8"),
-            "src/styles.css",
+            readFileSync(join(root, "web/src/styles.css"), "utf8"),
+            "web/src/styles.css",
         ),
         ...mediaConditionsFromMarkup([
             {
-                path: "src/main.js",
-                text: readFileSync(join(root, "src/main.js"), "utf8"),
+                path: "web/src/main.js",
+                text: readFileSync(join(root, "web/src/main.js"), "utf8"),
             },
             {
-                path: "index.html",
-                text: readFileSync(join(root, "index.html"), "utf8"),
+                path: "web/index.html",
+                text: readFileSync(join(root, "web/index.html"), "utf8"),
             },
         ]),
     ];
 
     if (conditions.length === 0) {
         throw new Error(
-            "no responsive breakpoints found in src/styles.css, src/main.js or " +
-                "index.html — either the responsive layout was deleted or this " +
-                "derivation has stopped matching the sources",
+            "no responsive breakpoints found in web/src/styles.css, " +
+                "web/src/main.js or web/index.html — either the responsive " +
+                "layout was deleted or this derivation has stopped matching " +
+                "the sources",
         );
     }