@cappa/core 0.16.0 → 0.18.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.mjs CHANGED
@@ -187,6 +187,61 @@ var PNG = class PNG {
187
187
  const sourcePath = typeof source === "string" ? source : void 0;
188
188
  return new PNG(info.width, info.height, data, sourcePath, metadata);
189
189
  }
190
+ /**
191
+ * A copy of this image on a `width` × `height` canvas, anchored top-left,
192
+ * with the added area filled with `fill` (RGBA, transparent by default).
193
+ *
194
+ * This is how two screenshots of different sizes are given a shared
195
+ * coordinate space: a component that grew keeps its pixels where they were.
196
+ */
197
+ padTo(width, height, fill = [
198
+ 0,
199
+ 0,
200
+ 0,
201
+ 0
202
+ ]) {
203
+ if (width < this.width_ || height < this.height_) throw new Error(`Cannot pad a ${this.width_}x${this.height_} image to a smaller ${width}x${height} canvas`);
204
+ if (width === this.width_ && height === this.height_) return new PNG(width, height, Buffer.from(this.data_));
205
+ const data = Buffer.alloc(width * height * 4);
206
+ const pixel = Buffer.from(fill);
207
+ for (let offset = 0; offset < data.length; offset += 4) pixel.copy(data, offset);
208
+ const rowBytes = this.width_ * 4;
209
+ for (let y = 0; y < this.height_; y++) this.data_.copy(data, y * width * 4, y * rowBytes, (y + 1) * rowBytes);
210
+ return new PNG(width, height, data);
211
+ }
212
+ /**
213
+ * The most common colour along the right column and the bottom row — the
214
+ * edges a top-left anchored {@link padTo} extends. For a screenshot that is
215
+ * its background, which is what the area it never covered should read as.
216
+ */
217
+ edgeColor() {
218
+ const counts = /* @__PURE__ */ new Map();
219
+ let best = 0;
220
+ let bestCount = 0;
221
+ const count = (x, y) => {
222
+ const value = this.data_.readUInt32BE((y * this.width_ + x) * 4);
223
+ const next = (counts.get(value) ?? 0) + 1;
224
+ counts.set(value, next);
225
+ if (next > bestCount) {
226
+ best = value;
227
+ bestCount = next;
228
+ }
229
+ };
230
+ if (this.width_ === 0 || this.height_ === 0) return [
231
+ 0,
232
+ 0,
233
+ 0,
234
+ 0
235
+ ];
236
+ for (let y = 0; y < this.height_; y++) count(this.width_ - 1, y);
237
+ for (let x = 0; x < this.width_ - 1; x++) count(x, this.height_ - 1);
238
+ return [
239
+ best >>> 24 & 255,
240
+ best >>> 16 & 255,
241
+ best >>> 8 & 255,
242
+ best & 255
243
+ ];
244
+ }
190
245
  get width() {
191
246
  return this.width_;
192
247
  }
@@ -244,21 +299,28 @@ const compare$1 = (image1, image2, diff, width, height, options) => {
244
299
  * @returns Comparison result
245
300
  */
246
301
  async function compareImagesGMSD(image1, image2, withDiff = false, options = {}) {
247
- const [png1, png2] = await Promise.all([loadPNG(image1), loadPNG(image2)]);
248
- const { width, height } = png1;
249
- if (width !== png2.width || height !== png2.height) return {
250
- gmsd: Infinity,
251
- passed: false
252
- };
302
+ const [loaded1, loaded2] = await Promise.all([loadPNG(image1), loadPNG(image2)]);
303
+ const differentSizes = loaded1.width !== loaded2.width || loaded1.height !== loaded2.height;
304
+ const width = Math.max(loaded1.width, loaded2.width);
305
+ const height = Math.max(loaded1.height, loaded2.height);
306
+ const png1 = differentSizes ? loaded1.padTo(width, height, loaded1.edgeColor()) : loaded1;
307
+ const png2 = differentSizes ? loaded2.padTo(width, height, loaded2.edgeColor()) : loaded2;
253
308
  const diff = withDiff ? PNG.create(width, height) : void 0;
254
309
  try {
255
310
  const gmsd = compare$1(png1.data, png2.data, diff?.data, width, height, {
256
311
  downsample: options.downsample ?? 0,
257
312
  c: options.c ?? 170
258
313
  });
314
+ const diffBuffer = diff ? await annotateDiffImage(diff, options).toBuffer() : void 0;
315
+ if (differentSizes) return {
316
+ gmsd,
317
+ diffBuffer,
318
+ passed: false,
319
+ differentSizes: true
320
+ };
259
321
  return {
260
322
  gmsd,
261
- diffBuffer: diff ? await annotateDiffImage(diff, options).toBuffer() : void 0,
323
+ diffBuffer,
262
324
  passed: gmsd <= (options.threshold ?? .1)
263
325
  };
264
326
  } catch (error) {
@@ -295,6 +357,46 @@ async function imagesMatchGMSD(image1, image2, options = {}) {
295
357
  return (await compareImagesGMSD(image1, image2, false, options)).passed;
296
358
  }
297
359
  //#endregion
360
+ //#region src/features/png/canvas.ts
361
+ /**
362
+ * Write copies of two images, padded to a shared canvas, into `dir`.
363
+ *
364
+ * Both are anchored top-left and padded up to the larger width and the larger
365
+ * height, so every pixel keeps its original coordinates and a region found on
366
+ * the canvas points at the same spot in either image.
367
+ *
368
+ * Each image is padded with its own background — the most common colour on
369
+ * the edges being extended — rather than with transparency. Area an image
370
+ * never covered then reads as empty rather than as content: a list that grew
371
+ * by one item diffs as that item (an addition), not as a whole strip that
372
+ * changed, and a component that only gained whitespace diffs as nothing at
373
+ * all, leaving the size change itself as the finding.
374
+ */
375
+ async function writeCommonCanvas(expected, actual, dir) {
376
+ const [expectedPng, actualPng] = await Promise.all([PNG.load(expected), PNG.load(actual)]);
377
+ const width = Math.max(expectedPng.width, actualPng.width);
378
+ const height = Math.max(expectedPng.height, actualPng.height);
379
+ const expectedPath = path.join(dir, "expected-canvas.png");
380
+ const actualPath = path.join(dir, "actual-canvas.png");
381
+ await Promise.all([expectedPng.padTo(width, height, expectedPng.edgeColor()).save(expectedPath), actualPng.padTo(width, height, actualPng.edgeColor()).save(actualPath)]);
382
+ return {
383
+ expectedPath,
384
+ actualPath,
385
+ width,
386
+ height,
387
+ dimensions: {
388
+ expected: {
389
+ width: expectedPng.width,
390
+ height: expectedPng.height
391
+ },
392
+ actual: {
393
+ width: actualPng.width,
394
+ height: actualPng.height
395
+ }
396
+ }
397
+ };
398
+ }
399
+ //#endregion
298
400
  //#region src/compare/pixel.ts
299
401
  async function ensureTempRoot(state) {
300
402
  if (!state.tempRoot) state.tempRoot = await fsp.mkdtemp(path.join(os.tmpdir(), "cappa-pxl-"));
@@ -358,13 +460,7 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
358
460
  }
359
461
  if (nativeResult.match === false) {
360
462
  if (nativeResult.reason === "file-not-exists") throw new Error(`File not found: ${nativeResult.file}`);
361
- if (nativeResult.reason === "layout-diff") return {
362
- numDiffPixels: 0,
363
- totalPixels: 0,
364
- percentDifference: 0,
365
- passed: false,
366
- differentSizes: true
367
- };
463
+ if (nativeResult.reason === "layout-diff") return await compareOnCommonCanvas(p1, p2, withDiff, options, state);
368
464
  }
369
465
  const { width, height } = await readIhdrDimensions(p1);
370
466
  const totalPixels = width * height;
@@ -376,23 +472,10 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
376
472
  passed: isPassed(0, 0, options),
377
473
  differentSizes: false
378
474
  };
379
- let diffBuffer;
380
- if (withDiff && diffPath) {
381
- const rawDiff = await fsp.readFile(diffPath);
382
- const diffMetadata = { "cappa.diff.algorithm": "pixel" };
383
- for (const [key, value] of Object.entries(options)) if (value !== void 0) diffMetadata[`cappa.diff.${key}`] = String(value);
384
- diffBuffer = injectTextMetadata(rawDiff, diffMetadata);
385
- }
475
+ const diffBuffer = withDiff && diffPath ? await readDiffImage(diffPath, options) : void 0;
386
476
  const numDiffPixels = nativeResult.diffCount;
387
477
  const percentDifference = nativeResult.diffPercentage;
388
- let interpretation;
389
- if (wantInterpret && !nativeResult.match) try {
390
- interpretation = await interpret(p1, p2, void 0, {
391
- source: "pixel",
392
- threshold: options.threshold,
393
- antialiasing: options.includeAA ?? false
394
- });
395
- } catch {}
478
+ const interpretation = wantInterpret ? await interpretBestEffort(p1, p2, options) : void 0;
396
479
  return {
397
480
  numDiffPixels,
398
481
  totalPixels,
@@ -409,6 +492,107 @@ async function compareImages(image1, image2, withDiff = false, options = {}) {
409
492
  }).catch(() => {});
410
493
  }
411
494
  }
495
+ async function readDiffImage(diffPath, options) {
496
+ let rawDiff;
497
+ try {
498
+ rawDiff = await fsp.readFile(diffPath);
499
+ } catch {
500
+ return;
501
+ }
502
+ return injectTextMetadata(rawDiff, diffMetadataFor(options));
503
+ }
504
+ function diffMetadataFor(options) {
505
+ const diffMetadata = { "cappa.diff.algorithm": "pixel" };
506
+ for (const [key, value] of Object.entries(options)) if (value !== void 0) diffMetadata[`cappa.diff.${key}`] = String(value);
507
+ return diffMetadata;
508
+ }
509
+ /**
510
+ * The diff for a size change whose padded images match: only background was
511
+ * added or removed. blazediff writes nothing for a match, so this draws one in
512
+ * the same spirit — the image faded out, with the area only one of the two
513
+ * images covers tinted — rather than leave the reviewer a placeholder.
514
+ */
515
+ async function renderSizeOnlyDiff(paddedActualPath, dimensions) {
516
+ const image = await PNG.load(paddedActualPath);
517
+ const sharedWidth = Math.min(dimensions.expected.width, dimensions.actual.width);
518
+ const sharedHeight = Math.min(dimensions.expected.height, dimensions.actual.height);
519
+ const data = image.data;
520
+ for (let y = 0; y < image.height; y++) for (let x = 0; x < image.width; x++) {
521
+ const i = (y * image.width + x) * 4;
522
+ const faded = 255 + (.299 * (data[i] ?? 0) + .587 * (data[i + 1] ?? 0) + .114 * (data[i + 2] ?? 0) - 255) * .1 * (data[i + 3] ?? 0) / 255;
523
+ const outside = x >= sharedWidth || y >= sharedHeight;
524
+ data[i] = outside ? 255 : faded;
525
+ data[i + 1] = outside ? faded * .75 : faded;
526
+ data[i + 2] = outside ? faded * .75 : faded;
527
+ data[i + 3] = 255;
528
+ }
529
+ return image;
530
+ }
531
+ async function interpretBestEffort(expectedPath, actualPath, options) {
532
+ try {
533
+ return await interpret(expectedPath, actualPath, void 0, {
534
+ source: "pixel",
535
+ threshold: options.threshold,
536
+ antialiasing: options.includeAA ?? false
537
+ });
538
+ } catch {
539
+ return;
540
+ }
541
+ }
542
+ /**
543
+ * Compare two images of different sizes on a shared canvas.
544
+ *
545
+ * blazediff refuses a size mismatch outright (`layout-diff`), which used to
546
+ * leave a changed screenshot with no pixel count, no diff image and no
547
+ * regions — exactly the screenshots where something grew or shrank and a
548
+ * reviewer most needs to see where. Padding both to the larger width and
549
+ * height keeps every pixel at its original coordinates, so the diff, the
550
+ * interpretation's region boxes and the review UI all line up with the
551
+ * top-left of either image.
552
+ */
553
+ async function compareOnCommonCanvas(expectedPath, actualPath, withDiff, options, state) {
554
+ const root = await ensureTempRoot(state);
555
+ const canvas = await writeCommonCanvas(expectedPath, actualPath, root);
556
+ const { dimensions, width, height } = canvas;
557
+ const paddedExpected = canvas.expectedPath;
558
+ const paddedActual = canvas.actualPath;
559
+ const diffPath = withDiff ? path.join(root, "diff-canvas.png") : void 0;
560
+ let nativeResult;
561
+ try {
562
+ nativeResult = await compare(paddedExpected, paddedActual, diffPath, toNativeOptions(options));
563
+ } catch (error) {
564
+ const message = error.message || "Unknown error";
565
+ getLogger().error(message);
566
+ return {
567
+ numDiffPixels: 0,
568
+ totalPixels: 0,
569
+ percentDifference: 0,
570
+ passed: false,
571
+ differentSizes: true,
572
+ dimensions,
573
+ error: message
574
+ };
575
+ }
576
+ const matched = nativeResult.match;
577
+ const numDiffPixels = "diffCount" in nativeResult ? nativeResult.diffCount : 0;
578
+ const percentDifference = "diffPercentage" in nativeResult ? nativeResult.diffPercentage : 0;
579
+ let diffBuffer;
580
+ if (withDiff && diffPath) {
581
+ if (matched) diffBuffer = injectTextMetadata(await (await renderSizeOnlyDiff(canvas.actualPath, dimensions)).toBuffer(), diffMetadataFor(options));
582
+ else diffBuffer = await readDiffImage(diffPath, options);
583
+ }
584
+ const interpretation = !matched && options.interpret && withDiff ? await interpretBestEffort(paddedExpected, paddedActual, options) : void 0;
585
+ return {
586
+ numDiffPixels,
587
+ totalPixels: width * height,
588
+ percentDifference,
589
+ diffBuffer,
590
+ passed: false,
591
+ differentSizes: true,
592
+ dimensions,
593
+ interpretation
594
+ };
595
+ }
412
596
  /**
413
597
  * Quick comparison function that returns only pass/fail
414
598
  * @param image1 - Baseline (expected) image (file path or Buffer)
@@ -499,6 +683,247 @@ const attachConsoleLogging = (page, setting, logger) => {
499
683
  });
500
684
  };
501
685
  //#endregion
686
+ //#region src/crop.ts
687
+ const DEFAULT_CROP_PADDING = 8;
688
+ /** The crop to apply, or `undefined` for none. */
689
+ const resolveCrop = (crop) => {
690
+ if (!crop) return void 0;
691
+ const options = crop === true ? {} : crop;
692
+ return {
693
+ root: options.root ?? "body",
694
+ padding: Math.max(0, options.padding ?? 8)
695
+ };
696
+ };
697
+ /**
698
+ * Runs in the page: the union of the boxes of everything `root` paints, in
699
+ * document coordinates.
700
+ *
701
+ * This is the box of the *ink*, not of the elements: a full-width wrapper
702
+ * `div` with nothing of its own to draw does not count, the text and the
703
+ * button inside it do. An element counts when it draws something itself — a
704
+ * background, a border, an outline, a shadow — or is replaced content (an
705
+ * image, an SVG, a canvas, a form control); text counts by the boxes of its
706
+ * line fragments. Descendants of an element that clips its overflow are
707
+ * clipped to it, and nothing inside a hidden or fully transparent subtree is
708
+ * counted.
709
+ *
710
+ * Portals need no special case: anything a component renders elsewhere in
711
+ * `body` — a popover, a dialog and its backdrop — is measured like the rest.
712
+ *
713
+ * Kept free of syntax a bundler might rewrite with a helper (spread, optional
714
+ * catch binding): Playwright ships this function to the browser as source.
715
+ */
716
+ function measurePaintedBox(args) {
717
+ const doc = document;
718
+ const win = window;
719
+ const scrollX = win.scrollX;
720
+ const scrollY = win.scrollY;
721
+ const scrolling = doc.scrollingElement || doc.documentElement;
722
+ const result = {
723
+ box: null,
724
+ scrollX,
725
+ scrollY,
726
+ documentWidth: Math.max(scrolling.scrollWidth, win.innerWidth),
727
+ documentHeight: Math.max(scrolling.scrollHeight, win.innerHeight)
728
+ };
729
+ const root = doc.querySelector(args.root);
730
+ if (!root) return result;
731
+ const NO_CLIP = {
732
+ l: -Infinity,
733
+ t: -Infinity,
734
+ r: Infinity,
735
+ b: Infinity
736
+ };
737
+ let l = Infinity;
738
+ let t = Infinity;
739
+ let r = -Infinity;
740
+ let b = -Infinity;
741
+ const add = (rect, grow, clip) => {
742
+ if (rect.width <= 0 || rect.height <= 0) return;
743
+ const left = Math.max(rect.left - grow, clip.l);
744
+ const top = Math.max(rect.top - grow, clip.t);
745
+ const right = Math.min(rect.right + grow, clip.r);
746
+ const bottom = Math.min(rect.bottom + grow, clip.b);
747
+ if (right <= left || bottom <= top) return;
748
+ if (left < l) l = left;
749
+ if (top < t) t = top;
750
+ if (right > r) r = right;
751
+ if (bottom > b) b = bottom;
752
+ };
753
+ const visibleColor = (color) => {
754
+ if (!color || color === "transparent") return false;
755
+ const slash = color.match(/\/\s*([\d.]+)(%?)\s*\)$/);
756
+ if (slash) return parseFloat(slash[1] || "0") > 0;
757
+ const rgba = color.match(/^rgba\((?:[^,]+,){3}\s*([\d.]+)(%?)\s*\)$/);
758
+ if (rgba) return parseFloat(rgba[1] || "0") > 0;
759
+ return true;
760
+ };
761
+ const shadowExtent = (value) => {
762
+ if (!value || value === "none") return 0;
763
+ let stripped = value;
764
+ let previous = "";
765
+ while (previous !== stripped) {
766
+ previous = stripped;
767
+ stripped = stripped.replace(/[a-z-]+\([^()]*\)/gi, " ");
768
+ }
769
+ let extent = 0;
770
+ const shadows = stripped.split(",");
771
+ for (let i = 0; i < shadows.length; i++) {
772
+ const shadow = shadows[i] || "";
773
+ if (/\binset\b/.test(shadow)) continue;
774
+ const lengths = (shadow.match(/-?\d*\.?\d+px/g) || []).map(parseFloat);
775
+ const reach = Math.max(Math.abs(lengths[0] || 0), Math.abs(lengths[1] || 0)) + Math.max(0, lengths[2] || 0) + (lengths[3] || 0);
776
+ if (reach > extent) extent = reach;
777
+ }
778
+ return extent;
779
+ };
780
+ const REPLACED = {
781
+ IMG: true,
782
+ SVG: true,
783
+ CANVAS: true,
784
+ VIDEO: true,
785
+ IFRAME: true,
786
+ EMBED: true,
787
+ OBJECT: true,
788
+ INPUT: true,
789
+ TEXTAREA: true,
790
+ SELECT: true,
791
+ PROGRESS: true,
792
+ METER: true,
793
+ HR: true
794
+ };
795
+ const SKIPPED = {
796
+ SCRIPT: true,
797
+ STYLE: true,
798
+ LINK: true,
799
+ META: true,
800
+ TEMPLATE: true,
801
+ NOSCRIPT: true
802
+ };
803
+ const range = doc.createRange();
804
+ const paintsSelf = (style) => {
805
+ if (visibleColor(style.backgroundColor)) return true;
806
+ if (style.backgroundImage && style.backgroundImage !== "none") return true;
807
+ const sides = [
808
+ "Top",
809
+ "Right",
810
+ "Bottom",
811
+ "Left"
812
+ ];
813
+ for (let i = 0; i < sides.length; i++) {
814
+ const side = sides[i];
815
+ const width = parseFloat(style.getPropertyValue(`border-${side?.toLowerCase()}-width`));
816
+ const kind = style.getPropertyValue(`border-${side?.toLowerCase()}-style`);
817
+ const color = style.getPropertyValue(`border-${side?.toLowerCase()}-color`);
818
+ if (width > 0 && kind !== "none" && kind !== "hidden" && visibleColor(color)) return true;
819
+ }
820
+ return false;
821
+ };
822
+ const walk = (node, clip, visible, isRoot) => {
823
+ if (node.nodeType === 3) {
824
+ if (!visible || !(node.textContent || "").trim()) return;
825
+ range.selectNodeContents(node);
826
+ const rects = range.getClientRects();
827
+ for (let i = 0; i < rects.length; i++) {
828
+ const rect = rects[i];
829
+ if (rect) add(rect, 0, clip);
830
+ }
831
+ return;
832
+ }
833
+ if (node.nodeType !== 1) return;
834
+ const el = node;
835
+ if (SKIPPED[el.tagName.toUpperCase()]) return;
836
+ const style = win.getComputedStyle(el);
837
+ if (style.display === "none") return;
838
+ if (parseFloat(style.opacity) === 0) return;
839
+ const selfVisible = style.visibility !== "hidden" && style.visibility !== "collapse";
840
+ const rect = el.getBoundingClientRect();
841
+ if (!isRoot && selfVisible) {
842
+ const tag = el.tagName.toUpperCase();
843
+ if (REPLACED[tag]) add(rect, 0, clip);
844
+ else if (paintsSelf(style)) add(rect, 0, clip);
845
+ const shadow = shadowExtent(style.boxShadow);
846
+ if (shadow > 0) add(rect, shadow, clip);
847
+ if (style.outlineStyle !== "none") {
848
+ const outline = (parseFloat(style.outlineWidth) || 0) + (parseFloat(style.outlineOffset) || 0);
849
+ if (outline > 0) add(rect, outline, clip);
850
+ }
851
+ if (REPLACED[tag]) return;
852
+ }
853
+ let childClip = clip;
854
+ const clipsX = style.overflowX !== "visible";
855
+ const clipsY = style.overflowY !== "visible";
856
+ if (!isRoot && (clipsX || clipsY)) childClip = {
857
+ l: clipsX ? Math.max(clip.l, rect.left) : clip.l,
858
+ t: clipsY ? Math.max(clip.t, rect.top) : clip.t,
859
+ r: clipsX ? Math.min(clip.r, rect.right) : clip.r,
860
+ b: clipsY ? Math.min(clip.b, rect.bottom) : clip.b
861
+ };
862
+ const shadowRoot = el.shadowRoot;
863
+ if (shadowRoot) {
864
+ const shadowChildren = shadowRoot.childNodes;
865
+ for (let i = 0; i < shadowChildren.length; i++) {
866
+ const child = shadowChildren[i];
867
+ if (child) walk(child, childClip, selfVisible, false);
868
+ }
869
+ }
870
+ const children = el.childNodes;
871
+ for (let i = 0; i < children.length; i++) {
872
+ const child = children[i];
873
+ if (child) walk(child, childClip, selfVisible, false);
874
+ }
875
+ };
876
+ walk(root, NO_CLIP, true, true);
877
+ range.detach();
878
+ if (r <= l || b <= t) return result;
879
+ result.box = {
880
+ x: l + scrollX,
881
+ y: t + scrollY,
882
+ width: r - l,
883
+ height: b - t
884
+ };
885
+ return result;
886
+ }
887
+ /**
888
+ * The clip for a content-cropped screenshot, or `undefined` when there is
889
+ * nothing to crop to (nothing painted, or the root is missing) — the caller
890
+ * then takes the uncropped screenshot rather than fail.
891
+ *
892
+ * Coordinates follow Playwright's `clip`: relative to the document with
893
+ * `fullPage`, to the viewport without it. Edges are rounded outwards to whole
894
+ * pixels so the crop never cuts into anti-aliased edges, and the padding is
895
+ * clamped to the document so it never asks for pixels that do not exist.
896
+ */
897
+ async function measureContentClip(page, crop, fullPage) {
898
+ const measured = await page.evaluate(measurePaintedBox, { root: crop.root });
899
+ if (!measured.box) return void 0;
900
+ const { box } = measured;
901
+ let left = Math.max(0, Math.floor(box.x - crop.padding));
902
+ let top = Math.max(0, Math.floor(box.y - crop.padding));
903
+ let right = Math.min(measured.documentWidth, Math.ceil(box.x + box.width + crop.padding));
904
+ let bottom = Math.min(measured.documentHeight, Math.ceil(box.y + box.height + crop.padding));
905
+ if (!fullPage) {
906
+ const viewport = page.viewportSize();
907
+ const scrollX = Math.floor(measured.scrollX);
908
+ const scrollY = Math.floor(measured.scrollY);
909
+ left = Math.max(0, left - scrollX);
910
+ top = Math.max(0, top - scrollY);
911
+ right -= scrollX;
912
+ bottom -= scrollY;
913
+ if (viewport) {
914
+ right = Math.min(right, viewport.width);
915
+ bottom = Math.min(bottom, viewport.height);
916
+ }
917
+ }
918
+ if (right <= left || bottom <= top) return void 0;
919
+ return {
920
+ x: left,
921
+ y: top,
922
+ width: right - left,
923
+ height: bottom - top
924
+ };
925
+ }
926
+ //#endregion
502
927
  //#region src/mapWithConcurrency.ts
503
928
  /**
504
929
  * Run async work over `items` with at most `concurrency` tasks in flight.
@@ -1571,6 +1996,8 @@ var ScreenshotTool = class {
1571
1996
  headless;
1572
1997
  viewport;
1573
1998
  fullPage;
1999
+ /** Default content crop; a screenshot's own `crop` overrides it. */
2000
+ crop;
1574
2001
  outputDir;
1575
2002
  browser = null;
1576
2003
  context = null;
@@ -1604,6 +2031,7 @@ var ScreenshotTool = class {
1604
2031
  height: 1080
1605
2032
  };
1606
2033
  this.fullPage = options.fullPage ?? true;
2034
+ this.crop = options.crop ?? false;
1607
2035
  this.outputDir = options.outputDir || "./screenshots";
1608
2036
  this.diff = this.resolveDiffOptions(options.diff);
1609
2037
  this.concurrency = Math.max(1, options.concurrency || 1);
@@ -1782,9 +2210,35 @@ var ScreenshotTool = class {
1782
2210
  try {
1783
2211
  const filepath = this.filesystem.getActualFilePath(filename);
1784
2212
  await this.filesystem.ensureParentDir(filepath);
2213
+ await this.shoot(page, options, filepath);
2214
+ this.logger.success(`Screenshot saved: ${filepath}`);
2215
+ return filepath;
2216
+ } catch (error) {
2217
+ this.logger.error(`Error taking screenshot of ${page.url()}:`, error.message);
2218
+ throw error;
2219
+ }
2220
+ }
2221
+ /**
2222
+ * Take one screenshot with `options`, under its viewport and after its
2223
+ * delay, cropped to the page's content when `crop` asks for it.
2224
+ *
2225
+ * The crop is measured right before the shot, after the delay, so it sees
2226
+ * the same render the screenshot does — and every retry measures afresh.
2227
+ */
2228
+ async shoot(page, options, filepath) {
2229
+ const fullPage = options.fullPage ?? this.fullPage;
2230
+ const crop = resolveCrop(options.crop ?? this.crop);
2231
+ return this.withViewport(page, options.viewport, async () => {
2232
+ if (options.delay) {
2233
+ this.logger.debug(`Waiting ${options.delay}ms before taking screenshot`);
2234
+ await page.waitForTimeout(options.delay);
2235
+ }
2236
+ const clip = crop ? await measureContentClip(page, crop, fullPage) : void 0;
2237
+ if (crop && !clip) this.logger.debug(`Nothing painted inside "${crop.root}" to crop to; taking the uncropped screenshot`);
1785
2238
  const screenshotOptions = {
1786
2239
  path: filepath,
1787
- fullPage: options.fullPage ?? this.fullPage,
2240
+ fullPage,
2241
+ clip,
1788
2242
  type: "png",
1789
2243
  timeout: 6e4,
1790
2244
  mask: options.mask,
@@ -1793,19 +2247,8 @@ var ScreenshotTool = class {
1793
2247
  animations: "disabled",
1794
2248
  caret: "hide"
1795
2249
  };
1796
- await this.withViewport(page, options.viewport, async () => {
1797
- if (options.delay) {
1798
- this.logger.debug(`Waiting ${options.delay}ms before taking screenshot`);
1799
- await page.waitForTimeout(options.delay);
1800
- }
1801
- await page.screenshot(screenshotOptions);
1802
- });
1803
- this.logger.success(`Screenshot saved: ${filepath}`);
1804
- return filepath;
1805
- } catch (error) {
1806
- this.logger.error(`Error taking screenshot of ${page.url()}:`, error.message);
1807
- throw error;
1808
- }
2250
+ return page.screenshot(screenshotOptions);
2251
+ });
1809
2252
  }
1810
2253
  /**
1811
2254
  * Sets the viewport size and executes the action, ensuring the original viewport is restored
@@ -1829,23 +2272,7 @@ var ScreenshotTool = class {
1829
2272
  if (!this.browser) throw new Error("Browser not initialized");
1830
2273
  if (options.skip) throw new Error("Screenshot skipped");
1831
2274
  try {
1832
- const screenshotOptions = {
1833
- fullPage: options.fullPage ?? this.fullPage,
1834
- type: "png",
1835
- timeout: 6e4,
1836
- mask: options.mask,
1837
- omitBackground: options.omitBackground,
1838
- scale: "css",
1839
- animations: "disabled",
1840
- caret: "hide"
1841
- };
1842
- return await this.withViewport(page, options.viewport, async () => {
1843
- if (options.delay) {
1844
- this.logger.debug(`Waiting ${options.delay}ms before taking screenshot`);
1845
- await page.waitForTimeout(options.delay);
1846
- }
1847
- return page.screenshot(screenshotOptions);
1848
- });
2275
+ return await this.shoot(page, options);
1849
2276
  } catch (error) {
1850
2277
  this.logger.error(`Error taking screenshot of ${page.url()}:`, error.message);
1851
2278
  throw error;
@@ -1857,6 +2284,7 @@ var ScreenshotTool = class {
1857
2284
  const filepath = this.filesystem.getActualFilePath(filename);
1858
2285
  const screenshotSettings = {
1859
2286
  fullPage: options.fullPage ?? this.fullPage,
2287
+ crop: options.crop,
1860
2288
  mask: options.mask,
1861
2289
  omitBackground: options.omitBackground,
1862
2290
  delay: options.delay,
@@ -1883,11 +2311,13 @@ var ScreenshotTool = class {
1883
2311
  }
1884
2312
  if (retryScreenshot.comparisonResult !== null && typeof retryScreenshot.comparisonResult === "object" && "differentSizes" in retryScreenshot.comparisonResult && retryScreenshot.comparisonResult.differentSizes) {
1885
2313
  this.logger.warn(`Screenshot has different sizes than reference image`);
1886
- const diffFilename = options.diffImageFilename || filename;
1887
- diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
1888
- const diffBuffer = await createDiffSizePngImage(200, 200);
1889
- await this.filesystem.writeDiffFile(diffFilename, diffBuffer);
1890
- this.logger.debug(`Diff Size image saved: ${diffImagePath}`);
2314
+ if (!diffImagePath) {
2315
+ const diffFilename = options.diffImageFilename || filename;
2316
+ diffImagePath = this.filesystem.getDiffFilePath(diffFilename);
2317
+ const diffBuffer = await createDiffSizePngImage(200, 200);
2318
+ await this.filesystem.writeDiffFile(diffFilename, diffBuffer);
2319
+ this.logger.debug(`Diff Size image saved: ${diffImagePath}`);
2320
+ }
1891
2321
  }
1892
2322
  return {
1893
2323
  screenshotPath: filepath,
@@ -1922,7 +2352,7 @@ var ScreenshotTool = class {
1922
2352
  passed: true
1923
2353
  };
1924
2354
  else {
1925
- const summary = "numDiffPixels" in comparisonResult ? comparisonResult.differentSizes ? "different image sizes" : `${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%)` : `gmsd score ${comparisonResult.gmsd.toFixed(4)}`;
2355
+ const summary = "numDiffPixels" in comparisonResult ? `${comparisonResult.differentSizes ? "different image sizes, " : ""}${comparisonResult.numDiffPixels} pixels different (${comparisonResult.percentDifference.toFixed(2)}%)` : `gmsd score ${comparisonResult.gmsd.toFixed(4)}`;
1926
2356
  this.logger.warn(`Comparison did not match. Retrying in ${this.getIncBackoffDelay(i + 1, options.delay || 0)}ms... \nComparison result: ${summary}`);
1927
2357
  }
1928
2358
  } catch (error) {
@@ -2177,27 +2607,23 @@ var ScreenshotTool = class {
2177
2607
  */
2178
2608
  const AGENT_DIRNAME = ".cappa-agent";
2179
2609
  /** Bumped only if `request.json` or `report.json` change incompatibly. */
2180
- const AGENT_REPORT_VERSION = 1;
2610
+ const AGENT_REPORT_VERSION = 2;
2181
2611
  const agentDir = (outputDir) => path.resolve(outputDir, AGENT_DIRNAME);
2182
2612
  const judgmentsRoot = (outputDir) => path.join(agentDir(outputDir), "judgments");
2183
2613
  const agentReportPath = (outputDir) => path.join(agentDir(outputDir), "report.json");
2184
2614
  //#endregion
2185
2615
  //#region src/agent/verdict.ts
2186
2616
  /**
2187
- * What a reviewer — heuristic or agent — believes a changed screenshot is.
2617
+ * What a judge believes a changed screenshot is, after looking at it.
2188
2618
  *
2189
- * `ambiguous` is only ever produced by the heuristic: it is the signal that
2190
- * the change has to be looked at, and an agent's verdict must resolve it into
2191
- * one of the other three.
2619
+ * Only a judge labels a change. Cappa's diff threshold already absorbs
2620
+ * sub-pixel rendering differences, so a screenshot that reaches `changed`
2621
+ * differs beyond the tolerance the project configured — and classifying it
2622
+ * from diff signals alone (change types, severity, pixel counts) proved to
2623
+ * mislabel exactly the changes that matter: a font-size change reads as a
2624
+ * harmless shift plus recolour. Every changed screenshot is looked at instead.
2192
2625
  */
2193
2626
  const VERDICT_LABELS = [
2194
- "regression-likely",
2195
- "intentional-likely",
2196
- "noise-likely",
2197
- "ambiguous"
2198
- ];
2199
- /** The labels a judge may hand back — everything but `ambiguous`. */
2200
- const JUDGED_LABELS = [
2201
2627
  "regression-likely",
2202
2628
  "intentional-likely",
2203
2629
  "noise-likely"
@@ -2205,103 +2631,43 @@ const JUDGED_LABELS = [
2205
2631
  const ACTION_BY_LABEL = {
2206
2632
  "regression-likely": "investigate",
2207
2633
  "intentional-likely": "approve-if-intended",
2208
- "noise-likely": "mask-or-approve",
2209
- ambiguous: "investigate"
2634
+ "noise-likely": "mask-or-approve"
2210
2635
  };
2211
2636
  const isVerdictLabel = (value) => typeof value === "string" && VERDICT_LABELS.includes(value);
2212
- const isJudgedLabel = (value) => typeof value === "string" && JUDGED_LABELS.includes(value);
2213
2637
  /**
2214
2638
  * Change types are normalised to kebab-case before they are compared.
2215
2639
  *
2216
2640
  * `@blazediff/interpret-native` reports `color-change` today but earlier
2217
- * releases reported `ColorChange`; normalising keeps the heuristic working
2218
- * across a diff-engine upgrade instead of silently degrading every screenshot
2219
- * to `ambiguous`.
2641
+ * releases reported `ColorChange`; normalising keeps the capture report's
2642
+ * labels working across a diff-engine upgrade.
2220
2643
  */
2221
2644
  const normalizeChangeType = (changeType) => changeType.replace(/([a-z0-9])([A-Z])/g, "$1-$2").replace(/[\s_]+/g, "-").toLowerCase();
2222
- const normalizeSeverity = (severity) => (severity ?? "").toLowerCase();
2223
- /** Structural: something appeared, vanished or was replaced. */
2224
- const REGRESSIVE_TYPES = /* @__PURE__ */ new Set([
2225
- "content-change",
2226
- "addition",
2227
- "deletion"
2228
- ]);
2229
- /** Restyled or moved, with structure intact. */
2230
- const RESTYLE_TYPES = /* @__PURE__ */ new Set(["color-change", "shift"]);
2231
- const NOISE_TYPES = /* @__PURE__ */ new Set(["rendering-noise"]);
2232
- const ELEVATED_SEVERITY = /* @__PURE__ */ new Set(["medium", "high"]);
2233
- /** Below this share of the image, a low-severity change is not perceptible. */
2234
- const SUB_PERCEPTUAL_PERCENT = .01;
2235
- /** Mean region confidence above which a pure recolour is trusted. */
2236
- const RECOLOR_CONFIDENCE = .7;
2237
2645
  const formatPercent = (percent) => {
2238
2646
  if (percent === void 0) return "?%";
2239
2647
  return percent >= .01 ? `${percent.toFixed(2)}%` : `${percent.toFixed(3)}%`;
2240
2648
  };
2241
- const countByType = (regions) => {
2242
- const counts = /* @__PURE__ */ new Map();
2243
- for (const region of regions) {
2244
- const type = normalizeChangeType(region.changeType);
2245
- counts.set(type, (counts.get(type) ?? 0) + 1);
2246
- }
2247
- return counts;
2248
- };
2249
- const formatBreakdown = (counts) => [...counts].sort((a, b) => b[1] - a[1]).map(([type, count]) => `${count} ${type}`).join(", ");
2250
2649
  const largestRegion = (regions) => regions.reduce((best, region) => !best || region.pixelCount > best.pixelCount ? region : best, void 0);
2251
- const meanConfidence = (regions) => regions.length === 0 ? 0 : regions.reduce((sum, region) => sum + (region.confidence ?? 0), 0) / regions.length;
2252
2650
  /**
2253
- * A one-line description of a change, shaped so that the same kind of change
2254
- * on different screenshots produces the same headline — which is what lets an
2255
- * agent spot one shared cause (a footer timestamp, a theme toggle) across
2256
- * dozens of screenshots without opening any of them.
2651
+ * A one-line description of where and how much a screenshot changed, shaped
2652
+ * so that the same change on different screenshots produces the same text —
2653
+ * which is what lets a judge spot one shared cause (a footer timestamp, a
2654
+ * theme toggle) across dozens of screenshots and judge them together.
2655
+ *
2656
+ * Deliberately geometry only: no change types, no severity. Those are guesses
2657
+ * from pixel signals, and a judge primed with "noise" or "shift" looks less
2658
+ * carefully at what is in fact a regression.
2257
2659
  */
2258
- const buildHeadline = (input) => {
2259
- if (input.differentSizes) return "image dimensions changed";
2260
- const interpretation = input.interpretation;
2261
- const percent = input.percentDifference ?? interpretation?.diffPercentage;
2262
- if (!interpretation || interpretation.regions.length === 0) return `${(input.numDiffPixels ?? interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no region analysis`;
2263
- const regions = interpretation.regions;
2264
- const counts = countByType(regions);
2660
+ const describeChange = (input) => {
2661
+ const regions = input.interpretation?.regions ?? [];
2662
+ if (input.differentSizes) return regions.length > 0 ? `dimensions changed; ${describeChange({
2663
+ ...input,
2664
+ differentSizes: false
2665
+ })}` : "image dimensions changed";
2666
+ const percent = input.percentDifference ?? input.interpretation?.diffPercentage;
2667
+ if (regions.length === 0) return `${(input.numDiffPixels ?? input.interpretation?.diffCount)?.toLocaleString("en-US") ?? "?"} px (${formatPercent(percent)}) - no regions located`;
2265
2668
  const position = largestRegion(regions)?.position;
2266
2669
  const at = position ? ` @ ${position}` : "";
2267
- const severity = normalizeSeverity(interpretation.severity) || "?";
2268
- if (regions.length === 1) return `1 ${[...counts.keys()][0]}${at} (${formatPercent(percent)}, ${severity})`;
2269
- return `${regions.length} regions: ${formatBreakdown(counts)}${at} (${formatPercent(percent)}, ${severity})`;
2270
- };
2271
- const verdict = (label, headline, rationale) => ({
2272
- label,
2273
- headline,
2274
- rationale,
2275
- action: ACTION_BY_LABEL[label]
2276
- });
2277
- /**
2278
- * Classify a changed screenshot from its diff interpretation alone.
2279
- *
2280
- * Deliberately conservative: only the cases the signals settle are labelled,
2281
- * and everything else is `ambiguous` so that it reaches a judge who can look
2282
- * at the pixels. A wrong `noise-likely` hides a regression; a wrong
2283
- * `ambiguous` costs one look.
2284
- */
2285
- const deriveVerdict = (input) => {
2286
- const headline = buildHeadline(input);
2287
- if (input.differentSizes) return verdict("ambiguous", headline, ["expected and actual have different dimensions — content likely grew or shrank", "could be an intended content change or a broken layout"]);
2288
- const interpretation = input.interpretation;
2289
- if (!interpretation || interpretation.regions.length === 0) return verdict("ambiguous", headline, ["pixels differ but no change regions were found"]);
2290
- const regions = interpretation.regions;
2291
- const types = regions.map((region) => normalizeChangeType(region.changeType));
2292
- const severity = normalizeSeverity(interpretation.severity);
2293
- const percent = input.percentDifference ?? interpretation.diffPercentage;
2294
- const counts = countByType(regions);
2295
- if (types.every((type) => NOISE_TYPES.has(type))) return verdict("noise-likely", headline, ["every region is classified as rendering noise"]);
2296
- if (percent < .01 && severity === "low") return verdict("noise-likely", headline, [`less than ${SUB_PERCEPTUAL_PERCENT}% of the image differs (${formatPercent(percent)}) at low severity`, "sub-perceptual change"]);
2297
- if (types.some((type) => REGRESSIVE_TYPES.has(type)) && ELEVATED_SEVERITY.has(severity)) {
2298
- const structural = [...counts].filter(([type]) => REGRESSIVE_TYPES.has(type)).map(([type, count]) => `${count} ${type}`).join(", ");
2299
- return verdict("regression-likely", headline, [`${severity} severity with structural changes (${structural})`, "content or layout changed, not just styling"]);
2300
- }
2301
- const allRecolor = types.every((type) => type === "color-change");
2302
- if (allRecolor && meanConfidence(regions) > RECOLOR_CONFIDENCE) return verdict("intentional-likely", headline, [`${regions.length} confident color-change ${regions.length === 1 ? "region" : "regions"}`, "edge structure preserved — looks like a theming or palette change"]);
2303
- if (!allRecolor && types.every((type) => RESTYLE_TYPES.has(type))) return verdict("intentional-likely", headline, ["every region is a shift or color change — content moved or was restyled, structure preserved"]);
2304
- return verdict("ambiguous", headline, [`mix of change types (${formatBreakdown(counts)}) at ${severity || "unknown"} severity`, `${formatPercent(percent)} of the image differs`]);
2670
+ return `${`${regions.length} ${regions.length === 1 ? "region" : "regions"}`}${at} (${formatPercent(percent)})`;
2305
2671
  };
2306
2672
  //#endregion
2307
2673
  //#region src/agent/reviewIndex.ts
@@ -2319,11 +2685,11 @@ const readAgentReviewIndex = async (outputDir) => {
2319
2685
  return;
2320
2686
  }
2321
2687
  const createdAt = typeof raw?.createdAt === "string" ? Date.parse(raw.createdAt) : NaN;
2322
- if (raw?.version !== 1 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
2688
+ if (raw?.version !== 2 || Number.isNaN(createdAt) || !Array.isArray(raw.entries)) return;
2323
2689
  const reviews = /* @__PURE__ */ new Map();
2324
2690
  for (const entry of raw.entries) {
2325
2691
  if (typeof entry !== "object" || entry === null) continue;
2326
- const { name, category, verdict, pending } = entry;
2692
+ const { name, category, verdict } = entry;
2327
2693
  if (typeof name !== "string" || category !== "changed") continue;
2328
2694
  if (typeof verdict !== "object" || verdict === null) continue;
2329
2695
  const v = verdict;
@@ -2333,9 +2699,9 @@ const readAgentReviewIndex = async (outputDir) => {
2333
2699
  headline: v.headline,
2334
2700
  rationale: Array.isArray(v.rationale) ? v.rationale.filter((line) => typeof line === "string") : [],
2335
2701
  action: v.action,
2336
- source: v.source === "agent" ? "agent" : "heuristic",
2702
+ source: "agent",
2337
2703
  ...typeof v.confidence === "number" ? { confidence: v.confidence } : {},
2338
- pending: pending === true,
2704
+ pending: false,
2339
2705
  reviewedAt: new Date(createdAt).toISOString()
2340
2706
  });
2341
2707
  }
@@ -2344,9 +2710,15 @@ const readAgentReviewIndex = async (outputDir) => {
2344
2710
  reviews
2345
2711
  };
2346
2712
  };
2713
+ /**
2714
+ * A file's modification time at the report's precision: `createdAt` is an ISO
2715
+ * string, so whole milliseconds, while `mtimeMs` carries a fraction. Compared
2716
+ * unrounded, an image written in the same millisecond the check started would
2717
+ * read as newer than the check and drop a verdict made about it.
2718
+ */
2347
2719
  const modifiedAt = async (file) => {
2348
2720
  try {
2349
- return (await fsp.stat(file)).mtimeMs;
2721
+ return Math.floor((await fsp.stat(file)).mtimeMs);
2350
2722
  } catch {
2351
2723
  return Number.POSITIVE_INFINITY;
2352
2724
  }
@@ -3595,6 +3967,7 @@ var LocalEngine = class {
3595
3967
  concurrency: this.options.concurrency,
3596
3968
  logConsoleEvents: this.options.logConsoleEvents,
3597
3969
  fullPage: this.options.fullPage ?? true,
3970
+ crop: this.options.crop ?? false,
3598
3971
  viewport: this.options.viewport ?? {
3599
3972
  width: 1920,
3600
3973
  height: 1080
@@ -4147,6 +4520,9 @@ const renderOverview = async (options) => {
4147
4520
  * Agent review: turn the screenshots on disk into something a coding agent
4148
4521
  * can judge cheaply, and fold its judgments back in.
4149
4522
  *
4523
+ * Every changed screenshot gets a judgment request. Nothing is labelled from
4524
+ * diff signals alone — see `VERDICT_LABELS` for why.
4525
+ *
4150
4526
  * Nothing here captures. It reads `actual/`, `expected/` and `diff/` as the
4151
4527
  * last `cappa capture` left them, so it is safe to run repeatedly — a re-run
4152
4528
  * is how an agent's verdicts are applied, and a re-capture invalidates them
@@ -4161,7 +4537,7 @@ const renderOverview = async (options) => {
4161
4537
  * judgments/<name>/request.json what to judge and where the evidence is
4162
4538
  * judgments/<name>/locator.png thumbnail with every region outlined
4163
4539
  * judgments/<name>/regions.png [expected | actual] crop per region
4164
- * judgments/<name>/overview.png instead of the two above when sizes differ
4540
+ * judgments/<name>/overview.png both images whole, when their sizes differ
4165
4541
  * judgments/<name>/verdict.json written by the judge
4166
4542
  * ```
4167
4543
  */
@@ -4174,11 +4550,6 @@ const JUDGMENT_FILES = [
4174
4550
  "regions.png",
4175
4551
  "overview.png"
4176
4552
  ];
4177
- const JUDGE_MODES = [
4178
- "ambiguous",
4179
- "all",
4180
- "none"
4181
- ];
4182
4553
  /**
4183
4554
  * The directory holding a screenshot's judgment.
4184
4555
  *
@@ -4231,7 +4602,7 @@ const parseAgentVerdict = (raw) => {
4231
4602
  const outer = raw;
4232
4603
  const inner = typeof outer.verdict === "object" && outer.verdict !== null ? outer.verdict : outer;
4233
4604
  const label = inner.label;
4234
- if (!isJudgedLabel(label)) return {
4605
+ if (!isVerdictLabel(label)) return {
4235
4606
  ok: false,
4236
4607
  error: `label must be one of regression-likely, intentional-likely, noise-likely (got ${JSON.stringify(label)})`
4237
4608
  };
@@ -4260,6 +4631,18 @@ const readSize = async (file) => {
4260
4631
  height
4261
4632
  };
4262
4633
  };
4634
+ /**
4635
+ * Whether the diff on disk can be outlined in the compared coordinate space.
4636
+ *
4637
+ * Same-size screenshots always qualify. For a size change, only a diff of the
4638
+ * padded canvas does — one left by an older capture (a fixed-size
4639
+ * placeholder) would be stretched over the regions and misplace them.
4640
+ */
4641
+ const diffMatchesCanvas = async (diffPath, comparedActual, differentSizes) => {
4642
+ if (!differentSizes) return true;
4643
+ const [diff, canvas] = await Promise.all([readSize(diffPath), readSize(comparedActual)]);
4644
+ return diff.width === canvas.width && diff.height === canvas.height;
4645
+ };
4263
4646
  const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a.pixelCount).map((region, index) => ({
4264
4647
  index: index + 1,
4265
4648
  bbox: {
@@ -4271,9 +4654,7 @@ const toAgentRegions = (regions) => [...regions].sort((a, b) => b.pixelCount - a
4271
4654
  pixelCount: region.pixelCount,
4272
4655
  percentage: region.percentage,
4273
4656
  position: region.position,
4274
- shape: region.shape,
4275
- changeType: normalizeChangeType(region.changeType),
4276
- confidence: region.confidence
4657
+ shape: region.shape
4277
4658
  }));
4278
4659
  /**
4279
4660
  * The interpretation a capture already persisted, or a fresh one.
@@ -4296,8 +4677,10 @@ const interpretationFor = async (screenshot, expectedPath, actualPath, diff) =>
4296
4677
  }
4297
4678
  };
4298
4679
  const JUDGE_INSTRUCTIONS = [
4680
+ "Every changed screenshot differs beyond the project's diff threshold, so sub-pixel rendering is already filtered out: look at each change before labelling it.",
4299
4681
  "Read locator.png and regions.png together. locator.png outlines every region (numbered) on a thumbnail; regions.png stacks one [expected | actual] row per region, in `regions` order.",
4300
- "Open overview.png when it exists instead — the image dimensions changed, so no regions could be located.",
4682
+ "overview.png exists only when the image dimensions changed: it shows both images whole, side by side. Regions are then located on a canvas padded to the larger size, anchored top-left — in a crop, area that only one image covers is empty.",
4683
+ "Compare sizes, not just content: text that is larger, smaller, bolder or reflowed, and spacing, alignment or wrapping that moved, are regressions unless a code change explains them.",
4301
4684
  "Only open paths.expected / paths.actual / paths.diff (full size) when a change clearly continues outside its crop.",
4302
4685
  "Write verdict.json next to this file, or run `cappa agent judge <name> --label <label> --headline <text>`."
4303
4686
  ];
@@ -4317,12 +4700,45 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4317
4700
  readSize(actualPath),
4318
4701
  exists(diffPath)
4319
4702
  ]);
4320
- const differentSizes = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height;
4321
- const interpretation = differentSizes ? void 0 : await interpretationFor(screenshot, expectedPath, actualPath, options.diff);
4703
+ const canvasDir = expectedSize.width !== actualSize.width || expectedSize.height !== actualSize.height ? await fsp.mkdtemp(path.join(os.tmpdir(), "cappa-agent-canvas-")) : void 0;
4704
+ try {
4705
+ const canvas = canvasDir ? await writeCommonCanvas(expectedPath, actualPath, canvasDir) : void 0;
4706
+ return await analyseOnCanvas({
4707
+ screenshot,
4708
+ options,
4709
+ createdAt,
4710
+ paths: {
4711
+ expectedPath,
4712
+ actualPath,
4713
+ diffPath,
4714
+ diffExists
4715
+ },
4716
+ sizes: {
4717
+ expectedSize,
4718
+ actualSize
4719
+ },
4720
+ canvas: canvas ? {
4721
+ expectedPath: canvas.expectedPath,
4722
+ actualPath: canvas.actualPath
4723
+ } : void 0
4724
+ });
4725
+ } finally {
4726
+ if (canvasDir) await fsp.rm(canvasDir, {
4727
+ recursive: true,
4728
+ force: true
4729
+ });
4730
+ }
4731
+ };
4732
+ const analyseOnCanvas = async ({ screenshot, options, createdAt, paths: { expectedPath, actualPath, diffPath, diffExists }, sizes: { expectedSize, actualSize }, canvas }) => {
4733
+ const { outputDir } = options;
4734
+ const differentSizes = canvas !== void 0;
4735
+ const comparedExpected = canvas?.expectedPath ?? expectedPath;
4736
+ const comparedActual = canvas?.actualPath ?? actualPath;
4737
+ const interpretation = await interpretationFor(screenshot, comparedExpected, comparedActual, options.diff);
4322
4738
  const percentDifference = screenshot.diffMeta?.percentDifference ?? interpretation?.diffPercentage;
4323
4739
  const numDiffPixels = screenshot.diffMeta?.numDiffPixels ?? interpretation?.diffCount;
4324
4740
  const regions = toAgentRegions(interpretation?.regions ?? []);
4325
- const heuristic = deriveVerdict({
4741
+ const change = describeChange({
4326
4742
  percentDifference,
4327
4743
  numDiffPixels,
4328
4744
  interpretation,
@@ -4346,20 +4762,13 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4346
4762
  expected: expectedSize,
4347
4763
  actual: actualSize
4348
4764
  },
4349
- severity: interpretation?.severity?.toLowerCase(),
4350
- summary: interpretation?.summary,
4765
+ change,
4351
4766
  regions,
4352
- heuristic,
4353
- verdict: {
4354
- ...heuristic,
4355
- source: "heuristic"
4356
- },
4357
- pending: false
4767
+ pending: true
4358
4768
  };
4359
4769
  const dir = judgmentDir(outputDir, screenshot.name);
4360
4770
  const requestPath = path.join(dir, REQUEST_FILE);
4361
4771
  const verdictPath = path.join(dir, VERDICT_FILE);
4362
- if (!(options.judge === "all" || options.judge === "ambiguous" && heuristic.label === "ambiguous" || await exists(requestPath))) return entry;
4363
4772
  const fingerprint = await fingerprintImages(expectedPath, actualPath);
4364
4773
  const previous = await readJson(requestPath);
4365
4774
  if (previous && previous.fingerprint !== fingerprint) await clearJudgmentFiles(dir);
@@ -4374,11 +4783,11 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4374
4783
  actualPath,
4375
4784
  outDir: dir
4376
4785
  });
4377
- else {
4786
+ if (!differentSizes || regions.length > 0) {
4378
4787
  const tiles = await renderJudgmentTiles({
4379
- expectedPath,
4380
- actualPath,
4381
- diffPath: diffExists ? diffPath : void 0,
4788
+ expectedPath: comparedExpected,
4789
+ actualPath: comparedActual,
4790
+ diffPath: diffExists && await diffMatchesCanvas(diffPath, comparedActual, differentSizes) ? diffPath : void 0,
4382
4791
  regions: regions.map((region) => region.bbox),
4383
4792
  outDir: dir,
4384
4793
  maxRegions: options.maxTileRegions
@@ -4388,7 +4797,7 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4388
4797
  }
4389
4798
  entry.judgment = judgment;
4390
4799
  await writeJson(requestPath, {
4391
- version: 1,
4800
+ version: 2,
4392
4801
  name: entry.name,
4393
4802
  taskId: entry.taskId,
4394
4803
  plugin: entry.plugin,
@@ -4396,12 +4805,10 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4396
4805
  createdAt,
4397
4806
  instructions: JUDGE_INSTRUCTIONS,
4398
4807
  verdictSchema: VERDICT_SCHEMA,
4399
- heuristic,
4808
+ change,
4400
4809
  percentDifference,
4401
4810
  numDiffPixels,
4402
4811
  dimensions: entry.dimensions,
4403
- severity: entry.severity,
4404
- summary: entry.summary,
4405
4812
  regions,
4406
4813
  paths: {
4407
4814
  locator: judgment.locator,
@@ -4413,22 +4820,18 @@ const analyseChanged = async (screenshot, options, createdAt) => {
4413
4820
  verdict: verdictPath
4414
4821
  }
4415
4822
  });
4416
- if (!await exists(verdictPath)) {
4417
- entry.pending = true;
4418
- return entry;
4419
- }
4823
+ if (!await exists(verdictPath)) return entry;
4420
4824
  const parsed = parseAgentVerdict(await readJson(verdictPath));
4421
4825
  if (!parsed.ok) {
4422
- entry.pending = true;
4423
4826
  entry.verdictError = parsed.error;
4424
4827
  return entry;
4425
4828
  }
4829
+ entry.pending = false;
4426
4830
  entry.verdict = {
4427
4831
  label: parsed.label,
4428
4832
  headline: parsed.headline,
4429
4833
  rationale: parsed.rationale,
4430
4834
  action: ACTION_BY_LABEL[parsed.label],
4431
- source: "agent",
4432
4835
  ...parsed.confidence !== void 0 ? { confidence: parsed.confidence } : {}
4433
4836
  };
4434
4837
  return entry;
@@ -4472,13 +4875,12 @@ const pruneJudgments = async (outputDir, keep) => {
4472
4875
  }
4473
4876
  };
4474
4877
  /**
4475
- * Analyse every non-passing screenshot, write judgment requests for the ones
4476
- * that need a judge, apply any verdicts already written, and persist the
4477
- * full report to `<outputDir>/.cappa-agent/report.json`.
4878
+ * Analyse every non-passing screenshot, write a judgment request for every
4879
+ * changed one, apply any verdicts already written, and persist the full
4880
+ * report to `<outputDir>/.cappa-agent/report.json`.
4478
4881
  */
4479
4882
  const runAgentCheck = async (options) => {
4480
4883
  const outputDir = path.resolve(options.outputDir);
4481
- const judge = options.judge ?? "ambiguous";
4482
4884
  const createdAt = (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString();
4483
4885
  const screenshots = await collectScreenshots(outputDir);
4484
4886
  await fsp.mkdir(agentDir(outputDir), { recursive: true });
@@ -4486,8 +4888,7 @@ const runAgentCheck = async (options) => {
4486
4888
  const changed = screenshots.filter((s) => s.category === "changed");
4487
4889
  const changedEntries = await mapWithConcurrency(options.concurrency ?? 4, changed, (screenshot) => analyseChanged(screenshot, {
4488
4890
  ...options,
4489
- outputDir,
4490
- judge
4891
+ outputDir
4491
4892
  }, createdAt));
4492
4893
  await pruneJudgments(outputDir, new Set(changedEntries.flatMap((entry) => entry.judgment ? [entry.judgment.dir] : [])));
4493
4894
  const otherEntries = screenshots.flatMap((s) => {
@@ -4512,11 +4913,10 @@ const runAgentCheck = async (options) => {
4512
4913
  const entries = [...changedEntries, ...otherEntries];
4513
4914
  const count = (category) => screenshots.filter((s) => s.category === category).length;
4514
4915
  const report = {
4515
- version: 1,
4916
+ version: 2,
4516
4917
  createdAt,
4517
4918
  outputDir,
4518
4919
  reportPath: agentReportPath(outputDir),
4519
- judge,
4520
4920
  totals: {
4521
4921
  total: screenshots.length,
4522
4922
  passed: count("passed"),
@@ -4533,7 +4933,7 @@ const runAgentCheck = async (options) => {
4533
4933
  /** Read the report the last {@link runAgentCheck} wrote, if any. */
4534
4934
  const readAgentReport = async (outputDir) => {
4535
4935
  const raw = await readJson(agentReportPath(outputDir));
4536
- return raw?.version === 1 ? raw : void 0;
4936
+ return raw?.version === 2 ? raw : void 0;
4537
4937
  };
4538
4938
  /**
4539
4939
  * The report as an agent should first see it: one line of state per
@@ -4546,11 +4946,11 @@ const toSlimAgentReport = (report) => ({
4546
4946
  results: report.entries.map((entry) => ({
4547
4947
  name: entry.name,
4548
4948
  category: entry.category,
4949
+ ...entry.change ? { change: entry.change } : {},
4549
4950
  ...entry.verdict ? { verdict: {
4550
4951
  label: entry.verdict.label,
4551
4952
  headline: entry.verdict.headline,
4552
- action: entry.verdict.action,
4553
- source: entry.verdict.source
4953
+ action: entry.verdict.action
4554
4954
  } } : {},
4555
4955
  ...entry.pending ? { pending: true } : {},
4556
4956
  ...entry.pending && entry.judgment ? { judgment: entry.judgment.dir } : {},
@@ -4563,7 +4963,7 @@ const toSlimAgentReport = (report) => ({
4563
4963
  */
4564
4964
  const writeAgentVerdict = async (outputDir, name, input) => {
4565
4965
  const dir = judgmentDir(outputDir, name);
4566
- if (!await exists(path.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first (use --judge all to request one for any changed screenshot).`);
4966
+ if (!await exists(path.join(dir, REQUEST_FILE))) throw new Error(`No judgment request for "${name}" — run \`cappa agent check\` first; only changed screenshots get one.`);
4567
4967
  const parsed = parseAgentVerdict(input);
4568
4968
  if (!parsed.ok) throw new Error(parsed.error);
4569
4969
  const verdictPath = path.join(dir, VERDICT_FILE);
@@ -4609,6 +5009,6 @@ function resolveWebServerConfig(webServer, configDir, env = process.env) {
4609
5009
  });
4610
5010
  }
4611
5011
  //#endregion
4612
- export { ACTION_BY_LABEL, AGENT_DIRNAME, AGENT_REPORT_VERSION, CONSOLE_LOG_LEVELS, CaptureRunner, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_KILL_GRACE_MS, DEFAULT_MAX_TASKS, DEFAULT_WEB_SERVER_TIMEOUT_MS, ENGINE_ERROR_CODES, FsScreenshotStore, JUDGED_LABELS, JUDGE_MODES, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, NO_WEB_SERVER_HINT, OutputTail, RunInProgressError, RunStore, SUB_PERCEPTUAL_PERCENT, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, VERDICT_LABELS, WarmBrowser, WatchInProgressError, WatchSession, WebServerError, WebServerPool, agentDir, agentReportPath, attachConsoleLogging, buildHeadline, clearJudgment, collectScreenshots, compareImages, compareImagesGMSD, contextPadding, defineConfig, deriveVerdict, didScreenshotFail, filterTasks, findRefusedConnection, fingerprintImages, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isJudgedLabel, isRunInProgressError, isUnknownTargetsError, isUrlReady, isVerdictLabel, isWatchInProgressError, judgmentDir, mapWithConcurrency, mergeCaptureManifest, normalizeChangeType, padAndClamp, parseAgentVerdict, readAgentReport, readCaptureManifest, readDiffMeta, recordCaptureOrigins, renderJudgmentTiles, renderOverview, resolveWebServerConfig, runAgentCheck, sameServer, sanitizeScreenshotFilename, selectTasks, spawnServerProcess, toConsoleLogLevel, toDiffMetaPath, toManifestKey, toSerializedError, toSlimAgentReport, toTaskStatus, waitForUrl, writeAgentVerdict };
5012
+ export { ACTION_BY_LABEL, AGENT_DIRNAME, AGENT_REPORT_VERSION, CONSOLE_LOG_LEVELS, CaptureRunner, DEFAULT_CROP_PADDING, DEFAULT_DEBOUNCE_MS, DEFAULT_IGNORED_DIRS, DEFAULT_KILL_GRACE_MS, DEFAULT_MAX_TASKS, DEFAULT_WEB_SERVER_TIMEOUT_MS, ENGINE_ERROR_CODES, FsScreenshotStore, LocalEngine, MANIFEST_FILENAME, MANIFEST_VERSION, NO_WEB_SERVER_HINT, OutputTail, RunInProgressError, RunStore, ScreenshotFileSystem, ScreenshotTool, UnknownTargetsError, VERDICT_LABELS, WarmBrowser, WatchInProgressError, WatchSession, WebServerError, WebServerPool, agentDir, agentReportPath, attachConsoleLogging, clearJudgment, collectScreenshots, compareImages, compareImagesGMSD, contextPadding, defineConfig, describeChange, didScreenshotFail, filterTasks, findRefusedConnection, fingerprintImages, getDeletedScreenshots, groupScreenshots, imagesMatch, imagesMatchGMSD, isRunInProgressError, isUnknownTargetsError, isUrlReady, isVerdictLabel, isWatchInProgressError, judgmentDir, mapWithConcurrency, measureContentClip, mergeCaptureManifest, normalizeChangeType, padAndClamp, parseAgentVerdict, readAgentReport, readCaptureManifest, readDiffMeta, recordCaptureOrigins, renderJudgmentTiles, renderOverview, resolveCrop, resolveWebServerConfig, runAgentCheck, sameServer, sanitizeScreenshotFilename, selectTasks, spawnServerProcess, toConsoleLogLevel, toDiffMetaPath, toManifestKey, toSerializedError, toSlimAgentReport, toTaskStatus, waitForUrl, writeAgentVerdict };
4613
5013
 
4614
5014
  //# sourceMappingURL=index.mjs.map