multiplane 0.0.0-stage → 0.3.0

package/src/alpha.mjs

@@ -0,0 +1,69 @@
+// All weighted operations use linear-light, premultiplied RGBA.
+const linear = Float64Array.from({ length: 256 }, (_, i) => {
+  const x = i / 255;
+  return x <= 0.04045 ? x / 12.92 : ((x + 0.055) / 1.055) ** 2.4;
+});
+const clamp = x => Math.max(0, Math.min(1, x));
+const srgb = x => Math.round(255 * (x <= 0.0031308 ? 12.92 * x : 1.055 * x ** (1 / 2.4) - 0.055));
+function premultiply(image) {
+  const data = new Float64Array(image.data.length);
+  for (let p = 0; p < data.length; p += 4) {
+    const a = image.data[p + 3] / 255;
+    for (let c = 0; c < 3; c++) data[p + c] = linear[image.data[p + c]] * a;
+    data[p + 3] = a;
+  }
+  return data;
+}
+function finish(data, width, height) {
+  const bytes = Buffer.alloc(data.length);
+  for (let p = 0; p < data.length; p += 4) {
+    const a = data[p + 3];
+    bytes[p + 3] = Math.round(clamp(a) * 255);
+    // Unpremultiply with the unquantized, unclamped weight, including ringing.
+    if (bytes[p + 3]) for (let c = 0; c < 3; c++) bytes[p + c] = srgb(clamp(data[p + c] / a));
+  }
+  return { width, height, data: bytes };
+}
+export function averageAlpha(images) {
+  const data = new Float64Array(images[0].data.length);
+  for (const image of images) {
+    for (let p = 0; p < data.length; p += 4) {
+      const a = image.data[p + 3] / 255;
+      for (let c = 0; c < 3; c++) data[p + c] += linear[image.data[p + c]] * a / images.length;
+      data[p + 3] += a / images.length;
+    }
+  }
+  return finish(data, images[0].width, images[0].height);
+}
+export function clearHiddenColors(image) {
+  const data = Buffer.from(image.data);
+  for (let p = 0; p < data.length; p += 4) if (!data[p + 3]) data.fill(0, p, p + 3);
+  return { ...image, data };
+}
+const sinc = x => x === 0 ? 1 : Math.sin(Math.PI * x) / (Math.PI * x);
+function weights(input, output, kernel) {
+  const ratio = input / output, support = Math.max(1, ratio);
+  return Array.from({ length: output }, (_, i) => {
+    const center = (i + 0.5) * ratio - 0.5;
+    if (kernel === 'neighbor') return [[Math.max(0, Math.min(input - 1, Math.round(center))), 1]];
+    const result = []; let total = 0;
+    for (let j = Math.ceil(center - 3 * support); j <= Math.floor(center + 3 * support); j++) {
+      const distance = (j - center) / support;
+      const weight = Math.abs(distance) < 3 ? sinc(distance) * sinc(distance / 3) : 0;
+      result.push([Math.max(0, Math.min(input - 1, j)), weight]); total += weight;
+    }
+    return result.map(([j, weight]) => [j, weight / total]);
+  });
+}
+export function resizeAlpha(image, width, height, kernel = 'lanczos') {
+  const input = premultiply(image), horizontal = new Float64Array(width * image.height * 4);
+  const output = new Float64Array(width * height * 4);
+  const wx = weights(image.width, width, kernel), wy = weights(image.height, height, kernel);
+  for (let y = 0; y < image.height; y++) for (let x = 0; x < width; x++) {
+    for (const [source, weight] of wx[x]) for (let c = 0; c < 4; c++) horizontal[(y * width + x) * 4 + c] += input[(y * image.width + source) * 4 + c] * weight;
+  }
+  for (let y = 0; y < height; y++) for (let x = 0; x < width; x++) {
+    for (const [source, weight] of wy[y]) for (let c = 0; c < 4; c++) output[(y * width + x) * 4 + c] += horizontal[(source * width + x) * 4 + c] * weight;
+  }
+  return finish(output, width, height);
+}

package/src/artifacts.mjs

@@ -0,0 +1,61 @@
+import { constants } from 'node:fs';
+import { copyFile, rm, writeFile, access, rename, mkdtemp, mkdir } from 'node:fs/promises';
+import path from 'node:path';
+import { MultiplaneError } from './errors.mjs';
+
+const outputError = (error, file) => {
+  if (error.code === 'EEXIST') throw new MultiplaneError('output_exists', undefined, { details: { path: file }, hint: 'Choose a new output path.' });
+  throw error;
+};
+export async function requireNewOutput(file) {
+  try { await access(file); }
+  catch (error) { if (error.code === 'ENOENT') return; throw error; }
+  throw new MultiplaneError('output_exists', undefined, { details: { path: file }, hint: 'Choose a new output path.' });
+}
+export async function writeArtifact(file, bytes) {
+  try { await writeFile(file, bytes, { flag: 'wx' }); }
+  catch (error) { outputError(error, file); }
+}
+export async function publishVideo(temporary, file, overwrite = false) {
+  if (overwrite) { await rename(temporary, file); return; }
+  try { await copyFile(temporary, file, constants.COPYFILE_EXCL); }
+  catch (error) { outputError(error, file); }
+  await rm(temporary);
+}
+
+// Build a replacement directory in isolation; publish only after the whole command succeeds.
+export async function directoryOutput(events, action) {
+  const target = events.options.out;
+  await mkdir(path.dirname(target), { recursive: true });
+  const temporary = await mkdtemp(target + '.partial-');
+  const backup = temporary + '.previous';
+  const artifacts = [], artifact = events.artifact;
+  const relocate = value => {
+    if (typeof value === 'string' && value.startsWith(temporary + path.sep)) return target + value.slice(temporary.length);
+    if (Array.isArray(value)) return value.map(relocate);
+    if (value && typeof value === 'object') return Object.fromEntries(Object.entries(value).map(([k, v]) => [k, relocate(v)]));
+    return value;
+  };
+  events.options.out = temporary;
+  events.artifact = (file, kind) => artifacts.push([file, kind]);
+  let saved = false, committed = false, keepTemporary = false;
+  try {
+    const data = await action(events);
+    events.check();
+    try { await rename(target, backup); saved = true; } catch (error) { if (error.code !== 'ENOENT') throw error; }
+    try { await rename(temporary, target); }
+    catch (error) { const restore = saved; saved = false; if (restore) await rename(backup, target); throw error; }
+    committed = true;
+    for (const [file, kind] of artifacts) artifact(relocate(file), kind);
+    return relocate(data);
+  } catch (error) {
+    // Keep completed diagnostic artifacts addressable when verification fails.
+    keepTemporary = artifacts.length > 0;
+    if (keepTemporary && !committed) for (const [file, kind] of artifacts) artifact(file, kind);
+    throw error;
+  } finally {
+    events.options.out = target; events.artifact = artifact;
+    if (!keepTemporary) await rm(temporary, { recursive: true, force: true });
+    if (saved && committed) await rm(backup, { recursive: true, force: true });
+  }
+}

package/src/benchmark.mjs

@@ -0,0 +1,140 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { mkdir, writeFile, rm } from 'node:fs/promises';
+import { renameSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { availableParallelism } from 'node:os';
+import { runCommand } from './events.mjs';
+import { launchBrowser, environment, warnGpuFallback } from './environment.mjs';
+import { createRenderPool } from './render-pool.mjs';
+import { benchmarkMachine, memoryWorkers, shotTypes } from './workers.mjs';
+import { userHome, stopSignals } from './platform.mjs';
+import { invalidOption, MultiplaneError } from './errors.mjs';
+
+export function recommendedPoint(points) {
+  const threshold = Math.max(...points.map(point => point.fps)) * 0.95;
+  return points.filter(point => point.fps >= threshold).sort((a, b) => a.workers - b.workers)[0];
+}
+
+export async function benchmarkCurves({ measure, maxWorkers, cores = availableParallelism(), memory = () => memoryWorkers(), check = () => {}, now = () => performance.now(), budgetMs = 170000 }) {
+  const shots = {}, deadline = now() + budgetMs;
+  const limit = Math.min(maxWorkers, cores);
+  const candidates = [1, 2, 4, 6, 8, 12, 16, 24].filter(workers => workers <= limit);
+  if (!candidates.includes(2)) throw new MultiplaneError('internal_error', 'Benchmark requires workers 1 and 2 for every shot type; no result was saved.');
+  let memoryLimit = Infinity, lastCost = 0, frameScale = 1;
+  for (const type of shotTypes) {
+    const points = [];
+    let stoppedWorkers;
+    for (const workers of candidates) {
+      check();
+      // Keep a memory ceiling for later shot types, even if free memory recovers.
+      if (workers > memoryLimit) { stoppedWorkers = workers; break; }
+      const available = memory();
+      if (workers > available) {
+        memoryLimit = Math.min(memoryLimit, available);
+        stoppedWorkers = workers;
+        break;
+      }
+      if (now() >= deadline) throw new MultiplaneError('cancelled', 'Benchmark time budget exceeded; no result was saved.');
+      // Divide the time budget only among points still allowed by memory.
+      const remaining = candidates.filter(n => n >= workers && n <= memoryLimit).length
+        + (shotTypes.length - shotTypes.indexOf(type) - 1) * candidates.filter(n => n <= memoryLimit).length;
+      const allowance = (deadline - now()) / remaining;
+      if (lastCost > allowance) frameScale *= allowance / lastCost;
+      const count = Math.max(workers, Math.floor(Math.max(24, workers * 4) * frameScale));
+      const started = now();
+      const fps = await measure(type, workers, { count });
+      check();
+      if (now() >= deadline) throw new MultiplaneError('cancelled', 'Benchmark time budget exceeded; no result was saved.');
+      if (!Number.isFinite(fps) || fps <= 0) throw new MultiplaneError('internal_error', 'Invalid benchmark throughput.');
+      lastCost = now() - started;
+      points.push({ workers, fps });
+    }
+    if (!points.some(point => point.workers === 2)) throw new MultiplaneError('internal_error', 'Insufficient free memory to benchmark workers 1 and 2 for every shot type; no result was saved.');
+    shots[type] = { ...recommendedPoint(points), points,
+      ...(stoppedWorkers === undefined ? {} : { limitedBy: 'memory', stoppedWorkers,
+        detail: `受内存限制，只测到 ${points.at(-1).workers} 个并发。` }) };
+  }
+  check();
+  return shots;
+}
+
+export async function saveBenchmark(record, { home = userHome(), check = () => {} } = {}) {
+  const file = path.join(home, 'benchmark.json'), temporary = file + '.' + randomUUID() + '.tmp';
+  await mkdir(home, { recursive: true });
+  try {
+    check();
+    await writeFile(temporary, JSON.stringify(record, null, 2) + '\n', { flag: 'wx' });
+    check();
+    // Commit synchronously with the last cancellation check; no event-loop gap.
+    renameSync(temporary, file);
+  } finally { await rm(temporary, { force: true }); }
+}
+
+export async function measureBenchmark(type, workers, { raster = 'gpu', check = () => {}, onWarning, onPool = () => {}, count = Math.max(24, workers * 4), createPool = createRenderPool, now = () => performance.now() } = {}) {
+  const root = fileURLToPath(new URL('../', import.meta.url));
+  const names = { dom: 'dom-light', canvas: 'canvas-2d', three: 'webgl' };
+  const fps = Math.max(30, Math.ceil(count / 2));
+  check();
+  const pool = createPool(path.join(root, 'tools/bench/shots', names[type] + '.html'),
+    { root, raster, scale: 1, 'render-scale': 1, 'no-post': true, 'no-static-reuse': true, transport: 'raw' },
+    fps, workers, { width: 1920, height: 1080 }, onWarning);
+  onPool(pool);
+  try {
+    // Warm every worker, excluding browser startup from capture throughput.
+    for await (const frame of pool.frames(0, workers)) { check(); }
+    const samples = [];
+    for (let repeat = 0; repeat < 2; repeat++) {
+      check();
+      const start = now();
+      for await (const frame of pool.frames(0, count)) { check(); }
+      const throughput = count * 1000 / (now() - start);
+      if (!Number.isFinite(throughput) || throughput <= 0) throw new MultiplaneError('internal_error', 'Invalid benchmark throughput.');
+      samples.push(throughput);
+    }
+    return (samples[0] + samples[1]) / 2;
+  } finally { await pool.close(); onPool(undefined); }
+}
+
+export const benchmark = (options = {}) => runCommand('benchmark', null, options, async events => {
+  options = events.options;
+  const raster = options.raster ?? 'gpu';
+  if (!['gpu', 'software'].includes(raster)) throw invalidOption('--raster', '--raster must be gpu or software.');
+  const maxWorkers = Number(options['max-workers'] ?? Math.max(1, availableParallelism()));
+  if (!Number.isSafeInteger(maxWorkers) || maxWorkers < 1) throw invalidOption('--max-workers', '--max-workers must be a positive integer.');
+  let browser, pool, stopped = false;
+  const stop = () => { if (stopped) return; stopped = true; void browser?.close().catch(() => {}); void pool?.cancel().catch(() => {}); };
+  const check = () => { if (stopped) throw new MultiplaneError('cancelled', 'Benchmark interrupted; no result was saved.'); };
+  const signals = stopSignals();
+  for (const signal of signals) process.on(signal, stop);
+  // Reserve cleanup time inside the three-minute command budget.
+  const timer = setTimeout(stop, 175000);
+  const started = performance.now();
+  try {
+    browser = await launchBrowser({ raster });
+    check();
+    const info = await environment(browser);
+    const machine = benchmarkMachine(info, raster);
+    warnGpuFallback(events, info, { raster });
+    await browser.close(); browser = undefined;
+    const shots = await benchmarkCurves({ maxWorkers, check, budgetMs: Math.max(1, 170000 - (performance.now() - started)),
+      measure: async (type, workers, { count }) => {
+        const fps = await measureBenchmark(type, workers, { raster, check, count, onWarning: events.warning, onPool: value => { pool = value; } });
+        events.emit('progress', { phase: 'capture', done: count * 2, total: count * 2, unit: 'frame', fps, etaMs: 0 });
+        return fps;
+      } });
+    check();
+    // TODO(design): Document the benchmark result and cache fields in the protocol.
+    const record = { schema: 'multiplane/1', testedAt: new Date().toISOString(), machine, shots };
+    await saveBenchmark(record, { check });
+    return record;
+  } catch (error) {
+    check();
+    throw error;
+  } finally {
+    clearTimeout(timer);
+    for (const signal of signals) process.off(signal, stop);
+    await browser?.close();
+    await pool?.close();
+  }
+}, false);

package/src/browser-recovery.mjs

@@ -0,0 +1,26 @@
+import { MultiplaneError } from './errors.mjs';
+
+export const MAX_BROWSER_RESTARTS = 2;
+export const recoveryBudget = () => new Int32Array(new SharedArrayBuffer(4));
+
+// Playwright includes bounded browser logs on transport errors. Never retain the
+// launch command (which also contains local profile paths) in public diagnostics.
+export function crashDetails(error, t) {
+  const messages = [], seen = new Set();
+  for (let e = error; e && !seen.has(e); e = e.cause) { seen.add(e); messages.push(e.message ?? String(e)); }
+  const log = messages.join('\n');
+  const exit = log.match(/process did exit: exitCode=([^,\s]+), signal=([^\s>]+)/);
+  const stderr = log.split(/\r?\n/).filter(line => /\[err\]/.test(line) && !line.includes('<launching>')).slice(-20).join('\n').slice(-4000);
+  return { ...(t === undefined ? {} : { t }), reason: (messages.at(-1) ?? 'Browser closed unexpectedly').split(/\r?\n/)[0].slice(0, 500),
+    ...(exit ? { exitCode: exit[1] === 'null' ? null : Number(exit[1]), signal: exit[2] === 'null' ? null : exit[2] } : {}),
+    ...(stderr ? { stderr } : {}) };
+}
+
+export function browserClosed(error, browser, page, crashed = false) {
+  if (error?.code === 'render_threw' || error?.code === 'cancelled') return false;
+  return crashed || page?.isClosed() || (browser && !browser.isConnected())
+    || /Target (?:page, context or browser|closed)|(?:Page|Browser|Connection|Session) closed|Page crashed|Target crashed|browser has disconnected/i.test(error?.message ?? '')
+    || (error?.cause && browserClosed(error.cause, browser, page, crashed));
+}
+
+export const crashedError = (error, t) => new MultiplaneError('browser_crashed', undefined, { cause: error, details: crashDetails(error, t) });

package/src/capture.mjs

@@ -0,0 +1,224 @@
+import { installStaticObserver, reuseEnabled, reuseState, observationReasons } from './static-reuse.mjs';
+import path from 'node:path';
+import { browserClosed, crashedError, recoveryBudget, MAX_BROWSER_RESTARTS } from './browser-recovery.mjs';
+import { access } from 'node:fs/promises';
+import { launchBrowser } from './environment.mjs';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { startServer } from './server.mjs';
+import { normalizeResourcePath, isInsideResourceRoot } from './resource-path.mjs';
+
+export function number(value, label, { positive = false } = {}) {
+  const result = Number(value);
+  if (!String(value).trim() || !Number.isFinite(result) || result < 0 || (positive && result === 0)) throw invalidOption(label, `${label} must be a finite ${positive ? 'positive' : 'nonnegative'} number.`);
+  return result;
+}
+
+export function validateScale(width, height, scale, label = '--scale') {
+  const valid = s => [width * s, height * s].every(v => Number.isSafeInteger(v) && v > 0 && v % 2 === 0);
+  if (!valid(scale)) {
+    const suggestions = [0.25, 0.4, 0.5, 1, 2, 4].filter(valid);
+    throw new MultiplaneError('invalid_scale', undefined, { details: { option: label, width, height, scale }, hint: `Use ${label}: ${suggestions.join(', ') || 'a scale producing even integer dimensions'}.` });
+  }
+}
+
+async function openShotOnce(shot, scale = 1, options = {}) {
+  const raster = options.raster ?? 'gpu';
+  if (!['software', 'gpu'].includes(raster)) throw invalidOption('--raster', '--raster must be software or gpu.');
+  number(scale, '--scale', { positive: true });
+  const inputRoot = path.resolve(options.root ?? process.cwd());
+  const root = await normalizeResourcePath(inputRoot);
+  const entry = path.resolve(inputRoot, shot);
+  if (!await isInsideResourceRoot(root, entry)) throw new MultiplaneError('shot_outside_root');
+  // Preserve the requested URL for in-root symlinks and their relative resources.
+  let relative = path.relative(inputRoot, entry);
+  if (relative === '..' || relative.startsWith('..' + path.sep) || path.isAbsolute(relative)) {
+    relative = path.relative(root, await normalizeResourcePath(entry));
+  }
+  if (path.extname(relative).toLowerCase() !== '.html') throw invalidOption('shot', 'Shot must be an HTML file.');
+  try { await access(entry); } catch { throw new MultiplaneError('shot_not_found'); }
+  const server = await startServer(0, root);
+  let browser, page, crashed = false;
+  try {
+    browser = await launchBrowser(options);
+    await options.onBrowser?.(browser);
+    page = await browser.newPage({ viewport: { width: 1920, height: 1080 }, deviceScaleFactor: scale });
+    if (reuseEnabled(options)) await page.addInitScript(installStaticObserver);
+    page.on('crash', () => { crashed = true; });
+    const errors = [];
+    const observerProbe = request => {
+      const headers = request.headers();
+      return headers['x-multiplane-image-probe'] === '1'
+        || headers['access-control-request-headers']?.toLowerCase().split(',').some(name => name.trim() === 'x-multiplane-image-probe');
+    };
+    page.on('pageerror', error => errors.push(new MultiplaneError('shot_load_failed', undefined, { details: { reason: error.message } })));
+    page.on('console', message => { if (['log', 'warning', 'error'].includes(message.type())) process.stderr.write(message.text() + '\n'); });
+    // Optional image inspection may fail CORS/CSP even when the actual image
+    // loads. Its failure means no reuse, not a shot resource failure.
+    page.on('response', response => { if (response.status() >= 400 && !observerProbe(response.request())) errors.push(new MultiplaneError(response.headers()['x-multiplane-error'] === 'three_not_installed' ? 'three_not_installed' : 'resource_failed', undefined, { details: { status: response.status(), url: response.url() } })); });
+    page.on('requestfailed', request => { if (!observerProbe(request)) errors.push(new MultiplaneError('resource_failed', undefined, { details: { url: request.url() } })); });
+    const url = `${server.url}/${relative.split(path.sep).map(encodeURIComponent).join('/')}?mode=render`;
+    const response = await page.goto(url).catch(cause => { throw new MultiplaneError('shot_load_failed', undefined, { cause }); });
+    if (!response.ok()) throw new MultiplaneError('shot_load_failed');
+    if (errors.length) throw errors[0];
+    if (!await page.evaluate(() => typeof window.SHOT?.render === 'function')) throw new MultiplaneError('shot_contract_invalid');
+    const metadata = await page.evaluate(async () => {
+      await Promise.race([
+        (async () => { await SHOT.ready; await document.fonts.ready; })(),
+        new Promise((_, reject) => setTimeout(() => reject(new Error('ready_timeout')), 30000)),
+      ]);
+      const stage = document.querySelector('#stage')?.getBoundingClientRect();
+      if (!stage || ![stage.width, stage.height].every(v => Number.isSafeInteger(v) && v > 0)) throw new Error('stage_size_invalid');
+      let meta;
+      try {
+        const json = JSON.stringify(SHOT.meta === undefined ? null : SHOT.meta);
+        if (typeof json !== 'string' || new TextEncoder().encode(json).length > 1024 * 1024) throw new Error('Invalid metadata.');
+        meta = JSON.parse(json);
+      } catch { throw new Error('shot_contract_invalid'); }
+      return { width: stage.width, height: stage.height, duration: SHOT.duration, fps: SHOT.fps ?? 30, cuts: SHOT.cuts ?? [], post: SHOT.post ?? {}, hasBlurAt: typeof SHOT.blurAt === 'function', meta };
+    }).catch(cause => { throw new MultiplaneError(['ready_timeout', 'stage_size_invalid', 'shot_contract_invalid'].find(code => cause.message.includes(code)) ?? 'resource_failed', undefined, { cause }); });
+    const { width, height } = metadata;
+    if (width !== 1920 || height !== 1080) {
+      await page.setViewportSize({ width, height });
+      const size = await page.locator('#stage').evaluate(stage => {
+        const rect = stage.getBoundingClientRect();
+        return { width: rect.width, height: rect.height };
+      });
+      if (size.width !== width || size.height !== height) throw new MultiplaneError('stage_size_invalid');
+    }
+    validateScale(width, height, scale, options['render-scale'] !== undefined ? '--render-scale' : '--scale');
+    if (![metadata.duration, metadata.fps].every(v => typeof v === 'number' && Number.isFinite(v) && v > 0)) throw new MultiplaneError('shot_contract_invalid');
+    if (!Array.isArray(metadata.cuts) || metadata.cuts.some(c => typeof c !== 'number' || !Number.isFinite(c) || c < 0 || c > metadata.duration)) throw new MultiplaneError('shot_contract_invalid');
+    const check = () => { if (errors.length) throw errors[0]; };
+    check();
+    const cdp = (options.capture ?? 'cdp') === 'cdp' ? await page.context().newCDPSession(page) : null;
+    if (reuseEnabled(options)) {
+      const inspection = cdp ?? await page.context().newCDPSession(page);
+      try {
+        // Include closed declarative shadow roots, which page JavaScript cannot inspect.
+        const { root } = await inspection.send('DOM.getDocument', { depth: -1, pierce: true });
+        const shadowed = node => node.shadowRoots?.some(root => root.shadowRootType !== 'user-agent') || node.children?.some(shadowed);
+        if (shadowed(root)) await page.evaluate(() => globalThis.__multiplaneStatic?.disqualify());
+      } catch {
+        await page.evaluate(() => globalThis.__multiplaneStatic?.disqualify());
+      } finally { if (!cdp) await inspection.detach(); }
+    }
+    const alpha = options.alpha ?? metadata.post.alpha ?? false;
+    if (typeof alpha !== 'boolean') throw invalidOption('--alpha', 'alpha must be a boolean.');
+    if (alpha && scale < 1) {
+      // Defer downsampling to the linear-light premultiplied post path.
+      const metrics = cdp ?? await page.context().newCDPSession(page);
+      await metrics.send('Emulation.setDeviceMetricsOverride', { width, height, deviceScaleFactor: 1, mobile: false });
+    }
+    if (alpha && cdp) await cdp.send('Emulation.setDefaultBackgroundColorOverride', { color: { r: 0, g: 0, b: 0, a: 0 } });
+    const timings = { renderCallMs: 0, screenshotMs: 0 };
+    let closing, sampleContextUsed = false;
+    const draw = async (t, { motionBlur = 1 } = {}) => {
+        const renderStart = performance.now();
+        const changed = await page.evaluate(({ t, motionBlur, alpha }) => {
+          globalThis.__multiplaneStatic?.suspend();
+          if (alpha) document.documentElement.style.setProperty('--multiplane-page-background', 'transparent');
+          const stage = document.querySelector('#stage');
+          const display = stage.style.getPropertyValue('display');
+          const priority = stage.style.getPropertyPriority('display');
+          stage.style.setProperty('display', 'none', 'important');
+          stage.getBoundingClientRect();
+          if (display) stage.style.setProperty('display', display, priority);
+          else stage.style.removeProperty('display');
+          globalThis.__multiplaneStatic?.resume();
+          const previous = SHOT.sampleContext;
+          let contextUsed = false;
+          SHOT.sampleContext = { time: t, get motionBlur() { contextUsed = true; return motionBlur; } };
+          let failure;
+          try { SHOT.render(t); } catch (error) { failure = String(error?.message ?? error); } finally {
+            if (previous === undefined) delete SHOT.sampleContext;
+            else SHOT.sampleContext = previous;
+          }
+          stage.getBoundingClientRect();
+          const changed = globalThis.__multiplaneStatic?.read() ?? true;
+          return { failure, contextUsed, changed, reason: globalThis.__multiplaneStatic?.reason };
+        }, { t, motionBlur, alpha }).then(({ failure, changed, contextUsed, reason }) => {
+          sampleContextUsed = contextUsed;
+          const index = observationReasons.indexOf(reason);
+          if (index >= 0) Atomics.add(reuseState(options), index + 4, 1);
+          if (failure !== undefined) throw new MultiplaneError('render_threw', undefined, { details: { t, reason: failure } });
+          return changed;
+        });
+        timings.renderCallMs += performance.now() - renderStart;
+        check();
+        return changed;
+    };
+    const beginFrame = async (t, context) => {
+        if (!context?.observed) await draw(t, context);
+        const screenshotStart = performance.now();
+        const png = cdp ? cdp.send('Page.captureScreenshot', { format: 'png', optimizeForSpeed: true, captureBeyondViewport: false,
+            clip: { x: 0, y: 0, width, height, scale: alpha ? Math.max(1, scale) : scale } }).then(({ data }) => {
+          const png = Buffer.from(data, 'base64');
+          if (png.readUInt32BE(16) !== width * (alpha ? Math.max(1, scale) : scale) || png.readUInt32BE(20) !== height * (alpha ? Math.max(1, scale) : scale)) throw new MultiplaneError('internal_error', 'CDP screenshot dimensions do not match output.');
+          return png;
+        }) : page.screenshot({ type: 'png', animations: 'allow', ...(alpha ? { omitBackground: true } : {}) });
+        const measured = png.then(buffer => { timings.screenshotMs += performance.now() - screenshotStart; return buffer; });
+        measured.catch(() => {});
+        return { png: measured };
+    };
+    return {
+      page, browser, server, ...metadata, alpha, beginFrame, timings,
+      get sampleContextUsed() { return sampleContextUsed; },
+      ...(reuseEnabled(options) ? { observe: draw } : {}),
+      isCrash: error => browserClosed(error, browser, page, crashed),
+      ...(metadata.hasBlurAt ? { blurAt: async t => {
+        const result = await page.evaluate(t => { try { return { value: SHOT.blurAt(t) }; } catch (error) { return { reason: String(error?.message ?? error) }; } }, t);
+        if ('reason' in result) throw new MultiplaneError('render_threw', undefined, { details: { t, reason: result.reason } });
+        return result.value;
+      } } : {}),
+      async frame(t, context) { return (await beginFrame(t, context)).png; },
+      close() { return closing ??= (async () => { try { await browser.close(); } finally { await server.close(); } })(); },
+    };
+  } catch (error) { const failure = browserClosed(error, browser, page, crashed) ? crashedError(error) : error; try { await browser?.close(); } finally { await server.close(); } throw failure; }
+}
+
+// Recovery belongs to a complete output frame, never to an individual blur sample.
+export async function openShot(shot, scale = 1, options = {}) {
+  const budget = options._browserRecovery ?? recoveryBudget();
+  let current, closed = false;
+  const recover = async (error, t) => {
+    options.check?.();
+    if (closed) throw error;
+    const failure = crashedError(error, t);
+    if (Atomics.load(budget, 0) >= MAX_BROWSER_RESTARTS) throw failure;
+    const attempt = Atomics.add(budget, 0, 1) + 1;
+    if (attempt > MAX_BROWSER_RESTARTS) throw failure;
+    await current?.close().catch(() => {});
+    try { current = await openShotOnce(shot, scale, options); }
+    catch (restartError) {
+      options.check?.();
+      const restarted = crashedError(restartError, t);
+      restarted.details = { ...failure.details, ...restarted.details };
+      throw restarted;
+    }
+    options.onWarning?.({ code: 'browser_restarted', message: 'Browser restarted; retrying the affected frame.', details: { ...failure.details, attempt } });
+  };
+  try { current = await openShotOnce(shot, scale, options); }
+  catch (error) { if (error.code !== 'browser_crashed') throw error; await recover(error); }
+  const api = {
+    ...current,
+    get page() { return current.page; },
+    get browser() { return current.browser; },
+    get sampleContextUsed() { return current.sampleContextUsed; },
+    ...(current.observe ? { observe: (...args) => current.observe(...args) } : {}),
+    beginFrame: (...args) => current.beginFrame(...args),
+    frame: (...args) => current.frame(...args),
+    ...(current.blurAt ? { blurAt: (...args) => current.blurAt(...args) } : {}),
+    async retryFrame(t, operation) {
+      for (;;) {
+        try { return await operation(); }
+        catch (error) {
+          options.check?.();
+          if (closed || !current.isCrash(error)) throw error;
+          await recover(error, t);
+        }
+      }
+    },
+    async close() { closed = true; await current.close(); },
+  };
+  return api;
+}

package/src/config.mjs

@@ -0,0 +1,79 @@
+import path from 'node:path';
+import { migrateUserHome } from './home-migration.mjs';
+import * as fs from 'node:fs/promises';
+import { randomUUID } from 'node:crypto';
+import { userHome } from './platform.mjs';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { ffmpegOutput } from './ffmpeg.mjs';
+
+export const configKeys = ['ffmpeg', 'raster', 'encoder', 'workers', 'jobsDir', 'hosted'];
+export async function probeFfmpeg(file) {
+  const check = { usable: false, version: null, encoders: { libx264: false, 'libvpx-vp9': false, prores_ks: false }, reason: null };
+  try {
+    check.version = (await ffmpegOutput(file, ['-version'])).split(/\r?\n/)[0];
+    if (!/^ffmpeg version\s/i.test(check.version)) { check.reason = 'not-ffmpeg'; return check; }
+    const list = await ffmpegOutput(file, ['-encoders']);
+    for (const name of Object.keys(check.encoders)) check.encoders[name] = new RegExp('\\b' + name + '\\b').test(list);
+    check.usable = check.encoders.libx264;
+    if (!check.usable) check.reason = 'missing-libx264';
+  } catch (error) { check.reason = error.code === 'ENOENT' ? 'not-found' : 'cannot-run'; }
+  return check;
+}
+export class Configuration {
+  constructor(home = userHome(), env = process.env, warning = () => {}) { this.file = path.join(home, 'config.json'); this.env = env; this.warning = warning; }
+  prepare() {
+    if (path.resolve(path.dirname(this.file)) === path.resolve(userHome(this.env))) {
+      for (const warning of migrateUserHome(this.env).warnings) this.warning(warning);
+    }
+  }
+  async document() {
+    let text;
+    try { text = await fs.readFile(this.file, 'utf8'); }
+    catch (error) { if (error.code === 'ENOENT') return { exists: false, values: {} }; throw error; }
+    try {
+      const values = JSON.parse(text);
+      if (!values || Array.isArray(values) || typeof values !== 'object') throw Error();
+      return { exists: true, values };
+    } catch { throw new MultiplaneError('config_invalid', `Invalid configuration: ${this.file}`, { details: { path: this.file }, hint: 'Repair or delete this configuration file before changing settings.' }); }
+  }
+  async read(key, prepared = false) {
+    if (!prepared) this.prepare();
+    if (key !== undefined && !configKeys.includes(key)) throw invalidOption('key', 'Unknown configuration key.');
+    const { exists, values } = await this.document();
+    return { file: this.file, exists, values: Object.fromEntries((key ? [key] : configKeys).map(k => [k, values[k] ?? null])), overrides: { ffmpeg: this.env.MULTIPLANE_FFMPEG || null, jobsDir: this.env.MULTIPLANE_JOBS_DIR || null } };
+  }
+  async save(key, value) {
+    if (!configKeys.includes(key)) throw invalidOption('key', 'Unknown configuration key.');
+    if (key === 'workers' && value === 'auto') value = null;
+    if (value !== null) {
+      if (key === 'hosted' && ['true', 'false'].includes(value)) value = value === 'true';
+      if (key === 'workers' && /^\d+$/.test(String(value))) value = Number(value);
+      const valid = ['ffmpeg', 'jobsDir'].includes(key) ? typeof value === 'string' && !!value.trim() && !value.includes('\0')
+        : key === 'raster' ? ['gpu', 'software'].includes(value) : key === 'encoder' ? ['x264', 'nvenc-h264', 'nvenc-hevc'].includes(value)
+          : key === 'hosted' ? typeof value === 'boolean' : Number.isSafeInteger(value) && value > 0;
+      if (!valid) throw invalidOption(key, 'Invalid configuration value.');
+      if (['ffmpeg', 'jobsDir'].includes(key)) value = path.resolve(value);
+    }
+    this.prepare();
+    await fs.mkdir(path.dirname(this.file), { recursive: true });
+    const lock = this.file + '.lock', deadline = performance.now() + 10000;
+    let handle;
+    while (!handle) {
+      try { handle = await fs.open(lock, 'wx'); }
+      catch (error) {
+        if (error.code !== 'EEXIST' || performance.now() >= deadline) throw error;
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+    }
+    const temporary = this.file + '.' + randomUUID() + '.tmp';
+    let result;
+    try {
+      const { values } = await this.document();
+      await fs.writeFile(temporary, JSON.stringify({ ...values, schema: 'multiplane/1', [key]: value }, null, 2) + '\n', { flag: 'wx' });
+      await fs.rename(temporary, this.file);
+      result = { ...await this.read(undefined, true), changed: key };
+    } finally { await fs.unlink(temporary).catch(() => {}); await handle.close(); await fs.unlink(lock); }
+    if (key === 'ffmpeg' && value !== null) result.check = await probeFfmpeg(value);
+    return result;
+  }
+}