@hyperframes/producer 0.9.14 → 0.9.15

package/dist/public-server.js

@@ -2,7 +2,7 @@
 
 // src/server.ts
 import {
-  existsSync as existsSync21,
+  existsSync as existsSync22,
   mkdirSync as mkdirSync11,
   statSync as statSync10,
   mkdtempSync as mkdtempSync4,
@@ -26,7 +26,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,
@@ -9959,6 +9959,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,
@@ -10092,8 +10093,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;
@@ -10131,7 +10133,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),
@@ -10179,7 +10181,12 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   );
   try {
     for (const step of plan.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,
@@ -10208,6 +10215,7 @@ async function padOrTrimAudioToVideoFrameCount(input) {
   if (probeTruePeak) {
     const correction = await enforceAacTruePeak({
       audioPath: input.outputPath,
+      sourcePath: input.sourcePath,
       targetDurationSeconds,
       signal: input.signal,
       probeTruePeak,
@@ -10243,9 +10251,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 {
@@ -10265,8 +10291,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;
@@ -10276,7 +10304,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)
@@ -10505,36 +10533,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,
@@ -10629,7 +10675,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,
@@ -10700,7 +10746,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));
@@ -11003,7 +11049,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,
@@ -11249,7 +11295,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) {
@@ -11262,7 +11308,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 };
 }
@@ -11823,7 +11869,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);
@@ -11980,7 +12026,7 @@ 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 readFileSync8,
@@ -12114,7 +12160,7 @@ async function encodeGifFromDir(framesDir, framePattern, outputPath, input) {
       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,
@@ -12275,7 +12321,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(
@@ -12286,7 +12332,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}`
@@ -12397,6 +12443,7 @@ async function assembleOutput(input, onSecondsWritten) {
     const normalizeResult = await padOrTrimAudioToVideoFrameCount({
       videoPath: videoOnlyPath,
       audioPath: audioOutputPath,
+      sourcePath: input.audioPcmPath,
       outputPath: normalizedAudioPath,
       signal: abortSignal,
       timeoutMs: ffmpegProcessTimeout
@@ -12678,7 +12725,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) {
@@ -12803,7 +12850,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;
 }
@@ -13468,7 +13515,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;
@@ -13610,7 +13657,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 });
     }
@@ -13640,7 +13687,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();
@@ -13648,7 +13695,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.`
         );
@@ -13959,7 +14006,8 @@ async function executeRenderPipeline(input) {
         masterFxChain: composition.masterFxChain,
         abortSignal: executionSignal,
         assertNotAborted,
-        log
+        log,
+        keepDeliverySource: true
       })
     );
     pendingAudio = audioStage.catch(() => void 0);
@@ -13991,7 +14039,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"
     });
@@ -14667,7 +14715,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) {
@@ -15293,6 +15341,7 @@ async function executeRenderPipeline(input) {
           job,
           videoOnlyPath,
           audioOutputPath,
+          audioPcmPath: deliverySourcePath,
           outputPath: stagedOutputPath,
           hasAudio,
           format: outputFormat,
@@ -15318,7 +15367,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({
@@ -15399,7 +15448,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);
       }
@@ -15511,7 +15560,7 @@ async function executeRenderPipeline(input) {
 
 // src/services/hyperframeLint.ts
 import {
-  existsSync as existsSync19,
+  existsSync as existsSync20,
   readFileSync as readFileSync9,
   statSync as statSync9,
   openSync as openSync5,
@@ -15565,7 +15614,7 @@ function readEntryHtml(filePath) {
 }
 function readProjectEntryFile(projectDir, preferredEntryFile) {
   const absProjectDir = resolve9(projectDir);
-  if (!existsSync19(absProjectDir) || !statSync9(absProjectDir).isDirectory()) {
+  if (!existsSync20(absProjectDir) || !statSync9(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entryCandidates = [preferredEntryFile, "index.html", "src/index.html"].filter(
@@ -15634,7 +15683,7 @@ async function runHyperframeLint(prepared) {
 import { Worker as Worker2 } from "node:worker_threads";
 import { fileURLToPath as fileURLToPath5 } from "node:url";
 import { dirname as dirname13, join as join30 } from "node:path";
-import { existsSync as existsSync20 } from "node:fs";
+import { existsSync as existsSync21 } from "node:fs";
 var DEFAULT_HEALTH_PORT = 9848;
 async function startHealthWorker(options = {}) {
   const log = options.logger ?? defaultLogger2();
@@ -15711,7 +15760,7 @@ function resolveWorkerEntry2() {
   const here = dirname13(fileURLToPath5(import.meta.url));
   const candidates = [join30(here, "healthWorkerThread.js"), join30(here, "healthWorkerThread.ts")];
   for (const candidate of candidates) {
-    if (existsSync20(candidate)) return candidate;
+    if (existsSync21(candidate)) return candidate;
   }
   return void 0;
 }
@@ -16261,7 +16310,7 @@ function resolvePreparedRenderOutput(prepared, rendersDir, log) {
   const { input, cleanupProjectDir } = prepared;
   const absoluteOutputPath = resolveOutputPath(input.projectDir, input.outputPath, rendersDir, log);
   const outputDir = dirname14(absoluteOutputPath);
-  if (!existsSync21(outputDir)) mkdirSync11(outputDir, { recursive: true });
+  if (!existsSync22(outputDir)) mkdirSync11(outputDir, { recursive: true });
   return { input, cleanupProjectDir, absoluteOutputPath };
 }
 function validateRenderOverrides(body) {
@@ -16302,11 +16351,11 @@ function prepareProjectDirectory(projectDir, options) {
   const candidate = nonEmptyString(projectDir);
   if (!candidate) return null;
   const absProjectDir = resolve10(candidate);
-  if (!existsSync21(absProjectDir) || !statSync10(absProjectDir).isDirectory()) {
+  if (!existsSync22(absProjectDir) || !statSync10(absProjectDir).isDirectory()) {
     return { error: `Project directory not found: ${absProjectDir}` };
   }
   const entry = options.entryFile || "index.html";
-  if (!existsSync21(resolve10(absProjectDir, entry))) {
+  if (!existsSync22(resolve10(absProjectDir, entry))) {
     return { error: `Entry file "${entry}" not found in project directory: ${absProjectDir}` };
   }
   return { prepared: { input: { projectDir: absProjectDir, ...options } } };
@@ -16398,7 +16447,7 @@ function cleanupTempDir(dir, log) {
   }
 }
 function outputFileSize(path) {
-  return existsSync21(path) ? statSync10(path).size : 0;
+  return existsSync22(path) ? statSync10(path).size : 0;
 }
 function createBlockingProgressReporter(log, requestId) {
   let lastLoggedPct = -10;
@@ -16702,7 +16751,7 @@ function createRenderHandlers(options = {}) {
     if (!artifact) {
       return c.json({ success: false, error: "Output artifact not found or expired" }, 404);
     }
-    if (!existsSync21(artifact.path)) {
+    if (!existsSync22(artifact.path)) {
       store.delete(token);
       return c.json({ success: false, error: "Output artifact file missing" }, 404);
     }

package/dist/services/render/audioPadTrim.d.ts

@@ -44,6 +44,8 @@ export interface PadTrimAudioInput {
     audioPath: string;
     /** Path the helper writes the duration-corrected audio to. */
     outputPath: string;
+    /** The PCM `audioPath` was encoded from: a pad, trim or peak correction encodes it instead of decoding the AAC. */
+    sourcePath?: string;
     signal?: AbortSignal;
     /** Deadline for each ffmpeg process; defaults to the engine's `ffmpegProcessTimeout`. */
     timeoutMs?: number;
@@ -126,12 +128,16 @@ export declare function constrainAacTruePeak(input: {
     timeoutMs?: number;
     probeTruePeakDbfs?: (audioPath: string, signal?: AbortSignal) => Promise<number>;
     encodeAac?: AacEncoder;
+    rewriteSource?: SourceRewriter;
 }): Promise<{
     success: boolean;
     error?: string;
     failureReason?: "external_interruption";
     loweredDb?: number;
+    sourceStale?: true;
 }>;
+/** Writes `sourcePath` through `filter` to `outputPath` as float PCM. */
+type SourceRewriter = (sourcePath: string, outputPath: string, filter: string) => Promise<StepResult>;
 export declare function defaultProbeVideoFrameInfo(videoPath: string, signal?: AbortSignal): Promise<ProbeVideoFrameInfo>;
 export declare function runFfprobeJson<T>(args: string[], signal?: AbortSignal): Promise<T>;
 export {};

package/dist/services/render/stages/assembleStage.d.ts

@@ -27,6 +27,7 @@ export interface AssembleStageInput {
     videoOnlyPath: string;
     /** Mixed audio path (only read when `hasAudio` is true). */
     audioOutputPath: string;
+    audioPcmPath?: string;
     /** Final on-disk output. A directory when `format` is `"hls"`. */
     outputPath: string;
     hasAudio: boolean;

package/dist/services/render/stages/audioStage.d.ts

@@ -41,12 +41,16 @@ export interface AudioStageInput {
     assertNotAborted: () => void;
     /** Where a per-track failure's detail goes. Optional so tests need not pass one. */
     log?: ProducerLogger;
+    /** Leave the delivered PCM in `workDir` for the assemble stage; its owner removes the dir. */
+    keepDeliverySource?: boolean;
 }
 export interface AudioStageResult {
     /** Actual delivery attenuation, for the render warning and metadata. */
     audioLoweredDb?: number;
     /** Always `join(workDir, MIXED_AUDIO_FILENAME)`. */
     audioOutputPath: string;
+    /** The PCM `audioOutputPath` encodes, when `keepDeliverySource` asked for it. */
+    deliverySourcePath?: string;
     /** True iff the audio mix actually produced a file. False when there are no audio elements. */
     hasAudio: boolean;
     /** Wall-clock ms for the audio mix phase. Zero-elements path is near-zero but always set. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.9.14",
+  "version": "0.9.15",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
-    "@hyperframes/core": "0.9.14",
-    "@hyperframes/lint": "0.9.14",
-    "@hyperframes/engine": "0.9.14",
-    "@hyperframes/studio-server": "0.9.14",
-    "@hyperframes/parsers": "0.9.14"
+    "@hyperframes/core": "0.9.15",
+    "@hyperframes/engine": "0.9.15",
+    "@hyperframes/lint": "0.9.15",
+    "@hyperframes/parsers": "0.9.15",
+    "@hyperframes/studio-server": "0.9.15"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",
@@ -48,7 +48,7 @@
     "tsx": "^4.21.0",
     "typescript": "^5.7.2",
     "vitest": "^4.1.11",
-    "@hyperframes/aws-lambda": "0.9.14"
+    "@hyperframes/aws-lambda": "0.9.15"
   },
   "engines": {
     "node": ">=22"