styleproof 3.20.0 → 4.0.0

package/bin/styleproof-capture.mjs

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

package/bin/styleproof-diff.mjs

@@ -25,11 +25,27 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { diffStyleMapDirs, findingLabel } from '../dist/diff.js';
+// The shared grouping brain (leaf — no Playwright-adjacent imports) that already
+// dedupes the report: group identical change-sets across surfaces and fold derived
+// longhands. Used for the HUMAN output only; --json stays the raw machine contract.
+import {
+  cleanFindings,
+  groupBySignature,
+  groupByPath,
+  groupTitle,
+  summarizeProps,
+  derivedLonghandCount,
+  formatSurfaceList,
+  classifyChrome,
+  surfaceBase,
+} from '../dist/change-groups.js';
 import {
   DEFAULT_MAP_STORE_BRANCH,
   DEFAULT_REMOTE,
   assertCompatibleMapDirs,
   cleanupCachedCaptureDirs,
+  manifestlessError,
+  manifestlessSide,
   resolveCachedCaptureDirs,
 } from '../dist/map-store.js';
 import {
@@ -39,8 +55,9 @@ import {
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
-import { readInventories } from '../dist/capture.js';
+import { readInventories, readResidue, surfaceElementPaths } from '../dist/capture.js';
 import { auditRunInventory, readAckFile } from '../dist/inventory.js';
+import { auditRunResidue, readResidueAckFile } from '../dist/data-residue.js';
 import { auditCoverage, auditDeterminism, COVERAGE_LEDGER } from '../dist/coverage.js';
 import { isMapFile } from '../dist/map-store.js';
 
@@ -100,6 +117,70 @@ function printInventoryAudit(audit) {
   return unexplained.length;
 }
 
+// ── data-residue guard (gate by default) ─────────────────────────────────────────
+// A data-boundary request (matching `replayUrl`) that FAILED during capture means the
+// captured state embedded that endpoint's fallback branch — its response-driven states
+// are unproven (issue #205). Residue is recorded + warned at capture time; here the diff
+// SURFACES it, and — unless the head bundle opted down to `dataResidue: 'warn'` — an
+// unacknowledged failing endpoint BLOCKS (exit 1). Acknowledge intentional ones in
+// styleproof.data-residue.json. (Bundles captured before this field existed read as warn.)
+
+// `key -> reason` acknowledged failing endpoints. Malformed JSON fails loud (exit 2),
+// like the inventory ack file, so a broken file can't silently un-acknowledge a failure.
+function loadAcknowledgedResidue() {
+  try {
+    return readResidueAckFile();
+  } catch (e) {
+    console.error(`${COMMAND}: ${e.message}`);
+    process.exit(2);
+  }
+}
+
+// Audit the HEAD bundle's residue against the ack ledger, carrying whether the head
+// ledger armed the gate. Returns null when no captured map carried residue AND the
+// gate wasn't armed — so a clean healthy run prints/gates nothing (byte-identical).
+function readResidueAudit(dirB, armed) {
+  const headResidue = readResidue(dirB);
+  if (!armed && !headResidue.some((m) => m.dataResidue?.length)) return null;
+  const acknowledged = loadAcknowledgedResidue();
+  return { acknowledged, ...auditRunResidue(headResidue, acknowledged, armed) };
+}
+
+// Print the Data-residue section; return the count of UNACKNOWLEDGED failing endpoints
+// that BLOCK (only when the gate is armed). No-op/0 when there was nothing to audit.
+/** One line per residue entry: acknowledged entries show their reason; the rest are
+ *  marked ✗ (armed — will block) or ⚠ (warn mode). */
+function residueLine(r, ackReason, armed) {
+  if (ackReason !== undefined) return `  ${r.surface} · ${r.endpoint} (${r.reason}) — acknowledged: ${ackReason}`;
+  return `  ${armed ? '✗ ' : '⚠ '}${r.surface} · ${r.endpoint} (${r.reason})${armed ? ', unacknowledged' : ''}`;
+}
+
+/** The action footer: the gate (default) names the remedy; warn mode is the opt-out. */
+function residueFooter(armed, unacknowledgedCount) {
+  if (!unacknowledgedCount) return null;
+  return armed
+    ? `  → ${unacknowledgedCount} unacknowledged failing endpoint(s): fixture each (page.route / liveStates), acknowledge intentional ones in styleproof.data-residue.json {"<key>":"<why>"}, or opt down with \`dataResidue: "warn"\` in the capture spec.`
+    : '  → recorded and warned (dataResidue: "warn" — the opt-out). Remove it to restore the default gate that BLOCKS on these.';
+}
+
+function printResidueAudit(audit) {
+  if (!audit) return 0;
+  const { residue, unacknowledged, staleAcknowledgements, armed } = audit;
+  if (!residue.length && !staleAcknowledgements.length) {
+    console.log('\n🩹 Data residue: no failing data-boundary request during capture');
+    return 0;
+  }
+  console.log('\n🩹 Data residue (data-boundary requests that FAILED during capture — fallback branch captured):');
+  for (const r of residue) console.log(residueLine(r, audit.acknowledged[r.key], armed));
+  for (const k of staleAcknowledgements)
+    console.log(`  ⚠ stale acknowledgement (endpoint no longer failing/present): ${k}`);
+  const footer = residueFooter(armed, unacknowledged.length);
+  if (footer) console.log(footer);
+  // Only an ARMED gate blocks; warn-mode surfaces without gating. A stale acknowledgement
+  // always blocks when armed, so the ledger can't rot (mirrors the `exclude` guard).
+  return armed ? unacknowledged.length + staleAcknowledgements.length : 0;
+}
+
 // ── coverage provenance (the completeness basis of a green) ──────────────────────
 // The head bundle carries a coverage ledger (the declared registry). The gate audits
 // the ACTUALLY-captured surfaces against it, so "clean" states its basis — complete vs
@@ -254,7 +335,13 @@ let result;
 let inventoryAudit = null;
 let coverageVerdict = null;
 let determinismVerdict = null;
+let residueAudit = null;
+let surfacePaths = new Map();
 try {
+  // v4: a side without a manifest is unsupported — the same-environment guard can't be
+  // enforced, so refuse (exit 2 via the catch below) rather than compare on false footing.
+  const manifestless = manifestlessSide(dirA, dirB);
+  if (manifestless) throw new Error(manifestlessError(manifestless));
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
   // Read inventory + the certification ledgers here, while the (possibly cached/restored)
@@ -264,6 +351,12 @@ try {
   const headLedger = readLedger(dirB);
   coverageVerdict = auditCoverage(capturedSurfaceKeys(dirB), headLedger);
   determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
+  // Data-residue: the head bundle's failing data endpoints, gated only if its ledger
+  // armed `dataResidue: 'gate'`. Same "read while the dirs exist" rule as the ledgers.
+  residueAudit = readResidueAudit(dirB, headLedger?.dataResidue === 'gate');
+  // Element-path sets per surface, for the shared-chrome tier — same "read while
+  // the dirs exist" rule as the ledgers above.
+  surfacePaths = surfaceElementPaths(dirA, dirB);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -272,34 +365,92 @@ try {
 }
 const { surfaces, counts, compared } = result;
 
-for (const sd of surfaces) {
-  if (sd.missing) {
-    const side = sd.missing === 'before' ? 'after' : 'before';
-    console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
-    continue;
-  }
+// ── grouped human output ─────────────────────────────────────────────────────
+// Reuse the report's dedup so one real change doesn't print once per surface with
+// its derived-longhand echo: group surfaces that changed identically, fold the
+// size/position-derived longhands behind a count, and keep the per-surface tally
+// in each group's header line. --json below is untouched (the raw machine feed).
+
+// One finding's lines: a heading, then its summarised property deltas (the same
+// dedupe the report shows). Returns [] for a DOM finding (handled separately) or a
+// finding whose props all summarised away.
+function findingLines(f) {
+  if (f.kind === 'dom') return [];
+  const rows = summarizeProps(f.props);
+  if (!rows.length) return [];
+  const head =
+    f.kind === 'state'
+      ? `  [:${f.state}] ${findingLabel(f.path, f.cls)}${f.sub !== f.path ? ` ⇒ ${f.sub}` : ''}`
+      : `  ${findingLabel(f.path, f.cls)}${f.pseudo || ''}`;
+  return [head, ...rows.map((p) => `    ${p.prop}: ${p.before} → ${p.after}`)];
+}
+
+// A DOM finding's one-line heading (added/removed/retagged).
+function domLine(dom) {
+  return dom.change === 'retagged'
+    ? `  DOM retagged: ${dom.path} ${dom.detail ?? ''}`
+    : `  DOM ${dom.change}: ${findingLabel(dom.path, dom.cls)}`;
+}
+
+// The element lines for one change group, from its representative's cleaned
+// findings: one heading per element, then its summarised property deltas.
+function elementLines(findings) {
   const lines = [];
-  for (const f of sd.findings) {
-    if (f.kind === 'dom') {
-      lines.push(
-        f.change === 'retagged'
-          ? `  DOM retagged: ${f.path} ${f.detail}`
-          : `  DOM ${f.change}: ${findingLabel(f.path, f.cls)}`,
-      );
-    } else if (f.kind === 'style') {
-      lines.push(`  ${findingLabel(f.path, f.cls)}${f.pseudo || ''}`);
-      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
-    } else {
-      lines.push(`  [:${f.state}] ${findingLabel(f.path, f.cls)}${f.sub !== f.path ? ` ⇒ ${f.sub}` : ''}`);
-      for (const p of f.props) lines.push(`    ${p.prop}: ${p.before} → ${p.after}`);
-    }
+  for (const group of groupByPath(findings)) {
+    const dom = group.find((f) => f.kind === 'dom');
+    if (dom) lines.push(domLine(dom));
+    for (const f of group) lines.push(...findingLines(f));
   }
-  console.log(`\n${sd.surface}: ${lines.filter((l) => !l.startsWith('    ')).length} element(s) differ`);
+  return lines;
+}
+
+// New (one-sided) surfaces keep their own line, unchanged.
+for (const sd of surfaces) {
+  if (!sd.missing) continue;
+  const side = sd.missing === 'before' ? 'after' : 'before';
+  console.log(`\n${sd.surface}: new surface — captured only in the ${side} set, no baseline to compare`);
+}
+
+// Group the changed surfaces the way the report does, so an identical change
+// across N surfaces prints once (with the count), not N times.
+const preparedForGrouping = surfaces
+  .filter((sd) => !sd.missing)
+  // Carry the RAW findings too, so we can report how many derived longhands the
+  // grouped view folded (the cleaned findings have them already removed).
+  .map((sd) => ({ surface: sd.surface, findings: cleanFindings(sd.findings), raw: sd.findings }))
+  .filter((p) => p.findings.length > 0);
+
+function printGroup(cg) {
+  const lines = elementLines(cg.findings);
+  const derived = derivedLonghandCount(cg.rep.raw);
+  const foldNote = derived > 0 ? ` (+${derived} derived longhand${derived === 1 ? '' : 's'})` : '';
+  const others = cg.surfaces.length - 1;
+  const scope =
+    others > 0
+      ? `${cg.rep.surface} (+${others} more surface${others === 1 ? '' : 's'}: ${formatSurfaceList(cg.surfaces)})`
+      : cg.rep.surface;
+  console.log(`\n${scope}: ${groupTitle(cg.findings)}${foldNote}`);
   for (const line of lines.slice(0, MAX)) console.log(line);
   if (lines.length > MAX) console.log(`  ... and ${lines.length - MAX} more lines (re-run with --max ${lines.length})`);
 }
 
+// Shared-chrome tier: a change that rode the frame every view draws (nav/header)
+// gets one banner up top, then its detail — so the reviewer reads "the nav changed
+// everywhere" once, not once per surface entry. Presentational only.
+const grouped = groupBySignature(preparedForGrouping);
+const { chrome, rest } = classifyChrome(grouped, surfacePaths);
+if (chrome.length) {
+  // Base count from the pre-cleanup surface set (dirB may be deleted by now).
+  const bases = new Set([...surfacePaths.keys()].map(surfaceBase)).size;
+  console.log(
+    `\n🧱 Global chrome change(s) — across all ${bases} surface(s): ${chrome.length} change(s) rode the shared frame every view draws (a persistent nav, header, or footer).`,
+  );
+  for (const cg of chrome) printGroup(cg);
+}
+for (const cg of rest) printGroup(cg);
+
 const invRemovals = printInventoryAudit(inventoryAudit);
+const residueFails = printResidueAudit(residueAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
 const determinismFails = printDeterminismVerdict(determinismVerdict);
 
@@ -335,6 +486,16 @@ if (jsonOut) {
                 inventoryNote:
                   'no captured map carried an inventory — set `inventory: true` in the capture spec to arm the navigable-removal gate',
               }),
+          // Additive data-residue field — the head bundle's failing data endpoints, parallel
+          // to inventory. `null` when nothing failed and the gate wasn't armed. `armed` says
+          // whether `unacknowledged` blocks; `blocking` is the CI-gating count.
+          dataResidue: residueAudit && {
+            armed: residueAudit.armed,
+            failing: residueAudit.residue.map((r) => r.key),
+            unacknowledged: residueAudit.unacknowledged.map((r) => r.key),
+            staleAcknowledgements: residueAudit.staleAcknowledgements,
+            blocking: residueFails,
+          },
         },
         null,
         2,
@@ -352,17 +513,21 @@ const newSurfaces = surfaces.filter((s) => s.missing).length;
 const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
+// residueFails counts unacknowledged failing endpoints AND stale acknowledgements (both gate).
+const resNote = residueFails ? ` + ${residueFails} data-residue gate failure(s) (unacknowledged or stale)` : '';
 const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
 const detNote = determinismFails ? ' + determinism unproven' : '';
-const clean = total === 0 && invRemovals === 0 && !coverageFails && !determinismFails;
+const clean = total === 0 && invRemovals === 0 && residueFails === 0 && !coverageFails && !determinismFails;
 console.log(
   clean
     ? newSurfaces === 0
       ? `\n✓ 0 changed surfaces across ${compared} captured surface(s): every computed style, pseudo-element, and hover/focus/active state matches`
       : `\nℹ ${newSurfaces} new surface(s) captured with no baseline to compare — review before baselining`
-    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${covNote}${detNote}`,
+    : `\n✗ ${counts.dom} DOM change(s), ${counts.style} computed-style difference(s), ${counts.state} state-delta difference(s) across ${surfaceCount} surfaces${newNote}${invNote}${resNote}${covNote}${detNote}`,
 );
 // 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals, an
-// incomplete coverage registry, or an unproven-determinism capture), 3 = only new surfaces
-// (no baseline). 2 = usage/capture error.
-process.exit(total > 0 || invRemovals > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0);
+// unacknowledged failing data endpoint under an armed residue gate, an incomplete coverage
+// registry, or an unproven-determinism capture), 3 = only new surfaces (no baseline). 2 = usage.
+process.exit(
+  total > 0 || invRemovals > 0 || residueFails > 0 || coverageFails || determinismFails ? 1 : newSurfaces > 0 ? 3 : 0,
+);

package/bin/styleproof-init.mjs

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

package/bin/styleproof-map.mjs

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

package/bin/styleproof-report.mjs

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

package/dist/capture-url.js

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

package/dist/capture.d.ts

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