@banou/media-player 0.10.6 → 0.10.7

package/dist/react/hooks/use-pass-through-picture-in-picture.d.ts

@@ -0,0 +1,10 @@
+import type { PassThroughPictureInPicture, PlayerMedia } from '../media';
+import type { PassThroughControl } from '../source-feature';
+/**
+ * The state behind a remote media's picture in picture control: whether the media is in picture in
+ * picture, and whether a click on the control is currently let through to the host.
+ *
+ * null unless the host opted in AND there is a media to follow AND the viewer points with something
+ * that hovers, so the chrome offers nothing otherwise.
+ */
+export declare const usePassThroughPictureInPicture: (media: PlayerMedia | null, options: PassThroughPictureInPicture | undefined) => PassThroughControl | null;

package/dist/react/media.d.ts

@@ -59,8 +59,56 @@ export type PlayerMedia = EventTarget & {
     videoWidth?: number;
     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/dist/react/player.d.ts

@@ -18,6 +18,7 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     setHideUI: (hide: boolean) => void;
     hasMedia: boolean;
     togglePictureInPicture: (() => void) | null;
+    passThroughPictureInPicture: import("./source-feature").PassThroughControl | null;
     pictureInPictureMode: import("../engine").PictureInPictureMode | null;
     burnedInSubtitles: boolean;
     requestSeek?: (time: number) => void;

package/dist/react/source-feature.d.ts

@@ -55,6 +55,41 @@ export type DownloadedRange = {
     startByteOffset: number;
     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.
@@ -133,12 +168,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
      * subtitles into the picture so the BROWSER'S own control carries them; the viewer presses that
@@ -264,12 +304,17 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
      * 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
      * subtitles into the picture so the BROWSER'S own control carries them; the viewer presses that

package/dist/react/video-player.d.ts

@@ -1,7 +1,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';
 /**
  * The source, read a range at a time: the player never downloads the whole file. Both fields travel
@@ -162,6 +162,12 @@ export type MediaPlayerRemoteOptions = CommonOptions & {
     /** 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;
 export declare const MediaPlayer: (options: MediaPlayerOptions & {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.10.6",
+  "version": "0.10.7",
   "description": "A video player for containers and codecs the browser cannot play natively, remuxed on the fly",
   "type": "module",
   "main": "dist/index.js",

package/src/lib/index.tsx

@@ -14,6 +14,7 @@ export type {
   DelegatedSelection,
   DelegatedTracks,
   ExternalThumbnails,
+  PassThroughPictureInPicture,
   PlayerMedia,
   TimeRangesLike,
 } from './react/media'
@@ -24,7 +25,9 @@ export type { PlayerStore } from './react/player'
 // Source state lives on the player store next to the built-in playback state, so `usePlayer` is the
 // only hook the chrome needs.
 export { sourceFeature } from './react/source-feature'
-export type { DownloadedRange, PlaybackErrorEntry, SourceState } from './react/source-feature'
+export type {
+  DownloadedRange, PassThroughControl, PlaybackErrorEntry, SourceState, ViewportBox,
+} from './react/source-feature'
 
 export { useSeekThumbnails } from './react/hooks/use-thumbnails'
 export { usePictureInPicture } from './react/hooks/use-picture-in-picture'

package/src/lib/react/components/chrome.tsx

@@ -1,5 +1,6 @@
 /// <reference types="@emotion/react/types/css-prop" />
 import type { ReactNode, Ref } from 'react'
+import type { ViewportBox } from '../source-feature'
 
 import { Children, Fragment, isValidElement, useEffect, useRef } from 'react'
 import { css } from '@emotion/react'
@@ -36,6 +37,13 @@ const overlayItemStyle = css`
   transition: opacity 0.1s cubic-bezier(.4,0,1,1), visibility 0.1s;
 `
 
+/** The layer minus the control's box, both measured against the viewport. */
+const holeAt = (hole: ViewportBox, layer: DOMRect) => {
+  const left = hole.left - layer.left
+  const top = hole.top - layer.top
+  return `path(evenodd, 'M0 0H${layer.width}V${layer.height}H0Z M${left} ${top}H${left + hole.width}V${top + hole.height}H${left}Z')`
+}
+
 const style = css`
   position: relative;
   background-color: black;
@@ -63,6 +71,15 @@ const style = css`
     pointer-events: none;
   }
 
+  /* Over everything, the control bar included, while a click on the picture in picture control is let
+     through, with a hole at the control. Inside the hole every pointer event goes to the host's
+     document and this one hears nothing, so the pointer arriving on this layer is the only sign here
+     that it left the control. Named with its type for the specificity reason just above. */
+  & > div.pass-through {
+    inset: 0;
+    z-index: 5;
+  }
+
   canvas {
     height: 100%;
     width: 100%;
@@ -120,6 +137,7 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, chil
   const hideUI = usePlayer((state) => state.hideUI)
   const setHideUI = usePlayer((state) => state.setHideUI)
   const hasMedia = usePlayer((state) => state.hasMedia)
+  const passThrough = usePlayer((state) => state.passThroughPictureInPicture)
   const autoHide = useRef<ReturnType<typeof setTimeout>>(undefined)
   // a tap and a click mean different things, so the last pointer kind is remembered
   const lastPointerType = useRef<string>('mouse')
@@ -173,8 +191,12 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, chil
    *
    * The mouse only. A finger has no resting position, and `elementFromPoint` on the last tap would
    * keep the controls up forever after one press.
+   *
+   * Armed, the pointer is on the picture in picture control by definition, and `elementFromPoint`
+   * answers with whatever the host put under it, since that is what takes the pointer meanwhile.
    */
   const pointerRestsOnAControl = () => {
+    if (player.passThroughPictureInPicture?.armed) return true
     if (lastPointerType.current !== 'mouse') return false
     const { x, y } = pointer.current
     if (!root.current || x < 0) return false
@@ -257,6 +279,15 @@ export const Chrome = ({ ref, onVideoRef, onSubtitleRef, overlay, controls, chil
       {/* Not tied to `hideUI`: it says what to do next, and it is on screen for nine seconds. */}
       <BurnInHint />
       <SkipChapter />
+      {passThrough?.armed && root.current
+        ? (
+          <div
+            className='pass-through'
+            style={{ clipPath: holeAt(passThrough.armed, root.current.getBoundingClientRect()) }}
+            onPointerOver={passThrough.disarm}
+          />
+        )
+        : null}
       <div className="video" onClick={onVideoClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}

package/src/lib/react/components/control-bar.tsx

@@ -1,5 +1,5 @@
 /// <reference types="@emotion/react/types/css-prop" />
-import { useCallback, useEffect, useState } from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
 import { css } from '@emotion/react'
 import { Maximize, Minimize, Pause, Play, RotateCcw } from 'react-feather'
 
@@ -19,6 +19,11 @@ import Sound from './sound'
 
 const VOLUME_STEP = 0.05
 const SEEK_STEP = 5
+// Whether the click let through took focus into the host's frame is asked, not heard: nested in
+// another page (stub's embed), this window never had focus, and the click fired neither a blur nor a
+// focusin here (Chrome 153, 2026-09-26). So while armed, and for a second after, it is polled.
+const REFOCUS_POLL = 50
+const REFOCUS_AFTER = 1_000
 
 /**
  * Two stacked lines inside a tooltip.
@@ -126,7 +131,9 @@ const style = css`
 
         cursor: pointer;
 
-        :hover {
+        /* .armed is the hover of a control letting its click through, which takes no pointer events
+           of its own and so is never :hover */
+        :hover, &.armed {
           background-color: ${colors.hover};
         }
 
@@ -179,11 +186,14 @@ export const ControlBar = () => {
   const togglePictureInPicture = usePlayer((state) => state.togglePictureInPicture)
   const pictureInPictureMode = usePlayer((state) => state.pictureInPictureMode)
   const burnedInSubtitles = usePlayer((state) => state.burnedInSubtitles)
+  const passThrough = usePlayer((state) => state.passThroughPictureInPicture)
   const subtitleTracks = usePlayer((state) => state.subtitleTracks)
   // Keyboard seeks go through the same door as the seek bar: data first, then the playhead. See
   // `requestSeek` on the source state for why an element that seeks into a hole is the problem.
   const requestSeek = usePlayer((state) => state.requestSeek)
   const [volumeElement, setVolumeElement] = useState<HTMLButtonElement | null>(null)
+  const passThroughButton = useRef<HTMLButtonElement>(null)
+  const refocus = useRef<ReturnType<typeof setInterval>>(undefined)
 
   const burnIn = pictureInPictureMode === 'burn-in'
   // Burning nothing in is a mode with no effect, so the control stays visible and goes dead rather
@@ -258,8 +268,47 @@ export const ControlBar = () => {
     return () => volumeElement.removeEventListener('wheel', handleWheel)
   }, [volumeElement, handleWheel])
 
+  // Moving too (not only entering): after leaving picture in picture the pointer is often still on
+  // the control, and entering fired long ago. Never for a finger, whose tap is already on its way to
+  // this button when it arrives, so arming would only flip the host's frame for nothing.
+  const armPassThrough = (event: React.PointerEvent<HTMLButtonElement>) => {
+    if (!passThrough || passThrough.active || passThrough.armed || event.pointerType === 'touch') return
+    const { left, top, width, height } = event.currentTarget.getBoundingClientRect()
+    passThrough.arm({ left, top, width, height })
+  }
+
+  // The click that went through took focus into the host's frame with it, and the shortcuts above
+  // listen on this window. Only a frame inside this player's picture counts, so a window blur while
+  // armed (Alt+Tab) or focus the viewer put elsewhere, a chat input say, is left where it is.
+  const armed = !!passThrough?.armed
+  useEffect(() => {
+    if (!armed) return
+    clearInterval(refocus.current)
+    let until = Infinity
+    const poll = setInterval(() => {
+      if (Date.now() > until) {
+        clearInterval(poll)
+        return
+      }
+      const button = passThroughButton.current
+      const focused = document.activeElement
+      if (button && focused?.tagName === 'IFRAME' && focused.closest('.video')?.parentElement?.contains(button)) {
+        button.focus({ preventScroll: true })
+      }
+    }, REFOCUS_POLL)
+    refocus.current = poll
+    // entering picture in picture disarms, which can come before the next tick
+    return () => { until = Date.now() + REFOCUS_AFTER }
+  }, [armed])
+  useEffect(() => () => clearInterval(refocus.current), [])
+
   return (
-    <div css={style} style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : {} }}>
+    // Armed, the whole bar takes no pointer events, or the rows around the control would still catch
+    // the click at its box. The chrome's layer covers everything but the control meanwhile.
+    <div
+      css={style}
+      style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : armed ? { pointerEvents: 'none' } : {} }}
+    >
       <ProgressBar />
       <div className='actions'>
         <div className='left'>
@@ -305,7 +354,33 @@ export const ControlBar = () => {
           <ErrorsAction />
           <SubtitlesAction />
           <SettingsAction />
-          {togglePictureInPicture
+          {passThrough
+            ? (
+              <TooltipDisplay
+                id='picture-in-picture'
+                tooltipPlace='top-end'
+                text={
+                  <button
+                    ref={passThroughButton}
+                    className={passThrough.armed ? 'picture-in-picture armed' : 'picture-in-picture'}
+                    type='button'
+                    onPointerEnter={armPassThrough}
+                    onPointerMove={armPassThrough}
+                    // Out of picture in picture the click was meant for the host's document, so one
+                    // that lands here instead (a key press) has nothing it could do.
+                    onClick={passThrough.active ? passThrough.exit : undefined}
+                    aria-label='Picture in picture'
+                    aria-pressed={passThrough.active}
+                  >
+                    <img src={pictureInPicture} alt='' />
+                  </button>
+                }
+                toolTipText={
+                  <span>{passThrough.active ? 'Exit picture in picture' : 'Picture in picture'}</span>
+                }
+              />
+            )
+            : togglePictureInPicture
             ? (
               <TooltipDisplay
                 id='picture-in-picture'

package/src/lib/react/hooks/use-pass-through-picture-in-picture.ts

@@ -0,0 +1,113 @@
+import type { PassThroughPictureInPicture, PlayerMedia } from '../media'
+import type { PassThroughControl, ViewportBox } from '../source-feature'
+
+import { useCallback, useEffect, useMemo, useRef, useState, useSyncExternalStore } from 'react'
+
+// Arming needs a pointer that rests over the control before it presses, and a finger arrives and
+// presses at once: tapped, the control armed and disarmed 11 to 33 ms later and the host's frame
+// heard nothing (Chrome 153 with touch emulated, 2026-09-26). Touch emulation flips this query.
+const HOVERING_POINTER = '(hover: hover) and (pointer: fine)'
+
+// Asked on every render of every player, and jsdom has no matchMedia: stub's unit suite renders this
+// player there and crashed with a ReferenceError (2026-09-26).
+const hoveringPointerQuery = () => (typeof matchMedia === 'function' ? matchMedia(HOVERING_POINTER) : undefined)
+const watchHoveringPointer = (onChange: () => void) => {
+  const query = hoveringPointerQuery()
+  query?.addEventListener('change', onChange)
+  return () => query?.removeEventListener('change', onChange)
+}
+const primaryPointerHovers = () => !!hoveringPointerQuery()?.matches
+const noHoverOnTheServer = () => false
+
+/**
+ * The state behind a remote media's picture in picture control: whether the media is in picture in
+ * picture, and whether a click on the control is currently let through to the host.
+ *
+ * null unless the host opted in AND there is a media to follow AND the viewer points with something
+ * that hovers, so the chrome offers nothing otherwise.
+ */
+export const usePassThroughPictureInPicture = (
+  media: PlayerMedia | null,
+  options: PassThroughPictureInPicture | undefined,
+): PassThroughControl | null => {
+  const [active, setActive] = useState(false)
+  const [armed, setArmed] = useState<ViewportBox>()
+
+  // The LAST option given rather than the current one: a host that withdraws the option while armed
+  // still has to hear the false, or whatever it flipped to take the click stays flipped.
+  const host = useRef(options)
+  if (options) host.current = options
+  const told = useRef(false)
+  const tell = useCallback((on: boolean) => {
+    if (told.current === on) return
+    told.current = on
+    host.current?.onArmedChange(on)
+  }, [])
+
+  // Nothing to show yet, or a media that failed: the host's request would be refused, and the click
+  // lost with it, so it lands on the control instead.
+  const arm = useCallback((box: ViewportBox) => {
+    if (!media || media.readyState < 1 || media.error) return
+    setArmed(box)
+    tell(true)
+  }, [media, tell])
+  const disarm = useCallback(() => {
+    setArmed(undefined)
+    tell(false)
+  }, [tell])
+
+  // Followed while the control is hidden too, so it shows the right state when it comes back.
+  const followed = !!options && !!media
+  useEffect(() => {
+    if (!followed || !media) return
+    const enter = () => {
+      setActive(true)
+      disarm()
+    }
+    const leave = () => setActive(false)
+    media.addEventListener('enterpictureinpicture', enter)
+    media.addEventListener('leavepictureinpicture', leave)
+    return () => {
+      media.removeEventListener('enterpictureinpicture', enter)
+      media.removeEventListener('leavepictureinpicture', leave)
+      setActive(false)
+      disarm()
+    }
+  }, [media, followed, disarm])
+
+  // A touch screen laptop reports the hovering pointer as primary and takes taps as well, so a touch
+  // hides the control until a pointer that hovers moves again.
+  const hovers = useSyncExternalStore(watchHoveringPointer, primaryPointerHovers, noHoverOnTheServer)
+  const [touching, setTouching] = useState(false)
+  useEffect(() => {
+    if (!followed) return
+    const down = (event: PointerEvent) => {
+      if (event.pointerType === 'touch') setTouching(true)
+    }
+    const move = (event: PointerEvent) => {
+      if (event.pointerType !== 'touch') setTouching(false)
+    }
+    window.addEventListener('pointerdown', down, { capture: true, passive: true })
+    window.addEventListener('pointermove', move, { capture: true, passive: true })
+    return () => {
+      window.removeEventListener('pointerdown', down, { capture: true })
+      window.removeEventListener('pointermove', move, { capture: true })
+    }
+  }, [followed])
+
+  const offered = followed && hovers && !touching
+  useEffect(() => {
+    if (!offered) disarm()
+  }, [offered, disarm])
+
+  const exit = useCallback(() => {
+    Promise.resolve(media?.exitPictureInPicture?.()).catch((error) => {
+      console.warn('leaving picture in picture was refused', error)
+    })
+  }, [media])
+
+  return useMemo(
+    () => (offered ? { active, armed, arm, disarm, exit } : null),
+    [offered, active, armed, arm, disarm, exit],
+  )
+}

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.
  *