multiplane 0.0.0-stage → 0.3.1

package/src/post.mjs

@@ -0,0 +1,433 @@
+import { reuseEnabled, reuseState, reuseReport, REUSE_INTERVAL } from './static-reuse.mjs';
+import { pixelDifference, classifyPixelDifference } from './pixel-comparison.mjs';
+import { averageAlpha, resizeAlpha, clearHiddenColors } from './alpha.mjs';
+import { MultiplaneError, invalidOption } from './errors.mjs';
+import { number, validateScale } from './capture.mjs';
+import { decodePNG, encodePNG } from './png.mjs';
+import { createHash } from 'node:crypto';
+import { decodeNativePNG } from './png-native.mjs';
+import sharp from 'sharp';
+
+export const postArgs = ['quality', 'motion-blur', 'max-motion-blur', 'shutter', 'grain', 'no-post', 'adaptive-blur'];
+export const scaleArgs = ['scale', 'render-scale', 'upscale'];
+export const DEFAULT_ADAPTIVE_BLUR = 0.5;
+
+export function resolveScale(options = {}) {
+  const scale = number(options.scale ?? 1, '--scale', { positive: true });
+  const renderScale = number(options['render-scale'] ?? scale, '--render-scale', { positive: true });
+  if (renderScale > scale) throw invalidOption('--render-scale', '--render-scale must not exceed --scale.');
+  const upscale = options.upscale ?? 'lanczos';
+  if (!['neighbor', 'lanczos'].includes(upscale)) throw invalidOption('--upscale', '--upscale must be neighbor or lanczos.');
+  return { scale, renderScale, upscale };
+}
+
+export function imageDifference(a, b) {
+  if (a.width !== b.width || a.height !== b.height) throw new MultiplaneError('internal_error', 'Sample dimensions differ.');
+  let sum = 0;
+  if (a.data.byteOffset % 4 === 0 && b.data.byteOffset % 4 === 0) {
+    const aa = new Uint32Array(a.data.buffer, a.data.byteOffset, a.data.length / 4);
+    const bb = new Uint32Array(b.data.buffer, b.data.byteOffset, b.data.length / 4);
+    for (let p = 0; p < aa.length; p++) {
+      const x = aa[p], y = bb[p];
+      if (x === y) continue;
+      sum += Math.abs((x & 255) - (y & 255)) + Math.abs(((x >>> 8) & 255) - ((y >>> 8) & 255)) + Math.abs(((x >>> 16) & 255) - ((y >>> 16) & 255));
+    }
+    return sum / (a.width * a.height * 3);
+  }
+  for (let p = 0; p < a.data.length; p += 4) for (let c = 0; c < 3; c++) sum += Math.abs(a.data[p + c] - b.data[p + c]);
+  return sum / (a.width * a.height * 3);
+}
+
+export async function resizeImage(image, width, height, upscale) {
+  const data = await sharp(image.data, { raw: { width: image.width, height: image.height, channels: 4 } })
+    .resize(width, height, { kernel: upscale === 'neighbor' ? 'nearest' : 'lanczos3' }).raw().toBuffer();
+  return { width, height, data };
+}
+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.');
+  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 });
+  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 });
+  if (!Number.isSafeInteger(maxMotionBlur)) throw invalidOption('maxMotionBlur', 'maxMotionBlur must be a positive integer.');
+  // 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') };
+}
+
+// Local temporal change divided by spatial edge strength estimates displacement.
+// Edge normalization avoids treating dense text as faster than a single straight edge.
+export function localMotionDifference(a, b, alpha = false, stopAbove = Infinity) {
+  if (a.width !== b.width || a.height !== b.height) throw new MultiplaneError('internal_error', 'Sample dimensions differ.');
+  let maximum = 0;
+  const channels = alpha ? 4 : 3;
+  const value = (image, p, c) => image.data[p + c] * (alpha && c < 3 ? image.data[p + 3] / 255 : 1);
+  for (let y = 0; y < a.height; y += 8) for (let x = 0; x < a.width; x += 8) {
+    const right = Math.min(x + 8, a.width), bottom = Math.min(y + 8, a.height);
+    let changed = false;
+    for (let yy = y; yy < bottom && !changed; yy++) for (let xx = x; xx < right && !changed; xx++) {
+      const p = (yy * a.width + xx) * 4;
+      for (let c = 0; c < channels; c++) if (value(a, p, c) !== value(b, p, c)) { changed = true; break; }
+    }
+    if (!changed) continue;
+    const sums = [0, 0, 0, 0], edgesA = [0, 0, 0, 0], edgesB = [0, 0, 0, 0];
+    for (let yy = y; yy < bottom; yy++) for (let xx = x; xx < right; xx++) {
+      const p = (yy * a.width + xx) * 4;
+      for (let c = 0; c < channels; c++) {
+        const av = value(a, p, c), bv = value(b, p, c);
+        sums[c] += Math.abs(av - bv);
+        if (xx > 0) {
+          edgesA[c] += Math.abs(av - value(a, p - 4, c));
+          edgesB[c] += Math.abs(bv - value(b, p - 4, c));
+        }
+        if (yy > 0) {
+          edgesA[c] += Math.abs(av - value(a, p - a.width * 4, c));
+          edgesB[c] += Math.abs(bv - value(b, p - b.width * 4, c));
+        }
+      }
+    }
+    // A byte-scale floor bounds division in flat or nearly flat blocks.
+    for (let c = 0; c < channels; c++) maximum = Math.max(maximum, sums[c] / Math.max(16, edgesA[c], edgesB[c]));
+    if (maximum > stopAbove) return maximum;
+  }
+  return maximum;
+}
+
+export function blurSampleReport(histogram) {
+  const entries = Object.entries(histogram).map(([n, count]) => [Number(n), count]).filter(([, count]) => count > 0).sort((a, b) => a[0] - b[0]);
+  const frames = entries.reduce((sum, [, count]) => sum + count, 0);
+  return { min: entries[0]?.[0] ?? 0, max: entries.at(-1)?.[0] ?? 0,
+    mean: frames ? entries.reduce((sum, [n, count]) => sum + n * count, 0) / frames : 0, histogram: Object.fromEntries(entries) };
+}
+
+export function sampleTimes(t, fps, duration, cuts, { motionBlur, shutter }) {
+  let lo = 0, hi = duration;
+  for (const c of cuts) {
+    if (t >= c) lo = Math.max(lo, c);
+    else hi = Math.min(hi, Math.max(t, c - 1e-6));
+  }
+  return Array.from({ length: motionBlur }, (_, i) => Math.min(hi, Math.max(lo, t + ((i + 0.5) / motionBlur - 0.5) * shutter / fps)));
+}
+
+// Work backwards from the final midpoint grid. Mirrored pairs keep the
+// centroid at zero; each smaller level chooses evenly spaced remaining pairs.
+export function nestedSampleGrids(t, fps, duration, cuts, post) {
+  const counts = [post.motionBlur];
+  while (counts.at(-1) < post.maxMotionBlur) counts.push(Math.min(post.maxMotionBlur, counts.at(-1) * 2));
+  const maximum = counts.at(-1);
+  let pairs = Array.from({ length: Math.floor(maximum / 2) }, (_, i) => (i + 0.5) / maximum - 0.5);
+  const grids = new Map();
+  for (const count of [...counts].reverse()) {
+    const size = Math.floor(count / 2);
+    let first = 0;
+    pairs = Array.from({ length: size }, (_, i) => {
+      const target = (i + 0.5) / count - 0.5;
+      let best = first;
+      for (let j = first + 1; j <= pairs.length - (size - i); j++) {
+        if (Math.abs(pairs[j] - target) < Math.abs(pairs[best] - target)) best = j;
+      }
+      first = best + 1;
+      return pairs[best];
+    });
+    const offsets = [...pairs, ...(count % 2 ? [0] : []), ...pairs.map(x => -x)].sort((a, b) => a - b);
+    // Reuse the existing clipping rules, including the cut epsilon.
+    const bounds = sampleTimes(t, fps, duration, cuts, { motionBlur: 2, shutter: post.shutter * 2 });
+    grids.set(count, offsets.map(x => Math.min(bounds[1], Math.max(bounds[0], t + x * post.shutter / fps))));
+  }
+  return grids;
+}
+
+const linear = Float64Array.from({ length: 256 }, (_, i) => {
+  const v = i / 255;
+  return v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+});
+const transfer = v => Math.round(255 * (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055));
+const transferTable = Uint8Array.from({ length: 65537 }, (_, i) => transfer(i / 65536));
+export function linearToByte(v) {
+  const index = Math.floor(v * 65536), value = transferTable[index];
+  return value === transferTable[index + 1] ? value : transfer(v);
+}
+export function averageLinear(images) {
+  const { width, height } = images[0], data = Buffer.alloc(images[0].data.length);
+  if (images.every(image => image.data.byteOffset % 4 === 0)) {
+    const words = images.map(image => new Uint32Array(image.data.buffer, image.data.byteOffset, image.data.length / 4));
+    const output = new Uint32Array(data.buffer, data.byteOffset, data.length / 4);
+    for (let pixel = 0; pixel < output.length; pixel++) {
+      const first = words[0][pixel];
+      let equal = true;
+      for (let i = 1; i < words.length; i++) if (words[i][pixel] !== first) { equal = false; break; }
+      if (equal) { output[pixel] = first; continue; }
+      for (let c = 0; c < 4; c++) {
+        const p = pixel * 4 + c;
+        let sum = 0;
+        for (const image of images) sum += c === 3 ? image.data[p] : linear[image.data[p]];
+        const v = sum / images.length;
+        data[p] = c === 3 ? Math.round(v) : linearToByte(v);
+      }
+    }
+    return { width, height, data };
+  }
+  for (let p = 0; p < data.length; p++) {
+    let sum = 0;
+    for (const image of images) sum += p % 4 === 3 ? image.data[p] : linear[image.data[p]];
+    const v = sum / images.length;
+    data[p] = p % 4 === 3 ? Math.round(v) : linearToByte(v);
+  }
+  return { width, height, data };
+}
+
+const grainTables = new Map();
+function grainTable(grain) {
+  if (!(grain > 0 && grain <= 128)) return null;
+  if (!grainTables.has(grain)) {
+    if (grainTables.size === 4) grainTables.delete(grainTables.keys().next().value);
+    grainTables.set(grain, Int16Array.from({ length: 65537 }, (_, i) => Math.round((i / 65536 - 0.5) * Math.sqrt(12) * grain)));
+  }
+  return grainTables.get(grain);
+}
+
+export function addGrain(image, grain, frame) {
+  const data = Buffer.from(image.data);
+  const table = grainTable(grain);
+  let state = (frame >>> 0) ^ 0x9e3779b9;
+  for (let p = 0; p < data.length; p += 4) {
+    state = (state + 0x6d2b79f5) | 0;
+    let r = Math.imul(state ^ (state >>> 15), 1 | state);
+    r ^= r + Math.imul(r ^ (r >>> 7), 61 | r);
+    const value = (r ^ (r >>> 14)) >>> 0, index = value >>> 16;
+    const offset = table && table[index] === table[index + 1] ? table[index]
+      : Math.round((value / 4294967296 - 0.5) * Math.sqrt(12) * grain);
+    data[p] = Math.max(0, Math.min(255, data[p] + offset));
+    data[p + 1] = Math.max(0, Math.min(255, data[p + 1] + offset));
+    data[p + 2] = Math.max(0, Math.min(255, data[p + 2] + offset));
+  }
+  return { ...image, data };
+}
+
+export function createPostCapture(capture, options = {}, fps = capture.fps) {
+  const alpha = options.alpha ?? capture.alpha ?? capture.post?.alpha ?? false;
+  const average = alpha ? averageAlpha : averageLinear;
+  const sizes = resolveScale(options);
+  validateScale(capture.width, capture.height, sizes.scale);
+  validateScale(capture.width, capture.height, sizes.renderScale, '--render-scale');
+  const adaptive = number(options['adaptive-blur'] ?? DEFAULT_ADAPTIVE_BLUR, '--adaptive-blur');
+  const post = resolvePost(options, capture.post), stats = { samples: 0, staticFrames: 0, adaptiveFrames: 0, hookFrames: 0, reusedDecodes: 0, frames: 0, observeMs: 0, auditMs: 0, captureMs: 0, decodeMs: 0, averageMs: 0, grainMs: 0, pngMs: 0, resizeMs: 0 };
+  const timed = (key, fn) => { const start = performance.now(); const value = fn(); stats[key] += performance.now() - start; return value; };
+  let decodedCache, previousRaw;
+  const state = reuseState(options);
+  const enabled = reuseEnabled(options) && !!capture.observe;
+  const decode = async (png, reuse = false) => {
+    if (reuse && decodedCache?.png.equals(png)) { stats.reusedDecodes++; return decodedCache.image; }
+    const start = performance.now();
+    let image = options.decoder === 'js' ? decodePNG(png) : await decodeNativePNG(png);
+    stats.decodeMs += performance.now() - start;
+    if (alpha && sizes.renderScale < 1) {
+      const resizeStart = performance.now();
+      image = resizeAlpha(image, capture.width * sizes.renderScale, capture.height * sizes.renderScale, sizes.upscale);
+      stats.resizeMs += performance.now() - resizeStart;
+    }
+    if (reuse) decodedCache = { png: Buffer.from(png), image };
+    return image;
+  };
+  const api = {
+    post, stats,
+    get staticReuse() { return reuseReport(options); },
+    progress: () => `Samples: ${stats.samples}; static: ${stats.staticFrames}; adaptive: ${stats.adaptiveFrames}; hooks: ${stats.hookFrames}`,
+    async frame(t, frame = Math.round(t * fps), audit = false) {
+      let motionBlur = post.motionBlur;
+      const hooked = motionBlur > 1 && typeof capture.blurAt === 'function';
+      if (hooked) {
+        const requested = await capture.blurAt(t);
+        if (typeof requested !== 'number' || !Number.isSafeInteger(requested) || requested < 1) throw new MultiplaneError('shot_contract_invalid', 'SHOT.blurAt(t) must return a positive integer sample count.');
+        motionBlur = Math.min(requested, motionBlur);
+        stats.hookFrames++;
+      }
+      // Explicit shot hooks retain their existing authority over sampling.
+      // TODO(design): Document that blurAt bypasses upward adaptation.
+      const upward = !hooked && motionBlur > 1 && post.maxMotionBlur > motionBlur;
+      const initialMotionBlur = motionBlur;
+      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 });
+      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 }));
+          observedTime = time;
+          if (changes.at(-1)) break;
+        }
+        stats.observeMs += performance.now() - observeStart;
+        uniform = !changes.some(Boolean);
+        const nearCut = capture.cuts.some(c => Math.abs(t - c) <= 1 / fps + 1e-9 || (previousRaw && c > previousRaw.t && c <= t));
+        candidate = !!previousRaw && previousRaw.uniform && previousRaw.motionBlur === motionBlur
+          && frame === previousRaw.frame + 1 && t > previousRaw.t && !nearCut && !changes.some(Boolean);
+      }
+      const verifyReuse = candidate && (audit || previousRaw.run === 0 || frame % REUSE_INTERVAL === 0);
+      const cache = new Map();
+      let contextUsed = false;
+      const sample = async (time, reuse = false) => {
+        if (!cache.has(time)) {
+          const start = performance.now();
+          const observed = time === observedTime;
+          observedTime = undefined;
+          const png = await capture.frame(time, { motionBlur, observed });
+          contextUsed ||= capture.sampleContextUsed === 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 });
+        }
+        return cache.get(time);
+      };
+      const sampleMany = async (sequence, reuse = false) => {
+        const missing = [...new Set(sequence)].filter(time => !cache.has(time));
+        if (!missing.length) return;
+        if (!capture.beginFrame || options.pipeline === false) {
+          for (const time of missing) await sample(time, reuse);
+          return;
+        }
+        const begin = async time => {
+          const start = performance.now(), observed = time === observedTime;
+          observedTime = undefined;
+          const pending = await capture.beginFrame(time, { motionBlur, observed });
+          contextUsed ||= capture.sampleContextUsed === true;
+          const png = pending.png.then(buffer => { stats.captureMs += performance.now() - start; return buffer; });
+          png.catch(() => {});
+          return { png };
+        };
+        let pending = await begin(missing[0]);
+        for (let i = 0; i < missing.length; i++) {
+          const png = await pending.png;
+          const next = i + 1 < missing.length ? await begin(missing[i + 1]) : null;
+          stats.samples++;
+          cache.set(missing[i], { png, image: await decode(png, reuse) });
+          pending = next;
+        }
+      };
+      const auditStart = performance.now();
+      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.
+        const threshold = resolveQuality(options) === 'high' ? 1 : 2;
+        await sampleMany([...endpoints, t], true);
+        const centerProbe = cache.get(t);
+        const still = endpoints.every(time => cache.get(time).image.data.equals(centerProbe.image.data));
+        let legacy = contextUsed;
+        let grid = legacy ? times : grids.get(motionBlur);
+        if (still) {
+          png = centerProbe.png; result = centerProbe.image; usedSamples = 1;
+          stats.staticFrames++; stats.adaptiveFrames++;
+        } else {
+          if (legacy) cache.clear();
+          while (true) {
+            await sampleMany([...grid, t], true);
+            // A conditional read discovered after the probes restarts the frame
+            // on the old grids. No image from a different sample context survives.
+            if (contextUsed && !legacy) {
+              legacy = true; motionBlur = initialMotionBlur;
+              cache.clear(); observedTime = undefined; grid = times; continue;
+            }
+            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;
+              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;
+              result = timed('averageMs', () => average(images)); break;
+            }
+            motionBlur = Math.min(post.maxMotionBlur, motionBlur * 2);
+            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 (hooked) {
+        await sampleMany(times);
+        result = timed('averageMs', () => average(times.map(time => cache.get(time).image)));
+      } else if (adaptive > 0) {
+        await sampleMany([times[0], times.at(-1)], true);
+        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++;
+          if (identical) stats.staticFrames++;
+        } else {
+          await sampleMany(times);
+          result = timed('averageMs', () => average(times.map(time => cache.get(time).image)));
+        }
+      } else {
+        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++;
+        } else {
+          await sampleMany(times);
+          const images = times.map(time => cache.get(time).image);
+          result = timed('averageMs', () => average(images));
+        }
+      }
+      if (verifyReuse) {
+        stats.auditMs += performance.now() - auditStart;
+        Atomics.add(state, 2, 1);
+        const actual = result ??= await decode(png), expected = previousRaw.image ??= await decode(previousRaw.png);
+        if (classifyPixelDifference(pixelDifference(expected, actual), options.raster) === 'different') {
+          if (Atomics.compareExchange(state, 0, 0, 1) === 0) {
+            Atomics.store(state, 3, frame);
+            options.onWarning?.({ code: 'static_reuse_disabled', message: 'Static reuse disabled after a pixel mismatch; frames will be recaptured.', details: { frame, t } });
+          }
+          candidate = false;
+        }
+      }
+      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 };
+      // Contributing temporal samples, excluding probes and failed attempts.
+      api.lastBlurSamples = usedSamples;
+      stats.frames++;
+      if (sizes.renderScale !== sizes.scale) {
+        result ??= await decode(png);
+        const start = performance.now();
+        result = await (alpha ? resizeAlpha : resizeImage)(result, capture.width * sizes.scale, capture.height * sizes.scale, sizes.upscale);
+        stats.resizeMs += performance.now() - start;
+        png = undefined;
+      }
+      if (post.grain > 0) result = timed('grainMs', () => addGrain(result, post.grain, frame));
+      // Grain changes straight visible RGB only; never alpha or hidden output colors.
+      if (alpha) { result = clearHiddenColors(result ?? await decode(png)); png = undefined; }
+      if (options.verify) {
+        const image = result ??= await decode(png);
+        if (image.width !== capture.width * sizes.scale || image.height !== capture.height * sizes.scale) throw new MultiplaneError('internal_error', 'Pixel verification dimensions do not match output.');
+        api.lastHash = createHash('sha256').update(image.data).digest('hex');
+      }
+      if (options.transport === 'raw') {
+        const image = result ?? await decode(png);
+        return image === decodedCache?.image || image === previousRaw?.image ? Buffer.from(image.data) : image.data;
+      }
+      if (post.grain > 0) return timed('pngMs', () => encodePNG(result));
+      return png ?? timed('pngMs', () => encodePNG(result));
+    },
+  };
+  if (capture.retryFrame) {
+    const frame = api.frame.bind(api);
+    api.frame = (t, index, audit) => capture.retryFrame(t, async () => {
+      const before = { ...stats };
+      try { return await frame(t, index, audit); }
+      catch (error) { Object.assign(stats, before); decodedCache = previousRaw = undefined; throw error; }
+    });
+  }
+  return api;
+}

package/src/preview.mjs

@@ -0,0 +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.' });
+    }
+  };
+}

package/src/process-identity.mjs

@@ -0,0 +1,17 @@
+import { execFile } from 'node:child_process';
+const execute = (file, args, options) => new Promise((resolve, reject) => {
+  execFile(file, args, options, (error, stdout) => error ? reject(error) : resolve({ stdout }));
+});
+// Process creation time, never the app publication time. Failure is fail-closed.
+export async function processCreatedAt(pid) {
+  if (!Number.isSafeInteger(pid) || pid <= 0) return null;
+  try {
+    process.kill(pid, 0);
+    const { stdout } = process.platform === 'win32'
+      ? await execute('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command',
+        `(Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().ToString('o')`], { windowsHide: true, timeout: 5000 })
+      : await execute('ps', ['-p', String(pid), '-o', 'lstart='], { env: { ...process.env, LC_ALL: 'C', TZ: 'UTC' }, timeout: 5000 });
+    const time = Date.parse(stdout.trim() + (process.platform === 'win32' ? '' : ' UTC'));
+    return Number.isFinite(time) ? new Date(time).toISOString() : null;
+  } catch { return null; }
+}

package/src/process.mjs

@@ -0,0 +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');
+  });
+}

package/src/render-pool.mjs

@@ -0,0 +1,93 @@
+import { reuseState, reuseReport, reuseEnabled, REUSE_INTERVAL } from './static-reuse.mjs';
+import { recoveryBudget } from './browser-recovery.mjs';
+import { MultiplaneError } from './errors.mjs';
+import { availableParallelism, freemem, totalmem } from 'node:os';
+import { Worker } from 'node:worker_threads';
+import { blurSampleReport } from './post.mjs';
+
+export function defaultWorkers(scale = 1, hardware = {}) {
+  const cores = hardware.cores ?? availableParallelism();
+  const free = Math.min(hardware.free ?? freemem(), hardware.total ?? totalmem());
+  const workerBytes = (0.25 + 0.1875 * scale * scale) * 1024 ** 3;
+  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) {
+  options = { ...options, _browserRecovery: options._browserRecovery ?? recoveryBudget() };
+  reuseState(options);
+  const slots = [], stats = { frames: 0, samples: 0, staticFrames: 0 };
+  const histogram = {};
+  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 } });
+    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 === '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;
+      pending?.resolve(message);
+    });
+    worker.on('error', error => fail(new MultiplaneError('worker_crashed', undefined, { cause: error })));
+    slot.exited = new Promise(resolve => worker.on('exit', code => {
+      slot.closed = true;
+      if (slot.pending || code !== 0) fail(new MultiplaneError('worker_crashed', `Rendering worker exited early: ${code}`));
+      resolve();
+    }));
+    slots.push(slot);
+  }
+  const api = {
+    stats,
+    get blurSamples() { return blurSampleReport(histogram); },
+    get staticReuse() { return reuseReport(options); },
+    progress: () => `Samples: ${stats.samples}; static: ${stats.staticFrames}; adaptive: ${stats.adaptiveFrames ?? 0}; hooks: ${stats.hookFrames ?? 0}`,
+    async *frames(first, end) {
+      await Promise.all(slots.map(s => s.ready));
+      const queue = [], chunk = reuseEnabled(options) ? Math.min(REUSE_INTERVAL + 1, Math.ceil((end - first) / slots.length)) : options.transport === 'raw' ? 1 : 4;
+      let next = first;
+      const schedule = slot => {
+        if (next >= end) return;
+        if (failure) throw failure;
+        const begin = next;
+        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.worker.postMessage({ type: 'render', first: begin, end: next });
+        queue.push({ slot, promise });
+      };
+      for (const slot of slots) schedule(slot);
+      while (queue.length) {
+        const { slot, promise } = queue.shift();
+        const batch = await promise;
+        if (failure) throw failure;
+        for (const [key, value] of Object.entries(batch.stats)) stats[key] = (stats[key] ?? 0) + value;
+        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];
+          histogram[count] = (histogram[count] ?? 0) + 1;
+          yield { frame: batch.first + i, png, hash: batch.hashes?.[i], blurSamples: count };
+        }
+        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));
+    },
+    async cancel() {
+      for (const slot of slots) if (!slot.closed) slot.worker.postMessage({ type: 'cancel' });
+      await Promise.all(slots.map(s => s.exited));
+    },
+  };
+  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; }
+  };
+  return api;
+}

package/src/render-worker.mjs

@@ -0,0 +1,59 @@
+import { verifiedFrames } from './static-reuse.mjs';
+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';
+
+let capture, closing = false, running = false;
+const sendFailure = error => {
+  const failure = asError(error);
+  parentPort.postMessage({ type: 'failure', error: failure.message, code: failure.code, details: failure.details, hint: failure.hint });
+};
+async function close() {
+  closing = true;
+  if (running) return;
+  await capture?.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'); } });
+  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 (closing) return;
+    running = true;
+    try {
+      const frames = [], hashes = [], blurSamples = [], 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 };
+        }
+      };
+      // RAW post output already owns an independent buffer. Keep it until the
+      // interval audit, then transfer it without a second full-frame copy.
+      for await (const item of verifiedFrames(source, workerData.options, message.end - message.first, { owned: workerData.options.transport === 'raw' })) {
+        const result = item.png;
+        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);
+        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));
+    } catch (error) {
+      sendFailure(error); closing = true;
+    } finally {
+      running = false;
+      if (closing) await close();
+    }
+  });
+  parentPort.postMessage({ type: 'ready' });
+} catch (error) {
+  sendFailure(error);
+  await close();
+}