@hyperframes/producer 0.8.199 → 0.8.201

package/dist/public-server.js

@@ -54,6 +54,7 @@ import {
   createVideoFrameInjector,
   getEncoderPreset as getEncoderPreset3,
   distributeFrames as distributeFrames2,
+  distributeFramesInterleaved as distributeFramesInterleaved2,
   executeParallelCapture as executeParallelCapture2,
   mergeWorkerFrames,
   getSystemTotalMb,
@@ -2114,6 +2115,7 @@ function aggregateDrawElement(perfs, de) {
     blankDeterministicAccepts: drain?.blankDeterministicAccepts ?? 0,
     blankRecaptures: drain?.blankRecaptures ?? 0,
     boundaryFrames: perfs.reduce((sum, p) => sum + (p.deBoundaryFrames ?? 0), 0),
+    riskFrames: perfs.reduce((sum, p) => sum + (p.deRiskFrames ?? 0), 0),
     ncprFallbacks: perfs.reduce((sum, p) => sum + (p.deNcprFallbacks ?? 0), 0),
     frameTimeouts: perfs.reduce((sum, p) => sum + (p.deFrameTimeouts ?? 0), 0)
   };
@@ -3750,11 +3752,21 @@ function createDrainFrameGuard(args) {
     return buf;
   };
 }
-async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEncoder, reorderBuffer, assertNotAborted, onProgress, log, stats, abortSignal) {
+async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEncoder, reorderBuffer, assertNotAborted, onProgress, log, stats, abortSignal, risk) {
   let prev = null;
   const frameTime = (i) => i * job.config.fps.den / job.config.fps.num;
   const guard = createDrainFrameGuard({ log, stats, frameTime });
-  const guardFrame = (idx, buf) => guard(session, idx, buf);
+  const guardFrame = (item, buf) => item.trusted ? Promise.resolve(buf) : guard(session, item.idx, buf);
+  const captureRisk = async (idx) => {
+    await risk.open();
+    lastProgressAt = Date.now();
+    return raceAgainstStall(
+      risk.capture(idx, frameTime(idx)),
+      stallTimeoutMs - (Date.now() - lastProgressAt),
+      { session, frameIndex: idx, totalFrames, stallTimeoutMs },
+      abortSignal
+    );
+  };
   const stallTimeoutMs = resolveCaptureStallTimeoutMs();
   let lastProgressAt = Date.now();
   const captureWithStallGuard = (idx, promise) => raceAgainstStall(
@@ -3766,7 +3778,7 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
   const drainPrev = async () => {
     if (!prev) return;
     assertNotAborted();
-    const buf = await guardFrame(prev.idx, await prev.encodeResult);
+    const buf = await guardFrame(prev, await prev.encodeResult);
     await reorderBuffer.waitForFrame(prev.idx);
     ensureFrameWritten(await currentEncoder.writeFrame(buf), prev.idx, currentEncoder);
     reorderBuffer.advanceTo(prev.idx + 1);
@@ -3786,7 +3798,7 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
   const drainBatch = async (batch) => {
     for (const item of batch) {
       assertNotAborted();
-      const buf = await guardFrame(item.idx, await item.encodeResult);
+      const buf = await guardFrame(item, await item.encodeResult);
       await reorderBuffer.waitForFrame(item.idx);
       ensureFrameWritten(await currentEncoder.writeFrame(buf), item.idx, currentEncoder);
       reorderBuffer.advanceTo(item.idx + 1);
@@ -3804,7 +3816,7 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
   };
   if (batchN > 1 && !session.onBeforeCapture) {
     const boundarySS = process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true";
-    const batchable = (f) => !session.staticFrames?.has(f) && !(boundarySS && session.clipBoundaryFrames?.has(f));
+    const batchable = (f) => !session.staticFrames?.has(f) && !(boundarySS && session.clipBoundaryFrames?.has(f)) && !risk?.frames.has(f);
     let prevBatch = [];
     let i = 0;
     while (i < totalFrames) {
@@ -3821,6 +3833,11 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
         );
         await drainBatch(prevBatch);
         prevBatch = results.map((r) => ({ idx: r.frameIndex, encodeResult: r.encodeResult }));
+      } else if (risk?.frames.has(i)) {
+        const buffer = await captureRisk(i);
+        await drainBatch(prevBatch);
+        prevBatch = [{ idx: i, encodeResult: Promise.resolve(buffer), trusted: true }];
+        i++;
       } else {
         const { encodeResult } = await captureWithStallGuard(
           i,
@@ -3836,6 +3853,12 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
   }
   for (let i = 0; i < totalFrames; i++) {
     assertNotAborted();
+    if (risk?.frames.has(i)) {
+      const buffer = await captureRisk(i);
+      await drainPrev();
+      prev = { idx: i, encodeResult: Promise.resolve(buffer), trusted: true };
+      continue;
+    }
     const time = frameTime(i);
     const { encodeResult } = await captureWithStallGuard(
       i,
@@ -4082,6 +4105,24 @@ async function runCaptureStreamingStage(input) {
         prepareCaptureSessionForReuse(session, framesDir, videoInjector);
         probeSession = null;
       }
+      let riskSession = null;
+      const openRiskSession = async () => {
+        const opened = await createCaptureSession(
+          fileServer.url,
+          framesDir,
+          buildCaptureOptions(),
+          createRenderVideoFrameInjector(),
+          {
+            ...captureCfg,
+            useDrawElement: false,
+            staticFrameDedup: false,
+            enableBrowserPool: false
+          }
+        );
+        riskSession = opened;
+        await initializeSession(opened);
+        return opened;
+      };
       try {
         if (!session.isInitialized) {
           await initializeSession(session);
@@ -4096,6 +4137,7 @@ async function runCaptureStreamingStage(input) {
             blankDeterministicAccepts: 0,
             blankRecaptures: 0
           };
+          const riskFrames = session.deRiskFrames;
           await runWorkerEncodePipelineLoop(
             session,
             totalFrames,
@@ -4106,7 +4148,16 @@ async function runCaptureStreamingStage(input) {
             onProgress,
             log,
             deDrainStats,
-            abortSignal
+            abortSignal,
+            riskFrames && riskFrames.size > 0 ? {
+              frames: riskFrames,
+              // Opened on the first risk frame, in a browser of its own: pages sharing a
+              // browser share a compositor, which starves the drawElement page's paint events.
+              open: async () => {
+                riskSession ??= await openRiskSession();
+              },
+              capture: async (frameIndex, time) => (await captureFrameToBuffer(riskSession, frameIndex, time)).buffer
+            } : void 0
           );
         } else {
           const stallTimeoutMs = resolveCaptureStallTimeoutMs();
@@ -4144,6 +4195,7 @@ async function runCaptureStreamingStage(input) {
       } finally {
         lastBrowserConsole = session.browserConsoleBuffer;
         await closeCaptureSession(session);
+        if (riskSession) await closeCaptureSession(riskSession);
       }
     }
     const encodeFrom = job.progress;
@@ -4303,7 +4355,7 @@ function openSegmentedSessionReuse(input, session) {
 async function openSegmentedSession(input) {
   const captureCfg = input.cfg.forceScreenshot === input.plan.forceScreenshot ? input.cfg : { ...input.cfg, forceScreenshot: input.plan.forceScreenshot };
   const videoInjector = input.createRenderVideoFrameInjector();
-  const captureOptions = input.buildCaptureOptions();
+  const captureOptions = { ...input.buildCaptureOptions(), deFrameFallback: false };
   const ownBrowser = shouldDisableBrowserPoolForParallelWorker({
     parallel: (input.workerCount ?? 1) > 1
   });
@@ -5548,6 +5600,7 @@ import {
   parseVideoElements,
   parseImageElements,
   parseAudioElements,
+  isSelfOrAncestorHidden,
   resolveReferencedStart
 } from "@hyperframes/engine";
 function resolveHostEnd(host, hostStart) {
@@ -5608,6 +5661,15 @@ function collectHostWindows(html) {
   }
   return windows;
 }
+function collectHiddenVideoIds(html) {
+  const { document: document2 } = parseHTML2(html);
+  const hidden = /* @__PURE__ */ new Set();
+  for (const element of document2.querySelectorAll("video")) {
+    const id = element.getAttribute(MEDIA_RENDER_ID_ATTR) || element.getAttribute("id");
+    if (id && isSelfOrAncestorHidden(element)) hidden.add(id);
+  }
+  return hidden;
+}
 function toAbsoluteWindow(start, end, window2) {
   const absoluteStart = resolveAbsoluteMediaStartSeconds({
     authoredStart: start,
@@ -5641,8 +5703,13 @@ function collectRenderMedia(html) {
   const windows = collectHostWindows(html);
   const windowFor = (id) => windows.get(id) ?? ROOT_WINDOW;
   const droppedMediaIds = /* @__PURE__ */ new Set();
+  const hiddenIds = collectHiddenVideoIds(html);
   const videos = [];
   for (const video of parseVideoElements(html)) {
+    if (hiddenIds.has(video.id)) {
+      droppedMediaIds.add(video.id);
+      continue;
+    }
     const absolute = toAbsoluteWindow(video.start, video.end, windowFor(video.id));
     if (!absolute) {
       droppedMediaIds.add(video.id);
@@ -5852,7 +5919,7 @@ async function runAnimatedGifTranscode(request) {
       failureReason: result.failureReason
     });
   }
-  if (result.terminationReason === "deadline") {
+  if (result.terminationReason === "inactivity") {
     throw new Error(`Animated GIF transcode timed out after ${timeout}ms`);
   }
   throw result.error ?? new Error(`Animated GIF transcode failed (${result.exitCode}): ${result.stderr.slice(-500)}`);
@@ -6319,10 +6386,6 @@ var THREE_D_CONTEXT_PATTERN = /transform-style\s*:\s*preserve-3d|backface-visibi
 function detectThreeDTransformUsage(html) {
   return THREE_D_CONTEXT_PATTERN.test(html);
 }
-var MIX_BLEND_MODE_PATTERN = /mix-blend-mode\s*:/i;
-function detectMixBlendModeUsage(html) {
-  return MIX_BLEND_MODE_PATTERN.test(html);
-}
 var BACKGROUND_IMAGE_DECL_PATTERN = /(?:^|;|\{)\s*background(?:-image)?\s*:[^;}]*(?:\bgradient\s*\(|url\s*\()/i;
 function detectAncestorBackgroundImage(html) {
   const { document: document2 } = parseHTML4(html);
@@ -6475,8 +6538,9 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
   const markedStaticHtml = markInferredVariableMediaDurations(staticCompiled, mediaUnresolved);
   let compiledHtml = resolutions.length > 0 ? injectDurations(markedStaticHtml, resolutions) : markedStaticHtml;
   const preResolved = extractResolvedMedia(compiledHtml);
+  const hiddenVideoIds = collectHiddenVideoIds(compiledHtml);
   const clampResults = await Promise.all(
-    preResolved.filter((el) => !!el.src && !el.loop).map(async (el) => {
+    preResolved.filter((el) => !!el.src && !el.loop && !hiddenVideoIds.has(el.id)).map(async (el) => {
       const { duration: maxDuration } = await resolveMediaDuration(
         el.src,
         el.mediaStart,
@@ -7335,7 +7399,6 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   const renderModeHints = detectRenderModeHints(sanitizedHtml, options.pageMotionBlur);
   const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
   const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
-  const usesMixBlendMode = detectMixBlendModeUsage(sanitizedHtml);
   const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
   const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
     injectTextRenderingRule(
@@ -7449,7 +7512,6 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
     renderModeHints,
     hasShaderTransitions,
     usesThreeDTransforms,
-    usesMixBlendMode,
     hasAncestorBackgroundImage
   };
 }
@@ -7856,13 +7918,6 @@ async function runCompileStage(input) {
       "[Render] Fast capture: composition uses a CSS 3D rendering context (perspective / preserve-3d / backface-visibility), so disabling drawElementImage for this render. Capture uses the platform's baseline route."
     );
   }
-  if (cfg.useDrawElement && process.env.HF_FAST_CAPTURE_BLEND !== "true" && compiled.usesMixBlendMode) {
-    cfg.useDrawElement = false;
-    deCompileGate = "mix_blend_mode";
-    log.info(
-      "[Render] Fast capture: composition uses mix-blend-mode, so disabling drawElementImage for this render. Capture uses the platform's baseline route."
-    );
-  }
   if (cfg.useDrawElement && process.env.HF_FAST_CAPTURE_ANCESTOR_BG !== "true" && compiled.hasAncestorBackgroundImage) {
     cfg.useDrawElement = false;
     deCompileGate = "ancestor_background_image";
@@ -8156,6 +8211,7 @@ async function runProbeStage(input) {
         height,
         fps: job.config.fps,
         format: captureFormat,
+        transparent: needsAlpha,
         quality: captureFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
         variables: job.config.variables,
         deviceScaleFactor,
@@ -9257,10 +9313,11 @@ async function constrainAacTruePeak(input) {
   const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
   return enforceAacTruePeak({
     audioPath: input.audioPath,
+    sourcePath: input.sourcePath,
     targetDurationSeconds: input.targetDurationSeconds,
     signal: input.signal,
-    probeTruePeak: (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }),
-    encode: defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
+    probeTruePeak: input.probeTruePeakDbfs ?? ((audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal })),
+    encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
   });
 }
 async function enforceAacTruePeak(input) {
@@ -9270,6 +9327,7 @@ async function enforceAacTruePeak(input) {
     const correctedPath = join18(scratchDir, "audio.m4a");
     const measurements = [];
     let attenuationDb = 0;
+    let sourcePeakDbfs;
     let measuredPath = input.audioPath;
     for (let pass = 0; pass <= MAX_TRUE_PEAK_CORRECTION_PASSES; pass += 1) {
       const truePeakDbfs = await input.probeTruePeak(measuredPath, input.signal);
@@ -9286,7 +9344,11 @@ async function enforceAacTruePeak(input) {
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
       const headroomDb = AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB * 2 ** pass;
-      attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - truePeakDbfs;
+      if (input.sourcePath && sourcePeakDbfs === void 0) {
+        sourcePeakDbfs = await input.probeTruePeak(input.sourcePath, input.signal);
+      }
+      const referenceDbfs = Math.max(truePeakDbfs, (sourcePeakDbfs ?? -Infinity) + attenuationDb);
+      attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - referenceDbfs;
       const result = await input.encode(
         input.audioPath,
         correctedPath,
@@ -9722,7 +9784,7 @@ async function runCaptureStage(input) {
       );
     }
   }
-  const captureOptions = buildCaptureOptions();
+  const captureOptions = { ...buildCaptureOptions(), deFrameFallback: false };
   const remedy = diskCaptureRemedy(cfg, job.config.format ?? "mp4", job.duration ?? 0, workerCount);
   const checkDiskProjection = createDiskCaptureProjection({
     framesDir,
@@ -9743,6 +9805,7 @@ async function runCaptureStage(input) {
       createBeforeCaptureHook: createRenderVideoFrameInjector,
       abortSignal,
       frameRangeStart: frameRange?.startFrame,
+      interleaveFrames: input.interleaveFrames,
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       onProgress: (progress) => {
@@ -11258,9 +11321,6 @@ async function runEncodeStage(input) {
     return { encodeMs: Date.now() - stage5Start };
   }
   const onFramesEncoded = startEncodeProgress(job, "Encoding video", onProgress);
-  const baseScaledEncodeTimeout = Math.ceil((job.duration ?? 0) * 4e3);
-  const scaledEncodeTimeout = baseScaledEncodeTimeout * (job.config.quality === "high" ? 6 : 1);
-  const videoEngineCfg = scaledEncodeTimeout > engineCfg.ffmpegEncodeTimeout ? { ...engineCfg, ffmpegEncodeTimeout: scaledEncodeTimeout } : engineCfg;
   const frameExt = frameFileExtension2(input.captureImageFormat);
   const framePattern = `frame_%06d.${frameExt}`;
   const encoderOpts = videoEncoderOptions(input, engineCfg);
@@ -11271,7 +11331,7 @@ async function runEncodeStage(input) {
     encoderOpts,
     chunkedEncodeSize,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   ) : await encodeFramesFromDir(
     framesDir,
@@ -11279,7 +11339,7 @@ async function runEncodeStage(input) {
     videoOnlyPath,
     encoderOpts,
     abortSignal,
-    videoEngineCfg,
+    engineCfg,
     onFramesEncoded
   );
   assertNotAborted();
@@ -11621,16 +11681,42 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   }
   return ranges;
 }
-function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0) {
+function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt, rangeStart = 0, stride = 1) {
   const workersPerBatch = Math.max(1, Math.floor(maxWorkers));
   const batches = [];
+  const outputDirFor = (batchIndex, workerId) => join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`);
+  if (stride > 1) {
+    const spans = /* @__PURE__ */ new Map();
+    for (const range of ranges) {
+      for (let frame = range.startFrame; frame < range.endFrame; frame++) {
+        const span = spans.get(frame % stride);
+        if (span) span.last = frame;
+        else spans.set(frame % stride, { first: frame, last: frame });
+      }
+    }
+    const strided = [...spans.values()];
+    for (let i = 0; i < strided.length; i += workersPerBatch) {
+      const batchIndex = batches.length;
+      batches.push(
+        strided.slice(i, i + workersPerBatch).map(({ first, last }, workerId) => ({
+          workerId,
+          startFrame: rangeStart + first,
+          endFrame: rangeStart + last + 1,
+          frameStride: stride,
+          outputDir: outputDirFor(batchIndex, workerId),
+          outputFrameOffset: rangeStart
+        }))
+      );
+    }
+    return batches;
+  }
   for (let i = 0; i < ranges.length; i += workersPerBatch) {
     const batchIndex = batches.length;
     const batch = ranges.slice(i, i + workersPerBatch).map((range, workerId) => ({
       workerId,
       startFrame: rangeStart + range.startFrame,
       endFrame: rangeStart + range.endFrame,
-      outputDir: join26(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`),
+      outputDir: outputDirFor(batchIndex, workerId),
       outputFrameOffset: rangeStart
     }));
     batches.push(batch);
@@ -11723,8 +11809,16 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
       currentWorkers,
       attemptWorkDir,
       attempt,
-      rangeStart
-    ) : [distributeFrames2(options.totalFrames, currentWorkers, attemptWorkDir, rangeStart)];
+      rangeStart,
+      options.interleaveFrames ? options.initialWorkerCount : 1
+    ) : [
+      (options.interleaveFrames ? distributeFramesInterleaved2 : distributeFrames2)(
+        options.totalFrames,
+        currentWorkers,
+        attemptWorkDir,
+        rangeStart
+      )
+    ];
     options.dedupPerfs.length = 0;
     try {
       for (const tasks of batches) {
@@ -12176,6 +12270,9 @@ function resolveDeShortBand(args) {
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
+function probeNeedsScreenshotFrames(session) {
+  return (session?.deRiskFrames?.size ?? 0) > 0;
+}
 function isProbeDeGated(session) {
   return session !== null && session.captureMode !== "drawelement" && !session.deInitDeferred;
 }
@@ -12833,6 +12930,7 @@ async function executeRenderPipeline(input) {
       height,
       fps: job.config.fps,
       format: captureImageFormat,
+      transparent: needsAlpha,
       quality: captureImageFormat === "png" ? void 0 : resolveCaptureJpegQuality(job.config.quality),
       variables: job.config.variables,
       deviceScaleFactor,
@@ -12854,6 +12952,7 @@ async function executeRenderPipeline(input) {
       // Probe-resolved duration: drawElement self-verification derives its
       // sample frame indices from this so they land inside the drained range.
       compositionDurationSeconds: job.duration,
+      deFrameFallback: true,
       requiresWebGpu: compositionRequiresWebGpu2(compiled.html),
       // Live route for Chrome memory (spec §5 Phase −1). The aggregate route
       // through CapturePerfSummary only exists on success; a mid-capture
@@ -12954,7 +13053,7 @@ async function executeRenderPipeline(input) {
       minFrames: deParallelMinFrames,
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
       supersampling: deviceScaleFactor !== 1,
-      probeDeGated: isProbeDeGated(probeSession),
+      probeDeGated: isProbeDeGated(probeSession) || probeNeedsScreenshotFrames(probeSession),
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || process.env.HF_DE_PARALLEL_STREAM === "true",
       routerEnabled: deParallelRouterEnabled,
       // Router pins 3 workers for the streaming path; don't pin when a
@@ -12996,6 +13095,8 @@ async function executeRenderPipeline(input) {
         deInversionEligible = false;
         deParallelRouterEligible = false;
         deShortBand = void 0;
+      } else if (probeNeedsScreenshotFrames(probeSession)) {
+        deParallelRouterEligible = false;
       }
     }
     const deProbeGateReason = isProbeDeGated(probeSession) ? probeSession.deGateReason : void 0;
@@ -13187,7 +13288,8 @@ async function executeRenderPipeline(input) {
       deParallelStreamForced
     );
     const deParallelStreamVerified = (deParallelStreamForced || process.env.HF_DE_PARALLEL_STREAM === "true") && useStreamingEncode && workerCount > 1;
-    if (shouldClampDefaultDrawElement({
+    const routeDropsScreenshotFrames = cfg.useDrawElement && probeNeedsScreenshotFrames(probeSession) && (!useStreamingEncode || workerCount !== 1);
+    if (routeDropsScreenshotFrames || shouldClampDefaultDrawElement({
       useDrawElement: cfg.useDrawElement,
       fastCaptureExplicitOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true",
       useStreamingEncode,
@@ -13861,7 +13963,8 @@ async function executeRenderPipeline(input) {
             abortSignal: executionSignal,
             assertNotAborted,
             onProgress,
-            onFrameLanded: (frame) => overlap?.onFrameLanded(frame)
+            onFrameLanded: (frame) => overlap?.onFrameLanded(frame),
+            interleaveFrames: overlap !== null
           })
         );
         let captureRes;

package/dist/regression-harness.d.ts

@@ -105,6 +105,54 @@ type CliOptions = {
      */
     mode: HarnessMode;
 };
+type TestResult = {
+    suite: TestSuite;
+    passed: boolean;
+    /**
+     * Set when `--mode=distributed-simulated` skips a fixture that the
+     * distributed pipeline can't run (HDR, NTSC fps, fps outside DISTRIBUTED_FPS).
+     * `passed` is `true` for skipped fixtures — skipping is a clean outcome,
+     * not a failure — but the summary distinguishes them.
+     */
+    skipped?: {
+        reason: string;
+    };
+    compilation?: {
+        passed: boolean;
+        errors: string[];
+        warnings: string[];
+    };
+    visual?: {
+        passed: boolean;
+        failedFrames: number;
+        checkpoints: Array<{
+            time: number;
+            psnr: number;
+            passed: boolean;
+        }>;
+    };
+    audio?: {
+        passed: boolean;
+        correlation: number;
+        lagWindows: number;
+        /**
+         * Residual Overall RMS (dBFS) of `rendered - snapshot`. Present only
+         * when the fixture opts in via `meta.maxAudioResidualRmsDb`.
+         * `Number.NEGATIVE_INFINITY` ⇒ perfect cancellation. `NaN` ⇒ residual
+         * check could not run (missing ffmpeg, duration mismatch, ...); see
+         * `audio.residualError` for the reason.
+         */
+        residualRmsDb?: number;
+        residualError?: string;
+    };
+    streamDurationParity?: {
+        passed: boolean;
+        videoDurationSeconds: number;
+        audioDurationSeconds: number;
+        driftSeconds: number;
+    };
+    renderedOutputPath?: string;
+};
 export declare function parseArgs(argv: string[]): CliOptions;
 export declare function discoverTestSuites(testsDir: string, filterNames: string[], excludeTags?: string[]): TestSuite[];
 /** The frame a checkpoint time samples. Shared so selection and lookup agree. */
@@ -154,4 +202,9 @@ export type StreamDurationParity = {
 };
 export declare function checkStreamDurationParity(videoPath: string): Promise<StreamDurationParity | null>;
 export declare function createRegressionTempRoot(suiteId: string, parent?: string): string;
+export declare function runTestSuite(suite: TestSuite, options: {
+    update: boolean;
+    keepTemp: boolean;
+    mode: HarnessMode;
+}): Promise<TestResult>;
 export {};

package/dist/services/distributed/chunkWeights.d.ts

@@ -9,6 +9,8 @@ export declare function planFrameWeights(input: {
     width: number;
     height: number;
 }): Float64Array;
+export declare function withChunkCaptureCost(slices: ChunkSliceJson[], weights: Float64Array): ChunkSliceJson[];
+export declare function effectiveChunkFrames(frames: number, captureCost?: number): number;
 /**
  * Cut `[0, weights.length)` into `chunkCount` ranges of ~equal summed weight, each within
  * `[minFrames, maxFrames]` where the frame count allows. `null` when the cost is uniform.

package/dist/services/htmlCompiler.d.ts

@@ -20,8 +20,6 @@ export interface CompiledComposition {
     hasShaderTransitions: boolean;
     /** Author HTML/CSS/scripts use a CSS 3D rendering context (pre-CDN-inline scan). */
     usesThreeDTransforms: boolean;
-    /** Author HTML/CSS use mix-blend-mode (pre-CDN-inline scan). */
-    usesMixBlendMode: boolean;
     /** Ancestors of the composition root carry a background-image (gradient/url). */
     hasAncestorBackgroundImage: boolean;
 }

package/dist/services/render/audioPadTrim.d.ts

@@ -124,6 +124,8 @@ export declare function constrainAacTruePeak(input: {
     targetDurationSeconds: number;
     signal?: AbortSignal;
     timeoutMs?: number;
+    probeTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
+    encodeAac?: AacEncoder;
 }): Promise<{
     success: boolean;
     error?: string;

package/dist/services/render/stages/captureStage.d.ts

@@ -84,6 +84,7 @@ export interface CaptureStageInput {
         endFrame: number;
     };
     onFrameLanded?: (frame: LandedFrame) => void;
+    interleaveFrames?: boolean;
 }
 export interface CaptureStageResult {
     /** Final worker count after any adaptive retry. */

package/dist/services/render/stages/compileStage.d.ts

@@ -101,7 +101,7 @@ export interface CompileStageResult {
      */
     forceScreenshot: boolean;
     /** Low-cardinality compile-time gate that disabled default drawElement:
-     * `3d` | `mix_blend_mode` | `shader_transitions`. Undefined when none fired. */
+     * `3d` | `ancestor_background_image` | `shader_transitions`. Undefined when none fired. */
     deCompileGate?: string;
 }
 export declare function runCompileStage(input: CompileStageInput): Promise<CompileStageResult>;

package/dist/services/render/stages/freezePlan.d.ts

@@ -87,6 +87,7 @@ export interface ChunkSliceJson {
     startFrame: number;
     /** Exclusive upper bound — chunk workers iterate frames in `[startFrame, endFrame)`. */
     endFrame: number;
+    captureCost?: number;
 }
 /**
  * Inputs to `freezePlan`. `planDir` already contains `compiled/`,

package/dist/services/renderMediaCollector.d.ts

@@ -6,6 +6,8 @@
  * and placed by the composition hosts it sits inside.
  */
 import { type VideoElement, type ImageElement, type AudioElement } from "@hyperframes/engine";
+/** Ids, as the parsers report them, of videos that are `data-hidden` or sit inside such an element. */
+export declare function collectHiddenVideoIds(html: string): Set<string>;
 export interface RenderMedia {
     videos: VideoElement[];
     audios: AudioElement[];