@hyperframes/producer 0.5.0-alpha.5 → 0.5.0-alpha.7

package/dist/public-server.js

@@ -103358,7 +103358,7 @@ var captionRules = [
       const hasHardKill = /\.set\s*\([^,]+,\s*\{[^}]*(?:visibility\s*:\s*["']hidden["']|opacity\s*:\s*0)/.test(
         content
       );
-      const hasCaptionLoop = /forEach|\.forEach\s*\(/.test(content) && /createElement|caption|group|cg-/.test(content);
+      const hasCaptionLoop = /forEach|\.forEach\s*\(/.test(content) && /karaoke|caption[-_]?(?:group|word|line|block)|cg-/.test(content);
       if (hasCaptionLoop && hasExitTween && !hasHardKill) {
         findings.push({
           code: "caption_exit_missing_hard_kill",
@@ -107053,6 +107053,7 @@ function calculateOptimalWorkers(totalFrames, requested, config2) {
   const effectiveCoresPerWorker = config2?.coresPerWorker ?? DEFAULT_CONFIG.coresPerWorker;
   const effectiveMinParallelFrames = config2?.minParallelFrames ?? DEFAULT_CONFIG.minParallelFrames;
   const effectiveLargeRenderThreshold = config2?.largeRenderThreshold ?? DEFAULT_CONFIG.largeRenderThreshold;
+  const captureCostMultiplier = Math.max(1, config2?.captureCostMultiplier ?? 1);
   if (requested !== void 0) {
     return Math.max(MIN_WORKERS, Math.min(effectiveMaxWorkers, requested));
   }
@@ -107065,8 +107066,14 @@ function calculateOptimalWorkers(totalFrames, requested, config2) {
   const optimal = Math.min(cpuBasedWorkers, memoryBasedWorkers, frameBasedWorkers);
   const minWorkersForJob = totalFrames >= effectiveMinParallelFrames ? 2 : MIN_WORKERS;
   let finalWorkers = Math.max(minWorkersForJob, Math.min(effectiveMaxWorkers, optimal));
-  if (totalFrames >= effectiveLargeRenderThreshold) {
-    const cpuScaledMax = Math.max(2, Math.floor(cpuCount / effectiveCoresPerWorker));
+  const weightedFrames = totalFrames * captureCostMultiplier;
+  const contentionThreshold = Math.max(
+    effectiveMinParallelFrames,
+    Math.floor(effectiveLargeRenderThreshold / 3)
+  );
+  if (totalFrames >= effectiveLargeRenderThreshold || weightedFrames >= contentionThreshold) {
+    const weightedCoresPerWorker = effectiveCoresPerWorker * captureCostMultiplier;
+    const cpuScaledMax = Math.max(MIN_WORKERS, Math.floor(cpuCount / weightedCoresPerWorker));
     if (finalWorkers > cpuScaledMax) {
       finalWorkers = cpuScaledMax;
     }
@@ -109588,6 +109595,18 @@ function detectRenderModeHints(html) {
     reasons
   };
 }
+var SHADER_TRANSITION_USAGE_PATTERN = /\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;
+function detectShaderTransitionUsage(html) {
+  let scriptMatch;
+  const scriptPattern = new RegExp(INLINE_SCRIPT_PATTERN.source, INLINE_SCRIPT_PATTERN.flags);
+  while ((scriptMatch = scriptPattern.exec(html)) !== null) {
+    const attrs = scriptMatch[1] || "";
+    if (/\bsrc\s*=/i.test(attrs)) continue;
+    const content = stripJsComments(stripCompilerMountBootstrap(scriptMatch[2] || ""));
+    if (SHADER_TRANSITION_USAGE_PATTERN.test(content)) return true;
+  }
+  return false;
+}
 async function resolveMediaDuration(src, mediaStart, baseDir, downloadDir, tagName19) {
   let filePath = src;
   if (isHttpUrl(src)) {
@@ -110124,6 +110143,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     "$1"
   );
   const renderModeHints = detectRenderModeHints(sanitizedHtml);
+  const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
   const coalescedHtml = await injectDeterministicFontFaces(
     coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml))
   );
@@ -110171,7 +110191,8 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     width,
     height,
     staticDuration,
-    renderModeHints
+    renderModeHints,
+    hasShaderTransitions
   };
 }
 async function discoverMediaFromBrowser(page) {
@@ -110273,7 +110294,8 @@ async function recompileWithResolutions(compiled, resolutions, projectDir, downl
     audios,
     images,
     unresolvedCompositions: remaining,
-    renderModeHints: compiled.renderModeHints
+    renderModeHints: compiled.renderModeHints,
+    hasShaderTransitions: compiled.hasShaderTransitions
   };
 }
 
@@ -110552,7 +110574,8 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
         mediaStart: a.mediaStart
       })),
       subCompositions: Array.from(compiled.subCompositions.keys()),
-      renderModeHints: compiled.renderModeHints
+      renderModeHints: compiled.renderModeHints,
+      hasShaderTransitions: compiled.hasShaderTransitions
     };
     writeFileSync5(join16(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   }
@@ -110565,6 +110588,290 @@ function applyRenderModeHints(cfg, compiled, log = defaultLogger) {
     reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
   });
 }
+function resolveRenderWorkerCount(totalFrames, requestedWorkers, cfg, compiled, composition, log = defaultLogger, measuredCaptureCost) {
+  const captureCost = combineCaptureCostEstimates(
+    estimateCaptureCostMultiplier(compiled, composition),
+    measuredCaptureCost
+  );
+  const workerCount = calculateOptimalWorkers(totalFrames, requestedWorkers, {
+    ...cfg,
+    captureCostMultiplier: captureCost.multiplier
+  });
+  if (requestedWorkers !== void 0 || captureCost.multiplier <= 1) {
+    return workerCount;
+  }
+  const baselineWorkers = calculateOptimalWorkers(totalFrames, void 0, cfg);
+  if (workerCount < baselineWorkers) {
+    log.warn(
+      "[Render] Reduced auto worker count for high-cost capture workload to avoid Chrome compositor starvation.",
+      {
+        from: baselineWorkers,
+        to: workerCount,
+        costMultiplier: captureCost.multiplier,
+        reasons: captureCost.reasons
+      }
+    );
+  }
+  return workerCount;
+}
+function estimateCaptureCostMultiplier(compiled, composition) {
+  let multiplier = 1;
+  const reasons = [];
+  if (compiled.hasShaderTransitions) {
+    multiplier += 2;
+    reasons.push("shader-transitions");
+  }
+  const reasonCodes = new Set(compiled.renderModeHints.reasons.map((reason) => reason.code));
+  if (reasonCodes.has("requestAnimationFrame")) {
+    multiplier += 1;
+    reasons.push("requestAnimationFrame");
+  }
+  if (reasonCodes.has("iframe")) {
+    multiplier += 0.5;
+    reasons.push("iframe");
+  }
+  if (composition.videos.length > 0) {
+    multiplier += Math.min(2, composition.videos.length * 0.75);
+    reasons.push(`${composition.videos.length} video${composition.videos.length === 1 ? "" : "s"}`);
+  }
+  if (composition.audios.length > 0) {
+    multiplier += Math.min(1, composition.audios.length * 0.75);
+    reasons.push(`${composition.audios.length} audio${composition.audios.length === 1 ? "" : "s"}`);
+  }
+  return {
+    multiplier: Math.round(multiplier * 100) / 100,
+    reasons
+  };
+}
+function combineCaptureCostEstimates(staticCost, measuredCost) {
+  if (!measuredCost || measuredCost.multiplier <= 1) return staticCost;
+  if (staticCost.multiplier >= measuredCost.multiplier) {
+    return {
+      multiplier: staticCost.multiplier,
+      reasons: [...staticCost.reasons, ...measuredCost.reasons],
+      p95Ms: measuredCost.p95Ms
+    };
+  }
+  return {
+    multiplier: measuredCost.multiplier,
+    reasons: [...measuredCost.reasons, ...staticCost.reasons],
+    p95Ms: measuredCost.p95Ms
+  };
+}
+var CAPTURE_CALIBRATION_TARGET_MS = 600;
+var MAX_MEASURED_CAPTURE_COST_MULTIPLIER = 8;
+var CAPTURE_CALIBRATION_PROTOCOL_TIMEOUT_MS = 3e4;
+function createCaptureCalibrationConfig(cfg) {
+  return {
+    ...cfg,
+    protocolTimeout: Math.min(cfg.protocolTimeout, CAPTURE_CALIBRATION_PROTOCOL_TIMEOUT_MS)
+  };
+}
+function estimateMeasuredCaptureCostMultiplier(samples) {
+  if (samples.length === 0) {
+    return { multiplier: 1, reasons: [] };
+  }
+  const sorted = [...samples].sort((a, b) => a.captureTimeMs - b.captureTimeMs);
+  const p95Index = Math.max(0, Math.ceil(sorted.length * 0.95) - 1);
+  const p95Sample = sorted[p95Index] ?? sorted[sorted.length - 1];
+  if (!p95Sample) {
+    return { multiplier: 1, reasons: [] };
+  }
+  const p95Ms = Math.round(p95Sample.captureTimeMs);
+  const multiplier = Math.min(
+    MAX_MEASURED_CAPTURE_COST_MULTIPLIER,
+    Math.max(1, Math.round(p95Ms / CAPTURE_CALIBRATION_TARGET_MS * 100) / 100)
+  );
+  return {
+    multiplier,
+    reasons: multiplier > 1 ? [`calibration-p95=${p95Ms}ms`] : [],
+    p95Ms
+  };
+}
+function selectCaptureCalibrationFrames(totalFrames) {
+  if (totalFrames <= 0) return [];
+  const lastFrame = totalFrames - 1;
+  const candidates = [
+    0,
+    Math.floor(totalFrames * 0.25),
+    Math.floor(totalFrames * 0.5),
+    Math.floor(totalFrames * 0.75),
+    lastFrame
+  ];
+  return Array.from(
+    new Set(candidates.map((frame) => Math.max(0, Math.min(lastFrame, frame))))
+  ).sort((a, b) => a - b);
+}
+function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
+  const ranges = [];
+  let rangeStart = null;
+  for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
+    const framePath = join16(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    const missing = !existsSync16(framePath);
+    if (missing && rangeStart === null) {
+      rangeStart = frameIndex;
+    } else if (!missing && rangeStart !== null) {
+      ranges.push({ startFrame: rangeStart, endFrame: frameIndex });
+      rangeStart = null;
+    }
+  }
+  if (rangeStart !== null) {
+    ranges.push({ startFrame: rangeStart, endFrame: totalFrames });
+  }
+  return ranges;
+}
+function buildMissingFrameRetryBatches(ranges, maxWorkers, workDir, attempt) {
+  const workersPerBatch = Math.max(1, Math.floor(maxWorkers));
+  const 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: range.startFrame,
+      endFrame: range.endFrame,
+      outputDir: join16(workDir, `retry-${attempt}-batch-${batchIndex}-worker-${workerId}`)
+    }));
+    batches.push(batch);
+  }
+  return batches;
+}
+function getNextRetryWorkerCount(currentWorkers) {
+  return Math.max(1, Math.floor(currentWorkers / 2));
+}
+function isRecoverableParallelCaptureError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return message.includes("[Parallel] Capture failed") && /Runtime\.callFunctionOn timed out|HeadlessExperimental\.beginFrame timed out|Waiting failed|timeout exceeded|timed out|Navigation timeout|Protocol error|Target closed/i.test(
+    message
+  );
+}
+function shouldFallbackToScreenshotAfterCalibrationError(error) {
+  const message = error instanceof Error ? error.message : String(error);
+  return /HeadlessExperimental\.beginFrame timed out|beginFrame probe timeout|Another frame is pending|Frame still pending|Protocol error.*HeadlessExperimental\.beginFrame/i.test(
+    message
+  );
+}
+function countCapturedFrames(totalFrames, framesDir, frameExt) {
+  let captured = 0;
+  for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
+    const framePath = join16(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    if (existsSync16(framePath)) captured++;
+  }
+  return captured;
+}
+function countFrameRanges(ranges) {
+  return ranges.reduce((sum, range) => sum + (range.endFrame - range.startFrame), 0);
+}
+async function measureCaptureCostFromSession(session, totalFrames, fps) {
+  const sampledFrames = selectCaptureCalibrationFrames(totalFrames);
+  const samples = [];
+  for (const frameIndex of sampledFrames) {
+    const time = frameIndex / fps;
+    const startedAt = Date.now();
+    const result = await captureFrameToBuffer(session, frameIndex, time);
+    samples.push({
+      frameIndex,
+      captureTimeMs: result.captureTimeMs || Date.now() - startedAt
+    });
+  }
+  return {
+    estimate: estimateMeasuredCaptureCostMultiplier(samples),
+    samples
+  };
+}
+async function executeDiskCaptureWithAdaptiveRetry(options) {
+  const attempts = [];
+  let currentWorkers = options.initialWorkerCount;
+  let missingRanges = null;
+  let attempt = 0;
+  while (true) {
+    const frameCount = missingRanges ? countFrameRanges(missingRanges) : options.totalFrames;
+    attempts.push({
+      attempt,
+      workers: currentWorkers,
+      frameCount,
+      reason: attempt === 0 ? "initial" : "retry"
+    });
+    const attemptWorkDir = join16(options.workDir, `capture-attempt-${attempt}`);
+    const batches = missingRanges ? buildMissingFrameRetryBatches(missingRanges, currentWorkers, attemptWorkDir, attempt) : [distributeFrames(options.totalFrames, currentWorkers, attemptWorkDir)];
+    try {
+      for (const tasks of batches) {
+        const capturedBeforeBatch = countCapturedFrames(
+          options.totalFrames,
+          options.framesDir,
+          options.frameExt
+        );
+        try {
+          await executeParallelCapture(
+            options.serverUrl,
+            attemptWorkDir,
+            tasks,
+            options.captureOptions,
+            options.createBeforeCaptureHook,
+            options.abortSignal,
+            options.onProgress ? (progress) => {
+              options.onProgress?.({
+                ...progress,
+                totalFrames: options.totalFrames,
+                capturedFrames: Math.min(
+                  options.totalFrames,
+                  capturedBeforeBatch + progress.capturedFrames
+                )
+              });
+            } : void 0,
+            void 0,
+            options.cfg
+          );
+        } finally {
+          await mergeWorkerFrames(attemptWorkDir, tasks, options.framesDir);
+        }
+      }
+      const remaining = findMissingFrameRanges(
+        options.totalFrames,
+        options.framesDir,
+        options.frameExt
+      );
+      if (remaining.length === 0) {
+        return attempts;
+      }
+      if (!options.allowRetry || currentWorkers <= 1) {
+        throw new Error(
+          `[Render] Capture completed but ${countFrameRanges(remaining)} frame(s) are missing`
+        );
+      }
+      const nextWorkers = getNextRetryWorkerCount(currentWorkers);
+      options.log.warn("[Render] Retrying missing captured frames with fewer workers.", {
+        fromWorkers: currentWorkers,
+        toWorkers: nextWorkers,
+        missingFrames: countFrameRanges(remaining)
+      });
+      currentWorkers = nextWorkers;
+      missingRanges = remaining;
+      attempt++;
+    } catch (error) {
+      const remaining = findMissingFrameRanges(
+        options.totalFrames,
+        options.framesDir,
+        options.frameExt
+      );
+      if (remaining.length === 0) {
+        return attempts;
+      }
+      if (!options.allowRetry || currentWorkers <= 1 || !isRecoverableParallelCaptureError(error)) {
+        throw error;
+      }
+      const nextWorkers = getNextRetryWorkerCount(currentWorkers);
+      options.log.warn("[Render] Parallel capture timed out; retrying missing frames.", {
+        fromWorkers: currentWorkers,
+        toWorkers: nextWorkers,
+        missingFrames: countFrameRanges(remaining),
+        error: error instanceof Error ? error.message : String(error)
+      });
+      currentWorkers = nextWorkers;
+      missingRanges = remaining;
+      attempt++;
+    }
+  }
+}
 function blitHdrVideoLayer(canvas, el, time, fps, hdrFrameDirs, hdrStartTimes, width, height, log, sourceTransfer, targetTransfer) {
   const frameDir = hdrFrameDirs.get(el.id);
   const startTime = hdrStartTimes.get(el.id);
@@ -111191,7 +111498,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     let extractionResult = null;
     const nativeHdrVideoIds = /* @__PURE__ */ new Set();
     const videoTransfers = /* @__PURE__ */ new Map();
-    if (job.config.hdr && composition.videos.length > 0) {
+    if (job.config.hdrMode !== "force-sdr" && composition.videos.length > 0) {
       await Promise.all(
         composition.videos.map(async (v) => {
           let videoPath = v.src;
@@ -111212,7 +111519,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     const imageTransfers = /* @__PURE__ */ new Map();
     const hdrImageSrcPaths = /* @__PURE__ */ new Map();
     const imageColorSpaces = [];
-    if (job.config.hdr && composition.images.length > 0) {
+    if (job.config.hdrMode !== "force-sdr" && composition.images.length > 0) {
       const probed = await Promise.all(
         composition.images.map(async (img) => {
           let imgPath = img.src;
@@ -111269,28 +111576,53 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       perfStages.videoExtractMs = Date.now() - stage2Start;
     }
     let effectiveHdr;
-    if (job.config.hdr) {
+    let forcedHdrWithoutSources = false;
+    {
+      const hdrMode = job.config.hdrMode ?? "auto";
       const videoColorSpaces = (extractionResult?.extracted ?? []).map(
         (ext) => ext.metadata.colorSpace
       );
       const allColorSpaces = [...videoColorSpaces, ...imageColorSpaces];
-      if (allColorSpaces.length > 0) {
-        const info = analyzeCompositionHdr(allColorSpaces);
-        if (info.hasHdr && info.dominantTransfer) {
+      const info = allColorSpaces.length > 0 ? analyzeCompositionHdr(allColorSpaces) : null;
+      if (hdrMode === "force-sdr") {
+        effectiveHdr = void 0;
+      } else if (hdrMode === "force-hdr") {
+        if (info?.hasHdr && info.dominantTransfer) {
+          effectiveHdr = { transfer: info.dominantTransfer };
+        } else {
+          effectiveHdr = { transfer: "hlg" };
+          forcedHdrWithoutSources = true;
+        }
+      } else {
+        if (info?.hasHdr && info.dominantTransfer) {
           effectiveHdr = { transfer: info.dominantTransfer };
         }
       }
     }
     if (effectiveHdr && outputFormat !== "mp4") {
+      const hdrSourceReason = forcedHdrWithoutSources ? "HDR was forced without detected HDR sources" : "HDR source detected";
       log.warn(
-        `[Render] HDR source detected but format is "${outputFormat}" \u2014 falling back to SDR. HDR + alpha is not supported. Use --format mp4 for HDR10 output.`
+        `[Render] ${hdrSourceReason}, but format is "${outputFormat}" \u2014 falling back to SDR. HDR + alpha is not supported. Use --format mp4 for HDR10 output.`
       );
       effectiveHdr = void 0;
     }
-    if (effectiveHdr) {
-      log.info(
-        `[Render] HDR source detected \u2014 output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
-      );
+    {
+      const hdrMode = job.config.hdrMode ?? "auto";
+      if (forcedHdrWithoutSources) {
+        log.warn(
+          "[Render] HDR forced by --hdr flag, but no HDR sources were detected \u2014 defaulting to HLG. SDR-only compositions may look perceptually wrong on HDR displays."
+        );
+      }
+      if (effectiveHdr) {
+        const reason = hdrMode === "force-hdr" ? forcedHdrWithoutSources ? "forced by --hdr flag (no HDR sources detected \u2014 defaulting to HLG)" : "forced by --hdr flag" : "auto-detected from source(s)";
+        log.info(
+          `[Render] HDR ${reason} \u2014 output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
+        );
+      } else if (hdrMode === "force-sdr") {
+        log.info("[Render] SDR forced by --sdr flag");
+      } else {
+        log.info("[Render] No HDR sources detected \u2014 rendering SDR");
+      }
     }
     const stage3Start = Date.now();
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress);
@@ -111337,7 +111669,101 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       ...captureOptions,
       skipReadinessVideoIds: Array.from(nativeHdrVideoIds)
     });
-    const workerCount = calculateOptimalWorkers(totalFrames, job.config.workers, cfg);
+    let captureCalibration;
+    let switchedToScreenshotAfterCalibration = false;
+    if (job.config.workers === void 0 && totalFrames >= 60) {
+      const calibrationDir = join16(workDir, "capture-calibration");
+      const calibrationCfg = createCaptureCalibrationConfig(cfg);
+      const videoInjector = createVideoFrameInjector(frameLookup);
+      let calibrationSession = null;
+      try {
+        calibrationSession = await createCaptureSession(
+          fileServer.url,
+          calibrationDir,
+          buildHdrCaptureOptions(),
+          videoInjector,
+          calibrationCfg
+        );
+        if (!calibrationSession.isInitialized) {
+          await initializeSession(calibrationSession);
+        }
+        assertNotAborted();
+        captureCalibration = await measureCaptureCostFromSession(
+          calibrationSession,
+          totalFrames,
+          job.config.fps
+        );
+        if (captureCalibration.estimate.multiplier > 1) {
+          log.warn("[Render] Measured slow frame capture during auto-worker calibration.", {
+            multiplier: captureCalibration.estimate.multiplier,
+            p95Ms: captureCalibration.estimate.p95Ms,
+            sampledFrames: captureCalibration.samples.map((sample) => sample.frameIndex)
+          });
+        } else {
+          log.debug("[Render] Auto-worker calibration kept baseline capture cost.", {
+            p95Ms: captureCalibration.estimate.p95Ms,
+            sampledFrames: captureCalibration.samples.map((sample) => sample.frameIndex)
+          });
+        }
+      } catch (error) {
+        const shouldFallbackToScreenshot = !cfg.forceScreenshot && shouldFallbackToScreenshotAfterCalibrationError(error);
+        if (shouldFallbackToScreenshot) {
+          cfg.forceScreenshot = true;
+          switchedToScreenshotAfterCalibration = true;
+          if (probeSession) {
+            lastBrowserConsole = probeSession.browserConsoleBuffer;
+            await closeCaptureSession(probeSession).catch(() => {
+            });
+            probeSession = null;
+          }
+        }
+        captureCalibration = {
+          estimate: {
+            multiplier: MAX_MEASURED_CAPTURE_COST_MULTIPLIER,
+            reasons: shouldFallbackToScreenshot ? ["calibration-beginframe-timeout", "screenshot-fallback"] : ["calibration-failed"]
+          },
+          samples: []
+        };
+        if (shouldFallbackToScreenshot) {
+          log.warn(
+            "[Render] BeginFrame auto-worker calibration timed out; falling back to screenshot capture mode.",
+            {
+              protocolTimeout: calibrationCfg.protocolTimeout,
+              error: error instanceof Error ? error.message : String(error)
+            }
+          );
+        } else {
+          log.warn("[Render] Auto-worker calibration failed; using conservative worker budget.", {
+            protocolTimeout: calibrationCfg.protocolTimeout,
+            error: error instanceof Error ? error.message : String(error)
+          });
+        }
+      } finally {
+        if (calibrationSession) {
+          lastBrowserConsole = calibrationSession.browserConsoleBuffer;
+          await closeCaptureSession(calibrationSession).catch(() => {
+          });
+        }
+      }
+    }
+    let workerCount = resolveRenderWorkerCount(
+      totalFrames,
+      job.config.workers,
+      cfg,
+      compiled,
+      composition,
+      log,
+      captureCalibration?.estimate
+    );
+    if (switchedToScreenshotAfterCalibration && workerCount > 1) {
+      workerCount = 1;
+    }
+    if (workerCount > 1 && probeSession) {
+      lastBrowserConsole = probeSession.browserConsoleBuffer;
+      await closeCaptureSession(probeSession);
+      probeSession = null;
+    }
+    const captureAttempts = [];
     const FORMAT_EXT = {
       mp4: ".mp4",
       webm: ".webm",
@@ -111929,15 +112355,18 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
           perfStages.encodeMs = encodeResult.durationMs;
         } else {
           if (workerCount > 1) {
-            const tasks = distributeFrames(job.totalFrames, workerCount, workDir);
-            await executeParallelCapture(
-              fileServer.url,
+            const attempts = await executeDiskCaptureWithAdaptiveRetry({
+              serverUrl: fileServer.url,
               workDir,
-              tasks,
-              buildHdrCaptureOptions(),
-              () => createVideoFrameInjector(frameLookup),
+              framesDir,
+              totalFrames: job.totalFrames,
+              initialWorkerCount: workerCount,
+              allowRetry: job.config.workers === void 0,
+              frameExt: needsAlpha ? "png" : "jpg",
+              captureOptions: buildHdrCaptureOptions(),
+              createBeforeCaptureHook: () => createVideoFrameInjector(frameLookup),
               abortSignal,
-              (progress) => {
+              onProgress: (progress) => {
                 job.framesRendered = progress.capturedFrames;
                 const frameProgress = progress.capturedFrames / progress.totalFrames;
                 const progressPct = 25 + frameProgress * 45;
@@ -111945,16 +112374,20 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
                   updateJobStatus(
                     job,
                     "rendering",
-                    `Capturing frame ${progress.capturedFrames}/${progress.totalFrames} (${workerCount} workers)`,
+                    `Capturing frame ${progress.capturedFrames}/${progress.totalFrames} (${progress.activeWorkers} workers)`,
                     Math.round(progressPct),
                     onProgress
                   );
                 }
               },
-              void 0,
-              cfg
-            );
-            await mergeWorkerFrames(workDir, tasks, framesDir);
+              cfg,
+              log
+            });
+            captureAttempts.push(...attempts);
+            const lastAttempt = attempts[attempts.length - 1];
+            if (lastAttempt) {
+              workerCount = lastAttempt.workers;
+            }
             if (probeSession) {
               lastBrowserConsole = probeSession.browserConsoleBuffer;
               await closeCaptureSession(probeSession);
@@ -112124,6 +112557,13 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
       stages: perfStages,
       videoExtractBreakdown: extractionResult?.phaseBreakdown,
       tmpPeakBytes,
+      captureCalibration: captureCalibration ? {
+        sampledFrames: captureCalibration.samples.map((sample) => sample.frameIndex),
+        p95Ms: captureCalibration.estimate.p95Ms,
+        multiplier: captureCalibration.estimate.multiplier,
+        reasons: captureCalibration.estimate.reasons
+      } : void 0,
+      captureAttempts: captureAttempts.length > 0 ? captureAttempts : void 0,
       hdrDiagnostics: hdrDiagnostics.videoExtractionFailures > 0 || hdrDiagnostics.imageDecodeFailures > 0 ? { ...hdrDiagnostics } : void 0,
       captureAvgMs: totalFrames > 0 ? Math.round((perfStages.captureMs ?? 0) / totalFrames) : void 0,
       peakRssMb: Math.round(peakRssBytes / (1024 * 1024)),