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

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.`
           )
         }
@@ -286,8 +289,9 @@ export function toNativeConfig(
     singleTrack: config.singleTrack,
     handleTrackLoad: config.handleTrackLoad,
     androidControllerOfflineError: config.androidControllerOfflineError,
+    viewMoreTitle: config.viewMoreTitle,
     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' }
  *   ]
  * })
  * ```
@@ -157,8 +157,16 @@ export function hasSearch(): boolean {
 /**
  * Searches for tracks using the configured search source.
  *
+ * Resolves `[]` only when the source found nothing; a failed search rejects,
+ * so a caller can tell "no results" from "the request failed". The rejection's
+ * message describes the failure — native platforms reject with the underlying
+ * throwable and JS sees only its message. On web the `Error` also carries a
+ * `code`, the {@link NavigationErrorType} the browse path reports as a
+ * {@link NavigationError} (`'http-error'`, `'network-error'`).
+ *
  * @param query - The search query string
  * @returns Promise resolving to an array of matching tracks
+ * @throws When the search source or its request fails
  *
  * @see {@link configureBrowser}
  *
@@ -169,5 +177,5 @@ export function hasSearch(): boolean {
  * ```
  */
 export async function search(query: string): Promise<Track[]> {
-  return nativeBrowser.onSearch(query)
+  return nativeBrowser.search(query)
 }

package/src/features/carConnection.ts

@@ -19,7 +19,7 @@ export function isCarConnected(): boolean {
  * Subscribes to car connection changes (CarPlay on iOS, Android Auto /
  * Android Automotive on Android). Never fires on web.
  * @param callback - Called with the new connection state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onCarConnectedChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onCarConnectedChanged = cb)

package/src/features/equalizer.ts

@@ -46,7 +46,7 @@ export function setEqualizerLevels(levels: number[]): void {
 /**
  * Subscribes to equalizer settings changes (Android only).
  * @param callback - Called when equalizer settings change
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onEqualizerChanged =
   NativeUpdatedValue.emitterize<EqualizerSettings>(

package/src/features/errors.ts

@@ -134,7 +134,7 @@ export function getPlaybackError(): PlaybackError | undefined {
 /**
  * Subscribes to playback error events.
  * @param callback - Called when a playback error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackError =
   NativeUpdatedValue.emitterize<PlaybackErrorEvent>(
@@ -165,7 +165,7 @@ export function getNavigationError(): NavigationError | undefined {
 /**
  * Subscribes to navigation error events.
  * @param callback - Called when a navigation error occurs
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNavigationError =
   NativeUpdatedValue.emitterize<NavigationErrorEvent>(
@@ -198,7 +198,7 @@ export function getFormattedNavigationError():
 /**
  * Subscribes to formatted navigation error changes.
  * @param callback - Called when the formatted navigation error changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onFormattedNavigationError = NativeUpdatedValue.emitterize<
   FormattedNavigationError | undefined

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 {
@@ -82,7 +85,7 @@ export interface FavoriteChangedEvent {
  * The native side has already updated the track's favorite state and UI.
  *
  * @param callback - Called with the track and its new favorite state
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  *
  * @example
  * ```ts

package/src/features/gate.ts

@@ -120,12 +120,20 @@ nativeBrowser.resolveGate = async (
  * some surfaces (CarPlay) any gate change pops pushed navigation back to root,
  * so a page the user had drilled into is reset to the tab root. Set the gate
  * before the car connects and it'll be there the moment it does.
+ *
+ * @platform ios android
+ * A no-op on web, which has no CarPlay or Android Auto surfaces for the gate to
+ * cover. Nothing is lost: the gate never covered in-app browse UI on any
+ * platform — that stays yours to gate.
  */
 export function setGate(gate: Gate, resolve?: GateResolver): void
 /**
  * Raises the gate with a resolver only (no default chrome).
  * The resolver must return a {@link Gate} or `true` for gated requests;
  * native uses the built-in fallback chrome when `true` and no default is set.
+ *
+ * @platform ios android
+ * A no-op on web — the resolver is never consulted there.
  */
 export function setGate(resolve: GateResolver): void
 export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
@@ -140,6 +148,9 @@ export function setGate(a: Gate | GateResolver, b?: GateResolver): void {
 
 /**
  * Drops the gate — the real content comes back, and the current tab is kept.
+ *
+ * @platform ios android
+ * A no-op on web, where no gate was ever raised.
  */
 export function clearGate(): void {
   resolver = undefined
@@ -148,7 +159,11 @@ export function clearGate(): void {
 
 /**
  * Subscribes to gate events (fired when a request is gated).
- * @returns Cleanup function to unsubscribe.
+ *
+ * @platform ios android
+ * Never fires on web — there are no gated serves to report.
+ *
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onGate = LazyNativeEmitter.emitterize<GateEvent>(
   (cb) => (nativeBrowser.onGate = cb)

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

@@ -0,0 +1,302 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, afterEach, vi } from 'vitest'
+
+/**
+ * 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
+ * already differ in name from the emitter that claims them
+ * (`onPlaybackPlayWhenReadyChanged` behind `onPlayWhenReadyChanged`, and
+ * friends), so the names cannot be derived — they have to be pinned.
+ */
+const slots = vi.hoisted(() => new Map<string, (event: unknown) => void>())
+
+vi.mock('../native', () => ({
+  nativeBrowser: new Proxy({} as Record<string, unknown>, {
+    get(target, prop: string) {
+      // Getters are the pre-native fallback; undefined stands in for "native
+      // has not answered yet", which is what these tests start from.
+      target[prop] ??= vi.fn(() => undefined)
+      return target[prop]
+    },
+    set(target, prop: string, value) {
+      if (typeof value === 'function') slots.set(prop, value)
+      target[prop] = value
+      return true
+    }
+  })
+}))
+
+const { useBatteryOptimizationStatus, useBatteryWarningPending } =
+  await import('./battery')
+const { useContent, usePath, useTabs } = await import('./browser')
+const { useCarConnected } = await import('./carConnection')
+const { useEqualizerSettings } = await import('./equalizer')
+const { useFormattedNavigationError, useNavigationError, usePlaybackError } =
+  await import('./errors')
+const { useOnline } = await import('./network')
+const { useNowPlaying } = await import('./nowPlaying')
+const { useOutput } = await import('./output')
+const { useOptions } = await import('./player/options')
+const { usePlayingState } = await import('./playback/playing')
+const { usePlayWhenReady } = await import('./playback/playWhenReady')
+const { useProgress } = await import('./playback/progress')
+const { usePlayback } = await import('./playback/state')
+const { useSystemVolume } = await import('./playback/volume')
+const { useActiveTrack } = await import('./queue/activeTrack')
+const { useQueue } = await import('./queue/queue')
+const { useRepeatMode } = await import('./queue/repeatMode')
+const { useShuffle } = await import('./queue/shuffle')
+
+afterEach(cleanup)
+
+type Wiring = {
+  name: string
+  hook: () => unknown
+  /** The property on the Nitro object the emitter assigns its callback to. */
+  slot: string
+  event: unknown
+  /** What the hook returns — differs from `event` exactly when an eventKey applies. */
+  expected: unknown
+}
+
+const wirings: Wiring[] = [
+  // Payload passed through whole (no eventKey).
+  {
+    name: 'useOutput',
+    hook: useOutput,
+    slot: 'onOutputChanged',
+    event: { type: 'bluetooth' },
+    expected: { type: 'bluetooth' }
+  },
+  {
+    name: 'useNowPlaying',
+    hook: useNowPlaying,
+    slot: 'onNowPlayingChanged',
+    event: { title: 'Song' },
+    expected: { title: 'Song' }
+  },
+  {
+    name: 'useOnline',
+    hook: useOnline,
+    slot: 'onOnlineChanged',
+    event: true,
+    expected: true
+  },
+  {
+    name: 'useCarConnected',
+    hook: useCarConnected,
+    slot: 'onCarConnectedChanged',
+    event: true,
+    expected: true
+  },
+  {
+    name: 'useEqualizerSettings',
+    hook: useEqualizerSettings,
+    slot: 'onEqualizerChanged',
+    event: { enabled: true },
+    expected: { enabled: true }
+  },
+  {
+    name: 'usePath',
+    hook: usePath,
+    slot: 'onPathChanged',
+    event: '/artists/1',
+    expected: '/artists/1'
+  },
+  {
+    name: 'useContent',
+    hook: useContent,
+    slot: 'onContentChanged',
+    event: { src: 'a' },
+    expected: { src: 'a' }
+  },
+  {
+    name: 'useTabs',
+    hook: useTabs,
+    slot: 'onTabsChanged',
+    event: [{ src: 'a' }],
+    expected: [{ src: 'a' }]
+  },
+  {
+    name: 'usePlayback',
+    hook: usePlayback,
+    slot: 'onPlaybackChanged',
+    event: { state: 'playing' },
+    expected: { state: 'playing' }
+  },
+  {
+    name: 'useSystemVolume',
+    hook: useSystemVolume,
+    slot: 'onSystemVolumeChanged',
+    event: 0.4,
+    expected: 0.4
+  },
+  {
+    name: 'useProgress',
+    hook: useProgress,
+    slot: 'onPlaybackProgressUpdated',
+    event: { position: 1, duration: 2, buffered: 3 },
+    expected: { position: 1, duration: 2, buffered: 3 }
+  },
+  {
+    name: 'usePlayingState',
+    hook: usePlayingState,
+    slot: 'onPlaybackPlayingState',
+    event: { state: 'ready' },
+    expected: { state: 'ready' }
+  },
+  {
+    name: 'useShuffle',
+    hook: useShuffle,
+    slot: 'onPlaybackShuffleModeChanged',
+    event: true,
+    expected: true
+  },
+  {
+    name: 'useFormattedNavigationError',
+    hook: useFormattedNavigationError,
+    slot: 'onFormattedNavigationError',
+    event: { title: 'Offline' },
+    expected: { title: 'Offline' }
+  },
+  {
+    name: 'useOptions',
+    hook: useOptions,
+    slot: 'onOptionsChanged',
+    event: { playbackSpeed: 1.5 },
+    expected: { playbackSpeed: 1.5 }
+  },
+
+  // A field lifted out of the payload — the eventKey cases.
+  {
+    name: 'usePlaybackError',
+    hook: usePlaybackError,
+    slot: 'onPlaybackError',
+    event: { error: { code: 'network' } },
+    expected: { code: 'network' }
+  },
+  {
+    name: 'useNavigationError',
+    hook: useNavigationError,
+    slot: 'onNavigationError',
+    event: { error: { code: 'notFound' } },
+    expected: { code: 'notFound' }
+  },
+  {
+    name: 'usePlayWhenReady',
+    hook: usePlayWhenReady,
+    slot: 'onPlaybackPlayWhenReadyChanged',
+    event: { playWhenReady: true },
+    expected: true
+  },
+  {
+    name: 'useRepeatMode',
+    hook: useRepeatMode,
+    slot: 'onPlaybackRepeatModeChanged',
+    event: { repeatMode: 'queue' },
+    expected: 'queue'
+  },
+  {
+    name: 'useBatteryWarningPending',
+    hook: useBatteryWarningPending,
+    slot: 'onBatteryWarningPendingChanged',
+    event: { pending: true },
+    expected: true
+  },
+  {
+    name: 'useBatteryOptimizationStatus',
+    hook: useBatteryOptimizationStatus,
+    slot: 'onBatteryOptimizationStatusChanged',
+    event: { status: 'unrestricted' },
+    expected: 'unrestricted'
+  }
+]
+
+describe.each(wirings)('$name', ({ hook, slot, event, expected }) => {
+  it(`reads $slot`, () => {
+    // A slot nothing claimed means the emitter assigns a different property
+    // than the one named here — the hook would never update in production.
+    expect(slots.has(slot)).toBe(true)
+
+    const { result } = renderHook(() => hook())
+    act(() => slots.get(slot)!(event))
+    expect(result.current).toEqual(expected)
+  })
+})
+
+describe('hook wiring table', () => {
+  it('covers every delegating hook exactly once', () => {
+    const names = wirings.map((w) => w.name)
+    expect(new Set(names).size).toBe(names.length)
+    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/metadata.ts

@@ -98,8 +98,13 @@ export interface ChapterMetadata {
 
 /**
  * Subscribes to chapter metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read chapter markers. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when chapter metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onChapterMetadata = NativeUpdatedValue.emitterize<
   ChapterMetadata[]
@@ -107,8 +112,13 @@ export const onChapterMetadata = NativeUpdatedValue.emitterize<
 
 /**
  * Subscribes to track metadata events.
+ *
+ * @platform ios android
+ * Never fires on web — the web player does not read embedded file tags. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when static track metadata is received
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
   (cb) => (nativeBrowser.onTrackMetadata = cb)
@@ -116,8 +126,15 @@ export const onTrackMetadata = NativeUpdatedValue.emitterize<TrackMetadata>(
 
 /**
  * Subscribes to timed metadata events (ICY/ID3 from live streams).
+ *
+ * @platform ios android
+ * Never fires on web. ICY metadata is stripped by the browser before the player
+ * can see it, and no browser API exposes it; in-band ID3 from HLS is reachable
+ * but not yet wired. See
+ * {@link https://github.com/radio-garden/react-native-audio-browser/issues/118 | #118}.
+ *
  * @param callback - Called when stream metadata is received (title, artist from ICY/ID3 tags)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onTimedMetadata = NativeUpdatedValue.emitterize<TimedMetadata>(
   (cb) => (nativeBrowser.onTimedMetadata = cb)

package/src/features/network.ts

@@ -17,7 +17,7 @@ export function getOnline(): boolean {
 /**
  * Subscribes to network connectivity changes.
  * @param callback - Called when network state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOnlineChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onOnlineChanged = cb)

package/src/features/nowPlaying.ts

@@ -74,7 +74,7 @@ export function clearNowPlayingFlash(): void {
  * Subscribes to now playing metadata change events.
  * Fires when updateNowPlaying is called or when the track changes.
  * @param callback - Called when now playing metadata changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onNowPlayingChanged =
   NativeUpdatedValue.emitterize<NowPlayingMetadata>(