multiplane 0.3.6 → 0.3.7

package/src/post.mjs

@@ -54,7 +54,7 @@ export function resolvePost(options = {}, post = {}) {
   if (options['no-post']) return { motionBlur: 1, maxMotionBlur: 1, shutter: 0.5, grain: 0 };
   let motionBlur = number(options['motion-blur'] ?? post.motionBlur ?? 1, 'motionBlur', { positive: true });
   if (!Number.isSafeInteger(motionBlur)) throw invalidOption('motionBlur', 'motionBlur must be a positive integer.');
-  const maxMotionBlur = number(quality === 'draft' ? 1 : options['max-motion-blur'] ?? post.maxMotionBlur ?? (quality === 'high' ? 256 : quality === 'fast' ? 16 : 32), 'maxMotionBlur', { positive: true });
+  const maxMotionBlur = number(quality === 'draft' ? 1 : options['max-motion-blur'] ?? post.maxMotionBlur ?? (quality === 'high' ? 256 : quality === 'fast' ? 16 : 32), 'maxMotionBlur', { positive: true });
   if (!Number.isSafeInteger(maxMotionBlur)) throw invalidOption('maxMotionBlur', 'maxMotionBlur must be a positive integer.');
   // Preserve explicit bases and fixed sampling before applying the preset cap.
   if ((quality === 'standard' || quality === 'fast') && options['motion-blur'] == null && maxMotionBlur > motionBlur) motionBlur = Math.min(motionBlur, 4);
@@ -276,19 +276,20 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       }
       const verifyReuse = candidate && (audit || previousRaw.run === 0 || frame % REUSE_INTERVAL === 0);
       const cache = new Map();
-      let contextUsed = false, motionProbeUsed = false;
-      let finalCapture = hooked || motionBlur === 1;
-      let selectedTimes = times;
-      let dofMotionSamples = new Set(times).size;
-      const context = observed => ({ motionBlur, motionBlurBase, observed,
-        motionProbeTime: finalCapture ? undefined : t,
-        dofMotionSamples: finalCapture ? dofMotionSamples : undefined });
+      let contextUsed = false, motionProbeUsed = false;
+      let finalCapture = hooked || motionBlur === 1;
+      let selectedTimes = times;
+      let dofMotionSamples = new Set(times).size;
+      const context = (observed, time) => ({ motionBlur, motionBlurBase, observed,
+        motionProbeTime: finalCapture ? undefined : t,
+        dofMotionSamples: finalCapture ? dofMotionSamples : undefined,
+        dofMotionIndex: finalCapture ? [...new Set(selectedTimes)].sort((a, b) => a - b).indexOf(time) : undefined });
       const sample = async (time, reuse = false) => {
         if (!cache.has(time)) {
           const start = performance.now();
-          const observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
+          const observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
           observedTime = undefined;
-          const png = await capture.frame(time, context(observed));
+          const png = await capture.frame(time, context(observed, time));
           contextUsed ||= capture.sampleContextUsed === true;
           motionProbeUsed ||= capture.motionProbeUsed === true;
           stats.captureMs += performance.now() - start;
@@ -305,9 +306,9 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
           return;
         }
         const begin = async time => {
-          const start = performance.now(), observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
+          const start = performance.now(), observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
           observedTime = undefined;
-          const pending = await capture.beginFrame(time, context(observed));
+          const pending = await capture.beginFrame(time, context(observed, time));
           contextUsed ||= capture.sampleContextUsed === true;
           motionProbeUsed ||= capture.motionProbeUsed === true;
           const png = pending.png.then(buffer => { stats.captureMs += performance.now() - start; return buffer; });
@@ -315,9 +316,9 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
           return { png, dofSamples: capture.dofSamples ?? 0, probe: capture.motionProbeUsed === true && !finalCapture };
         };
         let pending = await begin(missing[0]);
-        for (let i = 0; i < missing.length; i++) {
-          const png = await pending.png;
-          const { dofSamples, probe } = pending;
+        for (let i = 0; i < missing.length; i++) {
+          const png = await pending.png;
+          const { dofSamples, probe } = pending;
           const next = i + 1 < missing.length ? await begin(missing[i + 1]) : null;
           stats.samples++;
           cache.set(missing[i], { png, dofSamples, probe, image: await decode(png, reuse) });
@@ -356,15 +357,15 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
             }
             let difference = 0;
             for (let i = 1; i < images.length && difference <= threshold; i++) {
-              // All decision images share the output frame's fixed lens phase.
-              difference = Math.max(difference, localMotionDifference(images[i - 1], images[i], alpha, threshold));
+              // All decision images share the output frame's fixed lens phase.
+              difference = Math.max(difference, localMotionDifference(images[i - 1], images[i], alpha, threshold));
             }
-            if (difference <= threshold || motionBlur >= post.maxMotionBlur) {
-              usedSamples = motionBlur; selectedTimes = grid;
+            if (difference <= threshold || motionBlur >= post.maxMotionBlur) {
+              usedSamples = motionBlur; selectedTimes = grid;
               result = timed('averageMs', () => average(images)); break;
             }
             motionBlur = Math.min(post.maxMotionBlur, motionBlur * 2);
-            if (legacy) cache.clear();
+            if (legacy) cache.clear();
             observedTime = undefined;
             grid = legacy ? sampleTimes(t, fps, capture.duration, capture.cuts, { ...post, motionBlur }) : grids.get(motionBlur);
           }
@@ -395,22 +396,22 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
           result = timed('averageMs', () => average(images));
         }
       }
-      let usedDofSamples = previousRaw?.usedDofSamples ?? 0;
-      if (!(candidate && !verifyReuse)) {
-        // Only lens-dependent probe captures need replacing. DOM captures and
-        // final hook captures remain reusable at the same time and context.
-        if (motionProbeUsed && !finalCapture) {
-          finalCapture = true;
-          dofMotionSamples = new Set(selectedTimes).size;
-          for (const [time, item] of cache) if (item.probe) cache.delete(time);
-          observedTime = undefined;
-          await sampleMany(selectedTimes, true);
-          const images = selectedTimes.map(time => cache.get(time).image);
-          png = selectedTimes.length === 1 ? cache.get(selectedTimes[0]).png : undefined;
-          result = selectedTimes.length === 1 ? images[0] : timed('averageMs', () => average(images));
-        }
-        usedDofSamples = [...new Set(selectedTimes)].reduce((sum, time) => sum + (cache.get(time)?.dofSamples ?? 0), 0);
-      }
+      let usedDofSamples = previousRaw?.usedDofSamples ?? 0;
+      if (!(candidate && !verifyReuse)) {
+        // Only lens-dependent probe captures need replacing. DOM captures and
+        // final hook captures remain reusable at the same time and context.
+        if (motionProbeUsed && !finalCapture) {
+          finalCapture = true;
+          dofMotionSamples = new Set(selectedTimes).size;
+          for (const [time, item] of cache) if (item.probe) cache.delete(time);
+          observedTime = undefined;
+          await sampleMany(selectedTimes, true);
+          const images = selectedTimes.map(time => cache.get(time).image);
+          png = selectedTimes.length === 1 ? cache.get(selectedTimes[0]).png : undefined;
+          result = selectedTimes.length === 1 ? images[0] : timed('averageMs', () => average(images));
+        }
+        usedDofSamples = [...new Set(selectedTimes)].reduce((sum, time) => sum + (cache.get(time)?.dofSamples ?? 0), 0);
+      }
       if (verifyReuse) {
         stats.auditMs += performance.now() - auditStart;
         Atomics.add(state, 2, 1);
@@ -428,7 +429,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       if (enabled && options.transport === 'raw') result ??= await decode(png);
       previousRaw = { t, frame, motionBlur, uniform, png, image: result, usedSamples, usedDofSamples, run: candidate ? previousRaw.run + 1 : 0 };
       // Contributing temporal samples, excluding probes and failed attempts.
-      api.lastBlurSamples = usedSamples;
+      api.lastBlurSamples = usedSamples;
       api.lastDofSamples = usedDofSamples;
       stats.frames++;
       if (sizes.renderScale !== sizes.scale) {

package/src/preview.mjs

@@ -1,23 +1,23 @@
-import path from 'node:path';
-import { writeFile, rename, rm } from 'node:fs/promises';
-import sharp from 'sharp';
-
-export function createPreview(events, width, height, { enabled = true, now = () => performance.now() } = {}) {
-  let last = -Infinity, failed = false;
-  return async (pixels, frame) => {
-    if (!enabled || failed || now() - last < 2000) return;
-    const file = path.join(events.directory, 'preview.png'), temporary = file + '.tmp';
-    try {
-      const png = await sharp(pixels, { raw: { width, height, channels: 4 } })
-        .resize({ width: 480, height: 480, fit: 'inside', withoutEnlargement: true }).png().toBuffer();
-      await writeFile(temporary, png);
-      await rename(temporary, file);
-      events.preview(frame);
-      last = now();
-    } catch {
-      failed = true;
-      await rm(temporary, { force: true }).catch(() => {});
-      events.warning({ code: 'preview_failed', message: 'Preview could not be written; further preview updates are disabled.' });
-    }
-  };
-}
+import path from 'node:path';
+import { writeFile, rename, rm } from 'node:fs/promises';
+import sharp from 'sharp';
+
+export function createPreview(events, width, height, { enabled = true, now = () => performance.now() } = {}) {
+  let last = -Infinity, failed = false;
+  return async (pixels, frame) => {
+    if (!enabled || failed || now() - last < 2000) return;
+    const file = path.join(events.directory, 'preview.png'), temporary = file + '.tmp';
+    try {
+      const png = await sharp(pixels, { raw: { width, height, channels: 4 } })
+        .resize({ width: 480, height: 480, fit: 'inside', withoutEnlargement: true }).png().toBuffer();
+      await writeFile(temporary, png);
+      await rename(temporary, file);
+      events.preview(frame);
+      last = now();
+    } catch {
+      failed = true;
+      await rm(temporary, { force: true }).catch(() => {});
+      events.warning({ code: 'preview_failed', message: 'Preview could not be written; further preview updates are disabled.' });
+    }
+  };
+}

package/src/process.mjs

@@ -1,9 +1,9 @@
-// FFmpeg has no descendants; wait for its streams to close before cleaning files.
-export function stopChild(child, graceMs = 2000) {
-  return new Promise(resolve => {
-    if (child.exitCode !== null || child.signalCode !== null) { resolve(); return; }
-    const timer = setTimeout(() => child.kill('SIGKILL'), graceMs);
-    child.once('close', () => { clearTimeout(timer); resolve(); });
-    child.kill('SIGTERM');
-  });
-}
+// FFmpeg has no descendants; wait for its streams to close before cleaning files.
+export function stopChild(child, graceMs = 2000) {
+  return new Promise(resolve => {
+    if (child.exitCode !== null || child.signalCode !== null) { resolve(); return; }
+    const timer = setTimeout(() => child.kill('SIGKILL'), graceMs);
+    child.once('close', () => { clearTimeout(timer); resolve(); });
+    child.kill('SIGTERM');
+  });
+}

package/src/render-pool.mjs

@@ -51,7 +51,7 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
   }
   const api = {
     stats,
-    get blurSamples() { return blurSampleReport(histogram); },
+    get blurSamples() { return blurSampleReport(histogram); },
     get dofSamples() { return blurSampleReport(dofHistogram); },
     get staticReuse() { return reuseReport(options); },
     progress: () => `Samples: ${stats.samples}; static: ${stats.staticFrames}; adaptive: ${stats.adaptiveFrames ?? 0}; hooks: ${stats.hookFrames ?? 0}`,
@@ -78,7 +78,7 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         if (options.transport === 'raw') schedule(slot);
         // Worker audits have already replaced invalid frames in this batch.
         for (const [i, png] of batch.frames.entries()) {
-          const count = batch.blurSamples[i], dofCount = batch.dofSamples[i];
+          const count = batch.blurSamples[i], dofCount = batch.dofSamples[i];
           dofHistogram[dofCount] = (dofHistogram[dofCount] ?? 0) + 1;
           histogram[count] = (histogram[count] ?? 0) + 1;
           yield { frame: batch.first + i, png, hash: batch.hashes?.[i], blurSamples: count, dofSamples: dofCount };

package/src/render-worker.mjs

@@ -41,7 +41,7 @@ try {
         const png = result.byteOffset === 0 && result.byteLength === result.buffer.byteLength && !isMarkedAsUntransferable(result.buffer)
           ? new Uint8Array(result.buffer) : Uint8Array.from(result);
         frames.push(png);
-        blurSamples.push(item.blurSamples);
+        blurSamples.push(item.blurSamples);
         dofSamples.push(item.dofSamples);
         if (workerData.options.verify) hashes.push(item.hash);
       }

package/src/resource-path.mjs

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

@@ -1,27 +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(); },
-  };
-}
+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

@@ -1,37 +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 };
-})();
+(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

@@ -1,9 +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; }
+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/server.mjs

@@ -61,13 +61,13 @@ export async function startServer(port = 0, root = process.cwd()) {
       }
       let target = path.resolve(resourceRoot, `.${resourcePath}`);
       if (!await isInsideResourceRoot(resourceRoot, target)) { res.writeHead(403); return res.end(); }
-      let targetInfo;
-      try { targetInfo = await stat(target); }
-      catch (error) {
-        if (pathname === '/favicon.ico' && error.code === 'ENOENT') { res.writeHead(204); return res.end(); }
-        throw error;
-      }
-      if (targetInfo.isDirectory()) target = path.join(target, 'index.html');
+      let targetInfo;
+      try { targetInfo = await stat(target); }
+      catch (error) {
+        if (pathname === '/favicon.ico' && error.code === 'ENOENT') { res.writeHead(204); return res.end(); }
+        throw error;
+      }
+      if (targetInfo.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);

package/src/setup.mjs

@@ -1,51 +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(); }
-}
+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(); }
+}