styleproof 1.0.0 → 1.2.0

package/CHANGELOG.md

@@ -7,6 +7,64 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.2.0]
+
+Visual-review approval gate. StyleProof can now act as a per-PR review gate
+("here is what changed visually — sign off if it's intentional") rather than only
+a zero-diff refactor certifier.
+
+### Added
+
+- **`require-approval` Action input.** Instead of failing the job on any diff, the
+  Action sets a `StyleProof` commit status: green when there are no visual changes,
+  red ("needs sign-off") until the changes are approved. The report comment gains
+  **one approval checkbox per change** — each distinct visual change is signed off
+  on its own, and the gate goes green only when **every** box is ticked.
+- **`example/styleproof-approve.yml`** — a template `issue_comment` workflow (copy
+  to your default branch). As a write-access reviewer ticks the per-change boxes,
+  it updates the `StyleProof` status ("2 of 3 approved") and flips it green only at
+  full approval. Its trust model:
+  - acts only on a **human edit** of the **bot's own** report comment
+    (`comment.user.type == 'Bot'` and `sender.type == 'User'`), which excludes both
+    the Action's own comment upserts and any attacker-authored comment;
+  - **binds approval to the exact commit** the report was generated for (a
+    `<!-- styleproof-sha -->` marker), so a push after the report can never inherit
+    a green status — a new render re-opens the gate;
+  - **verifies write access** (`getCollaboratorPermissionLevel`, fails closed)
+    before moving the status. The marker is not the trust boundary — write access is.
+- **`status-context` input** to rename the commit status (must match the approve
+  workflow + branch protection).
+
+### Changed
+
+- The report no longer appends its own "regenerate the baseline" footer — the
+  consumer (the Action, or your own wrapper) owns the call to action. This also
+  removes the duplicate footer the Action used to add. `fail-on-diff` (legacy
+  refactor mode) is unchanged and still the default.
+
+## [1.1.0]
+
+Report readability overhaul. No change to the capture format, the diff, or the
+public API — `styleproof-diff` certification is byte-for-byte identical; only the
+human-facing `styleproof-report` / `generateStyleMapReport` output changed.
+
+### Changed
+
+- **Group an identical change across surfaces into one section + one image.** A
+  change that appears on every breakpoint of a responsive page (e.g. a new footer
+  link across 7 landing widths) was repeated once per surface with a near-duplicate
+  crop each time. Surfaces whose findings are identical now collapse into a single
+  section that lists the affected surfaces (`landing @ 1280, 1080, 390 …`) and shows
+  one representative crop (the widest). The summary counts distinct changes, not
+  per-surface repetitions.
+- **One heading per element.** An element's base, pseudo, and forced-state findings
+  render under a single heading instead of a separate `DOM added` / `:hover` /
+  `:focus` block each.
+- **Newly-added elements read naturally.** A brand-new element has no meaningful
+  "before", so its forced states render as a `State · Property · Value` table of the
+  values it takes, instead of a `Before` column full of `(state does not change it)`.
+- `outline-width`/`-style`/`-color` collapse into one `outline` row.
+
 ## [1.0.0]
 
 First stable release and first publish to npm. The capture format, the public API
@@ -192,7 +250,9 @@ number)`), so each viewport band can capture at its own height. Default remains
 - `styleproof-diff` CLI: certifies a refactor (exit 0) or names the exact element,
   property, and state that drifted (exit 1).
 
-[Unreleased]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.0.0...HEAD
+[Unreleased]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.2.0...HEAD
+[1.2.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.1.0...v1.2.0
+[1.1.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v1.0.0...v1.1.0
 [1.0.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.7.0...v1.0.0
 [0.7.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.6.0...v0.7.0
 [0.6.0]: https://github.com/BenSheridanEdwards/styleproof/compare/v0.5.0...v0.6.0

package/README.md

@@ -394,11 +394,11 @@ Numeric flags also accept the `--flag=value` form. The remaining `maxHeight` kno
 
 ## GitHub Action
 
-The repo ships a composite action that diffs against your committed baseline and, on
-changes, commits a compact report to an orphan branch and posts it to the PR. It
-fails the job while changes are unapproved; **approving = regenerating the committed
-baseline** and pushing it with the PR. The comment updates in place on every push and
-flips to ✓ when clean.
+The repo ships a composite action that diffs two capture dirs and, on changes, commits a
+compact report to an orphan branch and posts it to the PR. The comment updates in place on
+every push and flips to ✓ when clean. It runs in one of two modes — **certify a refactor**
+(default) or **review visual changes** with per-change sign-off (`require-approval`); see
+[Two modes](#two-modes-certify-a-refactor-or-review-visual-changes) below.
 
 ```yaml
 - name: Capture style maps
@@ -416,14 +416,16 @@ flips to ✓ when clean.
 
 ### Inputs
 
-| Input           | Required | Default               | Description                                                                                                                     |
-| --------------- | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
-| `baseline-dir`  | yes      | —                     | Directory with the committed baseline captures (`.json.gz` + `.png`).                                                           |
-| `fresh-dir`     | yes      | —                     | Directory with the freshly captured maps to compare.                                                                            |
-| `report-branch` | no       | `styleproof-reports`  | Orphan branch that stores reports (created on first run). One `pr-<n>/` folder per PR; never pruned.                            |
-| `inline-images` | no       | `auto`                | `auto` \| `always` \| `never`. `auto` embeds composites in the comment for public repos and links the report for private repos. |
-| `github-token`  | no       | `${{ github.token }}` | Token used to push the report branch and post the comment.                                                                      |
-| `fail-on-diff`  | no       | `'true'`              | Fail the job when differences are found.                                                                                        |
+| Input              | Required | Default               | Description                                                                                                                     |
+| ------------------ | -------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
+| `baseline-dir`     | yes      | —                     | Directory with the committed baseline captures (`.json.gz` + `.png`).                                                           |
+| `fresh-dir`        | yes      | —                     | Directory with the freshly captured maps to compare.                                                                            |
+| `report-branch`    | no       | `styleproof-reports`  | Orphan branch that stores reports (created on first run). One `pr-<n>/` folder per PR; never pruned.                            |
+| `inline-images`    | no       | `auto`                | `auto` \| `always` \| `never`. `auto` embeds composites in the comment for public repos and links the report for private repos. |
+| `github-token`     | no       | `${{ github.token }}` | Token used to push the report branch and post the comment.                                                                      |
+| `fail-on-diff`     | no       | `'true'`              | Legacy refactor mode: fail the job on any diff. Ignored when `require-approval` is `'true'`.                                    |
+| `require-approval` | no       | `'false'`             | Review-gate mode: set a `StyleProof` commit status (red until each change is approved) instead of failing the job. See below.   |
+| `status-context`   | no       | `StyleProof`          | Name of the commit status set in review-gate mode (must match the approve workflow + branch protection).                        |
 
 ### Outputs
 
@@ -432,6 +434,46 @@ flips to ✓ when clean.
 | `changed`    | `"true"` when any computed style, pseudo-element, or state changed. |
 | `report-url` | Blob URL of the committed report (when changed).                    |
 
+### Two modes: certify a refactor, or review visual changes
+
+- **Certify (default, `fail-on-diff: true`).** Any computed-style change fails the job.
+  Right for a refactor you expect to be a no-op (a CSS-to-Tailwind migration); "approving"
+  a change means regenerating the committed baseline and pushing it.
+- **Review gate (`require-approval: true`).** The report is the product: every PR shows
+  _what changed visually_, and a reviewer signs each change off against the PR's stated
+  intent. Instead of failing the job, the Action sets a **`StyleProof` commit status** —
+  green when nothing changed, red until approved — and posts **one approval checkbox per
+  change**. The gate goes green only when **every** box is ticked.
+
+To enable the review gate:
+
+1. Set `require-approval: 'true'` on the Action, and grant the job `statuses: write`
+   (plus the existing `contents: write` / `pull-requests: write`).
+2. Copy [`example/styleproof-approve.yml`](example/styleproof-approve.yml) to
+   `.github/workflows/` **on your default branch** (`issue_comment` workflows only run
+   from the default branch).
+3. Add a branch-protection rule that **requires the `StyleProof` status** to pass.
+
+A reviewer with write access walks the report change-by-change and ticks each box; the
+status updates ("2 of 3 approved") and flips green at full approval. A new push that
+changes styles re-opens the gate. The approval is bound to the exact reviewed commit and
+acts only on a human edit of the bot's own comment, so it can't be flipped green by a
+later push, by the bot's own comment updates, or by anyone without write access. Pair it
+naturally with a head-vs-**base-branch** diff (capture the base branch into `baseline-dir`)
+so each PR's report is exactly _what this PR changes_.
+
+Two things to know about the trust model:
+
+- **Single-reviewer by design.** Any write-access user can tick the boxes, **including the
+  PR author on their own PR** — the sign-off is "I confirm this is intentional," not
+  multi-party review. If you need a different person to approve, add a branch-protection
+  rule requiring a review from someone other than the author (CODEOWNERS); this gate
+  doesn't enforce that itself.
+- **Use the default `GITHUB_TOKEN`.** The approve workflow only acts on a comment authored
+  by a bot (so an attacker-authored comment can never trigger it). If you post the report
+  with a personal access token (a `User`), the workflow won't fire and the gate can never
+  go green. A GitHub App token works; a PAT does not.
+
 ### Why two image modes (and why it's automatic)
 
 The two ways an image can appear on a PR have **opposite** privacy behaviour, so

package/dist/report.js

@@ -261,6 +261,20 @@ export function summarizeProps(props) {
             map.set(fam.short, { prop: fam.short, before: members[0].before, after: members[0].after });
         }
     }
+    // outline-width/-style/-color → one `outline` row (offset stays separate).
+    const ow = map.get('outline-width');
+    const os = map.get('outline-style');
+    const oc = map.get('outline-color');
+    if (ow && os && oc) {
+        map.delete('outline-width');
+        map.delete('outline-style');
+        map.delete('outline-color');
+        map.set('outline', {
+            prop: 'outline',
+            before: `${ow.before} ${os.before} ${oc.before}`,
+            after: `${ow.after} ${os.after} ${oc.after}`,
+        });
+    }
     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));
@@ -271,44 +285,143 @@ export function prettyLabel(p, cls) {
     const first = cls.split(/\s+/)[0] ?? '';
     return /^[a-z][a-z0-9-]*$/.test(first) ? `${tag}.${first}` : tag;
 }
-// Group findings (identical siblings collapse to one ×N block) and render each
-// as a 3-column table; colours land in their own cell so GitHub adds swatches.
-function renderFindings(findings, maxRows = 60) {
-    const groups = [];
-    const byKey = new Map();
+const surfaceBase = (s) => s.replace(/@\d+$/, '');
+const surfaceWidth = (s) => Number(s.match(/@(\d+)$/)?.[1] ?? 0);
+/** "landing @ 1280, 1080, 390 · landing-nav-open @ 1080" from the surface keys. */
+function formatSurfaceList(surfaces) {
+    const byBase = new Map();
+    for (const s of surfaces) {
+        const arr = byBase.get(surfaceBase(s)) ?? [];
+        arr.push(surfaceWidth(s));
+        byBase.set(surfaceBase(s), arr);
+    }
+    return [...byBase]
+        .map(([base, ws]) => {
+        const widths = ws.filter((w) => w > 0).sort((a, b) => b - a);
+        return widths.length ? `${base} @ ${widths.join(', ')}` : base;
+    })
+        .join(' · ');
+}
+/** Canonical signature of a surface's findings: surfaces that changed in the
+ *  same way collapse into one section + one image (the rects differ per width;
+ *  the change itself does not). */
+function signatureOf(findings) {
+    return JSON.stringify(findings
+        .map((f) => ({
+        p: f.path,
+        k: f.kind,
+        t: f.kind === 'dom' ? f.change : f.kind === 'state' ? f.state : (f.pseudo ?? ''),
+        v: f.kind === 'dom'
+            ? ''
+            : summarizeProps(f.props)
+                .map((c) => `${c.prop}=${c.before}>${c.after}`)
+                .join('|'),
+    }))
+        .sort((a, b) => `${a.p}|${a.k}|${a.t}`.localeCompare(`${b.p}|${b.k}|${b.t}`)));
+}
+/** A one-line heading for a change group: "1 element added", "2 elements restyled". */
+function groupTitle(findings) {
+    const added = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'added').map((f) => f.path));
+    const removed = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'removed').map((f) => f.path));
+    const retagged = new Set(findings.filter((f) => f.kind === 'dom' && f.change === 'retagged').map((f) => f.path));
+    const restyled = new Set(findings.filter((f) => f.kind !== 'dom' && !added.has(f.path) && !removed.has(f.path)).map((f) => f.path));
+    const n = (c, w) => `${c} ${w}${c === 1 ? '' : 's'}`;
+    const parts = [];
+    if (added.size)
+        parts.push(`${n(added.size, 'element')} added`);
+    if (removed.size)
+        parts.push(`${n(removed.size, 'element')} removed`);
+    if (retagged.size)
+        parts.push(`${n(retagged.size, 'element')} retagged`);
+    if (restyled.size)
+        parts.push(`${n(restyled.size, 'element')} restyled`);
+    return parts.join(', ') || `${n(new Set(findings.map((f) => f.path)).size, 'element')} changed`;
+}
+// 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}\``);
+function beforeAfterTable(rows) {
+    return [
+        '| Property | Before | After |',
+        '| --- | --- | --- |',
+        ...rows.map((r) => `| \`${r.prop}\` | ${cell(r.before)} | ${cell(r.after)} |`),
+    ];
+}
+/** One element's heading + body lines (no leading blank, no ×N suffix). */
+function renderOneElement(group) {
+    const label = prettyLabel(group[0].path, group[0].cls);
+    const dom = group.find((f) => f.kind === 'dom');
+    const styles = group.filter((f) => f.kind === 'style');
+    const states = group.filter((f) => f.kind === 'state');
+    if (dom?.change === 'removed')
+        return { head: `**Removed** \`${label}\``, body: [] };
+    const added = dom?.change === 'added';
+    const head = added
+        ? `**Added** \`${label}\``
+        : dom?.change === 'retagged'
+            ? `**Retagged** \`${label}\` ${dom.detail ?? ''}`
+            : `**\`${label}\`**`;
+    const body = [];
+    for (const s of styles) {
+        const rows = summarizeProps(s.props);
+        if (rows.length)
+            body.push('', s.pseudo ? `On \`${s.pseudo}\`:` : 'Style:', '', ...beforeAfterTable(rows));
+    }
+    if (states.length) {
+        const rows = [];
+        for (const st of states)
+            for (const c of summarizeProps(st.props))
+                rows.push(added
+                    ? `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.after)} |`
+                    : `| \`:${st.state}\` | \`${c.prop}\` | ${cell(c.before)} → ${cell(c.after)} |`);
+        if (rows.length)
+            body.push('', added ? 'Interactive states:' : 'Interactive-state changes:', '', added ? '| State | Property | Value |' : '| State | Property | Before → After |', '| --- | --- | --- |', ...rows);
+    }
+    // Existing element with nothing left to show (all derived) → skip; an
+    // added/removed/retagged element always renders its heading.
+    if (!dom && !body.length)
+        return null;
+    return { head, body };
+}
+/**
+ * Render each changed element ONCE — its base / pseudo / state findings grouped
+ * under a single heading — then collapse identical siblings (same label, same
+ * change at the same level) into one block with a `×N` count. A newly-added
+ * element shows only the values it takes (a brand-new element has no meaningful
+ * "before"); an existing element shows before → after.
+ */
+function renderElements(findings, maxElements = 40) {
+    const byPath = new Map();
     for (const f of findings) {
-        const label = prettyLabel(f.path, f.cls);
-        const note = f.kind === 'state' ? `:${f.state}` : f.kind === 'style' ? (f.pseudo ?? '') : '';
-        const rows = f.kind === 'dom' ? [] : summarizeProps(f.props);
-        const headOnly = f.kind === 'dom' ? `DOM ${f.change}${f.detail ? ` ${f.detail}` : ''}` : '';
-        if (f.kind !== 'dom' && rows.length === 0)
+        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()) {
+        const el = renderOneElement(group);
+        if (!el)
             continue;
-        const key = `${label}|${note}|${headOnly}|${JSON.stringify(rows)}`;
-        const g = byKey.get(key);
-        if (g)
-            g.count++;
+        const sig = `${el.head}\n${el.body.join('\n')}`;
+        const seen = bySig.get(sig);
+        if (seen)
+            seen.count++;
         else {
-            const ng = { label, note: headOnly || note, rows, count: 1 };
-            byKey.set(key, ng);
-            groups.push(ng);
+            const block = { ...el, count: 1 };
+            bySig.set(sig, block);
+            blocks.push(block);
         }
     }
     const out = [];
-    let used = 0;
-    for (let i = 0; i < groups.length; i++) {
-        if (used >= maxRows) {
-            out.push('', `_…and ${groups.length - i} more element(s) — see report.json._`);
+    for (let i = 0; i < blocks.length; i++) {
+        if (i >= maxElements) {
+            out.push('', `_…and ${blocks.length - i} more element(s) — see report.json._`);
             break;
         }
-        const g = groups[i];
-        const head = `**\`${g.label}\`**${g.count > 1 ? ` ×${g.count}` : ''}${g.note ? `  ${g.note}` : ''}`;
-        if (!g.rows.length) {
-            out.push('', head);
-            used += 1;
-            continue;
-        }
-        out.push('', head, '', '| Property | Before | After |', '| --- | --- | --- |', ...g.rows.map((r) => `| \`${r.prop}\` | \`${r.before}\` | \`${r.after}\` |`));
-        used += 2 + g.rows.length;
+        const b = blocks[i];
+        out.push('', b.count > 1 ? `${b.head} ×${b.count}` : b.head, ...b.body);
     }
     return out;
 }
@@ -355,11 +468,31 @@ export function generateStyleMapReport(opts) {
         findings: sd.missing || includeNoise ? sd.findings : sd.findings.filter(hasRealChange).map(stripDerived),
     }))
         .filter((p) => p.sd.missing || p.findings.length > 0);
-    // Count what the report actually shows (after shorthand/dedupe collapsing),
-    // not the raw longhand explosion.
+    // 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);
+    const bySig = new Map();
+    for (const p of prepared) {
+        if (p.sd.missing)
+            continue;
+        const sig = signatureOf(p.findings);
+        const existing = bySig.get(sig);
+        if (existing) {
+            existing.surfaces.push(p.sd.surface);
+            if (surfaceWidth(p.sd.surface) > surfaceWidth(existing.rep.sd.surface))
+                existing.rep = p;
+        }
+        else {
+            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).
     const shown = { dom: 0, style: 0, state: 0 };
-    for (const { findings } of prepared)
-        for (const f of findings) {
+    for (const cg of changeGroups)
+        for (const f of cg.findings) {
             if (f.kind === 'dom')
                 shown.dom++;
             else if (f.kind === 'style')
@@ -367,26 +500,26 @@ export function generateStyleMapReport(opts) {
             else
                 shown.state += summarizeProps(f.props).length;
         }
+    const surfaceCount = changeGroups.reduce((acc, g) => acc + g.surfaces.length, 0) + missing.length;
     const md = [];
     const json = [];
     const img = (rel) => (imageBaseUrl ? `${imageBaseUrl.replace(/\/$/, '')}/${rel}` : rel);
-    md.push('## 🗺️ StyleProof report');
-    md.push('');
-    if (prepared.length === 0) {
+    md.push('## 🗺️ StyleProof report', '');
+    if (changeGroups.length === 0 && missing.length === 0) {
         md.push('✓ All surfaces identical: every computed style, pseudo-element, and hover/focus/active state matches.');
     }
     else {
-        md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** across ${prepared.length} changed surface(s).`);
+        md.push(`**${shown.dom} DOM change(s) · ${shown.style} computed-style difference(s) · ${shown.state} state-delta difference(s)** ` +
+            `across ${changeGroups.length} distinct change(s) in ${surfaceCount} surface(s).`);
     }
     let totalFindings = 0;
-    for (const { sd, findings: surfaceFindings } of prepared) {
-        md.push('', `### \`${sd.surface}\``);
-        if (sd.missing) {
-            md.push('', `⚠️ captured only in the **${sd.missing === 'before' ? 'after' : 'before'}** set — re-run both captures.`);
-            json.push({ surface: sd.surface, missing: sd.missing });
-            continue;
-        }
+    for (const cg of changeGroups) {
+        const { sd, findings: surfaceFindings } = cg.rep;
         totalFindings += surfaceFindings.length;
+        md.push('', `### ${groupTitle(surfaceFindings)}`);
+        md.push('', cg.surfaces.length > 1
+            ? `_Identical across ${cg.surfaces.length} surfaces: ${formatSurfaceList(cg.surfaces)}_`
+            : `_${formatSurfaceList(cg.surfaces)}_`);
         const mapA = loadStyleMap(findCapture(beforeDir, sd.surface));
         const mapB = loadStyleMap(findCapture(afterDir, sd.surface));
         const pngA = readPng(path.join(beforeDir, `${sd.surface}.png`));
@@ -402,12 +535,14 @@ export function generateStyleMapReport(opts) {
                 })),
             ];
         }
-        const surfaceJson = { surface: sd.surface, regions: [] };
+        const surfaceJson = {
+            surfaces: cg.surfaces,
+            representative: sd.surface,
+            regions: [],
+        };
         let n = 0;
         for (const g of groups) {
             n++;
-            const findings = surfaceFindings.filter((f) => g.paths.some((p) => f.path === p || f.path.startsWith(p + ' > ')));
-            const lines = renderFindings(findings);
             const region = visible(g.after) ? g.after : g.before;
             let images = {};
             if (region && pngA && pngB) {
@@ -425,7 +560,7 @@ export function generateStyleMapReport(opts) {
                 writePng(path.join(outDir, `${stem}-composite.png`), composite);
                 images = { before: `${stem}-before.png`, after: `${stem}-after.png`, composite: `${stem}-composite.png` };
                 // One side-by-side image per change: clean inline render, single upload.
-                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', '<sub>◀ before  ·  after ▶</sub>');
+                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface}</sub>`);
             }
             else if (!region) {
                 md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
@@ -433,19 +568,16 @@ export function generateStyleMapReport(opts) {
             else {
                 md.push('', '_No screenshots in these capture sets (run captures with `screenshots: true` for side-by-side crops)._');
             }
-            md.push(...lines);
-            surfaceJson.regions.push({
-                paths: g.paths,
-                before: g.before,
-                after: g.after,
-                images,
-                findings,
-            });
+            surfaceJson.regions.push({ paths: g.paths, before: g.before, after: g.after, images });
         }
+        // The findings, grouped per element, rendered once for the whole group.
+        md.push(...renderElements(surfaceFindings));
+        surfaceJson.findings = surfaceFindings;
         json.push(surfaceJson);
     }
-    if (surfaces.length) {
-        md.push('', '---', '_To accept these changes, regenerate the committed baseline from this build and commit it with your diff._');
+    for (const p of missing) {
+        md.push('', `### \`${p.sd.surface}\``, '', `⚠️ captured only in the **${p.sd.missing === 'before' ? 'after' : 'before'}** set — re-run both captures.`);
+        json.push({ surface: p.sd.surface, missing: p.sd.missing });
     }
     const reportMdPath = path.join(outDir, 'report.md');
     const reportJsonPath = path.join(outDir, 'report.json');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "styleproof",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "Certify CSS refactors with the browser's computed styles: capture every resolved longhand, pseudo-element, and forced hover/focus/active state, then diff before against after.",
   "keywords": [
     "playwright",