supervision 0.2.5 → 0.2.7

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

@@ -217,7 +217,7 @@
      * session path that is a probe plus a walk from the enclosing sync sample,
      * measured at 49ms mean / 80ms worst on a 2840x2840 15fps source, flat in how
      * far the jump travelled. Coverage past the window is worth having, not worth
-     * having crisp, so it lives in the preview tier at a 79th of the bytes.
+     * having crisp, so it lives in the smaller preview tier.
      *
      * resolveCacheBudgets turns these into a per-source budget from
      * navigator.deviceMemory and the decode frame size. A crisp slot costs
@@ -239,9 +239,8 @@
      * PREVIEW_SLOTS_MAX: the preview slot count is its byte budget over the
      * downscaled frame size, capped here. No floor pairs with it: raising a starved
      * count means overspending the byte budget, when the frame width is what a wide
-     * preview has to give up. At a 79th of a crisp slot the tier carries the
-     * timeline coverage an 8MP source cannot afford crisply: 163 slots against the
-     * exact tier's 13, 11s of a 15fps clip.
+     * preview has to give up. A 320px square preview costs about a 79th of an
+     * 8MP crisp slot, so that source keeps coarse history beyond its exact window.
      *
      * SKIP_NEAR_MS: cache lookups that resolve to a frame within this many
      * milliseconds of what the visible canvas already shows are rejected so the
@@ -356,22 +355,15 @@
      * scrub prefetch window, so its slot floor survives any frame size and the RAM
      * band adds speculative slots on top only while a slot stays cheap. An 8MP
      * source lands on the floor and keeps nothing speculative, which is what holds
-     * its resident footprint down; coverage past the window comes from the preview
-     * tier at a 79th of the cost per slot. That tier has no working set to protect,
-     * so its count is purely its byte budget over the downscaled frame size, which
-     * gives a square 8MP source enough coarse history without over-allocating for a
-     * small 16:9 one.
+     * its resident footprint down. The preview tier's byte ceiling depends on
+     * device memory; FrameCache derives its slot count from the actual raster size.
      */
-    function resolveCacheBudgets(decodeWidth, decodeHeight, previewWidth) {
+    function resolveCacheBudgets(decodeWidth, decodeHeight) {
         const gb = deviceMemoryGb();
         const crispFrameBytes = Math.max(1, decodeWidth * decodeHeight * 4);
         const exactBudgetBytes = Math.max(clamp$1(Math.round(gb * FRAME_CACHE.EXACT_BUDGET_BYTES_PER_GB), FRAME_CACHE.EXACT_BUDGET_BYTES_MIN, FRAME_CACHE.EXACT_BUDGET_BYTES_MAX), FRAME_CACHE.MIN_EXACT_SLOTS * crispFrameBytes);
-        const aspect = decodeWidth > 0 && decodeHeight > 0 ? decodeWidth / decodeHeight : 1;
-        const previewHeight = Math.max(1, Math.round(previewWidth / aspect));
-        const previewFrameBytes = Math.max(1, previewWidth * previewHeight * 4);
         const previewBudgetBytes = clamp$1(Math.round(gb * FRAME_CACHE.PREVIEW_BUDGET_BYTES_PER_GB), FRAME_CACHE.PREVIEW_BUDGET_BYTES_MIN, FRAME_CACHE.PREVIEW_BUDGET_BYTES_MAX);
-        const previewCapacity = Math.min(Math.floor(previewBudgetBytes / previewFrameBytes), FRAME_CACHE.PREVIEW_SLOTS_MAX);
-        return { exactBudgetBytes, previewCapacity };
+        return { exactBudgetBytes, previewBudgetBytes };
     }
 
     /*!
@@ -26973,6 +26965,99 @@
         }
     }
 
+    /**
+     * 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. A WebM block need not state a
+     * duration, which the demuxer reads as zero, so a last frame without one is
+     * given a duration from elsewhere.
+     */
+    async function readFrameTimeline(videoTrack) {
+        return (await readFrameIndex(videoTrack)).timeline;
+    }
+    /**
+     * The same walk, also naming the key frames: the presentation index of every
+     * frame a decode can start at, ascending.
+     */
+    async function readFrameIndex(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 = [];
+        const keyTicks = new Set();
+        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 WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, `openInput: source video track carries more than ${FRAME_TIMELINE.MAX_FRAMES} frames`);
+            }
+            ticks.push(at);
+            if (packet.type === "key")
+                keyTicks.add(at);
+            if (at >= lastTicks) {
+                lastTicks = at;
+                lastDurationTicks = Math.round(packet.duration * tickRate);
+            }
+        }
+        if (ticks.length === 0) {
+            throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, "openInput: source video track has no frames");
+        }
+        ticks.sort((a, b) => a - b);
+        if (lastDurationTicks === 0) {
+            lastDurationTicks = await unstatedLastDurationTicks(track, ticks, tickRate);
+        }
+        const timeline = FrameTimeline.from({
+            lastDurationTicks,
+            tickRate,
+            ticks: Float64Array.from(ticks),
+        });
+        const { ticks: presented, sourceTicks = presented } = timeline.toData();
+        const keyIndices = [];
+        for (let index = 0; index < sourceTicks.length; index += 1) {
+            if (keyTicks.has(sourceTicks[index]))
+                keyIndices.push(index);
+        }
+        return { keyIndices: Int32Array.from(keyIndices), timeline };
+    }
+    /**
+     * How long the last frame lasts when its packet does not say: until the end
+     * the container states for the track, else as long as the frame before it. A
+     * lone frame with neither keeps a span of no time.
+     */
+    async function unstatedLastDurationTicks(track, ticks, tickRate) {
+        const lastTicks = ticks[ticks.length - 1];
+        const statedEndS = await readStatedEndS(track);
+        if (statedEndS !== null) {
+            const toStatedEnd = Math.round(statedEndS * tickRate) - lastTicks;
+            if (toStatedEnd > 0)
+                return toStatedEnd;
+        }
+        let before = ticks.length - 2;
+        while (before >= 0 && ticks[before] === lastTicks)
+            before -= 1;
+        return before >= 0 ? lastTicks - ticks[before] : 0;
+    }
+    async function readStatedEndS(track) {
+        if (typeof track.getDurationFromMetadata !== "function")
+            return null;
+        try {
+            const endS = await track.getDurationFromMetadata();
+            return typeof endS === "number" && Number.isFinite(endS) ? endS : null;
+        }
+        catch {
+            return null;
+        }
+    }
+
     var ScrubCursorState;
     (function (ScrubCursorState) {
         ScrubCursorState["Idle"] = "idle";
@@ -27414,8 +27499,10 @@
         }
         const displayWidth = videoTrack.displayWidth;
         const displayHeight = videoTrack.displayHeight;
-        const durationS = asSec(await readTrackDurationS(videoTrack));
         const timeline = await readFrameTimeline(videoTrack);
+        // The demuxer measures a track to the end of its last packet, which falls
+        // short when that packet states no duration and the timeline found one.
+        const durationS = asSec(Math.max(await readTrackDurationS(videoTrack), timeline.endTicksAt(timeline.frameCount - 1) / timeline.tickRate));
         // 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
@@ -27470,47 +27557,6 @@
             ? new WebVideoEngineError(WebVideoEngineErrorCode.VideoTrackUnreadable, "openInput: the container opened and the demuxer parsed no track out of it")
             : new WebVideoEngineError(WebVideoEngineErrorCode.NoVideoTrack, "openInput: the container's tracks read and none of them carries video");
     }
-    /**
-     * Walks the track's packets metadata-only and records each one's timestamp in
-     * 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 WebVideoEngineError(WebVideoEngineErrorCode.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 WebVideoEngineError(WebVideoEngineErrorCode.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. True only when every condition holds: the 2D path is not pinned, the
      * strategy decodes at native (no downscale), and the realm offers WebGPU's
@@ -28013,7 +28059,10 @@
             const exactWidth = Math.max(1, Math.round(options.exactWidth));
             const exactHeight = Math.max(1, Math.round(options.exactHeight));
             const aspect = exactWidth / exactHeight;
-            const previewWidth = Math.max(1, Math.round(options.previewWidth));
+            const configuredPreviewWidth = Math.max(1, Math.round(options.previewWidth));
+            const previewWidth = options.fitPreviewToOutput
+                ? Math.min(configuredPreviewWidth, exactWidth)
+                : configuredPreviewWidth;
             const previewHeight = Math.max(1, Math.round(previewWidth / aspect));
             const frameBytes = exactWidth * exactHeight * BYTES_PER_PIXEL;
             const floor = Math.max(1, Math.floor(options.minExactSlots ?? 1));
@@ -28027,7 +28076,10 @@
             // pretending the floor's frames fit a smaller budget.
             this.exactBudgetBytes = Math.max(Math.max(0, options.exactBudgetBytes), exactCapacity * frameBytes);
             this.exact = new TierStore(exactCapacity, exactWidth, exactHeight, FRAME_IDENTITY_KEY_GRID_MS);
-            this.preview = new TierStore(Math.max(0, Math.floor(options.previewCapacity)), previewWidth, previewHeight, PREVIEW_KEY_GRID_MS);
+            this.preview = new TierStore(Math.min(Math.max(0, Math.floor(options.previewCapacity)), options.previewBudgetBytes === undefined
+                ? Infinity
+                : Math.max(0, Math.floor(options.previewBudgetBytes /
+                    (previewWidth * previewHeight * BYTES_PER_PIXEL)))), previewWidth, previewHeight, PREVIEW_KEY_GRID_MS);
         }
         resized(width, height) {
             return new FrameCache({
@@ -28076,6 +28128,11 @@
             const coarse = this.preview.get(timestampMs, previewTolMs);
             return coarse ? { ...coarse, tier: FrameTier.Preview } : null;
         }
+        /** Preview-only lookup without hit accounting or LRU promotion. */
+        peekPreview(timestampMs, toleranceMs) {
+            const coarse = this.preview.peek(timestampMs, toleranceMs);
+            return coarse ? { ...coarse, tier: FrameTier.Preview } : null;
+        }
         /**
          * Best cached frame for `timestampMs`, consulting the exact tier then the
          * preview tier: a crisp hit within `exactTolMs`, else a coarse hit within
@@ -28148,6 +28205,10 @@
         bumpExactFrame(frame) {
             this.exact.touchKey(frame.ticks);
         }
+        /** Protects a resident preview during a sweep that fills other targets. */
+        bumpPreview(timestampMs) {
+            this.preview.touch(timestampMs);
+        }
         clear() {
             this.exact.clear();
             this.preview.clear();
@@ -28284,6 +28345,15 @@
             this.bump(best.key);
             return { canvas: entry.canvas, timestampMs: entry.timestampMs };
         }
+        peek(timestampMs, tolMs) {
+            const best = this.nearest(timestampMs, false);
+            if (!best || best.delta > tolMs)
+                return null;
+            const entry = this.entries.get(best.key);
+            return entry
+                ? { canvas: entry.canvas, timestampMs: entry.timestampMs }
+                : null;
+        }
         /** Retrieves exactly one owner-assigned key and promotes it to MRU. */
         getByKey(key) {
             const entry = this.entries.get(key);
@@ -28692,6 +28762,8 @@
     /** Keyframes one idle sweep decodes; a short-GOP source offers far more inside
      *  the span than a background walk should hold the decoder for. */
     const PREVIEW_SWEEP_MAX_FRAMES = 8;
+    /** A provider may round or truncate timestamps onto WebCodecs' microseconds. */
+    const DECODE_TIMESTAMP_ROUNDING_MS = 0.001;
     /** Spends the sweep budget nearest the playhead, then returns to ascending
      *  order: the decoder flushes and re-walks the GOP on a backward step, so the
      *  batch it receives has to climb even though the budget was spent outward. */
@@ -29082,7 +29154,7 @@
                 return null;
             const pos = this.currentPositionS();
             const targetsS = this.mode === AccessMode.Idle
-                ? selectPreviewTargets(this.keyframeIndex.known.filter((k) => Math.abs(k - pos) <= PREVIEW_SWEEP_SPAN_S), pos)
+                ? selectPreviewTargets(this.keyframeIndex.known.filter((k) => Math.abs(k - pos) <= PREVIEW_SWEEP_SPAN_S), pos).filter((targetS) => !this.residentPreviewAt(targetS))
                 : this.windowTimestamps(pos);
             if (!targetsS.length)
                 return null;
@@ -29765,7 +29837,24 @@
                 gen !== this.prefetchGen ||
                 this.closed)
                 return;
-            await this.decodeInto(selectPreviewTargets(keyframes, aroundS), gen, true);
+            const targets = selectPreviewTargets(keyframes, aroundS).filter((targetS) => {
+                const resident = this.residentPreviewAt(targetS);
+                if (!resident)
+                    return true;
+                this.cache.bumpPreview(resident.timestampMs);
+                return false;
+            });
+            await this.decodeInto(targets, gen, true);
+        }
+        residentPreviewAt(timestampS) {
+            const timestampMs = timestampS * 1000;
+            const preview = this.cache.peekPreview(timestampMs, DECODE_TIMESTAMP_ROUNDING_MS +
+                Number.EPSILON * Math.max(1, Math.abs(timestampMs)));
+            return preview &&
+                this.frameIdOf(preview.timestampMs / 1000).ticks ===
+                    this.frameAtTime(timestampS).ticks
+                ? preview
+                : null;
         }
         async decodeInto(timestamps, gen, preview) {
             if (!timestamps.length || gen !== this.prefetchGen || this.closed)
@@ -30094,13 +30183,17 @@
         const bucketMs = fps && fps > 0
             ? Math.max(1, Math.round(1000 / fps))
             : FRAME_CACHE.DEFAULT_BUCKET_MS;
-        const budgets = resolveCacheBudgets(track.decodeWidth, track.decodeHeight, config.previewWidth);
+        const budgets = resolveCacheBudgets(track.decodeWidth, track.decodeHeight);
         return new FrameCache({
             exactWidth: track.decodeWidth,
             exactHeight: track.decodeHeight,
             previewWidth: config.previewWidth,
+            fitPreviewToOutput: config.fitPreviewToOutput,
             exactBudgetBytes: config.exactBudgetBytes ?? budgets.exactBudgetBytes,
-            previewCapacity: config.previewCapacity ?? budgets.previewCapacity,
+            previewCapacity: config.previewCapacity ?? FRAME_CACHE.PREVIEW_SLOTS_MAX,
+            previewBudgetBytes: config.previewCapacity === undefined
+                ? budgets.previewBudgetBytes
+                : undefined,
             bucketMs,
             // Floor the exact tier to one full prefetch window so a huge-frame source
             // does not evict the very neighbors a settle just decoded.
@@ -32752,6 +32845,8 @@ ${VERTEX_STAGE}
                     ? null
                     : {
                         previewWidth: config.previewWidth ?? FRAME_CACHE.PREVIEW_WIDTH_PX,
+                        fitPreviewToOutput: config.previewWidth === undefined &&
+                            this.decodeStrategy.kind === "displayBox",
                         // Budgets omitted: resolveCacheBudgets sizes both tiers
                         // from device memory and frame size. previewCapacity is
                         // still honored as an explicit caller override.
@@ -33482,8 +33577,10 @@ ${VERTEX_STAGE}
          *
          * An exact walk answers at or before the frame it aimed at, and no further
          * back than the sample next to it, so the target falls inside the answering
-         * frame's own span. That span is the whole test: a frame decoded for some
-         * earlier position sits outside it however recently it was painted.
+         * frame's own span. That span is the test: a frame decoded for some earlier
+         * position sits outside it however recently it was painted. The aimed-at
+         * frame answers without it, because a track's last frame has an empty span
+         * when its file states no duration for it.
          */
         answersAwaitedSeek(painted, isKeyFrame) {
             const awaited = this.awaitedSeek;
@@ -33493,7 +33590,8 @@ ${VERTEX_STAGE}
                 return false;
             if (awaited.keyOnly)
                 return isKeyFrame;
-            return awaited.target.ticks < this.timeline().endTicksAt(painted.index);
+            return (painted.ticks === awaited.target.ticks ||
+                awaited.target.ticks < this.timeline().endTicksAt(painted.index));
         }
         /** The frame table of the loaded source. Reached only from paths that have
          *  already established a cursor, which is what carries it. */

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

@@ -75,10 +75,14 @@ export interface FrameCacheOptions {
     readonly exactHeight: number;
     /** Coarse-tier width; height derives from the exact aspect ratio. */
     readonly previewWidth: number;
+    /** Limit the configured coarse width to the current decode width. */
+    readonly fitPreviewToOutput?: boolean;
     /** Crisp scrub-tier RAM ceiling in bytes; slot count derives from frame size. */
     readonly exactBudgetBytes: number;
     /** Coarse-tier slot count. */
     readonly previewCapacity: number;
+    /** Coarse-tier byte ceiling, additionally limiting its slot count. */
+    readonly previewBudgetBytes?: number;
     /** Source frame interval in ms, reported to diagnostics as the timeline mark
      *  width. It keys nothing. */
     readonly bucketMs: number;
@@ -116,6 +120,8 @@ export declare class FrameCache {
     getForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
     /** Non-accounting form of {@link getForFrame}. */
     peekForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
+    /** Preview-only lookup without hit accounting or LRU promotion. */
+    peekPreview(timestampMs: number, toleranceMs: number): CachedFrame | null;
     /**
      * Best cached frame for `timestampMs`, consulting the exact tier then the
      * preview tier: a crisp hit within `exactTolMs`, else a coarse hit within
@@ -145,6 +151,8 @@ export declare class FrameCache {
     bumpExact(timestampMs: number): void;
     /** Promotes one exact frame by identity. */
     bumpExactFrame(frame: FrameId): void;
+    /** Protects a resident preview during a sweep that fills other targets. */
+    bumpPreview(timestampMs: number): void;
     clear(): void;
     get stats(): FrameCacheStats;
 }
@@ -201,6 +209,7 @@ export declare class TierStore {
      * alternate.
      */
     get(timestampMs: number, tolMs: number, atOrBefore?: boolean): TierHit | null;
+    peek(timestampMs: number, tolMs: number): TierHit | null;
     /** Retrieves exactly one owner-assigned key and promotes it to MRU. */
     getByKey(key: number): TierHit | null;
     /** Promotes the entry nearest `timestampMs` to most-recently-used. Scans

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

@@ -0,0 +1 @@
+export { readFrameIndex, readFrameTimeline } from "./frame-timeline-reader";

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

@@ -0,0 +1,97 @@
+import { EncodedPacketSink } from 'mediabunny';
+import { h as FRAME_TIMELINE, W as WebVideoEngineError, b as WebVideoEngineErrorCode, F as FrameTimeline } from './frame-timeline-CYgzzmpA.js';
+
+/**
+ * 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. A WebM block need not state a
+ * duration, which the demuxer reads as zero, so a last frame without one is
+ * given a duration from elsewhere.
+ */
+async function readFrameTimeline(videoTrack) {
+    return (await readFrameIndex(videoTrack)).timeline;
+}
+/**
+ * The same walk, also naming the key frames: the presentation index of every
+ * frame a decode can start at, ascending.
+ */
+async function readFrameIndex(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 = [];
+    const keyTicks = new Set();
+    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 WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, `openInput: source video track carries more than ${FRAME_TIMELINE.MAX_FRAMES} frames`);
+        }
+        ticks.push(at);
+        if (packet.type === "key")
+            keyTicks.add(at);
+        if (at >= lastTicks) {
+            lastTicks = at;
+            lastDurationTicks = Math.round(packet.duration * tickRate);
+        }
+    }
+    if (ticks.length === 0) {
+        throw new WebVideoEngineError(WebVideoEngineErrorCode.DecodeUnsupported, "openInput: source video track has no frames");
+    }
+    ticks.sort((a, b) => a - b);
+    if (lastDurationTicks === 0) {
+        lastDurationTicks = await unstatedLastDurationTicks(track, ticks, tickRate);
+    }
+    const timeline = FrameTimeline.from({
+        lastDurationTicks,
+        tickRate,
+        ticks: Float64Array.from(ticks),
+    });
+    const { ticks: presented, sourceTicks = presented } = timeline.toData();
+    const keyIndices = [];
+    for (let index = 0; index < sourceTicks.length; index += 1) {
+        if (keyTicks.has(sourceTicks[index]))
+            keyIndices.push(index);
+    }
+    return { keyIndices: Int32Array.from(keyIndices), timeline };
+}
+/**
+ * How long the last frame lasts when its packet does not say: until the end
+ * the container states for the track, else as long as the frame before it. A
+ * lone frame with neither keeps a span of no time.
+ */
+async function unstatedLastDurationTicks(track, ticks, tickRate) {
+    const lastTicks = ticks[ticks.length - 1];
+    const statedEndS = await readStatedEndS(track);
+    if (statedEndS !== null) {
+        const toStatedEnd = Math.round(statedEndS * tickRate) - lastTicks;
+        if (toStatedEnd > 0)
+            return toStatedEnd;
+    }
+    let before = ticks.length - 2;
+    while (before >= 0 && ticks[before] === lastTicks)
+        before -= 1;
+    return before >= 0 ? lastTicks - ticks[before] : 0;
+}
+async function readStatedEndS(track) {
+    if (typeof track.getDurationFromMetadata !== "function")
+        return null;
+    try {
+        const endS = await track.getDurationFromMetadata();
+        return typeof endS === "number" && Number.isFinite(endS) ? endS : null;
+    }
+    catch {
+        return null;
+    }
+}
+
+export { readFrameIndex, readFrameTimeline };

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

@@ -310,114 +310,6 @@ function resolvePlaybackRate(rate) {
     return rate;
 }
 
-/**
- * Decode-resolution strategies. A strategy decides the pixel width each video
- * frame is decoded to, independent of the source's native resolution. Height
- * follows from native aspect, so a strategy only ever returns a width.
- *
- * Decoding below native trades preview sharpness for paint cost and frame-cache
- * memory. It does NOT cut decode cost: the codec decodes the full coded frame
- * regardless of target width, and CanvasSink resizes the result afterward. The
- * win scales with the gap between source resolution and the on-screen box: a 4K
- * source shown in a 640px surface still pays full 4K decode, but the smaller
- * surface cuts the per-frame paint work and the cached blit size.
- *
- * A strategy applies wherever frames decode through this seam: the live scrub
- * surface and the analysis / extraction path alike. AnalysisSession decodes at
- * whatever strategy it is given (native when omitted), so a thumbnail pass can
- * cache a small blit instead of a native-size one.
- */
-/** Decode at native resolution. The conservative default. */
-function nativeResolution() {
-    return { kind: "native" };
-}
-/**
- * Decode at the on-screen size: canvas CSS width times devicePixelRatio. Best
- * for fixed-size surfaces fed by a much larger source (frame sampler, inline
- * players). Falls back to native while the box is unmeasured.
- *
- * The box it reads is the one bindCanvas measures, so this strategy resolves to
- * native under presentation "frames", where the engine holds no canvas and
- * nothing ever measures one. A frames-mode consumer passes displayBoxResolution
- * instead.
- */
-function viewportResolution(options = {}) {
-    return {
-        kind: "viewport",
-        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
-    };
-}
-/**
- * Decode at no more than maxWidth regardless of display size. For consumers
- * with a hard throughput or memory ceiling (batch surfaces, thumbnail farms).
- */
-function cappedResolution(maxWidth) {
-    return { kind: "capped", maxWidth };
-}
-/**
- * Decode at the size the frame will actually occupy inside a box the consumer
- * describes: native aspect fitted into boxWidth x boxHeight, times the clamped
- * device pixel ratio. Letterboxing is why the box is two numbers and not one,
- * since a portrait source in a landscape box paints far narrower than the box.
- *
- * This is the strategy for presentation "frames". There the consumer owns the
- * compositor, so it is the only side that knows the box, and viewportResolution
- * has nothing to read.
- */
-function displayBoxResolution(options) {
-    return {
-        kind: "displayBox",
-        boxWidth: options.boxWidth,
-        boxHeight: options.boxHeight,
-        devicePixelRatio: options.devicePixelRatio,
-        maxDevicePixelRatio: options.maxDevicePixelRatio ?? 2,
-    };
-}
-/** Runs the descriptor against a context to produce a target decode width. */
-function strategyWidth(strategy, ctx) {
-    switch (strategy.kind) {
-        case "native":
-            return ctx.nativeWidth;
-        case "viewport": {
-            if (ctx.displayWidth === null || ctx.displayWidth <= 0)
-                return ctx.nativeWidth;
-            const dpr = clampDpr(ctx.devicePixelRatio, strategy.maxDevicePixelRatio);
-            return Math.ceil(ctx.displayWidth * dpr);
-        }
-        case "capped":
-            return Math.min(strategy.maxWidth, ctx.nativeWidth);
-        case "displayBox": {
-            const { boxWidth, boxHeight } = strategy;
-            if (!(boxWidth > 0) || !(boxHeight > 0))
-                return ctx.nativeWidth;
-            const fit = Math.min(boxWidth / ctx.nativeWidth, boxHeight / ctx.nativeHeight);
-            const dpr = clampDpr(strategy.devicePixelRatio, strategy.maxDevicePixelRatio);
-            return Math.ceil(ctx.nativeWidth * fit * dpr);
-        }
-    }
-}
-/**
- * Runs a strategy and returns native-bounded, aspect-preserving integer
- * dimensions safe to hand to CanvasSink and to size a canvas backing store.
- * A strategy that returns garbage (non-finite, non-positive) falls back to
- * native rather than producing a broken surface.
- */
-function resolveDecodeDimensions(strategy, ctx) {
-    const nativeWidth = Math.max(1, Math.round(ctx.nativeWidth));
-    const nativeHeight = Math.max(1, Math.round(ctx.nativeHeight));
-    const raw = strategyWidth(strategy, ctx);
-    const width = Number.isFinite(raw) && raw > 0
-        ? Math.min(Math.round(raw), nativeWidth)
-        : nativeWidth;
-    const height = Math.max(1, Math.round((width * nativeHeight) / nativeWidth));
-    return { width, height };
-}
-function clampDpr(dpr, maxDpr) {
-    if (!Number.isFinite(dpr) || dpr <= 0)
-        return 1;
-    return Math.min(dpr, maxDpr);
-}
-
 /**
  * One entry per presentation instant.
  *
@@ -613,4 +505,4 @@ class FrameTimeline {
     }
 }
 
-export { DIAGNOSTICS as D, FRAME_TIMELINE as F, HANG_RECOVERY as H, PlaybackStatus as P, SCRUB as S, TRACE_RING_BOUNDS as T, WebVideoEngineError as W, WebVideoEngineErrorCode as a, asSec as b, SourceKind as c, FrameTimeline as d, asPaintSeq as e, canvasBindingRefused as f, resolvePlaybackRate as g, PLAYBACK_RATE as h, asFps as i, cappedResolution as j, displayBoxResolution as k, nativeResolution as n, resolveDecodeDimensions as r, viewportResolution as v };
+export { DIAGNOSTICS as D, FrameTimeline as F, HANG_RECOVERY as H, PlaybackStatus as P, SourceKind as S, TRACE_RING_BOUNDS as T, WebVideoEngineError as W, asPaintSeq as a, WebVideoEngineErrorCode as b, canvasBindingRefused as c, PLAYBACK_RATE as d, asFps as e, asSec as f, SCRUB as g, FRAME_TIMELINE as h, resolvePlaybackRate as r };

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

@@ -0,0 +1,21 @@
+import { FrameTimeline } from "./frame-timeline";
+/**
+ * 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. A WebM block need not state a
+ * duration, which the demuxer reads as zero, so a last frame without one is
+ * given a duration from elsewhere.
+ */
+export declare function readFrameTimeline(videoTrack: unknown): Promise<FrameTimeline>;
+/**
+ * The same walk, also naming the key frames: the presentation index of every
+ * frame a decode can start at, ascending.
+ */
+export declare function readFrameIndex(videoTrack: unknown): Promise<{
+    readonly timeline: FrameTimeline;
+    readonly keyIndices: Int32Array;
+}>;