styleproof 2.3.1 → 2.5.0

package/CHANGELOG.md

@@ -7,6 +7,81 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [2.5.0] - 2026-06-26
+
+### Changed
+
+- **`styleproof-init` scaffolds parallel surface capture (`fullyParallel: true`).**
+  StyleProof emits one test per surface × width, each an isolated page writing a
+  uniquely-keyed file — independent and safe to run concurrently. Without
+  `fullyParallel`, all surfaces sit in one spec file and capture **serially**; with it
+  they fan out across workers. Measured: 6 surfaces went from 12.3 s (1 worker) to
+  4.9 s (4 workers) — **~2.5× faster**, byte-identical output. Profiling confirmed the
+  single-capture path is correctness-bound (the settle is a deterministic wait; forced
+  states must be isolated per element), so parallelism across surfaces — not
+  micro-optimising one capture — is the real lever.
+
+### Added
+
+- **Dogfood: StyleProof certifies its own demo page in CI.** A new
+  `example/demo/index.html` plus `test/dogfood.e2e.spec.ts` run the full
+  capture → detect → diff pipeline on a real multi-element page every CI run:
+  auto-detection finds the demo's `@media` breakpoints, two captures certify
+  identical (determinism), and a planted restyle is caught. `test:e2e` now runs the
+  whole `*.e2e.spec.ts` suite. (Repo-only; `example/` isn't in the published package.)
+
+- **`npm run bench` — measures the committed-map gate's CI speedup.** A reproducible
+  benchmark of one in-browser capture vs one precomputed-map diff, projected to a
+  sample app. On the dev fixture: capture ≈ 1 s/surface-width, diff ≈ 0.4 ms — so the
+  per-PR compare step is ~1000s× cheaper, before counting the build + serve the
+  committed-map CI also skips. (Internal tooling; not shipped in the package.)
+- **The Action and `styleproof-report` support `--base-ref`.** The committed-map gate
+  now gets the full review experience, not just a bare diff: pass `base-ref` to the
+  Action (e.g. the PR base branch) and point `fresh-dir` at your committed maps — it
+  reads the base from git and produces the same before/after report + approval gate,
+  with no recapture. `styleproof-report --base-ref <gitref> <mapsDir>` does the same
+  on the CLI. The git-materialisation is now a shared `materializeRef` (in `gitref`)
+  used by both `styleproof-diff` and `styleproof-report`. `baseline-dir` is no longer
+  required when `base-ref` is set.
+
+## [2.4.0] - 2026-06-26
+
+### Added
+
+- **Automatic breakpoint detection — `Surface.widths` is now optional.** Omit it and
+  StyleProof reads the app's real viewport breakpoints from the loaded CSSOM at
+  capture time and sweeps one width per `@media` band — no config, no guessing.
+  Because it reads the browser's parsed stylesheets (not your source), it's
+  framework-agnostic: Tailwind, CSS Modules, styled-components, Sass and vanilla all
+  resolve to the same `@media` rules. It is authoritative **or it fails**: an
+  unreadable cross-origin stylesheet throws (so a band is never silently missed)
+  rather than guessing. `min/max-width` and range syntax (`width >= …`) are handled,
+  `em`/`rem` resolved against the root font size; container/print/height queries are
+  correctly ignored. Set `widths` explicitly to pin the sweep or to cover a JS-only
+  (`matchMedia`) breakpoint that has no CSS rule. New exports: `detectViewportWidths`,
+  `mediaTextWidthBoundaries`, `widthsFromBoundaries`. **`styleproof-init` now scaffolds
+  surfaces with no `widths`**, so a fresh project gets zero-config breakpoint detection
+  by default.
+- **Out-of-the-box committed-map gate — capture pre-push, CI just diffs.**
+  `styleproof-init` now scaffolds the whole flow as the default: a **pre-push hook**
+  (`.githooks/pre-push`) captures this branch's computed-style map against a
+  production build, commits it as a lean `.json.gz` under `stylemaps/`, and **pushes
+  it with your branch — one `git push`, never two** (the hook pushes the map commit
+  itself, because git would otherwise send only the pre-hook commit); and a
+  **browser-less CI workflow** that just diffs the committed map against the base. So
+  `main` always carries a base map and every PR is a fast comparison of precomputed
+  maps, never a recapture. (Capture belongs pre-push because it needs the app built +
+  served; the same-environment requirement is self-enforced by the self-check.)
+- **`styleproof-diff --base-ref <gitref>` — diff against a committed base in git.**
+  `styleproof-diff --base-ref main <mapsDir>` materialises the captures committed at
+  `<mapsDir>` as of `main` and diffs them against your working `<mapsDir>` — the CI
+  half of the gate above. Reads the base purely through git (`ls-tree`/`show`, no
+  `tar`/deps; binary `.json.gz` preserved), into a temp dir cleaned up after.
+- **`STYLEPROOF_BASEDIR` / `STYLEPROOF_SCREENSHOTS` env knobs** (same wiring style as
+  `STYLEPROOF_REPLAY_*`): redirect capture into a committed dir and drop screenshots
+  for lean, commit-friendly maps — without editing the spec. This is what lets the
+  pre-push hook capture committed maps from the stock generated spec.
+
 ## [2.3.1] - 2026-06-23
 
 ### Fixed

package/README.md

@@ -292,19 +292,19 @@ It's **asynchronous by design**: approval is a checkbox tick handled by a separa
 
 **Capture spec `defineStyleMapCapture({ surfaces, … })`** — determinism is on by default; you rarely set more than `surfaces` and `dir`:
 
-| Option        | Default                     | Purpose                                                                                                                                                                             |
-| ------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths, ignore?, height? }`. `go(page)` drives to a settled state.                                                                        |
-| `expected`    | _none_                      | Your route/view universe. Emits a coverage-guard test (runs without a capture dir) that fails when a route has no surface and isn't excluded — so a new page can't ship uncaptured. |
-| `exclude`     | `{}`                        | `key → reason` for routes deliberately not captured. Keeps the guard green for known gaps; a key absent from `expected` fails the guard, so the ledger can't go stale.              |
-| `dir`         | `STYLEMAP_DIR`              | Output label (`base`/`head`); the spec is **inert until set**, so it sits safely beside your other specs.                                                                           |
-| `replayFrom`  | `STYLEPROOF_REPLAY_FROM`    | Baseline dir whose recorded responses to replay. Unset → this run **records** its HAR for the comparison to use.                                                                    |
-| `replayUrl`   | `**/api/**` (`…REPLAY_URL`) | URL glob for the data boundary to record/replay; everything else (JS/CSS/fonts) loads live so the code runs.                                                                        |
-| `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.                                                                     |
-| `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                                                                                                 |
-| `selfCheck`   | on while recording          | Capture each surface twice and fail on any difference — proves the capture is deterministic. Off on the replay run; `STYLEPROOF_SELFCHECK=1` forces both.                           |
-| `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                                                                                     |
-| `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                                                                                              |
+| Option        | Default                     | Purpose                                                                                                                                                                                                 |
+| ------------- | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `surfaces`    | _required_                  | Page states to certify — each `{ key, go, widths?, ignore?, height? }`. `go(page)` drives to a settled state. Omit `widths` to auto-detect the app's `@media` breakpoints and sweep one width per band. |
+| `expected`    | _none_                      | Your route/view universe. Emits a coverage-guard test (runs without a capture dir) that fails when a route has no surface and isn't excluded — so a new page can't ship uncaptured.                     |
+| `exclude`     | `{}`                        | `key → reason` for routes deliberately not captured. Keeps the guard green for known gaps; a key absent from `expected` fails the guard, so the ledger can't go stale.                                  |
+| `dir`         | `STYLEMAP_DIR`              | Output label (`base`/`head`); the spec is **inert until set**, so it sits safely beside your other specs.                                                                                               |
+| `replayFrom`  | `STYLEPROOF_REPLAY_FROM`    | Baseline dir whose recorded responses to replay. Unset → this run **records** its HAR for the comparison to use.                                                                                        |
+| `replayUrl`   | `**/api/**` (`…REPLAY_URL`) | URL glob for the data boundary to record/replay; everything else (JS/CSS/fonts) loads live so the code runs.                                                                                            |
+| `freezeClock` | `true`                      | Pin `Date.now()`/`new Date()` so time-derived styling can't drift; timers keep running so settling still works.                                                                                         |
+| `clockTime`   | `2025-01-01T00:00:00Z`      | The frozen instant.                                                                                                                                                                                     |
+| `selfCheck`   | on while recording          | Capture each surface twice and fail on any difference — proves the capture is deterministic. Off on the replay run; `STYLEPROOF_SELFCHECK=1` forces both.                                               |
+| `screenshots` | `true`                      | Save full-page screenshots for the report's before/after crops.                                                                                                                                         |
+| `baseDir`     | `__stylemaps__`             | Output root directory.                                                                                                                                                                                  |
 
 Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<style>`/… and `next-route-announcer`) are skipped automatically; a surface's `ignore` adds to that default, it doesn't replace it.
 

package/bin/styleproof-diff.mjs

@@ -3,6 +3,7 @@
  * Diff two computed-style map captures (see styleproof).
  *
  *   styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]
+ *   styleproof-diff --base-ref <gitref> <mapsDir> [--max N] [--json <file>]
  *
  * Reports, per surface:
  *   - DOM changes (elements added/removed/retagged) — a CSS-only refactor
@@ -13,18 +14,29 @@
  *     longer does (or now changes differently) — the classic dropped
  *     `hover:` variant a screenshot can never catch.
  *
+ * --base-ref reads the base from a git ref instead of a second directory: it
+ * materialises the captures committed at <mapsDir> as of <gitref> (e.g. `main`)
+ * and diffs them against your working <mapsDir>. That's the "base map lives on
+ * main, CI just diffs" flow — commit each branch's maps (pre-push), and the gate
+ * never recomputes the base. Both sides must be captured in the same environment
+ * (browser + fonts) for the diff to be meaningful.
+ *
  * Custom properties (--*) are ignored: they are inputs, not outcomes (see
  * README). Exit code 0 = identical, 1 = reviewable differences, 2 = usage/capture
  * error, 3 = only new surfaces (present on one side, no baseline to diff against).
  */
 import fs from 'node:fs';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
+import { materializeRef, GitRefError } from '../dist/gitref.js';
 
 const HELP = `styleproof-diff — certify a CSS refactor by diffing two computed-style captures
 
 usage: styleproof-diff <beforeDir> <afterDir> [options]
+       styleproof-diff --base-ref <gitref> <mapsDir> [options]
 
 options:
+  --base-ref <ref> diff <mapsDir> as committed at <ref> (e.g. main) against your
+                   working <mapsDir> — base from git, no recapture
   --max <n>        max lines printed per surface before truncating (default: 40)
   --json <file>    also write the full structured diff to <file>
   -h, --help       show this help
@@ -37,6 +49,7 @@ const argv = process.argv.slice(2);
 const args = [];
 let MAX = 40;
 let jsonOut = null;
+let baseRef = null;
 for (let i = 0; i < argv.length; i++) {
   if (argv[i] === '-h' || argv[i] === '--help') {
     process.stdout.write(HELP);
@@ -45,21 +58,46 @@ for (let i = 0; i < argv.length; i++) {
   else if (argv[i].startsWith('--max=')) MAX = Number(argv[i].slice(6));
   else if (argv[i] === '--json') jsonOut = argv[++i];
   else if (argv[i].startsWith('--json=')) jsonOut = argv[i].slice(7);
+  else if (argv[i] === '--base-ref') baseRef = argv[++i];
+  else if (argv[i].startsWith('--base-ref=')) baseRef = argv[i].slice(11);
   else if (argv[i].startsWith('--')) {
     console.error(`unknown flag: ${argv[i]}`);
     process.exit(2);
   } else args.push(argv[i]);
 }
-if (args.length !== 2 || !Number.isFinite(MAX)) {
-  console.error('usage: styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]  (--help for all options)');
-  process.exit(2);
-}
-const [dirA, dirB] = args;
-for (const d of [dirA, dirB]) {
-  if (!fs.existsSync(d)) {
-    console.error(`no capture at ${d}`);
+
+let dirA;
+let dirB;
+let tmpBase = null;
+if (baseRef) {
+  if (args.length !== 1 || !Number.isFinite(MAX)) {
+    console.error('usage: styleproof-diff --base-ref <gitref> <mapsDir> [--max N] [--json <file>]');
+    process.exit(2);
+  }
+  if (!fs.existsSync(args[0])) {
+    console.error(`no capture at ${args[0]}`);
     process.exit(2);
   }
+  try {
+    tmpBase = materializeRef(baseRef, args[0]);
+  } catch (e) {
+    console.error(e instanceof GitRefError ? `styleproof-diff --base-ref: ${e.message}` : String(e?.message ?? e));
+    process.exit(2);
+  }
+  dirA = tmpBase;
+  dirB = args[0];
+} else {
+  if (args.length !== 2 || !Number.isFinite(MAX)) {
+    console.error('usage: styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]  (--help for all options)');
+    process.exit(2);
+  }
+  [dirA, dirB] = args;
+  for (const d of [dirA, dirB]) {
+    if (!fs.existsSync(d)) {
+      console.error(`no capture at ${d}`);
+      process.exit(2);
+    }
+  }
 }
 
 let result;
@@ -68,6 +106,8 @@ try {
 } catch (e) {
   console.error(e.message);
   process.exit(2);
+} finally {
+  if (tmpBase) fs.rmSync(tmpBase, { recursive: true, force: true });
 }
 const { surfaces, counts } = result;
 
@@ -102,10 +142,8 @@ if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces }, null
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;
-const surfaceCount = new Set([
-  ...fs.readdirSync(dirA).filter((f) => /\.json(\.gz)?$/.test(f)),
-  ...fs.readdirSync(dirB).filter((f) => /\.json(\.gz)?$/.test(f)),
-]).size;
+// One SurfaceDiff per distinct surface across both sides (incl. missing-on-one-side).
+const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 console.log(
   total === 0

package/bin/styleproof-init.mjs

@@ -105,9 +105,9 @@ async function settle(page: Page) {
 const HEADER = `/**
  * styleproof capture spec (generated by \`styleproof-init\`).
  *
- * Each surface is one deterministic page state; widths sweep one viewport per
- * @media band so breakpoint rules are certified too. Capture against a
- * PRODUCTION build — dev servers inject their own styles.
+ * Each surface is one deterministic page state. Omit \`widths\` and StyleProof
+ * detects your @media breakpoints from the loaded CSS and sweeps one viewport per
+ * band — no config. Capture against a PRODUCTION build — dev servers inject styles.
  *
  *   STYLEMAP_DIR=before npx playwright test styleproof   # capture baseline
  *   ...refactor your CSS...
@@ -140,7 +140,9 @@ const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
     await settle(page);
   },
   ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
-  widths: [1280, 768, 390],
+  // No widths → StyleProof detects your @media breakpoints from the loaded CSS and
+  // sweeps one viewport per band. Pass an explicit array (e.g. 1280, 768, 390) to pin them (or to
+  // cover a JS-only matchMedia breakpoint that has no CSS @media rule).
 }));
 
 defineStyleMapCapture({
@@ -173,7 +175,9 @@ const SURFACES: Surface[] = [
       await settle(page);
     },
     ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
-    widths: [1280, 768, 390],
+    // No widths → StyleProof detects your @media breakpoints from the loaded CSS and
+    // sweeps one viewport per band. Pass an explicit array (e.g. 1280, 768, 390) to pin them (or to
+    // cover a JS-only matchMedia breakpoint that has no CSS @media rule).
   },
   // Add one surface per distinct page state: open menus, dialogs, selected
   // tabs, form errors — anything whose styling you want certified.
@@ -205,6 +209,14 @@ const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 // in-flight data either way, but a production build removes the variance at the source.)
 export default defineConfig({
   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
+  // per-page record/replay and frozen clock — so they're independent and safe to run
+  // concurrently. Without this, all surfaces sit in one spec file and capture serially;
+  // with it they fan out across workers, a near-linear speedup on a multi-surface app.
+  // (\`--shard\` splits them across CI machines too; they write disjoint files into one
+  // dir.) Tune \`workers\` to your machine if needed.
+  fullyParallel: true,
   use: {
     baseURL: process.env.BASE_URL || '${baseUrl}',
   },
@@ -221,6 +233,70 @@ export default defineConfig({
 });
 `;
 
+// The out-of-the-box gate: capture happens PRE-PUSH on your machine (where the app
+// already builds + serves) and the lean computed-style map is committed, so main
+// always carries a base map and CI is a fast, browser-less diff of two precomputed
+// maps. The hook redirects capture into a committed `stylemaps/` dir and drops
+// screenshots via the STYLEPROOF_BASEDIR / STYLEPROOF_SCREENSHOTS env knobs.
+const HOOK_PATH = '.githooks/pre-push';
+const PREPUSH_HOOK = `#!/bin/sh
+# StyleProof pre-push hook (generated by styleproof-init).
+#
+# Captures this branch's computed-style map, commits it, and pushes it WITH your
+# push — one \`git push\`, never two. So main always carries a base map and CI just
+# diffs two precomputed maps (no browser). Maps are lean .json.gz under stylemaps/.
+# Activate once per clone:  git config core.hooksPath .githooks
+set -e
+
+remote="$1"
+
+# Re-entry guard: the map commit is pushed by this hook (below), which fires the
+# hook a second time — skip the expensive capture on that pass.
+[ "\${STYLEPROOF_SKIP_CAPTURE:-}" = "1" ] && exit 0
+
+STYLEMAP_DIR=current STYLEPROOF_BASEDIR=stylemaps STYLEPROOF_SCREENSHOTS=0 \\
+  npx playwright test ${specPath}
+
+git add stylemaps
+git diff --cached --quiet -- stylemaps && exit 0  # map unchanged — let the push proceed
+
+# Map changed: commit it and push the updated branch ourselves so you never push
+# twice (git pushes the pre-hook commit, so a new commit here wouldn't otherwise go).
+# The re-entry guard stops the inner push from recapturing; then abort this original,
+# now-stale push so nothing is sent twice.
+git commit -m "chore(styleproof): update computed-style map"
+echo "StyleProof: style map changed — committed it and pushing with your branch…" >&2
+STYLEPROOF_SKIP_CAPTURE=1 git push "$remote" HEAD
+echo "StyleProof: ✓ pushed your branch with the updated map — nothing more to do." >&2
+echo "StyleProof: (git's 'failed to push some refs' below is expected; the push above already succeeded.)" >&2
+exit 1
+`;
+
+const CI_PATH = '.github/workflows/styleproof.yml';
+const CI_WORKFLOW = `name: StyleProof
+
+# Maps are captured + committed pre-push (see .githooks/pre-push), so CI runs no
+# browser — it just diffs this branch's committed map against the base branch's.
+on: pull_request
+
+permissions:
+  contents: read
+
+jobs:
+  styleproof:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # need the base ref to read its committed map
+      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - run: npm ci
+      - name: Diff this branch's committed map against the base
+        run: npx styleproof-diff --base-ref "origin/\${{ github.event.pull_request.base.ref }}" stylemaps/current
+`;
+
 function writeFileSafe(file, contents, { force: f } = {}) {
   const exists = fs.existsSync(file);
   if (exists && !f) return { wrote: false, exists: true };
@@ -263,15 +339,34 @@ if (fs.existsSync(configPath) || fs.existsSync('playwright.config.js')) {
   wroteSomething = true;
 }
 
-console.log('\nNext steps (run against a PRODUCTION build, not a dev server):');
-console.log('  1. capture the baseline:');
-console.log('       STYLEMAP_DIR=baseline npx playwright test styleproof');
-console.log('  2. commit it:');
-console.log('       git add __stylemaps__/baseline && git commit -m "chore: stylemap baseline"');
-console.log('  3. after a CSS change, certify it:');
-console.log('       STYLEMAP_DIR=after npx playwright test styleproof');
-console.log('       npx styleproof-diff __stylemaps__/baseline __stylemaps__/after');
-console.log('     an empty diff is the certificate; a non-empty one names every drift.');
+// Pre-push capture+commit hook — the out-of-the-box gate (capture local, CI diffs).
+const hook = writeFileSafe(HOOK_PATH, PREPUSH_HOOK, { force });
+if (hook.wrote) {
+  fs.chmodSync(HOOK_PATH, 0o755);
+  console.log(`${hook.exists ? 'overwrote' : 'created'} ${HOOK_PATH} (pre-push capture + commit)`);
+  wroteSomething = true;
+} else {
+  console.log(`${HOOK_PATH} already exists — left untouched (use --force to overwrite)`);
+}
+
+// Browser-less CI diff — never overwrite an existing workflow.
+const ci = writeFileSafe(CI_PATH, CI_WORKFLOW);
+if (ci.wrote) {
+  console.log(`created ${CI_PATH} (browser-less CI diff)`);
+  wroteSomething = true;
+} else {
+  console.log(`${CI_PATH} already exists — left untouched`);
+}
+
+console.log('\nHow the gate works — capture local, CI just diffs:');
+console.log('  1. Activate the pre-push hook (once per clone):');
+console.log('       git config core.hooksPath .githooks');
+console.log('  2. Push your branch. The hook captures the computed-style map against a');
+console.log('     PRODUCTION build, commits it (lean .json.gz under stylemaps/), and pushes it');
+console.log('     with your branch — one `git push`, never two.');
+console.log('  3. On the PR, CI diffs your committed map against the base branch — no browser,');
+console.log('     just a fast comparison of precomputed maps. An empty diff certifies no change.');
+console.log('  So main always carries a base map and every PR is a quick diff, not a recapture.');
 
 if (!wroteSomething) console.log('\nnothing to write — project already scaffolded.');
 process.exit(0);

package/bin/styleproof-report.mjs

@@ -10,13 +10,18 @@
  * need the .png screenshots that `defineStyleMapCapture` saves by default.
  * Exit code 0 = no changes, 1 = report generated, 2 = usage error.
  */
+import fs from 'node:fs';
 import { generateStyleMapReport } from '../dist/report.js';
+import { materializeRef, GitRefError } from '../dist/gitref.js';
 
 const HELP = `styleproof-report — reviewable before/after report from two captures
 
 usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]
+       styleproof-report --base-ref <gitref> <mapsDir> --out <dir> [options]
 
 options:
+  --base-ref <ref>          use <mapsDir> as committed at <ref> (e.g. main) as the
+                            before side — base from git, no recapture
   --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)
@@ -47,6 +52,7 @@ let minWidth;
 let minHeight;
 let includeLayoutNoise = false;
 let includeContent = false;
+let baseRef = null;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
   if (a === '-h' || a === '--help') {
@@ -70,14 +76,36 @@ for (let i = 0; i < argv.length; i++) {
   else if (a.startsWith('--include-layout-noise=')) includeLayoutNoise = a.slice(23) !== 'false';
   else if (a === '--include-content') includeContent = true;
   else if (a.startsWith('--include-content=')) includeContent = a.slice(18) !== 'false';
+  else if (a === '--base-ref') baseRef = argv[++i];
+  else if (a.startsWith('--base-ref=')) baseRef = a.slice(11);
   else if (a.startsWith('--')) {
     console.error(`unknown flag: ${a}`);
     process.exit(2);
   } else args.push(a);
 }
-if (args.length !== 2) {
-  console.error('usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]  (--help for all options)');
-  process.exit(2);
+let beforeDir;
+let afterDir;
+let tmpBase = null;
+if (baseRef) {
+  if (args.length !== 1) {
+    console.error('usage: styleproof-report --base-ref <gitref> <mapsDir> --out <dir> [options]');
+    process.exit(2);
+  }
+  try {
+    tmpBase = materializeRef(baseRef, args[0]);
+  } catch (e) {
+    console.error(e instanceof GitRefError ? `styleproof-report --base-ref: ${e.message}` : String(e?.message ?? e));
+    process.exit(2);
+  }
+  beforeDir = tmpBase;
+  afterDir = args[0];
+} else {
+  if (args.length !== 2) {
+    console.error('usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]  (--help for all options)');
+    process.exit(2);
+  }
+  beforeDir = args[0];
+  afterDir = args[1];
 }
 for (const [name, val] of [
   ['--pad', pad],
@@ -99,8 +127,8 @@ if (foldDetailsAt !== undefined && Number.isNaN(foldDetailsAt)) {
 let result;
 try {
   result = generateStyleMapReport({
-    beforeDir: args[0],
-    afterDir: args[1],
+    beforeDir,
+    afterDir,
     outDir: flags.out,
     imageBaseUrl: flags.imageBaseUrl || undefined,
     pad,
@@ -114,6 +142,8 @@ try {
 } catch (e) {
   console.error(e.message);
   process.exit(2);
+} finally {
+  if (tmpBase) fs.rmSync(tmpBase, { recursive: true, force: true });
 }
 
 const newNote = result.newSurfaces ? ` (+${result.newSurfaces} new surface(s) with no baseline)` : '';

package/dist/breakpoints.d.ts

@@ -0,0 +1,30 @@
+import type { Page } from '@playwright/test';
+/**
+ * Parse the px width BOUNDARIES a single `@media` condition introduces — the widths
+ * at which its match flips. A `min-width: V` opens a band at `V`; a `max-width: V`
+ * keeps the band below active through `V`, so the next band opens at `V + 1`. Range
+ * syntax (`width >= V`, `V <= width`, `width < V`, …) is normalised the same way.
+ * `em`/`rem` are resolved against `rootFontPx`. Non-width conditions yield nothing.
+ */
+export declare function mediaTextWidthBoundaries(mediaText: string, rootFontPx?: number): number[];
+/**
+ * Turn breakpoint boundaries into one representative viewport width per band: the
+ * base band below the first boundary uses `baseWidth` (clamped strictly inside it),
+ * every other band its lower boundary. With no boundaries (no width `@media` rules)
+ * the layout is band-invariant, so a single `noQueryWidth` covers it. Ascending,
+ * de-duplicated.
+ */
+export declare function widthsFromBoundaries(boundaries: number[], opts?: {
+    baseWidth?: number;
+    noQueryWidth?: number;
+}): number[];
+/**
+ * Detect the viewport widths to sweep for the currently-loaded page: read every
+ * `@media` width breakpoint from the live CSSOM and return one width per band.
+ * Throws if any stylesheet is unreadable (cross-origin) — detection is authoritative
+ * or it fails; it never guesses. Call after the page has loaded its styles.
+ */
+export declare function detectViewportWidths(page: Page, opts?: {
+    baseWidth?: number;
+    noQueryWidth?: number;
+}): Promise<number[]>;

package/dist/breakpoints.js

@@ -0,0 +1,114 @@
+/** Serialized into the browser by page.evaluate; cannot call module helpers. */
+function collectMediaTexts() {
+    const mediaTexts = [];
+    const unreadable = [];
+    const walk = (rules) => {
+        for (const rule of Array.from(rules)) {
+            // CSSMediaRule has `.media`; a CSSContainerRule does not, so container
+            // queries (container-relative, not viewport) are correctly skipped here.
+            const media = rule.media;
+            if (media && typeof media.mediaText === 'string')
+                mediaTexts.push(media.mediaText);
+            // Descend into @supports / @layer / nested @media groups.
+            const nested = rule.cssRules;
+            if (nested) {
+                try {
+                    walk(nested);
+                }
+                catch {
+                    /* a nested rule list we can't read — ignore, top-level catch reports sheets */
+                }
+            }
+        }
+    };
+    for (const sheet of Array.from(document.styleSheets)) {
+        try {
+            const rules = sheet.cssRules; // throws for a cross-origin sheet with no CORS
+            if (rules)
+                walk(rules);
+        }
+        catch {
+            unreadable.push(sheet.href ?? '<inline>');
+        }
+    }
+    const rootFontPx = parseFloat(getComputedStyle(document.documentElement).fontSize) || 16;
+    return { mediaTexts, unreadable, rootFontPx };
+}
+/**
+ * Parse the px width BOUNDARIES a single `@media` condition introduces — the widths
+ * at which its match flips. A `min-width: V` opens a band at `V`; a `max-width: V`
+ * keeps the band below active through `V`, so the next band opens at `V + 1`. Range
+ * syntax (`width >= V`, `V <= width`, `width < V`, …) is normalised the same way.
+ * `em`/`rem` are resolved against `rootFontPx`. Non-width conditions yield nothing.
+ */
+export function mediaTextWidthBoundaries(mediaText, rootFontPx = 16) {
+    const t = mediaText.toLowerCase();
+    const out = new Set();
+    const px = (v, unit) => (unit === 'px' ? v : v * rootFontPx);
+    const add = (v) => {
+        const n = Math.round(v);
+        if (n > 0)
+            out.add(n);
+    };
+    let m;
+    const reMinMax = /\((min|max)-width\s*:\s*([\d.]+)(px|r?em)\)/g;
+    while ((m = reMinMax.exec(t)) !== null) {
+        const v = px(parseFloat(m[2]), m[3]);
+        if (m[1] === 'min')
+            add(v);
+        else
+            add(v + 1); // max-width: V → next band opens at V+1
+    }
+    // Range syntax: `width <op> Vpx` and the mirrored `Vpx <op> width`.
+    const flip = (op) => (op === '<=' ? '>=' : op === '<' ? '>' : op === '>=' ? '<=' : '<');
+    const addCmp = (v, op) => {
+        if (op === '>=')
+            add(v);
+        else if (op === '>')
+            add(v + 1);
+        else if (op === '<=')
+            add(v + 1);
+        else if (op === '<')
+            add(v);
+    };
+    const reRight = /width\s*(<=|>=|<|>)\s*([\d.]+)(px|r?em)/g;
+    while ((m = reRight.exec(t)) !== null)
+        addCmp(px(parseFloat(m[2]), m[3]), m[1]);
+    const reLeft = /([\d.]+)(px|r?em)\s*(<=|>=|<|>)\s*width/g;
+    while ((m = reLeft.exec(t)) !== null)
+        addCmp(px(parseFloat(m[1]), m[2]), flip(m[3]));
+    return [...out].sort((a, b) => a - b);
+}
+/**
+ * Turn breakpoint boundaries into one representative viewport width per band: the
+ * base band below the first boundary uses `baseWidth` (clamped strictly inside it),
+ * every other band its lower boundary. With no boundaries (no width `@media` rules)
+ * the layout is band-invariant, so a single `noQueryWidth` covers it. Ascending,
+ * de-duplicated.
+ */
+export function widthsFromBoundaries(boundaries, opts = {}) {
+    const baseWidth = opts.baseWidth ?? 360;
+    const noQueryWidth = opts.noQueryWidth ?? 1280;
+    const bps = [...new Set(boundaries.map((n) => Math.round(n)))].filter((n) => n > 0).sort((a, b) => a - b);
+    if (bps.length === 0)
+        return [noQueryWidth];
+    const base = Math.min(baseWidth, bps[0] - 1);
+    return [...new Set([base, ...bps])].filter((n) => n > 0).sort((a, b) => a - b);
+}
+/**
+ * Detect the viewport widths to sweep for the currently-loaded page: read every
+ * `@media` width breakpoint from the live CSSOM and return one width per band.
+ * Throws if any stylesheet is unreadable (cross-origin) — detection is authoritative
+ * or it fails; it never guesses. Call after the page has loaded its styles.
+ */
+export async function detectViewportWidths(page, opts = {}) {
+    const { mediaTexts, unreadable, rootFontPx } = await page.evaluate(collectMediaTexts);
+    if (unreadable.length > 0) {
+        throw new Error(`styleproof: can't detect breakpoints — ${unreadable.length} stylesheet(s) are unreadable ` +
+            `(cross-origin, no CORS): ${unreadable.join(', ')}. Detection reads every stylesheet to stay ` +
+            `100% accurate, so it fails rather than guess. Make them same-origin / CORS-readable, or set ` +
+            `\`widths\` on the surface to skip detection.`);
+    }
+    const boundaries = mediaTexts.flatMap((t) => mediaTextWidthBoundaries(t, rootFontPx));
+    return widthsFromBoundaries(boundaries, opts);
+}

package/dist/gitref.d.ts

@@ -0,0 +1,13 @@
+/** A readable failure materialising a base from git — CLIs map this to exit 2. */
+export declare class GitRefError extends Error {
+}
+/**
+ * Materialise the captures committed at `dir` as of `ref` into a fresh temp dir,
+ * so a diff/report can use e.g. `main`'s committed map as the base with no checkout
+ * and no recapture — the "base map lives on main, CI just diffs" model.
+ *
+ * Reads purely through git (`ls-tree`/`show`, no `tar`/deps); binary `.json.gz`
+ * bytes come straight from `git show`. The caller owns cleanup of the returned dir.
+ * Throws {@link GitRefError} (never exits) so it's reusable from any entry point.
+ */
+export declare function materializeRef(ref: string, dir: string): string;

package/dist/gitref.js

@@ -0,0 +1,44 @@
+import { spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+/** A readable failure materialising a base from git — CLIs map this to exit 2. */
+export class GitRefError extends Error {
+}
+/**
+ * Materialise the captures committed at `dir` as of `ref` into a fresh temp dir,
+ * so a diff/report can use e.g. `main`'s committed map as the base with no checkout
+ * and no recapture — the "base map lives on main, CI just diffs" model.
+ *
+ * Reads purely through git (`ls-tree`/`show`, no `tar`/deps); binary `.json.gz`
+ * bytes come straight from `git show`. The caller owns cleanup of the returned dir.
+ * Throws {@link GitRefError} (never exits) so it's reusable from any entry point.
+ */
+export function materializeRef(ref, dir) {
+    const top = spawnSync('git', ['rev-parse', '--show-toplevel'], { encoding: 'utf8', maxBuffer: 1 << 28 });
+    if (top.status !== 0)
+        throw new GitRefError('must run inside a git repository');
+    const toplevel = top.stdout.trim();
+    // -z: NUL-separated, unquoted paths (handles spaces/unicode).
+    const ls = spawnSync('git', ['ls-tree', '-r', '-z', '--name-only', ref, '--', dir], {
+        encoding: 'utf8',
+        maxBuffer: 1 << 28,
+    });
+    if (ls.status !== 0)
+        throw new GitRefError(`cannot read ${dir} at ${ref}: ${(ls.stderr || '').trim()}`);
+    const files = ls.stdout.split('\0').filter(Boolean);
+    if (files.length === 0) {
+        throw new GitRefError(`no committed captures at ${dir} in ${ref} — commit the maps so the base lives in git`);
+    }
+    const dirRepoRel = path.relative(toplevel, path.resolve(dir));
+    const dest = fs.mkdtempSync(path.join(os.tmpdir(), 'styleproof-baseref-'));
+    for (const f of files) {
+        const show = spawnSync('git', ['show', `${ref}:${f}`], { maxBuffer: 1 << 28 }); // buffer — preserves .json.gz
+        if (show.status !== 0)
+            throw new GitRefError(`cannot read ${f} at ${ref}`);
+        const out = path.join(dest, path.relative(dirRepoRel, f));
+        fs.mkdirSync(path.dirname(out), { recursive: true });
+        fs.writeFileSync(out, show.stdout);
+    }
+    return dest;
+}

package/dist/index.d.ts

@@ -4,6 +4,7 @@ export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export type { Surface, DefineOptions, CrawlOptions } from './runner.js';
 export { coverageGaps } from './coverage.js';
 export type { CoverageGaps } from './coverage.js';
+export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';
 export { discoverNextRoutes } from './routes.js';
 export type { DiscoveredRoute } from './routes.js';
 export { selectCrawlLinks, defaultLinkKey } from './crawl.js';

package/dist/index.js

@@ -1,6 +1,7 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
 export { defineStyleMapCapture, defineCrawlCapture } from './runner.js';
 export { coverageGaps } from './coverage.js';
+export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';
 export { discoverNextRoutes } from './routes.js';
 export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';

package/dist/runner.d.ts

@@ -16,8 +16,14 @@ export type Surface = {
     go: (page: Page) => Promise<void>;
     /** Selectors for nondeterministic regions (live data, third-party embeds); skipped entirely. */
     ignore?: string[];
-    /** Viewport widths to sweep — one per @media band, so breakpoint rules are verified too. */
-    widths: number[];
+    /**
+     * Viewport widths to sweep — one per @media band, so breakpoint rules are verified
+     * too. OMIT to detect the app's real breakpoints from the loaded CSSOM and sweep one
+     * width per band automatically (no config); detection fails loudly if a stylesheet
+     * is cross-origin/unreadable rather than guess. Set it explicitly to pin the sweep
+     * or to cover a JS-only (`matchMedia`) breakpoint that has no CSS `@media` rule.
+     */
+    widths?: number[];
     /** Viewport height: a number, or a function of the width (default 800). */
     height?: number | ((width: number) => number);
 };
@@ -129,6 +135,19 @@ export declare function passLiveStreams(page: Page, url: string): Promise<void>;
  * forces it on either way.
  */
 export declare function defaultSelfCheck(replayFrom: string | undefined, env?: string | undefined): boolean;
+/**
+ * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
+ * default. Lets a pre-push hook redirect capture into a COMMITTED dir (so main
+ * always carries a base map and CI just diffs precomputed maps) without editing
+ * the spec — same env-wiring philosophy as `STYLEPROOF_REPLAY_*`.
+ */
+export declare function resolveBaseDir(baseDir: string | undefined, env?: string | undefined): string;
+/**
+ * Whether to save full-page screenshots: explicit `screenshots` wins, else
+ * `STYLEPROOF_SCREENSHOTS=0` turns them off — for committed maps you want the lean
+ * `.json.gz` only, never PNGs in git history. On by default otherwise.
+ */
+export declare function resolveScreenshots(screenshots: boolean | undefined, env?: string | undefined): boolean;
 /** The capture settings every capturer shares (everything bar the surface set). */
 type CaptureConfig = Omit<DefineOptions, 'surfaces' | 'expected' | 'exclude'>;
 /**

package/dist/runner.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps } from './coverage.js';
+import { detectViewportWidths } from './breakpoints.js';
 import { selectCrawlLinks } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
@@ -125,6 +126,23 @@ async function captureSurface(page, surface, width, s) {
 export function defaultSelfCheck(replayFrom, env = process.env.STYLEPROOF_SELFCHECK) {
     return env === '1' || !replayFrom;
 }
+/**
+ * Output base dir: explicit `baseDir` wins, then `STYLEPROOF_BASEDIR`, then the
+ * default. Lets a pre-push hook redirect capture into a COMMITTED dir (so main
+ * always carries a base map and CI just diffs precomputed maps) without editing
+ * the spec — same env-wiring philosophy as `STYLEPROOF_REPLAY_*`.
+ */
+export function resolveBaseDir(baseDir, env = process.env.STYLEPROOF_BASEDIR) {
+    return baseDir ?? env ?? '__stylemaps__';
+}
+/**
+ * Whether to save full-page screenshots: explicit `screenshots` wins, else
+ * `STYLEPROOF_SCREENSHOTS=0` turns them off — for committed maps you want the lean
+ * `.json.gz` only, never PNGs in git history. On by default otherwise.
+ */
+export function resolveScreenshots(screenshots, env = process.env.STYLEPROOF_SCREENSHOTS) {
+    return screenshots ?? env !== '0';
+}
 /**
  * Apply the capture defaults once, so explicit-surface and crawl capture can't
  * drift — the replay boundary, frozen clock and self-check policy resolve to the
@@ -135,8 +153,8 @@ function resolveSettings(c) {
     const replayFrom = c.replayFrom ?? process.env.STYLEPROOF_REPLAY_FROM;
     return {
         dir: c.dir,
-        baseDir: c.baseDir ?? '__stylemaps__',
-        screenshots: c.screenshots ?? true,
+        baseDir: resolveBaseDir(c.baseDir),
+        screenshots: resolveScreenshots(c.screenshots),
         replayFrom,
         replayUrl: c.replayUrl ?? process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**',
         freezeClock: c.freezeClock ?? true,
@@ -182,10 +200,24 @@ export function defineStyleMapCapture(options) {
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         for (const surface of surfaces) {
-            for (const width of surface.widths) {
-                test(`${surface.key} @ ${width}`, ({ page }) => {
-                    test.setTimeout(180_000);
-                    return captureSurface(page, surface, width, settings);
+            if (surface.widths && surface.widths.length > 0) {
+                // Explicit widths: one parallelizable test per surface × width.
+                for (const width of surface.widths) {
+                    test(`${surface.key} @ ${width}`, ({ page }) => {
+                        test.setTimeout(180_000);
+                        return captureSurface(page, surface, width, settings);
+                    });
+                }
+            }
+            else {
+                // Auto widths: the band set isn't known until the page renders its CSS, so a
+                // single test loads once, detects the breakpoints, then sweeps each band.
+                test(`${surface.key} @ auto`, async ({ page }) => {
+                    await surface.go(page);
+                    const widths = await detectViewportWidths(page);
+                    test.setTimeout(Math.max(180_000, widths.length * 60_000));
+                    for (const width of widths)
+                        await captureSurface(page, surface, width, settings);
                 });
             }
         }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.3.1",
+  "version": "2.5.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",
@@ -61,7 +61,8 @@
     "format:check": "prettier --check \"{src,bin,test,example}/**/*.{ts,mjs,js}\" \"*.{ts,js,mjs,json,md}\"",
     "test": "npm run build && node --test test/*.test.mjs",
     "test:watch": "node --test --watch test/*.test.mjs",
-    "test:e2e": "npm run build && playwright test test/smoke.e2e.spec.ts",
+    "test:e2e": "npm run build && playwright test",
+    "bench": "npm run build && node bench/gate-speed.mjs",
     "init": "node ./bin/styleproof-init.mjs",
     "prepare": "npm run build && husky",
     "prepublishOnly": "npm run clean && npm run build && npm run typecheck"