@banou/media-player 0.10.5 → 0.10.7

package/src/lib/react/media.ts

@@ -63,9 +63,58 @@ export type PlayerMedia = EventTarget & {
   videoHeight?: number
 
   requestPictureInPicture?: () => Promise<unknown>
+  /** What the control calls while the media is in picture in picture: see `PassThroughPictureInPicture`. */
+  exitPictureInPicture?: () => Promise<unknown>
   requestFullscreen?: () => Promise<unknown>
 }
 
+/**
+ * Picture in picture for a media whose own document has to ask for it, opted into by the host.
+ *
+ * A browser opens picture in picture only for a request made while the document that OWNS the
+ * `<video>` is handling a user gesture, and a click in this document never counts for another one:
+ * Chrome 153 refused a request relayed on the click with `NotAllowedError`, and refused delegating
+ * the activation with `NotSupportedError` (measured 2026-09-26). So the click itself has to land in
+ * the media's document. While the pointer is over the control, the chrome lets a click through at the
+ * control's box, and the host makes whatever renders the media take that click and enter picture in
+ * picture from inside, where the click counts.
+ *
+ * Passing this is the host's promise that it does both. Without it the control is not offered at all
+ * for a media the player does not own, since a button whose click lands nowhere is worse than none.
+ *
+ * What the player promises in return:
+ * - The control follows the media's `enterpictureinpicture` and `leavepictureinpicture` events,
+ *   which is the only state it reads.
+ * - While the media is in picture in picture a click on the control is an ordinary click here and
+ *   calls the media's `exitPictureInPicture`, since leaving needs no gesture. Nothing is let through.
+ * - Once a click has gone through and taken focus into a frame inside the player, the control takes
+ *   focus back, so the chrome's keyboard shortcuts keep working in this document rather than in the
+ *   host's. This holds with the player itself nested in another page. Focus anywhere else is left
+ *   alone.
+ *
+ * What it refuses:
+ * - A keyboard press on the control, which cannot reach the host's document, does nothing until the
+ *   media is in picture in picture.
+ * - A media with no metadata yet (`readyState` below 1) or with an `error`: the control does not arm,
+ *   so its click lands on the control and does nothing.
+ * - A finger. Only a pointer resting on the control arms it, and a tap presses as it arrives, so its
+ *   click lands on the control and goes nowhere. No control is offered where the primary pointer
+ *   cannot hover (`(hover: hover) and (pointer: fine)` fails: phones, tablets), and on a device that
+ *   has both, a touch hides it until a pointer that hovers moves again.
+ */
+export type PassThroughPictureInPicture = {
+  /**
+   * True while the pointer is over the control, and a click there goes to whatever the host renders
+   * under it. False once the pointer is back over the rest of the player, the media enters picture in
+   * picture, the host withdraws this option or the player unmounts. Called on a change only, and
+   * synchronously, so the host is ready before the next pointer event.
+   *
+   * The host makes its own element take pointer events while this is true (an iframe with
+   * `pointer-events: none` gets `auto`) and gives them back when it is false.
+   */
+  onArmedChange: (armed: boolean) => void
+}
+
 /**
  * Where the seekbar's hover previews come from.
  *

package/src/lib/react/source-feature.ts

@@ -61,6 +61,43 @@ export type DownloadedRange = {
   endByteOffset: number
 }
 
+/** A box in viewport coordinates, as `getBoundingClientRect` reports it. */
+export type ViewportBox = {
+  left: number
+  top: number
+  width: number
+  height: number
+}
+
+/**
+ * The picture in picture control of a media the player does not own, which the host enters from its
+ * own document (see `PassThroughPictureInPicture`).
+ *
+ * Armed means a click on the control goes through it to whatever the host renders below, so the
+ * chrome lays a layer over everything else with a hole at `armed`: inside the hole every pointer event
+ * belongs to the host's document, and the layer is how this one learns the pointer has left it.
+ */
+export type PassThroughControl = {
+  /** Between the media's `enterpictureinpicture` and `leavepictureinpicture`. */
+  active: boolean
+  /** The control's box while a click on it is let through, undefined otherwise. */
+  armed?: ViewportBox
+  /**
+   * Lets a click at `box` through to the host, and tells the host it is armed. For the pointer
+   * arriving on the control. Does nothing while the media has no metadata yet (`readyState` below 1)
+   * or has an `error`, since the host's request would be refused and the click lost with it.
+   */
+  arm: (box: ViewportBox) => void
+  /**
+   * Takes the click back, and tells the host it is disarmed if it had been told it was armed. For the
+   * pointer leaving the control; also done here on entering picture in picture, on a touch, and when
+   * the control stops being offered.
+   */
+  disarm: () => void
+  /** Leaves picture in picture through the media. */
+  exit: () => void
+}
+
 /**
  * Everything about the source that the chrome reads, carried on the player store next to the built-in
  * playback state so a component never has to know which of two channels owns a field.
@@ -145,12 +182,17 @@ export type SourceState = {
    * Owned here, not by `pip`: that watches the media element, and the window holds a mirror.
    *
    * null means the control is not offered at all. Locally that is "no element yet". For a media the
-   * player does not own it means the source cannot do it, and the difference matters: the compositing
-   * this does needs a local element to draw, and even a source that forwards the request cannot
-   * report the resulting STATE back, since `document.pictureInPictureElement` is never a proxy. A
-   * button that toggles nothing and never lights up is worse than no button.
+   * player does not own it is always null, because a request made from this document is refused: the
+   * compositing this does needs a local element to draw, and the browser wants a gesture in the
+   * media's own document. `passThroughPictureInPicture` is that arm's control instead.
    */
   togglePictureInPicture: (() => void) | null
+  /**
+   * The picture in picture control for a media the player does not own, when the host opted in with
+   * `pictureInPicture` and the viewer points with something that hovers. null otherwise, which is
+   * always the case for a local source.
+   */
+  passThroughPictureInPicture: PassThroughControl | null
 
   /**
    * Which shape the control takes. `window` opens one. `burn-in` cannot, and instead paints the
@@ -226,6 +268,7 @@ const initialState: SourceState = {
   setHideUI: () => {},
   hasMedia: false,
   togglePictureInPicture: null,
+  passThroughPictureInPicture: null,
   pictureInPictureMode: null,
   burnedInSubtitles: false,
   playbackError: null,

package/src/lib/react/video-player.tsx

@@ -2,7 +2,7 @@
 import type { ReactNode } from 'react'
 import type { MediaChapter } from '../engine'
 import type { DownloadedRange } from './source-feature'
-import type { DelegatedTracks, ExternalThumbnails, PlayerMedia } from './media'
+import type { DelegatedTracks, ExternalThumbnails, PassThroughPictureInPicture, PlayerMedia } from './media'
 import type { ExposePlayerOptions } from '../remote'
 
 import { useEffect, useRef, useState } from 'react'
@@ -13,6 +13,7 @@ import { Player, usePlayer } from './player'
 import { usePlayback } from './hooks/use-playback'
 import { useSeekThumbnails } from './hooks/use-thumbnails'
 import { usePictureInPicture } from './hooks/use-picture-in-picture'
+import { usePassThroughPictureInPicture } from './hooks/use-pass-through-picture-in-picture'
 import Chrome from './components/chrome'
 
 /**
@@ -185,6 +186,12 @@ export type MediaPlayerRemoteOptions =
     /** The source renders these; the player draws the menu and reports the pick. */
     subtitles?: DelegatedTracks
     audioTracks?: DelegatedTracks
+    /**
+     * Offer picture in picture, entered by the host from inside the media's own document. Off by
+     * default, and then there is no control at all. See `PassThroughPictureInPicture` for what the
+     * host takes on by passing it. Read by value, so it may be written inline.
+     */
+    pictureInPicture?: PassThroughPictureInPicture
   }
 
 export type MediaPlayerOptions = MediaPlayerLocalOptions | MediaPlayerRemoteOptions
@@ -264,6 +271,10 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     mode: pictureInPictureMode,
     burnedIn: burnedInSubtitles,
   } = usePictureInPicture(video, subtitleLayer)
+  const passThroughPictureInPicture = usePassThroughPictureInPicture(
+    remote?.media ?? null,
+    remote?.pictureInPicture,
+  )
 
   // Subscribed rather than read off the store, because it is a no-op until the media element
   // attaches: when attach swaps in the real setter the identity changes and these publish again.
@@ -295,6 +306,11 @@ const PlayerRoot = ({ options, children }: { options: MediaPlayerOptions, childr
     burnedInSubtitles,
   ])
 
+  // its own effect: it changes on every hover of the control, and nothing else here does
+  useEffect(() => {
+    setSourceState({ passThroughPictureInPicture })
+  }, [setSourceState, passThroughPictureInPicture])
+
   // A delegated track list writes the same store fields the engine writes, so the menus never learn
   // which arm they are showing. Only the writer differs: here the pick is forwarded to whoever owns
   // the document, and it renders the result itself.