@henols/c64-re-tools 1.1.0 → 2.0.0-rc.2

package/src/host/vice/process.ts

@@ -0,0 +1,402 @@
+// VICE launch, readiness and termination. The launch contract of x64sc:
+// - `-default` must come before `-binarymonitor`, or the monitor never binds;
+// - the monitor may accept a connection during startup and then drop it, so
+//   readiness is a connect plus a successful ping, retried until a deadline;
+// - any monitor command stops the machine, so readiness ends with `exit`;
+// - `-default` selects drive type 1542, whose ROM stock installs often lack,
+//   so drive 8 is a plain 1541;
+// - the remote text monitor runs beside the binary one for the few
+//   operations only it offers; both act on the same machine;
+// - autostart of a PRG needs `-autostartprgmode 1` (inject into RAM);
+// - the joyport command reaches the C64 only through the "Joyport I/O
+//   simulation" device (37), whose lines start all pressed until set;
+// - with the default JAM action a jammed CPU hangs silently; -jamaction 2
+//   enters the monitor instead;
+// - the monitor's profiler prints numbers in the host locale, so VICE runs
+//   with LC_NUMERIC=C;
+// - piped output is block-buffered and lost when VICE exits early (for
+//   example without its ROM files), so VICE also writes a log file;
+// - `-console` runs VICE with no window and needs no display; the
+//   monitors, the CPU and the frame buffer work as with a window. It is a
+//   start option only, so headless and windowed are two VICE processes.
+//   A headless VICE plays no sound: `-sounddev dummy` keeps the SID emulated.
+
+import { mkdtempSync, readFileSync, rmSync } from "node:fs";
+import { createServer } from "node:net";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+
+import { WireFailure, type VideoStandard } from "../../protocol/messages.ts";
+import { elapsedMs, trace } from "../../trace.ts";
+import { findTool, isOlderThanMinimum, MIN_VICE, VICE } from "../../native/discover.ts";
+import type { ExitStatus, ProcessSupervisor, SupervisedProcess } from "../../native/processes.ts";
+import { BinaryMonitor, Command, decodeMemory, memoryGetBody } from "./binary-monitor.ts";
+import { TextMonitor } from "./text-monitor.ts";
+
+export const DEFAULT_READY_TIMEOUT_MS = 30_000;
+const PING_TIMEOUT_MS = 5_000;
+const RETRY_MS = 50;
+const OUTPUT_TAIL_LINES = 40;
+const STOP_REPORT_MS = 10_000;
+
+/** Finds x64sc: C64RT_VICE, else PATH. Refuses by name with the remedy; never installs anything. */
+export function findVice(env: NodeJS.ProcessEnv = process.env): string {
+  return findTool(VICE, env);
+}
+
+/** Asks the OS for a free loopback port. Another process can still take it before VICE binds. */
+export function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close(() => {
+        if (address === null || typeof address === "string") reject(new Error("no TCP address"));
+        else resolve(address.port);
+      });
+    });
+  });
+}
+
+/** A VICE with no window (the default) or one with a window the user can use. */
+export type ViceMode = "headless" | "window";
+
+export function viceArguments(options: {
+  binary: string;
+  port: number;
+  textPort: number;
+  configFile: string;
+  logFile: string;
+  videoStandard: VideoStandard;
+  mode: ViceMode;
+}): string[] {
+  const headless = options.mode === "headless" ? ["-console", "-sounddev", "dummy"] : [];
+  return [
+    options.binary,
+    "-default",
+    "-logfile",
+    options.logFile,
+    "-binarymonitor",
+    "-binarymonitoraddress",
+    `ip4://127.0.0.1:${options.port}`,
+    "-remotemonitor",
+    "-remotemonitoraddress",
+    `ip4://127.0.0.1:${options.textPort}`,
+    "-config",
+    options.configFile,
+    "-model",
+    options.videoStandard === "ntsc" ? "ntsc" : "c64",
+    "-drive8type",
+    "1541",
+    // Autostart injects a PRG into RAM; the default mode copies it to a disk image first.
+    "-autostartprgmode",
+    "1",
+    // The same RAM after every power-up: a hard reset is a power cycle, and VICE's default can flip
+    // random bits, so two runs from one start state could differ.
+    "-raminitstartvalue",
+    "0",
+    "-raminitvalueinvert",
+    "64",
+    "-raminitpatterninvert",
+    "0",
+    "-raminitstartrandom",
+    "0",
+    "-raminitrepeatrandom",
+    "0",
+    "-raminitrandomchance",
+    "0",
+    // A CPU JAM enters the monitor, so it stops the machine visibly instead of hanging it.
+    "-jamaction",
+    "2",
+    // The binary monitor's joyport command drives only the "Joyport I/O simulation" device.
+    "-controlport1device",
+    "37",
+    "-controlport2device",
+    "37",
+    ...headless,
+  ];
+}
+
+export interface LaunchOptions {
+  videoStandard: VideoStandard;
+  /** Defaults to headless. */
+  mode?: ViceMode;
+  supervisor: ProcessSupervisor;
+  /** Environment to find VICE in and to run it with. Defaults to process.env. */
+  env?: NodeJS.ProcessEnv;
+  readyTimeoutMs?: number;
+  log?: (line: string) => void;
+}
+
+/** A running, ready VICE with its binary monitor connected. */
+export interface ViceProcess {
+  /** Host-internal; never leaves the Host Runtime. */
+  readonly pid: number;
+  readonly monitor: BinaryMonitor;
+  readonly text: TextMonitor;
+  /** Settles when VICE exits, for any reason. */
+  readonly exited: Promise<ExitStatus>;
+  /** The last lines VICE printed, for host logs only. */
+  outputTail(): string;
+  /** Closes the monitor, stops the process group and removes the scratch directory. Idempotent. */
+  stop(): Promise<void>;
+}
+
+/** The last lines of VICE's log file, or of its output while there is no log file. */
+function tailCollector(child: SupervisedProcess, logFile: string): () => string {
+  const lines: string[] = [];
+  let partial = "";
+  const take = (chunk: Buffer) => {
+    const parts = (partial + chunk.toString("utf8")).split("\n");
+    partial = parts.pop() ?? "";
+    lines.push(...parts);
+    if (lines.length > OUTPUT_TAIL_LINES) lines.splice(0, lines.length - OUTPUT_TAIL_LINES);
+  };
+  child.child.stdout?.on("data", take);
+  child.child.stderr?.on("data", take);
+  return () => {
+    try {
+      return readFileSync(logFile, "utf8").split("\n").filter((line) => line !== "").slice(-OUTPUT_TAIL_LINES).join("\n");
+    } catch {
+      return [...lines, partial].filter((line) => line !== "").join("\n");
+    }
+  };
+}
+
+/**
+ * Launches one VICE in its own scratch directory outside the project, waits
+ * until its binary monitor answers, then lets the machine run.
+ * Throws WireFailure: installation-incomplete when VICE is missing,
+ * machine-unavailable when it does not start.
+ */
+export async function launchVice(options: LaunchOptions): Promise<ViceProcess> {
+  // A failed launch is tried again with a fresh VICE: VICE exits, another
+  // process takes a monitor port between the free-port check and VICE binding
+  // it, or (on macOS, with a window) VICE starts but never binds its monitor,
+  // while the next VICE starts at once. A missing installation is final.
+  let lastError: unknown;
+  for (let attempt = 1; attempt <= LAUNCH_ATTEMPTS; attempt++) {
+    try {
+      return await launchOnce(options);
+    } catch (error) {
+      lastError = error;
+      if (error instanceof WireFailure && error.code === "installation-incomplete") throw error;
+      options.log?.(`VICE launch attempt ${attempt} failed: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (lastError instanceof WireFailure) throw lastError;
+  throw new WireFailure("machine-unavailable", "The emulator could not be started on the host.");
+}
+
+const LAUNCH_ATTEMPTS = 3;
+
+/** VICE's own error lines from the log lines of failed launches, without repeats. */
+export function startErrorLines(output: string[]): string[] {
+  return [...new Set(output.flatMap((entry) => entry.split("\n")).filter((line) => /\berror\b/i.test(line) && !line.startsWith("VICE ")))];
+}
+
+/**
+ * Starts VICE once, as a session does, and stops it again. Finding
+ * x64sc is not enough: without its ROM files VICE exits at once. Throws
+ * WireFailure installation-incomplete with VICE's own error lines.
+ */
+export async function checkViceStarts(options: Omit<LaunchOptions, "videoStandard" | "log">): Promise<void> {
+  const binary = findVice(options.env ?? process.env);
+  const output: string[] = [];
+  let vice: ViceProcess;
+  try {
+    vice = await launchVice({ ...options, videoStandard: "pal", log: (line) => output.push(line) });
+  } catch (error) {
+    if (error instanceof WireFailure && error.code === "installation-incomplete") throw error;
+    const reasons = startErrorLines(output);
+    throw new WireFailure(
+      "installation-incomplete",
+      `VICE (${binary}) is installed but does not start${reasons.length === 0 ? "." : `:\n  ${reasons.join("\n  ")}`}\n` +
+        "Make sure that VICE has its ROM files (the C64 KERNAL, BASIC and character ROMs) and that x64sc starts when you run it by hand, " +
+        "then restart the Host Runtime.",
+    );
+  }
+  // VICE_INFO: the length of the main version (4), then major, minor, build and revision.
+  let info: Buffer;
+  try {
+    info = (await vice.monitor.request(Command.viceInfo)).body;
+  } catch (error) {
+    throw new WireFailure(
+      "installation-incomplete",
+      `VICE (${binary}) starts, but it did not tell its version (${error instanceof Error ? error.message : String(error)}). ` +
+        `c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${VICE.remedy}`,
+    );
+  } finally {
+    await vice.stop();
+  }
+  const version = { major: info[1] ?? 0, minor: info[2] ?? 0 };
+  if (isOlderThanMinimum(version)) {
+    throw new WireFailure(
+      "installation-incomplete",
+      `VICE (${binary}) is version ${version.major}.${version.minor}, and c64-re-tools needs VICE ${MIN_VICE.major}.${MIN_VICE.minor} or later. ${VICE.remedy}`,
+    );
+  }
+}
+
+async function launchOnce(options: LaunchOptions): Promise<ViceProcess> {
+  const env = options.env ?? process.env;
+  const log = options.log ?? (() => {});
+  const binary = findVice(env);
+  const port = await freePort();
+  const textPort = await freePort();
+  const scratch = mkdtempSync(join(tmpdir(), "c64-re-tools-vice-"));
+  // Owned by the supervisor: its exit guard and the watchdog remove it if this process dies.
+  const releaseScratch = options.supervisor.ownPath(scratch);
+  const mode = options.mode ?? "headless";
+  const argv = viceArguments({ binary, port, textPort, configFile: join(scratch, "vicerc"), logFile: join(scratch, "vice.log"), videoStandard: options.videoStandard, mode });
+  const child = options.supervisor.spawn(argv, {
+    cwd: scratch,
+    // Keep VICE's config, cache and state away from the user's own VICE setup, and
+    // make its monitor print numbers the same way on every host.
+    env: { ...env, XDG_CONFIG_HOME: scratch, XDG_CACHE_HOME: scratch, XDG_STATE_HOME: scratch, LC_NUMERIC: "C" },
+    stdio: ["ignore", "pipe", "pipe"],
+  });
+  const launched = performance.now();
+  trace().event("vice.launch", { pid: child.pid, mode, videoStandard: options.videoStandard, ports: [port, textPort], scratch, argv });
+  const outputTail = tailCollector(child, join(scratch, "vice.log"));
+  let exited = false;
+  void child.exited.then((status) => {
+    exited = true;
+    trace().event("vice.exit", { pid: child.pid, ...status, ms: elapsedMs(launched) });
+  });
+
+  let monitor: BinaryMonitor | undefined;
+  let text: TextMonitor | undefined;
+  let stopping: Promise<void> | undefined;
+  const stop = () => {
+    stopping ??= (async () => {
+      // A stop that takes long says what it waits for, in the host log.
+      let step = "closing the binary monitor";
+      const started = Date.now();
+      const slow = setInterval(() => log(`VICE (pid ${child.pid}) is not stopped after ${Math.round((Date.now() - started) / 1000)} s: ${step}`), STOP_REPORT_MS);
+      slow.unref();
+      // Every step runs, also after one fails; the first failure is reported at the end.
+      let failure: unknown;
+      const run = async (name: string, work: () => Promise<void> | void) => {
+        step = name;
+        try {
+          await work();
+        } catch (error) {
+          failure ??= error;
+        }
+      };
+      try {
+        await run("closing the binary monitor", () => monitor?.close());
+        await run("closing the text monitor", () => text?.close());
+        await run("ending the process", () => child.stop());
+        // The supervisor keeps the directory on its list, to remove it at exit, until the removal works.
+        await run("removing its scratch directory", () => {
+          // VICE's own log goes with the directory; the trace keeps a copy.
+          trace().keep(join(scratch, "vice.log"), `vice-${child.pid}.log`);
+          rmSync(scratch, { recursive: true, force: true });
+          releaseScratch();
+        });
+      } finally {
+        clearInterval(slow);
+      }
+      if (failure !== undefined) throw failure;
+    })();
+    return stopping;
+  };
+
+  try {
+    const deadline = Date.now() + (options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS);
+    monitor = await waitForMonitor(port, () => exited, deadline);
+    text = await waitForText(textPort, () => exited, deadline);
+    await checkSameMachine(monitor, text);
+    // Readiness stopped the machine; let it run as a freshly started C64 does.
+    await monitor.request(Command.exit);
+  } catch (error) {
+    log(`VICE failed to start: ${error instanceof Error ? error.message : String(error)}\n${outputTail()}`);
+    trace().event("vice.launch-failed", { pid: child.pid, ms: elapsedMs(launched), error });
+    await stop();
+    if (error instanceof WireFailure) throw error;
+    throw new WireFailure("machine-unavailable", "The emulator could not be started on the host.");
+  }
+  log(`VICE started (pid ${child.pid}, monitor ports ${port} and ${textPort})`);
+  trace().event("vice.ready", { pid: child.pid, ms: elapsedMs(launched) });
+  return { pid: child.pid, monitor, text, exited: child.exited, outputTail, stop };
+}
+
+/**
+ * Connects the text monitor and proves it answers. Like the binary one, VICE
+ * can accept a connection during startup that it then never serves, so a
+ * connection that does not answer a probe is dropped and made again.
+ */
+async function waitForText(port: number, hasExited: () => boolean, deadline: number): Promise<TextMonitor> {
+  while (Date.now() < deadline) {
+    if (hasExited()) throw new WireFailure("machine-unavailable", "The emulator exited while it was starting.");
+    let text: TextMonitor;
+    try {
+      text = await TextMonitor.connect(port);
+    } catch {
+      await sleep(RETRY_MS);
+      continue;
+    }
+    try {
+      await text.command("dev c:", Math.min(TEXT_PROBE_MS, Math.max(1, deadline - Date.now())));
+      return text;
+    } catch {
+      await text.close();
+      await sleep(RETRY_MS);
+    }
+  }
+  throw new WireFailure("machine-unavailable", "The emulator's monitor did not become ready in time.");
+}
+
+const TEXT_PROBE_MS = 2_000;
+
+/**
+ * Proves both monitor connections reach the same, freshly started VICE: a
+ * byte written through the binary monitor must read back through the text
+ * monitor. Zero-page $02 is unused by the KERNAL; its value is restored.
+ */
+async function checkSameMachine(monitor: BinaryMonitor, text: TextMonitor): Promise<void> {
+  const read = memoryGetBody({ start: 0x0002, end: 0x0002, memspace: 0, bank: 0 });
+  const original = decodeMemory((await monitor.request(Command.memoryGet, read)).body)[0]!;
+  const marker = (original ^ 0xa5) & 0xff;
+  const write = (value: number) => {
+    const body = memoryGetBody({ start: 0x0002, end: 0x0002, memspace: 0, bank: 0 });
+    return monitor.request(Command.memorySet, Buffer.concat([body, Buffer.from([value])]));
+  };
+  await write(marker);
+  try {
+    const answer = await text.command("m 0002 0002", TEXT_PROBE_MS);
+    const seen = /^>C:0002\s+([0-9a-f]{2})/im.exec(answer);
+    if (seen === null || Number.parseInt(seen[1]!, 16) !== marker) {
+      throw new WireFailure("machine-unavailable", "The emulator's two monitor connections reached different machines.");
+    }
+  } finally {
+    await write(original);
+  }
+}
+
+/** Connects the binary monitor and proves it answers a ping, until `deadline`. */
+async function waitForMonitor(port: number, hasExited: () => boolean, deadline: number): Promise<BinaryMonitor> {
+  while (Date.now() < deadline) {
+    if (hasExited()) throw new WireFailure("machine-unavailable", "The emulator exited while it was starting.");
+    let monitor: BinaryMonitor;
+    try {
+      monitor = await BinaryMonitor.connect(port);
+    } catch {
+      await sleep(RETRY_MS);
+      continue;
+    }
+    try {
+      await monitor.request(Command.ping, undefined, Math.min(PING_TIMEOUT_MS, Math.max(1, deadline - Date.now())));
+      return monitor;
+    } catch {
+      // VICE can drop a connection it accepted during startup; connect again.
+      await monitor.close();
+      await sleep(RETRY_MS);
+    }
+  }
+  throw new WireFailure("machine-unavailable", "The emulator did not become ready in time.");
+}

package/src/host/vice/screen.ts

@@ -0,0 +1,183 @@
+// Canonical emulator-frame capture: VICE's own rendered VIC-II frame, never a
+// desktop screenshot; the frame comparison and difference image for baselines.
+
+import { crc32, deflateSync } from "node:zlib";
+
+import type { VideoStandard } from "../../protocol/messages.ts";
+
+export interface IndexedFrame {
+  width: number;
+  height: number;
+  /** One palette index per pixel, row by row. */
+  pixels: Uint8Array;
+}
+
+export interface RawDisplay {
+  /** Full buffer size, blanking included. */
+  bufferWidth: number;
+  bufferHeight: number;
+  /** Where the 320×200 display window starts, as VICE reports it. */
+  innerX: number;
+  innerY: number;
+  pixels: Uint8Array;
+}
+
+/** Decodes a binary-monitor display-get body (8 bits per pixel). The pixels may be short; see visibleFrame. */
+export function decodeDisplay(body: Buffer): RawDisplay {
+  const headerLength = body.readUInt32LE(0);
+  const bits = body[16];
+  if (bits !== 8) throw new Error(`VICE sent ${bits} bits per pixel, expected 8`);
+  // The buffer length follows the header fields; the pixels follow it.
+  const length = body.readUInt32LE(4 + headerLength);
+  const start = 4 + headerLength + 4;
+  return {
+    bufferWidth: body.readUInt16LE(4),
+    bufferHeight: body.readUInt16LE(6),
+    innerX: body.readUInt16LE(8),
+    innerY: body.readUInt16LE(10),
+    pixels: body.subarray(start, start + length),
+  };
+}
+
+/**
+ * The visible frame with normal borders, relative to VICE's display-window
+ * offsets: PAL 384×272, NTSC 384×247.
+ */
+const VISIBLE: Record<VideoStandard, { dx: number; dy: number; width: number; height: number }> = {
+  pal: { dx: -32, dy: -36, width: 384, height: 272 },
+  ntsc: { dx: -32, dy: -23, width: 384, height: 247 },
+};
+
+/** Crops the visible bordered frame out of VICE's full raster buffer. */
+export function visibleFrame(display: RawDisplay, standard: VideoStandard): IndexedFrame {
+  const area = VISIBLE[standard];
+  const left = display.innerX + area.dx;
+  const top = display.innerY + area.dy;
+  if (left < 0 || top < 0 || left + area.width > display.bufferWidth || top + area.height > display.bufferHeight) {
+    throw new Error(`the ${display.bufferWidth}x${display.bufferHeight} display buffer does not hold the visible ${standard} frame`);
+  }
+  // VICE sends 4 bytes fewer than its length field says; they are
+  // the last ones, in the blanking area, so only the cropped area must be present.
+  if (display.pixels.length < (top + area.height - 1) * display.bufferWidth + left + area.width) {
+    throw new Error("the display buffer is short");
+  }
+  const pixels = new Uint8Array(area.width * area.height);
+  for (let row = 0; row < area.height; row++) {
+    const from = (top + row) * display.bufferWidth + left;
+    pixels.set(display.pixels.subarray(from, from + area.width), row * area.width);
+  }
+  return { width: area.width, height: area.height, pixels };
+}
+
+/** Decodes a binary-monitor palette-get body into RGB triples. */
+export function decodePalette(body: Buffer): Array<[number, number, number]> {
+  const count = body.readUInt16LE(0);
+  const colours: Array<[number, number, number]> = [];
+  let offset = 2;
+  for (let index = 0; index < count; index++) {
+    const size = body[offset]!;
+    colours.push([body[offset + 1]!, body[offset + 2]!, body[offset + 3]!]);
+    offset += size + 1;
+  }
+  return colours;
+}
+
+function chunk(type: string, data: Uint8Array): Buffer {
+  const length = Buffer.alloc(4);
+  length.writeUInt32BE(data.length, 0);
+  const body = Buffer.concat([Buffer.from(type, "latin1"), data]);
+  const crc = Buffer.alloc(4);
+  crc.writeUInt32BE(crc32(body), 0);
+  return Buffer.concat([length, body, crc]);
+}
+
+/** Encodes an indexed frame as an 8-bit palette PNG. */
+export function encodePng(frame: IndexedFrame, palette: ReadonlyArray<readonly [number, number, number]>): Buffer {
+  for (const index of frame.pixels) {
+    if (index >= palette.length) throw new Error(`pixel colour ${index} is not in the ${palette.length}-colour palette`);
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(frame.width, 0);
+  header.writeUInt32BE(frame.height, 4);
+  header[8] = 8; // bit depth
+  header[9] = 3; // indexed colour
+  const rows = Buffer.alloc((frame.width + 1) * frame.height);
+  for (let row = 0; row < frame.height; row++) {
+    // Filter byte 0 (none), then the row.
+    rows.set(frame.pixels.subarray(row * frame.width, (row + 1) * frame.width), row * (frame.width + 1) + 1);
+  }
+  return Buffer.concat([
+    Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+    chunk("IHDR", header),
+    chunk("PLTE", Buffer.from(palette.flat())),
+    chunk("IDAT", deflateSync(rows)),
+    chunk("IEND", new Uint8Array(0)),
+  ]);
+}
+
+export interface FrameDifference {
+  mismatchingPixels: number;
+  /** Pixels compared: the frame minus the masked ones. */
+  comparedPixels: number;
+  /** The smallest rectangle holding every mismatch; absent when nothing differs. */
+  bounds?: { x: number; y: number; width: number; height: number };
+  /** One flag per pixel: 1 mismatch, 2 masked, 0 equal. */
+  map: Uint8Array;
+}
+
+/** Compares two frames of the same size pixel by pixel, outside the mask rectangles. */
+export function compareFrames(
+  baseline: IndexedFrame,
+  current: IndexedFrame,
+  mask: ReadonlyArray<{ x: number; y: number; width: number; height: number }>,
+): FrameDifference {
+  if (baseline.width !== current.width || baseline.height !== current.height) {
+    throw new Error(`frame sizes differ: ${baseline.width}x${baseline.height} and ${current.width}x${current.height}`);
+  }
+  const { width, height } = current;
+  const map = new Uint8Array(width * height);
+  for (const rectangle of mask) {
+    for (let y = rectangle.y; y < Math.min(height, rectangle.y + rectangle.height); y++) {
+      map.fill(2, y * width + rectangle.x, y * width + Math.min(width, rectangle.x + rectangle.width));
+    }
+  }
+  let mismatchingPixels = 0;
+  let comparedPixels = 0;
+  let left = width;
+  let top = height;
+  let right = -1;
+  let bottom = -1;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const at = y * width + x;
+      if (map[at] === 2) continue;
+      comparedPixels++;
+      if (baseline.pixels[at] === current.pixels[at]) continue;
+      map[at] = 1;
+      mismatchingPixels++;
+      left = Math.min(left, x);
+      top = Math.min(top, y);
+      right = Math.max(right, x);
+      bottom = Math.max(bottom, y);
+    }
+  }
+  const difference: FrameDifference = { mismatchingPixels, comparedPixels, map };
+  if (mismatchingPixels > 0) difference.bounds = { x: left, y: top, width: right - left + 1, height: bottom - top + 1 };
+  return difference;
+}
+
+/**
+ * The difference image: the current frame with equal and masked pixels at a
+ * quarter of their brightness and every mismatch in bright magenta.
+ */
+export function differenceImage(
+  current: IndexedFrame,
+  difference: FrameDifference,
+  palette: ReadonlyArray<readonly [number, number, number]>,
+): { frame: IndexedFrame; palette: Array<[number, number, number]> } {
+  const dimmed = palette.map(([r, g, b]) => [r >> 2, g >> 2, b >> 2] as [number, number, number]);
+  const highlight = dimmed.length;
+  const pixels = new Uint8Array(current.pixels.length);
+  for (let at = 0; at < pixels.length; at++) pixels[at] = difference.map[at] === 1 ? highlight : current.pixels[at]!;
+  return { frame: { width: current.width, height: current.height, pixels }, palette: [...dimmed, [255, 0, 255]] };
+}