CtrlK
BlogDocsLog inGet started
Tessl Logo
PluginPublic

adobe/stardust

Redesign an existing website to make it better. Built on top of impeccable.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Low

Low-risk findings worth noting

Overview
Quality
Evals
Security
Files

pixel-compare.mjsskills/replica/scripts/

#!/usr/bin/env node
/**
 * skills/replica/scripts/pixel-compare.mjs
 *
 * Pixel gate for the stardust:replica source-fidelity loop: pixelmatch over
 * two STITCHED full-page PNGs (produced by stitch-shot.mjs — never fullPage
 * captures, see that tool's header). Compares the overlapping region, reports
 * the height delta separately, and emits a per-band breakdown.
 *
 * The band breakdown is the navigation instrument, not decoration: the
 * overall % hides WHERE drift starts. The first hot band points at the
 * section whose height/geometry is wrong; every band below it is contaminated
 * by vertical offset and must be re-read after that section is fixed. Fix
 * top-down, one hot band at a time, re-capture, re-compare.
 *
 * Usage:
 *   node skills/replica/scripts/pixel-compare.mjs <a.png> <b.png> [options]
 *     --out <diff.png>     diff image path            (default diff.png)
 *     --threshold <pct>    pass bar; exit 2 above it  (default 10)
 *     --band <px>          band height for breakdown  (default 500)
 *     --pm-threshold <n>   pixelmatch per-pixel color threshold (default 0.1)
 *     --mask <yA:h[@yB]>   exclude a row band from the number (repeatable, comma
 *                          list): rows yA..yA+h in A and yB..yB+h in B (yB
 *                          defaults to yA) are neutralised on BOTH sides before
 *                          matching and removed from the denominator. For
 *                          authored-volatile regions — campaign heroes, promo
 *                          slots — whose live content changes between capture and
 *                          gate: they are authored content, not conversion
 *                          fidelity, and they must not consume the fidelity bar.
 *                          Every mask is printed on the verdict line; a masked
 *                          number is never reported as an unmasked one.
 *     --json               emit machine-readable summary on stdout
 *     --text-boxes <json>  AUXILIARY number (#125 D4): a JSON file with the
 *                          ORIGIN's text boxes ({ boxes: [{x,y,w,h}, …] } in A's
 *                          page coordinates — content-presence.mjs --json writes
 *                          one per side under `textBoxes`); the differing-pixel
 *                          share is re-computed over those boxes only and
 *                          reported as `textPct`. Pixelmatch underweights small
 *                          text inside otherwise matching shapes (a recorded page
 *                          read 6.7 % full-page, 16.5 % text-only). Not a verdict
 *                          criterion; summary.md carries it beside the pixel %.
 *     --align              ALIGNED comparison beside the overlap one (opt-in). The
 *                          overlap number lays B on A from the top-left corner, so
 *                          one vertical shift near the top makes every row below it
 *                          differ. --align finds a piecewise-constant vertical offset
 *                          map (see "Aligned mode" below), re-counts with the same
 *                          per-pixel rule and reports it as `aligned` — offset steps,
 *                          inserted / deleted rows, and a per-band aligned % that
 *                          names every band still differing, in one run.
 *     --align-max <px>     largest |offset| the map may reach (default 400, cap 4000)
 *     --verdict <which>    unaligned (default) | aligned — which number the exit
 *                          code and `pass` compare against --threshold. `aligned`
 *                          implies --align.
 *     --offset-max <b>     THE PIXEL CRITERION of the gates (gate.sh, gate-all.mjs —
 *                          its one definition, `pixelVerdict`): implies --verdict
 *                          aligned, and `pass` / the exit code also need the offsets
 *                          to be small — aligned % ≤ --threshold AND
 *                          aligned.totalShift (the sum of |shift| over the steps) ≤
 *                          the bound. <b> = a number of px, or a stage: `prototype`
 *                          = 8 px, `published` = the larger of 8 px and 1 % of A's
 *                          height. A low aligned % with large offsets is a page
 *                          whose sections sit in the wrong place: it fails with
 *                          `offsets: <n> step(s), <px>px total — …` (the fix list:
 *                          every step in one round), never a percentage. Alignment
 *                          not used (`aligned.used` false) → the unaligned rule.
 *                          Adds `offsets { bound, totalShift, pass }` and `reason`
 *                          to the JSON and one `pixel:` line to the text.
 *     --json-out <file>    also write the --json summary to <file> (the text output
 *                          stays on stdout) — gate.sh's pixel-<label>.json
 *     --timeout <s>        hard wall-clock deadline (default 120; 0 disables).
 *                          Enforced from a supervising process (the compare
 *                          itself is synchronous, so an in-process timer could
 *                          never fire). Exit 124 = deadline hit, not a gate
 *                          verdict — re-run; raise the cap only for a
 *                          legitimately huge capture.
 *
 * The hang this guards against (three field migrations, 2026-08/09, "0 % CPU
 * for 10+ minutes after the verdict was printed") was reproduced on
 * 2026-09-18: with stdout redirected to a file or /dev/null — how gate.sh and
 * every agent pipeline runs it — `process.exit()` after the compare could
 * block forever inside Node's platform shutdown (stack: Environment::Exit →
 * DisposePlatform → WorkerThreadsTaskRunner::Shutdown → uv_thread_join), 1 in
 * ~4 runs on Node 25. Letting the process drain (`process.exitCode`) instead
 * of forcing exit did not hang in 10/10 runs. The deadline stays as the
 * belt to that fix's braces.
 *
 * Aligned mode (--align). B's rows are A's rows moved by an integer offset that
 * is constant within a segment; between segments rows were inserted in B
 * (shift > 0) or deleted from it (shift < 0).
 *   1. Each row of both images becomes a signature: mean luminance in up to 48
 *      column buckets plus two colour-difference means in a quarter as many.
 *   2. A banded global sequence alignment (affine gaps, integer costs, offset
 *      within ±--align-max) matches A rows to B rows. A matched pair costs its
 *      signature distance (capped); an unmatched row costs more than half that
 *      cap, so "delete here, insert there" never beats comparing in place; and
 *      opening a gap costs ALIGN.minRun fully mismatching rows — a third of that
 *      where the first unmatched row is uniform (a blank separator).
 *   3. A delete next to an insert is folded: the rows are paired and compared.
 *   4. Each offset change is moved to the last row that splits its stretch best
 *      (so the rows after it are the ones it explains) and re-decided on pixels: it may stay only
 *      when at least ALIGN.minRun rows follow it and those rows differ at most
 *      half as much under the new offset as under the one before, and the set
 *      that stays is the one with the lowest count of step 5.
 *   5. The count: matched rows by pixelmatch (same --pm-threshold); every A row
 *      without a B row (deleted) and every B row without an A row (inserted) as
 *      a fully differing row. Denominator = width × (A rows + inserted B rows −
 *      masked rows). --mask rows are painted flat before step 1 (A's range in A,
 *      B's range in B) and excluded: a matched pair when either row is masked,
 *      an unmatched row when it is masked on its own side.
 *   6. The aligned number is never above the overlap number: when it is not
 *      lower, or the map is implausible (more than ALIGN.maxSteps steps, or
 *      back-and-forth shifts above ALIGN.maxChurn rows), `aligned.used` is false,
 *      `aligned.reason` says why and the aligned figures equal the overlap ones.
 * steps[] = { y, shift, cumulative }: y in A's rows; the shifts sum to
 * B height − A height. What alignment cannot hide: a changed region is either
 * compared in place or counted whole as unmatched rows. Its limit: content
 * that really is a vertical move of the same pixels reads as a move.
 *
 * Example:
 *   node skills/replica/scripts/pixel-compare.mjs \
 *     stardust/replica/gates/home-1440/live.png \
 *     stardust/replica/gates/home-1440/proto.png \
 *     --out stardust/replica/gates/home-1440/diff.png
 *
 * Requires: pixelmatch, pngjs (project devDependencies).
 * Exit codes: 0 under threshold, 1 error, 2 over threshold (gate FAIL; on the
 * overlap number unless --verdict aligned; under --offset-max also offsets over
 * the bound), 124 deadline exceeded (see
 * --timeout; not a measurement).
 * Note: the height delta does NOT affect the exit code — the SKILL gate
 * requires height Δ ≈ 0 separately; a large delta is printed as a warning
 * because the overlap-crop can make the % look artificially healthy.
 */

/* eslint-disable import/no-extraneous-dependencies, import/extensions, no-restricted-syntax, brace-style, object-curly-newline, max-len */
// pngjs and pixelmatch load inside main(): the aligner below is pure and its test imports this module without them.
import { readFileSync, writeFileSync, mkdirSync, realpathSync, rmSync } from 'fs';
import { dirname } from 'path';
import { fileURLToPath } from 'url';
import { runCapped, DEADLINE_EXIT } from './run-capped.mjs';

const HELP = `pixel-compare — pixelmatch two stitched full-page PNGs with per-band breakdown

Usage: node pixel-compare.mjs <a.png> <b.png> [options]
  --out <diff.png>    diff image path (default diff.png)
  --threshold <pct>   pass bar as percent; exit 2 above it (default 10)
  --band <px>         band height for the breakdown (default 500)
  --pm-threshold <n>  pixelmatch per-pixel color threshold (default 0.1)
  --mask <yA:h[@yB]>  exclude a row band (authored-volatile region) on both sides;
                      repeatable / comma list; yB defaults to yA
  --json              machine-readable summary on stdout
  --text-boxes <json> also report the % over the origin's text boxes only — auxiliary (#125 D4)
  --align             also compute the ALIGNED number: a piecewise-constant vertical offset map
                      between A and B (rows inserted / deleted in B), so one shift near the top
                      does not make every row below it differ. Adds \`aligned\` to --json
                      { used, pct, differingPixels, compared, steps: [{ y, shift, cumulative }],
                      maxOffset, totalShift, insertedRows, deletedRows, bands, diff, reason }, one
                      "aligned:" line and a per-band aligned % to the text output, and
                      <out stem>-aligned.png (A's coordinates; unmatched rows solid red).
                      Unmatched rows count as fully differing; denominator = width x (A rows +
                      inserted B rows - masked rows). Never above the unaligned number: when it
                      is not lower or the map is implausible, used is false and it equals it.
  --align-max <px>    largest |offset| the map may reach (default 400)
  --verdict <which>   unaligned (default) | aligned: the number the exit code and \`pass\` use
                      against --threshold; aligned implies --align
  --offset-max <b>    the gates' pixel criterion (implies --verdict aligned): pass = aligned % <= threshold
                      AND aligned.totalShift <= the bound — <b> px, or a stage: prototype = 8,
                      published = the larger of 8 and 1 % of A's height. Over the bound the reason is
                      "offsets: <n> step(s), <px>px total — …" (the fix list), not a percentage; alignment
                      not used → the unaligned rule. JSON: offsets { bound, totalShift, pass }, reason
  --json-out <file>   also write the --json summary to <file> (text stays on stdout)
  --timeout <s>       hard deadline, exit 124 when hit (default 120; 0 disables)
  --help              this text

Convention: <a.png> = live/source capture, <b.png> = prototype capture.`;

function parseArgs(argv) {
  const rest = argv.slice(2);
  if (rest.includes('--help') || rest.includes('-h')) { console.log(HELP); process.exit(0); }
  const pos = [];
  const opts = { out: 'diff.png', threshold: 10, band: 500, pmThreshold: 0.1, json: false, masks: [], timeout: 120, worker: false, textBoxes: null, align: false, alignMax: 400, verdict: 'unaligned', offsetMax: null, jsonOut: null };
  for (let i = 0; i < rest.length; i += 1) {
    const a = rest[i];
    if (a === '--out') { opts.out = rest[i += 1]; }
    else if (a === '--threshold') { opts.threshold = Number(rest[i += 1]); }
    else if (a === '--band') { opts.band = Number(rest[i += 1]); }
    else if (a === '--pm-threshold') { opts.pmThreshold = Number(rest[i += 1]); }
    else if (a === '--json') { opts.json = true; }
    else if (a === '--timeout') { opts.timeout = Number(rest[i += 1]); }
    else if (a === '--worker') { opts.worker = true; }
    else if (a === '--text-boxes') { opts.textBoxes = rest[i += 1]; }
    else if (a === '--align') { opts.align = true; }
    else if (a === '--align-max') {
      opts.alignMax = Number(rest[i += 1]);
      if (!Number.isInteger(opts.alignMax) || opts.alignMax < 1 || opts.alignMax > 4000) { console.error(`bad --align-max "${rest[i]}" — expected an integer 1..4000\n\n${HELP}`); process.exit(1); }
    }
    else if (a === '--verdict') {
      opts.verdict = rest[i += 1];
      if (opts.verdict !== 'aligned' && opts.verdict !== 'unaligned') { console.error(`bad --verdict "${opts.verdict}" — expected unaligned or aligned\n\n${HELP}`); process.exit(1); }
    }
    else if (a === '--offset-max') {
      const v = rest[i += 1];
      opts.offsetMax = v === 'prototype' || v === 'published' ? v : Number(v);
      if (typeof opts.offsetMax === 'number' && !(Number.isFinite(opts.offsetMax) && opts.offsetMax >= 0 && v !== '' && v !== undefined)) { console.error(`bad --offset-max "${v}" — expected a number of px, prototype or published\n\n${HELP}`); process.exit(1); }
      opts.verdict = 'aligned';
    }
    else if (a === '--json-out') { opts.jsonOut = rest[i += 1]; }
    else if (a === '--mask') {
      for (const spec of rest[i += 1].split(',').map((s) => s.trim()).filter(Boolean)) {
        const m = spec.match(/^(\d+):(\d+)(?:@(\d+))?$/);
        if (!m) { console.error(`bad --mask "${spec}" — expected yA:h or yA:h@yB\n\n${HELP}`); process.exit(1); }
        opts.masks.push({ yA: Number(m[1]), h: Number(m[2]), yB: m[3] === undefined ? Number(m[1]) : Number(m[3]) });
      }
    }
    else if (a.startsWith('--')) { console.error(`unknown flag ${a}\n\n${HELP}`); process.exit(1); }
    else pos.push(a);
  }
  if (opts.verdict === 'aligned') opts.align = true;
  const [aPath, bPath] = pos;
  if (!aPath || !bPath) { console.error(`need <a.png> and <b.png>\n\n${HELP}`); process.exit(1); }
  return { aPath, bPath, opts };
}

// ── Aligned mode (--align; header "Aligned mode") ────────────────────────────
// Pure and deterministic: integer arithmetic, fixed tie-breaks, no pngjs / pixelmatch — the per-pixel rule comes in
// as `countDiff(a, b, out|null, w, rows) → differing pixels` (pixelmatch in main(), a stand-in in the test).
export const ALIGN = {
  buckets: 48, // luminance buckets per row (fewer on narrow images)
  tol: 2, // per-bucket difference ignored as rendering noise
  capPerBucket: 4, // row-pair cost cap = capPerBucket × signature length
  minRun: 24, // rows: a gap costs this many fully mismatching rows to open; a step needs this many rows after it
  flatOpenDiv: 3, // opening a gap on a uniform row costs 1/flatOpenDiv of that
  flatRange: 6, // a row is uniform when its luminance spans at most this
  keepRatio: 0.5, // a step stays when its rows differ at most this share of what they differ under the previous offset
  window: 5, // distinct earlier offsets a segment may fall back to
  maxSteps: 40, // more steps than this = implausible map → used: false
  maxChurn: 600, // back-and-forth rows (Σ|shift| − |Σshift|) above this = implausible map → used: false
};
const NONE = -0x40000000;

function cropWidth(img, w) {
  if (img.width === w) return { width: w, height: img.height, data: img.data };
  const data = Buffer.allocUnsafe(w * img.height * 4);
  for (let y = 0; y < img.height; y += 1) img.data.copy(data, y * w * 4, y * img.width * 4, y * img.width * 4 + w * 4);
  return { width: w, height: img.height, data };
}

// The aligned diff picture beside <out>: <out stem>-aligned.png (diff-report's pickDiff skips it).
export const alignedPathOf = (stem) => `${stem}-aligned.png`;
// A mean colour difference (−255..255) as one signature byte: 128 ± half, clamped — 128 + 128 would wrap to 0.
export const chroma = (mean) => Math.max(0, Math.min(255, 128 + Math.round(mean / 2)));
// Per-row signature of an RGBA buffer: K luminance means, then C (R−G) and C (B−G) means; `flat` marks uniform rows.
export function rowSignatures(data, w, h) {
  const K = Math.max(1, Math.min(ALIGN.buckets, w >> 2)); const C = Math.max(1, K >> 2); const S = K + 2 * C;
  const sig = new Uint8Array(h * S); const flat = new Uint8Array(h);
  const kOf = new Uint8Array(w); const cOf = new Uint8Array(w); const kN = new Int32Array(K); const cN = new Int32Array(C);
  for (let x = 0; x < w; x += 1) { kOf[x] = Math.min(K - 1, Math.floor((x * K) / w)); cOf[x] = Math.min(C - 1, Math.floor((x * C) / w)); kN[kOf[x]] += 1; cN[cOf[x]] += 1; }
  const lum = new Int32Array(K); const cr = new Int32Array(C); const cb = new Int32Array(C);
  for (let y = 0; y < h; y += 1) {
    lum.fill(0); cr.fill(0); cb.fill(0);
    let lo = 255; let hi = 0; let p = y * w * 4;
    for (let x = 0; x < w; x += 1, p += 4) {
      const r = data[p]; const g = data[p + 1]; const b = data[p + 2];
      const l = (77 * r + 150 * g + 29 * b) >> 8;
      if (l < lo) lo = l; if (l > hi) hi = l;
      lum[kOf[x]] += l; cr[cOf[x]] += r - g; cb[cOf[x]] += b - g;
    }
    const o = y * S;
    for (let k = 0; k < K; k += 1) sig[o + k] = Math.round(lum[k] / kN[k]);
    for (let c = 0; c < C; c += 1) { sig[o + K + c] = chroma(cr[c] / cN[c]); sig[o + K + C + c] = chroma(cb[c] / cN[c]); }
    flat[y] = hi - lo <= ALIGN.flatRange ? 1 : 0;
  }
  return { sig, S, flat, rows: h };
}

// Banded global alignment of A's rows to B's rows, affine gaps. Cell (i, d): i rows of A and i + d rows of B consumed,
// |d| ≤ max. States: 0 = last pair matched, 1 = last A row unmatched (deleted in B), 2 = last B row unmatched
// (inserted in B). Returns, per A row, the offset of the B row it is matched to, or NONE.
export function alignRows(sa, sb, { max = 400 } = {}) {
  const A = sa.sig; const B = sb.sig; const { S } = sa; const fA = sa.flat; const fB = sb.flat;
  const HA = sa.rows; const HB = sb.rows;
  const M = Math.max(1, Math.min(max, Math.max(HA, HB)));
  const n = Math.min(HA, HB + M); // A rows past HB + M can match nothing: they stay unmatched
  const D = 2 * M + 1; const INF = 0x3fffffff; const { tol } = ALIGN;
  const CAP = ALIGN.capPerBucket * S; const EXT = (CAP >> 1) + 1; const OPEN = ALIGN.minRun * CAP; const OPENF = Math.floor(OPEN / ALIGN.flatOpenDiv);
  let pM = new Int32Array(D); let pX = new Int32Array(D); let pY = new Int32Array(D);
  let cM = new Int32Array(D).fill(INF); let cX = new Int32Array(D).fill(INF); let cY = new Int32Array(D).fill(INF);
  const tb = new Uint8Array((n + 1) * D);
  cM[M] = 0;
  for (let di = M + 1; di < D && di - M <= HB; di += 1) {
    const fromM = cM[di - 1] + (fB[di - M - 1] ? OPENF : OPEN); const fromY = cY[di - 1];
    if (fromM <= fromY) { cY[di] = fromM + EXT; } else { cY[di] = fromY + EXT; tb[di] = 2 << 4; }
  }
  for (let i = 1; i <= n; i += 1) {
    let t = pM; pM = cM; cM = t; t = pX; pX = cX; cX = t; t = pY; pY = cY; cY = t;
    cM.fill(INF); cX.fill(INF); cY.fill(INF);
    const lo = Math.max(0, M - i); const hi = Math.min(D - 1, HB - i + M);
    const ao = (i - 1) * S; const oA = fA[i - 1] ? OPENF : OPEN; const row = i * D;
    for (let di = lo; di <= hi; di += 1) {
      const j = i + di - M; let bits = 0;
      if (j >= 1) {
        let best = pM[di]; let st = 0;
        if (pX[di] < best) { best = pX[di]; st = 1; }
        if (pY[di] < best) { best = pY[di]; st = 2; }
        if (best < INF) {
          let c = 0; const bo = (j - 1) * S;
          for (let k = 0; k < S; k += 1) {
            let v = A[ao + k] - B[bo + k]; if (v < 0) v = -v;
            if (v > tol) { c += v - tol; if (c >= CAP) { c = CAP; break; } }
          }
          cM[di] = best + c; bits = st;
        }
      }
      if (di + 1 < D) {
        let best = pM[di + 1] + oA; let st = 0;
        if (pX[di + 1] < best) { best = pX[di + 1]; st = 1; }
        if (pY[di + 1] + oA < best) { best = pY[di + 1] + oA; st = 2; }
        if (best < INF) { cX[di] = best + EXT; bits |= st << 2; }
      }
      if (j >= 1 && di > lo) {
        const oB = fB[j - 1] ? OPENF : OPEN;
        let best = cM[di - 1] + oB; let st = 0;
        if (cX[di - 1] + oB < best) { best = cX[di - 1] + oB; st = 1; }
        if (cY[di - 1] < best) { best = cY[di - 1]; st = 2; }
        if (best < INF) { cY[di] = best + EXT; bits |= st << 4; }
      }
      tb[row + di] = bits;
    }
  }
  // end: all n rows of A consumed; B rows left over are one more gap
  let endCost = INF; let di = M; let st = 0;
  const lo = Math.max(0, M - n); const hi = Math.min(D - 1, HB - n + M);
  for (let e = lo; e <= hi; e += 1) {
    const j = n + e - M; const left = HB - j;
    const tailOpen = left > 0 ? (fB[j] ? OPENF : OPEN) + EXT * left : 0;
    const cand = [cM[e] + tailOpen, cX[e] + tailOpen, cY[e] + (left > 0 ? EXT * left : 0)];
    for (let s = 0; s < 3; s += 1) if (cand[s] < endCost) { endCost = cand[s]; di = e; st = s; }
  }
  const dOf = new Int32Array(HA).fill(NONE);
  let i = n;
  while (i > 0 || di !== M) {
    const bits = tb[i * D + di];
    if (st === 0) { dOf[i - 1] = di - M; st = bits & 3; i -= 1; }
    else if (st === 1) { st = (bits >> 2) & 3; i -= 1; di += 1; }
    else { st = (bits >> 4) & 3; di -= 1; }
  }
  return { dOf, cost: endCost };
}

// Matched runs → breakpoints { a0: first A row of the run, d: its offset }, in order, d differing from the run before.
export function offsetBreakpoints(dOf) {
  const bps = []; let d = 0;
  for (let i = 0; i < dOf.length; i += 1) {
    if (dOf[i] === NONE || dOf[i] === d) continue;
    d = dOf[i]; bps.push({ a0: i, d });
  }
  return bps;
}

// Where exactly a change takes effect is a tie wherever the rows match under neither offset (a replaced section) or
// under both (a blank band): each breakpoint is moved to the LAST row that splits its stretch best between the
// offset before and its own, so the rows after it are the ones that match under the new offset — the evidence
// chooseOffsets asks for.
export function settleBreakpoints(bps, sa, sb) {
  const { S } = sa; const CAP = ALIGN.capPerBucket * S; const HB = sb.rows;
  const cost = (i, d) => {
    const j = i + d; if (j < 0 || j >= HB) return CAP;
    let c = 0; const ao = i * S; const bo = j * S;
    for (let k = 0; k < S; k += 1) { let v = sa.sig[ao + k] - sb.sig[bo + k]; if (v < 0) v = -v; if (v > ALIGN.tol) { c += v - ALIGN.tol; if (c >= CAP) return CAP; } }
    return c;
  };
  const out = []; let dp = 0;
  bps.forEach(({ a0, d }, k) => {
    const end = k + 1 < bps.length ? bps[k + 1].a0 : sa.rows;
    let own = 0; for (let i = a0; i < end; i += 1) own += cost(i, d);
    let best = own; let at = a0; let run = own;
    for (let r = a0 + 1; r <= end; r += 1) { run += cost(r - 1, dp) - cost(r - 1, d); if (run <= best) { best = run; at = r; } }
    if (at < end) out.push({ a0: at, d });
    dp = d;
  });
  return out;
}

// Step 4 of the header: which offset changes stay, decided on pixels. Segment k = the rows from breakpoint k to the
// next one; it may run at its own offset or at one of the offsets before it (the last ALIGN.window distinct ones,
// and 0). A segment may CHANGE offset only on evidence (ALIGN.minRun rows, differing at most ALIGN.keepRatio of what
// they differ under the offset it would otherwise keep), and the choice minimises the number that is reported:
// differing pixels + width × rows left unmatched by every change and by the height difference at the end.
// evalRows(y0, y1, d) → differing pixels of A rows y0..y1 against B rows y0+d..y1+d.
export function chooseOffsets(bps, HA, HB, w, evalRows) {
  if (!bps.length) return [];
  const segs = [{ y0: 0, y1: bps[0].a0, cands: [0] }];
  const recent = [0];
  bps.forEach(({ a0, d }, k) => {
    const at = recent.indexOf(d); if (at >= 0) recent.splice(at, 1);
    recent.push(d);
    const cands = recent.slice(-ALIGN.window); if (!cands.includes(0)) cands.unshift(0);
    segs.push({ y0: a0, y1: k + 1 < bps.length ? bps[k + 1].a0 : HA, cands });
  });
  let prevCost = new Map([[0, 0]]); const back = [];
  for (const seg of segs) {
    const memo = new Map();
    const ev = (d) => { if (!memo.has(d)) memo.set(d, evalRows(seg.y0, seg.y1, d)); return memo.get(d); };
    const cost = new Map(); const from = new Map();
    for (const c of seg.cands) {
      let best = Infinity; let bestP = null;
      for (const [p, pc] of prevCost) {
        let t;
        if (p === c) t = pc;
        else if (seg.y1 - seg.y0 >= ALIGN.minRun && ev(p) > 0 && ev(c) <= ev(p) * ALIGN.keepRatio) t = pc + Math.abs(c - p) * w;
        else continue;
        if (t < best || (t === best && p === c)) { best = t; bestP = p; }
      }
      if (bestP !== null) { cost.set(c, best + ev(c)); from.set(c, bestP); }
    }
    prevCost = cost; back.push(from);
  }
  let end = 0; let endCost = Infinity;
  for (const [c, cc] of prevCost) { const t = cc + Math.abs(HB - HA - c) * w; if (t < endCost) { endCost = t; end = c; } }
  const chosen = new Array(segs.length);
  for (let k = segs.length - 1, c = end; k >= 0; k -= 1) { chosen[k] = c; c = back[k].get(c); }
  const kept = []; let dp = 0;
  for (let k = 1; k < segs.length; k += 1) if (chosen[k] !== dp) { dp = chosen[k]; kept.push({ a0: segs[k].y0, d: dp }); }
  return kept;
}

// Breakpoints → the row map (B row per A row, −1 = no counterpart). A delete next to an insert is folded here: the
// run before a breakpoint is extended over the rows both sides have, so a boundary is a pure insert or a pure delete.
export function offsetMap(bps, HA, HB) {
  const mapB = new Int32Array(HA).fill(-1);
  let lastJ = -1; let dp = 0; let from = 0;
  const fill = (y0, y1, d) => {
    for (let i = y0; i < y1; i += 1) { const j = i + d; if (j > lastJ && j < HB) { mapB[i] = j; lastJ = j; } }
  };
  for (const { a0, d } of bps) {
    const y = d > dp ? a0 : Math.max(from, a0 - (dp - d));
    fill(from, y, dp);
    from = y + Math.max(0, dp - d); dp = d;
  }
  fill(Math.min(from, HA), HA, dp);
  return mapB;
}

// The row map → steps { y, shift, cumulative } (their shifts sum to HB − HA), the inserts (B rows without an A row,
// attributed to the A row they precede) and the row counts.
export function stepsOf(mapB, HA, HB) {
  const steps = []; const inserts = [];
  let cum = 0; let lastJ = -1; let del = 0; let insertedRows = 0; let deletedRows = 0; let maxOffset = 0; let totalShift = 0;
  const boundary = (i, j) => {
    const ins = j - lastJ - 1;
    if (ins > 0) { inserts.push({ y: i, j0: lastJ + 1, count: ins }); insertedRows += ins; }
    const shift = ins - del;
    if (shift !== 0) {
      cum += shift; steps.push({ y: i - del, shift, cumulative: cum });
      totalShift += Math.abs(shift); if (Math.abs(cum) > maxOffset) maxOffset = Math.abs(cum);
    }
    del = 0;
  };
  for (let i = 0; i < HA; i += 1) {
    const j = mapB[i];
    if (j < 0) { del += 1; deletedRows += 1; continue; }
    boundary(i, j); lastJ = j;
  }
  boundary(HA, HB);
  return { steps, inserts, insertedRows, deletedRows, maxOffset, totalShift };
}

const isRed = (data, i) => data[i] === 255 && data[i + 1] < 100;

// The aligned candidate for two same-width RGBA buffers (masked rows already painted flat by the caller).
// Returns the map's steps and the count of header step 5; the caller decides `used` (never-worse, plausibility).
export function alignedCompare(A, B, w, HA, HB, { alignMax = 400, band = 500, maskA = null, maskB = null, countDiff }) {
  const stride = w * 4;
  const evalRows = (y0, y1, d) => {
    const s = Math.max(y0, -d); const e = Math.min(y1, HB - d); // rows whose B row exists
    if (e <= s) return (y1 - y0) * w;
    return ((s - y0) + (y1 - e)) * w + countDiff(A.subarray(s * stride, e * stride), B.subarray((s + d) * stride, (e + d) * stride), null, w, e - s);
  };
  const sa = rowSignatures(A, w, HA); const sb = rowSignatures(B, w, HB);
  const { dOf } = alignRows(sa, sb, { max: alignMax });
  const mapB = offsetMap(chooseOffsets(settleBreakpoints(offsetBreakpoints(dOf), sa, sb), HA, HB, w, evalRows), HA, HB);
  const shape = stepsOf(mapB, HA, HB);
  // B in A's coordinates; an unmatched A row is compared with itself and counted whole below
  const moved = Buffer.allocUnsafe(HA * stride);
  for (let i = 0; i < HA;) {
    let e = i + 1; const j = mapB[i];
    while (e < HA && (j < 0 ? mapB[e] < 0 : mapB[e] === j + (e - i))) e += 1;
    (j < 0 ? A : B).copy(moved, i * stride, (j < 0 ? i : j) * stride, (j < 0 ? e : j + (e - i)) * stride);
    i = e;
  }
  const diff = Buffer.alloc(HA * stride);
  if (HA > 0) countDiff(A, moved, diff, w, HA);
  const rowDiff = new Int32Array(HA); const rowDen = new Uint8Array(HA);
  let differing = 0; let rows = 0;
  for (let i = 0; i < HA; i += 1) {
    const j = mapB[i]; const o = i * stride;
    if ((maskA && maskA[i]) || (j >= 0 && maskB && maskB[j])) { diff.fill(128, o, o + stride); for (let x = 3; x < stride; x += 4) diff[o + x] = 255; continue; }
    let c = 0;
    if (j < 0) { c = w; for (let x = 0; x < stride; x += 4) { diff[o + x] = 255; diff[o + x + 1] = 0; diff[o + x + 2] = 0; diff[o + x + 3] = 255; } }
    else for (let x = 0; x < stride; x += 4) if (isRed(diff, o + x)) c += 1;
    rowDiff[i] = c; rowDen[i] = 1; differing += c; rows += 1;
  }
  const insAt = new Int32Array(HA + 1); // counted inserted rows per A row they precede
  for (const ins of shape.inserts) {
    let c = 0;
    for (let j = ins.j0; j < ins.j0 + ins.count; j += 1) if (!(maskB && maskB[j])) c += 1;
    insAt[ins.y] += c; differing += c * w; rows += c;
    // marker: a blue flag on the left edge where B has rows A lacks (drawn after the count)
    for (let y = ins.y; y < Math.min(HA, ins.y + Math.max(2, Math.min(c, 24))); y += 1) for (let x = 0; x < Math.min(w, 12); x += 1) { const p = y * stride + x * 4; diff[p] = 0; diff[p + 1] = 90; diff[p + 2] = 255; diff[p + 3] = 255; }
  }
  const bands = [];
  for (let y0 = 0; y0 < HA; y0 += band) {
    const y1 = Math.min(HA, y0 + band); let num = 0; let den = 0;
    for (let y = y0; y < y1; y += 1) { num += rowDiff[y] + insAt[y] * w; den += (rowDen[y] + insAt[y]) * w; }
    if (y1 === HA) { num += insAt[HA] * w; den += insAt[HA] * w; }
    bands.push({ y0, y1, pct: den ? (100 * num) / den : 0 });
  }
  const { steps, insertedRows, deletedRows, maxOffset, totalShift } = shape;
  return { differing, rows, pct: rows ? (100 * differing) / (rows * w) : 0, steps, insertedRows, deletedRows, maxOffset, totalShift, bands, diff };
}

// Header step 6: the reason a candidate map is not used, or null.
export function alignVerdict(cand, unalignedPct, heightDiff) {
  if (cand.steps.length > ALIGN.maxSteps) return `implausible map: ${cand.steps.length} offset steps (limit ${ALIGN.maxSteps})`;
  const churn = cand.totalShift - Math.abs(heightDiff);
  if (churn > ALIGN.maxChurn) return `implausible map: ${churn} rows of back-and-forth shift (limit ${ALIGN.maxChurn})`;
  if (!(cand.pct < unalignedPct)) return cand.steps.length ? 'aligned number not lower than the unaligned one' : 'no offset step found';
  return null;
}

const signed = (n) => `${n < 0 ? '−' : '+'}${Math.abs(n)}`;
export function alignedLine(al, pct) {
  if (!al.used) return `aligned: ${al.pct.toFixed(2)}% = unaligned — alignment not used (${al.reason}${al.candidate ? `; candidate ${al.candidate.pct.toFixed(2)}% with ${al.candidate.steps} steps` : ''})`;
  const shown = al.steps.slice(0, 8).map((s) => `${signed(s.shift)}px at y=${s.y}`).join(', ');
  return `aligned: ${al.pct.toFixed(2)}% (unaligned ${pct.toFixed(2)}%) — ${al.steps.length} offset step${al.steps.length === 1 ? '' : 's'}: ${shown}${al.steps.length > 8 ? ', …' : ''}${al.insertedRows || al.deletedRows ? `  [${al.insertedRows} rows only in B, ${al.deletedRows} only in A — counted as differing]` : ''}`;
}

// ── The gates' pixel criterion (--offset-max; header) — its one definition, read by gate.sh through this CLI and by
// gate-all.mjs through the import. Pure: `px` is this script's --json summary (an older one without `aligned` reads
// as alignment not used).
export const OFFSETS = { px: 8, share: 0.01, shown: 6, kept: 12 };
/** The bound in px: a number as given; 'prototype' → 8; 'published' → the larger of 8 and 1 % of the origin height; null → no bound. */
export function offsetBound(spec, originHeight = 0) {
  if (spec === null || spec === undefined || spec === '') return null;
  if (spec === 'prototype') return OFFSETS.px;
  if (spec === 'published') return Math.max(OFFSETS.px, Math.round(OFFSETS.share * (Number(originHeight) || 0)));
  return Number(spec);
}
/** `−5px at y=103, −20px at y=2125, … 2 more` — at most `max` steps. */
export function offsetsText(steps, max = OFFSETS.shown) {
  const list = steps || [];
  return `${list.slice(0, max).map((s) => `${signed(s.shift)}px at y=${s.y}`).join(', ')}${list.length > max ? `, … ${list.length - max} more` : ''}`;
}
/**
 * pixelVerdict(px, { threshold, offsetMax }) → { pass, used, pct, alignedPct, totalShift, steps (≤ 12), stepCount,
 * bound, offsetsPass, offsets, reason, line }. Used: aligned % ≤ threshold AND totalShift ≤ bound (offsetMax: px |
 * 'prototype' | 'published' | null = no bound). Not used: unaligned % ≤ threshold. `reason` (null on a pass) names the
 * offsets when they alone fail, else the percentage; `offsets` is the step list as text ('' when none).
 */
export function pixelVerdict(px, { threshold = 10, offsetMax = null } = {}) {
  const al = px && px.aligned && px.aligned.used ? px.aligned : null;
  const pct = px.pct; const alignedPct = al ? al.pct : pct;
  const all = al ? al.steps || [] : []; const totalShift = al ? al.totalShift || 0 : 0;
  const originH = px.compared && Number.isFinite(px.heightDelta) ? px.compared.height + Math.max(0, px.heightDelta) : 0;
  const bound = al ? offsetBound(offsetMax, originH) : null;
  const pctPass = alignedPct <= threshold; const offsetsPass = bound === null || totalShift <= bound;
  const offsets = all.length ? `offsets: ${all.length} step(s), ${totalShift}px total — ${offsetsText(all)}${bound === null ? '' : ` (bound ${bound}px)`}` : '';
  const shown = al ? `aligned ${alignedPct}% (unaligned ${pct}%)` : `${pct}%`;
  const reason = !pctPass ? `pixel ${shown} > ${threshold}%` : !offsetsPass ? offsets : null;
  const pass = pctPass && offsetsPass;
  const head = al ? `pixel: aligned ${alignedPct.toFixed(2)}% (unaligned ${pct.toFixed(2)}%)` : `pixel: ${pct.toFixed(2)}% (alignment not used — the unaligned number rules)`;
  const line = `${head}${pctPass ? '' : ` > ${threshold}%`} → ${pass ? 'PASS' : 'FAIL'}${offsets ? ` — ${offsets}` : ''}`;
  return { pass, used: !!al, pct, alignedPct, totalShift, steps: all.slice(0, OFFSETS.kept), stepCount: all.length, bound, offsetsPass, offsets, reason, line };
}

// --text-boxes: the share of differing pixels inside the origin's text boxes
// (A's page coordinates), read off the diff image already computed over the
// overlap crop. Masked rows are skipped like everywhere else. Exported for the test.
export function textBoxPct(diff, boxes, w, h, masked) {
  let total = 0; let differing = 0;
  for (const bx of boxes) {
    const x0 = Math.max(0, Math.floor(bx.x)); const x1 = Math.min(w, Math.ceil(bx.x + bx.w));
    const y0 = Math.max(0, Math.floor(bx.y)); const y1 = Math.min(h, Math.ceil(bx.y + bx.h));
    for (let y = y0; y < y1; y += 1) {
      if (masked && masked[y]) continue;
      for (let x = x0; x < x1; x += 1) {
        total += 1;
        const i = (y * w + x) * 4;
        if (diff.data[i] === 255 && diff.data[i + 1] < 100) differing += 1;
      }
    }
  }
  return { boxes: boxes.length, pixels: total, pct: total ? (100 * differing) / total : 0 };
}

function readTextBoxes(path) {
  const raw = JSON.parse(readFileSync(path, 'utf8'));
  const list = Array.isArray(raw) ? raw : (raw.textBoxes || raw.boxes || []);
  return list.filter((b) => b && Number.isFinite(b.x) && Number.isFinite(b.y) && b.w > 0 && b.h > 0);
}

// --timeout: the compare is synchronous end to end, so the deadline lives in a
// supervising copy of this process: the parent re-spawns itself with --worker
// under run-capped and mirrors the worker's exit code (124 on the deadline).
async function supervise(timeoutSec) {
  const args = [fileURLToPath(import.meta.url), '--worker', ...process.argv.slice(2).filter((x, i, arr) => !(x === '--timeout' || arr[i - 1] === '--timeout'))];
  const code = await runCapped(process.execPath, args, { timeoutSec, label: 'pixel-compare' });
  if (code === DEADLINE_EXIT) console.error(`pixel-compare: no verdict — deadline ${timeoutSec}s exceeded (exit ${DEADLINE_EXIT}). Not a gate FAIL: re-run, or pass --timeout <s> above ${timeoutSec} for a legitimately huge capture.`);
  process.exitCode = code;
}

async function main() {
  const { aPath, bPath, opts } = parseArgs(process.argv);
  if (!opts.worker && opts.timeout > 0) { await supervise(opts.timeout); return; }
  const { PNG } = await import('pngjs');
  const { default: pixelmatch } = await import('pixelmatch');
  const a = PNG.sync.read(readFileSync(aPath));
  const b = PNG.sync.read(readFileSync(bPath));
  const w = Math.min(a.width, b.width);
  const h = Math.min(a.height, b.height);
  const heightDelta = a.height - b.height;
  const stem = opts.out.replace(/\.png$/i, '');
  mkdirSync(dirname(opts.out), { recursive: true });

  // Full-height, width-cropped sides; the overlap compare reads their first h rows.
  const fa = cropWidth(a, w); const fb = cropWidth(b, w);
  // --align runs first: it needs each side masked at its OWN rows, and the union painted below is a superset.
  let cand = null;
  if (opts.align) {
    const maskA = new Uint8Array(a.height); const maskB = new Uint8Array(b.height);
    for (const mk of opts.masks) {
      for (let y = Math.max(0, mk.yA); y < Math.min(a.height, mk.yA + mk.h); y += 1) { maskA[y] = 1; fa.data.fill(128, y * w * 4, (y + 1) * w * 4); }
      for (let y = Math.max(0, mk.yB); y < Math.min(b.height, mk.yB + mk.h); y += 1) { maskB[y] = 1; fb.data.fill(128, y * w * 4, (y + 1) * w * 4); }
    }
    cand = alignedCompare(fa.data, fb.data, w, a.height, b.height, { alignMax: opts.alignMax, band: opts.band, maskA, maskB, countDiff: (x, y, out, ww, hh) => pixelmatch(x, y, out, ww, hh, { threshold: opts.pmThreshold }) });
  }

  const ca = { data: fa.data.subarray(0, h * w * 4) };
  const cb = { data: fb.data.subarray(0, h * w * 4) };
  // --mask: neutralise authored-volatile row bands. The masked rows are painted
  // one flat colour on BOTH sides (so they can never differ) and removed from the
  // denominator. When yA ≠ yB the UNION of both row ranges is masked on both
  // sides — masking each side at its own offset would compare grey against real
  // content on the other side and manufacture a false diff.
  const masked = new Uint8Array(h);
  for (const mk of opts.masks) {
    for (const y0 of [mk.yA, mk.yB]) for (let y = Math.max(0, y0); y < Math.min(h, y0 + mk.h); y += 1) masked[y] = 1;
  }
  let maskedRows = 0;
  for (let y = 0; y < h; y += 1) {
    if (!masked[y]) continue;
    maskedRows += 1;
    for (const img of [ca, cb]) img.data.fill(128, y * w * 4, (y + 1) * w * 4);
  }
  const diff = new PNG({ width: w, height: h });
  const n = pixelmatch(ca.data, cb.data, diff.data, w, h, { threshold: opts.pmThreshold });
  writeFileSync(opts.out, PNG.sync.write(diff));
  const denom = w * (h - maskedRows);
  const pct = denom > 0 ? (100 * n) / denom : 0;

  // Per-band breakdown: count pixelmatch's red diff pixels (anti-aliased
  // pixels are drawn yellow and are NOT counted — matches pixelmatch's own count).
  const bands = [];
  for (let y0 = 0; y0 < h; y0 += opts.band) {
    const hh = Math.min(opts.band, h - y0);
    let count = 0;
    for (let y = y0; y < y0 + hh; y += 1) {
      for (let x = 0; x < w; x += 1) {
        const i = (y * w + x) * 4;
        if (diff.data[i] === 255 && diff.data[i + 1] < 100) count += 1;
      }
    }
    bands.push({ y0, y1: y0 + hh, pct: (100 * count) / (w * hh) });
  }

  // --align: the candidate is used only when it is plausible and LOWER; otherwise the aligned figures are the overlap ones.
  let aligned = null;
  if (cand) {
    const reason = alignVerdict(cand, pct, b.height - a.height);
    const r1 = (x) => Number(x.toFixed(1));
    if (reason) {
      rmSync(alignedPathOf(stem), { force: true }); // an earlier run's aligned picture is not this run's
      aligned = { used: false, pct: Number(pct.toFixed(2)), differingPixels: n, compared: { width: w, height: h, mode: 'overlap' }, steps: [], maxOffset: 0, totalShift: 0, insertedRows: 0, deletedRows: 0, bands: bands.map((x) => ({ y0: x.y0, y1: x.y1, pct: r1(x.pct), unaligned: r1(x.pct) })), diff: null, reason, candidate: { pct: Number(cand.pct.toFixed(2)), steps: cand.steps.length, totalShift: cand.totalShift } };
    } else {
      const alignedOut = alignedPathOf(stem);
      writeFileSync(alignedOut, PNG.sync.write({ width: w, height: a.height, data: cand.diff }));
      aligned = { used: true, pct: Number(cand.pct.toFixed(2)), differingPixels: cand.differing, compared: { width: w, height: cand.rows, mode: 'aligned' }, steps: cand.steps, maxOffset: cand.maxOffset, totalShift: cand.totalShift, insertedRows: cand.insertedRows, deletedRows: cand.deletedRows, bands: cand.bands.map((x, i) => ({ y0: x.y0, y1: x.y1, pct: r1(x.pct), unaligned: bands[i] && bands[i].y1 === x.y1 ? r1(bands[i].pct) : null })), diff: alignedOut, reason: null };
    }
  }

  // --offset-max: the gates' criterion (pixelVerdict) decides; else the chosen number against the threshold.
  const round2 = (x) => Number(x.toFixed(2));
  const crit = opts.offsetMax === null ? null : pixelVerdict({ pct: round2(pct), heightDelta, compared: { width: w, height: h }, aligned }, { threshold: opts.threshold, offsetMax: opts.offsetMax });
  const pass = crit ? crit.pass : (opts.verdict === 'aligned' ? aligned.pct : pct) <= opts.threshold;
  // Auxiliary number (never the verdict — header): --text-boxes text-only %.
  const text = opts.textBoxes ? textBoxPct(diff, readTextBoxes(opts.textBoxes), w, h, masked) : null;
  const summary = () => JSON.stringify({ a: aPath, b: bPath, compared: { width: w, height: h, mode: 'overlap' }, heightDelta, differingPixels: n, pct: Number(pct.toFixed(2)), threshold: opts.threshold, pass, diff: opts.out, masks: opts.masks, maskedRows, textPct: text ? Number(text.pct.toFixed(2)) : null, textBoxes: text ? text.boxes : null, textPixels: text ? text.pixels : null, bands: bands.map((x) => ({ ...x, pct: Number(x.pct.toFixed(1)) })), ...(aligned ? { verdict: opts.verdict, aligned } : {}), ...(crit ? { offsets: { bound: crit.bound, totalShift: crit.totalShift, pass: crit.offsetsPass }, reason: crit.reason } : {}) }, null, 2);
  if (opts.jsonOut) writeFileSync(opts.jsonOut, `${summary()}\n`);
  if (opts.json) {
    console.log(summary());
  } else {
    console.log(`A ${a.width}x${a.height}  B ${b.width}x${b.height}  → compare ${w}x${h}, height delta ${heightDelta}px`);
    if (Math.abs(heightDelta) > 8) console.log(`  ⚠ height delta ${heightDelta}px — overlap-crop hides the tail; fix heights before trusting the %`);
    console.log(`differing pixels: ${n} / ${denom} = ${pct.toFixed(2)}%  (threshold ${opts.threshold}%) → ${pass ? 'PASS' : 'FAIL'}${maskedRows ? `  [MASKED ${maskedRows} rows: ${opts.masks.map((m) => `${m.yA}:${m.h}${m.yB !== m.yA ? `@${m.yB}` : ''}`).join(', ')} — authored-volatile, excluded]` : ''}`);
    if (aligned) console.log(`${alignedLine(aligned, pct)}${opts.verdict === 'aligned' ? '  [verdict on the aligned number]' : ''}`);
    if (crit) console.log(crit.line);
    if (text) console.log(`  text-boxes only: ${text.pct.toFixed(2)}% over ${text.boxes} boxes / ${text.pixels} px — auxiliary (#125 D4)`);
    console.log(`diff image: ${opts.out}${aligned && aligned.used ? `  aligned: ${aligned.diff}` : ''}`);
    const ab = aligned && aligned.used ? aligned.bands : null;
    for (let i = 0; i < Math.max(bands.length, ab ? ab.length : 0); i += 1) {
      const bd = bands[i]; const al = ab && ab[i];
      const y0 = bd ? bd.y0 : al.y0; const y1 = al && (!bd || al.y1 > bd.y1) ? al.y1 : bd.y1;
      console.log(`  y ${String(y0).padStart(6)}–${y1}: ${bd ? `${bd.pct.toFixed(1)}%` : '—'}${bd && bd.pct > 15 ? '  ◄◄ hot band' : ''}${al ? `  aligned ${al.pct.toFixed(1)}%${al.pct > 15 ? '  ◄◄ still differs' : ''}` : ''}`);
    }
  }
  // Never process.exit() here — see the header: forcing exit after the compare
  // hung Node's platform shutdown; the loop has nothing left and drains at once.
  process.exitCode = pass ? 0 : 2;
}

// Main-module guard by real path: the contract test imports textBoxPct without running a compare.
function safeRealpath(p) { try { return realpathSync(p); } catch { return p; } }
if (process.argv[1] && fileURLToPath(import.meta.url) === safeRealpath(process.argv[1])) {
  main().catch((e) => { console.error(`pixel-compare error: ${e.message}`); process.exit(1); });
}

skills

README.md

tile.json