styleproof 1.4.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,72 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.6.0]
+
+The report tells you what to look for, in plain English, and stops being a
+spot-the-difference puzzle.
+
+### Added
+
+- **Plain-English change bullets.** Each crop now leads with a few bullets that
+  name the change the way a person would — `**columns: 2 → 3**`, `becomes a
+centered flex layout`, `corners squared off (50% → 8px)`, `recoloured light
+yellow → cyan` — instead of a raw list of computed-style deltas. A deterministic
+  rule set over the summarised properties (no LLM, no network); the exact
+  before→after tables still live in the fold for when you want them. New
+  `describeChange` / `colorName` helpers in `src/describe.ts`.
+
+### Changed
+
+- **Before/after crops line up exactly.** Both sides are now cropped from the
+  SAME page rectangle (the union of where the change sits on each side), so the
+  backgrounds align and the bullet tells you where to look — no more comparing
+  two differently-framed screenshots.
+- **Forced-state noise is gone.** The `:hover`/`:focus`/`:active` layer was
+  drowning real changes in echoes — on one PR, 3135 "state-delta differences"
+  across 8 elements. Now:
+  - a state delta the **base style already changed** is suppressed (a `:hover
+color` that just follows a recoloured base is an echo, not a dropped variant);
+  - layout/grid-track props are stripped from state deltas (a forced relayout
+    isn't interaction feedback);
+  - a change between two "no value" markers (`— → (gone)`) is dropped — it never
+    meant anything;
+  - the `outline` shorthand no longer renders `(state no longer changes it)`
+    three times in a row.
+- `summarizeProps` drops no-op and non-value↔non-value rows, so counts and tables
+  reflect only real, reviewable changes.
+
+## [1.5.0]
+
+Live regions are handled automatically, so a dashboard with streaming data,
+tickers, or late-loading content no longer produces a false "everything
+changed" report.
+
+### Added
+
+- **Auto-settle before capture (`stabilize`, default on).** The capture now
+  polls the (motion-frozen) page until its computed-style map has been unchanged
+  for a quiet window, so content that paints _after_ `go()` resolves — an async
+  fetch, an SSE/WebSocket stream backfilling a grid — is captured loaded, not
+  mid-load. This is what fixes the most common false positive: base and head
+  racing an async load and diffing empty-state-vs-populated. Requiring a
+  _sustained_ no-change window (not a single quiet sample) is what lets it wait
+  through the gap before late content appears.
+- **Automatic live-region detection.** Anything still changing on its own when
+  the settle budget runs out is, by definition, nondeterministic (it mutates
+  with no code change). Those element paths are recorded in `StyleMap.volatile`
+  and excluded from the diff — unioned across both sides — so a stream or ticker
+  never reads as a change, with no manual `ignore`. The report notes how many
+  live regions were auto-excluded. Tune or disable via
+  `captureStyleMap(page, { stabilize })` (`false`, or `{ interval, quietFor, timeout }`).
+
+### Changed
+
+- `diffStyleMapDirs` now returns a `volatile` count alongside `surfaces`/`counts`.
+- Text-only churn (a clock, "2m ago") still never matters — the diff has always
+  compared computed style, not text; this release adds the structural/layout
+  determinism to match.
+
 ## [1.4.0]
 
 New surfaces (present on only one side, no baseline to diff) are shown for

package/README.md

@@ -14,7 +14,7 @@ Pixel-snapshot tools miss most CSS regressions: they can't force `:hover` / `:fo
 
 On every PR, StyleProof captures a `StyleMap` from the HEAD and from the base branch, diffs them, and posts a Markdown comment:
 
-- A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot and the property changes folded under a toggle.
+- A summary line, then **one section per distinct change**, with a side-by-side before/after cropped screenshot (both sides cropped from the same rectangle, so they line up exactly) and **plain-English bullets that tell you what to look for** (`columns: 2 → 3`, `recoloured cyan → amber`) above the exact property changes, folded under a toggle.
 - An **approval checkbox per change**, driving a `StyleProof` commit status: red until every change is signed off, green when there are none.
 - **New surfaces don't block.** A surface that exists only on the PR head (no baseline to diff — e.g. the bootstrap PR that first adds the capture spec, or a brand-new page) is shown with its screenshot under a `🆕 new surface` heading and an _optional_ approval box, but it never holds the status red. It becomes part of the baseline once merged.
 - No committed baseline to maintain — the diff is HEAD-vs-base, so the report is _exactly what this PR changes_.
@@ -25,13 +25,13 @@ One change — the hero CTA recoloured cyan → amber — posts as a single sect
 
 ![A StyleProof report: the CTA button before (cyan) and after (amber), side by side](docs/demo-composite.png)
 
-As it renders in the PR comment (colours become live swatches; the full table sits inside the toggle):
+As it renders in the PR comment (a plain-English bullet first, then the exact table inside the toggle):
 
 ```text
 ### `a.btn-solid` · 1 element restyled
 _landing @ 1280_
 
-`background-color` `rgb(95, 202, 219)` → `rgb(245, 158, 11)`
+- **`a.btn-solid`** — background cyan → amber
 
 ▾ Show the property change
    | Property         | Before            | After             |
@@ -123,6 +123,8 @@ jobs:
 
 > Capture both sides in the **same environment** (same machine, same env vars): if env vars change _what renders_, base and head will diff on DOM no PR touched.
 
+**Live pages just work.** Before each capture, StyleProof settles the page — it waits until the computed-style map stops changing, so async content (a fetch, an SSE/WebSocket stream backfilling a grid) is captured loaded, not mid-load. Anything still moving on its own after that is detected as a live region and excluded from the diff, so a stream or ticker never reads as a change — no manual `ignore` needed. Disable or tune with `captureStyleMap(page, { stabilize: false })` / `{ stabilize: { quietFor, timeout } }`.
+
 ## Reference
 
 **Action `BenSheridanEdwards/styleproof@v1`** — key inputs:

package/dist/capture.d.ts

@@ -45,13 +45,45 @@ export type StyleMap = {
      * certified, instead of silently reading as "identical".
      */
     statesSkipped?: boolean;
+    /**
+     * Element paths detected as LIVE at capture time — they kept changing on
+     * their own (after motion was frozen) until the settle budget ran out, so
+     * they're nondeterministic. Excluded from `elements`/`states`/`defaults`
+     * here, and skipped by the diff (which unions both sides' volatile sets) so a
+     * stream/ticker never reads as a change. Empty/absent on a fully-settled page.
+     */
+    volatile?: string[];
 };
 export type CaptureOptions = {
     /**
      * Selectors for nondeterministic regions (live data, embeds, ads). The
-     * matching elements and their descendants are skipped entirely.
+     * matching elements and their descendants are skipped entirely. Usually
+     * unnecessary now that `stabilize` auto-detects live regions; use it to skip
+     * a region you know is volatile without paying the settle wait for it.
      */
     ignore?: string[];
+    /**
+     * Settle the page before capturing, and auto-exclude live regions (default
+     * on). StyleProof polls the (motion-frozen) page until its computed-style map
+     * stops changing — so async content that paints AFTER `go()` resolves (a
+     * fetch, an SSE/WebSocket stream) is captured in its loaded state, not
+     * mid-load. Any region still changing when the budget runs out is a live
+     * region by definition (it mutates with no code change); its paths are
+     * recorded in `StyleMap.volatile` and excluded from the diff, so a stream or
+     * ticker never reads as a change — no manual `ignore` needed. Text-only churn
+     * (a clock, "2m ago") never matters: the diff compares computed style, not
+     * text. Pass `false` to capture the exact frame `go()` left, or `{ interval,
+     * quietFor, timeout }` (ms) to tune the poll cadence, the no-change window
+     * that counts as settled, and the budget. Note: content that first paints
+     * after a quiet gap longer than `quietFor` can't be waited for without a
+     * signal — settle that in `go()`; anything still moving at `timeout` is
+     * treated as a live region.
+     */
+    stabilize?: boolean | {
+        interval?: number;
+        quietFor?: number;
+        timeout?: number;
+    };
     /**
      * Capture forced :hover/:focus/:active state deltas (default true). This is
      * the expensive layer — O(interactive elements × 3 states) with a subtree
@@ -66,10 +98,14 @@ export type CaptureOptions = {
      */
     maxInteractive?: number;
 };
+/** True if `path` is one of `roots` or a structural descendant of one. Shared by
+ *  the capture (excluding live regions) and the diff (skipping them). */
+export declare function isUnder(path: string, roots: string[]): boolean;
 /**
- * Capture the page's complete style map. Drive the page to the state you
- * want first (navigate, open menus, settle fonts/animations) — the capture
- * reads whatever is in front of it.
+ * Capture the page's complete style map. Drive the page to the state you want
+ * first (navigate, open menus); by default the capture then auto-settles the
+ * page and excludes live regions (see `stabilize`), so a fetch/stream that
+ * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export declare function captureStyleMap(page: Page, options?: CaptureOptions): Promise<StyleMap>;
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */

package/dist/capture.js

@@ -5,6 +5,11 @@ const INTERACTIVE = 'a, button, input, textarea, select, summary, [role="button"
 // 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.
 const FREEZE_CSS = '*,*::before,*::after{animation:none!important;transition:none!important}';
+/** True if `path` is one of `roots` or a structural descendant of one. Shared by
+ *  the capture (excluding live regions) and the diff (skipping them). */
+export function isUnder(path, roots) {
+    return roots.some((r) => path === r || path.startsWith(r + ' > '));
+}
 // Serialized into the browser by page.evaluate; cannot call module helpers.
 function capturePage({ ignore, motionOnly }) {
     const MOTION = /^(transition|animation)/;
@@ -206,14 +211,16 @@ function pathsForSelector({ selector, skipSel }) {
 }
 // Forced pseudo-class states on interactive elements, via CDP so no real
 // mouse or focus is involved and parent-state descendant rules still apply.
-async function captureForcedStates(page, ignore, maxInteractive) {
+async function captureForcedStates(page, ignore, maxInteractive, skipPaths = []) {
     const client = await page.context().newCDPSession(page);
     await client.send('DOM.enable');
     await client.send('CSS.enable');
     const { root } = await client.send('DOM.getDocument');
     const { nodeIds } = await client.send('DOM.querySelectorAll', { nodeId: root.nodeId, selector: INTERACTIVE });
     const skipSel = ignore.length ? ignore.map((s) => `${s}, ${s} *`).join(', ') : '';
-    const paths = await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel });
+    // Null out forced-state work for live (volatile) paths too, so they're not
+    // probed and can't reintroduce the churn the settle pass just excluded.
+    const paths = (await page.evaluate(pathsForSelector, { selector: INTERACTIVE, skipSel })).map((p) => p && skipPaths.length && isUnder(p, skipPaths) ? null : p);
     // The CDP DOM snapshot and the live querySelectorAll are two separate,
     // non-atomic reads. They can legitimately disagree — display:contents,
     // nodes detached or injected between the two calls (next-route-announcer,
@@ -254,19 +261,84 @@ async function captureForcedStates(page, ignore, maxInteractive) {
     await client.detach();
     return { states, skipped: false };
 }
+/** Element paths that differ between two captures (added, removed, or restyled). */
+function changedElementPaths(a, b) {
+    const out = [];
+    for (const p of new Set([...Object.keys(a), ...Object.keys(b)]))
+        if (JSON.stringify(a[p]) !== JSON.stringify(b[p]))
+            out.push(p);
+    return out;
+}
 /**
- * Capture the page's complete style map. Drive the page to the state you
- * want first (navigate, open menus, settle fonts/animations) — the capture
- * reads whatever is in front of it.
+ * Poll the page until its computed-style map has been UNCHANGED for `quietFor`
+ * ms (it settled — async content finished painting) or the budget runs out.
+ * Requiring a sustained quiet window, not a single quiet sample, is what lets it
+ * wait THROUGH the gap before late content paints and through a streaming
+ * backfill instead of settling on the first lull. Returns the paths still
+ * changing at timeout: genuine LIVE regions, to be excluded from the capture.
+ * Reuses `capturePage` (motion already frozen by the caller), so only
+ * content/layout churn — not an animation frame — keeps it from settling.
+ */
+async function stabilizePage(page, ignore, interval, quietFor, timeout) {
+    const snap = async () => (await page.evaluate(capturePage, { ignore, motionOnly: false })).elements;
+    const start = Date.now();
+    let prev = await snap();
+    let lastChangeAt = start;
+    let recent = [];
+    while (Date.now() - start < timeout) {
+        await page.waitForTimeout(interval);
+        const cur = await snap();
+        const changed = changedElementPaths(prev, cur);
+        prev = cur;
+        if (changed.length) {
+            lastChangeAt = Date.now();
+            recent = changed;
+        }
+        else if (Date.now() - lastChangeAt >= quietFor) {
+            return []; // unchanged for the full quiet window → settled
+        }
+    }
+    return recent; // never went quiet for quietFor within budget → still-moving paths are live
+}
+/**
+ * Capture the page's complete style map. Drive the page to the state you want
+ * first (navigate, open menus); by default the capture then auto-settles the
+ * page and excludes live regions (see `stabilize`), so a fetch/stream that
+ * paints after `go()` resolves is captured loaded, not mid-load.
  */
 export async function captureStyleMap(page, options = {}) {
     const ignore = options.ignore ?? [];
     const captureStates = options.captureStates ?? true;
     const maxInteractive = options.maxInteractive ?? 800;
+    const stabilize = options.stabilize ?? true;
     // Motion longhands first (FREEZE_CSS would null them), then everything else.
     const motion = await page.evaluate(capturePage, { ignore, motionOnly: true });
     await page.addStyleTag({ content: FREEZE_CSS });
+    // Settle: wait for async content to finish painting so base and head capture
+    // the same loaded state, and collect any region still changing on its own
+    // (a live stream/ticker) to exclude — animations are frozen above, so only
+    // real content/layout churn lands here.
+    let volatile = [];
+    if (stabilize !== false) {
+        const opt = typeof stabilize === 'object' ? stabilize : {};
+        const interval = opt.interval || 150;
+        const quietFor = opt.quietFor || 600;
+        const timeout = opt.timeout || 5000;
+        volatile = await stabilizePage(page, ignore, interval, quietFor, timeout);
+        if (volatile.length) {
+            // eslint-disable-next-line no-console
+            console.warn(`styleproof: ${volatile.length} live region(s) kept changing on their own and were excluded from ` +
+                'this capture (nondeterministic — a stream, ticker, or late-loading content). The diff skips them so ' +
+                'they never read as a change. If a real change is being hidden, settle the page in go() or raise stabilize.timeout.');
+        }
+    }
     const base = await page.evaluate(capturePage, { ignore, motionOnly: false });
+    // Drop live regions (and their subtrees) detected by the settle pass — done
+    // here, in Node, so the serialized capturePage stays a pure snapshot.
+    if (volatile.length)
+        for (const p of Object.keys(base.elements))
+            if (isUnder(p, volatile))
+                delete base.elements[p];
     if (base.shadowHosts || base.sameOriginFrames) {
         // eslint-disable-next-line no-console
         console.warn(`styleproof: ${base.shadowHosts} shadow host(s) and ${base.sameOriginFrames} same-origin iframe(s) were ` +
@@ -286,7 +358,7 @@ export async function captureStyleMap(page, options = {}) {
     let states = {};
     let statesSkipped = false;
     if (captureStates) {
-        const forced = await captureForcedStates(page, ignore, maxInteractive);
+        const forced = await captureForcedStates(page, ignore, maxInteractive, volatile);
         states = forced.states;
         statesSkipped = forced.skipped;
     }
@@ -295,6 +367,7 @@ export async function captureStyleMap(page, options = {}) {
         elements: base.elements,
         states,
         ...(statesSkipped ? { statesSkipped: true } : {}),
+        ...(volatile.length ? { volatile } : {}),
     };
 }
 /** Write a style map to disk; gzipped when the path ends in `.gz`. */

package/dist/describe.d.ts

@@ -0,0 +1,28 @@
+import type { PropChange } from './diff.js';
+/**
+ * Deterministic, offline plain-English summariser for a crop's changes. Turns a
+ * wall of computed-style deltas into a few bullets that tell a reviewer WHAT to
+ * look for ("Grid: 2 → 3 columns", "Accent recoloured cyan → red") instead of
+ * leaving them to spot the difference. No LLM — just curated rules over the
+ * already-summarised property changes, so the same input always yields the same
+ * words and it runs with no network.
+ */
+/** One changed element, with its property deltas already run through summarizeProps. */
+export type ElementChange = {
+    label: string;
+    added?: boolean;
+    removed?: boolean;
+    retagged?: boolean;
+    /** Base/computed-style deltas (not interactive-state ones). */
+    props: PropChange[];
+    /** Interactive states this element gained/changed/dropped, by name. */
+    states?: string[];
+};
+/** A short colour word for an rgb/rgba value: "cyan", "dark blue", "transparent". */
+export declare function colorName(v: string): string | null;
+/**
+ * Plain-English bullets for a crop's changes — DOM verbs, then labelled restyle
+ * phrases, then a flag for interaction-state changes a static screenshot can't
+ * show. Capped so the summary stays a glance (the exact tables live in the fold).
+ */
+export declare function describeChange(els: ElementChange[], maxBullets?: number): string[];

package/dist/describe.js

@@ -0,0 +1,258 @@
+// --- colour naming: nearest of a small, legible palette -----------------------
+const PALETTE = [
+    ['black', [0, 0, 0]],
+    ['white', [255, 255, 255]],
+    ['gray', [128, 128, 128]],
+    ['red', [229, 57, 53]],
+    ['orange', [245, 124, 0]],
+    ['amber', [255, 179, 0]],
+    ['yellow', [253, 216, 53]],
+    ['lime', [124, 179, 66]],
+    ['green', [56, 142, 60]],
+    ['teal', [0, 150, 136]],
+    ['cyan', [38, 198, 218]],
+    ['blue', [33, 110, 233]],
+    ['indigo', [57, 73, 171]],
+    ['purple', [142, 68, 173]],
+    ['magenta', [216, 27, 170]],
+    ['pink', [236, 64, 122]],
+];
+function parseColor(v) {
+    const m = v.match(/rgba?\(\s*(\d+)[,\s]+(\d+)[,\s]+(\d+)(?:[,/\s]+([\d.]+))?\s*\)/i);
+    if (!m)
+        return null;
+    return [Number(m[1]), Number(m[2]), Number(m[3]), m[4] === undefined ? 1 : Number(m[4])];
+}
+/** Nearest palette word to an rgb point, by squared distance. */
+function nearest(r, g, b) {
+    let best = PALETTE[0][0];
+    let bestD = Infinity;
+    for (const [name, [pr, pg, pb]] of PALETTE) {
+        const d = (r - pr) ** 2 + (g - pg) ** 2 + (b - pb) ** 2;
+        if (d < bestD)
+            [bestD, best] = [d, name];
+    }
+    return best;
+}
+/** A short colour word for an rgb/rgba value: "cyan", "dark blue", "transparent". */
+export function colorName(v) {
+    if (v === 'transparent')
+        return 'transparent';
+    const c = parseColor(v);
+    if (!c)
+        return null;
+    const [r, g, b, a] = c;
+    if (a === 0)
+        return 'transparent';
+    const best = nearest(r, g, b);
+    // Light/dark qualifier for the chromatic colours, where it reads naturally.
+    const lum = 0.299 * r + 0.587 * g + 0.114 * b;
+    const chromatic = best !== 'black' && best !== 'white' && best !== 'gray';
+    const qual = chromatic ? (lum > 200 ? 'light ' : lum < 70 ? 'dark ' : '') : '';
+    return `${qual}${best}`;
+}
+const shift = (before, after) => {
+    const cb = colorName(before);
+    const ca = colorName(after);
+    return cb && ca ? `${cb} → ${ca}` : `${before} → ${after}`;
+};
+// --- track counting for grid columns/rows ------------------------------------
+/** Count grid tracks in a `grid-template-*` value, honouring the `Npx ×K` form. */
+function trackCount(v) {
+    if (v === 'none' || !v)
+        return 0;
+    const rep = v.match(/×(\d+)/); // summarizeProps collapses "8px 8px 8px" → "8px ×3"
+    if (rep)
+        return Number(rep[1]);
+    return v.split(/\s+/).filter((t) => t && t !== '0px' && t !== '0').length;
+}
+const round = (v) => /50%|9999|999px/.test(v);
+const flexPhrase = (m, before) => {
+    const col = m.get('flex-direction')?.after?.startsWith('column') ? 'vertical ' : '';
+    const centered = m.get('justify-content')?.after === 'center' || m.get('align-items')?.after === 'center';
+    return `becomes a${centered ? ' centered' : ''} ${col}flex layout (was ${before})`;
+};
+const layoutRule = (m, mark) => {
+    const d = m.get('display');
+    if (!d)
+        return [];
+    mark('display', 'justify-content', 'align-items', 'flex-direction');
+    if (d.after === 'none')
+        return ['**hidden**'];
+    if (d.before === 'none')
+        return ['**shown**'];
+    if (/flex/.test(d.after))
+        return [flexPhrase(m, d.before)];
+    if (/grid/.test(d.after))
+        return [`becomes a grid (was ${d.before})`];
+    return [`display ${d.before} → ${d.after}`];
+};
+const gridRule = (m, mark) => {
+    const out = [];
+    for (const [prop, word] of [
+        ['grid-template-columns', 'columns'],
+        ['grid-template-rows', 'rows'],
+    ]) {
+        const g = m.get(prop);
+        if (!g)
+            continue;
+        mark(prop);
+        const [b, a] = [trackCount(g.before), trackCount(g.after)];
+        if (b !== a && (b > 0 || a > 0))
+            out.push(`**${word}: ${b} → ${a}**`);
+    }
+    return out;
+};
+const borderWidthRule = (m, mark) => {
+    const bw = m.get('border-width');
+    if (!bw)
+        return [];
+    mark('border-width', 'border-style', 'border-color');
+    const wasZero = /^0/.test(bw.before);
+    const isZero = /^0/.test(bw.after);
+    if (wasZero && !isZero)
+        return [`gains a ${bw.after} border`];
+    if (!wasZero && isZero)
+        return ['loses its border'];
+    return [`border ${bw.before} → ${bw.after}`];
+};
+const borderRadiusRule = (m, mark) => {
+    const r = m.get('border-radius');
+    if (!r)
+        return [];
+    mark('border-radius');
+    if (round(r.before) && !round(r.after))
+        return [`corners squared off (${r.before} → ${r.after})`];
+    if (!round(r.before) && round(r.after))
+        return ['corners fully rounded'];
+    return [`corner radius ${r.before} → ${r.after}`];
+};
+const colorRule = (m, mark) => {
+    const fields = [
+        ['color', 'text'],
+        ['background-color', 'background'],
+        ['border-color', 'border colour'],
+    ];
+    const present = fields.map(([p, w]) => [m.get(p), w]).filter(([c]) => c);
+    if (!present.length)
+        return [];
+    const [first] = present;
+    const same = present.length > 1 && present.every(([c]) => c.before === first[0].before && c.after === first[0].after);
+    fields.forEach(([p]) => m.has(p) && mark(p));
+    if (same)
+        return [`recoloured ${shift(first[0].before, first[0].after)}`];
+    return present.map(([c, w]) => `${w} ${shift(c.before, c.after)}`);
+};
+const fillRule = (m, mark) => {
+    const bgi = m.get('background-image');
+    if (!bgi)
+        return [];
+    mark('background-image');
+    const kind = (v) => /gradient/.test(v) ? 'a gradient' : /url\(/.test(v) ? 'an image' : v === 'none' ? 'no fill' : v;
+    return [`fill → ${kind(bgi.after)} (was ${kind(bgi.before)})`];
+};
+const effectsRule = (m, mark) => {
+    const out = [];
+    const sh = m.get('box-shadow');
+    if (sh) {
+        mark('box-shadow');
+        out.push(sh.before === 'none' ? 'gains a shadow' : sh.after === 'none' ? 'loses its shadow' : 'shadow changes');
+    }
+    const op = m.get('opacity');
+    if (op) {
+        mark('opacity');
+        out.push(`opacity ${op.before} → ${op.after}`);
+    }
+    return out;
+};
+const weight = (v) => Number(v) || (v === 'bold' ? 700 : v === 'normal' ? 400 : NaN);
+const typographyRule = (m, mark) => {
+    const out = [];
+    const fs = m.get('font-size');
+    if (fs) {
+        mark('font-size');
+        out.push(`text size ${fs.before} → ${fs.after}`);
+    }
+    const fw = m.get('font-weight');
+    if (fw) {
+        mark('font-weight');
+        const d = weight(fw.after) - weight(fw.before);
+        out.push(Number.isNaN(d) ? `weight ${fw.before} → ${fw.after}` : d > 0 ? 'bolder text' : 'lighter text');
+    }
+    return out;
+};
+const spacingRule = (m, mark) => {
+    const spacing = ['padding', 'margin', 'gap'].filter((p) => m.has(p));
+    spacing.forEach((p) => mark(p));
+    return spacing.length ? [`${spacing.join(' & ')} adjusted`] : [];
+};
+const RULES = [
+    layoutRule,
+    gridRule,
+    borderWidthRule,
+    borderRadiusRule,
+    colorRule,
+    fillRule,
+    effectsRule,
+    typographyRule,
+    spacingRule,
+];
+/** Build the English phrases for ONE element's property deltas. */
+function phrasesFor(props) {
+    const m = new Map(props.map((p) => [p.prop, p]));
+    const used = new Set();
+    const mark = (...ps) => ps.forEach((p) => used.add(p));
+    const out = RULES.flatMap((rule) => rule(m, mark));
+    // Anything no rule named: a quiet tail so nothing is silently lost.
+    const rest = [...m.keys()].filter((p) => !used.has(p));
+    if (rest.length)
+        out.push(`+${rest.length} more (${rest.slice(0, 3).join(', ')}${rest.length > 3 ? '…' : ''})`);
+    return out;
+}
+/** Tally added/removed/retagged elements into "3 added" style lines. */
+function domVerbLines(els) {
+    const verbs = {};
+    for (const el of els) {
+        const v = el.added ? 'added' : el.removed ? 'removed' : el.retagged ? 'retagged' : null;
+        if (v)
+            verbs[v] = (verbs[v] ?? 0) + 1;
+    }
+    return Object.entries(verbs).map(([verb, n]) => `**${n}** element${n === 1 ? '' : 's'} ${verb}`);
+}
+/** Restyle phrases per element, deduped: a phrase on ONE element is labelled with
+ *  it; the same phrase across many collapses to `×N` (naming one of fourteen would
+ *  mislead). */
+function restyleLines(els) {
+    const byLine = new Map();
+    const order = [];
+    for (const el of els) {
+        if (el.added || el.removed)
+            continue; // values, not deltas — heading covers them
+        const line = phrasesFor(el.props).join(', ');
+        if (!line)
+            continue;
+        if (!byLine.has(line)) {
+            byLine.set(line, { count: 0, label: el.label });
+            order.push(line);
+        }
+        byLine.get(line).count++;
+    }
+    return order.map((line) => {
+        const { count, label } = byLine.get(line);
+        return count > 1 ? `${line} _(×${count})_` : `**\`${label}\`** — ${line}`;
+    });
+}
+/**
+ * Plain-English bullets for a crop's changes — DOM verbs, then labelled restyle
+ * phrases, then a flag for interaction-state changes a static screenshot can't
+ * show. Capped so the summary stays a glance (the exact tables live in the fold).
+ */
+export function describeChange(els, maxBullets = 6) {
+    const lines = [...domVerbLines(els), ...restyleLines(els)];
+    const states = [...new Set(els.flatMap((e) => e.states ?? []))];
+    if (states.length)
+        lines.push(`interaction states changed: ${states.map((s) => `\`:${s}\``).join(', ')}`);
+    if (lines.length <= maxBullets)
+        return lines;
+    return [...lines.slice(0, maxBullets - 1), `…and ${lines.length - (maxBullets - 1)} more change(s)`];
+}

package/dist/diff.d.ts

@@ -42,10 +42,12 @@ export type DiffCounts = {
 };
 /** Diff two style maps of the same surface. */
 export declare function diffStyleMaps(a: StyleMap, b: StyleMap): Finding[];
-/** Diff every same-named capture between two directories. */
+/** Diff every same-named capture between two directories. `volatile` is the
+ *  count of live regions auto-excluded across all surfaces (union per surface). */
 export declare function diffStyleMapDirs(dirA: string, dirB: string): {
     surfaces: SurfaceDiff[];
     counts: DiffCounts;
+    volatile: number;
 };
 /** Human label: structural path plus a truncated class hint. */
 export declare function findingLabel(path: string, cls: string): string;

package/dist/diff.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { loadStyleMap } from './capture.js';
+import { loadStyleMap, isUnder } from './capture.js';
 function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
     const changed = [];
     for (const prop of new Set([...Object.keys(propsA), ...Object.keys(propsB)])) {
@@ -16,7 +16,14 @@ function diffProps(propsA, propsB, fallbackA, fallbackB, unsetA, unsetB) {
 /** Diff two style maps of the same surface. */
 export function diffStyleMaps(a, b) {
     const findings = [];
+    // Live regions either capture flagged as nondeterministic (a stream, ticker,
+    // late-loading content): never diff them — their values move with no code
+    // change. Union both sides so a region volatile on only one capture is still
+    // skipped, in every layer (element, pseudo, forced-state).
+    const volatile = [...new Set([...(a.volatile ?? []), ...(b.volatile ?? [])])];
     for (const p of [...new Set([...Object.keys(a.elements), ...Object.keys(b.elements)])].sort()) {
+        if (volatile.length && isUnder(p, volatile))
+            continue;
         const ea = a.elements[p];
         const eb = b.elements[p];
         if (!ea || !eb) {
@@ -62,6 +69,8 @@ export function diffStyleMaps(a, b) {
         });
     }
     for (const p of new Set([...Object.keys(a.states ?? {}), ...Object.keys(b.states ?? {})])) {
+        if (volatile.length && isUnder(p, volatile))
+            continue;
         const sa = a.states?.[p] ?? {};
         const sb = b.states?.[p] ?? {};
         const cls = (a.elements[p] ?? b.elements[p])?.cls ?? '';
@@ -77,13 +86,25 @@ export function diffStyleMaps(a, b) {
     }
     return findings;
 }
+/** Add a surface's findings to the running totals (one DOM/style/state tally). */
+function tallyCounts(findings, counts) {
+    for (const f of findings) {
+        if (f.kind === 'dom')
+            counts.dom++;
+        else if (f.kind === 'style')
+            counts.style += f.props.length;
+        else
+            counts.state += f.props.length;
+    }
+}
 function indexDir(dir) {
     return Object.fromEntries(fs
         .readdirSync(dir)
         .filter((f) => /\.json(\.gz)?$/.test(f))
         .map((f) => [f.replace(/\.json(\.gz)?$/, ''), path.join(dir, f)]));
 }
-/** Diff every same-named capture between two directories. */
+/** Diff every same-named capture between two directories. `volatile` is the
+ *  count of live regions auto-excluded across all surfaces (union per surface). */
 export function diffStyleMapDirs(dirA, dirB) {
     const indexA = indexDir(dirA);
     const indexB = indexDir(dirB);
@@ -92,6 +113,7 @@ export function diffStyleMapDirs(dirA, dirB) {
         throw new Error(`no .json(.gz) captures found in ${dirA} or ${dirB}`);
     const surfaces = [];
     const counts = { dom: 0, style: 0, state: 0 };
+    let volatile = 0;
     for (const surface of names) {
         if (!indexA[surface] || !indexB[surface]) {
             // A surface present on only one side has no baseline to diff against — it's
@@ -101,19 +123,15 @@ export function diffStyleMapDirs(dirA, dirB) {
             surfaces.push({ surface, missing: indexA[surface] ? 'after' : 'before', findings: [] });
             continue;
         }
-        const findings = diffStyleMaps(loadStyleMap(indexA[surface]), loadStyleMap(indexB[surface]));
-        for (const f of findings) {
-            if (f.kind === 'dom')
-                counts.dom++;
-            else if (f.kind === 'style')
-                counts.style += f.props.length;
-            else
-                counts.state += f.props.length;
-        }
+        const mapA = loadStyleMap(indexA[surface]);
+        const mapB = loadStyleMap(indexB[surface]);
+        volatile += new Set([...(mapA.volatile ?? []), ...(mapB.volatile ?? [])]).size;
+        const findings = diffStyleMaps(mapA, mapB);
+        tallyCounts(findings, counts);
         if (findings.length)
             surfaces.push({ surface, findings });
     }
-    return { surfaces, counts };
+    return { surfaces, counts, volatile };
 }
 /** Human label: structural path plus a truncated class hint. */
 export function findingLabel(path, cls) {

package/dist/report.d.ts

@@ -1,4 +1,5 @@
 import { type PropChange } from './diff.js';
+export { describeChange, colorName } from './describe.js';
 /**
  * Visual diff report: for every surface with findings, crop the before/after
  * full-page screenshots around the changed elements and write a markdown
@@ -6,9 +7,9 @@ import { type PropChange } from './diff.js';
  *
  * Cropping zooms out to the OUTERMOST changed element: changed paths that are
  * descendants of other changed paths are folded into their ancestor, nearby
- * regions are merged, and both sides are cropped at identical dimensions
- * (centered on each side's own coordinates) so the pair stays comparable
- * even when the change moved things around.
+ * regions are merged, and both sides are cropped at the SAME page rectangle (the
+ * union of where the change sits on each side) so the pair lines up exactly —
+ * the reviewer compares like-for-like instead of playing spot-the-difference.
  */
 export type ReportOptions = {
     beforeDir: string;
@@ -27,9 +28,9 @@ export type ReportOptions = {
     maxCrops?: number;
     /**
      * Row count at which a crop's property tables fold under a `<details>` toggle
-     * (default 0 = always fold; the essence line and screenshot stay visible). Set
-     * to e.g. 5 to keep small changes inline and fold only verbose ones, or
-     * `Infinity` to never fold.
+     * (default 0 = always fold; the plain-English bullets and screenshot stay
+     * visible). Set to e.g. 5 to keep small changes inline and fold only verbose
+     * ones, or `Infinity` to never fold.
      */
     foldDetailsAt?: number;
     /**

package/dist/report.js

@@ -3,6 +3,10 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
+import { describeChange } from './describe.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 } from './describe.js';
 // Hidden marker appended to a new-surface heading. Invisible in rendered
 // markdown; lets the PR-comment layer attach an OPTIONAL "approve" box to a new
 // surface (vs the required box on a real change), so new surfaces never gate.
@@ -20,6 +24,16 @@ const visible = (b) => !!b && b.w > 0 && b.h > 0;
 function outermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && p.startsWith(q + ' > ')));
 }
+/** Group findings by their element path (one group per changed element). */
+function groupByPath(findings) {
+    const byPath = new Map();
+    for (const f of findings) {
+        const arr = byPath.get(f.path) ?? [];
+        arr.push(f);
+        byPath.set(f.path, arr);
+    }
+    return [...byPath.values()];
+}
 function groupRegions(paths, a, b, padBy) {
     const groups = paths.map((p) => {
         const ra = a.elements[p]?.rect;
@@ -218,6 +232,13 @@ const CURRENTCOLOR_FOLLOWERS = [
     '-webkit-text-fill-color',
     '-webkit-text-stroke-color',
 ];
+// "No value here" markers: a forced-state delta that doesn't apply, an unset
+// longhand, or a capture artifact where a path didn't line up. A change BETWEEN
+// two of these (e.g. `— → (gone)`) is meaningless and must never read as a diff.
+const NON_VALUE = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)', '(gone)']);
+const isNonValue = (v) => NON_VALUE.has(v);
+/** Combine longhands into a shorthand value; all-non-value sides collapse to one. */
+const combineValues = (vals) => (vals.every(isNonValue) ? '(unset)' : vals.join(' '));
 export function summarizeProps(props) {
     const map = new Map(props.map((p) => [p.prop, { ...p }]));
     for (const [logical, physical] of Object.entries(LOGICAL_TO_PHYSICAL)) {
@@ -273,13 +294,16 @@ export function summarizeProps(props) {
         map.delete('outline-color');
         map.set('outline', {
             prop: 'outline',
-            before: `${ow.before} ${os.before} ${oc.before}`,
-            after: `${ow.after} ${os.after} ${oc.after}`,
+            before: combineValues([ow.before, os.before, oc.before]),
+            after: combineValues([ow.after, os.after, oc.after]),
         });
     }
-    return [...map.values()]
+    return ([...map.values()]
         .map((p) => ({ prop: p.prop, before: cleanVal(p.before), after: cleanVal(p.after) }))
-        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop));
+        // Drop no-ops: a value that didn't actually change, or a change between two
+        // "no value here" markers (`— → (gone)`), which carries no information.
+        .filter((p) => p.before !== p.after && !(isNonValue(p.before) && isNonValue(p.after)))
+        .sort((a, b) => orderIdx(a.prop) - orderIdx(b.prop) || a.prop.localeCompare(b.prop)));
 }
 /** `div.who-grid`, `a.nav-cta`, `h3` — the semantic marker class, else the tag. */
 export function prettyLabel(p, cls) {
@@ -351,10 +375,8 @@ function regionHeading(regionPaths, findings) {
     const label = anchors.length > 1 ? `\`${head}\` + ${anchors.length - 1} more` : `\`${head}\``;
     return `${label} · ${groupTitle(findings)}`;
 }
-// A diff state row whose value is one of these placeholders means "this state
-// has no effect here" — meaningless to show, so render it as an em dash.
-const STATE_PLACEHOLDER = new Set(['(state does not change it)', '(state no longer changes it)', '(unset)']);
-const cell = (v) => (STATE_PLACEHOLDER.has(v) ? '—' : `\`${v}\``);
+// A "no value here" marker renders as an em dash rather than its literal text.
+const cell = (v) => (isNonValue(v) ? '—' : `\`${v}\``);
 function beforeAfterTable(rows) {
     return [
         '| Property | Before | After |',
@@ -406,15 +428,9 @@ function renderOneElement(group) {
  * "before"); an existing element shows before → after.
  */
 function renderElements(findings, maxElements = 40) {
-    const byPath = new Map();
-    for (const f of findings) {
-        const arr = byPath.get(f.path) ?? [];
-        arr.push(f);
-        byPath.set(f.path, arr);
-    }
     const blocks = [];
     const bySig = new Map();
-    for (const group of byPath.values()) {
+    for (const group of groupByPath(findings)) {
         const el = renderOneElement(group);
         if (!el)
             continue;
@@ -439,25 +455,6 @@ function renderElements(findings, maxElements = 40) {
     }
     return out;
 }
-/**
- * A scannable one-liner of what a crop changed, shown ABOVE the folded tables so a
- * reviewer can judge without expanding: its top property deltas with values, the
- * rest as a count, and a flag when the change reaches into hover/focus/active — the
- * one kind of change a static before|after screenshot can't show.
- */
-function changeEssence(findings) {
-    const verbs = [];
-    for (const c of ['added', 'removed', 'retagged']) {
-        const k = findings.filter((f) => f.kind === 'dom' && f.change === c).length;
-        if (k)
-            verbs.push(`${k} ${c}`);
-    }
-    const rows = findings.flatMap((f) => (f.kind === 'dom' ? [] : summarizeProps(f.props)));
-    const top = rows.slice(0, 3).map((r) => `\`${r.prop}\` ${cell(r.before)} → ${cell(r.after)}`);
-    const more = rows.length > top.length ? `+${rows.length - top.length} more` : '';
-    const line = [...verbs, ...top, more].filter(Boolean).join(' · ') || '_see changes_';
-    return findings.some((f) => f.kind === 'state') ? `${line} _· incl. hover/focus/active_` : line;
-}
 /** Plain-text `<summary>` affordance — GitHub renders markdown inside `<summary>`
  *  literally, so no backticks or bold here. */
 function foldSummary(findings) {
@@ -466,31 +463,24 @@ function foldSummary(findings) {
         return 'Show details';
     return n === 1 ? 'Show the property change' : `Show all ${n} property changes`;
 }
-/** Render a crop's changes: the essence line, then the property tables — folded
- *  under a toggle once they would be a wall (the screenshot and approval checkbox
- *  above always stay visible). Blank lines around the table block are mandatory or
- *  GitHub prints the tables as literal text. `foldAt` is the row count at which the
- *  tables collapse; ≤ 0 folds always, Infinity never. */
+/** Render a crop's changes: plain-English bullets that tell the reviewer what to
+ *  look for, then the exact property tables — folded under a toggle once they would
+ *  be a wall (the screenshot and approval checkbox above always stay visible).
+ *  Blank lines around the table block are mandatory or GitHub prints the tables as
+ *  literal text. `foldAt` is the row count at which the tables collapse; ≤ 0 folds
+ *  always, Infinity never. */
 function renderCropChanges(findings, foldAt) {
     const tables = renderElements(findings);
     if (!tables.length)
         return [];
     const rows = findings.flatMap((f) => (f.kind === 'dom' ? [] : summarizeProps(f.props))).length;
-    // Small enough to read at a glance: the tables speak for themselves, no essence
-    // line (it would just echo a one- or two-row table).
+    // Small enough to read at a glance: the tables speak for themselves.
     if (rows < foldAt)
         return tables;
-    // Folded: the essence line is the visible stand-in for what the toggle hides.
-    return [
-        '',
-        changeEssence(findings),
-        '',
-        '<details>',
-        `<summary>${foldSummary(findings)}</summary>`,
-        ...tables,
-        '',
-        '</details>',
-    ];
+    // Folded: plain-English bullets are the visible stand-in for what the toggle hides.
+    const bullets = describeChange(buildElementChanges(findings));
+    const summary = bullets.length ? bullets.map((b) => `- ${b}`) : ['_see changes_'];
+    return ['', ...summary, '', '<details>', `<summary>${foldSummary(findings)}</summary>`, ...tables, '', '</details>'];
 }
 // Computed values that follow from an element's box size or position rather than
 // its styling. On any reflow they change all the way up the ancestor chain
@@ -519,20 +509,82 @@ const DERIVED_PROPS = new Set([
     'inset-inline-start',
     'inset-inline-end',
 ]);
-const hasRealChange = (f) => f.kind === 'dom' || f.props.some((p) => !DERIVED_PROPS.has(p.prop));
-const stripDerived = (f) => f.kind === 'dom' ? f : { ...f, props: f.props.filter((p) => !DERIVED_PROPS.has(p.prop)) };
+// Props stripped from forced :hover/:focus/:active deltas specifically. Layout
+// and grid-track values that shift when a state forces a relayout are capture
+// noise, not interaction feedback — a state finding is meant to catch a changed
+// hover/focus/active *style* (colour, outline, shadow), not a reflow.
+const STATE_STRIP = new Set([
+    ...DERIVED_PROPS,
+    'grid-template-columns',
+    'grid-template-rows',
+    'grid-template-areas',
+    'grid-auto-columns',
+    'grid-auto-rows',
+    'grid-auto-flow',
+]);
+/**
+ * Strip the noise the visual report shouldn't carry, cross-referencing each
+ * element's layers so the forced-state layer stops echoing the base:
+ *   - base/pseudo styles: drop size/position-derived longhands (reflow casualties);
+ *   - forced states: drop derived + grid-track props, drop a delta the BASE
+ *     already changed (a `:hover color` that just follows a recoloured base is an
+ *     echo, not a dropped variant), and drop non-value↔non-value rows;
+ *   - any finding left with no props is removed entirely.
+ */
+function cleanFindings(findings) {
+    const out = [];
+    for (const group of groupByPath(findings)) {
+        const base = group.find((f) => f.kind === 'style' && f.pseudo === null);
+        const baseChanged = new Set(base?.props.map((p) => p.prop) ?? []);
+        for (const f of group) {
+            if (f.kind === 'dom') {
+                out.push(f);
+                continue;
+            }
+            const props = f.kind === 'style'
+                ? f.props.filter((p) => !DERIVED_PROPS.has(p.prop))
+                : f.props.filter((p) => !STATE_STRIP.has(p.prop) && !baseChanged.has(p.prop) && !(isNonValue(p.before) && isNonValue(p.after)));
+            if (props.length)
+                out.push({ ...f, props });
+        }
+    }
+    return out;
+}
+/** Per-element view for the plain-English summariser: the base deltas (summarised)
+ *  plus which interactive states genuinely changed. */
+function buildElementChanges(findings) {
+    const els = [];
+    for (const group of groupByPath(findings)) {
+        const dom = group.find((f) => f.kind === 'dom');
+        const styleProps = group
+            .filter((f) => f.kind === 'style')
+            .flatMap((f) => f.props);
+        els.push({
+            label: prettyLabel(group[0].path, group[0].cls),
+            added: dom?.change === 'added',
+            removed: dom?.change === 'removed',
+            retagged: dom?.change === 'retagged',
+            props: summarizeProps(styleProps),
+            states: [
+                ...new Set(group.filter((f) => f.kind === 'state').map((f) => f.state)),
+            ],
+        });
+    }
+    return els;
+}
 export function generateStyleMapReport(opts) {
     const { beforeDir, afterDir, outDir, imageBaseUrl = '', pad: padBy = 24, minWidth = 320, minHeight = 180, maxHeight = 1600, maxCrops = 6, foldDetailsAt = 0, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
-    const { surfaces } = diffStyleMapDirs(beforeDir, afterDir);
+    const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
-    // Focus each surface on styling intent: drop reflow-casualty elements (only
-    // size/position-derived changes) and strip those props from the rest, unless
-    // includeLayoutNoise is set. Surfaces left with no real change are dropped.
+    // 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 : sd.findings.filter(hasRealChange).map(stripDerived),
+        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
@@ -590,6 +642,9 @@ export function generateStyleMapReport(opts) {
                 `New surfaces don't block the check.`);
         }
     }
+    if (volatileCount > 0) {
+        md.push('', `_${volatileCount} live region(s) auto-excluded as nondeterministic (a stream, ticker, or late-loading content) — they don't affect the check._`);
+    }
     let totalFindings = 0;
     let cropSeq = 0;
     for (const cg of changeGroups) {
@@ -631,14 +686,18 @@ export function generateStyleMapReport(opts) {
             const region = visible(g.after) ? g.after : g.before;
             let images = {};
             if (region && pngA && pngB) {
-                // Same crop dimensions on both sides so the pair reads as a pair.
-                const w = Math.max(minWidth, visible(g.before) ? g.before.w : 0, visible(g.after) ? g.after.w : 0);
-                const h = Math.min(maxHeight, Math.max(minHeight, visible(g.before) ? g.before.h : 0, visible(g.after) ? g.after.h : 0));
+                // 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, visible(g.before) ? g.before : region, w, h);
-                const after = cropPng(pngB, visible(g.after) ? g.after : region, w, h);
+                const before = cropPng(pngA, cropBox, w, h);
+                const after = cropPng(pngB, cropBox, w, h);
                 const composite = compositePair(before, after);
                 writePng(path.join(outDir, `${stem}-before.png`), before);
                 writePng(path.join(outDir, `${stem}-after.png`), after);
@@ -653,8 +712,8 @@ export function generateStyleMapReport(opts) {
             else {
                 md.push('', '_No screenshots in these capture sets (run captures with `screenshots: true` for side-by-side crops)._');
             }
-            // What this crop changed: a scannable essence line, then the property
-            // tables — folded under a toggle once they'd be a wall (foldDetailsAt).
+            // 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));
             surfaceJson.regions.push({ paths: g.paths, before: g.before, after: g.after, images });
         }

package/package.json

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