@hyperframes/engine 0.8.200 → 0.8.201

package/dist/config.d.ts

@@ -163,9 +163,9 @@ export interface EngineConfig {
      * renders stream. Env: PRODUCER_STREAMING_ENCODE_DURATION_CAP_ENABLED.
      */
     streamingEncodeDurationCapEnabled: boolean;
-    /** Timeout for FFmpeg frame encoding (ms). Default: 600_000 */
+    /** How long a disk-frame encode may go without a new frame before it is stopped (ms). Default: 600_000 */
     ffmpegEncodeTimeout: number;
-    /** FFmpeg mux/faststart timeout (ms); extraction waits this long for each new frame. Default: 300_000 */
+    /** How long any other FFmpeg step (audio, mux, extraction) may go without progress (ms). Default: 300_000 */
     ffmpegProcessTimeout: number;
     /**
      * Inactivity timeout for FFmpeg streaming encode (ms). The timer resets on

package/dist/index.d.ts

@@ -42,11 +42,12 @@ export { createCaptureSession, initializeSession, closeCaptureSession, captureFr
 export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type CaptureFailureKind, type CaptureWorkerDiagnostic, } from "./services/captureFailure.js";
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
-export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
+export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, type BeginFrameResult, } from "./services/screenshotService.js";
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, 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, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, 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, } from "./services/videoFrameExtractor.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";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/index.js

@@ -45,12 +45,13 @@ export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, } from "
 export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 // ── Screenshot (BeginFrame) ─────────────────────────────────────────────────────
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.js";
-export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.js";
+export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFramesBatch, syncVideoFrameVisibility, cdpSessionCache, probeBeginFrameLiveness, initTransparentBackground, capturesAlpha, captureAlphaPng, applyDomLayerMask, removeDomLayerMask, DOM_LAYER_MASK_STYLE_ID, } from "./services/screenshotService.js";
 // ── Encoding ───────────────────────────────────────────────────────────────────
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
 export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, isVideoPastTimelineEnd, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, rebaseVideoToWindow, resolveFinalFrameExtractionWindow, resolveFrameFormat, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, isVideoHiddenBeforeStreamStart, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
+export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";

package/dist/services/audioMixer.js

@@ -339,7 +339,7 @@ function ffmpegFailure(stage, result, timeoutMs, elementId) {
         reason = "cancelled";
         owner = "user";
     }
-    else if (result.terminationReason === "deadline" || result.terminationReason === "inactivity") {
+    else if (result.terminationReason === "inactivity") {
         reason = "ffmpeg_timeout";
         retryable = true;
     }
@@ -692,14 +692,8 @@ async function generateSilence(outputPath, duration, signal, config) {
         failure,
     };
 }
-/** A mix graph's work grows with the film length (about 11 ms per film second at 96 inputs); so does its deadline. */
-const MIX_TIMEOUT_MS_PER_FILM_SECOND = 100;
-function mixProcessTimeout(config, totalDuration) {
-    const configured = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
-    return Math.max(configured, Math.ceil(totalDuration * MIX_TIMEOUT_MS_PER_FILM_SECOND));
-}
 async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
+    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const masterOutputGain = config?.audioGain ?? DEFAULT_CONFIG.audioGain;
     if (tracks.length === 0) {
         const result = await generateSilence(outputPath, totalDuration, signal, config);
@@ -876,7 +870,7 @@ function groupNormalizeOptionUnsupported(stderr) {
  * only runs when this ffmpeg build's `amix` rejects the option.
  */
 async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, signal, config) {
-    const ffmpegProcessTimeout = mixProcessTimeout(config, totalDuration);
+    const ffmpegProcessTimeout = config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout;
     const outputDir = dirname(outputPath);
     if (!existsSync(outputDir))
         mkdirSync(outputDir, { recursive: true });

package/dist/services/browserManager.d.ts

@@ -124,13 +124,13 @@ export declare function usesSoftwareWebGpu(requiresWebGpu: boolean | undefined,
 export declare function buildChromeArgs(options: BuildChromeArgsOptions, config?: GpuConfig): string[];
 /** Does the root, or a mounted root (data-hf-inner-root once bundled), declare `data-requires-webgpu`? */
 export declare function compositionRequiresWebGpu(html: string): boolean;
-/** No hardware WebGPU adapter on this host; distinct from a browser or navigation failure. */
+/** No usable WebGPU device on this launch; distinct from a browser or navigation failure. */
 export declare class WebGpuUnavailableError extends Error {
     constructor();
 }
 /**
- * Confirms the already-navigated page can obtain a hardware WebGPU adapter, or any adapter when the launch runs
- * software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
+ * Confirms the already-navigated page can create a device on a hardware WebGPU adapter, or any adapter when
+ * the launch runs software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
  * `page` must be on a secure-context origin, or navigator.gpu always reads absent.
  */
 export declare function assertWebGpuAdapterAvailable(page: Page, requiresWebGpu: boolean, softwareWebGpu?: boolean): Promise<void>;

package/dist/services/browserManager.js

@@ -666,7 +666,7 @@ async function launchBrowser(fingerprint) {
         });
         const browserVersion = await browser.version().catch(() => "unknown");
         const gpuFlags = fingerprint.args.filter((a) => a.startsWith("--use-gl=") || a.startsWith("--use-angle="));
-        console.log(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
+        console.error(`[BrowserManager] Browser launched (${browserVersion}, ${captureMode}, gl=${gpuFlags.join(" ") || "default"}, headlessShell=${!!fingerprint.executablePath}, platform=${process.platform})`);
         if (captureMode === "beginframe") {
             const probe = await probeBeginFrameSupport(browser).catch((error) => ({
                 supported: true,
@@ -909,43 +909,63 @@ export function compositionRequiresWebGpu(html) {
     }
     return false;
 }
-/** No hardware WebGPU adapter on this host; distinct from a browser or navigation failure. */
+/** No usable WebGPU device on this launch; distinct from a browser or navigation failure. */
 export class WebGpuUnavailableError extends Error {
     constructor() {
-        super("This composition declares data-requires-webgpu, but no hardware WebGPU adapter could be " +
-            "obtained on this browser launch. Run on a host with a GPU, set " +
+        super("This composition declares data-requires-webgpu, but a usable WebGPU device could not be " +
+            "created on this browser launch. Run on a host with a GPU, set " +
             "PRODUCER_ALLOW_SOFTWARE_WEBGPU=true to render it on SwiftShader (slow), or remove " +
             "data-requires-webgpu.");
         this.name = "WebGpuUnavailableError";
     }
 }
-const WEBGPU_ADAPTER_PROBE_TIMEOUT_MS = 10_000;
+const WEBGPU_DEVICE_PROBE_TIMEOUT_MS = 10_000;
 /**
- * Confirms the already-navigated page can obtain a hardware WebGPU adapter, or any adapter when the launch runs
- * software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
+ * Confirms the already-navigated page can create a device on a hardware WebGPU adapter, or any adapter when
+ * the launch runs software WebGPU ({@link usesSoftwareWebGpu}); no-op otherwise.
  * `page` must be on a secure-context origin, or navigator.gpu always reads absent.
  */
 export async function assertWebGpuAdapterAvailable(page, requiresWebGpu, softwareWebGpu = false) {
     if (!requiresWebGpu)
         return;
-    // requestAdapter() has no native timeout; a broken driver can hang it
-    // indefinitely. Race it in-page so a stuck adapter reads as "unavailable"
-    // instead of hanging the caller.
-    const hasUsableAdapter = await page.evaluate(async (timeoutMs, acceptFallback) => {
+    // An adapter can exist even when missing driver libraries make device creation fail.
+    // Both requests can hang; share one deadline and release late devices as well.
+    const hasUsableDevice = await page.evaluate(async (timeoutMs, acceptFallback) => {
         if (typeof navigator === "undefined" || !navigator.gpu)
             return false;
+        let expired = false;
+        let timer;
         try {
-            const adapter = await Promise.race([
-                navigator.gpu.requestAdapter(),
-                new Promise((resolve) => setTimeout(() => resolve(null), timeoutMs)),
+            const probe = async () => {
+                const adapter = await navigator.gpu.requestAdapter();
+                if (!adapter || expired || (!acceptFallback && adapter.info.isFallbackAdapter))
+                    return false;
+                const device = await adapter.requestDevice();
+                try {
+                    return !expired;
+                }
+                finally {
+                    device.destroy();
+                }
+            };
+            return await Promise.race([
+                probe(),
+                new Promise((resolve) => {
+                    timer = setTimeout(() => {
+                        expired = true;
+                        resolve(false);
+                    }, timeoutMs);
+                }),
             ]);
-            return !!adapter && (acceptFallback || !adapter.info.isFallbackAdapter);
         }
         catch {
             return false;
         }
-    }, WEBGPU_ADAPTER_PROBE_TIMEOUT_MS, softwareWebGpu);
-    if (!hasUsableAdapter)
+        finally {
+            clearTimeout(timer);
+        }
+    }, WEBGPU_DEVICE_PROBE_TIMEOUT_MS, softwareWebGpu);
+    if (!hasUsableDevice)
         throw new WebGpuUnavailableError();
 }
 function getBrowserGpuArgs(mode, platform) {

package/dist/services/chunkEncoder.js

@@ -27,15 +27,9 @@ export const ENCODER_PRESETS = {
 function appendEncodeTimeoutMessage(error, timedOut, timeoutMs) {
     if (!timedOut)
         return error;
-    // Two independent reports of this exact timeout, both resolved by env vars
-    // that already exist but aren't named anywhere the user would see them at
-    // the point of failure — they had to go find FFMPEG_ENCODE_TIMEOUT_MS and
-    // PRODUCER_ENABLE_CHUNKED_ENCODE themselves. Name both here instead of
-    // just stating what happened.
-    return (`${error}\nFFmpeg killed after exceeding ffmpegEncodeTimeout (${timeoutMs} ms). ` +
-        "Long or high-frame-count renders may need more time: set FFMPEG_ENCODE_TIMEOUT_MS " +
-        "to a higher value (ms), or set PRODUCER_ENABLE_CHUNKED_ENCODE=true to encode in " +
-        "smaller chunks instead of one long-running ffmpeg process.");
+    return (`${error}\nFFmpeg killed after writing no new frame for ffmpegEncodeTimeout (${timeoutMs} ms). ` +
+        "An encode that is still writing frames is never stopped; if this encoder legitimately " +
+        "pauses longer between frames, raise FFMPEG_ENCODE_TIMEOUT_MS (ms).");
 }
 function isAacSidecar(audioPath) {
     return extname(audioPath).toLowerCase() === ".aac";
@@ -430,7 +424,7 @@ export async function encodeFramesFromDir(framesDir, framePattern, outputPath, o
             framesEncoded: 0,
             fileSize: 0,
             error: appendEncodeTimeoutMessage(frameReadFailure(result.stderr, framePattern, 0, framesRead, frameCount) +
-                formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "deadline", encodeTimeout),
+                formatFfmpegError(result.exitCode, result.stderr), result.terminationReason === "inactivity", encodeTimeout),
             failureReason: isExternalFfmpegInterruption(result) ? "external_interruption" : undefined,
         };
     }
@@ -492,7 +486,7 @@ export async function concatVideoFiles(inputPaths, outputPath, signal, config) {
         return { success: true };
     return {
         success: false,
-        error: appendEncodeTimeoutMessage(`Chunk concat failed: ${result.stderr.slice(-400)}`, result.terminationReason === "deadline", encodeTimeout),
+        error: appendEncodeTimeoutMessage(`Chunk concat failed: ${result.stderr.slice(-400)}`, result.terminationReason === "inactivity", encodeTimeout),
         externalInterruption: isExternalFfmpegInterruption(result),
     };
 }
@@ -566,7 +560,7 @@ export async function encodeFramesChunkedConcat(framesDir, framePattern, outputP
             success: processResult.success,
             error: processResult.success
                 ? undefined
-                : appendEncodeTimeoutMessage(frameReadFailure(processResult.stderr, framePattern, startNumber, framesRead, framesInChunk) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "deadline", encodeTimeout),
+                : appendEncodeTimeoutMessage(frameReadFailure(processResult.stderr, framePattern, startNumber, framesRead, framesInChunk) + `Chunk ${i} encode failed: ${processResult.stderr.slice(-400)}`, processResult.terminationReason === "inactivity", encodeTimeout),
         };
         if (!chunkResult.success) {
             return {

package/dist/services/frameCapture.js

@@ -17,7 +17,7 @@ import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERT
 import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
 // ── Extracted modules ───────────────────────────────────────────────────────
 import { acquireBrowser, releaseBrowser, forceReleaseBrowser, buildChromeArgs, resolveBrowserGpuMode, captureWithoutWaylandDisplay, resolveHeadlessShellPath, compositionRequiresWebGpu, assertWebGpuAdapterAvailable, usesSoftwareWebGpu, } from "./browserManager.js";
-import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
+import { beginFrameCapture, ensureRenderFrameSiblings, getCdpSession, pageContentExceedsCaptureHeight, pageScreenshotCapture, initTransparentBackground, capturesAlpha, shouldDefaultCaptureBeyondViewport, } from "./screenshotService.js";
 import { classifyGpuRenderer, detectGpuBackend, injectDrawElementCanvas, captureDrawElementFrame, resolveDrawElementCaptureMode, instrumentAcceleratedCanvases, initDrawElementWorkerEncode, cleanupDrawElementWorkerEncode, produceDrawElementFrame, produceDrawElementFrameBatch, DE_CANVAS_NOT_INITIALIZED_CODE, } from "./drawElementService.js";
 import { initThreeDProjection, scanCssEffects } from "./threeDProjection.js";
 import { planRiskFrames, scanCssEffectLiveFrames, riskSessionFits, withFramesAfterCallback, MAX_RISK_FRAME_FRACTION, } from "./riskFrames.js";
@@ -474,20 +474,20 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
     if ((session.config?.useDrawElement ?? false) && supersampling) {
         session.deGateReason = "supersampling";
         session.deFallbackTrigger = "supersampling";
-        console.log("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
+        console.error("[engine] --experimental-fast-capture disabled for this render: drawElementImage " +
             "ignores deviceScaleFactor, so scaled (DPR other than 1) output uses screenshot capture.");
     }
     if ((session.config?.useDrawElement ?? false) && !supersampling && forceScreenshot) {
         session.deGateReason = "render_mode_hint";
         session.deFallbackTrigger = "render_mode_hint";
-        console.log("[engine] fast capture falls back to screenshot: render-mode compatibility " +
+        console.error("[engine] fast capture falls back to screenshot: render-mode compatibility " +
             "hint forced screenshot capture (e.g. raw requestAnimationFrame composition).");
     }
     if (useDrawElement) {
         const gpuBackend = await detectGpuBackend(page);
         session.isSwiftShader = gpuBackend.isSwiftShader;
         session.gpuRenderer = classifyGpuRenderer(gpuBackend.renderer);
-        const transparent = session.options.format === "png";
+        const transparent = capturesAlpha(session.options);
         async function routeToFallback() {
             session.captureMode = session.launchCaptureMode;
             if (transparent) {
@@ -528,7 +528,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
         if (!supportsDrawElement) {
             session.deGateReason = "unsupported_chrome";
             session.deFallbackTrigger = "unsupported_chrome";
-            console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+            console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
                 "this Chrome build does not implement canvas.drawElementImage (Dev/Canary-only " +
                 "feature); run `hyperframes browser ensure --force` to fetch a supported " +
                 "build, or set HYPERFRAMES_BROWSER_PATH to one.");
@@ -576,7 +576,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             // "screenshot": on a BeginFrame-launched browser (Linux fast capture)
             // Page.captureScreenshot hangs for the full protocol timeout, while
             // beginFrameCapture is the platform's normal baseline path.
-            console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+            console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
                 "SwiftShader (software rasterizer, no GPU egress to skip, drawElement is " +
                 "parity-or-slower; see fast-capture-limitations.md)");
             await routeToFallback();
@@ -598,7 +598,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             const routeWholeRender = async (reason, trigger, message) => {
                 session.deGateReason = reason;
                 session.deFallbackTrigger = trigger;
-                console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ${message}`);
+                console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ${message}`);
                 await routeToFallback();
             };
             if (!forceDE && process.env.HF_FAST_CAPTURE_CSSFX !== "true") {
@@ -682,7 +682,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             if (!forceDE && !threeD.ok) {
                 session.deGateReason = "3d_init_failed";
                 session.deFallbackTrigger = "3d_init_failed";
-                console.log(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
+                console.error(`[engine] fast capture falls back to ${session.launchCaptureMode} capture: ` +
                     `3D projection init failed (${threeD.reason ?? "unknown"})`);
                 await routeToFallback();
                 return;
@@ -715,7 +715,7 @@ async function initDrawElementOrTransparentBackground(session, page, logInitPhas
             await finalizeDrawElementInit(session, page, logInitPhase, { transparent, forceDE });
         }
     }
-    else if (session.options.format === "png") {
+    else if (capturesAlpha(session.options)) {
         await initTransparentBackground(session.page);
     }
 }
@@ -747,7 +747,7 @@ async function cssEffectRiskFrames(session, totalFrames) {
         return live && withFramesAfterCallback(live, scan.callbackFrom, fps, totalFrames);
     }
     catch (error) {
-        console.log(`[engine] fast capture: effect scan failed (${error instanceof Error ? error.message : String(error)})`);
+        console.error(`[engine] fast capture: effect scan failed (${error instanceof Error ? error.message : String(error)})`);
         return null;
     }
     finally {
@@ -817,9 +817,9 @@ export async function completeDeferredDrawElementInit(session) {
     if (!session.deInitDeferred || !session.onBeforeCapture)
         return;
     const page = session.page;
-    const logInitPhase = (phase) => console.log(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
+    const logInitPhase = (phase) => console.error(`[initSession:${session.captureMode}] ${phase} (deferred drawElement init)`);
     await finalizeDrawElementInit(session, page, logInitPhase, {
-        transparent: session.options.format === "png",
+        transparent: capturesAlpha(session.options),
         forceDE: process.env.HF_FORCE_DRAWELEMENT === "1",
     });
     session.deInitDeferred = false;
@@ -852,7 +852,7 @@ export async function createCaptureSession(serverUrl, outputDir, options, onBefo
     const isLinux = process.platform === "linux";
     const forceScreenshot = config?.forceScreenshot ?? DEFAULT_CONFIG.forceScreenshot;
     const useDrawElement = config?.useDrawElement ?? false;
-    const drawElementTransparent = useDrawElement && options.format === "png";
+    const drawElementTransparent = useDrawElement && capturesAlpha(options);
     // drawElement and page-side shader compositing are mutually incompatible
     // capture strategies: drawElement reads the composition root's paint records
     // directly and skips the prepare→micro-screenshot→resolve protocol (the
@@ -1849,14 +1849,14 @@ export function classifyPageError(details, projectScripts) {
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
     // Forward browser console to host. HyperFrames runtime logs get a dedicated
-    // prefix so page-context observability is visible in producer stdout.
+    // prefix so page-context observability is visible in producer stderr.
     page.on("console", (msg) => {
         const type = msg.type();
         const text = msg.text();
         const locationUrl = msg.location()?.url ?? "";
         const diagnostic = formatConsoleDiagnostic(type, text, locationUrl);
         if (!diagnostic.suppressHostLog && !loggedEarlierInRender(session, text)) {
-            console.log(diagnostic.text);
+            console.error(diagnostic.text);
         }
         appendBrowserDiagnostic(session, diagnostic.text);
         // A blocked script can never register its timeline (#3352); a thrown one may still, so it only counts on timeout.
@@ -1921,7 +1921,7 @@ export async function initializeSession(session) {
     const pageNavigationTimeout = session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
     const initStart = Date.now();
     const logInitPhase = (phase) => {
-        console.log(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
+        console.error(`[initSession:${session.captureMode}] ${phase} (${Date.now() - initStart}ms)`);
     };
     const gotoEntryPage = async () => {
         appendBrowserDiagnostic(session, formatNavigationStartDiagnostic({
@@ -2673,7 +2673,7 @@ export async function createStaticVerificationPage(session) {
             page.evaluate(`document.fonts?.ready`),
             waitForOptionalTailwindReady(page, pageReadyTimeout),
         ]);
-        if (session.options.format === "png")
+        if (capturesAlpha(session.options))
             await initTransparentBackground(page);
         return page;
     }
@@ -3377,6 +3377,13 @@ async function captureAccumulatedFrame(session, frameIndex, absFrameIndex, plan)
         ...totals,
     };
 }
+function framesAreStatic(staticFrames, from, to) {
+    for (let frame = from; frame <= to; frame++) {
+        if (!staticFrames.has(frame))
+            return false;
+    }
+    return true;
+}
 async function captureFrameCore(session, frameIndex, time) {
     const { options } = session;
     const startTime = Date.now();
@@ -3397,7 +3404,8 @@ async function captureFrameCore(session, frameIndex, time) {
     const absFrameIndex = Math.floor(time * fpsToNumber(options.fps) + 1e-9);
     if (session.staticFrames?.has(absFrameIndex) &&
         session.lastFrameBuffer &&
-        session.lastFrameAbsoluteIndex === absFrameIndex - 1 &&
+        session.lastFrameAbsoluteIndex !== undefined &&
+        framesAreStatic(session.staticFrames, session.lastFrameAbsoluteIndex + 1, absFrameIndex) &&
         (!session.motionBlur ||
             motionBlurWindowIsStatic(session.motionBlur, absFrameIndex, session.staticFrames))) {
         session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
@@ -3425,7 +3433,7 @@ async function captureFrameCore(session, frameIndex, time) {
         if (session.capturePerf.frames === 1) {
             const blur = await describePageMotionBlur(session.page).catch(() => null);
             if (blur)
-                console.log(blur);
+                console.error(blur);
         }
         // Retain this freshly-captured buffer so the following static frames can reuse it.
         if (session.staticFrames) {
@@ -3484,7 +3492,7 @@ export async function captureFrameToBuffer(session, frameIndex, time) {
             // works. Counted here rather than in captureFrameCore's catch: the
             // deadline rejects from outside it, so that catch never runs.
             session.deFrameTimeouts = (session.deFrameTimeouts ?? 0) + 1;
-            console.log(`[engine] fast capture frame ${frameIndex}: capture exceeded ` +
+            console.error(`[engine] fast capture frame ${frameIndex}: capture exceeded ` +
                 `${DE_FRAME_TIMEOUT_MS}ms; renderer stalled after drawElementImage ` +
                 `(PRINFRA-488). Failing the drawElement attempt so the whole render ` +
                 `retries via screenshot.`);
@@ -3527,13 +3535,7 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
         // same pixels. Sequential capture reduces to has(i) (gap = {i}); the
         // interleaved parallel stride makes the gap N frames wide.
         const lastIdx = session.lastEncodeResultFrame ?? frameIndex - 1;
-        let gapStatic = true;
-        for (let j = lastIdx + 1; j <= frameIndex; j++) {
-            if (!session.staticFrames.has(j)) {
-                gapStatic = false;
-                break;
-            }
-        }
+        const gapStatic = framesAreStatic(session.staticFrames, lastIdx + 1, frameIndex);
         if (gapStatic) {
             session.staticDedupCount = (session.staticDedupCount ?? 0) + 1;
             session.capturePerf.frames += 1;
@@ -3689,7 +3691,7 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
             throw new DrawElementCaptureError(frameIndices[failedAt] ?? failedAt, reason, error);
         }
         else {
-            console.log(`[engine] fast capture: batch produce failed at frame ` +
+            console.error(`[engine] fast capture: batch produce failed at frame ` +
                 `${frameIndices[failedAt] ?? "?"} (${error ?? "?"}); ` +
                 `re-capturing ${frameIndices.length - failedAt} frame(s) per-frame`);
             for (let i = failedAt; i < frameIndices.length; i++) {
@@ -3768,7 +3770,7 @@ export async function closeCaptureSession(session) {
     if (session.page && !session.pageReleased) {
         const blur = await describePageMotionBlurAtEnd(session.page);
         if (blur)
-            console.log(blur);
+            console.error(blur);
     }
     // Realized static-dedup telemetry: how much the cache actually helped this
     // render (vs the prediction logged at arm time). Both capture paths
@@ -3781,7 +3783,7 @@ export async function closeCaptureSession(session) {
         const total = captured + reused;
         const pct = total > 0 ? Math.round((reused / total) * 100) : 0;
         const avgTotalMs = captured > 0 ? Math.round(session.capturePerf.totalMs / captured) : 0;
-        console.log(`[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
+        console.error(`[static-dedup] reused ${reused}/${total} frame(s) (${pct}%), ` +
             `est. ~${reused * avgTotalMs}ms saved (avg ${avgTotalMs}ms/frame)`);
         session.staticDedupCount = 0;
     }

package/dist/services/parallelCoordinator.js

@@ -358,7 +358,7 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
                 throw new Error("Parallel worker cancelled");
             const time = (i * captureOptions.fps.den) / captureOptions.fps.num;
             if (dbg && i < task.startFrame + dbgWin) {
-                console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} start`);
+                console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} start`);
             }
             const { encodeResult } = await runCaptureOperation("frame_capture", i, () => captureFrameToBufferPipelined(session, i - outputOffset, time));
             // Marks the promise "handled" for Node's unhandled-rejection detector
@@ -368,19 +368,19 @@ async function captureFrameRange(session, task, captureOptions, signal, onFrameC
             // and would otherwise surface as an unhandled rejection during teardown.
             encodeResult.catch(() => { });
             if (dbg && i < task.startFrame + dbgWin) {
-                console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} kicked`);
+                console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms produce ${i} kicked`);
             }
             if (prev) {
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} await-encode`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} await-encode`);
                 }
                 const buf = await awaitEncode(prev.idx, prev.encodeResult);
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} encoded ${buf.length}B`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} encoded ${buf.length}B`);
                 }
                 await onFrameBuffer(prev.idx, buf, session);
                 if (dbg && prev.idx < task.startFrame + dbgWin) {
-                    console.log(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} written`);
+                    console.error(`[par:w${task.workerId}] +${Date.now() - dbgT0}ms drain ${prev.idx} written`);
                 }
                 framesCaptured++;
                 if (onFrameCaptured)
@@ -453,7 +453,7 @@ export function selectVerifySampleIndicesForTask(sampleIndices, task) {
 /** HF_DE_PAR_DEBUG=1 gated per-worker trace line (message built lazily). */
 function logParDebug(message) {
     if (process.env.HF_DE_PAR_DEBUG === "1")
-        console.log(message());
+        console.error(message());
 }
 /**
  * Throw the verification error for a sample below the PSNR floor; log the
@@ -466,7 +466,7 @@ function assertDiskSampleAboveFloor(db, verifyMinDb, idx, workerId) {
         throw new DrawElementVerificationError(`drawElement self-verify failed at frame ${idx} (disk path, worker ${workerId}): ` +
             `${db.toFixed(1)}dB < ${verifyMinDb}dB vs pre-injection screenshot`, { kind: "psnr", frameIndex: idx, failedDb: db, verifyThresholdDb: verifyMinDb });
     }
-    console.log(`[Parallel] drawElement disk self-verify passed (worker ${workerId}, frame ${idx}, ` +
+    console.error(`[Parallel] drawElement disk self-verify passed (worker ${workerId}, frame ${idx}, ` +
         `${db === Infinity ? "inf" : db.toFixed(1)}dB)`);
 }
 /**

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

@@ -150,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

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

package/dist/utils/runFfmpeg.js

@@ -94,11 +94,11 @@ export function formatFfmpegError(exitCode, stderr, tailLines = DEFAULT_STDERR_T
         ? `FFmpeg exited with code ${exitCode}\nffmpeg stderr (tail):\n${tail}`
         : `FFmpeg exited with code ${exitCode}`;
 }
-/** 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 function describeFfmpegFailure(result, timeoutMs) {
     const error = formatFfmpegError(result.exitCode, result.stderr);
-    if (result.terminationReason === "deadline") {
-        return (`FFmpeg timed out after ${timeoutMs} ms (ffmpegProcessTimeout; long renders can raise ` +
+    if (result.terminationReason === "inactivity") {
+        return (`FFmpeg timed out after ${timeoutMs} ms without progress (ffmpegProcessTimeout, ` +
             `FFMPEG_PROCESS_TIMEOUT_MS). ${error}`);
     }
     if (result.exitCode !== null)
@@ -147,25 +147,22 @@ const ABORTED_BEFORE_START = {
 export async function runFfmpeg(args, opts) {
     if (opts?.signal?.aborted)
         return { ...ABORTED_BEFORE_START };
-    const stallTimeout = opts?.stallTimeout;
     let framesWritten = 0;
-    const readStats = ffmpegStatsReader(({ frames }) => {
-        if (frames === undefined || frames <= framesWritten)
+    let secondsWritten = 0;
+    const readStats = ffmpegStatsReader(({ frames = 0, seconds = 0 }) => {
+        if (frames <= framesWritten && seconds <= secondsWritten)
             return;
-        framesWritten = frames;
+        framesWritten = Math.max(frames, framesWritten);
+        secondsWritten = Math.max(seconds, secondsWritten);
         managed.markActivity();
     });
     const managed = new ManagedChildProcess(spawnFfmpeg(args), {
         signal: opts?.signal,
-        ...(stallTimeout === undefined
-            ? { deadlineAtMs: Date.now() + (opts?.timeout ?? DEFAULT_TIMEOUT) }
-            : { inactivityTimeoutMs: stallTimeout }),
-        onStderr: stallTimeout === undefined
-            ? opts?.onStderr
-            : (chunk) => {
-                readStats(chunk);
-                opts?.onStderr?.(chunk);
-            },
+        inactivityTimeoutMs: opts?.timeout ?? DEFAULT_TIMEOUT,
+        onStderr: (chunk) => {
+            readStats(chunk);
+            opts?.onStderr?.(chunk);
+        },
     });
     return toResult(await managed.wait());
 }

package/dist/utils/urlDownloader.js

@@ -586,7 +586,7 @@ function checksumMismatchError(source, status, telemetry) {
 // Response protocol, streamed byte accounting, hashes, and payload validation
 // share one lifecycle so no validation can happen after publication.
 // fallow-ignore-next-line complexity
-async function fetchToPartial(url, partialPath, controller, options) {
+async function fetchToPartial(url, partialPath, controller, options, onSizedBodyBytes) {
     const { response, finalUrl } = await fetchWithValidatedRedirects(url, controller);
     const finalIdentity = safeDownloadUrlIdentity(finalUrl);
     const rangeDisposition = classifyRangeDisposition(response);
@@ -643,6 +643,8 @@ async function fetchToPartial(url, partialPath, controller, options) {
     const inspector = new Transform({
         transform(chunk, _encoding, callback) {
             const bytes = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+            if (declaredLength !== undefined)
+                onSizedBodyBytes();
             receivedBytes += bytes.length;
             sha256.update(bytes);
             md5.update(bytes);
@@ -771,16 +773,26 @@ async function runDownloadAttempt(url, localPath, timeoutMs, attempt, options, s
         controller.abort();
     };
     signal?.addEventListener("abort", onCallerAbort, { once: true });
-    const timeoutId = setTimeout(() => {
-        timedOut = true;
-        controller.abort();
-    }, timeoutMs);
+    let timeoutId;
+    const armTimeout = () => {
+        clearTimeout(timeoutId);
+        timeoutId = setTimeout(() => {
+            timedOut = true;
+            controller.abort();
+        }, timeoutMs);
+    };
+    armTimeout();
+    let sizedBodyStarted = false;
+    const extendTimeout = () => {
+        sizedBodyStarted = true;
+        armTimeout();
+    };
     const identity = safeDownloadUrlIdentity(url);
     try {
         if (callerAborted) {
             throw new UrlDownloadError("cancelled", false, "Download cancelled");
         }
-        const integrity = await fetchToPartial(url, partialPath, controller, options);
+        const integrity = await fetchToPartial(url, partialPath, controller, options, extendTimeout);
         let outcome = syncAndPublishPartial(partialPath, localPath);
         let publishedIntegrity = integrity;
         if (outcome === "race_reused") {
@@ -827,7 +839,9 @@ async function runDownloadAttempt(url, localPath, timeoutMs, attempt, options, s
             throw classified;
         }
         if (timedOut) {
-            const classified = new UrlDownloadError("timeout", true, `Download timeout after ${timeoutMs / 1000}s`);
+            const classified = new UrlDownloadError("timeout", true, sizedBodyStarted
+                ? `Download stalled: no data for ${timeoutMs / 1000}s`
+                : `Download timeout after ${timeoutMs / 1000}s`);
             emitDownloadTelemetry(options, {
                 urlFingerprint: identity.urlFingerprint,
                 initialHost: identity.host,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hyperframes/engine",
-  "version": "0.8.200",
+  "version": "0.8.201",
   "description": "Seekable web page to video rendering engine (Puppeteer + FFmpeg)",
   "repository": {
     "type": "git",
@@ -50,8 +50,8 @@
     "linkedom": "^0.18.12",
     "puppeteer": "^25.8.0",
     "puppeteer-core": "^25.8.0",
-    "@hyperframes/core": "^0.8.200",
-    "@hyperframes/parsers": "^0.8.200"
+    "@hyperframes/core": "^0.8.201",
+    "@hyperframes/parsers": "^0.8.201"
   },
   "devDependencies": {
     "@types/node": "^25.0.10",