test: automated responsive-layout harness (closes #13)

Verifies the mobile layout from #5 with a real browser engine instead of
by hand on a phone. make frontend-viewport-test builds dist/, serves it
from the same digest-pinned nginx image and the same nginx.conf the
shipping container uses, and drives a digest-pinned headless Chrome
against it over CDP.

Viewport widths are derived from the app's own CSS rather than from a
list of phone models: the @media conditions in src/styles.css and any
Tailwind responsive prefixes in the markup are parsed, and each
breakpoint is tested one pixel below, exactly on, and one pixel above.
max-width: 768px matches at 768, and a generic 375px test sails past
that boundary entirely. Four anchor viewports are added with stated
reasons: a 320px floor, a desktop baseline, and two phone-landscape
sizes straddling the breakpoint.

Assertions are on computed layout, not screenshots: horizontal overflow,
elements past the viewport edge, clipped text (deliberate ellipsis
truncation excluded), 44x44 minimum tap targets, and genuine reflow of
the host rows checked on both flex-direction and geometry. Probing and
gateway detection are asserted to still run at narrow widths, since the
early-return mobile path rejected in #8 is what would silently regress.
Screenshots are written to tmp/viewport/ as artifacts alongside the
results, not as the evidence.

puppeteer-core rather than playwright: it is the one variant of either
that never downloads or bundles a browser, so the browser stays a
digest-pinned image and the npm side is pinned by yarn.lock integrity.

The browser container runs on an --internal docker network with no route
off the host; the harness answers the app's latency probes itself from a
fixed delay table so the rows render a realistic spread of value widths.

Kept out of make check: it needs Docker and takes minutes, where make
test has to stay under 20 seconds.

Every check guards its own presence, so none can pass against a page it
is not measuring. The tap-target check in particular would otherwise be
inert: an empty undersized set means both "all controls are big enough"
and "the selectors have gone stale", and the size comparison alone
cannot tell those apart. Each selector therefore declares the minimum
number of visible instances the page must contain, per selector rather
than in total, so one stale selector out of four fails rather than only
all four at once.

Layout expectation is likewise refused rather than guessed. A width is
narrow when a max-width block matches (desktop-first, what the app does
today) or, for a min-width-only mobile-first set, when it falls below
every breakpoint; a set mixing both cannot be resolved from the
conditions alone, because which block owns the reflow is a property of
the rules inside it, so the run fails with an explanation instead of
testing the right widths against the wrong expectation.

The harness was observed failing before being trusted, four times: a
planted 900px fixed-width element in a host row; the mobile reflow rule
neutered; the tap-target threshold lowered so nothing was undersized and
.pin-btn then renamed, which took the check from 8/8 green at every
touch viewport to failing at all six, naming the stale selector; and a
second media block added so the breakpoint set mixed max and min, which
aborted the run. All reverted.

Against the current layout it reports two real defects, filed as #42
(horizontal overflow at 320px) and #43 (tap targets below 44x44).

TODO.md

@@ -25,7 +25,9 @@ files, so merging it also closes most compliance gaps.
 - 2026-08-09: automated responsive-layout harness
   (`make frontend-viewport-test`): digest-pinned headless Chrome driven over CDP
   against the built `dist/`, viewport widths derived from the breakpoints in
-  `src/styles.css` (#13). Found two real layout defects, filed as #42 and #43
+  `src/styles.css` (#13). Every check carries a presence guard so none of them
+  can pass against a page it is not actually measuring. Found two real layout
+  defects, filed as #42 and #43
 - 2026-07-07 Adopted scripts-to-rule-them-all: `script/` entrypoints, Makefile
   shims, README Entrypoints section
 - 2026-02-27: backend with buffered zstd-compressed report storage; CI workflow

script/frontend-viewport-test

@@ -25,9 +25,16 @@ RUN_ID="$$-$(date +%s)"
 NETWORK="netwatch-viewport-$RUN_ID"
 SERVER="netwatch-viewport-server-$RUN_ID"
 BROWSER="netwatch-viewport-browser-$RUN_ID"
+HARNESS="netwatch-viewport-harness-$RUN_ID"
 ARTIFACT_DIR="$ROOT/tmp/viewport"
 
+# Every container is named and removed here, including the harness itself:
+# `timeout` below kills the `docker run` client, not the container it
+# started, and an unnamed survivor keeps the --internal network in use so
+# `docker network rm` fails too. This host runs many sessions at once and
+# neither may be left behind.
 cleanup() {
+    docker rm -f "$HARNESS" > /dev/null 2>&1 || true
     docker rm -f "$BROWSER" > /dev/null 2>&1 || true
     docker rm -f "$SERVER" > /dev/null 2>&1 || true
     docker network rm "$NETWORK" > /dev/null 2>&1 || true
@@ -79,7 +86,7 @@ main() {
         -f '{{range .NetworkSettings.Networks}}{{.IPAddress}}{{end}}' \
         "$BROWSER")"
 
-    timeout 900 docker run --rm --init \
+    timeout 900 docker run --rm --init --name "$HARNESS" \
         --network "$NETWORK" \
         --user "$(id -u):$(id -g)" \
         -v "$ROOT:/app" \

test/viewport/README.md

@@ -27,10 +27,13 @@ matches _at_ 768, and the sweep pins down which side of that line each layout is
 on.
 
 Nothing hardcodes 768. Add a second media block or start using `md:` classes and
-the new breakpoint is covered without this directory being touched. 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.
+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.
 
 ## What it asserts
 
@@ -45,7 +48,11 @@ the rotation case.
   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. See below.
+  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

test/viewport/checks.js

@@ -14,13 +14,29 @@
 export const MIN_TAP_TARGET_PX = 44;
 
 // The controls named in the definition of done, plus the pause button.
-export const INTERACTIVE_SELECTORS = [
-    "#pause-btn",
-    "#interval-select",
-    ".pin-btn",
-    "#debug-toggle",
+// Each carries the smallest number of *visible* instances the page has to
+// contain for the tap-target oracle to be measuring anything at all.
+//
+// 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
+// matched nothing, and the pass condition cannot tell those apart. A single
+// combined floor would not be enough either — 26 pin buttons would cover
+// 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 },
 ];
 
+export const INTERACTIVE_SELECTORS = INTERACTIVE_CONTROLS.map(
+    (control) => control.selector,
+);
+
 // A host row is only "reflowed" if it stacked *and* went full width.
 // A row that merely shrank its 420px info column would keep
 // flex-direction: row, and a row that stacked but left the info column at
@@ -138,6 +154,17 @@ export function evaluateChecks(facts, viewport, probes) {
     );
 
     if (viewport.touch) {
+        // Presence first: a selector that matches nothing contributes no
+        // undersized targets, so without this the check would report
+        // "all 0 controls are at least 44x44" and pass.
+        const seen = new Map();
+        for (const target of facts.tapTargets) {
+            seen.set(target.selector, (seen.get(target.selector) ?? 0) + 1);
+        }
+        const missing = INTERACTIVE_CONTROLS.filter(
+            (control) => (seen.get(control.selector) ?? 0) < control.minCount,
+        );
+
         const undersized = facts.tapTargets.filter(
             (t) => t.width < MIN_TAP_TARGET_PX || t.height < MIN_TAP_TARGET_PX,
         );
@@ -154,11 +181,21 @@ export function evaluateChecks(facts, viewport, probes) {
                 existing.count += 1;
             }
         }
-        check(
-            `tap-targets-${MIN_TAP_TARGET_PX}px`,
-            undersized.length === 0,
+        const detail = [];
+        if (missing.length > 0) {
+            detail.push(
+                "oracle is not measuring the page: " +
+                    summarise(
+                        missing,
+                        (c) =>
+                            `${c.selector} matched ${seen.get(c.selector) ?? 0} visible element(s), expected at least ${c.minCount}`,
+                        4,
+                    ),
+            );
+        }
+        detail.push(
             undersized.length === 0
-                ? `all ${facts.tapTargets.length} controls are at least ${MIN_TAP_TARGET_PX}x${MIN_TAP_TARGET_PX}`
+                ? `${facts.tapTargets.length} controls measured, all at least ${MIN_TAP_TARGET_PX}x${MIN_TAP_TARGET_PX}`
                 : `${undersized.length} of ${facts.tapTargets.length} controls below ${MIN_TAP_TARGET_PX}x${MIN_TAP_TARGET_PX}: ` +
                       summarise(
                           [...bySelector.values()],
@@ -167,6 +204,11 @@ export function evaluateChecks(facts, viewport, probes) {
                           4,
                       ),
         );
+        check(
+            `tap-targets-${MIN_TAP_TARGET_PX}px`,
+            missing.length === 0 && undersized.length === 0,
+            detail.join("; "),
+        );
     }
 
     const badRows = facts.rows

test/viewport/viewports.js

@@ -73,13 +73,52 @@ export function mediaConditionsFromMarkup(sources) {
 }
 
 // Whether a given width should be rendering the app's narrow (stacked)
-// layout. The app keeps all of its narrow-viewport rules inside
-// `max-width` blocks, so a width is narrow exactly when one of those
-// blocks matches. Note that `max-width: 768px` matches *at* 768: getting
-// this inclusive boundary wrong in either direction is precisely what the
-// three-widths-per-breakpoint sweep exists to catch.
+// layout.
+//
+// Two breakpoint styles can be answered from the condition list alone:
+//
+//   - Desktop-first, which is what the app ships today: the wide layout is
+//     unconditional and every narrow rule lives in a `max-width` block, so
+//     a width is narrow exactly when one of those blocks matches. Note that
+//     `max-width: 768px` matches *at* 768 — getting this inclusive boundary
+//     wrong in either direction is what the three-widths-per-breakpoint
+//     sweep exists to catch.
+//   - Mobile-first, which is what Tailwind's `sm:`/`md:` prefixes are: the
+//     stacked layout is the unconditional base and a `min-width` block is
+//     what widens it, so a width is narrow exactly when it sits below every
+//     `min-width` breakpoint.
+//
+// A mix of the two cannot be resolved from the breakpoints alone — which
+// block owns the host-row reflow is a property of the rules inside it, not
+// of the condition — so this throws rather than guessing. Guessing is how
+// the wrong expectation gets applied at the right widths and the whole
+// sweep quietly verifies nothing.
 export function expectsStackedLayout(width, conditions) {
-    return conditions.some((c) => c.type === "max" && width <= c.px);
+    const kinds = new Set(conditions.map((c) => c.type));
+    for (const kind of kinds) {
+        if (kind !== "max" && kind !== "min") {
+            throw new Error(
+                `unsupported media condition type "${kind}" in ` +
+                    "expectsStackedLayout (test/viewport/viewports.js)",
+            );
+        }
+    }
+    if (kinds.has("max") && kinds.has("min")) {
+        throw new Error(
+            "the app now mixes max-width and min-width breakpoints (" +
+                conditions
+                    .map((c) => `${c.type}-width ${c.px}px in ${c.source}`)
+                    .join(", ") +
+                "), so which layout a width should be showing can no longer " +
+                "be inferred from the breakpoint list; teach " +
+                "expectsStackedLayout in test/viewport/viewports.js which " +
+                "block owns the host-row reflow",
+        );
+    }
+    if (kinds.has("min")) {
+        return !conditions.some((c) => width >= c.px);
+    }
+    return conditions.some((c) => width <= c.px);
 }
 
 // Viewports that are not derived from a breakpoint. Each one is here for