styleproof 2.5.0 → 3.0.1

package/CHANGELOG.md

@@ -7,6 +7,63 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.0.1] - 2026-06-27
+
+### Added
+
+- **First-class live states plus generic variants.** `Surface` now accepts
+  `liveStates`, each captured as `<surface>-<state>` with optional `setup`, `go`,
+  `widths`, `height`, and `ignore` overrides. This lets a spec certify both
+  `loading` and `loaded` (or `empty` / `error`) on the base branch and feature
+  branch, then compare matching states directly instead of relying on one moving
+  live page state. Reports label those captures as live states. Generic `variants`
+  remain available for non-live states such as nav-open or modal-open. `defineCrawlCapture`
+  accepts both and applies them to every discovered link surface.
+- **Semantic live-state candidates are auto-detected.** Captures now record
+  diagnostic metadata for `[aria-live]`, implicit live-region roles such as
+  `role=status` / `role=alert`, and `aria-busy=true`. Stable candidates are still
+  captured and compared by default; only regions that actually keep changing are
+  excluded as volatile.
+
+### Changed
+
+- **Self-check diagnostics now call out volatile root layout drift.** When a
+  capture contains volatile regions and the repeated self-check differs on
+  `html`/`body` layout properties, the error explains that ignored/live content can
+  still move document flow, includes any auto-detected live-state candidates, and
+  points users to deterministic `liveStates`.
+- **Release proof now matches CI before publishing.** The release workflow and
+  `prepublishOnly` gate now include format checking plus browser e2e coverage before
+  npm publication, so a version cannot publish ahead of the full package proof gate.
+
+### Fixed
+
+- **The composite Action now executes the checked-out Action version.** Report jobs
+  install StyleProof's runtime dependencies under `GITHUB_ACTION_PATH` and invoke the
+  local `bin/styleproof-*` entrypoints, so `uses: BenSheridanEdwards/StyleProof@v3`
+  cannot drift to a consumer workspace install or npm's latest package.
+
+## [3.0.0] - 2026-06-27
+
+**Milestone: the committed-map gate is how StyleProof works now.** Capture runs
+**pre-push** (parallel, with auto-detected `@media` breakpoints), the lean computed-
+style map is committed and **pushed in a single `git push`**, and CI is a
+**browser-less diff** of two precomputed maps — measured ~5400× cheaper on the
+compare step, and it skips build + serve entirely. `styleproof-init` scaffolds **and
+activates** the whole gate in one command. Coverage stays **full and sound**: every
+surface is captured (parallelised) and what changed is determined by _measuring_ the
+map, never by guessing which pages a code change touched. **No breaking API changes**
+— existing specs and the classic capture-both-in-CI flow keep working unchanged; the
+major marks the new default paradigm.
+
+### Changed
+
+- **`styleproof-init` now activates the pre-push hook for you** (`git config
+core.hooksPath .githooks`), so a single `styleproof-init` is all it takes — no
+  follow-up command. It never clobbers a repo that already manages hooks: if
+  `core.hooksPath` is already set or a `.husky/` dir exists, it leaves them alone and
+  prints the one-liner instead.
+
 ## [2.5.0] - 2026-06-26
 
 ### Changed
@@ -773,7 +830,30 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.2.0...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.1...HEAD
+[3.0.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.0...v3.0.1
+[3.0.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.5.0...v3.0.0
+[2.5.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.4.0...v2.5.0
+[2.4.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.3.1...v2.4.0
+[2.3.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.3.0...v2.3.1
+[2.3.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.2.0...v2.3.0
+[2.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.1.0...v2.2.0
+[2.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.0.0...v2.1.0
+[2.0.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.10.0...v2.0.0
+[1.10.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.9.4...v1.10.0
+[1.9.4]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.9.3...v1.9.4
+[1.9.3]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.9.2...v1.9.3
+[1.9.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.9.0...v1.9.1
+[1.9.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.8.1...v1.9.0
+[1.8.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.8.0...v1.8.1
+[1.8.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.7.2...v1.8.0
+[1.7.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.7.1...v1.7.2
+[1.7.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.6.0...v1.7.0
+[1.6.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.5.0...v1.6.0
+[1.5.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.4.0...v1.5.0
+[1.4.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.3.1...v1.4.0
+[1.3.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.2.0...v1.3.0
 [1.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.1.0...v1.2.0
 [1.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v0.7.0...v1.0.0

package/README.md

@@ -12,12 +12,12 @@ Pixel-snapshot tools miss most CSS regressions: they can't force `:hover` / `:fo
 
 ## What the gate does
 
-On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base branch, diffs them, and posts a Markdown comment:
+On every PR, StyleProof diffs the PR head's computed-style map against the base branch's, and posts a Markdown comment:
 
 - A **lean summary comment** linking to a committed side-by-side report — the report is the complete source of truth (**one section per distinct change**, with a before/after cropped screenshot cropped from the same rectangle so the two sides line up exactly, **plain-English bullets that tell you what to look for** — `columns: 2 → 3`, `recoloured cyan → amber` — and the exact property changes). The comment never duplicates the report, so the two can't drift, and it renders identically on public and private repos.
 - A single **Approve all changes** checkbox in the comment, driving a `StyleProof` commit status: red until one tick signs off every change, green when there are none. The reviewer who ticks it is recorded inline (_approved by @them_), sourced from the commit status so it survives a report re-run.
 - **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_.
+- The diff is always **head-vs-base**, so the report is _exactly what this PR changes_ — whether the maps are captured fresh in CI or (by default) committed pre-push and diffed browser-free in CI. See [Quickstart](#quickstart).
 
 ## Don't let a new page ship uncaptured
 
@@ -79,6 +79,42 @@ defineCrawlCapture({
 
 Each discovered link becomes a surface keyed by its URL (`/?tab=overview` → `overview`; pass `key` for a different scheme). The app only has to render its nav as real `<a href>` links — a button-only nav (`<button onClick>`) exposes nothing to crawl. Replay, self-check and clock-freeze behave exactly as for explicit surfaces; one Playwright test runs the whole sweep (the link set isn't known until the page renders).
 
+**Live UI states: capture each state, not an average.** StyleProof automatically
+detects semantic live-state candidates (`aria-live`, `role=status`, `role=alert`,
+`aria-busy=true`) and keeps stable ones in the normal diff. If a stream, poll, or
+live region represents product states you want certified (`loading`, `loaded`,
+`empty`, `error`), list only those pinned states with `liveStates`. StyleProof
+writes separate captures such as `dashboard-loading@1440` and
+`dashboard-loaded@1440`, so the base branch's loading state compares to the
+feature branch's loading state, and loaded compares to loaded.
+
+```ts
+defineStyleMapCapture({
+  dir: process.env.STYLEMAP_DIR,
+  surfaces: [
+    {
+      key: 'dashboard',
+      go: (page) => page.goto('/dashboard'),
+      widths: [1440, 768],
+      liveStates: [
+        {
+          key: 'loading',
+          setup: (page) =>
+            page.route('**/api/widgets', (route) => route.fulfill({ json: { status: 'loading', widgets: [] } })),
+        },
+        {
+          key: 'loaded',
+          setup: (page) =>
+            page.route('**/api/widgets', (route) =>
+              route.fulfill({ json: { status: 'loaded', widgets: [{ label: 'Revenue' }] } }),
+            ),
+        },
+      ],
+    },
+  ],
+});
+```
+
 ## What a report looks like
 
 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.
@@ -102,6 +138,10 @@ _landing @ 1280_
 
 StyleProof reads the browser's **computed styles** — the values it actually resolves — never your source CSS. Tailwind, CSS Modules, styled-components, Sass, vanilla CSS, inline styles: all produce the same computed output, and that's what it diffs. Elements are keyed by **DOM structure, not class name**, so a refactor that rewrites every `class` still lines up element-for-element.
 
+## Breakpoints, detected automatically
+
+Omit `widths` on a surface and StyleProof reads your app's real `@media` breakpoints from the **loaded CSSOM** at capture time and sweeps one viewport per band — no config. It's framework-agnostic for the same reason the diff is: it reads the rules the browser actually parsed, not your source, so Tailwind / CSS Modules / Sass / vanilla all resolve to the same `@media` boundaries. And it's authoritative **or it fails** — an unreadable cross-origin stylesheet throws rather than silently miss a band; it never guesses. Pin `widths` explicitly when you want a fixed sweep, or to cover a JS-only (`matchMedia`) breakpoint that has no CSS rule.
+
 ## Certify a refactor
 
 The same engine has a second mode that proves a change touched _nothing_ visual: with `fail-on-diff: true`, any difference at all fails the job. It's the job StyleProof was born for — certifying a CSS-to-Tailwind migration rendered byte-for-byte identical. Reach for it on any change whose whole promise is "the output is unchanged": a utility-class migration, a design-system swap, a dependency or build-tooling bump. Zero diff is the contract; one drifting longhand is a regression to investigate, not a change to approve.
@@ -117,70 +157,60 @@ Requires **Node ≥ 18** (ESM), **`@playwright/test` ≥ 1.40** (peer dep). Forc
 
 ## Quickstart
 
-**1. Scaffold the capture spec** (`npx styleproof-init` writes `e2e/styleproof.spec.ts`), then describe your surfaces:
+After installing (above), one command sets up — and **activates** — the whole gate:
+
+```bash
+npx styleproof-init
+```
+
+It scaffolds:
+
+- a **capture spec** (`e2e/styleproof.spec.ts`) describing your surfaces (a Next.js app gets its routes _and_ the coverage guard wired automatically — see below);
+- a **`playwright.config.ts`** that builds and serves a **production build** (never a flaky dev server) and captures surfaces **in parallel** (`fullyParallel`);
+- a **pre-push hook** (`.githooks/pre-push`, activated for you via `core.hooksPath` — it won't clobber an existing husky setup) that captures the map, commits it as a lean `.json.gz` under `stylemaps/`, and **pushes it with your branch — one `git push`, never two**;
+- a **browser-less CI workflow** that diffs your committed map against the base branch.
+
+Describe your surfaces — **omit `widths`** and StyleProof sweeps your real `@media` breakpoints automatically:
 
 ```ts
 import { defineStyleMapCapture } from 'styleproof';
 
 defineStyleMapCapture({
-  dir: process.env.STYLEMAP_DIR, // inert until set, so it lives safely beside other tests
   surfaces: [
     {
       key: 'landing',
-      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
+      go: (page) => page.goto('/'), // StyleProof settles the page (in-flight data, fonts, animations) before it reads
+      // no `widths` → auto-detected from your @media bands; set `widths: [1280, 768, 390]` to pin them
     },
   ],
+  dir: process.env.STYLEMAP_DIR,
 });
 ```
 
-**2. Wire CI to capture base and head, then hand both to the Action:**
+**That's the whole loop.** Capture happens **pre-push on your machine** (where the app already builds and serves); the lean map is committed and pushed; and **CI is a browser-less diff of two precomputed maps** — no build, no browser, just a fast comparison (~5400× cheaper on the compare step than re-capturing both sides in CI). `main` always carries a base map, so every PR is _your code vs the committed base_. Require the `StyleProof` status in branch protection and an unverified visual change can't merge.
+
+> **Same-environment note.** Computed styles depend on the browser build and installed fonts, so maps are only comparable when captured in the same environment (your machine, or a pinned container). The self-check fails loudly on a non-deterministic capture, so drift never passes silently.
+
+**Want the side-by-side report + one-click approval** (not just a pass/fail diff)? Use the Action, pointing it at the base ref:
 
 ```yaml
 # .github/workflows/styleproof.yml
-name: StyleProof
-on: pull_request
-
-jobs:
-  styleproof:
-    runs-on: ubuntu-latest
-    permissions:
-      contents: write # push the report branch
-      pull-requests: write # post/update the comment
-      statuses: write # set the StyleProof status
-    steps:
-      - uses: actions/checkout@v4
-        with:
-          fetch-depth: 0 # need the base branch too
-
-      # capture the base branch
-      - run: git checkout ${{ github.event.pull_request.base.sha }}
-      - run: npm ci && npm run build && (npm run serve &) # your framework's build + serve
-      - run: npx wait-on http://localhost:3000
-      - run: STYLEMAP_DIR=base npx playwright test e2e/styleproof.spec.ts
-
-      # capture the PR head — replay the base's recorded data so the diff is
-      # code, not live-data drift (see "Deterministic by default" below)
-      - run: git checkout ${{ github.event.pull_request.head.sha }}
-      - run: npm ci && npm run build && (npm run serve &)
-      - run: npx wait-on http://localhost:3000
-      - run: STYLEMAP_DIR=head STYLEPROOF_REPLAY_FROM=__stylemaps__/base npx playwright test e2e/styleproof.spec.ts
-
-      # report + gate
-      - uses: BenSheridanEdwards/StyleProof@v2
-        with:
-          baseline-dir: __stylemaps__/base # captures land under baseDir (default __stylemaps__)
-          fresh-dir: __stylemaps__/head
-          require-approval: true # review-gate mode (omit / use fail-on-diff: true to certify)
+- uses: actions/checkout@v4
+  with: { fetch-depth: 0 } # need the base ref's committed map
+- uses: BenSheridanEdwards/StyleProof@v3
+  with:
+    base-ref: origin/${{ github.event.pull_request.base.ref }} # read the base map from git
+    fresh-dir: stylemaps/current # your committed maps
+    require-approval: true # review-gate mode (omit / use fail-on-diff: true to certify)
 ```
 
-**3. Copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/example/styleproof-approve.yml) to `.github/workflows/` on your default branch** — GitHub only runs `issue_comment` workflows from there, so the checkboxes do nothing until it's merged.
+Then copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/example/styleproof-approve.yml) to `.github/workflows/` **on your default branch** (GitHub only runs `issue_comment` workflows from there, so the approval checkbox is inert until it's merged).
 
-**4. Require the `StyleProof` status** in branch protection. Now an unsigned visual change can't merge.
+**Prefer to capture in CI instead of committing maps?** For a repo with many outside contributors on different machines, StyleProof can capture **both** base and head in CI and diff them there — no committed maps. See **[Forks and Dependabot](#forks-and-dependabot)** for that flow (it's also the fork-safe split). The committed-map flow above is the default because it's far faster and simpler for a single team.
 
 ## Forks and Dependabot
 
-The single-workflow setup above runs the whole gate in one `pull_request` job — which needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
+If you **capture in CI** rather than committing maps (the alternative noted at the end of the Quickstart — a better fit when many outside contributors push from different machines), the simplest setup runs the whole gate in one `pull_request` job that captures base + head and diffs them. That job needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
 
 Fix it by splitting capture from reporting, the way the approve workflow is already split out:
 
@@ -191,18 +221,20 @@ That last point is why this works where `pull_request_target` does not: StylePro
 
 **Where the PR identity comes from.** The report stage comments on the PR and sets the `StyleProof` status against a specific PR number and head commit, so those values have to be trustworthy. It takes them from the trusted `workflow_run` event — `head_sha`, then the event's `pull_requests`, with a commit→PR lookup against that **same trusted head SHA** for fork PRs (whose association the event doesn't carry directly) — and **never** from the downloaded artifact. The artifact is produced by the untrusted capture job, so treating anything in it as identity would let a malicious PR point the privileged comment and status at a victim PR or an arbitrary commit (a confused-deputy attack). The artifact therefore carries only the style-map captures, consumed purely as diff input.
 
-Copy both `capture` and `report` files to `.github/workflows/` (the `report` one must be on your default branch, like `styleproof-approve.yml`), then require the `StyleProof` status as in step 4. The single-job `styleproof.yml` above remains fine for repos that never see fork or bot PRs.
+Copy both `capture` and `report` files to `.github/workflows/` (the `report` one must be on your default branch, like `styleproof-approve.yml`), then require the `StyleProof` status in branch protection. A single combined `pull_request` job that captures base + head and diffs them is fine for repos that never see fork or bot PRs; this split is only needed for untrusted PRs.
 
 **Deterministic by default — no fixtures required.** A style diff only means something if both sides saw the same inputs; otherwise live-data drift (a backend blip, a `5m ago` timestamp, a status chip that flips) reads as a style change on a PR that touched no CSS. StyleProof handles this for you:
 
-- **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`.
+- **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>` (set on the head capture); 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** — 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, 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 } }`.
+**Live pages just work when the intended state is deterministic.** 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 volatile region and excluded from direct element comparison, so a stream or ticker never reads as a change just because its value changed. That is not the same as certifying every state of the live UI: an ignored or volatile subtree can still change `html`/`body` layout if its height changes. When those states matter, make them deterministic `liveStates` (`loading`, `loaded`, `empty`, `error`) and capture each on both branches. Self-check and reports automatically mention detected live-state candidates when volatile layout drift appears. `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:
 
@@ -212,7 +244,8 @@ Copy both `capture` and `report` files to `.github/workflows/` (the `report` one
 | 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                                 |
+| Semantic live-state candidates (`aria-live`, `role=status`) | auto-detected and kept in the diff when stable                                           |
+| Live / volatile regions (tickers, third-party embeds)       | auto-detected as still-moving and excluded from direct element comparison                |
 | 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                                                                                                                                                                                                    |
@@ -220,6 +253,8 @@ Copy both `capture` and `report` files to `.github/workflows/` (the `report` one
 | `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.                                                                           |
+| `liveStates: [{ key, setup, go }]`            | A live feature has real states to certify. Capture each state on base and head (`surface-loading`, `surface-loaded`) instead of relying on a single moving page state.                                           |
+| `variants: [{ key, setup, go }]`              | Non-live deterministic variants, such as nav-open or modal-open states.                                                                                                                                          |
 | `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.                                                                                                                                    |
 
@@ -262,15 +297,16 @@ When a PR **adds** an element, StyleProof now reports its **full resting compute
 
 ## Reference
 
-**Action `BenSheridanEdwards/StyleProof@v2`** — key inputs:
+**Action `BenSheridanEdwards/StyleProof@v3`** — key inputs:
 
-| Input              | Default      | Purpose                                                                    |
-| ------------------ | ------------ | -------------------------------------------------------------------------- |
-| `baseline-dir`     | _required_   | Base-branch captures.                                                      |
-| `fresh-dir`        | _required_   | PR-head captures to compare.                                               |
-| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.          |
-| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.   |
-| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection. |
+| Input              | Default      | Purpose                                                                                                                                |
+| ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `fresh-dir`        | _required_   | PR-head (or committed) captures to compare.                                                                                            |
+| `base-ref`         | _none_       | Read the baseline from a git ref (e.g. the PR base branch) instead of `baseline-dir` — the committed-map flow. Needs `fetch-depth: 0`. |
+| `baseline-dir`     | _required\*_ | Base-branch captures dir. _\*Not required when `base-ref` is set._                                                                     |
+| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.                                                                      |
+| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.                                                               |
+| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection.                                                             |
 
 Outputs: `changed` (`"true"` when anything changed), `report-url`. Other inputs (`report-branch`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/action.yml).
 
@@ -292,38 +328,42 @@ 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. Omit `widths` to auto-detect the app's `@media` breakpoints and sweep one width per band. |
-| `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.                                                                                                                                                                                  |
+| Option        | Default                     | Purpose                                                                                                                                                                                                                         |
+| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths?, ignore?, height?, liveStates?, variants? }`. `go(page)` drives to a settled state. Omit `widths` to auto-detect the app's `@media` breakpoints and sweep one width per band. |
+| `liveStates`  | _none_                      | Optional pinned live product states. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<state>` and is labeled as a live state in reports.                                                              |
+| `variants`    | _none_                      | Optional non-live deterministic states under a surface. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<variant>` so base/head compare matching states.                                              |
+| `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.
 
 **Capture env vars** (wire CI without editing the spec):
 
-| Env                      | Purpose                                                                       |
-| ------------------------ | ----------------------------------------------------------------------------- |
-| `STYLEMAP_DIR`           | Output label; the capture is skipped entirely when unset.                     |
-| `STYLEPROOF_REPLAY_FROM` | Baseline dir to replay recorded data from — set this on the **head** capture. |
-| `STYLEPROOF_REPLAY_URL`  | Override the `**/api/**` data-boundary glob.                                  |
-| `STYLEPROOF_SELFCHECK`   | `1` to capture each surface twice and fail if the two differ.                 |
+| Env                      | Purpose                                                                                       |
+| ------------------------ | --------------------------------------------------------------------------------------------- |
+| `STYLEMAP_DIR`           | Output label; the capture is skipped entirely when unset.                                     |
+| `STYLEPROOF_BASEDIR`     | Output root dir (default `__stylemaps__`). The committed-map hook sets this to a tracked dir. |
+| `STYLEPROOF_SCREENSHOTS` | `0` to skip full-page screenshots — lean, commit-friendly `.json.gz`-only maps.               |
+| `STYLEPROOF_REPLAY_FROM` | Baseline dir to replay recorded data from — set this on the **head** capture.                 |
+| `STYLEPROOF_REPLAY_URL`  | Override the `**/api/**` data-boundary glob.                                                  |
+| `STYLEPROOF_SELFCHECK`   | `1` to capture each surface twice and fail if the two differ.                                 |
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `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).
+- `styleproof-init` — scaffold **and activate** the whole gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), the pre-push capture-and-push hook, and the browser-less CI workflow. One command.
+- `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). Use **`styleproof-diff --base-ref <gitref> <mapsDir>`** to diff your committed maps against a git ref (the committed-map flow) — no second dir, no recapture.
+- `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); **`--base-ref <gitref> <mapsDir>`** reads the base from git like the diff CLI.
 
-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.
+A programmatic API is also exported — `captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, and the breakpoint helpers `detectViewportWidths` / `widthsFromBoundaries`, among others. 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.
 
 ## License
 

package/bin/styleproof-init.mjs

@@ -20,6 +20,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { discoverNextRoutes } from '../dist/index.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
@@ -238,7 +239,8 @@ export default defineConfig({
 // always carries a base map and CI is a fast, browser-less diff of two precomputed
 // maps. The hook redirects capture into a committed `stylemaps/` dir and drops
 // screenshots via the STYLEPROOF_BASEDIR / STYLEPROOF_SCREENSHOTS env knobs.
-const HOOK_PATH = '.githooks/pre-push';
+const HOOK_DIR = '.githooks';
+const HOOK_PATH = `${HOOK_DIR}/pre-push`;
 const PREPUSH_HOOK = `#!/bin/sh
 # StyleProof pre-push hook (generated by styleproof-init).
 #
@@ -358,9 +360,33 @@ if (ci.wrote) {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+// Activate the hook so ONE `styleproof-init` is all it takes — but never clobber a
+// repo that already manages its hooks (husky, or an existing core.hooksPath); there
+// we leave it and print the one-liner instead.
+const git = (a) => spawnSync('git', a, { encoding: 'utf8' });
+const inGitRepo = git(['rev-parse', '--is-inside-work-tree']).status === 0;
+const existingHooksPath = inGitRepo ? git(['config', '--local', '--get', 'core.hooksPath']).stdout.trim() : '';
+const managesHooks = existingHooksPath !== '' || fs.existsSync('.husky');
+let hookActivated = false;
+if (inGitRepo && !managesHooks) {
+  if (git(['config', 'core.hooksPath', HOOK_DIR]).status === 0) {
+    hookActivated = true;
+    console.log(`activated the pre-push hook (core.hooksPath → ${HOOK_DIR})`);
+    wroteSomething = true;
+  }
+}
+
 console.log('\nHow the gate works — capture local, CI just diffs:');
-console.log('  1. Activate the pre-push hook (once per clone):');
-console.log('       git config core.hooksPath .githooks');
+if (hookActivated) {
+  console.log('  1. ✓ Pre-push hook is active — nothing to do.');
+} else if (managesHooks) {
+  console.log(`  1. Your repo already manages git hooks (${existingHooksPath || '.husky'}), so the hook`);
+  console.log(`     wasn't auto-activated. Point your hook runner at ${HOOK_DIR}/pre-push, or run:`);
+  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
+} else {
+  console.log('  1. Activate the pre-push hook (once per clone):');
+  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
+}
 console.log('  2. Push your branch. The hook captures the computed-style map against a');
 console.log('     PRODUCTION build, commits it (lean .json.gz under stylemaps/), and pushes it');
 console.log('     with your branch — one `git push`, never two.');

package/dist/capture.d.ts

@@ -55,7 +55,23 @@ export type ElementEntry = {
         props?: Record<string, string>;
     };
 };
+export type CaptureMetadata = {
+    surfaceKey?: string;
+    variantKey?: string;
+    variantKind?: 'variant' | 'live-state';
+};
+export type LiveRegionCandidate = {
+    path: string;
+    tag: string;
+    cls: string;
+    reason: string;
+    role?: string;
+    ariaLive?: string;
+    ariaBusy?: string;
+};
 export type StyleMap = {
+    /** Optional runner-supplied context; ignored by the certification diff. */
+    metadata?: CaptureMetadata;
     defaults: Record<string, Props>;
     elements: Record<string, ElementEntry>;
     states: Record<string, Record<string, Record<string, Props>>>;
@@ -74,6 +90,13 @@ export type StyleMap = {
      * stream/ticker never reads as a change. Empty/absent on a fully-settled page.
      */
     volatile?: string[];
+    /**
+     * Semantic live-state candidates detected automatically from the DOM, such as
+     * `[aria-live]`, `role=status`, `role=alert`, or `aria-busy=true`. These are
+     * diagnostics only: stable candidates are still captured and compared; only
+     * regions that actually keep changing are auto-excluded via `volatile`.
+     */
+    liveCandidates?: LiveRegionCandidate[];
     /**
      * Colour-valued `:root` custom properties (design/theme tokens), normalised to
      * the same `rgb(...)` form the longhands resolve to — `{ "--red-200": "rgb(254,
@@ -171,6 +194,8 @@ export type CaptureOptions = {
      * in flight when you called it (arm one yourself before `goto` if that matters).
      */
     pendingRequests?: () => number;
+    /** Advanced/internal: metadata to persist with the capture for report context. */
+    metadata?: CaptureMetadata;
 };
 /** 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). */

package/dist/capture.js

@@ -229,6 +229,41 @@ function capturePage({ ignore, motionOnly, captureText, captureComponent }) {
     frame.remove();
     return { defaults, elements, shadowHosts, sameOriginFrames };
 }
+function detectLiveCandidates({ ignore }) {
+    const pathOf = window.__spPathOf;
+    const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
+    const reasonsFor = (role, ariaLive, ariaBusy) => {
+        const reasons = [];
+        if (ariaLive && ariaLive !== 'off')
+            reasons.push(`aria-live=${ariaLive}`);
+        if (['alert', 'log', 'marquee', 'status', 'timer'].includes(role))
+            reasons.push(`role=${role}`);
+        if (ariaBusy === 'true')
+            reasons.push('aria-busy=true');
+        return reasons;
+    };
+    return [document.documentElement, document.body, ...document.querySelectorAll('body *')]
+        .filter((el) => !skipSel || !el.matches(skipSel))
+        .flatMap((el) => {
+        const role = (el.getAttribute('role') ?? '').trim().toLowerCase();
+        const ariaLive = (el.getAttribute('aria-live') ?? '').trim().toLowerCase();
+        const ariaBusy = (el.getAttribute('aria-busy') ?? '').trim().toLowerCase();
+        const reasons = reasonsFor(role, ariaLive, ariaBusy);
+        return reasons.length
+            ? [
+                {
+                    path: pathOf(el),
+                    tag: el.tagName.toLowerCase(),
+                    cls: el.getAttribute('class') || '',
+                    reason: reasons.join(', '),
+                    ...(role ? { role } : {}),
+                    ...(ariaLive ? { ariaLive } : {}),
+                    ...(ariaBusy ? { ariaBusy } : {}),
+                },
+            ]
+            : [];
+    });
+}
 /** Full (unpruned) computed styles for an element and its descendants, pseudo-elements included. */
 // Serialized into the browser by page.evaluate; cannot call module helpers.
 function snapSubtree({ selector, index }) {
@@ -571,6 +606,10 @@ export async function captureStyleMap(page, options = {}) {
     // (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, options.pendingRequests);
+    // Detect semantic live-state candidates automatically, but don't exclude them
+    // merely for being live regions. Stable status/alert/log UI is product UI and
+    // should still be captured; this metadata only improves reports and diagnostics.
+    const liveCandidates = await page.evaluate(detectLiveCandidates, { ignore: FRAMEWORK_IGNORE });
     // Motion longhands (transition/animation) are read separately so declared
     // motion is verified even though every other value is a frozen end state.
     // Read them on the SETTLED DOM, not before it: capturing pre-settle missed any
@@ -595,11 +634,13 @@ export async function captureStyleMap(page, options = {}) {
     }
     const tokens = await page.evaluate(capturePageTokens);
     return {
+        ...(options.metadata ? { metadata: options.metadata } : {}),
         defaults: base.defaults,
         elements: base.elements,
         states,
         ...(statesSkipped ? { statesSkipped: true } : {}),
         ...(volatile.length ? { volatile } : {}),
+        ...(liveCandidates.length ? { liveCandidates } : {}),
         ...(Object.keys(tokens).length ? { tokens } : {}),
     };
 }

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
-export type { StyleMap, CaptureOptions, ElementEntry, Rect } from './capture.js';
+export type { StyleMap, CaptureOptions, CaptureMetadata, ElementEntry, LiveRegionCandidate, Rect } from './capture.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
-export type { Surface, DefineOptions, CrawlOptions } from './runner.js';
+export type { Surface, SurfaceLiveState, SurfaceVariant, DefineOptions, CrawlOptions } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export type { CoverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';

package/dist/report.js

@@ -354,14 +354,12 @@ export function prettyLabel(p, cls) {
 }
 const surfaceBase = (s) => s.replace(/@\d+$/, '');
 const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
-/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
-function formatSurfaceList(surfaces) {
-    const byBase = new Map();
-    for (const s of surfaces) {
-        const arr = byBase.get(surfaceBase(s)) ?? [];
-        arr.push(surfaceWidth(s));
-        byBase.set(surfaceBase(s), arr);
-    }
+function pushSurfaceWidth(byBase, base, surface) {
+    const arr = byBase.get(base) ?? [];
+    arr.push(surfaceWidth(surface));
+    byBase.set(base, arr);
+}
+function renderSurfaceGroups(byBase) {
     return [...byBase]
         .map(([base, ws]) => {
         const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
@@ -369,6 +367,53 @@ function formatSurfaceList(surfaces) {
     })
         .join(' · ');
 }
+/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
+function formatSurfaceList(surfaces) {
+    const byBase = new Map();
+    for (const s of surfaces)
+        pushSurfaceWidth(byBase, surfaceBase(s), s);
+    return renderSurfaceGroups(byBase);
+}
+function surfaceContext(...maps) {
+    const metadata = maps.find((m) => m?.metadata)?.metadata;
+    if (!metadata?.variantKey)
+        return '';
+    return metadata.variantKind === 'live-state'
+        ? `live state \`${metadata.variantKey}\``
+        : `variant \`${metadata.variantKey}\``;
+}
+function formatSurfaceWithContext(surface, ...maps) {
+    const context = surfaceContext(...maps);
+    return context ? `${formatSurfaceList([surface])} · ${context}` : formatSurfaceList([surface]);
+}
+function formatSurfaceListWithContext(surfaces, beforeDir) {
+    const byBase = new Map();
+    for (const surface of surfaces) {
+        const map = loadStyleMap(findCapture(beforeDir, surface));
+        const context = surfaceContext(map);
+        const base = context ? `${surfaceBase(surface)} · ${context}` : surfaceBase(surface);
+        pushSurfaceWidth(byBase, base, surface);
+    }
+    return renderSurfaceGroups(byBase);
+}
+function liveCandidateLabel(candidate) {
+    const label = candidate.cls ? `${candidate.tag}.${candidate.cls.split(/\s+/)[0]}` : candidate.tag;
+    return `${label} (${candidate.reason})`;
+}
+function captureFiles(dir) {
+    return fs.existsSync(dir) ? fs.readdirSync(dir).filter((f) => /\.json(\.gz)?$/.test(f)) : [];
+}
+function collectLiveCandidateLabels(beforeDir, afterDir) {
+    const seen = new Set();
+    for (const dir of [beforeDir, afterDir]) {
+        for (const file of captureFiles(dir)) {
+            const map = loadStyleMap(path.join(dir, file));
+            for (const candidate of map.liveCandidates ?? [])
+                seen.add(liveCandidateLabel(candidate));
+        }
+    }
+    return [...seen].sort();
+}
 // Grid-track longhands compute to width-dependent pixels (`282px ×2` at one width,
 // `282px 228px` at another), so the SAME responsive change would otherwise get a
 // different signature per width. Key them by track COUNT — what actually
@@ -753,6 +798,7 @@ export function generateStyleMapReport(opts) {
     const includeNoise = opts.includeLayoutNoise ?? false;
     const includeContent = opts.includeContent ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
+    const liveCandidateLabels = volatileCount > 0 ? collectLiveCandidateLabels(beforeDir, afterDir) : [];
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
     // Focus each surface on styling intent: drop reflow-casualty props, suppress
     // forced-state echoes of base changes, and remove non-value noise (see
@@ -826,7 +872,10 @@ export function generateStyleMapReport(opts) {
         }
     }
     if (volatileCount > 0) {
-        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check._`);
+        const candidates = liveCandidateLabels.length
+            ? ` Auto-detected live-state candidate(s): ${liveCandidateLabels.slice(0, 5).join('; ')}.`
+            : '';
+        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check.${candidates}_`);
     }
     if (contentSection.count > 0 && (changeGroups.length > 0 || missing.length > 0)) {
         md.push('', `📝 _${contentSection.count} advisory content change(s) below — they don't affect the check._`);
@@ -856,9 +905,6 @@ export function generateStyleMapReport(opts) {
         // Read top-to-bottom: one section per crop, in page order.
         const topY = (g) => (visible(g.after) ? g.after.y : visible(g.before) ? g.before.y : Infinity);
         groups.sort((a, b) => topY(a) - topY(b));
-        const surfaceList = cg.surfaces.length > 1
-            ? `_Identical across ${cg.surfaces.length} surfaces: ${formatSurfaceList(cg.surfaces)}_`
-            : `_${formatSurfaceList(cg.surfaces)}_`;
         const surfaceJson = {
             surfaces: cg.surfaces,
             representative: sd.surface,
@@ -870,6 +916,9 @@ export function generateStyleMapReport(opts) {
             // sit directly under the screenshot that shows them — never a wall of
             // changes spanning several crops with no way to tell which is which.
             const regionFindings = surfaceFindings.filter((f) => g.paths.some((root) => f.path === root || f.path.startsWith(root + ' > ')));
+            const surfaceList = cg.surfaces.length > 1
+                ? `_Identical across ${cg.surfaces.length} surfaces: ${formatSurfaceListWithContext(cg.surfaces, beforeDir)}_`
+                : `_${formatSurfaceWithContext(sd.surface, mapA, mapB)}_`;
             md.push('', `### ${regionHeading(g.paths, regionFindings)}`, '', surfaceList);
             const region = visible(g.after) ? g.after : g.before;
             let images = {};
@@ -901,7 +950,7 @@ export function generateStyleMapReport(opts) {
                 // Clean before|after shown by default (the real UI); the annotated twin —
                 // boxes marking each change — sits one click away under a toggle. Plain
                 // images (no link wrap) so a click opens the full-resolution file.
-                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface}</sub>`, '', '<details>', '<summary>🔍 Highlight what changed</summary>', '', `![annotated before ◀ │ ▶ after](${img(images.annotated)})`, '', `<sub>magenta boxes mark each change — ${sd.surface}</sub>`, '', '</details>');
+                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${formatSurfaceWithContext(sd.surface, mapA, mapB)}</sub>`, '', '<details>', '<summary>🔍 Highlight what changed</summary>', '', `![annotated before ◀ │ ▶ after](${img(images.annotated)})`, '', `<sub>magenta boxes mark each change — ${formatSurfaceWithContext(sd.surface, mapA, mapB)}</sub>`, '', '</details>');
             }
             else if (!region) {
                 md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
@@ -923,8 +972,9 @@ export function generateStyleMapReport(opts) {
     for (const p of missing) {
         const side = p.sd.missing === 'before' ? 'after' : 'before';
         const srcDir = side === 'after' ? afterDir : beforeDir;
+        const map = loadStyleMap(findCapture(srcDir, p.sd.surface));
         const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
-        md.push('', `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`, '', `_${formatSurfaceList([p.sd.surface])}_`);
+        md.push('', `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`, '', `_${formatSurfaceWithContext(p.sd.surface, map)}_`);
         const surfaceJson = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
         if (png) {
             cropSeq++;
@@ -932,7 +982,7 @@ export function generateStyleMapReport(opts) {
             const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h).png;
             const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
             writePng(path.join(outDir, `${stem}.png`), crop);
-            md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${p.sd.surface}${png.height > h ? ' (top of page)' : ''}</sub>`);
+            md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${formatSurfaceWithContext(p.sd.surface, map)}${png.height > h ? ' (top of page)' : ''}</sub>`);
             surfaceJson.image = `${stem}.png`;
         }
         else {

package/dist/runner.d.ts

@@ -1,3 +1,5 @@
+import { type CaptureMetadata, type LiveRegionCandidate } from './capture.js';
+import { type Finding } from './diff.js';
 import { type LinkMatch } from './crawl.js';
 import type { Page } from '@playwright/test';
 /**
@@ -26,7 +28,37 @@ export type Surface = {
     widths?: number[];
     /** Viewport height: a number, or a function of the width (default 800). */
     height?: number | ((width: number) => number);
+    /**
+     * Optional deterministic states of this same surface. Each variant becomes its
+     * own capture (`<surface>-<variant>@<width>`), so base/head compare loading to
+     * loading and loaded to loaded instead of treating live UI as one fuzzy state.
+     */
+    variants?: SurfaceVariant[];
+    /**
+     * First-class live product states for this surface. Use this for loading,
+     * loaded, empty, error, streaming, etc. StyleProof records them as live-state
+     * variants so reports and diagnostics can explain why the capture was split.
+     */
+    liveStates?: SurfaceLiveState[];
+};
+export type SurfaceVariant = {
+    /** Capture key suffix, joined as `<surface.key>-<variant.key>`. */
+    key: string;
+    /**
+     * Seed the state before the parent surface navigates: route mocks, fixture data,
+     * localStorage/sessionStorage, feature flags, etc.
+     */
+    setup?: (page: Page) => Promise<void>;
+    /** Drive or assert the variant after the parent surface reaches its base state. */
+    go?: (page: Page) => Promise<void>;
+    /** Extra ignored selectors for this variant, appended to the parent surface's ignore list. */
+    ignore?: string[];
+    /** Override the parent viewport widths for this variant. */
+    widths?: number[];
+    /** Override the parent viewport height for this variant. */
+    height?: number | ((width: number) => number);
 };
+export type SurfaceLiveState = SurfaceVariant;
 export type DefineOptions = {
     surfaces: Surface[];
     /**
@@ -112,6 +144,11 @@ export type DefineOptions = {
      */
     captureComponent?: boolean;
 };
+export declare function selfCheckErrorMessage(surfaceKey: string, drift: Finding[], volatile?: string[], liveCandidates?: LiveRegionCandidate[]): string;
+type ExpandedSurface = Omit<Surface, 'variants' | 'liveStates'> & {
+    metadata?: CaptureMetadata;
+};
+export declare function expandSurfaceVariants(surface: Surface): ExpandedSurface[];
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording
@@ -181,6 +218,10 @@ export type CrawlOptions = CaptureConfig & {
     height?: number | ((width: number) => number);
     /** Selectors skipped on every surface (live regions, third-party embeds). */
     ignore?: string[];
+    /** Deterministic variants captured for every discovered link surface. */
+    variants?: SurfaceVariant[];
+    /** First-class live product states captured for every discovered link surface. */
+    liveStates?: SurfaceLiveState[];
     /** Max ms to wait for the crawl root's links to render before reading them
      *  (an SPA hydrates its nav client-side). Default 15000. */
     linkTimeout?: number;

package/dist/runner.js

@@ -1,7 +1,7 @@
 import { test, expect } from '@playwright/test';
 import fs from 'node:fs';
 import path from 'node:path';
-import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps } from './coverage.js';
 import { detectViewportWidths } from './breakpoints.js';
@@ -13,6 +13,77 @@ function driftDesc(f) {
     const p = f.props[0];
     return p ? `${f.path} ${p.prop}: ${p.before} → ${p.after}` : f.path;
 }
+const ROOT_LAYOUT_PATHS = new Set(['html', 'body']);
+const ROOT_LAYOUT_PROPS = new Set([
+    'block-size',
+    'height',
+    'inline-size',
+    'width',
+    'min-block-size',
+    'min-height',
+    'max-block-size',
+    'max-height',
+    'perspective-origin',
+    'transform-origin',
+]);
+function hasRootLayoutDrift(drift) {
+    return drift.some((f) => f.kind === 'style' && ROOT_LAYOUT_PATHS.has(f.path) && f.props.some((p) => ROOT_LAYOUT_PROPS.has(p.prop)));
+}
+function liveCandidateDesc(candidate) {
+    const label = candidate.cls ? `${candidate.tag}.${candidate.cls.split(/\s+/)[0]}` : candidate.tag;
+    return `${label} (${candidate.reason}) at ${candidate.path}`;
+}
+export function selfCheckErrorMessage(surfaceKey, drift, volatile = [], liveCandidates = []) {
+    const first = drift[0];
+    let message = `styleproof self-check failed: ${surfaceKey} is non-deterministic — ` +
+        `${drift.length} computed-style difference(s) between two captures of the same commit. ` +
+        `Likely a replay gap (a request not in the baseline HAR) or unseeded randomness.`;
+    if (volatile.length && hasRootLayoutDrift(drift)) {
+        message +=
+            ` Volatile regions were detected in this capture; root/body layout drift usually means live content ` +
+                `is still changing document flow. Model those live states with \`liveStates\` instead ` +
+                `of only ignoring the region.`;
+        if (liveCandidates.length) {
+            message += ` Auto-detected live-state candidate(s): ${liveCandidates
+                .slice(0, 3)
+                .map(liveCandidateDesc)
+                .join('; ')}.`;
+        }
+    }
+    return first ? `${message} First: ${driftDesc(first)}` : message;
+}
+function mergeIgnore(...groups) {
+    const merged = [...new Set(groups.flatMap((g) => g ?? []))];
+    return merged.length ? merged : undefined;
+}
+function expandOne(surface, variant, variantKind) {
+    return {
+        key: `${surface.key}-${variant.key}`,
+        go: async (page) => {
+            await variant.setup?.(page);
+            await surface.go(page);
+            await variant.go?.(page);
+        },
+        ignore: mergeIgnore(surface.ignore, variant.ignore),
+        widths: variant.widths ?? surface.widths,
+        height: variant.height ?? surface.height,
+        metadata: { surfaceKey: surface.key, variantKey: variant.key, variantKind },
+    };
+}
+export function expandSurfaceVariants(surface) {
+    const variants = surface.variants ?? [];
+    const liveStates = surface.liveStates ?? [];
+    if (!variants.length && !liveStates.length) {
+        const { variants: _variants, liveStates: _liveStates, ...base } = surface;
+        void _variants;
+        void _liveStates;
+        return [{ ...base, metadata: { surfaceKey: surface.key } }];
+    }
+    return [
+        ...variants.map((variant) => expandOne(surface, variant, 'variant')),
+        ...liveStates.map((state) => expandOne(surface, state, 'live-state')),
+    ];
+}
 /**
  * Let SSE (EventSource) requests bypass HAR record/replay and reach the live
  * server. A long-lived stream can't round-trip through a HAR entry: recording
@@ -77,10 +148,8 @@ async function assertDeterministic(page, surface, first, captureText, pending) {
     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 — ` +
-            `${drift.length} computed-style difference(s) between two captures of the same commit. ` +
-            `Likely a replay gap (a request not in the baseline HAR) or unseeded randomness. ` +
-            `First: ${driftDesc(drift[0])}`);
+        const liveCandidates = [...(first.liveCandidates ?? []), ...(again.liveCandidates ?? [])];
+        throw new Error(selfCheckErrorMessage(surface.key, drift, [...new Set([...(first.volatile ?? []), ...(again.volatile ?? [])])], liveCandidates));
     }
 }
 /** Drive one surface at one width to a settled state and save its style map (+ screenshot).
@@ -101,6 +170,7 @@ async function captureSurface(page, surface, width, s) {
             captureText: s.captureText,
             captureComponent: s.captureComponent,
             pendingRequests: requests.pending,
+            metadata: surface.metadata,
         });
         if (s.selfCheck)
             await assertDeterministic(page, surface, map, s.captureText, requests.pending);
@@ -180,6 +250,7 @@ function resolveSettings(c) {
 export function defineStyleMapCapture(options) {
     const { surfaces, expected, exclude = {}, dir } = options;
     const settings = resolveSettings(options);
+    const captureSurfaces = surfaces.flatMap(expandSurfaceVariants);
     // 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
@@ -199,7 +270,7 @@ export function defineStyleMapCapture(options) {
     }
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
-        for (const surface of surfaces) {
+        for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
                 for (const width of surface.widths) {
@@ -243,7 +314,7 @@ export function defineStyleMapCapture(options) {
  * ```
  */
 export function defineCrawlCapture(options) {
-    const { from, match, key, widths, height, ignore, linkTimeout = 15_000, dir } = options;
+    const { from, match, key, widths, height, ignore, variants, liveStates, linkTimeout = 15_000, dir } = options;
     const settings = resolveSettings(options);
     test.describe('styleproof crawl-capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
@@ -258,28 +329,30 @@ export function defineCrawlCapture(options) {
                 throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
                     `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
             }
+            const captureSurfaces = links.flatMap((link) => expandSurfaceVariants({
+                key: link.key,
+                go: async (p) => {
+                    await p.goto(link.url, { waitUntil: 'load' });
+                },
+                widths,
+                ignore,
+                height,
+                variants,
+                liveStates,
+            }));
             // Budget the whole sweep up front: one test captures every surface, and
             // captureSurface no longer sets its own timeout, so size it to the work found.
-            test.setTimeout(Math.max(180_000, links.length * widths.length * 60_000));
+            test.setTimeout(Math.max(180_000, captureSurfaces.reduce((sum, surface) => sum + (surface.widths?.length ?? 0), 0) * 60_000));
             // 2. Capture each discovered surface. Aggregate failures so one bad surface
             //    reports without skipping the rest — they're an independent set, not a chain.
             const failures = [];
-            for (const link of links) {
-                for (const width of widths) {
-                    const surface = {
-                        key: link.key,
-                        go: async (p) => {
-                            await p.goto(link.url, { waitUntil: 'load' });
-                        },
-                        widths: [width],
-                        ignore,
-                        height,
-                    };
+            for (const surface of captureSurfaces) {
+                for (const width of surface.widths ?? []) {
                     try {
                         await captureSurface(page, surface, width, settings);
                     }
                     catch (e) {
-                        failures.push(`${link.key} @ ${width}: ${e.message}`);
+                        failures.push(`${surface.key} @ ${width}: ${e.message}`);
                     }
                 }
             }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.5.0",
+  "version": "3.0.1",
   "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",
@@ -65,7 +65,7 @@
     "bench": "npm run build && node bench/gate-speed.mjs",
     "init": "node ./bin/styleproof-init.mjs",
     "prepare": "npm run build && husky",
-    "prepublishOnly": "npm run clean && npm run build && npm run typecheck"
+    "prepublishOnly": "npm run clean && npm run build && npm run typecheck && npm run lint && npm run format:check && npm test && npm run test:e2e"
   },
   "peerDependencies": {
     "@playwright/test": ">=1.40"