@hyperframes/producer 0.8.206 → 0.8.207

package/dist/index.js

@@ -5,7 +5,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,
@@ -14,7 +14,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,
@@ -810,7 +810,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;
@@ -835,7 +835,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 };
@@ -845,6 +845,41 @@ 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 chunkGopFrames(framesInChunk, intervalFrames) {
+  return Math.min(framesInChunk, intervalFrames ?? framesInChunk);
+}
+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,
@@ -1864,7 +1899,7 @@ function replanSegmentedAfterFailure(plan2, failure) {
   const keepSegmenting = failure.kind === "draw_element_verification" || failure.kind === "draw_element_capture";
   return createCapturePlan({
     ...plan2,
-    forceScreenshot: keepSegmenting || failure.kind === "capture_failure",
+    forceScreenshot: plan2.forceScreenshot || keepSegmenting || failure.kind === "capture_failure",
     useStreamingEncode: true,
     useLayeredComposite: false,
     useSegmentedCapture: keepSegmenting,
@@ -1934,7 +1969,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() {
@@ -2205,7 +2240,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,
@@ -2790,7 +2825,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";
@@ -3093,7 +3128,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;
@@ -3931,7 +3966,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,
@@ -3944,143 +3978,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);
@@ -4241,7 +4290,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 {
@@ -4335,6 +4384,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);
@@ -4665,8 +4720,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);
@@ -4813,7 +4870,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,
@@ -5017,7 +5074,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...");
@@ -5477,7 +5534,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
@@ -5512,7 +5569,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);
@@ -6774,7 +6831,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 });
@@ -6801,45 +6858,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));
@@ -6853,7 +6917,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
@@ -6870,7 +6934,8 @@ async function compileHtmlFile(html, baseDir, downloadDir, log, urlByAbsentLocal
         el.tagName,
         el.id,
         log,
-        urlByAbsentLocalPath
+        urlByAbsentLocalPath,
+        probes
       ).then(({ duration }) => ({ id: el.id, duration }))
     )
   );
@@ -6891,7 +6956,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 };
     })
@@ -6913,7 +6980,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]");
@@ -6941,14 +7008,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,
@@ -7718,19 +7787,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(
@@ -7833,9 +7905,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));
@@ -8386,13 +8461,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
@@ -8430,8 +8506,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(
@@ -8439,7 +8522,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) {
@@ -8865,7 +8948,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) {
@@ -8928,7 +9011,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 {
@@ -9464,16 +9547,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,
@@ -9482,6 +9566,7 @@ import {
   extractAudioMetadata as extractAudioMetadata3,
   getFfprobeBinary,
   ManagedChildProcess,
+  removeScratch,
   renameWithRetry as renameWithRetry5,
   runFfmpeg as runFfmpeg5,
   trackChildProcess
@@ -9677,7 +9762,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
       error: `audioPadTrim: failed to materialize ${plan2.operation}: ${err instanceof Error ? err.message : String(err)}`
     };
   } finally {
-    for (const path of plan2.cleanupPaths) rmSync9(path, { force: true });
+    for (const path of plan2.cleanupPaths) removeScratch(path);
   }
   let loweredDb = 0;
   if (probeTruePeak) {
@@ -9740,7 +9825,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;
@@ -9781,7 +9866,7 @@ async function enforceAacTruePeak(input) {
       )}`
     };
   } finally {
-    if (scratchDir) rmSync9(scratchDir, { recursive: true, force: true });
+    if (scratchDir) removeScratch(scratchDir);
   }
 }
 function failResult(outputPath, target, source, error) {
@@ -9926,7 +10011,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;
@@ -9948,7 +10041,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) {
@@ -10428,7 +10521,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";
@@ -11102,6 +11195,7 @@ async function runCaptureHdrStage(input) {
     preset,
     effectiveQuality,
     effectiveBitrate,
+    deliveryEncoder,
     fileServer,
     buildCaptureOptions,
     createRenderVideoFrameInjector,
@@ -11163,7 +11257,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),
@@ -11191,6 +11285,7 @@ async function runCaptureHdrStage(input) {
         preset: preset.preset,
         quality: effectiveQuality,
         bitrate: effectiveBitrate,
+        ...deliveryEncoder,
         pixelFormat: preset.pixelFormat,
         hdr: preset.hdr,
         rawInputFormat: "rgb48le"
@@ -11250,7 +11345,7 @@ async function runCaptureHdrStage(input) {
         beforeCaptureHook: domSession.onBeforeCapture,
         width,
         height,
-        fps: fpsToNumber8(job.config.fps),
+        fps: fpsToNumber7(job.config.fps),
         compositeTransfer,
         nativeHdrImageIds,
         hdrImageBuffers,
@@ -11394,7 +11489,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";
@@ -11533,7 +11628,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) {
@@ -11557,6 +11652,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,
@@ -12831,6 +12928,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 });
@@ -12851,7 +12949,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({
@@ -12909,11 +13007,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",
@@ -13153,7 +13254,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;
@@ -13996,6 +14097,7 @@ async function executeRenderPipeline(input) {
             preset,
             effectiveQuality,
             effectiveBitrate,
+            deliveryEncoder,
             fileServer: activeFileServer,
             buildCaptureOptions,
             createRenderVideoFrameInjector,
@@ -14020,9 +14122,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({
@@ -14037,6 +14137,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,
@@ -14062,71 +14165,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;
@@ -14146,7 +14307,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" });
@@ -14199,7 +14360,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,
@@ -14362,7 +14523,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
@@ -14418,7 +14579,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;
@@ -14516,7 +14677,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
@@ -14735,16 +14896,17 @@ import {
   existsSync as existsSync21,
   linkSync,
   mkdirSync as mkdirSync14,
-  rmSync as rmSync14,
+  rmSync as rmSync12,
   writeFileSync as writeFileSync9
 } from "node:fs";
 import { extname as extname6, isAbsolute as isAbsolute3, join as join35, relative as relative5, sep as sep2 } 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,
@@ -15770,7 +15932,7 @@ import { join as join33 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure3, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
 
 // src/services/distributed/mp4Stitch.ts
-import { createReadStream as createReadStream4, createWriteStream, mkdirSync as mkdirSync12, mkdtempSync as mkdtempSync4, rmSync as rmSync13 } from "node:fs";
+import { createReadStream as createReadStream4, createWriteStream, mkdirSync as mkdirSync12, mkdtempSync as mkdtempSync4, rmSync as rmSync11 } from "node:fs";
 import { open } from "node:fs/promises";
 import { renameWithRetry as renameWithRetry6 } from "@hyperframes/engine";
 import { dirname as dirname13, join as join32 } from "node:path";
@@ -16148,7 +16310,7 @@ async function writeStitchedMp4(chunkPaths, outputPath, audioPath) {
     renameWithRetry6(join32(workDir, "out.mp4"), outputPath);
   } finally {
     out.destroy();
-    rmSync13(workDir, { recursive: true, force: true });
+    rmSync11(workDir, { recursive: true, force: true });
   }
 }
 
@@ -16656,7 +16818,7 @@ var FREEZE_OWNED_PLAN_FILES = [
 ];
 function removeFreezeOwnedPlanFiles(planDir) {
   for (const relativePath of FREEZE_OWNED_PLAN_FILES) {
-    rmSync14(join35(planDir, relativePath), { force: true });
+    rmSync12(join35(planDir, relativePath), { force: true });
   }
 }
 function buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize) {
@@ -16716,6 +16878,9 @@ function buildLockedRenderConfig(input) {
     preset,
     crf: config.crf,
     bitrate: config.bitrate,
+    maxBitrate: config.maxBitrate,
+    bufferSize: config.bufferSize,
+    keyframeIntervalFrames: config.keyframeIntervalSeconds === void 0 ? void 0 : keyframeIntervalToGopSize3({ num: config.fps, den: 1 }, config.keyframeIntervalSeconds),
     ...locksVp9CpuUsed,
     // GOP === chunkSize so every chunk's first frame is an IDR keyframe and
     // ffmpeg concat-copy round-trips losslessly.
@@ -16867,7 +17032,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join35(planDir, ".plan-work");
-  rmSync14(workDir, { recursive: true, force: true });
+  rmSync12(workDir, { recursive: true, force: true });
   mkdirSync14(workDir, { recursive: true });
   const compiledDir = join35(workDir, "compiled");
   mkdirSync14(compiledDir, { recursive: true });
@@ -16960,7 +17125,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   validateDistributedDuration({
     duration: probeResult.duration,
     totalFrames,
-    fps: fpsToNumber10(job.config.fps)
+    fps: fpsToNumber9(job.config.fps)
   });
   if (probeResult.fileServer) closeFileServerSafely(probeResult.fileServer, "plan", log);
   if (probeResult.probeSession) {
@@ -17074,15 +17239,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join35(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join35(planDir, "video-frames");
-  if (existsSync21(videoFramesDst)) rmSync14(videoFramesDst, { recursive: true, force: true });
+  if (existsSync21(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join35(planDir, "video-sources");
-  rmSync14(videoSourcesDir, { recursive: true, force: true });
+  rmSync12(videoSourcesDir, { recursive: true, force: true });
   if (existsSync21(stagedVideoFrames)) {
     renameWithRetry7(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync14(videoFramesDst, { recursive: true });
   }
-  if (existsSync21(finalCompiledDir)) rmSync14(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync21(finalCompiledDir)) rmSync12(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry7(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -17250,7 +17415,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     format: config.format
   };
   try {
-    rmSync14(workDir, { recursive: true, force: true });
+    rmSync12(workDir, { recursive: true, force: true });
   } catch (err) {
     log.warn("[plan] failed to remove temp work dir", {
       workDir,
@@ -17401,6 +17566,20 @@ function validateDistributedRenderConfig(config) {
       `must look like "10M" or "5000k"; got ${JSON.stringify(config.bitrate)}`
     );
   }
+  try {
+    validateDeliveryEncoderConfig({
+      format: config.format,
+      fps: { num: config.fps, den: 1 },
+      keyframeIntervalSeconds: config.keyframeIntervalSeconds,
+      maxBitrate: config.maxBitrate,
+      bufferSize: config.bufferSize
+    });
+  } catch (error) {
+    throw new InvalidConfigError(
+      "config.maxBitrate",
+      error instanceof Error ? error.message : String(error)
+    );
+  }
   if (config.chunkSize !== void 0) {
     if (!Number.isInteger(config.chunkSize) || config.chunkSize < 1) {
       throw new InvalidConfigError(
@@ -17580,6 +17759,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`);
@@ -17627,10 +17812,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"]);
@@ -17733,6 +17919,9 @@ function distributedConfigFromRequest(request, runtime = {}) {
     crf: options.crf,
     pageMotionBlur: options.pageMotionBlur,
     bitrate: options.videoBitrate,
+    keyframeIntervalSeconds: options.keyframeIntervalSeconds,
+    maxBitrate: options.maxBitrate,
+    bufferSize: options.bufferSize,
     videoFrameFormat: options.videoFrameFormat,
     outputResolution: options.outputResolution,
     outputResolutionAspectAgnostic: options.outputResolutionAspectAgnostic,
@@ -17780,6 +17969,9 @@ function renderRequestFromDistributedConfig(input) {
     ...optionalProperty("crf", config.crf),
     ...optionalProperty("pageMotionBlur", config.pageMotionBlur),
     ...optionalProperty("videoBitrate", config.bitrate),
+    ...optionalProperty("keyframeIntervalSeconds", config.keyframeIntervalSeconds),
+    ...optionalProperty("maxBitrate", config.maxBitrate),
+    ...optionalProperty("bufferSize", config.bufferSize),
     ...optionalProperty("videoFrameFormat", config.videoFrameFormat),
     ...optionalProperty("outputResolution", config.outputResolution),
     ...optionalProperty("outputResolutionAspectAgnostic", config.outputResolutionAspectAgnostic),
@@ -17825,7 +18017,7 @@ import {
   statSync as statSync10,
   mkdtempSync as mkdtempSync5,
   writeFileSync as writeFileSync10,
-  rmSync as rmSync15,
+  rmSync as rmSync13,
   createReadStream as createReadStream5
 } from "node:fs";
 import { resolve as resolve11, dirname as dirname15, join as join38 } from "node:path";
@@ -18131,7 +18323,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,
@@ -18141,6 +18333,9 @@ function parseRenderOptions(body) {
     maxRenderMs,
     crf,
     videoBitrate,
+    keyframeIntervalSeconds,
+    maxBitrate,
+    bufferSize,
     useGpu,
     debug,
     strictness,
@@ -18175,6 +18370,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,
@@ -18321,7 +18519,7 @@ function createArtifactStore(ttlMs) {
 function cleanupTempDir(dir, log) {
   if (!dir) return;
   try {
-    rmSync15(dir, { recursive: true, force: true });
+    rmSync13(dir, { recursive: true, force: true });
   } catch (error) {
     log.warn("Failed to cleanup temp project dir", {
       cleanupProjectDir: dir,
@@ -18735,7 +18933,7 @@ import {
   mkdtempSync as mkdtempSync7,
   readFileSync as readFileSync14,
   readdirSync as readdirSync9,
-  rmSync as rmSync17,
+  rmSync as rmSync15,
   statSync as statSync12,
   writeFileSync as writeFileSync12
 } from "node:fs";
@@ -18751,7 +18949,7 @@ import {
   linkSync as linkSync2,
   mkdirSync as mkdirSync16,
   mkdtempSync as mkdtempSync6,
-  rmSync as rmSync16,
+  rmSync as rmSync14,
   statSync as statSync11,
   writeFileSync as writeFileSync11
 } from "node:fs";
@@ -18846,7 +19044,7 @@ var LocalPlanV2ArtifactPublisher = class {
       }
       renameWithRetry8(temporaryPath, destinationPath);
     } finally {
-      rmSync16(stagingDir, { recursive: true, force: true });
+      rmSync14(stagingDir, { recursive: true, force: true });
     }
   }
   async commitManifest(manifestBytes) {
@@ -18863,7 +19061,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async abort() {
     if (!this.#committed) {
-      rmSync16(this.temporaryDir, { recursive: true, force: true });
+      rmSync14(this.temporaryDir, { recursive: true, force: true });
     }
   }
 };
@@ -19132,7 +19330,7 @@ function writeBlob(sourcePath, destinationPath) {
     copyFileSync8(sourcePath, temporaryPath);
     renameWithRetry9(temporaryPath, destinationPath);
   } finally {
-    rmSync17(temporaryDir, { recursive: true, force: true });
+    rmSync15(temporaryDir, { recursive: true, force: true });
   }
 }
 function publishBlobFor(absolutePath, digests) {
@@ -19265,7 +19463,7 @@ function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
     renameWithRetry9(tempDir, planV2Dir);
     return resultFromManifest(planV2Dir, publication.manifest);
   } catch (error) {
-    rmSync17(tempDir, { recursive: true, force: true });
+    rmSync15(tempDir, { recursive: true, force: true });
     throw error;
   }
 }
@@ -19332,7 +19530,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
     }
     throw error;
   } finally {
-    rmSync17(stagingRoot, { recursive: true, force: true });
+    rmSync15(stagingRoot, { recursive: true, force: true });
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
@@ -19549,7 +19747,7 @@ function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}
     );
     renameWithRetry9(tempDir, destinationDir);
   } catch (error) {
-    rmSync17(tempDir, { recursive: true, force: true });
+    rmSync15(tempDir, { recursive: true, force: true });
     throw error;
   }
   return {
@@ -19613,7 +19811,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
 }
 
 // src/services/distributed/planV2Execution.ts
-import { mkdtempSync as mkdtempSync9, rmSync as rmSync20 } from "node:fs";
+import { mkdtempSync as mkdtempSync9, rmSync as rmSync18 } from "node:fs";
 import { tmpdir as tmpdir5 } from "node:os";
 import { join as join44 } from "node:path";
 
@@ -19625,12 +19823,13 @@ import {
   mkdtempSync as mkdtempSync8,
   readFileSync as readFileSync15,
   readdirSync as readdirSync10,
-  rmSync as rmSync18,
+  rmSync as rmSync16,
   statSync as statSync13,
   writeFileSync as writeFileSync13
 } from "node:fs";
 import { dirname as dirname18, join as join42 } from "node:path";
 import {
+  appendRateCapArgs as appendRateCapArgs2,
   appendRenderProvenanceArgs as appendRenderProvenanceArgs2,
   describeFfmpegFailure as describeFfmpegFailure4,
   getEncoderPreset as getEncoderPreset5,
@@ -19704,7 +19903,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
     });
   } finally {
     try {
-      rmSync18(workDir, { recursive: true, force: true });
+      rmSync16(workDir, { recursive: true, force: true });
     } catch (err) {
       log.warn("[assemble] failed to remove work dir", {
         workDir,
@@ -19766,6 +19965,9 @@ function cfrEncodeArgs(inputArgs, encoder, fpsArg) {
     "-r",
     fpsArg
   ];
+  if (encoder.keyframeIntervalFrames !== void 0)
+    args.push("-g", String(encoder.keyframeIntervalFrames));
+  appendRateCapArgs2(args, encoder);
   appendSoftwareEncoderThreadsArg(args, "libx264");
   return args;
 }
@@ -19902,7 +20104,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync27(outputPath)) rmSync18(outputPath, { recursive: true, force: true });
+  if (existsSync27(outputPath)) rmSync16(outputPath, { recursive: true, force: true });
   mkdirSync18(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -19947,7 +20149,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync28, mkdirSync as mkdirSync19, readFileSync as readFileSync16, readdirSync as readdirSync11, rmSync as rmSync19, writeFileSync as writeFileSync14 } from "node:fs";
+import { existsSync as existsSync28, mkdirSync as mkdirSync19, readFileSync as readFileSync16, readdirSync as readdirSync11, rmSync as rmSync17, writeFileSync as writeFileSync14 } from "node:fs";
 import { cpus as cpus3 } from "node:os";
 import { join as join43 } from "node:path";
 import {
@@ -20402,7 +20604,9 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
         // first frame is an IDR keyframe and concat-copy at assemble time
         // round-trips losslessly.
         lockGopForChunkConcat: !isPngSequence,
-        gopSize: framesInChunk
+        gopSize: chunkGopFrames(framesInChunk, encoder.keyframeIntervalFrames),
+        maxBitrate: encoder.maxBitrate,
+        bufferSize: encoder.bufferSize
       };
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
@@ -20474,7 +20678,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           return observedChunkCaptureMode(capturePerfs);
         },
         resetForScreenshotRetry: () => {
-          rmSync19(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+          rmSync17(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
           mkdirSync19(framesDir, { recursive: true });
           capturePerfs.length = 0;
           captureAttempts.length = 0;
@@ -20517,8 +20721,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
           timeoutMs: cfg.ffmpegProcessTimeout
         });
-        rmSync19(videoOnlyPath, { force: true });
-        rmSync19(audioScratchPath, { force: true });
+        rmSync17(videoOnlyPath, { force: true });
+        rmSync17(audioScratchPath, { force: true });
       }
       encodeStageMs = Date.now() - encodeStarted;
     } finally {
@@ -20568,8 +20772,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     writeFileSync14(perfPath, `${JSON.stringify(perfPayload, null, 2)}
 `, "utf-8");
     try {
-      rmSync19(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
-      rmSync19(videoFramesDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync17(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
+      rmSync17(videoFramesDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
     } catch (err) {
       log.warn("[renderChunk] failed to remove work dir", {
         workDir,
@@ -20604,7 +20808,7 @@ async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
     return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
   } finally {
-    rmSync20(workRoot, { recursive: true, force: true });
+    rmSync18(workRoot, { recursive: true, force: true });
   }
 }
 async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
@@ -20624,7 +20828,7 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
       options
     );
   } finally {
-    rmSync20(workRoot, { recursive: true, force: true });
+    rmSync18(workRoot, { recursive: true, force: true });
   }
 }