supervision 0.1.7 → 0.2.0-next.0

package/dist/renderers/presented-frame-channel.d.ts

@@ -0,0 +1,107 @@
+/**
+ * A frame of the source, named by its place in presentation order and by its
+ * presentation timestamp in the container's own integer grain.
+ */
+export interface PresentedFrameId {
+    readonly index: number;
+    readonly ticks: number;
+}
+/**
+ * One frame a push-based media producer has decided is on screen, carrying the
+ * frame it is and the media time it stands for. Whoever receives it owns it and
+ * must close it.
+ */
+export interface PresentedVideoFrame {
+    readonly frameId: PresentedFrameId;
+    /**
+     * The producer's count of the paints it has made, which is what its own
+     * diagnostics name a paint by. Two paints of one frame carry different
+     * numbers, so this is the only key that joins a frame the renderer drew to
+     * the paint the producer recorded making.
+     */
+    readonly paintSeq: number;
+    /**
+     * The producer's seconds for `frameId`. The producer also states the position
+     * in milliseconds, and this deliberately does not carry it: that value is the
+     * seconds scaled by a thousand, so dividing it back is not the identity, and
+     * on a container whose tick grain is not whole milliseconds, an NTSC
+     * 30000/1001 track among them, the result names no frame at all.
+     */
+    readonly mediaTimeS: number;
+    readonly frame: VideoFrame;
+}
+/** Where the producer's playhead sits, named as a frame of the source. */
+export interface PresentedFramePlayhead {
+    readonly frame: PresentedFrameId;
+    readonly mediaTimeS: number;
+}
+/** Coarse producer status, reported in the producer's own vocabulary. */
+export type PresentedFrameChannelStatus = "IDLE" | "LOADING" | "READY" | "PLAYING" | "PAUSED" | "SEEKING" | "ENDED" | "ERRORED";
+/**
+ * Whether a seek is a gesture still moving or a jump to a destination. A
+ * producer may answer a gesture from a cheap cache and a jump exactly.
+ */
+export type PresentedFrameSeekIntent = "gesture" | "jump";
+/**
+ * Producer signals, one per cadence: `time` on every playhead move, `state` on
+ * coarse status transitions, `seeking` when a seek starts or settles, `rate`
+ * when the playback speed changes.
+ */
+export type PresentedFrameChannelSignal = "time" | "state" | "seeking" | "rate";
+/**
+ * A producer's presented-frame plane. Registering replaces any previous
+ * handler, so the registered handler is the single owner of every frame.
+ */
+export interface PresentedFrameSource {
+    onPresentedFrame(handler: (presented: PresentedVideoFrame) => void): void;
+}
+/**
+ * The frame plane plus the transport that moves it. Everything below the frames
+ * is the playhead, and the producer owns it: a renderer holding this channel
+ * asks rather than decides.
+ */
+export interface PresentedFrameChannel extends PresentedFrameSource {
+    /**
+     * Runs the playhead forward from where it stands, and from `ENDED` restarts
+     * at the start of the source.
+     *
+     * A channel never loops itself. A renderer told to loop replays by calling
+     * this when the status turns `ENDED`, so a channel that resumes in place
+     * from `ENDED` never loops.
+     */
+    play(): Promise<void>;
+    /**
+     * Stops the playhead where it stands. A pause asked for here outranks the
+     * freeze `beginInteractiveSeek` holds, so the `endInteractiveSeek` that ends
+     * the drag has nothing left to resume.
+     */
+    pause(): void;
+    /** Latest-wins seek for a gesture in flight; returns without settling. */
+    scrub(timeMs: number, intent?: PresentedFrameSeekIntent): void;
+    /** Seek that settles: resolves once the producer has landed on `timeMs`. */
+    commit(timeMs: number): Promise<void>;
+    /** Walks one real source frame in presentation order. */
+    step(direction: 1 | -1): Promise<void>;
+    /**
+     * Forward playback speed, in media seconds per wall second. Throws on a rate
+     * the producer cannot play, reverse included.
+     */
+    setPlaybackRate(rate: number): void;
+    getPlaybackRate(): number;
+    /** Freezes a playing producer for the length of a drag. */
+    beginInteractiveSeek(): void;
+    /** Resumes play only if `beginInteractiveSeek` was what paused it. */
+    endInteractiveSeek(): Promise<void>;
+    getPlayhead(): PresentedFramePlayhead;
+    getDurationMs(): number;
+    getStatus(): PresentedFrameChannelStatus;
+    getSeeking(): boolean;
+    subscribe(signal: PresentedFrameChannelSignal, listener: () => void): () => void;
+}
+/**
+ * Reads the presented-frame plane an opened media source publishes as `engine`.
+ * A source without one is pull-only, and the renderer keeps driving it by
+ * asking for samples.
+ */
+export declare function resolvePresentedFrameChannel(source: unknown): PresentedFrameChannel | null;
+//# sourceMappingURL=presented-frame-channel.d.ts.map

package/dist/renderers/presented-frame-channel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"presented-frame-channel.d.ts","sourceRoot":"","sources":["../../src/renderers/presented-frame-channel.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED;;;;GAIG;AACH,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC;;;;;OAKG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;CAC5B;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC,QAAQ,CAAC,KAAK,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED,yEAAyE;AACzE,MAAM,MAAM,2BAA2B,GACnC,MAAM,GACN,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,GACT,OAAO,GACP,SAAS,CAAC;AAEd;;;GAGG;AACH,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG,MAAM,CAAC;AAE1D;;;;GAIG;AACH,MAAM,MAAM,2BAA2B,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAEhF;;;GAGG;AACH,MAAM,WAAW,oBAAoB;IACnC,gBAAgB,CAAC,OAAO,EAAE,CAAC,SAAS,EAAE,mBAAmB,KAAK,IAAI,GAAG,IAAI,CAAC;CAC3E;AAED;;;;GAIG;AACH,MAAM,WAAW,qBAAsB,SAAQ,oBAAoB;IACjE;;;;;;;OAOG;IACH,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACtB;;;;OAIG;IACH,KAAK,IAAI,IAAI,CAAC;IACd,0EAA0E;IAC1E,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,wBAAwB,GAAG,IAAI,CAAC;IAC/D,4EAA4E;IAC5E,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,yDAAyD;IACzD,IAAI,CAAC,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACvC;;;OAGG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpC,eAAe,IAAI,MAAM,CAAC;IAC1B,2DAA2D;IAC3D,oBAAoB,IAAI,IAAI,CAAC;IAC7B,sEAAsE;IACtE,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACpC,WAAW,IAAI,sBAAsB,CAAC;IACtC,aAAa,IAAI,MAAM,CAAC;IACxB,SAAS,IAAI,2BAA2B,CAAC;IACzC,UAAU,IAAI,OAAO,CAAC;IACtB,SAAS,CACP,MAAM,EAAE,2BAA2B,EACnC,QAAQ,EAAE,MAAM,IAAI,GACnB,MAAM,IAAI,CAAC;CACf;AAED;;;;GAIG;AACH,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,OAAO,GACd,qBAAqB,GAAG,IAAI,CAQ9B"}

package/dist/renderers/scene-render-scheduler.d.ts

@@ -0,0 +1,20 @@
+/**
+ * A comparable description of everything a render would put on screen. Values
+ * are compared position by position with `Object.is`, so a notification whose
+ * description matches the one already drawn costs nothing.
+ */
+export type SceneRenderSignature = readonly unknown[];
+export interface SceneRenderScheduler {
+    /** Renders only when the description differs from what was last drawn. */
+    renderOnChange(signature: SceneRenderSignature): boolean;
+    /** Renders whatever the description says, for pixels that changed outside it. */
+    render(signature: SceneRenderSignature): void;
+    /** Renders this scheduler issued, which is every render under its policy. */
+    getRenderCount(): number;
+}
+/**
+ * Turns change notifications into renders. It owns no timer, no ticker and no
+ * animation frame: a scheduler nobody notifies renders nothing, forever.
+ */
+export declare function createSceneRenderScheduler(draw: () => void): SceneRenderScheduler;
+//# sourceMappingURL=scene-render-scheduler.d.ts.map

package/dist/renderers/scene-render-scheduler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scene-render-scheduler.d.ts","sourceRoot":"","sources":["../../src/renderers/scene-render-scheduler.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,oBAAoB,GAAG,SAAS,OAAO,EAAE,CAAC;AAEtD,MAAM,WAAW,oBAAoB;IACnC,0EAA0E;IAC1E,cAAc,CAAC,SAAS,EAAE,oBAAoB,GAAG,OAAO,CAAC;IACzD,iFAAiF;IACjF,MAAM,CAAC,SAAS,EAAE,oBAAoB,GAAG,IAAI,CAAC;IAC9C,6EAA6E;IAC7E,cAAc,IAAI,MAAM,CAAC;CAC1B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,CACxC,IAAI,EAAE,MAAM,IAAI,GACf,oBAAoB,CA0BtB"}

package/dist/sessions/media-session-defaults.d.ts

@@ -1,15 +1,19 @@
 import type { DetectionBufferOptions, DetectionFrameRetentionOptions } from "supervision-js-core";
 import type { RenderPreparationOptions } from "#types/render-preparation";
-import type { MediaSessionAppendableDetectionOptions, MediaSessionDetectionOptions, MediaSessionMode, MediaSessionRendererOptions } from "#types/media-session";
+import type { MediaSessionAppendableDetectionOptions, MediaSessionMode, MediaSessionOptions } from "#types/media-session";
 export interface ResolvedMediaSessionDefaults {
     readonly detectionBuffer: DetectionBufferOptions;
     readonly renderPreparation: RenderPreparationOptions;
 }
-export declare function resolveMediaSessionDefaults(options: {
-    readonly detections?: MediaSessionDetectionOptions;
-    readonly mode?: MediaSessionMode;
-    readonly renderer?: MediaSessionRendererOptions;
-}): ResolvedMediaSessionDefaults;
+/**
+ * The detection-buffer and render-preparation configuration a session created
+ * with these options actually runs on.
+ *
+ * `createMediaSession` resolves its options through this, so a host can read
+ * the numbers a session will use, and show or log them, without restating the
+ * defaults itself.
+ */
+export declare function resolveMediaSessionDefaults(options: Pick<MediaSessionOptions, "detections" | "mode" | "playbackGate" | "renderer">): ResolvedMediaSessionDefaults;
 export declare function resolveMediaSessionAppendableRetention(options: {
     readonly mode?: MediaSessionMode;
     readonly appendable?: MediaSessionAppendableDetectionOptions;

package/dist/sessions/media-session-defaults.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-session-defaults.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EACV,sCAAsC,EACtC,4BAA4B,EAC5B,gBAAgB,EAChB,2BAA2B,EAC5B,MAAM,sBAAsB,CAAC;AAwC9B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,wBAAwB,CAAC;CACtD;AAED,wBAAgB,2BAA2B,CAAC,OAAO,EAAE;IACnD,QAAQ,CAAC,UAAU,CAAC,EAAE,4BAA4B,CAAC;IACnD,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,2BAA2B,CAAC;CACjD,GAAG,4BAA4B,CAwE/B;AAED,wBAAgB,sCAAsC,CAAC,OAAO,EAAE;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,sCAAsC,CAAC;CAC9D,GAAG,8BAA8B,CAgCjC;AAED,wBAAgB,oCAAoC,CAAC,OAAO,EAAE;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,sCAAsC,CAAC;CAC5D,GAAG,8BAA8B,CAKjC"}
+{"version":3,"file":"media-session-defaults.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-defaults.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,sBAAsB,EACtB,8BAA8B,EAC/B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,KAAK,EACV,sCAAsC,EACtC,gBAAgB,EAChB,mBAAmB,EACpB,MAAM,sBAAsB,CAAC;AAuD9B,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,eAAe,EAAE,sBAAsB,CAAC;IACjD,QAAQ,CAAC,iBAAiB,EAAE,wBAAwB,CAAC;CACtD;AAED;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CACzC,OAAO,EAAE,IAAI,CACX,mBAAmB,EACnB,YAAY,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CACpD,GACA,4BAA4B,CAgF9B;AAED,wBAAgB,sCAAsC,CAAC,OAAO,EAAE;IAC9D,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,sCAAsC,CAAC;CAC9D,GAAG,8BAA8B,CAgCjC;AAED,wBAAgB,oCAAoC,CAAC,OAAO,EAAE;IAC5D,QAAQ,CAAC,IAAI,CAAC,EAAE,gBAAgB,CAAC;IACjC,QAAQ,CAAC,QAAQ,CAAC,EAAE,sCAAsC,CAAC;CAC5D,GAAG,8BAA8B,CAKjC"}

package/dist/sessions/media-session-media.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-session-media.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-media.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,oBAAoB,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;IAC5E,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,UAAU,4BAA4B;IACpC,uBAAuB,IAAI,IAAI,CAAC;IAChC,uBAAuB,CAAC,QAAQ,EAAE;QAChC,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,oBAAoB,IAAI,IAAI,CAAC;CAC9B;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,KAAK,GAAG,gCAAgC,GAAG,SAAS,EAC/D,SAAS,EAAE,4BAA4B,GACtC,OAAO,CAAC,oBAAoB,CAAC,CA0F/B;AAED,wBAAgB,qBAAqB,IAAI,sBAAsB,CAM9D"}
+{"version":3,"file":"media-session-media.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-media.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EACjB,sBAAsB,EACtB,gCAAgC,EACjC,MAAM,sBAAsB,CAAC;AAC9B,OAAO,KAAK,EACV,oBAAoB,EAErB,MAAM,uBAAuB,CAAC;AAE/B,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,oBAAoB,EAAE,IAAI,CAAC,oBAAoB,EAAE,QAAQ,GAAG,KAAK,CAAC,CAAC;IAC5E,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,UAAU,4BAA4B;IACpC,uBAAuB,IAAI,IAAI,CAAC;IAChC,uBAAuB,CAAC,QAAQ,EAAE;QAChC,QAAQ,EAAE,MAAM,CAAC;QACjB,aAAa,EAAE,MAAM,CAAC;KACvB,GAAG,IAAI,CAAC;IACT,oBAAoB,IAAI,IAAI,CAAC;CAC9B;AAED,wBAAsB,mBAAmB,CACvC,KAAK,EAAE,iBAAiB,EACxB,SAAS,EAAE,KAAK,GAAG,gCAAgC,GAAG,SAAS,EAC/D,SAAS,EAAE,4BAA4B,GACtC,OAAO,CAAC,oBAAoB,CAAC,CAkH/B;AAED,wBAAgB,qBAAqB,IAAI,sBAAsB,CAO9D"}

package/dist/sessions/media-session-state.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-session-state.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-state.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAEL,KAAK,4BAA4B,EAClC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAKL,KAAK,sBAAsB,EAC3B,KAAK,8BAA8B,EACnC,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAgB,+BAA+B,CAAC,EAC9C,YAAY,EACZ,KAAK,EACL,aAAa,EACb,iBAAiB,EACjB,QAAQ,GACT,EAAE,8BAA8B,GAAG,iBAAiB,CAiIpD"}
+{"version":3,"file":"media-session-state.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session-state.ts"],"names":[],"mappings":"AACA,OAAO,EAGL,KAAK,kBAAkB,EACxB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAIL,KAAK,4BAA4B,EAClC,MAAM,2BAA2B,CAAC;AACnC,OAAO,EAML,KAAK,sBAAsB,EAC3B,KAAK,8BAA8B,EACnC,KAAK,iBAAiB,EACvB,MAAM,sBAAsB,CAAC;AAE9B,MAAM,WAAW,8BAA8B;IAC7C,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IACrC,QAAQ,CAAC,KAAK,EAAE,sBAAsB,CAAC;IACvC,QAAQ,CAAC,aAAa,EAAE,8BAA8B,GAAG,IAAI,CAAC;IAC9D,QAAQ,CAAC,iBAAiB,EAAE,4BAA4B,GAAG,IAAI,CAAC;IAChE,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,GAAG,IAAI,CAAC;CAC9C;AAED,wBAAgB,+BAA+B,CAAC,EAC9C,YAAY,EACZ,KAAK,EACL,aAAa,EACb,iBAAiB,EACjB,QAAQ,GACT,EAAE,8BAA8B,GAAG,iBAAiB,CAiMpD"}

package/dist/sessions/media-session.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"media-session.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,gBAAgB,EAKhB,mBAAmB,EAEpB,MAAM,sBAAsB,CAAC;AAoB9B;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAof3B"}
+{"version":3,"file":"media-session.d.ts","sourceRoot":"","sources":["../../src/sessions/media-session.ts"],"names":[],"mappings":"AAgBA,OAAO,KAAK,EACV,gBAAgB,EAKhB,mBAAmB,EAEpB,MAAM,sBAAsB,CAAC;AAoB9B;;;;;;GAMG;AACH,wBAAsB,kBAAkB,CACtC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,gBAAgB,CAAC,CAqf3B"}

package/dist/tracking.worker.js

@@ -17,6 +17,12 @@
     (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";
@@ -29,12 +35,30 @@
         /**
          * 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 = {}));
@@ -1398,6 +1422,30 @@
         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.
@@ -1438,6 +1486,13 @@
      */
     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";