@hyperframes/producer 0.8.175 → 0.8.176

package/dist/public-server.js

@@ -13763,13 +13763,42 @@ import { DISTRIBUTED_FPS, isDistributedFps } from "@hyperframes/core";
 // src/services/distributed/plan.ts
 import { audioFailureDiagnostics as audioFailureDiagnostics3 } from "@hyperframes/engine";
 import { extname as extname4, isAbsolute as isAbsolute4, join as join29, relative as relative4, sep as sep3 } from "node:path";
-import { fpsToNumber as fpsToNumber10 } from "@hyperframes/core";
+import {
+  fpsToNumber as fpsToNumber10,
+  HF_COLOR_GRADING_ATTR as HF_COLOR_GRADING_ATTR2
+} from "@hyperframes/core";
 import {
   getEncoderPreset as getEncoderPreset4,
   normalizeVp9CpuUsed,
   resolveConfig as resolveConfig3
 } from "@hyperframes/engine";
 
+// src/services/distributed/planFrameCost.ts
+import {
+  closeCaptureSession as closeCaptureSession9,
+  createCaptureSession as createCaptureSession8,
+  createFrameLookupTable as createFrameLookupTable3,
+  initializeSession as initializeSession8
+} from "@hyperframes/engine";
+
+// src/services/distributed/chunkFrames.ts
+import {
+  compositionRequiresWebGpu as compositionRequiresWebGpu3,
+  createFrameLookupTable as createFrameLookupTable2,
+  createVideoFrameInjector as createVideoFrameInjector2,
+  extractVideoFramesRange
+} from "@hyperframes/engine";
+
+// src/services/distributed/shared.ts
+import { execFile as execFileCallback } from "node:child_process";
+import { promisify as promisify2 } from "node:util";
+import {
+  getFfmpegBinary,
+  MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME3
+} from "@hyperframes/engine";
+var PLAN_AUDIO_RELATIVE_PATH = MIXED_AUDIO_FILENAME3;
+var execFile = promisify2(execFileCallback);
+
 // src/services/distributed/planProtocol.ts
 var PLAN_SCHEMA_VERSION = 1;
 var PLAN_ARTIFACT_LAYOUT = "plan-dir-v1";
@@ -13806,16 +13835,6 @@ var DISTRIBUTED_RENDER_CAPABILITIES = Object.freeze({
 // src/services/render/stages/planHash.ts
 var FIELD_DELIMITER = Buffer.from([0]);
 
-// src/services/distributed/shared.ts
-import { execFile as execFileCallback } from "node:child_process";
-import { promisify as promisify2 } from "node:util";
-import {
-  getFfmpegBinary,
-  MIXED_AUDIO_FILENAME as MIXED_AUDIO_FILENAME3
-} from "@hyperframes/engine";
-var PLAN_AUDIO_RELATIVE_PATH = MIXED_AUDIO_FILENAME3;
-var execFile = promisify2(execFileCallback);
-
 // src/services/distributed/planSize.ts
 var PLAN_ROOT_CATEGORY = {
   compiled: "compiled",

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

@@ -0,0 +1,48 @@
+import { type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type EngineConfig, type ExtractedFrames, type FrameLookupTable } from "@hyperframes/engine";
+import type { LockedRenderConfig } from "../render/stages/freezePlan.js";
+import { type DistributedFormat, INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
+/** Distinct codes so adapters route retries per cause: a missing artifact may heal, a hash mismatch never. */
+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 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;
+/** 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;
+    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 | null): () => 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.
+ */
+export declare function rebuildExtractedFramesFromPlanDir(planDir: string, videos: PlanVideosJson["extracted"], indexMode?: "dense-v1" | "sparse-v2"): ExtractedFrames[];
+/** Capture options a chunk session uses; the planner measures frame cost with the same ones. */
+export declare function buildChunkCaptureOptions(input: {
+    dimensions: {
+        width: number;
+        height: number;
+        fpsNum: number;
+        fpsDen: number;
+        format: DistributedFormat;
+    };
+    encoder: Pick<LockedRenderConfig, "quality" | "deviceScaleFactor" | "variables">;
+    videoCount: number;
+    html: string;
+}): CaptureOptions;
+/** Extracts the given frames of deferred videos under the names a full extraction gives them. */
+export declare function extractDeferredVideoFramesForChunk(input: {
+    planDir: string;
+    planVideos: PlanVideosJson;
+    frames: Iterable<number>;
+    fps: {
+        num: number;
+        den: number;
+    };
+    outputRoot: string;
+    cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
+}): Promise<ExtractedFrames[]>;

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

@@ -261,7 +261,11 @@ export declare const MIN_CHUNK_SIZE = 10;
 /** 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. */
-export declare function estimateChunkSeconds(frames: number, megapixels: number): number;
+export declare function estimateChunkSeconds(frames: number, megapixels: number, measuredSecondsPerFrame?: number): number;
+/** Graded media runs a full-frame shader per frame, which the per-pixel estimate cannot see. */
+export declare function planNeedsFrameCostMeasurement(html: string): boolean;
+/** Whether {@link resolveMaxParallelChunks} sizes chunks from what a frame costs. */
+export declare function chunkSizingUsesFrameCost(config: Pick<DistributedRenderConfig, "maxParallelChunks" | "chunkSize" | "targetChunkFrames" | "workerTimeoutSeconds" | "workerConcurrency">): boolean;
 /** Non-retryable: even {@link MAX_PARALLEL_CHUNKS_CEILING} chunks cannot fit the worker time limit. */
 export declare const CHUNK_EXCEEDS_WORKER_TIMEOUT = "CHUNK_EXCEEDS_WORKER_TIMEOUT";
 export declare class ChunkExceedsWorkerTimeoutError extends Error {
@@ -274,7 +278,9 @@ export declare class ChunkExceedsWorkerTimeoutError extends Error {
  */
 export declare function resolveMaxParallelChunks(config: Pick<DistributedRenderConfig, "maxParallelChunks" | "chunkSize" | "targetChunkFrames" | "workerTimeoutSeconds" | "workerConcurrency">, totalFrames: number, 
 /** Output pixels per frame, after supersampling. */
-megapixels: number, log?: ProducerLogger): number;
+megapixels: number, log?: ProducerLogger, 
+/** Measured capture seconds per frame; frames are priced at it when it beats the estimate. */
+measuredSecondsPerFrame?: number): number;
 /**
  * Default hard ceiling on `<planDir>/` size in bytes. 2 GB fits inside
  * AWS Lambda's 10 GB `/tmp` alongside the chunk worker's captured frames

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

@@ -0,0 +1,24 @@
+import { type EngineConfig } from "@hyperframes/engine";
+import type { ProducerLogger } from "../../logger.js";
+import type { DistributedFormat, PlanVideosJson } from "./shared.js";
+/**
+ * Captures the renderer's calibration frames in a session set up like a chunk
+ * worker's (same capture options, engine config and video frames) and returns
+ * the p95 capture seconds per frame.
+ */
+export declare function measurePlanSecondsPerFrame(input: {
+    planDir: string;
+    workDir: string;
+    html: string;
+    planVideos: PlanVideosJson;
+    totalFrames: number;
+    fps: number;
+    width: number;
+    height: number;
+    format: DistributedFormat;
+    quality: "draft" | "standard" | "high";
+    deviceScaleFactor: number;
+    variables?: Record<string, unknown>;
+    cfg: EngineConfig;
+    log: ProducerLogger;
+}): Promise<number>;

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

@@ -33,35 +33,10 @@
  * Every determinism toggle above is opt-in — only this primitive enables them.
  * In-process renders (`executeRenderJob`) leave them off.
  */
-import { assertSwiftShader, type BeforeCaptureHook, BROWSER_GPU_NOT_SOFTWARE, type CaptureOptions, type CaptureMode, type CaptureSession, closeCaptureSession, createCaptureSession, type EngineConfig, type ExtractedFrames, type FrameLookupTable, initializeSession, probeBeginFrameLiveness, readWebGlVendorInfoFromCanvas } from "@hyperframes/engine";
-import { type ChunkSliceJson, type LockedRenderConfig } from "../render/stages/freezePlan.js";
-import { INVALID_VIDEO_METADATA, type PlanVideosJson } from "./shared.js";
-/**
- * Non-retryable error codes raised when the planDir is structurally
- * malformed, semantically out of range, or fingerprints differently from
- * what the controller wrote. Each is distinct so adapter retry policies
- * can route them independently — e.g. `MISSING_PLAN_ARTIFACT` may point
- * to a partial S3 download that a retry could heal, while
- * `PLAN_HASH_MISMATCH` strictly indicates cross-version drift that
- * retries won't fix.
- */
-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 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;
-/**
- * Typed non-retryable error raised by `renderChunk` when the planDir is
- * malformed or the worker's runtime doesn't match the planDir's
- * controller-side fingerprint. Workflow adapters key retry policies off
- * `code` — most of these failures will not heal on retry.
- */
-export declare class RenderChunkValidationError extends Error {
-    readonly code: RenderChunkValidationCode;
-    constructor(code: RenderChunkValidationCode, message: string);
-}
+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 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";
 /** Validate the shared video contract before any v1 chunk can inject frames. */
 export declare function validatePlanVideosForChunk(value: unknown): PlanVideosJson;
 /**
@@ -134,12 +109,6 @@ 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>;
-/**
- * Build the immutable lookup table once, but keep injector state scoped to a
- * browser session. Reusing one hook across workers or a whole-chunk retry can
- * incorrectly suppress injection on a fresh page.
- */
-export declare function createChunkVideoFrameInjectorFactory(frameLookup: FrameLookupTable | null): () => BeforeCaptureHook | null;
 /**
  * Only BeginFrame-specific failures are safe to retry in screenshot mode.
  * Cancellation, memory exhaustion, and unrelated authoring/IO failures must
@@ -161,40 +130,6 @@ export declare function runCaptureWithScreenshotFallback<T>(input: {
  * and frame zero. `true` means the entire chunk should use screenshot mode.
  */
 export declare function beginFrameSessionNeedsScreenshotFallback(session: Pick<CaptureSession, "page" | "launchCaptureMode" | "beginFrameTimeTicks" | "beginFrameIntervalMs">, probe?: typeof probeBeginFrameLiveness): Promise<boolean>;
-/**
- * Rebuild the engine's in-memory `ExtractedFrames[]` from the on-disk
- * planDir layout. `<planDir>/video-frames/<videoId>/` holds the numbered
- * frame files plan() extracted; this lists each dir and rebuilds the
- * 0-based `framePaths` Map that `FrameLookupTable` / `videoFrameInjector`
- * both index against — the consumer is
- * `videoFrameExtractor.ts:getFrameAtTime`, which floors `localTime * fps`
- * to a 0-based index and reads `framePaths.get(frameIndex)`. Any drift
- * from that key convention silently drops every `<video>`'s first-paint
- * frame; see HF#1731 / HF#1730.
- *
- * Exported so a unit test can pin the 0-based contract without spinning
- * up the heavyweight Docker fixture — the bug surfaces only under
- * distributed mode and only at video first-paint, so this primitive is
- * the right granularity to guard.
- */
-export declare function rebuildExtractedFramesFromPlanDir(planDir: string, videos: PlanVideosJson["extracted"], indexMode?: "dense-v1" | "sparse-v2"): ExtractedFrames[];
-/**
- * Extract the frames this chunk shows from videos the planner left
- * unextracted. Frames land in `outputRoot/<videoId>/` under the names a full
- * extraction gives them, so the lookup indexes them exactly as it would
- * frames the planner wrote.
- */
-export declare function extractDeferredVideoFramesForChunk(input: {
-    planDir: string;
-    planVideos: PlanVideosJson;
-    slice: ChunkSliceJson;
-    fps: {
-        num: number;
-        den: number;
-    };
-    outputRoot: string;
-    cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
-}): Promise<ExtractedFrames[]>;
 /**
  * Re-export the runtime-env apply helper so adapters that import only
  * this subpath can prime `process.env` before instantiating their own

package/package.json

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