styleproof 3.0.2 → 3.1.1

package/CHANGELOG.md

@@ -7,6 +7,87 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.1.1] - 2026-06-27
+
+### Changed
+
+- **Release workflow now verifies npm publication before tagging.** A release
+  fails before creating tags or GitHub Releases if `NPM_TOKEN` is missing, and
+  it verifies `styleproof@<version>` on npm after publishing or detecting an
+  already-published version.
+- **Generated pre-push hooks now restore no-op map churn before committing.** The
+  hook captures through `styleproof-map`, runs a semantic diff against `HEAD`, and
+  restores `stylemaps/` when the refreshed map is identical. When the map really
+  changes, the hook prints the diff plus a concrete live-state/replay hint before
+  creating the map commit.
+
+### Fixed
+
+- **Real cursor hover no longer contaminates the resting style map.** Capture now
+  parks the mouse over an ignored 1px hover sink before reading, matching the
+  existing focus blur behavior. The canonical resting map stays unhovered while
+  the forced `:hover` layer still records the hover delta.
+- **`styleproof-map` now writes lean committed maps by default.** Recorded HAR
+  files are removed after successful capture so private API responses are not
+  accidentally committed by the default pre-push flow. Use `--keep-har` or
+  `STYLEPROOF_KEEP_HAR=1` for explicit record/replay workflows.
+- **Generated pre-push hooks now clean untracked no-op artifacts.** When the
+  refreshed map is semantically identical to `HEAD`, the hook restores tracked
+  `stylemaps/` files and removes untracked files under `stylemaps/current`, so a
+  clean push leaves no generated capture debris behind.
+
+## [3.1.0] - 2026-06-27
+
+### Changed
+
+- **`styleproof-init` now follows the repo's package manager.** Generated
+  Playwright configs, pre-push hooks, and browser-less CI workflows detect
+  `bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or `package-lock.json`
+  and scaffold matching build, install, `styleproof-map`, and `styleproof-diff`
+  commands instead of assuming npm everywhere.
+- **The committed-map flow is now a three-command CLI path.** Run
+  `styleproof-init`, `styleproof-map`, then `styleproof-diff`. `styleproof-map`
+  captures the current branch into `stylemaps/current`, while `styleproof-diff`
+  now defaults to that map directory and infers the base ref from GitHub Actions,
+  `branch.<name>.gh-merge-base`, `origin/main`, `origin/master`, `main`, or
+  `master` (or accepts `styleproof-diff main` / `--base-ref main`). The zero-diff
+  success line says `0 changed surfaces across N captured surface(s)` instead of
+  the confusing `N surfaces identical` / `0 surfaces identical` wording, and the
+  `--json` payload includes `compared` so consumers can show the same count.
+- **`styleproof-report` now mirrors the diff CLI defaults.** Run
+  `styleproof-report` with no args to generate the side-by-side report from
+  `stylemaps/current` against the inferred base branch, or pass
+  `styleproof-report main` / `--base-ref main` to pin the base while keeping the
+  committed-map directory default.
+- **No-arg diff/report now understand stacked PRs locally.** After
+  `GITHUB_BASE_REF` and explicit `branch.<name>.gh-merge-base` config, the shared
+  base-ref inference asks `gh pr view` for the current PR base before falling back
+  to `main`/`master`, so stacked branches compare against their real review base
+  out of the box.
+
+### Fixed
+
+- **CLI errors now lead with the recovery step.** Missing specs, unknown flags,
+  absent working maps, and missing committed base maps now print a concrete
+  `Next:` line such as `run styleproof-map`, pass `--maps-dir <dir>`, or commit
+  captures on the base branch.
+- **`styleproof-map` now runs generated capture tests correctly.** The CLI no
+  longer passes the spec path as a Playwright file filter, because StyleProof's
+  generated tests are registered through the package runner. It now targets the
+  capture suite with Playwright's grep path, matching the public
+  `styleproof-init` → `styleproof-map` → `styleproof-diff` flow.
+- **Clean StyleProof PR runs now leave a visible receipt.** The Action creates or
+  updates its PR comment with `No visual changes detected.` even when there is no
+  existing report comment yet, and `styleproof-init` scaffolds the same
+  no-change PR comment for the browser-less committed-map workflow.
+- **Layout-equivalent auto-margin drift no longer creates phantom diffs.** Some
+  browser/forced-state combinations can report horizontal `margin-left` /
+  `margin-right` / logical margin equivalents differently even when the captured
+  document-space rectangle is unchanged. StyleProof now drops only those
+  margin-longhand differences when the element's rect is identical on both sides,
+  including inside forced `:hover`/`:focus`/`:active` deltas. If the rect moves,
+  the margin change still reports.
+
 ## [3.0.2] - 2026-06-27
 
 ### Fixed
@@ -841,7 +922,9 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.2...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...HEAD
+[3.1.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.0...v3.1.1
+[3.1.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.2...v3.1.0
 [3.0.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.1...v3.0.2
 [3.0.1]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.0.0...v3.0.1
 [3.0.0]: https://github.com/BenSheridanEdwards/StyleProof/compare/v2.5.0...v3.0.0

package/README.md

@@ -16,6 +16,7 @@ On every PR, StyleProof diffs the PR head's computed-style map against the base
 
 - A **lean summary comment** linking to a committed side-by-side report — the report is the complete source of truth (**one section per distinct change**, with a before/after cropped screenshot cropped from the same rectangle so the two sides line up exactly, **plain-English bullets that tell you what to look for** — `columns: 2 → 3`, `recoloured cyan → amber` — and the exact property changes). The comment never duplicates the report, so the two can't drift, and it renders identically on public and private repos.
 - A single **Approve all changes** checkbox in the comment, driving a `StyleProof` commit status: red until one tick signs off every change, green when there are none. The reviewer who ticks it is recorded inline (_approved by @them_), sourced from the commit status so it survives a report re-run.
+- **Clean runs leave a receipt too.** When no visual changes are detected, StyleProof still creates or updates the PR comment with `✓ No visual changes detected.`, so a green status has a visible record instead of only a silent check.
 - **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown in the report under a `🆕 new surface` heading but never holds the status red and needs no sign-off. It becomes part of the baseline once merged.
 - The diff is always **head-vs-base**, so the report is _exactly what this PR changes_ — whether the maps are captured fresh in CI or (by default) committed pre-push and diffed browser-free in CI. See [Quickstart](#quickstart).
 
@@ -167,7 +168,7 @@ It scaffolds:
 
 - a **capture spec** (`e2e/styleproof.spec.ts`) describing your surfaces (a Next.js app gets its routes _and_ the coverage guard wired automatically — see below);
 - a **`playwright.config.ts`** that builds and serves a **production build** (never a flaky dev server) and captures surfaces **in parallel** (`fullyParallel`);
-- a **pre-push hook** (`.githooks/pre-push`, activated for you via `core.hooksPath` — it won't clobber an existing husky setup) that captures the map, commits it as a lean `.json.gz` under `stylemaps/`, and **pushes it with your branch — one `git push`, never two**;
+- a **pre-push hook** (`.githooks/pre-push`, activated for you via `core.hooksPath` — it won't clobber an existing husky setup) that captures the map, restores no-op map churn, commits real map changes as lean `.json.gz` files under `stylemaps/`, and **pushes them with your branch — one `git push`, never two**;
 - a **browser-less CI workflow** that diffs your committed map against the base branch.
 
 Describe your surfaces — **omit `widths`** and StyleProof sweeps your real `@media` breakpoints automatically:
@@ -187,11 +188,36 @@ defineStyleMapCapture({
 });
 ```
 
-**That's the whole loop.** Capture happens **pre-push on your machine** (where the app already builds and serves); the lean map is committed and pushed; and **CI is a browser-less diff of two precomputed maps** — no build, no browser, just a fast comparison (~5400× cheaper on the compare step than re-capturing both sides in CI). `main` always carries a base map, so every PR is _your code vs the committed base_. Require the `StyleProof` status in branch protection and an unverified visual change can't merge.
+The manual loop is deliberately three commands:
+
+```bash
+npx styleproof-init
+npx styleproof-map
+npx styleproof-diff
+```
+
+`styleproof-map` captures this branch into `stylemaps/current` as lean committed
+maps: HAR recordings are removed by default so private API responses do not land
+in git. Keep them only for an explicit record/replay workflow with
+`styleproof-map --keep-har` (or `STYLEPROOF_KEEP_HAR=1`). `styleproof-diff` then
+compares the committed map against the base branch automatically: in GitHub
+Actions it uses the PR base; locally it checks `branch.<name>.gh-merge-base`,
+then the current GitHub PR base via `gh pr view` (handy for stacked PRs), then
+`origin/main`, `origin/master`, `main`, and `master`. Pin it when needed with
+`styleproof-diff main`, `styleproof-diff master`, or `styleproof-diff --base-ref
+origin/my-base`.
+
+**That's the whole loop.** Capture happens **pre-push on your machine** (where the app already builds and serves); the hook first diffs the refreshed map against `HEAD` and restores it when the semantic map is unchanged, otherwise it commits and pushes the lean map; and **CI is a browser-less diff of two precomputed maps** — no build, no browser, just a fast comparison (~5400× cheaper on the compare step than re-capturing both sides in CI). `main` always carries a base map, so every PR is _your code vs the committed base_. Require the `StyleProof` status in branch protection and an unverified visual change can't merge.
 
 > **Same-environment note.** Computed styles depend on the browser build and installed fonts, so maps are only comparable when captured in the same environment (your machine, or a pinned container). The self-check fails loudly on a non-deterministic capture, so drift never passes silently.
 
-**Want the side-by-side report + one-click approval** (not just a pass/fail diff)? Use the Action, pointing it at the base ref:
+**Want the local side-by-side report** (not just a pass/fail diff)? Run `npx
+styleproof-report` after `styleproof-map`; it uses the same inferred base ref and
+`stylemaps/current` defaults as `styleproof-diff`. Pin the base with
+`styleproof-report main` or keep the manual form with `styleproof-report before
+after --out report`.
+
+**Want the side-by-side report + one-click approval**? Use the Action, pointing it at the base ref:
 
 ```yaml
 # .github/workflows/styleproof.yml
@@ -229,6 +255,12 @@ Copy both `capture` and `report` files to `.github/workflows/` (the `report` one
 - **Frozen clock.** `Date.now()` / `new Date()` are pinned to a fixed instant, so time-derived styling (`stale > 1h → red`) can't drift. Timers keep running, so settling still works.
 - **Self-check** — captures each surface twice and fails if they differ, so a replay gap or unseeded randomness surfaces as a clear _"non-deterministic capture"_ error, never as a phantom change on an unrelated PR. **On by default while recording** (where live nondeterminism shows up); off on the replay run, which renders against the recorded HAR and is deterministic by construction. `STYLEPROOF_SELFCHECK=1` forces it on for both; `selfCheck: false` opts out.
 - **Framework noise is skipped by default.** Non-visual and framework-injected elements never count as a change — `<meta>`/`<title>`/`<script>`/`<style>`/… (which Next.js streams into the body then hoists) and live regions like Next's `next-route-announcer`. A real stylesheet change still shows up in the affected elements' computed styles, not in the `<style>` tag. Add your own selectors with `ignore` — they extend this default, they don't replace it.
+- **Layout-equivalent margin noise is normalised.** If the browser reports
+  horizontal auto-centering margins (`margin-left`/`margin-right` and logical
+  equivalents) differently but the captured document-space rectangle is
+  identical, StyleProof treats that as the same rendered layout, including in
+  forced `:hover`/`:focus`/`:active` deltas. If the box moves or resizes, the
+  margin change still reports.
 
 > Replay covers data the page _fetches_. If your app **server-renders** differently per environment (SSR feature flags, locale), still capture both sides with the same server env so the rendered HTML matches.
 
@@ -241,9 +273,10 @@ Anything still moving on its own after that is detected as a volatile region and
 | Handled for you — zero config                               | How                                                                                      |
 | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
 | In-flight data, fonts, late layout                          | network-aware settle holds until requests finish _and_ the computed styles stop changing |
-| Animations, transitions, focus ring, caret                  | frozen / blurred before the map is read                                                  |
+| Animations, transitions, real hover/focus, caret            | frozen / neutralised before the map is read; forced states are captured separately       |
 | Clock-derived styling (`stale > 1h → red`)                  | `Date.now()` / `new Date()` frozen to a fixed instant                                    |
 | Framework & non-visual noise (`<script>`, route announcers) | skipped by default                                                                       |
+| Layout-equivalent horizontal auto margins                   | ignored only when the captured element rectangle is unchanged                            |
 | Semantic live-state candidates (`aria-live`, `role=status`) | auto-detected and kept in the diff when stable                                           |
 | Live / volatile regions (tickers, third-party embeds)       | auto-detected as still-moving and excluded from direct element comparison                |
 | Non-deterministic capture (replay gap, unseeded randomness) | self-check flags it _while recording_, with a named error                                |
@@ -359,9 +392,10 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 **CLIs** (every flag accepts `--flag value` and `--flag=value`; `--help` lists all):
 
-- `styleproof-init` — scaffold **and activate** the whole gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), the pre-push capture-and-push hook, and the browser-less CI workflow. One command.
-- `styleproof-diff <beforeDir> <afterDir>` — the certify gate; exits `0` certified (identical), `1` on a diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against). Use **`styleproof-diff --base-ref <gitref> <mapsDir>`** to diff your committed maps against a git ref (the committed-map flow) — no second dir, no recapture.
-- `styleproof-report <beforeDir> <afterDir> --out <dir>` — render the diff to a Markdown report with before/after crops. Add `--include-content` for the opt-in, advisory content section (see above); **`--base-ref <gitref> <mapsDir>`** reads the base from git like the diff CLI.
+- `styleproof-init` — scaffold **and activate** the whole gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), the pre-push capture-and-push hook, and the browser-less CI workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default) instead of assuming npm.
+- `styleproof-map` — capture the current branch's computed-style map through Playwright. By default it writes lean committed maps to `stylemaps/current`; pass `--spec`, `--dir`, `--base-dir`, or `--screenshots` when you need a custom capture.
+- `styleproof-diff` — the certify gate. With no args, it diffs `stylemaps/current` against the inferred base branch (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form. Exits `0` certified (identical), `1` on a diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
+- `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports `stylemaps/current` against the inferred base branch; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
 
 A programmatic API is also exported — `captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, and the breakpoint helpers `detectViewportWidths` / `widthsFromBoundaries`, among others. For the capture internals, the approve-workflow trust model, and how to contribute, see [CONTRIBUTING](https://github.com/BenSheridanEdwards/StyleProof/blob/main/CONTRIBUTING.md) and the [`example/`](https://github.com/BenSheridanEdwards/StyleProof/tree/main/example) workflows.
 

package/bin/styleproof-diff.mjs

@@ -2,8 +2,9 @@
 /**
  * Diff two computed-style map captures (see styleproof).
  *
+ *   styleproof-diff [baseRef] [--maps-dir <dir>] [--max N] [--json <file>]
+ *   styleproof-diff --base-ref <gitref> [mapsDir] [--max N] [--json <file>]
  *   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
@@ -26,17 +27,31 @@
  * error, 3 = only new surfaces (present on one side, no baseline to diff against).
  */
 import fs from 'node:fs';
+import path from 'node:path';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
-import { materializeRef, GitRefError } from '../dist/gitref.js';
+import { cleanupBaseRefCaptureDirs, resolveBaseRefCaptureDirs } from '../dist/cli-base-ref.js';
+import {
+  cliErrorMessage,
+  isHelpArg,
+  missingManualCaptureMessage,
+  showHelpAndExit,
+  unknownFlagMessage,
+} from '../dist/cli-errors.js';
 
-const HELP = `styleproof-diff — certify a CSS refactor by diffing two computed-style captures
+const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
+const DEFAULT_MAPS_DIR = 'stylemaps/current';
 
-usage: styleproof-diff <beforeDir> <afterDir> [options]
-       styleproof-diff --base-ref <gitref> <mapsDir> [options]
+const HELP = `${COMMAND} — certify a CSS refactor by diffing two computed-style map captures
+
+usage: ${COMMAND} [baseRef] [options]
+       ${COMMAND} --base-ref <gitref> [mapsDir] [options]
+       ${COMMAND} <beforeDir> <afterDir> [options]
 
 options:
   --base-ref <ref> diff <mapsDir> as committed at <ref> (e.g. main) against your
                    working <mapsDir> — base from git, no recapture
+  --maps-dir <dir> committed map dir for the base-ref flow
+                   (default: ${DEFAULT_MAPS_DIR})
   --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
@@ -50,51 +65,54 @@ const args = [];
 let MAX = 40;
 let jsonOut = null;
 let baseRef = null;
+let mapsDir = DEFAULT_MAPS_DIR;
 for (let i = 0; i < argv.length; i++) {
-  if (argv[i] === '-h' || argv[i] === '--help') {
-    process.stdout.write(HELP);
-    process.exit(0);
-  } else if (argv[i] === '--max') MAX = Number(argv[++i]);
+  if (isHelpArg(argv[i])) showHelpAndExit(HELP);
+  else if (argv[i] === '--max') MAX = Number(argv[++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] === '--maps-dir') mapsDir = argv[++i];
+  else if (argv[i].startsWith('--maps-dir=')) mapsDir = argv[i].slice(11);
   else if (argv[i].startsWith('--')) {
-    console.error(`unknown flag: ${argv[i]}`);
+    console.error(unknownFlagMessage(COMMAND, argv[i]));
     process.exit(2);
   } else args.push(argv[i]);
 }
 
 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]}`);
+let baseCapture = null;
+if (baseRef || args.length <= 1) {
+  if (!Number.isFinite(MAX)) {
+    console.error(`usage: ${COMMAND} [baseRef] [--maps-dir <dir>] [--max N] [--json <file>]`);
     process.exit(2);
   }
   try {
-    tmpBase = materializeRef(baseRef, args[0]);
+    baseCapture = resolveBaseRefCaptureDirs({
+      command: COMMAND,
+      baseRef,
+      mapsDir,
+      args,
+      usage: `usage: ${COMMAND} --base-ref <gitref> [mapsDir] [--max N] [--json <file>]`,
+    });
   } catch (e) {
-    console.error(e instanceof GitRefError ? `styleproof-diff --base-ref: ${e.message}` : String(e?.message ?? e));
+    console.error(cliErrorMessage(e));
     process.exit(2);
   }
-  dirA = tmpBase;
-  dirB = args[0];
+  dirA = baseCapture.beforeDir;
+  dirB = baseCapture.afterDir;
 } else {
   if (args.length !== 2 || !Number.isFinite(MAX)) {
-    console.error('usage: styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]  (--help for all options)');
+    console.error(`usage: ${COMMAND} <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}`);
+      console.error(missingManualCaptureMessage(COMMAND, d));
       process.exit(2);
     }
   }
@@ -107,9 +125,9 @@ try {
   console.error(e.message);
   process.exit(2);
 } finally {
-  if (tmpBase) fs.rmSync(tmpBase, { recursive: true, force: true });
+  cleanupBaseRefCaptureDirs(baseCapture);
 }
-const { surfaces, counts } = result;
+const { surfaces, counts, compared } = result;
 
 for (const sd of surfaces) {
   if (sd.missing) {
@@ -138,7 +156,7 @@ for (const sd of surfaces) {
   if (lines.length > MAX) console.log(`  ... and ${lines.length - MAX} more lines (re-run with --max ${lines.length})`);
 }
 
-if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces }, null, 2));
+if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared }, null, 2));
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;
@@ -148,7 +166,7 @@ const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline
 console.log(
   total === 0
     ? newSurfaces === 0
-      ? `\n✓ ${surfaceCount} surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches`
+      ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — shown for reference, no reviewable change`
     : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}`,
 );

package/bin/styleproof-init.mjs

@@ -22,6 +22,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { discoverNextRoutes } from '../dist/index.js';
+import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
 
@@ -42,13 +43,11 @@ What it writes:
   - playwright.config.ts, only if absent (an existing one is left untouched)
 
 After running, capture a baseline against a PRODUCTION build:
-  STYLEMAP_DIR=baseline npx playwright test styleproof
+  npx styleproof-map
 
 To certify a refactor:
-  STYLEMAP_DIR=before npx playwright test styleproof
-  # ...refactor your CSS...
-  STYLEMAP_DIR=after  npx playwright test styleproof
-  npx styleproof-diff __stylemaps__/before __stylemaps__/after
+  npx styleproof-map
+  npx styleproof-diff
 `;
 
 const argv = process.argv.slice(2);
@@ -57,10 +56,8 @@ let baseUrl = 'http://localhost:3000';
 let force = false;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a === '-h' || a === '--help') {
-    process.stdout.write(HELP);
-    process.exit(0);
-  } else if (a === '--dir') specPath = argv[++i];
+  if (isHelpArg(a)) showHelpAndExit(HELP);
+  else if (a === '--dir') specPath = argv[++i];
   else if (a.startsWith('--dir=')) specPath = a.slice(6);
   else if (a === '--base-url') baseUrl = argv[++i];
   else if (a.startsWith('--base-url=')) baseUrl = a.slice(11);
@@ -110,10 +107,8 @@ const HEADER = `/**
  * 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...
- *   STYLEMAP_DIR=after  npx playwright test styleproof   # capture again
- *   npx styleproof-diff __stylemaps__/before __stylemaps__/after
+ *   npx styleproof-map   # capture this branch into stylemaps/current
+ *   npx styleproof-diff  # compare against the inferred base branch
  */`;
 
 // Next.js detected: derive both surfaces and the coverage guard from the app's
@@ -198,6 +193,62 @@ defineStyleMapCapture({
 });
 `;
 
+const PACKAGE_MANAGERS = {
+  npm: {
+    label: 'npm',
+    run: (script) => `npm run ${script}`,
+    exec: (command) => `npx ${command}`,
+    install: 'npm ci',
+    setup: `      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: npm`,
+  },
+  yarn: {
+    label: 'Yarn v1',
+    run: (script) => `npx -y yarn@1.22.22 ${script}`,
+    exec: (command) => `npx -y yarn@1.22.22 ${command}`,
+    install: 'npx -y yarn@1.22.22 install --frozen-lockfile --non-interactive',
+    setup: `      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: yarn
+          cache-dependency-path: yarn.lock`,
+  },
+  pnpm: {
+    label: 'pnpm',
+    run: (script) => `npx -y pnpm ${script}`,
+    exec: (command) => `npx -y pnpm exec ${command}`,
+    install: 'npx -y pnpm install --frozen-lockfile',
+    setup: `      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+          cache: pnpm
+          cache-dependency-path: pnpm-lock.yaml`,
+  },
+  bun: {
+    label: 'Bun',
+    run: (script) => `bun run ${script}`,
+    exec: (command) => `bunx ${command}`,
+    install: 'bun install --frozen-lockfile',
+    setup: `      - uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+      - uses: oven-sh/setup-bun@v2`,
+  },
+};
+
+function detectPackageManager(root) {
+  if (fs.existsSync(path.join(root, 'bun.lock')) || fs.existsSync(path.join(root, 'bun.lockb'))) {
+    return PACKAGE_MANAGERS.bun;
+  }
+  if (fs.existsSync(path.join(root, 'pnpm-lock.yaml'))) return PACKAGE_MANAGERS.pnpm;
+  if (fs.existsSync(path.join(root, 'yarn.lock'))) return PACKAGE_MANAGERS.yarn;
+  return PACKAGE_MANAGERS.npm;
+}
+
+const PM = detectPackageManager(process.cwd());
+
 const CONFIG = `import { defineConfig, devices } from '@playwright/test';
 
 // Generated by styleproof-init.
@@ -225,7 +276,7 @@ export default defineConfig({
   // accidentally capture a dev server. Adjust the command to your framework (e.g.
   // \`vite build && vite preview\`); a server already running locally is reused.
   webServer: {
-    command: 'npm run build && npm run start',
+    command: '${PM.run('build')} && ${PM.run('start')}',
     url: process.env.BASE_URL || '${baseUrl}',
     reuseExistingServer: !process.env.CI,
     timeout: 600_000, // a cold production build can take a few minutes
@@ -256,8 +307,32 @@ remote="$1"
 # 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}
+${PM.exec(`styleproof-map --spec ${specPath}`)}
+
+if git cat-file -e HEAD:stylemaps/current 2>/dev/null; then
+  tmp="\${TMPDIR:-/tmp}/styleproof-pre-push-diff.$$"
+  set +e
+  ${PM.exec('styleproof-diff --base-ref HEAD --max=20')} > "$tmp"
+  code=$?
+  set -e
+
+  if [ "$code" -eq 2 ]; then
+    cat "$tmp" >&2
+    rm -f "$tmp"
+    exit 2
+  fi
+
+  if [ "$code" -eq 0 ]; then
+    rm -f "$tmp"
+    git restore --source=HEAD -- stylemaps
+    git clean -fdq -- stylemaps/current
+    exit 0
+  fi
+
+  cat "$tmp" >&2
+  rm -f "$tmp"
+  echo "StyleProof: style map changed. If this was not an intended visual change, pin live states or replay/fixture the data boundary before pushing." >&2
+fi
 
 git add stylemaps
 git diff --cached --quiet -- stylemaps && exit 0  # map unchanged — let the push proceed
@@ -283,6 +358,8 @@ on: pull_request
 
 permissions:
   contents: read
+  issues: write
+  pull-requests: write
 
 jobs:
   styleproof:
@@ -291,12 +368,54 @@ jobs:
       - uses: actions/checkout@v4
         with:
           fetch-depth: 0 # need the base ref to read its committed map
-      - uses: actions/setup-node@v4
+${PM.setup}
+      - run: ${PM.install}
+      - id: diff
+        name: Diff this branch's committed map against the base
+        shell: bash
+        run: |
+          set +e
+          ${PM.exec(`styleproof-diff --base-ref "origin/\${{ github.event.pull_request.base.ref }}"`)} | tee styleproof-diff.txt
+          code=\${PIPESTATUS[0]}
+          set -e
+          echo "exit-code=\${code}" >> "$GITHUB_OUTPUT"
+          if [ "$code" -eq 0 ]; then
+            echo "result=clean" >> "$GITHUB_OUTPUT"
+          elif [ "$code" -eq 1 ] || [ "$code" -eq 3 ]; then
+            echo "result=changed" >> "$GITHUB_OUTPUT"
+          else
+            echo "result=error" >> "$GITHUB_OUTPUT"
+          fi
+      - name: Comment StyleProof result
+        if: >-
+          always() &&
+          github.event_name == 'pull_request' &&
+          steps.diff.outputs.result != '' &&
+          steps.diff.outputs.result != 'error'
+        uses: actions/github-script@v9
         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
+          script: |
+            const issue_number = context.payload.pull_request.number;
+            const marker = '<!-- styleproof-report -->';
+            const clean = '\${{ steps.diff.outputs.result }}' === 'clean';
+            const body = clean
+              ? marker + '\\n## 🗺️ StyleProof report\\n\\n✓ No visual changes detected.'
+              : marker + '\\n## 🗺️ StyleProof report\\n\\nVisual changes detected. See the StyleProof check logs for the computed-style diff.';
+            const { data: comments } = await github.rest.issues.listComments({
+              ...context.repo,
+              issue_number,
+              per_page: 100,
+            });
+            const existing = comments.find((comment) => comment.body && comment.body.includes(marker));
+            if (existing) {
+              await github.rest.issues.updateComment({ ...context.repo, comment_id: existing.id, body });
+            } else {
+              await github.rest.issues.createComment({ ...context.repo, issue_number, body });
+            }
+      - name: Fail on StyleProof diff
+        if: steps.diff.outputs.exit-code != '0'
+        shell: bash
+        run: exit \${{ steps.diff.outputs.exit-code }}
 `;
 
 function writeFileSafe(file, contents, { force: f } = {}) {

package/bin/styleproof-map.mjs

@@ -0,0 +1,116 @@
+#!/usr/bin/env node
+/**
+ * Capture the current branch's computed-style map.
+ *
+ * The zero-config path is the committed-map flow scaffolded by styleproof-init:
+ *   styleproof-map
+ *
+ * It runs Playwright against e2e/styleproof.spec.ts with:
+ *   STYLEMAP_DIR=current
+ *   STYLEPROOF_BASEDIR=stylemaps
+ *   STYLEPROOF_SCREENSHOTS=0
+ */
+import fs from 'node:fs';
+import { spawnSync } from 'node:child_process';
+import {
+  isHelpArg,
+  missingSpecMessage,
+  playwrightMissingMessage,
+  showHelpAndExit,
+  unknownFlagMessage,
+} from '../dist/cli-errors.js';
+
+const HELP = `styleproof-map — capture this branch's computed-style map
+
+usage: styleproof-map [options] [-- <playwright args>]
+
+options:
+  --spec <path>       StyleProof spec that must exist (default: e2e/styleproof.spec.ts)
+  --dir <label>       output label under --base-dir (default: current)
+  --base-dir <path>   output root directory (default: stylemaps)
+  --screenshots       keep screenshots for reports (default: off for committed maps)
+  --no-screenshots    write lean .json.gz maps only (default)
+  --keep-har          keep recorded HAR files for advanced replay workflows
+  -h, --help          show this help
+
+Examples:
+  styleproof-map
+  styleproof-map --spec e2e/styleproof.spec.ts
+  styleproof-map --dir review --base-dir __stylemaps__ --screenshots --keep-har
+`;
+
+const argv = process.argv.slice(2);
+let spec = 'e2e/styleproof.spec.ts';
+let dir = process.env.STYLEMAP_DIR ?? 'current';
+let baseDir = process.env.STYLEPROOF_BASEDIR ?? 'stylemaps';
+let screenshots = process.env.STYLEPROOF_SCREENSHOTS ?? '0';
+let keepHar = process.env.STYLEPROOF_KEEP_HAR === '1';
+const playwrightArgs = [];
+
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (isHelpArg(a)) showHelpAndExit(HELP);
+  else if (a === '--') {
+    playwrightArgs.push(...argv.slice(i + 1));
+    break;
+  } else if (a === '--spec') spec = argv[++i];
+  else if (a.startsWith('--spec=')) spec = a.slice(7);
+  else if (a === '--dir') dir = argv[++i];
+  else if (a.startsWith('--dir=')) dir = a.slice(6);
+  else if (a === '--base-dir') baseDir = argv[++i];
+  else if (a.startsWith('--base-dir=')) baseDir = a.slice(11);
+  else if (a === '--screenshots') screenshots = '1';
+  else if (a === '--no-screenshots') screenshots = '0';
+  else if (a === '--keep-har') keepHar = true;
+  else if (a.startsWith('--')) {
+    console.error(unknownFlagMessage('styleproof-map', a));
+    process.exit(2);
+  } else {
+    spec = a;
+  }
+}
+
+if (!spec) {
+  console.error('--spec requires a path');
+  process.exit(2);
+}
+if (!dir) {
+  console.error('--dir requires a label');
+  process.exit(2);
+}
+if (!baseDir) {
+  console.error('--base-dir requires a path');
+  process.exit(2);
+}
+if (!fs.existsSync(spec)) {
+  console.error(missingSpecMessage(spec));
+  process.exit(2);
+}
+
+function removeHarFiles(root) {
+  if (!fs.existsSync(root)) return;
+  for (const entry of fs.readdirSync(root, { withFileTypes: true })) {
+    const full = `${root}/${entry.name}`;
+    if (entry.isDirectory()) removeHarFiles(full);
+    else if (entry.isFile() && entry.name.endsWith('.har')) fs.rmSync(full, { force: true });
+  }
+}
+
+const command = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
+const env = {
+  ...process.env,
+  STYLEMAP_DIR: dir,
+  STYLEPROOF_BASEDIR: baseDir,
+  STYLEPROOF_SCREENSHOTS: screenshots,
+};
+const result = spawnSync(command, ['test', '--grep', 'styleproof capture', ...playwrightArgs], {
+  stdio: 'inherit',
+  env,
+});
+if (result.error) {
+  console.error(playwrightMissingMessage(result.error.message));
+  process.exit(2);
+}
+const status = result.status ?? 1;
+if (status === 0 && !keepHar) removeHarFiles(`${baseDir}/${dir}`);
+process.exit(status);

package/bin/styleproof-report.mjs

@@ -10,18 +10,24 @@
  * 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';
+import { cleanupBaseRefCaptureDirs, resolveBaseRefCaptureDirs } from '../dist/cli-base-ref.js';
+import { cliErrorMessage, isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
 
-const HELP = `styleproof-report — reviewable before/after report from two captures
+const COMMAND = 'styleproof-report';
+const DEFAULT_MAPS_DIR = 'stylemaps/current';
 
-usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]
-       styleproof-report --base-ref <gitref> <mapsDir> --out <dir> [options]
+const HELP = `${COMMAND} — reviewable before/after report from two captures
+
+usage: ${COMMAND} [baseRef] [options]
+       ${COMMAND} --base-ref <gitref> [mapsDir] [options]
+       ${COMMAND} <beforeDir> <afterDir> [options]
 
 options:
-  --base-ref <ref>          use <mapsDir> as committed at <ref> (e.g. main) as the
-                            before side — base from git, no recapture
+  --base-ref <ref>          report <mapsDir> as committed at <ref> (e.g. main)
+                            against your working <mapsDir> — base from git, no recapture
+  --maps-dir <dir>          committed map dir for the base-ref flow
+                            (default: ${DEFAULT_MAPS_DIR})
   --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)
@@ -53,12 +59,11 @@ let minHeight;
 let includeLayoutNoise = false;
 let includeContent = false;
 let baseRef = null;
+let mapsDir = DEFAULT_MAPS_DIR;
 for (let i = 0; i < argv.length; i++) {
   const a = argv[i];
-  if (a === '-h' || a === '--help') {
-    process.stdout.write(HELP);
-    process.exit(0);
-  } else if (a === '--out') flags.out = argv[++i];
+  if (isHelpArg(a)) showHelpAndExit(HELP);
+  else if (a === '--out') flags.out = argv[++i];
   else if (a.startsWith('--out=')) flags.out = a.slice(6);
   else if (a === '--image-base-url') flags.imageBaseUrl = argv[++i];
   else if (a.startsWith('--image-base-url=')) flags.imageBaseUrl = a.slice(17);
@@ -78,27 +83,31 @@ for (let i = 0; i < argv.length; i++) {
   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 === '--maps-dir') mapsDir = argv[++i];
+  else if (a.startsWith('--maps-dir=')) mapsDir = a.slice(11);
   else if (a.startsWith('--')) {
-    console.error(`unknown flag: ${a}`);
+    console.error(unknownFlagMessage(COMMAND, a));
     process.exit(2);
   } else args.push(a);
 }
 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);
-  }
+let baseCapture = null;
+if (baseRef || args.length <= 1) {
   try {
-    tmpBase = materializeRef(baseRef, args[0]);
+    baseCapture = resolveBaseRefCaptureDirs({
+      command: COMMAND,
+      baseRef,
+      mapsDir,
+      args,
+      usage: 'usage: styleproof-report --base-ref <gitref> [mapsDir] [--out <dir>] [options]',
+    });
   } catch (e) {
-    console.error(e instanceof GitRefError ? `styleproof-report --base-ref: ${e.message}` : String(e?.message ?? e));
+    console.error(cliErrorMessage(e));
     process.exit(2);
   }
-  beforeDir = tmpBase;
-  afterDir = args[0];
+  beforeDir = baseCapture.beforeDir;
+  afterDir = baseCapture.afterDir;
 } else {
   if (args.length !== 2) {
     console.error('usage: styleproof-report <beforeDir> <afterDir> --out <dir> [options]  (--help for all options)');
@@ -143,7 +152,7 @@ try {
   console.error(e.message);
   process.exit(2);
 } finally {
-  if (tmpBase) fs.rmSync(tmpBase, { recursive: true, force: true });
+  cleanupBaseRefCaptureDirs(baseCapture);
 }
 
 const newNote = result.newSurfaces ? ` (+${result.newSurfaces} new surface(s) with no baseline)` : '';

package/dist/capture.js

@@ -24,7 +24,26 @@ const FRAMEWORK_IGNORE = [
     'template',
     'next-route-announcer',
     '[id="__next-route-announcer__"]',
+    '[data-styleproof-hover-sink]',
 ];
+function installHoverSink() {
+    let sink = document.querySelector('[data-styleproof-hover-sink]');
+    if (!sink) {
+        sink = document.createElement('div');
+        sink.setAttribute('data-styleproof-hover-sink', '');
+        document.body.appendChild(sink);
+    }
+    sink.setAttribute('style', [
+        'position:fixed',
+        'left:0',
+        'top:0',
+        'width:1px',
+        'height:1px',
+        'z-index:2147483647',
+        'pointer-events:auto',
+        'opacity:0',
+    ].join(';'));
+}
 /** True if `path` is one of `roots` or a structural descendant of one. Shared by
  *  the capture (excluding live regions) and the diff (skipping them). */
 export function isUnder(path, roots) {
@@ -582,15 +601,17 @@ export async function captureStyleMap(page, options = {}) {
     const stabilize = options.stabilize ?? true;
     const captureText = options.captureText ?? false;
     const captureComponent = options.captureComponent ?? false;
-    // Neutralise real focus the same way FREEZE_CSS neutralises motion: blur
-    // whatever element holds focus so every read below is the no-interaction
-    // resting state. Real :focus is nondeterministic across runs (autofocus, late
-    // hydration, a stray prior action) and contaminates BOTH layers — it bakes a
-    // focus ring into the resting map, AND it cancels the forced-state :focus delta
-    // (forcing :focus on an already-focused element changes nothing, so the ring
-    // shows up as a delta on some runs but not others — a self-check "non-
-    // deterministic" failure). Interaction states are certified deterministically
-    // via CDP forcePseudoState below, never via whatever happened to be focused.
+    // Neutralise real hover/focus the same way FREEZE_CSS neutralises motion: park
+    // the pointer over an ignored 1px sink and blur whatever element holds focus so
+    // every read below is the no-interaction resting state. Real :hover/:focus is
+    // nondeterministic across runs (the last Playwright action, autofocus, late
+    // hydration, a stray prior action) and contaminates BOTH layers — it bakes an
+    // interaction style into the resting map, AND it cancels that forced-state
+    // delta (forcing :focus on an already-focused element changes nothing). States
+    // are certified deterministically via CDP forcePseudoState below, never via
+    // whatever happened to be hovered or focused.
+    await page.evaluate(installHoverSink);
+    await page.mouse.move(0, 0);
     await page.evaluate(() => document.activeElement?.blur?.());
     // Inject the structural-path helper once so both capturePage and
     // markInteractiveElements (each serialized into the page by page.evaluate, which

package/dist/cli-base-ref.d.ts

@@ -0,0 +1,15 @@
+export interface BaseRefCaptureDirs {
+    beforeDir: string;
+    afterDir: string;
+    baseRef: string;
+    mapsDir: string;
+    tmpBase: string;
+}
+export declare function resolveBaseRefCaptureDirs(options: {
+    command: string;
+    baseRef: string | null;
+    mapsDir: string;
+    args: string[];
+    usage: string;
+}): BaseRefCaptureDirs;
+export declare function cleanupBaseRefCaptureDirs(captureDirs: BaseRefCaptureDirs | null): void;

package/dist/cli-base-ref.js

@@ -0,0 +1,53 @@
+import fs from 'node:fs';
+import { inferBaseRef, materializeRef, GitRefError } from './gitref.js';
+import { baseInferenceMessage, baseMapsMessage, missingWorkingMapsMessage } from './cli-errors.js';
+function errorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function exitUsage(usage) {
+    throw new Error(usage);
+}
+function inferBaseRefOrExit(command) {
+    try {
+        return inferBaseRef();
+    }
+    catch (e) {
+        throw new Error(e instanceof GitRefError ? baseInferenceMessage(command, e.message) : errorMessage(e), {
+            cause: e,
+        });
+    }
+}
+function selectBaseRef(options) {
+    const { command, args, usage } = options;
+    if (options.baseRef) {
+        if (args.length > 1)
+            exitUsage(usage);
+        return { baseRef: options.baseRef, mapsDir: args[0] ?? options.mapsDir };
+    }
+    if (args.length === 1)
+        return { baseRef: args[0], mapsDir: options.mapsDir };
+    return { baseRef: inferBaseRefOrExit(command), mapsDir: options.mapsDir };
+}
+function materializeBaseRefOrExit(command, baseRef, mapsDir) {
+    try {
+        return materializeRef(baseRef, mapsDir);
+    }
+    catch (e) {
+        throw new Error(e instanceof GitRefError ? baseMapsMessage(command, e.message, baseRef, mapsDir) : errorMessage(e), {
+            cause: e,
+        });
+    }
+}
+export function resolveBaseRefCaptureDirs(options) {
+    const { command } = options;
+    const { baseRef, mapsDir } = selectBaseRef(options);
+    if (!fs.existsSync(mapsDir)) {
+        throw new Error(missingWorkingMapsMessage(command, mapsDir));
+    }
+    const tmpBase = materializeBaseRefOrExit(command, baseRef, mapsDir);
+    return { beforeDir: tmpBase, afterDir: mapsDir, baseRef, mapsDir, tmpBase };
+}
+export function cleanupBaseRefCaptureDirs(captureDirs) {
+    if (captureDirs)
+        fs.rmSync(captureDirs.tmpBase, { recursive: true, force: true });
+}

package/dist/cli-errors.d.ts

@@ -0,0 +1,10 @@
+export declare function isHelpArg(arg: string | undefined): boolean;
+export declare function showHelpAndExit(help: string): never;
+export declare function cliErrorMessage(error: unknown): string;
+export declare function unknownFlagMessage(command: string, flag: string): string;
+export declare function missingSpecMessage(spec: string): string;
+export declare function playwrightMissingMessage(message: string): string;
+export declare function missingWorkingMapsMessage(command: string, dir: string): string;
+export declare function missingManualCaptureMessage(command: string, dir: string): string;
+export declare function baseInferenceMessage(command: string, message: string): string;
+export declare function baseMapsMessage(command: string, message: string, baseRef: string, mapsDir: string): string;

package/dist/cli-errors.js

@@ -0,0 +1,50 @@
+export function isHelpArg(arg) {
+    return arg === '-h' || arg === '--help';
+}
+export function showHelpAndExit(help) {
+    process.stdout.write(help);
+    process.exit(0);
+}
+export function cliErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+export function unknownFlagMessage(command, flag) {
+    return `${command}: unknown flag: ${flag}\nNext: run ${command} --help to see supported options.`;
+}
+export function missingSpecMessage(spec) {
+    return [
+        `styleproof-map: no StyleProof spec at ${spec}`,
+        'Next: run styleproof-init to scaffold the spec, or pass --spec <path> if your capture spec lives elsewhere.',
+    ].join('\n');
+}
+export function playwrightMissingMessage(message) {
+    return [
+        `styleproof-map: could not run Playwright (${message})`,
+        'Next: install @playwright/test, then run npx playwright install chromium.',
+    ].join('\n');
+}
+export function missingWorkingMapsMessage(command, dir) {
+    return [
+        `${command}: no capture at ${dir}`,
+        `Next: run styleproof-map to create ${dir}, then commit the updated maps.`,
+        'If your maps live elsewhere, pass --maps-dir <dir>.',
+    ].join('\n');
+}
+export function missingManualCaptureMessage(command, dir) {
+    return [
+        `${command}: no capture at ${dir}`,
+        `Next: pass existing capture directories, or run styleproof-map first and use ${command} [baseRef].`,
+    ].join('\n');
+}
+export function baseInferenceMessage(command, message) {
+    return [
+        `${command}: ${message}`,
+        `Next: pass a base ref explicitly, e.g. ${command} main, or set git config branch.<name>.gh-merge-base main.`,
+    ].join('\n');
+}
+export function baseMapsMessage(command, message, baseRef, mapsDir) {
+    return [
+        `${command}: ${message}`,
+        `Next: make sure ${baseRef} contains committed captures at ${mapsDir}. On the base branch, run styleproof-map and commit ${mapsDir}.`,
+    ].join('\n');
+}

package/dist/diff.d.ts

@@ -61,6 +61,7 @@ export declare function diffStyleMapDirs(dirA: string, dirB: string): {
     surfaces: SurfaceDiff[];
     counts: DiffCounts;
     volatile: number;
+    compared: number;
 };
 export declare function diffContentMaps(a: StyleMap, b: StyleMap): ContentChange[];
 /** Per-surface content diff across two capture dirs (opt-in layer). Mirrors

package/dist/diff.js

@@ -13,6 +13,20 @@ function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     }
     return changed;
 }
+const LAYOUT_EQUIVALENT_MARGIN_PROPS = new Set([
+    'margin-left',
+    'margin-right',
+    'margin-inline-start',
+    'margin-inline-end',
+]);
+function sameRect(a, b) {
+    return !!a && !!b && a.every((v, i) => v === b[i]);
+}
+function dropLayoutEquivalentMarginProps(props, a, b) {
+    if (!sameRect(a?.rect, b?.rect))
+        return props;
+    return props.filter((p) => !LAYOUT_EQUIVALENT_MARGIN_PROPS.has(p.prop));
+}
 /** Union of both captures' live-region paths — skipped by every diff layer so a
  *  region volatile on either side never reads as a change. */
 function volatilePaths(a, b) {
@@ -80,7 +94,8 @@ export function diffStyleMaps(a, b) {
             // tag defaults for maps written before that fix.
             const pdefsA = pseudo ? (a.defaults[ea.tag + pseudo] ?? defsA) : defsA;
             const pdefsB = pseudo ? (b.defaults[eb.tag + pseudo] ?? defsB) : defsB;
-            const props = diffProps(propsA, propsB, pdefsA, pdefsB, '(unset)', '(unset)');
+            const rawProps = diffProps(propsA, propsB, pdefsA, pdefsB, '(unset)', '(unset)');
+            const props = pseudo ? rawProps : dropLayoutEquivalentMarginProps(rawProps, ea, eb);
             if (props.length)
                 findings.push({ kind: 'style', path: p, cls: ea.cls, pseudo, props });
         }
@@ -115,8 +130,9 @@ export function diffStyleMaps(a, b) {
             const db = sb[state] ?? {};
             for (const sub of new Set([...Object.keys(da), ...Object.keys(db)])) {
                 const props = diffProps(da[sub] ?? {}, db[sub] ?? {}, {}, {}, '(state does not change it)', '(state no longer changes it)');
-                if (props.length)
-                    findings.push({ kind: 'state', path: p, cls, state, sub, props });
+                const filtered = dropLayoutEquivalentMarginProps(props, a.elements[sub], b.elements[sub]);
+                if (filtered.length)
+                    findings.push({ kind: 'state', path: p, cls, state, sub, props: filtered });
             }
         }
     }
@@ -167,7 +183,7 @@ export function diffStyleMapDirs(dirA, dirB) {
         if (findings.length)
             surfaces.push({ surface, findings });
     }
-    return { surfaces, counts, volatile };
+    return { surfaces, counts, volatile, compared: names.length };
 }
 /**
  * Diff the OPT-IN content layer: elements whose own rendered text changed.

package/dist/gitref.d.ts

@@ -1,6 +1,8 @@
 /** A readable failure materialising a base from git — CLIs map this to exit 2. */
 export declare class GitRefError extends Error {
 }
+/** Infer the committed-map base ref for local and GitHub Actions CLI runs. */
+export declare function inferBaseRef(env?: NodeJS.ProcessEnv): string;
 /**
  * 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

package/dist/gitref.js

@@ -5,6 +5,50 @@ import path from 'node:path';
 /** A readable failure materialising a base from git — CLIs map this to exit 2. */
 export class GitRefError extends Error {
 }
+function git(args) {
+    return spawnSync('git', args, { encoding: 'utf8', maxBuffer: 1 << 28 });
+}
+function gitOutput(args) {
+    const r = git(args);
+    return r.status === 0 ? r.stdout.trim() : '';
+}
+function refExists(ref) {
+    return git(['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).status === 0;
+}
+function firstExistingRef(refs) {
+    return refs.find(refExists);
+}
+function baseRefCandidate(ref) {
+    const refs = ref.startsWith('origin/') || ref.startsWith('refs/') ? [ref] : [`origin/${ref}`, ref];
+    return firstExistingRef(refs) ?? refs[0];
+}
+function ghPrBaseRef() {
+    const r = spawnSync('gh', ['pr', 'view', '--json', 'baseRefName', '--jq', '.baseRefName'], {
+        encoding: 'utf8',
+        maxBuffer: 1 << 20,
+    });
+    return r.status === 0 ? r.stdout.trim() : '';
+}
+/** Infer the committed-map base ref for local and GitHub Actions CLI runs. */
+export function inferBaseRef(env = process.env) {
+    if (env.GITHUB_BASE_REF) {
+        return baseRefCandidate(env.GITHUB_BASE_REF);
+    }
+    const branch = gitOutput(['branch', '--show-current']);
+    if (branch) {
+        const configured = gitOutput(['config', `branch.${branch}.gh-merge-base`]);
+        if (configured) {
+            return baseRefCandidate(configured);
+        }
+    }
+    const prBase = ghPrBaseRef();
+    if (prBase)
+        return baseRefCandidate(prBase);
+    const fallback = firstExistingRef(['origin/main', 'origin/master', 'main', 'master']);
+    if (fallback)
+        return fallback;
+    throw new GitRefError('could not infer a base branch (tried GITHUB_BASE_REF, branch.<name>.gh-merge-base, gh pr view, origin/main, origin/master, main, master)');
+}
 /**
  * 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
@@ -15,7 +59,7 @@ export class GitRefError extends Error {
  * 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 });
+    const top = git(['rev-parse', '--show-toplevel']);
     if (top.status !== 0)
         throw new GitRefError('must run inside a git repository');
     const toplevel = top.stdout.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.0.2",
+  "version": "3.1.1",
   "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",
@@ -37,6 +37,7 @@
   },
   "bin": {
     "styleproof-init": "./bin/styleproof-init.mjs",
+    "styleproof-map": "./bin/styleproof-map.mjs",
     "styleproof-diff": "./bin/styleproof-diff.mjs",
     "styleproof-report": "./bin/styleproof-report.mjs"
   },