@banou/media-player 0.8.2 → 0.8.4

package/dist/react/components/chrome.d.ts

@@ -4,9 +4,11 @@ export type ChromeProps = {
     /** Absent means render no video element: the media belongs to someone else and arrives as children. */
     onVideoRef?: (element: HTMLVideoElement | null) => void;
     onCanvasRef: (element: HTMLCanvasElement | null) => void;
-    /** The app's own content, drawn in the top bar beside the title, unlike `children`. */
+    /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
     overlay?: ReactNode;
+    /** False draws no control bar at all, leaving the picture, the title and the overlay. */
+    controls?: boolean;
     children?: ReactNode;
 };
-export declare const Chrome: ({ ref, onVideoRef, onCanvasRef, overlay, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+export declare const Chrome: ({ ref, onVideoRef, onCanvasRef, overlay, controls, children }: ChromeProps) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Chrome;

package/dist/react/components/overlay.d.ts

@@ -1,8 +1,4 @@
-import type { ReactNode } from 'react';
-export type OverlayProps = {
+export declare const Overlay: ({ onCanvasRef }: {
     onCanvasRef: (element: HTMLCanvasElement | null) => void;
-    /** The app's own content, drawn at the right of the top bar next to the title. */
-    overlay?: ReactNode;
-};
-export declare const Overlay: ({ onCanvasRef, overlay }: OverlayProps) => import("@emotion/react/jsx-runtime").JSX.Element;
+}) => import("@emotion/react/jsx-runtime").JSX.Element;
 export default Overlay;

package/dist/react/player.d.ts

@@ -7,10 +7,11 @@ export declare const Player: import("@videojs/react").CreatePlayerResult<import(
     thumbnailAt?: (time: number) => import("..").ThumbnailImage | undefined;
     subtitleTracks: import("./source-feature").TrackChoice[];
     selectedSubtitleTrack: string | number | undefined;
-    selectSubtitleTrack: (id: string | number | undefined) => void;
+    selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;
+    subtitleOffLabel?: string;
     audioTracks: import("./source-feature").TrackChoice[];
     selectedAudioTrack: string | number | undefined;
-    selectAudioTrack: (id: string | number) => void;
+    selectAudioTrack: (id: string | number) => void | Promise<void>;
     hideUI: boolean;
     setHideUI: (hide: boolean) => void;
     togglePictureInPicture: (() => void) | null;

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

@@ -10,6 +10,13 @@ import type { MediaIndex, ThumbnailImage } from '../engine';
 export type TrackChoice = {
     id: string | number;
     label: string;
+    /**
+     * Offered but not selectable, so the menu shows it and refuses the click.
+     *
+     * Hiding it instead would be worse: a source that lists a dub it cannot currently serve is telling
+     * the viewer the dub exists, and a menu that silently omits it looks like the source has nothing.
+     */
+    disabled?: boolean;
 };
 /**
  * A byte span of the file the consumer has in hand, mapped onto the timeline through the keyframe
@@ -40,13 +47,24 @@ export type SourceState = {
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Both selectors may answer with a promise, and the menu waits on it.
+     *
+     * The engine switches a track by pointing the pipeline at another stream, which is immediate and
+     * cannot fail, so locally these return nothing. A source that owns its own player is the opposite
+     * case: the switch is a round trip through somebody else's UI and takes seconds, and it can lose.
+     * A menu that closed on the click would report a selection that has not happened, and a rejection
+     * with nothing awaiting it is an unhandled rejection rather than an error the viewer ever sees.
+     */
     subtitleTracks: TrackChoice[];
     /** undefined means subtitles are off. */
     selectedSubtitleTrack: string | number | undefined;
-    selectSubtitleTrack: (id: string | number | undefined) => void;
+    selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;
+    /** What the row that turns subtitles off is called, when the source would rather name it itself. */
+    subtitleOffLabel?: string;
     audioTracks: TrackChoice[];
     selectedAudioTrack: string | number | undefined;
-    selectAudioTrack: (id: string | number) => void;
+    selectAudioTrack: (id: string | number) => void | Promise<void>;
     /** Chrome auto-hide. True means the controls, title and cursor are hidden. */
     hideUI: boolean;
     setHideUI: (hide: boolean) => void;
@@ -87,13 +105,24 @@ export declare const sourceFeature: import("@videojs/react").PlayerFeature<{
      * Falls back to scanning `thumbnails` when absent, which is what the engine's generator fills.
      */
     thumbnailAt?: (time: number) => ThumbnailImage | undefined;
+    /**
+     * Both selectors may answer with a promise, and the menu waits on it.
+     *
+     * The engine switches a track by pointing the pipeline at another stream, which is immediate and
+     * cannot fail, so locally these return nothing. A source that owns its own player is the opposite
+     * case: the switch is a round trip through somebody else's UI and takes seconds, and it can lose.
+     * A menu that closed on the click would report a selection that has not happened, and a rejection
+     * with nothing awaiting it is an unhandled rejection rather than an error the viewer ever sees.
+     */
     subtitleTracks: TrackChoice[];
     /** undefined means subtitles are off. */
     selectedSubtitleTrack: string | number | undefined;
-    selectSubtitleTrack: (id: string | number | undefined) => void;
+    selectSubtitleTrack: (id: string | number | undefined) => void | Promise<void>;
+    /** What the row that turns subtitles off is called, when the source would rather name it itself. */
+    subtitleOffLabel?: string;
     audioTracks: TrackChoice[];
     selectedAudioTrack: string | number | undefined;
-    selectAudioTrack: (id: string | number) => void;
+    selectAudioTrack: (id: string | number) => void | Promise<void>;
     /** Chrome auto-hide. True means the controls, title and cursor are hidden. */
     hideUI: boolean;
     setHideUI: (hide: boolean) => void;

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

@@ -14,16 +14,49 @@ export type MediaPlayerSource = {
 };
 /** Shared by both arms: nothing here depends on who owns the media. */
 type CommonOptions = {
+    /**
+     * Drawn across the top of the picture, in a layer of its own.
+     *
+     * That layer cannot see an `overlay` item, so an app that also places something along the top has
+     * two elements competing for one band of screen: on a narrow viewport the title ellipsizes against
+     * the FULL width and then runs underneath whatever is painted over it. An app in that position
+     * should leave this unset and draw the title as part of its own overlay row, where the two can
+     * share a flex line and the filename can be the one that gives way.
+     */
     title?: string;
     autoplay?: boolean;
     /**
-     * The app's own readout, drawn at the right of the top bar beside `title`, for whatever it has to
-     * say over the video. It shares the title's gradient and fades with the rest of the chrome, so a
-     * running counter does not sit over the picture once the controls have hidden themselves.
+     * Draw the control bar. Defaults to true.
+     *
+     * False leaves the picture, the title and the overlay and takes away only the chrome, for a host
+     * that has to put its own interactive UI over the media for a while. A source whose sign-in form
+     * lives inside its own document is the case this exists for: the form is the thing the viewer has
+     * to reach, and a control bar for a media that has not loaded yet sits on top of it and eats the
+     * clicks. Hiding it from the host side is not an option, since `setHideUI` is installed by the
+     * store's `attach` and does nothing at all until a media arrives.
+     */
+    controls?: boolean;
+    /**
+     * The app's own content over the video: a download readout, a badge, a logo, anything the player
+     * itself has no opinion about.
      *
-     * The slot itself takes no pointer events, so a click still reaches the video and toggles
-     * playback; content that needs a pointer (a tooltip anchor, a button) sets `pointer-events: auto`
-     * on itself. `children` land next to the media instead, below the chrome.
+     * Pass one node, or several, and EACH TOP-LEVEL ITEM gets its own layer covering the whole player.
+     * That layer is the coordinate space, so an item is placed with ordinary CSS against the picture:
+     *
+     * ```tsx
+     * <MediaPlayer overlay={[
+     *   <div key="stats" css={css`position: absolute; top: 0; right: 0;`}>82 peers</div>,
+     *   <div key="badge" css={css`position: absolute; inset: auto auto 0 0;`}>4K</div>,
+     * ]} />
+     * ```
+     *
+     * A fragment works the same way. Items never share a containing block, so one item's CSS cannot
+     * move another, and each keeps its own DOM as the list changes.
+     *
+     * Items fade with the rest of the chrome, so a running counter does not sit over the picture once
+     * the controls have hidden themselves. A layer takes no pointer events, so a click still reaches
+     * the video and toggles playback; content that needs a pointer (a tooltip anchor, a button) sets
+     * `pointer-events: auto` on itself. `children` land next to the media instead, below the chrome.
      */
     overlay?: ReactNode;
     onSeek?: (fraction: number) => void;
@@ -72,7 +105,16 @@ export type MediaPlayerLocalOptions = CommonOptions & MediaPlayerSource & {
  * works: the key session belongs to whoever owns the element.
  */
 export type MediaPlayerRemoteOptions = CommonOptions & {
-    media: PlayerMedia;
+    /**
+     * Null means the media has not been found yet: the chrome renders and attaches when it arrives.
+     *
+     * A source usually has to mount its own document before it can hand over an element, and that
+     * document is passed as `children`, so it can only exist once this component has rendered. The
+     * key is still REQUIRED even when the value is null, because its presence is what selects this
+     * arm: omitting it falls through to the local arm, which draws an idle `<video>` over whatever
+     * the children put there.
+     */
+    media: PlayerMedia | null;
     read?: never;
     size?: never;
     /** The source's own storyboard, since there are no bytes to generate previews from. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@banou/media-player",
-  "version": "0.8.2",
+  "version": "0.8.4",
   "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/react/components/chrome.tsx

@@ -1,7 +1,7 @@
 /// <reference types="@emotion/react/types/css-prop" />
 import type { ReactNode, Ref } from 'react'
 
-import { useEffect, useRef } from 'react'
+import { Children, Fragment, isValidElement, useEffect, useRef } from 'react'
 import { css } from '@emotion/react'
 
 import { usePlayer } from '../player'
@@ -10,6 +10,30 @@ import ControlBar from './control-bar'
 
 const AUTO_HIDE_DELAY = 3_000
 
+/**
+ * One overlay item's own layer: the whole player box, and nothing else in it.
+ *
+ * The box is what makes an item positionable at all. Dropped straight into the chrome an item is
+ * absolutely positioned with no inset, which resolves to its static position, and the chrome centres
+ * its children, so a download readout came out painted across the middle of the picture. With this
+ * the app writes ordinary CSS against the picture: `top: 0; right: 0` is the top right corner of the
+ * video and of nothing else.
+ *
+ * One layer per item rather than one for all of them, so an item's own CSS can never move a sibling.
+ */
+const overlayItemStyle = css`
+  position: absolute;
+  inset: 0;
+  z-index: 2;
+  /* Never eats a click: click-to-pause still reaches the video underneath, and an item that needs a
+     pointer (a tooltip anchor, a button) sets \`pointer-events: auto\` on itself. */
+  pointer-events: none;
+  /* visibility, not only opacity: an item that took pointer events back would otherwise stay
+     hoverable while faded out, popping a tooltip over nothing. It cascades where pointer-events does
+     not, and transitioning it holds the item on screen for the length of the fade. */
+  transition: opacity 0.1s cubic-bezier(.4,0,1,1), visibility 0.1s;
+`
+
 const style = css`
   position: relative;
   background-color: black;
@@ -44,17 +68,39 @@ const style = css`
   }
 `
 
+/**
+ * The overlay's top-level items, one entry per layer to draw.
+ *
+ * `Children.toArray` alone is not enough. It flattens an ARRAY and keys what it returns, but a
+ * fragment stays one child, and `<>{a}{b}</>` is the shorthand an app reaches for before it reaches
+ * for an array. Left unflattened both items land in one layer, where the first item's CSS decides
+ * where the second one goes, which is exactly what having a layer each is for.
+ *
+ * Keys are built from the path rather than taken from each level, because `Children.toArray` numbers
+ * from zero inside every call it makes: two fragments each holding one unkeyed item both hand back
+ * `.0`, and React would treat the second layer as the first one re-rendered.
+ */
+const overlayItems = (node: ReactNode, prefix = ''): { key: string, item: ReactNode }[] =>
+  Children.toArray(node).flatMap((child, index) => {
+    const key = `${prefix}${isValidElement(child) && child.key != null ? child.key : index}`
+    return isValidElement(child) && child.type === Fragment
+      ? overlayItems((child.props as { children?: ReactNode }).children, `${key}/`)
+      : [{ key, item: child }]
+  })
+
 export type ChromeProps = {
   ref?: Ref<HTMLDivElement> | ((element: HTMLDivElement | null) => void)
   /** Absent means render no video element: the media belongs to someone else and arrives as children. */
   onVideoRef?: (element: HTMLVideoElement | null) => void
   onCanvasRef: (element: HTMLCanvasElement | null) => void
-  /** The app's own content, drawn in the top bar beside the title, unlike `children`. */
+  /** The app's own content, over the video and outside the click-to-pause region, unlike `children`. */
   overlay?: ReactNode
+  /** False draws no control bar at all, leaving the picture, the title and the overlay. */
+  controls?: boolean
   children?: ReactNode
 }
 
-export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, children }: ChromeProps) => {
+export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, controls, children }: ChromeProps) => {
   const player = usePlayer()
   const hideUI = usePlayer((state) => state.hideUI)
   const setHideUI = usePlayer((state) => state.setHideUI)
@@ -116,8 +162,17 @@ export const Chrome = ({ ref, onVideoRef, onCanvasRef, overlay, children }: Chro
       onMouseOut={onMouseOut}
       className={hideUI ? 'hide' : ''}
     >
-      <Overlay onCanvasRef={onCanvasRef} overlay={overlay} />
-      <ControlBar />
+      <Overlay onCanvasRef={onCanvasRef} />
+      {overlayItems(overlay).map(({ key, item }) => (
+        <div
+          key={key}
+          css={overlayItemStyle}
+          style={{ ...hideUI ? { opacity: '0', visibility: 'hidden', pointerEvents: 'none' } : {} }}
+        >
+          {item}
+        </div>
+      ))}
+      {controls === false ? null : <ControlBar />}
       <div className="video" onClick={onVideoClick}>
         {onVideoRef ? <video ref={onVideoRef} playsInline /> : null}
         {children}

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

@@ -15,74 +15,35 @@ const style = css`
   pointer-events: none;
 `
 
-/**
- * Title on the left, the app's own readout on the right, one gradient behind both.
- *
- * They share a row rather than sitting in two layers because they are the same band of screen: a
- * filename wide enough to wrap would otherwise run under whatever the app put on the right, and two
- * stacked gradients would double the darkening.
- */
-const topBarStyle = css`
+const titleStyle = css`
   position: absolute;
   top: 0;
   left: 0;
   width: 100%;
+  padding: calc(1.2 * var(--mp-unit)) calc(1.6 * var(--mp-unit));
+  /* clears a notch once the player is fullscreen; resolves to zero everywhere else */
+  padding-top: calc(calc(1.2 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
+  ${fonts.headings.small}
+  color: white;
+  text-shadow: 0 0 4px rgba(0, 0, 0, 1);
   z-index: 2;
-  /* the video underneath keeps the click that toggles playback; anything in the slot that needs a
-     pointer takes it back for itself */
   pointer-events: none;
 
-  display: flex;
-  align-items: flex-start;
-  gap: calc(1.6 * var(--mp-unit));
-
-  /* longhands per breakpoint, never the shorthand: a nested at-rule is hoisted after the rule it
-     sits in, so a shorthand in a media query would override the longhands above it and silently
-     drop the safe-area insets. Those clear a notch once the player is fullscreen and resolve to
-     zero everywhere else. */
-  padding-top: calc(calc(1.2 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
-  padding-bottom: calc(1.2 * var(--mp-unit));
-  padding-left: calc(calc(1.6 * var(--mp-unit)) + env(safe-area-inset-left, 0px));
-  padding-right: calc(calc(1.6 * var(--mp-unit)) + env(safe-area-inset-right, 0px));
+  /* one line with an ellipsis until there is width to wrap, since a release filename would
+     otherwise run to four lines on a phone */
+  white-space: nowrap;
+  overflow: hidden;
+  text-overflow: ellipsis;
 
   @media (min-width: 768px) {
+    padding: calc(2.4 * var(--mp-unit));
     padding-top: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-top, 0px));
-    padding-bottom: calc(2.4 * var(--mp-unit));
-    padding-left: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-left, 0px));
-    padding-right: calc(calc(2.4 * var(--mp-unit)) + env(safe-area-inset-right, 0px));
+    white-space: normal;
+    overflow: visible;
   }
 
   background: linear-gradient(180deg, rgba(0,0,0,0.4) 0%, rgba(0,0,0,0.3) 30%, rgba(0,0,0,0.2) 60%, rgba(0,0,0,0.1) 80%, transparent 100%);
-  /* visibility, not only opacity: a slot child that took pointer events back would otherwise stay
-     hoverable while faded out, popping a tooltip over nothing. It cascades where pointer-events
-     does not, and transitioning it holds the element visible for the length of the fade. */
-  transition: opacity 0.1s cubic-bezier(.4,0,1,1), visibility 0.1s;
-
-  .title {
-    ${fonts.headings.small}
-    color: white;
-    text-shadow: 0 0 4px rgba(0, 0, 0, 1);
-
-    /* one line with an ellipsis until there is width to wrap, since a release filename would
-       otherwise run to four lines on a phone */
-    flex: 1;
-    min-width: 0;
-    white-space: nowrap;
-    overflow: hidden;
-    text-overflow: ellipsis;
-
-    @media (min-width: 768px) {
-      white-space: normal;
-      overflow: visible;
-    }
-  }
-
-  /* pinned right with or without a title, so an app's readout does not jump sideways when a
-     filename arrives late */
-  .app-slot {
-    margin-left: auto;
-    flex: none;
-  }
+  transition: opacity 0.1s cubic-bezier(.4,0,1,1);
 `
 
 const spin = keyframes`
@@ -127,13 +88,7 @@ const errorMessage = (error: unknown) =>
     ? error.message
     : typeof error === 'string' ? error : 'Playback failed'
 
-export type OverlayProps = {
-  onCanvasRef: (element: HTMLCanvasElement | null) => void
-  /** The app's own content, drawn at the right of the top bar next to the title. */
-  overlay?: ReactNode
-}
-
-export const Overlay = ({ onCanvasRef, overlay }: OverlayProps) => {
+export const Overlay = ({ onCanvasRef }: { onCanvasRef: (element: HTMLCanvasElement | null) => void }) => {
   const title = usePlayer((state) => state.title)
   const hideUI = usePlayer((state) => state.hideUI)
   const playbackError = usePlayer((state) => state.playbackError)
@@ -144,14 +99,14 @@ export const Overlay = ({ onCanvasRef, overlay }: OverlayProps) => {
 
   return (
     <>
-      {title || overlay
+      {title
         ? (
           <div
-            css={topBarStyle}
-            style={{ ...hideUI ? { opacity: '0', visibility: 'hidden', pointerEvents: 'none' } : {} }}
+            className="title"
+            css={titleStyle}
+            style={{ ...hideUI ? { opacity: '0', pointerEvents: 'none' } : {} }}
           >
-            {title ? <div className="title">{title}</div> : undefined}
-            {overlay ? <div className="app-slot">{overlay}</div> : undefined}
+            {title}
           </div>
         )
         : undefined}

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

@@ -158,6 +158,22 @@ position: relative;
   .description {
     word-break: break-word;
   }
+
+  /* Dimmed and inert, but still listed. A source that names a track it cannot serve right now is
+     saying the track exists, and dropping the row would read as the source having nothing. */
+  .unavailable {
+    opacity: 0.5;
+    cursor: default;
+    :hover {
+      background-color: transparent;
+    }
+  }
+
+  .failed {
+    border-bottom: 1px solid #4D4D4E;
+    color: #f66;
+    ${fonts.bSmall.regular}
+  }
 }
 `
 
@@ -168,46 +184,55 @@ enum PopoverContent {
   Audio
 }
 
-/** One track picker, shared by the subtitle and audio menus. */
+/**
+ * One track picker, shared by the subtitle and audio menus.
+ *
+ * `pending` and `failed` describe the switch the viewer just asked for, not the menu: while a source
+ * is working, every row is inert and the one being switched to says so, because the selection has
+ * not moved yet and a tick next to it would be a lie.
+ */
 const TrackMenu = (
-  { title, tracks, selected, onSelect, onBack, allowDisable }: {
+  { title, tracks, selected, onSelect, onBack, offLabel, pending, failed }: {
     title: string
     tracks: TrackChoice[]
     selected: string | number | undefined
     onSelect: (id: string | number | undefined) => void
     onBack: () => void
-    allowDisable?: boolean
+    /** Absent means the menu offers no way off at all, which is what audio wants. */
+    offLabel?: string
+    /** The id currently being switched to, where `null` is the off row and undefined means idle. */
+    pending?: string | number | null
+    failed?: boolean
+  }
+) => {
+  const busy = pending !== undefined
+  const row = (id: string | number | null, label: string, className?: string) => {
+    const isPending = busy && pending === id
+    const disabled = busy || tracks.find((track) => track.id === id)?.disabled
+    return (
+      <div
+        key={id ?? '__off__'}
+        onClick={() => { if (!disabled) onSelect(id ?? undefined) }}
+        className={[className, disabled ? 'unavailable' : null].filter(Boolean).join(' ') || undefined}
+      >
+        <span>{label}</span>
+        <span>{isPending ? '…' : (selected ?? null) === id ? '✓' : ''}</span>
+      </div>
+    )
   }
-) => (
-  <div className='popover track-list'>
-    <div className="back" onClick={onBack}>
-      <ChevronLeft />
-      <span>{title}</span>
+
+  return (
+    <div className='popover track-list'>
+      <div className="back" onClick={onBack}>
+        <ChevronLeft />
+        <span>{title}</span>
+      </div>
+      {failed ? <div className="no-hover failed">Could not switch. Try again.</div> : null}
+      {offLabel ? row(null, offLabel) : null}
+      {tracks.map(({ id, label }) => row(id, label, 'description'))}
     </div>
-    {
-      allowDisable
-        ? (
-          <div onClick={() => onSelect(undefined)}>
-            <span>Disable</span>
-            <span>{selected === undefined ? '✓' : ''}</span>
-          </div>
-        )
-        : null
-    }
-    {
-      tracks.map(({ id, label }) => (
-        <div
-          key={id}
-          onClick={() => onSelect(id)}
-          className="description"
-        >
-          <span>{label}</span>
-          <span>{selected === id ? '✓' : ''}</span>
-        </div>
-      ))
-    }
-  </div>
-)
+  )
+}
 
 export const SettingsAction = () => {
   const player = usePlayer()
@@ -219,13 +244,27 @@ export const SettingsAction = () => {
   const selectedAudioTrack = usePlayer((state) => state.selectedAudioTrack)
   const selectAudioTrack = usePlayer((state) => state.selectAudioTrack)
 
+  const subtitleOffLabel = usePlayer((state) => state.subtitleOffLabel)
+
   const [isOpenPopover, setIsOpenPopover] = useState(false)
   const [popoverContent, setPopoverContent] = useState(PopoverContent.Default)
   const settingsContainerRef = useRef<HTMLDivElement>(null)
+  // The id being switched to, or undefined when nothing is in flight. Null is the row that turns
+  // subtitles off, so this cannot be a plain id: undefined has to keep meaning idle.
+  const [pending, setPending] = useState<string | number | null | undefined>(undefined)
+  const [failed, setFailed] = useState(false)
 
   const togglePopover = () => {
     setIsOpenPopover(!isOpenPopover)
     setPopoverContent(PopoverContent.Default)
+    setFailed(false)
+  }
+
+  // Not `togglePopover`: this runs from a promise, where the captured `isOpenPopover` is whatever it
+  // was at click time, so a toggle could reopen a menu the viewer has already dismissed.
+  const closePopover = () => {
+    setIsOpenPopover(false)
+    setPopoverContent(PopoverContent.Default)
   }
 
   const setPlaybackRate = (rate: number) => {
@@ -248,15 +287,50 @@ export const SettingsAction = () => {
     return () => document.removeEventListener('pointerdown', handleClickOutside)
   }, [isOpenPopover])
 
-  const chooseSubtitle = (id: string | number | undefined) => {
-    selectSubtitleTrack(id)
-    togglePopover()
+  /**
+   * Runs a track switch and decides when the menu may close.
+   *
+   * A selector that returns nothing switched synchronously, so the click closes the menu as it always
+   * has. One that returns a promise owns a player this one cannot reach, and the menu stays open and
+   * inert until it answers: closing first would show a selection that has not happened yet, and
+   * dropping the promise would turn a failed switch into an unhandled rejection nobody ever sees.
+   */
+  const runSelect = (id: string | number | null, select: () => void | Promise<void>) => {
+    if (pending !== undefined) return
+    setFailed(false)
+    let result: void | Promise<void>
+    try {
+      result = select()
+    } catch (err) {
+      console.warn('[media-player] track selection failed:', err)
+      setFailed(true)
+      return
+    }
+    if (!(result instanceof Promise)) {
+      closePopover()
+      return
+    }
+    setPending(id)
+    result.then(
+      () => {
+        setPending(undefined)
+        closePopover()
+      },
+      (err) => {
+        console.warn('[media-player] track selection failed:', err)
+        setPending(undefined)
+        setFailed(true)
+      },
+    )
   }
 
+  const chooseSubtitle = (id: string | number | undefined) =>
+    runSelect(id ?? null, () => selectSubtitleTrack(id))
+
+  // the audio menu offers no way off, so there is no undefined case to answer for
   const chooseAudio = (id: string | number | undefined) => {
-    // the audio menu never offers "Disable"
-    if (id !== undefined) selectAudioTrack(id)
-    togglePopover()
+    if (id === undefined) return
+    runSelect(id, () => selectAudioTrack(id))
   }
 
   const changePopoverContent = (newPopoverContent: PopoverContent) => () => {
@@ -362,7 +436,9 @@ export const SettingsAction = () => {
             selected={selectedSubtitleTrack}
             onSelect={chooseSubtitle}
             onBack={changePopoverContent(PopoverContent.Default)}
-            allowDisable
+            offLabel={subtitleOffLabel ?? 'Disable'}
+            pending={pending}
+            failed={failed}
           />
         )
       }
@@ -374,6 +450,8 @@ export const SettingsAction = () => {
             selected={selectedAudioTrack}
             onSelect={chooseAudio}
             onBack={changePopoverContent(PopoverContent.Default)}
+            pending={pending}
+            failed={failed}
           />
         )
       }