multiplane 0.3.6 → 0.3.8

package/src/output-check.mjs

@@ -1,110 +1,110 @@
-import { spawn } from 'node:child_process';
-import { readFile, rm } from 'node:fs/promises';
-import { decodeNativePNG } from './png-native.mjs';
-import { MultiplaneError } from './errors.mjs';
-import { stopChild } from './process.mjs';
-
-// Container timestamp precision (notably WebM/Matroska) makes decoded rates
-// approximate; apply the same relative tolerance to every output format.
-const FRAME_RATE_RELATIVE_TOLERANCE = 1e-4;
-
-async function probePass(ffmpeg, args, events, spawnProcess, line) {
-  events?.check?.();
-  await new Promise((resolve, reject) => {
-    const child = spawnProcess(ffmpeg, ['-hide_banner', '-nostdin', '-nostats', ...args], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
-    const unsubscribe = events?.onCancel?.(() => stopChild(child));
-    let buffer = '';
-    child.stderr.on('data', bytes => {
-      buffer += bytes.toString();
-      let end;
-      while ((end = buffer.indexOf('\n')) >= 0) { line(buffer.slice(0, end)); buffer = buffer.slice(end + 1); }
-      if (buffer.length > 65536) buffer = buffer.slice(-65536);
-    });
-    child.once('error', error => { unsubscribe?.(); reject(error); });
-    child.once('close', code => {
-      unsubscribe?.(); line(buffer);
-      if (code !== 0) return reject(new Error('FFmpeg probe exited with code ' + code + '.'));
-      resolve();
-    });
-  });
-  events?.check?.();
-}
-
-export async function probeVideo(ffmpeg, file, events, spawnProcess = spawn, options = {}) {
-  // Count copied video packets independently of decoding and audio scheduling.
-  let packetCount;
-  await probePass(ffmpeg, ['-i', file, '-map', '0:v:0', '-an', '-c', 'copy', '-loglevel', 'verbose', '-f', 'null', '-'], events, spawnProcess, text => {
-    const count = text.match(/Output stream #0:0 \(video\):\s*(\d+) packets muxed/);
-    if (count) packetCount = Number(count[1]);
-  });
-  if (!Number.isSafeInteger(packetCount)) throw new Error('FFmpeg packet count could not be parsed.');
-  let frames = 0, minTime = Infinity, maxTime = -Infinity, audioStart = Infinity, audioEnd = -Infinity;
-  let width, height, fps, codec, pixelFormat, timeBase;
-  let input = true, hasAudio = false;
-  const line = text => {
-    if (text.startsWith('Stream mapping:')) input = false;
-    if (input && !codec) codec = text.match(/Stream #0:\d+.*Video: (\w+)/)?.[1];
-    if (input && /Stream #0:\d+.*Audio:/.test(text)) hasAudio = true;
-    if (text.includes('Parsed_showinfo')) {
-      const rate = text.match(/config in time_base:\s*(\d+)\/(\d+), frame_rate:\s*(\d+)\/(\d+)/);
-      if (rate) { timeBase = Number(rate[1]) / Number(rate[2]); fps = Number(rate[3]) / Number(rate[4]); }
-      const frame = text.match(/\bn:\s*\d+\s+pts:\s*(-?\d+)\s+pts_time:.*?fmt:(\S+).*?\bs:(\d+)x(\d+)/);
-      if (frame) {
-        frames++;
-        const t = Number(frame[1]) * timeBase;
-        const duration = Number(text.match(/\bduration:\s*(\d+)/)?.[1]) * timeBase;
-        minTime = Math.min(minTime, t); maxTime = Math.max(maxTime, t + (duration > 0 ? duration : 1 / fps));
-        pixelFormat = frame[2]; width = Number(frame[3]); height = Number(frame[4]);
-      }
-    }
-    if (text.includes('Parsed_ashowinfo')) {
-      const audio = text.match(/pts_time:([\d.e+-]+).*?rate:(\d+).*?nb_samples:(\d+)/);
-      if (audio) { audioStart = Math.min(audioStart, Number(audio[1])); audioEnd = Math.max(audioEnd, Number(audio[1]) + Number(audio[3]) / Number(audio[2])); }
-    }
-  };
-
-  await probePass(ffmpeg, [...(options.alpha && options.format === 'webm' ? ['-c:v', 'libvpx-vp9'] : []), '-i', file,
-    '-map', '0:v:0', '-an', '-vf', 'showinfo=checksum=0', '-fps_mode', 'passthrough', '-f', 'null', '-'], events, spawnProcess, line);
-  if (packetCount !== frames) throw new MultiplaneError('output_invalid', 'Video packet count and decoded frame count disagree.', {
-    details: { reason: 'video_count_mismatch', packetCount, decodedFrames: frames },
-  });
-  if (!frames || !width || !height || !Number.isFinite(fps) || fps <= 0 || !Number.isFinite(maxTime - minTime) || maxTime <= minTime || !codec || !pixelFormat) throw new Error('FFmpeg probe output could not be parsed.');
-  if (hasAudio) {
-    await probePass(ffmpeg, ['-i', file, '-map', '0:a:0', '-vn', '-af', 'ashowinfo', '-f', 'null', '-'], events, spawnProcess, line);
-    if (!Number.isFinite(audioEnd - audioStart) || audioEnd <= audioStart) throw new Error('FFmpeg audio duration could not be parsed.');
-  }
-  return { frames, durationSeconds: maxTime - minTime, width, height, fps, codec, pixelFormat,
-    // TODO(design): Document the optional audioDurationSeconds field.
-    ...(Number.isFinite(audioEnd) ? { audioDurationSeconds: audioEnd - audioStart } : {}) };
-}
-
-export async function checkVideo(ffmpeg, file, expected, events, probe = probeVideo) {
-  let actual;
-  try { actual = await probe(ffmpeg, file, events, undefined, expected); }
-  catch (error) {
-    events.check();
-    if (error.code === 'output_invalid') throw error;
-    if (expected.alpha) throw new MultiplaneError('output_invalid', 'Transparent output could not be verified.', { cause: error });
-    events.warning({ code: 'output_unverified', message: 'Output could not be verified.', details: { reason: error.message } });
-    return { verified: false, frames: null, durationSeconds: null, width: null, height: null, fps: null, codec: null, pixelFormat: null };
-  }
-  events.check();
-  const durationPrecision = 8 * Number.EPSILON * Math.max(1, expected.durationSeconds, actual.durationSeconds);
-  const mismatch = ['frames', 'width', 'height'].some(key => actual[key] !== expected[key])
-    || Math.abs(actual.fps - expected.fps) / expected.fps > FRAME_RATE_RELATIVE_TOLERANCE
-    || Math.abs(actual.durationSeconds - expected.durationSeconds) - 1 / expected.fps > durationPrecision;
-  if (expected.alpha && !/^(yuva|gbrap|rgba|bgra|argb|abgr)/.test(actual.pixelFormat)) throw new MultiplaneError('output_invalid', 'Decoded output has no alpha channel.', { details: { actual } });
-  if (mismatch) throw new MultiplaneError('output_invalid', undefined, { details: { expected, actual } });
-  return { verified: true, ...actual };
-}
-
-export async function checkStill(file, expected) {
-  let actual = { width: null, height: null };
-  try {
-    const decoded = await decodeNativePNG(await readFile(file));
-    actual = { width: decoded.width, height: decoded.height };
-    if (actual.width === expected.width && actual.height === expected.height) return;
-  } catch {}
-  await rm(file, { force: true });
-  throw new MultiplaneError('output_invalid', 'Still image could not be decoded or has incorrect dimensions.', { details: { expected, actual } });
-}
+import { spawn } from 'node:child_process';
+import { readFile, rm } from 'node:fs/promises';
+import { decodeNativePNG } from './png-native.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { stopChild } from './process.mjs';
+
+// Container timestamp precision (notably WebM/Matroska) makes decoded rates
+// approximate; apply the same relative tolerance to every output format.
+const FRAME_RATE_RELATIVE_TOLERANCE = 1e-4;
+
+async function probePass(ffmpeg, args, events, spawnProcess, line) {
+  events?.check?.();
+  await new Promise((resolve, reject) => {
+    const child = spawnProcess(ffmpeg, ['-hide_banner', '-nostdin', '-nostats', ...args], { windowsHide: true, stdio: ['ignore', 'ignore', 'pipe'] });
+    const unsubscribe = events?.onCancel?.(() => stopChild(child));
+    let buffer = '';
+    child.stderr.on('data', bytes => {
+      buffer += bytes.toString();
+      let end;
+      while ((end = buffer.indexOf('\n')) >= 0) { line(buffer.slice(0, end)); buffer = buffer.slice(end + 1); }
+      if (buffer.length > 65536) buffer = buffer.slice(-65536);
+    });
+    child.once('error', error => { unsubscribe?.(); reject(error); });
+    child.once('close', code => {
+      unsubscribe?.(); line(buffer);
+      if (code !== 0) return reject(new Error('FFmpeg probe exited with code ' + code + '.'));
+      resolve();
+    });
+  });
+  events?.check?.();
+}
+
+export async function probeVideo(ffmpeg, file, events, spawnProcess = spawn, options = {}) {
+  // Count copied video packets independently of decoding and audio scheduling.
+  let packetCount;
+  await probePass(ffmpeg, ['-i', file, '-map', '0:v:0', '-an', '-c', 'copy', '-loglevel', 'verbose', '-f', 'null', '-'], events, spawnProcess, text => {
+    const count = text.match(/Output stream #0:0 \(video\):\s*(\d+) packets muxed/);
+    if (count) packetCount = Number(count[1]);
+  });
+  if (!Number.isSafeInteger(packetCount)) throw new Error('FFmpeg packet count could not be parsed.');
+  let frames = 0, minTime = Infinity, maxTime = -Infinity, audioStart = Infinity, audioEnd = -Infinity;
+  let width, height, fps, codec, pixelFormat, timeBase;
+  let input = true, hasAudio = false;
+  const line = text => {
+    if (text.startsWith('Stream mapping:')) input = false;
+    if (input && !codec) codec = text.match(/Stream #0:\d+.*Video: (\w+)/)?.[1];
+    if (input && /Stream #0:\d+.*Audio:/.test(text)) hasAudio = true;
+    if (text.includes('Parsed_showinfo')) {
+      const rate = text.match(/config in time_base:\s*(\d+)\/(\d+), frame_rate:\s*(\d+)\/(\d+)/);
+      if (rate) { timeBase = Number(rate[1]) / Number(rate[2]); fps = Number(rate[3]) / Number(rate[4]); }
+      const frame = text.match(/\bn:\s*\d+\s+pts:\s*(-?\d+)\s+pts_time:.*?fmt:(\S+).*?\bs:(\d+)x(\d+)/);
+      if (frame) {
+        frames++;
+        const t = Number(frame[1]) * timeBase;
+        const duration = Number(text.match(/\bduration:\s*(\d+)/)?.[1]) * timeBase;
+        minTime = Math.min(minTime, t); maxTime = Math.max(maxTime, t + (duration > 0 ? duration : 1 / fps));
+        pixelFormat = frame[2]; width = Number(frame[3]); height = Number(frame[4]);
+      }
+    }
+    if (text.includes('Parsed_ashowinfo')) {
+      const audio = text.match(/pts_time:([\d.e+-]+).*?rate:(\d+).*?nb_samples:(\d+)/);
+      if (audio) { audioStart = Math.min(audioStart, Number(audio[1])); audioEnd = Math.max(audioEnd, Number(audio[1]) + Number(audio[3]) / Number(audio[2])); }
+    }
+  };
+
+  await probePass(ffmpeg, [...(options.alpha && options.format === 'webm' ? ['-c:v', 'libvpx-vp9'] : []), '-i', file,
+    '-map', '0:v:0', '-an', '-vf', 'showinfo=checksum=0', '-fps_mode', 'passthrough', '-f', 'null', '-'], events, spawnProcess, line);
+  if (packetCount !== frames) throw new MultiplaneError('output_invalid', 'Video packet count and decoded frame count disagree.', {
+    details: { reason: 'video_count_mismatch', packetCount, decodedFrames: frames },
+  });
+  if (!frames || !width || !height || !Number.isFinite(fps) || fps <= 0 || !Number.isFinite(maxTime - minTime) || maxTime <= minTime || !codec || !pixelFormat) throw new Error('FFmpeg probe output could not be parsed.');
+  if (hasAudio) {
+    await probePass(ffmpeg, ['-i', file, '-map', '0:a:0', '-vn', '-af', 'ashowinfo', '-f', 'null', '-'], events, spawnProcess, line);
+    if (!Number.isFinite(audioEnd - audioStart) || audioEnd <= audioStart) throw new Error('FFmpeg audio duration could not be parsed.');
+  }
+  return { frames, durationSeconds: maxTime - minTime, width, height, fps, codec, pixelFormat,
+    // TODO(design): Document the optional audioDurationSeconds field.
+    ...(Number.isFinite(audioEnd) ? { audioDurationSeconds: audioEnd - audioStart } : {}) };
+}
+
+export async function checkVideo(ffmpeg, file, expected, events, probe = probeVideo) {
+  let actual;
+  try { actual = await probe(ffmpeg, file, events, undefined, expected); }
+  catch (error) {
+    events.check();
+    if (error.code === 'output_invalid') throw error;
+    if (expected.alpha) throw new MultiplaneError('output_invalid', 'Transparent output could not be verified.', { cause: error });
+    events.warning({ code: 'output_unverified', message: 'Output could not be verified.', details: { reason: error.message } });
+    return { verified: false, frames: null, durationSeconds: null, width: null, height: null, fps: null, codec: null, pixelFormat: null };
+  }
+  events.check();
+  const durationPrecision = 8 * Number.EPSILON * Math.max(1, expected.durationSeconds, actual.durationSeconds);
+  const mismatch = ['frames', 'width', 'height'].some(key => actual[key] !== expected[key])
+    || Math.abs(actual.fps - expected.fps) / expected.fps > FRAME_RATE_RELATIVE_TOLERANCE
+    || Math.abs(actual.durationSeconds - expected.durationSeconds) - 1 / expected.fps > durationPrecision;
+  if (expected.alpha && !/^(yuva|gbrap|rgba|bgra|argb|abgr)/.test(actual.pixelFormat)) throw new MultiplaneError('output_invalid', 'Decoded output has no alpha channel.', { details: { actual } });
+  if (mismatch) throw new MultiplaneError('output_invalid', undefined, { details: { expected, actual } });
+  return { verified: true, ...actual };
+}
+
+export async function checkStill(file, expected) {
+  let actual = { width: null, height: null };
+  try {
+    const decoded = await decodeNativePNG(await readFile(file));
+    actual = { width: decoded.width, height: decoded.height };
+    if (actual.width === expected.width && actual.height === expected.height) return;
+  } catch {}
+  await rm(file, { force: true });
+  throw new MultiplaneError('output_invalid', 'Still image could not be decoded or has incorrect dimensions.', { details: { expected, actual } });
+}

package/src/platform.mjs

@@ -1,114 +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');
-}
+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

@@ -1,12 +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 };
-}
+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

@@ -1,74 +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))]);
-}
+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))]);
+}