react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/src/features/playback/progress.test.ts

@@ -0,0 +1,169 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { Progress } from './progress'
+import {
+  appStateListenerCount,
+  resetAppState,
+  setAppState
+} from '../../test-utils/reactNativeStub'
+
+const native = vi.hoisted(() => ({
+  getProgress: vi.fn<() => Progress>(() => ({
+    position: 0,
+    duration: 0,
+    buffered: 0
+  })),
+  onPlaybackChanged: undefined as ((event: unknown) => void) | undefined,
+  onPlaybackProgressUpdated: undefined as ((event: unknown) => void) | undefined
+}))
+
+vi.mock('../../native', () => ({ nativeBrowser: native }))
+
+const { usePolledProgress } = await import('./progress')
+
+const at = (position: number): Progress => ({
+  position,
+  duration: 300,
+  buffered: position + 10
+})
+
+beforeEach(() => {
+  vi.useFakeTimers()
+  resetAppState()
+  native.getProgress.mockReturnValue(at(0))
+})
+
+afterEach(() => {
+  cleanup()
+  vi.useRealTimers()
+})
+
+describe('usePolledProgress', () => {
+  it('starts at zero and polls the first value in', () => {
+    native.getProgress.mockReturnValue(at(12))
+    const { result } = renderHook(() => usePolledProgress())
+    // The initial poll runs inside the effect, so the zeroed useState default is
+    // never observable to a caller.
+    expect(result.current).toEqual(at(12))
+  })
+
+  it('polls on the given interval', () => {
+    const { result } = renderHook(() => usePolledProgress(500))
+    native.getProgress.mockReturnValue(at(1))
+    act(() => {
+      vi.advanceTimersByTime(500)
+    })
+    expect(result.current).toEqual(at(1))
+
+    native.getProgress.mockReturnValue(at(2))
+    act(() => {
+      vi.advanceTimersByTime(500)
+    })
+    expect(result.current).toEqual(at(2))
+  })
+
+  it('does not poll before the interval elapses', () => {
+    renderHook(() => usePolledProgress(1000))
+    native.getProgress.mockClear()
+    act(() => {
+      vi.advanceTimersByTime(999)
+    })
+    expect(native.getProgress).not.toHaveBeenCalled()
+  })
+
+  it('keeps the same object when nothing changed', () => {
+    const { result } = renderHook(() => usePolledProgress(500))
+    const first = result.current
+    act(() => {
+      vi.advanceTimersByTime(500)
+    })
+    // Identity, not equality: the hook returns the previous state object so a
+    // consumer's useEffect/memo on progress does not re-fire every tick.
+    expect(result.current).toBe(first)
+  })
+
+  it('updates immediately when playback changes, without waiting for a tick', () => {
+    const { result } = renderHook(() => usePolledProgress(10_000))
+    native.getProgress.mockReturnValue(at(7))
+    act(() => {
+      native.onPlaybackChanged?.({ state: 'playing' })
+    })
+    expect(result.current).toEqual(at(7))
+  })
+
+  it('survives a getter that throws before setup', () => {
+    native.getProgress.mockImplementation(() => {
+      throw new Error('not set up')
+    })
+    const { result } = renderHook(() => usePolledProgress(500))
+    expect(result.current).toEqual({ position: 0, duration: 0, buffered: 0 })
+    expect(() => act(() => vi.advanceTimersByTime(500))).not.toThrow()
+  })
+
+  it('stops polling in the background and resumes on return', () => {
+    const { result } = renderHook(() => usePolledProgress(500))
+
+    act(() => {
+      setAppState('background')
+    })
+    native.getProgress.mockReturnValue(at(99))
+    act(() => {
+      vi.advanceTimersByTime(5_000)
+    })
+    expect(result.current).toEqual(at(0))
+
+    // Returning to the foreground updates once immediately rather than leaving
+    // a stale position on screen until the next interval.
+    act(() => {
+      setAppState('active')
+    })
+    expect(result.current).toEqual(at(99))
+  })
+
+  it('ignores playback events while backgrounded', () => {
+    const { result } = renderHook(() => usePolledProgress(500))
+    act(() => {
+      setAppState('background')
+    })
+    native.getProgress.mockReturnValue(at(42))
+    act(() => {
+      native.onPlaybackChanged?.({ state: 'playing' })
+    })
+    expect(result.current).toEqual(at(0))
+  })
+
+  it('does not stack pollers when backgrounded twice', () => {
+    renderHook(() => usePolledProgress(500))
+    act(() => {
+      setAppState('background')
+    })
+    act(() => {
+      setAppState('active')
+    })
+    act(() => {
+      setAppState('active')
+    })
+
+    native.getProgress.mockClear()
+    act(() => {
+      vi.advanceTimersByTime(500)
+    })
+    expect(native.getProgress).toHaveBeenCalledTimes(1)
+  })
+
+  it('tears down its timer and subscriptions on unmount', () => {
+    const { unmount } = renderHook(() => usePolledProgress(500))
+    expect(appStateListenerCount()).toBe(1)
+
+    unmount()
+    expect(appStateListenerCount()).toBe(0)
+
+    native.getProgress.mockClear()
+    act(() => {
+      vi.advanceTimersByTime(5_000)
+    })
+    expect(native.getProgress).not.toHaveBeenCalled()
+  })
+})

package/src/features/playback/progress.ts

@@ -46,7 +46,7 @@ export function getProgress(): Progress {
 /**
  * Subscribes to playback progress updates.
  * @param callback - Called periodically with playback progress updates
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onProgressUpdated =
   NativeUpdatedValue.emitterize<PlaybackProgressUpdatedEvent>(
@@ -118,7 +118,8 @@ export function usePolledProgress(updateInterval = 1000): Progress {
     }
 
     const stop = () => {
-      clearTimeout(timer)
+      // Guarded: React Native types clearTimeout(handle: number) — no undefined.
+      if (timer !== undefined) clearTimeout(timer)
       timer = undefined
       unsubscribeState?.()
       unsubscribeState = undefined

package/src/features/playback/rate.ts

@@ -14,8 +14,15 @@ export function getRate(): number {
 
 /**
  * Sets the playback rate.
+ *
+ * The rate is a speed multiplier, not a transport control — it is independent
+ * of play/pause, and setting it while paused never starts playback. Use
+ * {@link play} / {@link pause} for that.
+ *
  * @param rate - The playback rate to change to, where 0.5 would be half speed,
- * 1 would be regular speed, 2 would be double speed etc.
+ * 1 would be regular speed, 2 would be double speed etc. Must be greater than
+ * zero; platforms disagree on what a non-positive rate does (iOS ignores it,
+ * Android throws, web stalls the element), so treat it as unsupported.
  */
 export function setRate(rate: number): void {
   nativeBrowser.setRate(rate)

package/src/features/playback/state.ts

@@ -18,9 +18,8 @@ import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
  * - `'buffering'`: Indicates that the player is currently loading more data
  *   before it can continue playing or is ready to start playing.
  * - `'error'`: Indicates that playback of the current item failed. Call
- *   `AudioBrowser.getError()` to get more information on the type of error that
- *   occurred. Call `AudioBrowser.retry()` or `AudioBrowser.play()` to try to play
- *   the item again.
+ *   `getPlaybackError()` (or subscribe via `usePlaybackError()`) for the
+ *   error details. Call `retry()` or `play()` to try to play the item again.
  * - `'ended'`: Indicates that playback stopped due to the end of the queue
  *   being reached.
  */
@@ -55,7 +54,7 @@ export function getPlayback(): Playback {
 /**
  * Subscribes to playback state changes.
  * @param callback - Called when the playback state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
   (cb) => (nativeBrowser.onPlaybackChanged = cb)

package/src/features/playback/trackPlaybackTime.test.ts

@@ -13,12 +13,22 @@ vi.mock('../queue/activeTrack', () => ({
   onActiveTrackChanged: { addListener: vi.fn(() => () => {}) }
 }))
 
-import { trackPlaybackTime, __emitTickForTests } from './trackPlaybackTime'
+import { trackPlaybackTime } from './trackPlaybackTime'
 
 beforeEach(() => {
   nativeMock.setPlaybackIntervalEnabled.mockClear()
 })
 
+/** Ticks through the slot `install()` assigns, so this covers that wiring too. */
+function tick(times = 1) {
+  for (let i = 0; i < times; i++) {
+    if (!nativeMock.onPlaybackInterval) {
+      throw new Error('trackPlaybackTime never installed onPlaybackInterval')
+    }
+    nativeMock.onPlaybackInterval()
+  }
+}
+
 describe('trackPlaybackTime', () => {
   it('enables native tick on first subscriber, disables on last', () => {
     const a = trackPlaybackTime(() => {}, 5)
@@ -38,17 +48,17 @@ describe('trackPlaybackTime', () => {
       (e) => calls.push({ total: e.total, sinceLast: e.sinceLast }),
       3
     )
-    __emitTickForTests(2)
+    tick(2)
     expect(calls).toEqual([])
-    __emitTickForTests(1) // total now 3 → fires
+    tick(1) // total now 3 → fires
     expect(calls).toEqual([{ total: 3, sinceLast: 3 }])
-    __emitTickForTests(3) // total now 6 → fires again
+    tick(3) // total now 6 → fires again
     expect(calls).toEqual([
       { total: 3, sinceLast: 3 },
       { total: 6, sinceLast: 3 }
     ])
     cancel()
-    __emitTickForTests(3)
+    tick(3)
     expect(calls).toHaveLength(2) // cancelled
   })
 
@@ -57,7 +67,7 @@ describe('trackPlaybackTime', () => {
     const slow: number[] = []
     const cancelFast = trackPlaybackTime((e) => fast.push(e.total), 1)
     const cancelSlow = trackPlaybackTime((e) => slow.push(e.total), 2)
-    __emitTickForTests(2)
+    tick(2)
     expect(fast).toEqual([1, 2])
     expect(slow).toEqual([2])
     cancelFast()

package/src/features/playback/trackPlaybackTime.ts

@@ -9,7 +9,7 @@ export interface PlaybackElapsed {
   total: number
   /** Seconds played since the previous callback (≈ `period`). */
   sinceLast: number
-  /** The currently playing track (id / src / url / title …), if any. */
+  /** The currently playing track (id / src / path / title …), if any. */
   track?: Track
 }
 
@@ -99,8 +99,3 @@ export function trackPlaybackTime(
     if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false)
   }
 }
-
-/** @internal test hook — drives the fan-out without a native tick. */
-export function __emitTickForTests(ticks = 1) {
-  for (let i = 0; i < ticks; i++) onTick()
-}

package/src/features/playback/volume.ts

@@ -42,7 +42,7 @@ export function setSystemVolume(level: number): void {
 /**
  * Subscribes to system volume changes.
  * @param callback - Called when the system volume changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onSystemVolumeChanged = NativeUpdatedValue.emitterize<number>(
   (cb) => (nativeBrowser.onSystemVolumeChanged = cb)

package/src/features/player/options.ts

@@ -1,8 +1,11 @@
-import type { FavoriteConfig } from '../../types'
-import type { CarPlayNowPlayingButton } from '../../types/browser'
+import type {
+  CarPlayNowPlayingButton,
+  CarPlayPlayingIndicatorLocation
+} from '../../types/browser'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
 import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { validateIOSUpdateOptions } from './validateOptions'
 
 // MARK: - Types
 
@@ -70,34 +73,26 @@ export interface PlayerCapabilities {
    *
    * Turns on the favorite/like heart across all surfaces:
    * - iOS: Control Center + CarPlay now-playing.
-   * - Android: notification button slot + Android Auto now-playing, and an
+   * - Android: a place in the {@link RemoteButtonLayout} — the notification,
+   *   Android Auto and the Android 13+ system media controls — and an
    *   (empty or filled) heart on playable browse rows.
    *
-   * `match` controls how the ids from `setFavorites` are
-   * compared against a track's `src` to decide its `favorited` state
-   * (see `FavoritesMatchMode`); `true` is shorthand for `'exact'`.
-   *
-   * - `false` / omitted: favoriting off everywhere.
-   * - `true`: on, with `'exact'` id matching.
-   * - `{ match }`: on, with the given match mode.
+   * The ids passed to `setFavorites` are matched exactly against a track's
+   * *identity* — its `id` when set, falling back to `src`. Store favorites as
+   * the same stable identifier you put in `Track.id` (or as the full `src`
+   * for tracks without an id).
    *
    * @example
    * ```ts
-   * // 'exact': a favorite id must equal the track's src.
-   * favorite: { match: 'exact' }
-   * setFavorites(['https://cdn.example.com/audio/track-42.mp3'])
-   * // → favorited when src === 'https://cdn.example.com/audio/track-42.mp3'
-   *
-   * // 'partial': a favorite id matches when it is a full path segment of src.
-   * favorite: { match: 'partial' }
+   * favorite: true
    * setFavorites(['track-42'])
-   * // → favorited when src is '/library/track-42' or '/stream/track-42?hq=1',
-   * //   but NOT '/library/track-420'
+   * // → favorited when track.id === 'track-42'
+   * //   (or, for id-less tracks, when track.src === 'track-42')
    * ```
    *
    * @default false
    */
-  favorite?: boolean | FavoriteConfig
+  favorite?: boolean
   /**
    * Enable shuffle mode toggle.
    * @default true
@@ -117,10 +112,11 @@ export interface PlayerCapabilities {
 }
 
 /**
- * Buttons that can be assigned to Android notification button slots.
- * These represent the interactive buttons users can tap in the notification.
+ * Buttons that can be placed in the Android button layout — the interactive
+ * controls a listener taps in the notification, on the Android Auto Now Playing
+ * screen, and in the Android 13+ system media controls.
  */
-export type NotificationButton =
+export type RemoteButton =
   | 'skip-to-previous'
   | 'skip-to-next'
   | 'jump-backward'
@@ -128,43 +124,71 @@ export type NotificationButton =
   | 'favorite'
 
 /**
- * Configuration for notification button layout on Android.
- * Allows explicit control over which buttons appear in which slots.
+ * Where each button sits on Android.
+ *
+ * Android offers exactly three positions, and play/pause always occupies the
+ * centre — you cannot move it, and you cannot put two buttons on the same side
+ * of it:
+ *
+ * ```
+ *   back  │  ▶ play/pause  │  forward        overflow ⋯
+ * ```
+ *
+ * - **`back`** — the single position left of play/pause
+ * - **`forward`** — the single position right of play/pause
+ * - **`overflow`** — everything else, in priority order
+ *
+ * **A layout describes the whole arrangement.** All three fields are required —
+ * there is no per-field merge with the capability defaults, so what you write is
+ * exactly what renders. Use `undefined` for an empty position and `[]` for no
+ * overflow. To go back to the derived defaults, omit `remoteButtonLayout`
+ * entirely (or set it to `null`); that is the only switch.
  *
- * Slot behavior:
- * - **Omit a slot**: Derive from capabilities (smart default)
- * - **Set to null**: Explicitly empty slot
- * - **Set to button**: Show that button in that slot
+ * **Overflow order is priority, not coordinates.** Each surface renders as many
+ * buttons as it has room for, taking them from the front — a phone
+ * notification, the Android 13+ system media controls, and a car head unit all
+ * have different budgets. A head unit with a spare slot may promote the first
+ * overflow entry onto the main row, and a long list gets truncated by whichever
+ * surface is showing it. Put what matters most first.
+ *
+ * Placement never changes what a control *can* do: a button left out entirely
+ * still responds to a Bluetooth remote or headset, as long as its
+ * {@link PlayerCapabilities} entry is enabled.
  *
  * @example
  * ```typescript
- * // Podcast-style: jump buttons as primary
- * notificationButtons: {
+ * // Podcast-style: jump either side of play/pause
+ * remoteButtonLayout: {
  *   back: 'jump-backward',
  *   forward: 'jump-forward',
- *   overflow: ['favorite']
+ *   overflow: ['skip-to-previous', 'skip-to-next', 'favorite']
  * }
  *
- * // Music-style: skip as primary, jump as secondary
- * notificationButtons: {
+ * // Music-style: skip either side of play/pause
+ * remoteButtonLayout: {
  *   back: 'skip-to-previous',
  *   forward: 'skip-to-next',
- *   backSecondary: 'jump-backward',
- *   forwardSecondary: 'jump-forward'
+ *   overflow: ['favorite']
+ * }
+ *
+ * // Live radio: forward only, nothing to the left
+ * remoteButtonLayout: {
+ *   back: undefined,
+ *   forward: 'skip-to-next',
+ *   overflow: []
  * }
  * ```
  */
-export type NotificationButtonLayout = {
-  /** Primary back position (SLOT_BACK) - typically previous track or jump backward */
-  back?: NotificationButton | null
-  /** Primary forward position (SLOT_FORWARD) - typically next track or jump forward */
-  forward?: NotificationButton | null
-  /** Secondary back position (SLOT_BACK_SECONDARY) */
-  backSecondary?: NotificationButton | null
-  /** Secondary forward position (SLOT_FORWARD_SECONDARY) */
-  forwardSecondary?: NotificationButton | null
-  /** Additional buttons in overflow area (SLOT_OVERFLOW) */
-  overflow?: NotificationButton[]
+export type RemoteButtonLayout = {
+  /** The single position left of play/pause. `undefined` leaves it empty. */
+  back: RemoteButton | undefined
+  /** The single position right of play/pause. `undefined` leaves it empty. */
+  forward: RemoteButton | undefined
+  /**
+   * Everything else, most important first — surfaces promote and truncate from
+   * the front. `[]` for none.
+   */
+  overflow: RemoteButton[]
 }
 
 /**
@@ -204,12 +228,22 @@ export interface Options {
 
   /**
    * Jump forward interval in seconds when using jump forward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   forwardJumpInterval: number
 
   /**
    * Jump backward interval in seconds when using jump backward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   backwardJumpInterval: number
@@ -254,6 +288,13 @@ export interface IOSOptions {
    * @default []
    */
   carPlayNowPlayingButtons: CarPlayNowPlayingButton[]
+
+  /**
+   * Where the now-playing indicator draws on CarPlay list rows.
+   * See {@link CarPlayPlayingIndicatorLocation}.
+   * @default 'leading'
+   */
+  carPlayPlayingIndicatorLocation: CarPlayPlayingIndicatorLocation
 }
 
 export interface AndroidOptions {
@@ -273,14 +314,14 @@ export interface AndroidOptions {
   skipSilence: boolean
 
   /**
-   * Slot-based button layout for Android notifications.
-   * Provides explicit control over which buttons appear in which positions.
+   * Ordered button layout, applied to the notification, Android Auto, and the
+   * Android 13+ system media controls. See {@link RemoteButtonLayout}.
    *
-   * When not specified, button layout is derived from capabilities.
+   * When not specified, the layout is derived from capabilities.
    *
    * @platform android
    */
-  notificationButtons: NotificationButtonLayout | null
+  remoteButtonLayout: RemoteButtonLayout | null
 }
 
 export interface AndroidUpdateOptions {
@@ -300,14 +341,14 @@ export interface AndroidUpdateOptions {
   skipSilence?: boolean
 
   /**
-   * Slot-based button layout for Android notifications.
-   * Provides explicit control over which buttons appear in which positions.
+   * Ordered button layout, applied to the notification, Android Auto, and the
+   * Android 13+ system media controls. See {@link RemoteButtonLayout}.
    *
-   * When not specified, button layout is derived from capabilities.
+   * When not specified, the layout is derived from capabilities.
    *
    * @platform android
    */
-  notificationButtons?: NotificationButtonLayout | null
+  remoteButtonLayout?: RemoteButtonLayout | null
 }
 
 /**
@@ -317,7 +358,7 @@ export interface AndroidUpdateOptions {
 export interface NitroAndroidUpdateOptions {
   appKilledPlaybackBehavior?: AppKilledPlaybackBehavior
   skipSilence?: boolean
-  notificationButtons?: NotificationButtonLayout | null
+  remoteButtonLayout?: RemoteButtonLayout | null
 }
 
 /**
@@ -350,6 +391,13 @@ export interface IOSUpdateOptions {
    * @default []
    */
   carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
+
+  /**
+   * Where the now-playing indicator draws on CarPlay list rows.
+   * See {@link CarPlayPlayingIndicatorLocation}.
+   * @default 'leading'
+   */
+  carPlayPlayingIndicatorLocation?: CarPlayPlayingIndicatorLocation
 }
 
 /**
@@ -360,6 +408,7 @@ export interface NitroIOSUpdateOptions {
   playbackRates?: number[]
   carPlayUpNextButton?: boolean
   carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
+  carPlayPlayingIndicatorLocation?: CarPlayPlayingIndicatorLocation
 }
 
 /**
@@ -394,12 +443,22 @@ export interface UpdateOptions {
 
   /**
    * Jump forward interval in seconds when using jump forward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   forwardJumpInterval?: number
 
   /**
    * Jump backward interval in seconds when using jump backward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   backwardJumpInterval?: number
@@ -442,12 +501,22 @@ export interface NativeUpdateOptions {
 
   /**
    * Jump forward interval in seconds when using jump forward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   forwardJumpInterval?: number
 
   /**
    * Jump backward interval in seconds when using jump backward controls.
+   *
+   * On Android, an interval of exactly 5, 10, 15 or 30 seconds gets an icon
+   * showing that number; any other interval gets an icon without one. Other
+   * values are perfectly valid — the interval also sets the seek distance.
+   *
    * @default 15
    */
   backwardJumpInterval?: number
@@ -464,25 +533,6 @@ export interface NativeUpdateOptions {
 
 // MARK: - Functions
 
-const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
-
-/**
- * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
- * Shared by {@link updateOptions} and `setupPlayer` (both can carry `ios` options).
- *
- * @internal Validation helper, not public API — `stripInternal` removes it from
- * the published types and typedoc hides it from the docs.
- */
-export function validateIOSUpdateOptions(ios?: IOSUpdateOptions): void {
-  const buttons = ios?.carPlayNowPlayingButtons
-  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
-    console.warn(
-      `[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` +
-        `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`
-    )
-  }
-}
-
 /**
  * Updates the configuration for the components.
  * Pass only the properties you want to change - all properties are optional.
@@ -527,7 +577,7 @@ export function getOptions(): Options {
 /**
  * Subscribes to player options changes.
  * @param callback - Called when the player options change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOptionsChanged = NativeUpdatedValue.emitterize<Options>(
   (cb) => (nativeBrowser.onOptionsChanged = cb)