avbridge 2.7.0 → 2.8.2

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" | "show-fit")[];
     private _video;
     private _playBtn;
     private _overlayBtn;
@@ -328,6 +331,8 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _statsEl;
     private _statsInterval;
     private _eventCleanup;
+    private _updateToolbarEmpty;
+    private _toolbarTop;
     constructor();
     private _template;
     private _bindEvents;
@@ -357,6 +362,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 +516,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 +599,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 +662,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 +753,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" | "show-fit")[];
     private _video;
     private _playBtn;
     private _overlayBtn;
@@ -328,6 +331,8 @@ declare class AvbridgePlayerElement extends HTMLElement {
     private _statsEl;
     private _statsInterval;
     private _eventCleanup;
+    private _updateToolbarEmpty;
+    private _toolbarTop;
     constructor();
     private _template;
     private _bindEvents;
@@ -357,6 +362,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 +516,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 +599,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 +662,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 +753,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>;
     /**