multiplane 0.0.0-stage → 0.3.0

package/src/doctor.mjs

@@ -0,0 +1,56 @@
+import { readBenchmark, validBenchmark, benchmarkMachine } from './workers.mjs';
+import { runCommand } from './events.mjs';
+import { launchBrowser, environment, warnGpuFallback } from './environment.mjs';
+import { inspectFFmpeg, ffmpegOutput } from './ffmpeg.mjs';
+import { MultiplaneError } from './errors.mjs';
+
+export function benchmarkCheck(record, machine) {
+  const current = validBenchmark(record, machine);
+  const limits = Object.entries(record.shots ?? {}).filter(([, shot]) => shot?.limitedBy === 'memory')
+    .map(([type, shot]) => `${type}: 受内存限制，只测到 ${shot.points?.at(-1)?.workers ?? shot.workers} 个并发。`);
+  return { name: 'benchmark', ok: current,
+    detail: [current ? 'Local performance benchmark is current.' : '本机性能测试已过期。Run multiplane benchmark to retest; rendering can continue.', ...limits].join(' ') };
+}
+
+export const doctor = (options = {}) => runCommand('doctor', null, options, async events => {
+  options = events.options;
+  const moved = events.migration.migrated.filter(item => ['config.json', 'jobs.jsonl'].includes(item.name));
+  const checks = [{ name: 'home', ok: true, detail: `User directory: ${events.config.path.slice(0, -'config.json'.length)}.` + (moved.length ? ` Copied from the previous location: ${moved.map(item => item.source).join(', ')}; original files were retained.` : '') }];
+  let failure, browser, info, ffmpeg;
+  const nodeOk = Number(process.versions.node.split('.')[0]) >= 24;
+  checks.push({ name: 'node', ok: nodeOk, detail: `Node ${process.version}; version 24 or newer is required.` });
+  if (!nodeOk) failure = new MultiplaneError('unsupported_node', 'Node 24 or newer is required.');
+  try {
+    browser = await launchBrowser(options);
+    checks.push({ name: 'browser', ok: true, detail: `Chromium ${browser.version()} is available.` });
+    info = await environment(browser);
+    checks.push({ name: 'gpu', ok: info.gpu.hardware, detail: `GPU renderer: ${info.gpu.renderer}.` });
+    warnGpuFallback(events, info, options);
+    const record = readBenchmark();
+    if (record) {
+      checks.push(benchmarkCheck(record, benchmarkMachine(info, options.raster)));
+    }
+  } catch (error) {
+    failure ??= error;
+    checks.push({ name: 'browser', ok: false, detail: error.message }, { name: 'gpu', ok: false, detail: 'GPU could not be inspected.' });
+  } finally { await browser?.close(); }
+  try {
+    ffmpeg = await inspectFFmpeg(options.ffmpeg);
+    checks.push({ name: 'ffmpeg', ok: true, detail: ffmpeg.version });
+    const encoderList = await ffmpegOutput(ffmpeg.path, ['-encoders']);
+    const x264 = /\blibx264\b/.test(encoderList);
+    for (const name of ['libvpx-vp9', 'prores_ks']) checks.push({ name, ok: new RegExp('\\b' + name + '\\b').test(encoderList), detail: name + ' is optional; required only for its video format, including transparent output.' });
+    checks.push({ name: 'libx264', ok: x264, detail: x264 ? 'libx264 is available.' : 'libx264 is unavailable.' });
+    if (!x264) failure ??= new MultiplaneError('ffmpeg_unusable', undefined, { hint: 'Install an FFmpeg build with libx264.' });
+  } catch (error) {
+    failure ??= error;
+    checks.push({ name: 'ffmpeg', ok: false, detail: error.message }, { name: 'libx264', ok: false, detail: 'Encoder list could not be inspected.' });
+    for (const name of ['libvpx-vp9', 'prores_ks']) checks.push({ name, ok: false, detail: `${name} is optional; encoder availability could not be inspected.` });
+  }
+  if (info) events.emit('environment', { ...info, ffmpeg: ffmpeg ?? null });
+  try { await import('three'); checks.push({ name: 'three', ok: true, detail: 'Optional three.js is available.' }); }
+  catch { checks.push({ name: 'three', ok: false, detail: 'Optional three.js is not installed.' }); }
+  if (failure && checks.some(c => ['ffmpeg', 'libx264'].includes(c.name) && !c.ok)) failure.hint = (failure.hint ? failure.hint + ' ' : '') + 'Run multiplane config set ffmpeg <path> to save an FFmpeg executable.';
+  if (failure) { failure.result = { data: { checks, config: events.config } }; throw failure; }
+  return { checks, config: events.config };
+}, false);

package/src/draft.mjs

@@ -0,0 +1,30 @@
+import { openShot, validateScale, number } from './capture.mjs';
+import { invalidOption } from './errors.mjs';
+
+export function draftScale(width, height, outputScale = 1) {
+  let a = width, b = height;
+  while (b) [a, b] = [b, a % b];
+  const limit = Math.floor(Math.min(0.5, outputScale) * a / 2);
+  for (let units = limit; units > 0; units--) {
+    const scale = 2 * units / a;
+    if ([width * scale, height * scale].every(v => Number.isSafeInteger(v) && v > 0 && v % 2 === 0)) return scale;
+  }
+  validateScale(width, height, 0, '--render-scale');
+}
+
+export async function applyDraft(command, shot, explicit, configured, probe = {}) {
+  if (!explicit.draft) return configured;
+  if (!['render', 'stills', 'verify'].includes(command)) throw invalidOption('--draft', '--draft is supported by render, stills and verify.');
+  const options = { ...configured, 'motion-blur': 1, grain: 0, upscale: 'lanczos', ...explicit, draft: true };
+  options['max-motion-blur'] = 1;
+  if (options['no-post']) Object.assign(options, { 'motion-blur': 1, grain: 0, shutter: 0.5 });
+  if (explicit['render-scale'] === undefined) {
+    // TODO(design): Document the dimension preflight before start for --draft in the v1 protocol.
+    // Load dimensions before start so the event describes the effective preset.
+    const outputScale = number(options.scale ?? 1, '--scale', { positive: true });
+    const capture = await openShot(shot, outputScale, { ...options, ...probe });
+    try { options['render-scale'] = draftScale(capture.width, capture.height, outputScale); }
+    finally { await capture.close(); }
+  }
+  return options;
+}

package/src/encoder.mjs

@@ -0,0 +1,16 @@
+import { invalidOption } from './errors.mjs';
+export const encoders = ['x264', 'nvenc-h264', 'nvenc-hevc'];
+
+export function encoderArgs(name = 'x264', quality, maxMbps) {
+  if (!encoders.includes(name)) throw invalidOption('--encoder', '--encoder must be x264, nvenc-h264 or nvenc-hevc.');
+  if (maxMbps !== undefined && !(Number.isFinite(maxMbps) && maxMbps > 0)) throw invalidOption('--max-bitrate', '--max-bitrate must be positive (Mbps).');
+  const cap = maxMbps ? ['-maxrate', `${maxMbps}M`, '-bufsize', `${maxMbps * 2}M`] : [];
+  if (name === 'x264') return ['-c:v', 'libx264', '-profile:v', 'high', '-crf', '16', ...cap];
+  quality ??= name === 'nvenc-hevc' ? 20 : 21;
+  if (!Number.isInteger(quality) || quality < 1 || quality > 51) throw invalidOption('NVENC', 'NVENC CQ must be an integer from 1 to 51.');
+  return ['-c:v', name === 'nvenc-h264' ? 'h264_nvenc' : 'hevc_nvenc',
+    '-preset', 'p7', '-tune', 'hq', '-rc', 'vbr', '-cq', String(quality), '-b:v', '0',
+    ...(maxMbps ? cap : ['-qmin', '0', '-qmax', String(Math.min(51, quality + 2))]),
+    '-multipass', 'fullres', '-spatial-aq', '1', '-temporal-aq', '1', '-rc-lookahead', '32', '-bf', '3',
+    ...(name === 'nvenc-h264' ? ['-profile:v', 'high'] : ['-tag:v', 'hvc1'])];
+}

package/src/environment.mjs

@@ -0,0 +1,56 @@
+import { chromium } from 'playwright';
+import { browserOptions, browserHint } from './platform.mjs';
+import { MultiplaneError } from './errors.mjs';
+export async function launchBrowser(options = {}, launcher = chromium, platform = process.platform) {
+  let browser;
+  try {
+    try {
+      browser = await launcher.launch(browserOptions(options.raster ?? 'gpu', options, platform));
+      if (platform !== 'linux' || options.raster === 'software' || (await environment(browser)).gpu.hardware) return browser;
+      await browser.close(); browser = undefined;
+    } catch (error) {
+      await browser?.close(); browser = undefined;
+      if (platform !== 'linux' || options.raster === 'software' || /Executable doesn't exist/.test(error.message)) throw error;
+    }
+    // ANGLE can launch without a working GL device on a headless Linux host.
+    // Relaunch with SwiftShader so WebGL shots remain usable and repeatable.
+    return await launcher.launch(browserOptions('software', options, platform));
+  } catch (cause) { throw new MultiplaneError(/Executable doesn't exist/.test(cause.message) ? 'browser_not_installed' : 'browser_launch_failed', undefined,
+    { cause, hint: browserHint(/Executable doesn't exist/.test(cause.message), platform), details: { reason: cause.message.split(/\r?\n/)[0] } }); }
+}
+export async function environment(browser, ffmpeg = null) {
+  const session = await browser.newBrowserCDPSession();
+  try {
+    const { gpu } = await session.send('SystemInfo.getInfo');
+    const renderer = gpu.auxAttributes?.glRenderer ?? gpu.devices?.[0]?.deviceString ?? 'unknown';
+    return { node: process.version, platform: process.platform, chromium: browser.version(),
+      gpu: { renderer, hardware: !/swiftshader|llvmpipe|software|unknown/i.test(renderer) }, ffmpeg };
+  } finally { await session.detach(); }
+}
+export async function loaded(events, capture, ffmpeg = null) {
+  events.options.alpha = capture.alpha;
+  events.start(true);
+  const { width, height, duration, fps, cuts, post } = capture;
+  events.emit('shot', { width, height, duration, fps, cuts, post });
+  events.check();
+}
+
+export function warnGpuFallback(events, info, options = {}) {
+  if ((options.raster ?? 'gpu') === 'gpu' && !info.gpu.hardware) {
+    events.emit('warning', { code: 'gpu_software_fallback', message: 'Hardware GPU rasterization is unavailable.' });
+  }
+}
+
+export const observeBrowser = (events, ffmpeg = null) => {
+  let observed = false;
+  return async browser => {
+    const unsubscribe = events.onCancel(() => browser.close());
+    browser.once('disconnected', unsubscribe);
+    events.check();
+    if (observed) return;
+    const info = await environment(browser, ffmpeg);
+    observed = true;
+    events.emit('environment', info);
+    warnGpuFallback(events, info, events.options);
+  };
+};

package/src/errors.mjs

@@ -0,0 +1,51 @@
+export const errorCodes = Object.freeze(Object.fromEntries([
+  [1, 'shot_not_found', 'Shot file was not found.'],
+  [1, 'shot_outside_root', 'Shot must be inside the project root.'],
+  [1, 'shot_load_failed', 'Shot failed to load.'],
+  [1, 'shot_contract_invalid', 'Shot contract is invalid.'],
+  [1, 'stage_size_invalid', 'Stage must have fixed positive integer dimensions.'],
+  [1, 'ready_timeout', 'Shot readiness timed out.'],
+  [1, 'render_threw', 'Shot render function threw an error.'],
+  [1, 'resource_failed', 'A shot resource failed to load.'],
+  [1, 'nondeterministic_output', 'Determinism verification failed.'],
+  [1, 'lint_failed', 'Shot lint checks failed.'],
+  [1, 'cancel_timeout', 'Timed out waiting for job cancellation.'],
+  [3, 'wait_timeout', 'Timed out waiting for job completion.'],
+  [2, 'job_not_found', 'Job status was not found or is invalid.'],
+  [3, 'config_invalid', 'User configuration is not a JSON object.'],
+  [3, 'skill_modified', 'The installed skill has local modifications.'],
+  [3, 'skill_blocked', 'The skill directory cannot be safely changed.'],
+  [3, 'skill_changed', 'The installed skill changed since inspection.'],
+  [3, 'unsupported_node', 'Node 24 or newer is required.'],
+  [2, 'invalid_option', 'Invalid option.'],
+  [2, 'invalid_scale', 'Scale must produce positive even integer dimensions.'],
+  [2, 'output_exists', 'Output already exists.'],
+  [3, 'ffmpeg_not_found', 'FFmpeg was not found.'],
+  [3, 'ffmpeg_unusable', 'FFmpeg cannot run or lacks the requested encoder.'],
+  [3, 'browser_not_installed', 'Chromium is not installed.'],
+  [3, 'browser_launch_failed', 'Chromium failed to launch.'],
+  [3, 'port_in_use', 'The requested port is already in use.'],
+  [3, 'three_not_installed', 'Optional three.js is not installed.'],
+  [3, 'job_dir_unwritable', 'Job directory cannot be created or written.'],
+  [4, 'browser_crashed', 'Browser closed unexpectedly and recovery failed.'],
+  [4, 'worker_crashed', 'A rendering worker exited unexpectedly.'],
+  [4, 'encode_failed', 'Video encoding failed.'],
+  [4, 'output_invalid', 'Output does not match the rendered frames.'],
+  [4, 'internal_error', 'An internal error occurred.'],
+  [130, 'cancelled', 'Job was cancelled.'],
+].map(([exitCode, code, message]) => [code, { exitCode, message }])));
+
+export class MultiplaneError extends Error {
+  constructor(code, message = errorCodes[code]?.message, { hint, details, result, cause } = {}) {
+    super(message, { cause });
+    this.name = 'MultiplaneError';
+    this.code = code;
+    this.exitCode = errorCodes[code]?.exitCode ?? 4;
+    this.hint = hint;
+    this.details = details;
+    this.result = result;
+  }
+}
+export const asError = error => error instanceof MultiplaneError ? error
+  : new MultiplaneError('internal_error', undefined, { cause: error, details: { reason: error.message } });
+export const invalidOption = (option, message) => new MultiplaneError('invalid_option', message, { details: { option } });

package/src/events.mjs

@@ -0,0 +1,252 @@
+import { resolveQuality } from './post.mjs';
+import { resolveFormat } from './format.mjs';
+import path from 'node:path';
+import { checkLint, scanShot } from './lint.mjs';
+import { requireNewOutput, directoryOutput } from './artifacts.mjs';
+import { randomBytes } from 'node:crypto';
+import { appendFileSync, mkdirSync, renameSync, writeFileSync, existsSync, statSync, readFileSync, unlinkSync } from 'node:fs';
+import { stopSignals, ffmpegName } from './platform.mjs';
+import { asError, MultiplaneError, invalidOption } from './errors.mjs';
+import { defaultWorkers } from './render-pool.mjs';
+import { loadUserConfig, appendJobIndex, retryFileOperation } from './user-home.mjs';
+import { userHome } from './platform.mjs';
+import { applyDraft } from './draft.mjs';
+import { createResourceSampler } from './resources.mjs';
+import { hostedAvailable, hostedEnvironment, handoff, followJob } from './hosted.mjs';
+
+export const version = JSON.parse(readFileSync(new URL('../package.json', import.meta.url))).version;
+export const jobDirectory = (options = {}, env = process.env) => path.resolve(options['job-dir'] ?? env.MULTIPLANE_JOBS_DIR ?? 'out/jobs');
+
+export function createEvents(command, shot, options = {}, job = false, deferStart = false) {
+  const started = performance.now(), startedAt = new Date().toISOString();
+  let directory, jobId, ended = false, lastProgress = -Infinity, stopped = false;
+  const artifacts = [];
+  if (job) {
+    const stamp = startedAt.replaceAll('-', '').replaceAll(':', '').replace('T', '-').slice(0, 15);
+    try {
+      if (options['job-dir-exact']) {
+        directory = path.resolve(options['job-dir-exact']);
+        if (!statSync(directory).isDirectory()) throw Error('Missing executor job directory.');
+        jobId = path.basename(directory);
+      } else {
+        mkdirSync(jobDirectory(options), { recursive: true });
+        for (;;) {
+          jobId = `${stamp}-${path.parse(shot).name}-${randomBytes(2).toString('hex')}`;
+          directory = path.join(jobDirectory(options), jobId);
+          try { mkdirSync(directory); break; } catch (error) { if (error.code !== 'EEXIST') throw error; }
+        }
+      }
+      // Exercise actual file creation, writing and removal before launching a browser.
+      const probe = path.join(directory, '.write-check');
+      writeFileSync(probe, 'write check', { flag: 'wx' });
+      unlinkSync(probe);
+    } catch (cause) {
+      throw new MultiplaneError('job_dir_unwritable', undefined, {
+        cause, details: { path: jobDirectory(options) },
+        hint: 'Use --job-dir or MULTIPLANE_JOBS_DIR to select a writable job directory.',
+      });
+    }
+    options.out = path.resolve(options.out ?? (command === 'render' ? path.join(directory, `${path.parse(shot).name}.${options.format ?? 'mp4'}`) : path.join(directory, command)));
+  }
+  let state = { schema: 'multiplane/1', jobId, command, shot, pid: process.pid, state: 'running',
+    phase: 'launch', done: 0, total: null, fps: null, etaMs: null, startedAt, updatedAt: startedAt, result: null, previewFrame: null, memoryBytes: null };
+  const save = () => {
+    if (!directory) return;
+    const file = path.join(directory, 'status.json');
+    const deadline = performance.now() + 1000;
+    retryFileOperation(() => writeFileSync(file + '.tmp', JSON.stringify(state) + '\n'), deadline);
+    retryFileOperation(() => renameSync(file + '.tmp', file), deadline);
+  };
+  let startedEvent = false;
+  const pendingEvents = [];
+  const emit = (type, fields = {}) => {
+    if (deferStart && !startedEvent && type !== 'start') { pendingEvents.push([type, fields]); return; }
+    if (ended) return;
+    if (type === 'progress') {
+      for (const key of ['phase', 'done', 'total', 'fps', 'etaMs']) state[key] = fields[key];
+      state.updatedAt = new Date().toISOString();
+      save();
+      if (performance.now() - lastProgress < 250) return;
+      lastProgress = performance.now();
+    }
+    const event = { schema: 'multiplane/1', type, command, ts: new Date().toISOString(), ...fields };
+    if (type === 'progress') for (const key of ['phase', 'done', 'total', 'fps', 'etaMs']) state[key] = fields[key];
+    if (type === 'result') { state.result = event; state.state = event.ok ? 'succeeded' : event.code === 'cancelled' ? 'cancelled' : 'failed'; ended = true; }
+    state.updatedAt = event.ts;
+    if (directory) appendFileSync(path.join(directory, 'events.jsonl'), JSON.stringify(event) + '\n');
+    save();
+    options.onEvent?.(event);
+    return event;
+  };
+  const cancelHandlers = new Set();
+  let homeWarned = false;
+  const warning = fields => {
+    if (fields.code === 'home_unavailable') { if (homeWarned) return; homeWarned = true; }
+    emit('warning', fields);
+  };
+  const index = (event, fields) => {
+    if (!directory || process.env.MULTIPLANE_NO_INDEX === '1') return;
+    try { appendJobIndex(userHome(), { schema: 'multiplane/1', event, jobId, jobDir: directory, ...fields, ts: new Date().toISOString() }); }
+    catch { warning({ code: 'home_unavailable', message: 'Job index could not be updated.' }); }
+  };
+  const requestStop = () => {
+    if (stopped) return;
+    stopped = true;
+    for (const handler of cancelHandlers) Promise.resolve().then(handler).catch(() => {});
+  };
+  const signals = job ? stopSignals().map(signal => [signal, requestStop]) : [];
+  let timer;
+  const monitor = () => {
+    if (!job || timer) return;
+    for (const [signal, handler] of signals) process.on(signal, handler);
+    timer = setInterval(() => { if (existsSync(path.join(directory, 'stop'))) requestStop(); }, 100);
+    timer.unref();
+  };
+  if (!options._hostedCLI) monitor();
+  return {
+    directory, jobId, emit, warning, artifacts, options, monitor,
+    // TODO(design): Document memoryBytes in status.json (latest sample, null on failure).
+    memory(bytes) { state.memoryBytes = bytes; state.updatedAt = new Date().toISOString(); save(); },
+    preview(frame) { state.previewFrame = frame; state.updatedAt = new Date().toISOString(); save(); },
+    start(resolved = false) {
+      if (startedEvent) return;
+      if (deferStart && !resolved) { save(); return; }
+      startedEvent = true;
+      const { onEvent, _preview, _resources, _probeVideo, _inspectFFmpeg, _hostedCLI, ...effective } = options;
+      emit('start', { version, shot, ...(jobId ? { jobId } : {}), options: effective, ...(this.workersSource ? { workersSource: this.workersSource } : {}) });
+      index('start', { command, shot, pid: process.pid });
+      for (const [type, fields] of pendingEvents.splice(0)) emit(type, fields);
+    },
+    check() { if (directory && existsSync(path.join(directory, 'stop'))) requestStop(); if (stopped) throw new MultiplaneError('cancelled'); },
+    onCancel(handler) { cancelHandlers.add(handler); if (stopped) Promise.resolve().then(handler).catch(() => {}); return () => cancelHandlers.delete(handler); },
+    progress(phase, done = 0, total = null) {
+      const seconds = (performance.now() - started) / 1000, fps = done && seconds ? done / seconds : null;
+      emit('progress', { phase, done, total, unit: 'frame', fps, etaMs: fps && total !== null ? Math.round((total - done) / fps * 1000) : null });
+    },
+    finalize() { emit('progress', { phase: 'finalize', done: state.done, total: state.total, unit: 'frame', fps: state.fps, etaMs: 0 }); },
+    artifact(file, kind) { const artifact = { path: path.resolve(file), kind, bytes: statSync(file).size }; artifacts.push(artifact); emit('artifact', artifact); },
+    finish(data = {}, error) {
+      if (deferStart) this.start(true);
+      const result = { command, ok: !error, code: error?.code ?? null, message: error?.message ?? null,
+        ...(error?.hint ? { hint: error.hint } : {}), ...(error?.details ? { details: error.details } : {}),
+        artifacts, elapsedMs: Math.round(performance.now() - started), ...(jobId ? { jobId } : {}), data };
+      index('end', { state: !error ? 'succeeded' : error.code === 'cancelled' ? 'cancelled' : 'failed' });
+      emit('result', result);
+      return result;
+    },
+    dispose() { clearInterval(timer); cancelHandlers.clear(); for (const [signal, handler] of signals) process.off(signal, handler); },
+  };
+}
+
+export async function runCommand(command, shot, options, action, job = true) {
+  let events, resources, linted = false;
+  try {
+    const explicit = options;
+    const user = loadUserConfig(command, options);
+    options = user.options;
+    if (['render', 'stills', 'verify'].includes(command)) {
+      options.quality = resolveQuality(options);
+      if (options.quality === 'draft') options.draft = true;
+    }
+    if (job || ['lint', 'inspect'].includes(command)) {
+      if (typeof shot !== 'string' || !shot.trim()) throw invalidOption('shot', 'Provide a shot HTML path.');
+      if (options.root !== undefined && typeof options.root !== 'string') throw invalidOption('--root', '--root must be a path.');
+      shot = path.resolve(options.root ?? process.cwd(), shot);
+    }
+    const positive = ['scale', 'render-scale', 'fps', 'workers', 'motion-blur', 'max-motion-blur', 'every', 'max-bitrate'];
+    for (const key of [...positive, 'from', 'to', 'shutter', 'grain', 'adaptive-blur', 'audio-offset', 'wait']) {
+      if (options[key] === undefined) continue;
+      const value = Number(options[key]);
+      if (!String(options[key]).trim() || !Number.isFinite(value) || value < 0 || (positive.includes(key) && value === 0)
+        || (['workers', 'motion-blur', 'max-motion-blur'].includes(key) && !Number.isSafeInteger(value))) throw invalidOption(`--${key}`, `Invalid value for --${key}.`);
+      options[key] = value;
+    }
+    if (command === 'render') {
+      // A saved MP4 preference must not override a requested fixed-codec container.
+      const inferred = resolveFormat({ ...options, encoder: explicit.encoder });
+      if (inferred !== 'mp4' && explicit.encoder === undefined) {
+        delete options.encoder;
+        user.config.applied = user.config.applied.filter(field => field !== 'encoder');
+      }
+      options.format = inferred;
+    } else if (job && ['stills', 'verify'].includes(command)) {
+      // TODO(design): Document PNG as the frame format reported by stills and verify.
+      options.format = 'png';
+    }
+    const defaults = job ? { root: process.cwd(), raster: 'gpu', scale: 1, 'render-scale': Number(options.scale ?? 1), upscale: 'lanczos',
+      'adaptive-blur': 0.5, 'no-post': false, 'no-lint': false, overwrite: false, 'job-dir': jobDirectory(options),
+      ...(command === 'render' ? { from: 0, ...(options.format === 'mp4' ? { encoder: 'x264' } : {}), workers: defaultWorkers(Number(options.scale ?? 1)), ffmpeg: process.env.MULTIPLANE_FFMPEG ?? ffmpegName() } : {}),
+      ...(command === 'verify' ? { workers: 2 } : {}),
+      ...(command === 'stills' && options.at === undefined ? { every: 1 } : {}) }
+      : ['lint', 'inspect', 'serve'].includes(command) ? { root: process.cwd() } : command === 'benchmark' ? { raster: 'gpu' }
+        : command === 'doctor' ? { raster: 'gpu', ffmpeg: process.env.MULTIPLANE_FFMPEG ?? ffmpegName() }
+        : { 'job-dir': jobDirectory(options), ...(command === 'cancel' ? { wait: 30 } : {}) };
+    // TODO(design): Document that start waits for effective shot alpha defaults.
+    events = createEvents(command, shot, { ...defaults, ...options }, job, job && ['render', 'stills', 'verify'].includes(command));
+    events.config = user.config;
+    if (command === 'render') events.workersSource = explicit.workers !== undefined ? 'option' : user.config.applied.includes('workers') ? 'config' : 'estimate';
+    events.migration = user.migration;
+    if (options['hosted-executor']) events.start();
+    // Defer start events until the owner is known. Lint failure remains local.
+    if (await hostedAvailable(command, options)) {
+      if (!options['no-lint']) { await checkLint(shot, events.options, events); linted = true; }
+      events.start();
+      const request = { schema: 'multiplane/1', jobId: events.jobId, jobDir: events.directory,
+        command, args: options._hostedCLI.args, cwd: process.cwd(), node: process.execPath,
+        bin: options._hostedCLI.bin, env: hostedEnvironment(process.env), at: new Date().toISOString() };
+      const ownership = await handoff(request);
+      if (ownership.hosted) {
+        const directory = events.directory;
+        events.dispose(); events = undefined;
+        return await followJob(directory, { onBytes: options._hostedCLI.onBytes });
+      }
+      process.stderr.write('Rendering locally: ' + ownership.reason + '\n');
+    }
+    // CLI transport callbacks must never enter workerData or shot evaluation.
+    delete options._hostedCLI;
+    delete events.options._hostedCLI;
+    events.monitor();
+    if (job) {
+      resources = createResourceSampler({ enabled: options._resources !== false, onSample: events.memory });
+      events.resources = resources;
+    }
+    if (options.draft) {
+      // Keep lint and cancellation active before the dimension-only draft probe.
+      if (!linted && !options['no-lint']) {
+        const { findings, data } = await scanShot(shot, events.options);
+        if (data.errors) {
+          events.start();
+          for (const finding of findings) events.emit('finding', finding);
+          throw new MultiplaneError('lint_failed', undefined, { result: { data } });
+        }
+      }
+      const normalized = { ...Object.fromEntries(Object.keys(explicit).filter(key => key !== '_hostedCLI').map(key => [key, options[key]])), draft: true };
+      Object.assign(events.options, await applyDraft(command, shot, normalized, options, {
+        check: events.check,
+        onBrowser: browser => {
+          const unsubscribe = events.onCancel(() => browser.close());
+          browser.once('disconnected', unsubscribe);
+          events.check();
+        },
+      }));
+    }
+    events.start();
+    for (const warning of user.warnings) events.warning(warning);
+    if ((job || command === 'inspect') && !linted && !options['no-lint']) await checkLint(shot, events.options, events);
+    if (job && options.out && !options.overwrite) await requireNewOutput(path.resolve(options.out));
+    const data = job && ['stills', 'verify'].includes(command) && options.out && options.overwrite
+      ? await directoryOutput(events, action) : await action(events);
+    events.check();
+    if (job) events.finalize();
+    if (resources) { await resources.stop(); data.resources = { ...resources.snapshot(), ...(events.workersSource ? { workersSource: events.workersSource } : {}) }; }
+    if (['render', 'stills', 'verify'].includes(command)) data.quality = options.quality;
+    return events.finish(data);
+  } catch (failure) {
+    let error = asError(failure);
+    try { events?.check(); } catch (cancelled) { error = cancelled; }
+    events ??= createEvents(command, shot, options);
+    await resources?.stop();
+    error.result = events.finish({ ...error.result?.data, ...(resources ? { resources: { ...resources.snapshot(), ...(events.workersSource ? { workersSource: events.workersSource } : {}) } } : {}) }, error);
+    throw error;
+  } finally { await resources?.stop(); events?.dispose(); }
+}

package/src/ffmpeg.mjs

@@ -0,0 +1,32 @@
+import { spawn } from 'node:child_process';
+import { MultiplaneError } from './errors.mjs';
+import { ffmpegName, ffmpegHint } from './platform.mjs';
+
+export function ffmpegOutput(executable, args, env = process.env) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, args, { env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+    const timer = setTimeout(() => child.kill('SIGKILL'), 15000);
+    child.once('close', () => clearTimeout(timer));
+    child.once('error', () => clearTimeout(timer));
+    let output = '';
+    child.stdout.on('data', bytes => { output += bytes; });
+    child.stderr.on('data', bytes => { output += bytes; });
+    child.once('error', reject);
+    child.once('close', code => code === 0 ? resolve(output) : reject(new Error(`FFmpeg exited with code ${code}.`)));
+  });
+}
+export async function inspectFFmpeg(explicit, env = process.env, encoder, output = ffmpegOutput) {
+  const executable = explicit ?? env.MULTIPLANE_FFMPEG ?? ffmpegName();
+  try {
+    const version = (await output(executable, ['-version'], env)).split(/\r?\n/)[0];
+    if (encoder && !new RegExp(`\\b${encoder}\\b`).test(await output(executable, ['-encoders'], env))) throw new Error(`Missing encoder: ${encoder}`);
+    return { path: executable, version };
+  } catch (cause) {
+    throw new MultiplaneError(cause.code === 'ENOENT' ? 'ffmpeg_not_found' : 'ffmpeg_unusable', undefined,
+      { cause, hint: cause.message.startsWith('Missing encoder:') ? `${cause.message}. Use an FFmpeg build that includes it.` : ffmpegHint(), details: { reason: cause.message } });
+  }
+}
+
+export async function resolveFFmpeg(explicit, env = process.env) {
+  return (await inspectFFmpeg(explicit, env)).path;
+}

package/src/format.mjs

@@ -0,0 +1,27 @@
+import path from 'node:path';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { encoderArgs } from './encoder.mjs';
+
+export function resolveFormat(options = {}) {
+  const extension = path.extname(options.out ?? '').slice(1).toLowerCase();
+  const formats = ['mp4', 'webm', 'mov'];
+  const format = options.format ?? (formats.includes(extension) ? extension : 'mp4');
+  if (!formats.includes(format)) throw invalidOption('--format', '--format must be mp4, webm or mov.');
+  // TODO(design): Document rejection of unknown output extensions as well as conflicts.
+  if (extension && extension !== format) throw invalidOption('--out', '--out extension must match --format.');
+  if (format !== 'mp4' && options.encoder !== undefined) throw invalidOption('--encoder', '--encoder only applies to mp4; omit it for webm or mov.');
+  // TODO(design): Define bitrate controls for the fixed-codec formats if needed.
+  if (format !== 'mp4' && options['max-bitrate'] !== undefined) throw invalidOption('--max-bitrate', '--max-bitrate currently only applies to mp4.');
+  if (format === 'mp4' && options.alpha) throw new MultiplaneError('invalid_option', 'MP4 does not support alpha.', { details: { option: '--alpha' }, hint: 'Use --format webm or --format mov and a matching --out extension.' });
+  return format;
+}
+
+export function videoEncoding(options) {
+  const { format, alpha } = options;
+  if (format === 'webm') {
+    // TODO(design): Document the fixed VP9 quality preset and audio codec.
+    return { encoder: 'libvpx-vp9', args: ['-c:v', 'libvpx-vp9', '-crf', alpha ? '0' : '16', '-b:v', '0', '-auto-alt-ref', '0', ...(alpha ? ['-lossless', '1'] : [])], pixelFormat: alpha ? 'yuva420p' : 'yuv420p', mux: [], audio: ['-c:a', 'libopus', '-b:a', '320k', '-ac', '2'] };
+  }
+  if (format === 'mov') return { encoder: 'prores_ks', args: ['-c:v', 'prores_ks', '-profile:v', '4'], pixelFormat: alpha ? 'yuva444p10le' : 'yuv444p10le', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
+  return { encoder: options.encoder ?? 'x264', args: encoderArgs(options.encoder ?? 'x264', undefined, options['max-bitrate']), pixelFormat: 'yuv420p', mux: ['-movflags', '+faststart'], audio: ['-c:a', 'aac', '-b:a', '320k', '-ac', '2'] };
+}

package/src/frame-rate.mjs

@@ -0,0 +1,28 @@
+import { invalidOption } from './errors.mjs';
+
+// Encoding time only: capture and post-processing must keep the requested fps.
+// Snap NTSC shorthand within 0.0001 fps of n * 1000 / 1001. Otherwise round
+// to six decimal places (at most 0.0000005 fps error) and reduce the fraction.
+// FFmpeg's AVRational stores both terms as signed 32-bit integers.
+export function frameRate(fps) {
+  if (!Number.isFinite(fps) || fps <= 0) throw invalidOption('--fps', '--fps must be positive and finite.');
+  const nominal = Math.round(fps * 1001 / 1000);
+  let numerator, denominator;
+  if (nominal > 0 && Math.abs(fps - nominal * 1000 / 1001) <= 0.0001) {
+    numerator = nominal * 1000;
+    denominator = 1001;
+  } else {
+    numerator = Math.round(fps * 1e6);
+    denominator = 1e6;
+  }
+  if (!Number.isSafeInteger(numerator) || numerator <= 0) throw invalidOption('--fps', 'Frame rate cannot be represented at micro-fps precision.');
+  let a = numerator, b = denominator;
+  while (b) [a, b] = [b, a % b];
+  numerator /= a; denominator /= a;
+  if (numerator > 2147483647) throw invalidOption('--fps', 'Frame rate exceeds FFmpeg rational precision.');
+  return {
+    numerator, denominator, argument: `${numerator}/${denominator}`,
+    fps: numerator / denominator,
+    seconds: frames => frames * denominator / numerator,
+  };
+}

package/src/home-migration.mjs

@@ -0,0 +1,54 @@
+import path from 'node:path';
+import os from 'node:os';
+import { randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, openSync, closeSync, copyFileSync, renameSync, unlinkSync } from 'node:fs';
+import { userHome } from './platform.mjs';
+
+const present = file => {
+  try { lstatSync(file); return true; }
+  catch (error) { if (error.code === 'ENOENT') return false; throw error; }
+};
+
+// Use the writers' locks, including the config lock introduced in 038.
+// Publish only complete copies, and recheck the destination under the lock.
+export function migrateUserHome(env = process.env, platform = process.platform, home = os.homedir()) {
+  const result = { migrated: [], warnings: [] };
+  if (platform !== 'win32' || env.MULTIPLANE_HOME) return result;
+  const directory = userHome(env, platform, home);
+  const previous = path.win32.join(env.APPDATA || path.win32.join(env.USERPROFILE || home, 'AppData', 'Roaming'), 'multiplane');
+  if (path.win32.resolve(previous).toLowerCase() === path.win32.resolve(directory).toLowerCase()) return result;
+  for (const [lockName, names] of [['config.json.lock', ['config.json']], ['jobs.lock', ['jobs.jsonl', 'jobs.1.jsonl']]]) {
+    let handle;
+    const lock = path.join(directory, lockName);
+    try {
+      if (!names.some(name => !present(path.join(directory, name)) && present(path.join(previous, name)))) continue;
+      mkdirSync(directory, { recursive: true });
+      const deadline = performance.now() + 10000;
+      for (;;) {
+        try { handle = openSync(lock, 'wx'); break; }
+        catch (error) {
+          if (error.code !== 'EEXIST' || performance.now() >= deadline) throw error;
+          Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+        }
+      }
+      for (const name of names) {
+        const target = path.join(directory, name), source = path.join(previous, name);
+        if (present(target) || !present(source)) continue;
+        const temporary = target + '.' + randomUUID() + '.tmp';
+        try {
+          copyFileSync(source, temporary);
+          renameSync(temporary, target);
+          result.migrated.push({ name, source });
+        } finally { try { unlinkSync(temporary); } catch (error) { if (error.code !== 'ENOENT') throw error; } }
+      }
+    } catch {
+      result.warnings.push({ code: 'home_unavailable', message: 'User directory migration could not be completed.' });
+    } finally {
+      if (handle !== undefined) {
+        closeSync(handle);
+        try { unlinkSync(lock); } catch { result.warnings.push({ code: 'home_unavailable', message: 'User directory migration lock could not be removed.' }); }
+      }
+    }
+  }
+  return result;
+}