styleproof 3.16.0 → 3.18.0

package/CHANGELOG.md

@@ -7,6 +7,132 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- **`report.md` is bounded so GitHub can always render it.** A large redesign used to
+  produce a `report.md` too big for GitHub's markdown viewer (it refuses to render past
+  ~512 KB) — the reviewer clicked through and got _"we can't show files this big"_, so the
+  report was useless exactly when the change was biggest. The generator now holds
+  `report.md` to a byte budget (`maxReportBytes`, default ~400 KB): it emits full property
+  tables greedily, then lists any remaining changed surfaces as one-liners (name · change
+  count · crop link) under an announced banner. The exhaustive per-row detail is always in
+  `report.json` and every crop in `crops/`, so nothing is dropped from the certification —
+  only the inline detail is capped. A report a reviewer can't open isn't a source of truth.
+
+### Added
+
+- **`affectedSurfaces` — selective-remap core (opt-in, advisory).** Given the files a
+  change touched, a declared surface→entry map, and a module graph (any tool's output
+  in `{ from, to }` shape — dependency-cruiser maps directly), returns exactly the
+  surfaces that could have rendered differently, or the sentinel `'all'`. Sound by
+  construction: it over-approximates and resolves every uncertainty to `'all'` — global
+  stylesheets/tokens, vanilla (unscoped) stylesheets, `createGlobalStyle`, design-system
+  configs, unbounded `import(x)`, and unplaceable files all force a full re-capture;
+  computed `import(`../dir/${x}`)` is recovered as a bundler context module (directory-
+  level, never a miss). Ships with `classifyStyleChange`. Purely additive, adds no
+  dependency, and never touches the default gate — the gate still captures every surface
+  and lets the map be the oracle. New export; existing specs unaffected.
+
 ## [3.16.0] - 2026-07-05
 
 ### Added

package/README.md

@@ -27,6 +27,7 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [Forks and Dependabot](#forks-and-dependabot)
 - [Optional: content layer](#optional-content-layer-advisory)
 - [Optional: React component layer](#optional-react-component-layer-advisory)
+- [Optional: selective remap](#optional-selective-remap-advisory)
 - [Newly-added elements show their full style](#newly-added-elements-show-their-full-style)
 - [Reference](#reference)
   - [Blocking without branch protection](#blocking-without-branch-protection)
@@ -52,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.
 
@@ -194,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
@@ -423,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.
 
@@ -542,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
@@ -679,6 +704,37 @@ Capture reads the React fiber in-page (`__reactFiber$*`/`__reactProps$*` on Reac
 
 Like the content layer it is **advisory**: never fed to the certification diff or the gate, so captures stay deterministic. Component names are mangled in minified production builds, so it's most useful against a dev / non-minified target; on a non-React page the fiber keys are absent and the field is simply omitted.
 
+## Optional: selective remap (advisory)
+
+On a large app, capturing every surface on every PR is the slow part. `affectedSurfaces` answers the question that lets you skip most of it: **given the files a change touched, which declared surfaces could have rendered differently?** Everything it doesn't return can reuse its committed base map.
+
+It is **opt-in and never part of the default gate** — the gate still captures every surface and lets the map be the oracle. This is a helper for wiring a faster pre-push/CI path yourself, and it is built to be wrong only in the safe direction: when it cannot _prove_ a surface is unaffected, it returns the sentinel `'all'` (re-capture everything). A global stylesheet or token, a vanilla (unscoped) stylesheet, a `createGlobalStyle`, a design-system config, an unbounded `import(x)`, or a file it can't place — all resolve to `'all'`.
+
+The module graph is an **input**, so StyleProof stays framework-agnostic and adds no dependency. Produce it with any tool whose output you can shape into `{ from, to }` edges — [dependency-cruiser](https://www.npmjs.com/package/dependency-cruiser)'s `modules[].dependencies[]` maps directly:
+
+```ts
+import { affectedSurfaces } from 'styleproof';
+import { readFileSync } from 'node:fs';
+
+// A dependency-cruiser run: `depcruise src --no-config --output-type json`
+const cruise = JSON.parse(readFileSync('dc.json', 'utf8'));
+const graph = cruise.modules.flatMap((m) =>
+  (m.dependencies ?? []).map((d) => ({ from: m.source, to: d.resolved, dynamic: d.dynamic })),
+);
+
+const result = affectedSurfaces({
+  changedFiles: ['src/components/PriceTable.tsx'], // e.g. `git diff --name-only origin/main`
+  surfaces: { home: 'src/pages/Home.tsx', pricing: 'src/pages/Pricing.tsx' },
+  graph,
+  files: cruise.modules.map((m) => m.source),
+  readFile: (p) => readFileSync(p, 'utf8'),
+});
+// → Set { 'pricing' }  (capture only these; reuse the base map for the rest)
+// → '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.
+
 ## Newly-added elements show their full style
 
 When a PR **adds** an element, StyleProof now reports its **full resting computed style** (background, padding, font, radius, …), value-only, in addition to any interaction-state deltas — previously an added element surfaced only its `:hover`/`:focus` changes. The new element already gates via its `added` finding; this only enriches what you see, in both the report and the `styleproof-diff` CLI.
@@ -754,7 +810,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
@@ -122,15 +124,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

@@ -322,6 +322,15 @@ if (jsonOut)
           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,

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

@@ -29,6 +29,7 @@ import {
   MapStoreError,
   currentGitSha,
   expectedCompatibilityKey,
+  isMapFile,
   publishMapBundle,
   restoreMapBundle,
   workingTreeDirty,
@@ -307,6 +308,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

@@ -0,0 +1,75 @@
+/**
+ * Selective remap: given the files a change touched, which declared surfaces
+ * could have rendered differently?
+ *
+ * This is the sound core behind "capture only what a PR can affect, reuse the
+ * committed base map for the rest" — an OPT-IN speed-up, never the default gate.
+ * The default gate captures every surface and lets the map be the oracle; this
+ * function only decides which surfaces a caller *may* skip, and it is built to
+ * be wrong only in the safe direction.
+ *
+ * The hard constraint: in the committed-map model a wrong "unaffected" is silent
+ * and fatal — a stale committed map matches the base, the diff is empty, and the
+ * regression ships green. So this function OVER-APPROXIMATES. When it cannot
+ * prove a surface is unaffected, it returns the sentinel `'all'`, meaning
+ * "re-capture everything." Every uncertainty resolves to `'all'`:
+ *
+ *   - a global style change (a reset, `:root`/theme token, `@tailwind`, a
+ *     `createGlobalStyle`, a design-system config) cascades everywhere → `'all'`;
+ *   - a vanilla (non-module) stylesheet has a global class namespace the import
+ *     graph cannot bound → `'all'`;
+ *   - a computed dynamic `import(x)` with no static prefix could load anything
+ *     → `'all'`; with a static prefix (`import(`../dir/${x}`)`) it is treated as
+ *     a bundler context module — every file under that dir is a possible target;
+ *   - a changed file the graph cannot place at all → `'all'`.
+ *
+ * The module graph is an INPUT, not a dependency: pass any tool's output in the
+ * {@link ModuleEdge} shape (dependency-cruiser's `modules[].dependencies[]` maps
+ * directly). StyleProof stays framework-agnostic and adds no dependency; the
+ * caller owns graph production, which is where framework-specific resolution
+ * lives.
+ *
+ * Pure and side-effect-free (I/O is injected via `readFile`) so it is fully
+ * unit-testable and deterministic.
+ */
+/** One resolved import edge: `from` imports `to`. Mirrors a dependency-cruiser
+ *  `modules[].dependencies[]` entry (use `module.source` as `from`, dependency
+ *  `resolved` as `to`). `dynamic` is informational; resolution already happened. */
+export type ModuleEdge = {
+    from: string;
+    to: string;
+    dynamic?: boolean;
+};
+export type AffectedSurfacesInput = {
+    /** Repo-relative paths the change touched (as they appear in the graph). */
+    changedFiles: Iterable<string>;
+    /** Declared surfaces: capture key → the surface's entry module path. */
+    surfaces: Record<string, string>;
+    /** Resolved import edges for the source tree (node_modules edges are ignored). */
+    graph: Iterable<ModuleEdge>;
+    /** Every candidate source file path — the universe a context-module glob can
+     *  resolve within. Typically the graph's node set. */
+    files: Iterable<string>;
+    /** Read a source file's text (for style classification and dynamic-import
+     *  recovery). Throwing/returning nothing is treated as "unknown" → `'all'`. */
+    readFile: (path: string) => string;
+};
+/** `'all'` means "re-capture everything" (some change could not be bounded). A
+ *  `Set` of surface keys means exactly those surfaces can be affected; any not
+ *  listed are provably unaffected and may reuse their committed base map. */
+export type AffectedSurfaces = Set<string> | 'all';
+/**
+ * Decide whether a single changed file's style scope is bounded to the files
+ * that import it (`'scope'` → follow the import graph) or escapes them
+ * (`'all'` → re-capture everything). Sound by construction: `'scope'` is
+ * returned only for provably-scoped changes (a CSS Module without escapes, or
+ * colocated CSS-in-JS with no global API); everything else, including anything
+ * unrecognized, is `'all'`.
+ */
+export declare function classifyStyleChange(file: string, readFile: (p: string) => string): 'scope' | 'all';
+/**
+ * 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;