@storyshelf/image 0.0.0-stage → 0.6.2

package/dist/pngjs-downscale.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pngjs-downscale.mjs","names":[],"sources":["../src/pngjs-downscale.ts"],"sourcesContent":["/** Box-sampling PNG downscale on pngjs. */\nimport { PNG } from \"pngjs\";\n\n/** Downscale a PNG so its long edge is at most `maxEdge` (box sampling). */\nexport function downscaleWithPngjs(buffer: Uint8Array, maxEdge: number): Uint8Array {\n  const src = PNG.sync.read(Buffer.from(buffer));\n  const scale = Math.min(1, maxEdge / Math.max(src.width, src.height));\n  if (scale >= 1) {\n    return new Uint8Array(PNG.sync.write(src));\n  }\n  const dst = new PNG({\n    width: Math.max(1, Math.round(src.width * scale)),\n    height: Math.max(1, Math.round(src.height * scale)),\n  });\n  for (let row = 0; row < dst.height; row += 1) {\n    for (let col = 0; col < dst.width; col += 1) {\n      writePixel(dst, col, row, averageBox(src, boxOf(src, col, row, 1 / scale)));\n    }\n  }\n  return new Uint8Array(PNG.sync.write(dst));\n}\n\ninterface Box {\n  x0: number;\n  y0: number;\n  x1: number;\n  y1: number;\n}\n\nfunction boxOf(src: PNG, col: number, row: number, factor: number): Box {\n  const x0 = Math.floor(col * factor);\n  const y0 = Math.floor(row * factor);\n  return {\n    x0,\n    y0,\n    x1: Math.min(src.width, Math.max(x0 + 1, Math.floor((col + 1) * factor))),\n    y1: Math.min(src.height, Math.max(y0 + 1, Math.floor((row + 1) * factor))),\n  };\n}\n\nfunction averageBox(src: PNG, box: Box): number[] {\n  const sum = [0, 0, 0, 0];\n  let count = 0;\n  for (let sy = box.y0; sy < box.y1; sy += 1) {\n    for (let sx = box.x0; sx < box.x1; sx += 1) {\n      const at = (sy * src.width + sx) * 4;\n      for (let channel = 0; channel < 4; channel += 1) {\n        sum[channel] = (sum[channel] ?? 0) + (src.data[at + channel] ?? 0);\n      }\n      count += 1;\n    }\n  }\n  return sum.map((total) => Math.round(total / Math.max(1, count)));\n}\n\nfunction writePixel(dst: PNG, col: number, row: number, rgba: number[]): void {\n  const at = (row * dst.width + col) * 4;\n  for (let channel = 0; channel < 4; channel += 1) {\n    dst.data[at + channel] = rgba[channel] ?? 0;\n  }\n}\n"],"mappings":";;;;;;;AAIA,SAAgB,mBAAmB,QAAoB,SAA6B;CAClF,MAAM,MAAM,IAAI,KAAK,KAAK,OAAO,KAAK,MAAM,CAAC;CAC7C,MAAM,QAAQ,KAAK,IAAI,GAAG,UAAU,KAAK,IAAI,IAAI,OAAO,IAAI,MAAM,CAAC;CACnE,IAAI,SAAS,GACX,OAAO,IAAI,WAAW,IAAI,KAAK,MAAM,GAAG,CAAC;CAE3C,MAAM,MAAM,IAAI,IAAI;EAClB,OAAO,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,QAAQ,KAAK,CAAC;EAChD,QAAQ,KAAK,IAAI,GAAG,KAAK,MAAM,IAAI,SAAS,KAAK,CAAC;CACpD,CAAC;CACD,KAAK,IAAI,MAAM,GAAG,MAAM,IAAI,QAAQ,OAAO,GACzC,KAAK,IAAI,MAAM,GAAG,MAAM,IAAI,OAAO,OAAO,GACxC,WAAW,KAAK,KAAK,KAAK,WAAW,KAAK,MAAM,KAAK,KAAK,KAAK,IAAI,KAAK,CAAC,CAAC;CAG9E,OAAO,IAAI,WAAW,IAAI,KAAK,MAAM,GAAG,CAAC;AAC3C;AASA,SAAS,MAAM,KAAU,KAAa,KAAa,QAAqB;CACtE,MAAM,KAAK,KAAK,MAAM,MAAM,MAAM;CAClC,MAAM,KAAK,KAAK,MAAM,MAAM,MAAM;CAClC,OAAO;EACL;EACA;EACA,IAAI,KAAK,IAAI,IAAI,OAAO,KAAK,IAAI,KAAK,GAAG,KAAK,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC;EACxE,IAAI,KAAK,IAAI,IAAI,QAAQ,KAAK,IAAI,KAAK,GAAG,KAAK,OAAO,MAAM,KAAK,MAAM,CAAC,CAAC;CAC3E;AACF;AAEA,SAAS,WAAW,KAAU,KAAoB;CAChD,MAAM,MAAM;EAAC;EAAG;EAAG;EAAG;CAAC;CACvB,IAAI,QAAQ;CACZ,KAAK,IAAI,KAAK,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,GACvC,KAAK,IAAI,KAAK,IAAI,IAAI,KAAK,IAAI,IAAI,MAAM,GAAG;EAC1C,MAAM,MAAM,KAAK,IAAI,QAAQ,MAAM;EACnC,KAAK,IAAI,UAAU,GAAG,UAAU,GAAG,WAAW,GAC5C,IAAI,YAAY,IAAI,YAAY,MAAM,IAAI,KAAK,KAAK,YAAY;EAElE,SAAS;CACX;CAEF,OAAO,IAAI,KAAK,UAAU,KAAK,MAAM,QAAQ,KAAK,IAAI,GAAG,KAAK,CAAC,CAAC;AAClE;AAEA,SAAS,WAAW,KAAU,KAAa,KAAa,MAAsB;CAC5E,MAAM,MAAM,MAAM,IAAI,QAAQ,OAAO;CACrC,KAAK,IAAI,UAAU,GAAG,UAAU,GAAG,WAAW,GAC5C,IAAI,KAAK,KAAK,WAAW,KAAK,YAAY;AAE9C"}

package/dist/pngjs.mjs

@@ -0,0 +1,31 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { downscaleWithPngjs } from "./pngjs-downscale.mjs";
+import { PNG } from "pngjs";
+//#region src/pngjs.ts
+/** The default codec: pure JavaScript (pngjs), runs on every runtime. */
+const pngjsCodec = {
+	name: "pngjs",
+	decode(png) {
+		const { width, height, data } = PNG.sync.read(png);
+		return {
+			width,
+			height,
+			data
+		};
+	},
+	encode({ width, height, data }) {
+		const view = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+		return PNG.sync.write({
+			width,
+			height,
+			data: view
+		});
+	},
+	downscale: downscaleWithPngjs
+};
+//#endregion
+export { pngjsCodec };
+
+//# sourceMappingURL=pngjs.mjs.map

package/dist/pngjs.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pngjs.mjs","names":[],"sources":["../src/pngjs.ts"],"sourcesContent":["/** The default codec: pure JavaScript (pngjs), runs on every runtime. */\nimport { PNG } from \"pngjs\";\nimport type { ImageCodec, RgbaImage } from \"./codec.ts\";\nimport { downscaleWithPngjs } from \"./pngjs-downscale.ts\";\n\nexport const pngjsCodec: ImageCodec = {\n  name: \"pngjs\",\n  decode(png: Buffer): RgbaImage {\n    const { width, height, data } = PNG.sync.read(png);\n    return { width, height, data };\n  },\n  encode({ width, height, data }: RgbaImage): Buffer {\n    // The packer only reads `width`, `height` and `data`, so hand it the pixels as they are\n    // instead of copying a full frame into a fresh PNG.\n    const view = Buffer.from(data.buffer, data.byteOffset, data.byteLength);\n    return PNG.sync.write({ width, height, data: view } as PNG);\n  },\n  downscale: downscaleWithPngjs,\n};\n"],"mappings":";;;;;;;AAKA,MAAa,aAAyB;CACpC,MAAM;CACN,OAAO,KAAwB;EAC7B,MAAM,EAAE,OAAO,QAAQ,SAAS,IAAI,KAAK,KAAK,GAAG;EACjD,OAAO;GAAE;GAAO;GAAQ;EAAK;CAC/B;CACA,OAAO,EAAE,OAAO,QAAQ,QAA2B;EAGjD,MAAM,OAAO,OAAO,KAAK,KAAK,QAAQ,KAAK,YAAY,KAAK,UAAU;EACtE,OAAO,IAAI,KAAK,MAAM;GAAE;GAAO;GAAQ,MAAM;EAAK,CAAQ;CAC5D;CACA,WAAW;AACb"}

package/dist/pool.mjs

@@ -0,0 +1,239 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadCodec } from "./codecs.mjs";
+import { diffImages, identicalResult } from "./engine.mjs";
+import { fromTransferred, toTransferable } from "./transfer.mjs";
+//#region src/pool.ts
+/** Workers dying before `ready` in a row, after one has started fine, before the pool gives up. */
+const MAX_START_FAILURES = 3;
+const livePools = /* @__PURE__ */ new Set();
+let exitHookInstalled = false;
+/**
+* Runs diffs on worker threads, transferring PNG bytes instead of copying them.
+*
+* Workers start on demand, take work only once they have reported `ready` (so a worker file that
+* fails to load never swallows a transferred buffer), and are `unref`'d while idle so they never
+* keep the process alive. If workers cannot be used at all, every diff runs in-thread.
+*/
+var DiffPool = class {
+	size;
+	workerUrl;
+	engine;
+	slots = [];
+	queue = [];
+	nextId = 0;
+	broken = false;
+	/** Whether any worker has reported ready, which proves the worker file loads. */
+	everReady = false;
+	startFailures = 0;
+	onFallback;
+	workerClass;
+	constructor(options) {
+		this.size = Math.max(0, Math.floor(options.size));
+		this.workerUrl = options.workerUrl;
+		this.engine = options.engine ?? "pngjs";
+		this.onFallback = options.onFallback ?? warnFallback;
+	}
+	/**
+	* Diff two PNGs. The inputs may be detached (transferred) when a worker runs the diff, so
+	* callers must not reuse them afterwards.
+	*/
+	async run(baseline, current, options) {
+		const identical = identicalResult(baseline, current);
+		if (identical) return identical;
+		if (this.size === 0 || this.broken || !await this.loadWorkerClass()) return await this.diffInThread(baseline, current, options);
+		return await new Promise((resolve, reject) => {
+			this.nextId += 1;
+			const { nextId: id } = this;
+			this.queue.push({
+				id,
+				baseline,
+				current,
+				options,
+				engine: this.engine,
+				resolve,
+				reject
+			});
+			this.pump();
+		});
+	}
+	async diffInThread(baseline, current, options) {
+		return await diffImages(baseline, current, options, await loadCodec(this.engine));
+	}
+	/** Stop all workers and reject unfinished work. The pool starts fresh workers if used again. */
+	async shutdown() {
+		livePools.delete(this);
+		const slots = this.slots.splice(0);
+		const queued = this.queue;
+		this.queue = [];
+		const stopped = /* @__PURE__ */ new Error("diff pool shut down");
+		for (const task of [...queued, ...slots.flatMap((slot) => slot.task ? [slot.task] : [])]) task.reject(stopped);
+		await Promise.all(slots.map(async (slot) => await slot.worker.terminate()));
+	}
+	/** Worker threads currently alive (for tests and diagnostics). */
+	get workerCount() {
+		return this.slots.length;
+	}
+	async loadWorkerClass() {
+		if (this.workerClass === void 0) try {
+			this.workerClass = (await import("node:worker_threads")).Worker;
+		} catch {
+			this.workerClass = null;
+		}
+		return this.workerClass !== null;
+	}
+	pump() {
+		if (this.broken) return;
+		this.dispatchToIdle();
+		this.spawnForQueue();
+	}
+	dispatchToIdle() {
+		for (let idle = this.idleSlot(); idle; idle = this.idleSlot()) {
+			const next = this.queue.shift();
+			if (!next) break;
+			dispatch(idle, next);
+		}
+	}
+	/** Start workers for queued work beyond the ones already starting, up to the pool size. */
+	spawnForQueue() {
+		const starting = this.slots.filter((slot) => !slot.ready).length;
+		const wanted = Math.min(this.queue.length - starting, this.size - this.slots.length);
+		for (let index = 0; index < wanted && this.workerClass; index += 1) this.spawn(this.workerClass);
+	}
+	idleSlot() {
+		return this.slots.find((slot) => slot.ready && !slot.task);
+	}
+	spawn(WorkerClass) {
+		try {
+			const slot = {
+				worker: new WorkerClass(this.workerUrl),
+				ready: false,
+				task: null
+			};
+			this.slots.push(slot);
+			installExitHook(this);
+			this.watch(slot);
+		} catch (error) {
+			this.onSpawnError(error);
+		}
+	}
+	watch(slot) {
+		slot.worker.on("message", (message) => {
+			this.onMessage(slot, message);
+		});
+		slot.worker.on("error", (error) => {
+			this.onLost(slot, error);
+		});
+		slot.worker.on("exit", (code) => {
+			this.onLost(slot, /* @__PURE__ */ new Error(`diff worker exited with code ${code}`));
+		});
+	}
+	/** `new Worker` threw (a thread limit, say): a start failure, and fatal with no worker left. */
+	onSpawnError(error) {
+		const reason = `diff worker could not start: ${String(error)}`;
+		this.onStartFailure(reason);
+		if (this.slots.length === 0) this.fallBackToThread(reason);
+	}
+	onMessage(slot, message) {
+		if (message.type === "ready") this.markReady(slot);
+		else if (slot.task?.id === message.id) {
+			const { task } = slot;
+			slot.task = null;
+			slot.worker.unref();
+			settle(task, message);
+		}
+		if (this.broken && !slot.task) this.retire(slot);
+		this.pump();
+	}
+	markReady(slot) {
+		slot.ready = true;
+		this.everReady = true;
+		this.startFailures = 0;
+		slot.worker.unref();
+	}
+	onLost(slot, error) {
+		const index = this.slots.indexOf(slot);
+		if (index === -1) return;
+		this.slots.splice(index, 1);
+		slot.task?.reject(error);
+		if (!slot.ready) this.onStartFailure(`diff worker exited before it was ready: ${error.message}`);
+		this.pump();
+	}
+	/**
+	* A worker died before reporting ready. Before any worker ever has, the worker file cannot run, so
+	* go in-thread; after one has, it is a crash (memory pressure, a thread limit) and the pool only
+	* gives up if replacements keep failing.
+	*/
+	onStartFailure(reason) {
+		this.startFailures += 1;
+		if (!this.everReady || this.startFailures >= MAX_START_FAILURES) this.fallBackToThread(reason);
+	}
+	retire(slot) {
+		const index = this.slots.indexOf(slot);
+		if (index !== -1) this.slots.splice(index, 1);
+		slot.worker.terminate().catch(ignore);
+	}
+	/**
+	* Stay in-thread for good. Idle and starting workers stop now; a worker busy with a diff keeps it
+	* (its buffers were transferred to it) and stops once it answers, so no running diff is dropped.
+	*/
+	fallBackToThread(reason) {
+		if (this.broken) return;
+		this.broken = true;
+		this.onFallback(reason);
+		for (const slot of this.slots.filter((candidate) => !candidate.task)) this.retire(slot);
+		const queued = this.queue;
+		this.queue = [];
+		for (const task of queued) this.diffInThread(task.baseline, task.current, task.options).then(task.resolve, (error) => {
+			task.reject(error instanceof Error ? error : new Error(String(error)));
+		});
+	}
+};
+/** Terminate workers when the process exits; they are unref'd when idle, this covers the rest. */
+function installExitHook(pool) {
+	livePools.add(pool);
+	if (exitHookInstalled) return;
+	exitHookInstalled = true;
+	process.once("exit", () => {
+		for (const live of livePools) live.shutdown().catch(ignore);
+	});
+}
+function ignore() {}
+function warnFallback(reason) {
+	process.emitWarning(`${reason}; running image diffs on the main thread from now on`, { code: "STORYSHELF_DIFF_POOL_FALLBACK" });
+}
+/** Hand a task to an idle worker, transferring both PNGs (copying any that are not exclusively owned). */
+function dispatch(slot, task) {
+	const baseline = toTransferable(task.baseline);
+	let current = toTransferable(task.current);
+	if (current.buffer === baseline.buffer) current = Uint8Array.from(current);
+	slot.task = task;
+	slot.worker.ref();
+	const request = {
+		id: task.id,
+		baseline,
+		current,
+		options: task.options,
+		engine: task.engine
+	};
+	slot.worker.postMessage(request, [baseline.buffer, current.buffer]);
+}
+/** Resolve or reject a task from the worker's answer. */
+function settle(task, message) {
+	if (message.type === "result") {
+		const { diffImage } = message.result;
+		task.resolve({
+			...message.result,
+			diffImage: diffImage ? fromTransferred(diffImage) : null
+		});
+		return;
+	}
+	const error = new Error(message.message);
+	error.name = message.name;
+	task.reject(error);
+}
+//#endregion
+export { DiffPool };
+
+//# sourceMappingURL=pool.mjs.map

package/dist/pool.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"pool.mjs","names":[],"sources":["../src/pool.ts"],"sourcesContent":["/** A small `worker_threads` pool that runs `diffImages` off the main thread. */\nimport type { Worker } from \"node:worker_threads\";\nimport type { ImageEngine } from \"./codec.ts\";\nimport { loadCodec } from \"./codecs.ts\";\nimport { diffImages, identicalResult } from \"./engine.ts\";\nimport type { DiffOptions, DiffResult } from \"./options.ts\";\nimport type { DiffRequest, DiffResponse } from \"./protocol.ts\";\nimport { fromTransferred, toTransferable } from \"./transfer.ts\";\n\n/** Options for {@link DiffPool}. */\nexport interface DiffPoolOptions {\n  /** Maximum worker threads; 0 runs every diff in the calling thread. */\n  size: number;\n  /** Worker module to spawn. */\n  workerUrl: URL | string;\n  /** Image engine the workers (and the in-thread fallback) use; pngjs when omitted. */\n  engine?: ImageEngine;\n  /**\n   * Called once if the pool gives up on threads and runs every diff in-thread from then on. Defaults\n   * to a process warning, since every later diff then blocks the event loop.\n   */\n  onFallback?: (reason: string) => void;\n}\n\n/** Workers dying before `ready` in a row, after one has started fine, before the pool gives up. */\nconst MAX_START_FAILURES = 3;\n\ninterface Pending {\n  id: number;\n  baseline: Buffer;\n  current: Buffer;\n  options: DiffOptions;\n  engine: ImageEngine;\n  resolve: (result: DiffResult) => void;\n  reject: (error: Error) => void;\n}\n\ninterface Slot {\n  worker: Worker;\n  ready: boolean;\n  task: Pending | null;\n}\n\ntype WorkerCtor = typeof Worker;\n\nconst livePools = new Set<DiffPool>();\nlet exitHookInstalled = false;\n\n/**\n * Runs diffs on worker threads, transferring PNG bytes instead of copying them.\n *\n * Workers start on demand, take work only once they have reported `ready` (so a worker file that\n * fails to load never swallows a transferred buffer), and are `unref`'d while idle so they never\n * keep the process alive. If workers cannot be used at all, every diff runs in-thread.\n */\nexport class DiffPool {\n  private readonly size: number;\n  private readonly workerUrl: URL | string;\n  private readonly engine: ImageEngine;\n  private readonly slots: Slot[] = [];\n  private queue: Pending[] = [];\n  private nextId = 0;\n  private broken = false;\n  /** Whether any worker has reported ready, which proves the worker file loads. */\n  private everReady = false;\n  private startFailures = 0;\n  private readonly onFallback: (reason: string) => void;\n  private workerClass: WorkerCtor | null | undefined;\n\n  constructor(options: DiffPoolOptions) {\n    this.size = Math.max(0, Math.floor(options.size));\n    this.workerUrl = options.workerUrl;\n    this.engine = options.engine ?? \"pngjs\";\n    this.onFallback = options.onFallback ?? warnFallback;\n  }\n\n  /**\n   * Diff two PNGs. The inputs may be detached (transferred) when a worker runs the diff, so\n   * callers must not reuse them afterwards.\n   */\n  async run(baseline: Buffer, current: Buffer, options: DiffOptions): Promise<DiffResult> {\n    const identical = identicalResult(baseline, current);\n    if (identical) {\n      return identical;\n    }\n    if (this.size === 0 || this.broken || !(await this.loadWorkerClass())) {\n      return await this.diffInThread(baseline, current, options);\n    }\n    return await new Promise<DiffResult>((resolve, reject) => {\n      this.nextId += 1;\n      const { nextId: id } = this;\n      this.queue.push({ id, baseline, current, options, engine: this.engine, resolve, reject });\n      this.pump();\n    });\n  }\n\n  private async diffInThread(\n    baseline: Buffer,\n    current: Buffer,\n    options: DiffOptions,\n  ): Promise<DiffResult> {\n    return await diffImages(baseline, current, options, await loadCodec(this.engine));\n  }\n\n  /** Stop all workers and reject unfinished work. The pool starts fresh workers if used again. */\n  async shutdown(): Promise<void> {\n    livePools.delete(this);\n    const slots = this.slots.splice(0);\n    const queued = this.queue;\n    this.queue = [];\n    const stopped = new Error(\"diff pool shut down\");\n    for (const task of [...queued, ...slots.flatMap((slot) => (slot.task ? [slot.task] : []))]) {\n      task.reject(stopped);\n    }\n    await Promise.all(slots.map(async (slot) => await slot.worker.terminate()));\n  }\n\n  /** Worker threads currently alive (for tests and diagnostics). */\n  get workerCount(): number {\n    return this.slots.length;\n  }\n\n  private async loadWorkerClass(): Promise<boolean> {\n    if (this.workerClass === undefined) {\n      try {\n        this.workerClass = (await import(\"node:worker_threads\")).Worker;\n      } catch {\n        this.workerClass = null;\n      }\n    }\n    return this.workerClass !== null;\n  }\n\n  private pump(): void {\n    if (this.broken) {\n      return;\n    }\n    this.dispatchToIdle();\n    this.spawnForQueue();\n  }\n\n  private dispatchToIdle(): void {\n    for (let idle = this.idleSlot(); idle; idle = this.idleSlot()) {\n      const next = this.queue.shift();\n      if (!next) {\n        break;\n      }\n      dispatch(idle, next);\n    }\n  }\n\n  /** Start workers for queued work beyond the ones already starting, up to the pool size. */\n  private spawnForQueue(): void {\n    const starting = this.slots.filter((slot) => !slot.ready).length;\n    const wanted = Math.min(this.queue.length - starting, this.size - this.slots.length);\n    for (let index = 0; index < wanted && this.workerClass; index += 1) {\n      this.spawn(this.workerClass);\n    }\n  }\n\n  private idleSlot(): Slot | undefined {\n    return this.slots.find((slot) => slot.ready && !slot.task);\n  }\n\n  private spawn(WorkerClass: WorkerCtor): void {\n    try {\n      const worker = new WorkerClass(this.workerUrl);\n      const slot: Slot = { worker, ready: false, task: null };\n      this.slots.push(slot);\n      installExitHook(this);\n      this.watch(slot);\n    } catch (error) {\n      this.onSpawnError(error);\n    }\n  }\n\n  private watch(slot: Slot): void {\n    slot.worker.on(\"message\", (message: DiffResponse) => {\n      this.onMessage(slot, message);\n    });\n    slot.worker.on(\"error\", (error: Error) => {\n      this.onLost(slot, error);\n    });\n    slot.worker.on(\"exit\", (code) => {\n      this.onLost(slot, new Error(`diff worker exited with code ${code}`));\n    });\n  }\n\n  /** `new Worker` threw (a thread limit, say): a start failure, and fatal with no worker left. */\n  private onSpawnError(error: unknown): void {\n    const reason = `diff worker could not start: ${String(error)}`;\n    this.onStartFailure(reason);\n    if (this.slots.length === 0) {\n      this.fallBackToThread(reason);\n    }\n  }\n\n  private onMessage(slot: Slot, message: DiffResponse): void {\n    if (message.type === \"ready\") {\n      this.markReady(slot);\n    } else if (slot.task?.id === message.id) {\n      const { task } = slot;\n      slot.task = null;\n      slot.worker.unref();\n      settle(task, message);\n    }\n    if (this.broken && !slot.task) {\n      this.retire(slot);\n    }\n    this.pump();\n  }\n\n  private markReady(slot: Slot): void {\n    slot.ready = true;\n    this.everReady = true;\n    this.startFailures = 0;\n    slot.worker.unref();\n  }\n\n  private onLost(slot: Slot, error: Error): void {\n    const index = this.slots.indexOf(slot);\n    if (index === -1) {\n      return;\n    }\n    this.slots.splice(index, 1);\n    slot.task?.reject(error);\n    if (!slot.ready) {\n      this.onStartFailure(`diff worker exited before it was ready: ${error.message}`);\n    }\n    this.pump();\n  }\n\n  /**\n   * A worker died before reporting ready. Before any worker ever has, the worker file cannot run, so\n   * go in-thread; after one has, it is a crash (memory pressure, a thread limit) and the pool only\n   * gives up if replacements keep failing.\n   */\n  private onStartFailure(reason: string): void {\n    this.startFailures += 1;\n    if (!this.everReady || this.startFailures >= MAX_START_FAILURES) {\n      this.fallBackToThread(reason);\n    }\n  }\n\n  private retire(slot: Slot): void {\n    const index = this.slots.indexOf(slot);\n    if (index !== -1) {\n      this.slots.splice(index, 1);\n    }\n    slot.worker.terminate().catch(ignore);\n  }\n\n  /**\n   * Stay in-thread for good. Idle and starting workers stop now; a worker busy with a diff keeps it\n   * (its buffers were transferred to it) and stops once it answers, so no running diff is dropped.\n   */\n  private fallBackToThread(reason: string): void {\n    if (this.broken) {\n      return;\n    }\n    this.broken = true;\n    this.onFallback(reason);\n    for (const slot of this.slots.filter((candidate) => !candidate.task)) {\n      this.retire(slot);\n    }\n    const queued = this.queue;\n    this.queue = [];\n    for (const task of queued) {\n      this.diffInThread(task.baseline, task.current, task.options).then(\n        task.resolve,\n        (error: unknown) => {\n          task.reject(error instanceof Error ? error : new Error(String(error)));\n        },\n      );\n    }\n  }\n}\n\n/** Terminate workers when the process exits; they are unref'd when idle, this covers the rest. */\nfunction installExitHook(pool: DiffPool): void {\n  livePools.add(pool);\n  if (exitHookInstalled) {\n    return;\n  }\n  exitHookInstalled = true;\n  process.once(\"exit\", () => {\n    for (const live of livePools) {\n      live.shutdown().catch(ignore);\n    }\n  });\n}\n\nfunction ignore(): void {}\n\nfunction warnFallback(reason: string): void {\n  process.emitWarning(`${reason}; running image diffs on the main thread from now on`, {\n    code: \"STORYSHELF_DIFF_POOL_FALLBACK\",\n  });\n}\n\n/** Hand a task to an idle worker, transferring both PNGs (copying any that are not exclusively owned). */\nfunction dispatch(slot: Slot, task: Pending): void {\n  const baseline = toTransferable(task.baseline);\n  let current = toTransferable(task.current);\n  if (current.buffer === baseline.buffer) {\n    current = Uint8Array.from(current);\n  }\n  slot.task = task;\n  slot.worker.ref();\n  const request: DiffRequest = {\n    id: task.id,\n    baseline,\n    current,\n    options: task.options,\n    engine: task.engine,\n  };\n  slot.worker.postMessage(request, [baseline.buffer as ArrayBuffer, current.buffer as ArrayBuffer]);\n}\n\n/** Resolve or reject a task from the worker's answer. */\nfunction settle(task: Pending, message: Exclude<DiffResponse, { type: \"ready\" }>): void {\n  if (message.type === \"result\") {\n    const { diffImage } = message.result;\n    task.resolve({ ...message.result, diffImage: diffImage ? fromTransferred(diffImage) : null });\n    return;\n  }\n  const error = new Error(message.message);\n  error.name = message.name;\n  task.reject(error);\n}\n"],"mappings":"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"}

package/dist/settings.d.mts

@@ -0,0 +1,22 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';
+import { ImageEngine } from "./codec.mjs";
+//#region src/settings.d.ts
+/** What `createShelfApp` passes down: `images.engine` and `compare.threads`. */
+interface ImageSettings {
+  /** Image library: `"pngjs"` (default) or `"sharp"`; falls back to `STORYSHELF_IMAGE_ENGINE`. */
+  engine?: string;
+  /** Worker threads for diffs; `0` runs on the main thread. */
+  threads?: number;
+}
+/** The engine in effect: the configured one, else the environment, else the default. */
+declare function currentImageEngine(): ImageEngine;
+/**
+ * Load the engine's dependencies now, so a missing `sharp` fails at boot with a clear message
+ * instead of on the first diff. The default engine is a hard dependency with nothing to verify,
+ * so it returns at once and never delays startup (or the first capture).
+ */
+declare function verifyImageEngine(): Promise<ImageEngine>;
+//#endregion
+export { ImageSettings, currentImageEngine, verifyImageEngine };
+//# sourceMappingURL=settings.d.mts.map

package/dist/settings.mjs

@@ -0,0 +1,48 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadCodec } from "./codecs.mjs";
+import { resolveImageEngine } from "./codec.mjs";
+//#region src/settings.ts
+/** Process-wide image settings, set once at app boot and read by the diff pool and thumbnails. */
+let configuredEngine;
+let configuredThreads;
+/**
+* Record the engine and thread count (the caller then rebuilds anything that depends on them).
+* The option wins: `STORYSHELF_IMAGE_ENGINE` is read only when no engine is given, so a bad
+* variable cannot break an explicit option. Throws on an unknown name so a typo never silently
+* picks a different engine.
+*/
+function setImageSettings(settings) {
+	configuredEngine = resolveImageEngine(settings.engine ?? process.env["STORYSHELF_IMAGE_ENGINE"]);
+	configuredThreads = settings.threads;
+}
+/** What the last {@link setImageSettings} resolved, without consulting the environment. */
+function appliedImageSettings() {
+	return {
+		engine: configuredEngine,
+		threads: configuredThreads
+	};
+}
+/** The engine in effect: the configured one, else the environment, else the default. */
+function currentImageEngine() {
+	return configuredEngine ?? resolveImageEngine(process.env["STORYSHELF_IMAGE_ENGINE"]);
+}
+/** The configured thread count, or `undefined` to defer to the environment/default. */
+function configuredThreadCount() {
+	return configuredThreads;
+}
+/**
+* Load the engine's dependencies now, so a missing `sharp` fails at boot with a clear message
+* instead of on the first diff. The default engine is a hard dependency with nothing to verify,
+* so it returns at once and never delays startup (or the first capture).
+*/
+async function verifyImageEngine() {
+	const engine = currentImageEngine();
+	if (engine !== "pngjs") await loadCodec(engine);
+	return engine;
+}
+//#endregion
+export { appliedImageSettings, configuredThreadCount, currentImageEngine, setImageSettings, verifyImageEngine };
+
+//# sourceMappingURL=settings.mjs.map

package/dist/settings.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.mjs","names":[],"sources":["../src/settings.ts"],"sourcesContent":["/** Process-wide image settings, set once at app boot and read by the diff pool and thumbnails. */\nimport {\n  DEFAULT_IMAGE_ENGINE,\n  IMAGE_ENGINE_ENV,\n  type ImageEngine,\n  resolveImageEngine,\n} from \"./codec.ts\";\nimport { loadCodec } from \"./codecs.ts\";\n\n/** What `createShelfApp` passes down: `images.engine` and `compare.threads`. */\nexport interface ImageSettings {\n  /** Image library: `\"pngjs\"` (default) or `\"sharp\"`; falls back to `STORYSHELF_IMAGE_ENGINE`. */\n  engine?: string;\n  /** Worker threads for diffs; `0` runs on the main thread. */\n  threads?: number;\n}\n\nlet configuredEngine: ImageEngine | undefined;\nlet configuredThreads: number | undefined;\n\n/**\n * Record the engine and thread count (the caller then rebuilds anything that depends on them).\n * The option wins: `STORYSHELF_IMAGE_ENGINE` is read only when no engine is given, so a bad\n * variable cannot break an explicit option. Throws on an unknown name so a typo never silently\n * picks a different engine.\n */\nexport function setImageSettings(settings: ImageSettings): void {\n  configuredEngine = resolveImageEngine(settings.engine ?? process.env[IMAGE_ENGINE_ENV]);\n  configuredThreads = settings.threads;\n}\n\n/** What the last {@link setImageSettings} resolved, without consulting the environment. */\nexport function appliedImageSettings(): {\n  engine: ImageEngine | undefined;\n  threads: number | undefined;\n} {\n  return { engine: configuredEngine, threads: configuredThreads };\n}\n\n/** The engine in effect: the configured one, else the environment, else the default. */\nexport function currentImageEngine(): ImageEngine {\n  return configuredEngine ?? resolveImageEngine(process.env[IMAGE_ENGINE_ENV]);\n}\n\n/** The configured thread count, or `undefined` to defer to the environment/default. */\nexport function configuredThreadCount(): number | undefined {\n  return configuredThreads;\n}\n\n/**\n * Load the engine's dependencies now, so a missing `sharp` fails at boot with a clear message\n * instead of on the first diff. The default engine is a hard dependency with nothing to verify,\n * so it returns at once and never delays startup (or the first capture).\n */\nexport async function verifyImageEngine(): Promise<ImageEngine> {\n  const engine = currentImageEngine();\n  if (engine !== DEFAULT_IMAGE_ENGINE) {\n    await loadCodec(engine);\n  }\n  return engine;\n}\n"],"mappings":";;;;;;;AAiBA,IAAI;AACJ,IAAI;;;;;;;AAQJ,SAAgB,iBAAiB,UAA+B;CAC9D,mBAAmB,mBAAmB,SAAS,UAAU,QAAQ,IAAA,0BAAqB;CACtF,oBAAoB,SAAS;AAC/B;;AAGA,SAAgB,uBAGd;CACA,OAAO;EAAE,QAAQ;EAAkB,SAAS;CAAkB;AAChE;;AAGA,SAAgB,qBAAkC;CAChD,OAAO,oBAAoB,mBAAmB,QAAQ,IAAA,0BAAqB;AAC7E;;AAGA,SAAgB,wBAA4C;CAC1D,OAAO;AACT;;;;;;AAOA,eAAsB,oBAA0C;CAC9D,MAAM,SAAS,mBAAmB;CAClC,IAAI,WAAA,SACF,MAAM,UAAU,MAAM;CAExB,OAAO;AACT"}

package/dist/sharp.mjs

@@ -0,0 +1,60 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { isMainThread } from "node:worker_threads";
+//#region src/sharp.ts
+/** The optional native codec: libvips via `sharp`. Several times faster than pngjs on large PNGs. */
+/**
+* Load `sharp` and build the codec. Throws a readable error when the optional peer is missing
+* or has no binary for this platform, so a misconfigured engine fails at boot, not mid-build.
+*/
+async function createSharpCodec() {
+	const sharp = await importSharp();
+	if (!isMainThread) sharp.concurrency(1);
+	return {
+		name: "sharp",
+		decode: async (png) => await decodeWithSharp(sharp, png),
+		encode: async (image) => await encodeWithSharp(sharp, image),
+		downscale: async (png, maxEdge) => await downscaleWithSharp(sharp, png, maxEdge)
+	};
+}
+async function importSharp() {
+	try {
+		return (await import("sharp")).default;
+	} catch (error) {
+		throw new Error("images.engine \"sharp\" needs the optional `sharp` package: install it next to StoryShelf (e.g. `nub add sharp`).", { cause: error });
+	}
+}
+async function decodeWithSharp(sharp, png) {
+	const { data, info } = await sharp(png).ensureAlpha().raw().toBuffer({ resolveWithObject: true });
+	return {
+		width: info.width,
+		height: info.height,
+		data
+	};
+}
+/**
+* Encode RGBA as a PNG. The result is copied: libvips hands back a Buffer over external native
+* memory, which a worker cannot transfer to the pool (`DataCloneError`).
+*/
+async function encodeWithSharp(sharp, { width, height, data }) {
+	const encoded = await sharp(data, { raw: {
+		width,
+		height,
+		channels: 4
+	} }).png().toBuffer();
+	return Buffer.from(encoded);
+}
+async function downscaleWithSharp(sharp, png, maxEdge) {
+	const out = await sharp(png).resize({
+		width: maxEdge,
+		height: maxEdge,
+		fit: "inside",
+		withoutEnlargement: true
+	}).png().toBuffer();
+	return new Uint8Array(out);
+}
+//#endregion
+export { createSharpCodec };
+
+//# sourceMappingURL=sharp.mjs.map

package/dist/sharp.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sharp.mjs","names":[],"sources":["../src/sharp.ts"],"sourcesContent":["/** The optional native codec: libvips via `sharp`. Several times faster than pngjs on large PNGs. */\nimport { isMainThread } from \"node:worker_threads\";\nimport type { ImageCodec, RgbaImage } from \"./codec.ts\";\n\ntype SharpModule = typeof import(\"sharp\");\n\n/**\n * Load `sharp` and build the codec. Throws a readable error when the optional peer is missing\n * or has no binary for this platform, so a misconfigured engine fails at boot, not mid-build.\n */\nexport async function createSharpCodec(): Promise<ImageCodec> {\n  const sharp = await importSharp();\n  if (!isMainThread) {\n    // Each pool worker would otherwise run libvips on a CPU-count thread pool of its own; the pool\n    // already parallelises across workers, so one libvips thread each avoids oversubscription.\n    sharp.concurrency(1);\n  }\n  return {\n    name: \"sharp\",\n    decode: async (png) => await decodeWithSharp(sharp, png),\n    encode: async (image) => await encodeWithSharp(sharp, image),\n    downscale: async (png, maxEdge) => await downscaleWithSharp(sharp, png, maxEdge),\n  };\n}\n\nasync function importSharp(): Promise<SharpModule[\"default\"]> {\n  try {\n    return (await import(\"sharp\")).default;\n  } catch (error) {\n    throw new Error(\n      'images.engine \"sharp\" needs the optional `sharp` package: install it next to StoryShelf (e.g. `nub add sharp`).',\n      { cause: error },\n    );\n  }\n}\n\nasync function decodeWithSharp(sharp: SharpModule[\"default\"], png: Buffer): Promise<RgbaImage> {\n  const { data, info } = await sharp(png).ensureAlpha().raw().toBuffer({ resolveWithObject: true });\n  return { width: info.width, height: info.height, data };\n}\n\n/**\n * Encode RGBA as a PNG. The result is copied: libvips hands back a Buffer over external native\n * memory, which a worker cannot transfer to the pool (`DataCloneError`).\n */\nasync function encodeWithSharp(\n  sharp: SharpModule[\"default\"],\n  { width, height, data }: RgbaImage,\n): Promise<Buffer> {\n  const encoded = await sharp(data, { raw: { width, height, channels: 4 } })\n    .png()\n    .toBuffer();\n  return Buffer.from(encoded);\n}\n\nasync function downscaleWithSharp(\n  sharp: SharpModule[\"default\"],\n  png: Uint8Array,\n  maxEdge: number,\n): Promise<Uint8Array> {\n  const out = await sharp(png)\n    .resize({ width: maxEdge, height: maxEdge, fit: \"inside\", withoutEnlargement: true })\n    .png()\n    .toBuffer();\n  return new Uint8Array(out);\n}\n"],"mappings":";;;;;;;;;;AAUA,eAAsB,mBAAwC;CAC5D,MAAM,QAAQ,MAAM,YAAY;CAChC,IAAI,CAAC,cAGH,MAAM,YAAY,CAAC;CAErB,OAAO;EACL,MAAM;EACN,QAAQ,OAAO,QAAQ,MAAM,gBAAgB,OAAO,GAAG;EACvD,QAAQ,OAAO,UAAU,MAAM,gBAAgB,OAAO,KAAK;EAC3D,WAAW,OAAO,KAAK,YAAY,MAAM,mBAAmB,OAAO,KAAK,OAAO;CACjF;AACF;AAEA,eAAe,cAA+C;CAC5D,IAAI;EACF,QAAQ,MAAM,OAAO,SAAA,CAAU;CACjC,SAAS,OAAO;EACd,MAAM,IAAI,MACR,qHACA,EAAE,OAAO,MAAM,CACjB;CACF;AACF;AAEA,eAAe,gBAAgB,OAA+B,KAAiC;CAC7F,MAAM,EAAE,MAAM,SAAS,MAAM,MAAM,GAAG,CAAC,CAAC,YAAY,CAAC,CAAC,IAAI,CAAC,CAAC,SAAS,EAAE,mBAAmB,KAAK,CAAC;CAChG,OAAO;EAAE,OAAO,KAAK;EAAO,QAAQ,KAAK;EAAQ;CAAK;AACxD;;;;;AAMA,eAAe,gBACb,OACA,EAAE,OAAO,QAAQ,QACA;CACjB,MAAM,UAAU,MAAM,MAAM,MAAM,EAAE,KAAK;EAAE;EAAO;EAAQ,UAAU;CAAE,EAAE,CAAC,CAAC,CACvE,IAAI,CAAC,CACL,SAAS;CACZ,OAAO,OAAO,KAAK,OAAO;AAC5B;AAEA,eAAe,mBACb,OACA,KACA,SACqB;CACrB,MAAM,MAAM,MAAM,MAAM,GAAG,CAAC,CACzB,OAAO;EAAE,OAAO;EAAS,QAAQ;EAAS,KAAK;EAAU,oBAAoB;CAAK,CAAC,CAAC,CACpF,IAAI,CAAC,CACL,SAAS;CACZ,OAAO,IAAI,WAAW,GAAG;AAC3B"}

package/dist/transfer.mjs

@@ -0,0 +1,24 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+//#region src/transfer.ts
+/** Zero-copy hand-off of Buffers across the worker boundary. */
+/**
+* A Uint8Array that may be transferred (detached from the caller) without corrupting anything.
+*
+* A Buffer that spans its whole ArrayBuffer is moved as-is. Pooled slices (small `Buffer`s share
+* one 8 KiB pool) and views over shared memory are copied, since transferring them would detach
+* unrelated data.
+*/
+function toTransferable(buffer) {
+	const { buffer: backing, byteOffset, byteLength } = buffer;
+	return backing instanceof ArrayBuffer && byteOffset === 0 && byteLength === backing.byteLength ? buffer : Uint8Array.from(buffer);
+}
+/** Wrap bytes received from a worker as a Buffer without copying. */
+function fromTransferred(bytes) {
+	return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+}
+//#endregion
+export { fromTransferred, toTransferable };
+
+//# sourceMappingURL=transfer.mjs.map

package/dist/transfer.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"transfer.mjs","names":[],"sources":["../src/transfer.ts"],"sourcesContent":["/** Zero-copy hand-off of Buffers across the worker boundary. */\n\n/**\n * A Uint8Array that may be transferred (detached from the caller) without corrupting anything.\n *\n * A Buffer that spans its whole ArrayBuffer is moved as-is. Pooled slices (small `Buffer`s share\n * one 8 KiB pool) and views over shared memory are copied, since transferring them would detach\n * unrelated data.\n */\nexport function toTransferable(buffer: Uint8Array): Uint8Array {\n  const { buffer: backing, byteOffset, byteLength } = buffer;\n  const owns =\n    backing instanceof ArrayBuffer && byteOffset === 0 && byteLength === backing.byteLength;\n  return owns ? buffer : Uint8Array.from(buffer);\n}\n\n/** Wrap bytes received from a worker as a Buffer without copying. */\nexport function fromTransferred(bytes: Uint8Array): Buffer {\n  return Buffer.from(bytes.buffer, bytes.byteOffset, bytes.byteLength);\n}\n"],"mappings":";;;;;;;;;;;;AASA,SAAgB,eAAe,QAAgC;CAC7D,MAAM,EAAE,QAAQ,SAAS,YAAY,eAAe;CAGpD,OADE,mBAAmB,eAAe,eAAe,KAAK,eAAe,QAAQ,aACjE,SAAS,WAAW,KAAK,MAAM;AAC/C;;AAGA,SAAgB,gBAAgB,OAA2B;CACzD,OAAO,OAAO,KAAK,MAAM,QAAQ,MAAM,YAAY,MAAM,UAAU;AACrE"}

package/dist/worker.d.mts

@@ -0,0 +1,2 @@
+import __tsdown_shims_path from 'node:path';
+import __tsdown_shims_url from 'node:url';

package/dist/worker.mjs

@@ -0,0 +1,47 @@
+import "node:path";
+import "node:url";
+import.meta.url;
+import { loadCodec } from "./codecs.mjs";
+import { diffImages } from "./engine.mjs";
+import { fromTransferred, toTransferable } from "./transfer.mjs";
+import { parentPort } from "node:worker_threads";
+//#region src/worker.ts
+/** Worker-thread entry for the diff pool: runs the same `diffImages` as the in-thread path. */
+const port = parentPort;
+async function handle(request) {
+	if (!port) return;
+	try {
+		const result = await diffImages(fromTransferred(request.baseline), fromTransferred(request.current), request.options, await loadCodec(request.engine));
+		const diffImage = result.diffImage ? toTransferable(result.diffImage) : null;
+		const response = {
+			type: "result",
+			id: request.id,
+			result: {
+				...result,
+				diffImage
+			}
+		};
+		port.postMessage(response, diffImage ? [diffImage.buffer] : []);
+	} catch (error) {
+		const cause = error instanceof Error ? error : new Error(String(error));
+		const response = {
+			type: "error",
+			id: request.id,
+			name: cause.name,
+			message: cause.message
+		};
+		port.postMessage(response);
+	}
+}
+port?.on("message", (request) => {
+	handle(request).catch((error) => {
+		setImmediate(() => {
+			throw error;
+		});
+	});
+});
+port?.postMessage({ type: "ready" });
+//#endregion
+export {};
+
+//# sourceMappingURL=worker.mjs.map

package/dist/worker.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker.mjs","names":[],"sources":["../src/worker.ts"],"sourcesContent":["/** Worker-thread entry for the diff pool: runs the same `diffImages` as the in-thread path. */\nimport { parentPort } from \"node:worker_threads\";\nimport { loadCodec } from \"./codecs.ts\";\nimport { diffImages } from \"./engine.ts\";\nimport type { DiffRequest, DiffResponse } from \"./protocol.ts\";\nimport { fromTransferred, toTransferable } from \"./transfer.ts\";\n\nconst port = parentPort;\n\nasync function handle(request: DiffRequest): Promise<void> {\n  if (!port) {\n    return;\n  }\n  try {\n    const result = await diffImages(\n      fromTransferred(request.baseline),\n      fromTransferred(request.current),\n      request.options,\n      await loadCodec(request.engine),\n    );\n    const diffImage = result.diffImage ? toTransferable(result.diffImage) : null;\n    const response: DiffResponse = {\n      type: \"result\",\n      id: request.id,\n      result: { ...result, diffImage },\n    };\n    port.postMessage(response, diffImage ? [diffImage.buffer as ArrayBuffer] : []);\n  } catch (error) {\n    const cause = error instanceof Error ? error : new Error(String(error));\n    const response: DiffResponse = {\n      type: \"error\",\n      id: request.id,\n      name: cause.name,\n      message: cause.message,\n    };\n    port.postMessage(response);\n  }\n}\n\nport?.on(\"message\", (request: DiffRequest) => {\n  handle(request).catch((error: unknown) => {\n    // Not even the error reply could be posted. Throw outside the promise so the thread dies with\n    // an 'error' event, which rejects the pool's task, instead of leaving it waiting forever.\n    setImmediate(() => {\n      throw error;\n    });\n  });\n});\nport?.postMessage({ type: \"ready\" } satisfies DiffResponse);\n"],"mappings":";;;;;;;;;AAOA,MAAM,OAAO;AAEb,eAAe,OAAO,SAAqC;CACzD,IAAI,CAAC,MACH;CAEF,IAAI;EACF,MAAM,SAAS,MAAM,WACnB,gBAAgB,QAAQ,QAAQ,GAChC,gBAAgB,QAAQ,OAAO,GAC/B,QAAQ,SACR,MAAM,UAAU,QAAQ,MAAM,CAChC;EACA,MAAM,YAAY,OAAO,YAAY,eAAe,OAAO,SAAS,IAAI;EACxE,MAAM,WAAyB;GAC7B,MAAM;GACN,IAAI,QAAQ;GACZ,QAAQ;IAAE,GAAG;IAAQ;GAAU;EACjC;EACA,KAAK,YAAY,UAAU,YAAY,CAAC,UAAU,MAAqB,IAAI,CAAC,CAAC;CAC/E,SAAS,OAAO;EACd,MAAM,QAAQ,iBAAiB,QAAQ,QAAQ,IAAI,MAAM,OAAO,KAAK,CAAC;EACtE,MAAM,WAAyB;GAC7B,MAAM;GACN,IAAI,QAAQ;GACZ,MAAM,MAAM;GACZ,SAAS,MAAM;EACjB;EACA,KAAK,YAAY,QAAQ;CAC3B;AACF;AAEA,MAAM,GAAG,YAAY,YAAyB;CAC5C,OAAO,OAAO,CAAC,CAAC,OAAO,UAAmB;EAGxC,mBAAmB;GACjB,MAAM;EACR,CAAC;CACH,CAAC;AACH,CAAC;AACD,MAAM,YAAY,EAAE,MAAM,QAAQ,CAAwB"}

package/package.json

@@ -1,6 +1,94 @@
 {
   "name": "@storyshelf/image",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.6.2",
+  "description": "StoryShelf image engine: pixel diffing, overlay rendering and thumbnails on a worker-thread pool, with pngjs (default) or sharp codecs.",
+  "keywords": [
+    "diff",
+    "image",
+    "pixelmatch",
+    "sharp",
+    "storybook",
+    "visual-testing"
+  ],
+  "homepage": "https://github.com/GuptaSiddhant/StoryShelf#readme",
+  "bugs": {
+    "url": "https://github.com/GuptaSiddhant/StoryShelf/issues"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Siddhant Gupta",
+    "url": "https://guptasiddhant.com"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GuptaSiddhant/StoryShelf.git",
+    "directory": "packages/image"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.mts",
+  "exports": {
+    ".": {
+      "source": "./src/index.ts",
+      "default": "./dist/index.mjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "exports": {
+      ".": "./dist/index.mjs",
+      "./package.json": "./package.json"
+    },
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown -w",
+    "fmt": "oxfmt ./src",
+    "lint": "oxlint --type-aware --type-check ./src",
+    "prepublishOnly": "nub run build",
+    "test": "vitest run",
+    "test:coverage": "vitest run --coverage",
+    "bench": "node --conditions=source bench/run.ts",
+    "test:flake": "vitest run --repeats=10 --maxWorkers=1 --no-file-parallelism src/pool.test.ts"
+  },
+  "dependencies": {
+    "pixelmatch": "^7.1.0",
+    "pngjs": "^7.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^26.0.0",
+    "@types/pngjs": "^6.0.5",
+    "@vitest/coverage-v8": "^4.0.0",
+    "oxfmt": "^0.65.0",
+    "oxlint": "^1.80.0",
+    "oxlint-tsgolint": "^7.0.2001",
+    "sharp": "^0.35.5",
+    "tsdown": "^0.22.14",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.0"
+  },
+  "peerDependencies": {
+    "sharp": ">=0.34.0"
+  },
+  "peerDependenciesMeta": {
+    "sharp": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=24"
+  },
+  "jsr": {
+    "runtimeCompat": {
+      "node": true,
+      "deno": true,
+      "bun": true,
+      "workerd": false,
+      "browser": false
+    }
+  }
+}