supervision 0.1.7 → 0.2.0-next.0

package/dist/web-video-engine/frame-cache.d.ts

@@ -0,0 +1,129 @@
+/**
+ * Two-tier frame cache, keyed by millisecond timestamp.
+ *
+ * The preview tier holds many downscaled frames: a long, coarse history that
+ * answers a scrub instantly while the crisp frame decodes. The exact tier holds
+ * a few full-resolution frames, bounded by a RAM budget rather than a fixed
+ * count so the slot count tracks frame size.
+ *
+ * A lookup prefers exact, then preview, tagging the hit with the tier that
+ * served it. Only an exact hit is full-resolution; a preview hit still owes the
+ * caller a crisp decode.
+ *
+ * Both tiers store OffscreenCanvas blits, never VideoFrames: a raw-frame cache
+ * pins decoder output, stalling the decoder and growing VRAM without bound. A
+ * frame fed as a live VideoSample is drawn into the blit and never retained, so
+ * the no-retention rule holds on the zero-copy path too.
+ */
+import type { VideoSampleLike } from "./scrub-cursor";
+/**
+ * What the cache can blit into a tier: an already-decoded canvas/image, or a
+ * live VideoSample it draws once and never retains. The sample's draw scales to
+ * the tier size just like drawImage does, so the stored blit is identical either
+ * way.
+ */
+export type CacheBlitSource = CanvasImageSource | VideoSampleLike;
+export declare enum FrameTier {
+    Exact = "exact",
+    Preview = "preview"
+}
+export interface CachedFrame {
+    readonly canvas: OffscreenCanvas;
+    readonly timestampMs: number;
+    readonly tier: FrameTier;
+}
+export interface FrameCacheStats {
+    readonly exactHits: number;
+    readonly previewHits: number;
+    readonly misses: number;
+    readonly exactSize: number;
+    readonly previewSize: number;
+    readonly exactCapacity: number;
+    readonly previewCapacity: number;
+    /** True timestamps (ms) currently resident in each tier, for the diagnostics
+     *  timeline. Bounded by capacity, so a small array per poll. */
+    readonly exactTimestampsMs: number[];
+    readonly previewTimestampsMs: number[];
+    /** Configured source frame interval: the visual width of each cached mark on
+     *  the timeline. Keys are per-millisecond, so this is a display width and
+     *  not the grid entries land on. */
+    readonly bucketMs: number;
+    /** Frames dropped to LRU pressure per tier, and puts that landed in an
+     *  occupied bucket (re-decodes collapsed onto one slot). */
+    readonly exactEvictions: number;
+    readonly previewEvictions: number;
+    readonly bucketCollapses: number;
+    /** Per-tier frame dimensions and the crisp tier's RAM ceiling, so a consumer
+     *  can derive resident bytes (size x w x h x 4) and the budget fill. */
+    readonly exactFrameWidth: number;
+    readonly exactFrameHeight: number;
+    readonly previewFrameWidth: number;
+    readonly previewFrameHeight: number;
+    readonly exactBudgetBytes: number;
+}
+export interface FrameCacheOptions {
+    /** Crisp-tier frame size, the cursor's decode resolution. */
+    readonly exactWidth: number;
+    readonly exactHeight: number;
+    /** Coarse-tier width; height derives from the exact aspect ratio. */
+    readonly previewWidth: number;
+    /** Crisp scrub-tier RAM ceiling in bytes; slot count derives from frame size. */
+    readonly exactBudgetBytes: number;
+    /** Coarse-tier slot count. */
+    readonly previewCapacity: number;
+    /** Source frame interval in ms, reported to diagnostics as the timeline mark
+     *  width. It does not key the tiers: a grid this wide rounds two adjacent
+     *  frames onto one slot wherever the rounded interval exceeds the true one
+     *  (24, 60fps and their pulldown rates), so each frame is keyed by its own
+     *  millisecond instead. */
+    readonly bucketMs: number;
+    /** Floor on exact-tier slots, applied even when the byte budget would yield
+     *  fewer. Lets a caller that owns the prefetch-window width guarantee a full
+     *  window fits regardless of frame size. The cache stays ignorant of the
+     *  window; it only honors the number it is handed. */
+    readonly minExactSlots?: number;
+}
+export declare class FrameCache {
+    private readonly exact;
+    private readonly preview;
+    private exactHits;
+    private previewHits;
+    private misses;
+    private readonly bucketMs;
+    private readonly exactBudgetBytes;
+    constructor(options: FrameCacheOptions);
+    /** Store a crisp full-resolution frame for the exact (scrub) tier. */
+    putExact(timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    /** Store a downscaled frame for the coarse preview tier. */
+    putPreview(timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    /**
+     * Best cached frame for `timestampMs`, consulting the exact tier then the
+     * preview tier: a crisp hit within `exactTolMs`, else a coarse hit within
+     * `previewTolMs`, else null. The two tolerances differ because the exact tier
+     * is keyed per source frame while the preview tier may only hold sparse
+     * keyframes.
+     *
+     * `exactTolMs` is an upper bound, not the reach: a crisp hit is also held to
+     * the frame span the exact tier has observed, since a tolerance wider than
+     * one frame (50ms is, at every rate from 24 to 60fps) would let a neighbour
+     * answer as the exact frame.
+     */
+    get(timestampMs: number, exactTolMs: number, previewTolMs: number): CachedFrame | null;
+    /**
+     * Same lookup as get() but without touching the hit/miss accounting. The
+     * synchronous render-loop peek and the authoritative seek both hit the cache
+     * for one user gesture; counting both double-books every scrub. The peek
+     * uses this so only the seek's get() is tallied, keeping the hit-rate a
+     * per-lookup rate rather than two-per-gesture.
+     */
+    peek(timestampMs: number, exactTolMs: number, previewTolMs: number): CachedFrame | null;
+    /**
+     * Marks the exact entry nearest `timestampMs` as most-recently-used without
+     * counting a hit. Lets the scheduler protect the just-shown center frame
+     * from being the LRU victim of its own neighbor sweep. No-op on a miss.
+     */
+    bumpExact(timestampMs: number): void;
+    clear(): void;
+    get stats(): FrameCacheStats;
+}
+//# sourceMappingURL=frame-cache.d.ts.map

package/dist/web-video-engine/frame-cache.d.ts.map

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

package/dist/web-video-engine/frame-extractor.d.ts

@@ -0,0 +1,28 @@
+import { AnalysisSession, type AnalysisOptions, type ExtractedFrame } from "./analysis-session";
+/**
+ * A second consumer of the runtime, built only on AnalysisSession's public
+ * surface, with no reach into the cursor, cache, worker, or render loop. Its
+ * existence is the proof that the analysis primitive is reusable: a thumbnail
+ * strip or contact sheet is just a choice of which timestamps to pull, and the
+ * open/close pair shows the full source lifecycle is reachable from the public
+ * API alone.
+ */
+export declare class FrameExtractor {
+    private readonly session;
+    constructor(session: AnalysisSession);
+    /** Opens a source and returns an extractor that owns it; close() disposes it. */
+    static open(options: AnalysisOptions): Promise<FrameExtractor>;
+    /** Frames at exactly the given timestamps (seconds). */
+    extractAt(timestampsS: readonly number[]): Promise<ExtractedFrame[]>;
+    /**
+     * `count` frames evenly spaced across the source, each sampled at the
+     * middle of its slice so neither the first black frame nor the exact end
+     * dominates the strip.
+     */
+    evenlySpaced(count: number): Promise<ExtractedFrame[]>;
+    /** One frame per keyframe in the range: a contact sheet that decodes cheaply. */
+    atKeyframes(startS?: number, endS?: number): Promise<ExtractedFrame[]>;
+    /** Disposes the underlying analysis session. */
+    close(): Promise<void>;
+}
+//# sourceMappingURL=frame-extractor.d.ts.map

package/dist/web-video-engine/frame-extractor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frame-extractor.d.ts","sourceRoot":"","sources":["../src/frame-extractor.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,eAAe,EACf,KAAK,eAAe,EACpB,KAAK,cAAc,EACpB,MAAM,oBAAoB,CAAC;AAE5B;;;;;;;GAOG;AACH,qBAAa,cAAc;IACb,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,eAAe;IAErD,iFAAiF;WACpE,IAAI,CAAC,OAAO,EAAE,eAAe,GAAG,OAAO,CAAC,cAAc,CAAC;IAIpE,wDAAwD;IACxD,SAAS,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAIpE;;;;OAIG;IACH,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAQtD,iFAAiF;IAC3E,WAAW,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,cAAc,EAAE,CAAC;IAK5E,gDAAgD;IAChD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAGvB"}