multiplane 0.3.3 → 0.3.7

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(); }
+}

package/src/skills.mjs

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

package/src/stills.mjs

@@ -44,17 +44,18 @@ export async function stillsShot(shot, options = {}) {
       await mkdir(out, { recursive: true });
       for (const file of [...times.map(t => `t-${t.toFixed(2)}.png`), '_sheet.png']) await requireNewOutput(path.join(out, file));
       const frames = [];
-      const histogram = {};
+      const histogram = {}, dofHistogram = {};
       const source = async function* (first, end) {
         for (let index = first; index < end; index++) {
           const t = times[index];
           events.check();
           const png = await processed.frame(t, Math.round(t * fps), index === end - 1);
           events.progress('capture', index + 1, times.length);
-          yield { t, png, blurSamples: processed.lastBlurSamples };
+          yield { t, png, blurSamples: processed.lastBlurSamples, dofSamples: processed.lastDofSamples };
         }
       };
-      for await (const { t, png: buffer, blurSamples } of verifiedFrames(source, { ...options, check: events.check }, times.length)) {
+      for await (const { t, png: buffer, blurSamples, dofSamples } of verifiedFrames(source, { ...options, check: events.check }, times.length)) {
+        dofHistogram[dofSamples] = (dofHistogram[dofSamples] ?? 0) + 1;
         histogram[blurSamples] = (histogram[blurSamples] ?? 0) + 1;
         events.check();
         await writeArtifact(path.join(out, `t-${t.toFixed(2)}.png`), buffer);
@@ -73,7 +74,7 @@ export async function stillsShot(shot, options = {}) {
       await writeArtifact(path.join(out, '_sheet.png'), sheetPNG);
       await checkStill(path.join(out, '_sheet.png'), { width: 1920, height: Math.ceil(Math.ceil(frames.length / 4) * rowHeight) });
       events.artifact(path.join(out, '_sheet.png'), 'contact-sheet');
-      result = { staticReuse: processed.staticReuse, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, blurSamples: blurSampleReport(histogram), format: 'png', alpha: capture.alpha, stills: times.map(t => ({ t, frame: Math.round(t * fps), path: path.join(out, `t-${t.toFixed(2)}.png`) })), contactSheet: path.join(out, '_sheet.png') };
+      result = { staticReuse: processed.staticReuse, post: { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) }, blurSamples: blurSampleReport(histogram), dofSamples: blurSampleReport(dofHistogram), format: 'png', alpha: capture.alpha, stills: times.map(t => ({ t, frame: Math.round(t * fps), path: path.join(out, `t-${t.toFixed(2)}.png`) })), contactSheet: path.join(out, '_sheet.png') };
     } finally { await cleanup(); }
 
     return options.draft ? { ...result, draft: true } : result;

package/src/three/index.js

@@ -79,7 +79,6 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
   previewAperture = 0.008, maxBlur = 0.016, toneMapping = false, zIndex = 1, style = {} } = {}) {
   // TODO(design): Document the shared layer/card style fields and single-family font values.
   const layerStyle = { ...defaultStyle, ...style };
-  const layerBackground = style.textureBackground !== undefined;
   const renderer = new THREE.WebGLRenderer({ alpha: true, premultipliedAlpha: false, antialias: true, preserveDrawingBuffer: true });
   renderer.setPixelRatio(pixelRatio);
   renderer.setSize(size.w, size.h);
@@ -177,7 +176,7 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
     }
     return patterns.get(count);
   }
-  function renderAccumulation(focus, radius, count, blur, rotation) {
+  function renderAccumulation(focus, radius, count, blur, rotation, budget = count, stride = 1, offset = 0) {
     const position = camera.position.clone(), projection = camera.projectionMatrix.clone();
     const projectionInverse = camera.projectionMatrixInverse.clone();
     const autoClear = renderer.autoClear, oldTarget = renderer.getRenderTarget();
@@ -195,8 +194,10 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
       sumMaterial.uniforms.focus.value = focus;
       sumMaterial.uniforms.cameraNear.value = camera.near;
       sumMaterial.uniforms.cameraFar.value = camera.far;
-      sumMaterial.uniforms.blurScale.value = radius * height * projection.elements[5] * 0.5 * blur / Math.sqrt(count);
-      for (const [x, y, jx, jy] of pattern(count)) {
+      sumMaterial.uniforms.blurScale.value = radius * height * projection.elements[5] * 0.5 * blur / Math.sqrt(budget);
+      const points = pattern(count * stride);
+      for (let i = offset; i < points.length; i += stride) {
+        const [x, y, jx, jy] = points[i];
         const dx = (x * Math.cos(rotation) - y * Math.sin(rotation)) * radius;
         const dy = (x * Math.sin(rotation) + y * Math.cos(rotation)) * radius;
         camera.position.copy(position).addScaledVector(right, dx).addScaledVector(up, dy);
@@ -226,19 +227,34 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
     textures.add(texture);
     return texture;
   }
+  /**
+   * @param {object} options
+   * @param {number} [options.lodBias=0] Texture mip LOD bias; negative values sharpen
+   * front-facing cards but can cause moire on dense textures at oblique angles.
+   */
   function card({ src, width, height, radius = 0, position = [0, 0, 0], rotation = [0, 0, 0],
-    border = null, shadow = false, annotations = [], browserFrame = false, textureWidth = 2048, style = {} }) {
+    border = null, shadow = false, annotations = [], browserFrame = false, textureWidth = 2048, style = {}, lodBias = 0 }) {
+    if (!Number.isFinite(lodBias)) throw Object.assign(new Error('lodBias must be a finite number.'), { code: 'shot_contract_invalid' });
     const textureStyle = { ...layerStyle, ...style };
-    const composeBackground = layerBackground || style.textureBackground !== undefined;
+    const composeBackground = annotations.length > 0 || browserFrame || style.textureBackground !== undefined;
     const group = new THREE.Group();
     group.position.fromArray(position); group.rotation.set(...rotation);
-    const material = new THREE.MeshBasicMaterial({ color: 0xffffff, side: THREE.DoubleSide });
+    const material = new THREE.MeshBasicMaterial({ color: 0xffffff, side: THREE.DoubleSide, transparent: !composeBackground });
+    if (lodBias !== 0) {
+      material.onBeforeCompile = shader => {
+        shader.uniforms.cardLodBias = { value: lodBias };
+        shader.fragmentShader = 'uniform float cardLodBias;\n' + shader.fragmentShader.replace('#include <map_fragment>',
+          THREE.ShaderChunk.map_fragment.replace('texture2D( map, vMapUv )', 'texture2D( map, vMapUv, cardLodBias )'));
+      };
+      material.customProgramCacheKey = () => 'card-lod-bias';
+    }
     const mesh = new THREE.Mesh(roundedGeometry(width, height, radius), material);
     group.add(mesh);
     if (border) {
       const edge = new THREE.Mesh(roundedGeometry(width + 2 * border.width, height + 2 * border.width, radius + border.width),
-        new THREE.MeshBasicMaterial({ color: border.color, side: THREE.DoubleSide }));
-      edge.position.z = -0.002; group.add(edge);
+        new THREE.MeshBasicMaterial({ color: border.color, side: THREE.DoubleSide,
+          polygonOffset: true, polygonOffsetFactor: 1, polygonOffsetUnits: 1 }));
+      group.add(edge);
     }
     if (shadow) {
       const c = document.createElement('canvas'); c.width = c.height = 512;
@@ -288,7 +304,8 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
       adaptiveSamples: adaptive = sampling.adaptiveSamples, maxSamples: maximum = sampling.maxSamples,
       sampleSpacing: spacing = sampling.sampleSpacing, sampleBlur: blur = sampling.sampleBlur,
       rotateSamples: rotate = sampling.rotateSamples,
-      t = window.SHOT?.sampleContext?.time ?? 0, motionBlur = window.SHOT?.sampleContext?.motionBlur ?? 1,
+      t = window.SHOT?.sampleContext?.time ?? 0,
+      motionBlur = window.SHOT?.sampleContext?.motionBlurBase ?? window.SHOT?.sampleContext?.motionBlur ?? 1,
       previewAperture: previewRadius = previewAperture, maxBlur: previewMax = maxBlur } = {}) {
       if (!Number.isFinite(focus) || focus <= 0 || !Number.isFinite(radius) || radius < 0
         || !Number.isInteger(count) || count < 1 || !['preview', 'final'].includes(mode)
@@ -319,11 +336,24 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
             maxRadius = Math.max(maxRadius, radius * height * camera.projectionMatrix.elements[5] * 0.5 * Math.abs(1 / z - 1 / focus));
           }
         });
-        const actual = adaptive ? Math.min(maximum, Math.max(count, Math.ceil((2 * maxRadius / spacing) ** 2))) : count;
-        const phase = t * 997 * Math.sqrt(2);
-        const rotation = rotate && motionBlur > 1 ? (phase - Math.floor(phase)) * Math.PI * 2 : 0;
+        const budget = adaptive ? Math.min(maximum, Math.max(count, Math.ceil((2 * maxRadius / spacing) ** 2))) : count;
+        const probe = globalThis.__multiplaneMotionProbe;
+        // Probes retain the stable base pattern; final captures share one frame budget.
+        const divisor = probe?.motionSamples ?? motionBlur;
+        const minimum = probe?.time === undefined ? 2 : 8;
+        const actual = rotate && motionBlur > 1 ? Math.min(budget, Math.max(minimum, Math.ceil(budget / divisor))) : budget;
+        if (probe) probe.samples += actual;
+        if (probe && rotate && motionBlur > 1) probe.used = true;
+        const phase = (probe?.time ?? t) * 997 * Math.sqrt(2);
+        // Final temporal samples partition one lens pattern, including its jitter.
+        // Fixed-phase probes and direct layer calls retain their existing pattern.
+        const interleaved = rotate && motionBlur > 1 && probe?.time === undefined
+          && Number.isInteger(probe?.motionIndex) && probe.motionIndex >= 0;
+        const stride = interleaved ? divisor : 1;
+        const rotation = !interleaved && rotate && motionBlur > 1 ? (phase - Math.floor(phase)) * Math.PI * 2 : 0;
         Object.assign(stats, { samples: actual, maxBlurRadius: maxRadius, rotation });
-        renderAccumulation(focus, radius, actual, blur, rotation);
+        renderAccumulation(focus, radius, actual, blur, rotation, interleaved ? actual * stride : budget,
+          stride, interleaved ? probe.motionIndex : 0);
       }
     },
     gpuInfo() {

package/src/verify.mjs

@@ -43,15 +43,17 @@ export async function verifyShot(shot, options = {}) {
       const references = new Map(), hashes = [], rangeReferences = new Map();
       if (compareReuse) referenceDirectory = await mkdtemp(path.join(tmpdir(), 'multiplane-verify-static-'));
       await mkdir(out, { recursive: true });
-      const histogram = {};
+      const histogram = {}, dofHistogram = {};
       const jitterChecks = new Set();
       let errors = 0, totalChangedPixels = 0;
       for (const t of times) {
         events.check(); references.set(t, decodePNG(await processed.frame(t)));
+        dofHistogram[processed.lastDofSamples] = (dofHistogram[processed.lastDofSamples] ?? 0) + 1;
         histogram[processed.lastBlurSamples] = (histogram[processed.lastBlurSamples] ?? 0) + 1;
       }
       data.post = { ...processed.post, adaptiveBlur: Number(options['adaptive-blur'] ?? 0.5) };
       data.blurSamples = blurSampleReport(histogram);
+      data.dofSamples = blurSampleReport(dofHistogram);
       const check = async (t, actual, name, reference = references.get(t)) => {
         events.check();
         if (reference.file) reference = { ...reference, data: await readFile(reference.file) };

package/src/video-pipe.mjs

@@ -1,6 +1,6 @@
-export async function writeFrame(stream, bytes) {
-  const chunkSize = 1024 * 1024;
-  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
-    await new Promise((resolve, reject) => stream.write(bytes.subarray(offset, offset + chunkSize), error => error ? reject(error) : resolve()));
-  }
-}
+export async function writeFrame(stream, bytes) {
+  const chunkSize = 1024 * 1024;
+  for (let offset = 0; offset < bytes.length; offset += chunkSize) {
+    await new Promise((resolve, reject) => stream.write(bytes.subarray(offset, offset + chunkSize), error => error ? reject(error) : resolve()));
+  }
+}

package/src/workers.mjs

@@ -41,7 +41,11 @@ export function selectWorkers({ workers, source, record, machine, type, scale =
   if (validBenchmark(record, machine) && shotTypes.includes(type)) {
     return { workers: Math.max(1, Math.min(record.shots[type].workers, memoryWorkers(memoryScale, hardware))), source: 'benchmark' };
   }
-  return { workers: defaultWorkers(scale, hardware), source: 'estimate' };
+  const estimate = defaultWorkers(scale, hardware);
+  // Unbenchmarked WebGL contexts share one GPU and retain large render targets.
+  const free = Math.min(hardware.free ?? freemem(), hardware.total ?? totalmem());
+  const threeLimit = Math.max(1, Math.floor((free - 2 * 1024 ** 3) / ((0.5 + 0.5 * memoryScale ** 2) * 1024 ** 3)));
+  return { workers: type === 'three' ? Math.min(4, estimate, threeLimit) : estimate, source: 'estimate' };
 }
 
 // Inspect the loaded probe only; its context is discarded before real rendering.

package/tools/bench/shots/canvas-2d.html

@@ -1 +1 @@
-<!doctype html><html><head><meta charset="utf-8"><link rel="icon" href="data:,"><title>canvas-2d</title><style>@font-face{font-family:Bench;src:url('../../../examples/assets/Roboto-Variable.ttf')}html,body{margin:0}#stage{width:1920px;height:1080px;position:relative;overflow:hidden;background:#18202c}canvas{position:absolute;inset:0;width:1920px;height:1080px}.tile{position:absolute;color:#fff;background:#375575;font:16px Bench;padding:4px;box-shadow:2px 3px 5px #0008}</style></head><body><div id="stage" data-kind="canvas-2d"></div><script src="scene.js"></script></body></html>
+<!doctype html><html><head><meta charset="utf-8"><link rel="icon" href="data:,"><title>canvas-2d</title><style>@font-face{font-family:Bench;src:url('../../../examples/assets/Roboto-Variable.ttf')}html,body{margin:0}#stage{width:1920px;height:1080px;position:relative;overflow:hidden;background:#18202c}canvas{position:absolute;inset:0;width:1920px;height:1080px}.tile{position:absolute;color:#fff;background:#375575;font:16px Bench;padding:4px;box-shadow:2px 3px 5px #0008}</style></head><body><div id="stage" data-kind="canvas-2d"></div><script src="scene.js"></script></body></html>

package/tools/bench/shots/dom-light.html

@@ -1 +1 @@
-<!doctype html><html><head><meta charset="utf-8"><link rel="icon" href="data:,"><title>dom-light</title><style>@font-face{font-family:Bench;src:url('../../../examples/assets/Roboto-Variable.ttf')}html,body{margin:0}#stage{width:1920px;height:1080px;position:relative;overflow:hidden;background:#18202c}canvas{position:absolute;inset:0;width:1920px;height:1080px}.tile{position:absolute;color:#fff;background:#375575;font:16px Bench;padding:4px;box-shadow:2px 3px 5px #0008}</style></head><body><div id="stage" data-kind="dom-light"></div><script src="scene.js"></script></body></html>
+<!doctype html><html><head><meta charset="utf-8"><link rel="icon" href="data:,"><title>dom-light</title><style>@font-face{font-family:Bench;src:url('../../../examples/assets/Roboto-Variable.ttf')}html,body{margin:0}#stage{width:1920px;height:1080px;position:relative;overflow:hidden;background:#18202c}canvas{position:absolute;inset:0;width:1920px;height:1080px}.tile{position:absolute;color:#fff;background:#375575;font:16px Bench;padding:4px;box-shadow:2px 3px 5px #0008}</style></head><body><div id="stage" data-kind="dom-light"></div><script src="scene.js"></script></body></html>