react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.31

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,15 +427,23 @@ 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
  * 2. `media`/`artwork` config - resource-specific settings
- * 3. `resolve(track)` result - per-track overrides (if provided)
- * 4. `transform(request)` result - final modifications (if provided)
+ * 3. the per-track callbacks, in an order that differs by kind:
+ *    - `artwork`: `resolve(track)`, then `transform(request)` last
+ *    - `media`: `transform(request)`, then **`resolve(track)` last** — the
+ *      per-track resolver is the most specific layer and wins over the
+ *      transform, on every platform
+ *
+ * The `media` order is deliberate: a resolver minting a per-track signed URL
+ * must not be overwritten by the static layer that shaped the unsigned one. It
+ * means a `media.transform` cannot sign what `resolve` produced — do that work
+ * inside `resolve`, or move the signing to `transform` and drop `resolve`.
  *
- * ## Usage Patterns
+ * ### Usage Patterns
  *
  * **Simple CDN configuration:**
  * ```typescript
@@ -477,8 +486,9 @@ export interface MediaRequestConfig extends TransformableRequestConfig {
    * Receives the full Track object, allowing URL generation based on
    * track metadata (id, artist, album, src, etc.).
    *
-   * The returned config is merged with base configs, then passed to
-   * `transform` if provided.
+   * Runs **last** for media — after `transform`, and winning over it on every
+   * field including `path`. See the hierarchy note on this interface; artwork
+   * runs them the other way round.
    *
    * @param track - The track being requested
    * @returns Request configuration for this specific track (sync or async)
@@ -590,9 +600,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 +666,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 +851,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 +877,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
@@ -963,6 +940,41 @@ export type BrowserConfiguration = {
    */
   androidControllerOfflineError?: boolean
 
+  /**
+   * Titles the "view more" row appended to a `Section` that carries a
+   * `Section.path` on surfaces whose section header cannot be tapped —
+   * Android Auto, today the only one.
+   *
+   * Leave it unset and the row is titled "View more" — the library's in-code
+   * default, the same arrangement `formatNavigationError` has. Set this to
+   * localize it: it is re-resolved once per content generation, so
+   * `invalidateAllContent()` after an in-app language switch picks up the new
+   * copy without reconfiguring the browser. That is why it is a callback rather
+   * than a plain string — an app whose locale is its own, not the system's,
+   * cannot express that with a value frozen at configure time.
+   *
+   * One string for every section by design — the row is a fallback for a
+   * surface that cannot draw a link in its header, so per-section wording would
+   * be ceremony most consumers never see rendered.
+   *
+   * For wording that varies by section — "View all 42 albums", "See every
+   * episode" — author the link yourself instead: append an ordinary browsable
+   * {@link Track} to the section's `children`, titled however you like, and
+   * leave `Section.path` unset so this row doesn't also appear. Since the
+   * row is Android-only, that branch is an ordinary platform check on the
+   * content you emit; CarPlay never sees the extra row.
+   *
+   * @default 'View more'
+   *
+   * @example
+   * ```typescript
+   * viewMoreTitle: () => t('View more')
+   * ```
+   *
+   * @platform android
+   */
+  viewMoreTitle?: ViewMoreTitleCallback
+
   /**
    * Title shown (as the list's centered empty state) on CarPlay screens whose
    * content is still loading — browse destinations while they resolve, and the
@@ -983,22 +995,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 +1050,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.
  *
@@ -1051,7 +1074,7 @@ export type CarPlaySiriListButtonPosition = 'top' | 'bottom'
  */
 export type FormattedNavigationError = {
   /**
-   * Title shown in the error action sheet header.
+   * Title of the error.
    *
    * Default values:
    * - `'content-not-found'`: "Content Not Found" (English)
@@ -1062,14 +1085,17 @@ export type FormattedNavigationError = {
    */
   title: string
   /**
-   * Optional second line — the body in the error action sheet, the subtitle in
-   * the browse error/empty view. Omit it to show a title only.
+   * Optional second line — the subtitle in the browse error/empty view. Omit it
+   * to show a title only.
    *
    * Default value: `error.message` (omitted when that is empty).
    */
   message?: string
 }
 
+/** What was being requested when a navigation error occurred. */
+export type NavigationErrorKind = 'browse' | 'search'
+
 /**
  * Parameters passed to the formatNavigationError callback.
  */
@@ -1080,6 +1106,8 @@ export type FormatNavigationErrorParams = {
   defaultFormatted: FormattedNavigationError
   /** The path that was being navigated to when the error occurred */
   path: string
+  /** Whether the failed request was a browse or a search */
+  kind: NavigationErrorKind
 }
 
 /**
@@ -1092,7 +1120,10 @@ export type FormatNavigationErrorParams = {
  * @example
  * ```typescript
  * // Override only specific error types or routes
- * formatNavigationError: ({ error, defaultFormatted, path }) => {
+ * formatNavigationError: ({ error, defaultFormatted, path, kind }) => {
+ *   if (error.code === 'empty-content' && kind === 'search') {
+ *     return { title: 'No results found' }
+ *   }
  *   // Custom message for local server routes
  *   if (error.code === 'network-error' && path.startsWith('/errors')) {
  *     return {
@@ -1111,6 +1142,9 @@ 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
+
+/** Supplies the title of the appended "view more" row. See `viewMoreTitle`. */
+export type ViewMoreTitleCallback = () => string

package/src/utils/LazyNativeEmitter.ts

@@ -1,26 +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 = LazyEmitter.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
   }
@@ -36,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)
@@ -43,14 +54,16 @@ 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
+   * @internal
    */
   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,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/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__
+    }
+  })
+})