react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.12

package/nitrogen/generated/shared/c++/TrackStyle.hpp

@@ -7,11 +7,6 @@
 
 #pragma once
 
-#if __has_include(<NitroModules/NitroHash.hpp>)
-#include <NitroModules/NitroHash.hpp>
-#else
-#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
-#endif
 #if __has_include(<NitroModules/JSIConverter.hpp>)
 #include <NitroModules/JSIConverter.hpp>
 #else
@@ -22,54 +17,75 @@
 #else
 #error NitroModules cannot be found! Are you sure you installed NitroModules properly?
 #endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `StyleDisplay` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class StyleDisplay; }
+// Forward declaration of `ArtworkRendering` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class ArtworkRendering; }
+
+#include "StyleDisplay.hpp"
+#include <optional>
+#include "ArtworkRendering.hpp"
 
 namespace margelo::nitro::audiobrowser {
 
   /**
-   * An enum which can be represented as a JavaScript union (TrackStyle).
+   * A struct which can be represented as a JavaScript object (TrackStyle).
    */
-  enum class TrackStyle {
-    LIST      SWIFT_NAME(list) = 0,
-    GRID      SWIFT_NAME(grid) = 1,
-  } CLOSED_ENUM;
+  struct TrackStyle final {
+  public:
+    std::optional<StyleDisplay> display     SWIFT_PRIVATE;
+    std::optional<ArtworkRendering> artworkRendering     SWIFT_PRIVATE;
+
+  public:
+    TrackStyle() = default;
+    explicit TrackStyle(std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering): display(display), artworkRendering(artworkRendering) {}
+
+  public:
+    friend bool operator==(const TrackStyle& lhs, const TrackStyle& rhs) = default;
+  };
 
 } // namespace margelo::nitro::audiobrowser
 
 namespace margelo::nitro {
 
-  // C++ TrackStyle <> JS TrackStyle (union)
+  // C++ TrackStyle <> JS TrackStyle (object)
   template <>
   struct JSIConverter<margelo::nitro::audiobrowser::TrackStyle> final {
     static inline margelo::nitro::audiobrowser::TrackStyle fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
-      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, arg);
-      switch (hashString(unionValue.c_str(), unionValue.size())) {
-        case hashString("list"): return margelo::nitro::audiobrowser::TrackStyle::LIST;
-        case hashString("grid"): return margelo::nitro::audiobrowser::TrackStyle::GRID;
-        default: [[unlikely]]
-          throw std::invalid_argument("Cannot convert \"" + unionValue + "\" to enum TrackStyle - invalid value!");
-      }
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::audiobrowser::TrackStyle(
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))
+      );
     }
-    static inline jsi::Value toJSI(jsi::Runtime& runtime, margelo::nitro::audiobrowser::TrackStyle arg) {
-      switch (arg) {
-        case margelo::nitro::audiobrowser::TrackStyle::LIST: return JSIConverter<std::string>::toJSI(runtime, "list");
-        case margelo::nitro::audiobrowser::TrackStyle::GRID: return JSIConverter<std::string>::toJSI(runtime, "grid");
-        default: [[unlikely]]
-          throw std::invalid_argument("Cannot convert TrackStyle to JS - invalid value: "
-                                    + std::to_string(static_cast<int>(arg)) + "!");
-      }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::TrackStyle& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "display"), JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::toJSI(runtime, arg.display));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::toJSI(runtime, arg.artworkRendering));
+      return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
-      if (!value.isString()) {
+      if (!value.isObject()) {
         return false;
       }
-      std::string unionValue = JSIConverter<std::string>::fromJSI(runtime, value);
-      switch (hashString(unionValue.c_str(), unionValue.size())) {
-        case hashString("list"):
-        case hashString("grid"):
-          return true;
-        default:
-          return false;
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
       }
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))) return false;
+      return true;
     }
   };
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.11",
+  "version": "0.2.0-next.12",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",

package/src/AudioBrowser.ts

@@ -1,4 +1,5 @@
 // `./native` is deliberately not re-exported — see public-surface.test.ts.
 export * from './features'
 export * from './types'
+export * from './utils/getTrackIdentity'
 export * from './utils/useDebug'

package/src/features/browser-config.test.ts

@@ -18,7 +18,7 @@ describe('toNativeConfig route classification', () => {
 
   it('keeps a static page with a string artwork out of the RouteConfig branch', () => {
     const page = {
-      url: '/x',
+      path: '/x',
       title: 'X',
       artwork: 'https://img.example.com/x.png',
       children: []
@@ -28,6 +28,21 @@ describe('toNativeConfig route classification', () => {
     expect(entry?.artwork).toBeUndefined()
   })
 
+  it('classifies a static page as static despite its top-level `path` key', () => {
+    // `path` is also a RequestConfig field; the page's required `title` must
+    // win the classification (a config with a `path` alone is not a page).
+    const page = { path: '/x', title: 'X', children: [] }
+    const entry = entryFor({ '/x': page }, '/x')
+    expect(entry?.browseStatic).toEqual(page)
+    expect(entry?.browseConfig).toBeUndefined()
+  })
+
+  it('classifies a path-only request config as a request config', () => {
+    const entry = entryFor({ '/x': { path: '/remapped' } }, '/x')
+    expect(entry?.browseConfig).toEqual({ path: '/remapped' })
+    expect(entry?.browseStatic).toBeUndefined()
+  })
+
   it('classifies a method-only request config as a request config', () => {
     const entry = entryFor({ '/x': { method: 'POST' } }, '/x')
     expect(entry?.browseConfig).toEqual({ method: 'POST' })
@@ -66,13 +81,13 @@ describe('validateBrowserConfiguration', () => {
   it('is silent for a valid configuration', () => {
     validateBrowserConfiguration({
       routes: {
-        '/favorites': async () => ({ url: '/favorites', title: 'Favorites' }),
+        '/favorites': async () => ({ path: '/favorites', title: 'Favorites' }),
         '/albums/{id}': { baseUrl: 'https://api.example.com' },
         '*': { baseUrl: 'https://api.example.com' }
       },
       tabs: [
-        { title: 'Home', url: '/' },
-        { title: 'Search', url: '/search' }
+        { title: 'Home', path: '/' },
+        { title: 'Search', path: '/search' }
       ]
     })
     expect(warnings).toEqual([])
@@ -96,14 +111,14 @@ describe('validateBrowserConfiguration', () => {
 
   it('does not flag a valid static page as unclassifiable', () => {
     validateBrowserConfiguration({
-      routes: { '/x': { url: '/x', title: 'X', children: [] } }
+      routes: { '/x': { path: '/x', title: 'X', children: [] } }
     })
     expect(warnings).toEqual([])
   })
 
   it('warns on more than 4 static tabs', () => {
     validateBrowserConfiguration({
-      tabs: [1, 2, 3, 4, 5].map((n) => ({ title: `Tab ${n}`, url: `/${n}` }))
+      tabs: [1, 2, 3, 4, 5].map((n) => ({ title: `Tab ${n}`, path: `/${n}` }))
     })
     expect(warnings.some((w) => w.includes('at most 4'))).toBe(true)
   })

package/src/features/browser-config.ts

@@ -38,9 +38,12 @@ function isTransformableRequestConfig(
   source: unknown
 ): source is TransformableRequestConfig {
   if (!isObjectValue(source)) return false
-  // Any RequestConfig key marks a request config. A static ResolvedTrack
-  // shares none of these at the top level (its per-track request override is
-  // nested under `request`).
+  // A static ResolvedTrack page also carries a top-level `path`, so `path`
+  // alone cannot mark a request config. A page is recognised by its required
+  // `title` — no RequestConfig field is named `title`.
+  if ('title' in source) return false
+  // Any RequestConfig key marks a request config. (A static ResolvedTrack's
+  // per-track request override is nested under `request`, not top-level.)
   return (
     'baseUrl' in source ||
     'path' in source ||
@@ -120,7 +123,7 @@ function searchSourceToRouteEntry(source: SearchSource): NativeRouteEntry {
  */
 function wrapTracksAsResolvedTrack(tracks: Track[]): ResolvedTrack {
   return {
-    url: TABS_ROUTE_PATH,
+    path: TABS_ROUTE_PATH,
     title: 'Tabs',
     children: tracks
   }
@@ -245,14 +248,14 @@ export function validateBrowserConfiguration(
         !isRouteConfig(source) &&
         !isTransformableRequestConfig(source)
       ) {
-        // Falls through to the static-page branch; a page needs url + title.
+        // Falls through to the static-page branch; a page needs path + title.
         const page = source as Partial<ResolvedTrack>
-        if (typeof page.url !== 'string' || typeof page.title !== 'string') {
+        if (typeof page.path !== 'string' || typeof page.title !== 'string') {
           warn(
             `route "${path}" matched no source shape — expected a callback, ` +
               `a request config ({ baseUrl, path, headers, ... }), a ` +
               `RouteConfig ({ browse, media, artwork }), or a static page ` +
-              `({ url, title, children? }). It will be served as static ` +
+              `({ path, title, children? }). It will be served as static ` +
               `content and likely render a blank screen.`
           )
         }
@@ -287,7 +290,7 @@ export function toNativeConfig(
     handleTrackLoad: config.handleTrackLoad,
     androidControllerOfflineError: config.androidControllerOfflineError,
     carPlayLoadingTitle: config.carPlayLoadingTitle,
-    resolveAlbumUrl: config.resolveAlbumUrl,
+    resolveAlbumPath: config.resolveAlbumPath,
     formatNavigationError: config.formatNavigationError
   }
 }

package/src/features/browser.test.ts

@@ -12,7 +12,7 @@ describe('getBrowserConfiguration', () => {
   })
 
   it('returns the last configuration in its public shape', () => {
-    const config = { tabs: [{ title: 'Home', url: '/' }] }
+    const config = { tabs: [{ title: 'Home', path: '/' }] }
     configureBrowser(config)
     expect(getBrowserConfiguration()).toBe(config)
   })

package/src/features/browser.ts

@@ -43,8 +43,8 @@ let currentConfiguration: BrowserConfiguration | undefined
  *     }
  *   },
  *   tabs: [
- *     { title: 'Home', url: '/' },
- *     { title: 'Search', url: '/search' }
+ *     { title: 'Home', path: '/' },
+ *     { title: 'Search', path: '/search' }
  *   ]
  * })
  * ```

package/src/features/favorites.ts

@@ -37,26 +37,29 @@ export function toggleActiveTrackFavorited(): void {
 }
 
 /**
- * Sets the list of favorited track source identifiers.
+ * Sets the list of favorited track identifiers.
  *
  * This syncs your app's favorites with the native favorites cache, enabling
  * the heart button in media controllers (notification, Android Auto, CarPlay)
  * to show the correct state.
  *
- * Note: This is only needed if the tracks provided to AudioBrowser do not
- * include the `favorited` field. If your API already includes favorite state in
- * track responses, the native favorites cache is populated automatically during browsing.
+ * Each identifier is 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 id-less tracks).
  *
- * When the heart button is tapped in media controllers or when you call
- * `setActiveTrackFavorited()`, the native favorites cache is automatically
- * updated. You only need to call this on app launch to hydrate the cache.
+ * A track whose response already carries `favorited` keeps that value on
+ * display surfaces — a caller-set flag wins over cache hydration. The cache
+ * itself is written only by this call and by heart toggles
+ * (`setActiveTrackFavorited()` / media-controller taps), so you only need to
+ * call this on app launch — and again whenever the collection changes outside
+ * the player (a sync from another device, say).
  *
- * @param favorites - Array of favorited track `src` values
+ * @param favorites - Array of favorited track identities (`id`, or `src` for id-less tracks)
  *
  * @example
  * ```ts
- * const favoriteSrcs = await loadFavoritesFromStorage()
- * setFavorites(favoriteSrcs)
+ * const favoriteIds = await loadFavoritesFromStorage()
+ * setFavorites(favoriteIds)
  * ```
  */
 export function setFavorites(favorites: string[]): void {

package/src/features/hook-wiring.test.ts

@@ -4,10 +4,12 @@ import { renderHook, act, cleanup } from '@testing-library/react'
 import { describe, it, expect, afterEach, vi } from 'vitest'
 
 /**
- * The 22 hooks that are a single delegation to `useNativeUpdatedValue`. Their
+ * The hooks that are a single delegation to `useNativeUpdatedValue`. Their
  * behaviour is covered once in `utils/useNativeUpdatedValue.test.ts`; what is
  * per-hook and untestable there is the wiring — which native callback slot the
  * emitter claims, and which `eventKey` is pulled out of the payload.
+ * (`useActiveTrack` and `useQueue` are getter-refreshed instead — they update
+ * on transitions AND favorite toggles — and are covered in their own block.)
  *
  * Both are easy to get wrong and silent when wrong: the hook simply never
  * updates, or yields the whole event where a field was meant. Five slots
@@ -159,13 +161,6 @@ const wirings: Wiring[] = [
     event: true,
     expected: true
   },
-  {
-    name: 'useQueue',
-    hook: useQueue,
-    slot: 'onPlaybackQueueChanged',
-    event: [{ src: 'a' }],
-    expected: [{ src: 'a' }]
-  },
   {
     name: 'useFormattedNavigationError',
     hook: useFormattedNavigationError,
@@ -210,13 +205,6 @@ const wirings: Wiring[] = [
     event: { repeatMode: 'queue' },
     expected: 'queue'
   },
-  {
-    name: 'useActiveTrack',
-    hook: useActiveTrack,
-    slot: 'onPlaybackActiveTrackChanged',
-    event: { track: { src: 'a' } },
-    expected: { src: 'a' }
-  },
   {
     name: 'useBatteryWarningPending',
     hook: useBatteryWarningPending,
@@ -252,3 +240,63 @@ describe('hook wiring table', () => {
     expect(new Set(wirings.map((w) => w.slot)).size).toBe(wirings.length)
   })
 })
+
+/**
+ * `useActiveTrack` and `useQueue` are getter-refreshed: a favorite toggle
+ * mutates the active track in place WITHOUT a transition event —
+ * transitions and mutations are separate events — so
+ * these hooks re-read their native getter on the transition slot AND on
+ * `onFavoriteChanged`.
+ */
+const { nativeBrowser } = await import('../native')
+
+describe.each([
+  {
+    name: 'useActiveTrack',
+    hook: useActiveTrack,
+    getter: 'getActiveTrack',
+    transitionSlot: 'onPlaybackActiveTrackChanged',
+    initial: { src: 'a', favorited: false },
+    mutated: { src: 'a', favorited: true }
+  },
+  {
+    name: 'useQueue',
+    hook: useQueue,
+    getter: 'getQueue',
+    transitionSlot: 'onPlaybackQueueChanged',
+    initial: [{ src: 'a', favorited: false }],
+    mutated: [{ src: 'a', favorited: true }]
+  }
+])(
+  '$name (getter-refreshed)',
+  ({ hook, getter, transitionSlot, initial, mutated }) => {
+    it(`re-reads ${getter} on ${transitionSlot} and onFavoriteChanged`, () => {
+      expect(slots.has(transitionSlot)).toBe(true)
+      expect(slots.has('onFavoriteChanged')).toBe(true)
+
+      const getterMock = (
+        nativeBrowser as unknown as Record<string, ReturnType<typeof vi.fn>>
+      )[getter]!
+
+      getterMock.mockReturnValue(initial)
+      const { result } = renderHook(() => hook())
+      expect(result.current).toEqual(initial)
+
+      // A transition re-reads the getter (the event payload is not consumed).
+      getterMock.mockReturnValue(mutated)
+      act(() => slots.get(transitionSlot)!({}))
+      expect(result.current).toEqual(mutated)
+
+      // A favorite toggle mutates in place — no transition event fires, but
+      // the hook must still refresh.
+      getterMock.mockReturnValue(initial)
+      act(() =>
+        slots.get('onFavoriteChanged')!({
+          track: { src: 'a' },
+          favorited: false
+        })
+      )
+      expect(result.current).toEqual(initial)
+    })
+  }
+)

package/src/features/playback/controls.ts

@@ -58,8 +58,10 @@ export function seekTo(position: number): void {
 }
 
 /**
- * Jump to the live edge of the current track. No-op for non-live tracks; for
- * live, seeks to the window end (HLS) or reconnects (non-seekable streams).
+ * Jump to the live edge of the current track; no-op unless the track
+ * declares `live: true`. A stream with a seekable live window (HLS) seeks
+ * to the window's edge; a non-seekable stream (e.g. ICY radio) reconnects
+ * to rejoin live — an expired URL re-resolves through `media.resolve`.
  */
 export function seekToLiveEdge(): void {
   nativeBrowser.seekToLiveEdge()

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

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
 }
 

package/src/features/player/options.ts

@@ -1,5 +1,7 @@
-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'
@@ -75,31 +77,22 @@ export interface PlayerCapabilities {
    *   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
@@ -295,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 {
@@ -391,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
 }
 
 /**
@@ -401,6 +408,7 @@ export interface NitroIOSUpdateOptions {
   playbackRates?: number[]
   carPlayUpNextButton?: boolean
   carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
+  carPlayPlayingIndicatorLocation?: CarPlayPlayingIndicatorLocation
 }
 
 /**

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

@@ -74,14 +74,23 @@ describe('setupPlayer wire regrouping', () => {
     })
   })
 
-  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 () => {

package/src/features/player/setup.ts

@@ -741,12 +741,14 @@ export async function setupPlayer(
     playbackRates,
     carPlayUpNextButton,
     carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation,
     ...iosSetup
   } = ios
   const iosUpdate = definedFields({
     playbackRates,
     carPlayUpNextButton,
-    carPlayNowPlayingButtons
+    carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation
   })
   validateIOSUpdateOptions(iosUpdate)
 

package/src/features/player/validateOptions.ts

@@ -7,6 +7,8 @@ const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
  * 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

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,6 +41,12 @@ 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 An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
@@ -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)
 }