@hyperframes/producer 0.8.199 → 0.8.201

package/dist/services/renderOrchestrator.d.ts

@@ -29,51 +29,40 @@ export interface RenderConfig {
     /** Segmented capture: keep renders/.hf-segments/<planHash> after a successful render. */
     keepSegments?: boolean;
     /**
-     * Output container format. Defaults to `"mp4"`; existing renders are
-     * unaffected unless this field is set explicitly.
+     * Output container format. Defaults to `"mp4"`; set explicitly for other formats.
      *
-     * - `"mp4"`: H.264 by default, or H.265 + HDR10 when HDR auto-detect
-     *   engages or `hdrMode: "force-hdr"` is set. Opaque. The
-     *   default streaming/social deliverable. Faststart is applied so the
-     *   `moov` atom sits at the file start and the file plays from a
-     *   partial download.
-     * - `"webm"`: VP9 + `yuva420p` pixel format → **true alpha channel**, no
-     *   chroma key. Plays in Chrome, Edge, and Firefox; Safari support for
-     *   alpha-WebM is incomplete. Use this when the output should drop
-     *   straight into a `<video>` over a colored background on the web.
-     *   Audio is muxed as Opus.
-     * - `"mov"`: ProRes 4444 + `yuva444p10le` → **true alpha channel +
-     *   10-bit color**. Sized for editor ingest (Premiere, Final Cut Pro,
-     *   DaVinci Resolve), not direct web playback. Audio is muxed as AAC.
-     * - `"gif"`: animated GIF encoded from captured RGBA frames with a two-pass
-     *   FFmpeg palette (`palettegen` + `paletteuse`). Use for PRs, READMEs,
-     *   and docs where inline autoplay matters more than file size. No audio
-     *   stream; transparency is binary because GIF has no partial alpha.
-     * - `"png-sequence"`: a directory of zero-padded RGBA PNGs
-     *   (`frame_000001.png` …). Lossless alpha, largest on disk, no muxed
-     *   audio (an `audio.m4a` sidecar is written alongside the PNGs when
-     *   the composition has audio elements). Use for After Effects / Nuke
-     *   / Fusion ingest, or when frames need post-processing before
-     *   encoding. `outputPath` is treated as a directory; it is created if
-     *   it doesn't exist.
-     * - `"hls"`: HLS VOD package — the same opaque H.264 + AAC encode as
-     *   `"mp4"`, stream-copied (no re-encode) into a directory of MPEG-TS
-     *   segments: `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and
-     *   `audio.m3u8` + `audio_%05d.ts` when the composition has audio.
-     *   Segments are fixed-length (see {@link RenderConfig.hlsSegmentSeconds})
-     *   and every one starts on an IDR frame, because the encoder's GOP is
-     *   locked to `hlsSegmentSeconds × fps`. Like `"png-sequence"`,
-     *   `outputPath` is treated as a directory. SDR only, software encoder
-     *   only, and not available in distributed / Lambda / Cloud Run mode.
+     * - `"mp4"`: opaque H.264, or H.265 + HDR10 with HDR auto-detection or
+     *   `hdrMode: "force-hdr"`. For streaming/social delivery; faststart puts the
+     *   `moov` atom first so playback can begin during a partial download.
+     * - `"webm"`: VP9 + `yuva420p` with true alpha (no chroma key) and Opus audio.
+     *   For `<video>` overlays in Chrome, Edge and Firefox; Safari's alpha-WebM
+     *   support is incomplete.
+     * - `"mov"`: ProRes 4444 + `yuva444p10le` with true alpha and AAC audio.
+     *   Chrome captures 8-bit RGBA; encoding it as 10-bit ProRes does not add
+     *   capture precision. For editor ingest (Premiere, Final Cut Pro, DaVinci
+     *   Resolve), rather than direct web playback.
+     * - `"gif"`: animated GIF from RGBA captures, using FFmpeg's two-pass
+     *   `palettegen` + `paletteuse`. For inline autoplay in PRs, READMEs and docs
+     *   when file size matters less. No audio; transparency is binary, not partial.
+     * - `"png-sequence"`: zero-padded RGBA PNGs (`frame_000001.png` ...), with
+     *   lossless alpha and the largest disk footprint. No muxed audio; an
+     *   `audio.m4a` sidecar is written when the composition contains audio.
+     *   For After Effects / Nuke / Fusion or post-processing before encoding.
+     *   `outputPath` is a directory, created if it does not exist.
+     * - `"hls"`: HLS VOD using the opaque H.264 + AAC encode from `"mp4"`,
+     *   stream-copied without re-encoding into MPEG-TS in the `outputPath` directory:
+     *   `master.m3u8`, `video.m3u8` + `video_%05d.ts`, and `audio.m3u8` +
+     *   `audio_%05d.ts` when the composition contains audio. Segment length is
+     *   {@link RenderConfig.hlsSegmentSeconds}; the encoder's GOP is locked to
+     *   that length in frames, so each segment starts on an IDR frame.
+     *   SDR and software encoders only; unavailable in distributed rendering,
+     *   including Lambda and Cloud Run.
      *
-     * Alpha output (`"webm"`, `"mov"`, `"png-sequence"`, `"gif"`) automatically
-     * forces screenshot capture (Chrome's BeginFrame compositor does not
-     * preserve alpha on Linux headless-shell) and disables HDR — HDR +
-     * alpha is not a supported combination, a warning is logged and HDR
-     * falls back to SDR. The transparent-background CSS is injected by
-     * the engine's `initTransparentBackground` helper, so authors should
-     * not paint a fullscreen `body` / `#root` background in their
-     * compositions when targeting alpha output.
+     * Alpha formats (`"webm"`, `"mov"`, `"png-sequence"`, `"gif"`) force screenshot
+     * capture because BeginFrame does not preserve alpha on Linux headless-shell.
+     * HDR + alpha is unsupported: a warning is logged and output falls back to SDR.
+     * The engine's `initTransparentBackground` injects transparent-background CSS;
+     * avoid painting a fullscreen `body` / `#root` background for alpha output.
      */
     format?: RenderOutputFormat;
     /** GIF Netscape loop count. 0 means infinite looping. Only used with `format: "gif"`. */
@@ -290,7 +279,7 @@ export interface RenderPerfSummary {
     drawElement?: {
         /** Final capture mode: "drawelement" | "screenshot" | "beginframe" (|-joined if workers diverge). */
         mode: string;
-        /** Compile-time gate that disabled default DE: 3d | mix_blend_mode | shader_transitions. */
+        /** Compile-time gate that disabled default DE: 3d | ancestor_background_image | shader_transitions. */
         compileGate?: string;
         /** Producer clamp that disabled default DE: parallel | disk_path. */
         clampReason?: string;
@@ -367,6 +356,7 @@ export interface RenderPerfSummary {
         blankRecaptures: number;
         /** Clip-cut boundary frames captured via per-frame screenshot. */
         boundaryFrames: number;
+        riskFrames: number;
         /** Per-frame "No cached paint record" screenshot fallbacks. */
         ncprFallbacks: number;
         /**
@@ -480,7 +470,7 @@ interface ExtractedVideoReadinessInput {
 }
 export declare function collectVideoMetadataHints(extractedVideos: readonly ExtractedVideoReadinessInput[]): CaptureVideoMetadataHint[];
 export declare function findMissingFrameRanges(totalFrames: number, framesDir: string, frameExt: "jpg" | "png"): FrameRange[];
-export declare function buildMissingFrameRetryBatches(ranges: FrameRange[], maxWorkers: number, workDir: string, attempt: number, rangeStart?: number): WorkerTask[][];
+export declare function buildMissingFrameRetryBatches(ranges: FrameRange[], maxWorkers: number, workDir: string, attempt: number, rangeStart?: number, stride?: number): WorkerTask[][];
 /**
  * The capture mode this render will REPORT, pre-capture.
  *
@@ -595,6 +585,8 @@ export declare function executeDiskCaptureWithAdaptiveRetry(options: {
     createBeforeCaptureHook: () => BeforeCaptureHook | null;
     abortSignal?: AbortSignal;
     onProgress?: (progress: ParallelProgress) => void;
+    /** Workers take frames round-robin so an in-order consumer (the overlapped encoder) is never starved. */
+    interleaveFrames?: boolean;
     cfg: EngineConfig;
     log: ProducerLogger;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/producer",
-  "version": "0.8.199",
+  "version": "0.8.201",
   "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/core": "0.8.199",
-    "@hyperframes/lint": "0.8.199",
-    "@hyperframes/parsers": "0.8.199",
-    "@hyperframes/studio-server": "0.8.199",
-    "@hyperframes/engine": "0.8.199"
+    "@hyperframes/core": "0.8.201",
+    "@hyperframes/engine": "0.8.201",
+    "@hyperframes/studio-server": "0.8.201",
+    "@hyperframes/parsers": "0.8.201",
+    "@hyperframes/lint": "0.8.201"
   },
   "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.199"
+    "@hyperframes/aws-lambda": "0.8.201"
   },
   "engines": {
     "node": ">=22"