supervision 0.1.7 → 0.2.0-next.0

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

@@ -0,0 +1,1678 @@
+import { CanvasSink, EncodedPacketSink, Input, ALL_FORMATS, VideoSampleSink, ReadableStreamSource, BlobSource, UrlSource, UnsupportedInputFormatError } from 'mediabunny';
+import { V as VideoEngineError, a as VideoEngineErrorCode, S as SCRUB, b as asSec, n as nativeResolution, r as resolveDecodeDimensions, c as SourceKind, F as FRAME_TIMELINE, d as FrameTimeline } from './frame-timeline-GINI8Gum.js';
+
+/**
+ * An H.264 sync sample that is not an IDR frame cannot open a WebCodecs decode
+ * session: Chrome rejects the chunk with "An EncodedVideoChunk was marked as
+ * type key but wasn't a key frame" and emits no frames. Adding a recovery-point
+ * SEI to the access unit declares it a valid entry point, which is enough for the
+ * decoder to accept it and decode forward from there.
+ *
+ * The decoder demands an entry point for exactly one chunk, the first after
+ * configure() or flush(), and putting the SEI on any other chunk misdescribes
+ * the stream. KeyPacketRequirement is what tracks which chunk that is.
+ */
+/**
+ * SEI NAL (unit type 6) carrying one recovery_point payload: recovery_frame_cnt
+ * 0, so this access unit is itself the recovery point, and exact_match_flag 1,
+ * so frames from here reconstruct exactly. Closed by RBSP trailing bits.
+ */
+const RECOVERY_POINT_SEI_NAL = Uint8Array.of(0x06, 0x06, 0x01, 0xc2, 0x80);
+/** Low five bits of a NAL's first byte, the AVC unit type. */
+const NAL_TYPE_MASK = 0x1f;
+/**
+ * An access unit delimiter has to be the first NAL of its access unit, so it is
+ * the one unit the SEI goes behind rather than ahead of.
+ */
+const ACCESS_UNIT_DELIMITER = 9;
+/** Coded slice of an IDR picture. */
+const IDR_SLICE = 5;
+/**
+ * Scalable and multiview extension NALs. A decoder configured from an avcC
+ * record decodes the base layer and reads none of them, and Chromium's key-frame
+ * detector reads the opening chunk as something other than a key frame when they
+ * are in it.
+ */
+const EXTENSION_NAL_FIRST = 20;
+const EXTENSION_NAL_LAST = 31;
+/** Byte of the avcC record holding lengthSizeMinusOne in its low two bits. */
+const LENGTH_SIZE_MINUS_ONE_OFFSET = 4;
+const LENGTH_SIZE_MINUS_ONE_MASK = 0b11;
+/**
+ * Prefix width per lengthSizeMinusOne encoding. ISO/IEC 14496-15 reserves the
+ * encoding 2, so a record carrying it names no width at all.
+ */
+const PREFIX_WIDTHS = [1, 2, undefined, 4];
+/**
+ * Width of the AVCC length prefix this track frames every NAL with, read from
+ * its avcC record, or null when the description names no usable width. Files
+ * carry 1, 2, and 4, so nothing downstream may assume one of them.
+ */
+function nalPrefixWidth(description) {
+    if (!description)
+        return null;
+    const record = avccRecord(description);
+    if (record.length <= LENGTH_SIZE_MINUS_ONE_OFFSET)
+        return null;
+    const encoding = record[LENGTH_SIZE_MINUS_ONE_OFFSET] & LENGTH_SIZE_MINUS_ONE_MASK;
+    return PREFIX_WIDTHS[encoding] ?? null;
+}
+function avccRecord(description) {
+    if (ArrayBuffer.isView(description)) {
+        return new Uint8Array(description.buffer, description.byteOffset, description.byteLength);
+    }
+    return new Uint8Array(description);
+}
+/** Big-endian NAL length over exactly `width` bytes, the AVCC framing. */
+function writePrefix(target, width, length) {
+    for (let i = 0; i < width; i++) {
+        target[i] = (length >>> ((width - 1 - i) * 8)) & 0xff;
+    }
+}
+/**
+ * The packet's NAL units in order, or null when the prefix widths do not walk
+ * to exactly the end of the packet. That reading is the wrong one, and dropping
+ * or reordering anything on it would throw away picture data.
+ */
+function nalUnits(packetBytes, prefixWidth) {
+    const units = [];
+    let offset = 0;
+    while (offset < packetBytes.length) {
+        if (offset + prefixWidth > packetBytes.length)
+            return null;
+        let length = 0;
+        for (let i = 0; i < prefixWidth; i++)
+            length = length * 256 + packetBytes[offset + i];
+        offset += prefixWidth;
+        if (length === 0 || offset + length > packetBytes.length)
+            return null;
+        units.push(packetBytes.subarray(offset, offset + length));
+        offset += length;
+    }
+    return units;
+}
+function nalType(unit) {
+    return unit[0] & NAL_TYPE_MASK;
+}
+/** The units re-framed at `prefixWidth`, the only framing this track's decoder
+ *  can parse the packet under. */
+function frameNalUnits(units, prefixWidth) {
+    let total = 0;
+    for (const unit of units)
+        total += prefixWidth + unit.length;
+    const framed = new Uint8Array(total);
+    let offset = 0;
+    for (const unit of units) {
+        writePrefix(framed.subarray(offset), prefixWidth, unit.length);
+        offset += prefixWidth;
+        framed.set(unit, offset);
+        offset += unit.length;
+    }
+    return framed;
+}
+/**
+ * Whether this access unit carries an IDR slice.
+ *
+ * A container's sync table names sync samples, and an H.264 sync sample is
+ * usually an ordinary I picture rather than an IDR. The two differ in what a
+ * decoder may assume about the pictures that follow: an IDR empties the
+ * reference list, so nothing after it can name a picture from before it, while
+ * an I picture leaves the list standing and the next reference frame is free to
+ * name pictures the entry point never decoded. Only the IDR is an entry point
+ * the bitstream cannot invalidate.
+ *
+ * Unreadable framing reads as not-IDR: the caller's fallback is to enter
+ * further back, which costs a walk and is never wrong.
+ */
+function isIdrAccessUnit(packetBytes, prefixWidth) {
+    const units = nalUnits(packetBytes, prefixWidth);
+    if (!units)
+        return false;
+    return units.some((unit) => nalType(unit) === IDR_SLICE);
+}
+/**
+ * The access unit as the chunk that opens a decode, carrying the recovery-point
+ * SEI that makes it a legal entry point.
+ *
+ * Where the SEI goes is the whole of it: an access unit delimiter, when the
+ * packet has one, is required to be the access unit's first NAL, so the SEI goes
+ * behind it. Ahead of it the access unit is malformed, and a decoder reading the
+ * opening chunk to decide whether it is really a key frame is entitled to say it
+ * is not.
+ */
+function openingKeyPacket(packetBytes, prefixWidth) {
+    const units = nalUnits(packetBytes, prefixWidth);
+    if (!units)
+        return seiAhead(packetBytes, prefixWidth);
+    const kept = units.filter((unit) => {
+        const type = nalType(unit);
+        return type < EXTENSION_NAL_FIRST || type > EXTENSION_NAL_LAST;
+    });
+    const seiAt = kept.length > 0 && nalType(kept[0]) === ACCESS_UNIT_DELIMITER ? 1 : 0;
+    kept.splice(seiAt, 0, RECOVERY_POINT_SEI_NAL);
+    return frameNalUnits(kept, prefixWidth);
+}
+/** `packetBytes` behind a recovery-point SEI framed at the file's own prefix
+ *  width, since a prefix of any other width makes the whole packet unparseable. */
+function seiAhead(packetBytes, prefixWidth) {
+    const seiBytes = prefixWidth + RECOVERY_POINT_SEI_NAL.length;
+    const framed = new Uint8Array(seiBytes + packetBytes.length);
+    writePrefix(framed, prefixWidth, RECOVERY_POINT_SEI_NAL.length);
+    framed.set(RECOVERY_POINT_SEI_NAL, prefixWidth);
+    framed.set(packetBytes, seiBytes);
+    return framed;
+}
+/**
+ * WebCodecs' standing demand for a key frame, which configure() and flush()
+ * both arm and the next submitted chunk clears.
+ */
+class KeyPacketRequirement {
+    prefixWidth;
+    pending = true;
+    constructor(prefixWidth) {
+        this.prefixWidth = prefixWidth;
+    }
+    /** Whether the demand still stands, so the chunk about to satisfy it can
+     *  also be typed as the key chunk the decoder is waiting for. */
+    get armed() {
+        return this.pending;
+    }
+    /** Call after every configure() and flush(). */
+    rearm() {
+        this.pending = true;
+    }
+    /**
+     * Bytes to submit for the next packet in decode order, carrying the
+     * recovery-point SEI while the demand stands. The container reports sync
+     * samples, never IDR frames, so the SEI goes on without inspecting the
+     * packet; ahead of a true IDR it is a NAL the decoder ignores.
+     */
+    satisfy(packetBytes) {
+        if (!this.pending)
+            return packetBytes;
+        this.pending = false;
+        return openingKeyPacket(packetBytes, this.prefixWidth);
+    }
+}
+
+/**
+ * Draws an image upright into a destination box, mirroring the transform
+ * mediabunny's own VideoSample.draw applies so a frame decoded by the runtime
+ * and a frame decoded by a mediabunny sink land the same pixels.
+ *
+ * dWidth and dHeight name the destination AFTER the turn, which is what the
+ * track's display size already is. So on a quarter turn the source is drawn at
+ * swapped extents inside the turned frame, and the scale below undoes the
+ * aspect that swap introduces.
+ */
+function drawRotated(context, image, rotation, dx, dy, dWidth, dHeight) {
+    if (rotation === 0) {
+        context.drawImage(image, dx, dy, dWidth, dHeight);
+        return;
+    }
+    context.save();
+    context.translate(dx + dWidth / 2, dy + dHeight / 2);
+    context.rotate((rotation * Math.PI) / 180);
+    const aspectRatioChange = rotation % 180 === 0 ? 1 : dWidth / dHeight;
+    context.scale(1 / aspectRatioChange, aspectRatioChange);
+    context.drawImage(image, -dWidth / 2, -dHeight / 2, dWidth, dHeight);
+    context.restore();
+}
+
+/**
+ * Half a microsecond: a submitted timestamp survives the round trip through the
+ * decoder as whole microseconds, so anything closer than this is the same
+ * packet and anything further is a decoder counting on a clock of its own.
+ */
+const TIMING_MATCH_S = 5e-7;
+function anchorKey(timestampS) {
+    return Math.round(timestampS * MICROSECONDS_PER_SECOND);
+}
+/**
+ * Verification rejects every sync sample that is not a true IDR, which collapses
+ * a container's sync table down to the handful of real IDRs and drags the anchor
+ * back by that much. Off, the honest table stands and a recovery-point SEI makes
+ * the non-IDR anchor legal to decode from.
+ *
+ * The anchor is read with its bytes: it is both the packet the walk starts from
+ * and the first chunk submitted, and a reader refuses a metadata-only packet as
+ * the start of a full-data walk.
+ */
+const ANCHOR_PROBE = { verifyKeyPackets: false };
+/**
+ * The fallback anchor read: the last IDR at or before the target, found by
+ * reading bitstreams rather than trusting the sync table. Reached only once an
+ * optimistic anchor has actually failed, since it drags the entry point back to
+ * the previous IDR and every picture between there and the target is decoded
+ * and thrown away.
+ */
+const IDR_PROBE = { verifyKeyPackets: true };
+/** The packet that closes the anchor span is read for its timestamp alone. */
+const SPAN_END_PROBE = {
+    metadataOnly: true,
+    verifyKeyPackets: false,
+};
+/**
+ * Chunks kept outstanding in the decoder. H.264 lets a decoder hold up to
+ * sixteen pictures before it has to emit one, and a stream that uses the whole
+ * buffer emits nothing at all until the seventeenth chunk arrives, so a
+ * shallower pipeline waits forever on the frame it just asked for.
+ */
+const DECODER_PIPELINE_CHUNKS = 17;
+/** Decoded frames held before the session stops feeding the decoder. These are
+ *  full-resolution and the session's own to retain, unlike the pipeline above,
+ *  which is the decoder's. */
+const READY_FRAMES = 4;
+/** Absorbs float error when a requested bound lands on a frame's timestamp. */
+const BOUND_EPSILON_S = 1e-6;
+/**
+ * Ceiling on waiting for ONE decoder output while chunks are in flight, which a
+ * healthy decoder answers in single-digit milliseconds. It is not the ceiling on
+ * a walk (that is the caller's, and a legitimate GOP walk runs far longer); it
+ * exists so a decoder that goes silent surfaces as a failure instead of parking
+ * the surface for the length of the walk ceiling. It only ever runs while output
+ * is owed, so an idle session cannot trip it however long it sits.
+ */
+const OUTPUT_TIMEOUT_MS = 5_000;
+const MICROSECONDS_PER_SECOND = 1e6;
+/** The recovery-point SEI is an H.264 NAL behind an AVCC length prefix, so the
+ *  session opens only codecs framed that way. */
+const AVCC_H264_CODEC = /^avc1\./;
+/**
+ * Width the session must frame its SEI at to drive a track with this config, or
+ * null when it cannot drive the track at all. The SEI it prepends to a non-IDR
+ * anchor is an H.264 NAL behind an AVCC length prefix, and the width of that
+ * prefix is only knowable from the avcC record in `description`, so a config
+ * without one is unusable however well-formed the rest of it looks.
+ */
+function drivablePrefixWidth(config) {
+    if (!AVCC_H264_CODEC.test(config.codec))
+        return null;
+    return nalPrefixWidth(config.description);
+}
+/**
+ * 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.
+ */
+function sessionDrivable(config) {
+    return drivablePrefixWidth(config) !== null;
+}
+/**
+ * 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.
+ */
+class DecodeSession {
+    options;
+    keyPacket;
+    prefixWidth;
+    decoder = null;
+    iterator = null;
+    peeked = null;
+    /** Timestamp of the key packet after the anchor: the end of the span a
+     *  forward seek can reach without re-anchoring. */
+    spanEndS = Infinity;
+    exhausted = true;
+    /** Timings the decoder still owes pictures for, in presentation order. */
+    pending = [];
+    decoded = [];
+    wake = null;
+    /**
+     * 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.
+     */
+    stalledError = null;
+    /**
+     * 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.
+     */
+    anchorError = null;
+    /** The entry currently feeding the decoder, or null before the first one. */
+    entry = null;
+    /** Entry points a decoder error has ruled out, by whole-microsecond
+     *  timestamp. Only ever grows: a bitstream does not change. */
+    rejectedAnchors = new Set();
+    /** 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. */
+    entryTargetS = 0;
+    /** The last picture handed out since the caller last chose a position, so a
+     *  re-anchor mid-walk resumes rather than replays. */
+    servedS = -Infinity;
+    closed = false;
+    anchors = 0;
+    framesDecodedCount = 0;
+    /** 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. */
+    reachable = -Infinity;
+    /** Serializes retrievals; see the class note on shared-decoder exclusivity. */
+    tail = Promise.resolve();
+    /** 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. */
+    epoch = 0;
+    outputTimeoutMs;
+    rotation;
+    constructor(options) {
+        this.options = options;
+        this.outputTimeoutMs = options.outputTimeoutMs ?? OUTPUT_TIMEOUT_MS;
+        this.rotation = options.rotation;
+        const prefixWidth = drivablePrefixWidth(options.config);
+        if (prefixWidth === null) {
+            throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `DecodeSession: ${options.config.codec} is not AVCC-framed H.264`);
+        }
+        this.prefixWidth = prefixWidth;
+        this.keyPacket = new KeyPacketRequirement(prefixWidth);
+    }
+    /** Times the session has configured the decoder onto an anchor. */
+    get anchorCount() {
+        return this.anchors;
+    }
+    /** 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() {
+        return this.framesDecodedCount;
+    }
+    /** 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() {
+        const queued = this.decoded[0];
+        if (queued)
+            return queued.timestampS;
+        return this.reachable;
+    }
+    /** The frame at or before `targetS`, or null when nothing precedes it. */
+    async frameAt(targetS) {
+        const landed = await this.exclusive(() => this.land(targetS));
+        return landed ? videoFrameSample(landed, this.rotation) : 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.
+     */
+    async *framesFrom(startS) {
+        let handedOutS = null;
+        let seenEpoch = this.epoch;
+        for (;;) {
+            const picture = await this.exclusive(() => {
+                if (handedOutS === null)
+                    return this.land(startS);
+                if (seenEpoch !== this.epoch)
+                    return this.resumeAfter(handedOutS);
+                return this.pull(Infinity);
+            });
+            if (!picture)
+                return;
+            handedOutS = picture.timestampS;
+            seenEpoch = this.epoch;
+            yield videoFrameSample(picture, this.rotation);
+        }
+    }
+    /**
+     * 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.
+     */
+    async *framesCovering(startS, endS) {
+        let positioned = false;
+        let seenEpoch = 0;
+        for (;;) {
+            const picture = await this.exclusive(async () => {
+                if (!positioned) {
+                    await this.positionFor(startS);
+                    positioned = true;
+                }
+                else if (seenEpoch !== this.epoch) {
+                    return null;
+                }
+                return this.pull(endS);
+            });
+            if (!picture)
+                return;
+            seenEpoch = this.epoch;
+            yield videoFrameSample(picture, this.rotation);
+        }
+    }
+    /**
+     * 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.
+     */
+    exclusive(op) {
+        const run = this.tail.then(op, op);
+        this.tail = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    /**
+     * 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.
+     */
+    async resumeAfter(afterS) {
+        await this.positionFor(afterS);
+        for (;;) {
+            const picture = await this.pull(Infinity);
+            if (!picture)
+                return null;
+            if (picture.timestampS > afterS + BOUND_EPSILON_S)
+                return picture;
+            picture.frame.close();
+        }
+    }
+    close() {
+        if (this.closed)
+            return;
+        this.closed = true;
+        void this.iterator?.return();
+        this.iterator = null;
+        this.peeked = null;
+        this.exhausted = true;
+        this.discardDecoded();
+        this.decoder?.close();
+        this.decoder = null;
+        this.wake?.();
+    }
+    /** Decodes through `targetS` and returns the last frame at or before it,
+     *  closing the frames walked past. */
+    async land(targetS) {
+        await this.positionFor(targetS);
+        let landed = null;
+        for (;;) {
+            const picture = await this.pull(targetS);
+            if (!picture)
+                return landed;
+            landed?.frame.close();
+            landed = picture;
+        }
+    }
+    async positionFor(targetS) {
+        if (this.closed)
+            return;
+        if (this.stalledError)
+            throw this.stalledError;
+        this.entryTargetS = targetS;
+        if (this.decoder && !this.exhausted) {
+            const headS = await this.readHeadS();
+            if (headS !== null && targetS >= headS && targetS < this.spanEndS)
+                return;
+        }
+        this.servedS = -Infinity;
+        await this.anchorAt(targetS);
+    }
+    /** 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. */
+    async readHeadS() {
+        const queued = this.decoded[0];
+        if (queued)
+            return queued.timestampS;
+        const packet = await this.peek();
+        return packet ? packet.timestamp : null;
+    }
+    async anchorAt(targetS) {
+        const entry = await this.resolveEntry(targetS);
+        void this.iterator?.return();
+        this.iterator = null;
+        this.peeked = null;
+        this.exhausted = true;
+        this.entry = null;
+        this.anchorError = null;
+        this.quiesce();
+        if (!entry || this.closed)
+            return;
+        this.spanEndS = await this.spanEndAfter(entry.anchor, targetS);
+        this.configureDecoder();
+        this.iterator = this.options.packets.packets(entry.anchor);
+        this.entry = entry;
+        this.exhausted = false;
+        this.anchors++;
+        this.epoch++;
+        this.reachable = entry.anchor.timestamp;
+    }
+    /**
+     * 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.
+     */
+    async resolveEntry(targetS) {
+        const sync = await this.options.packets.getKeyPacket(targetS, ANCHOR_PROBE);
+        if (sync) {
+            const key = anchorKey(sync.timestamp);
+            if (!this.rejectedAnchors.has(key)) {
+                return {
+                    anchor: sync,
+                    key,
+                    hasFallback: !isIdrAccessUnit(sync.data, this.prefixWidth),
+                };
+            }
+        }
+        const idr = await this.options.packets.getKeyPacket(targetS, IDR_PROBE);
+        if (!idr)
+            return null;
+        return { anchor: idr, key: anchorKey(idr.timestamp), hasFallback: false };
+    }
+    /**
+     * 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.
+     */
+    async spanEndAfter(anchor, targetS) {
+        let key = anchor;
+        for (;;) {
+            const next = await this.options.packets.getNextKeyPacket(key, SPAN_END_PROBE);
+            if (!next)
+                return Infinity;
+            if (next.timestamp > targetS + BOUND_EPSILON_S &&
+                !this.rejectedAnchors.has(anchorKey(next.timestamp))) {
+                return next.timestamp;
+            }
+            key = next;
+        }
+    }
+    /** 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. */
+    quiesce() {
+        this.decoder?.reset();
+        this.pending.length = 0;
+        this.discardDecoded();
+    }
+    configureDecoder() {
+        try {
+            if (!this.decoder) {
+                // Named so the callback can check that the decoder reporting the
+                // failure is still the one driving the session: a decoder dropped for
+                // erroring may report again afterwards, and that report must not
+                // condemn the anchor built to replace it.
+                const built = this.options.createDecoder({
+                    output: (frame) => this.receive(frame),
+                    error: (error) => this.fail(built, error),
+                });
+                this.decoder = built;
+            }
+            // Without prompt per-frame emission a session that never flushes has
+            // no way to get its frames out, so the whole flush-free design rests
+            // here.
+            this.decoder.configure({
+                ...this.options.config,
+                optimizeForLatency: true,
+            });
+        }
+        catch (cause) {
+            throw this.stall("the decoder refused to configure", cause);
+        }
+        this.keyPacket.rearm();
+    }
+    /** 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. */
+    async pull(boundS) {
+        // Every hand-out moves the decoder forward past that frame.
+        for (;;) {
+            if (this.closed)
+                return null;
+            if (this.stalledError)
+                throw this.stalledError;
+            const failed = this.anchorError;
+            if (failed) {
+                await this.enterFurtherBack(failed);
+                continue;
+            }
+            await this.fill();
+            const ready = this.decoded[0];
+            if (ready) {
+                // Re-entering further back re-decodes ground the walk already
+                // covered, and the caller has seen those pictures.
+                if (ready.timestampS <= this.servedS + BOUND_EPSILON_S) {
+                    this.decoded.shift();
+                    ready.frame.close();
+                    continue;
+                }
+                if (ready.timestampS > boundS + BOUND_EPSILON_S)
+                    return null;
+                this.decoded.shift();
+                this.reachable = ready.timestampS;
+                this.servedS = ready.timestampS;
+                return ready;
+            }
+            // The pipeline holds requests a failed decoder will never answer, so
+            // waiting on them is waiting out the ceiling for nothing.
+            if (this.anchorError)
+                continue;
+            if (this.pending.length === 0)
+                return null;
+            // Nothing is left to submit at end of stream, so a flush is the only
+            // way to get the last frames out.
+            if (this.exhausted)
+                await this.drain();
+            else
+                await this.awaitOutput();
+        }
+    }
+    /**
+     * 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.
+     */
+    async enterFurtherBack(failure) {
+        const entry = this.entry;
+        if (!entry?.hasFallback)
+            throw this.latch(failure);
+        this.rejectedAnchors.add(entry.key);
+        // An errored WebCodecs decoder is already closed and cannot be
+        // reconfigured, so the replacement anchor needs a replacement decoder.
+        this.decoder = null;
+        await this.anchorAt(Math.max(this.entryTargetS, this.servedS));
+        if (!this.entry)
+            throw this.latch(failure);
+    }
+    /**
+     * 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.
+     */
+    async fill() {
+        while (this.decoder &&
+            // The error arrives between two of the reads below, and a decoder that
+            // has reported one is closed: every further chunk is refused, and being
+            // refused is what would condemn the whole session for a failure the
+            // anchor already owns.
+            !this.anchorError &&
+            this.pending.length < DECODER_PIPELINE_CHUNKS &&
+            this.decoded.length < READY_FRAMES) {
+            const packet = await this.peek();
+            if (!packet)
+                return;
+            if (this.closed || this.anchorError)
+                return;
+            this.peeked = null;
+            this.awaitTiming({
+                timestampS: packet.timestamp,
+                durationS: packet.duration,
+            });
+            // The chunk that opens the decode is the only one submitted as a key
+            // chunk: a later sync sample is a recovery point, not an IDR, and the
+            // decoder verifies the claim. It is the same chunk that carries the
+            // SEI, so one latch answers both.
+            const opensDecode = this.keyPacket.armed;
+            const data = this.keyPacket.satisfy(packet.data);
+            try {
+                this.decoder.decode({
+                    type: opensDecode ? "key" : "delta",
+                    timestamp: Math.round(packet.timestamp * MICROSECONDS_PER_SECOND),
+                    duration: Math.round(packet.duration * MICROSECONDS_PER_SECOND),
+                    data,
+                });
+            }
+            catch (cause) {
+                throw this.stall("the decoder refused a chunk", cause);
+            }
+        }
+    }
+    async peek() {
+        if (this.peeked)
+            return this.peeked;
+        if (!this.iterator || this.exhausted)
+            return null;
+        const result = await this.iterator.next();
+        if (result.done) {
+            this.exhausted = true;
+            return null;
+        }
+        this.peeked = result.value;
+        return this.peeked;
+    }
+    async drain() {
+        const decoder = this.decoder;
+        if (!decoder)
+            return;
+        await decoder.flush();
+        this.pending.length = 0;
+        this.keyPacket.rearm();
+    }
+    awaitOutput() {
+        return new Promise((resolve, reject) => {
+            const owed = this.pending.length;
+            const timer = setTimeout(() => {
+                this.wake = null;
+                // Drop the work this was waiting on before handing the failure
+                // out. The chunks it timed out on stay counted as in flight
+                // otherwise, and the next retrieval inherits a decoder that owes
+                // frames it will never produce, so it waits out the same timeout
+                // again instead of re-anchoring onto a clean one.
+                this.quiesce();
+                this.exhausted = true;
+                // Which failure this is turns on the output counter, not on the
+                // timer: a decoder that has handed frames back and then gone quiet
+                // is one a rebuild can recover, and a decoder that has answered a
+                // full pipeline of requests with nothing at all may never have been
+                // given a legal place to start, which is the anchor's to answer for.
+                if (this.framesDecodedCount === 0) {
+                    this.anchorError ??= new VideoEngineError(VideoEngineErrorCode.DecoderStalled, `DecodeSession: the decoder acknowledged ${owed} decode requests and produced no frame`);
+                    resolve();
+                    return;
+                }
+                reject(new VideoEngineError(VideoEngineErrorCode.BackendCrashed, `DecodeSession: decoder produced no output in ${this.outputTimeoutMs}ms with ${owed} chunks in flight`));
+            }, this.outputTimeoutMs);
+            this.wake = () => {
+                this.wake = null;
+                clearTimeout(timer);
+                resolve();
+            };
+        });
+    }
+    /**
+     * 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.
+     */
+    awaitTiming(timing) {
+        let at = this.pending.length;
+        while (at > 0 && this.pending[at - 1].timestampS > timing.timestampS)
+            at--;
+        this.pending.splice(at, 0, timing);
+    }
+    /**
+     * 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.
+     */
+    claimTiming(frame) {
+        const submittedS = frame.timestamp / MICROSECONDS_PER_SECOND;
+        const at = this.pending.findIndex((timing) => Math.abs(timing.timestampS - submittedS) <= TIMING_MATCH_S);
+        return at === -1 ? this.pending.shift() : this.pending.splice(at, 1)[0];
+    }
+    receive(frame) {
+        this.framesDecodedCount += 1;
+        const timing = this.claimTiming(frame);
+        if (this.closed || !timing) {
+            frame.close();
+            return;
+        }
+        this.decoded.push({ frame, ...timing });
+        this.wake?.();
+    }
+    fail(from, error) {
+        if (from !== this.decoder)
+            return;
+        this.anchorError ??= new VideoEngineError(VideoEngineErrorCode.DecoderStalled, "DecodeSession: the decoder reported an error", error);
+        this.wake?.();
+    }
+    /** Latches the terminal failure and returns it. First writer wins, so the
+     *  cause a caller is handed is the one that started the failure rather than
+     *  whichever consequence surfaced last. */
+    stall(what, cause) {
+        return this.latch(new VideoEngineError(VideoEngineErrorCode.DecoderStalled, `DecodeSession: ${what}`, cause));
+    }
+    latch(error) {
+        this.stalledError ??= error;
+        return this.stalledError;
+    }
+    discardDecoded() {
+        for (const picture of this.decoded)
+            picture.frame.close();
+        this.decoded.length = 0;
+    }
+}
+/** A decoded frame in the runtime's own sample vocabulary, so a session frame
+ *  and a VideoSampleSink frame reach the renderer the same way. */
+function videoFrameSample({ frame, timestampS, durationS }, rotation) {
+    const quarterTurn = rotation % 180 !== 0;
+    return {
+        timestamp: timestampS,
+        duration: durationS,
+        rotation,
+        toVideoFrame: () => frame.clone(),
+        draw: (ctx, dx, dy, dWidth, dHeight) => {
+            drawRotated(ctx, frame, rotation, dx, dy, dWidth ?? (quarterTurn ? frame.displayHeight : frame.displayWidth), dHeight ?? (quarterTurn ? frame.displayWidth : frame.displayHeight));
+        },
+        close: () => frame.close(),
+    };
+}
+
+var ScrubCursorState;
+(function (ScrubCursorState) {
+    ScrubCursorState["Idle"] = "idle";
+    ScrubCursorState["Seeking"] = "seeking";
+    ScrubCursorState["Closed"] = "closed";
+})(ScrubCursorState || (ScrubCursorState = {}));
+/**
+ * Wraps a raw sample so its close() runs at most once, then no-ops. The
+ * lifetime is hard to keep linear: a sample is drawn into the cache, stashed for
+ * paint, then closed after paint, and may be closed again on teardown if a
+ * gesture left it unpainted. An idempotent close lets every path call it
+ * defensively without double-free.
+ */
+function idempotentSample(sample) {
+    let closed = false;
+    return {
+        toVideoFrame: () => sample.toVideoFrame(),
+        rotation: sample.rotation,
+        draw: (ctx, dx, dy, dWidth, dHeight) => sample.draw(ctx, dx, dy, dWidth, dHeight),
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            sample.close();
+        },
+        get timestamp() {
+            return sample.timestamp;
+        },
+        get duration() {
+            return sample.duration;
+        },
+    };
+}
+
+/**
+ * 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.
+ */
+async function openDecodeSource(options) {
+    return canvasHandle(await openInput(options), options.poolSize ?? SCRUB.DEFAULT_POOL_SIZE);
+}
+/**
+ * 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.
+ */
+async function openWalkSource(source) {
+    const opened = await openInput({ source });
+    const decoderConfig = await opened.videoTrack.getDecoderConfig();
+    if (decoderConfig &&
+        decodeSessionViable({
+            videoDecoderAvailable: detectVideoDecoder(),
+            decoderConfig,
+        })) {
+        const handle = sessionHandle(opened, decoderConfig);
+        return walkHandle(handle, (startS) => handle.session.framesFrom(startS));
+    }
+    const handle = sampleHandle(opened);
+    return walkHandle(handle, (startS) => handle.sampleSink.samples(startS));
+}
+function walkHandle(handle, stream) {
+    return {
+        track: handle.track,
+        async *framesFrom(startS) {
+            for await (const sample of stream(startS))
+                yield idempotentSample(sample);
+        },
+        dispose: () => handle.dispose(),
+    };
+}
+function canvasHandle(opened, poolSize) {
+    // Width-only: CanvasSink derives height from native aspect. This sizes the
+    // canvas the frame is drawn into; it does NOT reduce decode cost. The codec
+    // decodes the full coded frame regardless, and CanvasSink resizes after, so
+    // the win is paint work and cached-blit memory, not decode throughput.
+    const sink = new CanvasSink(opened.videoTrack, {
+        poolSize,
+        width: opened.track.decodeWidth,
+    });
+    return {
+        track: opened.track,
+        sink,
+        keyframeProbe: new EncodedPacketSink(opened.videoTrack),
+        dispose: async () => {
+            opened.input.dispose();
+        },
+    };
+}
+/** The zero-copy sample path: a VideoSampleSink in place of the CanvasSink. It
+ *  takes no width, so frames arrive at the source's own dimensions. */
+function sampleHandle(opened) {
+    return {
+        track: opened.track,
+        sampleSink: new VideoSampleSink(opened.videoTrack),
+        keyframeProbe: new EncodedPacketSink(opened.videoTrack),
+        dispose: async () => {
+            opened.input.dispose();
+        },
+    };
+}
+/**
+ * The long-lived-decoder path: an EncodedPacketSink feeding a DecodeSession that
+ * holds one VideoDecoder across seeks. The same sink answers the keyframe probe,
+ * so anchor resolution and packet reads share one reader. The session drives the
+ * decoder itself and every frame arrives at the source's own dimensions; the
+ * resolved decodeWidth still sizes the canvas and the cache blits, which scale
+ * the native frame down as they draw it.
+ */
+function sessionHandle(opened, config) {
+    const packets = new EncodedPacketSink(opened.videoTrack);
+    const session = new DecodeSession({
+        packets,
+        config,
+        createDecoder: webCodecsDecoder,
+        rotation: opened.track.rotation,
+    });
+    return {
+        track: opened.track,
+        session,
+        keyframeProbe: packets,
+        dispose: async () => {
+            session.close();
+            opened.input.dispose();
+        },
+    };
+}
+function webCodecsDecoder(init) {
+    const decoder = new VideoDecoder(init);
+    return {
+        configure: (config) => decoder.configure(config),
+        decode: (chunk) => decoder.decode(new EncodedVideoChunk(chunk)),
+        flush: () => decoder.flush(),
+        // Reporting an error closes a WebCodecs decoder, and both of these throw
+        // on one that is already closed. Teardown of a decoder that failed is a
+        // routine path, so the platform's rule is answered here rather than left
+        // for every caller to remember.
+        reset: () => {
+            if (decoder.state !== "closed")
+                decoder.reset();
+        },
+        close: () => {
+            if (decoder.state !== "closed")
+                decoder.close();
+        },
+    };
+}
+/** Opens the input, resolves the primary video track, and runs the decode
+ *  resolution math, the work every path shares before one is chosen.
+ *
+ *  Four ways to get no frames out of a file, and each one throws its own code
+ *  so a host can say which happened: the container is not one the demuxer
+ *  reads (ContainerUnreadable), the container reads but nothing inside it does
+ *  (VideoTrackUnreadable), the tracks read and none is video (NoVideoTrack), or
+ *  the video track reads and the browser has no decoder for its codec
+ *  (DecodeUnsupported). */
+async function openInput(options) {
+    const { source } = options;
+    const input = new Input({
+        formats: ALL_FORMATS,
+        source: toMediabunnySource(source, options.sourceResidency, options.urlSource),
+    });
+    const videoTrack = await resolveVideoTrack(input);
+    if (!(await videoTrack.canDecode())) {
+        const decoderConfig = await videoTrack.getDecoderConfig();
+        throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `openInput: browser cannot decode this video track's codec ${decoderConfig?.codec ?? "(unknown)"}`);
+    }
+    const displayWidth = videoTrack.displayWidth;
+    const displayHeight = videoTrack.displayHeight;
+    const durationS = asSec(await readTrackDurationS(videoTrack));
+    const timeline = await readFrameTimeline(videoTrack);
+    // Mediabunny ships a measured native fps via computePacketStats:
+    // averagePacketRate "for video tracks, equals the average frame rate". We
+    // bound the packet sample to a small slice so the load promise doesn't stall
+    // on long files. The result is good enough for 1/nativeFps step math;
+    // sub-frame precision falls through to stepForward/stepBackward.
+    const nativeFps = await readTrackFps(videoTrack);
+    const strategy = options.decodeStrategy ?? nativeResolution();
+    const { width: decodeWidth, height: decodeHeight } = resolveDecodeDimensions(strategy, {
+        nativeWidth: displayWidth,
+        nativeHeight: displayHeight,
+        displayWidth: options.viewport?.displayWidth ?? null,
+        devicePixelRatio: options.viewport?.devicePixelRatio ?? 1,
+    });
+    return {
+        input,
+        videoTrack,
+        strategy,
+        track: {
+            width: displayWidth,
+            height: displayHeight,
+            decodeWidth,
+            decodeHeight,
+            rotation: videoTrack.rotation,
+            nativeFps,
+            durationS,
+            firstTimestampS: timeline.timeAt(0),
+            timeline,
+        },
+    };
+}
+/**
+ * The primary video track, or the typed refusal that says which of the three
+ * ways to reach no track this file took. Only the last of them, where the
+ * demuxer listed tracks and none was video, is a statement about the file
+ * itself; the other two say what this build can read.
+ */
+async function resolveVideoTrack(input) {
+    let videoTrack;
+    try {
+        videoTrack = await input.getPrimaryVideoTrack();
+    }
+    catch (error) {
+        if (error instanceof UnsupportedInputFormatError) {
+            throw new VideoEngineError(VideoEngineErrorCode.ContainerUnreadable, "openInput: the demuxer does not read this file's container", error);
+        }
+        throw error;
+    }
+    if (videoTrack)
+        return videoTrack;
+    const tracks = await input.getTracks();
+    throw tracks.length === 0
+        ? new VideoEngineError(VideoEngineErrorCode.VideoTrackUnreadable, "openInput: the container opened and the demuxer parsed no track out of it")
+        : new VideoEngineError(VideoEngineErrorCode.NoVideoTrack, "openInput: the container's tracks read and none of them carries video");
+}
+/**
+ * Walks the track's packets metadata-only and records each one's timestamp in
+ * the container's own integer grain, which is the grain every timestamp of the
+ * track is a whole multiple of.
+ *
+ * Decode order is not presentation order on a B-frame source, so the table is
+ * sorted before it is indexed, and the trailing frame's duration comes from the
+ * packet that ends up last in that order.
+ */
+async function readFrameTimeline(videoTrack) {
+    const track = videoTrack;
+    const tickRate = typeof track.getTimeResolution === "function"
+        ? await track.getTimeResolution()
+        : (track.timeResolution ?? FRAME_TIMELINE.FALLBACK_TICK_RATE);
+    const sink = new EncodedPacketSink(videoTrack);
+    const ticks = [];
+    let lastTicks = -Infinity;
+    let lastDurationTicks = 0;
+    for await (const packet of sink.packets(undefined, undefined, {
+        metadataOnly: true,
+    })) {
+        const at = Math.round(packet.timestamp * tickRate);
+        if (ticks.length >= FRAME_TIMELINE.MAX_FRAMES) {
+            throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, `openInput: source video track carries more than ${FRAME_TIMELINE.MAX_FRAMES} frames`);
+        }
+        ticks.push(at);
+        if (at >= lastTicks) {
+            lastTicks = at;
+            lastDurationTicks = Math.round(packet.duration * tickRate);
+        }
+    }
+    if (ticks.length === 0) {
+        throw new VideoEngineError(VideoEngineErrorCode.DecodeUnsupported, "openInput: source video track has no frames");
+    }
+    ticks.sort((a, b) => a - b);
+    return FrameTimeline.from({
+        lastDurationTicks,
+        tickRate,
+        ticks: Float64Array.from(ticks),
+    });
+}
+/**
+ * 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.
+ */
+function decodeSessionViable(ctx) {
+    if (!ctx.videoDecoderAvailable)
+        return false;
+    return sessionDrivable(ctx.decoderConfig);
+}
+/** Whether this realm exposes the WebCodecs decoder the session constructs. */
+function detectVideoDecoder() {
+    return (typeof globalThis.VideoDecoder ===
+        "function");
+}
+function urlRequestInit(crossOrigin) {
+    if (!crossOrigin)
+        return undefined;
+    return {
+        requestInit: {
+            mode: "cors",
+            credentials: crossOrigin === "use-credentials" ? "include" : "omit",
+        },
+    };
+}
+function toMediabunnySource(source, residency, urlSource) {
+    switch (source.kind) {
+        case SourceKind.Url: {
+            const options = {
+                ...urlRequestInit(source.crossOrigin),
+                ...(residency ? { fetchFn: residency.fetchFn } : {}),
+                ...(urlSource?.maxCacheSize === undefined
+                    ? {}
+                    : { maxCacheSize: urlSource.maxCacheSize }),
+                ...(urlSource?.parallelism === undefined
+                    ? {}
+                    : { parallelism: urlSource.parallelism }),
+            };
+            return new UrlSource(source.url, Object.keys(options).length > 0 ? options : undefined);
+        }
+        case SourceKind.Blob:
+            return new BlobSource(source.blob);
+        case SourceKind.Stream:
+            return new ReadableStreamSource(source.stream);
+    }
+}
+async function readTrackDurationS(track) {
+    const t = track;
+    if (typeof t.computeDuration === "function") {
+        const d = await t.computeDuration();
+        return Number.isFinite(d) ? d : 0;
+    }
+    if (typeof t.duration === "number")
+        return t.duration;
+    if (typeof t.durationS === "number")
+        return t.durationS;
+    return 0;
+}
+/**
+ * Reads the native frame rate from mediabunny's computePacketStats. Bounded to a
+ * small packet sample so load() does not stall on long files. Returns null when
+ * the track exposes no stats API or the value is non-finite.
+ */
+async function readTrackFps(track) {
+    const t = track;
+    if (typeof t.computePacketStats !== "function")
+        return null;
+    try {
+        const stats = await t.computePacketStats(120);
+        const fps = stats?.averagePacketRate;
+        if (typeof fps !== "number" || !Number.isFinite(fps) || fps <= 0)
+            return null;
+        return fps;
+    }
+    catch {
+        return null;
+    }
+}
+
+/**
+ * Lazy index of a video track's keyframe timestamps, in seconds.
+ *
+ * Seeking decodes forward from the keyframe at-or-before the target, so every
+ * seek needs that anchor. Resolving one costs a container round-trip, so the
+ * index remembers each keyframe it discovers; repeated seeks around the same
+ * region then resolve synchronously through `cachedAtOrBefore`.
+ */
+// Only timestamps are read, never frame bytes, so every probe is metadata-only.
+const METADATA_ONLY = { metadataOnly: true };
+class KeyframeIndex {
+    probe;
+    times = [];
+    probeRoundTrips = 0;
+    /** Set once a full walk has completed, so a second call is a free no-op. */
+    fullyIndexed = false;
+    constructor(probe) {
+        this.probe = probe;
+    }
+    /** Keyframe timestamps discovered so far, ascending and deduplicated. */
+    get known() {
+        return this.times;
+    }
+    /** Container queries the index has made; the rest resolve from memory. */
+    get probeCount() {
+        return this.probeRoundTrips;
+    }
+    /**
+     * GOP-gap distribution over the keyframes discovered so far. Pass the track
+     * duration so density reflects keyframes across the whole clip, not just the
+     * clustered swept span; without it a few discovered keyframes in one region
+     * would read as a high density that does not hold track-wide.
+     */
+    gopStats(durationS) {
+        const t = this.times;
+        const n = t.length;
+        if (n < 2) {
+            return {
+                count: n,
+                avgGopS: 0,
+                maxGopS: 0,
+                minGopS: 0,
+                stddevS: 0,
+                densityPerS: 0,
+            };
+        }
+        const gaps = n - 1;
+        let sum = 0;
+        let max = -Infinity;
+        let min = Infinity;
+        for (let i = 1; i < n; i++) {
+            const gap = t[i] - t[i - 1];
+            sum += gap;
+            if (gap > max)
+                max = gap;
+            if (gap < min)
+                min = gap;
+        }
+        const avg = sum / gaps;
+        let variance = 0;
+        for (let i = 1; i < n; i++) {
+            const d = t[i] - t[i - 1] - avg;
+            variance += d * d;
+        }
+        const span = durationS && durationS > 0 ? durationS : t[n - 1] - t[0];
+        return {
+            count: n,
+            avgGopS: avg,
+            maxGopS: max,
+            minGopS: min,
+            stddevS: Math.sqrt(variance / gaps),
+            densityPerS: span > 0 ? gaps / span : 0,
+        };
+    }
+    /**
+     * Nearest keyframe at or before `tSec`, the anchor a seek decodes forward
+     * from. Null when `tSec` precedes the first keyframe.
+     */
+    async keyframeAtOrBefore(tSec) {
+        this.probeRoundTrips++;
+        const packet = await this.probe.getKeyPacket(tSec, METADATA_ONLY);
+        if (!packet)
+            return null;
+        this.record(packet.timestamp);
+        return packet.timestamp;
+    }
+    /**
+     * First keyframe strictly after `tSec`, the boundary a forward decode runs
+     * up to. Null when no keyframe follows, or when `tSec` precedes the first
+     * keyframe (no anchor to step from).
+     */
+    async nextKeyframeAfter(tSec) {
+        this.probeRoundTrips++;
+        const anchor = await this.probe.getKeyPacket(tSec, METADATA_ONLY);
+        if (!anchor)
+            return null;
+        this.record(anchor.timestamp);
+        this.probeRoundTrips++;
+        const next = await this.probe.getNextKeyPacket(anchor, METADATA_ONLY);
+        if (!next)
+            return null;
+        this.record(next.timestamp);
+        return next.timestamp;
+    }
+    /**
+     * Every keyframe needed to decode the window `[startS, endS]`: the anchor at
+     * or before `startS` plus each keyframe up to `endS`. Empty when `startS`
+     * precedes the first keyframe.
+     */
+    async keyframesCovering(startS, endS) {
+        this.probeRoundTrips++;
+        let packet = await this.probe.getKeyPacket(startS, METADATA_ONLY);
+        if (!packet)
+            return [];
+        const covering = [];
+        while (packet && packet.timestamp <= endS) {
+            this.record(packet.timestamp);
+            covering.push(packet.timestamp);
+            this.probeRoundTrips++;
+            packet = await this.probe.getNextKeyPacket(packet, METADATA_ONLY);
+        }
+        return covering;
+    }
+    /**
+     * Walks the whole track once, recording every keyframe timestamp. Metadata
+     * only: it threads the same getKeyPacket / getNextKeyPacket pattern as the
+     * lazy probes, so it never decodes a pixel. Idempotent: a second call after a
+     * completed walk returns at once. Meant for the diagnostics lane, off the hot
+     * seek path, so the purple lane reflects the whole file rather than only the
+     * regions a scrub has visited.
+     */
+    async ensureFullyIndexed(fromS = 0) {
+        if (this.fullyIndexed)
+            return;
+        this.probeRoundTrips++;
+        let packet = await this.probe.getKeyPacket(fromS, METADATA_ONLY);
+        while (packet) {
+            this.record(packet.timestamp);
+            this.probeRoundTrips++;
+            packet = await this.probe.getNextKeyPacket(packet, METADATA_ONLY);
+        }
+        this.fullyIndexed = true;
+    }
+    /**
+     * Largest discovered keyframe at or before `tSec`, resolved synchronously
+     * from memory. Null when nothing at or before `tSec` has been discovered
+     * yet; callers fall back to the async probes above.
+     */
+    cachedAtOrBefore(tSec) {
+        const i = floorIndex(this.times, tSec);
+        return i < 0 ? null : this.times[i];
+    }
+    record(t) {
+        const i = lowerBound(this.times, t);
+        if (i < this.times.length && this.times[i] === t)
+            return;
+        this.times.splice(i, 0, t);
+    }
+}
+/** First index whose value is `>= target` (insertion point for `target`). */
+function lowerBound(values, target) {
+    let lo = 0;
+    let hi = values.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (values[mid] < target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo;
+}
+/** Largest index whose value is `<= target`, or -1 when all exceed `target`. */
+function floorIndex(values, target) {
+    let lo = 0;
+    let hi = values.length;
+    while (lo < hi) {
+        const mid = (lo + hi) >>> 1;
+        if (values[mid] <= target)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    return lo - 1;
+}
+
+class AnalysisSession {
+    sink;
+    keyframeIndex;
+    track;
+    disposeSource;
+    closed = false;
+    constructor(source) {
+        this.sink = source.sink;
+        this.keyframeIndex = new KeyframeIndex(source.keyframeProbe);
+        this.track = source.track;
+        this.disposeSource = () => source.dispose();
+    }
+    /** Opens a source for analysis. The returned session owns the source. */
+    static async open(options) {
+        return new AnalysisSession(await openDecodeSource(options));
+    }
+    get metadata() {
+        return {
+            durationS: this.track.durationS,
+            width: this.track.width,
+            height: this.track.height,
+            frameWidth: this.track.decodeWidth,
+            frameHeight: this.track.decodeHeight,
+            nativeFps: this.track.nativeFps,
+        };
+    }
+    /**
+     * Keyframe timestamps (seconds) whose GOP overlaps the range, resolved
+     * lazily through the container. Useful for a contact sheet that lands on
+     * real I-frames, which decode without a GOP walk.
+     */
+    keyframeTimestamps(startS = 0, endS = this.track.durationS) {
+        return this.keyframeIndex.keyframesCovering(startS, endS);
+    }
+    /**
+     * Decodes a frame for each requested timestamp and returns a stable copy of
+     * each. Timestamps are sorted so the sink decodes each packet at most once;
+     * a timestamp with no frame is skipped rather than yielding a gap.
+     */
+    async extractFrames(timestampsS) {
+        const sorted = [...timestampsS].sort((a, b) => a - b);
+        const frames = [];
+        for await (const frame of this.framesAtTimestamps(sorted)) {
+            if (frame)
+                frames.push(frame);
+        }
+        return frames;
+    }
+    /**
+     * One frame per requested timestamp, in the order asked for, `null` where no
+     * frame covers it, so a caller pairing frames with its own indices keeps the
+     * gaps attributable. Timestamps that climb decode in a single pass over the
+     * track: one seek and GOP walk for the whole set.
+     *
+     * A consumer that finishes with each frame before pulling the next holds one
+     * frame of memory; {@link extractFrames} holds the whole set.
+     */
+    async *framesAtTimestamps(timestampsS) {
+        if (this.closed || timestampsS.length === 0)
+            return;
+        const iter = this.sink.canvasesAtTimestamps(timestampsS);
+        try {
+            for (let result = await iter.next(); !result.done; result = await iter.next()) {
+                if (this.closed)
+                    break;
+                yield result.value ? this.copyFrame(result.value) : null;
+            }
+        }
+        catch (error) {
+            // A concurrent close() disposes the source mid-decode; end the stream on
+            // the frames already yielded rather than throwing on the teardown.
+            if (!this.closed)
+                throw error;
+        }
+        finally {
+            void iter.return();
+        }
+    }
+    async close() {
+        this.closed = true;
+        await this.disposeSource();
+    }
+    copyFrame(frame) {
+        const width = this.track.decodeWidth;
+        const height = this.track.decodeHeight;
+        const canvas = new OffscreenCanvas(width, height);
+        // Frames are opaque video; alpha:false skips per-pixel blend.
+        const ctx = canvas.getContext("2d", { alpha: false });
+        ctx?.drawImage(frame.canvas, 0, 0, width, height);
+        return { timestampS: frame.timestamp, canvas, width, height };
+    }
+}
+
+/**
+ * A second consumer of the runtime, built only on AnalysisSession's public
+ * surface, with no reach into the cursor, cache, worker, or render loop. Its
+ * existence is the proof that the analysis primitive is reusable: a thumbnail
+ * strip or contact sheet is just a choice of which timestamps to pull, and the
+ * open/close pair shows the full source lifecycle is reachable from the public
+ * API alone.
+ */
+class FrameExtractor {
+    session;
+    constructor(session) {
+        this.session = session;
+    }
+    /** Opens a source and returns an extractor that owns it; close() disposes it. */
+    static async open(options) {
+        return new FrameExtractor(await AnalysisSession.open(options));
+    }
+    /** Frames at exactly the given timestamps (seconds). */
+    extractAt(timestampsS) {
+        return this.session.extractFrames(timestampsS);
+    }
+    /**
+     * `count` frames evenly spaced across the source, each sampled at the
+     * middle of its slice so neither the first black frame nor the exact end
+     * dominates the strip.
+     */
+    evenlySpaced(count) {
+        const { durationS } = this.session.metadata;
+        if (count <= 0 || durationS <= 0)
+            return Promise.resolve([]);
+        const step = durationS / count;
+        const times = Array.from({ length: count }, (_, i) => i * step + step / 2);
+        return this.session.extractFrames(times);
+    }
+    /** One frame per keyframe in the range: a contact sheet that decodes cheaply. */
+    async atKeyframes(startS, endS) {
+        const keyframes = await this.session.keyframeTimestamps(startS, endS);
+        return this.session.extractFrames(keyframes);
+    }
+    /** Disposes the underlying analysis session. */
+    close() {
+        return this.session.close();
+    }
+}
+
+const MS_PER_SECOND = 1000;
+/** One microsecond, the grain container timestamps are stored at, so a bound
+ *  that lands on a frame is never pushed off it by float error. */
+const BOUND_EPSILON_MS = 1e-3;
+/**
+ * Every real decoded frame of a range, in presentation order, exactly once.
+ *
+ * Nothing here is synthesized: the walk reads the source's own frames and counts
+ * them. Timestamps built from a frame rate and resolved through at-or-before
+ * extraction cannot promise that. One falling a float's width short of a sample
+ * lands on the frame before it, so the caller gets that frame twice and never
+ * sees the one it was aiming at.
+ *
+ * Every sample the walk decodes and does not yield is closed here: the frames
+ * before the range, the ones stride skips, and the first one past the end.
+ * Breaking out of the walk returns the underlying stream, which releases the
+ * decoder's read of the source; the sample in the caller's hand at that moment
+ * is still the caller's to close.
+ */
+async function* walkFrames(source, range = {}) {
+    const stride = range.stride ?? 1;
+    if (!Number.isInteger(stride) || stride < 1) {
+        throw new RangeError(`walkFrames: stride must be a positive integer, got ${stride}`);
+    }
+    const startMs = range.startMs ?? source.track.firstTimestampS * MS_PER_SECOND;
+    const endMs = range.endMs ?? Infinity;
+    if (endMs <= startMs)
+        return;
+    const frames = source.framesFrom(startMs / MS_PER_SECOND);
+    let framesInRange = 0;
+    try {
+        for (let next = await frames.next(); !next.done; next = await frames.next()) {
+            const sample = next.value;
+            const timestampMs = sample.timestamp * MS_PER_SECOND;
+            if (timestampMs < startMs - BOUND_EPSILON_MS) {
+                // The stream opens on the frame covering startMs, which is a
+                // frame the range does not contain.
+                sample.close();
+                continue;
+            }
+            if (timestampMs >= endMs - BOUND_EPSILON_MS) {
+                sample.close();
+                return;
+            }
+            const frameIndex = framesInRange++;
+            if (frameIndex % stride !== 0) {
+                sample.close();
+                continue;
+            }
+            yield {
+                frameIndex,
+                timestampMs,
+                durationMs: sample.duration * MS_PER_SECOND,
+                sample,
+            };
+        }
+    }
+    finally {
+        await frames.return();
+    }
+}
+/**
+ * A batch consumer's entry to the runtime: opens a source, walks its real
+ * frames, and disposes what it opened. It spins no worker, binds no canvas, and
+ * runs no clock, and it decodes on an input of its own, so a walk and a playing
+ * engine never contend for one decoder's read head.
+ *
+ * A walk in flight ends when the walker is closed, the same way extraction does,
+ * so a consumer that abandons a job mid-range has one call to make.
+ */
+class FrameWalker {
+    handle;
+    closed = false;
+    constructor(handle) {
+        this.handle = handle;
+    }
+    /** Opens a source for walking; the returned walker owns it. */
+    static async open(source) {
+        return new FrameWalker(await openWalkSource(source));
+    }
+    get metadata() {
+        const { track } = this.handle;
+        return {
+            durationS: track.durationS,
+            width: track.width,
+            height: track.height,
+            nativeFps: track.nativeFps,
+            firstTimestampS: track.firstTimestampS,
+        };
+    }
+    async *walkFrames(range = {}) {
+        if (this.closed)
+            return;
+        const walk = walkFrames(this.handle, range);
+        try {
+            for (let next = await walk.next(); !next.done; next = await walk.next()) {
+                if (this.closed) {
+                    next.value.sample.close();
+                    return;
+                }
+                yield next.value;
+            }
+        }
+        catch (error) {
+            // A concurrent close() disposes the source mid-decode; that teardown
+            // ends the walk and is not a decode failure.
+            if (!this.closed)
+                throw error;
+        }
+        finally {
+            await walk.return();
+        }
+    }
+    async close() {
+        this.closed = true;
+        await this.handle.dispose();
+    }
+}
+
+export { AnalysisSession, FrameExtractor, FrameWalker, walkFrames };
+//# sourceMappingURL=analysis.js.map