react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.20

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)

package/src/features/player/setup.test.ts

@@ -52,7 +52,11 @@ describe('setupPlayer wire regrouping', () => {
         minBuffer: 50_000,
         wakeMode: 'network',
         skipSilence: true,
-        notificationButtons: { overflow: ['favorite'] }
+        remoteButtonLayout: {
+          back: 'jump-backward',
+          forward: 'jump-forward',
+          overflow: ['favorite']
+        }
       }
     })
 
@@ -61,19 +65,32 @@ describe('setupPlayer wire regrouping', () => {
     expect(sent.options).toEqual({
       android: {
         skipSilence: true,
-        notificationButtons: { overflow: ['favorite'] }
+        remoteButtonLayout: {
+          back: 'jump-backward',
+          forward: 'jump-forward',
+          overflow: ['favorite']
+        }
       }
     })
   })
 
-  it('moves ios playbackRates into the runtime options', async () => {
+  it('moves ios runtime fields into the runtime options', async () => {
     await setupPlayer({
-      ios: { category: 'playback', playbackRates: [0.5, 1, 2] }
+      ios: {
+        category: 'playback',
+        playbackRates: [0.5, 1, 2],
+        carPlayPlayingIndicatorLocation: 'trailing'
+      }
     })
 
     const sent = payload()
     expect(sent.ios).toEqual({ category: 'playback' })
-    expect(sent.options).toEqual({ ios: { playbackRates: [0.5, 1, 2] } })
+    expect(sent.options).toEqual({
+      ios: {
+        playbackRates: [0.5, 1, 2],
+        carPlayPlayingIndicatorLocation: 'trailing'
+      }
+    })
   })
 
   it('omits a platform bag that only carried runtime fields', async () => {
@@ -85,12 +102,12 @@ describe('setupPlayer wire regrouping', () => {
   it('forwards meaningful nulls (progress disabled, empty button layout)', async () => {
     await setupPlayer({
       progressUpdateEventInterval: null,
-      android: { notificationButtons: null }
+      android: { remoteButtonLayout: null }
     })
 
     expect(payload().options).toEqual({
       progressUpdateEventInterval: null,
-      android: { notificationButtons: null }
+      android: { remoteButtonLayout: null }
     })
   })
 

package/src/features/player/setup.ts

@@ -11,7 +11,7 @@ import type {
   UpdateOptions
 } from './options'
 import { nativeBrowser } from '../../native'
-import { validateIOSUpdateOptions } from './options'
+import { validateIOSUpdateOptions } from './validateOptions'
 
 /**
  * Parameters passed to the {@link FormatNowPlayingCallback}.
@@ -25,7 +25,10 @@ import { validateIOSUpdateOptions } from './options'
 export type FormatNowPlayingParams = {
   /** The currently playing track. */
   track: Track
-  /** Timed metadata (ICY / ID3 "now playing song") received during playback, if any. */
+  /**
+   * Timed metadata (ICY / ID3 "now playing song") received during playback, if any.
+   * Always `undefined` on web — see `onTimedMetadata` for why.
+   */
   timedMetadata?: TimedMetadata
   /** The play/pause intent — `false` while paused. Stays `true` through buffers, so the song line won't flicker. */
   playWhenReady: boolean
@@ -326,7 +329,7 @@ export type AndroidPlayerWakeMode = 'none' | 'local' | 'network'
 
 /**
  * Android setup options: the engine-construction fields plus the Android runtime options
- * ({@link AndroidUpdateOptions} — `notificationButtons`, `skipSilence`, …), all expressible at
+ * ({@link AndroidUpdateOptions} — `remoteButtonLayout`, `skipSilence`, …), all expressible at
  * launch. The consumer never has to know which is which; `setupPlayer` routes each field to
  * where it's applied.
  */
@@ -496,7 +499,7 @@ export interface NativeSetupPlayerOptions extends Pick<
 
   /**
    * Player options to apply atomically with setup. They're stored before the player is
-   * constructed, so e.g. Android's media session derives its notification buttons from
+   * constructed, so e.g. Android's media session derives its remote button layout from
    * `capabilities` the moment the service connects — no window with default controls.
    * Normalized from the flat fields on {@link SetupPlayerOptions}.
    */
@@ -658,7 +661,7 @@ function wrapNowPlayingFormatter(
 
 /**
  * The object's entries whose values aren't `undefined`. `null` stays: it's meaningful on some
- * fields (`progressUpdateEventInterval: null` disables progress events, `notificationButtons:
+ * fields (`progressUpdateEventInterval: null` disables progress events, `remoteButtonLayout:
  * null` empties the layout), so only `undefined` means "not provided".
  */
 function definedFields<T extends object>(obj: T): Partial<T> {
@@ -682,7 +685,7 @@ function nonEmpty<K extends string, T extends object>(
 /**
  * Initializes the player with the specified options — the full launch description in one
  * declarative, atomic call. Runtime options (`capabilities`, jump intervals,
- * `notificationButtons`, …) and the initial `playWhenReady` / `repeatMode` are applied
+ * `remoteButtonLayout`, …) and the initial `playWhenReady` / `repeatMode` are applied
  * natively as part of setup itself, so there is no setup-then-command ordering for consumers
  * to know about, and no window where the player exists without its options.
  *
@@ -699,7 +702,14 @@ function nonEmpty<K extends string, T extends object>(
  *   playWhenReady: true,
  *   repeatMode: 'queue',
  *   capabilities: { favorite: true },
- *   android: { audioContentType: 'music', notificationButtons: { overflow: ['favorite'] } },
+ *   android: {
+ *     audioContentType: 'music',
+ *     remoteButtonLayout: {
+ *       back: 'jump-backward',
+ *       forward: 'jump-forward',
+ *       overflow: ['favorite']
+ *     }
+ *   },
  *   ios: { category: 'playback' }
  * })
  * ```
@@ -724,19 +734,21 @@ export async function setupPlayer(
   const {
     appKilledPlaybackBehavior,
     skipSilence,
-    notificationButtons,
+    remoteButtonLayout,
     ...androidSetup
   } = android
   const {
     playbackRates,
     carPlayUpNextButton,
     carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation,
     ...iosSetup
   } = ios
   const iosUpdate = definedFields({
     playbackRates,
     carPlayUpNextButton,
-    carPlayNowPlayingButtons
+    carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation
   })
   validateIOSUpdateOptions(iosUpdate)
 
@@ -750,7 +762,7 @@ export async function setupPlayer(
       definedFields({
         appKilledPlaybackBehavior,
         skipSilence,
-        notificationButtons
+        remoteButtonLayout
       })
     ),
     ...nonEmpty('ios', iosUpdate)

package/src/features/player/validateOptions.ts

@@ -0,0 +1,21 @@
+import type { IOSUpdateOptions } from './options'
+
+const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
+
+/**
+ * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
+ * Shared by `updateOptions` and `setupPlayer` (both can carry `ios` options).
+ * Kept out of `options.ts`, which the barrel re-exports — see
+ * public-surface.test.ts.
+ *
+ * @internal
+ */
+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}.`
+    )
+  }
+}

package/src/features/queue/activeTrack.ts

@@ -1,7 +1,8 @@
 import type { Track } from '../../types'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
-import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { useNativeValueRefreshedBy } from '../../utils/useNativeValueRefreshedBy'
+import { onFavoriteChanged } from '../favorites'
 
 /**
  * Event data for when the active track changes.
@@ -40,8 +41,14 @@ export function getActiveTrackIndex(): number | undefined {
 
 /**
  * Subscribes to active track change events.
+ *
+ * Fires on **transitions only** — selection, queue advance, skip. In-place
+ * metadata mutations of the active track (a favorite toggle) emit
+ * {@link onFavoriteChanged} instead; {@link useActiveTrack} subscribes to
+ * both, so UI bound through the hook still re-renders on a heart toggle.
+ *
  * @param callback - Called when the active track changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onActiveTrackChanged =
   NativeUpdatedValue.emitterize<PlaybackActiveTrackChangedEvent>(
@@ -50,10 +57,14 @@ export const onActiveTrackChanged =
 
 // MARK: - Hooks
 
+// Module-level so the hook's subscription identity is stable across renders.
+const activeTrackInvalidators = [onActiveTrackChanged, onFavoriteChanged]
+
 /**
- * Hook that returns the current active track and updates when it changes.
+ * Hook that returns the current active track, updating on transitions AND on
+ * in-place mutations of the active track (favorite toggles).
  * @returns The current active track or undefined
  */
 export function useActiveTrack(): Track | undefined {
-  return useNativeUpdatedValue(getActiveTrack, onActiveTrackChanged, 'track')
+  return useNativeValueRefreshedBy(getActiveTrack, activeTrackInvalidators)
 }

package/src/features/queue/queue.ts

@@ -1,7 +1,8 @@
 import type { Track } from '../../types'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
-import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { useNativeValueRefreshedBy } from '../../utils/useNativeValueRefreshedBy'
+import { onFavoriteChanged } from '../favorites'
 
 // MARK: - Types
 
@@ -156,7 +157,7 @@ export function getQueue(): Track[] {
 /**
  * Subscribes to playback queue ended events.
  * @param callback - Called when playback has paused due to reaching the end of the queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueEnded =
   NativeUpdatedValue.emitterize<PlaybackQueueEndedEvent>(
@@ -165,9 +166,11 @@ export const onQueueEnded =
 
 /**
  * Subscribes to queue change events.
- * Called when tracks are added, removed, reordered, or when track metadata changes.
+ * Called when tracks are added, removed, or reordered. An in-place mutation of
+ * a queued track's metadata (a favorite toggle) emits `onFavoriteChanged`
+ * instead; {@link useQueue} subscribes to both.
  * @param callback - Called with the updated queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
   (cb) => (nativeBrowser.onPlaybackQueueChanged = cb)
@@ -175,10 +178,14 @@ export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
 
 // MARK: - Hooks
 
+// Module-level so the hook's subscription identity is stable across renders.
+const queueInvalidators = [onQueueChanged, onFavoriteChanged]
+
 /**
- * Hook that returns the current queue and updates when it changes.
+ * Hook that returns the current queue, updating on queue changes AND on
+ * in-place mutations of queued tracks (favorite toggles).
  * @returns The current queue
  */
 export function useQueue(): Track[] {
-  return useNativeUpdatedValue(getQueue, onQueueChanged)
+  return useNativeValueRefreshedBy(getQueue, queueInvalidators)
 }

package/src/features/queue/repeatMode.ts

@@ -40,7 +40,7 @@ export interface RepeatModeChangedEvent {
 /**
  * Subscribes to repeat mode changes.
  * @param callback - Called when repeat mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRepeatModeChanged =
   NativeUpdatedValue.emitterize<RepeatModeChangedEvent>(

package/src/features/queue/shuffle.ts

@@ -32,7 +32,7 @@ export function toggleShuffle(): void {
 /**
  * Subscribes to shuffle mode changes.
  * @param callback - Called when shuffle mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onPlaybackShuffleModeChanged = cb)