supervision 0.1.7 → 0.2.0-next.0

package/node_modules/supervision-js-core/dist/index.js

@@ -14,6 +14,12 @@ var DetectionBufferStatus;
 (function (DetectionBufferStatus) {
     DetectionBufferStatus["Idle"] = "idle";
     DetectionBufferStatus["Loading"] = "loading";
+    /**
+     * The playback gate is holding playback until the source produces detections
+     * for the requested range. {@link DetectionBufferStatus.Loading} fetches
+     * detections the source already has; this one waits on a producer.
+     */
+    DetectionBufferStatus["AwaitingCoverage"] = "awaitingCoverage";
     DetectionBufferStatus["Ready"] = "ready";
     DetectionBufferStatus["Error"] = "error";
     DetectionBufferStatus["Destroyed"] = "destroyed";
@@ -26,12 +32,30 @@ var DetectionFrameSelectionMode;
     /**
      * Select the frame whose `[mediaTime, endTime)` interval contains the media
      * time. This is the default for interval annotations and timestamped sources.
+     *
+     * Frame times must come from the media itself. Times reconstructed from a
+     * nominal frame rate drift against a clip whose real rate differs, and once
+     * that drift passes the half-millisecond selection tolerance a playhead
+     * landing on a frame boundary selects the previous frame's detections.
+     *
+     * A frame that carries no `endTime` stays active until the next frame starts,
+     * which bridges an index the source never produced.
+     * {@link DetectionFrameSelectionMode.NearestFrameIndex} bounds each frame to
+     * one grid step instead, so a missing index reads as no detections.
      */
     DetectionFrameSelectionMode["Interval"] = "interval";
     /**
-     * Select from a known inference frame grid using `frameIndex`, `frameRate`,
-     * and optional `frameIndexOriginTime`. This is useful when inference was run
-     * on normalized frames and playback should snap detections to that grid.
+     * Select from a known inference frame grid using `frameIndex` and
+     * `frameRate`. This is useful when inference was run on normalized frames and
+     * playback should snap detections to that grid.
+     *
+     * A frame speaks for one grid step starting at its own media time, and an
+     * index the source never produced selects nothing rather than a neighbour.
+     *
+     * A frame carrying no `frameIndex` speaks for its step on the same terms,
+     * reached by the time it starts at rather than by an index that names it. Its
+     * `endTime` does not widen it past that step, so a source that labels only
+     * part of what it writes cannot bridge the indexes it never produced.
      */
     DetectionFrameSelectionMode["NearestFrameIndex"] = "nearestFrameIndex";
 })(DetectionFrameSelectionMode || (DetectionFrameSelectionMode = {}));
@@ -54,15 +78,32 @@ var DetectionFrameRetentionMode;
     DetectionFrameRetentionMode["PersistWindow"] = "persistWindow";
 })(DetectionFrameRetentionMode || (DetectionFrameRetentionMode = {}));
 
+/**
+ * A playhead compared by time can arrive perturbed by whatever plane it crossed
+ * to get here: a producer that publishes whole milliseconds reports a source
+ * frame at 5.033333s as 5.033s, and even an exact producer loses a bit to a
+ * seconds-to-milliseconds-and-back trip. A frame starting within that reach may
+ * already be on screen while one starting past it cannot.
+ *
+ * Selection by identity carries none of this, which is why it lives in its own
+ * function and not in a smaller number here.
+ */
+const PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS = 0.0005;
 function copySortedDetectionFrames(detectionFrames) {
     validateDetectionFrames(detectionFrames ?? []);
     return (detectionFrames ?? [])
-        .map((frame) => ({
+        .map(copyDetectionFrame)
+        .sort((left, right) => left.mediaTime - right.mediaTime);
+}
+/**
+ * One frame's deep copy, for a caller that already knows which frames it is
+ * keeping and only needs the ones it does not hold.
+ */
+function copyDetectionFrame(frame) {
+    return {
         detections: frame.detections.map((detection) => ({
             ...detection,
-            attributes: detection.attributes
-                ? [...detection.attributes]
-                : undefined,
+            attributes: detection.attributes ? [...detection.attributes] : undefined,
             keypoints: detection.keypoints
                 ? {
                     boxRelative: detection.keypoints.boxRelative
@@ -97,16 +138,56 @@ function copySortedDetectionFrames(detectionFrames) {
         endTime: frame.endTime,
         frameIndex: frame.frameIndex,
         mediaTime: frame.mediaTime,
-    }))
-        .sort((left, right) => left.mediaTime - right.mediaTime);
+    };
 }
+/** Returned by the plain copier when it meets a value only structuredClone can
+ *  carry, so the caller pays for that only when the metadata needs it. */
+const NOT_PLAIN = Symbol("not-plain-metadata");
 function copyDetectionMetadata(metadata) {
+    // Detection metadata is almost always a handful of strings and numbers, and a
+    // window rebuild copies it once per detection, tens of thousands of times a
+    // second while scrubbing. structuredClone serialises; walking the object does
+    // not, so it is the fallback rather than the default.
+    const plain = copyPlainMetadata(metadata);
+    if (plain !== NOT_PLAIN) {
+        return plain;
+    }
     const clone = globalThis.structuredClone;
     if (clone) {
         return clone(metadata);
     }
     return copyMetadataValue(metadata);
 }
+function copyPlainMetadata(value) {
+    if (value === null || typeof value !== "object") {
+        return typeof value === "function" || typeof value === "symbol"
+            ? NOT_PLAIN
+            : value;
+    }
+    if (Array.isArray(value)) {
+        const copied = [];
+        for (const entry of value) {
+            const child = copyPlainMetadata(entry);
+            if (child === NOT_PLAIN) {
+                return NOT_PLAIN;
+            }
+            copied.push(child);
+        }
+        return copied;
+    }
+    if (Object.getPrototypeOf(value) !== Object.prototype) {
+        return NOT_PLAIN;
+    }
+    const copied = {};
+    for (const [key, entry] of Object.entries(value)) {
+        const child = copyPlainMetadata(entry);
+        if (child === NOT_PLAIN) {
+            return NOT_PLAIN;
+        }
+        copied[key] = child;
+    }
+    return copied;
+}
 function copyMetadataValue(value) {
     if (Array.isArray(value)) {
         return value.map(copyMetadataValue);
@@ -120,95 +201,85 @@ function copyMetadataValue(value) {
     return value;
 }
 function validateDetectionFrames(detectionFrames) {
-    for (const [frameOffset, frame] of detectionFrames.entries()) {
-        validateNumber(frame.mediaTime, `frames[${frameOffset}].mediaTime`, {
+    for (let frameOffset = 0; frameOffset < detectionFrames.length; frameOffset += 1) {
+        const frame = detectionFrames[frameOffset];
+        const framePath = () => `frames[${frameOffset}]`;
+        validateNumber(frame.mediaTime, () => `${framePath()}.mediaTime`, {
             min: 0,
         });
         if (frame.endTime !== undefined) {
-            validateNumber(frame.endTime, `frames[${frameOffset}].endTime`, {
+            validateNumber(frame.endTime, () => `${framePath()}.endTime`, {
                 exclusiveMin: frame.mediaTime,
             });
         }
         if (frame.frameIndex !== undefined) {
-            validateNumber(frame.frameIndex, `frames[${frameOffset}].frameIndex`, {
+            validateNumber(frame.frameIndex, () => `${framePath()}.frameIndex`, {
                 integer: true,
                 min: 0,
             });
         }
         if (frame.coordinateSpace !== undefined) {
-            validateNumber(frame.coordinateSpace.width, `frames[${frameOffset}].coordinateSpace.width`, { exclusiveMin: 0 });
-            validateNumber(frame.coordinateSpace.height, `frames[${frameOffset}].coordinateSpace.height`, { exclusiveMin: 0 });
+            validateNumber(frame.coordinateSpace.width, () => `${framePath()}.coordinateSpace.width`, { exclusiveMin: 0 });
+            validateNumber(frame.coordinateSpace.height, () => `${framePath()}.coordinateSpace.height`, { exclusiveMin: 0 });
         }
-        for (const [detectionOffset, detection] of frame.detections.entries()) {
-            const detectionPath = `frames[${frameOffset}].detections[${detectionOffset}]`;
+        for (let detectionOffset = 0; detectionOffset < frame.detections.length; detectionOffset += 1) {
+            const detection = frame.detections[detectionOffset];
+            const detectionPath = () => `${framePath()}.detections[${detectionOffset}]`;
             if (detection.confidence !== undefined) {
-                validateNumber(detection.confidence, `${detectionPath}.confidence`, {
-                    max: 1,
-                    min: 0,
-                });
+                validateNumber(detection.confidence, () => `${detectionPath()}.confidence`, { max: 1, min: 0 });
             }
             if (detection.zIndex !== undefined) {
-                validateNumber(detection.zIndex, `${detectionPath}.zIndex`);
+                validateNumber(detection.zIndex, () => `${detectionPath()}.zIndex`);
             }
             if (detection.trackerId !== undefined) {
-                validateNumber(detection.trackerId, `${detectionPath}.trackerId`, {
-                    integer: true,
-                    min: 0,
-                });
+                validateNumber(detection.trackerId, () => `${detectionPath()}.trackerId`, { integer: true, min: 0 });
             }
             if (detection.sourceId !== undefined &&
                 typeof detection.sourceId !== "string") {
-                throw new Error(`${detectionPath}.sourceId must be a string.`);
+                throw new Error(`${detectionPath()}.sourceId must be a string.`);
             }
             if (detection.sourceDetectionIndex !== undefined) {
-                validateNumber(detection.sourceDetectionIndex, `${detectionPath}.sourceDetectionIndex`, {
+                validateNumber(detection.sourceDetectionIndex, () => `${detectionPath()}.sourceDetectionIndex`, {
                     integer: true,
                     min: 0,
                 });
             }
             if (detection.rect) {
-                validateNumber(detection.rect.x, `${detectionPath}.rect.x`);
-                validateNumber(detection.rect.y, `${detectionPath}.rect.y`);
-                validateNumber(detection.rect.width, `${detectionPath}.rect.width`, {
-                    exclusiveMin: 0,
-                });
-                validateNumber(detection.rect.height, `${detectionPath}.rect.height`, {
-                    exclusiveMin: 0,
-                });
+                validateNumber(detection.rect.x, () => `${detectionPath()}.rect.x`);
+                validateNumber(detection.rect.y, () => `${detectionPath()}.rect.y`);
+                validateNumber(detection.rect.width, () => `${detectionPath()}.rect.width`, { exclusiveMin: 0 });
+                validateNumber(detection.rect.height, () => `${detectionPath()}.rect.height`, { exclusiveMin: 0 });
             }
-            validatePoints(detection.polygon?.points, `${detectionPath}.polygon`, 3);
-            validatePoints(detection.polyline?.points, `${detectionPath}.polyline`, 2);
+            validatePoints(detection.polygon?.points, () => `${detectionPath()}.polygon`, 3);
+            validatePoints(detection.polyline?.points, () => `${detectionPath()}.polyline`, 2);
             if (detection.keypoints) {
-                validatePoints(detection.keypoints.points, `${detectionPath}.keypoints`, 1);
+                validatePoints(detection.keypoints.points, () => `${detectionPath()}.keypoints`, 1);
                 if (detection.keypoints.visibility !== undefined &&
                     detection.keypoints.visibility.length !==
                         detection.keypoints.points.length) {
-                    throw new Error(`${detectionPath}.keypoints.visibility must match points length.`);
+                    throw new Error(`${detectionPath()}.keypoints.visibility must match points length.`);
                 }
-                for (const [edgeOffset, edge] of detection.keypoints.edges.entries()) {
-                    const edgePath = `${detectionPath}.keypoints.edges[${edgeOffset}]`;
-                    for (const [endpointOffset, endpoint] of edge.entries()) {
-                        validateNumber(endpoint, `${edgePath}[${endpointOffset}]`, {
+                const edges = detection.keypoints.edges;
+                for (let edgeOffset = 0; edgeOffset < edges.length; edgeOffset += 1) {
+                    const edge = edges[edgeOffset];
+                    const edgePath = () => `${detectionPath()}.keypoints.edges[${edgeOffset}]`;
+                    for (let endpointOffset = 0; endpointOffset < edge.length; endpointOffset += 1) {
+                        const endpoint = edge[endpointOffset];
+                        validateNumber(endpoint, () => `${edgePath()}[${endpointOffset}]`, {
                             integer: true,
                             min: 0,
                         });
                         if (endpoint >= detection.keypoints.points.length) {
-                            throw new Error(`${edgePath}[${endpointOffset}] is out of range.`);
+                            throw new Error(`${edgePath()}[${endpointOffset}] is out of range.`);
                         }
                     }
                 }
             }
             if (detection.mask) {
-                validateNumber(detection.mask.width, `${detectionPath}.mask.width`, {
-                    integer: true,
-                    exclusiveMin: 0,
-                });
-                validateNumber(detection.mask.height, `${detectionPath}.mask.height`, {
-                    integer: true,
-                    exclusiveMin: 0,
-                });
+                validateNumber(detection.mask.width, () => `${detectionPath()}.mask.width`, { integer: true, exclusiveMin: 0 });
+                validateNumber(detection.mask.height, () => `${detectionPath()}.mask.height`, { integer: true, exclusiveMin: 0 });
                 if (detection.mask.counts.length === 0) {
-                    throw new Error(`${detectionPath}.mask.counts must not be empty.`);
+                    throw new Error(`${detectionPath()}.mask.counts must not be empty.`);
                 }
             }
         }
@@ -219,28 +290,30 @@ function validatePoints(points, path, minimumLength) {
         return;
     }
     if (points.length < minimumLength) {
-        throw new Error(`${path}.points must contain at least ${minimumLength} points.`);
+        throw new Error(`${path()}.points must contain at least ${minimumLength} points.`);
     }
-    for (const [pointOffset, point] of points.entries()) {
-        validateNumber(point.x, `${path}.points[${pointOffset}].x`);
-        validateNumber(point.y, `${path}.points[${pointOffset}].y`);
+    for (let pointOffset = 0; pointOffset < points.length; pointOffset += 1) {
+        const point = points[pointOffset];
+        validateNumber(point.x, () => `${path()}.points[${pointOffset}].x`);
+        validateNumber(point.y, () => `${path()}.points[${pointOffset}].y`);
     }
 }
-function validateNumber(value, path, options = {}) {
+const NO_BOUNDS = {};
+function validateNumber(value, path, options = NO_BOUNDS) {
     if (!Number.isFinite(value)) {
-        throw new Error(`${path} must be a finite number.`);
+        throw new Error(`${path()} must be a finite number.`);
     }
     if (options.integer && !Number.isInteger(value)) {
-        throw new Error(`${path} must be an integer.`);
+        throw new Error(`${path()} must be an integer.`);
     }
     if (options.min !== undefined && value < options.min) {
-        throw new Error(`${path} must be greater than or equal to ${options.min}.`);
+        throw new Error(`${path()} must be greater than or equal to ${options.min}.`);
     }
     if (options.exclusiveMin !== undefined && value <= options.exclusiveMin) {
-        throw new Error(`${path} must be greater than ${options.exclusiveMin}.`);
+        throw new Error(`${path()} must be greater than ${options.exclusiveMin}.`);
     }
     if (options.max !== undefined && value > options.max) {
-        throw new Error(`${path} must be less than or equal to ${options.max}.`);
+        throw new Error(`${path()} must be less than or equal to ${options.max}.`);
     }
 }
 function filterDetectionFramesForRange(detectionFrames, startTime, endTime) {
@@ -248,7 +321,7 @@ function filterDetectionFramesForRange(detectionFrames, startTime, endTime) {
 }
 function selectDetectionFrame(detectionFrames, mediaTime, options = {}) {
     if (options.selectionMode === DetectionFrameSelectionMode.NearestFrameIndex) {
-        const selection = selectNearestFrameIndexDetectionFrame(detectionFrames, mediaTime, options.frameRate, options.frameIndexOriginTime);
+        const selection = selectNearestFrameIndexDetectionFrame(detectionFrames, mediaTime, options.frameRate);
         if (selection.isApplicable) {
             return selection.frame;
         }
@@ -285,13 +358,77 @@ function decodeCompressedRleMask(mask) {
     };
 }
 function selectIntervalDetectionFrame(detectionFrames, mediaTime) {
+    const selectedFrame = findLastStartedDetectionFrame(detectionFrames, mediaTime);
+    return selectedFrame && isDetectionFrameActive(selectedFrame, mediaTime)
+        ? selectedFrame
+        : undefined;
+}
+/**
+ * The grid frame a playhead is standing on, or nothing.
+ *
+ * A frame at index `n` speaks for one step of the inference grid and no more,
+ * so it is on screen from its own media time until the next index is due. An
+ * index the source never produced leaves that step blank: the frames on either
+ * side describe media the playhead is not on, and a source still being written
+ * has a playback gate to hold the picture rather than a neighbour to borrow.
+ *
+ * A grid the source labelled only in part is still that source describing this
+ * media, so the frame the playhead stands on is the last one to have started,
+ * whether or not an index names it. The step it is held to is measured from the
+ * labelled frames alone.
+ */
+function selectNearestFrameIndexDetectionFrame(detectionFrames, mediaTime, frameRate) {
+    if (!frameRate || !Number.isFinite(frameRate) || frameRate <= 0) {
+        return { frame: undefined, isApplicable: false };
+    }
+    const firstIndexedFrame = findIndexedDetectionFrame(detectionFrames, 1);
+    const lastIndexedFrame = findIndexedDetectionFrame(detectionFrames, -1);
+    if (!firstIndexedFrame || !lastIndexedFrame) {
+        return { frame: undefined, isApplicable: false };
+    }
+    const gridStep = measureGridStep$1(firstIndexedFrame, lastIndexedFrame) ?? 1 / frameRate;
+    const startedFrame = findLastStartedDetectionFrame(detectionFrames, mediaTime);
+    return {
+        frame: startedFrame &&
+            mediaTime + PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS <
+                startedFrame.mediaTime + gridStep
+            ? startedFrame
+            : undefined,
+        isApplicable: true,
+    };
+}
+/**
+ * A grid step read off the frames instead of taken from `frameRate`.
+ *
+ * `frameRate` is what a manifest or an upload target says the grid is, and a
+ * clip whose real rate differs walks a step further out of position for every
+ * second that plays. The buffered frames carry the times the media itself
+ * reported, and measuring across the widest index span present divides the
+ * producer's millisecond rounding by that span.
+ */
+function measureGridStep$1(firstIndexedFrame, lastIndexedFrame) {
+    const indexSpan = lastIndexedFrame.frameIndex - firstIndexedFrame.frameIndex;
+    const step = (lastIndexedFrame.mediaTime - firstIndexedFrame.mediaTime) / indexSpan;
+    return indexSpan > 0 && Number.isFinite(step) && step > 0 ? step : undefined;
+}
+function findIndexedDetectionFrame(detectionFrames, direction) {
+    const startOffset = direction === 1 ? 0 : detectionFrames.length - 1;
+    for (let offset = startOffset; offset >= 0 && offset < detectionFrames.length; offset += direction) {
+        const frame = detectionFrames[offset];
+        if (isIndexedDetectionFrame(frame)) {
+            return frame;
+        }
+    }
+    return undefined;
+}
+function findLastStartedDetectionFrame(detectionFrames, mediaTime) {
     let selectedFrame;
     let low = 0;
     let high = detectionFrames.length - 1;
     while (low <= high) {
         const middle = Math.floor((low + high) / 2);
         const frame = detectionFrames[middle];
-        if (frame.mediaTime <= mediaTime) {
+        if (hasDetectionFrameStarted(frame, mediaTime)) {
             selectedFrame = frame;
             low = middle + 1;
         }
@@ -299,44 +436,16 @@ function selectIntervalDetectionFrame(detectionFrames, mediaTime) {
             high = middle - 1;
         }
     }
-    return selectedFrame && isDetectionFrameActive(selectedFrame, mediaTime)
-        ? selectedFrame
-        : undefined;
+    return selectedFrame;
 }
-function selectNearestFrameIndexDetectionFrame(detectionFrames, mediaTime, frameRate, frameIndexOriginTime) {
-    if (!frameRate || !Number.isFinite(frameRate) || frameRate <= 0) {
-        return { frame: undefined, isApplicable: false };
-    }
-    const firstIndexedFrame = detectionFrames.find((frame) => frame.frameIndex !== undefined);
-    if (!firstIndexedFrame || firstIndexedFrame.frameIndex === undefined) {
-        return { frame: undefined, isApplicable: false };
-    }
-    const originTime = frameIndexOriginTime !== undefined
-        ? frameIndexOriginTime
-        : firstIndexedFrame.mediaTime - firstIndexedFrame.frameIndex / frameRate;
-    const targetFrameIndex = Math.round((mediaTime - originTime) * frameRate);
-    let nearestFrame;
-    let nearestDistance = Number.POSITIVE_INFINITY;
-    for (const frame of detectionFrames) {
-        if (frame.frameIndex === undefined) {
-            continue;
-        }
-        const distance = Math.abs(frame.frameIndex - targetFrameIndex);
-        if (distance < nearestDistance ||
-            (distance === nearestDistance &&
-                nearestFrame?.frameIndex !== undefined &&
-                frame.frameIndex > nearestFrame.frameIndex)) {
-            nearestFrame = frame;
-            nearestDistance = distance;
-        }
-    }
-    return {
-        frame: nearestDistance <= 1 ? nearestFrame : undefined,
-        isApplicable: true,
-    };
+function isIndexedDetectionFrame(frame) {
+    return frame.frameIndex !== undefined;
+}
+function hasDetectionFrameStarted(frame, mediaTime) {
+    return frame.mediaTime - PLAYHEAD_QUANTIZATION_TOLERANCE_SECONDS <= mediaTime;
 }
 function isDetectionFrameActive(frame, mediaTime) {
-    return (frame.mediaTime <= mediaTime &&
+    return (hasDetectionFrameStarted(frame, mediaTime) &&
         (frame.endTime === undefined || mediaTime < frame.endTime));
 }
 function detectionFrameOverlapsRange(frame, startTime, endTime) {
@@ -398,8 +507,84 @@ function createArrayDetectionFrameSource(frames) {
     };
 }
 
+/**
+ * Slack allowed when comparing two range ends.
+ *
+ * Range bounds are computed from frame times and durations, so an end that
+ * should meet another exactly can miss it by a float's last bits.
+ */
+const RANGE_EPSILON_SECONDS = 1e-6;
+/**
+ * Whether the available ranges together span the whole of `range`.
+ *
+ * Detections arrive a batch at a time, and a source that has not coalesced its
+ * ranges holds several that abut. Asking each range on its own whether it spans
+ * the window reports a window that is entirely covered as uncovered, so the
+ * walk below spends ranges in order and asks how far their union reaches.
+ */
+function isRangeCovered(range, availableRanges) {
+    let reach = null;
+    for (const availableRange of inStartOrder(availableRanges)) {
+        if (reach === null) {
+            if (availableRange.startTime > range.startTime + RANGE_EPSILON_SECONDS) {
+                return false;
+            }
+            if (availableRange.endTime + RANGE_EPSILON_SECONDS < range.startTime) {
+                continue;
+            }
+            reach = availableRange.endTime;
+        }
+        else {
+            if (availableRange.startTime > reach + RANGE_EPSILON_SECONDS) {
+                return false;
+            }
+            reach = Math.max(reach, availableRange.endTime);
+        }
+        if (reach + RANGE_EPSILON_SECONDS >= range.endTime) {
+            return true;
+        }
+    }
+    return false;
+}
+function inStartOrder(ranges) {
+    for (let index = 1; index < ranges.length; index += 1) {
+        if (ranges[index].startTime < ranges[index - 1].startTime) {
+            return [...ranges].sort((left, right) => left.startTime - right.startTime);
+        }
+    }
+    return ranges;
+}
+
+function startWaitBound(timeoutMs) {
+    let handle;
+    const expired = new Promise((resolve) => {
+        handle = setTimeout(() => resolve(false), timeoutMs);
+    });
+    return { cancel: () => clearTimeout(handle), expired };
+}
+
 const DEFAULT_BUFFER_AHEAD_SECONDS = 5;
 const DEFAULT_BUFFER_BEHIND_SECONDS = 0.5;
+/**
+ * Share of the ahead window that must still lead the playhead when the next
+ * window is fetched.
+ *
+ * A window fetched only once the playhead reaches its end leaves the playhead
+ * uncovered for exactly as long as the fetch takes, every time, so annotations
+ * blink out once per window at a steady rate. Fetching while the current window
+ * still answers means the load lands behind a picture that never lost them.
+ */
+const REFILL_LEAD_FRACTION = 0.5;
+const MIN_REFILL_LEAD_SECONDS = 1;
+/**
+ * How long a playback gate holds before it gives up on coverage.
+ *
+ * The gate waits on a producer, and a producer that has failed, stalled, or
+ * fallen far behind is indistinguishable from one that is about to answer. Past
+ * this a frozen picture is the worse of the two outcomes, so the frame is
+ * presented with whatever detections exist.
+ */
+const DEFAULT_PLAYBACK_GATE_MAX_WAIT_SECONDS = 10;
 const bufferedFrameSnapshots = new WeakMap();
 /**
  * Returns the timeline-owned hot-buffer snapshot without copying it.
@@ -417,6 +602,9 @@ function createBufferedDetectionTimeline(options) {
         ? null
         : Math.max(0, options.refreshIntervalSeconds);
     const playbackGate = options.playbackGate;
+    const refillLeadSeconds = bufferAheadSeconds <= 0
+        ? 0
+        : Math.min(bufferAheadSeconds, Math.max(MIN_REFILL_LEAD_SECONDS, bufferAheadSeconds * REFILL_LEAD_FRACTION));
     let buffer = [];
     let state = createIdleDetectionBufferState();
     let destroyed = false;
@@ -429,30 +617,53 @@ function createBufferedDetectionTimeline(options) {
     };
     let inFlight;
     let incrementalRefresh;
+    /** Source version the gate last gave up on, or null while it still waits. */
+    let abandonedGateSourceVersion = null;
     let pendingPrefetch;
     let prefetchPump;
+    const listeners = new Set();
+    const notifyBufferChanged = () => {
+        for (const listener of listeners) {
+            listener();
+        }
+    };
     const getSourceVersion = (ranges) => {
         if (!ranges) {
             return options.source.getVersion?.() ?? 0;
         }
         return ranges.reduce((version, range) => Math.max(version, options.source.getVersion?.(range) ?? 0), 0);
     };
+    const isLoadingEnabled = () => typeof options.enabled === "function"
+        ? options.enabled()
+        : options.enabled !== false;
     const isBufferFresh = () => bufferedVersionRange !== null &&
         bufferedSourceVersion === getSourceVersion(getBufferedSourceRanges());
-    const getLoadRange = (mediaTime) => {
+    const getLoadRange = (mediaTime, lead = "full") => {
         const comparableMediaTime = getComparableMediaTime(mediaTime);
         const startTime = comparableMediaTime - bufferBehindSeconds;
-        const endTime = comparableMediaTime + bufferAheadSeconds;
+        const endTime = comparableMediaTime + (lead === "full" ? bufferAheadSeconds : 0);
         return createLoadPlan(startTime, endTime);
     };
-    const loadWindow = (mediaTime) => {
-        const { endTime, sourceRanges, startTime } = getLoadRange(mediaTime);
+    const loadWindow = (mediaTime, lead = "full") => {
+        const comparableMediaTime = getComparableMediaTime(mediaTime);
+        const { endTime, sourceRanges, startTime } = getLoadRange(mediaTime, lead);
         const versionRange = { endTime, startTime };
         const sourceVersion = getSourceVersion(sourceRanges);
-        if (inFlight &&
-            inFlight.sourceVersion === sourceVersion &&
-            rangeContains(inFlight.startTime, inFlight.endTime, startTime, endTime)) {
-            return inFlight.promise;
+        if (inFlight && inFlight.sourceVersion === sourceVersion) {
+            if (rangeContains(inFlight.startTime, inFlight.endTime, startTime, endTime)) {
+                return inFlight.promise;
+            }
+            // A load already in flight that still covers where the playhead is going
+            // answers the same question a fresh one would. Playback moves the anchor
+            // every frame, so a window superseded on anchor equality alone is
+            // superseded on every frame of its own flight: the fetch is thrown away
+            // and the wait restarts, which is how a gap grows instead of closing.
+            if (refillLeadSeconds > 0 &&
+                comparableMediaTime >= inFlight.mediaTime &&
+                comparableMediaTime + refillLeadSeconds <=
+                    inFlight.mediaTime + bufferAheadSeconds) {
+                return inFlight.promise;
+            }
         }
         const currentLoadId = loadId + 1;
         loadId = currentLoadId;
@@ -469,12 +680,12 @@ function createBufferedDetectionTimeline(options) {
                 return;
             }
             const committedSourceVersion = getSourceVersion(sourceRanges);
-            const loadedBuffer = copySortedDetectionFrames(frameRanges.flat());
+            const loadedFrames = frameRanges.flat();
             buffer =
                 bufferedSourceVersion !== null &&
                     bufferedSourceVersion === committedSourceVersion
-                    ? reuseBufferedFrameSnapshots(buffer, loadedBuffer)
-                    : loadedBuffer;
+                    ? reuseBufferedFrameSnapshots(buffer, loadedFrames)
+                    : copySortedDetectionFrames(loadedFrames);
             bufferedVersionRange = versionRange;
             bufferedSourceVersion = committedSourceVersion;
             state = {
@@ -487,6 +698,7 @@ function createBufferedDetectionTimeline(options) {
                 requestedStartTime: startTime,
                 status: DetectionBufferStatus.Ready,
             };
+            notifyBufferChanged();
         })
             .catch((error) => {
             if (!destroyed && currentLoadId === loadId) {
@@ -503,15 +715,56 @@ function createBufferedDetectionTimeline(options) {
                 inFlight = undefined;
             }
         });
+        if (lead === "covering") {
+            // Chained past the clearing of `inFlight`, which would otherwise be
+            // handed back to the widening load as a window that already answers.
+            void promise
+                .then(() => {
+                if (!destroyed && currentLoadId === loadId) {
+                    void loadWindow(mediaTime).catch(() => undefined);
+                }
+            })
+                .catch(() => undefined);
+        }
         inFlight = {
             endTime,
             id: currentLoadId,
+            mediaTime: comparableMediaTime,
             promise,
             sourceVersion,
             startTime,
         };
         return promise;
     };
+    /**
+     * Restates the window in the lap the playhead is on.
+     *
+     * A window planned near the end of a looping source runs past the loop
+     * point, so once playback wraps, a host comparing the window against the
+     * media clock reads a range that starts after the time it is holding. The
+     * offset removed here is a whole number of laps, which is what
+     * `getComparableMediaTime` already treats as the same position, so
+     * membership and the frames on screen are untouched.
+     */
+    const anchorWindowToPlayhead = (mediaTime) => {
+        const duration = timelineContext.duration;
+        if (!isLoopingTimeline() ||
+            duration === null ||
+            state.bufferStartTime === null ||
+            state.bufferEndTime === null) {
+            return;
+        }
+        const laps = Math.round((getComparableMediaTime(mediaTime) - mediaTime) / duration);
+        if (laps === 0) {
+            return;
+        }
+        state = {
+            ...state,
+            bufferEndTime: state.bufferEndTime - laps * duration,
+            bufferStartTime: state.bufferStartTime - laps * duration,
+        };
+        notifyBufferChanged();
+    };
     const isBuffered = (mediaTime) => {
         const comparableMediaTime = getComparableMediaTime(mediaTime);
         return (isBufferFresh() &&
@@ -528,7 +781,7 @@ function createBufferedDetectionTimeline(options) {
             comparableMediaTime >= state.bufferStartTime &&
             comparableMediaTime <= state.bufferEndTime);
     };
-    const refreshBuffer = async (mediaTime) => {
+    const refreshBuffer = async (mediaTime, lead = "full") => {
         if (isBuffered(mediaTime)) {
             return;
         }
@@ -544,11 +797,18 @@ function createBufferedDetectionTimeline(options) {
             if (isBuffered(mediaTime)) {
                 return;
             }
-            return refreshBuffer(mediaTime);
+            return refreshBuffer(mediaTime, lead);
         }
-        await loadWindow(mediaTime);
+        await loadWindow(mediaTime, lead);
     };
+    /**
+     * Whether the next window is worth fetching while the current one still
+     * answers, so the load lands behind annotations that never went away.
+     */
     const shouldPrefetch = (mediaTime) => {
+        if (!isLoadingEnabled()) {
+            return false;
+        }
         if (!isBuffered(mediaTime)) {
             return true;
         }
@@ -558,12 +818,19 @@ function createBufferedDetectionTimeline(options) {
         if (state.bufferEndTime === null || bufferAheadSeconds <= 0) {
             return false;
         }
-        return (getComparableMediaTime(mediaTime) + bufferAheadSeconds / 2 >=
-            state.bufferEndTime);
+        if (getComparableMediaTime(mediaTime) + bufferAheadSeconds / 2 <
+            state.bufferEndTime) {
+            return false;
+        }
+        const { endTime, startTime } = getLoadRange(mediaTime);
+        // A window already spanning everything the source can offer has nowhere to
+        // advance to, so its lead only shrinks from here. Refetching it would
+        // repeat for every remaining frame of playback and buy no coverage.
+        return (startTime !== state.bufferStartTime || endTime !== state.bufferEndTime);
     };
     const timeline = {
         async prepare(mediaTime, prepareOptions) {
-            if (destroyed) {
+            if (destroyed || !isLoadingEnabled()) {
                 return;
             }
             if (shouldWaitForPlaybackGate(prepareOptions)) {
@@ -573,9 +840,26 @@ function createBufferedDetectionTimeline(options) {
                 }
             }
             await refreshBuffer(mediaTime);
+            anchorWindowToPlayhead(mediaTime);
+        },
+        needsPlaybackGateWait(mediaTime, prepareOptions) {
+            if (destroyed ||
+                !isLoadingEnabled() ||
+                !playbackGate?.enabled ||
+                !options.source.waitForRange ||
+                !options.source.getAvailableRanges ||
+                hasAbandonedGate()) {
+                return false;
+            }
+            const availableRanges = options.source.getAvailableRanges();
+            return !createPlaybackGateCoveragePlan(mediaTime, prepareOptions).sourceRanges.every((range) => isRangeCovered(range, availableRanges));
         },
         prefetch(mediaTime) {
-            if (destroyed || !shouldPrefetch(mediaTime)) {
+            if (destroyed || !isLoadingEnabled()) {
+                return;
+            }
+            anchorWindowToPlayhead(mediaTime);
+            if (!shouldPrefetch(mediaTime)) {
                 return;
             }
             pendingPrefetch = { loadId, mediaTime };
@@ -598,11 +882,18 @@ function createBufferedDetectionTimeline(options) {
         getState() {
             return { ...state };
         },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
         destroy() {
             if (destroyed) {
                 return;
             }
             destroyed = true;
+            listeners.clear();
             pendingPrefetch = undefined;
             buffer = [];
             bufferedSourceVersion = null;
@@ -646,9 +937,16 @@ function createBufferedDetectionTimeline(options) {
             if (!shouldPrefetch(mediaTime)) {
                 continue;
             }
-            await (shouldRefreshRollingWindow(mediaTime)
-                ? loadWindow(mediaTime)
-                : refreshBuffer(mediaTime)).catch(() => undefined);
+            // A playhead the window does not reach is a jump rather than the window
+            // rolling forward, and the frame under it is the one thing the picture
+            // cannot draw without. A window that still spans it, however stale, is
+            // missing no such frame.
+            const lead = isInsideBufferedRange(mediaTime)
+                ? "full"
+                : "covering";
+            await (isBuffered(mediaTime) || shouldRefreshRollingWindow(mediaTime)
+                ? loadWindow(mediaTime, lead)
+                : refreshBuffer(mediaTime, lead)).catch(() => undefined);
         }
     }
     async function applyIncrementalChanges() {
@@ -690,6 +988,7 @@ function createBufferedDetectionTimeline(options) {
                 frameCount: buffer.length,
                 status: DetectionBufferStatus.Ready,
             };
+            notifyBufferChanged();
         }
         catch (error) {
             if (!destroyed) {
@@ -707,31 +1006,44 @@ function createBufferedDetectionTimeline(options) {
             playbackGate?.enabled === true &&
             Boolean(options.source.waitForRange));
     }
-    async function waitForPlaybackGate(mediaTime, prepareOptions) {
-        if (!playbackGate?.enabled || !options.source.waitForRange) {
-            return;
-        }
-        const requiredAheadSeconds = Math.max(0, playbackGate.requiredAheadSeconds ?? 0);
+    function createPlaybackGateCoveragePlan(mediaTime, prepareOptions) {
+        const requiredAheadSeconds = Math.max(0, playbackGate?.requiredAheadSeconds ?? 0);
         const comparableMediaTime = getComparableMediaTime(mediaTime);
         const endTime = getRequiredCoverageEndTime({
+            // A looping window counts past the end of media and wraps into the
+            // replay, so clamping it to duration would ask for less than it needs.
             duration: isLoopingTimeline() ? null : prepareOptions?.duration,
             firstTimestamp: prepareOptions?.firstTimestamp,
             mediaTime: comparableMediaTime,
             requiredAheadSeconds,
         });
-        if (endTime <= comparableMediaTime) {
+        // A lead clamped away at the end of media, or asked for as zero, still
+        // leaves the frame under the playhead to wait for.
+        return createLoadPlan(comparableMediaTime, Math.max(comparableMediaTime, endTime));
+    }
+    function hasAbandonedGate() {
+        return (abandonedGateSourceVersion !== null &&
+            getSourceVersion() <= abandonedGateSourceVersion);
+    }
+    async function waitForPlaybackGate(mediaTime, prepareOptions) {
+        if (!playbackGate?.enabled || !options.source.waitForRange) {
+            return;
+        }
+        if (hasAbandonedGate()) {
             return;
         }
-        const coveragePlan = createLoadPlan(comparableMediaTime, endTime);
+        const coveragePlan = createPlaybackGateCoveragePlan(mediaTime, prepareOptions);
         state = {
             ...state,
             errorMessage: null,
             requestedEndTime: coveragePlan.endTime,
             requestedStartTime: coveragePlan.startTime,
-            status: DetectionBufferStatus.Loading,
+            status: DetectionBufferStatus.AwaitingCoverage,
         };
         try {
-            await Promise.all(coveragePlan.sourceRanges.map((range) => options.source.waitForRange?.(range)));
+            const covered = await waitForSourceCoverage(coveragePlan.sourceRanges, Math.max(0, playbackGate.maxWaitSeconds ?? DEFAULT_PLAYBACK_GATE_MAX_WAIT_SECONDS));
+            abandonedGateSourceVersion =
+                covered || !options.source.getVersion ? null : getSourceVersion();
         }
         catch (error) {
             if (!destroyed) {
@@ -744,6 +1056,33 @@ function createBufferedDetectionTimeline(options) {
             throw error;
         }
     }
+    /**
+     * Resolves true once the source covers every range, false once the wait has
+     * run longer than `maxWaitSeconds`.
+     */
+    async function waitForSourceCoverage(sourceRanges, maxWaitSeconds) {
+        const covered = whenRangesCovered(sourceRanges);
+        if (!Number.isFinite(maxWaitSeconds)) {
+            return covered;
+        }
+        const bound = startWaitBound(maxWaitSeconds * 1000);
+        try {
+            const result = await Promise.race([covered, bound.expired]);
+            if (!result) {
+                // The abandoned wait outlives this call, and a rejection it reaches
+                // afterwards has nobody left to hand it to.
+                void covered.catch(() => undefined);
+            }
+            return result;
+        }
+        finally {
+            bound.cancel();
+        }
+    }
+    async function whenRangesCovered(sourceRanges) {
+        await Promise.all(sourceRanges.map((range) => options.source.waitForRange?.(range)));
+        return true;
+    }
     function shouldRefreshRollingWindow(mediaTime) {
         if (refreshIntervalSeconds === null ||
             refreshIntervalSeconds <= 0 ||
@@ -752,8 +1091,24 @@ function createBufferedDetectionTimeline(options) {
             return false;
         }
         const { endTime, startTime } = getLoadRange(mediaTime);
-        return (Math.abs(startTime - state.bufferStartTime) >= refreshIntervalSeconds ||
-            Math.abs(endTime - state.bufferEndTime) >= refreshIntervalSeconds);
+        return (getWindowDrift(startTime, state.bufferStartTime) >=
+            refreshIntervalSeconds ||
+            getWindowDrift(endTime, state.bufferEndTime) >= refreshIntervalSeconds);
+    }
+    /**
+     * How far a planned edge sits from the window's, counted the short way around
+     * a looping timeline. A plan is stated on the first lap and the window on the
+     * playhead's, so across the loop point the two state the same edge a whole lap
+     * apart; measured straight, that reads as a window a full lap stale and
+     * rebuilds it on every frame until the plan stops reaching behind zero.
+     */
+    function getWindowDrift(planTime, bufferTime) {
+        const drift = Math.abs(planTime - bufferTime);
+        if (!isLoopingTimeline() || timelineContext.duration === null) {
+            return drift;
+        }
+        const wrappedDrift = modulo(drift, timelineContext.duration);
+        return Math.min(wrappedDrift, timelineContext.duration - wrappedDrift);
     }
     function createLoadPlan(requestedStartTime, requestedEndTime) {
         const startTime = Math.min(requestedStartTime, requestedEndTime);
@@ -780,10 +1135,15 @@ function createBufferedDetectionTimeline(options) {
                 startTime: 0,
             };
         }
+        // Both ends move by the same whole number of laps, so the window keeps its
+        // span and its source ranges while its start reads on the media clock: a
+        // window counted in the laps playback accumulated is one no host can hold
+        // against a current time.
+        const laps = Math.floor(startTime / duration);
         return {
-            endTime,
+            endTime: endTime - laps * duration,
             sourceRanges: getLoopingSourceRanges(startTime, endTime, duration),
-            startTime,
+            startTime: startTime - laps * duration,
         };
     }
     function getBufferedSourceRanges() {
@@ -805,14 +1165,13 @@ function createBufferedDetectionTimeline(options) {
             return mediaTime;
         }
         const duration = timelineContext.duration;
-        let comparableMediaTime = mediaTime;
-        while (comparableMediaTime < state.bufferStartTime) {
-            comparableMediaTime += duration;
-        }
-        while (comparableMediaTime > state.bufferEndTime) {
-            comparableMediaTime -= duration;
-        }
-        return comparableMediaTime;
+        // The representative of mediaTime (mod duration) anchored at the window
+        // start. The mapping must depend only on where the window sits, never on
+        // how many laps playback has accumulated, or membership drifts away from
+        // what the buffer actually holds. A time less than one lap past the
+        // anchor never wraps, so ordinary forward playback cannot ratchet.
+        return (state.bufferStartTime +
+            modulo(mediaTime - state.bufferStartTime, duration));
     }
     function getSourceMediaTime(mediaTime) {
         if (!isLoopingTimeline() || timelineContext.duration === null) {
@@ -900,9 +1259,19 @@ function mergeIncrementalFrames(currentFrames, changedFrames, changedRanges) {
     }
     return Array.from(framesByIdentity.values()).sort(compareDetectionFrames$1);
 }
+/**
+ * Keeps the frame already held wherever the source returned one this buffer
+ * knows, and copies only what is new. Copying everything first and then
+ * discarding it is the same result for a great deal more work: a window rebuilt
+ * while a gesture moves inside it re-derives hundreds of frames it already has.
+ */
 function reuseBufferedFrameSnapshots(currentFrames, loadedFrames) {
+    validateDetectionFrames(loadedFrames);
     const currentFramesByIdentity = new Map(currentFrames.map((frame) => [getDetectionFrameIdentity(frame), frame]));
-    return loadedFrames.map((frame) => currentFramesByIdentity.get(getDetectionFrameIdentity(frame)) ?? frame);
+    return loadedFrames
+        .map((frame) => currentFramesByIdentity.get(getDetectionFrameIdentity(frame)) ??
+        copyDetectionFrame(frame))
+        .sort(compareDetectionFrames$1);
 }
 function getDetectionFrameIdentity(frame) {
     return frame.frameIndex === undefined
@@ -1043,7 +1412,7 @@ function createCompositeDetectionFrameSource(options) {
         },
         async waitForRange(range) {
             await Promise.all(sources
-                .filter((source) => source.requiredForPlayback)
+                .filter((source) => source.requiredForCoverage)
                 .map((source) => source.source.waitForRange?.(range)));
         },
         getAvailableRanges() {
@@ -1078,7 +1447,7 @@ function normalizeCompositeSources(entries) {
             declarationIndex,
             id: entry.id,
             order: entry.order ?? 0,
-            requiredForPlayback: entry.requiredForPlayback !== false,
+            requiredForCoverage: entry.requiredForCoverage !== false,
             source: entry.source ?? createArrayDetectionFrameSource(entry.frames ?? []),
             sync: entry.sync,
         };
@@ -1108,47 +1477,181 @@ function composeIntervalFrames(sources, startTime, endTime, options, coordinateS
         }
         const nextBoundaryTime = sortedBoundaryTimes[boundaryIndex + 1] ?? endTime;
         const endTimeForFrame = Math.min(nextBoundaryTime, endTime);
-        const frame = composeFrameAtTime(sources, mediaTime, endTimeForFrame, { ...options, selectionMode: DetectionFrameSelectionMode.Interval }, undefined, coordinateSpace);
+        const frame = composeFrameAtTime(sources, mediaTime, endTimeForFrame, { ...options, selectionMode: DetectionFrameSelectionMode.Interval }, coordinateSpace);
         if (frame) {
             frames.push(frame);
         }
     }
     return frames;
 }
+/**
+ * One composed frame per inference grid index the children wrote, and one per
+ * child frame that carries no index.
+ *
+ * Children are paired on the index their producer labelled, and the composed
+ * frame keeps the media time they reported for it. `frameRate` states the grid
+ * a producer was asked for, not the one the clip plays at, and a slower clip
+ * answers consecutive indexes with the same decoded sample: a timeline placed
+ * by that rate then asks for a time two indexes share, which can only ever
+ * reach one of them and leaves the other's detections stranded. Pairing on the
+ * index reaches every one and keeps each frame's detections on the frame they
+ * were computed for.
+ *
+ * A frame carrying no index has no grid position to be paired on, so it
+ * composes at its own media time, and every child answers there with whatever
+ * it has standing. That is how a child sitting on a grid index keeps its
+ * detections on screen while an unindexed frame from another child overlaps it.
+ * The composed frame carries no index of its own, because only part of what it
+ * holds sits on the grid.
+ */
 function composeNearestFrameIndexFrames(sources, startTime, endTime, options, coordinateSpace) {
     const frameRate = options.frameRate;
     if (!frameRate || !Number.isFinite(frameRate) || frameRate <= 0) {
         return null;
     }
-    const indexedFrames = sources.flatMap((source) => source.frames.filter((frame) => frame.frameIndex !== undefined));
-    const firstIndexedFrame = indexedFrames[0];
-    if (!firstIndexedFrame || firstIndexedFrame.frameIndex === undefined) {
+    const gridSources = sources.map((source) => ({
+        ...source,
+        framesByIndex: indexFramesByFrameIndex(source, options),
+    }));
+    const indexedSlots = mergeGridSlots(gridSources);
+    if (indexedSlots.length === 0) {
         return null;
     }
-    const originTime = options.frameIndexOriginTime ??
-        firstIndexedFrame.mediaTime - firstIndexedFrame.frameIndex / frameRate;
-    const frameIndexes = [
-        ...new Set(indexedFrames
-            .map((frame) => frame.frameIndex)
-            .filter((frameIndex) => frameIndex !== undefined)),
-    ].sort((left, right) => left - right);
+    const gridStep = measureGridStep(indexedSlots) ?? 1 / frameRate;
+    const slots = [
+        ...indexedSlots,
+        ...mergeUnindexedGridSlots(gridSources, indexedSlots),
+    ];
     const frames = [];
-    for (const frameIndex of frameIndexes) {
-        const mediaTime = originTime + frameIndex / frameRate;
-        if (mediaTime < startTime || mediaTime >= endTime) {
+    for (const slot of slots) {
+        if (slot.mediaTime < startTime || slot.mediaTime >= endTime) {
             continue;
         }
-        const frame = composeFrameAtTime(sources, mediaTime, Math.min(mediaTime + 1 / frameRate, endTime), {
+        const frame = composeFrameAtGridSlot(gridSources, slot, Math.min(slot.mediaTime + gridStep, endTime), {
             ...options,
             selectionMode: DetectionFrameSelectionMode.NearestFrameIndex,
-        }, frameIndex, coordinateSpace);
+        }, coordinateSpace);
         if (frame) {
             frames.push(frame);
         }
     }
-    return frames;
+    return frames.sort((left, right) => left.mediaTime - right.mediaTime);
+}
+function indexFramesByFrameIndex(source, options) {
+    const framesByIndex = new Map();
+    const selectionMode = source.sync?.selectionMode ?? options.selectionMode;
+    if (selectionMode !== DetectionFrameSelectionMode.NearestFrameIndex) {
+        return framesByIndex;
+    }
+    for (const frame of source.frames) {
+        if (frame.frameIndex !== undefined) {
+            framesByIndex.set(frame.frameIndex, frame);
+        }
+    }
+    return framesByIndex;
+}
+/**
+ * Where each grid index sits in the media, taken as the earliest time any child
+ * reported for it. Children on one grid watched the same source frame, and the
+ * earliest of their answers is where that frame starts.
+ */
+function mergeGridSlots(sources) {
+    const mediaTimes = new Map();
+    for (const source of sources) {
+        for (const [frameIndex, frame] of source.framesByIndex) {
+            const mediaTime = mediaTimes.get(frameIndex);
+            if (mediaTime === undefined || frame.mediaTime < mediaTime) {
+                mediaTimes.set(frameIndex, frame.mediaTime);
+            }
+        }
+    }
+    return [...mediaTimes]
+        .map(([frameIndex, mediaTime]) => ({ frameIndex, mediaTime }))
+        .sort((left, right) => left.frameIndex - right.frameIndex);
+}
+/**
+ * Where a frame no producer labelled sits: at the media time it reported, which
+ * is the only handle it has.
+ */
+function mergeUnindexedGridSlots(sources, indexedSlots) {
+    const indexedSlotTimes = new Set(indexedSlots.map((slot) => slot.mediaTime));
+    const mediaTimes = new Set();
+    for (const source of sources) {
+        for (const frame of source.frames) {
+            if (frame.frameIndex === undefined &&
+                !indexedSlotTimes.has(frame.mediaTime)) {
+                mediaTimes.add(frame.mediaTime);
+            }
+        }
+    }
+    return [...mediaTimes]
+        .sort((left, right) => left - right)
+        .map((mediaTime) => ({ mediaTime }));
+}
+/**
+ * How long one grid index stands, read off the slots across the widest index
+ * span they cover. A clip whose real rate differs from `frameRate` would end
+ * every composed frame a little short or a little long of where the next index
+ * is due, and that error accumulates for as long as the clip plays.
+ */
+function measureGridStep(gridSlots) {
+    const firstSlot = gridSlots[0];
+    const lastSlot = gridSlots[gridSlots.length - 1];
+    const indexSpan = lastSlot.frameIndex - firstSlot.frameIndex;
+    const step = (lastSlot.mediaTime - firstSlot.mediaTime) / indexSpan;
+    return indexSpan > 0 && Number.isFinite(step) && step > 0 ? step : undefined;
+}
+function composeFrameAtGridSlot(sources, slot, endTime, options, coordinateSpace) {
+    const detections = [];
+    for (const source of sources) {
+        const activeFrame = selectGridSlotFrame(source, slot, options);
+        if (!activeFrame) {
+            continue;
+        }
+        activeFrame.detections.forEach((detection, sourceDetectionIndex) => {
+            detections.push(copyDetectionWithSource(detection, source.id, sourceDetectionIndex));
+        });
+    }
+    if (detections.length === 0) {
+        return undefined;
+    }
+    return {
+        detections,
+        endTime,
+        frameIndex: slot.frameIndex,
+        mediaTime: slot.mediaTime,
+        // Children were projected before composition, so a composed frame is
+        // already in the coordinate space the renderer presents.
+        ...(coordinateSpace ? { coordinateSpace } : {}),
+    };
+}
+/**
+ * What one child has to say at a slot.
+ *
+ * A child that wrote this index answers with the frame it wrote for it, however
+ * far its own media time sits from the slot's. A child on the grid that never
+ * wrote this index answers only with a frame of its own that carries no index
+ * and is standing here: its neighbouring indexes describe media the slot is not
+ * on, and lending one of those would put those detections on a frame they were
+ * not computed for.
+ */
+function selectGridSlotFrame(source, slot, options) {
+    const pairedFrame = slot.frameIndex === undefined
+        ? undefined
+        : source.framesByIndex.get(slot.frameIndex);
+    if (pairedFrame) {
+        return pairedFrame;
+    }
+    const selectedFrame = selectDetectionFrame(source.frames, slot.mediaTime, {
+        ...options,
+        ...source.sync,
+    });
+    const isGridChildAtIndexedSlot = source.framesByIndex.size > 0 && slot.frameIndex !== undefined;
+    return isGridChildAtIndexedSlot && selectedFrame?.frameIndex !== undefined
+        ? undefined
+        : selectedFrame;
 }
-function composeFrameAtTime(sources, mediaTime, endTime, options, frameIndex, coordinateSpace) {
+function composeFrameAtTime(sources, mediaTime, endTime, options, coordinateSpace) {
     const detections = [];
     const activeFrameIndexes = [];
     for (const source of sources) {
@@ -1172,7 +1675,7 @@ function composeFrameAtTime(sources, mediaTime, endTime, options, frameIndex, co
     return {
         detections,
         endTime,
-        frameIndex: frameIndex ?? resolveComposedFrameIndex(activeFrameIndexes) ?? undefined,
+        frameIndex: resolveComposedFrameIndex(activeFrameIndexes) ?? undefined,
         mediaTime,
         // Children were projected before composition, so a composed frame is
         // already in the coordinate space the renderer presents.
@@ -1645,7 +2148,6 @@ function createProjectedDetectionFrameSource(source, resolveTarget) {
     };
 }
 
-const RANGE_EPSILON_SECONDS = 1e-6;
 const MAX_CHANGED_RANGE_JOURNAL_LENGTH = 512;
 const DEFAULT_LIVE_HOLD_SECONDS = 60;
 const NO_COVERAGE_INVALIDATION = { ranges: [] };
@@ -1786,8 +2288,8 @@ function createWritableDetectionFrameSource(options) {
                 // earlier, though, so report it rather than assume.
                 invalidation);
                 // Closing a held live frame shortens coverage. Reported availability
-                // has to shrink with it, or a playback gate would still believe the
-                // source covers time past the end of media.
+                // has to shrink with it, or `waitForRange` and the buffered window
+                // would still believe the source covers time past the end of media.
                 clipAvailableRangesAfter(endTime);
                 return finalSummary;
             });
@@ -2252,10 +2754,6 @@ function recordAvailableRange(range, availableRanges) {
     }
     availableRanges.length = writeIndex;
 }
-function isRangeCovered(range, availableRanges) {
-    return availableRanges.some((availableRange) => availableRange.startTime <= range.startTime + RANGE_EPSILON_SECONDS &&
-        availableRange.endTime + RANGE_EPSILON_SECONDS >= range.endTime);
-}
 
 /**
  * Creates one stateful SORT tracker for a single ordered media sequence.
@@ -3587,53 +4085,230 @@ function extractMaskContour(data, width, height) {
 }
 function extractMaskRectRuns(data, width, height) {
     assertMaskDimensions(data, width, height);
+    const rects = mergeRowSpansIntoRects(data, width, height, 0, 0);
+    return rects.length > 0 ? rects : undefined;
+}
+/**
+ * The rect runs of a compressed-RLE mask, without holding the mask's raster.
+ *
+ * A mask is the size of the whole frame, so reading a silhouette that covers a
+ * fraction of one percent of it otherwise costs a megabytes-wide allocation and
+ * a pass over every pixel. The counts carry the occupied box, so the raster and
+ * the pass are that box.
+ */
+function extractDetectionMaskRectRuns(mask) {
+    if (mask.encoding !== DetectionMaskEncoding.CompressedRle) {
+        throw new Error(`Unsupported detection mask encoding: ${mask.encoding}`);
+    }
+    const { height, width } = mask;
+    assertMaskSize(width, height);
+    const counts = decodeCompressedRleCounts(mask.counts);
+    const bounds = computeCompressedRleBounds(counts, width, height);
+    if (!bounds) {
+        return undefined;
+    }
+    const { left, top } = bounds;
+    const boundsWidth = bounds.width;
+    const boundsHeight = bounds.height;
+    const boundsBuffer = new Uint8Array(boundsWidth * boundsHeight);
+    const pixels = width * height;
+    let offset = 0;
+    for (let index = 0; index < counts.length; index += 1) {
+        const start = offset;
+        offset += counts[index] ?? 0;
+        if (!isForegroundRun(index) || start >= pixels) {
+            continue;
+        }
+        const end = Math.min(offset, pixels);
+        let cursor = start;
+        while (cursor < end) {
+            const column = Math.floor(cursor / height);
+            const columnEnd = Math.min(end, (column + 1) * height);
+            let target = (cursor - column * height - top) * boundsWidth + (column - left);
+            for (let step = columnEnd - cursor; step > 0; step -= 1) {
+                boundsBuffer[target] = 1;
+                target += boundsWidth;
+            }
+            cursor = columnEnd;
+        }
+    }
+    const rects = mergeRowSpansIntoRects(boundsBuffer, boundsWidth, boundsHeight, left, top);
+    return rects.length > 0 ? rects : undefined;
+}
+/** Counts alternate background, foreground, starting on background. */
+function isForegroundRun(index) {
+    return index % 2 === 1;
+}
+/**
+ * The occupied box of a compressed-RLE mask, read from the counts alone.
+ *
+ * COCO runs are column-major, so a run confined to one column bounds its own
+ * rows, and a run that reaches the next column has already spanned a full
+ * column top to bottom.
+ */
+function computeCompressedRleBounds(counts, width, height) {
+    const pixels = width * height;
+    let left = width;
+    let top = height;
+    let right = -1;
+    let bottom = -1;
+    let offset = 0;
+    for (let index = 0; index < counts.length; index += 1) {
+        const start = offset;
+        offset += counts[index] ?? 0;
+        if (!isForegroundRun(index) || start >= pixels) {
+            continue;
+        }
+        const end = Math.min(offset, pixels) - 1;
+        const startColumn = Math.floor(start / height);
+        const endColumn = Math.floor(end / height);
+        if (startColumn < left) {
+            left = startColumn;
+        }
+        if (endColumn > right) {
+            right = endColumn;
+        }
+        if (startColumn !== endColumn) {
+            top = 0;
+            bottom = height - 1;
+            continue;
+        }
+        const startRow = start - startColumn * height;
+        const endRow = end - endColumn * height;
+        if (startRow < top) {
+            top = startRow;
+        }
+        if (endRow > bottom) {
+            bottom = endRow;
+        }
+    }
+    return right < 0
+        ? null
+        : {
+            height: bottom - top + 1,
+            left,
+            top,
+            width: right - left + 1,
+        };
+}
+function createOpenMaskSpans(capacity) {
+    return {
+        openedAt: new Int32Array(capacity),
+        runWidth: new Int32Array(capacity),
+        startX: new Int32Array(capacity),
+        topY: new Int32Array(capacity),
+    };
+}
+/**
+ * Emits rects in the coordinates of the raster the given window was cut from,
+ * not the window's own.
+ *
+ * A span continues the rect above it when its start and width both match, and
+ * the row above holds exactly one open rect per span, so walking both in
+ * ascending x pairs them without a lookup.
+ */
+function mergeRowSpansIntoRects(data, width, height, offsetX, offsetY) {
     const rects = [];
-    const openRects = new Map();
+    // Spans need a gap between them, so a row holds at most half its width.
+    const capacity = (width >> 1) + 2;
+    const closed = new Int32Array(capacity);
+    let open = createOpenMaskSpans(capacity);
+    let next = createOpenMaskSpans(capacity);
+    let openCount = 0;
+    let opened = 0;
     for (let y = 0; y < height; y += 1) {
-        const activeSpans = new Set();
+        const row = y * width;
+        let nextCount = 0;
+        let closedCount = 0;
+        let cursor = 0;
         let x = 0;
         while (x < width) {
-            while (x < width && !data[y * width + x]) {
+            while (x < width && data[row + x] === 0) {
                 x += 1;
             }
             if (x >= width) {
                 break;
             }
             const startX = x;
-            while (x < width && data[y * width + x]) {
+            while (x < width && data[row + x] !== 0) {
                 x += 1;
             }
             const runWidth = x - startX;
-            const key = `${startX}:${runWidth}`;
-            const openRect = openRects.get(key);
-            activeSpans.add(key);
-            if (openRect && openRect.y + openRect.height === y) {
-                openRects.set(key, { ...openRect, height: openRect.height + 1 });
+            while (cursor < openCount && open.startX[cursor] < startX) {
+                closed[closedCount] = cursor;
+                closedCount += 1;
+                cursor += 1;
+            }
+            if (cursor < openCount &&
+                open.startX[cursor] === startX &&
+                open.runWidth[cursor] === runWidth) {
+                next.openedAt[nextCount] = open.openedAt[cursor];
+                next.topY[nextCount] = open.topY[cursor];
+                cursor += 1;
             }
             else {
-                if (openRect) {
-                    rects.push(openRect);
+                if (cursor < openCount && open.startX[cursor] === startX) {
+                    closed[closedCount] = cursor;
+                    closedCount += 1;
+                    cursor += 1;
                 }
-                openRects.set(key, { height: 1, width: runWidth, x: startX, y });
+                next.openedAt[nextCount] = opened;
+                next.topY[nextCount] = y;
+                opened += 1;
             }
-        }
-        for (const [key, openRect] of openRects) {
-            if (!activeSpans.has(key)) {
-                rects.push(openRect);
-                openRects.delete(key);
-            }
-        }
+            next.runWidth[nextCount] = runWidth;
+            next.startX[nextCount] = startX;
+            nextCount += 1;
+        }
+        while (cursor < openCount) {
+            closed[closedCount] = cursor;
+            closedCount += 1;
+            cursor += 1;
+        }
+        pushClosedRects(rects, open, closed, closedCount, y, offsetX, offsetY);
+        const carried = open;
+        open = next;
+        next = carried;
+        openCount = nextCount;
+    }
+    for (let index = 0; index < openCount; index += 1) {
+        closed[index] = index;
+    }
+    pushClosedRects(rects, open, closed, openCount, height, offsetX, offsetY);
+    return rects;
+}
+/** Rects leave in the order they opened, which is not their order across a row. */
+function pushClosedRects(rects, open, closed, closedCount, bottomY, offsetX, offsetY) {
+    for (let index = 1; index < closedCount; index += 1) {
+        const span = closed[index];
+        const openedAt = open.openedAt[span];
+        let sorted = index - 1;
+        while (sorted >= 0 && open.openedAt[closed[sorted]] > openedAt) {
+            closed[sorted + 1] = closed[sorted];
+            sorted -= 1;
+        }
+        closed[sorted + 1] = span;
+    }
+    for (let index = 0; index < closedCount; index += 1) {
+        const span = closed[index];
+        rects.push({
+            height: bottomY - open.topY[span],
+            width: open.runWidth[span],
+            x: open.startX[span] + offsetX,
+            y: open.topY[span] + offsetY,
+        });
     }
-    rects.push(...openRects.values());
-    return rects.length > 0 ? rects : undefined;
 }
-function assertMaskDimensions(data, width, height) {
+function assertMaskSize(width, height) {
     if (!Number.isInteger(width) || width <= 0) {
         throw new Error("Mask width must be a positive integer.");
     }
     if (!Number.isInteger(height) || height <= 0) {
         throw new Error("Mask height must be a positive integer.");
     }
+}
+function assertMaskDimensions(data, width, height) {
+    assertMaskSize(width, height);
     if (data.length !== width * height) {
         throw new Error("Mask data length must equal width * height.");
     }
@@ -5314,8 +5989,8 @@ const DEFAULT_SELECTED_STROKE_WIDTH = 4;
  * Default configurable interaction style.
  *
  * It resolves hover and selected picks into state-specific presentations using
- * the same style contracts as normal boxes, masks, and labels. The older
- * rectangle options are kept as compatibility sugar and resolve to a box style.
+ * the same style contracts as normal boxes, masks, and labels. A state left
+ * unconfigured falls back to a highlight rectangle over the detection.
  */
 class BaseInteractionStyle {
     options;
@@ -5337,60 +6012,22 @@ class BaseInteractionStyle {
             return undefined;
         }
         return {
-            boxStyle: createResolvedBoxStyle(this.resolveBoxInstruction(detection, context, rect)),
-        };
-    }
-    resolveBoxInstruction(detection, context, rect) {
-        const shape = this.resolveShape(detection, context);
-        const cornerRadius = this.resolveCornerRadius(detection, context, shape);
-        const instruction = {
-            fill: this.resolveFill(detection, context),
-            rect,
-            shape,
-            stroke: this.resolveStroke(detection, context),
+            boxStyle: createDefaultHighlightBoxStyle(context.state, rect),
         };
-        if (cornerRadius !== undefined) {
-            return {
-                ...instruction,
-                cornerRadius,
-            };
-        }
-        return instruction;
-    }
-    resolveShape(detection, context) {
-        return (resolveStyleValue(this.options.shape, detection, context) ?? BoxShape.Rect);
-    }
-    resolveCornerRadius(detection, context, shape) {
-        if (shape !== BoxShape.RoundedRect) {
-            return undefined;
-        }
-        return resolveStyleValue(this.options.cornerRadius, detection, context);
     }
-    resolveStroke(detection, context) {
-        const stroke = resolveStyleValue(this.options.stroke, detection, context);
-        if (stroke === null) {
-            return undefined;
-        }
-        const defaults = getStateDefaults(context.state);
-        return resolveStrokeStyle(stroke, {
+}
+function createDefaultHighlightBoxStyle(state, rect) {
+    const defaults = getStateDefaults(state);
+    const instruction = {
+        fill: { alpha: defaults.fillAlpha, color: defaults.fillColor },
+        rect,
+        shape: BoxShape.Rect,
+        stroke: {
             alpha: defaults.strokeAlpha,
             color: defaults.strokeColor,
             width: defaults.strokeWidth,
-        });
-    }
-    resolveFill(detection, context) {
-        const fill = resolveStyleValue(this.options.fill, detection, context);
-        if (fill === null) {
-            return undefined;
-        }
-        const defaults = getStateDefaults(context.state);
-        return {
-            alpha: fill?.alpha ?? defaults.fillAlpha,
-            color: fill?.color ?? defaults.fillColor,
-        };
-    }
-}
-function createResolvedBoxStyle(instruction) {
+        },
+    };
     return {
         resolve() {
             return instruction;
@@ -5790,8 +6427,18 @@ class BasePolylineStyle {
         if (stroke === null) {
             return undefined;
         }
+        const shadowStroke = resolveStyleValue(this.options.shadowStroke, detection, context);
         return {
             points: detection.polyline.points,
+            ...(shadowStroke === undefined || shadowStroke === null
+                ? {}
+                : {
+                    shadowStroke: resolveStrokeStyle(shadowStroke, {
+                        alpha: 0.65,
+                        color: 0x000000,
+                        width: 4,
+                    }),
+                }),
             stroke: resolveStrokeStyle(stroke, {
                 alpha: 1,
                 color: 0x00ff66,
@@ -5961,6 +6608,8 @@ const DEFAULT_KEYPOINT_EDGE_WIDTH = 1.5;
 const DEFAULT_KEYPOINT_SHADOW_WIDTH = 3;
 const DEFAULT_KEYPOINT_SHADOW_ALPHA = 0.25;
 const DEFAULT_KEYPOINT_RADIUS = 3.5;
+const DEFAULT_POLYLINE_SHADOW_WIDTH = DEFAULT_OUTLINE_WIDTH + 1;
+const DEFAULT_POLYLINE_SHADOW_ALPHA = 0.55;
 const DEFAULT_LABEL_CORNER_RADIUS = 4;
 const DEFAULT_LABEL_PADDING_X = 6;
 const DEFAULT_LABEL_PADDING_Y = 3;
@@ -6149,6 +6798,11 @@ function createDefaultPolygonStyle(options = {}) {
 function createDefaultPolylineStyle(options = {}) {
     const getClassColor = createClassColorResolver(options);
     return new BasePolylineStyle({
+        shadowStroke: {
+            alpha: DEFAULT_POLYLINE_SHADOW_ALPHA,
+            color: 0x000000,
+            width: DEFAULT_POLYLINE_SHADOW_WIDTH,
+        },
         stroke: (detection) => ({
             alpha: 1,
             color: getClassColor(detection),
@@ -6188,12 +6842,28 @@ const annotationRendererKinds = [
 /** Sources currently supported by a region renderer. */
 const RegionRendererSourceKind = {
     Asset: "asset",
+    Media: "media",
 };
 /** Media-space regions currently supported by a region renderer. */
 const RegionRendererRegionKind = {
     Bounds: "bounds",
     KeypointAnchor: "keypoint-anchor",
 };
+/** Semantic coverage used to clip pixels sampled from the current media. */
+const RegionRendererCoverageKind = {
+    Mask: "mask",
+    Polygon: "polygon",
+};
+/** Filter effects that can be applied to a current-frame media region. */
+const RegionRendererMediaEffectKind = {
+    Blur: "blur",
+    Pixelate: "pixelate",
+};
+/** Coordinate space used by an explicit region-renderer size. */
+const RegionRendererSizeSpace = {
+    Media: "media",
+    Screen: "screen",
+};
 /** Composition modes currently supported by a region renderer. */
 const RegionRendererComposeMode = {
     Over: "over",
@@ -6572,10 +7242,10 @@ function rasterizeRectToMask(rect, dimensions) {
     const topLeft = centerRectToTopLeftRect(rect);
     const left = Math.max(0, Math.round(topLeft.x));
     const top = Math.max(0, Math.round(topLeft.y));
-    const right = Math.min(dimensions.width - 1, Math.round(rect.x + rect.width / 2));
-    const bottom = Math.min(dimensions.height - 1, Math.round(rect.y + rect.height / 2));
-    for (let y = top; y <= bottom; y += 1) {
-        for (let x = left; x <= right; x += 1) {
+    const right = Math.min(dimensions.width, Math.round(topLeft.x + rect.width));
+    const bottom = Math.min(dimensions.height, Math.round(topLeft.y + rect.height));
+    for (let y = top; y < bottom; y += 1) {
+        for (let x = left; x < right; x += 1) {
             data[y * dimensions.width + x] = 1;
         }
     }
@@ -6603,9 +7273,9 @@ function rasterizePolygonToMask(points, dimensions) {
         }
         intersections.sort((left, right) => left - right);
         for (let index = 0; index < intersections.length - 1; index += 2) {
-            const left = Math.max(0, Math.ceil(intersections[index]));
-            const right = Math.min(dimensions.width - 1, Math.floor(intersections[index + 1]));
-            for (let x = left; x <= right; x += 1) {
+            const left = Math.max(0, Math.round(intersections[index]));
+            const right = Math.min(dimensions.width, Math.round(intersections[index + 1]));
+            for (let x = left; x < right; x += 1) {
                 data[y * dimensions.width + x] = 1;
             }
         }
@@ -6745,14 +7415,28 @@ function resolveMaskStyleOpacity(maskStyle) {
     return Number.isFinite(opacity) ? Math.max(0, Math.min(opacity, 1)) : 1;
 }
 
-const MAX_ID_MASK_PALETTE_ENTRIES = 64;
+/**
+ * Palette slots an id raster can name, one of them the background. A GLSL
+ * fragment stage is guaranteed only 224 uniform vectors, and a palette entry
+ * costs 2.25 of them, so this stays a multiple of four and well inside that
+ * budget; past it a frame draws from the RGBA composite instead.
+ */
+const MAX_ID_MASK_PALETTE_ENTRIES = 80;
 const MAX_ID_MASK_STROKE_WIDTH = 16;
-function createIdMaskFrame(instructions) {
+function createIdMaskFrame(instructions, options = {}) {
     if (instructions.length === 0) {
         return undefined;
     }
-    const width = Math.max(...instructions.map(({ mask }) => mask.width));
-    const height = Math.max(...instructions.map(({ mask }) => mask.height));
+    const maskWidth = Math.max(...instructions.map(({ mask }) => mask.width));
+    const maskHeight = Math.max(...instructions.map(({ mask }) => mask.height));
+    const width = resolveRasterWidth(maskWidth, options.maxWidth);
+    const height = width === maskWidth
+        ? maskHeight
+        : Math.max(1, Math.round((width * maskHeight) / maskWidth));
+    const strokeScale = width / maskWidth;
+    const scaledAxes = width === maskWidth
+        ? undefined
+        : createScaledMaskAxes({ height, maskHeight, maskWidth, width });
     const data = new Uint8Array(new ArrayBuffer(width * height));
     const fillPalette = new Float32Array(new ArrayBuffer(MAX_ID_MASK_PALETTE_ENTRIES * 4 * 4));
     const strokePalette = new Float32Array(new ArrayBuffer(MAX_ID_MASK_PALETTE_ENTRIES * 4 * 4));
@@ -6767,20 +7451,17 @@ function createIdMaskFrame(instructions) {
         }
         writePaletteEntry(fillPalette, detectionMaskId, instruction.color, instruction.alpha);
         if (instruction.stroke && instruction.stroke.width > 0) {
-            const strokeWidth = Math.min(Math.max(0, instruction.stroke.width), MAX_ID_MASK_STROKE_WIDTH);
+            const strokeWidth = Math.min(resolveStrokeTexels(instruction.stroke.width, strokeScale), MAX_ID_MASK_STROKE_WIDTH);
             hasStroke = true;
             strokeWidths[detectionMaskId] = strokeWidth;
             maxStrokeWidth = Math.max(maxStrokeWidth, strokeWidth);
             writePaletteEntry(strokePalette, detectionMaskId, instruction.stroke.color, instruction.stroke.alpha);
         }
-        const decodedMask = decodeCompressedRleMask(instruction.mask);
-        for (let y = 0; y < decodedMask.height; y += 1) {
-            for (let x = 0; x < decodedMask.width; x += 1) {
-                const maskOffset = y * decodedMask.width + x;
-                if (decodedMask.data[maskOffset]) {
-                    data[y * width + x] = detectionMaskId;
-                }
-            }
+        if (scaledAxes) {
+            writeScaledMaskRuns(data, scaledAxes, instruction.mask, detectionMaskId);
+        }
+        else {
+            writeMaskRuns(data, width, instruction.mask, detectionMaskId);
         }
     }
     return {
@@ -6794,6 +7475,103 @@ function createIdMaskFrame(instructions) {
         width,
     };
 }
+/**
+ * Compressed RLE counts runs down each column in turn, so a foreground run is
+ * a contiguous walk down one column that wraps into the next.
+ */
+function writeMaskRuns(data, frameWidth, mask, detectionMaskId) {
+    const counts = decodeCompressedRleCounts(mask.counts);
+    const maskWidth = mask.width;
+    const maskHeight = mask.height;
+    let maskOffset = 0;
+    for (let index = 0; index < counts.length; index += 1) {
+        const runLength = counts[index] ?? 0;
+        if (index % 2 === 0 || runLength <= 0) {
+            maskOffset += runLength;
+            continue;
+        }
+        let x = Math.floor(maskOffset / maskHeight);
+        let y = maskOffset - x * maskHeight;
+        let frameOffset = y * frameWidth + x;
+        for (let step = 0; step < runLength; step += 1) {
+            if (x >= maskWidth) {
+                break;
+            }
+            data[frameOffset] = detectionMaskId;
+            y += 1;
+            frameOffset += frameWidth;
+            if (y === maskHeight) {
+                y = 0;
+                x += 1;
+                frameOffset = x;
+            }
+        }
+        maskOffset += runLength;
+    }
+}
+/**
+ * The scaled twin of writeMaskRuns. Every source pixel marks the texel it lands
+ * in, so a mask keeps every part of itself the smaller raster can hold and
+ * gains up to a texel at its edges.
+ */
+function writeScaledMaskRuns(data, axes, mask, detectionMaskId) {
+    const counts = decodeCompressedRleCounts(mask.counts);
+    const maskWidth = mask.width;
+    const maskHeight = mask.height;
+    let maskOffset = 0;
+    for (let index = 0; index < counts.length; index += 1) {
+        const runLength = counts[index] ?? 0;
+        if (index % 2 === 0 || runLength <= 0) {
+            maskOffset += runLength;
+            continue;
+        }
+        let x = Math.floor(maskOffset / maskHeight);
+        let y = maskOffset - x * maskHeight;
+        let column = axes.columns[x];
+        for (let step = 0; step < runLength; step += 1) {
+            if (x >= maskWidth) {
+                break;
+            }
+            data[axes.rows[y] + column] = detectionMaskId;
+            y += 1;
+            if (y === maskHeight) {
+                y = 0;
+                x += 1;
+                column = axes.columns[x];
+            }
+        }
+        maskOffset += runLength;
+    }
+}
+function resolveRasterWidth(maskWidth, maxWidth) {
+    return maxWidth !== undefined && maxWidth > 0 && maxWidth < maskWidth
+        ? Math.max(1, Math.floor(maxWidth))
+        : maskWidth;
+}
+/**
+ * A stroke is measured in texels of the raster it is drawn on, so a coarser
+ * raster measures it in coarser texels. A stroke of a texel or more keeps at
+ * least one, the thinnest line the shader can draw; a narrower one keeps its
+ * own width, which the shader draws as an inner boundary at any scale.
+ */
+function resolveStrokeTexels(strokeWidth, scale) {
+    return Math.max(strokeWidth * scale, Math.min(strokeWidth, 1));
+}
+function createScaledMaskAxes(frame) {
+    return {
+        columns: createMaskAxisMap(frame.maskWidth, frame.width, 1),
+        rows: createMaskAxisMap(frame.maskHeight, frame.height, frame.width),
+    };
+}
+/** Rows hold their destination offset, so writing a run is two lookups. */
+function createMaskAxisMap(sourceLength, targetLength, stride) {
+    const map = new Int32Array(sourceLength);
+    const scale = targetLength / sourceLength;
+    for (let index = 0; index < sourceLength; index += 1) {
+        map[index] = Math.min(targetLength - 1, Math.floor(index * scale)) * stride;
+    }
+    return map;
+}
 function writePaletteEntry(palette, id, color, alpha) {
     const offset = id * 4;
     palette[offset] = ((color >> 16) & 0xff) / 255;
@@ -7058,6 +7836,30 @@ var MediaSourceStatus;
     MediaSourceStatus["Error"] = "error";
     MediaSourceStatus["Destroyed"] = "destroyed";
 })(MediaSourceStatus || (MediaSourceStatus = {}));
+/**
+ * Current renderer state.
+ */
+/**
+ * What a playback gate holds back.
+ *
+ * A source the renderer pulls samples from can be held between any two frames,
+ * because the renderer decides when each one is drawn. A source that presents
+ * its own frames owns the playhead, so holding it means stopping the producer
+ * and starting it again, which the detection gate does and the
+ * render-preparation gate does not.
+ */
+var PlaybackGateReach;
+(function (PlaybackGateReach) {
+    /** No gate: the picture moves and unprepared layers are absent from it. */
+    PlaybackGateReach["Off"] = "off";
+    /**
+     * Playback waits to begin, and stops again at any frame whose artifacts are
+     * missing, until they arrive or the gate's own wait bound gives up on them.
+     */
+    PlaybackGateReach["EveryFrame"] = "everyFrame";
+    /** Playback waits to begin; frames after that are not held. */
+    PlaybackGateReach["StartOfPlayback"] = "startOfPlayback";
+})(PlaybackGateReach || (PlaybackGateReach = {}));
 
 /**
  * Media-session operating mode.
@@ -7098,6 +7900,13 @@ var MediaSessionStatus;
  */
 var MediaSessionActivityKind;
 (function (MediaSessionActivityKind) {
+    /**
+     * Playback is held waiting for a producer to emit detections for the frame
+     * about to be shown, which is a wait on inference rather than on transfer or
+     * decode. `DetectionsBuffering` is the transfer of detections that already
+     * exist, and `PlaybackBuffering` is the wait for media bytes.
+     */
+    MediaSessionActivityKind["DetectionsAwaitingCoverage"] = "detectionsAwaitingCoverage";
     MediaSessionActivityKind["DetectionsBuffering"] = "detectionsBuffering";
     MediaSessionActivityKind["DetectionsLoading"] = "detectionsLoading";
     MediaSessionActivityKind["Error"] = "error";
@@ -7116,5 +7925,5 @@ var MediaSessionActivityStatus;
     MediaSessionActivityStatus["Waiting"] = "waiting";
 })(MediaSessionActivityStatus || (MediaSessionActivityStatus = {}));
 
-export { AnnotationFrameMutationKind, AnnotationGeometryKind, AnnotationGestureStateKind, AnnotationHandleKind, BaseBoxCornerStyle, BaseBoxStyle, BaseFocusStyle, BaseInteractionStyle, BaseKeypointStyle, BaseLabelStyle, BaseMarkerStyle, BaseMaskStyle, BasePolygonStyle, BasePolylineStyle, BoxShape, StrokeAlignment as BoxStrokeAlignment, DEFAULT_DETECTION_CLASS_STYLES, DEFAULT_DETECTION_COLOR_SEQUENCE, DetectionBufferStatus, DetectionFrameRetentionMode, DetectionFrameSelectionMode, DetectionInteractionState, DetectionMaskEncoding, DetectionMaskPayloadFormat, DetectionPickTarget, FocusTargetMode, KeypointMarkerShape, KeypointVisibility, LabelPlacement, LabelVisibilityMode, MAX_ID_MASK_PALETTE_ENTRIES, MAX_ID_MASK_STROKE_WIDTH, MarkerShape, MarkerSizeSpace, MaskRenderMode, MediaErrorKind, MediaInteractionMode, MediaRendererFit, MediaRendererPlaybackState, MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, MediaSourceStatus, RegionRendererComposeMode, RegionRendererRegionKind, RegionRendererSourceKind, SUPERVISION_ROBOFLOW_COLOR, ShapeInstructionKind, StrokeAlignment, TrackingGeometry, annotationRendererKinds, annotationRenderers, applyAnnotationHandleDrag, canReuseMaskStyleArtifacts, centerRectToTopLeftRect, computeDetectionMaskRect, computeMaskBounds, containsPoint, convertDetectionBoxToMask, convertDetectionBoxToPolygon, convertDetectionMaskToBox, convertDetectionMaskToPolygon, convertDetectionPolygonToBox, convertDetectionPolygonToMask, copySortedDetectionFrames, createAnnotationEditingEngine, createArrayDetectionFrameSource, createBufferedDetectionTimeline, createByteTrackTracker, createCBIoUTracker, createColdDetectionFrameSource, createCompositeDetectionFrameSource, createDefaultAnnotationPresentation, createDetectionPickKey, createEditableAnnotationFrameSession, createIdMaskFrame, createIdleDetectionBufferState, createMemoryColdDetectionFrameStore, createOCSortTracker, createProjectedDetectionFrameSource, createSortTracker, createSourceAwarePresentation, createViewportController, createWritableDetectionFrameSource, decodeCompressedRleCounts, decodeCompressedRleMask, decodeDetectionMaskPayload, deleteAnnotationVertex, detectMaskBorders, detectionFrameOverlapsRange, detectionPostProcessors, distanceToSegment, encodeBinaryMask, encodeBinaryMaskWithBounds, encodeCompressedRleCounts, encodeDetectionMaskPayload, extractMaskContour, extractMaskRectRuns, filterDetectionFramesForRange, findClosestAnnotationSegment, followDetectionPickAcrossFrames, getAnnotationHandles, getBufferedDetectionTimelineFrameSnapshot, getDetectionRect, getPointsRect, haveSameDetectionPickIdentities, includeDefined, isDeflatedBase64DetectionMaskPayload, lightenColor, mediaToScreen, mergeDetectionMasks, mergeDetectionPolygonsByClass, normalizeDetectionClassName, offsetDetection, pickAnnotationHandle, pickDetectionAtPoint, pickDetectionByMaskId, pointInPolygon, polygonArea, polygonToRect, projectDetectionFrame, projectDetectionFrameForTracking, projectDetectionFrames, rasterizePolygonToMask, rasterizeRectToMask, rebaseDetectionPickToFrame, rectArea, rectToPolygon, resolveAnnotationRendererPresentation, resolveAnnotationStyleState, resolveContrastTextColor, resolveDetectionClassColorStyle, resolveEllipseSegmentCount, resolveMarkerGeometry, resolveMaskStyleOpacity, resolveStyleValue, sampleEllipseArc, screenToMedia, selectDetectionFrame, topLeftRectToCenterRect, validateDetectionFrames };
+export { AnnotationFrameMutationKind, AnnotationGeometryKind, AnnotationGestureStateKind, AnnotationHandleKind, BaseBoxCornerStyle, BaseBoxStyle, BaseFocusStyle, BaseInteractionStyle, BaseKeypointStyle, BaseLabelStyle, BaseMarkerStyle, BaseMaskStyle, BasePolygonStyle, BasePolylineStyle, BoxShape, StrokeAlignment as BoxStrokeAlignment, DEFAULT_DETECTION_CLASS_STYLES, DEFAULT_DETECTION_COLOR_SEQUENCE, DetectionBufferStatus, DetectionFrameRetentionMode, DetectionFrameSelectionMode, DetectionInteractionState, DetectionMaskEncoding, DetectionMaskPayloadFormat, DetectionPickTarget, FocusTargetMode, KeypointMarkerShape, KeypointVisibility, LabelPlacement, LabelVisibilityMode, MAX_ID_MASK_PALETTE_ENTRIES, MAX_ID_MASK_STROKE_WIDTH, MarkerShape, MarkerSizeSpace, MaskRenderMode, MediaErrorKind, MediaInteractionMode, MediaRendererFit, MediaRendererPlaybackState, MediaSessionActivityKind, MediaSessionActivityStatus, MediaSessionMode, MediaSessionStatus, MediaSourceStatus, PlaybackGateReach, RegionRendererComposeMode, RegionRendererCoverageKind, RegionRendererMediaEffectKind, RegionRendererRegionKind, RegionRendererSizeSpace, RegionRendererSourceKind, SUPERVISION_ROBOFLOW_COLOR, ShapeInstructionKind, StrokeAlignment, TrackingGeometry, annotationRendererKinds, annotationRenderers, applyAnnotationHandleDrag, canReuseMaskStyleArtifacts, centerRectToTopLeftRect, computeDetectionMaskRect, computeMaskBounds, containsPoint, convertDetectionBoxToMask, convertDetectionBoxToPolygon, convertDetectionMaskToBox, convertDetectionMaskToPolygon, convertDetectionPolygonToBox, convertDetectionPolygonToMask, copySortedDetectionFrames, createAnnotationEditingEngine, createArrayDetectionFrameSource, createBufferedDetectionTimeline, createByteTrackTracker, createCBIoUTracker, createColdDetectionFrameSource, createCompositeDetectionFrameSource, createDefaultAnnotationPresentation, createDetectionPickKey, createEditableAnnotationFrameSession, createIdMaskFrame, createIdleDetectionBufferState, createMemoryColdDetectionFrameStore, createOCSortTracker, createProjectedDetectionFrameSource, createSortTracker, createSourceAwarePresentation, createViewportController, createWritableDetectionFrameSource, decodeCompressedRleCounts, decodeCompressedRleMask, decodeDetectionMaskPayload, deleteAnnotationVertex, detectMaskBorders, detectionFrameOverlapsRange, detectionPostProcessors, distanceToSegment, encodeBinaryMask, encodeBinaryMaskWithBounds, encodeCompressedRleCounts, encodeDetectionMaskPayload, extractDetectionMaskRectRuns, extractMaskContour, extractMaskRectRuns, filterDetectionFramesForRange, findClosestAnnotationSegment, followDetectionPickAcrossFrames, getAnnotationHandles, getBufferedDetectionTimelineFrameSnapshot, getDetectionRect, getPointsRect, haveSameDetectionPickIdentities, includeDefined, isDeflatedBase64DetectionMaskPayload, lightenColor, mediaToScreen, mergeDetectionMasks, mergeDetectionPolygonsByClass, normalizeDetectionClassName, offsetDetection, pickAnnotationHandle, pickDetectionAtPoint, pickDetectionByMaskId, pointInPolygon, polygonArea, polygonToRect, projectDetectionFrame, projectDetectionFrameForTracking, projectDetectionFrames, rasterizePolygonToMask, rasterizeRectToMask, rebaseDetectionPickToFrame, rectArea, rectToPolygon, resolveAnnotationRendererPresentation, resolveAnnotationRendererStyleFields, resolveAnnotationStyleState, resolveContrastTextColor, resolveDetectionClassColorStyle, resolveEllipseSegmentCount, resolveMarkerGeometry, resolveMaskStyleOpacity, resolveStyleValue, sampleEllipseArc, screenToMedia, selectDetectionFrame, topLeftRectToCenterRect, validateDetectionFrames };
 //# sourceMappingURL=index.js.map