styleproof 3.17.0 → 3.18.0

package/CHANGELOG.md

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

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
@@ -786,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/capture-url.js

@@ -26,7 +26,12 @@ const DEFAULTS = {
     screenshots: true,
     crawl: false,
     // Exhaustive by default — these are safety backstops, not budgets.
-    maxDepth: 1000,
+    // maxDepth mirrors CRAWL_DEFAULTS.maxDepth (crawl-surfaces.ts): 16 is
+    // exhaustive for real UI — no human-navigable surface is 16 clicks from load.
+    // The cap exists to bound append-generator UIs (a composer that appends a
+    // fresh-identity node per click, which dedup can't terminate); a higher value
+    // would make it decorative. Raise with --max-depth for a genuinely deeper nest.
+    maxDepth: 16,
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,

package/dist/crawl-surfaces.d.ts

@@ -44,11 +44,15 @@ export type CrawledSurface = {
 };
 /** Did the crawl SEE everything the design styles? `missing` lists classes the
  *  page's own stylesheets select on that never appeared in any captured surface —
- *  dead CSS, or a state the crawl could not reach. Empty missing = full coverage. */
+ *  dead CSS, or a state the crawl could not reach. `unreadable` names stylesheets
+ *  the browser could not parse (cross-origin, no CORS): their class vocabulary is
+ *  invisible, so coverage cannot be PROVEN against them. Full coverage = empty
+ *  `missing` AND empty `unreadable`. */
 export type CrawlCoverage = {
     defined: number;
     rendered: number;
     missing: string[];
+    unreadable: string[];
 };
 export type CrawlReport = {
     surfaces: CrawledSurface[];

package/dist/crawl-surfaces.js

@@ -249,12 +249,15 @@ function domShape() {
 /* c8 ignore stop */
 /** Runs in the browser: every class name the page's OWN stylesheets select on —
  *  the design's defined vocabulary, read from the parsed CSSOM (inline and
- *  same-origin sheets; unreadable cross-origin sheets are skipped). Coverage is
- *  checked against this, so "fully covered" means every class the design styles
- *  was seen rendered in at least one captured surface. */
+ *  same-origin sheets). Coverage is checked against this, so "fully covered" means
+ *  every class the design styles was seen rendered in at least one captured
+ *  surface. A cross-origin sheet the browser can't parse is NOT silently skipped:
+ *  its href is returned in `unreadable` so coverage names it as residue rather than
+ *  certifying completeness while blind to it. */
 /* c8 ignore start */
 function collectDefinedClasses() {
     const out = new Set();
+    const unreadable = [];
     const scan = (rules) => {
         if (!rules)
             return;
@@ -271,13 +274,13 @@ function collectDefinedClasses() {
     };
     for (const sheet of document.styleSheets) {
         try {
-            scan(sheet.cssRules);
+            scan(sheet.cssRules); // throws for a cross-origin sheet with no CORS
         }
         catch {
-            /* cross-origin sheet — not the design's own vocabulary */
+            unreadable.push(sheet.href ?? '<inline>');
         }
     }
-    return [...out];
+    return { classes: [...out], unreadable };
 }
 /* c8 ignore stop */
 /** Structural fingerprint of the page's CURRENT state. Dedup key for surfaces. */
@@ -842,16 +845,17 @@ async function discover(page, opts) {
     await gotoFresh(page, opts);
     // No widths given? Detect the page's real @media breakpoints (like the
     // one-shot path does) and sweep one width per band — automatically. Detection
-    // reads every stylesheet; if one is cross-origin/unreadable it falls back to
-    // the single default width rather than dying.
+    // reads every stylesheet and THROWS if one is cross-origin/unreadable: it never
+    // silently sweeps a single width, which would certify every other band
+    // unchanged without looking at it. Pin `--widths` for a cross-origin-CSS page.
     if (opts.widths.length === 0) {
-        const widths = await detectViewportWidths(page).catch(() => [1280]);
+        const widths = await detectViewportWidths(page);
         opts = { ...opts, widths };
         if ((widths[0] ?? 1280) !== 1280)
             await gotoFresh(page, opts); // re-pin discovery width BEFORE the base fingerprint
     }
     page.off('request', onRequest);
-    const defined = await page.evaluate(collectDefinedClasses).catch(() => []);
+    const { classes: defined, unreadable } = await page.evaluate(collectDefinedClasses);
     const fp = await fingerprint(page);
     const st = {
         seen: new Set([fp.sig]),
@@ -881,7 +885,7 @@ async function discover(page, opts) {
         skipped: counters.skipped,
         captured: st.captured,
         failed: st.failed,
-        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing },
+        coverage: { defined: defined.length, rendered: defined.length - missing.length, missing, unreadable },
     };
 }
 /**

package/dist/crawl.d.ts

@@ -60,3 +60,38 @@ export declare function defaultLinkKey(url: URL): string;
  * the capture order is the nav's order — stable across runs.
  */
 export declare function selectCrawlLinks(hrefs: Iterable<string | null | undefined>, opts: SelectLinksOptions): CrawlLink[];
+/**
+ * The reconciliation of a rendered nav (the crawl's discovered link keys) against a
+ * declared `expected` universe, both directions. Where the spec guard treats the
+ * hand-listed `surfaces` as what's captured, here the crawl's DISCOVERED links are —
+ * the nav is the route universe for a link-crawled SPA, so it is the source of truth.
+ *
+ * - `missing`: an `expected` key with no rendered link and no `exclude` entry — a
+ *   nav-regression (a route the app promised is no longer linked).
+ * - `unexpected`: a rendered link with no `expected` entry and no `exclude` entry — a
+ *   new route/view with no owner in the registry.
+ * - `staleExclusions`: an `exclude` key absent from BOTH `expected` and the rendered
+ *   set — a rotted opt-out.
+ *
+ * Unlike {@link CoverageGaps} (which permits captured-not-expected so a spec can
+ * tighten its registry over time), the crawl asserts BOTH directions strictly: the
+ * rendered link set is complete by construction, so an unowned link is a real gap.
+ * Pure and browser-free so it's unit-testable; {@link import('./runner.js')} wraps it
+ * in the crawl capture test, where the link set is finally known.
+ */
+export type CrawlCoverageGaps = {
+    /** Expected keys with no rendered link and no `exclude` — a nav regression. */
+    missing: string[];
+    /** Rendered link keys absent from `expected` and `exclude` — a route with no owner. */
+    unexpected: string[];
+    /** `exclude` keys in neither `expected` nor the rendered set — a rotted opt-out. */
+    staleExclusions: string[];
+};
+export declare function crawlCoverageGaps(discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CrawlCoverageGaps;
+/**
+ * Reconcile the crawled link set against `expected` (via {@link crawlCoverageGaps}) and
+ * render the failure message, or `null` when the nav reconciles. `from` names the crawl
+ * root in the message. Kept pure and out of the capture test so the wording is
+ * unit-testable and {@link defineCrawlCapture} just throws what this returns.
+ */
+export declare function crawlCoverageError(from: string, discoveredKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): string | null;

package/dist/crawl.js

@@ -97,3 +97,31 @@ export function selectCrawlLinks(hrefs, opts) {
     }
     return out;
 }
+export function crawlCoverageGaps(discoveredKeys, expected, exclude = {}) {
+    const discovered = new Set(discoveredKeys);
+    const expectedSet = new Set(expected);
+    const missing = [...expectedSet].filter((k) => !discovered.has(k) && !(k in exclude));
+    const unexpected = [...discovered].filter((k) => !expectedSet.has(k) && !(k in exclude));
+    const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k) && !discovered.has(k));
+    return { missing, unexpected, staleExclusions };
+}
+/**
+ * Reconcile the crawled link set against `expected` (via {@link crawlCoverageGaps}) and
+ * render the failure message, or `null` when the nav reconciles. `from` names the crawl
+ * root in the message. Kept pure and out of the capture test so the wording is
+ * unit-testable and {@link defineCrawlCapture} just throws what this returns.
+ */
+export function crawlCoverageError(from, discoveredKeys, expected, exclude = {}) {
+    const { missing, unexpected, staleExclusions } = crawlCoverageGaps(discoveredKeys, expected, exclude);
+    const problems = [];
+    if (missing.length)
+        problems.push(`nav regression — expected route(s) no longer linked from ${from}: ${missing.join(', ')}. ` +
+            `Restore the link, or move the key to \`exclude\` with a reason.`);
+    if (unexpected.length)
+        problems.push(`new route(s) with no owner — link(s) rendered at ${from} but absent from \`expected\`: ` +
+            `${unexpected.join(', ')}. Add each to \`expected\`, or to \`exclude\` with a reason.`);
+    if (staleExclusions.length)
+        problems.push(`stale \`exclude\` — key(s) in neither \`expected\` nor the rendered nav ` +
+            `(renamed or removed?): ${staleExclusions.join(', ')}.`);
+    return problems.length ? `styleproof crawl coverage gap:\n${problems.join('\n')}` : null;
+}

package/dist/diff.d.ts

@@ -9,6 +9,32 @@ export type PropChange = {
     before: string;
     after: string;
 };
+/**
+ * The before dir carries a bundle MANIFEST but ZERO captures while the after dir
+ * held some — a restore or capture that claims success yet delivered no maps (a
+ * corrupt bundle, a wrong --base-dir pointed at a manifest-only dir). Without
+ * this guard every after surface diffs as `missing: 'before'` (exit 3, "only new
+ * surfaces") and a whole app of regressions becomes one approvable "🆕 all new"
+ * report. The CLIs map this to exit 2 — a hard error, never the rubber-stampable
+ * exit 3. A truly BARE base dir (no manifest, no maps) is different: it means
+ * "never captured — no baseline exists yet", the first-adoption flow where the
+ * base commit predates the capture spec, and it keeps the exit-3 review path.
+ * (Both dirs empty stays the plain "no captures found" throw.)
+ */
+export declare class MissingBaseMapError extends Error {
+    constructor();
+}
+/**
+ * The mirror case: the AFTER (head) dir held ZERO captures while the before dir
+ * held some — a head capture or restore that produced nothing. Without this
+ * guard every base surface marks `missing: 'after'`, the CLI's new-surface count
+ * (which tallies BOTH directions) exits 3, and a head that rendered nothing
+ * becomes an approvable "all new surfaces" report — and, once approved, the
+ * next base. Same exit-2 path via the CLIs' existing catch.
+ */
+export declare class MissingHeadMapError extends Error {
+    constructor();
+}
 export type Finding = {
     kind: 'dom';
     path: string;

package/dist/diff.js

@@ -1,8 +1,42 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadStyleMap, isUnder } from './capture.js';
-import { isMapFile } from './map-store.js';
+import { isMapFile, MAP_MANIFEST } from './map-store.js';
 import { styleValuesEqual } from './canonicalize.js';
+/**
+ * The before dir carries a bundle MANIFEST but ZERO captures while the after dir
+ * held some — a restore or capture that claims success yet delivered no maps (a
+ * corrupt bundle, a wrong --base-dir pointed at a manifest-only dir). Without
+ * this guard every after surface diffs as `missing: 'before'` (exit 3, "only new
+ * surfaces") and a whole app of regressions becomes one approvable "🆕 all new"
+ * report. The CLIs map this to exit 2 — a hard error, never the rubber-stampable
+ * exit 3. A truly BARE base dir (no manifest, no maps) is different: it means
+ * "never captured — no baseline exists yet", the first-adoption flow where the
+ * base commit predates the capture spec, and it keeps the exit-3 review path.
+ * (Both dirs empty stays the plain "no captures found" throw.)
+ */
+export class MissingBaseMapError extends Error {
+    constructor() {
+        super('base map missing: restore it from the map store or recapture both sides — refusing to treat every surface as new. ' +
+            'Next: run styleproof-map --restore --sha <base>, or let CI recapture both sides.');
+        this.name = 'MissingBaseMapError';
+    }
+}
+/**
+ * The mirror case: the AFTER (head) dir held ZERO captures while the before dir
+ * held some — a head capture or restore that produced nothing. Without this
+ * guard every base surface marks `missing: 'after'`, the CLI's new-surface count
+ * (which tallies BOTH directions) exits 3, and a head that rendered nothing
+ * becomes an approvable "all new surfaces" report — and, once approved, the
+ * next base. Same exit-2 path via the CLIs' existing catch.
+ */
+export class MissingHeadMapError extends Error {
+    constructor() {
+        super('head map missing: the head capture produced zero surfaces — recapture the head side; refusing to treat every surface as removed/new. ' +
+            'Next: re-run styleproof-map on the head commit, or let CI recapture both sides.');
+        this.name = 'MissingHeadMapError';
+    }
+}
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -189,6 +223,25 @@ export function diffStyleMapDirs(dirA, dirB) {
     const names = [...new Set([...Object.keys(indexA), ...Object.keys(indexB)])].sort();
     if (names.length === 0)
         throw new Error(`no .json(.gz) captures found in ${dirA} or ${dirB}`);
+    // A whole side with zero captures is a missing MAP, not a set of genuinely
+    // new/removed surfaces — either way every surface would carry a `missing`
+    // marker and the run would read as "all new" (exit 3, approvable). Refuse
+    // each direction loudly with its own named cause — with one exception:
+    //
+    // Base side: only when the dir carries a bundle manifest. Manifest + zero maps
+    // means a restore/capture that claims success yet delivered nothing (a corrupt
+    // bundle) — breakage. A BARE dir (no manifest either) means no baseline was
+    // ever captured — the first-adoption flow, where the recapture fallback checks
+    // out a base commit that predates the capture spec. That legitimately yields
+    // zero surfaces and must keep the exit-3 "new surfaces, review before
+    // baselining" onboarding path, so it falls through.
+    if (Object.keys(indexA).length === 0 && fs.existsSync(path.join(dirA, MAP_MANIFEST)))
+        throw new MissingBaseMapError();
+    // Head side: UNCONDITIONAL (bare or manifest-present). The onboarding
+    // asymmetry only exists on the base side — the head is the commit under test,
+    // so a head that produced zero captures is always breakage, never a review flow.
+    if (Object.keys(indexB).length === 0)
+        throw new MissingHeadMapError();
     const surfaces = [];
     const counts = { dom: 0, style: 0, state: 0 };
     let volatile = 0;

package/dist/index.d.ts

@@ -15,8 +15,8 @@ export { discoverNextRoutes } from './routes.js';
 export type { DiscoveredRoute } from './routes.js';
 export { discoverComponentFiles, componentCatalogSurfaces } from './components.js';
 export type { DiscoveredComponent, DiscoverComponentFilesOptions, ComponentCatalogSurfaceOptions, } from './components.js';
-export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
-export type { CrawlLink, LinkMatch, SelectLinksOptions } from './crawl.js';
+export { selectCrawlLinks, defaultLinkKey, crawlCoverageGaps, crawlCoverageError } from './crawl.js';
+export type { CrawlLink, LinkMatch, SelectLinksOptions, CrawlCoverageGaps } from './crawl.js';
 export { harvestStyleVariants } from './variant-crawler.js';
 export type { HarvestAction, HarvestedLiveState, HarvestedRoute, HarvestedVariant, HarvestRoute, HarvestSkip, VariantHarvest, VariantHarvestOptions, } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';

package/dist/index.js

@@ -8,7 +8,7 @@ export { coverageGaps } from './coverage.js';
 export { detectViewportWidths, mediaTextWidthBoundaries, widthsFromBoundaries } from './breakpoints.js';
 export { discoverNextRoutes } from './routes.js';
 export { discoverComponentFiles, componentCatalogSurfaces } from './components.js';
-export { selectCrawlLinks, defaultLinkKey } from './crawl.js';
+export { selectCrawlLinks, defaultLinkKey, crawlCoverageGaps, crawlCoverageError } from './crawl.js';
 export { harvestStyleVariants } from './variant-crawler.js';
 export { diffStyleMaps, diffStyleMapDirs, diffContentMaps, diffContentDirs, findingLabel } from './diff.js';
 export { generateStyleMapReport, summarizeProps, prettyLabel } from './report.js';

package/dist/map-store.d.ts

@@ -3,6 +3,10 @@ export declare const DEFAULT_MAP_LABEL = "current";
 export declare const DEFAULT_MAP_STORE_BRANCH = "styleproof-maps";
 export declare const DEFAULT_REMOTE = "origin";
 export declare const MAP_MANIFEST = "styleproof-manifest.json";
+/** Sidecar written during a capture run (where a browser handle is in scope) recording
+ *  the real browser build (`browser().version()`). `writeMapManifest` runs after Playwright
+ *  has exited — no browser — so it reads the build back from here. Not a surface map. */
+export declare const BROWSER_BUILD_SIDECAR = "styleproof-browser.json";
 /** Bundle files that sit alongside the maps but are NOT surfaces (manifest, coverage
  *  ledger, and any future sidecar). Every place that enumerates surface maps must skip
  *  these, or a sidecar reads as a phantom "new surface". */
@@ -21,6 +25,10 @@ export interface MapManifest {
     lockfile?: string;
     lockfileHash?: string;
     playwrightVersion?: string;
+    /** Real browser build (`browser().version()`), recorded at capture time. The npm
+     *  `@playwright/test` version can hold constant while this changes (re-download, a
+     *  different browser store, a CI image bump), so this is what actually gates a compare. */
+    browserVersion?: string;
     platform: string;
     arch: string;
     nodeMajor: string;
@@ -39,6 +47,9 @@ export interface CachedCaptureDirs {
     compatibilityKey: string;
     tmpRoot: string;
 }
+/** Record the real browser build into the capture dir. Called from a capture run, where a
+ *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+export declare function writeBrowserBuildSidecar(dir: string, browserVersion: string | undefined): void;
 export declare function expectedCompatibilityKey(options?: {
     cwd?: string;
     spec?: string;

package/dist/map-store.js

@@ -11,11 +11,19 @@ export const DEFAULT_MAP_LABEL = 'current';
 export const DEFAULT_MAP_STORE_BRANCH = 'styleproof-maps';
 export const DEFAULT_REMOTE = 'origin';
 export const MAP_MANIFEST = 'styleproof-manifest.json';
+/** Sidecar written during a capture run (where a browser handle is in scope) recording
+ *  the real browser build (`browser().version()`). `writeMapManifest` runs after Playwright
+ *  has exited — no browser — so it reads the build back from here. Not a surface map. */
+export const BROWSER_BUILD_SIDECAR = 'styleproof-browser.json';
 const GENERATED_DIRTY_ALLOWLIST = new Set(['next-env.d.ts']);
 /** Bundle files that sit alongside the maps but are NOT surfaces (manifest, coverage
  *  ledger, and any future sidecar). Every place that enumerates surface maps must skip
  *  these, or a sidecar reads as a phantom "new surface". */
-export const RESERVED_BUNDLE_FILES = new Set([MAP_MANIFEST, COVERAGE_LEDGER]);
+export const RESERVED_BUNDLE_FILES = new Set([
+    MAP_MANIFEST,
+    COVERAGE_LEDGER,
+    BROWSER_BUILD_SIDECAR,
+]);
 /** True for a captured surface map (`<key>@<width>.json[.gz]`), false for metadata. */
 export function isMapFile(name) {
     return !RESERVED_BUNDLE_FILES.has(name) && /\.json(\.gz)?$/.test(name);
@@ -71,6 +79,23 @@ function detectLockfile(cwd) {
     }
     return {};
 }
+/** Record the real browser build into the capture dir. Called from a capture run, where a
+ *  Playwright browser handle is in scope. Best-effort: a missing version is simply not written. */
+export function writeBrowserBuildSidecar(dir, browserVersion) {
+    if (!browserVersion)
+        return;
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(path.join(dir, BROWSER_BUILD_SIDECAR), JSON.stringify({ browserVersion }, null, 2));
+}
+function readBrowserBuildSidecar(dir) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(dir, BROWSER_BUILD_SIDECAR), 'utf8'));
+        return parsed.browserVersion;
+    }
+    catch {
+        return undefined;
+    }
+}
 function hasHar(dir) {
     if (!fs.existsSync(dir))
         return false;
@@ -137,6 +162,7 @@ export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
 export function writeMapManifest(options) {
     const cwd = options.cwd ?? process.cwd();
     const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    const browserVersion = readBrowserBuildSidecar(options.dir);
     const manifest = {
         version: 1,
         packageVersion: input.packageVersion,
@@ -147,6 +173,7 @@ export function writeMapManifest(options) {
         ...(input.lockfile ? { lockfile: input.lockfile } : {}),
         ...(input.lockfileHash ? { lockfileHash: input.lockfileHash } : {}),
         ...(input.playwrightVersion ? { playwrightVersion: input.playwrightVersion } : {}),
+        ...(browserVersion ? { browserVersion } : {}),
         platform: input.platform,
         arch: input.arch,
         nodeMajor: input.nodeMajor,
@@ -186,12 +213,20 @@ export function assertCompatibleMapDirs(beforeDir, afterDir) {
         playwrightVersion: after.playwrightVersion ?? '',
         baseUrl: after.baseUrl ?? '',
     };
+    // Browser build is the actual renderer, but it's optional: only compare when BOTH sides
+    // carry it, so bundles cached before this field existed stay comparable to each other.
+    // A field on one side only can't be a proven mismatch.
+    if (before.browserVersion && after.browserVersion) {
+        beforeRuntime.browserVersion = before.browserVersion;
+        afterRuntime.browserVersion = after.browserVersion;
+    }
     if (JSON.stringify(beforeRuntime) === JSON.stringify(afterRuntime))
         return;
+    const build = (m) => (m.browserVersion ? `, browser ${m.browserVersion}` : '');
     throw new MapStoreError([
         'maps were captured in different runtime environments',
-        `before ${before.sha.slice(0, 12)}: ${before.compatibilityKey} (${before.platform}/${before.arch}, Playwright ${before.playwrightVersion ?? 'unknown'})`,
-        `after  ${after.sha.slice(0, 12)}: ${after.compatibilityKey} (${after.platform}/${after.arch}, Playwright ${after.playwrightVersion ?? 'unknown'})`,
+        `before ${before.sha.slice(0, 12)}: ${before.compatibilityKey} (${before.platform}/${before.arch}, Playwright ${before.playwrightVersion ?? 'unknown'}${build(before)})`,
+        `after  ${after.sha.slice(0, 12)}: ${after.compatibilityKey} (${after.platform}/${after.arch}, Playwright ${after.playwrightVersion ?? 'unknown'}${build(after)})`,
         'Next: rebuild one side with styleproof-map in the same environment, or let CI recapture both maps.',
     ].join('\n'));
 }

package/dist/report.js

@@ -385,6 +385,14 @@ export function prettyLabel(p, cls) {
     const first = cls.split(/\s+/)[0] ?? '';
     return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
 }
+// Surface keys originate from artifact filenames — attacker-controlled in the
+// fork capture/report split, and they flow into the PRIVILEGED PR-comment summary
+// (the Action slices report.md above the first `### `). Strip the Markdown/HTML
+// control characters (`` ` ``, [ ] ( ), < >, |) that could inject a link, image,
+// or table into that bot comment. Escaping at the render boundary — the keys stay
+// legible; only the injection surface is removed. (Crop FILENAMES are separately
+// restricted to [a-z0-9-]; this is the display-side equivalent.)
+const safeKey = (s) => s.replace(/[`[\]()<>|]/g, '-');
 const surfaceBase = (s) => s.replace(/@\d+$/, '');
 const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
 function pushSurfaceWidth(byBase, base, surface) {
@@ -396,7 +404,7 @@ function renderSurfaceGroups(byBase) {
     return [...byBase]
         .map(([base, ws]) => {
         const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
-        return widths.length ? `${base} @ ${widths.join(', ')}` : base;
+        return widths.length ? `${safeKey(base)} @ ${widths.join(', ')}` : safeKey(base);
     })
         .join(' · ');
 }
@@ -821,7 +829,7 @@ function renderContentSurface(ctx, surface, changes, seq) {
     const mapB = loadStyleMap(findCapture(ctx.afterDir, surface));
     const pngA = readPng(path.join(ctx.beforeDir, `${surface}.png`));
     const pngB = readPng(path.join(ctx.afterDir, `${surface}.png`));
-    const md = ['', `### \`${surface}\` · ${changes.length} content change(s)`];
+    const md = ['', `### \`${safeKey(surface)}\` · ${changes.length} content change(s)`];
     for (const c of changes) {
         seq++;
         md.push('', `**\`${prettyLabel(c.path, c.cls)}\`**`, '', `- before: \`${clipText(c.before) || '(empty)'}\``, `- after: \`${clipText(c.after) || '(empty)'}\``, ...contentCropLines(ctx, surface, c, mapA, mapB, pngA, pngB, seq));
@@ -888,7 +896,7 @@ function coverageLine(cov) {
     if (cov.basis === 'complete')
         return `- **Coverage** — ✓ complete (all ${cov.registrySize} registered surface(s) captured)`;
     if (cov.basis === 'incomplete')
-        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.join(', ')})`;
+        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.map(safeKey).join(', ')})`;
     return '- **Coverage** — ⚠ not asserted (no `expected` registry; certifies only the captured surfaces)';
 }
 function determinismLine(det) {
@@ -900,7 +908,7 @@ function determinismLine(det) {
 }
 function inventoryLine(inv) {
     if (inv.unexplained.length > 0) {
-        const keys = inv.unexplained.map((i) => i.key);
+        const keys = inv.unexplained.map((i) => safeKey(i.key));
         return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
     }
     if (inv.delta.removed.length > 0)
@@ -1176,7 +1184,7 @@ function renderNewSurface(p, ctx, cropSeq) {
     const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
     const md = [
         '',
-        `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`,
+        `### \`${safeKey(p.sd.surface)}\` · new surface ${NEW_SURFACE_MARKER}`,
         '',
         `_${formatSurfaceWithContext(p.sd.surface, map)}_`,
     ];
@@ -1214,7 +1222,7 @@ function cappedNoticeLines(budget) {
  *  name (and how many surfaces share the identical change) · change count · a crop
  *  link so the reviewer can still see it without opening report.json. */
 function compactChangeSummary(cg, json, img) {
-    const surface = cg.rep.sd.surface;
+    const surface = safeKey(cg.rep.sd.surface);
     const more = cg.surfaces.length > 1 ? ` (+${cg.surfaces.length - 1} more)` : '';
     const regions = json.regions ?? [];
     const composite = regions[0]?.images?.composite;
@@ -1317,7 +1325,7 @@ export function generateStyleMapReport(opts) {
         const r = renderNewSurface(p, ctx, cropSeq);
         json.push(r.json);
         cropSeq = r.cropSeq;
-        emitDetail(r.md, `- \`${p.sd.surface}\` · new surface`);
+        emitDetail(r.md, `- \`${safeKey(p.sd.surface)}\` · new surface`);
     }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');

package/dist/runner.d.ts

@@ -255,25 +255,29 @@ export type CrawlOptions = CaptureConfig & {
     /** Max ms to wait for the crawl root's links to render before reading them
      *  (an SPA hydrates its nav client-side). Default 15000. */
     linkTimeout?: number;
+    /**
+     * The full set of surface keys the app knows its nav should link to — its route
+     * universe. When set, the crawl reconciles the DISCOVERED link set against it, both
+     * directions: an `expected` key with no rendered link fails (nav regression), and a
+     * rendered link with no `expected` entry fails (a new route with no owner). For a
+     * link-crawled SPA the rendered nav IS the route universe, so this is the same
+     * list-vs-ledger discipline as `defineStyleMapCapture`'s guard with the nav as the
+     * source of truth.
+     *
+     * Unlike the spec guard, this runs INSIDE the crawl capture test — the link set
+     * isn't known until a browser renders the page — so it only fires when the capture
+     * runs (STYLEMAP_DIR set), not in every `npm test`. Omit to keep the current
+     * behaviour: capture what the nav links to, assert no completeness.
+     */
+    expected?: string[];
+    /**
+     * Expected/rendered keys deliberately not reconciled, each mapped to its reason — a
+     * visible, reviewed opt-out ledger for links that render CONDITIONALLY (behind auth
+     * or a feature flag) and so can't be asserted present or absent on every run. An
+     * excluded key never triggers a missing- or unexpected-link failure; an `exclude`
+     * key in neither `expected` nor the rendered set fails, so the ledger can't rot.
+     */
+    exclude?: Record<string, string>;
 };
-/**
- * Like {@link defineStyleMapCapture}, but the surface set is DISCOVERED at run time
- * by crawling a page's links instead of being hand-listed — for a single-route SPA
- * whose views are `?tab=`/client-routed and so invisible to the filesystem
- * {@link discoverNextRoutes}. It navigates `from`, reads its same-origin `<a href>`s
- * (filtered by `match`), and captures each as a surface keyed by `key`. The app just
- * has to render its nav as real links; nothing to hand-maintain, so the surface list
- * can't drift from the nav.
- *
- * One Playwright test does the whole sweep (the link set isn't known until a browser
- * has rendered the page, so per-surface tests can't be generated at collection time).
- * Per-surface failures are aggregated — one bad surface reports without hiding the
- * rest. Replay/self-check/clock-freeze behave exactly as for explicit surfaces.
- *
- * ```ts
- * // styleproof.spec.ts — capture every tab the nav links to
- * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
- * ```
- */
 export declare function defineCrawlCapture(options: CrawlOptions): void;
 export {};

package/dist/runner.js

@@ -4,8 +4,9 @@ import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps, COVERAGE_LEDGER } from './coverage.js';
+import { writeBrowserBuildSidecar } from './map-store.js';
 import { detectViewportWidths } from './breakpoints.js';
-import { selectCrawlLinks } from './crawl.js';
+import { selectCrawlLinks, crawlCoverageError } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
 function driftDesc(f) {
     if (f.kind === 'dom')
@@ -473,6 +474,17 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude) {
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
+/** Record the real browser build into the capture bundle. The npm `@playwright/test`
+ *  version (in the manifest) is only a proxy — the actual Chromium binary can change while
+ *  it holds constant (a re-download, a different browser store, a CI image bump). The
+ *  compatibility guard reads this back to refuse a cross-build compare instead of walling
+ *  a PR with false diffs. Best-effort: an unavailable version leaves the guard as-is. */
+function writeBrowserBuildTest(settings, dir) {
+    test('styleproof browser build', ({ page }) => {
+        const version = page.context().browser()?.version();
+        writeBrowserBuildSidecar(path.join(settings.baseDir, dir), version);
+    });
+}
 export function defineStyleMapCapture(options) {
     const { surfaces, expected, exclude = {}, dir } = options;
     const settings = resolveSettings(options);
@@ -498,6 +510,8 @@ export function defineStyleMapCapture(options) {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
             writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
+        if (dir)
+            writeBrowserBuildTest(settings, dir);
         for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
@@ -541,38 +555,91 @@ export function defineStyleMapCapture(options) {
  * defineCrawlCapture({ from: '/', match: /\?tab=/, widths: [1440, 1024, 768], dir: process.env.STYLEMAP_DIR });
  * ```
  */
+/**
+ * Load the crawl root, wait for its nav links to hydrate, and read them into a
+ * deduped, keyed surface list. A link-less page is fine for an unfiltered crawl —
+ * it still captures `from` itself (includeSelf); a `match`-filtered crawl genuinely
+ * needs links, so its hydration timeout surfaces. Throws when nothing matched.
+ */
+async function discoverCrawlLinks(page, { from, match, key, linkTimeout }) {
+    await page.goto(from, { waitUntil: 'load' });
+    await page.waitForSelector('a[href]', { timeout: linkTimeout }).catch((e) => {
+        if (match !== undefined)
+            throw e;
+    });
+    const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href')));
+    // Unfiltered crawl → also capture `from` itself, so the root is always covered and
+    // a single-page (or no-nav-self-link) app still yields a surface. A `match`-filtered
+    // crawl captures only the links the caller asked for.
+    const links = selectCrawlLinks(hrefs, { base: page.url(), match, key, includeSelf: match === undefined });
+    if (links.length === 0) {
+        throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
+            `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
+    }
+    return links;
+}
+/**
+ * Capture every discovered surface, aggregating per-surface failures so one bad
+ * surface reports without skipping the rest — they're an independent set, not a
+ * chain. Auto-width parity with explicit surfaces: no widths given → navigate once,
+ * detect the surface's @media bands, then sweep one viewport per band.
+ */
+async function sweepCrawlSurfaces(page, captureSurfaces, settings) {
+    const failures = [];
+    for (const surface of captureSurfaces) {
+        let sweep = surface.widths;
+        if (!sweep || sweep.length === 0) {
+            try {
+                await surface.go(page);
+                sweep = await detectViewportWidths(page);
+            }
+            catch (e) {
+                failures.push(`${surface.key} @ auto: ${e.message}`);
+                continue;
+            }
+        }
+        for (const width of sweep) {
+            try {
+                await captureSurface(page, surface, width, settings);
+            }
+            catch (e) {
+                failures.push(`${surface.key} @ ${width}: ${e.message}`);
+            }
+        }
+    }
+    if (failures.length) {
+        throw new Error(`styleproof crawl-capture: ${failures.length} surface(s) failed:\n${failures.join('\n')}`);
+    }
+}
 export function defineCrawlCapture(options) {
-    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir, settle, } = options;
+    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir, settle, expected, exclude = {}, } = options;
     const settings = resolveSettings(options);
     // Title contains "styleproof capture" so the same `--grep 'styleproof capture'`
     // that styleproof-map uses to select capture tests picks up crawl specs too.
     test.describe('styleproof capture (crawl)', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
-        // A crawl DISCOVERS its surfaces from the nav — it has no registry to check against,
-        // so it records `expected: null` (completeness honestly "not asserted": the crawl
-        // captures what the nav links to, and can't prove that's every route in the app).
+        // Record the completeness basis. Without `expected` a crawl has no registry to
+        // check against, so it records `expected: null` (honestly "not asserted": it
+        // captures what the nav links to, and can't prove that's every route). With
+        // `expected` the crawl reconciles the DISCOVERED link set against it below and the
+        // ledger travels with the declared universe.
+        if (dir)
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
         if (dir)
-            writeCoverageLedgerTest(settings, dir, null, {});
+            writeBrowserBuildTest(settings, dir);
         test('discover surfaces by crawling links, then capture each', async ({ page }) => {
-            // 1. Load the root and wait for its nav links to hydrate — an SPA renders them
-            //    client-side, so they aren't in the initial HTML.
-            await page.goto(from, { waitUntil: 'load' });
-            // Wait for the nav's links to hydrate (an SPA renders them client-side). A link-less
-            // page is fine for an unfiltered crawl — it still captures `from` itself (includeSelf);
-            // a `match`-filtered crawl genuinely needs links, so let its timeout surface.
-            await page.waitForSelector('a[href]', { timeout: linkTimeout }).catch((e) => {
-                if (match !== undefined)
-                    throw e;
-            });
-            const hrefs = await page.$$eval('a[href]', (els) => els.map((e) => e.getAttribute('href')));
-            // Unfiltered crawl → also capture `from` itself, so the root is always covered and
-            // a single-page (or no-nav-self-link) app still yields a surface. A `match`-filtered
-            // crawl captures only the links the caller asked for.
-            const links = selectCrawlLinks(hrefs, { base: page.url(), match, key, includeSelf: match === undefined });
-            if (links.length === 0) {
-                throw new Error(`styleproof crawl: no links matched at ${from}. The nav must render same-origin ` +
-                    `<a href> links (a button-only nav exposes nothing to crawl), and \`match\` must keep them.`);
-            }
+            // 1. Load the root and read its hydrated nav links into the surface set.
+            const links = await discoverCrawlLinks(page, { from, match, key, linkTimeout });
+            // Coverage guard for a crawled nav. The rendered link set IS the route universe
+            // for a link-crawled SPA, so reconciling it against `expected` (both directions)
+            // is the spec guard's list-vs-ledger discipline with the nav as source of truth.
+            // Runs here — inside the capture test — because the link set isn't known until
+            // the page renders (unlike the static spec guard, which runs in the plain suite).
+            const gap = expected
+                ? crawlCoverageError(from, links.map((l) => l.key), expected, exclude)
+                : null;
+            if (gap)
+                throw new Error(gap);
             const captureSurfaces = links.flatMap((link) => expandSurfaceVariants({
                 key: link.key,
                 go: async (p) => {
@@ -592,35 +659,8 @@ export function defineCrawlCapture(options) {
             // With auto-width the band count isn't known until each surface renders, so
             // assume up to 4 bands per surface.
             test.setTimeout(Math.max(180_000, captureSurfaces.reduce((sum, surface) => sum + (surface.widths?.length ?? 4), 0) * 60_000));
-            // 2. Capture each discovered surface. Aggregate failures so one bad surface
-            //    reports without skipping the rest — they're an independent set, not a chain.
-            const failures = [];
-            for (const surface of captureSurfaces) {
-                // Auto-width parity with explicit surfaces: no widths given → navigate once and
-                // detect this surface's @media bands, then sweep one viewport per band.
-                let sweep = surface.widths;
-                if (!sweep || sweep.length === 0) {
-                    try {
-                        await surface.go(page);
-                        sweep = await detectViewportWidths(page);
-                    }
-                    catch (e) {
-                        failures.push(`${surface.key} @ auto: ${e.message}`);
-                        continue;
-                    }
-                }
-                for (const width of sweep) {
-                    try {
-                        await captureSurface(page, surface, width, settings);
-                    }
-                    catch (e) {
-                        failures.push(`${surface.key} @ ${width}: ${e.message}`);
-                    }
-                }
-            }
-            if (failures.length) {
-                throw new Error(`styleproof crawl-capture: ${failures.length} surface(s) failed:\n${failures.join('\n')}`);
-            }
+            // 2. Capture each discovered surface, aggregating per-surface failures.
+            await sweepCrawlSurfaces(page, captureSurfaces, settings);
         });
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.17.0",
+  "version": "3.18.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",