styleproof 3.5.0 → 3.7.0

package/CHANGELOG.md

@@ -7,6 +7,61 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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
+
+- Crawl candidate collection collapses inherited-cursor subtrees to their
+  OUTERMOST clickable. `cursor` is an inherited CSS property, so a clickable card
+  makes every descendant compute `cursor: pointer`; each became its own candidate
+  even though clicking any of them just bubbles to the card's handler (the same
+  surface). Each redundant candidate paid a drive + verified reset — the dominant
+  cost of a large crawl. Measured on a 241-class design: base candidates 557 → 22,
+  whole coverage crawl ~40min → ~6min (240/241, unchanged). Semantic controls
+  nested in a clickable container are still kept.
+- `--until-covered` reaches deep coverage: it now terminates on the queue
+  draining (or full coverage), not a fixed "N surfaces without a new class"
+  plateau — a plateau cut the crawl off before a productive deep state (an
+  automation whose expandable run row is its last candidate) was ever swept.
+  Coverage mode also (a) prunes the queue to surfaces that add new render
+  vocabulary — a structural repeat like the ninth agent's identical dossier is
+  captured once but not re-drilled — and (b) uses the breadth-first queue rather
+  than the depth-first in-place descent, so distinct components are reached fast
+  and each drilled once via now-reliable resets. Measured on a 241-class design:
+  240/241 (the one gap a post-decision state reachable only with a setup step),
+  where a plateau-stopped crawl left the deep automation run-detail unmapped.
+
+### Fixed
+
+- Reset-replay to depth >= 2 no longer fails: the crawler's structural
+  fingerprint counted StyleProof's OWN injected hover-sink `<div>` (added during
+  a capture, so present when a state is captured in place but absent on a fresh
+  reset+replay). Every such reset failed its fingerprint verification, so any
+  surface reachable ONLY by re-driving from a deep state — a pairwise mode
+  combination like a tab's edit view — was silently lost. The fingerprint now
+  excludes the sink (and framework route-announcers). Measured: depth-2..5
+  resets went from all-fail to all-pass.
+
 ### Fixed
 
 - Report tables never show an equal-looking Before/After pair for a real diff.
@@ -20,23 +75,51 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
-- Control identity is now SEMANTIC, not positional: the driven-once dedup keys
-  on tag ancestry (no indices, no classes) + label + role — what stays stable
-  across every re-render — instead of nth-of-type selectors. Mode switches
-  re-render subtrees and re-mint positional selectors for the same logical
-  controls, which made every combination view refill the fresh-candidate pool
-  (a crawl inflated past 2,500 surfaces through that leak). Positional clones
-  with identical tag-path AND label (a repeated row's expand button) merge —
-  one is explored; distinctly-labeled controls stay distinct; anything hidden
-  behind a merge is still NAMED by the coverage verifier.
-- Family retries no longer compound: a state reached via a retry still explores
-  its genuinely-new UI, but never re-retries mode-switchers. Every PAIRWISE
-  combination of independent modes is captured (a tab's edit state, a decided
-  list's other tab); 3-way-and-deeper toggle products — which multiply surfaces
-  without new render vocabulary — are not walked. Observed live: an exhaustive
-  crawl inflated past 725 surfaces in the N-way product tail; the pairwise walk
-  covers the same vocabulary in a fraction of the states. Anything class-visible
-  only at deeper combination depth is still NAMED by the coverage verifier.
+- Crawl reset settle no longer waits on `networkidle`: it polls DOM-growth to
+  detect the mounted app (unchanged) and then waits for `document.fonts.ready`
+  specifically (fonts are part of the computed style the diff compares, so they
+  must be loaded — but that is the deterministic signal, cache-warm on repeat
+  loads). networkidle waited a 500ms idle window ON TOP of a cross-origin font
+  sheet that lingered ~1s per load with no bearing on readiness; since every
+  state reset re-navigates, that dominated crawl time. Measured: settle 911ms →
+  105ms per reset (~8.7x), whole-crawl surface rate ~5/min → ~17/min.
+
+- Crawl is now breadth-first (was depth-first): every shallow surface — nav
+  tabs, opened panels, the tabs inside a dossier — is exhausted before drilling
+  deeper. Depth-first starved breadth: one append-generator branch drilled past
+  depth 20 while sibling tabs sat unvisited, so real surfaces (an OAuth card, a
+  skills grid, a markdown editor) went uncaptured — measured live as 48 defined
+  classes never rendered across ~12 surfaces. Dedup is set-based, so order
+  changes only WHICH surface is found first, never the final set.
+- `maxDepth` default 1000 -> 16: exhaustive for real UI (nothing human-navigable
+  is 16 clicks from load) while terminating append-generator chains, whose every
+  appended node is a fresh tag-path identity. The coverage verifier still names
+  any class left unrendered, so a too-low cap fails loudly rather than lying.
+
+- The never-click guard now also covers state-mutating verbs (rotate,
+  provision, seal, regenerate, renew): mapping must not mutate, and a mutating
+  control that persists after its click re-labels its surroundings with fresh
+  data on every press — an unbounded mutation farm a crawl must not walk.
+  Observed live: credential-rotation cells minted new identities per press,
+  inflating a crawl past 470 surfaces at depth 23. Their render states are
+  seed-data territory (and anything unreached is named by the verifier).
+- Freshly-opened surfaces are swept IN PLACE (forward-drive), not only queued
+  for a later reset+replay. Reaching a surface by a forward click is reliable;
+  re-reaching it by reset is slow (a reset per candidate) and, at depth, starved
+  — a dossier's many filter combinations flood the queue and bury the deep
+  sweep, so an expanded run row inside an expanded job was captured 0 times
+  despite being reachable (now 29). The descent drives only fresh controls new
+  to the surface (excludes parent-present mode-switchers), so pairwise mode
+  coverage is unchanged and the lattice stays pairwise.
+
+### Added
+
+- `--until-covered`: stop the crawl as soon as every class the page's
+  stylesheets define has rendered (full coverage) or coverage stops improving
+  (no new class for a plateau of surfaces). Turns an exhaustive crawl into a
+  fast coverage check that stops once it has SEEN everything, instead of
+  enumerating every combinatorial surface that adds no new vocabulary. Opt-in;
+  exhaustive remains the default.
 
 ## [3.5.0] - 2026-07-02
 

package/bin/styleproof-capture.mjs

@@ -107,6 +107,7 @@ async function runCrawl() {
       resetStorage: opts.resetStorage,
       setup: setupSteps,
       dataStates: opts.dataStates,
+      stopWhenCovered: opts.untilCovered,
       workers: opts.workers,
       // each worker page in its OWN context, so storage resets can't interfere
       newPage: async () => (await browser.newContext()).newPage(),

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

@@ -56,6 +56,11 @@ export type CaptureUrlOptions = {
     /** crawl: exit non-zero unless every class the page's stylesheets define was
      *  rendered in at least one captured surface (default false — report only). */
     requireFullCoverage: boolean;
+    /** crawl: stop as soon as coverage is complete (every defined class seen) or
+     *  has converged (no new class for a plateau of surfaces). Turns the crawl
+     *  into a FAST coverage check that stops once it has seen everything, instead
+     *  of enumerating every combinatorial surface. Default false (exhaustive). */
+    untilCovered: boolean;
     /** crawl: JSON file of deterministic setup steps (login, unlock, seed input)
      *  run after every fresh navigation. See {@link loadSetupSteps}. */
     setupFile?: string;

package/dist/capture-url.js

@@ -31,6 +31,7 @@ const DEFAULTS = {
     maxStates: 100000,
     resetStorage: true,
     requireFullCoverage: false,
+    untilCovered: false,
     dataStates: true,
     workers: 4,
 };
@@ -71,6 +72,7 @@ const BOOL_FLAGS = {
     '--crawl': (o) => (o.crawl = true),
     '--no-reset-storage': (o) => (o.resetStorage = false),
     '--require-full-coverage': (o) => (o.requireFullCoverage = true),
+    '--until-covered': (o) => (o.untilCovered = true),
     '--data-states': (o) => (o.dataStates = true),
     '--no-data-states': (o) => (o.dataStates = false),
 };
@@ -119,6 +121,7 @@ export function parseCaptureUrlArgs(argv) {
         maxStates: DEFAULTS.maxStates,
         resetStorage: DEFAULTS.resetStorage,
         requireFullCoverage: DEFAULTS.requireFullCoverage,
+        untilCovered: DEFAULTS.untilCovered,
         setupFile: undefined,
         dataStates: DEFAULTS.dataStates,
         workers: DEFAULTS.workers,

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-surfaces.d.ts

@@ -90,6 +90,14 @@ export type SurfaceCrawlOptions = {
      *  requests stalled — the skeleton) and `error` (data requests fulfilled with
      *  a 500). Default true; states that render identically to base are skipped. */
     dataStates?: boolean;
+    /** Coverage-oriented termination: stop as soon as every class the page's
+     *  stylesheets define has been rendered (full coverage) OR coverage stops
+     *  improving (no new class for a plateau of surfaces — it has converged short
+     *  of full, and the rest is dead CSS or a genuinely-gated state). Off by
+     *  default (exhaustive: map every surface). On, the crawl is a fast coverage
+     *  check — it stops the moment it has SEEN everything, instead of enumerating
+     *  every combinatorial surface that adds no new vocabulary. */
+    stopWhenCovered?: boolean;
     /** Throttle: recursion depth into opened surfaces (base = 0). Default: unbounded. */
     maxDepth: number;
     /** Throttle: fresh controls driven per state. Default: unbounded — try them all. */

package/dist/crawl-surfaces.js

@@ -7,7 +7,14 @@ import { detectViewportWidths } from './breakpoints.js';
 export const CRAWL_DEFAULTS = {
     height: 900,
     screenshots: true,
-    maxDepth: 1000,
+    // ponytail: depth 16 is exhaustive for real UI — no human-navigable surface
+    // is 16 clicks from load. Past that you're not finding surfaces, you're
+    // riding an append-generator (a composer that adds a row per click) whose
+    // every appended node is a fresh tag-path identity, so it recurses forever.
+    // The cap terminates those chains; the coverage verifier still NAMES any
+    // class left unrendered, so a too-low cap fails loudly rather than lying.
+    // Raise with --max-depth if a design genuinely nests deeper.
+    maxDepth: 16,
     maxActionsPerState: 100000,
     maxStates: 100000,
     resetStorage: true,
@@ -41,7 +48,7 @@ function deriveKey(steps, used) {
 /* c8 ignore start */ // fallow-ignore-next-line complexity
 function collectClickable() {
     const SEMANTIC = 'button,summary,[role="button"],[role="tab"],[role="menuitem"],[role="combobox"],select,form';
-    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop)\b/i;
+    const DANGER = /\b(delete|remove|destroy|logout|log ?out|sign ?out|publish|deploy|pay|purchase|buy|checkout|archive|disconnect|revoke|reset|wipe|drop|rotate|provision|seal|regenerate|renew)\b/i;
     const esc = (v) => CSS.escape(v);
     const quote = (v) => JSON.stringify(v);
     const visible = (el) => {
@@ -99,7 +106,28 @@ function collectClickable() {
         if (pool.has(el))
             continue;
         const cursor = getComputedStyle(el).cursor;
-        if (cursor === 'pointer' || cursor === 'grab')
+        if (cursor !== 'pointer' && cursor !== 'grab')
+            continue;
+        // `cursor` is an INHERITED property: a clickable card makes every descendant
+        // compute cursor:pointer, and clicking any descendant just bubbles to the
+        // card's own handler — the SAME surface. Left unchecked, a card with N
+        // children becomes N+1 candidates, each paying a drive + verified reset to
+        // map one surface (the dominant cost of a large crawl). Add only the
+        // OUTERMOST clickable in an inherited-cursor subtree: skip when an ancestor
+        // is already a candidate. Semantic controls (button, a, [role]) are seeded
+        // above and skipped by the guard at the top of the loop, so a real button
+        // nested inside a clickable card is never dropped. (querySelectorAll walks
+        // document order, so an ancestor is always pooled before its descendants.)
+        let anc = el.parentElement;
+        let nested = false;
+        while (anc && anc !== document.body) {
+            if (pool.has(anc)) {
+                nested = true;
+                break;
+            }
+            anc = anc.parentElement;
+        }
+        if (!nested)
             pool.add(el);
     }
     // Neutral text inputs are typed automatically with a deterministic value —
@@ -203,6 +231,17 @@ function domShape() {
     for (const el of document.body.getElementsByTagName('*')) {
         if (SKIP.has(el.tagName))
             continue;
+        // Skip non-page artifacts that pollute the fingerprint: StyleProof's own
+        // injected hover-sink (added by a capture, so present when a state is
+        // captured in place but NOT on a fresh load) and framework route-announcers.
+        // Counting them made a state's in-place fingerprint differ from its
+        // reset+replay fingerprint, so every reset to depth >= 2 failed verification
+        // (and the same pollution split dedup, capturing one surface as two). They
+        // are not part of the page.
+        if (el.hasAttribute('data-styleproof-hover-sink'))
+            continue;
+        if (el.tagName === 'NEXT-ROUTE-ANNOUNCER' || el.id === '__next-route-announcer__')
+            continue;
         add(el);
     }
     return { shape: parts.join('\n'), elements: parts.length, classes: [...classes] };
@@ -267,15 +306,27 @@ async function settleDom(page, maxMs = 1200) {
  *  non-trivial. Generic — no app-specific selector needed, so a bare crawl of a
  *  Babel/React/Vue page that boots after `load` still captures the mounted UI. */
 async function waitSettled(page) {
-    await page.waitForLoadState('networkidle').catch(() => { });
+    // DOM-growth settle is the PRIMARY readiness signal — it detects an
+    // async-mounted app (the DOM stops growing and is non-trivial) without an
+    // app-specific selector, and it also catches fetch-painted content (that
+    // grows the DOM). We deliberately do NOT gate on networkidle: it waits a
+    // 500ms idle window ON TOP of any lingering request, and a single cross-origin
+    // asset — a Google-Fonts stylesheet — keeps the network "busy" ~1s per load
+    // with no bearing on readiness. gotoFresh runs once per state (plus per
+    // retry), so that dominated crawl time (measured: ~995ms of every ~1531ms
+    // reset). Instead we wait for FONTS specifically — they ARE part of the
+    // computed style the diff compares, so they must be loaded before capture,
+    // but document.fonts.ready is the deterministic signal (and resolves from the
+    // page's cache on repeat loads, so it's ~free after the first).
     let prev = -1;
     for (let i = 0; i < 40; i++) {
         const n = await page.evaluate(() => document.body.getElementsByTagName('*').length);
         if (n > 5 && n === prev)
-            return;
+            break;
         prev = n;
         await page.waitForTimeout(100);
     }
+    await page.evaluate(() => document.fonts.ready.then(() => true)).catch(() => { });
 }
 /**
  * Load the URL from a clean slate (storage cleared by the init script armed in
@@ -440,13 +491,39 @@ async function record(page, opts, newPath, depth, fp, st, sink, retryOnly = fals
     const key = deriveKey(newPath, st.used);
     const surface = { key, depth, path: newPath, elements: fp.elements };
     st.surfaces.push(surface);
+    let addsVocab = false;
+    for (const c of fp.classes)
+        if (!st.classes.has(c)) {
+            st.classes.add(c);
+            addsVocab = true;
+        }
     // Children buffer in the sweep's sink and enter the shared queue only when the
     // parent's sweep completes — family retry reads the parent's changer registry,
     // which is only complete then. (Serial mode passes st.queue directly.)
-    sink.push({ path: newPath, depth, sig: fp.sig, retryOnly, viaRetry });
-    for (const c of fp.classes)
-        st.classes.add(c);
-    await captureAndReport(page, opts, surface, st);
+    //
+    // COVERAGE-GUIDED QUEUE PRUNING: in --until-covered mode, a surface that adds
+    // NO new render vocabulary is a structural repeat (the ninth agent's dossier,
+    // identical to the first) — don't queue it for a sweep, because its subtree is
+    // the same repeats and contributes nothing to coverage. This is what turns the
+    // exhaustive breadth-first crawl into a FAST coverage check: the queue drains
+    // to the few distinct components, each still drilled to depth (its own new
+    // vocabulary keeps it queued) via now-reliable resets. Base (depth 0) always
+    // seeds. Exhaustive mode (default) queues everything, so the surface-by-surface
+    // diff still sees every state.
+    const keep = !opts.stopWhenCovered || addsVocab || depth === 0;
+    if (keep) {
+        sink.push({ path: newPath, depth, sig: fp.sig, retryOnly, viaRetry });
+    }
+    // Skip the expensive style-map capture (getComputedStyle over every element,
+    // per width) for coverage-redundant surfaces: in --until-covered mode a surface
+    // that adds no vocabulary needs no map — its classes were already counted from
+    // the fingerprint above — so paying the capture is pure waste. This is the
+    // difference between a fast coverage check and re-capturing hundreds of
+    // structural repeats. Distinct (vocab-adding) surfaces are still captured, so
+    // the run leaves a usable map set behind.
+    if (keep) {
+        await captureAndReport(page, opts, surface, st);
+    }
 }
 /** Capture the current page as `surface` at every width and report the outcome. */
 async function captureAndReport(page, opts, surface, st) {
@@ -478,7 +555,7 @@ async function tryInPlace(page, c) {
 }
 /** Drive one candidate from where the page stands. Returns whether the page is
  *  still in the swept state (no-op click) and whether the action was a skip. */
-async function driveCandidate(page, opts, entry, c, st, sink, viaRetry) {
+async function driveCandidate(page, opts, entry, c, st, sink, viaRetry, presentIds = new Set()) {
     // (retry-only lineage is inherited: a consumed state's descendants can also
     // only be mode-switch views, never fresh-candidate exploration.)
     const outcome = await tryInPlace(page, c);
@@ -509,7 +586,41 @@ async function driveCandidate(page, opts, entry, c, st, sink, viaRetry) {
         reason: c.reason,
         ...(c.value ? { value: c.value } : {}),
     };
-    await record(page, opts, [...entry.path, step], entry.depth + 1, fp, st, sink, entry.retryOnly || !persists, viaRetry);
+    const childPath = [...entry.path, step];
+    const childRetryOnly = entry.retryOnly || !persists;
+    await record(page, opts, childPath, entry.depth + 1, fp, st, sink, childRetryOnly, viaRetry);
+    // DESCEND IN PLACE. We are standing in the surface this click just opened,
+    // reached by a reliable forward click. Sweep its OWN fresh controls now, while
+    // we are here, rather than leaving it for the queued entry to re-reach by
+    // reset+replay. In EXHAUSTIVE mode this is the win: it maps a deep branch (an
+    // expanded run inside an expanded automation) while the page is already there,
+    // instead of via a fragile deep replay. The queued entry still executes for
+    // family-retry (pairwise) coverage; global `tried` means its fresh list is
+    // already empty here, so this does not double-drive.
+    //
+    // But descent is DEPTH-FIRST: it drills the first candidate's whole subtree
+    // before the base sweep reaches the next candidate, so a page whose distinct
+    // vocabulary lives across many components (a roster of dossiers) covers slowly.
+    // In --until-covered mode we therefore SKIP the in-place descent and let the
+    // breadth-first queue + coverage-guided pruning reach every component fast and
+    // drill each once — now that resets are reliable, the queue reaches depth too.
+    if (!opts.stopWhenCovered && persists && entry.depth + 1 < opts.maxDepth) {
+        const child = {
+            path: childPath,
+            depth: entry.depth + 1,
+            sig: fp.sig,
+            retryOnly: childRetryOnly,
+            viaRetry,
+        };
+        // Exclude controls that were ALSO present in the parent (mode-switchers,
+        // shared chrome): those are breadth, owned by the queued family-retry.
+        // Descend only into controls genuinely NEW to this surface — a run row that
+        // exists only after the job expanded — which is exactly the deep nested UI
+        // the reset-replay path starves.
+        await sweepCandidatesHere(page, opts, child, st, sink, /* freshOnly */ true, presentIds).catch(() => {
+            /* fail-soft: the surface was already captured; deeper descent is best-effort */
+        });
+    }
     return { inState: false, skipped: false };
 }
 /**
@@ -546,19 +657,36 @@ function familyRetries(entry, all, st) {
  *  global chrome would otherwise starve a deep surface's own controls; the
  *  throttle applies to fresh ones), then the parent's persistent mode-switchers
  *  re-tried in THIS sibling mode. A state reached through a consuming action
- *  collects NO fresh candidates — see QueueEntry.retryOnly. */
-function sweepWorkList(entry, all, opts, st) {
-    const fresh = entry.retryOnly ? [] : all.filter((c) => !st.tried.has(c.identity)).slice(0, opts.maxActionsPerState);
+ *  collects NO fresh candidates — see QueueEntry.retryOnly.
+ *
+ *  `freshOnly` drops the family-retries: the in-place descent of a
+ *  freshly-opened surface explores its own new UI (DEPTH), but must NOT re-apply
+ *  the parent's mode-switchers — that is the pairwise BREADTH, owned by the
+ *  queued sweep. Re-applying them while descending would compound modes into
+ *  N-way products (the very thing "retries don't compound" prevents). */
+function sweepWorkList(entry, all, opts, st, freshOnly = false, excludeIds = new Set()) {
+    const fresh = entry.retryOnly
+        ? []
+        : all.filter((c) => !st.tried.has(c.identity) && !excludeIds.has(c.identity)).slice(0, opts.maxActionsPerState);
     return [
         ...fresh.map((c) => ({ c, retry: false })),
-        ...familyRetries(entry, all, st).map((c) => ({ c, retry: true })),
+        ...(freshOnly ? [] : familyRetries(entry, all, st).map((c) => ({ c, retry: true }))),
     ];
 }
-async function sweepState(page, opts, entry, st, sink) {
-    if (!(await resetToState(page, opts, entry.path, entry.sig)))
-        return { tried: 0, skipped: 0 };
+/** Drive one state's work list from where the page ALREADY stands (no reset). A
+ *  no-op click leaves the page in the state and the loop continues; a
+ *  state-changing click drives the child in place (see driveCandidate) and then
+ *  a verified reset returns here before the next candidate. Split out from
+ *  sweepState so driveCandidate can call it to DESCEND a freshly-opened surface
+ *  in place — reaching that surface via a forward click is reliable, so its deep
+ *  descendants are captured on the first visit instead of via a later reset. */
+async function sweepCandidatesHere(page, opts, entry, st, sink, freshOnly = false, excludeIds = new Set()) {
     const all = await page.evaluate(collectClickable).catch(() => []);
-    const work = sweepWorkList(entry, all, opts, st);
+    const work = sweepWorkList(entry, all, opts, st, freshOnly, excludeIds);
+    // Controls present HERE — passed to each child's in-place descent as its
+    // exclude set, so the descent skips this surface's mode-switchers/chrome and
+    // only drills genuinely new nested UI.
+    const presentIds = new Set(all.map((c) => c.identity));
     let tried = 0;
     let skipped = 0;
     let inState = true;
@@ -577,13 +705,18 @@ async function sweepState(page, opts, entry, st, sink) {
             continue;
         }
         tried++;
-        const r = await driveCandidate(page, opts, entry, c, st, sink, retry);
+        const r = await driveCandidate(page, opts, entry, c, st, sink, retry, presentIds);
         inState = r.inState;
         if (r.skipped)
             skipped++;
     }
     return { tried, skipped };
 }
+async function sweepState(page, opts, entry, st, sink) {
+    if (!(await resetToState(page, opts, entry.path, entry.sig)))
+        return { tried: 0, skipped: 0 };
+    return sweepCandidatesHere(page, opts, entry, st, sink);
+}
 /** Capture one synthetic data state of the entry page (its data requests stalled
  *  or failed) in place, deduped and coverage-counted like any surface — but never
  *  queued: a stalled app is not a state to crawl deeper from. */
@@ -624,7 +757,7 @@ async function recordDataState(page, opts, mode, st) {
  * crawl — dedup sets are shared and mutated synchronously — only dup-key
  * suffix attribution can vary with timing.
  */
-async function runPool(primary, opts, st, counters) {
+async function runPool(primary, opts, st, counters, defined = []) {
     const target = Math.max(1, opts.workers ?? 1);
     const pages = [primary];
     while (opts.newPage && pages.length < target) {
@@ -633,11 +766,39 @@ async function runPool(primary, opts, st, counters) {
             await armResetStorage(extra);
         pages.push(extra);
     }
+    // Coverage-oriented early stop (opt-in): the moment every defined class has
+    // been SEEN, stop — the rest of the queue is redundant for a coverage check.
+    // We do NOT plateau-stop on "N surfaces without a new class": a productive
+    // deep state (an automation whose expandable run row is its last candidate)
+    // adds its vocabulary only after many no-new siblings, so a plateau cuts the
+    // crawl off before that state's sweep even starts. Termination instead comes
+    // from the queue draining — and it drains fast because coverage-guided pruning
+    // (see record) never queues a structural repeat. `cover.every` runs only when
+    // the class count actually grows, so this is cheap.
+    const cover = opts.stopWhenCovered && defined.length > 0 ? defined : null;
+    let prevSize = st.classes.size;
+    let covered = false;
+    const converged = () => {
+        if (!cover)
+            return false;
+        if (!covered && st.classes.size > prevSize) {
+            prevSize = st.classes.size;
+            if (cover.every((c) => st.classes.has(c)))
+                covered = true;
+        }
+        return covered;
+    };
     let active = 0;
     await new Promise((resolve) => {
         const pump = () => {
-            while (pages.length > 0 && st.queue.length > 0 && st.surfaces.length < opts.maxStates) {
-                const entry = st.queue.pop(); // LIFO → depth-first
+            while (pages.length > 0 && st.queue.length > 0 && st.surfaces.length < opts.maxStates && !converged()) {
+                const entry = st.queue.shift(); // FIFO → breadth-first: exhaust every
+                // shallow surface (nav tabs, opened panels — where distinct UI lives)
+                // before drilling. Depth-first starves breadth: one append-generator
+                // branch drills to depth 20+ while sibling tabs sit unpopped, so real
+                // surfaces (an OAuth card, a skills grid) go uncaptured. Dedup is
+                // set-based, so order never changes WHAT is found — only that shallow
+                // is found first, which is what full coverage needs.
                 if (entry.depth >= opts.maxDepth)
                     continue;
                 const worker = pages.pop();
@@ -658,7 +819,7 @@ async function runPool(primary, opts, st, counters) {
                     pump();
                 });
             }
-            if (active === 0 && (st.queue.length === 0 || st.surfaces.length >= opts.maxStates))
+            if (active === 0 && (st.queue.length === 0 || st.surfaces.length >= opts.maxStates || converged()))
                 resolve();
         };
         pump();
@@ -712,7 +873,7 @@ async function discover(page, opts) {
         await recordDataState(page, opts, 'error', st);
     }
     const counters = { tried: 0, skipped: 0 };
-    await runPool(page, opts, st, counters);
+    await runPool(page, opts, st, counters, defined);
     const missing = defined.filter((c) => !st.classes.has(c)).sort();
     return {
         surfaces: st.surfaces,

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/package.json

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