@hyperframes/engine 0.9.19 → 0.9.21

package/dist/index.d.ts

@@ -40,7 +40,7 @@ export { acquireBrowser, setHostHandlesSigint, releaseBrowser, drainBrowserPool,
 export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services/protocolTimeoutErrorHint.js";
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, type NavigationTimeoutHintContext, } from "./services/pageNavigationTimeoutErrorHint.js";
 export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, type CompositionLengthSource, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, applyVideoMetadataHints, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, type DrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, type CompositionLengthSource, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, type CaptureSession, isTransientBrowserError, isMemoryExhaustionError, type BeforeCaptureHook, type DiscardWarmupInnerCapture, type StaticVerificationOutcome, VfxFailureError, ImageMissingFromFrameError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, applyVideoMetadataHints, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
@@ -68,7 +68,7 @@ export { frameFileExtension } from "./services/frameCapture.js";
 export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThreads.js";
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionBlur.js";
-export type { PageMotionBlurOff } from "./types.js";
+export type { PageMotionBlurOff, PageMotionBlurSummary } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { isBrowserSafePort, listenOnBrowserSafePort, settleOnBrowserSafePort, } from "./utils/browserSafePort.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";

package/dist/index.js

@@ -42,7 +42,7 @@ export { augmentProtocolTimeoutError, isProtocolTimeoutError, } from "./services
 export { augmentPageNavigationTimeoutError, isPageNavigationTimeoutError, } from "./services/pageNavigationTimeoutErrorHint.js";
 // ── Frame capture pipeline ──────────────────────────────────────────────────────
 export { forcePreservedDrawingBuffer } from "./services/drawElementService.js";
-export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, applyVideoMetadataHints, } from "./services/frameCapture.js";
+export { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBuffer, captureFrameToBufferPipelined, captureFramesBatchPipelined, DrawElementVerificationError, isDrawElementVerificationError, getDrawElementVerificationDetails, recaptureDrawElementFrameForVerify, completeDeferredDrawElementInit, writeCapturedFrame, discardWarmupCapture, getCompositionDuration, getCompositionLengthSource, getCapturePerfSummary, percentileOf, prepareCaptureSessionForReuse, deriveBeginFrameProbeTimeTicks, isTransientBrowserError, isMemoryExhaustionError, VfxFailureError, ImageMissingFromFrameError, waitForImagesReady, evaluateHfDiagnostic, buildZeroDurationDiagnostic, applyVideoMetadataHints, } from "./services/frameCapture.js";
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────

package/dist/services/browserManager.d.ts

@@ -16,6 +16,7 @@ export declare const ownedLaunchOptions: () => {
     handleSIGINT: boolean;
     pipe: boolean;
 };
+export declare const SOFTWARE_WEBGL_RENDERER_TOKENS: readonly string[];
 export interface GpuProbeLifecycle {
     launch(puppeteer: PuppeteerNode, options: LaunchOptions): Promise<Browser>;
     close(browser: Browser): Promise<void>;

package/dist/services/browserManager.js

@@ -27,15 +27,18 @@ export function setHostHandlesSigint(owned) {
     hostHandlesSigint = owned;
 }
 export const ownedLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint, pipe: true });
+export const SOFTWARE_WEBGL_RENDERER_TOKENS = [
+    "swiftshader",
+    "llvmpipe",
+    "lavapipe",
+    "softpipe",
+    "mesa offscreen",
+    "microsoft basic render driver",
+    "software rasterizer",
+];
 function isSoftwareWebGlRenderer(rendererInfo) {
     const renderer = rendererInfo.trim().toLowerCase();
-    return (renderer.includes("swiftshader") ||
-        renderer.includes("llvmpipe") ||
-        renderer.includes("lavapipe") ||
-        renderer.includes("softpipe") ||
-        renderer.includes("mesa offscreen") ||
-        renderer.includes("microsoft basic render driver") ||
-        renderer.includes("software rasterizer"));
+    return SOFTWARE_WEBGL_RENDERER_TOKENS.some((token) => renderer.includes(token));
 }
 async function getPuppeteer() {
     if (_puppeteer)
@@ -999,7 +1002,7 @@ export async function assertWebGpuAdapterAvailable(page, requiresWebGpu, softwar
             return await Promise.race([
                 probe(),
                 new Promise((resolve) => {
-                    timer = setTimeout(() => {
+                    timer = (globalThis.window?.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(() => {
                         expired = true;
                         resolve(false);
                     }, timeoutMs);

package/dist/services/drawElementService.d.ts

@@ -13,6 +13,7 @@
  * Blink>Canvas, 2026-06-08).
  */
 import type { Page } from "puppeteer-core";
+import type { CaptureMode } from "./browserLeasePool.js";
 /**
  * Discriminant prefix embedded in every "capture canvas isn't set up yet"
  * error THIS module throws/returns (as opposed to the native
@@ -52,13 +53,23 @@ export declare const DE_CANVAS_NOT_INITIALIZED_CODE = "HF_DE_CANVAS_NOT_INITIALI
  *    destination additionally drops promoted sub-layers (Chromium bug
  *    521434899). The speedup is real only on a hardware GPU (macOS 1.6×), so
  *    SwiftShader always routes to the platform baseline.
- *
- * The former <video> gate (a proxy for the word-by-word caption opacity pattern)
- * was removed once Chrome 151 fixed crbug 521861819: video + nested-fade comps now
- * render correctly on the drawElement path (verified PSNR=inf vs baseline). 151 is
- * the pinned floor. See docs/fast-capture-limitations.md Lim 2.
+ *  - No WebGL at all (a GPU-less host asked for hardware GL) is software at best: `webgl_unavailable`.
+ *  - A BeginFrame launch (Linux headless-shell): the self-verify truth page has no BeginFrame
+ *    driver, so drawElement is gated as `beginframe_no_self_verify`.
+ */
+export declare function resolveDrawElementCaptureMode(softwareBackend: boolean, transparent: boolean): "drawelement" | "screenshot";
+export type DrawElementGateReason = "swiftshader" | "webgl_unavailable" | "beginframe_no_self_verify";
+/**
+ * The init-time gate that routes drawElement to the baseline capture, or null when it may engage.
+ * `swiftshader` covers any software GL; `webgl_unavailable` is a host with no WebGL at all.
+ * `beginframe_no_self_verify` is a BeginFrame launch, which cannot take the self-verify ground truth.
+ * `forceDE` (HF_FORCE_DRAWELEMENT) bypasses only the launch gate. Pure; exported for tests.
  */
-export declare function resolveDrawElementCaptureMode(isSwiftShader: boolean, transparent: boolean): "drawelement" | "screenshot";
+export declare function drawElementGate(args: {
+    backend: Pick<GpuBackendInfo, "isSwiftShader" | "webglAvailable">;
+    launchCaptureMode: CaptureMode;
+    forceDE: boolean;
+}): DrawElementGateReason | null;
 /**
  * Instrument `HTMLCanvasElement.getContext` before any page script runs.
  *
@@ -82,8 +93,10 @@ export declare function instrumentAcceleratedCanvases(): void;
  */
 export declare function forcePreservedDrawingBuffer(): void;
 export interface GpuBackendInfo {
-    /** SwiftShader (software rasterizer) — e.g. Docker headless-shell. */
+    /** Software GL (SwiftShader, llvmpipe, ...) — e.g. Docker headless-shell. Named for the common case. */
     isSwiftShader: boolean;
+    /** False when no WebGL context could be created (null or threw): not a real GPU. */
+    webglAvailable: boolean;
     /**
      * Raw UNMASKED_RENDERER_WEBGL string (e.g. "ANGLE (Apple, ANGLE Metal
      * Renderer: Apple M4 Pro, ...)", "ANGLE (NVIDIA, GeForce RTX 3080 Direct3D11
@@ -112,8 +125,8 @@ export declare function classifyGpuRenderer(renderer: string | null | undefined)
  * Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw
  * renderer string for telemetry.
  *
- * `isSwiftShader` is true inside Docker headless-shell with
- * --use-angle=swiftshader. Call once after window.__hf is ready; cache the
+ * `isSwiftShader` is true for any software GL, e.g. Docker headless-shell with
+ * --use-angle=swiftshader; `webglAvailable` is false with no WebGL at all. Call once after window.__hf is ready; cache the
  * result on the session.
  */
 export declare function detectGpuBackend(page: Page): Promise<GpuBackendInfo>;

package/dist/services/drawElementService.js

@@ -13,6 +13,7 @@
  * compositor sub-layers on a transparent canvas destination (Chromium bug, filed
  * Blink>Canvas, 2026-06-08).
  */
+import { SOFTWARE_WEBGL_RENDERER_TOKENS } from "./browserManager.js";
 /**
  * Discriminant prefix embedded in every "capture canvas isn't set up yet"
  * error THIS module throws/returns (as opposed to the native
@@ -52,21 +53,35 @@ export const DE_CANVAS_NOT_INITIALIZED_CODE = "HF_DE_CANVAS_NOT_INITIALIZED";
  *    destination additionally drops promoted sub-layers (Chromium bug
  *    521434899). The speedup is real only on a hardware GPU (macOS 1.6×), so
  *    SwiftShader always routes to the platform baseline.
- *
- * The former <video> gate (a proxy for the word-by-word caption opacity pattern)
- * was removed once Chrome 151 fixed crbug 521861819: video + nested-fade comps now
- * render correctly on the drawElement path (verified PSNR=inf vs baseline). 151 is
- * the pinned floor. See docs/fast-capture-limitations.md Lim 2.
+ *  - No WebGL at all (a GPU-less host asked for hardware GL) is software at best: `webgl_unavailable`.
+ *  - A BeginFrame launch (Linux headless-shell): the self-verify truth page has no BeginFrame
+ *    driver, so drawElement is gated as `beginframe_no_self_verify`.
  */
-export function resolveDrawElementCaptureMode(isSwiftShader, transparent) {
-    // `transparent` is retained for call-site clarity; SwiftShader blocks
+export function resolveDrawElementCaptureMode(softwareBackend, transparent) {
+    // `transparent` is retained for call-site clarity; a software backend blocks
     // unconditionally now (no GPU egress to skip — parity at best), which
     // subsumes the former transparent-only SwiftShader case.
     void transparent;
-    if (isSwiftShader)
+    if (softwareBackend)
         return "screenshot";
     return "drawelement";
 }
+/**
+ * The init-time gate that routes drawElement to the baseline capture, or null when it may engage.
+ * `swiftshader` covers any software GL; `webgl_unavailable` is a host with no WebGL at all.
+ * `beginframe_no_self_verify` is a BeginFrame launch, which cannot take the self-verify ground truth.
+ * `forceDE` (HF_FORCE_DRAWELEMENT) bypasses only the launch gate. Pure; exported for tests.
+ */
+export function drawElementGate(args) {
+    const { backend, launchCaptureMode, forceDE } = args;
+    if (backend.isSwiftShader)
+        return "swiftshader";
+    if (!backend.webglAvailable)
+        return "webgl_unavailable";
+    if (launchCaptureMode === "beginframe" && !forceDE)
+        return "beginframe_no_self_verify";
+    return null;
+}
 /**
  * Instrument `HTMLCanvasElement.getContext` before any page script runs.
  *
@@ -173,23 +188,35 @@ export function classifyGpuRenderer(renderer) {
  * Detect the page's WebGL backend: SwiftShader vs a real GPU, plus the raw
  * renderer string for telemetry.
  *
- * `isSwiftShader` is true inside Docker headless-shell with
- * --use-angle=swiftshader. Call once after window.__hf is ready; cache the
+ * `isSwiftShader` is true for any software GL, e.g. Docker headless-shell with
+ * --use-angle=swiftshader; `webglAvailable` is false with no WebGL at all. Call once after window.__hf is ready; cache the
  * result on the session.
  */
 export async function detectGpuBackend(page) {
-    return page.evaluate(() => {
+    return page.evaluate((softwareTokens) => {
         const canvas = document.createElement("canvas");
-        const gl = canvas.getContext("webgl") ||
-            canvas.getContext("experimental-webgl");
+        let gl = null;
+        try {
+            gl =
+                canvas.getContext("webgl") ||
+                    canvas.getContext("experimental-webgl");
+        }
+        catch {
+            gl = null;
+        }
         if (!gl)
-            return { isSwiftShader: false, renderer: null };
+            return { isSwiftShader: false, webglAvailable: false, renderer: null };
         const ext = gl.getExtension("WEBGL_debug_renderer_info");
         if (!ext)
-            return { isSwiftShader: false, renderer: null };
+            return { isSwiftShader: false, webglAvailable: true, renderer: null };
         const renderer = gl.getParameter(ext.UNMASKED_RENDERER_WEBGL);
-        return { isSwiftShader: renderer.toLowerCase().includes("swiftshader"), renderer };
-    });
+        const lower = renderer.toLowerCase();
+        return {
+            isSwiftShader: softwareTokens.some((token) => lower.includes(token)),
+            webglAvailable: true,
+            renderer,
+        };
+    }, SOFTWARE_WEBGL_RENDERER_TOKENS);
 }
 /**
  * Back-compat wrapper over {@link detectGpuBackend} for callers that only
@@ -461,7 +488,7 @@ syncToPaintEvent = true) {
                 }
                 // Encode OUTSIDE the paint handler — heavy canvas work inside the
                 // paint event can stall the renderer.
-                setTimeout(() => {
+                (window.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(() => {
                     try {
                         resolveCapture(fmt === "png"
                             ? canvas.toDataURL("image/png")
@@ -493,7 +520,7 @@ syncToPaintEvent = true) {
             // throttled page), fall back to an unsynchronized draw after 250 ms —
             // worst case one-frame-stale content (the root's alpha may lag its
             // transform by that frame) rather than a hung render.
-            setTimeout(() => {
+            (window.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(() => {
                 canvas.removeEventListener("paint", onPaint);
                 drawAndEncode();
             }, 250);
@@ -843,7 +870,7 @@ export async function produceDrawElementFrame(page, width, height, quality = 80,
             // Sentinel dirty + requestPaint() — see __hfDeInvalidate in
             // injectDrawElementCanvas.
             usedRequestPaint = aw.__hfDeInvalidate?.() === true;
-            setTimeout(() => {
+            (window.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(() => {
                 canvas.removeEventListener("paint", onPaint);
                 drawAndKick();
             }, 250);
@@ -930,7 +957,7 @@ export async function produceDrawElementFrameBatch(page, times, width, height, q
             // Sentinel dirty + requestPaint() — see __hfDeInvalidate in
             // injectDrawElementCanvas.
             usedRequestPaint = aw.__hfDeInvalidate?.() === true;
-            setTimeout(settle, 250);
+            (window.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(settle, 250);
         });
         let prevBitmap = Promise.resolve();
         let prevBitmapIdx = -1;

package/dist/services/frameCapture.d.ts

@@ -12,7 +12,7 @@ import { type MotionBlurPlan } from "./motionBlur.js";
 import { type BrowserLease, type CaptureMode } from "./browserManager.js";
 import { pageScreenshotCapture } from "./screenshotService.js";
 import { type EngineConfig } from "../config.js";
-import type { CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, SubTimelineWaitMemo, SubTimelineWaitOutcome } from "../types.js";
+import type { CaptureOptions, CaptureVideoMetadataHint, CaptureResult, CaptureBufferResult, CapturePerfSummary, CaptureWarning, PageMotionBlurSummary, SubTimelineWaitMemo, SubTimelineWaitOutcome } from "../types.js";
 import { type ChromeMemorySampler, type ChromePids } from "./chromeMemorySampler.js";
 import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
 export { isMemoryExhaustionError, isTransientBrowserError } from "./captureFailure.js";
@@ -25,7 +25,7 @@ export type BeforeCaptureHook = ((page: Page, time: number, heldVideoTime?: numb
     fresh?: () => BeforeCaptureHook | null;
 };
 /** The per-frame wait a capture is in, worded for the stall error a user reads. */
-type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame";
+type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame" | "waiting for a late image";
 export interface CaptureSession {
     browser: Browser;
     /** Exact ownership token for this browser acquisition. */
@@ -53,6 +53,7 @@ export interface CaptureSession {
     lastFrameAbsoluteIndex?: number;
     /** Count of frames served from a reused buffer (dedup telemetry). */
     staticDedupCount?: number;
+    pageMotionBlur?: PageMotionBlurSummary;
     /** Live Chrome memory sampler; started in initializeSession, stopped in closeCaptureSession. */
     chromeMemory?: ChromeMemorySampler;
     /**
@@ -109,6 +110,8 @@ export interface CaptureSession {
     subTimelineWaitMemo: SubTimelineWaitMemo;
     /** Structured readiness warnings surfaced to the producer's render policy. */
     warnings: CaptureWarning[];
+    /** Images still loading when capture began: a frame that shows one waits for it (waitForShownLateImages). */
+    lateImages?: Set<string>;
     initTelemetry?: {
         initDurationMs: number;
         tweenCount: number;
@@ -415,7 +418,7 @@ export declare function formatConsoleDiagnostic(type: string, text: string, loca
     text: string;
     suppressHostLog: boolean;
 };
-export declare const HF_READY_DIAGNOSTIC_EXPR = "(async function() {\n  var hf = window.__hf;\n  var player = window.__player;\n  var renderReady = !!window.__renderReady;\n  var hasSeek = !!(hf && typeof hf.seek === \"function\");\n  var duration = hf ? hf.duration : -1;\n  var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);\n  var root = document.querySelector(\"[data-composition-id]\");\n  var declaredDuration = root ? Number(root.getAttribute(\"data-duration\")) : -1;\n  var registry = (window.__hf && window.__hf.buildReady) || {};\n  var keys = Object.keys(registry);\n  // A microtask race mis-sorts a non-native thenable (extra adoption tick)\n  // and rejects the whole expression on a rejected entry. Settling each\n  // key onto its own record and waiting one macrotask avoids both.\n  var settled = {};\n  if (keys.length > 0) {\n    keys.forEach(function(key) {\n      Promise.resolve(registry[key]).then(\n        function() { settled[key] = \"resolved\"; },\n        function() { settled[key] = \"rejected\"; },\n      );\n    });\n    await new Promise(function(r) { setTimeout(r, 0); });\n  }\n  // A thenable resolving via its own setTimeout(0) can still misreport as\n  // pending here (macrotask registration order, not resolution order), a\n  // narrow case that self-corrects on the next ~1s diagnostic tick.\n  var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });\n  var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === \"rejected\"; });\n  return {\n    renderReady: renderReady,\n    hasHf: !!hf,\n    hasSeek: hasSeek,\n    hasPlayer: !!player,\n    duration: duration,\n    hasTimeline: hasTimeline,\n    declaredDuration: declaredDuration,\n    pendingBuildReadyKeys: pendingBuildReadyKeys,\n    rejectedBuildReadyKeys: rejectedBuildReadyKeys,\n  };\n})()";
+export declare const HF_READY_DIAGNOSTIC_EXPR = "(async function() {\n  var hf = window.__hf;\n  var player = window.__player;\n  var renderReady = !!window.__renderReady;\n  var hasSeek = !!(hf && typeof hf.seek === \"function\");\n  var duration = hf ? hf.duration : -1;\n  var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);\n  var root = document.querySelector(\"[data-composition-id]\");\n  var declaredDuration = root ? Number(root.getAttribute(\"data-duration\")) : -1;\n  var registry = (window.__hf && window.__hf.buildReady) || {};\n  var keys = Object.keys(registry);\n  // A microtask race mis-sorts a non-native thenable (extra adoption tick)\n  // and rejects the whole expression on a rejected entry. Settling each\n  // key onto its own record and waiting one macrotask avoids both.\n  var settled = {};\n  if (keys.length > 0) {\n    keys.forEach(function(key) {\n      Promise.resolve(registry[key]).then(\n        function() { settled[key] = \"resolved\"; },\n        function() { settled[key] = \"rejected\"; },\n      );\n    });\n    await new Promise(function(r) {\n      (window.__HF_VIRTUAL_TIME__ && window.__HF_VIRTUAL_TIME__.originalSetTimeout || setTimeout)(r, 0);\n    });\n  }\n  // A thenable resolving via its own setTimeout(0) can still misreport as\n  // pending here (macrotask registration order, not resolution order), a\n  // narrow case that self-corrects on the next ~1s diagnostic tick.\n  var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });\n  var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === \"rejected\"; });\n  return {\n    renderReady: renderReady,\n    hasHf: !!hf,\n    hasSeek: hasSeek,\n    hasPlayer: !!player,\n    duration: duration,\n    hasTimeline: hasTimeline,\n    declaredDuration: declaredDuration,\n    pendingBuildReadyKeys: pendingBuildReadyKeys,\n    rejectedBuildReadyKeys: rejectedBuildReadyKeys,\n  };\n})()";
 export interface HfDiagnostic {
     renderReady: boolean;
     hasHf: boolean;
@@ -455,6 +458,15 @@ export declare function pollImagesReady(page: Page, timeoutMs: number, intervalM
 export declare function waitForImagesReady(page: Page, timeoutMs: number, onUnloaded: (sources: string) => void): Promise<boolean>;
 /** @internal exported for contract testing. */
 export declare function collectMediaReadinessWarnings(page: Page, skipIds: readonly string[], timeoutMs: number): Promise<CaptureWarning[]>;
+/** Thrown when a frame would show an image that never arrived: the video would silently lack it. */
+export declare class ImageMissingFromFrameError extends Error {
+    readonly frameIndex: number;
+    readonly sources: readonly string[];
+    readonly failedToLoad: boolean;
+    constructor(frameIndex: number, sources: readonly string[], failedToLoad: boolean);
+}
+/** Before a frame: wait for any late image it shows, for as long as the page was given to get ready, else stop. */
+export declare function waitForShownLateImages(session: CaptureSession, frameIndex: number): Promise<void>;
 /** Report background urls that timed out decoding; the shown url drops credentials and query. */
 export declare function recordBackgroundDecodeTimeouts(session: CaptureSession, urls: readonly string[] | undefined): void;
 export declare function recordSubTimelineWarning(session: CaptureSession, timeoutMs: number): void;
@@ -798,6 +810,7 @@ export declare function getCompositionLengthSource(session: CaptureSession): Pro
 export declare function computeDeVerifySampleFractions(k: number): number[];
 /** Seeks the page the truth is read from; callbacks run unless suppressed (suppressed, a count-up's text is stale). */
 export declare function seekDeVerifyTruth(page: Page, t: number, suppressEvents: boolean): Promise<void>;
+export declare function captureDeVerificationFrames(session: CaptureSession, page: Page, logInitPhase: (phase: string) => void): Promise<void>;
 /**
  * Percentile of a positive-real sample set (nearest-rank; matches how the
  * existing {@link medianOf} p50 helper picks the middle index). `p` is a

package/dist/services/frameCapture.js

@@ -15,11 +15,11 @@ import { holdRenderFrameVideos } from "./renderFrameVideoHold.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";
+import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, pageMotionBlurRecorder, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.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 { classifyGpuRenderer, detectGpuBackend, drawElementGate, injectDrawElementCanvas, captureDrawElementFrame, 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";
 import { getAvailableMemoryMb } from "./systemMemory.js";
@@ -163,7 +163,7 @@ export async function decodeDynamicCssBackgroundImages(page) {
                 image.src = url;
                 let timer;
                 const expired = new Promise((resolve) => {
-                    timer = setTimeout(() => resolve("late"), limitMs);
+                    timer = (window.__HF_VIRTUAL_TIME__?.originalSetTimeout ?? setTimeout)(() => resolve("late"), limitMs);
                 });
                 try {
                     const outcome = await Promise.race([
@@ -453,6 +453,14 @@ async function waitForCloseWithTimeout(promise) {
         clearTimeout(timer);
     return !timedOut;
 }
+const DE_GATE_MESSAGES = {
+    swiftshader: "SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
+        "parity-or-slower; see fast-capture-limitations.md)",
+    webgl_unavailable: "WebGL is unavailable (no GPU behind this browser, so it rasterizes in software and " +
+        "drawElement has no GPU egress to skip)",
+    beginframe_no_self_verify: "this browser was launched for BeginFrame capture, whose self-verify truth page has no " +
+        "BeginFrame driver, so drawElement frames could not be checked",
+};
 /**
  * Post-readiness capture-surface init, shared by the screenshot and BeginFrame
  * init paths (called after the page is fully ready). When `useDrawElement` is
@@ -592,17 +600,20 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         // Both reproduced on Chrome <=150 (video+caption-fade ~12 dB; stacked fade
         // 24.5 dB) and both render correctly on 151 (verified: video+nested-fade repro
         // PSNR=inf; efb59c5b 24.5→47.4 dB, 0 damaged frames). 151 is the pinned floor.
-        const mode = resolveDrawElementCaptureMode(session.isSwiftShader, transparent);
-        if (mode === "screenshot") {
-            session.deGateReason = "swiftshader";
-            session.deFallbackTrigger = "swiftshader";
+        const gateReason = drawElementGate({
+            backend: gpuBackend,
+            launchCaptureMode: session.launchCaptureMode,
+            forceDE,
+        });
+        if (gateReason !== null) {
+            session.deGateReason = gateReason;
+            session.deFallbackTrigger = gateReason;
             // Fall back to the browser's LAUNCH mode, not unconditionally to
             // "screenshot": on a BeginFrame-launched browser (Linux fast capture)
             // Page.captureScreenshot hangs for the full protocol timeout, while
             // beginFrameCapture is the platform's normal baseline path.
             console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
-                "SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
-                "parity-or-slower; see fast-capture-limitations.md)");
+                DE_GATE_MESSAGES[gateReason]);
             await routeToFallback();
         }
         else {
@@ -771,7 +782,7 @@ async function cssEffectRiskFrames(session, totalFrames) {
         if (!scan.reason || !scan.bounded)
             return null;
         const fps = fpsToNumber(session.options.fps);
-        const live = await scanCssEffectLiveFrames(scratch.page, fps, totalFrames, totalFrames * MAX_RISK_FRAME_FRACTION, { onProgress: session.options.onEffectScanProgress });
+        const live = await scanCssEffectLiveFrames(scratch.page, fps, totalFrames, totalFrames * MAX_RISK_FRAME_FRACTION, { onProgress: session.options.onEffectScanProgress, onEnd: session.options.onEffectScanEnd });
         return live && withFramesAfterCallback(live, scan.callbackFrom, fps, totalFrames);
     }
     catch (error) {
@@ -1197,7 +1208,9 @@ export const HF_READY_DIAGNOSTIC_EXPR = `(async function() {
         function() { settled[key] = "rejected"; },
       );
     });
-    await new Promise(function(r) { setTimeout(r, 0); });
+    await new Promise(function(r) {
+      (window.__HF_VIRTUAL_TIME__ && window.__HF_VIRTUAL_TIME__.originalSetTimeout || setTimeout)(r, 0);
+    });
   }
   // A thenable resolving via its own setTimeout(0) can still misreport as
   // pending here (macrotask registration order, not resolution order), a
@@ -1709,6 +1722,85 @@ function recordCaptureWarnings(session, warnings) {
         console.warn(`[FrameCapture:${warning.code}] ${warning.message}`, warning.details ?? {});
     }
 }
+function recordReadiness(session, warnings) {
+    recordCaptureWarnings(session, warnings);
+    for (const warning of warnings) {
+        if (warning.code !== "media_readiness_timeout" || warning.details?.mediaType !== "image")
+            continue;
+        session.lateImages ??= new Set();
+        for (const source of warning.details.sources ?? [])
+            session.lateImages.add(source);
+    }
+}
+/** Thrown when a frame would show an image that never arrived: the video would silently lack it. */
+export class ImageMissingFromFrameError extends Error {
+    frameIndex;
+    sources;
+    failedToLoad;
+    constructor(frameIndex, sources, failedToLoad) {
+        super(`Frame ${frameIndex} shows ${sources.join(", ")}, which ${failedToLoad ? "failed to load" : "did not load in time"}, ` +
+            `so the render stopped rather than make a video missing it. ` +
+            (failedToLoad
+                ? `Check that the image exists and can be opened.`
+                : `Try fewer workers (--workers 1) or a longer --player-ready-timeout.`));
+        this.frameIndex = frameIndex;
+        this.sources = sources;
+        this.failedToLoad = failedToLoad;
+        this.name = "ImageMissingFromFrameError";
+    }
+}
+const LATE_IMAGE_POLL_MS = 100;
+/** Before a frame: wait for any late image it shows, for as long as the page was given to get ready, else stop. */
+export async function waitForShownLateImages(session, frameIndex) {
+    const lateImages = session.lateImages;
+    if (!lateImages?.size)
+        return;
+    session.captureStep = "waiting for a late image";
+    const timeoutMs = session.config?.playerReadyTimeout ?? DEFAULT_CONFIG.playerReadyTimeout;
+    const deadline = Date.now() + timeoutMs;
+    for (;;) {
+        const { arrived, waiting, broken } = await session.page.evaluate(async (urls) => {
+            const listed = new Set(urls);
+            const found = Array.from(document.querySelectorAll("img")).filter((img) => listed.has(img.src));
+            const loaded = found.filter((img) => img.complete && img.naturalWidth > 0);
+            await Promise.allSettled(loaded.map((img) => img.decode()));
+            const inViewport = (img) => {
+                const box = img.getBoundingClientRect();
+                return (box.width > 0 &&
+                    box.height > 0 &&
+                    box.right > 0 &&
+                    box.bottom > 0 &&
+                    box.left < window.innerWidth &&
+                    box.top < window.innerHeight);
+            };
+            const shown = found.filter((img) => !loaded.includes(img) &&
+                img.checkVisibility({ opacityProperty: true, visibilityProperty: true }) &&
+                inViewport(img));
+            return {
+                arrived: loaded.map((img) => img.src),
+                waiting: shown.filter((img) => !img.complete).map((img) => img.src),
+                broken: shown.filter((img) => img.complete).map((img) => img.src),
+            };
+        }, Array.from(lateImages));
+        for (const source of arrived)
+            lateImages.delete(source);
+        const missing = Date.now() >= deadline ? [...waiting, ...broken] : broken;
+        if (missing.length > 0) {
+            const stopped = new ImageMissingFromFrameError(frameIndex, [...new Set(missing.map(sanitizeDiagnosticUrl))].sort(), broken.length > 0);
+            recordCaptureWarnings(session, [
+                {
+                    code: "image_missing_from_frame",
+                    message: stopped.message,
+                    details: { mediaType: "image", sources: [...stopped.sources] },
+                },
+            ]);
+            throw stopped;
+        }
+        if (waiting.length === 0)
+            return;
+        await new Promise((resolve) => setTimeout(resolve, LATE_IMAGE_POLL_MS));
+    }
+}
 /** Report background urls that timed out decoding; the shown url drops credentials and query. */
 export function recordBackgroundDecodeTimeouts(session, urls) {
     // Mocked pages answer evaluate() with undefined, so tolerate a missing list.
@@ -2187,7 +2279,7 @@ export async function initializeSession(session) {
             console.warn(`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
                 `Continuing render. Affected videos will appear as blank/black frames.`);
         }
-        recordCaptureWarnings(session, await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout));
+        recordReadiness(session, await collectMediaReadinessWarnings(page, skipVideoIds, pageReadyTimeout));
         await recordLiveMapWarning(session, page);
         await recordSessionInitTelemetry(session, initStart);
         // Ground-truth-check the upstream captureBeyondViewport request (see
@@ -2300,7 +2392,7 @@ export async function initializeSession(session) {
             console.warn(`[FrameCapture] Some video elements did not decode within ${pageReadyTimeout}ms: ${failedVideos}. ` +
                 `Continuing render. Affected videos will appear as blank/black frames.`);
         }
-        recordCaptureWarnings(session, await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout));
+        recordReadiness(session, await collectMediaReadinessWarnings(page, bfSkipVideoIds, pageReadyTimeout));
         await recordLiveMapWarning(session, page);
         await recordSessionInitTelemetry(session, initStart);
     });
@@ -2419,6 +2511,7 @@ 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 waitForShownLateImages(session, frameIndex);
     session.captureStep = "decoding CSS background images";
     // Mocked pages answer evaluate() with undefined, so tolerate a missing list.
     recordBackgroundDecodeTimeouts(session, await decodeDynamicCssBackgroundImages(page));
@@ -3530,6 +3623,7 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
     const eventfulSeekStart = Date.now();
     session.captureStep = "seeking the timeline";
     await seekPageTimeline(session.page, frameTime, undefined);
+    await waitForShownLateImages(session, frameIndex);
     const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
     if (session.onBeforeCapture) {
         // Sub-samples leave a video's style alone: inject at frameTime first so the held frame
@@ -3624,7 +3718,7 @@ async function captureFrameCore(session, frameIndex, time) {
         session.capturePerf.totalMs += captureTimeMs;
         session.capturePerf.frameMs.push(captureTimeMs);
         if (session.capturePerf.frames === 1) {
-            const blur = await describePageMotionBlur(session.page).catch(() => null);
+            const blur = await describePageMotionBlur(session.page, pageMotionBlurRecorder(session)).catch(() => null);
             if (blur)
                 console.error(blur);
         }
@@ -3840,6 +3934,15 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
     assertVfxIntact(session);
     for (const frameIndex of frameIndices)
         assertNotRiskFrame(session, frameIndex);
+    // The fused batch seeks inside the page, with no stop between frames to wait for a late image.
+    if (session.lateImages?.size) {
+        const oneByOne = [];
+        for (const [i, frameIndex] of frameIndices.entries()) {
+            const { encodeResult } = await captureFrameToBufferPipelined(session, frameIndex, times[i] ?? 0);
+            oneByOne.push({ frameIndex, encodeResult });
+        }
+        return oneByOne;
+    }
     const startTime = Date.now();
     const fps = fpsToNumber(options.fps);
     const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
@@ -3966,7 +4069,7 @@ export async function closeCaptureSession(session) {
         await waitForCloseWithTimeout(session.chromeMemory.sampleOnce());
     }
     if (session.page && !session.pageReleased) {
-        const blur = await describePageMotionBlurAtEnd(session.page);
+        const blur = await describePageMotionBlurAtEnd(session.page, undefined, pageMotionBlurRecorder(session));
         if (blur)
             console.error(blur);
     }
@@ -4105,7 +4208,7 @@ export async function seekDeVerifyTruth(page, t, suppressEvents) {
             hf.seek(tt, { suppressEvents: suppress });
     }, t, suppressEvents);
 }
-async function captureDeVerificationFrames(session, page, logInitPhase) {
+export async function captureDeVerificationFrames(session, page, logInitPhase) {
     // Explicit HF_DE_VERIFY wins; otherwise the session's own sample count
     // (raised by the parallel coordinator for multi-worker DE), then default 4.
     const kRaw = Number(process.env.HF_DE_VERIFY ?? session.options.deVerifySamples ?? "4");
@@ -4283,6 +4386,7 @@ export function getCapturePerfSummary(session) {
         chromeGpuProcessSeenLastSample: session.chromeMemory?.stats().gpuProcessSeenLastSample,
         chromeMemorySamples: session.chromeMemory?.stats().samples,
         deGateReason: session.deGateReason,
+        motionBlur: session.pageMotionBlur,
         deFallbackTrigger: session.deFallbackTrigger,
         deWorkerEncode: session.workerEncodeEnabled ?? false,
         deVerifyArmed: session.deVerifyFrames?.size ?? 0,

package/dist/services/pageMotionBlur.d.ts

@@ -4,9 +4,14 @@
  * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
  */
 import type { Page } from "puppeteer-core";
-import type { CaptureOptions } from "../types.js";
+import type { CaptureOptions, PageMotionBlurSummary } from "../types.js";
 export declare function installPageMotionBlur(page: Pick<Page, "evaluateOnNewDocument">, options: Pick<CaptureOptions, "motionBlur" | "pageMotionBlur" | "deviceScaleFactor">): Promise<void>;
+export type RecordPageMotionBlur = (summary: PageMotionBlurSummary) => void;
+/** Keeps one summary object per session, updated in place, so a perf summary that holds it sees the session's last read. */
+export declare function pageMotionBlurRecorder(session: {
+    pageMotionBlur?: PageMotionBlurSummary;
+}): RecordPageMotionBlur;
 /** One line saying what the page's blur did for this session; null when the page never asked for blur. */
-export declare function describePageMotionBlur(page: Pick<Page, "evaluate">): Promise<string | null>;
+export declare function describePageMotionBlur(page: Pick<Page, "evaluate">, record?: RecordPageMotionBlur): Promise<string | null>;
 /** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
-export declare function describePageMotionBlurAtEnd(page: Pick<Page, "evaluate">, timeoutMs?: number): Promise<string | null>;
+export declare function describePageMotionBlurAtEnd(page: Pick<Page, "evaluate">, timeoutMs?: number, record?: RecordPageMotionBlur): Promise<string | null>;

package/dist/services/pageMotionBlur.js

@@ -3,7 +3,7 @@
  * its scripts run: when the engine blurs (it would average frames that are already blurred) or
  * when the render must match a Studio preview that could not blur (`pageMotionBlur: "off"`).
  */
-import { PAGE_DEVICE_SCALE_GLOBAL, PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, } from "@hyperframes/core";
+import { MOTION_BLUR_FINGERPRINT_FIELDS, PAGE_DEVICE_SCALE_GLOBAL, PAGE_MOTION_BLUR_OFF_GLOBAL, acceleratedCanvasTrackerSource, } from "@hyperframes/core";
 function pageOffReason(options) {
     if (options.motionBlur)
         return "engine-motion-blur";
@@ -26,37 +26,84 @@ export async function installPageMotionBlur(page, options) {
         window[key] = v;
     }, PAGE_MOTION_BLUR_OFF_GLOBAL, off);
 }
+function parseFingerprint(raw) {
+    if (!raw || typeof raw !== "object")
+        return null;
+    const count = (field) => Number(Reflect.get(raw, field)) || 0;
+    return Object.fromEntries(MOTION_BLUR_FINGERPRINT_FIELDS.map((field) => [field, count(field)]));
+}
 async function readPageMotionBlur(page) {
-    return page.evaluate(() => {
+    const read = await page.evaluate(() => {
         const api = Reflect.get(window, "__hfMotionBlur");
         const report = api && typeof api === "object" ? Reflect.get(api, "report") : null;
         const got = typeof report === "function" ? report() : null;
         if (!got || typeof got !== "object")
             return null;
         const tier = Reflect.get(got, "tier");
+        const reasonCode = Reflect.get(got, "reasonCode");
         return {
             state: String(Reflect.get(got, "state")),
-            code: String(Reflect.get(got, "reasonCode")),
+            reasonCode: typeof reasonCode === "string" ? reasonCode : null,
             movers: Number(Reflect.get(got, "movers")),
             failedFrames: Number(Reflect.get(got, "failedFrames")) || 0,
             tier: typeof tier === "string" ? tier : null,
+            readEvents: Reflect.get(got, "readEvents") === true,
+            fingerprint: Reflect.get(got, "fingerprint"),
         };
     });
+    return read && { ...read, fingerprint: parseFingerprint(read.fingerprint) };
+}
+function fingerprintCounts(fingerprint) {
+    if (!fingerprint)
+        return "";
+    return MOTION_BLUR_FINGERPRINT_FIELDS.filter((field) => fingerprint[field] > 0)
+        .map((field) => `${field}:${fingerprint[field]}`)
+        .join(",");
+}
+const formatPageMotionBlur = (r) => {
+    const counts = fingerprintCounts(r.fingerprint);
+    return (`[motion-blur] ${r.state} reasonCode=${r.reasonCode} movers=${r.movers} failedFrames=${r.failedFrames}` +
+        `${r.tier ? ` tier=${r.tier}` : ""}${r.readEvents ? " readEvents=true" : ""}${counts ? ` fp=${counts}` : ""}`);
+};
+const summarize = (r) => ({
+    tier: r.tier === "capture" || r.tier === "filter" ? r.tier : null,
+    reasonCode: r.reasonCode,
+    movers: r.movers,
+    failedFrames: r.failedFrames,
+    readEvents: r.readEvents,
+    fingerprint: r.fingerprint,
+});
+/** Keeps one summary object per session, updated in place, so a perf summary that holds it sees the session's last read. */
+export function pageMotionBlurRecorder(session) {
+    return (next) => {
+        const held = session.pageMotionBlur;
+        if (!held) {
+            session.pageMotionBlur = next;
+            return;
+        }
+        Object.assign(held, next, {
+            tier: next.tier ?? held.tier,
+            fingerprint: next.fingerprint ?? held.fingerprint,
+        });
+    };
 }
-const formatPageMotionBlur = (r) => `[motion-blur] ${r.state} reasonCode=${r.code} movers=${r.movers} failedFrames=${r.failedFrames}${r.tier ? ` tier=${r.tier}` : ""}`;
 /** One line saying what the page's blur did for this session; null when the page never asked for blur. */
-export async function describePageMotionBlur(page) {
+export async function describePageMotionBlur(page, record) {
     const r = await readPageMotionBlur(page);
+    if (r)
+        record?.(summarize(r));
     return r && formatPageMotionBlur(r);
 }
 /** The session's closing line, only when frames fell back to plain DOM: the first-frame line cannot know. */
-export async function describePageMotionBlurAtEnd(page, timeoutMs = 1500) {
+export async function describePageMotionBlurAtEnd(page, timeoutMs = 1500, record) {
     let timer;
     const stuck = new Promise((resolve) => {
         timer = setTimeout(() => resolve(null), timeoutMs);
     });
     try {
         const r = await Promise.race([readPageMotionBlur(page), stuck]);
+        if (r)
+            record?.(summarize(r));
         return r && r.failedFrames > 0 ? `${formatPageMotionBlur(r)} (session end)` : null;
     }
     catch {

package/dist/services/parallelCoordinator.js

@@ -524,8 +524,21 @@ export function isFfmpegInfrastructureFailure(err) {
  * remaining frame unverified.
  */
 async function psnrForDiskSample(framePath, truth, workerId, idx) {
+    const skipSample = (err) => {
+        console.warn(`[Parallel] drawElement disk self-verify sample skipped (worker ${workerId}, ` +
+            `frame ${idx}): ${err instanceof Error ? err.message : String(err)}`);
+        return null;
+    };
+    // Read apart from the compare: a frame file's ENOENT says nothing about ffmpeg.
+    let frame;
     try {
-        return await psnrDb(await readFile(framePath), truth);
+        frame = await readFile(framePath);
+    }
+    catch (err) {
+        return skipSample(err);
+    }
+    try {
+        return await psnrDb(frame, truth);
     }
     catch (err) {
         if (isFfmpegInfrastructureFailure(err)) {
@@ -536,9 +549,7 @@ async function psnrForDiskSample(framePath, truth, workerId, idx) {
                 "hit this after a successful preflight, ffmpeg was replaced mid-render or " +
                 "HYPERFRAMES_FFMPEG_PATH now points at a different binary.", { cause: err });
         }
-        console.warn(`[Parallel] drawElement disk self-verify sample skipped (worker ${workerId}, ` +
-            `frame ${idx}): ${err instanceof Error ? err.message : String(err)}`);
-        return null;
+        return skipSample(err);
     }
 }
 // Branches are the gate conditions themselves (mode/armed/streaming guards +

package/dist/services/riskFrames.d.ts

@@ -18,12 +18,13 @@ interface ScanOptions {
     budgetMs?: number;
     now?: () => number;
     onProgress?: (scannedFrames: number, totalFrames: number) => void;
+    onEnd?: () => void;
 }
 /**
  * Frames where a recorded effect element shows. Seeks the page forward, so use a throwaway one.
  * Null once more than `maxFrames` frames qualify, or once the whole scan would take over `budgetMs`.
  */
-export declare function scanCssEffectLiveFrames(page: Page, fps: number, totalFrames: number, maxFrames: number, { budgetMs, now, onProgress }?: ScanOptions): Promise<Set<number> | null>;
+export declare function scanCssEffectLiveFrames(page: Page, fps: number, totalFrames: number, maxFrames: number, { budgetMs, now, onProgress, onEnd, }?: ScanOptions): Promise<Set<number> | null>;
 /**
  * The given frames with a one-frame margin, ranges closer than {@link RISK_RANGE_HYSTERESIS_FRAMES}
  * joined. Null when they cover more than {@link MAX_RISK_FRAME_FRACTION} of the render.

package/dist/services/riskFrames.js

@@ -61,7 +61,15 @@ function withinBudget(work, ms) {
  * Frames where a recorded effect element shows. Seeks the page forward, so use a throwaway one.
  * Null once more than `maxFrames` frames qualify, or once the whole scan would take over `budgetMs`.
  */
-export async function scanCssEffectLiveFrames(page, fps, totalFrames, maxFrames, { budgetMs = SCAN_BUDGET_MS, now = () => performance.now(), onProgress } = {}) {
+export async function scanCssEffectLiveFrames(page, fps, totalFrames, maxFrames, { budgetMs = SCAN_BUDGET_MS, now = () => performance.now(), onProgress = () => { }, onEnd, } = {}) {
+    try {
+        return await scanLiveFrames(page, fps, totalFrames, maxFrames, budgetMs, now, onProgress);
+    }
+    finally {
+        onEnd?.();
+    }
+}
+async function scanLiveFrames(page, fps, totalFrames, maxFrames, budgetMs, now, onProgress) {
     const live = new Set();
     const started = now();
     for (let from = 0; from < totalFrames && live.size <= maxFrames; from += SCAN_CHUNK_FRAMES) {
@@ -77,7 +85,7 @@ export async function scanCssEffectLiveFrames(page, fps, totalFrames, maxFrames,
         }
         for (const i of shown)
             live.add(from + i);
-        onProgress?.(to, totalFrames);
+        onProgress(to, totalFrames);
         const projectedMs = ((now() - started) / to) * totalFrames;
         if (to < totalFrames && projectedMs > budgetMs) {
             console.error(`[engine] fast capture: the effect scan of ${totalFrames} frames would take ` +

package/dist/services/videoFrameExtractor.js

@@ -506,9 +506,20 @@ export function parseImageElements(html) {
     return images;
 }
 const firstFrameColourCache = new Map();
-/** A source's SPS transfers, so a PQ or SDR keyframe keeps an HLG one at 100 nits; null when the read failed. */
+/** A source's SPS transfers, read as the trace streams (a run keeps only stderr's tail); null when the read failed. */
 function readKeyframeTransfers(videoPath, codec) {
-    return inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...keyframeTransferArgs(videoPath, codec)])).then((result) => (result.success ? parseKeyframeTransfers(result.stderr) : null));
+    let traced = "";
+    let rest = "";
+    const onStderr = (chunk) => {
+        const lines = (rest + chunk).split("\n");
+        rest = lines.pop() ?? "";
+        for (const line of lines)
+            if (line.includes("transfer_characteristics"))
+                traced += `${line}\n`;
+    };
+    return inExtractionSlot(() => runFfmpeg([...urlInputArgs(videoPath), ...keyframeTransferArgs(videoPath, codec)], {
+        onStderr,
+    })).then((result) => (result.success ? parseKeyframeTransfers(traced + rest) : null));
 }
 /** The first shown frame's colour tags (see {@link firstFrameColourArgs}), probed once per source file. */
 function readFirstFrameColour(videoPath, codec) {

package/dist/types.d.ts

@@ -6,11 +6,19 @@
  */
 import type { ReferenceBackground } from "./services/referenceBackground.js";
 import type { AudioFailureDiagnostic } from "./services/audioMixer.types.js";
-import type { Fps } from "@hyperframes/core";
+import type { Fps, MotionBlurFingerprint } from "@hyperframes/core";
 import type { CompositionLengthSource } from "@hyperframes/core/runtime/composition-length";
 import type { ChromeMemoryStats } from "./services/chromeMemorySampler.js";
 import type { MotionBlurOptions } from "./services/motionBlur.js";
 export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "distributed-render";
+export interface PageMotionBlurSummary {
+    tier: "capture" | "filter" | null;
+    reasonCode: string | null;
+    movers: number;
+    failedFrames: number;
+    readEvents: boolean;
+    fingerprint: MotionBlurFingerprint | null;
+}
 /**
  * Outcome of waiting for a sub-composition's GSAP timelines to register.
  * Threaded string-typed through `CapturePerfSummary` / `RenderPerfSummary` /
@@ -25,7 +33,7 @@ export interface SubTimelineWaitMemo {
     unregisteredIds?: readonly string[];
     loggedSceneCallbackErrors?: string[];
 }
-export type CaptureWarningCode = "media_readiness_timeout" | "media_load_failed" | "audio_processing_failed" | "sub_timeline_readiness_timeout" | "sub_timeline_script_failure" | "script_error_isolated" | "vfx_failure" | "live_map_detected";
+export type CaptureWarningCode = "media_readiness_timeout" | "media_load_failed" | "image_missing_from_frame" | "audio_processing_failed" | "sub_timeline_readiness_timeout" | "sub_timeline_script_failure" | "script_error_isolated" | "vfx_failure" | "live_map_detected";
 /** Structured correctness warning produced while preparing a capture session. */
 export interface CaptureWarning {
     code: CaptureWarningCode;
@@ -237,6 +245,7 @@ export interface CaptureOptions {
     deVerifySamples?: number;
     deFrameFallback?: boolean;
     onEffectScanProgress?: (scannedFrames: number, totalFrames: number) => void;
+    onEffectScanEnd?: () => void;
 }
 export interface CaptureVideoMetadataHint {
     id: string;
@@ -374,11 +383,12 @@ export interface CapturePerfSummary {
     chromeMemorySamples?: number;
     /**
      * Low-cardinality init-time gate that routed a drawElement-eligible session
-     * to the baseline: `swiftshader` | `css_effect:<fx>` | `at_risk_timeline` |
-     * `3d_init_failed` | `supersampling` | `render_mode_hint`. Undefined when
-     * drawElement ran or was never attempted.
+     * to the baseline: `swiftshader` | `webgl_unavailable` | `beginframe_no_self_verify` |
+     * `css_effect:<fx>` | `at_risk_timeline` | `3d_init_failed` | `supersampling` |
+     * `render_mode_hint`. Undefined when drawElement ran or was never attempted.
      */
     deGateReason?: string;
+    motionBlur?: PageMotionBlurSummary;
     /**
      * Full-fidelity fallback trigger — the specific reason (CSS FX + property,
      * e.g. `filter:blur`, `filter:drop-shadow`, `backdrop-filter`, `clip-path`,
@@ -413,5 +423,8 @@ export interface CapturePerfSummary {
 declare global {
     interface Window {
         __hf?: HfProtocol;
+        __HF_VIRTUAL_TIME__?: {
+            originalSetTimeout?: typeof setTimeout;
+        };
     }
 }

package/package.json

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