styleproof 3.20.0 → 4.0.0

package/dist/change-groups.js

@@ -0,0 +1,471 @@
+import { trackCount } from './describe.js';
+/**
+ * Pure grouping / classification of diff findings — the report's dedup brain,
+ * lifted out of the crop-and-PNG machinery so BOTH the visual report
+ * (`report.ts`, which renders screenshots on top) and the terminal differ
+ * (`bin/styleproof-diff.mjs`, a leaf that must not pull Playwright-adjacent
+ * modules) share ONE implementation. No `fs`, no `pngjs`, no `capture.js`: this
+ * is a leaf so a bin can import it directly (#186 — bins import leaves, not the
+ * barrel).
+ *
+ * What lives here: collapse logical→physical longhands and shorthand families
+ * (`summarizeProps`), strip reflow-casualty/derived longhands (`cleanFindings`),
+ * a canonical per-surface signature so surfaces that changed the SAME way group
+ * once (`signatureOf` / `groupBySignature`), and the shared-chrome tier that
+ * promotes a change spanning every hosting surface to a single callout
+ * (`classifyChrome`).
+ */
+// ── property summarisation: dedupe logical longhands, collapse shorthand
+//    families, humanize values ────────────────────────────────────────────────
+// Logical longhand → its physical equivalent (LTR, horizontal-tb). Dropped when
+// the physical one changed identically, so each change appears once.
+const LOGICAL_TO_PHYSICAL = (() => {
+    const m = {};
+    const sides = {
+        'block-start': 'top',
+        'block-end': 'bottom',
+        'inline-start': 'left',
+        'inline-end': 'right',
+    };
+    for (const [l, p] of Object.entries(sides)) {
+        for (const k of ['color', 'width', 'style'])
+            m[`border-${l}-${k}`] = `border-${p}-${k}`;
+        m[`margin-${l}`] = `margin-${p}`;
+        m[`padding-${l}`] = `padding-${p}`;
+        m[`inset-${l}`] = p;
+    }
+    const radius = {
+        'start-start': 'top-left',
+        'start-end': 'top-right',
+        'end-start': 'bottom-left',
+        'end-end': 'bottom-right',
+    };
+    for (const [l, p] of Object.entries(radius))
+        m[`border-${l}-radius`] = `border-${p}-radius`;
+    return m;
+})();
+// Length-valued 4-side families → CSS 1–4-value shorthand whenever all four
+// sides changed (e.g. `padding: 26px 24px → 28px`).
+const BOX4 = [
+    { short: 'margin', parts: ['top', 'right', 'bottom', 'left'].map((s) => `margin-${s}`) },
+    { short: 'padding', parts: ['top', 'right', 'bottom', 'left'].map((s) => `padding-${s}`) },
+    { short: 'border-width', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-width`) },
+    {
+        short: 'border-radius',
+        parts: ['top-left', 'top-right', 'bottom-right', 'bottom-left'].map((s) => `border-${s}-radius`),
+    },
+];
+// Colour/keyword families → one row only when all four sides match (else
+// per-side, which keeps each colour swatchable).
+const UNIFORM = [
+    { short: 'border-color', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-color`) },
+    { short: 'border-style', parts: ['top', 'right', 'bottom', 'left'].map((s) => `border-${s}-style`) },
+];
+const boxShorthand = ([t, r, b, l]) => t === r && r === b && b === l
+    ? t
+    : t === b && r === l
+        ? `${t} ${r}`
+        : r === l
+            ? `${t} ${r} ${b}`
+            : `${t} ${r} ${b} ${l}`;
+const PROP_ORDER = [
+    'display',
+    'position',
+    'grid-template-columns',
+    'grid-template-rows',
+    'flex-direction',
+    'justify-content',
+    'align-items',
+    'gap',
+    'margin',
+    'padding',
+    'border-width',
+    'border-style',
+    'border-color',
+    'border-radius',
+    'outline',
+    'background-color',
+    'background-image',
+    'color',
+    'box-shadow',
+    'opacity',
+    'transform',
+    'font-family',
+    'font-size',
+    'font-weight',
+    'line-height',
+    'letter-spacing',
+    'text-transform',
+    'text-align',
+];
+const orderIdx = (p) => {
+    const i = PROP_ORDER.indexOf(p);
+    return i === -1 ? PROP_ORDER.length : i;
+};
+function cleanVal(v) {
+    // Verbatim by design: no rounding. Rounding once showed alpha 0.18 as 0.2 —
+    // and could erase a real 0.18→0.2 diff entirely via the no-op filter below.
+    let s = v;
+    if (!s.includes('(')) {
+        const toks = s.split(' ');
+        if (toks.length > 1 && new Set(toks).size === 1)
+            s = `${toks[0]} ×${toks.length}`;
+    }
+    return s.replace(/rgba\(\s*0,\s*0,\s*0,\s*0\s*\)/g, 'transparent');
+}
+// These default to `currentColor`, so a `color` change drags them all along —
+// pure echoes, dropped when they match the `color` change.
+const CURRENTCOLOR_FOLLOWERS = [
+    'caret-color',
+    'outline-color',
+    'column-rule-color',
+    'text-decoration-color',
+    'text-emphasis-color',
+    '-webkit-text-fill-color',
+    '-webkit-text-stroke-color',
+];
+// "No value here" markers: a forced-state delta that doesn't apply, an unset
+// longhand, or a capture artifact where a path didn't line up. A change BETWEEN
+// two of these (e.g. `— → (gone)`) is meaningless and must never read as a diff.
+const NON_VALUE = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)', '(gone)']);
+export const isNonValue = (v) => NON_VALUE.has(v);
+/** Combine longhands into a shorthand value; all-non-value sides collapse to one. */
+const combineValues = (vals) => (vals.every(isNonValue) ? '(unset)' : vals.join(' '));
+// A flat sequence of independent shorthand/longhand collapse rules — each `if` is
+// one family, not nested logic. Pre-existing (moved verbatim from report.ts, where
+// it was already in the health baseline); splitting it per-family would scatter one
+// cohesive pass across a dozen tiny functions for no readability gain.
+// fallow-ignore-next-line complexity
+export function summarizeProps(props) {
+    const map = new Map(props.map((p) => [p.prop, { ...p }]));
+    for (const [logical, physical] of Object.entries(LOGICAL_TO_PHYSICAL)) {
+        const lo = map.get(logical);
+        const ph = map.get(physical);
+        if (lo && ph && lo.before === ph.before && lo.after === ph.after)
+            map.delete(logical);
+    }
+    const color = map.get('color');
+    if (color)
+        for (const f of CURRENTCOLOR_FOLLOWERS) {
+            const m = map.get(f);
+            if (m && m.before === color.before && m.after === color.after)
+                map.delete(f);
+        }
+    for (const fam of BOX4) {
+        const members = fam.parts.map((p) => map.get(p));
+        if (members.every((m) => !!m)) {
+            fam.parts.forEach((p) => map.delete(p));
+            map.set(fam.short, {
+                prop: fam.short,
+                before: boxShorthand(members.map((m) => m.before)),
+                after: boxShorthand(members.map((m) => m.after)),
+            });
+        }
+    }
+    const rg = map.get('row-gap');
+    const cg = map.get('column-gap');
+    if (rg && cg) {
+        map.delete('row-gap');
+        map.delete('column-gap');
+        map.set('gap', {
+            prop: 'gap',
+            before: rg.before === cg.before ? rg.before : `${rg.before} ${cg.before}`,
+            after: rg.after === cg.after ? rg.after : `${rg.after} ${cg.after}`,
+        });
+    }
+    for (const fam of UNIFORM) {
+        const members = fam.parts.map((p) => map.get(p)).filter((m) => !!m);
+        if (members.length === fam.parts.length &&
+            members.every((m) => m.before === members[0].before && m.after === members[0].after)) {
+            fam.parts.forEach((p) => map.delete(p));
+            map.set(fam.short, { prop: fam.short, before: members[0].before, after: members[0].after });
+        }
+    }
+    // outline-width/-style/-color → one `outline` row (offset stays separate).
+    const ow = map.get('outline-width');
+    const os = map.get('outline-style');
+    const oc = map.get('outline-color');
+    if (ow && os && oc) {
+        map.delete('outline-width');
+        map.delete('outline-style');
+        map.delete('outline-color');
+        map.set('outline', {
+            prop: 'outline',
+            before: combineValues([ow.before, os.before, oc.before]),
+            after: combineValues([ow.after, os.after, oc.after]),
+        });
+    }
+    return ([...map.values()]
+        .map((p) => ({ prop: p.prop, before: cleanVal(p.before), after: cleanVal(p.after) }))
+        // Drop no-ops: a value that didn't actually change, or a change between two
+        // "no value here" markers (`— → (gone)`), which carries no information.
+        .filter((p) => p.before !== p.after && !(isNonValue(p.before) && isNonValue(p.after)))
+        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop)));
+}
+/** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
+export function prettyLabel(p, cls) {
+    const tag = (p.split('>').pop() ?? '').trim().replace(/:nth-child\(\d+\)/, '') || 'el';
+    const first = cls.split(/\s+/)[0] ?? '';
+    return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
+}
+// ── surface-key helpers (pure — no map reads) ────────────────────────────────
+// Surface keys originate from artifact filenames — attacker-controlled in the
+// fork capture/report split, and they flow into the PRIVILEGED PR-comment summary
+// (the Action slices report.md above the first `### `). Strip the Markdown/HTML
+// control characters (`` ` ``, [ ] ( ), < >, |) that could inject a link, image,
+// or table into that bot comment. Escaping at the render boundary — the keys stay
+// legible; only the injection surface is removed. (Crop FILENAMES are separately
+// restricted to [a-z0-9-]; this is the display-side equivalent.)
+export const safeKey = (s) => s.replace(/[`[\]()<>|]/g, '-');
+export const surfaceBase = (s) => s.replace(/@\d+$/, '');
+export const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
+export function pushSurfaceWidth(byBase, base, surface) {
+    const arr = byBase.get(base) ?? [];
+    arr.push(surfaceWidth(surface));
+    byBase.set(base, arr);
+}
+export function renderSurfaceGroups(byBase) {
+    return [...byBase]
+        .map(([base, ws]) => {
+        const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
+        return widths.length ? `${safeKey(base)} @ ${widths.join(', ')}` : safeKey(base);
+    })
+        .join(' · ');
+}
+/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
+export function formatSurfaceList(surfaces) {
+    const byBase = new Map();
+    for (const s of surfaces)
+        pushSurfaceWidth(byBase, surfaceBase(s), s);
+    return renderSurfaceGroups(byBase);
+}
+// ── signature + grouping ─────────────────────────────────────────────────────
+/** Group findings by their element path (one group per changed element). */
+export function groupByPath(findings) {
+    const byPath = new Map();
+    for (const f of findings) {
+        const arr = byPath.get(f.path) ?? [];
+        arr.push(f);
+        byPath.set(f.path, arr);
+    }
+    return [...byPath.values()];
+}
+// Grid-track longhands compute to width-dependent pixels (`282px ×2` at one width,
+// `282px 228px` at another), so the SAME responsive change would otherwise get a
+// different signature per width. Key them by track COUNT — what actually
+// identifies the change — so responsive variants group into one section.
+function sigValue(c) {
+    if (c.prop === 'grid-template-columns' || c.prop === 'grid-template-rows') {
+        return `${c.prop}=${trackCount(c.before)}t>${trackCount(c.after)}t`;
+    }
+    return `${c.prop}=${c.before}>${c.after}`;
+}
+/** Canonical signature of a surface's findings: surfaces that changed in the
+ *  same way collapse into one section + one image (the rects differ per width;
+ *  the change itself does not). */
+export function signatureOf(findings) {
+    return JSON.stringify(findings
+        .map((f) => ({
+        p: f.path,
+        k: f.kind,
+        t: f.kind === 'dom' ? f.change : f.kind === 'state' ? f.state : (f.pseudo ?? ''),
+        v: f.kind === 'dom' ? '' : summarizeProps(f.props).map(sigValue).join('|'),
+    }))
+        .sort((a, b) => `${a.p}|${a.k}|${a.t}`.localeCompare(`${b.p}|${b.k}|${b.t}`)));
+}
+/** A one-line heading for a change group: "1 element added", "2 elements restyled". */
+export function groupTitle(findings) {
+    const added = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'added').map((f) => f.path));
+    const removed = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'removed').map((f) => f.path));
+    const retagged = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'retagged').map((f) => f.path));
+    const restyled = new Set(findings.filter((f) => f.kind !== 'dom' && !added.has(f.path) && !removed.has(f.path)).map((f) => f.path));
+    const n = (c, w) => `${c} ${w}${c === 1 ? '' : 's'}`;
+    const parts = [];
+    if (added.size)
+        parts.push(`${n(added.size, 'element')} added`);
+    if (removed.size)
+        parts.push(`${n(removed.size, 'element')} removed`);
+    if (retagged.size)
+        parts.push(`${n(retagged.size, 'element')} retagged`);
+    if (restyled.size)
+        parts.push(`${n(restyled.size, 'element')} restyled`);
+    return parts.join(', ') || `${n(new Set(findings.map((f) => f.path)).size, 'element')} changed`;
+}
+// ── noise cleaning ───────────────────────────────────────────────────────────
+// Computed values that follow from an element's box size or position rather than
+// its styling. On any reflow they change all the way up the ancestor chain
+// (body, main, section…), so an element whose ONLY changes are these is a reflow
+// casualty: it must not anchor a crop region (that would zoom to the whole page)
+// nor clutter the findings. The certification differ keeps them — a reflow IS a
+// change to certify — but the visual report focuses on styling intent.
+const DERIVED_PROPS = new Set([
+    'width',
+    'height',
+    'block-size',
+    'inline-size',
+    'min-width',
+    'min-height',
+    'max-width',
+    'max-height',
+    'perspective-origin',
+    'transform-origin',
+    // position offsets shift with the document on any reflow
+    'top',
+    'right',
+    'bottom',
+    'left',
+    'inset-block-start',
+    'inset-block-end',
+    'inset-inline-start',
+    'inset-inline-end',
+]);
+// Props stripped from forced :hover/:focus/:active deltas specifically. Layout
+// and grid-track values that shift when a state forces a relayout are capture
+// noise, not interaction feedback — a state finding is meant to catch a changed
+// hover/focus/active *style* (colour, outline, shadow), not a reflow.
+const STATE_STRIP = new Set([
+    ...DERIVED_PROPS,
+    'grid-template-columns',
+    'grid-template-rows',
+    'grid-template-areas',
+    'grid-auto-columns',
+    'grid-auto-rows',
+    'grid-auto-flow',
+]);
+/** How many of a surface's summarised props are derived/box longhands — the count
+ *  the CLI folds behind `(+N derived longhands)`. Counts on the RAW finding props
+ *  (before cleaning) so the CLI can advertise exactly what it suppressed. */
+export function derivedLonghandCount(findings) {
+    let n = 0;
+    for (const f of findings) {
+        if (f.kind === 'dom')
+            continue;
+        const strip = f.kind === 'state' ? STATE_STRIP : DERIVED_PROPS;
+        for (const p of summarizeProps(f.props))
+            if (strip.has(p.prop))
+                n++;
+    }
+    return n;
+}
+/**
+ * Strip the noise the visual report shouldn't carry, cross-referencing each
+ * element's layers so the forced-state layer stops echoing the base:
+ *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
+ *   - forced states: drop derived + grid-track props, drop a delta the BASE
+ *     already changed (a `:hover color` that just follows a recoloured base is an
+ *     echo, not a dropped variant), and drop non-value↔non-value rows;
+ *   - any finding left with no props is removed entirely.
+ */
+export function cleanFindings(findings) {
+    const out = [];
+    for (const group of groupByPath(findings)) {
+        const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
+        const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        // For an ADDED element the base style is a full (unset)→value snapshot, not a
+        // delta — so a forced-state value is never an "echo" of a base *change*; keep
+        // every state row (suppressing them would drop a real :hover/:focus value).
+        const isAdded = group.some((f) => f.kind === 'dom' && f.change === 'added');
+        for (const f of group) {
+            if (f.kind === 'dom') {
+                out.push(f);
+                continue;
+            }
+            const props = f.kind === 'style'
+                ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) &&
+                    (isAdded || !baseChanged.has(p.prop)) &&
+                    !(isNonValue(p.before) && isNonValue(p.after)));
+            if (props.length)
+                out.push({ ...f, props });
+        }
+    }
+    return out;
+}
+/**
+ * Group surfaces that changed identically (same signature) into one group each,
+ * keeping the widest surface as the representative. The rects differ per width;
+ * the change itself does not. Callers pass the already-prepared per-surface
+ * findings (missing/one-sided surfaces excluded upstream).
+ */
+export function groupBySignature(prepared) {
+    const bySig = new Map();
+    for (const p of prepared) {
+        const sig = signatureOf(p.findings);
+        const existing = bySig.get(sig);
+        if (existing) {
+            existing.surfaces.push(p.surface);
+            if (surfaceWidth(p.surface) > surfaceWidth(existing.rep.surface))
+                existing.rep = p;
+        }
+        else {
+            bySig.set(sig, { surfaces: [p.surface], rep: p, findings: p.findings });
+        }
+    }
+    return [...bySig.values()];
+}
+/**
+ * The set of element paths that changed as SHARED CHROME — a persistent frame
+ * element (nav rail, header, footer) that every view renders and that moved on
+ * every view that renders it.
+ *
+ * The rule is STRUCTURAL, deliberately NOT a tunable percentage. For each changed
+ * path we compare two base-key sets:
+ *   - `hosting`  — the surface bases whose style map contains the path at all;
+ *   - `changed`  — the surface bases where the path appears in a finding.
+ * The path is chrome iff it is hosted on MORE THAN ONE base and it changed on
+ * EVERY base that hosts it (`changed ⊇ hosting`). "Every surface that has this
+ * element changed it" is exactly what shared chrome means; it needs no threshold
+ * to tune or defend. A content element (hosted on one base) fails the >1 guard; a
+ * partial change (some hosting bases unchanged) fails the coverage guard.
+ *
+ * Widths of one base collapse to the base key, so a nav present at @1280 and @390
+ * counts once. `surfacePaths` maps each captured surface key → the element paths
+ * it renders (union of both sides from the caller).
+ */
+export function chromePaths(changedOnSurfaces, surfacePaths) {
+    const hosting = new Map();
+    for (const [surface, paths] of surfacePaths) {
+        const base = surfaceBase(surface);
+        for (const p of paths) {
+            const set = hosting.get(p) ?? new Set();
+            set.add(base);
+            hosting.set(p, set);
+        }
+    }
+    const changed = new Map();
+    for (const f of changedOnSurfaces) {
+        const set = changed.get(f.path) ?? new Set();
+        for (const s of f.surfaces)
+            set.add(surfaceBase(s));
+        changed.set(f.path, set);
+    }
+    const chrome = new Set();
+    for (const [path, changedBases] of changed) {
+        const hostingBases = hosting.get(path) ?? new Set([path]);
+        if (hostingBases.size > 1 && [...hostingBases].every((b) => changedBases.has(b)))
+            chrome.add(path);
+    }
+    return chrome;
+}
+/**
+ * Split signature groups into the shared-chrome tier and the rest. A group is
+ * promoted only when EVERY one of its affected element paths is a chrome path
+ * (see `chromePaths`) — a group that entangles a frame change with a view's own
+ * content change stays in `rest` and renders in place, so we never hide a
+ * content change under a chrome banner.
+ */
+export function classifyChrome(groups, surfacePaths) {
+    // Findings tagged with the surfaces the group spans, so chromePaths sees which
+    // bases each path changed on across ALL groups (a path bundled with content on
+    // one view still counts as changed there).
+    const tagged = groups.flatMap((g) => g.findings.map((f) => ({ path: f.path, surfaces: g.surfaces })));
+    const paths = chromePaths(tagged, surfacePaths);
+    const chrome = [];
+    const rest = [];
+    for (const g of groups) {
+        const affected = new Set(g.findings.map((f) => f.path));
+        const isChrome = affected.size > 0 && [...affected].every((p) => paths.has(p));
+        (isChrome ? chrome : rest).push(g);
+    }
+    return { chrome, rest, chromePaths: paths };
+}

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

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';