@hyperframes/producer 0.9.13 → 0.9.15

package/dist/index.js

@@ -9,7 +9,7 @@ import {
 // src/services/renderOrchestrator.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics2 } from "@hyperframes/engine";
 import {
-  existsSync as existsSync18,
+  existsSync as existsSync19,
   mkdirSync as mkdirSync10,
   readdirSync as readdirSync5,
   rmSync as rmSync10,
@@ -3741,6 +3741,7 @@ function createStallClock(now = () => Date.now()) {
 
 // src/services/render/stages/captureStreamingStage.ts
 var DEFAULT_CAPTURE_STALL_MS = 6e4;
+var SESSION_INIT_STALL_MS = 3e5;
 var DE_STALL_POLL_MS = 5e3;
 var STALL_ADVICE = "Chrome stopped answering. If another app is keeping the GPU or CPU busy (a 3D render, a game, another export), let it finish or render one job at a time, then retry.";
 function poolFailure(error, probeSession) {
@@ -3771,6 +3772,14 @@ function captureModeLabel(mode) {
   if (mode === "beginframe") return "BeginFrame";
   return "screenshot";
 }
+var OPENING_CAPTURE_SESSION = {
+  captureMode: "screenshot",
+  captureStep: "opening the capture session"
+};
+var OPENING_RISK_SESSION = {
+  captureMode: "screenshot",
+  captureStep: "opening the screenshot session for effect frames"
+};
 var SequentialCaptureStallError = class extends Error {
   captureMode;
   constructor(session, stallTimeoutMs, frameIndex, totalFrames) {
@@ -3920,7 +3929,12 @@ async function runWorkerEncodePipelineLoop(session, totalFrames, job, currentEnc
   const guard = createDrainFrameGuard({ log, stats, frameTime });
   const guardFrame = (item, buf) => item.trusted ? Promise.resolve(buf) : guard(session, item.idx, buf);
   const captureRisk = async (idx) => {
-    await risk.open();
+    await raceAgainstStall(
+      risk.open(),
+      stallTimeoutMs - quiet.idle(0),
+      { session: OPENING_RISK_SESSION, frameIndex: idx, totalFrames, stallTimeoutMs },
+      abortSignal
+    );
     quiet.reset();
     return raceAgainstStall(
       risk.capture(idx, frameTime(idx)),
@@ -4279,19 +4293,38 @@ async function runCaptureStreamingStage(input) {
       let resumes = 0;
       for (; ; ) {
         const videoInjector = createRenderVideoFrameInjector();
-        const session = probeSession ?? await createCaptureSession(
-          fileServer.url,
-          framesDir,
-          buildCaptureOptions(),
-          videoInjector,
-          captureCfg
+        const initStallMs = Math.max(SESSION_INIT_STALL_MS, resolveCaptureStallTimeoutMs());
+        const setup = createStallClock();
+        const withinInitBudget = (work, stalled) => raceAgainstStall(
+          work,
+          initStallMs - setup.idle(0),
+          { session: stalled, frameIndex: resume.from, totalFrames, stallTimeoutMs: initStallMs },
+          abortSignal
         );
+        const openSession = async () => {
+          const opening = createCaptureSession(
+            fileServer.url,
+            framesDir,
+            buildCaptureOptions(),
+            videoInjector,
+            captureCfg
+          );
+          try {
+            return await withinInitBudget(opening, OPENING_CAPTURE_SESSION);
+          } catch (error) {
+            void opening.then(closeCaptureSession, () => {
+            });
+            throw error;
+          }
+        };
+        const session = probeSession ?? await openSession();
         captureBeyondViewport = session.options.captureBeyondViewport;
         if (probeSession) {
           prepareCaptureSessionForReuse(session, framesDir, videoInjector);
           probeSession = null;
         }
         let riskSession = null;
+        let attemptClosed = false;
         const openRiskSession = async () => {
           const opened = await createCaptureSession(
             fileServer.url,
@@ -4305,6 +4338,10 @@ async function runCaptureStreamingStage(input) {
               enableBrowserPool: false
             }
           );
+          if (attemptClosed) {
+            await closeCaptureSession(opened);
+            throw new Error("[Render] Capture attempt ended while its screenshot session opened");
+          }
           riskSession = opened;
           await initializeSession(opened);
           return opened;
@@ -4312,9 +4349,9 @@ async function runCaptureStreamingStage(input) {
         let resumed = false;
         try {
           if (!session.isInitialized) {
-            await initializeSession(session);
+            await withinInitBudget(initializeSession(session), session);
           }
-          await completeDeferredDrawElementInit(session);
+          await withinInitBudget(completeDeferredDrawElementInit(session), session);
           assertNotAborted();
           lastBrowserConsole = session.browserConsoleBuffer;
           if (session.workerEncodeEnabled) {
@@ -4397,6 +4434,7 @@ async function runCaptureStreamingStage(input) {
           resumes++;
           resumed = true;
         } finally {
+          attemptClosed = true;
           lastBrowserConsole = session.browserConsoleBuffer;
           await closeCaptureSession(session);
           if (riskSession) await closeCaptureSession(riskSession);
@@ -5863,7 +5901,7 @@ import { suggestMatchingPreset } from "@hyperframes/core";
 // src/services/htmlCompiler.ts
 import { decodedUrlPath } from "@hyperframes/parsers/asset-paths";
 import { createHash as createHash6 } from "node:crypto";
-import { createReadStream as createReadStream2, existsSync as existsSync10, mkdirSync as mkdirSync7 } from "fs";
+import { createReadStream as createReadStream2, existsSync as existsSync10, mkdirSync as mkdirSync7, readFileSync as readFileSync7 } from "fs";
 import { join as join15, dirname as dirname7, resolve as resolve7, basename as basename4, relative as relative2 } from "path";
 import { parseHTML as parseHTML5 } from "linkedom";
 import {
@@ -7838,6 +7876,25 @@ ${fontFaceBlocks.join("\n")}
   }
   return result;
 }
+function projectStylesheetFontFamilies(html, projectDir) {
+  const families = [];
+  for (const [tag] of html.matchAll(/<link\b[^>]*\brel=["']stylesheet["'][^>]*>/gi)) {
+    const href = /\bhref=["']([^"']+)["']/i.exec(tag)?.[1];
+    if (!href || /^(?:[a-z][a-z\d+.-]*:|\/\/)/i.test(href)) continue;
+    const sheet = resolve7(projectDir, decodedUrlPath(href).replace(/^(?:\.?\/)+/, ""));
+    if (!isPathInside2(sheet, projectDir) || !existsSync10(sheet)) continue;
+    for (const face of extractFontFaceBlocks(readFileSync7(sheet, "utf8"))) {
+      const family = /font-family\s*:\s*([^;}]+)/i.exec(face)?.[1]?.trim().replace(/^['"]|['"]$/g, "");
+      const shipsFile = [...face.matchAll(LOCAL_FONTFACE_URL_RE)].some(([, url = ""]) => {
+        const path = decodedUrlPath(url);
+        const file = path.startsWith("/") ? resolve7(projectDir, `.${path}`) : resolve7(dirname7(sheet), path);
+        return isPathInside2(file, projectDir) && existsSync10(file);
+      });
+      if (family && shipsFile) families.push(family);
+    }
+  }
+  return families;
+}
 function collectFontFaceUrls(html) {
   const styleBlockRe = /<style\b[^>]*>([\s\S]*?)<\/style>/gi;
   const urlSet = /* @__PURE__ */ new Set();
@@ -7869,11 +7926,12 @@ function collectFontFaceUrls(html) {
   return urlSet;
 }
 async function localizeRemoteFontFaces(html, downloadDir) {
-  const processed = await inlineExternalFontStylesheets(html);
-  const urlSet = collectFontFaceUrls(processed);
+  return localizeFontFaceUrls(await inlineExternalFontStylesheets(html), downloadDir);
+}
+function localizeFontFaceUrls(html, downloadDir) {
   return downloadAndRewriteUrls(
-    urlSet,
-    processed,
+    collectFontFaceUrls(html),
+    html,
     join15(downloadDir, REMOTE_MEDIA_SUBDIR),
     "Remote font download failed",
     "Localized remote font face(s)",
@@ -8041,15 +8099,17 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   const hasShaderTransitions = detectShaderTransitionUsage(sanitizedHtml);
   const usesThreeDTransforms = detectThreeDTransformUsage(sanitizedHtml);
   const hasAncestorBackgroundImage = detectAncestorBackgroundImage(sanitizedHtml);
+  const fontSheetHtml = await inlineExternalFontStylesheets(
+    promoteCssImportsToLinkTags(sanitizedHtml)
+  );
   const normalizedFontHtml = normalizeSystemFontPrimaryFamilies(
-    injectTextRenderingRule(
-      coalesceHeadStylesAndBodyScripts(promoteCssImportsToLinkTags(sanitizedHtml))
-    )
+    injectTextRenderingRule(coalesceHeadStylesAndBodyScripts(fontSheetHtml))
   );
   const coalescedHtml = await injectDeterministicFontFaces(normalizedFontHtml, {
     logger: defaultLogger,
     failClosedFontFetch: options.failClosedFontFetch === true,
     allowSystemFontCapture: options.allowSystemFontCapture,
+    projectFontFamilies: projectStylesheetFontFamilies(fontSheetHtml, projectDir),
     abortSignal: options.abortSignal
   });
   const assembledHtml = await inlineExternalScripts(coalescedHtml);
@@ -8075,7 +8135,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
   );
   const { html: htmlWithLocalImages, remoteMediaAssets: remoteImageAssets } = await localizeRemoteImageSources(htmlWithLocalMedia, downloadDir);
   const { html: htmlWithLocalBg, remoteMediaAssets: remoteBgAssets } = await localizeRemoteBackgroundImages(htmlWithLocalImages, downloadDir);
-  const { html: htmlWithLocalizedFonts, remoteMediaAssets: remoteFontAssets } = await localizeRemoteFontFaces(htmlWithLocalBg, downloadDir);
+  const { html: htmlWithLocalizedFonts, remoteMediaAssets: remoteFontAssets } = await localizeFontFaceUrls(htmlWithLocalBg, downloadDir);
   const {
     html: htmlWithJpegs,
     preparedAssets: preparedHeifAssets,
@@ -9926,6 +9986,7 @@ async function planVideoLayerPassthrough(input) {
 }
 
 // src/services/render/stages/audioStage.ts
+import { existsSync as existsSync14 } from "node:fs";
 import { join as join21 } from "node:path";
 import {
   MIXED_AUDIO_FILENAME,
@@ -10059,8 +10120,9 @@ 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;
+var gainFilter = (gainDb) => `volume=${gainDb.toFixed(3)}dB`;
 function aacTruePeakCorrectionFilter(targetDurationSeconds, attenuationDb) {
-  return `volume=${attenuationDb.toFixed(3)}dB,apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
+  return `${gainFilter(attenuationDb)},apad,atrim=0:${formatSeconds(targetDurationSeconds)}`;
 }
 function buildPadTrimAudioPlan(audioPath, outputPath, sourceDurationSeconds, targetDurationSeconds) {
   const delta = targetDurationSeconds - sourceDurationSeconds;
@@ -10098,7 +10160,7 @@ 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 encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal);
+  const encode = input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath);
   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),
@@ -10146,7 +10208,12 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   );
   try {
     for (const step of plan2.steps) {
-      const ffmpegResult = step.kind === "copy" ? await runner(step.args) : await encode(input.audioPath, input.outputPath, targetDurationSeconds, step.filter);
+      const ffmpegResult = step.kind === "copy" ? await runner(step.args) : await encode(
+        input.sourcePath ?? input.audioPath,
+        input.outputPath,
+        targetDurationSeconds,
+        step.filter
+      );
       if (!ffmpegResult.success) {
         return {
           success: false,
@@ -10175,6 +10242,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   if (probeTruePeak) {
     const correction = await enforceAacTruePeak({
       audioPath: input.outputPath,
+      sourcePath: input.sourcePath,
       targetDurationSeconds,
       signal: input.signal,
       probeTruePeak,
@@ -10210,9 +10278,27 @@ async function constrainAacTruePeak(input) {
     targetDurationSeconds: input.targetDurationSeconds,
     signal: input.signal,
     probeTruePeak: input.probeTruePeakDbfs ?? ((audioPath, signal) => measureTruePeakDbfs(audioPath, { timeoutMs, signal })),
-    encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath)
+    encode: input.encodeAac ?? defaultAacEncoder(timeoutMs, input.signal, input.sourcePath),
+    rewriteSource: input.rewriteSource ?? ((sourcePath, outputPath, filter) => defaultRunFfmpeg(
+      ["-i", sourcePath, "-af", filter, "-c:a", "pcm_f32le", "-y", outputPath],
+      timeoutMs,
+      input.signal
+    ))
   });
 }
+async function cutSource(input, scratchDir, attenuationDb) {
+  if (!input.sourcePath || !input.rewriteSource) return true;
+  const cutPath = join19(scratchDir, "source.wav");
+  try {
+    const result = await input.rewriteSource(input.sourcePath, cutPath, gainFilter(attenuationDb));
+    if (!result.success) throw new Error(result.error);
+    renameWithRetry5(cutPath, input.sourcePath, { copyFallback: true });
+    return true;
+  } catch {
+    removeScratch(input.sourcePath);
+    return false;
+  }
+}
 async function enforceAacTruePeak(input) {
   let scratchDir;
   try {
@@ -10232,8 +10318,10 @@ async function enforceAacTruePeak(input) {
       }
       if (truePeakDbfs <= AAC_DELIVERY_TRUE_PEAK_DBFS) {
         if (measuredPath !== correctedPath) return { success: true };
+        const sourceCut = await cutSource(input, scratchDir, attenuationDb);
         renameWithRetry5(correctedPath, input.audioPath, { copyFallback: true });
-        return { success: true, loweredDb: Number((-attenuationDb).toFixed(2)) };
+        const loweredDb = Number((-attenuationDb).toFixed(2));
+        return sourceCut ? { success: true, loweredDb } : { success: true, loweredDb, sourceStale: true };
       }
       if (pass === MAX_TRUE_PEAK_CORRECTION_PASSES) break;
       const headroomDb = AAC_TRUE_PEAK_CORRECTION_HEADROOM_DB * 2 ** pass;
@@ -10243,7 +10331,7 @@ async function enforceAacTruePeak(input) {
       const referenceDbfs = Math.max(truePeakDbfs, (sourcePeakDbfs ?? -Infinity) + attenuationDb);
       attenuationDb += AAC_DELIVERY_TRUE_PEAK_DBFS - headroomDb - referenceDbfs;
       const result = await input.encode(
-        input.audioPath,
+        input.sourcePath ?? input.audioPath,
         correctedPath,
         input.targetDurationSeconds,
         aacTruePeakCorrectionFilter(input.targetDurationSeconds, attenuationDb)
@@ -10472,36 +10560,54 @@ async function runAudioStageScoped(input) {
   const stageStart = Date.now();
   const pcmSourcePath = join21(input.workDir, "audio-source.wav");
   const duration = input.totalFrames * input.fps.den / input.fps.num;
+  let deliverySourcePath;
   try {
     const result = await mixAudioForDelivery(input, duration, pcmSourcePath);
     let audioLoweredDb;
     if (result.hasAudio) {
       const guardStart = Date.now();
-      const limited = await limitDeliveryPeaks({
-        audioPath: result.audioOutputPath,
-        sourcePath: pcmSourcePath,
-        targetDurationSeconds: duration,
-        signal: input.abortSignal,
-        timeoutMs: input.ffmpegProcessTimeout,
-        warn: (message, details) => input.log?.warn?.(message, details)
-      });
-      if (!limited.success) throw encoderFailureError("Audio true-peak limit failed", limited);
-      const peak = await constrainAacTruePeak({
-        audioPath: result.audioOutputPath,
-        sourcePath: pcmSourcePath,
-        targetDurationSeconds: duration,
-        signal: input.abortSignal,
-        timeoutMs: input.ffmpegProcessTimeout
-      });
-      if (!peak.success) throw encoderFailureError("Audio true-peak check failed", peak);
-      audioLoweredDb = peak.loweredDb;
+      const guard = await guardDeliveryPeaks(
+        input,
+        result.audioOutputPath,
+        pcmSourcePath,
+        duration
+      );
+      audioLoweredDb = guard.loweredDb;
       input.log?.info("[audio] phases", { ...result.audioPhaseMs, guard: Date.now() - guardStart });
+      if (input.keepDeliverySource && !guard.sourceStale && existsSync14(pcmSourcePath)) {
+        deliverySourcePath = pcmSourcePath;
+      }
     }
-    return { ...result, audioLoweredDb, audioProcessMs: Date.now() - stageStart };
+    return {
+      ...result,
+      audioLoweredDb,
+      deliverySourcePath,
+      audioProcessMs: Date.now() - stageStart
+    };
   } finally {
-    removeScratch2(pcmSourcePath);
+    if (!deliverySourcePath) removeScratch2(pcmSourcePath);
   }
 }
+async function guardDeliveryPeaks(input, audioPath, sourcePath, duration) {
+  const limited = await limitDeliveryPeaks({
+    audioPath,
+    sourcePath,
+    targetDurationSeconds: duration,
+    signal: input.abortSignal,
+    timeoutMs: input.ffmpegProcessTimeout,
+    warn: (message, details) => input.log?.warn?.(message, details)
+  });
+  if (!limited.success) throw encoderFailureError("Audio true-peak limit failed", limited);
+  const peak = await constrainAacTruePeak({
+    audioPath,
+    sourcePath,
+    targetDurationSeconds: duration,
+    signal: input.abortSignal,
+    timeoutMs: input.ffmpegProcessTimeout
+  });
+  if (!peak.success) throw encoderFailureError("Audio true-peak check failed", peak);
+  return { loweredDb: peak.loweredDb, sourceStale: peak.sourceStale };
+}
 async function mixAudioForDelivery(input, duration, pcmSourcePath) {
   const {
     projectDir,
@@ -10596,7 +10702,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
 }
 
 // src/services/render/stages/captureStage.ts
-import { existsSync as existsSync14, readdirSync as readdirSync3, statfsSync as statfsSync2 } from "node:fs";
+import { existsSync as existsSync15, readdirSync as readdirSync3, statfsSync as statfsSync2 } from "node:fs";
 import { join as join22 } from "node:path";
 import {
   classifyCaptureFailure as classifyCaptureFailure2,
@@ -10667,7 +10773,7 @@ function diskCaptureShortfallError(needBytes, freeBytes, framesDir, basis, remed
 }
 function measureCaptureFrameBytes(workDir, framesDir) {
   let total = sampleDirectoryBytes(framesDir);
-  if (!existsSync14(workDir)) return total;
+  if (!existsSync15(workDir)) return total;
   for (const attempt of readdirSync3(workDir)) {
     if (/^retry-\d+-batch-\d+-worker-\d+$/.test(attempt)) {
       total += sampleDirectoryBytes(join22(workDir, attempt));
@@ -10970,7 +11076,7 @@ async function captureSessionFrames(session, { input, rangeStart, rangeEnd, resu
 }
 
 // src/services/render/stages/captureHdrStage.ts
-import { existsSync as existsSync16, mkdirSync as mkdirSync8 } from "node:fs";
+import { existsSync as existsSync17, mkdirSync as mkdirSync8 } from "node:fs";
 import { join as join26 } from "node:path";
 import {
   closeCaptureSession as closeCaptureSession7,
@@ -11216,7 +11322,7 @@ import { Worker } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath3, pathToFileURL } from "node:url";
 import { dirname as dirname10, join as join24 } from "node:path";
 import { createRequire } from "node:module";
-import { existsSync as existsSync15 } from "node:fs";
+import { existsSync as existsSync16 } from "node:fs";
 import { cpus as cpus2 } from "node:os";
 function resolveWorkerEntry(explicit) {
   if (explicit && explicit.length > 0) {
@@ -11229,7 +11335,7 @@ function resolveWorkerEntry(explicit) {
   }
   const moduleDir = dirname10(fileURLToPath3(import.meta.url));
   const jsPath = join24(moduleDir, "shaderTransitionWorker.js");
-  if (existsSync15(jsPath)) return { path: jsPath, isTs: false };
+  if (existsSync16(jsPath)) return { path: jsPath, isTs: false };
   const tsPath = join24(moduleDir, "shaderTransitionWorker.ts");
   return { path: tsPath, isTs: true };
 }
@@ -11790,7 +11896,7 @@ async function runCaptureHdrStage(input) {
       }
       const debugDumpEnabled = process.env.KEEP_TEMP === "1";
       const debugDumpDir = debugDumpEnabled ? join26(framesDir, "debug-composite") : null;
-      if (debugDumpDir && !existsSync16(debugDumpDir)) {
+      if (debugDumpDir && !existsSync17(debugDumpDir)) {
         mkdirSync8(debugDumpDir, { recursive: true });
       }
       const compositeTransfer = resolveCompositeTransfer(hasHdrContent, effectiveHdr);
@@ -11947,10 +12053,10 @@ async function runCaptureHdrStage(input) {
 // src/services/render/stages/encodeStage.ts
 import {
   copyFileSync as copyFileSync4,
-  existsSync as existsSync17,
+  existsSync as existsSync18,
   mkdirSync as mkdirSync9,
   readdirSync as readdirSync4,
-  readFileSync as readFileSync7,
+  readFileSync as readFileSync8,
   rmSync as rmSync9,
   statSync as statSync7,
   writeFileSync as writeFileSync5
@@ -12044,7 +12150,7 @@ async function reencodeWithClearedWholeFrames(argsInput, run, startTime) {
     const error = formatFfmpegError(result.exitCode, result.stderr);
     return gifEncodeFailure(startTime, outputPath, error, result.failureReason);
   }
-  const gif = readFileSync7(outputPath);
+  const gif = readFileSync8(outputPath);
   if (!clearGifFramesBeforeNext(gif)) {
     const error = "[FFmpeg] GIF output could not be parsed to clear its frames";
     return gifEncodeFailure(startTime, outputPath, error);
@@ -12077,11 +12183,11 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
         return gifEncodeFailure(startTime, outputPath, error, result.failureReason);
       }
     }
-    if (input.preserveAlpha && gifClearsAfterLeavingFrameInPlace(readFileSync7(outputPath)) !== false) {
+    if (input.preserveAlpha && gifClearsAfterLeavingFrameInPlace(readFileSync8(outputPath)) !== false) {
       const failure = await reencodeWithClearedWholeFrames(argsInput, run, startTime);
       if (failure) return failure;
     }
-    const fileSize = existsSync17(outputPath) ? statSync7(outputPath).size : 0;
+    const fileSize = existsSync18(outputPath) ? statSync7(outputPath).size : 0;
     return {
       success: true,
       outputPath,
@@ -12242,7 +12348,7 @@ async function runEncodeStage(input) {
   const stage5Start = Date.now();
   if (isPngSequence) {
     const encoded = startEncodeProgress(job, "Writing PNG sequence", onProgress);
-    if (!existsSync17(outputPath)) mkdirSync9(outputPath, { recursive: true });
+    if (!existsSync18(outputPath)) mkdirSync9(outputPath, { recursive: true });
     const captured = readdirSync4(framesDir).filter((name) => name.endsWith(".png")).sort();
     if (captured.length === 0) {
       throw new Error(
@@ -12253,7 +12359,7 @@ async function runEncodeStage(input) {
       const dst = join27(outputPath, formatExportFrameName(i, "png"));
       copyFileSync4(join27(framesDir, name), dst);
     });
-    if (hasAudio && audioOutputPath && existsSync17(audioOutputPath)) {
+    if (hasAudio && audioOutputPath && existsSync18(audioOutputPath)) {
       copyFileSync4(audioOutputPath, join27(outputPath, MIXED_AUDIO_FILENAME2));
       log.info(
         `[Render] png-sequence: ${MIXED_AUDIO_FILENAME2} sidecar written to ${outputPath}/${MIXED_AUDIO_FILENAME2}`
@@ -12364,6 +12470,7 @@ async function assembleOutput(input, onSecondsWritten) {
     const normalizeResult = await padOrTrimAudioToVideoFrameCount({
       videoPath: videoOnlyPath,
       audioPath: audioOutputPath,
+      sourcePath: input.audioPcmPath,
       outputPath: normalizedAudioPath,
       signal: abortSignal,
       timeoutMs: ffmpegProcessTimeout
@@ -12645,7 +12752,7 @@ function findMissingFrameRanges(totalFrames, framesDir, frameExt) {
   let rangeStart = null;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join28(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    const missing = !existsSync18(framePath) || statSync8(framePath).size <= 8;
+    const missing = !existsSync19(framePath) || statSync8(framePath).size <= 8;
     if (missing && rangeStart === null) {
       rangeStart = frameIndex;
     } else if (!missing && rangeStart !== null) {
@@ -12770,7 +12877,7 @@ function countCapturedFrames(totalFrames, framesDir, frameExt) {
   let captured = 0;
   for (let frameIndex = 0; frameIndex < totalFrames; frameIndex++) {
     const framePath = join28(framesDir, formatCaptureFrameName(frameIndex, frameExt));
-    if (existsSync18(framePath)) captured++;
+    if (existsSync19(framePath)) captured++;
   }
   return captured;
 }
@@ -13435,7 +13542,7 @@ async function executeRenderJob(job, projectDir, outputPath, progressSink, abort
   validateDeliveryEncoderConfig(job.config);
   const debugDir = resolveRenderDebugDir();
   const outputDir = dirname12(outputPath);
-  if (!existsSync18(outputDir)) mkdirSync10(outputDir, { recursive: true });
+  if (!existsSync19(outputDir)) mkdirSync10(outputDir, { recursive: true });
   const workDir = job.config.debug ? join28(debugDir, job.id) : createRenderWorkDir(resolveRenderWorkDirPrefix(outputPath, job.id), outputDir);
   const pipelineStart = Date.now();
   const baseLog = job.config.logger ?? defaultLogger;
@@ -13577,7 +13684,7 @@ async function executeRenderPipeline(input) {
     job.startedAt = /* @__PURE__ */ new Date();
     assertNotAborted();
     assertConfiguredFfmpegBinariesExist();
-    if (!existsSync18(workDir)) mkdirSync10(workDir, { recursive: true });
+    if (!existsSync19(workDir)) mkdirSync10(workDir, { recursive: true });
     if (job.config.debug) {
       log.info("[Render] Debug artifacts enabled", { workDir, logPath });
     }
@@ -13607,7 +13714,7 @@ async function executeRenderPipeline(input) {
     });
     const entryFile = job.config.entryFile || "index.html";
     let htmlPath = join28(projectDir, entryFile);
-    if (!existsSync18(htmlPath)) {
+    if (!existsSync19(htmlPath)) {
       throw new Error(`Entry file not found: ${htmlPath}`);
     }
     assertNotAborted();
@@ -13615,7 +13722,7 @@ async function executeRenderPipeline(input) {
     if (entryFile !== "index.html" && isTemplateEntry(rawEntry)) {
       const wrapperPath = join28(workDir, "standalone-entry.html");
       const projectIndexPath = join28(projectDir, "index.html");
-      if (!existsSync18(projectIndexPath)) {
+      if (!existsSync19(projectIndexPath)) {
         throw new Error(
           `Template entry file "${entryFile}" requires a project index.html to extract its render shell.`
         );
@@ -13926,7 +14033,8 @@ async function executeRenderPipeline(input) {
         masterFxChain: composition.masterFxChain,
         abortSignal: executionSignal,
         assertNotAborted,
-        log
+        log,
+        keepDeliverySource: true
       })
     );
     pendingAudio = audioStage.catch(() => void 0);
@@ -13958,7 +14066,7 @@ async function executeRenderPipeline(input) {
       throw new Error("File server failed to initialize before frame capture");
     }
     const framesDir = join28(workDir, "captured-frames");
-    if (!existsSync18(framesDir)) mkdirSync10(framesDir, { recursive: true });
+    if (!existsSync19(framesDir)) mkdirSync10(framesDir, { recursive: true });
     updateJobStatus(job, "rendering", "Checking browser GPU", 25, onProgress, {
       code: "start_browsers"
     });
@@ -14634,7 +14742,7 @@ async function executeRenderPipeline(input) {
     const effectiveQuality = job.config.crf ?? preset.quality;
     const effectiveBitrate = job.config.crf != null ? void 0 : job.config.videoBitrate;
     const audioResult = await audioStage;
-    const { audioOutputPath, hasAudio } = audioResult;
+    const { audioOutputPath, deliverySourcePath, hasAudio } = audioResult;
     perfStages.audioProcessMs = audioResult.audioProcessMs;
     recordLimiterAttenuation(job, audioResult.audioLoweredDb);
     if (audioResult.audioError) {
@@ -15260,6 +15368,7 @@ async function executeRenderPipeline(input) {
           job,
           videoOnlyPath,
           audioOutputPath,
+          audioPcmPath: deliverySourcePath,
           outputPath: stagedOutputPath,
           hasAudio,
           format: outputFormat,
@@ -15285,7 +15394,7 @@ async function executeRenderPipeline(input) {
       })
     );
     const totalElapsed = Date.now() - pipelineStart;
-    const tmpPeakBytes = existsSync18(workDir) ? sampleDirectoryBytes(workDir) : 0;
+    const tmpPeakBytes = existsSync19(workDir) ? sampleDirectoryBytes(workDir) : 0;
     recordTransientRetryObservability();
     observability.checkpoint("pipeline", "artifact validated", { totalElapsedMs: totalElapsed });
     const observabilitySummary = observability.summary({
@@ -15366,7 +15475,7 @@ async function executeRenderPipeline(input) {
       }
     }
     if (job.config.debug) {
-      if (!isPngSequence && !isHls && existsSync18(stagedOutputPath)) {
+      if (!isPngSequence && !isHls && existsSync19(stagedOutputPath)) {
         const debugOutput = join28(workDir, `output${videoExt}`);
         copyFileSync5(stagedOutputPath, debugOutput);
       }
@@ -15481,7 +15590,7 @@ import {
   REFERENCE_BACKGROUND_FIELD as REFERENCE_BACKGROUND_FIELD4,
   referenceBackgroundResult as referenceBackgroundResult6
 } from "@hyperframes/engine";
-import { mkdirSync as mkdirSync18, mkdtempSync as mkdtempSync7, readFileSync as readFileSync13, rmSync as rmSync16 } from "node:fs";
+import { mkdirSync as mkdirSync18, mkdtempSync as mkdtempSync7, readFileSync as readFileSync14, rmSync as rmSync16 } from "node:fs";
 import { join as join42 } from "node:path";
 import { tmpdir as tmpdir4 } from "node:os";
 
@@ -15878,7 +15987,7 @@ import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframe
 import {
   copyFileSync as copyFileSync6,
   cpSync as cpSync2,
-  existsSync as existsSync23,
+  existsSync as existsSync24,
   linkSync,
   mkdirSync as mkdirSync14,
   rmSync as rmSync12,
@@ -15909,7 +16018,7 @@ import {
 } from "@hyperframes/engine";
 
 // src/services/distributed/chunkFrames.ts
-import { existsSync as existsSync20, readdirSync as readdirSync6 } from "node:fs";
+import { existsSync as existsSync21, readdirSync as readdirSync6 } from "node:fs";
 import { extname as extname4, join as join31 } from "node:path";
 import {
   compositionRequiresWebGpu as compositionRequiresWebGpu3,
@@ -15921,7 +16030,7 @@ import {
 // src/services/distributed/shared.ts
 import { execFile as execFileCallback } from "node:child_process";
 import { dirname as dirname14, join as join30 } from "node:path";
-import { existsSync as existsSync19, readFileSync as readFileSync8 } from "node:fs";
+import { existsSync as existsSync20, readFileSync as readFileSync9 } from "node:fs";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { promisify as promisify2 } from "node:util";
 import {
@@ -15937,7 +16046,7 @@ function isPlanAudioArtifactPath(path) {
 function resolvePlanAudioPath(planDir) {
   for (const name of [PLAN_AUDIO_RELATIVE_PATH, PLAN_AUDIO_LEGACY_RELATIVE_PATH]) {
     const candidate = join30(planDir, name);
-    if (existsSync19(candidate)) return candidate;
+    if (existsSync20(candidate)) return candidate;
   }
   return null;
 }
@@ -16198,9 +16307,9 @@ function readProducerVersion() {
   let current = startDir;
   for (let i = 0; i < 10; i++) {
     const candidate = join30(current, "package.json");
-    if (existsSync19(candidate)) {
+    if (existsSync20(candidate)) {
       try {
-        const pkg = JSON.parse(readFileSync8(candidate, "utf-8"));
+        const pkg = JSON.parse(readFileSync9(candidate, "utf-8"));
         if (pkg.name === "@hyperframes/producer" && typeof pkg.version === "string") {
           cachedProducerVersion = pkg.version;
           return pkg.version;
@@ -16252,7 +16361,7 @@ function rebuildExtractedFramesFromPlanDir(planDir, videos, indexMode = "dense-v
   const result = [];
   for (const v of videos) {
     const outputDir = join31(planDir, "video-frames", v.videoId);
-    if (!existsSync20(outputDir)) {
+    if (!existsSync21(outputDir)) {
       throw new Error(
         `[renderChunk] planDir missing extracted video frames for ${JSON.stringify(v.videoId)}: ${outputDir} not present. plan() should have written frames here; the planDir is malformed.`
       );
@@ -16368,7 +16477,7 @@ async function extractDeferredVideoFramesForChunk(input) {
       const range = video.deferredRange;
       const remoteUrl = remoteSources[range.sourcePath];
       const sourcePath = remoteUrl ?? join31(input.planDir, ...range.sourcePath.split("/"));
-      if (remoteUrl === void 0 && !existsSync20(sourcePath)) {
+      if (remoteUrl === void 0 && !existsSync21(sourcePath)) {
         throw new RenderChunkValidationError(
           MISSING_PLAN_ARTIFACT,
           `[renderChunk] planDir is missing the source for video ${JSON.stringify(video.videoId)}: ${range.sourcePath}`
@@ -16586,7 +16695,7 @@ async function readPlanReferenceBackground(input) {
 }
 
 // src/services/render/stages/freezePlan.ts
-import { existsSync as existsSync21, mkdirSync as mkdirSync12, readFileSync as readFileSync9, readdirSync as readdirSync7, writeFileSync as writeFileSync7 } from "node:fs";
+import { existsSync as existsSync22, mkdirSync as mkdirSync12, readFileSync as readFileSync10, readdirSync as readdirSync7, writeFileSync as writeFileSync7 } from "node:fs";
 import { join as join34, relative as relative3, resolve as resolve9 } from "node:path";
 import {
   REFERENCE_BACKGROUND_FIELD,
@@ -16780,7 +16889,7 @@ function planFileSha256(absolutePath, digests) {
   return sha256;
 }
 async function prehashPlanFiles(dir, digests) {
-  if (!existsSync21(dir)) return;
+  if (!existsSync22(dir)) return;
   for (const { absolutePath } of listPlanFiles(dir)) {
     if (!digests.has(absolutePath)) digests.set(absolutePath, await sha256FileAsync(absolutePath));
   }
@@ -16826,7 +16935,7 @@ function collectPlanAssetShas(planDir, digests) {
   const assets = [];
   for (const file of files) {
     if (file.planRelativePath === COMPILED_INDEX_RELATIVE_PATH) {
-      compositionHtml = readFileSync9(file.absolutePath);
+      compositionHtml = readFileSync10(file.absolutePath);
       continue;
     }
     if (HASH_EXCLUDED_PLAN_FILES.has(file.planRelativePath)) continue;
@@ -16850,19 +16959,19 @@ function writePlanRemoteFiles(planDir, files) {
 }
 function readPlanRemoteFiles(planDir) {
   const path = join34(planDir, PLAN_REMOTE_FILES_RELATIVE_PATH);
-  return existsSync21(path) ? JSON.parse(readFileSync9(path, "utf-8")) : [];
+  return existsSync22(path) ? JSON.parse(readFileSync10(path, "utf-8")) : [];
 }
 function recomputePlanHashFromPlanDir(planDir, digests) {
   const planJsonPath = join34(planDir, "plan.json");
   const encoderJsonPath = join34(planDir, "meta", "encoder.json");
-  if (!existsSync21(planJsonPath)) {
+  if (!existsSync22(planJsonPath)) {
     throw new Error(`[freezePlan] plan.json missing: ${planJsonPath}`);
   }
-  if (!existsSync21(encoderJsonPath)) {
+  if (!existsSync22(encoderJsonPath)) {
     throw new Error(`[freezePlan] meta/encoder.json missing: ${encoderJsonPath}`);
   }
-  const planJson = JSON.parse(readFileSync9(planJsonPath, "utf-8"));
-  const encoderConfigCanonicalJson = readFileSync9(encoderJsonPath, "utf-8");
+  const planJson = JSON.parse(readFileSync10(planJsonPath, "utf-8"));
+  const encoderConfigCanonicalJson = readFileSync10(encoderJsonPath, "utf-8");
   const { compositionHtml, assets } = collectPlanAssetShas(planDir, digests);
   return computePlanHash({
     compositionHtml,
@@ -16888,11 +16997,11 @@ async function freezePlan(input) {
     hasAudio,
     digests
   } = input;
-  if (!existsSync21(planDir)) {
+  if (!existsSync22(planDir)) {
     throw new Error(`[freezePlan] planDir does not exist: ${planDir}`);
   }
   const metaDir = join34(planDir, "meta");
-  if (!existsSync21(metaDir)) mkdirSync12(metaDir, { recursive: true });
+  if (!existsSync22(metaDir)) mkdirSync12(metaDir, { recursive: true });
   writeFileSync7(
     join34(metaDir, "composition.json"),
     `${JSON.stringify(composition, null, 2)}
@@ -16969,7 +17078,7 @@ function applyRuntimeEnvSnapshot(snapshot, env = process.env) {
 }
 
 // src/services/distributed/chunkAudio.ts
-import { closeSync as closeSync6, existsSync as existsSync22, ftruncateSync, mkdirSync as mkdirSync13, openSync as openSync6, readFileSync as readFileSync10 } from "node:fs";
+import { closeSync as closeSync6, existsSync as existsSync23, ftruncateSync, mkdirSync as mkdirSync13, openSync as openSync6, readFileSync as readFileSync11 } from "node:fs";
 import { writeFileSync as writeFileSync8, writeSync } from "node:fs";
 import { join as join35 } from "node:path";
 import { appendRenderProvenanceArgs, describeFfmpegFailure as describeFfmpegFailure4, runFfmpeg as runFfmpeg7 } from "@hyperframes/engine";
@@ -17057,7 +17166,7 @@ async function writeChunkAudioSlices(input) {
       offset += track.sizes[offsets.length - 1];
     }
   });
-  const bytes = readFileSync10(input.audioPath);
+  const bytes = readFileSync11(input.audioPath);
   const layout = { sizeBytes: bytes.length, payloadStart, payloadEnd, partStarts: {} };
   mkdirSync13(join35(input.planDir, SLICE_DIR), { recursive: true });
   input.chunks.forEach((_, index) => {
@@ -17075,9 +17184,9 @@ async function writeChunkAudioSlices(input) {
 }
 function chunkAudioSource(planDir, chunkIndex, scratchPath) {
   const layoutPath = join35(planDir, SLICE_LAYOUT);
-  if (!existsSync22(layoutPath)) return resolvePlanAudioPath(planDir);
-  const layout = JSON.parse(readFileSync10(layoutPath, "utf-8"));
-  const frame = readFileSync10(join35(planDir, SLICE_FRAME));
+  if (!existsSync23(layoutPath)) return resolvePlanAudioPath(planDir);
+  const layout = JSON.parse(readFileSync11(layoutPath, "utf-8"));
+  const frame = readFileSync11(join35(planDir, SLICE_FRAME));
   const fd = openSync6(scratchPath, "w");
   try {
     writeSync(fd, frame, 0, layout.payloadStart, 0);
@@ -17090,7 +17199,7 @@ function chunkAudioSource(planDir, chunkIndex, scratchPath) {
     );
     const start = layout.partStarts[chunkIndex];
     if (start !== void 0) {
-      const part = readFileSync10(join35(planDir, chunkAudioSlicePath(chunkIndex)));
+      const part = readFileSync11(join35(planDir, chunkAudioSlicePath(chunkIndex)));
       writeSync(fd, part, 0, part.length, start);
     }
     ftruncateSync(fd, layout.sizeBytes);
@@ -17635,7 +17744,7 @@ function createVideoSourceShipper(input) {
     let result = null;
     for (const root of stagedRel === null ? [input.workCompiledDir, input.projectDir] : []) {
       const rel = pathInside(root, srcPath);
-      if (rel !== null && (existsSync23(join37(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
+      if (rel !== null && (existsSync24(join37(input.planDir, "compiled", rel)) || input.isRemote(srcPath))) {
         result = ["compiled", ...rel.split(sep2)].join("/");
         break;
       }
@@ -17663,7 +17772,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     useGpu: false,
     browserGpuMode: "software"
   });
-  if (!existsSync23(planDir)) mkdirSync14(planDir, { recursive: true });
+  if (!existsSync24(planDir)) mkdirSync14(planDir, { recursive: true });
   const log = config.logger ?? defaultLogger;
   const sizeLimitBytes = options.executionPlanSizeLimitBytes ?? config.planDirSizeLimitBytes ?? PLAN_DIR_SIZE_LIMIT_BYTES;
   const abortSignal = config.abortSignal;
@@ -17693,7 +17802,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   });
   const entryFile = config.entryFile ?? "index.html";
   const htmlPath = join37(projectDir, entryFile);
-  if (!existsSync23(htmlPath)) {
+  if (!existsSync24(htmlPath)) {
     throw new Error(`[plan] entry file not found: ${htmlPath}`);
   }
   const workDir = join37(planDir, ".plan-work");
@@ -17922,15 +18031,15 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
   logPlanStage(log, "extract", stageStarted);
   const stagedVideoFrames = join37(compiledDir, "__hyperframes_video_frames");
   const videoFramesDst = join37(planDir, "video-frames");
-  if (existsSync23(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
+  if (existsSync24(videoFramesDst)) rmSync12(videoFramesDst, { recursive: true, force: true });
   const videoSourcesDir = join37(planDir, "video-sources");
   rmSync12(videoSourcesDir, { recursive: true, force: true });
-  if (existsSync23(stagedVideoFrames)) {
+  if (existsSync24(stagedVideoFrames)) {
     renameWithRetry8(stagedVideoFrames, videoFramesDst);
   } else {
     mkdirSync14(videoFramesDst, { recursive: true });
   }
-  if (existsSync23(finalCompiledDir)) rmSync12(finalCompiledDir, { recursive: true, force: true });
+  if (existsSync24(finalCompiledDir)) rmSync12(finalCompiledDir, { recursive: true, force: true });
   renameWithRetry8(compiledDir, finalCompiledDir);
   const shipVideoSource = createVideoSourceShipper({
     planDir,
@@ -18050,10 +18159,10 @@ async function buildLocalExecutionPlan(projectDir, config, executionPlanDir, opt
     applyDistributedAudioWarningPolicy(job, audioResult.audioError, audioResult.audioFailures, log);
   }
   const planAudioPath = join37(planDir, PLAN_AUDIO_RELATIVE_PATH);
-  if (audioResult?.hasAudio && existsSync23(audioResult.audioOutputPath)) {
+  if (audioResult?.hasAudio && existsSync24(audioResult.audioOutputPath)) {
     renameWithRetry8(audioResult.audioOutputPath, planAudioPath);
   }
-  if (chunksCarryAudio && existsSync23(planAudioPath)) {
+  if (chunksCarryAudio && existsSync24(planAudioPath)) {
     if (options.sliceChunkAudio) {
       stageStarted = Date.now();
       await writeChunkAudioSlices({
@@ -18171,7 +18280,7 @@ async function plan(projectDir, config, planDir, options = {}) {
 
 // src/services/distributed/renderChunk.ts
 import { randomBytes } from "node:crypto";
-import { existsSync as existsSync26, mkdirSync as mkdirSync17, readFileSync as readFileSync12, readdirSync as readdirSync10, rmSync as rmSync15, writeFileSync as writeFileSync12 } from "node:fs";
+import { existsSync as existsSync27, mkdirSync as mkdirSync17, readFileSync as readFileSync13, readdirSync as readdirSync10, rmSync as rmSync15, writeFileSync as writeFileSync12 } from "node:fs";
 import { cpus as cpus3 } from "node:os";
 import { join as join41 } from "node:path";
 import {
@@ -18198,11 +18307,11 @@ import {
 } from "@hyperframes/engine";
 import {
   copyFileSync as copyFileSync8,
-  existsSync as existsSync25,
+  existsSync as existsSync26,
   lstatSync as lstatSync3,
   mkdirSync as mkdirSync16,
   mkdtempSync as mkdtempSync6,
-  readFileSync as readFileSync11,
+  readFileSync as readFileSync12,
   readdirSync as readdirSync9,
   rmSync as rmSync14,
   statSync as statSync10,
@@ -18216,7 +18325,7 @@ import { createFrameLookupTable as createFrameLookupTable4, renameWithRetry as r
 // src/services/distributed/planV2Publisher.ts
 import {
   copyFileSync as copyFileSync7,
-  existsSync as existsSync24,
+  existsSync as existsSync25,
   linkSync as linkSync2,
   mkdirSync as mkdirSync15,
   mkdtempSync as mkdtempSync5,
@@ -18285,7 +18394,7 @@ var LocalPlanV2ArtifactPublisher = class {
   #linkFile;
   #committed = false;
   constructor(destinationDir, options = {}) {
-    if (existsSync24(destinationDir)) {
+    if (existsSync25(destinationDir)) {
       throw new PlanV2IntegrityError(`output directory already exists: ${destinationDir}`);
     }
     this.destinationDir = destinationDir;
@@ -18302,7 +18411,7 @@ var LocalPlanV2ArtifactPublisher = class {
       );
     }
     const destinationPath = planV2BlobPath(this.temporaryDir, digest);
-    if (existsSync24(destinationPath)) return;
+    if (existsSync25(destinationPath)) return;
     mkdirSync15(dirname15(destinationPath), { recursive: true });
     const stagingDir = mkdtempSync5(join39(dirname15(destinationPath), ".plan-v2-blob-"));
     const temporaryPath = join39(stagingDir, "blob");
@@ -18320,7 +18429,7 @@ var LocalPlanV2ArtifactPublisher = class {
   }
   async commitManifest(manifestBytes) {
     for (const digest of new Set(manifestDigests(manifestBytes))) {
-      if (!existsSync24(planV2BlobPath(this.temporaryDir, digest))) {
+      if (!existsSync25(planV2BlobPath(this.temporaryDir, digest))) {
         throw new PlanV2IntegrityError(
           `cannot commit manifest before referenced blob is durable: ${digest}`
         );
@@ -18351,7 +18460,7 @@ function isNonNegativeIntegerArray(value) {
   return Array.isArray(value) && value.every((item) => typeof item === "number" && Number.isInteger(item) && item >= 0);
 }
 function readJsonFile(path, label) {
-  const contents = readFileSync11(path, "utf-8");
+  const contents = readFileSync12(path, "utf-8");
   try {
     const parsed = JSON.parse(contents);
     return parsed;
@@ -18399,7 +18508,7 @@ function assertValidExtractionCacheCompleteSentinel(path) {
 }
 function validateExtractionCacheCompleteSentinels(executionPlanDir) {
   const videoRoot = join40(executionPlanDir, "video-frames");
-  if (!existsSync25(videoRoot)) return;
+  if (!existsSync26(videoRoot)) return;
   for (const videoEntry of readdirSync9(videoRoot, { withFileTypes: true })) {
     if (!videoEntry.isDirectory()) continue;
     const videoDir = join40(videoRoot, videoEntry.name);
@@ -18500,7 +18609,7 @@ function parsePlanVideosJson2(value) {
 }
 function materializeExtractedVideoDirectories(planDir) {
   const videosPath = join40(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync25(videosPath)) return;
+  if (!existsSync26(videosPath)) return;
   const videos = parsePlanVideosJson2(readJsonFile(videosPath, PLAN_VIDEOS_META_RELATIVE_PATH));
   for (const video of videos.extracted) {
     mkdirSync16(resolveExtractedVideoOutputDir(planDir, video.videoId), { recursive: true });
@@ -18534,9 +18643,9 @@ function parseChunkSlices(value) {
 }
 function buildVideoChunkDependencies(executionPlanDir, dimensions) {
   const videoRoot = join40(executionPlanDir, "video-frames");
-  const hasExtractedFrames = existsSync25(videoRoot) && listFiles(videoRoot).length > 0;
+  const hasExtractedFrames = existsSync26(videoRoot) && listFiles(videoRoot).length > 0;
   const videosPath = join40(executionPlanDir, PLAN_VIDEOS_META_RELATIVE_PATH);
-  if (!existsSync25(videosPath)) {
+  if (!existsSync26(videosPath)) {
     return hasExtractedFrames ? { mode: "full-source-pack", dependencies: null } : { mode: "exact-rendered-frames", dependencies: /* @__PURE__ */ new Map() };
   }
   const chunksPath = join40(executionPlanDir, "meta", "chunks.json");
@@ -18593,7 +18702,7 @@ function computeManifestHash(manifest) {
   return sha256Hex(`${PLAN_V2_HASH_PREFIX}${canonicalJsonStringify(manifestPayload(manifest))}`);
 }
 function writeBlob(sourcePath, destinationPath) {
-  if (existsSync25(destinationPath)) return;
+  if (existsSync26(destinationPath)) return;
   mkdirSync16(dirname16(destinationPath), { recursive: true });
   const temporaryDir = mkdtempSync6(join40(dirname16(destinationPath), ".plan-v2-blob-"));
   const temporaryPath = join40(temporaryDir, "blob");
@@ -18633,7 +18742,7 @@ async function putTasks(tasks) {
 }
 function buildPlanV2Publication(executionPlanDir, digests) {
   const executionPlanPath = join40(executionPlanDir, "plan.json");
-  if (!existsSync25(executionPlanPath)) {
+  if (!existsSync26(executionPlanPath)) {
     throw new PlanV2IntegrityError(`execution plan is missing plan.json: ${executionPlanPath}`);
   }
   const executionPlanValue = readJsonFile(executionPlanPath, "execution plan.json");
@@ -18713,7 +18822,7 @@ function buildPlanV2Publication(executionPlanDir, digests) {
   };
 }
 function createPlanV2FromExecutionPlan(executionPlanDir, planV2Dir) {
-  if (existsSync25(planV2Dir)) {
+  if (existsSync26(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publication = buildPlanV2Publication(executionPlanDir);
@@ -18799,7 +18908,7 @@ async function planV2WithPublisher(projectDir, config, publisher, options = {})
   }
 }
 async function planV2(projectDir, config, planV2Dir) {
-  if (existsSync25(planV2Dir)) {
+  if (existsSync26(planV2Dir)) {
     throw new PlanV2IntegrityError(`output directory already exists: ${planV2Dir}`);
   }
   const publisher = new LocalPlanV2ArtifactPublisher(planV2Dir);
@@ -18953,7 +19062,7 @@ function parsePlanV2Manifest(value) {
 }
 function readPlanV2Manifest(planV2Dir) {
   const manifestPath = join40(planV2Dir, "plan.json");
-  if (!existsSync25(manifestPath)) {
+  if (!existsSync26(manifestPath)) {
     throw new PlanV2IntegrityError(`missing v2 manifest: ${manifestPath}`);
   }
   const value = readJsonFile(manifestPath, "v2 manifest");
@@ -18972,7 +19081,7 @@ function listPlanV2ArtifactsForTarget(manifest, target) {
 }
 function verifyBlob(planV2Dir, artifact) {
   const sourcePath = planV2BlobPath(planV2Dir, artifact.sha256);
-  if (!existsSync25(sourcePath)) {
+  if (!existsSync26(sourcePath)) {
     throw new PlanV2IntegrityError(`missing content-addressed artifact ${artifact.sha256}`);
   }
   const stats = statSync10(sourcePath);
@@ -18985,7 +19094,7 @@ function verifyBlob(planV2Dir, artifact) {
   return sourcePath;
 }
 function materializePlanV2Target(planV2Dir, target, destinationDir, options = {}) {
-  if (existsSync25(destinationDir)) {
+  if (existsSync26(destinationDir)) {
     throw new PlanV2IntegrityError(`materialization destination already exists: ${destinationDir}`);
   }
   const manifest = readPlanV2Manifest(planV2Dir);
@@ -19050,7 +19159,7 @@ function validatePlanV2MaterializedTarget(planDir, expectedTarget) {
 }
 function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   const markerPath = join40(planDir, PLAN_V2_MATERIALIZATION_MARKER);
-  if (!existsSync25(markerPath)) return null;
+  if (!existsSync26(markerPath)) return null;
   const marker = readJsonFile(markerPath, "materialization marker");
   if (!isRecord3(marker) || !isRecord3(marker.manifest) || !isRecord3(marker.target)) {
     throw new PlanV2IntegrityError("malformed materialization marker");
@@ -19068,7 +19177,7 @@ function readValidatedPlanV2Materialization(planDir, expectedTarget) {
   for (const artifact of required) {
     if (Object.hasOwn(remoteSources, artifact.path)) continue;
     const path = join40(planDir, ...artifact.path.split("/"));
-    if (!existsSync25(path) || statSync10(path).size !== artifact.sizeBytes) {
+    if (!existsSync26(path) || statSync10(path).size !== artifact.sizeBytes) {
       throw new PlanV2IntegrityError(
         `materialized artifact missing or truncated: ${artifact.path}`
       );
@@ -19185,10 +19294,10 @@ async function beginFrameSessionNeedsScreenshotFallback(session, probe = probeBe
   return !await probe(session.page, timeoutMs, probeTick, session.beginFrameIntervalMs);
 }
 function hashChunkOutput(outputPath, kind) {
-  if (kind === "file") return sha256Hex(readFileSync12(outputPath));
+  if (kind === "file") return sha256Hex(readFileSync13(outputPath));
   const entries = readdirSync10(outputPath).filter((name) => /\.(png|jpg|jpeg)$/i.test(name)).sort();
   const lines = entries.map(
-    (name) => `${name}\0${sha256Hex(readFileSync12(join41(outputPath, name)))}`
+    (name) => `${name}\0${sha256Hex(readFileSync13(join41(outputPath, name)))}`
   );
   return sha256Hex(lines.join("\0"));
 }
@@ -19208,13 +19317,13 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const planJsonPath = join41(planDir, "plan.json");
   const encoderJsonPath = join41(planDir, "meta", "encoder.json");
   const chunksJsonPath = join41(planDir, "meta", "chunks.json");
-  if (!existsSync26(planJsonPath)) {
+  if (!existsSync27(planJsonPath)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir is missing required artifact: ${planJsonPath}`
     );
   }
-  const plan2 = JSON.parse(readFileSync12(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync13(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.chunk);
   const planHashStarted = Date.now();
   const v2Materialization = readValidatedPlanV2Materialization(planDir, {
@@ -19224,20 +19333,20 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const v2Manifest = v2Materialization?.manifest ?? null;
   const remoteSources = v2Materialization?.remoteSources ?? {};
   for (const required of [encoderJsonPath, chunksJsonPath]) {
-    if (!existsSync26(required)) {
+    if (!existsSync27(required)) {
       throw new RenderChunkValidationError(
         MISSING_PLAN_ARTIFACT,
         `[renderChunk] planDir is missing required artifact: ${required}`
       );
     }
   }
-  const encoder = JSON.parse(readFileSync12(encoderJsonPath, "utf-8"));
-  const chunks = JSON.parse(readFileSync12(chunksJsonPath, "utf-8"));
+  const encoder = JSON.parse(readFileSync13(encoderJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync13(chunksJsonPath, "utf-8"));
   const videosJsonPath = join41(planDir, PLAN_VIDEOS_META_RELATIVE_PATH);
   let planVideos = null;
-  if (existsSync26(videosJsonPath)) {
+  if (existsSync27(videosJsonPath)) {
     try {
-      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync12(videosJsonPath, "utf-8")));
+      planVideos = validatePlanVideosForChunk(JSON.parse(readFileSync13(videosJsonPath, "utf-8")));
     } catch (err) {
       if (err instanceof RenderChunkValidationError) throw err;
       throw new RenderChunkValidationError(
@@ -19266,7 +19375,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
   const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join41(planDir, "compiled");
-  if (!existsSync26(compiledDir)) {
+  if (!existsSync27(compiledDir)) {
     throw new RenderChunkValidationError(
       MISSING_PLAN_ARTIFACT,
       `[renderChunk] planDir missing compiled/ directory: ${compiledDir}`
@@ -19348,7 +19457,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       dimensions: plan2.dimensions,
       encoder,
       videoCount: planVideos?.videos.length ?? 0,
-      html: readFileSync12(join41(compiledDir, "index.html"), "utf-8"),
+      html: readFileSync13(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: deferredVideos.filter(
         (video) => !shownFrames.get(video.videoId)?.size || remoteVideoIds.has(video.videoId)
@@ -19516,10 +19625,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       const effectiveBitrate = encoder.crf != null ? void 0 : encoder.bitrate;
       const videoOnlyPath = encoder.chunksCarryAudio ? `${outputChunkPath}.video.mp4` : outputChunkPath;
       if (isPngSequence) {
-        if (!existsSync26(outputChunkPath)) mkdirSync17(outputChunkPath, { recursive: true });
+        if (!existsSync27(outputChunkPath)) mkdirSync17(outputChunkPath, { recursive: true });
       } else {
         const outDir = join41(outputChunkPath, "..");
-        if (!existsSync26(outDir)) mkdirSync17(outDir, { recursive: true });
+        if (!existsSync27(outDir)) mkdirSync17(outDir, { recursive: true });
       }
       const encodeInput = {
         job,
@@ -19810,7 +19919,7 @@ async function renderSpan(projectDir, config, span, outputPath) {
       planned.totalFrames
     );
     const slices = JSON.parse(
-      readFileSync13(join42(planDir, "meta", "chunks.json"), "utf-8")
+      readFileSync14(join42(planDir, "meta", "chunks.json"), "utf-8")
     );
     const parts = [];
     for (const slice of slices) {
@@ -20419,7 +20528,7 @@ import {
 
 // src/server.ts
 import {
-  existsSync as existsSync29,
+  existsSync as existsSync30,
   mkdirSync as mkdirSync19,
   statSync as statSync12,
   mkdtempSync as mkdtempSync8,
@@ -20442,8 +20551,8 @@ import {
 
 // src/services/hyperframeLint.ts
 import {
-  existsSync as existsSync27,
-  readFileSync as readFileSync14,
+  existsSync as existsSync28,
+  readFileSync as readFileSync15,
   statSync as statSync11,
   openSync as openSync7,
   fstatSync as fstatSync3,
@@ -20489,14 +20598,14 @@ function readEntryHtml(filePath) {
   }
   try {
     if (!fstatSync3(fd).isFile()) return null;
-    return readFileSync14(fd, "utf-8");
+    return readFileSync15(fd, "utf-8");
   } finally {
     closeSync7(fd);
   }
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
   const absProjectDir = resolve11(projectDir);
-  if (!existsSync27(absProjectDir) || !statSync11(absProjectDir).isDirectory()) {
+  if (!existsSync28(absProjectDir) || !statSync11(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entryCandidates = [preferredEntryFile, "index.html", "src/index.html"].filter(
@@ -20565,7 +20674,7 @@ async function runHyperframeLint(prepared) {
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath6 } from "node:url";
 import { dirname as dirname17, join as join44 } from "node:path";
-import { existsSync as existsSync28 } from "node:fs";
+import { existsSync as existsSync29 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
   const log = options.logger ?? defaultLogger2();
@@ -20642,7 +20751,7 @@ function resolveWorkerEntry2() {
   const here = dirname17(fileURLToPath6(import.meta.url));
   const candidates = [join44(here, "healthWorkerThread.js"), join44(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
-    if (existsSync28(candidate)) return candidate;
+    if (existsSync29(candidate)) return candidate;
   }
   return void 0;
 }
@@ -20788,7 +20897,7 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   const { input, cleanupProjectDir } = prepared;
   const absoluteOutputPath = resolveOutputPath(input.projectDir, input.outputPath, rendersDir, log);
   const outputDir = dirname18(absoluteOutputPath);
-  if (!existsSync29(outputDir)) mkdirSync19(outputDir, { recursive: true });
+  if (!existsSync30(outputDir)) mkdirSync19(outputDir, { recursive: true });
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
@@ -20829,11 +20938,11 @@ function prepareProjectDirectory(projectDir, options) {
   const candidate = nonEmptyString(projectDir);
   if (!candidate) return null;
   const absProjectDir = resolve12(candidate);
-  if (!existsSync29(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
+  if (!existsSync30(absProjectDir) || !statSync12(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entry = options.entryFile || "index.html";
-  if (!existsSync29(resolve12(absProjectDir, entry))) {
+  if (!existsSync30(resolve12(absProjectDir, entry))) {
     return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
   }
   return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -20925,7 +21034,7 @@ function cleanupTempDir(dir, log) {
   }
 }
 function outputFileSize(path) {
-  return existsSync29(path) ? statSync12(path).size : 0;
+  return existsSync30(path) ? statSync12(path).size : 0;
 }
 function createBlockingProgressReporter(log, requestId) {
   let lastLoggedPct = -10;
@@ -21229,7 +21338,7 @@ function createRenderHandlers(options = {}) {
     if (!artifact) {
       return c.json({ success: false, error: "Output artifact not found or expired" }, 404);
     }
-    if (!existsSync29(artifact.path)) {
+    if (!existsSync30(artifact.path)) {
       store.delete(token);
       return c.json({ success: false, error: "Output artifact file missing" }, 404);
     }
@@ -21335,10 +21444,10 @@ import {
 } from "@hyperframes/engine";
 import {
   cpSync as cpSync3,
-  existsSync as existsSync30,
+  existsSync as existsSync31,
   mkdirSync as mkdirSync20,
   mkdtempSync as mkdtempSync9,
-  readFileSync as readFileSync15,
+  readFileSync as readFileSync16,
   readdirSync as readdirSync11,
   rmSync as rmSync18,
   statSync as statSync13,
@@ -21390,7 +21499,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   }
   const format = plan2.dimensions.format;
   const cfrEncoder = cfr ? readCfrEncoder(planDir, format) : null;
-  if (!existsSync30(dirname19(outputPath))) {
+  if (!existsSync31(dirname19(outputPath))) {
     mkdirSync20(dirname19(outputPath), { recursive: true });
   }
   const workDir = mkdtempSync9(`${outputPath}.assemble-work-`);
@@ -21414,7 +21523,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   try {
     const videoSources = cfrEncoder ? [await reencodeCfr(ctx, chunkPaths, cfrEncoder)] : chunkPaths;
     const finalPath = join46(workDir, `output.${format}`);
-    const audio = audioPath !== null && existsSync30(audioPath) ? audioPath : null;
+    const audio = audioPath !== null && existsSync31(audioPath) ? audioPath : null;
     await writeJoined(ctx, videoSources, audio, finalPath);
     renameWithRetry11(finalPath, outputPath);
     log.info("[assemble] stage timings", {
@@ -21432,7 +21541,7 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
       });
     }
   }
-  const fileSize = existsSync30(outputPath) ? statSync13(outputPath).size : 0;
+  const fileSize = existsSync31(outputPath) ? statSync13(outputPath).size : 0;
   return {
     ...referenceBackgroundResult8(plan2[REFERENCE_BACKGROUND_FIELD6]),
     outputPath,
@@ -21444,16 +21553,16 @@ async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
 function readAssemblePlan(planDir, chunkPaths) {
   const planJsonPath = join46(planDir, "plan.json");
   const chunksJsonPath = join46(planDir, "meta", "chunks.json");
-  if (!existsSync30(planJsonPath)) {
+  if (!existsSync31(planJsonPath)) {
     throw new Error(`[assemble] planDir missing plan.json: ${planJsonPath}`);
   }
-  const plan2 = JSON.parse(readFileSync15(planJsonPath, "utf-8"));
+  const plan2 = JSON.parse(readFileSync16(planJsonPath, "utf-8"));
   readPlanProtocolV1(plan2, DISTRIBUTED_RENDER_CAPABILITIES.roles.assembler);
   validatePlanV2MaterializedTarget(planDir, { role: "assembler" });
-  if (!existsSync30(chunksJsonPath)) {
+  if (!existsSync31(chunksJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/chunks.json: ${chunksJsonPath}`);
   }
-  const chunks = JSON.parse(readFileSync15(chunksJsonPath, "utf-8"));
+  const chunks = JSON.parse(readFileSync16(chunksJsonPath, "utf-8"));
   if (chunkPaths.length !== chunks.length) {
     throw new Error(
       `[assemble] chunkPaths length (${chunkPaths.length}) does not match chunks.json length (${chunks.length}). Adapters must pass one path per chunk, ordered by index.`
@@ -21465,7 +21574,7 @@ function readAssemblePlan(planDir, chunkPaths) {
     }
   }
   for (const path of chunkPaths.flat()) {
-    if (!existsSync30(path)) {
+    if (!existsSync31(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
   }
@@ -21599,13 +21708,13 @@ function stitchesSeparateAudio(planDir) {
   return lockedAudio(planDir).separateAudio === true;
 }
 function planFormat(planDir) {
-  const plan2 = JSON.parse(readFileSync15(join46(planDir, "plan.json"), "utf-8"));
+  const plan2 = JSON.parse(readFileSync16(join46(planDir, "plan.json"), "utf-8"));
   return plan2.dimensions.format;
 }
 function lockedAudio(planDir) {
   const encoderJsonPath = join46(planDir, "meta", "encoder.json");
-  if (!existsSync30(encoderJsonPath)) return {};
-  return JSON.parse(readFileSync15(encoderJsonPath, "utf-8"));
+  if (!existsSync31(encoderJsonPath)) return {};
+  return JSON.parse(readFileSync16(encoderJsonPath, "utf-8"));
 }
 function readCfrEncoder(planDir, format) {
   if (format !== "mp4") {
@@ -21614,10 +21723,10 @@ function readCfrEncoder(planDir, format) {
     );
   }
   const encoderJsonPath = join46(planDir, "meta", "encoder.json");
-  if (!existsSync30(encoderJsonPath)) {
+  if (!existsSync31(encoderJsonPath)) {
     throw new Error(`[assemble] planDir missing meta/encoder.json: ${encoderJsonPath}`);
   }
-  const encoderJson = JSON.parse(readFileSync15(encoderJsonPath, "utf-8"));
+  const encoderJson = JSON.parse(readFileSync16(encoderJsonPath, "utf-8"));
   if (encoderJson.encoder === "libx265-software") {
     throw new Error(
       `[assemble] cfr=true is not yet supported with codec: "h265". The cfr re-encode pass uses libx264 and would silently transcode the h265 chunks. Either disable cfr or render with codec: "h264".`
@@ -21626,7 +21735,7 @@ function readCfrEncoder(planDir, format) {
   return encoderJson;
 }
 function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, startTimeMs) {
-  if (existsSync30(outputPath)) rmSync18(outputPath, { recursive: true, force: true });
+  if (existsSync31(outputPath)) rmSync18(outputPath, { recursive: true, force: true });
   mkdirSync20(outputPath, { recursive: true });
   let globalIdx = 0;
   for (const chunkDir of chunkPaths) {
@@ -21650,7 +21759,7 @@ function mergePngFrameDirs(chunkPaths, outputPath, totalFrames, audioPath, start
       `[assemble] png-sequence frame count mismatch: merged ${globalIdx} frames vs plan.totalFrames=${totalFrames}. Using on-disk count.`
     );
   }
-  if (audioPath !== null && existsSync30(audioPath)) {
+  if (audioPath !== null && existsSync31(audioPath)) {
     const sidecar = join46(outputPath, MIXED_AUDIO_FILENAME4);
     cpSync3(audioPath, sidecar);
   }