avbridge 2.6.0 → 2.8.1

package/dist/player.d.cts

@@ -283,6 +283,9 @@ interface AvbridgeVideoElementEventMap {
         buffered: TimeRanges;
     }>;
     loadstart: CustomEvent<Record<string, never>>;
+    fitchange: CustomEvent<{
+        fit: "contain" | "cover" | "fill";
+    }>;
 }
 
 /**
@@ -297,7 +300,7 @@ interface AvbridgeVideoElementEventMap {
  */
 
 declare class AvbridgePlayerElement extends HTMLElement {
-    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy")[];
+    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy" | "fit")[];
     private _video;
     private _playBtn;
     private _overlayBtn;
@@ -328,6 +331,7 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _statsEl;
     private _statsInterval;
     private _eventCleanup;
+    private _updateToolbarEmpty;
     constructor();
     private _template;
     private _bindEvents;
@@ -357,6 +361,11 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _scheduleHide;
     /** Track whether the last interaction was touch so click handler can skip. */
     private _lastPointerTypeWasTouch;
+    /** 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;
     private _onContainerClick;
     private _onContainerDblClick;
     private _onPointerDown;
@@ -506,14 +515,17 @@ declare class UnifiedPlayer {
  *   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.
  */
 
 /** Strategy preference passed via the `preferstrategy` attribute. */
 type PreferredStrategy = "auto" | StrategyName;
+/** Fit mode — how the video fills the element's box. Mirrors CSS object-fit. */
+type FitMode = "contain" | "cover" | "fill";
 /**
  * `HTMLElement` is a browser-only global. SSR frameworks (Next.js, Astro,
  * Remix, etc.) commonly import library modules on the server to extract
@@ -586,12 +598,26 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
      * native fails.
      */
     private _preferredStrategy;
+    /** 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;
+    /** The stage wrapper — the element the canvas attaches into, and where
+     *  the `--avbridge-fit` CSS custom property lives. */
+    private _stageEl;
     /** Set if currentTime was assigned before the player was ready. */
     private _pendingSeek;
     /** Set if play() was called before the player was ready. */
     private _pendingPlay;
     /** MutationObserver tracking light-DOM `<track>` children. */
     private _trackObserver;
+    /** Document-level fullscreenchange handler — installed while connected so
+     *  the element can lock/unlock screen orientation to match the video's
+     *  intrinsic aspect. */
+    private _fullscreenChangeHandler;
+    /** True if we successfully called screen.orientation.lock() on the last
+     *  fullscreen entry. Used to know whether to unlock on exit. */
+    private _orientationLocked;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -635,6 +661,8 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
     set preload(value: "none" | "metadata" | "auto");
     get diagnostics(): boolean;
     set diagnostics(value: boolean);
+    get fit(): FitMode;
+    set fit(value: FitMode);
     get preferredStrategy(): PreferredStrategy;
     set preferredStrategy(value: PreferredStrategy);
     get currentTime(): number;
@@ -724,6 +752,36 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
         language?: string;
         format?: "vtt" | "srt";
     }): Promise<void>;
+    /**
+     * 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;
+    set noOrientationLock(value: boolean);
+    /** 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;
+    /** 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;
+    /** 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;
+    /** 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 _lockOrientation;
+    private _releaseOrientationLock;
     /** Force a (re-)bootstrap if a source is currently set. */
     load(): Promise<void>;
     /**

package/dist/player.d.ts

@@ -283,6 +283,9 @@ interface AvbridgeVideoElementEventMap {
         buffered: TimeRanges;
     }>;
     loadstart: CustomEvent<Record<string, never>>;
+    fitchange: CustomEvent<{
+        fit: "contain" | "cover" | "fill";
+    }>;
 }
 
 /**
@@ -297,7 +300,7 @@ interface AvbridgeVideoElementEventMap {
  */
 
 declare class AvbridgePlayerElement extends HTMLElement {
-    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy")[];
+    static readonly observedAttributes: ("src" | "muted" | "autoplay" | "loop" | "preload" | "poster" | "playsinline" | "crossorigin" | "disableremoteplayback" | "preferstrategy" | "fit")[];
     private _video;
     private _playBtn;
     private _overlayBtn;
@@ -328,6 +331,7 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _statsEl;
     private _statsInterval;
     private _eventCleanup;
+    private _updateToolbarEmpty;
     constructor();
     private _template;
     private _bindEvents;
@@ -357,6 +361,11 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _scheduleHide;
     /** Track whether the last interaction was touch so click handler can skip. */
     private _lastPointerTypeWasTouch;
+    /** 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;
     private _onContainerClick;
     private _onContainerDblClick;
     private _onPointerDown;
@@ -506,14 +515,17 @@ declare class UnifiedPlayer {
  *   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.
  */
 
 /** Strategy preference passed via the `preferstrategy` attribute. */
 type PreferredStrategy = "auto" | StrategyName;
+/** Fit mode — how the video fills the element's box. Mirrors CSS object-fit. */
+type FitMode = "contain" | "cover" | "fill";
 /**
  * `HTMLElement` is a browser-only global. SSR frameworks (Next.js, Astro,
  * Remix, etc.) commonly import library modules on the server to extract
@@ -586,12 +598,26 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
      * native fails.
      */
     private _preferredStrategy;
+    /** 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;
+    /** The stage wrapper — the element the canvas attaches into, and where
+     *  the `--avbridge-fit` CSS custom property lives. */
+    private _stageEl;
     /** Set if currentTime was assigned before the player was ready. */
     private _pendingSeek;
     /** Set if play() was called before the player was ready. */
     private _pendingPlay;
     /** MutationObserver tracking light-DOM `<track>` children. */
     private _trackObserver;
+    /** Document-level fullscreenchange handler — installed while connected so
+     *  the element can lock/unlock screen orientation to match the video's
+     *  intrinsic aspect. */
+    private _fullscreenChangeHandler;
+    /** True if we successfully called screen.orientation.lock() on the last
+     *  fullscreen entry. Used to know whether to unlock on exit. */
+    private _orientationLocked;
     constructor();
     connectedCallback(): void;
     disconnectedCallback(): void;
@@ -635,6 +661,8 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
     set preload(value: "none" | "metadata" | "auto");
     get diagnostics(): boolean;
     set diagnostics(value: boolean);
+    get fit(): FitMode;
+    set fit(value: FitMode);
     get preferredStrategy(): PreferredStrategy;
     set preferredStrategy(value: PreferredStrategy);
     get currentTime(): number;
@@ -724,6 +752,36 @@ declare class AvbridgeVideoElement extends HTMLElementCtor {
         language?: string;
         format?: "vtt" | "srt";
     }): Promise<void>;
+    /**
+     * 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;
+    set noOrientationLock(value: boolean);
+    /** 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;
+    /** 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;
+    /** 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;
+    /** 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 _lockOrientation;
+    private _releaseOrientationLock;
     /** Force a (re-)bootstrap if a source is currently set. */
     load(): Promise<void>;
     /**

package/dist/player.js

@@ -494,6 +494,22 @@ function classifyContext(ctx) {
     };
   }
   if (REMUXABLE_CONTAINERS.has(ctx.container)) {
+    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 \u2014 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 \u2014 falling back to WASM decode`
+      };
+    }
     return {
       class: "REMUX_CANDIDATE",
       strategy: "remux",
@@ -1237,7 +1253,7 @@ var VideoRenderer = class {
       this.resolveFirstFrame = resolve;
     });
     this.canvas = document.createElement("canvas");
-    this.canvas.style.cssText = "position:absolute;left:0;top:0;width:100%;height:100%;background:black;object-fit:contain;";
+    this.canvas.style.cssText = "position:absolute;left:0;top:0;width:100%;height:100%;background:black;object-fit:var(--avbridge-fit, contain);";
     const parent = target.parentElement ?? target.parentNode;
     if (parent && parent instanceof HTMLElement) {
       if (getComputedStyle(parent).position === "static") {
@@ -2580,7 +2596,7 @@ async function createHybridSession(ctx, target, transport) {
 
 // src/strategies/fallback/decoder.ts
 async function startDecoder(opts) {
-  const variant = pickLibavVariant(opts.context);
+  const variant = "avbridge";
   const libav = await loadLibav(variant);
   const bridge = await loadBridge2();
   const { prepareLibavInput } = await import('./libav-http-reader-WXG3Z7AI.js');
@@ -2636,9 +2652,8 @@ async function startDecoder(opts) {
       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 \u2014 rebuild with scripts/build-libav.sh including the missing decoder, or use a lighter strategy (native, remux, hybrid) instead.`
     );
   }
   let bsfCtx = null;
@@ -3765,6 +3780,8 @@ var PREFERRED_STRATEGY_VALUES = /* @__PURE__ */ new Set([
   "hybrid",
   "fallback"
 ]);
+var FIT_VALUES = /* @__PURE__ */ new Set(["contain", "cover", "fill"]);
+var DEFAULT_FIT = "contain";
 var FORWARDED_VIDEO_EVENTS = [
   "loadstart",
   "loadedmetadata",
@@ -3799,7 +3816,9 @@ var AvbridgeVideoElement = class extends HTMLElementCtor {
     "crossorigin",
     "disableremoteplayback",
     "diagnostics",
-    "preferstrategy"
+    "preferstrategy",
+    "fit",
+    "no-orientation-lock"
   ];
   // ── Internal state ─────────────────────────────────────────────────────
   /** The shadow DOM `<video>` element that strategies render into. */
@@ -3851,23 +3870,38 @@ var AvbridgeVideoElement = class extends HTMLElementCtor {
    * native fails.
    */
   _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`). */
+  _fit = DEFAULT_FIT;
+  /** The stage wrapper — the element the canvas attaches into, and where
+   *  the `--avbridge-fit` CSS custom property lives. */
+  _stageEl;
   /** Set if currentTime was assigned before the player was ready. */
   _pendingSeek = null;
   /** Set if play() was called before the player was ready. */
   _pendingPlay = false;
   /** MutationObserver tracking light-DOM `<track>` children. */
   _trackObserver = null;
+  /** Document-level fullscreenchange handler — installed while connected so
+   *  the element can lock/unlock screen orientation to match the video's
+   *  intrinsic aspect. */
+  _fullscreenChangeHandler = null;
+  /** True if we successfully called screen.orientation.lock() on the last
+   *  fullscreen entry. Used to know whether to unlock on exit. */
+  _orientationLocked = false;
   // ── Construction & lifecycle ───────────────────────────────────────────
   constructor() {
     super();
     const root = this.attachShadow({ mode: "open" });
     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);
     this._videoEl.addEventListener("progress", () => {
@@ -3888,6 +3922,10 @@ var AvbridgeVideoElement = class 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);
+    }
     const source = this._activeSource();
     if (source != null) {
       void this._bootstrap(source);
@@ -3899,6 +3937,11 @@ var AvbridgeVideoElement = class extends HTMLElementCtor {
       this._trackObserver.disconnect();
       this._trackObserver = null;
     }
+    if (this._fullscreenChangeHandler) {
+      document.removeEventListener("fullscreenchange", this._fullscreenChangeHandler);
+      this._fullscreenChangeHandler = null;
+    }
+    this._releaseOrientationLock();
     this._bootstrapId++;
     void this._teardown();
   }
@@ -3932,6 +3975,14 @@ var AvbridgeVideoElement = class extends HTMLElementCtor {
           this._preferredStrategy = "auto";
         }
         break;
+      case "fit": {
+        const next = newValue && FIT_VALUES.has(newValue) ? newValue : DEFAULT_FIT;
+        if (next === this._fit) break;
+        this._fit = next;
+        this._stageEl.style.setProperty("--avbridge-fit", next);
+        this._dispatch("fitchange", { fit: next });
+        break;
+      }
     }
   }
   // ── Source handling ────────────────────────────────────────────────────
@@ -4173,6 +4224,13 @@ var AvbridgeVideoElement = class extends HTMLElementCtor {
     if (value) this.setAttribute("diagnostics", "");
     else this.removeAttribute("diagnostics");
   }
+  get fit() {
+    return this._fit;
+  }
+  set fit(value) {
+    if (!FIT_VALUES.has(value)) return;
+    this.setAttribute("fit", value);
+  }
   get preferredStrategy() {
     return this._preferredStrategy;
   }
@@ -4346,6 +4404,87 @@ var AvbridgeVideoElement = class 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() {
+    return this.hasAttribute("no-orientation-lock");
+  }
+  set noOrientationLock(value) {
+    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. */
+  _onFullscreenChange() {
+    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;
+      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. */
+  _isInsideOrEquals(target) {
+    let node = this;
+    while (node) {
+      if (node === target) return true;
+      const parent = 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). */
+  _desiredOrientation() {
+    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. */
+  async _lockOrientation(target) {
+    const so = screen.orientation;
+    if (!so || typeof so.lock !== "function") return;
+    try {
+      await so.lock(target);
+      this._orientationLocked = true;
+    } catch {
+    }
+  }
+  _releaseOrientationLock() {
+    if (!this._orientationLocked) return;
+    this._orientationLocked = false;
+    const so = screen.orientation;
+    if (so && typeof so.unlock === "function") {
+      try {
+        so.unlock();
+      } catch {
+      }
+    }
+  }
   // ── Public methods ─────────────────────────────────────────────────────
   /** Force a (re-)bootstrap if a source is currently set. */
   async load() {
@@ -4605,6 +4744,50 @@ var PLAYER_STYLES = (
 
 :host([data-controls-hidden]) { cursor: none; }
 
+/* \u2500\u2500 Top toolbar (slotted consumer chrome) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+   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 \u2014 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;
+}
+
 /* \u2500\u2500 Seek bar \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500 */
 
 .avp-seek {
@@ -4956,7 +5139,8 @@ var PROXY_ATTRIBUTES = [
   "playsinline",
   "crossorigin",
   "disableremoteplayback",
-  "preferstrategy"
+  "preferstrategy",
+  "fit"
 ];
 var AvbridgePlayerElement = class extends HTMLElement {
   static observedAttributes = [...PROXY_ATTRIBUTES];
@@ -4994,6 +5178,8 @@ var AvbridgePlayerElement = class extends HTMLElement {
   _statsEl;
   _statsInterval = null;
   _eventCleanup = [];
+  _updateToolbarEmpty = () => {
+  };
   // ── Constructor ────────────────────────────────────────────────────────
   constructor() {
     super();
@@ -5017,12 +5203,23 @@ var AvbridgePlayerElement = class extends HTMLElement {
     this._statsEl = shadow.querySelector(".avp-stats");
     this._rippleLeft = shadow.querySelector(".avp-ripple-left");
     this._rippleRight = shadow.querySelector(".avp-ripple-right");
+    const slots = shadow.querySelectorAll('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();
   }
   _template() {
     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>
@@ -5175,13 +5372,14 @@ var AvbridgePlayerElement = class extends HTMLElement {
       });
     });
     on(this, "keydown", (e) => this._onKeydown(e));
-    if (!this.hasAttribute("tabindex")) {
-      this.setAttribute("tabindex", "0");
-    }
   }
   // ── Lifecycle ──────────────────────────────────────────────────────────
   connectedCallback() {
     this._setState("idle");
+    if (!this.hasAttribute("tabindex")) {
+      this.setAttribute("tabindex", "0");
+    }
+    this._updateToolbarEmpty();
   }
   disconnectedCallback() {
     this._clearTimers();
@@ -5443,8 +5641,19 @@ var AvbridgePlayerElement = class extends HTMLElement {
   // it's treated as a double-click and the single-click action is cancelled.
   /** Track whether the last interaction was touch so click handler can skip. */
   _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. */
+  _isToolbarEvent(e) {
+    for (const node of e.composedPath()) {
+      if (node instanceof HTMLElement && node.classList.contains("avp-toolbar-top")) return true;
+    }
+    return false;
+  }
   _onContainerClick(e) {
     if (e.target.closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
+    if (this._isToolbarEvent(e)) return;
     if (this._lastPointerTypeWasTouch) {
       this._lastPointerTypeWasTouch = false;
       return;
@@ -5460,6 +5669,7 @@ var AvbridgePlayerElement = class extends HTMLElement {
   }
   _onContainerDblClick(e) {
     if (e.target.closest?.(".avp-controls, .avp-settings")) return;
+    if (this._isToolbarEvent(e)) return;
     if (this._tapTimer) {
       clearTimeout(this._tapTimer);
       this._tapTimer = null;
@@ -5481,6 +5691,7 @@ var AvbridgePlayerElement = class extends HTMLElement {
     if (e.pointerType !== "touch") return;
     this._lastPointerTypeWasTouch = true;
     if (e.target.closest?.(".avp-controls, .avp-settings, .avp-overlay-btn")) return;
+    if (this._isToolbarEvent(e)) return;
     const now = Date.now();
     if (now - this._lastTapTime < 300) {
       if (this._tapTimer) {