supervision 0.1.7 → 0.2.0-next.1

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

@@ -0,0 +1,200 @@
+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 source frames: two paints of one media position can
+ * take two sequence numbers. Source-frame identity is carried separately by
+ * the presented frame's frameId and media timestamp.
+ */
+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;
+    /** The load transfers this stream to the worker, which detaches this side's
+     *  reference: afterwards the worker holds the only readable end. */
+    stream: ReadableStream<Uint8Array>;
+    /** Declared container type. Nothing reads it: the demuxer sniffs the bytes,
+     *  and no metadata surface carries it back out. */
+    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 WebVideoEngineErrorCode {
+    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; 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 / WebVideoEngine.load when decode is unsupported
+ * or the source is unreadable. Branch on `error.code` (WebVideoEngineErrorCode)
+ * to differentiate decode failures from network failures.
+ */
+export declare class WebVideoEngineError extends Error {
+    readonly code: WebVideoEngineErrorCode;
+    readonly cause?: unknown;
+    constructor(code: WebVideoEngineErrorCode, 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(): WebVideoEngineError;
+/**
+ * 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: WebVideoEngineError | 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.
+     */
+    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";

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

@@ -0,0 +1,437 @@
+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 WebVideoEngineOptions {
+    source: VideoSource;
+    /**
+     * Creates the worker that hosts decode and presentation. Omit it to use the
+     * embedded Blob worker. A host whose Content Security Policy disallows
+     * `blob:` workers can return a Worker created from the separately exported
+     * `supervision/web-video-engine/worker` URL instead.
+     */
+    workerFactory?: () => Worker;
+    /**
+     * 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 web 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 WebVideoEngine {
+    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: WebVideoEngineOptions, createWorker?: () => EngineWorkerPort);
+    /**
+     * Loads the configured source. A stream source is transferred on this call,
+     * so a repeat load has nothing left to hand over and rejects.
+     */
+    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.
+     * After synchronously drawing the frame and its matching layers, the handler
+     * calls acknowledgePresentation(), then close(). A discarded frame is only
+     * closed. 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 WebVideoEngineErrorCode.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(): WebVideoEngineHandle;
+    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
+     * WebVideoEngine 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. After drawing its pixels and
+ * matching layers, call acknowledgePresentation(), then close(). If it is
+ * discarded before display, only close it. */
+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 WebVideoEngineHandle {
+    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; a displayed frame is acknowledged before it is closed, while a
+     * discarded frame is only closed.
+     */
+    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;
+}