multiplane 0.3.6 → 0.3.8

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) });
@@ -328,11 +329,25 @@ export function createPostCapture(capture, options = {}, fps = capture.fps) {
       let png, result, usedSamples = motionBlur;
       if (candidate && !verifyReuse) { ({ png, image: result, usedSamples } = previousRaw); }
       else if (upward) {
+        // TODO(design): Half-size probes need a compatible decision policy;
+        // halving the raster and displacement threshold changes refinement.
         // 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);
+        // Stop as soon as motion is established. Retain exact full-size still
+        // checks, and reuse every matching time without changing the final grid.
+        await sampleMany([t, endpoints[0]], true);
         const centerProbe = cache.get(t);
-        const still = endpoints.every(time => cache.get(time).image.data.equals(centerProbe.image.data));
+        let still = cache.get(endpoints[0]).image.data.equals(centerProbe.image.data);
+        if (still) {
+          await sampleMany([endpoints[1]], true);
+          still = cache.get(endpoints[1]).image.data.equals(centerProbe.image.data);
+        } else if (capture._inspectSample) {
+          // Preserve conditional sampleContext reads at the skipped endpoint.
+          const start = performance.now();
+          await capture._inspectSample(endpoints[1], context(false, endpoints[1]));
+          stats.captureMs += performance.now() - start;
+          contextUsed ||= capture.sampleContextUsed === true;
+        }
         let legacy = contextUsed;
         let grid = legacy ? times : grids.get(motionBlur);
         if (still) {
@@ -356,15 +371,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 +410,24 @@ 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.
+        // TODO(design): Zero aperture still has interleaved projection jitter;
+        // reusing its probes requires an approved change to that pattern.
+        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 +445,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

@@ -4,6 +4,7 @@ import { MultiplaneError } from './errors.mjs';
 import { availableParallelism, freemem, totalmem } from 'node:os';
 import { Worker } from 'node:worker_threads';
 import { blurSampleReport } from './post.mjs';
+import { createCaptureWatchdog } from './capture-watchdog.mjs';
 
 export function defaultWorkers(scale = 1, hardware = {}) {
   const cores = hardware.cores ?? availableParallelism();
@@ -12,24 +13,50 @@ 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, onCaptured) {
+export function createRenderPool(shot, options, fps, workers, size, onWarning, onCaptured, onInput) {
   options = { ...options, _browserRecovery: options._browserRecovery ?? recoveryBudget() };
   reuseState(options);
   const slots = [], stats = { frames: 0, samples: 0, staticFrames: 0 };
   const histogram = {}, dofHistogram = {};
   const captured = new Set();
-  let failure;
+  let failure, stopping = false, closing;
+  function close() {
+    if (closing) return closing;
+    stopping = true; watchdog.stop();
+    for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
+    // A blocked page cannot finish its frame. Close only browsers owned by
+    // these workers after the grace period, letting their normal cleanup run.
+    const timer = setTimeout(() => {
+      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
+    }, options._stopGraceMs ?? 5000); // Internal override for short fault tests.
+    closing = Promise.all(slots.map(s => s.exited)).finally(() => clearTimeout(timer));
+    return closing;
+  }
+  // Internal deadline override for short fault-injection tests; no CLI option.
+  const watchdog = createCaptureWatchdog(slots, (slot, details) => {
+    if (failure || stopping) return;
+    try {
+      onWarning?.({ code: 'worker_stalled', severity: 'warning', message: 'Rendering worker stalled.', details });
+      slot.worker.postMessage({ type: 'stalled', details });
+    } catch (error) { fail(error); }
+  }, { minimumMs: options._stallTimeoutMs });
+  const fail = error => {
+    failure ??= error;
+    watchdog.stop();
+    for (const s of slots) { s.pending?.reject(failure); s.pending = null; }
+    void close();
+  };
   for (let i = 0; i < workers; i++) {
     const worker = new Worker(new URL('./render-worker.mjs', import.meta.url), { workerData: { shot, options, fps, size } });
     const slot = { worker, pending: null, closed: false };
-    const fail = error => {
-      failure ??= error;
-      for (const s of slots) { s.pending?.reject(error); s.pending = null; }
-    };
     slot.ready = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
     slot.ready.catch(() => {});
     worker.on('message', message => {
+      if (message.type === 'frame-start') { slot.frame = message.frame; slot.frameStarted = performance.now(); return; }
+      if (message.type === 'recovered') { watchdog.recovered(slot); return; }
+      if (message.type === 'input') { try { onInput?.(message.file, message.record); } catch (error) { fail(error); } return; }
       if (message.type === 'captured') {
+        watchdog.completed(slot);
         if (!captured.has(message.frame)) {
           captured.add(message.frame);
           try { onCaptured?.(captured.size); } catch (error) { fail(error); }
@@ -39,6 +66,7 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
       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;
+      slot.job = null;
       pending?.resolve(message);
     });
     worker.on('error', error => fail(new MultiplaneError('worker_crashed', undefined, { cause: error })));
@@ -51,7 +79,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}`,
@@ -66,6 +94,8 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         next = Math.min(end, next + chunk, reuseEnabled(options) ? (Math.floor(begin / REUSE_INTERVAL) + 1) * REUSE_INTERVAL + 1 : end);
         const promise = new Promise((resolve, reject) => { slot.pending = { resolve, reject }; });
         promise.catch(() => {});
+        slot.job = { first: begin, end: next }; slot.frame = begin;
+        slot.lastDelivery = performance.now(); slot.frameStarted = undefined;
         slot.worker.postMessage({ type: 'render', first: begin, end: next });
         queue.push({ slot, promise });
       };
@@ -78,7 +108,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 };
@@ -86,13 +116,10 @@ export function createRenderPool(shot, options, fps, workers, size, onWarning, o
         if (options.transport !== 'raw') schedule(slot);
       }
     },
-    async close() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'close' });
-      await Promise.all(slots.map(s => s.exited));
-    },
+    close,
     async cancel() {
-      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
-      await Promise.all(slots.map(s => s.exited));
+      fail(new MultiplaneError('cancelled'));
+      await close();
     },
   };
   const frames = api.frames.bind(api);

package/src/render-worker.mjs

@@ -3,8 +3,11 @@ import { MultiplaneError, asError } from './errors.mjs';
 import { parentPort, workerData, isMarkedAsUntransferable } from 'node:worker_threads';
 import { openShot } from './capture.mjs';
 import { createPostCapture, resolveScale } from './post.mjs';
+import { inputRecords } from './input-records.mjs';
 
-let capture, closing = false, running = false;
+if (workerData.options._recordInputs) inputRecords.enterWith((file, record) => parentPort.postMessage({ type: 'input', file, record }));
+
+let capture, closing = false, running = false, activeFrame;
 const sendFailure = error => {
   const failure = asError(error);
   parentPort.postMessage({ type: 'failure', error: failure.message, code: failure.code, details: failure.details, hint: failure.hint });
@@ -16,12 +19,17 @@ async function close() {
   parentPort.close();
 }
 try {
-  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
+  capture = await openShot(workerData.shot, resolveScale(workerData.options).renderScale, { ...workerData.options, onRecovered: () => parentPort.postMessage({ type: 'recovered' }), onWarning: warning => parentPort.postMessage({ type: 'warning', warning }), check: () => { if (closing) throw new MultiplaneError('cancelled'); } });
   if (workerData.size && (capture.width !== workerData.size.width || capture.height !== workerData.size.height)) throw new MultiplaneError('internal_error', 'Worker stage dimensions differ from the main process.');
   const processed = createPostCapture(capture, { ...workerData.options, onWarning: warning => parentPort.postMessage({ type: 'warning', warning }) }, workerData.fps);
   parentPort.on('message', async message => {
     if (message.type === 'cancel') { closing = true; await capture?.close(); if (!running) parentPort.close(); return; }
     if (message.type === 'close') { await close(); return; }
+    if (message.type === 'stalled') {
+      if (!closing && activeFrame === message.details.frame) await capture.stall(message.details).catch(sendFailure);
+      else parentPort.postMessage({ type: 'recovered' });
+      return;
+    }
     if (closing) return;
     running = true;
     try {
@@ -29,7 +37,10 @@ try {
       const source = async function* (first, end) {
         for (let index = first; index < end && !closing; index++) {
           const frame = message.first + index;
+          activeFrame = frame;
+          parentPort.postMessage({ type: 'frame-start', frame });
           const png = await processed.frame(frame / workerData.fps, frame, index === end - 1);
+          activeFrame = undefined;
           parentPort.postMessage({ type: 'captured', frame });
           yield { png, hash: processed.lastHash, blurSamples: processed.lastBlurSamples, dofSamples: processed.lastDofSamples };
         }
@@ -41,7 +52,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);
       }