styleproof 1.7.1 → 1.8.0

package/CHANGELOG.md

@@ -7,7 +7,39 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
-## [1.7.1]
+## [1.8.0]
+
+The crop now shows you where to look — without painting over the UI.
+
+### Added
+
+- **Annotated crop, alongside the clean one.** Each crop shows the clean
+  before|after composite by default (the real UI), with an annotated twin one
+  click away under a `🔍 Highlight what changed` toggle — a thin magenta outline
+  around each changed element on both sides, so the eye lands on exactly what the
+  bullet named. Outline only (never filled), and the clean image right there
+  proves the box isn't part of the design, so the marker can be confident without
+  reading as a change.
+
+### Changed
+
+- **Tighter, more focused crops.** Default crop padding drops from 24px to 12px
+  (the change fills more of the frame), and up to 8 crop regions per surface
+  (was 6) before collapsing — so distinct changes get their own focused frame
+  instead of one wide merged one. Both are still tunable (`pad`, `maxCrops`).
+- The action now commits the annotated crops alongside the composites.
+
+## [1.7.2]
+
+### Fixed
+
+- **Responsive variants of one change no longer show as duplicate sections.** A
+  grid whose `grid-template-columns/rows` computes to different pixels per width
+  (`282px ×2` vs `282px 228px`) was given a different signature per width, so the
+  same change rendered once per breakpoint. The signature now keys grid tracks by
+  their COUNT, so responsive widths collapse into one grouped section.
+- The `e.g. …` fold line no longer names the `+N more` overflow marker as if it
+  were a change.
 
 ### Fixed
 

package/dist/describe.d.ts

@@ -25,6 +25,8 @@ export declare function toHex(v: string): string;
 /** Reverse-index a token map (`--red-200` → `rgb(...)`) to value → token name,
  *  preferring a scale step (`red-200`) over an alias, then the shorter name. */
 export declare function tokenIndex(tokens?: Record<string, string>): Map<string, string>;
+/** Count grid tracks in a `grid-template-*` value, honouring the `Npx ×K` form. */
+export declare function trackCount(v: string): number;
 /** Token reverse-indexes for each side, so colour rules can name `red-200`. */
 export type DescribeCtx = {
     tokensBefore?: Map<string, string>;

package/dist/describe.js

@@ -117,7 +117,7 @@ const shift = (before, after, idxB, idxA) => {
 };
 // --- track counting for grid columns/rows ------------------------------------
 /** Count grid tracks in a `grid-template-*` value, honouring the `Npx ×K` form. */
-function trackCount(v) {
+export function trackCount(v) {
     if (v === 'none' || !v)
         return 0;
     const rep = v.match(/×(\d+)/); // summarizeProps collapses "8px 8px 8px" → "8px ×3"
@@ -318,10 +318,13 @@ function foldedLine(group, ctx) {
     const common = lists[0].filter((p) => lists.every((l) => l.includes(p)));
     if (common.length)
         return `${common.join(', ')} _(details vary)_`;
+    // Rank the most common REAL changes — the `+N more` overflow marker isn't a
+    // change and shouldn't be named.
     const freq = new Map();
     for (const l of lists)
         for (const p of new Set(l))
-            freq.set(p, (freq.get(p) ?? 0) + 1);
+            if (!/^\+\d+ more$/.test(p))
+                freq.set(p, (freq.get(p) ?? 0) + 1);
     const top = [...freq.entries()]
         .sort((a, b) => b[1] - a[1])
         .slice(0, 3)

package/dist/report.d.ts

@@ -17,14 +17,14 @@ export type ReportOptions = {
     outDir: string;
     /** Prefix for image URLs in report.md (default: relative paths). */
     imageBaseUrl?: string;
-    /** Padding around the union of changed rects (default 24px). */
+    /** Padding around the union of changed rects (default 12px). */
     pad?: number;
     /** Minimum crop size, for context around tiny changes (default 320×180). */
     minWidth?: number;
     minHeight?: number;
     /** Crops taller than this are clamped (default 1600px). */
     maxHeight?: number;
-    /** Max crop regions per surface before collapsing into one union crop (default 6). */
+    /** Max crop regions per surface before collapsing into one union crop (default 8). */
     maxCrops?: number;
     /**
      * Row count at which a crop's property tables fold under a `<details>` toggle

package/dist/report.js

@@ -3,7 +3,7 @@ import path from 'node:path';
 import { PNG } from 'pngjs';
 import { loadStyleMap } from './capture.js';
 import { diffStyleMapDirs } from './diff.js';
-import { describeChange, tokenIndex, toHex } from './describe.js';
+import { describeChange, tokenIndex, toHex, trackCount } 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, tokenIndex, toHex } from './describe.js';
@@ -80,13 +80,13 @@ function cropPng(src, box, w, h) {
     // Center the fixed-size crop on the box, clamped to the image.
     const cx = box.x + box.w / 2;
     const cy = box.y + box.h / 2;
-    const x = Math.max(0, Math.min(Math.round(cx - w / 2), src.width - w));
-    const y = Math.max(0, Math.min(Math.round(cy - h / 2), src.height - h));
+    const ox = Math.max(0, Math.min(Math.round(cx - w / 2), src.width - w));
+    const oy = Math.max(0, Math.min(Math.round(cy - h / 2), src.height - h));
     const cw = Math.min(w, src.width);
     const ch = Math.min(h, src.height);
     const out = new PNG({ width: cw, height: ch });
-    PNG.bitblt(src, out, Math.max(0, x), Math.max(0, y), cw, ch, 0, 0);
-    return out;
+    PNG.bitblt(src, out, Math.max(0, ox), Math.max(0, oy), cw, ch, 0, 0);
+    return { png: out, ox, oy };
 }
 // Lossless but lean: drop the alpha channel (every crop/composite is opaque),
 // max deflate, adaptive per-row filtering. ~15% smaller than the default, and
@@ -108,6 +108,29 @@ function fillRect(png, x, y, w, h, [r, g, b]) {
         }
     }
 }
+// The annotation hue: a magenta no real UI palette tends to use, so an outline
+// reads as a marker, not content. Drawn as a hollow rectangle (never filled) so
+// the UI underneath stays visible — and the clean image alongside proves the box
+// isn't part of the design.
+const HILITE = [255, 0, 200];
+function strokeRect(png, x, y, w, h, t = 2, color = HILITE) {
+    fillRect(png, x, y, w, t, color); // top
+    fillRect(png, x, y + h - t, w, t, color); // bottom
+    fillRect(png, x, y, t, h, color); // left
+    fillRect(png, x + w - t, y, t, h, color); // right
+}
+/** Clone a crop and outline each changed element's box (page coords mapped into
+ *  the crop via its origin), so the eye lands on exactly what the bullet named. */
+function annotateCrop(crop, rects) {
+    const out = new PNG({ width: crop.png.width, height: crop.png.height });
+    PNG.bitblt(crop.png, out, 0, 0, crop.png.width, crop.png.height, 0, 0);
+    for (const [rx, ry, rw, rh] of rects) {
+        if (rw <= 0 || rh <= 0)
+            continue;
+        strokeRect(out, rx - crop.ox, ry - crop.oy, rw, rh);
+    }
+    return out;
+}
 /**
  * One before|after image: the two equal-size crops on a dark canvas with a
  * neutral divider between them. Left is always before; before/after is labelled
@@ -339,6 +362,16 @@ function formatSurfaceList(surfaces) {
     })
         .join(' · ');
 }
+// Grid-track longhands compute to width-dependent pixels (`282px ×2` at one width,
+// `282px 228px` at another), so the SAME responsive change would otherwise get a
+// different signature per width. Key them by track COUNT — what actually
+// identifies the change — so responsive variants group into one section.
+function sigValue(c) {
+    if (c.prop === 'grid-template-columns' || c.prop === 'grid-template-rows') {
+        return `${c.prop}=${trackCount(c.before)}t>${trackCount(c.after)}t`;
+    }
+    return `${c.prop}=${c.before}>${c.after}`;
+}
 /** 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). */
@@ -348,11 +381,7 @@ function signatureOf(findings) {
         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('|'),
+        v: f.kind === 'dom' ? '' : summarizeProps(f.props).map(sigValue).join('|'),
     }))
         .sort((a, b) => `${a.p}|${a.k}|${a.t}`.localeCompare(`${b.p}|${b.k}|${b.t}`)));
 }
@@ -585,7 +614,13 @@ function buildElementChanges(findings) {
     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 { beforeDir, afterDir, outDir, imageBaseUrl = '', 
+    // Tighter than before (was 24) so the change fills the frame — the annotation
+    // box keeps enough context legible.
+    pad: padBy = 12, minWidth = 320, minHeight = 180, maxHeight = 1600, 
+    // More, smaller crops before collapsing (was 6), so distinct changes get their
+    // own focused frame rather than one wide merged one.
+    maxCrops = 8, foldDetailsAt = 0, } = opts;
     const includeNoise = opts.includeLayoutNoise ?? false;
     const { surfaces, volatile: volatileCount } = diffStyleMapDirs(beforeDir, afterDir);
     fs.mkdirSync(path.join(outDir, 'crops'), { recursive: true });
@@ -711,15 +746,19 @@ export function generateStyleMapReport(opts) {
                 const stem = `crops/${sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}`;
                 const before = cropPng(pngA, cropBox, w, h);
                 const after = cropPng(pngB, cropBox, w, h);
-                const composite = compositePair(before, after);
-                writePng(path.join(outDir, `${stem}-before.png`), before);
-                writePng(path.join(outDir, `${stem}-after.png`), after);
+                const composite = compositePair(before.png, after.png);
                 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 crop, left as a PLAIN image (not wrapped in a
-                // link) so GitHub's built-in lightbox opens it in a zoomable popup on click —
-                // a link wrapper would navigate to the file instead.
-                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface} · click to zoom</sub>`);
+                // Annotated twin: outline each changed element on both sides, so the eye
+                // lands on what the bullet named. The clean image stays the default.
+                const rectsA = g.paths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
+                const rectsB = g.paths.map((p) => mapB.elements[p]?.rect).filter((r) => !!r);
+                const annotated = compositePair(annotateCrop(before, rectsA), annotateCrop(after, rectsB));
+                writePng(path.join(outDir, `${stem}-annotated.png`), annotated);
+                images = { composite: `${stem}-composite.png`, annotated: `${stem}-annotated.png` };
+                // Clean before|after shown by default (the real UI); the annotated twin —
+                // boxes marking each change — sits one click away under a toggle. Plain
+                // images (no link wrap) so a click opens the full-resolution file.
+                md.push('', `![before ◀ │ ▶ after](${img(images.composite)})`, '', `<sub>◀ before  ·  after ▶ — ${sd.surface}</sub>`, '', '<details>', '<summary>🔍 Highlight what changed</summary>', '', `![annotated before ◀ │ ▶ after](${img(images.annotated)})`, '', `<sub>magenta boxes mark each change — ${sd.surface}</sub>`, '', '</details>');
             }
             else if (!region) {
                 md.push('', '_Changed element is not visible in this state (zero-size box) — see the property list._');
@@ -747,7 +786,7 @@ export function generateStyleMapReport(opts) {
         if (png) {
             cropSeq++;
             const h = Math.min(maxHeight, png.height);
-            const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h);
+            const crop = cropPng(png, { x: 0, y: 0, w: png.width, h }, png.width, h).png;
             const stem = `crops/${p.sd.surface.replace(/[^a-z0-9-]/gi, '-')}-${cropSeq}-new`;
             writePng(path.join(outDir, `${stem}.png`), crop);
             md.push('', `![new surface — ${side}](${img(`${stem}.png`)})`, '', `<sub>${side} · ${p.sd.surface}${png.height > h ? ' (top of page)' : ''}</sub>`);

package/package.json

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