@hyperframes/producer 0.8.189 → 0.8.191

package/dist/index.js

@@ -1188,6 +1188,14 @@ function materializeExtractedFramesForCompiledDir(extracted, compiledDir, option
   }
 }
 
+// src/services/render/frameCacheBudget.ts
+function frameCacheOptions(cfg, workers) {
+  return {
+    frameDataUriCacheLimit: cfg.frameDataUriCacheLimit,
+    frameDataUriCacheBytesLimitMb: Math.floor(cfg.frameDataUriCacheBytesLimitMb / (workers || 1))
+  };
+}
+
 // src/services/render/cleanup.ts
 import { freemem } from "node:os";
 
@@ -1500,7 +1508,7 @@ async function defaultArtifactDurationProbe(path) {
   };
 }
 function buildArtifactExpectation(input) {
-  if (input.outputFormat === "png-sequence" || input.outputFormat === "gif") return void 0;
+  if (input.outputFormat === "gif") return void 0;
   if (!Number.isFinite(input.durationSeconds) || input.durationSeconds <= 0) return void 0;
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
@@ -1565,12 +1573,12 @@ function assertDurationWithinTolerance(expectedSeconds, probedSeconds, tolerance
     `Render artifact is truncated: expected ${expectedSeconds.toFixed(3)}s, probed ${probedSeconds.toFixed(3)}s (deficit ${deficit.toFixed(3)}s exceeds tolerance ${toleranceSeconds.toFixed(3)}s). Artifact: ${stagingPath}`
   );
 }
-function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath) {
+function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath, toleranceFrames = 1) {
   if (probedFrames === void 0 || !Number.isFinite(probedFrames) || probedFrames <= 0) {
     return;
   }
   const shortfall = expectedFrames - probedFrames;
-  if (shortfall <= 1) return;
+  if (shortfall <= toleranceFrames) return;
   throw new Error(
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
@@ -1607,8 +1615,8 @@ var ArtifactTransaction = class {
       if (expected) await this.assertArtifactDuration(expected);
       return;
     }
-    this.assertReadableNonEmptyDirectory();
-    if (expected) await this.assertDirectoryExpectation(expected);
+    const files = this.assertReadableNonEmptyDirectory();
+    if (expected) await this.assertDirectoryExpectation(expected, files);
   }
   assertReadableNonEmptyDirectory() {
     let files;
@@ -1623,13 +1631,14 @@ var ArtifactTransaction = class {
       throw new Error(`Render artifact directory is empty: ${this.stagingPath}`);
     }
     for (const file of files) assertReadableNonEmptyFile(file);
+    return files;
   }
   /**
    * The named-entry and duration gates a directory artifact opts into. A
-   * directory has no single probe target, so an expectation without
-   * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+   * directory with a probe target checks duration; one without a probe target
+   * checks the exported PNG frame count when the caller supplied it.
    */
-  async assertDirectoryExpectation(expected) {
+  async assertDirectoryExpectation(expected, files) {
     for (const required of expected.requiredFiles ?? []) {
       const path = join5(this.stagingPath, required);
       if (!existsSync5(path)) {
@@ -1637,8 +1646,25 @@ var ArtifactTransaction = class {
       }
       assertReadableNonEmptyFile(path);
     }
-    if (expected.probeTarget === void 0) return;
-    await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+    if (expected.probeTarget !== void 0) {
+      await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+      return;
+    }
+    if (expected.expectedFrames === void 0) return;
+    const frameCount = files.filter(
+      (file) => dirname4(file) === this.stagingPath && /^frame_\d+\.png$/.test(basename3(file))
+    ).length;
+    if (frameCount === 0) {
+      throw new Error(
+        `Render artifact is truncated: expected ${expected.expectedFrames} frames, probed 0 frames. Artifact: ${this.stagingPath}`
+      );
+    }
+    assertFrameCountWithinTolerance(
+      expected.expectedFrames,
+      frameCount,
+      this.stagingPath,
+      Math.max(1, Math.ceil(expected.expectedFrames * 2e-3))
+    );
   }
   async assertArtifactDuration(expected, probePath = this.stagingPath) {
     const expectedSeconds = expected.expectedDurationSeconds;
@@ -7137,7 +7163,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
       );
       if (analysis.isProblematic) {
         defaultLogger.warn(
-          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). This causes seek failures and frame freezing. Re-encode with: ${reencode}`
+          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). Long GOPs can make preview seeking slower; rendering is unaffected. If preview seeking is slow, re-encode with: ${reencode}`
         );
       }
       if (metadata.isVFR) {
@@ -9188,6 +9214,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -9211,6 +9238,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
           audioGain,
           masterFxChain,
           urlByAbsentLocalPath,
+          audioSidecarUrlByLocalPath,
           keepEncoderInputAt: pcmSourcePath
         },
         compiledDir
@@ -12515,10 +12543,7 @@ async function executeRenderPipeline(input) {
         });
       }
     });
-    const createRenderVideoFrameInjector = () => createVideoFrameInjector(frameLookup, {
-      frameDataUriCacheLimit: cfg.frameDataUriCacheLimit,
-      frameDataUriCacheBytesLimitMb: cfg.frameDataUriCacheBytesLimitMb
-    });
+    const createRenderVideoFrameInjector = () => createVideoFrameInjector(frameLookup, frameCacheOptions(cfg, workerCount));
     let captureCalibration;
     const htmlInCanvasDetected = compiled.renderModeHints.reasons.some(
       (r) => r.code === "htmlInCanvas"
@@ -14172,12 +14197,13 @@ var RenderChunkValidationError = class extends Error {
     this.code = code;
   }
 };
-function createChunkVideoFrameInjectorFactory(frameLookup) {
-  if (!(frameLookup instanceof Promise)) return () => createVideoFrameInjector2(frameLookup);
+function createChunkVideoFrameInjectorFactory(frameLookup, options) {
+  if (!(frameLookup instanceof Promise))
+    return () => createVideoFrameInjector2(frameLookup, options);
   return () => {
     let hook;
     return async (page, time, heldVideoTime) => {
-      hook ??= createVideoFrameInjector2(await frameLookup);
+      hook ??= createVideoFrameInjector2(await frameLookup, options);
       await hook?.(page, time, heldVideoTime);
     };
   };
@@ -15895,6 +15921,11 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
   const localPathByUrl = new Map(
     remoteFiles.map(([rel, file]) => [file.url, remoteLocalPath(rel)])
   );
+  const audioSidecarUrlByLocalPath = new Map(
+    remoteFiles.flatMap(
+      ([rel, file]) => file.audioSidecarUrl ? [[remoteLocalPath(rel), file.audioSidecarUrl]] : []
+    )
+  );
   stageStarted = Date.now();
   const compileResult = await runCompileStage({
     urlByAbsentLocalPath,
@@ -15979,6 +16010,7 @@ async function compilePlanComposition(projectDir, config, planDir, options) {
     finalCompiledDir,
     remoteFiles,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     localPathByUrl,
     compileResult,
     compiled,
@@ -15996,6 +16028,7 @@ function mixPlanAudio(c, compiledDir) {
     workDir: c.workDir,
     compiledDir,
     urlByAbsentLocalPath: c.urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath: c.audioSidecarUrlByLocalPath,
     totalFrames: c.totalFrames,
     fps: c.job.config.fps,
     ffmpegProcessTimeout: c.cfg.ffmpegProcessTimeout,
@@ -18975,6 +19008,22 @@ async function createVerifiedDistributedCaptureSession(serverUrl, framesDir, cap
 function isCaptureMode(value) {
   return value === "beginframe" || value === "screenshot" || value === "drawelement";
 }
+var MixedCaptureModesError = class extends Error {
+  constructor(modes) {
+    super(`[renderChunk] capture workers reported inconsistent modes: ${modes.join(",")}`);
+    this.modes = modes;
+    this.name = "MixedCaptureModesError";
+  }
+};
+function observedChunkCaptureMode(perfs) {
+  const modes = [...new Set(perfs.map((perf) => perf.captureMode))];
+  if (modes.length > 1) throw new MixedCaptureModesError(modes);
+  const [mode] = modes;
+  if (!mode || !isCaptureMode(mode)) {
+    throw new Error(`[renderChunk] capture workers reported an invalid mode: ${mode ?? "<none>"}`);
+  }
+  return mode;
+}
 function shouldRetryChunkCaptureWithScreenshot(error) {
   const failure = classifyCaptureFailure4(error);
   if (failure.kind === "cancelled" || failure.kind === "memory_exhaustion") return false;
@@ -19272,7 +19321,10 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
       ) : null;
       videoFrameLookup?.catch(() => {
       });
-      const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(videoFrameLookup);
+      const createChunkVideoFrameInjector = createChunkVideoFrameInjectorFactory(
+        videoFrameLookup,
+        frameCacheOptions(cfg, chunkWorkerCount)
+      );
       const captureStarted = Date.now();
       captureMode = await runCaptureWithScreenshotFallback({
         forceScreenshot: forceScreenshotForChunk,
@@ -19326,17 +19378,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
             },
             frameRange: range
           });
-          const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
-          if (observedModes.size !== 1 || ![...observedModes].every(isCaptureMode)) {
-            throw new Error(
-              `[renderChunk] capture workers reported invalid or inconsistent modes: ${[...observedModes].join(",") || "<none>"}`
-            );
-          }
-          const [observedMode] = observedModes;
-          if (!observedMode || !isCaptureMode(observedMode)) {
-            throw new Error("[renderChunk] capture completed without an observed mode");
-          }
-          return observedMode;
+          return observedChunkCaptureMode(capturePerfs);
         },
         resetForScreenshotRetry: () => {
           rmSync17(workDir, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
@@ -19541,6 +19583,10 @@ async function assembleV2(planV2Dir, chunkPaths, outputPath, options) {
 
 // src/services/distributed/projectHash.ts
 var READ_CHUNK_BYTES = 256 * 1024;
+
+// src/services/distributed/audioSidecar.ts
+import { extractAudioMetadata as extractAudioMetadata4, runFfmpeg as runFfmpeg8 } from "@hyperframes/engine";
+var AUDIO_SIDECAR_MIN_BYTES = 32 * 1024 * 1024;
 export {
   CURRENT_PLAN_PROTOCOL,
   DEFAULT_CONFIG2 as DEFAULT_CONFIG,

package/dist/public-server.js

@@ -1208,6 +1208,14 @@ function materializeExtractedFramesForCompiledDir(extracted, compiledDir, option
   }
 }
 
+// src/services/render/frameCacheBudget.ts
+function frameCacheOptions(cfg, workers) {
+  return {
+    frameDataUriCacheLimit: cfg.frameDataUriCacheLimit,
+    frameDataUriCacheBytesLimitMb: Math.floor(cfg.frameDataUriCacheBytesLimitMb / (workers || 1))
+  };
+}
+
 // src/services/render/cleanup.ts
 import { freemem } from "node:os";
 
@@ -1519,7 +1527,7 @@ async function defaultArtifactDurationProbe(path) {
   };
 }
 function buildArtifactExpectation(input) {
-  if (input.outputFormat === "png-sequence" || input.outputFormat === "gif") return void 0;
+  if (input.outputFormat === "gif") return void 0;
   if (!Number.isFinite(input.durationSeconds) || input.durationSeconds <= 0) return void 0;
   const expectation = {
     expectedDurationSeconds: input.durationSeconds,
@@ -1584,12 +1592,12 @@ function assertDurationWithinTolerance(expectedSeconds, probedSeconds, tolerance
     `Render artifact is truncated: expected ${expectedSeconds.toFixed(3)}s, probed ${probedSeconds.toFixed(3)}s (deficit ${deficit.toFixed(3)}s exceeds tolerance ${toleranceSeconds.toFixed(3)}s). Artifact: ${stagingPath}`
   );
 }
-function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath) {
+function assertFrameCountWithinTolerance(expectedFrames, probedFrames, stagingPath, toleranceFrames = 1) {
   if (probedFrames === void 0 || !Number.isFinite(probedFrames) || probedFrames <= 0) {
     return;
   }
   const shortfall = expectedFrames - probedFrames;
-  if (shortfall <= 1) return;
+  if (shortfall <= toleranceFrames) return;
   throw new Error(
     `Render artifact is truncated: expected ${expectedFrames} frames, probed ${probedFrames} frames (shortfall ${shortfall} frames). Artifact: ${stagingPath}`
   );
@@ -1626,8 +1634,8 @@ var ArtifactTransaction = class {
       if (expected) await this.assertArtifactDuration(expected);
       return;
     }
-    this.assertReadableNonEmptyDirectory();
-    if (expected) await this.assertDirectoryExpectation(expected);
+    const files = this.assertReadableNonEmptyDirectory();
+    if (expected) await this.assertDirectoryExpectation(expected, files);
   }
   assertReadableNonEmptyDirectory() {
     let files;
@@ -1642,13 +1650,14 @@ var ArtifactTransaction = class {
       throw new Error(`Render artifact directory is empty: ${this.stagingPath}`);
     }
     for (const file of files) assertReadableNonEmptyFile(file);
+    return files;
   }
   /**
    * The named-entry and duration gates a directory artifact opts into. A
-   * directory has no single probe target, so an expectation without
-   * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+   * directory with a probe target checks duration; one without a probe target
+   * checks the exported PNG frame count when the caller supplied it.
    */
-  async assertDirectoryExpectation(expected) {
+  async assertDirectoryExpectation(expected, files) {
     for (const required of expected.requiredFiles ?? []) {
       const path = join5(this.stagingPath, required);
       if (!existsSync5(path)) {
@@ -1656,8 +1665,25 @@ var ArtifactTransaction = class {
       }
       assertReadableNonEmptyFile(path);
     }
-    if (expected.probeTarget === void 0) return;
-    await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+    if (expected.probeTarget !== void 0) {
+      await this.assertArtifactDuration(expected, join5(this.stagingPath, expected.probeTarget));
+      return;
+    }
+    if (expected.expectedFrames === void 0) return;
+    const frameCount = files.filter(
+      (file) => dirname4(file) === this.stagingPath && /^frame_\d+\.png$/.test(basename3(file))
+    ).length;
+    if (frameCount === 0) {
+      throw new Error(
+        `Render artifact is truncated: expected ${expected.expectedFrames} frames, probed 0 frames. Artifact: ${this.stagingPath}`
+      );
+    }
+    assertFrameCountWithinTolerance(
+      expected.expectedFrames,
+      frameCount,
+      this.stagingPath,
+      Math.max(1, Math.ceil(expected.expectedFrames * 2e-3))
+    );
   }
   async assertArtifactDuration(expected, probePath = this.stagingPath) {
     const expectedSeconds = expected.expectedDurationSeconds;
@@ -7156,7 +7182,7 @@ async function compileForRender(projectDir, htmlPath, downloadDir, options = {})
       );
       if (analysis.isProblematic) {
         defaultLogger.warn(
-          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). This causes seek failures and frame freezing. Re-encode with: ${reencode}`
+          `[Compiler] WARNING: Video "${video.id}" has sparse keyframes (max interval: ${analysis.maxIntervalSeconds}s). Long GOPs can make preview seeking slower; rendering is unaffected. If preview seeking is slow, re-encode with: ${reencode}`
         );
       }
       if (metadata.isVFR) {
@@ -9171,6 +9197,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
     audios,
     masterFxChain,
     urlByAbsentLocalPath,
+    audioSidecarUrlByLocalPath,
     abortSignal,
     assertNotAborted,
     log
@@ -9194,6 +9221,7 @@ async function mixAudioForDelivery(input, duration, pcmSourcePath) {
           audioGain,
           masterFxChain,
           urlByAbsentLocalPath,
+          audioSidecarUrlByLocalPath,
           keepEncoderInputAt: pcmSourcePath
         },
         compiledDir
@@ -12498,10 +12526,7 @@ async function executeRenderPipeline(input) {
         });
       }
     });
-    const createRenderVideoFrameInjector = () => createVideoFrameInjector(frameLookup, {
-      frameDataUriCacheLimit: cfg.frameDataUriCacheLimit,
-      frameDataUriCacheBytesLimitMb: cfg.frameDataUriCacheBytesLimitMb
-    });
+    const createRenderVideoFrameInjector = () => createVideoFrameInjector(frameLookup, frameCacheOptions(cfg, workerCount));
     let captureCalibration;
     const htmlInCanvasDetected = compiled.renderModeHints.reasons.some(
       (r) => r.code === "htmlInCanvas"

package/dist/services/distributed/audioSidecar.d.ts

@@ -0,0 +1,10 @@
+/**
+ * A video's audio copied out of its container, nothing re-encoded, stored beside it. Reading audio from the
+ * cloud file moves the whole interleaved file; the sidecar is a few MB.
+ */
+/** Smaller files are cheap to read whole. */
+export declare const AUDIO_SIDECAR_MIN_BYTES: number;
+export declare function wantsAudioSidecar(path: string, sizeBytes: number): boolean;
+/** `unavailable`: no ffmpeg on this machine. `none`: no audio, or audio the sidecar would not read back the same. */
+export type AudioSidecarOutcome = "built" | "none" | "unavailable";
+export declare function buildAudioSidecar(inputPath: string, outputPath: string, signal?: AbortSignal): Promise<AudioSidecarOutcome>;

package/dist/services/distributed/chunkFrames.d.ts

@@ -1,4 +1,4 @@
-import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable, type ShownBox } from "@hyperframes/engine";
+import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, createVideoFrameInjector, type EngineConfig, type ExtractedFrames, type FrameLookupTable, type ShownBox } from "@hyperframes/engine";
 import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
 import type { PlanV2RemoteSources } from "./planV2.js";
 import { type DistributedFormat, INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
@@ -17,7 +17,7 @@ export declare class RenderChunkValidationError extends Error {
     constructor(code: RenderChunkValidationCode, message: string);
 }
 /** One injector per browser session: a hook reused on a fresh page can skip its first injection. */
-export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | Promise<FrameLookupTable> | null): () => BeforeCaptureHook | null;
+export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | Promise<FrameLookupTable> | null, options?: Parameters<typeof createVideoFrameInjector>[1]): () => BeforeCaptureHook | null;
 /**
  * Rebuilds `ExtractedFrames[]` from `<planDir>/video-frames/<videoId>/`. `framePaths` keys are 0-based
  * frame indexes (what `getFrameAtTime` reads); any other key drops every video's first-paint frame.

package/dist/services/distributed/plan.d.ts

@@ -217,6 +217,8 @@ export interface BuildLocalExecutionPlanOptions {
 }
 export interface RemoteProjectFile {
     readonly url: string;
+    /** A file of only this video's audio, when one was stored: the audio mix reads it, not the video. */
+    readonly audioSidecarUrl?: string;
     readonly sha256: string;
     readonly sizeBytes: number;
 }

package/dist/services/distributed/renderChunk.d.ts

@@ -33,7 +33,7 @@
  * Every determinism toggle above is opt-in — only this primitive enables them.
  * In-process renders (`executeRenderJob`) leave them off.
  */
-import { assertSwiftShader, type CaptureOptions, type CaptureMode, type CaptureSession, closeCaptureSession, createCaptureSession, type EngineConfig, initializeSession, probeBeginFrameLiveness, readWebGlVendorInfoFromCanvas } from "@hyperframes/engine";
+import { assertSwiftShader, type CaptureOptions, type CaptureMode, type CapturePerfSummary, type CaptureSession, closeCaptureSession, createCaptureSession, type EngineConfig, initializeSession, probeBeginFrameLiveness, readWebGlVendorInfoFromCanvas } from "@hyperframes/engine";
 import { type ChunkSliceJson, type LockedRenderConfig } from "../render/stages/freezePlan.js";
 import { type PlanVideosJson } from "./shared.js";
 export { CHUNK_FRAME_RANGE_INVALID, CHUNK_INDEX_OUT_OF_RANGE, createChunkVideoFrameInjectorFactory, extractDeferredVideoFramesForChunk, FFMPEG_VERSION_MISMATCH, INVALID_VIDEO_METADATA, MISSING_PLAN_ARTIFACT, MISSING_RUNTIME_ENV_SNAPSHOT, PLAN_HASH_MISMATCH, rebuildExtractedFramesFromPlanDir, RenderChunkValidationError, } from "./chunkFrames.js";
@@ -136,6 +136,12 @@ export declare const distributedCaptureSessionDependencies: DistributedCaptureSe
  * assertion, including fresh screenshot browsers created after a fallback.
  */
 export declare function createVerifiedDistributedCaptureSession(serverUrl: string, framesDir: string, captureOptions: CaptureOptions, cfg: EngineConfig, dependencies?: DistributedCaptureSessionDependencies): Promise<CaptureSession>;
+/** Workers of one chunk launched in different modes: one worker's BeginFrame check failed and it fell back alone. */
+export declare class MixedCaptureModesError extends Error {
+    readonly modes: readonly string[];
+    constructor(modes: readonly string[]);
+}
+export declare function observedChunkCaptureMode(perfs: readonly Pick<CapturePerfSummary, "captureMode">[]): CaptureMode;
 /**
  * Only BeginFrame-specific failures are safe to retry in screenshot mode.
  * Cancellation, memory exhaustion, and unrelated authoring/IO failures must

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

@@ -37,7 +37,7 @@ export interface ArtifactDurationProbeResult {
  */
 export type ArtifactDurationProbe = (path: string) => Promise<ArtifactDurationProbeResult>;
 /**
- * Caller-supplied expectation for file-artifact validation. The transaction
+ * Caller-supplied expectation for artifact validation. The transaction
  * still does the readable-non-empty check; this layer adds a duration /
  * frame-count comparison against the values the pipeline already held.
  *
@@ -48,15 +48,15 @@ export type ArtifactDurationProbe = (path: string) => Promise<ArtifactDurationPr
  *
  * `toleranceSeconds` defaults to a single frame at `fps` (or 20 ms when fps
  * is unknown) so that a normal container-level last-frame rounding does not
- * trip the gate. Multi-frame drops (e.g. the 326-frame / 11s truncation in
- * #3395) still fail.
+ * trip the gate. Multi-frame drops beyond that tolerance still fail.
  *
  * `probeTarget` / `requiredFiles` exist for directory artifacts. A `"file"`
  * artifact is its own probe target; a directory has no single one, so an HLS
  * output names its video playlist (`probeTarget: "video.m3u8"`) and the files
  * that must be present (`requiredFiles: ["master.m3u8"]`). Without
- * `probeTarget` the directory branch keeps its historical behavior — readable
- * non-empty files only, no duration gate (png-sequence).
+ * `probeTarget`, an `expectedFrames` value instead checks the top-level PNG
+ * frame files. Directory artifacts without either keep their historical
+ * readable-non-empty check.
  */
 export interface ArtifactValidationExpectation {
     expectedDurationSeconds: number;
@@ -75,8 +75,10 @@ export interface ArtifactValidationExpectation {
  * The per-format expectation the render pipeline hands `validate()`, or
  * `undefined` when the format has nothing probeable.
  *
- * - `png-sequence` / `gif`: no expectation. A PNG directory has no container
- *   duration, and the GIF encoder writes `outputPath` itself without a
+ * - `png-sequence`: count exported PNG frames without a duration probe.
+ *   `expectedDurationSeconds` is carried by the shared expectation but is
+ *   unused for this directory format.
+ * - `gif`: no expectation. The GIF encoder writes `outputPath` itself without a
  *   frame-accurate duration the pipeline could compare against.
  * - `hls`: the directory's `video.m3u8` is the probe target and `master.m3u8`
  *   must exist. `expectedFrames` is passed through but is inert — ffprobe
@@ -104,8 +106,9 @@ export declare function buildArtifactExpectation(input: {
  * transaction additionally probes the staged artifact's container duration
  * (and decoded frame count when available) and rejects any artifact that is
  * significantly shorter than what the pipeline asked for. A directory artifact
- * is probed only when `expected.probeTarget` names a file inside it. The
- * readable-non-empty check is unchanged; this is a second gate on top.
+ * is probed only when `expected.probeTarget` names a file inside it.
+ * Without a directory probe target, the expectation instead checks exported
+ * PNG frame files. The readable-non-empty check is a separate gate.
  */
 export declare class ArtifactTransaction {
     private readonly kind;
@@ -121,8 +124,8 @@ export declare class ArtifactTransaction {
     private assertReadableNonEmptyDirectory;
     /**
      * The named-entry and duration gates a directory artifact opts into. A
-     * directory has no single probe target, so an expectation without
-     * `probeTarget` (png-sequence) keeps the historical behavior: structure only.
+     * directory with a probe target checks duration; one without a probe target
+     * checks the exported PNG frame count when the caller supplied it.
      */
     private assertDirectoryExpectation;
     private assertArtifactDuration;

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

@@ -0,0 +1,3 @@
+import type { EngineConfig } from "@hyperframes/engine";
+/** Cache options for one of `workers` injectors that share the configured budget on the one Node heap. */
+export declare function frameCacheOptions(cfg: Pick<EngineConfig, "frameDataUriCacheLimit" | "frameDataUriCacheBytesLimitMb">, workers: number | undefined): Pick<EngineConfig, "frameDataUriCacheLimit" | "frameDataUriCacheBytesLimitMb">;

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

@@ -36,6 +36,7 @@ export interface AudioStageInput {
     audios: CompositionMetadata["audios"];
     masterFxChain?: string;
     urlByAbsentLocalPath?: ReadonlyMap<string, string>;
+    audioSidecarUrlByLocalPath?: ReadonlyMap<string, string>;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     /** Where a per-track failure's detail goes. Optional so tests need not pass one. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.189",
+  "version": "0.8.191",
   "description": "HTML-to-video rendering engine using Chrome's BeginFrame API",
   "repository": {
     "type": "git",
@@ -35,11 +35,11 @@
     "postcss": "^8.4.0",
     "puppeteer": "^25.2.1",
     "puppeteer-core": "^25.2.1",
-    "@hyperframes/engine": "0.8.189",
-    "@hyperframes/parsers": "0.8.189",
-    "@hyperframes/lint": "0.8.189",
-    "@hyperframes/studio-server": "0.8.189",
-    "@hyperframes/core": "0.8.189"
+    "@hyperframes/lint": "0.8.191",
+    "@hyperframes/core": "0.8.191",
+    "@hyperframes/parsers": "0.8.191",
+    "@hyperframes/studio-server": "0.8.191",
+    "@hyperframes/engine": "0.8.191"
   },
   "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.8.189"
+    "@hyperframes/aws-lambda": "0.8.191"
   },
   "engines": {
     "node": ">=22"