@g9tm/app-pilot-cli 0.0.0-stage → 0.1.0

package/src/visual.mjs

@@ -0,0 +1,401 @@
+// Visual comparison (plan §5.4): a screenshot against an approved reference, per platform, theme and language.
+//
+// No dependency, on purpose: the CLI has none. PNG is read and written with node:zlib, and the comparison is the
+// pixelmatch method (YIQ colour distance with a perceptual threshold, anti-aliased edge pixels detected and not
+// counted). The screenshot must be lossless: a JPEG's block noise would be "a difference" everywhere, so `capture`
+// takes the OS's own PNG (adb screencap -p, simctl io screenshot) and never the bridge's JPEG ui.screenshot.
+//
+// Layout of the references (g9pilot.json "visual": { "dir", "variant", "threshold", "maxDiffRatio", "masks" }):
+//   <dir>/<variant>/<name>.png        the approved reference
+//   <dir>/<variant>/<name>.new.png    the last capture that did not match (or had no reference yet)
+//   <dir>/<variant>/<name>.diff.png   what differed: red = counted, yellow = anti-aliasing, grey = the unchanged page
+// Approving moves .new.png over .png. Nothing here commits.
+import fs from 'node:fs';
+import path from 'node:path';
+import zlib from 'node:zlib';
+import { execFileSync } from 'node:child_process';
+
+const SIGNATURE = [137, 80, 78, 71, 13, 10, 26, 10];
+
+// ---------------------------------------------------------------- PNG
+
+/** PNG bytes → { width, height, data: RGBA Uint8Array }. 8-bit grey, grey+alpha, RGB, RGBA and palette; no interlace. */
+export function decodePng(buffer) {
+  const buf = Buffer.from(buffer);
+  for (let i = 0; i < 8; i++) if (buf[i] !== SIGNATURE[i]) throw new Error('not a PNG file');
+  let width = 0;
+  let height = 0;
+  let depth = 0;
+  let colour = 0;
+  let interlace = 0;
+  let palette = null;
+  let paletteAlpha = null;
+  const idat = [];
+  for (let at = 8; at < buf.length; ) {
+    const length = buf.readUInt32BE(at);
+    const type = buf.toString('latin1', at + 4, at + 8);
+    const body = buf.subarray(at + 8, at + 8 + length);
+    if (type === 'IHDR') {
+      width = body.readUInt32BE(0);
+      height = body.readUInt32BE(4);
+      depth = body[8];
+      colour = body[9];
+      interlace = body[12];
+    } else if (type === 'PLTE') palette = body;
+    else if (type === 'tRNS') paletteAlpha = body;
+    else if (type === 'IDAT') idat.push(body);
+    else if (type === 'IEND') break;
+    at += 12 + length;
+  }
+  if (!width || !height) throw new Error('PNG without a header');
+  if (depth !== 8) throw new Error(`PNG bit depth ${depth} is not supported (8 only)`);
+  if (interlace) throw new Error('interlaced PNG is not supported');
+  const channels = { 0: 1, 2: 3, 3: 1, 4: 2, 6: 4 }[colour];
+  if (!channels) throw new Error(`PNG colour type ${colour} is not supported`);
+  if (colour === 3 && !palette) throw new Error('palette PNG without PLTE');
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const stride = width * channels;
+  const pixels = Buffer.alloc(stride * height);
+  let prev = Buffer.alloc(stride);
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * (stride + 1)];
+    const line = raw.subarray(y * (stride + 1) + 1, (y + 1) * (stride + 1));
+    const out = pixels.subarray(y * stride, (y + 1) * stride);
+    for (let x = 0; x < stride; x++) {
+      const a = x >= channels ? out[x - channels] : 0;
+      const b = prev[x];
+      const c = x >= channels ? prev[x - channels] : 0;
+      let v = line[x];
+      if (filter === 1) v += a;
+      else if (filter === 2) v += b;
+      else if (filter === 3) v += (a + b) >> 1;
+      else if (filter === 4) v += paeth(a, b, c);
+      else if (filter !== 0) throw new Error(`PNG row filter ${filter} is unknown`);
+      out[x] = v & 255;
+    }
+    prev = out;
+  }
+  const data = new Uint8Array(width * height * 4);
+  for (let i = 0, p = 0; i < width * height; i++, p += channels) {
+    const o = i * 4;
+    if (colour === 6) {
+      data[o] = pixels[p]; data[o + 1] = pixels[p + 1]; data[o + 2] = pixels[p + 2]; data[o + 3] = pixels[p + 3];
+    } else if (colour === 2) {
+      data[o] = pixels[p]; data[o + 1] = pixels[p + 1]; data[o + 2] = pixels[p + 2]; data[o + 3] = 255;
+    } else if (colour === 0 || colour === 4) {
+      data[o] = data[o + 1] = data[o + 2] = pixels[p];
+      data[o + 3] = colour === 4 ? pixels[p + 1] : 255;
+    } else {
+      const k = pixels[p];
+      data[o] = palette[k * 3]; data[o + 1] = palette[k * 3 + 1]; data[o + 2] = palette[k * 3 + 2];
+      data[o + 3] = paletteAlpha && k < paletteAlpha.length ? paletteAlpha[k] : 255;
+    }
+  }
+  return { width, height, data };
+}
+
+function paeth(a, b, c) {
+  const p = a + b - c;
+  const pa = Math.abs(p - a);
+  const pb = Math.abs(p - b);
+  const pc = Math.abs(p - c);
+  return pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+}
+
+const CRC_TABLE = (() => {
+  const t = new Int32Array(256);
+  for (let n = 0; n < 256; n++) {
+    let c = n;
+    for (let k = 0; k < 8; k++) c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+    t[n] = c;
+  }
+  return t;
+})();
+
+function crc32(bytes) {
+  let c = -1;
+  for (const b of bytes) c = CRC_TABLE[(c ^ b) & 255] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+function chunk(type, body) {
+  const head = Buffer.alloc(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, 'latin1');
+  const tail = Buffer.alloc(4);
+  tail.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+  return Buffer.concat([head, body, tail]);
+}
+
+/** { width, height, data: RGBA } → PNG bytes (RGBA, 8-bit). `filter` (0–4) is for tests of the reader. */
+export function encodePng({ width, height, data }, { filter = 0 } = {}) {
+  const stride = width * 4;
+  const raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = filter;
+    for (let x = 0; x < stride; x++) {
+      const v = data[y * stride + x];
+      const a = x >= 4 ? data[y * stride + x - 4] : 0;
+      const b = y > 0 ? data[(y - 1) * stride + x] : 0;
+      const c = x >= 4 && y > 0 ? data[(y - 1) * stride + x - 4] : 0;
+      const pred = filter === 1 ? a : filter === 2 ? b : filter === 3 ? (a + b) >> 1 : filter === 4 ? paeth(a, b, c) : 0;
+      raw[y * (stride + 1) + 1 + x] = (v - pred) & 255;
+    }
+  }
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width, 0);
+  header.writeUInt32BE(height, 4);
+  header[8] = 8;
+  header[9] = 6;
+  return Buffer.concat([Buffer.from(SIGNATURE), chunk('IHDR', header), chunk('IDAT', zlib.deflateSync(raw)), chunk('IEND', Buffer.alloc(0))]);
+}
+
+// ---------------------------------------------------------------- comparison
+
+/**
+ * Masks → pixel rectangles. A mask is { x, y, w, h }: values of 1 or less are fractions of the image (a status bar is
+ * { x: 0, y: 0, w: 1, h: 0.04 }), larger ones are pixels. Masked pixels are never compared: a clock, a live map.
+ */
+export function maskRects(masks, width, height) {
+  const px = (v, whole) => (Math.abs(v) <= 1 ? Math.round(v * whole) : Math.round(v));
+  return (masks ?? []).map((m) => {
+    const x = Math.max(0, px(m.x ?? 0, width));
+    const y = Math.max(0, px(m.y ?? 0, height));
+    return { x, y, x2: Math.min(width, x + px(m.w ?? 0, width)), y2: Math.min(height, y + px(m.h ?? 0, height)) };
+  });
+}
+
+/**
+ * Two RGBA images of one size → { diff, antialiased, masked, total, ratio, image }. `threshold` 0–1 is the colour
+ * distance a pixel may move unseen (0.1 = the pixelmatch default); `includeAA` counts anti-aliased pixels too.
+ * `image` is the diff picture (RGBA) to write with encodePng.
+ */
+export function compareImages(a, b, { threshold = 0.1, includeAA = false, masks = [] } = {}) {
+  if (a.width !== b.width || a.height !== b.height) {
+    const error = new Error(`sizes differ: reference ${a.width}×${a.height}, capture ${b.width}×${b.height}`);
+    error.code = 'SIZE';
+    throw error;
+  }
+  const { width, height } = a;
+  const rects = maskRects(masks, width, height);
+  const out = new Uint8Array(width * height * 4);
+  const maxDelta = 35215 * threshold * threshold;
+  let diff = 0;
+  let aa = 0;
+  let masked = 0;
+  for (let y = 0; y < height; y++) {
+    for (let x = 0; x < width; x++) {
+      const pos = (y * width + x) * 4;
+      if (rects.some((r) => x >= r.x && x < r.x2 && y >= r.y && y < r.y2)) {
+        masked++;
+        paint(out, pos, 70, 110, 220);
+        continue;
+      }
+      const delta = colourDelta(a.data, b.data, pos, pos, false);
+      if (Math.abs(delta) > maxDelta) {
+        if (!includeAA && (antialiased(a.data, x, y, width, height, b.data) || antialiased(b.data, x, y, width, height, a.data))) {
+          aa++;
+          paint(out, pos, 255, 210, 0);
+        } else {
+          diff++;
+          paint(out, pos, 230, 20, 20);
+        }
+      } else {
+        const grey = 255 - 0.1 * (255 - blend(luma(a.data[pos], a.data[pos + 1], a.data[pos + 2]), a.data[pos + 3] / 255));
+        paint(out, pos, grey, grey, grey);
+      }
+    }
+  }
+  const total = width * height - masked;
+  return { diff, antialiased: aa, masked, total, ratio: total ? diff / total : 0, width, height, image: { width, height, data: out } };
+}
+
+function paint(out, pos, r, g, b) {
+  out[pos] = r;
+  out[pos + 1] = g;
+  out[pos + 2] = b;
+  out[pos + 3] = 255;
+}
+
+const blend = (c, alpha) => 255 + (c - 255) * alpha;
+const luma = (r, g, b) => r * 0.29889531 + g * 0.58662247 + b * 0.11448223;
+const chromaI = (r, g, b) => r * 0.59597799 - g * 0.2741761 - b * 0.32180189;
+const chromaQ = (r, g, b) => r * 0.21147017 - g * 0.52261711 + b * 0.31114694;
+
+/** The YIQ distance of two pixels over white (signed: lighter or darker), or only the brightness part. */
+function colourDelta(img1, img2, k, m, yOnly) {
+  let r1 = img1[k];
+  let g1 = img1[k + 1];
+  let b1 = img1[k + 2];
+  let r2 = img2[m];
+  let g2 = img2[m + 1];
+  let b2 = img2[m + 2];
+  const a1 = img1[k + 3];
+  const a2 = img2[m + 3];
+  if (a1 === a2 && r1 === r2 && g1 === g2 && b1 === b2) return 0;
+  if (a1 < 255) {
+    r1 = blend(r1, a1 / 255);
+    g1 = blend(g1, a1 / 255);
+    b1 = blend(b1, a1 / 255);
+  }
+  if (a2 < 255) {
+    r2 = blend(r2, a2 / 255);
+    g2 = blend(g2, a2 / 255);
+    b2 = blend(b2, a2 / 255);
+  }
+  const y1 = luma(r1, g1, b1);
+  const y2 = luma(r2, g2, b2);
+  const dy = y1 - y2;
+  if (yOnly) return dy;
+  const di = chromaI(r1, g1, b1) - chromaI(r2, g2, b2);
+  const dq = chromaQ(r1, g1, b1) - chromaQ(r2, g2, b2);
+  const d = 0.5053 * dy * dy + 0.299 * di * di + 0.1957 * dq * dq;
+  return y1 > y2 ? -d : d;
+}
+
+/**
+ * Is (x1, y1) an anti-aliased edge pixel? Among its eight neighbours it has both a darker and a lighter extreme, few
+ * equal ones, and the extremes sit in a flat area in both images — the soft rim of a line, not a changed control.
+ */
+function antialiased(img, x1, y1, width, height, img2) {
+  const x0 = Math.max(x1 - 1, 0);
+  const y0 = Math.max(y1 - 1, 0);
+  const x2 = Math.min(x1 + 1, width - 1);
+  const y2 = Math.min(y1 + 1, height - 1);
+  const pos = (y1 * width + x1) * 4;
+  let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;
+  let min = 0;
+  let max = 0;
+  let minX = 0;
+  let minY = 0;
+  let maxX = 0;
+  let maxY = 0;
+  for (let x = x0; x <= x2; x++) {
+    for (let y = y0; y <= y2; y++) {
+      if (x === x1 && y === y1) continue;
+      const delta = colourDelta(img, img, pos, (y * width + x) * 4, true);
+      if (delta === 0) {
+        zeroes++;
+        if (zeroes > 2) return false;
+      } else if (delta < min) {
+        min = delta;
+        minX = x;
+        minY = y;
+      } else if (delta > max) {
+        max = delta;
+        maxX = x;
+        maxY = y;
+      }
+    }
+  }
+  if (min === 0 || max === 0) return false;
+  return (manySiblings(img, minX, minY, width, height) && manySiblings(img2, minX, minY, width, height))
+    || (manySiblings(img, maxX, maxY, width, height) && manySiblings(img2, maxX, maxY, width, height));
+}
+
+function manySiblings(img, x1, y1, width, height) {
+  const x0 = Math.max(x1 - 1, 0);
+  const y0 = Math.max(y1 - 1, 0);
+  const x2 = Math.min(x1 + 1, width - 1);
+  const y2 = Math.min(y1 + 1, height - 1);
+  const pos = (y1 * width + x1) * 4;
+  let zeroes = x1 === x0 || x1 === x2 || y1 === y0 || y1 === y2 ? 1 : 0;
+  for (let x = x0; x <= x2; x++) {
+    for (let y = y0; y <= y2; y++) {
+      if (x === x1 && y === y1) continue;
+      const p = (y * width + x) * 4;
+      if (img[pos] === img[p] && img[pos + 1] === img[p + 1] && img[pos + 2] === img[p + 2] && img[pos + 3] === img[p + 3]) zeroes++;
+      if (zeroes > 2) return true;
+    }
+  }
+  return false;
+}
+
+// ---------------------------------------------------------------- references on disk
+
+/** The "visual" settings of g9pilot.json, resolved against the config file's folder. */
+export function visualSettings(config, baseDir, flags = {}) {
+  const v = config.visual ?? {};
+  const variant = String(flags.variant ?? v.variant ?? 'default');
+  if (!/^[A-Za-z0-9._-]+$/.test(variant)) throw new Error(`variant "${variant}": letters, digits, . _ - only`);
+  return {
+    dir: path.resolve(baseDir, String(flags.dir ?? v.dir ?? 'visual')),
+    variant,
+    threshold: Number(flags.threshold ?? v.threshold ?? 0.1),
+    maxDiffRatio: Number(flags['max-diff'] ?? v.maxDiffRatio ?? 0.001),
+    masks: v.masks ?? {},
+  };
+}
+
+export function referencePaths(settings, name) {
+  if (!/^[A-Za-z0-9._-]+$/.test(name)) throw new Error(`name "${name}": letters, digits, . _ - only`);
+  const folder = path.join(settings.dir, settings.variant);
+  return { folder, reference: path.join(folder, `${name}.png`), capture: path.join(folder, `${name}.new.png`), diff: path.join(folder, `${name}.diff.png`) };
+}
+
+/**
+ * Compares a PNG capture with the reference `name` → { verdict: 'match' | 'differs' | 'new' | 'size', … }.
+ * 'new' (no reference yet) and 'differs' leave <name>.new.png to approve; 'differs' also <name>.diff.png.
+ */
+export function checkVisual(settings, name, png) {
+  const p = referencePaths(settings, name);
+  fs.mkdirSync(p.folder, { recursive: true });
+  const capture = decodePng(png);
+  if (!fs.existsSync(p.reference)) {
+    fs.writeFileSync(p.capture, png);
+    return { verdict: 'new', name, variant: settings.variant, capture: p.capture, width: capture.width, height: capture.height };
+  }
+  const reference = decodePng(fs.readFileSync(p.reference));
+  const masks = [...(settings.masks['*'] ?? []), ...(settings.masks[name] ?? [])];
+  let r;
+  try {
+    r = compareImages(reference, capture, { threshold: settings.threshold, masks });
+  } catch (e) {
+    if (e.code !== 'SIZE') throw e;
+    fs.writeFileSync(p.capture, png);
+    return { verdict: 'size', name, variant: settings.variant, message: e.message, capture: p.capture };
+  }
+  const summary = { name, variant: settings.variant, diff: r.diff, antialiased: r.antialiased, masked: r.masked, total: r.total, ratio: r.ratio, maxDiffRatio: settings.maxDiffRatio };
+  if (r.ratio <= settings.maxDiffRatio) {
+    for (const f of [p.capture, p.diff]) fs.rmSync(f, { force: true });
+    return { verdict: 'match', ...summary };
+  }
+  fs.writeFileSync(p.capture, png);
+  fs.writeFileSync(p.diff, encodePng(r.image));
+  return { verdict: 'differs', ...summary, capture: p.capture, diffImage: p.diff };
+}
+
+/** The last capture of `name` becomes its reference (no commit; the reviewer looked at the .diff.png first). */
+export function approveVisual(settings, name) {
+  const p = referencePaths(settings, name);
+  if (!fs.existsSync(p.capture)) throw new Error(`nothing to approve: ${p.capture} does not exist (run visual check first)`);
+  fs.renameSync(p.capture, p.reference);
+  fs.rmSync(p.diff, { force: true });
+  return p.reference;
+}
+
+export function listVisual(settings) {
+  if (!fs.existsSync(settings.dir)) return [];
+  const rows = [];
+  for (const variant of fs.readdirSync(settings.dir)) {
+    const folder = path.join(settings.dir, variant);
+    if (!fs.statSync(folder).isDirectory()) continue;
+    for (const f of fs.readdirSync(folder)) {
+      if (!f.endsWith('.png') || f.endsWith('.new.png') || f.endsWith('.diff.png')) continue;
+      const name = f.slice(0, -4);
+      rows.push({ variant, name, pending: fs.existsSync(path.join(folder, `${name}.new.png`)) });
+    }
+  }
+  return rows;
+}
+
+/** A lossless screenshot from the OS: an adb serial (screencap -p) or a booted simulator (simctl io screenshot). */
+export function captureOsPng({ serial, simulator, adb = 'adb' }) {
+  if (serial) return execFileSync(adb, ['-s', serial, 'exec-out', 'screencap', '-p'], { timeout: 30_000, maxBuffer: 64 * 1024 * 1024 });
+  if (simulator) {
+    const file = path.join(fs.mkdtempSync(path.join(process.env.TMPDIR ?? '/tmp', 'g9pilot-')), 'shot.png');
+    execFileSync('xcrun', ['simctl', 'io', String(simulator), 'screenshot', '--type=png', file], { timeout: 30_000 });
+    return fs.readFileSync(file);
+  }
+  throw new Error('a lossless capture needs --serial <adb serial>, --simulator <udid> or --file <png>');
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.