styleproof 2.4.0 → 3.0.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.0.0] - 2026-06-27
+
+**Milestone: the committed-map gate is how StyleProof works now.** Capture runs
+**pre-push** (parallel, with auto-detected `@media` breakpoints), the lean computed-
+style map is committed and **pushed in a single `git push`**, and CI is a
+**browser-less diff** of two precomputed maps — measured ~5400× cheaper on the
+compare step, and it skips build + serve entirely. `styleproof-init` scaffolds **and
+activates** the whole gate in one command. Coverage stays **full and sound**: every
+surface is captured (parallelised) and what changed is determined by _measuring_ the
+map, never by guessing which pages a code change touched. **No breaking API changes**
+— existing specs and the classic capture-both-in-CI flow keep working unchanged; the
+major marks the new default paradigm.
+
+### Changed
+
+- **`styleproof-init` now activates the pre-push hook for you** (`git config
+core.hooksPath .githooks`), so a single `styleproof-init` is all it takes — no
+  follow-up command. It never clobbers a repo that already manages hooks: if
+  `core.hooksPath` is already set or a `.husky/` dir exists, it leaves them alone and
+  prints the one-liner instead.
+
+## [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

package/bin/styleproof-diff.mjs

@@ -26,10 +26,8 @@
  * 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';
+import { materializeRef, GitRefError } from '../dist/gitref.js';
 
 const HELP = `styleproof-diff — certify a CSS refactor by diffing two computed-style captures
 
@@ -68,50 +66,6 @@ for (let i = 0; i < argv.length; i++) {
   } else args.push(argv[i]);
 }
 
-/** 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;
-}
-
 let dirA;
 let dirB;
 let tmpBase = null;
@@ -124,7 +78,12 @@ if (baseRef) {
     console.error(`no capture at ${args[0]}`);
     process.exit(2);
   }
-  tmpBase = materializeRef(baseRef, args[0]);
+  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 {

package/bin/styleproof-init.mjs

@@ -20,6 +20,7 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { spawnSync } from 'node:child_process';
 import { discoverNextRoutes } from '../dist/index.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
@@ -209,6 +210,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}',
   },
@@ -230,7 +239,8 @@ export default defineConfig({
 // 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 HOOK_DIR = '.githooks';
+const HOOK_PATH = `${HOOK_DIR}/pre-push`;
 const PREPUSH_HOOK = `#!/bin/sh
 # StyleProof pre-push hook (generated by styleproof-init).
 #
@@ -350,9 +360,33 @@ if (ci.wrote) {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+// Activate the hook so ONE `styleproof-init` is all it takes — but never clobber a
+// repo that already manages its hooks (husky, or an existing core.hooksPath); there
+// we leave it and print the one-liner instead.
+const git = (a) => spawnSync('git', a, { encoding: 'utf8' });
+const inGitRepo = git(['rev-parse', '--is-inside-work-tree']).status === 0;
+const existingHooksPath = inGitRepo ? git(['config', '--local', '--get', 'core.hooksPath']).stdout.trim() : '';
+const managesHooks = existingHooksPath !== '' || fs.existsSync('.husky');
+let hookActivated = false;
+if (inGitRepo && !managesHooks) {
+  if (git(['config', 'core.hooksPath', HOOK_DIR]).status === 0) {
+    hookActivated = true;
+    console.log(`activated the pre-push hook (core.hooksPath → ${HOOK_DIR})`);
+    wroteSomething = true;
+  }
+}
+
 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');
+if (hookActivated) {
+  console.log('  1. ✓ Pre-push hook is active — nothing to do.');
+} else if (managesHooks) {
+  console.log(`  1. Your repo already manages git hooks (${existingHooksPath || '.husky'}), so the hook`);
+  console.log(`     wasn't auto-activated. Point your hook runner at ${HOOK_DIR}/pre-push, or run:`);
+  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
+} else {
+  console.log('  1. Activate the pre-push hook (once per clone):');
+  console.log(`       git config core.hooksPath ${HOOK_DIR}`);
+}
 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.');

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/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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "2.4.0",
+  "version": "3.0.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"