@hyperframes/engine 0.8.192 → 0.8.194

package/dist/index.d.ts

@@ -50,7 +50,7 @@ export { parseVideoElements, parseImageElements, extractVideoFramesRange, extrac
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
-export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
+export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, videoAudioId, } from "./services/audioMixer.js";
 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";
@@ -64,7 +64,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, 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, 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";
@@ -72,6 +72,7 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 export { ManagedChildProcess, type ManagedChildProcessOptions, type ManagedChildProcessOutcome, type ManagedProcessTerminationReason, } 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 { 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

@@ -54,7 +54,7 @@ export { parseVideoElements, parseImageElements, extractVideoFramesRange, extrac
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
-export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, } from "./services/audioMixer.js";
+export { MIXED_AUDIO_FILENAME, parseAudioElements, parseMasterFxChain, processCompositionAudio, videoAudioId, } from "./services/audioMixer.js";
 export { audioFailureDiagnostics } from "./services/audioFailureDiagnostic.js";
 export { cloneCaptureWarning, cloneCaptureWarnings } from "./services/captureWarning.js";
 // ── Parallel rendering ─────────────────────────────────────────────────────────
@@ -68,7 +68,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, probeMediaProfile, analyzeKeyframeIntervals, } from "./utils/ffprobe.js";
+export { extractMediaMetadata, extractVideoMetadata, extractFinalVideoFrameTimestamp, extractAudioMetadata, declareContentAddressedUrl, declareProbeFactsUrl, PROBE_FACTS_VERSION, buildProbeFactsText, probeMediaProfile, 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";
@@ -76,6 +76,7 @@ export { aacSegmentCount, encodeAac } from "./services/aacEncode.js";
 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";
 // 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

@@ -2,8 +2,10 @@
  * AAC for the mixed 48 kHz audio. One encoder is single-threaded (about 60x real time),
  * 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 { dirname, join } from "node:path";
+import { getFfmpegBinary } from "../utils/ffmpegBinaries.js";
 import { runFfmpeg } from "../utils/runFfmpeg.js";
 const SAMPLE_RATE = 48_000;
 const FRAME_SAMPLES = 1024;
@@ -48,8 +50,33 @@ function planSegments(totalDuration, count) {
         return { trim, keepFrom: cut - firstFrame, keepTo: next - firstFrame };
     });
 }
+const settsDurationSupport = new Map();
+/** FFmpeg before 5.0 (Ubuntu 22.04 ships 4.4) has no `duration` option on the setts filter. */
+function supportsSettsDuration(binary = getFfmpegBinary()) {
+    let supported = settsDurationSupport.get(binary);
+    if (!supported) {
+        supported = new Promise((resolve) => {
+            execFile(binary, ["-hide_banner", "-h", "bsf=setts"], (error, stdout) => {
+                // A binary that cannot even print help fails the encode with its own error, not this one.
+                resolve(error !== null || stdout.includes("duration"));
+            });
+        });
+        settsDurationSupport.set(binary, supported);
+    }
+    return supported;
+}
+function encodeInOnePass(input, outputPath, { signal, timeout, filter }) {
+    const filters = [filter, `aresample=${SAMPLE_RATE}`].filter(Boolean).join(",");
+    return runFfmpeg(["-i", input, "-af", filters, ...AAC_ARGS, "-y", outputPath], {
+        signal,
+        timeout,
+    });
+}
 /** `input`, after `filter`, is audio of exactly `totalDuration`. */
 export async function encodeAac(input, outputPath, totalDuration, { signal, timeout, filter, segments: count = aacSegmentCount(totalDuration), }) {
+    if (!(await supportsSettsDuration())) {
+        return encodeInOnePass(input, outputPath, { signal, timeout, filter });
+    }
     const dir = mkdtempSync(join(dirname(outputPath), ".aac-segments-"));
     try {
         const segments = planSegments(totalDuration, count).map((segment, k) => ({

package/dist/services/audioMixer.d.ts

@@ -30,6 +30,7 @@ export declare function volumeLaneKeyframes(automation: {
  * itself has no parsed element to carry it.
  */
 export declare function parseMasterFxChain(html: string): string | undefined;
+export declare function videoAudioId(videoId: string): string;
 export declare function parseAudioElements(html: string): AudioElement[];
 /** Tracks per ffmpeg graph; a larger mix is summed in stages, so there is no cap on the total. */
 export declare const MAX_MIX_INPUTS = 96;

package/dist/services/audioMixer.js

@@ -1,6 +1,7 @@
 // fallow-ignore-file complexity code-duplication
 import { isSelfOrAncestorHidden, memberGroupKey, isMemberGroupHidden } from "./mediaHidden.js";
-import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, renameSync, rmSync, writeFileSync, } from "fs";
+import { closeSync, existsSync, mkdirSync, mkdtempSync, openSync, rmSync, writeFileSync } from "fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { join, dirname, isAbsolute, relative } from "path";
 import { parseHTML } from "linkedom";
 import { extractAudioMetadata } from "../utils/ffprobe.js";
@@ -419,6 +420,9 @@ export function volumeLaneKeyframes(automation, trackStart, duration, gain, gain
 export function parseMasterFxChain(html) {
     return readMasterFxChain(parseHTML(unwrapTemplate(html)).document);
 }
+export function videoAudioId(videoId) {
+    return `${videoId}-audio`;
+}
 export function parseAudioElements(html) {
     const elements = [];
     const { document } = parseHTML(unwrapTemplate(html));
@@ -503,7 +507,7 @@ export function parseAudioElements(html) {
             continue;
         if (isKnownInactiveTimelineWindow(el, resolveStart(el)))
             continue;
-        elements.push(build(el, `${id}-audio`, src, "video", true));
+        elements.push(build(el, videoAudioId(id), src, "video", true));
     }
     return elements;
 }
@@ -1013,7 +1017,7 @@ async function mixGroupMembers(memberTracks, outputPath, totalDuration, signal,
         const summed = await sumInSlices(memberTracks, scratchDir, totalDuration, signal, config);
         if (!summed.success)
             return summed;
-        renameSync(summed.track.srcPath, outputPath);
+        renameWithRetry(summed.track.srcPath, outputPath);
         return { success: true, degradedAutomation: summed.degradedAutomation };
     }
     finally {
@@ -1059,15 +1063,18 @@ async function mixAudioTracks(tracks, outputPath, totalDuration, signal, config)
  */
 async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, totalDuration, signal, config) {
     const sumPath = join(workDir, "master-sum.wav");
+    const mixStart = Date.now();
     const sum = await mixAudioTracks(tracks, sumPath, totalDuration, signal, config);
     if (!sum.success)
         return { ...sum, outputPath };
+    const masterStart = Date.now();
     const encoderInput = masterChain
         ? (await applyAudioFxChain(sumPath, masterChain, join(workDir, "master-fx.wav"), {
             trackId: "master",
             signal,
         })).path
         : sumPath;
+    const encodeStart = Date.now();
     const encoded = await encodeAac(encoderInput, outputPath, totalDuration, {
         signal,
         timeout: config?.ffmpegProcessTimeout ?? DEFAULT_CONFIG.ffmpegProcessTimeout,
@@ -1084,8 +1091,17 @@ async function mixThroughFloatSum(tracks, masterChain, outputPath, workDir, tota
         };
     }
     if (config?.keepEncoderInputAt)
-        renameSync(encoderInput, config.keepEncoderInputAt);
-    return { ...sum, outputPath, durationMs: sum.durationMs + encoded.durationMs };
+        renameWithRetry(encoderInput, config.keepEncoderInputAt);
+    return {
+        ...sum,
+        outputPath,
+        durationMs: sum.durationMs + encoded.durationMs,
+        phaseMs: {
+            mix: masterStart - mixStart,
+            master: encodeStart - masterStart,
+            encode: Date.now() - encodeStart,
+        },
+    };
 }
 export async function processCompositionAudio(elements, baseDir, workDir, outputPath, totalDuration, signal, config, compiledDir) {
     const startMs = Date.now();
@@ -1367,6 +1383,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
             failures,
         };
     };
+    const prepareMs = Date.now() - startMs;
     if (failures.length > 0)
         return bail();
     // Parsed before any group is mixed, so a malformed master chain fails fast and
@@ -1486,6 +1503,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     }
     if (failures.length > 0)
         return bail();
+    const groupsMs = Date.now() - startMs - prepareMs;
     let mixResult;
     try {
         mixResult =
@@ -1505,6 +1523,7 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
     return {
         ...mixResult,
         durationMs: Date.now() - startMs,
+        phaseMs: { prepare: prepareMs, groups: groupsMs, ...mixResult.phaseMs },
         // Both, when both degraded. `mixResult.error ?? degradedNote` reported only
         // the outer mix and dropped the one that names which GROUPS lost their
         // members' automation — two different losses, and the operator needs to

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

@@ -81,4 +81,5 @@ export interface MixResult {
     tracksProcessed: number;
     error?: string;
     failures?: AudioProcessingFailure[];
+    phaseMs?: Partial<Record<"prepare" | "groups" | "mix" | "master" | "encode", number>>;
 }

package/dist/services/audioVolumeEnvelope.js

@@ -14,7 +14,8 @@
  * `extractAudioSegment`). Anything else is rejected so
  * the caller can fall back to the expression path rather than corrupting audio.
  */
-import { mkdtempSync, readFileSync, renameSync, rmSync, writeFileSync } from "fs";
+import { mkdtempSync, readFileSync, rmSync, writeFileSync } from "fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { dirname, join } from "path";
 import { normaliseEnvelope } from "@hyperframes/core/media-volume-envelope";
 import { riffChunks, wavFormatTag } from "./wavChunks.js";
@@ -131,7 +132,7 @@ export function applyVolumeEnvelopeToWav(wavPath, keyframes, trackStart, baseVol
         stagingDir = mkdtempSync(join(dirname(wavPath), ".hf-volume-"));
         const tempPath = join(stagingDir, "audio.wav");
         writeFileSync(tempPath, buffer, { flag: "wx" });
-        renameSync(tempPath, wavPath);
+        renameWithRetry(tempPath, wavPath);
         return true;
     }
     catch {

package/dist/services/browserManager.js

@@ -5,6 +5,7 @@
  * Manages Puppeteer browser lifecycle: Chrome executable resolution,
  * launch args, pooled browser acquisition/release.
  */
+import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
 import { scanHtmlOpeningTags } from "@hyperframes/parsers/html-attribute-spans";
 import { execSync } from "child_process";
 import { existsSync, readdirSync, statSync } from "fs";
@@ -55,7 +56,7 @@ async function probeHardwareWebGlInfo(ppt, options) {
         const launchOptions = {
             ...sigintLaunchOptions(),
             headless: true,
-            args: options.args,
+            args: withHyperframesBrowserMarker(options.args),
             defaultViewport: { width: 64, height: 64 },
             executablePath: options.executablePath,
             env: options.env,
@@ -637,7 +638,7 @@ async function launchBrowser(fingerprint) {
         browser = await ppt.launch({
             ...sigintLaunchOptions(),
             headless: true,
-            args: [...fingerprint.args],
+            args: withHyperframesBrowserMarker(fingerprint.args),
             defaultViewport: null,
             executablePath: fingerprint.executablePath,
             env,
@@ -662,7 +663,7 @@ async function launchBrowser(fingerprint) {
                 browser = await ppt.launch({
                     ...sigintLaunchOptions(),
                     headless: true,
-                    args: stripBeginFrameFlags([...fingerprint.args]),
+                    args: withHyperframesBrowserMarker(stripBeginFrameFlags([...fingerprint.args])),
                     defaultViewport: null,
                     executablePath: fingerprint.executablePath,
                     env,
@@ -769,6 +770,7 @@ function getLowMemoryFlags() {
 }
 const CANVAS_DRAW_ELEMENT_FEATURE_FLAG = "--enable-features=CanvasDrawElement";
 const WEBGPU_FLAG = "--enable-unsafe-webgpu";
+const DISABLE_DXC_FLAG = "--disable-dawn-features=use_dxc";
 /**
  * Whether this launch renders WebGPU on SwiftShader: the composition needs it, the render opted in, no GPU is in use.
  * SwiftShader draws canvas WebGPU only via Vulkan with GPU compositing on, and not at all under --disable-gpu.
@@ -839,6 +841,9 @@ export function buildChromeArgs(options, config) {
     ];
     if (browserGpuMode !== "software" || options.requiresWebGpu) {
         chromeArgs.push(WEBGPU_FLAG);
+        if (platform === "win32") {
+            chromeArgs.push(DISABLE_DXC_FLAG);
+        }
     }
     if (softwareWebGpu)
         chromeArgs.push("--use-vulkan=swiftshader");

package/dist/services/captureFailure.d.ts

@@ -10,16 +10,19 @@ export declare class CaptureFailure extends Error {
     readonly kind: CaptureFailureKind;
     readonly cause: unknown;
     readonly workerDiagnostics: readonly CaptureWorkerDiagnostic[];
+    readonly pageErrorLines: readonly string[];
     constructor(input: {
         kind: CaptureFailureKind;
         message: string;
         cause?: unknown;
         workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
+        pageErrorLines?: readonly string[];
     });
 }
 export declare function classifyCaptureFailure(error: unknown, options?: {
     signal?: AbortSignal;
     workerDiagnostics?: readonly CaptureWorkerDiagnostic[];
+    pageErrorLines?: readonly string[];
 }): CaptureFailure;
 export declare function isTransientBrowserError(error: unknown): boolean;
 export declare function isMemoryExhaustionError(error: unknown): boolean;

package/dist/services/captureFailure.js

@@ -2,12 +2,14 @@ export class CaptureFailure extends Error {
     kind;
     cause;
     workerDiagnostics;
+    pageErrorLines;
     constructor(input) {
         super(input.message);
         this.name = "CaptureFailure";
         this.kind = input.kind;
         this.cause = input.cause;
         this.workerDiagnostics = Object.freeze((input.workerDiagnostics ?? []).map((diagnostic) => Object.freeze({ ...diagnostic, lines: Object.freeze([...diagnostic.lines]) })));
+        this.pageErrorLines = Object.freeze([...(input.pageErrorLines ?? [])]);
         if (input.cause instanceof Error && input.cause.stack)
             this.stack = input.cause.stack;
     }
@@ -101,41 +103,40 @@ function ioError(error, message) {
         BROKEN_PIPE_MESSAGE.test(message) ||
         hasIoOperationFailure(message));
 }
+const ORDERED_KIND_RULES = [
+    [
+        "memory_exhaustion",
+        (message) => BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()) ||
+            BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message) ||
+            matchesAny(message, MEMORY_EXHAUSTION_ERROR_PATTERNS),
+    ],
+    ["verification", (message) => matchesAny(message, VERIFICATION_ERROR_PATTERNS)],
+    ["protocol_timeout", (message) => matchesAny(message, PROTOCOL_TIMEOUT_PATTERNS)],
+    ["transient_browser", (message) => matchesAny(message, TRANSIENT_BROWSER_ERROR_PATTERNS)],
+    ["authoring", (message) => matchesAny(message, AUTHORING_ERROR_PATTERNS)],
+];
+function classifyKind(error, message, signal) {
+    if (signal?.aborted || /(?:render|capture)?_?cancelled|AbortError/i.test(message)) {
+        return "cancelled";
+    }
+    const rule = ORDERED_KIND_RULES.find(([, matches]) => matches(message));
+    if (rule)
+        return rule[0];
+    return ioError(error, message) ? "io" : "authoring";
+}
 export function classifyCaptureFailure(error, options = {}) {
-    if (error instanceof CaptureFailure && !options.workerDiagnostics && !options.signal?.aborted) {
-        return error;
+    const prior = error instanceof CaptureFailure ? error : undefined;
+    if (prior && !(options.workerDiagnostics || options.pageErrorLines || options.signal?.aborted)) {
+        return prior;
     }
     const message = messageOf(error);
-    let kind;
-    if (options.signal?.aborted || /(?:render|capture)?_?cancelled|AbortError/i.test(message)) {
-        kind = "cancelled";
-    }
-    else if (BUN_MEMORY_EXHAUSTION_EXACT_MESSAGE.test(message.trim()) ||
-        BUN_MEMORY_EXHAUSTION_WRAPPED_WORKER_MESSAGE.test(message) ||
-        matchesAny(message, MEMORY_EXHAUSTION_ERROR_PATTERNS)) {
-        kind = "memory_exhaustion";
-    }
-    else if (matchesAny(message, VERIFICATION_ERROR_PATTERNS)) {
-        kind = "verification";
-    }
-    else if (matchesAny(message, PROTOCOL_TIMEOUT_PATTERNS)) {
-        kind = "protocol_timeout";
-    }
-    else if (matchesAny(message, TRANSIENT_BROWSER_ERROR_PATTERNS)) {
-        kind = "transient_browser";
-    }
-    else if (matchesAny(message, AUTHORING_ERROR_PATTERNS)) {
-        kind = "authoring";
-    }
-    else {
-        kind = ioError(error, message) ? "io" : "authoring";
-    }
+    const kind = classifyKind(error, message, options.signal);
     return new CaptureFailure({
         kind,
         message,
         cause: error,
-        workerDiagnostics: options.workerDiagnostics ??
-            (error instanceof CaptureFailure ? error.workerDiagnostics : undefined),
+        workerDiagnostics: options.workerDiagnostics ?? prior?.workerDiagnostics,
+        pageErrorLines: options.pageErrorLines ?? prior?.pageErrorLines,
     });
 }
 export function isTransientBrowserError(error) {

package/dist/services/chunkEncoder.js

@@ -7,7 +7,7 @@
  */
 import { frameSequencePath } from "./extractedFrameIndex.js";
 import { closeSync, copyFileSync, existsSync, ftruncateSync, mkdirSync, mkdtempSync, openSync, readFileSync, readdirSync, statSync, writeFileSync, writeSync, } from "fs";
-import { join, dirname, extname } from "path";
+import { join, dirname, extname, resolve } from "path";
 import { DEFAULT_CONFIG } from "../config.js";
 import { getCachedGpuEncoder, getGpuEncoderName, buildVideoToolboxRateControlArgs, mapPresetForGpuEncoder, } from "../utils/gpuEncoder.js";
 import { getHdrEncoderColorParams, hdrFrameTagsFilter } from "../utils/hdr.js";
@@ -460,7 +460,7 @@ let concatListSeq = 0;
 function writeConcatList(dir, inputPaths) {
     concatListSeq += 1;
     const listPath = join(dir, `concat-list-${process.pid}-${concatListSeq}.txt`);
-    const body = inputPaths.map((p) => `file '${p.replace(/'/g, "'\\''")}'`).join("\n");
+    const body = inputPaths.map((p) => `file '${resolve(p).replace(/'/g, "'\\''")}'`).join("\n");
     writeFileSync(listPath, body, "utf-8");
     return listPath;
 }

package/dist/services/extractionCache.js

@@ -32,7 +32,8 @@
  * become inert and can be gc'd by the caller.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { renameWithRetry } from "../utils/renameWithRetry.js";
 import { join } from "node:path";
 import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
 /** Filename prefix for extracted frames. Shared with the extractor. */
@@ -185,7 +186,7 @@ export function publishCacheEntry(entry, partialDir) {
         return { dir: partialDir, published: false };
     }
     try {
-        renameSync(partialDir, entry.dir);
+        renameWithRetry(partialDir, entry.dir);
         return { dir: entry.dir, published: true };
     }
     catch (err) {
@@ -202,7 +203,7 @@ export function publishCacheEntry(entry, partialDir) {
         return { dir: partialDir, published: false };
     }
     try {
-        renameSync(partialDir, entry.dir);
+        renameWithRetry(partialDir, entry.dir);
         return { dir: entry.dir, published: true };
     }
     catch {

package/dist/services/frameCapture.js

@@ -393,14 +393,17 @@ export async function driveWarmupTicks(options, state) {
             if (!state.running)
                 return;
         }
+        let ticked = false;
         try {
             await options.tick(state.ticks * options.intervalMs, options.intervalMs);
             state.ticks += 1;
+            ticked = true;
         }
         catch {
             // Page not ready yet; keep spinning.
         }
-        await sleep(options.intervalMs);
+        if (!(options.lockWarmupTicks && !state.running && ticked))
+            await sleep(options.intervalMs);
     }
 }
 export function resolveCaptureSessionOptions(options, browserVersion, platform = process.platform) {

package/dist/services/hdrCapture.js

@@ -18,6 +18,7 @@
  *
  * Performance: ~6 fps at 1080x1920 via base64 transfer.
  */
+import { withHyperframesBrowserMarker } from "@hyperframes/core/browser-marker";
 import { resolveFullChromePath, sigintLaunchOptions } from "./browserManager.js";
 // ── PQ (SMPTE 2084) OETF ─────────────────────────────────────────────────────
 const PQ_M1 = 0.1593017578125;
@@ -183,7 +184,7 @@ export async function launchHdrBrowser(width, height) {
         ...sigintLaunchOptions(),
         headless: false,
         executablePath: chromePath,
-        args: buildHdrChromeArgs(width, height),
+        args: withHyperframesBrowserMarker(buildHdrChromeArgs(width, height)),
     });
     const page = await browser.newPage();
     await page.setViewport({ width, height });

package/dist/services/parallelCoordinator.d.ts

@@ -46,6 +46,8 @@ export interface WorkerResult {
     perf?: CapturePerfSummary;
     error?: string;
     diagnostics?: string[];
+    /** The worker session's `[Browser:PAGEERROR]` console lines, kept so the render's error count sees them. */
+    pageErrorLines?: string[];
     failure?: CaptureFailure;
 }
 export interface ParallelProgress {

package/dist/services/parallelCoordinator.js

@@ -6,7 +6,8 @@
  */
 import { cpus, freemem } from "os";
 import { existsSync, mkdirSync, readdirSync } from "fs";
-import { copyFile, readFile, rename } from "fs/promises";
+import { copyFile, readFile } from "fs/promises";
+import { renameWithRetryAsync } from "../utils/renameWithRetry.js";
 import { join } from "path";
 import { getHeapStatistics } from "v8";
 import { createCaptureSession, initializeSession, closeCaptureSession, captureFrame, captureFrameToBufferPipelined, captureFrameToBuffer, getCapturePerfSummary, DrawElementVerificationError, } from "./frameCapture.js";
@@ -615,6 +616,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
             frameStride: task.frameStride,
             durationMs: Date.now() - startTime,
             perf,
+            pageErrorLines: pageErrorLinesOf(activeSession),
         };
     }
     catch (error) {
@@ -629,6 +631,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
         const failure = classifyCaptureFailure(error, {
             signal,
             workerDiagnostics: [workerDiagnostic],
+            pageErrorLines: session ? pageErrorLinesOf(session) : undefined,
         });
         onFailure?.(failure);
         return {
@@ -641,6 +644,7 @@ async function executeWorkerTask(task, serverUrl, captureOptions, createBeforeCa
             perf,
             error: failure.message,
             diagnostics: diagnostics.length > 0 ? diagnostics : undefined,
+            pageErrorLines: session ? pageErrorLinesOf(session) : undefined,
             failure,
         };
     }
@@ -681,6 +685,9 @@ export function isPoolFatalWorkerFailure(failure, streaming) {
         return failure.kind !== "cancelled";
     return isFatalCaptureFailure(failure);
 }
+function pageErrorLinesOf(session) {
+    return session.browserConsoleBuffer.filter((line) => line.includes("PAGEERROR"));
+}
 /**
  * The pool's single failure gate. Both halves of the contract the streaming
  * stage relies on live here so they can be pinned without a browser: the
@@ -778,6 +785,7 @@ export async function executeParallelCapture(serverUrl, workDir, tasks, captureO
             message: `[Parallel] Capture failed: ${errorMessages}`,
             cause: representative,
             workerDiagnostics,
+            pageErrorLines: [...new Set(results.flatMap((result) => result.pageErrorLines ?? []))],
         });
     }
     return results;
@@ -798,7 +806,7 @@ export async function mergeWorkerFrames(workDir, tasks, outputDir) {
             const sourcePath = join(task.outputDir, file);
             const targetPath = join(outputDir, file);
             try {
-                await rename(sourcePath, targetPath);
+                await renameWithRetryAsync(sourcePath, targetPath);
             }
             catch {
                 await copyFile(sourcePath, targetPath);

package/dist/services/videoFrameExtractor.d.ts

@@ -6,7 +6,7 @@
  */
 import { resolveProjectRelativeSrc } from "@hyperframes/parsers/asset-resolution";
 import { type RateSpec, type FpsInput } from "@hyperframes/core";
-import { type VideoMetadata } from "../utils/ffprobe.js";
+import { resolvePlayableVideoDuration, type VideoMetadata } from "../utils/ffprobe.js";
 import { type HdrTransfer } from "../utils/hdr.js";
 import { type EngineConfig } from "../config.js";
 import { type CacheFrameFormat } from "./extractionCache.js";
@@ -60,6 +60,17 @@ export declare function isVideoFrameFormat(value: unknown): value is VideoFrameF
  * rejected because the two paths disagree by one frame.
  */
 export declare function extractionFrameCountForDuration(durationSeconds: number, fps: FpsInput, isVFR: boolean): number;
+/** Slots of a window reaching the source's end that hold a frame, from the stored final frame; null if unsure. */
+export declare function tailFramesFromFinalFrame(input: {
+    startTime: number;
+    firstFrame: number;
+    tailFrames: number;
+    outputFps: number;
+    sourceFps: number;
+    finalFrameSeconds: number;
+    streamLeadSeconds: number;
+    lastPacketSeconds?: number;
+}): number | null;
 export interface FrameRange {
     firstFrame: number;
     frames: number;
@@ -100,6 +111,8 @@ export interface ExtractionOptions {
     collectProbeFailures?: boolean;
     /** Extract only these runs of output frames, named as a full extraction names them. CFR only. */
     frameRanges?: readonly FrameRange[];
+    /** A short decode of a remote source, only to count its frames: it waits on the network, so it runs wider. */
+    tailProbe?: boolean;
     /**
      * Leave CFR windows longer than a second unextracted, returning `deferredRange` and an exact
      * `totalFrames` so another process can extract just the frames it needs with `frameRanges`.
@@ -259,7 +272,7 @@ export declare function classifyFfmpegSpawnError(error: unknown, stderr?: string
  * the container duration when ffprobe omits the stream duration; keep the
  * explicit fallback here for callers supplying older/manual metadata.
  */
-export declare function resolvePlayableVideoDuration(metadata: VideoMetadata): number;
+export { resolvePlayableVideoDuration };
 export interface TimelineExtractionWindow {
     compositionStart: number;
     mediaStart: number;

package/dist/services/videoFrameExtractor.js

@@ -17,7 +17,7 @@ import { alphaDecoderFor } from "@hyperframes/parsers/media-alpha";
 import { MEDIA_RENDER_ID_ATTR, isAudibleVideoElement, fpsToFfmpegArg, fpsToNumber, MEDIA_DURATION_CLAMP_EPSILON_SECONDS, normalizeRateSpec, readElementRateSpec, shiftRateLane, sourceTimeAt, timeAtSourceTime, exportClipWindow, hasClipStarted, isInClipWindow, parseStrictFiniteTimingNumber, readMediaStart, toFps, firstFrameColourArgs, hdrToSdrToneMapFilter, parseFirstFrameColour, } from "@hyperframes/core";
 import { resolveReferencedStart } from "./referenceResolver.js";
 import { isKnownInactiveTimelineWindow } from "./mediaTimelineWindow.js";
-import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, writeMetadataCache, } from "../utils/ffprobe.js";
+import { extractFinalVideoFrameTimestamp, extractMediaMetadata, mediaFileIdentity, readMetadataCache, readStoredFinalFrame, resolvePlayableVideoDuration, writeMetadataCache, } from "../utils/ffprobe.js";
 import { inputAlphaOpaqueWarning, probeInputAlphaPlane } from "../utils/alphaPlaneProbe.js";
 import { redactUrlQueriesInError, urlInputArgs } from "../utils/urlInput.js";
 import { analyzeCompositionHdr, isHdrColorSpace as isHdrColorSpaceUtil, } from "../utils/hdr.js";
@@ -109,6 +109,32 @@ export function extractionFrameCountForDuration(durationSeconds, fps, isVFR) {
     const frames = Number(frameCount);
     return Math.max(1, Number.isSafeInteger(frames) ? frames : Number.MAX_SAFE_INTEGER);
 }
+/** The exact rate behind a probed one (rounded to 0.01): a whole number or its 1000/1001 NTSC form. */
+function exactSourceRate(probed) {
+    const nominal = Math.round(probed * 1.001);
+    return ([nominal, (nominal * 1000) / 1001].find((rate) => Math.abs(rate - probed) <= 0.005 + 1e-9) ??
+        null);
+}
+/** Slots of a window reaching the source's end that hold a frame, from the stored final frame; null if unsure. */
+export function tailFramesFromFinalFrame(input) {
+    const sourceRate = exactSourceRate(input.sourceFps);
+    if (!sourceRate || !(input.outputFps > 0))
+        return null;
+    // A late-starting stream ends where its last packet does, and ffmpeg shortens the last frame
+    // to a short packet in ways the stored facts cannot predict: trust only a full-frame packet.
+    const lead = input.streamLeadSeconds;
+    if (lead !== 0 && !(Math.abs((input.lastPacketSeconds ?? NaN) - 1 / sourceRate) <= 1e-4)) {
+        return null;
+    }
+    const seek = input.startTime + input.firstFrame / input.outputFps;
+    const slots = (lead + input.finalFrameSeconds + 1 / sourceRate - seek) * input.outputFps;
+    const distanceToSlot = Math.abs(slots - Math.round(slots));
+    // ffprobe prints the final time to 1 us; a slot closer than 50 us/fps to the end is a tie, up to 500 us/fps unknown.
+    if (distanceToSlot >= 5e-5 && distanceToSlot < 5e-4)
+        return null;
+    const count = Math.min(input.tailFrames, Math.ceil(slots - 5e-5));
+    return count > 0 ? count : null;
+}
 const DOWNLOAD_SUBDIR = "_downloads";
 export const EXTRACT_CACHE_MIN_AGE_MS = 60 * 60 * 1000;
 const GC_STALENESS_MS = 24 * 60 * 60 * 1000;
@@ -468,6 +494,8 @@ function undoTickRoundingOnTheSourceFrameGrid(seek, lead) {
 // Caps extraction ffmpeg runs across all clips; uncapped, dozens of clips starved each other into timeouts.
 const EXTRACTION_SLOTS = Math.max(1, Math.floor(cpus().length / 2));
 const inExtractionSlot = createConcurrencyLimit(EXTRACTION_SLOTS);
+const TAIL_PROBE_SLOTS = Math.max(1, Number(process.env.HF_TAIL_PROBE_SLOTS) || 16);
+const inTailProbeSlot = createConcurrencyLimit(TAIL_PROBE_SLOTS);
 /** Split runs so no single ffmpeg process extracts more than `segmentFrames` frames. */
 function splitFrameRanges(ranges, segmentFrames) {
     const segments = [];
@@ -482,7 +510,7 @@ function splitFrameRanges(ranges, segmentFrames) {
     return segments;
 }
 async function runSegmentedExtraction(job) {
-    const { decodeArgs, filterAndEncodeArgs, videoPath, startTime, fps, segments } = job;
+    const { decodeArgs, filterAndEncodeArgs, videoPath, startTime, fps, segments, gate } = job;
     const segmentCount = segments.length;
     // One failed segment fails the range, so stop the others instead of finishing them.
     const failed = new AbortController();
@@ -496,7 +524,7 @@ async function runSegmentedExtraction(job) {
             const index = next++;
             const { firstFrame, frames } = segments[index];
             const seek = startTime + firstFrame / fps;
-            const result = await inExtractionSlot(() => runFfmpeg([
+            const result = await gate(() => runFfmpeg([
                 ...decodeArgs,
                 "-noaccurate_seek",
                 "-ss",
@@ -677,6 +705,7 @@ outputDirOverride) {
             videoPath,
             startTime,
             fps,
+            gate: options.tailProbe ? inTailProbeSlot : inExtractionSlot,
             segments: splitFrameRanges(options.frameRanges ?? [{ firstFrame: 0, frames: totalFrames }], segmentFrames),
             runOptions,
         })
@@ -772,12 +801,7 @@ function resolveSegmentDuration(requested, mediaStart, sourceDuration) {
  * the container duration when ffprobe omits the stream duration; keep the
  * explicit fallback here for callers supplying older/manual metadata.
  */
-export function resolvePlayableVideoDuration(metadata) {
-    return Number.isFinite(metadata.videoStreamDurationSeconds) &&
-        metadata.videoStreamDurationSeconds > 0
-        ? (metadata.videoStreamLeadSeconds ?? 0) + metadata.videoStreamDurationSeconds
-        : metadata.durationSeconds;
-}
+export { resolvePlayableVideoDuration };
 function canHoldFinalFramePastEof(video) {
     const timelineDuration = video.end - video.start;
     return !video.loop && Number.isFinite(timelineDuration) && timelineDuration > 0;
@@ -1499,16 +1523,7 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
         const tailFrames = Math.min(expectedFrames, Math.ceil(fps));
         if (expectedFrames <= tailFrames)
             return null;
-        const probeDir = join(options.outputDir, `${work.video.id}.tail-probe`);
-        try {
-            const tail = await extractVideoFramesRange(work.videoPath, work.video.id, work.extractionMediaStart, work.videoDuration, {
-                ...scopedExtractionOptions(work),
-                frameRanges: [{ firstFrame: expectedFrames - tailFrames, frames: tailFrames }],
-            }, signal, config, probeDir);
-            const totalFrames = expectedFrames - tailFrames + tail.totalFrames;
-            // A full extraction this short rewrites the probed duration; let it.
-            if (totalFrames <= expectedFrames * 0.6)
-                return null;
+        const deferred = (totalFrames) => {
             const outputDir = join(options.outputDir, work.video.id);
             mkdirSync(outputDir, { recursive: true });
             return {
@@ -1526,6 +1541,42 @@ export async function extractAllVideoFrames(videos, baseDir, options, signal, co
                     format: work.format,
                 },
             };
+        };
+        // A window that ends a second or more inside the source cannot run out of frames: its count is the expected one.
+        if (work.extractionMediaStart + work.videoDuration + 1 <=
+            resolvePlayableVideoDuration(work.metadata)) {
+            return deferred(expectedFrames);
+        }
+        const firstTailFrame = expectedFrames - tailFrames;
+        const storedFinalFrame = await readStoredFinalFrame(work.videoPath, work.metadata);
+        const storedTailFrames = storedFinalFrame === undefined
+            ? null
+            : tailFramesFromFinalFrame({
+                startTime: work.extractionMediaStart,
+                firstFrame: firstTailFrame,
+                tailFrames,
+                outputFps: fps,
+                sourceFps: work.metadata.fps,
+                finalFrameSeconds: storedFinalFrame.seconds,
+                lastPacketSeconds: storedFinalFrame.lastPacketSeconds,
+                streamLeadSeconds: work.metadata.videoStreamLeadSeconds ?? 0,
+            });
+        if (storedTailFrames !== null) {
+            const totalFrames = firstTailFrame + storedTailFrames;
+            return totalFrames <= expectedFrames * 0.6 ? null : deferred(totalFrames);
+        }
+        const probeDir = join(options.outputDir, `${work.video.id}.tail-probe`);
+        try {
+            const tail = await extractVideoFramesRange(work.videoPath, work.video.id, work.extractionMediaStart, work.videoDuration, {
+                ...scopedExtractionOptions(work),
+                frameRanges: [{ firstFrame: firstTailFrame, frames: tailFrames }],
+                tailProbe: isHttpUrl(work.videoPath),
+            }, signal, config, probeDir);
+            const totalFrames = firstTailFrame + tail.totalFrames;
+            // A full extraction this short rewrites the probed duration; let it.
+            if (totalFrames <= expectedFrames * 0.6)
+                return null;
+            return deferred(totalFrames);
         }
         catch {
             return null;

package/dist/utils/ffprobe.d.ts

@@ -102,9 +102,18 @@ export interface MediaProbeProfile {
 }
 /** A URL whose bytes can never change (its path holds their hash), so probes of it are cacheable. */
 export declare function declareContentAddressedUrl(url: string, sha256: string): void;
+/** Where the ffprobe JSON of a content-addressed URL was stored beforehand: reading it replaces probing the file. */
+export declare function declareProbeFactsUrl(url: string, factsUrl: string): void;
 export declare function mediaFileIdentity(filePath: string): string | null;
 export declare function readMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null): Promise<T> | undefined;
 export declare function writeMetadataCache<T>(cache: Map<string, MediaProbeCacheEntry<T>>, key: string, identity: string | null, promise: Promise<T>): void;
+/** Part of the name a stored probe is kept under: bump it with the args below. */
+export declare const PROBE_FACTS_VERSION = "v2";
+/** The ffprobe JSON `probeMediaOutput` works from; a declared URL's stored copy is read in place of probing it. */
+export declare function readProbeJson(filePath: string, signal?: AbortSignal): Promise<string>;
+/** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */
+export declare function buildProbeFactsText(filePath: string, signal?: AbortSignal): Promise<string>;
+export declare function resolvePlayableVideoDuration(metadata: VideoMetadata): number;
 /**
  * Probe stream capabilities without assuming the caller's element type.
  * File extensions and HTTP MIME are deliberately ignored: extensionless
@@ -154,6 +163,11 @@ export declare function parseFrameRate(frameRateStr: string | undefined): number
  * can be used uniformly for any visual asset the HDR pipeline encounters.
  */
 export declare function extractMediaMetadata(filePath: string): Promise<VideoMetadata>;
+/** Stored final-frame facts for this stream window; none if undeclared (no await then, so a probe spawns at once). */
+export declare function readStoredFinalFrame(filePath: string, metadata: Pick<VideoMetadata, "videoStreamDurationSeconds" | "videoStreamStartSeconds">): Promise<{
+    seconds: number;
+    lastPacketSeconds?: number;
+} | undefined> | undefined;
 /**
  * Return the FFmpeg input-seek position of the final decoded video frame.
  *

package/dist/utils/ffprobe.js

@@ -217,6 +217,11 @@ const withoutQuery = (url) => url.split(/[?#]/, 1)[0] ?? url;
 export function declareContentAddressedUrl(url, sha256) {
     contentAddressedUrls.set(withoutQuery(url), sha256);
 }
+const probeFactsUrls = new Map();
+/** Where the ffprobe JSON of a content-addressed URL was stored beforehand: reading it replaces probing the file. */
+export function declareProbeFactsUrl(url, factsUrl) {
+    probeFactsUrls.set(withoutQuery(url), factsUrl);
+}
 export function mediaFileIdentity(filePath) {
     if (/^https?:\/\//i.test(filePath)) {
         const sha256 = contentAddressedUrls.get(withoutQuery(filePath));
@@ -246,6 +251,88 @@ export function writeMetadataCache(cache, key, identity, promise) {
             cache.delete(key);
     });
 }
+/** Part of the name a stored probe is kept under: bump it with the args below. */
+export const PROBE_FACTS_VERSION = "v2";
+const PROBE_JSON_ARGS = ["-print_format", "json", "-show_format", "-show_streams"];
+const storedFacts = new Map();
+/** The facts stored for a declared URL, fetched once; null when there are none or they cannot be read. */
+function readStoredFacts(filePath) {
+    if (!/^https?:\/\//i.test(filePath))
+        return undefined;
+    const factsUrl = probeFactsUrls.get(withoutQuery(filePath));
+    if (!factsUrl)
+        return undefined;
+    let facts = storedFacts.get(factsUrl);
+    if (!facts) {
+        facts = (async () => {
+            try {
+                const response = await fetch(factsUrl, { signal: AbortSignal.timeout(10_000) });
+                if (!response.ok)
+                    return null;
+                const parsed = JSON.parse(await response.text());
+                return Array.isArray(parsed.ffprobe?.streams) ? parsed : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        storedFacts.set(factsUrl, facts);
+    }
+    return facts;
+}
+/** The ffprobe JSON `probeMediaOutput` works from; a declared URL's stored copy is read in place of probing it. */
+export function readProbeJson(filePath, signal) {
+    const pending = readStoredFacts(filePath);
+    if (!pending)
+        return runFfprobe(filePath, PROBE_JSON_ARGS, signal);
+    return pending.then((stored) => stored ? JSON.stringify(stored.ffprobe) : runFfprobe(filePath, PROBE_JSON_ARGS, signal));
+}
+let runtimeFfprobeMajor;
+/** The major version of the ffprobe this process runs; undefined when it cannot be read. */
+function ffprobeMajor() {
+    runtimeFfprobeMajor ??= new Promise((resolve) => {
+        let out = "";
+        const binary = getFfprobeBinary();
+        const proc = spawn(binary, ["-version"], { stdio: ["ignore", "pipe", "ignore"] });
+        proc.stdout.on("data", (chunk) => (out += String(chunk)));
+        proc.on("error", () => resolve(undefined));
+        proc.on("close", () => resolve(Number(/version n?(\d+)/.exec(out)?.[1]) || undefined));
+    });
+    return runtimeFfprobeMajor;
+}
+/** What a site stores beside a video: its ffprobe JSON and the final-frame facts a plan would otherwise probe for. */
+export async function buildProbeFactsText(filePath, signal) {
+    const facts = {
+        ffprobe: parseProbeJson(await runFfprobe(filePath, PROBE_JSON_ARGS, signal)),
+        ffprobeMajor: await ffprobeMajor(),
+    };
+    try {
+        const metadata = await extractMediaMetadata(filePath);
+        const window = resolveStreamWindow(filePath, {
+            videoStreamStartSeconds: metadata.videoStreamStartSeconds,
+            videoStreamDurationSeconds: resolvePlayableVideoDuration(metadata) - (metadata.videoStreamLeadSeconds ?? 0),
+        });
+        if (window.videoStreamDurationSeconds > 0) {
+            facts.finalFrame = {
+                streamStart: window.videoStreamStartSeconds,
+                streamDuration: window.videoStreamDurationSeconds,
+                seconds: await extractFinalVideoFrameTimestamp(filePath, window, signal),
+                lastPacketSeconds: await extractFinalPacketDuration(filePath, window, signal),
+            };
+        }
+    }
+    catch {
+        if (signal?.aborted)
+            throw signal.reason;
+    }
+    return JSON.stringify(facts);
+}
+export function resolvePlayableVideoDuration(metadata) {
+    return Number.isFinite(metadata.videoStreamDurationSeconds) &&
+        metadata.videoStreamDurationSeconds > 0
+        ? (metadata.videoStreamLeadSeconds ?? 0) + metadata.videoStreamDurationSeconds
+        : metadata.durationSeconds;
+}
 async function probeMediaOutput(filePath, signal) {
     let cache = mediaProbeOutputCache;
     if (signal) {
@@ -264,7 +351,7 @@ async function probeMediaOutput(filePath, signal) {
         }
         return cached.promise;
     }
-    const promise = runFfprobe(filePath, ["-print_format", "json", "-show_format", "-show_streams"], signal).then(parseProbeJson);
+    const promise = readProbeJson(filePath, signal).then(parseProbeJson);
     if (identity !== null) {
         cache.set(filePath, { identity, promise });
         if (!signal && cache.size > MEDIA_PROBE_OUTPUT_CACHE_MAX_ENTRIES) {
@@ -672,6 +759,45 @@ function resolveStreamWindow(filePath, metadata) {
     const cacheKey = `${filePath}\0${String(videoStreamStartSeconds)}\0${String(videoStreamDurationSeconds)}`;
     return { videoStreamStartSeconds, videoStreamDurationSeconds, cacheKey };
 }
+/** Stored final-frame facts for this stream window; none if undeclared (no await then, so a probe spawns at once). */
+export function readStoredFinalFrame(filePath, metadata) {
+    const { videoStreamStartSeconds, videoStreamDurationSeconds } = resolveStreamWindow(filePath, metadata);
+    return readStoredFacts(filePath)?.then(async (facts) => {
+        const stored = facts?.finalFrame;
+        // Another major version may place the final frame or stream start differently: probe instead.
+        if (facts?.ffprobeMajor !== undefined && facts.ffprobeMajor !== (await ffprobeMajor()))
+            return undefined;
+        return stored &&
+            stored.streamStart === videoStreamStartSeconds &&
+            stored.streamDuration === videoStreamDurationSeconds
+            ? stored
+            : undefined;
+    });
+}
+/**
+ * `duration_time` of the stream's last packet (by presentation time), read from the same final
+ * second the final-frame probe reads; undefined when ffprobe reports none.
+ */
+async function extractFinalPacketDuration(filePath, window, signal) {
+    const streamEnd = window.videoStreamStartSeconds + window.videoStreamDurationSeconds;
+    const intervalStart = Math.max(window.videoStreamStartSeconds, streamEnd - 1);
+    const stdout = await runFfprobe(filePath, [
+        "-select_streams",
+        "v:0",
+        "-read_intervals",
+        `${intervalStart}%${streamEnd}`,
+        "-show_entries",
+        "packet=pts_time,duration_time",
+        "-of",
+        "csv=p=0",
+    ], signal, { retainTail: true, maxChars: 64 * 1024 });
+    const packets = stdout
+        .split("\n")
+        .map((line) => line.trim().split(",").map(Number))
+        .filter(([pts, duration]) => Number.isFinite(pts) && Number.isFinite(duration));
+    const last = packets.reduce((best, packet) => (!best || packet[0] > best[0] ? packet : best), undefined);
+    return last?.[1];
+}
 /**
  * Return the FFmpeg input-seek position of the final decoded video frame.
  *
@@ -705,6 +831,10 @@ export async function extractFinalVideoFrameTimestamp(filePath, metadata, signal
     if (cached)
         return cached;
     const probePromise = (async () => {
+        const pendingStored = readStoredFinalFrame(filePath, metadata);
+        const stored = pendingStored && (await pendingStored);
+        if (stored)
+            return stored.seconds;
         if (!(videoDurationSeconds > 0) || !Number.isFinite(videoDurationSeconds)) {
             throw new Error(`[FFmpeg] Cannot locate final video frame for invalid duration ${String(videoDurationSeconds)}`);
         }

package/dist/utils/renameWithRetry.d.ts

@@ -0,0 +1,12 @@
+interface Options {
+    platform?: NodeJS.Platform;
+}
+/** `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;
+}): void;
+/** Async twin of {@link renameWithRetry}. */
+export declare function renameWithRetryAsync(from: string, to: string, options?: Options & {
+    rename?: (from: string, to: string) => Promise<void>;
+}): Promise<void>;
+export {};

package/dist/utils/renameWithRetry.js

@@ -0,0 +1,46 @@
+import { renameSync } from "node:fs";
+import { rename } from "node:fs/promises";
+// 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"]);
+const BACKOFF_MS = [10, 20, 40, 80, 160, 320, 640];
+function isRetryable(error, platform) {
+    if (platform !== "win32")
+        return false;
+    return RETRYABLE.has(error?.code ?? "");
+}
+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 platform = options.platform ?? process.platform;
+    for (let attempt = 0;; attempt++) {
+        try {
+            doRename(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+                throw error;
+            sleepSync(BACKOFF_MS[attempt]);
+        }
+    }
+}
+/** Async twin of {@link renameWithRetry}. */
+export async function renameWithRetryAsync(from, to, options = {}) {
+    const doRename = options.rename ?? rename;
+    const platform = options.platform ?? process.platform;
+    for (let attempt = 0;; attempt++) {
+        try {
+            await doRename(from, to);
+            return;
+        }
+        catch (error) {
+            if (attempt >= BACKOFF_MS.length || !isRetryable(error, platform))
+                throw error;
+            await new Promise((resolve) => setTimeout(resolve, BACKOFF_MS[attempt]));
+        }
+    }
+}

package/package.json

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