supervision 0.1.7 → 0.2.0-next.0

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

@@ -0,0 +1,276 @@
+import { type Rotation } from "./rotation";
+import type { VideoSampleLike } from "./scrub-cursor";
+/**
+ * One packet as the session submits it. Mirrors the fields of mediabunny's
+ * EncodedPacket the decoder needs, so the session never imports mediabunny.
+ */
+export interface EncodedPacketLike {
+    readonly data: Uint8Array;
+    readonly type: "key" | "delta";
+    readonly timestamp: number;
+    readonly duration: number;
+}
+export interface PacketRetrievalOptionsLike {
+    readonly metadataOnly?: boolean;
+    readonly verifyKeyPackets?: boolean;
+}
+/** The slice of mediabunny's EncodedPacketSink the session decodes through. */
+export interface PacketSource {
+    getKeyPacket(timestamp: number, options?: PacketRetrievalOptionsLike): Promise<EncodedPacketLike | null>;
+    getNextKeyPacket(packet: EncodedPacketLike, options?: PacketRetrievalOptionsLike): Promise<EncodedPacketLike | null>;
+    packets(startPacket?: EncodedPacketLike, endPacket?: EncodedPacketLike, options?: PacketRetrievalOptionsLike): AsyncGenerator<EncodedPacketLike, void, unknown>;
+}
+/** The slice of WebCodecs' VideoDecoder the session drives. Chunks cross as
+ *  inits so the session never reaches for a platform constructor. */
+export interface VideoDecoderLike {
+    configure(config: VideoDecoderConfig): void;
+    decode(chunk: EncodedVideoChunkInit): void;
+    flush(): Promise<void>;
+    reset(): void;
+    close(): void;
+}
+export interface DecodeSessionOptions {
+    readonly packets: PacketSource;
+    readonly config: VideoDecoderConfig;
+    readonly createDecoder: (init: VideoDecoderInit) => VideoDecoderLike;
+    /**
+     * 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
+     * the display matrix, so this is the only route the turn has here, and a
+     * caller that forgets it paints every portrait recording sideways.
+     */
+    readonly rotation: Rotation;
+    /**
+     * Ceiling on waiting for one decoder output while chunks are in flight;
+     * defaults to OUTPUT_TIMEOUT_MS. Overridable so a test can drive the
+     * silent-decoder path without waiting out the production ceiling.
+     */
+    readonly outputTimeoutMs?: number;
+}
+/**
+ * Whether the session can drive a track with this decoder config. The gate that
+ * routes a source here and the constructor that refuses everything else read the
+ * same predicate.
+ */
+export declare function sessionDrivable(config: VideoDecoderConfig): boolean;
+/**
+ * The three retrievals the session answers, mirror for mirror with the sink
+ * slices the other decode paths ride. Held as an interface so the provider that
+ * wraps it stays fake-injectable under test.
+ */
+export interface SessionFrameSource {
+    frameAt(targetS: number): Promise<VideoSampleLike | null>;
+    framesFrom(startS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+    framesCovering(startS: number, endS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+    /** Earliest position still reachable without re-anchoring, or -Infinity when
+     *  the session has not been positioned yet. A decoder only moves forward, so
+     *  asking for anything below this costs a walk from the enclosing keyframe. */
+    readonly reachableFromS: number;
+    /** Every frame the decoder has output since open, discarded pre-roll
+     *  included; monotonic. */
+    readonly framesDecoded: number;
+}
+/**
+ * One long-lived VideoDecoder, held across seeks.
+ *
+ * A decoder can only ever move forward, and every flush re-arms its demand for a
+ * key frame, so a runtime that flushes per retrieval pays a walk back to the
+ * nearest true IDR on every seek. This session flushes only at end of stream:
+ * a seek at-or-ahead of the read head, inside the current anchor span, decodes
+ * only the packets between the two, and a backward jump or a jump past the span
+ * re-anchors. Positioning is the only thing that costs a walk.
+ *
+ * One decoder serving several readers is the whole point, and it is also the
+ * hazard: a scrub's frameAt and playback's framesFrom drive the same decoder,
+ * the same packet iterator, and the same queue of decoded frames. So every
+ * retrieval takes the decoder exclusively for the length of one frame, and a
+ * reader displaced by someone else's re-anchor is told, rather than left to read
+ * the emptied queue as end of stream and stop for good.
+ *
+ * Frames are handed out as VideoSampleLike and their close is the caller's, the
+ * same obligation the zero-copy sample path carries.
+ */
+export declare class DecodeSession implements SessionFrameSource {
+    private readonly options;
+    private readonly keyPacket;
+    private readonly prefixWidth;
+    private decoder;
+    private iterator;
+    private peeked;
+    /** Timestamp of the key packet after the anchor: the end of the span a
+     *  forward seek can reach without re-anchoring. */
+    private spanEndS;
+    private exhausted;
+    /** Timings the decoder still owes pictures for, in presentation order. */
+    private readonly pending;
+    private readonly decoded;
+    private wake;
+    /**
+     * Latched once the decoder is judged unable to decode this source at all.
+     * Every later retrieval refuses with it instead of re-anchoring onto the
+     * same failure, which is what turns a silent forever-retry into one honest
+     * error the caller can show.
+     */
+    private stalledError;
+    /**
+     * The current entry point's failure, held only until the walk that is owed a
+     * picture decides what it means. It condemns the anchor, never the session:
+     * a source whose sync table names one bad entry point still decodes from
+     * every other one, and latching the first failure is what turned a seek into
+     * a poisoned GOP into a player that never painted again.
+     */
+    private anchorError;
+    /** The entry currently feeding the decoder, or null before the first one. */
+    private entry;
+    /** Entry points a decoder error has ruled out, by whole-microsecond
+     *  timestamp. Only ever grows: a bitstream does not change. */
+    private readonly rejectedAnchors;
+    /** Where the live retrieval wants to be, so a re-anchor after a failed entry
+     *  aims at the position the caller asked for rather than the anchor's. */
+    private entryTargetS;
+    /** The last picture handed out since the caller last chose a position, so a
+     *  re-anchor mid-walk resumes rather than replays. */
+    private servedS;
+    private closed;
+    private anchors;
+    private framesDecodedCount;
+    /** Where the decoder sits, kept in step with what it hands out. Read
+     *  synchronously by callers deciding what to ask for, so it cannot await. */
+    private reachable;
+    /** Serializes retrievals; see the class note on shared-decoder exclusivity. */
+    private tail;
+    /** Bumped by every re-anchor, so a reader can tell whether the decoder is
+     *  still where it left it or has been moved under it by another reader. */
+    private epoch;
+    private readonly outputTimeoutMs;
+    private readonly rotation;
+    constructor(options: DecodeSessionOptions);
+    /** Times the session has configured the decoder onto an anchor. */
+    get anchorCount(): number;
+    /** Every frame the decoder has ever output, including walk pre-roll that is
+     *  discarded before the target: the honest denominator for what a paint
+     *  actually cost. Monotonic for the session's lifetime. */
+    get framesDecoded(): number;
+    /** See SessionFrameSource. The oldest frame decoded but not yet handed out
+     *  when there is one, since those are still servable, else the last position
+     *  handed out. */
+    get reachableFromS(): number;
+    /** The frame at or before `targetS`, or null when nothing precedes it. */
+    frameAt(targetS: number): Promise<VideoSampleLike | null>;
+    /**
+     * Frames from `startS` onward, beginning at the frame at or before it. The
+     * walk from the anchor up to `startS` is decoded but not yielded, since the
+     * caller asked to start there.
+     *
+     * Playback rides this for the length of a session, so it outlives any number
+     * of scrubs. When one of those moved the decoder, the walk resumes from the
+     * last frame it handed out rather than ending.
+     */
+    framesFrom(startS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+    /**
+     * Every frame decoded while covering `[startS, endS]`, including the walk
+     * from the anchor. Those prefix frames cost the same decode either way, so
+     * yielding them hands the caller a span of frames for the price of the one
+     * it asked for.
+     *
+     * This serves speculative sweeps, so a re-anchor by anyone else ends it:
+     * chasing the span back would spend a foreground decode's worth of decoder
+     * time on frames nobody is waiting for.
+     */
+    framesCovering(startS: number, endS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+    /**
+     * Runs `op` with the decoder to itself. Retrievals interleave at frame
+     * granularity, which bounds how long a foreground seek waits behind a
+     * background sweep at one frame, while keeping any one walk's view of the
+     * packet iterator, the in-flight count, and the decoded queue consistent.
+     */
+    private exclusive;
+    /**
+     * The first frame after `afterS` once another reader has moved the decoder.
+     * Re-positions and discards the frames already handed out, so a walk picks
+     * up exactly where it left off however far away the decoder was taken.
+     */
+    private resumeAfter;
+    close(): void;
+    /** Decodes through `targetS` and returns the last frame at or before it,
+     *  closing the frames walked past. */
+    private land;
+    private positionFor;
+    /** The earliest position still reachable without re-anchoring: the oldest
+     *  frame decoded but not yet handed out, or the next packet in line when
+     *  there is none. Decode runs ahead of the read, so the packet alone would
+     *  put the head past frames the session can still serve. */
+    private readHeadS;
+    private anchorAt;
+    /**
+     * The packet to open a decode of `targetS` from: the container's own sync
+     * sample, unless a decoder has already proved that one is not a legal entry
+     * point, in which case the last verified IDR at or before the target.
+     *
+     * A sync sample that is itself an IDR is already the furthest-back entry
+     * worth reaching for, so a failure there is a failure of the source.
+     */
+    private resolveEntry;
+    /**
+     * Where the span a forward seek can reach without re-anchoring ends: the
+     * first sync sample past the target that is still worth anchoring at.
+     *
+     * Skipping the rejected ones is what keeps the pre-roll paid for once. Ending
+     * the span at an entry point already known not to decode would send the very
+     * next seek into that GOP back to the same rejected anchor and back through
+     * the same walk to recover from it.
+     */
+    private spanEndAfter;
+    /** Drops the work in flight and the frames it produced, in one turn, so no
+     *  output from the old anchor can land against the new one. */
+    private quiesce;
+    private configureDecoder;
+    /** One frame at or before `boundS`, or null once the bound is passed. A frame
+     *  decoded past the bound stays queued for the next read rather than being
+     *  handed out or thrown away. */
+    private pull;
+    /**
+     * Re-opens the decode from the last entry point ahead of the failed one,
+     * which for an open GOP means the previous IDR plus a walk to the target.
+     *
+     * The failed anchor is struck off for the life of the session, so the cost is
+     * paid once per bad entry point rather than once per seek into it. When there
+     * is nothing further back to enter from, the failure is the source's and it
+     * latches here.
+     */
+    private enterFurtherBack;
+    /**
+     * Keeps the decoder's pipeline fed, regardless of which frame is being read.
+     * A decoder emits nothing until it holds enough pictures, so submitting only
+     * as far as the requested frame leaves the session waiting on output it is
+     * refusing to make possible. Feeding stops once the frames already decoded
+     * pile up, which is what bounds the memory the session holds.
+     */
+    private fill;
+    private peek;
+    private drain;
+    private awaitOutput;
+    /**
+     * Files a submitted chunk's timing in presentation order, which is the order
+     * pictures come back in and is not the order chunks go in on a B-frame
+     * source.
+     */
+    private awaitTiming;
+    /**
+     * A decoder that echoes the timestamp it was handed names its own pending
+     * entry, which survives an output being dropped. One that counts from an
+     * origin of its own names nothing, and position is all that is left. Taking
+     * position alone would let a single dropped output shift every picture after
+     * it onto the wrong detections, permanently and without a symptom.
+     */
+    private claimTiming;
+    private receive;
+    private fail;
+    /** 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. */
+    private stall;
+    private latch;
+    private discardDecoded;
+}
+//# sourceMappingURL=decode-session.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"decode-session.d.ts","sourceRoot":"","sources":["../src/decode-session.ts"],"names":[],"mappings":"AAKA,OAAO,EAAe,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAGtD;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,IAAI,EAAE,KAAK,GAAG,OAAO,CAAC;IAC/B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;CAC3B;AAED,MAAM,WAAW,0BAA0B;IACzC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;CACrC;AAED,+EAA+E;AAC/E,MAAM,WAAW,YAAY;IAC3B,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACrC,gBAAgB,CACd,MAAM,EAAE,iBAAiB,EACzB,OAAO,CAAC,EAAE,0BAA0B,GACnC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACrC,OAAO,CACL,WAAW,CAAC,EAAE,iBAAiB,EAC/B,SAAS,CAAC,EAAE,iBAAiB,EAC7B,OAAO,CAAC,EAAE,0BAA0B,GACnC,cAAc,CAAC,iBAAiB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CACrD;AAED;qEACqE;AACrE,MAAM,WAAW,gBAAgB;IAC/B,SAAS,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAC5C,MAAM,CAAC,KAAK,EAAE,qBAAqB,GAAG,IAAI,CAAC;IAC3C,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACvB,KAAK,IAAI,IAAI,CAAC;IACd,KAAK,IAAI,IAAI,CAAC;CACf;AAkDD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,OAAO,EAAE,YAAY,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,aAAa,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,gBAAgB,CAAC;IACrE;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAyED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,kBAAkB,GAAG,OAAO,CAEnE;AAED;;;;GAIG;AACH,MAAM,WAAW,kBAAkB;IACjC,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAC1D,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3E,cAAc,CACZ,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAClD;;mFAE+E;IAC/E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC;+BAC2B;IAC3B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;CAChC;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,aAAc,YAAW,kBAAkB;IAyD1C,OAAO,CAAC,QAAQ,CAAC,OAAO;IAxDpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;IACjD,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,OAAO,CAAiC;IAChD,OAAO,CAAC,QAAQ,CACT;IACP,OAAO,CAAC,MAAM,CAAkC;IAChD;uDACmD;IACnD,OAAO,CAAC,QAAQ,CAAY;IAC5B,OAAO,CAAC,SAAS,CAAQ;IACzB,0EAA0E;IAC1E,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAsB;IAC9C,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAwB;IAChD,OAAO,CAAC,IAAI,CAA6B;IACzC;;;;;OAKG;IACH,OAAO,CAAC,YAAY,CAAiC;IACrD;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAiC;IACpD,6EAA6E;IAC7E,OAAO,CAAC,KAAK,CAA4B;IACzC;mEAC+D;IAC/D,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAqB;IACrD;8EAC0E;IAC1E,OAAO,CAAC,YAAY,CAAK;IACzB;0DACsD;IACtD,OAAO,CAAC,OAAO,CAAa;IAC5B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAK;IACpB,OAAO,CAAC,kBAAkB,CAAK;IAC/B;iFAC6E;IAC7E,OAAO,CAAC,SAAS,CAAa;IAC9B,+EAA+E;IAC/E,OAAO,CAAC,IAAI,CAAuC;IACnD;+EAC2E;IAC3E,OAAO,CAAC,KAAK,CAAK;IAElB,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAS;IAEzC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAW;gBAEP,OAAO,EAAE,oBAAoB;IAc1D,mEAAmE;IACnE,IAAI,WAAW,IAAI,MAAM,CAExB;IAED;;+DAE2D;IAC3D,IAAI,aAAa,IAAI,MAAM,CAE1B;IAED;;sBAEkB;IAClB,IAAI,cAAc,IAAI,MAAM,CAI3B;IAED,0EAA0E;IACpE,OAAO,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC;IAK/D;;;;;;;;OAQG;IACI,UAAU,CACf,MAAM,EAAE,MAAM,GACb,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC;IAgBjD;;;;;;;;;OASG;IACI,cAAc,CACnB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC;IAmBjD;;;;;OAKG;IACH,OAAO,CAAC,SAAS;IASjB;;;;OAIG;YACW,WAAW;IAUzB,KAAK,IAAI,IAAI;IAab;0CACsC;YACxB,IAAI;YAWJ,WAAW;IAYzB;;;gEAG4D;YAC9C,SAAS;YAOT,QAAQ;IAoBtB;;;;;;;OAOG;YACW,YAAY;IAiB1B;;;;;;;;OAQG;YACW,YAAY;IAqB1B;mEAC+D;IAC/D,OAAO,CAAC,OAAO;IAMf,OAAO,CAAC,gBAAgB;IA0BxB;;qCAEiC;YACnB,IAAI;IAqClB;;;;;;;;OAQG;YACW,gBAAgB;IAW9B;;;;;;OAMG;YACW,IAAI;YAsCJ,IAAI;YAYJ,KAAK;IAQnB,OAAO,CAAC,WAAW;IAwCnB;;;;OAIG;IACH,OAAO,CAAC,WAAW;IAMnB;;;;;;OAMG;IACH,OAAO,CAAC,WAAW;IASnB,OAAO,CAAC,OAAO;IAWf,OAAO,CAAC,IAAI;IAUZ;;+CAE2C;IAC3C,OAAO,CAAC,KAAK;IAUb,OAAO,CAAC,KAAK;IAKb,OAAO,CAAC,cAAc;CAIvB"}

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

@@ -0,0 +1,250 @@
+import { BlobSource, ReadableStreamSource, UrlSource } from "mediabunny";
+import type { CreateScrubCursorOptions } from "./create-scrub-cursor";
+import { type SessionFrameSource } from "./decode-session";
+import type { SourceResidency } from "./source-residency";
+import type { KeyframeProbe } from "./keyframe-index";
+import { type ScrubTrackInfo, type VideoSampleLike } from "./scrub-cursor";
+import { type DecodePath, type UrlSourceReadConfig, type UrlVideoSource, type VideoSource } from "./types";
+/**
+ * A decoded frame handle: the slice of mediabunny's WrappedCanvas the runtime
+ * paints, caches, and extracts. Only the canvas and its presentation timestamp
+ * matter.
+ */
+export interface WrappedCanvasLike {
+    readonly canvas: OffscreenCanvas | HTMLCanvasElement;
+    readonly timestamp: number;
+}
+/**
+ * The slice of mediabunny's CanvasSink the runtime decodes through. getCanvas
+ * does the random-access keyframe walk and GOP decode internally; canvases
+ * streams forward for playback and stepping; canvasesAtTimestamps decodes a set
+ * of sorted timestamps in one pass (the prefetch window and frame extraction).
+ */
+export interface CanvasFrameSource {
+    getCanvas(timestampS: number): Promise<WrappedCanvasLike | null>;
+    canvases(startS: number): AsyncGenerator<WrappedCanvasLike, void, unknown>;
+    canvasesAtTimestamps(timestamps: Iterable<number>): AsyncGenerator<WrappedCanvasLike | null, void, unknown>;
+}
+/**
+ * The opened decode primitives for one source: resolved track facts plus the
+ * two sinks the runtime rides. Built once by openDecodeSource, so a consumer
+ * never imports mediabunny and stays fake-injectable under test. This seam is
+ * shared by the playback cursors and the playback-independent AnalysisSession,
+ * so it lives here next to its producer rather than inside any one consumer.
+ */
+export interface DecodeSourceHandle {
+    readonly track: ScrubTrackInfo;
+    readonly sink: CanvasFrameSource;
+    readonly keyframeProbe: KeyframeProbe;
+    dispose(): Promise<void>;
+}
+/**
+ * The slice of mediabunny's VideoSampleSink the runtime decodes through, mirror
+ * for mirror with CanvasFrameSource but yielding live VideoSamples the zero-copy
+ * WebGPU path imports directly. The sink yields raw samples; the cursor wraps
+ * each in idempotentSample before emitting so the close obligation is safe to
+ * discharge from every path.
+ */
+export interface SampleFrameSource {
+    getSample(timestampS: number): Promise<VideoSampleLike | null>;
+    samples(startS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+    samplesAtTimestamps(timestamps: Iterable<number>): AsyncGenerator<VideoSampleLike | null, void, unknown>;
+}
+/**
+ * The opened decode primitives for the zero-copy sample path: the same resolved
+ * track facts and keyframe probe as DecodeSourceHandle, with the VideoSampleSink
+ * standing in for the CanvasSink. Built only where zeroCopyViable approves the
+ * path, so the rest of the runtime never reaches it by accident.
+ */
+export interface SampleSourceHandle {
+    readonly track: ScrubTrackInfo;
+    readonly sampleSink: SampleFrameSource;
+    readonly keyframeProbe: KeyframeProbe;
+    dispose(): Promise<void>;
+}
+/**
+ * The opened decode primitives for the long-lived-decoder path: the same
+ * resolved track facts and keyframe probe as the sink handles, with a
+ * DecodeSession standing in for the sink. Built only where decodeSessionViable
+ * approves the path.
+ */
+export interface SessionSourceHandle {
+    readonly track: ScrubTrackInfo;
+    readonly session: SessionFrameSource;
+    readonly keyframeProbe: KeyframeProbe;
+    dispose(): Promise<void>;
+}
+/**
+ * One decoded frame, tagged by which sink produced it. A canvas frame from the
+ * CanvasSink path; a sample frame from the VideoSampleSink path, carrying a live
+ * VideoSample the cursor owns the close of. The cursor turns each into the
+ * matching ScrubFrame kind, so the canvas-vs-sample branch lives in one place
+ * rather than forking every cursor method.
+ */
+export type DecodedFrame = {
+    readonly kind: "canvas";
+    readonly canvas: OffscreenCanvas | HTMLCanvasElement;
+    readonly timestamp: number;
+} | {
+    readonly kind: "sample";
+    readonly sample: VideoSampleLike;
+    readonly timestamp: number;
+};
+/**
+ * The decode seam both cursors ride, normalized over the two sink kinds: a
+ * random-access read, a forward stream, and a sorted-timestamp batch, each
+ * yielding a DecodedFrame. The provider also names the path it was built over,
+ * which the scheduler reports so a human can see which machinery is decoding.
+ */
+export interface FrameProvider {
+    readonly decodePath: DecodePath;
+    readonly track: ScrubTrackInfo;
+    readonly keyframeProbe: KeyframeProbe;
+    getFrame(timestampS: number): Promise<DecodedFrame | null>;
+    frames(startS: number): AsyncGenerator<DecodedFrame, void, unknown>;
+    framesAt(timestamps: Iterable<number>): AsyncGenerator<DecodedFrame | null, void, unknown>;
+    /**
+     * Whether reaching `timestampS` would restart this provider from a keyframe
+     * and decode everything in between. Only the long-lived decode session ever
+     * answers true: the sink paths re-position per retrieval, so nothing they
+     * are asked for is dearer than anything else.
+     */
+    wouldReanchor(timestampS: number): boolean;
+    /**
+     * Decoded frames a consumer may hold ahead of the playhead. Only the
+     * zero-copy sample sink is constrained here: each of its frames pins a slot
+     * in a fixed pool, so a deep queue starves the decoder that fills it. The
+     * other paths hand out frames they own, and a cushion is what stops a decode
+     * that overruns one frame interval from starving the next paint.
+     */
+    readonly playReadAhead: number;
+    /**
+     * Frames the decode machinery has produced since open, monotonic. On the
+     * session path this counts every decoder output including discarded walk
+     * pre-roll; the sink paths can only count what mediabunny yields, so their
+     * figure is a floor, not the decoder's true output.
+     */
+    framesDecoded(): number;
+    dispose(): Promise<void>;
+}
+/**
+ * The forward-sample seam a batch range walk reads: the track's own timing
+ * origin and one stream of its frames in presentation order. Both sample-
+ * yielding paths present this shape, so the walk never branches on which decoder
+ * it got, and every sample it hands over carries a close obligation.
+ */
+export interface WalkFrameSource {
+    readonly track: ScrubTrackInfo;
+    framesFrom(startS: number): AsyncGenerator<VideoSampleLike, void, unknown>;
+}
+/** A walk source and its disposal, held by whoever opened it. */
+export interface WalkSourceHandle extends WalkFrameSource {
+    dispose(): Promise<void>;
+}
+/** Discriminates the opened-source handle shapes at the cursor boundary. */
+export type AnySourceHandle = DecodeSourceHandle | SampleSourceHandle | SessionSourceHandle;
+/**
+ * Wraps any opened-source handle in the unified FrameProvider. The two sample
+ * paths wrap each yielded VideoSample in idempotentSample so the cursor can
+ * discharge the close obligation from any path without double-free.
+ */
+export declare function openFrameProvider(handle: AnySourceHandle): FrameProvider;
+/**
+ * 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
+ * described handle and never touches mediabunny or the resolution math. Playback
+ * consumers call openScrubSource instead and take whatever path the source
+ * supports; this is for consumers that want canvases specifically.
+ */
+export declare function openDecodeSource(options: CreateScrubCursorOptions): Promise<DecodeSourceHandle>;
+/**
+ * Opens a source and routes it to the fastest decode path it supports: the
+ * long-lived DecodeSession, then the zero-copy VideoSampleSink, then the
+ * CanvasSink.
+ *
+ * The session's condition is the track's codec, which nothing can answer until
+ * the container has been read, so the input opens first and the path is chosen
+ * against what the opened track reports. The one input then serves whichever
+ * path won.
+ */
+export declare function openScrubSource(options: CreateScrubCursorOptions): Promise<AnySourceHandle>;
+/**
+ * Opens a source for a batch walk over its frames, on its own input and its own
+ * decoder. A walk reads thousands of frames in a row and a playback cursor is
+ * serving a screen, so the two never share: whatever a walk does to its read
+ * head, no gesture is waiting behind it.
+ *
+ * The CanvasSink path is not offered here. It yields recycled canvases with no
+ * duration and no close, and a walk's whole contract is real frames with the
+ * timing they were encoded with, so a source that cannot present samples cannot
+ * be walked. Frames arrive at the source's native resolution; nothing downscales
+ * them on the way out.
+ */
+export declare function openWalkSource(source: VideoSource): Promise<WalkSourceHandle>;
+/**
+ * Inputs the zero-copy gate reasons over. Held as data, not probed live, so the
+ * predicate is pure and unit-testable: the caller measures the realm once and
+ * passes the facts in.
+ */
+export interface ZeroCopyContext {
+    /** True when the consumer pinned the 2D renderer. */
+    readonly prefer2d: boolean;
+    /** Whether decode runs at the source's native size (the strategy requests no
+     *  downscale). A downscale rules the path out: the sample arrives native, so
+     *  importing it zero-copy would paint at the wrong resolution. */
+    readonly decodesNative: boolean;
+    /** Whether the worker realm has WebGPU with importExternalTexture, the API
+     *  the zero-copy import needs. */
+    readonly webgpuImportAvailable: boolean;
+}
+/**
+ * The gate. True only when every condition holds: the 2D path is not pinned, the
+ * strategy decodes at native (no downscale), and the realm offers WebGPU's
+ * importExternalTexture. False keeps the byte-identical CanvasSink path; this is
+ * the one place the additive path is allowed to switch on.
+ */
+export declare function zeroCopyViable(ctx: ZeroCopyContext): boolean;
+/**
+ * Inputs the long-lived-decoder gate reasons over, held as data for the same
+ * reason ZeroCopyContext is.
+ *
+ * Decode resolution is deliberately absent. The session owns its decoder and
+ * always decodes at the source's native size, so a requested downscale is a
+ * canvas and cache concern rather than a reason to refuse the path.
+ */
+export interface DecodeSessionContext {
+    /** Whether this realm has WebCodecs. The session builds and drives its own
+     *  VideoDecoder rather than decoding through a mediabunny sink. */
+    readonly videoDecoderAvailable: boolean;
+    /** The opened track's decoder config, which decides whether the session's
+     *  anchor trick applies to this bitstream. */
+    readonly decoderConfig: VideoDecoderConfig;
+}
+/**
+ * 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
+ * every other source keeps the mediabunny sinks.
+ */
+export declare function decodeSessionViable(ctx: DecodeSessionContext): boolean;
+/** Whether this realm exposes the WebCodecs decoder the session constructs. */
+export declare function detectVideoDecoder(): boolean;
+/**
+ * Probes the worker realm for WebGPU with importExternalTexture. Checks for the
+ * method on the prototype rather than acquiring a device, so it is synchronous
+ * and cheap; the actual device acquisition still happens (and can still fail
+ * back to 2D) in the renderer.
+ */
+export declare function detectWebgpuImport(): boolean;
+export declare function urlRequestInit(crossOrigin: UrlVideoSource["crossOrigin"]): {
+    requestInit: RequestInit;
+} | undefined;
+export declare function toMediabunnySource(source: VideoSource, residency?: SourceResidency, urlSource?: UrlSourceReadConfig): UrlSource | BlobSource | ReadableStreamSource;
+/**
+ * Whether a source can be opened a second time, which the hang-recovery path
+ * needs to rebuild a wedged decoder. A URL re-fetches and a Blob re-reads, so
+ * both re-open cleanly. A ReadableStream is consumed once and cannot be rewound,
+ * so a rebuild on it would open onto an exhausted stream; the watchdog falls back
+ * to a degraded-but-alive state instead of rebuilding for that kind.
+ */
+export declare function isReopenableSource(source: VideoSource): boolean;
+//# sourceMappingURL=decode-source.d.ts.map

package/dist/web-video-engine/decode-source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"decode-source.d.ts","sourceRoot":"","sources":["../src/decode-source.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,UAAU,EAIV,oBAAoB,EAEpB,SAAS,EAEV,MAAM,YAAY,CAAC;AAGpB,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACtE,OAAO,EAGL,KAAK,kBAAkB,EAExB,MAAM,kBAAkB,CAAC;AAO1B,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAEL,KAAK,cAAc,EACnB,KAAK,eAAe,EACrB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,mBAAmB,EACxB,KAAK,cAAc,EACnB,KAAK,WAAW,EACjB,MAAM,SAAS,CAAC;AAEjB;;;;GAIG;AACH,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;;;GAKG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;IACjE,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,iBAAiB,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IAC3E,oBAAoB,CAClB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,cAAc,CAAC,iBAAiB,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CAC5D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,iBAAiB,CAAC;IACjC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,iBAAiB;IAChC,SAAS,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAAC;IAC/D,OAAO,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACxE,mBAAmB,CACjB,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,cAAc,CAAC,eAAe,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CAC1D;AAED;;;;;GAKG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,UAAU,EAAE,iBAAiB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,OAAO,EAAE,kBAAkB,CAAC;IACrC,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,MAAM,YAAY,GACpB;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,GAAG,iBAAiB,CAAC;IACrD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,GACD;IACE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,CAAC;AAEN;;;;;GAKG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,QAAQ,CAAC,aAAa,EAAE,aAAa,CAAC;IACtC,QAAQ,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,GAAG,IAAI,CAAC,CAAC;IAC3D,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,YAAY,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACpE,QAAQ,CACN,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,GAC3B,cAAc,CAAC,YAAY,GAAG,IAAI,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;IACtD;;;;;OAKG;IACH,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C;;;;;;OAMG;IACH,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B;;;;;OAKG;IACH,aAAa,IAAI,MAAM,CAAC;IACxB,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED;;;;;GAKG;AACH,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,CAAC,eAAe,EAAE,IAAI,EAAE,OAAO,CAAC,CAAC;CAC5E;AAED,iEAAiE;AACjE,MAAM,WAAW,gBAAiB,SAAQ,eAAe;IACvD,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,4EAA4E;AAC5E,MAAM,MAAM,eAAe,GACzB,kBAAkB,GAAG,kBAAkB,GAAG,mBAAmB,CAAC;AAYhE;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,eAAe,GAAG,aAAa,CAIxE;AAgHD;;;;;;GAMG;AACH,wBAAsB,gBAAgB,CACpC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,kBAAkB,CAAC,CAK7B;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,eAAe,CAAC,CAsB1B;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,gBAAgB,CAAC,CAe3B;AA2QD;;;;GAIG;AACH,MAAM,WAAW,eAAe;IAC9B,qDAAqD;IACrD,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;sEAEkE;IAClE,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC;sCACkC;IAClC,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;CACzC;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,eAAe,GAAG,OAAO,CAK5D;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,oBAAoB;IACnC;uEACmE;IACnE,QAAQ,CAAC,qBAAqB,EAAE,OAAO,CAAC;IACxC;kDAC8C;IAC9C,QAAQ,CAAC,aAAa,EAAE,kBAAkB,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,OAAO,CAGtE;AAED,+EAA+E;AAC/E,wBAAgB,kBAAkB,IAAI,OAAO,CAK5C;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAQ5C;AAED,wBAAgB,cAAc,CAC5B,WAAW,EAAE,cAAc,CAAC,aAAa,CAAC,GACzC;IAAE,WAAW,EAAE,WAAW,CAAA;CAAE,GAAG,SAAS,CAQ1C;AAED,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,WAAW,EACnB,SAAS,CAAC,EAAE,eAAe,EAC3B,SAAS,CAAC,EAAE,mBAAmB,GAC9B,SAAS,GAAG,UAAU,GAAG,oBAAoB,CAuB/C;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAE/D"}

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

@@ -0,0 +1,18 @@
+import type { DiagnosticsSnapshot } from "./diagnostics";
+/**
+ * Sibling of MirrorStore for the diagnostics broadcast plane. A single
+ * channel holding the latest snapshot, shaped for useSyncExternalStore. Fed only
+ * by the 'diag' event; the playback mirror store and its subscribers never touch
+ * it, so a 10Hz diagnostics push never wakes a playback consumer.
+ *
+ * getSnapshot returns the same reference between writes, so a selector using
+ * Object.is short-circuits when nothing changed.
+ */
+export declare class DiagnosticsStore {
+    private snapshot;
+    private readonly listeners;
+    getSnapshot(): DiagnosticsSnapshot | null;
+    write(snapshot: DiagnosticsSnapshot): void;
+    subscribe(listener: () => void): () => void;
+}
+//# sourceMappingURL=diagnostics-store.d.ts.map

package/dist/web-video-engine/diagnostics-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics-store.d.ts","sourceRoot":"","sources":["../src/diagnostics-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,eAAe,CAAC;AAEzD;;;;;;;;GAQG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAoC;IACpD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAyB;IAEnD,WAAW,IAAI,mBAAmB,GAAG,IAAI;IAIzC,KAAK,CAAC,QAAQ,EAAE,mBAAmB,GAAG,IAAI;IAK1C,SAAS,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;CAM5C"}