visual-regression-compare 1.0.0-beta.0 → 1.0.0-beta.1

package/dist/comparer.d.ts

@@ -1,5 +1,5 @@
 import { ManifestWriter, type Manifest, type ManifestEntry, type ManifestHeaderInput } from 'visual-regression-manifest';
-import type { CompareInput, DiffEngine, EngineOptions, Layout, Limits, Matcher, OnMissingBaseline, Plugin, Reporter, SizeMismatch, Store, UpdatePolicy } from './types';
+import type { CompareInput, CompareResult, DiffEngine, EngineOptions, ImagePart, Layout, Limits, Matcher, OnMissingBaseline, Plugin, Reporter, SizeMismatch, Store, UpdatePolicy } from './types';
 export declare const TOOL_NAME = "visual-regression-compare";
 export type ComparerOptions = {
     /**
@@ -21,6 +21,12 @@ export type ComparerOptions = {
     layout?: Layout;
     matcher?: Matcher;
     manifest: {
+        /**
+         * A manifest writer the caller owns, for a runner that builds the header
+         * (CI, run and reproduction metadata, one file per worker) itself. The
+         * other keys of this object are then ignored.
+         */
+        writer?: ManifestWriter;
         /** Where the manifest is written; default `visual-regression-manifest.compare.json` in the project root. */
         path?: string;
         /** Absolute path every manifest path is relative to; default the working directory. */
@@ -33,7 +39,12 @@ export type ComparerOptions = {
     };
     plugins?: Plugin[];
     reporters?: Reporter[];
-    /** Worker threads for decoding and comparing; default the CPU count. */
+    /**
+     * Worker threads for decoding and comparing, and parallel reads in
+     * `compareAll`. Default `1`: everything runs in the calling thread, which is
+     * what a runner adapter wants (its own workers already use the CPUs). The
+     * command line passes the CPU count.
+     */
     concurrency?: number;
     /** The built worker module; found next to this file in the published package. */
     workerFile?: URL | string;
@@ -48,15 +59,28 @@ export declare class Comparer {
     private readonly pool;
     private readonly registry;
     private readonly ready;
-    private engine;
+    private readonly engines;
     private closed;
     constructor(options: ComparerOptions);
+    private createWriter;
+    /** The comparer's settings with the overrides of one call applied. */
+    private settings;
     /** The engine as the main thread knows it: for its name and metric, and to run it when it is an object or came from a plugin. */
     private resolveEngine;
     private measure;
     /** Compares one screenshot, decides, writes the files and records the manifest entry. */
     compareImage(input: CompareInput): Promise<ManifestEntry>;
+    /**
+     * `compareImage` that can also hand back the compared images as PNG bytes,
+     * for a runner that shows them (a review UI). `include` names the parts;
+     * the diff is encoded anyway, the other two cost nothing when the sizes
+     * match.
+     */
+    compare(input: CompareInput, { include }?: {
+        include?: ImagePart[];
+    }): Promise<CompareResult>;
     private compareAt;
+    private compareWith;
     /** `maxDiffRatio` of the entry: the stricter of the ratio and the pixel count, for the size actually compared. */
     private limitFor;
     private decide;

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export { Comparer, TOOL_NAME, createComparer, type ComparerOptions, } from './comparer';
 export { loadEngine, pixelmatchEngine, BUILT_IN_ENGINES, type PixelmatchOptions, } from './engines';
-export { fsStore, type FsStoreOptions } from './store';
+export { fileStore, fsStore, type FsStoreOptions } from './store';
 export { manifestLayout, samePathMatcher, sanitizeName, templateMatcher, } from './layout';
 export { approve, type ApproveOptions, type ApproveResult, type Skipped, } from './approve';
 export { consoleReporter, ctrfReporter, githubSummaryReporter, parseReporters, summaryMarkdown, } from './reporters';

package/dist/index.js

@@ -1,9 +1,9 @@
 // src/comparer.ts
-import fs from "fs";
-import os from "os";
-import path2 from "path";
+import fs2 from "fs";
+import path3 from "path";
 import {
   ManifestWriter,
+  IMAGE_SUFFIX as IMAGE_SUFFIX2,
   getManifestFileName,
   maxRatioFrom
 } from "visual-regression-manifest";
@@ -144,13 +144,18 @@ var runCompare = async (job, engine) => {
     );
   }
   const { diff, ...result } = await engine.compare(baseline, actual);
+  const compared = (part, image) => job.include?.includes(part) ? {
+    [`${part}Png`]: resized ? encodePng(image) : job[part]
+  } : {};
   return {
     kind: "compared",
     baselineSize,
     actualSize,
     ...resized && { resized },
     ...result,
-    ...diff && { diffPng: encodePng(diff) }
+    ...diff && { diffPng: encodePng(diff) },
+    ...compared("baseline", baseline),
+    ...compared("actual", actual)
   };
 };
 var runJob = async (job) => runCompare(
@@ -272,6 +277,103 @@ var templateMatcher = (template) => ({
   }
 });
 
+// src/store.ts
+import fs from "fs";
+import path2 from "path";
+import { isSafeRelativePath } from "visual-regression-manifest";
+var GENERATED = /\.(actual|diff)\.png$/;
+var fsStore = ({
+  baselineDir,
+  actualDir,
+  diffDir
+}) => {
+  const roots = {
+    baseline: baselineDir,
+    incoming: actualDir,
+    actual: diffDir ?? baselineDir,
+    diff: diffDir ?? baselineDir
+  };
+  const rootOf = (kind) => {
+    const root = roots[kind];
+    if (!root) throw new Error(`The store has no directory for ${kind} images`);
+    return path2.resolve(root);
+  };
+  const locate = ({ kind, path: relative }) => {
+    if (relative !== "" && !isSafeRelativePath(relative)) {
+      throw new Error(`Unsafe image path ${JSON.stringify(relative)}`);
+    }
+    return path2.join(rootOf(kind), relative);
+  };
+  return {
+    locate,
+    async read(ref) {
+      try {
+        return await fs.promises.readFile(locate(ref));
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      }
+    },
+    async write(ref, bytes) {
+      const file = locate(ref);
+      await fs.promises.mkdir(path2.dirname(file), { recursive: true });
+      await fs.promises.writeFile(file, bytes);
+    },
+    async remove(ref) {
+      await fs.promises.rm(locate(ref), { force: true });
+    },
+    async *list(kind) {
+      const root = rootOf(kind);
+      const found = [];
+      const walk = async (dir, prefix) => {
+        for (const dirent of await fs.promises.readdir(dir, {
+          withFileTypes: true
+        })) {
+          const relative = prefix ? `${prefix}/${dirent.name}` : dirent.name;
+          if (dirent.isDirectory()) {
+            if (dirent.name !== "node_modules" && dirent.name !== ".git") {
+              await walk(path2.join(dir, dirent.name), relative);
+            }
+          } else if (dirent.isFile() && dirent.name.endsWith(".png") && !GENERATED.test(dirent.name)) {
+            found.push(relative);
+          }
+        }
+      };
+      await walk(root, "");
+      for (const relative of found.sort()) yield { kind, path: relative };
+    }
+  };
+};
+var fileStore = (files) => {
+  const locate = ({ kind }) => {
+    if (kind === "incoming") {
+      throw new Error("A file store has no incoming images");
+    }
+    return files[kind];
+  };
+  return {
+    locate,
+    async read(ref) {
+      try {
+        return await fs.promises.readFile(locate(ref));
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      }
+    },
+    async write(ref, bytes) {
+      const file = locate(ref);
+      await fs.promises.mkdir(path2.dirname(file), { recursive: true });
+      await fs.promises.writeFile(file, bytes);
+    },
+    async remove(ref) {
+      await fs.promises.rm(locate(ref), { force: true });
+    },
+    async *list() {
+    }
+  };
+};
+
 // src/plugins.ts
 var createRegistry = (initial) => {
   const registry = {
@@ -306,7 +408,7 @@ var createRegistry = (initial) => {
 var TOOL_NAME = "visual-regression-compare";
 var packageVersion = () => {
   try {
-    const text = fs.readFileSync(
+    const text = fs2.readFileSync(
       new URL("../package.json", import.meta.url),
       "utf8"
     );
@@ -315,15 +417,21 @@ var packageVersion = () => {
     return void 0;
   }
 };
+var withDefaults = ({ baseline, actual, diff }) => {
+  const stem = baseline.replace(/\.png$/, "");
+  return {
+    baseline,
+    actual: actual ?? `${stem}${IMAGE_SUFFIX2.actual}.png`,
+    diff: diff ?? `${stem}${IMAGE_SUFFIX2.diff}.png`
+  };
+};
 var DEFAULT_WORKER = new URL("./worker.js", import.meta.url);
 var percent = (ratio) => `${Number((ratio * 100).toPrecision(3))}%`;
 var sizeText = ({ width, height }) => `${width}x${height}`;
 var Comparer = class {
   constructor(options) {
     this.options = options;
-    this.projectRoot = path2.resolve(
-      options.manifest.projectRoot ?? process.cwd()
-    );
+    this.projectRoot = options.manifest.writer ? options.manifest.writer.projectRoot : path3.resolve(options.manifest.projectRoot ?? process.cwd());
     this.registry = createRegistry({
       store: options.store,
       layout: options.layout ?? manifestLayout(),
@@ -334,9 +442,27 @@ var Comparer = class {
     this.layout = () => this.registry.layout;
     this.matcher = () => this.registry.matcher;
     this.ready = this.registry.setup(options.plugins ?? []);
-    const manifestPath = options.manifest.path ?? path2.join(this.projectRoot, getManifestFileName("compare"));
-    this.writer = new ManifestWriter(
-      path2.resolve(this.projectRoot, manifestPath),
+    this.writer = options.manifest.writer ?? this.createWriter(options);
+    this.pool = new WorkerPool(
+      options.concurrency ?? 1,
+      options.workerFile ?? DEFAULT_WORKER
+    );
+  }
+  options;
+  writer;
+  projectRoot;
+  store;
+  layout;
+  matcher;
+  pool;
+  registry;
+  ready;
+  engines = /* @__PURE__ */ new Map();
+  closed = false;
+  createWriter(options) {
+    const manifestPath = options.manifest.path ?? path3.join(this.projectRoot, getManifestFileName("compare"));
+    return new ManifestWriter(
+      path3.resolve(this.projectRoot, manifestPath),
       {
         projectRoot: this.projectRoot,
         tool: options.manifest.tool ?? {
@@ -355,73 +481,106 @@ var Comparer = class {
       },
       { writeDelayMs: 200 }
     );
-    this.pool = new WorkerPool(
-      options.concurrency ?? os.cpus().length,
-      options.workerFile ?? DEFAULT_WORKER
-    );
   }
-  options;
-  writer;
-  projectRoot;
-  store;
-  layout;
-  matcher;
-  pool;
-  registry;
-  ready;
-  engine;
-  closed = false;
+  /** The comparer's settings with the overrides of one call applied. */
+  settings(call = {}) {
+    const o = this.options;
+    return {
+      limits: call.limits ?? o.limits ?? {},
+      engineOptions: { ...o.engineOptions, ...call.engineOptions },
+      update: call.update ?? o.update ?? "none",
+      onMissingBaseline: call.onMissingBaseline ?? o.onMissingBaseline ?? "fail",
+      onSizeMismatch: call.onSizeMismatch ?? o.onSizeMismatch ?? "fail"
+    };
+  }
   /** The engine as the main thread knows it: for its name and metric, and to run it when it is an object or came from a plugin. */
-  resolveEngine() {
-    this.engine ??= (async () => {
-      await this.ready;
-      const { engine = "pixelmatch", engineOptions = {} } = this.options;
-      if (typeof engine === "object") return engine;
-      const registered = this.registry.engines.get(engine);
-      if (typeof registered === "object") return registered;
-      if (typeof registered === "function") return registered(engineOptions);
-      return loadEngine(engine, engineOptions);
-    })();
-    return this.engine;
-  }
-  async measure(baseline, actual, engine) {
-    const { engine: spec = "pixelmatch", engineOptions } = this.options;
-    const inMainThread = typeof spec === "object" || this.registry.engines.has(spec);
-    const onSizeMismatch = this.options.onSizeMismatch ?? "fail";
-    if (inMainThread) {
-      return runCompare({ baseline, actual, onSizeMismatch }, engine);
+  resolveEngine(engineOptions) {
+    const key = JSON.stringify(engineOptions);
+    let engine = this.engines.get(key);
+    if (!engine) {
+      engine = (async () => {
+        await this.ready;
+        const { engine: spec = "pixelmatch" } = this.options;
+        if (typeof spec === "object") return spec;
+        const registered = this.registry.engines.get(spec);
+        if (typeof registered === "object") return registered;
+        if (typeof registered === "function") return registered(engineOptions);
+        return loadEngine(spec, engineOptions);
+      })();
+      this.engines.set(key, engine);
     }
-    return this.pool.run({
+    return engine;
+  }
+  async measure(baseline, actual, engine, cfg, include) {
+    const { engine: spec = "pixelmatch" } = this.options;
+    const inMainThread = typeof spec === "object" || this.registry.engines.has(spec);
+    const job = {
       baseline,
       actual,
-      onSizeMismatch,
-      engine: { id: spec, options: engineOptions, cwd: process.cwd() }
+      onSizeMismatch: cfg.onSizeMismatch,
+      include
+    };
+    if (inMainThread) return runCompare(job, engine);
+    return this.pool.run({
+      ...job,
+      engine: { id: spec, options: cfg.engineOptions, cwd: process.cwd() }
     });
   }
   /** Compares one screenshot, decides, writes the files and records the manifest entry. */
   async compareImage(input) {
+    return (await this.compare(input)).entry;
+  }
+  /**
+   * `compareImage` that can also hand back the compared images as PNG bytes,
+   * for a runner that shows them (a review UI). `include` names the parts;
+   * the diff is encoded anyway, the other two cost nothing when the sizes
+   * match.
+   */
+  async compare(input, { include = [] } = {}) {
     await this.ready;
     const name = sanitizeName(input.name);
+    if (input.files) {
+      return this.compareAt(
+        input,
+        name,
+        { kind: "baseline", path: "baseline" },
+        include
+      );
+    }
     const baseline = {
       kind: "baseline",
       path: this.layout().paths(name).baseline
     };
-    return this.compareAt(input, name, baseline);
+    return this.compareAt(input, name, baseline, include);
+  }
+  compareAt(input, name, baselineRef, include) {
+    const store = input.files ? fileStore(withDefaults(input.files)) : this.store();
+    const names = input.files ? { actual: "actual", diff: "diff" } : this.layout().paths(name);
+    return this.compareWith(input, name, baselineRef, include, store, names);
   }
-  async compareAt(input, name, baselineRef) {
+  async compareWith(input, name, baselineRef, include, store, names) {
+    const cfg = this.settings(input.options);
     const started = Date.now();
     const ctx = { name, input };
     for (const fn of this.registry.hooks.beforeCompare) await fn(ctx);
-    const engine = await this.resolveEngine();
-    const baselineBytes = await this.store().read(baselineRef);
+    const engine = await this.resolveEngine(cfg.engineOptions);
+    const baselineBytes = await store.read(baselineRef);
     let measurement;
     let diffPng;
+    const images = {};
     if (baselineBytes === null) {
       measurement = { kind: "missing-baseline" };
+      if (include.includes("actual")) images.actual = input.actual;
     } else {
       let job;
       try {
-        job = await this.measure(baselineBytes, input.actual, engine);
+        job = await this.measure(
+          baselineBytes,
+          input.actual,
+          engine,
+          cfg,
+          include
+        );
       } catch (error) {
         throw new Error(`${name}: ${error.message}`, {
           cause: error
@@ -439,21 +598,25 @@ var Comparer = class {
         }
       };
       diffPng = job.kind === "compared" ? job.diffPng : void 0;
+      if (job.kind === "compared") {
+        if (include.includes("diff") && diffPng) images.diff = diffPng;
+        if (job.baselinePng) images.baseline = job.baselinePng;
+        if (job.actualPng) images.actual = job.actualPng;
+      }
     }
     for (const fn of this.registry.hooks.afterCompare)
       await fn(ctx, measurement);
-    const limit = this.limitFor(measurement);
-    let decision = this.decide(measurement, limit);
+    const limit = this.limitFor(measurement, cfg);
+    let decision = this.decide(measurement, limit, cfg);
     for (const fn of this.registry.hooks.decide) {
       decision = await fn(ctx, decision);
     }
-    const names = this.layout().paths(name);
     const refs = {
       actual: { kind: "actual", path: names.actual },
       diff: { kind: "diff", path: names.diff }
     };
-    await this.store().remove(refs.actual);
-    await this.store().remove(refs.diff);
+    await store.remove(refs.actual);
+    await store.remove(refs.diff);
     let plan = { write: [] };
     const status = decision.status;
     if (status === "failed" || status === "missing-baseline") {
@@ -464,9 +627,10 @@ var Comparer = class {
     }
     for (const fn of this.registry.hooks.beforeWrite)
       plan = await fn(ctx, plan);
-    for (const { ref, bytes } of plan.write)
-      await this.store().write(ref, bytes);
+    for (const { ref, bytes } of plan.write) await store.write(ref, bytes);
     const entry = this.record(
+      store,
+      cfg,
       input,
       name,
       baselineRef,
@@ -479,10 +643,10 @@ var Comparer = class {
     );
     for (const reporter of this.registry.reporters)
       await reporter.onEntry?.(entry);
-    return entry;
+    return { entry, images };
   }
   /** `maxDiffRatio` of the entry: the stricter of the ratio and the pixel count, for the size actually compared. */
-  limitFor(measurement) {
+  limitFor(measurement, cfg) {
     if (measurement.kind !== "compared") return void 0;
     const { baselineSize: b, actualSize: a, resized } = measurement;
     const size = resized === "pad" ? {
@@ -492,11 +656,10 @@ var Comparer = class {
       width: Math.min(a.width, b.width),
       height: Math.min(a.height, b.height)
     } : a;
-    const { maxDiffRatio, maxDiffPixels } = this.options.limits ?? {};
+    const { maxDiffRatio, maxDiffPixels } = cfg.limits;
     return maxRatioFrom({ ratio: maxDiffRatio, pixels: maxDiffPixels }, size) ?? 0;
   }
-  decide(measurement, limit) {
-    const { update = "none", onMissingBaseline = "fail" } = this.options;
+  decide(measurement, limit, { update, onMissingBaseline }) {
     if (measurement.kind === "missing-baseline") {
       return onMissingBaseline === "create" ? {
         status: "created",
@@ -534,16 +697,15 @@ var Comparer = class {
       message: `${counts}; the limit is ${percent(limit ?? 0)}.${resized}`
     };
   }
-  record(input, name, baselineRef, refs, measurement, decision, limit, engine, duration) {
-    const store = this.store();
-    const where = (ref) => store.locate(ref) ?? path2.join(this.projectRoot, ref.path);
+  record(store, cfg, input, name, baselineRef, refs, measurement, decision, limit, engine, duration) {
+    const where = (ref) => store.locate(ref) ?? path3.join(this.projectRoot, ref.path);
     const status = decision.status;
     const compared = measurement.kind === "compared" ? measurement : void 0;
     const sized = measurement.kind !== "missing-baseline" ? measurement : void 0;
-    const { maxDiffRatio = 0 } = this.options.limits ?? {};
-    const baselineRoot = path2.relative(
+    const { maxDiffRatio = 0 } = cfg.limits;
+    const baselineRoot = path3.relative(
       this.projectRoot,
-      where({ kind: "baseline", path: "" })
+      input.files ? path3.dirname(input.files.baseline) : where({ kind: "baseline", path: "" })
     );
     const meta = {
       engine: engine.name,
@@ -578,12 +740,13 @@ var Comparer = class {
       viewport: input.viewport,
       variant: input.variant ?? this.options.manifest.variant,
       extra: { ...input.extra, visualRegressionCompare: meta },
-      options: {
+      ...input.entry,
+      options: input.entry?.options ?? {
         imagesPath: `${baselineRoot || "."}/{name}.png`,
         maxDiffRatio,
-        diffConfig: { engine: engine.name, ...this.options.engineOptions },
-        createMissingImages: this.options.onMissingBaseline === "create",
-        updateImages: this.options.update === "failures-only" ? "failures-only" : this.options.update === "all"
+        diffConfig: { engine: engine.name, ...cfg.engineOptions },
+        createMissingImages: cfg.onMissingBaseline === "create",
+        updateImages: cfg.update === "failures-only" ? "failures-only" : cfg.update === "all"
       },
       duration: input.duration ?? duration
     });
@@ -594,7 +757,7 @@ var Comparer = class {
     const refs = [];
     for await (const ref of this.store().list("incoming")) refs.push(ref);
     const queue = [...refs];
-    const workers = Math.max(1, this.options.concurrency ?? os.cpus().length);
+    const workers = Math.max(1, this.options.concurrency ?? 1);
     const failures = [];
     await Promise.all(
       Array.from({ length: Math.min(workers, queue.length) }, async () => {
@@ -622,7 +785,7 @@ ${failures.map((f) => `  ${f.message}`).join("\n")}`
     const name = this.layout().nameOf("baseline", baselineRef.path) ?? baselineRef.path.replace(/\.png$/, "");
     const actual = await this.store().read(incoming);
     if (actual === null) return;
-    await this.compareAt({ name, actual }, name, baselineRef);
+    await this.compareAt({ name, actual }, name, baselineRef, []);
   }
   /** Flushes the manifest and ends the reporters. Call once, after the last comparison. */
   async close() {
@@ -642,74 +805,6 @@ ${failures.map((f) => `  ${f.message}`).join("\n")}`
 };
 var createComparer = (options) => new Comparer(options);
 
-// src/store.ts
-import fs2 from "fs";
-import path3 from "path";
-import { isSafeRelativePath } from "visual-regression-manifest";
-var GENERATED = /\.(actual|diff)\.png$/;
-var fsStore = ({
-  baselineDir,
-  actualDir,
-  diffDir
-}) => {
-  const roots = {
-    baseline: baselineDir,
-    incoming: actualDir,
-    actual: diffDir ?? baselineDir,
-    diff: diffDir ?? baselineDir
-  };
-  const rootOf = (kind) => {
-    const root = roots[kind];
-    if (!root) throw new Error(`The store has no directory for ${kind} images`);
-    return path3.resolve(root);
-  };
-  const locate = ({ kind, path: relative }) => {
-    if (relative !== "" && !isSafeRelativePath(relative)) {
-      throw new Error(`Unsafe image path ${JSON.stringify(relative)}`);
-    }
-    return path3.join(rootOf(kind), relative);
-  };
-  return {
-    locate,
-    async read(ref) {
-      try {
-        return await fs2.promises.readFile(locate(ref));
-      } catch (error) {
-        if (error.code === "ENOENT") return null;
-        throw error;
-      }
-    },
-    async write(ref, bytes) {
-      const file = locate(ref);
-      await fs2.promises.mkdir(path3.dirname(file), { recursive: true });
-      await fs2.promises.writeFile(file, bytes);
-    },
-    async remove(ref) {
-      await fs2.promises.rm(locate(ref), { force: true });
-    },
-    async *list(kind) {
-      const root = rootOf(kind);
-      const found = [];
-      const walk = async (dir, prefix) => {
-        for (const dirent of await fs2.promises.readdir(dir, {
-          withFileTypes: true
-        })) {
-          const relative = prefix ? `${prefix}/${dirent.name}` : dirent.name;
-          if (dirent.isDirectory()) {
-            if (dirent.name !== "node_modules" && dirent.name !== ".git") {
-              await walk(path3.join(dir, dirent.name), relative);
-            }
-          } else if (dirent.isFile() && dirent.name.endsWith(".png") && !GENERATED.test(dirent.name)) {
-            found.push(relative);
-          }
-        }
-      };
-      await walk(root, "");
-      for (const relative of found.sort()) yield { kind, path: relative };
-    }
-  };
-};
-
 // src/approve.ts
 import { createHash } from "crypto";
 import fs3 from "fs";
@@ -935,6 +1030,7 @@ export {
   ctrfReporter,
   decodePng,
   encodePng,
+  fileStore,
   fsStore,
   githubSummaryReporter,
   loadEngine,

package/dist/job.d.ts

@@ -1,9 +1,11 @@
-import type { DiffEngine, EngineOptions, EngineResult, SizeMismatch } from './types';
+import type { DiffEngine, EngineOptions, EngineResult, ImagePart, SizeMismatch } from './types';
 /** The CPU-bound part of one comparison: plain data in, plain data out, so it can run in a worker. */
 export type CompareJob = {
     baseline: Uint8Array;
     actual: Uint8Array;
     onSizeMismatch: SizeMismatch;
+    /** Images to hand back besides the measurement (`diff` is always encoded; this decides whether it is sent). */
+    include?: ImagePart[];
     /** An engine id (see `loadEngine`), so a worker can load it itself. */
     engine: {
         id: string;
@@ -24,13 +26,16 @@ export type JobResult = {
     diffRatio: number;
     /** The diff image, already encoded. */
     diffPng?: Uint8Array;
+    /** The compared baseline and actual, encoded, when the job asked for them. */
+    baselinePng?: Uint8Array;
+    actualPng?: Uint8Array;
     score?: EngineResult['score'];
 } | {
     kind: 'size-mismatch';
     baselineSize: Size;
     actualSize: Size;
 };
-export declare const runCompare: (job: Pick<CompareJob, "baseline" | "actual" | "onSizeMismatch">, engine: DiffEngine) => Promise<JobResult>;
+export declare const runCompare: (job: Pick<CompareJob, "baseline" | "actual" | "onSizeMismatch" | "include">, engine: DiffEngine) => Promise<JobResult>;
 /** Runs a job in this thread (what a worker does for each message). */
 export declare const runJob: (job: CompareJob) => Promise<JobResult>;
 export {};

package/dist/store.d.ts

@@ -1,4 +1,4 @@
-import type { Store } from './types';
+import type { CompareFiles, Store } from './types';
 export type FsStoreOptions = {
     baselineDir: string;
     /** Where the screenshots to compare are; only the directory call needs it. */
@@ -7,3 +7,8 @@ export type FsStoreOptions = {
     diffDir?: string;
 };
 export declare const fsStore: ({ baselineDir, actualDir, diffDir, }: FsStoreOptions) => Store;
+/**
+ * A store for one screenshot whose files are given as absolute paths (see
+ * `CompareFiles`). Every ref of a kind is that kind's file, whatever its path.
+ */
+export declare const fileStore: (files: Required<CompareFiles>) => Store;