supervision 0.2.5 → 0.2.6

package/dist/render-preparation/depth/frame-preparer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-preparer.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/frame-preparer.ts"],"names":[],"mappings":"AAGA,OAAO,EAEL,KAAK,oBAAoB,EAG1B,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAMnC,gFAAgF;AAChF,MAAM,WAAW,iBAAiB,CAAC,MAAM,SAAS,WAAW,GAAG,UAAU;IACxE,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,6DAA6D;IAC7D,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;QAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC,UAAU,CAAC,CAAC;CAC7D;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC,sEAAsE;IACtE,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,yEAAyE;IACzE,QAAQ,CAAC,MAAM,CAAC,EAAE,WAAW,CAAC;CAC/B;AAED,MAAM,WAAW,kBAAkB;IACjC;;;OAGG;IACH,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,6EAA6E;IAC7E,WAAW,CACT,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,kBAAkB,GAC3B,OAAO,CAAC,iBAAiB,CAAC,WAAW,CAAC,CAAC,CAAC;IAC3C,gBAAgB,CACd,KAAK,EAAE,WAAW,EAClB,OAAO,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,QAAQ,CAAC,GAC3C,OAAO,CAAC,iBAAiB,CAAC,UAAU,CAAC,CAAC,CAAC;IAC1C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,kBAAkB,CA4LpB;AAWD,6EAA6E;AAC7E,wBAAgB,SAAS,CAAC,CAAC,EACzB,IAAI,EAAE,OAAO,CAAC,CAAC,CAAC,EAChB,MAAM,EAAE,WAAW,GAAG,SAAS,cAuBhC"}

package/dist/render-preparation/depth/frame-window.d.ts

@@ -0,0 +1,146 @@
+import type { DepthMap } from "supervision-js-core";
+import type { DepthPreviewDecodeOptions, DepthPreviewDecodeRun, DepthPreviewLumaFrame } from "#media/depth-preview-track";
+import { type RenderPreparationArtifactDiagnostics, type ResolvedRenderPreparationGateThresholds } from "#types/render-preparation";
+/** One pass over a frame source, from where it was started forward. */
+export interface DepthFrameRun<Frame> {
+    /** The next frame, or null once the source has ended or the run was cancelled. */
+    next(): Promise<Frame | null>;
+    cancel(): void;
+}
+/**
+ * A video track decodes from a key frame forward; a source with
+ * `randomAccess` starts a run at any frame and skips the frames `keep`
+ * turns away at no cost, so one run serves every frame ahead of it.
+ */
+export interface DepthFrameSource<Frame extends {
+    readonly index: number;
+} = DepthPreviewLumaFrame> {
+    readonly frameCount: number;
+    readonly randomAccess?: boolean;
+    keyIndexAtOrBefore(index: number): number;
+    decode(fromIndex: number, options: DepthPreviewDecodeOptions): DepthFrameRun<Frame> | DepthPreviewDecodeRun;
+}
+export interface DepthWindowEntry {
+    readonly index: number;
+    readonly map: DepthMap;
+    readonly bytes: number;
+}
+export interface DepthFrameWindowOptions<Frame extends {
+    readonly index: number;
+} = DepthPreviewLumaFrame> {
+    readonly frames: DepthFrameSource<Frame>;
+    /** Start of frame `index` on the media timeline, in seconds. */
+    readonly timeAt: (index: number) => number;
+    /** End of frame `index` on the media timeline, in seconds. */
+    readonly endAt: (index: number) => number;
+    readonly createMap: (frame: Frame) => DepthMap;
+    /**
+     * Bytes one decoded frame is expected to hold; sets how many frames fit in
+     * `maxBytes`.
+     */
+    readonly frameBytes: number;
+    /**
+     * For frames that differ in size. Defaults to the frame's `luma` length,
+     * then `frameBytes`.
+     */
+    readonly bytesOf?: (frame: Frame) => number;
+    /** Names the frames in errors and warnings. Defaults to "preview". */
+    readonly precision?: "exact" | "preview";
+    /** What playback draws once the window stops, for its stop message. */
+    readonly stillDrawn: () => string;
+    /** Budget for decoded frames, in bytes. */
+    readonly maxBytes: number;
+    /**
+     * How far ahead of the playhead to decode while playing, in seconds of
+     * media; a drag spends the same span both ways.
+     */
+    readonly prefetchSeconds: number;
+    /** How much behind the playhead to keep, in seconds of media. */
+    readonly retainSeconds: number;
+    /**
+     * Frames a resting playhead keeps decoded ahead, its own included, so a
+     * step forward lands on a decoded frame.
+     */
+    readonly pausedFrameCount: number;
+    readonly loop?: boolean;
+    /** A frame was decoded and kept. */
+    readonly onFrame?: (index: number) => void;
+    /** What the window holds or waits for changed. */
+    readonly onChange?: () => void;
+}
+export interface DepthFrameWindow {
+    getEntry(index: number): DepthWindowEntry | null;
+    /**
+     * The playhead moved to `index`: decoding follows it, and its moves give
+     * the heading and, while playing, how many frames each present moves.
+     */
+    setPlayhead(index: number): void;
+    /**
+     * Whether playback runs or a drag moves the playhead. A resting playhead
+     * keeps only a small margin decoded ahead of it.
+     */
+    setPlaybackActive(active: boolean): void;
+    /**
+     * Whether a drag holds the playhead. A slow drag forward moves it the way
+     * playback does; this is what tells the two apart.
+     */
+    setScrubbing(scrubbing: boolean): void;
+    setLoop(loop: boolean): void;
+    /** A hidden page decodes nothing and starts no run until it is shown. */
+    setHidden(hidden: boolean): void;
+    /** Which way the playhead travels: 1, -1, or 0 without enough to say. */
+    heading(): -1 | 0 | 1;
+    /**
+     * Seconds of decoded frames from the start of `index` onward that the
+     * next presents land on, without a gap; Infinity once that run reaches
+     * the last frame of a clip that does not loop.
+     */
+    leadSeconds(index: number): number;
+    needsPlaybackGateWait(index: number, thresholds: ResolvedRenderPreparationGateThresholds): boolean;
+    waitForReady(index: number, thresholds: ResolvedRenderPreparationGateThresholds, signal?: AbortSignal): Promise<void>;
+    /** Frames decoded and kept, counted up across the window's life. */
+    getPreparationProgress(): number;
+    /**
+     * Decoded entries for `count` frames in a row from `skip` frames after
+     * `index`, nearest first, stopping at the first one not decoded.
+     */
+    upcoming(index: number, count: number, skip?: number): DepthWindowEntry[];
+    getDiagnostics(): RenderPreparationArtifactDiagnostics;
+    /**
+     * The most lead the window decodes ahead of `index` while playing, in
+     * seconds of media; Infinity where that reaches the end of a clip that
+     * does not loop.
+     */
+    wantedLeadSeconds(index: number): number;
+    /** The decoder failed; the window stops waiting and decoding. */
+    readonly failure: unknown;
+    /** Why the window stopped and what playback draws now, or null. */
+    readonly stopMessage: string | null;
+    destroy(): void;
+}
+/**
+ * Decoded depth frames around the playhead, by frame index.
+ *
+ * One decode run is active at a time; it starts at the frame it is for, or
+ * at the key frame before it on a source without random access. What the
+ * window wants decoded follows how the playhead moves:
+ *
+ * - Playing, it leads the playhead by `prefetchSeconds` times how many frames
+ *   presents move, wrapping at the last frame when the clip loops. Once every
+ *   recent present has moved the same number of frames, it keeps only the
+ *   frames presents land on.
+ * - Dragged, it spends `prefetchSeconds` both ways, most of it the way the
+ *   playhead heads. Dragged backwards, a run from a key frame keeps every
+ *   frame up to the playhead, so the frames the hand reaches next are there.
+ * - Resting, it keeps a small margin ahead; stepping backwards fills behind.
+ *
+ * A frame the playback gate waits on is decoded before anything else. When
+ * the budget is short, frames the window no longer wants go first, then the
+ * ones farthest the other way from where the playhead heads. The frame at the
+ * playhead and the ones the gate waits on or just let through stay, over the
+ * budget if they must.
+ */
+export declare function createDepthFrameWindow<Frame extends {
+    readonly index: number;
+} = DepthPreviewLumaFrame>(options: DepthFrameWindowOptions<Frame>): DepthFrameWindow;
+//# sourceMappingURL=frame-window.d.ts.map

package/dist/render-preparation/depth/frame-window.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-window.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/frame-window.ts"],"names":[],"mappings":"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"}

package/dist/render-preparation/depth/options.d.ts

@@ -0,0 +1,37 @@
+import type { DepthPlaybackSource, RenderPreparationDepthOptions } from "#types/render-preparation";
+export interface DepthClipOptions {
+    /** Exact frames loaded around the frame at rest. */
+    readonly exact: {
+        readonly settleSeconds: number;
+        readonly neighborFrameCount: number;
+        /** The frame on screen is always kept, whatever this says. */
+        readonly maxCacheBytes: number;
+    };
+    readonly playback: {
+        readonly source: DepthPlaybackSource;
+        readonly maxExactCacheBytes: number;
+    };
+    /** What the preview window, and the exact playback window, decode ahead. */
+    readonly preview: {
+        readonly maxCacheBytes: number;
+        /** Frames a resting playhead keeps decoded ahead, its own included. */
+        readonly pausedFrameCount: number;
+        readonly prefetchSeconds: number;
+        readonly retainSeconds: number;
+    };
+}
+/**
+ * The clip's budgets and timing. Byte budgets that are not given scale with
+ * the clip's resolution, so a 4K clip keeps about as many seconds as a 720p
+ * one.
+ */
+export declare function resolveDepthClipOptions(clip: {
+    /** Its confidence plane included. */
+    readonly exactFrameBytes: number;
+    /** 0 without a preview. */
+    readonly previewFrameBytes: number;
+    readonly frameRate: number;
+}, options?: RenderPreparationDepthOptions, shared?: {
+    readonly scheduleBatchSize?: number;
+}): DepthClipOptions;
+//# sourceMappingURL=options.d.ts.map

package/dist/render-preparation/depth/options.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"options.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/options.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,mBAAmB,EACnB,6BAA6B,EAC9B,MAAM,2BAA2B,CAAC;AAkBnC,MAAM,WAAW,gBAAgB;IAC/B,oDAAoD;IACpD,QAAQ,CAAC,KAAK,EAAE;QACd,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;QACpC,8DAA8D;QAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;KAChC,CAAC;IACF,QAAQ,CAAC,QAAQ,EAAE;QACjB,QAAQ,CAAC,MAAM,EAAE,mBAAmB,CAAC;QACrC,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;KACrC,CAAC;IACF,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;QAC/B,uEAAuE;QACvE,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;QAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;QACjC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;KAChC,CAAC;CACH;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,IAAI,EAAE;IACJ,qCAAqC;IACrC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,2BAA2B;IAC3B,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B,EACD,OAAO,GAAE,6BAAkC,EAC3C,MAAM,GAAE;IAAE,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAAO,GACnD,gBAAgB,CAsDlB"}

package/dist/render-preparation/depth/png16.d.ts

@@ -0,0 +1,40 @@
+/** A decoded 16-bit grayscale PNG, samples in host byte order. */
+export interface DecodedPng16 {
+    readonly width: number;
+    readonly height: number;
+    readonly values: Uint16Array<ArrayBuffer>;
+    /**
+     * The samples as `rg8` texture bytes with every row padded to a multiple of
+     * four bytes, present only when padding was asked for and the width is odd.
+     */
+    readonly paddedUpload?: {
+        readonly bytes: Uint8Array<ArrayBuffer>;
+        readonly textureWidth: number;
+    };
+}
+export interface DecodedPng8 {
+    readonly width: number;
+    readonly height: number;
+    readonly values: Uint8Array<ArrayBuffer>;
+}
+/**
+ * Inflates a zlib stream split over `chunks` into exactly `byteLength` bytes.
+ * A PNG's IDAT chunks, joined, are one zlib stream.
+ */
+export type PngInflate = (chunks: readonly Uint8Array[], byteLength: number) => Promise<Uint8Array>;
+export interface DecodePng16Options {
+    readonly inflate?: PngInflate;
+    /** Also return WebGL-aligned upload bytes when the width is odd. */
+    readonly padRowsForWebGl?: boolean;
+}
+export declare function decodePng16(bytes: ArrayBuffer | Uint8Array, options?: DecodePng16Options): Promise<DecodedPng16>;
+export declare function decodePng8Gray(bytes: ArrayBuffer | Uint8Array, options?: {
+    readonly inflate?: PngInflate;
+}): Promise<DecodedPng8>;
+/**
+ * Inflates with the platform's `DecompressionStream("deflate")` (zlib
+ * framing, which is what PNG uses) straight into one buffer of the expected
+ * size, so no second copy joins the output chunks.
+ */
+export declare function inflateWithDecompressionStream(chunks: readonly Uint8Array[], byteLength: number): Promise<Uint8Array>;
+//# sourceMappingURL=png16.d.ts.map

package/dist/render-preparation/depth/png16.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"png16.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/png16.ts"],"names":[],"mappings":"AAYA,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAC1C;;;OAGG;IACH,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;QACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;CACH;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,MAAM,EAAE,UAAU,CAAC,WAAW,CAAC,CAAC;CAC1C;AAED;;;GAGG;AACH,MAAM,MAAM,UAAU,GAAG,CACvB,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,UAAU,EAAE,MAAM,KACf,OAAO,CAAC,UAAU,CAAC,CAAC;AAEzB,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAC;IAC9B,oEAAoE;IACpE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;CACpC;AAOD,wBAAsB,WAAW,CAC/B,KAAK,EAAE,WAAW,GAAG,UAAU,EAC/B,OAAO,GAAE,kBAAuB,GAC/B,OAAO,CAAC,YAAY,CAAC,CAqBvB;AAED,wBAAsB,cAAc,CAClC,KAAK,EAAE,WAAW,GAAG,UAAU,EAC/B,OAAO,GAAE;IAAE,QAAQ,CAAC,OAAO,CAAC,EAAE,UAAU,CAAA;CAAO,GAC9C,OAAO,CAAC,WAAW,CAAC,CAatB;AAED;;;;GAIG;AACH,wBAAsB,8BAA8B,CAClD,MAAM,EAAE,SAAS,UAAU,EAAE,EAC7B,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CAuCrB"}

package/dist/render-preparation/depth/preview-luma-copier.d.ts

@@ -0,0 +1,12 @@
+import type { DepthPreviewLumaCopier } from "./preview-luma";
+import { type RenderPreparationOptions } from "#types/render-preparation";
+export type { DepthPreviewLumaCopier };
+/**
+ * Hands each frame to a render-preparation worker of its own, which copies
+ * its luma and closes it; the page only posts the frame and takes the bytes
+ * back. A browser that cannot send a frame to a worker, or a worker that
+ * fails, leaves this and every later frame to the page, unless the mode
+ * requires the worker.
+ */
+export declare function createDepthPreviewLumaCopier(options: RenderPreparationOptions | undefined): DepthPreviewLumaCopier;
+//# sourceMappingURL=preview-luma-copier.d.ts.map

package/dist/render-preparation/depth/preview-luma-copier.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-luma-copier.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/preview-luma-copier.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAoB,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,EAEL,KAAK,wBAAwB,EAC9B,MAAM,2BAA2B,CAAC;AAMnC,YAAY,EAAE,sBAAsB,EAAE,CAAC;AAEvC;;;;;;GAMG;AACH,wBAAgB,4BAA4B,CAC1C,OAAO,EAAE,wBAAwB,GAAG,SAAS,GAC5C,sBAAsB,CA+FxB"}

package/dist/render-preparation/depth/preview-luma.d.ts

@@ -0,0 +1,48 @@
+/** How the decoded pixels reached the luma codes. */
+export type DepthPreviewLumaPath = 
+/** The decoder's own luma plane: the codes exactly as decoded. */
+"plane"
+/**
+ * The browser converted the frame to RGB first, and the green channel
+ * stands in for luma. A range or matrix conversion can move codes.
+ */
+ | "rgb";
+/** One decoded preview frame's luma, one byte per map pixel. */
+export interface DepthPreviewLuma {
+    readonly luma: Uint8Array;
+    readonly width: number;
+    readonly height: number;
+    readonly path: DepthPreviewLumaPath;
+}
+/** A buffer reused from one copy to the next, grown as needed. */
+export interface DepthPreviewLumaScratch {
+    buffer: ArrayBuffer;
+}
+/**
+ * Copies a decoded preview frame's luma codes out of it, mapped through
+ * `correction` when one is given. The frame stays open; its owner closes
+ * it.
+ */
+export declare function readVideoFrameLuma(frame: VideoFrame, scratch: DepthPreviewLumaScratch, correction?: Uint8Array | null): Promise<DepthPreviewLuma>;
+/** Copies decoded preview frames' luma out, wherever that costs least. */
+export interface DepthPreviewLumaCopier {
+    /**
+     * Takes the frame and closes it once its luma is out; the promise answers
+     * null when the frame was lost on the way, handed to a worker that then
+     * failed. Answers null itself, synchronously and leaving the frame
+     * untouched, when it cannot take the frame: the page copies it instead.
+     */
+    copy(frame: VideoFrame, correction: Uint8Array | null): Promise<DepthPreviewLuma | null> | null;
+    readonly offMainThread: boolean;
+    destroy(): void;
+}
+/** A copier that never declines: the page always takes the frame. */
+export interface MainThreadLumaCopier extends DepthPreviewLumaCopier {
+    copy(frame: VideoFrame, correction: Uint8Array | null): Promise<DepthPreviewLuma>;
+}
+/**
+ * Copies on the page, one frame at a time through one scratch buffer. Each
+ * copy reports the main-thread time it took.
+ */
+export declare function createMainThreadLumaCopier(): MainThreadLumaCopier;
+//# sourceMappingURL=preview-luma.d.ts.map

package/dist/render-preparation/depth/preview-luma.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"preview-luma.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/preview-luma.ts"],"names":[],"mappings":"AAYA,qDAAqD;AACrD,MAAM,MAAM,oBAAoB;AAC9B,kEAAkE;AAChE,OAAO;AACT;;;GAGG;GACD,KAAK,CAAC;AAEV,gEAAgE;AAChE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC;AAED,kEAAkE;AAClE,MAAM,WAAW,uBAAuB;IACtC,MAAM,EAAE,WAAW,CAAC;CACrB;AAED;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,KAAK,EAAE,UAAU,EACjB,OAAO,EAAE,uBAAuB,EAChC,UAAU,GAAE,UAAU,GAAG,IAAW,GACnC,OAAO,CAAC,gBAAgB,CAAC,CA4D3B;AAED,0EAA0E;AAC1E,MAAM,WAAW,sBAAsB;IACrC;;;;;OAKG;IACH,IAAI,CACF,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,UAAU,GAAG,IAAI,GAC5B,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG,IAAI,CAAC;IAC3C,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,qEAAqE;AACrE,MAAM,WAAW,oBAAqB,SAAQ,sBAAsB;IAClE,IAAI,CACF,KAAK,EAAE,UAAU,EACjB,UAAU,EAAE,UAAU,GAAG,IAAI,GAC5B,OAAO,CAAC,gBAAgB,CAAC,CAAC;CAC9B;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,oBAAoB,CAoBjE"}

package/dist/render-preparation/depth/source.d.ts

@@ -0,0 +1,123 @@
+import { type DepthMap, type DepthPreviewLevels } from "supervision-js-core";
+import type { DepthPreviewDecoding } from "#media/depth-preview-probe";
+import type { DepthPreviewTrackOptions, DepthPreviewTrackReader } from "#media/depth-preview-track";
+import type { MediaFrameClock } from "#types/media-frame-clock";
+import type { MediaRendererDepthInput } from "#types/media-depth";
+import type { RenderPreparationDepthOptions, RenderPreparationDiagnostics, RenderPreparationMaskFrameOptions, ResolvedRenderPreparationGateThresholds } from "#types/render-preparation";
+import type { DepthFramePreparer } from "./frame-preparer";
+import type { DepthPreviewLumaCopier } from "./preview-luma";
+/** One depth map ready to draw, and which frame of depth it is. */
+export interface DepthFrameEntry {
+    readonly map: DepthMap;
+    readonly frameIndex: number | null;
+}
+/** What the depth layer reads to find the map for a media time. */
+export interface DepthFrameProvider {
+    /**
+     * The depth to draw over the frame at `mediaTime`, or null to draw none.
+     * The layer asks only for the frame it is drawing, so a clip takes each
+     * call as naming the frame on screen.
+     */
+    getEntry(mediaTime: number): DepthFrameEntry | null;
+    /**
+     * Whether playback runs or a drag is still moving. A clip fetches exact
+     * frames only once this has been false for a moment, and draws its preview
+     * until then.
+     */
+    setPlaybackActive?(active: boolean): void;
+    /** Whether a drag, not playback, holds the playhead. */
+    setScrubbing?(scrubbing: boolean): void;
+    /** Whether playback wraps at the media end: decoding ahead wraps with it. */
+    setLoop?(loop: boolean): void;
+    /** Calls `listener` whenever an answer of `getEntry` may have changed. */
+    subscribe?(listener: () => void): () => void;
+    /** The playhead moved: decoding ahead follows it. Never called in a present. */
+    prefetch?(mediaTime: number): void;
+    /**
+     * The entries the next presents may draw, nearest first, so their
+     * textures can go up before those presents: `count` frames in a row from
+     * `skip` frames after the one at `mediaTime`. Above 1x a present skips
+     * frames, and `skip` is how many it last moved.
+     */
+    getUpcomingEntries?(mediaTime: number, count: number, skip?: number): readonly DepthFrameEntry[];
+    /** Whether the frame at `mediaTime` has to wait for depth before it shows. */
+    needsPlaybackGateWait?(mediaTime: number, thresholds: ResolvedRenderPreparationGateThresholds): boolean;
+    /** Resolves once depth leads `mediaTime` as far as the thresholds ask. */
+    waitForReady?(mediaTime: number, thresholds: ResolvedRenderPreparationGateThresholds, signal?: AbortSignal): Promise<void>;
+    /** Depth frames prepared ahead, counted up across the source's life. */
+    getPreparationProgress?(): number;
+    /**
+     * The depth frame `getEntry` answers for `mediaTime`, without drawing it,
+     * and whether it is decoded yet. Null where there is no depth frame.
+     */
+    getFrameStatus?(mediaTime: number): {
+        readonly frameIndex: number | null;
+        readonly prepared: boolean;
+    } | null;
+    destroy(): void;
+}
+export interface DepthSourceContext {
+    /** The media the map is stretched over. */
+    readonly media: {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * The media's frame index. A clip needs it to pair each depth frame with
+     * the video frame it measures.
+     */
+    readonly frameClock?: MediaFrameClock | null;
+    /**
+     * Reads the frame index for media that does not keep one, the first time
+     * a clip asks: a Mediabunny URL or Blob.
+     */
+    readonly readFrameClock?: (() => Promise<MediaFrameClock>) | null;
+    /** Why the media has no frame index, told to a clip that needs one. */
+    readonly frameClockUnavailableReason?: string;
+    /** The decoder, created only when a manifest needs one. */
+    readonly preparer?: () => DepthFramePreparer;
+    readonly fetch?: typeof globalThis.fetch;
+    /** Pad odd-width rows for WebGL while decoding, off the main thread. */
+    readonly padRowsForWebGl?: boolean;
+    /**
+     * The box the picture is shown in. Exact depth at least twice the size the
+     * box shows at its pixel ratio is uploaded shrunk by that whole factor,
+     * prepared while decoding; readouts keep the full map.
+     */
+    readonly display?: RenderPreparationMaskFrameOptions["display"];
+    readonly signal?: AbortSignal;
+    readonly depth?: RenderPreparationDepthOptions;
+    /**
+     * The mask window's schedule batch, which also sizes what the preview keeps
+     * at rest: masks and depth keep the same margin ahead of a paused frame.
+     */
+    readonly scheduleBatchSize?: number;
+    /**
+     * Opens a clip's preview video; null leaves the preview out. Defaults to
+     * the WebCodecs decoder, loaded on first use.
+     */
+    readonly openPreviewTrack?: ((url: string, options?: DepthPreviewTrackOptions) => Promise<DepthPreviewTrackReader>) | null;
+    /**
+     * Copies decoded preview frames' luma out, made when a preview first opens:
+     * the session's render-preparation worker keeps those copies off the page.
+     * Without one, they run on the page.
+     */
+    readonly previewLumaCopier?: () => DepthPreviewLumaCopier;
+    /**
+     * Picks, once per page and level, the decoder that returns preview codes
+     * as written; null skips the probe and leaves the choice to the browser.
+     */
+    readonly choosePreviewDecoding?: ((levels: DepthPreviewLevels) => Promise<DepthPreviewDecoding>) | null;
+    /** Hears the preview window's state: its lead, frames held and gate holds. */
+    readonly onDiagnostics?: (diagnostics: RenderPreparationDiagnostics) => void;
+}
+/**
+ * Checks a depth input against the media it will be drawn over and opens it.
+ * A still map, given or loaded from an image manifest, answers every media
+ * time with itself. A clip manifest answers with the exact frame for the
+ * video frame on screen once playback rests.
+ */
+export declare function openDepthSource(input: MediaRendererDepthInput, context: DepthSourceContext): Promise<DepthFrameProvider>;
+/** Rejects an input whose shape no renderer could draw, before any media opens. */
+export declare function validateDepthInput(input: MediaRendererDepthInput): void;
+//# sourceMappingURL=source.d.ts.map

package/dist/render-preparation/depth/source.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"source.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/source.ts"],"names":[],"mappings":"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"}

package/dist/render-preparation/depth/worker-protocol.d.ts

@@ -0,0 +1,76 @@
+import type { DepthPreviewLumaPath } from "./preview-luma";
+/**
+ * Messages between the depth source and the render-preparation worker, which
+ * decodes depth and confidence PNGs, and copies decoded preview frames' luma,
+ * off the main thread. Internal: the worker script is a deployment asset, and
+ * its protocol is not public.
+ */
+export declare enum DepthPreparationWorkerMessageType {
+    Decode = "depth-decode",
+    Complete = "depth-decode-complete",
+    Error = "depth-decode-error",
+    PreviewLuma = "depth-preview-luma",
+    PreviewLumaComplete = "depth-preview-luma-complete"
+}
+/** A decoded preview frame, transferred to the worker, which closes it. */
+export interface DepthPreviewLumaWorkerRequest {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.PreviewLuma;
+    readonly frame: VideoFrame;
+    readonly correction: Uint8Array | null;
+}
+export type DepthPreviewLumaWorkerResponse = {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.PreviewLumaComplete;
+    /** One byte per pixel, transferred. */
+    readonly luma: ArrayBuffer;
+    readonly width: number;
+    readonly height: number;
+    readonly path: DepthPreviewLumaPath;
+} | {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.Error;
+    readonly error: string;
+};
+export interface DepthPreparationWorkerRequest {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.Decode;
+    /** The PNG file's bytes, transferred once the worker has proven itself. */
+    readonly bytes: ArrayBuffer;
+    /** 16 for depth samples, 8 for a confidence plane. */
+    readonly bitDepth: 16 | 8;
+    /** Also return odd-width depth rows padded for a WebGL upload. */
+    readonly padRowsForWebGl?: boolean;
+    /**
+     * Also return depth decimated by this whole factor for upload, when it is
+     * 2 or more: the texture the box shows, beside the full samples a readout
+     * reads.
+     */
+    readonly decimateBy?: number;
+}
+export type DepthPreparationWorkerResponse = {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.Complete;
+    readonly bitDepth: 16 | 8;
+    readonly width: number;
+    readonly height: number;
+    /** Host-order Uint16 samples at 16 bits, bytes at 8, transferred. */
+    readonly values: ArrayBuffer;
+    readonly paddedUpload?: {
+        readonly bytes: ArrayBuffer;
+        readonly textureWidth: number;
+    };
+    readonly decimatedUpload?: DecimatedDepthUpload<ArrayBuffer>;
+} | {
+    readonly requestId: number;
+    readonly type: DepthPreparationWorkerMessageType.Error;
+    readonly error: string;
+};
+/** Depth decimated for upload: two bytes a texel, low byte first, rows padded as asked. */
+export interface DecimatedDepthUpload<Bytes extends ArrayBuffer | Uint8Array> {
+    readonly bytes: Bytes;
+    readonly width: number;
+    readonly height: number;
+    readonly textureWidth: number;
+}
+//# sourceMappingURL=worker-protocol.d.ts.map

package/dist/render-preparation/depth/worker-protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"worker-protocol.d.ts","sourceRoot":"","sources":["../../../src/render-preparation/depth/worker-protocol.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;GAKG;AACH,oBAAY,iCAAiC;IAC3C,MAAM,iBAAiB;IACvB,QAAQ,0BAA0B;IAClC,KAAK,uBAAuB;IAC5B,WAAW,uBAAuB;IAClC,mBAAmB,gCAAgC;CACpD;AAED,2EAA2E;AAC3E,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,WAAW,CAAC;IAC7D,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC;IAC3B,QAAQ,CAAC,UAAU,EAAE,UAAU,GAAG,IAAI,CAAC;CACxC;AAED,MAAM,MAAM,8BAA8B,GACtC;IACE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,mBAAmB,CAAC;IACrE,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;CACrC,GACD;IACE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,KAAK,CAAC;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEN,MAAM,WAAW,6BAA6B;IAC5C,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,MAAM,CAAC;IACxD,2EAA2E;IAC3E,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1B,kEAAkE;IAClE,QAAQ,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC;IACnC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,MAAM,8BAA8B,GACtC;IACE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,QAAQ,CAAC;IAC1D,QAAQ,CAAC,QAAQ,EAAE,EAAE,GAAG,CAAC,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC;IAC7B,QAAQ,CAAC,YAAY,CAAC,EAAE;QACtB,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;QAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;KAC/B,CAAC;IACF,QAAQ,CAAC,eAAe,CAAC,EAAE,oBAAoB,CAAC,WAAW,CAAC,CAAC;CAC9D,GACD;IACE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,IAAI,EAAE,iCAAiC,CAAC,KAAK,CAAC;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB,CAAC;AAEN,2FAA2F;AAC3F,MAAM,WAAW,oBAAoB,CAAC,KAAK,SAAS,WAAW,GAAG,UAAU;IAC1E,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B"}

package/dist/render-preparation/playhead-motion.d.ts

@@ -0,0 +1,67 @@
+/**
+ * How the playhead is moving, read from where it lands: playing forward at a
+ * cadence, dragged, or stepped, and which way. Every prepared window that
+ * works ahead of the playhead reads it here, so a drag or a fast rate reads
+ * the same to each.
+ */
+/** The widest stride a present is taken to move: 8x of a 30 fps clip on 60 Hz. */
+export declare const MAX_PRESENTED_FRAME_STRIDE = 4;
+/**
+ * Share of a window spent the way the playhead is heading, as the engine's
+ * scrub window spends it. The rest covers the ground just behind, which is
+ * what a reversal lands on before the new heading is established.
+ */
+export declare const WINDOW_LEAD_FRACTION = 0.75;
+export interface PlayheadMotion {
+    /**
+     * The playhead landed at `position`. `settledAdvance` is the widest
+     * forward step playback makes, in the same unit; a move past it, or any
+     * move back, is a jump.
+     */
+    observe(position: number, settledAdvance: number): void;
+    /**
+     * False while the playhead is dragged: it jumped twice in a row. A single
+     * jump is a seek that lands, and the window may lead it at once.
+     */
+    readonly settled: boolean;
+    /** Which way the playhead travels: 1, -1, or 0 without enough to say. */
+    heading(): -1 | 0 | 1;
+    /** Playback started or stopped: the gesture that moved the playhead is over. */
+    endGesture(): void;
+}
+export declare function createPlayheadMotion(now?: () => number): PlayheadMotion;
+/**
+ * How many frames each present moves, from the last few that moved. A
+ * cadence counts only once it has repeated, which is what separates it from
+ * a seek.
+ */
+export interface PresentedFrameStride {
+    observe(step: number): void;
+    /** The narrowest of the repeated strides, 1 until there are enough. */
+    narrowest(): number;
+    /** How far presents move on average, 1 until there are enough. */
+    average(): number;
+    /**
+     * The stride every recent present moved, or 1 when they differ: a cadence
+     * that alternates lands on frames no single stride names.
+     */
+    uniform(): number;
+    reset(): void;
+}
+/**
+ * `sampleCount` is how many moves a cadence has to repeat over. A cadence
+ * that is not a whole number of frames, 3.2 at 8x of 24 fps on 60 Hz, moves
+ * 3, 3, 3, 3 and then 4, so a reading that skips frames on it needs more
+ * than four moves to see that.
+ */
+export declare function createPresentedFrameStride(sampleCount?: number): PresentedFrameStride;
+/**
+ * The playhead's own frame plus one schedule batch ahead. A batch is the most
+ * a window commits to in one pass, so a resting playhead holds a single pass
+ * of work, and a step forward still lands on a frame already prepared.
+ */
+export declare function getPausedPreparedWindowFrameCount(options: {
+    readonly prefetchFrameCount: number;
+    readonly scheduleBatchSize: number;
+}): number;
+//# sourceMappingURL=playhead-motion.d.ts.map

package/dist/render-preparation/playhead-motion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"playhead-motion.d.ts","sourceRoot":"","sources":["../../src/render-preparation/playhead-motion.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH,kFAAkF;AAClF,eAAO,MAAM,0BAA0B,IAAI,CAAC;AAS5C;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,OAAO,CAAC;AAEzC,MAAM,WAAW,cAAc;IAC7B;;;;OAIG;IACH,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IACxD;;;OAGG;IACH,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;IAC1B,yEAAyE;IACzE,OAAO,IAAI,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACtB,gFAAgF;IAChF,UAAU,IAAI,IAAI,CAAC;CACpB;AAED,wBAAgB,oBAAoB,CAClC,GAAG,GAAE,MAAM,MAAgC,GAC1C,cAAc,CA+EhB;AAED;;;;GAIG;AACH,MAAM,WAAW,oBAAoB;IACnC,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,uEAAuE;IACvE,SAAS,IAAI,MAAM,CAAC;IACpB,kEAAkE;IAClE,OAAO,IAAI,MAAM,CAAC;IAClB;;;OAGG;IACH,OAAO,IAAI,MAAM,CAAC;IAClB,KAAK,IAAI,IAAI,CAAC;CACf;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CACxC,WAAW,SAAsC,GAChD,oBAAoB,CAqBtB;AAED;;;;GAIG;AACH,wBAAgB,iCAAiC,CAAC,OAAO,EAAE;IACzD,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;IACpC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;CACpC,UAEA"}

package/dist/render-preparation/prepared-render-window.d.ts

@@ -5,6 +5,11 @@ import { type BufferedDetectionTimeline } from "supervision-js-core";
 import type { DetectionFrame } from "supervision-js-core";
 import type { MaskStyle } from "supervision-js-core";
 import { RenderPreparationArtifactKind, type RenderPreparationOptions, type ResolvedRenderPreparationGateThresholds } from "#types/render-preparation";
+export declare enum PreparedRasterTier {
+    Coarse = "coarse",
+    Fine = "fine"
+}
+export declare const DEFAULT_MASK_SCHEDULE_BATCH_SIZE = 2;
 export interface PreparedRenderFrame {
     readonly detectionFrame: DetectionFrame;
     readonly key: string;
@@ -19,6 +24,10 @@ export declare enum PreparedRenderFrameMaskStatus {
 }
 export interface PreparedRenderWindow {
     getFrame(mediaTime: number): PreparedRenderFrame | undefined;
+    /** Revision of the prepared artifact, including replacements at the same time. */
+    getArtifactRevision(mediaTime: number): number;
+    /** Recooks the active frame and its targets after the display raster size changes. */
+    invalidateRasterSize(): void;
     /**
      * Whether this window's artifact for a media time is cooked, scheduling
      * nothing. True when there is nothing to cook: no style, no frame there.
@@ -65,6 +74,9 @@ export declare function createPreparedRenderWindow(options: {
     readonly detectionTimeline: BufferedDetectionTimeline;
     readonly maskStyle?: MaskStyle | null;
     readonly maxMaskFrameCacheSize?: number;
+    readonly maxMaskFrameCacheBytes?: number;
+    /** Reserves renderer backing before a prepared frame can be drawn. */
+    readonly resolveMaskFrameBackingBytes?: (frame: PreparedMaskFrame) => number;
     readonly onMaskFrameEvicted?: (key: string) => void;
     readonly onMaskFramePrepared?: (maskFrame: PreparedMaskFrame) => void;
     readonly onMaskFramesCleared?: () => void;