avbridge 1.0.0

package/src/strategies/fallback/index.ts

@@ -0,0 +1,170 @@
+import type { MediaContext, PlaybackSession } from "../../types.js";
+import { VideoRenderer } from "./video-renderer.js";
+import { AudioOutput } from "./audio-output.js";
+import { startDecoder, type DecoderHandles } from "./decoder.js";
+
+/**
+ * Fallback strategy session.
+ *
+ * Owns the orchestration between the libav decoder, the audio scheduler,
+ * and the canvas renderer. Three things make this non-trivial:
+ *
+ * 1. **Cold-start ready gate.** When `play()` is called, we wait until the
+ *    audio scheduler has buffered enough audio (≥ 300 ms) AND the renderer
+ *    has at least one decoded video frame, before actually telling the
+ *    audio context to start. Without this gate, audio and the wall clock
+ *    race ahead of the still-warming-up software decoder, and every video
+ *    frame lands "in the past" and gets dropped.
+ *
+ * 2. **Pause / resume.** The audio context is suspended on pause and
+ *    resumed on play. The media-time anchor is preserved across the
+ *    suspend so the clock is continuous.
+ *
+ * 3. **Seek.** Pauses the audio scheduler, asks the decoder to cancel its
+ *    current pump and `av_seek_frame` to the target, resets the audio
+ *    output's media-time anchor to the seek target, flushes the renderer
+ *    queue, then re-enters the ready gate. If we were playing before the
+ *    seek, we automatically resume once the buffer fills.
+ *
+ * The unified player API on top of this just sees `play() / pause() /
+ * seek(t)` — none of the buffering choreography leaks out.
+ */
+
+const READY_AUDIO_BUFFER_SECONDS = 0.3;
+const READY_TIMEOUT_SECONDS = 10;
+
+export async function createFallbackSession(
+  ctx: MediaContext,
+  target: HTMLVideoElement,
+): Promise<PlaybackSession> {
+  // Normalize the source so URL inputs go through the libav HTTP block
+  // reader instead of being buffered into memory.
+  const { normalizeSource } = await import("../../util/source.js");
+  const source = await normalizeSource(ctx.source);
+
+  const fps = ctx.videoTracks[0]?.fps ?? 30;
+  const audio = new AudioOutput();
+  const renderer = new VideoRenderer(target, audio, fps);
+
+  let handles: DecoderHandles;
+  try {
+    handles = await startDecoder({
+      source,
+      filename: ctx.name ?? "input.bin",
+      context: ctx,
+      renderer,
+      audio,
+    });
+  } catch (err) {
+    audio.destroy();
+    renderer.destroy();
+    throw err;
+  }
+
+  // Patch the <video> element so the unified player layer (which polls
+  // `target.currentTime` for `timeupdate` events and lets users assign to
+  // it for seeks) gets the right values from the fallback strategy.
+  Object.defineProperty(target, "currentTime", {
+    configurable: true,
+    get: () => audio.now(),
+    set: (v: number) => {
+      // Fire-and-forget — the user is expected to await player.seek() if
+      // they want to know when the seek completes.
+      void doSeek(v);
+    },
+  });
+  // Mirror duration so the demo's controls can use target.duration too.
+  if (ctx.duration && Number.isFinite(ctx.duration)) {
+    Object.defineProperty(target, "duration", {
+      configurable: true,
+      get: () => ctx.duration ?? NaN,
+    });
+  }
+
+  /**
+   * Wait until the decoder has produced enough buffered output to start
+   * playback smoothly. Returns early on timeout so we don't hang forever
+   * if the decoder is producing nothing (e.g. immediately past EOF after
+   * a seek to the end).
+   */
+  async function waitForBuffer(): Promise<void> {
+    const start = performance.now();
+    while (true) {
+      const audioReady = audio.isNoAudio() || audio.bufferAhead() >= READY_AUDIO_BUFFER_SECONDS;
+      if (audioReady && renderer.hasFrames()) {
+        return;
+      }
+      if ((performance.now() - start) / 1000 > READY_TIMEOUT_SECONDS) {
+        // Give up waiting; play whatever we have.
+        return;
+      }
+      await new Promise((r) => setTimeout(r, 50));
+    }
+  }
+
+  async function doSeek(timeSec: number): Promise<void> {
+    const wasPlaying = audio.isPlaying();
+    // 1. Stop audio (suspend ctx + capture media time).
+    await audio.pause().catch(() => {});
+    // 2. Tell the decoder to cancel its pump and seek the demuxer.
+    await handles.seek(timeSec).catch((err) =>
+      console.warn("[avbridge] decoder seek failed:", err),
+    );
+    // 3. Reset audio + renderer to the new media time. New samples from
+    //    the decoder will queue against this anchor.
+    await audio.reset(timeSec);
+    renderer.flush();
+    // 4. If we were playing, wait for the buffer to fill again and then
+    //    resume. If we were paused, leave it paused at the new position.
+    if (wasPlaying) {
+      await waitForBuffer();
+      await audio.start();
+    }
+  }
+
+  return {
+    strategy: "fallback",
+
+    async play() {
+      // Either a cold start (very first play() call) or a resume from
+      // pause. AudioOutput.start() handles both.
+      if (!audio.isPlaying()) {
+        await waitForBuffer();
+        await audio.start();
+      }
+    },
+
+    pause() {
+      void audio.pause();
+    },
+
+    async seek(time) {
+      await doSeek(time);
+    },
+
+    async setAudioTrack(_id) {
+      // Multi-track audio is post-MVP for the fallback strategy.
+    },
+
+    async setSubtitleTrack(_id) {
+      // Subtitle overlay support is post-MVP for the fallback strategy.
+    },
+
+    getCurrentTime() {
+      return audio.now();
+    },
+    async destroy() {
+      await handles.destroy();
+      renderer.destroy();
+      audio.destroy();
+      try {
+        delete (target as unknown as Record<string, unknown>).currentTime;
+        delete (target as unknown as Record<string, unknown>).duration;
+      } catch { /* ignore */ }
+    },
+
+    getRuntimeStats() {
+      return handles.stats();
+    },
+  };
+}

package/src/strategies/fallback/libav-import.ts

@@ -0,0 +1,27 @@
+/**
+ * Static-import wrapper for the libavjs-webcodecs-bridge optional peer dep.
+ *
+ * The variant itself is **not** imported here — it's loaded via a runtime
+ * dynamic import with `/* @vite-ignore *\/` from `libav-loader.ts`, so the
+ * variant's `.mjs` file is never touched by Vite's transform pipeline (which
+ * would otherwise pre-bundle it and break the `import.meta.url`-based path
+ * resolution it uses to find its sibling .wasm files).
+ *
+ * The bridge has no such issue — it's pure JS and doesn't reference sibling
+ * binaries — so a normal static import is fine here.
+ *
+ * TypeScript resolves `libavjs-webcodecs-bridge` via the `paths` mapping in
+ * tsconfig.json which redirects to `src/libav-stubs.d.ts`, sidestepping the
+ * polyfill source files that don't typecheck under TS 5.7.
+ */
+import * as bridge from "libavjs-webcodecs-bridge";
+
+export const libavBridge: BridgeModule = bridge as unknown as BridgeModule;
+
+export interface BridgeModule {
+  videoStreamToConfig(libav: unknown, stream: unknown): Promise<VideoDecoderConfig | null>;
+  audioStreamToConfig(libav: unknown, stream: unknown): Promise<AudioDecoderConfig | null>;
+  packetToEncodedVideoChunk(pkt: unknown, stream: unknown): EncodedVideoChunk;
+  packetToEncodedAudioChunk(pkt: unknown, stream: unknown): EncodedAudioChunk;
+  libavFrameToVideoFrame?(frame: unknown, stream: unknown): VideoFrame | null;
+}

package/src/strategies/fallback/libav-loader.ts

@@ -0,0 +1,190 @@
+/**
+ * Lazy libav.js loader supporting multiple variants.
+ *
+ * avbridge recognises three libav variants:
+ *
+ * - **webcodecs** — npm `@libav.js/variant-webcodecs`, ~5 MB. Modern formats
+ *   only (mp4/mkv/webm/ogg/wav/...) — designed to bridge to WebCodecs.
+ *
+ * - **default** — npm `@libav.js/variant-default`, ~12 MB. Audio-only build
+ *   (Opus, FLAC, WAV) despite the name. Useful for audio fallback.
+ *
+ * - **avbridge** — a custom build produced by `scripts/build-libav.sh` and
+ *   landing in `vendor/libav/`. Includes the AVI/ASF/FLV/MKV demuxers plus
+ *   the legacy decoders (WMV3, MPEG-4 Part 2, MS-MPEG4 v1/2/3, VC-1, MPEG-1/2,
+ *   AC-3/E-AC-3, WMAv1/v2/Pro). This is the only variant that can read AVI;
+ *   the npm variants are intentionally minimal and ship none of the legacy
+ *   demuxers.
+ *
+ * Variant resolution always goes through a runtime URL + `/* @vite-ignore *\/`
+ * dynamic import. Static imports trigger Vite's optimized-deps pipeline,
+ * which rewrites `import.meta.url` away from the real `dist/` directory and
+ * breaks libav's sibling-binary loading.
+ */
+
+export type LibavVariant = "webcodecs" | "default" | "avbridge";
+
+export interface LoadLibavOptions {
+  /**
+   * Force threading on/off for this load. If unspecified, defaults to
+   * "true if `crossOriginIsolated`, otherwise false". Some libav.js code
+   * paths (notably the cross-thread reader-device protocol used during
+   * `avformat_find_stream_info` for AVI) are unreliable in threaded mode,
+   * so probing forces this to `false` while decode keeps it default.
+   */
+  threads?: boolean;
+}
+
+// Cache key includes both variant and threading mode so probe and decode
+// can run different libav instances of the same variant.
+const cache: Map<string, Promise<LibavInstance>> = new Map();
+
+function cacheKey(variant: LibavVariant, threads: boolean): string {
+  return `${variant}:${threads ? "thr" : "wasm"}`;
+}
+
+/**
+ * Load (and cache) a libav.js variant. Pass `"webcodecs"` for the small
+ * default; pass `"default"` for the audio fallback; pass `"avbridge"` for the
+ * custom build that supports AVI/WMV/legacy codecs.
+ */
+export function loadLibav(
+  variant: LibavVariant = "webcodecs",
+  opts: LoadLibavOptions = {},
+): Promise<LibavInstance> {
+  // Threading is OFF by default. The threaded libav.js variant is too
+  // fragile in practice for our usage:
+  //   - Probe (`avformat_find_stream_info` for AVI) throws an `undefined`
+  //     exception out of `ff_init_demuxer_file`, apparently due to the
+  //     cross-thread reader-device protocol racing with the main thread.
+  //   - Decode hits a `TypeError: Cannot read properties of undefined
+  //     (reading 'apply')` inside libav.js's own worker message handler
+  //     within seconds of starting — a bug in libav.js's threaded message
+  //     dispatch that we can't fix from outside.
+  //
+  // Performance work for the fallback strategy needs to come from elsewhere
+  // (WASM SIMD, OffscreenCanvas, larger decode batches) instead of libav's
+  // pthreads. Threading can still be force-enabled with
+  // `globalThis.AVBRIDGE_LIBAV_THREADS = true` for testing if libav.js fixes
+  // those bugs in a future release.
+  const env = globalThis as { AVBRIDGE_LIBAV_THREADS?: boolean };
+  const wantThreads =
+    opts.threads !== undefined
+      ? opts.threads
+      : env.AVBRIDGE_LIBAV_THREADS === true;
+
+  const key = cacheKey(variant, wantThreads);
+  let entry = cache.get(key);
+  if (!entry) {
+    entry = loadVariant(variant, wantThreads);
+    cache.set(key, entry);
+  }
+  return entry;
+}
+
+async function loadVariant(
+  variant: LibavVariant,
+  wantThreads: boolean,
+): Promise<LibavInstance> {
+  const key = cacheKey(variant, wantThreads);
+  const base = `${libavBaseUrl()}/${variant}`;
+  // The custom variant is named `libav-avbridge.mjs`; the npm variants follow
+  // the same convention (`libav-webcodecs.mjs`, `libav-default.mjs`).
+  const variantUrl = `${base}/libav-${variant}.mjs`;
+
+  let mod: LoadedVariant;
+  try {
+    // @ts-ignore runtime URL
+    const imported: unknown = await import(/* @vite-ignore */ variantUrl);
+    if (!imported || typeof (imported as { LibAV?: unknown }).LibAV !== "function") {
+      throw new Error(`module at ${variantUrl} did not export LibAV`);
+    }
+    mod = imported as LoadedVariant;
+  } catch (err) {
+    cache.delete(key);
+    const hint =
+      variant === "avbridge"
+        ? `The "avbridge" variant is a custom local build. Run \`./scripts/build-libav.sh\` ` +
+          `to produce it (requires Emscripten; ~15-30 min the first time), then ` +
+          `\`npm run predemo\` to copy it into the demo asset path.`
+        : `Make sure the variant files are present (run \`npm run predemo\` or copy ` +
+          `node_modules/@libav.js/variant-${variant}/dist/* into the URL space).`;
+    throw new Error(
+      `failed to load libav.js "${variant}" variant from ${variantUrl}. ${hint} ` +
+        `Original error: ${(err as Error).message || String(err)}`,
+    );
+  }
+
+  try {
+    const inst = (await mod.LibAV(buildOpts(base, wantThreads))) as LibavInstance;
+    await silenceLibavLogs(inst);
+    return inst;
+  } catch (err) {
+    cache.delete(key);
+    throw chain(`LibAV() factory failed for "${variant}" variant (threads=${wantThreads})`, err);
+  }
+}
+
+/**
+ * Lower libav's internal log level so the console doesn't get flooded with
+ * `[mp3 @ ...] Header missing` and `Video uses a non-standard and wasteful
+ * way to store B-frames` warnings on every legacy file. We still get any
+ * actual JS-level errors via the normal Error path; this only affects
+ * libav's own ffmpeg log channel.
+ *
+ * AV_LOG_QUIET = -8 (no output at all). If you want to keep fatal errors,
+ * use AV_LOG_FATAL = 8 instead.
+ */
+async function silenceLibavLogs(inst: LibavInstance): Promise<void> {
+  try {
+    const setLevel = (inst as { av_log_set_level?: (n: number) => Promise<void> })
+      .av_log_set_level;
+    if (typeof setLevel === "function") {
+      const quiet = (inst as { AV_LOG_QUIET?: number }).AV_LOG_QUIET ?? -8;
+      await setLevel(quiet);
+    }
+  } catch {
+    /* not fatal — verbose logs are noise, not an error */
+  }
+}
+
+function buildOpts(base: string, wantThreads: boolean): Record<string, unknown> {
+  // The wantThreads decision is made by `loadLibav()` so callers (probe,
+  // decoder) can override per-load. Decode wants pthreads for speed; probe
+  // forces them off because libav.js's cross-thread reader-device protocol
+  // is unreliable mid-`avformat_find_stream_info` for some AVI files.
+  return {
+    base,
+    nothreads: !wantThreads,
+    yesthreads: wantThreads,
+  };
+}
+
+function libavBaseUrl(): string {
+  const override =
+    typeof globalThis !== "undefined"
+      ? (globalThis as { AVBRIDGE_LIBAV_BASE?: string }).AVBRIDGE_LIBAV_BASE
+      : undefined;
+  if (override) return override;
+  if (typeof location !== "undefined" && location.protocol.startsWith("http")) {
+    return `${location.origin}/libav`;
+  }
+  return "/libav";
+}
+
+function chain(message: string, err: unknown): Error {
+  const inner = err instanceof Error ? err.message : String(err);
+  // eslint-disable-next-line no-console
+  console.error(`[avbridge] ${message}:`, err);
+  return new Error(`${message}: ${inner || "(no message — see browser console)"}`);
+}
+
+interface LoadedVariant {
+  LibAV: (opts?: Record<string, unknown>) => Promise<Record<string, unknown>>;
+}
+
+/** Loose structural type — the AVI probe and the fallback decoder add fields. */
+export type LibavInstance = Record<string, unknown> & {
+  mkreadaheadfile(name: string, blob: Blob): Promise<void>;
+  unlinkreadaheadfile(name: string): Promise<void>;
+};

package/src/strategies/fallback/variant-routing.ts

@@ -0,0 +1,43 @@
+import type { MediaContext, AudioCodec, VideoCodec } from "../../types.js";
+import type { LibavVariant } from "./libav-loader.js";
+
+/**
+ * Decide which libav.js variant to load for a given media context.
+ *
+ * - **webcodecs** (~5 MB, npm) — modern formats only, designed for the
+ *   WebCodecs bridge. Used when the codec is browser-supported and we just
+ *   need libav.js for demuxing or as a parser source.
+ *
+ * - **avbridge** (custom build, vendor/libav/) — has the AVI/ASF/FLV demuxers
+ *   and the legacy decoders (WMV3, MPEG-4 Part 2, VC-1, MS-MPEG4 v1/2/3,
+ *   AC-3, WMA*). Required for any of those formats; the npm variants ship
+ *   none of them.
+ *
+ * Rule: pick "avbridge" if either the container or any codec is one only the
+ * custom build can handle. Otherwise pick "webcodecs".
+ */
+
+const LEGACY_CONTAINERS = new Set(["avi", "asf", "flv"]);
+
+const LEGACY_VIDEO_CODECS = new Set<VideoCodec>([
+  "wmv3",
+  "vc1",
+  "mpeg4", // MPEG-4 Part 2 / DivX / Xvid
+  "rv40",
+  "mpeg2",
+  "mpeg1",
+  "theora",
+]);
+
+const LEGACY_AUDIO_CODECS = new Set<AudioCodec>(["wmav2", "wmapro", "ac3", "eac3"]);
+
+export function pickLibavVariant(ctx: MediaContext): LibavVariant {
+  if (LEGACY_CONTAINERS.has(ctx.container)) return "avbridge";
+  for (const v of ctx.videoTracks) {
+    if (LEGACY_VIDEO_CODECS.has(v.codec)) return "avbridge";
+  }
+  for (const a of ctx.audioTracks) {
+    if (LEGACY_AUDIO_CODECS.has(a.codec)) return "avbridge";
+  }
+  return "webcodecs";
+}

package/src/strategies/fallback/video-renderer.ts

@@ -0,0 +1,216 @@
+import type { ClockSource } from "./audio-output.js";
+
+/**
+ * Renders decoded `VideoFrame`s into a 2D canvas overlaid on the user's
+ * `<video>` element. The fallback strategy never assigns a src to the video,
+ * so we hide it and put the canvas in its place visually.
+ *
+ * The renderer has two modes:
+ *
+ * 1. **Pre-roll** — `clock.isPlaying()` is false. The very first decoded
+ *    frame is painted as a "poster" so the user sees something while audio
+ *    buffers; subsequent frames stay queued without being dropped.
+ *
+ * 2. **Synced** — `clock.isPlaying()` is true. On each rAF tick, find the
+ *    latest frame whose timestamp ≤ `clock.now() + lookahead` and paint it.
+ *    Drop any older frames as "late."
+ *
+ * The pre-roll behavior is what fixes the cold-start "first minute is all
+ * dropped" problem: without it, the wall clock raced ahead while the
+ * decoder was still warming up, and every frame was already in the past by
+ * the time it landed in the queue.
+ */
+export class VideoRenderer {
+  private canvas: HTMLCanvasElement;
+  private ctx: CanvasRenderingContext2D;
+  private queue: VideoFrame[] = [];
+  private rafHandle: number | null = null;
+  private destroyed = false;
+
+  private framesPainted = 0;
+  private framesDroppedLate = 0;
+  private framesDroppedOverflow = 0;
+  private prerolled = false;
+  /** Wall-clock time of the last paint, in ms (performance.now()). */
+  private lastPaintWall = 0;
+  /** Minimum ms between paints — paces video at roughly source fps. */
+  private paintIntervalMs: number;
+
+  /** Resolves once the first decoded frame has been enqueued. */
+  readonly firstFrameReady: Promise<void>;
+  private resolveFirstFrame!: () => void;
+
+  constructor(
+    private readonly target: HTMLVideoElement,
+    private readonly clock: ClockSource,
+    fps = 30,
+  ) {
+    this.paintIntervalMs = Math.max(1, 1000 / fps);
+    this.firstFrameReady = new Promise<void>((resolve) => {
+      this.resolveFirstFrame = resolve;
+    });
+
+    this.canvas = document.createElement("canvas");
+    this.canvas.style.cssText =
+      "position:absolute;left:0;top:0;width:100%;height:100%;background:black;";
+    const parent = target.parentElement;
+    if (parent && getComputedStyle(parent).position === "static") {
+      parent.style.position = "relative";
+    }
+    parent?.insertBefore(this.canvas, target);
+    target.style.visibility = "hidden";
+
+    const ctx = this.canvas.getContext("2d");
+    if (!ctx) throw new Error("video renderer: failed to acquire 2D context");
+    this.ctx = ctx;
+
+    this.tick = this.tick.bind(this);
+    this.rafHandle = requestAnimationFrame(this.tick);
+  }
+
+  /** True once at least one frame has been enqueued. */
+  hasFrames(): boolean {
+    return this.queue.length > 0 || this.framesPainted > 0;
+  }
+
+  /** Current depth of the frame queue. Used by the decoder for backpressure. */
+  queueDepth(): number {
+    return this.queue.length;
+  }
+
+  /**
+   * Soft cap for decoder backpressure. The decoder pump throttles when
+   * `queueDepth() >= queueHighWater`. Set high enough that normal decode
+   * bursts don't trigger the renderer's overflow-drop loop (which runs at
+   * every paint), but low enough that the decoder doesn't run unboundedly
+   * ahead. The hard cap in `enqueue()` is 64.
+   */
+  readonly queueHighWater = 30;
+
+  enqueue(frame: VideoFrame): void {
+    if (this.destroyed) {
+      frame.close();
+      return;
+    }
+    this.queue.push(frame);
+    if (this.queue.length === 1 && this.framesPainted === 0) {
+      this.resolveFirstFrame();
+    }
+    // Hard cap. Should rarely trigger because the decoder backs off at
+    // queueHighWater (30) and the drift correction trims gently. This is
+    // the last-resort defense against runaway producers.
+    while (this.queue.length > 60) {
+      this.queue.shift()?.close();
+      this.framesDroppedOverflow++;
+    }
+  }
+
+  private tick(): void {
+    if (this.destroyed) return;
+    this.rafHandle = requestAnimationFrame(this.tick);
+
+    if (this.queue.length === 0) return;
+
+    const playing = this.clock.isPlaying();
+
+    // Pre-roll: paint the very first frame as a poster while audio buffers.
+    if (!playing) {
+      if (!this.prerolled) {
+        const head = this.queue.shift()!;
+        this.paint(head);
+        head.close();
+        this.prerolled = true;
+        this.lastPaintWall = performance.now();
+      }
+      return;
+    }
+
+    // Wall-clock-paced painting with coarse A/V drift correction.
+    //
+    // Base policy: paint one frame every `paintIntervalMs` of wall time,
+    // regardless of the frame's synthetic timestamp. This avoids the old
+    // per-frame audio-gate that caused massive overflow during decode bursts.
+    //
+    // Drift correction (runs every ~1 sec):
+    //   - Video > 150 ms behind audio → drop one frame (catch up)
+    //   - Video > 150 ms ahead of audio → skip one paint (let audio catch up)
+    //
+    // This keeps long-run sync robust even for legacy AVI/DivX with messy
+    // timestamps, packed B-frames, and odd frame durations. The correction
+    // is deliberately gentle (one frame at a time) so it doesn't cause
+    // visible stuttering.
+    const wallNow = performance.now();
+    if (wallNow - this.lastPaintWall < this.paintIntervalMs - 2) return;
+
+    if (this.queue.length === 0) return;
+
+    // Coarse drift correction: compare the head frame's timestamp to
+    // audio.now() every ~1 sec (every 30 frames at 30fps). The frame ts
+    // and audio.now() are both in seconds of media time. Drift beyond
+    // 150ms triggers gentle correction — one frame per check, not a burst.
+    if (this.framesPainted > 0 && this.framesPainted % 30 === 0) {
+      const audioNowUs = this.clock.now() * 1_000_000;
+      const headTs = this.queue[0].timestamp ?? 0;
+      const driftUs = headTs - audioNowUs;
+
+      if (driftUs < -150_000) {
+        // Video behind audio by > 150ms — drop one frame to catch up.
+        this.queue.shift()?.close();
+        this.framesDroppedLate++;
+        if (this.queue.length === 0) return;
+      } else if (driftUs > 150_000) {
+        // Video ahead of audio by > 150ms — skip this paint cycle.
+        return;
+      }
+    }
+
+    const frame = this.queue.shift()!;
+    this.paint(frame);
+    frame.close();
+    this.lastPaintWall = wallNow;
+  }
+
+  private paint(frame: VideoFrame): void {
+    if (
+      this.canvas.width !== frame.displayWidth ||
+      this.canvas.height !== frame.displayHeight
+    ) {
+      this.canvas.width = frame.displayWidth;
+      this.canvas.height = frame.displayHeight;
+    }
+    try {
+      this.ctx.drawImage(frame, 0, 0, this.canvas.width, this.canvas.height);
+      this.framesPainted++;
+    } catch (err) {
+      // Log only once so a structurally broken frame format doesn't spam
+      // the console at 60 Hz, but we still find out about it.
+      if (this.framesPainted === 0 && this.framesDroppedLate === 0) {
+        // eslint-disable-next-line no-console
+        console.warn("[avbridge] canvas drawImage failed:", err);
+      }
+    }
+  }
+
+  /** Discard all queued frames. Used by seek to drop stale buffers. */
+  flush(): void {
+    while (this.queue.length > 0) this.queue.shift()?.close();
+    this.prerolled = false;
+  }
+
+  stats(): Record<string, unknown> {
+    return {
+      framesPainted: this.framesPainted,
+      framesDroppedLate: this.framesDroppedLate,
+      framesDroppedOverflow: this.framesDroppedOverflow,
+      queueDepth: this.queue.length,
+    };
+  }
+
+  destroy(): void {
+    this.destroyed = true;
+    if (this.rafHandle != null) cancelAnimationFrame(this.rafHandle);
+    this.flush();
+    this.canvas.remove();
+    this.target.style.visibility = "";
+  }
+}