@hyperframes/engine 0.8.145 → 0.8.147

package/dist/config.d.ts

@@ -442,4 +442,3 @@ export declare function shouldClampToScreenshotForConcreteGpu(resolvedGpuMode: "
  * without consulting anything else.
  */
 export declare function applyConcreteGpuScreenshotClamp(currentForceScreenshot: boolean, resolvedGpuMode: "software" | "hardware", cfg: Pick<EngineConfig, "forceScreenshotExplicitlyOptedOut"> | undefined, env?: NodeJS.ProcessEnv): boolean;
-//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -647,7 +647,7 @@ export function resolveConfig(overrides) {
         })) {
         merged.enableStreamingEncode = false;
         merged.streamingEncodeAutoDisabledOnWin32Compound = true;
-        console.error("[hyperframes] Windows compound-workaround auto-detected — disabling streaming-encode " +
+        console.error("[hyperframes] Windows compound-workaround auto-detected, disabling streaming-encode " +
             "(platform=win32, software-GPU forced, workers=1). Field signal ts=1784131903. " +
             "Override: PRODUCER_ENABLE_STREAMING_ENCODE=true.");
     }
@@ -720,4 +720,3 @@ export function applyConcreteGpuScreenshotClamp(currentForceScreenshot, resolved
             programmaticOptOut: cfg?.forceScreenshotExplicitlyOptedOut ?? false,
         }));
 }
-//# sourceMappingURL=config.js.map

package/dist/index.d.ts

@@ -45,7 +45,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, type GpuEncoder, type PackageHlsOptions, } from "./services/chunkEncoder.js";
 export type { EncoderOptions, EncodeResult, MuxResult } from "./services/chunkEncoder.types.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, type StreamingEncoder, type StreamingEncoderOptions, type StreamingEncoderResult, type FrameReorderBuffer, } from "./services/streamingEncoder.js";
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, 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, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, 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 { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, type RefResolverEl, type RefResolverDoc, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
@@ -78,4 +78,3 @@ export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompo
 export type { VideoColorSpace } from "./utils/ffprobe.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, type RenderProvenance, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -49,7 +49,7 @@ export { beginFrameCapture, pageScreenshotCapture, getCdpSession, injectVideoFra
 export { buildEncoderArgs, encodeFramesFromDir, buildConcatArgs, concatVideoFiles, encodeFramesChunkedConcat, muxVideoWithAudio, applyFaststart, packageHls, detectGpuEncoder, ENCODER_PRESETS, getEncoderPreset, HLS_MASTER_PLAYLIST, HLS_VIDEO_PLAYLIST, HLS_AUDIO_PLAYLIST, } from "./services/chunkEncoder.js";
 export { spawnStreamingEncoder, createFrameReorderBuffer, } from "./services/streamingEncoder.js";
 // ── Media processing ───────────────────────────────────────────────────────────
-export { parseVideoElements, parseImageElements, extractVideoFramesRange, extractAllVideoFrames, resolveTimelineExtractionWindow, resolveVideoExtractionWindow, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, 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, resolveFinalFrameExtractionWindow, resolveVideoExtractionDuration, resolvePlayableVideoDuration, extractionFrameCountForDuration, resolveProjectRelativeSrc, getFrameAtTime, createFrameLookupTable, FrameLookupTable, analyzeClipMediaFit, classifyVideoExtractionError, isVideoSourceExtractionError, runVideoExtractionWithRetry, safeVideoExtractionSourceIdentity, VideoSourceExtractionError, VIDEO_FRAME_FORMATS, isVideoFrameFormat, EXTRACT_CACHE_MIN_AGE_MS, } from "./services/videoFrameExtractor.js";
 export { directorySizeBytes, gcExtractionCache } from "./services/extractionCache.js";
 export { resolveReferencedStart, resolveReferencedDuration, } from "./services/referenceResolver.js";
 export { createVideoFrameInjector } from "./services/videoFrameInjector.js";
@@ -85,4 +85,3 @@ export { hideVideoElements, showVideoElements, queryVideoElementBounds, queryEle
 export { isHdrColorSpace, detectTransfer, getHdrEncoderColorParams, analyzeCompositionHdr, findHdrAutoPromotion, formatHdrAutoPromotionWarning, sanitizeHdrAutoPromotionAsset, DEFAULT_HDR10_MASTERING, HDR_AUTO_PROMOTION_PIPELINE, } from "./utils/hdr.js";
 export { renderProvenanceArgs, appendRenderProvenanceArgs, readRenderProvenance, PROVENANCE_RENDERER_TAG, PROVENANCE_VERSION_TAG, PROVENANCE_RENDERER_NAME, PROVENANCE_VERSION, } from "./utils/renderProvenance.js";
 export { DrawElementCaptureError, isDrawElementCaptureError, } from "./services/drawElementCaptureError.js";
-//# sourceMappingURL=index.js.map

package/dist/services/__fixtures__/jpeg.d.ts

@@ -1,2 +1 @@
 export declare const validJpeg: Buffer<ArrayBuffer>;
-//# sourceMappingURL=jpeg.d.ts.map

package/dist/services/__fixtures__/jpeg.js

@@ -1,3 +1,2 @@
 // A 64x64 JPEG encoded by FFmpeg; contains real DQT, DHT, SOF and scan data.
 export const validJpeg = Buffer.from("/9j/4AAQSkZJRgABAgAAAQABAAD//gAQTGF2YzYyLjI4LjEwMQD/2wBDAAgEBAQEBAUFBQUFBQYGBgYGBgYGBgYGBgYHBwcICAgHBwcGBgcHCAgICAkJCQgICAgJCQoKCgwMCwsODg4RERT/xABNAAEBAAAAAAAAAAAAAAAAAAAABgEBAQEAAAAAAAAAAAAAAAAAAAYHEAEAAAAAAAAAAAAAAAAAAAAAEQEAAAAAAAAAAAAAAAAAAAAA/8AAEQgAQABAAwEiAAIRAAMRAP/aAAwDAQACEQMRAD8AiwEm38AAAAAAAAAAAAAAAAAAAAAAAAAAAAAB/9k=", "base64");
-//# sourceMappingURL=jpeg.js.map

package/dist/services/audioFxRender.d.ts

@@ -75,4 +75,3 @@ export declare function applyAudioFxChain(inputWav: string, chain: HfAudioFxChai
     envelopeBaked: boolean;
 }>;
 export type { HfAudioFxChain, HfAutomation };
-//# sourceMappingURL=audioFxRender.d.ts.map

package/dist/services/audioFxRender.js

@@ -398,4 +398,3 @@ function envelopeWalkerFor(envelope) {
         return null;
     return createEnvelopeWalker(envelope.keyframes, envelope.trackStart, envelope.baseVolume);
 }
-//# sourceMappingURL=audioFxRender.js.map

package/dist/services/audioMixer.d.ts

@@ -41,4 +41,3 @@ export declare function volumeLaneKeyframes(automation: {
 }, trackStart: number, duration: number): AudioVolumeKeyframe[] | null;
 export declare function parseAudioElements(html: string): AudioElement[];
 export declare function processCompositionAudio(elements: AudioElement[], baseDir: string, workDir: string, outputPath: string, totalDuration: number, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout" | "audioGain">>, compiledDir?: string): Promise<MixResult>;
-//# sourceMappingURL=audioMixer.d.ts.map

package/dist/services/audioMixer.js

@@ -1320,4 +1320,3 @@ export async function processCompositionAudio(elements, baseDir, workDir, output
         error: [mixResult.error, degradedNote].filter(Boolean).join("; ") || undefined,
     };
 }
-//# sourceMappingURL=audioMixer.js.map

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

@@ -73,4 +73,3 @@ export interface MixResult {
     error?: string;
     failures?: AudioProcessingFailure[];
 }
-//# sourceMappingURL=audioMixer.types.d.ts.map

package/dist/services/audioMixer.types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=audioMixer.types.js.map

package/dist/services/audioVolumeEnvelope.d.ts

@@ -33,4 +33,3 @@ export declare function createEnvelopeWalker(keyframes: AudioVolumeKeyframe[], t
  *   16-bit PCM nor 32-bit float (caller should fall back to the expression path).
  */
 export declare function applyVolumeEnvelopeToWav(wavPath: string, keyframes: AudioVolumeKeyframe[], trackStart: number, baseVolume: number): boolean;
-//# sourceMappingURL=audioVolumeEnvelope.d.ts.map

package/dist/services/audioVolumeEnvelope.js

@@ -150,4 +150,3 @@ export function applyVolumeEnvelopeToWav(wavPath, keyframes, trackStart, baseVol
         }
     }
 }
-//# sourceMappingURL=audioVolumeEnvelope.js.map

package/dist/services/browserLeasePool.d.ts

@@ -50,4 +50,3 @@ export declare class BrowserLeasePool {
     private requestClose;
     private removeLease;
 }
-//# sourceMappingURL=browserLeasePool.d.ts.map

package/dist/services/browserLeasePool.js

@@ -234,4 +234,3 @@ export class BrowserLeasePool {
             this.leasesByBrowser.delete(browser);
     }
 }
-//# sourceMappingURL=browserLeasePool.js.map

package/dist/services/browserManager.d.ts

@@ -119,4 +119,3 @@ export declare class WebGpuUnavailableError extends Error {
  * `page` must be on a secure-context origin, or navigator.gpu always reads absent.
  */
 export declare function assertWebGpuAdapterAvailable(page: Page, requiresWebGpu: boolean, softwareWebGpu?: boolean): Promise<void>;
-//# sourceMappingURL=browserManager.d.ts.map

package/dist/services/browserManager.js

@@ -477,7 +477,7 @@ let _unverifiedHardwareGpuWarned = false;
 function buildUnverifiedHardwareGpuWarning(platform, cause) {
     if (cause === "probe-error") {
         return ("[hyperframes] browserGpuMode=hardware was requested, but the GPU probe could not run, " +
-            "so hardware acceleration is UNVERIFIED — if Chrome falls back to software WebGL the " +
+            "so hardware acceleration is UNVERIFIED. If Chrome falls back to software WebGL the " +
             "capture will run at CPU speed. Honouring the explicit request anyway.\n" +
             "  This is a probe failure, not evidence of a missing GPU: see the " +
             "`browserGpuMode probe → software (probe failed ...)` line above for the underlying " +
@@ -493,7 +493,7 @@ function buildUnverifiedHardwareGpuWarning(platform, cause) {
         : "Check that the host exposes a GPU to this process and that the graphics drivers are " +
             "installed.";
     return ("[hyperframes] browserGpuMode=hardware was requested, but the WebGL probe found no " +
-        "hardware GPU — Chrome will silently fall back to software WebGL and the capture will " +
+        "hardware GPU, so Chrome will silently fall back to software WebGL and the capture will " +
         "run at CPU speed. Honouring the explicit request anyway.\n" +
         `  ${remediation}\n` +
         "  Pass --no-browser-gpu to select deterministic SwiftShader instead of waiting on a " +
@@ -874,4 +874,3 @@ function getBrowserGpuArgs(mode, platform) {
             return ["--enable-gpu-rasterization"];
     }
 }
-//# sourceMappingURL=browserManager.js.map

package/dist/services/captureFailure.d.ts

@@ -24,4 +24,3 @@ export declare function classifyCaptureFailure(error: unknown, options?: {
 export declare function isTransientBrowserError(error: unknown): boolean;
 export declare function isMemoryExhaustionError(error: unknown): boolean;
 export declare function isFatalCaptureFailure(failure: CaptureFailure): boolean;
-//# sourceMappingURL=captureFailure.d.ts.map

package/dist/services/captureFailure.js

@@ -147,4 +147,3 @@ export function isMemoryExhaustionError(error) {
 export function isFatalCaptureFailure(failure) {
     return !["cancelled", "transient_browser", "protocol_timeout"].includes(failure.kind);
 }
-//# sourceMappingURL=captureFailure.js.map

package/dist/services/captureWarning.d.ts

@@ -2,4 +2,3 @@ import type { CaptureWarning } from "../types.js";
 /** Clone every mutable field before a warning crosses an async or ownership boundary. */
 export declare function cloneCaptureWarning<T extends CaptureWarning>(warning: T): T;
 export declare function cloneCaptureWarnings<T extends CaptureWarning>(warnings: readonly T[]): T[];
-//# sourceMappingURL=captureWarning.d.ts.map

package/dist/services/captureWarning.js

@@ -19,4 +19,3 @@ export function cloneCaptureWarning(warning) {
 export function cloneCaptureWarnings(warnings) {
     return warnings.map(cloneCaptureWarning);
 }
-//# sourceMappingURL=captureWarning.js.map

package/dist/services/chromeHostCeiling.d.ts

@@ -2,4 +2,3 @@
 export declare function chromeMajorCeiling(hostPlatform?: string, hostRelease?: string): number | undefined;
 /** True when a cache dir name (`mac-152.0.1.2`) or build id (`152.0.1.2`) is newer than the ceiling. */
 export declare function exceedsChromeCeiling(versionName: string, ceiling: number | undefined): boolean;
-//# sourceMappingURL=chromeHostCeiling.d.ts.map

package/dist/services/chromeHostCeiling.js

@@ -14,4 +14,3 @@ export function exceedsChromeCeiling(versionName, ceiling) {
     const major = Number.parseInt(versionName.slice(versionName.indexOf("-") + 1), 10);
     return major > ceiling;
 }
-//# sourceMappingURL=chromeHostCeiling.js.map

package/dist/services/chromeMemorySampler.d.ts

@@ -52,4 +52,3 @@ export interface ChromeMemorySampler {
 export declare function mergeSample(prev: ChromeMemoryStats, pids: ChromePids, rss: readonly ProcessRssSample[]): ChromeMemoryStats;
 export declare function createChromeMemorySampler(deps: ChromeMemorySamplerDeps): ChromeMemorySampler;
 export {};
-//# sourceMappingURL=chromeMemorySampler.d.ts.map

package/dist/services/chromeMemorySampler.js

@@ -82,4 +82,3 @@ export function createChromeMemorySampler(deps) {
         sampleOnce,
     };
 }
-//# sourceMappingURL=chromeMemorySampler.js.map

package/dist/services/chunkEncoder.d.ts

@@ -139,4 +139,3 @@ export interface PackageHlsOptions extends Partial<Pick<EngineConfig, "ffmpegPro
  */
 export declare function packageHls(videoPath: string, audioPath: string | null, outputDir: string, options: PackageHlsOptions): Promise<MuxResult>;
 export declare function applyFaststart(inputPath: string, outputPath: string, signal?: AbortSignal, config?: Partial<Pick<EngineConfig, "ffmpegProcessTimeout">>, fps?: Fps, onSecondsWritten?: (seconds: number) => void): Promise<MuxResult>;
-//# sourceMappingURL=chunkEncoder.d.ts.map

package/dist/services/chunkEncoder.js

@@ -804,4 +804,3 @@ export async function applyFaststart(inputPath, outputPath, signal, config, fps,
         failureReason: result.failureReason,
     };
 }
-//# sourceMappingURL=chunkEncoder.js.map

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

@@ -61,4 +61,3 @@ export interface MuxResult {
     /** Stable machine-readable cause for failures safe to retry on a fresh host. */
     failureReason?: "external_interruption";
 }
-//# sourceMappingURL=chunkEncoder.types.d.ts.map

package/dist/services/chunkEncoder.types.js

@@ -1,2 +1 @@
 export {};
-//# sourceMappingURL=chunkEncoder.types.js.map

package/dist/services/drawElementCaptureError.d.ts

@@ -5,4 +5,3 @@ export declare class DrawElementCaptureError extends Error {
 }
 /** Structural matching survives engine/producer copies and worker error wrappers. */
 export declare function isDrawElementCaptureError(error: unknown): boolean;
-//# sourceMappingURL=drawElementCaptureError.d.ts.map

package/dist/services/drawElementCaptureError.js

@@ -19,4 +19,3 @@ export function isDrawElementCaptureError(error) {
     }
     return false;
 }
-//# sourceMappingURL=drawElementCaptureError.js.map

package/dist/services/drawElementService.d.ts

@@ -205,4 +205,3 @@ export declare function produceDrawElementFrameBatch(page: Page, times: number[]
     failedAt: number | null;
     error?: string;
 }>;
-//# sourceMappingURL=drawElementService.d.ts.map

package/dist/services/drawElementService.js

@@ -578,7 +578,7 @@ export async function initDrawElementWorkerEncode(page) {
         // frame's id so the node-side promise rejects instead of hanging.
         const workerSrc = `
       // Reuse one OffscreenCanvas across frames (dimensions are constant for a
-      // render) — a fresh canvas per frame churns ~w*h*4 bytes of backing store
+      // render): a fresh canvas per frame churns ~w*h*4 bytes of backing store
       // every frame and pressures GC on the encode hot path.
       let oc = null, c = null;
       self.onmessage = async (e) => {
@@ -1066,4 +1066,3 @@ export async function produceDrawElementFrameBatch(page, times, width, height, q
     }
     return { encodeResults, failedAt: outcome.failedAt, error: outcome.error };
 }
-//# sourceMappingURL=drawElementService.js.map

package/dist/services/extractedFrameIndex.d.ts

@@ -5,4 +5,3 @@ export declare class ExtractedFrameSequenceError extends Error {
 }
 export declare function extractedFrameIndex(file: string, format: ExtractedFrameFormat): number;
 export declare function framePathsFromDirectory(outputDir: string, format: ExtractedFrameFormat, allowGaps?: boolean): Map<number, string>;
-//# sourceMappingURL=extractedFrameIndex.d.ts.map

package/dist/services/extractedFrameIndex.js

@@ -42,4 +42,3 @@ export function framePathsFromDirectory(outputDir, format, allowGaps = false) {
     }
     return ordered;
 }
-//# sourceMappingURL=extractedFrameIndex.js.map

package/dist/services/extractionCache.d.ts

@@ -64,6 +64,8 @@ export interface CacheKeyInput {
     format: CacheFrameFormat;
     /** Optional source transform applied during extraction. */
     transform?: string;
+    /** SHA-256 of the source bytes, in place of path and mtime (downloaded media gets new ones each render). */
+    contentSha256?: string;
 }
 export interface CacheEntry {
     /** Absolute path to the cache entry directory. */
@@ -82,6 +84,7 @@ export interface CachePublishResult {
     dir: string;
     published: boolean;
 }
+export declare function readContentSha256(path: string, signal?: AbortSignal): Promise<string | null>;
 /**
  * Read `(mtimeMs, size)` for a path. Returns `null` if the file is missing —
  * callers should skip the cache path for that entry so the extractor surfaces
@@ -207,4 +210,3 @@ export interface RehydratedFrames {
     framePaths: Map<number, string>;
 }
 export declare function rehydrateCacheEntry(entry: CacheEntry, options: RehydrateOptions): RehydratedFrames;
-//# sourceMappingURL=extractionCache.d.ts.map

package/dist/services/extractionCache.js

@@ -32,7 +32,7 @@
  * become inert and can be gc'd by the caller.
  */
 import { createHash, randomUUID } from "node:crypto";
-import { existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
+import { createReadStream, existsSync, lstatSync, mkdirSync, readdirSync, renameSync, rmSync, statSync, utimesSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { FRAME_FILENAME_PREFIX, framePathsFromDirectory } from "./extractedFrameIndex.js";
 /** Filename prefix for extracted frames. Shared with the extractor. */
@@ -48,6 +48,17 @@ export const GC_MARKER = ".hf-last-gc";
 export const SCHEMA_PREFIX = "hfcache-v6-";
 /** Truncated hex chars of SHA-256 used for the entry directory name. */
 const KEY_HEX_CHARS = 16;
+export async function readContentSha256(path, signal) {
+    try {
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(path, { signal }))
+            hash.update(chunk);
+        return hash.digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
 /**
  * Read `(mtimeMs, size)` for a path. Returns `null` if the file is missing —
  * callers should skip the cache path for that entry so the extractor surfaces
@@ -66,9 +77,12 @@ export function readKeyStat(videoPath) {
 }
 function canonicalKeyBlob(input) {
     const durationForKey = Number.isFinite(input.duration) ? input.duration : -1;
+    // Identity first, so keys of path-keyed entries stay byte-identical.
+    const identity = input.contentSha256 !== undefined
+        ? { c: input.contentSha256 }
+        : { p: input.videoPath, m: input.mtimeMs };
     const blob = {
-        p: input.videoPath,
-        m: input.mtimeMs,
+        ...identity,
         s: input.size,
         ms: input.mediaStart,
         d: durationForKey,
@@ -402,4 +416,3 @@ export function rehydrateCacheEntry(entry, options) {
         framePaths,
     };
 }
-//# sourceMappingURL=extractionCache.js.map

package/dist/services/fileServer.d.ts

@@ -22,4 +22,3 @@ export interface FileServerHandle {
     close: () => void;
 }
 export declare function createFileServer(options: FileServerOptions): Promise<FileServerHandle>;
-//# sourceMappingURL=fileServer.d.ts.map

package/dist/services/fileServer.js

@@ -128,4 +128,3 @@ export function createFileServer(options) {
         });
     });
 }
-//# sourceMappingURL=fileServer.js.map

package/dist/services/frameCapture.d.ts

@@ -20,6 +20,8 @@ export type { CaptureOptions, CaptureResult, CaptureBufferResult, CapturePerfSum
  * `heldVideoTime` (motion-blur samples only) is the output frame's time: a video on screen at
  * both times shows its frame for `heldVideoTime`, so footage does not smear. */
 export type BeforeCaptureHook = (page: Page, time: number, heldVideoTime?: number) => Promise<void>;
+/** The per-frame wait a capture is in, worded for the stall error a user reads. */
+type CaptureStep = "seeking the timeline" | "decoding CSS background images" | "injecting video frames" | "waiting for page seek handlers" | "loading color-grading LUTs" | "compositing the page" | "capturing the frame";
 export interface CaptureSession {
     browser: Browser;
     /** Exact ownership token for this browser acquisition. */
@@ -202,6 +204,7 @@ export interface CaptureSession {
      * retries via screenshot.
      */
     deFrameTimeouts?: number;
+    captureStep?: CaptureStep;
     /**
      * drawElement init passed every gate but stopped before verification +
      * canvas injection: the session has no video-frame injector yet (probe
@@ -386,7 +389,7 @@ export declare function formatConsoleDiagnostic(type: string, text: string, loca
     text: string;
     suppressHostLog: boolean;
 };
-export declare const HF_READY_DIAGNOSTIC_EXPR = "(async function() {\n  var hf = window.__hf;\n  var player = window.__player;\n  var renderReady = !!window.__renderReady;\n  var hasSeek = !!(hf && typeof hf.seek === \"function\");\n  var duration = hf ? hf.duration : -1;\n  var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);\n  var root = document.querySelector(\"[data-composition-id]\");\n  var declaredDuration = root ? Number(root.getAttribute(\"data-duration\")) : -1;\n  var registry = (window.__hf && window.__hf.buildReady) || {};\n  var keys = Object.keys(registry);\n  // A microtask race mis-sorts a non-native thenable (extra adoption tick)\n  // and rejects the whole expression on a rejected entry. Settling each\n  // key onto its own record and waiting one macrotask avoids both.\n  var settled = {};\n  if (keys.length > 0) {\n    keys.forEach(function(key) {\n      Promise.resolve(registry[key]).then(\n        function() { settled[key] = \"resolved\"; },\n        function() { settled[key] = \"rejected\"; },\n      );\n    });\n    await new Promise(function(r) { setTimeout(r, 0); });\n  }\n  // A thenable resolving via its own setTimeout(0) can still misreport as\n  // pending here (macrotask registration order, not resolution order) \u2014 a\n  // narrow case that self-corrects on the next ~1s diagnostic tick.\n  var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });\n  var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === \"rejected\"; });\n  return {\n    renderReady: renderReady,\n    hasHf: !!hf,\n    hasSeek: hasSeek,\n    hasPlayer: !!player,\n    duration: duration,\n    hasTimeline: hasTimeline,\n    declaredDuration: declaredDuration,\n    pendingBuildReadyKeys: pendingBuildReadyKeys,\n    rejectedBuildReadyKeys: rejectedBuildReadyKeys,\n  };\n})()";
+export declare const HF_READY_DIAGNOSTIC_EXPR = "(async function() {\n  var hf = window.__hf;\n  var player = window.__player;\n  var renderReady = !!window.__renderReady;\n  var hasSeek = !!(hf && typeof hf.seek === \"function\");\n  var duration = hf ? hf.duration : -1;\n  var hasTimeline = !!(window.__timelines && Object.keys(window.__timelines).length > 0);\n  var root = document.querySelector(\"[data-composition-id]\");\n  var declaredDuration = root ? Number(root.getAttribute(\"data-duration\")) : -1;\n  var registry = (window.__hf && window.__hf.buildReady) || {};\n  var keys = Object.keys(registry);\n  // A microtask race mis-sorts a non-native thenable (extra adoption tick)\n  // and rejects the whole expression on a rejected entry. Settling each\n  // key onto its own record and waiting one macrotask avoids both.\n  var settled = {};\n  if (keys.length > 0) {\n    keys.forEach(function(key) {\n      Promise.resolve(registry[key]).then(\n        function() { settled[key] = \"resolved\"; },\n        function() { settled[key] = \"rejected\"; },\n      );\n    });\n    await new Promise(function(r) { setTimeout(r, 0); });\n  }\n  // A thenable resolving via its own setTimeout(0) can still misreport as\n  // pending here (macrotask registration order, not resolution order), a\n  // narrow case that self-corrects on the next ~1s diagnostic tick.\n  var pendingBuildReadyKeys = keys.filter(function(key) { return !settled[key]; });\n  var rejectedBuildReadyKeys = keys.filter(function(key) { return settled[key] === \"rejected\"; });\n  return {\n    renderReady: renderReady,\n    hasHf: !!hf,\n    hasSeek: hasSeek,\n    hasPlayer: !!player,\n    duration: duration,\n    hasTimeline: hasTimeline,\n    declaredDuration: declaredDuration,\n    pendingBuildReadyKeys: pendingBuildReadyKeys,\n    rejectedBuildReadyKeys: rejectedBuildReadyKeys,\n  };\n})()";
 export interface HfDiagnostic {
     renderReady: boolean;
     hasHf: boolean;
@@ -399,6 +402,7 @@ export interface HfDiagnostic {
     rejectedBuildReadyKeys: string[];
 }
 export declare function buildZeroDurationDiagnostic(diag: HfDiagnostic): string;
+export declare function pollHfReady(page: Page, timeoutMs: number, intervalMs?: number): Promise<void>;
 export declare function waitForSubCompositionTimelines(session: CaptureSession, page: Page, timeoutMs: number): Promise<void>;
 export interface SubTimelinePollOptions {
     intervalMs?: number;
@@ -752,4 +756,3 @@ export declare function computeDeVerifySampleFractions(k: number): number[];
  */
 export declare function percentileOf(samples: number[], p: number): number;
 export declare function getCapturePerfSummary(session: CaptureSession): CapturePerfSummary;
-//# sourceMappingURL=frameCapture.d.ts.map