@banou/media-player 0.10.6 → 0.10.7

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.