react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/src/utils/LazyNativeEmitter.ts

@@ -1,8 +1,6 @@
-/** @internal */
 type Callback<T> = (arg: T) => void
 
 /**
- * @internal
  * A lightweight event emitter that lazily bridges native callbacks to multiple JavaScript listeners.
  *
  * The native callback is only assigned when the first listener is added, making the emitter
@@ -14,9 +12,11 @@ type Callback<T> = (arg: T) => void
  *
  * @example
  * ```typescript
- * export const onRemotePlay = LazyEmitter.emitterize<void>(
+ * export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
  *   (cb) => (nativeBrowser.onRemotePlay = cb)
  * )
+ *
+ * const unsubscribe = onRemotePlay.addListener(() => console.log('play'))
  * ```
  */
 export class LazyNativeEmitter<T> {
@@ -45,14 +45,15 @@ export class LazyNativeEmitter<T> {
   }
 
   /**
-   * Creates a lazy emitter subscription function for a native callback.
+   * Creates a lazy emitter for a native callback.
+   *
    * @param setter - Function that sets the native callback property
-   * @returns A subscription function that returns an unsubscribe function
+   * @returns The emitter instance — subscribe with `addListener`, which returns
+   * an unsubscribe function
    */
   static emitterize<T>(
     setter: (callback: (data: T) => void) => void
-  ): (callback: Callback<T>) => () => void {
-    const emitter = new LazyNativeEmitter(setter)
-    return (callback: Callback<T>) => emitter.addListener(callback)
+  ): LazyNativeEmitter<T> {
+    return new LazyNativeEmitter(setter)
   }
 }

package/src/utils/NativeUpdatedValue.ts

@@ -1,8 +1,6 @@
-/** @internal */
 type Callback<T> = (arg: T) => void
 
 /**
- * @internal
  * Bridges native value changes to JavaScript, storing the latest value for immediate access.
  *
  * Subscribes to native changes immediately at module load to ensure no updates are missed.

package/src/utils/artwork.ts

@@ -0,0 +1,30 @@
+import type { ArtworkVariants, TrackArtwork } from '../types/browser-nodes'
+
+/**
+ * Whether a track's artwork ships one image per appearance.
+ *
+ * Narrows the union in one place, so nothing else has to know how it is
+ * discriminated.
+ */
+export function isArtworkVariants(
+  artwork: TrackArtwork | undefined
+): artwork is ArtworkVariants {
+  return typeof artwork === 'object' && artwork !== null
+}
+
+/**
+ * The single artwork URL to use.
+ *
+ * Mirrors the Swift `Variant_String_ArtworkVariants.url` accessor: a pair
+ * resolves to its dark URL unless a scheme is given, because dark is what a
+ * single-URL track would have shipped and is the only appearance Android Auto
+ * has. Callers that can render per appearance (CarPlay, via a `UIImageAsset`)
+ * take the pair itself rather than going through this.
+ */
+export function artworkUrl(
+  artwork: TrackArtwork | undefined,
+  scheme: 'light' | 'dark' = 'dark'
+): string | undefined {
+  if (artwork === undefined) return undefined
+  return isArtworkVariants(artwork) ? artwork[scheme] : artwork
+}

package/src/utils/useDebug.test.ts

@@ -0,0 +1,182 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+
+const native = vi.hoisted(() => {
+  const slots = new Map<string, (event: never) => void>()
+  return {
+    slots,
+    browser: new Proxy({} as Record<string, unknown>, {
+      get(target, prop: string) {
+        // Defaults have to be shaped, not undefined: useDebugState reads
+        // `playback.state`, `queue.map(...)` and `progress.position` directly.
+        target[prop] ??= vi.fn(() => defaults[prop])
+        return target[prop]
+      },
+      set(target, prop: string, value) {
+        if (typeof value === 'function') slots.set(prop, value)
+        target[prop] = value
+        return true
+      }
+    })
+  }
+})
+
+const defaults: Record<string, unknown> = {
+  getPlayback: { state: 'none' },
+  getQueue: [],
+  getProgress: { position: 0, duration: 0, buffered: 0 },
+  getOptions: {},
+  getPlayWhenReady: false,
+  getShuffle: false,
+  getRepeatMode: 'off',
+  getOnline: true
+}
+
+vi.mock('../native', () => ({ nativeBrowser: native.browser }))
+
+const { useDebug } = await import('./useDebug')
+
+const fire = (slot: string, event: unknown) =>
+  act(() => native.slots.get(slot)?.(event as never))
+
+let logSpy: ReturnType<typeof vi.spyOn>
+
+beforeEach(() => {
+  logSpy = vi.spyOn(console, 'log').mockImplementation(() => {})
+  // Emitters and the log store are module singletons, so both the last value
+  // and the entries outlive a test. Pin a baseline rather than letting each
+  // test inherit whatever the previous one happened to fire.
+  fire('onOnlineChanged', true)
+  fire('onPlaybackProgressUpdated', { position: 0, duration: 0, buffered: 0 })
+  const { result, unmount } = renderHook(() => useDebug({ enabled: false }))
+  act(() => result.current.clear())
+  unmount()
+  logSpy.mockClear()
+})
+
+afterEach(() => {
+  cleanup()
+  logSpy.mockRestore()
+})
+
+describe('useDebug', () => {
+  it('records nothing while disabled', () => {
+    const { result } = renderHook(() => useDebug({ enabled: false }))
+    fire('onOnlineChanged', false)
+    expect(result.current.logs).toEqual([])
+    expect(logSpy).not.toHaveBeenCalled()
+  })
+
+  it('logs a single initial snapshot on mount', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    expect(result.current.logs).toHaveLength(1)
+    expect(result.current.logs[0]).toMatchObject({
+      type: 'initial',
+      elapsed: null
+    })
+    expect(result.current.logs[0]!.message).toContain('online: true')
+  })
+
+  it('logs a change entry naming the field that moved', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', false)
+
+    expect(result.current.logs).toHaveLength(2)
+    const entry = result.current.logs[1]!
+    expect(entry.type).toBe('change')
+    expect(entry.message).toContain('online')
+    expect(entry.message).toContain('old → true')
+    expect(entry.message).toContain('new → false')
+  })
+
+  it('logs nothing when a re-render changes no field', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', true) // already true
+    expect(result.current.logs).toHaveLength(1)
+  })
+
+  // Progress ticks every second; logging each one would bury every other event.
+  it('ignores position drift under two seconds but reports a real seek', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+
+    fire('onPlaybackProgressUpdated', { position: 1, duration: 0, buffered: 0 })
+    expect(result.current.logs).toHaveLength(1)
+
+    fire('onPlaybackProgressUpdated', {
+      position: 30,
+      duration: 0,
+      buffered: 0
+    })
+    expect(result.current.logs).toHaveLength(2)
+    expect(result.current.logs[1]!.message).toContain('position')
+  })
+
+  it('clears on demand', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    fire('onOnlineChanged', false)
+    expect(result.current.logs.length).toBeGreaterThan(0)
+
+    act(() => result.current.clear())
+    expect(result.current.logs).toEqual([])
+  })
+
+  it('caps the history and keeps the newest entries', () => {
+    const { result } = renderHook(() => useDebug({ enabled: true }))
+    for (let i = 0; i < 120; i++) fire('onOnlineChanged', i % 2 === 0)
+
+    expect(result.current.logs).toHaveLength(100)
+    // 120 alternating flips after the initial snapshot: the last one set online
+    // to false (i = 119 is odd), so the newest entry is the tail, not the head.
+    expect(result.current.logs.at(-1)!.message).toContain('new → false')
+  })
+
+  describe('metadata logging', () => {
+    it('is off by default', () => {
+      const { result } = renderHook(() => useDebug({ enabled: true }))
+      fire('onTrackMetadata', { title: 'Song' })
+      expect(result.current.logs.filter((l) => l.type === 'metadata')).toEqual(
+        []
+      )
+    })
+
+    it('records track, timed and chapter events when enabled', () => {
+      const { result } = renderHook(() =>
+        useDebug({ enabled: true, metadata: true })
+      )
+
+      fire('onTrackMetadata', { title: 'Song', artist: null })
+      fire('onTimedMetadata', { title: 'Live' })
+      fire('onChapterMetadata', [{}, {}])
+
+      const entries = result.current.logs.filter((l) => l.type === 'metadata')
+      expect(entries).toHaveLength(3)
+      expect(entries[0]!.message).toContain('[track] title: "Song"')
+      // Null fields are dropped rather than printed as `artist: "null"`.
+      expect(entries[0]!.message).not.toContain('artist')
+      expect(entries[1]!.message).toContain('[timed]')
+      expect(entries[2]!.message).toContain('2 chapters')
+    })
+
+    it('stops recording metadata after unmount', () => {
+      const { result, unmount } = renderHook(() =>
+        useDebug({ enabled: true, metadata: true })
+      )
+      const before = result.current.logs.length
+      unmount()
+      fire('onTrackMetadata', { title: 'Song' })
+      expect(result.current.logs).toHaveLength(before)
+    })
+  })
+
+  it('falls back to __DEV__ when enabled is not given', () => {
+    ;(globalThis as { __DEV__?: boolean }).__DEV__ = false
+    try {
+      const { result } = renderHook(() => useDebug())
+      expect(result.current.logs).toEqual([])
+    } finally {
+      delete (globalThis as { __DEV__?: boolean }).__DEV__
+    }
+  })
+})

package/src/utils/useNativeUpdatedValue.test.ts

@@ -0,0 +1,103 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, afterEach, vi } from 'vitest'
+import { NativeUpdatedValue } from './NativeUpdatedValue'
+import { useNativeUpdatedValue } from './useNativeUpdatedValue'
+
+afterEach(cleanup)
+
+/**
+ * Builds an emitter plus the native-side callback that feeds it, so a test can
+ * push a value the way native would. `NativeUpdatedValue` hands its internal
+ * handler to the setter it is constructed with; capturing that handler _is_ the
+ * native bridge.
+ */
+function makeEmitter<T>() {
+  let emit: (value: T) => void = () => {}
+  const emitter = NativeUpdatedValue.emitterize<T>((cb) => (emit = cb))
+  return {
+    emitter,
+    /** Emit from outside React, as a native event would arrive. */
+    fire: (value: T) => act(() => emit(value)),
+    /** Emit from inside a render pass, where wrapping in `act` would nest. */
+    fireDuringRender: (value: T) => emit(value)
+  }
+}
+
+describe('useNativeUpdatedValue', () => {
+  it('falls back to the getter when nothing has fired yet', () => {
+    const { emitter } = makeEmitter<string>()
+    const { result } = renderHook(() =>
+      useNativeUpdatedValue(() => 'a', emitter)
+    )
+    expect(result.current).toBe('a')
+  })
+
+  it('prefers lastValue over the getter', () => {
+    const { emitter, fire } = makeEmitter<string>()
+    fire('fromNative')
+    const getter = vi.fn(() => 'fromGetter')
+    const { result } = renderHook(() => useNativeUpdatedValue(getter, emitter))
+    expect(result.current).toBe('fromNative')
+    expect(getter).not.toHaveBeenCalled()
+  })
+
+  it('updates when the emitter fires', () => {
+    const { emitter, fire } = makeEmitter<string>()
+    const { result } = renderHook(() =>
+      useNativeUpdatedValue(() => 'a', emitter)
+    )
+    fire('b')
+    expect(result.current).toBe('b')
+  })
+
+  it('extracts eventKey from both lastValue and later events', () => {
+    const { emitter, fire } = makeEmitter<{ volume: number }>()
+    fire({ volume: 0.5 })
+    const { result } = renderHook(() =>
+      useNativeUpdatedValue(() => 0, emitter, 'volume')
+    )
+    expect(result.current).toBe(0.5)
+    fire({ volume: 0.9 })
+    expect(result.current).toBe(0.9)
+  })
+
+  // The reason the effect re-reads `lastValue` instead of going straight to
+  // `addListener`. Nothing reads the value again until the next native event, so
+  // a value landing in this window would otherwise be missed permanently.
+  it('re-syncs a value that lands between the render read and the effect', () => {
+    const { emitter, fireDuringRender } = makeEmitter<string>()
+    // Firing from inside the getter puts the emit exactly where the race is:
+    // after the useState initializer has read, before the effect subscribes.
+    const getter = () => {
+      fireDuringRender('landedMidRender')
+      return 'staleAtRender'
+    }
+    const { result } = renderHook(() => useNativeUpdatedValue(getter, emitter))
+    expect(result.current).toBe('landedMidRender')
+  })
+
+  it('stops updating after unmount', () => {
+    const { emitter, fire } = makeEmitter<string>()
+    const { result, unmount } = renderHook(() =>
+      useNativeUpdatedValue(() => 'a', emitter)
+    )
+    unmount()
+    fire('b')
+    expect(result.current).toBe('a')
+  })
+
+  it('leaves no listener behind on unmount', () => {
+    const { emitter, fire } = makeEmitter<string>()
+    const { unmount } = renderHook(() =>
+      useNativeUpdatedValue(() => 'a', emitter)
+    )
+    unmount()
+    const seen: string[] = []
+    emitter.addListener((v) => seen.push(v))
+    fire('b')
+    // Only the listener added above — the hook's is gone, not merely inert.
+    expect(seen).toEqual(['b'])
+  })
+})

package/src/web/NativeAudioBrowser.playWhenReady.test.ts

@@ -0,0 +1,301 @@
+import { describe, expect, it } from 'vitest'
+import type { PlaybackState } from '../features'
+import type { Track } from '../types'
+import { NativeAudioBrowser } from './NativeAudioBrowser'
+
+// Transport calls must emit the intent change through the playWhenReady
+// accessor override — they previously wrote the raw base field, so JS
+// consumers never heard about play()/pause()/stop() intent changes (only
+// setPlayWhenReady()'s) and MediaSession never synced.
+class TestBrowser extends NativeAudioBrowser {
+  playCalls = 0
+  pauseCalls = 0
+
+  constructor() {
+    super()
+    // Minimal fakes so transport calls run without setupPlayer/DOM.
+    this.element = {
+      play: () => {
+        this.playCalls++
+        return Promise.resolve()
+      },
+      pause: () => {
+        this.pauseCalls++
+      }
+    } as unknown as HTMLMediaElement
+    this.player = {
+      load: () => Promise.resolve(),
+      unload: () => Promise.resolve()
+    } as unknown as typeof this.player
+  }
+
+  forceState(state: PlaybackState): void {
+    this.state = { state }
+  }
+}
+
+const track: Track = {
+  id: 't1',
+  src: 'https://example.com/audio.mp3',
+  title: 'Test Track'
+}
+
+function makeBrowser(): { browser: TestBrowser; emitted: boolean[] } {
+  const browser = new TestBrowser()
+  const emitted: boolean[] = []
+  browser.onPlaybackPlayWhenReadyChanged = (event) =>
+    emitted.push(event.playWhenReady)
+  return { browser, emitted }
+}
+
+describe('NativeAudioBrowser playWhenReady emission', () => {
+  it('play() emits the intent change', () => {
+    const { browser, emitted } = makeBrowser()
+    browser.play()
+    expect(emitted).toEqual([true])
+  })
+
+  it('pause() emits the intent change', () => {
+    const { browser, emitted } = makeBrowser()
+    browser.play()
+    browser.pause()
+    expect(emitted).toEqual([true, false])
+  })
+
+  it('stop() emits the intent change', () => {
+    const { browser, emitted } = makeBrowser()
+    browser.play()
+    browser.stop()
+    expect(emitted).toEqual([true, false])
+  })
+
+  it('does not emit when the value is unchanged', () => {
+    const { browser, emitted } = makeBrowser()
+    browser.play()
+    browser.play()
+    expect(emitted).toEqual([true])
+  })
+})
+
+// setPlayWhenReady must drive the engine like native, not just the flag:
+// audio kept playing after setPlayWhenReady(false) while every event and
+// MediaSession reported paused, and true from 'paused' never resumed.
+describe('NativeAudioBrowser setPlayWhenReady drives the engine', () => {
+  it('false pauses the element', () => {
+    const { browser } = makeBrowser()
+    browser.play()
+    browser.forceState('playing')
+
+    browser.setPlayWhenReady(false)
+
+    expect(browser.pauseCalls).toBe(1)
+    expect(browser.getPlayWhenReady()).toBe(false)
+  })
+
+  it('true from paused resumes the element', () => {
+    const { browser } = makeBrowser()
+    browser.current = track
+    browser.forceState('paused')
+
+    browser.setPlayWhenReady(true)
+
+    expect(browser.playCalls).toBe(1)
+  })
+
+  it('true while loading only sets the flag (load auto-plays)', () => {
+    const { browser } = makeBrowser()
+    browser.current = track
+    browser.forceState('loading')
+
+    browser.setPlayWhenReady(true)
+
+    expect(browser.playCalls).toBe(0)
+    expect(browser.getPlayWhenReady()).toBe(true)
+  })
+})
+
+// Intent-only changes alter the derived playing/buffering flags without a
+// state transition (e.g. pause during 'loading') — they must emit too, and
+// identical derivations must not double-emit (parity with Android's
+// refreshPlayingState dedupe).
+describe('NativeAudioBrowser playing-state emission', () => {
+  it('emits on an intent-only change', () => {
+    const { browser } = makeBrowser()
+    const states: Array<{ playing: boolean; buffering: boolean }> = []
+    browser.onPlaybackPlayingState = (s) =>
+      states.push({ playing: s.playing, buffering: s.buffering })
+    browser.forceState('loading')
+    browser.setPlayWhenReady(true)
+    states.length = 0
+
+    browser.setPlayWhenReady(false)
+
+    expect(states).toEqual([{ playing: false, buffering: false }])
+  })
+
+  it('does not re-emit an identical derivation across state changes', () => {
+    const { browser } = makeBrowser()
+    const states: Array<{ playing: boolean }> = []
+    browser.onPlaybackPlayingState = (s) => states.push({ playing: s.playing })
+
+    browser.forceState('paused')
+    browser.forceState('stopped')
+
+    // pwr is false throughout: both derive {playing:false,buffering:false}.
+    expect(states.length).toBe(1)
+  })
+})
+
+describe('NativeAudioBrowser stop vs in-flight load', () => {
+  it('stop() invalidates a load still resolving its URL', async () => {
+    const { browser } = makeBrowser()
+    browser.load(track)
+    browser.stop()
+
+    // Let the load's post-await continuation run.
+    await new Promise((resolve) => setTimeout(resolve, 0))
+
+    // The stale load must not revive the player: previously its continuation
+    // re-armed _isStopped = false and set the current track after stop().
+    expect(browser.current).toBeUndefined()
+    expect(browser.getPlayback().state).toBe('stopped')
+  })
+})
+
+// Queue mutations must emit onPlaybackQueueChanged (the JS contract documents
+// "added, removed, reordered"; Android emits via onTimelineChanged) — only
+// load/setQueue did on web, so useQueue() went stale after any mutation.
+describe('NativeAudioBrowser queue change events', () => {
+  function makeQueueBrowser(): {
+    browser: TestBrowser
+    lengths: number[]
+  } {
+    class QueueEventBrowser extends TestBrowser {
+      load(): void {}
+    }
+    const browser = new QueueEventBrowser()
+    const lengths: number[] = []
+    browser.onPlaybackQueueChanged = (queue) => lengths.push(queue.length)
+    browser.setQueue([track, { ...track, id: 't2' }], 0)
+    lengths.length = 0
+    return { browser, lengths }
+  }
+
+  it('add emits', () => {
+    const { browser, lengths } = makeQueueBrowser()
+    browser.add([{ ...track, id: 't3' }])
+    expect(lengths).toEqual([3])
+  })
+
+  it('remove emits', () => {
+    const { browser, lengths } = makeQueueBrowser()
+    browser.remove([1])
+    expect(lengths).toEqual([1])
+  })
+
+  it('move emits', () => {
+    const { browser, lengths } = makeQueueBrowser()
+    browser.move(0, 1)
+    expect(lengths).toEqual([2])
+  })
+
+  it('removeUpcomingTracks emits', () => {
+    const { browser, lengths } = makeQueueBrowser()
+    browser.removeUpcomingTracks()
+    expect(lengths).toEqual([1])
+  })
+
+  it('reset emits the emptied queue', () => {
+    const { browser, lengths } = makeQueueBrowser()
+    browser.reset()
+    expect(lengths).toEqual([0])
+  })
+})
+
+// The queue array must never leak by live reference: in-place mutations
+// (add/move) otherwise emit the same object React already holds, and the
+// useState Object.is bailout suppresses the re-render the event exists for.
+describe('NativeAudioBrowser queue reference freshness', () => {
+  it('emits a fresh array on each mutation', () => {
+    class QueueEventBrowser extends TestBrowser {
+      load(): void {}
+    }
+    const browser = new QueueEventBrowser()
+    const seen: object[] = []
+    browser.onPlaybackQueueChanged = (queue) => seen.push(queue)
+    browser.setQueue([track, { ...track, id: 't2' }], 0)
+
+    browser.add([{ ...track, id: 't3' }])
+    browser.move(0, 1)
+
+    expect(seen[1]).not.toBe(seen[0])
+    expect(seen[2]).not.toBe(seen[1])
+    expect(seen[2]).not.toBe(browser.getQueue())
+  })
+
+  it('getQueue returns a defensive copy', () => {
+    class QueueEventBrowser extends TestBrowser {
+      load(): void {}
+    }
+    const browser = new QueueEventBrowser()
+    browser.setQueue([track, { ...track, id: 't2' }], 0)
+
+    browser.getQueue().length = 0
+
+    expect(browser.getQueue().length).toBe(2)
+  })
+})
+
+// Halting must precede the fade-cancel volume restore — the reverse lets
+// full-volume audio slip out while the element is still playing.
+describe('NativeAudioBrowser sleep-fade halt order', () => {
+  it('setPlayWhenReady(false) pauses before restoring the fading volume', () => {
+    const order: string[] = []
+    class FadeBrowser extends NativeAudioBrowser {
+      constructor() {
+        super()
+        this.element = {
+          play: () => Promise.resolve(),
+          pause: () => {
+            order.push('pause')
+          },
+          get volume() {
+            return 1
+          },
+          set volume(_v: number) {
+            order.push('volume')
+          }
+        } as unknown as HTMLMediaElement
+        this.player = {
+          unload: () => Promise.resolve()
+        } as unknown as typeof this.player
+      }
+    }
+    const browser = new FadeBrowser()
+    ;(
+      browser as unknown as { sleepFader: { start(d: number): void } }
+    ).sleepFader.start(10)
+    order.length = 0
+
+    browser.setPlayWhenReady(false)
+
+    expect(order[0]).toBe('pause')
+    expect(order).toContain('volume')
+  })
+})
+
+describe('NativeAudioBrowser setQueue start position', () => {
+  it('passes startPosition through to skip() in seconds', () => {
+    const skips: Array<[number, number | undefined]> = []
+    class SkipRecordingBrowser extends TestBrowser {
+      skip(index: number, initialPosition?: number): void {
+        skips.push([index, initialPosition])
+      }
+    }
+    const browser = new SkipRecordingBrowser()
+
+    browser.setQueue([track], 0, 30)
+
+    expect(skips).toEqual([[0, 30]])
+  })
+})