supervision 0.2.0-next.1 → 0.2.0-next.2

package/dist/index.js

@@ -1,7 +1,7 @@
 import { copySortedDetectionFrames, detectionFrameOverlapsRange, projectDetectionFrameForTracking, createSortTracker, createOCSortTracker, createCBIoUTracker, createByteTrackTracker, MediaErrorKind, includeDefined, MediaSourceStatus, MediaRendererPlaybackState, MediaRendererFit, createDefaultAnnotationPresentation, createProjectedDetectionFrameSource, createArrayDetectionFrameSource, createBufferedDetectionTimeline, resolveAnnotationRendererPresentation, PlaybackGateReach, createIdleDetectionBufferState, MediaInteractionMode, decodeCompressedRleMask, createIdMaskFrame, encodeBinaryMask, rasterizePolygonToMask, resolveIdMaskPaletteId, decodeCompressedRleCounts, canReuseMaskStyleArtifacts, getBufferedDetectionTimelineFrameSnapshot, MAX_ID_MASK_PALETTE_ENTRIES, StrokeAlignment, BaseBoxStyle, centerRectToTopLeftRect, BoxShape, BaseFocusStyle, extractDetectionMaskRectRuns, AnnotationGestureStateKind, AnnotationHandleKind, getDetectionRect, DetectionPickTarget, createDetectionPickKey, rebaseDetectionPickToFrame, pickDetectionAtPoint, followDetectionPickAcrossFrames, haveSameDetectionPickIdentities, pickAnnotationHandle, getAnnotationHandles, LabelPlacement, BasePolygonStyle, BasePolylineStyle, BaseKeypointStyle, ShapeInstructionKind, sampleEllipseArc, resolveEllipseSegmentCount, KeypointMarkerShape, MarkerSizeSpace, MarkerShape, resolveMarkerGeometry, BaseInteractionStyle, DetectionInteractionState, writeIdMaskPaletteEntry, resolveIdMaskStrokeTexels, MAX_ID_MASK_STROKE_WIDTH, DetectionBufferStatus, resolveMaskStyleOpacity, pickDetectionByMaskId, BoxStrokeAlignment, RegionRendererMediaEffectKind, RegionRendererSourceKind, RegionRendererCoverageKind, RegionRendererSizeSpace, resolveStyleValue, resolveAnnotationStyleState, lightenColor, resolveAnnotationRendererStyleFields, annotationRendererKinds, createViewportController, MediaSessionMode, DetectionFrameRetentionMode, createMemoryColdDetectionFrameStore, createWritableDetectionFrameSource, createCompositeDetectionFrameSource, MediaSessionActivityStatus, MediaSessionActivityKind, MediaSessionStatus, createSourceAwarePresentation, projectDetectionFrames, DetectionFrameSelectionMode } from 'supervision-js-core';
 export { BaseBoxCornerStyle, BaseBoxStyle, BaseFocusStyle, BaseInteractionStyle, BaseKeypointStyle, BaseLabelStyle, BaseMarkerStyle, BaseMaskStyle, BasePolygonStyle, BasePolylineStyle, BoxShape, BoxStrokeAlignment, DEFAULT_DETECTION_CLASS_STYLES, DEFAULT_DETECTION_COLOR_SEQUENCE, DetectionBufferStatus, DetectionFrameRetentionMode, DetectionFrameSelectionMode, DetectionInteractionState, DetectionMaskEncoding, DetectionPickTarget, FocusTargetMode, KeypointMarkerShape, KeypointVisibility, LabelPlacement, LabelVisibilityMode, MarkerShape, MarkerSizeSpace, MaskRenderMode, MediaErrorKind, MediaInteractionMode, MediaRendererFit, MediaRendererPlaybackState, MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, MediaSourceStatus, PlaybackGateReach, RegionRendererComposeMode, RegionRendererCoverageKind, RegionRendererMediaEffectKind, RegionRendererRegionKind, RegionRendererSizeSpace, RegionRendererSourceKind, SUPERVISION_ROBOFLOW_COLOR, TrackingGeometry, annotationRendererKinds, annotationRenderers, createArrayDetectionFrameSource, createBufferedDetectionTimeline, createByteTrackTracker, createCBIoUTracker, createColdDetectionFrameSource, createCompositeDetectionFrameSource, createDefaultAnnotationPresentation, createMemoryColdDetectionFrameStore, createOCSortTracker, createProjectedDetectionFrameSource, createSortTracker, createWritableDetectionFrameSource, detectionPostProcessors, normalizeDetectionClassName, pickDetectionAtPoint, projectDetectionFrame, projectDetectionFrameForTracking, projectDetectionFrames, resolveDetectionClassColorStyle } from 'supervision-js-core';
-import { M as MediaSourceError, t as toMediaSourceError, r as resolveDisplayPixelRatio } from './video-engine-media-source-CUXnOJOV.js';
-export { c as createWebVideoEngineMediaRendererSource, g as getMediaErrorKind, i as isMediaSourceError, o as openWebVideoEngineMediaSource } from './video-engine-media-source-CUXnOJOV.js';
+import { M as MediaSourceError, t as toMediaSourceError, r as resolveDisplayPixelRatio } from './video-engine-media-source-DR-x1UfK.js';
+export { c as createWebVideoEngineMediaRendererSource, g as getMediaErrorKind, i as isMediaSourceError, o as openWebVideoEngineMediaSource } from './video-engine-media-source-DR-x1UfK.js';
 
 const DEFAULT_DATABASE_NAME = "supervision-js-detection-frames";
 const DEFAULT_CHUNK_DURATION_SECONDS = 1;
@@ -2341,7 +2341,7 @@ function createMediaPlaybackController(options) {
             ((now - playbackOriginNow) / 1000) * playbackRate;
         const playableEnd = options.duration === null
             ? null
-            : options.firstTimestamp + Math.max(options.duration, 0);
+            : Math.max(options.firstTimestamp, options.duration);
         let shouldPresentLoopStartSample = false;
         if (playableEnd !== null && requestedMediaTime >= playableEnd) {
             if (!options.loop) {
@@ -2959,6 +2959,178 @@ function createMediaRenderErrorSourcePatch(error) {
     };
 }
 
+function createMediaFrameNavigation(options) {
+    let activeOperation = null;
+    let displayed = null;
+    let destroyed = false;
+    let destroyError;
+    const controller = {
+        api: {
+            moveToFrame(index) {
+                return startMove(() => landingAt(index));
+            },
+            moveToTime(mediaTime) {
+                return startMove(() => landingAt(options.clock.indexAtOrBefore(mediaTime)));
+            },
+            scrubToFrame(index) {
+                const target = landingAt(index);
+                return startScrub(target);
+            },
+            scrubToTime(mediaTime) {
+                const target = landingAt(options.clock.indexAtOrBefore(mediaTime));
+                return startScrub(target);
+            },
+        },
+        presented(frame) {
+            displayed = frame;
+            const operation = activeOperation;
+            if (!operation ||
+                frame.index !== operation.target.index ||
+                frame.mediaTime !== operation.target.mediaTime) {
+                return;
+            }
+            if (operation.kind === "scrub") {
+                activeOperation = null;
+                operation.resolve({ frame: operation.target, status: "landed" });
+                return;
+            }
+            operation.presented = true;
+        },
+        cancel() {
+            supersedeActive(createAbortError("Media frame navigation was superseded."));
+        },
+        destroy(error) {
+            if (destroyed) {
+                return;
+            }
+            destroyed = true;
+            destroyError =
+                error ?? createAbortError("Media frame navigation was destroyed.");
+            supersedeActive(destroyError);
+        },
+    };
+    return controller;
+    function landingAt(index) {
+        return {
+            duration: options.clock.durationAt(index),
+            index,
+            mediaTime: options.clock.timeAt(index),
+        };
+    }
+    function startMove(getTarget) {
+        if (destroyed) {
+            return own(Promise.reject(destroyError));
+        }
+        let target;
+        try {
+            target = getTarget();
+        }
+        catch (error) {
+            return own(Promise.reject(error));
+        }
+        supersedeActive(createAbortError("Media frame navigation was superseded."));
+        let resolve;
+        let reject;
+        const promise = new Promise((resolvePromise, rejectPromise) => {
+            resolve = resolvePromise;
+            reject = rejectPromise;
+        });
+        const operation = {
+            kind: "move",
+            presented: false,
+            reject,
+            resolve,
+            target,
+        };
+        activeOperation = operation;
+        let command;
+        try {
+            command = options.seek(target.mediaTime);
+        }
+        catch (error) {
+            failMove(operation, error);
+            return own(promise);
+        }
+        void Promise.resolve(command).then(() => {
+            if (activeOperation !== operation) {
+                return;
+            }
+            if (!operation.presented && !isDisplayed(operation.target)) {
+                failMove(operation, new Error("Media seek completed without presenting the requested exact frame."));
+                return;
+            }
+            activeOperation = null;
+            operation.resolve(operation.target);
+        }, (error) => {
+            failMove(operation, error);
+        });
+        return own(promise);
+    }
+    function startScrub(target) {
+        if (destroyed) {
+            throw destroyError;
+        }
+        supersedeActive(createAbortError("Media frame navigation was superseded."));
+        let resolve;
+        const settled = new Promise((resolvePromise) => {
+            resolve = resolvePromise;
+        });
+        const operation = {
+            kind: "scrub",
+            resolve,
+            target,
+        };
+        activeOperation = operation;
+        own(settled);
+        try {
+            options.scrub(target.mediaTime);
+            if (activeOperation === operation && isDisplayed(target)) {
+                activeOperation = null;
+                operation.resolve({ frame: target, status: "landed" });
+            }
+        }
+        catch (error) {
+            if (activeOperation === operation) {
+                activeOperation = null;
+                operation.resolve({ status: "superseded" });
+            }
+            throw error;
+        }
+        return { settled, target };
+    }
+    function isDisplayed(target) {
+        return (displayed?.index === target.index &&
+            displayed.mediaTime === target.mediaTime);
+    }
+    function failMove(operation, error) {
+        if (activeOperation !== operation) {
+            return;
+        }
+        activeOperation = null;
+        operation.reject(error);
+    }
+    function supersedeActive(error) {
+        const operation = activeOperation;
+        if (!operation) {
+            return;
+        }
+        activeOperation = null;
+        if (operation.kind === "move") {
+            operation.reject(error);
+        }
+        else {
+            operation.resolve({ status: "superseded" });
+        }
+    }
+}
+function own(promise) {
+    void promise.catch(() => undefined);
+    return promise;
+}
+function createAbortError(message) {
+    return new DOMException(message, "AbortError");
+}
+
 const MILLISECONDS_PER_SECOND$2 = 1000;
 /**
  * The renderer's playback surface over a producer that owns the playhead.
@@ -2985,6 +3157,7 @@ function createMediaRendererTransport(options) {
     let readinessFreezeHeld = false;
     let activeReadinessWait;
     let presentationWait = 0;
+    let displayResize = 0;
     let presentationHold = null;
     const isHoldingForReadiness = () => readinessHoldIntent === playbackIntent ||
         presentationHold?.intent === playbackIntent;
@@ -3143,6 +3316,10 @@ function createMediaRendererTransport(options) {
                     await options.waitForReadiness(channel.getPlayhead().mediaTimeS, readinessWait.signal);
                     readinessLanded = true;
                 }
+                catch (error) {
+                    if (intent === playbackIntent)
+                        throw error;
+                }
                 finally {
                     if (activeReadinessWait === readinessWait) {
                         activeReadinessWait = undefined;
@@ -3176,6 +3353,11 @@ function createMediaRendererTransport(options) {
             // A pause ends the producer's mechanical hold, so it lands ahead of the
             // releases a readiness hold or an open gesture still owe.
             channel.pause();
+            // A gate may already have mechanically paused the producer, so its
+            // no-op pause emits no state signal to retire Buffering.
+            if (channel.getStatus() === "PAUSED") {
+                publishPlaybackState();
+            }
             void releaseReadinessFreeze();
             void releaseGesture();
         },
@@ -3211,7 +3393,7 @@ function createMediaRendererTransport(options) {
             options.invalidatePresentedFrame?.();
             const navigationPresentation = ++presentationWait;
             presentationHold = null;
-            beginPlaybackIntent();
+            const intent = beginPlaybackIntent();
             // Releasing first is what keeps a drag from freezing the picture on
             // release: the producer resumes on its own terms, and the landing decode
             // for a cold region no longer sits between the pointer coming up and
@@ -3229,16 +3411,51 @@ function createMediaRendererTransport(options) {
                     landingRelease = null;
                 }
             }
+            if (intent !== playbackIntent)
+                return;
             const presentation = options.beginPresentedFrameNavigation?.();
             try {
+                const before = channel.getPlayhead().frame;
                 await channel.commit(mediaTime * MILLISECONDS_PER_SECOND$2);
-                await presentation?.waitFor(channel.getPlayhead().frame);
+                if (intent !== playbackIntent) {
+                    presentation?.cancel();
+                    return;
+                }
+                const after = channel.getPlayhead().frame;
+                await presentation?.waitFor(after, before.index === after.index && before.ticks === after.ticks);
             }
             catch (error) {
                 presentation?.cancel();
                 throw error;
             }
         },
+        async resizeOutput(resize) {
+            const intent = playbackIntent;
+            const request = ++displayResize;
+            const assertCurrent = () => {
+                if (intent !== playbackIntent || request !== displayResize)
+                    throw new DOMException("Display resize was superseded.", "AbortError");
+            };
+            // Geometry does not change the viewer's play/pause or annotation gate.
+            // A replacement enters through the same guard as every other frame.
+            const presentation = options.beginPresentedFrameNavigation?.(true);
+            try {
+                const changed = await resize();
+                assertCurrent();
+                if (changed) {
+                    await presentation?.waitFor(channel.getPlayhead().frame);
+                    assertCurrent();
+                }
+                else {
+                    presentation?.cancel();
+                }
+            }
+            catch (error) {
+                presentation?.cancel();
+                assertCurrent();
+                throw error;
+            }
+        },
         async step(direction) {
             options.invalidatePresentedFrame?.();
             const navigationPresentation = ++presentationWait;
@@ -3277,15 +3494,17 @@ function createMediaRendererTransport(options) {
             const guarded = options.waitForPresentationReadiness(mediaTime, signal);
             if (!guarded) {
                 if (presentationHold) {
-                    presentationWait += 1;
-                    presentationHold = null;
-                    void releaseReadinessFreeze().then(publishPlaybackState);
+                    presentationHold = {
+                        intent: playbackIntent,
+                        ready: true,
+                        wait: ++presentationWait,
+                    };
                 }
                 return null;
             }
             const wait = ++presentationWait;
             const intent = playbackIntent;
-            presentationHold = { intent, wait };
+            presentationHold = { intent, ready: false, wait };
             readinessFreezeHeld = true;
             channel.beginInteractiveSeek();
             publishPlaybackState();
@@ -3298,18 +3517,22 @@ function createMediaRendererTransport(options) {
                     // provider's diagnostics own the error while the frame stays visible.
                 }
                 finally {
-                    if (presentationHold?.wait === wait) {
-                        presentationHold = null;
-                    }
-                    // An aborted frame hands the existing freeze to a newer frame. A
-                    // navigation increments presentationWait and releases explicitly.
                     if (wait === presentationWait && !signal.aborted) {
-                        await releaseReadinessFreeze();
-                        publishPlaybackState();
+                        presentationHold = { intent, ready: true, wait };
                     }
                 }
             })();
         },
+        didPresentFrame() {
+            const hold = presentationHold;
+            if (!hold?.ready ||
+                hold.intent !== playbackIntent ||
+                hold.wait !== presentationWait) {
+                return;
+            }
+            presentationHold = null;
+            return releaseReadinessFreeze().then(publishPlaybackState);
+        },
         destroy() {
             presentationWait += 1;
             presentationHold = null;
@@ -3363,13 +3586,14 @@ function isSettling(status, seeking) {
  * VideoFrame, so stale readiness can never authorize presentation after a new
  * seek. The downstream handler owns a frame only after the guard succeeds.
  */
-function createProtectedPresentedFrameSource(upstream, onPresentationError = () => undefined) {
+function createProtectedPresentedFrameSource(upstream, onPresentationError = () => undefined, onAccepted, onPresented) {
     let downstream = null;
     let protect = null;
     let pending = null;
     let active = null;
-    let navigation = null;
+    const navigations = new Set();
     let generation = 0;
+    let lastAcceptedKey = null;
     let destroyed = false;
     let firstPresented = false;
     let resolveFirstPresentation;
@@ -3392,27 +3616,27 @@ function createProtectedPresentedFrameSource(upstream, onPresentationError = ()
         if (ticket.settled)
             return;
         ticket.settled = true;
-        if (navigation === ticket)
-            navigation = null;
+        navigations.delete(ticket);
         if (error === undefined)
             ticket.resolve();
         else
             ticket.reject(error);
     };
-    const acceptNavigationFrame = (frameId) => {
-        const ticket = navigation;
-        if (!ticket || ticket.settled)
-            return;
+    const acceptNavigationFrame = (frameId, frameGeneration) => {
         const accepted = frameKey(frameId);
-        ticket.accepted.add(accepted);
-        if (ticket.target === accepted)
-            settleNavigation(ticket);
+        for (const ticket of navigations) {
+            if (frameGeneration <= ticket.afterGeneration)
+                continue;
+            ticket.accepted.add(accepted);
+            if (ticket.target === accepted)
+                settleNavigation(ticket);
+        }
     };
     const failPresentation = (error) => {
         if (!firstPresented)
             rejectFirstPresentation(error);
-        if (navigation)
-            settleNavigation(navigation, error);
+        for (const ticket of navigations)
+            settleNavigation(ticket, error);
         if (firstPresented)
             onPresentationError(error);
     };
@@ -3450,29 +3674,64 @@ function createProtectedPresentedFrameSource(upstream, onPresentationError = ()
             run.handedOff = true;
             try {
                 const acknowledge = frame.acknowledgePresentation;
-                downstream(acknowledge
-                    ? {
-                        ...frame,
-                        acknowledgePresentation: () => {
-                            if (destroyed ||
-                                controller.signal.aborted ||
-                                run.generation !== generation) {
-                                return;
+                let acknowledged = false;
+                downstream({
+                    ...frame,
+                    acknowledgePresentation: () => {
+                        if (acknowledged ||
+                            destroyed ||
+                            controller.signal.aborted ||
+                            run.generation !== generation) {
+                            return;
+                        }
+                        acknowledged = true;
+                        try {
+                            acknowledge?.();
+                        }
+                        catch (error) {
+                            failPresentation(error);
+                            return;
+                        }
+                        if (destroyed ||
+                            controller.signal.aborted ||
+                            run.generation !== generation) {
+                            return;
+                        }
+                        try {
+                            const release = onPresented?.();
+                            if (release) {
+                                void release.catch((error) => {
+                                    if (!destroyed &&
+                                        !controller.signal.aborted &&
+                                        run.generation === generation) {
+                                        failPresentation(error);
+                                    }
+                                });
                             }
-                            acknowledge();
-                        },
-                    }
-                    : frame);
+                        }
+                        catch (error) {
+                            failPresentation(error);
+                            return;
+                        }
+                        if (destroyed ||
+                            controller.signal.aborted ||
+                            run.generation !== generation) {
+                            return;
+                        }
+                        lastAcceptedKey = frameKey(frame.frameId);
+                        onAccepted?.(frame.frameId, frame.mediaTimeS);
+                        acceptNavigationFrame(frame.frameId, run.generation);
+                        if (!firstPresented) {
+                            firstPresented = true;
+                            resolveFirstPresentation();
+                        }
+                    },
+                });
             }
             catch (error) {
                 failPresentation(error);
                 return;
             }
-            acceptNavigationFrame(frame.frameId);
-            if (!firstPresented) {
-                firstPresented = true;
-                resolveFirstPresentation();
-            }
         };
         let guarded;
         try {
@@ -3532,16 +3791,18 @@ function createProtectedPresentedFrameSource(upstream, onPresentationError = ()
             cancelActive();
             pending?.frame.close();
             pending = null;
-            if (navigation)
-                settleNavigation(navigation);
-        },
-        beginNavigation() {
-            generation += 1;
-            cancelActive();
-            pending?.frame.close();
-            pending = null;
-            if (navigation)
-                settleNavigation(navigation);
+            for (const ticket of navigations)
+                settleNavigation(ticket);
+        },
+        beginNavigation(preserveCurrent = false) {
+            if (!preserveCurrent) {
+                generation += 1;
+                cancelActive();
+                pending?.frame.close();
+                pending = null;
+                for (const ticket of navigations)
+                    settleNavigation(ticket);
+            }
             let resolve;
             let reject;
             const promise = new Promise((onResolve, onReject) => {
@@ -3553,20 +3814,28 @@ function createProtectedPresentedFrameSource(upstream, onPresentationError = ()
             void promise.catch(() => undefined);
             const ticket = {
                 accepted: new Set(),
+                afterGeneration: generation,
                 promise,
                 reject,
                 resolve,
                 settled: false,
                 target: null,
             };
-            navigation = ticket;
+            navigations.add(ticket);
             return {
-                waitFor(frameId) {
+                waitFor(frameId, allowCurrent = false) {
                     if (ticket.settled)
                         return ticket.promise;
                     ticket.target = frameKey(frameId);
                     if (ticket.accepted.has(ticket.target))
                         settleNavigation(ticket);
+                    if (allowCurrent &&
+                        lastAcceptedKey === ticket.target &&
+                        generation === ticket.afterGeneration &&
+                        pending === null &&
+                        active === null) {
+                        settleNavigation(ticket);
+                    }
                     return ticket.promise;
                 },
                 cancel() {
@@ -3583,8 +3852,8 @@ function createProtectedPresentedFrameSource(upstream, onPresentationError = ()
             cancelActive();
             pending?.frame.close();
             pending = null;
-            if (navigation)
-                settleNavigation(navigation);
+            for (const ticket of navigations)
+                settleNavigation(ticket);
             upstream.onPresentedFrame((presented) => presented.frame.close());
             if (!firstPresented)
                 resolveFirstPresentation();
@@ -3723,6 +3992,8 @@ async function createMediaRendererCore(options, providers) {
             options.onState?.(state);
         },
     });
+    let frameClock = null;
+    let frameNavigation;
     let activeSampleIterator;
     let mediaInput;
     let playbackController;
@@ -3789,6 +4060,7 @@ async function createMediaRendererCore(options, providers) {
                 runtimeState.setLoading();
                 break;
             case MediaRendererPlaybackState.Error:
+                frameNavigation?.cancel();
                 runtimeState.setRenderError(new Error("Media playback failed."));
                 break;
         }
@@ -4104,8 +4376,53 @@ async function createMediaRendererCore(options, providers) {
             });
         });
     };
+    const seekMediaTime = async (mediaTime) => {
+        if (runtimeState.isDestroyed()) {
+            throw new Error("Media renderer has been destroyed.");
+        }
+        if (runtimeState.isError()) {
+            throw new Error(runtimeState.errorMessage() ?? "Media renderer is in error state.");
+        }
+        const targetTime = clampSeekTime({
+            duration: runtimeState.duration(),
+            firstTimestamp,
+            mediaTime,
+        });
+        endSeekGesture();
+        if (transport) {
+            await transport.commit(targetTime);
+            return;
+        }
+        await seekPullSample(targetTime);
+    };
+    const scrubMediaTime = (mediaTime) => {
+        if (runtimeState.isDestroyed() || runtimeState.isError())
+            return;
+        const targetTime = clampSeekTime({
+            duration: runtimeState.duration(),
+            firstTimestamp,
+            mediaTime,
+        });
+        isSeekGestureInFlight = true;
+        publishPlaybackActivity();
+        if (transport) {
+            transport.scrub(targetTime);
+            return;
+        }
+        pendingPullScrubTime = targetTime;
+        if (pullScrubReadInFlight)
+            navigationVersion += 1;
+        schedulePullScrubPreview();
+    };
     const renderer = {
+        get frameClock() {
+            return frameClock;
+        },
+        get frameNavigation() {
+            return frameNavigation?.api ?? null;
+        },
         async play() {
+            frameNavigation?.cancel();
             if (runtimeState.isDestroyed()) {
                 throw new Error("Media renderer has been destroyed.");
             }
@@ -4134,6 +4451,7 @@ async function createMediaRendererCore(options, providers) {
             playbackController.play();
         },
         pause() {
+            frameNavigation?.cancel();
             if (runtimeState.isDestroyed()) {
                 return;
             }
@@ -4149,6 +4467,7 @@ async function createMediaRendererCore(options, providers) {
             playbackController?.pause();
         },
         async togglePlayback() {
+            frameNavigation?.cancel();
             if (runtimeState.isDestroyed()) {
                 return;
             }
@@ -4164,49 +4483,19 @@ async function createMediaRendererCore(options, providers) {
             await renderer.play();
         },
         async seek(mediaTime) {
-            if (runtimeState.isDestroyed()) {
-                throw new Error("Media renderer has been destroyed.");
-            }
-            if (runtimeState.isError()) {
-                throw new Error(runtimeState.errorMessage() ?? "Media renderer is in error state.");
-            }
-            const targetTime = clampSeekTime({
-                duration: runtimeState.duration(),
-                firstTimestamp,
-                mediaTime,
-            });
-            endSeekGesture();
-            if (transport) {
-                await transport.commit(targetTime);
-                return;
-            }
-            await seekPullSample(targetTime);
+            frameNavigation?.cancel();
+            await seekMediaTime(mediaTime);
         },
         scrub(mediaTime) {
-            if (runtimeState.isDestroyed() || runtimeState.isError()) {
-                return;
-            }
-            const targetTime = clampSeekTime({
-                duration: runtimeState.duration(),
-                firstTimestamp,
-                mediaTime,
-            });
-            isSeekGestureInFlight = true;
-            publishPlaybackActivity();
-            if (transport) {
-                transport.scrub(targetTime);
-                return;
-            }
-            pendingPullScrubTime = targetTime;
-            if (pullScrubReadInFlight) {
-                navigationVersion += 1;
-            }
-            schedulePullScrubPreview();
+            frameNavigation?.cancel();
+            scrubMediaTime(mediaTime);
         },
         async stepForward() {
+            frameNavigation?.cancel();
             await stepToAdjacentSample("forward");
         },
         async stepBackward() {
+            frameNavigation?.cancel();
             await stepToAdjacentSample("backward");
         },
         setPlaybackRate(playbackRate) {
@@ -4246,7 +4535,7 @@ async function createMediaRendererCore(options, providers) {
             if (requestVersion !== navigationVersion || runtimeState.isDestroyed()) {
                 return;
             }
-            const presentedSample = mediaScene.setPresentation(currentPresentation, mediaTime);
+            const presentedSample = mediaScene.setPresentation(currentPresentation, runtimeState.presentedTime() ?? runtimeState.currentTime());
             if (presentedSample) {
                 runtimeState.recordPresentationUpdate(presentedSample);
             }
@@ -4337,6 +4626,7 @@ async function createMediaRendererCore(options, providers) {
                 return;
             }
             cancelPullScrubPreview();
+            frameNavigation?.destroy();
             runtimeState.markDestroyed();
             protectedPresentedFrames?.destroy();
             transport?.destroy();
@@ -4355,6 +4645,7 @@ async function createMediaRendererCore(options, providers) {
             throw new Error("Provide either detectionFrames or detectionSource, not both.");
         }
         const mediaSource = await openRendererMediaSource(options, providers);
+        frameClock = mediaSource.frameClock ?? null;
         mediaInput = mediaSource.input;
         sampleSink = mediaSource.sampleSink;
         if (runtimeState.isDestroyed()) {
@@ -4388,11 +4679,12 @@ async function createMediaRendererCore(options, providers) {
                 // the producer keeps running. Cut off future frames and state
                 // signals before publishing the rendering failure.
                 protectedPresentedFrames?.destroy();
+                frameNavigation?.destroy(error);
                 transport?.destroy();
                 presentedFrameChannel.pause();
                 if (!runtimeState.isDestroyed())
                     runtimeState.setRenderError(error);
-            })
+            }, (id, mediaTime) => frameNavigation?.presented({ index: id.index, mediaTime }), () => transport?.didPresentFrame())
             : undefined;
         const mediaDimensions = runtimeState.recordMediaMetadata(metadata);
         mediaScene = await providers.createScene({
@@ -4437,14 +4729,13 @@ async function createMediaRendererCore(options, providers) {
         });
         publishPlaybackActivity();
         runtimeState.setRendererBackend(mediaScene.rendererBackend);
-        detectionTimeline.setTimelineContext?.({
-            duration: metadata.duration,
-            loop: options.loop !== false,
-        });
-        mediaScene.setTimelineContext?.({
+        const timelineContext = {
             duration: metadata.duration,
+            firstTimestamp: metadata.firstTimestamp,
             loop: options.loop !== false,
-        });
+        };
+        detectionTimeline.setTimelineContext?.(timelineContext);
+        mediaScene.setTimelineContext?.(timelineContext);
         mediaScene.initializeMedia(mediaDimensions);
         runtimeState.setSourceReady(metadata);
         if (presentedFrameChannel) {
@@ -4474,9 +4765,35 @@ async function createMediaRendererCore(options, providers) {
                     ? holdForPresentationReadiness
                     : undefined,
                 invalidatePresentedFrame: () => protectedPresentedFrames?.invalidate(),
-                beginPresentedFrameNavigation: () => protectedPresentedFrames.beginNavigation(),
+                beginPresentedFrameNavigation: (preserveCurrent) => protectedPresentedFrames.beginNavigation(preserveCurrent),
             });
-            protectedPresentedFrames?.activate((presented, signal) => transport.protectPresentation(presented.mediaTimeS, signal));
+            const setDisplay = mediaSource.setDisplay;
+            if (setDisplay) {
+                renderer.setDisplay = async (display) => {
+                    if (runtimeState.isDestroyed())
+                        throw new Error("Media renderer has been destroyed.");
+                    await transport.resizeOutput(() => setDisplay(display));
+                };
+            }
+            if (frameClock) {
+                frameNavigation = createMediaFrameNavigation({
+                    clock: frameClock,
+                    seek: seekMediaTime,
+                    scrub(mediaTime) {
+                        if (runtimeState.isDestroyed()) {
+                            throw new Error("Media renderer has been destroyed.");
+                        }
+                        if (runtimeState.isError()) {
+                            throw new Error(runtimeState.errorMessage() ??
+                                "Media renderer is in error state.");
+                        }
+                        scrubMediaTime(mediaTime);
+                    },
+                });
+            }
+            protectedPresentedFrames?.activate((presented, signal) => pushPresentationReady
+                ? transport.protectPresentation(presented.mediaTimeS, signal)
+                : null);
             if (initialPlaybackRate !== 1) {
                 transport.setPlaybackRate(initialPlaybackRate);
             }
@@ -4498,7 +4815,11 @@ async function createMediaRendererCore(options, providers) {
             pushPresentationReady = true;
             runtimeState.setReady();
             if (options.autoPlay ?? true) {
-                await renderer.play();
+                // Opening exposes the writer even when autoplay awaits future detections.
+                void renderer.play().catch((error) => {
+                    if (!runtimeState.isDestroyed())
+                        runtimeState.setRenderError(error);
+                });
             }
             return renderer;
         }
@@ -4662,7 +4983,7 @@ function clampSeekTime(options) {
     const startTime = options.firstTimestamp;
     const endTime = options.duration === null
         ? null
-        : options.firstTimestamp + Math.max(options.duration, 0);
+        : Math.max(options.firstTimestamp, options.duration);
     return Math.min(Math.max(mediaTime, startTime), endTime ?? mediaTime);
 }
 
@@ -5559,9 +5880,10 @@ function createPreparedWindowTimeline() {
         },
     };
     function isLoopingTimeline() {
+        const firstTimestamp = timelineContext.firstTimestamp ?? 0;
         return (timelineContext.loop &&
             timelineContext.duration !== null &&
-            timelineContext.duration > 0);
+            timelineContext.duration > firstTimestamp);
     }
     /**
      * Travel forward from `mediaTime` to `frameTime`, wrapping at the media end,
@@ -5571,11 +5893,12 @@ function createPreparedWindowTimeline() {
         if (!isLoopingTimeline() || timelineContext.duration === null) {
             return Math.max(0, frameTime - mediaTime);
         }
-        const duration = timelineContext.duration;
-        const normalizedFrameTime = modulo(frameTime, duration);
-        const normalizedMediaTime = modulo(mediaTime, duration);
+        const firstTimestamp = timelineContext.firstTimestamp ?? 0;
+        const loopSpan = timelineContext.duration - firstTimestamp;
+        const normalizedFrameTime = firstTimestamp + modulo(frameTime - firstTimestamp, loopSpan);
+        const normalizedMediaTime = firstTimestamp + modulo(mediaTime - firstTimestamp, loopSpan);
         const rawDistance = normalizedFrameTime - normalizedMediaTime;
-        return rawDistance >= 0 ? rawDistance : rawDistance + duration;
+        return rawDistance >= 0 ? rawDistance : rawDistance + loopSpan;
     }
     /**
      * The buffer's end time is the far edge of what the playhead reaches next, and
@@ -6642,17 +6965,23 @@ function createPreparedAnnotationWindow(options) {
     const spanFrameCount = resolvePreparedWindowFrameCount({
         renderPreparation: options.renderPreparation,
     });
+    const frameRevisions = new WeakMap();
+    let nextFrameRevision = 0;
     const getPreparedFrame = (mediaTime) => options.detectionTimeline.selectFrame(mediaTime) ?? null;
     const isFrameArtifactPrepared = (mediaTime) => options.getLayers().every((layer) => layer.isArtifactPrepared(mediaTime));
     return {
         getPreparedFrame,
         getReadinessToken(mediaTime) {
             const detectionFrame = options.detectionTimeline.selectFrame(mediaTime);
+            if (detectionFrame && !frameRevisions.has(detectionFrame)) {
+                frameRevisions.set(detectionFrame, ++nextFrameRevision);
+            }
+            const revision = detectionFrame ? frameRevisions.get(detectionFrame) : 0;
             const cooks = options
                 .getLayers()
                 .map((layer) => (layer.isArtifactPrepared(mediaTime) ? "1" : "0"))
                 .join("");
-            return `${detectionFrame?.frameIndex ?? "time"}:${detectionFrame?.mediaTime ?? "none"}:${cooks}`;
+            return `${detectionFrame?.frameIndex ?? "time"}:${detectionFrame?.mediaTime ?? "none"}:${revision}:${cooks}`;
         },
         getSnapshot() {
             const playheadMediaTime = options.getPlayheadMediaTime();
@@ -13143,13 +13472,14 @@ async function createPixiMediaScene(options) {
             });
         },
     };
-    // The focus fade and the overlay are advanced by a clock: the presented media
-    // time in a push scene, the ticker in a pull one. Drawing them from a walk
-    // that clock did not drive would move them out of turn.
+    // A content redraw updates editing geometry at the same media time without
+    // advancing the focus animation.
     const annotationDrawLayers = {
         ...presentLayers,
         advanceFocus: () => undefined,
-        drawAnnotationOverlay: () => undefined,
+        drawAnnotationOverlay: frameChannel
+            ? presentLayers.drawAnnotationOverlay
+            : () => undefined,
     };
     // A viewport-style redraw covers the layers whose geometry is a function of
     // the viewport scale. Neither the mask raster nor the interaction hit map
@@ -13593,6 +13923,8 @@ async function createPixiMediaScene(options) {
             return pick;
         },
         destroy() {
+            if (isDestroyed)
+                return;
             isDestroyed = true;
             if (displayFrameHandle !== null) {
                 cancelDisplayFrame(displayFrameHandle);
@@ -13634,6 +13966,7 @@ async function createPixiMediaScene(options) {
                 texture: true,
                 textureSource: true,
             });
+            backdrop.remove();
         },
     };
     /**
@@ -14648,10 +14981,11 @@ const STREAM_DETECTION_BUFFER_DEFAULTS = {
     refreshIntervalSeconds: 0.25,
 };
 /**
- * Playback waits for annotations unless a host says otherwise, so a viewer sees
- * a frame and the marks that belong to it together rather than a picture that
- * fills in afterwards. `playbackGate: false` on the session, or either gate's
- * own `enabled`, turns it off.
+ * Once a session is open, playback waits for annotations unless a host says
+ * otherwise, so a viewer sees a frame and the marks that belong to it together.
+ * Opening itself may show a bare initial frame while future annotations arrive.
+ * `playbackGate: false` on the session, or either gate's own `enabled`, turns
+ * it off.
  */
 const DETECTION_PLAYBACK_GATE_DEFAULTS = {
     enabled: true,
@@ -14844,10 +15178,16 @@ async function prepareSessionDetections(options) {
             sourcePresentations: [],
         };
     }
+    const writableSource = isWritableSource(detections.source)
+        ? detections.source
+        : undefined;
     return {
-        appendableSources: new Map(),
+        appendableSource: writableSource,
+        appendableSources: new Map(writableSource ? [[writableSource.datasetId, writableSource]] : []),
         detectionFrames: detections.frames,
-        detectionSource: detections.source,
+        detectionSource: detections.source
+            ? borrowDetectionSource(detections.source)
+            : undefined,
         sourcePresentations: [],
     };
 }
@@ -14866,6 +15206,7 @@ async function prepareMultiSourceSessionDetections(options) {
         throw new Error("detections.sources must include at least one source.");
     }
     const appendableSources = new Map();
+    const ownedSources = [];
     const compositeEntries = [];
     validateMediaSessionDetectionSources(detections.sources);
     try {
@@ -14875,7 +15216,12 @@ async function prepareMultiSourceSessionDetections(options) {
                     appendable: sourceOptions.appendable,
                     mode: options.mode,
                 })
-                : undefined;
+                : isWritableSource(sourceOptions.source)
+                    ? sourceOptions.source
+                    : undefined;
+            if (sourceOptions.appendable && appendableSource) {
+                ownedSources.push(appendableSource);
+            }
             if (appendableSource) {
                 appendableSources.set(sourceOptions.id, appendableSource);
             }
@@ -14884,13 +15230,15 @@ async function prepareMultiSourceSessionDetections(options) {
                 id: sourceOptions.id,
                 order: sourceOptions.order,
                 requiredForCoverage: sourceOptions.requiredForCoverage,
-                source: sourceOptions.source ?? appendableSource,
+                source: sourceOptions.source
+                    ? borrowDetectionSource(sourceOptions.source)
+                    : appendableSource,
                 sync: sourceOptions.sync,
             });
         }
     }
     catch (error) {
-        for (const source of appendableSources.values()) {
+        for (const source of ownedSources) {
             source.destroy?.();
         }
         throw error;
@@ -14907,6 +15255,36 @@ async function prepareMultiSourceSessionDetections(options) {
         })),
     };
 }
+function isWritableSource(source) {
+    const candidate = source;
+    return (typeof candidate?.datasetId === "string" &&
+        [
+            "appendFrames",
+            "replaceFrames",
+            "clear",
+            "getVersion",
+            "getSummary",
+            "waitForRange",
+            "getAvailableRanges",
+        ].every((method) => typeof candidate[method] === "function"));
+}
+function borrowDetectionSource(source) {
+    return {
+        loadFrames: source.loadFrames.bind(source),
+        ...(source.getVersion
+            ? { getVersion: source.getVersion.bind(source) }
+            : {}),
+        ...(source.getChangesSince
+            ? { getChangesSince: source.getChangesSince.bind(source) }
+            : {}),
+        ...(source.getAvailableRanges
+            ? { getAvailableRanges: source.getAvailableRanges.bind(source) }
+            : {}),
+        ...(source.waitForRange
+            ? { waitForRange: source.waitForRange.bind(source) }
+            : {}),
+    };
+}
 function validateMediaSessionDetectionSources(sources) {
     const sourceIds = new Set();
     for (const source of sources) {
@@ -15529,6 +15907,9 @@ async function createMediaSession(options) {
             };
         };
         return {
+            frameClock: renderer.frameClock ?? null,
+            frameNavigation: renderer.frameNavigation ?? null,
+            setDisplay: renderer.setDisplay?.bind(renderer),
             detectionSource: sessionDetections.detectionSource,
             media: sessionMedia.state,
             renderer,