styleproof 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -7,6 +7,29 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [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 +215,8 @@ 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.1.0...HEAD
+[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/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,17 +568,17 @@ 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);
     }
+    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 });
+    }
     if (surfaces.length) {
         md.push('', '---', '_To accept these changes, regenerate the committed baseline from this build and commit it with your diff._');
     }

package/package.json

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