simframe 0.1.0

package/src/png.js

@@ -0,0 +1,191 @@
+// Minimal PNG codec. sips only ever hands us 8-bit non-interlaced RGB/RGBA, so
+// that is all we decode; encoding is filter-0 RGBA, which is all we produce.
+import zlib from 'node:zlib';
+
+const SIG = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+/** @typedef {{ width: number, height: number, data: Buffer }} Bitmap RGBA, 4 bytes per pixel. */
+
+/** @returns {Bitmap} */
+export function decodePng(buf) {
+  if (!buf.subarray(0, 8).equals(SIG)) throw new Error('not a PNG');
+  let off = 8;
+  let hdr = null;
+  const idat = [];
+  while (off + 8 <= buf.length) {
+    const len = buf.readUInt32BE(off);
+    const type = buf.toString('ascii', off + 4, off + 8);
+    const body = buf.subarray(off + 8, off + 8 + len);
+    if (type === 'IHDR') {
+      hdr = {
+        width: body.readUInt32BE(0),
+        height: body.readUInt32BE(4),
+        depth: body[8],
+        colorType: body[9],
+        interlace: body[12],
+      };
+    } else if (type === 'IDAT') {
+      idat.push(body);
+    } else if (type === 'IEND') {
+      break;
+    }
+    off += 12 + len;
+  }
+  if (!hdr) throw new Error('PNG has no IHDR');
+  if (hdr.depth !== 8) throw new Error(`unsupported PNG bit depth ${hdr.depth}`);
+  if (hdr.interlace !== 0) throw new Error('interlaced PNG is unsupported');
+  const channels = hdr.colorType === 6 ? 4 : hdr.colorType === 2 ? 3 : 0;
+  if (!channels) throw new Error(`unsupported PNG color type ${hdr.colorType}`);
+
+  const raw = zlib.inflateSync(Buffer.concat(idat));
+  const { width, height } = hdr;
+  const stride = width * channels;
+  const out = Buffer.allocUnsafe(width * height * 4);
+  let prev = Buffer.alloc(stride);
+  const line = Buffer.allocUnsafe(stride);
+
+  for (let y = 0; y < height; y++) {
+    const start = y * (stride + 1);
+    const filter = raw[start];
+    raw.copy(line, 0, start + 1, start + 1 + stride);
+    unfilter(filter, line, prev, channels, stride);
+    if (channels === 4) {
+      line.copy(out, y * width * 4);
+    } else {
+      for (let x = 0; x < width; x++) {
+        const s = x * 3;
+        const d = (y * width + x) * 4;
+        out[d] = line[s];
+        out[d + 1] = line[s + 1];
+        out[d + 2] = line[s + 2];
+        out[d + 3] = 255;
+      }
+    }
+    prev = Buffer.from(line);
+  }
+  return { width, height, data: out };
+}
+
+function unfilter(filter, line, prev, bpp, stride) {
+  switch (filter) {
+    case 0:
+      return;
+    case 1:
+      for (let i = bpp; i < stride; i++) line[i] = (line[i] + line[i - bpp]) & 0xff;
+      return;
+    case 2:
+      for (let i = 0; i < stride; i++) line[i] = (line[i] + prev[i]) & 0xff;
+      return;
+    case 3:
+      for (let i = 0; i < stride; i++) {
+        const left = i >= bpp ? line[i - bpp] : 0;
+        line[i] = (line[i] + ((left + prev[i]) >> 1)) & 0xff;
+      }
+      return;
+    case 4:
+      for (let i = 0; i < stride; i++) {
+        const a = i >= bpp ? line[i - bpp] : 0;
+        const b = prev[i];
+        const c = i >= bpp ? prev[i - bpp] : 0;
+        const p = a + b - c;
+        const pa = Math.abs(p - a);
+        const pb = Math.abs(p - b);
+        const pc = Math.abs(p - c);
+        const pred = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+        line[i] = (line[i] + pred) & 0xff;
+      }
+      return;
+    default:
+      throw new Error(`unknown PNG filter ${filter}`);
+  }
+}
+
+/** @param {Bitmap} bmp */
+export function encodePng(bmp) {
+  const { width, height, data } = bmp;
+  const stride = width * 4;
+  const raw = Buffer.allocUnsafe(height * (stride + 1));
+  for (let y = 0; y < height; y++) {
+    raw[y * (stride + 1)] = 0;
+    data.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  }
+  const ihdr = Buffer.alloc(13);
+  ihdr.writeUInt32BE(width, 0);
+  ihdr.writeUInt32BE(height, 4);
+  ihdr[8] = 8;
+  ihdr[9] = 6;
+  return Buffer.concat([
+    SIG,
+    chunk('IHDR', ihdr),
+    chunk('IDAT', zlib.deflateSync(raw, { level: 6 })),
+    chunk('IEND', Buffer.alloc(0)),
+  ]);
+}
+
+function chunk(type, body) {
+  const head = Buffer.allocUnsafe(8);
+  head.writeUInt32BE(body.length, 0);
+  head.write(type, 4, 'ascii');
+  const crc = Buffer.allocUnsafe(4);
+  crc.writeUInt32BE(crc32(Buffer.concat([head.subarray(4), body])), 0);
+  return Buffer.concat([head, body, crc]);
+}
+
+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(buf) {
+  let c = -1;
+  for (let i = 0; i < buf.length; i++) c = CRC_TABLE[(c ^ buf[i]) & 0xff] ^ (c >>> 8);
+  return (c ^ -1) >>> 0;
+}
+
+/**
+ * Box-average a bitmap down to a small grayscale grid. This is the basis for
+ * every cheap comparison simframe makes: hashes, diffs and region maps.
+ * @param {Bitmap} bmp
+ * @returns {{ cols: number, rows: number, gray: Uint8Array }}
+ */
+export function grayGrid(bmp, cols, rows) {
+  const gray = new Uint8Array(cols * rows);
+  const { width, height, data } = bmp;
+  for (let ry = 0; ry < rows; ry++) {
+    const y0 = Math.floor((ry * height) / rows);
+    const y1 = Math.max(y0 + 1, Math.floor(((ry + 1) * height) / rows));
+    for (let rx = 0; rx < cols; rx++) {
+      const x0 = Math.floor((rx * width) / cols);
+      const x1 = Math.max(x0 + 1, Math.floor(((rx + 1) * width) / cols));
+      let sum = 0;
+      let n = 0;
+      for (let y = y0; y < y1; y++) {
+        for (let x = x0; x < x1; x++) {
+          const i = (y * width + x) * 4;
+          sum += (data[i] * 299 + data[i + 1] * 587 + data[i + 2] * 114) / 1000;
+          n++;
+        }
+      }
+      gray[ry * cols + rx] = Math.round(sum / n);
+    }
+  }
+  return { cols, rows, gray };
+}
+
+/** Nearest-neighbour scale. Only used for contact sheets, where speed beats quality. */
+export function scaleBitmap(bmp, width, height) {
+  const out = Buffer.allocUnsafe(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const sy = Math.min(bmp.height - 1, Math.floor((y * bmp.height) / height));
+    for (let x = 0; x < width; x++) {
+      const sx = Math.min(bmp.width - 1, Math.floor((x * bmp.width) / width));
+      bmp.data.copy(out, (y * width + x) * 4, (sy * bmp.width + sx) * 4, (sy * bmp.width + sx) * 4 + 4);
+    }
+  }
+  return { width, height, data: out };
+}

package/src/simctl.js

@@ -0,0 +1,104 @@
+// Everything that shells out to Xcode's command line tools.
+import { execFile, execFileSync } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const run = promisify(execFile);
+
+// `simctl list` costs ~130ms, which would otherwise dominate every warm read,
+// so the parsed list is cached for a few seconds.
+const DEVICE_CACHE_MS = 4000;
+let deviceCache = { at: 0, devices: null, inflight: null };
+
+/** @returns {Promise<Array<{udid: string, name: string, runtime: string, state: string}>>} */
+export async function listDevices({ maxAgeMs = DEVICE_CACHE_MS } = {}) {
+  if (deviceCache.devices && Date.now() - deviceCache.at <= maxAgeMs) return deviceCache.devices;
+  if (deviceCache.inflight) return deviceCache.inflight;
+  deviceCache.inflight = fetchDevices()
+    .then((devices) => {
+      deviceCache = { at: Date.now(), devices, inflight: null };
+      return devices;
+    })
+    .catch((err) => {
+      deviceCache.inflight = null;
+      throw err;
+    });
+  return deviceCache.inflight;
+}
+
+async function fetchDevices() {
+  const { stdout } = await run('xcrun', ['simctl', 'list', 'devices', '--json'], {
+    maxBuffer: 8 << 20,
+  });
+  const parsed = JSON.parse(stdout);
+  const out = [];
+  for (const [runtime, devices] of Object.entries(parsed.devices || {})) {
+    for (const d of devices) {
+      out.push({
+        udid: d.udid,
+        name: d.name,
+        runtime: runtime.replace('com.apple.CoreSimulator.SimRuntime.', '').replace(/-/g, '.'),
+        state: d.state,
+      });
+    }
+  }
+  return out;
+}
+
+export async function bootedDevices(opts) {
+  return (await listDevices(opts)).filter((d) => d.state === 'Booted');
+}
+
+/**
+ * Resolve a user-supplied device string (UDID, exact name, or substring) to one
+ * booted device. Prefers booted devices; falls back to a clear error listing
+ * what is actually available.
+ */
+export async function resolveDevice(query, opts) {
+  const all = await listDevices(opts);
+  const booted = all.filter((d) => d.state === 'Booted');
+  if (!query) {
+    if (booted.length === 0) throw new Error('no booted simulator (open Simulator.app or run `xcrun simctl boot <udid>`)');
+    return booted[0];
+  }
+  const q = query.toLowerCase();
+  const pools = [booted, all];
+  for (const pool of pools) {
+    const exact = pool.find((d) => d.udid.toLowerCase() === q || d.name.toLowerCase() === q);
+    if (exact) return exact;
+    const partial = pool.filter((d) => d.name.toLowerCase().includes(q));
+    if (partial.length === 1) return partial[0];
+    if (partial.length > 1) {
+      throw new Error(`"${query}" matches ${partial.length} devices: ${partial.map((d) => d.name).join(', ')}`);
+    }
+  }
+  throw new Error(`no simulator matches "${query}"; booted: ${booted.map((d) => d.name).join(', ') || 'none'}`);
+}
+
+export function isBootedSync(udid) {
+  try {
+    const out = execFileSync('xcrun', ['simctl', 'list', 'devices', '--json'], {
+      maxBuffer: 8 << 20,
+      encoding: 'utf8',
+    });
+    const parsed = JSON.parse(out);
+    for (const devices of Object.values(parsed.devices || {})) {
+      const hit = devices.find((d) => d.udid === udid);
+      if (hit) return hit.state === 'Booted';
+    }
+  } catch {
+    /* treat an unreadable device list as "still booted" and retry next tick */
+    return true;
+  }
+  return false;
+}
+
+export async function screenshot(udid, outFile, { mask = 'ignored' } = {}) {
+  await run('xcrun', ['simctl', 'io', udid, 'screenshot', '--type=png', `--mask=${mask}`, outFile], {
+    timeout: 10_000,
+  });
+}
+
+/** Resample with sips, which ships with macOS, so simframe needs no image deps. */
+export async function resize(inFile, outFile, maxDim) {
+  await run('sips', ['-Z', String(maxDim), inFile, '--out', outFile], { timeout: 10_000 });
+}

package/src/store.js

@@ -0,0 +1,94 @@
+// On-disk layout for a device's frame cache. Files are the whole IPC mechanism:
+// the daemon renames completed frames into place, readers just stat and read.
+// A rename is atomic, so a reader can never observe a half-written frame.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+export const ROOT = process.env.SIMFRAME_HOME || path.join(os.homedir(), '.simframe');
+
+export function deviceDir(udid) {
+  return path.join(ROOT, udid);
+}
+
+export function paths(udid) {
+  const dir = deviceDir(udid);
+  return {
+    dir,
+    ring: path.join(dir, 'ring'),
+    full: path.join(dir, 'full'),
+    state: path.join(dir, 'state.json'),
+    meta: path.join(dir, 'meta.json'),
+    heartbeat: path.join(dir, 'heartbeat'),
+    log: path.join(dir, 'daemon.log'),
+    lock: path.join(dir, 'daemon.lock'),
+  };
+}
+
+export function ensureDirs(udid) {
+  const p = paths(udid);
+  fs.mkdirSync(p.ring, { recursive: true });
+  fs.mkdirSync(p.full, { recursive: true });
+  return p;
+}
+
+export function writeAtomic(file, data) {
+  const tmp = `${file}.tmp-${process.pid}`;
+  fs.writeFileSync(tmp, data);
+  fs.renameSync(tmp, file);
+}
+
+export function readJson(file) {
+  try {
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch {
+    return null;
+  }
+}
+
+export function touchHeartbeat(udid) {
+  const p = paths(udid);
+  try {
+    fs.mkdirSync(p.dir, { recursive: true });
+    writeAtomic(p.heartbeat, String(Date.now()));
+  } catch {
+    /* a missing heartbeat only costs the daemon an earlier idle exit */
+  }
+}
+
+export function heartbeatAge(udid) {
+  const raw = readJson(paths(udid).heartbeat);
+  if (typeof raw === 'number') return Date.now() - raw;
+  try {
+    return Date.now() - fs.statSync(paths(udid).heartbeat).mtimeMs;
+  } catch {
+    return Infinity;
+  }
+}
+
+export function pruneDir(dir, keep) {
+  let names;
+  try {
+    names = fs.readdirSync(dir).filter((n) => n.endsWith('.png'));
+  } catch {
+    return;
+  }
+  names.sort((a, b) => parseInt(a, 10) - parseInt(b, 10));
+  for (const name of names.slice(0, Math.max(0, names.length - keep))) {
+    try {
+      fs.unlinkSync(path.join(dir, name));
+    } catch {
+      /* another process may have pruned it already */
+    }
+  }
+}
+
+export function isProcessAlive(pid) {
+  if (!pid) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return err.code === 'EPERM';
+  }
+}