supervision 0.1.7 → 0.2.0-next.0

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

@@ -0,0 +1,204 @@
+import type { FrameTimelineData } from "./frame-timeline";
+/**
+ * Seconds, as a branded float. Promoted out of `number` so a duration
+ * cannot accidentally be passed where a frame index is expected.
+ */
+export type Sec = number & {
+    readonly __sec: unique symbol;
+};
+/** Frames per second. Branded for the same reason as Sec. */
+export type Fps = number & {
+    readonly __fps: unique symbol;
+};
+/**
+ * Paints since the source loaded, monotonic within it and reset on source swap.
+ * It counts paints, not frames of the source: two paints of the same media
+ * position (a coarse stand-in then the crisp decode) take two numbers, and
+ * nothing here identifies which frame of the source is on screen. That identity
+ * travels only as the media timestamp on the paint event.
+ */
+export type PaintSeq = number & {
+    readonly __paintSeq: unique symbol;
+};
+export declare const asSec: (n: number) => Sec;
+export declare const asFps: (n: number) => Fps;
+export declare const asPaintSeq: (n: number) => PaintSeq;
+export declare enum SourceKind {
+    Url = "url",
+    Blob = "blob",
+    Stream = "stream"
+}
+export interface UrlVideoSource {
+    kind: SourceKind.Url;
+    url: string;
+    /** The engine fetches rather than building an element, so these reach the
+     *  request as the CORS fetch they stand for. Undeclared leaves the request at
+     *  the demuxer's own same-origin default. */
+    crossOrigin?: "anonymous" | "use-credentials";
+}
+/**
+ * Mediabunny's own read tuning for a URL source, passed straight through to its
+ * `UrlSource`. Every field absent leaves mediabunny's defaults in place.
+ */
+export interface UrlSourceReadConfig {
+    /** Range requests the demuxer may have in flight at once. */
+    readonly parallelism?: number;
+    /** Ceiling on the bytes mediabunny's own read cache holds. */
+    readonly maxCacheSize?: number;
+}
+export interface BlobVideoSource {
+    kind: SourceKind.Blob;
+    blob: Blob;
+}
+export interface StreamVideoSource {
+    kind: SourceKind.Stream;
+    stream: ReadableStream<Uint8Array>;
+    /** Declared container type. The demuxer sniffs the bytes and never reads
+     *  this; it travels so a host can report what the media is. */
+    mimeType: string;
+}
+/**
+ * Source descriptor. Discriminated so each backend can route without runtime
+ * sniffing and so the future mediabunny v2 StreamSource slots in as a new
+ * variant rather than a refactor.
+ */
+export type VideoSource = UrlVideoSource | BlobVideoSource | StreamVideoSource;
+/**
+ * Which decode machinery a source was opened through: mediabunny's CanvasSink,
+ * mediabunny's VideoSampleSink, or the runtime's own long-lived DecodeSession.
+ * Resolved per source at open time from what the track and the realm support.
+ */
+export type DecodePath = "canvas" | "sample" | "session";
+/**
+ * Who owns the pixels. "canvas" is the engine: it holds a display canvas and
+ * paints every frame that earns the screen. "frames" is the host: the engine
+ * holds no canvas, paints nothing, and hands each of those frames out as a
+ * VideoFrame instead, so an external compositor can own the only canvas.
+ */
+export type PresentationMode = "canvas" | "frames";
+/**
+ * Coarse-grained engine status. Updates rarely (load, play, pause, end,
+ * error). Sits on its own emit channel so subscribers do not wake up on
+ * 60Hz time ticks.
+ */
+export declare enum PlaybackStatus {
+    Idle = "IDLE",
+    Loading = "LOADING",
+    Ready = "READY",
+    Playing = "PLAYING",
+    Paused = "PAUSED",
+    Seeking = "SEEKING",
+    Ended = "ENDED",
+    Errored = "ERRORED"
+}
+export declare enum VideoEngineErrorCode {
+    DecodeUnsupported = "DECODE_UNSUPPORTED",
+    SourceUnreadable = "SOURCE_UNREADABLE",
+    /**
+     * The demuxer refused the file outright: its container is not one this build
+     * reads, so no track was ever listed and no decoder was ever asked.
+     */
+    ContainerUnreadable = "CONTAINER_UNREADABLE",
+    /**
+     * The container opened and the demuxer parsed no track at all out of it. The
+     * file's streams are in formats it does not carry, so their video cannot be
+     * reached even though it is there.
+     */
+    VideoTrackUnreadable = "VIDEO_TRACK_UNREADABLE",
+    /**
+     * The container opened, its tracks listed, and none of them is video. This
+     * is the only case where the file itself is what lacks video.
+     */
+    NoVideoTrack = "NO_VIDEO_TRACK",
+    BackendCrashed = "BACKEND_CRASHED",
+    Aborted = "ABORTED",
+    /** A canvas was offered to an engine loaded in "frames" presentation mode,
+     *  where the host owns the only canvas. */
+    PresentationMismatch = "PRESENTATION_MISMATCH",
+    /**
+     * The decoder cannot decode this source at all: it refused to configure, it
+     * errored, or it acknowledged decode requests and never produced a frame.
+     * Distinct from BackendCrashed, which a rebuild can recover; this one
+     * survives every rebuild, so the runtime stops rebuilding and says so. The
+     * usual cause is outside the page: another tab holding every hardware
+     * decoder session the machine has.
+     */
+    DecoderStalled = "DECODER_STALLED",
+    /** A playback rate outside the forward range the engine supports. */
+    RateUnsupported = "RATE_UNSUPPORTED"
+}
+/**
+ * Thrown by createScrubCursor / VideoEngine.load when decode is unsupported
+ * or the source is unreadable. Branch on `error.code` (VideoEngineErrorCode)
+ * to differentiate decode failures from network failures.
+ */
+export declare class VideoEngineError extends Error {
+    readonly code: VideoEngineErrorCode;
+    readonly cause?: unknown;
+    constructor(code: VideoEngineErrorCode, message: string, cause?: unknown);
+}
+/** Shared by the facade and the core so a host gets the same refusal wherever
+ *  its canvas is caught. */
+export declare function canvasBindingRefused(): VideoEngineError;
+/**
+ * Validates a requested playback rate and returns it. The facade and the core
+ * both call it, so a rate is refused at whichever boundary it arrives at and
+ * with the same message: the facade posts fire-and-forget, so a refusal raised
+ * only in the worker would reach nobody.
+ *
+ * Reverse is rejected, not clamped: backwards playback is a different decode
+ * problem, and a -1 quietly serviced as +0.25 plays the wrong direction while
+ * reporting success.
+ */
+export declare function resolvePlaybackRate(rate: number): number;
+export interface PlaybackState {
+    status: PlaybackStatus;
+    error: VideoEngineError | null;
+}
+export interface VideoMetadata {
+    durationMs: number;
+    nativeFps: Fps | null;
+    naturalWidth: number;
+    naturalHeight: number;
+    /** Media time of the first sample, ms. Non-zero on trimmed/offset sources,
+     *  where an annotation timeline that assumes 0 drifts by exactly this. */
+    firstTimestampMs: number;
+    codec: string | null;
+    canDecode: boolean;
+}
+/**
+ * Snapshot delivered through the `onReady` lifecycle callback exactly once
+ * per loaded source after metadata resolves.
+ */
+export interface EngineReadySnapshot extends VideoMetadata {
+    /**
+     * Every real frame of the source, by its container tick timestamp. A host
+     * holding this can name any position the engine publishes, and can resolve
+     * one of its own pointer positions to a frame without asking.
+     */
+    readonly timeline: FrameTimelineData;
+    /**
+     * The kind of reader the demuxer was opened over, recorded once the open
+     * succeeded. A host knows what it asked for; only the engine knows what it
+     * got, and the three kinds differ in what they can do afterwards — a stream
+     * cannot be rewound or reopened, and only a URL is fetched.
+     *
+     * Optional so a host holding a snapshot it built before this field existed
+     * still satisfies the type.
+     */
+    readonly byteSource?: SourceKind;
+}
+/**
+ * Channels the engine store emits on. Pick the channel matching the slice
+ * cadence so consumers do not wake up on unrelated mutations.
+ *
+ *   - time:     emits per paint (raw ms; bucketing lives in hook selectors).
+ *   - frame:    emits per settled cursor frame (frame-index changes).
+ *   - state:    coarse status transitions (load, play, pause, end, error).
+ *   - duration: once per loaded source.
+ *   - seeking:  cursor scrub-in-flight transitions (opt-in indicator).
+ *   - rate:     playback-rate changes. Rare, and on its own channel so a rate
+ *               readout does not wake on status and vice versa.
+ */
+export type EngineChannel = "time" | "frame" | "state" | "duration" | "seeking" | "rate";
+//# sourceMappingURL=types.d.ts.map

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

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

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

@@ -0,0 +1,426 @@
+import type { DecodeResolutionStrategy } from "./decode-resolution";
+import type { DiagnosticsSnapshot, EngineDiagnostics } from "./diagnostics";
+import { type FrameId, type FrameLanding } from "./frame-timeline";
+import type { SeekIntent } from "./scrub-cursor";
+import type { EngineTrace } from "./trace-recorder";
+import { type EngineChannel, type EngineReadySnapshot, type PaintSeq, type PlaybackState, PlaybackStatus, type PresentationMode, type UrlSourceReadConfig, type VideoSource } from "./types";
+import { type EngineCommand, type EngineEvent, type PresentedFrame, type SourceResidencyConfig } from "./worker-protocol";
+/**
+ * Where a caller wants the playhead: a frame of the source, or a position in
+ * milliseconds. A pointer only ever has the second kind; anything the engine
+ * published carries the first, and handing that back needs no conversion.
+ */
+export type SeekTarget = number | FrameId;
+export interface VideoEngineOptions {
+    source: VideoSource;
+    /**
+     * Who owns the pixels, fixed for the life of the engine. Default "canvas":
+     * the engine holds the display canvas bindCanvas transfers to it and paints
+     * every frame that earns the screen. Under "frames" it holds no canvas,
+     * paints nothing, and hands those frames to onPresentedFrame instead, for a
+     * host compositor to draw; bindCanvas then throws.
+     */
+    presentation?: PresentationMode;
+    /**
+     * Cache strategy for instant scrub feedback. Default "tiered" keeps a
+     * downscaled preview history plus a RAM-bounded full-resolution tier;
+     * "none" disables caching (the cursor decodes every seek from scratch).
+     */
+    cacheStrategy?: "tiered" | "none";
+    /** Preview-tier capacity (frames). Ignored when cacheStrategy is "none". */
+    previewCapacity?: number;
+    /** Preview-tier entry width in CSS pixels. Ignored when cacheStrategy is "none". */
+    previewWidth?: number;
+    /**
+     * Cache lookups whose nearest hit lies within this many milliseconds of
+     * what the canvas already shows are rejected, forcing a full-res decode.
+     * See constants.FRAME_CACHE.SKIP_NEAR_MS for the default and tuning notes.
+     */
+    cacheSkipNearMs?: number;
+    /**
+     * Decides the resolution preview frames decode to. Defaults to native, so a
+     * consumer that says nothing keeps full source resolution and pays for it in
+     * paint work and frame-cache slots. Governs the live preview only; never the
+     * timestamps a consumer extracts.
+     *
+     * Which strategy fits follows from `presentation`. Under "canvas" the engine
+     * measures the box it was handed, so viewportResolution() reads it. Under
+     * "frames" nothing binds a canvas and there is no box to read, so
+     * viewportResolution() resolves to native there and displayBoxResolution()
+     * is how that consumer states the size it composites into.
+     */
+    decodeStrategy?: DecodeResolutionStrategy;
+    /**
+     * Pin the 2D renderer instead of WebGPU. WebGPU is the default; leaving this
+     * unset prefers it and falls back to the 2D renderer only when WebGPU is
+     * unavailable, so unset is not a guarantee of WebGPU. Both renderers paint
+     * the same already-decoded frames on the same cadence (the render loop draws
+     * a frame only when a new one is decoded). The 2D path is one canvas blit
+     * per frame, not a re-decode and not a per-tick CPU repaint; the two differ
+     * only in where a frame is composited, the GPU versus a 2D context.
+     */
+    prefer2d?: boolean;
+    /**
+     * Hold the source's bytes in this process and serve the demuxer's reads from
+     * them, so a position read once is read locally ever after. Off by default:
+     * it spends memory the host has to be willing to spend, and prefetching
+     * spends the viewer's link on bytes they may never watch.
+     *
+     * Only a `SourceKind.Url` source can use this. A Blob source is already local
+     * and a Stream source is consumed once, so neither has anything to hold.
+     */
+    sourceResidency?: SourceResidencyConfig;
+    /**
+     * Read tuning handed to mediabunny for a `SourceKind.Url` source: how many
+     * range requests it may run at once, and how many bytes its own reader keeps.
+     * Nothing here is read for a Blob or Stream source.
+     */
+    urlSource?: UrlSourceReadConfig;
+}
+/**
+ * The slice of a Worker this facade depends on. A real Worker is structurally
+ * assignable, so production passes one through createEngineWorker; tests
+ * pass a fake port that hosts an EngineCore in-process.
+ */
+export interface EngineWorkerPort {
+    postMessage(message: EngineCommand, transfer: Transferable[]): void;
+    addEventListener(type: "message", listener: (event: MessageEvent<EngineEvent>) => void): void;
+    terminate(): void;
+}
+/**
+ * Main-thread facade for the worker-hosted video engine. Owns the worker
+ * (spawned lazily on the first command), the mirror store React reads through
+ * useSyncExternalStore, and the imperative handle. The decode + render loop runs
+ * in the worker (EngineCore); this class never touches a cursor or clock directly.
+ *
+ * Three planes cross the worker boundary (see workerProtocol): commands go out,
+ * broadcast state comes back as MirrorEvents fed into the store, and the display
+ * canvas is transferred once on bindCanvas. Awaitable commands carry a requestId
+ * the worker echoes back so each call settles its own promise.
+ *
+ * Time has two owners, gated by playback. While playing, the worker emits time;
+ * while paused, the main thread owns the position: scrub/commit/step write it
+ * optimistically so a late worker paint never yanks it back. Consumers render the
+ * playhead by reading getTimeMs/getDurationMs at their own cadence.
+ *
+ * Engine outlives a single React render. Recreate the engine only when the
+ * source identity changes.
+ */
+export declare class VideoEngine {
+    private readonly options;
+    private readonly store;
+    private readonly diagnosticsStore;
+    private readonly createWorker;
+    private port;
+    private disposed;
+    private lastTrace;
+    private traceArmed;
+    private readonly pending;
+    private nextRequestId;
+    private metadata;
+    /** The loaded source's frame table, held here so a gesture is resolved to a
+     *  frame in the tick it arrives, with no worker round trip. */
+    private timeline;
+    private transferredCanvas;
+    private presentedFrameHandler;
+    /** Deliveries counted toward the one frame-ownership check, frozen past it,
+     *  and the frame that check reads. Weak, so watching costs the frame no
+     *  lifetime: a host that closes and drops it leaves nothing to find, which is
+     *  itself the answer. */
+    private presentedDeliveries;
+    private watchedFrame;
+    private cachedHandle;
+    /** WebGPU support is a main-thread fact the worker cannot cheaply probe, so
+     *  the facade fills it onto each diagnostics snapshot for the warning rules. */
+    private readonly webgpuAvailable;
+    constructor(options: VideoEngineOptions, createWorker?: () => EngineWorkerPort);
+    load(): Promise<EngineReadySnapshot>;
+    /**
+     * Transfers the display canvas to the worker exactly once. The transfer is
+     * permanent (it neuters the element's 2D/GPU context), so a repeat call with
+     * the same element, or a null detach, is a no-op; the binding lives until
+     * dispose terminates the worker. The viewport box is measured here, where
+     * layout lives, and shipped so a viewport-aware decode strategy can size the
+     * sink worker-side.
+     */
+    bindCanvas: (el: HTMLCanvasElement | null) => void;
+    play: () => Promise<void>;
+    pause: () => void;
+    togglePlayback: () => void;
+    /**
+     * Forward playback speed, in media seconds per wall second. Takes effect at
+     * once while playing and on the next play while paused; either way it
+     * survives pause, seek, interactive-seek, and replay from the end, because
+     * it is the clock's slope and none of those touch it.
+     *
+     * Throws synchronously on a rate outside the supported forward range,
+     * including any reverse rate. The refusal has to happen here: the command is
+     * fire-and-forget, so a worker-side throw would reach no caller.
+     */
+    setPlaybackRate: (rate: number) => void;
+    getPlaybackRate(): number;
+    /**
+     * Fire-and-forget seek: latest-wins, does not await idle. A pointer position
+     * is not a frame time and never can be, so it is resolved to the frame
+     * covering it before it reaches the store or the worker; the table lives on
+     * this thread, so the playhead lands on a frame in the same tick the gesture
+     * arrives, with no round trip.
+     *
+     * intent steers what the cache prepares next. Ignored when cacheStrategy is
+     * "none": that backend has no access modes to switch and no prefetch to aim.
+     */
+    scrub: (target: SeekTarget, intent?: SeekIntent) => void;
+    /**
+     * Pause-during-drag entry point. Consumers that handle pointer-driven
+     * scrub gestures call this on pointerdown so playback freezes and the
+     * decoder is not continuously chasing the cursor; the corresponding
+     * endInteractiveSeek call on pointerup resumes play if the engine was
+     * playing when the drag started. Matches the way native <video> pauses
+     * during the scrub-bar drag and resumes on release.
+     */
+    beginInteractiveSeek: () => void;
+    /**
+     * Pointerup counterpart to beginInteractiveSeek. Resumes play only if the
+     * engine was playing when the drag started; an idle-to-idle drag leaves the
+     * engine paused. Resolves once the worker has applied the release.
+     */
+    endInteractiveSeek: () => Promise<void>;
+    /**
+     * Awaited seek. Resolves after the cursor settles. Use on pointer-up so
+     * downstream logic (export, telemetry, marker placement) sees the
+     * settled frame.
+     */
+    commit: (target: SeekTarget) => Promise<void>;
+    seekToKey: (target: SeekTarget) => Promise<void>;
+    /**
+     * Moves one frame along the source in presentation order. Which frame that
+     * is depends on where the walk actually settled, which only the worker
+     * knows, so the landing rides back on the ack and is written here, keeping
+     * the paused playhead in step with the freshly painted frame.
+     */
+    private stepChain;
+    /**
+     * Serialized so concurrent callers (rapid key-repeat, mashed buttons, a
+     * programmatic loop) never run overlapping steps that race the cursor's
+     * one-shot decode iterator and wedge it. Each call chains after the previous,
+     * so every invocation advances exactly one frame from the settled position,
+     * on any surface.
+     */
+    step: (direction: 1 | -1) => Promise<void>;
+    private runStep;
+    /**
+     * Settled iff the engine is between operations. Derived from mirror state
+     * rather than the cursor (which lives in the worker): Idle/Loading read as
+     * settled, otherwise a live seek is the only thing that unsettles it.
+     */
+    isIdle(): boolean;
+    getSeeking(): boolean;
+    /** Where the transport has settled: a frame of the source, never a request
+     *  and never a clock reading. */
+    getPlayhead(): FrameLanding;
+    getTimeMs(): number;
+    getDurationMs(): number;
+    getStatus(): PlaybackStatus;
+    getPaintSeq(): PaintSeq;
+    getMetadata(): EngineReadySnapshot | null;
+    /**
+     * Cache hit-rate, scrub-decode latency, and access mode from the worker, or
+     * null on the uncached cursor. A round-trip per call; for diagnostics, not
+     * the hot path.
+     */
+    getStats(): Promise<EngineDiagnostics | null>;
+    /**
+     * Opt-in diagnostics broadcast. Starts the worker's BROADCAST_HZ timer and
+     * flips on the per-rAF counters; snapshots arrive on the diag plane and land
+     * in the DiagnosticsStore. The instrument calls this on mount and
+     * stopDiagnostics on unmount, so a closed panel costs the engine nothing.
+     */
+    startDiagnostics: (hz?: number) => void;
+    stopDiagnostics: () => void;
+    /** Arm the worker trace rings. Fire-and-forget; disarmTrace frees them. */
+    armTrace: (windowMs: number) => void;
+    disarmTrace: () => void;
+    /** The capture rescued from a dispose that landed mid-recording, or null. */
+    getLastTrace: () => EngineTrace | null;
+    /** Awaitable: assembles the worker trace and returns it for download. Null
+     *  when nothing was armed. */
+    exportTrace: () => Promise<EngineTrace | null>;
+    /**
+     * Registers THE consumer of presented frames, in "frames" presentation mode.
+     * A second registration replaces the first, so at most one holder exists.
+     * The handler owns every frame it is given and must close() it; one left
+     * open pins a decoder buffer and stalls the decoder.
+     *
+     * There is deliberately no counterpart that reports the frame most recently
+     * presented. A frame readable apart from the message that carried it can be
+     * read at a moment when a newer one has already been handed out, which is
+     * the desync this plane is shaped to make impossible.
+     */
+    onPresentedFrame: (handler: PresentedFrameHandler) => void;
+    /** Subscribe to diagnostics pushes; fires on every diag broadcast. Separate
+     *  from the playback subscribe channels so a diagnostics consumer never wakes
+     *  on playback state and vice versa. */
+    subscribeDiagnostics: (listener: () => void) => (() => void);
+    /** Latest broadcast snapshot, or null before the first push. */
+    getLatestDiagnostics: () => DiagnosticsSnapshot | null;
+    subscribe(channel: EngineChannel, listener: () => void): () => void;
+    /**
+     * Tears the engine down: drains pending requests so an in-flight load/commit
+     * rejects rather than hanging, and terminates the worker. The dispose ack is
+     * awaited first so the worker closes its cursor cleanly before the realm is
+     * killed.
+     *
+     * The engine is inert afterwards. A fire-and-forget command is dropped and an
+     * awaitable one rejects with {@link VideoEngineErrorCode.Aborted}; neither
+     * starts another worker.
+     */
+    dispose(): Promise<void>;
+    /**
+     * Curated subset exposed to React via useImperativeHandle. Cached so the
+     * handle keeps a stable identity for the lifetime of the engine (consumers
+     * may list it in useEffect deps).
+     */
+    toHandle(): VideoEngineHandle;
+    private readonly isIdleBound;
+    private readonly getPlayheadBound;
+    private readonly getTimeMsBound;
+    private readonly getDurationMsBound;
+    private readonly getPaintSeqBound;
+    private readonly getMetadataBound;
+    private readonly getStatsBound;
+    private readonly getPlaybackStateBound;
+    private readonly getSeekingBound;
+    private readonly getPlaybackRateBound;
+    private readonly subscribeBound;
+    private readonly onWorkerMessage;
+    /**
+     * Hands one frame to the registered consumer, which owns it from here. With
+     * nobody registered it is closed at once rather than dropped on the floor:
+     * the worker has already let go of it, so an unclaimed frame is a leak that
+     * pins a decoder buffer.
+     */
+    private deliverPresentedFrame;
+    /**
+     * Says out loud that this host does not close the frames it is handed.
+     * Nothing else in the runtime can: the frame left the worker on the transfer
+     * list, so no engine-side counter ever sees it again, and the decoder it
+     * starves reports the damage as a hung decode instead.
+     *
+     * One frame is watched and read once, so the check costs a host that closes a
+     * single allocation for the whole session and every later delivery one
+     * predicted-false branch.
+     */
+    private checkFrameOwnership;
+    private settle;
+    /**
+     * Spawns the worker on first use and wires the state plane into the mirror
+     * store. Deferring the spawn keeps construction side-effect-free, so a
+     * VideoEngine built during render (e.g. a useState initializer) never leaks
+     * a worker when React discards a duplicate.
+     */
+    private ensurePort;
+    private request;
+    private post;
+    private rejectAllPending;
+    /**
+     * The frame a target names.
+     *
+     * A frame names itself. A millisecond position is narrowed in seconds and
+     * then settled against `timeAt(i) * 1000`, the expression getTimeMs
+     * publishes: dividing a published millisecond back into seconds re-rounds
+     * it, and on tick rates like NTSC's 24000 the quotient can land just under
+     * the frame's own second, one frame early.
+     */
+    private snap;
+    private writePlayheadAt;
+    private writePlayhead;
+    private requireTimeline;
+    private measureViewport;
+}
+/**
+ * Receives one presented frame and owns it: it must close() the VideoFrame, and
+ * the identity it is judged against arrives in the same object, never fetched.
+ */
+export type PresentedFrameHandler = (presented: PresentedFrame) => void;
+/**
+ * Imperative handle exposed to React via useImperativeHandle. Stable identity
+ * for the lifetime of one source, so consumers may list it in effect deps.
+ *
+ * Curated subset on purpose: coarse status + error are reachable via the
+ * PlaybackStateContext or useVideoEngineState hook, NOT through the handle, so a
+ * consumer that latches onto the handle does not also depend on the shape of
+ * getPlaybackState.
+ */
+export interface VideoEngineHandle {
+    play(): Promise<void>;
+    pause(): void;
+    togglePlayback(): void;
+    /**
+     * Forward playback speed in media seconds per wall second, within the range
+     * PLAYBACK_RATE bounds. Throws synchronously outside it, reverse included.
+     * Subscribe on the "rate" channel to follow it.
+     */
+    setPlaybackRate(rate: number): void;
+    getPlaybackRate(): number;
+    scrub(target: SeekTarget, intent?: SeekIntent): void;
+    commit(target: SeekTarget): Promise<void>;
+    seekToKey(target: SeekTarget): Promise<void>;
+    step(direction: 1 | -1): Promise<void>;
+    /**
+     * Pointerdown of a drag-based scrub. Pauses if the engine was playing
+     * and remembers to resume on endInteractiveSeek. Idempotent inside a
+     * drag (re-entries while the resume flag is armed are no-ops, so the
+     * original "was playing" state survives).
+     */
+    beginInteractiveSeek(): void;
+    /** Pointerup of a drag-based scrub. Resumes play iff begin paused us. */
+    endInteractiveSeek(): Promise<void>;
+    isIdle(): boolean;
+    /** Where the transport has settled, as a frame of the source. */
+    getPlayhead(): FrameLanding;
+    /** The same position on the whole-millisecond plane, for a host that still
+     *  speaks it. Handing this value back to scrub, commit or seekToKey lands on
+     *  the frame it came from, on every source. */
+    getTimeMs(): number;
+    getDurationMs(): number;
+    getPaintSeq(): PaintSeq;
+    getMetadata(): EngineReadySnapshot | null;
+    /** Worker-side runtime stats (cache hit-rate, scrub latency, access mode)
+     *  for diagnostics; null on the uncached cursor. A round-trip per call. */
+    getStats(): Promise<EngineDiagnostics | null>;
+    getPlaybackState(): PlaybackState;
+    /**
+     * True while the cursor is mid-scrub. Cache-hit scrubs do not flip this
+     * because the cache paint is synchronous; only real cursor decode walks
+     * trip it. Subscribed via the "seeking" channel.
+     */
+    getSeeking(): boolean;
+    bindCanvas(el: HTMLCanvasElement | null): void;
+    /**
+     * Registers the single consumer of presented frames ("frames" presentation
+     * mode). Registering again replaces the previous consumer. The handler owns
+     * each frame and must close() it.
+     */
+    onPresentedFrame(handler: PresentedFrameHandler): void;
+    subscribe(channel: EngineChannel, listener: () => void): () => void;
+    /**
+     * Opt-in diagnostics broadcast control. The instrument starts on mount and
+     * stops on unmount (and on visibilitychange), so the worker pays nothing when
+     * no panel listens. Snapshots arrive via subscribeDiagnostics; the playback
+     * channels are untouched.
+     */
+    startDiagnostics(hz?: number): void;
+    stopDiagnostics(): void;
+    /** Arm/disarm the worker trace rings (fire-and-forget). */
+    armTrace(windowMs: number): void;
+    disarmTrace(): void;
+    /** Assemble and return the worker trace for download; null when not armed. */
+    exportTrace(): Promise<EngineTrace | null>;
+    /** The capture rescued from a dispose that landed mid-recording, or null. */
+    getLastTrace(): EngineTrace | null;
+    /** Subscribe to diagnostics pushes. Separate from the playback channels. */
+    subscribeDiagnostics(listener: () => void): () => void;
+    /** Latest broadcast snapshot, or null before the first push. */
+    getLatestDiagnostics(): DiagnosticsSnapshot | null;
+}
+//# sourceMappingURL=video-engine.d.ts.map

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

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