styleproof 1.5.0 → 1.6.0

package/CHANGELOG.md

@@ -7,6 +7,41 @@ 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,

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             |

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/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, 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
@@ -634,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);
@@ -656,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.5.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",