styleproof 3.2.0 → 3.4.0

package/CHANGELOG.md

@@ -7,6 +7,90 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.4.0] - 2026-07-02
+
+### Fixed
+
+- Consuming actions (controls that disappear when used — resolve/approve/dismiss
+  rows) no longer spawn a combinatorial decision lattice. Their result-states are
+  captured and swept RETRY-ONLY: the parent's persistent mode-switchers still
+  apply (a resolved list's tab view stays reachable), but no fresh candidates are
+  collected there — removed rows shift sibling nth-of-type selectors, which made
+  the same logical controls look "fresh" in every decided subset and could stall
+  an exhaustive crawl for hours adding zero coverage. Found live, on a
+  decision-heavy page whose crawl went 449 surfaces / 6 new classes before the
+  rule; with it, the same shape converges in single digits with full coverage.
+
+### Added
+
+- `styleproof-capture --setup <file>`: deterministic steps (goto/fill/click/
+  waitFor) run after every fresh navigation, so input-gated states — a login,
+  an unlock code, seeded input — become crawlable. `${ENV_VAR}` in values is
+  interpolated from the environment at load time, so credentials never live in
+  the file or the maps; a failed non-optional step aborts loudly.
+- Automatic data states: the crawl watches the entry page's data requests and
+  additionally captures `loading` (requests stalled — the skeleton) and `error`
+  (requests fulfilled with 500) out of the box. Identical-to-base renders dedup
+  away; `--no-data-states` to skip.
+- README: "What the crawler can and cannot reach — honestly" — the crawl
+  vocabulary, what each state class is reached by, and the verifier contract
+  that anything unreached is named, never silently missed.
+- Automatic neutral-input fill: text/search/email/tel/url/number inputs and
+  textareas are typed with a deterministic value, so input-driven states (a
+  search's results, a filter's rendering) are crawled with no config.
+  Credential-semantic fields (type=password, autocomplete username/
+  current-password/new-password/one-time-code) are never auto-filled — that is
+  `--setup` territory, the only input the tool cannot derive.
+- Automatic scroll reveal: a bounded, deterministic scroll pass on every load
+  mounts IntersectionObserver/lazy content before discovery, so scroll-gated
+  sections are part of the mapped surface.
+- The crawl now auto-detects the page's real `@media` breakpoints when no
+  `--widths` are given (like the one-shot path), sweeping one width per band.
+- `--setup` steps are honoured by the one-shot (non-crawl) capture too, so a
+  gated page's single state is capturable directly.
+
+### Fixed
+
+- Automatic data states now intercept by resource type (fetch/XHR) instead of
+  exact URL — apps that cache-bust their requests (`?t=...`) previously
+  slipped past the stall and produced no `loading` capture.
+
+## [3.3.0] - 2026-07-02
+
+### Added
+
+- New `styleproof-capture <url>` CLI: capture a single page (a deployed URL, a
+  static export, or a standalone HTML mockup) so you can prove a production build
+  renders identically to its design. Point it at the design and at the build,
+  diff the two, and zero diff means pixel-identical — anything else is named down
+  to the computed style. One shot, no spec, no config; writes the same
+  `<key>@<width>.json.gz` (+ `.png`) shape any capture does, so `styleproof-diff`
+  compares it against anything. Also exported programmatically as
+  `captureUrlToDir` / `runCaptureUrl` / `parseCaptureUrlArgs`.
+- `styleproof-capture --crawl`: map a whole interactive design from one URL with
+  no spec and no selectors — EXHAUSTIVE by default, running until every
+  non-destructive control has been driven once and every structurally new surface
+  captured (a modal's tabs, a drawer's sub-views, a popover's panels), each under
+  a derived key. The sweep works in place with lazy, fingerprint-verified resets:
+  a no-op click costs nothing, only state-changing clicks pay a fresh
+  navigation + replay, and children are never attributed to the wrong parent.
+  Deterministic, deduped by a structural fingerprint, self-settling for async
+  (React/Vue/Babel) apps, discovery pinned to one viewport width, progress
+  streamed per captured surface, and destructive-looking controls are never
+  clicked. `--max-depth` / `--max-actions` / `--max-states` exist only as
+  throttles. Exported programmatically as `crawlAndCapture`.
+- Crawl coverage verifier: after `--crawl`, every class the page's own
+  stylesheets define (parsed CSSOM) is checked against the classes rendered
+  across all captured surfaces, and the never-seen residue is printed — dead
+  CSS, or a state the crawl could not reach. `--require-full-coverage` makes
+  any residue exit 4, so "the design is fully covered, nothing missing" is a
+  machine-checked property. On `CrawlReport.coverage` programmatically.
+
+### Fixed
+
+- GitHub Action reports now publish every generated crop PNG, including zoom
+  crops, so committed `report.md` files do not point at missing images.
+
 ## [3.2.0] - 2026-06-30
 
 ### Added
@@ -72,6 +156,13 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [3.1.4] - 2026-06-29
 
+### Changed
+
+- New surfaces now require approval in review-gate mode. A new-surface-only diff
+  still exits `3`, but the Action marks `changed=true`, posts the report, and
+  holds the `StyleProof` status red until the reviewer approves it. Certify mode
+  was already strict because it fails on any report.
+
 ### Fixed
 
 - **Popup capture no longer collapses distinct triggers that reuse the same

package/README.md

@@ -21,6 +21,7 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [Works with any styling system](#works-with-any-styling-system)
 - [Breakpoints, detected automatically](#breakpoints-detected-automatically)
 - [Certify a refactor](#certify-a-refactor)
+- [Match a design pixel-for-pixel](#match-a-design-pixel-for-pixel)
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Forks and Dependabot](#forks-and-dependabot)
@@ -52,7 +53,9 @@ The important boundary: StyleProof only certifies states it can reach. If a stat
 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.
+silently passing. A surface that exists only on the PR head is still reviewable:
+in review-gate mode it holds the status red until approved, then becomes part of
+the baseline once merged.
 
 ## The short version
 
@@ -117,8 +120,8 @@ full report. The report groups each distinct visual change with:
 
 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`.
+changes detected.` New surfaces are shown as new baselines and require approval;
+coverage gaps are handled by `expected`.
 
 ## Auto-discovery
 
@@ -397,6 +400,77 @@ Omit `widths` on a surface and StyleProof reads your app's real `@media` breakpo
 
 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.
 
+## Match a design pixel-for-pixel
+
+When you build a design in production, "looks the same" is a judgement call — and small gaps ship. `styleproof-capture` makes it an objective check: point it at the **design** (a deployed mockup, a static export, a standalone HTML file), point it at your **build**, and diff. Zero diff means the production UI renders _identically_ to the design; anything else is named exactly, down to the computed style, so you know precisely what's still off.
+
+```bash
+styleproof-capture https://example.com/pricing --key pricing --widths 1440,1024,768 --out design
+styleproof-diff design .styleproof/maps/current   # design vs build — zero diff = pixel-identical
+```
+
+You watch one number as you implement: the diff starts large and shrinks toward zero, and it hits zero the moment the built page matches the design. It's the objective version of putting the mockup and the app side by side and squinting.
+
+(`styleproof-map` is the spec-driven flow for your own app's surfaces, with the coverage guard, map store, and record/replay; `styleproof-capture` is the one-shot for a page you just point at.) It writes `design/pricing@1440.json.gz` (+ `.png`), the same shape any capture writes, so `styleproof-diff` compares it against anything. Omit `--widths` to auto-detect the page's own `@media` breakpoints; pin them for a page whose CSS is cross-origin (a font stylesheet, say), since detection reads every sheet and fails loudly rather than guess. `--wait <selector>` holds until the intended state is on screen; `--ignore <selector>` skips a live region. Capture both sides in the same browser + fonts, since that's what "identical" is measured against.
+
+### Crawl the whole interactive design: `--crawl`
+
+A design is mostly _behind clicks_ — modals, drawers, popovers, tabs that don't exist in the DOM until you open them. A single capture sees only the landing state. `--crawl` maps the rest for you: point it at the URL and it drives every non-destructive control, keeps whatever opens a structurally new surface, and recurses into it — a modal's tabs, a drawer's sub-views, a popover's panels — capturing each under a derived key. No spec, no selectors, no hand-holding.
+
+```bash
+styleproof-capture https://example.com --crawl --out design    # maps every reachable surface
+styleproof-diff design .styleproof/maps/current                # diff the whole surface vs your build
+```
+
+It's **exhaustive by default**: the crawl stops when there is nothing left to drive — every control tried once, every structurally new surface captured — not at a budget. Termination is guaranteed by dedup (controls dedup by selector, surfaces by a structural fingerprint), and the `--max-depth` / `--max-actions` / `--max-states` flags exist only as deliberate throttles. It's deterministic (document order; the same surface reached two ways is captured once) and self-settling — it waits for an async app (React/Vue/Babel that boots after `load`) to mount before reading, so a bare crawl of a client-rendered page still captures the mounted UI.
+
+What makes exhaustive affordable is that the sweep works **in place**: standing in a state, each control is clicked right where the page is, and a cheap DOM fingerprint decides what happened — a no-op click costs nothing, and only a state-changing click pays a reset (fresh navigation + replay of the click-path), which is then **verified by fingerprint** so children are never attributed to the wrong parent. New surfaces are captured at every width the moment they're reached — a deep or animated click-path is never re-driven to capture, so it can't be the thing that drops a surface. Progress streams as it goes, one line per captured surface.
+
+**And it proves nothing was missed.** After the crawl, StyleProof compares every class the page's own stylesheets define (read from the parsed CSSOM) against the classes actually rendered across the captured surfaces, and prints what — if anything — was never seen. `--require-full-coverage` turns any residue into exit code 4, so "the design is fully covered" is a CI-checkable property, not a judgement call. What's left is either dead CSS (delete it) or a state the crawl couldn't reach (drive it with a spec, or file the gap).
+
+**Destructive-looking controls (delete, deploy, pay, revoke…) are never clicked** — mapping must not mutate; states gated behind one of those need a spec. Prefer the spec-driven `defineStyleMapCapture` when you want stable, named keys and the coverage guard; reach for `--crawl` to map a design (or a third-party page) you don't have a spec for.
+
+### Data states, out of the box
+
+Every data-driven page has states that almost never sit on a click path: the **loading skeleton** and the **error render**. The crawl captures both automatically — it watches the entry page's data requests, then re-loads once with them **stalled** (the skeleton is the settled state, captured as `loading`) and once with them **fulfilled as 500** (captured as `error`). States that render identically to the base (e.g. server-rendered pages) dedup away silently. On by default; `--no-data-states` to skip. Deeper data states — a specific empty list, a partial payload — are fixture territory: model them as `liveStates`/`variants` in a spec.
+
+### Input-gated states: `--setup`
+
+A crawler clicks and selects; it does not guess your password. States behind typed input — a login, an unlock code, a seeded search — become crawlable with a deterministic setup file, run after **every** fresh navigation so each reset re-establishes the gate identically:
+
+```json
+[
+  { "action": "fill", "selector": "#user", "value": "${CAPTURE_USER}" },
+  { "action": "fill", "selector": "#pass", "value": "${CAPTURE_PASS}" },
+  { "action": "click", "selector": "#sign-in" },
+  { "action": "waitFor", "selector": ".dashboard" }
+]
+```
+
+```bash
+CAPTURE_USER=demo CAPTURE_PASS=… styleproof-capture https://example.com --crawl --setup login.json --out design
+```
+
+`${ENV_VAR}` in `value`/`url` is interpolated from the environment at load time — **credentials never live in the file, the shell history, or the captured maps.** A non-optional step that fails aborts the crawl loudly (a half-established gate must never silently crawl the ungated page); mark a step `"optional": true` when it legitimately may not apply (a cookie-session app that shows the login form only once).
+
+### What the crawler can and cannot reach — honestly
+
+The crawl's vocabulary is **click, select, neutral typing, scrolling, and your setup steps** — and it sweeps the page's real `@media` breakpoints automatically when you give it none. Within it, mapping is exhaustive. Outside it, states are not reached by crawling — and the coverage verifier is what keeps that honest: anything unreached is _named_, never silently missed.
+
+| State                                                                        | Reached by                                                                                                                                                                            |
+| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Click-opened surfaces (modals, drawers, popovers, tabs, toggles)             | crawl, automatically                                                                                                                                                                  |
+| Mode × sibling combinations (a tab's edit state, a decided list's other tab) | crawl — family retry                                                                                                                                                                  |
+| Loading / error data states of the entry page                                | crawl — automatic data states                                                                                                                                                         |
+| Login / unlock / typed input                                                 | `--setup` steps                                                                                                                                                                       |
+| `:hover` / `:focus` / `:active` styling                                      | the forced-state layer of every capture                                                                                                                                               |
+| Deeper data states (empty, partial, streaming)                               | spec `liveStates` / `variants` with fixtures                                                                                                                                          |
+| States behind destructive actions                                            | a spec, deliberately — the crawl never clicks them                                                                                                                                    |
+| Drag-and-drop, keyboard-shortcut, scroll-triggered states                    | a spec driving them explicitly                                                                                                                                                        |
+| Components not mounted anywhere in the UI                                    | a component catalog page (each component per prop-state is a surface — Storybook/Ladle stories work; `discoverComponentFiles` fails CI when a component file has no captured surface) |
+
+The rule of thumb: **a rendered state is a function of props, data, and input.** Control all three — mock the data, script the input, mount the component — and every state a component can render is a capturable surface. The verifier tells you, by name, which ones you haven't controlled yet.
+
 ## Install
 
 ```bash
@@ -620,7 +694,7 @@ When a PR **adds** an element, StyleProof now reports its **full resting compute
 | `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).
+Outputs: `changed` (`"true"` when any existing surface changed, or a new surface needs approval), `report-url`. Other inputs (`report-branch`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/action.yml).
 
 **Policy file `styleproof.config.json`** (optional, at the repo root) — gate policy that isn't workflow plumbing:
 
@@ -679,7 +753,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `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-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; approval policy decides whether to gate). 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.
 

package/bin/styleproof-capture.mjs

@@ -0,0 +1,148 @@
+#!/usr/bin/env node
+/**
+ * Capture a single URL's computed-style map — one shot, no spec, no config.
+ *
+ *   styleproof-capture <url> [options]
+ *
+ * For a page you just want to point at: a deployed URL, a static export, or a
+ * standalone HTML mockup. Writes `<key>@<width>.json.gz` (+ `.png`) into --out,
+ * the same shape a surface capture writes, so `styleproof-diff <a> <b>` compares
+ * it against any other capture. Capture a design mockup once, then diff each
+ * build against it to measure how close the implementation is.
+ *
+ * (Use styleproof-map — the spec-driven flow — for your own app's surfaces, where
+ * you also want the coverage guard, the map store, and record/replay.)
+ *
+ * Exit code 0 = captured, 2 = usage error, 3 = capture failed (e.g. browser
+ * missing, page unreachable, cross-origin CSS with no explicit --widths).
+ */
+import { chromium } from '@playwright/test';
+import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
+import { UsageError, parseCaptureUrlArgs, runCaptureUrl, loadSetupSteps } from '../dist/capture-url.js';
+import { crawlAndCapture } from '../dist/crawl-surfaces.js';
+
+const COMMAND = 'styleproof-capture';
+
+const HELP = `${COMMAND} — capture a page's computed-style map(s) (no spec, no config)
+
+usage: ${COMMAND} <url> [options]
+
+one state (default): capture the page as it loads
+  --key <name>      capture file prefix, <key>@<width>.json.gz (default: page)
+  --wait <selector> wait for this selector to be visible before capturing
+  --widths <csv>    viewport widths, e.g. 1440,1024,768. Omit to detect the
+                    page's own @media breakpoints (fails on cross-origin CSS —
+                    pass widths for those). The crawl auto-detects too.
+
+whole surface: --crawl
+  --crawl           EXHAUSTIVE: drive every non-destructive control, recurse into
+                    what opens, and capture every discovered surface under a derived
+                    key — runs to natural termination, no budget. For a design that's
+                    mostly modals/drawers/popovers. Destructive-looking controls
+                    (delete/deploy/pay/revoke…) are never clicked.
+  --require-full-coverage
+                    exit 4 unless every class the page's stylesheets define was
+                    rendered in a captured surface — the machine check that
+                    NOTHING in the design was missed (coverage is always printed)
+  --setup <file>    JSON steps (goto/fill/click/waitFor) run after EVERY fresh
+                    navigation — how input-gated states (login, unlock) become
+                    crawlable. \${ENV_VAR} in value/url is read from the
+                    environment, so secrets never live in the file or the maps.
+  --no-data-states  skip the automatic loading/error captures of the entry page
+                    (on by default: data requests stalled → loading skeleton;
+                    fulfilled with 500 → error render)
+  --max-depth <n>   throttle recursion depth (default: unbounded)
+  --max-actions <n> throttle controls tried per state (default: unbounded)
+  --max-states <n>  throttle total surfaces (default: unbounded)
+  --no-reset-storage  don't clear localStorage between steps (default: clear)
+
+common:
+  --out <dir>       output directory (default: styleproof-capture)
+  --ignore <sel>    skip a nondeterministic region (repeatable)
+  --height <px>     viewport height (default: 800)
+  --no-screenshots  write lean .json.gz maps only (screenshots on by default)
+  -h, --help        show this help
+
+Then diff against another capture — zero diff = pixel-identical:
+  ${COMMAND} https://example.com --crawl --out design
+  styleproof-diff design .styleproof/maps/current
+
+exit: 0 captured, 2 usage error, 3 capture failed, 4 coverage gap (--require-full-coverage).
+`;
+
+const argv = process.argv.slice(2);
+if (isHelpArg(argv[0])) showHelpAndExit(HELP);
+
+let opts;
+let setupSteps;
+try {
+  opts = parseCaptureUrlArgs(argv);
+  setupSteps = opts.setupFile ? loadSetupSteps(opts.setupFile) : undefined;
+  opts.setup = setupSteps; // one-shot capture honours setup steps too
+} catch (e) {
+  if (e instanceof UsageError) {
+    console.error(`${COMMAND}: ${e.message}\nNext: run ${COMMAND} --help to see supported options.`);
+    process.exit(2);
+  }
+  throw e;
+}
+
+async function runCrawl() {
+  const browser = await chromium.launch();
+  try {
+    const page = await browser.newPage();
+    const crawlOpts = {
+      url: opts.url,
+      out: opts.out,
+      widths: opts.widths, // empty = auto-detect the page's real breakpoints
+      ignore: opts.ignore,
+      height: opts.height,
+      screenshots: opts.screenshots,
+      waitSelector: opts.waitSelector,
+      maxDepth: opts.maxDepth,
+      maxActionsPerState: opts.maxActionsPerState,
+      maxStates: opts.maxStates,
+      resetStorage: opts.resetStorage,
+      setup: setupSteps,
+      dataStates: opts.dataStates,
+      // Stream each surface as it is captured, so progress is visible live and an
+      // interrupted run still shows exactly what it mapped.
+      onSurface: (s, ok) =>
+        console.log(`  ${'·'.repeat(s.depth)}${s.key} (${s.elements} elements)${ok ? '' : ' — CAPTURE FAILED'}`),
+    };
+    const report = await crawlAndCapture(page, crawlOpts);
+    console.log(
+      `✓ ${report.captured}/${report.surfaces.length} surface(s) × ${crawlOpts.widths.length} width(s) → ${opts.out}  ` +
+        `(${report.actionsTried} actions tried, ${report.skipped} skipped${report.failed.length ? `, ${report.failed.length} capture-failed` : ''})`,
+    );
+    const cov = report.coverage;
+    if (cov.missing.length === 0) {
+      console.log(`✓ coverage: all ${cov.defined} stylesheet classes rendered in at least one captured surface`);
+    } else {
+      console.log(
+        `⚠ coverage: ${cov.rendered}/${cov.defined} stylesheet classes rendered — ${cov.missing.length} never seen ` +
+          `(dead CSS, or a state the crawl could not reach):\n    ${cov.missing.join(' ')}`,
+      );
+      if (opts.requireFullCoverage) process.exit(4);
+    }
+  } finally {
+    await browser.close();
+  }
+}
+
+try {
+  if (opts.crawl) {
+    await runCrawl();
+    process.exit(0);
+  }
+  const results = await runCaptureUrl(opts, () => chromium.launch());
+  for (const r of results) console.log(`captured ${r.map}${r.screenshot ? ` (+ ${r.screenshot})` : ''}`);
+  console.log(`✓ ${results.length} capture(s) → ${opts.out}`);
+  process.exit(0);
+} catch (e) {
+  console.error(`${COMMAND}: capture failed: ${e instanceof Error ? e.message : String(e)}`);
+  console.error(
+    'Next: check the URL is reachable and run `npx playwright install chromium` if the browser is missing.',
+  );
+  process.exit(3);
+}

package/bin/styleproof-diff.mjs

@@ -181,7 +181,7 @@ console.log(
   total === 0
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
-      : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — shown for reference, no reviewable change`
+      : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
     : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}`,
 );
 // 0 = identical, 1 = reviewable differences, 3 = only new surfaces (no baseline,

package/bin/styleproof-report.mjs

@@ -36,8 +36,8 @@ options:
   --remote <name>            git remote for the map store (default: ${DEFAULT_REMOTE})
   --out <dir>               output directory (default: styleproof-report)
   --image-base-url <url>    prefix for image URLs in report.md (default: relative)
-  --pad <px>                padding around changed rects when cropping (default: 24)
-  --max-crops <n>           max crop regions per surface before collapsing (default: 6)
+  --pad <px>                padding around changed rects when cropping (default: 12)
+  --max-crops <n>           max crop regions per surface before collapsing (default: 8)
   --fold-details-at <n>     row count at which a crop's property tables fold under a
                             <details> toggle (default: 0 = always; 'Infinity' = never)
   --min-width <px>          minimum crop width, for context (default: 320)
@@ -178,7 +178,7 @@ console.log(
   result.changedSurfaces === 0
     ? result.newSurfaces === 0
       ? '✓ no changes — empty report written'
-      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for reference`
+      : `ℹ ${result.newSurfaces} new surface(s) with no baseline — report written for review`
     : `✗ ${result.changedSurfaces} changed surface(s), ${result.totalFindings} finding(s)${newNote}`,
 );
 console.log(`report: ${result.reportMdPath}`);

package/dist/capture-url.d.ts

@@ -0,0 +1,97 @@
+import type { Browser, Page } from '@playwright/test';
+import { type SetupStep } from './crawl-surfaces.js';
+/**
+ * One-shot capture of a single URL's computed-style map — no spec, no config,
+ * no git. `defineStyleMapCapture` is the right tool when the surfaces live in
+ * your own app and you want the coverage guard, the map store, and record/replay.
+ * This is the tool for a page you just want to point at: a deployed URL, a
+ * static export, or a standalone HTML mockup. Capture it into a directory of
+ * `<key>@<width>.json.gz` maps (+ `.png`) that {@link diffStyleMapDirs} — i.e.
+ * `styleproof-diff <a> <b>` — compares like any other capture.
+ *
+ * The output is deliberately the same shape a surface capture writes, so a
+ * mockup's map and your app's committed map are directly diffable: capture the
+ * design once, then diff each build against it to measure how close the
+ * implementation is (a diff that shrinks toward zero as it converges).
+ */
+/** Raised for bad CLI usage so the bin can print help and exit 2. */
+export declare class UsageError extends Error {
+}
+export type CaptureUrlOptions = {
+    /** Page to capture. */
+    url: string;
+    /** Capture file name prefix (`<key>@<width>.json.gz`); default `page`. */
+    key: string;
+    /**
+     * Viewport widths to sweep, one per @media band. Empty = auto-detect from the
+     * loaded CSSOM (fails loudly on a cross-origin/unreadable stylesheet — pass
+     * widths explicitly for a page whose CSS can't be read, e.g. a cross-origin
+     * font stylesheet).
+     */
+    widths: number[];
+    /** Output directory for the maps (+ screenshots). */
+    out: string;
+    /** Selectors for nondeterministic regions to skip (passed through to capture). */
+    ignore: string[];
+    /** Wait for this selector to be visible before capturing (reach the intended state). */
+    waitSelector?: string;
+    /** Viewport height (default 800). */
+    height: number;
+    /** Also write a full-page `.png` per capture (default true). */
+    screenshots: boolean;
+    /**
+     * Crawl the URL's whole interactive surface instead of capturing one state:
+     * drive every non-destructive control, recurse into what opens, capture each
+     * discovered surface under a derived key. See {@link crawlAndCapture}.
+     */
+    crawl: boolean;
+    /** crawl: recursion depth into opened surfaces (default 3). */
+    maxDepth: number;
+    /** crawl: fresh controls driven per state (default: unbounded — try them all). */
+    maxActionsPerState: number;
+    /** crawl: safety backstop on total surfaces (default: unbounded — exhaustive). */
+    maxStates: number;
+    /** crawl: clear storage on each reset so replay is deterministic (default true). */
+    resetStorage: boolean;
+    /** crawl: exit non-zero unless every class the page's stylesheets define was
+     *  rendered in at least one captured surface (default false — report only). */
+    requireFullCoverage: boolean;
+    /** crawl: JSON file of deterministic setup steps (login, unlock, seed input)
+     *  run after every fresh navigation. See {@link loadSetupSteps}. */
+    setupFile?: string;
+    /** Loaded setup steps (set by the CLI from `setupFile`); applied after every
+     *  navigation in BOTH modes, so a gated page's single state is capturable too. */
+    setup?: SetupStep[];
+    /** crawl: also capture automatic `loading`/`error` data states of the entry
+     *  page (default true). */
+    dataStates: boolean;
+};
+/**
+ * Parse `styleproof-capture` argv into options. Pure and throwing so the CLI
+ * flow (help/exit codes) and this parse are testable without a browser.
+ */
+export declare function parseCaptureUrlArgs(argv: string[]): CaptureUrlOptions;
+/** Written artifacts for one width. */
+export type CaptureUrlResult = {
+    width: number;
+    map: string;
+    screenshot?: string;
+};
+/**
+ * Capture `opts.url` at each width using an already-open {@link Page}, writing
+ * `<out>/<key>@<width>.json.gz` (+ `.png`). Re-navigates per width so
+ * width-dependent rendering (media queries, `matchMedia`) is captured fresh, and
+ * arms the in-flight request tracker before each navigation so the page's own
+ * load fetches count toward the network-aware settle — same contract as a
+ * surface capture. Returns the files written.
+ */
+export declare function captureUrlToDir(page: Page, opts: CaptureUrlOptions): Promise<CaptureUrlResult[]>;
+/** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */
+export declare function runCaptureUrl(opts: CaptureUrlOptions, launch: () => Promise<Browser>): Promise<CaptureUrlResult[]>;
+/**
+ * Load and validate a `--setup` steps file, interpolating `${ENV_VAR}` in every
+ * `value` and `url` from the environment — so credentials for an input-gated
+ * page live in env vars, never in the file, the shell history, or the maps.
+ * Throws {@link UsageError} on a malformed file or a missing variable.
+ */
+export declare function loadSetupSteps(file: string, env?: NodeJS.ProcessEnv): SetupStep[];