multiplane 0.0.0-stage → 0.3.0

package/src/pixel-comparison.mjs

@@ -0,0 +1,43 @@
+// Calibration and boundaries: tools/reports/059-gpu-jitter-tolerance.md.
+// Set between the largest measured GPU jitter (0.109) and the weakest real change (0.875), with similar margin both ways; see tools/reports/059.
+export const GPU_JITTER_BLOCK_THRESHOLD = 0.3;
+export const GPU_JITTER_CHANNEL_LIMIT = 32;
+
+export function classifyPixelDifference(difference, raster = 'gpu') {
+  if (difference.changedPixels === 0) return 'identical';
+  return raster === 'gpu' && difference.maxBlockMeanDiff <= GPU_JITTER_BLOCK_THRESHOLD &&
+    difference.maxChannelDiff <= GPU_JITTER_CHANNEL_LIMIT ? 'jitter' : 'different';
+}
+
+// Absolute differences are averaged per channel, never across channels.
+export function pixelDifference(reference, actual, { distribution = false } = {}) {
+  if (reference.width !== actual.width || reference.height !== actual.height ||
+      reference.data.length !== reference.width * reference.height * 4 || actual.data.length !== reference.data.length) {
+    throw new RangeError('RGBA image dimensions must match.');
+  }
+  const { width, height } = reference;
+  let changedPixels = 0, maxChannelDiff = 0, maxBlockMeanDiff = 0;
+  const blockMeans = distribution ? [] : undefined;
+  if (!distribution && reference.data.equals(actual.data)) return { changedPixels, maxChannelDiff, maxBlockMeanDiff };
+  for (let y = 0; y < height; y += 8) for (let x = 0; x < width; x += 8) {
+    const sums = [0, 0, 0, 0], w = Math.min(8, width - x), h = Math.min(8, height - y);
+    for (let j = 0; j < h; j++) for (let i = 0; i < w; i++) {
+      const p = ((y + j) * width + x + i) * 4;
+      let changed = false;
+      for (let c = 0; c < 4; c++) {
+        const delta = Math.abs(reference.data[p + c] - actual.data[p + c]);
+        sums[c] += delta;
+        maxChannelDiff = Math.max(maxChannelDiff, delta);
+        changed ||= delta > 0;
+      }
+      if (changed) changedPixels++;
+    }
+    for (let c = 0; c < 4; c++) {
+      const mean = sums[c] / (w * h);
+      maxBlockMeanDiff = Math.max(maxBlockMeanDiff, mean);
+      // Opaque alpha has no encoding error and is excluded from RGB statistics.
+      if (distribution && c < 3) blockMeans.push(mean);
+    }
+  }
+  return { changedPixels, maxChannelDiff, maxBlockMeanDiff, ...(distribution ? { blockMeans } : {}) };
+}

package/src/platform.mjs

@@ -0,0 +1,114 @@
+import path from 'node:path';
+import os from 'node:os';
+import { execFile, spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { promisify } from 'node:util';
+
+const execute = promisify(execFile);
+const windowsMemoryQuery = '$rows = @(Get-CimInstance Win32_Process -Property ProcessId,ParentProcessId,WorkingSetSize | Select-Object ProcessId,ParentProcessId,WorkingSetSize); @{ observer = $PID; rows = $rows } | ConvertTo-Json -Compress';
+function windowsMemory(stdout, pid) {
+  const data = JSON.parse(stdout);
+  const rows = data.rows.map(row => ({ pid: Number(row.ProcessId), parent: Number(row.ParentProcessId), bytes: Number(row.WorkingSetSize) }));
+  return sumProcessTree(rows, pid, [data.observer]);
+}
+
+// Reuse the Windows observer to avoid launching PowerShell for every sample.
+// It reads requests on stdin and writes one JSON line per response.
+export function createProcessTreeReader({ platform = process.platform, pid = process.pid } = {}) {
+  if (platform !== 'win32') return { sample: () => processTreeMemory({ platform, pid }), close() {} };
+  let child, pending, closed = false, failed = false;
+  const settle = value => { const current = pending; pending = undefined; if (current) { clearTimeout(current.timer); current.resolve(value); } };
+  const fail = () => { failed = true; settle(null); child?.kill(); };
+  return {
+    sample() {
+      if (closed || failed) return Promise.resolve(null);
+      if (pending) return pending.promise;
+      if (!child) {
+        const script = `$ErrorActionPreference = 'Stop'; while ($null -ne [Console]::ReadLine()) { try { ${windowsMemoryQuery} } catch { [Console]::WriteLine('null') } }`;
+        child = spawn('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true, stdio: ['pipe', 'pipe', 'ignore'] });
+        child.on('error', fail); child.on('close', () => { failed = true; settle(null); }); child.stdin.on('error', fail);
+        createInterface({ input: child.stdout }).on('line', line => {
+          let bytes = null; try { bytes = windowsMemory(line, pid); } catch {}
+          settle(bytes);
+        });
+      }
+      let resolve;
+      const promise = new Promise(done => { resolve = done; });
+      pending = { promise, resolve, timer: setTimeout(fail, 5000) };
+      child.stdin.write('\n');
+      return promise;
+    },
+    async close() {
+      if (closed) return;
+      closed = true; settle(null);
+      if (!child || child.exitCode !== null || child.signalCode !== null) return;
+      await new Promise(resolve => {
+        const timer = setTimeout(() => child.kill('SIGKILL'), 1000);
+        child.once('close', () => { clearTimeout(timer); resolve(); });
+        child.stdin.end();
+      });
+    },
+  };
+}
+export function sumProcessTree(rows, rootPid, excluded = []) {
+  const selected = new Set([rootPid]), blocked = new Set(excluded);
+  for (let changed = true; changed;) {
+    changed = false;
+    for (const row of rows) if (!blocked.has(row.pid) && selected.has(row.parent) && !selected.has(row.pid)) { selected.add(row.pid); changed = true; }
+  }
+  if (!rows.some(row => row.pid === rootPid)) return null;
+  let sum = 0;
+  for (const row of rows) if (selected.has(row.pid)) {
+    if (!Number.isSafeInteger(row.bytes) || row.bytes < 0) return null;
+    sum += row.bytes;
+  }
+  return Number.isSafeInteger(sum) && sum > 0 ? sum : null;
+}
+
+export async function processTreeMemory({ platform = process.platform, pid = process.pid, run = execute } = {}) {
+  try {
+    let rows;
+    if (platform === 'win32') {
+      // Exclude the observer itself and its descendants from the target tree.
+      const script = '$ErrorActionPreference = "Stop"; ' + windowsMemoryQuery;
+      const { stdout } = await run('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', script], { windowsHide: true, timeout: 5000, maxBuffer: 8 * 1024 * 1024 });
+      return windowsMemory(stdout, pid);
+    }
+    if (!['linux', 'darwin'].includes(platform)) return null;
+    const { stdout } = await run('ps', ['-axo', 'pid=,ppid=,rss=,comm='], { timeout: 5000, maxBuffer: 8 * 1024 * 1024 });
+    rows = stdout.trim().split(/\r?\n/).map(line => {
+      const match = line.trim().match(/^(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/);
+      if (!match) throw new Error('Invalid process table.');
+      return { pid: Number(match[1]), parent: Number(match[2]), bytes: Number(match[3]) * 1024, name: match[4] };
+    });
+    return sumProcessTree(rows, pid, rows.filter(row => row.parent === pid && /(^|\/)ps$/.test(row.name)).map(row => row.pid));
+  } catch { return null; }
+}
+
+// Keep platform-specific Chromium switches isolated from capture logic.
+export function browserOptions(raster = 'gpu', options = {}, platform = process.platform) {
+  const gpu = raster === 'gpu';
+  return { headless: true, ...(gpu ? { channel: 'chromium' } : {}), args: [
+    '--disable-partial-raster',
+    ...(options.rasterThreads ? [`--num-raster-threads=${options.rasterThreads}`] : []),
+    ...(gpu ? ['--enable-gpu-rasterization', ...(platform === 'win32' ? ['--use-angle=d3d11'] : platform === 'darwin' ? ['--use-angle=metal'] : ['--use-angle=gl']),
+      '--force-high-performance-gpu', '--ignore-gpu-blocklist'] : []),
+    ...(!gpu && platform !== 'win32' ? ['--use-angle=swiftshader', '--enable-unsafe-swiftshader'] : []),
+  ] };
+}
+
+export const ffmpegName = (platform = process.platform) => platform === 'win32' ? 'ffmpeg.exe' : 'ffmpeg';
+export const ffmpegHint = (platform = process.platform) => `${platform === 'darwin' ? 'Run brew install ffmpeg' : platform === 'linux' ? 'Install FFmpeg with libx264 using your distribution package manager (for example: sudo apt-get install ffmpeg)' : 'Get FFmpeg with libx264 from https://ffmpeg.org/download.html'} and set --ffmpeg, MULTIPLANE_FFMPEG or PATH.`;
+export const browserHint = (missing, platform = process.platform) => missing ? 'Run npx playwright install chromium.'
+  : platform === 'linux' ? 'Run npx playwright install-deps chromium, then npx playwright install chromium.' : 'Run npx playwright install chromium.';
+
+export const stopSignals = (platform = process.platform) => platform === 'win32'
+  ? ['SIGINT', 'SIGTERM', 'SIGHUP', 'SIGBREAK'] : ['SIGINT', 'SIGTERM', 'SIGHUP'];
+export function userHome(env = process.env, platform = process.platform, home = os.homedir()) {
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+  if (env.MULTIPLANE_HOME) return paths.resolve(env.MULTIPLANE_HOME);
+  if (platform === 'win32') return paths.join(env.USERPROFILE || home, '.multiplane');
+  const base = platform === 'darwin' ? paths.join(home, 'Library', 'Application Support')
+      : (env.XDG_CONFIG_HOME || paths.join(home, '.config'));
+  return paths.join(base, 'multiplane');
+}

package/src/png-native.mjs

@@ -0,0 +1,12 @@
+import { MultiplaneError } from './errors.mjs';
+import sharp from 'sharp';
+
+sharp.concurrency(1);
+sharp.cache(false);
+
+export async function decodeNativePNG(png) {
+  if (png.length < 33 || !png.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex')) || png[24] !== 8 || ![2, 6].includes(png[25]) || png[26] || png[27] || png[28]) throw new MultiplaneError('internal_error', 'Only non-interlaced 8-bit RGB/RGBA PNG is supported.');
+  const { data, info } = await sharp(png, { ignoreIcc: true }).ensureAlpha().raw({ depth: 'uchar' }).toBuffer({ resolveWithObject: true });
+  if (info.channels !== 4 || data.length !== info.width * info.height * 4) throw new MultiplaneError('internal_error', 'Native PNG decoder returned an invalid format.');
+  return { width: info.width, height: info.height, data };
+}

package/src/png.mjs

@@ -0,0 +1,74 @@
+import { MultiplaneError } from './errors.mjs';
+import { deflateSync, inflateSync, crc32 } from 'node:zlib';
+
+export function decodePNG(png) {
+  if (!png.subarray(0, 8).equals(Buffer.from('89504e470d0a1a0a', 'hex'))) throw new MultiplaneError('internal_error', 'Invalid PNG.');
+  let width, height, channels;
+  const chunks = [];
+  for (let offset = 8; offset < png.length;) {
+    const size = png.readUInt32BE(offset), type = png.toString('ascii', offset + 4, offset + 8);
+    const data = png.subarray(offset + 8, offset + 8 + size);
+    if (type === 'IHDR') {
+      width = data.readUInt32BE(0); height = data.readUInt32BE(4);
+      if (data[8] !== 8 || ![2, 6].includes(data[9]) || data[10] || data[11] || data[12]) throw new MultiplaneError('internal_error', 'Only non-interlaced 8-bit RGB/RGBA PNG is supported.');
+      channels = data[9] === 2 ? 3 : 4;
+    }
+    if (type === 'IDAT') chunks.push(data);
+    offset += size + 12;
+  }
+  const raw = inflateSync(Buffer.concat(chunks)), stride = width * channels;
+  if (raw.length !== (stride + 1) * height) throw new MultiplaneError('internal_error', 'PNG data length mismatch.');
+  const line = stride + 1;
+  for (let y = 0; y < height; y++) {
+    const filter = raw[y * line];
+    if (filter > 4) throw new MultiplaneError('internal_error', 'Invalid PNG row filter.');
+    const row = y * line + 1;
+    if (filter === 0) continue;
+    if (filter === 1 || (filter === 4 && y === 0)) {
+      for (let x = channels; x < stride; x++) raw[row + x] += raw[row + x - channels];
+      continue;
+    }
+    if (filter === 2) {
+      if (y) for (let x = 0; x < stride; x++) raw[row + x] += raw[row + x - line];
+      continue;
+    }
+    if (filter === 3) {
+      for (let x = 0; x < stride; x++) raw[row + x] += ((x >= channels ? raw[row + x - channels] : 0) + (y ? raw[row + x - line] : 0)) >>> 1;
+      continue;
+    }
+    for (let x = 0; x < stride; x++) {
+      const p = row + x;
+      const a = x >= channels ? raw[p - channels] : 0;
+      const b = raw[p - line];
+      const c = x >= channels ? raw[p - line - channels] : 0;
+      const predictor = a + b - c;
+      const pa = Math.abs(predictor - a), pb = Math.abs(predictor - b), pc = Math.abs(predictor - c);
+      const correction = pa <= pb && pa <= pc ? a : pb <= pc ? b : c;
+      raw[p] += correction;
+    }
+  }
+  const data = Buffer.alloc(width * height * 4);
+  for (let y = 0; y < height; y++) {
+    const row = y * line + 1;
+    if (channels === 4) { raw.copy(data, y * stride, row, row + stride); continue; }
+    for (let x = 0, j = y * width * 4; x < stride; x += 3, j += 4) {
+      data[j] = raw[row + x]; data[j + 1] = raw[row + x + 1]; data[j + 2] = raw[row + x + 2]; data[j + 3] = 255;
+    }
+  }
+  return { width, height, data };
+}
+
+function chunk(type, data) {
+  const result = Buffer.alloc(data.length + 12);
+  result.writeUInt32BE(data.length); result.write(type, 4, 'ascii'); data.copy(result, 8);
+  result.writeUInt32BE(crc32(result.subarray(4, -4)), result.length - 4);
+  return result;
+}
+
+export function encodePNG({ width, height, data }) {
+  const header = Buffer.alloc(13);
+  header.writeUInt32BE(width); header.writeUInt32BE(height, 4); header[8] = 8; header[9] = 6;
+  const stride = width * 4, raw = Buffer.alloc((stride + 1) * height);
+  for (let y = 0; y < height; y++) data.copy(raw, y * (stride + 1) + 1, y * stride, (y + 1) * stride);
+  return Buffer.concat([Buffer.from('89504e470d0a1a0a', 'hex'), chunk('IHDR', header), chunk('IDAT', deflateSync(raw, { level: 1 })), chunk('IEND', Buffer.alloc(0))]);
+}