vitest-screenshot 1.0.0 → 1.1.0

package/CHANGELOG.md

@@ -1,12 +1,5 @@
-## [vitest-screenshot-v1.0.0](https://github.com/bhouston/vitest-gpu/compare/vitest-screenshot-v0.1.0...vitest-screenshot-v1.0.0) (2026-09-18)
-
-### ⚠ BREAKING CHANGES
-
-* **screenshot:** `threshold` and `maxDiffRatio` are no longer top-level options. Use
-`comparatorOptions: { threshold, allowedMismatchedPixelRatio }` (Vitest's names) instead.
-* **screenshot:** the matcher is async and must be awaited; reference paths need an image extension.
+## [vitest-screenshot-v1.1.0](https://github.com/bhouston/vitest-gpu/compare/vitest-screenshot-v1.0.1...vitest-screenshot-v1.1.0) (2026-09-21)
 
 ### Features
 
-* **screenshot:** accept canvases, images and any image format in toMatchScreenshot ([edaabc4](https://github.com/bhouston/vitest-gpu/commit/edaabc43ac0ab895601565129a8db38121cfa5d3)), closes [#1](https://github.com/bhouston/vitest-gpu/issues/1)
-* **screenshot:** vitest-style comparators with an imagemagick metrics comparator ([fd37a14](https://github.com/bhouston/vitest-gpu/commit/fd37a14651b3281ec3cdeec9cfd8f434a4233570)), closes [#3](https://github.com/bhouston/vitest-gpu/issues/3)
+* **screenshot:** follow snapshot update mode ([1af74a4](https://github.com/bhouston/vitest-gpu/commit/1af74a4a94dec9912d5c5d37169adf3ff1259f73)), closes [#27](https://github.com/bhouston/vitest-gpu/issues/27)

package/README.md

@@ -45,8 +45,12 @@ relative to `baselineDir` unless absolute.
 - 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.
+- Screenshot baselines follow Vitest's snapshot update mode: missing baselines are created locally, fail in CI,
+  and `vitest -u` creates or overwrites them.
+- `UPDATE_SCREENSHOTS=1 vitest` remains an alias for updating all screenshot baselines.
+- Per assertion, `update: true` creates or overwrites a baseline and `update: false` prevents both overwriting and
+  creating one. This explicit option takes precedence over Vitest's mode and `UPDATE_SCREENSHOTS`.
+- `.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.
 
@@ -60,11 +64,12 @@ comparators, go to `extendMatchers()` (the equivalent of `test.browser.expect.to
 extendMatchers({
   comparatorName: 'pixelmatch',
   comparatorOptions: { threshold: 0.2, allowedMismatchedPixelRatio: 0.01 },
-  comparators: { 'my-comparator': (reference, actual, { createDiff, ...options }) => ({ pass, diff, message }) },
 });
 ```
 
-Per-assertion `comparatorOptions` are merged over the global ones when they name the same comparator.
+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)
 
@@ -119,6 +124,37 @@ knot.png: AE 760 (fuzz 0), PAE 0.1569, MAE 0.01042, MSE 0.0007709, RMSE 0.02777,
 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`.
+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.
+
+## Author
+
+Created by [Ben Houston](https://ben3d.ca) and sponsored by [Land of Assets](https://landofassets.com).
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -37,26 +37,34 @@ export type PixelmatchOptions = NonNullable<Parameters<typeof pixelmatch>[5]> &
     /** Number of pixels allowed to differ. With both limits given the stricter wins; with neither, none may differ. */
     allowedMismatchedPixels?: number;
 };
-/** Which comparator judges the images. `pixelmatch` (default) and `metrics` are built in; others come from `extendMatchers({ comparators })`. */
+/** 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 = {
-    comparatorName?: 'pixelmatch';
-    comparatorOptions?: PixelmatchOptions;
-} | {
-    comparatorName: 'metrics';
-    comparatorOptions?: MetricsOptions;
-} | {
-    comparatorName: string;
-    comparatorOptions?: Record<string, unknown>;
+    [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. */
+    /** Override Vitest's snapshot update mode. `true` creates/overwrites; `false` prevents both. */
     update?: boolean;
 };
 /** Defaults for every assertion plus custom comparators, like `test.browser.expect.toMatchScreenshot` in Vitest config. */
 export type ScreenshotConfig = ComparatorSelection & {
-    comparators?: Record<string, Comparator<never>>;
+    comparators?: {
+        [Name in ComparatorName]?: Comparator<ComparatorOptions<Name>>;
+    };
 };
 declare module 'vitest' {
     interface Assertion {

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAEA,OAAO,UAAU,MAAM,YAAY,CAAC;AAGpC,OAAO,EAAqB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEtE,YAAY,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE3D,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;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,SAAS,GACT;IAAE,UAAU,IAAI,OAAO,CAAC,SAAS,CAAC,CAAA;CAAE,GACpC;IAAE,YAAY,IAAI,SAAS,CAAA;CAAE,GAC7B;IAAE,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAA;CAAE,CAAC;AAEhC,qHAAqH;AACrH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,WAAW,CAAC;AAE7C,+GAA+G;AAC/G,MAAM,MAAM,gBAAgB,GAAG;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,CAAC;AAEjG,mFAAmF;AACnF,MAAM,MAAM,UAAU,CAAC,OAAO,SAAS,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,IAAI,CACzE,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,SAAS,EACjB,OAAO,EAAE,OAAO,GAAG;IAAE,UAAU,EAAE,OAAO,CAAA;CAAE,KACvC,gBAAgB,CAAC;AAEtB,uFAAuF;AACvF,MAAM,MAAM,iBAAiB,GAAG,WAAW,CAAC,UAAU,CAAC,OAAO,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG;IAC9E,mDAAmD;IACnD,2BAA2B,CAAC,EAAE,MAAM,CAAC;IACrC,mHAAmH;IACnH,uBAAuB,CAAC,EAAE,MAAM,CAAC;CAClC,CAAC;AAEF,iJAAiJ;AACjJ,MAAM,MAAM,mBAAmB,GAC3B;IAAE,cAAc,CAAC,EAAE,YAAY,CAAC;IAAC,iBAAiB,CAAC,EAAE,iBAAiB,CAAA;CAAE,GACxE;IAAE,cAAc,EAAE,SAAS,CAAC;IAAC,iBAAiB,CAAC,EAAE,cAAc,CAAA;CAAE,GACjE;IAAE,cAAc,EAAE,MAAM,CAAC;IAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE,CAAC;AAE5E,MAAM,MAAM,iBAAiB,GAAG,mBAAmB,GAAG;IACpD,mHAAmH;IACnH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,iFAAiF;IACjF,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,CAAC;AAEF,2HAA2H;AAC3H,MAAM,MAAM,gBAAgB,GAAG,mBAAmB,GAAG;IAAE,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,KAAK,CAAC,CAAC,CAAA;CAAE,CAAC;AAEzG,OAAO,QAAQ,QAAQ,CAAC;IACtB,UAAU,SAAS;QACjB,iBAAiB,CAAC,SAAS,EAAE,SAAS,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACrF;CACF;AA+BD,2FAA2F;AAC3F,eAAO,MAAM,oBAAoB,EAAE,UAAU,CAAC,iBAAiB,CAgB9D,CAAC;AAEF,wBAAgB,cAAc,CAAC,MAAM,GAAE,gBAAqB,GAAG,IAAI,CAiDlE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/index.js

@@ -4,6 +4,7 @@ import pixelmatch from 'pixelmatch';
 import sharp from 'sharp';
 import { expect } from 'vitest';
 import { metricsComparator } from './metrics.js';
+import { resolveScreenshotUpdateState } from './update-policy.js';
 const result = (pass, message) => ({ pass, message: () => message });
 const raw = ({ width, height, data }) => sharp(data, { raw: { width, height, channels: 4 } });
 /** Decodes any format sharp reads (png, jpg, gif, webp, ...) into RGBA8. */
@@ -54,6 +55,8 @@ export function extendMatchers(config = {}) {
     };
     expect.extend({
         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;
@@ -62,13 +65,14 @@ export function extendMatchers(config = {}) {
                 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)) {
+                const exists = existsSync(file);
+                const update = resolveScreenshotUpdateState(this.snapshotState, options.update, Boolean(process.env.UPDATE_SCREENSHOTS), Boolean(process.env.CI));
+                if (update === 'all' || (update === 'new' && !exists)) {
                     await writeImage(file, actual);
                     return result(true, `wrote baseline ${file}`);
                 }
-                if (!existsSync(file))
-                    return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1`);
+                if (!exists)
+                    return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1 or vitest -u`);
                 baseline = await readImage(file);
             }
             else {

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/update-policy.d.ts

@@ -0,0 +1,3 @@
+export type ScreenshotUpdateState = 'all' | 'new' | 'none';
+export declare const resolveScreenshotUpdateState: (snapshotState: unknown, explicitUpdate: boolean | undefined, environmentUpdate: boolean, isCi: boolean) => ScreenshotUpdateState;
+//# sourceMappingURL=update-policy.d.ts.map

package/dist/update-policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-policy.d.ts","sourceRoot":"","sources":["../src/update-policy.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,qBAAqB,GAAG,KAAK,GAAG,KAAK,GAAG,MAAM,CAAC;AAW3D,eAAO,MAAM,4BAA4B,kBACxB,OAAO,kBACN,OAAO,GAAG,SAAS,qBAChB,OAAO,QACpB,OAAO,KACZ,qBAMF,CAAC"}

package/dist/update-policy.js

@@ -0,0 +1,11 @@
+const isUpdateState = (value) => value === 'all' || value === 'new' || value === 'none';
+export const resolveScreenshotUpdateState = (snapshotState, explicitUpdate, environmentUpdate, isCi) => {
+    if (explicitUpdate !== undefined)
+        return explicitUpdate ? 'all' : 'none';
+    if (environmentUpdate)
+        return 'all';
+    const compatible = snapshotState;
+    const state = compatible?.snapshotUpdateState ?? compatible?._updateSnapshot;
+    return isUpdateState(state) ? state : isCi ? 'none' : 'new';
+};
+//# sourceMappingURL=update-policy.js.map

package/dist/update-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"update-policy.js","sourceRoot":"","sources":["../src/update-policy.ts"],"names":[],"mappings":"AAQA,MAAM,aAAa,GAAG,CAAC,KAAc,EAAkC,EAAE,CACvE,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,KAAK,IAAI,KAAK,KAAK,MAAM,CAAC;AAEzD,MAAM,CAAC,MAAM,4BAA4B,GAAG,CAC1C,aAAsB,EACtB,cAAmC,EACnC,iBAA0B,EAC1B,IAAa,EACU,EAAE;IACzB,IAAI,cAAc,KAAK,SAAS;QAAE,OAAO,cAAc,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC;IACzE,IAAI,iBAAiB;QAAE,OAAO,KAAK,CAAC;IACpC,MAAM,UAAU,GAAG,aAAoD,CAAC;IACxE,MAAM,KAAK,GAAG,UAAU,EAAE,mBAAmB,IAAI,UAAU,EAAE,eAAe,CAAC;IAC7E,OAAO,aAAa,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,KAAK,CAAC;AAC9D,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "vitest-screenshot",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "toMatchScreenshot(): pixel-diff a canvas, Image or ImageData against a committed png/jpg/gif/webp baseline in Vitest",
   "keywords": [
     "matcher",
@@ -27,6 +27,8 @@
     "dist/**/*.js.map",
     "dist/**/*.d.ts",
     "dist/**/*.d.ts.map",
+    "src/**/*.ts",
+    "!src/**/*.test.ts",
     "CHANGELOG.md"
   ],
   "type": "module",
@@ -43,7 +45,7 @@
   },
   "scripts": {
     "build": "tsc",
-    "tsc": "tsc"
+    "tsc": "tsc && tsc -p tsconfig.type-tests.json"
   },
   "dependencies": {
     "pixelmatch": "^7.1.0",

package/src/index.ts

@@ -0,0 +1,186 @@
+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';
+import { resolveScreenshotUpdateState } from './update-policy.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;
+  /** Override Vitest's snapshot update mode. `true` creates/overwrites; `false` prevents both. */
+  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 exists = existsSync(file);
+        const update = resolveScreenshotUpdateState(
+          this.snapshotState,
+          options.update,
+          Boolean(process.env.UPDATE_SCREENSHOTS),
+          Boolean(process.env.CI),
+        );
+        if (update === 'all' || (update === 'new' && !exists)) {
+          await writeImage(file, actual);
+          return result(true, `wrote baseline ${file}`);
+        }
+        if (!exists) return result(false, `missing baseline ${file}; run with UPDATE_SCREENSHOTS=1 or vitest -u`);
+        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,
+  };
+};

package/src/update-policy.ts

@@ -0,0 +1,23 @@
+export type ScreenshotUpdateState = 'all' | 'new' | 'none';
+
+type CompatibleSnapshotState = {
+  readonly snapshotUpdateState?: unknown;
+  /** Vitest 3 compatibility; remove when the peer range no longer includes Vitest 3. */
+  readonly _updateSnapshot?: unknown;
+};
+
+const isUpdateState = (value: unknown): value is ScreenshotUpdateState =>
+  value === 'all' || value === 'new' || value === 'none';
+
+export const resolveScreenshotUpdateState = (
+  snapshotState: unknown,
+  explicitUpdate: boolean | undefined,
+  environmentUpdate: boolean,
+  isCi: boolean,
+): ScreenshotUpdateState => {
+  if (explicitUpdate !== undefined) return explicitUpdate ? 'all' : 'none';
+  if (environmentUpdate) return 'all';
+  const compatible = snapshotState as CompatibleSnapshotState | undefined;
+  const state = compatible?.snapshotUpdateState ?? compatible?._updateSnapshot;
+  return isUpdateState(state) ? state : isCi ? 'none' : 'new';
+};