styleproof 3.7.0 → 3.9.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.9.0] - 2026-07-05
+
+### Added
+
+- **Coverage provenance — a green now states its completeness basis.** Source-of-truth
+  step 1: a green from `styleproof-diff` used to silently imply completeness it couldn't
+  back up (it certified only the surfaces it happened to capture). Now the capture writes
+  a coverage ledger (`styleproof-coverage.json`) into the bundle — the declared
+  `expected` registry, or `null` — and `styleproof-diff` reads it and:
+  - **blocks (exit 1) when a registered surface was never captured**, even if the style
+    diff is empty — the one failure the gate couldn't catch before (a green over a
+    surface it never looked at). This checks the surfaces actually captured, so a
+    declared surface whose capture _failed_ is caught here, where the suite guard (which
+    checks the declared list) cannot see it;
+  - prints the basis on every run: `✓ coverage complete — all N registered surface(s)
+captured`, `✗ coverage INCOMPLETE — …`, or `⚠ completeness NOT asserted` (no
+    registry — certifies only the captured surfaces, so declare `expected` to certify
+    completeness). A crawl records `expected: null` honestly (it captures what the nav
+    links to, not proven-every-route).
+- `isMapFile` / `RESERVED_BUNDLE_FILES` (map-store) — one place that knows which bundle
+  files are surface maps vs metadata sidecars, so a new sidecar can't read as a phantom
+  "new surface".
+
+## [3.8.0] - 2026-07-05
+
+### Added
+
+- **Zero-config out of the box** — `styleproof-init` now scaffolds a crawl-by-default
+  spec for any non-Next.js app: `defineCrawlCapture({ from: '/', settle, inventory: true })`
+  captures every surface the nav links to (the root plus each same-origin `<a href>`)
+  with **nothing to hand-list** — the surface set is discovered from the rendered nav and
+  can't drift from it. Next.js keeps filesystem route discovery; both variants now enable
+  the inventory guard by default.
+- **`defineCrawlCapture` auto-width** — omit `widths` and StyleProof detects each
+  discovered surface's `@media` breakpoints and sweeps one viewport per band, the same
+  zero-config behaviour explicit surfaces already had.
+- **`defineCrawlCapture` `settle` hook** — run an app-specific step (e.g. trigger
+  scroll-reveal) after navigating to each crawled surface, for parity with a hand-listed
+  surface's `go`.
+- **`inventory` spec option** — `defineStyleMapCapture` / `defineCrawlCapture` now forward
+  `inventory: true` to the capture, so turning the inventory guard on (a removed nav item
+  fails `styleproof-diff`) is a one-line opt-in from a spec, no manual `captureStyleMap`.
+- The crawl now always covers its `from` root on an unfiltered crawl, so a home page not
+  linked in its own nav — or a single-page app with no links — is still captured.
+
+### Changed
+
+- `styleproof-init` guidance now leads with "it runs on your first PR with no extra
+  steps" (CI captures both sides on a cache miss); the local `npx styleproof-map`
+  pre-cache is framed as an optional speedup, not a required first step.
+
+### Tests / docs
+
+- **Dogfood: the "100% surfaced" contract** — `test/pr-surfacing.e2e.spec.ts` runs the
+  real capture → diff → report flow for every change class (resting style,
+  `:hover/:focus/:active` drop, `::before/::after`, DOM add/remove/retag, a removed nav
+  item via the inventory guard, a new surface, and a clean no-op) and asserts each is
+  surfaced — the last two levels through the actual `styleproof-diff` / `styleproof-report`
+  CLIs. Closes the four classes that previously had no end-to-end proof (`:active` drop,
+  DOM removed, retag, pseudo-element change).
+- **Dogfood: zero-config flow** — `test/cli-flow.e2e.spec.ts` runs `styleproof-init` on a
+  real multi-page app and proves the generated crawl spec captures every page (root +
+  pricing + about), multi-width, with the inventory harvested — no spec editing.
+- **`docs/what-it-catches.md`** — states what StyleProof catches and its honest boundary
+  (surfaces it never captured), so a green check is earned, not assumed.
+
 ## [3.7.0] - 2026-07-04
 
 ### Added

package/bin/styleproof-diff.mjs

@@ -41,6 +41,8 @@ import {
 } from '../dist/cli-errors.js';
 import { loadStyleMap } from '../dist/capture.js';
 import { auditRunInventory } from '../dist/inventory.js';
+import { auditCoverage, COVERAGE_LEDGER } from '../dist/coverage.js';
+import { isMapFile } from '../dist/map-store.js';
 
 const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
 
@@ -55,7 +57,7 @@ const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.m
 function dirInventories(dir) {
   return fs
     .readdirSync(dir)
-    .filter((f) => f !== 'styleproof-manifest.json' && /\.json(\.gz)?$/.test(f))
+    .filter(isMapFile)
     .map((f) => loadStyleMap(path.join(dir, f)))
     .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
 }
@@ -110,6 +112,59 @@ function printInventoryAudit(audit) {
   return unexplained.length;
 }
 
+// ── coverage provenance (the completeness basis of a green) ──────────────────────
+// The head bundle carries a coverage ledger (the declared registry). The gate audits
+// the ACTUALLY-captured surfaces against it, so "clean" states its basis — complete vs
+// the registry, or explicitly "not asserted" — instead of silently implying completeness.
+
+// Surface keys captured in a dir (file `<key>@<width>.json[.gz]` → `<key>`, deduped).
+function capturedSurfaceKeys(dir) {
+  return [
+    ...new Set(
+      fs
+        .readdirSync(dir)
+        .filter(isMapFile)
+        .map((f) => f.replace(/@\d+\.json(\.gz)?$/, '')),
+    ),
+  ];
+}
+
+function readCoverageVerdict(dir) {
+  let ledger = null;
+  const p = path.join(dir, COVERAGE_LEDGER);
+  if (fs.existsSync(p)) {
+    try {
+      ledger = JSON.parse(fs.readFileSync(p, 'utf8'));
+    } catch {
+      /* a corrupt ledger reads as no registry → "not asserted", never a false green */
+    }
+  }
+  return auditCoverage(capturedSurfaceKeys(dir), ledger);
+}
+
+// Print the completeness verdict; return true if it BLOCKS (a registered surface is missing).
+function printCoverageVerdict(v) {
+  if (v.basis === 'complete') {
+    console.log(`\n✓ coverage complete — all ${v.registrySize} registered surface(s) captured`);
+    return false;
+  }
+  if (v.basis === 'unasserted') {
+    console.log(
+      '\n⚠ completeness NOT asserted — the spec declared no `expected` registry, so this certifies only the\n' +
+        '  surfaces that were captured, not that they are all of them. Declare `expected` to certify completeness.',
+    );
+    return false;
+  }
+  console.log(
+    `\n✗ coverage INCOMPLETE — ${v.uncovered.length} registered surface(s) not captured (of ${v.registrySize}):`,
+  );
+  for (const k of v.uncovered) console.log(`  ✗ missing: ${k}`);
+  console.log(
+    "  → capture each (or move it to `exclude` with a reason). A green can't certify what was never captured.",
+  );
+  return true;
+}
+
 const HELP = `${COMMAND} — certify a CSS refactor by diffing two computed-style map captures
 
 usage: ${COMMAND} [baseRef] [options]
@@ -201,12 +256,15 @@ if (args.length <= 1) {
 
 let result;
 let inventoryAudit = null;
+let coverageVerdict = null;
 try {
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
-  // Read inventory here, while the (possibly cached/restored) dirs still exist —
-  // the finally below deletes them in cached-map mode.
+  // Read inventory + coverage here, while the (possibly cached/restored) dirs still
+  // exist — the finally below deletes them in cached-map mode. Coverage is the HEAD
+  // bundle's completeness basis.
   inventoryAudit = readInventoryAudit(dirA, dirB);
+  coverageVerdict = readCoverageVerdict(dirB);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -243,8 +301,10 @@ for (const sd of surfaces) {
 }
 
 const invRemovals = printInventoryAudit(inventoryAudit);
+const coverageFails = printCoverageVerdict(coverageVerdict);
 
-if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared }, null, 2));
+if (jsonOut)
+  fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared, coverage: coverageVerdict }, null, 2));
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;
@@ -252,13 +312,15 @@ const newSurfaces = surfaces.filter((s) => s.missing).length;
 const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
+const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
+const clean = total === 0 && invRemovals === 0 && !coverageFails;
 console.log(
-  total === 0 && invRemovals === 0
+  clean
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${covNote}`,
 );
-// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory
-// removals), 3 = only new surfaces (no baseline). 2 reserved for usage/capture errors.
-process.exit(total > 0 || invRemovals > 0 ? 1 : newSurfaces > 0 ? 3 : 0);
+// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals or
+// an incomplete coverage registry), 3 = only new surfaces (no baseline). 2 = usage/capture error.
+process.exit(total > 0 || invRemovals > 0 || coverageFails ? 1 : newSurfaces > 0 ? 3 : 0);

package/bin/styleproof-init.mjs

@@ -153,64 +153,37 @@ defineStyleMapCapture({
   exclude: Object.fromEntries(
     ROUTES.filter((r) => r.dynamic).map((r) => [r.key, \`dynamic route (\${r.path}) — add a surface with a concrete param\`]),
   ),
+  inventory: true, // also fail the diff when a nav item / route the UI used to offer disappears
   dir: process.env.STYLEMAP_DIR,
 });
 `;
 
-// Non-Next project: one sample surface + a commented guard block to wire to
-// whatever the project uses as a route/view registry.
+// Non-Next project: crawl every surface the nav links to, so ANY app captures its
+// whole reachable surface out of the box with nothing to hand-list. The crawl reads
+// the rendered nav; the surface set can't drift from it.
 const GENERIC_SPEC = `import type { Page } from '@playwright/test';
-import { defineStyleMapCapture, type Surface } from 'styleproof';
+import { defineCrawlCapture } from 'styleproof';
 
 ${HEADER}
 
 ${SETTLE}
 
-const SURFACES: Surface[] = [
-  {
-    key: 'home',
-    go: async (page) => {
-      await page.goto('/');
-      await settle(page);
-    },
-    ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
-    // No widths → StyleProof detects your @media breakpoints from the loaded CSS and
-    // sweeps one viewport per band. Pass an explicit array (e.g. 1280, 768, 390) to pin them (or to
-    // cover a JS-only matchMedia breakpoint that has no CSS @media rule).
-    // Non-live UI states belong here as variants, so the base branch's
-    // dialog-open state compares to the head branch's dialog-open state.
-    // variants: [
-    //   {
-    //     key: 'dialog-open',
-    //     go: async (page) => {
-    //       await page.getByRole('button', { name: /open settings/i }).click();
-    //       await page.getByRole('dialog').waitFor();
-    //     },
-    //   },
-    //   {
-    //     key: 'popover-open',
-    //     go: async (page) => {
-    //       await page.getByRole('button', { name: /more/i }).click();
-    //       await page.locator('[popover], [role="menu"]').first().waitFor();
-    //     },
-    //   },
-    // ],
-  },
-  // Add more surfaces for distinct routes/views; add menus, dialogs, popovers,
-  // selected tabs, and form errors as variants of the route/view that owns them.
-];
-
-defineStyleMapCapture({
-  surfaces: SURFACES,
-  // Coverage guard (recommended): declare every route your app knows about so a
-  // newly added page can't ship without a surface. Wire \`expected\` to your route
-  // registry — a routes/views list, your router config, or a glob of your pages —
-  // and StyleProof fails the suite (no STYLEMAP_DIR needed) when a route has no
-  // surface and isn't excluded. (A Next.js app gets this auto-wired; see
-  // \`discoverNextRoutes\` in the README.)
-  //   expected: ROUTES.map((r) => r.id),
-  //   exclude: { checkout: 'auth-gated — fixture pending' },
+// Zero-config capture: crawl every surface your nav links to from '/'. The surface set
+// is DISCOVERED from the rendered nav, so it can't drift from it — no hand-listed
+// \`surfaces\` array to maintain, and a page you add to the nav is captured automatically.
+// The root (/) is always captured, plus every same-origin <a href> it links to.
+defineCrawlCapture({
+  from: '/',
+  settle, // trigger scroll-reveal per surface (StyleProof handles fonts/animation/network itself)
+  // No \`widths\` → StyleProof detects each surface's @media breakpoints and sweeps one
+  // viewport per band. Pass an array (e.g. [1440, 768, 390]) to pin them.
+  inventory: true, // also fail the diff when a nav item / route the UI used to offer disappears
+  ignore: [], // e.g. ['.live-feed', '.ad-slot'] for nondeterministic regions
   dir: process.env.STYLEMAP_DIR,
+  // A single-route SPA whose views are ?tab= / client-routed? Keep only those:
+  //   match: /\\?tab=/,
+  // 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(); } }],
 });
 `;
 
@@ -472,7 +445,8 @@ if (spec.wrote) {
         (dynamic ? ` (${dynamic} dynamic route(s) excluded pending a concrete param)` : ''),
     );
   } else {
-    console.log('  no Next.js routes detected — wrote a starter surface + a commented coverage-guard block');
+    console.log('  no Next.js routes detected — wrote a crawl-by-default spec that captures every');
+    console.log('  surface your nav links to from / (nothing to hand-list; the inventory guard is on)');
   }
   wroteSomething = true;
 } else {
@@ -508,15 +482,14 @@ if (ci.wrote) {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
-console.log('\nHow the gate works — local-first maps, CI report when cached:');
-console.log('  1. Commit your code, then run:');
+console.log('\nHow the gate works — it runs on your first PR with no extra steps:');
+console.log('  1. Commit and open a PR. CI captures the base and head surfaces in one pinned');
+console.log('     environment and posts the StyleProof report — no local step required.');
+console.log('  2. (Optional, faster) Pre-cache this commit so CI skips recapturing the base:');
 console.log('       npx styleproof-map');
-console.log('     It captures a production-build map into .styleproof/ and uploads the bundle');
-console.log('     to the styleproof-maps branch when the git remote is available.');
-console.log('  2. Open the PR. CI restores the base/head bundles and generates the report');
-console.log('     without a browser when both maps are present and compatible.');
-console.log('  3. If a bundle is missing or incompatible, CI recaptures both sides in the same');
-console.log('     environment before generating the report. Correctness beats a stale cache.');
+console.log('     It captures a production-build map into .styleproof/ and uploads the bundle to');
+console.log('     the styleproof-maps branch when the git remote is available; CI then restores');
+console.log('     it and generates the report without a browser.');
 
 if (!wroteSomething) console.log('\nnothing to write — project already scaffolded.');
 process.exit(0);

package/dist/coverage.d.ts

@@ -34,3 +34,26 @@ export type CoverageGaps = {
  * dir), and it's exported so a consumer can assert coverage however it likes.
  */
 export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;
+/** Bundled next to the maps, so the completeness basis travels with the capture. */
+export declare const COVERAGE_LEDGER = "styleproof-coverage.json";
+export type CoverageLedger = {
+    version: 1;
+    /** The declared surface registry, or null when the spec asserted none. */
+    expected: string[] | null;
+    /** Reviewed opt-outs (`key → reason`). */
+    exclude: Record<string, string>;
+};
+export type CoverageVerdict = {
+    /** `complete` — every registered surface captured; `incomplete` — a registered
+     *  surface is missing (gates); `unasserted` — no registry, so a green can only
+     *  certify the captured surfaces, not that they are all of them. */
+    basis: 'complete' | 'incomplete' | 'unasserted';
+    /** Size of the declared registry, or null when unasserted. */
+    registrySize: number | null;
+    /** Registered surfaces neither captured nor excluded — the coverage hole. */
+    uncovered: string[];
+    /** `exclude` entries no longer in `expected` — a rotted opt-out. */
+    staleExclusions: string[];
+};
+/** The gate's completeness call: audit what was actually captured against the ledger. */
+export declare function auditCoverage(capturedKeys: Iterable<string>, ledger: CoverageLedger | null): CoverageVerdict;

package/dist/coverage.js

@@ -34,3 +34,26 @@ export function coverageGaps(capturedKeys, expected, exclude = {}) {
     const staleExclusions = Object.keys(exclude).filter((k) => !expectedSet.has(k));
     return { uncovered, staleExclusions };
 }
+// ── coverage provenance (the gate-level completeness assertion) ──────────────────
+// The guard above runs in the app's SUITE. That fails a build when the spec forgets a
+// route, but the GATE (styleproof-diff, reading captured maps) never learns whether
+// coverage was asserted at all — so a green silently implies a completeness it can't
+// back up. The capture writes this ledger into the bundle; the gate reads it and
+// certifies "clean" only against a STATED basis, enforcing the registry against the
+// maps actually captured (a declared surface whose capture FAILED is caught here, where
+// the suite guard — which checks the declared list — cannot see it).
+/** Bundled next to the maps, so the completeness basis travels with the capture. */
+export const COVERAGE_LEDGER = 'styleproof-coverage.json';
+/** The gate's completeness call: audit what was actually captured against the ledger. */
+export function auditCoverage(capturedKeys, ledger) {
+    if (!ledger || ledger.expected == null) {
+        return { basis: 'unasserted', registrySize: null, uncovered: [], staleExclusions: [] };
+    }
+    const { uncovered, staleExclusions } = coverageGaps(capturedKeys, ledger.expected, ledger.exclude);
+    return {
+        basis: uncovered.length ? 'incomplete' : 'complete',
+        registrySize: ledger.expected.length,
+        uncovered,
+        staleExclusions,
+    };
+}

package/dist/crawl.d.ts

@@ -37,6 +37,10 @@ export type SelectLinksOptions = {
     match?: LinkMatch;
     /** Derive the surface key from a link URL. Default: {@link defaultLinkKey}. */
     key?: (url: URL) => string;
+    /** Also capture the crawled page itself as the first surface, so `from` is always
+     *  covered — even if the nav doesn't link back to it, or it's a single-page app with
+     *  no links at all. Default false. Used for an unfiltered "capture everything" crawl. */
+    includeSelf?: boolean;
 };
 /**
  * Filename-safe, readable key from a link URL. Joins the path segments and the

package/dist/crawl.js

@@ -83,6 +83,11 @@ export function selectCrawlLinks(hrefs, opts) {
     const keyFor = opts.key ?? defaultLinkKey;
     const seen = new Set();
     const out = [];
+    if (opts.includeSelf) {
+        const selfUrl = base.pathname + base.search;
+        seen.add(selfUrl);
+        out.push({ key: keyFor(base), url: selfUrl });
+    }
     for (const href of hrefs) {
         const link = href ? toLink(href, base, keyFor, opts.match) : null;
         if (!link || seen.has(link.url))

package/dist/diff.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadStyleMap, isUnder } from './capture.js';
+import { isMapFile } from './map-store.js';
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -173,7 +174,7 @@ function tallyCounts(findings, counts) {
 function indexDir(dir) {
     return Object.fromEntries(fs
         .readdirSync(dir)
-        .filter((f) => f !== 'styleproof-manifest.json' && /\.json(\.gz)?$/.test(f))
+        .filter(isMapFile)
         .map((f) => [f.replace(/\.json(\.gz)?$/, ''), path.join(dir, f)]));
 }
 /** Diff every same-named capture between two directories. `volatile` is the

package/dist/map-store.d.ts

@@ -3,6 +3,12 @@ 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";
+/** 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 declare const RESERVED_BUNDLE_FILES: ReadonlySet<string>;
+/** True for a captured surface map (`<key>@<width>.json[.gz]`), false for metadata. */
+export declare function isMapFile(name: string): boolean;
 export declare class MapStoreError extends Error {
 }
 export interface MapManifest {

package/dist/map-store.js

@@ -5,12 +5,21 @@ import { createRequire } from 'node:module';
 import os from 'node:os';
 import path from 'node:path';
 import { inferBaseRef } from './gitref.js';
+import { COVERAGE_LEDGER } from './coverage.js';
 export const DEFAULT_MAP_DIR = '.styleproof/maps';
 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';
 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]);
+/** 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);
+}
 export class MapStoreError extends Error {
 }
 function runGit(cwd, args, maxBuffer = 1 << 28) {

package/dist/report.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
+import { isMapFile } from './map-store.js';
 import { diffStyleMapDirs, diffContentDirs, } from './diff.js';
 import { describeChange, tokenIndex, toHex, trackCount } from './describe.js';
 // Re-export the plain-English summariser so consumers (and tests) reach it
@@ -443,9 +444,7 @@ function liveCandidateLabel(candidate) {
     return `${label} (${candidate.reason})`;
 }
 function captureFiles(dir) {
-    return fs.existsSync(dir)
-        ? fs.readdirSync(dir).filter((f) => f !== 'styleproof-manifest.json' && /\.json(\.gz)?$/.test(f))
-        : [];
+    return fs.existsSync(dir) ? fs.readdirSync(dir).filter(isMapFile) : [];
 }
 function collectLiveCandidateLabels(beforeDir, afterDir) {
     const seen = new Set();

package/dist/runner.d.ts

@@ -168,6 +168,15 @@ export type DefineOptions = {
      * their exact capture set unless this is enabled.
      */
     popups?: boolean | PopupCaptureOptions;
+    /**
+     * Opt-in inventory guard (default OFF). Harvest each surface's navigable
+     * affordances — route links, `role=tab`/`menuitem`, button-only nav — into
+     * `StyleMap.inventory`, so `styleproof-diff` fails when a nav item / route the UI
+     * used to offer disappears (acknowledge intentional removals in
+     * `styleproof.inventory.json`). Additive; ignored by the certification style diff.
+     * See `docs/inventory-guard.md`.
+     */
+    inventory?: boolean;
 };
 export declare function selfCheckErrorMessage(surfaceKey: string, drift: Finding[], volatile?: string[], liveCandidates?: LiveRegionCandidate[]): string;
 type ResolvedPopupCaptureOptions = Required<PopupCaptureOptions>;
@@ -213,19 +222,6 @@ export declare function resolveBaseDir(baseDir: string | undefined, env?: string
 export declare function resolveScreenshots(screenshots: boolean | undefined, env?: string | undefined): boolean;
 /** The capture settings every capturer shares (everything bar the surface set). */
 type CaptureConfig = Omit<DefineOptions, 'surfaces' | 'expected' | 'exclude'>;
-/**
- * Generate one Playwright test per surface × width that captures the style
- * map to `<baseDir>/<dir>/<key>@<width>.json.gz`. Captures are made
- * deterministic with no per-repo fixtures: the baseline run records each
- * surface's data responses to a HAR, and the comparison run replays them (set
- * STYLEPROOF_REPLAY_FROM=<baseline dir> on the comparison capture), while the
- * clock is frozen so time-derived styling is stable.
- *
- * ```ts
- * // styleproof.spec.ts
- * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
- * ```
- */
 export declare function defineStyleMapCapture(options: DefineOptions): void;
 /** Options for {@link defineCrawlCapture}: where to crawl, how to filter/key the
  *  links, and the viewport sweep — plus the shared capture settings. */
@@ -238,10 +234,16 @@ export type CrawlOptions = CaptureConfig & {
     match?: LinkMatch;
     /** Derive a surface key from a link URL. Default: path+query slug (`/?tab=x` → `x`). */
     key?: (url: URL) => string;
-    /** Viewport widths swept for every discovered surface — one per @media band. */
-    widths: number[];
+    /** Viewport widths swept for every discovered surface. Omit to auto-detect each
+     *  surface's @media breakpoints (one viewport per band) — the same zero-config
+     *  behaviour as an explicit surface with no `widths`. */
+    widths?: number[];
     /** Viewport height per width (default 800). */
     height?: number | ((width: number) => number);
+    /** Run after navigating to each discovered link, before capture — e.g. to trigger
+     *  scroll-reveal content. The built-in font/animation/network settle always runs;
+     *  this is the app-specific hook, the crawl's parity with a hand-listed surface's `go`. */
+    settle?: (page: Page) => Promise<void>;
     /** Selectors skipped on every surface (live regions, third-party embeds). */
     ignore?: string[];
     /** Deterministic variants captured for every discovered link surface. */

package/dist/runner.js

@@ -3,7 +3,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
-import { coverageGaps } from './coverage.js';
+import { coverageGaps, COVERAGE_LEDGER } from './coverage.js';
 import { detectViewportWidths } from './breakpoints.js';
 import { selectCrawlLinks } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
@@ -371,6 +371,7 @@ async function captureSurface(page, surface, width, s) {
             ignore: surface.ignore ?? [],
             captureText: s.captureText,
             captureComponent: s.captureComponent,
+            inventory: s.inventory,
             pendingRequests: requests.pending,
             metadata: surface.metadata,
         });
@@ -435,6 +436,7 @@ function resolveSettings(c) {
         captureText: c.captureText ?? false,
         captureComponent: c.captureComponent ?? false,
         popups: resolvePopupCaptureOptions(c.popups),
+        inventory: c.inventory ?? false,
     };
 }
 /**
@@ -450,6 +452,20 @@ function resolveSettings(c) {
  * defineStyleMapCapture({ surfaces: SURFACES, dir: process.env.STYLEMAP_DIR });
  * ```
  */
+/**
+ * Emit a test that records the coverage ledger into the capture bundle, so the GATE
+ * (styleproof-diff) can state its completeness basis — not just the app's own suite.
+ * `expected: null` records that the spec declared no registry, so a green can only
+ * certify the captured surfaces. Runs on a capture run (dir set) only.
+ */
+function writeCoverageLedgerTest(baseDir, dir, expected, exclude) {
+    test('styleproof coverage ledger', () => {
+        const outDir = path.join(baseDir, dir);
+        fs.mkdirSync(outDir, { recursive: true });
+        const ledger = { version: 1, expected, exclude };
+        fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
+    });
+}
 export function defineStyleMapCapture(options) {
     const { surfaces, expected, exclude = {}, dir } = options;
     const settings = resolveSettings(options);
@@ -473,6 +489,8 @@ export function defineStyleMapCapture(options) {
     }
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
+        if (dir)
+            writeCoverageLedgerTest(settings.baseDir, dir, expected ?? null, exclude);
         for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
@@ -517,17 +535,33 @@ export function defineStyleMapCapture(options) {
  * ```
  */
 export function defineCrawlCapture(options) {
-    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir } = options;
+    const { from, match, key, widths, height, ignore, variants, liveStates, popups, linkTimeout = 15_000, dir, settle, } = options;
     const settings = resolveSettings(options);
-    test.describe('styleproof crawl-capture', () => {
+    // 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).
+        if (dir)
+            writeCoverageLedgerTest(settings.baseDir, dir, null, {});
         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' });
-            await page.waitForSelector('a[href]', { timeout: linkTimeout });
+            // 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')));
-            const links = selectCrawlLinks(hrefs, { base: page.url(), match, key });
+            // 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.`);
@@ -536,6 +570,8 @@ export function defineCrawlCapture(options) {
                 key: link.key,
                 go: async (p) => {
                     await p.goto(link.url, { waitUntil: 'load' });
+                    if (settle)
+                        await settle(p);
                 },
                 widths,
                 ignore,
@@ -546,12 +582,27 @@ export function defineCrawlCapture(options) {
             }));
             // Budget the whole sweep up front: one test captures every surface, and
             // captureSurface no longer sets its own timeout, so size it to the work found.
-            test.setTimeout(Math.max(180_000, captureSurfaces.reduce((sum, surface) => sum + (surface.widths?.length ?? 0), 0) * 60_000));
+            // 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) {
-                for (const width of surface.widths ?? []) {
+                // 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);
                     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.7.0",
+  "version": "3.9.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",