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

package/dist/cli.js

@@ -0,0 +1,1301 @@
+#!/usr/bin/env node
+
+// src/run.ts
+import fs6 from "fs";
+import path7 from "path";
+
+// src/approve.ts
+import { createHash } from "crypto";
+import fs from "fs";
+import path from "path";
+import {
+  isSafeRelativePath,
+  mergeManifests,
+  projectDirInRepo,
+  readManifestFile,
+  selectEntries,
+  summarize,
+  toRepoPath,
+  writeManifestFile
+} from "visual-regression-manifest";
+var sha256 = (file) => createHash("sha256").update(fs.readFileSync(file)).digest("hex");
+var locateProject = (manifest, repoRoot) => {
+  if (manifest.ci?.workspace) {
+    return { projectDir: projectDirInRepo(manifest), base: repoRoot };
+  }
+  const relative = path.relative(repoRoot, manifest.projectRoot).split(path.sep).join("/");
+  if (relative === "") return { projectDir: "", base: repoRoot };
+  return isSafeRelativePath(relative) ? { projectDir: relative, base: repoRoot } : { projectDir: null, base: repoRoot };
+};
+var approve = ({
+  manifests,
+  repoRoot = process.cwd(),
+  names,
+  testFile,
+  force = false,
+  dryRun = false
+}) => {
+  const root = path.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 = path.join(base, actualRepo);
+    const baseline = path.join(base, baselineRepo);
+    const diffRepo = toRepoPath(projectDir, entry.images.diff.path);
+    if (!fs.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 = fs.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) {
+      fs.mkdirSync(path.dirname(baseline), { recursive: true });
+      fs.copyFileSync(actual, baseline);
+      fs.rmSync(actual, { force: true });
+      if (diffRepo) fs.rmSync(path.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/comparer.ts
+import fs2 from "fs";
+import os from "os";
+import path3 from "path";
+import {
+  ManifestWriter,
+  getManifestFileName,
+  maxRatioFrom
+} from "visual-regression-manifest";
+
+// src/engines/index.ts
+import path2 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) || path2.isAbsolute(id);
+  const specifier = isPath ? pathToFileURL(path2.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);
+  return {
+    kind: "compared",
+    baselineSize,
+    actualSize,
+    ...resized && { resized },
+    ...result,
+    ...diff && { diffPng: encodePng(diff) }
+  };
+};
+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/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 DEFAULT_WORKER = new URL("./worker.js", import.meta.url);
+var percent = (ratio2) => `${Number((ratio2 * 100).toPrecision(3))}%`;
+var sizeText = ({ width, height }) => `${width}x${height}`;
+var Comparer = class {
+  constructor(options) {
+    this.options = options;
+    this.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 ?? []);
+    const manifestPath = options.manifest.path ?? path3.join(this.projectRoot, getManifestFileName("compare"));
+    this.writer = 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 }
+    );
+    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 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);
+    }
+    return this.pool.run({
+      baseline,
+      actual,
+      onSizeMismatch,
+      engine: { id: spec, options: engineOptions, cwd: process.cwd() }
+    });
+  }
+  /** Compares one screenshot, decides, writes the files and records the manifest entry. */
+  async compareImage(input) {
+    await this.ready;
+    const name = sanitizeName(input.name);
+    const baseline = {
+      kind: "baseline",
+      path: this.layout().paths(name).baseline
+    };
+    return this.compareAt(input, name, baseline);
+  }
+  async compareAt(input, name, baselineRef) {
+    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);
+    let measurement;
+    let diffPng;
+    if (baselineBytes === null) {
+      measurement = { kind: "missing-baseline" };
+    } else {
+      let job;
+      try {
+        job = await this.measure(baselineBytes, input.actual, engine);
+      } 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;
+    }
+    for (const fn of this.registry.hooks.afterCompare)
+      await fn(ctx, measurement);
+    const limit = this.limitFor(measurement);
+    let decision = this.decide(measurement, limit);
+    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);
+    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 this.store().write(ref, bytes);
+    const entry = this.record(
+      input,
+      name,
+      baselineRef,
+      refs,
+      measurement,
+      decision,
+      limit,
+      engine,
+      Date.now() - started
+    );
+    for (const reporter of this.registry.reporters)
+      await reporter.onEntry?.(entry);
+    return entry;
+  }
+  /** `maxDiffRatio` of the entry: the stricter of the ratio and the pixel count, for the size actually compared. */
+  limitFor(measurement) {
+    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 } = this.options.limits ?? {};
+    return maxRatioFrom({ ratio: maxDiffRatio, pixels: maxDiffPixels }, size) ?? 0;
+  }
+  decide(measurement, limit) {
+    const { update = "none", onMissingBaseline = "fail" } = this.options;
+    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(input, name, baselineRef, refs, measurement, decision, limit, engine, duration) {
+    const store = this.store();
+    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 = path3.relative(
+      this.projectRoot,
+      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 },
+      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"
+      },
+      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 ?? os.cpus().length);
+    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/config.ts
+import fs3 from "fs";
+import path4 from "path";
+import { pathToFileURL as pathToFileURL2 } from "url";
+var CANDIDATES = [
+  "visual-regression.config.json",
+  "visual-regression.config.mjs",
+  "visual-regression.config.js"
+];
+var loadConfig = async (explicit, cwd = process.cwd()) => {
+  const file = explicit ? path4.resolve(cwd, explicit) : CANDIDATES.map((name) => path4.join(cwd, name)).find(
+    (f) => fs3.existsSync(f)
+  );
+  if (!file) return {};
+  if (!fs3.existsSync(file))
+    throw new Error(`Config file ${file} does not exist`);
+  if (file.endsWith(".json")) return JSON.parse(fs3.readFileSync(file, "utf8"));
+  const loaded = await import(pathToFileURL2(file).href);
+  return loaded.default ?? {};
+};
+var configArg = (argv) => {
+  const at = argv.findIndex(
+    (arg2) => arg2 === "--config" || arg2.startsWith("--config=")
+  );
+  if (at === -1) return void 0;
+  const arg = argv[at];
+  return arg.includes("=") ? arg.slice(arg.indexOf("=") + 1) : argv[at + 1];
+};
+
+// src/store.ts
+import fs4 from "fs";
+import path5 from "path";
+import { isSafeRelativePath as isSafeRelativePath2 } 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 path5.resolve(root);
+  };
+  const locate = ({ kind, path: relative }) => {
+    if (relative !== "" && !isSafeRelativePath2(relative)) {
+      throw new Error(`Unsafe image path ${JSON.stringify(relative)}`);
+    }
+    return path5.join(rootOf(kind), relative);
+  };
+  return {
+    locate,
+    async read(ref) {
+      try {
+        return await fs4.promises.readFile(locate(ref));
+      } catch (error) {
+        if (error.code === "ENOENT") return null;
+        throw error;
+      }
+    },
+    async write(ref, bytes) {
+      const file = locate(ref);
+      await fs4.promises.mkdir(path5.dirname(file), { recursive: true });
+      await fs4.promises.writeFile(file, bytes);
+    },
+    async remove(ref) {
+      await fs4.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 fs4.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(path5.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/options.ts
+import { parseArgs } from "util";
+import {
+  MANIFEST_STATUSES
+} from "visual-regression-manifest";
+var UsageError = class extends Error {
+};
+var helpText = `Compare folders of screenshots against their baselines and write a visual-regression-manifest.
+
+Usage:
+  visual-regression-compare [compare] <actual-dir> --baseline <dir> [options]
+  visual-regression-compare record <actual-dir> --baseline <dir> [options]
+  visual-regression-compare approve --manifest <path>... [<name>...|--all] [options]
+
+compare options:
+  --baseline <dir>          directory of baseline images (required)
+  --diff <dir>              where .actual and .diff files go (default: next to the baselines)
+  --engine <id>             pixelmatch, or a module path or package name (default: pixelmatch)
+  --max-diff-ratio <n>      largest accepted share of differing pixels, 0..1 (default: 0)
+  --max-diff-pixels <n>     largest accepted number of differing pixels
+  --color-threshold <n>     per-pixel color tolerance of the engine, 0..1 (default: 0.1)
+  --include-aa              count anti-aliased pixels as differences
+  --on-missing fail|create  a screenshot without baseline (default: fail)
+  --on-size-mismatch fail|pad|crop
+                            fail records the size change and compares nothing; pad grows both
+                            images to the larger size, crop cuts both to the smaller (default: fail)
+  --update none|failures-only|all
+                            overwrite baselines (default: none)
+  --match <template>        baseline path from the screenshot path: {dir}, {name}, {path}
+  --layout manifest         file naming (default: manifest)
+  --manifest <path>         default: <actual-dir>/visual-regression-manifest.compare.json
+  --runner <name> --variant <id> --platform <os>[/<browser>]
+                            metadata recorded on every entry
+  --report <list>           console, ctrf[:<file>], github-summary[:<file>] (default: console)
+  --concurrency <n>         worker threads for decoding and comparing (default: CPU count)
+  --config <file>           visual-regression.config.{json,mjs,js}, found in the working directory
+  --fail-on <list>          statuses that make the exit code 1 (default: failed,missing-baseline)
+
+approve options:
+  --manifest <path>         a manifest to apply (repeatable; required)
+  --all                     every entry that needs a human (the default without names)
+  --test <file>             only entries of this test file
+  --repo-root <dir>         the repository the manifest's paths are applied to (default: the working directory)
+  --force                   approve although the baseline changed since the run
+  --dry-run                 report what would be approved
+
+  -h, --help, -v, --version
+`;
+var number = (name, value) => {
+  if (value === void 0) return void 0;
+  const parsed = Number(value);
+  if (value.trim() === "" || Number.isNaN(parsed)) {
+    throw new UsageError(`${name} must be a number, got "${value}"`);
+  }
+  return parsed;
+};
+var ratio = (value) => {
+  if (value !== void 0 && (value < 0 || value > 1)) {
+    throw new UsageError(
+      `--max-diff-ratio must be between 0 and 1, got ${value}`
+    );
+  }
+  return value;
+};
+var oneOf = (name, value, allowed, fallback) => {
+  if (value === void 0) return fallback;
+  if (!allowed.includes(value)) {
+    throw new UsageError(
+      `${name} must be one of ${allowed.join(", ")}, got "${value}"`
+    );
+  }
+  return value;
+};
+var parseCommand = (argv, config = {}) => {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        baseline: { type: "string" },
+        diff: { type: "string" },
+        engine: { type: "string" },
+        "max-diff-ratio": { type: "string" },
+        "max-diff-pixels": { type: "string" },
+        "color-threshold": { type: "string" },
+        "include-aa": { type: "boolean" },
+        "on-missing": { type: "string" },
+        "on-size-mismatch": { type: "string" },
+        update: { type: "string" },
+        match: { type: "string" },
+        layout: { type: "string" },
+        manifest: { type: "string", multiple: true },
+        runner: { type: "string" },
+        variant: { type: "string" },
+        platform: { type: "string" },
+        report: { type: "string" },
+        concurrency: { type: "string" },
+        config: { type: "string" },
+        "fail-on": { type: "string" },
+        all: { type: "boolean" },
+        test: { type: "string" },
+        "repo-root": { type: "string" },
+        force: { type: "boolean" },
+        "dry-run": { type: "boolean" }
+      }
+    });
+  } catch (error) {
+    throw new UsageError(error.message);
+  }
+  const { values } = parsed;
+  const verbAt = parsed.positionals.findIndex(
+    (arg) => ["compare", "record", "approve"].includes(arg)
+  );
+  const verb = verbAt === -1 ? void 0 : parsed.positionals[verbAt];
+  const positionals = parsed.positionals.filter((_, i) => i !== verbAt);
+  if (values.help) return { kind: "help" };
+  if (values.version) return { kind: "version" };
+  const manifests = values.manifest ?? [];
+  if (verb === "approve") {
+    if (manifests.length === 0) {
+      throw new UsageError("approve needs at least one --manifest <path>");
+    }
+    return {
+      kind: "approve",
+      options: {
+        manifests,
+        names: positionals,
+        all: Boolean(values.all) || positionals.length === 0,
+        test: values.test,
+        repoRoot: values["repo-root"],
+        force: Boolean(values.force),
+        dryRun: Boolean(values["dry-run"])
+      }
+    };
+  }
+  if (manifests.length > 1) {
+    throw new UsageError("compare takes one --manifest <path>");
+  }
+  const actualDir = positionals[0] ?? config.actualDir;
+  if (!actualDir) throw new UsageError("Missing <actual-dir>");
+  if (positionals.length > 1) {
+    throw new UsageError(`Unexpected argument "${positionals[1]}"`);
+  }
+  const baselineDir = values.baseline ?? config.baselineDir;
+  if (!baselineDir) throw new UsageError("Missing --baseline <dir>");
+  const record = verb === "record";
+  const failOn = (values["fail-on"]?.split(",").map((s) => s.trim()).filter(Boolean) ?? config.failOn ?? ["failed", "missing-baseline"]).map(
+    (status) => oneOf("--fail-on", status, MANIFEST_STATUSES, "failed")
+  );
+  if (failOn.length === 0) {
+    throw new UsageError("--fail-on needs at least one status");
+  }
+  const colorThreshold = number(
+    "--color-threshold",
+    values["color-threshold"]
+  );
+  return {
+    kind: "compare",
+    options: {
+      actualDir,
+      baselineDir,
+      diffDir: values.diff ?? config.diffDir,
+      engine: values.engine ?? config.engine ?? "pixelmatch",
+      engineOptions: {
+        ...config.engineOptions,
+        ...colorThreshold !== void 0 && { threshold: colorThreshold },
+        ...values["include-aa"] && { includeAA: true }
+      },
+      maxDiffRatio: ratio(
+        number(
+          "--max-diff-ratio",
+          values["max-diff-ratio"]
+        ) ?? config.maxDiffRatio
+      ),
+      maxDiffPixels: number(
+        "--max-diff-pixels",
+        values["max-diff-pixels"]
+      ) ?? config.maxDiffPixels,
+      onMissingBaseline: record ? "create" : oneOf(
+        "--on-missing",
+        values["on-missing"] ?? config.onMissingBaseline,
+        ["fail", "create"],
+        "fail"
+      ),
+      onSizeMismatch: oneOf(
+        "--on-size-mismatch",
+        values["on-size-mismatch"] ?? config.onSizeMismatch,
+        ["fail", "pad", "crop"],
+        "fail"
+      ),
+      update: record ? "all" : oneOf(
+        "--update",
+        values.update ?? config.update,
+        ["none", "failures-only", "all"],
+        "none"
+      ),
+      match: values.match ?? config.match,
+      layout: oneOf(
+        "--layout",
+        values.layout,
+        ["manifest"],
+        "manifest"
+      ),
+      manifest: manifests[0] ?? config.manifest,
+      runner: values.runner ?? config.runner,
+      variant: values.variant ?? config.variant,
+      platform: values.platform ?? config.platform,
+      report: values.report ?? config.report ?? "console",
+      concurrency: number("--concurrency", values.concurrency) ?? config.concurrency,
+      failOn,
+      record
+    }
+  };
+};
+
+// src/reporters.ts
+import fs5 from "fs";
+import path6 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) {
+    fs5.mkdirSync(path6.dirname(path6.resolve(file)), { recursive: true });
+    fs5.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;
+    fs5.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(", ")})`
+      );
+  }
+});
+
+// src/run.ts
+var platformOf = (spec) => {
+  if (!spec) return void 0;
+  const [osPlatform, browser] = spec.split("/");
+  return { osPlatform, ...browser && { browser: { name: browser } } };
+};
+var compare = async (options, version, out) => {
+  const actualDir = path7.resolve(options.actualDir);
+  const comparer = createComparer({
+    engine: options.engine,
+    engineOptions: options.engineOptions,
+    limits: {
+      maxDiffRatio: options.maxDiffRatio,
+      maxDiffPixels: options.maxDiffPixels
+    },
+    onMissingBaseline: options.onMissingBaseline,
+    onSizeMismatch: options.onSizeMismatch,
+    update: options.update,
+    store: fsStore({
+      baselineDir: options.baselineDir,
+      actualDir,
+      diffDir: options.diffDir
+    }),
+    layout: manifestLayout(),
+    matcher: options.match ? templateMatcher(options.match) : samePathMatcher(),
+    manifest: {
+      path: options.manifest ?? path7.join(actualDir, "visual-regression-manifest.compare.json"),
+      projectRoot: commonRoot([
+        actualDir,
+        path7.resolve(options.baselineDir),
+        ...options.diffDir ? [path7.resolve(options.diffDir)] : []
+      ]),
+      tool: { name: "visual-regression-compare", version },
+      runner: { name: options.runner ?? "visual-regression-compare" },
+      platform: platformOf(options.platform),
+      variant: options.variant
+    },
+    reporters: parseReporters(options.report),
+    concurrency: options.concurrency
+  });
+  try {
+    await comparer.compareAll();
+  } finally {
+    await comparer.close();
+  }
+  const manifest = comparer.writer.toJSON();
+  const failing = manifest.entries.filter(
+    (entry) => options.failOn.includes(entry.status)
+  );
+  if (manifest.entries.length === 0) {
+    out.error(`No images found in ${options.actualDir}`);
+    return 1;
+  }
+  out.log(`Manifest: ${comparer.writer.filePath}`);
+  return failing.length > 0 ? 1 : 0;
+};
+var commonRoot = (dirs) => {
+  const split = dirs.map((dir) => dir.split(path7.sep));
+  const shared = [];
+  for (let i = 0; i < split[0].length; i++) {
+    if (split.every((parts) => parts[i] === split[0][i]))
+      shared.push(split[0][i]);
+    else break;
+  }
+  return shared.join(path7.sep) || path7.sep;
+};
+var approveCommand = (options, out) => {
+  const result = approve({
+    manifests: options.manifests,
+    names: options.all ? void 0 : options.names,
+    testFile: options.test,
+    repoRoot: options.repoRoot,
+    force: options.force,
+    dryRun: options.dryRun
+  });
+  for (const warning of result.warnings) out.error(`warning: ${warning}`);
+  for (const name of result.unknown) out.error(`No entry named "${name}"`);
+  for (const { entry, reason } of result.skipped) {
+    out.error(`skipped ${entry.name}: ${reason}`);
+  }
+  const verb = options.dryRun ? "Would approve" : "Approved";
+  out.log(
+    `${verb} ${result.approved.length} screenshot${result.approved.length === 1 ? "" : "s"}`
+  );
+  for (const file of result.files) out.log(`  ${file}`);
+  return result.skipped.length > 0 || result.unknown.length > 0 ? 1 : 0;
+};
+var runCli = async (argv, out) => {
+  try {
+    const config = await loadConfig(configArg(argv));
+    const command = parseCommand(argv, config);
+    if (command.kind === "help") {
+      out.log(helpText);
+      return 0;
+    }
+    const { version } = JSON.parse(
+      fs6.readFileSync(new URL("../package.json", import.meta.url), "utf8")
+    );
+    if (command.kind === "version") {
+      out.log(version);
+      return 0;
+    }
+    return command.kind === "approve" ? approveCommand(command.options, out) : await compare(command.options, version, out);
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    out.error(
+      error instanceof UsageError ? `${message}
+Run with --help for the options.` : `Error: ${message}`
+    );
+    return 2;
+  }
+};
+
+// src/cli.ts
+process.exitCode = await runCli(process.argv.slice(2), {
+  log: (line) => process.stdout.write(`${line}
+`),
+  error: (line) => process.stderr.write(`${line}
+`)
+});