styleproof 3.18.0 → 3.19.0

package/CHANGELOG.md

@@ -7,6 +7,120 @@ 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

package/README.md

@@ -733,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
 

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-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;

package/dist/affected-surfaces.js

@@ -42,6 +42,15 @@ const GLOBAL_CSS = /(^|\})\s*(:root|html|body|\*)[\s,{]|@tailwind\b|@layer\s+bas
 const CSSJS_GLOBAL = /\b(createGlobalStyle|injectGlobal|globalStyle|globalCss|createGlobalTheme)\b/;
 // `:global(...)` escape hatch or cross-module composition pulls in outside scope.
 const MODULE_ESCAPES = /:global\b|\bcompose[sd]?\b[^;]*\bfrom\b/;
+// Sass `@use`/`@forward`/`@import` pull another sheet's members into a CSS-module
+// file. dependency-cruiser parses JS imports, not Sass loads, so the import graph
+// can't bound them — fail closed on any occurrence. `@import` covers both the Sass
+// partial load (`@import "vars"`, whose members — possibly global rules — merge in
+// exactly like `@use`) and the plain-CSS pass-through form (`@import url(x.css)`,
+// `@import "sheet.css"`): a CSS `@import` composes an external sheet whose selectors
+// are NOT hashed into the module's per-file scope, so it escapes the module too.
+// Either way the change is unbounded → 'all'. Only widen; never narrows a verdict.
+const SASS_LOAD = /@(?:use|forward|import)\b/;
 const isConfig = (f) => /(?:^|\/)(?:tailwind|postcss|theme|tokens?|panda|uno)\.config\.[cm]?[jt]s$/.test(f) ||
     /(?:^|\/)theme\.[cm]?[jt]s$/.test(f);
 const isStyleSheet = (f) => /\.(css|scss|sass|less|styl)$/.test(f);
@@ -71,9 +80,10 @@ export function classifyStyleChange(file, readFile) {
         return CSSJS_GLOBAL.test(src) ? 'all' : 'scope'; // .tsx: global CSS-in-JS or colocated scope
     if (isStyleSheet(file)) {
         if (isCssModule(file)) {
-            // Hashed per-file scope — but `:global`, cross-module `composes … from`, and
-            // genuinely global selectors (`:root`, `html`, `@font-face`, …) all escape it.
-            return MODULE_ESCAPES.test(src) || GLOBAL_CSS.test(src) ? 'all' : 'scope';
+            // Hashed per-file scope — but `:global`, cross-module `composes … from`,
+            // genuinely global selectors (`:root`, `html`, `@font-face`, …), and any
+            // `@use`/`@forward`/`@import` load (Sass partial or plain-CSS sheet) escape it.
+            return MODULE_ESCAPES.test(src) || GLOBAL_CSS.test(src) || SASS_LOAD.test(src) ? 'all' : 'scope';
         }
         return 'all'; // vanilla stylesheet: global class namespace, import graph can't bound it
     }
@@ -83,6 +93,26 @@ export function classifyStyleChange(file, readFile) {
 const DYNAMIC_IMPORT = /import\(\s*([^)]+?)\s*\)/g;
 const dirOf = (p) => (p.includes('/') ? p.slice(0, p.lastIndexOf('/')) : '');
 const isSource = (p) => !p.includes('node_modules');
+/**
+ * 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 function canonicalPath(p) {
+    const out = [];
+    for (const seg of p.split('/')) {
+        if (seg === '' || seg === '.')
+            continue;
+        if (seg === '..')
+            out.pop();
+        else
+            out.push(seg);
+    }
+    return out.join('/');
+}
 function link(rev, to, from) {
     let s = rev.get(to);
     if (!s)
@@ -147,22 +177,19 @@ function normalizeDir(fromDir, prefix) {
     }
     return out.join('/');
 }
-/** True if any changed file is a style change that escapes its importers. */
-function anyGlobalStyleChange(changed, readFile) {
-    return changed.some((f) => (isStyleSheet(f) || isCode(f) || isConfig(f)) && classifyStyleChange(f, readFile) === 'all');
-}
 /**
  * Build the reverse-import adjacency (`imported → importers`) from the graph plus
  * recovered context-module edges. `'all'` when an unbounded dynamic import makes
- * the whole reachability untrustworthy.
+ * the whole reachability untrustworthy. Paths are already canonical; `read`
+ * resolves a canonical path back to the caller's spelling before reading.
  */
-function buildReverseGraph(input, files) {
+function buildReverseGraph(graph, files, read) {
     const rev = new Map();
-    for (const e of input.graph)
+    for (const e of graph)
         if (isSource(e.from) && isSource(e.to))
             link(rev, e.to, e.from);
     for (const f of files) {
-        const src = isCode(f) ? safeRead(input.readFile, f) : undefined;
+        const src = isCode(f) ? read(f) : undefined;
         if (src === undefined)
             continue;
         const extra = recoverContextEdges(f, src, files);
@@ -179,18 +206,45 @@ function buildReverseGraph(input, files) {
  * provably unaffected and may reuse their committed base map.
  */
 export function affectedSurfaces(input) {
-    const changed = [...input.changedFiles];
+    // Canonicalize every path (surfaces values, changedFiles, graph from/to, files)
+    // through one spelling up front, so a `./`-prefixed or `//`-collapsed path from
+    // one source can't silently miss a match against another source's spelling.
+    // `readFile` is keyed on the caller's ORIGINAL spellings, so wrap it to resolve
+    // a canonical path back to the original it came from before reading.
+    const changed = [...input.changedFiles].map((f) => canonicalPath(f));
     const files = [...input.files];
+    const canonFiles = files.map((f) => canonicalPath(f));
+    const originalByCanon = new Map();
+    files.forEach((orig, i) => originalByCanon.set(canonFiles[i], orig));
+    [...input.changedFiles].forEach((orig) => {
+        const c = canonicalPath(orig);
+        if (!originalByCanon.has(c))
+            originalByCanon.set(c, orig);
+    });
+    const surfaces = Object.fromEntries(Object.entries(input.surfaces).map(([k, f]) => [k, canonicalPath(f)]));
+    const graph = [...input.graph].map((e) => ({ ...e, from: canonicalPath(e.from), to: canonicalPath(e.to) }));
+    const read = (canon) => safeRead(input.readFile, originalByCanon.get(canon) ?? canon);
     // 1. A style change that escapes its importers forces a full re-capture.
-    if (anyGlobalStyleChange(changed, input.readFile))
+    if (changed.some((f) => isStyleOrCode(f) && classifyCanon(f, read) === 'all'))
         return 'all';
     // 2. Reverse reachability (+ recovered context edges; unbounded dynamic → all).
-    const rev = buildReverseGraph(input, files);
+    const rev = buildReverseGraph(graph, canonFiles, read);
     if (rev === 'all')
         return 'all';
-    // 3. Map each changed file to the surfaces that transitively import it. A file
-    //    the graph can't place (no importers, not a surface entry) → 'all'.
-    const entryToKey = new Map(Object.entries(input.surfaces).map(([k, f]) => [f, k]));
+    // 3. Map each changed file to the surfaces that transitively import it.
+    const entryToKey = new Map(Object.entries(surfaces).map(([k, f]) => [f, k]));
+    // A surface whose entry path appears in neither `files` nor any graph edge is
+    // unplaceable: reverse reachability can never route a change to it, so a genuine
+    // hit would be dropped silently. Same fail-closed rule as an unplaceable changed
+    // file → 'all'.
+    const placeable = new Set(canonFiles);
+    for (const e of graph) {
+        placeable.add(e.from);
+        placeable.add(e.to);
+    }
+    for (const f of Object.values(surfaces))
+        if (!placeable.has(f))
+            return 'all';
     const hit = new Set();
     for (const f of changed) {
         const reach = reverseReach(f, rev);
@@ -204,6 +258,18 @@ export function affectedSurfaces(input) {
     }
     return hit;
 }
+/** A changed file whose kind participates in style scope (stylesheet, code, or config). */
+const isStyleOrCode = (f) => isStyleSheet(f) || isCode(f) || isConfig(f);
+/** {@link classifyStyleChange} against a reader that returns `undefined` for a missing
+ *  file (rather than throwing), matching the reverse-graph reader shape. */
+function classifyCanon(file, read) {
+    return classifyStyleChange(file, (p) => {
+        const src = read(p);
+        if (src == null)
+            throw new Error('unreadable');
+        return src;
+    });
+}
 function reverseReach(file, rev) {
     const seen = new Set();
     const stack = [file];
@@ -218,3 +284,35 @@ function reverseReach(file, rev) {
     }
     return seen;
 }
+/**
+ * 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 function explainAffectedSurfaces(result, allSurfaces, reason) {
+    const all = [...allSurfaces].sort();
+    if (result === 'all') {
+        const why = reason ? ` — ${reason}` : '';
+        return [
+            `selective remap: OFF → re-capture all ${all.length} surface(s)${why}`,
+            ...all.map((k) => `  ↻ ${k} (re-capture)`),
+        ].join('\n');
+    }
+    const recapture = [...result].sort();
+    const hit = new Set(recapture);
+    const reused = all.filter((k) => !hit.has(k));
+    return [
+        `selective remap: ON → re-capture ${recapture.length}, reuse ${reused.length} from base`,
+        ...recapture.map((k) => `  ↻ ${k} (re-capture — a changed file reaches it)`),
+        ...reused.map((k) => `  ✓ ${k} (reuse base map — no changed file reaches it)`),
+    ].join('\n');
+}

package/dist/capture-url.d.ts

@@ -45,7 +45,7 @@ export type CaptureUrlOptions = {
      * discovered surface under a derived key. See {@link crawlAndCapture}.
      */
     crawl: boolean;
-    /** crawl: recursion depth into opened surfaces (default 3). */
+    /** crawl: recursion depth into opened surfaces (default 16). */
     maxDepth: number;
     /** crawl: fresh controls driven per state (default: unbounded — try them all). */
     maxActionsPerState: number;

package/dist/capture.js

@@ -727,33 +727,47 @@ export async function captureStyleMap(page, options = {}) {
     // nulls motion to 0s), then re-apply it before reading everything else.
     await freezeTag.evaluate((el) => el.remove());
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true, captureText: false });
-    await page.addStyleTag({ content: FREEZE_CSS });
-    const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
-    dropVolatile(base.elements, volatile);
-    const overlays = (await page.evaluate(detectOverlayCandidates, { ignore })).filter((overlay) => base.elements[overlay.path]);
-    warnUntraversed(base.shadowHosts, base.sameOriginFrames);
-    mergeMotion(base.elements, motion.elements);
-    let states = {};
-    let statesSkipped = false;
-    if (captureStates) {
-        const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
-        states = forced.states;
-        statesSkipped = forced.skipped;
+    // Re-apply the freeze for the base + forced-state reads (both must see motion
+    // nulled). This tag is KEEP-a-handle: unlike the pre-motion tag above (which was
+    // explicitly removed), an un-tracked tag would accumulate on any page reused without
+    // a reload — a second capture on the same page (SPA go() that doesn't navigate,
+    // multi-surface reuse, the self-check's re-run) would then read this run's frozen
+    // motion (`none`/`0s`) as its baseline and report phantom drift. Remove it in a
+    // `finally` so throw paths (a settle timeout, a forced-state error) also leave the
+    // page clean, not just the happy path.
+    const refreezeTag = await page.addStyleTag({ content: FREEZE_CSS });
+    try {
+        const base = await page.evaluate(capturePage, { ignore, motionOnly: false, captureText, captureComponent });
+        dropVolatile(base.elements, volatile);
+        const overlays = (await page.evaluate(detectOverlayCandidates, { ignore })).filter((overlay) => base.elements[overlay.path]);
+        warnUntraversed(base.shadowHosts, base.sameOriginFrames);
+        mergeMotion(base.elements, motion.elements);
+        let states = {};
+        let statesSkipped = false;
+        if (captureStates) {
+            const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
+            states = forced.states;
+            statesSkipped = forced.skipped;
+        }
+        const tokens = await page.evaluate(capturePageTokens);
+        const inventory = await harvestInventoryFor(page, options.inventory);
+        return {
+            ...(options.metadata ? { metadata: options.metadata } : {}),
+            defaults: base.defaults,
+            elements: base.elements,
+            states,
+            ...(statesSkipped ? { statesSkipped: true } : {}),
+            ...(volatile.length ? { volatile } : {}),
+            ...(liveCandidates.length ? { liveCandidates } : {}),
+            ...(overlays.length ? { overlays } : {}),
+            ...(Object.keys(tokens).length ? { tokens } : {}),
+            ...(inventory.length ? { inventory } : {}),
+        };
+    }
+    finally {
+        // Best-effort: the page may already be closing on a throw path.
+        await refreezeTag.evaluate((el) => el.remove()).catch(() => { });
     }
-    const tokens = await page.evaluate(capturePageTokens);
-    const inventory = await harvestInventoryFor(page, options.inventory);
-    return {
-        ...(options.metadata ? { metadata: options.metadata } : {}),
-        defaults: base.defaults,
-        elements: base.elements,
-        states,
-        ...(statesSkipped ? { statesSkipped: true } : {}),
-        ...(volatile.length ? { volatile } : {}),
-        ...(liveCandidates.length ? { liveCandidates } : {}),
-        ...(overlays.length ? { overlays } : {}),
-        ...(Object.keys(tokens).length ? { tokens } : {}),
-        ...(inventory.length ? { inventory } : {}),
-    };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */
 export function saveStyleMap(filePath, map) {

package/dist/coverage.d.ts

@@ -34,6 +34,41 @@ export type CoverageGaps = {
  * dir), and it's exported so a consumer can assert coverage however it likes.
  */
 export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;
+/**
+ * Translate captured surface keys into the DECLARED keys they satisfy for coverage.
+ *
+ * `expected` is stated in base surface keys (`home`), but a surface with `liveStates`
+ * is captured ONLY as its split expansions (`home-loading`, `home-loaded`) — the bare
+ * base key is dropped by design (the base live state is fuzzy). Comparing the expanded
+ * keys literally against `expected` would report the declared `home` as uncovered on a
+ * fully-captured app. Each expansion still carries its originating `surfaceKey`, so the
+ * declared base key is exactly recoverable: a capture satisfies its own key AND its
+ * `surfaceKey`. This is precise (it maps only real expansions back to their real base),
+ * not a suffix heuristic — an unrelated `home-banner` never satisfies an uncaptured `home`.
+ */
+export declare function coverageKeys(captured: Iterable<{
+    key: string;
+    metadata?: {
+        surfaceKey?: string;
+    };
+}>): string[];
+/**
+ * Rewrite a declared `expected` universe (base keys) into the keys that are actually
+ * captured to disk, so the GATE — which reads expanded map filenames (`home-loading`)
+ * and can't see each capture's `surfaceKey` metadata — can compare literally.
+ *
+ * A declared key `K` is replaced by its captured liveState expansions when `K` is NOT
+ * itself a captured key but expansions carrying `surfaceKey === K` exist. A directly
+ * captured `K` is kept; a genuinely uncaptured `K` is kept verbatim so the gate still
+ * flags it. This is the write-time half of {@link coverageKeys}: the ledger travels
+ * pre-translated, so `auditCoverage` needs no metadata at gate time.
+ */
+export declare function translateExpected(expected: readonly string[], captured: Iterable<{
+    key: string;
+    metadata?: {
+        surfaceKey?: string;
+    };
+}>): string[];
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export declare const COVERAGE_LEDGER = "styleproof-coverage.json";
 /**