styleproof 3.21.0 → 4.0.1

package/bin/styleproof-capture.mjs

@@ -20,6 +20,7 @@ import { chromium } from '@playwright/test';
 import { isHelpArg, showHelpAndExit } from '../dist/cli-errors.js';
 import { UsageError, parseCaptureUrlArgs, runCaptureUrl, loadSetupSteps } from '../dist/capture-url.js';
 import { crawlAndCapture } from '../dist/crawl-surfaces.js';
+import { writeCaptureManifest } from '../dist/map-store.js';
 
 const COMMAND = 'styleproof-capture';
 
@@ -122,6 +123,9 @@ async function runCrawl() {
         console.log(`  ${'·'.repeat(s.depth)}${s.key} (${s.elements} elements)${ok ? '' : ' — CAPTURE FAILED'}`),
     };
     const report = await crawlAndCapture(page, crawlOpts);
+    // Stamp a manifest so a two-directory diff against this crawl output has the
+    // same-environment guard on both sides (v4 refuses a manifest-less side).
+    writeCaptureManifest({ dir: opts.out, screenshots: opts.screenshots });
     console.log(
       `✓ ${report.captured}/${report.surfaces.length} surface(s) × ${crawlOpts.widths.length} width(s) → ${opts.out}  ` +
         `(${report.actionsTried} actions tried, ${report.skipped} skipped${report.failed.length ? `, ${report.failed.length} capture-failed` : ''})`,

package/bin/styleproof-diff.mjs

@@ -44,6 +44,8 @@ import {
   DEFAULT_REMOTE,
   assertCompatibleMapDirs,
   cleanupCachedCaptureDirs,
+  manifestlessError,
+  manifestlessSide,
   resolveCachedCaptureDirs,
 } from '../dist/map-store.js';
 import {
@@ -53,8 +55,9 @@ import {
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
-import { readInventories, surfaceElementPaths } from '../dist/capture.js';
+import { readInventories, readResidue, surfaceElementPaths } from '../dist/capture.js';
 import { auditRunInventory, readAckFile } from '../dist/inventory.js';
+import { auditRunResidue, readResidueAckFile } from '../dist/data-residue.js';
 import { auditCoverage, auditDeterminism, COVERAGE_LEDGER } from '../dist/coverage.js';
 import { isMapFile } from '../dist/map-store.js';
 
@@ -114,6 +117,70 @@ function printInventoryAudit(audit) {
   return unexplained.length;
 }
 
+// ── data-residue guard (gate by default) ─────────────────────────────────────────
+// A data-boundary request (matching `replayUrl`) that FAILED during capture means the
+// captured state embedded that endpoint's fallback branch — its response-driven states
+// are unproven (issue #205). Residue is recorded + warned at capture time; here the diff
+// SURFACES it, and — unless the head bundle opted down to `dataResidue: 'warn'` — an
+// unacknowledged failing endpoint BLOCKS (exit 1). Acknowledge intentional ones in
+// styleproof.data-residue.json. (Bundles captured before this field existed read as warn.)
+
+// `key -> reason` acknowledged failing endpoints. Malformed JSON fails loud (exit 2),
+// like the inventory ack file, so a broken file can't silently un-acknowledge a failure.
+function loadAcknowledgedResidue() {
+  try {
+    return readResidueAckFile();
+  } catch (e) {
+    console.error(`${COMMAND}: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+// Audit the HEAD bundle's residue against the ack ledger, carrying whether the head
+// ledger armed the gate. Returns null when no captured map carried residue AND the
+// gate wasn't armed — so a clean healthy run prints/gates nothing (byte-identical).
+function readResidueAudit(dirB, armed) {
+  const headResidue = readResidue(dirB);
+  if (!armed && !headResidue.some((m) => m.dataResidue?.length)) return null;
+  const acknowledged = loadAcknowledgedResidue();
+  return { acknowledged, ...auditRunResidue(headResidue, acknowledged, armed) };
+}
+
+// Print the Data-residue section; return the count of UNACKNOWLEDGED failing endpoints
+// that BLOCK (only when the gate is armed). No-op/0 when there was nothing to audit.
+/** One line per residue entry: acknowledged entries show their reason; the rest are
+ *  marked ✗ (armed — will block) or ⚠ (warn mode). */
+function residueLine(r, ackReason, armed) {
+  if (ackReason !== undefined) return `  ${r.surface} · ${r.endpoint} (${r.reason}) — acknowledged: ${ackReason}`;
+  return `  ${armed ? '✗ ' : '⚠ '}${r.surface} · ${r.endpoint} (${r.reason})${armed ? ', unacknowledged' : ''}`;
+}
+
+/** The action footer: the gate (default) names the remedy; warn mode is the opt-out. */
+function residueFooter(armed, unacknowledgedCount) {
+  if (!unacknowledgedCount) return null;
+  return armed
+    ? `  → ${unacknowledgedCount} unacknowledged failing endpoint(s): fixture each (page.route / liveStates), acknowledge intentional ones in styleproof.data-residue.json {"<key>":"<why>"}, or opt down with \`dataResidue: "warn"\` in the capture spec.`
+    : '  → recorded and warned (dataResidue: "warn" — the opt-out). Remove it to restore the default gate that BLOCKS on these.';
+}
+
+function printResidueAudit(audit) {
+  if (!audit) return 0;
+  const { residue, unacknowledged, staleAcknowledgements, armed } = audit;
+  if (!residue.length && !staleAcknowledgements.length) {
+    console.log('\n🩹 Data residue: no failing data-boundary request during capture');
+    return 0;
+  }
+  console.log('\n🩹 Data residue (data-boundary requests that FAILED during capture — fallback branch captured):');
+  for (const r of residue) console.log(residueLine(r, audit.acknowledged[r.key], armed));
+  for (const k of staleAcknowledgements)
+    console.log(`  ⚠ stale acknowledgement (endpoint no longer failing/present): ${k}`);
+  const footer = residueFooter(armed, unacknowledged.length);
+  if (footer) console.log(footer);
+  // Only an ARMED gate blocks; warn-mode surfaces without gating. A stale acknowledgement
+  // always blocks when armed, so the ledger can't rot (mirrors the `exclude` guard).
+  return armed ? unacknowledged.length + staleAcknowledgements.length : 0;
+}
+
 // ── coverage provenance (the completeness basis of a green) ──────────────────────
 // The head bundle carries a coverage ledger (the declared registry). The gate audits
 // the ACTUALLY-captured surfaces against it, so "clean" states its basis — complete vs
@@ -268,8 +335,13 @@ let result;
 let inventoryAudit = null;
 let coverageVerdict = null;
 let determinismVerdict = null;
+let residueAudit = null;
 let surfacePaths = new Map();
 try {
+  // v4: a side without a manifest is unsupported — the same-environment guard can't be
+  // enforced, so refuse (exit 2 via the catch below) rather than compare on false footing.
+  const manifestless = manifestlessSide(dirA, dirB);
+  if (manifestless) throw new Error(manifestlessError(manifestless));
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
   // Read inventory + the certification ledgers here, while the (possibly cached/restored)
@@ -279,6 +351,9 @@ try {
   const headLedger = readLedger(dirB);
   coverageVerdict = auditCoverage(capturedSurfaceKeys(dirB), headLedger);
   determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
+  // Data-residue: the head bundle's failing data endpoints, gated only if its ledger
+  // armed `dataResidue: 'gate'`. Same "read while the dirs exist" rule as the ledgers.
+  residueAudit = readResidueAudit(dirB, headLedger?.dataResidue === 'gate');
   // Element-path sets per surface, for the shared-chrome tier — same "read while
   // the dirs exist" rule as the ledgers above.
   surfacePaths = surfaceElementPaths(dirA, dirB);
@@ -375,6 +450,7 @@ if (chrome.length) {
 for (const cg of rest) printGroup(cg);
 
 const invRemovals = printInventoryAudit(inventoryAudit);
+const residueFails = printResidueAudit(residueAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
 const determinismFails = printDeterminismVerdict(determinismVerdict);
 
@@ -410,6 +486,16 @@ if (jsonOut) {
                 inventoryNote:
                   'no captured map carried an inventory — set `inventory: true` in the capture spec to arm the navigable-removal gate',
               }),
+          // Additive data-residue field — the head bundle's failing data endpoints, parallel
+          // to inventory. `null` when nothing failed and the gate wasn't armed. `armed` says
+          // whether `unacknowledged` blocks; `blocking` is the CI-gating count.
+          dataResidue: residueAudit && {
+            armed: residueAudit.armed,
+            failing: residueAudit.residue.map((r) => r.key),
+            unacknowledged: residueAudit.unacknowledged.map((r) => r.key),
+            staleAcknowledgements: residueAudit.staleAcknowledgements,
+            blocking: residueFails,
+          },
         },
         null,
         2,
@@ -427,17 +513,21 @@ const newSurfaces = surfaces.filter((s) => s.missing).length;
 const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
+// residueFails counts unacknowledged failing endpoints AND stale acknowledgements (both gate).
+const resNote = residueFails ? ` + ${residueFails} data-residue gate failure(s) (unacknowledged or stale)` : '';
 const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
 const detNote = determinismFails ? ' + determinism unproven' : '';
-const clean = total === 0 && invRemovals === 0 && !coverageFails && !determinismFails;
+const clean = total === 0 && invRemovals === 0 && residueFails === 0 && !coverageFails && !determinismFails;
 console.log(
   clean
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${covNote}${detNote}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${resNote}${covNote}${detNote}`,
 );
 // 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals, an
-// incomplete coverage registry, or an unproven-determinism capture), 3 = only new surfaces
-// (no baseline). 2 = usage/capture error.
-process.exit(total > 0 || invRemovals > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0);
+// unacknowledged failing data endpoint under an armed residue gate, an incomplete coverage
+// registry, or an unproven-determinism capture), 3 = only new surfaces (no baseline). 2 = usage.
+process.exit(
+  total > 0 || invRemovals > 0 || residueFails > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0,
+);

package/bin/styleproof-init.mjs

@@ -19,13 +19,19 @@
  *     never disturbed or accidentally reused.
  *   - .github/workflows/styleproof.yml: restores reusable maps from the
  *     styleproof-maps branch and only captures in CI when the maps are missing.
+ *   - .github/workflows/styleproof-approve.yml: the issue_comment handler that
+ *     flips the StyleProof status when a reviewer ticks "Approve all changes".
+ *     The report workflow runs with `require-approval: true`, so without this the
+ *     approval checkbox is inert. GitHub only runs issue_comment workflows from the
+ *     default branch, so it takes effect once the init PR merges.
  *
  * Idempotent: re-running never overwrites an existing spec (use --force) and
- * never touches an existing app playwright.config.ts. Exit 0 = done (or nothing
- * to do), 2 = usage error.
+ * never touches an existing app playwright.config.ts or an existing workflow.
+ * Exit 0 = done (or nothing to do), 2 = usage error.
  */
 import fs from 'node:fs';
 import path from 'node:path';
+import { fileURLToPath } from 'node:url';
 // Import from the leaf module, not the barrel: styleproof-init only scaffolds
 // files and never captures. Pulling `../dist/index.js` here dragged the whole
 // library — capture, crawler, report, and six Playwright-importing modules —
@@ -53,6 +59,8 @@ What it writes:
     the two diverge. Otherwise it writes one sample surface + a commented guard block.
   - playwright.styleproof.config.ts, a dedicated production-build Playwright config
   - .github/workflows/styleproof.yml, a cache-first PR report workflow
+  - .github/workflows/styleproof-approve.yml, the "Approve all changes" gate
+    (active once merged to your default branch)
 
 After running, build and upload this commit's map outside CI when possible:
   npx styleproof-map
@@ -549,6 +557,65 @@ if (ci.wrote) {
   console.log(`${CI_PATH} already exists — left untouched`);
 }
 
+// Approval gate — the issue_comment handler that flips the StyleProof status when a
+// reviewer ticks "Approve all changes". The report workflow above runs with
+// `require-approval: true`, so this is what makes the checkbox live; without it the
+// gate can never go green. It's a static workflow (no package-manager wiring), so we
+// copy the packaged example verbatim rather than regenerate it. GitHub only runs
+// issue_comment workflows from the DEFAULT branch, so it activates when the init PR
+// merges — writing it to the feature branch now is correct and harmless.
+const APPROVE_PATH = '.github/workflows/styleproof-approve.yml';
+const approveSource = path.join(
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
+  'example',
+  'styleproof-approve.yml',
+);
+let approveWorkflow;
+try {
+  approveWorkflow = fs.readFileSync(approveSource, 'utf8');
+} catch {
+  // Packaged example missing (unexpected) — don't abort the rest of init.
+  console.warn(`could not read the approval workflow template at ${approveSource} — skipped`);
+}
+if (approveWorkflow !== undefined) {
+  const approve = writeFileSafe(APPROVE_PATH, approveWorkflow);
+  if (approve.wrote) {
+    touched.push(APPROVE_PATH);
+    console.log(`created ${APPROVE_PATH} (approval gate — active once merged to your default branch)`);
+    wroteSomething = true;
+  } else {
+    console.log(`${APPROVE_PATH} already exists — left untouched`);
+  }
+}
+
+// Pre-push publish hook — the default fast path. Capture locally at push time and
+// publish to the SHA-keyed styleproof-maps branch; CI restores by SHA and stays
+// report-only. Maps are NEVER committed to the PR branch: a shared tracked map path
+// shows up in every PR's changed files and forces cross-PR rebases on each merge.
+const HOOK = `#!/bin/sh
+# StyleProof pre-push: capture this commit's map and publish it to the
+# styleproof-maps branch, so CI restores it and reports without a browser.
+# Maps never get committed to the PR branch.
+# Skip (e.g. a docs-only push): STYLEPROOF_SKIP_CAPTURE=1 git push
+set -e
+[ "\${STYLEPROOF_SKIP_CAPTURE:-}" = "1" ] && exit 0
+${PM.exec(`styleproof-map --spec ${specPath}`)}
+${PM.exec('styleproof-diff')} || true # advisory: show drift before CI does
+`;
+const hookDir = fs.existsSync('.husky') ? '.husky' : '.githooks';
+const hookPath = path.join(hookDir, 'pre-push');
+const hook = writeFileSafe(hookPath, HOOK);
+if (hook.wrote) {
+  fs.chmodSync(hookPath, 0o755);
+  touched.push(hookPath);
+  console.log(`created ${hookPath} (pre-push capture → publish; maps never land on the PR branch)`);
+  if (hookDir === '.githooks') console.log('  activate with: git config core.hooksPath .githooks');
+  wroteSomething = true;
+} else {
+  console.log(`${hookPath} already exists — left untouched`);
+}
+
 if (touched.length) {
   // State exactly what init wrote, and — because adopters have blamed init for the
   // `styleproof` entry their package manager's `install` added — say plainly that it
@@ -560,11 +627,12 @@ if (touched.length) {
 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 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.');
+console.log('  2. The pre-push hook captures each pushed commit into .styleproof/ and publishes');
+console.log('     the bundle to the styleproof-maps branch; CI restores it by SHA and generates');
+console.log('     the report without a browser. Maps never get committed to the PR branch.');
+console.log('     Skip a push that cannot affect render: STYLEPROOF_SKIP_CAPTURE=1 git push');
+console.log('  3. Merge this PR. The approval workflow only runs from your default branch, so');
+console.log('     the "Approve all changes" checkbox goes live once styleproof-approve.yml is there.');
 
 if (!wroteSomething) console.log('\nnothing to write — project already scaffolded.');
 process.exit(0);

package/bin/styleproof-map.mjs

@@ -254,11 +254,19 @@ function runVariantCrawl(env) {
 }
 
 const targetDir = path.join(baseDir, dir);
+// Sample the tree state the capture is ABOUT to render, so the manifest can bind the
+// map to it. A capture runs for minutes; if the source is edited or HEAD moves in that
+// window, the map renders one state but would otherwise be stamped clean@post-HEAD and
+// published as the authoritative map for a SHA it never rendered — a stale map every
+// future diff against that SHA silently trusts as a false green.
 let dirtyBeforeCapture;
+let headBeforeCapture;
 try {
   dirtyBeforeCapture = workingTreeDirty(process.cwd());
+  headBeforeCapture = currentGitSha(process.cwd());
 } catch {
   dirtyBeforeCapture = false;
+  headBeforeCapture = undefined;
 }
 
 if (restore) {
@@ -329,21 +337,27 @@ if (status === 0) {
     );
     process.exit(status);
   }
+  // Bind the map to the commit it actually started rendering (headBeforeCapture), not a
+  // HEAD that may have moved mid-capture. `--sha` still wins for callers that know better.
+  const manifestSha = sha || headBeforeCapture || 'local';
+  // Re-check the tree AFTER capture (ignoring the maps this run just wrote): if the source
+  // was edited, or HEAD moved, during the capture window, the map↔SHA binding is a lie —
+  // mark it dirty so publishMapBundle refuses to push a stale map into the SHA-keyed store.
+  let dirty = dirtyBeforeCapture;
+  try {
+    const rel = path.relative(process.cwd(), targetDir) || targetDir;
+    const headAfter = currentGitSha(process.cwd(), env);
+    if (workingTreeDirty(process.cwd(), rel) || (headBeforeCapture && headAfter !== headBeforeCapture)) dirty = true;
+  } catch {
+    // git unreadable now — keep the pre-capture verdict rather than guess
+  }
   try {
-    let manifestSha = sha || undefined;
-    if (!manifestSha) {
-      try {
-        manifestSha = currentGitSha(process.cwd(), env);
-      } catch {
-        manifestSha = 'local';
-      }
-    }
     const manifest = writeMapManifest({
       dir: targetDir,
       spec,
       sha: manifestSha,
       screenshots: screenshots !== '0',
-      dirty: dirtyBeforeCapture,
+      dirty,
       env,
     });
     console.error(`styleproof-map: wrote ${targetDir} for ${manifest.sha.slice(0, 12)} (${manifest.compatibilityKey})`);

package/bin/styleproof-report.mjs

@@ -18,6 +18,8 @@ import {
   DEFAULT_REMOTE,
   assertCompatibleMapDirs,
   cleanupCachedCaptureDirs,
+  manifestlessError,
+  manifestlessSide,
   resolveCachedCaptureDirs,
 } from '../dist/map-store.js';
 
@@ -146,6 +148,10 @@ if (foldDetailsAt !== undefined && Number.isNaN(foldDetailsAt)) {
 
 let result;
 try {
+  // v4: refuse a manifest-less side (exit 2 via the catch) — same-environment
+  // compatibility can't be verified without a manifest on both sides.
+  const manifestless = manifestlessSide(beforeDir, afterDir);
+  if (manifestless) throw new Error(manifestlessError(manifestless));
   assertCompatibleMapDirs(beforeDir, afterDir);
   result = generateStyleMapReport({
     beforeDir,

package/dist/capture-url.js

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { captureStyleMap, saveStyleMap, trackInflightRequests } from './capture.js';
 import { detectViewportWidths } from './breakpoints.js';
 import { runSetup } from './crawl-surfaces.js';
+import { writeCaptureManifest } from './map-store.js';
 /**
  * One-shot capture of a single URL's computed-style map — no spec, no config,
  * no git. `defineStyleMapCapture` is the right tool when the surfaces live in
@@ -192,6 +193,10 @@ export async function captureUrlToDir(page, opts) {
             requests.dispose();
         }
     }
+    // Stamp a manifest so `styleproof-diff <thisDir> <build>` has the same-environment
+    // guard on both sides — v4 refuses to compare a manifest-less side. May run outside
+    // a git repo (a design mockup); the git fields degrade gracefully.
+    writeCaptureManifest({ dir: opts.out, screenshots: opts.screenshots });
     return results;
 }
 /** Launch Chromium, capture the URL, and close — the whole bin body given parsed options. */

package/dist/capture.d.ts

@@ -1,5 +1,6 @@
 import type { Page } from '@playwright/test';
 import { type NavigableItem } from './inventory.js';
+import { type DataResidueEntry } from './data-residue.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
@@ -132,6 +133,15 @@ export type StyleMap = {
      * by the certification diff. See docs/inventory-guard.md.
      */
     inventory?: NavigableItem[];
+    /**
+     * Data-boundary requests (matching `replayUrl`) that FAILED during this capture —
+     * a network error or a 4xx/5xx. Their presence means the captured state renders the
+     * endpoint's FALLBACK branch, so states driven by its real responses are uncaptured
+     * and unproven. Present only when the residue guard was armed (`dataResidue` set) and
+     * a failure actually occurred; absent (byte-identical to before) on a clean capture.
+     * Surfaced by the data-residue guard, never by the certification diff. See issue #205.
+     */
+    dataResidue?: DataResidueEntry[];
 };
 export type CaptureOptions = {
     /**
@@ -248,6 +258,39 @@ export declare function trackInflightRequests(page: Page): {
     pending: () => number;
     dispose: () => void;
 };
+/**
+ * Watch the data boundary (`url`, the same `replayUrl` glob record/replay uses) for
+ * requests that FAIL during capture — a network-level failure or a 4xx/5xx response.
+ * A failing data request means the captured state renders that endpoint's FALLBACK
+ * branch; the response-driven state is uncaptured and unproven (issue #205).
+ *
+ * Matches purely by listening to `requestfailed`/`response` and testing the URL against
+ * the boundary glob — NOT via a `page.route`. A passive route can't be used to tag: the
+ * tracker is armed before `go()`, and a route the surface itself adds in `go()` (an abort
+ * fixture, the HAR replay route) runs first and never falls through to a tag route added
+ * earlier, so tagged requests would be missed. Listeners see every request regardless of
+ * routing, which is exactly what a residue observer needs. Arm BEFORE navigation, like
+ * {@link trackInflightRequests}, so the page's own load fetches are seen; deduped per
+ * `<surface>·<endpoint>` so the same failure across widths / a self-check re-run is one entry.
+ *
+ * ONLY failures are recorded — never a 2xx that merely wasn't fixtured: in recording mode
+ * every live 2xx is legitimately recorded, so a blanket "uncontrolled" flag would fire on
+ * every healthy record run (issue #205, "deliberately out of scope").
+ */
+export declare function trackDataResidue(page: Page, url: string, surface: string): {
+    residue: () => DataResidueEntry[];
+    dispose: () => void;
+};
+/**
+ * A predicate matching a URL against a Playwright-style URL glob — the same micro-syntax
+ * `page.route`/`routeFromHAR` accept for `replayUrl`, replicated because Playwright exposes
+ * no public matcher and reaching into its bundled internals is fragile across versions.
+ * `**` spans path separators, `*` matches within a segment (not `/`), `?` is a literal
+ * (URL globs, unlike shell globs, treat `?` as the query delimiter), and `{a,b}` alternates.
+ * A plain (glob-char-free) string is treated as a substring match, matching Playwright's
+ * own "contains" fallback for non-glob route URLs.
+ */
+export declare function urlMatcher(glob: string): (url: string) => boolean;
 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;
@@ -261,6 +304,14 @@ export declare function loadStyleMap(filePath: string): StyleMap;
 export declare function readInventories(dir: string): Array<{
     inventory?: NavigableItem[];
 }>;
+/**
+ * Read every surface map's `dataResidue` from a capture dir, in the shape the
+ * data-residue audit consumes. Lives here (not in data-residue.ts) so that module
+ * stays a pure leaf — it must not import `loadStyleMap` back from this file.
+ */
+export declare function readResidue(dir: string): Array<{
+    dataResidue?: DataResidueEntry[];
+}>;
 /**
  * Each captured surface key → the set of element paths it renders, unioned across
  * the given dirs (so an element present on only one side still "belongs" to the

package/dist/capture.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { classifyInventory, collectNavAffordances } from './inventory.js';
+import { endpointOf, residueKey } from './data-residue.js';
 import { isMapFile } from './map-store.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
@@ -598,6 +599,93 @@ export function trackInflightRequests(page) {
         },
     };
 }
+/**
+ * Watch the data boundary (`url`, the same `replayUrl` glob record/replay uses) for
+ * requests that FAIL during capture — a network-level failure or a 4xx/5xx response.
+ * A failing data request means the captured state renders that endpoint's FALLBACK
+ * branch; the response-driven state is uncaptured and unproven (issue #205).
+ *
+ * Matches purely by listening to `requestfailed`/`response` and testing the URL against
+ * the boundary glob — NOT via a `page.route`. A passive route can't be used to tag: the
+ * tracker is armed before `go()`, and a route the surface itself adds in `go()` (an abort
+ * fixture, the HAR replay route) runs first and never falls through to a tag route added
+ * earlier, so tagged requests would be missed. Listeners see every request regardless of
+ * routing, which is exactly what a residue observer needs. Arm BEFORE navigation, like
+ * {@link trackInflightRequests}, so the page's own load fetches are seen; deduped per
+ * `<surface>·<endpoint>` so the same failure across widths / a self-check re-run is one entry.
+ *
+ * ONLY failures are recorded — never a 2xx that merely wasn't fixtured: in recording mode
+ * every live 2xx is legitimately recorded, so a blanket "uncontrolled" flag would fire on
+ * every healthy record run (issue #205, "deliberately out of scope").
+ */
+export function trackDataResidue(page, url, surface) {
+    const byKey = new Map();
+    const inBoundary = urlMatcher(url);
+    const record = (request, reason) => {
+        if (!inBoundary(request.url()))
+            return;
+        const endpoint = endpointOf(request.url());
+        const key = residueKey(surface, endpoint);
+        if (!byKey.has(key))
+            byKey.set(key, { key, surface, endpoint, reason });
+    };
+    const onFailed = (r) => record(r, r.failure()?.errorText ?? 'request failed');
+    // A completed response's status is synchronous here, so a 4xx/5xx is recorded before
+    // capture reads the residue. A >=400 is a fallback-branch trigger just like a net failure.
+    const onResponse = (resp) => {
+        if (resp.status() >= 400)
+            record(resp.request(), `HTTP ${resp.status()}`);
+    };
+    page.on('requestfailed', onFailed);
+    page.on('response', onResponse);
+    return {
+        residue: () => Array.from(byKey.values()).sort((a, b) => a.key.localeCompare(b.key)),
+        dispose: () => {
+            page.off('requestfailed', onFailed);
+            page.off('response', onResponse);
+        },
+    };
+}
+/**
+ * A predicate matching a URL against a Playwright-style URL glob — the same micro-syntax
+ * `page.route`/`routeFromHAR` accept for `replayUrl`, replicated because Playwright exposes
+ * no public matcher and reaching into its bundled internals is fragile across versions.
+ * `**` spans path separators, `*` matches within a segment (not `/`), `?` is a literal
+ * (URL globs, unlike shell globs, treat `?` as the query delimiter), and `{a,b}` alternates.
+ * A plain (glob-char-free) string is treated as a substring match, matching Playwright's
+ * own "contains" fallback for non-glob route URLs.
+ */
+export function urlMatcher(glob) {
+    if (!/[*?{}[\]]/.test(glob))
+        return (url) => url.includes(glob);
+    const specials = new Set(['.', '+', '^', '$', '|', '(', ')']);
+    let re = '';
+    for (let i = 0; i < glob.length; i++) {
+        const c = glob[i];
+        if (c === '*') {
+            if (glob[i + 1] === '*') {
+                re += '.*';
+                i++;
+            }
+            else
+                re += '[^/]*';
+        }
+        else if (c === '?')
+            re += '\\?';
+        else if (c === '{')
+            re += '(';
+        else if (c === '}')
+            re += ')';
+        else if (c === ',')
+            re += '|';
+        else if (specials.has(c))
+            re += `\\${c}`;
+        else
+            re += c;
+    }
+    const compiled = new RegExp(`^${re}$`);
+    return (url) => compiled.test(url);
+}
 /** Settle the page and return the paths of live regions to exclude. */
 async function detectVolatile(page, ignore, stabilize, captureText, externalPending) {
     if (stabilize === false)
@@ -793,17 +881,29 @@ export function loadStyleMap(filePath) {
             'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.', { cause: e });
     }
 }
+/** Every surface map in a capture dir, loaded — the shared reader behind the
+ *  per-field extractors below. */
+function loadDirMaps(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter(isMapFile)
+        .map((f) => loadStyleMap(path.join(dir, f)));
+}
 /**
  * Read every surface map's navigable inventory from a capture dir, in the shape the
  * inventory audit consumes. One home for "read the inventories out of a dir", shared
  * by the diff CLI and the report (was duplicated in both).
  */
 export function readInventories(dir) {
-    return fs
-        .readdirSync(dir)
-        .filter(isMapFile)
-        .map((f) => loadStyleMap(path.join(dir, f)))
-        .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+    return loadDirMaps(dir).map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+}
+/**
+ * Read every surface map's `dataResidue` from a capture dir, in the shape the
+ * data-residue audit consumes. Lives here (not in data-residue.ts) so that module
+ * stays a pure leaf — it must not import `loadStyleMap` back from this file.
+ */
+export function readResidue(dir) {
+    return loadDirMaps(dir).map((m) => (m.dataResidue ? { dataResidue: m.dataResidue } : {}));
 }
 /**
  * Each captured surface key → the set of element paths it renders, unioned across

package/dist/coverage.d.ts

@@ -86,6 +86,13 @@ export type CoverageLedger = {
     exclude: Record<string, string>;
     /** How this capture's determinism was established (3.10.0). Absent on older bundles. */
     determinism?: DeterminismBasis;
+    /**
+     * The data-residue guard mode this capture ran under (issue #205). `'gate'` (the v4
+     * default) — an unacknowledged failing data endpoint blocks the diff; `'warn'` — the
+     * explicit opt-out, residue is recorded and warned but never blocks. Absent on bundles
+     * captured before the field existed, and read as warn so they never gate retroactively.
+     */
+    dataResidue?: 'warn' | 'gate';
 };
 export type DeterminismVerdict = {
     /** `proven` — both sides self-checked or replayed; `unproven` — a side was neither, so