@hyperframes/engine 0.8.199 → 0.8.201

package/dist/services/riskFrames.js

@@ -0,0 +1,101 @@
+/**
+ * Which frames drawElement capture cannot reproduce, so those frames alone are captured by
+ * screenshot and the rest keep the fast path.
+ */
+import { quantizeTimeToFrame } from "@hyperframes/core";
+/** Frames per page round trip while scanning; a scan is one in-page loop per chunk. */
+const SCAN_CHUNK_FRAMES = 240;
+/**
+ * Above this share of risk frames the second browser and the switching cost outweigh the fast
+ * frames, so the whole render captures by screenshot as it always has.
+ */
+export const MAX_RISK_FRAME_FRACTION = 0.6;
+/** Peak memory per-frame capture adds over a screenshot render at 1080p: 1002 to 2001 MB measured. */
+export const RISK_RENDER_ADDED_BYTES = 1_000_000_000;
+/** Memory that must still be available once the screenshot browser is open. */
+export const RISK_RENDER_HEADROOM_BYTES = 1_500_000_000;
+const PIXELS_1080P = 1920 * 1080;
+/** Risk ranges closer than this many frames are joined, so capture never alternates modes. */
+export const RISK_RANGE_HYSTERESIS_FRAMES = 12;
+/**
+ * Frames where a recorded effect element shows. Seeks the page forward, so use a throwaway one.
+ * Null once more than `maxFrames` frames qualify.
+ */
+export async function scanCssEffectLiveFrames(page, fps, totalFrames, maxFrames) {
+    const live = new Set();
+    for (let from = 0; from < totalFrames; from += SCAN_CHUNK_FRAMES) {
+        const times = [];
+        for (let f = from; f < Math.min(totalFrames, from + SCAN_CHUNK_FRAMES); f++) {
+            times.push(quantizeTimeToFrame(f / fps, fps));
+        }
+        const hits = await page.evaluate(async (ts) => {
+            const w = window;
+            const targets = w.__hfCssFxTargets ?? [];
+            // A hidden element still shows a descendant that sets `visibility: visible` itself.
+            const paints = (el) => getComputedStyle(el).visibility !== "hidden" ||
+                Array.from(el.querySelectorAll("*")).some((d) => getComputedStyle(d).visibility === "visible");
+            const shows = (el) => {
+                for (let n = el; n; n = n.parentElement) {
+                    const cs = getComputedStyle(n);
+                    if (cs.display === "none" || Number(cs.opacity) === 0)
+                        return false;
+                }
+                return paints(el);
+            };
+            const out = [];
+            for (let i = 0; i < ts.length; i++) {
+                w.__hf?.seek?.(ts[i]);
+                await w.__hfWaitForSeekCompletion?.();
+                if (targets.some(shows))
+                    out.push(i);
+            }
+            return out;
+        }, times);
+        for (const i of hits)
+            live.add(from + i);
+        if (live.size > maxFrames)
+            break;
+    }
+    return live.size > maxFrames ? null : live;
+}
+/**
+ * The given frames with a one-frame margin, ranges closer than {@link RISK_RANGE_HYSTERESIS_FRAMES}
+ * joined. Null when they cover more than {@link MAX_RISK_FRAME_FRACTION} of the render.
+ */
+export function planRiskFrames(frames, totalFrames) {
+    const sorted = [...new Set(frames)].sort((a, b) => a - b);
+    const plan = new Set();
+    let rangeStart = -1;
+    let rangeEnd = -1;
+    const flush = () => {
+        for (let f = Math.max(0, rangeStart - 1); f <= Math.min(totalFrames - 1, rangeEnd + 1); f++) {
+            plan.add(f);
+        }
+    };
+    for (const f of sorted) {
+        if (rangeStart >= 0 && f - rangeEnd <= RISK_RANGE_HYSTERESIS_FRAMES) {
+            rangeEnd = f;
+            continue;
+        }
+        if (rangeStart >= 0)
+            flush();
+        rangeStart = f;
+        rangeEnd = f;
+    }
+    if (rangeStart >= 0)
+        flush();
+    return plan.size > totalFrames * MAX_RISK_FRAME_FRACTION ? null : plan;
+}
+/** `live` plus every frame from just before the first callback to the end of the render. */
+export function withFramesAfterCallback(live, callbackFrom, fps, totalFrames) {
+    if (callbackFrom === null)
+        return live;
+    for (let f = Math.max(0, Math.floor(callbackFrom * fps) - 1); f < totalFrames; f++)
+        live.add(f);
+    return live;
+}
+/** Whether the render fits: what it adds, scaled by output pixels, leaves the headroom. */
+export function riskSessionFits(availableMb, outputPixels) {
+    const rss = RISK_RENDER_ADDED_BYTES * Math.max(1, outputPixels / PIXELS_1080P);
+    return availableMb * 1024 * 1024 - rss >= RISK_RENDER_HEADROOM_BYTES;
+}

package/dist/services/screenshotService.d.ts

@@ -73,6 +73,13 @@ export declare function pageScreenshotCapture(page: Page, options: CaptureOption
  * round-trip overhead.
  */
 export declare function captureScreenshotWithAlpha(page: Page, width: number, height: number): Promise<Buffer>;
+/**
+ * Make the page transparent for alpha capture, then use captureAlphaPng() per frame. html/body always clear;
+ * [data-composition-id] roots (nested too) keep their background unless clearCompositionRoot (HDR layered pass).
+ * A repeat call rewrites the rule, so the last call wins.
+ */
+/** 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 }?: {
     clearCompositionRoot?: boolean;
 }): Promise<void>;

package/dist/services/screenshotService.js

@@ -234,6 +234,10 @@ export async function captureScreenshotWithAlpha(page, width, height) {
  * [data-composition-id] roots (nested too) keep their background unless clearCompositionRoot (HDR layered pass).
  * A repeat call rewrites the rule, so the last call wins.
  */
+/** Whether frames must carry alpha. PNG alone does not imply it: motion blur captures opaque output as PNG. */
+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 } = {}) {
     const client = await getCdpSession(page);

package/dist/services/systemMemory.d.ts

@@ -49,3 +49,5 @@ export declare const LOW_MEMORY_TOTAL_MB_THRESHOLD = 8192;
  * small VMs, small Lambda tiers, small containers) are detected correctly.
  */
 export declare function isLowMemorySystem(totalMb?: number): boolean;
+/** Memory available in MiB: on macOS and Linux, counting pages the OS reclaims on demand. */
+export declare function getAvailableMemoryMb(): number;

package/dist/services/systemMemory.js

@@ -7,8 +7,9 @@
  * They all need the same "how much memory does this box have" reading, so
  * it lives here once instead of being re-derived inline.
  */
+import { execSync } from "child_process";
 import { readFileSync } from "fs";
-import { totalmem } from "os";
+import { freemem, platform, totalmem } from "os";
 const BYTES_PER_MIB = 1024 * 1024;
 const BYTES_PER_MIB_BIGINT = BigInt(BYTES_PER_MIB);
 // These are the paths as seen from INSIDE a container, where the runtime
@@ -154,3 +155,39 @@ export const LOW_MEMORY_TOTAL_MB_THRESHOLD = 8192;
 export function isLowMemorySystem(totalMb = getSystemTotalMb()) {
     return totalMb <= LOW_MEMORY_TOTAL_MB_THRESHOLD;
 }
+/** Memory available in MiB: on macOS and Linux, counting pages the OS reclaims on demand. */
+export function getAvailableMemoryMb() {
+    const fallback = Math.trunc(freemem() / BYTES_PER_MIB);
+    if (platform() === "darwin") {
+        try {
+            const raw = execSync("vm_stat", { encoding: "utf-8", timeout: 5000 });
+            const pageSize = parseInt(raw.match(/page size of (\d+)/)?.[1] ?? "0", 10);
+            if (!pageSize)
+                return fallback;
+            const pages = (key) => parseInt(raw.match(new RegExp(`${key}:\\s+(\\d+)`))?.[1] ?? "0", 10);
+            const available = (pages("Pages free") +
+                pages("Pages inactive") +
+                pages("Pages purgeable") +
+                pages("Pages speculative")) *
+                pageSize;
+            return available > 0 ? Math.trunc(available / BYTES_PER_MIB) : fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+    if (platform() === "linux") {
+        try {
+            const meminfo = readFileSync("/proc/meminfo", "utf-8");
+            const match = meminfo.match(/MemAvailable:\s+(\d+)\s+kB/);
+            if (match) {
+                return Math.trunc(parseInt(match[1], 10) / 1024);
+            }
+            return fallback;
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return fallback;
+}

package/dist/services/threeDProjection.d.ts

@@ -77,3 +77,17 @@ export declare function initThreeDProjection(page: Page): Promise<ThreeDProjecti
  * Returns the first matched effect name (for logging) or null.
  */
 export declare function detectCssEffectRisk(page: Page): Promise<string | null>;
+/** What {@link scanCssEffects} found. */
+export interface CssEffectScan {
+    /** First effect matched, in scan order (computed, stylesheet, tween vars, WebGL), or null. */
+    reason: string | null;
+    /** False when a match is not tied to an element (unmatched rule, CSS animation, WebGL). */
+    bounded: boolean;
+    /** Seconds at which the first timeline callback can fire; the effect can show anywhere after. */
+    callbackFrom: number | null;
+}
+/**
+ * Which CSS effects drawElementImage cannot reproduce. `collect: true` scans past the first match
+ * and leaves the elements carrying an effect in `window.__hfCssFxTargets`.
+ */
+export declare function scanCssEffects(page: Page, collect: boolean): Promise<CssEffectScan>;

package/dist/services/threeDProjection.js

@@ -864,6 +864,13 @@ export async function initThreeDProjection(page) {
  * Returns the first matched effect name (for logging) or null.
  */
 export async function detectCssEffectRisk(page) {
+    return (await scanCssEffects(page, false)).reason;
+}
+/**
+ * Which CSS effects drawElementImage cannot reproduce. `collect: true` scans past the first match
+ * and leaves the elements carrying an effect in `window.__hfCssFxTargets`.
+ */
+export async function scanCssEffects(page, collect) {
     try {
         // MUST NOT seek the timeline here. Driving `window.__hf.seek` to sample
         // frames renders GSAP `.from()` / overlapping tweens out of forward order and
@@ -874,10 +881,23 @@ export async function detectCssEffectRisk(page) {
         // 1e5a1165: the Pong scene's scale/rotation tween lands wrong, 19.8 dB / 27
         // damaged frames; the fix restored it to baseline parity, 43 dB / 0). So we
         // detect the same effects seek-free, four ways:
-        return await page.evaluate(() => {
+        return await page.evaluate((collectAll) => {
             const root = document.querySelector("[data-composition-id]");
             if (!root)
-                return null;
+                return { reason: null, bounded: true, callbackFrom: null };
+            let reason = null;
+            let bounded = true;
+            const targets = new Set();
+            // A match on `els` (null: not tied to any element). Returns true to stop the scan.
+            const hit = (name, els) => {
+                reason = reason ?? name;
+                if (els && els.length > 0)
+                    for (const el of Array.from(els))
+                        targets.add(el);
+                else
+                    bounded = false;
+                return !collectAll;
+            };
             // (1) Computed styles at the current (init/t0) state — effects present in
             // the base render.
             const scanComputed = () => {
@@ -885,28 +905,51 @@ export async function detectCssEffectRisk(page) {
                 for (const el of els) {
                     const cs = getComputedStyle(el);
                     const bf = cs.backdropFilter || cs.webkitBackdropFilter || "";
-                    if (bf && bf !== "none")
-                        return "backdrop-filter";
+                    if (bf && bf !== "none" && hit("backdrop-filter", [el]))
+                        return true;
                     const f = cs.filter || "";
-                    if (f && f !== "none" && f.indexOf("blur(") !== -1)
-                        return "filter:blur";
-                    if (f && f !== "none" && f.indexOf("drop-shadow(") !== -1)
-                        return "filter:drop-shadow";
+                    if (f && f !== "none" && f.indexOf("blur(") !== -1 && hit("filter:blur", [el])) {
+                        return true;
+                    }
+                    if (f &&
+                        f !== "none" &&
+                        f.indexOf("drop-shadow(") !== -1 &&
+                        hit("filter:drop-shadow", [el])) {
+                        return true;
+                    }
                     const mbm = cs.mixBlendMode || "";
-                    if (mbm && mbm !== "normal")
-                        return "mix-blend-mode";
+                    if (mbm && mbm !== "normal" && hit("mix-blend-mode", [el]))
+                        return true;
                     const an = cs.animationName || "";
                     const ad = cs.animationDuration || "0s";
-                    if (an && an !== "none" && ad !== "0s" && parseFloat(ad) > 0)
-                        return "css-animation";
+                    if (an &&
+                        an !== "none" &&
+                        ad !== "0s" &&
+                        parseFloat(ad) > 0 &&
+                        hit("css-animation", null)) {
+                        return true;
+                    }
                 }
-                return null;
+                return false;
             };
             // (2) Stylesheet rules — an effect applied later via a class swap won't be
             // computed at t0, but the rule that declares it exists up front. This
             // replaces the old per-frame scrub scan seek-free (conservative: a declared
             // rule ⇒ gate, even if applied only mid-timeline).
             const scanStyleSheets = () => {
+                // The elements a style rule can apply to now; a pseudo-element's effect shows only while
+                // its owner does. Empty when the rule is not a plain style rule or matches nothing yet.
+                const ruleTargets = (rule) => {
+                    const selector = rule.selectorText;
+                    if (!selector)
+                        return [];
+                    try {
+                        return Array.from(root.querySelectorAll(selector.replace(/::?(before|after|first-line|first-letter|marker|placeholder|selection|backdrop)/g, "")));
+                    }
+                    catch {
+                        return [];
+                    }
+                };
                 for (const sheet of Array.from(document.styleSheets)) {
                     let rules = null;
                     try {
@@ -917,63 +960,96 @@ export async function detectCssEffectRisk(page) {
                     }
                     for (const rule of Array.from(rules ?? [])) {
                         const txt = rule.cssText || "";
+                        let name = null;
                         if (/backdrop-filter\s*:\s*(?!none)/i.test(txt))
-                            return "backdrop-filter";
-                        if (/(?:^|[^-])filter\s*:[^;{}]*blur\(/i.test(txt))
-                            return "filter:blur";
-                        if (/(?:^|[^-])filter\s*:[^;{}]*drop-shadow\(/i.test(txt)) {
-                            return "filter:drop-shadow";
+                            name = "backdrop-filter";
+                        else if (/(?:^|[^-])filter\s*:[^;{}]*blur\(/i.test(txt))
+                            name = "filter:blur";
+                        else if (/(?:^|[^-])filter\s*:[^;{}]*drop-shadow\(/i.test(txt)) {
+                            name = "filter:drop-shadow";
                         }
-                        if (/mix-blend-mode\s*:\s*(?!normal)/i.test(txt))
-                            return "mix-blend-mode";
+                        else if (/mix-blend-mode\s*:\s*(?!normal)/i.test(txt))
+                            name = "mix-blend-mode";
+                        if (name && hit(name, ruleTargets(rule)))
+                            return true;
                     }
                 }
-                return null;
+                return false;
             };
             // (3) GSAP tween vars — effects animated by GSAP writing inline
             // filter / backdropFilter / mixBlendMode (never present in a stylesheet).
             const scanTweenVars = () => {
                 const walk = (tl) => {
                     if (typeof tl.getChildren !== "function")
-                        return null;
+                        return false;
                     for (const c of tl.getChildren(false, true, true)) {
-                        const sub = walk(c);
-                        if (sub)
-                            return sub;
+                        if (walk(c))
+                            return true;
                         const vars = c.vars || {};
                         for (const k of Object.keys(vars)) {
                             const kl = k.toLowerCase();
+                            let name = null;
                             if (kl.includes("blend"))
-                                return "mix-blend-mode";
-                            if (kl.includes("backdrop"))
-                                return "backdrop-filter";
-                            if (kl === "filter" && /blur\(/i.test(String(vars[k] ?? "")))
-                                return "filter:blur";
-                            if (kl === "filter" && /drop-shadow\(/i.test(String(vars[k] ?? ""))) {
-                                return "filter:drop-shadow";
+                                name = "mix-blend-mode";
+                            else if (kl.includes("backdrop"))
+                                name = "backdrop-filter";
+                            else if (kl === "filter" && /blur\(/i.test(String(vars[k] ?? ""))) {
+                                name = "filter:blur";
                             }
+                            else if (kl === "filter" && /drop-shadow\(/i.test(String(vars[k] ?? ""))) {
+                                name = "filter:drop-shadow";
+                            }
+                            if (!name)
+                                continue;
+                            const els = (typeof c.targets === "function" ? c.targets() : []).filter((t) => t instanceof Element);
+                            if (hit(name, els))
+                                return true;
                         }
                     }
-                    return null;
+                    return false;
                 };
                 const tls = window.__timelines || {};
                 for (const tl of Object.values(tls)) {
-                    const r = walk(tl);
-                    if (r)
-                        return r;
+                    if (walk(tl))
+                        return true;
                 }
-                return null;
+                return false;
             };
             // (4) WebGL context — seek-invariant, recorded at context creation.
             const scanWebgl = () => {
                 const aw = window;
                 const accel = (aw.__hf_accel_canvases ?? []).filter((c) => root.contains(c));
-                return accel.length > 0 ? "webgl-context" : null;
+                return accel.length > 0 && hit("webgl-context", null);
             };
-            return scanComputed() || scanStyleSheets() || scanTweenVars() || scanWebgl();
-        });
+            for (const scan of [scanComputed, scanStyleSheets, scanTweenVars, scanWebgl]) {
+                if (scan())
+                    break;
+            }
+            const calls = ["onStart", "onUpdate", "onComplete", "onRepeat", "onReverseComplete"];
+            const firstCallback = (node, offset) => {
+                const start = offset + (typeof node.startTime === "function" ? node.startTime() : 0);
+                let first = calls.some((k) => typeof node.vars?.[k] === "function") ? start : Infinity;
+                if (typeof node.getChildren === "function") {
+                    for (const child of node.getChildren(false, true, true)) {
+                        first = Math.min(first, firstCallback(child, start));
+                    }
+                }
+                return first;
+            };
+            const timelines = window
+                .__timelines;
+            const callbackStart = reason
+                ? Math.min(Infinity, ...Object.values(timelines ?? {}).map((tl) => firstCallback(tl, 0)))
+                : Infinity;
+            window.__hfCssFxTargets = [...targets];
+            return {
+                reason,
+                bounded,
+                callbackFrom: Number.isFinite(callbackStart) ? callbackStart : null,
+            };
+        }, collect);
     }
     catch {
-        return null;
+        return { reason: null, bounded: true, callbackFrom: null };
     }
 }

package/dist/services/videoFrameExtractor.js

@@ -23,7 +23,7 @@ import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
 import { downloadToTemp, isHttpUrl, safeDownloadUrlIdentity, UrlDownloadError, writeUrlDownloadTelemetry, } from "../utils/urlDownloader.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
-import { isFfmpegFilterAvailable } from "../utils/psnrFilterAvailability.js";
+import { isFfmpegFilterAvailable, isFfmpegHwaccelAvailable, } from "../utils/psnrFilterAvailability.js";
 import { DEFAULT_CONFIG } from "../config.js";
 import { unwrapTemplate } from "../utils/htmlTemplate.js";
 import { FRAME_FILENAME_PREFIX, gcExtractionCache, gcSweepDue, lookupCacheEntry, partialCacheEntryDir, publishCacheEntry, readContentSha256, readKeyStat, rehydrateCacheEntry, touchCacheEntry, } from "./extractionCache.js";
@@ -606,7 +606,12 @@ outputDirOverride) {
     const isHdr = isHdrColorSpaceUtil(metadata.colorSpace);
     const isMacOS = process.platform === "darwin";
     const toneMappedToSdr = options.toneMapHdrToSdr === true && isHdr && (await toneMapsWithZscale());
-    const decodeWithVideoToolbox = isHdr && isMacOS && !toneMappedToSdr;
+    const keepsHdrForChrome = isHdr && isMacOS && !toneMappedToSdr;
+    const decodeWithVideoToolbox = keepsHdrForChrome ||
+        (isMacOS &&
+            !metadata.hasAlpha &&
+            !codecMayHaveAlpha(metadata.videoCodec) &&
+            (await isFfmpegHwaccelAvailable("videotoolbox")));
     const sampleAtOutputFps = !options.finalFrameOnly;
     if (options.frameRanges && (!sampleAtOutputFps || metadata.isVFR)) {
         throw new Error("frameRanges extraction needs a constant-frame-rate source");
@@ -642,7 +647,7 @@ outputDirOverride) {
         args.push("-ss", String(startTime), "-i", videoPath, "-t", String(duration));
     }
     const vfFilters = [];
-    if (decodeWithVideoToolbox) {
+    if (keepsHdrForChrome) {
         vfFilters.push("format=nv12");
     }
     const samplingAt = vfFilters.length;
@@ -685,8 +690,7 @@ outputDirOverride) {
     if (format === "png")
         encodeArgs.push("-compression_level", "1");
     encodeArgs.push("-y", outputPattern);
-    // A long 4K run can take far longer than the timeout and still be healthy; only a stall is a hang.
-    const runOptions = { signal, stallTimeout: ffmpegProcessTimeout };
+    const runOptions = { signal, timeout: ffmpegProcessTimeout };
     const filterArgsFor = (seek) => {
         const filters = [...vfFilters];
         filters.splice(samplingAt, 0, ...samplingFilters(seek));

package/dist/services/videoFrameInjector.js

@@ -148,7 +148,7 @@ export function createVideoFrameInjector(frameLookup, config) {
         lastCacheTouchByDir.set(cacheDir, now);
     }
     // fallow-ignore-next-line complexity
-    return async (page, time, heldVideoTime) => {
+    const inject = async (page, time, heldVideoTime) => {
         for (const cacheDir of frameLookup.frameDirs())
             renewCacheLease(cacheDir);
         const activePayloads = frameLookup.getActiveFramePayloads(time);
@@ -205,6 +205,7 @@ export function createVideoFrameInjector(frameLookup, config) {
             }
         }
     };
+    return Object.assign(inject, { fresh: () => createVideoFrameInjector(frameLookup, config) });
 }
 /**
  * Hide specific video elements by ID. Used in Pass 1 of the HDR pipeline so

package/dist/types.d.ts

@@ -16,11 +16,12 @@ export type PageMotionBlurOff = "off" | "hdr-render" | "layered-composite" | "di
  */
 export type SubTimelineWaitOutcome = "ready" | "timeout" | "script_failure";
 /**
- * Shared by every capture session of one render: composition ids whose timeline
- * wait already timed out, so later sessions report the timeout without waiting again.
+ * Shared by every capture session of one render: timeline waits that already timed out
+ * (so later sessions skip the wait), and scene callback errors the render log already shows.
  */
 export interface SubTimelineWaitMemo {
     unregisteredIds?: readonly string[];
+    loggedSceneCallbackErrors?: string[];
 }
 export type CaptureWarningCode = "media_readiness_timeout" | "media_load_failed" | "audio_processing_failed" | "sub_timeline_readiness_timeout" | "sub_timeline_script_failure" | "script_error_isolated" | "vfx_failure" | "live_map_detected";
 /** Structured correctness warning produced while preparing a capture session. */
@@ -149,6 +150,7 @@ export interface CaptureOptions {
      */
     fps: Fps;
     format?: "jpeg" | "png";
+    transparent?: boolean;
     quality?: number;
     /**
      * Opt into sub-frame multi-sample motion blur (issue #4010). Absent means off and the
@@ -221,6 +223,7 @@ export interface CaptureOptions {
      * Clamped to 0..8 like the env knob; HF_DE_VERIFY, when set, still wins.
      */
     deVerifySamples?: number;
+    deFrameFallback?: boolean;
 }
 export interface CaptureVideoMetadataHint {
     id: string;
@@ -382,6 +385,7 @@ export interface CapturePerfSummary {
     deVerifyInitMs: number;
     /** Clip-cut boundary frames routed to per-frame screenshot (Lim 6). */
     deBoundaryFrames: number;
+    deRiskFrames: number;
     /** Per-frame "No cached paint record" screenshot fallbacks during capture. */
     deNcprFallbacks: number;
     /**

package/dist/utils/psnrFilterAvailability.d.ts

@@ -9,5 +9,6 @@
  */
 export declare function isPsnrFilterAvailable(): Promise<boolean>;
 export declare function isFfmpegFilterAvailable(name: string): Promise<boolean>;
+export declare function isFfmpegHwaccelAvailable(name: string): Promise<boolean>;
 /** Test-only: drop the memoized probe result. */
 export declare function resetPsnrFilterAvailabilityCache(): void;

package/dist/utils/psnrFilterAvailability.js

@@ -14,7 +14,14 @@ import { getFfmpegBinary } from "./ffmpegBinaries.js";
  * not change across renders within the same CLI invocation, and re-probing
  * per session would burn ~50-100ms of subprocess spawn per capture worker.
  */
-let cachedFilterList = null;
+const cachedLists = new Map();
+function listed(flag) {
+    let list = cachedLists.get(flag);
+    if (!list)
+        cachedLists.set(flag, (list = listFfmpeg(flag)));
+    return list;
+}
+const listsWord = (stdout, name) => stdout !== null && new RegExp(`(^|\\s)${name}(\\s|$)`, "m").test(stdout);
 /**
  * Returns true when the resident ffmpeg exposes the `psnr` filter. False on
  * any probe failure — missing binary (ENOENT), non-zero exit, timeout,
@@ -27,25 +34,25 @@ let cachedFilterList = null;
 export function isPsnrFilterAvailable() {
     return isFfmpegFilterAvailable("psnr");
 }
+// `-filters` and `-hwaccels` list one name per line; a whole-word match ignores longer names
+// and banner prose that mentions it.
 export async function isFfmpegFilterAvailable(name) {
-    if (cachedFilterList === null)
-        cachedFilterList = listFilters();
-    const stdout = await cachedFilterList;
-    // `-filters` lists one filter per line; a whole-word match ignores longer names
-    // and banner prose that mentions the filter.
-    return stdout !== null && new RegExp(`(^|\\s)${name}(\\s|$)`, "m").test(stdout);
+    return listsWord(await listed("-filters"), name);
+}
+export async function isFfmpegHwaccelAvailable(name) {
+    return listsWord(await listed("-hwaccels"), name);
 }
 /** Test-only: drop the memoized probe result. */
 export function resetPsnrFilterAvailabilityCache() {
-    cachedFilterList = null;
+    cachedLists.clear();
 }
-async function listFilters() {
+async function listFfmpeg(flag) {
     // Match `psnr.ts`: promisify lazily so a partial `node:child_process` mock
     // (test that omits `execFile`) doesn't crash at module load — it fails at
     // call time instead, and the try/catch below reports no filters at all.
     const execFileP = promisify(execFile);
     try {
-        const { stdout } = await execFileP(getFfmpegBinary(), ["-hide_banner", "-filters"], {
+        const { stdout } = await execFileP(getFfmpegBinary(), ["-hide_banner", flag], {
             maxBuffer: 4 * 1024 * 1024,
             timeout: 5_000,
             windowsHide: true,

package/dist/utils/runFfmpeg.d.ts

@@ -7,9 +7,8 @@
 import { type ManagedProcessTerminationReason } from "./managedChildProcess.js";
 export interface RunFfmpegOptions {
     signal?: AbortSignal;
+    /** Stop after this long without a higher frame count or output time (counted from spawn until one). */
     timeout?: number;
-    /** Replaces `timeout`: stop only once this long passes without a new output frame. */
-    stallTimeout?: number;
     onStderr?: (line: string) => void;
 }
 export interface RunFfmpegResult {
@@ -49,6 +48,6 @@ export declare function ffmpegStatsReader(onStats: (stats: FfmpegStats) => void)
  * exactly which option to fix.
  */
 export declare function formatFfmpegError(exitCode: number | null, stderr: string, tailLines?: number): string;
-/** formatFfmpegError, led by the timeout when this process was killed at its deadline. */
+/** formatFfmpegError, led by the timeout when this process was killed for making no progress. */
 export declare function describeFfmpegFailure(result: Pick<RunFfmpegResult, "exitCode" | "signal" | "stderr" | "terminationReason">, timeoutMs: number): string;
 export declare function runFfmpeg(args: string[], opts?: RunFfmpegOptions): Promise<RunFfmpegResult>;