styleproof 2.3.0 → 2.4.0

package/CHANGELOG.md

@@ -7,6 +7,58 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- **Animation freeze is now deterministic for content that mounts during the
+  settle.** Motion longhands (declared `animation`/`transition`) were read _before_
+  the settle, so an element that mounts while the page settles — a status glyph
+  gated on a snapshot fetch — missed that read: its declared `animation-duration`
+  was folded back on a run where it mounted early but left frozen to `0s` on a run
+  where it mounted late, surfacing as a self-check `animation-duration: 0s ↔ 1.6s`
+  non-deterministic failure. Motion is now read on the settled DOM (the freeze is
+  lifted only for that read), so a late-mounted animated element is captured
+  identically every run.
+
 ## [2.3.0] - 2026-06-23
 
 ### Added

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,31 @@
  *     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 os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.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 +51,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 +60,85 @@ 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);
+
+/** Run git, exiting 2 with a clean message on failure. */
+function git(gitArgs, { encoding = 'buffer' } = {}) {
+  const r = spawnSync('git', gitArgs, { encoding, maxBuffer: 1 << 28 });
+  return r;
+}
+
+/**
+ * Materialise the captures committed at <dir> as of <ref> into a fresh temp dir,
+ * so the base of the diff is e.g. main's map — no checkout, no recapture. Reads
+ * only via git (no `tar`/deps); binary `.json.gz` files come through `git show`.
+ */
+function materializeRef(ref, dir) {
+  const top = git(['rev-parse', '--show-toplevel'], { encoding: 'utf8' });
+  if (top.status !== 0) {
+    console.error('styleproof-diff --base-ref must run inside a git repository');
+    process.exit(2);
+  }
+  const toplevel = top.stdout.trim();
+  // -z: NUL-separated, unquoted paths (handles spaces/unicode).
+  const ls = git(['ls-tree', '-r', '-z', '--name-only', ref, '--', dir], { encoding: 'utf8' });
+  if (ls.status !== 0) {
+    console.error(`cannot read ${dir} at ${ref}: ${(ls.stderr || '').toString().trim()}`);
+    process.exit(2);
+  }
+  const files = ls.stdout.split('\0').filter(Boolean);
+  if (files.length === 0) {
+    console.error(`no committed captures at ${dir} in ${ref} — commit the maps so the base lives in git`);
+    process.exit(2);
+  }
+  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 = git(['show', `${ref}:${f}`]); // buffer — preserves .json.gz bytes
+    if (show.status !== 0) {
+      console.error(`cannot read ${f} at ${ref}`);
+      process.exit(2);
+    }
+    const out = path.join(dest, path.relative(dirRepoRel, f));
+    fs.mkdirSync(path.dirname(out), { recursive: true });
+    fs.writeFileSync(out, show.stdout);
+  }
+  return dest;
 }
-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);
+  }
+  tmpBase = materializeRef(baseRef, args[0]);
+  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 +147,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 +183,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.
@@ -221,6 +225,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 +331,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/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/capture.js

@@ -562,15 +562,26 @@ export async function captureStyleMap(page, options = {}) {
     // can't share a module-scope function) call ONE definition — no duplicated source.
     // It persists on `window` for every evaluate below (no navigation between them).
     await page.evaluate(injectPathOf);
-    // Motion longhands first (FREEZE_CSS would null them), then everything else.
-    // Motion never carries text — it's a settled end state of declared motion.
-    const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
-    await page.addStyleTag({ content: FREEZE_CSS });
+    // Freeze motion BEFORE settling: animating elements would otherwise read as
+    // perpetual churn during the settle, and any content that mounts during the
+    // settle must be frozen by the time we read it below.
+    const freezeTag = await page.addStyleTag({ content: FREEZE_CSS });
     // Settle: wait for async content to finish painting so base and head capture
     // the same loaded state, and collect any region still changing on its own
     // (a live stream/ticker) to exclude — animations are frozen above, so only
     // real content/layout churn lands here.
     const volatile = await detectVolatile(page, ignore, stabilize, captureText, options.pendingRequests);
+    // Motion longhands (transition/animation) are read separately so declared
+    // motion is verified even though every other value is a frozen end state.
+    // Read them on the SETTLED DOM, not before it: capturing pre-settle missed any
+    // element that mounts DURING the settle (e.g. a late status glyph), so its
+    // declared `animation-duration` was folded back on the run where it happened to
+    // mount early but left frozen (0s) on the run where it mounted late — a
+    // self-check "non-deterministic" flip. Lift the freeze just for this read (it
+    // nulls motion to 0s), then re-apply it before reading everything else.
+    await freezeTag.evaluate((el) => el.remove());
+    const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
+    await page.addStyleTag({ content: FREEZE_CSS });
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
     dropVolatile(base.elements, volatile);
     warnUntraversed(base.shadowHosts, base.sameOriginFrames);

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.0",
+  "version": "2.4.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",