@hyperframes/engine 0.8.199 → 0.8.201

package/dist/services/frameCapture.js

@@ -9,7 +9,7 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
 import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
@@ -17,9 +17,11 @@ import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERT
 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, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
-import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
+import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
+import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
+import { getAvailableMemoryMb } from "./systemMemory.js";
 import { isPsnrFilterAvailable } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG, applyConcreteGpuScreenshotClamp } from "../config.js";
 import { cloneCaptureWarnings } from "./captureWarning.js";
@@ -472,20 +474,20 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
     if ((session.config?.useDrawElement ?? false) && supersampling) {
         session.deGateReason = "supersampling";
         session.deFallbackTrigger = "supersampling";
-        console.log("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
+        console.error("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
             "ignores deviceScaleFactor, so scaled (DPR other than 1) output uses screenshot capture.");
     }
     if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
         session.deGateReason = "render_mode_hint";
         session.deFallbackTrigger = "render_mode_hint";
-        console.log("[engine] fast capture falls back to screenshot: render-mode compatibility " +
+        console.error("[engine] fast capture falls back to screenshot: render-mode compatibility " +
             "hint forced screenshot capture (e.g. raw requestAnimationFrame composition).");
     }
     if (useDrawElement) {
         const gpuBackend = await detectGpuBackend(page);
         session.isSwiftShader = gpuBackend.isSwiftShader;
         session.gpuRenderer = classifyGpuRenderer(gpuBackend.renderer);
-        const transparent = session.options.format === "png";
+        const transparent = capturesAlpha(session.options);
         async function routeToFallback() {
             session.captureMode = session.launchCaptureMode;
             if (transparent) {
@@ -526,7 +528,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         if (!supportsDrawElement) {
             session.deGateReason = "unsupported_chrome";
             session.deFallbackTrigger = "unsupported_chrome";
-            console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+            console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
                 "this Chrome build does not implement canvas.drawElementImage (Dev/Canary-only " +
                 "feature); run `hyperframes browser ensure --force` to fetch a supported " +
                 "build, or set HYPERFRAMES_BROWSER_PATH to one.");
@@ -574,7 +576,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             // "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.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+            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)");
             await routeToFallback();
@@ -585,18 +587,37 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             // path — drawElementImage can't reproduce either, producing 18–49 dB
             // damaged frames (community eval). Fall back to the platform baseline.
             // HF_FAST_CAPTURE_CSSFX=true bypasses for R&D.
+            // Frames this render captures by screenshot instead (see CaptureSession.deRiskFrames);
+            // only a session whose caller can hand them over (worker-encode pipeline) may keep drawElement.
+            const perFrame = session.options.deFrameFallback === true &&
+                drawElementWorkerEncodeEligible(session, transparent) &&
+                !forceDE;
+            const riskFrames = new Set();
+            const riskReasons = [];
+            let cssFrames = 0;
+            const routeWholeRender = async (reason, trigger, message) => {
+                session.deGateReason = reason;
+                session.deFallbackTrigger = trigger;
+                console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ${message}`);
+                await routeToFallback();
+            };
             if (!forceDE && process.env.HF_FAST_CAPTURE_CSSFX !== "true") {
-                const cssFx = await detectCssEffectRisk(page);
+                const cssFx = (await scanCssEffects(page, false)).reason;
                 if (cssFx) {
-                    session.deGateReason = `css_effect:${(cssFx.split(":")[0] ?? "").replace(/[^a-z-]/gi, "")}`;
-                    // Full specific effect from `detectCssEffectRisk` (e.g. "filter:blur",
+                    // Full specific effect from `scanCssEffects` (e.g. "filter:blur",
                     // "mix-blend-mode", "webgl-context") — `deGateReason` keeps its
                     // low-cardinality prefix, `deFallbackTrigger` the full value.
-                    session.deFallbackTrigger = cssFx;
-                    console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
-                        `${cssFx} detected (drawElementImage cannot reproduce it; see fast-capture-limitations.md)`);
-                    await routeToFallback();
-                    return;
+                    const gateReason = `css_effect:${(cssFx.split(":")[0] ?? "").replace(/[^a-z-]/gi, "")}`;
+                    const gateMessage = `${cssFx} detected (drawElementImage cannot reproduce it; see fast-capture-limitations.md)`;
+                    cssFrames = perFrame ? await renderFrameCount(session, page) : 0;
+                    const live = cssFrames > 0 ? await cssEffectRiskFrames(session, cssFrames) : null;
+                    if (!live) {
+                        await routeWholeRender(gateReason, cssFx, gateMessage);
+                        return;
+                    }
+                    for (const f of live)
+                        riskFrames.add(f);
+                    riskReasons.push(cssFx);
                 }
             }
             // Lim 7: timeline-interval at-risk predictor. Walk window.__timelines and
@@ -622,15 +643,36 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
                 const fractionFloor = Number(process.env.HF_FAST_CAPTURE_INTERVAL_FRACTION ?? "0");
                 logInitPhase(`timeline at-risk predictor: ${atRisk.size}/${totalFrames} frames (${Math.round(atRiskFraction * 100)}%)`);
                 if (atRisk.size > 0 && atRiskFraction > fractionFloor) {
-                    session.deGateReason = "at_risk_timeline";
-                    session.deFallbackTrigger = "at_risk_timeline";
-                    console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
-                        `${atRisk.size}/${totalFrames} frames animate a compositor-incompatible prop ` +
-                        `(blend/3D/clip/mask); drawElementImage drops these mid-animation ` +
-                        `(deterministic timeline gate; see fast-capture-limitations.md Lim 7)`);
-                    await routeToFallback();
+                    if (perFrame) {
+                        for (const f of atRisk)
+                            riskFrames.add(f);
+                        riskReasons.push("at_risk_timeline");
+                    }
+                    else {
+                        await routeWholeRender("at_risk_timeline", "at_risk_timeline", `${atRisk.size}/${totalFrames} frames animate a compositor-incompatible prop ` +
+                            `(blend/3D/clip/mask); drawElementImage drops these mid-animation ` +
+                            `(deterministic timeline gate; see fast-capture-limitations.md Lim 7)`);
+                        return;
+                    }
+                }
+            }
+            if (riskFrames.size > 0) {
+                const total = cssFrames > 0 ? cssFrames : await renderFrameCount(session, page);
+                const plan = total > 0 ? planRiskFrames(riskFrames, total) : null;
+                if (!plan) {
+                    await routeWholeRender("risk_frames", riskReasons.join("+"), `${riskFrames.size}/${total} frames need screenshot capture (${riskReasons.join(", ")}), ` +
+                        `too many to keep fast capture for the rest`);
+                    return;
+                }
+                if (!riskSessionFits(getAvailableMemoryMb(), session.options.width * session.options.height)) {
+                    await routeWholeRender("risk_session_memory", riskReasons.join("+"), `${plan.size} frames need screenshot capture (${riskReasons.join(", ")}) but too little ` +
+                        `memory is available for per-frame capture`);
                     return;
                 }
+                session.deRiskFrames = plan;
+                session.deRiskReason = riskReasons.join("+");
+                logInitPhase(`fast capture keeps ${total - plan.size}/${total} frames; ${plan.size} frame(s) ` +
+                    `capture by screenshot (${session.deRiskReason})`);
             }
             // Rewrite CSS 3D contexts into WebGL-projected canvases BEFORE the
             // layoutsubtree canvas goes in (rects are measured in normal layout).
@@ -640,7 +682,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             if (!forceDE && !threeD.ok) {
                 session.deGateReason = "3d_init_failed";
                 session.deFallbackTrigger = "3d_init_failed";
-                console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+                console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
                     `3D projection init failed (${threeD.reason ?? "unknown"})`);
                 await routeToFallback();
                 return;
@@ -653,6 +695,10 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             // passed) and the DOM is still normal (canvas not yet injected, so the
             // verification screenshots are valid). drawElement-path only; see armStaticDedup.
             await armStaticDedup(session, page, logInitPhase);
+            // A static frame reuses the previous drawElement capture; a risk frame is captured by
+            // another session, so its neighbours must not reuse across it.
+            for (const f of session.deRiskFrames ?? [])
+                session.staticFrames?.delete(f);
             // Video comps on injector-less sessions (probe sessions initialize before
             // video extraction) DEFER the rest of the drawElement init: ground-truth
             // screenshots would capture black <video> boxes, and once the canvas is
@@ -669,10 +715,53 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             await finalizeDrawElementInit(session, page, logInitPhase, { transparent, forceDE });
         }
     }
-    else if (session.options.format === "png") {
+    else if (capturesAlpha(session.options)) {
         await initTransparentBackground(session.page);
     }
 }
+/** Worker-encode pipeline: macOS hardware GPU path only, JPEG output only. */
+function drawElementWorkerEncodeEligible(session, transparent) {
+    return ((session.config?.enableDrawElementWorkerEncode ?? false) &&
+        !transparent &&
+        session.beginFrameTimeTicks === 0);
+}
+/**
+ * The frames a CSS effect shows on, or null when it cannot be bounded. Scans in a throwaway
+ * session: the scan seeks the timeline end to end, which this page's render must not inherit.
+ */
+async function cssEffectRiskFrames(session, totalFrames) {
+    let scratch = null;
+    try {
+        scratch = await createCaptureSession(session.serverUrl, session.outputDir, { ...session.options, onMemorySample: undefined }, null, {
+            ...session.config,
+            useDrawElement: false,
+            staticFrameDedup: false,
+            enableBrowserPool: false,
+        });
+        await initializeSession(scratch);
+        const scan = await scanCssEffects(scratch.page, true);
+        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);
+        return live && withFramesAfterCallback(live, scan.callbackFrom, fps, totalFrames);
+    }
+    catch (error) {
+        console.error(`[engine] fast capture: effect scan failed (${error instanceof Error ? error.message : String(error)})`);
+        return null;
+    }
+    finally {
+        if (scratch)
+            await closeCaptureSession(scratch).catch(() => { });
+    }
+}
+/** Frames the render will capture, from the producer's duration when it set one. */
+async function renderFrameCount(session, page) {
+    const duration = session.options.compositionDurationSeconds ??
+        (await page.evaluate(() => window.__hf?.duration ?? 0));
+    const total = Math.ceil(duration * fpsToNumber(session.options.fps));
+    return isStaticDedupFrameAnalysisSafe(total) ? total : 0;
+}
 /**
  * The tail of drawElement init: self-verification ground truth (pre-injection),
  * canvas injection, capture-mode flip, clip-boundary predictor, worker-encode.
@@ -712,9 +801,7 @@ async function finalizeDrawElementInit(session, page, logInitPhase, opts) {
     // Worker-encode pipeline: macOS hardware GPU path only (syncToPaintEvent=true,
     // beginFrameTimeTicks=0). Skip for BeginFrame (Linux/Docker) and transparent
     // (PNG) output — those use the existing synchronous path unchanged.
-    const workerEncodeEnabled = (session.config?.enableDrawElementWorkerEncode ?? false) &&
-        !transparent &&
-        session.beginFrameTimeTicks === 0;
+    const workerEncodeEnabled = drawElementWorkerEncodeEligible(session, transparent);
     if (workerEncodeEnabled) {
         await initDrawElementWorkerEncode(page);
         session.workerEncodeEnabled = true;
@@ -730,13 +817,23 @@ export async function completeDeferredDrawElementInit(session) {
     if (!session.deInitDeferred || !session.onBeforeCapture)
         return;
     const page = session.page;
-    const logInitPhase = (phase) => console.log(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
+    const logInitPhase = (phase) => console.error(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
     await finalizeDrawElementInit(session, page, logInitPhase, {
-        transparent: session.options.format === "png",
+        transparent: capturesAlpha(session.options),
         forceDE: process.env.HF_FORCE_DRAWELEMENT === "1",
     });
     session.deInitDeferred = false;
 }
+/**
+ * Media elements are addressed by a document-unique render id, not by the per-file element id.
+ * Installed before any page script runs, on the render page and the self-check's truth page alike.
+ */
+async function installMediaPageHooks(page, options) {
+    await installMediaRenderIdBridge(page);
+    if (options.skipReadinessVideoIds?.length) {
+        await page.evaluateOnNewDocument(holdRenderFrameVideos, options.skipReadinessVideoIds, MEDIA_RENDER_ID_ATTR);
+    }
+}
 // fallow-ignore-next-line unit-size
 export async function createCaptureSession(serverUrl, outputDir, options, onBeforeCapture = null, config) {
     if (!existsSync(outputDir))
@@ -755,7 +852,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     const isLinux = process.platform === "linux";
     const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
     const useDrawElement = config?.useDrawElement ?? false;
-    const drawElementTransparent = useDrawElement && options.format === "png";
+    const drawElementTransparent = useDrawElement && capturesAlpha(options);
     // drawElement and page-side shader compositing are mutually incompatible
     // capture strategies: drawElement reads the composition root's paint records
     // directly and skips the prepare→micro-screenshot→resolve protocol (the
@@ -903,12 +1000,7 @@ async function constructCaptureSession(input) {
             w.__name = (fn, _name) => fn;
         }
     });
-    // Media elements are addressed by a document-unique render id, not by the
-    // per-file element id. Install the resolvers before any page script runs.
-    await installMediaRenderIdBridge(page);
-    if (options.skipReadinessVideoIds?.length) {
-        await page.evaluateOnNewDocument(holdRenderFrameVideos, options.skipReadinessVideoIds, MEDIA_RENDER_ID_ATTR);
-    }
+    await installMediaPageHooks(page, options);
     // 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
@@ -1693,6 +1785,16 @@ function recordConsoleScriptError(session, error) {
     const message = new VfxFailureError(error).message;
     recordCaptureWarnings(session, [{ code: "vfx_failure", message, details: { sources: [error] } }]);
 }
+// Every worker page hits the same scene callback error; the render log names it once.
+function loggedEarlierInRender(session, text) {
+    if (!text.startsWith(SCENE_CALLBACK_ERROR_PREFIX))
+        return false;
+    const logged = (session.subTimelineWaitMemo.loggedSceneCallbackErrors ??= []);
+    if (logged.includes(text))
+        return true;
+    logged.push(text);
+    return false;
+}
 function recordPageError(session, error) {
     if (error && !session.pageErrors.includes(error))
         session.pageErrors.push(error);
@@ -1747,14 +1849,15 @@ export function classifyPageError(details, projectScripts) {
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
     // Forward browser console to host. HyperFrames runtime logs get a dedicated
-    // prefix so page-context observability is visible in producer stdout.
+    // prefix so page-context observability is visible in producer stderr.
     page.on("console", (msg) => {
         const type = msg.type();
         const text = msg.text();
         const locationUrl = msg.location()?.url ?? "";
         const diagnostic = formatConsoleDiagnostic(type, text, locationUrl);
-        if (!diagnostic.suppressHostLog)
-            console.log(diagnostic.text);
+        if (!diagnostic.suppressHostLog && !loggedEarlierInRender(session, text)) {
+            console.error(diagnostic.text);
+        }
         appendBrowserDiagnostic(session, diagnostic.text);
         // A blocked script can never register its timeline (#3352); a thrown one may still, so it only counts on timeout.
         const scriptFailure = classifyConsoleScriptFailure(type, text);
@@ -1818,7 +1921,7 @@ export async function initializeSession(session) {
     const pageNavigationTimeout = session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
     const initStart = Date.now();
     const logInitPhase = (phase) => {
-        console.log(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
+        console.error(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
     };
     const gotoEntryPage = async () => {
         appendBrowserDiagnostic(session, formatNavigationStartDiagnostic({
@@ -2538,6 +2641,7 @@ export async function createStaticVerificationPage(session) {
                 w.__name = (fn, _name) => fn;
             }
         });
+        await installMediaPageHooks(page, session.options);
         if (session.options.variables && Object.keys(session.options.variables).length > 0) {
             const variablesJson = JSON.stringify(session.options.variables);
             await page.evaluateOnNewDocument((json) => {
@@ -2569,7 +2673,7 @@ export async function createStaticVerificationPage(session) {
             page.evaluate(`document.fonts?.ready`),
             waitForOptionalTailwindReady(page, pageReadyTimeout),
         ]);
-        if (session.options.format === "png")
+        if (capturesAlpha(session.options))
             await initTransparentBackground(page);
         return page;
     }
@@ -3046,6 +3150,15 @@ async function redrawDrawElementFrame(session, frameIndex, time, seekOptions, he
     await prepareFrameForCapture(session, frameIndex, time, seekOptions, heldVideoTime);
     return captureDrawElementFrame(page, options.width, options.height, options.format ?? "jpeg", options.quality ?? 80, true);
 }
+/**
+ * Fails the attempt on a frame in {@link CaptureSession.deRiskFrames}. Callers that hand those
+ * frames to a screenshot session never reach it; any other caller restarts by screenshot.
+ */
+function assertNotRiskFrame(session, frameIndex) {
+    if (session.deRiskFrames?.has(frameIndex)) {
+        throw new DrawElementCaptureError(frameIndex, "frame needs screenshot capture, which this capture path cannot hand over");
+    }
+}
 /** Seek to `time` and capture one surface with the session's capture mode. */
 async function captureFrameSurface(session, frameIndex, time, seekOptions, heldVideoTime) {
     const { page, options } = session;
@@ -3078,6 +3191,7 @@ async function captureFrameSurface(session, frameIndex, time, seekOptions, heldV
         throw new DrawElementCaptureError(frameIndex, "boundary screenshot requested on an injected canvas page");
     }
     else if (session.captureMode === "drawelement") {
+        assertNotRiskFrame(session, frameIndex);
         // Advance compositor state via BeginFrame when available (Linux headless-shell);
         // on macOS the compositor advances naturally without BeginFrame.
         if (session.beginFrameTimeTicks > 0) {
@@ -3263,6 +3377,13 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
         ...totals,
     };
 }
+function framesAreStatic(staticFrames, from, to) {
+    for (let frame = from; frame <= to; frame++) {
+        if (!staticFrames.has(frame))
+            return false;
+    }
+    return true;
+}
 async function captureFrameCore(session, frameIndex, time) {
     const { options } = session;
     const startTime = Date.now();
@@ -3283,7 +3404,8 @@ async function captureFrameCore(session, frameIndex, time) {
     const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
     if (session.staticFrames?.has(absFrameIndex) &&
         session.lastFrameBuffer &&
-        session.lastFrameAbsoluteIndex === absFrameIndex - 1 &&
+        session.lastFrameAbsoluteIndex !== undefined &&
+        framesAreStatic(session.staticFrames, session.lastFrameAbsoluteIndex + 1, absFrameIndex) &&
         (!session.motionBlur ||
             motionBlurWindowIsStatic(session.motionBlur, absFrameIndex, session.staticFrames))) {
         session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
@@ -3311,7 +3433,7 @@ async function captureFrameCore(session, frameIndex, time) {
         if (session.capturePerf.frames === 1) {
             const blur = await describePageMotionBlur(session.page).catch(() => null);
             if (blur)
-                console.log(blur);
+                console.error(blur);
         }
         // Retain this freshly-captured buffer so the following static frames can reuse it.
         if (session.staticFrames) {
@@ -3370,7 +3492,7 @@ export async function captureFrameToBuffer(session, frameIndex, time) {
             // works. Counted here rather than in captureFrameCore's catch: the
             // deadline rejects from outside it, so that catch never runs.
             session.deFrameTimeouts = (session.deFrameTimeouts ?? 0) + 1;
-            console.log(`[engine] fast capture frame ${frameIndex}: capture exceeded ` +
+            console.error(`[engine] fast capture frame ${frameIndex}: capture exceeded ` +
                 `${DE_FRAME_TIMEOUT_MS}ms; renderer stalled after drawElementImage ` +
                 `(PRINFRA-488). Failing the drawElement attempt so the whole render ` +
                 `retries via screenshot.`);
@@ -3403,6 +3525,7 @@ export async function captureFrameToBuffer(session, frameIndex, time) {
 export async function captureFrameToBufferPipelined(session, frameIndex, time) {
     const { page, options } = session;
     const startTime = Date.now();
+    assertNotRiskFrame(session, frameIndex);
     // Task B: static-frame dedup (worker path). Reuse the prior frame's encode result
     // and skip the seek + drawElement + encode entirely. Same predicate as the serial
     // path; clip-cut frames are excluded from staticFrames so they always capture.
@@ -3412,13 +3535,7 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
         // same pixels. Sequential capture reduces to has(i) (gap = {i}); the
         // interleaved parallel stride makes the gap N frames wide.
         const lastIdx = session.lastEncodeResultFrame ?? frameIndex - 1;
-        let gapStatic = true;
-        for (let j = lastIdx + 1; j <= frameIndex; j++) {
-            if (!session.staticFrames.has(j)) {
-                gapStatic = false;
-                break;
-            }
-        }
+        const gapStatic = framesAreStatic(session.staticFrames, lastIdx + 1, frameIndex);
         if (gapStatic) {
             session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
             session.capturePerf.frames += 1;
@@ -3527,6 +3644,8 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
         throw new Error("[FrameCapture] Session not initialized");
     }
     assertVfxIntact(session);
+    for (const frameIndex of frameIndices)
+        assertNotRiskFrame(session, frameIndex);
     const startTime = Date.now();
     const fps = fpsToNumber(options.fps);
     const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
@@ -3572,7 +3691,7 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
             throw new DrawElementCaptureError(frameIndices[failedAt] ?? failedAt, reason, error);
         }
         else {
-            console.log(`[engine] fast capture: batch produce failed at frame ` +
+            console.error(`[engine] fast capture: batch produce failed at frame ` +
                 `${frameIndices[failedAt] ?? "?"} (${error ?? "?"}); ` +
                 `re-capturing ${frameIndices.length - failedAt} frame(s) per-frame`);
             for (let i = failedAt; i < frameIndices.length; i++) {
@@ -3651,7 +3770,7 @@ export async function closeCaptureSession(session) {
     if (session.page && !session.pageReleased) {
         const blur = await describePageMotionBlurAtEnd(session.page);
         if (blur)
-            console.log(blur);
+            console.error(blur);
     }
     // Realized static-dedup telemetry: how much the cache actually helped this
     // render (vs the prediction logged at arm time). Both capture paths
@@ -3664,7 +3783,7 @@ export async function closeCaptureSession(session) {
         const total = captured + reused;
         const pct = total > 0 ? Math.round((reused / total) * 100) : 0;
         const avgTotalMs = captured > 0 ? Math.round(session.capturePerf.totalMs / captured) : 0;
-        console.log(`[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
+        console.error(`[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
             `est. ~${reused * avgTotalMs}ms saved (avg ${avgTotalMs}ms/frame)`);
         session.staticDedupCount = 0;
     }
@@ -3827,9 +3946,10 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
     // would share the corruption, PSNR would pass on the damaged output.
     // Seeking 0 → ascending reproduces the render's own seek order.
     const fractions = computeDeVerifySampleFractions(k);
-    // A video-free comp reads its truth on a disposable page: callbacks that run there
-    // cannot leave the render's own page changed. The video injector is tied to the render page.
-    const disposable = session.onBeforeCapture
+    // The truth is read on a disposable page, so callbacks that run there cannot change the render's
+    // own page. A video comp needs an injector of its own for it (the render's tracks its page).
+    const truthInjector = session.onBeforeCapture?.fresh?.() ?? null;
+    const disposable = session.onBeforeCapture && truthInjector === null
         ? null
         : await createStaticVerificationPage(session).catch(() => {
             logInitPhase("self-verify truth page unavailable; reading it on the render page");
@@ -3837,6 +3957,9 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
         });
     const isolated = disposable !== null;
     const truthPage = disposable ?? page;
+    const injectFrames = isolated
+        ? (truthInjector ?? session.onBeforeCapture)
+        : session.onBeforeCapture;
     const seekTo = (t) => seekDeVerifyTruth(truthPage, t, !isolated);
     const frames = new Map();
     try {
@@ -3848,9 +3971,10 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
             // Nudge off clip-cut boundaries (±1-frame desync is legitimate there);
             // if the nudge saturates on a boundary index, skip the sample entirely.
             let guard = 0;
-            while (boundary.has(idx) && guard++ < 6)
+            const skip = (i) => boundary.has(i) || session.deRiskFrames?.has(i) === true;
+            while (skip(idx) && guard++ < 6)
                 idx = Math.min(totalFrames - 1, idx + 2);
-            if (boundary.has(idx))
+            if (skip(idx))
                 continue;
             if (frames.has(idx))
                 continue;
@@ -3859,8 +3983,7 @@ async function captureDeVerificationFrames(session, page, logInitPhase) {
             // Video frame injection (same hook the real capture paths run) — without
             // it, <video> elements screenshot black and every video comp would
             // false-positive into the screenshot fallback.
-            if (session.onBeforeCapture)
-                await session.onBeforeCapture(truthPage, t);
+            await injectFrames?.(truthPage, t);
             // The first screenshot forces a frame, which runs rAF-driven callbacks (a count-up lands
             // a tick after seek()); waiting on rAF via evaluate deadlocks, headless fires it only
             // when a frame is produced.
@@ -3960,6 +4083,7 @@ export function getCapturePerfSummary(session) {
         deVerifyArmed: session.deVerifyFrames?.size ?? 0,
         deVerifyInitMs: session.deVerifyInitMs ?? 0,
         deBoundaryFrames: session.clipBoundaryFrames?.size ?? 0,
+        deRiskFrames: session.deRiskFrames?.size ?? 0,
         deNcprFallbacks: ncprFallbacks,
         deFrameTimeouts: session.deFrameTimeouts ?? 0,
     };

package/dist/services/parallelCoordinator.js

@@ -358,7 +358,7 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
                 throw new Error("Parallel worker cancelled");
             const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
             if (dbg && i < task.startFrame + dbgWin) {
-                console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} start`);
+                console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} start`);
             }
             const { encodeResult } = await runCaptureOperation("frame_capture", i, () => captureFrameToBufferPipelined(session, i - outputOffset, time));
             // Marks the promise "handled" for Node's unhandled-rejection detector
@@ -368,19 +368,19 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
             // and would otherwise surface as an unhandled rejection during teardown.
             encodeResult.catch(() => { });
             if (dbg && i < task.startFrame + dbgWin) {
-                console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} kicked`);
+                console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} kicked`);
             }
             if (prev) {
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} await-encode`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} await-encode`);
                 }
                 const buf = await awaitEncode(prev.idx, prev.encodeResult);
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} encoded ${buf.length}B`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} encoded ${buf.length}B`);
                 }
                 await onFrameBuffer(prev.idx, buf, session);
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} written`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} written`);
                 }
                 framesCaptured++;
                 if (onFrameCaptured)
@@ -453,7 +453,7 @@ export function selectVerifySampleIndicesForTask(sampleIndices, task) {
 /** HF_DE_PAR_DEBUG=1 gated per-worker trace line (message built lazily). */
 function logParDebug(message) {
     if (process.env.HF_DE_PAR_DEBUG === "1")
-        console.log(message());
+        console.error(message());
 }
 /**
  * Throw the verification error for a sample below the PSNR floor; log the
@@ -466,7 +466,7 @@ function assertDiskSampleAboveFloor(db, verifyMinDb, idx, workerId) {
         throw new DrawElementVerificationError(`drawElement self-verify failed at frame ${idx} (disk path, worker ${workerId}): ` +
             `${db.toFixed(1)}dB < ${verifyMinDb}dB vs pre-injection screenshot`, { kind: "psnr", frameIndex: idx, failedDb: db, verifyThresholdDb: verifyMinDb });
     }
-    console.log(`[Parallel] drawElement disk self-verify passed (worker ${workerId}, frame ${idx}, ` +
+    console.error(`[Parallel] drawElement disk self-verify passed (worker ${workerId}, frame ${idx}, ` +
         `${db === Infinity ? "inf" : db.toFixed(1)}dB)`);
 }
 /**
@@ -760,9 +760,11 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
     };
     const parallel = tasks.length > 1;
     const deVerifySamples = resolveParallelDeVerifySamples(captureOptions.deVerifySamples, tasks.length);
-    const workerCaptureOptions = deVerifySamples === captureOptions.deVerifySamples
-        ? captureOptions
-        : { ...captureOptions, deVerifySamples };
+    const workerCaptureOptions = {
+        ...captureOptions,
+        deVerifySamples,
+        deFrameFallback: false,
+    };
     const peerController = new AbortController();
     const workerSignal = signal
         ? AbortSignal.any([signal, peerController.signal])

package/dist/services/riskFrames.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Which frames drawElement capture cannot reproduce, so those frames alone are captured by
+ * screenshot and the rest keep the fast path.
+ */
+import type { Page } from "puppeteer-core";
+/**
+ * Above this share of risk frames the second browser and the switching cost outweigh the fast
+ * frames, so the whole render captures by screenshot as it always has.
+ */
+export declare const MAX_RISK_FRAME_FRACTION = 0.6;
+/** Peak memory per-frame capture adds over a screenshot render at 1080p: 1002 to 2001 MB measured. */
+export declare const RISK_RENDER_ADDED_BYTES = 1000000000;
+/** Memory that must still be available once the screenshot browser is open. */
+export declare const RISK_RENDER_HEADROOM_BYTES = 1500000000;
+/** Risk ranges closer than this many frames are joined, so capture never alternates modes. */
+export declare const RISK_RANGE_HYSTERESIS_FRAMES = 12;
+/**
+ * Frames where a recorded effect element shows. Seeks the page forward, so use a throwaway one.
+ * Null once more than `maxFrames` frames qualify.
+ */
+export declare function scanCssEffectLiveFrames(page: Page, fps: number, totalFrames: number, maxFrames: number): 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.
+ */
+export declare function planRiskFrames(frames: Iterable<number>, totalFrames: number): Set<number> | null;
+/** `live` plus every frame from just before the first callback to the end of the render. */
+export declare function withFramesAfterCallback(live: Set<number>, callbackFrom: number | null, fps: number, totalFrames: number): Set<number>;
+/** Whether the render fits: what it adds, scaled by output pixels, leaves the headroom. */
+export declare function riskSessionFits(availableMb: number, outputPixels: number): boolean;