styleproof 2.0.0 → 2.1.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.1.0] - 2026-06-23
+
+### Added
+
+- **Coverage guard (`expected` / `exclude`).** `defineStyleMapCapture` now accepts
+  `expected` — the app's route/view universe — and emits a guard test that fails
+  when a route has no captured surface and isn't in `exclude`. It runs in the
+  normal test suite (no `STYLEMAP_DIR`, no browser — a static check), closing the
+  one hole captures can't catch on their own: a new page nobody added to
+  `surfaces` is invisible to the diff (no base capture, no head capture), so the
+  gate goes green having never looked at it. `exclude` is a `key → reason` ledger
+  of deliberate opt-outs; a key absent from `expected` (a renamed/removed route)
+  fails the guard too, so the ledger can't rot. Omit `expected` and behaviour is
+  unchanged. The pure `coverageGaps(captured, expected, exclude)` helper is also
+  exported. Closes the class of regression where a brand-new view's styles ship
+  uncaptured because the surface list silently drifted from the app's routes.
+- **Coverage guard works out of the box for Next.js.** New `discoverNextRoutes()`
+  reads the App Router (`app/`) and Pages Router (`pages/`) at run time and returns
+  `{ key, path, dynamic }[]` (route groups/slots stripped, `[param]` flagged). `styleproof-init`
+  now detects a Next.js app and scaffolds a spec that wires both the surfaces and
+  `expected` to it — so a fresh install is protected without hand-wiring, and a page
+  added later is covered automatically. Non-Next projects get the previous starter
+  surface plus a commented guard block to point at their own route registry.
+- **Network-aware settle (default on).** The settle now holds while the page's own
+  data requests are in flight — excluding long-lived `EventSource`/WebSocket streams
+  (handled by the live-region pass) — instead of only waiting for the computed-style
+  map to go quiet. So late-fetched content is captured **loaded, not mid-load**, and
+  the settle can't false-settle on a loading state before a slow backend responds —
+  the phantom-diff / self-check flake that a fixed wait produces under CI load. New
+  exported `trackInflightRequests(page)` arms the tracker; `defineStyleMapCapture`
+  arms it before each `go()` automatically.
+  Opt out with `stabilize.waitForRequests: false`.
+- **`styleproof-init` scaffolds a production-build web server.** The generated
+  `playwright.config.ts` now includes a `webServer` that runs
+  `npm run build && npm run start` (reusing a server already up), so a fresh project
+  captures against a production build by default instead of a `next dev`-style server
+  whose JIT timing variance is the top source of capture flakes.
+
+### Changed
+
+- **`selfCheck` defaults on while recording, off on replay.** The determinism guard
+  (capture twice, fail on drift) was opt-in (`STYLEPROOF_SELFCHECK=1`), so by default
+  nondeterminism shipped silently as a phantom diff. It now defaults **on when
+  recording** (no `replayFrom`), where live nondeterminism surfaces, and **off on
+  replay**, which is deterministic by construction — so a fresh
+  `defineStyleMapCapture({ surfaces })` auto-detects and names nondeterminism with no
+  2× cost on the replay run. `STYLEPROOF_SELFCHECK=1` still forces it on for both;
+  `selfCheck: false` opts out.
+- **`styleproof-init` scaffolds a minimal `settle()`.** Now that the engine's
+  network-aware settle waits out in-flight data and fonts, freezes animations, and
+  blurs focus, the generated helper drops the hand-rolled `document.fonts.ready`,
+  animation-freeze, fixed `waitForTimeout`, and `networkidle` wait (the last an
+  active trap — it never fires against an SSE stream). It keeps only what the engine
+  can't know about — scroll-reveal — and `go()` is a plain `page.goto(...)`.
+
 ## [2.0.0] - 2026-06-22
 
 ### Changed

package/README.md

@@ -19,13 +19,58 @@ On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base br
 - **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown in the report under a `🆕 new surface` heading but never holds the status red and needs no sign-off. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
 
+## Don't let a new page ship uncaptured
+
+StyleProof diffs the surfaces your spec lists — so a page nobody added to the list is invisible to the gate. Its change has no base capture _and_ no head capture, so it never appears in any diff, and the status goes green having never looked at it. This is the one thing the captures can't catch on their own: a capture that was never taken.
+
+Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
+
+```ts
+import { defineStyleMapCapture } from 'styleproof';
+import { ROUTES } from '../app/routes'; // your registry — wherever routes live
+
+defineStyleMapCapture({
+  dir: process.env.STYLEMAP_DIR,
+  surfaces: SURFACES,
+  expected: ROUTES.map((r) => r.id), // every route StyleProof should cover
+  exclude: { checkout: 'auth-gated — capture fixture pending' }, // visible, reviewed opt-outs (key → reason)
+});
+```
+
+A route that's neither a captured surface nor an `exclude` entry fails the guard; an `exclude` key that isn't in `expected` (a renamed/removed route) fails too, so the opt-out ledger can't quietly rot. Captured surfaces beyond `expected` are fine — one route can have several states (`landing`, `landing-nav-open`). Omit `expected` and behaviour is unchanged.
+
+**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and wires both the surfaces and `expected` to them — so it's protected out of the box, and a page you add later is covered automatically with nothing to keep in sync:
+
+```ts
+import { defineStyleMapCapture, discoverNextRoutes } from 'styleproof';
+
+const ROUTES = discoverNextRoutes(); // [{ key, path, dynamic }, …] from app/ + pages/
+defineStyleMapCapture({
+  surfaces: ROUTES.filter((r) => !r.dynamic).map((r) => ({
+    key: r.key,
+    go: (p) => p.goto(r.path),
+    widths: [1280, 768, 390],
+  })),
+  expected: ROUTES.map((r) => r.key),
+  exclude: Object.fromEntries(
+    ROUTES.filter((r) => r.dynamic).map((r) => [
+      r.key,
+      `dynamic route ${r.path} — add a surface with a concrete param`,
+    ]),
+  ),
+  dir: process.env.STYLEMAP_DIR,
+});
+```
+
+`discoverNextRoutes(cwd?)` reads the filesystem only (route groups `(group)` and `@slots` stripped, `[param]`/`[...catchall]` flagged `dynamic`) — a heuristic, not a router; edit the generated spec for exotic routing. For any other framework, point `expected` at your own route registry as above.
+
 ## What a report looks like
 
-One change — the hero CTA recoloured cyan → amber — posts as a single section: a side-by-side before/after cropped screenshot, a one-line summary, then the exact property change folded under a toggle.
+One change — the hero CTA recoloured cyan → amber — appears as a single section in the report: a side-by-side before/after cropped screenshot, a one-line summary, then the exact property change folded under a toggle.
 
 ![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](https://raw.githubusercontent.com/BenSheridanEdwards/StyleProof/main/docs/demo-composite.png)
 
-As it renders in the PR comment (a plain-English bullet first — naming the theme token and showing the hex with a live colour swatch — then the exact table inside the toggle):
+As it renders in the committed report (a plain-English bullet first — naming the theme token and showing the hex with a live colour swatch — then the exact table inside the toggle). The PR comment itself stays lean — a summary plus the approval box — and links here:
 
 ```text
 ### `a.btn-solid` · 1 element restyled
@@ -67,11 +112,7 @@ defineStyleMapCapture({
   surfaces: [
     {
       key: 'landing',
-      go: async (page) => {
-        await page.goto('/');
-        await page.waitForLoadState('networkidle');
-        await page.evaluate(() => document.fonts.ready);
-      },
+      go: (page) => page.goto('/'), // that's it — StyleProof settles the page (in-flight data, fonts, animations) before it reads
       widths: [1280, 768, 390], // one viewport per @media band
     },
   ],
@@ -141,12 +182,31 @@ Copy both `capture` and `report` files to `.github/workflows/` (the `report` one
 
 - **Record / replay.** The base capture records each surface's data responses (anything matching `**/api/**`) to a HAR; the head capture replays them, so the head renders _its_ code against the _base's_ data — the app's own JS/CSS still load live. Backend down during a run? Both sides replay the same recording, so there's no phantom diff. Point the head capture at the base's recording with `STYLEPROOF_REPLAY_FROM=<base dir>` (see the CI step above); tune the data boundary with `STYLEPROOF_REPLAY_URL` / `replayUrl` if your API isn't under `/api`.
 - **Frozen clock.** `Date.now()` / `new Date()` are pinned to a fixed instant, so time-derived styling (`stale > 1h → red`) can't drift. Timers keep running, so settling still works.
-- **Self-check** (`STYLEPROOF_SELFCHECK=1`). Captures each surface twice and fails if they differ — a replay gap or unseeded randomness surfaces as a clear _"non-deterministic capture"_ error, never as a phantom change on an unrelated PR.
+- **Self-check** — captures each surface twice and fails if they differ, so a replay gap or unseeded randomness surfaces as a clear _"non-deterministic capture"_ error, never as a phantom change on an unrelated PR. **On by default while recording** (where live nondeterminism shows up); off on the replay run, which renders against the recorded HAR and is deterministic by construction. `STYLEPROOF_SELFCHECK=1` forces it on for both; `selfCheck: false` opts out.
 - **Framework noise is skipped by default.** Non-visual and framework-injected elements never count as a change — `<meta>`/`<title>`/`<script>`/`<style>`/… (which Next.js streams into the body then hoists) and live regions like Next's `next-route-announcer`. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. Add your own selectors with `ignore` — they extend this default, they don't replace it.
 
 > Replay covers data the page _fetches_. If your app **server-renders** differently per environment (SSR feature flags, locale), still capture both sides with the same server env so the rendered HTML matches.
 
-**Live pages just work.** Before each capture, StyleProof settles the page — it waits until the computed-style map stops changing, so async content (a fetch, an SSE/WebSocket stream backfilling a grid) is captured loaded, not mid-load. Anything still moving on its own after that is detected as a live region and excluded from the diff, so a stream or ticker never reads as a change — no manual `ignore` needed. Disable or tune with `captureStyleMap(page, { stabilize: false })` / `{ stabilize: { quietFor, timeout } }`.
+**Live pages just work.** Before each capture, StyleProof settles the page, and the settle is **network-aware**: it holds while the page's data requests are in flight (excluding long-lived `EventSource`/WebSocket streams, which never finish) _and_ until the computed-style map stops changing. So async content (a fetch backfilling a grid, an SSE stream) is captured **loaded, not mid-load** — and, crucially, it **can't false-settle on the loading state before a slow backend's response arrives**. That's the failure mode of a fixed wait: against a slow server (e.g. a dev server under CI load) a timer settles on the loading skeleton one run and the loaded deck the next — a phantom diff / self-check flake. Waiting on the actual request removes it. Anything still moving on its own after that is detected as a live region and excluded from the diff, so a stream or ticker never reads as a change — no manual `ignore` needed. `defineStyleMapCapture` arms the request tracker before each `go()` automatically; for a direct `captureStyleMap` call, arm one before you navigate with `trackInflightRequests(page)` and pass `{ pendingRequests }`. Disable or tune with `{ stabilize: false }` / `{ stabilize: { quietFor, timeout, waitForRequests } }`.
+
+**At a glance — almost everything is automatic.** The few knobs exist only for what StyleProof can't know about your app, and each says why:
+
+| Handled for you — zero config                               | How                                                                                      |
+| ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
+| In-flight data, fonts, late layout                          | network-aware settle holds until requests finish _and_ the computed styles stop changing |
+| Animations, transitions, focus ring, caret                  | frozen / blurred before the map is read                                                  |
+| Clock-derived styling (`stale > 1h → red`)                  | `Date.now()` / `new Date()` frozen to a fixed instant                                    |
+| Framework & non-visual noise (`<script>`, route announcers) | skipped by default                                                                       |
+| Live / volatile regions (tickers, third-party embeds)       | auto-detected as still-moving and excluded from the diff                                 |
+| Non-deterministic capture (replay gap, unseeded randomness) | self-check flags it _while recording_, with a named error                                |
+
+| You set this — only because it's app-specific | Why it exists                                                                                                                                                                                                    |
+| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STYLEPROOF_REPLAY_FROM` (record / replay)    | Base and head capture at different times against a live backend; replaying the base's recorded data pins the head to the same inputs, so the diff is **your code, not data drift**. The one piece of real setup. |
+| `replayUrl` / `STYLEPROOF_REPLAY_URL`         | Your data endpoints aren't under `**/api/**`.                                                                                                                                                                    |
+| `ignore: ['.selector']`                       | You want a region gone **explicitly** — auto-exclude already handles most live regions, but a known-noisy element reads clearer named.                                                                           |
+| `clockTime`                                   | Your styling keys off a **specific** date, not just "now".                                                                                                                                                       |
+| `stabilize: { quietFor, timeout }`            | An unusually slow surface needs a longer quiet window before the map is read.                                                                                                                                    |
 
 ## Optional: content layer (advisory)
 
@@ -200,17 +260,19 @@ It's **asynchronous by design**: approval is a checkbox tick handled by a separa
 
 **Capture spec `defineStyleMapCapture({ surfaces, … })`** — determinism is on by default; you rarely set more than `surfaces` and `dir`:
 
-| Option        | Default                     | Purpose                                                                                                          |
-| ------------- | --------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths, ignore?, height? }`. `go(page)` drives to a settled state.     |
-| `dir`         | `STYLEMAP_DIR`              | Output label (`base`/`head`); the spec is **inert until set**, so it sits safely beside your other specs.        |
-| `replayFrom`  | `STYLEPROOF_REPLAY_FROM`    | Baseline dir whose recorded responses to replay. Unset → this run **records** its HAR for the comparison to use. |
-| `replayUrl`   | `**/api/**` (`…REPLAY_URL`) | URL glob for the data boundary to record/replay; everything else (JS/CSS/fonts) loads live so the code runs.     |
-| `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.  |
-| `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                              |
-| `selfCheck`   | `STYLEPROOF_SELFCHECK=1`    | Capture each surface twice and fail on any difference — proves the capture is deterministic.                     |
-| `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                  |
-| `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                           |
+| Option        | Default                     | Purpose                                                                                                                                                                             |
+| ------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths, ignore?, height? }`. `go(page)` drives to a settled state.                                                                        |
+| `expected`    | _none_                      | Your route/view universe. Emits a coverage-guard test (runs without a capture dir) that fails when a route has no surface and isn't excluded — so a new page can't ship uncaptured. |
+| `exclude`     | `{}`                        | `key → reason` for routes deliberately not captured. Keeps the guard green for known gaps; a key absent from `expected` fails the guard, so the ledger can't go stale.              |
+| `dir`         | `STYLEMAP_DIR`              | Output label (`base`/`head`); the spec is **inert until set**, so it sits safely beside your other specs.                                                                           |
+| `replayFrom`  | `STYLEPROOF_REPLAY_FROM`    | Baseline dir whose recorded responses to replay. Unset → this run **records** its HAR for the comparison to use.                                                                    |
+| `replayUrl`   | `**/api/**` (`…REPLAY_URL`) | URL glob for the data boundary to record/replay; everything else (JS/CSS/fonts) loads live so the code runs.                                                                        |
+| `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.                                                                     |
+| `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                                                                                                 |
+| `selfCheck`   | on while recording          | Capture each surface twice and fail on any difference — proves the capture is deterministic. Off on the replay run; `STYLEPROOF_SELFCHECK=1` forces both.                           |
+| `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                                                                                     |
+| `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                                                                                              |
 
 Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<style>`/… and `next-route-announcer`) are skipped automatically; a surface's `ignore` adds to that default, it doesn't replace it.
 
@@ -225,8 +287,8 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `styleproof-init` — scaffold the capture spec (and a starter `playwright.config.ts` if none exists).
-- `styleproof-diff <beforeDir> <afterDir>` — the certify gate; exits `1` on any difference.
+- `styleproof-init` — scaffold the capture spec (and, if none exists, a starter `playwright.config.ts` whose `webServer` **builds and serves a production build**, so captures never run against a flaky dev server).
+- `styleproof-diff <beforeDir> <afterDir>` — the certify gate; exits `0` certified (identical), `1` on a diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against).
 - `styleproof-report <beforeDir> <afterDir> --out <dir>` — render the diff to a Markdown report with before/after crops. Add `--include-content` for the opt-in, advisory content section (see above).
 
 A programmatic API (`captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, …) is also exported. For the capture internals, the approve-workflow trust model, and how to contribute, see [CONTRIBUTING](https://github.com/BenSheridanEdwards/StyleProof/blob/main/CONTRIBUTING.md) and the [`example/`](https://github.com/BenSheridanEdwards/StyleProof/tree/main/example) workflows.

package/bin/styleproof-init.mjs

@@ -6,8 +6,11 @@
  *
  * Writes:
  *   - <dir> (default e2e/styleproof.spec.ts): a starter capture spec with a
- *     robust settle() helper (waits fonts + neutralises scroll-reveal and CSS
- *     animation/transition) and one sample Surface.
+ *     minimal settle() helper (triggers scroll-reveal content; StyleProof itself
+ *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives surfaces AND
+ *     the `expected` coverage guard from the app's routes at run time, so a page
+ *     added later can't ship without a surface; otherwise it writes one sample
+ *     surface plus a commented guard block to wire to your own route registry.
  *   - playwright.config.ts: only if one does not already exist, so an existing
  *     Playwright project is never disturbed.
  *
@@ -17,6 +20,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { discoverNextRoutes } from '../dist/index.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
 
@@ -30,13 +34,14 @@ options:
   -h, --help          show this help
 
 What it writes:
-  - the spec at --dir, with a settle() helper (fonts + reveal/animation freeze)
-    and one sample Surface sweeping widths [1280, 768, 390]
+  - the spec at --dir, with a minimal settle() helper (scroll-reveal only).
+    In a Next.js app it discovers your routes at run time and wires both the
+    surfaces and the \`expected\` coverage guard to them, so a new page can't ship
+    uncaptured. Otherwise it writes one sample surface + a commented guard block.
   - playwright.config.ts, only if absent (an existing one is left untouched)
 
 After running, capture a baseline against a PRODUCTION build:
   STYLEMAP_DIR=baseline npx playwright test styleproof
-  git add e2e/__stylemaps__/baseline && git commit -m "chore: stylemap baseline"
 
 To certify a refactor:
   STYLEMAP_DIR=before npx playwright test styleproof
@@ -70,10 +75,34 @@ if (!specPath) {
   process.exit(2);
 }
 
-const SPEC = `import type { Page } from '@playwright/test';
-import { defineStyleMapCapture, type Surface } from 'styleproof';
+// Captures read whatever is in front of them, so the page must be settled and
+// deterministic first — this helper is shared by both spec variants below.
+const SETTLE = `// StyleProof settles the page for you before it reads — it waits out in-flight data
+// and fonts, freezes animations/transitions, and blurs focus. The one thing it can't
+// know about is *scroll-reveal* content: elements an IntersectionObserver mounts (or
+// fades in) only once they're scrolled into view. settle() triggers that — it scrolls
+// the page so those reveals fire, forces common reveal markers to their final state so
+// nothing is caught mid-fade, then returns to the top. Tune the selectors to match
+// your project. No reveal-on-scroll content? Delete settle() and use the one-liner
+// \`go: (page) => page.goto('/')\`.
+async function settle(page: Page) {
+  await page.addStyleTag({
+    content: \`.reveal, [data-reveal], .fade-in, .animate-in {
+      opacity: 1 !important;
+      transform: none !important;
+      visibility: visible !important;
+    }\`,
+  });
+  await page.evaluate(async () => {
+    for (let y = 0; y < document.body.scrollHeight; y += window.innerHeight) {
+      window.scrollTo(0, y);
+      await new Promise((r) => setTimeout(r, 60));
+    }
+    window.scrollTo(0, 0);
+  });
+}`;
 
-/**
+const HEADER = `/**
  * styleproof capture spec (generated by \`styleproof-init\`).
  *
  * Each surface is one deterministic page state; widths sweep one viewport per
@@ -84,46 +113,63 @@ import { defineStyleMapCapture, type Surface } from 'styleproof';
  *   ...refactor your CSS...
  *   STYLEMAP_DIR=after  npx playwright test styleproof   # capture again
  *   npx styleproof-diff __stylemaps__/before __stylemaps__/after
- */
+ */`;
 
-// Captures read whatever is in front of them, so the page must be settled and
-// deterministic first. settle() (1) waits for web fonts, (2) freezes CSS
-// animations/transitions and forces common scroll-reveal markers to their final
-// state so nothing is mid-fade, then (3) scrolls the page to trigger any
-// IntersectionObserver-driven reveals and returns to the top. Tune the reveal
-// selectors below to match your project.
-async function settle(page: Page) {
-  await page.addStyleTag({
-    content: \`
-      *, *::before, *::after {
-        animation: none !important;
-        transition: none !important;
-        animation-duration: 0s !important;
-        transition-duration: 0s !important;
-      }
-      .reveal, [data-reveal], .fade-in, .animate-in {
-        opacity: 1 !important;
-        transform: none !important;
-        visibility: visible !important;
-      }
-    \`,
-  });
-  await page.evaluate(async () => {
-    await document.fonts.ready;
-    for (let y = 0; y < document.body.scrollHeight; y += window.innerHeight) {
-      window.scrollTo(0, y);
-      await new Promise((r) => setTimeout(r, 60));
-    }
-    window.scrollTo(0, 0);
-  });
-  await page.waitForTimeout(300);
-}
+// Next.js detected: derive both surfaces and the coverage guard from the app's
+// routes AT RUN TIME, so a page added later is in `expected` automatically and
+// fails the guard until it has a surface — no static list to drift.
+const NEXT_SPEC = `import type { Page } from '@playwright/test';
+import { defineStyleMapCapture, discoverNextRoutes, type Surface } from 'styleproof';
+
+${HEADER}
+
+${SETTLE}
+
+// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME — so a page
+// you add later is covered automatically, with no surface list to keep in sync
+// (that drift is exactly what lets a new page ship unverified). Edit freely; this
+// is your spec. Static routes each get a capture; dynamic [param] routes can't be
+// navigated without a value, so they're listed in \`exclude\` until you add a
+// surface with a concrete param.
+const ROUTES = discoverNextRoutes();
+
+const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
+  key: r.key,
+  go: async (page) => {
+    await page.goto(r.path);
+    await settle(page);
+  },
+  ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
+  widths: [1280, 768, 390],
+}));
+
+defineStyleMapCapture({
+  surfaces: SURFACES,
+  // Coverage guard: every known route must be a captured surface or excluded, or
+  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser).
+  // A new page with no surface can't slip through the gate unseen.
+  expected: ROUTES.map((r) => r.key),
+  exclude: Object.fromEntries(
+    ROUTES.filter((r) => r.dynamic).map((r) => [r.key, \`dynamic route (\${r.path}) — add a surface with a concrete param\`]),
+  ),
+  dir: process.env.STYLEMAP_DIR,
+});
+`;
+
+// Non-Next project: one sample surface + a commented guard block to wire to
+// whatever the project uses as a route/view registry.
+const GENERIC_SPEC = `import type { Page } from '@playwright/test';
+import { defineStyleMapCapture, type Surface } from 'styleproof';
+
+${HEADER}
+
+${SETTLE}
 
 const SURFACES: Surface[] = [
   {
     key: 'home',
     go: async (page) => {
-      await page.goto('/', { waitUntil: 'networkidle' });
+      await page.goto('/');
       await settle(page);
     },
     ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
@@ -133,18 +179,44 @@ const SURFACES: Surface[] = [
   // tabs, form errors — anything whose styling you want certified.
 ];
 
-defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
+defineStyleMapCapture({
+  surfaces: SURFACES,
+  // Coverage guard (recommended): declare every route your app knows about so a
+  // newly added page can't ship without a surface. Wire \`expected\` to your route
+  // registry — a routes/views list, your router config, or a glob of your pages —
+  // and StyleProof fails the suite (no STYLEMAP_DIR needed) when a route has no
+  // surface and isn't excluded. (A Next.js app gets this auto-wired; see
+  // \`discoverNextRoutes\` in the README.)
+  //   expected: ROUTES.map((r) => r.id),
+  //   exclude: { checkout: 'auth-gated — fixture pending' },
+  dir: process.env.STYLEMAP_DIR,
+});
 `;
 
 const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 
-// Generated by styleproof-init. Point BASE_URL at a PRODUCTION build of the site
-// to capture — dev servers inject their own styles.
+// Generated by styleproof-init.
+//
+// Capture against a PRODUCTION build, never a dev server. Dev servers (\`next dev\`,
+// \`vite\`, …) JIT-compile each route on first request — slow and TIMING-VARIABLE
+// under parallel CI load, so a capture can settle on the loading state on one run and
+// the loaded state on the next: phantom diffs and self-check flakes. A built-and-served
+// app serves precompiled routes at consistent timing. (StyleProof's settle waits for
+// in-flight data either way, but a production build removes the variance at the source.)
 export default defineConfig({
   timeout: 120_000,
   use: {
     baseURL: process.env.BASE_URL || '${baseUrl}',
   },
+  // Build once, then serve THAT production build for the captures — so you can't
+  // accidentally capture a dev server. Adjust the command to your framework (e.g.
+  // \`vite build && vite preview\`); a server already running locally is reused.
+  webServer: {
+    command: 'npm run build && npm run start',
+    url: process.env.BASE_URL || '${baseUrl}',
+    reuseExistingServer: !process.env.CI,
+    timeout: 600_000, // a cold production build can take a few minutes
+  },
   projects: [{ name: 'chromium', use: { ...devices['Desktop Chrome'] } }],
 });
 `;
@@ -157,11 +229,26 @@ function writeFileSafe(file, contents, { force: f } = {}) {
   return { wrote: true, exists };
 }
 
+// Choose the scaffold: routes-aware when this is a Next.js app with discoverable
+// routes, else the generic one-surface starter.
+const routes = discoverNextRoutes(process.cwd());
+const isNext = routes.length > 0;
+const SPEC = isNext ? NEXT_SPEC : GENERIC_SPEC;
+
 let wroteSomething = false;
 
 const spec = writeFileSafe(specPath, SPEC, { force });
 if (spec.wrote) {
   console.log(`${spec.exists ? 'overwrote' : 'created'} ${specPath}`);
+  if (isNext) {
+    const dynamic = routes.filter((r) => r.dynamic).length;
+    console.log(
+      `  detected ${routes.length} Next.js route(s) — wired surfaces + the \`expected\` coverage guard to them` +
+        (dynamic ? ` (${dynamic} dynamic route(s) excluded pending a concrete param)` : ''),
+    );
+  } else {
+    console.log('  no Next.js routes detected — wrote a starter surface + a commented coverage-guard block');
+  }
   wroteSomething = true;
 } else {
   console.log(`${specPath} already exists — left untouched (use --force to overwrite)`);

package/dist/capture.d.ts

@@ -92,16 +92,24 @@ export type CaptureOptions = {
      * ticker never reads as a change — no manual `ignore` needed. Text-only churn
      * (a clock, "2m ago") never matters: the diff compares computed style, not
      * text. Pass `false` to capture the exact frame `go()` left, or `{ interval,
-     * quietFor, timeout }` (ms) to tune the poll cadence, the no-change window
-     * that counts as settled, and the budget. Note: content that first paints
-     * after a quiet gap longer than `quietFor` can't be waited for without a
-     * signal — settle that in `go()`; anything still moving at `timeout` is
-     * treated as a live region.
+     * quietFor, timeout, waitForRequests }` to tune the poll cadence, the no-change
+     * window that counts as settled, the budget (ms), and the network signal.
+     *
+     * By default the settle is **network-aware** (`waitForRequests: true`): it won't
+     * settle on the brief DOM lull BEFORE a `fetch`/XHR response arrives — it holds
+     * while data requests are in flight (excluding long-lived `EventSource`/WebSocket
+     * streams, which never finish), so late-fetched content is captured loaded, not
+     * mid-load. This is the signal a DOM-quiet window alone lacks: without it, a slow
+     * backend (e.g. a dev server under CI load) settles on the loading state on one run
+     * and the loaded state on the next — a self-check flake. Anything still moving at
+     * `timeout` is treated as a live region. Set `waitForRequests: false` to settle on
+     * DOM quiet alone.
      */
     stabilize?: boolean | {
         interval?: number;
         quietFor?: number;
         timeout?: number;
+        waitForRequests?: boolean;
     };
     /**
      * Capture forced :hover/:focus/:active state deltas (default true). This is
@@ -129,10 +137,34 @@ export type CaptureOptions = {
      * guards styles, since text now participates in change detection.
      */
     captureText?: boolean;
+    /**
+     * Advanced/internal: a getter for the count of in-flight data requests, supplied by
+     * a tracker ({@link trackInflightRequests}) armed BEFORE navigation so the page's own
+     * load fetches are counted by the network-aware settle. `defineStyleMapCapture`
+     * wires this automatically. Omit it for a direct `captureStyleMap` call and the
+     * settle arms its own tracker from capture time — which can't see a request already
+     * in flight when you called it (arm one yourself before `goto` if that matters).
+     */
+    pendingRequests?: () => number;
 };
 /** True if `path` is one of `roots` or a structural descendant of one. Shared by
  *  the capture (excluding live regions) and the diff (skipping them). */
 export declare function isUnder(path: string, roots: string[]): boolean;
+/**
+ * Track in-flight DATA requests on `page` so the network-aware settle can wait for
+ * late-loading content to ARRIVE, not just for the DOM to go briefly quiet (the lull
+ * before a response paints). Long-lived streams (EventSource/WebSocket) never finish,
+ * so they're excluded — their painted state is handled by the live-region pass.
+ *
+ * Attach BEFORE navigation to count the page's OWN load fetches: a request already in
+ * flight when you call `captureStyleMap` fired its `request` event before any listener
+ * attached there, so only a tracker armed earlier (the runner does this before `go()`)
+ * can see it.
+ */
+export declare function trackInflightRequests(page: Page): {
+    pending: () => number;
+    dispose: () => void;
+};
 /**
  * Capture the page's complete style map. Drive the page to the state you want
  * first (navigate, open menus); by default the capture then auto-settles the

package/dist/capture.js

@@ -322,7 +322,7 @@ function changedElementPaths(a, b) {
  * Reuses `capturePage` (motion already frozen by the caller), so only
  * content/layout churn — not an animation frame — keeps it from settling.
  */
-async function stabilizePage(page, ignore, interval, quietFor, timeout, captureText) {
+async function stabilizePage(page, ignore, interval, quietFor, timeout, captureText, pending) {
     // captureText is threaded in so text churn participates in settle detection:
     // a clock/ticker whose text changes (with no style change) keeps the map from
     // settling and is excluded as a live region, exactly as style churn already is.
@@ -340,8 +340,16 @@ async function stabilizePage(page, ignore, interval, quietFor, timeout, captureT
             lastChangeAt = Date.now();
             recent = changed;
         }
+        else if (pending() > 0) {
+            // The DOM is momentarily quiet, but data requests are still in flight — this
+            // is the lull BEFORE the response paints, not a settled state. Hold the quiet
+            // window so we wait for the content to ARRIVE (no live-region path to record;
+            // network activity isn't a mutating element). Long-lived streams are excluded
+            // by the caller, so this can't hang on an SSE that never finishes.
+            lastChangeAt = Date.now();
+        }
         else if (Date.now() - lastChangeAt >= quietFor) {
-            return []; // unchanged for the full quiet window → settled
+            return []; // DOM unchanged AND network idle for the full quiet window → settled
         }
     }
     return recent; // never went quiet for quietFor within budget → still-moving paths are live
@@ -374,19 +382,75 @@ function capturePageTokens() {
     probe.remove();
     return tokens;
 }
+/**
+ * Track in-flight DATA requests on `page` so the network-aware settle can wait for
+ * late-loading content to ARRIVE, not just for the DOM to go briefly quiet (the lull
+ * before a response paints). Long-lived streams (EventSource/WebSocket) never finish,
+ * so they're excluded — their painted state is handled by the live-region pass.
+ *
+ * Attach BEFORE navigation to count the page's OWN load fetches: a request already in
+ * flight when you call `captureStyleMap` fired its `request` event before any listener
+ * attached there, so only a tracker armed earlier (the runner does this before `go()`)
+ * can see it.
+ */
+export function trackInflightRequests(page) {
+    const inflight = new Set();
+    const isStream = (r) => {
+        const t = r.resourceType();
+        return t === 'eventsource' || t === 'websocket';
+    };
+    const onStart = (r) => {
+        if (!isStream(r))
+            inflight.add(r);
+    };
+    const onEnd = (r) => {
+        inflight.delete(r);
+    };
+    page.on('request', onStart);
+    page.on('requestfinished', onEnd);
+    page.on('requestfailed', onEnd);
+    return {
+        pending: () => inflight.size,
+        dispose: () => {
+            page.off('request', onStart);
+            page.off('requestfinished', onEnd);
+            page.off('requestfailed', onEnd);
+        },
+    };
+}
 /** Settle the page and return the paths of live regions to exclude. */
-async function detectVolatile(page, ignore, stabilize, captureText) {
+async function detectVolatile(page, ignore, stabilize, captureText, externalPending) {
     if (stabilize === false)
         return [];
     const opt = typeof stabilize === 'object' ? stabilize : {};
-    const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000, captureText);
-    if (volatile.length) {
-        // eslint-disable-next-line no-console
-        console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
-            'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
-            'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+    const waitForRequests = opt.waitForRequests ?? true;
+    // Prefer the runner's pre-navigation tracker (it counts the page's load fetches);
+    // otherwise arm one here as a fallback for requests that fire after this call.
+    let pending = () => 0;
+    let dispose = () => { };
+    if (waitForRequests) {
+        if (externalPending) {
+            pending = externalPending;
+        }
+        else {
+            const t = trackInflightRequests(page);
+            pending = t.pending;
+            dispose = t.dispose;
+        }
+    }
+    try {
+        const volatile = await stabilizePage(page, ignore, opt.interval || 150, opt.quietFor || 600, opt.timeout || 5000, captureText, pending);
+        if (volatile.length) {
+            // eslint-disable-next-line no-console
+            console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
+                'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
+                'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+        }
+        return volatile;
+    }
+    finally {
+        dispose();
     }
-    return volatile;
 }
 /** Drop live regions (and their subtrees) from the base capture, in Node so the
  *  serialized capturePage stays a pure snapshot. */
@@ -451,7 +515,7 @@ export async function captureStyleMap(page, options = {}) {
     // the same loaded state, and collect any region still changing on its own
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
-    const volatile = await detectVolatile(page, ignore, stabilize, captureText);
+    const volatile = await detectVolatile(page, ignore, stabilize, captureText, options.pendingRequests);
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);

package/dist/coverage.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Coverage guard for the surface list.
+ *
+ * StyleProof captures exactly the surfaces a spec declares, and the diff matches
+ * surfaces by key — so a route nobody added to `surfaces` is invisible to the
+ * gate: the change it introduces has no baseline capture AND no head capture, so
+ * it never appears in any diff. The gate goes green having never looked at it.
+ * This is the one failure StyleProof can't catch from the captures alone, because
+ * it's about a capture that was never taken.
+ *
+ * `expected` closes the hole: a spec declares its full route/surface universe
+ * (e.g. an app's view registry), and the guard fails when that universe drifts
+ * from what's actually captured — turning a silent coverage hole into a red test,
+ * in the app's own suite, the moment the route is added.
+ */
+export type CoverageGaps = {
+    /** Expected surfaces that are neither captured nor explicitly excluded. */
+    uncovered: string[];
+    /** `exclude` entries absent from `expected` — a renamed or removed route whose
+     *  opt-out has gone stale (the same drift, in reverse). */
+    staleExclusions: string[];
+};
+/**
+ * Compare the captured surface keys against a declared `expected` universe.
+ *
+ * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
+ * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
+ * allowed: one route legitimately has several captured states (`landing`,
+ * `landing-nav-open`), and only the routes themselves form the universe.
+ *
+ * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
+ * it in a Playwright test that runs in the normal suite (not gated on a capture
+ * dir), and it's exported so a consumer can assert coverage however it likes.
+ */
+export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;

package/dist/coverage.js

@@ -0,0 +1,35 @@
+/**
+ * Coverage guard for the surface list.
+ *
+ * StyleProof captures exactly the surfaces a spec declares, and the diff matches
+ * surfaces by key — so a route nobody added to `surfaces` is invisible to the
+ * gate: the change it introduces has no baseline capture AND no head capture, so
+ * it never appears in any diff. The gate goes green having never looked at it.
+ * This is the one failure StyleProof can't catch from the captures alone, because
+ * it's about a capture that was never taken.
+ *
+ * `expected` closes the hole: a spec declares its full route/surface universe
+ * (e.g. an app's view registry), and the guard fails when that universe drifts
+ * from what's actually captured — turning a silent coverage hole into a red test,
+ * in the app's own suite, the moment the route is added.
+ */
+/**
+ * Compare the captured surface keys against a declared `expected` universe.
+ *
+ * A surface is covered if it's captured OR listed in `exclude` (a deliberate,
+ * documented opt-out — `key → reason`). Captured surfaces NOT in `expected` are
+ * allowed: one route legitimately has several captured states (`landing`,
+ * `landing-nav-open`), and only the routes themselves form the universe.
+ *
+ * Pure and side-effect-free so it's unit-testable; `defineStyleMapCapture` wraps
+ * it in a Playwright test that runs in the normal suite (not gated on a capture
+ * dir), and it's exported so a consumer can assert coverage however it likes.
+ */
+export function coverageGaps(capturedKeys, expected, exclude = {}) {
+    const captured = new Set(capturedKeys);
+    const expectedList = [...expected];
+    const expectedSet = new Set(expectedList);
+    const uncovered = expectedList.filter((k) => !captured.has(k) && !(k in exclude));
+    const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k));
+    return { uncovered, staleExclusions };
+}

package/dist/index.d.ts

@@ -1,7 +1,11 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
 export type { Surface, DefineOptions } from './runner.js';
+export { coverageGaps } from './coverage.js';
+export type { CoverageGaps } from './coverage.js';
+export { discoverNextRoutes } from './routes.js';
+export type { DiscoveredRoute } from './routes.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export type { Finding, PropChange, SurfaceDiff, DiffCounts, ContentChange } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/index.js

@@ -1,4 +1,6 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export { defineStyleMapCapture } from './runner.js';
+export { coverageGaps } from './coverage.js';
+export { discoverNextRoutes } from './routes.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/routes.d.ts

@@ -0,0 +1,29 @@
+/**
+ * Best-effort route discovery for Next.js projects, so the coverage guard works
+ * out of the box: a generated spec calls this at run time, so `expected` reflects
+ * the app's *current* routes — a newly added page appears automatically, and the
+ * guard fails until it has a surface. No static list to keep in sync (that drift
+ * is the whole bug the guard exists to prevent).
+ *
+ * Covers the App Router (`app/`, `src/app/` — directories with a `page.*`) and the
+ * Pages Router (`pages/`, `src/pages/` — page files, minus `_app`/`_document`/`api`).
+ * Route groups `(group)` and parallel slots `@slot` are stripped; `[param]` /
+ * `[...catchall]` segments mark a route dynamic. It reads the filesystem only —
+ * no framework internals — so it's a heuristic, not a router; edit the generated
+ * spec if your routing does something exotic.
+ */
+export type DiscoveredRoute = {
+    /** Filename-safe surface key (`/` → `index`, `/blog/[slug]` → `blog-slug`). */
+    key: string;
+    /** URL path to navigate (`/`, `/about`, `/blog/[slug]`). */
+    path: string;
+    /** True when a segment is a `[param]` / `[...catchall]` — can't be navigated as-is. */
+    dynamic: boolean;
+};
+/**
+ * Discover a Next.js project's routes under `cwd` (default `process.cwd()`).
+ * Returns one entry per route, deduped by path (App Router wins a tie) and sorted.
+ * Empty array when no `app/` or `pages/` dir is found — the caller decides whether
+ * that means "not a Next project".
+ */
+export declare function discoverNextRoutes(cwd?: string): DiscoveredRoute[];

package/dist/routes.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const APP_PAGE_RE = /^page\.(?:js|jsx|ts|tsx|mdx)$/;
+const PAGES_EXT_RE = /\.(?:js|jsx|ts|tsx)$/;
+const isGroupOrSlot = (seg) => /^\(.*\)$/.test(seg) || seg.startsWith('@');
+const isDynamicSeg = (seg) => /\[.*\]/.test(seg);
+/** Filename-safe, readable key from a route path. */
+function toKey(routePath) {
+    if (routePath === '/')
+        return 'index';
+    const k = routePath
+        .replace(/^\//, '')
+        .replace(/\[\[?\.\.\.([^\]]+)\]\]?/g, 'all-$1') // [...x] / [[...x]] → all-x
+        .replace(/\[([^\]]+)\]/g, '$1') // [x] → x
+        .replace(/[^a-zA-Z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .toLowerCase();
+    return k || 'index';
+}
+function makeRoute(segs) {
+    const routePath = segs.length ? '/' + segs.join('/') : '/';
+    return { key: toKey(routePath), path: routePath, dynamic: segs.some(isDynamicSeg) };
+}
+function readDir(dir) {
+    try {
+        return fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return []; // missing/unreadable dir → no routes, never throw into a spec
+    }
+}
+/** App Router: a directory holding a `page.*` is a route; nest by sub-directory. */
+function appRoutes(appDir) {
+    const out = [];
+    const walk = (dir, segs) => {
+        const entries = readDir(dir);
+        if (entries.some((e) => e.isFile() && APP_PAGE_RE.test(e.name))) {
+            out.push(makeRoute(segs.filter((s) => !isGroupOrSlot(s))));
+        }
+        for (const e of entries)
+            if (e.isDirectory())
+                walk(path.join(dir, e.name), [...segs, e.name]);
+    };
+    walk(appDir, []);
+    return out;
+}
+/** Pages Router: each page file is a route; `index` collapses to its directory. */
+function pagesRoutes(pagesDir) {
+    const out = [];
+    const walk = (dir, segs) => {
+        for (const e of readDir(dir)) {
+            if (e.isDirectory()) {
+                if (segs.length === 0 && e.name === 'api')
+                    continue; // API routes aren't pages
+                walk(path.join(dir, e.name), [...segs, e.name]);
+            }
+            else if (e.isFile() && PAGES_EXT_RE.test(e.name)) {
+                const base = e.name.replace(PAGES_EXT_RE, '');
+                if (base.startsWith('_'))
+                    continue; // _app, _document, _error
+                out.push(makeRoute(base === 'index' ? segs : [...segs, base]));
+            }
+        }
+    };
+    walk(pagesDir, []);
+    return out;
+}
+const firstExisting = (cwd, candidates) => candidates.map((d) => path.join(cwd, d)).find((p) => fs.existsSync(p));
+/**
+ * Discover a Next.js project's routes under `cwd` (default `process.cwd()`).
+ * Returns one entry per route, deduped by path (App Router wins a tie) and sorted.
+ * Empty array when no `app/` or `pages/` dir is found — the caller decides whether
+ * that means "not a Next project".
+ */
+export function discoverNextRoutes(cwd = process.cwd()) {
+    const appDir = firstExisting(cwd, ['app', 'src/app']);
+    const pagesDir = firstExisting(cwd, ['pages', 'src/pages']);
+    const found = [...(appDir ? appRoutes(appDir) : []), ...(pagesDir ? pagesRoutes(pagesDir) : [])];
+    const byPath = new Map();
+    for (const r of found)
+        if (!byPath.has(r.path))
+            byPath.set(r.path, r);
+    return [...byPath.values()].sort((a, b) => a.path.localeCompare(b.path));
+}

package/dist/runner.d.ts

@@ -7,7 +7,11 @@ import type { Page } from '@playwright/test';
 export type Surface = {
     /** Capture file name prefix; must be unique. */
     key: string;
-    /** Navigate and drive the page to the state, ending settled (fonts loaded, entrance animations done). */
+    /**
+     * Navigate and drive the page to the state. Only reach the state — StyleProof
+     * settles it for you (waits out in-flight data and fonts, freezes animations)
+     * before reading, so you don't hand-roll `networkidle`/`fonts.ready` waits here.
+     */
     go: (page: Page) => Promise<void>;
     /** Selectors for nondeterministic regions (live data, third-party embeds); skipped entirely. */
     ignore?: string[];
@@ -18,6 +22,23 @@ export type Surface = {
 };
 export type DefineOptions = {
     surfaces: Surface[];
+    /**
+     * The full set of surface keys the app knows it has — its route/view universe,
+     * typically derived from a registry (e.g. an app's list of routes or view ids).
+     * When set, StyleProof emits a coverage-guard test (in the NORMAL suite, not
+     * gated on a capture dir) that fails if any expected key is neither captured (a
+     * surface) nor in `exclude`. This is what stops a newly added route from
+     * shipping uncaptured: the gate can only diff what a spec lists, so without this
+     * a forgotten surface is silently invisible. Omit to opt out (no guard).
+     */
+    expected?: string[];
+    /**
+     * Expected keys deliberately NOT captured, each mapped to the reason — a visible,
+     * reviewed opt-out ledger. Keeps the coverage guard green for known gaps without
+     * letting them hide: an entry whose key isn't in `expected` (a renamed/removed
+     * route) also fails the guard, so the ledger can't rot.
+     */
+    exclude?: Record<string, string>;
     /**
      * Output directory label. Convention: drive it from an env var so the same
      * spec captures `before`, `after`, or a CI label — and skips entirely when
@@ -58,10 +79,16 @@ export type DefineOptions = {
     /** Fixed instant for the frozen clock (default `2025-01-01T00:00:00Z`). */
     clockTime?: string | number | Date;
     /**
-     * Capture each surface twice and fail if the computed styles differ — proves
-     * the capture is deterministic (catches a replay gap falling through to the
-     * live backend, or unseeded client randomness) instead of letting it surface
-     * as a phantom change on an unrelated diff. Default from STYLEPROOF_SELFCHECK=1.
+     * Capture each surface twice and fail if the computed styles differ — proves the
+     * capture is deterministic (catches a replay gap falling through to the live
+     * backend, or unseeded client randomness) instead of letting it surface as a
+     * phantom change on an unrelated diff.
+     *
+     * Defaults ON for the RECORDING run and OFF for the REPLAY run: live nondeterminism
+     * surfaces while recording against the real backend, whereas the replay run renders
+     * against the recorded HAR and is deterministic by construction — so self-checking it
+     * just doubles the work. `STYLEPROOF_SELFCHECK=1` forces it on for both; pass
+     * `selfCheck` explicitly to override.
      */
     selfCheck?: boolean;
     /**
@@ -87,6 +114,14 @@ export type DefineOptions = {
  * recently added route first); non-stream requests `fallback()` to the HAR.
  */
 export declare function passLiveStreams(page: Page, url: string): Promise<void>;
+/**
+ * Default for `selfCheck` when the consumer didn't set it: ON when RECORDING (no
+ * `replayFrom`) — that's where live nondeterminism surfaces — and OFF when REPLAYING,
+ * since the replay run renders against the recorded HAR and is deterministic by
+ * construction, so self-checking it just doubles the work. `STYLEPROOF_SELFCHECK=1`
+ * forces it on either way.
+ */
+export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -100,4 +135,4 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export declare function defineStyleMapCapture({ surfaces, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;
+export declare function defineStyleMapCapture({ surfaces, expected, exclude, dir, baseDir, screenshots, replayFrom, replayUrl, freezeClock, clockTime, selfCheck, captureText, }: DefineOptions): void;

package/dist/runner.js

@@ -1,8 +1,9 @@
-import { test } from '@playwright/test';
+import { test, expect } from '@playwright/test';
 import fs from 'node:fs';
 import path from 'node:path';
-import { captureStyleMap, saveStyleMap } from './capture.js';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { diffStyleMaps } from './diff.js';
+import { coverageGaps } from './coverage.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
     if (f.kind === 'dom')
@@ -69,9 +70,9 @@ async function pinInputs(page, harName, s) {
         await page.clock.setFixedTime(new Date(s.clockTime));
 }
 /** Capture the surface again and throw if the computed styles drifted from `first`. */
-async function assertDeterministic(page, surface, first, captureText) {
+async function assertDeterministic(page, surface, first, captureText, pending) {
     await surface.go(page);
-    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText });
+    const again = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText, pendingRequests: pending });
     const drift = diffStyleMaps(first, again);
     if (drift.length) {
         throw new Error(`styleproof self-check failed: ${surface.key} is non-deterministic — ` +
@@ -86,18 +87,41 @@ async function captureSurface(page, surface, width, s) {
     await pinInputs(page, `${surface.key}@${width}.har`, s);
     const height = typeof surface.height === 'function' ? surface.height(width) : (surface.height ?? 800);
     await page.setViewportSize({ width, height });
-    await surface.go(page);
-    const map = await captureStyleMap(page, { ignore: surface.ignore ?? [], captureText: s.captureText });
-    if (s.selfCheck)
-        await assertDeterministic(page, surface, map, s.captureText);
-    const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
-    saveStyleMap(`${stem}.json.gz`, map);
-    if (s.screenshots) {
-        // captureStyleMap froze animations/transitions, so this is the same settled
-        // state the map describes.
-        await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
+    // Arm the in-flight request tracker BEFORE go() so the surface's own load fetches
+    // count toward the network-aware settle — a request that starts during navigation
+    // fired its event before captureStyleMap could attach a listener of its own.
+    const requests = trackInflightRequests(page);
+    try {
+        await surface.go(page);
+        const map = await captureStyleMap(page, {
+            ignore: surface.ignore ?? [],
+            captureText: s.captureText,
+            pendingRequests: requests.pending,
+        });
+        if (s.selfCheck)
+            await assertDeterministic(page, surface, map, s.captureText, requests.pending);
+        const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
+        saveStyleMap(`${stem}.json.gz`, map);
+        if (s.screenshots) {
+            // captureStyleMap froze animations/transitions, so this is the same settled
+            // state the map describes.
+            await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
+        }
+    }
+    finally {
+        requests.dispose();
     }
 }
+/**
+ * Default for `selfCheck` when the consumer didn't set it: ON when RECORDING (no
+ * `replayFrom`) — that's where live nondeterminism surfaces — and OFF when REPLAYING,
+ * since the replay run renders against the recorded HAR and is deterministic by
+ * construction, so self-checking it just doubles the work. `STYLEPROOF_SELFCHECK=1`
+ * forces it on either way.
+ */
+export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
+    return env === '1' || !replayFrom;
+}
 /**
  * Generate one Playwright test per surface × width that captures the style
  * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
@@ -111,8 +135,7 @@ async function captureSurface(page, surface, width, s) {
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
-export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = process.env.STYLEPROOF_SELFCHECK === '1', captureText = false, }) {
-    test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
+export function defineStyleMapCapture({ surfaces, expected, exclude = {}, dir, baseDir = '__stylemaps__', screenshots = true, replayFrom = process.env.STYLEPROOF_REPLAY_FROM, replayUrl = process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**', freezeClock = true, clockTime = '2025-01-01T00:00:00Z', selfCheck = defaultSelfCheck(replayFrom), captureText = false, }) {
     const settings = {
         dir: dir,
         baseDir,
@@ -124,7 +147,25 @@ export function defineStyleMapCapture({ surfaces, dir, baseDir = '__stylemaps__'
         selfCheck,
         captureText,
     };
+    // Coverage guard. Runs in the NORMAL test suite (NOT gated on a capture dir), so
+    // a route added without a surface fails the app's own tests — long before, and
+    // independent of, a capture run. This is the one gap captures can't catch: a
+    // surface never taken can't be diffed. Only emitted when the spec declares its
+    // `expected` universe; otherwise StyleProof keeps its prior behaviour exactly.
+    if (expected) {
+        test.describe('styleproof coverage', () => {
+            test('every expected surface is captured or explicitly excluded', () => {
+                const { uncovered, staleExclusions } = coverageGaps(surfaces.map((s) => s.key), expected, exclude);
+                expect(uncovered, `StyleProof coverage gap: ${uncovered.length} expected surface(s) are neither captured ` +
+                    `nor excluded — add each to \`surfaces\`, or to \`exclude\` with a reason. ` +
+                    `Missing: ${uncovered.join(', ')}`).toEqual([]);
+                expect(staleExclusions, `StyleProof: \`exclude\` lists surface(s) absent from \`expected\` ` +
+                    `(renamed or removed?): ${staleExclusions.join(', ')}`).toEqual([]);
+            });
+        });
+    }
     test.describe('styleproof capture', () => {
+        test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         for (const surface of surfaces) {
             for (const width of surface.widths) {
                 test(`${surface.key} @ ${width}`, ({ page }) => captureSurface(page, surface, width, settings));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",