styleproof 3.6.0 → 3.8.0

package/CHANGELOG.md

@@ -7,6 +7,69 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- **Inventory guard** — StyleProof can now assert the navigable UI doesn't silently
+  shrink. Opt in with `captureStyleMap(page, { inventory: true })` and each surface's
+  navigable affordances — internal route links, `role=tab`, `role=menuitem`,
+  button-only nav — are harvested (keyed stably) into `StyleMap.inventory`.
+  `styleproof-diff` then unions the reachable set across both sides and **exits 1 on
+  any affordance present on base but absent on head** — a feature that stopped being
+  reachable — unless it's acknowledged in `styleproof.inventory.json` (`{"<key>":
+"<why>"}`, path overridable via `STYLEPROOF_INVENTORY`; a stale acknowledgement is
+  flagged so the ledger can't rot). Closes the certification diff's blind spot for the
+  information-architecture / replacement class: a redesign staged as a new surface, or
+  a nav item / route that disappears, which a same-surface computed-style diff catches
+  only incidentally. **Off by default (no map carries inventory ⇒ the CLI is
+  byte-for-byte unchanged); the certification diff itself is untouched.** The
+  programmatic entry point `auditRunInventory(baseMaps, headMaps, allowRemoved)`
+  stays available for custom gates. See `docs/inventory-guard.md`.
+
 ## [3.6.0] - 2026-07-03
 
 ### Changed

package/bin/styleproof-diff.mjs

@@ -39,9 +39,77 @@ import {
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
+import { loadStyleMap } from '../dist/capture.js';
+import { auditRunInventory } from '../dist/inventory.js';
 
 const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
 
+// ── inventory guard (opt-in) ────────────────────────────────────────────────────
+// Surfaces the navigable-inventory audit through the CLI. When captures carry
+// `inventory` (from captureStyleMap({ inventory: true })), an affordance base
+// offered and head no longer does BLOCKS unless acknowledged. Inert when no map
+// carries inventory, so every existing capture behaves exactly as before.
+
+// Mirror of indexDir() in diff.ts — the capture-dir file filter, kept local so the
+// bin needn't reach into diff internals for one small read.
+function dirInventories(dir) {
+  return fs
+    .readdirSync(dir)
+    .filter((f) => f !== 'styleproof-manifest.json' && /\.json(\.gz)?$/.test(f))
+    .map((f) => loadStyleMap(path.join(dir, f)))
+    .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+}
+
+// `key -> reason` acknowledged removals. Optional file; absent → none. Malformed
+// JSON fails loud (exit 2) rather than silently un-acknowledging a real removal.
+function loadAllowRemoved() {
+  const p = path.resolve(process.env.STYLEPROOF_INVENTORY ?? 'styleproof.inventory.json');
+  if (!fs.existsSync(p)) return {};
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (e) {
+    console.error(`${COMMAND}: ${p} is not valid JSON — ${e.message}`);
+    process.exit(2);
+  }
+}
+
+// Read both sides' inventory and audit removals. MUST run before any cached-map
+// cleanup deletes the restored dirs. Returns null when no capture carries inventory.
+function readInventoryAudit(dirA, dirB) {
+  const baseInv = dirInventories(dirA);
+  const headInv = dirInventories(dirB);
+  if (![...baseInv, ...headInv].some((m) => m.inventory?.length)) return null;
+  const allowed = loadAllowRemoved();
+  return { allowed, ...auditRunInventory(baseInv, headInv, allowed) };
+}
+
+// Print the Inventory section from a prior audit; return the count of UNACKNOWLEDGED
+// removals (which block). No-op/0 when there was nothing with inventory to audit.
+function printInventoryAudit(audit) {
+  if (!audit) return 0;
+  const { delta, unexplained, staleAllowances, allowed } = audit;
+  if (!delta.added.length && !delta.removed.length && !staleAllowances.length) {
+    console.log('\n📐 Inventory: navigable set unchanged across captured surfaces');
+    return 0;
+  }
+  console.log('\n📐 Inventory (navigable affordances — route links, tabs, menu items, nav buttons):');
+  for (const it of delta.removed) {
+    const why = allowed[it.key];
+    console.log(
+      why
+        ? `  removed: ${it.key} ("${it.label}") — acknowledged: ${why}`
+        : `  ✗ REMOVED, unacknowledged: ${it.key} ("${it.label}")`,
+    );
+  }
+  for (const it of delta.added) console.log(`  + added: ${it.key} ("${it.label}")`);
+  for (const k of staleAllowances) console.log(`  ⚠ stale allowRemoved (key is not actually removed): ${k}`);
+  if (unexplained.length)
+    console.log(
+      `  → ${unexplained.length} unacknowledged removal(s): restore the affordance, or record the decision in styleproof.inventory.json {"<key>":"<why>"}.`,
+    );
+  return unexplained.length;
+}
+
 const HELP = `${COMMAND} — certify a CSS refactor by diffing two computed-style map captures
 
 usage: ${COMMAND} [baseRef] [options]
@@ -132,9 +200,13 @@ if (args.length <= 1) {
 }
 
 let result;
+let inventoryAudit = 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.
+  inventoryAudit = readInventoryAudit(dirA, dirB);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -170,6 +242,8 @@ for (const sd of surfaces) {
   if (lines.length > MAX) console.log(`  ... and ${lines.length - MAX} more lines (re-run with --max ${lines.length})`);
 }
 
+const invRemovals = printInventoryAudit(inventoryAudit);
+
 if (jsonOut) fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared }, null, 2));
 
 const total = counts.dom + counts.style + counts.state;
@@ -177,13 +251,14 @@ const newSurfaces = surfaces.filter((s) => s.missing).length;
 // One SurfaceDiff per distinct surface across both sides (incl. missing-on-one-side).
 const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
+const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
 console.log(
-  total === 0
+  total === 0 && invRemovals === 0
     ? 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}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}`,
 );
-// 0 = identical, 1 = reviewable differences, 3 = only new surfaces (no baseline,
-// nothing to review). 2 stays reserved for usage/capture errors.
-process.exit(total > 0 ? 1 : newSurfaces > 0 ? 3 : 0);
+// 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);

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/capture.d.ts

@@ -1,4 +1,5 @@
 import type { Page } from '@playwright/test';
+import { type NavigableItem } from './inventory.js';
 /**
  * Computed-style capture: the browser's final resolved value for every CSS
  * longhand on every element, keyed by DOM structure (never by class name, so
@@ -124,6 +125,13 @@ export type StyleMap = {
      * surface from the document root; per-subtree overrides aren't tracked.
      */
     tokens?: Record<string, string>;
+    /**
+     * The surface's navigable inventory — user-reachable affordances (route links,
+     * tabs, menu items, button-only nav), keyed stably. Present only when captured
+     * with `inventory: true`. Diffed by the inventory guard (a removal gates), never
+     * by the certification diff. See docs/inventory-guard.md.
+     */
+    inventory?: NavigableItem[];
 };
 export type CaptureOptions = {
     /**
@@ -135,6 +143,12 @@ export type CaptureOptions = {
      * is volatile without paying the settle wait for it.
      */
     ignore?: string[];
+    /**
+     * Harvest the surface's navigable inventory (route links, tabs, menu items,
+     * button-only nav) into `StyleMap.inventory`, for the inventory guard. Off by
+     * default; advisory to the certification diff — a removal gates separately.
+     */
+    inventory?: boolean;
     /**
      * Settle the page before capturing, and auto-exclude live regions (default
      * on). StyleProof polls the (motion-frozen) page until its computed-style map
@@ -234,12 +248,6 @@ export declare function trackInflightRequests(page: Page): {
     pending: () => number;
     dispose: () => void;
 };
-/**
- * Capture the page's complete style map. Drive the page to the state you want
- * first (navigate, open menus); by default the capture then auto-settles the
- * page and excludes live regions (see `stabilize`), so a fetch/stream that
- * paints after `go()` resolves is captured loaded, not mid-load.
- */
 export declare function captureStyleMap(page: Page, options?: CaptureOptions): Promise<StyleMap>;
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */
 export declare function saveStyleMap(filePath: string, map: StyleMap): void;

package/dist/capture.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
+import { classifyInventory, collectNavAffordances } from './inventory.js';
 const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"], [tabindex]';
 // Freeze motion so every captured value is a settled end state, not a frame
 // of an animation or a mid-flight transition after a forced :hover.
@@ -354,6 +355,7 @@ function detectOverlayCandidates({ ignore }) {
 }
 /** Full (unpruned) computed styles for an element and its descendants, pseudo-elements included. */
 // Serialized into the browser by page.evaluate; cannot call module helpers.
+// fallow-ignore-next-line complexity -- pre-existing (cog 16); in-page fn can't call module helpers, so it can't be split. Exposed here only because the inventory feature edits this file. Refactor separately.
 function snapSubtree({ selector, index }) {
     const el = document.querySelectorAll(selector)[index];
     const pathOf = (n) => {
@@ -665,6 +667,13 @@ function mergeMotion(elements, motion) {
  * page and excludes live regions (see `stabilize`), so a fetch/stream that
  * paints after `go()` resolves is captured loaded, not mid-load.
  */
+/**
+ * Harvest the surface's navigable inventory when enabled; `[]` otherwise. Kept out
+ * of captureStyleMap so that function stays within the complexity budget.
+ */
+async function harvestInventoryFor(page, enabled) {
+    return enabled ? classifyInventory(await page.evaluate(collectNavAffordances)) : [];
+}
 export async function captureStyleMap(page, options = {}) {
     // Framework/non-visual noise is always skipped, so it can't read as a DOM
     // change; the caller's `ignore` adds to it (not replaces it).
@@ -730,6 +739,7 @@ export async function captureStyleMap(page, options = {}) {
         statesSkipped = forced.skipped;
     }
     const tokens = await page.evaluate(capturePageTokens);
+    const inventory = await harvestInventoryFor(page, options.inventory);
     return {
         ...(options.metadata ? { metadata: options.metadata } : {}),
         defaults: base.defaults,
@@ -740,6 +750,7 @@ export async function captureStyleMap(page, options = {}) {
         ...(liveCandidates.length ? { liveCandidates } : {}),
         ...(overlays.length ? { overlays } : {}),
         ...(Object.keys(tokens).length ? { tokens } : {}),
+        ...(inventory.length ? { inventory } : {}),
     };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */

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/index.d.ts

@@ -1,4 +1,5 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export * from './inventory.js';
 export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
 export type { CaptureUrlOptions, CaptureUrlResult } from './capture-url.js';
 export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';

package/dist/index.js

@@ -1,4 +1,5 @@
 export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export * from './inventory.js';
 export { captureUrlToDir, runCaptureUrl, parseCaptureUrlArgs, UsageError } from './capture-url.js';
 export { crawlAndCapture, CRAWL_DEFAULTS } from './crawl-surfaces.js';
 export { loadSetupSteps } from './capture-url.js';

package/dist/inventory.d.ts

@@ -0,0 +1,70 @@
+/** One user-reachable navigation affordance, keyed stably across base/head. */
+export type NavigableItem = {
+    /**
+     * Stable identity across captures. `route:<pathname><search>` for internal
+     * links; `<role>:<slug(name)>` for tabs / menu items / button-only nav — so a
+     * tab labelled "MODEL CONFIG" keys as `tab:model-config` regardless of styling,
+     * and lines up with an app's own view id.
+     */
+    key: string;
+    kind: 'link' | 'tab' | 'menuitem' | 'nav-button';
+    /** Visible accessible name at capture time (for the report). */
+    label: string;
+    /** Resolved same-origin path, for `kind: 'link'`. */
+    href?: string;
+};
+export type InventoryDelta = {
+    /** Present on head, absent on base — a newly-offered affordance (informational). */
+    added: NavigableItem[];
+    /** Present on base, absent on head — a feature the UI stopped offering (gates). */
+    removed: NavigableItem[];
+};
+/** `key -> reason` — removals that are intentional, reviewed, and on the record. */
+export type AllowedRemovals = Record<string, string>;
+/** One raw navigable affordance as read from the DOM, before classification. */
+export type RawAffordance = {
+    tag: string;
+    role: string;
+    name: string;
+    /** pathname+search for a same-origin `<a href>`; null otherwise. Resolved in-page. */
+    internalPath: string | null;
+};
+/** In-page: collect visible navigable affordances. No classification. */
+export declare function collectNavAffordances(): RawAffordance[];
+/** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
+export declare function classifyInventory(raw: RawAffordance[]): NavigableItem[];
+/** Harvest a page's inventory: thin in-page collect + pure classify. */
+export declare function harvestInventory(page: {
+    evaluate: <T>(fn: () => T) => Promise<T>;
+}): Promise<NavigableItem[]>;
+/** Union the per-surface inventories of a whole run into one reachable set. */
+export declare function unionInventory(perSurface: Array<{
+    inventory?: NavigableItem[];
+} | undefined>): NavigableItem[];
+/** Base vs head reachable sets → what the UI newly offers / stopped offering. */
+export declare function diffInventory(base: NavigableItem[], head: NavigableItem[]): InventoryDelta;
+/**
+ * The gate. Removals that aren't acknowledged in `allowed` (key -> reason) are
+ * unexplained — the caller fails on a non-empty result. An `allowed` key that
+ * isn't actually removed is a stale acknowledgement, returned separately so the
+ * ledger can't quietly rot (mirrors the `exclude` coverage guard).
+ */
+export declare function auditRemovals(delta: InventoryDelta, allowed?: AllowedRemovals): {
+    unexplained: NavigableItem[];
+    staleAllowances: string[];
+};
+/**
+ * Run-level entry point: union both sides' per-surface `map.inventory`, diff, and
+ * audit removals. This is what a gate calls — pass every base map and every head
+ * map (the reachable set is the union across all surfaces). `unexplained` non-empty
+ * ⇒ the gate should fail; `staleAllowances` non-empty ⇒ prune the ledger.
+ */
+export declare function auditRunInventory(baseMaps: Array<{
+    inventory?: NavigableItem[];
+} | undefined>, headMaps: Array<{
+    inventory?: NavigableItem[];
+} | undefined>, allowed?: AllowedRemovals): {
+    delta: InventoryDelta;
+    unexplained: NavigableItem[];
+    staleAllowances: string[];
+};

package/dist/inventory.js

@@ -0,0 +1,135 @@
+// Inventory guard — assert the navigable UI doesn't silently shrink.
+//
+// StyleProof's certification diff answers "did surface X change between base and
+// head?" — a same-key regression check. It is structurally blind to a whole class
+// of high-stakes change: a redesign delivered as a NEW surface beside the old one
+// (the diff is old-vs-old, clean), or a nav item / route that DISAPPEARS (a feature
+// stops being reachable). Those aren't restyles — they're the reachable set of the
+// UI shrinking, which is an information-architecture change the pixel diff catches
+// only incidentally, if at all.
+//
+// This module harvests the *navigable inventory* of each captured surface — the
+// user-reachable affordances (route links, tabs, menu items, button-only SPA nav) —
+// keyed by a stable id, then diffs the UNION across a run. A key present on base but
+// absent on head is a REMOVAL: a feature the UI no longer offers. Removals gate
+// (like the `exclude` coverage ledger) unless explicitly acknowledged with a reason,
+// so "we dropped Model Config" is a decision on the record, never a silent green.
+//
+// The harvest (`collectNavAffordances`) runs in-page, mirroring
+// `detectOverlayCandidates`; the diff/union/guard are pure and unit-testable.
+// ── in-page harvest ───────────────────────────────────────────────────────────
+// Split in two: the DOM-touching half stays thin (and serializable to the page,
+// like detectOverlayCandidates); the classification is pure and unit-testable.
+/** In-page: collect visible navigable affordances. No classification. */
+export function collectNavAffordances() {
+    const visible = (el) => {
+        if (el.hidden || el.getAttribute('aria-hidden') === 'true')
+            return false;
+        const r = el.getBoundingClientRect();
+        const s = getComputedStyle(el);
+        return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden';
+    };
+    const nameOf = (el) => (el.getAttribute('aria-label') || el.textContent || '').replace(/\s+/g, ' ').trim().slice(0, 80);
+    const internalPath = (el) => {
+        const raw = (el.getAttribute('href') || '').trim();
+        if (!raw || raw.startsWith('#'))
+            return null;
+        try {
+            const u = new URL(raw, location.href);
+            return u.origin === location.origin ? `${u.pathname}${u.search}` : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    // Semantic nav first (a[href], role=tab/menuitem, <nav>/tablist buttons); then a
+    // conservative class heuristic for button-only navs that skip ARIA — a container
+    // whose class strongly implies navigation (nav / navtab / subnav / tabs / subtab).
+    // Erring broad is correct here: a stray non-nav button is harmless noise, but a
+    // MISSED nav item defeats the guard. Prefer semantic markup (role=tablist) for
+    // fully reliable harvesting; see docs/inventory-guard.md.
+    const SEL = 'a[href], [role="tab"], [role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], nav button, [role="navigation"] button, [role="tablist"] button, [class*="navtab" i] button, [class*="nav-tab" i] button, [class*="subnav" i] button, [class*="subtab" i] button, [class*="tabs" i] button';
+    return Array.from(document.querySelectorAll(SEL))
+        .filter(visible)
+        .map((el) => ({
+        tag: el.tagName.toLowerCase(),
+        role: (el.getAttribute('role') || '').toLowerCase(),
+        name: nameOf(el),
+        internalPath: el.tagName === 'A' ? internalPath(el) : null,
+    }));
+}
+const slug = (s) => s
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-+|-+$/g, '')
+    .slice(0, 60);
+/** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
+export function classifyInventory(raw) {
+    const items = new Map();
+    const add = (key, kind, label, href) => {
+        if (key && !items.has(key))
+            items.set(key, href ? { key, kind, label, href } : { key, kind, label });
+    };
+    for (const c of raw) {
+        if (c.tag === 'a' && c.internalPath) {
+            add(`route:${c.internalPath}`, 'link', c.name || c.internalPath, c.internalPath);
+        }
+        else if (c.name && c.role === 'tab') {
+            add(`tab:${slug(c.name)}`, 'tab', c.name);
+        }
+        else if (c.name && c.role.startsWith('menuitem')) {
+            add(`menuitem:${slug(c.name)}`, 'menuitem', c.name);
+        }
+        else if (c.name && c.tag === 'button') {
+            add(`nav-button:${slug(c.name)}`, 'nav-button', c.name);
+        }
+    }
+    return Array.from(items.values()).sort((a, b) => a.key.localeCompare(b.key));
+}
+/** Harvest a page's inventory: thin in-page collect + pure classify. */
+export async function harvestInventory(page) {
+    return classifyInventory(await page.evaluate(collectNavAffordances));
+}
+// ── pure diff / union / guard ───────────────────────────────────────────────────
+/** Union the per-surface inventories of a whole run into one reachable set. */
+export function unionInventory(perSurface) {
+    const byKey = new Map();
+    for (const map of perSurface) {
+        for (const item of map?.inventory ?? [])
+            if (!byKey.has(item.key))
+                byKey.set(item.key, item);
+    }
+    return Array.from(byKey.values()).sort((a, b) => a.key.localeCompare(b.key));
+}
+/** Base vs head reachable sets → what the UI newly offers / stopped offering. */
+export function diffInventory(base, head) {
+    const headKeys = new Set(head.map((i) => i.key));
+    const baseKeys = new Set(base.map((i) => i.key));
+    return {
+        added: head.filter((i) => !baseKeys.has(i.key)),
+        removed: base.filter((i) => !headKeys.has(i.key)),
+    };
+}
+/**
+ * The gate. Removals that aren't acknowledged in `allowed` (key -> reason) are
+ * unexplained — the caller fails on a non-empty result. An `allowed` key that
+ * isn't actually removed is a stale acknowledgement, returned separately so the
+ * ledger can't quietly rot (mirrors the `exclude` coverage guard).
+ */
+export function auditRemovals(delta, allowed = {}) {
+    const removedKeys = new Set(delta.removed.map((i) => i.key));
+    return {
+        unexplained: delta.removed.filter((i) => !(i.key in allowed)),
+        staleAllowances: Object.keys(allowed).filter((k) => !removedKeys.has(k)),
+    };
+}
+/**
+ * Run-level entry point: union both sides' per-surface `map.inventory`, diff, and
+ * audit removals. This is what a gate calls — pass every base map and every head
+ * map (the reachable set is the union across all surfaces). `unexplained` non-empty
+ * ⇒ the gate should fail; `staleAllowances` non-empty ⇒ prune the ledger.
+ */
+export function auditRunInventory(baseMaps, headMaps, allowed = {}) {
+    const delta = diffInventory(unionInventory(baseMaps), unionInventory(headMaps));
+    return { delta, ...auditRemovals(delta, allowed) };
+}

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>;
@@ -238,10 +247,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

@@ -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,
     };
 }
 /**
@@ -517,17 +519,28 @@ 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');
         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 +549,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 +561,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.6.0",
+  "version": "3.8.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",