react-native-queue-player 1.1.2 → 2.0.0

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

@@ -9,40 +9,29 @@ import androidx.media3.exoplayer.audio.TeeAudioProcessor
 /**
  * Strategy abstraction over the audio output pipeline.
  *
- * Two concrete implementations:
+ * Three concrete implementations:
  *  - [GaplessEngine]: single ExoPlayer, native gapless via item chaining.
  *  - [CrossfadeEngine]: dual ExoPlayer with equal-power gain ramping at
  *    track boundaries.
+ *  - [AirPlayEngine]: single ExoPlayer bound to an AirPlay PCM sink;
+ *    selected by `applyEngineSwapForMode` while an AirPlay session is
+ *    active.
  *
  * The engine owns the player instance(s), audio-thread effects, and
  * track-boundary scheduling. The lib's [TrackPlayer] holds the canonical
  * queue model + listener registries + system-side surfaces (NowPlaying,
  * RemoteCommands, AudioSession) and routes transport / queue calls
- * through whichever engine is active. Engine swap (gapless ↔ crossfade)
- * is a `handoff` at the next track boundary.
+ * through whichever engine is active. An engine swap (gapless ↔ crossfade)
+ * is `TrackPlayer.applyEngineSwapForMode`: [PlaybackService.swapEngine]
+ * installs the new engine and releases the old one, then `TrackPlayer`
+ * seeds the new engine through [setMediaItems].
  *
  * Threading: all methods are called on the service main looper unless
- * noted. `suspend` methods are launched on the same dispatcher; the
- * impl is responsible for any internal off-loop work (e.g. heavy
- * lookahead-cache prefetch).
+ * noted; the impl is responsible for any internal off-loop work (e.g.
+ * heavy lookahead-cache prefetch).
  */
 interface PlaybackEngine {
 
-  /**
-   * Build the underlying player(s), apply [mediaItems] starting at
-   * [startIndex] / [startPositionMs], and wait for the underlying
-   * player(s) to reach a playable state.
-   *
-   * Empty [mediaItems] is allowed; the engine prepares an empty
-   * timeline and [currentMediaItemIndex] returns `-1` until items
-   * arrive via [setMediaItems] / [addMediaItems].
-   */
-  suspend fun prepare(
-    mediaItems: List<MediaItem>,
-    startIndex: Int,
-    startPositionMs: Long,
-  )
-
   /**
    * Release the underlying player(s) and stop all background work.
    * After [release], no further methods are valid.
@@ -127,20 +116,16 @@ interface PlaybackEngine {
   val allMediaItems: List<MediaItem>
 
   /**
-   * Underlying ExoPlayer instance the service-level wiring
-   * (audio-focus listener, `MediaSession.setPlayer`) attaches
-   * to. `GaplessEngine` returns its single player; `CrossfadeEngine`
+   * Underlying ExoPlayer for the audio-focus listener and the
+   * `MediaSession` binding. `GaplessEngine` returns its single
+   * player, which [PlaybackService] binds directly; `CrossfadeEngine`
    * returns the leading leg's player.
    *
-   * Mid-fade role swap inside `CrossfadeEngine` flips which
-   * underlying player this getter returns, but the
-   * `MediaSession` currently bound by `PlaybackService.swapEngine`
-   * does NOT auto-rebind — `MediaSession.setPlayer` is invoked
-   * once per engine swap, not per fade midpoint. The
-   * `CrossfadeForwardingPlayer` wrapper exists to bridge that
-   * gap (re-target the bound delegate via `setPlayer` on every
-   * role swap); wiring lands when [PlaybackService] starts
-   * binding through the wrapper for crossfade engines.
+   * A mid-fade role swap inside `CrossfadeEngine` flips which player this
+   * getter returns, and nothing re-reads it: [PlaybackService] binds a
+   * crossfade engine through a [CrossfadeForwardingPlayer] instead, which
+   * re-targets via `setPlayer` on every role swap, fade start and fade
+   * cancel, so the session and the focus listener follow the audible leg.
    */
   val mediaSessionPlayer: ExoPlayer
 
@@ -176,12 +161,36 @@ interface PlaybackEngine {
   fun detachAudioBufferSink(sink: TeeAudioProcessor.AudioBufferSink)
 
   /**
-   * Snapshot the active item's cached [ReplayGainData], or `null`
-   * when no usable RG tags have been parsed yet. Surfaced by
-   * [NowPlayingFormatExtractor] to populate the four
-   * `replayGain*Db` / `replayGain*Peak` fields. Default returns
-   * `null` so engines without RG wiring (future stub variants)
-   * compile without a no-op override.
+   * Settle any in-flight or armed crossfade so the queue can be mutated by
+   * something other than this engine.
+   *
+   * An armed standby leg holds a snapshot of the queue taken when it was
+   * armed. A caller that appends or replaces items through a path the engine
+   * does not see — Media3 setting them on the session player after resolving
+   * an assistant request — leaves that snapshot stale, and promoting it drops
+   * whatever the caller added. Default is a no-op: an engine with one player
+   * has nothing to settle.
+   */
+  fun settlePendingFade() {}
+
+  /**
+   * Settle an in-flight fade by promoting the incoming leg, so the leg a
+   * caller reads is the track actually being heard.
+   *
+   * Mid-fade the leading leg holds the outgoing track while the canonical
+   * index names the incoming one, so a caller that reads the player and the
+   * index together sees two different tracks. Promoting resolves them to the
+   * incoming track, which is the one the listener is arriving at. Default is a
+   * no-op: an engine with one player is never in this state.
+   */
+  fun settlePendingFadeByPromoting() {}
+
+  /**
+   * Snapshot the active item's cached [ReplayGainData], or `null` when no
+   * usable RG tags have been parsed yet. Surfaced by
+   * [NowPlayingFormatExtractor] to populate the four `replayGain*Db` /
+   * `replayGain*Peak` fields. The default is `null`, for an engine that
+   * reads no tags.
    */
   fun currentReplayGainData(): ReplayGainData? = null
 
@@ -194,43 +203,22 @@ interface PlaybackEngine {
    */
   fun currentReplayGainActive(): Boolean = false
 
-  /**
-   * Hand playback off to [nextEngine] when the user changes
-   * `PlaybackMode`.
-   *
-   * Contract:
-   *  - The receiver inherits the donor's queue, current index, and
-   *    current position; the caller does NOT pre-call [prepare] on
-   *    [nextEngine].
-   *  - When [atTrackBoundary] is `true`, the donor plays the active
-   *    track to its natural end and the receiver starts playing the
-   *    NEXT queue position fresh.
-   *  - When [atTrackBoundary] is `false` (idle player or empty
-   *    queue), the swap is immediate; receiver picks up at the
-   *    inherited position.
-   *  - The donor's [release] is the caller's responsibility AFTER
-   *    the boundary fires; the engine itself does not self-release.
-   *  - The donor's listeners on [delegate] continue firing until
-   *    [release] runs; the caller swaps the delegate before that.
-   */
-  suspend fun handoff(to: PlaybackEngine, atTrackBoundary: Boolean)
-
   /**
    * Single delegate receiving state / track / progress / error /
    * queue-end events. TrackPlayer is the canonical delegate; engines
    * fire on the service main looper.
    *
-   * Strong reference by design; the iOS counterpart uses a weak
-   * reference because the AVQueuePlayer-driven engine sits inside
-   * the same actor as TrackPlayer and Swift's reference graph would
-   * otherwise close (TrackPlayer → engine → delegate → TrackPlayer).
-   * On Android the engine lives inside [PlaybackService.serviceBinder]
-   * which is owned by the service lifecycle, not by TrackPlayer; the
-   * cycle is broken explicitly by [release] dropping `delegate` and
-   * by [TrackPlayer.tearDownEventObservers] dropping the binder.
+   * Strong reference by design; the iOS counterpart is `weak` because
+   * `TrackPlayer` owns its engine strongly and Swift's reference graph
+   * would otherwise close (TrackPlayer → engine → delegate → TrackPlayer).
+   * On Android the engine lives inside [PlaybackService], reached through
+   * [PlaybackService.LocalBinder.engine] and owned by the service
+   * lifecycle, not by TrackPlayer; the cycle is broken explicitly by
+   * [release] dropping `delegate` and by `TrackPlayer.tearDownEventObservers`
+   * clearing itself from the engine's `delegate`.
    *
    * Threading: setter MUST be invoked on the service main looper to
-   * avoid a write-vs-fire race during [handoff].
+   * avoid a write-vs-fire race during an engine swap.
    */
   var delegate: PlaybackEngineDelegate?
 }
@@ -290,10 +278,14 @@ interface PlaybackEngineDelegate {
   fun onActiveItemFormatChanged(engine: PlaybackEngine)
 
   /**
-   * Fires on Media3 `Player.Listener.onPlayerError`. The delegate
-   * maps [exception] via the lib's `PlaybackErrorMapping`.
+   * Fires on Media3 `Player.Listener.onPlayerError`. The delegate maps
+   * [exception] via the lib's `PlaybackErrorMapping`. [failedIndex] is the
+   * queue position of the item that failed, or -1 when the engine cannot
+   * attribute it. A crossfade engine can fail on its standby leg while the
+   * leading leg plays on, so the failure need not belong to the track the
+   * delegate considers current.
    */
-  fun onError(engine: PlaybackEngine, exception: PlaybackException)
+  fun onError(engine: PlaybackEngine, exception: PlaybackException, failedIndex: Int = -1)
 
   /**
    * Fires on Media3 `Player.STATE_ENDED`. The delegate consults the
@@ -316,9 +308,10 @@ interface PlaybackEngineDelegate {
    * [ExoPlayer] has started playback at volume 0 and the leading
    * leg's fade-out has begun. The delegate treats this as the
    * canonical "active track changed" trigger and emits
-   * `onTrackChange` + repoints `MediaSessionCompat` to the
-   * incoming track. The subsequent `onTrackTransition` for the
-   * same incoming index is a structural Media3 echo and must be
+   * `onTrackChange` for the incoming track; the `MediaSession` re-bind
+   * to the standby leg is [CrossfadeForwardingPlayer]'s, through the
+   * engine's `onCrossfadeBegin` lambda. The subsequent `onTrackTransition`
+   * for the same incoming index is a structural Media3 echo and must be
    * deduplicated.
    *
    * Crossfade-only — [GaplessEngine] never invokes this.
@@ -333,7 +326,9 @@ interface PlaybackEngineDelegate {
    * mutation that invalidates the standby leg). The delegate
    * reverts JS-facing state to the leading leg — emit
    * `onTrackChange(reason: CROSSFADE_CANCELLED)` for the leading
-   * track + repoint `MediaSessionCompat` back. Pairs with
+   * track; the `MediaSession` re-bind back to the leading leg is
+   * [CrossfadeForwardingPlayer]'s, through the engine's
+   * `onCrossfadeCancel` lambda. Pairs with
    * [onCrossfadeBegin]: only fires when a `Begin` was fired
    * earlier and the fade did not complete.
    *

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

@@ -85,9 +85,9 @@ internal object PlaybackErrorMapping {
 
   /**
    * Strip query strings from a native error message so logged
-   * `nativeMessage` doesn't leak auth tokens (Subsonic-style
-   * `s=…&t=…` salt+token pairs in stream URLs end up inside
-   * `PlaybackException.message`).
+   * `nativeMessage` doesn't leak auth tokens: stream URLs with
+   * `?token=…`-style query strings end up inside
+   * `PlaybackException.message`.
    *
    * Walks the full message removing EVERY `?…(whitespace|end)` run
    * so multi-URL error messages have all query strings stripped.

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

@@ -49,8 +49,8 @@ internal class PlaybackModeStateMachine {
    * the new duration.
    *
    * The caller is responsible for managing the brief audio
-   * interruption (resume position carryover, queue re-attach,
-   * etc.) — that's the engine-handoff contract.
+   * interruption — `applyEngineSwapForMode` carries the position
+   * and re-installs the queue.
    */
   fun setRequested(
     state: State,

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

@@ -17,7 +17,6 @@ import android.os.IBinder
 import android.os.Looper
 import androidx.core.content.ContextCompat
 import androidx.annotation.VisibleForTesting
-import androidx.media3.common.C
 import androidx.media3.common.MediaItem
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
@@ -26,25 +25,17 @@ import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.exoplayer.source.MediaSource
 import androidx.media3.session.CacheBitmapLoader
 import androidx.media3.session.CommandButton
-import androidx.media3.session.LibraryResult
 import androidx.media3.session.MediaLibraryService
-import androidx.media3.session.MediaLibraryService.LibraryParams
 import androidx.media3.session.MediaLibraryService.MediaLibrarySession
 import androidx.media3.session.MediaSession
-import androidx.media3.session.SessionResult
-import com.google.common.collect.ImmutableList
-import com.google.common.util.concurrent.Futures
 import com.google.common.util.concurrent.ListenableFuture
 import com.google.common.util.concurrent.MoreExecutors
 import com.google.common.util.concurrent.SettableFuture
 import com.margelo.nitro.core.Promise
 import com.margelo.nitro.queueplayer.cast.PlaybackStateRouter
 import java.util.UUID
+import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.cancel
-import kotlinx.coroutines.currentCoroutineContext
-import kotlinx.coroutines.delay
-import kotlinx.coroutines.flow.collect
-import kotlinx.coroutines.isActive
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.withContext
 
@@ -147,7 +138,7 @@ class PlaybackService : HeadlessJsMediaService() {
      * resolve — covers (a) the JS bridge spinning up + the consumer's
      * `registerPlaybackService` running, AND (b) the consumer's
      * resolution Promise running. 20 s mirrors the iOS
-     * [PendingIntentBuffer] TTL: ~3 s for bridge boot + ~17 s of
+     * `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 kept the same so the
@@ -260,8 +251,8 @@ class PlaybackService : HeadlessJsMediaService() {
 
   /**
    * Per-query cache of JS-supplied search results. Populated by
-   * `TrackPlayer.setSearchResults` once the JS handler
-   * responds to a search request; read by
+   * [dispatchSearchToJs] once the JS `onSearchRequest` handler
+   * responds; read by
    * [PlaybackServiceCallback.onGetSearchResult]. Empty by default —
    * a controller's `getSearchResult` call before the JS responder
    * has answered returns an empty page.
@@ -315,7 +306,7 @@ class PlaybackService : HeadlessJsMediaService() {
       // Cold-wake the JS bridge so the consumer's
       // `registerPlaybackService` can fire its callbacks before
       // Media3's framework dispatches `onAddMediaItems`. Idempotent
-      // — `HeadlessJsMediaService.initialized` latches the JS task
+      // — `HeadlessJsMediaService.initialized` is set by the JS task
       // spawn so re-entrant connects do not double-spawn.
       this@PlaybackService.selfWakeForHeadlessClient(packageName)
     }
@@ -341,14 +332,16 @@ class PlaybackService : HeadlessJsMediaService() {
     }
 
     override fun onPlayFromSearchRequest(
-      request: MediaSearchRequest
+      request: MediaSearchRequest,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> =
-      this@PlaybackService.dispatchPlayFromSearchToJs(request)
+      this@PlaybackService.dispatchPlayFromSearchToJs(request, append)
 
     override fun onPlayFromIdRequest(
-      mediaId: String
+      mediaId: String,
+      append: Boolean
     ): ListenableFuture<List<MediaItem>> =
-      this@PlaybackService.dispatchPlayFromIdToJs(mediaId)
+      this@PlaybackService.dispatchPlayFromIdToJs(mediaId, append)
 
     override fun onPlayFromIdRequestNoSync(mediaId: String) {
       this@PlaybackService.dispatchPlayFromIdToJsFireOnly(mediaId)
@@ -425,14 +418,6 @@ class PlaybackService : HeadlessJsMediaService() {
      */
     val instanceId: java.util.UUID = java.util.UUID.randomUUID()
 
-    /**
-     * Direct access to the underlying ExoPlayer. Retained as a
-     * back-compat shim for [TrackPlayer] until its transport /
-     * queue calls migrate onto the [engine] surface; engine-aware
-     * code paths use [engine] instead.
-     */
-    val player: ExoPlayer get() = exoPlayer
-
     /**
      * Strategy-pattern engine wrapping the active player(s).
      * Routes through the abstract [PlaybackEngine] surface so
@@ -464,7 +449,7 @@ class PlaybackService : HeadlessJsMediaService() {
      * AVRCP, Android Auto, and Wear surfaces grey out skip buttons
      * that the queue boundary makes invalid. No-op when no handler
      * is registered (no authoritative capability source) or when no
-     * controllers have connected yet (next [PlaybackCallback.onConnect]
+     * controllers have connected yet (next [PlaybackServiceCallback.onConnect]
      * picks up the fresh capability).
      */
     internal fun refreshAvailableCommands() {
@@ -504,9 +489,12 @@ class PlaybackService : HeadlessJsMediaService() {
   private val localBinder by lazy { LocalBinder() }
 
   /**
-   * Currently-registered handler consulted by [PlaybackCallback]
-   * before the default routing runs. `null` until
-   * [TrackPlayer.configureInternal] wires itself in; under that
+   * Currently-registered handler consulted by [SessionCommandForwardingPlayer]
+   * before the default routing runs, by [MediaButtonDispatch] for raw
+   * media-button intents, by the audio-focus listener, and by
+   * [PlaybackServiceCallback.onConnect] for the initial player commands.
+   * `null` until
+   * [TrackPlayer.configureInternal] registers one; under that
    * state every callback falls through to the Media3 default and
    * raw media-button intents fall through to the framework.
    */
@@ -640,7 +628,7 @@ class PlaybackService : HeadlessJsMediaService() {
    * PcmStream (AirPlay) session is not a RemotePlayer.
    */
   private val castBindScope = kotlinx.coroutines.CoroutineScope(
-    kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.Main.immediate
+    kotlinx.coroutines.SupervisorJob() + Dispatchers.Main.immediate
   )
 
   override fun onCreate() {
@@ -925,8 +913,8 @@ class PlaybackService : HeadlessJsMediaService() {
    * the new leading player, swap `MediaSession` to the new
    * player, carry the delegate over, re-wire the Equalizer, and
    * release the old engine. Queue migration is the caller's
-   * responsibility — `TrackPlayer` re-installs the canonical
-   * queue model onto the new engine before the swap if needed.
+   * responsibility — `TrackPlayer` seeds the new engine through
+   * `setMediaItems` after this returns.
    */
   fun swapEngine(newEngine: PlaybackEngine): PlaybackEngine {
     return swapEngineInternal(newEngine)
@@ -1080,6 +1068,16 @@ class PlaybackService : HeadlessJsMediaService() {
    * complete kill. A future multi-session change would need to stop each.
    */
   override fun onTaskRemoved(rootIntent: Intent?) {
+    // Stop the engine, not the session's player. Under crossfade the session
+    // is bound to a forwarding wrapper that addresses one leg, so stopping it
+    // leaves the other leg running: the task is swiped away, the notification
+    // and session go, and audio keeps playing with nothing left to control
+    // it. The engine stops both legs and abandons audio focus.
+    engine.stop()
+    // And the session's player. While cast-bound that is the receiver, which
+    // the engine does not own — stopping only the legs leaves the Chromecast
+    // playing after the task, notification and session are all gone. Off cast
+    // it is the forwarding wrapper around a leg the engine just stopped.
     mediaSession?.player?.stop()
     stopForeground(Service.STOP_FOREGROUND_REMOVE)
     stopSelf()
@@ -1129,7 +1127,7 @@ class PlaybackService : HeadlessJsMediaService() {
    */
   private val callbackDispatchScope =
     kotlinx.coroutines.CoroutineScope(
-      kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.IO
+      kotlinx.coroutines.SupervisorJob() + Dispatchers.IO
     )
 
   /**
@@ -1152,6 +1150,9 @@ class PlaybackService : HeadlessJsMediaService() {
         kotlinx.coroutines.withTimeoutOrNull(SEARCH_DISPATCH_TIMEOUT_MS) {
           callback(query).await().await().toList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         // JS handler threw — surface as an empty answered result so
         // the controller stops waiting. The thrown error is the
@@ -1165,7 +1166,11 @@ class PlaybackService : HeadlessJsMediaService() {
         emptyList()
       }
       searchResultCache.setResults(query, items)
-      notifySearchResultChanged(query, items.size)
+      // `mediaSession` is owned by main and nulled by onDestroy there; the
+      // notify has to read it on the same thread or it races the release.
+      withContext(Dispatchers.Main) {
+        notifySearchResultChanged(query, items.size)
+      }
     }
   }
 
@@ -1185,9 +1190,11 @@ class PlaybackService : HeadlessJsMediaService() {
    * retries).
    */
   internal fun dispatchPlayFromSearchToJs(
-    request: MediaSearchRequest
+    request: MediaSearchRequest,
+    append: Boolean = false
   ): ListenableFuture<List<MediaItem>> = dispatchAssistantPlay(
     methodLabel = "onPlayFromSearchRequest",
+    append = append,
     awaitSlot = { browseCallbacks.awaitPlayFromSearchRequestCallback() }
   ) { browseCallbacks.playFromSearchRequestCallback()?.invoke(request) }
 
@@ -1198,9 +1205,11 @@ class PlaybackService : HeadlessJsMediaService() {
    * [dispatchPlayFromSearchToJs].
    */
   internal fun dispatchPlayFromIdToJs(
-    mediaId: String
+    mediaId: String,
+    append: Boolean = false
   ): ListenableFuture<List<MediaItem>> = dispatchAssistantPlay(
     methodLabel = "onPlayFromIdRequest",
+    append = append,
     awaitSlot = { browseCallbacks.awaitPlayFromIdRequestCallback() }
   ) { browseCallbacks.playFromIdRequestCallback()?.invoke(mediaId) }
 
@@ -1233,6 +1242,9 @@ class PlaybackService : HeadlessJsMediaService() {
               }
           promise?.await()?.await()
         }
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1263,6 +1275,9 @@ class PlaybackService : HeadlessJsMediaService() {
               }
           promise?.await()?.await()?.toList() ?: emptyList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1286,6 +1301,7 @@ class PlaybackService : HeadlessJsMediaService() {
 
   private inline fun dispatchAssistantPlay(
     methodLabel: String,
+    append: Boolean,
     crossinline awaitSlot: suspend () -> Unit,
     crossinline invoke: () -> Promise<Promise<Array<TrackItem>>>?
   ): ListenableFuture<List<MediaItem>> {
@@ -1303,6 +1319,9 @@ class PlaybackService : HeadlessJsMediaService() {
           }
           promise?.await()?.await()?.toList() ?: emptyList()
         } ?: emptyList()
+      } catch (t: kotlinx.coroutines.CancellationException) {
+        // The service is being destroyed; nothing below may run.
+        throw t
       } catch (t: Throwable) {
         android.util.Log.w(
           LOG_TAG,
@@ -1316,7 +1335,7 @@ class PlaybackService : HeadlessJsMediaService() {
       // with whatever this future resolves to, so we MUST return the
       // real items — returning emptyList here would wipe the queue
       // immediately after Media3 installs it.
-      val items = applyAssistantQueueOnMain(tracks)
+      val items = applyAssistantQueueOnMain(tracks, append)
       future.set(items)
     }
     // Cancel the launched dispatch when the controller drops the
@@ -1355,26 +1374,27 @@ class PlaybackService : HeadlessJsMediaService() {
         )
         return@launch
       }
-      kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Main) {
+      withContext(Dispatchers.Main) {
         callback()
       }
     }
   }
 
   private suspend fun applyAssistantQueueOnMain(
-    tracks: List<TrackItem>
+    tracks: List<TrackItem>,
+    append: Boolean
   ): List<MediaItem> {
     if (tracks.isEmpty()) return emptyList()
     val player = TrackPlayer.current ?: return emptyList()
-    return kotlinx.coroutines.withContext(kotlinx.coroutines.Dispatchers.Main) {
-      player.applyResolvedAssistantQueue(tracks)
+    return withContext(Dispatchers.Main) {
+      player.applyResolvedAssistantQueue(tracks, append)
     }
   }
 
   /**
    * Boot the JS task IF a headless-eligible controller has connected
    * AND no JS task is already running. Idempotent — the
-   * `HeadlessJsMediaService.initialized` latch + the wake-intent
+   * `HeadlessJsMediaService.initialized` flag + the wake-intent
    * action gate prevent re-entrancy.
    */
   internal fun selfWakeForHeadlessClient(packageName: String) {
@@ -1593,6 +1613,8 @@ class PlaybackService : HeadlessJsMediaService() {
   /**
    * Fire `notifySearchResultChanged` for [query] across every
    * connected controller after [searchResultCache] is populated.
+   * Caller is on main; the session's own thread-safety contract
+   * handles the controller iteration.
    */
   private fun notifySearchResultChanged(query: String, count: Int) {
     val session = mediaSession ?: return
@@ -1626,11 +1648,11 @@ class PlaybackService : HeadlessJsMediaService() {
   }
 
   /**
-   * Hook the [PlaybackCallback] consults before letting Media3 route
+   * Interface [SessionCommandForwardingPlayer] consults before letting Media3 route
    * a controller-initiated command to the bound player. Calls run on
    * 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
+   * so the default routing is suppressed; `onTransportCommand` fires for
    * play / pause / in-item seek / setPlaybackSpeed and is purely a
    * side-channel notification (no return value).
    */
@@ -1654,7 +1676,7 @@ class PlaybackService : HeadlessJsMediaService() {
     /**
      * Returns the lib's current authoritative skip capability —
      * driven by repeat-mode + queue position + queue size on the
-     * `TrackPlayer` side. Read by [PlaybackCallback.onConnect] and
+     * `TrackPlayer` side. Read by [PlaybackServiceCallback.onConnect] and
      * [LocalBinder.refreshAvailableCommands] so the available
      * `Player.Commands` reflect what skip arithmetic actually allows.
      */

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

@@ -91,7 +91,8 @@ internal class PlaybackServiceCallback(
      *  registered, the controller's "play X" voice command surfaces
      *  as "no results". */
     fun onPlayFromSearchRequest(
-      request: MediaSearchRequest
+      request: MediaSearchRequest,
+      append: Boolean = false
     ): ListenableFuture<List<MediaItem>> =
       Futures.immediateFuture(emptyList())
 
@@ -101,7 +102,8 @@ internal class PlaybackServiceCallback(
      *
      *  Default returns an empty list. */
     fun onPlayFromIdRequest(
-      mediaId: String
+      mediaId: String,
+      append: Boolean = false
     ): ListenableFuture<List<MediaItem>> =
       Futures.immediateFuture(emptyList())
 
@@ -194,7 +196,7 @@ internal class PlaybackServiceCallback(
           requestMetadata.extras
         )
         return Futures.transform(
-          environment.onPlayFromSearchRequest(request),
+          environment.onPlayFromSearchRequest(request, append = true),
           { items -> items.toMutableList() },
           MoreExecutors.directExecutor()
         )
@@ -202,7 +204,7 @@ internal class PlaybackServiceCallback(
       val mediaId = unresolved.mediaId.takeIf { it.isNotEmpty() }
       if (mediaId != null) {
         return Futures.transform(
-          environment.onPlayFromIdRequest(mediaId),
+          environment.onPlayFromIdRequest(mediaId, append = true),
           { items -> items.toMutableList() },
           MoreExecutors.directExecutor()
         )
@@ -749,7 +751,6 @@ internal class PlaybackServiceCallback(
     internal const val CONTENT_STYLE_PLAYABLE_HINT =
       "android.media.browse.CONTENT_STYLE_PLAYABLE_HINT"
     internal const val CONTENT_STYLE_LIST_ITEM = 1
-    internal const val CONTENT_STYLE_GRID_ITEM = 2
 
     /** Root extras flag: when `true`, gearhead surfaces a search
      *  affordance ("Search artists, albums, songs" mic / magnifying-

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

@@ -1,12 +1,11 @@
 package com.margelo.nitro.queueplayer
 
 /**
- * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
- * 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
- * an item to extract the same shapes on that side for parity.
+ * Pure-Kotlin index-shift arithmetic for queue mutations, kept out of
+ * [TrackPlayer] so the shift semantics stand alone without an
+ * ExoPlayer. Its iOS counterpart is `QueueMutationArithmetic.swift`,
+ * with the same function shapes and input/output semantics for these
+ * five helpers.
  *
  * The helper only computes the new `currentTrackIndex` and (for
  * `removeFromQueue`) which original indices apply after dedup /