@hyperframes/engine 0.8.44 → 0.8.46

package/dist/services/frameCapture.js

@@ -9,8 +9,10 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
+import { quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, } from "@hyperframes/core";
 import { DrawElementCaptureError } from "./drawElementCaptureError.js";
+import { encodePng } from "../utils/alphaBlit.js";
+import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, resolveHeadlessShellPath, } from "./browserManager.js";
 import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
@@ -1653,7 +1655,7 @@ export async function initializeSession(session) {
         await initDrawElementOrTransparentBackground(session, page, logInitPhase);
         await armStaticDedup(session, session.page, logInitPhase);
         await ensureRenderFrameSiblings(session.page);
-        session.isInitialized = true;
+        finalizeSessionInit(session);
         return;
     }
     // In BeginFrame mode, Chrome's event loop is paused until we issue frames.
@@ -1821,7 +1823,7 @@ export async function initializeSession(session) {
     await ensureRenderFrameSiblings(page);
     const commitCdp = await getCdpSession(page);
     await commitCdp.send("HeadlessExperimental.beginFrame", preparedBeginFrameTimeline.commitParams);
-    session.isInitialized = true;
+    finalizeSessionInit(session);
 }
 async function captureFrameErrorDiagnostics(session, frameIndex, time, error) {
     try {
@@ -1856,23 +1858,30 @@ export async function waitForPendingSeekCompletion(page) {
         await waitForCompletion?.();
     });
 }
-async function prepareFrameForCapture(session, frameIndex, time) {
+/**
+ * Seek the page timeline and report whether a page-side composite is pending.
+ *
+ * The page's `seek()` owns all framework-specific stepping (GSAP, CSS animations, WAAPI);
+ * the options object reaches it untouched through the producer's `__hf.seek` bridge.
+ * Seek and pending-flag read share one round trip.
+ */
+async function seekPageTimeline(page, time, seekOptions) {
+    return page.evaluate((t, opts) => {
+        if (window.__hf && typeof window.__hf.seek === "function") {
+            window.__hf.seek(t, opts);
+        }
+        return !!window
+            .__hf_page_composite_pending;
+    }, time, seekOptions);
+}
+async function prepareFrameForCapture(session, frameIndex, time, seekOptions) {
     const { page, options } = session;
     if (!session.isInitialized) {
         throw new Error("[FrameCapture] Session not initialized");
     }
-    const quantizedTime = quantizeTimeToFrame(time, fpsToNumber(options.fps));
+    const quantizedTime = quantizeSeekTime(time, fpsToNumber(options.fps), seekOptions?.subFrameDivisions);
     const seekStart = Date.now();
-    // Seek via the __hf protocol. The page's seek() implementation handles
-    // all framework-specific logic (GSAP stepping, CSS animation sync, etc.)
-    // Seek + check page-side composite pending flag in one round-trip.
-    const hasPendingComposite = await page.evaluate((t) => {
-        if (window.__hf && typeof window.__hf.seek === "function") {
-            window.__hf.seek(t);
-        }
-        return !!window
-            .__hf_page_composite_pending;
-    }, quantizedTime);
+    const hasPendingComposite = await seekPageTimeline(page, quantizedTime, seekOptions);
     await decodeDynamicCssBackgroundImages(page);
     const seekMs = Date.now() - seekStart;
     // Before-capture hook (e.g. video frame injection) — runs before
@@ -1976,7 +1985,19 @@ export function isStaticDedupFrameAnalysisSafe(totalFrames) {
  * a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
  */
 export async function computeStaticFrameSet(page, fps) {
-    const result = await page.evaluate(() => {
+    const result = await page.evaluate((spatialProps) => {
+        // Passed in from SPATIAL_TWEEN_PROPERTIES rather than declared here, so the list
+        // stays the one this module's own tests exercise (the matching code itself must
+        // stay inline — this closure is serialized and runs in the page realm).
+        const SPATIAL_PROPS = new Set(spatialProps);
+        function isSpatial(vars) {
+            if (!vars)
+                return false;
+            for (const key of Object.keys(vars))
+                if (SPATIAL_PROPS.has(key))
+                    return true;
+            return false;
+        }
         const intervals = [];
         let tweenCount = 0;
         // totalDuration() (NOT duration()): a repeat/yoyo tween animates past one iteration;
@@ -2002,8 +2023,9 @@ export async function computeStaticFrameSet(page, fps) {
             // Mark its entire span as animated so those frames are never deduped.
             if (typeof tl.vars?.onUpdate === "function") {
                 const total = typeof tl.totalDuration === "function" ? tl.totalDuration() : 0;
+                // onUpdate can move anything (e.g. x/y from Math.random) — conservatively spatial.
                 if (total > 0)
-                    intervals.push({ start: offset, end: offset + total });
+                    intervals.push({ start: offset, end: offset + total, spatial: true });
             }
             for (const child of tl.getChildren(false, true, true)) {
                 const start = offset + (typeof child.startTime === "function" ? child.startTime() : 0);
@@ -2011,7 +2033,10 @@ export async function computeStaticFrameSet(page, fps) {
                 const total = typeof child.totalDuration === "function" ? child.totalDuration() : single;
                 if (typeof child.getChildren === "function") {
                     if (total > single + 1e-6) {
-                        intervals.push({ start, end: start + total });
+                        // A repeating nested timeline's own children are walked for their real
+                        // vars below; this span is a conservative (spatial) placeholder for the
+                        // repeat/yoyo overrun, which a per-child walk doesn't otherwise cover.
+                        intervals.push({ start, end: start + total, spatial: true });
                         // Still descend for hasTimelineCall even though the repeating
                         // span is already opaque (its frames are excluded from dedup
                         // regardless): a call() inside it is a review-flagged detection
@@ -2026,7 +2051,7 @@ export async function computeStaticFrameSet(page, fps) {
                 }
                 else {
                     tweenCount++;
-                    intervals.push({ start, end: start + total });
+                    intervals.push({ start, end: start + total, spatial: isSpatial(child.vars) });
                     if (total <= 1e-6 &&
                         (typeof child.vars?.onComplete === "function" ||
                             typeof child.vars?.onReverseComplete === "function")) {
@@ -2074,13 +2099,14 @@ export async function computeStaticFrameSet(page, fps) {
             hasUnresolvableClipStart,
             hasTimelineCall,
         };
-    });
+    }, SPATIAL_TWEEN_PROPERTIES);
     const { intervals, tweenCount, duration, hasVideo, hasCanvas, hasNonGsapAnim, hasUnresolvableClipStart, hasTimelineCall, } = result;
     const totalFrames = Math.max(1, Math.ceil(duration * fps));
     if (!isStaticDedupFrameAnalysisSafe(totalFrames)) {
         return {
             totalFrames,
             staticFrameSet: new Set(),
+            nonSpatialOnlyFrameSet: new Set(),
             hasVideo,
             hasCanvas,
             hasNonGsapAnim,
@@ -2090,11 +2116,15 @@ export async function computeStaticFrameSet(page, fps) {
         };
     }
     const animated = new Set();
-    for (const { start, end } of intervals) {
+    const spatialFrameSet = new Set();
+    for (const { start, end, spatial } of intervals) {
         const lo = Math.max(0, Math.floor(start * fps));
         const hi = Math.min(totalFrames - 1, Math.ceil(end * fps));
-        for (let f = lo; f <= hi; f++)
+        for (let f = lo; f <= hi; f++) {
             animated.add(f);
+            if (spatial)
+                spatialFrameSet.add(f);
+        }
     }
     for (const f of await computeClipBoundaryFrames(page, fps))
         animated.add(f);
@@ -2126,9 +2156,16 @@ export async function computeStaticFrameSet(page, fps) {
                 staticFrameSet.add(f);
         }
     }
+    const nonSpatialOnlyFrameSet = new Set();
+    if (eligible) {
+        for (const f of animated)
+            if (!spatialFrameSet.has(f))
+                nonSpatialOnlyFrameSet.add(f);
+    }
     return {
         totalFrames,
         staticFrameSet,
+        nonSpatialOnlyFrameSet,
         hasVideo,
         hasCanvas,
         hasNonGsapAnim,
@@ -2396,6 +2433,21 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
  * via HF_STATIC_DEDUP_SAMPLES (default 24).
  */
 async function armStaticDedup(session, page, logInitPhase) {
+    // Adaptive motion-blur sample-count classification shares the GSAP-timeline walk
+    // below but is gated independently of dedup (capture mode / before-capture hooks are
+    // about buffer-reuse safety, irrelevant to which properties a tween touches), so it
+    // is computed here, once, ahead of dedup's own idempotency check. Cached in
+    // `sharedStaticFrameStats` so dedup's own call further down does not repeat the walk.
+    // Reads `session.options.motionBlur` (the raw caller options), not `session.motionBlur`
+    // (the resolved plan) — every armStaticDedup call site runs before finalizeSessionInit
+    // resolves the plan, so the resolved field is never set yet at this point.
+    let sharedStaticFrameStats;
+    if (session.options.motionBlur &&
+        session.options.motionBlur.samplesPerFrame === undefined &&
+        !session.motionBlurNonSpatialFrames) {
+        sharedStaticFrameStats = await computeStaticFrameSet(page, fpsToNumber(session.options.fps));
+        session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
+    }
     // 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
@@ -2442,7 +2494,7 @@ async function armStaticDedup(session, page, logInitPhase) {
         return;
     }
     const fps = fpsToNumber(session.options.fps);
-    const stats = await computeStaticFrameSet(page, fps);
+    const stats = sharedStaticFrameStats ?? (await computeStaticFrameSet(page, fps));
     if (!stats.eligible || stats.staticFrameSet.size === 0) {
         session.staticDedupSkipReason = "ineligible";
         logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
@@ -2676,8 +2728,192 @@ export async function withFrameDeadline(work, label, ms, onTimeout) {
         });
     }
 }
-async function captureFrameCore(session, frameIndex, time) {
+/**
+ * Resolve the session's motion-blur plan, rejecting combinations the accumulation pass
+ * cannot render correctly instead of silently producing an unblurred frame.
+ *
+ * Called once initialization has settled the capture mode. `format: "png"` is required
+ * because samples are averaged pixel by pixel: JPEG samples would be averaged after
+ * lossy quantization and the blended frame is re-encoded as PNG. `<video>` content is
+ * out of scope because it is supplied by the before-capture frame-injection hook rather
+ * than by the timeline seek, so it cannot follow a sub-frame time.
+ */
+export function resolveSessionMotionBlur(session) {
+    const plan = resolveMotionBlurPlan(session.options.motionBlur);
+    if (!plan)
+        return undefined;
+    if (session.captureMode !== "screenshot") {
+        throw new Error(`[MotionBlur] sub-frame motion blur requires screenshot capture mode, got "${session.captureMode}"`);
+    }
+    if (session.options.format !== "png") {
+        throw new Error(`[MotionBlur] sub-frame motion blur requires format "png", got "${session.options.format ?? "jpeg"}"`);
+    }
+    if (session.onBeforeCapture) {
+        throw new Error("[MotionBlur] sub-frame motion blur cannot run with injected video frames: video content is extracted per output frame and does not follow a sub-frame seek");
+    }
+    return plan;
+}
+/** Seek to `time` and capture one surface with the session's capture mode. */
+async function captureFrameSurface(session, frameIndex, time, seekOptions) {
     const { page, options } = session;
+    const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(session, frameIndex, time, seekOptions);
+    const screenshotStart = Date.now();
+    let screenshotBuffer;
+    if (session.captureMode === "beginframe") {
+        const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
+        const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);
+        if (result.hasDamage)
+            session.beginFrameHasDamageCount++;
+        else
+            session.beginFrameNoDamageCount++;
+        screenshotBuffer = result.buffer;
+    }
+    else if (session.captureMode === "drawelement" &&
+        session.clipBoundaryFrames?.has(frameIndex) &&
+        process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true") {
+        throw new DrawElementCaptureError(frameIndex, "boundary screenshot requested on an injected canvas page");
+    }
+    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);
+            // A tiny JPEG may be a dropped paint record. Never screenshot this page:
+            // its injected canvas can still hold the preceding frame's bitmap.
+            // Restart on a fresh screenshot page even if this was a simple valid frame.
+            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) {
+                    throw new DrawElementCaptureError(frameIndex, `suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`);
+                }
+                else {
+                    if (sizes.length >= 60)
+                        sizes.shift();
+                    sizes.push(screenshotBuffer.length);
+                }
+            }
+        }
+        catch (err) {
+            // Missing paint records/canvas state require a new screenshot page.
+            if (isRecoverableDrawElementError(err)) {
+                session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
+                const reason = isCanvasNotInitializedError(err)
+                    ? "drawElement canvas not initialized"
+                    : "No cached paint record";
+                throw new DrawElementCaptureError(frameIndex, reason, err);
+            }
+            else {
+                throw err;
+            }
+        }
+    }
+    else {
+        screenshotBuffer = await pageScreenshotCapture(page, options);
+    }
+    const screenshotMs = Date.now() - screenshotStart;
+    return { buffer: screenshotBuffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs };
+}
+/**
+ * Mark the session ready to capture.
+ *
+ * The single owner of what finishing initialization means, because `initializeSession`
+ * has two exits: screenshot mode returns early, and every other mode falls through the
+ * end. Resolving motion blur at only one of them marks the session ready with no plan,
+ * which silently renders unblurred rather than failing. Both fields are set here so a
+ * third exit cannot forget one.
+ */
+function finalizeSessionInit(session) {
+    session.motionBlur = resolveSessionMotionBlur(session);
+    session.isInitialized = true;
+}
+/** Choose how many samples this frame gets when the plan is adaptive: the floor with
+ * no probe for a frame confirmed non-spatial, otherwise two edge probes (see
+ * motionBlurProbeTimes) mapped through adaptiveSampleCount. Probe cost is returned
+ * alongside the count so the caller folds it into the frame's timing totals. */
+async function resolveAdaptiveSampleCount(session, frameIndex, absFrameIndex, plan, fps, sampleSeek) {
+    if (session.motionBlurNonSpatialFrames?.has(absFrameIndex)) {
+        return {
+            samplesPerFrame: DEFAULT_SAMPLES_PER_FRAME,
+            seekMs: 0,
+            beforeCaptureMs: 0,
+            screenshotMs: 0,
+        };
+    }
+    const { windowStart, windowEnd } = motionBlurProbeTimes(plan, absFrameIndex, fps);
+    const probeA = await captureFrameSurface(session, frameIndex, windowStart, sampleSeek);
+    const probeB = await captureFrameSurface(session, frameIndex, windowEnd, sampleSeek);
+    return {
+        samplesPerFrame: adaptiveSampleCount(probeDiffMagnitude(probeA.buffer, probeB.buffer)),
+        seekMs: probeA.seekMs + probeB.seekMs,
+        beforeCaptureMs: probeA.beforeCaptureMs + probeB.beforeCaptureMs,
+        screenshotMs: probeA.screenshotMs + probeB.screenshotMs,
+    };
+}
+/**
+ * Capture one output frame as the average of some number of sub-frame captures — fixed
+ * by the caller, or chosen per frame from measured motion (see
+ * `resolveAdaptiveSampleCount`).
+ *
+ * Callback invariant: exactly one eventful seek per output frame, at the frame time,
+ * arriving from the previous frame's time. Every sample seek (including a probe)
+ * suppresses events and the playhead is restored to the frame time afterwards, so a
+ * composition's own onUpdate/onComplete fire on the same interval boundaries as a
+ * render with blur off.
+ */
+async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan) {
+    const fps = fpsToNumber(session.options.fps);
+    const frameTime = quantizeSeekTime(absFrameIndex / fps, fps);
+    const eventfulSeekStart = Date.now();
+    await seekPageTimeline(session.page, frameTime, undefined);
+    const totals = { seekMs: Date.now() - eventfulSeekStart, beforeCaptureMs: 0, screenshotMs: 0 };
+    const sampleSeek = {
+        suppressEvents: true,
+        subFrameDivisions: plan.subFrameDivisions,
+    };
+    let samplesPerFrame = plan.fixedSamplesPerFrame;
+    if (samplesPerFrame === null) {
+        const chosen = await resolveAdaptiveSampleCount(session, frameIndex, absFrameIndex, plan, fps, sampleSeek);
+        samplesPerFrame = chosen.samplesPerFrame;
+        totals.seekMs += chosen.seekMs;
+        totals.beforeCaptureMs += chosen.beforeCaptureMs;
+        totals.screenshotMs += chosen.screenshotMs;
+    }
+    const accumulator = new MotionBlurAccumulator(plan.blend);
+    for (const sampleTime of motionBlurSampleTimes(plan, absFrameIndex, fps, samplesPerFrame)) {
+        const sample = await captureFrameSurface(session, frameIndex, sampleTime, sampleSeek);
+        totals.seekMs += sample.seekMs;
+        totals.beforeCaptureMs += sample.beforeCaptureMs;
+        totals.screenshotMs += sample.screenshotMs;
+        accumulator.add(sample.buffer);
+    }
+    const restoreSeekStart = Date.now();
+    await seekPageTimeline(session.page, frameTime, { suppressEvents: true });
+    totals.seekMs += Date.now() - restoreSeekStart;
+    const blended = accumulator.finish();
+    return {
+        buffer: encodePng(blended.width, blended.height, blended.data),
+        quantizedTime: frameTime,
+        ...totals,
+    };
+}
+async function captureFrameCore(session, frameIndex, time) {
+    const { options } = session;
     const startTime = Date.now();
     // Static-frame dedup: this frame is byte-identical to its predecessor (predicted +
     // anchor-verified at init) → reuse the prior buffer, skip the seek + screenshot.
@@ -2696,7 +2932,9 @@ 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 === absFrameIndex - 1 &&
+        (!session.motionBlur ||
+            motionBlurWindowIsStatic(session.motionBlur, absFrameIndex, session.staticFrames))) {
         session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
         session.lastFrameAbsoluteIndex = absFrameIndex;
         return {
@@ -2706,77 +2944,12 @@ async function captureFrameCore(session, frameIndex, time) {
         };
     }
     try {
-        const { quantizedTime, seekMs, beforeCaptureMs } = await prepareFrameForCapture(session, frameIndex, time);
-        const screenshotStart = Date.now();
-        let screenshotBuffer;
-        if (session.captureMode === "beginframe") {
-            const frameTimeTicks = session.beginFrameTimeTicks + frameIndex * session.beginFrameIntervalMs;
-            const result = await beginFrameCapture(page, options, frameTimeTicks, session.beginFrameIntervalMs);
-            if (result.hasDamage)
-                session.beginFrameHasDamageCount++;
-            else
-                session.beginFrameNoDamageCount++;
-            screenshotBuffer = result.buffer;
-        }
-        else if (session.captureMode === "drawelement" &&
-            session.clipBoundaryFrames?.has(frameIndex) &&
-            process.env.HF_FAST_CAPTURE_BOUNDARY_SS === "true") {
-            throw new DrawElementCaptureError(frameIndex, "boundary screenshot requested on an injected canvas page");
-        }
-        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);
-                // A tiny JPEG may be a dropped paint record. Never screenshot this page:
-                // its injected canvas can still hold the preceding frame's bitmap.
-                // Restart on a fresh screenshot page even if this was a simple valid frame.
-                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) {
-                        throw new DrawElementCaptureError(frameIndex, `suspect small frame (${screenshotBuffer.length}B < ${Math.round(floor)}B)`);
-                    }
-                    else {
-                        if (sizes.length >= 60)
-                            sizes.shift();
-                        sizes.push(screenshotBuffer.length);
-                    }
-                }
-            }
-            catch (err) {
-                // Missing paint records/canvas state require a new screenshot page.
-                if (isRecoverableDrawElementError(err)) {
-                    session.deNcprFallbacks = (session.deNcprFallbacks ?? 0) + 1;
-                    const reason = isCanvasNotInitializedError(err)
-                        ? "drawElement canvas not initialized"
-                        : "No cached paint record";
-                    throw new DrawElementCaptureError(frameIndex, reason, err);
-                }
-                else {
-                    throw err;
-                }
-            }
-        }
-        else {
-            screenshotBuffer = await pageScreenshotCapture(page, options);
-        }
-        const screenshotMs = Date.now() - screenshotStart;
+        const plan = session.motionBlur;
+        // One capture per frame, or `plan.samplesPerFrame` captures averaged into one. Both
+        // report the same timings, so perf accounting and the dedup anchor stay shared.
+        const { buffer, quantizedTime, seekMs, beforeCaptureMs, screenshotMs } = plan
+            ? await captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
+            : await captureFrameSurface(session, frameIndex, time);
         const captureTimeMs = Date.now() - startTime;
         session.capturePerf.frames += 1;
         session.capturePerf.seekMs += seekMs;
@@ -2786,10 +2959,10 @@ async function captureFrameCore(session, frameIndex, time) {
         session.capturePerf.frameMs.push(captureTimeMs);
         // Retain this freshly-captured buffer so the following static frames can reuse it.
         if (session.staticFrames) {
-            session.lastFrameBuffer = screenshotBuffer;
+            session.lastFrameBuffer = buffer;
             session.lastFrameAbsoluteIndex = absFrameIndex;
         }
-        return { buffer: screenshotBuffer, quantizedTime, captureTimeMs };
+        return { buffer, quantizedTime, captureTimeMs };
     }
     catch (captureError) {
         if (session.isInitialized) {
@@ -2803,6 +2976,15 @@ export async function captureFrame(session, frameIndex, time) {
     const framePath = writeCapturedFrame(session, frameIndex, buffer);
     return { frameIndex, time: quantizedTime, path: framePath, captureTimeMs };
 }
+/**
+ * File extension for a captured frame, keyed on the format the frames were actually
+ * captured in. The encoder's input pattern and the writer must agree, so both read this
+ * rather than re-deriving the answer from whether the OUTPUT needs alpha, which is a
+ * different question and stops being equivalent as soon as anything else forces PNG.
+ */
+export function frameFileExtension(format) {
+    return format === "png" ? "png" : "jpg";
+}
 /**
  * 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
@@ -2812,7 +2994,7 @@ export async function captureFrame(session, frameIndex, time) {
  * `captureFrameToBufferPipelined` without duplicating the naming convention.
  */
 export function writeCapturedFrame(session, fileIndex, buffer) {
-    const ext = session.options.format === "png" ? "png" : "jpg";
+    const ext = frameFileExtension(session.options.format);
     const framePath = join(session.outputDir, `frame_${String(fileIndex).padStart(6, "0")}.${ext}`);
     writeFileSync(framePath, buffer);
     return framePath;
@@ -2855,6 +3037,13 @@ export async function captureFrameToBuffer(session, frameIndex, time) {
  *  - macOS hardware GPU path (syncToPaintEvent=true, beginFrameTimeTicks=0).
  *    BeginFrame (Linux) uses the standard synchronous path unchanged.
  */
+/**
+ * Worker-encode path, gated to drawElement capture. It does not route through
+ * `captureFrameCore` and so has no accumulation branch; that is safe only because
+ * `resolveSessionMotionBlur` rejects every capture mode except screenshot, which makes
+ * this function unreachable with motion blur on. Widening the supported capture modes
+ * means handling accumulation here too.
+ */
 export async function captureFrameToBufferPipelined(session, frameIndex, time) {
     const { page, options } = session;
     const startTime = Date.now();