supervision 0.1.7 → 0.2.0-next.0

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

@@ -0,0 +1,74 @@
+import { type WalkFrameSource, type WalkSourceHandle } from "./decode-source";
+import type { VideoSampleLike } from "./scrub-cursor";
+import type { VideoSource } from "./types";
+/**
+ * One frame of a walk.
+ *
+ * `frameIndex` counts real frames from the start of the walked range, so the
+ * same frame carries the same number whatever stride was taken, and
+ * `timestampMs` is the sample's own.
+ *
+ * `sample` is live and closing it is the caller's, the obligation every
+ * VideoSampleLike carries. One dropped without close holds a decoder frame until
+ * garbage collection, which WebCodecs complains about on the console and which
+ * starves the decoder long before that.
+ */
+export interface WalkedFrame {
+    readonly frameIndex: number;
+    readonly timestampMs: number;
+    readonly durationMs: number;
+    readonly sample: VideoSampleLike;
+}
+export interface FrameWalkRange {
+    /** Inclusive start; the track's first timestamp when omitted. */
+    readonly startMs?: number;
+    /** Exclusive end, so two abutting ranges walk every frame once between them;
+     *  the end of the source when omitted. */
+    readonly endMs?: number;
+    /** Yield every Nth real frame. Counted in frames, not in time, so the spacing
+     *  holds on a variable-rate source and cannot accumulate drift. */
+    readonly stride?: number;
+}
+export interface FrameWalkMetadata {
+    readonly durationS: number;
+    readonly width: number;
+    readonly height: number;
+    readonly nativeFps: number | null;
+    readonly firstTimestampS: number;
+}
+/**
+ * Every real decoded frame of a range, in presentation order, exactly once.
+ *
+ * Nothing here is synthesized: the walk reads the source's own frames and counts
+ * them. Timestamps built from a frame rate and resolved through at-or-before
+ * extraction cannot promise that. One falling a float's width short of a sample
+ * lands on the frame before it, so the caller gets that frame twice and never
+ * sees the one it was aiming at.
+ *
+ * Every sample the walk decodes and does not yield is closed here: the frames
+ * before the range, the ones stride skips, and the first one past the end.
+ * Breaking out of the walk returns the underlying stream, which releases the
+ * decoder's read of the source; the sample in the caller's hand at that moment
+ * is still the caller's to close.
+ */
+export declare function walkFrames(source: WalkFrameSource, range?: FrameWalkRange): AsyncGenerator<WalkedFrame, void, unknown>;
+/**
+ * A batch consumer's entry to the runtime: opens a source, walks its real
+ * frames, and disposes what it opened. It spins no worker, binds no canvas, and
+ * runs no clock, and it decodes on an input of its own, so a walk and a playing
+ * engine never contend for one decoder's read head.
+ *
+ * A walk in flight ends when the walker is closed, the same way extraction does,
+ * so a consumer that abandons a job mid-range has one call to make.
+ */
+export declare class FrameWalker {
+    private readonly handle;
+    private closed;
+    constructor(handle: WalkSourceHandle);
+    /** Opens a source for walking; the returned walker owns it. */
+    static open(source: VideoSource): Promise<FrameWalker>;
+    get metadata(): FrameWalkMetadata;
+    walkFrames(range?: FrameWalkRange): AsyncGenerator<WalkedFrame, void, unknown>;
+    close(): Promise<void>;
+}
+//# sourceMappingURL=frame-walker.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame-walker.d.ts","sourceRoot":"","sources":["../src/frame-walker.ts"],"names":[],"mappings":"AAAA,OAAO,EAEL,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACtB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AACtD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAQ3C;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;CAClC;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B;8CAC0C;IAC1C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB;uEACmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;CAClC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAuB,UAAU,CAC/B,MAAM,EAAE,eAAe,EACvB,KAAK,GAAE,cAAmB,GACzB,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC,CA8C5C;AAED;;;;;;;;GAQG;AACH,qBAAa,WAAW;IAGV,OAAO,CAAC,QAAQ,CAAC,MAAM;IAFnC,OAAO,CAAC,MAAM,CAAS;gBAEM,MAAM,EAAE,gBAAgB;IAErD,+DAA+D;WAClD,IAAI,CAAC,MAAM,EAAE,WAAW,GAAG,OAAO,CAAC,WAAW,CAAC;IAI5D,IAAI,QAAQ,IAAI,iBAAiB,CAShC;IAEM,UAAU,CACf,KAAK,GAAE,cAAmB,GACzB,cAAc,CAAC,WAAW,EAAE,IAAI,EAAE,OAAO,CAAC;IAoBvC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAI7B"}

package/dist/web-video-engine/index.d.ts

@@ -0,0 +1,3 @@
+export * from "#web-video-engine";
+export { createVideoEngineMediaRendererSource, openVideoEngineMediaSource, type VideoEngineMediaSource, type VideoEngineMediaSourceOptions, } from "supervision";
+//# sourceMappingURL=index.d.ts.map

package/dist/web-video-engine/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/web-video-engine/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC;AAClC,OAAO,EACL,oCAAoC,EACpC,0BAA0B,EAC1B,KAAK,sBAAsB,EAC3B,KAAK,6BAA6B,GACnC,MAAM,aAAa,CAAC"}

package/dist/web-video-engine/index.js

@@ -0,0 +1,3 @@
+export * from './engine.js';
+export { createVideoEngineMediaRendererSource, openVideoEngineMediaSource } from '../index.js';
+//# sourceMappingURL=index.js.map

package/dist/web-video-engine/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":[],"sourcesContent":[],"names":[],"mappings":";"}

package/dist/web-video-engine/key-packet.d.ts

@@ -0,0 +1,65 @@
+/**
+ * An H.264 sync sample that is not an IDR frame cannot open a WebCodecs decode
+ * session: Chrome rejects the chunk with "An EncodedVideoChunk was marked as
+ * type key but wasn't a key frame" and emits no frames. Adding a recovery-point
+ * SEI to the access unit declares it a valid entry point, which is enough for the
+ * decoder to accept it and decode forward from there.
+ *
+ * The decoder demands an entry point for exactly one chunk, the first after
+ * configure() or flush(), and putting the SEI on any other chunk misdescribes
+ * the stream. KeyPacketRequirement is what tracks which chunk that is.
+ */
+/**
+ * Width of the AVCC length prefix this track frames every NAL with, read from
+ * its avcC record, or null when the description names no usable width. Files
+ * carry 1, 2, and 4, so nothing downstream may assume one of them.
+ */
+export declare function nalPrefixWidth(description: VideoDecoderConfig["description"]): number | null;
+/**
+ * Whether this access unit carries an IDR slice.
+ *
+ * A container's sync table names sync samples, and an H.264 sync sample is
+ * usually an ordinary I picture rather than an IDR. The two differ in what a
+ * decoder may assume about the pictures that follow: an IDR empties the
+ * reference list, so nothing after it can name a picture from before it, while
+ * an I picture leaves the list standing and the next reference frame is free to
+ * name pictures the entry point never decoded. Only the IDR is an entry point
+ * the bitstream cannot invalidate.
+ *
+ * Unreadable framing reads as not-IDR: the caller's fallback is to enter
+ * further back, which costs a walk and is never wrong.
+ */
+export declare function isIdrAccessUnit(packetBytes: Uint8Array, prefixWidth: number): boolean;
+/**
+ * The access unit as the chunk that opens a decode, carrying the recovery-point
+ * SEI that makes it a legal entry point.
+ *
+ * Where the SEI goes is the whole of it: an access unit delimiter, when the
+ * packet has one, is required to be the access unit's first NAL, so the SEI goes
+ * behind it. Ahead of it the access unit is malformed, and a decoder reading the
+ * opening chunk to decide whether it is really a key frame is entitled to say it
+ * is not.
+ */
+export declare function openingKeyPacket(packetBytes: Uint8Array, prefixWidth: number): Uint8Array;
+/**
+ * WebCodecs' standing demand for a key frame, which configure() and flush()
+ * both arm and the next submitted chunk clears.
+ */
+export declare class KeyPacketRequirement {
+    private readonly prefixWidth;
+    private pending;
+    constructor(prefixWidth: number);
+    /** Whether the demand still stands, so the chunk about to satisfy it can
+     *  also be typed as the key chunk the decoder is waiting for. */
+    get armed(): boolean;
+    /** Call after every configure() and flush(). */
+    rearm(): void;
+    /**
+     * Bytes to submit for the next packet in decode order, carrying the
+     * recovery-point SEI while the demand stands. The container reports sync
+     * samples, never IDR frames, so the SEI goes on without inspecting the
+     * packet; ahead of a true IDR it is a NAL the decoder ignores.
+     */
+    satisfy(packetBytes: Uint8Array): Uint8Array;
+}
+//# sourceMappingURL=key-packet.d.ts.map

package/dist/web-video-engine/key-packet.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"key-packet.d.ts","sourceRoot":"","sources":["../src/key-packet.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAyCH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,WAAW,EAAE,kBAAkB,CAAC,aAAa,CAAC,GAC7C,MAAM,GAAG,IAAI,CAOf;AAqED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAC7B,WAAW,EAAE,UAAU,EACvB,WAAW,EAAE,MAAM,GAClB,OAAO,CAIT;AAED;;;;;;;;;GASG;AACH,wBAAgB,gBAAgB,CAC9B,WAAW,EAAE,UAAU,EACvB,WAAW,EAAE,MAAM,GAClB,UAAU,CAWZ;AAaD;;;GAGG;AACH,qBAAa,oBAAoB;IAGnB,OAAO,CAAC,QAAQ,CAAC,WAAW;IAFxC,OAAO,CAAC,OAAO,CAAQ;gBAEM,WAAW,EAAE,MAAM;IAEhD;qEACiE;IACjE,IAAI,KAAK,IAAI,OAAO,CAEnB;IAED,gDAAgD;IAChD,KAAK,IAAI,IAAI;IAIb;;;;;OAKG;IACH,OAAO,CAAC,WAAW,EAAE,UAAU,GAAG,UAAU;CAK7C"}

package/dist/web-video-engine/keyframe-index.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Lazy index of a video track's keyframe timestamps, in seconds.
+ *
+ * Seeking decodes forward from the keyframe at-or-before the target, so every
+ * seek needs that anchor. Resolving one costs a container round-trip, so the
+ * index remembers each keyframe it discovers; repeated seeks around the same
+ * region then resolve synchronously through `cachedAtOrBefore`.
+ */
+/**
+ * Opaque packet handle. Only `timestamp` is read; the object is threaded back
+ * into `getNextKeyPacket` unchanged so the probe's hidden packet fields survive.
+ */
+export interface KeyframePacketLike {
+    readonly timestamp: number;
+}
+interface KeyframeRetrievalOptions {
+    readonly metadataOnly?: boolean;
+}
+/** The slice of mediabunny's `EncodedPacketSink` the index depends on. */
+export interface KeyframeProbe {
+    getKeyPacket(timestamp: number, options?: KeyframeRetrievalOptions): Promise<KeyframePacketLike | null>;
+    getNextKeyPacket(packet: KeyframePacketLike, options?: KeyframeRetrievalOptions): Promise<KeyframePacketLike | null>;
+}
+/**
+ * Distribution of the gaps between discovered keyframes, in seconds. A long
+ * maxGopS (or a high stddev) is the badly-encoded-source tell: an off-anchor
+ * seek must decode forward from the prior keyframe, so a long GOP is a wall of
+ * frames every scrub pays for. Zeros when fewer than two keyframes are known.
+ */
+export interface GopStats {
+    readonly count: number;
+    readonly avgGopS: number;
+    readonly maxGopS: number;
+    readonly minGopS: number;
+    readonly stddevS: number;
+    readonly densityPerS: number;
+}
+export declare class KeyframeIndex {
+    private readonly probe;
+    private readonly times;
+    private probeRoundTrips;
+    /** Set once a full walk has completed, so a second call is a free no-op. */
+    private fullyIndexed;
+    constructor(probe: KeyframeProbe);
+    /** Keyframe timestamps discovered so far, ascending and deduplicated. */
+    get known(): readonly number[];
+    /** Container queries the index has made; the rest resolve from memory. */
+    get probeCount(): number;
+    /**
+     * GOP-gap distribution over the keyframes discovered so far. Pass the track
+     * duration so density reflects keyframes across the whole clip, not just the
+     * clustered swept span; without it a few discovered keyframes in one region
+     * would read as a high density that does not hold track-wide.
+     */
+    gopStats(durationS?: number): GopStats;
+    /**
+     * Nearest keyframe at or before `tSec`, the anchor a seek decodes forward
+     * from. Null when `tSec` precedes the first keyframe.
+     */
+    keyframeAtOrBefore(tSec: number): Promise<number | null>;
+    /**
+     * First keyframe strictly after `tSec`, the boundary a forward decode runs
+     * up to. Null when no keyframe follows, or when `tSec` precedes the first
+     * keyframe (no anchor to step from).
+     */
+    nextKeyframeAfter(tSec: number): Promise<number | null>;
+    /**
+     * Every keyframe needed to decode the window `[startS, endS]`: the anchor at
+     * or before `startS` plus each keyframe up to `endS`. Empty when `startS`
+     * precedes the first keyframe.
+     */
+    keyframesCovering(startS: number, endS: number): Promise<readonly number[]>;
+    /**
+     * Walks the whole track once, recording every keyframe timestamp. Metadata
+     * only: it threads the same getKeyPacket / getNextKeyPacket pattern as the
+     * lazy probes, so it never decodes a pixel. Idempotent: a second call after a
+     * completed walk returns at once. Meant for the diagnostics lane, off the hot
+     * seek path, so the purple lane reflects the whole file rather than only the
+     * regions a scrub has visited.
+     */
+    ensureFullyIndexed(fromS?: number): Promise<void>;
+    /**
+     * Largest discovered keyframe at or before `tSec`, resolved synchronously
+     * from memory. Null when nothing at or before `tSec` has been discovered
+     * yet; callers fall back to the async probes above.
+     */
+    cachedAtOrBefore(tSec: number): number | null;
+    private record;
+}
+export {};
+//# sourceMappingURL=keyframe-index.d.ts.map

package/dist/web-video-engine/keyframe-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyframe-index.d.ts","sourceRoot":"","sources":["../src/keyframe-index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,UAAU,wBAAwB;IAChC,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;CACjC;AAED,0EAA0E;AAC1E,MAAM,WAAW,aAAa;IAC5B,YAAY,CACV,SAAS,EAAE,MAAM,EACjB,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;IACtC,gBAAgB,CACd,MAAM,EAAE,kBAAkB,EAC1B,OAAO,CAAC,EAAE,wBAAwB,GACjC,OAAO,CAAC,kBAAkB,GAAG,IAAI,CAAC,CAAC;CACvC;AAKD;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,qBAAa,aAAa;IAMZ,OAAO,CAAC,QAAQ,CAAC,KAAK;IALlC,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAgB;IACtC,OAAO,CAAC,eAAe,CAAK;IAC5B,4EAA4E;IAC5E,OAAO,CAAC,YAAY,CAAS;gBAEA,KAAK,EAAE,aAAa;IAEjD,yEAAyE;IACzE,IAAI,KAAK,IAAI,SAAS,MAAM,EAAE,CAE7B;IAED,0EAA0E;IAC1E,IAAI,UAAU,IAAI,MAAM,CAEvB;IAED;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,QAAQ;IAwCtC;;;OAGG;IACG,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAQ9D;;;;OAIG;IACG,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC;IAY7D;;;;OAIG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC;IAc7B;;;;;;;OAOG;IACG,kBAAkB,CAAC,KAAK,SAAI,GAAG,OAAO,CAAC,IAAI,CAAC;IAYlD;;;;OAIG;IACH,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAK7C,OAAO,CAAC,MAAM;CAKf"}

package/dist/web-video-engine/mirror-store.d.ts

@@ -0,0 +1,56 @@
+import type { FrameId, FrameLanding } from "./frame-timeline";
+import { type EngineChannel, type PaintSeq, type PlaybackState, PlaybackStatus } from "./types";
+/**
+ * Tiny external store powering useSyncExternalStore subscriptions. Five
+ * emit channels by mutation cadence:
+ *
+ *   - time: emits when the playhead moves to a different frame. Consumers
+ *           wanting a slower rerender cadence apply their own selector.
+ *   - frame: emits on every settled cursor-yielded frame, for marker rails.
+ *   - state: status transitions only. Rare. Driven by load, play, pause,
+ *            seek, end, error.
+ *   - duration: emits once per loaded source.
+ *   - seeking: emits when the cursor transitions in/out of an in-flight
+ *              scrub. Powers an opt-in scrub-in-flight indicator. Cache-hit
+ *              scrubs typically don't trip this because the cache paint is
+ *              synchronous, so the engine writes true only when the cursor
+ *              is actually doing a decode walk.
+ *   - rate:    emits on a playback-rate change. Rarest channel of the six.
+ *
+ * Channels are separate so a status-only consumer does not wake up at
+ * 60Hz when only time advances.
+ */
+export declare class MirrorStore {
+    private playhead;
+    private paintSeq;
+    private durationMs;
+    private status;
+    private error;
+    private seeking;
+    private rate;
+    private playbackStateSnapshot;
+    private readonly channelListeners;
+    getPlayhead(): FrameLanding;
+    getDurationMs(): number;
+    getStatus(): PlaybackStatus;
+    getError(): PlaybackState["error"];
+    getPaintSeq(): PaintSeq;
+    getPlaybackState(): PlaybackState;
+    getSeeking(): boolean;
+    getRate(): number;
+    /**
+     * Moves the playhead onto a frame. Ticks are integers, so the same frame
+     * arriving twice is recognised as the same frame and wakes nobody; the
+     * millisecond plane this replaced could not tell two positions apart at all,
+     * and emitted on every paint.
+     */
+    writePlayhead(frame: FrameId, mediaTimeS: number): void;
+    writePaintSeq(value: PaintSeq): void;
+    writeDurationMs(value: number): void;
+    writeStatus(status: PlaybackStatus, error?: PlaybackState["error"]): void;
+    writeSeeking(isSeeking: boolean): void;
+    writeRate(value: number): void;
+    subscribe(channel: EngineChannel, listener: () => void): () => void;
+    private emit;
+}
+//# sourceMappingURL=mirror-store.d.ts.map

package/dist/web-video-engine/mirror-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mirror-store.d.ts","sourceRoot":"","sources":["../src/mirror-store.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAC9D,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,aAAa,EAClB,cAAc,EACf,MAAM,SAAS,CAAC;AAEjB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,qBAAa,WAAW;IACtB,OAAO,CAAC,QAAQ,CAGd;IACF,OAAO,CAAC,QAAQ,CAA2B;IAC3C,OAAO,CAAC,UAAU,CAAK;IACvB,OAAO,CAAC,MAAM,CAAuC;IACrD,OAAO,CAAC,KAAK,CAAgC;IAC7C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,IAAI,CAAK;IAIjB,OAAO,CAAC,qBAAqB,CAG3B;IAEF,OAAO,CAAC,QAAQ,CAAC,gBAAgB,CAO/B;IAEF,WAAW,IAAI,YAAY;IAG3B,aAAa,IAAI,MAAM;IAGvB,SAAS,IAAI,cAAc;IAG3B,QAAQ,IAAI,aAAa,CAAC,OAAO,CAAC;IAGlC,WAAW,IAAI,QAAQ;IAGvB,gBAAgB,IAAI,aAAa;IAGjC,UAAU,IAAI,OAAO;IAGrB,OAAO,IAAI,MAAM;IAIjB;;;;;OAKG;IACH,aAAa,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI;IAMvD,aAAa,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI;IAMpC,eAAe,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAMpC,WAAW,CACT,MAAM,EAAE,cAAc,EACtB,KAAK,GAAE,aAAa,CAAC,OAAO,CAAQ,GACnC,IAAI;IAQP,YAAY,CAAC,SAAS,EAAE,OAAO,GAAG,IAAI;IAMtC,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAM9B,SAAS,CAAC,OAAO,EAAE,aAAa,EAAE,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI;IAOnE,OAAO,CAAC,IAAI;CAGb"}

package/dist/web-video-engine/renderer.d.ts

@@ -0,0 +1,94 @@
+import type { RendererName } from "./diagnostics";
+import type { ScrubFrame } from "./scrub-cursor";
+/**
+ * The colour space every render surface declares. A decoded frame carries its
+ * own and the browser converts it into whatever the destination names, but only
+ * on the canvas routes: the zero-copy import converts to sRGB whatever colour
+ * space it is asked for. A wider value here would therefore reach some routes
+ * and not others, on the same frame.
+ */
+export declare const DISPLAY_COLOR_SPACE: PredefinedColorSpace;
+/**
+ * The render seam: turns a decoded frame into pixels on the display canvas. The
+ * render loop owns timing and frame selection; a Renderer owns only how a frame
+ * reaches the screen, so the 2D and WebGPU paths are interchangeable behind it
+ * without the loop knowing which is in play.
+ */
+export interface Renderer {
+    /** Which backend this is, for diagnostics. */
+    readonly name: RendererName;
+    /**
+     * Paint one frame to fill the canvas, replacing whatever it last showed.
+     * A canvas frame carries a CanvasImageSource (a CanvasSink decode or a cache
+     * blit); a sample frame carries a live VideoSample the WebGPU path can import
+     * zero-copy. The controller owns the sample's lifetime and close, so a
+     * renderer never closes the frame it is handed.
+     */
+    draw(frame: ScrubFrame): void;
+    dispose(): void;
+}
+/**
+ * 2D-canvas renderer: one blit of an already-decoded frame through a 2D context.
+ * It is the graceful-degradation fallback wherever WebGPU is unavailable and the
+ * path prefer2d pins. Per the Renderer contract the loop owns cadence, so a draw
+ * happens only when a new frame is decoded. This is not a re-decode and not a
+ * per-tick repaint; it differs from the WebGPU path only in compositing a frame
+ * through a 2D context rather than on the GPU. Canvas dimensions are read live,
+ * so a resize between draws is picked up on the next frame.
+ */
+export declare class CanvasRenderer implements Renderer {
+    private readonly canvas;
+    readonly name: "2d";
+    private readonly ctx;
+    constructor(canvas: OffscreenCanvas);
+    draw(frame: ScrubFrame): void;
+    dispose(): void;
+}
+/**
+ * The presentation seam: what one paint does with a frame's pixels. The render
+ * loop decides which frame is presented and when, and keeps the same books
+ * either way; a sink decides only where the pixels go, so the engine's own
+ * display canvas and a host compositor are interchangeable behind it.
+ *
+ * present returns a frame when the pixels left the worker instead of reaching a
+ * canvas. That frame has exactly one owner from then on: the sink keeps no
+ * reference and never closes it.
+ */
+export interface FrameSink {
+    /** The render backend behind this sink, for diagnostics; null when the sink
+     *  renders nothing. */
+    readonly name: RendererName | null;
+    present(frame: ScrubFrame): VideoFrame | null;
+    dispose(): void;
+}
+/** Pixels to the engine's display canvas, through the resolved Renderer. */
+export declare class RendererFrameSink implements FrameSink {
+    private readonly renderer;
+    constructor(renderer: Renderer);
+    get name(): RendererName;
+    present(frame: ScrubFrame): null;
+    dispose(): void;
+}
+/**
+ * Pixels out of the worker as a VideoFrame, for a host that owns the canvas.
+ * A sample hands over its own frame, so a live decode reaches the host without
+ * a detour through a canvas. A cache blit has only canvas pixels to give, and
+ * the wrap has to be told the media time, which canvas pixels do not carry.
+ */
+export declare class TransferFrameSink implements FrameSink {
+    readonly name: null;
+    present(frame: ScrubFrame): VideoFrame;
+    dispose(): void;
+}
+export interface RendererOptions {
+    /** Pin the 2D renderer. Unset, WebGPU is preferred and used when available,
+     *  falling back to 2D otherwise, so it is not a guarantee of WebGPU. */
+    prefer2d?: boolean;
+}
+/**
+ * Chooses the render backend for a canvas. WebGPU is the default and probed at
+ * runtime; an explicit prefer2d, or any failure to acquire a device, yields the
+ * 2D renderer instead, so a caller always gets a working renderer.
+ */
+export declare function createRenderer(canvas: OffscreenCanvas, options?: RendererOptions): Promise<Renderer>;
+//# sourceMappingURL=renderer.d.ts.map

package/dist/web-video-engine/renderer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"renderer.d.ts","sourceRoot":"","sources":["../src/renderer.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AAGjD;;;;;;GAMG;AACH,eAAO,MAAM,mBAAmB,EAAE,oBAA6B,CAAC;AAEhE;;;;;GAKG;AACH,MAAM,WAAW,QAAQ;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B;;;;;;OAMG;IACH,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI,CAAC;IAC9B,OAAO,IAAI,IAAI,CAAC;CACjB;AAED;;;;;;;;GAQG;AACH,qBAAa,cAAe,YAAW,QAAQ;IAIjC,OAAO,CAAC,QAAQ,CAAC,MAAM;IAHnC,QAAQ,CAAC,IAAI,EAAG,IAAI,CAAU;IAC9B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAA2C;gBAElC,MAAM,EAAE,eAAe;IAQpD,IAAI,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAc7B,OAAO,IAAI,IAAI;CAChB;AAED;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB;2BACuB;IACvB,QAAQ,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,CAAC;IACnC,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU,GAAG,IAAI,CAAC;IAC9C,OAAO,IAAI,IAAI,CAAC;CACjB;AAED,4EAA4E;AAC5E,qBAAa,iBAAkB,YAAW,SAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,QAAQ;IAE/C,IAAI,IAAI,IAAI,YAAY,CAEvB;IAED,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAKhC,OAAO,IAAI,IAAI;CAGhB;AAED;;;;;GAKG;AACH,qBAAa,iBAAkB,YAAW,SAAS;IACjD,QAAQ,CAAC,IAAI,OAAQ;IAErB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,UAAU;IAOtC,OAAO,IAAI,IAAI;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B;4EACwE;IACxE,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,eAAe,EACvB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CASnB"}

package/dist/web-video-engine/rotation.d.ts

@@ -0,0 +1,35 @@
+/**
+ * A quarter turn, in degrees clockwise, that stored pixels still need before
+ * they face the way the container says they should. Every phone recording held
+ * in portrait carries one: the sensor stores landscape and the track's display
+ * matrix names the turn.
+ *
+ * The sign is mediabunny's, read straight off the track. ffprobe prints the
+ * opposite sign for the same file, so a clip ffprobe calls +90 is 270 here.
+ */
+export type Rotation = 0 | 90 | 180 | 270;
+/**
+ * Draws an image upright into a destination box, mirroring the transform
+ * mediabunny's own VideoSample.draw applies so a frame decoded by the runtime
+ * and a frame decoded by a mediabunny sink land the same pixels.
+ *
+ * dWidth and dHeight name the destination AFTER the turn, which is what the
+ * track's display size already is. So on a quarter turn the source is drawn at
+ * swapped extents inside the turned frame, and the scale below undoes the
+ * aspect that swap introduces.
+ */
+export declare function drawRotated(context: CanvasRenderingContext2D | OffscreenCanvasRenderingContext2D, image: CanvasImageSource, rotation: Rotation, dx: number, dy: number, dWidth: number, dHeight: number): void;
+/**
+ * The 2x2 rotation, row-major, that turns a destination texture coordinate
+ * about (0.5, 0.5) into the source coordinate to sample. Each entry is
+ * [cos -sin; sin cos] evaluated at MINUS the rotation, written out because a
+ * quarter turn is exact and trig at these angles is not.
+ *
+ * The negation is the whole point: sampling turns opposite to the picture, so
+ * showing a frame turned clockwise by R means reading it counter-clockwise by
+ * R. The unit square is closed under quarter turns about its centre, so the
+ * whole source still maps onto the whole destination and the shader's existing
+ * stretch-to-fill absorbs the aspect change for free.
+ */
+export declare function uvRotationMatrix(rotation: Rotation): readonly [number, number, number, number];
+//# sourceMappingURL=rotation.d.ts.map

package/dist/web-video-engine/rotation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rotation.d.ts","sourceRoot":"","sources":["../src/rotation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AACH,MAAM,MAAM,QAAQ,GAAG,CAAC,GAAG,EAAE,GAAG,GAAG,GAAG,GAAG,CAAC;AAE1C;;;;;;;;;GASG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,wBAAwB,GAAG,iCAAiC,EACrE,KAAK,EAAE,iBAAiB,EACxB,QAAQ,EAAE,QAAQ,EAClB,EAAE,EAAE,MAAM,EACV,EAAE,EAAE,MAAM,EACV,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,GACd,IAAI,CAYN;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,QAAQ,GACjB,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAE3C"}