hyperframes 0.8.180 → 0.8.183

package/dist/{chunk-G2ZMCNRN.js → chunk-4UFJWRHG.js}

@@ -5,12 +5,10 @@ var require = __hf_createRequire(import.meta.url);
 var __filename = __hf_fileURLToPath(import.meta.url);
 var __dirname = __hf_dirname(__filename);
 import {
-  parseEncoderOptions
-} from "./chunk-KLIKCX6Q.js";
-import {
-  RENDER_TEMP_DIR,
-  createStudioPositionSeekReapplyScript
-} from "./chunk-EVMY7IPL.js";
+  EncoderInterruptedError,
+  encoderFailureError,
+  prepareAnimatedGifInputs
+} from "./chunk-ATMDOUNN.js";
 import {
   GENERIC_FAMILIES,
   collectFontFamilyCustomProperties,
@@ -18,12 +16,14 @@ import {
   iterateFontFamilyDeclarations,
   normalizeSystemFontPrimaryFamilies,
   resolveFontFamilyDeclarationFamilies
-} from "./chunk-B4VT6YU2.js";
+} from "./chunk-QGOYNPQT.js";
 import {
-  EncoderInterruptedError,
-  encoderFailureError,
-  prepareAnimatedGifInputs
-} from "./chunk-L527FLMV.js";
+  parseEncoderOptions
+} from "./chunk-KLIKCX6Q.js";
+import {
+  RENDER_TEMP_DIR,
+  createStudioPositionSeekReapplyScript
+} from "./chunk-EVMY7IPL.js";
 import {
   BROWSER_GPU_NOT_SOFTWARE,
   CaptureFailure,
@@ -37,6 +37,7 @@ import {
   ManagedChildProcess,
   NotMediaPayloadError,
   VIDEO_FRAME_FORMATS,
+  aacSegmentCount,
   analyzeCompositionHdr,
   analyzeKeyframeIntervals,
   appendRenderProvenanceArgs,
@@ -79,6 +80,7 @@ import {
   distributeFrames,
   distributeFramesInterleaved,
   downloadToTemp,
+  encodeAac,
   encodeFramesChunkedConcat,
   encodeFramesFromDir,
   executeParallelCapture,
@@ -112,6 +114,7 @@ import {
   isVideoFrameFormat,
   isVideoHiddenBeforeStreamStart,
   isVideoPastTimelineEnd,
+  measureVideoShownBoxes,
   mergeWorkerFrames,
   muxVideoWithAudio,
   normalizeObjectFit,
@@ -138,7 +141,6 @@ import {
   resolveFinalFrameExtractionWindow,
   resolveHeadlessShellPath,
   resolvePlayableVideoDuration,
-  resolveReferencedStart,
   resolveVideoExtractionWindow,
   runFfmpeg,
   runVideoExtractionWithRetry,
@@ -152,46 +154,35 @@ import {
   validateEngineConfigSnapshot,
   verifyDiskDrawElementSamples,
   writeCapturedFrame
-} from "./chunk-W4SLIGGM.js";
-import {
-  assignBundledRuntimeCompositionIds,
-  buildVariablesByCompScript,
-  emitMountedModuleScripts,
-  emitRootCompositionVariableStyles,
-  ensureExternalLinkTag,
-  ensureExternalScriptTag,
-  extractStandaloneEntryFromIndex,
-  inlineSubCompositions,
-  isTemplateEntry,
-  parsesAsScript,
-  prepareFlattenedInnerRoot
-} from "./chunk-4IEH6EAC.js";
-import {
-  LOW_MEMORY_TOTAL_MB_THRESHOLD,
-  getCgroupMemoryLimitMb,
-  getSystemTotalMb
-} from "./chunk-W2LGJSEN.js";
+} from "./chunk-73LTCCZI.js";
 import {
   DISTRIBUTED_FPS,
   HF_VFX_ATTR,
-  MEDIA_START_BASIS_ATTR,
   chainCapture,
   clearGifFramesBeforeNext,
-  compositionOriginSeconds,
-  cutToHostSlots,
   fpsToFfmpegArg,
   fpsToNumber,
   gifClearsAfterLeavingFrameInPlace,
   gsapCdnDist,
-  hostInPointSeconds,
   isDistributedFps,
   parseFps,
   parseVfxChain,
-  readMediaStartBasis,
-  resolveAbsoluteMediaStartSeconds,
   resolveAuthoredTimingWindow,
   toFps
-} from "./chunk-LBQFLUIY.js";
+} from "./chunk-VFBAKPRC.js";
+import {
+  assignBundledRuntimeCompositionIds,
+  buildVariablesByCompScript,
+  emitMountedModuleScripts,
+  emitRootCompositionVariableStyles,
+  ensureExternalLinkTag,
+  ensureExternalScriptTag,
+  extractStandaloneEntryFromIndex,
+  inlineSubCompositions,
+  isTemplateEntry,
+  parsesAsScript,
+  prepareFlattenedInnerRoot
+} from "./chunk-WT4PYV2J.js";
 import {
   COMPOSITION_SOURCE_URL,
   HF_COLOR_GRADING_ATTR,
@@ -219,7 +210,7 @@ import {
   shouldClampResolvedMediaDuration,
   sourceTimeAt,
   styleElementsFor
-} from "./chunk-BAZ5LCR3.js";
+} from "./chunk-GMNHAOMJ.js";
 import {
   MAX_AUDIO_GAIN
 } from "./chunk-UJKQWGFF.js";
@@ -234,24 +225,36 @@ import {
   normalizeResolutionFlag,
   suggestMatchingPreset
 } from "./chunk-YMS5FOMC.js";
+import {
+  TRANSITIONS,
+  convertTransfer,
+  crossfade
+} from "./chunk-3GXQPCJC.js";
 import {
   redactKnownPaths,
   redactTelemetryString
 } from "./chunk-634HSJ3J.js";
 import {
   chromeMajorCeiling
-} from "./chunk-537IYAEE.js";
+} from "./chunk-4UMPIPCQ.js";
 import {
-  lintHyperframeHtml
-} from "./chunk-GK2FIKIQ.js";
+  lintHyperframeHtml,
+  resolveReferencedStart
+} from "./chunk-ADDHW2FS.js";
 import {
   isUnresolvedAssetPlaceholder,
   readProjectFile,
   resolveProjectRelativeSrc
 } from "./chunk-6BNTGNGD.js";
 import {
-  checkSubCompositionUsability
-} from "./chunk-32GKETR7.js";
+  MEDIA_START_BASIS_ATTR,
+  checkSubCompositionUsability,
+  compositionOriginSeconds,
+  cutToHostSlots,
+  hostInPointSeconds,
+  readMediaStartBasis,
+  resolveAbsoluteMediaStartSeconds
+} from "./chunk-MMQ52NIZ.js";
 import {
   CSS_URL_RE,
   decodedUrlPath,
@@ -264,10 +267,10 @@ import {
   parseHTML
 } from "./chunk-SDYDNHEE.js";
 import {
-  TRANSITIONS,
-  convertTransfer,
-  crossfade
-} from "./chunk-3GXQPCJC.js";
+  LOW_MEMORY_TOTAL_MB_THRESHOLD,
+  getCgroupMemoryLimitMb,
+  getSystemTotalMb
+} from "./chunk-W2LGJSEN.js";
 
 // ../producer/src/services/renderOrchestrator.ts
 import {
@@ -1595,7 +1598,7 @@ function pidScope() {
   return {
     host: hostname(),
     // Without /proc (macOS, Windows) the boot time, to the minute, stands in for the boot id.
-    boot: attempt(() => readFileSync2("/proc/sys/kernel/random/boot_id", "utf-8").trim()) ?? String(Math.round(Date.now() / 6e4 - uptime() / 60)),
+    boot: attempt(() => readFileSync2("/proc/sys/kernel/random/boot_id", "utf-8").trim()) ?? attempt(() => String(Math.round(Date.now() / 6e4 - uptime() / 60))),
     pidns: attempt(() => readlinkSync("/proc/self/ns/pid"))
   };
 }
@@ -1613,9 +1616,14 @@ function alive(pid) {
     return error.code === "EPERM";
   }
 }
-function inThisPidScope(owner) {
+function knownPidScope() {
   const scope = pidScope();
-  return owner.host === scope.host && owner.boot === scope.boot && owner.pidns === scope.pidns;
+  const unknown = scope.boot === void 0 || process.platform === "linux" && scope.pidns === void 0;
+  return unknown ? void 0 : scope;
+}
+function inThisPidScope(owner) {
+  const scope = knownPidScope();
+  return scope !== void 0 && owner.host === scope.host && owner.boot === scope.boot && owner.pidns === scope.pidns;
 }
 function ownerState(dir) {
   let owner;
@@ -1680,7 +1688,9 @@ async function defaultArtifactDurationProbe(path) {
   const meta = await extractMediaMetadata(path);
   return {
     durationSeconds: meta.durationSeconds,
-    frames: meta.frames
+    frames: meta.frames,
+    width: meta.width,
+    height: meta.height
   };
 }
 function buildArtifactExpectation(input) {
@@ -1689,7 +1699,9 @@ function buildArtifactExpectation(input) {
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
     fps: input.fps,
-    expectedFrames: input.expectedFrames
+    expectedFrames: input.expectedFrames,
+    expectedWidth: input.width,
+    expectedHeight: input.height
   };
   if (input.outputFormat !== "hls") return expectation;
   return {
@@ -1757,6 +1769,16 @@ function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPa
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
 }
+function assertSizeMatches(expected, probed, stagingPath) {
+  const { expectedWidth: width, expectedHeight: height } = expected;
+  if (width === void 0 || height === void 0) return;
+  if (probed.width === void 0 || probed.height === void 0) return;
+  const fits = (want, got) => got === want || got === want + want % 2;
+  if (fits(width, probed.width) && fits(height, probed.height)) return;
+  throw new Error(
+    `Render artifact has the wrong size: expected ${width}x${height}, probed ${probed.width}x${probed.height}. Artifact: ${stagingPath}`
+  );
+}
 var ArtifactTransaction = class {
   constructor(destinationPath, kind, fileSystem = defaultFileSystem, durationProbe = defaultArtifactDurationProbe) {
     this.kind = kind;
@@ -1829,6 +1851,7 @@ var ArtifactTransaction = class {
     if (expected.expectedFrames !== void 0) {
       assertFrameCountWithinTolerance(expected.expectedFrames, probed.frames, probePath);
     }
+    assertSizeMatches(expected, probed, probePath);
   }
   async runDurationProbe(probePath) {
     try {
@@ -3307,7 +3330,9 @@ function aggregateDrawElement(perfs, de) {
   if (perfs.length === 0) return void 0;
   const modes = [...new Set(perfs.map((p) => p.captureMode).filter(Boolean))].sort();
   const gateReasons = [
-    ...new Set(perfs.map((p) => p.deGateReason).filter((r) => !!r))
+    ...new Set(
+      [de.probeGateReason, ...perfs.map((p) => p.deGateReason)].filter((r) => !!r)
+    )
   ].sort();
   const gpuRenderers = [
     ...new Set(perfs.map((p) => p.gpuRenderer).filter((r) => !!r))
@@ -6579,7 +6604,7 @@ async function readLocalFont(absPath) {
   return { kind: "inline", buffer: Buffer.concat(chunks, totalBytes) };
 }
 async function embedLocalFontFaces(html, projectDir) {
-  const { fontToDataUri: toDataUri } = await import("./deterministicFonts-L7YEEFGI.js");
+  const { fontToDataUri: toDataUri } = await import("./deterministicFonts-JFLSSKRB.js");
   const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
   const fontFaceRe = /@font-face\s*\{([^}]*)\}/gi;
   let result = html;
@@ -8336,6 +8361,7 @@ async function runAudioStage(input) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    keepEncoderInputAt,
     abortSignal,
     assertNotAborted,
     log
@@ -8355,7 +8381,13 @@ async function runAudioStage(input) {
         audioOutputPath,
         duration,
         abortSignal,
-        { ffmpegProcessTimeout, audioGain, masterFxChain, urlByAbsentLocalPath },
+        {
+          ffmpegProcessTimeout,
+          audioGain,
+          masterFxChain,
+          urlByAbsentLocalPath,
+          keepEncoderInputAt
+        },
         compiledDir
       );
     } catch (err) {
@@ -8455,13 +8487,29 @@ function inspectDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, free
   }
   return { available: false, estimatedBytes, freeBytes };
 }
-function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis) {
+function diskCaptureRemedy(cfg, outputFormat, durationSeconds, workerCount) {
+  const oneWorker = explainStreamingEncodeGate(cfg, outputFormat, 1, durationSeconds);
+  if (workerCount > 1 && oneWorker.enabled) {
+    return `This render stores frames because it captures with ${workerCount} workers. Free up disk space, or re-run this render with --workers 1 to stream frames into the encoder instead. One worker is slower, so keep the default worker count for renders that fit on disk.`;
+  }
+  switch (oneWorker.reason) {
+    case "format_excluded":
+      return `${outputFormat} output stores every frame at any worker count. Free up disk space or render to mp4.`;
+    case "disabled_by_config":
+      return "PRODUCER_ENABLE_STREAMING_ENCODE=false sends every render to disk. Free up disk space or unset it.";
+    case "duration_cap":
+      return "The streaming duration cap (PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED=true) sends renders longer than PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS to disk at any worker count. Free up disk space, unset the cap, or use --low-memory-mode, which streams past it on one worker.";
+    default:
+      return "Free up disk space.";
+  }
+}
+function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remedy) {
   const basisNote = basis === "measured" ? ` (measured from the first ${DISK_PROJECTION_SAMPLE_FRAMES} frames)` : "";
   return new Error(
-    `Disk capture may need ~${(needBytes / 1e6).toFixed(1)} MB of temporary frame storage${basisNote}, but only ${(freeBytes / 1e6).toFixed(1)} MB is free at ${framesDir}. Disk capture stores every frame as an image file (JPEG, or PNG for alpha). mp4/mov renders stream instead: always at --workers 1, and multi-worker on Linux BeginFrame capture. This render landed on disk because the output is png-sequence or gif, because it is multi-worker screenshot capture (opt in with HF_CAPTURE_PARALLEL_STREAM=true), or because streaming was switched off: HF_CAPTURE_PARALLEL_STREAM=false, PRODUCER_ENABLE_STREAMING_ENCODE=false, or the duration cap (PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED=true) on a render longer than PRODUCER_STREAMING_ENCODE_MAX_DURATION_SECONDS. HDR and shader-transition renders never reach this check; they run their own compositor. Re-run with --workers 1, use --low-memory-mode, or free up disk space.`
+    `Disk capture may need ~${(needBytes / 1e6).toFixed(1)} MB of temporary frame storage${basisNote}, but only ${(freeBytes / 1e6).toFixed(1)} MB is free at ${framesDir}. Disk capture stores every frame as an image file (JPEG, or PNG for alpha). ${remedy}`
   );
 }
-function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, freeDiskBytes) {
+function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, remedy, freeDiskBytes) {
   const headroom = inspectDiskCaptureHeadroom(
     framesDir,
     totalFrames,
@@ -8473,7 +8521,8 @@ function assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, freeD
     headroom.estimatedBytes,
     headroom.freeBytes,
     framesDir,
-    "estimate"
+    "estimate",
+    remedy
   );
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
@@ -8493,7 +8542,7 @@ function measureCaptureFrameBytes(workDir, framesDir) {
   return total;
 }
 function createDiskCaptureProjection(input) {
-  const { framesDir, totalFrames, measureBytes, freeDiskBytes = freeDiskBytesAt } = input;
+  const { framesDir, totalFrames, measureBytes, remedy, freeDiskBytes = freeDiskBytesAt } = input;
   let checked = false;
   return (capturedFrames) => {
     if (checked || capturedFrames < DISK_PROJECTION_SAMPLE_FRAMES) return;
@@ -8505,7 +8554,7 @@ function createDiskCaptureProjection(input) {
     if (remaining <= 0 || freeBytes === null) return;
     const needBytes = Math.ceil(measured / capturedFrames * remaining);
     if (needBytes > freeBytes * 0.9) {
-      throw diskCaptureShortfallError(needBytes, freeBytes, framesDir, "measured");
+      throw diskCaptureShortfallError(needBytes, freeBytes, framesDir, "measured", remedy);
     }
   };
 }
@@ -8547,11 +8596,13 @@ async function runCaptureStage(input) {
     }
   }
   const captureOptions = buildCaptureOptions();
-  assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions);
+  const remedy = diskCaptureRemedy(cfg, job.config.format ?? "mp4", job.duration ?? 0, workerCount);
+  assertDiskCaptureHeadroom(framesDir, totalFrames, captureOptions, remedy);
   const checkDiskProjection = createDiskCaptureProjection({
     framesDir,
     totalFrames,
-    measureBytes: () => measureCaptureFrameBytes(workDir, framesDir)
+    measureBytes: () => measureCaptureFrameBytes(workDir, framesDir),
+    remedy
   });
   if (workerCount > 1) {
     const attempts = await executeDiskCaptureWithAdaptiveRetry({
@@ -9727,8 +9778,10 @@ function fpsToFfmpegArg2(fps) {
 }
 var KEEP_FILTER_GRAPH_WHEN_FRAMES_DROP_ALPHA = ["-reinit_filter", "0"];
 var WRITE_EVERY_FRAME_WHOLE = ["-gifflags", "0"];
+var FAIL_ON_UNREADABLE_FRAME_INSTEAD_OF_ENDING_THERE = ["-xerror"];
 function framesInput(input, fpsArg) {
   return [
+    ...FAIL_ON_UNREADABLE_FRAME_INSTEAD_OF_ENDING_THERE,
     "-framerate",
     fpsArg,
     ...KEEP_FILTER_GRAPH_WHEN_FRAMES_DROP_ALPHA,
@@ -9974,28 +10027,82 @@ import { extname as extname3 } from "path";
 import { spawn } from "child_process";
 import { mkdtempSync as mkdtempSync3, renameSync as renameSync3, rmSync as rmSync7 } from "fs";
 import { dirname as dirname8, join as join24 } from "path";
+
+// ../producer/src/services/render/audioTruePeak.ts
+var toDbfs = (token) => token.toLowerCase() === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
+function checkedDbfs(value) {
+  if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
+    throw new Error("[audioTruePeak] FFmpeg did not report AAC true peak");
+  }
+  return value;
+}
+async function scanTruePeak(audioPath, trim, timeoutMs, signal) {
+  let firstBlock;
+  let laterBlocks = Number.NEGATIVE_INFINITY;
+  let partialLine = "";
+  const readLines = (chunk) => {
+    const lines = (partialLine + chunk).split(/\r|\n/);
+    partialLine = lines.pop() ?? "";
+    for (const line of lines) {
+      const ftpk = /FTPK:([^d]*)dBFS/.exec(line)?.[1];
+      if (!ftpk) continue;
+      const block = Math.max(...ftpk.trim().split(/\s+/).map(toDbfs));
+      if (firstBlock === void 0) firstBlock = block;
+      else laterBlocks = Math.max(laterBlocks, block);
+    }
+  };
+  const result = await runFfmpeg(
+    ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", `${trim}ebur128=peak=true`, "-f", "null", "-"],
+    { signal, timeout: timeoutMs, onStderr: readLines }
+  );
+  if (!result.success) {
+    throw new Error(`[audioTruePeak] ${describeFfmpegFailure(result, timeoutMs)}`);
+  }
+  const summary = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
+  return {
+    peak: checkedDbfs(toDbfs(summary.at(-1)?.[1] ?? "nan")),
+    firstBlock: checkedDbfs(firstBlock ?? Number.NEGATIVE_INFINITY),
+    laterBlocks: checkedDbfs(laterBlocks)
+  };
+}
+async function measureTruePeakDbfs(audioPath, options) {
+  const { timeoutMs, signal } = options;
+  const wholeFile = async () => (await scanTruePeak(audioPath, "", timeoutMs, signal)).peak;
+  const { durationSeconds, sampleRate } = await extractAudioMetadata(audioPath, { signal });
+  const block = 4800;
+  const count = sampleRate === 48e3 && Number.isFinite(durationSeconds) ? aacSegmentCount(durationSeconds) : 1;
+  if (count === 1) return wholeFile();
+  const cut = (k) => k * Math.floor(durationSeconds * 10 / count) * block;
+  const peers = new AbortController();
+  const segmentSignal = signal ? AbortSignal.any([signal, peers.signal]) : peers.signal;
+  const scans = await Promise.all(
+    Array.from({ length: count }, (_, k) => {
+      const start = k === 0 ? 0 : cut(k) - block;
+      const end = k === count - 1 ? "" : `:end_sample=${cut(k + 1)}`;
+      return scanTruePeak(
+        audioPath,
+        `atrim=start_sample=${start}${end},`,
+        timeoutMs,
+        segmentSignal
+      );
+    })
+  ).catch((error) => {
+    peers.abort();
+    throw error;
+  });
+  const last = scans[count - 1];
+  const counted = Math.max(scans[0].peak, ...scans.slice(1).map((scan) => scan.laterBlocks));
+  if (last.peak > last.firstBlock || last.peak <= counted) return Math.max(counted, last.peak);
+  return wholeFile();
+}
+
+// ../producer/src/services/render/audioPadTrim.ts
 var AUDIO_DURATION_TOLERANCE_SECONDS = 1e-3;
 var AAC_DELIVERY_TRUE_PEAK_DBFS = -1;
 var AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB = 0.5;
 var MAX_TRUE_PEAK_CORRECTION_PASSES = 3;
-function buildAacTruePeakCorrectionArgs(inputPath, outputPath, targetDurationSeconds, attenuationDb) {
-  return [
-    "-i",
-    inputPath,
-    "-map",
-    "0:a:0",
-    "-vn",
-    "-af",
-    `volume=${attenuationDb.toFixed(3)}dB`,
-    "-t",
-    formatSeconds(targetDurationSeconds),
-    "-c:a",
-    "aac",
-    "-b:a",
-    "192k",
-    "-y",
-    outputPath
-  ];
+function aacTruePeakCorrectionFilter(targetDurationSeconds, attenuationDb) {
+  return `volume=${attenuationDb.toFixed(3)}dB,apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
 }
 function buildPadTrimAudioPlan(audioPath, outputPath, sourceDurationSeconds, targetDurationSeconds) {
   const delta = targetDurationSeconds - sourceDurationSeconds;
@@ -10010,53 +10117,13 @@ function buildPadTrimAudioPlan(audioPath, outputPath, sourceDurationSeconds, tar
   if (delta > 0) {
     return {
       operation: "pad",
-      steps: [
-        {
-          kind: "normalize",
-          args: [
-            "-i",
-            audioPath,
-            "-af",
-            `apad,atrim=0:${targetSec}`,
-            "-t",
-            targetSec,
-            "-c:a",
-            "aac",
-            "-b:a",
-            "192k",
-            "-y",
-            outputPath
-          ]
-        }
-      ],
+      steps: [{ kind: "normalize", filter: `apad,atrim=0:${targetSec}` }],
       cleanupPaths: []
     };
   }
   return {
     operation: "trim",
-    steps: [
-      {
-        kind: "trim",
-        args: [
-          "-i",
-          audioPath,
-          "-af",
-          `atrim=duration=${targetSec},asetpts=PTS-STARTPTS`,
-          // `atrim` limits decoded samples but does not cap muxer timestamps
-          // introduced by encoder delay/flush.  The output duration contract
-          // is enforced at the container boundary as well; without `-t`, a
-          // long primed source can retain its original tail after re-encode.
-          "-t",
-          targetSec,
-          "-c:a",
-          "aac",
-          "-b:a",
-          "192k",
-          "-y",
-          outputPath
-        ]
-      }
-    ],
+    steps: [{ kind: "trim", filter: `atrim=duration=${targetSec},asetpts=PTS-STARTPTS` }],
     cleanupPaths: []
   };
 }
@@ -10073,7 +10140,8 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   const probeAudio = input.probeAudioInfo ?? defaultProbeAudioInfo;
   const timeoutMs = input.timeoutMs ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
   const runner = input.runFfmpeg ?? ((args) => defaultRunFfmpeg(args, timeoutMs, input.signal));
-  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg ? void 0 : (audioPath, signal) => defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal));
+  const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal);
+  const probeTruePeak = input.probeAudioTruePeakDbfs ?? (input.runFfmpeg || input.encodeAac ? void 0 : (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }));
   const [videoResult, audioResult] = await Promise.allSettled([
     probeVideo(input.videoPath),
     probeAudio(input.audioPath, input.signal)
@@ -10120,7 +10188,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   );
   try {
     for (const step of plan2.steps) {
-      const ffmpegResult = await runner(step.args);
+      const ffmpegResult = step.kind === "copy" ? await runner(step.args) : await encode(input.audioPath, input.outputPath, targetDurationSeconds, step.filter);
       if (!ffmpegResult.success) {
         return {
           success: false,
@@ -10152,7 +10220,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
       targetDurationSeconds,
       signal: input.signal,
       probeTruePeak,
-      runner
+      encode
     });
     if (!correction.success) {
       return {
@@ -10182,8 +10250,8 @@ async function constrainAacTruePeak(input) {
     audioPath: input.audioPath,
     targetDurationSeconds: input.targetDurationSeconds,
     signal: input.signal,
-    probeTruePeak: (audioPath, signal) => defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal),
-    runner: (args) => defaultRunFfmpeg(args, timeoutMs, input.signal)
+    probeTruePeak: (audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal }),
+    encode: defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
   });
 }
 async function enforceAacTruePeak(input) {
@@ -10210,13 +10278,11 @@ async function enforceAacTruePeak(input) {
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
       attenuationDb += correctionTargetDbfs - truePeakDbfs;
-      const result = await input.runner(
-        buildAacTruePeakCorrectionArgs(
-          input.audioPath,
-          correctedPath,
-          input.targetDurationSeconds,
-          attenuationDb
-        )
+      const result = await input.encode(
+        input.audioPath,
+        correctedPath,
+        input.targetDurationSeconds,
+        aacTruePeakCorrectionFilter(input.targetDurationSeconds, attenuationDb)
       );
       if (!result.success) {
         return {
@@ -10319,24 +10385,19 @@ async function defaultProbeAudioInfo(audioPath, signal) {
     audioCodec: metadata.audioCodec
   };
 }
-async function defaultProbeAudioTruePeakDbfs(audioPath, timeoutMs, signal) {
-  const result = await runFfmpeg(
-    ["-i", audioPath, "-map", "0:a:0", "-vn", "-af", "ebur128=peak=true", "-f", "null", "-"],
-    { signal, timeout: timeoutMs }
-  );
-  if (!result.success) {
-    throw new Error(`[audioPadTrim] ${describeFfmpegFailure(result, timeoutMs)}`);
-  }
-  const matches = [...result.stderr.matchAll(/^\s*Peak:\s*([+-]?(?:[\d.]+|inf)) dBFS$/gim)];
-  const token = matches.at(-1)?.[1]?.toLowerCase();
-  const value = token === "-inf" ? Number.NEGATIVE_INFINITY : Number(token);
-  if (Number.isNaN(value) || value === Number.POSITIVE_INFINITY) {
-    throw new Error("[audioPadTrim] FFmpeg did not report AAC true peak");
-  }
-  return value;
-}
 async function defaultRunFfmpeg(args, timeoutMs, signal) {
-  const result = await runFfmpeg(args, { signal, timeout: timeoutMs });
+  return toStepResult(await runFfmpeg(args, { signal, timeout: timeoutMs }), timeoutMs);
+}
+function defaultAacEncoder(timeoutMs, signal, pcmSourcePath) {
+  return async (inputPath, outputPath, durationSeconds, filter) => {
+    const options = pcmSourcePath ? { signal, timeout: timeoutMs, filter } : { signal, timeout: timeoutMs, filter, segments: 1 };
+    return toStepResult(
+      await encodeAac(pcmSourcePath ?? inputPath, outputPath, durationSeconds, options),
+      timeoutMs
+    );
+  };
+}
+function toStepResult(result, timeoutMs) {
   if (result.success) return { success: true };
   return {
     success: false,
@@ -10524,7 +10585,7 @@ function assertOutputScaleSupported(deviceScaleFactor, route) {
   const reason = UNSUPPORTED_REASON2[route];
   if (reason === null) return;
   throw new Error(
-    `[Render] --resolution other than the composition's size is not supported on the "${route}" capture route: ${reason}. Render at the composition's size, or as mp4 with page-side compositing.`
+    `[Render] --resolution other than the composition's size is not supported on the "${route}" capture route: ${reason}. Render at the composition's size; or, for HDR footage, add --sdr to render this size in standard colour; or, for shader transitions, render as mp4.`
   );
 }
 
@@ -10742,7 +10803,7 @@ function getNextRetryWorkerCount(currentWorkers) {
   return Math.max(1, Math.floor(currentWorkers / 2));
 }
 function resolveRenderWorkDirPrefix(outputPath, jobId, platform2 = process.platform, systemTempDir = tmpdir2()) {
-  if (platform2 === "win32") return join25(systemTempDir, "hf-render-");
+  if (platform2 === "win32" || platform2 === "darwin") return join25(systemTempDir, "hf-render-");
   return join25(dirname9(outputPath), `work-${jobId}-`);
 }
 var MAX_TRANSIENT_CAPTURE_RETRIES = 1;
@@ -11236,6 +11297,9 @@ function resolveDeShortBand(args) {
 function shouldPreferSingleWorkerDrawElement(args) {
   return args.workerCount > 1 && typeof args.requestedWorkers !== "number" && args.useDrawElement && !args.deCompileGate && !args.forceScreenshot && outputUsesH264Pipeline(args.outputFormat) && args.minFrames > 0 && args.totalFrames >= args.minFrames && args.singleWorkerStreamingOk && !args.layeredOrEffectRoute && !args.supersampling && !args.probeDeGated && !args.experimentalParallelDeOptIn;
 }
+function isProbeDeGated(session) {
+  return session !== null && session.captureMode !== "drawelement" && !session.deInitDeferred;
+}
 function resolveInversionRetryPlan(args) {
   if (args.deWorkerInversion !== "inverted") return null;
   const workerCount = args.isMemoryExhaustion ? 1 : args.preInversionWorkerCount;
@@ -11317,7 +11381,8 @@ async function closeOrphanedProbeForRetry(probe, closer, log, retryContext) {
 }
 function resolveParallelCaptureMode(args) {
   const supersampling = (args.deviceScaleFactor ?? 1) !== 1;
-  return args.headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling ? "beginframe" : "screenshot";
+  const headlessShell = args.headlessShellPath !== void 0;
+  return headlessShell && args.platform === "linux" && !args.forceScreenshot && !supersampling ? "beginframe" : "screenshot";
 }
 function isCaptureParallelStreamRouterEnabled(env, resolvedMode) {
   const raw = env.HF_CAPTURE_PARALLEL_STREAM?.trim().toLowerCase();
@@ -11925,6 +11990,7 @@ async function executeRenderPipeline(input) {
     );
     const nativeHdrIds = /* @__PURE__ */ new Set([...nativeHdrVideoIds, ...nativeHdrImageIds]);
     const hasHdrContent = Boolean(effectiveHdr && nativeHdrIds.size > 0);
+    if (hasHdrContent) assertOutputScaleSupported(deviceScaleFactor, "hdr_layered");
     const deSingleMinFramesRaw = process.env.HF_DE_SINGLE_MIN_FRAMES;
     const deSingleMinFramesNum = deSingleMinFramesRaw === void 0 || deSingleMinFramesRaw.trim() === "" ? 900 : Number(deSingleMinFramesRaw);
     const deSingleMinFrames = Number.isFinite(deSingleMinFramesNum) ? deSingleMinFramesNum : 900;
@@ -11965,7 +12031,7 @@ async function executeRenderPipeline(input) {
       singleWorkerStreamingOk: shouldUseStreamingEncode(cfg, outputFormat, 1, job.duration),
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
       supersampling: deviceScaleFactor !== 1,
-      probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
+      probeDeGated: isProbeDeGated(probeSession),
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || // Verified parallel DE streaming (opt-in) wants its parallelism kept.
       process.env.HF_DE_PARALLEL_STREAM === "true"
     };
@@ -11974,14 +12040,14 @@ async function executeRenderPipeline(input) {
       ...deInversionArgs,
       minFrames: Math.min(deSingleMinFrames, deShortBandMinFrames)
     });
-    const deShortBand = resolveDeShortBand({
+    let deShortBand = resolveDeShortBand({
       invertAtBaseFloor,
       invertAtBandFloor,
       bandEnabled: deShortBandEnabled,
       bandOpen: deShortBandOpen,
       elementCountSource: compositionElementCountSource
     });
-    const deInversionEligible = deShortBandRoute && deShortBand === "applied" ? invertAtBandFloor : invertAtBaseFloor;
+    let deInversionEligible = deShortBandRoute && deShortBand === "applied" ? invertAtBandFloor : invertAtBaseFloor;
     const deInversionEffectiveMinFrames = deShortBandRoute && deShortBand === "applied" ? Math.min(deSingleMinFrames, deShortBandMinFrames) : deSingleMinFrames;
     const deParallelRouterEnabled = isDeParallelRouterEnabled(process.env);
     const deParallelMinFramesRaw = process.env.HF_DE_PARALLEL_MIN_FRAMES;
@@ -11990,7 +12056,7 @@ async function executeRenderPipeline(input) {
     const deParallelMinMemRaw = process.env.HF_DE_PARALLEL_MIN_MEM_MB;
     const deParallelMinMemNum = deParallelMinMemRaw === void 0 || deParallelMinMemRaw.trim() === "" ? 24576 : Number(deParallelMinMemRaw);
     const deParallelMinMemoryMb = Number.isFinite(deParallelMinMemNum) ? deParallelMinMemNum : 24576;
-    const deParallelRouterEligible = shouldPreferParallelDrawElement({
+    let deParallelRouterEligible = shouldPreferParallelDrawElement({
       workerCount: WOULD_RESOLVE_MULTI_WORKER,
       requestedWorkers: job.config.workers,
       useDrawElement: cfg.useDrawElement,
@@ -12001,7 +12067,7 @@ async function executeRenderPipeline(input) {
       minFrames: deParallelMinFrames,
       layeredOrEffectRoute: hasHdrContent || compiled.hasShaderTransitions,
       supersampling: deviceScaleFactor !== 1,
-      probeDeGated: probeSession !== null && probeSession.captureMode !== "drawelement" && !probeSession.deInitDeferred,
+      probeDeGated: isProbeDeGated(probeSession),
       experimentalParallelDeOptIn: process.env.PRODUCER_EXPERIMENTAL_FAST_CAPTURE === "true" || process.env.HF_DE_PARALLEL_STREAM === "true",
       routerEnabled: deParallelRouterEnabled,
       // Router pins 3 workers for the streaming path; don't pin when a
@@ -12017,6 +12083,35 @@ async function executeRenderPipeline(input) {
       totalMemoryMb: Math.round(totalmem2() / (1024 * 1024)),
       minMemoryMb: deParallelMinMemoryMb
     });
+    if (probeSession === null && (deInversionEligible || deParallelRouterEligible)) {
+      try {
+        probeSession = await createCaptureSession(
+          activeFileServer.url,
+          framesDir,
+          buildCaptureOptions(),
+          null,
+          { ...cfg, forceScreenshot: captureForceScreenshot }
+        );
+        await initializeSession(probeSession);
+      } catch (error) {
+        assertNotAborted();
+        if (probeSession) {
+          lastBrowserConsole = probeSession.browserConsoleBuffer;
+          await closeCaptureSession(probeSession).catch(() => {
+          });
+          probeSession = null;
+        }
+        log.warn("[Render] Fast capture gate check failed; routing without it.", {
+          error: error instanceof Error ? error.message : String(error)
+        });
+      }
+      if (isProbeDeGated(probeSession)) {
+        deInversionEligible = false;
+        deParallelRouterEligible = false;
+        deShortBand = void 0;
+      }
+    }
+    const deProbeGateReason = isProbeDeGated(probeSession) ? probeSession.deGateReason : void 0;
     let workerCount;
     const captureStageObservationData = (extra = {}) => ({
       stagePhase: "capturing",
@@ -12204,7 +12299,7 @@ async function executeRenderPipeline(input) {
     }
     const parallelCaptureMode = resolveParallelCaptureMode({
       platform: process.platform,
-      headlessShell: resolveHeadlessShellPath(cfg) !== null,
+      headlessShellPath: resolveHeadlessShellPath(cfg),
       forceScreenshot: captureForceScreenshot,
       deviceScaleFactor: captureOptions.deviceScaleFactor
     });
@@ -12976,7 +13071,9 @@ async function executeRenderPipeline(input) {
         outputFormat,
         durationSeconds: job.duration,
         fps: fpsToNumber(job.config.fps),
-        expectedFrames: captureTotalFrames
+        expectedFrames: captureTotalFrames,
+        width: outputWidth,
+        height: outputHeight
       })
     );
     const totalElapsed = Date.now() - pipelineStart;
@@ -13012,6 +13109,7 @@ async function executeRenderPipeline(input) {
       drawElement: {
         compileGate: deCompileGate,
         clampReason: deClampReason,
+        probeGateReason: deProbeGateReason,
         workerInversion: deWorkerInversion,
         preInversionWorkers: deWorkerInversion ? preRoutingWorkerCount : void 0,
         compositionElementCount,
@@ -13564,6 +13662,29 @@ function buildChunkCaptureOptions(input) {
     requiresWebGpu: compositionRequiresWebGpu(input.html)
   };
 }
+function shownDeferredFrameIndexes(planVideos, frames, fps) {
+  const shown = /* @__PURE__ */ new Map();
+  const deferred = planVideos.extracted.filter((video) => video.deferredRange);
+  if (deferred.length === 0) return shown;
+  const table = createFrameLookupTable(
+    planVideos.videos,
+    deferred.map((video) => ({
+      ...video,
+      outputDir: "",
+      framePaths: new Map(Array.from({ length: video.totalFrames }, (_, i) => [i, String(i)]))
+    })),
+    resolveRenderFpsConfig(fps).value
+  );
+  for (const frame of frames) {
+    const globalTime = frame * fps.den / fps.num;
+    for (const [videoId, payload] of table.getActiveFramePayloads(globalTime)) {
+      const indexes = shown.get(videoId) ?? /* @__PURE__ */ new Set();
+      indexes.add(payload.frameIndex);
+      shown.set(videoId, indexes);
+    }
+  }
+  return shown;
+}
 async function extractDeferredVideoFramesForChunk(input) {
   const deferred = input.planVideos.extracted.filter((video) => video.deferredRange);
   const remoteSources = input.remoteSources ?? {};
@@ -13580,24 +13701,7 @@ async function extractDeferredVideoFramesForChunk(input) {
     });
   }
   if (deferred.length === 0) return [];
-  const table = createFrameLookupTable(
-    input.planVideos.videos,
-    deferred.map((video) => ({
-      ...video,
-      outputDir: input.outputRoot,
-      framePaths: new Map(Array.from({ length: video.totalFrames }, (_, i) => [i, String(i)]))
-    })),
-    resolveRenderFpsConfig(input.fps).value
-  );
-  const shown = /* @__PURE__ */ new Map();
-  for (const frame of input.frames) {
-    const globalTime = frame * input.fps.den / input.fps.num;
-    for (const [videoId, payload] of table.getActiveFramePayloads(globalTime)) {
-      const indexes = shown.get(videoId) ?? /* @__PURE__ */ new Set();
-      indexes.add(payload.frameIndex);
-      shown.set(videoId, indexes);
-    }
-  }
+  const shown = shownDeferredFrameIndexes(input.planVideos, input.frames, input.fps);
   return Promise.all(
     deferred.map(async (video) => {
       const outputDir = join27(input.outputRoot, video.videoId);
@@ -13623,7 +13727,8 @@ async function extractDeferredVideoFramesForChunk(input) {
           fps: input.fps,
           outputDir: input.outputRoot,
           format: range.format,
-          frameRanges: contiguousRuns(indexes)
+          frameRanges: contiguousRuns(indexes),
+          shownBox: input.shownBoxes?.get(video.videoId)
         },
         void 0,
         input.cfg
@@ -14275,6 +14380,20 @@ function withDuration(buf, target, duration) {
 function timescaleOf(buf, header) {
   return buf.readUInt32BE(header.bodyStart + (buf[header.bodyStart] === 1 ? 20 : 12));
 }
+var TRACK_ID_AT = { tkhd: [12, 20], mvhd: [96, 108] };
+function idOf(buf, target) {
+  return buf.readUInt32BE(
+    target.bodyStart + TRACK_ID_AT[target.type][buf[target.bodyStart] === 1 ? 1 : 0]
+  );
+}
+function withId(boxBytes, type, id) {
+  const header = boxAt(boxBytes, 0, 0, boxBytes.length);
+  boxBytes.writeUInt32BE(
+    id,
+    header.bodyStart + TRACK_ID_AT[type][boxBytes[header.bodyStart] === 1 ? 1 : 0]
+  );
+  return boxBytes;
+}
 function buildStbl(stsd, track) {
   const stts = runs(track.durations);
   const stsc = [];
@@ -14316,24 +14435,48 @@ function planTracksOf(tracks, plan2, index) {
   }
   return matched;
 }
-function buildStitchedHeader(layouts) {
-  const plan2 = readTracks(layouts[0].moov);
-  const chunks = layouts.map((layout, i) => planTracksOf(readTracks(layout.moov), plan2, i));
+function sourceTracks(layouts, audio) {
+  const chunkPlan = readTracks(layouts[0].moov);
+  const audioTracks = audio ? readTracks(audio.moov) : [];
+  if (audio && (audioTracks.length !== 1 || audioTracks[0].handler !== "soun")) {
+    throw new Error("[mp4Stitch] the separate audio file must hold one audio track");
+  }
+  const plan2 = [...chunkPlan, ...audioTracks];
+  const chunks = layouts.map((layout, i) => {
+    const tracks = readTracks(layout.moov);
+    if (audio && tracks.some((track) => track.handler === "soun")) {
+      throw new Error(`[mp4Stitch] chunk ${i} carries its own audio`);
+    }
+    return planTracksOf(tracks, plan2, i);
+  });
+  return {
+    plan: plan2,
+    chunkTrackCount: chunkPlan.length,
+    sources: audio ? [[...chunkPlan.map(() => null), audioTracks[0]], ...chunks] : chunks
+  };
+}
+function buildStitchedHeader(layouts, audio) {
+  const { plan: plan2, chunkTrackCount, sources } = sourceTracks(layouts, audio);
+  const sourceLayouts = audio ? [audio, ...layouts] : layouts;
   const payloadBases = [];
   let payloadBytes = 0;
-  for (const layout of layouts) {
+  for (const layout of sourceLayouts) {
     payloadBases.push(payloadBytes);
     payloadBytes += layout.payloadEnd - layout.payloadStart;
   }
   const template = layouts[0].moov;
   const root = boxAt(template, 0, 0, template.length);
-  const movieTimescale = timescaleOf(template, child(template, root, "mvhd"));
+  const mvhd = child(template, root, "mvhd");
+  const movieTimescale = timescaleOf(template, mvhd);
+  const chunkTrackIds = plan2.slice(0, chunkTrackCount).map((track) => idOf(template, child(template, track.trak, "tkhd")));
+  const audioTrackId = Math.max(...chunkTrackIds) + 1;
   const buildMoov = (dataStart2) => {
     const traks = plan2.map((track, t) => {
-      const parts = chunks.flatMap((tracks, chunk) => {
+      const parts = sources.flatMap((tracks, chunk) => {
         const part = tracks[t];
         return part ? [{ ...part, chunk }] : [];
       });
+      const moov = t < chunkTrackCount ? template : audio.moov;
       const merged = {
         durations: parts.flatMap((part) => part.durations),
         sizes: parts.flatMap((part) => part.sizes),
@@ -14342,9 +14485,9 @@ function buildStitchedHeader(layouts) {
         chunkOffsets: parts.flatMap(
           (part) => part.chunkOffsets.map((offset) => {
             const i = part.chunk;
-            const { payloadStart, payloadEnd } = layouts[i];
+            const { payloadStart, payloadEnd } = sourceLayouts[i];
             if (offset < payloadStart || offset >= payloadEnd) {
-              throw new Error(`[mp4Stitch] chunk ${i} has samples outside its mdat`);
+              throw new Error(`[mp4Stitch] source ${i} has samples outside its mdat`);
             }
             return offset - payloadStart + payloadBases[i] + dataStart2;
           })
@@ -14360,20 +14503,25 @@ function buildStitchedHeader(layouts) {
       elst.writeBigInt64BE(BigInt(track.mediaTime), 12);
       elst.writeUInt32BE(65536, 20);
       const edts = track.mediaTime ? box("edts", fullBox("elst", 1, elst)) : Buffer.alloc(0);
-      const trak = rebuild(template, track.trak, {
-        tkhd: (tkhd) => Buffer.concat([withDuration(template, tkhd, shown), edts]),
+      const tkhdOf = (tkhd) => {
+        const timed = withDuration(moov, tkhd, shown);
+        return t < chunkTrackCount ? timed : withId(timed, "tkhd", audioTrackId);
+      };
+      const trak = rebuild(moov, track.trak, {
+        tkhd: (tkhd) => Buffer.concat([tkhdOf(tkhd), edts]),
         edts: () => Buffer.alloc(0),
-        mdia: (mdia) => rebuild(template, mdia, {
-          mdhd: (mdhd) => withDuration(template, mdhd, mediaDuration),
-          minf: (minf) => rebuild(template, minf, { stbl: () => buildStbl(track.stsd, merged) })
+        mdia: (mdia) => rebuild(moov, mdia, {
+          mdhd: (mdhd) => withDuration(moov, mdhd, mediaDuration),
+          minf: (minf) => rebuild(moov, minf, { stbl: () => buildStbl(track.stsd, merged) })
         })
       });
       return { trak, shown };
     });
     let next = 0;
+    const movieHeader = withDuration(template, mvhd, Math.max(...traks.map((t) => t.shown)));
     return rebuild(template, root, {
-      mvhd: (mvhd) => withDuration(template, mvhd, Math.max(...traks.map((t) => t.shown))),
-      trak: () => traks[next++].trak
+      mvhd: () => audio ? withId(movieHeader, "mvhd", audioTrackId + 1) : movieHeader,
+      trak: () => ++next < chunkTrackCount ? traks[next - 1].trak : Buffer.concat(traks.slice(next - 1).map((t) => t.trak))
     });
   };
   const ftyp = layouts[0].ftyp;
@@ -14406,15 +14554,16 @@ async function copyPayload(path, layout, index, out) {
     );
   }
 }
-async function writeStitchedMp4(chunkPaths, outputPath) {
-  const layouts = await Promise.all(chunkPaths.map((path) => readMp4Layout(fileRange(path))));
-  const header = buildStitchedHeader(layouts);
+async function writeStitchedMp4(chunkPaths, outputPath, audioPath) {
+  const sourcePaths = audioPath ? [audioPath, ...chunkPaths] : chunkPaths;
+  const layouts = await Promise.all(sourcePaths.map((path) => readMp4Layout(fileRange(path))));
+  const header = audioPath ? buildStitchedHeader(layouts.slice(1), layouts[0]) : buildStitchedHeader(layouts);
   mkdirSync10(dirname11(outputPath), { recursive: true });
   const workDir = mkdtempSync4(`${outputPath}.stitch-`);
   const out = createWriteStream(join30(workDir, "out.mp4"));
   try {
     out.write(header);
-    for (const [i, path] of chunkPaths.entries()) await copyPayload(path, layouts[i], i, out);
+    for (const [i, path] of sourcePaths.entries()) await copyPayload(path, layouts[i], i, out);
     out.end();
     await finished(out);
     renameSync4(join30(workDir, "out.mp4"), outputPath);
@@ -14985,7 +15134,8 @@ function buildLockedRenderConfig(input) {
     chunkCount: input.chunkCount,
     runtimeEnv: input.runtimeEnv,
     variables: config.variables,
-    ...input.chunksCarryAudio ? { chunksCarryAudio: true } : {}
+    ...input.chunksCarryAudio ? { chunksCarryAudio: true } : {},
+    ...input.separateAudio ? { separateAudio: true } : {}
   };
 }
 function carriesChunkAudio(config, options) {
@@ -15080,8 +15230,10 @@ function createVideoSourceShipper(input) {
     return result;
   };
 }
-async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, options = {}) {
-  const planDir = executionPlanDir;
+function plansSeparateAudio(config, options) {
+  return options.deferAudio === true && config.format === "mp4" && config.cfr !== true;
+}
+async function compilePlanComposition(projectDir, config, planDir, options) {
   rejectUnsupportedDistributedFormat(config);
   validateNoGpuEncode({
     useGpu: false,
@@ -15209,7 +15361,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   if (probeResult.fileServer) closeFileServerSafely(probeResult.fileServer, "plan", log);
   if (probeResult.probeSession) {
     try {
-      const { closeCaptureSession: closeCaptureSession2 } = await import("./src-XRTZOBO5.js");
+      const { closeCaptureSession: closeCaptureSession2 } = await import("./src-EL6HGIS4.js");
       await closeCaptureSession2(probeResult.probeSession);
     } catch (err) {
       log.warn("[plan] probe session close failed", {
@@ -15217,6 +15369,100 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
       });
     }
   }
+  return {
+    projectDir,
+    log,
+    sizeLimitBytes,
+    abortSignal,
+    assertNotAborted,
+    cfg,
+    job,
+    workDir,
+    compiledDir,
+    finalCompiledDir,
+    remoteFiles,
+    urlByAbsentLocalPath,
+    localPathByUrl,
+    compileResult,
+    compiled,
+    composition,
+    deviceScaleFactor,
+    forceScreenshot,
+    width,
+    height,
+    probeResult,
+    totalFrames
+  };
+}
+function mixPlanAudio(c, compiledDir, seconds, pcmPath) {
+  return runAudioStage({
+    projectDir: c.projectDir,
+    workDir: c.workDir,
+    compiledDir,
+    urlByAbsentLocalPath: c.urlByAbsentLocalPath,
+    duration: seconds,
+    ffmpegProcessTimeout: c.cfg.ffmpegProcessTimeout,
+    audioGain: c.cfg.audioGain,
+    audios: c.composition.audios,
+    masterFxChain: c.composition.masterFxChain,
+    ...pcmPath ? { keepEncoderInputAt: pcmPath } : {},
+    abortSignal: c.abortSignal,
+    assertNotAborted: c.assertNotAborted
+  });
+}
+async function extractPlanVideos(c, deferRangeExtraction) {
+  const extractResult = await runExtractVideosStage({
+    projectDir: c.projectDir,
+    compiledDir: c.compiledDir,
+    job: c.job,
+    cfg: c.cfg,
+    composition: c.composition,
+    abortSignal: c.abortSignal,
+    assertNotAborted: c.assertNotAborted,
+    materializeSymlinks: true,
+    deferRangeExtraction,
+    urlByAbsentLocalPath: c.urlByAbsentLocalPath
+  });
+  if (extractResult.failureToEnforce) throw extractResult.failureToEnforce;
+  if (extractResult.extractionResult) {
+    assertVideoExtractionSucceeded(extractResult.extractionResult);
+  }
+  return extractResult;
+}
+async function holdPlanAudioPeak(c, audioPath, pcmPath, seconds) {
+  const peak = await constrainAacTruePeak({
+    audioPath,
+    ...existsSync20(pcmPath) ? { sourcePath: pcmPath } : {},
+    targetDurationSeconds: seconds,
+    signal: c.abortSignal,
+    timeoutMs: c.cfg.ffmpegProcessTimeout
+  }).finally(() => rmSync10(pcmPath, { force: true }));
+  if (!peak.success) throw encoderFailureError("[plan] audio true-peak check failed", peak);
+}
+async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, options = {}) {
+  const planDir = executionPlanDir;
+  const c = await compilePlanComposition(projectDir, config, planDir, options);
+  const {
+    log,
+    sizeLimitBytes,
+    cfg,
+    job,
+    workDir,
+    compiledDir,
+    finalCompiledDir,
+    remoteFiles,
+    urlByAbsentLocalPath,
+    localPathByUrl,
+    compileResult,
+    compiled,
+    composition,
+    deviceScaleFactor,
+    forceScreenshot,
+    width,
+    height,
+    probeResult,
+    totalFrames
+  } = c;
   const megapixels = compileResult.outputWidth * compileResult.outputHeight / 1e6;
   let maxParallel = resolveMaxParallelChunks(config, totalFrames, megapixels, log);
   const measureFrameCost = chunkSizingUsesFrameCost(config) && planNeedsFrameCostMeasurement(compiled.html);
@@ -15227,24 +15473,9 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     observedAt: "pre-extract",
     log
   });
-  stageStarted = Date.now();
-  const extractResult = await runExtractVideosStage({
-    projectDir,
-    compiledDir,
-    job,
-    cfg,
-    composition,
-    abortSignal,
-    assertNotAborted,
-    materializeSymlinks: true,
-    deferRangeExtraction: options.deferVideoExtraction,
-    urlByAbsentLocalPath
-  });
+  let stageStarted = Date.now();
+  const extractResult = await extractPlanVideos(c, options.deferVideoExtraction);
   logPlanStage(log, "extract", stageStarted);
-  if (extractResult.failureToEnforce) throw extractResult.failureToEnforce;
-  if (extractResult.extractionResult) {
-    assertVideoExtractionSucceeded(extractResult.extractionResult);
-  }
   const stagedVideoFrames = join33(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join33(planDir, "video-frames");
   if (existsSync20(videoFramesDst)) rmSync10(videoFramesDst, { recursive: true, force: true });
@@ -15300,23 +15531,18 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     "utf-8"
   );
   const digests = options.digests ?? /* @__PURE__ */ new Map();
-  const chunksCarryAudio2 = carriesChunkAudio(config, options);
-  const audioSeconds = chunksCarryAudio2 ? totalFrames / config.fps : probeResult.duration;
+  const separateAudio = plansSeparateAudio(config, options);
+  const chunksCarryAudio = !separateAudio && carriesChunkAudio(config, options);
+  const audioSeconds = chunksCarryAudio ? totalFrames / config.fps : probeResult.duration;
+  const planMixPcmPath = join33(workDir, "plan-mix.wav");
   stageStarted = Date.now();
   const [audioOutcome, overlapOutcome, frameCostOutcome] = await Promise.allSettled([
-    runAudioStage({
-      projectDir,
-      workDir,
-      compiledDir: finalCompiledDir,
-      urlByAbsentLocalPath,
-      duration: audioSeconds,
-      ffmpegProcessTimeout: cfg.ffmpegProcessTimeout,
-      audioGain: cfg.audioGain,
-      audios: composition.audios,
-      masterFxChain: composition.masterFxChain,
-      abortSignal,
-      assertNotAborted
-    }).finally(() => logPlanStage(log, "audio", stageStarted)),
+    separateAudio ? null : mixPlanAudio(
+      c,
+      finalCompiledDir,
+      audioSeconds,
+      chunksCarryAudio ? planMixPcmPath : void 0
+    ).finally(() => logPlanStage(log, "audio", stageStarted)),
     (async () => {
       for (const dir of [finalCompiledDir, videoFramesDst, videoSourcesDir]) {
         await prehashPlanFiles(dir, digests);
@@ -15366,22 +15592,16 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   );
   const chunks = buildChunkSlices(totalFrames, chunkCount, effectiveChunkSize);
   const audioResult = audioOutcome.value;
-  if (audioResult.audioError) {
+  if (audioResult?.audioError) {
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
   const planAudioPath = join33(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult.hasAudio && existsSync20(audioResult.audioOutputPath)) {
+  if (audioResult?.hasAudio && existsSync20(audioResult.audioOutputPath)) {
     renameSync5(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio2 && existsSync20(planAudioPath)) {
+  if (chunksCarryAudio && existsSync20(planAudioPath)) {
     stageStarted = Date.now();
-    const peak = await constrainAacTruePeak({
-      audioPath: planAudioPath,
-      targetDurationSeconds: audioSeconds,
-      signal: abortSignal,
-      timeoutMs: cfg.ffmpegProcessTimeout
-    });
-    if (!peak.success) throw encoderFailureError("[plan] audio true-peak check failed", peak);
+    await holdPlanAudioPeak(c, planAudioPath, planMixPcmPath, audioSeconds);
     logPlanStage(log, "audio-peak", stageStarted);
     if (options.sliceChunkAudio) {
       stageStarted = Date.now();
@@ -15407,7 +15627,8 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     effectiveChunkSize,
     chunkCount,
     runtimeEnv,
-    chunksCarryAudio: chunksCarryAudio2
+    chunksCarryAudio,
+    separateAudio
   });
   const compositionJson = {
     durationSeconds: job.duration ?? 0,
@@ -15452,7 +15673,7 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     fontSnapshotSha,
     durationSeconds: job.duration ?? 0,
     totalFrames,
-    hasAudio: audioResult.hasAudio,
+    hasAudio: audioResult?.hasAudio ?? false,
     digests
   });
   logPlanStage(log, "freeze", stageStarted);
@@ -16803,7 +17024,7 @@ function startServer(options = {}) {
   });
   async function shutdown(signal) {
     log.info(`Received ${signal}, shutting down`);
-    const { drainBrowserPool } = await import("./src-XRTZOBO5.js");
+    const { drainBrowserPool } = await import("./src-EL6HGIS4.js");
     await drainBrowserPool().catch(() => {
     });
     const handle = await Promise.race([
@@ -17427,7 +17648,8 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
         )
       ),
       chunksCarryAudio: options.chunksCarryAudio,
-      sliceChunkAudio: true
+      sliceChunkAudio: true,
+      deferAudio: options.deferAudio
     });
     return await publishExecutionPlan(stagingRoot, publisher, { digests, log: config.logger });
   } catch (error) {
@@ -17753,7 +17975,8 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
     return mergePngFrameDirs(chunkPaths, outputPath, plan2.totalFrames, audioPath, start);
   }
   if (chunksAreStitchedMp4(planDir, cfr)) {
-    await writeStitchedMp4(chunkPaths, outputPath);
+    const separateAudio = stitchesSeparateAudio(planDir) && audioPath !== null;
+    await writeStitchedMp4(chunkPaths, outputPath, separateAudio ? audioPath : void 0);
     return {
       outputPath,
       durationMs: Date.now() - start,
@@ -17951,16 +18174,20 @@ async function runAssembleFfmpeg(args, step, signal, timeout) {
   }
 }
 function chunksAreStitchedMp4(planDir, cfr) {
-  if (!chunksCarryAudio(planDir)) return false;
+  const { chunksCarryAudio, separateAudio } = lockedAudio(planDir);
+  if (!chunksCarryAudio && !separateAudio) return false;
   if (cfr) {
-    throw new Error("[assemble] cfr=true cannot re-encode a plan whose mp4 chunks carry audio");
+    throw new Error("[assemble] cfr=true cannot re-encode a plan whose mp4 chunks are stitched");
   }
   return true;
 }
-function chunksCarryAudio(planDir) {
+function stitchesSeparateAudio(planDir) {
+  return lockedAudio(planDir).separateAudio === true;
+}
+function lockedAudio(planDir) {
   const encoderJsonPath = join40(planDir, "meta", "encoder.json");
-  if (!existsSync26(encoderJsonPath)) return false;
-  return JSON.parse(readFileSync13(encoderJsonPath, "utf-8")).chunksCarryAudio === true;
+  if (!existsSync26(encoderJsonPath)) return {};
+  return JSON.parse(readFileSync13(encoderJsonPath, "utf-8"));
 }
 function readCfrEncoder(planDir, format) {
   if (format !== "mp4") {
@@ -18244,34 +18471,15 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     const framesDir = join41(workDir, "captured-frames");
     mkdirSync17(framesDir, { recursive: true });
     const videoFramesDir = `${workDir}.video-frames`;
-    const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
-      planDir,
-      planVideos,
-      frames: Array.from({ length: framesInChunk }, (_, i) => range.startFrame + i),
-      fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
-      outputRoot: videoFramesDir,
-      cfg,
-      remoteSources
-    }) : [];
+    const chunkFrameNumbers = Array.from({ length: framesInChunk }, (_, i) => range.startFrame + i);
+    const chunkFps = { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen };
+    const deferredVideos = planVideos?.extracted.filter((video) => video.deferredRange) ?? [];
+    const shownFrames = planVideos ? shownDeferredFrameIndexes(planVideos, chunkFrameNumbers, chunkFps) : /* @__PURE__ */ new Map();
     const remoteVideoIds = new Set(
       planVideos?.extracted.filter(
         (video) => video.deferredRange && Object.hasOwn(remoteSources, video.deferredRange.sourcePath)
       ).map((video) => video.videoId)
     );
-    const remoteVideos = deferredVideoFrames.filter((video) => remoteVideoIds.has(video.videoId));
-    const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable(
-      planVideos.videos,
-      [
-        ...rebuildExtractedFramesFromPlanDir(
-          planDir,
-          planVideos.extracted.filter((video) => !video.deferredRange),
-          v2Manifest === null ? "dense-v1" : "sparse-v2"
-        ),
-        ...deferredVideoFrames
-      ],
-      resolveRenderFpsConfig(job.config.fps).value
-    ) : null;
-    const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
     const fileServer = await createFileServer({
       projectDir: compiledDir,
       compiledDir,
@@ -18287,8 +18495,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       videoCount: planVideos?.videos.length ?? 0,
       html: readFileSync14(join41(compiledDir, "index.html"), "utf-8"),
       // The plan ships a deferred source only to chunks that show it; don't wait on the rest.
-      skipReadinessVideoIds: deferredVideoFrames.filter((video) => video.framePaths.size === 0 || remoteVideoIds.has(video.videoId)).map((video) => video.videoId),
-      videoMetadataHints: collectVideoMetadataHints(remoteVideos)
+      skipReadinessVideoIds: deferredVideos.filter(
+        (video) => !shownFrames.get(video.videoId)?.size || remoteVideoIds.has(video.videoId)
+      ).map((video) => video.videoId),
+      videoMetadataHints: collectVideoMetadataHints(
+        deferredVideos.filter((video) => remoteVideoIds.has(video.videoId))
+      )
     });
     const chunkWorkerCount = calculateOptimalWorkers(framesInChunk, void 0, cfg);
     let session = null;
@@ -18301,6 +18513,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
     const capturePerfs = [];
     const captureAttempts = [];
     let forceScreenshotForChunk = encoder.forceScreenshot;
+    let shownBoxes;
     try {
       if (chunkWorkerCount === 1 || !forceScreenshotForChunk) {
         const bootStarted = Date.now();
@@ -18311,6 +18524,11 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           cfg
         );
         sessionBootMs = Date.now() - bootStarted;
+        shownBoxes = await measureVideoShownBoxes(
+          session.page,
+          [...shownFrames.keys()],
+          chunkFrameNumbers.map((frame) => frame * chunkFps.den / chunkFps.num)
+        );
         const browserSelectedScreenshot = session.launchCaptureMode === "screenshot";
         const beginFrameStalled = !browserSelectedScreenshot && await beginFrameSessionNeedsScreenshotFallback(session);
         if (browserSelectedScreenshot) {
@@ -18352,6 +18570,29 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
           session = null;
         }
       }
+      const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
+        planDir,
+        planVideos,
+        frames: chunkFrameNumbers,
+        fps: chunkFps,
+        outputRoot: videoFramesDir,
+        cfg,
+        remoteSources,
+        shownBoxes
+      }) : [];
+      const videoFrameLookup = planVideos && planVideos.extracted.length > 0 ? createFrameLookupTable(
+        planVideos.videos,
+        [
+          ...rebuildExtractedFramesFromPlanDir(
+            planDir,
+            planVideos.extracted.filter((video) => !video.deferredRange),
+            v2Manifest === null ? "dense-v1" : "sparse-v2"
+          ),
+          ...deferredVideoFrames
+        ],
+        resolveRenderFpsConfig(job.config.fps).value
+      ) : null;
+      const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
         forceScreenshot: forceScreenshotForChunk,
@@ -18542,6 +18783,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       encodeStageMs,
       workers: chunkWorkerCount,
       captureMode,
+      // Device-pixel box each video's frames were extracted to cover; a video not listed kept full size.
+      videoShownBoxes: Object.fromEntries(shownBoxes ?? []),
       sha256,
       outputKind,
       producerVersion: plan2.producerVersion,
@@ -18611,9 +18854,10 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
 }
 
 // ../producer/src/services/distributed/projectHash.ts
-import { readdirSync as readdirSync12, readFileSync as readFileSync15, realpathSync as realpathSync2, statSync as statSync11 } from "fs";
+import { closeSync as closeSync8, openSync as openSync7, readdirSync as readdirSync12, readSync as readSync5, realpathSync as realpathSync2, statSync as statSync11 } from "fs";
 import { createHash as createHash7 } from "crypto";
 import { join as join43 } from "path";
+var READ_CHUNK_BYTES = 256 * 1024;
 
 export {
   createConsoleLogger,