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

package/src/types/browser.ts

@@ -15,9 +15,10 @@ export interface TrackLoadEvent {
 
 /**
  * Callback for handling track load events.
- * When set on BrowserConfiguration, navigateTrack() will call this handler
- * instead of auto-loading/playing the track. The native side awaits completion
- * before proceeding (e.g., showing Now Playing in CarPlay).
+ * When set on BrowserConfiguration, loading a playable track — a browse-row
+ * tap or a `navigate(track)` call — invokes this handler instead of the
+ * library auto-loading/playing it. The native side awaits the returned
+ * promise before proceeding (e.g., showing Now Playing in CarPlay).
  */
 export type HandleTrackLoadCallback = (event: TrackLoadEvent) => Promise<void>
 
@@ -187,7 +188,7 @@ export interface RequestConfig {
   method?: HttpMethod
   /**
    * The request path.
-   * - For browser requests, this is the track's `url`
+   * - For browser requests, this is the track's `path`
    * - For media requests, this is the track's `src` value
    * - For artwork requests, this is the track's `artwork` URL
    */
@@ -351,7 +352,7 @@ export type RequestConfigResolver = () =>
 /**
  * Configuration for artwork image requests
  *
- * ## Configuration Hierarchy
+ * ### Configuration Hierarchy
  *
  * When a request is made, configs are merged in this order (later overrides earlier):
  * 1. `request` (base config) - shared settings like user agent, common headers
@@ -360,7 +361,7 @@ export type RequestConfigResolver = () =>
  * 4. `imageQueryParams` - automatic size query param injection (if configured)
  * 5. `transform(request, context)` result - final modifications (if provided)
  *
- * ## Usage Patterns
+ * ### Usage Patterns
  *
  * **Simple CDN configuration:**
  * ```typescript
@@ -426,7 +427,7 @@ export interface ImageQueryParams {
  * Used for both `media` (audio streaming) and `artwork` (image loading) configuration
  * in BrowserConfiguration.
  *
- * ## Configuration Hierarchy
+ * ### Configuration Hierarchy
  *
  * When a request is made, configs are merged in this order (later overrides earlier):
  * 1. `request` (base config) - shared settings like user agent, common headers
@@ -434,7 +435,7 @@ export interface ImageQueryParams {
  * 3. `resolve(track)` result - per-track overrides (if provided)
  * 4. `transform(request)` result - final modifications (if provided)
  *
- * ## Usage Patterns
+ * ### Usage Patterns
  *
  * **Simple CDN configuration:**
  * ```typescript
@@ -590,9 +591,9 @@ export interface ArtworkRequestConfig extends RequestConfig {
  *
  * **Response shape (HTTP / `TransformableRequestConfig`):** the endpoint must
  * return a single **page object** — a {@link ResolvedTrack}
- * (`{ title, url?, children: Track[] }`). The `children` array holds the rows
+ * (`{ title, path?, children: Track[] }`). The `children` array holds the rows
  * shown for the container; each child is a playable leaf (`src`) or a navigable
- * sub-container (`url`). A callback / static `ResolvedTrack` returns the same
+ * sub-container (`path`). A callback / static `ResolvedTrack` returns the same
  * page object directly.
  *
  * {@link SearchSource} and {@link TabsSource} HTTP endpoints return this same
@@ -656,43 +657,10 @@ export type TabsSource =
  */
 export type SearchSource = SearchSourceCallback | TransformableRequestConfig
 
-/**
- * How ids passed to `setFavorites` are matched against a
- * track's `src` to hydrate its `favorited` flag.
- *
- * - `'exact'`: the id must equal `src`.
- * - `'partial'`: the id matches if it appears as a complete path segment within
- *   `src` (delimited by `/`, `?`, `#`, or the string boundaries). Useful when
- *   favorites are stored as a stable identifier that is embedded in — but not
- *   equal to — the playable `src` URL.
- *
- * @example
- * ```text
- * setFavorites(['abc123'])  +  track.src = '/stream/jazz-fm/abc123'
- *
- *   'exact'    'abc123' === '/stream/jazz-fm/abc123'   → not favorited
- *   'partial'  'abc123' is the last segment of the src → favorited
- *
- * setFavorites(['https://cdn.example.com/jazz-fm/abc123.mp3'])
- *
- *   'exact'    id === src                              → favorited
- *   'partial'  id is a full segment of src             → favorited
- * ```
- */
-export type FavoritesMatchMode = 'exact' | 'partial'
-
-/**
- * Object form of the `favorite` capability — enables favoriting with an explicit
- * {@link FavoritesMatchMode}. (A bare `true` is shorthand for `{ match: 'exact' }`.)
- */
-export interface FavoriteConfig {
-  match: FavoritesMatchMode
-}
-
 export type BrowserConfiguration = {
   /**
    * Initial navigation path. Setting this triggers initial navigation to the
-   * specified path. When unset, the first tab's URL is used; when there are
+   * specified path. When unset, the first tab's path is used; when there are
    * no tabs either, `/`.
    */
   path?: string | undefined
@@ -874,19 +842,19 @@ export type BrowserConfiguration = {
 
   /**
    * Configuration for navigation tabs in the media browser.
-   * The first tab's URL is automatically loaded when the browser starts.
+   * The first tab's path is automatically loaded when the browser starts.
    *
    * Optional - if not provided, no tab navigation will be available.
    * Limited to maximum 4 tabs for automotive platform compatibility (Android Auto/CarPlay).
    *
-   * Can provide static array of Track objects with urls as tabs, API configuration, or custom callback.
+   * Can provide static array of Track objects with paths as tabs, API configuration, or custom callback.
    */
   tabs?: TabsSource
 
   /**
-   * Route-specific configurations. Maps URL path patterns to browse sources.
+   * Route-specific configurations. Maps path patterns to browse sources.
    *
-   * ## Matching
+   * ### Matching
    *
    * Patterns match on **exact segment count** — `/artists` does NOT match
    * `/artists/123`. Segments may be:
@@ -900,7 +868,7 @@ export type BrowserConfiguration = {
    * When several patterns match, the most specific wins
    * (constants > parameters > wildcards > tail wildcard).
    *
-   * ## Defaults and reserved keys
+   * ### Defaults and reserved keys
    *
    * A path matching no route is fetched over HTTP via the `request` →
    * `browse` layers with the path applied — most APIs only need explicit
@@ -983,22 +951,22 @@ export type BrowserConfiguration = {
 
   /**
    * Called when the album line on the CarPlay Now Playing screen is tapped
-   * and the active track has no {@link Track.albumUrl}. Return a browse path
+   * and the active track has no {@link Track.albumPath}. Return a browse path
    * to navigate the CarPlay browse stack there, or `undefined` if the tap was
    * handled (or should do nothing).
    *
-   * The album line is tappable whenever the active track has an `albumUrl`
+   * The album line is tappable whenever the active track has an `albumPath`
    * or this callback is configured.
    *
    * @example
    * ```typescript
-   * resolveAlbumUrl: (track) =>
+   * resolveAlbumPath: (track) =>
    *   track.album ? `/album/${slugify(track.album)}` : undefined
    * ```
    *
    * @platform ios
    */
-  resolveAlbumUrl?: ResolveAlbumUrlCallback
+  resolveAlbumPath?: ResolveAlbumPathCallback
 
   /**
    * Callback to customize error messages for navigation errors.
@@ -1038,6 +1006,17 @@ export type CarPlayNowPlayingButton =
   | 'favorite'
   | 'playback-rate'
 
+/**
+ * Where the now-playing indicator draws on a CarPlay list row.
+ *
+ * - `'leading'`: in the artwork slot, replacing the row's artwork while it
+ *   plays (the system default, as Apple Music does)
+ * - `'trailing'`: at the end of the row, keeping the artwork visible
+ *
+ * @platform ios
+ */
+export type CarPlayPlayingIndicatorLocation = 'leading' | 'trailing'
+
 /**
  * Position of the "Ask Siri to Play Audio" assistant cell on a CarPlay list template.
  *
@@ -1111,6 +1090,6 @@ export type FormatNavigationErrorCallback = (
 
 /**
  * Maps the tapped active track to a browse path for the CarPlay album line,
- * or `undefined` to do nothing. See `resolveAlbumUrl`.
+ * or `undefined` to do nothing. See `resolveAlbumPath`.
  */
-export type ResolveAlbumUrlCallback = (track: Track) => string | undefined
+export type ResolveAlbumPathCallback = (track: Track) => string | undefined

package/src/utils/LazyNativeEmitter.ts

@@ -1,28 +1,31 @@
 type Callback<T> = (arg: T) => void
 
 /**
- * A lightweight event emitter that lazily bridges native callbacks to multiple JavaScript listeners.
+ * The subscription object behind the library's **discrete** events — the
+ * remote-control exports (`onRemotePlay`, `onRemoteSeek`, …) and other
+ * one-shot signals with no "current value" to cache. Subscribe with
+ * {@link addListener}; the returned function unsubscribes. The emitter is
+ * not callable itself.
  *
- * The native callback is only assigned when the first listener is added, making the emitter
- * creation lightweight with no side effects until actually used.
- *
- * Use this for optional/rare events like remote controls where most apps won't need to listen.
- * For critical state changes (playback, progress, etc.), use NativeEmitter instead to ensure
- * no events are missed.
+ * "Lazy" is an implementation detail you may notice in timing: the native
+ * side only starts delivering the event once the first listener is added.
+ * State that always has a current reading uses `NativeUpdatedValue`
+ * instead.
  *
  * @example
  * ```typescript
- * export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
- *   (cb) => (nativeBrowser.onRemotePlay = cb)
- * )
+ * import { onRemotePlay } from 'react-native-audio-browser'
  *
  * const unsubscribe = onRemotePlay.addListener(() => console.log('play'))
+ * // later:
+ * unsubscribe()
  * ```
  */
 export class LazyNativeEmitter<T> {
   private setter: (callback: (data: T) => void) => void
   private listeners: Set<(arg: T) => void> | undefined
 
+  /** @internal */
   constructor(setter: (callback: (data: T) => void) => void) {
     this.setter = setter
   }
@@ -38,6 +41,12 @@ export class LazyNativeEmitter<T> {
     return listeners
   }
 
+  /**
+   * Subscribes to the event.
+   *
+   * @param callback - Invoked with each event
+   * @returns A function that removes the listener
+   */
   addListener(callback: Callback<T>): () => void {
     const listeners = this.getListeners()
     listeners.add(callback)
@@ -50,6 +59,7 @@ export class LazyNativeEmitter<T> {
    * @param setter - Function that sets the native callback property
    * @returns The emitter instance — subscribe with `addListener`, which returns
    * an unsubscribe function
+   * @internal
    */
   static emitterize<T>(
     setter: (callback: (data: T) => void) => void

package/src/utils/NativeUpdatedValue.ts

@@ -1,30 +1,39 @@
 type Callback<T> = (arg: T) => void
 
 /**
- * Bridges native value changes to JavaScript, storing the latest value for immediate access.
+ * The subscription object behind the library's **state** events — every
+ * `on<Thing>Changed`-style export (`onPlaybackChanged`, `onQueueChanged`, …)
+ * is one of these. Subscribe with {@link addListener}; the returned function
+ * unsubscribes. The emitter is not callable itself.
  *
- * Subscribes to native changes immediately at module load to ensure no updates are missed.
- * The `lastValue` property caches the most recent value, allowing hooks to read the current
- * state synchronously without calling a separate getter function.
- *
- * Use this for state-based values that have a "current value" (playback state, options, progress).
- * For discrete events without a current value (remote controls), use LazyNativeEmitter instead.
+ * It tracks a value that always has a *current* reading (playback state,
+ * progress, options): {@link lastValue} caches the most recent one so hooks —
+ * and you — can read it synchronously without a getter round-trip. Discrete
+ * events with no current value (remote-control presses) use
+ * `LazyNativeEmitter` instead.
  *
  * @example
  * ```typescript
- * export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
- *   (cb) => (nativeBrowser.onPlaybackChanged = cb)
- * )
+ * import { onPlaybackChanged } from 'react-native-audio-browser'
  *
- * export function usePlayback(): Playback {
- *   return useUpdatedNativeValue(getPlayback, onPlaybackChanged)
- * }
+ * const unsubscribe = onPlaybackChanged.addListener((p) => {
+ *   console.log(p.state)
+ * })
+ * // later:
+ * unsubscribe()
  * ```
  */
 export class NativeUpdatedValue<T> {
   private listeners = new Set<Callback<T>>()
+
+  /**
+   * The most recent value delivered by native, or `undefined` before the
+   * first update. Subscription starts at module load, so this is safe to
+   * read synchronously at any time.
+   */
   lastValue: T | undefined = undefined
 
+  /** @internal */
   constructor(setter: (callback: (data: T) => void) => void) {
     // Install native callback immediately at module load
     setter((data: T) => {
@@ -35,6 +44,12 @@ export class NativeUpdatedValue<T> {
     })
   }
 
+  /**
+   * Subscribes to value changes.
+   *
+   * @param callback - Invoked with each new value
+   * @returns A function that removes the listener
+   */
   addListener(callback: Callback<T>): () => void {
     this.listeners.add(callback)
     return () => this.listeners.delete(callback)
@@ -45,6 +60,7 @@ export class NativeUpdatedValue<T> {
    *
    * @param setter - Function that sets the native callback property
    * @returns The subscription instance with lastValue and addListener
+   * @internal
    */
   static emitterize<T>(
     setter: (callback: (data: T) => void) => void

package/src/utils/getTrackIdentity.ts

@@ -0,0 +1,20 @@
+/**
+ * A track's identity: its opaque `id` when present (non-blank), falling back
+ * to the playable `src`. Two tracks refer to the same item exactly when their
+ * identities are equal. Browsable-only tracks (neither `id` nor `src`) have
+ * no identity — they are addressed by their `path` instead.
+ *
+ * This is the same comparison the library uses everywhere it matches tracks:
+ * favorites (`setFavorites`), the CarPlay / Android Auto "now playing" row
+ * indicator, and queue expansion and in-place skipping when a track is
+ * selected from browse content. Use it for your own bookkeeping — keying a
+ * favorites collection, deduplicating history — so your comparisons agree
+ * with the library's.
+ */
+// Decision record: ADR 0008 (docs/adr/).
+export function getTrackIdentity(track: {
+  id?: string
+  src?: string
+}): string | undefined {
+  return track.id?.length ? track.id : track.src
+}

package/src/utils/useNativeValueRefreshedBy.ts

@@ -0,0 +1,38 @@
+import { useEffect, useState } from 'react'
+
+type Subscribable = {
+  addListener(callback: (event: unknown) => void): () => void
+}
+
+/**
+ * Hook for a native-fetched value that must stay fresh across SEVERAL event
+ * sources — e.g. the active track, which changes on a queue transition
+ * (`onActiveTrackChanged`) but is also mutated in place by a favorite toggle
+ * (`onFavoriteChanged`).
+ *
+ * Unlike {@link useNativeUpdatedValue}, this never reads a cached event
+ * payload: every trigger re-reads `getter()`, and the mount effect re-reads
+ * once after the subscriptions attach (so an event firing between render and
+ * effect cannot be missed). The getters are cheap synchronous Nitro calls.
+ *
+ * @param getter - Synchronous native getter for the current value
+ * @param emitters - Event sources that invalidate the value (a stable,
+ *   module-level array — identity changes resubscribe)
+ */
+export function useNativeValueRefreshedBy<T>(
+  getter: () => T,
+  emitters: readonly Subscribable[]
+): T {
+  const [value, setValue] = useState(getter)
+
+  useEffect(() => {
+    setValue(getter())
+    const cleanups = emitters.map((emitter) =>
+      emitter.addListener(() => setValue(getter()))
+    )
+    return () => cleanups.forEach((cleanup) => cleanup())
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [getter, ...emitters])
+
+  return value
+}

package/src/web/NativeAudioBrowser.ts

@@ -44,6 +44,7 @@ import type {
 } from '../specs/audio-browser.nitro'
 import type { ResolvedTrack, Track, TrackLoadEvent } from '../types'
 import type { NativeBrowserConfiguration } from '../types/browser-native'
+import { getTrackIdentity } from '../utils/getTrackIdentity'
 import { BrowserManager } from './browser/BrowserManager'
 import { classifyTrackNavigation } from './browser/classifyTrackNavigation'
 import { FavoriteManager } from './browser/FavoriteManager'
@@ -57,6 +58,7 @@ import { RemoteCommandController } from './player/RemoteCommandController'
 import { QueuePlayer, SleepTimerManager, VolumeFader } from './TrackPlayer'
 import { PlaybackTimer } from './TrackPlayer/PlaybackTimer'
 import { derivePlayingState } from './TrackPlayer/PlayingStateFactory'
+import { BrowserPathHelper } from './util/BrowserPathHelper'
 
 /**
  * Web implementation of AudioBrowser (unified browser + player)
@@ -414,11 +416,13 @@ export class NativeAudioBrowser
    * Attempts to skip to a track already in the current queue.
    * Used as an optimization to avoid re-expanding the queue.
    *
-   * @param trackId The track's src identifier
+   * @param track The tapped track (its contextual path pins the exact copy)
+   * @param trackId The track's identity (id, falling back to src)
    * @param parentPath The parent path to check against queueSourcePath
    * @returns true if successfully skipped to existing track, false otherwise
    */
   private async trySkipToExistingQueueTrack(
+    track: Track,
     trackId: string,
     parentPath: string
   ): Promise<boolean> {
@@ -426,8 +430,21 @@ export class NativeAudioBrowser
       return false
     }
 
+    // Exact-surface match first: a contextual path carries the tapped page
+    // position (__index), so path equality pins the exact copy when the page
+    // holds the same identity more than once. The identity match remains for
+    // index-less paths (e.g. pre-stamp persisted state); an index-stamped path
+    // with no exact match falls through to expansion, which re-scopes the
+    // queue to the tapped section.
     const queue = this.getQueue()
-    const index = queue.findIndex((t) => t.src === trackId)
+    let index = queue.findIndex((t) => t.path != null && t.path === track.path)
+    if (
+      index < 0 &&
+      track.path != null &&
+      BrowserPathHelper.extractIndex(track.path) === undefined
+    ) {
+      index = queue.findIndex((t) => getTrackIdentity(t) === trackId)
+    }
 
     if (index < 0) {
       return false
@@ -474,6 +491,11 @@ export class NativeAudioBrowser
    */
   private async navigateTrackAsync(track: Track): Promise<void> {
     try {
+      // A disabled track is unavailable — it never plays, whichever surface
+      // or stale resume path delivered the selection (Track.disabled; mirrors
+      // iOS TrackSelector.select and Android navigateTrack).
+      if (track.disabled === true) return
+
       const nav = classifyTrackNavigation(track)
       switch (nav.kind) {
         case 'contextual':
@@ -481,6 +503,7 @@ export class NativeAudioBrowser
           if (
             nav.trackId &&
             (await this.trySkipToExistingQueueTrack(
+              track,
               nav.trackId,
               nav.parentPath
             ))
@@ -504,7 +527,7 @@ export class NativeAudioBrowser
           return
 
         case 'invalid':
-          throw new Error("Track must have either 'url' or 'src' property")
+          throw new Error("Track must have either 'path' or 'src' property")
       }
     } catch (error) {
       const message = error instanceof Error ? error.message : 'Unknown error'
@@ -941,13 +964,14 @@ export class NativeAudioBrowser
   setActiveTrackFavorited(favorited: boolean): void {
     const track = this.getActiveTrack()
     const index = this.getActiveTrackIndex()
-    if (!track || !track.src || index === undefined) return
+    if (!track || getTrackIdentity(track) === undefined || index === undefined)
+      return
 
-    // Update favorites set via manager
+    // Update favorites set via manager (keyed by track identity)
     if (favorited) {
-      this.favoriteManager.addFavorite(track.src)
+      this.favoriteManager.addFavorite(track)
     } else {
-      this.favoriteManager.removeFavorite(track.src)
+      this.favoriteManager.removeFavorite(track)
     }
 
     // Create updated track with new favorited state
@@ -959,27 +983,18 @@ export class NativeAudioBrowser
     // Replace the track in the queue
     this.queue.replaceTrack(index, updatedTrack)
 
-    // Emit favorite changed event
+    // Emit favorite changed only. A favorite toggle is an in-place mutation of
+    // the active track, not a transition — onPlaybackActiveTrackChanged and
+    // onPlaybackQueueChanged stay transition-only, and the useActiveTrack /
+    // useQueue hooks subscribe to onFavoriteChanged themselves.
     this.onFavoriteChanged({ track: updatedTrack, favorited })
-
-    // Emit active track changed so useActiveTrack() hook updates
-    this.onPlaybackActiveTrackChanged({
-      lastIndex: index,
-      lastTrack: track,
-      lastPosition: this.element?.currentTime ?? 0,
-      index,
-      track: updatedTrack
-    })
-
-    // Emit queue changed so useQueue() hook updates
-    this.emitQueueChanged()
   }
 
   toggleActiveTrackFavorited(): void {
     const track = this.getActiveTrack()
-    if (!track || !track.src) return
+    if (!track || getTrackIdentity(track) === undefined) return
 
-    const isFavorited = this.favoriteManager.isFavorited(track.src)
+    const isFavorited = this.favoriteManager.isFavorited(track)
     this.setActiveTrackFavorited(!isFavorited)
   }