styleproof 3.17.0 → 3.19.0

package/CHANGELOG.md

@@ -7,6 +7,218 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- **Crawl coverage guard (`defineCrawlCapture` gains `expected` + `exclude`).** A
+  link-crawled SPA can now reconcile its _rendered nav_ against a declared route
+  registry, both directions: a rendered link with no `expected` entry fails as a new
+  route with no owner, and an `expected` route the nav stopped linking fails as a nav
+  regression. For such an app the nav is the route universe, so this is the spec
+  guard's list-vs-ledger discipline with the nav as the source of truth. Because the
+  link set isn't known until the page renders, the check runs _inside the capture
+  test_ (fires when `STYLEMAP_DIR` is set), not in the plain suite like the Next
+  guard. `exclude` (`key → reason`) opts out conditionally-rendered links (auth /
+  feature-flag) so they can't flake the guard; an `exclude` key in neither `expected`
+  nor the rendered nav fails as stale. Opt-in and backward-compatible: omit `expected`
+  and the crawl behaves exactly as before (captures what the nav links to, asserts no
+  completeness). New pure `crawlCoverageGaps` export for asserting reconciliation
+  yourself. README's "protected out of the box" scoped to what's wired per framework.
+
+### Fixed
+
+- **`--crawl` now honours the fail-loud contract on unreadable CSS.** Three deviations on
+  the crawl path let a page with a cross-origin stylesheet be certified without ever being
+  fully looked at:
+  - Breakpoint auto-detection swallowed the "unreadable stylesheet" throw and silently swept
+    only 1280px — every other band certified unchanged without being rendered. The crawl now
+    propagates the throw like every other entry point (`styleproof-capture` one-shot,
+    `styleproof-map`); the message advises pinning `--widths` for a cross-origin-CSS page.
+  - The coverage verifier read class vocabulary only from _readable_ sheets, so a design
+    served cross-origin could pass `--require-full-coverage` with an artificially complete
+    verdict. Unreadable sheets are now counted and surfaced as **named residue**: a plain
+    crawl prints `N stylesheet(s) unreadable — class coverage not provable against them`, and
+    `--require-full-coverage` treats them as residue → exit 4. (`CrawlCoverage` gains an
+    `unreadable: string[]` field; purely additive.)
+  - `--max-depth` had two different defaults (16 in `CRAWL_DEFAULTS`, 1000 in the CLI). The
+    CLI default is now **16 everywhere** — the cap exists to bound append-generator UIs (a
+    composer that appends a fresh-identity node per click, which dedup can't terminate); 1000
+    made it decorative. Raise with `--max-depth` for a genuinely deeper nest.
+- **The navigable-removal hard-gate now has data out of the box for new scaffolds — and
+  says so when it doesn't.** The Action defaults the inventory gate _on_ (3.14.0), but
+  inventory _capture_ defaults off, so on a spec that doesn't opt in, no map carries an
+  inventory, the diff's `inventory` verdict is `null`, and the gate counted zero removals
+  forever — armed, but with no ammunition. `styleproof-init` already scaffolds
+  `inventory: true` in the generated capture spec (since 3.15.0's zero-config default), so
+  **freshly scaffolded projects get the protection**; existing specs are untouched and stay
+  opt-in. To make the mismatch impossible to miss on pre-existing specs, the Action's gate
+  step now prints a `::notice::` — _"inventory gate is on but the captured maps carry no
+  inventory — set `inventory: true`"_ — instead of silently passing green, and
+  `styleproof-diff --json` emits an `inventoryNote` explaining the `null` verdict. Both are
+  notices, never failures: a spec that deliberately omits inventory capture keeps working.
+
+- **The compatibility guard now keys on the real browser build, not just the Playwright
+  npm version.** Each capture records `browser().version()` (the actual Chromium build) in
+  its manifest, and `styleproof-diff` / `styleproof-report` refuse to compare two maps whose
+  builds differ (exit 2, both builds named). The npm `@playwright/test` version was only a
+  proxy: the actual binary can change while it holds constant — a `playwright install`
+  re-download after a cache wipe, a different `PLAYWRIGHT_BROWSERS_PATH`, or a CI image
+  bump — and two maps captured under different Chromium builds used to pass the guard and
+  then diff for real, walling the PR with false diffs the canonicalizer can't absorb.
+  Backward compatible: the build is compared only when **both** manifests carry it, so
+  bundles cached before this field keep comparing against each other; a build change now
+  fires the scaffolded recapture fallback instead of a cross-build compare. Fonts are
+  documented as an environment responsibility (too noisy across machines to fingerprint
+  cheaply); see the same-environment note.
+
+- **A missing map is now refused, not mislabelled as "all new surfaces".** When one dir
+  held zero captures while the other held some, `styleproof-diff` used to mark every
+  surface `missing` and exit `3` ("only new surfaces") — the Action then rendered the
+  whole app as 🆕 new baselines a reviewer could approve wholesale. An empty **base** (a
+  restore that "succeeded" into an empty dir, a wrong `--base-dir`, a contributor without
+  the pre-push hook) meant approving a possibly fully-regressed head as the baseline; an
+  empty **head** (a head capture that produced nothing) meant approving a head that
+  rendered zero surfaces. Now: a bundle that claims to exist yet holds zero captures — a
+  `styleproof-manifest.json` present alongside no maps, on either side — and any empty
+  head exit `2` with their own named causes (`base map missing: restore it from the map
+store or recapture both sides — refusing to treat every surface as new` / `head map
+missing: the head capture produced zero surfaces — recapture the head side; refusing to
+treat every surface as removed/new`), distinct enough that the scaffolded workflow's
+  capture-needed fallback is the obvious remedy in CI logs. A truly **bare** base dir (no
+  manifest, no maps) still means "no baseline exists yet" — the first-adoption flow where
+  the base commit predates the capture spec — and keeps the exit-`3` new-surfaces review
+  path. To keep that discrimination sound, `styleproof-map` no longer writes a manifest
+  (or uploads) when a capture run produced zero surfaces. `styleproof-report` shares the
+  load path and is refused identically, so it can't render the misleading all-new page
+  either. Exit `3` keeps its meaning: no baseline for _these_ surfaces — new against an
+  existing baseline, or the very first one.
+
+### Security
+
+- **Surface keys are escaped before they reach the privileged PR comment.** Surface keys
+  originate from artifact filenames — attacker-controlled in the fork capture/report split
+  — and flow into the bot comment (sliced from `report.md`'s headline). Markdown/HTML
+  control characters (`` ` ``, `[`, `]`, `(`, `)`, `<`, `>`, `|`) are now stripped where a
+  key is interpolated into the report headline, certification, and summary lines, so a
+  crafted key can't inject a link, image, or table into the comment. (Crop filenames were
+  already restricted to `[a-z0-9-]`; this is the display-side equivalent.) No code
+  execution was possible; this closes a Markdown-injection surface.
+
 ## [3.17.0] - 2026-07-05
 
 ### Changed

package/README.md

@@ -53,9 +53,22 @@ It is useful for:
 
 The important boundary: StyleProof only certifies states it can reach. If a state
 matters, list it as a surface, variant, popup, live state, or component-catalog
-surface. `expected` turns that inventory into a guard, so an uncaptured new page,
-component, modal, dropdown, or toast fails as missing coverage instead of
-silently passing. A surface that exists only on the PR head is still reviewable:
+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.
+- **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
+  `expected` route the nav stopped linking fails. This runs inside the capture, so
+  it fires when you capture (unlike the Next guard, which runs in your plain suite).
+- **Other frameworks:** point `expected` at your own route registry.
+- **Modals, dropdowns, toasts:** guarded only for the state keys you enumerate in
+  `expected` (e.g. `dashboard-dialog-open`) — nothing discovers UI states for you.
+
+A surface that exists only on the PR head is still reviewable:
 in review-gate mode it holds the status red until approved, then becomes part of
 the baseline once merged.
 
@@ -195,6 +208,17 @@ defineCrawlCapture({
 
 Each discovered link becomes a surface keyed by its URL (`/?tab=overview` → `overview`; pass `key` for a different scheme). The app only has to render its nav as real `<a href>` links — a button-only nav (`<button onClick>`) exposes nothing to crawl. Replay, self-check and clock-freeze behave exactly as for explicit surfaces; one Playwright test runs the whole sweep (the link set isn't known until the page renders).
 
+Pass `expected` (a route registry) to turn the crawl into a coverage guard: the crawl reconciles the rendered link set against it, both directions — a rendered link with no `expected` entry fails as a new route with no owner, and an `expected` route the nav stopped linking fails as a nav regression. For a link-crawled SPA the rendered nav _is_ the route universe, so this is the same list-vs-ledger discipline as the spec guard with the nav as the source of truth. Because the link set isn't known until the page renders, this reconciliation runs _inside the capture test_ — so it fires when you capture (`STYLEMAP_DIR` set), not in every `npm test`, unlike the static Next guard. A link that renders conditionally (behind auth or a feature flag) would otherwise make the guard flaky either direction; list it in `exclude` (`key → reason`) to opt it out visibly — an `exclude` key in neither `expected` nor the rendered nav fails as stale, so the ledger can't rot. Omit `expected` and the crawl keeps its default: capture what the nav links to, assert no completeness.
+
+```ts
+defineCrawlCapture({
+  from: '/',
+  expected: ['index', 'pricing'], // the routes the nav must link to
+  exclude: { admin: 'feature-flagged, renders only for staff' },
+  dir: process.env.STYLEMAP_DIR,
+});
+```
+
 **Component inventory: fail when the catalog misses a component.** StyleProof
 cannot render arbitrary component files by itself across frameworks; props,
 providers, loaders, portals, and app shell context are app-owned. What it can do
@@ -424,7 +448,7 @@ styleproof-capture https://example.com --crawl --out design    # maps every reac
 styleproof-diff design .styleproof/maps/current                # diff the whole surface vs your build
 ```
 
-It's **exhaustive by default**: the crawl stops when there is nothing left to drive — every control tried once, every structurally new surface captured — not at a budget. Termination is guaranteed by dedup (controls dedup by selector, surfaces by a structural fingerprint), and the `--max-depth` / `--max-actions` / `--max-states` flags exist only as deliberate throttles. It's deterministic (document order; the same surface reached two ways is captured once) and self-settling — it waits for an async app (React/Vue/Babel that boots after `load`) to mount before reading, so a bare crawl of a client-rendered page still captures the mounted UI.
+It's **exhaustive by default**: the crawl stops when there is nothing left to drive — every control tried once, every structurally new surface captured — not at a budget. Dedup bounds the normal case — controls dedup by selector, surfaces by a structural fingerprint, so a finite UI runs out of new surfaces — and the `--max-depth` cap bounds the pathological one: an append-generator (a composer that appends a fresh-identity node per click) never repeats a fingerprint, so dedup can't stop it; the depth cap (16 by default) does. `--max-depth` / `--max-actions` / `--max-states` are otherwise deliberate throttles. It's deterministic (document order; the same surface reached two ways is captured once) and self-settling — it waits for an async app (React/Vue/Babel that boots after `load`) to mount before reading, so a bare crawl of a client-rendered page still captures the mounted UI.
 
 What makes exhaustive affordable is that the sweep works **in place**: standing in a state, each control is clicked right where the page is, and a cheap DOM fingerprint decides what happened — a no-op click costs nothing, and only a state-changing click pays a reset (fresh navigation + replay of the click-path), which is then **verified by fingerprint** so children are never attributed to the wrong parent. New surfaces are captured at every width the moment they're reached — a deep or animated click-path is never re-driven to capture, so it can't be the thing that drops a surface. Progress streams as it goes, one line per captured surface. And it's **parallel by default** — `--workers <n>` (default 4) sweeps states concurrently on isolated browser contexts with the exact same surface set as a serial crawl (dedup is shared; children only enter the queue when their parent's sweep completes); `--workers 1` if you want byte-stable dup-key attribution.
 
@@ -543,7 +567,7 @@ 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.
+> **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. Each capture also records the **real browser build** (`browser().version()`) in its manifest — the npm `@playwright/test` version is only a proxy, and the actual Chromium binary can change while it holds constant (a `playwright install` re-download, a different `PLAYWRIGHT_BROWSERS_PATH`, a CI image bump). When both sides carry it, a differing build refuses to compare (exit 2, both builds named) instead of walling the PR with false diffs. **Installed fonts are your responsibility:** they are noisy across machines (user-installed families, OS updates, and no cheap cross-platform enumeration), so StyleProof does not fingerprint them — capture both sides on the same fonts, which is what CI's pinned image already gives you.
 
 **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
@@ -709,7 +733,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
 
@@ -786,7 +851,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 diff, `2` on a usage/capture error, `3` when only new surfaces are present (no baseline to diff against; 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); `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

@@ -43,7 +43,9 @@ whole surface: --crawl
   --require-full-coverage
                     exit 4 unless every class the page's stylesheets define was
                     rendered in a captured surface — the machine check that
-                    NOTHING in the design was missed (coverage is always printed)
+                    NOTHING in the design was missed (coverage is always printed).
+                    An unreadable cross-origin sheet is residue too: its vocabulary
+                    can't be proven covered, so it also fails the check.
   --setup <file>    JSON steps (goto/fill/click/waitFor) run after EVERY fresh
                     navigation — how input-gated states (login, unlock) become
                     crawlable. \${ENV_VAR} in value/url is read from the
@@ -53,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)
@@ -122,15 +127,25 @@ async function runCrawl() {
         `(${report.actionsTried} actions tried, ${report.skipped} skipped${report.failed.length ? `, ${report.failed.length} capture-failed` : ''})`,
     );
     const cov = report.coverage;
+    const unreadable = cov.unreadable ?? [];
+    if (unreadable.length > 0) {
+      console.log(
+        `⚠ coverage: ${unreadable.length} stylesheet(s) unreadable — class coverage not provable against them ` +
+          `(cross-origin, no CORS; make them same-origin / CORS-readable, or pin --widths):\n    ${unreadable.join(' ')}`,
+      );
+    }
     if (cov.missing.length === 0) {
-      console.log(`✓ coverage: all ${cov.defined} stylesheet classes rendered in at least one captured surface`);
+      if (unreadable.length === 0)
+        console.log(`✓ coverage: all ${cov.defined} stylesheet classes rendered in at least one captured surface`);
     } else {
       console.log(
         `⚠ coverage: ${cov.rendered}/${cov.defined} stylesheet classes rendered — ${cov.missing.length} never seen ` +
           `(dead CSS, or a state the crawl could not reach):\n    ${cov.missing.join(' ')}`,
       );
-      if (opts.requireFullCoverage) process.exit(4);
     }
+    // Residue under --require-full-coverage → exit 4: a never-seen class OR an
+    // unreadable sheet (whose vocabulary can't be proven covered at all).
+    if (opts.requireFullCoverage && (cov.missing.length > 0 || unreadable.length > 0)) process.exit(4);
   } finally {
     await browser.close();
   }

package/bin/styleproof-diff.mjs

@@ -303,30 +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',
+              }),
         },
-      },
-      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

@@ -182,6 +182,13 @@ defineCrawlCapture({
   dir: process.env.STYLEMAP_DIR,
   // A single-route SPA whose views are ?tab= / client-routed? Keep only those:
   //   match: /\\?tab=/,
+  // Turn the crawl into a coverage guard: reconcile the rendered nav against a route
+  // registry, both directions — a new linked route with no \`expected\` entry fails, and
+  // an \`expected\` route the nav stopped linking fails. (Runs inside the capture, so it
+  // fires when you capture, not in every test run.) List conditionally-rendered links
+  // (auth / feature-flag) in \`exclude\` so they can't flake the guard either direction:
+  //   expected: ['index', 'pricing'],
+  //   exclude: { admin: 'feature-flagged, renders only for staff' },
   // Certify menus, dialogs, tabs, and form-error states on every surface as variants:
   //   variants: [{ key: 'menu-open', go: async (page) => { await page.getByRole('button', { name: /menu/i }).click(); } }],
 });

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,
@@ -29,6 +30,7 @@ import {
   MapStoreError,
   currentGitSha,
   expectedCompatibilityKey,
+  isMapFile,
   publishMapBundle,
   restoreMapBundle,
   workingTreeDirty,
@@ -284,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)
@@ -307,6 +316,19 @@ if (result.error) {
 const status = result.status ?? 1;
 if (status === 0) {
   if (!keepHar) removeHarFiles(targetDir);
+  // A run that produced ZERO surface maps must not stamp a manifest (or upload):
+  // a manifest over an empty bundle would read as "a bundle that claims to exist
+  // yet holds nothing" and the diff would refuse it as a missing base map. A bare
+  // dir instead means "no baseline yet" — on a first adoption, capturing the base
+  // commit that predates the spec legitimately yields zero surfaces, and the diff
+  // then takes the exit-3 new-surfaces review path.
+  const captured = fs.existsSync(targetDir) ? fs.readdirSync(targetDir).filter(isMapFile).length : 0;
+  if (captured === 0) {
+    console.error(
+      'styleproof-map: 0 surfaces captured — no manifest written; if this is the base side of a first adoption, the diff will treat it as no-baseline',
+    );
+    process.exit(status);
+  }
   try {
     let manifestSha = sha || undefined;
     if (!manifestSha) {

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;