styleproof 3.10.0 → 3.12.0

package/CHANGELOG.md

@@ -7,6 +7,45 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [3.12.0] - 2026-07-05
+
+### Changed
+
+- **Inventory guard: target-based keying.** Source-of-truth step 4 (keying honesty).
+  Tabs / menu items / nav buttons now key by the most stable identity the element
+  exposes — a developer-authored `data-testid`, else a non-generated `id` /
+  `aria-controls` — falling back to the label slug only when there's none. Previously
+  they always keyed by `slug(accessible-name)`, so a wobble in the **label** (a live
+  count badge like "COMMAND 5" → "COMMAND 3", a re-word) faked a `removed` + `added`
+  pair. Links were already immune (they key by href); this extends the same
+  target-based principle to the rest.
+
+  Framework-generated ids (React `useId` `:r0:`, Headless UI `headlessui-…`, Radix,
+  hashes) are rejected so keying on them can't _add_ churn. The design keeps the
+  guard's safe failure direction: the label-slug fallback turns a wobble into a
+  **surfaced** removed+added (a red you see and acknowledge), never a hidden real
+  removal. Give a nav item a `data-testid` to key it immune to its own text.
+
+  Note: an id-bearing affordance's key changes from `<role>:<slug>` to
+  `<role>:#<id>`, so existing `styleproof.inventory.json` acknowledgements for such
+  items need re-keying once (the guard names the new key).
+
+## [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

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,14 +33,14 @@ 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 { 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';
 
@@ -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) };
@@ -245,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 {

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/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;
@@ -28,9 +35,23 @@ export type RawAffordance = {
     name: string;
     /** pathname+search for a same-origin `<a href>`; null otherwise. Resolved in-page. */
     internalPath: string | null;
+    /** `data-testid` — developer-authored, trusted as a stable identity when present. */
+    testId: string | null;
+    /** `id` — used as a stable identity only when it doesn't look framework-generated. */
+    domId: string | null;
+    /** `aria-controls` (a tab's panel) — a stable identity when not framework-generated. */
+    controls: string | null;
 };
 /** In-page: collect visible navigable affordances. No classification. */
 export declare function collectNavAffordances(): RawAffordance[];
+/**
+ * Whether an `id` / `aria-controls` value is a STABLE identity worth keying on, vs a
+ * framework-generated one (React useId `:r0:`, Headless UI `headlessui-tabs-tab-3`,
+ * Radix `radix-:r1:`, Emotion hashes) that wobbles across renders/builds. Keying by a
+ * generated id would ADD churn, so those fall back to the label slug. (`data-testid` is
+ * developer-authored by definition, so it's trusted without this check.)
+ */
+export declare function isStableId(id: string | null | undefined): id is string;
 /** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
 export declare function classifyInventory(raw: RawAffordance[]): NavigableItem[];
 /** Harvest a page's inventory: thin in-page collect + pure classify. */

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.
@@ -56,6 +75,9 @@ export function collectNavAffordances() {
         role: (el.getAttribute('role') || '').toLowerCase(),
         name: nameOf(el),
         internalPath: el.tagName === 'A' ? internalPath(el) : null,
+        testId: el.getAttribute('data-testid'),
+        domId: el.getAttribute('id'),
+        controls: el.getAttribute('aria-controls'),
     }));
 }
 const slug = (s) => s
@@ -63,6 +85,48 @@ const slug = (s) => s
     .replace(/[^a-z0-9]+/g, '-')
     .replace(/^-+|-+$/g, '')
     .slice(0, 60);
+/**
+ * Whether an `id` / `aria-controls` value is a STABLE identity worth keying on, vs a
+ * framework-generated one (React useId `:r0:`, Headless UI `headlessui-tabs-tab-3`,
+ * Radix `radix-:r1:`, Emotion hashes) that wobbles across renders/builds. Keying by a
+ * generated id would ADD churn, so those fall back to the label slug. (`data-testid` is
+ * developer-authored by definition, so it's trusted without this check.)
+ */
+export function isStableId(id) {
+    if (!id)
+        return false;
+    const v = id.trim();
+    if (!v || v.length > 80)
+        return false;
+    if (v.includes(':'))
+        return false; // React useId / Radix scoped ids
+    if (/^(headlessui|radix|mui|chakra|reach|react-aria|floating-ui|downshift)-/i.test(v))
+        return false;
+    if (/^[0-9a-f]{8,}$/i.test(v))
+        return false; // hash-like
+    return true;
+}
+// A tab/menuitem/button's stable identity, if it exposes one: a data-testid (trusted),
+// else a non-generated id or aria-controls. Preferred over the label so a count badge
+// or re-label in the text doesn't move the key. (Links already key by href, the most
+// stable target of all.) When absent, we fall back to the label slug — the wobble is a
+// false removed+added, which the guard SURFACES; it never hides a real removal.
+function stableIdOf(c) {
+    if (c.testId && c.testId.trim())
+        return c.testId.trim();
+    if (isStableId(c.domId))
+        return c.domId.trim();
+    if (isStableId(c.controls))
+        return c.controls.trim();
+    return null;
+}
+// `<role>:#<stable-id>` when the affordance exposes a stable identity, else
+// `<role>:<slug(name)>`. The `#` marker keeps id-keys from colliding with slug-keys
+// (a slug never contains `#`).
+function affordanceKey(role, c) {
+    const id = stableIdOf(c);
+    return id ? `${role}:#${id}` : `${role}:${slug(c.name)}`;
+}
 /** Pure: turn raw affordances into keyed, deduped, sorted navigable items. */
 export function classifyInventory(raw) {
     const items = new Map();
@@ -75,13 +139,13 @@ export function classifyInventory(raw) {
             add(`route:${c.internalPath}`, 'link', c.name || c.internalPath, c.internalPath);
         }
         else if (c.name && c.role === 'tab') {
-            add(`tab:${slug(c.name)}`, 'tab', c.name);
+            add(affordanceKey('tab', c), 'tab', c.name);
         }
         else if (c.name && c.role.startsWith('menuitem')) {
-            add(`menuitem:${slug(c.name)}`, 'menuitem', c.name);
+            add(affordanceKey('menuitem', c), 'menuitem', c.name);
         }
         else if (c.name && c.tag === 'button') {
-            add(`nav-button:${slug(c.name)}`, 'nav-button', c.name);
+            add(affordanceKey('nav-button', c), 'nav-button', c.name);
         }
     }
     return Array.from(items.values()).sort((a, b) => a.key.localeCompare(b.key));

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "3.10.0",
+  "version": "3.12.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",