@hyperframes/engine 0.8.225 → 0.8.227

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/chunkEncoder.d.ts

@@ -105,7 +105,7 @@ export declare function appendRateCapArgs(args: string[], options: {
     maxBitrate?: string;
     bufferSize?: string;
 }): void;
-export declare function buildEncoderArgs(options: EncoderOptions, inputArgs: string[], outputPath: string, gpuEncoder?: GpuEncoder): string[];
+export declare function buildEncoderArgs(options: EncoderOptions, inputArgs: string[], outputPath: string, gpuEncoder?: GpuEncoder, nvencPresets?: ReadonlySet<string>): string[];
 export declare function encodeFramesFromDir(framesDir: string, framePattern: string, outputPath: string, options: EncoderOptions, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegEncodeTimeout">>, onFramesEncoded?: (frames: number) => void): Promise<EncodeResult>;
 export declare function buildConcatArgs(concatListPath: string, outputPath: string): string[];
 /**

package/dist/services/chunkEncoder.js

@@ -9,7 +9,7 @@ import { frameSequencePath } from "./extractedFrameIndex.js";
 import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync, } from "fs";
 import { join, dirname, extname, resolve } from "path";
 import { DEFAULT_CONFIG } from "../config.js";
-import { getCachedGpuEncoder, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
+import { getCachedGpuEncoder, getCachedNvencPresets, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
 import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
 import { withEvenDimensionPad } from "../utils/evenDimensions.js";
 import { SDR_CAPTURE_TO_BT709_FILTER, SDR_RGB_TO_TAGGED_BT709_FILTER, } from "../utils/sdrCaptureColor.js";
@@ -169,7 +169,7 @@ export function appendRateCapArgs(args, options) {
     }
     args.push("-maxrate", String(Math.round(cap)), "-bufsize", String(Math.round(buffer)));
 }
-export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = null) {
+export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = null, nvencPresets) {
     const { fps, codec = "h264", preset = "medium", quality = 23, bitrate, pixelFormat = "yuv420p", vp9CpuUsed, useGpu = false, } = options;
     // libx264 cannot encode HDR. If a caller passes hdr with codec=h264 we'd
     // produce a "half-HDR" file (BT.2020 container tags but a BT.709 VUI block
@@ -190,7 +190,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
             args.push("-c:v", encoderName);
             switch (gpuEncoder) {
                 case "nvenc":
-                    args.push("-preset", mapPresetForGpuEncoder("nvenc", preset));
+                    args.push("-preset", mapPresetForGpuEncoder("nvenc", preset, nvencPresets));
                     if (bitrate)
                         args.push("-b:v", bitrate);
                     else
@@ -437,7 +437,8 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
     }
     const inputPath = frameSequencePath(framesDir, framePattern);
     const inputArgs = ["-framerate", fpsToFfmpegArg(options.fps), "-i", inputPath];
-    const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder);
+    const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
+    const args = buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder, nvencPresets);
     const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
     let framesRead = 0;
     const result = await runFfmpeg(args, {
@@ -587,7 +588,8 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
         let gpuEncoder = null;
         if (options.useGpu)
             gpuEncoder = await getCachedGpuEncoder();
-        const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder);
+        const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
+        const args = buildEncoderArgs(options, inputArgs, chunkPath, gpuEncoder, nvencPresets);
         const encodeTimeout = config?.ffmpegEncodeTimeout ?? DEFAULT_CONFIG.ffmpegEncodeTimeout;
         let framesRead = 0;
         const processResult = await runFfmpeg(args, {

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. */
@@ -1534,7 +1538,7 @@ export async function pollVideosReady(page, skipIds, timeoutMs, intervalMs = 100
                         return true;
                     if (ve.networkState === HTMLMediaElement.NETWORK_NO_SOURCE)
                         return true;
-                    return false;
+                    return !ve.getAttribute("src") && !ve.querySelector("source");
                 }));
         }, skipIds));
     };
@@ -1631,6 +1635,8 @@ export async function collectMediaReadinessWarnings(page, skipIds, timeoutMs) {
             const mediaElement = media;
             if (skipped.has(mediaElement.id))
                 continue;
+            if (!mediaElement.getAttribute("src") && !mediaElement.querySelector("source"))
+                continue;
             const src = mediaElement.currentSrc || mediaElement.getAttribute("src") || "(no src)";
             const failed = Boolean(mediaElement.error) ||
                 mediaElement.networkState === HTMLMediaElement.NETWORK_NO_SOURCE;
@@ -2447,8 +2453,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 +2469,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 +2494,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 +2517,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 +2532,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 +2556,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 +2641,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 +2808,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 +2842,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 +2919,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 +2968,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 +4173,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";
     /**
@@ -101,7 +104,7 @@ export interface StreamingEncoder {
  * Exported so unit tests can assert on the constructed CLI without spawning
  * FFmpeg — see streamingEncoder.test.ts.
  */
-export declare function buildStreamingArgs(options: StreamingEncoderOptions, outputPath: string, gpuEncoder?: GpuEncoder): string[];
+export declare function buildStreamingArgs(options: StreamingEncoderOptions, outputPath: string, gpuEncoder?: GpuEncoder, nvencPresets?: ReadonlySet<string>): string[];
 /**
  * Spawn a streaming FFmpeg encoder that accepts frame buffers on stdin.
  */

package/dist/services/streamingEncoder.js

@@ -19,7 +19,7 @@ import { trackChildProcess } from "../utils/processTracker.js";
 import { ManagedChildProcess, } from "../utils/managedChildProcess.js";
 import { existsSync, mkdirSync, statSync } from "fs";
 import { dirname } from "path";
-import { getCachedGpuEncoder, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
+import { getCachedGpuEncoder, getCachedNvencPresets, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
 import { ffmpegStatsReader, formatFfmpegError, isExternalFfmpegInterruption, } from "../utils/runFfmpeg.js";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
@@ -98,7 +98,7 @@ export function createFrameReorderBuffer(startFrame, endFrame) {
  * Exported so unit tests can assert on the constructed CLI without spawning
  * FFmpeg — see streamingEncoder.test.ts.
  */
-export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
+export function buildStreamingArgs(options, outputPath, gpuEncoder = null, nvencPresets) {
     const { fps, codec = "h264", preset = "medium", quality = 23, bitrate, pixelFormat = "yuv420p", vp9CpuUsed, useGpu = false, imageFormat = "jpeg", } = options;
     // Input args: pipe from stdin
     const args = [];
@@ -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) {
@@ -128,7 +137,7 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
             args.push("-c:v", encoderName);
             switch (gpuEncoder) {
                 case "nvenc":
-                    args.push("-preset", mapPresetForGpuEncoder("nvenc", preset));
+                    args.push("-preset", mapPresetForGpuEncoder("nvenc", preset, nvencPresets));
                     if (bitrate)
                         args.push("-b:v", bitrate);
                     else
@@ -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=eof_action=endall: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".
@@ -295,7 +309,8 @@ export async function spawnStreamingEncoder(outputPath, options, signal, config)
     if (options.useGpu) {
         gpuEncoder = await getCachedGpuEncoder();
     }
-    const args = buildStreamingArgs(options, outputPath, gpuEncoder);
+    const nvencPresets = gpuEncoder === "nvenc" ? await getCachedNvencPresets() : undefined;
+    const args = buildStreamingArgs(options, outputPath, gpuEncoder, nvencPresets);
     const ffmpeg = spawn(getFfmpegBinary(), args, {
         stdio: ["pipe", "pipe", "pipe"],
         // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.

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>;

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";
@@ -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))
@@ -645,6 +667,87 @@ 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];
+}
+const VIDEO_LAYER_TAIL_SLACK_SECONDS = 0.5;
+/** 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) + VIDEO_LAYER_TAIL_SLACK_SECONDS ||
+        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`);
+    }
+    filters.push(`tpad=stop_mode=clone:stop_duration=${VIDEO_LAYER_TAIL_SLACK_SECONDS * 2}`);
+    return {
+        inputArgs: [
+            "-noaccurate_seek",
+            "-ss",
+            formatFfmpegSeconds(ffmpegSeekSeconds(metadata, startTime)),
+            ...urlInputArgs(videoPath),
+            "-i",
+            videoPath,
+        ],
+        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) {
@@ -717,48 +820,18 @@ outputDirOverride) {
             args.push("-noaccurate_seek");
         args.push("-ss", formatFfmpegSeconds(ffmpegSeek(startTime)), "-i", videoPath, "-t", formatFfmpegSeconds(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);
-        }
-    }
+    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 +839,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);
@@ -1911,10 +1983,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.js

@@ -340,6 +340,10 @@ 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);
 }
@@ -864,7 +868,7 @@ async function extractFinalPacketDuration(filePath, window, signal) {
         "-select_streams",
         "v:0",
         "-read_intervals",
-        `${formatFfmpegSeconds(intervalStart)}%${formatFfmpegSeconds(streamEnd)}`,
+        readIntervalSpec(intervalStart, streamEnd),
         "-show_entries",
         "packet=pts_time,duration_time",
         "-of",
@@ -943,8 +947,7 @@ export async function extractFinalVideoFrameTimestamp(filePath, metadata, signal
             });
             return parseFinalTimestamp(stdout);
         };
-        const timestamp = (await probe(`${formatFfmpegSeconds(intervalStart)}%${formatFfmpegSeconds(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");
         }
@@ -1089,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;
@@ -1119,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", `${formatFfmpegSeconds(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/dist/utils/gpuEncoder.d.ts

@@ -31,4 +31,8 @@ export declare function getProbeArgs(encoder: ConcreteGpuEncoder): string[];
  * - `videotoolbox`, `vaapi`, `amf`, `null`: no remap (they either ignore
  *   `-preset` entirely or accept the libx264 vocabulary).
  */
-export declare function mapPresetForGpuEncoder(encoder: GpuEncoder, preset: string): string;
+export declare function mapPresetForGpuEncoder(encoder: GpuEncoder, preset: string, nvencPresets?: ReadonlySet<string>): string;
+/** The names an encoder lists under its `-preset` option in `ffmpeg -h encoder=<name>`. */
+export declare function parseEncoderPresetNames(helpText: string): ReadonlySet<string>;
+/** The presets this ffmpeg's h264_nvenc takes; empty when it cannot be read, which keeps the pN names. */
+export declare function getCachedNvencPresets(): Promise<ReadonlySet<string>>;

package/dist/utils/gpuEncoder.js

@@ -44,9 +44,10 @@ export async function selectUsableGpuEncoder(candidates, isUsable) {
     }
     return null;
 }
-export async function detectGpuEncoder() {
-    const ffmpeg = spawn(getFfmpegBinary(), ["-encoders"], {
-        stdio: ["pipe", "pipe", "pipe"],
+/** ffmpeg's stdout, or null when it did not exit cleanly within the deadline. */
+async function ffmpegStdout(args, deadlineMs, terminationGraceMs) {
+    const ffmpeg = spawn(getFfmpegBinary(), args, {
+        stdio: ["ignore", "pipe", "pipe"],
         // See runFfmpeg.ts: keeps a console window off the user's desktop on Windows.
         windowsHide: true,
     });
@@ -56,9 +57,14 @@ export async function detectGpuEncoder() {
         stdout += data.toString();
     });
     const outcome = await new ManagedChildProcess(ffmpeg, {
-        deadlineAtMs: Date.now() + 30_000,
+        deadlineAtMs: Date.now() + deadlineMs,
+        terminationGraceMs,
     }).wait();
-    if (outcome.reason !== "exit" || outcome.exitCode !== 0)
+    return outcome.reason === "exit" && outcome.exitCode === 0 ? stdout : null;
+}
+export async function detectGpuEncoder() {
+    const stdout = await ffmpegStdout(["-encoders"], 30_000);
+    if (stdout === null)
         return null;
     const candidates = getCompiledGpuEncoders(stdout);
     return selectUsableGpuEncoder(candidates, canUseGpuEncoder).catch(() => null);
@@ -213,9 +219,11 @@ const QSV_PRESET_MAP = {
  * - `videotoolbox`, `vaapi`, `amf`, `null`: no remap (they either ignore
  *   `-preset` entirely or accept the libx264 vocabulary).
  */
-export function mapPresetForGpuEncoder(encoder, preset) {
+export function mapPresetForGpuEncoder(encoder, preset, nvencPresets) {
     switch (encoder) {
         case "nvenc":
+            if (nvencPresets && nvencPresets.size > 0 && !nvencPresets.has("p4"))
+                return legacyNvencPreset(preset, nvencPresets);
             if (/^p[1-7]$/.test(preset))
                 return preset;
             return NVENC_PRESET_MAP[preset] ?? "p4";
@@ -225,3 +233,47 @@ export function mapPresetForGpuEncoder(encoder, preset) {
             return preset;
     }
 }
+// Builds on an older NVENC SDK list `default slow medium fast hp hq ...` and reject p1..p7.
+const LEGACY_NVENC_PRESET_MAP = {
+    ultrafast: "hp",
+    superfast: "hp",
+    veryfast: "hp",
+    faster: "fast",
+    fast: "fast",
+    medium: "medium",
+    slow: "slow",
+    slower: "slow",
+    veryslow: "slow",
+    placebo: "slow",
+};
+function legacyNvencPreset(preset, accepted) {
+    if (accepted.has(preset) && !/^p[1-7]$/.test(preset))
+        return preset;
+    const mapped = LEGACY_NVENC_PRESET_MAP[preset] ?? "medium";
+    return accepted.has(mapped) ? mapped : "default";
+}
+/** The names an encoder lists under its `-preset` option in `ffmpeg -h encoder=<name>`. */
+export function parseEncoderPresetNames(helpText) {
+    const names = new Set();
+    let inPreset = false;
+    for (const line of helpText.split(/\r?\n/)) {
+        if (/^\s{1,3}-\S/.test(line)) {
+            inPreset = /^\s{1,3}-preset\s/.test(line);
+            continue;
+        }
+        const entry = inPreset ? /^\s{4,}([a-z][a-z0-9_]*)\s+-?\d+\s+[E.]\S{3}/.exec(line) : null;
+        if (entry)
+            names.add(entry[1]);
+    }
+    return names;
+}
+let cachedNvencPresets = undefined;
+/** The presets this ffmpeg's h264_nvenc takes; empty when it cannot be read, which keeps the pN names. */
+export function getCachedNvencPresets() {
+    cachedNvencPresets ??= readNvencPresets();
+    return cachedNvencPresets;
+}
+async function readNvencPresets() {
+    const help = await ffmpegStdout(["-hide_banner", "-h", "encoder=h264_nvenc"], GPU_PROBE_TIMEOUT_MS, GPU_PROBE_KILL_GRACE_MS).catch(() => null);
+    return help === null ? new Set() : parseEncoderPresetNames(help);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.225",
+  "version": "0.8.227",
   "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.225",
-    "@hyperframes/parsers": "^0.8.225"
+    "@hyperframes/parsers": "^0.8.227",
+    "@hyperframes/core": "^0.8.227"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",