avbridge 2.7.0 → 2.8.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "avbridge",
-  "version": "2.7.0",
+  "version": "2.8.2",
   "description": "Play and convert arbitrary video files in the browser. Native, remux, hybrid, fallback, and transcode — one API.",
   "license": "MIT",
   "author": "Keishi Hattori",

package/src/classify/rules.ts

@@ -195,6 +195,29 @@ export function classifyContext(ctx: MediaContext): Classification {
   // Remuxing goes through mediabunny, which only supports certain containers.
   // AVI/ASF/FLV are NOT in that set — mediabunny rejects them at Input().
   if (REMUXABLE_CONTAINERS.has(ctx.container)) {
+    // Feature-detect: the remux target is fragmented MP4 via MSE. If the
+    // browser's MSE can't decode this codec combo (e.g. HEVC on
+    // open-source Chromium — no proprietary codecs by design — or
+    // future codec/container combos we haven't thought of), remux will
+    // stall. Degrade gracefully: try hybrid (WebCodecs hardware decode)
+    // or fallback (WASM software decode) without waiting for runtime
+    // escalation.
+    const mime = mp4MimeFor(video, audio);
+    if (mime && typeof MediaSource !== "undefined" && !mseSupports(mime)) {
+      if (webCodecsAvailable()) {
+        return {
+          class: "HYBRID_CANDIDATE",
+          strategy: "hybrid",
+          reason: `${ctx.container} container with ${video.codec}${audio ? "/" + audio.codec : ""}; MSE rejects the remux target mime — routing to WebCodecs hardware decode`,
+          fallbackChain: ["fallback"],
+        };
+      }
+      return {
+        class: "FALLBACK_REQUIRED",
+        strategy: "fallback",
+        reason: `${ctx.container} container with ${video.codec}${audio ? "/" + audio.codec : ""}; MSE rejects the remux target mime and WebCodecs is unavailable — falling back to WASM decode`,
+      };
+    }
     return {
       class: "REMUX_CANDIDATE",
       strategy: "remux",

package/src/element/avbridge-player.ts

@@ -58,12 +58,19 @@ const FORWARDED_EVENTS = [
 const PROXY_ATTRIBUTES = [
   "src", "autoplay", "muted", "loop", "preload", "poster",
   "playsinline", "crossorigin", "disableremoteplayback", "preferstrategy",
+  "fit",
 ] as const;
 
+/** Player-only attributes that don't forward to <avbridge-video>. */
+const PLAYER_ATTRIBUTES = ["show-fit"] as const;
+
+const FIT_MODES = ["contain", "cover", "fill"] as const;
+type FitMode = (typeof FIT_MODES)[number];
+
 // ═══════════════════════════════════════════════════════════════════════════
 
 export class AvbridgePlayerElement extends HTMLElement {
-  static readonly observedAttributes = [...PROXY_ATTRIBUTES];
+  static readonly observedAttributes = [...PROXY_ATTRIBUTES, ...PLAYER_ATTRIBUTES];
 
   // ── Internal DOM refs ──────────────────────────────────────────────────
 
@@ -102,6 +109,8 @@ export class AvbridgePlayerElement extends HTMLElement {
   private _statsEl!: HTMLDivElement;
   private _statsInterval: ReturnType<typeof setInterval> | null = null;
   private _eventCleanup: (() => void)[] = [];
+  private _updateToolbarEmpty: () => void = () => { /* wired in constructor */ };
+  private _toolbarTop!: HTMLDivElement;
 
   // ── Constructor ────────────────────────────────────────────────────────
 
@@ -131,6 +140,21 @@ export class AvbridgePlayerElement extends HTMLElement {
     this._statsEl = shadow.querySelector(".avp-stats") as HTMLDivElement;
     this._rippleLeft = shadow.querySelector(".avp-ripple-left") as HTMLDivElement;
     this._rippleRight = shadow.querySelector(".avp-ripple-right") as HTMLDivElement;
+    this._toolbarTop = shadow.querySelector('[part="toolbar-top"]') as HTMLDivElement;
+    // Start visible — controls are shown until the auto-hide timer fires.
+    this._toolbarTop.setAttribute("data-visible", "true");
+
+    // Track whether the top toolbar has any slotted content. Used to hide
+    // its gradient when empty (see data-toolbar-empty in player-styles.ts).
+    // MUST defer the initial attribute write to connectedCallback — the
+    // Custom Elements spec forbids constructors from adding attributes.
+    const slots = shadow.querySelectorAll<HTMLSlotElement>('slot[name="top-left"], slot[name="top-right"]');
+    this._updateToolbarEmpty = () => {
+      const hasContent = Array.from(slots).some((s) => s.assignedNodes({ flatten: true }).length > 0);
+      if (hasContent) this.removeAttribute("data-toolbar-empty");
+      else this.setAttribute("data-toolbar-empty", "");
+    };
+    for (const s of slots) s.addEventListener("slotchange", this._updateToolbarEmpty);
 
     this._bindEvents();
   }
@@ -139,6 +163,10 @@ export class AvbridgePlayerElement extends HTMLElement {
     return `
 <div part="container" class="avp">
   <avbridge-video part="video"></avbridge-video>
+  <div part="toolbar-top" class="avp-toolbar-top">
+    <div part="toolbar-top-left" class="avp-toolbar-top-left"><slot name="top-left"></slot></div>
+    <div part="toolbar-top-right" class="avp-toolbar-top-right"><slot name="top-right"></slot></div>
+  </div>
   <div part="overlay" class="avp-overlay">
     <button class="avp-overlay-btn" aria-label="Play">${ICON_PLAY}</button>
     <div class="avp-spinner"></div>
@@ -326,17 +354,20 @@ export class AvbridgePlayerElement extends HTMLElement {
 
     // Keyboard
     on(this, "keydown", (e) => this._onKeydown(e as KeyboardEvent));
-
-    // Make focusable for keyboard events
-    if (!this.hasAttribute("tabindex")) {
-      this.setAttribute("tabindex", "0");
-    }
   }
 
   // ── Lifecycle ──────────────────────────────────────────────────────────
 
   connectedCallback(): void {
     this._setState("idle");
+    // Attribute writes the Custom Elements spec forbids in constructors
+    // — document.createElement rejects with "The result must not have
+    // attributes" — deferred here. Surfaced by the Playwright
+    // cross-browser tests.
+    if (!this.hasAttribute("tabindex")) {
+      this.setAttribute("tabindex", "0");
+    }
+    this._updateToolbarEmpty();
   }
 
   disconnectedCallback(): void {
@@ -344,8 +375,15 @@ export class AvbridgePlayerElement extends HTMLElement {
   }
 
   attributeChangedCallback(name: string, _old: string | null, value: string | null): void {
-    // Proxy attributes down to inner avbridge-video
     if (!this._video) return;
+    // Player-only attributes — not forwarded to the inner <avbridge-video>.
+    if ((PLAYER_ATTRIBUTES as readonly string[]).includes(name)) {
+      if (name === "show-fit" && this._settingsOpen) {
+        this._buildSettingsMenu();
+      }
+      return;
+    }
+    // Proxy everything else down.
     if (value == null) this._video.removeAttribute(name);
     else this._video.setAttribute(name, value);
   }
@@ -499,6 +537,20 @@ export class AvbridgePlayerElement extends HTMLElement {
   private _buildSettingsMenu(): void {
     const sections: string[] = [];
 
+    // Fit mode — opt-in via the `show-fit` attribute. Off by default so
+    // chromeless consumers don't get a surprise entry they have to theme
+    // around.
+    if (this.hasAttribute("show-fit")) {
+      const currentFit = (this._video.fit ?? "contain") as FitMode;
+      let fitItems = "";
+      for (const mode of FIT_MODES) {
+        const active = mode === currentFit;
+        const label = mode[0].toUpperCase() + mode.slice(1);
+        fitItems += `<div class="avp-settings-item${active ? " active" : ""}" data-fit="${mode}">${label}</div>`;
+      }
+      sections.push(`<div class="avp-settings-section"><div class="avp-settings-label">Fit</div>${fitItems}</div>`);
+    }
+
     // Playback speed
     const currentRate = this._video.playbackRate ?? 1;
     let speedItems = "";
@@ -535,6 +587,14 @@ export class AvbridgePlayerElement extends HTMLElement {
     this._settingsMenu.innerHTML = sections.join("");
 
     // Bind click handlers
+    for (const item of this._settingsMenu.querySelectorAll("[data-fit]")) {
+      item.addEventListener("click", (e) => {
+        e.stopPropagation();
+        const mode = (item as HTMLElement).dataset.fit as FitMode;
+        this.setAttribute("fit", mode);
+        this._buildSettingsMenu();
+      });
+    }
     for (const item of this._settingsMenu.querySelectorAll("[data-speed]")) {
       item.addEventListener("click", (e) => {
         e.stopPropagation();
@@ -622,6 +682,7 @@ export class AvbridgePlayerElement extends HTMLElement {
 
   private _showControls(): void {
     this.removeAttribute("data-controls-hidden");
+    this._toolbarTop.setAttribute("data-visible", "true");
     this._scheduleHide();
   }
 
@@ -632,6 +693,7 @@ export class AvbridgePlayerElement extends HTMLElement {
     this._controlsTimer = setTimeout(() => {
       if (this._state === "playing") {
         this.setAttribute("data-controls-hidden", "");
+        this._toolbarTop.setAttribute("data-visible", "false");
       }
     }, CONTROLS_HIDE_MS);
   }
@@ -649,9 +711,21 @@ export class AvbridgePlayerElement extends HTMLElement {
   /** Track whether the last interaction was touch so click handler can skip. */
   private _lastPointerTypeWasTouch = false;
 
+  /** True if the event's composed path passes through consumer-slotted toolbar
+   *  content. Slotted content lives in the light DOM so `.closest(".avp-toolbar-top")`
+   *  on the event target won't find the shadow-DOM wrapper — `composedPath()`
+   *  does. */
+  private _isToolbarEvent(e: Event): boolean {
+    for (const node of e.composedPath()) {
+      if (node instanceof HTMLElement && node.classList.contains("avp-toolbar-top")) return true;
+    }
+    return false;
+  }
+
   private _onContainerClick(e: MouseEvent): void {
     // Ignore clicks on controls
     if ((e.target as HTMLElement).closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
+    if (this._isToolbarEvent(e)) return;
 
     // Touch taps are handled by _onPointerUp (show/hide controls + double-tap).
     // The browser fires a synthetic click after touchend — skip it.
@@ -670,6 +744,7 @@ export class AvbridgePlayerElement extends HTMLElement {
 
   private _onContainerDblClick(e: MouseEvent): void {
     if ((e.target as HTMLElement).closest?.(".avp-controls, .avp-settings")) return;
+    if (this._isToolbarEvent(e)) return;
     // Cancel the pending single-click play/pause
     if (this._tapTimer) { clearTimeout(this._tapTimer); this._tapTimer = null; }
     this._toggleFullscreen();
@@ -695,6 +770,7 @@ export class AvbridgePlayerElement extends HTMLElement {
 
     // Ignore touches on controls — buttons have their own handlers
     if ((e.target as HTMLElement).closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
+    if (this._isToolbarEvent(e)) return;
 
     // Double-tap detection
     const now = Date.now();

package/src/element/avbridge-video.ts

@@ -10,8 +10,9 @@
  *   3. Give consumers a `<video>`-compatible primitive they can wrap with
  *      their own UI.
  *
- * **It is not a player UI framework.** The tag name `<avbridge-player>` is
- * reserved for a future controls-bearing element. See
+ * **It is not a player UI framework.** For YouTube-style chrome (seek
+ * bar, play/pause, settings menu, fullscreen, auto-hiding controls) use
+ * `<avbridge-player>` — it wraps this element with a full UI. See
  * `docs/dev/WEB_COMPONENT_SPEC.md` for the full spec, lifecycle invariants,
  * and edge case list.
  */
@@ -38,6 +39,11 @@ const PREFERRED_STRATEGY_VALUES = new Set<PreferredStrategy>([
   "fallback",
 ]);
 
+/** Fit mode — how the video fills the element's box. Mirrors CSS object-fit. */
+type FitMode = "contain" | "cover" | "fill";
+const FIT_VALUES = new Set<FitMode>(["contain", "cover", "fill"]);
+const DEFAULT_FIT: FitMode = "contain";
+
 /**
  * Standard `HTMLMediaElement` events we forward from the inner `<video>`
  * to the wrapper element so consumers can `el.addEventListener("loadedmetadata", ...)`
@@ -110,6 +116,8 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
     "disableremoteplayback",
     "diagnostics",
     "preferstrategy",
+    "fit",
+    "no-orientation-lock",
   ];
 
   // ── Internal state ─────────────────────────────────────────────────────
@@ -172,6 +180,14 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
    */
   private _preferredStrategy: PreferredStrategy = "auto";
 
+  /** Current fit mode. Applied to the inner `<video>` via object-fit, and
+   *  to the fallback canvas via the `--avbridge-fit` CSS custom property on
+   *  the stage wrapper (see `src/strategies/fallback/video-renderer.ts`). */
+  private _fit: FitMode = DEFAULT_FIT;
+  /** The stage wrapper — the element the canvas attaches into, and where
+   *  the `--avbridge-fit` CSS custom property lives. */
+  private _stageEl!: HTMLDivElement;
+
   /** Set if currentTime was assigned before the player was ready. */
   private _pendingSeek: number | null = null;
   /** Set if play() was called before the player was ready. */
@@ -180,6 +196,14 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
   /** MutationObserver tracking light-DOM `<track>` children. */
   private _trackObserver: MutationObserver | null = null;
 
+  /** Document-level fullscreenchange handler — installed while connected so
+   *  the element can lock/unlock screen orientation to match the video's
+   *  intrinsic aspect. */
+  private _fullscreenChangeHandler: (() => void) | null = null;
+  /** True if we successfully called screen.orientation.lock() on the last
+   *  fullscreen entry. Used to know whether to unlock on exit. */
+  private _orientationLocked = false;
+
   // ── Construction & lifecycle ───────────────────────────────────────────
 
   constructor() {
@@ -193,12 +217,13 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
     // not an Element) and the canvas would never attach to the DOM.
     const stage = document.createElement("div");
     stage.setAttribute("part", "stage");
-    stage.style.cssText = "position:relative;width:100%;height:100%;display:block;";
+    stage.style.cssText = `position:relative;width:100%;height:100%;display:block;--avbridge-fit:${DEFAULT_FIT};`;
     root.appendChild(stage);
+    this._stageEl = stage;
 
     this._videoEl = document.createElement("video");
     this._videoEl.setAttribute("part", "video");
-    this._videoEl.style.cssText = "width:100%;height:100%;display:block;background:#000;";
+    this._videoEl.style.cssText = `width:100%;height:100%;display:block;background:#000;object-fit:var(--avbridge-fit, ${DEFAULT_FIT});`;
     this._videoEl.playsInline = true;
     stage.appendChild(this._videoEl);
 
@@ -233,6 +258,10 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
       this._trackObserver = new MutationObserver(() => this._syncTextTracks());
       this._trackObserver.observe(this, { childList: true, subtree: false });
     }
+    if (!this._fullscreenChangeHandler) {
+      this._fullscreenChangeHandler = () => this._onFullscreenChange();
+      document.addEventListener("fullscreenchange", this._fullscreenChangeHandler);
+    }
     // Connection is the trigger for bootstrap. If we have a pending source
     // (set before connect), kick off bootstrap now.
     const source = this._activeSource();
@@ -247,6 +276,13 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
       this._trackObserver.disconnect();
       this._trackObserver = null;
     }
+    if (this._fullscreenChangeHandler) {
+      document.removeEventListener("fullscreenchange", this._fullscreenChangeHandler);
+      this._fullscreenChangeHandler = null;
+    }
+    // If we were fullscreen via some ancestor and got disconnected, release
+    // any orientation lock we had taken.
+    this._releaseOrientationLock();
     // Bump the bootstrap token so any in-flight async work is invalidated
     // before we tear down. _teardown() also bumps but we want the bump to
     // happen synchronously here so any awaited promise that resolves
@@ -287,6 +323,16 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
           this._preferredStrategy = "auto";
         }
         break;
+      case "fit": {
+        const next: FitMode = newValue && FIT_VALUES.has(newValue as FitMode)
+          ? (newValue as FitMode)
+          : DEFAULT_FIT;
+        if (next === this._fit) break;
+        this._fit = next;
+        this._stageEl.style.setProperty("--avbridge-fit", next);
+        this._dispatch("fitchange", { fit: next });
+        break;
+      }
     }
   }
 
@@ -587,6 +633,15 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
     else this.removeAttribute("diagnostics");
   }
 
+  get fit(): FitMode {
+    return this._fit;
+  }
+
+  set fit(value: FitMode) {
+    if (!FIT_VALUES.has(value)) return;
+    this.setAttribute("fit", value);
+  }
+
   get preferredStrategy(): PreferredStrategy {
     return this._preferredStrategy;
   }
@@ -796,6 +851,95 @@ export class AvbridgeVideoElement extends HTMLElementCtor {
     );
   }
 
+  /**
+   * Disable the automatic `screen.orientation.lock()` that runs on
+   * fullscreen entry. Set when you want to honor the device's native
+   * auto-rotate instead of matching the video's intrinsic orientation.
+   */
+  get noOrientationLock(): boolean {
+    return this.hasAttribute("no-orientation-lock");
+  }
+
+  set noOrientationLock(value: boolean) {
+    if (value) this.setAttribute("no-orientation-lock", "");
+    else this.removeAttribute("no-orientation-lock");
+  }
+
+  // ── Fullscreen orientation lock ────────────────────────────────────────
+
+  /** Called whenever `document.fullscreenchange` fires. If this element (or
+   *  any of its ancestors) is now fullscreen, derive the target orientation
+   *  from the video's intrinsic size and call `screen.orientation.lock()`.
+   *  On exit, release the lock we took. iOS Safari rejects `lock()` — we
+   *  swallow the rejection so nothing breaks on that path. */
+  private _onFullscreenChange(): void {
+    if (this._destroyed) return;
+    const fsEl = document.fullscreenElement;
+    const nowFullscreen = fsEl != null && this._isInsideOrEquals(fsEl);
+    if (nowFullscreen && !this._orientationLocked) {
+      if (this.noOrientationLock) return;
+      const target = this._desiredOrientation();
+      if (!target) return; // square or unknown — don't lock
+      void this._lockOrientation(target);
+    } else if (!nowFullscreen && this._orientationLocked) {
+      this._releaseOrientationLock();
+    }
+  }
+
+  /** Walk composed-tree ancestors to see if `target` is this element or
+   *  any ancestor across shadow boundaries. `Node.contains()` can't cross
+   *  shadow roots, so when `<avbridge-player>` (the fullscreen element)
+   *  hosts this `<avbridge-video>` inside its shadow DOM, `contains()`
+   *  returns false. */
+  private _isInsideOrEquals(target: Element): boolean {
+    let node: Node | null = this;
+    while (node) {
+      if (node === target) return true;
+      const parent: Node | null = node.parentNode;
+      if (parent instanceof ShadowRoot) node = parent.host;
+      else node = parent;
+    }
+    return false;
+  }
+
+  /** Derive "landscape" / "portrait" from the intrinsic video dimensions.
+   *  Returns null when dimensions aren't known yet or the video is square.
+   *  Uses `videoWidth` / `videoHeight` from the inner `<video>`, which the
+   *  browser sets to the display-aspect-corrected size (so anamorphic
+   *  content is judged by its display aspect, not pixel aspect). */
+  private _desiredOrientation(): "landscape" | "portrait" | null {
+    const w = this._videoEl.videoWidth;
+    const h = this._videoEl.videoHeight;
+    if (!w || !h) return null;
+    if (w === h) return null;
+    return w > h ? "landscape" : "portrait";
+  }
+
+  /** Attempt to lock screen orientation. Swallows rejections — iOS Safari
+   *  doesn't implement `lock()`, and desktop / non-fullscreen contexts will
+   *  reject too. Records success so we know whether to unlock on exit. */
+  private async _lockOrientation(target: "landscape" | "portrait"): Promise<void> {
+    const so = (screen as Screen & {
+      orientation?: ScreenOrientation & { lock?: (o: string) => Promise<void> };
+    }).orientation;
+    if (!so || typeof so.lock !== "function") return;
+    try {
+      await so.lock(target);
+      this._orientationLocked = true;
+    } catch {
+      // iOS Safari, desktop, or user denied — ignore.
+    }
+  }
+
+  private _releaseOrientationLock(): void {
+    if (!this._orientationLocked) return;
+    this._orientationLocked = false;
+    const so = screen.orientation as ScreenOrientation | undefined;
+    if (so && typeof so.unlock === "function") {
+      try { so.unlock(); } catch { /* ignore */ }
+    }
+  }
+
   // ── Public methods ─────────────────────────────────────────────────────
 
   /** Force a (re-)bootstrap if a source is currently set. */

package/src/element/player-styles.ts

@@ -197,6 +197,50 @@ export const PLAYER_STYLES = /* css */ `
 
 :host([data-controls-hidden]) { cursor: none; }
 
+/* ── Top toolbar (slotted consumer chrome) ─────────────────────────────
+   Two named slots (top-left, top-right) let consumers place back / title /
+   translate buttons inside the auto-hide chrome. Wrapper has
+   pointer-events:none so empty slots don't block container clicks; each
+   side re-enables pointer-events so real buttons remain interactive. */
+
+.avp-toolbar-top {
+  position: absolute;
+  top: 0;
+  left: 0;
+  right: 0;
+  z-index: 5;
+  padding: 8px 12px 24px;
+  background: linear-gradient(rgba(0, 0, 0, 0.6), transparent);
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 8px;
+  opacity: 1;
+  pointer-events: none;
+  transition: opacity 0.25s;
+}
+
+.avp-toolbar-top-left,
+.avp-toolbar-top-right {
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  pointer-events: auto;
+}
+
+.avp-toolbar-top-right { margin-left: auto; }
+
+/* Hide the gradient band when no consumer has slotted anything — we
+   toggle data-toolbar-empty from JS via slotchange. */
+:host([data-toolbar-empty]) .avp-toolbar-top {
+  background: none;
+}
+
+:host([data-controls-hidden]) .avp-toolbar-top {
+  opacity: 0;
+  pointer-events: none;
+}
+
 /* ── Seek bar ─────────────────────────────────────────────────────────── */
 
 .avp-seek {

package/src/element.ts

@@ -9,9 +9,9 @@
  * The registration is guarded so re-importing this module (e.g. via HMR or
  * multiple bundles) does not throw a "name already defined" error.
  *
- * The tag name `<avbridge-player>` is reserved for a future controls-bearing
- * element. Today, only `<avbridge-video>` (the bare HTMLMediaElement-compatible
- * primitive) is registered.
+ * Only `<avbridge-video>` (the bare HTMLMediaElement-compatible primitive)
+ * is registered here. The chrome-bearing `<avbridge-player>` lives at the
+ * `avbridge/player-element` subpath.
  */
 
 import { AvbridgeVideoElement } from "./element/avbridge-video.js";

package/src/strategies/fallback/decoder.ts

@@ -59,7 +59,16 @@ export interface StartDecoderOptions {
 }
 
 export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHandles> {
-  const variant: LibavVariant = pickLibavVariant(opts.context);
+  // Fallback always does full software decode. The "webcodecs" libav
+  // variant is trimmed to demuxing + WebCodecs-companion use; it lacks
+  // software decoders for codecs whose browsers usually handle them
+  // (e.g. h265). When we've reached fallback for those codecs, it's
+  // precisely because the browser *can't* decode them — so we need
+  // the full "avbridge" variant with software decoders. pickLibavVariant
+  // is still right for the hybrid strategy (which software-decodes only
+  // audio and relies on WebCodecs for video), but not here.
+  const variant: LibavVariant = "avbridge";
+  void pickLibavVariant; // kept in scope for future opt-in use
   const libav = (await loadLibav(variant)) as unknown as LibavRuntime;
   const bridge = await loadBridge();
 
@@ -137,13 +146,11 @@ export async function startDecoder(opts: StartDecoderOptions): Promise<DecoderHa
       videoStream ? `video: ${opts.context.videoTracks[0]?.codec ?? "unknown"}` : null,
       audioStream ? `audio: ${opts.context.audioTracks[0]?.codec ?? "unknown"}` : null,
     ].filter(Boolean).join(", ");
-    const hint = variant === "webcodecs"
-      ? ` The "${variant}" libav variant does not include software decoders for these codecs. ` +
-        `Try the custom "avbridge" variant (scripts/build-libav.sh) for broader codec support, ` +
-        `or use a lighter strategy (native, remux, hybrid) instead.`
-      : "";
     throw new Error(
-      `fallback decoder: could not initialize any libav decoders (${codecs}).${hint}`,
+      `fallback decoder: could not initialize any libav decoders (${codecs}). ` +
+      `The "${variant}" libav variant lacks software decoders for these codecs — ` +
+      `rebuild with scripts/build-libav.sh including the missing decoder, ` +
+      `or use a lighter strategy (native, remux, hybrid) instead.`,
     );
   }
 

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

@@ -84,12 +84,14 @@ export class VideoRenderer {
     });
 
     this.canvas = document.createElement("canvas");
-    // object-fit:contain letterboxes the canvas bitmap (sized to
-    // frame.displayWidth × displayHeight in paint()) inside the stage so
-    // portrait / non-stage-aspect content isn't stretched. Canvas is a
-    // replaced element, so object-fit applies.
+    // `object-fit` is driven by the `--avbridge-fit` custom property so the
+    // `<avbridge-video>` element's `fit` attribute can retarget the canvas
+    // without reaching into the fallback strategy. Default is `contain` —
+    // letterboxes the canvas bitmap (sized to frame.displayWidth ×
+    // displayHeight in paint()) inside the stage so portrait / non-stage-aspect
+    // content isn't stretched. Canvas is a replaced element, so object-fit applies.
     this.canvas.style.cssText =
-      "position:absolute;left:0;top:0;width:100%;height:100%;background:black;object-fit:contain;";
+      "position:absolute;left:0;top:0;width:100%;height:100%;background:black;object-fit:var(--avbridge-fit, contain);";
 
     // Attach the canvas next to the video. When the video lives inside an
     // `<avbridge-video>` shadow root, `target.parentElement` is the

package/src/types.ts

@@ -342,6 +342,7 @@ export interface AvbridgeVideoElementEventMap {
   error: CustomEvent<{ error: Error; diagnostics: DiagnosticsSnapshot | null }>;
   progress: CustomEvent<{ buffered: TimeRanges }>;
   loadstart: CustomEvent<Record<string, never>>;
+  fitchange: CustomEvent<{ fit: "contain" | "cover" | "fill" }>;
 }
 
 // ── Conversion types ────────────────────────────────────────────────────