styleproof 3.1.5 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- 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
@@ -56,6 +108,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
@@ -1058,7 +1117,8 @@ 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.5...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

package/README.md

@@ -16,11 +16,12 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [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)
+- [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)
+- [Match a design pixel-for-pixel](#match-a-design-pixel-for-pixel)
 - [Install](#install)
 - [Quickstart](#quickstart)
 - [Forks and Dependabot](#forks-and-dependabot)
@@ -52,13 +53,15 @@ 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
 
 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.
+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
@@ -94,6 +97,12 @@ states that matter:
 - 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.
@@ -111,12 +120,22 @@ 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
 
-## Don't let a new page ship uncaptured
+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 — 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.
+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:
 
@@ -258,9 +277,17 @@ styles. It also reports live-state candidates that need fixtures or opt-outs.
 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`.
+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
 {
@@ -373,6 +400,36 @@ 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.
+
 ## Install
 
 ```bash
@@ -393,7 +450,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.
 
@@ -596,7 +653,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:
 
@@ -637,22 +694,25 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 **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-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-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; 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,136 @@
+#!/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 } 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). Crawl defaults to 1280 when omitted.
+
+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)
+  --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;
+try {
+  opts = parseCaptureUrlArgs(argv);
+} 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.length ? opts.widths : [1280],
+      ignore: opts.ignore,
+      height: opts.height,
+      screenshots: opts.screenshots,
+      waitSelector: opts.waitSelector,
+      maxDepth: opts.maxDepth,
+      maxActionsPerState: opts.maxActionsPerState,
+      maxStates: opts.maxStates,
+      resetStorage: opts.resetStorage,
+      // 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-init.mjs

@@ -11,14 +11,15 @@
  *     the `expected` coverage guard from the app's routes at run time, so a page
  *     added later can't ship without a surface; otherwise it writes one sample
  *     surface plus a commented guard block to wire to your own route registry.
- *   - playwright.config.ts: only if one does not already exist, so an existing
- *     Playwright project is never disturbed.
+ *   - playwright.styleproof.config.ts: a dedicated production-build Playwright
+ *     config for StyleProof captures, so an existing app Playwright config is
+ *     never disturbed or accidentally reused.
  *   - .github/workflows/styleproof.yml: restores reusable maps from the
  *     styleproof-maps branch and only captures in CI when the maps are missing.
  *
  * Idempotent: re-running never overwrites an existing spec (use --force) and
- * never touches an existing playwright.config.ts. Exit 0 = done (or nothing to
- * do), 2 = usage error.
+ * never touches an existing app playwright.config.ts. Exit 0 = done (or nothing
+ * to do), 2 = usage error.
  */
 import fs from 'node:fs';
 import path from 'node:path';
@@ -31,7 +32,7 @@ usage: styleproof-init [options]
 
 options:
   --dir <path>        spec output path (default: e2e/styleproof.spec.ts)
-  --base-url <url>    baseURL for a generated playwright.config.ts
+  --base-url <url>    baseURL for a generated playwright.styleproof.config.ts
                       (default: http://localhost:3000)
   --force             overwrite the spec if it already exists
   -h, --help          show this help
@@ -41,7 +42,7 @@ What it writes:
     In a Next.js app it discovers your routes at run time and wires both the
     surfaces and the \`expected\` coverage guard to them, so a new page can't ship
     uncaptured. Otherwise it writes one sample surface + a commented guard block.
-  - playwright.config.ts, only if absent (an existing one is left untouched)
+  - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
 After running, build and upload this commit's map outside CI when possible:
@@ -237,14 +238,15 @@ const PACKAGE_MANAGERS = {
   },
   pnpm: {
     label: 'pnpm',
-    run: (script) => `npx -y pnpm ${script}`,
-    exec: (command) => `npx -y pnpm exec ${command}`,
-    install: 'npx -y pnpm install --frozen-lockfile',
+    run: (script) => `pnpm run ${script}`,
+    exec: (command) => `pnpm exec ${command}`,
+    install: 'pnpm install --frozen-lockfile',
     setup: `      - uses: actions/setup-node@v4
         with:
           node-version: '20'
           cache: pnpm
-          cache-dependency-path: pnpm-lock.yaml`,
+          cache-dependency-path: pnpm-lock.yaml
+      - run: corepack enable`,
   },
   bun: {
     label: 'Bun',
@@ -269,6 +271,57 @@ function detectPackageManager(root) {
 
 const PM = detectPackageManager(process.cwd());
 
+function readPackageJson(root) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(root, 'package.json'), 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+function hasDep(pkg, name) {
+  return Boolean(pkg.dependencies?.[name] ?? pkg.devDependencies?.[name]);
+}
+
+function scriptIncludes(pkg, script, text) {
+  return typeof pkg.scripts?.[script] === 'string' && pkg.scripts[script].includes(text);
+}
+
+function portFromBaseUrl(url) {
+  try {
+    const parsed = new URL(url);
+    if (parsed.port) return parsed.port;
+    return parsed.protocol === 'https:' ? '443' : '80';
+  } catch {
+    return '3000';
+  }
+}
+
+function productionServerCommand(root, base) {
+  const pkg = readPackageJson(root);
+  const port = portFromBaseUrl(base);
+  const build = pkg.scripts?.build ? `${PM.run('build')} && ` : '';
+  const looksLikeVite =
+    hasDep(pkg, 'vite') || scriptIncludes(pkg, 'dev', 'vite') || scriptIncludes(pkg, 'build', 'vite');
+  const looksLikeNext =
+    hasDep(pkg, 'next') || scriptIncludes(pkg, 'dev', 'next') || scriptIncludes(pkg, 'build', 'next');
+
+  if (looksLikeVite) return `${build}${PM.exec(`vite preview --host 127.0.0.1 --port ${port}`)}`;
+  if (looksLikeNext) {
+    const start = pkg.scripts?.start ? PM.run('start') : PM.exec(`next start -p ${port}`);
+    return `${build}${start}`;
+  }
+  if (pkg.scripts?.start) return `${build}${PM.run('start')}`;
+  if (pkg.scripts?.preview) return `${build}${PM.run('preview')}`;
+  return `${PM.run('build')} && ${PM.run('start')}`;
+}
+
+function configTestDir(spec) {
+  const dir = path.dirname(path.resolve(process.cwd(), spec));
+  const rel = path.relative(process.cwd(), dir).replace(/\\/g, '/');
+  return rel ? `./${rel}` : '.';
+}
+
 const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 
 // Generated by styleproof-init.
@@ -280,6 +333,8 @@ const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 // app serves precompiled routes at consistent timing. (StyleProof's settle waits for
 // in-flight data either way, but a production build removes the variance at the source.)
 export default defineConfig({
+  testDir: ${JSON.stringify(configTestDir(specPath))},
+  testMatch: ${JSON.stringify(path.basename(specPath))},
   timeout: 120_000,
   // Capture surfaces in PARALLEL. StyleProof generates one test per surface × width,
   // each an isolated page writing a uniquely-keyed file (\`<key>@<width>.json.gz\`), with
@@ -293,11 +348,13 @@ export default defineConfig({
     baseURL: process.env.BASE_URL || '${baseUrl}',
   },
   // Build once, then serve THAT production build for the captures — so you can't
-  // accidentally capture a dev server. Adjust the command to your framework (e.g.
-  // \`vite build && vite preview\`); a server already running locally is reused.
+  // accidentally capture a dev server. styleproof-init detected the production
+  // serve command from your package scripts/dependencies; tune it here if your
+  // framework needs a custom preview command.
   webServer: {
-    command: '${PM.run('build')} && ${PM.run('start')}',
+    command: '${productionServerCommand(process.cwd(), baseUrl)}',
     url: process.env.BASE_URL || '${baseUrl}',
+    env: { PORT: '${portFromBaseUrl(baseUrl)}' },
     reuseExistingServer: !process.env.CI,
     timeout: 600_000, // a cold production build can take a few minutes
   },
@@ -422,13 +479,18 @@ if (spec.wrote) {
   console.log(`${specPath} already exists — left untouched (use --force to overwrite)`);
 }
 
-const configPath = 'playwright.config.ts';
-if (fs.existsSync(configPath) || fs.existsSync('playwright.config.js')) {
-  console.log('playwright.config exists — left untouched; ensure its baseURL points at a production build');
-} else {
-  fs.writeFileSync(configPath, CONFIG);
-  console.log(`created ${configPath} (baseURL ${baseUrl})`);
+const configPath = 'playwright.styleproof.config.ts';
+const config = writeFileSafe(configPath, CONFIG, { force });
+if (config.wrote) {
+  console.log(`${config.exists ? 'overwrote' : 'created'} ${configPath} (dedicated StyleProof capture config)`);
   wroteSomething = true;
+} else {
+  console.log(`${configPath} already exists — left untouched (use --force to overwrite)`);
+}
+if (fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js')) {
+  console.log(
+    'app playwright.config exists — left untouched; styleproof-map uses playwright.styleproof.config.ts by default',
+  );
 }
 
 const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));