react-native-queue-player 1.0.3 → 1.0.6

package/android/src/main/java/com/margelo/nitro/queueplayer/BufferStateTranslator.kt

@@ -9,7 +9,7 @@ import androidx.media3.common.Player
  *
  * Extracted from [TrackPlayer.computeBufferState] so the discriminator
  * between an initial `BUFFERING` load and a mid-playback `STALLED`
- * rebuffer is unit-testable without a live ExoPlayer, matching the
+ * rebuffer stands alone without a live ExoPlayer, matching the
  * [TransportStateTranslator] pattern.
  */
 internal object BufferStateTranslator {

package/android/src/main/java/com/margelo/nitro/queueplayer/CarConnectionState.kt

@@ -0,0 +1,46 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.annotation.VisibleForTesting
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Process-wide count of attached headless (automotive) controllers, backing
+ * the `isCarConnected()` getter. Holds the same "a car is connected" state
+ * the `onCarConnect` / `onCarDisconnect` events transition between, so a
+ * consumer that missed the connect event — because it fired before the
+ * consumer registered its handler in this process — can still gate car-only
+ * work (e.g. browse-snapshot pushes) on the current connection.
+ *
+ * The count is process-scoped rather than tied to a [PlaybackService]
+ * instance so it stays correct across a service restart while a controller
+ * remains attached: the new instance's `onConnect` and the dying instance's
+ * late `onConnect`/`onDisconnected` all mutate this single source of truth, so
+ * the getter can't momentarily read disconnected mid-handoff. It is
+ * floor-guarded so a stray disconnect can't drive it negative, and process
+ * death clears it (a fresh process starts disconnected), which is correct.
+ *
+ * Only [PlaybackServiceCallback] mutates this — at the same headless
+ * connect / disconnect points that drive the events. This count is separate
+ * from that callback's per-instance counter, which stays per-service so the
+ * events keep their per-session first/last edge semantics.
+ */
+internal object CarConnectionState {
+  private val count = AtomicInteger(0)
+
+  fun isConnected(): Boolean = count.get() > 0
+
+  /** A headless controller attached. */
+  fun retain() {
+    count.incrementAndGet()
+  }
+
+  /** A headless controller detached; never drops below zero. */
+  fun release() {
+    count.updateAndGet { if (it > 0) it - 1 else 0 }
+  }
+
+  @VisibleForTesting
+  fun reset() {
+    count.set(0)
+  }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/Equalizer.kt

@@ -25,9 +25,7 @@ import com.margelo.nitro.core.Promise
  * The JS-facing methods that mutate state return `Promise<Unit>`
  * via `Promise.async` per the spec, but each delegates to a
  * synchronous `*Internal` method that owns the actual mutation.
- * Unit tests target the synchronous core; the async wrapper is a
- * JS-interface adapter and is exercised at integration via demo
- * Maestro.
+ * The async wrapper is a thin JS-interface adapter.
  *
  * Listener registries follow the same shape as other event
  * listeners on this lib: stable numeric IDs returned via the

package/android/src/main/java/com/margelo/nitro/queueplayer/HeadlessJsMediaService.kt

@@ -141,8 +141,7 @@ public abstract class HeadlessJsMediaService :
   /**
    * The host's [ReactHost]. Returns `null` when the host
    * `Application` does not implement [ReactApplication] — production
-   * Expo / RN consumers always do; the null branch covers the
-   * Robolectric / unit-test path where the application is a stub.
+   * Expo / RN consumers always do.
    */
   protected val reactHost: ReactHost?
     get() = (application as? ReactApplication)?.reactHost
@@ -151,8 +150,7 @@ public abstract class HeadlessJsMediaService :
    * The live [ReactContext] from the consumer app's [ReactHost], or
    * `null` when no context has been created yet (the service kicks
    * one off via [createReactContextAndScheduleTask] in that case) OR
-   * when the host application isn't a [ReactApplication] at all (e.g.
-   * unit-test stubs).
+   * when the host application isn't a [ReactApplication] at all.
    */
   protected val reactContext: ReactContext?
     get() = reactHost?.currentReactContext

package/android/src/main/java/com/margelo/nitro/queueplayer/LookaheadCacheWriter.kt

@@ -285,9 +285,8 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
    * cache state.
    *
    * `runCatching` swallows the "Method myLooper in android.os.Looper
-   * not mocked" exception that fires under plain-JUnit (the writer's
-   * pure-orchestration tests deliberately avoid Robolectric to stay
-   * fast); production reads the looper normally.
+   * not mocked" exception that fires on a JVM host without the Android
+   * framework present; production reads the looper normally.
    */
   private fun requireMainThread() {
     val onMain = runCatching {
@@ -429,12 +428,11 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
         // Errors (OutOfMemoryError etc.) propagate — those are
         // not transient and shouldn't be hidden.
         //
-        // Log via runCatching: android.util.Log is not stubbed in
-        // plain-JUnit test runs (the writer's pure-orchestration
-        // tests deliberately avoid Robolectric), so a Log.w call
-        // would throw "Method w in android.util.Log not mocked"
-        // and terminate the prefetch loop. Production reads this
-        // log normally; tests get a silent no-op.
+        // Log via runCatching: on a JVM host without the Android
+        // framework present, android.util.Log is not stubbed, so a
+        // Log.w call would throw "Method w in android.util.Log not
+        // mocked" and terminate the prefetch loop. Production reads
+        // this log normally.
         runCatching { Log.w(TAG, "Lookahead prefetch failed for ${track.url}: ${e.message}") }
       }
 

package/android/src/main/java/com/margelo/nitro/queueplayer/MilestoneTracker.kt

@@ -2,8 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Tracks fixed playback-progress milestones (25/50/75/90%) for the
- * current track playthrough. Pure + deterministic (no Media3), so it
- * unit-tests directly.
+ * current track playthrough. Pure + deterministic (no Media3).
  *
  * A threshold emits only when forward playback crosses it: [seek] moves
  * the baseline WITHOUT emitting (so thresholds a seek jumps over are

package/android/src/main/java/com/margelo/nitro/queueplayer/NotificationProvider.kt

@@ -18,6 +18,12 @@ import androidx.media3.session.DefaultMediaNotificationProvider
  * `setMediaButtonPreferences(...)` builder call; this provider reads
  * those preferences directly.
  *
+ * This provider only pins the channel + notification id — it does NOT
+ * restyle transport buttons. On API 33+ the System UI media control is
+ * derived from the media session, so `MediaNotification.Provider` layout
+ * changes take effect only pre-33; transport customization belongs in the
+ * session's available commands + media button preferences, never here.
+ *
  * Artwork loading is wired separately on the [androidx.media3.session.MediaSession]
  * via `setBitmapLoader(...)` — the provider routes artwork requests
  * through that loader chain

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackService.kt

@@ -150,8 +150,8 @@ class PlaybackService : HeadlessJsMediaService() {
      * [PendingIntentBuffer] TTL: ~3 s for bridge boot + ~17 s of
      * headroom for the consumer's network calls before the controller
      * surfaces "no results" and the user retries. The two platforms'
-     * cold-start windows are deliberately the same so the manual
-     * playbook reads identically on iPhone + Android.
+     * cold-start windows are deliberately kept the same so the
+     * behaviour is identical on iPhone + Android.
      */
     private const val HEADLESS_DISPATCH_TIMEOUT_MS = 20_000L
 
@@ -788,20 +788,18 @@ class PlaybackService : HeadlessJsMediaService() {
     )
 
   /**
-   * The compact notification view shows three buttons in priority
-   * order: prev / play-pause / next. Media3 1.9+ resolves these from
-   * standard player commands set via [CommandButton.Builder.setPlayerCommand]
-   * — no custom command handlers required. The expanded view shows
-   * the same three buttons plus the scrub progress bar that
-   * `DefaultMediaNotificationProvider` adds automatically when the
-   * session reports a known duration.
+   * The back + forward buttons for the notification compact view and the
+   * Android Auto control row. Play/pause is intentionally NOT supplied:
+   * Media3 owns the central slot (`CommandButton.SLOT_CENTRAL`) and
+   * synthesizes a state-aware play/pause from `COMMAND_PLAY_PAUSE`. A
+   * caller-supplied central button is dropped on the notification path
+   * (`DefaultMediaNotificationProvider` builds its own play/pause) and on
+   * Android Auto forces a static, non-toggling icon — so supplying only
+   * back/forward lets Media3 render the toggling play/pause on both
+   * surfaces. The expanded view adds the scrub progress bar automatically
+   * when the session reports a known duration.
    */
   private fun buildMediaButtonPreferences(): List<CommandButton> {
-    val playPause = CommandButton.Builder(CommandButton.ICON_PLAY)
-      .setPlayerCommand(Player.COMMAND_PLAY_PAUSE)
-      .setSlots(CommandButton.SLOT_CENTRAL)
-      .setDisplayName(getString(R.string.rnqp_action_play_pause))
-      .build()
     // In `interval` mode the back/forward slots jump within the current track
     // (COMMAND_SEEK_BACK / COMMAND_SEEK_FORWARD, honored by
     // [SessionCommandForwardingPlayer] with the runtime interval); in `track`
@@ -813,7 +811,6 @@ class PlaybackService : HeadlessJsMediaService() {
           .setSlots(CommandButton.SLOT_BACK)
           .setDisplayName(getString(R.string.rnqp_action_jump_backward))
           .build(),
-        playPause,
         CommandButton.Builder(CommandButton.ICON_SKIP_FORWARD)
           .setPlayerCommand(Player.COMMAND_SEEK_FORWARD)
           .setSlots(CommandButton.SLOT_FORWARD)
@@ -826,7 +823,6 @@ class PlaybackService : HeadlessJsMediaService() {
           .setSlots(CommandButton.SLOT_BACK)
           .setDisplayName(getString(R.string.rnqp_action_previous))
           .build(),
-        playPause,
         CommandButton.Builder(CommandButton.ICON_NEXT)
           .setPlayerCommand(Player.COMMAND_SEEK_TO_NEXT)
           .setSlots(CommandButton.SLOT_FORWARD)
@@ -1455,10 +1451,9 @@ class PlaybackService : HeadlessJsMediaService() {
   override fun getTaskConfig(intent: Intent?): com.facebook.react.jstasks.HeadlessJsTaskConfig? {
     val action = intent?.action ?: return null
     if (action !in HEADLESS_WAKE_ACTIONS) return null
-    // Robolectric / non-ReactApplication hosts cannot spawn a JS
-    // task — short-circuit here so `Arguments.createMap()` never
-    // has to load the React native libs that aren't on the test
-    // classpath.
+    // Non-ReactApplication hosts cannot spawn a JS task —
+    // short-circuit here so `Arguments.createMap()` never has to load
+    // the React native libs such a host lacks.
     if ((application as? com.facebook.react.ReactApplication) == null) return null
     // Belt-and-braces: if a wake intent somehow lands while a React
     // context is already alive (foreground app, prior wake already
@@ -1621,6 +1616,13 @@ class PlaybackService : HeadlessJsMediaService() {
       // Once both are zero, AA lands on the Library/Browse surface
       // instead of "Now Playing — To play something, tap the icon at
       // the top left."
+      //
+      // This rides Media3 1.10.0's internal Player.Commands →
+      // PlaybackStateCompat action-mask translation, which is not a public
+      // contract — re-validate on a Media3 upgrade. Unit tests cover the
+      // command-strip input; the resulting action mask is verified on the
+      // Android Auto lane, since the legacy bridge only populates for a
+      // connected controller that can't be driven under Robolectric.
       builder.remove(Player.COMMAND_PLAY_PAUSE)
       builder.remove(Player.COMMAND_PREPARE)
       builder.remove(Player.COMMAND_STOP)
@@ -1647,11 +1649,11 @@ class PlaybackService : HeadlessJsMediaService() {
   /**
    * Hook the [PlaybackCallback] consults before letting Media3 route
    * a controller-initiated command to the bound player. Calls run on
-   * the service main looper. Skip-next / skip-previous return true
-   * when the implementation has handled the skip itself, so the
-   * default routing is suppressed; the transport hook fires for play /
-   * pause / seek / setPlaybackSpeed and is purely a side-channel
-   * notification (no return value).
+   * the service main looper. Skip-next / skip-previous / seek-to-queue-item
+   * return true when the implementation has handled the command itself,
+   * so the default routing is suppressed; the transport hook fires for
+   * play / pause / in-item seek / setPlaybackSpeed and is purely a
+   * side-channel notification (no return value).
    */
   internal interface MediaSessionCommandHandler {
     /** Stamps `system` on the state-change channel for the upcoming
@@ -1663,6 +1665,12 @@ class PlaybackService : HeadlessJsMediaService() {
     /** Returns true if the lib intercepted the skip and the default
      *  routing should be suppressed. */
     fun onSkipToPreviousCommand(): Boolean
+    /** Routes an external controller's tap on a queue row (Android Auto's
+     *  "seek to this item") through the lib's `skipToIndex` path so the
+     *  canonical current index + track-change reason land. Returns true
+     *  when handled so the default per-item seek is suppressed; returns
+     *  false for an out-of-range index so the default routing no-ops it. */
+    fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean
 
     /**
      * Returns the lib's current authoritative skip capability —

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackServiceCallback.kt

@@ -73,7 +73,7 @@ internal class PlaybackServiceCallback(
      *  package (Android Auto, Wear OS, Google Assistant) connects.
      *  Production wires the React-context cold-start through here so
      *  "Hey Google, play …" works from a phone with the app killed.
-     *  Default no-op so unit-test setups without a service can fall
+     *  Default no-op so callers without a wired service fall
      *  through harmlessly. */
     fun onHeadlessControllerConnect(packageName: String) {}
 
@@ -287,6 +287,9 @@ internal class PlaybackServiceCallback(
   ): MediaSession.ConnectionResult {
     if (controller.packageName in HEADLESS_ELIGIBLE_PACKAGES) {
       val previousCount = headlessControllerCount.getAndIncrement()
+      // A headless controller is now attached — record it in the process-wide
+      // count the `isCarConnected()` getter reads.
+      CarConnectionState.retain()
       environment.onHeadlessControllerConnect(controller.packageName)
       // Fire onCarConnect only on the FIRST headless controller of
       // this service-lifetime session — subsequent connects (Wear
@@ -348,6 +351,10 @@ internal class PlaybackServiceCallback(
       } else if (previousCount > 0 && remaining == 0) {
         environment.onHeadlessControllerDisconnect()
       }
+      // Drop this controller from the process-wide connection count the
+      // `isCarConnected()` getter reads (floor-guarded against a stray
+      // disconnect, so it can't go negative).
+      CarConnectionState.release()
     }
     super.onDisconnected(session, controller)
   }
@@ -361,6 +368,14 @@ internal class PlaybackServiceCallback(
     return dispatch.handle(intent, RemoteCommandDeduper.Channel.SESSION_KEY)
   }
 
+  /**
+   * Cold-start playback resumption: a hardware / Bluetooth media button that
+   * wakes the service while nothing is loaded. Returns an empty queue by
+   * design — the lib does not reconstruct a queue here; a consumer that wants
+   * resume-from-cold restores its own queue on launch via `setQueue`. The
+   * override exists (rather than being omitted) because Media3 requires a
+   * declared `MediaButtonReceiver` to pair with an `onPlaybackResumption`.
+   */
   override fun onPlaybackResumption(
     mediaSession: MediaSession,
     controller: MediaSession.ControllerInfo,

package/android/src/main/java/com/margelo/nitro/queueplayer/ProgressEmissionGate.kt

@@ -3,7 +3,7 @@ package com.margelo.nitro.queueplayer
 /**
  * Throttles the JS `onProgress` fan-out to a configurable cadence, with an
  * optional reduced rate while the app is backgrounded. Pure + deterministic
- * (the caller supplies a monotonic timestamp), so it unit-tests directly.
+ * (the caller supplies a monotonic timestamp).
  *
  * This gates ONLY the JS emission — the native 2 Hz sampler keeps running, so
  * milestone detection and buffer-state recomputation stay full-rate. A tick

package/android/src/main/java/com/margelo/nitro/queueplayer/QueueMutationArithmetic.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
- * from [TrackPlayer] so the shift semantics are unit-testable without
+ * from [TrackPlayer] so the shift semantics stand alone without
  * an ExoPlayer. Mirrors (and lightly supersedes) the inline math
  * inside iOS `TrackPlayer.swift`'s `addToQueueBody` /
  * `removeFromQueueBody` / `moveInQueueBody` — the iOS backlog carries

package/android/src/main/java/com/margelo/nitro/queueplayer/QueueSkipArithmetic.kt

@@ -4,7 +4,7 @@ package com.margelo.nitro.queueplayer
  * Pure-Kotlin skip-index arithmetic. Mirrors the iOS sibling
  * `ios/QueueSkipArithmetic.swift` 1-for-1.
  *
- * Extracted from [TrackPlayer] so the logic is unit-testable without
+ * Extracted from [TrackPlayer] so the logic stands alone without
  * instantiating an ExoPlayer. [TrackPlayer.computeNextIndex] /
  * [TrackPlayer.computePreviousIndex] are thin adapters that translate
  * the Nitrogen-generated [RepeatMode] enum into [QueueSkipRepeatMode]

package/android/src/main/java/com/margelo/nitro/queueplayer/RemoteCommandDeduper.kt

@@ -29,7 +29,7 @@ package com.margelo.nitro.queueplayer
  *
  * Bias is toward emitting: when in doubt, act rather than swallow a real press.
  *
- * Pure and time-injected ([nowUptimeMs] is passed in) so it unit-tests without an
+ * Pure and time-injected ([nowUptimeMs] is passed in), so it needs no
  * Android runtime. [shouldEmit] is `@Synchronized` so it is safe regardless of
  * which thread an emit site runs on (today they are all main-thread-confined).
  */

package/android/src/main/java/com/margelo/nitro/queueplayer/SessionCommandForwardingPlayer.kt

@@ -89,6 +89,15 @@ internal class SessionCommandForwardingPlayer(
       Player.COMMAND_SEEK_TO_PREVIOUS_MEDIA_ITEM ->
         if (commandHandler()?.onSkipToPreviousCommand() == true) Futures.immediateVoidFuture()
         else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
+      // Android Auto's queue-row tap. A raw per-item seek would move the
+      // player without updating the lib's canonical current index — the
+      // SEEK transition handler only syncs the index for player-originated
+      // transitions, not controller seeks. Route through the skip path so
+      // the index + track-change reason land; an index the lib declines
+      // (out of range) falls through to the default seek.
+      Player.COMMAND_SEEK_TO_MEDIA_ITEM ->
+        if (commandHandler()?.onSeekToMediaItemCommand(mediaItemIndex) == true) Futures.immediateVoidFuture()
+        else super.handleSeek(mediaItemIndex, positionMs, seekCommand)
       // Interval-skip mode: recompute the target with the runtime jump interval
       // rather than the wrapped player's build-time seek increment, so the value
       // is adjustable at runtime.

package/android/src/main/java/com/margelo/nitro/queueplayer/SleepTimerCore.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure state machine for the sleep timer — no player, volume, or handler
- * dependencies, so it is unit-testable in isolation. The owning [TrackPlayer]
+ * dependencies, so it stands alone. The owning [TrackPlayer]
  * drives it from a repeating main-looper runnable and applies the returned
  * decision (volume fade, pause) to the engine.
  *

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -46,10 +46,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // --- Stored state
   //
   // Mirrors iOS TrackPlayer.swift's "Stored state" block. Field
-  // visibility is `internal` + `@VisibleForTesting` so Robolectric
-  // tests can observe lifecycle transitions without going through
-  // the JNI-backed Nitro Promise machinery (which does not load in
-  // the JVM unit-test runtime).
+  // visibility is `internal` + `@VisibleForTesting` so lifecycle
+  // transitions can be observed without going through the JNI-backed
+  // Nitro Promise machinery (which does not load on a plain JVM).
 
   /**
    * `true` after [configureInternal] has bound + configured the
@@ -158,8 +157,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var lastEmittedFormatMediaItem: MediaItem? = null
 
   // The fields below are written on main (via `onMain` / `syncMain`
-  // from the Promise adapter path, or directly from Robolectric tests
-  // which run on main). They are read off-main by the synchronous
+  // from the Promise adapter path). They are read off-main by the synchronous
   // snapshot accessors — `getCurrentTrackIndex`, `getQueue` —
   // dispatched on the JS thread by Nitro. `@Volatile` gives the
   // read path a happens-before edge on the most recent main-thread
@@ -581,7 +579,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private val progressEmissionGate = ProgressEmissionGate()
   // ProcessLifecycleOwner observer driving the gate's background state. Held in
   // a nullable field so a re-configureInternal without an intervening
-  // destroyInternal (Robolectric) is a no-op instead of leaking a second
+  // destroyInternal is a no-op instead of leaking a second
   // observer. Registered in configureInternal, removed in destroyInternal.
   private var progressLifecycleObserver: DefaultLifecycleObserver? = null
   private val errorListeners = ListenerRegistry<(PlaybackError) -> Unit>()
@@ -866,11 +864,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Lifecycle configure body. `internal` so Robolectric tests can
-   * exercise it without the Nitro Promise path. Callers MUST hop
-   * to the main thread first — ExoPlayer construction binds to the
-   * calling Looper. Production path goes through `onMain`; tests
-   * run on Robolectric's main-thread dispatcher.
+   * Lifecycle configure body. `internal`, bypassing the Nitro Promise
+   * path. Callers MUST hop to the main thread first — ExoPlayer
+   * construction binds to the calling Looper. Production path goes
+   * through `onMain`.
    *
    * Builds the ExoPlayer with a [MediaSource.Factory] that attaches
    * the config's HTTP headers + User-Agent on every network request.
@@ -879,9 +876,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * Per the universal auto-destroy contract every `configure()` call
    * tears the player down upstream so this body is purely
    * constructive — `player` is guaranteed null on entry from the
-   * production path. Robolectric tests that drive `configureInternal`
-   * directly are responsible for calling `destroyInternal` first
-   * between configures.
+   * production path. Any caller driving `configureInternal` directly
+   * must call `destroyInternal` first between configures.
    */
   @VisibleForTesting
   @MainThread
@@ -995,6 +991,25 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         return true
       }
 
+      override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean {
+        // Decline an out-of-range index so the default per-item seek
+        // no-ops it (Media3 passes C.INDEX_UNSET when the seek implies
+        // no move).
+        if (mediaItemIndex < 0 || mediaItemIndex >= tracks.size) return false
+        pendingStateChangeReason = StateChangeReason.SYSTEM
+        // Same path as the public skipToIndex: jump the receiver while
+        // casting, else the local engine. Both write currentTrackIndex +
+        // the USER_SKIP_TO_INDEX reason that a raw controller seek skips.
+        // The tapped track starts at position 0 — the controller's
+        // positionMs is intentionally not threaded through, matching the
+        // public skipToIndex "play this track" contract.
+        if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSkipToIndex(mediaItemIndex)) {
+          return true
+        }
+        skipToIndexInternal(mediaItemIndex)
+        return true
+      }
+
       override fun onMediaPlay() {
         pendingStateChangeReason = StateChangeReason.SYSTEM
         serviceBinder?.engine?.play()
@@ -2442,9 +2457,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   /**
    * Main-thread body for [setPlaybackSpeed]. The engine applies the
    * active pitch-correction mode's pitch alongside the speed (voice/music
-   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`
-   * so Robolectric exercises the cast + speed-application logic rather than
-   * just bypassing through `ExoPlayer.playbackParameters`.
+   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`;
+   * centralizes the cast + speed-application logic rather than routing
+   * straight through `ExoPlayer.playbackParameters`.
    *
    * Diverges from iOS: on iOS `player.rate = Float(rate)` implicitly
    * starts playback when the player was paused. Android's
@@ -3032,6 +3047,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun onCarDisconnect(callback: () -> Unit): () -> Unit =
     deferredRegister { it.registerOnCarDisconnect(callback) }
 
+  override fun isCarConnected(): Boolean = CarConnectionState.isConnected()
+
   override fun onServiceReady(
     callback: (reason: ServiceReadyReason) -> Unit
   ): () -> Unit = deferredRegister { it.registerOnServiceReady(callback) }
@@ -4157,11 +4174,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: stash a [TrackChangeReason] that the next
+   * Stash a [TrackChangeReason] that the next
    * [handleMediaItemTransition] with `REASON_SEEK` will consume.
-   * Production code reaches this field via `skipTo*Internal`
-   * bodies; the hook just lets Robolectric tests simulate the
-   * stash without driving a real skip + ExoPlayer seek.
+   * Production code reaches this field via `skipTo*Internal` bodies.
    */
   @VisibleForTesting
   internal fun setPendingTrackChangeReasonForTest(reason: TrackChangeReason?) {
@@ -4169,9 +4184,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: reset the [lastReportedState] dedup edge so
-   * [emitStateIfChanged] tests can force an emit from an already-
-   * NONE state without going through a real Player.Listener fire.
+   * Reset the [lastReportedState] dedup edge, forcing [emitStateIfChanged]
+   * to emit from an already-NONE state without a real Player.Listener fire.
    */
   @VisibleForTesting
   internal fun resetLastReportedStateForTest() {
@@ -4250,8 +4264,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     /**
      * Decide which [ServiceReadyReason] (if any) to dispatch on a
-     * fresh service-bind. Pure function so the reason-decision logic
-     * is unit-testable without spinning up a service controller.
+     * fresh service-bind. Pure function — no service controller needed.
      *
      *  - First-ever bind ([prior] == null): [ServiceReadyReason.FIRST_BIND].
      *  - Bind against a different binder identity:

package/android/src/main/java/com/margelo/nitro/queueplayer/TransportStateTranslator.kt

@@ -7,8 +7,8 @@ import androidx.media3.common.Player
  * isPlaying, playWhenReady, playbackSuppressionReason, hasTracks,
  * currentTrackIndex)` tuple to the library's [PlayerState] enum.
  *
- * Extracted from [TrackPlayer.getStateInternal] so every branch is
- * unit-testable without a live ExoPlayer. Matches the pattern of
+ * Extracted from [TrackPlayer.getStateInternal] so every branch
+ * stands alone without a live ExoPlayer. Matches the pattern of
  * [QueueSkipArithmetic] + [QueueMutationArithmetic] — TrackPlayer
  * is a thin adapter that reads the live player's state and
  * delegates the translation here.

package/android/src/main/res/values/strings.xml

@@ -11,9 +11,6 @@
        transport button. Shown by TalkBack and by pre-Media3 controllers
        that read the platform PlaybackStateCompat custom-action name. -->
   <string name="rnqp_action_previous">Previous</string>
-  <!-- Accessibility / legacy-controller label for the play-pause
-       transport button. -->
-  <string name="rnqp_action_play_pause">Play or pause</string>
   <!-- Accessibility / legacy-controller label for the next-track
        transport button. -->
   <string name="rnqp_action_next">Next</string>

package/android/src/test/java/com/margelo/nitro/queueplayer/AudioPipelineRenderersFactoryTest.kt

@@ -14,12 +14,9 @@ import java.lang.reflect.Field
 /**
  * Unit coverage for [AudioPipelineRenderersFactory] construction — it wraps a
  * caller-supplied [androidx.media3.common.audio.AudioProcessorChain] and leaves
- * the produced sink at 16-bit (float output off). The engines drive end-to-end exercise of
- * `buildAudioSink` via `ExoPlayer.Builder.build()` in
- * [GaplessEngineLifecycleTest] / [CrossfadeEngineLifecycleTest]; `buildAudioSink`
+ * the produced sink at 16-bit (float output off). `buildAudioSink`
  * itself is `protected` on [DefaultRenderersFactory] and cannot be called
- * outside the Media3 internal call path. Chain composition + order is covered by
- * [PitchAwareAudioProcessorChainTest].
+ * outside the Media3 internal call path.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

package/android/src/test/java/com/margelo/nitro/queueplayer/AvrcpMetadataTest.kt

@@ -252,6 +252,7 @@ class AvrcpMetadataTest {
     override fun onTransportCommand() {}
     override fun onSkipToNextCommand(): Boolean = false
     override fun onSkipToPreviousCommand(): Boolean = false
+    override fun onSeekToMediaItemCommand(mediaItemIndex: Int): Boolean = false
     override fun getCachedSkipCapability(): SkipCapability = capability
     override fun onMediaPlay() {}
     override fun onMediaPause() {}

package/android/src/test/java/com/margelo/nitro/queueplayer/BrowseCallbackRegistryTest.kt

@@ -9,10 +9,7 @@ import org.junit.Test
 /**
  * Pure-Kotlin coverage for [BrowseCallbackRegistry]'s slot-replace
  * + dispose semantics. The Promise-typed callbacks are stored as
- * function references; tests use simple stand-in lambdas — actual
- * dispatch coverage lives at the integration layer
- * (`PlaybackServiceCallbackSearchTest` for the search dispatch
- * path; future Maestro flows for end-to-end Auto cold-wake).
+ * function references; tests use simple stand-in lambdas.
  */
 @UnstableApi
 class BrowseCallbackRegistryTest {

package/android/src/test/java/com/margelo/nitro/queueplayer/CrossfadeEngineLifecycleTest.kt

@@ -15,8 +15,7 @@ import org.robolectric.annotation.Config
 /**
  * Lifecycle + fade-math coverage for [CrossfadeEngine].
  *
- * Audible verification of the dual-player crossfade runs at the
- * Maestro / demo-app integration layer; this suite exercises:
+ * This suite exercises:
  * empty-state sentinels, role-swap arithmetic, equal-power gain
  * curve, duration-clamp formula, manual-skip cancellation,
  * release idempotence + delegate clearing.

package/android/src/test/java/com/margelo/nitro/queueplayer/CrossfadeEngineReplayGainTest.kt

@@ -24,9 +24,7 @@ import org.robolectric.annotation.Config
  * Media3 metadata dispatch is not emulated by Robolectric without
  * playback, so the listener body composes its work through the
  * engine-internal `handleReplayGainParse(isA, parsed)` helper which
- * these tests drive directly with synthetic [ReplayGainData]. The
- * pure-math piece is covered in [ReplayGainGainTest]; end-to-end
- * propagation lands in the demo app's `replaygain` Maestro suite.
+ * these tests drive directly with synthetic [ReplayGainData].
  * This file covers the no-data baseline + the per-leg
  * `handleReplayGainParse` cache + recompute contract.
  */
@@ -173,8 +171,6 @@ class CrossfadeEngineReplayGainTest {
 
   // The per-leg cache-clear-on-transition path lives inline in each
   // leg's `Player.Listener.onMediaItemTransition` body. Robolectric
-  // does not drive that callback without real playback; integration
-  // coverage is in `RNQP-Demo/src/tests/suites/replaygain.ts` (steps
-  // `cross-track-active-updates` +
-  // `skip-next-mid-playback-resets-from-stale-cache`).
+  // does not drive that callback without real playback, so it is out
+  // of scope here.
 }

package/android/src/test/java/com/margelo/nitro/queueplayer/EqualizerEngineTest.kt

@@ -13,8 +13,7 @@ import org.robolectric.annotation.Config
 /**
  * State-mirror coverage for [EqualizerEngine] on the API 28+ path.
  * Robolectric stubs the audio-effect subsystem at this SDK level so
- * `attach` exercises the construction path without throwing; the
- * audible effect is verified at integration via demo Maestro.
+ * `attach` exercises the construction path without throwing.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])