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

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

@@ -1,5 +1,5 @@
 /**
- * Two-tier frame cache, keyed by millisecond timestamp.
+ * Two-tier frame cache.
  *
  * The preview tier holds many downscaled frames: a long, coarse history that
  * answers a scrub instantly while the crisp frame decodes. The exact tier holds
@@ -10,11 +10,18 @@
  * served it. Only an exact hit is full-resolution; a preview hit still owes the
  * caller a crisp decode.
  *
+ * The exact tier is keyed by the timeline's identity for the frame, so two
+ * source frames can never share a slot at any frame rate. The preview tier is
+ * keyed by rounded millisecond, which merges frames spaced under a millisecond;
+ * it is the tier whose answer is already declared approximate, and it never
+ * claims to be the frame at the target.
+ *
  * Both tiers store OffscreenCanvas blits, never VideoFrames: a raw-frame cache
  * pins decoder output, stalling the decoder and growing VRAM without bound. A
  * frame fed as a live VideoSample is drawn into the blit and never retained, so
  * the no-retention rule holds on the zero-copy path too.
  */
+import type { FrameId } from "./frame-timeline";
 import type { VideoSampleLike } from "./scrub-cursor";
 /**
  * What the cache can blit into a tier: an already-decoded canvas/image, or a
@@ -45,11 +52,12 @@ export interface FrameCacheStats {
     readonly exactTimestampsMs: number[];
     readonly previewTimestampsMs: number[];
     /** Configured source frame interval: the visual width of each cached mark on
-     *  the timeline. Keys are per-millisecond, so this is a display width and
-     *  not the grid entries land on. */
+     *  the timeline. Nothing is keyed by it, so this is a display width and not
+     *  the grid entries land on. */
     readonly bucketMs: number;
-    /** Frames dropped to LRU pressure per tier, and puts that landed in an
-     *  occupied bucket (re-decodes collapsed onto one slot). */
+    /** Frames dropped to LRU pressure per tier, and puts that overwrote a live
+     *  key: a frame decoded again on the exact tier, and on the preview tier
+     *  either that or two frames sharing one rounded millisecond. */
     readonly exactEvictions: number;
     readonly previewEvictions: number;
     readonly bucketCollapses: number;
@@ -72,10 +80,7 @@ export interface FrameCacheOptions {
     /** Coarse-tier slot count. */
     readonly previewCapacity: number;
     /** Source frame interval in ms, reported to diagnostics as the timeline mark
-     *  width. It does not key the tiers: a grid this wide rounds two adjacent
-     *  frames onto one slot wherever the rounded interval exceeds the true one
-     *  (24, 60fps and their pulldown rates), so each frame is keyed by its own
-     *  millisecond instead. */
+     *  width. It keys nothing. */
     readonly bucketMs: number;
     /** Floor on exact-tier slots, applied even when the byte budget would yield
      *  fewer. Lets a caller that owns the prefetch-window width guarantee a full
@@ -84,6 +89,7 @@ export interface FrameCacheOptions {
     readonly minExactSlots?: number;
 }
 export declare class FrameCache {
+    private readonly options;
     private readonly exact;
     private readonly preview;
     private exactHits;
@@ -92,10 +98,24 @@ export declare class FrameCache {
     private readonly bucketMs;
     private readonly exactBudgetBytes;
     constructor(options: FrameCacheOptions);
-    /** Store a crisp full-resolution frame for the exact (scrub) tier. */
-    putExact(timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    resized(width: number, height: number): FrameCache;
+    /**
+     * Store a crisp full-resolution frame for the exact (scrub) tier under
+     * `frame`, the timeline's name for it. `timestampMs` is the decoded
+     * timestamp, which is what lookups match on and what a hit reports back.
+     */
+    putExact(frame: FrameId, timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
     /** Store a downscaled frame for the coarse preview tier. */
     putPreview(timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    /**
+     * Best cached answer for a named source frame. The exact tier is looked up
+     * only by `frame` identity; time is used solely for the approximate preview
+     * fallback. This keeps a long variable-rate frame from borrowing a crisp
+     * neighbour merely because both timestamps fit a millisecond tolerance.
+     */
+    getForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
+    /** Non-accounting form of {@link getForFrame}. */
+    peekForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
     /**
      * Best cached frame for `timestampMs`, consulting the exact tier then the
      * preview tier: a crisp hit within `exactTolMs`, else a coarse hit within
@@ -123,7 +143,96 @@ export declare class FrameCache {
      * from being the LRU victim of its own neighbor sweep. No-op on a miss.
      */
     bumpExact(timestampMs: number): void;
+    /** Promotes one exact frame by identity. */
+    bumpExactFrame(frame: FrameId): void;
     clear(): void;
     get stats(): FrameCacheStats;
 }
-//# sourceMappingURL=frame-cache.d.ts.map
+interface TierHit {
+    readonly canvas: OffscreenCanvas;
+    readonly timestampMs: number;
+}
+/**
+ * One cache tier: a fixed-capacity, MRU-ordered set of OffscreenCanvas copies
+ * under keys its owner assigns. A put onto a live key overwrites that slot in
+ * place, so an owner that lets two frames share a key loses one of them
+ * silently; overflow past capacity evicts the least-recently-used entry
+ * instead. Lookups match on the stored frame's true timestamp and never on the
+ * key, so a cache-served frame carries the same timestamp a fresh decode would.
+ */
+export declare class TierStore {
+    readonly capacity: number;
+    readonly width: number;
+    readonly height: number;
+    /** Width of the grid the owner's keys round onto, or 0 when a key names a
+     *  frame outright. Two entries closer together than this are one frame
+     *  whose two decodes rounded onto either side of a key boundary. */
+    private readonly keyGridMs;
+    /** MRU-ordered keys. Index 0 is the LRU, the last index is the MRU. */
+    private readonly keys;
+    private readonly entries;
+    /** Canvases released by eviction, held for the next put to fill. */
+    private readonly spare;
+    private evictionCount;
+    private bucketCollapseCount;
+    /** Smallest gap between two stored frames, which is the source frame interval
+     *  once neighbours are resident. Learned from the timestamps the tier is
+     *  handed, so it is what the source really did rather than a declared rate.
+     *  Null until two frames have landed. */
+    private observedIntervalMs;
+    constructor(capacity: number, width: number, height: number, 
+    /** Width of the grid the owner's keys round onto, or 0 when a key names a
+     *  frame outright. Two entries closer together than this are one frame
+     *  whose two decodes rounded onto either side of a key boundary. */
+    keyGridMs: number);
+    /** Frames dropped to the LRU policy; a cache-pressure signal for diagnostics. */
+    get evictions(): number;
+    /** Puts that landed on a key already live, collapsing both onto one slot. */
+    get bucketCollapses(): number;
+    put(key: number, timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    /**
+     * Nearest resident frame to `timestampMs` within `tolMs`, or null.
+     *
+     * `atOrBefore` restricts it to frames at or before the target, which is the
+     * contract a decode answers a seek with. Without it the tier can answer with
+     * the frame AFTER the target, one no decode would ever return, so the same
+     * pointer position paints a different frame depending on whether the cache or
+     * the decoder served it, and the picture steps forward and back as the two
+     * alternate.
+     */
+    get(timestampMs: number, tolMs: number, atOrBefore?: boolean): TierHit | null;
+    /** Retrieves exactly one owner-assigned key and promotes it to MRU. */
+    getByKey(key: number): TierHit | null;
+    /** Promotes the entry nearest `timestampMs` to most-recently-used. Scans
+     *  rather than keys off the timestamp: callers pass a gesture position, which
+     *  is not a frame timestamp, so a keyed lookup would miss the very frame on
+     *  screen. No accounting; it is not a lookup. */
+    touch(timestampMs: number): void;
+    /** Promotes an owner-assigned key without a timestamp scan. */
+    touchKey(key: number): void;
+    clear(): void;
+    get size(): number;
+    /** True timestamps (ms) of resident frames, for diagnostics. Bounded by capacity. */
+    timestampsSnapshot(): number[];
+    private bump;
+    /**
+     * Best candidate for `timestampMs`, or null when nothing qualifies.
+     *
+     * Under `atOrBefore` a stored frame stands for the span from its own
+     * timestamp up to the next source frame; a target past that span belongs to
+     * the next frame, which is what a decode for it returns. Answering it from
+     * this tier would paint a frame no decode for that time ever produces, so a
+     * candidate outside its own frame's span is not eligible however generous the
+     * caller's tolerance is. Until the tier has learned a frame gap it has no
+     * spacing to bound with and the caller's tolerance stands alone.
+     */
+    private nearest;
+    /** Narrows the learned frame interval to the smallest gap seen so far. A gap
+     *  at or below the key grid is one frame that rounded onto two keys rather
+     *  than two frames, so it is no interval at all; what survives is a gap
+     *  between two frames, and never zero. It only ever tightens, so a tier that
+     *  has watched an unrepresentative stretch of a variable-rate source bounds
+     *  lookups too tightly (a decode) rather than too loosely (the wrong frame). */
+    private observeSpacing;
+}
+export {};

package/dist/web-video-engine/frame-extractor.d.ts

@@ -25,4 +25,3 @@ export declare class FrameExtractor {
     /** Disposes the underlying analysis session. */
     close(): Promise<void>;
 }
-//# sourceMappingURL=frame-extractor.d.ts.map

package/dist/web-video-engine/{frame-timeline-GINI8Gum.js → frame-timeline-DreEwsRY.js}

@@ -157,6 +157,7 @@ const DIAGNOSTICS = {
     TRACE_EVENT_CAP: 2000,
     TRACE_SNAPSHOT_CAP: 600,
     SCRUB_LATENCY_RING: 64,
+    KEYFRAME_TIMESTAMPS_CAP: 512,
 };
 /**
  * What an armed capture actually keeps. The snapshot ring is fed at the fixed
@@ -205,8 +206,9 @@ const TRACE_RING_BOUNDS = {
  * reply before the facade gives up on it.
  */
 const DECODE_HANG_TIMEOUT_MS = 30_000;
+const WORKER_COMMAND_TIMEOUT_MS = DECODE_HANG_TIMEOUT_MS + 15_000;
 const HANG_RECOVERY = {
-    WORKER_COMMAND_TIMEOUT_MS: DECODE_HANG_TIMEOUT_MS + 15_000,
+    WORKER_COMMAND_TIMEOUT_MS,
 };
 
 const asSec = (n) => n;
@@ -234,49 +236,48 @@ var PlaybackStatus;
     PlaybackStatus["Ended"] = "ENDED";
     PlaybackStatus["Errored"] = "ERRORED";
 })(PlaybackStatus || (PlaybackStatus = {}));
-var VideoEngineErrorCode;
-(function (VideoEngineErrorCode) {
-    VideoEngineErrorCode["DecodeUnsupported"] = "DECODE_UNSUPPORTED";
-    VideoEngineErrorCode["SourceUnreadable"] = "SOURCE_UNREADABLE";
+var WebVideoEngineErrorCode;
+(function (WebVideoEngineErrorCode) {
+    WebVideoEngineErrorCode["DecodeUnsupported"] = "DECODE_UNSUPPORTED";
+    WebVideoEngineErrorCode["SourceUnreadable"] = "SOURCE_UNREADABLE";
     /**
      * The demuxer refused the file outright: its container is not one this build
      * reads, so no track was ever listed and no decoder was ever asked.
      */
-    VideoEngineErrorCode["ContainerUnreadable"] = "CONTAINER_UNREADABLE";
+    WebVideoEngineErrorCode["ContainerUnreadable"] = "CONTAINER_UNREADABLE";
     /**
      * The container opened and the demuxer parsed no track at all out of it. The
      * file's streams are in formats it does not carry, so their video cannot be
      * reached even though it is there.
      */
-    VideoEngineErrorCode["VideoTrackUnreadable"] = "VIDEO_TRACK_UNREADABLE";
+    WebVideoEngineErrorCode["VideoTrackUnreadable"] = "VIDEO_TRACK_UNREADABLE";
     /**
      * The container opened, its tracks listed, and none of them is video. This
      * is the only case where the file itself is what lacks video.
      */
-    VideoEngineErrorCode["NoVideoTrack"] = "NO_VIDEO_TRACK";
-    VideoEngineErrorCode["BackendCrashed"] = "BACKEND_CRASHED";
-    VideoEngineErrorCode["Aborted"] = "ABORTED";
+    WebVideoEngineErrorCode["NoVideoTrack"] = "NO_VIDEO_TRACK";
+    WebVideoEngineErrorCode["BackendCrashed"] = "BACKEND_CRASHED";
+    WebVideoEngineErrorCode["Aborted"] = "ABORTED";
     /** A canvas was offered to an engine loaded in "frames" presentation mode,
      *  where the host owns the only canvas. */
-    VideoEngineErrorCode["PresentationMismatch"] = "PRESENTATION_MISMATCH";
+    WebVideoEngineErrorCode["PresentationMismatch"] = "PRESENTATION_MISMATCH";
     /**
      * The decoder cannot decode this source at all: it refused to configure, it
      * errored, or it acknowledged decode requests and never produced a frame.
-     * Distinct from BackendCrashed, which a rebuild can recover; this one
-     * survives every rebuild, so the runtime stops rebuilding and says so. The
-     * usual cause is outside the page: another tab holding every hardware
-     * decoder session the machine has.
+     * Distinct from BackendCrashed; this one survives every rebuild, so the
+     * runtime stops rebuilding and says so. The usual cause is outside the page:
+     * another tab holding every hardware decoder session the machine has.
      */
-    VideoEngineErrorCode["DecoderStalled"] = "DECODER_STALLED";
+    WebVideoEngineErrorCode["DecoderStalled"] = "DECODER_STALLED";
     /** A playback rate outside the forward range the engine supports. */
-    VideoEngineErrorCode["RateUnsupported"] = "RATE_UNSUPPORTED";
-})(VideoEngineErrorCode || (VideoEngineErrorCode = {}));
+    WebVideoEngineErrorCode["RateUnsupported"] = "RATE_UNSUPPORTED";
+})(WebVideoEngineErrorCode || (WebVideoEngineErrorCode = {}));
 /**
- * Thrown by createScrubCursor / VideoEngine.load when decode is unsupported
- * or the source is unreadable. Branch on `error.code` (VideoEngineErrorCode)
+ * Thrown by createScrubCursor / WebVideoEngine.load when decode is unsupported
+ * or the source is unreadable. Branch on `error.code` (WebVideoEngineErrorCode)
  * to differentiate decode failures from network failures.
  */
-class VideoEngineError extends Error {
+class WebVideoEngineError extends Error {
     code;
     cause;
     constructor(code, message, cause) {
@@ -288,7 +289,7 @@ class VideoEngineError extends Error {
 /** Shared by the facade and the core so a host gets the same refusal wherever
  *  its canvas is caught. */
 function canvasBindingRefused() {
-    return new VideoEngineError(VideoEngineErrorCode.PresentationMismatch, 'presentation "frames" leaves the canvas to the host: this engine paints nothing and hands out VideoFrames instead');
+    return new WebVideoEngineError(WebVideoEngineErrorCode.PresentationMismatch, 'presentation "frames" leaves the canvas to the host: this engine paints nothing and hands out VideoFrames instead');
 }
 /**
  * Validates a requested playback rate and returns it. The facade and the core
@@ -304,7 +305,7 @@ function resolvePlaybackRate(rate) {
     if (!Number.isFinite(rate) ||
         rate < PLAYBACK_RATE.MIN ||
         rate > PLAYBACK_RATE.MAX) {
-        throw new VideoEngineError(VideoEngineErrorCode.RateUnsupported, `playback rate ${rate} is outside the supported forward range ${PLAYBACK_RATE.MIN}-${PLAYBACK_RATE.MAX}; reverse playback is not supported`);
+        throw new WebVideoEngineError(WebVideoEngineErrorCode.RateUnsupported, `playback rate ${rate} is outside the supported forward range ${PLAYBACK_RATE.MIN}-${PLAYBACK_RATE.MAX}; reverse playback is not supported`);
     }
     return rate;
 }
@@ -435,15 +436,55 @@ function oneEntryPerInstant(data) {
     if (at === ticks.length)
         return data;
     const distinct = new Float64Array(ticks.length);
+    const distinctSource = data.sourceTicks
+        ? new Float64Array(ticks.length)
+        : undefined;
     distinct.set(ticks.subarray(0, at));
+    if (distinctSource)
+        distinctSource.set(data.sourceTicks.subarray(0, at));
     let size = at;
     for (let i = at + 1; i < ticks.length; i += 1) {
         if (ticks[i] === distinct[size - 1])
             continue;
         distinct[size] = ticks[i];
+        if (distinctSource)
+            distinctSource[size] = data.sourceTicks[i];
         size += 1;
     }
-    return { ...data, ticks: distinct.slice(0, size) };
+    return {
+        ...data,
+        ticks: distinct.slice(0, size),
+        ...(distinctSource ? { sourceTicks: distinctSource.slice(0, size) } : {}),
+    };
+}
+function normalizePresentationOrigin(data) {
+    if (data.sourceTicks !== undefined || !(data.ticks[0] < 0))
+        return data;
+    let firstVisible = 0;
+    while (firstVisible < data.ticks.length) {
+        const end = firstVisible + 1 < data.ticks.length
+            ? data.ticks[firstVisible + 1]
+            : data.ticks[firstVisible] + data.lastDurationTicks;
+        if (end > 0)
+            break;
+        firstVisible += 1;
+    }
+    if (firstVisible === data.ticks.length) {
+        throw new RangeError("FrameTimeline: a track containing only pre-roll has no presentation timeline");
+    }
+    const sourceTicks = data.ticks.slice(firstVisible);
+    const ticks = sourceTicks.slice();
+    if (ticks[0] < 0)
+        ticks[0] = 0;
+    const lastDurationTicks = ticks.length === 1 && sourceTicks[0] < 0
+        ? data.lastDurationTicks + sourceTicks[0]
+        : data.lastDurationTicks;
+    return {
+        ...data,
+        lastDurationTicks,
+        sourceTicks,
+        ticks,
+    };
 }
 /**
  * Every real frame of one track, in presentation order, by its container tick
@@ -469,7 +510,7 @@ class FrameTimeline {
         if (!(data.tickRate > 0)) {
             throw new RangeError(`FrameTimeline: tick rate ${data.tickRate} is not positive`);
         }
-        return new FrameTimeline(oneEntryPerInstant(data));
+        return new FrameTimeline(oneEntryPerInstant(normalizePresentationOrigin(data)));
     }
     /** A synthetic constant-rate table. Tests and fakes only. The default tick
      *  rate is a whole multiple of `fps`, so no test table needs rounding. */
@@ -493,6 +534,22 @@ class FrameTimeline {
     timeAt(index) {
         return asSec(this.ticksAt(index) / this.data.tickRate);
     }
+    /** Timestamp passed to the decoder for the named presentation frame. */
+    sourceTimeAt(index) {
+        const at = this.clampIndex(index);
+        return asSec((this.data.sourceTicks?.[at] ?? this.ticksArray[at]) / this.data.tickRate);
+    }
+    /** Maps a public presentation time onto the container's source clock. */
+    toSourceTime(timeS) {
+        if (this.data.sourceTicks && timeS <= this.timeAt(0)) {
+            return this.sourceTimeAt(0);
+        }
+        return asSec(timeS);
+    }
+    /** Maps a decoded/container timestamp onto the public presentation clock. */
+    fromSourceTime(timeS) {
+        return asSec(this.data.sourceTicks ? Math.max(0, timeS) : timeS);
+    }
     idAt(index) {
         const at = this.clampIndex(index);
         return { index: at, ticks: this.ticksArray[at] };
@@ -556,5 +613,4 @@ class FrameTimeline {
     }
 }
 
-export { DIAGNOSTICS as D, FRAME_TIMELINE as F, HANG_RECOVERY as H, PlaybackStatus as P, SCRUB as S, TRACE_RING_BOUNDS as T, VideoEngineError as V, VideoEngineErrorCode as a, asSec as b, SourceKind as c, FrameTimeline as d, asPaintSeq as e, canvasBindingRefused as f, resolvePlaybackRate as g, PLAYBACK_RATE as h, asFps as i, cappedResolution as j, displayBoxResolution as k, nativeResolution as n, resolveDecodeDimensions as r, viewportResolution as v };
-//# sourceMappingURL=frame-timeline-GINI8Gum.js.map
+export { DIAGNOSTICS as D, FRAME_TIMELINE as F, HANG_RECOVERY as H, PlaybackStatus as P, SCRUB as S, TRACE_RING_BOUNDS as T, WebVideoEngineError as W, WebVideoEngineErrorCode as a, asSec as b, SourceKind as c, FrameTimeline as d, asPaintSeq as e, canvasBindingRefused as f, resolvePlaybackRate as g, PLAYBACK_RATE as h, asFps as i, cappedResolution as j, displayBoxResolution as k, nativeResolution as n, resolveDecodeDimensions as r, viewportResolution as v };

package/dist/web-video-engine/frame-timeline.d.ts

@@ -22,6 +22,10 @@ export interface FrameTimelineData {
     readonly tickRate: TickRate;
     readonly ticks: Float64Array;
     readonly lastDurationTicks: number;
+    /** Original source timestamps when presentation pre-roll was removed. The
+     *  public `ticks` stay zero-based while decode requests retain the addresses
+     *  needed to reach a frame straddling presentation time zero. */
+    readonly sourceTicks?: Float64Array;
 }
 /**
  * Every real frame of one track, in presentation order, by its container tick
@@ -46,6 +50,12 @@ export declare class FrameTimeline {
     toData(): FrameTimelineData;
     ticksAt(index: number): number;
     timeAt(index: number): Sec;
+    /** Timestamp passed to the decoder for the named presentation frame. */
+    sourceTimeAt(index: number): Sec;
+    /** Maps a public presentation time onto the container's source clock. */
+    toSourceTime(timeS: number): Sec;
+    /** Maps a decoded/container timestamp onto the public presentation clock. */
+    fromSourceTime(timeS: number): Sec;
     idAt(index: number): FrameId;
     landingAt(index: number): FrameLanding;
     /** Ticks the frame at `index` ends at, which is where the next one starts. */
@@ -68,4 +78,3 @@ export declare class FrameTimeline {
     indexOfDecoded(timeS: number): number;
     private clampIndex;
 }
-//# sourceMappingURL=frame-timeline.d.ts.map

package/dist/web-video-engine/frame-walker.d.ts

@@ -71,4 +71,3 @@ export declare class FrameWalker {
     walkFrames(range?: FrameWalkRange): AsyncGenerator<WalkedFrame, void, unknown>;
     close(): Promise<void>;
 }
-//# sourceMappingURL=frame-walker.d.ts.map

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

@@ -1,3 +1,13 @@
-export * from "#web-video-engine";
-export { createVideoEngineMediaRendererSource, openVideoEngineMediaSource, type VideoEngineMediaSource, type VideoEngineMediaSourceOptions, } from "supervision";
+/**
+ * The web video engine, and the two adapters that hand what it decodes to a
+ * media renderer.
+ *
+ * The engine's own barrel is wider than this, because its modules export for
+ * one another. A name reaches an application only by being listed here, so
+ * listing one is a decision to support it. Worker message shapes, mediabunny
+ * pass-through configuration, and the React imperative handle stay inside.
+ */
+export { createWebVideoEngineMediaRendererSource, openWebVideoEngineMediaSource, type WebVideoEngineMediaSource, type WebVideoEngineMediaSourceOptions, } from "#media/video-engine-media-source";
+export { DIAGNOSTICS, FrameTimeline, PLAYBACK_RATE, PlaybackStatus, SourceKind, TRACE_RING_BOUNDS, WebVideoEngine, WebVideoEngineError, WebVideoEngineErrorCode, cappedResolution, displayBoxResolution, nativeResolution, viewportResolution, } from "#web-video-engine";
+export type { BlobVideoSource, DecodeResolutionStrategy, DiagnosticsSnapshot, DisplayBoxResolutionOptions, EngineChannel, EngineReadySnapshot, Fps, FrameId, FrameLanding, FrameQuality, FrameTimelineData, PaintSeq, PlaybackState, PresentationMode, PresentedFrame, PresentedFrameHandler, Rotation, Sec, SeekIntent, SeekTarget, SourceResidencyConfig, SourceResidencyDiagnostics, StreamVideoSource, TickRate, UrlVideoSource, VideoMetadata, VideoSource, ViewportResolutionOptions, Warning, WarningSeverity, WebVideoEngineOptions, } from "#web-video-engine";
 //# sourceMappingURL=index.d.ts.map

package/dist/web-video-engine/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-video-engine/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,oCAAoC,EACpC,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,aAAa,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-video-engine/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,OAAO,EACL,uCAAuC,EACvC,6BAA6B,EAC7B,KAAK,yBAAyB,EAC9B,KAAK,gCAAgC,GACtC,MAAM,kCAAkC,CAAC;AAC1C,OAAO,EACL,WAAW,EACX,aAAa,EACb,aAAa,EACb,cAAc,EACd,UAAU,EACV,iBAAiB,EACjB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,gBAAgB,EAChB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EACV,eAAe,EACf,wBAAwB,EACxB,mBAAmB,EACnB,2BAA2B,EAC3B,aAAa,EACb,mBAAmB,EACnB,GAAG,EACH,OAAO,EACP,YAAY,EACZ,YAAY,EACZ,iBAAiB,EACjB,QAAQ,EACR,aAAa,EACb,gBAAgB,EAChB,cAAc,EACd,qBAAqB,EACrB,QAAQ,EACR,GAAG,EACH,UAAU,EACV,UAAU,EACV,qBAAqB,EACrB,0BAA0B,EAC1B,iBAAiB,EACjB,QAAQ,EACR,cAAc,EACd,aAAa,EACb,WAAW,EACX,yBAAyB,EACzB,OAAO,EACP,eAAe,EACf,qBAAqB,GACtB,MAAM,mBAAmB,CAAC"}

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

@@ -1,3 +1,3 @@
-export * from './engine.js';
-export { createVideoEngineMediaRendererSource, openVideoEngineMediaSource } from '../index.js';
+export { createWebVideoEngineMediaRendererSource, openWebVideoEngineMediaSource } from '../media/video-engine-media-source.js';
+export { DIAGNOSTICS, FrameTimeline, PLAYBACK_RATE, PlaybackStatus, SourceKind, TRACE_RING_BOUNDS, WebVideoEngine, WebVideoEngineError, WebVideoEngineErrorCode, cappedResolution, displayBoxResolution, nativeResolution, viewportResolution } from './engine.js';
 //# sourceMappingURL=index.js.map

package/dist/web-video-engine/key-packet.d.ts

@@ -62,4 +62,3 @@ export declare class KeyPacketRequirement {
      */
     satisfy(packetBytes: Uint8Array): Uint8Array;
 }
-//# sourceMappingURL=key-packet.d.ts.map

package/dist/web-video-engine/keyframe-index.d.ts

@@ -88,4 +88,3 @@ export declare class KeyframeIndex {
     private record;
 }
 export {};
-//# sourceMappingURL=keyframe-index.d.ts.map

package/dist/web-video-engine/mirror-store.d.ts

@@ -53,4 +53,3 @@ export declare class MirrorStore {
     subscribe(channel: EngineChannel, listener: () => void): () => void;
     private emit;
 }
-//# sourceMappingURL=mirror-store.d.ts.map

package/dist/web-video-engine/pausable-deadline.d.ts

@@ -0,0 +1,11 @@
+/**
+ * A timeout whose budget advances only while its owner is visible. The owner
+ * still decides which work is eligible: this helper never pauses the work
+ * itself, nor any unrelated watchdog.
+ */
+export interface PausableDeadline {
+    cancel(): void;
+    pause(): void;
+    resume(): void;
+}
+export declare function createPausableDeadline(timeoutMs: number, onExpire: () => void): PausableDeadline;

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

@@ -91,4 +91,3 @@ export interface RendererOptions {
  * 2D renderer instead, so a caller always gets a working renderer.
  */
 export declare function createRenderer(canvas: OffscreenCanvas, options?: RendererOptions): Promise<Renderer>;
-//# sourceMappingURL=renderer.d.ts.map

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

@@ -32,4 +32,3 @@ export declare function drawRotated(context: CanvasRenderingContext2D | Offscree
  * stretch-to-fill absorbs the aspect change for free.
  */
 export declare function uvRotationMatrix(rotation: Rotation): readonly [number, number, number, number];
-//# sourceMappingURL=rotation.d.ts.map

package/dist/web-video-engine/scrub-controller.d.ts

@@ -349,6 +349,8 @@ export declare class ScrubController {
      *  walk. Detaches the iterator and drops the read-ahead so paused ticks
      *  never paint a stale play frame. */
     endPlay(): void;
+    holdOutput(): void;
+    releaseOutput(): void;
     /**
      * Cache lookup helper used by the engine on scrub. Asks the cursor for a
      * cached frame near the target and, if it is far enough from what the canvas
@@ -356,12 +358,14 @@ export declare class ScrubController {
      * calls cursor.seekTo to land the full-res frame; the cursor's emit listener
      * stashes it for the next tick.
      *
-     * The skip-near-current check rejects hits whose timestamp falls within
-     * cacheSkipNearMs of the currently-displayed frame. This is the knob
-     * consumers tune to control single-frame-step UX: a higher value forces a
-     * fresh decode on tighter movements, a value of 0 always serves the cache.
+     * Nearby approximate hits respect cacheSkipNearMs. An exact hit for the
+     * requested frame can advance immediately, without waiting for a decode.
      */
     tryPaintFromCache(timestampMs: number): boolean;
+    /** A new commit needs its own presentation even when its exact pixels were
+     *  already shown by the preceding scrub. Approximate neighbors cannot answer it. */
+    presentExactFromCache(timestampMs: number): boolean;
+    private paintCached;
     private start;
     private runTick;
     private paint;
@@ -373,4 +377,3 @@ export declare class ScrubController {
     getRealtimeStats(): RealtimeStats;
     private stop;
 }
-//# sourceMappingURL=scrub-controller.d.ts.map

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

@@ -1,4 +1,5 @@
 import type { CreateScrubCursorOptions } from "./create-scrub-cursor";
+import type { DecodeDimensions } from "./decode-resolution";
 import type { FrameCacheStats } from "./frame-cache";
 import type { FrameId, FrameTimeline } from "./frame-timeline";
 import type { GopStats } from "./keyframe-index";
@@ -27,8 +28,9 @@ export interface ScrubFrameBase {
 }
 /**
  * The structural slice of mediabunny's VideoSample the runtime touches: enough
- * to draw it into a 2D canvas, hand its pixels to WebGPU zero-copy, and release
- * it. Kept as a slice rather than the concrete class so the runtime never
+ * to draw it into a 2D canvas, hand its pixels to WebGPU without an intermediate
+ * transfer copy where the selected path supports that, and release it. Kept as
+ * a slice rather than the concrete class so the runtime never
  * imports mediabunny and stays fake-injectable under test.
  *
  * close() is the caller's obligation and is made idempotent at the cursor
@@ -44,6 +46,9 @@ export interface VideoSampleLike {
      * whoever takes one owes it the turn named by `rotation` below.
      */
     toVideoFrame(): VideoFrame;
+    /** The sample owns storage independent of a decoder output pool, so a host
+     * transfer may rewrap it without copying its pixels again. */
+    readonly independentPixels?: true;
     /** The turn the pixels still need, already applied by draw() and dropped by
      *  toVideoFrame(). */
     readonly rotation: Rotation;
@@ -58,9 +63,11 @@ export interface VideoSampleLike {
  *
  * A canvas frame carries a canvas and no close obligation: it is a cache blit
  * or a CanvasSink decode. WebGPU uploads it with copyExternalImageToTexture,
- * which accepts neither an SVG image nor a video element. A sample frame carries a live VideoSample
- * the zero-copy path imports straight into WebGPU; whoever stashes it owns its
- * close, so only fresh decodes on the sample source produce one.
+ * which accepts neither an SVG image nor a video element. A sample frame carries
+ * a live VideoSample that an eligible VideoSampleSink route can import directly
+ * into WebGPU. A DecodeSession route may first materialize independently owned
+ * pixels. Whoever stashes the sample owns its close, so only fresh decodes on
+ * the sample source produce one.
  */
 export interface CanvasScrubFrame extends ScrubFrameBase {
     readonly kind: "canvas";
@@ -270,13 +277,15 @@ export interface ScrubTrackInfo {
  *     frame as a keyframe result.
  *   - next is VFR-correct and a no-op while paused (no iterator attached),
  *     so it never advances media time across a paused canvas. The 1/fps step
- *     approximation lives in VideoEngine.step, not here.
+ *     approximation lives in WebVideoEngine.step, not here.
  *   - isIdle is true only when no seek is draining and no pull is in flight.
  *   - subscribe replays the most recent frame to a new listener so the seed
  *     frame from open() is never dropped.
  *   - close is final; reusing a closed cursor is a programming error.
  */
 export interface ScrubCursor {
+    /** Drains old output and changes frame/cache size without reopening decode. */
+    resizeOutput?(dimensions: DecodeDimensions): Promise<boolean>;
     readonly state: ScrubCursorState;
     readonly track: ScrubTrackInfo;
     readonly isIdle: boolean;
@@ -339,4 +348,3 @@ export interface ScrubCursor {
     close(): Promise<void>;
 }
 export type ScrubCursorFactory = (options: CreateScrubCursorOptions) => Promise<ScrubCursor>;
-//# sourceMappingURL=scrub-cursor.d.ts.map

package/dist/web-video-engine/scrub-trajectory.d.ts

@@ -27,4 +27,3 @@ export declare class ScrubTrajectory {
     private indexFromNewest;
     private indexFromOldest;
 }
-//# sourceMappingURL=scrub-trajectory.d.ts.map

package/dist/web-video-engine/source-residency.d.ts

@@ -53,5 +53,39 @@ export interface SourceResidency {
  *  the network for less than half a mebibyte, so every read it makes banks
  *  at least one block. */
 export declare const READ_BLOCK_BYTES: number;
+/** How long a delivered chunk may sit unclaimed before the walk stops deferring
+ *  to the read that produced it. It measures the gap between a chunk and the
+ *  consumer's next pull, not the wait for the server, so a slow link reads as
+ *  a live read while a reader that walked away frees the link. */
+export declare const FOREGROUND_STALL_MS = 250;
+/**
+ * Bytes held in one buffer per contiguous run, so a lookup is a single scan and
+ * a served range is a subarray with nothing copied. Insert is where copying
+ * happens: a run keeps spare capacity so an append that extends it writes into
+ * that room, and only a backward or overlapping insert re-materializes the run.
+ */
+export declare class ByteStore {
+    #private;
+    get residentBytes(): number;
+    /** Bytes retained by backing arrays, including append headroom. */
+    get allocatedBytes(): number;
+    ranges(): ResidentRange[];
+    /** The held run from `offset` to the end of its run, or null. */
+    runAt(offset: number): Uint8Array | null;
+    /** Where the gap containing `offset` ends, or null when nothing is held past it. */
+    nextHeldStart(offset: number): number | null;
+    insert(start: number, bytes: Uint8Array): void;
+    /**
+     * Brings held bytes under the budget: whole runs go first, furthest from
+     * `focus`, and a lone run that has outgrown the budget is narrowed to a
+     * `budgetBytes` window at `focus`.
+     */
+    evictTo(budgetBytes: number, focus: number): void;
+    clear(): void;
+}
+/**
+ * Outstanding claims on the link, for this module's own tests: they drive every
+ * way a read can end and assert the count comes back to zero.
+ */
+export declare function outstandingForegroundHolds(residency: SourceResidency): number;
 export declare function createSourceResidency(options: SourceResidencyOptions): SourceResidency;
-//# sourceMappingURL=source-residency.d.ts.map