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

package/src/features/player/setup.test.ts

@@ -52,7 +52,11 @@ describe('setupPlayer wire regrouping', () => {
         minBuffer: 50_000,
         wakeMode: 'network',
         skipSilence: true,
-        notificationButtons: { overflow: ['favorite'] }
+        remoteButtonLayout: {
+          back: 'jump-backward',
+          forward: 'jump-forward',
+          overflow: ['favorite']
+        }
       }
     })
 
@@ -61,19 +65,32 @@ describe('setupPlayer wire regrouping', () => {
     expect(sent.options).toEqual({
       android: {
         skipSilence: true,
-        notificationButtons: { overflow: ['favorite'] }
+        remoteButtonLayout: {
+          back: 'jump-backward',
+          forward: 'jump-forward',
+          overflow: ['favorite']
+        }
       }
     })
   })
 
-  it('moves ios playbackRates into the runtime options', async () => {
+  it('moves ios runtime fields into the runtime options', async () => {
     await setupPlayer({
-      ios: { category: 'playback', playbackRates: [0.5, 1, 2] }
+      ios: {
+        category: 'playback',
+        playbackRates: [0.5, 1, 2],
+        carPlayPlayingIndicatorLocation: 'trailing'
+      }
     })
 
     const sent = payload()
     expect(sent.ios).toEqual({ category: 'playback' })
-    expect(sent.options).toEqual({ ios: { playbackRates: [0.5, 1, 2] } })
+    expect(sent.options).toEqual({
+      ios: {
+        playbackRates: [0.5, 1, 2],
+        carPlayPlayingIndicatorLocation: 'trailing'
+      }
+    })
   })
 
   it('omits a platform bag that only carried runtime fields', async () => {
@@ -85,12 +102,12 @@ describe('setupPlayer wire regrouping', () => {
   it('forwards meaningful nulls (progress disabled, empty button layout)', async () => {
     await setupPlayer({
       progressUpdateEventInterval: null,
-      android: { notificationButtons: null }
+      android: { remoteButtonLayout: null }
     })
 
     expect(payload().options).toEqual({
       progressUpdateEventInterval: null,
-      android: { notificationButtons: null }
+      android: { remoteButtonLayout: null }
     })
   })
 

package/src/features/player/setup.ts

@@ -11,7 +11,7 @@ import type {
   UpdateOptions
 } from './options'
 import { nativeBrowser } from '../../native'
-import { validateIOSUpdateOptions } from './options'
+import { validateIOSUpdateOptions } from './validateOptions'
 
 /**
  * Parameters passed to the {@link FormatNowPlayingCallback}.
@@ -25,7 +25,10 @@ import { validateIOSUpdateOptions } from './options'
 export type FormatNowPlayingParams = {
   /** The currently playing track. */
   track: Track
-  /** Timed metadata (ICY / ID3 "now playing song") received during playback, if any. */
+  /**
+   * Timed metadata (ICY / ID3 "now playing song") received during playback, if any.
+   * Always `undefined` on web — see `onTimedMetadata` for why.
+   */
   timedMetadata?: TimedMetadata
   /** The play/pause intent — `false` while paused. Stays `true` through buffers, so the song line won't flicker. */
   playWhenReady: boolean
@@ -326,7 +329,7 @@ export type AndroidPlayerWakeMode = 'none' | 'local' | 'network'
 
 /**
  * Android setup options: the engine-construction fields plus the Android runtime options
- * ({@link AndroidUpdateOptions} — `notificationButtons`, `skipSilence`, …), all expressible at
+ * ({@link AndroidUpdateOptions} — `remoteButtonLayout`, `skipSilence`, …), all expressible at
  * launch. The consumer never has to know which is which; `setupPlayer` routes each field to
  * where it's applied.
  */
@@ -496,7 +499,7 @@ export interface NativeSetupPlayerOptions extends Pick<
 
   /**
    * Player options to apply atomically with setup. They're stored before the player is
-   * constructed, so e.g. Android's media session derives its notification buttons from
+   * constructed, so e.g. Android's media session derives its remote button layout from
    * `capabilities` the moment the service connects — no window with default controls.
    * Normalized from the flat fields on {@link SetupPlayerOptions}.
    */
@@ -658,7 +661,7 @@ function wrapNowPlayingFormatter(
 
 /**
  * The object's entries whose values aren't `undefined`. `null` stays: it's meaningful on some
- * fields (`progressUpdateEventInterval: null` disables progress events, `notificationButtons:
+ * fields (`progressUpdateEventInterval: null` disables progress events, `remoteButtonLayout:
  * null` empties the layout), so only `undefined` means "not provided".
  */
 function definedFields<T extends object>(obj: T): Partial<T> {
@@ -682,7 +685,7 @@ function nonEmpty<K extends string, T extends object>(
 /**
  * Initializes the player with the specified options — the full launch description in one
  * declarative, atomic call. Runtime options (`capabilities`, jump intervals,
- * `notificationButtons`, …) and the initial `playWhenReady` / `repeatMode` are applied
+ * `remoteButtonLayout`, …) and the initial `playWhenReady` / `repeatMode` are applied
  * natively as part of setup itself, so there is no setup-then-command ordering for consumers
  * to know about, and no window where the player exists without its options.
  *
@@ -699,7 +702,14 @@ function nonEmpty<K extends string, T extends object>(
  *   playWhenReady: true,
  *   repeatMode: 'queue',
  *   capabilities: { favorite: true },
- *   android: { audioContentType: 'music', notificationButtons: { overflow: ['favorite'] } },
+ *   android: {
+ *     audioContentType: 'music',
+ *     remoteButtonLayout: {
+ *       back: 'jump-backward',
+ *       forward: 'jump-forward',
+ *       overflow: ['favorite']
+ *     }
+ *   },
  *   ios: { category: 'playback' }
  * })
  * ```
@@ -724,19 +734,21 @@ export async function setupPlayer(
   const {
     appKilledPlaybackBehavior,
     skipSilence,
-    notificationButtons,
+    remoteButtonLayout,
     ...androidSetup
   } = android
   const {
     playbackRates,
     carPlayUpNextButton,
     carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation,
     ...iosSetup
   } = ios
   const iosUpdate = definedFields({
     playbackRates,
     carPlayUpNextButton,
-    carPlayNowPlayingButtons
+    carPlayNowPlayingButtons,
+    carPlayPlayingIndicatorLocation
   })
   validateIOSUpdateOptions(iosUpdate)
 
@@ -750,7 +762,7 @@ export async function setupPlayer(
       definedFields({
         appKilledPlaybackBehavior,
         skipSilence,
-        notificationButtons
+        remoteButtonLayout
       })
     ),
     ...nonEmpty('ios', iosUpdate)

package/src/features/player/validateOptions.ts

@@ -0,0 +1,21 @@
+import type { IOSUpdateOptions } from './options'
+
+const MAX_CARPLAY_NOW_PLAYING_BUTTONS = 5
+
+/**
+ * Warns when more CarPlay now-playing buttons are configured than CarPlay renders.
+ * Shared by `updateOptions` and `setupPlayer` (both can carry `ios` options).
+ * Kept out of `options.ts`, which the barrel re-exports — see
+ * public-surface.test.ts.
+ *
+ * @internal
+ */
+export function validateIOSUpdateOptions(ios?: IOSUpdateOptions): void {
+  const buttons = ios?.carPlayNowPlayingButtons
+  if (buttons && buttons.length > MAX_CARPLAY_NOW_PLAYING_BUTTONS) {
+    console.warn(
+      `[react-native-audio-browser] ${buttons.length} CarPlay now-playing ` +
+        `buttons configured; CarPlay shows at most ${MAX_CARPLAY_NOW_PLAYING_BUTTONS}.`
+    )
+  }
+}

package/src/features/queue/activeTrack.ts

@@ -1,7 +1,8 @@
 import type { Track } from '../../types'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
-import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { useNativeValueRefreshedBy } from '../../utils/useNativeValueRefreshedBy'
+import { onFavoriteChanged } from '../favorites'
 
 /**
  * Event data for when the active track changes.
@@ -40,8 +41,14 @@ export function getActiveTrackIndex(): number | undefined {
 
 /**
  * Subscribes to active track change events.
+ *
+ * Fires on **transitions only** — selection, queue advance, skip. In-place
+ * metadata mutations of the active track (a favorite toggle) emit
+ * {@link onFavoriteChanged} instead; {@link useActiveTrack} subscribes to
+ * both, so UI bound through the hook still re-renders on a heart toggle.
+ *
  * @param callback - Called when the active track changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onActiveTrackChanged =
   NativeUpdatedValue.emitterize<PlaybackActiveTrackChangedEvent>(
@@ -50,10 +57,14 @@ export const onActiveTrackChanged =
 
 // MARK: - Hooks
 
+// Module-level so the hook's subscription identity is stable across renders.
+const activeTrackInvalidators = [onActiveTrackChanged, onFavoriteChanged]
+
 /**
- * Hook that returns the current active track and updates when it changes.
+ * Hook that returns the current active track, updating on transitions AND on
+ * in-place mutations of the active track (favorite toggles).
  * @returns The current active track or undefined
  */
 export function useActiveTrack(): Track | undefined {
-  return useNativeUpdatedValue(getActiveTrack, onActiveTrackChanged, 'track')
+  return useNativeValueRefreshedBy(getActiveTrack, activeTrackInvalidators)
 }

package/src/features/queue/queue.ts

@@ -1,7 +1,8 @@
 import type { Track } from '../../types'
 import { nativeBrowser } from '../../native'
 import { NativeUpdatedValue } from '../../utils/NativeUpdatedValue'
-import { useNativeUpdatedValue } from '../../utils/useNativeUpdatedValue'
+import { useNativeValueRefreshedBy } from '../../utils/useNativeValueRefreshedBy'
+import { onFavoriteChanged } from '../favorites'
 
 // MARK: - Types
 
@@ -156,7 +157,7 @@ export function getQueue(): Track[] {
 /**
  * Subscribes to playback queue ended events.
  * @param callback - Called when playback has paused due to reaching the end of the queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueEnded =
   NativeUpdatedValue.emitterize<PlaybackQueueEndedEvent>(
@@ -165,9 +166,11 @@ export const onQueueEnded =
 
 /**
  * Subscribes to queue change events.
- * Called when tracks are added, removed, reordered, or when track metadata changes.
+ * Called when tracks are added, removed, or reordered. An in-place mutation of
+ * a queued track's metadata (a favorite toggle) emits `onFavoriteChanged`
+ * instead; {@link useQueue} subscribes to both.
  * @param callback - Called with the updated queue
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
   (cb) => (nativeBrowser.onPlaybackQueueChanged = cb)
@@ -175,10 +178,14 @@ export const onQueueChanged = NativeUpdatedValue.emitterize<Track[]>(
 
 // MARK: - Hooks
 
+// Module-level so the hook's subscription identity is stable across renders.
+const queueInvalidators = [onQueueChanged, onFavoriteChanged]
+
 /**
- * Hook that returns the current queue and updates when it changes.
+ * Hook that returns the current queue, updating on queue changes AND on
+ * in-place mutations of queued tracks (favorite toggles).
  * @returns The current queue
  */
 export function useQueue(): Track[] {
-  return useNativeUpdatedValue(getQueue, onQueueChanged)
+  return useNativeValueRefreshedBy(getQueue, queueInvalidators)
 }

package/src/features/queue/repeatMode.ts

@@ -40,7 +40,7 @@ export interface RepeatModeChangedEvent {
 /**
  * Subscribes to repeat mode changes.
  * @param callback - Called when repeat mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRepeatModeChanged =
   NativeUpdatedValue.emitterize<RepeatModeChangedEvent>(

package/src/features/queue/shuffle.ts

@@ -32,7 +32,7 @@ export function toggleShuffle(): void {
 /**
  * Subscribes to shuffle mode changes.
  * @param callback - Called when shuffle mode changes
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onShuffleChanged = NativeUpdatedValue.emitterize<boolean>(
   (cb) => (nativeBrowser.onPlaybackShuffleModeChanged = cb)

package/src/features/remoteControls.ts

@@ -53,90 +53,11 @@ export interface RemoteSkipEvent {
   index: number
 }
 
-// MARK: - Default Handlers
-
-// Install remote control handlers with default behavior immediately when module loads
-// Custom handlers can override the defaults using handleRemote* functions
-
-// Basic playback controls
-// AudioBrowser.onRemotePlay(() => {
-//   const customHandler = customHandlers.get('play')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     play()
-//   }
-// })
-
-// AudioBrowser.onRemotePause(() => {
-//   const customHandler = customHandlers.get('pause')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     pause()
-//   }
-// })
-
-// AudioBrowser.onRemoteNext(() => {
-//   const customHandler = customHandlers.get('next')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToNext()
-//   }
-// })
-
-// AudioBrowser.onRemotePrevious(() => {
-//   const customHandler = customHandlers.get('previous')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     skipToPrevious()
-//   }
-// })
-
-// AudioBrowser.onRemoteStop(() => {
-//   const customHandler = customHandlers.get('stop')
-//   if (customHandler) {
-//     customHandler()
-//   } else {
-//     stop()
-//   }
-// })
-
-// // Seek controls
-// AudioBrowser.onRemoteSeek((event: any) => {
-//   const customHandler = customHandlers.get('seek')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekTo(event.position)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpForward((event: any) => {
-//   const customHandler = customHandlers.get('jumpForward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(event.interval)
-//   }
-// })
-
-// AudioBrowser.onRemoteJumpBackward((event: any) => {
-//   const customHandler = customHandlers.get('jumpBackward')
-//   if (customHandler) {
-//     customHandler(event)
-//   } else {
-//     seekBy(-event.interval)
-//   }
-// })
-
 // MARK: - Handler Override Functions
 //
 // Use these functions when you want to OVERRIDE the default remote control behavior.
 // These will replace the default handlers with your custom logic.
-// If you just want to listen to events for debugging/logging, use the onRemote* functions below.
+// If you just want to listen to events for debugging/logging, use the onRemote* emitters below.
 
 /**
  * Sets a custom handler for remote play events, overriding the default behavior.
@@ -210,7 +131,7 @@ export function handleRemoteJumpBackward(
 
 // MARK: - Event Callbacks (for listening/debugging only)
 //
-// Use these functions when you want to LISTEN to remote control events without overriding
+// Use these emitters when you want to LISTEN to remote control events without overriding
 // the default behavior. These are perfect for logging, analytics, or debugging.
 // Multiple listeners can be registered for the same event.
 // To override the default behavior, use the handleRemote* functions above.
@@ -218,7 +139,7 @@ export function handleRemoteJumpBackward(
 /**
  * Subscribes to remote jump backward events.
  * @param callback - Called when the user presses the jump backward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpBackward =
   LazyNativeEmitter.emitterize<RemoteJumpBackwardEvent>(
@@ -228,7 +149,7 @@ export const onRemoteJumpBackward =
 /**
  * Subscribes to remote jump forward events.
  * @param callback - Called when the user presses the jump forward button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteJumpForward =
   LazyNativeEmitter.emitterize<RemoteJumpForwardEvent>(
@@ -238,7 +159,7 @@ export const onRemoteJumpForward =
 /**
  * Subscribes to remote next events.
  * @param callback - Called when the user presses the next track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteNext = cb)
@@ -247,7 +168,7 @@ export const onRemoteNext = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote pause events.
  * @param callback - Called when the user presses the pause button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePause = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePause = cb)
@@ -256,7 +177,7 @@ export const onRemotePause = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play events.
  * @param callback - Called when the user presses the play button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePlay = cb)
@@ -265,7 +186,7 @@ export const onRemotePlay = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote play ID events (Android only).
  * @param callback - Called when the user selects a track from an external device
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
   (cb) => (nativeBrowser.onRemotePlayId = cb)
@@ -274,7 +195,7 @@ export const onRemotePlayId = LazyNativeEmitter.emitterize<RemotePlayIdEvent>(
 /**
  * Subscribes to remote play search events (Android only).
  * @param callback - Called when the user searches for a track (usually voice search)
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePlaySearch =
   LazyNativeEmitter.emitterize<RemotePlaySearchEvent>(
@@ -284,7 +205,7 @@ export const onRemotePlaySearch =
 /**
  * Subscribes to remote previous events.
  * @param callback - Called when the user presses the previous track button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemotePrevious = cb)
@@ -293,7 +214,7 @@ export const onRemotePrevious = LazyNativeEmitter.emitterize<void>(
 /**
  * Subscribes to remote seek events.
  * @param callback - Called when the user changes the position of the timeline
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
   (cb) => (nativeBrowser.onRemoteSeek = cb)
@@ -302,7 +223,7 @@ export const onRemoteSeek = LazyNativeEmitter.emitterize<RemoteSeekEvent>(
 /**
  * Subscribes to remote skip events (Android only).
  * @param callback - Called when the user presses the skip button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
   (cb) => (nativeBrowser.onRemoteSkip = cb)
@@ -311,7 +232,7 @@ export const onRemoteSkip = LazyNativeEmitter.emitterize<RemoteSkipEvent>(
 /**
  * Subscribes to remote stop events.
  * @param callback - Called when the user presses the stop button
- * @returns Cleanup function to unsubscribe
+ * @returns An emitter — subscribe with `addListener(callback)`, which returns a cleanup function
  */
 export const onRemoteStop = LazyNativeEmitter.emitterize<void>(
   (cb) => (nativeBrowser.onRemoteStop = cb)

package/src/features/sleepTimer.test.ts

@@ -0,0 +1,172 @@
+/** @vitest-environment happy-dom */
+
+import { renderHook, act, cleanup } from '@testing-library/react'
+import { describe, it, expect, beforeEach, afterEach, vi } from 'vitest'
+import type { SleepTimer } from './sleepTimer'
+
+const native = vi.hoisted(() => ({
+  getSleepTimer: vi.fn<() => SleepTimer>(() => null),
+  // The single callback slot `NativeUpdatedValue` claims at module load.
+  onSleepTimerChanged: undefined as ((timer: SleepTimer) => void) | undefined
+}))
+
+vi.mock('../native', () => ({ nativeBrowser: native }))
+
+const { onSleepTimerChanged, useSleepTimer, useSleepTimerActive } =
+  await import('./sleepTimer')
+
+/** Push a value the way native would. */
+const fire = (timer: SleepTimer) =>
+  act(() => native.onSleepTimerChanged?.(timer))
+
+/**
+ * The emitter is a module-level singleton, so `lastValue` outlives each test.
+ * `undefined` is its pre-native state and distinct from `null`, which is a real
+ * value meaning "no timer" — the distinction the re-sync gate turns on.
+ */
+beforeEach(() => {
+  onSleepTimerChanged.lastValue = undefined
+  native.getSleepTimer.mockReturnValue(null)
+})
+afterEach(cleanup)
+
+describe('useSleepTimerActive', () => {
+  it('reads the getter when nothing has fired yet', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('tracks timers being set and cleared', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(true)
+    fire(null)
+    expect(result.current).toBe(false)
+  })
+
+  it('treats an end-of-track timer as active', () => {
+    const { result } = renderHook(() => useSleepTimerActive())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toBe(true)
+  })
+
+  // The regression from f7a25040. The getter ran during render and saw a live
+  // timer; the clear landed before the effect subscribed. Without the re-sync
+  // the UI shows a running timer that is already gone — permanently, since
+  // nothing reads it again until the next native event.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(false)
+  })
+
+  // The gate is `!== undefined`, not truthiness: `undefined` means native has
+  // never spoken, so the getter's answer must stand.
+  it('keeps the getter value when native has not fired at all', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    const { result } = renderHook(() => useSleepTimerActive())
+    expect(result.current).toBe(true)
+  })
+
+  it('stops tracking after unmount', () => {
+    const { result, unmount } = renderHook(() => useSleepTimerActive())
+    unmount()
+    fire({ time: Date.now() + 60_000 })
+    expect(result.current).toBe(false)
+  })
+})
+
+describe('useSleepTimer', () => {
+  it('is undefined when no timer is set', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+
+  it('reports secondsLeft for a time-based timer', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 30_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toEqual({
+        time: 1_000_000_030_000,
+        secondsLeft: 30
+      })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('passes an end-of-track timer through without secondsLeft', () => {
+    const { result } = renderHook(() => useSleepTimer())
+    fire({ sleepWhenPlayedToEnd: true })
+    expect(result.current).toEqual({ sleepWhenPlayedToEnd: true })
+  })
+
+  it('counts down as time passes', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 5_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      expect(result.current).toMatchObject({ secondsLeft: 5 })
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 3 })
+      act(() => {
+        vi.advanceTimersByTime(3_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('stops the countdown once it reaches zero', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 2_000 })
+      const { result } = renderHook(() => useSleepTimer())
+      act(() => {
+        vi.advanceTimersByTime(2_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+      // Clamped at zero rather than running negative.
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 0 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  it('does not tick while inactive', () => {
+    vi.useFakeTimers()
+    try {
+      vi.setSystemTime(1_000_000_000_000)
+      native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+      const { result } = renderHook(() => useSleepTimer({ inactive: true }))
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+      act(() => {
+        vi.advanceTimersByTime(10_000)
+      })
+      expect(result.current).toMatchObject({ secondsLeft: 60 })
+    } finally {
+      vi.useRealTimers()
+    }
+  })
+
+  // Same race as useSleepTimerActive, and the reason both hooks carry the gate.
+  it('re-syncs a clear that landed between the render read and the effect', () => {
+    native.getSleepTimer.mockReturnValue({ time: Date.now() + 60_000 })
+    onSleepTimerChanged.lastValue = null
+    const { result } = renderHook(() => useSleepTimer())
+    expect(result.current).toBeUndefined()
+  })
+})