supervision 0.1.7 → 0.2.0-next.1

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

@@ -0,0 +1,371 @@
+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, WebVideoEngineError } from "./types";
+export interface DecodeSchedulerOptions {
+    readonly source: AnySourceHandle;
+    readonly cache: FrameCache;
+    /** A cache hit within this of the target serves a crisp frame; default 50. */
+    readonly exactToleranceMs?: number;
+    /** A coarse hit within this of the target serves a preview; default 250. */
+    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
+     * AbortSignal, so a hung decode is uncancellable; the watchdog disposes the
+     * dead provider and rebuilds from this seam so later decodes work. Omitted in
+     * tests that do not exercise recovery, where the scheduler degrades instead.
+     */
+    readonly reopen?: (() => Promise<AnySourceHandle>) | null;
+    /**
+     * Hang ceiling for one random-access decode; defaults to the runtime
+     * constant. A decode that outruns it is treated as failed and triggers
+     * provider recovery. Overridable so a test can drive it with fake timers at a
+     * small value.
+     */
+    readonly decodeHangTimeoutMs?: number;
+    /**
+     * Hang ceiling for the first-frame seed; defaults to the runtime constant,
+     * which is tighter than the one above. Overridable so a test can drive it
+     * with fake timers at a small value.
+     */
+    readonly seedHangTimeoutMs?: number;
+    /**
+     * Called once, with the failure, when the decoder is judged unable to decode
+     * this source at all. Nothing else tells a consumer: a stalled decoder still
+     * 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: 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
+ * a decode window around the playhead so the next move is already in hand.
+ *
+ * A scrub first reads the cache. An exact hit needs no decode. A preview hit
+ * paints a coarse frame at once, then a crisp decode follows. A miss decodes
+ * straight away. Once the foreground frame settles, a background sweep fills the
+ * cache around the playhead, shaped by how the consumer is moving: neighbor
+ * frames while scrubbing or stepping, a coarse keyframe pass while idle.
+ *
+ * A new gesture signals the sweep to bail and proceeds without waiting for it, so
+ * speculative work never sits on the critical path; mediabunny builds a decoder
+ * per iterator, so a sweep still unwinding alongside a foreground decode costs
+ * memory, not correctness. Every decoded frame is copied into the cache, never
+ * held as a raw VideoFrame, so the decoder is never pinned.
+ */
+export declare class DecodeScheduler implements ScrubCursor {
+    private provider;
+    private readonly cache;
+    private keyframeIndex;
+    private readonly trackInfo;
+    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;
+    private readonly seedHangTimeoutMs;
+    /** Single-flight latch: a watchdog recovery already running. A second hang
+     *  during the rebuild awaits the same recovery rather than racing a second
+     *  dispose/rebuild of the provider. */
+    private recovering;
+    /** True once a hang hit a non-re-openable source: the provider is dead and
+     *  could not be rebuilt, so decodes no-op rather than hang. Surfaced via stats
+     *  so a consumer can show a degraded state instead of a silent freeze. */
+    private decoderDead;
+    /** Consecutive failed rebuilds. One is a transient read; a run of them is a
+     *  source that cannot be re-opened, which is what decoderDead describes. */
+    private failedRebuilds;
+    /** True once the decoder is judged unable to decode this source at all. See
+     *  SchedulerStats.decoderStalled; latched, and it stops the rebuild loop. */
+    private decoderStalled;
+    /** The failure markStalled latched, so a caller still awaiting a decode is
+     *  handed the same one the consumer was told about rather than a parallel
+     *  account of it. */
+    private stallFailure;
+    /** Decode requests the live provider has left unanswered in a row; see
+     *  MAX_UNANSWERED_DECODES. */
+    private unansweredDecodes;
+    private readonly onDecodeFailure;
+    private iterator;
+    private nextInFlight;
+    private nextPending;
+    private currentState;
+    private readonly listeners;
+    private idleResolvers;
+    private settleResolvers;
+    private pendingSeekTargetS;
+    private pendingSeekKeyOnly;
+    private seekDraining;
+    private closed;
+    private lastEmittedFrame;
+    private mode;
+    /** Recent scrub motion. Only its heading is read, which is what decides the
+     *  side of the playhead a scrub window spends most of its budget on. */
+    private readonly trajectory;
+    /** 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;
+    /** Whether a sweep is still depending on the live token. Cleared both by the
+     *  cancellation that supersedes the sweep and by the sweep finishing. */
+    private prefetchArmed;
+    /** Woken when the token moves, so a sweep parked on a decode unwinds at the
+     *  gesture rather than at the end of the decode it is parked on. */
+    private abandonResolvers;
+    private scrubSamples;
+    private scrubSumMs;
+    private scrubMaxMs;
+    private scrubLastMs;
+    /** Ring of recent scrub-decode latencies for p50/p95. Overwrite-oldest so the
+     *  percentile tracks the recent region, not an all-time tail. One push/seek. */
+    private readonly scrubLatencyRing;
+    private scrubLatencyCount;
+    private scrubLatencyHead;
+    private targetVsLandedLastMs;
+    private timeToCrispLastMs;
+    private foregroundDecodes;
+    private prefetchExactFrames;
+    private prefetchPreviewFrames;
+    private keyframeAnchoredEmits;
+    private exactSeeks;
+    private keySeeks;
+    private seekCoalesceOverwrites;
+    constructor(options: DecodeSchedulerOptions);
+    get state(): ScrubCursorState;
+    get track(): ScrubTrackInfo;
+    get playReadAhead(): number;
+    get isIdle(): boolean;
+    open(): Promise<void>;
+    /**
+     * The first frame, on the seed ceiling and its own attempt budget.
+     *
+     * A decoder that accepts this decode and never answers it is the one failure
+     * the rest of the machinery cannot see: nothing has been asked of it twice
+     * yet, so no request budget can run out, and open() is what the load path
+     * awaits, so the wait ends only when the caller above gives up on the whole
+     * worker. Bounding it here turns that into a decoder failure named at the
+     * point it happened.
+     *
+     * Attempts are spent against rebuilt providers wherever the source can be
+     * re-opened, so exhausting them means the source was re-opened that many
+     * times and the first frame never arrived.
+     */
+    private seedFirstFrame;
+    /**
+     * Synchronous best-effort lookup the render loop calls on scrub to paint a
+     * frame this same tick. Pure: it reads the cache and returns a paintable
+     * frame without touching decode or cursor state.
+     */
+    peekCached(timeMs: number): ScrubFrame | null;
+    /**
+     * Resolves once foreground work has settled and any background prefetch
+     * kicked by that settle has drained. The plain idle() contract excludes
+     * prefetch so commits resolve promptly; this awaits full quiescence.
+     */
+    whenSettled(): Promise<void>;
+    /**
+     * Walks the whole track's keyframes into the index, metadata only, so the
+     * diagnostics keyframe lane fills out across the entire file. Decoder-less
+     * (it rides the EncodedPacketSink probe, never the frame sink), so it does
+     * not contend with the foreground decode. Idempotent and best-effort: a
+     * failure just leaves the lane as sparse as the lazy probes made it.
+     */
+    ensureKeyframeIndex(): Promise<void>;
+    getStats(): SchedulerStats;
+    /** Percentile over the bounded recent-latency ring. Copies the live samples
+     *  into a small scratch array and sorts; bounded by SCRUB_LATENCY_RING, and
+     *  this runs only at snapshot time, never per seek. */
+    private scrubPercentile;
+    /** The targets the next prefetch sweep would decode for the current mode
+     *  and position; a pure recompute from existing state. The Idle plan is
+     *  built from the keyframes discovered so far, so it grows as the index
+     *  learns, exactly like the sweep it predicts. */
+    private prefetchPlanMs;
+    seekTo(timestamp: Sec, intent?: SeekIntent): void;
+    seekToKey(timestamp: Sec): void;
+    /** Floors a seek target to the track's first timestamp. A seek below the
+     *  origin (an offset/trimmed clip) has no sample to land on, so it would
+     *  emit nothing; clamping lands it on the first frame instead. */
+    private clampToOrigin;
+    /** Motion sampled across a pause, a step, or a stretch of playback describes
+     *  no hand still on the timeline, so leaving a scrub drops the gesture. */
+    private enterMode;
+    attachPlay(startS: number): void;
+    detachPlay(): void;
+    next(): void;
+    /**
+     * Decodes one named frame of the source and emits it.
+     *
+     * The retrieval is at-or-before a time the frame table produced, and the
+     * demuxer normalises that back to the same integer tick it came from, so it
+     * lands on that frame and no other. Nothing here walks, compares or skips,
+     * so a step across a frame boundary needs no epsilon, and a burst of steps
+     * reuses whatever decode position the session already holds, with no
+     * iterator opened per press.
+     */
+    seekToFrame(frame: FrameId): Promise<ScrubFrame | null>;
+    idle(): Promise<void>;
+    seekSettled(): Promise<void>;
+    subscribe(listener: ScrubFrameListener): () => void;
+    close(): Promise<void>;
+    private drainSeek;
+    private runSeek;
+    private runExactSeek;
+    /**
+     * Whether a decode that outlived its target still improves the picture,
+     * judged from where the gesture has since reached. A drag that outruns the
+     * decoder supersedes every decode it starts, and the screen holds something
+     * older than all of them, so refusing the lot pins the picture at whatever
+     * was up when the drag began.
+     *
+     * Only a gesture reads this way. A jump has one destination and no
+     * intermediate positions worth showing, so a superseded decode there is
+     * work for a place nobody is looking.
+     */
+    private gainsOnTarget;
+    /**
+     * Whether a cached frame earns the screen over what is already on it. A
+     * crisp frame always does. A coarse stand-in exists to bridge the wait for a
+     * decode, so it earns the screen only by landing closer to the target than
+     * what is showing: replacing a crisp frame with a blurry one at the same
+     * position is a visible drop in quality for nothing, and on a slow drag,
+     * where each step lands within a frame of the last, it repeats several times
+     * a second and reads as the picture flickering between sharp and soft.
+     */
+    private worthPainting;
+    private runKeySeek;
+    private pullForwardOne;
+    /**
+     * Bounds a decode so a hung mediabunny decode (which takes no AbortSignal and
+     * cannot be cancelled) never wedges the caller. On timeout it returns null and
+     * kicks provider recovery; the orphaned decode promise is abandoned, since
+     * there is no handle to cancel it. The healthy path resolves before the timer
+     * and behaves exactly as a bare await: the loser timer is cleared, so it adds
+     * no work to a decode that lands in time.
+     *
+     * A rejected decode takes the same route as a hung one. Every caller here is
+     * mid-gesture with no way to answer a decode failure other than to try again
+     * on a working decoder, and a throw would escape the fire-and-forget seek
+     * drain and the play pull chain as an unhandled rejection. Taking that route
+     * is also why an unanswered decode has to be counted here: the failure is
+     * absorbed at this one point, so this is the only place that can tell a
+     * decoder having a bad moment from one that will never answer again.
+     */
+    private withDecodeWatchdog;
+    /**
+     * The same watchdog over a container metadata read. Deliberately unbooked:
+     * the keyframe probe never touches the decoder, so its answer is no evidence
+     * that decoding works, and clearing the stall budget on one would keep a
+     * background sweep forgiving a decoder that answers nothing.
+     */
+    private withProbeWatchdog;
+    private watchdogged;
+    private raceWatchdog;
+    /**
+     * Books one decode the live provider failed to answer, and decides whether
+     * to rebuild or to give up. A decoder that refuses outright says so in the
+     * rejection and there is nothing to rebuild toward; otherwise the runtime
+     * rebuilds until the request budget runs out, which is what stops a source
+     * that re-opens cleanly and then decodes nothing from being rebuilt forever
+     * while every surface reads as healthy.
+     */
+    private noteUnanswered;
+    /** Latches the terminal decoder failure and hands it out exactly once. */
+    private markStalled;
+    /**
+     * Rebuilds the decoder after a hung decode. The old provider is wedged on an
+     * uncancellable decode, so it is disposed and a fresh source opened in its
+     * place; the keyframe index is repointed at the new probe since disposing the
+     * old input invalidated the old one. Single-flight: a second hang during the
+     * rebuild awaits the same recovery. When the source cannot be re-opened (a
+     * one-shot stream), the decoder is marked dead so later decodes no-op rather
+     * than hang, leaving the engine degraded but alive instead of frozen.
+     */
+    private recoverDecoder;
+    /**
+     * The only writer of the generation token, so no bump can move it without
+     * also waking the sweep it cancels. A running sweep bails at its next
+     * checkpoint and is never joined: joining it puts an unbounded background
+     * walk on the critical path of every seek and play pull. The task handle
+     * stays so close() can await teardown.
+     */
+    private abandonPrefetch;
+    /** Resolves the moment `gen` stops being the live prefetch generation. */
+    private whenAbandoned;
+    /**
+     * Kicks a background sweep around `aroundS` for the current access mode.
+     * Fire-and-forget: it waits for any prior sweep to tear down so the decoder
+     * is never used twice at once, then runs under a captured generation token.
+     */
+    private schedulePrefetch;
+    private runPrefetch;
+    private runExactWindow;
+    private runPreviewSweep;
+    private decodeInto;
+    /**
+     * One sweep pull, ended by abandonment rather than by the decode it is
+     * waiting on. A native async generator serializes its request queue, so the
+     * return() that cancellation would issue is queued behind the in-flight
+     * next() and lands only once that walk finishes; the pull itself cannot be
+     * called back. The sweep therefore stops awaiting it and leaves it orphaned,
+     * closing the sample it may still deliver, which the cache will never own.
+     */
+    private pullSwept;
+    private windowTimestamps;
+    /**
+     * How a window's slots divide between the way the gesture is heading and the
+     * way it came from. An unmoving gesture has no direction to favour, so it
+     * splits evenly, which is also what a step or an idle settle wants.
+     */
+    private splitByHeading;
+    /**
+     * Whether reaching `t` backwards is worth it, measured in frames the walk
+     * from its keyframe would decode. The index is what the runtime knows so far,
+     * so an empty one is no evidence and does not veto: guessing a source has no
+     * keyframes would throw away every backward slot on a source that has plenty.
+     */
+    private walkToTargetAffordable;
+    /**
+     * Per-side neighbor count for the current mode, clamped so the whole window
+     * (both sides plus the center already in hand) fits the exact tier. A window
+     * wider than the tier would evict its own freshly decoded frames, so a
+     * re-scrub into the swept region would still miss.
+     */
+    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. */
+    private cacheDecoded;
+    private emitCached;
+    private emit;
+    private frameFromCache;
+    private recordScrubLatency;
+    private flushIdleResolvers;
+    private flushSettleResolvers;
+}

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

@@ -0,0 +1,283 @@
+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;
+    /** 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
+     * 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;
+    private readonly outputWidth;
+    private readonly outputHeight;
+    private readonly snapshotFrame;
+    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;
+}