@hyperframes/producer 0.8.197 → 0.8.199

package/dist/renderRequest.d.ts

@@ -26,6 +26,7 @@ export interface RenderRequestOptions {
     gifLoop?: number;
     hlsSegmentSeconds?: number;
     workers?: number;
+    maxRenderMs?: number;
     useGpu?: boolean;
     debug?: boolean;
     /** Segmented capture: reuse segments recorded in a matching manifest. */

package/dist/server.d.ts

@@ -44,6 +44,7 @@ interface RenderInput {
     pageMotionBlur?: RenderConfig["pageMotionBlur"];
     outputDynamicRange?: "auto" | "hdr" | "sdr";
     workers?: number;
+    maxRenderMs?: number;
     crf?: number;
     videoBitrate?: string;
     useGpu: boolean;

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

@@ -0,0 +1,16 @@
+import type { ChunkSliceJson } from "../render/stages/freezePlan.js";
+import type { PlanVideosJson } from "./shared.js";
+/** Estimated capture cost of every frame: page base plus each active video's pixels. */
+export declare function planFrameWeights(input: {
+    videos: PlanVideosJson["videos"];
+    extracted: PlanVideosJson["extracted"];
+    totalFrames: number;
+    fps: number;
+    width: number;
+    height: number;
+}): Float64Array;
+/**
+ * Cut `[0, weights.length)` into `chunkCount` ranges of ~equal summed weight, each within
+ * `[minFrames, maxFrames]` where the frame count allows. `null` when the cost is uniform.
+ */
+export declare function buildWeightedChunkSlices(weights: Float64Array, chunkCount: number, minFrames: number, maxFrames: number): ChunkSliceJson[] | null;

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

@@ -271,6 +271,8 @@ export declare const DEFAULT_MAX_PARALLEL_CHUNKS = 16;
  * outweighs the parallelism gain on tiny renders.
  */
 export declare const MIN_CHUNK_SIZE = 10;
+/** Largest `chunkSize`; `validateDistributedRenderConfig` enforces it, and cost-weighted chunks stay under it. */
+export declare const MAX_CHUNK_SIZE = 3600;
 /** Most chunks one render may plan; `validateDistributedRenderConfig` enforces it on `maxParallelChunks`. */
 export declare const MAX_PARALLEL_CHUNKS_CEILING = 256;
 /** Predicted seconds for one chunk of `frames` frames at `megapixels` output pixels per frame. */
@@ -402,6 +404,11 @@ export declare function resolveChunkPlan(totalFrames: number, configChunkSize: n
  * upper bound — chunk workers iterate `i in [startFrame, endFrame)`.
  */
 export declare function buildChunkSlices(totalFrames: number, chunkCount: number, effectiveChunkSize: number): ChunkSliceJson[];
+/**
+ * The plan's chunk cut: auto-sized plans re-cut the same chunk count by estimated capture cost;
+ * explicit `chunkSize` or uniform cost keeps {@link buildChunkSlices}; `targetChunkFrames` and the time limit cap it.
+ */
+export declare function buildPlanChunkSlices(frameWeights: Float64Array, config: Pick<DistributedRenderConfig, "chunkSize" | "targetChunkFrames">, chunkCount: number, effectiveChunkSize: number, maxFramesPerChunk?: number): ChunkSliceJson[];
 /** Test-visible construction of the engine config used by distributed planning. */
 export declare function resolveDistributedEngineConfig(config: DistributedRenderConfig): EngineConfig;
 /**

package/dist/services/hdrCompositor.d.ts

@@ -10,6 +10,7 @@
  * `captureHdrHybridLoop.ts`, `captureHdrFrameShared.ts`,
  * `captureHdrResources.ts`.
  */
+import type { HdrFrameWindows } from "./hdrFrameWindows.js";
 import { type CaptureSession, type BeforeCaptureHook, type HdrTransfer, type ElementStackingInfo, type HfTransitionMeta } from "@hyperframes/engine";
 import type { ProducerLogger } from "../logger.js";
 import { type HdrImageTransferCache } from "./hdrImageTransferCache.js";
@@ -34,21 +35,20 @@ export interface TransitionRange extends HdrTransitionMeta {
  */
 export interface HdrVideoFrameSource {
     dir: string;
-    rawPath: string;
-    fd: number;
+    windows: HdrFrameWindows;
     width: number;
     height: number;
     frameSize: number;
-    frameCount: number;
+    readonly frameCount: number;
     scratch: Buffer;
-    /** The raw file contains one playable source cycle and must wrap at EOF. */
+    /** The playable range is one source cycle and must wrap at its end. */
     loop?: boolean;
     mediaStart?: number;
     videoStreamLeadSeconds?: number;
 }
 export declare function closeHdrVideoFrameSource(source: HdrVideoFrameSource, log?: ProducerLogger): void;
 export declare function resolveHdrVideoFrameIndex(time: number, startTime: number, fps: number, frameCount: number, loop?: boolean): number | null;
-export declare function blitHdrVideoLayer(canvas: Buffer, el: ElementStackingInfo, time: number, fps: number, hdrVideoFrameSources: Map<string, HdrVideoFrameSource>, hdrStartTimes: Map<string, number>, width: number, height: number, log?: ProducerLogger, sourceTransfer?: HdrTransfer, targetTransfer?: HdrTransfer, hdrPerf?: HdrPerfCollector): void;
+export declare function blitHdrVideoLayer(canvas: Buffer, el: ElementStackingInfo, time: number, fps: number, hdrVideoFrameSources: Map<string, HdrVideoFrameSource>, hdrStartTimes: Map<string, number>, width: number, height: number, log?: ProducerLogger, sourceTransfer?: HdrTransfer, targetTransfer?: HdrTransfer, hdrPerf?: HdrPerfCollector): Promise<void>;
 /**
  * Pre-decoded HDR image buffer with its native pixel dimensions.
  *

package/dist/services/hdrFrameWindows.d.ts

@@ -0,0 +1,23 @@
+export interface HdrFrameLease {
+    fd: number;
+    offset: number;
+    release(): void;
+}
+export interface HdrWindowSpec {
+    firstFrame: number;
+    frames: number;
+    path: string;
+}
+export interface HdrFrameWindows {
+    readonly totalFrames: number;
+    lease(frameIndex: number): Promise<HdrFrameLease | null>;
+    close(): void;
+}
+export declare function createHdrFrameWindows(opts: {
+    dir: string;
+    frameSize: number;
+    totalFrames: number;
+    windowFrames: number;
+    maxResident: number;
+    extract: (spec: HdrWindowSpec) => Promise<number>;
+}): HdrFrameWindows;

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

@@ -0,0 +1,35 @@
+interface RenderEtaInput {
+    /** Absent or 0 means no guard. */
+    maxRenderMs?: number;
+    /** Wall time since the render started, so time already spent counts. */
+    elapsedMs: number;
+    framesCompleted: number;
+    totalFrames: number;
+    /** Wall ms per frame across all workers. */
+    msPerFrame: number;
+}
+export declare class RenderTooSlowError extends Error {
+    readonly code: "RENDER_TOO_SLOW";
+    readonly owner: "user";
+    readonly retryable: false;
+    readonly publicMetadata: Readonly<Record<string, unknown>>;
+    constructor(stage: string, input: Required<RenderEtaInput> & {
+        etaMs: number;
+    });
+}
+/** The one ETA decision, shared by the post-calibration and the measured-rate checks. */
+export declare function checkRenderEta(stage: string, input: RenderEtaInput): RenderTooSlowError | undefined;
+interface RenderEtaGuardOptions {
+    maxRenderMs?: number;
+    job: {
+        framesRendered?: number;
+    };
+    totalFrames: number;
+    pipelineStartMs: number;
+    onTooSlow: (error: RenderTooSlowError) => void;
+    now?: () => number;
+    pollMs?: number;
+}
+/** Polls `job.framesRendered`, which every capture path updates, and trips once. Returns stop(). */
+export declare function startRenderEtaGuard(options: RenderEtaGuardOptions): () => void;
+export {};

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

@@ -58,19 +58,6 @@ export declare function probeHdrExtractionDims(args: {
     composition: CompositionMetadata;
     prep: HdrResourcePrep;
 }): Promise<void>;
-/**
- * Total bytes the raw rgb48le pre-extraction below will write: 6 bytes/px ×
- * frame area × frame count, summed across HDR videos. Exposed for the
- * disk-headroom gate — a plain iPhone HLG clip auto-detected as HDR filled a
- * near-full disk with 16-bit raw frames before the user found --sdr (wild
- * report, CLI 0.7.52), so the commitment must be checked and surfaced BEFORE
- * FFmpeg starts writing.
- */
-export declare function estimateHdrExtractionBytes(videos: Array<{
-    durationSeconds: number;
-    width: number;
-    height: number;
-}>, fps: number): number;
 export declare function resolveHdrExtractionBudgetBytes(raw: string | undefined, cgroupLimitMb?: number | null): number | undefined;
 export declare function resolveHdrExtractionActiveBudgetBytes(configuredBudgetBytes: number | undefined, freeBytes: number): number;
 export declare function reserveHdrExtractionBytes(estimatedBytes: number, budgetBytes: number | undefined): () => void;
@@ -91,10 +78,9 @@ export interface HdrVideoExtractionResult {
     releaseReservation: () => void;
 }
 /**
- * Extract each HDR video into a raw rgb48le frame file via a single FFmpeg
- * pass per video, and open a file descriptor for each. The caller owns both
- * source teardown and the aggregate scratch reservation, which intentionally
- * remains held until the capture-stage finally block.
+ * Plan each HDR video's frame windows; a source extracts a window with one FFmpeg pass when the
+ * capture first reaches it. The caller owns teardown and the scratch reservation (resident
+ * windows only), held until the capture-stage finally block.
  */
 export declare function extractHdrVideoFrames(args: {
     job: RenderJob;
@@ -106,6 +92,8 @@ export declare function extractHdrVideoFrames(args: {
     height: number;
     abortSignal: AbortSignal | undefined;
     hdrDiagnostics: HdrDiagnostics;
+    maxResidentWindows?: number;
+    windowBytes?: number;
     runFfmpegImpl?: typeof runFfmpeg;
     extractMediaMetadataImpl?: typeof extractMediaMetadata;
     resolveFinalFrameExtractionWindowImpl?: typeof resolveFinalFrameExtractionWindow;

package/dist/services/renderOrchestrator.d.ts

@@ -96,6 +96,8 @@ export interface RenderConfig {
     motionBlur?: MotionBlurOptions;
     pageMotionBlur?: "off";
     workers?: number;
+    /** Wall-time budget in ms for the whole render. Absent or 0 disables the ETA guard. */
+    maxRenderMs?: number;
     useGpu?: boolean;
     debug?: boolean;
     /** Strict rejects correctness warnings; best-effort returns a qualified outcome. */
@@ -822,19 +824,17 @@ export declare function resolveDeShortBand(args: {
     elementCountSource: "live" | "static";
 }): "applied" | "skipped_elements" | "unmeasured" | undefined;
 /**
- * DE priority inversion predicate: should an AUTO-resolved multi-worker render
- * drop to single-worker verified drawElement streaming?
+ * DE priority inversion predicate: should a multi-worker render drop to
+ * single-worker verified drawElement streaming?
  *
  * Benchmarked 2026-07-08: above ~900 frames DE-single beats screenshot-parallel
  * at every worker count (2,380f: 66s vs 109–127s at W2–W5); below it DE's fixed
  * init cost (verify + dedup arming) loses by a small margin. Only fires for the
  * exact benchmarked configuration: default-on DE, mp4, streaming-eligible,
- * no compile gate, no forced screenshot, workers not explicitly requested.
+ * no compile gate, no forced screenshot.
  */
 export declare function shouldPreferSingleWorkerDrawElement(args: {
     workerCount: number;
-    /** job.config.workers — a number means the user explicitly chose. */
-    requestedWorkers: number | "auto" | undefined;
     useDrawElement: boolean;
     deCompileGate: string | undefined;
     forceScreenshot: boolean;

package/package.json

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