@hyperframes/producer 0.8.179 → 0.8.180

package/dist/index.js

@@ -13927,6 +13927,7 @@ var FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 var PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
 var MISSING_PLAN_ARTIFACT = "MISSING_PLAN_ARTIFACT";
 var CHUNK_INDEX_OUT_OF_RANGE = "CHUNK_INDEX_OUT_OF_RANGE";
+var CHUNK_FRAME_RANGE_INVALID = "CHUNK_FRAME_RANGE_INVALID";
 var MISSING_RUNTIME_ENV_SNAPSHOT = "MISSING_RUNTIME_ENV_SNAPSHOT";
 var RenderChunkValidationError = class extends Error {
   code;
@@ -14178,7 +14179,8 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
       accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
       acceptsLegacyV1WithoutDescriptor: true
     })
-  })
+  }),
+  chunkFrameRange: true
 });
 function getDistributedRenderCapabilities() {
   return DISTRIBUTED_RENDER_CAPABILITIES;
@@ -14893,6 +14895,18 @@ function audioCutForChunk(grid, chunks, index, fps) {
   const durationSeconds = end === grid.packetCount ? null : cutSeconds(end) - (seekSeconds ?? 0);
   return { seekSeconds, durationSeconds, firstPacket: first, packetCount: end - first };
 }
+function chunksWithSubRange(chunks, index, range) {
+  const slice = chunks[index];
+  const parts = [
+    { startFrame: slice.startFrame, endFrame: range.startFrame },
+    range,
+    { startFrame: range.endFrame, endFrame: slice.endFrame }
+  ].filter((part) => part.endFrame > part.startFrame);
+  const split = [...chunks.slice(0, index), ...parts, ...chunks.slice(index + 1)].map(
+    (chunk, i) => ({ index: i, startFrame: chunk.startFrame, endFrame: chunk.endFrame })
+  );
+  return { chunks: split, index: range.startFrame > slice.startFrame ? index + 1 : index };
+}
 async function probeAacPacketGrid(audioPath) {
   const probe = await runFfprobeJson([
     "-v",
@@ -18234,11 +18248,12 @@ function cfrRateControlArgs(locked) {
   }
   return ["-preset", preset.preset, "-crf", String(locked.crf ?? preset.quality)];
 }
-async function assemble(planDir, chunkPaths, audioPath, outputPath, options) {
+async function assemble(planDir, chunkOutputs, audioPath, outputPath, options) {
   const start = Date.now();
   const log = options?.logger ?? defaultLogger;
   const cfr = options?.cfr === true;
-  const plan2 = readAssemblePlan(planDir, chunkPaths);
+  const plan2 = readAssemblePlan(planDir, chunkOutputs);
+  const chunkPaths = chunkOutputs.flat();
   if (plan2.dimensions.format === "png-sequence") {
     return mergePngFrameDirs(chunkPaths, outputPath, plan2.totalFrames, audioPath, start);
   }
@@ -18321,7 +18336,12 @@ function readAssemblePlan(planDir, chunkPaths) {
       `[assemble] chunkPaths length (${chunkPaths.length}) does not match chunks.json length (${chunks.length}). Adapters must pass one path per chunk, ordered by index.`
     );
   }
-  for (const path of chunkPaths) {
+  for (const [index, entry] of chunkPaths.entries()) {
+    if (typeof entry !== "string" && entry.length === 0) {
+      throw new Error(`[assemble] chunk ${index} has an empty list of parts`);
+    }
+  }
+  for (const path of chunkPaths.flat()) {
     if (!existsSync27(path)) {
       throw new Error(`[assemble] chunk path does not exist: ${path}`);
     }
@@ -18540,6 +18560,17 @@ function validatePlanVideosForChunk(value) {
     );
   }
 }
+function resolveChunkFrameRange(slice, chunkIndex, frameRange) {
+  if (frameRange === void 0) return { startFrame: slice.startFrame, endFrame: slice.endFrame };
+  const { startFrame, endFrame } = frameRange;
+  if (!Number.isSafeInteger(startFrame) || !Number.isSafeInteger(endFrame) || startFrame < slice.startFrame || endFrame > slice.endFrame || endFrame <= startFrame) {
+    throw new RenderChunkValidationError(
+      CHUNK_FRAME_RANGE_INVALID,
+      `[renderChunk] frameRange ${JSON.stringify(frameRange)} must be a non-empty integer range inside chunk ${chunkIndex}'s slice [${slice.startFrame}, ${slice.endFrame})`
+    );
+  }
+  return { startFrame, endFrame };
+}
 var distributedCaptureSessionDependencies = {
   createCaptureSession: createCaptureSession10,
   assertSwiftShader,
@@ -18610,7 +18641,7 @@ function resolveLockedVp9CpuUsed(lockedEncoder) {
   if (lockedEncoder.encoder !== "libvpx-vp9-software") return void 0;
   return lockedEncoder.vp9CpuUsed ?? LEGACY_DISTRIBUTED_VP9_CPU_USED;
 }
-async function renderChunk(planDir, chunkIndex, outputChunkPath) {
+async function renderChunk(planDir, chunkIndex, outputChunkPath, options) {
   const start = Date.now();
   const log = defaultLogger;
   const planJsonPath = join42(planDir, "plan.json");
@@ -18664,13 +18695,15 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
   if (slice === void 0) {
     throw new RenderChunkValidationError(CHUNK_INDEX_OUT_OF_RANGE, "[renderChunk] missing slice");
   }
-  const framesInChunk = slice.endFrame - slice.startFrame;
-  if (framesInChunk <= 0) {
+  const sliceFrames = slice.endFrame - slice.startFrame;
+  if (sliceFrames <= 0) {
     throw new RenderChunkValidationError(
       CHUNK_INDEX_OUT_OF_RANGE,
-      `[renderChunk] chunk ${chunkIndex} has non-positive frame count: ${framesInChunk}`
+      `[renderChunk] chunk ${chunkIndex} has non-positive frame count: ${sliceFrames}`
     );
   }
+  const range = resolveChunkFrameRange(slice, chunkIndex, options?.frameRange);
+  const framesInChunk = range.endFrame - range.startFrame;
   const compiledDir = join42(planDir, "compiled");
   if (!existsSync28(compiledDir)) {
     throw new RenderChunkValidationError(
@@ -18735,10 +18768,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const deferredVideoFrames = planVideos ? await extractDeferredVideoFramesForChunk({
       planDir,
       planVideos,
-      frames: Array.from(
-        { length: slice.endFrame - slice.startFrame },
-        (_, i) => slice.startFrame + i
-      ),
+      frames: Array.from({ length: framesInChunk }, (_, i) => range.startFrame + i),
       fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
       outputRoot: videoFramesDir,
       cfg,
@@ -18894,7 +18924,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
             abortSignal: void 0,
             assertNotAborted: () => {
             },
-            frameRange: { startFrame: slice.startFrame, endFrame: slice.endFrame }
+            frameRange: range
           });
           const observedModes = new Set(capturePerfs.map((perf) => perf.captureMode));
           if (observedModes.size !== 1 || ![...observedModes].every(isCaptureMode)) {
@@ -18988,12 +19018,13 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       });
       if (encoder.chunksCarryAudio) {
         const audioScratchPath = `${outputChunkPath}.audio.m4a`;
+        const audioChunks = options?.frameRange ? chunksWithSubRange(chunks, chunkIndex, range) : { chunks, index: chunkIndex };
         await muxChunkWithAudio({
           videoPath: videoOnlyPath,
           audioPath: chunkAudioSource(planDir, chunkIndex, audioScratchPath),
           outputPath: outputChunkPath,
-          chunks,
-          chunkIndex,
+          chunks: audioChunks.chunks,
+          chunkIndex: audioChunks.index,
           fps: { num: plan2.dimensions.fpsNum, den: plan2.dimensions.fpsDen },
           timeoutMs: cfg.ffmpegProcessTimeout
         });
@@ -19022,8 +19053,8 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
     const perfPayload = {
       planHash: plan2.planHash,
       chunkIndex,
-      startFrame: slice.startFrame,
-      endFrame: slice.endFrame,
+      startFrame: range.startFrame,
+      endFrame: range.endFrame,
       framesEncoded,
       durationMs,
       planHashMs,
@@ -19052,6 +19083,7 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
       outputPath: outputChunkPath,
       outputKind,
       framesEncoded,
+      frameRange: range,
       sha256,
       durationMs,
       planHashMs,
@@ -19068,12 +19100,12 @@ async function renderChunk(planDir, chunkIndex, outputChunkPath) {
 }
 
 // src/services/distributed/planV2Execution.ts
-async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath) {
+async function renderChunkV2(planV2Dir, chunkIndex, outputChunkPath, options) {
   const workRoot = mkdtempSync9(join43(tmpdir5(), "hf-plan-v2-chunk-"));
   const materializedPlanDir = join43(workRoot, "plan");
   try {
     materializePlanV2Target(planV2Dir, { role: "chunk", chunkIndex }, materializedPlanDir);
-    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath);
+    return await renderChunk(materializedPlanDir, chunkIndex, outputChunkPath, options);
   } finally {
     rmSync17(workRoot, { recursive: true, force: true });
   }

package/dist/public-server.js

@@ -13845,7 +13845,8 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
       accepts: Object.freeze([PLAN_PROTOCOL_V1, PLAN_PROTOCOL_V2]),
       acceptsLegacyV1WithoutDescriptor: true
     })
-  })
+  }),
+  chunkFrameRange: true
 });
 
 // src/services/render/stages/planHash.ts

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

@@ -31,6 +31,7 @@ export interface AssembleResult {
     framesEncoded: number;
     fileSize: number;
 }
+export type AssembleChunkPaths = readonly (string | readonly string[])[];
 type CfrRateControlSource = Partial<Pick<LockedRenderConfig, "quality" | "crf" | "bitrate">>;
 export declare function cfrRateControlArgs(locked: CfrRateControlSource): string[];
 /**
@@ -39,7 +40,8 @@ export declare function cfrRateControlArgs(locked: CfrRateControlSource): string
  * @param planDir — absolute path to the planDir produced by `plan()`.
  * @param chunkPaths — ordered chunk outputs, length === `chunks.json` length.
  *   For mp4/mov each entry is a path to an encoded chunk file; for
- *   png-sequence each entry is a path to a directory of frames.
+ *   png-sequence each entry is a path to a directory of frames. An entry
+ *   may instead be the ordered parts of that chunk (see {@link AssembleChunkPaths}).
  * @param audioPath — `<planDir>/<MIXED_AUDIO_FILENAME>` for mux'd formats. Pass `null`
  *   when the composition has no audio (or `assemble` is being called for a
  *   format whose audio is muxed elsewhere). `assemble` always normalizes
@@ -48,7 +50,7 @@ export declare function cfrRateControlArgs(locked: CfrRateControlSource): string
  * @param outputPath — final on-disk output (file for mp4/mov; directory
  *   for png-sequence — created if missing).
  */
-export declare function assemble(planDir: string, chunkPaths: readonly string[], audioPath: string | null, outputPath: string, options?: {
+export declare function assemble(planDir: string, chunkOutputs: AssembleChunkPaths, audioPath: string | null, outputPath: string, options?: {
     logger?: ProducerLogger;
     abortSignal?: AbortSignal;
     /**

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

@@ -15,6 +15,14 @@ interface AudioCut {
     packetCount: number;
 }
 export declare function audioCutForChunk(grid: AacPacketGrid, chunks: readonly ChunkSliceJson[], index: number, fps: Fps): AudioCut | null;
+/** Chunk `index` split around `range`, so `audioCutForChunk` treats `range` as a chunk. */
+export declare function chunksWithSubRange(chunks: readonly ChunkSliceJson[], index: number, range: {
+    startFrame: number;
+    endFrame: number;
+}): {
+    chunks: ChunkSliceJson[];
+    index: number;
+};
 export declare function chunkAudioSlicePath(index: number): string;
 /** Which chunks need a sliced-audio file: `"all"`, one index, or `null` if it is not one. */
 export declare function chunkAudioSliceTarget(path: string): "all" | number | null;

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

@@ -7,9 +7,10 @@ export declare const FFMPEG_VERSION_MISMATCH = "FFMPEG_VERSION_MISMATCH";
 export declare const PLAN_HASH_MISMATCH = "PLAN_HASH_MISMATCH";
 export declare const MISSING_PLAN_ARTIFACT = "MISSING_PLAN_ARTIFACT";
 export declare const CHUNK_INDEX_OUT_OF_RANGE = "CHUNK_INDEX_OUT_OF_RANGE";
+export declare const CHUNK_FRAME_RANGE_INVALID = "CHUNK_FRAME_RANGE_INVALID";
 export declare const MISSING_RUNTIME_ENV_SNAPSHOT = "MISSING_RUNTIME_ENV_SNAPSHOT";
 export { INVALID_VIDEO_METADATA };
-export type RenderChunkValidationCode = typeof FFMPEG_VERSION_MISMATCH | typeof PLAN_HASH_MISMATCH | typeof MISSING_PLAN_ARTIFACT | typeof CHUNK_INDEX_OUT_OF_RANGE | typeof MISSING_RUNTIME_ENV_SNAPSHOT | typeof INVALID_VIDEO_METADATA | typeof BROWSER_GPU_NOT_SOFTWARE;
+export type RenderChunkValidationCode = typeof FFMPEG_VERSION_MISMATCH | typeof PLAN_HASH_MISMATCH | typeof MISSING_PLAN_ARTIFACT | typeof CHUNK_INDEX_OUT_OF_RANGE | typeof CHUNK_FRAME_RANGE_INVALID | typeof MISSING_RUNTIME_ENV_SNAPSHOT | typeof INVALID_VIDEO_METADATA | typeof BROWSER_GPU_NOT_SOFTWARE;
 /** A malformed planDir or a worker that does not match the plan's fingerprint; adapters key retries off `code`. */
 export declare class RenderChunkValidationError extends Error {
     readonly code: RenderChunkValidationCode;

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

@@ -53,6 +53,7 @@ export interface DistributedRenderCapabilities {
         chunk: Readonly<PlanProtocolConsumerCapabilities>;
         assembler: Readonly<PlanProtocolConsumerCapabilities>;
     }>;
+    readonly chunkFrameRange?: boolean;
 }
 /** Serializable capability payload for fleet rollout and worker handshakes. */
 export declare const DISTRIBUTED_RENDER_CAPABILITIES: Readonly<DistributedRenderCapabilities>;

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

@@ -1,12 +1,12 @@
-import { assemble, type AssembleResult } from "./assemble.js";
-import { type EffectiveChunkResult } from "./renderChunk.js";
+import { assemble, type AssembleChunkPaths, type AssembleResult } from "./assemble.js";
+import { type EffectiveChunkResult, type RenderChunkOptions } from "./renderChunk.js";
 /**
  * Direct v2 chunk-role entry point. Storage adapters may instead download the
  * selected blobs themselves and call `materializePlanV2Target` + `renderChunk`.
  */
-export declare function renderChunkV2(planV2Dir: string, chunkIndex: number, outputChunkPath: string): Promise<EffectiveChunkResult>;
+export declare function renderChunkV2(planV2Dir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions): Promise<EffectiveChunkResult>;
 /**
  * Direct v2 assembler-role entry point. Audio is resolved exclusively from
  * the assembler dependency set and never materialized by chunk workers.
  */
-export declare function assembleV2(planV2Dir: string, chunkPaths: readonly string[], outputPath: string, options?: Parameters<typeof assemble>[4]): Promise<AssembleResult>;
+export declare function assembleV2(planV2Dir: string, chunkPaths: AssembleChunkPaths, outputPath: string, options?: Parameters<typeof assemble>[4]): Promise<AssembleResult>;

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

@@ -34,9 +34,9 @@
  * 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 { type LockedRenderConfig } from "../render/stages/freezePlan.js";
+import { type ChunkSliceJson, type LockedRenderConfig } from "../render/stages/freezePlan.js";
 import { type PlanVideosJson } from "./shared.js";
-export { 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";
+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";
 /** Validate the shared video contract before any v1 chunk can inject frames. */
 export declare function validatePlanVideosForChunk(value: unknown): PlanVideosJson;
 /**
@@ -51,6 +51,7 @@ export interface ChunkResult {
     /** `"file"` for mp4/mov; `"frame-dir"` for png-sequence. */
     outputKind: "file" | "frame-dir";
     framesEncoded: number;
+    frameRange?: ChunkFrameRange;
     sha256: string;
     durationMs: number;
     /**
@@ -92,7 +93,26 @@ export interface ChunkResult {
 /** Result returned by the built-in renderer, which always observes its mode. */
 export interface EffectiveChunkResult extends ChunkResult {
     captureMode: CaptureMode;
+    frameRange: ChunkFrameRange;
 }
+/** Absolute composition frame indices, end exclusive, like a chunk's slice. */
+export interface ChunkFrameRange {
+    startFrame: number;
+    endFrame: number;
+}
+export interface RenderChunkOptions {
+    /**
+     * Render only these frames of the chunk, e.g. to retry a slow chunk as
+     * parts rendered in parallel. Must be a non-empty range inside the chunk's
+     * slice. Each part is a self-contained output (its own IDR keyframe, frame
+     * names from zero, the audio packets it owns); pass the parts of a chunk,
+     * in order, as one `chunkPaths` entry to `assemble`. Omitted renders the
+     * whole slice.
+     */
+    frameRange?: ChunkFrameRange;
+}
+/** The frames a chunk renders: its slice, or a validated sub-range of it. */
+export declare function resolveChunkFrameRange(slice: ChunkSliceJson, chunkIndex: number, frameRange: ChunkFrameRange | undefined): ChunkFrameRange;
 /** Compatibility-safe adapter seam for built-in or injected chunk renderers. */
 export type ChunkRenderer = (planDir: string, chunkIndex: number, outputChunkPath: string) => Promise<ChunkResult>;
 interface DistributedCaptureSessionDependencies {
@@ -159,4 +179,4 @@ export declare function resolveLockedVp9CpuUsed(lockedEncoder: Pick<LockedRender
  * outputs — the caller picks the right shape based on `meta/encoder.json`.
  * `renderChunk` enforces the same choice via `outputKind` on the result.
  */
-export declare function renderChunk(planDir: string, chunkIndex: number, outputChunkPath: string): Promise<EffectiveChunkResult>;
+export declare function renderChunk(planDir: string, chunkIndex: number, outputChunkPath: string, options?: RenderChunkOptions): Promise<EffectiveChunkResult>;

package/package.json

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