@storyshelf/image 0.0.0-stage → 0.6.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Siddhant Gupta
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,46 @@
-# Temporary Holding Version
+# @storyshelf/image
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+StoryShelf's image engine: pixel diffing (pixelmatch), diff overlay rendering and thumbnails, run on a
+worker-thread pool.
+
+## Engines
+
+The comparison is always pixelmatch; the **engine** is the PNG codec around it.
+
+| Engine            | Install         | Notes                                              |
+| ----------------- | --------------- | -------------------------------------------------- |
+| `pngjs` (default) | built in        | Pure JavaScript, runs anywhere.                    |
+| `sharp`           | `nub add sharp` | Native (libvips); several times faster on big PNGs |
+
+## Usage
+
+Most users never import this package; set the engine on `createShelfApp`:
+
+```ts
+createShelfApp({ ..., testing: { runner, images: { engine: "sharp" } } });
+```
+
+or set `STORYSHELF_IMAGE_ENGINE=sharp`. The option wins over the variable.
+
+## API
+
+```ts
+import {
+  diffImages, // (baseline, current, options, codec?) -> Promise<DiffResult>
+  diffImagesAsync, // same, on the shared worker-thread pool
+  downscalePng, // (png, maxEdge) -> Promise<Uint8Array>, on the configured engine
+  configureImages, // ({ engine?, threads? }) apply testing.images.engine and testing.compare.threads
+  verifyImageEngine, // load the configured engine now; rejects when it cannot load
+  shutdownDiffPool, // stop the pool's workers
+  DEFAULT_DIFF_OPTIONS,
+  type DiffOptions,
+  type DiffResult,
+  type ImageEngine,
+} from "@storyshelf/image";
+```
+
+`configureImages` is process-wide. The option beats `STORYSHELF_IMAGE_ENGINE`, and an unknown engine name throws.
+
+## License
+
+MIT

package/dist/async.d.mts

@@ -0,0 +1,30 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DiffOptions, DiffResult } from "./options.mjs";
+import { ImageSettings } from "./settings.mjs";
+//#region src/async.d.ts
+/** Environment variable overriding the pool size; `0` runs diffs in-thread. */
+declare const DIFF_WORKERS_ENV = "STORYSHELF_DIFF_WORKERS";
+/**
+ * Apply `images.engine` and `compare.threads`; both beat their environment variables
+ * (`STORYSHELF_IMAGE_ENGINE`, `STORYSHELF_DIFF_WORKERS`). A running pool whose engine or size no
+ * longer matches is shut down and rebuilt on next use.
+ */
+declare function configureImages(settings: ImageSettings): void;
+/**
+ * Diff two PNGs without blocking the event loop; same result as `diffImages`.
+ *
+ * Runs on a shared `worker_threads` pool (`max(1, availableParallelism() - 1)` threads, or
+ * `STORYSHELF_DIFF_WORKERS`; `0` means in-thread) and falls back to the in-thread path when
+ * threads are unavailable. The buffers may be transferred to a worker, which detaches them in
+ * the caller: do not read them afterwards.
+ *
+ * The pool is process-scoped, not owned by the capture consumer, so the re-diff route benefits
+ * even on an instance that never renders.
+ */
+declare function diffImagesAsync(baseline: Buffer, current: Buffer, options: DiffOptions): Promise<DiffResult>;
+/** Stop the shared pool's workers. A later `diffImagesAsync` starts a fresh pool. */
+declare function shutdownDiffPool(): Promise<void>;
+//#endregion
+export { DIFF_WORKERS_ENV, configureImages, diffImagesAsync, shutdownDiffPool };
+//# sourceMappingURL=async.d.mts.map

package/dist/async.mjs

@@ -0,0 +1,64 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { DiffPool } from "./pool.mjs";
+import { appliedImageSettings, configuredThreadCount, currentImageEngine, setImageSettings } from "./settings.mjs";
+import { availableParallelism } from "node:os";
+//#region src/async.ts
+/** `diffImagesAsync`: `diffImages` on a lazily created, process-wide worker pool, plus `configureImages`. */
+/** Environment variable overriding the pool size; `0` runs diffs in-thread. */
+const DIFF_WORKERS_ENV = "STORYSHELF_DIFF_WORKERS";
+let pool;
+/**
+* Apply `images.engine` and `compare.threads`; both beat their environment variables
+* (`STORYSHELF_IMAGE_ENGINE`, `STORYSHELF_DIFF_WORKERS`). A running pool whose engine or size no
+* longer matches is shut down and rebuilt on next use.
+*/
+function configureImages(settings) {
+	const before = appliedImageSettings();
+	setImageSettings(settings);
+	const after = appliedImageSettings();
+	if (before.engine === after.engine && before.threads === after.threads) return;
+	const stale = pool;
+	pool = void 0;
+	stale?.shutdown().catch(() => {});
+}
+/**
+* Diff two PNGs without blocking the event loop; same result as `diffImages`.
+*
+* Runs on a shared `worker_threads` pool (`max(1, availableParallelism() - 1)` threads, or
+* `STORYSHELF_DIFF_WORKERS`; `0` means in-thread) and falls back to the in-thread path when
+* threads are unavailable. The buffers may be transferred to a worker, which detaches them in
+* the caller: do not read them afterwards.
+*
+* The pool is process-scoped, not owned by the capture consumer, so the re-diff route benefits
+* even on an instance that never renders.
+*/
+async function diffImagesAsync(baseline, current, options) {
+	pool ??= new DiffPool({
+		size: configuredThreadCount() ?? resolveDiffWorkers(process.env),
+		workerUrl: defaultWorkerUrl(),
+		engine: currentImageEngine()
+	});
+	return await pool.run(baseline, current, options);
+}
+/** Stop the shared pool's workers. A later `diffImagesAsync` starts a fresh pool. */
+async function shutdownDiffPool() {
+	const current = pool;
+	pool = void 0;
+	await current?.shutdown();
+}
+/** Pool size from the environment: a non-negative integer, else one fewer than the CPU count (min 1). */
+function resolveDiffWorkers(env, parallelism = availableParallelism()) {
+	const raw = env[DIFF_WORKERS_ENV]?.trim();
+	if (raw && /^\d+$/u.test(raw)) return Number(raw);
+	return Math.max(1, parallelism - 1);
+}
+/** `worker.mjs` beside the built output; `worker.ts` when running from source (tests, `nub run serve`). */
+function defaultWorkerUrl() {
+	return import.meta.url.endsWith(".ts") ? new URL("worker.ts", import.meta.url) : new URL("worker.mjs", import.meta.url);
+}
+//#endregion
+export { DIFF_WORKERS_ENV, configureImages, diffImagesAsync, resolveDiffWorkers, shutdownDiffPool };
+
+//# sourceMappingURL=async.mjs.map

package/dist/async.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"async.mjs","names":[],"sources":["../src/async.ts"],"sourcesContent":["/** `diffImagesAsync`: `diffImages` on a lazily created, process-wide worker pool, plus `configureImages`. */\nimport { availableParallelism } from \"node:os\";\nimport type { DiffOptions, DiffResult } from \"./options.ts\";\nimport { DiffPool } from \"./pool.ts\";\nimport {\n  appliedImageSettings,\n  configuredThreadCount,\n  currentImageEngine,\n  type ImageSettings,\n  setImageSettings,\n} from \"./settings.ts\";\n\n/** Environment variable overriding the pool size; `0` runs diffs in-thread. */\nexport const DIFF_WORKERS_ENV = \"STORYSHELF_DIFF_WORKERS\";\n\nlet pool: DiffPool | undefined;\n\n/**\n * Apply `images.engine` and `compare.threads`; both beat their environment variables\n * (`STORYSHELF_IMAGE_ENGINE`, `STORYSHELF_DIFF_WORKERS`). A running pool whose engine or size no\n * longer matches is shut down and rebuilt on next use.\n */\nexport function configureImages(settings: ImageSettings): void {\n  const before = appliedImageSettings();\n  setImageSettings(settings);\n  const after = appliedImageSettings();\n  if (before.engine === after.engine && before.threads === after.threads) {\n    return;\n  }\n  const stale = pool;\n  pool = undefined;\n  stale?.shutdown().catch(() => {});\n}\n\n/**\n * Diff two PNGs without blocking the event loop; same result as `diffImages`.\n *\n * Runs on a shared `worker_threads` pool (`max(1, availableParallelism() - 1)` threads, or\n * `STORYSHELF_DIFF_WORKERS`; `0` means in-thread) and falls back to the in-thread path when\n * threads are unavailable. The buffers may be transferred to a worker, which detaches them in\n * the caller: do not read them afterwards.\n *\n * The pool is process-scoped, not owned by the capture consumer, so the re-diff route benefits\n * even on an instance that never renders.\n */\nexport async function diffImagesAsync(\n  baseline: Buffer,\n  current: Buffer,\n  options: DiffOptions,\n): Promise<DiffResult> {\n  pool ??= new DiffPool({\n    size: configuredThreadCount() ?? resolveDiffWorkers(process.env),\n    workerUrl: defaultWorkerUrl(),\n    engine: currentImageEngine(),\n  });\n  return await pool.run(baseline, current, options);\n}\n\n/** Stop the shared pool's workers. A later `diffImagesAsync` starts a fresh pool. */\nexport async function shutdownDiffPool(): Promise<void> {\n  const current = pool;\n  pool = undefined;\n  await current?.shutdown();\n}\n\n/** Pool size from the environment: a non-negative integer, else one fewer than the CPU count (min 1). */\nexport function resolveDiffWorkers(\n  env: Record<string, string | undefined>,\n  parallelism: number = availableParallelism(),\n): number {\n  const raw = env[DIFF_WORKERS_ENV]?.trim();\n  if (raw && /^\\d+$/u.test(raw)) {\n    return Number(raw);\n  }\n  return Math.max(1, parallelism - 1);\n}\n\n/** `worker.mjs` beside the built output; `worker.ts` when running from source (tests, `nub run serve`). */\nfunction defaultWorkerUrl(): URL {\n  return import.meta.url.endsWith(\".ts\")\n    ? new URL(\"worker.ts\", import.meta.url)\n    : new URL(\"worker.mjs\", import.meta.url);\n}\n"],"mappings":";;;;;;;;;AAaA,MAAa,mBAAmB;AAEhC,IAAI;;;;;;AAOJ,SAAgB,gBAAgB,UAA+B;CAC7D,MAAM,SAAS,qBAAqB;CACpC,iBAAiB,QAAQ;CACzB,MAAM,QAAQ,qBAAqB;CACnC,IAAI,OAAO,WAAW,MAAM,UAAU,OAAO,YAAY,MAAM,SAC7D;CAEF,MAAM,QAAQ;CACd,OAAO,KAAA;CACP,OAAO,SAAS,CAAC,CAAC,YAAY,CAAC,CAAC;AAClC;;;;;;;;;;;;AAaA,eAAsB,gBACpB,UACA,SACA,SACqB;CACrB,SAAS,IAAI,SAAS;EACpB,MAAM,sBAAsB,KAAK,mBAAmB,QAAQ,GAAG;EAC/D,WAAW,iBAAiB;EAC5B,QAAQ,mBAAmB;CAC7B,CAAC;CACD,OAAO,MAAM,KAAK,IAAI,UAAU,SAAS,OAAO;AAClD;;AAGA,eAAsB,mBAAkC;CACtD,MAAM,UAAU;CAChB,OAAO,KAAA;CACP,MAAM,SAAS,SAAS;AAC1B;;AAGA,SAAgB,mBACd,KACA,cAAsB,qBAAqB,GACnC;CACR,MAAM,MAAM,IAAI,iBAAiB,EAAE,KAAK;CACxC,IAAI,OAAO,SAAS,KAAK,GAAG,GAC1B,OAAO,OAAO,GAAG;CAEnB,OAAO,KAAK,IAAI,GAAG,cAAc,CAAC;AACpC;;AAGA,SAAS,mBAAwB;CAC/B,OAAO,YAAY,IAAI,SAAS,KAAK,IACjC,IAAI,IAAI,aAAa,YAAY,GAAG,IACpC,IAAI,IAAI,cAAc,YAAY,GAAG;AAC3C"}

package/dist/codec.d.mts

@@ -0,0 +1,38 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/codec.d.ts
+/** Image codecs: how PNGs become raw RGBA pixels and back. The comparison itself is always pixelmatch. */
+/** Engine names accepted by `images.engine` and `STORYSHELF_IMAGE_ENGINE`. */
+declare const IMAGE_ENGINES: readonly ["pngjs", "sharp"];
+/** A codec that can decode, encode and downscale PNGs. */
+type ImageEngine = (typeof IMAGE_ENGINES)[number];
+/** Environment variable that selects the engine when `images.engine` is not set. */
+declare const IMAGE_ENGINE_ENV = "STORYSHELF_IMAGE_ENGINE";
+/** The engine used when nothing is configured: pure JavaScript, runs anywhere. */
+declare const DEFAULT_IMAGE_ENGINE: ImageEngine;
+/** Raw 8-bit RGBA pixels, row-major, `width * height * 4` bytes. */
+interface RgbaImage {
+  width: number;
+  height: number;
+  data: Uint8Array;
+}
+/** Everything the engine needs from an image library. */
+interface ImageCodec {
+  readonly name: ImageEngine;
+  /** Decode a PNG to RGBA. */
+  decode(png: Buffer): Promise<RgbaImage> | RgbaImage;
+  /** Encode RGBA pixels as a PNG. */
+  encode(image: RgbaImage): Promise<Buffer> | Buffer;
+  /** Downscale a PNG so its long edge is at most `maxEdge`; output stays PNG. */
+  downscale(png: Uint8Array, maxEdge: number): Promise<Uint8Array> | Uint8Array;
+}
+/** Narrow an arbitrary string to a known engine name. */
+declare function isImageEngine(value: unknown): value is ImageEngine;
+/**
+ * The engine named by a raw setting (an option or the `STORYSHELF_IMAGE_ENGINE` value); blank or
+ * missing means the default. An unknown name throws so a typo cannot silently fall back.
+ */
+declare function resolveImageEngine(raw: string | undefined): ImageEngine;
+//#endregion
+export { DEFAULT_IMAGE_ENGINE, IMAGE_ENGINES, IMAGE_ENGINE_ENV, ImageCodec, ImageEngine, RgbaImage, isImageEngine, resolveImageEngine };
+//# sourceMappingURL=codec.d.mts.map

package/dist/codec.mjs

@@ -0,0 +1,29 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/codec.ts
+/** Image codecs: how PNGs become raw RGBA pixels and back. The comparison itself is always pixelmatch. */
+/** Engine names accepted by `images.engine` and `STORYSHELF_IMAGE_ENGINE`. */
+const IMAGE_ENGINES = ["pngjs", "sharp"];
+/** Environment variable that selects the engine when `images.engine` is not set. */
+const IMAGE_ENGINE_ENV = "STORYSHELF_IMAGE_ENGINE";
+/** The engine used when nothing is configured: pure JavaScript, runs anywhere. */
+const DEFAULT_IMAGE_ENGINE = "pngjs";
+/** Narrow an arbitrary string to a known engine name. */
+function isImageEngine(value) {
+	return IMAGE_ENGINES.some((engine) => engine === value);
+}
+/**
+* The engine named by a raw setting (an option or the `STORYSHELF_IMAGE_ENGINE` value); blank or
+* missing means the default. An unknown name throws so a typo cannot silently fall back.
+*/
+function resolveImageEngine(raw) {
+	const value = raw?.trim();
+	if (value === void 0 || value === "") return DEFAULT_IMAGE_ENGINE;
+	if (!isImageEngine(value)) throw new Error(`Unknown image engine "${value}". Use one of: ${IMAGE_ENGINES.join(", ")}.`);
+	return value;
+}
+//#endregion
+export { DEFAULT_IMAGE_ENGINE, IMAGE_ENGINES, IMAGE_ENGINE_ENV, isImageEngine, resolveImageEngine };
+
+//# sourceMappingURL=codec.mjs.map

package/dist/codec.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.mjs","names":[],"sources":["../src/codec.ts"],"sourcesContent":["/** Image codecs: how PNGs become raw RGBA pixels and back. The comparison itself is always pixelmatch. */\n\n/** Engine names accepted by `images.engine` and `STORYSHELF_IMAGE_ENGINE`. */\nexport const IMAGE_ENGINES = [\"pngjs\", \"sharp\"] as const;\n\n/** A codec that can decode, encode and downscale PNGs. */\nexport type ImageEngine = (typeof IMAGE_ENGINES)[number];\n\n/** Environment variable that selects the engine when `images.engine` is not set. */\nexport const IMAGE_ENGINE_ENV = \"STORYSHELF_IMAGE_ENGINE\";\n\n/** The engine used when nothing is configured: pure JavaScript, runs anywhere. */\nexport const DEFAULT_IMAGE_ENGINE: ImageEngine = \"pngjs\";\n\n/** Raw 8-bit RGBA pixels, row-major, `width * height * 4` bytes. */\nexport interface RgbaImage {\n  width: number;\n  height: number;\n  data: Uint8Array;\n}\n\n/** Everything the engine needs from an image library. */\nexport interface ImageCodec {\n  readonly name: ImageEngine;\n  /** Decode a PNG to RGBA. */\n  decode(png: Buffer): Promise<RgbaImage> | RgbaImage;\n  /** Encode RGBA pixels as a PNG. */\n  encode(image: RgbaImage): Promise<Buffer> | Buffer;\n  /** Downscale a PNG so its long edge is at most `maxEdge`; output stays PNG. */\n  downscale(png: Uint8Array, maxEdge: number): Promise<Uint8Array> | Uint8Array;\n}\n\n/** Narrow an arbitrary string to a known engine name. */\nexport function isImageEngine(value: unknown): value is ImageEngine {\n  return IMAGE_ENGINES.some((engine) => engine === value);\n}\n\n/**\n * The engine named by a raw setting (an option or the `STORYSHELF_IMAGE_ENGINE` value); blank or\n * missing means the default. An unknown name throws so a typo cannot silently fall back.\n */\nexport function resolveImageEngine(raw: string | undefined): ImageEngine {\n  const value = raw?.trim();\n  if (value === undefined || value === \"\") {\n    return DEFAULT_IMAGE_ENGINE;\n  }\n  if (!isImageEngine(value)) {\n    throw new Error(`Unknown image engine \"${value}\". Use one of: ${IMAGE_ENGINES.join(\", \")}.`);\n  }\n  return value;\n}\n"],"mappings":";;;;;;AAGA,MAAa,gBAAgB,CAAC,SAAS,OAAO;;AAM9C,MAAa,mBAAmB;;AAGhC,MAAa,uBAAoC;;AAqBjD,SAAgB,cAAc,OAAsC;CAClE,OAAO,cAAc,MAAM,WAAW,WAAW,KAAK;AACxD;;;;;AAMA,SAAgB,mBAAmB,KAAsC;CACvE,MAAM,QAAQ,KAAK,KAAK;CACxB,IAAI,UAAU,KAAA,KAAa,UAAU,IACnC,OAAO;CAET,IAAI,CAAC,cAAc,KAAK,GACtB,MAAM,IAAI,MAAM,yBAAyB,MAAM,iBAAiB,cAAc,KAAK,IAAI,EAAE,EAAE;CAE7F,OAAO;AACT"}

package/dist/codecs.mjs

@@ -0,0 +1,28 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/codecs.ts
+const loaded = /* @__PURE__ */ new Map();
+/** The codec for an engine, loaded once per thread. Rejects when its dependency is unavailable. */
+async function loadCodec(engine) {
+	const existing = loaded.get(engine);
+	if (existing) return await existing;
+	const pending = engine === "sharp" ? importSharpCodec() : importPngjsCodec();
+	loaded.set(engine, pending);
+	try {
+		return await pending;
+	} catch (error) {
+		loaded.delete(engine);
+		throw error;
+	}
+}
+async function importPngjsCodec() {
+	return (await import("./pngjs.mjs")).pngjsCodec;
+}
+async function importSharpCodec() {
+	return await (await import("./sharp.mjs")).createSharpCodec();
+}
+//#endregion
+export { loadCodec };
+
+//# sourceMappingURL=codecs.mjs.map

package/dist/codecs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"codecs.mjs","names":[],"sources":["../src/codecs.ts"],"sourcesContent":["/** Codec registry: engines load on demand so an unused engine's dependencies are never imported. */\nimport type { ImageCodec, ImageEngine } from \"./codec.ts\";\n\nconst loaded = new Map<ImageEngine, Promise<ImageCodec>>();\n\n/** The codec for an engine, loaded once per thread. Rejects when its dependency is unavailable. */\nexport async function loadCodec(engine: ImageEngine): Promise<ImageCodec> {\n  const existing = loaded.get(engine);\n  if (existing) {\n    return await existing;\n  }\n  const pending = engine === \"sharp\" ? importSharpCodec() : importPngjsCodec();\n  loaded.set(engine, pending);\n  try {\n    return await pending;\n  } catch (error) {\n    loaded.delete(engine);\n    throw error;\n  }\n}\n\nasync function importPngjsCodec(): Promise<ImageCodec> {\n  return (await import(\"./pngjs.ts\")).pngjsCodec;\n}\n\nasync function importSharpCodec(): Promise<ImageCodec> {\n  return await (await import(\"./sharp.ts\")).createSharpCodec();\n}\n"],"mappings":";;;;AAGA,MAAM,yBAAS,IAAI,IAAsC;;AAGzD,eAAsB,UAAU,QAA0C;CACxE,MAAM,WAAW,OAAO,IAAI,MAAM;CAClC,IAAI,UACF,OAAO,MAAM;CAEf,MAAM,UAAU,WAAW,UAAU,iBAAiB,IAAI,iBAAiB;CAC3E,OAAO,IAAI,QAAQ,OAAO;CAC1B,IAAI;EACF,OAAO,MAAM;CACf,SAAS,OAAO;EACd,OAAO,OAAO,MAAM;EACpB,MAAM;CACR;AACF;AAEA,eAAe,mBAAwC;CACrD,QAAQ,MAAM,OAAO,eAAA,CAAe;AACtC;AAEA,eAAe,mBAAwC;CACrD,OAAO,OAAO,MAAM,OAAO,eAAA,CAAe,iBAAiB;AAC7D"}

package/dist/downscale.d.mts

@@ -0,0 +1,8 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/downscale.d.ts
+/** Downscale a PNG so its long edge is at most `maxEdge`, using the configured image engine. */
+declare function downscalePng(buffer: Uint8Array, maxEdge: number): Promise<Uint8Array>;
+//#endregion
+export { downscalePng };
+//# sourceMappingURL=downscale.d.mts.map

package/dist/downscale.mjs

@@ -0,0 +1,15 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadCodec } from "./codecs.mjs";
+import { currentImageEngine } from "./settings.mjs";
+//#region src/downscale.ts
+/** PNG thumbnails on the configured engine (output stays PNG). */
+/** Downscale a PNG so its long edge is at most `maxEdge`, using the configured image engine. */
+async function downscalePng(buffer, maxEdge) {
+	return await (await loadCodec(currentImageEngine())).downscale(buffer, maxEdge);
+}
+//#endregion
+export { downscalePng };
+
+//# sourceMappingURL=downscale.mjs.map

package/dist/downscale.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"downscale.mjs","names":[],"sources":["../src/downscale.ts"],"sourcesContent":["/** PNG thumbnails on the configured engine (output stays PNG). */\nimport { loadCodec } from \"./codecs.ts\";\nimport { currentImageEngine } from \"./settings.ts\";\n\n/** Downscale a PNG so its long edge is at most `maxEdge`, using the configured image engine. */\nexport async function downscalePng(buffer: Uint8Array, maxEdge: number): Promise<Uint8Array> {\n  const codec = await loadCodec(currentImageEngine());\n  return await codec.downscale(buffer, maxEdge);\n}\n"],"mappings":";;;;;;;;AAKA,eAAsB,aAAa,QAAoB,SAAsC;CAE3F,OAAO,OAAM,MADO,UAAU,mBAAmB,CAAC,EAAA,CAC/B,UAAU,QAAQ,OAAO;AAC9C"}

package/dist/engine.d.mts

@@ -0,0 +1,18 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DiffOptions, DiffResult } from "./options.mjs";
+import { ImageCodec } from "./codec.mjs";
+//#region src/engine.d.ts
+/**
+ * Compare baseline and current screenshots, returning pass/fail and a diff image.
+ *
+ * @param baseline - Baseline PNG buffer.
+ * @param current - Current capture PNG buffer.
+ * @param options - Pixel threshold and ratio limits.
+ * @param codec - Decodes and encodes the PNGs; pngjs unless an engine says otherwise.
+ * @returns The diff result with pixel counts and an optional overlay image.
+ */
+declare function diffImages(baseline: Buffer, current: Buffer, options: DiffOptions, codec?: ImageCodec): Promise<DiffResult>;
+//#endregion
+export { diffImages };
+//# sourceMappingURL=engine.d.mts.map

package/dist/engine.mjs

@@ -0,0 +1,144 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { pngjsCodec } from "./pngjs.mjs";
+import pixelmatch from "pixelmatch";
+//#region src/engine.ts
+/**
+* Compare baseline and current screenshots, returning pass/fail and a diff image.
+*
+* @param baseline - Baseline PNG buffer.
+* @param current - Current capture PNG buffer.
+* @param options - Pixel threshold and ratio limits.
+* @param codec - Decodes and encodes the PNGs; pngjs unless an engine says otherwise.
+* @returns The diff result with pixel counts and an optional overlay image.
+*/
+async function diffImages(baseline, current, options, codec = pngjsCodec) {
+	const identical = identicalResult(baseline, current);
+	if (identical) return identical;
+	const [baselineImage, currentImage] = await Promise.all([codec.decode(baseline), codec.decode(current)]);
+	return await compareImages(baselineImage, currentImage, options, codec);
+}
+/** Diff two decoded images; a size mismatch fails, or (with `failOnSizeChange: false`) diffs the overlap. */
+async function compareImages(baseline, current, options, codec) {
+	const baselineDimensions = {
+		width: baseline.width,
+		height: baseline.height
+	};
+	const currentDimensions = {
+		width: current.width,
+		height: current.height
+	};
+	const sizeChanged = baselineDimensions.width !== currentDimensions.width || baselineDimensions.height !== currentDimensions.height;
+	if (sizeChanged && options.failOnSizeChange) return {
+		passed: false,
+		diffPixels: 0,
+		diffRatio: 1,
+		diffImage: null,
+		baselineDimensions,
+		currentDimensions,
+		sizeChanged
+	};
+	const regions = sizeChanged ? overlapRegions(baseline, current) : whole(baseline, current);
+	const overlap = await compareRegions(regions, options, codec);
+	const diffRatio = overlap.diffPixels / (regions.width * regions.height);
+	return {
+		passed: diffRatio <= options.maxDiffRatio,
+		diffPixels: overlap.diffPixels,
+		diffRatio,
+		diffImage: overlap.diffImage,
+		baselineDimensions,
+		currentDimensions,
+		sizeChanged
+	};
+}
+function whole(baseline, current) {
+	return {
+		width: baseline.width,
+		height: baseline.height,
+		baseline: baseline.data,
+		current: current.data
+	};
+}
+/** Pixelmatch needs equal-size inputs, so both images are cropped to their shared top-left area. */
+function overlapRegions(baseline, current) {
+	const width = Math.min(baseline.width, current.width);
+	const height = Math.min(baseline.height, current.height);
+	return {
+		width,
+		height,
+		baseline: cropRgba(baseline.data, baseline.width, width, height),
+		current: cropRgba(current.data, current.width, width, height)
+	};
+}
+const PNG_SIGNATURE = Buffer.from([
+	137,
+	80,
+	78,
+	71,
+	13,
+	10,
+	26,
+	10
+]);
+const IHDR_END = 24;
+/**
+* Fast path for byte-equal inputs: no decode, no pixelmatch, no overlay.
+*
+* Equal bytes decode to equal pixels, so the diff is empty by construction. Dimensions come from
+* the IHDR chunk (big-endian width/height at bytes 16-23). Inputs that are not recognisably PNG
+* return null so the regular path reports the decode error as before. A direct byte comparison
+* is used instead of hashing both buffers: it is exact and cheaper than two digests.
+*/
+function identicalResult(baseline, current) {
+	if (baseline.length < IHDR_END || !baseline.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE) || !baseline.equals(current)) return null;
+	const dimensions = {
+		width: baseline.readUInt32BE(16),
+		height: baseline.readUInt32BE(20)
+	};
+	return {
+		passed: true,
+		diffPixels: 0,
+		diffRatio: 0,
+		diffImage: null,
+		baselineDimensions: dimensions,
+		currentDimensions: { ...dimensions },
+		sizeChanged: false
+	};
+}
+function cropRgba(source, sourceWidth, width, height) {
+	const cropped = new Uint8Array(width * height * 4);
+	const rowBytes = width * 4;
+	const sourceRowBytes = sourceWidth * 4;
+	for (let y = 0; y < height; y += 1) cropped.set(source.subarray(y * sourceRowBytes, y * sourceRowBytes + rowBytes), y * rowBytes);
+	return cropped;
+}
+/**
+* Count differing pixels first without an output buffer; only a failing result pays for the
+* overlay (a second pixelmatch pass plus PNG encode), since passing overlays are discarded.
+*/
+async function compareRegions({ width, height, baseline, current }, options, codec) {
+	const matchOptions = {
+		threshold: options.pixelThreshold,
+		includeAA: options.includeAntialiasing
+	};
+	const diffPixels = pixelmatch(baseline, current, void 0, width, height, matchOptions);
+	if (diffPixels / (width * height) <= options.maxDiffRatio) return {
+		diffPixels,
+		diffImage: null
+	};
+	const overlay = {
+		width,
+		height,
+		data: new Uint8Array(width * height * 4)
+	};
+	pixelmatch(baseline, current, overlay.data, width, height, matchOptions);
+	return {
+		diffPixels,
+		diffImage: await codec.encode(overlay)
+	};
+}
+//#endregion
+export { diffImages, identicalResult };
+
+//# sourceMappingURL=engine.mjs.map

package/dist/engine.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.mjs","names":[],"sources":["../src/engine.ts"],"sourcesContent":["import pixelmatch from \"pixelmatch\";\nimport type { ImageCodec, RgbaImage } from \"./codec.ts\";\nimport type { DiffOptions, DiffResult } from \"./options.ts\";\nimport { pngjsCodec } from \"./pngjs.ts\";\n\n/**\n * Compare baseline and current screenshots, returning pass/fail and a diff image.\n *\n * @param baseline - Baseline PNG buffer.\n * @param current - Current capture PNG buffer.\n * @param options - Pixel threshold and ratio limits.\n * @param codec - Decodes and encodes the PNGs; pngjs unless an engine says otherwise.\n * @returns The diff result with pixel counts and an optional overlay image.\n */\nexport async function diffImages(\n  baseline: Buffer,\n  current: Buffer,\n  options: DiffOptions,\n  codec: ImageCodec = pngjsCodec,\n): Promise<DiffResult> {\n  const identical = identicalResult(baseline, current);\n  if (identical) {\n    return identical;\n  }\n  const [baselineImage, currentImage] = await Promise.all([\n    codec.decode(baseline),\n    codec.decode(current),\n  ]);\n  return await compareImages(baselineImage, currentImage, options, codec);\n}\n\n/** Diff two decoded images; a size mismatch fails, or (with `failOnSizeChange: false`) diffs the overlap. */\nasync function compareImages(\n  baseline: RgbaImage,\n  current: RgbaImage,\n  options: DiffOptions,\n  codec: ImageCodec,\n): Promise<DiffResult> {\n  const baselineDimensions = { width: baseline.width, height: baseline.height };\n  const currentDimensions = { width: current.width, height: current.height };\n  const sizeChanged =\n    baselineDimensions.width !== currentDimensions.width ||\n    baselineDimensions.height !== currentDimensions.height;\n  if (sizeChanged && options.failOnSizeChange) {\n    return {\n      passed: false,\n      diffPixels: 0,\n      diffRatio: 1,\n      diffImage: null,\n      baselineDimensions,\n      currentDimensions,\n      sizeChanged,\n    };\n  }\n  // The larger image is cropped to the top-left overlap, which is normalised by its own area.\n  const regions = sizeChanged ? overlapRegions(baseline, current) : whole(baseline, current);\n  const overlap = await compareRegions(regions, options, codec);\n  const diffRatio = overlap.diffPixels / (regions.width * regions.height);\n  return {\n    passed: diffRatio <= options.maxDiffRatio,\n    diffPixels: overlap.diffPixels,\n    diffRatio,\n    diffImage: overlap.diffImage,\n    baselineDimensions,\n    currentDimensions,\n    sizeChanged,\n  };\n}\n\nfunction whole(baseline: RgbaImage, current: RgbaImage): Regions {\n  return {\n    width: baseline.width,\n    height: baseline.height,\n    baseline: baseline.data,\n    current: current.data,\n  };\n}\n\n/** Pixelmatch needs equal-size inputs, so both images are cropped to their shared top-left area. */\nfunction overlapRegions(baseline: RgbaImage, current: RgbaImage): Regions {\n  const width = Math.min(baseline.width, current.width);\n  const height = Math.min(baseline.height, current.height);\n  return {\n    width,\n    height,\n    baseline: cropRgba(baseline.data, baseline.width, width, height),\n    current: cropRgba(current.data, current.width, width, height),\n  };\n}\n\nconst PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);\nconst IHDR_END = 24;\n\n/**\n * Fast path for byte-equal inputs: no decode, no pixelmatch, no overlay.\n *\n * Equal bytes decode to equal pixels, so the diff is empty by construction. Dimensions come from\n * the IHDR chunk (big-endian width/height at bytes 16-23). Inputs that are not recognisably PNG\n * return null so the regular path reports the decode error as before. A direct byte comparison\n * is used instead of hashing both buffers: it is exact and cheaper than two digests.\n */\nexport function identicalResult(baseline: Buffer, current: Buffer): DiffResult | null {\n  if (\n    baseline.length < IHDR_END ||\n    !baseline.subarray(0, PNG_SIGNATURE.length).equals(PNG_SIGNATURE) ||\n    !baseline.equals(current)\n  ) {\n    return null;\n  }\n  const dimensions = { width: baseline.readUInt32BE(16), height: baseline.readUInt32BE(20) };\n  return {\n    passed: true,\n    diffPixels: 0,\n    diffRatio: 0,\n    diffImage: null,\n    baselineDimensions: dimensions,\n    currentDimensions: { ...dimensions },\n    sizeChanged: false,\n  };\n}\n\nfunction cropRgba(\n  source: Uint8Array,\n  sourceWidth: number,\n  width: number,\n  height: number,\n): Uint8Array {\n  const cropped = new Uint8Array(width * height * 4);\n  const rowBytes = width * 4;\n  const sourceRowBytes = sourceWidth * 4;\n  for (let y = 0; y < height; y += 1) {\n    cropped.set(source.subarray(y * sourceRowBytes, y * sourceRowBytes + rowBytes), y * rowBytes);\n  }\n  return cropped;\n}\n\n/** Two same-sized RGBA buffers to compare. */\ninterface Regions {\n  width: number;\n  height: number;\n  baseline: Uint8Array;\n  current: Uint8Array;\n}\n\n/**\n * Count differing pixels first without an output buffer; only a failing result pays for the\n * overlay (a second pixelmatch pass plus PNG encode), since passing overlays are discarded.\n */\nasync function compareRegions(\n  { width, height, baseline, current }: Regions,\n  options: DiffOptions,\n  codec: ImageCodec,\n): Promise<{ diffPixels: number; diffImage: Buffer | null }> {\n  const matchOptions = {\n    threshold: options.pixelThreshold,\n    includeAA: options.includeAntialiasing,\n  };\n  const diffPixels = pixelmatch(baseline, current, undefined, width, height, matchOptions);\n  if (diffPixels / (width * height) <= options.maxDiffRatio) {\n    return { diffPixels, diffImage: null };\n  }\n  const overlay: RgbaImage = { width, height, data: new Uint8Array(width * height * 4) };\n  pixelmatch(baseline, current, overlay.data, width, height, matchOptions);\n  return { diffPixels, diffImage: await codec.encode(overlay) };\n}\n"],"mappings":"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"}

package/dist/index.d.mts

@@ -0,0 +1,9 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { DEFAULT_DIFF_OPTIONS, DiffOptions, DiffResult } from "./options.mjs";
+import { DEFAULT_IMAGE_ENGINE, IMAGE_ENGINES, IMAGE_ENGINE_ENV, ImageEngine, isImageEngine, resolveImageEngine } from "./codec.mjs";
+import { ImageSettings, currentImageEngine, verifyImageEngine } from "./settings.mjs";
+import { DIFF_WORKERS_ENV, configureImages, diffImagesAsync, shutdownDiffPool } from "./async.mjs";
+import { downscalePng } from "./downscale.mjs";
+import { diffImages } from "./engine.mjs";
+export { DEFAULT_DIFF_OPTIONS, DEFAULT_IMAGE_ENGINE, DIFF_WORKERS_ENV, type DiffOptions, type DiffResult, IMAGE_ENGINES, IMAGE_ENGINE_ENV, type ImageEngine, type ImageSettings, configureImages, currentImageEngine, diffImages, diffImagesAsync, downscalePng, isImageEngine, resolveImageEngine, shutdownDiffPool, verifyImageEngine };

package/dist/index.mjs

@@ -0,0 +1,10 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { diffImages } from "./engine.mjs";
+import { DEFAULT_IMAGE_ENGINE, IMAGE_ENGINES, IMAGE_ENGINE_ENV, isImageEngine, resolveImageEngine } from "./codec.mjs";
+import { currentImageEngine, verifyImageEngine } from "./settings.mjs";
+import { DIFF_WORKERS_ENV, configureImages, diffImagesAsync, shutdownDiffPool } from "./async.mjs";
+import { downscalePng } from "./downscale.mjs";
+import { DEFAULT_DIFF_OPTIONS } from "./options.mjs";
+export { DEFAULT_DIFF_OPTIONS, DEFAULT_IMAGE_ENGINE, DIFF_WORKERS_ENV, IMAGE_ENGINES, IMAGE_ENGINE_ENV, configureImages, currentImageEngine, diffImages, diffImagesAsync, downscalePng, isImageEngine, resolveImageEngine, shutdownDiffPool, verifyImageEngine };

package/dist/options.d.mts

@@ -0,0 +1,42 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+//#region src/options.d.ts
+/** Options that control how two images are compared. */
+interface DiffOptions {
+  /** Per-pixel difference threshold (0-1) above which a pixel counts as different. */
+  pixelThreshold: number;
+  /** Maximum allowed ratio of differing pixels for a diff to pass. */
+  maxDiffRatio: number;
+  /** Whether to include antialiasing artifacts when counting differing pixels. */
+  includeAntialiasing: boolean;
+  /** Whether a size mismatch between images should fail the diff. When false, only the overlapping region is diffed. */
+  failOnSizeChange: boolean;
+}
+/** The outcome of comparing a baseline and a current screenshot. */
+interface DiffResult {
+  /** Whether the current image is within the accepted tolerance. */
+  passed: boolean;
+  /** Number of differing pixels. */
+  diffPixels: number;
+  /** Ratio of differing pixels to total pixels. */
+  diffRatio: number;
+  /** Generated diff overlay image, or null when unavailable. */
+  diffImage: Buffer | null;
+  /** Dimensions of the baseline image. */
+  baselineDimensions: {
+    width: number;
+    height: number;
+  };
+  /** Dimensions of the current image. */
+  currentDimensions: {
+    width: number;
+    height: number;
+  };
+  /** Whether the two images have different dimensions. */
+  sizeChanged: boolean;
+}
+/** Default diff settings used when no project overrides are present. */
+declare const DEFAULT_DIFF_OPTIONS: DiffOptions;
+//#endregion
+export { DEFAULT_DIFF_OPTIONS, DiffOptions, DiffResult };
+//# sourceMappingURL=options.d.mts.map

package/dist/options.mjs

@@ -0,0 +1,15 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/options.ts
+/** Default diff settings used when no project overrides are present. */
+const DEFAULT_DIFF_OPTIONS = {
+	pixelThreshold: .1,
+	maxDiffRatio: .01,
+	includeAntialiasing: false,
+	failOnSizeChange: true
+};
+//#endregion
+export { DEFAULT_DIFF_OPTIONS };
+
+//# sourceMappingURL=options.mjs.map

package/dist/options.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.mjs","names":[],"sources":["../src/options.ts"],"sourcesContent":["/** Options that control how two images are compared. */\nexport interface DiffOptions {\n  /** Per-pixel difference threshold (0-1) above which a pixel counts as different. */\n  pixelThreshold: number;\n  /** Maximum allowed ratio of differing pixels for a diff to pass. */\n  maxDiffRatio: number;\n  /** Whether to include antialiasing artifacts when counting differing pixels. */\n  includeAntialiasing: boolean;\n  /** Whether a size mismatch between images should fail the diff. When false, only the overlapping region is diffed. */\n  failOnSizeChange: boolean;\n}\n\n/** The outcome of comparing a baseline and a current screenshot. */\nexport interface DiffResult {\n  /** Whether the current image is within the accepted tolerance. */\n  passed: boolean;\n  /** Number of differing pixels. */\n  diffPixels: number;\n  /** Ratio of differing pixels to total pixels. */\n  diffRatio: number;\n  /** Generated diff overlay image, or null when unavailable. */\n  diffImage: Buffer | null;\n  /** Dimensions of the baseline image. */\n  baselineDimensions: { width: number; height: number };\n  /** Dimensions of the current image. */\n  currentDimensions: { width: number; height: number };\n  /** Whether the two images have different dimensions. */\n  sizeChanged: boolean;\n}\n\n/** Default diff settings used when no project overrides are present. */\nexport const DEFAULT_DIFF_OPTIONS: DiffOptions = {\n  pixelThreshold: 0.1,\n  maxDiffRatio: 0.01,\n  includeAntialiasing: false,\n  failOnSizeChange: true,\n};\n"],"mappings":";;;;;AA+BA,MAAa,uBAAoC;CAC/C,gBAAgB;CAChB,cAAc;CACd,qBAAqB;CACrB,kBAAkB;AACpB"}

package/dist/pngjs-downscale.mjs

@@ -0,0 +1,51 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { PNG } from "pngjs";
+//#region src/pngjs-downscale.ts
+/** Box-sampling PNG downscale on pngjs. */
+/** Downscale a PNG so its long edge is at most `maxEdge` (box sampling). */
+function downscaleWithPngjs(buffer, maxEdge) {
+	const src = PNG.sync.read(Buffer.from(buffer));
+	const scale = Math.min(1, maxEdge / Math.max(src.width, src.height));
+	if (scale >= 1) return new Uint8Array(PNG.sync.write(src));
+	const dst = new PNG({
+		width: Math.max(1, Math.round(src.width * scale)),
+		height: Math.max(1, Math.round(src.height * scale))
+	});
+	for (let row = 0; row < dst.height; row += 1) for (let col = 0; col < dst.width; col += 1) writePixel(dst, col, row, averageBox(src, boxOf(src, col, row, 1 / scale)));
+	return new Uint8Array(PNG.sync.write(dst));
+}
+function boxOf(src, col, row, factor) {
+	const x0 = Math.floor(col * factor);
+	const y0 = Math.floor(row * factor);
+	return {
+		x0,
+		y0,
+		x1: Math.min(src.width, Math.max(x0 + 1, Math.floor((col + 1) * factor))),
+		y1: Math.min(src.height, Math.max(y0 + 1, Math.floor((row + 1) * factor)))
+	};
+}
+function averageBox(src, box) {
+	const sum = [
+		0,
+		0,
+		0,
+		0
+	];
+	let count = 0;
+	for (let sy = box.y0; sy < box.y1; sy += 1) for (let sx = box.x0; sx < box.x1; sx += 1) {
+		const at = (sy * src.width + sx) * 4;
+		for (let channel = 0; channel < 4; channel += 1) sum[channel] = (sum[channel] ?? 0) + (src.data[at + channel] ?? 0);
+		count += 1;
+	}
+	return sum.map((total) => Math.round(total / Math.max(1, count)));
+}
+function writePixel(dst, col, row, rgba) {
+	const at = (row * dst.width + col) * 4;
+	for (let channel = 0; channel < 4; channel += 1) dst.data[at + channel] = rgba[channel] ?? 0;
+}
+//#endregion
+export { downscaleWithPngjs };
+
+//# sourceMappingURL=pngjs-downscale.mjs.map