styleproof 3.1.4 → 3.1.5

package/CHANGELOG.md

@@ -7,6 +7,55 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.1.5] - 2026-06-29
+
+### Added
+
+- Added `harvestStyleVariants` and the `styleproof-variants` CLI to discover
+  one-step UI state variants from a running app. The crawler tries semantic
+  controls, keeps only actions that change computed styles, dedupes equivalent
+  outcomes, and reports live-state candidates that need fixtures or opt-outs.
+- **Captured maps now include semantic overlay proof metadata.** Visible dialog,
+  menu, listbox, modal, popover, tooltip, and toast roots that are present in the
+  captured DOM are recorded under `overlays`, filtered to paths that are actually
+  in the computed-style map. Downstream suites can now assert that a popup map
+  captured `role="dialog"`, `aria-modal`, `role="menu"`, `role="listbox"`, or
+  hot-toast text instead of only asserting that a popup file exists.
+- **Component inventory coverage is now available through
+  `discoverComponentFiles`.** It scans explicit component roots across common
+  framework file types and returns stable `component-*` keys, so teams can wire a
+  Storybook/Ladle/custom catalog into `expected` and fail CI when a component file
+  has no rendered StyleProof surface or reviewed exclusion. `componentCatalogSurfaces`
+  turns the same inventory into catalog URL capture surfaces so the surface list
+  and expected list cannot drift apart.
+
+### Changed
+
+- **`styleproof-init` now points modal, popover, menu, tab, and form-error
+  captures at `variants`.** The generated generic spec includes commented
+  `dialog-open` and `popover-open` examples under the base surface, so app-owned
+  UI states compare state-to-state instead of becoming orphan root surfaces.
+- **The coverage guard now checks expanded variant keys.** Projects can put
+  required states such as `dashboard-user-menu-open`, `dashboard-toast-visible`,
+  or component catalog keys in `expected`; StyleProof fails unless those exact
+  surfaces are captured or explicitly excluded.
+- **Non-live variants now keep the base capture.** Dialog, menu, popover, toast,
+  and overlay captures augment the owning surface instead of replacing its normal
+  page capture. `liveStates` continue to model explicit pinned live states.
+- **Automatic popup capture now treats modal attributes, dropdown roles, and
+  toast roots as default overlay candidates.** The default selector includes
+  `[aria-modal="true"]`, `role="menu"`, `role="listbox"`, hot-toast/Sonner-style
+  toast markers, and status/alert toast roots. Popup matching also compares a
+  semantic/text signature, so a reused mount or toast host can still be captured
+  when its visible state changes.
+
+### Fixed
+
+- Computed-style diffs now ignore sub-pixel `transform-origin` and
+  `perspective-origin` jitter while still reporting meaningful origin changes.
+
+## [3.1.4] - 2026-06-29
+
 ### Fixed
 
 - **Popup capture no longer collapses distinct triggers that reuse the same
@@ -1009,7 +1058,9 @@ 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/v3.1.3...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.5...HEAD
+[3.1.5]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.4...v3.1.5
+[3.1.4]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.3...v3.1.4
 [3.1.3]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.2...v3.1.3
 [3.1.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...v3.1.2
 [3.1.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.0...v3.1.1

package/README.md

@@ -1,24 +1,118 @@
 # StyleProof
 
-**Know exactly what every PR changes visually, and sign it off.** StyleProof captures the browser's _computed_ styles (not pixels), diffs your PR's HEAD against its base branch, and posts a per-change report on the PR, so a styling change never ships without someone confirming it was intended.
+**StyleProof is a PR gate for visual CSS changes.** You tell it which app states
+matter. It opens those states in a real browser, records the browser's computed
+styles, compares the PR head against the base branch, and posts a reviewable PR
+report. Intentional visual changes get approved; unexpected ones block or fail.
 
 [![npm version](https://img.shields.io/npm/v/styleproof.svg)](https://www.npmjs.com/package/styleproof)
 [![CI](https://github.com/BenSheridanEdwards/StyleProof/actions/workflows/ci.yml/badge.svg)](https://github.com/BenSheridanEdwards/StyleProof/actions)
 [![license](https://img.shields.io/npm/l/styleproof.svg)](https://github.com/BenSheridanEdwards/StyleProof/blob/main/LICENSE)
 
-## Why
-
-Pixel-snapshot tools miss most CSS regressions: they can't force `:hover` / `:focus` / `:active`, can't see hidden or off-screen elements, can't reach between-breakpoint rules, and blur away sub-pixel drift. StyleProof reads the **computed style** of every element instead — every resolved longhand, every pseudo-element, the deltas `:hover` / `:focus` / `:active` apply (forced via CDP, no mouse), swept across each `@media` breakpoint.
-
-## What the gate does
+## Contents
+
+- [Why](#why)
+- [The short version](#the-short-version)
+- [What it catches](#what-it-catches)
+- [What you own](#what-you-own)
+- [What the PR gets](#what-the-pr-gets)
+- [Don't let a new page ship uncaptured](#dont-let-a-new-page-ship-uncaptured)
+- [What a report looks like](#what-a-report-looks-like)
+- [Works with any styling system](#works-with-any-styling-system)
+- [Breakpoints, detected automatically](#breakpoints-detected-automatically)
+- [Certify a refactor](#certify-a-refactor)
+- [Install](#install)
+- [Quickstart](#quickstart)
+- [Forks and Dependabot](#forks-and-dependabot)
+- [Optional: content layer](#optional-content-layer-advisory)
+- [Optional: React component layer](#optional-react-component-layer-advisory)
+- [Newly-added elements show their full style](#newly-added-elements-show-their-full-style)
+- [Reference](#reference)
+  - [Blocking without branch protection](#blocking-without-branch-protection)
+- [License](#license)
 
-On every PR, StyleProof diffs the PR head's computed-style map against the base branch's, and posts a Markdown comment:
+## Why
 
-- 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.
-- **Clean runs leave a receipt too.** When no visual changes are detected, StyleProof still creates or updates the PR comment with `✓ No visual changes detected.`, so a green status has a visible record instead of only a silent check.
-- **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.
-- The diff is always **head-vs-base**, so the report is _exactly what this PR changes_ — whether the maps are restored from the `styleproof-maps` cache or recaptured in CI on a cache miss. See [Quickstart](#quickstart).
+Use StyleProof when a PR can change CSS, design tokens, component classes,
+layout, or hidden/open UI states and you want CI to say whether the browser's
+rendered styles actually changed. Unit and e2e tests prove behavior; StyleProof
+proves the visual contract for the states you declared.
+
+It is useful for:
+
+- certifying a "no visual change" refactor such as CSS Modules to Tailwind;
+- reviewing intentional visual changes with exact before/after style evidence;
+- catching accidental changes that only appear at one breakpoint;
+- catching open-state regressions in dialogs, dropdowns, listboxes, popovers, and
+  toasts;
+- failing CI when a required route, component, or UI state exists but has no
+  capture.
+
+The important boundary: StyleProof only certifies states it can reach. If a state
+matters, list it as a surface, variant, popup, live state, or component-catalog
+surface. `expected` turns that inventory into a guard, so an uncaptured new page,
+component, modal, dropdown, or toast fails as missing coverage instead of
+silently passing.
+
+## The short version
+
+1. A **surface** is one UI state to certify: a route, tab, modal-open state,
+   dropdown-open state, toast-visible state, loading state, etc.
+2. You list surfaces in a Playwright-style spec.
+3. StyleProof opens each surface at real breakpoint widths and records computed
+   styles for every captured element.
+4. On a PR, it compares base vs head and reports exactly which rendered styles
+   changed.
+5. The PR gets a `StyleProof` status: green when nothing changed, red until
+   someone approves intentional changes, or failing when certification mode is
+   configured.
+
+StyleProof is not a screenshot diff. Screenshots appear in the report so humans
+can see the change, but the gate compares browser-computed CSS: resolved
+longhands, pseudo-elements, layout boxes, motion longhands, and forced
+`:hover`/`:focus`/`:active` deltas.
+
+## What it catches
+
+- A button recoloured by a token, utility class, CSS module, inline style, or
+  design-system change.
+- A layout shift at one breakpoint but not another.
+- A dropped `:hover`, `:focus`, or `:active` style.
+- A modal, menu, listbox, popover, sheet, or toast whose open state changed.
+- A supposedly no-op refactor, such as CSS-to-Tailwind, that changed rendered
+  output.
+
+## What you own
+
+StyleProof can only certify states it reaches. You own the app-specific list of
+states that matter:
+
+- routes and views belong in `surfaces`;
+- open states belong in `variants` or `popups`;
+- loading/loaded/empty/error states belong in `liveStates`;
+- component catalogs can be wired through `discoverComponentFiles`;
+- required-but-not-yet-captured states belong in `expected`, where the coverage
+  guard fails until they are captured or explicitly excluded with a reason.
+
+That boundary is deliberate. StyleProof should not guess destructive flows,
+auth-only fixtures, or which product state your component needs. It should make
+missing coverage loud.
+
+## What the PR gets
+
+On every PR, StyleProof posts a small summary comment that links to the committed
+full report. The report groups each distinct visual change with:
+
+- before/after crops from the same page rectangle;
+- highlighted crops that box the changed element;
+- a plain-English summary such as `columns: 2 -> 3` or
+  `background brand-cyan -> brand-amber`;
+- the exact computed CSS properties that changed.
+
+In review-gate mode, one **Approve all changes** checkbox turns the `StyleProof`
+status green for that commit. Clean runs still leave a receipt: `No visual
+changes detected.` New surfaces are shown as new baselines; coverage gaps are
+handled by `expected`.
 
 ## Don't let a new page ship uncaptured
 
@@ -80,6 +174,136 @@ 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).
 
+**Component inventory: fail when the catalog misses a component.** StyleProof
+cannot render arbitrary component files by itself across frameworks; props,
+providers, loaders, portals, and app shell context are app-owned. What it can do
+reliably is inventory component files and make your catalog/story route prove it
+has a capture for each one:
+
+```ts
+import { componentCatalogSurfaces, defineStyleMapCapture, discoverComponentFiles } from 'styleproof';
+
+const COMPONENTS = discoverComponentFiles({
+  roots: ['src/components'],
+  ignore: [/\/icons\//],
+});
+
+defineStyleMapCapture({
+  surfaces: componentCatalogSurfaces(COMPONENTS, {
+    url: (component) => `/styleproof/components/${component.key}`,
+    widths: [390, 1024],
+  }),
+  expected: COMPONENTS.map((component) => component.key),
+  exclude: {
+    'component-payment-card': 'needs a billing provider fixture',
+  },
+  dir: process.env.STYLEMAP_DIR,
+});
+```
+
+Use Storybook, Ladle, a framework route, or a tiny app-specific catalog for
+`/styleproof/components/:key`. The inventory feeds both `surfaces` and
+`expected`, so a new component file appears immediately and CI fails until it has
+a rendered surface or an explicit exclusion.
+
+**Dialogs, popovers and menus: capture the open state as a variant.** StyleProof
+cannot guess which app-specific button opens a modal, but once you tell it the
+interaction, it compares matching states on base and head (`home-dialog-open` to
+`home-dialog-open`). Keep these under the route/view that owns them:
+
+```ts
+const SURFACES: Surface[] = [
+  {
+    key: 'home',
+    go: (page) => page.goto('/'),
+    variants: [
+      {
+        key: 'dialog-open',
+        go: async (page) => {
+          await page.getByRole('button', { name: /open settings/i }).click();
+          await page.getByRole('dialog').waitFor();
+        },
+      },
+      {
+        key: 'popover-open',
+        go: async (page) => {
+          await page.getByRole('button', { name: /more/i }).click();
+          await page.locator('[popover], [role="menu"]').first().waitFor();
+        },
+      },
+    ],
+  },
+];
+```
+
+Non-live `variants` add captures; the owning surface still captures too. Use
+`liveStates` instead when the default live state is too fuzzy and only pinned
+states such as `loading`, `loaded`, `empty`, or `error` should be compared.
+
+When `popups: true` is enabled, StyleProof also tries visible safe triggers and
+captures opened dialogs, menus, listboxes, modal roots, popovers, tooltips, and
+toast/status roots. Each saved map includes `overlays` proof metadata for
+semantic roots that were actually present in the computed-style map, so tests can
+assert a capture reached `role="dialog"`, `aria-modal`, `role="menu"`,
+`role="listbox"`, or hot-toast text.
+
+**Harvest one-step variants.** Routes are not the whole UI: drawers, tabs,
+dialogs, empty form errors, selects, and other one-step states need their own
+captures. `styleproof-variants` opens a running app, tries semantic controls
+(`[aria-expanded]`, tabs, summaries, selects, required forms, etc.), captures a
+baseline and post-action StyleMap, and keeps only actions that change computed
+styles. It also reports live-state candidates that need fixtures or opt-outs.
+
+```bash
+styleproof-variants --base-url http://localhost:3000 --route / --route settings=/settings
+```
+
+Use it as a manifest generator, not a replacement for review. The generated JSON
+is deliberately not read by `styleproof-map`; approve the states you want, then
+copy them into your capture spec as ordinary `variants` / `liveStates`.
+
+```json
+{
+  "routes": [
+    {
+      "key": "settings",
+      "url": "/settings",
+      "variants": [
+        {
+          "key": "plan-selected",
+          "action": "select-option",
+          "selector": "select[aria-label=\"Plan\"]",
+          "value": "pro"
+        }
+      ],
+      "liveStates": [{ "key": "status", "fixtureRequired": true }],
+      "skipped": []
+    }
+  ]
+}
+```
+
+```ts
+defineStyleMapCapture({
+  surfaces: [
+    {
+      key: 'settings',
+      go: (page) => page.goto('/settings'),
+      variants: [
+        {
+          key: 'plan-selected',
+          go: (page) => page.locator('select[aria-label="Plan"]').selectOption('pro'),
+        },
+      ],
+    },
+  ],
+});
+```
+
+Destructive labels are skipped, duplicate computed-style outcomes are deduped,
+and `--strict` exits non-zero when live-state fixtures or skipped candidates
+remain unresolved.
+
 **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
@@ -312,16 +536,16 @@ Anything still moving on its own after that is detected as a volatile region and
 | 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                                                                                                                                                                                                                                                           |
-| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `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.                                                                                                                                                                                                 |
-| `popups: true`                                | Visible click-triggered overlays should be discovered automatically. Captures each matching trigger's persistent dialogs, popovers, menus, listboxes, and open data-state overlays as `surface-popup-XX`; keep hover-only or destructive states as explicit `variants`. |
-| `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.                                                                                                                                                                                           |
+| 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.                                                                                                                                                                   |
+| `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, modal-open, toast-visible, or overlay-expanded states.                                                                                                                                                                                                |
+| `popups: true`                                | Visible click-triggered overlays should be discovered automatically. Captures each matching trigger's persistent dialogs, modal roots, popovers, menus, listboxes, toast/status roots, and open data-state overlays as `surface-popup-XX`; keep hover-only or destructive states as explicit `variants`. |
+| `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)
 
@@ -392,22 +616,22 @@ 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?, liveStates?, variants?, popups? }`. `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.                                                       |
-| `popups`      | `false`                     | Optional automatic popup capture. Set `true` or `{ max, triggers, overlays, timeoutMs }` to click visible safe triggers and save each opened overlay state as `<surface>-popup-XX`.                                                      |
-| `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?, popups? }`. `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. The base surface still captures; each variant becomes `<surface>-<variant>` so base/head compare matching states.                                                                               |
+| `popups`      | `false`                     | Optional automatic popup capture. Set `true` or `{ max, triggers, overlays, timeoutMs }` to click visible safe triggers and save each opened overlay state as `<surface>-popup-XX`; maps include `overlays` proof metadata for captured semantic roots. |
+| `expected`    | _none_                      | Your route/view/state/component universe. Emits a coverage-guard test (runs without a capture dir) that fails when a required key has no surface and isn't excluded.                                                                                    |
+| `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.
 
@@ -430,6 +654,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 - `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
 - `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. 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). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
 - `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
+- `styleproof-variants` — crawl a running app for one-step state variants and write `styleproof.variants.generated.json`. Pass `--base-url`, repeat `--route`, and use `--strict` when unresolved skipped/live candidates should fail automation.
 
 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.
 

package/bin/styleproof-init.mjs

@@ -176,9 +176,27 @@ const SURFACES: Surface[] = [
     // No widths → StyleProof detects your @media breakpoints from the loaded CSS and
     // sweeps one viewport per band. Pass an explicit array (e.g. 1280, 768, 390) to pin them (or to
     // cover a JS-only matchMedia breakpoint that has no CSS @media rule).
+    // Non-live UI states belong here as variants, so the base branch's
+    // dialog-open state compares to the head branch's dialog-open state.
+    // variants: [
+    //   {
+    //     key: 'dialog-open',
+    //     go: async (page) => {
+    //       await page.getByRole('button', { name: /open settings/i }).click();
+    //       await page.getByRole('dialog').waitFor();
+    //     },
+    //   },
+    //   {
+    //     key: 'popover-open',
+    //     go: async (page) => {
+    //       await page.getByRole('button', { name: /more/i }).click();
+    //       await page.locator('[popover], [role="menu"]').first().waitFor();
+    //     },
+    //   },
+    // ],
   },
-  // Add one surface per distinct page state: open menus, dialogs, selected
-  // tabs, form errors — anything whose styling you want certified.
+  // Add more surfaces for distinct routes/views; add menus, dialogs, popovers,
+  // selected tabs, and form errors as variants of the route/view that owns them.
 ];
 
 defineStyleMapCapture({

package/bin/styleproof-variants.mjs

@@ -0,0 +1,97 @@
+#!/usr/bin/env node
+/**
+ * Harvest one-step UI state variants from a running app.
+ *
+ *   styleproof-variants --base-url http://localhost:3000 --route / --route /settings
+ */
+import fs from 'node:fs';
+import { chromium } from '@playwright/test';
+import { harvestStyleVariants } from '../dist/variant-crawler.js';
+import { defaultLinkKey } from '../dist/crawl.js';
+import { isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
+
+const HELP = `styleproof-variants — discover one-step UI state variants
+
+usage: styleproof-variants --base-url <url> --route <path-or-key=path> [options]
+
+options:
+  --base-url <url>       running app origin, e.g. http://localhost:3000
+  --route <route>        route path, absolute URL, or key=path. Repeatable.
+  --out <file>           manifest output (default: styleproof.variants.generated.json)
+  --max-actions <n>      max attempted actions per route (default: 40)
+  --width <px>           viewport width (default: 1280)
+  --height <px>          viewport height (default: 800)
+  --strict               exit 1 if live-state fixtures or skipped candidates remain
+  -h, --help             show this help
+`;
+
+const argv = process.argv.slice(2);
+let baseUrl = '';
+let out = 'styleproof.variants.generated.json';
+let maxActions = 40;
+let width = 1280;
+let height = 800;
+let strict = false;
+const routeArgs = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (isHelpArg(a)) showHelpAndExit(HELP);
+  else if (a === '--base-url') baseUrl = argv[++i];
+  else if (a.startsWith('--base-url=')) baseUrl = a.slice(11);
+  else if (a === '--route') routeArgs.push(argv[++i]);
+  else if (a.startsWith('--route=')) routeArgs.push(a.slice(8));
+  else if (a === '--out') out = argv[++i];
+  else if (a.startsWith('--out=')) out = a.slice(6);
+  else if (a === '--max-actions') maxActions = Number(argv[++i]);
+  else if (a.startsWith('--max-actions=')) maxActions = Number(a.slice(14));
+  else if (a === '--width') width = Number(argv[++i]);
+  else if (a.startsWith('--width=')) width = Number(a.slice(8));
+  else if (a === '--height') height = Number(argv[++i]);
+  else if (a.startsWith('--height=')) height = Number(a.slice(9));
+  else if (a === '--strict') strict = true;
+  else if (a.startsWith('--')) {
+    console.error(unknownFlagMessage('styleproof-variants', a));
+    process.exit(2);
+  } else {
+    routeArgs.push(a);
+  }
+}
+
+if (!baseUrl) {
+  console.error('styleproof-variants: --base-url is required');
+  process.exit(2);
+}
+if (!routeArgs.length) {
+  console.error('styleproof-variants: at least one --route is required');
+  process.exit(2);
+}
+if (![maxActions, width, height].every(Number.isFinite)) {
+  console.error('styleproof-variants: --max-actions, --width, and --height must be numbers');
+  process.exit(2);
+}
+
+function parseRoute(input) {
+  const eq = input.indexOf('=');
+  if (eq > 0) return { key: input.slice(0, eq), url: input.slice(eq + 1) };
+  return { key: defaultLinkKey(new URL(input, baseUrl)), url: input };
+}
+
+const browser = await chromium.launch();
+try {
+  const page = await browser.newPage({ viewport: { width, height } });
+  const harvest = await harvestStyleVariants(page, {
+    baseUrl,
+    routes: routeArgs.map(parseRoute),
+    maxActionsPerRoute: maxActions,
+  });
+  fs.writeFileSync(out, JSON.stringify(harvest, null, 2) + '\n');
+  const variants = harvest.routes.reduce((sum, route) => sum + route.variants.length, 0);
+  const liveStates = harvest.routes.reduce((sum, route) => sum + route.liveStates.length, 0);
+  const skipped = harvest.routes.reduce((sum, route) => sum + route.skipped.length, 0);
+  console.log(`styleproof-variants: wrote ${out}`);
+  console.log(`${variants} variant(s), ${liveStates} live-state candidate(s), ${skipped} skipped candidate(s)`);
+  if (strict && (liveStates || skipped)) process.exit(1);
+} finally {
+  await browser.close();
+}

package/dist/action-context.d.ts

@@ -0,0 +1,38 @@
+export type ActionContextInput = {
+    eventName: string;
+    payload: {
+        pull_request?: {
+            number?: number;
+            head?: {
+                sha?: string;
+            };
+        };
+        workflow_run?: {
+            head_sha?: string;
+            pull_requests?: {
+                number?: number;
+            }[];
+        };
+    };
+    repo: Record<string, string>;
+    github: {
+        rest: {
+            repos: {
+                listPullRequestsAssociatedWithCommit: (args: Record<string, string>) => Promise<{
+                    data: {
+                        state?: string;
+                        number?: number;
+                        head?: {
+                            sha?: string;
+                        };
+                    }[];
+                }>;
+            };
+        };
+    };
+};
+export type ActionContextResult = {
+    prNumber: string;
+    headSha: string;
+};
+export declare function resolveActionContext({ eventName, payload, repo, github, }: ActionContextInput): Promise<ActionContextResult>;

package/dist/action-context.js

@@ -0,0 +1,17 @@
+export async function resolveActionContext({ eventName, payload, repo, github, }) {
+    let prNumber = payload.pull_request?.number;
+    let headSha = payload.pull_request?.head?.sha;
+    if (eventName === 'workflow_run') {
+        const run = payload.workflow_run;
+        headSha = run?.head_sha;
+        prNumber = run?.pull_requests?.[0]?.number;
+        if (headSha && !prNumber) {
+            const { data } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+                ...repo,
+                commit_sha: headSha,
+            });
+            prNumber = data.find((pr) => pr.state === 'open' && pr.head?.sha === headSha)?.number;
+        }
+    }
+    return prNumber && headSha ? { prNumber: String(prNumber), headSha } : { prNumber: '', headSha: '' };
+}

package/dist/capture.d.ts

@@ -69,6 +69,16 @@ export type LiveRegionCandidate = {
     ariaLive?: string;
     ariaBusy?: string;
 };
+export type CapturedOverlay = {
+    path: string;
+    tag: string;
+    cls: string;
+    reason: string;
+    role?: string;
+    ariaModal?: string;
+    ariaLive?: string;
+    text?: string;
+};
 export type StyleMap = {
     /** Optional runner-supplied context; ignored by the certification diff. */
     metadata?: CaptureMetadata;
@@ -98,6 +108,14 @@ export type StyleMap = {
      * regions that actually keep changing are auto-excluded via `volatile`.
      */
     liveCandidates?: LiveRegionCandidate[];
+    /**
+     * Visible semantic overlay roots that were present in the captured DOM and
+     * whose paths are present in `elements`. This is diagnostic/proof metadata:
+     * dialogs, menus, listboxes, modal roots and toast roots are still certified by
+     * the normal computed-style map, while this list lets tests prove those states
+     * were actually reached and captured.
+     */
+    overlays?: CapturedOverlay[];
     /**
      * Colour-valued `:root` custom properties (design/theme tokens), normalised to
      * the same `rgb(...)` form the longhands resolve to — `{ "--red-200": "rgb(254,