@hyperframes/engine 0.8.205 → 0.8.207

package/dist/index.d.ts

@@ -43,10 +43,10 @@ export { CaptureFailure, classifyCaptureFailure, isFatalCaptureFailure, type Cap
 export { createChromeMemorySampler, type ChromeMemoryStats, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.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 { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, 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, 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 { 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, sdrCanvasColourFilters, } 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";
@@ -55,7 +55,7 @@ export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCo
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 export type { AudioElement, AudioFailureReason, AudioFailureStage, AudioProcessingFailure, AudioFailureDiagnostic, AudioSubprocessEvidence, AudioTrack, AudioVolumeKeyframe, MixResult, } from "./services/audioMixer.types.js";
-export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, } from "./services/parallelCoordinator.js";
+export { calculateOptimalWorkers, computeWorkerSizing, selectVerifySampleIndicesForTask, verifyDiskDrawElementSamples, distributeFrames, distributeFramesInterleaved, executeParallelCapture, mergeWorkerFrames, getSystemResources, shouldDisableBrowserPoolForParallelWorker, type WorkerTask, type WorkerResult, type WorkerSizing, type WorkerSizingBound, type LandedFrame, type ParallelProgress, type ParallelWorkerPhaseDiagnostic, } from "./services/parallelCoordinator.js";
 export { createFileServer, type FileServerOptions, type FileServerHandle, } from "./services/fileServer.js";
 export { quantizeTimeToFrame, MEDIA_VISUAL_STYLE_PROPERTIES } from "@hyperframes/core";
 export { frameFileExtension } from "./services/frameCapture.js";
@@ -65,7 +65,7 @@ export type { MotionBlurOptions, MotionBlurBlendSpace } from "./services/motionB
 export type { PageMotionBlurOff } from "./types.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
-export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, type VideoMetadata, type AudioMetadata, type MediaProbeProfile, type KeyframeAnalysis, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, type SafeDownloadUrlIdentity, type UrlDownloadOptions, type UrlDownloadTelemetry, type PublicHttpsTextOptions, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, type RunFfmpegOptions, type RunFfmpegResult, } from "./utils/runFfmpeg.js";
@@ -74,6 +74,7 @@ export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChild
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
 export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
+export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";
 export { decodePng, decodePngToRgb48le, blitRgba8OverRgb48le, blitRgb48leRegion, blitRgb48leAffine, parseTransformMatrix, roundedRectAlpha, resampleRgb48leObjectFit, normalizeObjectFit, type ObjectFit, } from "./utils/alphaBlit.js";
 export { groupIntoLayers, type CompositeLayer } from "./utils/layerCompositor.js";

package/dist/index.js

@@ -47,10 +47,10 @@ export { createChromeMemorySampler, } from "./services/chromeMemorySampler.js";
 export { installMediaRenderIdBridge } from "./services/mediaRenderIdBridge.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 { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, 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, 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 { 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, sdrCanvasColourFilters, } from "./services/videoFrameExtractor.js";
 export { isSelfOrAncestorHidden } from "./services/mediaHidden.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
@@ -69,7 +69,7 @@ export { appendSoftwareEncoderThreadsArg } from "./services/softwareEncoderThrea
 export { frameSequencePath } from "./services/extractedFrameIndex.js";
 export { assertSwiftShader, readWebGlVendorInfo, SwiftShaderAssertionError, BROWSER_GPU_NOT_SOFTWARE, } from "./utils/assertSwiftShader.js";
 export { readWebGlVendorInfoFromCanvas } from "./utils/readWebGlVendorInfoFromCanvas.js";
-export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, runFfprobe, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
 export { NOT_MEDIA_PAYLOAD, NotMediaPayloadError, assertMediaPayload, fingerprintElementId, isNotMediaPayload, } from "./utils/notMediaPayload.js";
 export { assertPublicHttpsUrl, isBlockedNetworkHost, downloadToTemp, fetchPublicHttpsText, isHttpUrl, safeDownloadUrlIdentity, writeUrlDownloadTelemetry, } from "./utils/urlDownloader.js";
 export { runFfmpeg, formatFfmpegError, describeFfmpegFailure, isExternalFfmpegInterruption, } from "./utils/runFfmpeg.js";
@@ -78,6 +78,7 @@ export { ManagedChildProcess, } from "./utils/managedChildProcess.js";
 export { assertConfiguredFfmpegBinariesExist, getFfmpegBinary, getFfprobeBinary, FFMPEG_PATH_ENV, FFPROBE_PATH_ENV, } from "./utils/ffmpegBinaries.js";
 export { trackChildProcess, killTrackedProcesses } from "./utils/processTracker.js";
 export { renameWithRetry, renameWithRetryAsync } from "./utils/renameWithRetry.js";
+export { removeScratch, collectScratchLeftovers } from "./utils/removeScratch.js";
 // drawElement self-verify comparison — shared by the streaming drain
 // (producer) and the parallel disk-path verify (parallelCoordinator).
 export { psnrDb, resolveDeVerifyMinDb } from "./utils/psnr.js";

package/dist/services/aacEncode.js

@@ -3,7 +3,8 @@
  * so long audio is encoded as frame-aligned segments in parallel and their frames joined.
  */
 import { execFile } from "node:child_process";
-import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { mkdtempSync, readFileSync, writeFileSync } from "node:fs";
+import { removeScratch } from "../utils/removeScratch.js";
 import { dirname, join } from "node:path";
 import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
@@ -133,6 +134,6 @@ export async function encodeAac(input, outputPath, totalDuration, { signal, time
         return { ...muxed, durationMs: slowest + muxed.durationMs };
     }
     finally {
-        rmSync(dir, { recursive: true, force: true });
+        removeScratch(dir);
     }
 }

package/dist/services/audioFxRender.js

@@ -11,13 +11,14 @@
  * dynamics processors and the modulated delays) have no filter that behaves the
  * same way, so preview would quietly stop predicting the render.
  */
-import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, rmSync, statSync, writeFileSync, writeSync, } from "node:fs";
+import { closeSync, existsSync, mkdtempSync, openSync, readFileSync, readSync, statSync, writeFileSync, writeSync, } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { pathToFileURL } from "node:url";
 import { getAudioFxRuntimeScript } from "@hyperframes/core/audio-fx-runtime";
 import { enabledAudioFxNodes } from "@hyperframes/core/audio-fx";
 import { serializeAutomation } from "@hyperframes/core/audio-automation";
+import { removeScratch } from "../utils/removeScratch.js";
 import { acquireBrowser } from "./browserManager.js";
 import { createEnvelopeWalker } from "./audioVolumeEnvelope.js";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
@@ -460,7 +461,7 @@ async function withFxBrowser(options, body) {
         throw new AudioFxRenderError(`Audio FX failed for track ${options.trackId}: ${err.message}`);
     }
     finally {
-        rmSync(hostDir, { recursive: true, force: true });
+        removeScratch(hostDir);
         await lease?.release().catch(() => undefined);
     }
 }

package/dist/services/audioMixer.js

@@ -2,6 +2,7 @@
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
 import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
 import { renameWithRetry } from "../utils/renameWithRetry.js";
+import { removeScratch } from "../utils/removeScratch.js";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -575,7 +576,7 @@ async function extractAudioSegment(srcPath, outputPath, stage, mediaStart, durat
             };
         }
         finally {
-            rmSync(cycleDir, { recursive: true, force: true });
+            removeScratch(cycleDir);
         }
     }
     const inputSeek = mediaStart >= (metadata?.latestStreamLeadSeconds ?? 0);
@@ -773,7 +774,7 @@ async function mixAudioTracksFlat(tracks, outputPath, totalDuration, signal, con
             return await runFfmpeg(currentArgs, { signal, timeout: ffmpegProcessTimeout });
         }
         finally {
-            rmSync(scriptDir, { recursive: true, force: true });
+            removeScratch(scriptDir);
         }
     };
     let useNormalize = true;
@@ -934,7 +935,7 @@ async function mixGroupMembersFlat(memberTracks, outputPath, totalDuration, sign
             return await runFfmpeg(currentArgs, { signal, timeout: ffmpegProcessTimeout });
         }
         finally {
-            rmSync(scriptDir, { recursive: true, force: true });
+            removeScratch(scriptDir);
         }
     };
     let useNormalize = true;
@@ -991,8 +992,8 @@ async function sumInSlices(tracks, scratchDir, totalDuration, signal, config) {
         }
         const foldedPath = join(scratchDir, `${id}.wav`);
         const folded = await mixGroupMembersFlat([running, wavTrack(`${id}-slice`, slicePath)], foldedPath, totalDuration, signal, config);
-        rmSync(running.srcPath, { force: true });
-        rmSync(slicePath, { force: true });
+        removeScratch(running.srcPath);
+        removeScratch(slicePath);
         if (!folded.success)
             return folded;
         running = wavTrack(id, foldedPath);
@@ -1011,11 +1012,11 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         const summed = await sumInSlices(memberTracks, scratchDir, totalDuration, signal, config);
         if (!summed.success)
             return summed;
-        renameWithRetry(summed.track.srcPath, outputPath);
+        renameWithRetry(summed.track.srcPath, outputPath, { copyFallback: true });
         return { success: true, degradedAutomation: summed.degradedAutomation };
     }
     finally {
-        rmSync(scratchDir, { recursive: true, force: true });
+        removeScratch(scratchDir);
     }
 }
 async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config) {
@@ -1048,7 +1049,7 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
             : mixed;
     }
     finally {
-        rmSync(scratchDir, { recursive: true, force: true });
+        removeScratch(scratchDir);
     }
 }
 /**
@@ -1085,7 +1086,7 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         };
     }
     if (config?.keepEncoderInputAt)
-        renameWithRetry(encoderInput, config.keepEncoderInputAt);
+        renameWithRetry(encoderInput, config.keepEncoderInputAt, { copyFallback: true });
     return {
         ...sum,
         outputPath,

package/dist/services/browserManager.d.ts

@@ -12,8 +12,9 @@ export { BrowserLeasePool } from "./browserLeasePool.js";
 export type { BrowserLaunchFingerprint, BrowserLease, BrowserPoolState, CaptureMode, } from "./browserLeasePool.js";
 /** Set while the host cancels renders on Ctrl+C; Puppeteer's own handler would exit before any cleanup ran. */
 export declare function setHostHandlesSigint(owned: boolean): void;
-export declare const sigintLaunchOptions: () => {
+export declare const ownedLaunchOptions: () => {
     handleSIGINT: boolean;
+    pipe: boolean;
 };
 export interface GpuProbeLifecycle {
     launch(puppeteer: PuppeteerNode, options: LaunchOptions): Promise<Browser>;

package/dist/services/browserManager.js

@@ -23,7 +23,7 @@ let hostHandlesSigint = false;
 export function setHostHandlesSigint(owned) {
     hostHandlesSigint = owned;
 }
-export const sigintLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint });
+export const ownedLaunchOptions = () => ({ handleSIGINT: !hostHandlesSigint, pipe: true });
 function isSoftwareWebGlRenderer(rendererInfo) {
     const renderer = rendererInfo.trim().toLowerCase();
     return (renderer.includes("swiftshader") ||
@@ -54,7 +54,7 @@ async function probeHardwareWebGlInfo(ppt, options) {
     let probeBrowser;
     try {
         const launchOptions = {
-            ...sigintLaunchOptions(),
+            ...ownedLaunchOptions(),
             headless: true,
             args: withHyperframesBrowserMarker(options.args),
             defaultViewport: { width: 64, height: 64 },
@@ -659,7 +659,7 @@ async function launchBrowser(fingerprint) {
     let captureMode = fingerprint.requestedCaptureMode;
     let browser;
     const launch = (args) => ppt.launch({
-        ...sigintLaunchOptions(),
+        ...ownedLaunchOptions(),
         headless: true,
         args: withHyperframesBrowserMarker(args),
         defaultViewport: null,
@@ -706,6 +706,8 @@ async function launchBrowser(fingerprint) {
 }
 function forceCloseBrowserProcess(browser) {
     const proc = browser.process?.();
+    for (const stream of proc?.stdio ?? [])
+        stream?.on("error", () => { });
     if (proc && !proc.killed) {
         try {
             proc.kill("SIGKILL");

package/dist/services/chunkEncoder.d.ts

@@ -87,6 +87,14 @@ export declare function appendLockedGopArgs(args: string[], gopSize: number): vo
  * open-GOP references. `repeat-headers=1` keeps each boundary self-contained.
  */
 export declare function lockedGopCodecParams(codec: "h264" | "h265", gopSize: number): string;
+/** Frames per keyframe interval: the nearest whole frame, never below one. */
+export declare function keyframeIntervalToGopSize(fps: Fps, seconds: number): number;
+/** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */
+export declare function appendRateCapArgs(args: string[], options: {
+    codec?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
+}): void;
 export declare function buildEncoderArgs(options: EncoderOptions, inputArgs: string[], outputPath: string, gpuEncoder?: GpuEncoder): 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

@@ -128,6 +128,38 @@ export function lockedGopCodecParams(codec, gopSize) {
     const shared = "scenecut=0:open-gop=0:repeat-headers=1";
     return codec === "h264" ? shared : `keyint=${gopSize}:min-keyint=${gopSize}:${shared}`;
 }
+/** Frames per keyframe interval: the nearest whole frame, never below one. */
+export function keyframeIntervalToGopSize(fps, seconds) {
+    return Math.max(1, Math.round(fpsToNumber(fps) * seconds));
+}
+const BITRATE_PATTERN = /^(\d+(?:\.\d+)?)([kKmMgG]?)$/;
+function bitrateToBitsPerSecond(value) {
+    const match = BITRATE_PATTERN.exec(value);
+    if (!match)
+        throw new Error(`[chunkEncoder] invalid bitrate ${JSON.stringify(value)}`);
+    const unit = match[2].toLowerCase();
+    const scale = { g: 1_000_000_000, m: 1_000_000, k: 1_000 }[unit] ?? 1;
+    return Number(match[1]) * scale;
+}
+/** `-maxrate` / `-bufsize` for the VBV cap, written once for both arg builders. Buffer defaults to 2x. */
+export function appendRateCapArgs(args, options) {
+    const { maxBitrate, bufferSize } = options;
+    if (maxBitrate === undefined) {
+        if (bufferSize !== undefined)
+            throw new Error("[chunkEncoder] bufferSize requires maxBitrate");
+        return;
+    }
+    const codec = options.codec ?? "h264";
+    if (codec !== "h264" && codec !== "h265") {
+        throw new Error(`[chunkEncoder] maxBitrate is not supported for codec ${codec}`);
+    }
+    const cap = bitrateToBitsPerSecond(maxBitrate);
+    const buffer = bufferSize !== undefined ? bitrateToBitsPerSecond(bufferSize) : cap * 2;
+    if (cap <= 0 || buffer <= 0) {
+        throw new Error("[chunkEncoder] maxBitrate and bufferSize must be positive");
+    }
+    args.push("-maxrate", String(Math.round(cap)), "-bufsize", String(Math.round(buffer)));
+}
 export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = null) {
     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
@@ -142,6 +174,7 @@ export function buildEncoderArgs(options, inputArgs, outputPath, gpuEncoder = nu
     // Without -xerror, ffmpeg ends the video at the first frame file it cannot read and still exits 0.
     const args = ["-xerror", ...inputArgs, "-r", fpsToFfmpegArg(fps)];
     const shouldUseGpu = useGpu && gpuEncoder !== null;
+    appendRateCapArgs(args, options);
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
             const encoderName = getGpuEncoderName(gpuEncoder, codec);

package/dist/services/chunkEncoder.types.d.ts

@@ -9,6 +9,8 @@ export interface EncoderOptions {
     preset?: string;
     quality?: number;
     bitrate?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
     pixelFormat?: string;
     /** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
     vp9CpuUsed?: number;

package/dist/services/drawElementCaptureError.d.ts

@@ -3,5 +3,6 @@ export declare class DrawElementCaptureError extends Error {
     readonly frameIndex: number;
     constructor(frameIndex: number, reason: string, cause?: unknown);
 }
+export declare function asDrawElementCaptureFailure(frameIndex: number, encodeResult: Promise<Buffer>): Promise<Buffer>;
 /** Structural matching survives engine/producer copies and worker error wrappers. */
 export declare function isDrawElementCaptureError(error: unknown): boolean;

package/dist/services/drawElementCaptureError.js

@@ -9,6 +9,19 @@ export class DrawElementCaptureError extends Error {
         this.frameIndex = frameIndex;
     }
 }
+function markRejectionHandled(promise) {
+    promise.catch(() => { });
+}
+export function asDrawElementCaptureFailure(frameIndex, encodeResult) {
+    const wrapped = encodeResult.catch((cause) => {
+        if (isDrawElementCaptureError(cause))
+            throw cause;
+        const reason = cause instanceof Error ? cause.message : String(cause);
+        throw new DrawElementCaptureError(frameIndex, reason, cause);
+    });
+    markRejectionHandled(wrapped);
+    return wrapped;
+}
 /** Structural matching survives engine/producer copies and worker error wrappers. */
 export function isDrawElementCaptureError(error) {
     let current = error;

package/dist/services/frameCapture.d.ts

@@ -6,7 +6,7 @@
  * the page to expose window.__hf, then captures frames deterministically
  * via Chrome's BeginFrame API or Page.captureScreenshot fallback.
  */
-import { type Browser, type Page, type Protocol } from "puppeteer-core";
+import { type Browser, type CDPSession, type Page, type Protocol } from "puppeteer-core";
 import { type RawAuthoredTiming } from "@hyperframes/core";
 import { type MotionBlurPlan } from "./motionBlur.js";
 import { type BrowserLease, type CaptureMode } from "./browserManager.js";
@@ -429,6 +429,7 @@ export interface IsolatedComposition {
     compositionId: string;
     elementId: string | null;
 }
+export declare function authorScriptsMayRegisterTimelines(runtimeAttr: string, authoredBegin: string, authoredEnd: string): Promise<boolean>;
 export interface SubTimelinePollOptions {
     intervalMs?: number;
     getScriptLoadFailures?: () => readonly string[];
@@ -467,6 +468,8 @@ export declare function classifyConsoleScriptError(type: string, text: string):
 export declare function classifyConsoleScriptFailure(type: string, text: string): string | null;
 /** `runtime-error:<first line>` when a script served with the composition threw; null if not attributable to one. */
 export declare function classifyPageError(details: Protocol.Runtime.ExceptionDetails, projectScripts: ReadonlySet<string>): string | null;
+/** ` [thrown at: <url>:<line>:<col>, <lookup>]` for a throw's authored frame, so the author can find the element. */
+export declare function describeThrowSite(client: CDPSession, details: Protocol.Runtime.ExceptionDetails, projectScripts: ReadonlySet<string>): Promise<string>;
 export declare function initializeSession(session: CaptureSession): Promise<void>;
 /**
  * Internal helper: seek timeline and inject video frames.

package/dist/services/frameCapture.js

@@ -9,9 +9,9 @@
  */
 import { existsSync, mkdirSync, writeFileSync } from "fs";
 import { join } from "path";
-import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
+import { COMPOSITION_SOURCE_URL, MEDIA_RENDER_ID_ATTR, quantizeSeekTime, quantizeTimeToFrame, fpsToNumber, resolveAuthoredTimingWindow, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END, RUNTIME_BOOTSTRAP_ATTR, SCENE_CALLBACK_ERROR_PREFIX, } from "@hyperframes/core";
 import { holdRenderFrameVideos } from "./renderFrameVideoHold.js";
-import { DrawElementCaptureError } from "./drawElementCaptureError.js";
+import { asDrawElementCaptureFailure, DrawElementCaptureError } from "./drawElementCaptureError.js";
 import { encodePng } from "../utils/alphaBlit.js";
 import { DEFAULT_SAMPLES_PER_FRAME, MotionBlurAccumulator, SPATIAL_TWEEN_PROPERTIES, adaptiveSampleCount, motionBlurProbeTimes, motionBlurSampleTimes, motionBlurWindowIsStatic, probeDiffMagnitude, resolveMotionBlurPlan, } from "./motionBlur.js";
 import { describePageMotionBlur, describePageMotionBlurAtEnd, installPageMotionBlur, } from "./pageMotionBlur.js";
@@ -1361,6 +1361,50 @@ export async function waitForSubCompositionTimelines(session, page, timeoutMs, o
         memo.unregisteredIds = session.pendingTimelineIds ?? [];
     }
 }
+// Runs in the page. False once every inline, template and same-origin script is read and none
+// mentions __timelines or imports code; an unreadable or module script, or a page still loading, answers true.
+export async function authorScriptsMayRegisterTimelines(runtimeAttr, authoredBegin, authoredEnd) {
+    if (document.readyState !== "complete")
+        return true;
+    const memo = globalThis;
+    memo.__hfAuthorScan ??= await (async () => {
+        const scripts = [
+            ...Array.from(document.querySelectorAll("script")),
+            ...Array.from(document.querySelectorAll("template")).flatMap((t) => Array.from(t.content.querySelectorAll("script"))),
+        ].filter((script) => !script.hasAttribute(runtimeAttr));
+        // Code that imports another file may register through it, which is not read here.
+        const mayRegister = (code) => code.includes("__timelines") || /\bimport\s*\(|^\s*import\s*[\w{*"']/m.test(code);
+        for (const script of scripts) {
+            if (script.type === "module")
+                return true;
+            if (!script.src) {
+                const text = script.textContent ?? "";
+                const authored = text.includes(authoredBegin)
+                    ? text
+                        .split(authoredBegin)
+                        .slice(1)
+                        .map((region) => region.split(authoredEnd)[0])
+                        .join("\n")
+                    : text;
+                if (mayRegister(authored))
+                    return true;
+                continue;
+            }
+            const url = new URL(script.src, location.href);
+            if (url.origin !== location.origin)
+                return true;
+            try {
+                if (mayRegister(await (await fetch(url)).text()))
+                    return true;
+            }
+            catch {
+                return true;
+            }
+        }
+        return false;
+    })();
+    return memo.__hfAuthorScan;
+}
 export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs = 150, getScriptLoadFailures, scriptFailureGraceMs = 2_000, getPageErrors, scriptErrorGraceMs = 5_000, onPending, shouldStop, knownUnregisteredIds = [], } = {}) {
     // Hosts may opt out of the timeline wait with `data-no-timeline` —
     // compositions driven purely by CSS animations / rAF (the render-compat
@@ -1386,15 +1430,19 @@ export async function pollSubCompositionTimelines(page, timeoutMs, { intervalMs
     // A page error is given its grace from when it first appeared, not from when the poll began.
     let errorSeenAt;
     for (;;) {
-        ready = Boolean(await page.evaluate(expression));
+        const failures = getScriptLoadFailures?.() ?? [];
+        const errors = getPageErrors?.() ?? [];
+        const failed = failures.length > 0 ? failures : errors;
+        // A failed script keeps the wait, so the failure is still named; only a quiet page is ready early.
+        ready =
+            Boolean(await page.evaluate(expression)) ||
+                (failed.length === 0 &&
+                    !(await page.evaluate(authorScriptsMayRegisterTimelines, RUNTIME_BOOTSTRAP_ATTR, AUTHORED_SOURCE_BEGIN, AUTHORED_SOURCE_END)));
         if (ready || shouldStop?.())
             break;
         const now = Date.now();
         if (now >= deadline)
             break;
-        const failures = getScriptLoadFailures?.() ?? [];
-        const errors = getPageErrors?.() ?? [];
-        const failed = failures.length > 0 ? failures : errors;
         const graceMs = failures.length > 0 ? scriptFailureGraceMs : scriptErrorGraceMs;
         if (failed.length > 0)
             errorSeenAt ??= now;
@@ -1839,10 +1887,41 @@ export function classifyPageError(details, projectScripts) {
     if (frames.length === 0 && details.text.startsWith("Uncaught (in promise)"))
         return null;
     const urls = frames.length > 0 ? frames : [details.url];
-    // The render compiler names the composition's inline code.
-    // Inline handlers report the document, which a widget can move.
-    const owned = (url) => url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
-    return urls.some(owned) ? `runtime-error:${firstLine}` : null;
+    return urls.some((url) => isOwnedScriptUrl(url, projectScripts))
+        ? `runtime-error:${firstLine}`
+        : null;
+}
+// The render compiler names the composition's inline code.
+// Inline handlers report the document, which a widget can move.
+function isOwnedScriptUrl(url, projectScripts) {
+    return url !== undefined && (projectScripts.has(url) || url.startsWith(COMPOSITION_SOURCE_URL));
+}
+const LOOKUP_CALL = /\b(?:getElementById|querySelectorAll|querySelector|getElementsByClassName|getElementsByTagName)\(\s*(["'`])((?:(?!\1).)*)\1/g;
+/** ` [thrown at: <url>:<line>:<col>, <lookup>]` for a throw's authored frame, so the author can find the element. */
+export async function describeThrowSite(client, details, projectScripts) {
+    const frame = (details.stackTrace?.callFrames ?? []).find((f) => isOwnedScriptUrl(f.url, projectScripts));
+    if (!frame)
+        return "";
+    let where = `${frame.url}:${frame.lineNumber + 1}:${frame.columnNumber + 1}`;
+    try {
+        // Source is only fetchable with the debugger on; enabling after the fact keeps script ids.
+        await client.send("Debugger.enable");
+        const { scriptSource } = await client.send("Debugger.getScriptSource", {
+            scriptId: frame.scriptId,
+        });
+        const line = scriptSource.split("\n")[frame.lineNumber] ?? "";
+        const lookups = [...line.matchAll(LOOKUP_CALL)];
+        // Only a lone lookup is certain to be the one that returned null; with several the position alone is given.
+        if (lookups.length === 1)
+            where += `, ${lookups[0]?.[0]})`;
+    }
+    catch {
+        // Source unavailable: line:col alone still locates the throw.
+    }
+    finally {
+        await client.send("Debugger.disable").catch(() => undefined);
+    }
+    return ` [thrown at: ${where}]`;
 }
 export async function initializeSession(session) {
     const { page, serverUrl } = session;
@@ -1913,7 +1992,20 @@ export async function initializeSession(session) {
     // Unlike the pageerror Error, this keeps the script URL of syntax errors and thrown non-errors.
     const runtimeClient = await getCdpSession(page);
     runtimeClient.on("Runtime.exceptionThrown", ({ exceptionDetails }) => {
-        recordPageError(session, classifyPageError(exceptionDetails, projectScripts));
+        const error = classifyPageError(exceptionDetails, projectScripts);
+        recordPageError(session, error);
+        if (!error)
+            return;
+        // Recorded first so fail-fast sees it; the throw site is appended once the source is fetched.
+        void describeThrowSite(runtimeClient, exceptionDetails, projectScripts).then((site) => {
+            const i = session.pageErrors.indexOf(error);
+            if (!site || i < 0)
+                return;
+            if (session.pageErrors.includes(`${error}${site}`))
+                session.pageErrors.splice(i, 1);
+            else
+                session.pageErrors[i] = `${error}${site}`;
+        });
     });
     await runtimeClient.send("Runtime.enable");
     const pageNavigationTimeout = session.config?.pageNavigationTimeout ?? DEFAULT_CONFIG.pageNavigationTimeout;
@@ -3556,7 +3648,8 @@ export async function captureFrameToBufferPipelined(session, frameIndex, time) {
         // syncToPaintEvent = true); see initDrawElementOrTransparentBackground. The
         // BeginFrame branch present in the synchronous captureFrameCore is therefore
         // unreachable here and intentionally omitted.
-        const { encodeResult } = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+        const produced = await produceDrawElementFrame(page, options.width, options.height, options.quality ?? 80, true);
+        const encodeResult = asDrawElementCaptureFailure(frameIndex, produced.encodeResult);
         const captureTimeMs = Date.now() - startTime;
         session.capturePerf.frames += 1;
         session.capturePerf.seekMs += seekMs;
@@ -3671,7 +3764,10 @@ export async function captureFramesBatchPipelined(session, frameIndices, times)
         const encodeResult = encodeResults[i];
         if (frameIndex === undefined || !encodeResult)
             break;
-        results.push({ frameIndex, encodeResult });
+        results.push({
+            frameIndex,
+            encodeResult: asDrawElementCaptureFailure(frameIndex, encodeResult),
+        });
     }
     if (failedAt !== null) {
         // `error` is a plain string here (produceDrawElementFrameBatch returns it

package/dist/services/hdrCapture.js

@@ -19,7 +19,7 @@
  * Performance: ~6 fps at 1080x1920 via base64 transfer.
  */
 import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
-import { resolveFullChromePath, sigintLaunchOptions } from "./browserManager.js";
+import { resolveFullChromePath, ownedLaunchOptions } from "./browserManager.js";
 // ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
 const PQ_M1 = 0.1593017578125;
 const PQ_M2 = 78.84375;
@@ -181,7 +181,7 @@ export async function launchHdrBrowser(width, height) {
         throw new Error("[HDR] No Chrome binary found. Install: npx @puppeteer/browsers install chrome@stable");
     }
     const browser = await ppt.launch({
-        ...sigintLaunchOptions(),
+        ...ownedLaunchOptions(),
         headless: false,
         executablePath: chromePath,
         args: withHyperframesBrowserMarker(buildHdrChromeArgs(width, height)),

package/dist/services/parallelCoordinator.d.ts

@@ -74,6 +74,7 @@ export interface ParallelWorkerPhaseDiagnostic {
     browserVersion: string;
     canvasDrawElement: boolean | "unknown";
     gpuBackend: string;
+    readStep?: () => string | undefined;
 }
 export interface WorkerSizingConfig extends Partial<Pick<EngineConfig, "concurrency" | "coresPerWorker" | "minParallelFrames" | "largeRenderThreshold">> {
     /**
@@ -237,6 +238,7 @@ export interface ParallelCaptureHooks {
      * frame (the ordered writer) with the original error, not a stall.
      */
     onWorkerFailure?: (failure: CaptureFailure) => void;
+    onWorkerOperation?: (diagnostic: ParallelWorkerPhaseDiagnostic) => void;
 }
 /**
  * The pool's single failure gate. Both halves of the contract the streaming

package/dist/services/parallelCoordinator.js

@@ -320,20 +320,22 @@ function resolveParallelWorkerTimeoutMs(enabled) {
     return Number.isFinite(parsed) && parsed > 0 ? parsed : 30_000;
 }
 // fallow-ignore-next-line complexity
-async function captureFrameRange(session, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase) {
+async function captureFrameRange(session, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase, onWorkerOperation) {
     let framesCaptured = 0;
     const outputOffset = task.outputFrameOffset ?? 0;
     const stride = task.frameStride ?? 1;
     const runCaptureOperation = (phase, frameIndex, operation) => {
-        const diagnostic = diagnosticFor(phase, frameIndex);
+        const diagnostic = { ...diagnosticFor(phase, frameIndex), readStep: () => session.captureStep };
         if (framesCaptured === 0)
             onWorkerPhase?.(diagnostic);
+        onWorkerOperation?.(diagnostic);
         return withParallelWorkerDeadline(operation(), diagnostic, phaseTimeoutMs, signal);
     };
     const awaitEncode = (frameIndex, encodeResult) => {
         const diagnostic = diagnosticFor("frame_encode", frameIndex);
         if (framesCaptured === 0)
             onWorkerPhase?.(diagnostic);
+        onWorkerOperation?.(diagnostic);
         return withParallelWorkerDeadline(encodeResult, diagnostic, phaseTimeoutMs, signal);
     };
     // Depth-2 pipelined drawElement produce (HF_DE_PARALLEL_STREAM spike): frame
@@ -550,7 +552,7 @@ export async function verifyDiskDrawElementSamples(session, task, streaming) {
 // flagged only because the disk self-verify call shifted its line range into
 // the changed-code audit. Not restructured by this PR.
 // fallow-ignore-next-line complexity
-async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase) {
+async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCaptureHook, signal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, onWorkerOperation) {
     const startTime = Date.now();
     let framesCaptured = 0;
     if (!existsSync(task.outputDir))
@@ -605,7 +607,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         canvasDrawElement = activeSession.captureMode === "drawelement";
         gpuBackend = activeSession.gpuRenderer ?? "unknown";
         logParDebug(() => `[par:w${task.workerId}] init done (mode=${session?.captureMode} workerEncode=${session?.workerEncodeEnabled === true})`);
-        framesCaptured = await captureFrameRange(activeSession, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase);
+        framesCaptured = await captureFrameRange(activeSession, task, captureOptions, signal, onFrameCaptured, onFrameBuffer, phaseTimeoutMs, diagnosticFor, onWorkerPhase, onWorkerOperation);
         await verifyDiskDrawElementSamples(activeSession, task, Boolean(onFrameBuffer));
         perf = getCapturePerfSummary(activeSession);
         return {
@@ -775,7 +777,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
         hooks,
     });
     const onFailure = failureHandler.onFailure;
-    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase)));
+    const results = await Promise.all(tasks.map((task) => executeWorkerTask(task, serverUrl, workerCaptureOptions, createBeforeCaptureHook, workerSignal, onFrameCaptured, onFrameBuffer, config, parallel, onFailure, onWorkerPhase, hooks?.onWorkerOperation)));
     flagSilentWorkerExits(results);
     const errors = results.filter((r) => r.failure || r.error);
     if (errors.length > 0) {

package/dist/services/streamingEncoder.d.ts

@@ -38,6 +38,8 @@ export interface StreamingEncoderOptions {
     preset?: string;
     quality?: number;
     bitrate?: string;
+    maxBitrate?: string;
+    bufferSize?: string;
     pixelFormat?: string;
     /** libvpx-vp9 -cpu-used value. Defaults to the engine VP9 setting. */
     vp9CpuUsed?: number;

package/dist/services/streamingEncoder.js

@@ -30,7 +30,7 @@ import { fpsToFfmpegArg, fpsToNumber } from "@hyperframes/core";
 import { appendVp9CpuUsedArg } from "./vp9Options.js";
 import { appendSoftwareEncoderThreadsArg } from "./softwareEncoderThreads.js";
 import { appendRenderProvenanceArgs } from "../utils/renderProvenance.js";
-import { appendLockedGopArgs, lockedGopCodecParams, resolveLockedGopSize } from "./chunkEncoder.js";
+import { appendLockedGopArgs, appendRateCapArgs, lockedGopCodecParams, resolveLockedGopSize, } from "./chunkEncoder.js";
 export function createFrameReorderBuffer(startFrame, endFrame) {
     let cursor = startFrame;
     let aborted = null;
@@ -121,6 +121,7 @@ export function buildStreamingArgs(options, outputPath, gpuEncoder = null) {
     }
     args.push("-r", fpsToFfmpegArg(fps));
     const shouldUseGpu = useGpu && gpuEncoder !== null;
+    appendRateCapArgs(args, options);
     if (codec === "h264" || codec === "h265") {
         if (shouldUseGpu) {
             const encoderName = getGpuEncoderName(gpuEncoder, codec);

package/dist/services/videoFrameExtractor.d.ts

@@ -258,6 +258,7 @@ export interface ImageElement {
     end: number;
 }
 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>;
 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). */

package/dist/services/videoFrameExtractor.js

@@ -14,7 +14,7 @@ import { parseHTML } from "linkedom";
 import { isPathInside } from "@hyperframes/parsers/asset-paths";
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
 import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
-import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
+import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, mediaElementTime, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
 import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
@@ -477,6 +477,12 @@ function chromeGuessForUntaggedMatrix(metadata) {
     const hd = metadata.height >= 720 && !CHROME_BT601_UNTAGGED_CODECS.has(metadata.videoCodec);
     return [`setparams=colorspace=${hd ? "bt709" : "smpte170m"}`];
 }
+export function sdrCanvasColourFilters(metadata, toneMappedToSdr = false) {
+    if (!isHdrColorSpaceUtil(metadata.colorSpace)) {
+        return [...chromeGuessForUntaggedMatrix(metadata), SDR_CANVAS_PASSTHROUGH_FILTER];
+    }
+    return toneMappedToSdr ? [SDR_CANVAS_PASSTHROUGH_FILTER] : [];
+}
 /**
  * Longest stretch of output one ffmpeg process extracts; longer ranges split into segments
  * that run side by side. Segments sample the same absolute times as a single pass, so their
@@ -617,9 +623,6 @@ outputDirOverride) {
         throw new Error("frameRanges extraction needs a constant-frame-rate source");
     }
     const args = urlInputArgs(videoPath);
-    if (decodeWithVideoToolbox) {
-        args.push("-hwaccel", "videotoolbox");
-    }
     // Always force the alpha-aware decoder on codecs that can carry alpha. The
     // alternative — gating on `metadata.hasAlpha` — relies on tag detection that
     // has at least three known failure modes: case-sensitivity across ffmpeg
@@ -678,7 +681,7 @@ outputDirOverride) {
         vfFilters.push(hdrToSdrToneMapFilter(metadata.colorSpace ?? {}, frameColour));
     }
     if (toneMappedToSdr || (!isHdr && !options.sdrToHdrTransfer)) {
-        vfFilters.push(...(isHdr ? [] : chromeGuessForUntaggedMatrix(metadata)), SDR_CANVAS_PASSTHROUGH_FILTER);
+        vfFilters.push(...sdrCanvasColourFilters(metadata, toneMappedToSdr));
         if (format === "jpg") {
             if (options.shownBox)
                 vfFilters.push(halveToCoverScaleFilter(options.shownBox));
@@ -702,9 +705,9 @@ outputDirOverride) {
     // emits that last slot: the fps filter ends a `-t` window at the nearest slot. A
     // decimal rate counts zero frames here and keeps the `-t` window.
     const boundVfrFrameCount = metadata.isVFR && totalFrames > 0;
-    const processResult = sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
-        ? await runSegmentedExtraction({
-            decodeArgs,
+    const extract = (hwaccel) => sampleAtOutputFps && (options.frameRanges || boundVfrFrameCount || totalFrames > segmentFrames)
+        ? runSegmentedExtraction({
+            decodeArgs: [...hwaccel, ...decodeArgs],
             filterAndEncodeArgs: (seek) => [...filterArgsFor(seek), ...encodeArgs],
             videoPath,
             startTime,
@@ -713,7 +716,14 @@ outputDirOverride) {
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
         })
-        : await inExtractionSlot(() => runFfmpeg([...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
+        : inExtractionSlot(() => runFfmpeg([...hwaccel, ...args, ...filterArgsFor(startTime), ...encodeArgs], runOptions), signal);
+    let processResult = await extract(decodeWithVideoToolbox ? ["-hwaccel", "videotoolbox"] : []);
+    const ffmpegExitedFailing = processResult.terminationReason === "exit" &&
+        !processResult.success &&
+        !processResult.failureReason;
+    const videoToolboxWasOptional = decodeWithVideoToolbox && !keepsHdrForChrome;
+    if (ffmpegExitedFailing && videoToolboxWasOptional)
+        processResult = await extract([]);
     if (processResult.failureReason === "external_interruption") {
         throw new VideoSourceExtractionError("external_interruption", true, "Video frame extraction interrupted by host lifecycle", `FFmpeg exited with code ${processResult.exitCode}: ${processResult.stderr.slice(-500)}`);
     }
@@ -1832,9 +1842,9 @@ function getFrameIndexAtTime(extracted, globalTime, videoStart, loop = false, me
         if (cycle > 0 && sourceTime >= cycle)
             sourceTime %= cycle;
     }
-    // Add epsilon before flooring to avoid IEEE 754 boundary errors where
-    // e.g. 0.28 * 25 === 6.999999999999999 instead of 7.
-    const frameIndex = Math.floor(sourceTime * extracted.fps + 1e-9);
+    // The frame the preview's <video> shows at this source time, so render and preview pick the same one.
+    const shownTime = mediaElementTime(mediaStart + sourceTime) - mediaStart;
+    const frameIndex = Math.floor(shownTime * extracted.fps);
     if (frameIndex < 0 || extracted.totalFrames <= 0)
         return null;
     if (isVideoHiddenBeforeStreamStart(extracted.metadata.videoStreamLeadSeconds, mediaStart + sourceTime)) {

package/dist/utils/ffprobe.d.ts

@@ -1,3 +1,8 @@
+/** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
+export declare function runFfprobe(filePath: string, argsWithoutInput: string[], signal?: AbortSignal, stdoutOptions?: {
+    retainTail?: boolean;
+    maxChars?: number;
+}): Promise<string>;
 export interface MediaProbeCacheEntry<T = FFProbeOutput> {
     identity: string | null;
     promise: Promise<T>;

package/dist/utils/ffprobe.js

@@ -49,7 +49,7 @@ function sanitizeFfprobeDiagnostic(stderr, filePath) {
     return `…${redacted.slice(-(FFPROBE_ERROR_MAX_CHARS - 1))}`;
 }
 /** Spawn ffprobe with given args, return stdout. Throws on non-zero exit or missing binary. */
-async function runFfprobe(filePath, argsWithoutInput, signal, stdoutOptions) {
+export async function runFfprobe(filePath, argsWithoutInput, signal, stdoutOptions) {
     // `--` stops option parsing so a path like "-intro.mp4" is a filename, but
     // it does NOT cover a path of exactly "-": ffprobe rewrites that to `fd:`
     // AFTER option parsing and then reads stdin. Since stdin here is a pipe the

package/dist/utils/removeScratch.d.ts

@@ -0,0 +1,5 @@
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export declare function removeScratch(path: string): void;
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export declare function collectScratchLeftovers<T>(run: () => Promise<T>, report: (left: string[]) => void): Promise<T>;

package/dist/utils/removeScratch.js

@@ -0,0 +1,23 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+import { rmSync } from "node:fs";
+const collecting = new AsyncLocalStorage();
+/** Removes a scratch folder or file the mix is already done with. A refusal (Windows temp folders that deny
+ * delete) leaves it for the render's own cleanup and never fails the audio it served. */
+export function removeScratch(path) {
+    try {
+        rmSync(path, { recursive: true, force: true });
+    }
+    catch {
+        collecting.getStore()?.push(path);
+    }
+}
+/** Runs `run`; whatever removeScratch left behind inside it (this run's only) goes to `report` once it ends. */
+export async function collectScratchLeftovers(run, report) {
+    const left = [];
+    try {
+        return await collecting.run(left, run);
+    }
+    finally {
+        report(left);
+    }
+}

package/dist/utils/renameWithRetry.d.ts

@@ -1,12 +1,16 @@
 interface Options {
     platform?: NodeJS.Platform;
+    /** Copy the bytes when Windows keeps refusing (a TEMP that denies delete). Not atomic: scratch files only. */
+    copyFallback?: boolean;
 }
 /** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
 export declare function renameWithRetry(from: string, to: string, options?: Options & {
     rename?: (from: string, to: string) => void;
+    copy?: (from: string, to: string) => void;
 }): void;
 /** Async twin of {@link renameWithRetry}. */
 export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
     rename?: (from: string, to: string) => Promise<void>;
+    copy?: (from: string, to: string) => Promise<void>;
 }): Promise<void>;
 export {};

package/dist/utils/renameWithRetry.js

@@ -1,5 +1,6 @@
-import { renameSync } from "node:fs";
-import { rename } from "node:fs/promises";
+import { copyFileSync, renameSync } from "node:fs";
+import { copyFile, rename } from "node:fs/promises";
+import { removeScratch } from "./removeScratch.js";
 // Windows reports EPERM/EACCES/EBUSY while antivirus or a just-exited process still holds the
 // file; the hold clears within milliseconds. Total wait before giving up: about 1.3 s.
 const RETRYABLE = new Set(["EPERM", "EACCES", "EBUSY"]);
@@ -9,12 +10,21 @@ function isRetryable(error, platform) {
         return false;
     return RETRYABLE.has(error?.code ?? "");
 }
+/** What a refused rename does next: wait and try again, fall back to a copy, or give up with the error. */
+function nextStep(error, attempt, options, platform) {
+    if (!isRetryable(error, platform))
+        return "throw";
+    if (attempt < BACKOFF_MS.length)
+        return "wait";
+    return options.copyFallback ? "copy" : "throw";
+}
 function sleepSync(ms) {
     Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
 }
 /** `renameSync` that rides out Windows' transient file locks; other platforms and errors throw at once. */
 export function renameWithRetry(from, to, options = {}) {
     const doRename = options.rename ?? renameSync;
+    const doCopy = options.copy ?? copyFileSync;
     const platform = options.platform ?? process.platform;
     for (let attempt = 0;; attempt++) {
         try {
@@ -22,15 +32,28 @@ export function renameWithRetry(from, to, options = {}) {
             return;
         }
         catch (error) {
-            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
+                throw error;
+            if (step === "wait") {
+                sleepSync(BACKOFF_MS[attempt]);
+                continue;
+            }
+            try {
+                doCopy(from, to);
+            }
+            catch {
                 throw error;
-            sleepSync(BACKOFF_MS[attempt]);
+            }
+            removeScratch(from);
+            return;
         }
     }
 }
 /** Async twin of {@link renameWithRetry}. */
 export async function renameWithRetryAsync(from, to, options = {}) {
     const doRename = options.rename ?? rename;
+    const doCopy = options.copy ?? copyFile;
     const platform = options.platform ?? process.platform;
     for (let attempt = 0;; attempt++) {
         try {
@@ -38,9 +61,21 @@ export async function renameWithRetryAsync(from, to, options = {}) {
             return;
         }
         catch (error) {
-            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+            const step = nextStep(error, attempt, options, platform);
+            if (step === "throw")
                 throw error;
-            await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+            if (step === "wait") {
+                await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+                continue;
+            }
+            try {
+                await doCopy(from, to);
+            }
+            catch {
+                throw error;
+            }
+            removeScratch(from);
+            return;
         }
     }
 }

package/package.json

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