hyperframes 0.5.0-alpha.6 → 0.5.0-alpha.7

package/dist/cli.js

@@ -54,7 +54,7 @@ var VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    VERSION = true ? "0.5.0-alpha.6" : "0.0.0-dev";
+    VERSION = true ? "0.5.0-alpha.7" : "0.0.0-dev";
   }
 });
 
@@ -9490,9 +9490,12 @@ function readCache(path2) {
   }
 }
 function writeCache(path2, data) {
-  mkdirSync(dirname3(path2), { recursive: true });
-  const entry = { fetchedAt: Date.now(), data };
-  writeFileSync(path2, JSON.stringify(entry), "utf-8");
+  try {
+    mkdirSync(dirname3(path2), { recursive: true });
+    const entry = { fetchedAt: Date.now(), data };
+    writeFileSync(path2, JSON.stringify(entry), "utf-8");
+  } catch {
+  }
 }
 async function fetchJson(url) {
   const res = await fetch(url, { signal: AbortSignal.timeout(FETCH_TIMEOUT_MS) });
@@ -29126,6 +29129,7 @@ function calculateOptimalWorkers(totalFrames, requested, config) {
   const effectiveCoresPerWorker = config?.coresPerWorker ?? DEFAULT_CONFIG2.coresPerWorker;
   const effectiveMinParallelFrames = config?.minParallelFrames ?? DEFAULT_CONFIG2.minParallelFrames;
   const effectiveLargeRenderThreshold = config?.largeRenderThreshold ?? DEFAULT_CONFIG2.largeRenderThreshold;
+  const captureCostMultiplier = Math.max(1, config?.captureCostMultiplier ?? 1);
   if (requested !== void 0) {
     return Math.max(MIN_WORKERS, Math.min(effectiveMaxWorkers, requested));
   }
@@ -29138,8 +29142,14 @@ function calculateOptimalWorkers(totalFrames, requested, config) {
   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;
     }
@@ -32899,6 +32909,17 @@ function detectRenderModeHints(html) {
     reasons
   };
 }
+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)) {
@@ -33435,6 +33456,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     "$1"
   );
   const renderModeHints = detectRenderModeHints(sanitizedHtml);
+  const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
   const coalescedHtml = await injectDeterministicFontFaces(
     coalesceHeadStylesAndBodyScripts2(promoteCssImportsToLinkTags(sanitizedHtml))
   );
@@ -33482,7 +33504,8 @@ async function compileForRender(projectDir, htmlPath, downloadDir) {
     width,
     height,
     staticDuration,
-    renderModeHints
+    renderModeHints,
+    hasShaderTransitions
   };
 }
 async function discoverMediaFromBrowser(page) {
@@ -33584,10 +33607,11 @@ async function recompileWithResolutions(compiled, resolutions, projectDir, downl
     audios,
     images,
     unresolvedCompositions: remaining,
-    renderModeHints: compiled.renderModeHints
+    renderModeHints: compiled.renderModeHints,
+    hasShaderTransitions: compiled.hasShaderTransitions
   };
 }
-var INLINE_SCRIPT_PATTERN, COMPILER_MOUNT_BLOCK_START, COMPILER_MOUNT_BLOCK_END;
+var INLINE_SCRIPT_PATTERN, COMPILER_MOUNT_BLOCK_START, COMPILER_MOUNT_BLOCK_END, SHADER_TRANSITION_USAGE_PATTERN;
 var init_htmlCompiler2 = __esm({
   "../producer/src/services/htmlCompiler.ts"() {
     "use strict";
@@ -33602,6 +33626,7 @@ var init_htmlCompiler2 = __esm({
     INLINE_SCRIPT_PATTERN = /<script\b([^>]*)>([\s\S]*?)<\/script>/gi;
     COMPILER_MOUNT_BLOCK_START = "/* __HF_COMPILER_MOUNT_START__ */";
     COMPILER_MOUNT_BLOCK_END = "/* __HF_COMPILER_MOUNT_END__ */";
+    SHADER_TRANSITION_USAGE_PATTERN = /\b(?:(?:window|globalThis)\s*\.\s*)?HyperShader\s*\.\s*init\s*\(|\b__hf\s*\.\s*transitions\s*=/;
   }
 });
 
@@ -33905,7 +33930,8 @@ function writeCompiledArtifacts(compiled, workDir, includeSummary) {
         mediaStart: a.mediaStart
       })),
       subCompositions: Array.from(compiled.subCompositions.keys()),
-      renderModeHints: compiled.renderModeHints
+      renderModeHints: compiled.renderModeHints,
+      hasShaderTransitions: compiled.hasShaderTransitions
     };
     writeFileSync14(join36(compileDir, "summary.json"), JSON.stringify(summary, null, 2), "utf-8");
   }
@@ -33918,6 +33944,287 @@ function applyRenderModeHints(cfg, compiled, log2 = defaultLogger) {
     reasons: compiled.renderModeHints.reasons.map((reason) => reason.message)
   });
 }
+function resolveRenderWorkerCount(totalFrames, requestedWorkers, cfg, compiled, composition, log2 = 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) {
+    log2.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
+  };
+}
+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 = join36(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    const missing = !existsSync34(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 i2 = 0; i2 < ranges.length; i2 += workersPerBatch) {
+    const batchIndex = batches.length;
+    const batch = ranges.slice(i2, i2 + workersPerBatch).map((range, workerId) => ({
+      workerId,
+      startFrame: range.startFrame,
+      endFrame: range.endFrame,
+      outputDir: join36(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 = join36(framesDir, `frame_${String(frameIndex).padStart(6, "0")}.${frameExt}`);
+    if (existsSync34(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 = join36(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, log2, sourceTransfer, targetTransfer) {
   const frameDir = hdrFrameDirs.get(el.id);
   const startTime = hdrStartTimes.get(el.id);
@@ -34544,7 +34851,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;
@@ -34565,7 +34872,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;
@@ -34622,28 +34929,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";
       log2.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) {
-      log2.info(
-        `[Render] HDR source detected \u2014 output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
-      );
+    {
+      const hdrMode = job.config.hdrMode ?? "auto";
+      if (forcedHdrWithoutSources) {
+        log2.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)";
+        log2.info(
+          `[Render] HDR ${reason} \u2014 output: ${effectiveHdr.transfer.toUpperCase()} (BT.2020, 10-bit H.265)`
+        );
+      } else if (hdrMode === "force-sdr") {
+        log2.info("[Render] SDR forced by --sdr flag");
+      } else {
+        log2.info("[Render] No HDR sources detected \u2014 rendering SDR");
+      }
     }
     const stage3Start = Date.now();
     updateJobStatus(job, "preprocessing", "Processing audio tracks", 20, onProgress);
@@ -34690,7 +35022,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 = join36(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) {
+          log2.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 {
+          log2.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) {
+          log2.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 {
+          log2.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,
+      log2,
+      captureCalibration?.estimate
+    );
+    if (switchedToScreenshotAfterCalibration && workerCount > 1) {
+      workerCount = 1;
+    }
+    if (workerCount > 1 && probeSession) {
+      lastBrowserConsole = probeSession.browserConsoleBuffer;
+      await closeCaptureSession(probeSession);
+      probeSession = null;
+    }
+    const captureAttempts = [];
     const FORMAT_EXT2 = {
       mp4: ".mp4",
       webm: ".webm",
@@ -35282,15 +35708,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;
@@ -35298,16 +35727,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: log2
+            });
+            captureAttempts.push(...attempts);
+            const lastAttempt = attempts[attempts.length - 1];
+            if (lastAttempt) {
+              workerCount = lastAttempt.workers;
+            }
             if (probeSession) {
               lastBrowserConsole = probeSession.browserConsoleBuffer;
               await closeCaptureSession(probeSession);
@@ -35477,6 +35910,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)),
@@ -35592,7 +36032,7 @@ async function executeRenderJob(job, projectDir, outputPath, onProgress, abortSi
     clearInterval(memSamplerInterval);
   }
 }
-var RenderCancelledError, BROWSER_MEDIA_EPSILON;
+var RenderCancelledError, BROWSER_MEDIA_EPSILON, CAPTURE_CALIBRATION_TARGET_MS, MAX_MEASURED_CAPTURE_COST_MULTIPLIER, CAPTURE_CALIBRATION_PROTOCOL_TIMEOUT_MS;
 var init_renderOrchestrator = __esm({
   "../producer/src/services/renderOrchestrator.ts"() {
     "use strict";
@@ -35613,6 +36053,9 @@ var init_renderOrchestrator = __esm({
       }
     };
     BROWSER_MEDIA_EPSILON = 1e-4;
+    CAPTURE_CALIBRATION_TARGET_MS = 600;
+    MAX_MEASURED_CAPTURE_COST_MULTIPLIER = 8;
+    CAPTURE_CALIBRATION_PROTOCOL_TIMEOUT_MS = 3e4;
   }
 });
 
@@ -38645,13 +39088,13 @@ function buildDockerRunArgs(input) {
     options.quality,
     "--format",
     options.format,
-    "--workers",
-    String(options.workers),
+    ...options.workers != null ? ["--workers", String(options.workers)] : [],
     ...options.crf != null ? ["--crf", String(options.crf)] : [],
     ...options.videoBitrate ? ["--video-bitrate", options.videoBitrate] : [],
     ...options.quiet ? ["--quiet"] : [],
     ...options.gpu ? ["--gpu"] : [],
-    ...options.hdr ? ["--hdr"] : []
+    ...options.hdrMode === "force-hdr" ? ["--hdr"] : [],
+    ...options.hdrMode === "force-sdr" ? ["--sdr"] : []
   ];
 }
 var init_dockerRunArgs = __esm({
@@ -38707,9 +39150,6 @@ import { mkdirSync as mkdirSync24, readFileSync as readFileSync29, statSync as s
 import { cpus as cpus3, freemem as freemem3, tmpdir as tmpdir4 } from "os";
 import { resolve as resolve28, dirname as dirname16, join as join44, basename as basename9 } from "path";
 import { execFileSync as execFileSync6, spawn as spawn11 } from "child_process";
-function defaultWorkerCount() {
-  return Math.max(1, Math.min(Math.floor(CPU_CORE_COUNT * 3 / 4), 8));
-}
 function dockerImageTag(version) {
   return `${DOCKER_IMAGE_PREFIX}:${version}`;
 }
@@ -38801,7 +39241,7 @@ async function renderDocker(projectDir, outputPath, options) {
       format: options.format,
       workers: options.workers,
       gpu: options.gpu,
-      hdr: options.hdr,
+      hdrMode: options.hdrMode,
       crf: options.crf,
       videoBitrate: options.videoBitrate,
       quiet: options.quiet
@@ -38850,7 +39290,7 @@ async function renderLocal(projectDir, outputPath, options) {
     format: options.format,
     workers: options.workers,
     useGpu: options.gpu,
-    hdr: options.hdr,
+    hdrMode: options.hdrMode,
     crf: options.crf,
     videoBitrate: options.videoBitrate
   });
@@ -38897,7 +39337,7 @@ function trackRenderMetrics(job, elapsedMs, options, docker) {
     durationMs: elapsedMs,
     fps: options.fps,
     quality: options.quality,
-    workers: options.workers,
+    workers: options.workers ?? perf?.workers,
     docker,
     gpu: options.gpu,
     compositionDurationMs,
@@ -38963,7 +39403,7 @@ var init_render2 = __esm({
       ["High quality at 60fps", "hyperframes render --fps 60 --quality high --output hd.mp4"],
       ["Deterministic render via Docker", "hyperframes render --docker --output deterministic.mp4"],
       ["Parallel rendering with 6 workers", "hyperframes render --workers 6 --output fast.mp4"],
-      ["HDR output (H.265 10-bit)", "hyperframes render --hdr --output hdr-output.mp4"]
+      ["HDR output (auto-detected)", "hyperframes render --output hdr-output.mp4"]
     ];
     VALID_FPS = /* @__PURE__ */ new Set([24, 30, 60]);
     VALID_QUALITY = /* @__PURE__ */ new Set(["draft", "standard", "high"]);
@@ -39015,7 +39455,12 @@ var init_render2 = __esm({
         },
         hdr: {
           type: "boolean",
-          description: "Enable HDR: probe sources for PQ/HLG, output H.265 10-bit BT.2020",
+          description: "Force HDR output even if no HDR sources are detected",
+          default: false
+        },
+        sdr: {
+          type: "boolean",
+          description: "Force SDR output even if HDR sources are detected",
           default: false
         },
         crf: {
@@ -39121,9 +39566,8 @@ var init_render2 = __esm({
           );
           process.exit(1);
         }
-        const workerCount = workers ?? defaultWorkerCount();
         if (!quiet) {
-          const workerLabel = args.workers != null ? `${workerCount} workers` : `${workerCount} workers (auto \u2014 ${CPU_CORE_COUNT} cores detected)`;
+          const workerLabel = workers != null ? `${workers} workers` : `auto workers (${CPU_CORE_COUNT} cores detected)`;
           console.log("");
           console.log(
             c.accent("\u25C6") + "  Rendering " + c.accent(project.name) + c.dim(" \u2192 " + outputPath)
@@ -39191,14 +39635,18 @@ var init_render2 = __esm({
             console.log("");
           }
         }
+        if (args.hdr && args.sdr) {
+          console.error("Error: --hdr and --sdr are mutually exclusive.");
+          process.exit(1);
+        }
         if (useDocker) {
           await renderDocker(project.dir, outputPath, {
             fps,
             quality,
             format,
-            workers: workerCount,
+            workers,
             gpu: useGpu,
-            hdr: args.hdr ?? false,
+            hdrMode: args.sdr ? "force-sdr" : args.hdr ? "force-hdr" : "auto",
             crf,
             videoBitrate,
             quiet
@@ -39208,9 +39656,9 @@ var init_render2 = __esm({
             fps,
             quality,
             format,
-            workers: workerCount,
+            workers,
             gpu: useGpu,
-            hdr: args.hdr ?? false,
+            hdrMode: args.sdr ? "force-sdr" : args.hdr ? "force-hdr" : "auto",
             crf,
             videoBitrate,
             quiet,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hyperframes",
-  "version": "0.5.0-alpha.6",
+  "version": "0.5.0-alpha.7",
   "description": "HyperFrames CLI — create, preview, and render HTML video compositions",
   "repository": {
     "type": "git",
@@ -55,7 +55,7 @@
     "vitest": "^3.2.4"
   },
   "optionalDependencies": {
-    "@google/genai": "^1.50.0"
+    "@google/genai": "^1.50.1"
   },
   "engines": {
     "node": ">=22"