supervision 0.1.7 → 0.2.0-next.1

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

@@ -0,0 +1,236 @@
+/**
+ * Two-tier frame cache.
+ *
+ * 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.
+ *
+ * The exact tier is keyed by the timeline's identity for the frame, so two
+ * source frames can never share a slot at any frame rate. The preview tier is
+ * keyed by rounded millisecond, which merges frames spaced under a millisecond;
+ * it is the tier whose answer is already declared approximate, and it never
+ * claims to be the frame at the target.
+ *
+ * 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 { FrameId } from "./frame-timeline";
+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. Nothing is keyed by it, 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 overwrote a live
+     *  key: a frame decoded again on the exact tier, and on the preview tier
+     *  either that or two frames sharing one rounded millisecond. */
+    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 keys nothing. */
+    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 under
+     * `frame`, the timeline's name for it. `timestampMs` is the decoded
+     * timestamp, which is what lookups match on and what a hit reports back.
+     */
+    putExact(frame: FrameId, 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 answer for a named source frame. The exact tier is looked up
+     * only by `frame` identity; time is used solely for the approximate preview
+     * fallback. This keeps a long variable-rate frame from borrowing a crisp
+     * neighbour merely because both timestamps fit a millisecond tolerance.
+     */
+    getForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
+    /** Non-accounting form of {@link getForFrame}. */
+    peekForFrame(frame: FrameId, timestampMs: number, previewTolMs: number): CachedFrame | null;
+    /**
+     * 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;
+    /** Promotes one exact frame by identity. */
+    bumpExactFrame(frame: FrameId): void;
+    clear(): void;
+    get stats(): FrameCacheStats;
+}
+interface TierHit {
+    readonly canvas: OffscreenCanvas;
+    readonly timestampMs: number;
+}
+/**
+ * One cache tier: a fixed-capacity, MRU-ordered set of OffscreenCanvas copies
+ * under keys its owner assigns. A put onto a live key overwrites that slot in
+ * place, so an owner that lets two frames share a key loses one of them
+ * silently; overflow past capacity evicts the least-recently-used entry
+ * instead. Lookups match on the stored frame's true timestamp and never on the
+ * key, so a cache-served frame carries the same timestamp a fresh decode would.
+ */
+export declare class TierStore {
+    readonly capacity: number;
+    readonly width: number;
+    readonly height: number;
+    /** Width of the grid the owner's keys round onto, or 0 when a key names a
+     *  frame outright. Two entries closer together than this are one frame
+     *  whose two decodes rounded onto either side of a key boundary. */
+    private readonly keyGridMs;
+    /** MRU-ordered keys. Index 0 is the LRU, the last index is the MRU. */
+    private readonly keys;
+    private readonly entries;
+    /** Canvases released by eviction, held for the next put to fill. */
+    private readonly spare;
+    private evictionCount;
+    private bucketCollapseCount;
+    /** Smallest gap between two stored frames, which is the source frame interval
+     *  once neighbours are resident. Learned from the timestamps the tier is
+     *  handed, so it is what the source really did rather than a declared rate.
+     *  Null until two frames have landed. */
+    private observedIntervalMs;
+    constructor(capacity: number, width: number, height: number, 
+    /** Width of the grid the owner's keys round onto, or 0 when a key names a
+     *  frame outright. Two entries closer together than this are one frame
+     *  whose two decodes rounded onto either side of a key boundary. */
+    keyGridMs: number);
+    /** Frames dropped to the LRU policy; a cache-pressure signal for diagnostics. */
+    get evictions(): number;
+    /** Puts that landed on a key already live, collapsing both onto one slot. */
+    get bucketCollapses(): number;
+    put(key: number, timestampMs: number, src: CacheBlitSource, srcWidth: number, srcHeight: number): void;
+    /**
+     * Nearest resident frame to `timestampMs` within `tolMs`, or null.
+     *
+     * `atOrBefore` restricts it to frames at or before the target, which is the
+     * contract a decode answers a seek with. Without it the tier can answer with
+     * the frame AFTER the target, one no decode would ever return, so the same
+     * pointer position paints a different frame depending on whether the cache or
+     * the decoder served it, and the picture steps forward and back as the two
+     * alternate.
+     */
+    get(timestampMs: number, tolMs: number, atOrBefore?: boolean): TierHit | null;
+    /** Retrieves exactly one owner-assigned key and promotes it to MRU. */
+    getByKey(key: number): TierHit | null;
+    /** Promotes the entry nearest `timestampMs` to most-recently-used. Scans
+     *  rather than keys off the timestamp: callers pass a gesture position, which
+     *  is not a frame timestamp, so a keyed lookup would miss the very frame on
+     *  screen. No accounting; it is not a lookup. */
+    touch(timestampMs: number): void;
+    /** Promotes an owner-assigned key without a timestamp scan. */
+    touchKey(key: number): void;
+    clear(): void;
+    get size(): number;
+    /** True timestamps (ms) of resident frames, for diagnostics. Bounded by capacity. */
+    timestampsSnapshot(): number[];
+    private bump;
+    /**
+     * Best candidate for `timestampMs`, or null when nothing qualifies.
+     *
+     * Under `atOrBefore` a stored frame stands for the span from its own
+     * timestamp up to the next source frame; a target past that span belongs to
+     * the next frame, which is what a decode for it returns. Answering it from
+     * this tier would paint a frame no decode for that time ever produces, so a
+     * candidate outside its own frame's span is not eligible however generous the
+     * caller's tolerance is. Until the tier has learned a frame gap it has no
+     * spacing to bound with and the caller's tolerance stands alone.
+     */
+    private nearest;
+    /** Narrows the learned frame interval to the smallest gap seen so far. A gap
+     *  at or below the key grid is one frame that rounded onto two keys rather
+     *  than two frames, so it is no interval at all; what survives is a gap
+     *  between two frames, and never zero. It only ever tightens, so a tier that
+     *  has watched an unrepresentative stretch of a variable-rate source bounds
+     *  lookups too tightly (a decode) rather than too loosely (the wrong frame). */
+    private observeSpacing;
+}
+export {};

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

@@ -0,0 +1,27 @@
+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>;
+}