styleproof 3.2.0 → 3.3.0

package/CHANGELOG.md

@@ -7,6 +7,42 @@ 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
@@ -72,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

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,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
@@ -620,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:
 
@@ -679,7 +712,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,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-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,80 @@
+import type { Browser, Page } from '@playwright/test';
+/**
+ * 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;
+};
+/**
+ * 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[]>;

package/dist/capture-url.js

@@ -0,0 +1,185 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+import { detectViewportWidths } from './breakpoints.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 class UsageError extends Error {
+}
+const DEFAULTS = {
+    key: 'page',
+    height: 800,
+    screenshots: true,
+    crawl: false,
+    // Exhaustive by default — these are safety backstops, not budgets.
+    maxDepth: 1000,
+    maxActionsPerState: 100000,
+    maxStates: 100000,
+    resetStorage: true,
+    requireFullCoverage: false,
+};
+function positiveNumber(raw, flag) {
+    const n = Number(raw);
+    if (!Number.isFinite(n) || n <= 0)
+        throw new UsageError(`${flag}: not a positive number: ${raw}`);
+    return n;
+}
+function parseWidths(raw) {
+    const widths = raw
+        .split(',')
+        .map((s) => s.trim())
+        .filter(Boolean)
+        .map((s) => positiveNumber(s, '--widths'));
+    if (widths.length === 0)
+        throw new UsageError('--widths: no widths given');
+    return widths;
+}
+// Table-driven so adding a flag is one entry, not another branch in the loop.
+// value flags mutate the accumulator with their argument; bool flags take none.
+const VALUE_FLAGS = {
+    '--key': (o, v) => (o.key = v),
+    '--widths': (o, v) => (o.widths = parseWidths(v)),
+    '--out': (o, v) => (o.out = v),
+    '--ignore': (o, v) => o.ignore.push(v),
+    '--wait': (o, v) => (o.waitSelector = v),
+    '--height': (o, v) => (o.height = positiveNumber(v, '--height')),
+    '--max-depth': (o, v) => (o.maxDepth = positiveNumber(v, '--max-depth')),
+    '--max-actions': (o, v) => (o.maxActionsPerState = positiveNumber(v, '--max-actions')),
+    '--max-states': (o, v) => (o.maxStates = positiveNumber(v, '--max-states')),
+};
+const BOOL_FLAGS = {
+    '--screenshots': (o) => (o.screenshots = true),
+    '--no-screenshots': (o) => (o.screenshots = false),
+    '--crawl': (o) => (o.crawl = true),
+    '--no-reset-storage': (o) => (o.resetStorage = false),
+    '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+};
+// Apply one argv token to the accumulator; returns the index to resume from
+// (advanced past a consumed `--flag value` pair). Flat early-returns so the
+// parse loop stays trivial. Supports `--flag value` and `--flag=value`.
+function applyArg(o, argv, i, positional) {
+    const a = argv[i];
+    const eq = a.startsWith('--') ? a.indexOf('=') : -1;
+    const name = eq === -1 ? a : a.slice(0, eq);
+    const bool = BOOL_FLAGS[name];
+    if (bool) {
+        bool(o);
+        return i;
+    }
+    const apply = VALUE_FLAGS[name];
+    if (apply) {
+        const v = eq === -1 ? argv[i + 1] : a.slice(eq + 1);
+        if (v === undefined)
+            throw new UsageError(`${name}: missing value`);
+        apply(o, v);
+        return eq === -1 ? i + 1 : i;
+    }
+    if (a.startsWith('--'))
+        throw new UsageError(`unknown flag: ${a}`);
+    positional.push(a);
+    return i;
+}
+/**
+ * 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 function parseCaptureUrlArgs(argv) {
+    const o = {
+        url: '',
+        key: DEFAULTS.key,
+        widths: [],
+        out: 'styleproof-capture',
+        ignore: [],
+        waitSelector: undefined,
+        height: DEFAULTS.height,
+        screenshots: DEFAULTS.screenshots,
+        crawl: DEFAULTS.crawl,
+        maxDepth: DEFAULTS.maxDepth,
+        maxActionsPerState: DEFAULTS.maxActionsPerState,
+        maxStates: DEFAULTS.maxStates,
+        resetStorage: DEFAULTS.resetStorage,
+        requireFullCoverage: DEFAULTS.requireFullCoverage,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++)
+        i = applyArg(o, argv, i, positional);
+    if (positional.length === 0)
+        throw new UsageError('missing <url>');
+    if (positional.length > 1)
+        throw new UsageError(`expected one <url>, got ${positional.length}`);
+    o.url = positional[0];
+    return o;
+}
+/**
+ * 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 async function captureUrlToDir(page, opts) {
+    fs.mkdirSync(opts.out, { recursive: true });
+    let widths = opts.widths;
+    if (widths.length === 0) {
+        await page.setViewportSize({ width: 1280, height: opts.height });
+        await page.goto(opts.url, { waitUntil: 'load' });
+        if (opts.waitSelector)
+            await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+        widths = await detectViewportWidths(page);
+    }
+    const results = [];
+    for (const width of widths) {
+        await page.setViewportSize({ width, height: opts.height });
+        const requests = trackInflightRequests(page);
+        try {
+            await page.goto(opts.url, { waitUntil: 'load' });
+            if (opts.waitSelector)
+                await page.locator(opts.waitSelector).first().waitFor({ state: 'visible' });
+            const map = await captureStyleMap(page, {
+                ignore: opts.ignore,
+                pendingRequests: requests.pending,
+                metadata: { surfaceKey: opts.key },
+            });
+            const stem = path.join(opts.out, `${opts.key}@${width}`);
+            const mapPath = `${stem}.json.gz`;
+            saveStyleMap(mapPath, map);
+            const result = { width, map: mapPath };
+            if (opts.screenshots) {
+                const shot = `${stem}.png`;
+                // captureStyleMap froze animations, so the shot matches the mapped state.
+                await page.screenshot({ path: shot, fullPage: true, animations: 'disabled' });
+                result.screenshot = shot;
+            }
+            results.push(result);
+        }
+        finally {
+            requests.dispose();
+        }
+    }
+    return results;
+}
+/** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */
+export async function runCaptureUrl(opts, launch) {
+    const browser = await launch();
+    try {
+        const page = await browser.newPage();
+        return await captureUrlToDir(page, opts);
+    }
+    finally {
+        await browser.close();
+    }
+}

package/dist/crawl-surfaces.d.ts

@@ -0,0 +1,96 @@
+import type { Page } from '@playwright/test';
+/**
+ * Surface crawler: deterministically map a single URL's WHOLE interactive
+ * surface — not just the state it loads in — and run to natural termination.
+ *
+ * A one-shot capture records the page as it lands, so a design that's mostly
+ * modals, drawers, and popovers has most of its surface behind clicks it never
+ * reaches. This crawls it instead: from the base state it finds every visible,
+ * non-destructive control (semantic controls AND anything the page styles as
+ * clickable — `cursor: pointer`) and drives each one, keeping whatever opens a
+ * structurally new surface. It then recurses depth-first into each new surface,
+ * so a modal's tabs, a drawer's sub-views, and a popover's panels are all mapped.
+ *
+ * EXHAUSTIVE by default: the crawl stops when the queue drains and every control
+ * has been driven once — not at a budget. Termination is guaranteed by dedup
+ * (a control is driven once by selector; a structural surface is captured once;
+ * both sets are finite). The `--max-*` options exist only as throttles.
+ *
+ * The sweep is IN-PLACE with lazy resets, which is what makes exhaustive
+ * affordable: standing in a state, each candidate is clicked where the page
+ * already is, and a cheap DOM fingerprint (tag+class in document order — no
+ * computed styles) decides what happened. A no-op click costs nothing; only a
+ * state-changing click pays a reset (fresh navigation + path replay), and every
+ * reset is VERIFIED against the state's fingerprint before the sweep continues,
+ * so children are never attributed to the wrong parent. New surfaces are
+ * captured in place 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.
+ *
+ * Destructive-looking controls (delete, deploy, pay, revoke…) are never clicked —
+ * mapping must not mutate. States gated behind such an action need a spec.
+ */
+export type CrawlStep = {
+    action: 'click' | 'select-option';
+    selector: string;
+    label: string;
+    reason: string;
+    value?: string;
+};
+export type CrawledSurface = {
+    key: string;
+    depth: number;
+    path: CrawlStep[];
+    elements: number;
+};
+/** Did the crawl SEE everything the design styles? `missing` lists classes the
+ *  page's own stylesheets select on that never appeared in any captured surface —
+ *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+export type CrawlCoverage = {
+    defined: number;
+    rendered: number;
+    missing: string[];
+};
+export type CrawlReport = {
+    surfaces: CrawledSurface[];
+    actionsTried: number;
+    skipped: number;
+    /** Surfaces successfully captured to disk at every width. */
+    captured: number;
+    /** Keys of surfaces discovered but whose full capture failed. */
+    failed: string[];
+    coverage: CrawlCoverage;
+};
+export type SurfaceCrawlOptions = {
+    url: string;
+    out: string;
+    widths: number[];
+    ignore: string[];
+    height: number;
+    screenshots: boolean;
+    waitSelector?: string;
+    /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
+    maxDepth: number;
+    /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */
+    maxActionsPerState: number;
+    /** Throttle: total surfaces. Default: unbounded — run to natural termination. */
+    maxStates: number;
+    /** Clear localStorage/sessionStorage on each reset so replay is deterministic. Default true. */
+    resetStorage: boolean;
+    /** Called as each surface is recorded (captured=false when its full capture failed).
+     *  Lets CLIs stream progress instead of reporting only at the end. */
+    onSurface?: (surface: CrawledSurface, captured: boolean) => void;
+};
+export declare const CRAWL_DEFAULTS: {
+    height: number;
+    screenshots: boolean;
+    maxDepth: number;
+    maxActionsPerState: number;
+    maxStates: number;
+    resetStorage: boolean;
+};
+/**
+ * Crawl `opts.url` and capture every reachable surface at every width — runs to
+ * natural termination by default. Returns the surfaces mapped (with the click-path
+ * that reached each), how many actions were tried/skipped, and captured/failed.
+ */
+export declare function crawlAndCapture(page: Page, opts: SurfaceCrawlOptions): Promise<CrawlReport>;

package/dist/crawl-surfaces.js

@@ -0,0 +1,500 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
+// Exhaustive by default — these ceilings are safety backstops, not budgets.
+export const CRAWL_DEFAULTS = {
+    height: 900,
+    screenshots: true,
+    maxDepth: 1000,
+    maxActionsPerState: 100000,
+    maxStates: 100000,
+    resetStorage: true,
+};
+function slug(value) {
+    return (value
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 24) || 'state');
+}
+function pathAndSearch(url) {
+    try {
+        const u = new URL(url);
+        return u.pathname + u.search;
+    }
+    catch {
+        return url;
+    }
+}
+function deriveKey(steps, used) {
+    const base = steps.length === 0 ? 'base' : slug(steps[steps.length - 1].label);
+    let key = base;
+    for (let i = 2; used.has(key); i++)
+        key = `${base}-${i}`;
+    used.add(key);
+    return key;
+}
+/** Runs in the browser: every visible, enabled, non-navigating control worth trying. */
+/* c8 ignore start */ // fallow-ignore-next-line complexity
+function collectClickable() {
+    const SEMANTIC = 'button,summary,[role="button"],[role="tab"],[role="menuitem"],[role="combobox"],select,form';
+    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop)\b/i;
+    const esc = (v) => CSS.escape(v);
+    const quote = (v) => JSON.stringify(v);
+    const visible = (el) => {
+        const b = el.getBoundingClientRect();
+        const cs = getComputedStyle(el);
+        return (b.width > 0 && b.height > 0 && cs.display !== 'none' && cs.visibility !== 'hidden' && cs.pointerEvents !== 'none');
+    };
+    const unique = (s) => document.querySelectorAll(s).length === 1;
+    const pathSelector = (el) => {
+        const parts = [];
+        let cur = el;
+        while (cur && cur !== document.documentElement) {
+            let i = 1;
+            for (let sib = cur.previousElementSibling; sib; sib = sib.previousElementSibling)
+                if (sib.tagName === cur.tagName)
+                    i++;
+            parts.unshift(`${cur.tagName.toLowerCase()}:nth-of-type(${i})`);
+            cur = cur.parentElement;
+        }
+        return parts.join(' > ');
+    };
+    const selectorFor = (el) => {
+        const id = el.getAttribute('id');
+        if (id && unique(`#${esc(id)}`))
+            return `#${esc(id)}`;
+        for (const attr of ['data-testid', 'data-test', 'aria-label', 'name']) {
+            const v = el.getAttribute(attr);
+            if (v && unique(`${el.tagName.toLowerCase()}[${attr}=${quote(v)}]`))
+                return `${el.tagName.toLowerCase()}[${attr}=${quote(v)}]`;
+        }
+        return pathSelector(el);
+    };
+    const labelFor = (el) => (el.getAttribute('aria-label') || el.getAttribute('name') || el.textContent || '')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, 80) || el.tagName.toLowerCase();
+    // Semantic controls first (stable, meaningful), then anything styled clickable.
+    // `grab` counts too: a draggable card is routinely ALSO a click target (open on
+    // click, drag to move), and we never drag — el.click() fires no drag gesture.
+    const pool = new Set([...document.querySelectorAll(SEMANTIC)]);
+    for (const el of document.querySelectorAll('body *')) {
+        if (pool.has(el))
+            continue;
+        const cursor = getComputedStyle(el).cursor;
+        if (cursor === 'pointer' || cursor === 'grab')
+            pool.add(el);
+    }
+    const seen = new Set();
+    const out = [];
+    for (const el of pool) {
+        if (el instanceof HTMLAnchorElement && el.href)
+            continue; // links navigate — handled by link crawl, not here
+        if (el.closest(':disabled,[aria-disabled="true"]'))
+            continue;
+        if (!visible(el))
+            continue;
+        const selector = selectorFor(el);
+        if (seen.has(selector))
+            continue;
+        seen.add(selector);
+        const label = labelFor(el);
+        const unsafe = DANGER.test(label);
+        if (el instanceof HTMLSelectElement) {
+            const next = [...el.options].find((o) => !o.disabled && o.value !== el.value);
+            if (next)
+                out.push({ action: 'select-option', selector, label, reason: 'select-option', value: next.value, unsafe });
+        }
+        else {
+            out.push({
+                action: 'click',
+                selector,
+                label,
+                reason: el.getAttribute('role') === 'tab' ? 'tab' : 'click',
+                unsafe,
+            });
+        }
+    }
+    return out;
+}
+/* c8 ignore stop */
+/** Runs in the browser: the DOM's structural shape — every element's tag + class
+ *  in document order (scripts/styles/meta skipped). Text and computed styles are
+ *  deliberately excluded, so a ticking clock or animated opacity never reads as a
+ *  new state, while any mount/unmount/class flip does. ~30ms vs the full
+ *  computed-style walk it replaces for change detection. */
+/* c8 ignore start */
+function domShape() {
+    const SKIP = new Set(['SCRIPT', 'STYLE', 'META', 'LINK', 'NOSCRIPT', 'TEMPLATE']);
+    const parts = [];
+    const classes = new Set();
+    const add = (el) => {
+        const cls = el.getAttribute('class') ?? '';
+        parts.push(`${el.tagName}.${cls}`);
+        for (const c of cls.split(/\s+/))
+            if (c)
+                classes.add(c);
+    };
+    // html/body themselves first: state classes there (a theme switch, modal-open)
+    // are a common pattern and restyle the whole page without touching any
+    // descendant's class — invisible to a descendants-only walk.
+    add(document.documentElement);
+    add(document.body);
+    for (const el of document.body.getElementsByTagName('*')) {
+        if (SKIP.has(el.tagName))
+            continue;
+        add(el);
+    }
+    return { shape: parts.join('\n'), elements: parts.length, classes: [...classes] };
+}
+/* c8 ignore stop */
+/** Runs in the browser: every class name the page's OWN stylesheets select on —
+ *  the design's defined vocabulary, read from the parsed CSSOM (inline and
+ *  same-origin sheets; unreadable cross-origin sheets are skipped). Coverage is
+ *  checked against this, so "fully covered" means every class the design styles
+ *  was seen rendered in at least one captured surface. */
+/* c8 ignore start */
+function collectDefinedClasses() {
+    const out = new Set();
+    const scan = (rules) => {
+        if (!rules)
+            return;
+        for (const rule of rules) {
+            const r = rule;
+            if (r.selectorText) {
+                const re = /\.([A-Za-z_][A-Za-z0-9_-]*)/g;
+                for (let m = re.exec(r.selectorText); m; m = re.exec(r.selectorText))
+                    out.add(m[1]);
+            }
+            if (r.cssRules)
+                scan(r.cssRules);
+        }
+    };
+    for (const sheet of document.styleSheets) {
+        try {
+            scan(sheet.cssRules);
+        }
+        catch {
+            /* cross-origin sheet — not the design's own vocabulary */
+        }
+    }
+    return [...out];
+}
+/* c8 ignore stop */
+/** Structural fingerprint of the page's CURRENT state. Dedup key for surfaces. */
+async function fingerprint(page) {
+    const fp = await page.evaluate(domShape);
+    return {
+        sig: createHash('sha256').update(fp.shape).digest('hex').slice(0, 16),
+        elements: fp.elements,
+        classes: fp.classes,
+    };
+}
+/** Wait for the DOM to stop changing (element count stable) — a cheap post-click
+ *  settle that also covers content painted by a click-triggered fetch. */
+async function settleDom(page, maxMs = 1200) {
+    let prev = -1;
+    const deadline = Date.now() + maxMs;
+    while (Date.now() < deadline) {
+        const n = await page.evaluate(() => document.body.getElementsByTagName('*').length);
+        if (n === prev)
+            return;
+        prev = n;
+        await page.waitForTimeout(90);
+    }
+}
+/** Wait for an async-rendered app to finish mounting: the DOM stops growing and is
+ *  non-trivial. Generic — no app-specific selector needed, so a bare crawl of a
+ *  Babel/React/Vue page that boots after `load` still captures the mounted UI. */
+async function waitSettled(page) {
+    await page.waitForLoadState('networkidle').catch(() => { });
+    let prev = -1;
+    for (let i = 0; i < 40; i++) {
+        const n = await page.evaluate(() => document.body.getElementsByTagName('*').length);
+        if (n > 5 && n === prev)
+            return;
+        prev = n;
+        await page.waitForTimeout(100);
+    }
+}
+/**
+ * Load the URL from a clean slate (storage cleared by the init script armed in
+ * crawlAndCapture — one navigation, no clear-then-reload) and wait for the app to
+ * mount. Pins the viewport to widths[0] so DISCOVERY always happens at one
+ * consistent width — captureInPlace sweeps the other widths and would otherwise
+ * leave the viewport wherever it finished (e.g. a mobile band where half the
+ * controls are hidden).
+ */
+async function gotoFresh(page, opts) {
+    await page.setViewportSize({ width: opts.widths[0] ?? 1280, height: opts.height });
+    await page.goto(opts.url, { waitUntil: 'load' });
+    // Tolerant wait: the generic settle below is the real readiness signal; an
+    // optional waitSelector just accelerates it and must not fail the crawl.
+    const ready = opts.waitSelector ? page.locator(opts.waitSelector).first() : null;
+    if (ready)
+        await ready.waitFor({ state: 'visible' }).catch(() => { });
+    await waitSettled(page);
+}
+async function perform(page, s) {
+    const target = page.locator(s.selector).first();
+    if (s.action === 'select-option') {
+        await target.selectOption(s.value ?? '');
+        return;
+    }
+    await target.waitFor({ state: 'attached', timeout: 5000 });
+    await target.scrollIntoViewIfNeeded({ timeout: 3000 }).catch(() => { });
+    // Dispatch the click IN-PAGE rather than through Playwright's actionability
+    // pipeline. `el.click()` fires the app's real (delegated) click handler but
+    // skips the stability/visibility/hit-testing waits that make Playwright's own
+    // click flake on an opening modal — the intermittent failure that silently
+    // dropped deep states on re-drive. We only need to REACH the state to map it.
+    const dispatched = await target
+        .evaluate((el) => {
+        if (el instanceof HTMLElement) {
+            el.click();
+            return true;
+        }
+        return false;
+    })
+        .catch(() => false);
+    if (!dispatched)
+        await target.click({ timeout: 3000 }); // non-HTMLElement (SVG etc.)
+}
+async function replay(page, steps) {
+    for (const s of steps) {
+        await perform(page, s);
+        await settleDom(page);
+    }
+}
+/** Reset to a known state and VERIFY arrival by fingerprint (retry once). A false
+ *  return means the path won't reproduce right now — the caller abandons the rest
+ *  of that state's sweep (fail-soft) rather than mis-attributing children. */
+async function resetToState(page, opts, steps, wantSig) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        try {
+            await gotoFresh(page, opts);
+            await replay(page, steps);
+            if ((await fingerprint(page)).sig === wantSig)
+                return true;
+        }
+        catch {
+            /* retry */
+        }
+    }
+    return false;
+}
+/** Capture the page's CURRENT state (already driven to) at every width, resizing
+ *  in place. Capturing where discovery already stands means a fragile click-path
+ *  is never replayed a second time — the failure mode of re-driving deep, animated
+ *  controls. */
+async function captureInPlace(page, key, opts) {
+    for (const width of opts.widths) {
+        await page.setViewportSize({ width, height: opts.height });
+        const requests = trackInflightRequests(page);
+        try {
+            const map = await captureStyleMap(page, {
+                ignore: opts.ignore,
+                pendingRequests: requests.pending,
+                metadata: { surfaceKey: key },
+            });
+            const stem = path.join(opts.out, `${key}@${width}`);
+            saveStyleMap(`${stem}.json.gz`, map);
+            if (opts.screenshots)
+                await page.screenshot({ path: `${stem}.png`, fullPage: true, animations: 'disabled' });
+        }
+        finally {
+            requests.dispose();
+        }
+    }
+}
+/** Identity of a state for the changer registry: the click-path that defines it. */
+function stateKey(steps) {
+    return steps.map((s) => s.selector + (s.value ?? '')).join(' → ');
+}
+/** Record a newly-found surface, capture it in place (page is already there), and
+ *  queue it for its own sweep. Streams progress via onSurface. */
+async function record(page, opts, newPath, depth, fp, st) {
+    const key = deriveKey(newPath, st.used);
+    const surface = { key, depth, path: newPath, elements: fp.elements };
+    st.surfaces.push(surface);
+    st.queue.push({ path: newPath, depth, sig: fp.sig });
+    for (const c of fp.classes)
+        st.classes.add(c);
+    let ok = true;
+    try {
+        await captureInPlace(page, key, opts);
+        st.captured++;
+    }
+    catch {
+        st.failed.push(key);
+        ok = false;
+    }
+    opts.onSurface?.(surface, ok);
+}
+/** Click one candidate where the page stands; classify the outcome. */
+async function tryInPlace(page, c) {
+    const startUrl = pathAndSearch(page.url());
+    const before = (await fingerprint(page)).sig;
+    try {
+        await perform(page, c);
+    }
+    catch {
+        return 'failed';
+    }
+    await settleDom(page);
+    if (pathAndSearch(page.url()) !== startUrl)
+        return 'navigated';
+    return (await fingerprint(page)).sig === before ? 'noop' : 'changed';
+}
+/** Drive one candidate from where the page stands. Returns whether the page is
+ *  still in the swept state (no-op click) and whether the action was a skip. */
+async function driveCandidate(page, opts, entry, c, st) {
+    const outcome = await tryInPlace(page, c);
+    if (outcome === 'noop')
+        return { inState: true, skipped: false }; // still in the state — no reset needed
+    if (outcome === 'failed' || outcome === 'navigated')
+        return { inState: false, skipped: true };
+    // Register the changer for family retry — persistence checked in the state its
+    // own click produced (a tab survives its switch; an approve row consumes itself).
+    const persists = await page
+        .locator(c.selector)
+        .first()
+        .isVisible()
+        .catch(() => false);
+    const from = stateKey(entry.path);
+    const list = st.changersFrom.get(from) ?? [];
+    if (!list.some((x) => x.c.selector === c.selector))
+        list.push({ c, persists });
+    st.changersFrom.set(from, list);
+    const fp = await fingerprint(page);
+    if (st.seen.has(fp.sig))
+        return { inState: false, skipped: false }; // same surface reached another way
+    st.seen.add(fp.sig);
+    const step = {
+        action: c.action,
+        selector: c.selector,
+        label: c.label,
+        reason: c.reason,
+        ...(c.value ? { value: c.value } : {}),
+    };
+    await record(page, opts, [...entry.path, step], entry.depth + 1, fp, st);
+    return { inState: false, skipped: false };
+}
+/**
+ * Sweep one state: drive every not-yet-tried control reachable from it, IN PLACE.
+ * A no-op click leaves the page in the state, so the sweep just continues; only a
+ * state-changing click (new surface, dup, navigation, or failure) pays a verified
+ * reset before the next candidate.
+ */
+/** The family-retry list for a state: its parent's persistent mode-switchers that
+ *  are visible right now — minus the step that created this state itself. */
+function familyRetries(entry, all, st) {
+    if (entry.path.length === 0)
+        return [];
+    const parentKey = stateKey(entry.path.slice(0, -1));
+    const ownSelector = entry.path[entry.path.length - 1].selector;
+    const visibleNow = new Set(all.map((c) => c.selector));
+    return (st.changersFrom.get(parentKey) ?? [])
+        .filter((x) => x.persists && x.c.selector !== ownSelector && visibleNow.has(x.c.selector))
+        .map((x) => x.c);
+}
+async function sweepState(page, opts, entry, st) {
+    if (!(await resetToState(page, opts, entry.path, entry.sig)))
+        return { tried: 0, skipped: 0 };
+    const all = await page.evaluate(collectClickable).catch(() => []);
+    // Fresh controls first (already-driven global chrome would otherwise starve a
+    // deep surface's own controls; the throttle applies to fresh ones), then the
+    // parent's persistent mode-switchers re-tried in THIS sibling mode.
+    const fresh = all.filter((c) => !st.tried.has(c.selector)).slice(0, opts.maxActionsPerState);
+    const work = [
+        ...fresh.map((c) => ({ c, retry: false })),
+        ...familyRetries(entry, all, st).map((c) => ({ c, retry: true })),
+    ];
+    let tried = 0;
+    let skipped = 0;
+    let inState = true;
+    for (const { c, retry } of work) {
+        if (st.surfaces.length >= opts.maxStates)
+            break;
+        if (!inState) {
+            if (!(await resetToState(page, opts, entry.path, entry.sig)))
+                break; // abandon rest, fail-soft
+            inState = true;
+        }
+        if (!retry)
+            st.tried.add(c.selector);
+        if (c.unsafe) {
+            skipped++;
+            continue;
+        }
+        tried++;
+        const r = await driveCandidate(page, opts, entry, c, st);
+        inState = r.inState;
+        if (r.skipped)
+            skipped++;
+    }
+    return { tried, skipped };
+}
+/** Depth-first discovery + in-place capture of every reachable surface. Depth-first
+ *  so a surface's OWN sub-states (a modal's tab → its toggles) are mapped while the
+ *  branch is fresh; with no budget, order affects time-to-depth, not coverage. */
+async function discover(page, opts) {
+    fs.mkdirSync(opts.out, { recursive: true });
+    await gotoFresh(page, opts);
+    const defined = await page.evaluate(collectDefinedClasses).catch(() => []);
+    const fp = await fingerprint(page);
+    const st = {
+        seen: new Set([fp.sig]),
+        used: new Set(),
+        tried: new Set(),
+        changersFrom: new Map(),
+        classes: new Set(),
+        surfaces: [],
+        queue: [],
+        captured: 0,
+        failed: [],
+    };
+    await record(page, opts, [], 0, fp, st);
+    let actionsTried = 0;
+    let skipped = 0;
+    while (st.queue.length > 0 && st.surfaces.length < opts.maxStates) {
+        const entry = st.queue.pop(); // LIFO → depth-first
+        if (entry.depth >= opts.maxDepth)
+            continue;
+        const r = await sweepState(page, opts, entry, st);
+        actionsTried += r.tried;
+        skipped += r.skipped;
+    }
+    const missing = defined.filter((c) => !st.classes.has(c)).sort();
+    return {
+        surfaces: st.surfaces,
+        actionsTried,
+        skipped,
+        captured: st.captured,
+        failed: st.failed,
+        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing },
+    };
+}
+/**
+ * Crawl `opts.url` and capture every reachable surface at every width — runs to
+ * natural termination by default. Returns the surfaces mapped (with the click-path
+ * that reached each), how many actions were tried/skipped, and captured/failed.
+ */
+export async function crawlAndCapture(page, opts) {
+    if (opts.resetStorage) {
+        // Clear storage before the app's code runs on EVERY load, so each gotoFresh is
+        // a clean slate in one navigation (no clear-then-reload round trip).
+        await page.addInitScript(() => {
+            try {
+                localStorage.clear();
+                sessionStorage.clear();
+            }
+            catch {
+                /* storage unavailable (e.g. file://) — ignore */
+            }
+        });
+    }
+    return discover(page, opts);
+}

package/dist/index.d.ts

@@ -1,4 +1,8 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
+export type { CaptureUrlOptions, CaptureUrlResult } from './capture-url.js';
+export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
+export type { SurfaceCrawlOptions, CrawlReport, CrawlCoverage, CrawledSurface, CrawlStep } from './crawl-surfaces.js';
 export type { StyleMap, CaptureOptions, CaptureMetadata, ElementEntry, LiveRegionCandidate, CapturedOverlay, Rect, } from './capture.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export type { Surface, SurfaceLiveState, SurfaceVariant, PopupCaptureOptions, DefineOptions, CrawlOptions, } from './runner.js';

package/dist/index.js

@@ -1,4 +1,6 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
+export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';

package/dist/report.js

@@ -8,8 +8,7 @@ import { describeChange, tokenIndex, toHex, trackCount } from './describe.js';
 // through the package's report module rather than a deep path.
 export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
 // Hidden marker appended to a new-surface heading. Invisible in rendered
-// markdown; lets the PR-comment layer attach an OPTIONAL "approve" box to a new
-// surface (vs the required box on a real change), so new surfaces never gate.
+// markdown; lets the PR-comment layer recognize one-sided surfaces.
 const NEW_SURFACE_MARKER = '<!-- styleproof-new -->';
 const rectToBox = (r) => ({ x: r[0], y: r[1], w: r[2], h: r[3] });
 const pad = (b, by) => ({ x: b.x - by, y: b.y - by, w: b.w + 2 * by, h: b.h + 2 * by });
@@ -910,8 +909,8 @@ export function generateStyleMapReport(opts) {
         if (missing.length > 0) {
             if (changeGroups.length > 0)
                 md.push('');
-            md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for reference. ` +
-                `New surfaces don't block the check.`);
+            md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for review. ` +
+                `Approve them before they become the baseline.`);
         }
     }
     if (volatileCount > 0) {
@@ -1037,8 +1036,7 @@ export function generateStyleMapReport(opts) {
         json.push(surfaceJson);
     }
     // New surfaces: present on only one side, so there's nothing to diff. Show the
-    // captured side as a single screenshot for reference and mark the heading so the
-    // PR comment can attach an OPTIONAL approval box — these never gate the check.
+    // captured side as a single screenshot and mark the heading for the PR comment.
     for (const p of missing) {
         const side = p.sd.missing === 'before' ? 'after' : 'before';
         const srcDir = side === 'after' ? afterDir : beforeDir;
@@ -1058,7 +1056,7 @@ export function generateStyleMapReport(opts) {
         else {
             md.push('', `_Captured only in the **${side}** set; no screenshot saved (run captures with \`screenshots: true\`)._`);
         }
-        md.push('', `_No baseline to compare against — this surface is new, so it doesn't block the check. It becomes part of the baseline once this merges._`);
+        md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
         json.push(surfaceJson);
     }
     md.push(...contentSection.md);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.2.0",
+  "version": "3.3.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",
@@ -38,6 +38,7 @@
   "bin": {
     "styleproof-init": "./bin/styleproof-init.mjs",
     "styleproof-map": "./bin/styleproof-map.mjs",
+    "styleproof-capture": "./bin/styleproof-capture.mjs",
     "styleproof-diff": "./bin/styleproof-diff.mjs",
     "styleproof-report": "./bin/styleproof-report.mjs",
     "styleproof-variants": "./bin/styleproof-variants.mjs"