styleproof 1.7.2 → 1.8.1

package/CHANGELOG.md

@@ -7,6 +7,37 @@ this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ## [Unreleased]
 
+## [1.8.1]
+
+### Fixed
+
+- The crop annotation now boxes the **innermost** changed elements (the added
+  avatars, the restyled cards) instead of the container the crop anchors on —
+  whose box just traced the whole frame and told you nothing. An element present
+  on only one side (added/removed) is boxed only there.
+
+## [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

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

@@ -20,10 +20,17 @@ const union = (a, b) => {
 };
 const intersects = (a, b) => a.x < b.x + b.w && b.x < a.x + a.w && a.y < b.y + b.h && b.y < a.y + a.h;
 const visible = (b) => !!b && b.w > 0 && b.h > 0;
-/** Outermost changed paths: drop any path that has a changed strict ancestor. */
+/** Outermost changed paths: drop any path that has a changed strict ancestor.
+ *  Used to ANCHOR a crop (zoom to the whole changed region, not a leaf). */
 function outermost(paths) {
     return paths.filter((p) => !paths.some((q) => q !== p && p.startsWith(q + ' > ')));
 }
+/** Innermost changed paths: drop any path that has a changed strict descendant.
+ *  Used to ANNOTATE — box the leaf elements that actually changed (the added
+ *  avatars, the restyled cards), not their container, whose box ≈ the whole crop. */
+function innermost(paths) {
+    return paths.filter((p) => !paths.some((q) => q !== p && q.startsWith(p + ' > ')));
+}
 /** Headline counts with the zeros dropped — `0 state-delta difference(s)` is noise. */
 function changeCountLabel(shown) {
     const parts = [];
@@ -80,13 +87,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 +115,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
@@ -591,7 +621,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 });
@@ -717,15 +753,22 @@ 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 the LEAF changed elements (the added avatars, the
+                // restyled cards) on each side — not the merged container the crop anchors
+                // on, whose box would just trace the whole frame. An element present on only
+                // one side (added/removed) is boxed only there.
+                const markPaths = innermost([...new Set(regionFindings.map((f) => f.path))]);
+                const rectsA = markPaths.map((p) => mapA.elements[p]?.rect).filter((r) => !!r);
+                const rectsB = markPaths.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._');
@@ -753,7 +796,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.2",
+  "version": "1.8.1",
   "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",