@hyperframes/producer 0.8.206 → 0.8.208

package/dist/public-server.js

@@ -7,7 +7,7 @@ import {
   statSync as statSync10,
   mkdtempSync as mkdtempSync4,
   writeFileSync as writeFileSync7,
-  rmSync as rmSync13,
+  rmSync as rmSync11,
   createReadStream as createReadStream3
 } from "node:fs";
 import { resolve as resolve10, dirname as dirname13, join as join31 } from "node:path";
@@ -26,7 +26,7 @@ import {
   mkdirSync as mkdirSync10,
   readFileSync as readFileSync9,
   readdirSync as readdirSync5,
-  rmSync as rmSync12,
+  rmSync as rmSync10,
   statSync as statSync8,
   writeFileSync as writeFileSync6,
   copyFileSync as copyFileSync5,
@@ -35,7 +35,7 @@ import {
 import { tmpdir as tmpdir2 } from "node:os";
 import {
   chainCapture,
-  fpsToNumber as fpsToNumber9,
+  fpsToNumber as fpsToNumber8,
   HF_COLOR_GRADING_ATTR,
   HF_VFX_ATTR,
   parseVfxChain,
@@ -831,7 +831,7 @@ function outputUsesH264Pipeline(format) {
 }
 
 // src/services/render/hlsConfig.ts
-import { fpsToNumber as fpsToNumber2 } from "@hyperframes/core";
+import { keyframeIntervalToGopSize } from "@hyperframes/engine";
 var DEFAULT_HLS_SEGMENT_SECONDS = 4;
 function validateHlsRenderConfig(config) {
   if (config.format !== "hls") return;
@@ -856,7 +856,7 @@ function resolveHlsSegmentSeconds(config) {
   return config.hlsSegmentSeconds ?? DEFAULT_HLS_SEGMENT_SECONDS;
 }
 function resolveHlsGopSize(fps, segmentSeconds) {
-  return Math.max(1, Math.round(fpsToNumber2(fps) * segmentSeconds));
+  return keyframeIntervalToGopSize(fps, segmentSeconds);
 }
 function resolveHlsEncoderGopLock(outputFormat, fps, segmentSeconds) {
   if (outputFormat !== "hls") return { lockGopForChunkConcat: false, gopSize: void 0 };
@@ -866,6 +866,38 @@ function resolveHlsEncoderGopLock(outputFormat, fps, segmentSeconds) {
   };
 }
 
+// src/services/render/deliveryEncoder.ts
+import { appendRateCapArgs, keyframeIntervalToGopSize as keyframeIntervalToGopSize2 } from "@hyperframes/engine";
+function validateDeliveryEncoderConfig(config) {
+  const { keyframeIntervalSeconds, maxBitrate, bufferSize, format } = config;
+  if (keyframeIntervalSeconds === void 0 && maxBitrate === void 0 && bufferSize === void 0)
+    return;
+  if (keyframeIntervalSeconds !== void 0) {
+    if (!Number.isFinite(keyframeIntervalSeconds) || keyframeIntervalSeconds <= 0) {
+      throw new Error(
+        `keyframeIntervalSeconds must be a positive number of seconds; got ${keyframeIntervalSeconds}`
+      );
+    }
+    if (format === "hls") {
+      throw new Error(
+        "keyframeIntervalSeconds does not apply to hls; hlsSegmentSeconds sets its keyframes"
+      );
+    }
+  }
+  if (format !== void 0 && format !== "mp4") {
+    throw new Error(`keyframeIntervalSeconds and maxBitrate apply to mp4 renders, not ${format}`);
+  }
+  appendRateCapArgs([], { maxBitrate, bufferSize });
+}
+function resolveDeliveryEncoderOptions(config) {
+  const { maxBitrate, bufferSize, keyframeIntervalSeconds } = config;
+  const gop = keyframeIntervalSeconds === void 0 ? resolveHlsEncoderGopLock(config.format ?? "mp4", config.fps, config.hlsSegmentSeconds) : {
+    lockGopForChunkConcat: true,
+    gopSize: keyframeIntervalToGopSize2(config.fps, keyframeIntervalSeconds)
+  };
+  return { maxBitrate, bufferSize, ...gop };
+}
+
 // src/services/render/shared.ts
 import {
   copyFileSync,
@@ -1884,7 +1916,7 @@ function replanSegmentedAfterFailure(plan, failure) {
   const keepSegmenting = failure.kind === "draw_element_verification" || failure.kind === "draw_element_capture";
   return createCapturePlan({
     ...plan,
-    forceScreenshot: keepSegmenting || failure.kind === "capture_failure",
+    forceScreenshot: plan.forceScreenshot || keepSegmenting || failure.kind === "capture_failure",
     useStreamingEncode: true,
     useLayeredComposite: false,
     useSegmentedCapture: keepSegmenting,
@@ -1954,7 +1986,7 @@ import { CaptureFailure, classifyCaptureFailure } from "@hyperframes/engine";
 
 // src/services/render/perfSummary.ts
 import { arch, cpus, platform, totalmem } from "node:os";
-import { fpsToNumber as fpsToNumber3 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber2 } from "@hyperframes/core";
 
 // src/services/render/hdrPerf.ts
 function createHdrPerfCollector() {
@@ -2225,7 +2257,7 @@ function buildRenderPerfSummary(input) {
     // payloads (CLI telemetry, regression-harness reports) where a single
     // number is friendlier than `{num,den}`. Callers needing the rational
     // back can read `job.config.fps`.
-    fps: fpsToNumber3(input.job.config.fps),
+    fps: fpsToNumber2(input.job.config.fps),
     quality: input.job.config.quality,
     workers: input.workerCount,
     workerSizing: input.workerSizing,
@@ -2810,7 +2842,7 @@ import {
   resolveVideoExtractionWindow,
   runFfmpeg
 } from "@hyperframes/engine";
-import { fpsToFfmpegArg, fpsToNumber as fpsToNumber4 } from "@hyperframes/core";
+import { fpsToFfmpegArg, fpsToNumber as fpsToNumber3 } from "@hyperframes/core";
 
 // src/services/hdrFrameWindows.ts
 import { closeSync as closeSync3, constants as constants2, openSync as openSync3, rmSync as rmSync4 } from "node:fs";
@@ -3113,7 +3145,7 @@ async function extractHdrVideoFrames(args) {
   const runFfmpegImpl = args.runFfmpegImpl ?? runFfmpeg;
   const extractMediaMetadataImpl = args.extractMediaMetadataImpl ?? extractMediaMetadata2;
   const resolveFinalFrameExtractionWindowImpl = args.resolveFinalFrameExtractionWindowImpl ?? resolveFinalFrameExtractionWindow;
-  const fps = fpsToNumber4(job.config.fps);
+  const fps = fpsToNumber3(job.config.fps);
   const out = /* @__PURE__ */ new Map();
   mkdirSync2(framesDir, { recursive: true });
   let scratchBytes = 0;
@@ -3951,7 +3983,6 @@ async function runCaptureStreamingStage(input) {
     const reorderBuffer = createFrameReorderBuffer(0, totalFrames);
     if (workerCount > 1) {
       const deParallelStream = forceParallelStream === true || process.env.HF_DE_PARALLEL_STREAM === "true";
-      const tasks = deParallelStream ? distributeFramesInterleaved(totalFrames, workerCount, workDir) : distributeFrames(totalFrames, workerCount, workDir);
       const parallelStats = {
         verifyChecked: 0,
         blankSuspects: 0,
@@ -3964,143 +3995,158 @@ async function runCaptureStreamingStage(input) {
         frameTime: (i) => i * job.config.fps.den / job.config.fps.num
       });
       let parallelGuardRan = false;
-      let parallelDrainError = null;
-      const onFrameBuffer = async (frameIndex, buffer, workerSession) => {
-        try {
-          if (deParallelStream && workerSession.captureMode === "drawelement") {
-            parallelGuardRan = true;
-            buffer = await parallelGuard(workerSession, frameIndex, buffer);
-          }
-          await reorderBuffer.waitForFrame(frameIndex);
-          ensureFrameWritten(await currentEncoder.writeFrame(buffer), frameIndex, currentEncoder);
-          reorderBuffer.advanceTo(frameIndex + 1);
-        } catch (err) {
-          const e = err instanceof Error ? err : new Error(String(err));
-          if (!parallelDrainError) {
-            parallelDrainError = e;
-            reorderBuffer.abort(e);
+      let writtenFrames = 0;
+      let resumeFrom = 0;
+      let resumedAfterStall = false;
+      let workerResults;
+      for (; ; ) {
+        const parallelReorder = createFrameReorderBuffer(resumeFrom, totalFrames);
+        const tasks = deParallelStream ? distributeFramesInterleaved(totalFrames - resumeFrom, workerCount, workDir, resumeFrom) : distributeFrames(totalFrames - resumeFrom, workerCount, workDir, resumeFrom);
+        let parallelDrainError = null;
+        const onFrameBuffer = async (frameIndex, buffer, workerSession) => {
+          try {
+            if (deParallelStream && workerSession.captureMode === "drawelement") {
+              parallelGuardRan = true;
+              buffer = await parallelGuard(workerSession, frameIndex, buffer);
+            }
+            await parallelReorder.waitForFrame(frameIndex);
+            ensureFrameWritten(await currentEncoder.writeFrame(buffer), frameIndex, currentEncoder);
+            parallelReorder.advanceTo(frameIndex + 1);
+            writtenFrames = frameIndex + 1;
+          } catch (err) {
+            const e = err instanceof Error ? err : new Error(String(err));
+            if (!parallelDrainError) {
+              parallelDrainError = e;
+              parallelReorder.abort(e);
+            }
+            throw e;
           }
-          throw e;
+        };
+        const captureLabel = input.parallelCaptureLabel ?? "worker";
+        let watchdogArmed = false;
+        const stallController = new AbortController();
+        const forwardParentAbort = () => stallController.abort();
+        if (abortSignal) {
+          if (abortSignal.aborted) stallController.abort();
+          else abortSignal.addEventListener("abort", forwardParentAbort, { once: true });
         }
-      };
-      const captureLabel = input.parallelCaptureLabel ?? "worker";
-      let watchdogArmed = false;
-      const stallController = new AbortController();
-      const forwardParentAbort = () => stallController.abort();
-      if (abortSignal) {
-        if (abortSignal.aborted) stallController.abort();
-        else abortSignal.addEventListener("abort", forwardParentAbort, { once: true });
-      }
-      const stallTimeoutMs = resolveCaptureStallTimeoutMs();
-      let lastCapturedFrames = 0;
-      let lastProgressAt = Date.now();
-      const workerPhases = /* @__PURE__ */ new Map();
-      const phaseSummary = () => [...workerPhases.entries()].sort(([left], [right]) => left - right).map(([workerId, detail]) => `worker=${workerId} ${detail}`).join("; ");
-      let stalled = false;
-      const stallTimer = setInterval(
-        () => {
-          if (!watchdogArmed || Date.now() - lastProgressAt <= stallTimeoutMs) return;
-          stalled = true;
-          const stallErr = new ParallelCaptureStallError({
-            variant: "drain",
-            captureLabel,
-            stallTimeoutMs,
-            lastCapturedFrames,
-            totalFrames,
-            phaseSummary: phaseSummary()
-          });
-          reorderBuffer.abort(stallErr);
-          stallController.abort();
-        },
-        Math.min(stallTimeoutMs, DE_STALL_POLL_MS)
-      );
-      let workerResults;
-      try {
-        workerResults = await executeParallelCapture(
-          fileServer.url,
-          workDir,
-          tasks,
-          buildCaptureOptions(),
-          createRenderVideoFrameInjector,
-          stallController.signal,
-          (progress) => {
-            if (progress.latestWorkerPhase) {
-              const phase = progress.latestWorkerPhase;
-              const detail = `phase=${phase.phase} frame=${phase.frameIndex ?? "n/a"} browser=${phase.browserExecutable} version=${phase.browserVersion} CanvasDrawElement=${phase.canvasDrawElement} gpu=${phase.gpuBackend}`;
-              workerPhases.set(phase.workerId, detail);
-              if (phase.phase === "frame_capture" && !watchdogArmed) {
-                watchdogArmed = true;
+        const stallTimeoutMs = resolveCaptureStallTimeoutMs();
+        let lastCapturedFrames = 0;
+        let lastProgressAt = Date.now();
+        const workerPhases = /* @__PURE__ */ new Map();
+        const phaseDetail = (phase) => `phase=${phase.phase} frame=${phase.frameIndex ?? "n/a"} step=${phase.readStep?.() ?? "n/a"} browser=${phase.browserExecutable} version=${phase.browserVersion} CanvasDrawElement=${phase.canvasDrawElement} gpu=${phase.gpuBackend}`;
+        const phaseSummary = () => [...workerPhases.entries()].sort(([left], [right]) => left - right).map(([workerId, detail]) => `worker=${workerId} ${detail}`).join("; ");
+        let stalled = false;
+        const stallTimer = setInterval(
+          () => {
+            if (!watchdogArmed || Date.now() - lastProgressAt <= stallTimeoutMs) return;
+            stalled = true;
+            const stallErr = new ParallelCaptureStallError({
+              variant: "drain",
+              captureLabel,
+              stallTimeoutMs,
+              lastCapturedFrames: resumeFrom + lastCapturedFrames,
+              totalFrames,
+              phaseSummary: phaseSummary()
+            });
+            parallelReorder.abort(stallErr);
+            stallController.abort();
+          },
+          Math.min(stallTimeoutMs, DE_STALL_POLL_MS)
+        );
+        try {
+          workerResults = await executeParallelCapture(
+            fileServer.url,
+            workDir,
+            tasks,
+            buildCaptureOptions(),
+            createRenderVideoFrameInjector,
+            stallController.signal,
+            (progress) => {
+              if (progress.latestWorkerPhase) {
+                const phase = progress.latestWorkerPhase;
+                workerPhases.set(phase.workerId, phaseDetail(phase));
+                if (phase.phase === "frame_capture" && !watchdogArmed) {
+                  watchdogArmed = true;
+                  lastProgressAt = Date.now();
+                }
+                log.info("[Render] Parallel capture worker phase", {
+                  workerId: phase.workerId,
+                  phase: phase.phase,
+                  frameIndex: phase.frameIndex,
+                  browserExecutable: phase.browserExecutable,
+                  browserVersion: phase.browserVersion,
+                  canvasDrawElement: phase.canvasDrawElement,
+                  gpuBackend: phase.gpuBackend
+                });
+                if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
+                return;
+              }
+              if (progress.capturedFrames > lastCapturedFrames) {
+                lastCapturedFrames = progress.capturedFrames;
                 lastProgressAt = Date.now();
+                watchdogArmed = true;
+              }
+              const doneFrames = resumeFrom + progress.capturedFrames;
+              job.framesRendered = doneFrames;
+              const frameProgress = doneFrames / totalFrames;
+              reportFrameProgress(
+                job,
+                `Streaming frame ${doneFrames}/${totalFrames} (${workerCount} workers)`,
+                Math.round(25 + frameProgress * 55),
+                onProgress,
+                doneFrames,
+                totalFrames
+              );
+            },
+            onFrameBuffer,
+            // Interleaved DE workers each get their own browser process: co-tenant pages starve
+            // each other's paint events.
+            deParallelStream ? { ...captureCfg, enableBrowserPool: false } : captureCfg,
+            {
+              // A worker died: release parked peers with its original failure, not the stall the
+              // watchdog raises later.
+              onWorkerOperation: (phase) => workerPhases.set(phase.workerId, phaseDetail(phase)),
+              onWorkerFailure: (failure) => {
+                if (parallelDrainError) return;
+                parallelDrainError = failure;
+                parallelReorder.abort(failure);
               }
-              log.info("[Render] Parallel capture worker phase", {
-                workerId: phase.workerId,
-                phase: phase.phase,
-                frameIndex: phase.frameIndex,
-                browserExecutable: phase.browserExecutable,
-                browserVersion: phase.browserVersion,
-                canvasDrawElement: phase.canvasDrawElement,
-                gpuBackend: phase.gpuBackend
-              });
-              if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
-              return;
-            }
-            if (progress.capturedFrames > lastCapturedFrames) {
-              lastCapturedFrames = progress.capturedFrames;
-              lastProgressAt = Date.now();
-              watchdogArmed = true;
             }
-            job.framesRendered = progress.capturedFrames;
-            const frameProgress = progress.capturedFrames / progress.totalFrames;
-            reportFrameProgress(
-              job,
-              `Streaming frame ${progress.capturedFrames}/${progress.totalFrames} (${workerCount} workers)`,
-              Math.round(25 + frameProgress * 55),
-              onProgress,
-              progress.capturedFrames,
-              progress.totalFrames
+          );
+        } catch (err) {
+          if (stalled && abortSignal?.aborted !== true && captureLabel === "BeginFrame" && !resumedAfterStall && writtenFrames > resumeFrom) {
+            resumedAfterStall = true;
+            log.warn(
+              "[Render] Parallel BeginFrame capture stalled; resuming from the first unwritten frame",
+              {
+                resumeFrom: writtenFrames,
+                totalFrames,
+                workerPhases: phaseSummary()
+              }
             );
-          },
-          onFrameBuffer,
-          // Interleaved DE workers each need their own browser PROCESS:
-          // pages co-tenant in one browser share one compositor, whose
-          // internal frame scheduling deprioritizes non-active pages — their
-          // canvas `paint` events starve and the drawElement paint-wait slows
-          // ~3x (measured: 86s vs 30s on a 3,245-frame rAF comp). This is
-          // Chromium's internal frame-production scheduling on ALL platforms,
-          // NOT the Linux-only HeadlessExperimental.beginFrame capture mode.
-          deParallelStream ? { ...captureCfg, enableBrowserPool: false } : captureCfg,
-          {
-            // A worker died (Target closed, Page crashed, launch failure).
-            // Its frames are gone and peers are parked in waitForFrame on the
-            // first of them; release them with the ORIGINAL failure so the
-            // orchestrator sees a transient browser error it knows how to
-            // retry, not the stall the watchdog would have raised a minute
-            // later. First failure wins, same as the drain guard above.
-            onWorkerFailure: (failure) => {
-              if (parallelDrainError) return;
-              parallelDrainError = failure;
-              reorderBuffer.abort(failure);
-            }
+            resumeFrom = writtenFrames;
+            continue;
           }
-        );
-      } catch (err) {
-        if (parallelDrainError) throw poolFailure(parallelDrainError, probeSession);
-        if (stalled && abortSignal?.aborted !== true) {
-          throw new ParallelCaptureStallError({
-            variant: "pool",
-            captureLabel,
-            stallTimeoutMs,
-            lastCapturedFrames,
-            totalFrames,
-            phaseSummary: phaseSummary()
-          });
+          if (parallelDrainError) throw poolFailure(parallelDrainError, probeSession);
+          if (stalled && abortSignal?.aborted !== true) {
+            throw new ParallelCaptureStallError({
+              variant: "pool",
+              captureLabel,
+              stallTimeoutMs,
+              lastCapturedFrames: resumeFrom + lastCapturedFrames,
+              totalFrames,
+              phaseSummary: phaseSummary()
+            });
+          }
+          throw poolFailure(err, probeSession);
+        } finally {
+          clearInterval(stallTimer);
+          abortSignal?.removeEventListener("abort", forwardParentAbort);
         }
-        throw poolFailure(err, probeSession);
-      } finally {
-        clearInterval(stallTimer);
-        abortSignal?.removeEventListener("abort", forwardParentAbort);
+        if (parallelDrainError) throw poolFailure(parallelDrainError, probeSession);
+        break;
       }
-      if (parallelDrainError) throw poolFailure(parallelDrainError, probeSession);
       pushWorkerDedupPerfs(workerResults, dedupPerfs);
       const workerPageErrors = [];
       pushWorkerPageErrors(workerResults, workerPageErrors);
@@ -4261,7 +4307,7 @@ function segmentEncoderOptions(base, segment) {
   return {
     ...base,
     lockGopForChunkConcat: true,
-    gopSize: segment.endFrame - segment.startFrame
+    gopSize: Math.min(base.gopSize ?? Infinity, segment.endFrame - segment.startFrame)
   };
 }
 var SegmentEncoderSpawnError = class extends Error {
@@ -4355,6 +4401,12 @@ function defaultSessionFactory(input) {
   let probeSession = input.probeSession;
   return {
     create: async () => {
+      const probeCannotCaptureEveryFrame = Boolean(probeSession?.deRiskFrames?.size);
+      if (probeSession && probeCannotCaptureEveryFrame) {
+        await closeCaptureSession2(probeSession).catch(() => {
+        });
+        probeSession = null;
+      }
       const session = probeSession ?? await openSegmentedSession(input);
       if (probeSession) {
         openSegmentedSessionReuse(input, probeSession);
@@ -4685,8 +4737,10 @@ function computeSegmentPlanHash(input) {
     input.motionBlur,
     input.pageMotionBlur ?? "",
     input.captureQuality === void 0 ? "" : String(input.captureQuality)
-  ].join(" ");
-  return createHash2("sha256").update(ordered).digest("hex").slice(0, 16);
+  ];
+  const delivery = [input.maxBitrate, input.bufferSize, input.gopSize].map((v) => v ?? "");
+  if (delivery.some((v) => v !== "")) ordered.push(...delivery.map(String));
+  return createHash2("sha256").update(ordered.join(" ")).digest("hex").slice(0, 16);
 }
 function segmentDirFor(projectRendersDir, planHash) {
   return join11(projectRendersDir, ".hf-segments", planHash);
@@ -4833,7 +4887,7 @@ function resolveVideoCaptureBeyondViewport(videoCount) {
 
 // src/services/render/captureCost.ts
 import { join as join12 } from "node:path";
-import { fpsToNumber as fpsToNumber5 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber4 } from "@hyperframes/core";
 import {
   calculateOptimalWorkers,
   captureFrameToBuffer as captureFrameToBuffer3,
@@ -5037,7 +5091,7 @@ async function runCaptureCalibration(input) {
   let probeSession = input.probeSession;
   let forceScreenshot = input.forceScreenshot;
   let lastBrowserConsole = [];
-  const fps = fpsToNumber5(job.config.fps);
+  const fps = fpsToNumber4(job.config.fps);
   const sessionRef = { current: null };
   const runOneCalibration = async (sessionDir, sessionCfg) => {
     log.info("Launching browser for capture calibration...");
@@ -5497,7 +5551,7 @@ function emitFallbackCaptureProfile(recorder, perfSummaries, env = process.env)
 // src/services/render/videoFrameCoverage.ts
 import { parseHTML } from "linkedom";
 import {
-  fpsToNumber as fpsToNumber6,
+  fpsToNumber as fpsToNumber5,
   normalizeRateSpec,
   sourceTimeAt,
   toFps
@@ -5532,7 +5586,7 @@ function resolveVideoCoverageThreshold(envValue = process.env.HF_VIDEO_COVERAGE_
   return parsed;
 }
 function expectedFramesForClip(start, end, fps, rounding = "ceil") {
-  const fpsValue = fpsToNumber6(toFps(fps));
+  const fpsValue = fpsToNumber5(toFps(fps));
   if (!Number.isFinite(start) || !Number.isFinite(end) || !Number.isFinite(fpsValue)) return 0;
   if (fpsValue <= 0) return 0;
   const duration = Math.max(0, end - start);
@@ -6794,7 +6848,7 @@ function detectShaderTransitionUsage(html) {
   }
   return false;
 }
-async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath) {
+async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, downloadDir, tagName, elementIdentity, log, urlByAbsentLocalPath, probes) {
   let filePath = src;
   if (isHttpUrl(src)) {
     if (!existsSync10(downloadDir)) mkdirSync7(downloadDir, { recursive: true });
@@ -6821,45 +6875,52 @@ async function resolveMediaDuration(src, mediaStart, playbackRate, baseDir, down
     if (error instanceof Error && error.stack) wrapped.stack = error.stack;
     return wrapped;
   };
-  return withMediaProbeSlot(async () => {
-    let profile;
+  const probe = () => withMediaProbeSlot(async () => {
     try {
       await assertMediaPayload(filePath, elementIdentity);
-      profile = await probeMediaProfile2(filePath);
-    } catch (error) {
-      if (tagName !== "video") {
-        if (error instanceof NotMediaPayloadError2) {
-          log?.warn(
-            `[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media file, so the element is dropped from the render. Point it at a rendered media file.`
-          );
-        }
-        return { duration: null, resolvedPath: filePath };
-      }
-      throw withSrcContext(error);
-    }
-    assertAssetMediaTypeProfile(tagName === "video" ? "video" : "audio", profile, elementIdentity);
-    let metadata;
-    if (tagName === "video") {
-      try {
-        metadata = await extractMediaMetadata(filePath);
-      } catch (error) {
-        throw withSrcContext(error);
+      const profile = await probeMediaProfile2(filePath);
+      if (tagName === "video") {
+        return { profile, fileDuration: (await extractMediaMetadata(filePath)).durationSeconds };
       }
-    } else {
       try {
-        metadata = await extractAudioMetadata(filePath);
+        return { profile, fileDuration: (await extractAudioMetadata(filePath)).durationSeconds };
       } catch {
-        return { duration: null, resolvedPath: filePath };
+        return { profile, fileDuration: null };
       }
+    } catch (error) {
+      return { error };
     }
-    const fileDuration = metadata.durationSeconds;
-    const duration = resolveNaturalMediaTimelineDurationFromValues(
-      fileDuration,
-      mediaStart,
-      playbackRate
-    );
-    return { duration, resolvedPath: filePath };
   });
+  const key = `${tagName}\0${filePath}`;
+  let probed = probes?.get(key);
+  if (!probed) {
+    probed = probe();
+    probes?.set(key, probed);
+  }
+  const outcome = await probed;
+  if ("error" in outcome) {
+    if (tagName !== "video") {
+      if (outcome.error instanceof NotMediaPayloadError2) {
+        log?.warn(
+          `[compile] Audio "${elementIdentity}" (${src}) is a text document, not a media file, so the element is dropped from the render. Point it at a rendered media file.`
+        );
+      }
+      return { duration: null, resolvedPath: filePath };
+    }
+    throw withSrcContext(outcome.error);
+  }
+  assertAssetMediaTypeProfile(
+    tagName === "video" ? "video" : "audio",
+    outcome.profile,
+    elementIdentity
+  );
+  if (outcome.fileDuration === null) return { duration: null, resolvedPath: filePath };
+  const duration = resolveNaturalMediaTimelineDurationFromValues(
+    outcome.fileDuration,
+    mediaStart,
+    playbackRate
+  );
+  return { duration, resolvedPath: filePath };
 }
 function markInferredVariableMediaDurations(html, unresolvedMedia) {
   const unresolvedIds = new Set(unresolvedMedia.map((element) => element.id));
@@ -6873,7 +6934,7 @@ function markInferredVariableMediaDurations(html, unresolvedMedia) {
   }
   return changed ? document2.toString() : html;
 }
-async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath) {
+async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocalPath, probes) {
   const { html: staticCompiled, unresolved } = compileTimingAttrs(html);
   const mediaUnresolved = unresolved.filter(
     (el) => (el.tagName === "video" || el.tagName === "audio") && el.src
@@ -6890,7 +6951,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
         el.tagName,
         el.id,
         log,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -6911,7 +6973,9 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
         downloadDir,
         el.tagName,
         el.id,
-        log
+        log,
+        void 0,
+        probes
       );
       return { id: el.id, tagName: el.tagName, duration: el.duration, maxDuration, src: el.src };
     })
@@ -6933,7 +6997,7 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
   compiledHtml = compiledHtml.replace(/(<audio\b[^>]*)\s+crossorigin(?:=["'][^"']*["'])?/gi, "$1");
   return { html: compiledHtml, unresolvedCompositions };
 }
-async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath) {
+async function parseSubCompositions(html, projectDir, downloadDir, visited = /* @__PURE__ */ new Set(), urlByAbsentLocalPath, probes) {
   const subCompositions = /* @__PURE__ */ new Map();
   const { document: document2 } = parseHTML5(html);
   const compEls = document2.querySelectorAll("[data-composition-src]");
@@ -6961,14 +7025,16 @@ async function parseSubCompositions(html, projectDir, downloadDir, visited = /*
         dirname7(item.filePath),
         downloadDir,
         void 0,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       );
       const nested = await parseSubCompositions(
         compiledSub,
         projectDir,
         downloadDir,
         item.nestedVisited,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       );
       return {
         srcPath: item.srcPath,
@@ -7738,19 +7804,22 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   );
   const rawHtml = rewriteUnresolvableGsapToCdn(entryHtml, projectDir);
   assertSubCompositionsUsable(rawHtml, projectDir);
+  const probes = /* @__PURE__ */ new Map();
   const { html: compiledHtml, unresolvedCompositions } = await compileHtmlFile(
     rawHtml,
     projectDir,
     downloadDir,
     options.log,
-    options.urlByAbsentLocalPath
+    options.urlByAbsentLocalPath,
+    probes
   );
   const { subCompositions } = await parseSubCompositions(
     compiledHtml,
     projectDir,
     downloadDir,
     void 0,
-    options.urlByAbsentLocalPath
+    options.urlByAbsentLocalPath,
+    probes
   );
   const fullHtml = ensureFullDocument(compiledHtml);
   const inlinedHtml = inlineSubCompositions(
@@ -7853,9 +7922,12 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   }
   const { videos, audios, images, droppedMediaIds } = collectRenderMedia(html);
   const masterFxChain = parseMasterFxChain(html);
+  const advised = /* @__PURE__ */ new Set();
   for (const video of videos) {
     if (isHttpUrl(video.src)) continue;
     const videoPath = resolve7(projectDir, video.src);
+    if (advised.has(videoPath)) continue;
+    advised.add(videoPath);
     const reencode = `ffmpeg -i "${video.src}" -c:v libx264 -r 30 -g 30 -keyint_min 30 -movflags +faststart -c:a copy output.mp4`;
     (async () => {
       const metadata = await withMediaProbeSlot(() => extractMediaMetadata(videoPath));
@@ -8406,13 +8478,14 @@ import {
 } from "@hyperframes/engine";
 import {
   MEDIA_RENDER_ID_ATTR as MEDIA_RENDER_ID_ATTR2,
-  fpsToNumber as fpsToNumber7,
+  fpsToNumber as fpsToNumber6,
   normalizeRateSpec as normalizeRateSpec3,
   readMediaStart as readMediaStart2,
   shiftRateLane as shiftRateLane2,
   sourceTimeAt as sourceTimeAt3,
   timeAtSourceTime
 } from "@hyperframes/core";
+import { parseHostVariableValues as parseHostVariableValues2, readDeclaredDefaults as readDeclaredDefaults2 } from "@hyperframes/core/compiler";
 import { extractMediaSrcMutations } from "@hyperframes/parsers";
 
 // src/services/render/stages/probeFailures.ts
@@ -8450,8 +8523,15 @@ function hasAutoStartVideos(html) {
   const { document: document2 } = parseHTML6(html);
   return document2.querySelector("video[data-hf-auto-start]") !== null;
 }
+function variableHasValue(element, variableId, variables) {
+  if (variables && Object.hasOwn(variables, variableId)) return true;
+  for (let scope = element.parentElement; scope; scope = scope.parentElement) {
+    if (Object.hasOwn(parseHostVariableValues2(scope), variableId)) return true;
+    if (Object.hasOwn(readDeclaredDefaults2(scope), variableId)) return true;
+  }
+  return Object.hasOwn(readDeclaredDefaults2(element.ownerDocument.documentElement), variableId);
+}
 function hasVariableBoundMedia(html, variables) {
-  if (!variables || Object.keys(variables).length === 0) return false;
   const { document: document2 } = parseHTML6(html);
   return Array.from(
     document2.querySelectorAll(
@@ -8459,7 +8539,7 @@ function hasVariableBoundMedia(html, variables) {
     )
   ).some((element) => {
     const variableId = element.getAttribute("data-var-src")?.trim();
-    return Boolean(variableId && Object.hasOwn(variables, variableId));
+    return Boolean(variableId && variableHasValue(element, variableId, variables));
   });
 }
 function authoredMediaStarts(html) {
@@ -8885,7 +8965,7 @@ async function runProbeStage(input) {
           session.page,
           composition.audios.map((audio) => audio.id),
           composition.duration,
-          fpsToNumber7(job.config.fps)
+          fpsToNumber6(job.config.fps)
         );
         assertNotAborted();
         if (automation.length > 0) {
@@ -8948,7 +9028,7 @@ async function runProbeStage(input) {
   }
   const browserProbeMs = Date.now() - probeStart;
   const duration = composition.duration;
-  const totalFrames = durationToFrameCount(duration, fpsToNumber7(job.config.fps));
+  const totalFrames = durationToFrameCount(duration, fpsToNumber6(job.config.fps));
   if (duration <= 0) {
     const diagnostics = [];
     try {
@@ -9162,10 +9242,11 @@ var VideoExtractionStageError = class extends Error {
       kind: failure.kind,
       affectedElementCount: failure.count
     }))
-  )) {
+  ), ffmpegReason) {
     const total = failures.reduce((sum, failure) => sum + failure.count, 0);
     const breakdown = failures.map((failure) => `${failure.kind}=${failure.count}`).join(",");
-    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]`);
+    const reason = ffmpegReason ? `: ffmpeg said: ${ffmpegReason}` : "";
+    super(`Video extraction failed for ${total} source(s) [${code}; ${breakdown}]${reason}`);
     this.code = code;
     this.retryable = retryable;
     this.failures = failures;
@@ -9207,7 +9288,8 @@ function buildVideoExtractionStageError(result) {
     retryable ? "VIDEO_EXTRACTION_FAILED" : "VIDEO_SOURCE_UNRENDERABLE",
     retryable,
     failures,
-    extractionFailureMetadataFromResult(result)
+    extractionFailureMetadataFromResult(result),
+    result.errors.find((failure) => failure.ffmpegReason)?.ffmpegReason
   );
 }
 function buildHdrProbeStageError(failures) {
@@ -9448,16 +9530,17 @@ function appendAutoDetectedVideoAudio(composition, extracted) {
 
 // src/services/render/stages/audioStage.ts
 import { join as join20 } from "node:path";
-import { rmSync as rmSync10 } from "node:fs";
 import {
   MIXED_AUDIO_FILENAME,
   audioFailureDiagnostics,
-  processCompositionAudio
+  processCompositionAudio,
+  removeScratch as removeScratch2,
+  collectScratchLeftovers
 } from "@hyperframes/engine";
 
 // src/services/render/audioPadTrim.ts
 import { spawn } from "node:child_process";
-import { mkdtempSync as mkdtempSync3, rmSync as rmSync9 } from "node:fs";
+import { mkdtempSync as mkdtempSync3 } from "node:fs";
 import { dirname as dirname8, join as join19 } from "node:path";
 import {
   DEFAULT_CONFIG,
@@ -9466,6 +9549,7 @@ import {
   extractAudioMetadata as extractAudioMetadata3,
   getFfprobeBinary,
   ManagedChildProcess,
+  removeScratch,
   renameWithRetry as renameWithRetry5,
   runFfmpeg as runFfmpeg5,
   trackChildProcess
@@ -9661,7 +9745,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
       error: `audioPadTrim: failed to materialize ${plan.operation}: ${err instanceof Error ? err.message : String(err)}`
     };
   } finally {
-    for (const path of plan.cleanupPaths) rmSync9(path, { force: true });
+    for (const path of plan.cleanupPaths) removeScratch(path);
   }
   let loweredDb = 0;
   if (probeTruePeak) {
@@ -9724,7 +9808,7 @@ async function enforceAacTruePeak(input) {
       }
       if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
         if (measuredPath !== correctedPath) return { success: true };
-        renameWithRetry5(correctedPath, input.audioPath);
+        renameWithRetry5(correctedPath, input.audioPath, { copyFallback: true });
         return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
@@ -9765,7 +9849,7 @@ async function enforceAacTruePeak(input) {
       )}`
     };
   } finally {
-    if (scratchDir) rmSync9(scratchDir, { recursive: true, force: true });
+    if (scratchDir) removeScratch(scratchDir);
   }
 }
 function failResult(outputPath, target, source, error) {
@@ -9910,7 +9994,15 @@ function assertAudioNotInterrupted(failures) {
     ])
   });
 }
-async function runAudioStage(input) {
+function runAudioStage(input) {
+  return collectScratchLeftovers(
+    () => runAudioStageScoped(input),
+    (left) => {
+      if (left.length > 0) input.log?.warn("[audio] scratch left behind", { count: left.length });
+    }
+  );
+}
+async function runAudioStageScoped(input) {
   const stageStart = Date.now();
   const pcmSourcePath = join20(input.workDir, "audio-source.wav");
   const duration = input.totalFrames * input.fps.den / input.fps.num;
@@ -9932,7 +10024,7 @@ async function runAudioStage(input) {
     }
     return { ...result, audioLoweredDb, audioProcessMs: Date.now() - stageStart };
   } finally {
-    rmSync10(pcmSourcePath, { force: true });
+    removeScratch2(pcmSourcePath);
   }
 }
 async function mixAudioForDelivery(input, duration, pcmSourcePath) {
@@ -10194,6 +10286,7 @@ async function runCaptureStage(input) {
       dedupPerfs,
       pageErrorLines: workerPageErrors,
       openAttempt: input.openAttempt,
+      verifyFirstSession: input.verifyFirstSession,
       onProgress: (progress) => {
         if (progress.latestWorkerPhase) {
           if (progress.capturedFrames === 0) reportWorkerStartup(job, progress, onProgress);
@@ -10412,7 +10505,7 @@ import {
   initializeSession as initializeSession7,
   spawnStreamingEncoder as spawnStreamingEncoder3
 } from "@hyperframes/engine";
-import { fpsToNumber as fpsToNumber8 } from "@hyperframes/core";
+import { fpsToNumber as fpsToNumber7 } from "@hyperframes/core";
 
 // src/services/hdrImageTransferCache.ts
 import { convertTransfer as convertTransfer2 } from "@hyperframes/engine";
@@ -11086,6 +11179,7 @@ async function runCaptureHdrStage(input) {
     preset,
     effectiveQuality,
     effectiveBitrate,
+    deliveryEncoder,
     fileServer,
     buildCaptureOptions,
     createRenderVideoFrameInjector,
@@ -11147,7 +11241,7 @@ async function runCaptureHdrStage(input) {
       }
       return map;
     });
-    const fpsDecimal = fpsToNumber8(job.config.fps);
+    const fpsDecimal = fpsToNumber7(job.config.fps);
     const transitionRanges = transitionMeta.map((t) => ({
       ...t,
       startFrame: Math.floor(t.time * fpsDecimal),
@@ -11175,6 +11269,7 @@ async function runCaptureHdrStage(input) {
         preset: preset.preset,
         quality: effectiveQuality,
         bitrate: effectiveBitrate,
+        ...deliveryEncoder,
         pixelFormat: preset.pixelFormat,
         hdr: preset.hdr,
         rawInputFormat: "rgb48le"
@@ -11234,7 +11329,7 @@ async function runCaptureHdrStage(input) {
         beforeCaptureHook: domSession.onBeforeCapture,
         width,
         height,
-        fps: fpsToNumber8(job.config.fps),
+        fps: fpsToNumber7(job.config.fps),
         compositeTransfer,
         nativeHdrImageIds,
         hdrImageBuffers,
@@ -11378,7 +11473,7 @@ import {
   mkdirSync as mkdirSync9,
   readdirSync as readdirSync4,
   readFileSync as readFileSync8,
-  rmSync as rmSync11,
+  rmSync as rmSync9,
   statSync as statSync7,
   writeFileSync as writeFileSync5
 } from "node:fs";
@@ -11517,7 +11612,7 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
       fileSize
     };
   } finally {
-    rmSync11(input.palettePath, { force: true });
+    rmSync9(input.palettePath, { force: true });
   }
 }
 function startEncodeProgress(job, stage, onProgress) {
@@ -11541,6 +11636,8 @@ function videoEncoderOptions(input, engineCfg) {
     preset: preset.preset,
     quality: input.effectiveQuality,
     bitrate: input.effectiveBitrate,
+    maxBitrate: input.maxBitrate,
+    bufferSize: input.bufferSize,
     pixelFormat: preset.pixelFormat,
     vp9CpuUsed: engineCfg.vp9CpuUsed,
     useGpu: job.config.useGpu,
@@ -12249,7 +12346,8 @@ async function executeDiskCaptureWithAdaptiveRetry(options) {
               });
             } : void 0,
             void 0,
-            options.cfg
+            options.cfg,
+            { verifyFirstSession: options.verifyFirstSession }
           );
           pushWorkerDedupPerfs(workerResults, options.dedupPerfs);
           if (options.pageErrorLines) pushWorkerPageErrors(workerResults, options.pageErrorLines);
@@ -12815,6 +12913,7 @@ function resolveRenderDebugDir() {
 }
 async function executeRenderJob(job, projectDir, outputPath, progressSink, abortSignal, assertRenderActive) {
   validateHlsRenderConfig(job.config);
+  validateDeliveryEncoderConfig(job.config);
   const debugDir = resolveRenderDebugDir();
   const outputDir = dirname11(outputPath);
   if (!existsSync16(outputDir)) mkdirSync10(outputDir, { recursive: true });
@@ -12835,7 +12934,7 @@ async function executeRenderJob(job, projectDir, outputPath, progressSink, abort
       log.info("KEEP_TEMP=1, leaving workDir on disk for inspection", { workDir });
       return;
     }
-    rmSync12(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+    rmSync10(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
   });
   try {
     await executeRenderPipeline({
@@ -12893,11 +12992,14 @@ async function executeRenderPipeline(input) {
   const isGif = outputFormat === "gif";
   const isHls = outputFormat === "hls";
   const hlsSegmentSeconds = isHls ? resolveHlsSegmentSeconds(job.config) : void 0;
-  const hlsEncoderGopLock = resolveHlsEncoderGopLock(
-    outputFormat,
-    job.config.fps,
-    job.config.hlsSegmentSeconds
-  );
+  const deliveryEncoder = resolveDeliveryEncoderOptions({
+    format: outputFormat,
+    fps: job.config.fps,
+    hlsSegmentSeconds: job.config.hlsSegmentSeconds,
+    keyframeIntervalSeconds: job.config.keyframeIntervalSeconds,
+    maxBitrate: job.config.maxBitrate,
+    bufferSize: job.config.bufferSize
+  });
   const artifactTransaction = new ArtifactTransaction(
     outputPath,
     isPngSequence || isHls ? "directory" : "file",
@@ -13137,7 +13239,7 @@ async function executeRenderPipeline(input) {
     validateRenderDuration({
       duration: probeResult.duration,
       totalFrames,
-      fps: fpsToNumber9(job.config.fps)
+      fps: fpsToNumber8(job.config.fps)
     });
     perfStages.browserProbeMs = probeResult.browserProbeMs;
     perfStages.compileMs = Date.now() - stage1Start;
@@ -13980,6 +14082,7 @@ async function executeRenderPipeline(input) {
             preset,
             effectiveQuality,
             effectiveBitrate,
+            deliveryEncoder,
             fileServer: activeFileServer,
             buildCaptureOptions,
             createRenderVideoFrameInjector,
@@ -14004,9 +14107,7 @@ async function executeRenderPipeline(input) {
     } else {
       let streamingHandled = false;
       if (capturePlan.kind === "sdr_segmented") {
-        const segmentedPlan = capturePlan;
         const captureFrameStart = Date.now();
-        resetCaptureAttemptProgress(job);
         const segmentFrames = resolveSegmentFrames(process.env);
         const segmentImageFormat = captureOptions.format || "jpeg";
         const segmentPlanHash = computeSegmentPlanHash({
@@ -14021,6 +14122,9 @@ async function executeRenderPipeline(input) {
           preset: preset.preset,
           quality: effectiveQuality,
           bitrate: effectiveBitrate,
+          maxBitrate: deliveryEncoder.maxBitrate,
+          bufferSize: deliveryEncoder.bufferSize,
+          gopSize: deliveryEncoder.gopSize,
           pixelFormat: preset.pixelFormat,
           imageFormat: segmentImageFormat,
           useGpu: job.config.useGpu === true,
@@ -14046,71 +14150,129 @@ async function executeRenderPipeline(input) {
             });
           }
           if (completedSegments.size === 0) {
-            rmSync12(segmentDir, { recursive: true, force: true });
+            rmSync10(segmentDir, { recursive: true, force: true });
           }
         } else {
-          rmSync12(segmentDir, { recursive: true, force: true });
+          rmSync10(segmentDir, { recursive: true, force: true });
         }
-        const segmentManifest = readSegmentManifest(segmentDir) ?? {
+        const emptySegmentManifest = () => ({
           version: 1,
           planHash: segmentPlanHash,
           totalFrames,
           segmentFrames,
           completed: []
+        });
+        let segmentManifest = readSegmentManifest(segmentDir) ?? emptySegmentManifest();
+        const invokeSegmented = () => {
+          if (capturePlan.kind !== "sdr_segmented") {
+            throw new Error(`Cannot invoke segmented stage with ${capturePlan.kind} plan`);
+          }
+          const segmentedPlan = capturePlan;
+          resetCaptureAttemptProgress(job);
+          return observeRenderStage(
+            observability,
+            "capture_segmented",
+            captureStageObservationData(),
+            () => runCaptureSegmentedStage({
+              fileServer: activeFileServer,
+              workDir,
+              framesDir,
+              videoOnlyPath,
+              job,
+              totalFrames,
+              cfg,
+              plan: segmentedPlan,
+              log,
+              probeSession,
+              outputFormat,
+              streamingEncoderOptions: {
+                fps: job.config.fps,
+                width: captureCompositionWidth ?? width,
+                height: captureCompositionHeight ?? height,
+                codec: preset.codec,
+                preset: preset.preset,
+                quality: effectiveQuality,
+                bitrate: effectiveBitrate,
+                pixelFormat: preset.pixelFormat,
+                vp9CpuUsed: cfg.vp9CpuUsed,
+                useGpu: job.config.useGpu,
+                imageFormat: segmentImageFormat,
+                hdr: preset.hdr,
+                // Each segment sets its own GOP (at most the interval); hls never reaches this route.
+                ...deliveryEncoder
+              },
+              buildCaptureOptions,
+              createRenderVideoFrameInjector,
+              abortSignal: executionSignal,
+              assertNotAborted,
+              onProgress,
+              dedupPerfs,
+              segmentFrames,
+              segmentDir,
+              workerCount: segmentedPlan.workerCount,
+              browserRecycleEverySegments: resolveSegmentBrowserRecycle(process.env),
+              completedSegments,
+              onSegmentComplete: (entry) => {
+                segmentManifest.completed = [
+                  ...segmentManifest.completed.filter((e) => e.index !== entry.index),
+                  { ...entry, completedAt: (/* @__PURE__ */ new Date()).toISOString() }
+                ];
+                writeSegmentManifest(segmentDir, segmentManifest);
+              },
+              updateCaptureObservability
+            })
+          );
         };
-        const segmentedRes = await observeRenderStage(
-          observability,
-          "capture_segmented",
-          captureStageObservationData(),
-          () => runCaptureSegmentedStage({
-            fileServer: activeFileServer,
-            workDir,
-            framesDir,
-            videoOnlyPath,
-            job,
-            totalFrames,
-            cfg,
-            plan: segmentedPlan,
-            log,
-            probeSession,
-            outputFormat,
-            streamingEncoderOptions: {
-              fps: job.config.fps,
-              width: captureCompositionWidth ?? width,
-              height: captureCompositionHeight ?? height,
-              codec: preset.codec,
-              preset: preset.preset,
-              quality: effectiveQuality,
-              bitrate: effectiveBitrate,
-              pixelFormat: preset.pixelFormat,
-              vp9CpuUsed: cfg.vp9CpuUsed,
-              useGpu: job.config.useGpu,
-              imageFormat: segmentImageFormat,
-              hdr: preset.hdr
-              // No hlsEncoderGopLock here: each segment sets its own GOP to
-              // its own length, and hls never reaches this route.
-            },
-            buildCaptureOptions,
-            createRenderVideoFrameInjector,
-            abortSignal: executionSignal,
-            assertNotAborted,
-            onProgress,
-            dedupPerfs,
-            segmentFrames,
-            segmentDir,
-            workerCount: segmentedPlan.workerCount,
-            browserRecycleEverySegments: resolveSegmentBrowserRecycle(process.env),
-            completedSegments,
-            onSegmentComplete: (entry) => {
-              segmentManifest.completed = [
-                ...segmentManifest.completed.filter((e) => e.index !== entry.index),
-                { ...entry, completedAt: (/* @__PURE__ */ new Date()).toISOString() }
-              ];
-              writeSegmentManifest(segmentDir, segmentManifest);
-            },
-            updateCaptureObservability
-          })
-        );
+        let segmentedRes;
+        try {
+          segmentedRes = await invokeSegmented();
+        } catch (err) {
+          const isVerifyError = isDrawElementVerificationError(err);
+          const isDeStall = isDeRendererStallError(err);
+          if (!isVerifyError && !isDrawElementCaptureError(err) && !isDeStall || err instanceof RenderCancelledError || executionSignal?.aborted === true) {
+            throw err;
+          }
+          deSelfVerifyFallback = isVerifyError;
+          const t = deVerifyFallbackTelemetry(err);
+          deFallbackReason = isVerifyError ? t.reason : isDeStall ? "de_renderer_stall" : "capture_error";
+          deFallbackFailedDb = t.failedDb;
+          deFallbackFrameIndex = t.frameIndex;
+          deFallbackThresholdDb = t.thresholdDb;
+          log.warn(
+            "[Render] drawElement capture failed on the segmented path; re-rendering via screenshot",
+            {
+              error: err instanceof Error ? err.message : String(err)
+            }
+          );
+          observability.checkpoint(
+            "capture_segmented",
+            "drawElement capture failed; retrying with a fresh screenshot session"
+          );
+          if (probeSession) {
+            lastBrowserConsole = probeSession.browserConsoleBuffer;
+            const orphaned = probeSession;
+            probeSession = null;
+            await closeOrphanedProbeForRetry(orphaned, closeCaptureSession8, log, "segmented");
+          }
+          rmSync10(segmentDir, { recursive: true, force: true });
+          completedSegments = /* @__PURE__ */ new Set();
+          segmentManifest = emptySegmentManifest();
+          dedupPerfs.length = 0;
+          capturePlan = replanAfterFailure(capturePlan, {
+            kind: isVerifyError ? "draw_element_verification" : "draw_element_capture"
+          });
+          syncCapturePlan();
+          updateCaptureObservability({
+            forceScreenshot: capturePlan.forceScreenshot,
+            deSelfVerifyFallback,
+            deFallbackReason,
+            deFallbackFailedDb,
+            deFallbackFrameIndex,
+            deFallbackThresholdDb
+          });
+          segmentedRes = await invokeSegmented();
+          observability.clearFailure("capture_segmented");
+        }
         if (segmentedRes.success) {
           streamingHandled = true;
           workerCount = segmentedRes.workerCount;
@@ -14130,7 +14292,7 @@ async function executeRenderPipeline(input) {
           );
           updateCaptureObservability({ segmentRetries: segmentedRes.segmentRetries });
           if (job.config.keepSegments !== true) {
-            rmSync12(segmentDir, { recursive: true, force: true });
+            rmSync10(segmentDir, { recursive: true, force: true });
           }
         } else {
           capturePlan = replanAfterFailure(capturePlan, { kind: "streaming_unavailable" });
@@ -14183,7 +14345,7 @@ async function executeRenderPipeline(input) {
                 // assemble stage's `-c copy` segmentation cuts exactly on
                 // the segment boundary. Every other format leaves the
                 // encoder's open-GOP output untouched.
-                ...hlsEncoderGopLock
+                ...deliveryEncoder
               },
               buildCaptureOptions,
               createRenderVideoFrameInjector,
@@ -14346,7 +14508,7 @@ async function executeRenderPipeline(input) {
           engineConfig: cfg,
           // Same value the streaming encoder above spreads — the disk and
           // chunked-concat encoders need an identical GOP lock for HLS.
-          ...hlsEncoderGopLock,
+          ...deliveryEncoder,
           abortSignal: executionSignal,
           assertNotAborted,
           onProgress
@@ -14402,7 +14564,7 @@ async function executeRenderPipeline(input) {
             "capture_disk",
             "drawElement capture failed; retrying with a fresh screenshot session"
           );
-          rmSync12(framesDir, { recursive: true, force: true });
+          rmSync10(framesDir, { recursive: true, force: true });
           mkdirSync10(framesDir, { recursive: true });
           resetCaptureAttemptProgress(job);
           dedupPerfs.length = 0;
@@ -14500,7 +14662,7 @@ async function executeRenderPipeline(input) {
       buildArtifactExpectation({
         outputFormat,
         durationSeconds: job.duration,
-        fps: fpsToNumber9(job.config.fps),
+        fps: fpsToNumber8(job.config.fps),
         expectedFrames: captureTotalFrames,
         width: outputWidth,
         height: outputHeight
@@ -14930,11 +15092,12 @@ import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframes/engine";
 import { extname as extname4, isAbsolute as isAbsolute4, join as join30, relative as relative4, sep as sep3 } from "node:path";
 import {
-  fpsToNumber as fpsToNumber10,
+  fpsToNumber as fpsToNumber9,
   HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
 } from "@hyperframes/core";
 import {
   getEncoderPreset as getEncoderPreset4,
+  keyframeIntervalToGopSize as keyframeIntervalToGopSize3,
   normalizeVp9CpuUsed,
   resolveConfig as resolveConfig3,
   declareContentAddressedUrl,
@@ -15130,6 +15293,12 @@ function assertOptionalInteger(options, field, min = 0) {
     throw new Error(`Render request ${field} must be an integer >= ${min}`);
   }
 }
+function assertOptionalPositiveNumber(options, field) {
+  const value = options[field];
+  if (value !== void 0 && !(typeof value === "number" && value > 0)) {
+    throw new Error(`Render request ${field} must be a positive number`);
+  }
+}
 function assertOptionalString(options, field) {
   if (options[field] !== void 0 && typeof options[field] !== "string") {
     throw new Error(`Render request ${field} must be a string`);
@@ -15177,10 +15346,11 @@ function assertRequestOptionScalars(options) {
   assertOptionalInteger(options, "workers", 1);
   assertOptionalInteger(options, "maxRenderMs");
   assertOptionalInteger(options, "crf");
+  assertOptionalPositiveNumber(options, "keyframeIntervalSeconds");
   for (const field of ["useGpu", "debug", "outputResolutionAspectAgnostic"]) {
     assertOptionalBoolean(options, field);
   }
-  for (const field of ["entryFile", "videoBitrate"]) {
+  for (const field of ["entryFile", "videoBitrate", "maxBitrate", "bufferSize"]) {
     assertOptionalString(options, field);
   }
   assertOptionalEnum(options, "strictness", ["strict", "best-effort"]);
@@ -15341,7 +15511,7 @@ function parseRenderOptions(body) {
   const format = parseServerFormat(body.format);
   const outputDynamicRange = parseServerOutputDynamicRange(body.outputDynamicRange) ?? fromRenderHdrMode(parseLegacyServerHdrMode(body.hdrMode));
   const encoder = parseEncoderOptions(body, format ?? "mp4");
-  const { crf, videoBitrate, videoFrameFormat } = encoder.ok ? encoder.options : {};
+  const { crf, videoBitrate, videoFrameFormat, keyframeIntervalSeconds, maxBitrate, bufferSize } = encoder.ok ? encoder.options : {};
   const { variables, outputResolution, outputResolutionAspectAgnostic } = parseRenderOverrides(body);
   return {
     outputPath,
@@ -15351,6 +15521,9 @@ function parseRenderOptions(body) {
     maxRenderMs,
     crf,
     videoBitrate,
+    keyframeIntervalSeconds,
+    maxBitrate,
+    bufferSize,
     useGpu,
     debug,
     strictness,
@@ -15385,6 +15558,9 @@ function buildRenderJobConfig(input, outputPath, log) {
       maxRenderMs: input.maxRenderMs,
       crf: input.crf,
       videoBitrate: input.videoBitrate,
+      keyframeIntervalSeconds: input.keyframeIntervalSeconds,
+      maxBitrate: input.maxBitrate,
+      bufferSize: input.bufferSize,
       useGpu: input.useGpu,
       debug: input.debug,
       strictness: input.strictness,
@@ -15531,7 +15707,7 @@ function createArtifactStore(ttlMs) {
 function cleanupTempDir(dir, log) {
   if (!dir) return;
   try {
-    rmSync13(dir, { recursive: true, force: true });
+    rmSync11(dir, { recursive: true, force: true });
   } catch (error) {
     log.warn("Failed to cleanup temp project dir", {
       cleanupProjectDir: dir,