styleproof 3.1.4 → 3.2.0

package/CHANGELOG.md

@@ -7,6 +7,71 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.2.0] - 2026-06-30
+
+### Added
+
+- Added optional `styleproof-map --crawl-base-url ... --crawl-route ...` pre-map
+  variant crawling, so automation can refresh the generated variant manifest
+  immediately before map capture.
+
+### Changed
+
+- `styleproof-init` now writes a dedicated `playwright.styleproof.config.ts`,
+  scopes discovery to the StyleProof spec, detects Vite/Next production preview
+  commands, and respects pnpm/Corepack pins in generated commands.
+- Map upload dirty-tree detection now ignores Next's generated `next-env.d.ts`
+  shim, while normal source edits still block upload.
+
+## [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 +1074,10 @@ 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.2.0...HEAD
+[3.2.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.5...v3.2.0
+[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,28 +1,138 @@
 # 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
-
-On every PR, StyleProof diffs the PR head's computed-style map against the base branch's, and posts a Markdown comment:
+## 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)
+- [Auto-discovery](#auto-discovery)
+- [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)
 
-- 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).
-
-## Don't let a new page ship uncaptured
+## Why
 
-StyleProof diffs the surfaces your spec lists — so a page nobody added to the list is invisible to the gate. Its change has no base capture _and_ no head capture, so it never appears in any diff, and the status goes green having never looked at it. This is the one thing the captures can't catch on their own: a capture that was never taken.
+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 or auto-discover 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.
+
+Auto-discovery is a key feature, not a side path: StyleProof can discover
+Next.js routes, crawl real nav links, inventory component files, harvest
+one-step variants, click safe popups, detect breakpoints, and flag live or
+volatile regions. You review the app-specific leftovers; StyleProof keeps the
+mechanical inventory from drifting.
+
+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`.
+
+## Auto-discovery
+
+StyleProof's auto-discovery keeps the boring inventory out of your hands where it
+can be inferred safely: Next.js routes, crawlable links, component files,
+semantic popups, one-step variants, breakpoints, and volatile/live candidates.
+The key loop is simple: discover what the app exposes, capture what is safe, and
+fail loudly for anything that still needs an owner.
+
+StyleProof diffs the surfaces your spec lists or discovers — so a page nobody
+added to either set is invisible to the gate. Its change has no base capture
+_and_ no head capture, so it never appears in any diff, and the status goes
+green having never looked at it. This is the one thing the captures can't catch
+on their own: a capture that was never taken.
 
 Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
 
@@ -80,6 +190,144 @@ 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. To refresh that
+manifest as part of the map loop, pass the same crawl inputs to `styleproof-map`;
+it runs the crawler before Playwright captures the maps:
+
+```bash
+styleproof-map --crawl-base-url http://localhost:3000 --crawl-route / --crawl-route settings=/settings
+```
+
+The app must already be reachable at `--crawl-base-url`. If Playwright's
+`webServer` is the thing starting the app, keep route-link crawling inside the
+capture run with `defineCrawlCapture`.
+
+```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
@@ -169,7 +417,7 @@ 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 dedicated **`playwright.styleproof.config.ts`** that builds and serves a **production build** (never a flaky dev server), scopes discovery to the StyleProof spec, and captures surfaces **in parallel** (`fullyParallel`) without disturbing your app's existing Playwright config;
 - `.gitignore` entries for `.styleproof/`, `test-results/`, and `playwright-report/`;
 - a **cache-first CI workflow** that restores reusable maps from the `styleproof-maps` branch and generates the report without a browser when both maps are already built.
 
@@ -312,16 +560,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,44 +640,48 @@ 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.
 
 **Capture env vars** (wire CI without editing the spec):
 
-| Env                       | Purpose                                                                                                               |
-| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
-| `STYLEMAP_DIR`            | Output label; the capture is skipped entirely when unset.                                                             |
-| `STYLEPROOF_BASEDIR`      | Output root dir (runner default `__stylemaps__`; `styleproof-map` CLI default `.styleproof/maps`).                    |
-| `STYLEPROOF_SCREENSHOTS`  | `0` to skip full-page screenshots. The CLI keeps screenshots by default so reports can crop maps restored from cache. |
-| `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.                                                         |
-| `STYLEPROOF_UPLOAD`       | `1` to require map-store upload; `0` to capture locally only.                                                         |
-| `STYLEPROOF_CACHE_BRANCH` | Map store branch (default `styleproof-maps`).                                                                         |
+| Env                         | Purpose                                                                                                               |
+| --------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `STYLEMAP_DIR`              | Output label; the capture is skipped entirely when unset.                                                             |
+| `STYLEPROOF_BASEDIR`        | Output root dir (runner default `__stylemaps__`; `styleproof-map` CLI default `.styleproof/maps`).                    |
+| `STYLEPROOF_SCREENSHOTS`    | `0` to skip full-page screenshots. The CLI keeps screenshots by default so reports can crop maps restored from cache. |
+| `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.                                                         |
+| `STYLEPROOF_UPLOAD`         | `1` to require map-store upload; `0` to capture locally only.                                                         |
+| `STYLEPROOF_CACHE_BRANCH`   | Map store branch (default `styleproof-maps`).                                                                         |
+| `STYLEPROOF_CRAWL_BASE_URL` | App URL for the optional pre-map `styleproof-variants` crawl.                                                         |
+| `STYLEPROOF_CRAWL_ROUTES`   | Comma-separated routes for the optional pre-map crawl, e.g. `/,settings=/settings`.                                   |
+| `STYLEPROOF_CRAWL_STRICT`   | `1` to fail the optional pre-map crawl on live-state fixtures or skipped candidates.                                  |
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `styleproof-init` — scaffold the gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default) instead of assuming npm.
-- `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-init` — scaffold the gate: the capture spec, a dedicated `playwright.styleproof.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
+- `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 `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--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.