styleproof 3.9.0 → 3.11.0

package/CHANGELOG.md

@@ -7,6 +7,38 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.11.0] - 2026-07-06
+
+### Added
+
+- **Report leads with the certification gates.** Source-of-truth step 3: the reviewer-
+  facing `report.md` now opens with a **Certification** block — the three source-of-truth
+  verdicts, so "is this green trustworthy?" is answered before the pixel details:
+  - **Coverage** — ✓ complete / ✗ INCOMPLETE (names the uncaptured surfaces) / ⚠ not asserted;
+  - **Determinism** — ✓ proven / ✗ NOT proven / ⚠ unknown;
+  - **Inventory** — ✓ navigable set unchanged / ⚠ N affordance(s) removed (names them) /
+    ✓ N removal(s), all acknowledged.
+
+  These verdicts were previously visible only in the `styleproof-diff` CI logs; now
+  they're in the artifact a reviewer actually reads. The block is omitted for an old
+  bundle that carries no certification metadata, so nothing changes for legacy captures.
+
+## [3.10.0] - 2026-07-06
+
+### Added
+
+- **Determinism provenance — a green needs a proven-deterministic capture.** Source-of-
+  truth step 2: a clean diff of two _nondeterministic_ captures is meaningless (they
+  might just happen to match). The capture now records its determinism basis in the
+  ledger — `self-checked` (captured twice, styles matched — a drift would have failed the
+  capture), `replayed` (rendered against a recorded HAR, deterministic by construction),
+  or `unproven` (neither) — and `styleproof-diff`:
+  - **blocks (exit 1) when either side is `unproven`**, even on an empty style diff;
+  - prints `✓ determinism proven — base X, head Y`, `✗ determinism NOT proven …`, or
+    `⚠ determinism basis unknown` (an older bundle with no field — degrades, never a
+    false red). The record-then-replay flow (base `self-checked`, head `replayed`) is
+    proven, as it should be.
+
 ## [3.9.0] - 2026-07-05
 
 ### Added

package/README.md

@@ -30,6 +30,7 @@ report. Intentional visual changes get approved; unexpected ones block or fail.
 - [Newly-added elements show their full style](#newly-added-elements-show-their-full-style)
 - [Reference](#reference)
   - [Blocking without branch protection](#blocking-without-branch-protection)
+- [Contributing](#contributing)
 - [License](#license)
 
 ## Why
@@ -759,6 +760,17 @@ Non-visual and framework-injected elements (`<meta>`/`<title>`/`<script>`/`<styl
 
 A programmatic API is also exported — `captureStyleMap`, `diffStyleMaps`, `generateStyleMapReport`, and the breakpoint helpers `detectViewportWidths` / `widthsFromBoundaries`, among others. For the capture internals, the approve-workflow trust model, and how to contribute, see [CONTRIBUTING](https://github.com/BenSheridanEdwards/StyleProof/blob/main/CONTRIBUTING.md) and the [`example/`](https://github.com/BenSheridanEdwards/StyleProof/tree/main/example) workflows.
 
+## Contributing
+
+See [CONTRIBUTING](https://github.com/BenSheridanEdwards/StyleProof/blob/main/CONTRIBUTING.md)
+for the dev loop, and [AGENTS.md](https://github.com/BenSheridanEdwards/StyleProof/blob/main/AGENTS.md)
+(the same file as `CLAUDE.md`) for the operating rules and agent tooling. The repo
+is wired for Claude Code with **Ponytail** (default lazy-coding mode), **GitNexus**
+(code-intelligence graph — MCP server in [`.mcp.json`](.mcp.json), skills in
+`.claude/skills/gitnexus/`), and **Graphify** (`/graphify` knowledge graph). The
+GitNexus index (`.gitnexus/`) and Graphify output (`graphify-out/`) are gitignored;
+build the index with `npx gitnexus analyze`.
+
 ## License
 
 MIT © Ben Sheridan-Edwards

package/bin/styleproof-diff.mjs

@@ -33,15 +33,15 @@ import {
   resolveCachedCaptureDirs,
 } from '../dist/map-store.js';
 import {
-  cliErrorMessage,
+  cachedMapsUnavailableMessage,
   isHelpArg,
   missingManualCaptureMessage,
   showHelpAndExit,
   unknownFlagMessage,
 } from '../dist/cli-errors.js';
-import { loadStyleMap } from '../dist/capture.js';
-import { auditRunInventory } from '../dist/inventory.js';
-import { auditCoverage, COVERAGE_LEDGER } from '../dist/coverage.js';
+import { readInventories } from '../dist/capture.js';
+import { auditRunInventory, readAckFile } from '../dist/inventory.js';
+import { auditCoverage, auditDeterminism, COVERAGE_LEDGER } from '../dist/coverage.js';
 import { isMapFile } from '../dist/map-store.js';
 
 const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.mjs$/, '');
@@ -52,25 +52,13 @@ const COMMAND = path.basename(process.argv[1] ?? 'styleproof-diff').replace(/\.m
 // offered and head no longer does BLOCKS unless acknowledged. Inert when no map
 // carries inventory, so every existing capture behaves exactly as before.
 
-// Mirror of indexDir() in diff.ts — the capture-dir file filter, kept local so the
-// bin needn't reach into diff internals for one small read.
-function dirInventories(dir) {
-  return fs
-    .readdirSync(dir)
-    .filter(isMapFile)
-    .map((f) => loadStyleMap(path.join(dir, f)))
-    .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
-}
-
 // `key -> reason` acknowledged removals. Optional file; absent → none. Malformed
 // JSON fails loud (exit 2) rather than silently un-acknowledging a real removal.
 function loadAllowRemoved() {
-  const p = path.resolve(process.env.STYLEPROOF_INVENTORY ?? 'styleproof.inventory.json');
-  if (!fs.existsSync(p)) return {};
   try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
+    return readAckFile();
   } catch (e) {
-    console.error(`${COMMAND}: ${p} is not valid JSON — ${e.message}`);
+    console.error(`${COMMAND}: ${e.message}`);
     process.exit(2);
   }
 }
@@ -78,8 +66,8 @@ function loadAllowRemoved() {
 // Read both sides' inventory and audit removals. MUST run before any cached-map
 // cleanup deletes the restored dirs. Returns null when no capture carries inventory.
 function readInventoryAudit(dirA, dirB) {
-  const baseInv = dirInventories(dirA);
-  const headInv = dirInventories(dirB);
+  const baseInv = readInventories(dirA);
+  const headInv = readInventories(dirB);
   if (![...baseInv, ...headInv].some((m) => m.inventory?.length)) return null;
   const allowed = loadAllowRemoved();
   return { allowed, ...auditRunInventory(baseInv, headInv, allowed) };
@@ -129,17 +117,14 @@ function capturedSurfaceKeys(dir) {
   ];
 }
 
-function readCoverageVerdict(dir) {
-  let ledger = null;
+function readLedger(dir) {
   const p = path.join(dir, COVERAGE_LEDGER);
-  if (fs.existsSync(p)) {
-    try {
-      ledger = JSON.parse(fs.readFileSync(p, 'utf8'));
-    } catch {
-      /* a corrupt ledger reads as no registry → "not asserted", never a false green */
-    }
+  if (!fs.existsSync(p)) return null;
+  try {
+    return JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch {
+    return null; // a corrupt ledger reads as no registry → "not asserted", never a false green
   }
-  return auditCoverage(capturedSurfaceKeys(dir), ledger);
 }
 
 // Print the completeness verdict; return true if it BLOCKS (a registered surface is missing).
@@ -165,6 +150,23 @@ function printCoverageVerdict(v) {
   return true;
 }
 
+// Print the determinism verdict; return true if it BLOCKS (a side's capture was unproven).
+function printDeterminismVerdict(v) {
+  if (v.status === 'proven') {
+    console.log(`\n✓ determinism proven — base ${v.base}, head ${v.head}`);
+    return false;
+  }
+  if (v.status === 'unknown') {
+    console.log('\n⚠ determinism basis unknown — a capture predates the determinism ledger; recapture to certify it.');
+    return false;
+  }
+  console.log(
+    `\n✗ determinism NOT proven — base ${v.base}, head ${v.head}. An unproven capture can drift, so a clean\n` +
+      '  diff might be two matching NONDETERMINISTIC reads. Enable selfCheck (default) or replay a recorded HAR.',
+  );
+  return true;
+}
+
 const HELP = `${COMMAND} — certify a CSS refactor by diffing two computed-style map captures
 
 usage: ${COMMAND} [baseRef] [options]
@@ -231,13 +233,7 @@ if (args.length <= 1) {
     dirA = cacheCapture.beforeDir;
     dirB = cacheCapture.afterDir;
   } catch (e) {
-    console.error(
-      [
-        `${COMMAND}: cached maps are not available for this comparison`,
-        cliErrorMessage(e),
-        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
-      ].join('\n'),
-    );
+    console.error(cachedMapsUnavailableMessage(COMMAND, 'comparison', e));
     process.exit(2);
   }
 } else {
@@ -257,14 +253,17 @@ if (args.length <= 1) {
 let result;
 let inventoryAudit = null;
 let coverageVerdict = null;
+let determinismVerdict = null;
 try {
   assertCompatibleMapDirs(dirA, dirB);
   result = diffStyleMapDirs(dirA, dirB);
-  // Read inventory + coverage here, while the (possibly cached/restored) dirs still
-  // exist — the finally below deletes them in cached-map mode. Coverage is the HEAD
-  // bundle's completeness basis.
+  // Read inventory + the certification ledgers here, while the (possibly cached/restored)
+  // dirs still exist — the finally below deletes them in cached-map mode. Coverage is the
+  // HEAD bundle's completeness basis; determinism needs both sides.
   inventoryAudit = readInventoryAudit(dirA, dirB);
-  coverageVerdict = readCoverageVerdict(dirB);
+  const headLedger = readLedger(dirB);
+  coverageVerdict = auditCoverage(capturedSurfaceKeys(dirB), headLedger);
+  determinismVerdict = auditDeterminism(readLedger(dirA), headLedger);
 } catch (e) {
   console.error(e.message);
   process.exit(2);
@@ -302,9 +301,13 @@ for (const sd of surfaces) {
 
 const invRemovals = printInventoryAudit(inventoryAudit);
 const coverageFails = printCoverageVerdict(coverageVerdict);
+const determinismFails = printDeterminismVerdict(determinismVerdict);
 
 if (jsonOut)
-  fs.writeFileSync(jsonOut, JSON.stringify({ counts, surfaces, compared, coverage: coverageVerdict }, null, 2));
+  fs.writeFileSync(
+    jsonOut,
+    JSON.stringify({ counts, surfaces, compared, coverage: coverageVerdict, determinism: determinismVerdict }, null, 2),
+  );
 
 const total = counts.dom + counts.style + counts.state;
 const newSurfaces = surfaces.filter((s) => s.missing).length;
@@ -313,14 +316,16 @@ const surfaceCount = surfaces.length;
 const newNote = newSurfaces ? ` (+${newSurfaces} new surface(s) with no baseline)` : '';
 const invNote = invRemovals ? ` + ${invRemovals} unacknowledged inventory removal(s)` : '';
 const covNote = coverageFails ? ` + ${coverageVerdict.uncovered.length} uncaptured registered surface(s)` : '';
-const clean = total === 0 && invRemovals === 0 && !coverageFails;
+const detNote = determinismFails ? ' + determinism unproven' : '';
+const clean = total === 0 && invRemovals === 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}`,
+    : `\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}`,
 );
-// 0 = identical, 1 = reviewable differences (incl. unacknowledged inventory removals or
-// an incomplete coverage registry), 3 = only new surfaces (no baseline). 2 = usage/capture error.
-process.exit(total > 0 || invRemovals > 0 || coverageFails ? 1 : newSurfaces > 0 ? 3 : 0);
+// 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);

package/bin/styleproof-report.mjs

@@ -12,7 +12,7 @@
  * Exit code 0 = no changes, 1 = report generated, 2 = usage error.
  */
 import { generateStyleMapReport } from '../dist/report.js';
-import { cliErrorMessage, isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
+import { cachedMapsUnavailableMessage, isHelpArg, showHelpAndExit, unknownFlagMessage } from '../dist/cli-errors.js';
 import {
   DEFAULT_MAP_STORE_BRANCH,
   DEFAULT_REMOTE,
@@ -116,13 +116,7 @@ if (args.length <= 1) {
     beforeDir = cacheCapture.beforeDir;
     afterDir = cacheCapture.afterDir;
   } catch (e) {
-    console.error(
-      [
-        `${COMMAND}: cached maps are not available for this report`,
-        cliErrorMessage(e),
-        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
-      ].join('\n'),
-    );
+    console.error(cachedMapsUnavailableMessage(COMMAND, 'report', e));
     process.exit(2);
   }
 } else {

package/dist/capture.d.ts

@@ -253,4 +253,12 @@ export declare function captureStyleMap(page: Page, options?: CaptureOptions): P
 export declare function saveStyleMap(filePath: string, map: StyleMap): void;
 /** Read a style map written by {@link saveStyleMap} (`.json` or `.json.gz`). */
 export declare function loadStyleMap(filePath: string): StyleMap;
+/**
+ * Read every surface map's navigable inventory from a capture dir, in the shape the
+ * inventory audit consumes. One home for "read the inventories out of a dir", shared
+ * by the diff CLI and the report (was duplicated in both).
+ */
+export declare function readInventories(dir: string): Array<{
+    inventory?: NavigableItem[];
+}>;
 export {};

package/dist/capture.js

@@ -2,6 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { gzipSync, gunzipSync } from 'node:zlib';
 import { classifyInventory, collectNavAffordances } from './inventory.js';
+import { isMapFile } from './map-store.js';
 const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"], [tabindex]';
 // Freeze motion so every captured value is a settled end state, not a frame
 // of an animation or a mid-flight transition after a forced :hover.
@@ -354,8 +355,9 @@ function detectOverlayCandidates({ ignore }) {
     });
 }
 /** Full (unpruned) computed styles for an element and its descendants, pseudo-elements included. */
-// Serialized into the browser by page.evaluate; cannot call module helpers.
-// fallow-ignore-next-line complexity -- pre-existing (cog 16); in-page fn can't call module helpers, so it can't be split. Exposed here only because the inventory feature edits this file. Refactor separately.
+// Serialized into the browser by page.evaluate; cannot call module helpers, so this
+// in-page fn (cog 16) can't be split into smaller ones. Pre-existing; refactor separately.
+// fallow-ignore-next-line complexity
 function snapSubtree({ selector, index }) {
     const el = document.querySelectorAll(selector)[index];
     const pathOf = (n) => {
@@ -777,3 +779,15 @@ export function loadStyleMap(filePath) {
             'Re-capture it — a partial write or interrupted upload produces an unreadable .gz.', { cause: e });
     }
 }
+/**
+ * Read every surface map's navigable inventory from a capture dir, in the shape the
+ * inventory audit consumes. One home for "read the inventories out of a dir", shared
+ * by the diff CLI and the report (was duplicated in both).
+ */
+export function readInventories(dir) {
+    return fs
+        .readdirSync(dir)
+        .filter(isMapFile)
+        .map((f) => loadStyleMap(path.join(dir, f)))
+        .map((m) => (m.inventory ? { inventory: m.inventory } : {}));
+}

package/dist/cli-errors.d.ts

@@ -1,6 +1,11 @@
 export declare function isHelpArg(arg: string | undefined): boolean;
 export declare function showHelpAndExit(help: string): never;
 export declare function cliErrorMessage(error: unknown): string;
+/**
+ * The "cached maps couldn't be restored" guidance, shared by styleproof-diff and
+ * styleproof-report (each names its own `purpose` — "comparison" / "report").
+ */
+export declare function cachedMapsUnavailableMessage(command: string, purpose: string, error: unknown): string;
 export declare function unknownFlagMessage(command: string, flag: string): string;
 export declare function missingSpecMessage(spec: string): string;
 export declare function playwrightMissingMessage(message: string): string;

package/dist/cli-errors.js

@@ -8,6 +8,17 @@ export function showHelpAndExit(help) {
 export function cliErrorMessage(error) {
     return error instanceof Error ? error.message : String(error);
 }
+/**
+ * The "cached maps couldn't be restored" guidance, shared by styleproof-diff and
+ * styleproof-report (each names its own `purpose` — "comparison" / "report").
+ */
+export function cachedMapsUnavailableMessage(command, purpose, error) {
+    return [
+        `${command}: cached maps are not available for this ${purpose}`,
+        cliErrorMessage(error),
+        'Next: run styleproof-map on the base and head commits to upload maps, or let CI recapture both sides.',
+    ].join('\n');
+}
 export function unknownFlagMessage(command, flag) {
     return `${command}: unknown flag: ${flag}\nNext: run ${command} --help to see supported options.`;
 }

package/dist/coverage.d.ts

@@ -36,13 +36,32 @@ export type CoverageGaps = {
 export declare function coverageGaps(capturedKeys: Iterable<string>, expected: Iterable<string>, exclude?: Record<string, string>): CoverageGaps;
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export declare const COVERAGE_LEDGER = "styleproof-coverage.json";
+/**
+ * How a capture's determinism was established — the second half of a trustworthy green.
+ * `self-checked`: captured twice and the computed styles matched (a drift would have
+ * failed the capture). `replayed`: rendered against a recorded HAR, so deterministic by
+ * construction. `unproven`: neither — the styles could have drifted and no one checked.
+ */
+export type DeterminismBasis = 'self-checked' | 'replayed' | 'unproven';
 export type CoverageLedger = {
     version: 1;
     /** The declared surface registry, or null when the spec asserted none. */
     expected: string[] | null;
     /** Reviewed opt-outs (`key → reason`). */
     exclude: Record<string, string>;
+    /** How this capture's determinism was established (3.10.0). Absent on older bundles. */
+    determinism?: DeterminismBasis;
+};
+export type DeterminismVerdict = {
+    /** `proven` — both sides self-checked or replayed; `unproven` — a side was neither, so
+     *  a clean diff might just be two matching NONDETERMINISTIC captures; `unknown` — an
+     *  older bundle with no determinism field (degrade, don't block). */
+    status: 'proven' | 'unproven' | 'unknown';
+    base: DeterminismBasis | 'unknown';
+    head: DeterminismBasis | 'unknown';
 };
+/** The gate's determinism call: a green needs BOTH sides proven (self-checked or replayed). */
+export declare function auditDeterminism(base: CoverageLedger | null, head: CoverageLedger | null): DeterminismVerdict;
 export type CoverageVerdict = {
     /** `complete` — every registered surface captured; `incomplete` — a registered
      *  surface is missing (gates); `unasserted` — no registry, so a green can only

package/dist/coverage.js

@@ -44,6 +44,17 @@ export function coverageGaps(capturedKeys, expected, exclude = {}) {
 // the suite guard — which checks the declared list — cannot see it).
 /** Bundled next to the maps, so the completeness basis travels with the capture. */
 export const COVERAGE_LEDGER = 'styleproof-coverage.json';
+/** The gate's determinism call: a green needs BOTH sides proven (self-checked or replayed). */
+export function auditDeterminism(base, head) {
+    const b = base?.determinism ?? 'unknown';
+    const h = head?.determinism ?? 'unknown';
+    const proven = (d) => d === 'self-checked' || d === 'replayed';
+    if (b === 'unproven' || h === 'unproven')
+        return { status: 'unproven', base: b, head: h };
+    if (proven(b) && proven(h))
+        return { status: 'proven', base: b, head: h };
+    return { status: 'unknown', base: b, head: h };
+}
 /** The gate's completeness call: audit what was actually captured against the ledger. */
 export function auditCoverage(capturedKeys, ledger) {
     if (!ledger || ledger.expected == null) {

package/dist/inventory.d.ts

@@ -21,6 +21,13 @@ export type InventoryDelta = {
 };
 /** `key -> reason` — removals that are intentional, reviewed, and on the record. */
 export type AllowedRemovals = Record<string, string>;
+/**
+ * Read the acknowledged-removals file (`$STYLEPROOF_INVENTORY` or
+ * `styleproof.inventory.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 loss; the advisory report degrades to `{}`).
+ */
+export declare function readAckFile(): AllowedRemovals;
 /** One raw navigable affordance as read from the DOM, before classification. */
 export type RawAffordance = {
     tag: string;

package/dist/inventory.js

@@ -17,6 +17,25 @@
 //
 // The harvest (`collectNavAffordances`) runs in-page, mirroring
 // `detectOverlayCandidates`; the diff/union/guard are pure and unit-testable.
+import fs from 'node:fs';
+import path from 'node:path';
+/**
+ * Read the acknowledged-removals file (`$STYLEPROOF_INVENTORY` or
+ * `styleproof.inventory.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 loss; the advisory report degrades to `{}`).
+ */
+export function readAckFile() {
+    const p = path.resolve(process.env.STYLEPROOF_INVENTORY ?? 'styleproof.inventory.json');
+    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 });
+    }
+}
 // ── in-page harvest ───────────────────────────────────────────────────────────
 // Split in two: the DOM-touching half stays thin (and serializable to the page,
 // like detectOverlayCandidates); the classification is pure and unit-testable.

package/dist/png-util.d.ts

@@ -0,0 +1,5 @@
+import type { PNG } from 'pngjs';
+/** An [r, g, b] colour triple, each channel 0–255. */
+export type RGB = [number, number, number];
+/** Paint a solid rectangle onto a PNG, clamped to the canvas bounds. */
+export declare function fillRect(png: PNG, x: number, y: number, w: number, h: number, [r, g, b]: RGB): void;

package/dist/png-util.js

@@ -0,0 +1,12 @@
+/** Paint a solid rectangle onto a PNG, clamped to the canvas bounds. */
+export function fillRect(png, x, y, w, h, [r, g, b]) {
+    for (let yy = Math.max(0, y); yy < Math.min(png.height, y + h); yy++) {
+        for (let xx = Math.max(0, x); xx < Math.min(png.width, x + w); xx++) {
+            const i = (yy * png.width + xx) << 2;
+            png.data[i] = r;
+            png.data[i + 1] = g;
+            png.data[i + 2] = b;
+            png.data[i + 3] = 255;
+        }
+    }
+}

package/dist/report.js

@@ -1,10 +1,13 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { PNG } from 'pngjs';
-import { loadStyleMap } from './capture.js';
+import { loadStyleMap, readInventories, } 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, trackCount } from './describe.js';
+import { auditCoverage, auditDeterminism, COVERAGE_LEDGER, } from './coverage.js';
+import { auditRunInventory, readAckFile } from './inventory.js';
 // Re-export the plain-English summariser so consumers (and tests) reach it
 // through the package's report module rather than a deep path.
 export { describeChange, colorName, tokenIndex, toHex } from './describe.js';
@@ -111,17 +114,6 @@ const PNG_OPTS = { deflateLevel: 9, filterType: -1, colorType: 2, inputColorType
 function writePng(file, png) {
     fs.writeFileSync(file, PNG.sync.write(png, PNG_OPTS));
 }
-function fillRect(png, x, y, w, h, [r, g, b]) {
-    for (let yy = Math.max(0, y); yy < Math.min(png.height, y + h); yy++) {
-        for (let xx = Math.max(0, x); xx < Math.min(png.width, x + w); xx++) {
-            const i = (yy * png.width + xx) << 2;
-            png.data[i] = r;
-            png.data[i + 1] = g;
-            png.data[i + 2] = b;
-            png.data[i + 3] = 255;
-        }
-    }
-}
 // The annotation hue: a magenta no real UI palette tends to use, so an outline
 // reads as a marker, not content. Drawn as a hollow rectangle (never filled) so
 // the UI underneath stays visible — and the clean image alongside proves the box
@@ -869,33 +861,89 @@ function renderContentSection(ctx) {
 // Pre-existing, grandfathered in the health baseline; the content layer is
 // rendered by extracted helpers, this only gained a call + headline branch.
 // fallow-ignore-next-line complexity
-export function generateStyleMapReport(opts) {
-    const { beforeDir, afterDir, outDir, imageBaseUrl = '', 
-    // Tighter than before (was 24) so the change fills the frame — the annotation
-    // box keeps enough context legible.
-    pad: padBy = 12, minWidth = 320, minHeight = 180, maxHeight = 1600, zoomBelow = 64, 
-    // More, smaller crops before collapsing (was 6), so distinct changes get their
-    // own focused frame rather than one wide merged one.
-    maxCrops = 8, foldDetailsAt = 0, } = opts;
-    const includeNoise = opts.includeLayoutNoise ?? false;
-    const includeContent = opts.includeContent ?? false;
-    const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
-    const liveCandidateLabels = volatileCount > 0 ? collectLiveCandidateLabels(beforeDir, afterDir) : [];
-    fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
-    // Focus each surface on styling intent: drop reflow-casualty props, suppress
-    // forced-state echoes of base changes, and remove non-value noise (see
-    // cleanFindings), unless includeLayoutNoise is set. Surfaces left with no real
-    // change are dropped.
-    const prepared = surfaces
-        .map((sd) => ({
-        sd,
-        findings: sd.missing || includeNoise ? sd.findings : cleanFindings(sd.findings),
-    }))
-        .filter((p) => p.sd.missing || p.findings.length > 0);
-    // Group surfaces that changed in the SAME way (the rects differ per width; the
-    // change itself does not) so an identical change shows once, not once per
-    // surface — with one representative image (the widest surface in the group).
-    const missing = prepared.filter((p) => p.sd.missing);
+function readLedgerFile(dir) {
+    const p = path.join(dir, COVERAGE_LEDGER);
+    if (!fs.existsSync(p))
+        return null;
+    try {
+        return JSON.parse(fs.readFileSync(p, 'utf8'));
+    }
+    catch {
+        return null;
+    }
+}
+function surfaceKeysIn(dir) {
+    return [
+        ...new Set(fs
+            .readdirSync(dir)
+            .filter(isMapFile)
+            .map((f) => f.replace(/@\d+\.json(\.gz)?$/, ''))),
+    ];
+}
+// ── Certification renderers ──────────────────────────────────────────────────────
+// Each maps one source-of-truth verdict to its report line. Kept as separate one-
+// verdict functions so certificationLines stays a thin orchestrator (and each stays
+// well under the complexity gate).
+function coverageLine(cov) {
+    if (cov.basis === 'complete')
+        return `- **Coverage** — ✓ complete (all ${cov.registrySize} registered surface(s) captured)`;
+    if (cov.basis === 'incomplete')
+        return `- **Coverage** — ✗ INCOMPLETE (${cov.uncovered.length} registered surface(s) not captured: ${cov.uncovered.join(', ')})`;
+    return '- **Coverage** — ⚠ not asserted (no `expected` registry; certifies only the captured surfaces)';
+}
+function determinismLine(det) {
+    if (det.status === 'proven')
+        return `- **Determinism** — ✓ proven (base ${det.base}, head ${det.head})`;
+    if (det.status === 'unproven')
+        return `- **Determinism** — ✗ NOT proven (base ${det.base}, head ${det.head}) — a clean diff could be two nondeterministic reads`;
+    return '- **Determinism** — ⚠ unknown (a capture predates the determinism ledger)';
+}
+function inventoryLine(inv) {
+    if (inv.unexplained.length > 0) {
+        const keys = inv.unexplained.map((i) => i.key);
+        return `- **Inventory** — ⚠ ${inv.unexplained.length} navigable affordance(s) removed, unacknowledged: ${keys.slice(0, 8).join(', ')}${keys.length > 8 ? ', …' : ''}`;
+    }
+    if (inv.delta.removed.length > 0)
+        return `- **Inventory** — ✓ ${inv.delta.removed.length} removal(s), all acknowledged`;
+    return '- **Inventory** — ✓ navigable set unchanged';
+}
+// Acknowledged removals for the report — lenient: a missing OR malformed ack file
+// just means no acknowledgements. (The diff CLI fails loud on malformed instead,
+// because in CI an unreadable ack file must not silently un-acknowledge a real loss;
+// the report is advisory, so it degrades quietly.)
+function readAcknowledgedRemovals() {
+    try {
+        return readAckFile();
+    }
+    catch {
+        return {};
+    }
+}
+/**
+ * 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.
+ * Empty when the bundle carries no certification metadata (an old capture).
+ */
+function certificationLines(beforeDir, afterDir) {
+    const baseLedger = readLedgerFile(beforeDir);
+    const headLedger = readLedgerFile(afterDir);
+    const inv = auditRunInventory(readInventories(beforeDir), readInventories(afterDir), readAcknowledgedRemovals());
+    const hasLedger = baseLedger !== null || headLedger !== null;
+    const hasInvChange = inv.delta.removed.length > 0 || inv.delta.added.length > 0;
+    if (!hasLedger && !hasInvChange)
+        return [];
+    return [
+        '**Certification**',
+        coverageLine(auditCoverage(surfaceKeysIn(afterDir), headLedger)),
+        determinismLine(auditDeterminism(baseLedger, headLedger)),
+        inventoryLine(inv),
+        '',
+    ];
+}
+// Group surfaces that changed in the SAME way (the rects differ per width; the change
+// itself does not) so an identical change shows once, not once per surface — keeping
+// the widest surface as the representative image.
+function groupBySignature(prepared) {
     const bySig = new Map();
     for (const p of prepared) {
         if (p.sd.missing)
@@ -911,9 +959,11 @@ export function generateStyleMapReport(opts) {
             bySig.set(sig, { surfaces: [p.sd.surface], rep: p, findings: p.findings });
         }
     }
-    const changeGroups = [...bySig.values()];
-    // Counts reflect the GROUPED view: each distinct change counts once, not once
-    // per surface it appears on (after shorthand/dedupe collapsing).
+    return [...bySig.values()];
+}
+// Counts reflect the GROUPED view: each distinct change counts once, not once per
+// surface it appears on (after shorthand/dedupe collapsing).
+function countShownChanges(changeGroups) {
     const shown = { dom: 0, style: 0, state: 0 };
     for (const cg of changeGroups)
         for (const f of cg.findings) {
@@ -924,6 +974,254 @@ export function generateStyleMapReport(opts) {
             else
                 shown.state += summarizeProps(f.props).length;
         }
+    return shown;
+}
+// The identical / changed / new-surface summary line(s). Split out (with an early
+// return for the all-identical case) so reportHeadline stays flat.
+function summaryLines(args) {
+    const { changeGroups, missing, shown, changedSurfaceCount, contentCount } = args;
+    if (changeGroups.length === 0 && missing.length === 0) {
+        return [
+            contentCount > 0
+                ? '✓ Computed styles identical: every longhand, pseudo-element, and hover/focus/active state matches. See the advisory content changes below.'
+                : '✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.',
+        ];
+    }
+    const md = [];
+    if (changeGroups.length > 0) {
+        md.push(`**${changeCountLabel(shown)}** across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
+    }
+    if (missing.length > 0) {
+        if (changeGroups.length > 0)
+            md.push('');
+        md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for review. ` +
+            `Approve them before they become the baseline.`);
+    }
+    return md;
+}
+// The headline summary lines between the certification block and the per-surface
+// detail: identical-vs-changed, new-surface count, live-region note, advisory-content
+// note. Extracted so generateStyleMapReport stays orchestration, not prose.
+function reportHeadline(args) {
+    const { changeGroups, missing, shown, changedSurfaceCount, volatileCount, liveCandidateLabels, contentCount } = args;
+    const md = summaryLines({ changeGroups, missing, shown, changedSurfaceCount, contentCount });
+    if (volatileCount > 0) {
+        const candidates = liveCandidateLabels.length
+            ? ` Auto-detected live-state candidate(s): ${liveCandidateLabels.slice(0, 5).join('; ')}.`
+            : '';
+        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check.${candidates}_`);
+    }
+    if (contentCount > 0 && (changeGroups.length > 0 || missing.length > 0)) {
+        md.push('', `📝 _${contentCount} advisory content change(s) below — they don't affect the check._`);
+    }
+    return md;
+}
+// Collapse many crops into one merged frame when a change scatters across more regions
+// than maxCrops would show — the union of all their boxes on each side.
+function collapseGroups(groups) {
+    return [
+        groups.reduce((acc, g) => ({
+            paths: [...acc.paths, ...g.paths],
+            before: visible(acc.before) && visible(g.before) ? union(acc.before, g.before) : (acc.before ?? g.before),
+            after: visible(acc.after) && visible(g.after) ? union(acc.after, g.after) : (acc.after ?? g.after),
+        })),
+    ];
+}
+// Crop, composite, annotate and (for small changes) zoom the before/after pair for one
+// region, writing the PNGs and returning the image markdown + the images sidecar. The
+// dense pixel work, isolated from renderRegion's prose.
+function buildRegionImages(args) {
+    const { g, region, regionFindings, sd, mapA, mapB, pngA, pngB, ctx, cropSeq } = args;
+    const { img, outDir, minWidth, minHeight, maxHeight, zoomBelow } = ctx;
+    // Crop the SAME page rectangle from both sides — the union of where the change sits
+    // on each side — so the pair lines up exactly and the reviewer compares like-for-like
+    // instead of playing spot-the-difference. (Centring each side on its own moved box
+    // would shift the background between them.)
+    const cropBox = visible(g.before) && visible(g.after) ? union(g.before, g.after) : region;
+    const w = Math.max(minWidth, cropBox.w);
+    const h = Math.min(maxHeight, Math.max(minHeight, cropBox.h));
+    // Path-safe, report-unique stem: `hero@1280` → `hero-1280-3` so relative image links
+    // resolve cleanly and two crops never collide on one filename.
+    const stem = `crops/${sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}`;
+    const before = cropPng(pngA, cropBox, w, h);
+    const after = cropPng(pngB, cropBox, w, h);
+    const composite = compositePair(before.png, after.png);
+    writePng(path.join(outDir, `${stem}-composite.png`), composite);
+    // Annotated twin: outline the LEAF changed elements (the added avatars, the restyled
+    // cards) on each side — not the merged container the crop anchors on, whose box would
+    // just trace the whole frame. An element present on only one side (added/removed) is
+    // boxed only there.
+    const markPaths = innermost([...new Set(regionFindings.map((f) => f.path))]);
+    const rectsA = markPaths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
+    const rectsB = markPaths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
+    const annotated = compositePair(annotateCrop(before, rectsA), annotateCrop(after, rectsB));
+    writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
+    const images = {
+        composite: `${stem}-composite.png`,
+        annotated: `${stem}-annotated.png`,
+    };
+    // Name the changed element(s) so the reviewer knows where to look without expanding
+    // anything (e.g. `changed: span.caret`).
+    const changedNames = [
+        ...new Set(markPaths
+            .map((p) => mapA.elements[p] ?? mapB.elements[p])
+            .filter((e) => !!e)
+            .map((e) => (e.cls ? `${e.tag}.${e.cls.split(/\s+/)[0]}` : e.tag))),
+    ].slice(0, 3);
+    const changedLabel = changedNames.length ? ` — changed: \`${changedNames.join('`, `')}\`` : '';
+    const ctxLabel = formatSurfaceWithContext(sd.surface, mapA, mapB);
+    // A sub-pixel change (e.g. a 2px font bump on a caret) is invisible at 1:1, so when
+    // the changed-element footprint is small, add a magnified crop that makes it obvious
+    // without the reviewer hunting. Anchored on the leaf rects.
+    const changed = unionRects([...rectsA, ...rectsB]);
+    const maxDim = changed ? Math.max(changed.w, changed.h) : 0;
+    let zoomFactor = 0;
+    if (zoomBelow > 0 && changed && maxDim > 0 && maxDim <= zoomBelow) {
+        const zBox = pad(changed, Math.max(maxDim, 16)); // ~3× the change for context
+        zoomFactor = Math.min(8, Math.max(2, Math.round(240 / Math.max(zBox.w, zBox.h))));
+        const zoom = compositePair(zoomCrop(pngA, zBox, rectsA, zoomFactor), zoomCrop(pngB, zBox, rectsB, zoomFactor));
+        writePng(path.join(outDir, `${stem}-zoom.png`), zoom);
+        images.zoom = `${stem}-zoom.png`;
+    }
+    // Both views shown by default: the clean before|after (the real UI) and the
+    // highlighted twin (magenta boxes on each change) so a reviewer sees WHAT changed and
+    // WHERE without expanding anything. Plain images (no link wrap) so a click opens the
+    // full-resolution file.
+    const md = [
+        '',
+        `![before ◀ │ ▶ after](${img(images.composite)})`,
+        '',
+        `<sub>◀ before  ·  after ▶ — ${ctxLabel}</sub>`,
+        '',
+        `![highlighted before ◀ │ ▶ after](${img(images.annotated)})`,
+        '',
+        `<sub>🔍 magenta boxes mark each change${changedLabel}</sub>`,
+    ];
+    if (images.zoom) {
+        md.push('', `![zoomed before ◀ │ ▶ after](${img(images.zoom)})`, '', `<sub>🔬 magnified ${zoomFactor}× — change too small to see at 1:1${changedLabel}</sub>`);
+    }
+    return { md, images };
+}
+// Render one crop region: its heading, the surface list, the before/after imagery (or a
+// note when there's nothing to show), and the per-crop change tables.
+function renderRegion(args) {
+    const { g, cg, mapA, mapB, pngA, pngB, describeCtx, ctx, cropSeq } = args;
+    const { sd } = cg.rep;
+    // Exactly the findings whose element lives inside THIS crop, so the tables sit
+    // directly under the screenshot that shows them — never a wall of changes spanning
+    // several crops with no way to tell which is which.
+    const regionFindings = cg.rep.findings.filter((f) => g.paths.some((root) => f.path === root || f.path.startsWith(root + ' > ')));
+    const surfaceList = cg.surfaces.length > 1
+        ? `_Identical across ${cg.surfaces.length} surfaces: ${formatSurfaceListWithContext(cg.surfaces, ctx.beforeDir)}_`
+        : `_${formatSurfaceWithContext(sd.surface, mapA, mapB)}_`;
+    const md = ['', `### ${regionHeading(g.paths, regionFindings)}`, '', surfaceList];
+    const region = visible(g.after) ? g.after : g.before;
+    let images = {};
+    if (region && pngA && pngB) {
+        const built = buildRegionImages({ g, region, regionFindings, sd, mapA, mapB, pngA, pngB, ctx, cropSeq });
+        md.push(...built.md);
+        images = built.images;
+    }
+    else if (!region) {
+        md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
+    }
+    else {
+        md.push('', '_No screenshots in these capture sets (run captures with `screenshots: true` for side-by-side crops)._');
+    }
+    // What this crop changed: plain-English bullets, then the property tables — folded
+    // under a toggle once they'd be a wall (foldDetailsAt).
+    md.push(...renderCropChanges(regionFindings, ctx.foldDetailsAt, describeCtx));
+    return { md, regionJson: { paths: g.paths, before: g.before, after: g.after, images } };
+}
+// Render one change group: load its representative maps/screenshots, split it into
+// crop regions (collapsing past maxCrops), and render each region top-to-bottom.
+function renderChangeGroup(cg, ctx, maxCrops, cropSeq) {
+    const { sd, findings: surfaceFindings } = cg.rep;
+    const mapA = loadStyleMap(findCapture(ctx.beforeDir, sd.surface));
+    const mapB = loadStyleMap(findCapture(ctx.afterDir, sd.surface));
+    // Theme-token reverse-indexes so colour changes can name `red-200` per side.
+    const describeCtx = { tokensBefore: tokenIndex(mapA.tokens), tokensAfter: tokenIndex(mapB.tokens) };
+    const pngA = readPng(path.join(ctx.beforeDir, `${sd.surface}.png`));
+    const pngB = readPng(path.join(ctx.afterDir, `${sd.surface}.png`));
+    const changedPaths = outermost([...new Set(surfaceFindings.map((f) => f.path))]);
+    let groups = groupRegions(changedPaths, mapA, mapB, ctx.padBy);
+    if (groups.length > maxCrops)
+        groups = collapseGroups(groups);
+    // Read top-to-bottom: one section per crop, in page order.
+    const topY = (g) => (visible(g.after) ? g.after.y : visible(g.before) ? g.before.y : Infinity);
+    groups.sort((a, b) => topY(a) - topY(b));
+    const md = [];
+    const regions = [];
+    for (const g of groups) {
+        cropSeq++;
+        const r = renderRegion({ g, cg, mapA, mapB, pngA, pngB, describeCtx, ctx, cropSeq });
+        md.push(...r.md);
+        regions.push(r.regionJson);
+    }
+    const json = {
+        surfaces: cg.surfaces,
+        representative: sd.surface,
+        regions,
+        findings: surfaceFindings,
+    };
+    return { md, json, findingCount: surfaceFindings.length, cropSeq };
+}
+// Render a new surface: present on only one side, so there's nothing to diff. Show the
+// captured side as a single screenshot and mark the heading for the PR comment.
+function renderNewSurface(p, ctx, cropSeq) {
+    const { img, outDir, maxHeight } = ctx;
+    const side = p.sd.missing === 'before' ? 'after' : 'before';
+    const srcDir = side === 'after' ? ctx.afterDir : ctx.beforeDir;
+    const map = loadStyleMap(findCapture(srcDir, p.sd.surface));
+    const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
+    const md = [
+        '',
+        `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`,
+        '',
+        `_${formatSurfaceWithContext(p.sd.surface, map)}_`,
+    ];
+    const json = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
+    if (png) {
+        cropSeq++;
+        const h = Math.min(maxHeight, png.height);
+        const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h).png;
+        const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
+        writePng(path.join(outDir, `${stem}.png`), crop);
+        md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${formatSurfaceWithContext(p.sd.surface, map)}${png.height > h ? ' (top of page)' : ''}</sub>`);
+        json.image = `${stem}.png`;
+    }
+    else {
+        md.push('', `_Captured only in the **${side}** set; no screenshot saved (run captures with \`screenshots: true\`)._`);
+    }
+    md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
+    return { md, json, cropSeq };
+}
+export function generateStyleMapReport(opts) {
+    const { beforeDir, afterDir, outDir, imageBaseUrl = '', 
+    // Tighter than before (was 24) so the change fills the frame — the annotation
+    // box keeps enough context legible.
+    pad: padBy = 12, minWidth = 320, minHeight = 180, maxHeight = 1600, zoomBelow = 64, 
+    // More, smaller crops before collapsing (was 6), so distinct changes get their
+    // own focused frame rather than one wide merged one.
+    maxCrops = 8, foldDetailsAt = 0, } = opts;
+    const includeNoise = opts.includeLayoutNoise ?? false;
+    const includeContent = opts.includeContent ?? false;
+    const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
+    const liveCandidateLabels = volatileCount > 0 ? collectLiveCandidateLabels(beforeDir, afterDir) : [];
+    fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
+    // Focus each surface on styling intent: drop reflow-casualty props, suppress
+    // forced-state echoes of base changes, and remove non-value noise (see
+    // cleanFindings), unless includeLayoutNoise is set. Surfaces left with no real
+    // change are dropped.
+    const prepared = surfaces
+        .map((sd) => ({
+        sd,
+        findings: sd.missing || includeNoise ? sd.findings : cleanFindings(sd.findings),
+    }))
+        .filter((p) => p.sd.missing || p.findings.length > 0);
+    const missing = prepared.filter((p) => p.sd.missing);
+    const changeGroups = groupBySignature(prepared);
+    const shown = countShownChanges(changeGroups);
     // Surfaces carrying a reviewable change — NOT the new (one-sided) ones, which
     // have no baseline to compare and are summarised on their own line below so the
     // headline never reads "0 changes" while warnings sit beneath it.
@@ -931,173 +1229,50 @@ export function generateStyleMapReport(opts) {
     const md = [];
     const json = [];
     const img = (rel) => (imageBaseUrl ? `${imageBaseUrl.replace(/\/$/, '')}/${rel}` : rel);
+    const ctx = {
+        beforeDir,
+        afterDir,
+        outDir,
+        img,
+        padBy,
+        minWidth,
+        minHeight,
+        maxHeight,
+        zoomBelow,
+        foldDetailsAt,
+    };
     // Opt-in, advisory: computed here so its count can colour the headline, but its
     // markdown is appended at the very end and it NEVER feeds the gate below.
     const contentSection = includeContent
         ? renderContentSection({ beforeDir, afterDir, outDir, img, padBy, minWidth, minHeight, maxHeight })
         : { md: [], count: 0 };
     md.push('## 🗺️ StyleProof report', '');
-    if (changeGroups.length === 0 && missing.length === 0) {
-        md.push(contentSection.count > 0
-            ? '✓ Computed styles identical: every longhand, pseudo-element, and hover/focus/active state matches. See the advisory content changes below.'
-            : '✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
-    }
-    else {
-        if (changeGroups.length > 0) {
-            md.push(`**${changeCountLabel(shown)}** across ${changeGroups.length} distinct change(s) in ${changedSurfaceCount} surface(s).`);
-        }
-        if (missing.length > 0) {
-            if (changeGroups.length > 0)
-                md.push('');
-            md.push(`🆕 **${missing.length} new surface(s)** captured with no baseline to compare — shown below for review. ` +
-                `Approve them before they become the baseline.`);
-        }
-    }
-    if (volatileCount > 0) {
-        const candidates = liveCandidateLabels.length
-            ? ` Auto-detected live-state candidate(s): ${liveCandidateLabels.slice(0, 5).join('; ')}.`
-            : '';
-        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check.${candidates}_`);
-    }
-    if (contentSection.count > 0 && (changeGroups.length > 0 || missing.length > 0)) {
-        md.push('', `📝 _${contentSection.count} advisory content change(s) below — they don't affect the check._`);
-    }
+    // Lead with the source-of-truth gates (coverage / determinism / inventory) so a
+    // reviewer reads "is this green trustworthy?" before the pixel details.
+    md.push(...certificationLines(beforeDir, afterDir));
+    md.push(...reportHeadline({
+        changeGroups,
+        missing,
+        shown,
+        changedSurfaceCount,
+        volatileCount,
+        liveCandidateLabels,
+        contentCount: contentSection.count,
+    }));
     let totalFindings = 0;
     let cropSeq = 0;
     for (const cg of changeGroups) {
-        const { sd, findings: surfaceFindings } = cg.rep;
-        totalFindings += surfaceFindings.length;
-        const mapA = loadStyleMap(findCapture(beforeDir, sd.surface));
-        const mapB = loadStyleMap(findCapture(afterDir, sd.surface));
-        // Theme-token reverse-indexes so colour changes can name `red-200` per side.
-        const describeCtx = { tokensBefore: tokenIndex(mapA.tokens), tokensAfter: tokenIndex(mapB.tokens) };
-        const pngA = readPng(path.join(beforeDir, `${sd.surface}.png`));
-        const pngB = readPng(path.join(afterDir, `${sd.surface}.png`));
-        const changedPaths = outermost([...new Set(surfaceFindings.map((f) => f.path))]);
-        let groups = groupRegions(changedPaths, mapA, mapB, padBy);
-        if (groups.length > maxCrops) {
-            groups = [
-                groups.reduce((acc, g) => ({
-                    paths: [...acc.paths, ...g.paths],
-                    before: visible(acc.before) && visible(g.before) ? union(acc.before, g.before) : (acc.before ?? g.before),
-                    after: visible(acc.after) && visible(g.after) ? union(acc.after, g.after) : (acc.after ?? g.after),
-                })),
-            ];
-        }
-        // Read top-to-bottom: one section per crop, in page order.
-        const topY = (g) => (visible(g.after) ? g.after.y : visible(g.before) ? g.before.y : Infinity);
-        groups.sort((a, b) => topY(a) - topY(b));
-        const surfaceJson = {
-            surfaces: cg.surfaces,
-            representative: sd.surface,
-            regions: [],
-        };
-        for (const g of groups) {
-            cropSeq++;
-            // Exactly the findings whose element lives inside THIS crop, so the tables
-            // sit directly under the screenshot that shows them — never a wall of
-            // changes spanning several crops with no way to tell which is which.
-            const regionFindings = surfaceFindings.filter((f) => g.paths.some((root) => f.path === root || f.path.startsWith(root + ' > ')));
-            const surfaceList = cg.surfaces.length > 1
-                ? `_Identical across ${cg.surfaces.length} surfaces: ${formatSurfaceListWithContext(cg.surfaces, beforeDir)}_`
-                : `_${formatSurfaceWithContext(sd.surface, mapA, mapB)}_`;
-            md.push('', `### ${regionHeading(g.paths, regionFindings)}`, '', surfaceList);
-            const region = visible(g.after) ? g.after : g.before;
-            let images = {};
-            if (region && pngA && pngB) {
-                // Crop the SAME page rectangle from both sides — the union of where the
-                // change sits on each side — so the pair lines up exactly and the reviewer
-                // compares like-for-like instead of playing spot-the-difference. (Centring
-                // each side on its own moved box would shift the background between them.)
-                const cropBox = visible(g.before) && visible(g.after) ? union(g.before, g.after) : region;
-                const w = Math.max(minWidth, cropBox.w);
-                const h = Math.min(maxHeight, Math.max(minHeight, cropBox.h));
-                // Path-safe, report-unique stem: `hero@1280` → `hero-1280-3` so relative
-                // image links resolve cleanly and two crops never collide on one filename.
-                const stem = `crops/${sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}`;
-                const before = cropPng(pngA, cropBox, w, h);
-                const after = cropPng(pngB, cropBox, w, h);
-                const composite = compositePair(before.png, after.png);
-                writePng(path.join(outDir, `${stem}-composite.png`), composite);
-                // Annotated twin: outline the LEAF changed elements (the added avatars, the
-                // restyled cards) on each side — not the merged container the crop anchors
-                // on, whose box would just trace the whole frame. An element present on only
-                // one side (added/removed) is boxed only there.
-                const markPaths = innermost([...new Set(regionFindings.map((f) => f.path))]);
-                const rectsA = markPaths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
-                const rectsB = markPaths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
-                const annotated = compositePair(annotateCrop(before, rectsA), annotateCrop(after, rectsB));
-                writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
-                images = { composite: `${stem}-composite.png`, annotated: `${stem}-annotated.png` };
-                // Name the changed element(s) so the reviewer knows where to look without
-                // expanding anything (e.g. `changed: span.caret`).
-                const changedNames = [
-                    ...new Set(markPaths
-                        .map((p) => mapA.elements[p] ?? mapB.elements[p])
-                        .filter((e) => !!e)
-                        .map((e) => (e.cls ? `${e.tag}.${e.cls.split(/\s+/)[0]}` : e.tag))),
-                ].slice(0, 3);
-                const changedLabel = changedNames.length ? ` — changed: \`${changedNames.join('`, `')}\`` : '';
-                const ctxLabel = formatSurfaceWithContext(sd.surface, mapA, mapB);
-                // A sub-pixel change (e.g. a 2px font bump on a caret) is invisible at 1:1,
-                // so when the changed-element footprint is small, add a magnified crop that
-                // makes it obvious without the reviewer hunting. Anchored on the leaf rects.
-                const changed = unionRects([...rectsA, ...rectsB]);
-                const maxDim = changed ? Math.max(changed.w, changed.h) : 0;
-                let zoomFactor = 0;
-                if (zoomBelow > 0 && changed && maxDim > 0 && maxDim <= zoomBelow) {
-                    const zBox = pad(changed, Math.max(maxDim, 16)); // ~3× the change for context
-                    zoomFactor = Math.min(8, Math.max(2, Math.round(240 / Math.max(zBox.w, zBox.h))));
-                    const zoom = compositePair(zoomCrop(pngA, zBox, rectsA, zoomFactor), zoomCrop(pngB, zBox, rectsB, zoomFactor));
-                    writePng(path.join(outDir, `${stem}-zoom.png`), zoom);
-                    images.zoom = `${stem}-zoom.png`;
-                }
-                // Both views shown by default: the clean before|after (the real UI) and the
-                // highlighted twin (magenta boxes on each change) so a reviewer sees WHAT
-                // changed and WHERE without expanding anything. Plain images (no link wrap)
-                // so a click opens the full-resolution file.
-                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${ctxLabel}</sub>`, '', `![highlighted before ◀ │ ▶ after](${img(images.annotated)})`, '', `<sub>🔍 magenta boxes mark each change${changedLabel}</sub>`);
-                if (images.zoom) {
-                    md.push('', `![zoomed before ◀ │ ▶ after](${img(images.zoom)})`, '', `<sub>🔬 magnified ${zoomFactor}× — change too small to see at 1:1${changedLabel}</sub>`);
-                }
-            }
-            else if (!region) {
-                md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
-            }
-            else {
-                md.push('', '_No screenshots in these capture sets (run captures with `screenshots: true` for side-by-side crops)._');
-            }
-            // What this crop changed: plain-English bullets, then the property tables —
-            // folded under a toggle once they'd be a wall (foldDetailsAt).
-            md.push(...renderCropChanges(regionFindings, foldDetailsAt, describeCtx));
-            surfaceJson.regions.push({ paths: g.paths, before: g.before, after: g.after, images });
-        }
-        surfaceJson.findings = surfaceFindings;
-        json.push(surfaceJson);
+        const r = renderChangeGroup(cg, ctx, maxCrops, cropSeq);
+        md.push(...r.md);
+        json.push(r.json);
+        totalFindings += r.findingCount;
+        cropSeq = r.cropSeq;
     }
-    // New surfaces: present on only one side, so there's nothing to diff. Show the
-    // captured side as a single screenshot and mark the heading for the PR comment.
     for (const p of missing) {
-        const side = p.sd.missing === 'before' ? 'after' : 'before';
-        const srcDir = side === 'after' ? afterDir : beforeDir;
-        const map = loadStyleMap(findCapture(srcDir, p.sd.surface));
-        const png = readPng(path.join(srcDir, `${p.sd.surface}.png`));
-        md.push('', `### \`${p.sd.surface}\` · new surface ${NEW_SURFACE_MARKER}`, '', `_${formatSurfaceWithContext(p.sd.surface, map)}_`);
-        const surfaceJson = { surface: p.sd.surface, missing: p.sd.missing, isNew: true };
-        if (png) {
-            cropSeq++;
-            const h = Math.min(maxHeight, png.height);
-            const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h).png;
-            const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
-            writePng(path.join(outDir, `${stem}.png`), crop);
-            md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${formatSurfaceWithContext(p.sd.surface, map)}${png.height > h ? ' (top of page)' : ''}</sub>`);
-            surfaceJson.image = `${stem}.png`;
-        }
-        else {
-            md.push('', `_Captured only in the **${side}** set; no screenshot saved (run captures with \`screenshots: true\`)._`);
-        }
-        md.push('', `_No baseline to compare against — this surface is new. Review and approve it before it becomes part of the baseline._`);
-        json.push(surfaceJson);
+        const r = renderNewSurface(p, ctx, cropSeq);
+        md.push(...r.md);
+        json.push(r.json);
+        cropSeq = r.cropSeq;
     }
     md.push(...contentSection.md);
     const reportMdPath = path.join(outDir, 'report.md');

package/dist/runner.js

@@ -458,11 +458,18 @@ function resolveSettings(c) {
  * `expected: null` records that the spec declared no registry, so a green can only
  * certify the captured surfaces. Runs on a capture run (dir set) only.
  */
-function writeCoverageLedgerTest(baseDir, dir, expected, exclude) {
+function writeCoverageLedgerTest(settings, dir, expected, exclude) {
     test('styleproof coverage ledger', () => {
-        const outDir = path.join(baseDir, dir);
+        const outDir = path.join(settings.baseDir, dir);
         fs.mkdirSync(outDir, { recursive: true });
-        const ledger = { version: 1, expected, exclude };
+        // Determinism basis: self-check ON proves it (a drift would have failed the capture);
+        // else a replay run is deterministic by construction; else it's unproven.
+        const determinism = settings.selfCheck
+            ? 'self-checked'
+            : settings.replayFrom
+                ? 'replayed'
+                : 'unproven';
+        const ledger = { version: 1, expected, exclude, determinism };
         fs.writeFileSync(path.join(outDir, COVERAGE_LEDGER), JSON.stringify(ledger, null, 2));
     });
 }
@@ -490,7 +497,7 @@ export function defineStyleMapCapture(options) {
     test.describe('styleproof capture', () => {
         test.skip(!dir, 'set STYLEMAP_DIR=<label> to capture computed-style maps');
         if (dir)
-            writeCoverageLedgerTest(settings.baseDir, dir, expected ?? null, exclude);
+            writeCoverageLedgerTest(settings, dir, expected ?? null, exclude);
         for (const surface of captureSurfaces) {
             if (surface.widths && surface.widths.length > 0) {
                 // Explicit widths: one parallelizable test per surface × width.
@@ -545,7 +552,7 @@ export function defineCrawlCapture(options) {
         // so it records `expected: null` (completeness honestly "not asserted": the crawl
         // captures what the nav links to, and can't prove that's every route in the app).
         if (dir)
-            writeCoverageLedgerTest(settings.baseDir, dir, null, {});
+            writeCoverageLedgerTest(settings, dir, null, {});
         test('discover surfaces by crawling links, then capture each', async ({ page }) => {
             // 1. Load the root and wait for its nav links to hydrate — an SPA renders them
             //    client-side, so they aren't in the initial HTML.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.9.0",
+  "version": "3.11.0",
   "description": "Catch every CSS change before it ships — review PRs and certify refactors by the browser's computed styles, not pixels. Works with any styling system.",
   "keywords": [
     "playwright",