supervision 0.2.7 → 0.2.8

package/dist/index.js

@@ -1,4 +1,4 @@
-import { copySortedDetectionFrames, detectionFrameOverlapsRange, sortedDetectionFrames, projectDetectionFrameForTracking, createSortTracker, createOCSortTracker, createCBIoUTracker, createByteTrackTracker, MediaErrorKind, includeDefined, createDepthColormapLut, parseDepthManifest, validateDepthMap, resolveDepthFrameFile, PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS, decodeCompressedRleMask, decodeCompressedRleCounts, createIdMaskFrame, encodeBinaryMask, rasterizePolygonToMask, resolveIdMaskPaletteId, canReuseMaskStyleArtifacts, getBufferedDetectionTimelineFrameSnapshot, MediaSourceStatus, MediaRendererPlaybackState, MediaRendererFit, createDefaultAnnotationPresentation, createProjectedDetectionFrameSource, createArrayDetectionFrameSource, createBufferedDetectionTimeline, resolveAnnotationRendererPresentation, PlaybackGateReach, createIdleDetectionBufferState, MediaInteractionMode, MAX_ID_MASK_PALETTE_ENTRIES, StrokeAlignment, BaseBoxStyle, centerRectToTopLeftRect, BoxShape, depthPreviewTopCode, resolveDepthColorMapping, resolveDepthQuantity, computeDepthPercentileRange, BaseFocusStyle, extractDetectionMaskRectRuns, AnnotationGestureStateKind, AnnotationHandleKind, getDetectionRect, DetectionPickTarget, createDetectionPickKey, rebaseDetectionPickToFrame, pickDetectionAtPoint, followDetectionPickAcrossFrames, haveSameDetectionPickIdentities, pickAnnotationHandle, getAnnotationHandles, MAX_ID_MASK_STROKE_WIDTH, LabelPlacement, BasePolygonStyle, BasePolylineStyle, BaseKeypointStyle, ShapeInstructionKind, sampleEllipseArc, resolveEllipseSegmentCount, KeypointMarkerShape, MarkerSizeSpace, MarkerShape, resolveMarkerGeometry, BaseInteractionStyle, DetectionInteractionState, writeIdMaskPaletteEntry, resolveIdMaskStrokeTexels, 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';
+import { copySortedDetectionFrames, detectionFrameOverlapsRange, sortedDetectionFrames, projectDetectionFrameForTracking, createSortTracker, createOCSortTracker, createCBIoUTracker, createByteTrackTracker, MediaErrorKind, includeDefined, createDepthColormapLut, parseDepthManifest, validateDepthMap, resolveDepthFrameFile, PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS, decodeCompressedRleMask, decodeCompressedRleCounts, createIdMaskFrame, encodeBinaryMask, rasterizePolygonToMask, resolveIdMaskPaletteId, canReuseMaskStyleArtifacts, getBufferedDetectionTimelineFrameSnapshot, MediaSourceStatus, MediaRendererPlaybackState, MediaRendererFit, createDefaultAnnotationPresentation, createProjectedDetectionFrameSource, createArrayDetectionFrameSource, createBufferedDetectionTimeline, resolveAnnotationRendererPresentation, PlaybackGateReach, createIdleDetectionBufferState, MediaInteractionMode, MAX_ID_MASK_PALETTE_ENTRIES, StrokeAlignment, BaseBoxStyle, centerRectToTopLeftRect, BoxShape, depthPreviewTopCode, resolveDepthColorMapping, resolveDepthQuantity, computeDepthPercentileRange, BaseFocusStyle, extractDetectionMaskRectRuns, AnnotationGestureStateKind, AnnotationHandleKind, getDetectionRect, DetectionPickTarget, rebaseDetectionPickToFrame, pickDetectionAtPoint, createDetectionPickKey, followDetectionPickAcrossFrames, haveSameDetectionPickIdentities, pickAnnotationHandle, getAnnotationHandles, MAX_ID_MASK_STROKE_WIDTH, LabelPlacement, BasePolygonStyle, BasePolylineStyle, BaseKeypointStyle, ShapeInstructionKind, sampleEllipseArc, resolveEllipseSegmentCount, KeypointMarkerShape, MarkerSizeSpace, MarkerShape, resolveMarkerGeometry, BaseInteractionStyle, DetectionInteractionState, writeIdMaskPaletteEntry, resolveIdMaskStrokeTexels, 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, BaseOrientedBoxStyle, BasePercentageBarStyle, BasePolygonStyle, BasePolylineStyle, BoxShape, BoxStrokeAlignment, DEFAULT_DETECTION_CLASS_STYLES, DEFAULT_DETECTION_COLOR_SEQUENCE, DepthColormap, DepthMapKind, DepthPreviewLevels, DepthQuantity, DepthSampling, DetectionBufferStatus, DetectionFrameRetentionMode, DetectionFrameSelectionMode, DetectionInteractionState, DetectionMaskEncoding, DetectionPickTarget, FocusTargetMode, KeypointMarkerShape, KeypointVisibility, LabelPlacement, LabelVisibilityMode, MarkerShape, MarkerSizeSpace, MaskRenderMode, MediaErrorKind, MediaInteractionMode, MediaRendererFit, MediaRendererPlaybackState, MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, MediaSourceStatus, PercentageBarPlacement, PlaybackGateReach, RegionRendererComposeMode, RegionRendererCoverageKind, RegionRendererMediaEffectKind, RegionRendererRegionKind, RegionRendererSizeSpace, RegionRendererSourceKind, SUPERVISION_ROBOFLOW_COLOR, TrackingGeometry, annotationRendererKinds, annotationRenderers, computeDepthPercentileRange, createArrayDetectionFrameSource, createBufferedDetectionTimeline, createByteTrackTracker, createCBIoUTracker, createColdDetectionFrameSource, createCompositeDetectionFrameSource, createDefaultAnnotationPresentation, createMemoryColdDetectionFrameStore, createOCSortTracker, createProjectedDetectionFrameSource, createSortTracker, createWritableDetectionFrameSource, depthColormapColors, detectionPostProcessors, normalizeDetectionClassName, parseDepthManifest, pickDetectionAtPoint, projectDetectionFrame, projectDetectionFrameForTracking, projectDetectionFrames, readDepthAt, resolveDetectionClassColorStyle } from 'supervision-js-core';
 import { c as createMediaFrameClock, M as MediaSourceError, t as toMediaSourceError, r as resolveDisplayPixelRatio } from './video-engine-media-source-DOFsuGS4.js';
 export { a as createWebVideoEngineMediaRendererSource, g as getMediaErrorKind, i as isMediaSourceError, o as openWebVideoEngineMediaSource } from './video-engine-media-source-DOFsuGS4.js';
@@ -10132,6 +10132,9 @@ async function createMediaRendererCore(options, providers) {
             polygonStyle: currentPresentation.polygonStyle,
             polylineStyle: currentPresentation.polylineStyle,
             presentedFrames: protectedPresentedFrames?.source,
+            // A source with no duration, such as a still image, has one frame to
+            // show and nothing to play.
+            stillFrame: metadata.duration === 0,
             regionRenderers: resolveRegionRenderers(currentPresentation),
             heatmapRenderers: resolveHeatmapRenderers(currentPresentation),
             depthRenderers: resolveDepthRenderers(currentPresentation),
@@ -13562,7 +13565,6 @@ function createPixiInteractionLayer(options) {
     let hoveredPick = null;
     let hoveredPickKey = null;
     let selectedPick = null;
-    let selectedPickKey = null;
     let selectedPicks = [];
     let marqueeStart = null;
     let marqueeRect = null;
@@ -13615,9 +13617,19 @@ function createPixiInteractionLayer(options) {
                 setSelectedPick(null);
                 return null;
             }
-            const nextPick = createPickFromSelection(selection);
-            setSelectedPick(nextPick);
-            return nextPick;
+            const nextPicks = selection.detectionIds
+                ? [...new Set(selection.detectionIds)].flatMap((detectionId) => {
+                    const pick = createPickFromSelection({
+                        detectionId,
+                        mediaTime: selection.mediaTime,
+                        point: selection.point,
+                        target: selection.target,
+                    });
+                    return pick ? [pick] : [];
+                })
+                : [createPickFromSelection(selection)].filter((pick) => pick !== null);
+            setSelectedPicks(nextPicks);
+            return nextPicks.at(-1) ?? null;
         },
         getState() {
             return createState();
@@ -13744,6 +13756,18 @@ function createPixiInteractionLayer(options) {
             if (event.button !== undefined && event.button !== 0) {
                 return;
             }
+            if (options.interaction.multiSelect &&
+                event.shiftKey &&
+                pick &&
+                !options.editingEngine.hasCreationTool() &&
+                options.editingEngine.getState().kind ===
+                    AnnotationGestureStateKind.Idle) {
+                // Selection modifiers must run before the editing engine captures a
+                // move. The following pointertap belongs to this same toggle.
+                toggleSelectedPick(pick);
+                suppressNextTap = true;
+                return;
+            }
             // Keep selection owned by this layer. The editing engine deliberately
             // treats a click as a cancelled move, so it cannot establish selection
             // itself; selecting here also makes resize handles available on the next
@@ -13783,7 +13807,7 @@ function createPixiInteractionLayer(options) {
         if (!marqueeStart)
             return;
         if (didDragMarquee && marqueeRect && activeFrame) {
-            selectedPicks = activeFrame.detections.flatMap((detection, detectionIndex) => {
+            const nextPicks = activeFrame.detections.flatMap((detection, detectionIndex) => {
                 if (!canPickDetection(detection))
                     return [];
                 const rect = getDetectionRect(detection);
@@ -13804,10 +13828,7 @@ function createPixiInteractionLayer(options) {
                     },
                 ];
             });
-            selectedPick = selectedPicks.at(-1) ?? null;
-            selectedPickKey = createDetectionPickKey(selectedPick);
-            options.interaction.onSelect?.(selectedPick);
-            options.interaction.onSelectionChange?.(selectedPicks);
+            setSelectedPicks(nextPicks);
         }
         marqueeStart = null;
         marqueeRect = null;
@@ -13903,7 +13924,6 @@ function createPixiInteractionLayer(options) {
         if (nextKeys === currentKeys) {
             return;
         }
-        selectedPickKey = createDetectionPickKey(selectedPick);
         // A followed pick re-bases onto every new frame, so its full pick key
         // changes at playback rate. The scene's normal frame path consumes this
         // refreshed state immediately; emitting onStateChange here would redraw
@@ -13935,15 +13955,17 @@ function createPixiInteractionLayer(options) {
         return true;
     }
     function setSelectedPick(nextPick) {
-        const nextKey = createDetectionPickKey(nextPick);
-        if (nextKey === selectedPickKey) {
-            selectedPick = nextPick;
+        setSelectedPicks(nextPick ? [nextPick] : []);
+    }
+    function setSelectedPicks(nextPicks) {
+        const unchanged = selectedPicks.length === nextPicks.length &&
+            selectedPicks.every((pick, index) => createDetectionPickKey(pick) ===
+                createDetectionPickKey(nextPicks[index]));
+        selectedPicks = nextPicks;
+        selectedPick = nextPicks.at(-1) ?? null;
+        if (unchanged)
             return;
-        }
-        selectedPick = nextPick;
-        selectedPicks = nextPick ? [nextPick] : [];
-        selectedPickKey = nextKey;
-        options.interaction.onSelect?.(nextPick);
+        options.interaction.onSelect?.(selectedPick);
         options.interaction.onSelectionChange?.(selectedPicks);
         notifyStateChange();
     }
@@ -13962,17 +13984,20 @@ function createPixiInteractionLayer(options) {
     function toggleSelectedPick(pick) {
         if (!pick)
             return;
-        const key = createDetectionPickKey(pick);
-        const index = selectedPicks.findIndex((candidate) => createDetectionPickKey(candidate) === key);
-        selectedPicks =
-            index >= 0
-                ? selectedPicks.filter((_, candidateIndex) => candidateIndex !== index)
-                : [...selectedPicks, pick];
-        selectedPick = selectedPicks.at(-1) ?? null;
-        selectedPickKey = createDetectionPickKey(selectedPick);
-        options.interaction.onSelect?.(selectedPick);
-        options.interaction.onSelectionChange?.(selectedPicks);
-        notifyStateChange();
+        const key = createSelectionKey(pick);
+        const index = selectedPicks.findIndex((candidate) => createSelectionKey(candidate) === key);
+        setSelectedPicks(index >= 0
+            ? selectedPicks.filter((_, candidateIndex) => candidateIndex !== index)
+            : [...selectedPicks, pick]);
+    }
+    function createSelectionKey(pick) {
+        // Selection toggles the detection, regardless of whether its body, label,
+        // or keypoint was hit. Keep the picker's frame/index fallback for duplicate ids.
+        return createDetectionPickKey({
+            ...pick,
+            geometryIndex: undefined,
+            target: DetectionPickTarget.Box,
+        });
     }
     function getPoint(event) {
         if (!container)
@@ -17438,6 +17463,13 @@ function createPixiRegionLayer(options) {
             }
             return { activeDetectionIndexes: [...activeDetectionIndexes] };
         },
+        hasAnimatedDisplay() {
+            for (const entry of entries.values()) {
+                if (isAnimatedDisplay(entry.display))
+                    return true;
+            }
+            return false;
+        },
         releaseMaskTexture(texture) {
             if (destroyed)
                 return;
@@ -17760,12 +17792,15 @@ function destroyEntry(entry) {
     // lightweight crop texture; the scene destroys the shared source.
     entry.ownedTexture?.destroy(false);
 }
+function isAnimatedDisplay(display) {
+    return "play" in display && typeof display.play === "function";
+}
 function pauseAnimatedDisplay(display) {
     if ("stop" in display && typeof display.stop === "function")
         display.stop();
 }
 function resumeAnimatedDisplay(display) {
-    if ("play" in display && typeof display.play === "function")
+    if (isAnimatedDisplay(display))
         display.play();
 }
 function matchesTarget(renderer, detection, context) {
@@ -18466,6 +18501,11 @@ function observePixiContainerResize(container, resize) {
  * sample it wants, hands it to `presentSample`, and Pixi's ticker paints the
  * scene every frame.
  *
+ * A still frame is pulled once and then renders on change the way push
+ * presentation does, with the sample it presents as one more change. The
+ * ticker runs only while a looping GIF region or a loading spinner is on the
+ * frame.
+ *
  * Push presentation engages when the opened source carries a presented-frame
  * channel. The producer then decides which frame is on screen and announces it,
  * so the ticker paints nothing and every render is an explicit answer to a
@@ -18496,6 +18536,18 @@ async function createPixiMediaScene(options) {
     let maxTextureSide;
     const maxTextureSize = () => (maxTextureSide ??= queryMaxTextureSize(app.renderer));
     const frameChannel = options.presentedFrames;
+    /**
+     * A still frame has nothing to play, so it renders on change exactly as push
+     * presentation does. The ticker runs only while something on the frame
+     * animates by the clock.
+     */
+    const stillFrame = frameChannel === undefined && options.stillFrame === true;
+    const rendersOnChange = frameChannel !== undefined || stillFrame;
+    let stillFrameTickerRunning = false;
+    /** The content of the `previewOverlay` answer the overlay on screen drew. */
+    let drawnPreviewOverlayContent = null;
+    /** The editing state the overlay on screen was drawn from. */
+    let drawnEditingState;
     let currentFocusStyle = options.focusStyle ?? null;
     let currentLabelStyle = options.labelStyle ?? null;
     let currentMaskStyle = options.maskStyle ?? null;
@@ -18736,7 +18788,7 @@ async function createPixiMediaScene(options) {
         : undefined;
     await app.init({
         autoDensity: true,
-        autoStart: frameChannel === undefined,
+        autoStart: !rendersOnChange,
         backgroundColor: options.backgroundColor ?? 0x111111,
         /* Only the video-engine media path supplies a presented-frame channel, so
          * which reader opens the clip is also what decides which backend draws. */
@@ -18755,7 +18807,10 @@ async function createPixiMediaScene(options) {
     if (!stagingContext) {
         throw new Error("Unable to create staging canvas context.");
     }
-    const renderScheduler = createSceneRenderScheduler(() => app.render());
+    const renderScheduler = createSceneRenderScheduler(() => {
+        app.render();
+        syncStillFrameTicker();
+    });
     const maskBrushPreview = options.maskBrush
         ? createPixiMaskBrushPreview({
             CanvasSource,
@@ -18764,7 +18819,7 @@ async function createPixiMediaScene(options) {
             Sprite,
             Texture,
             preview: options.maskBrush,
-            onInvalidate: frameChannel ? renderNow : undefined,
+            onInvalidate: rendersOnChange ? renderNow : undefined,
         })
         : undefined;
     let appliedPresentation;
@@ -18933,6 +18988,17 @@ async function createPixiMediaScene(options) {
             labelLayer?.drawFrame(currentMediaTime, viewportScale);
             renderNow();
         }
+        // With no ticker to pick it up, an edit the host drives itself, such as a
+        // cancel or a commit, reaches the screen through this notification. A
+        // pointer gesture draws and renders its own state before the microtask
+        // runs, which then finds nothing left to draw or render.
+        if (rendersOnChange) {
+            queueMicrotask(() => {
+                if (isDestroyed || isPresenting)
+                    return;
+                renderOnChange();
+            });
+        }
     });
     const handleKeyDown = (event) => {
         if (event.key === "Tab" && interactionLayer) {
@@ -19122,15 +19188,17 @@ async function createPixiMediaScene(options) {
             renderScene();
     };
     let unsubscribeDetectionTimeline;
-    if (frameChannel) {
-        frameChannel.onPresentedFrame(handlePresentedFrame);
+    if (rendersOnChange) {
         document.addEventListener?.("visibilitychange", handleVisibilityChange);
         // A detection load landing moves what the window covers exactly as a cook
         // landing does. Nothing else brings that to a resting playhead: the layers
         // read the timeline only while drawing, and this is what makes the draw.
         unsubscribeDetectionTimeline = options.detectionTimeline.subscribe?.(handlePreparedWindowChange);
     }
-    else {
+    if (frameChannel) {
+        frameChannel.onPresentedFrame(handlePresentedFrame);
+    }
+    else if (!stillFrame) {
         app.ticker.add(updateMediaSceneFit);
         app.ticker.add(drawAnnotationOverlayNow);
         app.ticker.add(tickFocusLayer);
@@ -19200,7 +19268,9 @@ async function createPixiMediaScene(options) {
         advanceFocus: () => undefined,
         drawAnnotationOverlay: frameChannel
             ? presentLayers.drawAnnotationOverlay
-            : () => undefined,
+            : stillFrame
+                ? (mediaTime) => drawAnnotationOverlay(mediaTime, overlayNow())
+                : () => undefined,
     };
     // A viewport-style redraw covers the layers whose geometry is a function of
     // the viewport scale. Mask outlines reuse the artifact already on screen;
@@ -19250,7 +19320,7 @@ async function createPixiMediaScene(options) {
     };
     return {
         getRenderCount() {
-            return frameChannel ? renderScheduler.getRenderCount() : null;
+            return rendersOnChange ? renderScheduler.getRenderCount() : null;
         },
         getPreparedAnnotationWindow() {
             return frameChannel ? annotationWindow.getSnapshot() : null;
@@ -19363,6 +19433,7 @@ async function createPixiMediaScene(options) {
                     stagingTexture?.update();
                     const { boxState, regionState } = drawFramePresentLayers(annotationDrawLayers, sample.timestamp);
                     updateMediaSceneFit();
+                    renderOnChange();
                     return {
                         ...createPresentedSampleState(sample.timestamp, boxState, regionState),
                         duration: sample.duration,
@@ -19378,6 +19449,7 @@ async function createPixiMediaScene(options) {
                 });
                 const { boxState, regionState } = drawFramePresentLayers(measuredAnnotationDrawLayers, sample.timestamp);
                 const fitMs = measure(updateMediaSceneFit);
+                renderOnChange();
                 return {
                     ...createPresentedSampleState(sample.timestamp, boxState, regionState),
                     duration: sample.duration,
@@ -20256,7 +20328,7 @@ async function createPixiMediaScene(options) {
             return;
         }
         const { boxState, regionState } = drawAnnotationFrame(currentMediaTime);
-        if (frameChannel) {
+        if (rendersOnChange) {
             const signature = describeSceneRender();
             if (forceRender)
                 renderScheduler.render(signature);
@@ -20313,6 +20385,13 @@ async function createPixiMediaScene(options) {
         labelLayer?.drawCreationPreview(editingState?.kind === AnnotationGestureStateKind.Creating
             ? editingState.preview
             : null, mediaTime, viewportScale);
+        const previewOverlay = options.previewOverlay?.() ?? null;
+        drawnEditingState = editingState;
+        // Only a scene that renders on change compares signatures.
+        if (rendersOnChange) {
+            drawnPreviewOverlayContent =
+                describePreviewOverlayContent(previewOverlay);
+        }
         annotationOverlayLayer.draw({
             frame,
             marquee: interactionState?.marqueeRect ?? null,
@@ -20320,7 +20399,7 @@ async function createPixiMediaScene(options) {
             mediaWidth,
             now: overlayNowMs,
             pointer: interactionState?.pointerPoint ?? null,
-            previewOverlay: options.previewOverlay?.() ?? null,
+            previewOverlay,
             selectedDetectionIds: (interactionState?.selectedPicks ?? []).flatMap(({ detection }) => (detection.id === undefined ? [] : [detection.id])),
             viewportScale,
             visibility: currentVisibility,
@@ -20328,8 +20407,9 @@ async function createPixiMediaScene(options) {
     }
     /**
      * Milliseconds for animations that are not annotation geometry. A pull scene
-     * has a ticker and reads the wall clock; a push scene has the presented media
-     * time and nothing else, so its animations move only when the media does.
+     * has a ticker and reads the wall clock, as does a still frame while its
+     * ticker runs; a push scene has the presented media time and nothing else,
+     * so its animations move only when the media does.
      */
     function overlayNow() {
         return frameChannel ? currentMediaTime * MILLISECONDS_PER_SECOND : now();
@@ -20378,8 +20458,21 @@ async function createPixiMediaScene(options) {
         focusLayer.tick(focusAnimationTimeMs);
     }
     function renderScene() {
+        drawOverlayForEditingState();
         renderScheduler.render(describeSceneRender());
     }
+    /**
+     * The render signature names the editing state, so a render must not record
+     * a state the overlay has not drawn: the redraw that follows would match the
+     * recorded signature and be skipped, leaving the old preview on screen.
+     */
+    function drawOverlayForEditingState() {
+        const editingState = options.editingEngine?.getState();
+        if (editingState === undefined || editingState === drawnEditingState) {
+            return;
+        }
+        drawAnnotationOverlay(currentMediaTime, overlayNow());
+    }
     /**
      * Renders a present at most once per display refresh. Frames arrive as
      * messages from the producer's own thread, so a main thread that falls
@@ -20405,15 +20498,46 @@ async function createPixiMediaScene(options) {
         presentFrameNow(deferred);
     }
     function renderNow() {
-        if (frameChannel)
+        if (rendersOnChange)
             renderScene();
     }
     function renderOnChange() {
-        if (!frameChannel)
+        if (!rendersOnChange)
             return;
         settleFocusAnimation();
+        drawOverlayForEditingState();
         renderScheduler.renderOnChange(describeSceneRender());
     }
+    /**
+     * Runs the ticker on a still frame for as long as something on it moves by
+     * the clock: a looping GIF region or a loading spinner. Pixi renders on
+     * every tick it runs, and the overlay redraws so the spinner turns. Each
+     * render checks again, so the ticker stops with the render that removes the
+     * last of them.
+     */
+    function syncStillFrameTicker() {
+        if (!stillFrame || isDestroyed)
+            return;
+        const animating = hasPresentedSample &&
+            (regionLayer.hasAnimatedDisplay() || hasLoadingDetections());
+        if (animating === stillFrameTickerRunning)
+            return;
+        stillFrameTickerRunning = animating;
+        if (animating) {
+            app.ticker.add(drawAnnotationOverlayNow);
+            app.ticker.start();
+        }
+        else {
+            app.ticker.stop();
+            app.ticker.remove(drawAnnotationOverlayNow);
+        }
+    }
+    function hasLoadingDetections() {
+        const loading = currentVisibility?.loadingDetectionIds;
+        if (!loading)
+            return false;
+        return "size" in loading ? loading.size > 0 : loading.length > 0;
+    }
     /**
      * Everything a render would put on screen, as values that can be compared.
      * Styles are opaque resolvers, so they are compared by identity: handing the
@@ -20451,6 +20575,9 @@ async function createPixiMediaScene(options) {
             interactionState?.marqueeRect,
             options.editingEngine?.getState(),
             options.editingEngine ? interactionState?.pointerPoint : null,
+            // The host's preview is read when the overlay draws, and a host may edit
+            // its arrays in place, so its content is what tells a redraw it changed.
+            drawnPreviewOverlayContent,
         ];
     }
     /**
@@ -20789,6 +20916,37 @@ function elapsedSince(start) {
 function now() {
     return globalThis.performance?.now?.() ?? Date.now();
 }
+/**
+ * A key for what a preview overlay draws, hashed from its coordinates rather
+ * than its arrays, so a preview the host edits in place still changes it.
+ * Coordinates count to a 256th of a media pixel, finer than anything drawn.
+ */
+function describePreviewOverlayContent(overlay) {
+    if (!overlay)
+        return null;
+    let hash = 0x811c9dc5;
+    const mix = (value) => {
+        hash = Math.imul(hash ^ value, 0x01000193);
+    };
+    const mixPoint = (point) => {
+        mix(Math.round(point.x * 256));
+        mix(Math.round(point.y * 256));
+    };
+    for (const polygons of [overlay.hoverPolygons, overlay.draftPolygons]) {
+        mix(polygons?.length ?? -1);
+        for (const polygon of polygons ?? []) {
+            mix(polygon.length);
+            for (const point of polygon)
+                mixPoint(point);
+        }
+    }
+    mix(overlay.points?.length ?? -1);
+    for (const point of overlay.points ?? []) {
+        mixPoint(point);
+        mix(point.positive ? 1 : 0);
+    }
+    return hash;
+}
 /**
  * Fills the container and paints the margin around the canvas in the colour the
  * renderer clears to. The scene owns this element so the canvas is positioned