styleproof 2.0.0 → 2.2.0

package/CHANGELOG.md

@@ -7,6 +7,84 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.2.0] - 2026-06-23
+
+### Added
+
+- **Newly-added elements now report their full resting computed style**, not just
+  interaction-state deltas. Previously an added element surfaced only its
+  `:hover`/`:focus` changes (the diff short-circuited added elements before the
+  style loop); its background, padding, font, radius, etc. were captured but never
+  shown. The diff now emits the new element's full style as `(unset) → value`
+  findings and the report renders them value-only (no bogus "Before" column), in
+  both the PR report and the `styleproof-diff` CLI. The element already gated via
+  its `added` finding, so this enriches detail without changing what gates.
+- **`captureComponent` (opt-in, default off): surface the React component + props**
+  behind each element. With it on, capture reads the React fiber in-page
+  (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on
+  ≤16) to record the component display name and a sanitized subset of its props
+  (primitives only; `children`/handlers/objects dropped) on `ElementEntry.component`.
+  The report names it — `React component: Button (variant=primary, size=sm)` —
+  instead of a bare `<button>`. **Advisory only**, exactly like the content layer:
+  never fed to the certification diff or its blocking counts, so captures stay
+  deterministic. Names are mangled in minified prod builds, so it's most useful
+  against dev/non-minified output; a no-op on non-React pages.
+
+## [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)
 
@@ -168,6 +228,23 @@ The report then carries a separate **📝 Content changes (advisory)** section:
 
 Notes: only an element's _own_ text is recorded (so a parent and child never double-report the same string); text churn in a live region is auto-excluded by the same settle pass that guards styles; and the certification CLI (`styleproof-diff`) is deliberately left content-blind.
 
+## Optional: React component layer (advisory)
+
+For a React app, knowing _which component_ rendered an element is often the fastest way to read a change. Off by default, opt in with `captureComponent`:
+
+```ts
+// styleproof.spec.ts — record the React component + props behind each element
+defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR, captureComponent: true });
+```
+
+Capture reads the React fiber in-page (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*` on ≤16) and records the component display name plus a **sanitized** subset of its props (primitives only — `children`, handlers, and objects are dropped) on `ElementEntry.component`. The report then names the element — **`React component: Button (variant=primary, size=sm)`** — instead of showing a bare `<button>`.
+
+Like the content layer it is **advisory**: never fed to the certification diff or the gate, so captures stay deterministic. Component names are mangled in minified production builds, so it's most useful against a dev / non-minified target; on a non-React page the fiber keys are absent and the field is simply omitted.
+
+## Newly-added elements show their full style
+
+When a PR **adds** an element, StyleProof now reports its **full resting computed style** (background, padding, font, radius, …), value-only, in addition to any interaction-state deltas — previously an added element surfaced only its `:hover`/`:focus` changes. The new element already gates via its `added` finding; this only enriches what you see, in both the report and the `styleproof-diff` CLI.
+
 ## Reference
 
 **Action `BenSheridanEdwards/StyleProof@v2`** — key inputs:
@@ -200,17 +277,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 +304,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

@@ -42,6 +42,18 @@ export type ElementEntry = {
      * advisory, not a computed-style outcome. See README "Optional: content layer".
      */
     text?: string;
+    /**
+     * The React component that rendered this element, and a sanitized subset of its
+     * props — present only when capture ran with `captureComponent: true` (opt-in,
+     * off by default). Extracted in-page from the React fiber. ADVISORY: never fed
+     * to the certification diff or its counts (like {@link ElementEntry.text}); it
+     * only enriches the report so a reviewer sees `Button (variant=primary)` rather
+     * than a bare `<button>`. Best in dev/non-minified builds (prod mangles names).
+     */
+    component?: {
+        name: string;
+        props?: Record<string, string>;
+    };
 };
 export type StyleMap = {
     defaults: Record<string, Props>;
@@ -92,16 +104,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 +149,47 @@ export type CaptureOptions = {
      * guards styles, since text now participates in change detection.
      */
     captureText?: boolean;
+    /**
+     * Opt-in React layer (default OFF). When true, each element records the React
+     * component that rendered it (display name) and a sanitized subset of its props
+     * on {@link ElementEntry.component}, read in-page from the React fiber
+     * (`__reactFiber$*`/`__reactProps$*` on React 17+, `__reactInternalInstance$*`
+     * on ≤16). Lets the report name `Button (variant=primary)` instead of a bare
+     * `<button>`. ADVISORY — like `captureText` it never feeds the certification
+     * diff or its blocking counts. Only primitive props (string/number/boolean) are
+     * kept (children/handlers/objects dropped); names are mangled in minified prod
+     * builds, so this is most useful against dev/non-minified output. No-op on
+     * non-React pages (fiber keys absent → field omitted).
+     */
+    captureComponent?: 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