styleproof 3.21.0 → 4.0.0

package/dist/data-residue.d.ts

@@ -0,0 +1,70 @@
+/** One data-boundary request that FAILED during capture — an embedded fallback branch. */
+export type DataResidueEntry = {
+    /**
+     * Stable identity across captures: `<surface>·<endpoint>` where `endpoint` is the
+     * request URL's `pathname` (query stripped so `?all=1` vs `?all=2` don't fork the
+     * key). Escaped so it can't inject Markdown into the report/PR-comment summary.
+     */
+    key: string;
+    /** The captured surface key this failure was observed on. */
+    surface: string;
+    /** The failing endpoint's URL pathname (query stripped). */
+    endpoint: string;
+    /** Why it failed: a network error text (`net::ERR_CONNECTION_REFUSED`) or `HTTP 503`. */
+    reason: string;
+};
+/** `key -> reason` — failing endpoints that are intentional/known and on the record. */
+export type AcknowledgedResidue = Record<string, string>;
+/** Acknowledgement file, parallel to the inventory guard's `styleproof.inventory.json`. */
+export declare const DATA_RESIDUE_ACK_FILE = "styleproof.data-residue.json";
+/**
+ * Read the acknowledged-residue file (`$STYLEPROOF_DATA_RESIDUE` or
+ * `styleproof.data-residue.json`). `{}` when absent; THROWS on malformed JSON — the
+ * caller picks the policy (the CI gate fails loud so a broken ack file can't silently
+ * un-acknowledge a real failure; the advisory report degrades to `{}`). Mirrors
+ * `readAckFile` in the inventory guard exactly.
+ */
+export declare function readResidueAckFile(): AcknowledgedResidue;
+/** Build a residue key from a surface and an endpoint URL. Query stripped, escaped. */
+export declare function residueKey(surface: string, endpoint: string): string;
+/** The endpoint pathname a URL resolves to, query stripped. Falls back to the raw URL. */
+export declare function endpointOf(url: string): string;
+/**
+ * Union the per-surface `map.dataResidue` of a whole run into one deduped set, keyed by
+ * `key` (surface·endpoint), so the same failure seen across widths / a self-check re-run
+ * is ONE entry, not a spray. Sorted for a stable rendering order.
+ */
+export declare function unionResidue(perSurface: Array<{
+    dataResidue?: DataResidueEntry[];
+} | undefined>): DataResidueEntry[];
+export type ResidueAudit = {
+    /** Every failing endpoint observed across the run (union, deduped). */
+    residue: DataResidueEntry[];
+    /** Failing endpoints NOT acknowledged in the ledger — the gate fails on a non-empty set. */
+    unacknowledged: DataResidueEntry[];
+    /** Acknowledged keys no longer present in the residue (the endpoint is fixtured/gone) —
+     *  a rotted opt-out, so the ledger can't quietly rot (mirrors the `exclude` guard). */
+    staleAcknowledgements: string[];
+};
+/**
+ * The gate. A failing endpoint whose key isn't in `acknowledged` (key -> reason) is
+ * unacknowledged — the caller fails on a non-empty result. An `acknowledged` key that
+ * isn't actually failing is stale, returned separately so the ledger can't rot. Unlike
+ * the inventory guard (a base-vs-head REMOVAL), residue is present-on-HEAD: the head
+ * capture's failing endpoints are audited directly, so only the head maps matter.
+ */
+export declare function auditResidue(headMaps: Array<{
+    dataResidue?: DataResidueEntry[];
+} | undefined>, acknowledged?: AcknowledgedResidue): ResidueAudit;
+/**
+ * Run-level entry point for a gate/report: audit the HEAD bundle's residue against the
+ * acknowledgement ledger, carrying whether the guard was ARMED to gate. `armed` comes
+ * from the head coverage ledger's `dataResidue: 'gate'` (the default; only an explicit
+ * `'warn'` — or an older bundle with no field — is unarmed). When not armed, the caller
+ * still surfaces residue (warn is the explicit opt-out) but must not block.
+ */
+export declare function auditRunResidue(headMaps: Array<{
+    dataResidue?: DataResidueEntry[];
+} | undefined>, acknowledged: AcknowledgedResidue, armed: boolean): ResidueAudit & {
+    armed: boolean;
+};

package/dist/data-residue.js

@@ -0,0 +1,105 @@
+// Data-residue guard — name the data-boundary requests that FAILED during capture.
+//
+// The certification diff proves "did surface X change?" but is structurally blind to
+// a whole class of high-stakes miss: a surface requests a data endpoint that nothing
+// controls — no fixture routes it, so it falls through and FAILS (network error, or a
+// 4xx/5xx) — and the view silently renders its FALLBACK branch. Capture after capture
+// embeds that fallback state; the response-driven state its real data would produce is
+// never captured, so a restyle confined to that state ships green. StyleProof's
+// request tracker watched the request fail every time and said nothing.
+//
+// This module records, per surface, any request matching the data boundary (the
+// `replayUrl` glob) that failed or errored. The residue travels on the StyleMap (like
+// `inventory`), so the diff/report can surface it; a stderr warning names it at capture
+// time; and the gate (on by default, opted down via `dataResidue: 'warn'`) blocks an
+// unacknowledged failing endpoint — mirroring the `exclude`/inventory-ack discipline.
+//
+// Observing that a data request failed needs NO app knowledge — it's the same move as
+// the unreadable-stylesheet residue: convert silent blindness into a name. Declaring
+// the app's data STATES stays app-owned (see issue #202); this only observes failures.
+//
+// Deliberately OUT OF SCOPE (unsound or noisy):
+//   - Flagging endpoints that responded 2xx but weren't fixtured. In recording mode
+//     every live response is legitimately recorded, so a blanket "uncontrolled" flag
+//     would fire on every healthy record run. A sound record-fulfilled-vs-network
+//     discriminator (if Playwright exposes one) could be a follow-up; we do not ship a
+//     heuristic version. Only FAILED requests (network error / 4xx / 5xx) are residue.
+//   - Synthesising payloads or surfaces for un-exercised response variants (app
+//     knowledge; issue #202's territory).
+import fs from 'node:fs';
+import path from 'node:path';
+import { safeKey } from './change-groups.js';
+/** Acknowledgement file, parallel to the inventory guard's `styleproof.inventory.json`. */
+export const DATA_RESIDUE_ACK_FILE = 'styleproof.data-residue.json';
+/**
+ * Read the acknowledged-residue file (`$STYLEPROOF_DATA_RESIDUE` or
+ * `styleproof.data-residue.json`). `{}` when absent; THROWS on malformed JSON — the
+ * caller picks the policy (the CI gate fails loud so a broken ack file can't silently
+ * un-acknowledge a real failure; the advisory report degrades to `{}`). Mirrors
+ * `readAckFile` in the inventory guard exactly.
+ */
+export function readResidueAckFile() {
+    const p = path.resolve(process.env.STYLEPROOF_DATA_RESIDUE ?? DATA_RESIDUE_ACK_FILE);
+    if (!fs.existsSync(p))
+        return {};
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch (e) {
+        throw new Error(`${p} is not valid JSON — ${e.message}`, { cause: e });
+    }
+}
+/** Build a residue key from a surface and an endpoint URL. Query stripped, escaped. */
+export function residueKey(surface, endpoint) {
+    return `${safeKey(surface)}·${safeKey(endpoint)}`;
+}
+/** The endpoint pathname a URL resolves to, query stripped. Falls back to the raw URL. */
+export function endpointOf(url) {
+    try {
+        return new URL(url).pathname;
+    }
+    catch {
+        return url;
+    }
+}
+// ── pure union / audit / reconciliation ─────────────────────────────────────────
+/**
+ * Union the per-surface `map.dataResidue` of a whole run into one deduped set, keyed by
+ * `key` (surface·endpoint), so the same failure seen across widths / a self-check re-run
+ * is ONE entry, not a spray. Sorted for a stable rendering order.
+ */
+export function unionResidue(perSurface) {
+    const byKey = new Map();
+    for (const map of perSurface) {
+        for (const entry of map?.dataResidue ?? [])
+            if (!byKey.has(entry.key))
+                byKey.set(entry.key, entry);
+    }
+    return Array.from(byKey.values()).sort((a, b) => a.key.localeCompare(b.key));
+}
+/**
+ * The gate. A failing endpoint whose key isn't in `acknowledged` (key -> reason) is
+ * unacknowledged — the caller fails on a non-empty result. An `acknowledged` key that
+ * isn't actually failing is stale, returned separately so the ledger can't rot. Unlike
+ * the inventory guard (a base-vs-head REMOVAL), residue is present-on-HEAD: the head
+ * capture's failing endpoints are audited directly, so only the head maps matter.
+ */
+export function auditResidue(headMaps, acknowledged = {}) {
+    const residue = unionResidue(headMaps);
+    const residueKeys = new Set(residue.map((r) => r.key));
+    return {
+        residue,
+        unacknowledged: residue.filter((r) => !(r.key in acknowledged)),
+        staleAcknowledgements: Object.keys(acknowledged).filter((k) => !residueKeys.has(k)),
+    };
+}
+/**
+ * Run-level entry point for a gate/report: audit the HEAD bundle's residue against the
+ * acknowledgement ledger, carrying whether the guard was ARMED to gate. `armed` comes
+ * from the head coverage ledger's `dataResidue: 'gate'` (the default; only an explicit
+ * `'warn'` — or an older bundle with no field — is unarmed). When not armed, the caller
+ * still surfaces residue (warn is the explicit opt-out) but must not block.
+ */
+export function auditRunResidue(headMaps, acknowledged, armed) {
+    return { armed, ...auditResidue(headMaps, acknowledged) };
+}

package/dist/index.d.ts

@@ -1,5 +1,6 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests, trackDataResidue, urlMatcher, } from './capture.js';
 export * from './inventory.js';
+export * from './data-residue.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,5 +1,6 @@
-export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests } from './capture.js';
+export { captureStyleMap, saveStyleMap, loadStyleMap, trackInflightRequests, trackDataResidue, urlMatcher, } from './capture.js';
 export * from './inventory.js';
+export * from './data-residue.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/map-store.d.ts

@@ -61,7 +61,12 @@ export declare function expectedCompatibilityKey(options?: {
 }): string;
 export declare function currentGitSha(cwd?: string, env?: NodeJS.ProcessEnv): string;
 export declare function refSha(ref: string, cwd?: string): string;
-export declare function workingTreeDirty(cwd?: string): boolean;
+/**
+ * True if any tracked file is modified/added/deleted. `ignorePrefix` (a repo-relative
+ * directory) is excluded — pass the map OUTPUT dir when re-sampling AFTER a capture, so
+ * the maps the capture just wrote don't read as tree dirt and mask a real source edit.
+ */
+export declare function workingTreeDirty(cwd?: string, ignorePrefix?: string): boolean;
 export declare function remoteExists(remote?: string, cwd?: string): boolean;
 export declare function writeMapManifest(options: {
     dir: string;
@@ -72,7 +77,38 @@ export declare function writeMapManifest(options: {
     cwd?: string;
     env?: NodeJS.ProcessEnv;
 }): MapManifest;
+/**
+ * Write a `styleproof-manifest.json` for a one-shot `styleproof-capture` output dir,
+ * so a two-directory `styleproof-diff design <build>` has the same-environment guard
+ * on both sides (v4 refuses to compare a manifest-less side). Unlike
+ * {@link writeMapManifest}, this may run OUTSIDE a git repo (a design mockup, a static
+ * export), so the git-derived fields degrade gracefully: `sha` falls back to
+ * `'uncommitted'` and `dirty` to `true` rather than throwing. The parts the guard
+ * actually consumes — `compatibilityKey`, `platform`/`arch`/`nodeMajor`,
+ * `playwrightVersion`, `browserVersion`, `baseUrl` — are recorded the same way as a
+ * spec capture. Overwrites any existing manifest in `dir`.
+ */
+export declare function writeCaptureManifest(options: {
+    dir: string;
+    screenshots: boolean;
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+}): MapManifest;
 export declare function readMapManifest(dir: string): MapManifest | null;
+/** Which side(s) of a two-directory compare hold captured maps but NO
+ *  `styleproof-manifest.json` — a legacy committed-map bundle. Since v4 that is
+ *  unsupported: without a manifest the same-environment guard can't be enforced, so the
+ *  CLI refuses (exit 2). `null` means every side WITH maps also has a manifest (nothing to
+ *  refuse). A side with zero maps is NOT flagged — an empty/bare dir is "no baseline yet",
+ *  handled by the base/head-missing guards, not this one. Pure: presence reads only, so the
+ *  CLI layer owns the exit code and the library stays side-effect-free. */
+export declare function manifestlessSide(beforeDir: string, afterDir: string): 'before' | 'after' | 'both' | null;
+/** Fail-loud message for a manifest-less compare. Since v4 a side without a
+ *  `styleproof-manifest.json` is unsupported: the same-environment guard can't be
+ *  enforced, so captures from different browser builds or platforms would diff as
+ *  false changes. The CLI raises this and exits 2 (usage/capture error) — the
+ *  legacy "compare anyway" tolerance is gone. */
+export declare function manifestlessError(side: 'before' | 'after' | 'both'): string;
 export declare function assertCompatibleMapDirs(beforeDir: string, afterDir: string): void;
 export declare function publishMapBundle(options: {
     dir: string;

package/dist/map-store.js

@@ -153,28 +153,40 @@ export function refSha(ref, cwd = process.cwd()) {
         throw new MapStoreError(`could not resolve ${ref} to a commit`);
     return sha;
 }
-export function workingTreeDirty(cwd = process.cwd()) {
+/**
+ * True if any tracked file is modified/added/deleted. `ignorePrefix` (a repo-relative
+ * directory) is excluded — pass the map OUTPUT dir when re-sampling AFTER a capture, so
+ * the maps the capture just wrote don't read as tree dirt and mask a real source edit.
+ */
+export function workingTreeDirty(cwd = process.cwd(), ignorePrefix) {
     const r = runGit(cwd, ['status', '--porcelain']);
     const status = r.status === 0 ? r.stdout.trimEnd() : '';
     if (!status)
         return false;
+    const prefix = ignorePrefix ? `${ignorePrefix.replace(/\/+$/, '')}/` : undefined;
     return status.split(/\r?\n/).some((line) => {
         const file = line.slice(3).trim();
-        return file && !GENERATED_DIRTY_ALLOWLIST.has(file);
+        if (!file || GENERATED_DIRTY_ALLOWLIST.has(file))
+            return false;
+        if (prefix && (file === prefix.slice(0, -1) || file.startsWith(prefix)))
+            return false;
+        return true;
     });
 }
 export function remoteExists(remote = DEFAULT_REMOTE, cwd = process.cwd()) {
     return runGit(cwd, ['remote', 'get-url', remote], 1 << 20).status === 0;
 }
-export function writeMapManifest(options) {
-    const cwd = options.cwd ?? process.cwd();
-    const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
-    const browserVersion = readBrowserBuildSidecar(options.dir);
-    const manifest = {
+/** Assemble a {@link MapManifest} from the compatibility inputs and the caller-resolved
+ *  git fields. Shared by {@link writeMapManifest} (spec capture) and
+ *  {@link writeCaptureManifest} (one-shot capture) so the object shape lives in one place. */
+function buildManifest(options) {
+    const { dir, input } = options;
+    const browserVersion = readBrowserBuildSidecar(dir);
+    return {
         version: 1,
         packageVersion: input.packageVersion,
-        sha: options.sha ?? currentGitSha(cwd, options.env),
-        dirty: options.dirty ?? workingTreeDirty(cwd),
+        sha: options.sha,
+        dirty: options.dirty,
         spec: input.spec,
         specHash: input.specHash,
         ...(input.lockfile ? { lockfile: input.lockfile } : {}),
@@ -186,10 +198,49 @@ export function writeMapManifest(options) {
         nodeMajor: input.nodeMajor,
         ...(input.baseUrl ? { baseUrl: input.baseUrl } : {}),
         screenshots: options.screenshots,
-        har: hasHar(options.dir),
+        har: hasHar(dir),
         compatibilityKey: hash(JSON.stringify(input)).slice(0, 16),
         createdAt: new Date().toISOString(),
     };
+}
+export function writeMapManifest(options) {
+    const cwd = options.cwd ?? process.cwd();
+    const input = compatibilityInput({ cwd, spec: options.spec, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    const manifest = buildManifest({
+        dir: options.dir,
+        input,
+        sha: options.sha ?? currentGitSha(cwd, options.env),
+        dirty: options.dirty ?? workingTreeDirty(cwd),
+        screenshots: options.screenshots,
+    });
+    fs.writeFileSync(path.join(options.dir, MAP_MANIFEST), JSON.stringify(manifest, null, 2));
+    return manifest;
+}
+/**
+ * Write a `styleproof-manifest.json` for a one-shot `styleproof-capture` output dir,
+ * so a two-directory `styleproof-diff design <build>` has the same-environment guard
+ * on both sides (v4 refuses to compare a manifest-less side). Unlike
+ * {@link writeMapManifest}, this may run OUTSIDE a git repo (a design mockup, a static
+ * export), so the git-derived fields degrade gracefully: `sha` falls back to
+ * `'uncommitted'` and `dirty` to `true` rather than throwing. The parts the guard
+ * actually consumes — `compatibilityKey`, `platform`/`arch`/`nodeMajor`,
+ * `playwrightVersion`, `browserVersion`, `baseUrl` — are recorded the same way as a
+ * spec capture. Overwrites any existing manifest in `dir`.
+ */
+export function writeCaptureManifest(options) {
+    const cwd = options.cwd ?? process.cwd();
+    // A one-shot capture has no spec file; key comparability off the capture inputs only.
+    const input = compatibilityInput({ cwd, spec: MAP_MANIFEST, baseUrl: options.env?.BASE_URL ?? process.env.BASE_URL });
+    // Degrade the git fields gracefully outside a repo (a design mockup): no HEAD → uncommitted/dirty.
+    const sha = gitOutput(cwd, ['rev-parse', 'HEAD']) || 'uncommitted';
+    const manifest = buildManifest({
+        dir: options.dir,
+        input,
+        sha,
+        dirty: sha === 'uncommitted' ? true : workingTreeDirty(cwd),
+        screenshots: options.screenshots,
+    });
+    fs.mkdirSync(options.dir, { recursive: true });
     fs.writeFileSync(path.join(options.dir, MAP_MANIFEST), JSON.stringify(manifest, null, 2));
     return manifest;
 }
@@ -201,6 +252,48 @@ export function readMapManifest(dir) {
         return null;
     }
 }
+/** True if `dir` holds at least one captured surface map (`<key>@<width>.json[.gz]`),
+ *  ignoring metadata sidecars. Distinguishes a real capture that merely lacks a manifest
+ *  (a legacy committed-map bundle — v4 refuses it) from an empty/bare dir (no baseline
+ *  yet — the missing-map guards own that). */
+function dirHasMaps(dir) {
+    try {
+        return fs.readdirSync(dir).some(isMapFile);
+    }
+    catch {
+        return false;
+    }
+}
+/** Which side(s) of a two-directory compare hold captured maps but NO
+ *  `styleproof-manifest.json` — a legacy committed-map bundle. Since v4 that is
+ *  unsupported: without a manifest the same-environment guard can't be enforced, so the
+ *  CLI refuses (exit 2). `null` means every side WITH maps also has a manifest (nothing to
+ *  refuse). A side with zero maps is NOT flagged — an empty/bare dir is "no baseline yet",
+ *  handled by the base/head-missing guards, not this one. Pure: presence reads only, so the
+ *  CLI layer owns the exit code and the library stays side-effect-free. */
+export function manifestlessSide(beforeDir, afterDir) {
+    const before = dirHasMaps(beforeDir) && readMapManifest(beforeDir) == null;
+    const after = dirHasMaps(afterDir) && readMapManifest(afterDir) == null;
+    if (before && after)
+        return 'both';
+    if (before)
+        return 'before';
+    if (after)
+        return 'after';
+    return null;
+}
+/** Fail-loud message for a manifest-less compare. Since v4 a side without a
+ *  `styleproof-manifest.json` is unsupported: the same-environment guard can't be
+ *  enforced, so captures from different browser builds or platforms would diff as
+ *  false changes. The CLI raises this and exits 2 (usage/capture error) — the
+ *  legacy "compare anyway" tolerance is gone. */
+export function manifestlessError(side) {
+    const carry = side === 'both' ? 'before and after carry' : `${side} carries`;
+    return (`styleproof: ${carry} no ${MAP_MANIFEST} — environment compatibility can't be verified, so ` +
+        'captures from different browser builds or platforms would diff as false changes. ' +
+        'Re-capture with current StyleProof (styleproof-map, or styleproof-capture for a one-shot ' +
+        'diff); maps without a manifest are unsupported since v4.');
+}
 export function assertCompatibleMapDirs(beforeDir, afterDir) {
     const before = readMapManifest(beforeDir);
     const after = readMapManifest(afterDir);

package/dist/report.js

@@ -1,13 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from 'pngjs';
-import { loadStyleMap, readInventories, surfaceElementPaths, } from './capture.js';
+import { loadStyleMap, readInventories, readResidue, surfaceElementPaths, } from './capture.js';
 import { isMapFile } from './map-store.js';
 import { fillRect } from './png-util.js';
 import { diffStyleMapDirs, diffContentDirs, } from './diff.js';
 import { describeChange, tokenIndex, toHex } from './describe.js';
 import { auditCoverage, auditDeterminism, COVERAGE_LEDGER, } from './coverage.js';
 import { auditRunInventory, readAckFile } from './inventory.js';
+import { auditRunResidue, readResidueAckFile } from './data-residue.js';
 // The pure grouping / classification brain — shared with the CLI. report.ts keeps
 // the crop-and-PNG rendering on top of these.
 import { cleanFindings, groupByPath, groupTitle, isNonValue, prettyLabel, safeKey, signatureOf, summarizeProps, surfaceBase, surfaceWidth, pushSurfaceWidth, renderSurfaceGroups, formatSurfaceList, classifyChrome, } from './change-groups.js';
@@ -625,6 +626,29 @@ function readAcknowledgedRemovals() {
         return {};
     }
 }
+// Lenient acknowledged-residue read — same advisory degradation as the inventory one.
+function readAcknowledgedResidue() {
+    try {
+        return readResidueAckFile();
+    }
+    catch {
+        return {};
+    }
+}
+// One data-residue clause. A failing data endpoint captured the fallback branch, so its
+// response-driven states are unproven; an ARMED gate escalates an unacknowledged one to ✗.
+function dataResidueLine(res) {
+    const { residue, unacknowledged, staleAcknowledgements, armed } = res;
+    if (armed && (unacknowledged.length > 0 || staleAcknowledgements.length > 0)) {
+        const stale = staleAcknowledgements.length ? `; ${staleAcknowledgements.length} stale acknowledgement(s)` : '';
+        return `- **Data residue** — ✗ ${unacknowledged.length} failing data endpoint(s), unacknowledged: ${keyList(unacknowledged)}${stale}`;
+    }
+    if (unacknowledged.length > 0)
+        return `- **Data residue** — ⚠ ${unacknowledged.length} failing data endpoint(s) (fallback branch captured): ${keyList(unacknowledged)} — recorded, not gating (\`dataResidue: 'warn'\` opt-out)`;
+    if (residue.length > 0)
+        return `- **Data residue** — ✓ ${residue.length} failing endpoint(s), all acknowledged`;
+    return '- **Data residue** — ✓ no failing data-boundary request during capture';
+}
 /**
  * The certification block a reviewer reads FIRST — the source-of-truth gates (coverage
  * complete? determinism proven? did the navigable set shrink?), not just the pixel diff.
@@ -634,15 +658,20 @@ function certificationLines(beforeDir, afterDir) {
     const baseLedger = readLedgerFile(beforeDir);
     const headLedger = readLedgerFile(afterDir);
     const inv = auditRunInventory(readInventories(beforeDir), readInventories(afterDir), readAcknowledgedRemovals());
+    const res = auditRunResidue(readResidue(afterDir), readAcknowledgedResidue(), headLedger?.dataResidue === 'gate');
     const hasLedger = baseLedger !== null || headLedger !== null;
     const hasInvChange = inv.delta.removed.length > 0 || inv.delta.added.length > 0;
-    if (!hasLedger && !hasInvChange)
+    const hasResidue = res.residue.length > 0 || res.armed;
+    if (!hasLedger && !hasInvChange && !hasResidue)
         return [];
     return [
         '**Certification**',
         coverageLine(auditCoverage(surfaceKeysIn(afterDir), headLedger)),
         determinismLine(auditDeterminism(baseLedger, headLedger)),
         inventoryLine(inv),
+        // Only add the residue line when there's residue or the gate was armed — an ordinary
+        // bundle (no failing endpoint, not armed) keeps its exact prior 3-line block.
+        ...(hasResidue ? [dataResidueLine(res)] : []),
         '',
     ];
 }

package/dist/runner.d.ts

@@ -177,6 +177,20 @@ export type DefineOptions = {
      * See `docs/inventory-guard.md`.
      */
     inventory?: boolean;
+    /**
+     * Data-residue guard. During capture, any request matching the data boundary
+     * (`replayUrl`, default `**\/api/**`) that FAILS — a network error or a 4xx/5xx —
+     * means the captured state renders that endpoint's FALLBACK branch, so states driven
+     * by its real responses are uncaptured and unproven (issue #205). Such a failure is
+     * ALWAYS named on stderr and recorded on the capture (`StyleMap.dataResidue`) so the
+     * diff/report can surface it. `'gate'` (the default) makes an UNACKNOWLEDGED failing
+     * endpoint block `styleproof-diff` (exit 1); acknowledge intentional ones in
+     * `styleproof.data-residue.json` (`key -> reason`). `'warn'` is the explicit opt-out —
+     * failures are still named + recorded but never block. A capture with no failing data
+     * request is byte-identical either way. A 2xx that merely wasn't fixtured is NEVER
+     * flagged (recording legitimately records live 2xx).
+     */
+    dataResidue?: 'warn' | 'gate';
 };
 export declare function selfCheckErrorMessage(surfaceKey: string, drift: Finding[], volatile?: string[], liveCandidates?: LiveRegionCandidate[]): string;
 type ResolvedPopupCaptureOptions = Required<PopupCaptureOptions>;
@@ -237,6 +251,12 @@ export declare function resolveBaseDir(baseDir: string | undefined, env?: string
  * can generate reviewable reports without recapturing.
  */
 export declare function resolveScreenshots(screenshots: boolean | undefined, env?: string | undefined): boolean;
+/**
+ * The data-residue guard mode: `'gate'` (the v4 default) blocks the diff on an
+ * unacknowledged failing data endpoint; `'warn'` is the explicit opt-out that records +
+ * warns without gating. Single source of truth for the default, so the flip lives here.
+ */
+export declare function resolveDataResidue(mode: 'warn' | 'gate' | undefined): 'warn' | 'gate';
 /** The capture settings every capturer shares (everything bar the surface set). */
 type CaptureConfig = Omit<DefineOptions, 'surfaces' | 'expected' | 'exclude'>;
 export declare function defineStyleMapCapture(options: DefineOptions): void;

package/dist/runner.js

@@ -1,10 +1,10 @@
 import { test, expect } from '@playwright/test';
 import fs from 'node:fs';
 import path from 'node:path';
-import { captureStyleMap, saveStyleMap, trackInflightRequests, } from './capture.js';
+import { captureStyleMap, saveStyleMap, trackInflightRequests, trackDataResidue, } from './capture.js';
 import { diffStyleMaps } from './diff.js';
 import { coverageGaps, coverageKeys, translateExpected, COVERAGE_LEDGER, } from './coverage.js';
-import { writeBrowserBuildSidecar } from './map-store.js';
+import { writeBrowserBuildSidecar, writeCaptureManifest } from './map-store.js';
 import { detectViewportWidths } from './breakpoints.js';
 import { selectCrawlLinks, crawlCoverageError } from './crawl.js';
 /** One-line description of the first drift finding, for the self-check error. */
@@ -476,6 +476,10 @@ async function captureSurface(page, surface, width, s) {
     // count toward the network-aware settle — a request that starts during navigation
     // fired its event before captureStyleMap could attach a listener of its own.
     const requests = trackInflightRequests(page);
+    // Same timing for the residue watcher: a data request that fails during navigation
+    // must be seen. Keyed on the BASE surface key so a liveStates split (`-loading`/
+    // `-loaded`) and every width dedupe to one `<surface>·<endpoint>` residue entry.
+    const residue = trackDataResidue(page, s.replayUrl, surface.metadata?.surfaceKey ?? surface.key);
     try {
         await surface.go(page);
         const map = await captureStyleMap(page, {
@@ -488,6 +492,9 @@ async function captureSurface(page, surface, width, s) {
         });
         if (s.selfCheck)
             await assertDeterministic(page, surface, map, s.captureText, requests.pending);
+        // Attach data-residue AFTER the self-check re-run so both runs' failures are folded
+        // (deduped in the watcher). Warn always; the recorded residue is what the gate reads.
+        attachDataResidue(map, residue.residue());
         const stem = path.join(s.baseDir, s.dir, `${surface.key}@${width}`);
         saveStyleMap(`${stem}.json.gz`, map);
         if (s.screenshots) {
@@ -499,6 +506,21 @@ async function captureSurface(page, surface, width, s) {
     }
     finally {
         requests.dispose();
+        residue.dispose();
+    }
+}
+/** Attach any observed data-residue to the map and NAME each failure on stderr — what
+ *  failed, what it means (fallback branch captured), what to do. One warning per
+ *  (surface, endpoint); the watcher already deduped across widths / the self-check. */
+function attachDataResidue(map, residue) {
+    if (!residue.length)
+        return;
+    map.dataResidue = residue;
+    for (const r of residue) {
+        // eslint-disable-next-line no-console
+        console.warn(`styleproof: surface '${r.surface}' — data request ${r.endpoint} FAILED during capture (${r.reason}). ` +
+            `The captured state renders this endpoint's fallback branch; states driven by its real responses are ` +
+            `uncaptured and unproven. Fixture it (page.route / liveStates) or acknowledge it in styleproof.data-residue.json.`);
     }
 }
 /**
@@ -527,6 +549,14 @@ export function resolveBaseDir(baseDir, env = process.env.STYLEPROOF_BASEDIR) {
 export function resolveScreenshots(screenshots, env = process.env.STYLEPROOF_SCREENSHOTS) {
     return screenshots ?? env !== '0';
 }
+/**
+ * The data-residue guard mode: `'gate'` (the v4 default) blocks the diff on an
+ * unacknowledged failing data endpoint; `'warn'` is the explicit opt-out that records +
+ * warns without gating. Single source of truth for the default, so the flip lives here.
+ */
+export function resolveDataResidue(mode) {
+    return mode ?? 'gate';
+}
 /**
  * Apply the capture defaults once, so explicit-surface and crawl capture can't
  * drift — the replay boundary, frozen clock and self-check policy resolve to the
@@ -541,6 +571,7 @@ function resolveSettings(c) {
         screenshots: resolveScreenshots(c.screenshots),
         replayFrom,
         replayUrl: c.replayUrl ?? process.env.STYLEPROOF_REPLAY_URL ?? '**/api/**',
+        dataResidue: resolveDataResidue(c.dataResidue),
         freezeClock: c.freezeClock ?? true,
         clockTime: c.clockTime ?? '2025-01-01T00:00:00Z',
         selfCheck: c.selfCheck ?? defaultSelfCheck(replayFrom),
@@ -584,19 +615,42 @@ function writeCoverageLedgerTest(settings, dir, expected, exclude, captureSurfac
         // the GATE (which reads expanded map filenames and can't see `surfaceKey` metadata)
         // compares literally — a liveStates surface's `-loading`/`-loaded` splits satisfy it.
         const ledgerExpected = expected == null ? null : translateExpected(expected, captureSurfaces);
-        const ledger = { version: 1, expected: ledgerExpected, exclude, determinism };
+        // Carry the residue-gate mode in the bundle so styleproof-diff knows whether an
+        // unacknowledged failing endpoint should BLOCK ('gate', the v4 default) or only
+        // inform ('warn', the explicit opt-out). Recorded verbatim so the bundle is
+        // self-documenting; an absent field (older bundles) is still read as warn, so
+        // maps captured before this default flip never start gating retroactively.
+        const ledger = {
+            version: 1,
+            expected: ledgerExpected,
+            exclude,
+            determinism,
+            dataResidue: settings.dataResidue,
+        };
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
-/** Record the real browser build into the capture bundle. The npm `@playwright/test`
- *  version (in the manifest) is only a proxy — the actual Chromium binary can change while
- *  it holds constant (a re-download, a different browser store, a CI image bump). The
- *  compatibility guard reads this back to refuse a cross-build compare instead of walling
- *  a PR with false diffs. Best-effort: an unavailable version leaves the guard as-is. */
+/** Record the real browser build into the capture bundle, then stamp the manifest. The
+ *  npm `@playwright/test` version (in the manifest) is only a proxy — the actual Chromium
+ *  binary can change while it holds constant (a re-download, a different browser store, a
+ *  CI image bump). The compatibility guard reads this back to refuse a cross-build compare
+ *  instead of walling a PR with false diffs. Best-effort: an unavailable version leaves
+ *  the guard as-is.
+ *
+ *  The manifest is stamped HERE, at the runner level, so every capture flow produces a
+ *  manifest-bearing dir — including a raw `STYLEMAP_DIR=x npx playwright test` run (the
+ *  fork capture workflow's shape), which never goes through the styleproof-map CLI. Since
+ *  v4 the diff refuses a map-bearing dir without one. It's written in the same test as
+ *  the sidecar (not a sibling test) because the manifest reads the sidecar back for
+ *  `browserVersion`, and fullyParallel gives sibling tests no ordering. styleproof-map
+ *  re-stamps a richer manifest (real spec hash, git identity) after the run; the runtime
+ *  fields the compare guard reads are the same either way. */
 function writeBrowserBuildTest(settings, dir) {
     test('styleproof browser build', ({ page }) => {
         const version = page.context().browser()?.version();
-        writeBrowserBuildSidecar(path.join(settings.baseDir, dir), version);
+        const outDir = path.join(settings.baseDir, dir);
+        writeBrowserBuildSidecar(outDir, version);
+        writeCaptureManifest({ dir: outDir, screenshots: settings.screenshots });
     });
 }
 export function defineStyleMapCapture(options) {