styleproof 3.1.2 → 3.1.4

package/CHANGELOG.md

@@ -7,6 +7,57 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+### Fixed
+
+- **Popup capture no longer collapses distinct triggers that reuse the same
+  overlay mount.** Each visible trigger slot that opens a persistent overlay now
+  gets its own `<surface>-popup-XX` map, so separate modals or menus rendered at
+  the same DOM path are captured instead of being deduped away.
+
+## [3.1.3] - 2026-06-29
+
+### Added
+
+- **Optional automatic popup capture.** `defineStyleMapCapture` and
+  `defineCrawlCapture` now accept `popups: true` or `{ max, triggers, overlays,
+timeoutMs }`. When enabled, StyleProof clicks visible safe triggers after each
+  base surface capture and saves persistent dialogs, popovers, menus, listboxes,
+  tooltips, and open data-state overlays as `<surface>-popup-XX` captures with
+  popup labels in reports.
+- **Local-first reusable map bundles are now the default v3 flow.** `styleproof-map`
+  writes `.styleproof/maps/current`, records a `styleproof-manifest.json` with the
+  commit SHA and capture compatibility key, and uploads the bundle to a dedicated
+  `styleproof-maps` branch when the working tree was clean and a git remote is
+  available. The upload happens from the explicit `styleproof-map` command, not
+  from a git hook, so generated maps no longer enter PR branch history.
+- **The report now surfaces tiny changes by default.** Every changed region shows
+  the clean before/after crop **and** a highlighted twin (magenta boxes marking each
+  change) without expanding anything, and names the changed element next to the image
+  (e.g. `changed: span.caret`). When the changed element's footprint is small
+  (≤ `zoomBelow`, default 64px) a magnified zoom crop is added so a sub-pixel change
+  (e.g. a 2px caret bump) is obvious at a glance instead of hiding in a collapsed
+  section. New `zoomBelow` report option tunes or disables it. ([#97](https://github.com/BenSheridanEdwards/StyleProof/issues/97))
+
+### Changed
+
+- **`styleproof-init` no longer generates or activates a pre-push hook.** It now
+  scaffolds `.gitignore` cache entries and a cache-first PR workflow that restores
+  base/head maps from `styleproof-maps`, runs the full StyleProof report action
+  when both bundles are present, and recaptures both sides in CI only on cache miss
+  or incompatible cache.
+- **`styleproof-diff` and `styleproof-report` now default to cached maps by commit
+  SHA.** No-arg and single base argument usage restores base/head bundles from the map
+  store, while explicit `<beforeDir> <afterDir>` usage remains for CI fallback
+  captures and custom comparisons. The old committed-map `--base-ref`/`--maps-dir`
+  mode is removed from v3 so generated maps no longer have any supported path into
+  PR branch history.
+
+### Fixed
+
+- `styleproof-diff` and report generation now ignore `styleproof-manifest.json`
+  when discovering surface map files, so manifest-backed bundles do not get parsed
+  as captures.
+
 ## [3.1.2] - 2026-06-28
 
 ### Added
@@ -958,7 +1009,8 @@ 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.1.2...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.3...HEAD
+[3.1.3]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.2...v3.1.3
 [3.1.2]: https://github.com/BenSheridanEdwards/StyleProof/compare/v3.1.1...v3.1.2
 [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

package/README.md

@@ -18,7 +18,7 @@ On every PR, StyleProof diffs the PR head's computed-style map against the base
 - 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).
+- The diff is always **head-vs-base**, so the report is _exactly what this PR changes_ — whether the maps are restored from the `styleproof-maps` cache or recaptured in CI on a cache miss. See [Quickstart](#quickstart).
 
 ## Don't let a new page ship uncaptured
 
@@ -118,10 +118,12 @@ defineStyleMapCapture({
 
 ## What a report looks like
 
-One change — the hero CTA recoloured cyan → amber — appears as a single section in the report: a side-by-side before/after cropped screenshot, a one-line summary, then the exact property change folded under a toggle.
+One change — the hero CTA recoloured cyan → amber — appears as a single section in the report: a side-by-side before/after cropped screenshot, the same crop again with magenta boxes marking exactly what changed, a one-line summary, then the exact property change folded under a toggle. A change too small to see at 1:1 (say a 2px icon tweak) also gets a magnified zoom crop, so a sub-pixel change can't slip past a reviewer.
 
 ![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](https://raw.githubusercontent.com/BenSheridanEdwards/StyleProof/main/docs/demo-composite.png)
 
+📄 **[See a full live report](docs/demo/report.md)** — rendered by the current code with real images (clean before/after, the highlighted twin, a magnified zoom for a sub-pixel change, and a `🆕 new surface`). It's regenerated and verified on every PR (`npm run demo:report`), so it always reflects exactly what StyleProof produces today.
+
 As it renders in the committed report (a plain-English bullet first — naming the theme token and showing the hex with a live colour swatch — then the exact table inside the toggle). The PR comment itself stays lean — a summary plus the approval box — and links here:
 
 ```text
@@ -158,7 +160,7 @@ Requires **Node ≥ 18** (ESM), **`@playwright/test` ≥ 1.40** (peer dep). Forc
 
 ## Quickstart
 
-After installing (above), one command sets up — and **activates** — the whole gate:
+After installing (above), one command sets up the whole gate:
 
 ```bash
 npx styleproof-init
@@ -168,8 +170,8 @@ 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, 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.
+- `.gitignore` entries for `.styleproof/`, `test-results/`, and `playwright-report/`;
+- a **cache-first CI workflow** that restores reusable maps from the `styleproof-maps` branch and generates the report without a browser when both maps are already built.
 
 Describe your surfaces — **omit `widths`** and StyleProof sweeps your real `@media` breakpoints automatically:
 
@@ -196,43 +198,54 @@ 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.
+`styleproof-map` captures the current commit into `.styleproof/maps/current`,
+writes a manifest, and uploads the bundle
+to the dedicated `styleproof-maps` branch when the working tree was clean and a
+git remote is available. Nothing under `.styleproof/` belongs in the PR branch.
+HAR recordings are removed before upload by default so private API responses do
+not land in the map store. Keep them locally only for an explicit record/replay
+workflow with `styleproof-map --keep-har` (or `STYLEPROOF_KEEP_HAR=1`).
+
+`styleproof-diff` restores the base and head maps from `styleproof-maps`
+automatically: in GitHub Actions it uses the PR base/head SHAs; 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 the base with `styleproof-diff main` or `styleproof-diff master`.
+
+**That's the whole loop.** Build the map outside CI when possible by running
+`styleproof-map` after committing. On the PR, CI first restores the base/head
+bundles and only generates the report — no build, no browser. If either bundle
+is missing or incompatible, CI recaptures both sides in the same pinned
+environment before reporting. Correctness wins over a stale cache, but the hot
+path is report-only.
+
+> **Same-environment note.** Computed styles depend on the browser build and installed fonts, so maps are only comparable when captured in the same runtime environment. StyleProof records a compatibility key to select the right cached bundle and refuses to compare maps captured under different browser/platform settings; CI then recaptures both sides instead of producing a bogus report.
 
 **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
+the same cached-map 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:
+**Want the side-by-side report + one-click approval**? `styleproof-init` scaffolds
+this for you. If you wire it by hand, restore or capture two dirs first, then use
+the Action on those dirs:
 
 ```yaml
 # .github/workflows/styleproof.yml
 - uses: actions/checkout@v4
-  with: { fetch-depth: 0 } # need the base ref's committed map
+- run: npx styleproof-map --restore --sha "${{ github.event.pull_request.base.sha }}" --dir base --base-dir __stylemaps__
+- run: npx styleproof-map --restore --sha "${{ github.event.pull_request.head.sha }}" --dir head --base-dir __stylemaps__
 - uses: BenSheridanEdwards/StyleProof@v3
   with:
-    base-ref: origin/${{ github.event.pull_request.base.ref }} # read the base map from git
-    fresh-dir: stylemaps/current # your committed maps
+    baseline-dir: __stylemaps__/base
+    fresh-dir: __stylemaps__/head
     require-approval: true # review-gate mode (omit / use fail-on-diff: true to certify)
 ```
 
 Then copy [`example/styleproof-approve.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/example/styleproof-approve.yml) to `.github/workflows/` **on your default branch** (GitHub only runs `issue_comment` workflows from there, so the approval checkbox is inert until it's merged).
 
-**Prefer to capture in CI instead of committing maps?** For a repo with many outside contributors on different machines, StyleProof can capture **both** base and head in CI and diff them there — no committed maps. See **[Forks and Dependabot](#forks-and-dependabot)** for that flow (it's also the fork-safe split). The committed-map flow above is the default because it's far faster and simpler for a single team.
+**Prefer to always capture in CI?** For a repo with many outside contributors on different machines, StyleProof can capture **both** base and head in CI and diff them there. See **[Forks and Dependabot](#forks-and-dependabot)** for that flow (it's also the fork-safe split). The default cache-first flow is faster for same-repo teams because local `styleproof-map` can build the head map before CI starts.
 
 **Want to skip work safely?** Skip the **whole** StyleProof workflow only for
 changes that cannot affect rendered output, such as docs-only edits, using your
@@ -254,7 +267,7 @@ on:
 
 ## Forks and Dependabot
 
-If you **capture in CI** rather than committing maps (the alternative noted at the end of the Quickstart — a better fit when many outside contributors push from different machines), the simplest setup runs the whole gate in one `pull_request` job that captures base + head and diffs them. That job needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
+If you **always capture in CI** rather than restoring maps from `styleproof-maps` (a better fit when many outside contributors push from different machines), the simplest setup runs the whole gate in one `pull_request` job that captures base + head and diffs them. That job needs a **write** token to push the report branch, post the comment, and set the `StyleProof` status. That's fine for same-repo PRs, but **fork and Dependabot PRs run with a read-only `GITHUB_TOKEN`** (GitHub's security default for untrusted PRs). So the job can't post the status — and a required `StyleProof` check then sits `pending` forever, blocking the PR even though a dependency or fork change usually touches no UI at all.
 
 Fix it by splitting capture from reporting, the way the approve workflow is already split out:
 
@@ -299,15 +312,16 @@ Anything still moving on its own after that is detected as a volatile region and
 | 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                                |
 
-| You set this — only because it's app-specific | Why it exists                                                                                                                                                                                                    |
-| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `STYLEPROOF_REPLAY_FROM` (record / replay)    | Base and head capture at different times against a live backend; replaying the base's recorded data pins the head to the same inputs, so the diff is **your code, not data drift**. The one piece of real setup. |
-| `replayUrl` / `STYLEPROOF_REPLAY_URL`         | Your data endpoints aren't under `**/api/**`.                                                                                                                                                                    |
-| `ignore: ['.selector']`                       | You want a region gone **explicitly** — auto-exclude already handles most live regions, but a known-noisy element reads clearer named.                                                                           |
-| `liveStates: [{ key, setup, go }]`            | A live feature has real states to certify. Capture each state on base and head (`surface-loading`, `surface-loaded`) instead of relying on a single moving page state.                                           |
-| `variants: [{ key, setup, go }]`              | Non-live deterministic variants, such as nav-open or modal-open states.                                                                                                                                          |
-| `clockTime`                                   | Your styling keys off a **specific** date, not just "now".                                                                                                                                                       |
-| `stabilize: { quietFor, timeout }`            | An unusually slow surface needs a longer quiet window before the map is read.                                                                                                                                    |
+| You set this — only because it's app-specific | Why it exists                                                                                                                                                                                                                                                           |
+| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `STYLEPROOF_REPLAY_FROM` (record / replay)    | Base and head capture at different times against a live backend; replaying the base's recorded data pins the head to the same inputs, so the diff is **your code, not data drift**. The one piece of real setup.                                                        |
+| `replayUrl` / `STYLEPROOF_REPLAY_URL`         | Your data endpoints aren't under `**/api/**`.                                                                                                                                                                                                                           |
+| `ignore: ['.selector']`                       | You want a region gone **explicitly** — auto-exclude already handles most live regions, but a known-noisy element reads clearer named.                                                                                                                                  |
+| `liveStates: [{ key, setup, go }]`            | A live feature has real states to certify. Capture each state on base and head (`surface-loading`, `surface-loaded`) instead of relying on a single moving page state.                                                                                                  |
+| `variants: [{ key, setup, go }]`              | Non-live deterministic variants, such as nav-open or modal-open states.                                                                                                                                                                                                 |
+| `popups: true`                                | Visible click-triggered overlays should be discovered automatically. Captures each matching trigger's persistent dialogs, popovers, menus, listboxes, and open data-state overlays as `surface-popup-XX`; keep hover-only or destructive states as explicit `variants`. |
+| `clockTime`                                   | Your styling keys off a **specific** date, not just "now".                                                                                                                                                                                                              |
+| `stabilize: { quietFor, timeout }`            | An unusually slow surface needs a longer quiet window before the map is read.                                                                                                                                                                                           |
 
 ## Optional: content layer (advisory)
 
@@ -350,14 +364,13 @@ When a PR **adds** an element, StyleProof now reports its **full resting compute
 
 **Action `BenSheridanEdwards/StyleProof@v3`** — key inputs:
 
-| Input              | Default      | Purpose                                                                                                                                |
-| ------------------ | ------------ | -------------------------------------------------------------------------------------------------------------------------------------- |
-| `fresh-dir`        | _required_   | PR-head (or committed) captures to compare.                                                                                            |
-| `base-ref`         | _none_       | Read the baseline from a git ref (e.g. the PR base branch) instead of `baseline-dir` — the committed-map flow. Needs `fetch-depth: 0`. |
-| `baseline-dir`     | _required\*_ | Base-branch captures dir. _\*Not required when `base-ref` is set._                                                                     |
-| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.                                                                      |
-| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.                                                               |
-| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection.                                                             |
+| Input              | Default      | Purpose                                                                             |
+| ------------------ | ------------ | ----------------------------------------------------------------------------------- |
+| `fresh-dir`        | _required_   | PR-head captures restored from `styleproof-maps` or freshly captured in CI.         |
+| `baseline-dir`     | _required_   | Base-branch captures dir restored from `styleproof-maps` or freshly captured in CI. |
+| `require-approval` | `false`      | Review-gate mode: set the `StyleProof` status instead of failing.                   |
+| `fail-on-diff`     | `true`       | Certify mode: fail on any diff. Ignored when `require-approval` is true.            |
+| `status-context`   | `StyleProof` | Commit-status name. Must match the approve workflow and branch protection.          |
 
 Outputs: `changed` (`"true"` when anything changed), `report-url`. Other inputs (`report-branch`, `github-token`) have sensible defaults — see [`action.yml`](https://github.com/BenSheridanEdwards/StyleProof/blob/main/action.yml).
 
@@ -379,41 +392,44 @@ 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?, liveStates?, variants? }`. `go(page)` drives to a settled state. Omit `widths` to auto-detect the app's `@media` breakpoints and sweep one width per band. |
-| `liveStates`  | _none_                      | Optional pinned live product states. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<state>` and is labeled as a live state in reports.                                                              |
-| `variants`    | _none_                      | Optional non-live deterministic states under a surface. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<variant>` so base/head compare matching states.                                              |
-| `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?, liveStates?, variants?, popups? }`. `go(page)` drives to a settled state. Omit `widths` to auto-detect the app's `@media` breakpoints and sweep one width per band. |
+| `liveStates`  | _none_                      | Optional pinned live product states. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<state>` and is labeled as a live state in reports.                                                                       |
+| `variants`    | _none_                      | Optional non-live deterministic states under a surface. Each `{ key, setup?, go?, widths?, height?, ignore? }` becomes `<surface>-<variant>` so base/head compare matching states.                                                       |
+| `popups`      | `false`                     | Optional automatic popup capture. Set `true` or `{ max, triggers, overlays, timeoutMs }` to click visible safe triggers and save each opened overlay state as `<surface>-popup-XX`.                                                      |
+| `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.
 
 **Capture env vars** (wire CI without editing the spec):
 
-| Env                      | Purpose                                                                                       |
-| ------------------------ | --------------------------------------------------------------------------------------------- |
-| `STYLEMAP_DIR`           | Output label; the capture is skipped entirely when unset.                                     |
-| `STYLEPROOF_BASEDIR`     | Output root dir (default `__stylemaps__`). The committed-map hook sets this to a tracked dir. |
-| `STYLEPROOF_SCREENSHOTS` | `0` to skip full-page screenshots — lean, commit-friendly `.json.gz`-only maps.               |
-| `STYLEPROOF_REPLAY_FROM` | Baseline dir to replay recorded data from — set this on the **head** capture.                 |
-| `STYLEPROOF_REPLAY_URL`  | Override the `**/api/**` data-boundary glob.                                                  |
-| `STYLEPROOF_SELFCHECK`   | `1` to capture each surface twice and fail if the two differ.                                 |
+| Env                       | Purpose                                                                                                               |
+| ------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `STYLEMAP_DIR`            | Output label; the capture is skipped entirely when unset.                                                             |
+| `STYLEPROOF_BASEDIR`      | Output root dir (runner default `__stylemaps__`; `styleproof-map` CLI default `.styleproof/maps`).                    |
+| `STYLEPROOF_SCREENSHOTS`  | `0` to skip full-page screenshots. The CLI keeps screenshots by default so reports can crop maps restored from cache. |
+| `STYLEPROOF_REPLAY_FROM`  | Baseline dir to replay recorded data from — set this on the **head** capture.                                         |
+| `STYLEPROOF_REPLAY_URL`   | Override the `**/api/**` data-boundary glob.                                                                          |
+| `STYLEPROOF_SELFCHECK`    | `1` to capture each surface twice and fail if the two differ.                                                         |
+| `STYLEPROOF_UPLOAD`       | `1` to require map-store upload; `0` to capture locally only.                                                         |
+| `STYLEPROOF_CACHE_BRANCH` | Map store branch (default `styleproof-maps`).                                                                         |
 
 **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. 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).
+- `styleproof-init` — scaffold the gate: the capture spec, a `playwright.config.ts` (production-build `webServer`, parallel capture), `.gitignore` cache entries, and the cache-first report workflow. One command. Generated commands follow the repo's lockfile (`bun.lock`/`bun.lockb`, `pnpm-lock.yaml`, `yarn.lock`, or npm by default) instead of assuming npm.
+- `styleproof-map` — capture the current commit's computed-style map through Playwright. By default it writes `.styleproof/maps/current`, keeps screenshots for reports, writes a manifest, and uploads to `styleproof-maps` outside CI when the working tree was clean and a git remote exists. Pass `--no-upload`, `--restore --sha <commit>`, `--spec`, `--dir`, `--base-dir`, or `--no-screenshots` for custom flows.
+- `styleproof-diff` — the certify gate. With no args, it restores cached maps for the current commit and inferred base (`GITHUB_BASE_REF`, `branch.<name>.gh-merge-base`, `gh pr view`, then main/master fallbacks); `styleproof-diff main` / `styleproof-diff master` pins the base; `styleproof-diff <beforeDir> <afterDir>` keeps the manual two-directory form for CI fallback captures. Exits `0` certified (identical), `1` on a diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
+- `styleproof-report` — render the diff to a Markdown report with before/after crops. With no args, it reports cached maps for the current commit against the inferred base; `styleproof-report main` / `styleproof-report master` pins the base; `styleproof-report <beforeDir> <afterDir> --out <dir>` keeps the manual two-directory form. Add `--include-content` for the opt-in, advisory content section (see above).
 
 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,7 @@
 /**
  * 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 [baseRef] [--max N] [--json <file>]
  *   styleproof-diff <beforeDir> <afterDir> [--max N] [--json <file>]
  *
  * Reports, per surface:
@@ -15,12 +14,9 @@
  *     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.
+ * No-arg and single base argument usage restore base/head maps from the StyleProof
+ * map store branch by commit SHA. To compare already-restored/captured maps,
+ * pass explicit before/after directories.
  *
  * Custom properties (--*) are ignored: they are inputs, not outcomes (see
  * README). Exit code 0 = identical, 1 = reviewable differences, 2 = usage/capture
@@ -29,7 +25,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
-import { cleanupBaseRefCaptureDirs, resolveBaseRefCaptureDirs } from '../dist/cli-base-ref.js';
+import {
+  DEFAULT_MAP_STORE_BRANCH,
+  DEFAULT_REMOTE,
+  assertCompatibleMapDirs,
+  cleanupCachedCaptureDirs,
+  resolveCachedCaptureDirs,
+} from '../dist/map-store.js';
 import {
   cliErrorMessage,
   isHelpArg,
@@ -39,19 +41,19 @@ import {
 } from '../dist/cli-errors.js';
 
 const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
-const DEFAULT_MAPS_DIR = 'stylemaps/current';
 
 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})
+  --spec <path>     StyleProof spec used to select compatible cached maps
+                   (default: e2e/styleproof.spec.ts)
+  --cache-branch <b>
+                   map store branch for default cached-map mode
+                   (default: ${DEFAULT_MAP_STORE_BRANCH})
+  --remote <name>   git remote for the map store (default: ${DEFAULT_REMOTE})
   --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
@@ -64,18 +66,21 @@ const argv = process.argv.slice(2);
 const args = [];
 let MAX = 40;
 let jsonOut = null;
-let baseRef = null;
-let mapsDir = DEFAULT_MAPS_DIR;
+let spec = 'e2e/styleproof.spec.ts';
+let cacheBranch = process.env.STYLEPROOF_CACHE_BRANCH ?? DEFAULT_MAP_STORE_BRANCH;
+let remote = process.env.STYLEPROOF_REMOTE ?? DEFAULT_REMOTE;
 for (let i = 0; i < argv.length; 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] === '--spec') spec = argv[++i];
+  else if (argv[i].startsWith('--spec=')) spec = argv[i].slice(7);
+  else if (argv[i] === '--cache-branch') cacheBranch = argv[++i];
+  else if (argv[i].startsWith('--cache-branch=')) cacheBranch = argv[i].slice(15);
+  else if (argv[i] === '--remote') remote = argv[++i];
+  else if (argv[i].startsWith('--remote=')) remote = argv[i].slice(9);
   else if (argv[i].startsWith('--')) {
     console.error(unknownFlagMessage(COMMAND, argv[i]));
     process.exit(2);
@@ -84,26 +89,34 @@ for (let i = 0; i < argv.length; i++) {
 
 let dirA;
 let dirB;
-let baseCapture = null;
-if (baseRef || args.length <= 1) {
+let cacheCapture = null;
+if (args.length <= 1) {
   if (!Number.isFinite(MAX)) {
-    console.error(`usage: ${COMMAND} [baseRef] [--maps-dir <dir>] [--max N] [--json <file>]`);
+    console.error(`usage: ${COMMAND} [baseRef] [--max N] [--json <file>]`);
     process.exit(2);
   }
   try {
-    baseCapture = resolveBaseRefCaptureDirs({
+    cacheCapture = resolveCachedCaptureDirs({
       command: COMMAND,
-      baseRef,
-      mapsDir,
       args,
-      usage: `usage: ${COMMAND} --base-ref <gitref> [mapsDir] [--max N] [--json <file>]`,
+      spec,
+      branch: cacheBranch,
+      remote,
+      baseUrl: process.env.BASE_URL,
+      usage: `usage: ${COMMAND} [baseRef] [--max N] [--json <file>]`,
     });
+    dirA = cacheCapture.beforeDir;
+    dirB = cacheCapture.afterDir;
   } catch (e) {
-    console.error(cliErrorMessage(e));
+    console.error(
+      [
+        `${COMMAND}: cached maps are not available for this comparison`,
+        cliErrorMessage(e),
+        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
+      ].join('\n'),
+    );
     process.exit(2);
   }
-  dirA = baseCapture.beforeDir;
-  dirB = baseCapture.afterDir;
 } else {
   if (args.length !== 2 || !Number.isFinite(MAX)) {
     console.error(`usage: ${COMMAND} <beforeDir> <afterDir> [--max N] [--json <file>]  (--help for all options)`);
@@ -120,12 +133,13 @@ if (baseRef || args.length <= 1) {
 
 let result;
 try {
+  assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
 } finally {
-  cleanupBaseRefCaptureDirs(baseCapture);
+  cleanupCachedCaptureDirs(cacheCapture);
 }
 const { surfaces, counts, compared } = result;