supervision 0.2.0-next.0 → 0.2.0-next.2

package/dist/web-video-engine/analysis.js

@@ -1,5 +1,5 @@
 import { CanvasSink, EncodedPacketSink, Input, ALL_FORMATS, VideoSampleSink, ReadableStreamSource, BlobSource, UrlSource, UnsupportedInputFormatError } from 'mediabunny';
-import { V as VideoEngineError, a as VideoEngineErrorCode, S as SCRUB, b as asSec, n as nativeResolution, r as resolveDecodeDimensions, c as SourceKind, F as FRAME_TIMELINE, d as FrameTimeline } from './frame-timeline-GINI8Gum.js';
+import { W as WebVideoEngineError, a as WebVideoEngineErrorCode, S as SCRUB, b as asSec, n as nativeResolution, r as resolveDecodeDimensions, c as SourceKind, F as FRAME_TIMELINE, d as FrameTimeline } from './frame-timeline-DreEwsRY.js';
 
 /**
  * An H.264 sync sample that is not an IDR frame cannot open a WebCodecs decode
@@ -372,13 +372,19 @@ class DecodeSession {
     epoch = 0;
     outputTimeoutMs;
     rotation;
+    outputWidth;
+    outputHeight;
+    snapshotFrame;
     constructor(options) {
         this.options = options;
         this.outputTimeoutMs = options.outputTimeoutMs ?? OUTPUT_TIMEOUT_MS;
         this.rotation = options.rotation;
+        this.outputWidth = options.outputWidth;
+        this.outputHeight = options.outputHeight;
+        this.snapshotFrame = options.snapshotFrame ?? createVideoFrameSnapshotter();
         const prefixWidth = drivablePrefixWidth(options.config);
         if (prefixWidth === null) {
-            throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `DecodeSession: ${options.config.codec} is not AVCC-framed H.264`);
+            throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, `DecodeSession: ${options.config.codec} is not AVCC-framed H.264`);
         }
         this.prefixWidth = prefixWidth;
         this.keyPacket = new KeyPacketRequirement(prefixWidth);
@@ -402,6 +408,19 @@ class DecodeSession {
             return queued.timestampS;
         return this.reachable;
     }
+    async resizeOutput({ width, height }) {
+        await this.exclusive(async () => {
+            if (this.closed || this.outputWidth === undefined)
+                return;
+            if (this.outputWidth === width && this.outputHeight === height)
+                return;
+            this.quiesce();
+            this.outputWidth = width;
+            this.outputHeight = height;
+            this.exhausted = true;
+            this.epoch++;
+        });
+    }
     /** The frame at or before `targetS`, or null when nothing precedes it. */
     async frameAt(targetS) {
         const landed = await this.exclusive(() => this.land(targetS));
@@ -793,11 +812,11 @@ class DecodeSession {
                 // full pipeline of requests with nothing at all may never have been
                 // given a legal place to start, which is the anchor's to answer for.
                 if (this.framesDecodedCount === 0) {
-                    this.anchorError ??= new VideoEngineError(VideoEngineErrorCode.DecoderStalled, `DecodeSession: the decoder acknowledged ${owed} decode requests and produced no frame`);
+                    this.anchorError ??= new WebVideoEngineError(WebVideoEngineErrorCode.DecoderStalled, `DecodeSession: the decoder acknowledged ${owed} decode requests and produced no frame`);
                     resolve();
                     return;
                 }
-                reject(new VideoEngineError(VideoEngineErrorCode.BackendCrashed, `DecodeSession: decoder produced no output in ${this.outputTimeoutMs}ms with ${owed} chunks in flight`));
+                reject(new WebVideoEngineError(WebVideoEngineErrorCode.BackendCrashed, `DecodeSession: decoder produced no output in ${this.outputTimeoutMs}ms with ${owed} chunks in flight`));
             }, this.outputTimeoutMs);
             this.wake = () => {
                 this.wake = null;
@@ -836,20 +855,38 @@ class DecodeSession {
             frame.close();
             return;
         }
-        this.decoded.push({ frame, ...timing });
+        let stable = frame;
+        if (this.outputWidth !== undefined && this.outputHeight !== undefined) {
+            try {
+                stable = this.snapshotFrame(frame, this.outputWidth, this.outputHeight);
+            }
+            catch (error) {
+                this.stall("could not own decoder output pixels", error);
+                this.wake?.();
+                return;
+            }
+            finally {
+                frame.close();
+            }
+        }
+        this.decoded.push({
+            frame: stable,
+            ...timing,
+            independentPixels: stable !== frame,
+        });
         this.wake?.();
     }
     fail(from, error) {
         if (from !== this.decoder)
             return;
-        this.anchorError ??= new VideoEngineError(VideoEngineErrorCode.DecoderStalled, "DecodeSession: the decoder reported an error", error);
+        this.anchorError ??= new WebVideoEngineError(WebVideoEngineErrorCode.DecoderStalled, "DecodeSession: the decoder reported an error", error);
         this.wake?.();
     }
     /** Latches the terminal failure and returns it. First writer wins, so the
      *  cause a caller is handed is the one that started the failure rather than
      *  whichever consequence surfaced last. */
     stall(what, cause) {
-        return this.latch(new VideoEngineError(VideoEngineErrorCode.DecoderStalled, `DecodeSession: ${what}`, cause));
+        return this.latch(new WebVideoEngineError(WebVideoEngineErrorCode.DecoderStalled, `DecodeSession: ${what}`, cause));
     }
     latch(error) {
         this.stalledError ??= error;
@@ -861,14 +898,29 @@ class DecodeSession {
         this.decoded.length = 0;
     }
 }
+function createVideoFrameSnapshotter() {
+    return (frame, width, height) => {
+        const canvas = new OffscreenCanvas(width, height);
+        const context = canvas.getContext("2d", { alpha: false });
+        if (!context)
+            throw new Error("2D canvas unavailable for frame snapshot");
+        context.drawImage(frame, 0, 0, width, height);
+        context.getImageData(0, 0, 1, 1);
+        return new VideoFrame(canvas, {
+            timestamp: frame.timestamp,
+            ...(frame.duration === null ? {} : { duration: frame.duration }),
+        });
+    };
+}
 /** A decoded frame in the runtime's own sample vocabulary, so a session frame
  *  and a VideoSampleSink frame reach the renderer the same way. */
-function videoFrameSample({ frame, timestampS, durationS }, rotation) {
+function videoFrameSample({ frame, timestampS, durationS, independentPixels }, rotation) {
     const quarterTurn = rotation % 180 !== 0;
     return {
         timestamp: timestampS,
         duration: durationS,
         rotation,
+        ...(independentPixels ? { independentPixels: true } : {}),
         toVideoFrame: () => frame.clone(),
         draw: (ctx, dx, dy, dWidth, dHeight) => {
             drawRotated(ctx, frame, rotation, dx, dy, dWidth ?? (quarterTurn ? frame.displayHeight : frame.displayWidth), dHeight ?? (quarterTurn ? frame.displayWidth : frame.displayHeight));
@@ -894,6 +946,7 @@ function idempotentSample(sample) {
     let closed = false;
     return {
         toVideoFrame: () => sample.toVideoFrame(),
+        independentPixels: sample.independentPixels,
         rotation: sample.rotation,
         draw: (ctx, dx, dy, dWidth, dHeight) => sample.draw(ctx, dx, dy, dWidth, dHeight),
         close: () => {
@@ -911,6 +964,115 @@ function idempotentSample(sample) {
     };
 }
 
+function sampleAtPresentationTime(sample, timestamp) {
+    const owned = idempotentSample(sample);
+    return {
+        toVideoFrame: () => owned.toVideoFrame(),
+        independentPixels: owned.independentPixels,
+        rotation: owned.rotation,
+        draw: (ctx, dx, dy, dWidth, dHeight) => owned.draw(ctx, dx, dy, dWidth, dHeight),
+        close: () => owned.close(),
+        timestamp,
+        duration: owned.duration,
+    };
+}
+function presentationCanvasSource(source, timeline) {
+    const wrap = (frame) => frame
+        ? {
+            canvas: frame.canvas,
+            timestamp: timeline.fromSourceTime(frame.timestamp),
+        }
+        : null;
+    return {
+        async getCanvas(timestampS) {
+            return wrap(await source.getCanvas(timeline.toSourceTime(timestampS)));
+        },
+        async *canvases(startS) {
+            for await (const frame of source.canvases(timeline.toSourceTime(startS))) {
+                yield wrap(frame);
+            }
+        },
+        async *canvasesAtTimestamps(timestamps) {
+            const sourceTimestamps = Array.from(timestamps, (timestamp) => timeline.toSourceTime(timestamp));
+            for await (const frame of source.canvasesAtTimestamps(sourceTimestamps)) {
+                yield wrap(frame);
+            }
+        },
+    };
+}
+function presentationSampleSource(source, timeline) {
+    const wrap = (sample) => sample
+        ? sampleAtPresentationTime(sample, timeline.fromSourceTime(sample.timestamp))
+        : null;
+    return {
+        async getSample(timestampS) {
+            return wrap(await source.getSample(timeline.toSourceTime(timestampS)));
+        },
+        async *samples(startS) {
+            for await (const sample of source.samples(timeline.toSourceTime(startS))) {
+                yield wrap(sample);
+            }
+        },
+        async *samplesAtTimestamps(timestamps) {
+            const sourceTimestamps = Array.from(timestamps, (timestamp) => timeline.toSourceTime(timestamp));
+            for await (const sample of source.samplesAtTimestamps(sourceTimestamps)) {
+                yield wrap(sample);
+            }
+        },
+    };
+}
+function presentationSessionSource(source, timeline) {
+    const wrap = (sample) => sample
+        ? sampleAtPresentationTime(sample, timeline.fromSourceTime(sample.timestamp))
+        : null;
+    return {
+        ...(source.resizeOutput
+            ? { resizeOutput: source.resizeOutput.bind(source) }
+            : {}),
+        async frameAt(targetS) {
+            return wrap(await source.frameAt(timeline.toSourceTime(targetS)));
+        },
+        async *framesFrom(startS) {
+            for await (const sample of source.framesFrom(timeline.toSourceTime(startS))) {
+                yield wrap(sample);
+            }
+        },
+        async *framesCovering(startS, endS) {
+            for await (const sample of source.framesCovering(timeline.toSourceTime(startS), timeline.toSourceTime(endS))) {
+                yield wrap(sample);
+            }
+        },
+        get reachableFromS() {
+            return source.reachableFromS === -Infinity
+                ? -Infinity
+                : timeline.fromSourceTime(source.reachableFromS);
+        },
+        get framesDecoded() {
+            return source.framesDecoded;
+        },
+    };
+}
+function presentationKeyframeProbe(source, timeline) {
+    const sourcePackets = new WeakMap();
+    const wrap = (packet) => {
+        if (!packet)
+            return null;
+        const mapped = {
+            timestamp: timeline.fromSourceTime(packet.timestamp),
+        };
+        sourcePackets.set(mapped, packet);
+        return mapped;
+    };
+    return {
+        async getKeyPacket(timestamp, options) {
+            return wrap(await source.getKeyPacket(timeline.toSourceTime(timestamp), options));
+        },
+        async getNextKeyPacket(packet, options) {
+            const sourcePacket = sourcePackets.get(packet) ?? packet;
+            return wrap(await source.getNextKeyPacket(sourcePacket, options));
+        },
+    };
+}
 /**
  * Opens a source on the CanvasSink path, the one every decodable source
  * supports. Track facts are resolved here too, so the consumer receives a fully
@@ -962,14 +1124,15 @@ function canvasHandle(opened, poolSize) {
     // canvas the frame is drawn into; it does NOT reduce decode cost. The codec
     // decodes the full coded frame regardless, and CanvasSink resizes after, so
     // the win is paint work and cached-blit memory, not decode throughput.
-    const sink = new CanvasSink(opened.videoTrack, {
+    const source = new CanvasSink(opened.videoTrack, {
         poolSize,
         width: opened.track.decodeWidth,
     });
+    const { timeline } = opened.track;
     return {
         track: opened.track,
-        sink,
-        keyframeProbe: new EncodedPacketSink(opened.videoTrack),
+        sink: presentationCanvasSource(source, timeline),
+        keyframeProbe: presentationKeyframeProbe(new EncodedPacketSink(opened.videoTrack), timeline),
         dispose: async () => {
             opened.input.dispose();
         },
@@ -977,11 +1140,12 @@ function canvasHandle(opened, poolSize) {
 }
 /** The zero-copy sample path: a VideoSampleSink in place of the CanvasSink. It
  *  takes no width, so frames arrive at the source's own dimensions. */
-function sampleHandle(opened) {
+function sampleHandle(opened, optimizeForLatency = false) {
+    const { timeline } = opened.track;
     return {
         track: opened.track,
-        sampleSink: new VideoSampleSink(opened.videoTrack),
-        keyframeProbe: new EncodedPacketSink(opened.videoTrack),
+        sampleSink: presentationSampleSource(new VideoSampleSink(opened.videoTrack, optimizeForLatency ? { optimizeForLatency: true } : undefined), timeline),
+        keyframeProbe: presentationKeyframeProbe(new EncodedPacketSink(opened.videoTrack), timeline),
         dispose: async () => {
             opened.input.dispose();
         },
@@ -997,16 +1161,24 @@ function sampleHandle(opened) {
  */
 function sessionHandle(opened, config) {
     const packets = new EncodedPacketSink(opened.videoTrack);
+    const ownDecoderOutputPixels = detectDecodeSessionPixelOwnership();
     const session = new DecodeSession({
         packets,
         config,
         createDecoder: webCodecsDecoder,
         rotation: opened.track.rotation,
+        ...(ownDecoderOutputPixels
+            ? {
+                outputHeight: opened.track.decodeHeight,
+                outputWidth: opened.track.decodeWidth,
+            }
+            : {}),
     });
+    const { timeline } = opened.track;
     return {
         track: opened.track,
-        session,
-        keyframeProbe: packets,
+        session: presentationSessionSource(session, timeline),
+        keyframeProbe: presentationKeyframeProbe(packets, timeline),
         dispose: async () => {
             session.close();
             opened.input.dispose();
@@ -1051,7 +1223,7 @@ async function openInput(options) {
     const videoTrack = await resolveVideoTrack(input);
     if (!(await videoTrack.canDecode())) {
         const decoderConfig = await videoTrack.getDecoderConfig();
-        throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `openInput: browser cannot decode this video track's codec ${decoderConfig?.codec ?? "(unknown)"}`);
+        throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, `openInput: browser cannot decode this video track's codec ${decoderConfig?.codec ?? "(unknown)"}`);
     }
     const displayWidth = videoTrack.displayWidth;
     const displayHeight = videoTrack.displayHeight;
@@ -1100,7 +1272,7 @@ async function resolveVideoTrack(input) {
     }
     catch (error) {
         if (error instanceof UnsupportedInputFormatError) {
-            throw new VideoEngineError(VideoEngineErrorCode.ContainerUnreadable, "openInput: the demuxer does not read this file's container", error);
+            throw new WebVideoEngineError(WebVideoEngineErrorCode.ContainerUnreadable, "openInput: the demuxer does not read this file's container", error);
         }
         throw error;
     }
@@ -1108,8 +1280,8 @@ async function resolveVideoTrack(input) {
         return videoTrack;
     const tracks = await input.getTracks();
     throw tracks.length === 0
-        ? new VideoEngineError(VideoEngineErrorCode.VideoTrackUnreadable, "openInput: the container opened and the demuxer parsed no track out of it")
-        : new VideoEngineError(VideoEngineErrorCode.NoVideoTrack, "openInput: the container's tracks read and none of them carries video");
+        ? new WebVideoEngineError(WebVideoEngineErrorCode.VideoTrackUnreadable, "openInput: the container opened and the demuxer parsed no track out of it")
+        : new WebVideoEngineError(WebVideoEngineErrorCode.NoVideoTrack, "openInput: the container's tracks read and none of them carries video");
 }
 /**
  * Walks the track's packets metadata-only and records each one's timestamp in
@@ -1134,7 +1306,7 @@ async function readFrameTimeline(videoTrack) {
     })) {
         const at = Math.round(packet.timestamp * tickRate);
         if (ticks.length >= FRAME_TIMELINE.MAX_FRAMES) {
-            throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `openInput: source video track carries more than ${FRAME_TIMELINE.MAX_FRAMES} frames`);
+            throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, `openInput: source video track carries more than ${FRAME_TIMELINE.MAX_FRAMES} frames`);
         }
         ticks.push(at);
         if (at >= lastTicks) {
@@ -1143,7 +1315,7 @@ async function readFrameTimeline(videoTrack) {
         }
     }
     if (ticks.length === 0) {
-        throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, "openInput: source video track has no frames");
+        throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, "openInput: source video track has no frames");
     }
     ticks.sort((a, b) => a - b);
     return FrameTimeline.from({
@@ -1152,6 +1324,23 @@ async function readFrameTimeline(videoTrack) {
         ticks: Float64Array.from(ticks),
     });
 }
+function shouldOwnDecodeSessionPixels(context) {
+    if (!context.offscreenCanvasAvailable)
+        return false;
+    const clientPlatform = context.clientPlatform?.trim();
+    if (clientPlatform)
+        return clientPlatform.toLowerCase() === "android";
+    return /\bAndroid\b/i.test(context.userAgent ?? "");
+}
+function detectDecodeSessionPixelOwnership() {
+    const navigator = globalThis.navigator;
+    return shouldOwnDecodeSessionPixels({
+        clientPlatform: navigator?.userAgentData?.platform,
+        offscreenCanvasAvailable: typeof globalThis.OffscreenCanvas ===
+            "function",
+        userAgent: navigator?.userAgent,
+    });
+}
 /**
  * The gate. The session reaches a non-IDR anchor by declaring it a recovery
  * point, which only holds for AVCC-framed H.264 carrying its parameter sets, so
@@ -1675,4 +1864,3 @@ class FrameWalker {
 }
 
 export { AnalysisSession, FrameExtractor, FrameWalker, walkFrames };
-//# sourceMappingURL=analysis.js.map

package/dist/web-video-engine/cache-budget.d.ts

@@ -16,4 +16,3 @@ export interface CacheBudgets {
  * small 16:9 one.
  */
 export declare function resolveCacheBudgets(decodeWidth: number, decodeHeight: number, previewWidth: number): CacheBudgets;
-//# sourceMappingURL=cache-budget.d.ts.map

package/dist/web-video-engine/canvas-sink-scrub-cursor.d.ts

@@ -1,5 +1,6 @@
 import { type AnySourceHandle } from "./decode-source";
 import type { FrameId } from "./frame-timeline";
+import type { DecodeDimensions } from "./decode-resolution";
 import { type ScrubCursor, ScrubCursorState, type ScrubFrame, type ScrubFrameListener, type ScrubTrackInfo } from "./scrub-cursor";
 import { type Sec } from "./types";
 /**
@@ -23,7 +24,9 @@ import { type Sec } from "./types";
  */
 export declare class CanvasSinkScrubCursor implements ScrubCursor {
     private readonly provider;
-    private readonly trackInfo;
+    private trackInfo;
+    private outputGeneration;
+    private readonly outputReads;
     private readonly disposeSource;
     /**
      * Forward-playback iterator. Lives only between attachPlay and detachPlay so
@@ -50,6 +53,8 @@ export declare class CanvasSinkScrubCursor implements ScrubCursor {
     get state(): ScrubCursorState;
     get track(): ScrubTrackInfo;
     get isIdle(): boolean;
+    resizeOutput({ width, height }: DecodeDimensions): Promise<boolean>;
+    private trackOutputRead;
     open(): Promise<void>;
     /** No cache to read; the scheduler is the caching backend. */
     peekCached(): ScrubFrame | null;
@@ -87,4 +92,3 @@ export declare class CanvasSinkScrubCursor implements ScrubCursor {
     private flushIdleResolvers;
     private flushSettleResolvers;
 }
-//# sourceMappingURL=canvas-sink-scrub-cursor.d.ts.map

package/dist/web-video-engine/clock.d.ts

@@ -80,4 +80,3 @@ export declare class AudioContextMediaClock implements MediaClock {
     pause(): void;
     seek(t: number): void;
 }
-//# sourceMappingURL=clock.d.ts.map

package/dist/web-video-engine/constants.d.ts

@@ -231,6 +231,7 @@ export declare const DIAGNOSTICS: {
     readonly TRACE_EVENT_CAP: 2000;
     readonly TRACE_SNAPSHOT_CAP: 600;
     readonly SCRUB_LATENCY_RING: 64;
+    readonly KEYFRAME_TIMESTAMPS_CAP: 512;
 };
 /**
  * What an armed capture actually keeps. The snapshot ring is fed at the fixed
@@ -248,6 +249,13 @@ export declare const HANG_RECOVERY: {
     readonly DECODE_HANG_TIMEOUT_MS: 30000;
     readonly SEED_HANG_TIMEOUT_MS: 8000;
     readonly SEED_DECODE_ATTEMPTS: 3;
+    /**
+     * A movement whose decode settled without a matching crisp paint is ended
+     * here, while the worker can still return its specific failure through the
+     * command channel. The remaining margin belongs to message delivery and
+     * main-thread scheduling; without it the facade replaces the useful verdict
+     * with its generic worker-command timeout.
+     */
+    readonly PRESENTATION_LATCH_TIMEOUT_MS: number;
     readonly WORKER_COMMAND_TIMEOUT_MS: number;
 };
-//# sourceMappingURL=constants.d.ts.map

package/dist/web-video-engine/create-scrub-cursor.d.ts

@@ -1,7 +1,8 @@
 import type { DecodeResolutionStrategy } from "./decode-resolution";
 import type { ScrubCursorFactory } from "./scrub-cursor";
 import type { SourceResidency } from "./source-residency";
-import type { UrlSourceReadConfig, VideoEngineError, VideoSource } from "./types";
+import type { PresentationMode } from "./types";
+import type { UrlSourceReadConfig, WebVideoEngineError, VideoSource } from "./types";
 /** On-screen canvas measurements the decode strategy reasons over. */
 export interface ScrubViewport {
     /** CSS-pixel width of the canvas box, or null when unmeasured. */
@@ -20,6 +21,9 @@ export interface ScrubCacheConfig {
 }
 export interface CreateScrubCursorOptions {
     source: VideoSource;
+    /** How decoded pixels leave the worker. Host-frame presentation keeps samples
+     * available until the selected output can be copied for transfer. */
+    presentation?: PresentationMode;
     /**
      * Decides the resolution frames are held and painted at: the display canvas
      * backing store and every cache blit. Combined with the viewport and the
@@ -42,7 +46,7 @@ export interface CreateScrubCursorOptions {
      * all. A failure after open() cannot surface as a rejected promise, since by
      * then nobody is awaiting one; this is how it reaches the transport.
      */
-    onDecodeFailure?: (error: VideoEngineError) => void;
+    onDecodeFailure?: (error: WebVideoEngineError) => void;
     /** Serves the demuxer's byte reads from what this process already holds. */
     sourceResidency?: SourceResidency;
     /** Read tuning for a URL source, passed through to mediabunny. */
@@ -59,4 +63,3 @@ export interface CreateScrubCursorOptions {
  * both backends share the same opened source.
  */
 export declare const createScrubCursor: ScrubCursorFactory;
-//# sourceMappingURL=create-scrub-cursor.d.ts.map

package/dist/web-video-engine/decode-resolution.d.ts

@@ -112,4 +112,3 @@ export declare function displayBoxResolution(options: DisplayBoxResolutionOption
  * native rather than producing a broken surface.
  */
 export declare function resolveDecodeDimensions(strategy: DecodeResolutionStrategy, ctx: DecodeResolutionContext): DecodeDimensions;
-//# sourceMappingURL=decode-resolution.d.ts.map

package/dist/web-video-engine/decode-scheduler.d.ts

@@ -1,8 +1,9 @@
+import type { DecodeDimensions } from "./decode-resolution";
 import { type AnySourceHandle } from "./decode-source";
 import { FrameCache } from "./frame-cache";
 import type { FrameId } from "./frame-timeline";
 import { type ScrubCursor, ScrubCursorState, type ScrubFrame, type ScrubFrameListener, type ScrubTrackInfo, type SchedulerStats, type SeekIntent } from "./scrub-cursor";
-import { type Sec, VideoEngineError } from "./types";
+import { type Sec, WebVideoEngineError } from "./types";
 export interface DecodeSchedulerOptions {
     readonly source: AnySourceHandle;
     readonly cache: FrameCache;
@@ -12,6 +13,8 @@ export interface DecodeSchedulerOptions {
     readonly previewToleranceMs?: number;
     /** Millisecond time source for latency stats; defaults to performance.now. */
     readonly now?: () => number;
+    /** Delay before scrub-neighbor prefetch; overridable for deterministic tests. */
+    readonly scrubPrefetchQuietMs?: number;
     /**
      * Opens a fresh source handle to replace a wedged decoder, or null when the
      * source cannot be re-opened (a one-shot stream). mediabunny decodes take no
@@ -39,8 +42,12 @@ export interface DecodeSchedulerOptions {
      * accepts every command and answers none of them, so without this the
      * transport reads as playing over a canvas that will never change again.
      */
-    readonly onDecodeFailure?: (error: VideoEngineError) => void;
+    readonly onDecodeFailure?: (error: WebVideoEngineError) => void;
 }
+/** Bounds the clone payload while preserving the first and last discovered
+ * anchors and sampling the interior evenly. GOP statistics still use the full
+ * index; only the diagnostic lane is thinned. */
+export declare function boundedKeyframeTimestamps(keyframesS: readonly number[]): number[];
 /**
  * Caching scrub cursor. Wraps the same decode primitives as CanvasSinkScrubCursor
  * but routes every random-access seek through a two-tier FrameCache and prefetches
@@ -60,12 +67,16 @@ export interface DecodeSchedulerOptions {
  */
 export declare class DecodeScheduler implements ScrubCursor {
     private provider;
-    private readonly cache;
+    private cache;
     private keyframeIndex;
-    private readonly trackInfo;
+    private trackInfo;
+    private outputGeneration;
+    private resizingOutput;
+    private readonly outputReads;
     private readonly exactTolMs;
     private readonly previewTolMs;
     private readonly now;
+    private readonly scrubPrefetchQuietMs;
     /** Re-opens the source after a hung decode, or null when it cannot be re-opened. */
     private readonly reopen;
     private readonly decodeHangTimeoutMs;
@@ -111,6 +122,8 @@ export declare class DecodeScheduler implements ScrubCursor {
     /** Outstanding background prefetch chain, or null once it unwinds. Awaited
      *  only by close(), so teardown cannot outrun a sweep still holding a decoder. */
     private prefetchTask;
+    /** True only while a sweep is decoding, not while scrub prefetch is parked. */
+    private prefetchDecoding;
     /** Bumped when a running prefetch is cancelled; that prefetch bails when it
      *  sees the token move, which is how cancellation propagates. */
     private prefetchGen;
@@ -143,6 +156,7 @@ export declare class DecodeScheduler implements ScrubCursor {
     get track(): ScrubTrackInfo;
     get playReadAhead(): number;
     get isIdle(): boolean;
+    resizeOutput({ width, height }: DecodeDimensions): Promise<boolean>;
     open(): Promise<void>;
     /**
      * The first frame, on the seed ceiling and its own attempt budget.
@@ -260,6 +274,7 @@ export declare class DecodeScheduler implements ScrubCursor {
      * decoder having a bad moment from one that will never answer again.
      */
     private withDecodeWatchdog;
+    private trackOutputRead;
     /**
      * The same watchdog over a container metadata read. Deliberately unbooked:
      * the keyframe probe never touches the decoder, so its answer is no evidence
@@ -342,6 +357,13 @@ export declare class DecodeScheduler implements ScrubCursor {
     private perSideWindowFrames;
     private frameIntervalS;
     private currentPositionS;
+    /** The timeline's name for a decoded frame, which is what the exact cache
+     *  tier stores it under. Two decodes of one frame land on one identity
+     *  however their microsecond timestamps differ, and two frames never share
+     *  one however close together the source puts them. */
+    private frameIdOf;
+    /** The timeline identity of the frame covering a presentation time. */
+    private frameAtTime;
     private emitDecoded;
     /** Puts a decoded frame in both tiers without painting it, and releases it.
      *  For a frame worth keeping whose moment to be seen has passed. */
@@ -353,4 +375,3 @@ export declare class DecodeScheduler implements ScrubCursor {
     private flushIdleResolvers;
     private flushSettleResolvers;
 }
-//# sourceMappingURL=decode-scheduler.d.ts.map

package/dist/web-video-engine/decode-session.d.ts

@@ -1,3 +1,4 @@
+import type { DecodeDimensions } from "./decode-resolution";
 import { type Rotation } from "./rotation";
 import type { VideoSampleLike } from "./scrub-cursor";
 /**
@@ -33,6 +34,11 @@ export interface DecodeSessionOptions {
     readonly packets: PacketSource;
     readonly config: VideoDecoderConfig;
     readonly createDecoder: (init: VideoDecoderInit) => VideoDecoderLike;
+    /** Dimensions used to take ownership of decoder output pixels when set. */
+    readonly outputWidth?: number;
+    readonly outputHeight?: number;
+    /** Test seam for taking ownership of decoder output pixels. */
+    readonly snapshotFrame?: (frame: VideoFrame, width: number, height: number) => VideoFrame;
     /**
      * The track's quarter turn, which the session's frames carry and its draw
      * applies. A raw decoded picture holds the stored pixels and nothing about
@@ -59,6 +65,7 @@ export declare function sessionDrivable(config: VideoDecoderConfig): boolean;
  * wraps it stays fake-injectable under test.
  */
 export interface SessionFrameSource {
+    resizeOutput?(dimensions: DecodeDimensions): Promise<void>;
     frameAt(targetS: number): Promise<VideoSampleLike | null>;
     framesFrom(startS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
     framesCovering(startS: number, endS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
@@ -144,6 +151,9 @@ export declare class DecodeSession implements SessionFrameSource {
     private epoch;
     private readonly outputTimeoutMs;
     private readonly rotation;
+    private outputWidth;
+    private outputHeight;
+    private readonly snapshotFrame;
     constructor(options: DecodeSessionOptions);
     /** Times the session has configured the decoder onto an anchor. */
     get anchorCount(): number;
@@ -155,6 +165,7 @@ export declare class DecodeSession implements SessionFrameSource {
      *  when there is one, since those are still servable, else the last position
      *  handed out. */
     get reachableFromS(): number;
+    resizeOutput({ width, height }: DecodeDimensions): Promise<void>;
     /** The frame at or before `targetS`, or null when nothing precedes it. */
     frameAt(targetS: number): Promise<VideoSampleLike | null>;
     /**
@@ -273,4 +284,3 @@ export declare class DecodeSession implements SessionFrameSource {
     private latch;
     private discardDecoded;
 }
-//# sourceMappingURL=decode-session.d.ts.map