styleproof 3.18.0 → 3.20.0

package/CHANGELOG.md

@@ -7,6 +7,197 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.20.0] - 2026-07-07
+
+### Fixed
+
+- **Crawl no longer double-captures `/` and `/index.html` as two surfaces.** On a
+  static multi-page site whose nav links the `.html` files, `/` and `/index.html`
+  (and `/dir/` vs `/dir/index.html`) are the same route but were captured twice as
+  byte-near-identical maps — doubling the capture work and duplicating every finding
+  in the diff. The crawl's dedup identity now normalizes a trailing `index.html` to
+  its directory path, so they collapse to one surface (first-seen href keeps its
+  original navigable form). Only the literal `index.html` filename normalizes — a
+  genuine `about.html` stays a distinct surface from `about`.
+- **`styleproof-init` now states exactly which files it wrote — and that it did NOT
+  touch `package.json` or your lockfile.** Adopters attributed the `styleproof`
+  dependency entry (added by their package manager's `install`) to init; init only
+  ever reads `package.json` and writes the spec, the dedicated Playwright config,
+  `.gitignore` lines, and the CI workflow. The summary now enumerates those files and
+  says plainly that the manifest and lockfile were left untouched.
+- **The no-comparison outcome of `styleproof-diff` / `styleproof-report` names both
+  ways forward.** When the no-args (inferred-base) path can restore no base map — no
+  map-store remote, no cached bundle — nothing is compared. That already exits `2`
+  (never a soft `0` a newcomer could read as "certified clean"); the message now says
+  "nothing was compared" and names the two working alternatives: run in CI (or a repo
+  with the `origin` remote) where the base is restorable, or the two-directory form
+  `styleproof-diff <beforeDir> <afterDir>`. A regression test pins the exit-2 contract
+  in a remote-less repo for both commands.
+- **README: the Next.js coverage guard is described accurately.** The docs conflated
+  two behaviors. With the auto-wired spec, `surfaces` and `expected` both derive from
+  the same `discoverNextRoutes()` call, so a new static route is captured and expected
+  together — **auto-covered, never a guard failure**. The guard **fails** only on
+  genuine divergence (a dynamic route, a hand-maintained registry, or a route dropped
+  from `surfaces` while still `expected`). Rewrote the overclaiming passages and the
+  generated-spec comments to state both behaviors.
+- **Layout-equivalent margin suppression no longer drops a real one-sided margin
+  change.** `dropLayoutEquivalentMarginProps` suppressed any horizontal
+  `margin-left/right/inline-start/inline-end` change whenever the element's rect
+  was unchanged — reasoning that a margin that doesn't move the box is cosmetic
+  drift. But a one-sided change (e.g. `margin-left: 0 → 40px` with `margin-right`
+  untouched) that leaves the rect identical only stayed put because _something
+  else compensated_; that is a genuine restyle, and it was silently dropped. The
+  suppression now fires only when there is no **demonstrable px imbalance**
+  between a side and its opposite — balanced drift (both sides move together) and
+  forced-state deltas are still suppressed exactly as before, but a one-sided
+  real change surfaces. A residual, consciously-deferred corner remains (a
+  perfectly _balanced_ change held in place by external compensation), documented
+  inline; closing it needs cross-element layout reasoning.
+- **`styleproof-init` no longer imports the whole library barrel (fixes a CI
+  flake).** The scaffolder only needs `discoverNextRoutes`, but it imported it
+  from `dist/index.js` — dragging capture, the crawler, the report renderer, and
+  six Playwright-importing modules into a tool that writes files and captures
+  nothing. Loading that oversized module graph concurrently (init's own suite
+  spawns the CLI many times, alongside the rest of `node --test`) is what made
+  init's tests flake in CI, red-flagging releases with no code cause. It now
+  imports from the `dist/routes.js` leaf (`fs` + `path` only): init's transitive
+  module graph drops from 21 dist modules to 1, with zero Playwright modules on
+  its load path. Behaviour is unchanged; a regression test pins the leaf import.
+- **Popup capture: verified reset + identity-bound triggers (no leaked-overlay
+  contamination, no wrong-trigger keying).** On a surface whose `go()` doesn't
+  navigate (SPA variants), the between-popups reset was Escape-only and assumed:
+  a toast or `[role="status"]` overlay Escape can't dismiss leaked into the next
+  popup's capture, and each reopen re-enumerated triggers positionally, so a
+  shifted trigger set (e.g. a click that adds a button) could key a popup under a
+  different trigger than the one originally enumerated. Triggers are now re-bound
+  by the DOM identity recorded at first enumeration, and the reset is verified
+  against the surface's pristine overlay set; a candidate that can't be opened
+  safely is skipped loudly (a `styleproof:` warning naming the popup and the
+  leaked overlay or missing trigger) instead of being captured contaminated,
+  mis-keyed, or — with self-check on — saved unproven. That identity is the
+  trigger's DOM path **and** its accessible label, not the path alone: for an
+  id-less trigger the path ends in `:nth-of-type`, which is still position within
+  a parent, so a same-tag same-parent sibling injected earlier in DOM order
+  between enumeration and reopen would slide the recorded path onto a different
+  trigger and key its popup under the wrong one — silently. Requiring the label
+  (the same aria-label/name/text/title accessible name the crawler reads) to match
+  too turns that mismatch into the same loud skip. Navigating surfaces are
+  unaffected.
+
+## [3.19.0] - 2026-07-06
+
+### Added
+
+- **Selective-remap wiring: `explainAffectedSurfaces` + the pre-push recipe.** The
+  sound core (`affectedSurfaces`) shipped in 3.17.0 returns a bare `Set | 'all'` that
+  names nothing; the new pure `explainAffectedSurfaces(result, allSurfaceKeys, reason?)`
+  formatter renders the verdict as reviewer-checkable lines — which surfaces re-capture
+  and which reuse their committed base map — so a pre-push hook or CI log can print the
+  skip list before anyone trusts it. `affectedSurfaces`'s return shape is unchanged
+  (backward-compatible; the helper takes the surface keys as a second argument rather
+  than extending the sentinel). README's selective-remap section gains the helper, its
+  output, and the full `git diff → dependency-cruiser → affectedSurfaces → capture subset`
+  pre-push recipe. Opt-in and advisory throughout — the default full-coverage gate is
+  untouched.
+
+### Fixed
+
+- **Report tables escape hostile CSS values (no Markdown breakout).** A property
+  value carrying a `|` used to split a report table row, and a backtick used to close
+  the code span and leak live Markdown (`content:"…"`, `url(…)`, `font` strings). The
+  render boundary now escapes values instead of stripping them — `|` → `\|`, and the
+  code fence widens past the value's longest backtick run — so hostile values render
+  as one intact, readable cell. `report.md` only; the privileged review comment was
+  never affected.
+- **The navigable-removal guard now sees SVG `<a>` nav links.** The in-page harvest
+  keyed anchors off `tagName === 'A'`, which is HTML-only (SVG reports lowercase `a`),
+  so an SVG nav link never entered the inventory and its removal never gated. The tag
+  check is now case-insensitive, the selector matches any-namespace `href`
+  (`a[*|href]`), and the target falls back to `xlink:href` — an `<svg><a>` link now
+  resolves like an HTML one.
+- **Single-value `transform-origin`/`perspective-origin` jitter is suppressed.** The
+  sub-pixel-origin equality check required at least two length components, so a
+  one-value origin (`50px`) leaked rounding jitter as a false diff. One to three
+  components are now all suppressed within `ORIGIN_EPSILON_PX`; a real, larger change
+  still reports.
+- **`styleproof-diff --json` exits 2 (not 1) when the file cannot be written.** A bad
+  `--json` path is a usage/setup error, but the write sat outside the guarded blocks
+  and let the failure fall through to exit 1 — which CI reads as a real diff. It now
+  reports to stderr and exits 2.
+- **Crawl flag docs corrected.** `--max-depth`'s default is documented as 16 (not
+  "unbounded" in `--help`, not "3" in the JSDoc); `--until-covered` is now listed in
+  `styleproof-capture --help`.
+- **Crawl no longer silently drops surfaces to key collisions, and mapping no longer
+  clicks title-only destructive controls.** Five soundness fixes across the crawl path:
+  - `selectCrawlLinks` deduped by raw URL, so `/about` and `/about/` — one route — were
+    two links that keyed identically and the second capture overwrote the first. Trailing
+    slashes are now normalized in the dedup identity (root `/` and the query string are
+    left intact), so a route is captured once.
+  - Genuinely distinct surfaces whose derived keys collide (e.g. `/a/b` and `/a-b` both
+    slugify to `a-b`) previously overwrote each other's map file. `selectCrawlLinks` now
+    disambiguates with a `-2`, `-3`, … suffix (mirroring the surface crawler), so every
+    surface survives.
+  - `defaultLinkKey` joined query-param values in iteration order, so `?tab=a&x=b` and
+    `?x=b&tab=a` — the same route — keyed as `a-b` vs `b-a` and flapped the coverage
+    guard into phantom regressions. Params are now sorted by name before joining.
+  - The surface crawler's clickable-candidate label omitted the `title` attribute, so an
+    icon-only `<button title="Delete">` labeled as `button` and slipped past the
+    destructive-action guard — mapping would click it. `title` is now part of the label
+    input in both crawlers.
+  - The variant crawler carried a weaker, divergent copy of the destructive-action word
+    list (missing `revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew`). Both
+    crawlers now share one `DANGER_SOURCE` constant, so mapping refuses the same set of
+    destructive controls everywhere.
+  - `defineStyleMapCapture` and `defineCrawlCapture` now assert every expanded capture
+    key is unique before running: the `surface.key-variant.key` join is ambiguous
+    (`a` + `b-c` and `a-b` + `c` both expand to `a-b-c`), which used to overwrite a map
+    file with no error. The key format is unchanged (it's public — filenames and report
+    identities); a collision now throws up front and names both origins so the author can
+    rename one.
+- **Sass `@use`/`@forward` in a CSS Module now fails closed to `'all'`.** A
+  `.module.scss`/`.module.sass` that loads a partial via `@use`/`@forward` can pull in
+  global rules the JS import graph can't see, so `classifyStyleChange` now treats any
+  such file as global (`'all'`) — a sound over-approximation, no heuristics. A plain CSS
+  Module with only class selectors stays `'scope'` as before.
+- **Legacy Sass/CSS `@import` in a CSS Module now fails closed too.** The fail-closed
+  load check missed the `@import` form, so a `.module.scss` loading a partial via
+  `@import "vars"` — whose members merge in exactly like `@use` — classified as `'scope'`
+  and could silently skip a re-capture. `classifyStyleChange` now treats any
+  `@use`/`@forward`/`@import` load as global (`'all'`), covering both the Sass partial
+  load and the plain-CSS pass-through (`@import url(x.css)`, whose selectors are not
+  hashed into the module's per-file scope, so it escapes the module). Only ever widens
+  toward `'all'`; a module with no load directive still stays `'scope'`.
+- **`affectedSurfaces` now canonicalizes paths across all inputs, closing a silent
+  unsound skip.** `surfaces` entries, `changedFiles`, graph edges, and `files` are now
+  normalized to one spelling (strip a leading `./`, collapse `//`, resolve `.`/`..` as
+  pure string math — no fs), so a `./pages/Home.tsx` surface entry no longer misses a
+  reachability hit spelled `pages/Home.tsx` and gets dropped from the affected set. And a
+  declared surface whose entry path appears in neither `files` nor any graph edge is now
+  unplaceable → `'all'`, the same fail-closed rule as an unplaceable changed file.
+- **Stale browser-build sidecar can no longer stamp a false fingerprint.**
+  `styleproof-map` now deletes any prior run's `styleproof-browser.json` before Playwright
+  runs, and `writeBrowserBuildSidecar(dir, undefined)` now removes an existing sidecar
+  rather than leaving it. Previously a reused capture dir plus a run that recorded no
+  browser version would fold the _previous_ run's build into this run's manifest, and
+  `assertCompatibleMapDirs` would trust that false `browserVersion` fingerprint.
+- **`captureStyleMap` no longer leaks its motion-freeze `<style>` onto a reused page.**
+  The freeze injected for the base/forced-state reads was re-applied without a handle and
+  never removed, so on a page recaptured **without a reload** (an SPA `go()` that doesn't
+  navigate, multi-surface reuse, the self-check's re-run) the next capture's motion pass
+  read the still-frozen transition/animation longhands (`none`/`0s`) as its baseline —
+  phantom drift that surfaced as a **false "non-deterministic capture"** self-check
+  failure. The re-applied tag is now tracked and removed in a `finally`, so throw paths
+  clean up too. (No API change.)
+- **`liveStates` + `expected` no longer reports a false coverage gap.** A surface with
+  `liveStates` is captured only as its split expansions (`home-loading`, `home-loaded`) —
+  the bare base key is dropped by design — but the coverage ledger recorded `expected`
+  in base keys and the gate compared captured keys literally, so a fully-captured app
+  failed the gate with `uncovered: ['home']` (live in 3.18.0). The ledger writer now
+  records `expected` already translated through the same liveState expansion, and the
+  suite-side guard maps each capture back to its originating `surfaceKey` — a precise
+  mapping via real metadata, so an unrelated `home-banner` never satisfies an uncaptured
+  `home`. Both the spec-driven and crawl capture paths are fixed consistently.
+
 ## [3.18.0] - 2026-07-06
 
 ### Added

package/README.md

@@ -57,8 +57,12 @@ surface. `expected` turns that inventory into a guard: a key it lists that is
 neither captured nor excluded fails as missing coverage instead of silently
 passing. What's guarded depends on how `expected` is fed —
 
-- **Next.js:** auto-guarded. `styleproof-init` wires `expected` to the routes it
-  discovers, so a new page fails the guard with nothing to keep in sync.
+- **Next.js:** auto-covered. `styleproof-init` derives both `surfaces` and
+  `expected` from the same `discoverNextRoutes()` call, so a new static route lands
+  in both at once — captured and expected together, with nothing to keep in sync.
+  The guard then fails only on genuine divergence between the two: a dynamic route
+  (pre-excluded, so its reason surfaces), a hand-maintained registry, or a route
+  dropped from `surfaces` while still in `expected`.
 - **Link-crawled SPAs:** pass `expected` to `defineCrawlCapture` and the crawl
   reconciles it against the _rendered nav_ (the route universe for such an app),
   both directions — a new linked route with no `expected` entry fails, and an
@@ -152,7 +156,7 @@ _and_ no head capture, so it never appears in any diff, and the status goes
 green having never looked at it. This is the one thing the captures can't catch
 on their own: a capture that was never taken.
 
-Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails the moment a route exists with no surface, so a new page can't ship uncaptured:
+Declare your app's route/view universe in `expected` and StyleProof emits a coverage-guard test in your **normal** suite (it runs even without `STYLEMAP_DIR` — it's a static check, no browser). It fails when `expected` and your captured surfaces diverge — a route you listed in `expected` with no surface and no `exclude` entry fails as missing coverage, so a registry entry can't quietly ship uncaptured:
 
 ```ts
 import { defineStyleMapCapture } from 'styleproof';
@@ -168,7 +172,7 @@ defineStyleMapCapture({
 
 A route that's neither a captured surface nor an `exclude` entry fails the guard; an `exclude` key that isn't in `expected` (a renamed/removed route) fails too, so the opt-out ledger can't quietly rot. Captured surfaces beyond `expected` are fine — one route can have several states (`landing`, `landing-nav-open`). Omit `expected` and behaviour is unchanged.
 
-**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and wires both the surfaces and `expected` to them — so it's protected out of the box, and a page you add later is covered automatically with nothing to keep in sync:
+**Next.js: wired for you.** Run `styleproof-init` in a Next.js project and the generated spec discovers your routes (App Router `app/` + Pages Router `pages/`) at run time and derives **both** the surfaces and `expected` from that same `discoverNextRoutes()` call. Because they share one source, a static route you add later is captured and expected in the same step — auto-covered, never a guard failure, with nothing to keep in sync. The guard exists for the cases where the two genuinely diverge: a dynamic `[param]` route (it can't be navigated without a value, so it's placed in `exclude` with a reason rather than captured), a registry you hand-maintain instead of the live call, or a route you drop from `surfaces` while it's still `expected`:
 
 ```ts
 import { defineStyleMapCapture, discoverNextRoutes } from 'styleproof';
@@ -292,6 +296,17 @@ semantic roots that were actually present in the computed-style map, so tests ca
 assert a capture reached `role="dialog"`, `aria-modal`, `role="menu"`,
 `role="listbox"`, or hot-toast text.
 
+Triggers are enumerated once per surface and every reopen re-binds to that same
+element by identity — its DOM path **and** its accessible label — never by
+position. Between popups the surface is reset (Escape + `go()`) and the reset is
+verified: if an overlay a previous popup left behind is still visible (Escape
+closes dialogs, not toasts or status regions), or an enumerated trigger
+disappeared or changed identity (e.g. a same-tag sibling shifted in earlier),
+that candidate is **skipped loudly** — a `styleproof:` warning names the popup and
+why — instead of capturing contaminated state or keying a popup under the wrong
+trigger. Dismiss the leaking overlay in the surface's `go()`, or capture it as an
+explicit variant.
+
 **Harvest one-step variants.** Routes are not the whole UI: drawers, tabs,
 dialogs, empty form errors, selects, and other one-step states need their own
 captures. `styleproof-variants` opens a running app, tries semantic controls
@@ -733,7 +748,48 @@ const result = affectedSurfaces({
 // → 'all'              (some change couldn't be bounded — capture everything)
 ```
 
-Two honest limits, both resolving to `'all'`: a computed `import(`../dir/${x}`)` is treated as a bundler **context module** (every file under that dir is a possible target, so precision there is directory-level, never a miss); and the CSS-in-JS global list (`createGlobalStyle`, `injectGlobal`, `globalStyle`, …) must match the libraries you use — an unrecognized global API is the one way a scoped verdict could be unsound, so treat an unsupported styling system as a reason to skip selective remap. Because a PR-time miss would be silent, always let `main` (or a scheduled run) capture **all** surfaces as the trust-but-verify net.
+Two honest limits, both resolving to `'all'`: a computed `import(`../dir/${x}`)` is treated as a bundler **context module** (every file under that dir is a possible target, so precision there is directory-level, never a miss); and a CSS-Module (`.module.scss`/`.module.sass`) that carries a Sass `@use`/`@forward` load resolves to `'all'`, because those pull in a partial the JS import graph can't bound. One honest **residual** stays `'scope'` by design: the CSS-in-JS global list (`createGlobalStyle`, `injectGlobal`, `globalStyle`, …) must match the libraries you use — an allowlist can't fail closed on an _unknown_ member, so an unrecognized global API in a `.tsx` is the one way a scoped verdict could be unsound. Treat an unsupported styling system as a reason to skip selective remap. Because a PR-time miss would be silent, always let `main` (or a scheduled run) capture **all** surfaces as the trust-but-verify net.
+
+### Show the skip list, then wire the pre-push hook
+
+Before you trust a skip, print it. `explainAffectedSurfaces(result, allSurfaceKeys)` renders the verdict as reviewer-checkable lines — which surfaces re-capture and which reuse their committed base map — and takes an optional reason string for the `'all'` case:
+
+```ts
+import { affectedSurfaces, explainAffectedSurfaces } from 'styleproof';
+
+const result = affectedSurfaces(/* … */);
+console.log(explainAffectedSurfaces(result, Object.keys(surfaces)));
+```
+
+A scoped change (only `dashboard`'s subtree touched) prints:
+
+```
+selective remap: ON → re-capture 1, reuse 2 from base
+  ↻ dashboard (re-capture — a changed file reaches it)
+  ✓ home (reuse base map — no changed file reaches it)
+  ✓ pricing (reuse base map — no changed file reaches it)
+```
+
+A global/token change fails closed to a full re-capture:
+
+```
+selective remap: OFF → re-capture all 3 surface(s) — src/tokens.css is a global (unscoped) stylesheet
+  ↻ dashboard (re-capture)
+  ↻ home (re-capture)
+  ↻ pricing (re-capture)
+```
+
+Wired into a pre-push hook, the whole recipe is: diff the changed files, produce the graph, ask `affectedSurfaces`, print the skip list, then capture only the subset and reuse the committed base maps for the rest.
+
+```sh
+#!/usr/bin/env sh
+# .husky/pre-push (opt-in; the default CI gate still captures every surface)
+CHANGED=$(git diff --name-only origin/main...HEAD)
+npx dependency-cruiser src --no-config --output-type json > dc.json
+node scripts/selective-remap.mjs "$CHANGED" dc.json   # affectedSurfaces + explain + capture subset
+```
+
+`scripts/selective-remap.mjs` is yours to own — it maps `dc.json` into `{ from, to }` edges (as above), calls `affectedSurfaces`, prints `explainAffectedSurfaces`, then captures only the returned keys and copies each reused surface's committed base map forward. `main` re-captures everything, so a PR-time miss is still caught at merge.
 
 ## Newly-added elements show their full style
 
@@ -810,7 +866,7 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 - `styleproof-init` — scaffold the gate: the capture spec, a dedicated `playwright.styleproof.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), respect pnpm/Corepack version pins, and detect Vite/Next production preview commands instead of assuming every repo has `start`.
 - `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 `--crawl-base-url` plus repeated `--crawl-route` to run `styleproof-variants` before capture, `--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 reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new); `3` when only new surfaces are present (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no manifest at all, meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). A clean run prints `0 changed surfaces across N captured surface(s)`, and `--json` includes `compared`.
+- `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 reviewable diff — computed-style/DOM/state differences, and equally an unacknowledged inventory removal, an incomplete coverage registry, or an unproven-determinism capture; `2` on a usage/capture error (including a **missing map** — a bundle that claims to exist yet holds zero captures, i.e. a `styleproof-manifest.json` present with no maps, on either side, or a head capture that produced nothing; refused loudly rather than mislabelled as all-new — **and** the no-args case where the cached base map can't be restored at all: no map-store remote, no cached bundle, nothing to compare. A "nothing was compared" outcome always exits `2`, never a soft `0` that would read as certified; the error names the two ways forward — run in CI where the base is restorable, or use the two-directory form); `3` when only new surfaces are present (no baseline for _those_ surfaces to diff against — new surfaces against an existing baseline, or a base dir with no manifest at all, meaning no baseline was ever captured: the first-adoption review path; approval policy decides whether to gate). 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).
 - `styleproof-variants` — crawl a running app for one-step state variants and write `styleproof.variants.generated.json`. Pass `--base-url`, repeat `--route`, and use `--strict` when unresolved skipped/live candidates should fail automation.
 

package/bin/styleproof-capture.mjs

@@ -55,7 +55,10 @@ whole surface: --crawl
                     fulfilled with 500 → error render)
   --workers <n>     concurrent sweep workers (default 4); same surface set as a
                     serial crawl — pass 1 for byte-stable key attribution
-  --max-depth <n>   throttle recursion depth (default: unbounded)
+  --until-covered   stop the crawl early the moment every stylesheet class has
+                    been rendered — a coverage-oriented sweep for design mockups
+  --max-depth <n>   throttle recursion depth (default: 16 — backstop for
+                    append-generator UIs)
   --max-actions <n> throttle controls tried per state (default: unbounded)
   --max-states <n>  throttle total surfaces (default: unbounded)
   --no-reset-storage  don't clear localStorage between steps (default: clear)

package/bin/styleproof-diff.mjs

@@ -303,39 +303,48 @@ const invRemovals = printInventoryAudit(inventoryAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
 const determinismFails = printDeterminismVerdict(determinismVerdict);
 
-if (jsonOut)
-  fs.writeFileSync(
-    jsonOut,
-    JSON.stringify(
-      {
-        counts,
-        surfaces,
-        compared,
-        coverage: coverageVerdict,
-        determinism: determinismVerdict,
-        // The inventory verdict, machine-readable — parallel to coverage/determinism and
-        // to the report's certification block. `null` when no capture carried inventory.
-        // `unacknowledged` is the gating set: a CI can hard-fail on `unacknowledged.length`.
-        inventory: inventoryAudit && {
-          removed: inventoryAudit.delta.removed.map((i) => i.key),
-          added: inventoryAudit.delta.added.map((i) => i.key),
-          unacknowledged: inventoryAudit.unexplained.map((i) => i.key),
-          staleAcknowledgements: inventoryAudit.staleAllowances,
+if (jsonOut) {
+  // A write failure (bad --json path, unwritable dir) is a usage/setup error, not a
+  // "reviewable differences" result — exit 2, never leak the exit-1 that CI reads as
+  // a real diff.
+  try {
+    fs.writeFileSync(
+      jsonOut,
+      JSON.stringify(
+        {
+          counts,
+          surfaces,
+          compared,
+          coverage: coverageVerdict,
+          determinism: determinismVerdict,
+          // The inventory verdict, machine-readable — parallel to coverage/determinism and
+          // to the report's certification block. `null` when no capture carried inventory.
+          // `unacknowledged` is the gating set: a CI can hard-fail on `unacknowledged.length`.
+          inventory: inventoryAudit && {
+            removed: inventoryAudit.delta.removed.map((i) => i.key),
+            added: inventoryAudit.delta.added.map((i) => i.key),
+            unacknowledged: inventoryAudit.unexplained.map((i) => i.key),
+            staleAcknowledgements: inventoryAudit.staleAllowances,
+          },
+          // Explain the `inventory: null` so a gate reading this JSON can tell "armed but no
+          // data" apart from "audited, nothing removed". Neither map carried inventory → set
+          // `inventory: true` in the capture spec (styleproof-init scaffolds it).
+          ...(inventoryAudit
+            ? {}
+            : {
+                inventoryNote:
+                  'no captured map carried an inventory — set `inventory: true` in the capture spec to arm the navigable-removal gate',
+              }),
         },
-        // Explain the `inventory: null` so a gate reading this JSON can tell "armed but no
-        // data" apart from "audited, nothing removed". Neither map carried inventory → set
-        // `inventory: true` in the capture spec (styleproof-init scaffolds it).
-        ...(inventoryAudit
-          ? {}
-          : {
-              inventoryNote:
-                'no captured map carried an inventory — set `inventory: true` in the capture spec to arm the navigable-removal gate',
-            }),
-      },
-      null,
-      2,
-    ),
-  );
+        null,
+        2,
+      ),
+    );
+  } catch (e) {
+    console.error(`${COMMAND}: could not write --json ${jsonOut}: ${e.message}`);
+    process.exit(2);
+  }
+}
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;

package/bin/styleproof-init.mjs

@@ -7,10 +7,13 @@
  * Writes:
  *   - <dir> (default e2e/styleproof.spec.ts): a starter capture spec with a
  *     minimal settle() helper (triggers scroll-reveal content; StyleProof itself
- *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives surfaces AND
- *     the `expected` coverage guard from the app's routes at run time, so a page
- *     added later can't ship without a surface; otherwise it writes one sample
- *     surface plus a commented guard block to wire to your own route registry.
+ *     handles fonts, animation freeze, and the settle). For a detected Next.js app it derives BOTH the
+ *     surfaces AND the `expected` coverage guard from the same `discoverNextRoutes()`
+ *     call, so a static route added later is captured and expected together —
+ *     auto-covered, never a guard failure; the guard fails only on genuine
+ *     divergence (a dynamic route, a hand-maintained registry, or a route dropped
+ *     from surfaces but still expected). Otherwise it writes one sample surface
+ *     plus a commented guard block to wire to your own route registry.
  *   - playwright.styleproof.config.ts: a dedicated production-build Playwright
  *     config for StyleProof captures, so an existing app Playwright config is
  *     never disturbed or accidentally reused.
@@ -23,7 +26,12 @@
  */
 import fs from 'node:fs';
 import path from 'node:path';
-import { discoverNextRoutes } from '../dist/index.js';
+// Import from the leaf module, not the barrel: styleproof-init only scaffolds
+// files and never captures. Pulling `../dist/index.js` here dragged the whole
+// library — capture, crawler, report, and six Playwright-importing modules —
+// into a tiny scaffolder's load path, and that oversized concurrent module
+// graph is what made init's tests flake in CI. routes.js needs only fs + path.
+import { discoverNextRoutes } from '../dist/routes.js';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 
 const HELP = `styleproof-init — scaffold a styleproof capture spec
@@ -39,9 +47,10 @@ options:
 
 What it writes:
   - the spec at --dir, with a minimal settle() helper (scroll-reveal only).
-    In a Next.js app it discovers your routes at run time and wires both the
-    surfaces and the \`expected\` coverage guard to them, so a new page can't ship
-    uncaptured. Otherwise it writes one sample surface + a commented guard block.
+    In a Next.js app it discovers your routes at run time and derives both the
+    surfaces and the \`expected\` coverage guard from that one call, so a new static
+    route is auto-covered (captured + expected together); the guard fails only when
+    the two diverge. Otherwise it writes one sample surface + a commented guard block.
   - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
 
@@ -114,9 +123,12 @@ const HEADER = `/**
  *   npx styleproof-diff  # compare cached base/head maps by commit SHA
  */`;
 
-// Next.js detected: derive both surfaces and the coverage guard from the app's
-// routes AT RUN TIME, so a page added later is in `expected` automatically and
-// fails the guard until it has a surface — no static list to drift.
+// Next.js detected: derive BOTH surfaces and the coverage guard from the app's
+// routes AT RUN TIME, from one `discoverNextRoutes()` call — so a static page added
+// later is a captured surface AND `expected` in the same step (auto-covered, never a
+// guard failure), with no static list to drift. The guard fires only when the two
+// diverge (a dynamic route, a hand-maintained registry, or a route dropped from
+// surfaces but still expected).
 const NEXT_SPEC = `import type { Page } from '@playwright/test';
 import { defineStyleMapCapture, discoverNextRoutes, type Surface } from 'styleproof';
 
@@ -124,12 +136,12 @@ ${HEADER}
 
 ${SETTLE}
 
-// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME — so a page
-// you add later is covered automatically, with no surface list to keep in sync
-// (that drift is exactly what lets a new page ship unverified). Edit freely; this
-// is your spec. Static routes each get a capture; dynamic [param] routes can't be
-// navigated without a value, so they're listed in \`exclude\` until you add a
-// surface with a concrete param.
+// Routes discovered from your Next.js app (app/ + pages/) at RUN TIME. Both SURFACES
+// and \`expected\` below come from this one list, so a static route you add later is
+// captured and expected together — covered automatically, with no surface list to
+// keep in sync. Edit freely; this is your spec. Static routes each get a capture;
+// dynamic [param] routes can't be navigated without a value, so they're listed in
+// \`exclude\` until you add a surface with a concrete param.
 const ROUTES = discoverNextRoutes();
 
 const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
@@ -146,9 +158,10 @@ const SURFACES: Surface[] = ROUTES.filter((r) => !r.dynamic).map((r) => ({
 
 defineStyleMapCapture({
   surfaces: SURFACES,
-  // Coverage guard: every known route must be a captured surface or excluded, or
-  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser).
-  // A new page with no surface can't slip through the gate unseen.
+  // Coverage guard: every \`expected\` route must be a captured surface or excluded, or
+  // the suite fails (it runs without STYLEMAP_DIR — a static check, no browser). Since
+  // both sides come from ROUTES, static routes never trip it; it fires when they
+  // diverge — a dynamic route (excluded below), or a route you drop from SURFACES.
   expected: ROUTES.map((r) => r.key),
   exclude: Object.fromEntries(
     ROUTES.filter((r) => r.dynamic).map((r) => [r.key, \`dynamic route (\${r.path}) — add a surface with a concrete param\`]),
@@ -480,9 +493,14 @@ const isNext = routes.length > 0;
 const SPEC = isNext ? NEXT_SPEC : GENERIC_SPEC;
 
 let wroteSomething = false;
+// Every path init created or modified this run, so the summary can name exactly what
+// it touched — and, by omission, what it did NOT (init never writes package.json or a
+// lockfile; that's the package manager's `install`, not this scaffolder).
+const touched = [];
 
 const spec = writeFileSafe(specPath, SPEC, { force });
 if (spec.wrote) {
+  touched.push(specPath);
   console.log(`${spec.exists ? 'overwrote' : 'created'} ${specPath}`);
   if (isNext) {
     const dynamic = routes.filter((r) => r.dynamic).length;
@@ -502,6 +520,7 @@ if (spec.wrote) {
 const configPath = 'playwright.styleproof.config.ts';
 const config = writeFileSafe(configPath, CONFIG, { force });
 if (config.wrote) {
+  touched.push(configPath);
   console.log(`${config.exists ? 'overwrote' : 'created'} ${configPath} (dedicated StyleProof capture config)`);
   wroteSomething = true;
 } else {
@@ -515,6 +534,7 @@ if (fs.existsSync('playwright.config.ts') || fs.existsSync('playwright.config.js
 
 const ignored = ['.styleproof/', 'test-results/', 'playwright-report/'].filter((line) => ensureGitignoreLine(line));
 if (ignored.length) {
+  touched.push('.gitignore');
   console.log(`updated .gitignore (${ignored.join(', ')})`);
   wroteSomething = true;
 }
@@ -522,12 +542,21 @@ if (ignored.length) {
 // Cache-first CI report — never overwrite an existing workflow.
 const ci = writeFileSafe(CI_PATH, CI_WORKFLOW);
 if (ci.wrote) {
+  touched.push(CI_PATH);
   console.log(`created ${CI_PATH} (cache-first StyleProof report)`);
   wroteSomething = true;
 } else {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+if (touched.length) {
+  // State exactly what init wrote, and — because adopters have blamed init for the
+  // `styleproof` entry their package manager's `install` added — say plainly that it
+  // did NOT touch package.json or the lockfile. Truth over assumption.
+  console.log(`\nstyleproof-init wrote only: ${touched.join(', ')}`);
+  console.log('It did NOT modify package.json or your lockfile (that was your package manager’s install).');
+}
+
 console.log('\nHow the gate works — it runs on your first PR with no extra steps:');
 console.log('  1. Commit and open a PR. CI captures the base and head surfaces in one pinned');
 console.log('     environment and posts the StyleProof report — no local step required.');

package/bin/styleproof-map.mjs

@@ -22,6 +22,7 @@ import {
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
 import {
+  BROWSER_BUILD_SIDECAR,
   DEFAULT_MAP_DIR,
   DEFAULT_MAP_LABEL,
   DEFAULT_MAP_STORE_BRANCH,
@@ -285,6 +286,13 @@ if (restore) {
   }
 }
 
+// Clear any prior run's browser-build sidecar before Playwright runs, so ONLY this
+// run can have written it. The default dir (.styleproof/maps/current) is reused across
+// runs; if this run records no browser version (the capture test not reached, or the
+// handle unavailable), a stale sidecar would otherwise be read into the manifest and
+// stamp a WRONG browser build that the compatibility guard then trusts as a fingerprint.
+fs.rmSync(path.join(targetDir, BROWSER_BUILD_SIDECAR), { force: true });
+
 const command = process.platform === 'win32' ? 'playwright.cmd' : 'playwright';
 const configArgs =
   fs.existsSync(STYLEPROOF_PLAYWRIGHT_CONFIG) && !hasPlaywrightConfigArg(playwrightArgs)

package/dist/affected-surfaces.d.ts

@@ -67,9 +67,33 @@ export type AffectedSurfaces = Set<string> | 'all';
  * unrecognized, is `'all'`.
  */
 export declare function classifyStyleChange(file: string, readFile: (p: string) => string): 'scope' | 'all';
+/**
+ * Canonicalize a repo-relative path so the same file spells the same regardless
+ * of source (a `surfaces` value, a `changedFiles` entry, or a graph edge). Two
+ * tools disagree on `./pages/Home.tsx` vs `pages/Home.tsx` vs `pages//Home.tsx`;
+ * without one spelling, a reverse-reachability hit can silently miss the surface
+ * whose entry key was spelled differently, dropping it from the affected set —
+ * an unsound skip. Byte-cheap and fs-free: strip a leading `./`, collapse `//`,
+ * and drop `.`/`..` segments as pure string math (no realpath, no resolution). */
+export declare function canonicalPath(p: string): string;
 /**
  * Compute the set of declared surfaces a change could have altered, or `'all'`.
  * See the module doc for the soundness contract. Any not in the returned set are
  * provably unaffected and may reuse their committed base map.
  */
 export declare function affectedSurfaces(input: AffectedSurfacesInput): AffectedSurfaces;
+/**
+ * Render an {@link affectedSurfaces} verdict as human-readable lines a pre-push
+ * hook (or CI log) can print, so a reviewer can sanity-check the skip list before
+ * trusting it. Pure formatter — no I/O, no graph work.
+ *
+ * @param result       the value {@link affectedSurfaces} returned.
+ * @param allSurfaces  every declared surface key (e.g. `Object.keys(surfaces)`),
+ *                     so the helper can name what is *reused from base* — the ones
+ *                     the verdict skips — not just what re-captures.
+ * @param reason       optional one-line explanation for an `'all'` verdict (e.g.
+ *                     the classifying file, from {@link classifyStyleChange}). The
+ *                     library doesn't attach a reason to the sentinel, so pass it
+ *                     if the caller knows why; omitted, the `'all'` line stands alone.
+ */
+export declare function explainAffectedSurfaces(result: AffectedSurfaces, allSurfaces: Iterable<string>, reason?: string): string;