vitest-screenshot 0.1.0 → 1.0.1

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+## [vitest-screenshot-v1.0.1](https://github.com/bhouston/vitest-gpu/compare/vitest-screenshot-v1.0.0...vitest-screenshot-v1.0.1) (2026-09-18)
+
+### Bug Fixes
+
+* **screenshot:** enforce comparator option types ([1af7d9c](https://github.com/bhouston/vitest-gpu/commit/1af7d9cefe5531e0d5ed160455aa02418de39491)), closes [#28](https://github.com/bhouston/vitest-gpu/issues/28)
+* **screenshot:** reject negated assertions ([0753f31](https://github.com/bhouston/vitest-gpu/commit/0753f317972e73d9e50d7e594d1ed22db6359c4a)), closes [#22](https://github.com/bhouston/vitest-gpu/issues/22)
+* ship sources referenced by package maps ([8db482e](https://github.com/bhouston/vitest-gpu/commit/8db482ed56714f375b53d9a30df3f080a86fb81d)), closes [#23](https://github.com/bhouston/vitest-gpu/issues/23)

package/README.md

@@ -1,9 +1,10 @@
 # vitest-screenshot
 
-`expect(image).toMatchScreenshot(name)`: pixel-diff an RGBA image against a PNG baseline committed
-next to your tests. Backend-agnostic: feed it `canvas.getImageData()` from
-[`vitest-environment-webgl-node`](../vitest-environment-webgl-node), a WebGPU texture readback, or
-pixels from a real browser.
+`await expect(image).toMatchScreenshot(reference)`: compare an image against a baseline committed next to your
+tests, with the same options as Vitest browser mode's `toMatchScreenshot`. Backend-agnostic: feed it a canvas from
+[`vitest-environment-webgl-node`](../vitest-environment-webgl-node) or
+[`vitest-environment-webgpu-node`](../vitest-environment-webgpu-node), an `ImageData`, a WebGPU texture
+readback, or pixels from a real browser.
 
 ## Install
 
@@ -17,16 +18,132 @@ pnpm add -D vitest vitest-screenshot
 import { extendMatchers } from 'vitest-screenshot';
 extendMatchers();
 
-it('renders the knot', () => {
+it('renders the knot', async () => {
   renderer.render(scene, camera);
-  expect(canvas.getImageData()).toMatchScreenshot('knot', { maxDiffRatio: 0.01 });
+  await expect(canvas).toMatchScreenshot('knot.png', {
+    comparatorOptions: { allowedMismatchedPixelRatio: 0.01 },
+  });
 });
 ```
 
-- Baselines live in `__screenshots__/<name>.png` beside the test file (override with `baselineDir`).
+The matcher is async: always `await` it.
+
+### What you can compare
+
+The received value and the reference can each be any of:
+
+- `{ width, height, data }` with RGBA8 pixels, top row first (an `ImageData`, `canvas.getImageData()`, a WebGPU readback).
+- A canvas: node-webgl's `Canvas` (read with `getImageData()`) or the WebGPU environment's `HeadlessCanvas` (read with `readPixels()`).
+- An `Image` from `vitest-environment-webgl-node` (decoded with `decode()` first).
+
+The reference may also be a file path. It must include the extension (`'knot.png'`, not `'knot'`), and resolves
+relative to `baselineDir` unless absolute.
+
+### Baseline files
+
+- Baselines live in `__screenshots__/` beside the test file (override with `baselineDir`).
+- Any format sharp reads and writes works: png, jpg, gif, webp, avif, tiff. **We recommend png**: it is lossless,
+  so a baseline written on the first run matches exactly. jpg and webp are re-encoded lossily on write and gif is
+  limited to 256 colours, so loosen the comparator if you use them.
 - A missing baseline is written on first run, except when `CI` is set, where it fails.
 - `UPDATE_SCREENSHOTS=1 vitest` (or `update: true`) rewrites baselines.
-- On failure `<name>.actual.png` and `<name>.diff.png` are written beside the baseline. Gitignore them.
-- `threshold` is pixelmatch's per-pixel colour tolerance (default 0.1); `maxDiffRatio` is the fraction
-  of pixels allowed to differ (default 0.001). GPUs and drivers rasterize slightly differently, so loosen
-  `maxDiffRatio` for baselines shared across platforms.
+- `.not.toMatchScreenshot()` is unsupported and fails without reading pixels or writing baseline files.
+- On failure `<name>.actual.png` and `<name>.diff.png` are written to `baselineDir` (named after the test when the
+  reference is in memory). Gitignore them.
+
+## Comparators
+
+As in [Vitest browser mode](https://vitest.dev/guide/browser/visual-regression-testing), `comparatorName` picks
+how the two images are judged and `comparatorOptions` configures it. Defaults for every assertion, and custom
+comparators, go to `extendMatchers()` (the equivalent of `test.browser.expect.toMatchScreenshot` in Vitest config):
+
+```ts
+extendMatchers({
+  comparatorName: 'pixelmatch',
+  comparatorOptions: { threshold: 0.2, allowedMismatchedPixelRatio: 0.01 },
+});
+```
+
+Per-assertion `comparatorOptions` are merged over the global ones when they name the same comparator. When an
+assertion omits `comparatorName`, its options may match any registered comparator because the global default selects
+their meaning at runtime. Supplying `comparatorName` checks the options strictly against that comparator.
+
+### `pixelmatch` (default)
+
+Vitest's built-in comparison: counts pixels whose perceptual colour distance exceeds `threshold`.
+
+| Option                                                                   | Default             | Meaning                                                          |
+| ------------------------------------------------------------------------ | ------------------- | ---------------------------------------------------------------- |
+| `threshold`                                                              | `0.1`               | Per-pixel colour distance (0..1) tolerated; smaller is stricter. |
+| `allowedMismatchedPixelRatio`                                            |                     | Fraction (0..1) of pixels allowed to differ.                     |
+| `allowedMismatchedPixels`                                                |                     | Number of pixels allowed to differ.                              |
+| `includeAA`, `alpha`, `aaColor`, `diffColor`, `diffColorAlt`, `diffMask` | pixelmatch defaults | Forwarded to [pixelmatch](https://github.com/mapbox/pixelmatch). |
+
+With both limits given the stricter wins; with neither, no pixel may differ. GPUs and drivers rasterize edges
+slightly differently, so set a ratio for baselines shared across machines.
+
+### `metrics`
+
+Whole-image error bounds with the names and semantics of ImageMagick's `compare -metric`. Give any subset; the
+assertion passes only if every bound holds. With none given it requires an exact match (`AE: 0`), like
+`compare -metric AE`.
+
+| Option  | Bound | Unit   | Meaning                                                                                                            |
+| ------- | ----- | ------ | ------------------------------------------------------------------------------------------------------------------ |
+| `fuzz`  |       | 0..1   | `-fuzz`: colour distance within which two pixels count as equal (default 0). Only affects `AE` and the diff image. |
+| `AE`    | max   | pixels | Absolute error: pixels differing by more than `fuzz`.                                                              |
+| `PAE`   | max   | 0..1   | Peak absolute error: the largest channel difference anywhere.                                                      |
+| `MAE`   | max   | 0..1   | Mean absolute error.                                                                                               |
+| `MSE`   | max   | 0..1   | Mean squared error.                                                                                                |
+| `RMSE`  | max   | 0..1   | Root mean squared error.                                                                                           |
+| `PSNR`  | min   | dB     | Peak signal-to-noise ratio; `Infinity` for identical images. 30–50 dB is typical for "same picture".               |
+| `SSIM`  | min   | 0..1   | Structural similarity (Gaussian 11×11 window, σ 1.5, over RGB); 1 is identical.                                    |
+| `DSSIM` | max   | 0..1   | Structural dissimilarity, `(1 − SSIM) / 2`.                                                                        |
+
+```ts
+await expect(canvas).toMatchScreenshot('knot.png', {
+  comparatorName: 'metrics',
+  comparatorOptions: { fuzz: 0.05, AE: 50, PSNR: 40 }, // few pixels off by >5%, and low overall error
+});
+```
+
+`AE`, `PAE`, `MAE`, `MSE`, `RMSE` and `PSNR` are computed as ImageMagick does for images with an alpha channel
+(colours alpha-premultiplied, all four channels averaged) and agree with `magick compare` to the printed digits.
+`SSIM` is the textbook definition over RGB, the value `magick compare -metric SSIM` on an opaque image reports
+as `(1 − SSIM) / 2`. The failure message lists every computed metric so you can pick a bound from a real run:
+
+```
+knot.png: AE 760 (fuzz 0), PAE 0.1569, MAE 0.01042, MSE 0.0007709, RMSE 0.02777, PSNR 31.13; failed: AE 760 > 0; see __screenshots__/knot.diff.png
+```
+
+### Custom comparators
+
+A comparator has Vitest's signature: `(reference, actual, options) => { pass, diff, message }`, where `reference`
+and `actual` are `{ width, height, data }`, `options` carries `comparatorOptions` plus `createDiff`, and `diff`
+(an RGBA image or `null`) is written as `<name>.diff.png` on failure. Register it under `comparators` and select
+it with `comparatorName`. Add its option type to `ComparatorRegistry` so registration and assertions check the
+custom name and options:
+
+```ts
+import { type Comparator, extendMatchers } from 'vitest-screenshot';
+
+declare module 'vitest-screenshot' {
+  interface ComparatorRegistry {
+    'red-channel': { tolerance?: number };
+  }
+}
+
+const redChannel: Comparator<{ tolerance?: number }> = (reference, actual, { tolerance = 0 }) => {
+  const difference = Math.abs(reference.data[0]! - actual.data[0]!);
+  return { pass: difference <= tolerance, diff: null, message: `red channel differs by ${difference}` };
+};
+
+extendMatchers({ comparators: { 'red-channel': redChannel } });
+
+await expect(image).toMatchScreenshot('baseline.png', {
+  comparatorName: 'red-channel',
+  comparatorOptions: { tolerance: 2 },
+});
+```
+
+See [`demo/test/screenshots`](../../demo/test/screenshots) for every source, format and comparator combination.

package/dist/index.d.ts

@@ -1,23 +1,77 @@
+import pixelmatch from 'pixelmatch';
+import { type MetricsOptions } from './metrics.js';
+export type { Metric, MetricsOptions } from './metrics.js';
 /** Anything with RGBA8 pixels, top row first: `ImageData`, node-webgl's `canvas.getImageData()`, or a WebGPU readback. */
 export type RgbaImage = {
     width: number;
     height: number;
     data: Uint8Array | Uint8ClampedArray;
 };
-export type ScreenshotOptions = {
-    /** Directory holding baseline PNGs. Default: `__screenshots__` beside the test file. */
+/**
+ * A source of pixels: an `RgbaImage` / `ImageData`, a WebGPU `HeadlessCanvas` (`readPixels()`), a node-webgl
+ * `Canvas` (`getImageData()`), or a node-webgl `Image` (decoded with `decode()`).
+ */
+export type ImageSource = RgbaImage | {
+    readPixels(): Promise<RgbaImage>;
+} | {
+    getImageData(): RgbaImage;
+} | {
+    decode(): Promise<void>;
+};
+/** A baseline: a file path with extension (relative to `baselineDir` or absolute), or an in-memory `ImageSource`. */
+export type Reference = string | ImageSource;
+/** What a comparator returns, as in Vitest browser mode: `diff` is written next to the baseline on failure. */
+export type ComparatorResult = {
+    pass: boolean;
+    diff: RgbaImage | null;
+    message: string | null;
+};
+/** A comparator, with the signature Vitest browser mode uses for `comparators`. */
+export type Comparator<Options extends object = Record<string, unknown>> = (reference: RgbaImage, actual: RgbaImage, options: Options & {
+    createDiff: boolean;
+}) => ComparatorResult;
+/** Options of the default `pixelmatch` comparator, named as in Vitest browser mode. */
+export type PixelmatchOptions = NonNullable<Parameters<typeof pixelmatch>[5]> & {
+    /** Fraction (0..1) of pixels allowed to differ. */
+    allowedMismatchedPixelRatio?: number;
+    /** Number of pixels allowed to differ. With both limits given the stricter wins; with neither, none may differ. */
+    allowedMismatchedPixels?: number;
+};
+/** Comparator names and their options. Augment this interface when registering a custom comparator. */
+export interface ComparatorRegistry {
+    pixelmatch: PixelmatchOptions;
+    metrics: MetricsOptions;
+}
+type ComparatorName = Extract<keyof ComparatorRegistry, string>;
+type ComparatorOptions<Name extends ComparatorName> = Extract<ComparatorRegistry[Name], object>;
+/** Which registered comparator judges the images. `pixelmatch` is the default. */
+export type ComparatorSelection = {
+    [Name in ComparatorName]: {
+        comparatorName: Name;
+        comparatorOptions?: ComparatorOptions<Name>;
+    };
+}[ComparatorName] | {
+    comparatorName?: undefined;
+    comparatorOptions?: ComparatorOptions<ComparatorName>;
+};
+export type ScreenshotOptions = ComparatorSelection & {
+    /** Directory relative reference paths and diff images live in. Default: `__screenshots__` beside the test file. */
     baselineDir?: string;
-    /** Per-pixel colour distance (0..1) tolerated by pixelmatch. Default 0.1. */
-    threshold?: number;
-    /** Fraction (0..1) of pixels allowed to differ. Default 0.001. */
-    maxDiffRatio?: number;
-    /** Overwrite the baseline. Default: `UPDATE_SCREENSHOTS` env var is set. */
+    /** Overwrite the baseline file. Default: `UPDATE_SCREENSHOTS` env var is set. */
     update?: boolean;
 };
+/** Defaults for every assertion plus custom comparators, like `test.browser.expect.toMatchScreenshot` in Vitest config. */
+export type ScreenshotConfig = ComparatorSelection & {
+    comparators?: {
+        [Name in ComparatorName]?: Comparator<ComparatorOptions<Name>>;
+    };
+};
 declare module 'vitest' {
     interface Assertion {
-        toMatchScreenshot(name: string, options?: ScreenshotOptions): void;
+        toMatchScreenshot(reference: Reference, options?: ScreenshotOptions): Promise<void>;
     }
 }
-export declare function extendMatchers(): void;
+/** `comparatorName: 'pixelmatch'` (default): Vitest browser mode's built-in comparison. */
+export declare const pixelmatchComparator: Comparator<PixelmatchOptions>;
+export declare function extendMatchers(config?: ScreenshotConfig): void;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,0HAA0H;AAC1H,MAAM,MAAM,SAAS,GAAG;IAAE,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,UAAU,GAAG,iBAAiB,CAAA;CAAE,CAAC;AAEhG,MAAM,MAAM,iBAAiB,GAAG;IAC9B,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,6EAA6E;IAC7E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kEAAkE;IAClE,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,OAAO,QAAQ,QAAQ,CAAC;IACtB,UAAU,SAAS;QACjB,iBAAiB,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;KACpE;CACF;AAUD,wBAAgB,cAAc,IAAI,IAAI,CAoCrC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -1,43 +1,100 @@
-import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
-import { basename, dirname, join } from 'node:path';
+import { existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join } from 'node:path';
 import pixelmatch from 'pixelmatch';
-import { PNG } from 'pngjs';
+import sharp from 'sharp';
 import { expect } from 'vitest';
+import { metricsComparator } from './metrics.js';
 const result = (pass, message) => ({ pass, message: () => message });
-const toPng = ({ width, height, data }) => {
-    const png = new PNG({ width, height });
-    png.data = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
-    return png;
+const raw = ({ width, height, data }) => sharp(data, { raw: { width, height, channels: 4 } });
+/** Decodes any format sharp reads (png, jpg, gif, webp, ...) into RGBA8. */
+const readImage = async (file) => {
+    const { data, info } = await sharp(file).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+    return { width: info.width, height: info.height, data };
 };
-export function extendMatchers() {
+/** Encodes by file extension; lossy formats (jpg, webp) alter pixels on write. */
+const writeImage = (file, image) => {
+    mkdirSync(dirname(file), { recursive: true });
+    return raw(image)
+        .toFormat(extname(file).slice(1))
+        .toFile(file);
+};
+const toRgba = async (source) => {
+    if ('data' in source)
+        return source;
+    if ('readPixels' in source)
+        return source.readPixels();
+    if ('getImageData' in source)
+        return source.getImageData();
+    await source.decode();
+    // node-webgl's Image and ImageBitmap expose decoded pixels this way (it is what their own texImage2D uses).
+    const rgba = source._toRGBA8?.();
+    if (!rgba)
+        throw new Error('unsupported image source: expected RGBA data, readPixels(), getImageData() or an Image');
+    return rgba;
+};
+/** `comparatorName: 'pixelmatch'` (default): Vitest browser mode's built-in comparison. */
+export const pixelmatchComparator = (reference, actual, { createDiff, allowedMismatchedPixelRatio, allowedMismatchedPixels, ...pixelmatchOptions }) => {
+    const { width, height } = actual;
+    const total = width * height;
+    const diff = createDiff ? new Uint8Array(total * 4) : undefined;
+    const count = pixelmatch(reference.data, actual.data, diff, width, height, pixelmatchOptions);
+    const limits = [allowedMismatchedPixels, allowedMismatchedPixelRatio && allowedMismatchedPixelRatio * total];
+    const allowed = limits.some((l) => l !== undefined) ? Math.min(...limits.filter((l) => l !== undefined)) : 0;
+    return {
+        pass: count <= allowed,
+        diff: diff ? { width, height, data: diff } : null,
+        message: `${count} pixels (${((count / total) * 100).toFixed(3)}%) differ, ${Math.floor(allowed)} allowed`,
+    };
+};
+export function extendMatchers(config = {}) {
+    const comparators = {
+        pixelmatch: pixelmatchComparator,
+        metrics: metricsComparator,
+        ...config.comparators,
+    };
     expect.extend({
-        toMatchScreenshot(received, name, options = {}) {
-            const dir = options.baselineDir ?? join(dirname(this.testPath ?? ''), '__screenshots__');
-            const file = join(dir, `${name}.png`);
-            const actual = toPng(received);
-            const update = options.update ?? Boolean(process.env.UPDATE_SCREENSHOTS);
-            if (update || (!existsSync(file) && !process.env.CI)) {
-                mkdirSync(dir, { recursive: true });
-                writeFileSync(file, PNG.sync.write(actual));
-                return result(true, `wrote baseline ${file}`);
+        async toMatchScreenshot(received, reference, options = {}) {
+            if (this.isNot)
+                throw new Error('`.not.toMatchScreenshot()` is not supported');
+            const dir = options.baselineDir ?? join(dirname(this.testPath), '__screenshots__');
+            const actual = await toRgba(received);
+            let file;
+            let baseline;
+            if (typeof reference === 'string') {
+                if (!extname(reference))
+                    throw new Error(`reference "${reference}" needs an image extension, e.g. "${reference}.png"`);
+                file = isAbsolute(reference) ? reference : join(dir, reference);
+                const update = options.update ?? Boolean(process.env.UPDATE_SCREENSHOTS);
+                if (update || (!existsSync(file) && !process.env.CI)) {
+                    await writeImage(file, actual);
+                    return result(true, `wrote baseline ${file}`);
+                }
+                if (!existsSync(file))
+                    return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1`);
+                baseline = await readImage(file);
             }
-            if (!existsSync(file))
-                return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1`);
-            const baseline = PNG.sync.read(readFileSync(file));
+            else {
+                baseline = await toRgba(reference);
+            }
+            const label = file ? basename(file) : this.currentTestName;
             if (baseline.width !== actual.width || baseline.height !== actual.height) {
-                return result(false, `size mismatch: baseline ${baseline.width}x${baseline.height}, actual ${actual.width}x${actual.height}`);
+                return result(false, `${label}: size mismatch: baseline ${baseline.width}x${baseline.height}, actual ${actual.width}x${actual.height}`);
             }
-            const diff = new PNG({ width: actual.width, height: actual.height });
-            const count = pixelmatch(baseline.data, actual.data, diff.data, actual.width, actual.height, {
-                threshold: options.threshold ?? 0.1,
+            const name = options.comparatorName ?? config.comparatorName ?? 'pixelmatch';
+            const comparator = comparators[name];
+            if (!comparator)
+                throw new Error(`unknown comparator "${name}"; known: ${Object.keys(comparators).join(', ')}`);
+            const inherited = name === (config.comparatorName ?? 'pixelmatch') ? config.comparatorOptions : undefined;
+            const { pass, diff, message } = comparator(baseline, actual, {
+                ...inherited,
+                ...options.comparatorOptions,
+                createDiff: true,
             });
-            const ratio = count / (actual.width * actual.height);
-            const pass = ratio <= (options.maxDiffRatio ?? 0.001);
-            if (!pass) {
-                writeFileSync(join(dir, `${name}.actual.png`), PNG.sync.write(actual));
-                writeFileSync(join(dir, `${name}.diff.png`), PNG.sync.write(diff));
-            }
-            return result(pass, `${basename(file)}: ${count} pixels (${(ratio * 100).toFixed(3)}%) differ; see ${name}.diff.png`);
+            const stem = join(dir, file ? basename(file, extname(file)) : label.replace(/[^\w-]+/g, '_'));
+            const seeDiff = !pass && diff ? `; see ${stem}.diff.png` : '';
+            if (!pass)
+                await Promise.all([writeImage(`${stem}.actual.png`, actual), diff && writeImage(`${stem}.diff.png`, diff)]);
+            return result(pass, `${label}: ${message ?? (pass ? 'matches' : 'differs')}${seeDiff}`);
         },
     });
 }

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/metrics.d.ts

@@ -0,0 +1,44 @@
+import type { Comparator, RgbaImage } from './index.js';
+/** ImageMagick `compare -metric` names. Upper bounds: AE PAE MAE MSE RMSE DSSIM. Lower bounds: PSNR SSIM. */
+export type Metric = 'AE' | 'PAE' | 'MAE' | 'MSE' | 'RMSE' | 'PSNR' | 'SSIM' | 'DSSIM';
+export type MetricsOptions = {
+    /** ImageMagick `-fuzz`: per-channel RMS colour distance (0..1) within which two pixels count as equal. Default 0. */
+    fuzz?: number;
+    /** Absolute error: pixels differing by more than `fuzz`. Default bound when no metric is given: 0. */
+    AE?: number;
+    /** Peak absolute error, 0..1. */
+    PAE?: number;
+    /** Mean absolute error, 0..1. */
+    MAE?: number;
+    /** Mean squared error, 0..1. */
+    MSE?: number;
+    /** Root mean squared error, 0..1. */
+    RMSE?: number;
+    /** Peak signal-to-noise ratio in dB (lower bound). `Infinity` for identical images. */
+    PSNR?: number;
+    /** Structural similarity, 1 = identical (lower bound). Gaussian 11x11 window, sigma 1.5, over RGB. */
+    SSIM?: number;
+    /** Structural dissimilarity, `(1 - SSIM) / 2`. */
+    DSSIM?: number;
+};
+/**
+ * AE, PAE, MAE, MSE, RMSE and PSNR in one pass, matching `magick compare` for RGBA images: colour channels are
+ * alpha-premultiplied and all four channels are averaged. Also returns which pixels differ by more than `fuzz`.
+ */
+export declare function distortion(a: RgbaImage, b: RgbaImage, fuzz: number): {
+    AE: number;
+    PAE: number;
+    MAE: number;
+    MSE: number;
+    RMSE: number;
+    PSNR: number;
+    mask: Uint8Array<ArrayBuffer>;
+};
+/** Mean SSIM over RGB (K1 0.01, K2 0.03), the textbook definition also used by ssim.js and Playwright. */
+export declare function ssim(a: RgbaImage, b: RgbaImage): number;
+/**
+ * `comparatorName: 'metrics'`: ImageMagick `compare -metric` bounds. Give any subset; all must pass. With no
+ * bound given, requires `AE: 0` (an exact match, like `compare -metric AE`).
+ */
+export declare const metricsComparator: Comparator<MetricsOptions>;
+//# sourceMappingURL=metrics.d.ts.map

package/dist/metrics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.d.ts","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAExD,6GAA6G;AAC7G,MAAM,MAAM,MAAM,GAAG,IAAI,GAAG,KAAK,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEvF,MAAM,MAAM,cAAc,GAAG;IAC3B,qHAAqH;IACrH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,iCAAiC;IACjC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,gCAAgC;IAChC,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,qCAAqC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,sGAAsG;IACtG,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kDAAkD;IAClD,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAqBF;;;GAGG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM;;;;;;;;EAgClE;AA+BD,0GAA0G;AAC1G,wBAAgB,IAAI,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,MAAM,CAmBvD;AAkBD;;;GAGG;AACH,eAAO,MAAM,iBAAiB,EAAE,UAAU,CAAC,cAAc,CAgCxD,CAAC"}

package/dist/metrics.js

@@ -0,0 +1,150 @@
+const LOWER_IS_WORSE = new Set(['PSNR', 'SSIM']);
+const METRICS = new Set(['AE', 'PAE', 'MAE', 'MSE', 'RMSE', 'PSNR', 'SSIM', 'DSSIM']);
+/**
+ * ImageMagick's IsFuzzyEquivalencePixel: alpha must be within `fuzz`, then the colour distance, scaled by both
+ * alphas (a 4D cone: transparent pixels always match), must be within `fuzz` per channel RMS.
+ */
+const fuzzyEqual = (a, b, i, fuzz2) => {
+    const sa = a[i + 3] / 255;
+    const sb = b[i + 3] / 255;
+    const dAlpha = (sa - sb) ** 2;
+    if (dAlpha > fuzz2)
+        return false;
+    const scale = sa * sb;
+    if (scale <= Number.EPSILON)
+        return true;
+    let d = 3 * dAlpha;
+    for (let c = 0; c < 3; c++)
+        d += scale * ((a[i + c] - b[i + c]) / 255) ** 2;
+    return d <= 3 * fuzz2;
+};
+/**
+ * AE, PAE, MAE, MSE, RMSE and PSNR in one pass, matching `magick compare` for RGBA images: colour channels are
+ * alpha-premultiplied and all four channels are averaged. Also returns which pixels differ by more than `fuzz`.
+ */
+export function distortion(a, b, fuzz) {
+    const n = a.width * a.height;
+    const mask = new Uint8Array(n);
+    const fuzz2 = fuzz * fuzz;
+    let AE = 0;
+    let PAE = 0;
+    let sumAbs = 0;
+    let sumSq = 0;
+    for (let p = 0, i = 0; p < n; p++, i += 4) {
+        if (!fuzzyEqual(a.data, b.data, i, fuzz2)) {
+            mask[p] = 1;
+            AE++;
+        }
+        const sa = a.data[i + 3] / 255;
+        const sb = b.data[i + 3] / 255;
+        for (let c = 0; c < 4; c++) {
+            const d = c === 3 ? Math.abs(sa - sb) : Math.abs((a.data[i + c] / 255) * sa - (b.data[i + c] / 255) * sb);
+            if (d > PAE)
+                PAE = d;
+            sumAbs += d;
+            sumSq += d * d;
+        }
+    }
+    const MSE = sumSq / (n * 4);
+    return {
+        AE,
+        PAE,
+        MAE: sumAbs / (n * 4),
+        MSE,
+        RMSE: Math.sqrt(MSE),
+        PSNR: MSE > 0 ? 10 * Math.log10(1 / MSE) : Infinity,
+        mask,
+    };
+}
+/** Gaussian taps for an 11x11 window with sigma 1.5, normalised to sum 1 (Wang et al. 2004). */
+const KERNEL = (() => {
+    const k = Float64Array.from({ length: 11 }, (_, i) => Math.exp(-((i - 5) ** 2) / (2 * 1.5 * 1.5)));
+    const sum = k.reduce((s, v) => s + v, 0);
+    return k.map((v) => v / sum);
+})();
+/** Separable Gaussian blur of a 3-channel float image, clamping to edge pixels. */
+const blur = (src, width, height) => {
+    const pass = (input, dx, dy) => {
+        const out = new Float32Array(input.length);
+        for (let y = 0; y < height; y++)
+            for (let x = 0; x < width; x++)
+                for (let c = 0; c < 3; c++) {
+                    let s = 0;
+                    for (let k = -5; k <= 5; k++) {
+                        const sx = Math.min(width - 1, Math.max(0, x + k * dx));
+                        const sy = Math.min(height - 1, Math.max(0, y + k * dy));
+                        s += KERNEL[k + 5] * input[(sy * width + sx) * 3 + c];
+                    }
+                    out[(y * width + x) * 3 + c] = s;
+                }
+        return out;
+    };
+    return pass(pass(src, 1, 0), 0, 1);
+};
+const mul = (x, y) => x.map((v, i) => v * y[i]);
+/** Mean SSIM over RGB (K1 0.01, K2 0.03), the textbook definition also used by ssim.js and Playwright. */
+export function ssim(a, b) {
+    const { width, height } = a;
+    const rgb = (img) => Float32Array.from({ length: width * height * 3 }, (_, i) => img.data[i + Math.floor(i / 3)] / 255);
+    const fa = rgb(a);
+    const fb = rgb(b);
+    const [ma, mb, maa, mbb, mab] = [fa, fb, mul(fa, fa), mul(fb, fb), mul(fa, fb)].map((img) => blur(img, width, height));
+    const c1 = 0.01 ** 2;
+    const c2 = 0.03 ** 2;
+    let sum = 0;
+    for (let i = 0; i < fa.length; i++) {
+        const va = maa[i] - ma[i] ** 2;
+        const vb = mbb[i] - mb[i] ** 2;
+        const cov = mab[i] - ma[i] * mb[i];
+        sum += ((2 * ma[i] * mb[i] + c1) * (2 * cov + c2)) / ((ma[i] ** 2 + mb[i] ** 2 + c1) * (va + vb + c2));
+    }
+    return sum / fa.length;
+}
+/** Diff image in pixelmatch's style: the actual image faded towards white, differing pixels in red. */
+const diffImage = (actual, mask) => {
+    const data = new Uint8Array(actual.data.length);
+    for (let p = 0, i = 0; p < mask.length; p++, i += 4) {
+        if (mask[p])
+            data.set([255, 0, 0, 255], i);
+        else {
+            const grey = 255 - 0.1 * (255 - (0.299 * actual.data[i] + 0.587 * actual.data[i + 1] + 0.114 * actual.data[i + 2]));
+            data.set([grey, grey, grey, 255], i);
+        }
+    }
+    return { width: actual.width, height: actual.height, data };
+};
+const fmt = (n) => (Number.isFinite(n) ? String(Number(n.toPrecision(4))) : String(n));
+/**
+ * `comparatorName: 'metrics'`: ImageMagick `compare -metric` bounds. Give any subset; all must pass. With no
+ * bound given, requires `AE: 0` (an exact match, like `compare -metric AE`).
+ */
+export const metricsComparator = (reference, actual, { createDiff, fuzz = 0, ...bounds }) => {
+    for (const key of Object.keys(bounds)) {
+        if (!METRICS.has(key))
+            throw new Error(`unknown metric "${key}"; expected one of ${[...METRICS].join(', ')}`);
+    }
+    const wanted = Object.keys(bounds).filter((k) => bounds[k] !== undefined);
+    if (wanted.length === 0) {
+        bounds.AE = 0;
+        wanted.push('AE');
+    }
+    const values = distortion(reference, actual, fuzz);
+    if (wanted.includes('SSIM') || wanted.includes('DSSIM')) {
+        values.SSIM = ssim(reference, actual);
+        values.DSSIM = (1 - values.SSIM) / 2;
+    }
+    const failed = wanted.filter((k) => (LOWER_IS_WORSE.has(k) ? values[k] < bounds[k] : values[k] > bounds[k]));
+    const report = [...METRICS]
+        .filter((k) => values[k] !== undefined)
+        .map((k) => `${k} ${fmt(values[k])}${k === 'AE' ? ` (fuzz ${fmt(fuzz)})` : ''}`)
+        .join(', ');
+    const why = failed
+        .map((k) => `${k} ${fmt(values[k])} ${LOWER_IS_WORSE.has(k) ? '<' : '>'} ${fmt(bounds[k])}`)
+        .join(', ');
+    return {
+        pass: failed.length === 0,
+        diff: createDiff ? diffImage(actual, values.mask) : null,
+        message: failed.length ? `${report}; failed: ${why}` : report,
+    };
+};
+//# sourceMappingURL=metrics.js.map

package/dist/metrics.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"metrics.js","sourceRoot":"","sources":["../src/metrics.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vitest-screenshot",
-  "version": "0.1.0",
-  "description": "toMatchScreenshot(): pixel-diff an RGBA image against a committed PNG baseline in Vitest",
+  "version": "1.0.1",
+  "description": "toMatchScreenshot(): pixel-diff a canvas, Image or ImageData against a committed png/jpg/gif/webp baseline in Vitest",
   "keywords": [
     "matcher",
     "pixelmatch",
@@ -27,6 +27,8 @@
     "dist/**/*.js.map",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
     "CHANGELOG.md"
   ],
   "type": "module",
@@ -42,15 +44,12 @@
     "access": "public"
   },
   "scripts": {
-    "build": "tsc -b",
-    "tsc": "tsc -b"
+    "build": "tsc",
+    "tsc": "tsc && tsc -p tsconfig.type-tests.json"
   },
   "dependencies": {
     "pixelmatch": "^7.1.0",
-    "pngjs": "^7.0.0"
-  },
-  "devDependencies": {
-    "@types/pngjs": "^6.0.5"
+    "sharp": "^0.35.4"
   },
   "peerDependencies": {
     "vitest": ">=3 <5"

package/src/index.ts

@@ -0,0 +1,179 @@
+import { existsSync, mkdirSync } from 'node:fs';
+import { basename, dirname, extname, isAbsolute, join } from 'node:path';
+import pixelmatch from 'pixelmatch';
+import sharp, { type FormatEnum } from 'sharp';
+import { expect } from 'vitest';
+import { metricsComparator, type MetricsOptions } from './metrics.js';
+
+export type { Metric, MetricsOptions } from './metrics.js';
+
+/** Anything with RGBA8 pixels, top row first: `ImageData`, node-webgl's `canvas.getImageData()`, or a WebGPU readback. */
+export type RgbaImage = { width: number; height: number; data: Uint8Array | Uint8ClampedArray };
+
+/**
+ * A source of pixels: an `RgbaImage` / `ImageData`, a WebGPU `HeadlessCanvas` (`readPixels()`), a node-webgl
+ * `Canvas` (`getImageData()`), or a node-webgl `Image` (decoded with `decode()`).
+ */
+export type ImageSource =
+  | RgbaImage
+  | { readPixels(): Promise<RgbaImage> }
+  | { getImageData(): RgbaImage }
+  | { decode(): Promise<void> };
+
+/** A baseline: a file path with extension (relative to `baselineDir` or absolute), or an in-memory `ImageSource`. */
+export type Reference = string | ImageSource;
+
+/** What a comparator returns, as in Vitest browser mode: `diff` is written next to the baseline on failure. */
+export type ComparatorResult = { pass: boolean; diff: RgbaImage | null; message: string | null };
+
+/** A comparator, with the signature Vitest browser mode uses for `comparators`. */
+export type Comparator<Options extends object = Record<string, unknown>> = (
+  reference: RgbaImage,
+  actual: RgbaImage,
+  options: Options & { createDiff: boolean },
+) => ComparatorResult;
+
+/** Options of the default `pixelmatch` comparator, named as in Vitest browser mode. */
+export type PixelmatchOptions = NonNullable<Parameters<typeof pixelmatch>[5]> & {
+  /** Fraction (0..1) of pixels allowed to differ. */
+  allowedMismatchedPixelRatio?: number;
+  /** Number of pixels allowed to differ. With both limits given the stricter wins; with neither, none may differ. */
+  allowedMismatchedPixels?: number;
+};
+
+/** Comparator names and their options. Augment this interface when registering a custom comparator. */
+export interface ComparatorRegistry {
+  pixelmatch: PixelmatchOptions;
+  metrics: MetricsOptions;
+}
+
+type ComparatorName = Extract<keyof ComparatorRegistry, string>;
+type ComparatorOptions<Name extends ComparatorName> = Extract<ComparatorRegistry[Name], object>;
+
+/** Which registered comparator judges the images. `pixelmatch` is the default. */
+export type ComparatorSelection =
+  | {
+      [Name in ComparatorName]: {
+        comparatorName: Name;
+        comparatorOptions?: ComparatorOptions<Name>;
+      };
+    }[ComparatorName]
+  | { comparatorName?: undefined; comparatorOptions?: ComparatorOptions<ComparatorName> };
+
+export type ScreenshotOptions = ComparatorSelection & {
+  /** Directory relative reference paths and diff images live in. Default: `__screenshots__` beside the test file. */
+  baselineDir?: string;
+  /** Overwrite the baseline file. Default: `UPDATE_SCREENSHOTS` env var is set. */
+  update?: boolean;
+};
+
+/** Defaults for every assertion plus custom comparators, like `test.browser.expect.toMatchScreenshot` in Vitest config. */
+export type ScreenshotConfig = ComparatorSelection & {
+  comparators?: { [Name in ComparatorName]?: Comparator<ComparatorOptions<Name>> };
+};
+
+declare module 'vitest' {
+  interface Assertion {
+    toMatchScreenshot(reference: Reference, options?: ScreenshotOptions): Promise<void>;
+  }
+}
+
+const result = (pass: boolean, message: string) => ({ pass, message: () => message });
+
+const raw = ({ width, height, data }: RgbaImage) => sharp(data, { raw: { width, height, channels: 4 } });
+
+/** Decodes any format sharp reads (png, jpg, gif, webp, ...) into RGBA8. */
+const readImage = async (file: string): Promise<RgbaImage> => {
+  const { data, info } = await sharp(file).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+  return { width: info.width, height: info.height, data };
+};
+
+/** Encodes by file extension; lossy formats (jpg, webp) alter pixels on write. */
+const writeImage = (file: string, image: RgbaImage) => {
+  mkdirSync(dirname(file), { recursive: true });
+  return raw(image)
+    .toFormat(extname(file).slice(1) as keyof FormatEnum)
+    .toFile(file);
+};
+
+const toRgba = async (source: ImageSource): Promise<RgbaImage> => {
+  if ('data' in source) return source;
+  if ('readPixels' in source) return source.readPixels();
+  if ('getImageData' in source) return source.getImageData();
+  await source.decode();
+  // node-webgl's Image and ImageBitmap expose decoded pixels this way (it is what their own texImage2D uses).
+  const rgba = (source as { _toRGBA8?: () => RgbaImage })._toRGBA8?.();
+  if (!rgba) throw new Error('unsupported image source: expected RGBA data, readPixels(), getImageData() or an Image');
+  return rgba;
+};
+
+/** `comparatorName: 'pixelmatch'` (default): Vitest browser mode's built-in comparison. */
+export const pixelmatchComparator: Comparator<PixelmatchOptions> = (
+  reference,
+  actual,
+  { createDiff, allowedMismatchedPixelRatio, allowedMismatchedPixels, ...pixelmatchOptions },
+) => {
+  const { width, height } = actual;
+  const total = width * height;
+  const diff = createDiff ? new Uint8Array(total * 4) : undefined;
+  const count = pixelmatch(reference.data, actual.data, diff, width, height, pixelmatchOptions);
+  const limits = [allowedMismatchedPixels, allowedMismatchedPixelRatio && allowedMismatchedPixelRatio * total];
+  const allowed = limits.some((l) => l !== undefined) ? Math.min(...limits.filter((l) => l !== undefined)) : 0;
+  return {
+    pass: count <= allowed,
+    diff: diff ? { width, height, data: diff } : null,
+    message: `${count} pixels (${((count / total) * 100).toFixed(3)}%) differ, ${Math.floor(allowed)} allowed`,
+  };
+};
+
+export function extendMatchers(config: ScreenshotConfig = {}): void {
+  const comparators = {
+    pixelmatch: pixelmatchComparator,
+    metrics: metricsComparator,
+    ...config.comparators,
+  } as unknown as Record<string, Comparator>;
+  expect.extend({
+    async toMatchScreenshot(received: ImageSource, reference: Reference, options: ScreenshotOptions = {}) {
+      if (this.isNot) throw new Error('`.not.toMatchScreenshot()` is not supported');
+      const dir = options.baselineDir ?? join(dirname(this.testPath!), '__screenshots__');
+      const actual = await toRgba(received);
+      let file: string | undefined;
+      let baseline: RgbaImage;
+      if (typeof reference === 'string') {
+        if (!extname(reference))
+          throw new Error(`reference "${reference}" needs an image extension, e.g. "${reference}.png"`);
+        file = isAbsolute(reference) ? reference : join(dir, reference);
+        const update = options.update ?? Boolean(process.env.UPDATE_SCREENSHOTS);
+        if (update || (!existsSync(file) && !process.env.CI)) {
+          await writeImage(file, actual);
+          return result(true, `wrote baseline ${file}`);
+        }
+        if (!existsSync(file)) return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1`);
+        baseline = await readImage(file);
+      } else {
+        baseline = await toRgba(reference);
+      }
+      const label = file ? basename(file) : this.currentTestName!;
+      if (baseline.width !== actual.width || baseline.height !== actual.height) {
+        return result(
+          false,
+          `${label}: size mismatch: baseline ${baseline.width}x${baseline.height}, actual ${actual.width}x${actual.height}`,
+        );
+      }
+      const name = options.comparatorName ?? config.comparatorName ?? 'pixelmatch';
+      const comparator = comparators[name];
+      if (!comparator) throw new Error(`unknown comparator "${name}"; known: ${Object.keys(comparators).join(', ')}`);
+      const inherited = name === (config.comparatorName ?? 'pixelmatch') ? config.comparatorOptions : undefined;
+      const { pass, diff, message } = comparator(baseline, actual, {
+        ...inherited,
+        ...options.comparatorOptions,
+        createDiff: true,
+      });
+      const stem = join(dir, file ? basename(file, extname(file)) : label.replace(/[^\w-]+/g, '_'));
+      const seeDiff = !pass && diff ? `; see ${stem}.diff.png` : '';
+      if (!pass)
+        await Promise.all([writeImage(`${stem}.actual.png`, actual), diff && writeImage(`${stem}.diff.png`, diff)]);
+      return result(pass, `${label}: ${message ?? (pass ? 'matches' : 'differs')}${seeDiff}`);
+    },
+  });
+}

package/src/metrics.ts

@@ -0,0 +1,187 @@
+import type { Comparator, RgbaImage } from './index.js';
+
+/** ImageMagick `compare -metric` names. Upper bounds: AE PAE MAE MSE RMSE DSSIM. Lower bounds: PSNR SSIM. */
+export type Metric = 'AE' | 'PAE' | 'MAE' | 'MSE' | 'RMSE' | 'PSNR' | 'SSIM' | 'DSSIM';
+
+export type MetricsOptions = {
+  /** ImageMagick `-fuzz`: per-channel RMS colour distance (0..1) within which two pixels count as equal. Default 0. */
+  fuzz?: number;
+  /** Absolute error: pixels differing by more than `fuzz`. Default bound when no metric is given: 0. */
+  AE?: number;
+  /** Peak absolute error, 0..1. */
+  PAE?: number;
+  /** Mean absolute error, 0..1. */
+  MAE?: number;
+  /** Mean squared error, 0..1. */
+  MSE?: number;
+  /** Root mean squared error, 0..1. */
+  RMSE?: number;
+  /** Peak signal-to-noise ratio in dB (lower bound). `Infinity` for identical images. */
+  PSNR?: number;
+  /** Structural similarity, 1 = identical (lower bound). Gaussian 11x11 window, sigma 1.5, over RGB. */
+  SSIM?: number;
+  /** Structural dissimilarity, `(1 - SSIM) / 2`. */
+  DSSIM?: number;
+};
+
+const LOWER_IS_WORSE = new Set<Metric>(['PSNR', 'SSIM']);
+const METRICS = new Set<Metric>(['AE', 'PAE', 'MAE', 'MSE', 'RMSE', 'PSNR', 'SSIM', 'DSSIM']);
+
+/**
+ * ImageMagick's IsFuzzyEquivalencePixel: alpha must be within `fuzz`, then the colour distance, scaled by both
+ * alphas (a 4D cone: transparent pixels always match), must be within `fuzz` per channel RMS.
+ */
+const fuzzyEqual = (a: RgbaImage['data'], b: RgbaImage['data'], i: number, fuzz2: number) => {
+  const sa = a[i + 3]! / 255;
+  const sb = b[i + 3]! / 255;
+  const dAlpha = (sa - sb) ** 2;
+  if (dAlpha > fuzz2) return false;
+  const scale = sa * sb;
+  if (scale <= Number.EPSILON) return true;
+  let d = 3 * dAlpha;
+  for (let c = 0; c < 3; c++) d += scale * ((a[i + c]! - b[i + c]!) / 255) ** 2;
+  return d <= 3 * fuzz2;
+};
+
+/**
+ * AE, PAE, MAE, MSE, RMSE and PSNR in one pass, matching `magick compare` for RGBA images: colour channels are
+ * alpha-premultiplied and all four channels are averaged. Also returns which pixels differ by more than `fuzz`.
+ */
+export function distortion(a: RgbaImage, b: RgbaImage, fuzz: number) {
+  const n = a.width * a.height;
+  const mask = new Uint8Array(n);
+  const fuzz2 = fuzz * fuzz;
+  let AE = 0;
+  let PAE = 0;
+  let sumAbs = 0;
+  let sumSq = 0;
+  for (let p = 0, i = 0; p < n; p++, i += 4) {
+    if (!fuzzyEqual(a.data, b.data, i, fuzz2)) {
+      mask[p] = 1;
+      AE++;
+    }
+    const sa = a.data[i + 3]! / 255;
+    const sb = b.data[i + 3]! / 255;
+    for (let c = 0; c < 4; c++) {
+      const d = c === 3 ? Math.abs(sa - sb) : Math.abs((a.data[i + c]! / 255) * sa - (b.data[i + c]! / 255) * sb);
+      if (d > PAE) PAE = d;
+      sumAbs += d;
+      sumSq += d * d;
+    }
+  }
+  const MSE = sumSq / (n * 4);
+  return {
+    AE,
+    PAE,
+    MAE: sumAbs / (n * 4),
+    MSE,
+    RMSE: Math.sqrt(MSE),
+    PSNR: MSE > 0 ? 10 * Math.log10(1 / MSE) : Infinity,
+    mask,
+  };
+}
+
+/** Gaussian taps for an 11x11 window with sigma 1.5, normalised to sum 1 (Wang et al. 2004). */
+const KERNEL = (() => {
+  const k = Float64Array.from({ length: 11 }, (_, i) => Math.exp(-((i - 5) ** 2) / (2 * 1.5 * 1.5)));
+  const sum = k.reduce((s, v) => s + v, 0);
+  return k.map((v) => v / sum);
+})();
+
+/** Separable Gaussian blur of a 3-channel float image, clamping to edge pixels. */
+const blur = (src: Float32Array, width: number, height: number) => {
+  const pass = (input: Float32Array, dx: number, dy: number) => {
+    const out = new Float32Array(input.length);
+    for (let y = 0; y < height; y++)
+      for (let x = 0; x < width; x++)
+        for (let c = 0; c < 3; c++) {
+          let s = 0;
+          for (let k = -5; k <= 5; k++) {
+            const sx = Math.min(width - 1, Math.max(0, x + k * dx));
+            const sy = Math.min(height - 1, Math.max(0, y + k * dy));
+            s += KERNEL[k + 5]! * input[(sy * width + sx) * 3 + c]!;
+          }
+          out[(y * width + x) * 3 + c] = s;
+        }
+    return out;
+  };
+  return pass(pass(src, 1, 0), 0, 1);
+};
+
+const mul = (x: Float32Array, y: Float32Array) => x.map((v, i) => v * y[i]!);
+
+/** Mean SSIM over RGB (K1 0.01, K2 0.03), the textbook definition also used by ssim.js and Playwright. */
+export function ssim(a: RgbaImage, b: RgbaImage): number {
+  const { width, height } = a;
+  const rgb = (img: RgbaImage) =>
+    Float32Array.from({ length: width * height * 3 }, (_, i) => img.data[i + Math.floor(i / 3)]! / 255);
+  const fa = rgb(a);
+  const fb = rgb(b);
+  const [ma, mb, maa, mbb, mab] = [fa, fb, mul(fa, fa), mul(fb, fb), mul(fa, fb)].map((img) =>
+    blur(img, width, height),
+  ) as Float32Array[];
+  const c1 = 0.01 ** 2;
+  const c2 = 0.03 ** 2;
+  let sum = 0;
+  for (let i = 0; i < fa.length; i++) {
+    const va = maa![i]! - ma![i]! ** 2;
+    const vb = mbb![i]! - mb![i]! ** 2;
+    const cov = mab![i]! - ma![i]! * mb![i]!;
+    sum += ((2 * ma![i]! * mb![i]! + c1) * (2 * cov + c2)) / ((ma![i]! ** 2 + mb![i]! ** 2 + c1) * (va + vb + c2));
+  }
+  return sum / fa.length;
+}
+
+/** Diff image in pixelmatch's style: the actual image faded towards white, differing pixels in red. */
+const diffImage = (actual: RgbaImage, mask: Uint8Array): RgbaImage => {
+  const data = new Uint8Array(actual.data.length);
+  for (let p = 0, i = 0; p < mask.length; p++, i += 4) {
+    if (mask[p]) data.set([255, 0, 0, 255], i);
+    else {
+      const grey =
+        255 - 0.1 * (255 - (0.299 * actual.data[i]! + 0.587 * actual.data[i + 1]! + 0.114 * actual.data[i + 2]!));
+      data.set([grey, grey, grey, 255], i);
+    }
+  }
+  return { width: actual.width, height: actual.height, data };
+};
+
+const fmt = (n: number) => (Number.isFinite(n) ? String(Number(n.toPrecision(4))) : String(n));
+
+/**
+ * `comparatorName: 'metrics'`: ImageMagick `compare -metric` bounds. Give any subset; all must pass. With no
+ * bound given, requires `AE: 0` (an exact match, like `compare -metric AE`).
+ */
+export const metricsComparator: Comparator<MetricsOptions> = (
+  reference,
+  actual,
+  { createDiff, fuzz = 0, ...bounds },
+) => {
+  for (const key of Object.keys(bounds)) {
+    if (!METRICS.has(key as Metric))
+      throw new Error(`unknown metric "${key}"; expected one of ${[...METRICS].join(', ')}`);
+  }
+  const wanted = (Object.keys(bounds) as Metric[]).filter((k) => bounds[k] !== undefined);
+  if (wanted.length === 0) {
+    bounds.AE = 0;
+    wanted.push('AE');
+  }
+  const values: Partial<Record<Metric, number>> & ReturnType<typeof distortion> = distortion(reference, actual, fuzz);
+  if (wanted.includes('SSIM') || wanted.includes('DSSIM')) {
+    values.SSIM = ssim(reference, actual);
+    values.DSSIM = (1 - values.SSIM) / 2;
+  }
+  const failed = wanted.filter((k) => (LOWER_IS_WORSE.has(k) ? values[k]! < bounds[k]! : values[k]! > bounds[k]!));
+  const report = [...METRICS]
+    .filter((k) => values[k] !== undefined)
+    .map((k) => `${k} ${fmt(values[k]!)}${k === 'AE' ? ` (fuzz ${fmt(fuzz)})` : ''}`)
+    .join(', ');
+  const why = failed
+    .map((k) => `${k} ${fmt(values[k]!)} ${LOWER_IS_WORSE.has(k) ? '<' : '>'} ${fmt(bounds[k]!)}`)
+    .join(', ');
+  return {
+    pass: failed.length === 0,
+    diff: createDiff ? diffImage(actual, values.mask) : null,
+    message: failed.length ? `${report}; failed: ${why}` : report,
+  };
+};