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

package/dist/index.js

@@ -0,0 +1,1044 @@
+// src/comparer.ts
+import fs2 from "fs";
+import path3 from "path";
+import {
+  ManifestWriter,
+  IMAGE_SUFFIX as IMAGE_SUFFIX2,
+  getManifestFileName,
+  maxRatioFrom
+} from "visual-regression-manifest";
+
+// src/engines/index.ts
+import path from "path";
+import { pathToFileURL } from "url";
+
+// src/engines/pixelmatch.ts
+import pixelmatch from "pixelmatch";
+var pixelmatchEngine = ({
+  threshold = 0.1,
+  includeAA = false
+} = {}) => ({
+  name: "pixelmatch",
+  colorMetric: "yiq",
+  colorThreshold: threshold,
+  compare(baseline, actual) {
+    const { width, height } = baseline;
+    const diff = new Uint8ClampedArray(width * height * 4);
+    const diffPixels = pixelmatch(
+      baseline.data,
+      actual.data,
+      diff,
+      width,
+      height,
+      {
+        threshold,
+        includeAA
+      }
+    );
+    const area = width * height;
+    return {
+      diffPixels,
+      diffRatio: area === 0 ? 0 : diffPixels / area,
+      diff: { width, height, data: diff }
+    };
+  }
+});
+var pixelmatchFrom = (options) => pixelmatchEngine(options);
+
+// src/engines/index.ts
+var BUILT_IN = {
+  pixelmatch: pixelmatchFrom
+};
+var BUILT_IN_ENGINES = Object.keys(BUILT_IN);
+var isDiffEngine = (value) => typeof value === "object" && value !== null && typeof value.compare === "function" && typeof value.name === "string";
+var loadEngine = async (id, options = {}, cwd = process.cwd()) => {
+  const builtIn = BUILT_IN[id];
+  if (builtIn) return builtIn(options);
+  const isPath = /^\.{0,2}[\\/]/.test(id) || path.isAbsolute(id);
+  const specifier = isPath ? pathToFileURL(path.resolve(cwd, id)).href : id;
+  let loaded;
+  try {
+    loaded = await import(specifier);
+  } catch (error) {
+    throw new Error(
+      `Cannot load engine "${id}" (built in: ${BUILT_IN_ENGINES.join(", ")}): ${error.message}`,
+      { cause: error }
+    );
+  }
+  const exported = loaded.default;
+  const engine = typeof exported === "function" ? exported(options) : exported;
+  if (!isDiffEngine(engine)) {
+    throw new Error(
+      `Engine "${id}" must default-export a { name, colorMetric, compare } object or a function returning one`
+    );
+  }
+  return engine;
+};
+
+// src/image.ts
+import { PNG } from "pngjs";
+var LFS_POINTER = "version https://git-lfs.github.com/spec/";
+var decodePng = (bytes) => {
+  const head = Buffer.from(bytes.subarray(0, LFS_POINTER.length)).toString(
+    "latin1"
+  );
+  if (head === LFS_POINTER) {
+    throw new Error(
+      "the file is a Git LFS pointer, not an image; run `git lfs pull`"
+    );
+  }
+  const { width, height, data } = PNG.sync.read(Buffer.from(bytes));
+  return { width, height, data: new Uint8ClampedArray(data) };
+};
+var encodePng = ({ width, height, data }) => {
+  const png = new PNG({ width, height });
+  png.data = Buffer.from(data.buffer, data.byteOffset, data.byteLength);
+  return PNG.sync.write(png);
+};
+var resize = (image, width, height) => {
+  const data = new Uint8ClampedArray(width * height * 4);
+  const rows = Math.min(height, image.height);
+  const rowBytes = Math.min(width, image.width) * 4;
+  for (let y = 0; y < rows; y++) {
+    const from = y * image.width * 4;
+    data.set(image.data.subarray(from, from + rowBytes), y * width * 4);
+  }
+  return { width, height, data };
+};
+var padToSame = (a, b) => {
+  const width = Math.max(a.width, b.width);
+  const height = Math.max(a.height, b.height);
+  return [resize(a, width, height), resize(b, width, height)];
+};
+var cropToSame = (a, b) => {
+  const width = Math.min(a.width, b.width);
+  const height = Math.min(a.height, b.height);
+  return [resize(a, width, height), resize(b, width, height)];
+};
+
+// src/job.ts
+var decodeNamed = (which, bytes) => {
+  try {
+    return decodePng(bytes);
+  } catch (error) {
+    throw new Error(`the ${which} image: ${error.message}`, {
+      cause: error
+    });
+  }
+};
+var sizeOf = ({ width, height }) => ({ width, height });
+var runCompare = async (job, engine) => {
+  let baseline = decodeNamed("baseline", job.baseline);
+  let actual = decodeNamed("actual", job.actual);
+  const baselineSize = sizeOf(baseline);
+  const actualSize = sizeOf(actual);
+  let resized;
+  if (baseline.width !== actual.width || baseline.height !== actual.height) {
+    if (job.onSizeMismatch === "fail") {
+      return { kind: "size-mismatch", baselineSize, actualSize };
+    }
+    resized = job.onSizeMismatch;
+    [baseline, actual] = (resized === "pad" ? padToSame : cropToSame)(
+      baseline,
+      actual
+    );
+  }
+  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) },
+    ...compared("baseline", baseline),
+    ...compared("actual", actual)
+  };
+};
+var runJob = async (job) => runCompare(
+  job,
+  await loadEngine(job.engine.id, job.engine.options, job.engine.cwd)
+);
+
+// src/pool.ts
+import { Worker } from "worker_threads";
+var WorkerPool = class {
+  constructor(size, workerFile) {
+    this.size = size;
+    this.workerFile = workerFile;
+  }
+  size;
+  workerFile;
+  idle = [];
+  workers = [];
+  queue = [];
+  running = /* @__PURE__ */ new Map();
+  nextId = 0;
+  current = /* @__PURE__ */ new WeakMap();
+  get threaded() {
+    return this.size > 1 && this.workerFile !== void 0;
+  }
+  run(job) {
+    if (!this.threaded) return runJob(job);
+    return new Promise((resolve, reject) => {
+      this.queue.push({ job, resolve, reject });
+      this.pump();
+    });
+  }
+  pump() {
+    while (this.queue.length > 0) {
+      const worker = this.idle.pop() ?? this.spawn();
+      if (!worker) return;
+      const pending = this.queue.shift();
+      const id = this.nextId++;
+      this.running.set(id, pending);
+      this.current.set(worker, id);
+      worker.postMessage({ id, job: pending.job });
+    }
+  }
+  spawn() {
+    if (this.workers.length >= this.size) return void 0;
+    const worker = new Worker(this.workerFile);
+    this.workers.push(worker);
+    worker.on("message", ({ id, result, error }) => {
+      const pending = this.running.get(id);
+      this.running.delete(id);
+      this.idle.push(worker);
+      if (error !== void 0) pending?.reject(new Error(error));
+      else pending?.resolve(result);
+      this.pump();
+    });
+    const lose = (error) => {
+      for (const list of [this.workers, this.idle]) {
+        const at = list.indexOf(worker);
+        if (at !== -1) list.splice(at, 1);
+      }
+      const id = this.current.get(worker);
+      const pending = id === void 0 ? void 0 : this.running.get(id);
+      if (id !== void 0) this.running.delete(id);
+      pending?.reject(error);
+      this.pump();
+    };
+    worker.on(
+      "exit",
+      (code) => lose(new Error(`A compare worker exited with code ${code}`))
+    );
+    worker.on("error", lose);
+    return worker;
+  }
+  async close() {
+    for (const pending of this.running.values()) {
+      pending.reject(new Error("The compare worker pool was closed"));
+    }
+    this.running.clear();
+    this.queue.length = 0;
+    await Promise.all(this.workers.map((worker) => worker.terminate()));
+    this.workers.length = 0;
+    this.idle.length = 0;
+  }
+};
+
+// src/layout.ts
+import { IMAGE_SUFFIX } from "visual-regression-manifest";
+var sanitizeName = (name) => name.replace(/[\\:*?"<>|\u0000-\u001f]/g, "-").split("/").filter((segment) => segment !== "" && segment !== "." && segment !== "..").map(
+  (segment, _, all) => segment === all[all.length - 1] ? segment.replace(/\.(actual|diff)$/, "-$1") : segment
+).join("/") || "screenshot";
+var manifestLayout = () => ({
+  paths: (name) => ({
+    baseline: `${name}.png`,
+    incoming: `${name}.png`,
+    actual: `${name}${IMAGE_SUFFIX.actual}.png`,
+    diff: `${name}${IMAGE_SUFFIX.diff}.png`
+  }),
+  nameOf(kind, file) {
+    if (!file.endsWith(".png")) return null;
+    const stem = file.slice(0, -".png".length);
+    const suffix = kind === "actual" ? IMAGE_SUFFIX.actual : kind === "diff" ? IMAGE_SUFFIX.diff : "";
+    if (suffix)
+      return stem.endsWith(suffix) ? stem.slice(0, -suffix.length) : null;
+    return stem.endsWith(IMAGE_SUFFIX.actual) || stem.endsWith(IMAGE_SUFFIX.diff) ? null : stem;
+  }
+});
+var samePathMatcher = () => ({
+  baselineFor: (incoming) => ({ kind: "baseline", path: incoming.path })
+});
+var templateMatcher = (template) => ({
+  baselineFor({ path: incoming }) {
+    const slash = incoming.lastIndexOf("/");
+    const dir = slash === -1 ? "" : incoming.slice(0, slash + 1);
+    const name = incoming.slice(slash + 1).replace(/\.png$/, "");
+    return {
+      kind: "baseline",
+      path: template.replaceAll("{dir}", dir).replaceAll("{name}", name).replaceAll("{path}", `${dir}${name}`)
+    };
+  }
+});
+
+// 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 = {
+    ...initial,
+    reporters: [...initial.reporters],
+    engines: /* @__PURE__ */ new Map(),
+    hooks: {
+      beforeCompare: [],
+      afterCompare: [],
+      decide: [],
+      beforeWrite: [],
+      end: []
+    },
+    async setup(plugins) {
+      const api = {
+        addEngine: (name, engine) => registry.engines.set(name, engine),
+        addReporter: (reporter) => registry.reporters.push(reporter),
+        setStore: (store) => registry.store = store,
+        setLayout: (layout) => registry.layout = layout,
+        setMatcher: (matcher) => registry.matcher = matcher,
+        on: ((event, fn) => {
+          registry.hooks[event].push(fn);
+        })
+      };
+      for (const plugin of plugins) await plugin.setup(api);
+    }
+  };
+  return registry;
+};
+
+// src/comparer.ts
+var TOOL_NAME = "visual-regression-compare";
+var packageVersion = () => {
+  try {
+    const text = fs2.readFileSync(
+      new URL("../package.json", import.meta.url),
+      "utf8"
+    );
+    return JSON.parse(text).version;
+  } catch {
+    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 = options.manifest.writer ? options.manifest.writer.projectRoot : path3.resolve(options.manifest.projectRoot ?? process.cwd());
+    this.registry = createRegistry({
+      store: options.store,
+      layout: options.layout ?? manifestLayout(),
+      matcher: options.matcher ?? samePathMatcher(),
+      reporters: options.reporters ?? []
+    });
+    this.store = () => this.registry.store;
+    this.layout = () => this.registry.layout;
+    this.matcher = () => this.registry.matcher;
+    this.ready = this.registry.setup(options.plugins ?? []);
+    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 ?? {
+          name: TOOL_NAME,
+          version: packageVersion()
+        },
+        runner: options.manifest.runner ?? { name: TOOL_NAME },
+        options: {
+          engine: typeof options.engine === "object" ? options.engine.name : options.engine ?? "pixelmatch",
+          engineOptions: options.engineOptions ?? {},
+          limits: options.limits ?? {},
+          onMissingBaseline: options.onMissingBaseline ?? "fail",
+          onSizeMismatch: options.onSizeMismatch ?? "fail",
+          update: options.update ?? "none"
+        }
+      },
+      { writeDelayMs: 200 }
+    );
+  }
+  /** 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(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 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: 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, 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 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(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,
+          cfg,
+          include
+        );
+      } catch (error) {
+        throw new Error(`${name}: ${error.message}`, {
+          cause: error
+        });
+      }
+      measurement = job.kind === "size-mismatch" ? job : {
+        kind: "compared",
+        baselineSize: job.baselineSize,
+        actualSize: job.actualSize,
+        resized: job.resized,
+        result: {
+          diffPixels: job.diffPixels,
+          diffRatio: job.diffRatio,
+          score: job.score
+        }
+      };
+      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, cfg);
+    let decision = this.decide(measurement, limit, cfg);
+    for (const fn of this.registry.hooks.decide) {
+      decision = await fn(ctx, decision);
+    }
+    const refs = {
+      actual: { kind: "actual", path: names.actual },
+      diff: { kind: "diff", path: names.diff }
+    };
+    await store.remove(refs.actual);
+    await store.remove(refs.diff);
+    let plan = { write: [] };
+    const status = decision.status;
+    if (status === "failed" || status === "missing-baseline") {
+      plan.write.push({ ref: refs.actual, bytes: input.actual });
+      if (diffPng) plan.write.push({ ref: refs.diff, bytes: diffPng });
+    } else if (status === "created" || status === "updated" || status === "approved") {
+      plan.write.push({ ref: baselineRef, bytes: input.actual });
+    }
+    for (const fn of this.registry.hooks.beforeWrite)
+      plan = await fn(ctx, plan);
+    for (const { ref, bytes } of plan.write) await store.write(ref, bytes);
+    const entry = this.record(
+      store,
+      cfg,
+      input,
+      name,
+      baselineRef,
+      refs,
+      measurement,
+      decision,
+      limit,
+      engine,
+      Date.now() - started
+    );
+    for (const reporter of this.registry.reporters)
+      await reporter.onEntry?.(entry);
+    return { entry, images };
+  }
+  /** `maxDiffRatio` of the entry: the stricter of the ratio and the pixel count, for the size actually compared. */
+  limitFor(measurement, cfg) {
+    if (measurement.kind !== "compared") return void 0;
+    const { baselineSize: b, actualSize: a, resized } = measurement;
+    const size = resized === "pad" ? {
+      width: Math.max(a.width, b.width),
+      height: Math.max(a.height, b.height)
+    } : resized === "crop" ? {
+      width: Math.min(a.width, b.width),
+      height: Math.min(a.height, b.height)
+    } : a;
+    const { maxDiffRatio, maxDiffPixels } = cfg.limits;
+    return maxRatioFrom({ ratio: maxDiffRatio, pixels: maxDiffPixels }, size) ?? 0;
+  }
+  decide(measurement, limit, { update, onMissingBaseline }) {
+    if (measurement.kind === "missing-baseline") {
+      return onMissingBaseline === "create" ? {
+        status: "created",
+        message: "Baseline image was created from the actual screenshot."
+      } : {
+        status: "missing-baseline",
+        message: "There is no baseline image."
+      };
+    }
+    if (measurement.kind === "size-mismatch") {
+      const message = `The size changed: baseline ${sizeText(measurement.baselineSize)}, actual ${sizeText(measurement.actualSize)}.`;
+      return update === "none" ? { status: "failed", message } : {
+        status: "updated",
+        message: `${message} Baseline image was replaced with the actual screenshot.`
+      };
+    }
+    const { diffPixels, diffRatio } = measurement.result;
+    const passed = diffRatio <= (limit ?? 0);
+    const resized = measurement.resized ? ` Both images were ${measurement.resized === "pad" ? "padded" : "cropped"} to the same size (baseline ${sizeText(measurement.baselineSize)}, actual ${sizeText(measurement.actualSize)}).` : "";
+    const counts = `${diffPixels} pixels (${percent(diffRatio)}) differ`;
+    if (passed && !(update === "all" && diffPixels > 0)) {
+      return {
+        status: "passed",
+        message: diffPixels === 0 ? `Identical to the baseline.${resized}` : `${counts}, within the limit of ${percent(limit ?? 0)}.${resized}`
+      };
+    }
+    if (update !== "none") {
+      return {
+        status: "updated",
+        message: `${counts}. Baseline image was replaced with the actual screenshot.${resized}`
+      };
+    }
+    return {
+      status: "failed",
+      message: `${counts}; the limit is ${percent(limit ?? 0)}.${resized}`
+    };
+  }
+  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 } = cfg.limits;
+    const baselineRoot = path3.relative(
+      this.projectRoot,
+      input.files ? path3.dirname(input.files.baseline) : where({ kind: "baseline", path: "" })
+    );
+    const meta = {
+      engine: engine.name,
+      ...compared && { diffPixels: compared.result.diffPixels },
+      ...compared?.result.score && { score: compared.result.score },
+      ...compared?.resized && { sizeMismatch: compared.resized },
+      ...measurement.kind === "size-mismatch" && {
+        sizeMismatch: "fail",
+        baselineSize: measurement.baselineSize,
+        actualSize: measurement.actualSize
+      },
+      ...decision.extra
+    };
+    return this.writer.record({
+      actualPath: where(refs.actual),
+      baselinePath: where(baselineRef),
+      diffPath: where(refs.diff),
+      name,
+      testFile: input.test?.filePath,
+      titlePath: input.test?.titlePath,
+      retry: input.test?.retry,
+      status,
+      diffRatio: measurement.kind === "size-mismatch" ? 1 : compared?.result.diffRatio,
+      maxDiffRatio: limit ?? maxDiffRatio,
+      colorThreshold: engine.colorThreshold,
+      colorMetric: engine.colorMetric,
+      baselineWritten: status === "created" || status === "updated" || status === "approved",
+      message: decision.message,
+      baselineSize: sized?.baselineSize,
+      actualSize: sized?.actualSize,
+      platform: input.platform ?? this.options.manifest.platform,
+      viewport: input.viewport,
+      variant: input.variant ?? this.options.manifest.variant,
+      extra: { ...input.extra, visualRegressionCompare: meta },
+      ...input.entry,
+      options: input.entry?.options ?? {
+        imagesPath: `${baselineRoot || "."}/{name}.png`,
+        maxDiffRatio,
+        diffConfig: { engine: engine.name, ...cfg.engineOptions },
+        createMissingImages: cfg.onMissingBaseline === "create",
+        updateImages: cfg.update === "failures-only" ? "failures-only" : cfg.update === "all"
+      },
+      duration: input.duration ?? duration
+    });
+  }
+  /** Compares every incoming image of the store against its baseline. */
+  async compareAll() {
+    await this.ready;
+    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 ?? 1);
+    const failures = [];
+    await Promise.all(
+      Array.from({ length: Math.min(workers, queue.length) }, async () => {
+        for (let ref = queue.shift(); ref; ref = queue.shift()) {
+          try {
+            await this.compareIncoming(ref);
+          } catch (error) {
+            failures.push(error);
+          }
+        }
+      })
+    );
+    if (failures.length > 0) {
+      throw new AggregateError(
+        failures,
+        `${failures.length} image${failures.length === 1 ? "" : "s"} could not be compared:
+${failures.map((f) => `  ${f.message}`).join("\n")}`
+      );
+    }
+    return this.writer.toJSON();
+  }
+  async compareIncoming(incoming) {
+    const baselineRef = this.matcher().baselineFor(incoming);
+    if (!baselineRef) return;
+    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, []);
+  }
+  /** Flushes the manifest and ends the reporters. Call once, after the last comparison. */
+  async close() {
+    await this.ready;
+    if (!this.closed) {
+      this.closed = true;
+      this.writer.write();
+      this.writer.flush();
+      await this.pool.close();
+      for (const fn of this.registry.hooks.end) await fn(this.writer.toJSON());
+      for (const reporter of this.registry.reporters) {
+        await reporter.onEnd?.(this.writer.toJSON());
+      }
+    }
+    return this.writer.toJSON();
+  }
+};
+var createComparer = (options) => new Comparer(options);
+
+// src/approve.ts
+import { createHash } from "crypto";
+import fs3 from "fs";
+import path4 from "path";
+import {
+  isSafeRelativePath as isSafeRelativePath2,
+  mergeManifests,
+  projectDirInRepo,
+  readManifestFile,
+  selectEntries,
+  summarize,
+  toRepoPath,
+  writeManifestFile
+} from "visual-regression-manifest";
+var sha256 = (file) => createHash("sha256").update(fs3.readFileSync(file)).digest("hex");
+var locateProject = (manifest, repoRoot) => {
+  if (manifest.ci?.workspace) {
+    return { projectDir: projectDirInRepo(manifest), base: repoRoot };
+  }
+  const relative = path4.relative(repoRoot, manifest.projectRoot).split(path4.sep).join("/");
+  if (relative === "") return { projectDir: "", base: repoRoot };
+  return isSafeRelativePath2(relative) ? { projectDir: relative, base: repoRoot } : { projectDir: null, base: repoRoot };
+};
+var approve = ({
+  manifests,
+  repoRoot = process.cwd(),
+  names,
+  testFile,
+  force = false,
+  dryRun = false
+}) => {
+  const root = path4.resolve(repoRoot);
+  const sources = manifests.map((file) => ({
+    file,
+    label: file,
+    manifest: readManifestFile(file)
+  }));
+  const run = mergeManifests(sources);
+  const picked = selectEntries(run, names ? { names } : "all");
+  const explicit = names !== void 0;
+  const chosen = testFile ? picked.entries.filter((m) => m.entry.test.filePath === testFile) : picked.entries;
+  const result = {
+    approved: [],
+    skipped: [],
+    files: [],
+    warnings: run.warnings,
+    unknown: picked.unknown
+  };
+  const changed = /* @__PURE__ */ new Set();
+  const skip = (m, reason) => result.skipped.push({ entry: m.entry, reason });
+  for (const m of chosen) {
+    const { entry, source } = m;
+    if (m.unapprovableReason) {
+      skip(m, `cannot be approved: ${m.unapprovableReason}`);
+      continue;
+    }
+    if (!explicit && m.collidesWith.length > 0) {
+      skip(m, "writes the same baseline as another entry; name one to approve");
+      continue;
+    }
+    const { projectDir, base } = locateProject(source.manifest, root);
+    if (projectDir === null) {
+      skip(
+        m,
+        `the project root ${source.manifest.projectRoot} is outside the repository root ${root}; run from the repository root or pass --repo-root`
+      );
+      continue;
+    }
+    if (!entry.images.actual.path) {
+      skip(m, "the run kept no actual image for it");
+      continue;
+    }
+    const actualRepo = toRepoPath(projectDir, entry.images.actual.path);
+    const baselineRepo = toRepoPath(projectDir, entry.images.baseline.path);
+    if (!actualRepo || !baselineRepo) {
+      skip(m, "its paths are outside the repository");
+      continue;
+    }
+    const actual = path4.join(base, actualRepo);
+    const baseline = path4.join(base, baselineRepo);
+    const diffRepo = toRepoPath(projectDir, entry.images.diff.path);
+    if (!fs3.existsSync(actual)) {
+      skip(m, "the actual image is gone");
+      continue;
+    }
+    if (!force) {
+      if (entry.hashes?.actual && entry.hashes.actual !== sha256(actual)) {
+        skip(m, "the actual image changed since the run (stale)");
+        continue;
+      }
+      const baselineNow = fs3.existsSync(baseline) ? sha256(baseline) : void 0;
+      const expected = entry.hashes?.baseline;
+      const stale = entry.status === "missing-baseline" ? baselineNow !== void 0 : expected !== void 0 && baselineNow !== expected;
+      if (stale) {
+        skip(m, "the baseline changed since the run (stale)");
+        continue;
+      }
+    }
+    if (!dryRun) {
+      fs3.mkdirSync(path4.dirname(baseline), { recursive: true });
+      fs3.copyFileSync(actual, baseline);
+      fs3.rmSync(actual, { force: true });
+      if (diffRepo) fs3.rmSync(path4.join(base, diffRepo), { force: true });
+      Object.assign(entry, {
+        status: "approved",
+        images: {
+          // the approved screenshot is the baseline now, with its size
+          baseline: {
+            ...entry.images.baseline,
+            width: entry.images.actual.width ?? entry.images.baseline.width,
+            height: entry.images.actual.height ?? entry.images.baseline.height
+          },
+          actual: { path: null },
+          diff: { path: null }
+        },
+        baselineWritten: true,
+        recordedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        hashes: { baseline: sha256(baseline) },
+        message: "Baseline image was replaced with the approved screenshot."
+      });
+      changed.add(source);
+    }
+    result.approved.push(entry);
+    result.files.push(baselineRepo);
+  }
+  for (const { file, manifest } of changed) {
+    manifest.summary = summarize(manifest.entries);
+    manifest.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
+    writeManifestFile(file, manifest);
+  }
+  return result;
+};
+
+// src/reporters.ts
+import fs4 from "fs";
+import path5 from "path";
+import {
+  needsHuman,
+  toCtrf
+} from "visual-regression-manifest";
+var MARK = {
+  passed: "\u2713",
+  failed: "\u2717",
+  "missing-baseline": "?",
+  created: "+",
+  updated: "~",
+  approved: "\u2713"
+};
+var consoleReporter = (log = (line) => process.stdout.write(`${line}
+`)) => ({
+  onEntry(entry) {
+    const note = entry.status === "passed" ? "" : ` ${entry.status}: ${entry.message}`;
+    log(`${MARK[entry.status]} ${entry.name}${note}`);
+  },
+  onEnd({ summary }) {
+    const parts = [
+      `${summary.passed} passed`,
+      `${summary.failed} failed`,
+      `${summary.missingBaseline} without baseline`,
+      `${summary.created} created`,
+      `${summary.updated} updated`
+    ];
+    log(`
+${summary.entries} compared: ${parts.join(", ")}`);
+  }
+});
+var ctrfReporter = (file) => ({
+  onEnd(manifest) {
+    fs4.mkdirSync(path5.dirname(path5.resolve(file)), { recursive: true });
+    fs4.writeFileSync(file, JSON.stringify(toCtrf(manifest), null, 2));
+  }
+});
+var cell = (text) => text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+var summaryMarkdown = ({ summary, entries }) => {
+  const lines = [
+    "### Visual regression",
+    "",
+    `${summary.entries} screenshots: ${summary.passed} passed, ${summary.failed} failed, ${summary.missingBaseline} without baseline, ${summary.created} created, ${summary.updated} updated.`
+  ];
+  const open = entries.filter((entry) => needsHuman(entry.status));
+  if (open.length > 0) {
+    lines.push("", "| Screenshot | Status | Details |", "| --- | --- | --- |");
+    for (const entry of open) {
+      lines.push(
+        `| ${cell(entry.name)} | ${entry.status} | ${cell(entry.message)} |`
+      );
+    }
+  }
+  return `${lines.join("\n")}
+`;
+};
+var githubSummaryReporter = (file = process.env.GITHUB_STEP_SUMMARY) => ({
+  onEnd(manifest) {
+    if (!file) return;
+    fs4.appendFileSync(file, summaryMarkdown(manifest));
+  }
+});
+var REPORTER_NAMES = ["console", "ctrf", "github-summary"];
+var parseReporters = (spec) => spec.split(",").map((part) => part.trim()).filter(Boolean).map((part) => {
+  const colon = part.indexOf(":");
+  const name = colon === -1 ? part : part.slice(0, colon);
+  const arg = colon === -1 ? void 0 : part.slice(colon + 1);
+  switch (name) {
+    case "console":
+      return consoleReporter();
+    case "ctrf":
+      return ctrfReporter(arg ?? "ctrf-report.json");
+    case "github-summary":
+      return githubSummaryReporter(arg);
+    default:
+      throw new Error(
+        `Unknown reporter "${name}" (known: ${REPORTER_NAMES.join(", ")})`
+      );
+  }
+});
+export {
+  BUILT_IN_ENGINES,
+  Comparer,
+  TOOL_NAME,
+  approve,
+  consoleReporter,
+  createComparer,
+  ctrfReporter,
+  decodePng,
+  encodePng,
+  fileStore,
+  fsStore,
+  githubSummaryReporter,
+  loadEngine,
+  manifestLayout,
+  parseReporters,
+  pixelmatchEngine,
+  samePathMatcher,
+  sanitizeName,
+  summaryMarkdown,
+  templateMatcher
+};