@hyperframes/producer 0.9.16 → 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/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/package.json

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