@hyperframes/engine 0.7.37 → 0.7.38

package/dist/services/frameCapture.js

@@ -1,4 +1,4 @@
-// fallow-ignore-file complexity
+// fallow-ignore-file complexity code-duplication
 /**
  * Frame Capture Service
  *
@@ -13,7 +13,36 @@ import { quantizeTimeToFrame, fpsToNumber } from "@hyperframes/core";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, resolveHeadlessShellPath, } from "./browserManager.js";
 import { beginFrameCapture, getCdpSession, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { detectSwiftShader, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, } from "./drawElementService.js";
+import { initThreeDProjection, detectCssEffectRisk } from "./threeDProjection.js";
 import { DEFAULT_CONFIG } from "../config.js";
+/**
+ * drawElement self-verification failure — a captured DE frame diverged from its
+ * pre-injection screenshot ground truth (or a blank frame survived a retry).
+ * The orchestrator catches this and re-renders the whole job with
+ * forceScreenshot. Discriminant-based guard (not instanceof) so it survives
+ * duplicated module instances across package boundaries.
+ */
+export class DrawElementVerificationError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "DrawElementVerificationError";
+        // Discriminant property, assigned dynamically: isDrawElementVerificationError
+        // reads it structurally so detection survives duplicated module instances
+        // across package boundaries (where instanceof fails).
+        this.deVerificationFailure = true;
+    }
+}
+export function isDrawElementVerificationError(err) {
+    // Walk the cause chain — the producer wraps capture errors (CaptureStageError).
+    let e = err;
+    for (let depth = 0; depth < 5 && typeof e === "object" && e !== null; depth++) {
+        if (e.deVerificationFailure === true)
+            return true;
+        e = e.cause;
+    }
+    return false;
+}
 // Circular buffer for browser console messages dumped on render failure diagnostics.
 // Complex compositions produce 100+ messages; 50 was too small to capture relevant errors.
 const BROWSER_CONSOLE_BUFFER_SIZE = 200;
@@ -167,6 +196,225 @@ async function waitForCloseWithTimeout(promise) {
         clearTimeout(timer);
     return !timedOut;
 }
+/**
+ * Post-readiness capture-surface init, shared by the screenshot and BeginFrame
+ * init paths (called after the page is fully ready). When `useDrawElement` is
+ * set, detect SwiftShader and route: transparent+SwiftShader falls back to
+ * screenshot capture (the drawElement transparent path is broken on SwiftShader),
+ * everything else injects the drawElement canvas and switches to "drawelement"
+ * mode. Otherwise, for PNG output, force a transparent page background so the
+ * screenshots carry a real alpha channel (Chrome resets the override on every
+ * navigation, so this must run after page load).
+ *
+ * drawElement is also skipped when supersampling (deviceScaleFactor > 1):
+ * `drawElementImage` reads the canvas at CSS pixels and has no equivalent of
+ * `Page.captureScreenshot`'s clip+scale, so it would silently capture at 1x and
+ * drop the requested supersample. Such renders fall through to the screenshot
+ * path (preMode already forces "screenshot" for DPR > 1).
+ */
+async function initDrawElementOrTransparentBackground(session, page, logInitPhase) {
+    const supersampling = (session.options.deviceScaleFactor ?? 1) > 1;
+    // forceScreenshot is an explicit routing decision made upstream (render-mode
+    // compat hints like raw requestAnimationFrame, alpha formats, low-memory) —
+    // drawElement must not override it. Concretely: an rAF-compat comp on
+    // SwiftShader gets a screenshot-launched (free-running) browser, where
+    // drawElement runs in paint-event-sync mode; SwiftShader never refreshes a
+    // 2d canvas bitmap inside a cached paint record there, so every canvas
+    // captures frozen-blank (raf-ball rendered fully black). On a GPU the same
+    // path happens to work, but the hint asked for screenshot — honor it.
+    const forceScreenshot = session.config?.forceScreenshot ?? false;
+    // DIAGNOSTIC ONLY — HF_FORCE_DRAWELEMENT=1 forces the drawElement path,
+    // bypassing every compile/init gate AND the compatibility hints (it overrides
+    // forceScreenshot). Exists for upstream-Chromium repro work (isolating gate
+    // behavior from drawElementImage behavior, e.g. the crbug 521861819 149-vs-151
+    // comparison) and for R&D on gated effect classes. Renders under this flag may
+    // be DAMAGED by design — the gates it skips exist because measured damage
+    // (blur/backdrop ~18-49dB, 3D backface, SwiftShader sub-layer drops) is real.
+    // Never set it in production; it is intentionally not documented in user-facing
+    // help, and the safety-net blank guard also stands down under it so diagnostic
+    // frames arrive unmodified.
+    const forceDE = process.env.HF_FORCE_DRAWELEMENT === "1";
+    const useDrawElement = ((session.config?.useDrawElement ?? false) || forceDE) &&
+        !supersampling &&
+        (!forceScreenshot || forceDE);
+    if ((session.config?.useDrawElement ?? false) && supersampling) {
+        session.deGateReason = "supersampling";
+        console.log("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
+            "ignores deviceScaleFactor, so supersampled (DPR > 1) output uses screenshot capture.");
+    }
+    if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
+        session.deGateReason = "render_mode_hint";
+        console.log("[engine] fast capture: falling back to screenshot — render-mode compatibility " +
+            "hint forced screenshot capture (e.g. raw requestAnimationFrame composition).");
+    }
+    // Retract the per-page autoAlpha rewrite flag when a runtime gate routes the
+    // session to screenshot mode. evaluateOnNewDocument already fired; a follow-up
+    // evaluate overrides it in the live page context so hideTransparentAutoAlpha-
+    // Targets does not hide elements on the fallback screenshot render
+    // (up to 21 dB damage if not retracted, A/B proven 2026-06-12).
+    async function retractAutoAlphaFlag() {
+        await page.evaluate(() => {
+            window.__HF_FAST_CAPTURE_AUTOALPHA__ = false;
+        });
+    }
+    if (useDrawElement) {
+        session.isSwiftShader = await detectSwiftShader(page);
+        const transparent = session.options.format === "png";
+        async function routeToFallback() {
+            session.captureMode = session.launchCaptureMode;
+            if (transparent) {
+                await initTransparentBackground(session.page);
+            }
+            await retractAutoAlphaFlag();
+            // Static-frame dedup is capture-mode-independent (the serial path reuses
+            // lastFrameBuffer regardless of how the frame was captured) and lossless
+            // (anchor-verified). A comp only reaches THIS fallback with useDrawElement=true
+            // AND forceScreenshot=false — i.e. it is deterministic: raw-rAF / iframe /
+            // htmlInCanvas comps are forced to screenshot upstream (forceScreenshot=true) and
+            // never enter this block, so they never arm dedup. The comps that DO fall back here
+            // (blur / backdrop / 3D / at-risk) carry only a compositor
+            // EFFECT drawElement can't paint, not nondeterminism, so their predicted-static set
+            // is sound. Verification seeks via Page.captureScreenshot, which hangs on a
+            // BeginFrame-launched browser — gate on the launch mode (macOS fast-capture launches
+            // screenshot-mode; Linux/Docker launches beginframe and is skipped).
+            if (session.launchCaptureMode === "screenshot") {
+                await armStaticDedup(session, page, logInitPhase);
+            }
+        }
+        // SwiftShader gate: drawElement's only advantage is skipping the GPU→CPU
+        // screenshot-readback IPC. On a software rasterizer (Docker/CI, no GPU) both
+        // paths block on identical software raster, so drawElement is parity-or-slower
+        // — route to the platform baseline.
+        //
+        // Two gates were REMOVED here once Chrome 151 fixed crbug 521861819
+        // (drawElementImage dropped compositor-promoted opacity layers mid-fade):
+        //   - the <video> gate (a proxy for the word-by-word caption opacity pattern,
+        //     Lim 2), and
+        //   - the stacked-fade gate (>=2 overlapping viewport-scale opacity-fade targets).
+        // 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";
+            // 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.log(`[engine] fast capture: falling 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();
+        }
+        else {
+            // CSS-effect gate: backdrop-filter samples the compositor backdrop and
+            // filter:blur/drop-shadow render differently through the paint-record
+            // 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.
+            if (!forceDE && process.env.HF_FAST_CAPTURE_CSSFX !== "true") {
+                const cssFx = await detectCssEffectRisk(page);
+                if (cssFx) {
+                    session.deGateReason = `css_effect:${(cssFx.split(":")[0] ?? "").replace(/[^a-z-]/gi, "")}`;
+                    console.log(`[engine] fast capture: falling back to ${session.launchCaptureMode} capture — ` +
+                        `${cssFx} detected (drawElementImage cannot reproduce it; see fast-capture-limitations.md)`);
+                    await routeToFallback();
+                    return;
+                }
+            }
+            // Lim 7: timeline-interval at-risk predictor. Walk window.__timelines and
+            // find tweens animating compositor-incompatible props (opacity, filter,
+            // blend-mode, 3D transform, clip-path, mask). drawElementImage drops these
+            // mid-animation (crbug 521861819 et al), and whether it drops a given one
+            // cannot be told reliably without rendering (jump-seek != sequential render,
+            // proven 2026-06-16) nor from geometry (size is a proxy, not the mechanism).
+            // The only deterministic + reliable route to 0 damage is to gate on the
+            // PRESENCE of any such tween — a pure fact of the declared timeline, the same
+            // every run. Conservative by design: comps whose risky tweens drawElement
+            // would have handled also fall back, but correctness is never at risk and the
+            // fast path stays open for static + plain-2D-transform comps (x/y/scale are
+            // NOT in the at-risk set). Tune the gate's frame-fraction floor with
+            // HF_FAST_CAPTURE_INTERVAL_FRACTION (default 0 = any at-risk frame gates).
+            // Must run BEFORE canvas injection so a whole-comp fallback doesn't leave the
+            // drawElement canvas wrapping the composition root. Disable with
+            // HF_FAST_CAPTURE_INTERVAL_SS=false.
+            if (!forceDE && process.env.HF_FAST_CAPTURE_INTERVAL_SS !== "false") {
+                const fps = fpsToNumber(session.options.fps);
+                const { frames: atRisk, totalFrames } = await computeTimelineAtRiskFrames(page, fps);
+                const atRiskFraction = atRisk.size / totalFrames;
+                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";
+                    console.log(`[engine] fast capture: falling 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();
+                    return;
+                }
+            }
+            // Rewrite CSS 3D contexts into WebGL-projected canvases BEFORE the
+            // layoutsubtree canvas goes in (rects are measured in normal layout).
+            // drawElementImage cannot paint 3D rendering contexts — see
+            // threeDProjection.ts. No-op for compositions without 3D content.
+            const threeD = await initThreeDProjection(page);
+            if (!forceDE && !threeD.ok) {
+                session.deGateReason = "3d_init_failed";
+                console.log(`[engine] fast capture: falling back to ${session.launchCaptureMode} capture — ` +
+                    `3D projection init failed (${threeD.reason ?? "unknown"})`);
+                await routeToFallback();
+                return;
+            }
+            if (threeD.groups > 0) {
+                logInitPhase(`3D projection active: ${threeD.groups} context(s), ${threeD.quads} quad(s), ` +
+                    `${threeD.selfQuads ?? 0} self-quad el(s), ${threeD.stubTargets ?? 0} stub target(s)`);
+            }
+            // Task B: arm static-frame dedup here — drawElement is confirmed (all gates
+            // 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);
+            // Self-verification ground truth: must ALSO run pre-injection — after the
+            // canvas wraps the root, a page screenshot shows the canvas's last-drawn
+            // bitmap, not the live DOM (see the Lim 6 boundary-screenshot note).
+            {
+                const verifyStart = Date.now();
+                await captureDeVerificationFrames(session, page, logInitPhase);
+                session.deVerifyInitMs = Date.now() - verifyStart;
+            }
+            await injectDrawElementCanvas(page, session.options.width, session.options.height);
+            if (transparent) {
+                await initTransparentBackground(session.page);
+            }
+            session.captureMode = "drawelement";
+            session.drawElementReady = true;
+            logInitPhase("drawElement canvas injected");
+            // Lim 6: clip-cut boundary frames — screenshot these instead of drawElement.
+            if (process.env.HF_FAST_CAPTURE_BOUNDARY_SS !== "false" && !forceDE) {
+                const fps = fpsToNumber(session.options.fps);
+                const boundaryFrames = await computeClipBoundaryFrames(page, fps);
+                if (boundaryFrames.size > 0) {
+                    session.clipBoundaryFrames = boundaryFrames;
+                    logInitPhase(`screenshot fallback: ${boundaryFrames.size} clip-boundary frame(s)`);
+                }
+            }
+            // 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;
+            if (workerEncodeEnabled) {
+                await initDrawElementWorkerEncode(page);
+                session.workerEncodeEnabled = true;
+                logInitPhase("drawElement worker encode initialized");
+            }
+        }
+    }
+    else if (session.options.format === "png") {
+        await initTransparentBackground(session.page);
+    }
+}
 // fallow-ignore-next-line unit-size
 export async function createCaptureSession(serverUrl, outputDir, options, onBeforeCapture = null, config) {
     if (!existsSync(outputDir))
@@ -176,16 +424,38 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     // `options.format === "png"` for transparent capture should also set
     // `config.forceScreenshot = true` (the producer's renderOrchestrator does this
     // automatically when `RenderConfig.format` is an alpha-capable value).
+    // Exception: `useDrawElement=true` with png self-manages the screenshot-browser
+    // requirement (both the SwiftShader fallback and the GPU transparent path need
+    // a screenshot-launched browser — the SwiftShader path calls Page.captureScreenshot
+    // which hangs on a BeginFrame browser, and the GPU path doesn't need BeginFrame
+    // because the compositor runs freely on a screenshot-launched browser).
     const headlessShell = resolveHeadlessShellPath(config);
     const isLinux = process.platform === "linux";
     const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
+    const useDrawElement = config?.useDrawElement ?? false;
+    const drawElementTransparent = useDrawElement && options.format === "png";
+    // 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
+    // micro-screenshot would also hang on an opaque/beginframe-launched browser).
+    // `resolveConfig` forces page-side compositing off whenever useDrawElement is
+    // set, so this only trips for a direct caller that bypassed resolveConfig and
+    // passed both flags — warn once and treat page-side as disabled.
+    if (useDrawElement &&
+        (config?.enablePageSideCompositing ?? DEFAULT_CONFIG.enablePageSideCompositing)) {
+        console.warn("[engine] useDrawElement is incompatible with page-side shader compositing — " +
+            "ignoring enablePageSideCompositing for this render. Prefer resolveConfig, " +
+            "which disables page-side compositing automatically for fast-capture renders.");
+    }
     // BeginFrame's screenshot does not honor a viewport `deviceScaleFactor`
     // (the captured surface is sized by the OS window in CSS pixels regardless
     // of `Emulation.setDeviceMetricsOverride`'s DPR). When supersampling we
     // need explicit clip+scale on `Page.captureScreenshot`, so fall back to
     // the screenshot path for any DPR > 1.
     const supersampling = (options.deviceScaleFactor ?? 1) > 1;
-    const preMode = headlessShell && isLinux && !forceScreenshot && !supersampling ? "beginframe" : "screenshot";
+    const preMode = headlessShell && isLinux && !forceScreenshot && !supersampling && !drawElementTransparent
+        ? "beginframe"
+        : "screenshot";
     const requestedGpuMode = config?.browserGpuMode ?? DEFAULT_CONFIG.browserGpuMode;
     const resolvedGpuMode = await resolveBrowserGpuMode(requestedGpuMode, {
         chromePath: headlessShell ?? undefined,
@@ -226,6 +496,42 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
             w.__name = (fn, _name) => fn;
         }
     });
+    // 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
+    // composites their live content via drawImage instead (see
+    // instrumentAcceleratedCanvases). Must be registered before navigation.
+    if (useDrawElement) {
+        await page.evaluateOnNewDocument(instrumentAcceleratedCanvases);
+    }
+    // Signal the producer's GSAP stub to rewrite `opacity` → `autoAlpha` in tween
+    // vars (stacked opacity-0 caption layers break drawElementImage capture).
+    //
+    // DEFAULT OFF (opt in with HF_FAST_CAPTURE_AUTOALPHA=true). The rewrite is baked
+    // at tween-creation (page load) and `retractAutoAlphaFlag` (flag-only) can't
+    // un-bake it: GSAP autoAlpha sets visibility:hidden under seek capture and renders
+    // ~28 dB below a clean opacity baseline (corpus eval 2026-06-16, e.g.
+    // 05f22830/06167790: autoAlpha-off = ∞, autoAlpha-on = 28 dB). The rewrite was a
+    // workaround for the stacked-fade opacity-layer drop (crbug 521861819), now fixed
+    // in Chrome 151 — so it damages more than it fixes. Re-enable per render only if a
+    // drawElement comp shows transparent-layer drop on the pinned 151 floor.
+    if (useDrawElement && process.env.HF_FAST_CAPTURE_AUTOALPHA === "true") {
+        await page.evaluateOnNewDocument(() => {
+            window.__HF_FAST_CAPTURE_AUTOALPHA__ = true;
+        });
+    }
+    // Re-apply the captured root's own computed opacity to the 2D context:
+    // drawElementImage does not reflect post-paint changes to compositor-applied
+    // properties on the captured element itself (the root's opacity is applied by
+    // its parent at composite time, never baked into its content snapshot), so an
+    // animated root fade renders at full opacity. captureDrawElementFrame corrects
+    // this by the ratio current/base opacity (no-op for a static root). On by
+    // default; disable with HF_FAST_CAPTURE_ROOT_PROPS=false.
+    if (useDrawElement && process.env.HF_FAST_CAPTURE_ROOT_PROPS !== "false") {
+        await page.evaluateOnNewDocument(() => {
+            window.__HF_ROOT_PROPS__ = true;
+        });
+    }
     // Inject render-time variable overrides before any page script runs, so the
     // runtime helper `getVariables()` returns the merged result on its first
     // call. Pass the JSON string and parse inside the page so we don't require
@@ -280,6 +586,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
             totalMs: 0,
         },
         captureMode,
+        launchCaptureMode: captureMode,
         beginFrameTimeTicks: 0,
         // Frame interval in ms: 1000 * den / num. For 30/1 → 33.333…, for
         // 30000/1001 (NTSC) → 33.366…. JavaScript number precision is fine at
@@ -444,11 +751,16 @@ async function pollHfReady(page, timeoutMs, intervalMs = 100) {
         `renderReady=${diag.renderReady}, duration=${diag.duration}`);
 }
 async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150) {
+    // Hosts may opt out of the timeline wait with `data-no-timeline` —
+    // compositions driven purely by CSS animations / rAF (the render-compat
+    // contract) never register window.__timelines[id], and without the opt-out
+    // they stall here for the full playerReadyTimeout (45 s) on every render.
     const expression = `(function() {
     var hosts = document.querySelectorAll("[data-composition-id]");
     if (hosts.length === 0) return true;
     var timelines = window.__timelines || {};
     for (var i = 0; i < hosts.length; i++) {
+      if (hosts[i].hasAttribute("data-no-timeline")) continue;
       var id = hosts[i].getAttribute("data-composition-id");
       if (!id) continue;
       if (!timelines[id]) return false;
@@ -476,13 +788,15 @@ async function pollSubCompositionTimelines(page, timeoutMs, intervalMs = 150) {
       var timelines = window.__timelines || {};
       var m = [];
       for (var i = 0; i < hosts.length; i++) {
+        if (hosts[i].hasAttribute("data-no-timeline")) continue;
         var id = hosts[i].getAttribute("data-composition-id");
         if (id && !timelines[id]) m.push(id);
       }
       return m.join(", ");
     })()`);
         console.warn(`[FrameCapture] Sub-composition timelines not registered after ${timeoutMs}ms: ${missing}. ` +
-            `Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes.`);
+            `Compositions that load data asynchronously (e.g. fetch) must register window.__timelines[id] after setup completes. ` +
+            `Compositions intentionally driven without GSAP timelines (CSS animations / rAF) can mark the host with data-no-timeline to skip this wait.`);
     }
 }
 async function pollVideosReady(page, skipIds, timeoutMs, intervalMs = 100) {
@@ -760,16 +1074,8 @@ export async function initializeSession(session) {
                 `Continuing render — affected videos will appear as blank/black frames.`);
         }
         await recordSessionInitTelemetry(session, initStart);
-        // For PNG captures, force the page background fully transparent so the
-        // captured screenshots carry a real alpha channel. Must run AFTER
-        // navigation (Chrome resets the override on every goto) and AFTER the
-        // page is loaded (the injected stylesheet needs a real document.head).
-        // The override is overridden by `body { background: ... }` and
-        // `#root { background: ... }` rules — the helper handles that with a
-        // `[data-composition-id]{background:transparent !important}` injection.
-        if (session.options.format === "png") {
-            await initTransparentBackground(session.page);
-        }
+        // drawElement or transparent-background init — runs after page is fully ready.
+        await initDrawElementOrTransparentBackground(session, page, logInitPhase);
         await armStaticDedup(session, session.page, logInitPhase);
         session.isInitialized = true;
         return;
@@ -896,15 +1202,15 @@ export async function initializeSession(session) {
     // constant so chunk workers on different hosts compute the same baseline.
     const baseTickCount = lockWarmupTicks ? LOCKED_WARMUP_TICKS : warmupState.ticks;
     session.beginFrameTimeTicks = (baseTickCount + 10) * session.beginFrameIntervalMs;
-    // For PNG captures, inject the transparent-background override + stylesheet
-    // (see the screenshot-mode branch above for the rationale). BeginFrame mode
-    // does not actually preserve alpha through its compositor — callers that
-    // need transparent output should set `forceScreenshot: true` so this branch
-    // is bypassed entirely. The call is left here as defense-in-depth for any
-    // future BeginFrame alpha support.
-    if (session.options.format === "png") {
-        await initTransparentBackground(session.page);
-    }
+    // drawElement or transparent-background init — runs after page is fully ready.
+    // IMPORTANT: must stay after beginFrameTimeTicks is set above. The per-frame
+    // drawelement branch gates its BeginFrame call on `beginFrameTimeTicks > 0`;
+    // if this ran first, ticks would be 0 and the paused compositor would never
+    // advance for opaque drawElement on Linux. (In beginframe-launched mode,
+    // transparent is always false — useDrawElement+png forces preMode="screenshot"
+    // upstream — so the SwiftShader fallback inside the helper is dead-but-harmless
+    // defense-in-depth here.)
+    await initDrawElementOrTransparentBackground(session, page, logInitPhase);
     await armStaticDedup(session, session.page, logInitPhase);
     session.isInitialized = true;
 }
@@ -965,7 +1271,9 @@ async function prepareFrameForCapture(session, frameIndex, time) {
     //  1. prepare — clone scenes (now containing injected video <img>s)
     //  2. micro-screenshot — force browser to paint cloned elements
     //  3. resolve — drawElementImage reads paint records, shader composites
-    if (hasPendingComposite && session.captureMode !== "beginframe") {
+    if (hasPendingComposite &&
+        session.captureMode !== "beginframe" &&
+        session.captureMode !== "drawelement") {
         await page.evaluate(async () => {
             const w = window;
             if (typeof w.__hf_page_composite_prepare === "function") {
@@ -1249,6 +1557,14 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
  * via HF_STATIC_DEDUP_SAMPLES (default 24).
  */
 async function armStaticDedup(session, page, logInitPhase) {
+    // Idempotent: the drawElement init path arms dedup BEFORE canvas injection
+    // (verification screenshots need the un-injected DOM), and initializeSession
+    // calls this again unconditionally afterwards. Once staticFrames is
+    // populated, re-running would overwrite the armed state with
+    // skipReason="capture_mode" (captureMode is "drawelement" by then) —
+    // contradictory telemetry — and re-run the verification seeks. No-op instead.
+    if (session.staticFrames || session.staticDedupSkipReason)
+        return;
     // Default ON for everyone; opt out via HF_STATIC_DEDUP in {false,0,off} (resolved into
     // EngineConfig.staticFrameDedup by resolveConfig). Verification is the safety net at scale.
     // Default-on: only an explicit `staticFrameDedup === false` (resolved from
@@ -1315,10 +1631,90 @@ async function armStaticDedup(session, page, logInitPhase) {
         `(${Math.round((stats.staticFrameSet.size / stats.totalFrames) * 100)}%, verified)`);
 }
 /**
- * Internal core: prepare, screenshot, and track perf.
- * Shared by captureFrame (disk) and captureFrameToBuffer (buffer).
- * Returns the screenshot buffer, quantized time, and total capture time.
+ * Walk window.__timelines and collect frame intervals where GSAP tweens animate
+ * compositor-incompatible properties (blend-mode, 3D transforms, clip-path, mask).
+ * drawElement cannot reproduce these effects mid-tween → capture those frames via
+ * screenshot instead. opacity/filter fades were dropped from the set once Chrome 151
+ * fixed crbug 521861819. See docs/fast-capture-limitations.md Lim 7.
+ *
+ * Returns the union of at-risk frame indices (±1 margin around each tween interval)
+ * and totalFrames (for fraction computation by the caller).
  */
+async function computeTimelineAtRiskFrames(page, fps) {
+    const result = await page.evaluate(() => {
+        // opacity/autoAlpha/filter fades were removed from this set once Chrome 151
+        // fixed crbug 521861819 (drawElementImage dropped promoted opacity layers
+        // mid-fade) — those now render correctly on the drawElement path. backdrop-filter
+        // and filter:blur stay gated by detectCssEffectRisk (architectural single-element
+        // capture limit, not 521861819). What remains here is the per-tween backstop for
+        // effects drawElementImage still cannot reproduce mid-animation: mix-blend-mode,
+        // CSS 3D transforms (crbug 522872457), clip-path, and mask.
+        const AT_RISK_PROPS = new Set([
+            "backdropFilter",
+            "backdrop-filter",
+            "mixBlendMode",
+            "mix-blend-mode",
+            "rotationX",
+            "rotationY",
+            "rotateX",
+            "rotateY",
+            "z",
+            "translateZ",
+            "clipPath",
+            "clip-path",
+            "maskImage",
+            "mask",
+        ]);
+        function walkTimeline(tl, offset, out) {
+            if (typeof tl.getChildren !== "function")
+                return;
+            for (const child of tl.getChildren(false, true, true)) {
+                const childStart = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
+                const childDur = typeof child.duration === "function" ? child.duration() : 0;
+                if (typeof child.getChildren === "function") {
+                    walkTimeline(child, childStart, out);
+                }
+                else {
+                    const vars = child.vars || {};
+                    if (Object.keys(vars).some((k) => AT_RISK_PROPS.has(k))) {
+                        out.push({ start: childStart, end: childStart + childDur });
+                    }
+                }
+            }
+        }
+        const w = window;
+        const timelines = w.__timelines || {};
+        const intervals = [];
+        for (const tl of Object.values(timelines)) {
+            if (tl && typeof tl.getChildren === "function") {
+                walkTimeline(tl, 0, intervals);
+            }
+        }
+        const duration = w.__hf?.duration ?? 0;
+        return { intervals, duration };
+    });
+    const { intervals, duration } = result;
+    const frames = new Set();
+    for (const { start, end } of intervals) {
+        const lo = Math.floor(start * fps) - 1;
+        const hi = Math.ceil(end * fps) + 1;
+        for (let f = Math.max(0, lo); f <= hi; f++) {
+            frames.add(f);
+        }
+    }
+    const totalFrames = Math.max(1, Math.ceil(duration * fps));
+    return { frames, totalFrames };
+}
+/**
+ * True for the drawElement `InvalidStateError: No cached paint record for element`
+ * thrown when a subtree element has no paint record for the current frame (display
+ * toggled / detached / freshly-shown at a clip-cut boundary). Per-frame, not
+ * whole-comp — callers fall back to screenshot for the single frame.
+ */
+function isNoCachedPaintRecordError(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    return msg.includes("No cached paint record");
+}
 async function captureFrameCore(session, frameIndex, time) {
     const { page, options } = session;
     const startTime = Date.now();
@@ -1358,6 +1754,84 @@ async function captureFrameCore(session, frameIndex, time) {
                 session.beginFrameNoDamageCount++;
             screenshotBuffer = result.buffer;
         }
+        else if (session.captureMode === "drawelement" &&
+            session.clipBoundaryFrames?.has(frameIndex) &&
+            process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true") {
+            // Lim 6 (serial path): proactively screenshotting clip-boundary frames is now
+            // OPT-IN (was default-on). It is net-harmful: drawElement renders most boundary
+            // frames correctly, but Page.captureScreenshot in drawElement mode captures the
+            // injected canvas (unpainted at render start → white; mid-render → ~1-frame
+            // stale), so the "fallback" REPLACES good frames with damaged ones (validated:
+            // 35e8fa9f 462→0 damaged frames, 4001da8e 11→0, when this is off). The two real
+            // boundary failure modes are now caught reactively below — the throw case by
+            // isNoCachedPaintRecordError, the silent-solid-black case by the small-frame
+            // blank-guard (a solid frame is a tiny JPEG) — without touching frames drawElement
+            // handles. Force the old behavior with HF_FAST_CAPTURE_BOUNDARY_SS=true. The worker
+            // path keeps proactive boundary-SS (it has no blank-guard); see
+            // captureFrameToBufferPipelined and docs/fast-capture-limitations.md.
+            screenshotBuffer = await pageScreenshotCapture(page, options);
+        }
+        else if (session.captureMode === "drawelement") {
+            // Advance compositor state via BeginFrame when available (Linux headless-shell);
+            // on macOS the compositor advances naturally without BeginFrame.
+            if (session.beginFrameTimeTicks > 0) {
+                const client = await getCdpSession(page);
+                await client.send("HeadlessExperimental.beginFrame", {
+                    frameTimeTicks: session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs,
+                    interval: session.beginFrameIntervalMs,
+                    noDisplayUpdates: false,
+                    // no screenshot param — we capture via canvas
+                });
+            }
+            try {
+                screenshotBuffer = await captureDrawElementFrame(page, options.width, options.height, options.format ?? "jpeg", options.quality ?? 80, 
+                // Paint-event sync only without BeginFrame (macOS / screenshot-launched):
+                // under BeginFrame control the per-frame beginFrame above already painted
+                // a fresh snapshot, and no further paint would arrive during a wait.
+                session.beginFrameTimeTicks === 0);
+                // Silent-blank-drop guard: drawElement occasionally returns a blank/dropped
+                // frame WITHOUT throwing (paint-record miss; the throw case is handled below).
+                // Such a frame's JPEG is anomalously tiny vs the comp's running median (a blank
+                // 1080p frame ~5-9 KB; content frames 50 KB-1 MB). Re-capture via screenshot
+                // (ground truth) — harmless for legitimately simple frames (screenshot matches).
+                // Catches scattered intermittent drops (e.g. 4001da8e: 11 blanks in 9300 frames,
+                // 9.7 dB) that no static gate can see. PNG/transparent excluded (alpha sizing
+                // differs and that path is its own).
+                if ((options.format ?? "jpeg") !== "png" && process.env.HF_FORCE_DRAWELEMENT !== "1") {
+                    const sizes = (session.deFrameSizes ??= []);
+                    const sorted = sizes.length >= 12 ? [...sizes].sort((a, b) => a - b) : null;
+                    const median = sorted ? (sorted[sorted.length >> 1] ?? 0) : 0;
+                    const floor = Math.max(20000, median * 0.12);
+                    if (screenshotBuffer.length < floor) {
+                        console.log(`[engine] fast capture: frame ${frameIndex} — drawElement frame anomalously ` +
+                            `small (${screenshotBuffer.length}B < ${Math.round(floor)}B, likely a silent ` +
+                            `paint-record drop); screenshot fallback (see fast-capture-limitations.md)`);
+                        screenshotBuffer = await pageScreenshotCapture(page, options);
+                    }
+                    else {
+                        if (sizes.length >= 60)
+                            sizes.shift();
+                        sizes.push(screenshotBuffer.length);
+                    }
+                }
+            }
+            catch (err) {
+                // drawElementImage throws `InvalidStateError: No cached paint record for
+                // element` when an element in the subtree has no paint record this frame
+                // (display toggled / detached / freshly-shown at a clip-cut boundary). This
+                // is a per-frame condition, not a whole-comp one — fall back to screenshot
+                // for THIS frame instead of aborting the render. See fast-capture-limitations.md.
+                if (isNoCachedPaintRecordError(err)) {
+                    session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
+                    console.log(`[engine] fast capture: frame ${frameIndex} — No cached paint record; ` +
+                        `screenshot fallback for this frame (see fast-capture-limitations.md)`);
+                    screenshotBuffer = await pageScreenshotCapture(page, options);
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
         else {
             screenshotBuffer = await pageScreenshotCapture(page, options);
         }
@@ -1381,14 +1855,24 @@ async function captureFrameCore(session, frameIndex, time) {
     }
 }
 export async function captureFrame(session, frameIndex, time) {
-    const { options, outputDir } = session;
     const { buffer, quantizedTime, captureTimeMs } = await captureFrameCore(session, frameIndex, time);
-    const ext = options.format === "png" ? "png" : "jpg";
-    const frameName = `frame_${String(frameIndex).padStart(6, "0")}.${ext}`;
-    const framePath = join(outputDir, frameName);
-    writeFileSync(framePath, buffer);
+    const framePath = writeCapturedFrame(session, frameIndex, buffer);
     return { frameIndex, time: quantizedTime, path: framePath, captureTimeMs };
 }
+/**
+ * Write an already-captured frame buffer to the session's output dir using the
+ * canonical `frame_NNNNNN.{jpg,png}` naming. `fileIndex` is the ENCODER-facing
+ * index (0-based within the captured range), which may differ from the absolute
+ * composition frame index used for seeking/boundary lookups. Extracted so the
+ * disk worker-encode pipeline can write a buffer produced by
+ * `captureFrameToBufferPipelined` without duplicating the naming convention.
+ */
+export function writeCapturedFrame(session, fileIndex, buffer) {
+    const ext = session.options.format === "png" ? "png" : "jpg";
+    const framePath = join(session.outputDir, `frame_${String(fileIndex).padStart(6, "0")}.${ext}`);
+    writeFileSync(framePath, buffer);
+    return framePath;
+}
 /**
  * Capture a frame and return the screenshot as a Buffer instead of writing to disk.
  * Used by the streaming encode pipeline to pipe frames directly to FFmpeg stdin.
@@ -1397,6 +1881,167 @@ export async function captureFrameToBuffer(session, frameIndex, time) {
     const { buffer, captureTimeMs } = await captureFrameCore(session, frameIndex, time);
     return { buffer, captureTimeMs };
 }
+/**
+ * Pipelined drawElement frame capture for the worker-encode path.
+ *
+ * Performs seek prep + paint-wait + drawElementImage + composite +
+ * `createImageBitmap` + transfers the bitmap to the in-page encode worker.
+ * Returns `encodeResult` immediately (before the worker finishes encoding).
+ * The caller overlaps frame N's encode with frame N+1's produce phase.
+ *
+ * Requirements:
+ *  - `session.workerEncodeEnabled` must be true (set by initializeSession when
+ *    `config.enableDrawElementWorkerEncode` is true and mode resolved to drawelement).
+ *  - JPEG format only. PNG falls back to `captureFrameToBuffer`.
+ *  - macOS hardware GPU path (syncToPaintEvent=true, beginFrameTimeTicks=0).
+ *    BeginFrame (Linux) uses the standard synchronous path unchanged.
+ */
+export async function captureFrameToBufferPipelined(session, frameIndex, time) {
+    const { page, options } = session;
+    const startTime = Date.now();
+    // 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.
+    if (session.staticFrames?.has(frameIndex) && session.lastEncodeResult) {
+        session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
+        session.capturePerf.frames += 1;
+        return { encodeResult: session.lastEncodeResult, captureTimeMs: Date.now() - startTime };
+    }
+    try {
+        const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(session, frameIndex, time);
+        void quantizedTime;
+        // Lim 6: clip-cut boundary frame — screenshot ONLY when opt-in, matching the serial
+        // path (captureFrameCore). Proactive boundary screenshots in drawElement mode are
+        // net-HARMFUL: with `<canvas layoutsubtree>` the child composition root is laid out
+        // but not painted to screen — only the canvas 2D bitmap is visible — so
+        // Page.captureScreenshot captures the injected canvas holding the LAST drawElement
+        // frame (stale by ≥1 scene at a hard cut), REPLACING a good frame with a stale one.
+        // Measured on 0531c45f: worker boundary frames showed the previous scene's video.
+        // Default OFF → boundary frames fall through to produceDrawElementFrame, which draws
+        // the CURRENT frame into the canvas. (Force old behavior with
+        // HF_FAST_CAPTURE_BOUNDARY_SS=true.) See captureFrameCore for the serial rationale.
+        if (session.clipBoundaryFrames?.has(frameIndex) &&
+            process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true") {
+            const buffer = await pageScreenshotCapture(page, options);
+            session.capturePerf.frames += 1;
+            session.capturePerf.seekMs += seekMs;
+            session.capturePerf.beforeCaptureMs += beforeCaptureMs;
+            session.capturePerf.totalMs += Date.now() - startTime;
+            const boundaryResult = Promise.resolve(buffer);
+            if (session.staticFrames)
+                session.lastEncodeResult = boundaryResult;
+            return { encodeResult: boundaryResult, captureTimeMs: Date.now() - startTime };
+        }
+        // Worker-encode is gated to the macOS GPU path (beginFrameTimeTicks === 0,
+        // syncToPaintEvent = true); see initDrawElementOrTransparentBackground. The
+        // BeginFrame branch present in the synchronous captureFrameCore is therefore
+        // unreachable here and intentionally omitted.
+        const { encodeResult } = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+        const captureTimeMs = Date.now() - startTime;
+        session.capturePerf.frames += 1;
+        session.capturePerf.seekMs += seekMs;
+        session.capturePerf.beforeCaptureMs += beforeCaptureMs;
+        // screenshotMs reflects produce time only (encode is async, not tracked here)
+        session.capturePerf.screenshotMs += captureTimeMs - seekMs - beforeCaptureMs;
+        session.capturePerf.totalMs += captureTimeMs;
+        // Task B: retain this encode result so a following static frame can reuse it.
+        if (session.staticFrames)
+            session.lastEncodeResult = encodeResult;
+        return { encodeResult, captureTimeMs };
+    }
+    catch (captureError) {
+        // Per-frame `No cached paint record`: fall back to screenshot for THIS frame
+        // instead of aborting the render (clip-cut boundary / freshly-shown element).
+        // The worker isn't involved for this frame; return a resolved encodeResult so
+        // the pipeline loop writes it like any other. See fast-capture-limitations.md.
+        if (isNoCachedPaintRecordError(captureError)) {
+            session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
+            console.log(`[engine] fast capture: frame ${frameIndex} — No cached paint record; ` +
+                `screenshot fallback for this frame (see fast-capture-limitations.md)`);
+            const buffer = await pageScreenshotCapture(page, options);
+            return { encodeResult: Promise.resolve(buffer), captureTimeMs: Date.now() - startTime };
+        }
+        // Mirror captureFrameCore: capture per-frame diagnostics (frame-error
+        // PNG/HTML/JSON + console tail) before rethrowing so pipelined-path
+        // failures are debuggable like the serial path.
+        if (session.isInitialized) {
+            await captureFrameErrorDiagnostics(session, frameIndex, time, captureError instanceof Error ? captureError : new Error(String(captureError)));
+        }
+        throw captureError;
+    }
+}
+/**
+ * Verification-grade single-frame recapture for the producer's blank-frame
+ * guard. Unlike {@link captureFrameToBufferPipelined} it takes NO shortcuts
+ * and has NO fallbacks, both of which can return the WRONG FRAME's pixels at
+ * drain time:
+ *  - the static-dedup fast path returns session.lastEncodeResult, which by
+ *    drain time can hold a frame several indices AHEAD of the suspect frame;
+ *  - the per-frame "No cached paint record" screenshot fallback captures the
+ *    injected canvas — i.e. the LAST drawn drawElement frame, not this one.
+ * Any failure here throws; the caller treats that as verification failure and
+ * falls back the whole render (correct, never wrong-frame).
+ */
+export async function recaptureDrawElementFrameForVerify(session, frameIndex, time) {
+    const { page, options } = session;
+    if (!session.isInitialized) {
+        throw new Error("[FrameCapture] Session not initialized");
+    }
+    await prepareFrameForCapture(session, frameIndex, time);
+    const { encodeResult } = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+    return encodeResult;
+}
+/**
+ * P6 prototype (HF_DE_BATCH): capture N consecutive frames in one CDP
+ * round-trip via {@link produceDrawElementFrameBatch}. The caller pre-plans the
+ * batch (consecutive frame indices, none static-dedup'd, none opt-in
+ * boundary-screenshot). On a mid-batch in-page failure the remaining frames are
+ * re-captured through {@link captureFrameToBufferPipelined}, which owns the
+ * per-frame screenshot-fallback semantics — so failure behavior is identical to
+ * the unbatched path, just discovered at batch granularity.
+ */
+export async function captureFramesBatchPipelined(session, frameIndices, times) {
+    const { page, options } = session;
+    if (!session.isInitialized) {
+        throw new Error("[FrameCapture] Session not initialized");
+    }
+    const startTime = Date.now();
+    const fps = fpsToNumber(options.fps);
+    const quantized = times.map((t) => quantizeTimeToFrame(t, fps));
+    const { encodeResults, failedAt, error } = await produceDrawElementFrameBatch(page, quantized, options.width, options.height, options.quality ?? 80);
+    const okCount = failedAt === null ? frameIndices.length : failedAt;
+    const elapsed = Date.now() - startTime;
+    session.capturePerf.frames += okCount;
+    // Round-trips are fused — attribute the whole batch to produce time.
+    session.capturePerf.screenshotMs += elapsed;
+    session.capturePerf.totalMs += elapsed;
+    const results = [];
+    for (let i = 0; i < okCount; i++) {
+        const frameIndex = frameIndices[i];
+        const encodeResult = encodeResults[i];
+        if (frameIndex === undefined || !encodeResult)
+            break;
+        results.push({ frameIndex, encodeResult });
+    }
+    if (failedAt !== null) {
+        console.log(`[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++) {
+            const frameIndex = frameIndices[i];
+            const time = times[i];
+            if (frameIndex === undefined || time === undefined)
+                break;
+            const { encodeResult } = await captureFrameToBufferPipelined(session, frameIndex, time);
+            results.push({ frameIndex, encodeResult });
+        }
+    }
+    // Task B: retain the last encode result so a following static frame can reuse it.
+    const last = results[results.length - 1];
+    if (session.staticFrames && last)
+        session.lastEncodeResult = last.encodeResult;
+    return results;
+}
 /**
  * Perform one capture, throw away the buffer, and restore any session
  * side-effects (perf counters, BeginFrame damage tallies) so downstream
@@ -1478,6 +2123,9 @@ export async function closeCaptureSession(session) {
     // Example: page release succeeds, browser release throws → pageReleased=true
     // but browserReleased=false → second call no-ops on page and retries browser.
     // This matches the orchestrator's intent for HDR cleanup.
+    if (session.workerEncodeEnabled && session.page && !session.pageReleased) {
+        cleanupDrawElementWorkerEncode(session.page);
+    }
     if (!session.pageReleased && session.page) {
         const pageClosed = await waitForCloseWithTimeout(session.page.close());
         if (!pageClosed) {
@@ -1526,6 +2174,112 @@ export async function getCompositionDuration(session) {
         return window.__hf?.duration ?? 0;
     });
 }
+/**
+ * Ungated-release safety net, part 1: capture K screenshot ground-truth frames
+ * BEFORE the drawElement canvas is injected (the only window where a page
+ * screenshot shows the live DOM). The producer's drain compares each DE frame
+ * at these indices against its screenshot; a breach (or a blank frame that
+ * survives one retry) throws DrawElementVerificationError, and the orchestrator
+ * re-renders the whole job via the screenshot path.
+ *
+ * Env: HF_DE_VERIFY = sample count (default 4, clamp 0..8; 0 disables).
+ * Deterministic index selection: fixed fractions of the timeline, nudged off
+ * clip-cut boundaries (screenshot-vs-DE is legitimately ±1-frame desynced
+ * there — Lim 6). Skipped for tiny comps (<10 frames) and under
+ * HF_FORCE_DRAWELEMENT (debug escape hatch).
+ *
+ * False-positive bias is intentional: a nondeterministic comp may mismatch its
+ * init-time screenshot → the render falls back to the screenshot path (slower,
+ * never wrong). Cost when passing: ~K×(seek+screenshot) ≈ 150–300ms at init.
+ */
+async function captureDeVerificationFrames(session, page, logInitPhase) {
+    const kRaw = Number(process.env.HF_DE_VERIFY ?? "4");
+    const k = Number.isFinite(kRaw) ? Math.max(0, Math.min(8, Math.floor(kRaw))) : 4;
+    if (k === 0 || process.env.HF_FORCE_DRAWELEMENT === "1")
+        return;
+    if (session.options.format === "png")
+        return; // worker-encode drain (the consumer) is jpeg-only
+    const fps = fpsToNumber(session.options.fps);
+    // Prefer the producer-resolved duration (the range that will actually be
+    // drained). The page's raw __hf.duration can exceed it — timelines outrun
+    // their data-duration, and infinite-repeat GSAP reports a huge sentinel —
+    // and indices derived from it would never be drained, silently disarming
+    // verification for exactly the comps that need it.
+    const duration = session.options.compositionDurationSeconds ??
+        (await page.evaluate(() => window.__hf?.duration ?? 0));
+    const totalFrames = Math.floor(duration * fps);
+    if (totalFrames < 10)
+        return;
+    if (duration > 3600) {
+        // No producer duration and the page reports an implausible one.
+        logInitPhase(`drawElement self-verify skipped: implausible duration ${duration}s`);
+        return;
+    }
+    // Ground truth must show what the real capture paths would show: <video>
+    // pixels come from the onBeforeCapture injector. When this session has no
+    // injector (e.g. a probe session initialized before the render wires one
+    // up) a video comp's truth would screenshot black boxes and every sample
+    // would false-positive into the screenshot fallback — skip instead.
+    if (!session.onBeforeCapture) {
+        const hasVideos = await page.evaluate(() => document.querySelector("video") !== null);
+        if (hasVideos) {
+            logInitPhase("drawElement self-verify skipped: video comp without frame injector");
+            return;
+        }
+    }
+    const boundary = await computeClipBoundaryFrames(page, fps);
+    // Ascending order, and seek frame 0 first: GSAP .from()/overlapping tweens
+    // lazily record their start values on FIRST seek — scrubbing mid-timeline
+    // before the render's frame-0 seek corrupts those caches for the whole
+    // render (the detectCssEffectRisk lesson), and because DE frames and truth
+    // would share the corruption, PSNR would pass on the damaged output.
+    // Seeking 0 → ascending reproduces the render's own seek order.
+    const fractions = Array.from({ length: k }, (_, i) => (i + 1) / (k + 1));
+    const seekTo = async (t) => {
+        await page.evaluate((tt) => {
+            const hf = window.__hf;
+            if (hf && typeof hf.seek === "function")
+                hf.seek(tt);
+        }, t);
+    };
+    await seekTo(quantizeTimeToFrame(0, fps));
+    // Force one frame so lazy tween initialization paints at t=0 state.
+    await pageScreenshotCapture(page, session.options);
+    const frames = new Map();
+    for (const f of fractions) {
+        let idx = Math.min(totalFrames - 1, Math.max(1, Math.round(totalFrames * f)));
+        // 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)
+            idx = Math.min(totalFrames - 1, idx + 2);
+        if (boundary.has(idx))
+            continue;
+        if (frames.has(idx))
+            continue;
+        const t = quantizeTimeToFrame(idx / fps, fps);
+        await seekTo(t);
+        // 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(page, t);
+        // Double-capture: the first screenshot forces a frame, which is what runs
+        // rAF-driven callbacks (count-up text counters land a tick after seek()
+        // returns — a single immediate screenshot captures stale text and
+        // false-positives the verify: 3bea8c73 28.7dB vs a truth missing its stat
+        // values while the DE frame was correct). NOTE: waiting on rAF via
+        // evaluate instead deadlocks — headless only fires rAF when a frame is
+        // produced, and nothing produces one until a screenshot asks.
+        await pageScreenshotCapture(page, session.options);
+        frames.set(idx, await pageScreenshotCapture(page, session.options));
+    }
+    // Leave the page at frame 0 so the render's first seek starts from the
+    // same state as an unverified render.
+    await seekTo(quantizeTimeToFrame(0, fps));
+    session.deVerifyFrames = frames;
+    logInitPhase(`drawElement self-verify armed: ${frames.size} ground-truth frame(s) @ [${[...frames.keys()].join(", ")}] of ${totalFrames}`);
+}
 export function getCapturePerfSummary(session) {
     const frames = Math.max(1, session.capturePerf.frames);
     return {
@@ -1540,6 +2294,13 @@ export function getCapturePerfSummary(session) {
         staticDedupArmed: (session.staticFrames?.size ?? 0) > 0,
         staticDedupPredicted: session.staticFrames?.size ?? 0,
         staticDedupSkipReason: session.staticDedupSkipReason,
+        captureMode: session.captureMode,
+        deGateReason: session.deGateReason,
+        deWorkerEncode: session.workerEncodeEnabled ?? false,
+        deVerifyArmed: session.deVerifyFrames?.size ?? 0,
+        deVerifyInitMs: session.deVerifyInitMs ?? 0,
+        deBoundaryFrames: session.clipBoundaryFrames?.size ?? 0,
+        deNcprFallbacks: session.deNcprFallbacks ?? 0,
     };
 }
 // ── Transient browser error classification ─────────────────────────────────