@hyperframes/engine 0.9.4 → 0.9.5

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";

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";

package/dist/services/frameCapture.js

@@ -10,8 +10,8 @@
 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";
@@ -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;

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/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.5",
   "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/parsers": "^0.9.5",
+    "@hyperframes/core": "^0.9.5"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",