multiplane 0.3.3 → 0.3.6

package/src/hosted.mjs

@@ -28,7 +28,7 @@ export async function hostedAvailable(command, options, env = process.env) {
 }
 
 export function hostedEnvironment(env) {
-  const allowed = /^(PATH|MULTIPLANE_.*|HTTPS?_PROXY|ALL_PROXY|NO_PROXY|TEMP|TMP|TMPDIR|HOME|USERPROFILE|APPDATA|LOCALAPPDATA|SystemRoot|ComSpec|PATHEXT|LANG|LC_.*)$/i;
+  const allowed = /^(PATH|MULTIPLANE_.*|ELECTRON_RUN_AS_NODE|HTTPS?_PROXY|ALL_PROXY|NO_PROXY|TEMP|TMP|TMPDIR|HOME|USERPROFILE|APPDATA|LOCALAPPDATA|SystemRoot|ComSpec|PATHEXT|LANG|LC_.*)$/i;
   const secret = /TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|BEARER|COOKIE|SESSION|API_?KEY|PRIVATE_?KEY|ACCESS_?KEY/i;
   return Object.fromEntries(Object.entries(env).filter(([key, value]) => {
     if (value === undefined || !allowed.test(key) || secret.test(key)) return false;

package/src/post.mjs

@@ -45,17 +45,19 @@ export async function resizeImage(image, width, height, upscale) {
 }
 export function resolveQuality(options = {}) {
   const quality = options.quality ?? (options.draft ? 'draft' : 'standard');
-  if (!['draft', 'standard', 'high'].includes(quality) || (options.draft && quality !== 'draft')) throw invalidOption('--quality', 'Quality must be draft, standard or high, and agree with --draft.');
+  if (!['draft', 'fast', 'standard', 'high'].includes(quality) || (options.draft && quality !== 'draft')) throw invalidOption('--quality', 'Quality must be draft, fast, standard or high, and agree with --draft.');
   return quality;
 }
 
 export function resolvePost(options = {}, post = {}) {
   const quality = resolveQuality(options);
   if (options['no-post']) return { motionBlur: 1, maxMotionBlur: 1, shutter: 0.5, grain: 0 };
-  const motionBlur = number(options['motion-blur'] ?? post.motionBlur ?? 1, 'motionBlur', { positive: true });
+  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 : 64), '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);
   // TODO(design): Document max <= base as disabling upward adaptation, including draft overrides.
   return { motionBlur, maxMotionBlur, shutter: number(options.shutter ?? post.shutter ?? 0.5, 'shutter'), grain: number(options.grain ?? post.grain ?? 0, 'grain') };
 }
@@ -254,13 +256,15 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       const grids = upward ? nestedSampleGrids(t, fps, capture.duration, capture.cuts, post) : null;
       const endpoints = sampleTimes(t, fps, capture.duration, capture.cuts, { motionBlur: 2, shutter: post.shutter * 2 });
       const times = sampleTimes(t, fps, capture.duration, capture.cuts, { ...post, motionBlur: upward ? Math.max(2, motionBlur) : motionBlur });
+      // Clipped or zero-width shutters may contain fewer unique temporal samples.
+      const motionBlurBase = new Set(upward ? grids.get(motionBlur) : times).size;
       let candidate = false, uniform = motionBlur === 1, observedTime;
       if (enabled && !Atomics.load(state, 0)) {
         const probes = [...new Set(motionBlur === 1 && !upward ? [t] : [...endpoints, ...times, t])].sort((a, b) => a - b);
         const changes = [];
         const observeStart = performance.now();
         for (const time of probes) {
-          changes.push(await capture.observe(time, { motionBlur }));
+          changes.push(await capture.observe(time, { motionBlur, motionBlurBase }));
           observedTime = time;
           if (changes.at(-1)) break;
         }
@@ -272,17 +276,24 @@ 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;
+      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 });
       const sample = async (time, reuse = false) => {
         if (!cache.has(time)) {
           const start = performance.now();
-          const observed = time === observedTime;
+          const observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
           observedTime = undefined;
-          const png = await capture.frame(time, { motionBlur, observed });
+          const png = await capture.frame(time, context(observed));
           contextUsed ||= capture.sampleContextUsed === true;
+          motionProbeUsed ||= capture.motionProbeUsed === true;
           stats.captureMs += performance.now() - start;
           stats.samples++;
-          cache.set(time, { png, image: post.motionBlur > 1 || upward || post.grain > 0 ? await decode(png, reuse) : null });
+          cache.set(time, { png, dofSamples: capture.dofSamples ?? 0, probe: capture.motionProbeUsed === true && !finalCapture, image: post.motionBlur > 1 || upward || post.grain > 0 ? await decode(png, reuse) : null });
         }
         return cache.get(time);
       };
@@ -294,20 +305,22 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
           return;
         }
         const begin = async time => {
-          const start = performance.now(), observed = time === observedTime;
+          const start = performance.now(), observed = time === observedTime && !(motionBlur > 1 && capture.motionProbeUsed);
           observedTime = undefined;
-          const pending = await capture.beginFrame(time, { motionBlur, observed });
+          const pending = await capture.beginFrame(time, context(observed));
           contextUsed ||= capture.sampleContextUsed === true;
+          motionProbeUsed ||= capture.motionProbeUsed === true;
           const png = pending.png.then(buffer => { stats.captureMs += performance.now() - start; return buffer; });
           png.catch(() => {});
-          return { png };
+          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;
+        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, image: await decode(png, reuse) });
+          cache.set(missing[i], { png, dofSamples, probe, image: await decode(png, reuse) });
           pending = next;
         }
       };
@@ -315,7 +328,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       let png, result, usedSamples = motionBlur;
       if (candidate && !verifyReuse) { ({ png, image: result, usedSamples } = previousRaw); }
       else if (upward) {
-        // Calibrated in capture raster pixels: about 2px for standard, 1px for high.
+        // Calibrated in capture raster pixels: about 2px for fast/standard, 1px for high.
         const threshold = resolveQuality(options) === 'high' ? 1 : 2;
         await sampleMany([...endpoints, t], true);
         const centerProbe = cache.get(t);
@@ -323,7 +336,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
         let legacy = contextUsed;
         let grid = legacy ? times : grids.get(motionBlur);
         if (still) {
-          png = centerProbe.png; result = centerProbe.image; usedSamples = 1;
+          png = centerProbe.png; result = centerProbe.image; usedSamples = 1; selectedTimes = [t];
           stats.staticFrames++; stats.adaptiveFrames++;
         } else {
           if (legacy) cache.clear();
@@ -338,22 +351,25 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
             const images = grid.map(time => cache.get(time).image), center = cache.get(t);
             const identical = images.every(image => image.data.equals(center.image.data));
             if (identical) {
-              png = center.png; result = center.image; usedSamples = 1;
+              png = center.png; result = center.image; usedSamples = 1; selectedTimes = [t];
               stats.staticFrames++; stats.adaptiveFrames++; break;
             }
             let difference = 0;
-            for (let i = 1; i < images.length && difference <= threshold; i++) difference = Math.max(difference, localMotionDifference(images[i - 1], images[i], alpha, threshold));
-            if (difference <= threshold || motionBlur >= post.maxMotionBlur) {
-              usedSamples = motionBlur;
+            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));
+            }
+            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);
           }
         }
-      } else if (motionBlur === 1) ({ png, image: result } = await sample(t));
+      } else if (motionBlur === 1) { selectedTimes = [t]; ({ png, image: result } = await sample(t)); }
       else if (hooked) {
         await sampleMany(times);
         result = timed('averageMs', () => average(times.map(time => cache.get(time).image)));
@@ -362,7 +378,7 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
         const first = cache.get(times[0]), last = cache.get(times.at(-1));
         const identical = first.image.data === last.image.data || first.image.data.equals(last.image.data);
         if (identical || (!alpha && imageDifference(first.image, last.image) < adaptive)) {
-          png = first.png; result = first.image; usedSamples = 1; stats.adaptiveFrames++;
+          png = first.png; result = first.image; usedSamples = 1; selectedTimes = [times[0]]; stats.adaptiveFrames++;
           if (identical) stats.staticFrames++;
         } else {
           await sampleMany(times);
@@ -372,13 +388,29 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
         await sampleMany([times[0], times.at(-1), t]);
         const first = cache.get(times[0]), last = cache.get(times.at(-1)), center = cache.get(t);
         if (first.image.data.equals(last.image.data) && first.image.data.equals(center.image.data)) {
-          png = center.png; result = center.image; usedSamples = 1; stats.staticFrames++;
+          png = center.png; result = center.image; usedSamples = 1; selectedTimes = [t]; stats.staticFrames++;
         } else {
           await sampleMany(times);
           const images = times.map(time => cache.get(time).image);
           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);
+      }
       if (verifyReuse) {
         stats.auditMs += performance.now() - auditStart;
         Atomics.add(state, 2, 1);
@@ -394,9 +426,10 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       if (candidate && !verifyReuse) Atomics.add(state, 1, 1);
       // Keep a decoded raw reference as well; never retain a transferable output buffer.
       if (enabled && options.transport === 'raw') result ??= await decode(png);
-      previousRaw = { t, frame, motionBlur, uniform, png, image: result, usedSamples, run: candidate ? previousRaw.run + 1 : 0 };
+      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) {
         result ??= await decode(png);

package/src/render-pool.mjs

@@ -12,11 +12,12 @@ export function defaultWorkers(scale = 1, hardware = {}) {
   return Math.max(1, Math.min(12, Math.floor(cores / 2), Math.floor((free - 2 * 1024 ** 3) / workerBytes)));
 }
 
-export function createRenderPool(shot, options, fps, workers, size, onWarning) {
+export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured) {
   options = { ...options, _browserRecovery: options._browserRecovery ?? recoveryBudget() };
   reuseState(options);
   const slots = [], stats = { frames: 0, samples: 0, staticFrames: 0 };
-  const histogram = {};
+  const histogram = {}, dofHistogram = {};
+  const captured = new Set();
   let failure;
   for (let i = 0; i < workers; i++) {
     const worker = new Worker(new URL('./render-worker.mjs', import.meta.url), { workerData: { shot, options, fps, size } });
@@ -28,6 +29,13 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning) {
     slot.ready = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
     slot.ready.catch(() => {});
     worker.on('message', message => {
+      if (message.type === 'captured') {
+        if (!captured.has(message.frame)) {
+          captured.add(message.frame);
+          try { onCaptured?.(captured.size); } catch (error) { fail(error); }
+        }
+        return;
+      }
       if (message.type === 'warning') { onWarning?.(message.warning); return; }
       if (message.type === 'failure') { fail(new MultiplaneError(message.code ?? 'worker_crashed', message.error, { details: message.details, hint: message.hint })); return; }
       const pending = slot.pending; slot.pending = null;
@@ -43,7 +51,8 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning) {
   }
   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}`,
     async *frames(first, end) {
@@ -69,9 +78,10 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning) {
         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];
+          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 };
+          yield { frame: batch.first + i, png, hash: batch.hashes?.[i], blurSamples: count, dofSamples: dofCount };
         }
         if (options.transport !== 'raw') schedule(slot);
       }
@@ -86,8 +96,8 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning) {
     },
   };
   const frames = api.frames.bind(api);
-  api.frames = async function* (first, end, onCaptured) {
-    for await (const item of frames(first, end)) { await onCaptured?.(item); yield item; }
+  api.frames = async function* (first, end, onDelivered) {
+    for await (const item of frames(first, end)) { await onDelivered?.(item); yield item; }
   };
   return api;
 }

package/src/render-worker.mjs

@@ -25,12 +25,13 @@ try {
     if (closing) return;
     running = true;
     try {
-      const frames = [], hashes = [], blurSamples = [], before = { ...processed.stats };
+      const frames = [], hashes = [], blurSamples = [], dofSamples = [], before = { ...processed.stats };
       const source = async function* (first, end) {
         for (let index = first; index < end && !closing; index++) {
           const frame = message.first + index;
           const png = await processed.frame(frame / workerData.fps, frame, index === end - 1);
-          yield { png, hash: processed.lastHash, blurSamples: processed.lastBlurSamples };
+          parentPort.postMessage({ type: 'captured', frame });
+          yield { png, hash: processed.lastHash, blurSamples: processed.lastBlurSamples, dofSamples: processed.lastDofSamples };
         }
       };
       // RAW post output already owns an independent buffer. Keep it until the
@@ -40,11 +41,12 @@ 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);
       }
       const stats = Object.fromEntries(Object.entries(processed.stats).map(([key, value]) => [key, value - before[key]]));
-      if (!closing) parentPort.postMessage({ type: 'frames', first: message.first, frames, hashes, blurSamples, stats }, frames.map(f => f.buffer));
+      if (!closing) parentPort.postMessage({ type: 'frames', first: message.first, frames, hashes, blurSamples, dofSamples, stats }, frames.map(f => f.buffer));
     } catch (error) {
       sendFailure(error); closing = true;
     } finally {

package/src/render.mjs

@@ -1,4 +1,4 @@
-import { readBenchmark, validBenchmark, benchmarkMachine, selectWorkers, classifyShot } from './workers.mjs';
+import { readBenchmark, 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';
@@ -59,10 +59,10 @@ export async function renderShot(shot, options = {}) {
       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 (!['option', 'config'].includes(events.workersSource)) type = await classifyShot(capture);
       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,
@@ -94,7 +94,8 @@ export async function renderShot(shot, options = {}) {
       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);
+      pool = createRenderPool(shot, options, fps, actualWorkers, { width, height }, events.warning,
+        done => events.progress('capture', done, total));
       events.onCancel(() => pool?.cancel());
       await mkdir(path.dirname(out), { recursive: true });
       events.check();
@@ -122,7 +123,6 @@ export async function renderShot(shot, options = {}) {
       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 });
@@ -149,7 +149,7 @@ export async function renderShot(shot, options = {}) {
       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 };
+      result = { staticReuse: pool.staticReuse, blurSamples: pool.blurSamples, dofSamples: pool.dofSamples, 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/server.mjs

@@ -61,7 +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(); }
-      if ((await stat(target)).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/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) {
     const position = camera.position.clone(), projection = camera.projectionMatrix.clone();
     const projectionInverse = camera.projectionMatrixInverse.clone();
     const autoClear = renderer.autoClear, oldTarget = renderer.getRenderTarget();
@@ -195,7 +194,7 @@ 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);
+      sumMaterial.uniforms.blurScale.value = radius * height * projection.elements[5] * 0.5 * blur / Math.sqrt(budget);
       for (const [x, y, jx, jy] of pattern(count)) {
         const dx = (x * Math.cos(rotation) - y * Math.sin(rotation)) * radius;
         const dy = (x * Math.sin(rotation) + y * Math.cos(rotation)) * radius;
@@ -226,19 +225,34 @@ export function createThreeLayer({ stage = document.querySelector('#stage'), siz
     textures.add(texture);
     return texture;
   }
-  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 = {} }) {
-    const textureStyle = { ...layerStyle, ...style };
-    const composeBackground = layerBackground || style.textureBackground !== undefined;
+  /**
+   * @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 = {}, 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 = 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 +302,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 +334,18 @@ 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 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);
         const rotation = 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, budget);
       }
     },
     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.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/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.