@hyperframes/producer 0.9.15 → 0.9.17

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

@@ -38,8 +38,7 @@ export declare function buildChunkCaptureOptions(input: {
     skipReadinessVideoIds?: string[];
     videoMetadataHints?: CaptureOptions["videoMetadataHints"];
 }): CaptureOptions;
-/** Extracts the given frames of deferred videos under the names a full extraction gives them. */
-export declare function shownDeferredFrameIndexes(planVideos: PlanVideosJson, frames: Iterable<number>, fps: {
+export declare function shownPlanFrameIndexes(planVideos: PlanVideosJson, frames: Iterable<number>, fps: {
     num: number;
     den: number;
 }): Map<string, Set<number>>;

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

@@ -0,0 +1,42 @@
+import { type EngineConfig, type ExtractedFrames, type ShownBox, type VideoElement } from "@hyperframes/engine";
+/** The frame indexes each deferred video shows across `frames`, by video id. */
+export declare function shownDeferredFrameIndexes(source: {
+    videos: VideoElement[];
+    extracted: ExtractedFrames[];
+}, frames: Iterable<number>, fps: {
+    num: number;
+    den: number;
+}): Map<string, Set<number>>;
+/** Extracts the given frames of deferred videos under the names a full extraction gives them. */
+export declare function extractDeferredFrames(input: {
+    videos: VideoElement[];
+    extracted: ExtractedFrames[];
+    frames: Iterable<number>;
+    fps: {
+        num: number;
+        den: number;
+    };
+    outputRoot: string;
+    cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
+    signal?: AbortSignal;
+    /** Where the video's source is read from: a local path or a URL. May throw. */
+    sourceOf: (video: ExtractedFrames) => string;
+    shownBoxes?: ReadonlyMap<string, ShownBox>;
+    /** The error to throw when the extractor returns no frame for an index the video shows. */
+    onMissingFrame: (video: ExtractedFrames, index: number) => Error;
+}): Promise<ExtractedFrames[]>;
+/**
+ * Fills every deferred video in place with the frames a full extraction writes, into the folder it
+ * already has. For a route that cannot read frames per segment.
+ */
+export declare function extractAllDeferredFrames(extracted: ExtractedFrames[], input: {
+    fps: {
+        num: number;
+        den: number;
+    };
+    cfg: Pick<EngineConfig, "ffmpegProcessTimeout">;
+    signal?: AbortSignal;
+    sourceOf?: (video: ExtractedFrames) => string;
+    maxTransientRetries?: number;
+    onProgress?: (framesDone: number, framesTotal: number) => void;
+}): Promise<void>;

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

@@ -200,6 +200,8 @@ export interface RenderCaptureObservability {
     /** Segmented capture only (Phase 2): current segment and retries so far. */
     segmentIndex?: number;
     segmentRetries?: number;
+    videoFrameWindow?: "on" | "off";
+    videoFrameWindowPeakBytes?: number;
 }
 export interface RenderExtractionObservability {
     videoCount: number;

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

@@ -0,0 +1,41 @@
+import { createVideoFrameInjector, type BeforeCaptureHook, type EngineConfig, type ExtractedFrames, type VideoElement } from "@hyperframes/engine";
+import { extractDeferredFrames } from "./deferredVideoFrames.js";
+import type { SegmentSlice } from "./segmentPlan.js";
+export interface SegmentWorkerFrames {
+    /**
+     * One hook for the worker's whole life, so a recycled session keeps it. Inside a
+     * prepared window it injects from the window; outside one it extracts the frames
+     * it is asked for and removes them again.
+     */
+    hook: BeforeCaptureHook;
+    /** Extracts the frames `segment` shows and points the hook at them. */
+    prepare(segment: SegmentSlice): Promise<void>;
+    /** Deletes the segment's frames. Safe to call again. */
+    release(): void;
+}
+export interface SegmentVideoFrames {
+    forWorker(): SegmentWorkerFrames;
+    /** Extracts the given output frames into `segment-frames/<name>/` ahead of time; `release()` is idempotent. */
+    forFrames(frames: readonly number[], name: string): Promise<{
+        injector(): BeforeCaptureHook | null;
+        release(): void;
+    }>;
+}
+type FrameExtractor = typeof extractDeferredFrames;
+/** Each worker reads only the video frames its current segment shows, and deletes them when the segment closes. */
+export declare function createSegmentVideoFrames(input: {
+    videos: VideoElement[];
+    extracted: ExtractedFrames[];
+    fps: {
+        num: number;
+        den: number;
+    };
+    /** The render's work dir; frames go under `segment-frames/segment_NNNNN/`. */
+    rootDir: string;
+    cfg: EngineConfig;
+    injectorOptions: Parameters<typeof createVideoFrameInjector>[1];
+    abortSignal?: AbortSignal;
+    sourceOf?: (video: ExtractedFrames) => string;
+    extractFrames?: FrameExtractor;
+}): SegmentVideoFrames;
+export {};

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

@@ -3,6 +3,7 @@ import type { FileServerHandle } from "../../fileServer.js";
 import type { ProducerLogger } from "../../../logger.js";
 import type { ProgressCallback, RenderJob } from "../../renderOrchestrator.js";
 import type { SdrSegmentedCapturePlan } from "../capturePlan.js";
+import type { SegmentVideoFrames } from "../segmentVideoFrames.js";
 import { type StreamingEncoderOptions } from "./captureStreamingStage.js";
 export interface SegmentedStageDeps {
     spawnEncoder: typeof spawnStreamingEncoder;
@@ -12,9 +13,9 @@ export interface SegmentedStageDeps {
     /** Delete a partial segment so a retry cannot leave a stale file behind. */
     removeFile: (path: string) => void;
 }
-/** Opens a fresh, initialized capture session with the video injector attached. */
+/** Opens a fresh, initialized capture session with the video injector attached; a custom factory may ignore the override. */
 export interface SessionFactory {
-    create: () => Promise<CaptureSession>;
+    create: (injectorOverride?: () => BeforeCaptureHook | null) => Promise<CaptureSession>;
 }
 export interface CaptureSegmentedStageInput {
     fileServer: FileServerHandle;
@@ -32,6 +33,8 @@ export interface CaptureSegmentedStageInput {
     streamingEncoderOptions: StreamingEncoderOptions;
     buildCaptureOptions: () => CaptureOptions;
     createRenderVideoFrameInjector: () => BeforeCaptureHook | null;
+    /** Windowed frames: extracted per segment, deleted when it closes; segment files are deleted once joined. */
+    segmentVideoFrames?: SegmentVideoFrames;
     abortSignal: AbortSignal | undefined;
     assertNotAborted: () => void;
     onProgress?: ProgressCallback;

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

@@ -127,5 +127,12 @@ export type CaptureStreamingStageResult = {
     /** Spawn failed (non-abort) — sequencer should fall back to the disk path. */
     success: false;
 };
+/** At an armed sample index, a frame below the PSNR floor vs its pre-injection screenshot throws. */
+export declare function verifyDrawElementSample(session: CaptureSession, idx: number, buf: Buffer, ctx: {
+    log: CaptureStreamingStageInput["log"];
+    /** Telemetry counters; the stages that report none pass nothing. */
+    stats?: Pick<DeDrainStats, "verifyChecked" | "verifyMinDb">;
+    verifyMinDb: number;
+}): Promise<void>;
 export declare function runCaptureStreamingStage(input: CaptureStreamingStageInput): Promise<CaptureStreamingStageResult>;
 export {};

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

@@ -42,9 +42,7 @@ import type { RenderJob } from "../../renderOrchestrator.js";
 export interface CompileStageInput {
     projectDir: string;
     workDir: string;
-    /** Absolute path to the entry HTML (already resolved to standalone-entry if needed). */
-    htmlPath: string;
-    /** The relative `entryFile` string, used only for log payloads. */
+    /** Entry HTML relative to `projectDir`; a `<template>` sub-composition is isolated inside the index shell. */
     entryFile: string;
     job: RenderJob;
     /**
@@ -104,4 +102,15 @@ export interface CompileStageResult {
      * `3d` | `ancestor_background_image` | `shader_transitions`. Undefined when none fired. */
     deCompileGate?: string;
 }
+/**
+ * The HTML file to compile for `entryFile`. A `<template>`-wrapped
+ * sub-composition has no live root, timeline or duration of its own, so it is
+ * rendered through the project's index.html shell with only its mount host kept.
+ */
+export declare function resolveEntryHtmlPath(input: {
+    projectDir: string;
+    workDir: string;
+    entryFile: string;
+    log: ProducerLogger;
+}): string;
 export declare function runCompileStage(input: CompileStageInput): Promise<CompileStageResult>;

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

@@ -0,0 +1,12 @@
+import type { SegmentVideoFrames } from "./segmentVideoFrames.js";
+/**
+ * Whether source-video frames are read one capture segment at a time. Off unless
+ * `HF_VIDEO_FRAME_WINDOW` reads `true`, and only for a render that segments, because only
+ * the segmented stage knows which frames a segment shows and when it is done with them.
+ */
+export declare function shouldWindowVideoFrames(args: {
+    env: Readonly<Record<string, string | undefined>>;
+    segmented: boolean;
+}): boolean;
+/** Reports the most bytes `segment-frames` has held at once, sampled each time a segment's frames land. */
+export declare function trackSegmentFramePeak(frames: SegmentVideoFrames, rootDir: string, onPeak: (bytes: number) => void): SegmentVideoFrames;

package/dist/services/renderOrchestrator.d.ts

@@ -1,5 +1,5 @@
 import { type CanvasResolution, type Fps, type FpsInput, type HfVfxCapture } from "@hyperframes/core";
-import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ProresProfile, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, explainDrawElementDisabled, type CaptureFailureKind, type MotionBlurOptions } from "@hyperframes/engine";
+import { type EngineConfig, type ExtractionPhaseBreakdown, type VideoFrameFormat, type CaptureOptions, type CaptureVideoMetadataHint, type CaptureSession, type BeforeCaptureHook, type ProresProfile, type ParallelProgress, type WorkerTask, type CapturePerfSummary, type CaptureWarning, type SubTimelineWaitOutcome, type WorkerSizing, type StaticVerificationOutcome, explainDrawElementDisabled, type CaptureFailureKind, displaySize, type MotionBlurOptions } from "@hyperframes/engine";
 import { type ReferenceBackgroundResult } from "@hyperframes/engine";
 import { type ProducerLogger } from "../logger.js";
 import { type RenderOutputFormat } from "./render/renderFormat.js";
@@ -480,10 +480,7 @@ export declare function createRenderFileLogger(logPath: string, base?: ProducerL
 export declare function collectVideoReadinessSkipIds(nativeHdrVideoIds: ReadonlySet<string>, extractedVideos: readonly ExtractedVideoReadinessInput[]): string[];
 interface ExtractedVideoReadinessInput {
     videoId: string;
-    metadata: {
-        width: number;
-        height: number;
-    };
+    metadata: Parameters<typeof displaySize>[0];
 }
 export declare function collectVideoMetadataHints(extractedVideos: readonly ExtractedVideoReadinessInput[]): CaptureVideoMetadataHint[];
 export declare function findMissingFrameRanges(totalFrames: number, framesDir: string, frameExt: "jpg" | "png"): FrameRange[];

package/package.json

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