vitest-plugin-vis 5.1.8 → 5.2.1

package/dist/shared/review_image.mjs

@@ -0,0 +1,160 @@
+//#region src/shared/review_image.ts
+/**
+* The longest edge of the review image, in pixels.
+*/
+const REVIEW_IMAGE_MAX_EDGE = 2576;
+/**
+* The review image is skipped when there are more regions than this.
+*/
+const REVIEW_IMAGE_MAX_REGIONS = 5;
+/**
+* The review image is skipped when the regions cover more than this share of the image.
+*/
+const REVIEW_IMAGE_MAX_COVERAGE = .5;
+const CROP_GAP = 4;
+const REGION_GAP = 16;
+const GAP_COLOR = [
+	128,
+	128,
+	128,
+	255
+];
+const CHANGED_COLOR = [
+	255,
+	0,
+	0,
+	255
+];
+/**
+* Returns why a review image does not help, or `undefined` when it does.
+*/
+function getReviewImageSkipReason({ baseline, result, regions }) {
+	if (baseline.width !== result.width || baseline.height !== result.height) return "the image size changed";
+	if (regions.length === 0) return "no changed region found";
+	if (regions.length > REVIEW_IMAGE_MAX_REGIONS) return `${regions.length} regions, more than ${REVIEW_IMAGE_MAX_REGIONS}`;
+	const coverage = regions.reduce((sum, r) => sum + r.width * r.height, 0) / (baseline.width * baseline.height);
+	if (coverage > REVIEW_IMAGE_MAX_COVERAGE) return `the regions cover ${Math.round(coverage * 100)}% of the image`;
+}
+/**
+* Creates one image that shows, for each region, the baseline crop, the result crop, and the diff crop.
+*
+* A wide region places its crops top to bottom, a narrow one left to right.
+* Regions are placed top to bottom.
+* The diff crop shows the baseline in grayscale at full contrast with the changed pixels in red.
+* The image is scaled down to fit {@link REVIEW_IMAGE_MAX_EDGE}.
+*
+* @param mask One byte per pixel of the baseline; non-zero marks a changed pixel.
+*/
+function createReviewImage(baseline, result, mask, regions) {
+	return fitWithin(stack(regions.map((region) => {
+		const crops = [
+			crop(baseline, region),
+			crop(result, region),
+			createDiffCrop(baseline, mask, region)
+		];
+		return region.width > region.height ? stack(crops, "vertical", CROP_GAP) : stack(crops, "horizontal", CROP_GAP);
+	}), "vertical", REGION_GAP), REVIEW_IMAGE_MAX_EDGE);
+}
+function crop(image, { x, y, width, height }) {
+	const data = new Uint8ClampedArray(width * height * 4);
+	for (let row = 0; row < height; row++) {
+		const start = ((y + row) * image.width + x) * 4;
+		data.set(image.data.subarray(start, start + width * 4), row * width * 4);
+	}
+	return {
+		data,
+		width,
+		height
+	};
+}
+function createDiffCrop(image, mask, { x, y, width, height }) {
+	const data = new Uint8ClampedArray(width * height * 4);
+	for (let row = 0; row < height; row++) for (let col = 0; col < width; col++) {
+		const i = (y + row) * image.width + x + col;
+		const pos = (row * width + col) * 4;
+		if (mask[i]) {
+			data.set(CHANGED_COLOR, pos);
+			continue;
+		}
+		const src = i * 4;
+		const r = image.data[src];
+		const g = image.data[src + 1];
+		const b = image.data[src + 2];
+		const a = image.data[src + 3];
+		const gray = 255 + (.29889531 * r + .58662247 * g + .11448223 * b - 255) * a / 255;
+		data[pos] = gray;
+		data[pos + 1] = gray;
+		data[pos + 2] = gray;
+		data[pos + 3] = 255;
+	}
+	return {
+		data,
+		width,
+		height
+	};
+}
+function stack(images, direction, gap) {
+	const horizontal = direction === "horizontal";
+	const gaps = gap * (images.length - 1);
+	const width = horizontal ? images.reduce((sum, image) => sum + image.width, gaps) : Math.max(...images.map((image) => image.width));
+	const height = horizontal ? Math.max(...images.map((image) => image.height)) : images.reduce((sum, image) => sum + image.height, gaps);
+	const data = new Uint8ClampedArray(width * height * 4);
+	for (let i = 0; i < data.length; i += 4) data.set(GAP_COLOR, i);
+	let offset = 0;
+	for (const image of images) {
+		const x = horizontal ? offset : 0;
+		const y = horizontal ? 0 : offset;
+		for (let row = 0; row < image.height; row++) data.set(image.data.subarray(row * image.width * 4, (row + 1) * image.width * 4), ((y + row) * width + x) * 4);
+		offset += (horizontal ? image.width : image.height) + gap;
+	}
+	return {
+		data,
+		width,
+		height
+	};
+}
+/**
+* Scales the image down, averaging the pixels each target pixel covers,
+* so its longest edge is at most `maxEdge`.
+*/
+function fitWithin(image, maxEdge) {
+	const scale = maxEdge / Math.max(image.width, image.height);
+	if (scale >= 1) return image;
+	const width = Math.max(1, Math.round(image.width * scale));
+	const height = Math.max(1, Math.round(image.height * scale));
+	const data = new Uint8ClampedArray(width * height * 4);
+	for (let y = 0; y < height; y++) {
+		const fromY = Math.floor(y * image.height / height);
+		const toY = Math.max(fromY + 1, Math.floor((y + 1) * image.height / height));
+		for (let x = 0; x < width; x++) {
+			const fromX = Math.floor(x * image.width / width);
+			const toX = Math.max(fromX + 1, Math.floor((x + 1) * image.width / width));
+			let r = 0;
+			let g = 0;
+			let b = 0;
+			let a = 0;
+			for (let sy = fromY; sy < toY; sy++) for (let sx = fromX; sx < toX; sx++) {
+				const src = (sy * image.width + sx) * 4;
+				r += image.data[src];
+				g += image.data[src + 1];
+				b += image.data[src + 2];
+				a += image.data[src + 3];
+			}
+			const count = (toY - fromY) * (toX - fromX);
+			const pos = (y * width + x) * 4;
+			data[pos] = r / count;
+			data[pos + 1] = g / count;
+			data[pos + 2] = b / count;
+			data[pos + 3] = a / count;
+		}
+	}
+	return {
+		data,
+		width,
+		height
+	};
+}
+
+//#endregion
+export { createReviewImage, getReviewImageSkipReason };
+//# sourceMappingURL=review_image.mjs.map

package/dist/shared/review_image.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"review_image.mjs","names":[],"sources":["../../src/shared/review_image.ts"],"sourcesContent":["import type { ChangedRegion } from './changed_regions.ts'\n\n/**\n * Raw RGBA pixels, compatible with `ImageData`.\n */\nexport type PixelImage = {\n\tdata: Uint8ClampedArray<ArrayBuffer>\n\twidth: number\n\theight: number\n}\n\n/**\n * The longest edge of the review image, in pixels.\n */\nexport const REVIEW_IMAGE_MAX_EDGE = 2576\n\n/**\n * The review image is skipped when there are more regions than this.\n */\nexport const REVIEW_IMAGE_MAX_REGIONS = 5\n\n/**\n * The review image is skipped when the regions cover more than this share of the image.\n */\nexport const REVIEW_IMAGE_MAX_COVERAGE = 0.5\n\nconst CROP_GAP = 4\nconst REGION_GAP = 16\nconst GAP_COLOR = [128, 128, 128, 255] as const\nconst CHANGED_COLOR = [255, 0, 0, 255] as const\n\n/**\n * Returns why a review image does not help, or `undefined` when it does.\n */\nexport function getReviewImageSkipReason({\n\tbaseline,\n\tresult,\n\tregions,\n}: {\n\tbaseline: { width: number; height: number }\n\tresult: { width: number; height: number }\n\tregions: ChangedRegion[]\n}) {\n\tif (baseline.width !== result.width || baseline.height !== result.height) return 'the image size changed'\n\tif (regions.length === 0) return 'no changed region found'\n\tif (regions.length > REVIEW_IMAGE_MAX_REGIONS)\n\t\treturn `${regions.length} regions, more than ${REVIEW_IMAGE_MAX_REGIONS}`\n\tconst area = regions.reduce((sum, r) => sum + r.width * r.height, 0)\n\tconst coverage = area / (baseline.width * baseline.height)\n\tif (coverage > REVIEW_IMAGE_MAX_COVERAGE) return `the regions cover ${Math.round(coverage * 100)}% of the image`\n\treturn undefined\n}\n\n/**\n * Creates one image that shows, for each region, the baseline crop, the result crop, and the diff crop.\n *\n * A wide region places its crops top to bottom, a narrow one left to right.\n * Regions are placed top to bottom.\n * The diff crop shows the baseline in grayscale at full contrast with the changed pixels in red.\n * The image is scaled down to fit {@link REVIEW_IMAGE_MAX_EDGE}.\n *\n * @param mask One byte per pixel of the baseline; non-zero marks a changed pixel.\n */\nexport function createReviewImage(\n\tbaseline: PixelImage,\n\tresult: PixelImage,\n\tmask: ArrayLike<number>,\n\tregions: ChangedRegion[],\n): PixelImage {\n\tconst panels = regions.map((region) => {\n\t\tconst crops = [crop(baseline, region), crop(result, region), createDiffCrop(baseline, mask, region)]\n\t\treturn region.width > region.height ? stack(crops, 'vertical', CROP_GAP) : stack(crops, 'horizontal', CROP_GAP)\n\t})\n\treturn fitWithin(stack(panels, 'vertical', REGION_GAP), REVIEW_IMAGE_MAX_EDGE)\n}\n\nfunction crop(image: PixelImage, { x, y, width, height }: ChangedRegion): PixelImage {\n\tconst data = new Uint8ClampedArray(width * height * 4)\n\tfor (let row = 0; row < height; row++) {\n\t\tconst start = ((y + row) * image.width + x) * 4\n\t\tdata.set(image.data.subarray(start, start + width * 4), row * width * 4)\n\t}\n\treturn { data, width, height }\n}\n\nfunction createDiffCrop(\n\timage: PixelImage,\n\tmask: ArrayLike<number>,\n\t{ x, y, width, height }: ChangedRegion,\n): PixelImage {\n\tconst data = new Uint8ClampedArray(width * height * 4)\n\tfor (let row = 0; row < height; row++) {\n\t\tfor (let col = 0; col < width; col++) {\n\t\t\tconst i = (y + row) * image.width + x + col\n\t\t\tconst pos = (row * width + col) * 4\n\t\t\tif (mask[i]) {\n\t\t\t\tdata.set(CHANGED_COLOR, pos)\n\t\t\t\tcontinue\n\t\t\t}\n\t\t\tconst src = i * 4\n\t\t\tconst r = image.data[src]!\n\t\t\tconst g = image.data[src + 1]!\n\t\t\tconst b = image.data[src + 2]!\n\t\t\tconst a = image.data[src + 3]!\n\t\t\tconst luma = 0.29889531 * r + 0.58662247 * g + 0.11448223 * b\n\t\t\t// blend with white by the pixel's own alpha only, so the baseline is not faded\n\t\t\tconst gray = 255 + ((luma - 255) * a) / 255\n\t\t\tdata[pos] = gray\n\t\t\tdata[pos + 1] = gray\n\t\t\tdata[pos + 2] = gray\n\t\t\tdata[pos + 3] = 255\n\t\t}\n\t}\n\treturn { data, width, height }\n}\n\nfunction stack(images: PixelImage[], direction: 'horizontal' | 'vertical', gap: number): PixelImage {\n\tconst horizontal = direction === 'horizontal'\n\tconst gaps = gap * (images.length - 1)\n\tconst width = horizontal\n\t\t? images.reduce((sum, image) => sum + image.width, gaps)\n\t\t: Math.max(...images.map((image) => image.width))\n\tconst height = horizontal\n\t\t? Math.max(...images.map((image) => image.height))\n\t\t: images.reduce((sum, image) => sum + image.height, gaps)\n\tconst data = new Uint8ClampedArray(width * height * 4)\n\tfor (let i = 0; i < data.length; i += 4) data.set(GAP_COLOR, i)\n\n\tlet offset = 0\n\tfor (const image of images) {\n\t\tconst x = horizontal ? offset : 0\n\t\tconst y = horizontal ? 0 : offset\n\t\tfor (let row = 0; row < image.height; row++) {\n\t\t\tdata.set(image.data.subarray(row * image.width * 4, (row + 1) * image.width * 4), ((y + row) * width + x) * 4)\n\t\t}\n\t\toffset += (horizontal ? image.width : image.height) + gap\n\t}\n\treturn { data, width, height }\n}\n\n/**\n * Scales the image down, averaging the pixels each target pixel covers,\n * so its longest edge is at most `maxEdge`.\n */\nfunction fitWithin(image: PixelImage, maxEdge: number): PixelImage {\n\tconst scale = maxEdge / Math.max(image.width, image.height)\n\tif (scale >= 1) return image\n\n\tconst width = Math.max(1, Math.round(image.width * scale))\n\tconst height = Math.max(1, Math.round(image.height * scale))\n\tconst data = new Uint8ClampedArray(width * height * 4)\n\tfor (let y = 0; y < height; y++) {\n\t\tconst fromY = Math.floor((y * image.height) / height)\n\t\tconst toY = Math.max(fromY + 1, Math.floor(((y + 1) * image.height) / height))\n\t\tfor (let x = 0; x < width; x++) {\n\t\t\tconst fromX = Math.floor((x * image.width) / width)\n\t\t\tconst toX = Math.max(fromX + 1, Math.floor(((x + 1) * image.width) / width))\n\t\t\tlet r = 0\n\t\t\tlet g = 0\n\t\t\tlet b = 0\n\t\t\tlet a = 0\n\t\t\tfor (let sy = fromY; sy < toY; sy++) {\n\t\t\t\tfor (let sx = fromX; sx < toX; sx++) {\n\t\t\t\t\tconst src = (sy * image.width + sx) * 4\n\t\t\t\t\tr += image.data[src]!\n\t\t\t\t\tg += image.data[src + 1]!\n\t\t\t\t\tb += image.data[src + 2]!\n\t\t\t\t\ta += image.data[src + 3]!\n\t\t\t\t}\n\t\t\t}\n\t\t\tconst count = (toY - fromY) * (toX - fromX)\n\t\t\tconst pos = (y * width + x) * 4\n\t\t\tdata[pos] = r / count\n\t\t\tdata[pos + 1] = g / count\n\t\t\tdata[pos + 2] = b / count\n\t\t\tdata[pos + 3] = a / count\n\t\t}\n\t}\n\treturn { data, width, height }\n}\n"],"mappings":"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"}

package/dist/shared/types.d.mts

@@ -19,6 +19,21 @@ interface ImageSnapshotKeyOptions {
    */
   snapshotKey?: string | undefined;
 }
+interface ReviewImageOptions {
+  /**
+   * When the snapshot mismatches, write a review image next to the diff.
+   *
+   * The review image places the baseline, result, and diff crops of each changed region side by side,
+   * so a person or an agent can see what changed without opening the full images.
+   * It is skipped when cropping does not help:
+   * the image size changed, there are many regions, or the regions cover most of the image.
+   *
+   * The changed regions are written as JSON next to the diff either way.
+   *
+   * @default true
+   */
+  reviewImage?: boolean | undefined;
+}
 type ComparisonMethod = 'pixel' | 'ssim';
 type FailureThresholdOptions = {
   /**
@@ -75,7 +90,7 @@ type ImageSnapshotSubjectOptions = {
    */
   subject?: string | undefined;
 };
-type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions & ImageSnapshotKeyOptions & ImageSnapshotCompareOptions<M> & {
+type ToMatchImageSnapshotOptions<M extends ComparisonMethod = 'pixel'> = ImageSnapshotTimeoutOptions & ImageSnapshotKeyOptions & ImageSnapshotCompareOptions<M> & ReviewImageOptions & {
   /**
    * Expect the matcher to fail.
    * If it passes, it will throw an error with details.
@@ -130,8 +145,8 @@ type ImageSnapshotComparisonInfo = {
    * Base64 encoded diff image.
    */
   diff?: string | undefined;
-} & ImageSnapshotTimeoutOptions & FailureThresholdOptions & (SsimComparisonOptions | PixelComparisonOptions);
-type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions & ImageSnapshotCompareOptions<any> & ImageSnapshotKeyOptions & {
+} & ImageSnapshotTimeoutOptions & FailureThresholdOptions & ReviewImageOptions & (SsimComparisonOptions | PixelComparisonOptions);
+type MatchImageSnapshotOptions = ImageSnapshotTimeoutOptions & ImageSnapshotCompareOptions<any> & ImageSnapshotKeyOptions & ReviewImageOptions & {
   /**
    * When `true`, write a missing baseline on first run (see {@link ToMatchImageSnapshotOptions} `createMissingBaseline`).
    */
@@ -147,5 +162,5 @@ type SetupVisOptions<GM extends Record<string, any> | unknown = unknown> = {
   createMissingBaseline?: boolean | undefined;
 };
 //#endregion
-export { Awaitable, ComparisonMethod, FailureThresholdOptions, ImageSnapshotCompareOptions, ImageSnapshotComparisonInfo, ImageSnapshotKeyOptions, ImageSnapshotSubjectOptions, ImageSnapshotTimeoutOptions, MatchImageSnapshotOptions, PageImageSnapshotOptions, PixelComparisonOptions, PixelDiffOptions, SetupVisOptions, SnapshotTestMeta, SsimComparisonOptions, type SsimDiffOptions, ToMatchImageSnapshotOptions, ToMatchPageImageSnapshotOptions };
+export { Awaitable, ComparisonMethod, FailureThresholdOptions, ImageSnapshotCompareOptions, ImageSnapshotComparisonInfo, ImageSnapshotKeyOptions, ImageSnapshotSubjectOptions, ImageSnapshotTimeoutOptions, MatchImageSnapshotOptions, PageImageSnapshotOptions, PixelComparisonOptions, PixelDiffOptions, ReviewImageOptions, SetupVisOptions, SnapshotTestMeta, SsimComparisonOptions, type SsimDiffOptions, ToMatchImageSnapshotOptions, ToMatchPageImageSnapshotOptions };
 //# sourceMappingURL=types.d.mts.map

package/dist/shared/types.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/shared/types.ts"],"sourcesContent":[],"mappings":";;;;;;KAKY,eAAe,IAAI,YAAY;UAE1B,2BAAA;EAFL;;;;;EAEK,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AASjB;AAOY,UAPK,uBAAA,CAOW;EAEhB;AA6BZ;;EAKuB,WAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;AAAD,KApCV,gBAAA,GAoCU,OAAA,GAAA,MAAA;AAKV,KAvCA,uBAAA,GAuCsB;EAQtB;AAEZ;;;;EACG,oBAAA,CAAA,EAAA,OAAA,GAAA,SAAA,GAAA,SAAA;EACuB;;;;AAG1B;AAWA;;;;;;;AAmBA;AAIA;;;;;;EAGY,gBAAA,CAAA,EAAgB,MAAA,GAAA,SAAA;CAEJ;AAAb,KAhEC,qBAgED,CAAA,IAAA,MAAA,CAAA,GAAA;EAAR,gBAAA,EA/DgB,CA+DhB;EAAI;AAIP;;EA+BC,WAAA,CAAA,EA9Fc,OA8Fd,CA9FsB,eA8FtB,CAAA,GAAA,SAAA;CACC;AAA8C,KA1FpC,sBA0FoC,CAAA,IAAA,OAAA,CAAA,GAAA;EAEpC,gBAAA,CAAA,EA3FQ,CA2FR,GAAA,SAAyB;EAAG;;;EAEhB,WAAA,CAAA,EAzFT,gBAyFS,GAAA,SAAA;AAOxB,CAAA;AAAuC,KA7F3B,gBAAA,GAAmB,UA6FQ,CAAA,OA7FU,UA6FV,CAAA,CAAA,CAAA,CAAA;AAGvB,KA9FJ,2BA8FI,CAAA,UA9FkC,gBA8FlC,GAAA,OAAA,CAAA,GAAA,CA9FiE,CA8FjE,SAAA,MAAA,GA7Fb,qBA6Fa,CA7FS,CA6FT,CAAA,GA5Fb,sBA4Fa,CA5FU,CA4FV,CAAA,CAAA,GA3Ff,uBA2Fe;AAA4B,KAzFhC,2BAAA,GAyFgC;EAClB;;;;;;;;EAME,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CAAb;AAAkB,KArFrB,2BAqFqB,CAAA,UArFiB,gBAqFjB,GAAA,OAAA,CAAA,GArF+C,2BAqF/C,GApFhC,uBAoFgC,GAnFhC,2BAmFgC,CAnFJ,CAmFI,CAAA,GAAA;EAAI;;;;EAJ3B,YAAA,CAAA,EAAA,OAAA,GAAA,SAAA;;;;;;;;;;;UA9DO,wBAAA;;;KAIL,0CAA0C,8BAA8B,4BAA4B,KAC/G;KAEW,gBAAA;;KAET,IAAA,IAAQ,aAAa;;;KAIZ,2BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BR,8BACH,2BACC,wBAAwB;KAEd,yBAAA,GAA4B,8BACvC,mCACA;;;;;;KAOW,2BAA2B;+BAGvB,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB,kCACxB,qCAGc,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB"}
+{"version":3,"file":"types.d.mts","names":[],"sources":["../../src/shared/types.ts"],"sourcesContent":[],"mappings":";;;;;;KAKY,eAAe,IAAI,YAAY;UAE1B,2BAAA;EAFL;;;;;EAEK,OAAA,CAAA,EAAA,MAAA,GAAA,SAAA;AASjB;AAOiB,UAPA,uBAAA,CAOkB;EAgBvB;AAEZ;AA6BA;EACmB,WAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;AAIJ,UApDE,kBAAA,CAoDF;EAAO;AAKtB;AAQA;AAEA;;;;;;;;;EAKY,WAAA,CAAA,EAAA,OAAA,GAAA,SAA2B;AAWvC;AAAkD,KAnEtC,gBAAA,GAmEsC,OAAA,GAAA,MAAA;AAA8B,KAjEpE,uBAAA,GAiEoE;EAC/E;;;;;EAmBgB,oBAAA,CAAA,EAAA,OAAwB,GAAA,SAAA,GAAA,SAAA;EAI7B;;;;;;AAGZ;;;;;AAMA;;;;;;;AAmCA;EAAwC,gBAAA,CAAA,EAAA,MAAA,GAAA,SAAA;CACvC;AACA,KA1GW,qBA0GX,CAAA,IAAA,MAAA,CAAA,GAAA;EACA,gBAAA,EA1GkB,CA0GlB;EAAkB;AAOnB;;EAGgB,WAAA,CAAA,EAhHD,OAgHC,CAhHO,eAgHP,CAAA,GAAA,SAAA;CAA4B;AAC/B,KA5GD,sBA4GC,CAAA,IAAA,OAAA,CAAA,GAAA;EAAkB,gBAAA,CAAA,EA3GX,CA2GW,GAAA,SAAA;EAAI;;;EAKjB,WAAA,CAAA,EA5GH,gBA4GG,GAAA,SAAA;CAA4B;AAClB,KA1GhB,gBAAA,GAAmB,UA0GH,CAAA,OA1GqB,UA0GrB,CAAA,CAAA,CAAA,CAAA;AAAb,KAxGH,2BAwGG,CAAA,UAxGmC,gBAwGnC,GAAA,OAAA,CAAA,GAAA,CAxGkE,CAwGlE,SAAA,MAAA,GAvGZ,qBAuGY,CAvGU,CAuGV,CAAA,GAtGZ,sBAsGY,CAtGW,CAsGX,CAAA,CAAA,GArGd,uBAqGc;AAAkB,KAnGrB,2BAAA,GAmGqB;EAAI;;;;;;;;;;KAxFzB,sCAAsC,8BAA8B,8BAC/E,0BACA,4BAA4B,KAC5B;;;;;;;;;;;;;;;;UAiBgB,wBAAA;;;KAIL,0CAA0C,8BAA8B,4BAA4B,KAC/G;KAEW,gBAAA;;KAET,IAAA,IAAQ,aAAa;;;KAIZ,2BAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;IA8BR,8BACH,0BACA,sBACC,wBAAwB;KAEd,yBAAA,GAA4B,8BACvC,mCACA,0BACA;;;;;;KAOW,2BAA2B;+BAGvB,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB,kCACxB,qCAGc,4BAA4B,kDAC/B,aAAa,KAAK,IAAI,OAC1B,mBAAmB"}

package/llms.txt

@@ -0,0 +1,54 @@
+# vitest-plugin-vis
+
+> vitest-plugin-vis: Vitest visual testing plugin. Image snapshot testing for Vitest browser mode, with a Storybook integration.
+
+This file is generated by `packages/storybook-addon-vis/scripts/generate-llms-txt.mjs` from the packages' `exports` maps, their source, and the documentation pages. Do not edit it by hand; run `pnpm docs:llms` instead.
+
+If an image snapshot test fails, read [Reviewing Failures with Agents](https://repobuddy.github.io/visual-testing/?path=/docs/reviewing-failures-with-agents--docs) before opening any image.
+
+Image snapshots are stored in the repository under `__vis__/`. Within it, `__baselines__` holds the expected images, `__results__` holds the images from the latest run, and `__diffs__` holds the diff images of failed comparisons. Next to each diff image, `<name>.review.png` is the review image of the changed regions and `<name>.regions.json` lists those regions.
+
+Import from the entry points listed below, not from package internals. Documentation pages list the names they cover; names without a page have only their type declarations.
+
+## Start here
+
+- [storybook-addon-vis: Reviewing Failures with Agents](https://repobuddy.github.io/visual-testing/?path=/docs/reviewing-failures-with-agents--docs): When an image snapshot fails, a coding agent often opens the baseline and the result and compares them.
+
+## Packages
+
+- [vitest-plugin-vis](https://www.npmjs.com/package/vitest-plugin-vis): Vitest visual testing plugin. Peer dependencies: @vitest/browser ^4, @vitest/browser-playwright ^4 (optional), @vitest/browser-webdriverio ^4 (optional), vitest ^4.
+
+## Documentation
+
+- [vitest-plugin-vis: Overview](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/overview.mdx): vitest-plugin-vis provides visual testing for tests running in Vitest Browser Mode.
+- [vitest-plugin-vis: auto snapshots/setAutoSnapshotOptions](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/auto_snapshots/auto_snapshot_options.mdx): A function to configure visual snapshot testing options for the current test or test suite. Documents: setAutoSnapshotOptions.
+- [vitest-plugin-vis: config](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/config/overview.mdx): Configuration refers to configuring the plugin in your `vitest.config.ts` file.
+- [vitest-plugin-vis: config/trimCommonFolder](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/config/trim_common_folder.mdx): The `trimCommonFolder` function is a utility that removes common folder prefixes from file paths to generate cleaner snapshot sub-paths. Documents: trimCommonFolder.
+- [vitest-plugin-vis: config/vis](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/config/vis.mdx): `vis` from `vitest-plugin-vis/config` is the Vitest plugin of `vitest-plugin-vis`. Documents: vis.
+- [vitest-plugin-vis: expect/toMatchImageSnapshot](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/client/expect/to_match_image_snapshot.mdx): `expect().toMatchImageSnapshot()` is a custom matcher that compares the current DOM to a snapshot image.
+- [vitest-plugin-vis: page/hasImageSnapshot](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/client/page/has_image_snapshot.mdx): `page.hasImageSnapshot()` is a utility method that checks if an image snapshot exists for the current test.
+- [vitest-plugin-vis: page/toMatchImageSnapshot](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/client/page/to_match_image_snapshot.mdx): `page.toMatchImageSnapshot()` is a method that captures and compares full page or viewport screenshots against baseline images.
+- [vitest-plugin-vis: setup](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/setup/overview.mdx): `vitest-plugin-vis/setup` provides the API to setup the plugin on the client side.
+- [vitest-plugin-vis: setup/createVis](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/setup/create_vis.mdx): Import `createVis` from `vitest-plugin-vis/setup-api` (not from `vitest-plugin-vis/setup`). Documents: createVis.
+- [vitest-plugin-vis: setup/vis](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/setup/vis.mdx): `vis` object from `vitest-plugin-vis/setup` provides the API to setup the plugin on the client side. Documents: vis.
+
+## Entry points
+
+- [`vitest-plugin-vis`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/index.ts): function: setAutoSnapshotOptions; types: Awaitable, ComparisonMethod, FailureThresholdOptions, ImageSnapshotCompareOptions, ImageSnapshotComparisonInfo, ImageSnapshotKeyOptions, ImageSnapshotSubjectOptions, ImageSnapshotTimeoutOptions, MatchImageSnapshotOptions, MetaTask, PageImageSnapshotOptions, PixelComparisonOptions, PixelDiffOptions, ReviewImageOptions, SetupVisOptions, SnapshotTestMeta, SsimComparisonOptions, SsimDiffOptions, ToMatchImageSnapshotOptions, ToMatchPageImageSnapshotOptions (21 exports, 1 with a documentation page).
+- [`vitest-plugin-vis/client-api`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/client-api.ts): functions: autoSnapshotMatcher, hasImageSnapshotAction, loadImageSnapshotResultsAction, matchImageSnapshotAction, matchPageImageSnapshotAction, setAutoSnapshotOptions, toTaskId; types: Awaitable, ComparisonMethod, FailureThresholdOptions, ImageSnapshotCompareOptions, ImageSnapshotComparisonInfo, ImageSnapshotKeyOptions, ImageSnapshotMatcher, ImageSnapshotSubjectOptions, ImageSnapshotTimeoutOptions, MatchImageSnapshotOptions, MetaTask, PageImageSnapshotOptions, PixelComparisonOptions, PixelDiffOptions, ReviewImageOptions, SetupVisOptions, SnapshotTestMeta, SsimComparisonOptions, SsimDiffOptions, ToMatchImageSnapshotOptions, ToMatchPageImageSnapshotOptions; values: BASELINE_DIR, CHANGED_REGIONS_SUFFIX, DIFF_DIR, NAME, RESULT_DIR, REVIEW_IMAGE_SUFFIX, SNAPSHOT_ROOT_DIR, success (36 exports, 1 with a documentation page).
+- [`vitest-plugin-vis/config`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/config.ts): functions: trimCommonFolder, vis; types: ComparisonMethod, PixelComparisonOptions, PixelDiffOptions, SsimComparisonOptions, SsimDiffOptions, VisOptions (8 exports, 2 with a documentation page).
+- [`vitest-plugin-vis/presets/auto`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/presets/auto.ts): no named exports; it is imported for its side effects.
+- [`vitest-plugin-vis/presets/manual`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/presets/manual.ts): no named exports; it is imported for its side effects.
+- [`vitest-plugin-vis/server-utils`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/server-utils.ts): functions: getSnapshotRootDir, resolveLegacySnapshotFileRelativePath, resolveSnapshotSubpathWithinLimits, trimCommonFolder; values: BASELINE_DIR, CHANGED_REGIONS_SUFFIX, DIFF_DIR, REVIEW_IMAGE_SUFFIX, SNAPSHOT_ROOT_DIR (9 exports, 1 with a documentation page).
+- [`vitest-plugin-vis/setup`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/setup.ts): value: vis (1 export, 1 with a documentation page).
+- [`vitest-plugin-vis/setup-api`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/setup-api.ts): function: createVis; type: VisClientConfigurator (2 exports, 1 with a documentation page).
+- [`vitest-plugin-vis/testing`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/testing.ts): values: UNI_IMAGE_DATA, UNI_PNG_BASE64, UNI_PNG_URL (3 exports, 0 with a documentation page).
+- [`vitest-plugin-vis/testing/node`](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/exports/testing/node.ts): functions: getVisOption, stubSuite; values: UNI_IMAGE_DATA, UNI_PNG_BASE64, UNI_PNG_URL (5 exports, 0 with a documentation page).
+
+## Optional
+
+- [vitest-plugin-vis: Changelog](https://github.com/repobuddy/visual-testing/blob/main/packages/vitest-plugin-vis/src/changelog.mdx): Release history of vitest-plugin-vis.
+- [Generator](https://github.com/repobuddy/visual-testing/blob/main/packages/storybook-addon-vis/scripts/generate-llms-txt.mjs): Source of this file. Run it with `--gaps` to list the undocumented exports.
+
+Documentation coverage: 5 of 50 distinct exported declarations are named on a documentation page; 8 carry a doc comment.
+12 of the pages above are not published on the documentation site; they link to their source on GitHub.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-plugin-vis",
-  "version": "5.1.8",
+  "version": "5.2.1",
   "description": "Vitest visual testing plugin",
   "keywords": [
     "image-snapshot",
@@ -45,7 +45,14 @@
   "files": [
     "dist",
     "src",
-    "!**/*.{spec,test,unit,accept,integrate,system,perf,stress}.*"
+    "llms.txt",
+    "plugin.json",
+    ".claude-plugin",
+    ".cursor-plugin",
+    ".codex-plugin",
+    "skills",
+    "!**/*.{spec,test,unit,accept,integrate,system,perf,stress}.*",
+    "CHANGELOG.md"
   ],
   "dependencies": {
     "dedent": "^1.7.2",
@@ -57,7 +64,7 @@
     "pngjs": "^7.0.0",
     "rimraf": "^6.1.3",
     "ssim.js": "^3.5.0",
-    "type-plus": "8.0.0"
+    "type-plus": "8.0.1"
   },
   "devDependencies": {
     "@repobuddy/storybook": "^2.33.4",

package/plugin.json

@@ -0,0 +1,24 @@
+{
+	"$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json",
+	"name": "vitest-plugin-vis",
+	"version": "5.1.8",
+	"description": "Review failed image snapshots from vitest-plugin-vis cheaply: read the message, then the review image.",
+	"author": {
+		"name": "Homa Wong",
+		"email": "homawong@gmail.com",
+		"url": "https://github.com/unional"
+	},
+	"homepage": "https://github.com/repobuddy/visual-testing/tree/main/packages/vitest-plugin-vis",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/repobuddy/visual-testing",
+		"directory": "packages/vitest-plugin-vis"
+	},
+	"license": "MIT",
+	"keywords": ["image-snapshot", "vitest", "visual-test"],
+	"extensions": {
+		"org.cyberuni.universal-plugin": {
+			"vendors": ["claude-code", "cursor", "codex", "copilot-cli"]
+		}
+	}
+}

package/skills/review-image-snapshot-failures/README.md

@@ -0,0 +1,18 @@
+# review-image-snapshot-failures
+
+Reviews a failed image snapshot through its review image instead of the full images, which costs far fewer tokens.
+
+## When to use
+
+An agent loads it when a visual test fails with a `Snapshot ... mismatched` error from `toMatchImageSnapshot`, or when it is asked to run visual tests or update image snapshots. It is not a slash command (`user-invocable: false`).
+
+## What it does
+
+1. Reads the error message: pixel count, size change, changed regions, image paths.
+2. Opens the review image, not the full Expected, Actual, or Difference images.
+3. Opens a full image only when the message says the review image was skipped.
+4. Updates a baseline (`-u`) only for an intended change, and reports rendering drift instead.
+
+## Install
+
+It ships as a plugin in both the `vitest-plugin-vis` and `storybook-addon-vis` npm packages (`plugin.json` and `skills/` in the package), identical in each. The measured token costs are on the "Reviewing Failures with Agents" page.

package/skills/review-image-snapshot-failures/SKILL.md

@@ -0,0 +1,37 @@
+---
+name: review-image-snapshot-failures
+user-invocable: false
+description: Reviews a failed image snapshot through its review image instead of the full images, at a fraction of the tokens. Applies when a visual test fails with a `Snapshot ... mismatched` error from toMatchImageSnapshot, or when asked to run visual tests or update image snapshots, even if the request never mentions images.
+---
+
+# Review image snapshot failures
+
+Use the review image of a failed image snapshot before opening any full image.
+
+## Run the tests
+
+Run the project's own test command (for example `vitest run`). Do not pass `-u` to make a failure go away. Updating baselines is step 5 below, and only for an intended change.
+
+Snapshots live under `__vis__/`: `__baselines__` is expected, `__results__` is the latest run, `__diffs__` holds the diff of a failed comparison. Next to each diff, `<name>.review.png` is the review image and `<name>.regions.json` lists the changed regions.
+
+## When a snapshot fails
+
+1. **Read the error message first.** It gives the pixel count, any size change, the changed regions (`Changed:`), and the image paths. It is text and costs little.
+2. **Open the review image** (`Review:`), not the full images. For each region it shows Expected, Actual, and the changed pixels in red, side by side. Open the full Expected, Actual, or Difference image only if the review image leaves the question open.
+3. **If the message says the review image was skipped, read why.**
+   - The image size changed: open only the Actual image. A size change means the layout changed.
+   - Too many regions, or they cover most of the image: open the Difference image. Red pixels changed; yellow pixels are anti-aliasing and do not count. Open Expected and Actual only if the Difference image does not show what changed.
+4. **If there is no `Review:` line**, the review image is turned off (`reviewImage: false`). The `Changed:` line still gives each region. Crop Expected and Actual to those regions with any image tool available, and open the crops.
+5. **Decide what the change is.**
+   - Intended by the task: update the baseline (run the tests with `-u`).
+   - Same content, only the edges of text or shapes differ: rendering drift (fonts, operating system, browser). Report it; do not update the baseline.
+   - Anything else is a regression. Fix it or report it.
+
+Full explanation and measured token costs: the "Reviewing Failures with Agents" page, shipped as `src/reviewing_failures_with_agents.mdx` in `storybook-addon-vis`.
+
+## Validate
+
+- The error message was read before any image was opened.
+- No full Expected, Actual, or Difference image was opened while a `Review:` image existed and answered the question.
+- `-u` was not run unless the change is what the task intended.
+- A change that only differs at the edges of text or shapes was reported as rendering drift, and its baseline is unchanged (`git diff` shows no file under `__baselines__`).

package/src/client/expect/to_match_image_snapshot.mdx

@@ -120,6 +120,39 @@ it('should allow percentage differences', async ({ expect }) => {
 })
 ```
 
+### Review Image
+
+#### `reviewImage`
+
+When a snapshot mismatches, the matcher finds the changed regions and writes two files next to the diff image:
+
+- `<name>.regions.json`: the image size and one box per changed region.
+- `<name>.review.png`: for each region, the baseline, result, and diff crops side by side.
+
+The failure message lists the regions and the review image:
+
+```txt
+Changed:    2 regions: 106x37 at (0,0), 40x20 at (300,512)
+Review:     ./__vis__/local/__diffs__/button.stories.tsx/primary-1.review.png (baseline, result, diff of each region)
+```
+
+Open the review image first: it shows only what changed, at full contrast, and is much smaller than the full images.
+The review image is skipped when cropping does not help:
+the image size changed, there are more than 5 regions, or the regions cover more than half of the image.
+The message then says why, and you open the `Actual` or `Difference` image instead.
+
+Set `reviewImage: false` to not write the review image.
+
+```ts
+it('should not write a review image', async ({ expect }) => {
+	render(<MyComponent />)
+
+	await expect(document.body).toMatchImageSnapshot({
+		reviewImage: false
+	})
+})
+```
+
 ### Comparison Methods
 
 #### `comparisonMethod`

package/src/client/external/browser/image_data.ts

@@ -1,23 +1,24 @@
-export function toImageData(base64: string) {
-	return new Promise<ImageData>((resolve, reject) => {
-		const img = new Image()
-		img.src = `data:image/png;base64,${base64}`
-
-		img.onload = () => {
-			const canvas = document.createElement('canvas')
-			canvas.width = img.width
-			canvas.height = img.height
-			const ctx = canvas.getContext('2d')!
-			ctx.drawImage(img, 0, 0)
-			resolve(ctx.getImageData(0, 0, canvas.width, canvas.height))
-		}
-
-		img.onerror = () => {
-			reject(new Error('Failed to load image'))
-		}
-	})
+export async function toImageData(base64: string) {
+	// `createImageBitmap` + `close()` releases the decoded pixels right away.
+	// `new Image()` + `drawImage` leaves a full-size decode in Chromium's image decode cache.
+	let bitmap: ImageBitmap
+	try {
+		const blob = await (await fetch(`data:image/png;base64,${base64}`)).blob()
+		bitmap = await createImageBitmap(blob)
+	} catch (cause) {
+		throw new Error('Failed to load image', { cause })
+	}
+	try {
+		const canvas = document.createElement('canvas')
+		canvas.width = bitmap.width
+		canvas.height = bitmap.height
+		const ctx = canvas.getContext('2d')!
+		ctx.drawImage(bitmap, 0, 0)
+		return ctx.getImageData(0, 0, canvas.width, canvas.height)
+	} finally {
+		bitmap.close()
+	}
 }
-
 export async function toDataURL(imageData: ImageData) {
 	const canvas = document.createElement('canvas')
 	canvas.width = imageData.width

package/src/client/snapshot/compare_image_snapshot.ts

@@ -1,11 +1,14 @@
 import dedent from 'dedent'
 import { resolve } from 'pathe'
 import type { BrowserCommands } from 'vitest/browser'
+import { findChangedRegions, formatChangedRegions } from '../../shared/changed_regions.ts'
 import type {
 	ImageSnapshotNextIndexCommand,
 	PrepareImageSnapshotComparisonCommand,
 } from '../../shared/commands.types.ts'
-import { compareImage } from '../../shared/compare_image.ts'
+import { compareImage, getChangedMask } from '../../shared/compare_image.ts'
+import { CHANGED_REGIONS_SUFFIX, REVIEW_IMAGE_SUFFIX } from '../../shared/constants.ts'
+import { createReviewImage, getReviewImageSkipReason } from '../../shared/review_image.ts'
 import type { ImageSnapshotComparisonInfo, ToMatchImageSnapshotOptions } from '../../shared/types.ts'
 import { toDataURL, toImageData } from '../external/browser/image_data.ts'
 import { server } from '../external/vitest/vitest_browser_context_proxy.ts'
@@ -68,6 +71,36 @@ export async function compareImageSnapshot(
 
 	await writeSnapshot(commands, resolve(info.projectRoot, info.diffPath), diffImage)
 
+	const mask = getChangedMask(
+		baselineAlignedImage.data,
+		resultAlignedImage.data,
+		diffImage.data,
+		width,
+		height,
+		options as ToMatchImageSnapshotOptions<any>,
+	)
+	const regions = findChangedRegions(mask, width, height)
+	await commands.writeFile(
+		resolve(info.projectRoot, toSiblingPath(info.diffPath, CHANGED_REGIONS_SUFFIX)),
+		JSON.stringify({ width, height, regions }),
+	)
+	let review = ''
+	if (options?.reviewImage !== false) {
+		const skipReason = getReviewImageSkipReason({ baseline: baselineImage, result: resultImage, regions })
+		if (skipReason) {
+			review = `\nReview:     skipped, ${skipReason}; open Actual or Difference instead`
+		} else {
+			const reviewPath = toSiblingPath(info.diffPath, REVIEW_IMAGE_SUFFIX)
+			const reviewImage = createReviewImage(baselineAlignedImage, resultAlignedImage, mask, regions)
+			await writeSnapshot(
+				commands,
+				resolve(info.projectRoot, reviewPath),
+				new ImageData(reviewImage.data, reviewImage.width, reviewImage.height),
+			)
+			review = `\nReview:     ${formatSnapshotPath(info.projectRoot, reviewPath)} (baseline, result, diff of each region)`
+		}
+	}
+
 	throw new Error(
 		dedent`Snapshot \`${taskId}\` mismatched
 
@@ -87,10 +120,15 @@ export async function compareImageSnapshot(
 
 					Expected:   ${formatSnapshotPath(info.projectRoot, info.baselinePath)}
 					Actual:     ${formatSnapshotPath(info.projectRoot, info.resultPath)}
-					Difference: ${formatSnapshotPath(info.projectRoot, info.diffPath)}`,
+					Difference: ${formatSnapshotPath(info.projectRoot, info.diffPath)}
+					Changed:    ${formatChangedRegions(regions)}${review}`,
 	)
 }
 
+function toSiblingPath(diffPath: string, suffix: string) {
+	return diffPath.replace(/\.png$/, suffix)
+}
+
 async function writeSnapshot(commands: BrowserCommands, path: string, image: ImageData) {
 	const content = (await toDataURL(image)).split(',')[1]!
 	return commands.writeFile(path, content, { encoding: 'base64' })

package/src/config/types.ts

@@ -6,6 +6,7 @@ import type {
 	ImageSnapshotTimeoutOptions,
 	PixelComparisonOptions,
 	PixelDiffOptions,
+	ReviewImageOptions,
 	SsimComparisonOptions,
 	SsimDiffOptions,
 } from '../shared/types.ts'
@@ -30,7 +31,8 @@ export type VisOptions<M extends ComparisonMethod = 'pixel'> = (M extends 'ssim'
 	FailureThresholdOptions &
 	ImageSnapshotTimeoutOptions &
 	ImageSnapshotKeyOptions &
-	ImageSnapshotSubjectOptions & {
+	ImageSnapshotSubjectOptions &
+	ReviewImageOptions & {
 		/**
 		 * Loads the `test.setupFiles` of the specified preset.
 		 *

package/src/config/vis.mdx

@@ -278,6 +278,27 @@ export default defineConfig({
 })
 ```
 
+## Review Image
+
+When a snapshot mismatches, `vitest-plugin-vis` writes a review image (`<name>.review.png`) next to the diff image.
+It places the baseline, result, and diff crops of each changed region side by side,
+so you or a coding agent can see what changed without opening the full images.
+The changed regions are also written to `<name>.regions.json`.
+See [`toMatchImageSnapshot()`](?path=/docs/expect-tomatchimagesnapshot--docs) for details.
+
+To not write the review image:
+
+```ts
+// vitest.config.ts
+import { vis } from 'vitest-plugin-vis/config'
+
+export default defineConfig({
+	plugins: [vis({
+		reviewImage: false
+	})],
+})
+```
+
 ## Timeout Configuration
 
 Sometimes your tests need a bit more time to render, especially if you're working with complex components or slower environments. You can adjust the timeout to give your tests the breathing room they need.

package/src/exports/server-utils.ts

@@ -3,5 +3,11 @@ export {
 	resolveLegacySnapshotFileRelativePath,
 	resolveSnapshotSubpathWithinLimits,
 } from '../server/snapshot_path_limits.ts'
-export { BASELINE_DIR, DIFF_DIR, SNAPSHOT_ROOT_DIR } from '../shared/constants.ts'
+export {
+	BASELINE_DIR,
+	CHANGED_REGIONS_SUFFIX,
+	DIFF_DIR,
+	REVIEW_IMAGE_SUFFIX,
+	SNAPSHOT_ROOT_DIR,
+} from '../shared/constants.ts'
 export { trimCommonFolder } from '../shared/trim_common_folder.ts'