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

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

@@ -0,0 +1,254 @@
+/** @vitest-environment happy-dom */
+
+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
+ * 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.
+ *
+ * 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: 'useQueue',
+    hook: useQueue,
+    slot: 'onPlaybackQueueChanged',
+    event: [{ src: 'a' }],
+    expected: [{ src: 'a' }]
+  },
+  {
+    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: 'useActiveTrack',
+    hook: useActiveTrack,
+    slot: 'onPlaybackActiveTrackChanged',
+    event: { track: { src: 'a' } },
+    expected: { src: 'a' }
+  },
+  {
+    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)
+  })
+})

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>(

package/src/features/output.ts

@@ -46,7 +46,7 @@ export function getOutput(): Output | undefined {
 /**
  * Subscribes to current-output changes (headphones unplugged, Bluetooth speaker
  * connected, AirPlay/route selected). Fires on iOS and Android 11+; never below.
- * @returns Cleanup function to unsubscribe.
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onOutputChanged = NativeUpdatedValue.emitterize<Output>(
   (cb) => (nativeBrowser.onOutputChanged = cb)

package/src/features/playback/playWhenReady.ts

@@ -35,7 +35,7 @@ export function setPlayWhenReady(playWhenReady: boolean): void {
 /**
  * Subscribes to play when ready changes.
  * @param callback - Called when playWhenReady changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayWhenReadyChanged =
   NativeUpdatedValue.emitterize<PlaybackPlayWhenReadyChangedEvent>(

package/src/features/playback/playing.ts

@@ -23,7 +23,7 @@ export function getPlayingState(): PlayingState {
 /**
  * Subscribes to playing state changes.
  * @param callback - Called when playing or buffering state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlayingState = NativeUpdatedValue.emitterize<PlayingState>(
   (cb) => (nativeBrowser.onPlaybackPlayingState = cb)

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

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

package/src/features/playback/progress.ts

@@ -46,7 +46,7 @@ export function getProgress(): Progress {
 /**
  * Subscribes to playback progress updates.
  * @param callback - Called periodically with playback progress updates
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onProgressUpdated =
   NativeUpdatedValue.emitterize<PlaybackProgressUpdatedEvent>(

package/src/features/playback/state.ts

@@ -55,7 +55,7 @@ export function getPlayback(): Playback {
 /**
  * Subscribes to playback state changes.
  * @param callback - Called when the playback state changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onPlaybackChanged = NativeUpdatedValue.emitterize<Playback>(
   (cb) => (nativeBrowser.onPlaybackChanged = cb)

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

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

package/src/features/playback/trackPlaybackTime.ts

@@ -99,8 +99,3 @@ export function trackPlaybackTime(
     if (handles.size === 0) nativeBrowser.setPlaybackIntervalEnabled(false)
   }
 }
-
-/** @internal test hook — drives the fan-out without a native tick. */
-export function __emitTickForTests(ticks = 1) {
-  for (let i = 0; i < ticks; i++) onTick()
-}

package/src/features/playback/volume.ts

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