@hyperframes/engine 0.8.224 → 0.8.226

package/dist/config.d.ts

@@ -54,6 +54,8 @@ export interface EngineConfig {
      * `HF_STATIC_DEDUP` in {false,0,off}. Only arms in screenshot capture mode.
      */
     staticFrameDedup: boolean;
+    /** Opt-in `HF_VIDEO_LAYER_PASSTHROUGH`: ffmpeg composites a full-canvas source video under the page capture. */
+    videoLayerPassthrough: boolean;
     /**
      * Use drawElementImage for frame capture (requires the CanvasDrawElement
      * Chrome flag, added globally in buildChromeArgs). Default ON, clamped in

package/dist/config.js

@@ -29,6 +29,7 @@ export const DEFAULT_CONFIG = {
     protocolTimeout: 300_000,
     forceScreenshot: false,
     staticFrameDedup: true,
+    videoLayerPassthrough: false,
     useDrawElement: true,
     enableDrawElementWorkerEncode: true,
     // Auto-detected per host in `resolveConfig`; defaults off for the raw
@@ -72,6 +73,7 @@ const BOOLEAN_ENGINE_CONFIG_FIELDS = [
     "enableBrowserPool",
     "forceScreenshot",
     "staticFrameDedup",
+    "videoLayerPassthrough",
     "useDrawElement",
     "enableDrawElementWorkerEncode",
     "lowMemoryMode",
@@ -512,6 +514,7 @@ export function resolveConfig(overrides) {
             : undefined,
         forceScreenshot: envBool("PRODUCER_FORCE_SCREENSHOT", DEFAULT_CONFIG.forceScreenshot),
         staticFrameDedup: resolveStaticFrameDedup(),
+        videoLayerPassthrough: envBool("HF_VIDEO_LAYER_PASSTHROUGH", DEFAULT_CONFIG.videoLayerPassthrough),
         useDrawElement: envBool("PRODUCER_EXPERIMENTAL_FAST_CAPTURE", DEFAULT_CONFIG.useDrawElement),
         enableDrawElementWorkerEncode: envBool("HF_DE_WORKER_ENCODE", DEFAULT_CONFIG.enableDrawElementWorkerEncode),
         lowMemoryMode: resolveLowMemoryMode(),

package/dist/index.d.ts

@@ -47,7 +47,8 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, type ProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
-export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, type VideoElement, type ImageElement, type ExtractedFrames, type DeferredFrameRange, type FrameRange, type ExtractionOptions, type ExtractionResult, type ExtractionPhaseBreakdown, type TimelineExtractionWindow, type VideoExtractionFailure, type VideoExtractionFailureKind, type VideoExtractionFailureGroupDetails, type VideoExtractionFailureRetry, type VideoExtractionFailureStatusClass, type SafeVideoExtractionSourceIdentity, type VideoFrameFormat, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, buildVideoLayerInput, type VideoLayerInput, } from "./services/videoFrameExtractor.js";
+export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";

package/dist/index.js

@@ -51,7 +51,8 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, getCachedGpuEncoder, ENCODER_PRESETS, getEncoderPreset, PRORES_PROFILES, PRORES_PROFILE_NAMES, isProresProfile, appendRateCapArgs, keyframeIntervalToGopSize, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
-export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
+export { parseVideoElements, hasGradedCanvas, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, videoStartOnMediaTimeline, ffmpegSeekSeconds, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, sdrCanvasColourFilters, buildVideoLayerInput, } from "./services/videoFrameExtractor.js";
+export { qualifyVideoLayer } from "./services/videoLayerPassthrough.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";

package/dist/services/audioMixer.js

@@ -5,7 +5,7 @@ import { renameWithRetry } from "@hyperframes/core/rename-retry";
 import { removeScratch } from "@hyperframes/core/remove-scratch";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
-import { extractAudioMetadata, ffmpegSeekSeconds } from "../utils/ffprobe.js";
+import { extractAudioMetadata, ffmpegSeekSeconds, formatFfmpegSeconds, } from "../utils/ffprobe.js";
 import { isNotMediaPayload } from "../utils/notMediaPayload.js";
 import { urlInputArgs } from "../utils/urlInput.js";
 import { clampAudioGain, clipGain } from "@hyperframes/core/audio-gain";
@@ -550,7 +550,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
                 "-stream_loop",
                 "-1",
                 "-t",
-                String(sourceDuration),
+                formatFfmpegSeconds(sourceDuration),
                 "-i",
                 cyclePath,
                 "-vn",
@@ -560,7 +560,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
                 "48000",
                 ...outputArgs,
                 "-t",
-                String(duration),
+                formatFfmpegSeconds(duration),
                 "-y",
                 outputPath,
             ], { signal, timeout: ffmpegProcessTimeout });
@@ -598,14 +598,19 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
         ...(readsUrl ? FAIL_ON_READ_ERROR_INSTEAD_OF_ENDING_THERE : []),
         ...urlInputArgs(readFrom),
         ...(inputSeek
-            ? ["-ss", String(ffmpegStart - warmUp), "-t", String(sourceDuration + warmUp)]
+            ? [
+                "-ss",
+                formatFfmpegSeconds(ffmpegStart - warmUp),
+                "-t",
+                formatFfmpegSeconds(sourceDuration + warmUp),
+            ]
             : []),
         "-i",
         readFrom,
     ];
     args.push("-vn", "-acodec", "pcm_s16le", "-ar", "48000", ...outputArgs);
     if (normalizedPlaybackRate !== 1 || options?.padToDuration)
-        args.push("-t", String(duration));
+        args.push("-t", formatFfmpegSeconds(duration));
     args.push("-y", outputPath);
     const result = await runFfmpeg(args, { signal, timeout: ffmpegProcessTimeout });
     if (signal?.aborted) {
@@ -660,7 +665,7 @@ async function generateSilence(outputPath, duration, signal, config) {
         "-i",
         "anullsrc=r=48000:cl=stereo",
         "-t",
-        String(duration),
+        formatFfmpegSeconds(duration),
         "-acodec",
         "pcm_s16le",
         "-y",
@@ -761,7 +766,7 @@ async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, con
             "-ar",
             "48000",
             "-t",
-            String(totalDuration),
+            formatFfmpegSeconds(totalDuration),
             "-y",
             outputPath,
         ];
@@ -923,7 +928,7 @@ async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, sign
                 "-ar",
                 "48000",
                 "-t",
-                String(totalDuration),
+                formatFfmpegSeconds(totalDuration),
                 "-y",
                 outputPath,
             ];

package/dist/services/frameCapture.d.ts

@@ -494,7 +494,7 @@ export declare function isStaticDedupFrameAnalysisSafe(totalFrames: number): boo
  * comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
  * a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
  */
-export declare function computeStaticFrameSet(page: Page, fps: number): Promise<{
+export declare function computeStaticFrameSet(page: Page, fps: number, ignoredVideoIds?: readonly string[]): Promise<{
     totalFrames: number;
     staticFrameSet: Set<number>;
     /** Frames whose only active motion is non-spatial (opacity, colour); safe to skip

package/dist/services/frameCapture.js

@@ -716,7 +716,11 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         }
     }
     else if (capturesAlpha(session.options)) {
-        await initTransparentBackground(session.page);
+        const hideElementIds = session.options.hiddenElementIds ?? [];
+        await initTransparentBackground(session.page, {
+            clearCompositionRoot: hideElementIds.length > 0,
+            hideElementIds,
+        });
     }
 }
 /** Worker-encode pipeline: macOS hardware GPU path only, JPEG output only. */
@@ -2447,8 +2451,8 @@ export function isStaticDedupFrameAnalysisSafe(totalFrames) {
  * comp on any signal the tween-walker can't see: video / canvas / webgl (redraw without
  * a tween), zero tweens (non-GSAP animation), or a running CSS/WAAPI animation.
  */
-export async function computeStaticFrameSet(page, fps) {
-    const result = await page.evaluate((spatialProps) => {
+export async function computeStaticFrameSet(page, fps, ignoredVideoIds = []) {
+    const result = await page.evaluate((spatialProps, ignored) => {
         // 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).
@@ -2463,20 +2467,8 @@ export async function computeStaticFrameSet(page, fps) {
         }
         const intervals = [];
         let tweenCount = 0;
-        // totalDuration() (NOT duration()): a repeat/yoyo tween animates past one iteration;
-        // a repeating timeline is marked opaque over its whole span (conservative).
-        // A GSAP tl.call() is a zero-duration tween whose vars wire the callback as
-        // onComplete (and onReverseComplete, fired on backward crossing — GSAP has
-        // no separate "undo" callback, so both directions invoke the SAME forward
-        // side effect). A one-shot DOM mutation driven this way (e.g. a counter's
-        // textContent) is not seek-idempotent: crossing it during the static-dedup
-        // verifier's own arm-time seeking permanently mutates the page, and that
-        // corruption can leak into a LATER, unrelated static run's real capture
-        // (the verifier's mismatch check only catches drift within the run being
-        // checked, not contamination from a run checked afterward). No reliable
-        // way to tell a DOM-mutating call() from a harmless one (analytics ping,
-        // class toggle with no visual effect) without executing it, so disqualify
-        // the whole comp on ANY call() rather than risk shipping wrong pixels.
+        // totalDuration(), not duration(): repeat/yoyo tweens animate past one iteration.
+        // Any tl.call() disqualifies the comp: its DOM side effects are not seek-idempotent.
         let hasTimelineCall = false;
         function walk(tl, offset) {
             if (typeof tl.getChildren !== "function")
@@ -2500,12 +2492,7 @@ export async function computeStaticFrameSet(page, fps) {
                         // 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
-                        // gap otherwise — the arm-time verifier can still forward-seek
-                        // through this span while checking a LATER static run, firing
-                        // the call() and corrupting the page (review).
+                        // Still descend: a call() inside the repeating span would otherwise go undetected.
                         walk(child, start);
                     }
                     else {
@@ -2528,7 +2515,7 @@ export async function computeStaticFrameSet(page, fps) {
             if (tl && typeof tl.getChildren === "function")
                 walk(tl, 0);
         }
-        const hasVideo = !!document.querySelector("video");
+        const hasVideo = Array.from(document.querySelectorAll("video")).some((v) => !ignored.includes(v.id));
         const hasCanvas = !!document.querySelector("canvas");
         const hasFrameSources = w.__hfHasFrameSources?.() ?? false;
         const hasIframe = !!document.querySelector("iframe");
@@ -2543,7 +2530,8 @@ export async function computeStaticFrameSet(page, fps) {
         // getAnimations(); any running/paused one can change content without a tween.
         let hasNonGsapAnim = false;
         try {
-            const docAnims = document.getAnimations;
+            const docAnims = document
+                .getAnimations;
             if (typeof docAnims === "function") {
                 hasNonGsapAnim = docAnims.call(document).some((a) => {
                     const t = a;
@@ -2566,7 +2554,7 @@ export async function computeStaticFrameSet(page, fps) {
             hasUnresolvableClipStart,
             hasTimelineCall,
         };
-    }, SPATIAL_TWEEN_PROPERTIES);
+    }, SPATIAL_TWEEN_PROPERTIES, [...ignoredVideoIds]);
     const { intervals, tweenCount, duration, hasVideo, hasCanvas, hasFrameSources, hasIframe, hasNonGsapAnim, hasUnresolvableClipStart, hasTimelineCall, } = result;
     const totalFrames = Math.max(1, Math.ceil(duration * fps));
     if (!isStaticDedupFrameAnalysisSafe(totalFrames)) {
@@ -2651,12 +2639,13 @@ export async function computeStaticFrameSet(page, fps) {
 // what fixes long runs going nearly unverified — deliberately NOT derived from
 // sampleCount, so that knob's effect on density stays monotonic (see below).
 const STATIC_VERIFY_REFERENCE_STRIDE = 24;
-// Verification uses full-page screenshots, whose cost scales with canvas size
-// and page complexity rather than frame count. Bound wall time as well as the
-// capture count so a long composition cannot spend minutes proving an
-// optimization before the real render starts. Exhaustion fails closed: dedup is
-// disabled and normal capture proceeds.
+// Wall budget for verification: 15 s is the floor; above it the budget is 1.5x
+// planned shots x the first shot's seek+capture time, capped at 300 s (nothing
+// was gained past 600 s on a 4K job). Exhaustion fails closed: dedup is
+// disabled for the unverified runs and normal capture proceeds.
 const STATIC_VERIFY_MAX_MS = 15_000;
+const STATIC_VERIFY_HEADROOM = 1.5;
+const STATIC_VERIFY_CEILING_MS = 300_000;
 // Two captures (anchor + comparison) are the minimum proof for a run. Four hundred
 // therefore permits 200 fully verified runs while bounding pathological schedules.
 const STATIC_VERIFY_MIN_SCREENSHOT_CAP = 400;
@@ -2817,7 +2806,6 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
     const now = dependencies.now ?? Date.now;
     const capture = dependencies.capture ?? pageScreenshotCapture;
     const startedAt = now();
-    const deadline = startedAt + STATIC_VERIFY_MAX_MS;
     const verifiedFrames = new Set();
     const stats = {
         plannedRuns: plan.runs.length,
@@ -2852,14 +2840,21 @@ export async function verifyStaticFramesSafe(session, page, staticFrames, fps, s
         }, t);
     };
     const hardCap = Math.max(STATIC_VERIFY_MIN_SCREENSHOT_CAP, plan.effectiveSampleFloor * STATIC_VERIFY_SAMPLE_CAP_MULTIPLIER, Math.ceil(plan.predictedFrames / STATIC_VERIFY_REFERENCE_STRIDE) * 3 + plan.runs.length);
+    let firstShotMs = 0;
     const seekCapture = async (frameIdx) => {
-        if (now() >= deadline)
+        const spent = now() - startedAt;
+        const budget = Math.max(STATIC_VERIFY_MAX_MS, Math.min(STATIC_VERIFY_CEILING_MS, STATIC_VERIFY_HEADROOM * plan.plannedScreenshots * firstShotMs));
+        if (spent >= budget)
             return "time_budget";
         if (stats.screenshots >= hardCap)
             return "count_budget";
+        const shotStart = now();
         await seekToFrame(frameIdx);
         stats.screenshots++;
-        return capture(page, session.options);
+        const buf = await capture(page, session.options);
+        if (stats.screenshots === 1)
+            firstShotMs = now() - shotStart;
+        return buf;
     };
     // Verify profitable runs in deterministic savings order. A run is added to the armed
     // set only after its anchor and every planner-selected comparison match. Budget exits
@@ -2922,7 +2917,7 @@ async function armStaticDedup(session, page, logInitPhase) {
     if (session.options.motionBlur &&
         session.options.motionBlur.samplesPerFrame === undefined &&
         !session.motionBlurNonSpatialFrames) {
-        sharedStaticFrameStats = await computeStaticFrameSet(page, fpsToNumber(session.options.fps));
+        sharedStaticFrameStats = await computeStaticFrameSet(page, fpsToNumber(session.options.fps), session.options.hiddenElementIds);
         session.motionBlurNonSpatialFrames = sharedStaticFrameStats.nonSpatialOnlyFrameSet;
     }
     // Idempotent: the drawElement init path arms dedup BEFORE canvas injection
@@ -2971,7 +2966,8 @@ async function armStaticDedup(session, page, logInitPhase) {
         return;
     }
     const fps = fpsToNumber(session.options.fps);
-    const stats = sharedStaticFrameStats ?? (await computeStaticFrameSet(page, fps));
+    const stats = sharedStaticFrameStats ??
+        (await computeStaticFrameSet(page, fps, session.options.hiddenElementIds));
     if (!stats.eligible || stats.staticFrameSet.size === 0) {
         session.staticDedupSkipReason = "ineligible";
         logInitPhase(`static-frame dedup: disabled (${stats.reason})`);
@@ -4175,6 +4171,7 @@ export function getCapturePerfSummary(session) {
         avgSeekMs: Math.round(session.capturePerf.seekMs / frames),
         avgBeforeCaptureMs: Math.round(session.capturePerf.beforeCaptureMs / frames),
         avgScreenshotMs: Math.round(session.capturePerf.screenshotMs / frames),
+        captureBeyondViewport: session.options.captureBeyondViewport,
         p50TotalMs: medianOf(session.capturePerf.frameMs),
         p95TotalMs: percentileOf(session.capturePerf.frameMs, 0.95),
         p99TotalMs: percentileOf(session.capturePerf.frameMs, 0.99),

package/dist/services/screenshotService.d.ts

@@ -80,8 +80,9 @@ export declare function captureScreenshotWithAlpha(page: Page, width: number, he
  */
 /** Whether frames must carry alpha. PNG alone does not imply it: motion blur captures opaque output as PNG. */
 export declare function capturesAlpha(options: Pick<CaptureOptions, "format" | "transparent">): boolean;
-export declare function initTransparentBackground(page: Page, { clearCompositionRoot }?: {
+export declare function initTransparentBackground(page: Page, { clearCompositionRoot, hideElementIds, }?: {
     clearCompositionRoot?: boolean;
+    hideElementIds?: readonly string[];
 }): Promise<void>;
 /**
  * Capture a transparent-background PNG screenshot without setting the

package/dist/services/screenshotService.js

@@ -239,12 +239,12 @@ export function capturesAlpha(options) {
     return options.transparent ?? options.format === "png";
 }
 const TRANSPARENT_BG_STYLE_ID = "__hf_transparent_bg__";
-export async function initTransparentBackground(page, { clearCompositionRoot = false } = {}) {
+export async function initTransparentBackground(page, { clearCompositionRoot = false, hideElementIds = [], } = {}) {
     const client = await getCdpSession(page);
     await client.send("Emulation.setDefaultBackgroundColorOverride", {
         color: { r: 0, g: 0, b: 0, a: 0 },
     });
-    await page.evaluate((styleId, clearCompositionRoot) => {
+    await page.evaluate((styleId, clearCompositionRoot, hideIds) => {
         const selector = clearCompositionRoot ? "html,body,[data-composition-id]" : "html,body";
         let style = document.getElementById(styleId);
         if (!style) {
@@ -252,8 +252,11 @@ export async function initTransparentBackground(page, { clearCompositionRoot = f
             style.id = styleId;
             document.head.appendChild(style);
         }
-        style.textContent = `${selector}{background:transparent !important;background-color:transparent !important;background-image:none !important;}`;
-    }, TRANSPARENT_BG_STYLE_ID, clearCompositionRoot);
+        const hidden = hideIds.map((id) => `#${CSS.escape(id)}`).join(",");
+        style.textContent =
+            `${selector}{background:transparent !important;background-color:transparent !important;background-image:none !important;}` +
+                (hidden ? `${hidden}{visibility:hidden !important;}` : "");
+    }, TRANSPARENT_BG_STYLE_ID, clearCompositionRoot, [...hideElementIds]);
 }
 /**
  * Capture a transparent-background PNG screenshot without setting the

package/dist/services/streamingEncoder.d.ts

@@ -14,6 +14,7 @@
 import { type GpuEncoder } from "../utils/gpuEncoder.js";
 import { type EngineConfig } from "../config.js";
 import { type Fps } from "@hyperframes/core";
+import type { VideoLayerInput } from "./videoFrameExtractor.js";
 export type { EncoderOptions } from "./chunkEncoder.types.js";
 export interface FrameReorderBuffer {
     waitForFrame: (frame: number) => Promise<void>;
@@ -48,6 +49,8 @@ export interface StreamingEncoderOptions {
     hdr?: {
         transfer: import("../utils/hdr.js").HdrTransfer;
     };
+    /** A source video ffmpeg composites under the piped RGBA frames; see `buildVideoLayerInput`. */
+    videoLayer?: VideoLayerInput;
     /** When set, use rawvideo input instead of image2pipe. For HDR PQ-encoded frames. */
     rawInputFormat?: "rgb48le";
     /**

package/dist/services/streamingEncoder.js

@@ -119,8 +119,17 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
         const inputCodec = imageFormat === "png" ? "png" : "mjpeg";
         args.push("-f", "image2pipe", "-vcodec", inputCodec, "-framerate", fpsToFfmpegArg(fps), "-i", "-");
     }
+    if (options.videoLayer)
+        args.push(...options.videoLayer.inputArgs);
     args.push("-r", fpsToFfmpegArg(fps));
     const shouldUseGpu = useGpu && gpuEncoder !== null;
+    if (options.videoLayer &&
+        (imageFormat !== "png" ||
+            options.rawInputFormat ||
+            shouldUseGpu ||
+            (codec !== "h264" && codec !== "h265"))) {
+        throw new Error("videoLayer needs software h264/h265 and PNG frames");
+    }
     appendRateCapArgs(args, options);
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
@@ -266,6 +275,11 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
                 args[vfIdx + 1] = `${frameFilter},${args[vfIdx + 1]}`;
             }
         }
+        else if (options.videoLayer) {
+            const video = `[1:v]${options.videoLayer.filters.join(",")},format=gbrp[v]`;
+            const tail = withEvenDimensionPad(SDR_RGB_TO_TAGGED_BT709_FILTER, pixelFormat, options.width, options.height);
+            args.push("-filter_complex", `${video};[0:v]format=rgba[o];[v][o]overlay=format=gbrp,${tail}[vout]`, "-map", "[vout]");
+        }
         else {
             // Pad odd dimensions up to even so 4:2:0 encoders (software and
             // nvenc/videotoolbox/qsv/amf) don't abort with "height not divisible by 2".

package/dist/services/videoFrameExtractor.d.ts

@@ -5,7 +5,7 @@
  * Videos are replaced with <img> elements during capture.
  */
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
-import { type RateSpec, type FpsInput } from "@hyperframes/core";
+import { type RateSpec, type Fps, type FpsInput } from "@hyperframes/core";
 import { ffmpegSeekSeconds, resolvePlayableVideoDuration, videoStartOnMediaTimeline, type VideoMetadata } from "../utils/ffprobe.js";
 import { type HdrTransfer } from "../utils/hdr.js";
 import { type EngineConfig } from "../config.js";
@@ -195,7 +195,11 @@ export interface VideoExtractionFailure {
     error: string;
     /** ffmpeg's last stderr lines, without paths or URLs: what a producer-facing error may say. */
     ffmpegReason?: string;
+    /** The clip's file, project-relative; a remote source shows only its file name. Safe for producer-facing errors. */
+    source?: string;
 }
+/** A clip's src as a producer-facing error may print it: no scheme payload, host, query, fragment or absolute path. */
+export declare function videoExtractionSourceLabel(src: string, baseDir: string): string;
 export type VideoExtractionFailureStatusClass = "http_4xx" | "http_5xx" | "timeout" | "network" | "other";
 export interface VideoExtractionFailureRetry {
     phase: "download";
@@ -270,6 +274,15 @@ export declare function hasGradedCanvas(html: string): boolean;
 export declare function parseImageElements(html: string): ImageElement[];
 export declare function sdrCanvasColourFilters(metadata: VideoMetadata, toneMappedToSdr?: boolean): string[];
 export declare function extractVideoFramesRange(...args: Parameters<typeof extractVideoFramesRangeUnredacted>): Promise<ExtractedFrames>;
+export interface VideoLayerInput {
+    inputArgs: string[];
+    filters: string[];
+}
+/** ffmpeg input and filters showing the same frames and colour as extraction; undefined if unsupported. */
+export declare function buildVideoLayerInput(videoPath: string, startTime: number, duration: number, fps: Fps, canvas: {
+    width: number;
+    height: number;
+}, fit?: "fill" | "cover"): Promise<VideoLayerInput | undefined>;
 declare function extractVideoFramesRangeUnredacted(videoPath: string, videoId: string, startTime: number, duration: number, options: ExtractionOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>, 
 /** Frames go straight here, with no per-videoId subdir (the cache layer's keyed entry). */
 outputDirOverride?: string): Promise<ExtractedFrames>;
@@ -313,6 +326,7 @@ export interface TimelineExtractionWindow {
 }
 type TimelineWindowVideo = Pick<VideoElement, "start" | "end" | "mediaStart"> & Partial<Pick<VideoElement, "playbackRate">> & Partial<Pick<VideoElement, "loop">>;
 export declare function isVideoPastTimelineEnd(video: Pick<VideoElement, "start">, timelineEnd: number): boolean;
+export declare function alignClipStartToFirstOutputFrame(video: VideoElement, fps: number): void;
 /** Move a clip to its extraction window; a rate lane is shifted so it keeps integrating from the new origin. */
 export declare function rebaseVideoToWindow(video: VideoElement, window: TimelineExtractionWindow): void;
 /**

package/dist/services/videoFrameExtractor.js

@@ -7,7 +7,7 @@
  */
 import { audioGroupsById, isMemberGroupHidden, isSelfOrAncestorHidden } from "./mediaHidden.js";
 import { copyFileSync, existsSync, linkSync, mkdirSync, rmSync } from "fs";
-import { basename, join } from "path";
+import { basename, isAbsolute, join, normalize, relative, win32 } from "path";
 import { cpus } from "os";
 import { createConcurrencyLimit } from "../utils/concurrencyLimit.js";
 import { parseHTML } from "linkedom";
@@ -18,7 +18,7 @@ import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, ffmpegSeekSeconds, formatFfmpegSeconds, keyframeGapSeconds, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, videoStartOnMediaTimeline, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -168,6 +168,28 @@ async function hdrToSdrTransformKey() {
 function sdrToHdrTransformKey(transfer) {
     return `sdr2hdr-${transfer}`;
 }
+const URL_SCHEME = /^[a-z][a-z0-9+.-]+:/i;
+const WINDOWS_ABSOLUTE = /^([a-zA-Z]:[\\/]|\\\\)/;
+/** A clip's src as a producer-facing error may print it: no scheme payload, host, query, fragment or absolute path. */
+export function videoExtractionSourceLabel(src, baseDir) {
+    if (/^(data|blob):/i.test(src))
+        return "inline video";
+    if (URL_SCHEME.test(src)) {
+        try {
+            return basename(decodeURIComponent(new URL(src).pathname)) || "remote video";
+        }
+        catch {
+            return "remote video";
+        }
+    }
+    const path = src.split(/[?#]/)[0];
+    const lib = WINDOWS_ABSOLUTE.test(path) ? win32 : { isAbsolute, relative, basename, normalize };
+    const relativePath = lib.isAbsolute(path) ? lib.relative(baseDir, path) : lib.normalize(path);
+    const label = relativePath.startsWith("..") || lib.isAbsolute(relativePath)
+        ? lib.basename(path)
+        : relativePath;
+    return label.replace(/\\/g, "/");
+}
 /** Query/fragment-free remote identity safe for extraction logs and wire metadata. */
 export function safeVideoExtractionSourceIdentity(source) {
     if (!isHttpUrl(source))
@@ -593,12 +615,12 @@ async function runSegmentedExtraction(job) {
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
-                String(job.ffmpegSeek(seek)),
+                formatFfmpegSeconds(job.ffmpegSeek(seek)),
                 "-i",
                 videoPath,
                 // Read one frame past the segment and keep exactly its own frames.
                 "-t",
-                String((frames + 1) / fps),
+                formatFfmpegSeconds((frames + 1) / fps),
                 "-frames:v",
                 String(frames),
                 "-start_number",
@@ -645,6 +667,86 @@ export async function extractVideoFramesRange(...args) {
         throw redactUrlQueriesInError(error);
     }
 }
+/** The one place that decides which source frame a slot shows and how its colour is converted. */
+function videoFilterChain(input) {
+    const { metadata, format, ffmpegFps, sampleAtOutputFps, keepsHdrForChrome, toneMapFrom } = input;
+    const toneMappedToSdr = toneMapFrom !== undefined;
+    const head = [];
+    if (keepsHdrForChrome)
+        head.push("format=nv12");
+    const tail = [];
+    if (metadata.sampleAspectRatio) {
+        tail.push("scale=trunc(iw*sar/2)*2:ih", "setsar=1");
+    }
+    // Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
+    // first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
+    const sampling = (seek) => sampleAtOutputFps
+        ? [
+            ...(metadata.isVFR
+                ? []
+                : undoTickRoundingOnTheSourceFrameGrid(seek, videoStartOnMediaTimeline(metadata))),
+            "settb=intb/2",
+            "setpts=PTS-lte(TB\\,0.001)",
+            `fps=${ffmpegFps}:start_time=0:round=up`,
+        ]
+        : [];
+    if (input.sdrToHdrTransfer) {
+        // Fps sampling runs before the colorspace remap so only kept frames are converted. The
+        // remap is pointwise, so the result is identical either way for the SDR inputs it applies
+        // to (it never meets nv12, which is HDR-only); revisit if the two ever combine.
+        tail.push(SDR_TO_HDR_COLORSPACE_FILTER);
+    }
+    if (toneMapFrom) {
+        tail.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, toneMapFrom));
+    }
+    if (toneMappedToSdr || (!input.isHdr && !input.sdrToHdrTransfer)) {
+        tail.push(...sdrCanvasColourFilters(metadata, toneMappedToSdr));
+        if (format === "jpg") {
+            if (input.shownBox)
+                tail.push(halveToCoverScaleFilter(input.shownBox));
+            tail.push(SDR_JPEG_AS_BT601_FULL_RANGE_FILTER);
+        }
+    }
+    return (seek) => [...head, ...sampling(seek), ...tail];
+}
+/** ffmpeg input and filters showing the same frames and colour as extraction; undefined if unsupported. */
+export async function buildVideoLayerInput(videoPath, startTime, duration, fps, canvas, fit = "fill") {
+    const metadata = await extractMediaMetadata(videoPath);
+    if (startTime + duration > resolvePlayableVideoDuration(metadata) + 1e-3 ||
+        isHdrColorSpaceUtil(metadata.colorSpace) ||
+        metadata.isVFR ||
+        metadata.hasAlpha ||
+        codecMayHaveAlpha(metadata.videoCodec)) {
+        return undefined;
+    }
+    const chain = videoFilterChain({
+        metadata,
+        format: "png",
+        ffmpegFps: fpsToFfmpegArg(fps),
+        sampleAtOutputFps: true,
+        keepsHdrForChrome: false,
+        isHdr: false,
+    });
+    const filters = chain(startTime);
+    if (metadata.width !== canvas.width || metadata.height !== canvas.height) {
+        filters.push(fit === "cover"
+            ? `scale=${canvas.width}:${canvas.height}:force_original_aspect_ratio=increase:flags=bicubic,crop=${canvas.width}:${canvas.height}`
+            : `scale=${canvas.width}:${canvas.height}:flags=bicubic`);
+    }
+    return {
+        inputArgs: [
+            "-noaccurate_seek",
+            "-ss",
+            formatFfmpegSeconds(ffmpegSeekSeconds(metadata, startTime)),
+            ...urlInputArgs(videoPath),
+            "-i",
+            videoPath,
+            "-t",
+            formatFfmpegSeconds(duration),
+        ],
+        filters,
+    };
+}
 async function extractVideoFramesRangeUnredacted(videoPath, videoId, startTime, duration, options, signal, config, 
 /** Frames go straight here, with no per-videoId subdir (the cache layer's keyed entry). */
 outputDirOverride) {
@@ -709,56 +811,26 @@ outputDirOverride) {
         // sample. This is intentionally reserved for the one-frame path: input
         // seeking is faster, but valid unindexed transports (notably MPEG-TS with
         // a negative timestamp base) can seek to EOF and emit zero frames.
-        args.push("-i", videoPath, "-ss", String(Math.max(0, ffmpegSeek(startTime))), "-frames:v", "1");
+        args.push("-i", videoPath, "-ss", formatFfmpegSeconds(Math.max(0, ffmpegSeek(startTime))), "-frames:v", "1");
     }
     else {
         // An accurate seek drops the frame on screen at startTime; the fps sampling below needs it.
         if (sampleAtOutputFps)
             args.push("-noaccurate_seek");
-        args.push("-ss", String(ffmpegSeek(startTime)), "-i", videoPath, "-t", String(duration));
-    }
-    const vfFilters = [];
-    if (keepsHdrForChrome) {
-        vfFilters.push("format=nv12");
-    }
-    const samplingAt = vfFilters.length;
-    if (metadata.sampleAspectRatio) {
-        vfFilters.push("scale=trunc(iw*sar/2)*2:ih", "setsar=1");
-    }
-    // Each slot takes the last frame starting at or before its time. Ticks of 2 ms or finer
-    // first shift half a tick, absorbing container rounding (WebM/MKV use whole ms).
-    const samplingFilters = (seek) => sampleAtOutputFps
-        ? [
-            ...(metadata.isVFR
-                ? []
-                : undoTickRoundingOnTheSourceFrameGrid(seek, videoStartOnMediaTimeline(metadata))),
-            "settb=intb/2",
-            "setpts=PTS-lte(TB\\,0.001)",
-            `fps=${ffmpegFps}:start_time=0:round=up`,
-        ]
-        : [];
-    if (options.sdrToHdrTransfer) {
-        // Ordering intent: fps sampling runs BEFORE the colorspace remap so only
-        // kept frames are converted. The remap is pointwise per-frame, so the
-        // output is identical either way for the SDR (BT.709, 8-bit) inputs this
-        // flag is set for. If format=nv12 (macOS HDR-source decode) ever combines
-        // with this flag, revisit: nv12 subsampling before a BT.2020 remap is an
-        // untested interaction (today the flags are mutually exclusive — the
-        // remap only applies to SDR sources, nv12 only to HDR sources).
-        vfFilters.push(SDR_TO_HDR_COLORSPACE_FILTER);
-    }
-    if (toneMappedToSdr) {
-        const frameColour = await readFirstFrameColour(videoPath);
-        vfFilters.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, frameColour));
-    }
-    if (toneMappedToSdr || (!isHdr && !options.sdrToHdrTransfer)) {
-        vfFilters.push(...sdrCanvasColourFilters(metadata, toneMappedToSdr));
-        if (format === "jpg") {
-            if (options.shownBox)
-                vfFilters.push(halveToCoverScaleFilter(options.shownBox));
-            vfFilters.push(SDR_JPEG_AS_BT601_FULL_RANGE_FILTER);
-        }
+        args.push("-ss", formatFfmpegSeconds(ffmpegSeek(startTime)), "-i", videoPath, "-t", formatFfmpegSeconds(duration));
     }
+    const frameColour = toneMappedToSdr ? await readFirstFrameColour(videoPath) : undefined;
+    const filtersFor = videoFilterChain({
+        metadata,
+        format,
+        ffmpegFps,
+        sampleAtOutputFps,
+        keepsHdrForChrome,
+        toneMapFrom: frameColour,
+        isHdr,
+        sdrToHdrTransfer: options.sdrToHdrTransfer,
+        shownBox: options.shownBox,
+    });
     const encodeArgs = ["-q:v", format === "jpg" ? String(Math.ceil((100 - quality) / 3)) : "0"];
     // Render-scoped temp frames are read once; level 1 measured 3-5x faster for ~14% larger files.
     if (format === "png")
@@ -766,8 +838,7 @@ outputDirOverride) {
     encodeArgs.push("-y", outputPattern);
     const runOptions = { signal, timeout: ffmpegProcessTimeout };
     const filterArgsFor = (seek) => {
-        const filters = [...vfFilters];
-        filters.splice(samplingAt, 0, ...samplingFilters(seek));
+        const filters = filtersFor(seek);
         return filters.length > 0 ? ["-vf", filters.join(",")] : [];
     };
     const segmentFrames = Math.round(EXTRACTION_SEGMENT_SECONDS * fps);
@@ -917,14 +988,17 @@ const FINAL_FRAME_LOGICAL_DURATION_SECONDS = 1e-6;
 export function isVideoPastTimelineEnd(video, timelineEnd) {
     return video.start >= timelineEnd;
 }
-function alignClipStartToFirstOutputFrame(video, fps) {
+export function alignClipStartToFirstOutputFrame(video, fps) {
     if (video.loop || !Number.isFinite(video.start) || video.start < 0 || !(fps > 0))
         return;
     const position = exportClipWindow(video.start, Infinity, fps).start * fps;
     const firstFrame = Math.abs(position - Math.round(position)) < 1e-6 ? Math.round(position) : Math.ceil(position);
     const shift = firstFrame / fps - video.start;
-    if (shift === 0)
+    // Float dust (a sum landing a hair off the grid) snaps the start; it never reaches mediaStart.
+    if (Math.abs(shift) < 1e-9) {
+        video.start = firstFrame / fps;
         return;
+    }
     const playbackRate = normalizeRateSpec(video.playbackRate);
     video.mediaStart += sourceTimeAt(playbackRate, shift);
     video.playbackRate = shiftRateLane(playbackRate, shift);
@@ -1908,10 +1982,16 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         breakdown.cacheGcBytesFreed = gcStats.evictedBytes;
         breakdown.cacheAgedPartialsCleared = gcStats.agedPartialsRemoved;
     }
+    const srcById = new Map(videos.map((video) => [video.id, video.src]));
     return {
         success: errors.length === 0,
         extracted,
-        errors,
+        errors: errors.map((failure) => {
+            const src = srcById.get(failure.videoId);
+            return src === undefined
+                ? failure
+                : { ...failure, source: videoExtractionSourceLabel(src, baseDir) };
+        }),
         totalFramesExtracted,
         durationMs: Date.now() - startTime,
         phaseBreakdown: breakdown,

package/dist/services/videoLayerPassthrough.d.ts

@@ -0,0 +1,10 @@
+import type { VideoElement } from "./videoFrameExtractor.js";
+export type VideoLayerQualification = {
+    qualifies: true;
+    video: VideoElement;
+} | {
+    qualifies: false;
+    reason: string;
+};
+/** One video that alone fills the whole timeline at normal speed, ungraded; layout is checked in the page. */
+export declare function qualifyVideoLayer(videos: readonly VideoElement[], compositionDuration: number): VideoLayerQualification;

package/dist/services/videoLayerPassthrough.js

@@ -0,0 +1,24 @@
+const EDGE_EPSILON_SECONDS = 1e-3;
+/** One video that alone fills the whole timeline at normal speed, ungraded; layout is checked in the page. */
+export function qualifyVideoLayer(videos, compositionDuration) {
+    if (videos.length !== 1)
+        return { qualifies: false, reason: "video_count" };
+    const video = videos[0];
+    if (!video)
+        return { qualifies: false, reason: "video_count" };
+    if (video.hidden)
+        return { qualifies: false, reason: "hidden" };
+    if (video.graded)
+        return { qualifies: false, reason: "color_grading" };
+    if (video.loop)
+        return { qualifies: false, reason: "loop" };
+    if (video.playbackRate !== undefined && video.playbackRate !== 1) {
+        return { qualifies: false, reason: "playback_rate" };
+    }
+    if (video.start > EDGE_EPSILON_SECONDS)
+        return { qualifies: false, reason: "late_start" };
+    if (video.end < compositionDuration - EDGE_EPSILON_SECONDS) {
+        return { qualifies: false, reason: "ends_early" };
+    }
+    return { qualifies: true, video };
+}

package/dist/types.d.ts

@@ -154,6 +154,7 @@ export interface CaptureOptions {
     fps: Fps;
     format?: "jpeg" | "png";
     transparent?: boolean;
+    hiddenElementIds?: string[];
     quality?: number;
     /**
      * Opt into sub-frame multi-sample motion blur (issue #4010). Absent means off and the
@@ -250,6 +251,7 @@ export interface CapturePerfSummary {
     avgSeekMs: number;
     avgBeforeCaptureMs: number;
     avgScreenshotMs: number;
+    captureBeyondViewport?: boolean;
     /**
      * Median per-frame capture time — warmup-robust, unlike `avgTotalMs`
      * (first frames pay font/image decode + GC that swamps short renders'

package/dist/utils/ffprobe.d.ts

@@ -128,6 +128,7 @@ export declare function readProbeJson(filePath: string, signal?: AbortSignal): P
 /** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */
 export declare function buildProbeFactsText(filePath: string, signal?: AbortSignal): Promise<string>;
 export declare function videoStartOnMediaTimeline(metadata: Pick<VideoMetadata, "videoStreamLeadSeconds" | "mediaTimeOffsetSeconds">): number;
+export declare function formatFfmpegSeconds(seconds: number): string;
 export declare function ffmpegSeekSeconds(metadata: Pick<VideoMetadata, "mediaTimeOffsetSeconds">, mediaTime: number): number;
 export declare function resolvePlayableVideoDuration(metadata: VideoMetadata): number;
 /**

package/dist/utils/ffprobe.js

@@ -336,6 +336,14 @@ export async function buildProbeFactsText(filePath, signal) {
 export function videoStartOnMediaTimeline(metadata) {
     return (metadata.videoStreamLeadSeconds ?? 0) + (metadata.mediaTimeOffsetSeconds ?? 0);
 }
+export function formatFfmpegSeconds(seconds) {
+    const text = String(seconds);
+    return text.includes("e") ? String(+seconds.toFixed(6)) : text;
+}
+function readIntervalSpec(startSeconds, end) {
+    const to = typeof end === "number" ? formatFfmpegSeconds(end) : end;
+    return `${formatFfmpegSeconds(startSeconds)}%${to}`;
+}
 export function ffmpegSeekSeconds(metadata, mediaTime) {
     return mediaTime - (metadata.mediaTimeOffsetSeconds ?? 0);
 }
@@ -860,7 +868,7 @@ async function extractFinalPacketDuration(filePath, window, signal) {
         "-select_streams",
         "v:0",
         "-read_intervals",
-        `${intervalStart}%${streamEnd}`,
+        readIntervalSpec(intervalStart, streamEnd),
         "-show_entries",
         "packet=pts_time,duration_time",
         "-of",
@@ -939,7 +947,7 @@ export async function extractFinalVideoFrameTimestamp(filePath, metadata, signal
             });
             return parseFinalTimestamp(stdout);
         };
-        const timestamp = (await probe(`${intervalStart}%${streamEnd}`)) ?? (await probe( /* full scan */));
+        const timestamp = (await probe(readIntervalSpec(intervalStart, streamEnd))) ?? (await probe( /* full scan */));
         if (timestamp === undefined) {
             throw new Error("[FFmpeg] ffprobe found no decodable final video frame");
         }
@@ -1084,7 +1092,8 @@ async function probeDecodedAudioDuration(filePath, audioStream, sampleRate, star
         }
     };
     const tailStart = Math.max(startSeconds, startSeconds + containerDurationSeconds - AUDIO_DURATION_PROBE_TAIL_SECONDS);
-    const lastFrame = (await probe(`${tailStart}%${FFPROBE_READ_INTERVAL_EXPLICIT_FAR_END}`)) ?? (await probe());
+    const lastFrame = (await probe(readIntervalSpec(tailStart, FFPROBE_READ_INTERVAL_EXPLICIT_FAR_END))) ??
+        (await probe());
     if (!lastFrame)
         return null;
     return lastFrame.timestamp + lastFrame.nbSamples / sampleRate - startSeconds;
@@ -1114,7 +1123,7 @@ export async function analyzeKeyframeIntervals(filePath, metadata) {
 export async function keyframeGapSeconds(filePath, seekSeconds, signal) {
     const stdout = await runFfprobe(filePath, [
         ...["-select_streams", "v:0", "-show_entries", "packet=pts_time", "-of", "csv=p=0"],
-        ...["-read_intervals", `${seekSeconds}%+#1`],
+        ...["-read_intervals", readIntervalSpec(seekSeconds, "+#1")],
     ], signal);
     const keyframe = parseFloat(stdout.split("\n")[0] ?? "");
     return Number.isFinite(keyframe) ? Math.max(0, seekSeconds - keyframe) : 0;

package/package.json

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