@hyperframes/engine 0.9.4 → 0.9.6

package/dist/config.d.ts

@@ -74,6 +74,7 @@ export interface EngineConfig {
      * true. Kill switch: `HF_DE_WORKER_ENCODE=false`.
      */
     enableDrawElementWorkerEncode: boolean;
+    useInPageEncode: boolean;
     /**
      * INTERNAL. Set by resolveConfig when it disabled enablePageSideCompositing
      * solely because drawElement was on. Lets the producer's compile-time gates

package/dist/config.js

@@ -32,6 +32,7 @@ export const DEFAULT_CONFIG = {
     videoLayerPassthrough: false,
     useDrawElement: true,
     enableDrawElementWorkerEncode: true,
+    useInPageEncode: false,
     // Auto-detected per host in `resolveConfig`; defaults off for the raw
     // DEFAULT_CONFIG (used directly by tests and worker-sizing fallbacks).
     lowMemoryMode: false,
@@ -76,6 +77,7 @@ const BOOLEAN_ENGINE_CONFIG_FIELDS = [
     "videoLayerPassthrough",
     "useDrawElement",
     "enableDrawElementWorkerEncode",
+    "useInPageEncode",
     "lowMemoryMode",
     "enablePageSideCompositing",
     "enableChunkedEncode",
@@ -517,6 +519,7 @@ export function resolveConfig(overrides) {
         videoLayerPassthrough: envBool("HF_VIDEO_LAYER_PASSTHROUGH", DEFAULT_CONFIG.videoLayerPassthrough),
         useDrawElement: envBool("PRODUCER_EXPERIMENTAL_FAST_CAPTURE", DEFAULT_CONFIG.useDrawElement),
         enableDrawElementWorkerEncode: envBool("HF_DE_WORKER_ENCODE", DEFAULT_CONFIG.enableDrawElementWorkerEncode),
+        useInPageEncode: envBool("HF_INPAGE_ENCODE", DEFAULT_CONFIG.useInPageEncode),
         lowMemoryMode: resolveLowMemoryMode(),
         enablePageSideCompositing: envBool("HF_PAGE_SIDE_COMPOSITING", DEFAULT_CONFIG.enablePageSideCompositing),
         vp9CpuUsed: envVp9CpuUsed(),

package/dist/index.d.ts

@@ -29,6 +29,7 @@
  *   getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
  *
  */
+export { REFERENCE_BACKGROUND_FIELD, referenceBackgroundResult, createReferenceBackgroundRecorder, readReferenceBackground, type ReferenceBackground, type ReferenceBackgroundResult, } from "./services/referenceBackground.js";
 export type { HfProtocol, HfMediaElement, HfTransitionMeta, CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, CaptureWarningCode, SubTimelineWaitMemo, SubTimelineWaitOutcome, } from "./types.js";
 export { resolveConfig, resolvePageNavigationTimeout, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, type EngineConfig, type ExtractCacheDirResolution, } from "./config.js";
 export { SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "./utils/sdrCaptureColor.js";
@@ -47,6 +48,8 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
+export { spawnChunkStreamingEncoder, buildChunkStreamingArgs, BT709_LIMITED, type ChunkColour, type ChunkStreamingOptions, } from "./services/chunkStreamingEncoder.js";
+export { resolveInPageEncode, type InPageEncodeDecision, type InPageEncodeInput, } from "./services/inPageEncodeEligibility.js";
 export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, buildVideoLayerInput, type VideoLayerInput, } from "./services/videoFrameExtractor.js";
 export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";

package/dist/index.js

@@ -29,6 +29,7 @@
  *   getFrameAtTime, detectGpuEncoder) return a nullable value instead of throwing.
  *
  */
+export { REFERENCE_BACKGROUND_FIELD, referenceBackgroundResult, createReferenceBackgroundRecorder, readReferenceBackground, } from "./services/referenceBackground.js";
 // ── Configuration ──────────────────────────────────────────────────────────────
 export { resolveConfig, resolvePageNavigationTimeout, validateEngineConfigSnapshot, DEFAULT_CONFIG, scaleProtocolTimeoutForComposition, shouldClampToScreenshotForConcreteGpu, applyConcreteGpuScreenshotClamp, explainDrawElementDisabled, resolveExtractCacheDir, defaultExtractCacheDir, EXTRACT_CACHE_DIR_DISABLED_ALIASES, } from "./config.js";
 export { SDR_RGB_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "./utils/sdrCaptureColor.js";
@@ -50,6 +51,8 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 // ── Encoding ───────────────────────────────────────────────────────────────────
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
+export { spawnChunkStreamingEncoder, buildChunkStreamingArgs, BT709_LIMITED, } from "./services/chunkStreamingEncoder.js";
+export { resolveInPageEncode, } from "./services/inPageEncodeEligibility.js";
 // ── Media processing ───────────────────────────────────────────────────────────
 export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, buildVideoLayerInput, } from "./services/videoFrameExtractor.js";
 export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";

package/dist/services/chunkStreamingEncoder.d.ts

@@ -0,0 +1,16 @@
+import type { Fps } from "@hyperframes/core";
+import type { EngineConfig } from "../config.js";
+import { type StreamingEncoder } from "./streamingEncoder.js";
+export interface ChunkColour {
+    primaries: number;
+    transfer: number;
+    matrix: number;
+    fullRange: boolean;
+}
+export declare const BT709_LIMITED: ChunkColour;
+export interface ChunkStreamingOptions {
+    fps: Fps;
+    colour?: ChunkColour;
+}
+export declare function buildChunkStreamingArgs(options: ChunkStreamingOptions, outputPath: string): string[];
+export declare function spawnChunkStreamingEncoder(outputPath: string, options: ChunkStreamingOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>): StreamingEncoder;

package/dist/services/chunkStreamingEncoder.js

@@ -0,0 +1,30 @@
+import { fpsToFfmpegArg } from "@hyperframes/core";
+import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
+import { spawnFfmpegStream } from "./streamingEncoder.js";
+export const BT709_LIMITED = {
+    primaries: 1,
+    transfer: 1,
+    matrix: 1,
+    fullRange: false,
+};
+export function buildChunkStreamingArgs(options, outputPath) {
+    const { primaries, transfer, matrix, fullRange } = options.colour ?? BT709_LIMITED;
+    const vui = [
+        `colour_primaries=${primaries}`,
+        `transfer_characteristics=${transfer}`,
+        `matrix_coefficients=${matrix}`,
+        `video_full_range_flag=${fullRange ? 1 : 0}`,
+    ].join(":");
+    const args = ["-f", "h264", "-framerate", fpsToFfmpegArg(options.fps), "-i", "-"];
+    args.push("-c:v", "copy", "-bsf:v", `h264_metadata=${vui}`);
+    args.push(...["-colorspace:v", "bt709", "-color_primaries:v", "bt709", "-color_trc:v", "bt709"], ...["-color_range", fullRange ? "pc" : "tv"], ...["-video_track_timescale", "90000", "-avoid_negative_ts", "make_zero"]);
+    appendRenderProvenanceArgs(args, outputPath);
+    args.push("-y", outputPath);
+    return args;
+}
+export function spawnChunkStreamingEncoder(outputPath, options, signal, config) {
+    return spawnFfmpegStream(outputPath, buildChunkStreamingArgs(options, outputPath), {
+        signal,
+        config,
+    });
+}

package/dist/services/frameCapture.js

@@ -10,15 +10,15 @@
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
 import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, RUNTIME_BOOTSTRAP_ATTR, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
+import { readReferenceBackground } from "./referenceBackground.js";
 import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
-import { recordWebglContexts, releaseEndedWebglContexts } from "./webglRelease.js";
 import { asDrawElementCaptureFailure, DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
-import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { beginFrameCapture, forgetBeginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, forcePreservedDrawingBuffer, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
 import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
@@ -448,6 +448,7 @@ async function waitForCloseWithTimeout(promise) {
  * path (preMode already forces "screenshot" for DPR other than 1).
  */
 async function initDrawElementOrTransparentBackground(session, page, logInitPhase) {
+    await session.options.recordReferenceBackground?.(() => readReferenceBackground(page));
     const supersampling = (session.options.deviceScaleFactor ?? 1) !== 1;
     // forceScreenshot is an explicit routing decision made upstream (render-mode
     // compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
@@ -1005,7 +1006,6 @@ async function constructCaptureSession(input) {
         }
     });
     await installMediaPageHooks(page, options);
-    await page.evaluateOnNewDocument(recordWebglContexts);
     // Fast capture: record accelerated canvases (webgl/webgl2/webgpu) and force
     // preserveDrawingBuffer before any page script can create a context — their
     // paint records freeze at the first frame, so captureDrawElementFrame
@@ -1726,6 +1726,10 @@ export function recordSubTimelineWarning(session, timeoutMs) {
             },
         },
     ]);
+    if (scriptFailure) {
+        const failed = session.warnings.filter((w) => w.code === "sub_timeline_script_failure");
+        session.options?.onSubTimelineScriptFailure?.(failed);
+    }
 }
 /**
  * Runtime-mounted map-viewport markers, keyed by the CSS selector each map
@@ -2347,7 +2351,6 @@ async function prepareFrameForCapture(session, frameIndex, time, seekOptions, he
     const seekStart = Date.now();
     session.captureStep = "seeking the timeline";
     const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
-    await releaseEndedWebglContexts(page, quantizedTime);
     session.captureStep = "decoding CSS background images";
     await decodeDynamicCssBackgroundImages(page);
     const seekMs = Date.now() - seekStart;
@@ -3296,6 +3299,7 @@ async function captureFrameSurface(session, frameIndex, time, seekOptions, heldV
                 interval: session.beginFrameIntervalMs,
                 noDisplayUpdates: false,
             });
+            forgetBeginFrameCapture(page);
             session.beginFrameSeekPresented = true;
         }
         const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);

package/dist/services/inPageEncodeEligibility.d.ts

@@ -0,0 +1,19 @@
+export interface InPageEncodeInput {
+    enabled: boolean;
+    captureMode: "drawelement" | "screenshot" | "beginframe";
+    format: string;
+    codec: string;
+    hdr: boolean;
+    transparent: boolean;
+    workers: number;
+    hls: boolean;
+    videoLayer: boolean;
+    encoderSupported: boolean;
+}
+export type InPageEncodeDecision = {
+    eligible: true;
+} | {
+    eligible: false;
+    reason: string;
+};
+export declare function resolveInPageEncode(input: InPageEncodeInput): InPageEncodeDecision;

package/dist/services/inPageEncodeEligibility.js

@@ -0,0 +1,15 @@
+export function resolveInPageEncode(input) {
+    const blocker = [
+        [!input.enabled, "disabled"],
+        [input.captureMode !== "drawelement", "capture is not drawElement"],
+        [input.format !== "mp4", "output is not mp4"],
+        [input.codec !== "h264", "codec is not h264"],
+        [input.hdr, "hdr"],
+        [input.transparent, "transparent"],
+        [input.workers !== 1, "parallel workers"],
+        [input.hls, "hls"],
+        [input.videoLayer, "video layer passthrough"],
+        [!input.encoderSupported, "page encoder unsupported"],
+    ].find(([blocked]) => blocked);
+    return blocker ? { eligible: false, reason: blocker[1] } : { eligible: true };
+}

package/dist/services/referenceBackground.d.ts

@@ -0,0 +1,34 @@
+import type { Page } from "puppeteer-core";
+export declare const REFERENCE_BACKGROUND_FIELD = "reference_background";
+export type ReferenceBackground = {
+    kind: "solid";
+    rgb: [number, number, number];
+} | {
+    kind: "none";
+} | {
+    kind: "unsupported_non_solid";
+} | {
+    kind: "unknown";
+};
+export type ReferenceBackgroundResult = {
+    [REFERENCE_BACKGROUND_FIELD]: ReferenceBackground;
+};
+export declare function referenceBackgroundResult(value: unknown): ReferenceBackgroundResult;
+/** Shared by a render's existing sessions; concurrent workers reserve the first read, not a chunk frame. */
+export declare function createReferenceBackgroundRecorder(record: (result: ReferenceBackgroundResult) => void): (read: () => Promise<ReferenceBackground>) => Promise<void>;
+export interface BackgroundLayer {
+    rgba: readonly number[];
+    image: string;
+    opacity: string;
+    filter: string;
+    blend: string;
+    varying: boolean;
+}
+export interface BackgroundObservation {
+    layers: readonly BackgroundLayer[];
+    explicitNone: boolean;
+}
+export declare function classifyReferenceBackground(observation: BackgroundObservation | null): ReferenceBackground;
+/** Runs in the browser, before transparent capture rewrites the author's root/body styles. */
+export declare function observeReferenceBackground(): Promise<BackgroundObservation | null>;
+export declare function readReferenceBackground(page: Pick<Page, "evaluate">): Promise<ReferenceBackground>;

package/dist/services/referenceBackground.js

@@ -0,0 +1,175 @@
+export const REFERENCE_BACKGROUND_FIELD = "reference_background";
+function isByte(value) {
+    return typeof value === "number" && Number.isInteger(value) && value >= 0 && value <= 255;
+}
+function readRgb(value) {
+    if (!Array.isArray(value) || value.length !== 3)
+        return null;
+    const [r, g, b] = value;
+    return isByte(r) && isByte(g) && isByte(b) ? [r, g, b] : null;
+}
+export function referenceBackgroundResult(value) {
+    if (value !== null && typeof value === "object" && "kind" in value) {
+        if (value.kind === "solid" && "rgb" in value) {
+            const rgb = readRgb(value.rgb);
+            if (rgb)
+                return { [REFERENCE_BACKGROUND_FIELD]: { kind: "solid", rgb } };
+        }
+        if (value.kind === "none" || value.kind === "unsupported_non_solid") {
+            return { [REFERENCE_BACKGROUND_FIELD]: { kind: value.kind } };
+        }
+    }
+    return { [REFERENCE_BACKGROUND_FIELD]: { kind: "unknown" } };
+}
+/** Shared by a render's existing sessions; concurrent workers reserve the first read, not a chunk frame. */
+export function createReferenceBackgroundRecorder(record) {
+    let pending;
+    return (read) => {
+        pending ??= read()
+            .catch(() => ({ kind: "unknown" }))
+            .then((value) => record(referenceBackgroundResult(value)));
+        return pending;
+    };
+}
+function layerIsIndeterminate(layer) {
+    return (layer.varying || layer.opacity !== "1" || layer.filter !== "none" || layer.blend !== "normal");
+}
+function validLayer(layer) {
+    return layer.rgba.length === 4 && layer.rgba.every(isByte) && layer.image.length > 0;
+}
+function opaqueReference(rgb, indeterminate) {
+    return indeterminate ? { kind: "unknown" } : { kind: "solid", rgb };
+}
+export function classifyReferenceBackground(observation) {
+    if (!observation || observation.layers.length === 0)
+        return { kind: "unknown" };
+    const indeterminate = observation.layers.some(layerIsIndeterminate);
+    let translucent = false;
+    for (const layer of observation.layers) {
+        if (!validLayer(layer))
+            return { kind: "unknown" };
+        if (layer.image !== "none")
+            return { kind: "unsupported_non_solid" };
+        const rgb = layer.rgba[3] === 255 ? readRgb(layer.rgba.slice(0, 3)) : null;
+        if (rgb)
+            return opaqueReference(rgb, translucent || indeterminate);
+        translucent ||= layer.rgba[3] !== 0;
+    }
+    return !indeterminate && !translucent && observation.explicitNone
+        ? { kind: "none" }
+        : { kind: "unknown" };
+}
+/** Runs in the browser, before transparent capture rewrites the author's root/body styles. */
+export async function observeReferenceBackground() {
+    const root = document.querySelector("[data-composition-id]");
+    if (!root || !document.body)
+        return null;
+    // Inspect the initial film state, never the worker's eventual frame range.
+    window.__hf?.seek?.(0);
+    if ("__hfWaitForSeekCompletion" in window &&
+        typeof window.__hfWaitForSeekCompletion === "function") {
+        await window.__hfWaitForSeekCompletion();
+    }
+    const elements = [];
+    for (let element = root; element; element = element.parentElement)
+        elements.push(element);
+    const canvas = document.createElement("canvas");
+    canvas.width = canvas.height = 1;
+    const context = canvas.getContext("2d", { willReadFrequently: true });
+    if (!context)
+        return null;
+    const layers = elements.map((element) => {
+        const style = getComputedStyle(element);
+        context.clearRect(0, 0, 1, 1);
+        if (!CSS.supports("color", style.backgroundColor))
+            return { rgba: [], image: "", opacity: "", filter: "", blend: "", varying: false };
+        // Chromium resolves CSS color syntax and color spaces; this is a swatch, not film pixels.
+        context.fillStyle = style.backgroundColor;
+        context.fillRect(0, 0, 1, 1);
+        return {
+            rgba: Array.from(context.getImageData(0, 0, 1, 1).data),
+            image: style.backgroundImage,
+            opacity: style.opacity,
+            filter: style.filter,
+            blend: style.mixBlendMode,
+            varying: false,
+        };
+    });
+    return { layers, explicitNone: false };
+}
+function hasChangingCssBackground() {
+    const root = document.querySelector("[data-composition-id]");
+    if (!root)
+        return true;
+    const properties = [
+        "background",
+        "backgroundColor",
+        "backgroundImage",
+        "opacity",
+        "filter",
+        "mixBlendMode",
+    ];
+    return document.getAnimations().some((animation) => {
+        const effect = animation.effect;
+        if (!(effect instanceof KeyframeEffect) || !(effect.target instanceof Element))
+            return false;
+        return (effect.target.contains(root) &&
+            effect.getKeyframes().some((frame) => properties.some((key) => key in frame)));
+    });
+}
+function hasChangingTimelineBackground() {
+    const root = document.querySelector("[data-composition-id]");
+    const timelines = "__timelines" in window ? window.__timelines : undefined;
+    if (!root || !timelines || typeof timelines !== "object")
+        return false;
+    const children = Object.values(timelines).flatMap((timeline) => typeof timeline?.getChildren === "function" ? timeline.getChildren(true, true, false) : []);
+    return children.some((tween) => {
+        const vars = { ...tween?.vars, ...tween?.vars?.css, ...tween?.vars?.startAt };
+        const targets = typeof tween?.targets === "function" ? tween.targets() : [];
+        const changesPaint = Object.keys(vars).some((key) => key.startsWith("background") ||
+            ["opacity", "filter", "autoAlpha", "mixBlendMode"].includes(key));
+        return (changesPaint &&
+            targets.some((target) => target instanceof Element && target.contains(root)));
+    });
+}
+function hasExplicitNoBackground() {
+    const root = document.querySelector("[data-composition-id]");
+    const elements = [];
+    for (let element = root; element; element = element.parentElement)
+        elements.push(element);
+    const declarations = elements.flatMap((element) => element instanceof HTMLElement || element instanceof SVGElement ? [element.style] : []);
+    const sheets = [...document.styleSheets, ...document.adoptedStyleSheets].filter((sheet) => !sheet.disabled);
+    for (const rule of sheets.flatMap((sheet) => Array.from(sheet.cssRules))) {
+        if (rule instanceof CSSFontFaceRule || rule instanceof CSSKeyframesRule)
+            continue;
+        // Proving absence needs complete cascade participation. Unhandled grouping/nesting stays unknown.
+        if (!(rule instanceof CSSStyleRule) || rule.cssRules.length > 0)
+            return false;
+        if (elements.some((element) => element.matches(rule.selectorText)))
+            declarations.push(rule.style);
+    }
+    const backgrounds = declarations.filter((style) => style.getPropertyValue("background-color") || style.getPropertyValue("background-image"));
+    return (backgrounds.length > 0 &&
+        backgrounds.every((style) => style.getPropertyValue("background").trim() === "none"));
+}
+export async function readReferenceBackground(page) {
+    try {
+        const observation = await page.evaluate(observeReferenceBackground);
+        const initial = classifyReferenceBackground(observation);
+        if (!observation || initial.kind === "unsupported_non_solid")
+            return initial;
+        const changes = await Promise.all([
+            page.evaluate(hasChangingCssBackground),
+            page.evaluate(hasChangingTimelineBackground),
+        ]);
+        if (changes.some(Boolean))
+            return { kind: "unknown" };
+        if (initial.kind === "solid")
+            return initial;
+        observation.explicitNone = await page.evaluate(hasExplicitNoBackground);
+        return classifyReferenceBackground(observation);
+    }
+    catch {
+        return { kind: "unknown" };
+    }
+}

package/dist/services/screenshotService.d.ts

@@ -32,6 +32,7 @@ export interface BeginFrameResult {
  * the safe direction (screenshot capture always works).
  */
 export declare function probeBeginFrameLiveness(page: Page, timeoutMs: number, frameTimeTicks?: number, intervalMs?: number): Promise<boolean>;
+export declare function forgetBeginFrameCapture(page: Page): void;
 export declare function beginFrameCapture(page: Page, options: CaptureOptions, frameTimeTicks: number, interval: number): Promise<BeginFrameResult>;
 /**
  * True if the page's actual rendered content is taller than the requested

package/dist/services/screenshotService.js

@@ -81,11 +81,14 @@ frameTimeTicks, intervalMs) {
  * Requires chrome-headless-shell with --enable-begin-frame-control and
  * --deterministic-mode flags.
  */
-// Cache the last valid screenshot buffer per page for hasDamage=false frames.
-// When Chrome reports no visual change, we reuse the previous frame rather than
-// attempting Page.captureScreenshot (which times out in beginFrame mode since
-// the compositor is paused).
+// The last buffer beginFrameCapture returned per page. A screenshot BeginFrame always
+// reports damage, so a frame is reused only when a screenshot-less BeginFrame right after
+// the seek reports none. Any BeginFrame sent elsewhere moves the display past this buffer:
+// call forgetBeginFrameCapture first.
 const lastFrameCache = new WeakMap();
+export function forgetBeginFrameCapture(page) {
+    lastFrameCache.delete(page);
+}
 const PENDING_FRAME_RETRIES = 5;
 async function sendBeginFrame(client, params) {
     for (let attempt = 0;; attempt++) {
@@ -115,14 +118,30 @@ export async function beginFrameCapture(page, options, frameTimeTicks, interval)
         quality: isPng ? undefined : (options.quality ?? 80),
         optimizeForSpeed: true,
     };
-    const result = await sendBeginFrame(client, { frameTimeTicks, interval, screenshot });
+    // With a cached buffer, a screenshot-less BeginFrame first draws the seek and reports
+    // whether it changed anything. The screenshot after it is not displayed: a displayed
+    // screenshot frame leaves damage the next probe would report, and a settle frame to
+    // absorb it would draw page changes that nothing captures.
+    const cached = lastFrameCache.get(page);
+    let screenshotTicks = frameTimeTicks;
+    if (cached) {
+        const probe = await sendBeginFrame(client, { frameTimeTicks, interval });
+        if (!probe.hasDamage)
+            return { buffer: cached, hasDamage: false };
+        screenshotTicks = frameTimeTicks + interval / 2;
+    }
+    const result = await sendBeginFrame(client, {
+        frameTimeTicks: screenshotTicks,
+        interval,
+        screenshot,
+        noDisplayUpdates: cached !== undefined,
+    });
     let buffer;
     if (result.screenshotData) {
         buffer = Buffer.from(result.screenshotData, "base64");
         lastFrameCache.set(page, buffer);
     }
     else {
-        const cached = lastFrameCache.get(page);
         if (cached) {
             buffer = cached;
         }

package/dist/services/streamingEncoder.d.ts

@@ -109,3 +109,8 @@ export declare function buildStreamingArgs(options: StreamingEncoderOptions, out
  * Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
  */
 export declare function spawnStreamingEncoder(outputPath: string, options: StreamingEncoderOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>): Promise<StreamingEncoder>;
+export declare function spawnFfmpegStream(outputPath: string, args: string[], { signal, config, checkFrame, }: {
+    signal?: AbortSignal;
+    config?: Partial<Pick<EngineConfig, "ffmpegStreamingTimeout">>;
+    checkFrame?: (frame: Buffer, index: number) => void;
+}): StreamingEncoder;

package/dist/services/streamingEncoder.js

@@ -302,15 +302,29 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null, nvenc
  * Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
  */
 export async function spawnStreamingEncoder(outputPath, options, signal, config) {
-    const outputDir = dirname(outputPath);
-    if (!existsSync(outputDir))
-        mkdirSync(outputDir, { recursive: true });
     let gpuEncoder = null;
     if (options.useGpu) {
         gpuEncoder = await getCachedGpuEncoder();
     }
     const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
     const args = buildStreamingArgs(options, outputPath, gpuEncoder, nvencPresets);
+    const checksJpeg = !options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg";
+    return spawnFfmpegStream(outputPath, args, {
+        signal,
+        config,
+        checkFrame: checksJpeg
+            ? (frame, index) => {
+                const error = jpegInputError(frame);
+                if (error)
+                    throw new Error(`Invalid JPEG input at frame ${index}: ${error}`);
+            }
+            : undefined,
+    });
+}
+export function spawnFfmpegStream(outputPath, args, { signal, config, checkFrame, }) {
+    const outputDir = dirname(outputPath);
+    if (!existsSync(outputDir))
+        mkdirSync(outputDir, { recursive: true });
     const ffmpeg = spawn(getFfmpegBinary(), args, {
         stdio: ["pipe", "pipe", "pipe"],
         // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
@@ -412,11 +426,7 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
             // so without this copy the pipe would read partially-overwritten data
             // and flicker.
             const copy = Buffer.from(buffer);
-            if (!options.rawInputFormat && (options.imageFormat ?? "jpeg") === "jpeg") {
-                const error = jpegInputError(copy);
-                if (error)
-                    throw new Error(`Invalid JPEG input at frame ${inputFrameIndex}: ${error}`);
-            }
+            checkFrame?.(copy, inputFrameIndex);
             const accepted = stdin.write(copy);
             inputFrameIndex++;
             // Reset inactivity timer immediately ONLY on `accepted === true`. `true`

package/dist/types.d.ts

@@ -4,6 +4,7 @@
  * The engine's page contract. Any web page that wants to be rendered
  * as video must expose `window.__hf` implementing the HfProtocol interface.
  */
+import type { ReferenceBackground } from "./services/referenceBackground.js";
 import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
 import type { Fps } from "@hyperframes/core";
 import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
@@ -129,8 +130,11 @@ export interface HfProtocol {
     } | null;
 }
 export interface CaptureOptions {
+    /** Shared once-only reader, invoked before capture changes root/body paint. */
+    recordReferenceBackground?: (read: () => Promise<ReferenceBackground>) => Promise<void>;
     width: number;
     height: number;
+    onSubTimelineScriptFailure?: (warnings: readonly CaptureWarning[]) => void;
     /**
      * Producer-resolved composition duration (seconds) — the data-duration
      * clamp actually rendered, which can differ from the page's raw

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -59,8 +59,8 @@
     "puppeteer": "~25.11.0",
     "puppeteer-core": "^25.11.0",
     "undici": "7.25.0",
-    "@hyperframes/core": "^0.9.4",
-    "@hyperframes/parsers": "^0.9.4"
+    "@hyperframes/core": "^0.9.6",
+    "@hyperframes/parsers": "^0.9.6"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",