styleproof 3.21.0 → 4.0.1

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;