multiplane 0.0.0-stage → 0.3.0

package/src/render.mjs

@@ -0,0 +1,157 @@
+import { readBenchmark, validBenchmark, benchmarkMachine, selectWorkers, classifyShot } from './workers.mjs';
+import { recoveryBudget } from './browser-recovery.mjs';
+import path from 'node:path';
+import { mkdir, rm, writeFile } from 'node:fs/promises';
+import { createHash } from 'node:crypto';
+import { spawn } from 'node:child_process';
+import { stopChild } from './process.mjs';
+import { inspectFFmpeg } from './ffmpeg.mjs';
+import { openShot, number } from './capture.mjs';
+import { createPostCapture, resolveScale } from './post.mjs';
+import { createRenderPool } from './render-pool.mjs';
+import { resolveFormat, videoEncoding } from './format.mjs';
+import { checkAlphaVideo } from './output-alpha.mjs';
+import { writeFrame } from './video-pipe.mjs';
+import { runCommand } from './events.mjs';
+import { loaded, observeBrowser, environment } from './environment.mjs';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { requireNewOutput, publishVideo } from './artifacts.mjs';
+import { createPreview } from './preview.mjs';
+import { checkVideo } from './output-check.mjs';
+import { frameRate } from './frame-rate.mjs';
+
+export async function renderShot(shot, options = {}) {
+  return runCommand('render', shot, options, async events => {
+    options = { ...events.options };
+    delete options.onEvent;
+    const probe = options._probeVideo;
+    delete options._probeVideo;
+    const inspect = options._inspectFFmpeg ?? inspectFFmpeg;
+    delete options._inspectFFmpeg;
+    options._browserRecovery = recoveryBudget();
+    const name = path.basename(shot, path.extname(shot));
+    let result;
+
+    let capture, pool, encoder, temporary, cleaning, encoderClosed = false;
+    function cleanup() { return cleaning ??= cleanResources(); }
+    async function cleanResources() {
+      try {
+        if (encoder && !encoderClosed) await stopChild(encoder);
+      } finally {
+        try { await capture?.close(); }
+        finally { try { await pool?.close(); } finally { if (temporary) await rm(temporary, { force: true }); } }
+      }
+    }
+
+    try {
+      const out = path.resolve(options.out ?? path.join(events.directory, `${name}.${options.format}`));
+      if (!options.overwrite) await requireNewOutput(out);
+      events.check();
+      events.progress('launch');
+      const { scale, renderScale } = resolveScale(options);
+      const encoding = videoEncoding(options);
+      let videoArgs = encoding.args;
+      const ffmpegInfo = await inspect(options.ffmpeg, process.env, { x264: 'libx264', 'nvenc-h264': 'h264_nvenc', 'nvenc-hevc': 'hevc_nvenc' }[encoding.encoder] ?? encoding.encoder);
+      const ffmpeg = ffmpegInfo.path;
+      options.transport = 'raw';
+      const audioOffset = number(options['audio-offset'] ?? 0, '--audio-offset');
+      if (options['audio-offset'] !== undefined && !options.audio) throw invalidOption('--audio-offset', '--audio-offset requires --audio.');
+      capture = await openShot(shot, renderScale, { ...options, onWarning: events.warning, check: events.check, onBrowser: observeBrowser(events, ffmpegInfo) });
+      const record = ['option', 'config'].includes(events.workersSource) ? null : readBenchmark();
+      let machine, type;
+      if (record) {
+        try {
+          machine = benchmarkMachine(await environment(capture.browser), options.raster);
+          if (validBenchmark(record, machine)) type = await classifyShot(capture);
+        } catch { /* Optional tuning must not prevent an otherwise valid render. */ }
+      }
+      const selection = selectWorkers({ workers: options.workers, source: events.workersSource, record, machine, type,
+        scale, memoryScale: Math.max(scale, renderScale) });
+      const workers = selection.workers;
+      options.workers = events.options.workers = workers;
+      // TODO(design): Document workersSource on start and result.data.resources.
+      events.workersSource = selection.source;
+      options.alpha = events.options.alpha = capture.alpha;
+      resolveFormat(options);
+      Object.assign(encoding, videoEncoding(options));
+      videoArgs = encoding.args;
+      await loaded(events, capture, ffmpegInfo);
+      const fps = number(options.fps ?? capture.fps, '--fps', { positive: true });
+      const rate = frameRate(fps);
+      const processed = createPostCapture(capture, options, fps);
+      const from = number(options.from ?? 0, '--from');
+      const to = number(options.to ?? capture.duration, '--to');
+      if (to <= from || to > capture.duration) throw invalidOption('--to', 'Require 0 <= from < to <= shot duration.');
+      const first = Math.ceil(from * fps - 1e-9);
+      const end = Math.ceil(to * fps - 1e-9);
+      const total = end - first;
+      if (!total) throw invalidOption('--from', 'Range contains no frames.');
+      const { width, height } = capture;
+      events.progress('capture', 0, total);
+      await capture.close(); capture = undefined;
+      events.check();
+      const actualWorkers = Math.min(workers, Math.ceil(total / 4));
+      events.resources.setWorkers(actualWorkers);
+      const started = performance.now();
+      const frameHashes = process.env.RENDER_FRAME_HASHES ? [] : null;
+      pool = createRenderPool(shot, options, fps, actualWorkers, { width, height }, events.warning);
+      events.onCancel(() => pool?.cancel());
+      await mkdir(path.dirname(out), { recursive: true });
+      events.check();
+      temporary = `${out}.${events.jobId}.partial.${options.format}`;
+      const audioArgs = options.audio
+        ? ['-i', path.resolve(options.audio), '-map', '0:v:0', '-map', '1:a:0', '-af', `atrim=start=${audioOffset + rate.seconds(first)},asetpts=PTS-STARTPTS,apad,atrim=duration=${rate.seconds(total)}`, ...encoding.audio]
+        : ['-an'];
+      // Supported since FFmpeg 5.1; older FFmpeg uses the global -vsync 0.
+      // Do not add output -r: passthrough must neither drop nor duplicate frames.
+      encoder = spawn(ffmpeg, ['-hide_banner', '-loglevel', 'error', '-y', '-f', 'rawvideo', '-pixel_format', 'rgba', '-video_size', `${width * scale}x${height * scale}`, '-framerate', rate.argument, '-i', 'pipe:0', ...audioArgs, ...videoArgs, '-fps_mode', 'passthrough', '-pix_fmt', encoding.pixelFormat, ...encoding.mux, temporary], { windowsHide: true, stdio: ['pipe', 'ignore', 'pipe'] });
+      encoder.once('close', () => { encoderClosed = true; });
+      events.onCancel(() => stopChild(encoder));
+      let stderr = '', failure;
+      encoder.stderr.on('data', data => { stderr = (stderr + data).slice(-8000); });
+      encoder.stdin.on('error', error => { failure = error; });
+      const finished = new Promise((resolve, reject) => {
+        encoder.once('error', cause => reject(new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } })));
+        encoder.once('close', code => code === 0 ? resolve() : reject(new MultiplaneError('encode_failed', undefined, { details: { exitCode: code, stderr } })));
+      });
+      finished.catch(error => { failure = error; });
+      const alphaReferences = new Map();
+      let encoderWriteMs = 0, framesSent = 0;
+      // Internal switch for the pixel-equivalence and overhead tests, not a CLI option.
+      const preview = createPreview(events, width * scale, height * scale, { enabled: options._preview !== false });
+      for await (const { frame, png } of pool.frames(first, end, async ({ frame, png }) => {
+        events.check();
+        await preview(png, frame);
+        events.progress('capture', frame - first + 1, total);
+      })) {
+        events.check();
+        if (failure) throw new MultiplaneError('encode_failed', undefined, { cause: failure });
+        if (options.alpha && (framesSent === 0 || framesSent === Math.floor(total / 2))) alphaReferences.set(framesSent, Buffer.from(png.filter((_, i) => i % 4 === 3)));
+        frameHashes?.push({ frame, sha256: createHash('sha256').update(png).digest('hex') });
+        const writeStarted = performance.now();
+        await writeFrame(encoder.stdin, png).catch(cause => { throw new MultiplaneError('encode_failed', undefined, { cause, details: { reason: cause.message } }); });
+        encoderWriteMs += performance.now() - writeStarted;
+        framesSent++;
+      }
+      const drainStarted = performance.now();
+      events.progress('encode', total, total);
+      encoder.stdin.end();
+      await finished;
+      events.check();
+      const encoderDrainMs = performance.now() - drainStarted;
+      const probeStarted = performance.now();
+      const outputCheck = await checkVideo(ffmpeg, temporary, { frames: framesSent, durationSeconds: rate.seconds(framesSent), width: width * scale, height: height * scale, fps: rate.fps, ...(options.alpha ? { alpha: true, format: options.format } : {}) }, events, probe);
+      if (options.alpha) await checkAlphaVideo(ffmpeg, temporary, options.format, alphaReferences, width * scale, height * scale, events);
+      const outputCheckMs = performance.now() - probeStarted;
+      await publishVideo(temporary, out, options.overwrite);
+      temporary = undefined;
+      const elapsed = (performance.now() - started) / 1000;
+      if (frameHashes) await writeFile(process.env.RENDER_FRAME_HASHES, JSON.stringify(frameHashes, null, 2));
+      if (process.env.RENDER_PROFILE) await writeFile(process.env.RENDER_PROFILE, JSON.stringify({elapsed,frames:total,workers:actualWorkers,options,stats:pool.stats,encoderWriteMs,encoderDrainMs,outputCheckMs},null,2));
+      events.artifact(out, 'video');
+      result = { staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, output: out, frames: framesSent, fps, from, to, width: width * scale, height: height * scale, encoder: encoding.encoder, format: options.format, alpha: options.alpha, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, renderScale, scale, outputCheck };
+    } finally { await cleanup(); }
+
+    return options.draft ? { ...result, draft: true } : result;
+  });
+}

package/src/resource-path.mjs

@@ -0,0 +1,29 @@
+import path from 'node:path';
+import { realpath } from 'node:fs';
+import { promisify } from 'node:util';
+
+const nativeRealpath = promisify(realpath.native);
+
+// Resolve aliases (including Windows 8.3 names) even for missing descendants.
+export async function normalizeResourcePath(file) {
+  const absolute = path.resolve(file);
+  try { return await nativeRealpath(absolute); }
+  catch (error) {
+    if (error.code !== 'ENOENT' && error.code !== 'ENOTDIR') throw error;
+    const parent = path.dirname(absolute);
+    if (parent === absolute) return absolute;
+    return path.join(await normalizeResourcePath(parent), path.basename(absolute));
+  }
+}
+
+export function relativeResourcePath(root, target, platform = process.platform) {
+  const paths = platform === 'win32' ? path.win32 : path.posix;
+  return paths.relative(platform === 'win32' ? root.toLowerCase() : root,
+    platform === 'win32' ? target.toLowerCase() : target);
+}
+
+export async function isInsideResourceRoot(root, target) {
+  const [base, file] = await Promise.all([normalizeResourcePath(root), normalizeResourcePath(target)]);
+  const relative = relativeResourcePath(base, file);
+  return relative !== '..' && !relative.startsWith('..' + path.sep) && !path.isAbsolute(relative);
+}

package/src/resources.mjs

@@ -0,0 +1,27 @@
+import { cpus } from 'node:os';
+import { createProcessTreeReader } from './platform.mjs';
+
+// Diagnostics only: never pass these values to frame generation.
+export function createResourceSampler({ sample, intervalMs = 1000, onSample = () => {}, enabled = true } = {}) {
+  const reader = !sample && enabled ? createProcessTreeReader() : undefined;
+  sample ??= reader?.sample;
+  let pending, timer, stopped = false, peakMemoryBytes = null, memorySamples = 0, workers = 1;
+  const take = () => {
+    if (pending || stopped || !enabled) return pending ?? Promise.resolve();
+    clearTimeout(timer);
+    pending = (async () => {
+      let bytes = null;
+      try { const value = await sample(); if (Number.isSafeInteger(value) && value > 0) bytes = value; } catch {}
+      if (bytes !== null) { peakMemoryBytes = Math.max(peakMemoryBytes ?? 0, bytes); memorySamples++; }
+      try { onSample(bytes); } catch {}
+    })().finally(() => { pending = undefined; if (!stopped) { timer = setTimeout(take, intervalMs); timer.unref(); } });
+    return pending;
+  };
+  void take();
+  return {
+    sample: take,
+    setWorkers(value) { workers = value; },
+    snapshot: () => ({ peakMemoryBytes, memorySamples, workers, cpuCount: cpus().length || null }),
+    async stop() { stopped = true; clearTimeout(timer); await pending; await reader?.close(); },
+  };
+}

package/src/runtime/camera.js

@@ -0,0 +1,37 @@
+(function () {
+  const E = Shot.ease;
+
+  function interp(a, b, k) {
+    const s = a.s * Math.pow(b.s / a.s, k);
+    if (b.s >= a.s) {
+      const px = (b.f[0] - a.f[0]) * a.s * (1 - k);
+      const py = (b.f[1] - a.f[1]) * a.s * (1 - k);
+      return { f: [b.f[0] - px / s, b.f[1] - py / s], s };
+    }
+    const px = (a.f[0] - b.f[0]) * b.s * k;
+    const py = (a.f[1] - b.f[1]) * b.s * k;
+    return { f: [a.f[0] - px / s, a.f[1] - py / s], s };
+  }
+
+  function track(keys) {
+    function at(t) {
+      if (t <= keys[0].t) return { f: keys[0].f, s: keys[0].s };
+      for (let i = 1; i < keys.length; i++) {
+        const a = keys[i - 1], b = keys[i];
+        if (b.t === a.t) continue;
+        if (t < b.t) return interp(a, b, (b.ease || E.inOutCubic)((t - a.t) / (b.t - a.t)));
+      }
+      const z = keys[keys.length - 1];
+      return { f: z.f, s: z.s };
+    }
+    return {
+      at,
+      apply(node, t, w = Shot.size.w, h = Shot.size.h) {
+        const { f, s } = at(t);
+        node.setAttribute('transform', `translate(${w / 2} ${h / 2}) scale(${s}) translate(${-f[0]} ${-f[1]})`);
+      },
+    };
+  }
+
+  window.Camera = { track, linear: k => k };
+})();

package/src/runtime/shot.css

@@ -0,0 +1,9 @@
+html, body { margin: 0; height: 100%; overflow: hidden; background: var(--multiplane-page-background, #000); }
+#stage {
+  position: absolute; left: 0; top: 0;
+  width: 1920px; height: 1080px;
+  transform-origin: 0 0;
+  overflow: hidden;
+  background: var(--paper, #fff);
+}
+#stage > svg { display: block; }

package/src/runtime/shot.js

@@ -0,0 +1,71 @@
+(function () {
+  const params = new URLSearchParams(location.search);
+  const mode = params.get('mode') || 'standalone';
+  const stage = document.getElementById('stage');
+  const css = stage && getComputedStyle(stage);
+  const size = css ? { w: parseFloat(css.width), h: parseFloat(css.height) } : { w: 1920, h: 1080 };
+
+  const E = {
+    clamp: (x, a = 0, b = 1) => Math.min(b, Math.max(a, x)),
+    lerp: (a, b, k) => a + (b - a) * k,
+    prog: (t, start, dur) => E.clamp((t - start) / dur),
+    inCubic: k => k * k * k,
+    outCubic: k => 1 - Math.pow(1 - k, 3),
+    outQuart: k => 1 - Math.pow(1 - k, 4),
+    outExpo: k => (k >= 1 ? 1 : 1 - Math.pow(2, -10 * k)),
+    inOutCubic: k => (k < 0.5 ? 4 * k * k * k : 1 - Math.pow(-2 * k + 2, 3) / 2),
+    inOutQuart: k => (k < 0.5 ? 8 * k ** 4 : 1 - Math.pow(-2 * k + 2, 4) / 2),
+  };
+
+  function fitStage(stage) {
+    if (mode === 'render') return;
+    const s = Math.min(innerWidth / size.w, innerHeight / size.h);
+    const x = (innerWidth - size.w * s) / 2;
+    const y = (innerHeight - size.h * s) / 2;
+    stage.style.transform = `translate(${x}px, ${y}px) scale(${s})`;
+  }
+
+  // spec: { duration, fps?, fonts?: [[font, text?]...], setup?(), render(t) }
+  function define(spec) {
+    const stage = document.getElementById('stage');
+    document.documentElement.dataset.mode = mode;
+    fitStage(stage);
+    addEventListener('resize', () => fitStage(stage));
+
+    const fontLoads = (spec.fonts || []).map(([f, text]) => document.fonts.load(f, text));
+    const ready = Promise.all(fontLoads)
+      .then(() => document.fonts.ready)
+      .then(() => (spec.setup ? spec.setup() : null))
+      .then(() => spec.render(0));
+    // The host awaits ready after navigation; preserve its rejection without
+    // reporting an early unhandled rejection as a generic script load failure.
+    ready.catch(() => {});
+
+    window.SHOT = {
+      get duration() { return spec.duration; },
+      fps: spec.fps || 30,
+      get cuts() { return spec.cuts || []; },
+      post: spec.post || {},
+      meta: spec.meta === undefined ? null : spec.meta,
+      ready,
+      ...(spec.blurAt ? { blurAt: t => spec.blurAt(t) } : {}),
+      render: t => spec.render(Math.min(Math.max(t, 0), spec.duration)),
+    };
+
+    if (mode === 'standalone') {
+      ready.then(() => {
+        const fixed = params.get('t');
+        if (fixed !== null) return window.SHOT.render(+fixed);
+        const t0 = performance.now();
+        const loop = now => {
+          const t = ((now - t0) / 1000) % (spec.duration + 1);
+          window.SHOT.render(t);
+          requestAnimationFrame(loop);
+        };
+        requestAnimationFrame(loop);
+      });
+    }
+  }
+
+  window.Shot = { define, ease: E, mode, size };
+})();

package/src/serve.mjs

@@ -0,0 +1,23 @@
+import { runCommand } from './events.mjs';
+import { startServer } from './server.mjs';
+import { stopSignals } from './platform.mjs';
+
+export async function serve(options = {}) {
+  return runCommand('serve', null, options, async events => {
+    let server;
+    let stop;
+    const stopped = new Promise(resolve => { stop = resolve; });
+    const signals = stopSignals();
+    for (const signal of signals) process.on(signal, stop);
+    try {
+      server = await startServer(events.options.port ?? 0, events.options.root);
+      const { url, root, port } = server;
+      events.emit('listening', { url, root, port });
+      await stopped;
+      return {};
+    } finally {
+      try { await server?.close(); }
+      finally { for (const signal of signals) process.off(signal, stop); }
+    }
+  }, false);
+}

package/src/server.mjs

@@ -0,0 +1,93 @@
+import { normalizeResourcePath, isInsideResourceRoot } from './resource-path.mjs';
+import http from 'node:http';
+import { createReadStream } from 'node:fs';
+import { stat, readdir } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+
+export const root = process.cwd();
+const packageRoot = fileURLToPath(new URL('../', import.meta.url));
+const mime = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.mjs': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.gif': 'image/gif', '.webp': 'image/webp', '.avif': 'image/avif', '.woff2': 'font/woff2', '.ttf': 'font/ttf', '.json': 'application/json' };
+
+export async function startServer(port = 0, root = process.cwd()) {
+  if (typeof root !== 'string' || !root.trim()) throw invalidOption('--root', '--root must be a directory path.');
+  if (!String(port).trim() || !Number.isInteger(Number(port)) || Number(port) < 0 || Number(port) > 65535) throw invalidOption('--port', '--port must be an integer from 0 to 65535.');
+  port = Number(port);
+  const base = await normalizeResourcePath(root);
+  try { if (!(await stat(base)).isDirectory()) throw new Error(); }
+  catch { throw invalidOption('--root', '--root must be an existing directory.'); }
+  root = base;
+  async function shots(directory = base, ancestors = new Set()) {
+    const canonical = await normalizeResourcePath(directory);
+    if (ancestors.has(canonical) || !await isInsideResourceRoot(base, canonical)) return [];
+    const parents = new Set([...ancestors, canonical]), found = [];
+    for (const entry of await readdir(directory, { withFileTypes: true })) {
+      if (entry.name.startsWith('.') || ['node_modules', 'out'].includes(entry.name)) continue;
+      const file = path.join(directory, entry.name);
+      if (!await isInsideResourceRoot(base, file)) continue;
+      let info;
+      try { info = await stat(file); } catch (error) { if (error.code === 'ENOENT') continue; throw error; }
+      if (info.isDirectory()) found.push(...await shots(file, parents));
+      else if (info.isFile() && path.extname(file).toLowerCase() === '.html') found.push(path.relative(base, file).split(path.sep).join('/'));
+    }
+    return found;
+  }
+  const server = http.createServer(async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    try {
+      if (!['GET', 'HEAD'].includes(req.method)) { res.writeHead(405); return res.end(); }
+      const pathname = decodeURIComponent(new URL(req.url, 'http://localhost').pathname);
+
+      const segments = pathname.replaceAll('\\', '/').split('/');
+      if (segments.some(p => p.startsWith('.') || p === 'node_modules')) { res.writeHead(403); return res.end(); }
+      let resourceRoot = root, resourceBase = base, resourcePath = pathname;
+      // /multiplane/ is reserved for runtime resources.
+      if (pathname.startsWith('/multiplane/')) {
+        if (pathname === '/multiplane/shots.json') {
+          const body = JSON.stringify((await shots()).sort());
+          res.writeHead(200, { 'Content-Type': mime['.json'], 'Content-Length': Buffer.byteLength(body) });
+          return res.end(req.method === 'HEAD' ? undefined : body);
+        }
+        if (pathname.startsWith('/multiplane/runtime/')) { resourceRoot = path.join(packageRoot, 'src/runtime'); resourcePath = pathname.slice('/multiplane/runtime'.length); }
+        else if (pathname === '/multiplane/three.js') { resourceRoot = path.join(packageRoot, 'src/three'); resourcePath = '/index.js'; }
+        else if (pathname.startsWith('/multiplane/vendor/three/')) {
+          resourceRoot = path.dirname(path.dirname(fileURLToPath(import.meta.resolve('three'))));
+          resourcePath = pathname.slice('/multiplane/vendor/three'.length);
+          if (!/^\/(build|examples\/jsm)\/.*\.js$/.test(resourcePath)) { res.writeHead(403); return res.end(); }
+        } else { res.writeHead(404); return res.end(); }
+        resourceBase = await normalizeResourcePath(resourceRoot);
+      }
+      let target = path.resolve(resourceRoot, `.${resourcePath}`);
+      if (!await isInsideResourceRoot(resourceRoot, target)) { res.writeHead(403); return res.end(); }
+      if ((await stat(target)).isDirectory()) target = path.join(target, 'index.html');
+      target = await normalizeResourcePath(target);
+      if (!await isInsideResourceRoot(resourceBase, target)) { res.writeHead(403); return res.end(); }
+      const info = await stat(target);
+      const contentType = { '.wav': 'audio/wav', '.srt': 'text/plain; charset=utf-8', '.mp4': 'video/mp4' }[path.extname(target)] ?? mime[path.extname(target)] ?? 'application/octet-stream';
+      const headers = { 'Content-Type': contentType, 'Content-Length': info.size, 'Accept-Ranges': 'bytes' };
+      if (req.headers.range) {
+        const match = /^bytes=(\d*)-(\d*)$/.exec(req.headers.range);
+        let start = match?.[1] ? Number(match[1]) : Math.max(0, info.size - Number(match?.[2]));
+        let end = match?.[1] && match[2] ? Math.min(Number(match[2]), info.size - 1) : info.size - 1;
+        if (!match || (!match[1] && !match[2]) || !Number.isSafeInteger(start) || start < 0 || start > end) {
+          res.writeHead(416, { 'Content-Range': `bytes */${info.size}` }); return res.end();
+        }
+        res.writeHead(206, { ...headers, 'Content-Length': end - start + 1, 'Content-Range': `bytes ${start}-${end}/${info.size}` });
+        if (req.method === 'HEAD') return res.end();
+        return createReadStream(target, { start, end }).on('error', () => res.destroy()).pipe(res);
+      }
+      res.writeHead(200, headers);
+      if (req.method === 'HEAD') return res.end();
+      createReadStream(target).on('error', () => res.destroy()).pipe(res);
+    } catch (error) {
+      if (error.code === 'ERR_MODULE_NOT_FOUND') { res.writeHead(503, { 'x-multiplane-error': 'three_not_installed' }); return res.end('Optional three.js is not installed.'); }
+      res.writeHead(error.code === 'ENOENT' ? 404 : 400);
+      res.end('Cannot read the requested file.');
+    }
+  });
+  await new Promise((resolve, reject) => { server.once('error', reject); server.listen(port, '127.0.0.1', resolve); })
+    .catch(cause => { if (cause.code === 'EADDRINUSE') throw new MultiplaneError('port_in_use', undefined, { cause }); throw cause; });
+  return { url: `http://127.0.0.1:${server.address().port}`, root: base, port: server.address().port,
+    close: () => new Promise((resolve, reject) => { server.close(error => error ? reject(error) : resolve()); server.closeAllConnections(); }) };
+}

package/src/setup.mjs

@@ -0,0 +1,51 @@
+import { fileURLToPath } from 'node:url';
+import { Configuration } from './config.mjs';
+import { Skills } from './skills.mjs';
+import { createEvents, version } from './events.mjs';
+import { asError, invalidOption, MultiplaneError } from './errors.mjs';
+
+export async function setup(command, args, onEvent) {
+  const events = createEvents(command, null, { onEvent });
+  events.start();
+  try {
+    const positional = [], options = {};
+    for (let i = 0; i < args.length; i++) {
+      const token = args[i];
+      if (!token.startsWith('--')) { positional.push(token); continue; }
+      const key = token.slice(2);
+      if (!['json', ...(command === 'skill' ? ['host', 'force', 'expect'] : [])].includes(key) || key in options) throw invalidOption(token, 'Invalid or duplicate option.');
+      if (['json', 'force'].includes(key)) options[key] = true;
+      else { if (args[i + 1] === undefined || args[i + 1].startsWith('--')) throw invalidOption(token, 'Missing option value.'); options[key] = args[++i]; }
+    }
+    const [action, key, value] = positional;
+    let data;
+    if (command === 'config') {
+      if (!['get', 'set', 'unset'].includes(action) || (action === 'get' ? positional.length > 2 : positional.length !== (action === 'set' ? 3 : 2))) throw invalidOption('action', 'Use config get [key], set <key> <value>, or unset <key>.');
+      const config = new Configuration(undefined, process.env, warning => events.warning(warning));
+      data = action === 'get' ? await config.read(key) : await config.save(key, action === 'unset' ? null : value);
+      if (data.check && !data.check.usable) events.warning({ code: 'ffmpeg_unusable', message: 'The saved FFmpeg path is unusable.', details: { reason: data.check.reason } });
+    } else {
+      if (!['status', 'install', 'remove'].includes(action) || positional.length !== 1 || (action !== 'status' && !options.host) || !['all', 'claude', 'codex'].includes(options.host ?? 'all') || (action === 'status' && ('force' in options || 'expect' in options))) throw invalidOption('host', 'Use skill status, install, or remove with --host claude|codex|all.');
+      const skills = new Skills(fileURLToPath(new URL('../skills/multiplane/', import.meta.url)), version);
+      const hosts = await skills.list(!options.host || options.host === 'all' ? ['claude', 'codex'] : [options.host]);
+      if (action === 'status') data = { hosts };
+      else {
+        data = { hosts: [] }; let first;
+        for (const status of hosts) {
+          const item = { host: status.host, action, ok: true, code: null, message: null, target: status.target, version: action === 'install' ? version : null, backup: null };
+          try {
+            if (status.blocked) throw new MultiplaneError('skill_blocked', status.error);
+            // TODO(design): Document --expect null for the missing-copy signature.
+            const expected = options.expect === 'null' ? null : options.expect;
+            Object.assign(item, await skills.change(status.host, action, expected, undefined, !!options.force));
+          } catch (failure) { const error = asError(failure); first ??= error; Object.assign(item, { ok: false, code: error.code, message: error.message, version: status.version }); }
+          data.hosts.push(item);
+        }
+        if (first) { first.result = { data }; throw first; }
+      }
+    }
+    return events.finish(data);
+  } catch (failure) {
+    const error = asError(failure); error.result = events.finish(error.result?.data ?? {}, error); throw error;
+  } finally { events.dispose(); }
+}

package/src/skills.mjs

@@ -0,0 +1,128 @@
+import path from 'node:path';
+import os from 'node:os';
+import * as fs from 'node:fs/promises';
+import { createHash, randomUUID } from 'node:crypto';
+import { MultiplaneError } from './errors.mjs';
+export async function findCommand(name, env = process.env) {
+  const extensions = process.platform === 'win32' ? ['.exe', '.cmd', '.bat', ''] : [''];
+  const search = Object.entries(env).find(([k]) => k.toLowerCase() === 'path')?.[1] ?? '';
+  for (const dir of search.split(path.delimiter).filter(Boolean)) for (const ext of extensions) {
+    const file = path.resolve(dir.replace(/^"|"$/g, ''), name + ext);
+    try { if ((await fs.stat(file)).isFile()) { await fs.access(file, process.platform === 'win32' ? fs.constants.F_OK : fs.constants.X_OK); return file; } } catch {}
+  }
+  return null;
+}
+const marker = '.multiplane.json';
+const hash = bytes => createHash('sha256').update(bytes).digest('hex');
+async function exists(file) { try { await fs.lstat(file); return true; } catch (e) { if (e.code === 'ENOENT') return false; throw e; } }
+// Resolve existing ancestors without creating directories during inspection.
+async function realRoot(root) {
+  try {
+    const resolved = await fs.realpath(root);
+    if (!(await fs.stat(resolved)).isDirectory()) throw Object.assign(Error('Skill root is not a directory'), { code: 'ENOTDIR' });
+    return resolved;
+  }
+  catch (error) {
+    if (error.code !== 'ENOENT' || await exists(root)) throw error;
+    const parent = path.dirname(root);
+    if (parent === root) throw error;
+    return path.join(await realRoot(parent), path.basename(root));
+  }
+}
+const linkedSkill = () => Object.assign(Error('Skill directories cannot contain symbolic links'), { code: 'SKILL_LINK' });
+export async function treeHashes(root) {
+  const files = Object.create(null);
+  async function walk(dir, prefix = '') {
+    if ((await fs.lstat(dir)).isSymbolicLink()) throw linkedSkill();
+    for (const entry of (await fs.readdir(dir, { withFileTypes: true })).sort((a, b) => a.name < b.name ? -1 : 1)) {
+      const name = prefix + entry.name;
+      if (entry.isSymbolicLink()) throw linkedSkill();
+      if (entry.isDirectory()) { files[name + '/'] = null; await walk(path.join(dir, entry.name), name + '/'); }
+      else if (entry.isFile()) { if (name !== marker) files[name] = hash(await fs.readFile(path.join(dir, entry.name))); }
+      else throw Object.assign(Error('Unsupported skill file type'), { code: 'SKILL_LINK' });
+    }
+  }
+  await walk(root); return files;
+}
+export class Skills {
+  queue = Promise.resolve();
+  constructor(source, version, { user = process.env.MULTIPLANE_AGENT_HOME || os.homedir(), env = process.env } = {}) { this.source = source; this.version = version; this.user = user; this.env = env; }
+  target(host) {
+    if (!['claude', 'codex'].includes(host)) throw Error('Invalid agent');
+    return path.join(this.user, host === 'claude' ? '.claude' : '.agents', 'skills', 'multiplane');
+  }
+  async status(host) {
+    const target = path.join(await realRoot(path.dirname(this.target(host))), 'multiplane');
+    const detected = await exists(path.join(this.user, host === 'claude' ? '.claude' : '.codex')) || !!await findCommand(host, this.env);
+    const base = { host, target, detected, availableVersion: this.version, version: null, state: 'missing', signature: null, blocked: false, error: null };
+    if (!await exists(target)) return base;
+    let files;
+    try { files = await treeHashes(target); }
+    catch (error) { if (error.code === 'SKILL_LINK') return { ...base, state: 'modified', blocked: true, error: error.message }; throw error; }
+    const signature = hash(JSON.stringify(files));
+    let record;
+    try { record = JSON.parse(await fs.readFile(path.join(target, marker), 'utf8')); } catch {}
+    const current = await treeHashes(this.source);
+    const known = record?.v === 1 && record.host === host && record.skill === 'multiplane' && Array.isArray(record.releases)
+      ? record.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
+    const release = [{ version: this.version, files: current }, ...known].find(r => JSON.stringify(r.files) === JSON.stringify(files));
+    return { ...base, signature, version: release?.version ?? record?.version ?? null, state: release ? release.version === this.version ? 'latest' : 'update' : 'modified' };
+  }
+  list(hosts = ['claude', 'codex']) { return Promise.all(hosts.map(async host => {
+    try { return await this.status(host); }
+    catch (error) { return { host, target: this.target(host), detected: false, availableVersion: this.version, version: null, state: 'error', blocked: true, error: error.message }; }
+  })); }
+  async backupName(host, date = new Date()) {
+    const pad = n => String(n).padStart(2, '0');
+    const base = `multiplane.bak-${date.getFullYear()}${pad(date.getMonth() + 1)}${pad(date.getDate())}-${pad(date.getHours())}${pad(date.getMinutes())}${pad(date.getSeconds())}`;
+    const parent = await realRoot(path.dirname(this.target(host)));
+    let name = base;
+    for (let i = 2; await exists(path.join(parent, name)); i++) name = `${base}-${i}`;
+    return name;
+  }
+  change(host, action, expected, backupName, force = false) {
+    const operation = this.queue.then(async () => {
+      if (!['install', 'remove'].includes(action)) throw Error('Invalid skill action');
+      backupName ??= await this.backupName(host);
+      if (!/^multiplane\.bak-\d{8}-\d{6}(?:-[2-9]\d*|-1\d+)?$/.test(backupName)) throw Error('Invalid backup name');
+      const before = await this.status(host);
+      if (before.blocked) throw new MultiplaneError('skill_blocked', before.error);
+      if (expected !== undefined && before.signature !== expected) throw new MultiplaneError('skill_changed');
+      if (before.state === 'modified' && !force) throw new MultiplaneError('skill_modified', undefined, { hint: 'Use --force to back up the modified directory before continuing.' });
+      const parent = path.dirname(before.target);
+      await fs.mkdir(parent, { recursive: true });
+      if (await fs.realpath(parent) !== parent) throw Error('Skill path changed');
+      const token = randomUUID(), stage = path.join(parent, '.multiplane-new-' + token);
+      const old = path.join(parent, backupName);
+      if (await exists(old)) throw Error('Backup already exists');
+      let moved = false, installed = false;
+      const remove = async target => {
+        if (path.dirname(path.resolve(target)) !== path.resolve(parent) || path.resolve(target) === path.resolve(parent)) throw Error('Invalid removal target');
+        await fs.rm(target, { recursive: true, force: true });
+      };
+      try {
+        if (action === 'install') {
+          const files = await treeHashes(this.source);
+          await fs.cp(this.source, stage, { recursive: true });
+          let previous;
+          try { previous = JSON.parse(await fs.readFile(path.join(before.target, marker), 'utf8')); } catch {}
+          const releases = previous?.v === 1 && previous.host === host && Array.isArray(previous.releases)
+            ? previous.releases.filter(r => r && typeof r.version === 'string' && r.files && typeof r.files === 'object' && !Array.isArray(r.files)) : [];
+          await fs.writeFile(path.join(stage, marker), JSON.stringify({ v: 1, host, skill: 'multiplane', version: this.version, installedAt: Date.now(), files, releases: [...releases.filter(r => r.version !== this.version), { version: this.version, files }] }, null, 2));
+          if (JSON.stringify(await treeHashes(stage)) !== JSON.stringify(files)) throw Error('Skill source changed during copy');
+        }
+        const latest = await this.status(host);
+        if (latest.blocked || latest.target !== before.target || latest.signature !== before.signature || await fs.realpath(parent) !== parent) throw new MultiplaneError('skill_changed');
+        if (before.state !== 'missing') { await fs.rename(before.target, old); moved = true; }
+        if (action === 'install') { await fs.rename(stage, before.target); installed = true; }
+      } catch (error) {
+        if (installed) await remove(before.target);
+        if (moved) await fs.rename(old, before.target);
+        throw error;
+      } finally { await remove(stage); }
+      if (moved && before.state !== 'modified') await remove(old);
+      return { backup: moved && before.state === 'modified' ? old : null };
+    });
+    this.queue = operation.catch(() => {}); return operation;
+  }
+}