react-native-queue-player 1.2.0 → 2.0.0

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

@@ -19,6 +19,8 @@ import androidx.media3.common.MediaItem
 import androidx.media3.common.PlaybackException
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
+import androidx.media3.database.StandaloneDatabaseProvider
+import androidx.media3.datasource.cache.SimpleCache
 import com.facebook.react.ReactApplication
 import androidx.media3.exoplayer.ExoPlayer
 import com.facebook.proguard.annotations.DoNotStrip
@@ -26,6 +28,8 @@ import com.margelo.nitro.NitroModules
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.CountDownLatch
 import kotlinx.coroutines.CompletableDeferred
+import kotlinx.coroutines.Job
+import kotlinx.coroutines.launch
 import kotlinx.coroutines.sync.Mutex
 import kotlinx.coroutines.sync.withLock
 import kotlinx.coroutines.withTimeoutOrNull
@@ -86,9 +90,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * an on-disk LRU. Built with [LookaheadCache.DEFAULT_MAX_SIZE_BYTES]
    * by default; `setLookaheadCache` lets consumers disable / resize.
    *
-   * Read on main only (configure / destroy run there); no @Volatile
-   * needed.
+   * Written on main (configure / destroy); read off main by
+   * `buildCacheStatusSnapshot` from the `Promise.async` pool
+   * (`getLookaheadCacheStatus`) and the cache-status IO dispatcher
+   * (`emitCacheStatus` / `onCacheStatusChange`), hence @Volatile.
    */
+  @Volatile
   @VisibleForTesting
   internal var lookaheadCache: LookaheadCache? = null
     private set
@@ -100,22 +107,35 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * mutation. Default lookahead window = [LookaheadCacheWriter.DEFAULT_LOOKAHEAD_COUNT]
    * (3); [setLookaheadCache] runtime config can override.
    */
+  @Volatile
   @VisibleForTesting
   internal var lookaheadCacheWriter: LookaheadCacheWriter? = null
     private set
 
   /**
-   * Live lookahead cache config — initialised from
-   * [LookaheadCacheConfigDefaults] on first configure, mutated by
-   * [setLookaheadCache]. Read on main only (config + status
-   * methods always hop). Persists across destroy → configure so a
-   * consumer who set custom values once doesn't lose them on a
-   * reconfigure cycle.
+   * Watches the default network's transport so prefetch can stop the moment
+   * the device hands off to cellular while `allowsCellularAccess` is off.
+   * Built with the lookahead stack and released with it.
+   */
+  @VisibleForTesting
+  internal var cellularTransportMonitor: CellularTransportMonitor? = null
+    private set
+
+  /**
+   * Live lookahead cache config — enabled with
+   * [LookaheadCacheWriter.DEFAULT_LOOKAHEAD_COUNT] until
+   * [setLookaheadCache] mutates it, on main; read on main by the config
+   * paths and off it by [buildCacheStatusSnapshot] on the `Promise.async`
+   * pool and the cache-status dispatcher, which is why it is `@Volatile`.
+   * Persists across destroy → configure so a consumer who set custom
+   * values once doesn't lose them on a reconfigure cycle.
    */
+  @Volatile
   @VisibleForTesting
   internal var lookaheadConfig: LookaheadCacheConfig = LookaheadCacheConfig(
     enabled = true,
-    lookaheadCount = LookaheadCacheWriter.DEFAULT_LOOKAHEAD_COUNT.toDouble()
+    lookaheadCount = LookaheadCacheWriter.DEFAULT_LOOKAHEAD_COUNT.toDouble(),
+    allowsCellularAccess = true
   )
 
   /** Configure-time cache disk budget in MB — `PlayerConfig.lookaheadCacheMaxSizeMb`
@@ -131,6 +151,130 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private fun evictionPolicyFrom(cfg: PlayerConfig): EvictionPolicy =
     cfg.lookaheadCacheEvictionPolicy ?: EvictionPolicy.LRU
 
+  private fun cachePrefs(context: Context) =
+    context.getSharedPreferences(CACHE_PREFS_NAME, Context.MODE_PRIVATE)
+
+  /**
+   * The eviction policy the cache on disk was last built with, or null before
+   * the first configure. Read from disk because the in-memory config starts at
+   * the default in every fresh process, which cannot distinguish "unchanged"
+   * from "changed back to the default".
+   */
+  private fun persistedEvictionPolicy(context: Context): EvictionPolicy? =
+    // The live cache wins while the process holds one: it is what the policy
+    // describes, and the prefs write is asynchronous, so a quick reconfigure
+    // would otherwise read a stale value and wipe a correct cache.
+    LookaheadCache.appliedEvictionPolicy(defaultCacheDirectory(context))
+      ?: cachePrefs(context).getString(KEY_EVICTION_POLICY, null)
+        ?.let { name -> EvictionPolicy.entries.firstOrNull { it.name == name } }
+
+  private fun defaultCacheDirectory(context: Context) =
+    java.io.File(context.applicationContext.cacheDir, LookaheadCache.DEFAULT_CACHE_DIR_NAME)
+
+  /**
+   * `commit()`, not `apply()`: this has to survive a process kill. A queued
+   * write lost to one leaves the previous policy recorded, and the next launch
+   * reads that as a policy change and wipes a cache that is already correct.
+   */
+  private fun persistEvictionPolicy(context: Context, policy: EvictionPolicy) {
+    val appCtx = context.applicationContext
+    cacheIoScope.launch {
+      runCatching {
+        val prefs = cachePrefs(appCtx)
+        if (prefs.getString(KEY_EVICTION_POLICY, null) != policy.name) {
+          prefs.edit().putString(KEY_EVICTION_POLICY, policy.name).commit()
+        }
+      }
+    }
+  }
+
+  /**
+   * Drop the on-disk cache: rename it out of the way on the caller's thread,
+   * then delete the files and the index tables off it.
+   *
+   * The rename is the load-bearing part. `configureInternal` rebuilds a
+   * `SimpleCache` in this same directory a few statements later, and
+   * `SimpleCache.initialize` reads the directory as it starts; a delete still
+   * running underneath makes that read fail and the cache throws for the rest
+   * of its life. Renaming is atomic within a filesystem, so the rebuild sees a
+   * clean path immediately and the slow part happens where nothing is watching.
+   */
+  private fun discardCacheDirectory(context: Context): Job? {
+    val appCtx = context.applicationContext
+    val cacheDir = defaultCacheDirectory(appCtx)
+    // A cache built by a previous process has no shared instance to release, so
+    // open a provider for it — the index tables are keyed by cache uid and
+    // outlive the files, and deleting the directory alone strands one per
+    // policy change.
+    val provider = LookaheadCache.releaseSharedInstance(cacheDir)
+      ?: runCatching { StandaloneDatabaseProvider(appCtx) }.getOrNull()
+    val doomed = java.io.File(
+      appCtx.cacheDir,
+      "${LookaheadCache.DEFAULT_CACHE_DIR_NAME}$DELETING_DIR_SUFFIX${System.nanoTime()}"
+    )
+    // Claimed before the rename, so the sweep — which runs off the looper and
+    // may list the directory at any moment — never collects a directory this
+    // process is deleting: otherwise it would match the name the rename just
+    // produced and start a second delete of the same tree, with a second
+    // database provider dropping the same index tables.
+    claimDoomedDirectory(doomed)
+    if (!cacheDir.exists() || !cacheDir.renameTo(doomed)) {
+      releaseDoomedDirectory(doomed)
+      // Without the rename the directory is still the one the rebuild is about
+      // to use, so the delete has to finish before this returns. Doing it off
+      // thread here would race the rebuild and can drop the *new* cache's index
+      // tables, which is worse than the main-thread cost of a path that only
+      // fires when a same-filesystem rename fails.
+      deleteCacheDirectory(cacheDir, provider)
+      return null
+    }
+    return cacheIoScope.launch {
+      try {
+        deleteCacheDirectory(doomed, provider)
+      } finally {
+        releaseDoomedDirectory(doomed)
+      }
+    }
+  }
+
+  private fun deleteCacheDirectory(
+    dir: java.io.File,
+    provider: StandaloneDatabaseProvider?
+  ) {
+    runCatching {
+      // Reads the uid from inside `dir`, so it drops the index tables belonging
+      // to this cache and no other.
+      if (provider != null) SimpleCache.delete(dir, provider) else dir.deleteRecursively()
+    }
+    runCatching { provider?.close() }
+  }
+
+  /**
+   * Delete directories left behind by a discard that did not finish — a process
+   * death between the rename and the delete strands one, and nothing else would
+   * ever collect it.
+   */
+  private fun sweepAbandonedCacheDirectories(context: Context) {
+    val appCtx = context.applicationContext
+    val prefix = "${LookaheadCache.DEFAULT_CACHE_DIR_NAME}$DELETING_DIR_SUFFIX"
+    // Listing and deleting both run off the looper; a directory this process
+    // is deleting is claimed before it is renamed into this name pattern, so
+    // the listing cannot pick one up mid-discard.
+    cacheIoScope.launch {
+      val orphans = appCtx.cacheDir.listFiles()
+        ?.filter {
+          it.isDirectory && it.name.startsWith(prefix) && !isDoomedDirectoryClaimed(it)
+        }
+        ?: return@launch
+      if (orphans.isEmpty()) return@launch
+      // Each orphan still carries its own `.uid`, so route it through the same
+      // delete to take its index tables with it.
+      val provider = runCatching { StandaloneDatabaseProvider(appCtx) }.getOrNull()
+      orphans.forEach { runCatching { if (provider != null) SimpleCache.delete(it, provider) else it.deleteRecursively() } }
+      runCatching { provider?.close() }
+    }
+  }
+
   /**
    * Cache-status listeners registered via [onCacheStatusChange].
    * Multi-listener registry — every JS consumer that subscribes gets
@@ -198,6 +342,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       networkTimeoutMs = null,
       audioContentType = null,
       audioCategoryOptions = null,
+      // iOS-only opt-in; Android has no in-app vocabulary donation API and
+      // ignores it, as `donateVoiceVocabulary` itself does.
+      voiceVocabularyDonationEnabled = null,
       visualizationEnabled = null,
       clampSeekToBuffered = null,
       lookaheadCacheMaxSizeMb = null, lookaheadCacheEvictionPolicy = null,
@@ -248,29 +395,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var playbackModeState: PlaybackModeStateMachine.State =
     PlaybackModeStateMachine.Initial
 
-  /**
-   * Subscribe to cast-route activate/deactivate transitions.
-   * Push-PCM sessions (AirPlay 1/2) force-degrade the active engine
-   * from Crossfade to Gapless because the wire protocol cannot mix
-   * two ExoPlayers into one sink; clearing the session re-applies
-   * the user's requested mode (so crossfade re-instates).
-   *
-   * The disposer is intentionally discarded — TrackPlayer is a
-   * process-singleton `HybridObject`; the listener lives for the
-   * lifetime of the JVM and the disposer would only matter if a
-   * second TrackPlayer instance ever existed.
-   */
-  @Suppress("unused")
-  private val castRouteDisposer: () -> Unit =
-    com.margelo.nitro.queueplayer.cast.CastSinkRouter.addRouteChangeListener { _ ->
-      // Re-apply against the user's requested mode on every flip.
-      // `applyEngineSwapForMode` consults `CastSinkRouter.isRemoteActive`
-      // for the degrade decision, so the swap settles to the right
-      // engine for the new route state.
-      val mode = playbackModeState.active
-      mainHandler.post { applyEngineSwapForMode(mode) }
-    }
-
   /**
    * Bridges Chromecast `RemotePlayer` session events back to the
    * lib's existing JS event surface (`onStateChange` etc.). Lives for
@@ -278,7 +402,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * `PlaybackStateRouter.activeFlow` and subscribes / unsubscribes to
    * the active session's StateFlows on every transition.
    */
-  @Suppress("unused")
   private val castEventBridge = com.margelo.nitro.queueplayer.cast.CastEventBridge(this).also {
     it.start()
   }
@@ -304,6 +427,39 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       kotlinx.coroutines.SupervisorJob() + kotlinx.coroutines.Dispatchers.Main.immediate
     )
 
+  /**
+   * Scope for cache file work that must not run on the app looper — recursive
+   * directory deletes and the SQLite index drop that goes with them.
+   *
+   * Process-lifetime and deliberately not cancelled on destroy: a delete that
+   * outlives a `destroy()` still has to finish, or the renamed directory it is
+   * clearing leaks until the next launch sweeps it.
+   */
+  private val cacheIoScope =
+    kotlinx.coroutines.CoroutineScope(
+      kotlinx.coroutines.SupervisorJob() +
+        kotlinx.coroutines.Dispatchers.IO +
+        // Cache housekeeping must never take the process down. Off the main
+        // thread there is no JS call to surface a failure to, and the default
+        // handler treats an uncaught one as fatal.
+        kotlinx.coroutines.CoroutineExceptionHandler { _, t ->
+          Log.w(TAG, "cache maintenance failed", t)
+        }
+    )
+
+  /**
+   * Cache-status snapshots, built one at a time.
+   *
+   * `onTrackProcessed` fires one of these per prefetched track, and on the
+   * unbounded IO dispatcher two builds can finish in either order and deliver
+   * out of sequence — a subscriber would watch `tracksFullyCached` go
+   * backwards. Serialising the builds keeps the deliveries in the order the
+   * snapshots were taken.
+   */
+  @OptIn(kotlinx.coroutines.ExperimentalCoroutinesApi::class)
+  private val cacheStatusDispatcher =
+    kotlinx.coroutines.Dispatchers.IO.limitedParallelism(1)
+
   /**
    * Connection to the in-process [PlaybackService]. `onServiceConnected`
    * stashes the [PlaybackService.LocalBinder] and completes
@@ -324,13 +480,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       // landed; the next disconnect starts the backoff fresh.
       rebindAttempt = 0
       rebindHandler.removeCallbacks(rebindRunnable)
-      // Apply any browse-callback registrations the consumer made
-      // before the binder was available — typically `bootstrap.ts`
-      // → `installCarService` → `registerPlaybackService` running
-      // at bundle-load time, before `configure()` binds the service.
-      // Without this drain, those pre-bind registrations are dropped
-      // and Android Auto's later bind times out waiting for the JS
-      // carConnect callback.
+      // Apply browse-callback registrations made while [serviceBinder]
+      // was null — before the first bind, or between a service kill and
+      // this rebind. Without the drain those registrations never reach
+      // the service and `dispatchCarConnect` times out waiting for a JS
+      // carConnect callback that was never installed.
       drainPendingBrowseRegistrations()
       drainPendingSnapshot()
       // Re-apply the remote-control config to the (possibly reborn) service.
@@ -544,7 +698,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // simultaneously without clobbering each other.
   private val stateChangeListeners = ListenerRegistry<(PlayerState, StateChangeReason) -> Unit>()
   private val trackChangeListeners = ListenerRegistry<(TrackItem?, Double, TrackChangeReason, Double?) -> Unit>()
-  private val queueChangeListeners = ListenerRegistry<(Array<TrackItem>, Double, QueueChangeReason) -> Unit>()
+  private val queueChangeListeners = ListenerRegistry<(QueueChangeDelta, Double, QueueChangeReason) -> Unit>()
   private val progressListeners = ListenerRegistry<(PlayerProgress) -> Unit>()
   // Buffer state — discrete empty/buffering/stalled/full for the active track, derived
   // from Media3's playback state + buffered-ahead. Recomputed on the engine
@@ -585,17 +739,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var progressLifecycleObserver: DefaultLifecycleObserver? = null
   private val errorListeners = ListenerRegistry<(PlaybackError) -> Unit>()
   private val queueEndListeners = ListenerRegistry<() -> Unit>()
-  // SkipCapability struct — wraps (canSkipPrevious, canSkipNext).
-  // Struct rather than separate boolean args dodges a Nitrogen
-  // 0.35.4 (bool, bool) callback codegen bug.
+  // Workaround: the callback carries a `SkipCapability` struct rather than
+  // two boolean arguments, because Nitrogen miscompiles a `(bool, bool) ->
+  // void` callback. No margelo/nitro issue found for it.
   private val skipCapabilityListeners = ListenerRegistry<(SkipCapability) -> Unit>()
 
-  /**
-   * Last-emitted skip capability tuple. Native owns the truth; the
-   * JS layer is a passive observer. Recomputed via
-   * [recomputeCapabilities] at every `tracks` / `currentTrackIndex`
-   * / `repeatModeState` write site, with dedup.
-   */
   /**
    * Authoritative snapshot of (canSkipPrevious, canSkipNext) — single
    * `@Volatile` reference write keeps the pair atomic across cross-
@@ -643,12 +791,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var gaplessGapPrevEndedAtNs: Long = 0L
 
   /**
-   * Debug-only timestamps backing the verbose `RNQP-GAPLESS` Log.d
-   * emits. Wrapped in `if (BuildConfig.DEBUG)` at every read/write
-   * site so R8 strips the branches in Release builds. Field storage
-   * stays (16 bytes total — negligible) but is never accessed in prod.
+   * Debug-only timestamp backing the verbose `RNQP-GAPLESS` Log.d emits.
+   * Every read and write sits inside `if (BuildConfig.DEBUG)`, so R8
+   * strips the branches in Release builds; only the field itself remains.
    */
-  private var gaplessLogLastEndedAtNs: Long = 0L
   private var gaplessLogLastChangedAtNs: Long = 0L
 
   /** Stashed by transport methods before calling player.play()/pause()/stop()/seekTo().
@@ -700,9 +846,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    *  transient-error fire; when 0, the error surfaces to JS.
    *  Re-populated on `setQueueInternal` /
    *  `addToQueueInternal` from `effectiveAutoRetries()` (clamped
-   *  0..5; default 3). Reset to 1 (single shot) by `play()` if state
-   *  is `.error` and the counter is 0 — stuck-recovery on user-
-   *  initiated re-tap. Cleared on `removeFromQueue` / `moveInQueue`
+   *  0..5; default 1). Restored to the configured value by `retry()`, so
+   *  a manual attempt gives whatever fails next its configured automatic
+   *  allowance. `play()` restores the same configured value when the counter
+   *  is 0 — stuck-recovery on a user re-tap. Cleared on `removeFromQueue` / `moveInQueue`
    *  (index shifts invalidate keys; budget resets are an acceptable
    *  trade-off vs walking + remapping the map per shifted index). */
   private var retryAttemptsRemaining: MutableMap<Int, Int> = mutableMapOf()
@@ -874,25 +1021,34 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   internal fun configureInternal(newConfig: PlayerConfig, context: Context) {
     // Eviction policy is fixed at SimpleCache construction; a change clears the
     // cache + rebuilds under the new evictor (infrequent — see FifoCacheEvictor).
-    // Safe to release the shared SimpleCache here: configure() runs
-    // destroyInternal() before this, which releases the prior engine — the only
-    // CacheDataSource reader of that cache — so there is no live reader when the
-    // shared instance is released and its directory deleted below.
-    val previousEvictionPolicy = evictionPolicyFrom(this.config)
+    // The service still holds the engine `configurePlayer` replaces further
+    // down — `destroyInternal` drops this player's references, not the
+    // service's engine — and that engine reads through the shared cache, so it
+    // is stopped before the cache is released and its directory renamed away.
+    // Compare against what was last APPLIED, not against the in-memory config.
+    // A fresh process starts at the LRU default, so a FIFO consumer would
+    // otherwise read every cold launch as a policy change and wipe its cache
+    // before it could ever be used.
+    val previousEvictionPolicy =
+      persistedEvictionPolicy(context) ?: evictionPolicyFrom(this.config)
     this.config = newConfig
     // Swap the cover-art placeholder bitmap to the consumer-supplied image
     // (or back to the built-in when unset). The no-art metadata URI is
     // threaded separately at each buildMediaItems call.
     PlaceholderArtwork.setCustom(newConfig.placeholderArtworkUri)
     if (evictionPolicyFrom(newConfig) != previousEvictionPolicy) {
+      serviceBinder?.engine?.stop()
       lookaheadCacheWriter?.release()
       lookaheadCacheWriter = null
       lookaheadCache?.release()
       lookaheadCache = null
-      val cacheDir = java.io.File(context.cacheDir, LookaheadCache.DEFAULT_CACHE_DIR_NAME)
-      LookaheadCache.releaseSharedInstance(cacheDir)
-      cacheDir.deleteRecursively()
+      cellularTransportMonitor?.stop()
+      cellularTransportMonitor = null
+      discardCacheDirectory(context)
     }
+    // Collect what a previous process left mid-delete. Directories this
+    // process is still deleting are claimed and skipped.
+    sweepAbandonedCacheDirectories(context)
     // Seed the progress-emission throttle from config and start observing app
     // background/foreground. Both are idempotent, so a re-configure refreshes
     // the rate without double-registering the lifecycle observer.
@@ -907,6 +1063,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // new field.
     VisualizationGate.setEnabled(newConfig.visualizationEnabled ?: true)
     buildLookaheadStack(newConfig, context)
+    // Recorded only once a cache actually exists under this policy, so a failed
+    // build cannot leave a policy stamped that nothing was built with.
+    if (lookaheadCache != null) {
+      persistEvictionPolicy(context, evictionPolicyFrom(newConfig))
+    }
+    // configure() destroys first, so the queue is empty here and this clears
+    // protection rather than seeding it. That is the point: the evictor lives
+    // in a process-wide shared instance that outlives a destroy/configure
+    // cycle, so without this it would keep shielding the previous session's
+    // tracks until the next queue mutation.
+    refreshCacheProtection()
     val mediaSourceFactory =
       MediaItemBuilder.buildMediaSourceFactory(context, newConfig, lookaheadCache)
     val binder = serviceBinder
@@ -943,6 +1110,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       engine.setVolume(volumeState)
       engine.setPlaybackSpeed(playbackSpeedState)
       engine.setPitchCorrectionMode(pitchCorrectionModeState)
+      installSuppliedReplayGainResolver(engine)
     }
     installEventObservers()
     binder.setCommandHandler(mediaSessionCommandHandler)
@@ -950,7 +1118,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Bridge from [PlaybackService.PlaybackCallback] back into this
+   * Bridge from `PlaybackService` — its [SessionCommandForwardingPlayer],
+   * [MediaButtonDispatch] and audio-focus listener — back into this
    * TrackPlayer. Stamps the `system` pending-reason for transports
    * that the system surface drives (lock-screen, Bluetooth, Android
    * Auto, hardware media keys), and routes skip-next / skip-previous
@@ -1089,6 +1258,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * not a correctness gate.
    */
   private fun buildLookaheadStack(config: PlayerConfig, context: Context) {
+    // Ahead of the writer, which captures the monitor's reading at every
+    // reschedule, and a transport flip has to move the window itself. Built
+    // regardless of `enabled` for the same reason the cache is: prefetch can
+    // be turned on at runtime, and the writer built then needs a monitor.
+    cellularTransportMonitor?.stop()
+    cellularTransportMonitor = CellularTransportMonitor(context).apply {
+      // The callback arrives on a ConnectivityManager thread; the reschedule
+      // is main-confined.
+      onTransportChanged = { mainHandler.post { rescheduleLookahead() } }
+      start()
+    }
     // Build the cache regardless of `enabled` so caching can be turned on at
     // runtime (setLookaheadCacheInternal) without a configure() cycle. Media3's
     // SimpleCache fixes its size at construction and allows one instance per
@@ -1118,6 +1298,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       null
     }
     lookaheadCache = cache
+    cache?.servesPlayback = lookaheadConfig.enabled
     // Writer + player factory share state via the cache, not via the
     // http factory instance. Writer is only useful when there's a
     // cache to write into — gate on both `lookaheadConfig.enabled`
@@ -1131,10 +1312,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
           networkTimeoutMs = MediaItemBuilder.effectiveNetworkTimeoutMs(
             config.networkTimeoutMs
           )
-        )
+        ),
+        isOnCellular = { cellularTransportMonitor?.isOnCellular == true }
       ).apply {
         defaultLookaheadCount = lookaheadConfig.lookaheadCount.toInt()
           .coerceAtLeast(0)
+        allowsCellularAccess = lookaheadConfig.allowsCellularAccess ?: true
         onTrackProcessed = { onMainPostStatusEmit() }
       }
     } else {
@@ -1142,20 +1325,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     }
   }
 
-  /**
-   * Tear down the ExoPlayer + lookahead writer + cache instances so
-   * the configure() rebuild path (headers/userAgent change) can
-   * recreate them cleanly. The on-disk cache directory is preserved
-   * — `SimpleCache.release()` only frees the in-memory instance and
-   * its file lock; the entries stay on disk and the next
-   * `LookaheadCache(...)` constructor reads them back. Mirrors the
-   * SimpleCache "one-instance-per-directory" invariant captured in
-   * NOTES.md.
-   */
-  private fun destroyPlayerKeepCacheOnDisk() {
-    releasePlayerAndState(notifyTrackChange = true)
-  }
-
   /**
    * Lifecycle destroy body. Releases the ExoPlayer instance and
    * resets every piece of mutable state so a subsequent configure()
@@ -1171,7 +1340,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // player.
     cancelPendingRebind()
     serviceBinder?.setCommandHandler(null)
-    releasePlayerAndState(notifyTrackChange = false)
+    releasePlayerAndState()
     boundContext?.let { ctx ->
       try {
         ctx.unbindService(serviceConnection)
@@ -1200,25 +1369,22 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     pendingStateChangeReason = null
     pendingTrackChangeReason = null
     lastErrorKey = null
+    cancelPendingRetry()
     retryAttemptsRemaining.clear()
     if (current === this) current = null
   }
 
   /**
-   * Shared tear-down for the player + cache + writer + per-position
-   * state. Tear order matters: prefetcher releases before the cache
-   * so an in-flight `CacheWriter` reading from a released SimpleCache
-   * cannot NPE. SimpleCache enforces a one-instance-per-directory
-   * invariant for the JVM lifetime, so the in-memory cache object is
-   * released here even when the on-disk directory is preserved for
-   * a follow-up `configureInternal` to re-open. When
-   * `notifyTrackChange` is true, fires a synthetic
-   * `(null, -1, QUEUE_REPLACED)` so JS hooks like `useActiveTrack`
-   * clear their snapshot — without it a Player UI rendering
-   * `#${index+1}/${queueLength}` would show `#1/0` after the queue
-   * empties.
+   * Tear-down for the writer, the cache reference and per-position
+   * state, called from [destroyInternal]. The writer's coroutine scope
+   * is cancelled before the cache's MIME store is cleared so a racing
+   * `recordMimeType` cannot land after the clear. The Media3 SimpleCache
+   * is a per-folder process singleton and is not released here —
+   * `LookaheadCache.release()` drops only per-instance state; an
+   * eviction-policy change in [configureInternal] releases and rebuilds
+   * it via [discardCacheDirectory].
    */
-  private fun releasePlayerAndState(notifyTrackChange: Boolean) {
+  private fun releasePlayerAndState() {
     // Cancel any armed sleep timer up front — the engine (and its volume) is
     // going away, so don't touch it or emit; just stop the tick + reset state.
     stopSleepTimerTick()
@@ -1228,16 +1394,27 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     tearDownEventObservers()
     lookaheadCacheWriter?.release()
     lookaheadCacheWriter = null
+    // Before dropping the reference: the evictor is process-wide and outlives
+    // this player, so its protected set has to be cleared here or those entries
+    // stay unevictable until the next configure moves the window.
+    // `LookaheadCache.release()` does not touch it.
+    lookaheadCache?.setProtectedUrls(emptySet())
     lookaheadCache?.release()
     lookaheadCache = null
+    cellularTransportMonitor?.stop()
+    cellularTransportMonitor = null
     // Mark unconfigured so the [player] accessor returns null even
     // though the service may still be bound (it unbinds at the
     // bottom of destroyInternal). The PlaybackService releases its
     // own engine (which owns the ExoPlayer instances) on service
     // unbind / onDestroy.
     configured = false
-    val hadTracks = tracks.isNotEmpty()
     tracks = emptyList()
+    // The clear emits nothing, so a mirror built from `onQueueChange` deltas
+    // would splice the next delta onto the queue this just dropped. Moving
+    // the revision past the next emit's value is what a subscriber reads as
+    // a missed event, and re-reads.
+    queueRevision += 1
     currentTrackIndex = -1
     currentTrackSource = null
     currentBufferState = BufferState.EMPTY
@@ -1247,9 +1424,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     hasStartedPlaying = false
     wantsToPlay = false
     lastReportedState = PlayerState.NONE
-    if (notifyTrackChange && hadTracks) {
-      trackChangeListeners.forEach { it(null, -1.0, TrackChangeReason.QUEUE_REPLACED, null) }
-    }
     refreshNowPlayingFormatForActiveItem()
     recomputeCapabilities()
   }
@@ -1296,13 +1470,13 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (Looper.myLooper() == Looper.getMainLooper()) {
       return body()
     }
-    val latch = CountDownLatch(1)
+    val done = CountDownLatch(1)
     var result: Result<T>? = null
     mainHandler.post {
       result = runCatching { body() }
-      latch.countDown()
+      done.countDown()
     }
-    latch.await()
+    done.await()
     return result!!.getOrThrow()
   }
 
@@ -1418,6 +1592,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       if (trackIndex < 0 || trackIndex >= engine.allMediaItems.size) return@onMainSync
       currentTrackIndex = trackIndex
       engine.seekTo(trackIndex, maxOf(0L, positionMs))
+      // The index drifted throughout the cast session without touching the
+      // local prefetch or protection windows, so both are stale for the track
+      // local playback is about to resume on.
+      rescheduleLookahead()
+      recomputeCapabilities()
     }
   }
 
@@ -1462,7 +1641,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
     rescheduleLookahead()
     recomputeCapabilities()
-    emitQueueChange(QueueChangeReason.SET_QUEUE)
+    emitQueueChange(
+      QueueChangeReason.SET_QUEUE,
+      inserted = tracks.toTypedArray(),
+      insertedAt = if (tracks.isEmpty()) -1 else 0
+    )
   }
 
   /**
@@ -1492,6 +1675,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // last item must not suppress an identical coded error on the
     // new queue's first item.
     lastErrorKey = null
+    cancelPendingRetry()
     // Reset auto-retry counters: new queue → new budget per index.
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining =
@@ -1515,19 +1699,48 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    */
   @MainThread
   internal fun applyResolvedAssistantQueue(
-    newTracks: List<TrackItem>
+    newTracks: List<TrackItem>,
+    append: Boolean = false
   ): List<MediaItem> {
-    val items = applyTrackListMetadata(newTracks) ?: return emptyList()
-    serviceBinder?.engine?.setWakeMode(pickWakeMode(newTracks))
+    // `onAddMediaItems` means Media3 will APPEND what this returns, so the
+    // lib's queue has to grow by the same amount. Replacing it here would
+    // leave the player holding old + new while getQueue() reported only the
+    // new tracks, and every index operation after that maps against the
+    // wrong list. `onSetMediaItems` is a genuine replace and keeps that.
+    // Media3 sets the resolved items on the session player after this returns,
+    // which under crossfade addresses the leading leg only. An armed standby
+    // leg still holds the queue as it stood when it was armed, so promoting it
+    // would drop everything added here and auto-advance would stop at the old
+    // queue end. Settle the fade first; the next boundary re-arms from the
+    // updated queue. `CrossfadeEngine.addMediaItems` does this for the paths
+    // that do go through the engine — this is the path that cannot.
+    serviceBinder?.engine?.settlePendingFade()
+    val resolved = if (append) this.tracks + newTracks else newTracks
+    val appendAt = this.tracks.size
+    val previousIndex = this.currentTrackIndex
+    val items = applyTrackListMetadata(resolved) ?: return emptyList()
+    if (append) {
+      // An append does not move the listener off what is playing.
+      this.currentTrackIndex = previousIndex
+      pendingTrackChangeReason = null
+    }
+    serviceBinder?.engine?.setWakeMode(pickWakeMode(resolved))
     rescheduleLookahead()
     recomputeCapabilities()
-    emitQueueChange(QueueChangeReason.SET_QUEUE)
-    return items
+    // The tracks came from a voice / Android Auto request, so a subscriber has
+    // no other way to learn them — carry them either way.
+    emitQueueChange(
+      if (append) QueueChangeReason.ADD else QueueChangeReason.SET_QUEUE,
+      inserted = if (append) resolved.drop(appendAt).toTypedArray() else resolved.toTypedArray(),
+      insertedAt = if (append) appendAt else if (resolved.isEmpty()) -1 else 0
+    )
+    // Media3 appends only what it is handed back, so return the added slice.
+    return if (append) items.drop(appendAt) else items
   }
 
   override fun addToQueue(tracks: Array<TrackItem>, insertBefore: Double?): Promise<Unit> =
     Promise.async {
-      // Mirror `seekToInternal:890` non-finite guard: NaN/±Infinity
+      // Mirror `seekToInternal`'s non-finite guard: NaN/±Infinity
       // from JS would `.toInt()` to MIN/MAX or 0 silently. When
       // insertBefore is non-finite, drop it (treat as "append at
       // end") rather than silently jumping to position 0.
@@ -1578,10 +1791,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     )
 
     // Index-keyed retry-budget map: insertion at `at` shifts every
-    // existing key >= at up by `newTracks.size`. Snapshot via
-    // `filterKeys` so mutation of the live map is safe regardless of
-    // iteration order; `toSortedMap` is incidental cleanliness, not
-    // load-bearing for correctness.
+    // existing key >= at up by `newTracks.size`. The shift must run in
+    // descending key order: each iteration removes `oldIdx` and writes
+    // `oldIdx + shift`, and in ascending order the write for key k lands
+    // on k + shift, and the later iteration for k + shift removes it, so
+    // that budget is lost.
+    cancelPendingRetry()
     val attempts = effectiveAutoRetries()
     val shift = newTracks.size
     val shifted = retryAttemptsRemaining
@@ -1614,7 +1829,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     serviceBinder?.engine?.setWakeMode(pickWakeMode(this.tracks))
     rescheduleLookahead()
     recomputeCapabilities()
-    emitQueueChange(QueueChangeReason.ADD)
+    emitQueueChange(
+      QueueChangeReason.ADD,
+      inserted = newTracks.toTypedArray(),
+      insertedAt = at
+    )
     return at
   }
 
@@ -1698,6 +1917,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // - **Why not preserve via remap**: requires walking the map
     //   AND the sanitised-indices in lockstep with offset
     //   accounting. The clear-and-repopulate is intentional.
+    cancelPendingRetry()
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
@@ -1710,7 +1930,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     recomputeCapabilities()
     // Reached only past the `sanitised.isEmpty()` guard, so ≥1 track was
     // removed; tracks + index are final.
-    emitQueueChange(QueueChangeReason.REMOVE)
+    emitQueueChange(QueueChangeReason.REMOVE, removed = sanitised)
     return sanitised
   }
 
@@ -1721,7 +1941,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       // mirror the reorder to the receiver. `routeMoveInQueue` is
       // suspending so it runs outside `onMain`. Mirrors iOS `moveInQueue`.
       val move = onMain {
-        // Mirror `seekToInternal:890` non-finite guard.
+        // Mirror `seekToInternal`'s non-finite guard.
         if (!fromIndex.isFinite() || !toIndex.isFinite()) return@onMain null
         val from = fromIndex.toInt()
         val to = toIndex.toInt()
@@ -1771,6 +1991,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // arbitrarily. Cheapest correct path is to clear + repopulate
     // (same trade-off as removeFromQueueInternal — structural reset
     // semantics for queue mutations).
+    cancelPendingRetry()
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in this.tracks.indices) retryAttemptsRemaining[i] = attempts
@@ -1778,12 +1999,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     recomputeCapabilities()
     // Reached only past the invalid / `from == to` / pinned-current
     // guards, so the order actually changed.
-    emitQueueChange(QueueChangeReason.MOVE)
+    emitQueueChange(QueueChangeReason.MOVE, movedFrom = from, movedTo = to)
     return true
   }
 
-  override fun getQueue(): Array<TrackItem> =
-    tracks.toTypedArray()
+  override fun getQueue(): Promise<Array<TrackItem>> =
+    Promise.async { onMain { tracks.toTypedArray() } }
 
   override fun clearQueue(): Promise<Unit> =
     Promise.async {
@@ -1812,6 +2033,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // Reset error-dedup so a subsequent queue's identical-coded error
     // isn't suppressed by a stale entry from the cleared queue.
     lastErrorKey = null
+    cancelPendingRetry()
     retryAttemptsRemaining.clear()
     tracks = emptyList()
     currentTrackIndex = -1
@@ -1866,18 +2088,23 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // engine. Same shape at every transport entry point — see
         // `CastTransportRouter` for the early-return contract.
         if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routePlay()) return@onMain
-        // Stuck-recovery: if the user re-taps play after
-        // an exhausted-retries error, give one more shot. Reset
-        // counter to 1 (single shot, not full autoRetries — each
-        // user tap = one attempt for predictable UX) and re-prepare.
-        // Mirrors iOS `play()` stuck-recovery.
+        // Stuck-recovery: if the user re-taps play after an exhausted-retries
+        // error, hand the track back the allowance the consumer configured and
+        // re-prepare. Not a hard-coded 1: a consumer who set `autoRetries: 0`
+        // asked for none. Mirrors iOS `play()` stuck-recovery.
         if (lastReportedState == PlayerState.ERROR &&
             currentTrackIndex >= 0 &&
             (retryAttemptsRemaining[currentTrackIndex] ?: 0) == 0) {
-          retryAttemptsRemaining[currentTrackIndex] = 1
+          retryAttemptsRemaining[currentTrackIndex] = effectiveAutoRetries()
           lastErrorKey = null
           player?.prepare()
         }
+        // At the end of the queue there is nothing to play: ExoPlayer stays
+        // STATE_ENDED through play(), and a playWhenReady left set would
+        // start the next track a skip seats without anyone asking. A skip, a
+        // seek or a fresh queue leaves this state; play() alone restarts
+        // nothing — the same contract as iOS.
+        if (player?.playbackState == Player.STATE_ENDED && tracks.isNotEmpty()) return@onMain
         // Stash USER on the pending-reason channel so the
         // subsequent Player.Listener fire attributes the transition
         // correctly.
@@ -1894,14 +2121,22 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
         // During cast the receiver owns playback — forward a play so a failed
         // receiver item re-attempts.
         if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routePlay()) return@onMain
-        // Local recovery: only meaningful for a track that errored after its
-        // automatic retries were exhausted. Give it one fresh attempt — reset
-        // the per-track retry budget, then rebuild the failed item via
-        // retryFailedItem, which discards the wedged DataSource (a bare
-        // prepare() would re-use it), restores the pre-failure position, and
-        // resumes playing.
-        if (lastReportedState != PlayerState.ERROR || currentTrackIndex < 0) return@onMain
-        retryAttemptsRemaining[currentTrackIndex] = 1
+        // A user asking for a retry has a reason, and the library is not the
+        // one to judge it. This is the manual attempt once the automatic one
+        // is spent, so gating it on the player's state would gate recovery on
+        // the state of a player that has already failed to recover — and a
+        // wedged decoder still reporting PLAYING is exactly when someone
+        // reaches for the button. retryFailedItem below discards the wedged
+        // DataSource (a bare prepare() would re-use it), restores the
+        // pre-failure position, and resumes playing.
+        //
+        // Only the bounds remain: no current track is genuinely nothing to
+        // retry, which is not second-guessing the request.
+        if (currentTrackIndex < 0) return@onMain
+        // The configured budget, not a hard-coded 1: this restores the track's
+        // automatic allowance for whatever fails *next*, and a consumer who
+        // set `autoRetries: 0` asked for none.
+        retryAttemptsRemaining[currentTrackIndex] = effectiveAutoRetries()
         lastErrorKey = null
         pendingStateChangeReason = StateChangeReason.USER
         wantsToPlay = true
@@ -2108,7 +2343,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun skipToIndex(index: Double): Promise<Unit> =
     Promise.async {
       onMain {
-        // Mirror `seekToInternal:890` non-finite guard. Without this
+        // Mirror `seekToInternal`'s non-finite guard. Without this
         // `Double.NaN.toInt()` returns 0 — `skipToIndex(NaN)` would
         // silently jump to track 0 instead of no-op'ing. iOS uses
         // `InputGuards.validQueueIndex` for the same guarantee.
@@ -2240,14 +2475,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       repeatMode = repeatModeAsSkipMode()
     )
 
-  @VisibleForTesting
-  internal fun computePreviousIndex(): Int? =
-    QueueSkipArithmetic.computePrevious(
-      trackCount = tracks.size,
-      currentIndex = currentTrackIndex,
-      repeatMode = repeatModeAsSkipMode()
-    )
-
   private fun repeatModeAsSkipMode(): QueueSkipRepeatMode = when (repeatModeState) {
     RepeatMode.OFF -> QueueSkipRepeatMode.OFF
     RepeatMode.TRACK -> QueueSkipRepeatMode.TRACK
@@ -2279,7 +2506,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * clearQueueInternal, skipToIndexInternal / skipToNextInternal /
    * skipToPreviousInternal (all index writes), setRepeatModeInternal,
    * shuffleQueueInternal, handleMediaItemTransition (covers Media3
-   * REASON_AUTO + REASON_REPEAT auto-advance), destroyInternal.
+   * REASON_AUTO + REASON_REPEAT auto-advance), the crossfade
+   * fade-start / cancel index writes, emitRemoteTrackChange and
+   * resumeLocalAfterCast (cast), destroyInternal.
    */
   @MainThread
   internal fun recomputeCapabilities() {
@@ -2470,6 +2699,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     newEngine.setVolume(volumeState)
     newEngine.setPlaybackSpeed(playbackSpeedState)
     newEngine.setPitchCorrectionMode(pitchCorrectionModeState)
+    installSuppliedReplayGainResolver(newEngine)
     // Drive the AirPlay receiver-display metadata sync. When the new engine is
     // the dedicated AirPlay engine, hand the now-active session this engine's
     // ExoPlayer — registered in AirPlayEngine.init, so CastSinkRouter.player()
@@ -2489,7 +2719,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun setPlaybackSpeed(rate: Double): Promise<Unit> =
     Promise.async {
       onMain {
-        // Mirror `seekToInternal:890` non-finite guard. NaN →
+        // Mirror `seekToInternal`'s non-finite guard. NaN →
         // undefined ExoPlayer audio behaviour at the AudioSink;
         // ±Infinity → IllegalArgumentException from
         // `PlaybackParameters` constructor.
@@ -2537,7 +2767,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun setVolume(volume: Double): Promise<Unit> =
     Promise.async {
       onMain {
-        // Mirror `seekToInternal:890` non-finite guard. NaN →
+        // Mirror `seekToInternal`'s non-finite guard. NaN →
         // undefined audio output; ±Infinity → ditto.
         if (!volume.isFinite()) return@onMain
         if (com.margelo.nitro.queueplayer.cast.CastTransportRouter.routeSetVolume(volume.toFloat())) return@onMain
@@ -2840,13 +3070,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // resume after the rebuild.
     val wasPlaying = p.isPlaying
 
-    // Kotlin stdlib `shuffled()` is Fisher-Yates (documented).
-    val newTracks = tracks.shuffled()
+    // Shuffle positions rather than tracks: the permutation is what
+    // onQueueChange reports, and it cannot be recovered from the reordered
+    // list afterwards. Kotlin stdlib `shuffled()` is Fisher-Yates (documented).
+    val order = tracks.indices.shuffled()
+    val newTracks = order.map { tracks[it] }
 
     this.tracks = newTracks
     this.currentTrackIndex = 0
     pendingTrackChangeReason = TrackChangeReason.QUEUE_REPLACED
     // Destructive shuffle replaces every position; reset retry budget.
+    cancelPendingRetry()
     val attempts = effectiveAutoRetries()
     retryAttemptsRemaining.clear()
     for (i in newTracks.indices) retryAttemptsRemaining[i] = attempts
@@ -2864,7 +3098,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     rescheduleLookahead()
     recomputeCapabilities()
     // Skip a single-track shuffle — the order can't change.
-    if (newTracks.size > 1) emitQueueChange(QueueChangeReason.SHUFFLE)
+    if (newTracks.size > 1) emitQueueChange(QueueChangeReason.SHUFFLE, order = order)
 
     return ShuffleResult(
       tracks = newTracks.toTypedArray(),
@@ -2920,11 +3154,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     )
   }
 
-  // No `syncMain` hop on the next 3 getters: each reads a single
+  // No `syncMain` hop on the next five getters: each reads a single
   // `@Volatile` field that is only written on main, so the JVM
   // memory model gives the cross-thread happens-before edge for
-  // free. iOS uses `onMainSync` because Swift has no `@Volatile`-
-  // equivalent storage class.
+  // free. iOS hops through `onPlayerQueueSync` instead: its state is
+  // confined to `playerQueue`, and Swift has no `@Volatile`-equivalent
+  // storage class.
   override fun getCurrentTrackIndex(): Double = currentTrackIndex.toDouble()
 
   override fun getCurrentTrackSource(): TrackSource? = currentTrackSource
@@ -2968,26 +3203,48 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   override fun onQueueChange(
-    callback: (queue: Array<TrackItem>, currentIndex: Double, reason: QueueChangeReason) -> Unit
+    callback: (delta: QueueChangeDelta, currentIndex: Double, reason: QueueChangeReason) -> Unit
   ): () -> Unit {
     val id = queueChangeListeners.add(callback)
     return { queueChangeListeners.remove(id) }
   }
 
   /**
-   * Fire onQueueChange with an atomic snapshot of the post-mutation
-   * queue + current index. Main-thread only — every queue mutation
-   * commits on main, so [tracks] / [currentTrackIndex] are settled here.
-   * Callers gate this on an actual content/order change so a no-op
-   * mutation never emits.
+   * Emit a queue change as a description of what happened rather than a copy of
+   * the queue. Callers pass only the fields their mutation defines; the rest
+   * stay empty, and `revision` lets a subscriber notice a dropped event.
+   * Main-thread only — every queue mutation commits on main, so [tracks] /
+   * [currentTrackIndex] are settled here. Callers gate this on an actual
+   * content/order change so a no-op mutation never emits.
    */
   @MainThread
-  private fun emitQueueChange(reason: QueueChangeReason) {
-    val snapshot = tracks.toTypedArray()
+  private fun emitQueueChange(
+    reason: QueueChangeReason,
+    inserted: Array<TrackItem> = emptyArray(),
+    insertedAt: Int = -1,
+    removed: List<Int> = emptyList(),
+    movedFrom: Int = -1,
+    movedTo: Int = -1,
+    order: List<Int> = emptyList()
+  ) {
+    queueRevision += 1
+    val delta = QueueChangeDelta(
+      revision = queueRevision.toDouble(),
+      length = tracks.size.toDouble(),
+      inserted = inserted,
+      insertedAt = insertedAt.toDouble(),
+      removed = removed.map { it.toDouble() }.toDoubleArray(),
+      movedFrom = movedFrom.toDouble(),
+      movedTo = movedTo.toDouble(),
+      order = order.map { it.toDouble() }.toDoubleArray()
+    )
     val index = currentTrackIndex.toDouble()
-    queueChangeListeners.forEach { it(snapshot, index, reason) }
+    queueChangeListeners.forEach { it(delta, index, reason) }
   }
 
+  /** Increments once per queue-change emit; a gap tells a subscriber it missed one. */
+  private var queueRevision: Long = 0
+
   override fun onProgress(
     callback: (progress: PlayerProgress) -> Unit
   ): () -> Unit {
@@ -3149,15 +3406,11 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * drained). Post-bind: registers immediately. Either way the
    * returned disposer matches the consumer's expectation that
    * calling it tears the registration down regardless of timing.
-   *
-   * Past failure: `bootstrap.ts` (demo) calls `registerPlaybackService`
-   * at bundle-load time, which fires every `onCarConnect` /
-   * `onPlayFromIdRequest` / etc. BEFORE `configure()` has bound the
-   * service. The old "?: NO_OP_DISPOSER" fallback silently dropped
-   * every registration; the carService thought it had wired up but
-   * the lib had nothing recorded, so Android Auto's later bind hit
-   * `dispatchCarConnect` with a null callback + timed out → AA
-   * "No items".
+   * `registerPlaybackService` may run before `configure()` resolves, and
+   * [serviceBinder] is null again between an OS service kill and the
+   * rebind (`onServiceDisconnected`); both cases queue here and are
+   * applied by [drainPendingBrowseRegistrations] on the next
+   * `onServiceConnected`.
    */
   private fun deferredRegister(
     register: (BrowseCallbackRegistry) -> () -> Unit
@@ -3203,14 +3456,39 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       }
     }
 
-  override fun getLookaheadCacheStatus(): CacheStatus =
-    syncMain { buildCacheStatusSnapshot() }
+  /**
+   * Asynchronous because the snapshot counts fully-cached entries, which walks
+   * every cache key and takes the cache's monitor per key — contended against
+   * the prefetch thread. Resolved off both the JS thread and the app looper;
+   * every field it reads is published for that.
+   */
+  override fun getLookaheadCacheStatus(): Promise<CacheStatus> =
+    Promise.async { buildCacheStatusSnapshot() }
 
+  /**
+   * Wipe the cache and resolve once it is actually gone.
+   *
+   * The delete is file IO, so it runs off the app looper; the promise resolves
+   * after it, because a consumer that awaits this and then reads
+   * `getLookaheadCacheStatus()` must not see the pre-wipe size.
+   */
   override fun clearLookaheadCache(): Promise<Unit> =
-    Promise.async { onMain { clearLookaheadCacheInternal() } }
+    Promise.async {
+      onMain { clearLookaheadCacheInternal() }?.join()
+      onMain { emitCacheStatus() }
+    }
 
   override fun onCacheStatusChange(callback: (status: CacheStatus) -> Unit): () -> Unit {
     val id = cacheStatusListeners.add(callback)
+    // Deliver the current status once. Otherwise a settings screen shows its
+    // placeholder until the next prefetch completes — which never happens for a
+    // fully-cached queue or a consumer running with prefetch off.
+    cacheIoScope.launch(cacheStatusDispatcher) {
+      val snapshot = buildCacheStatusSnapshot()
+      mainHandler.post {
+        if (cacheStatusListeners.contains(id)) callback(snapshot)
+      }
+    }
     return { cacheStatusListeners.remove(id) }
   }
 
@@ -3267,6 +3545,30 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
   override fun getReplayGainMode(): ReplayGainMode = ReplayGainConfig.getMode()
 
+  /**
+   * Hand a freshly-installed engine the reader for consumer-supplied
+   * ReplayGain. The engine holds no queue metadata of its own — it
+   * plays `MediaItem`s — so the lookup from a queue index back to the
+   * consumer's `TrackItem` lives here, where the canonical [tracks]
+   * list does.
+   *
+   * The lambda reads [tracks] on every invocation rather than closing
+   * over a snapshot, so a `setQueue` carrying corrected values is
+   * picked up by the next recompute. Called wherever an engine is
+   * installed — the configure-time rebuild and the playback-mode swap —
+   * because a fresh engine starts with no resolver.
+   */
+  private fun installSuppliedReplayGainResolver(engine: PlaybackEngine?) {
+    val resolver: (Int) -> SuppliedReplayGain? = { index ->
+      tracks.getOrNull(index)?.let { SuppliedReplayGain.from(it) }
+    }
+    when (engine) {
+      is GaplessEngine -> engine.suppliedReplayGainResolver = resolver
+      is CrossfadeEngine -> engine.suppliedReplayGainResolver = resolver
+      else -> Unit
+    }
+  }
+
   /**
    * Re-resolve the active item's format and emit if it differs from
    * the last cached value. Call sites: [Player.Listener.onMediaItemTransition]
@@ -3326,14 +3628,15 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * live — no configure() cycle needed:
    *
    * - `enabled` toggle:
-   *   - true → false: tears down the WRITER (no more proactive
-   *     prefetch). The CACHE stays alive — Media3's CacheDataSource
-   *     in the player's MediaSource.Factory still reads existing
-   *     entries, so disabling can't yank cache out from under
-   *     in-flight reads.
+   *   - true → false: tears down the WRITER (no more proactive prefetch)
+   *     and routes the player's reads to the origin from the next item
+   *     load; the item already loading keeps the source it opened. The
+   *     cache OBJECT stays alive (Media3 allows one per directory) but is
+   *     neither read nor written while disabled.
    *   - false → true: rebuilds the writer against the existing cache
-   *     (the cache is built at configure() regardless of `enabled`),
-   *     so caching turns on without a configure() cycle.
+   *     (the cache is built at configure() regardless of `enabled`) and
+   *     routes reads through it again, so caching turns on without a
+   *     configure() cycle.
    *
    * - `lookaheadCount` change: live update via
    *   `LookaheadCacheWriter.defaultLookaheadCount`. Applies on the
@@ -3355,8 +3658,17 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     val countChanged = newConfig.lookaheadCount != previous.lookaheadCount
     val enableChanged = newConfig.enabled != previous.enabled
-
-    // Disable → tear down WRITER only. Cache stays for player reads.
+    val cellularChanged =
+      (newConfig.allowsCellularAccess ?: true) != (previous.allowsCellularAccess ?: true)
+
+    // The player's reads follow the flag from the next item load: disabled
+    // means the origin, whatever the disk holds. The cache object stays —
+    // Media3 allows one instance per directory — but nothing reads or writes
+    // it until it is enabled again.
+    if (enableChanged) {
+      lookaheadCache?.servesPlayback = newConfig.enabled
+    }
+    // Disable → tear down the writer.
     if (enableChanged && !newConfig.enabled) {
       lookaheadCacheWriter?.release()
       lookaheadCacheWriter = null
@@ -3377,51 +3689,80 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
             networkTimeoutMs = MediaItemBuilder.effectiveNetworkTimeoutMs(
               config.networkTimeoutMs
             )
-          )
+          ),
+          isOnCellular = { cellularTransportMonitor?.isOnCellular == true }
         ).apply {
           defaultLookaheadCount =
             newConfig.lookaheadCount.toInt().coerceAtLeast(0)
+          allowsCellularAccess = newConfig.allowsCellularAccess ?: true
           onTrackProcessed = { onMainPostStatusEmit() }
         }
         rescheduleLookahead()
       }
     }
 
-    // Live count update — safe regardless of player lifecycle. Skipped when
-    // the enable branch above just rebuilt the writer (it already applied the
-    // new count + rescheduled), so a single enable+count change reschedules once.
+    // Live policy update — safe regardless of player lifecycle. `lookaheadCount`
+    // resizes the window; `allowsCellularAccess` decides whether the window is
+    // fetched at all, so turning it off empties it and cancels the prefetch in
+    // flight and turning it back on refills it. Both take effect on the single
+    // reschedule below. Skipped when the enable branch above just rebuilt the
+    // writer, which already applied both values and rescheduled.
     val writer = lookaheadCacheWriter
-    if (countChanged && !enableChanged && writer != null) {
-      writer.defaultLookaheadCount =
-        newConfig.lookaheadCount.toInt().coerceAtLeast(0)
+    if (!enableChanged && writer != null && (countChanged || cellularChanged)) {
+      if (countChanged) {
+        writer.defaultLookaheadCount =
+          newConfig.lookaheadCount.toInt().coerceAtLeast(0)
+      }
+      if (cellularChanged) {
+        writer.allowsCellularAccess = newConfig.allowsCellularAccess ?: true
+      }
       rescheduleLookahead()
     }
 
+    // `lookaheadCount` sizes the protected window, so a change to it must move
+    // the window even when the branches above did not reschedule — prefetch
+    // disabled leaves no writer, and a combined disable+count change skips the
+    // count branch entirely. The cache still evicts in both cases.
+    refreshCacheProtection()
     emitCacheStatus()
   }
 
+  /**
+   * Cancel the prefetch and wipe the cache, returning the job doing the file
+   * work so a caller can await it. Null when there is no cache to clear.
+   *
+   * The wipe is a per-resource delete walk, so it runs off the app looper.
+   * Cancelling the prefetch first is what keeps it from racing: a `CacheWriter`
+   * mid-write into a key just removed re-creates the entry seconds later.
+   *
+   * Deliberately does NOT call [rescheduleLookahead] — an immediate refill makes
+   * `clearLookaheadCache` impossible to observe at zero from JS, and "clear"
+   * means "wipe and stop" (the consumer re-triggers prefetch via
+   * setLookaheadCache, skipToIndex, or setQueue). Matches iOS.
+   */
+  @MainThread
   @VisibleForTesting
-  internal fun clearLookaheadCacheInternal() {
-    val cache = lookaheadCache ?: return
-    // Cancel any in-flight prefetch first so we don't race with the
-    // wipe (CacheWriter mid-write into a key we just removed would
-    // re-create the entry seconds later). We deliberately do NOT
-    // call rescheduleLookahead() here — an immediate refill makes
-    // `clearLookaheadCache` impossible to observe at zero from JS,
-    // and "clear" semantically means "wipe and stop" (consumer can
-    // re-trigger prefetch via setLookaheadCache, skipToIndex, or
-    // setQueue). Matches iOS.
+  internal fun clearLookaheadCacheInternal(): Job? {
+    val cache = lookaheadCache ?: return null
+    // Stops the blocking CacheWriter too, not just the coroutine. Its cancelled
+    // flag is polled between chunk reads, so a span already mid-write can still
+    // land after the wipe; this closes the window rather than eliminating it.
     lookaheadCacheWriter?.cancel()
-    cache.clear()
-    emitCacheStatus()
+    // File work only. Emitting from in here would make the job depend on the
+    // main thread, which deadlocks anyone awaiting it with a blocking wait on
+    // that thread. The caller emits instead.
+    return cacheIoScope.launch { cache.clear() }
   }
 
   /**
    * Build a [CacheStatus] snapshot from the current cache + writer
-   * state. Synchronous — called inside `syncMain` from
-   * [getLookaheadCacheStatus].
+   * state. Called off the app looper — from the `Promise.async` pool
+   * (`getLookaheadCacheStatus`) and the serialised cache-status IO
+   * dispatcher (`emitCacheStatus` / `onCacheStatusChange`); reads
+   * `lookaheadCache` / `lookaheadCacheWriter` as @Volatile snapshots.
    */
-  private fun buildCacheStatusSnapshot(): CacheStatus {
+  @VisibleForTesting
+  internal fun buildCacheStatusSnapshot(): CacheStatus {
     val cache = lookaheadCache
     val writer = lookaheadCacheWriter
     val currentSizeBytes = cache?.currentSizeBytes() ?: 0L
@@ -3444,21 +3785,32 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     )
   }
 
-  /** Fire the cache-status listeners with a fresh snapshot. Called on main. */
+  /**
+   * Fire the cache-status listeners with a fresh snapshot. Called from main
+   * and from the writer's IO thread (`onTrackProcessed`); the registry is
+   * copy-on-write and the listeners run on main either way.
+   */
   private fun emitCacheStatus() {
     if (cacheStatusListeners.isEmpty) return
-    val snapshot = buildCacheStatusSnapshot()
-    cacheStatusListeners.forEach { it(snapshot) }
+    // Built off the app looper. The snapshot counts fully-cached entries,
+    // which walks every cache key and takes the cache's monitor per key —
+    // contended against the prefetch thread that is committing downloads —
+    // and this fires after every prefetch iteration whenever a consumer is
+    // subscribed. Listeners are still called on the looper they expect.
+    cacheIoScope.launch(cacheStatusDispatcher) {
+      val snapshot = buildCacheStatusSnapshot()
+      mainHandler.post { cacheStatusListeners.forEach { it(snapshot) } }
+    }
   }
 
   /**
-   * Hop to main + emit a cache-status snapshot. Bound to the writer's
-   * `onTrackProcessed` hook so post-download status updates are
-   * always dispatched on main even though the writer's coroutine
-   * runs on Dispatchers.IO.
+   * Emit a cache-status snapshot. Bound to the writer's `onTrackProcessed`
+   * hook, so it fires once per prefetched track.
    */
   private fun onMainPostStatusEmit() {
-    mainHandler.post { emitCacheStatus() }
+    // `emitCacheStatus` does its own hopping — off the looper to build, back
+    // onto it to deliver — so there is nothing to post first.
+    emitCacheStatus()
   }
 
   // --- Events — observer wiring + dispatch
@@ -3489,12 +3841,25 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   private fun tearDownEventObservers() {
+    // A retry posted before teardown would otherwise land on a released engine.
+    // Cancelled here rather than in stopProgressTick, which also runs when the
+    // last progress subscriber unsubscribes — a screen unmounting must not kill
+    // an in-flight retry.
+    cancelPendingRetry()
     // Clear the delegate from the engine TrackPlayer last wired
     // itself onto, even if [serviceBinder] has been re-bound to a
     // fresh engine since.
     engineDelegateRegistration?.let { engine ->
       if (engine.delegate === this) engine.delegate = null
     }
+    // And from whatever engine is bound now. A playback-mode swap carries the
+    // delegate across to the incoming engine without this registration
+    // following it, so clearing only the remembered one unwires an engine
+    // that has already been released and leaves the live one still
+    // delivering into a torn-down player.
+    serviceBinder?.engine?.let { engine ->
+      if (engine.delegate === this) engine.delegate = null
+    }
     engineDelegateRegistration = null
     stopProgressTick()
   }
@@ -3568,8 +3933,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     p.replaceMediaItem(idx, updated)
   }
 
-  override fun onError(engine: PlaybackEngine, exception: PlaybackException) {
-    handlePlayerError(exception)
+  override fun onError(
+    engine: PlaybackEngine, exception: PlaybackException, failedIndex: Int
+  ) {
+    handlePlayerError(exception, failedIndex)
   }
 
   override fun onPlaybackEnded(engine: PlaybackEngine) {
@@ -3595,12 +3962,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     currentTrackIndex = incomingIndex
     lastErrorKey = null
     val track = tracks[incomingIndex]
-    val cache = lookaheadCache
-    currentTrackSource = classifyTrackSource(track.url) { url ->
-      cache?.isFullyCached(url) == true
-    }
+    currentTrackSource = classifyTrackSource(track.url, ::servedFromCache)
     crossfadeFadeStartEmittedIdx = incomingIndex
     pendingTrackChangeReason = null
+    logPlaybackSource(track.url)
     // New active track => new milestone playthrough (the matching
     // structural transition echo is deduped in handleMediaItemTransition).
     milestoneTracker.reset()
@@ -3612,6 +3977,26 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     rescheduleLookahead()
   }
 
+  /**
+   * Records what the player is actually reading for the active track.
+   *
+   * The reported source says whether the file is on disk; it does not say the
+   * bytes reaching the decoder came from there. Media3 reads through
+   * [LookaheadCache]'s CacheDataSource, so a rising cached-bytes total is the
+   * proof that playback is being served from the cache rather than the origin.
+   */
+  private fun logPlaybackSource(url: String?) {
+    // Debug builds only, and never the query string: stream URLs carry auth
+    // tokens there, and logcat is readable by every app on older devices.
+    if (!BuildConfig.DEBUG) return
+    val cachedBytes = lookaheadCache?.cachedBytesReadTotal?.get() ?: 0L
+    Log.i(
+      DIAG_TAG,
+      "now-playing source=$currentTrackSource cachedBytesRead=$cachedBytes " +
+        "url=${url?.let(PlaybackErrorMapping::stripQuery)}"
+    )
+  }
+
   override fun onCrossfadeCancel(engine: PlaybackEngine, revertedIndex: Int) {
     // Fade-cancelled mid-flight (pause / stop / focus loss / queue
     // mutation). JS already received `onTrackChange(incoming,
@@ -3625,10 +4010,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     lastErrorKey = null
     crossfadeFadeStartEmittedIdx = null
     val track = tracks[revertedIndex]
-    val cache = lookaheadCache
-    currentTrackSource = classifyTrackSource(track.url) { url ->
-      cache?.isFullyCached(url) == true
-    }
+    currentTrackSource = classifyTrackSource(track.url, ::servedFromCache)
     pendingTrackChangeReason = null
     trackChangeListeners.forEach {
       it(track, revertedIndex.toDouble(), TrackChangeReason.CROSSFADE_CANCELLED, null)
@@ -3642,7 +4024,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     val now = System.nanoTime()
     gaplessGapPrevEndedAtNs = now
     if (BuildConfig.DEBUG) {
-      gaplessLogLastEndedAtNs = now
       Log.d(
         GAPLESS_LOG_TAG,
         "item-ended trackIdx=$currentTrackIndex ts_ns=$now"
@@ -3650,7 +4031,6 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     }
   }
 
-
   /**
    * Translate Media3 playback state + playWhenReady + suppression
    * reason into our [PlayerState] enum and fire [stateChangeListeners]
@@ -3728,7 +4108,12 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (index == currentTrackIndex) return
     currentTrackIndex = index
     val track = tracks[index]
+    // No engine call happens on this path, so nothing downstream
+    // reclassifies the source or recomputes the skip capability the
+    // way handleMediaItemTransition does for a local advance.
+    currentTrackSource = classifyTrackSource(track.url, ::servedFromCache)
     trackChangeListeners.forEach { it(track, index.toDouble(), TrackChangeReason.AUTO_ADVANCE, null) }
+    recomputeCapabilities()
   }
 
   /**
@@ -3748,6 +4133,19 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     fireEndOfTrackSleepTimer()
     queueEndListeners.forEach { it() }
     emitState(PlayerState.ENDED, StateChangeReason.QUEUE_END)
+    // Park the engine. Reaching the end of the queue is not the same as being
+    // paused — `playWhenReady` stays set through STATE_ENDED — so a queue
+    // installed afterwards would start playing without anyone asking. Repeat
+    // modes wrap without ever reaching STATE_ENDED, so they are unaffected.
+    serviceBinder?.engine?.pause()
+    // The intent to play ends with the queue: nothing that seats a track from
+    // here — a skip, a seek, a fresh queue, an engine swap — starts it until
+    // play() is called again.
+    wantsToPlay = false
+    // The pause's inline callback stamps USER_REQUEST; ENDED is already
+    // reported, so that emit deduplicates and the stamp would label the next
+    // terminal emit a user action. Nobody asked for this pause.
+    pendingStateChangeReason = null
   }
 
   /**
@@ -3764,6 +4162,16 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    *   (user-skip), else fallback to [TrackChangeReason.SEEK]
    * - REASON_PLAYLIST_CHANGED → [TrackChangeReason.QUEUE_REPLACED]
    */
+  /**
+   * Whether playback of [url] is served from the disk cache: the cache
+   * holds the whole file AND is enabled. Disabled, every read goes to the
+   * origin whatever the disk holds, so a complete copy does not make the
+   * track `CACHED`. An item whose data source opened before a toggle keeps
+   * that source, so its report can differ from the flag for that one item.
+   */
+  private fun servedFromCache(url: String): Boolean =
+    lookaheadConfig.enabled && lookaheadCache?.isFullyCached(url) == true
+
   @VisibleForTesting
   internal fun handleMediaItemTransition(reason: Int) {
     val p = player ?: return
@@ -3782,10 +4190,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     // iOS reset in `handleCurrentItemDidChange`.
     lastErrorKey = null
     val track = if (currentTrackIndex in tracks.indices) tracks[currentTrackIndex] else null
-    val cache = lookaheadCache
-    currentTrackSource = classifyTrackSource(track?.url) { url ->
-      cache?.isFullyCached(url) == true
-    }
+    currentTrackSource = classifyTrackSource(track?.url, ::servedFromCache)
 
     // Crossfade post-swap echo: fade-start already fired
     // `onCrossfadeBegin` which dispatched the JS-facing track-
@@ -3884,20 +4289,84 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * reschedule the proactive prefetcher after a
    * queue/skip mutation. Reads `tracks` + `currentTrackIndex` (both
    * @Volatile) and dispatches the next N remote tracks to
-   * [LookaheadCacheWriter]. No-op when the writer hasn't been built
-   * (configure not yet called).
+   * [LookaheadCacheWriter]. Always refreshes cache protection; the prefetch
+   * dispatch is skipped when the writer hasn't been built (configure not yet
+   * called, or prefetch disabled).
    */
   @MainThread
   private fun rescheduleLookahead() {
+    // Ahead of the writer guard on purpose: the cache is built at configure()
+    // regardless of `lookaheadConfig.enabled`, so a consumer with prefetch off
+    // still has a live cache that evicts, and it would otherwise run with an
+    // empty protected set.
+    refreshCacheProtection()
     val writer = lookaheadCacheWriter ?: return
     writer.reschedule(tracks, currentTrackIndex)
   }
 
+  /**
+   * Tell the cache which entries eviction must not take: the playing track, the
+   * tracks being prefetched ahead of it, and one behind for an immediate
+   * skip-back.
+   *
+   * Bounded deliberately — protecting the whole remaining queue would leave
+   * nothing evictable and turn each commit into a cache wipe.
+   */
+  @MainThread
+  private fun refreshCacheProtection() {
+    val cache = lookaheadCache ?: return
+    // Under LRU the set is discarded, and this runs on every queue mutation.
+    if (!cache.honoursProtection) return
+    val cur = currentTrackIndex
+    if (cur < 0 || cur >= tracks.size) {
+      cache.setProtectedUrls(emptySet())
+      return
+    }
+    // The count arrives from JS as a Double, so Infinity and NaN are reachable.
+    // Both survive `toInt()` as Int.MAX_VALUE / 0, and `cur + Int.MAX_VALUE`
+    // wraps negative, which would make the subList bounds throw on main.
+    // Bounded by MAX_PROTECTED_AHEAD as well as by the queue: a consumer count
+    // at or above the queue length would protect every entry, leaving the
+    // evictor nothing to reclaim and the cache growing past its budget with no
+    // ceiling. The window that matters is the one around the playhead.
+    val ahead = lookaheadConfig.lookaheadCount
+      .takeIf { it.isFinite() }
+      ?.toInt()
+      ?.coerceIn(0, minOf(tracks.size, MAX_PROTECTED_AHEAD))
+      ?: 0
+    val lower = (cur - 1).coerceAtLeast(0)
+    val upper = (cur + ahead).coerceAtMost(tracks.size - 1)
+    cache.setProtectedUrls(tracks.subList(lower, upper + 1).map { it.url }.toSet())
+  }
+
   private fun syncCurrentTrackIndexFromPlayer(p: ExoPlayer) {
     val playerIndex = p.currentMediaItemIndex
     currentTrackIndex = if (playerIndex in tracks.indices) playerIndex else -1
   }
 
+  /** Scheduled auto-retry, held so teardown can cancel it. */
+  private var pendingRetryRunnable: Runnable? = null
+
+  /**
+   * Track index whose automatic attempt is scheduled but has not run yet. A
+   * failure naming it is an echo of the one being retried, so it is not
+   * reported while the attempt is still owed.
+   */
+  private var pendingRetryIndex: Int = -1
+
+  /**
+   * Drop a scheduled automatic attempt.
+   *
+   * Called wherever the queue changes, because the attempt is keyed by
+   * position: after a mutation that index names a different track, and both
+   * the attempt itself and the echo suppression would then be aimed at it.
+   */
+  private fun cancelPendingRetry() {
+    pendingRetryRunnable?.let { mainHandler.removeCallbacks(it) }
+    pendingRetryRunnable = null
+    pendingRetryIndex = -1
+  }
+
   /**
    * Translate [PlaybackException] into a [PlaybackError] + emit on
    * both [errorListeners] and as a terminal ERROR state. Mirrors iOS
@@ -3905,27 +4374,48 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * conditions surface as non-fatal so consumers can offer retry
    * UX; codec / decoding errors surface as fatal.
    */
-  private fun handlePlayerError(error: PlaybackException) {
+  private fun handlePlayerError(error: PlaybackException, failedIndex: Int = -1) {
     val mapped = PlaybackErrorMapping.classify(error)
-    // Dedup by (currentTrackIndex, standardized code). Mirrors iOS
+    // Attribute to the track that actually failed. Under crossfade the
+    // standby leg can fail while prerolling an upcoming track, and the
+    // leading leg plays on — keying any of the three uses below off
+    // currentTrackIndex would dedup against the wrong track, spend the wrong
+    // track's retry budget, and report the wrong url to the consumer.
+    val idx = if (failedIndex in tracks.indices) failedIndex else currentTrackIndex
+    // Dedup by (failing index, standardized code). Mirrors iOS
     // `(queueItemId, code)` dedup. ExoPlayer can fire onPlayerError
     // multiple times for a single failed item under retry storms.
-    val key = currentTrackIndex to mapped
+    val key = idx to mapped
+    // An echo of a failure whose attempt has not run yet belongs to that
+    // attempt, not to the consumer.
+    if (idx >= 0 && idx == pendingRetryIndex) return
     if (lastErrorKey == key) return
     lastErrorKey = key
     // Auto-retry path: transient errors with retries left
     // schedule a delayed `prepare()`. Skip the JS error emit + state
     // ERROR transition until retries exhausted; consumer sees onError
     // only when the lib has given up. Mirrors iOS path.
-    val idx = currentTrackIndex
+    // Only the track being played is retried. A standby leg's preroll failing
+    // is the *next* track failing to load early, and the cancel that precedes
+    // the report reverts `currentTrackIndex` to the leading track, so an
+    // attempt scheduled for it could never run. Surfacing it instead is both
+    // honest and harmless: when that track becomes current it is loaded fresh
+    // and gets its own automatic attempt then.
     if (idx >= 0 &&
+        idx == currentTrackIndex &&
         PlaybackErrorMapping.isTransient(mapped) &&
         (retryAttemptsRemaining[idx] ?: 0) > 0) {
       retryAttemptsRemaining[idx] = retryAttemptsRemaining[idx]!! - 1
       // Clear dedup so the retry-then-fail (if any) fires fresh.
       lastErrorKey = null
       val backoff = effectiveRetryBackoffMs()
-      mainHandler.postDelayed({ retryFailedItem(idx) }, backoff.toLong())
+      // Hold the runnable so teardown can drop it. A retry posted moments
+      // before destroy() would otherwise fire against a released engine.
+      pendingRetryRunnable?.let { mainHandler.removeCallbacks(it) }
+      val retry = Runnable { retryFailedItem(idx) }
+      pendingRetryRunnable = retry
+      pendingRetryIndex = idx
+      mainHandler.postDelayed(retry, backoff.toLong())
       return
     }
     // Surface the failing track's URL so consumers can correlate the
@@ -3939,16 +4429,22 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
       error, mapped, queueItemId = "", url = failedUrl,
     )
     errorListeners.forEach { it(err) }
-    emitState(PlayerState.ERROR, StateChangeReason.ERROR)
+    // The state is the current track's. A standby leg's preroll failing is
+    // reported above and leaves the leading leg playing; announcing ERROR for
+    // it would put a terminal state under audio that is still running, and
+    // the next engine callback would flip it straight back to PLAYING.
+    if (idx == currentTrackIndex) {
+      emitState(PlayerState.ERROR, StateChangeReason.ERROR)
+    }
   }
 
   // --- Auto-retry + stuck-recovery
 
   /** Lib-clamped auto-retry budget. Reads from `config.autoRetries`,
-   *  defaults to 3, clamps to [0, 5]. */
+   *  defaults to 1, clamps to [0, 5]. */
   @VisibleForTesting
   internal fun effectiveAutoRetries(): Int =
-    (config.autoRetries?.toInt() ?: 3).coerceIn(0, 5)
+    (config.autoRetries?.toInt() ?: 1).coerceIn(0, 5)
 
   /** Lib-clamped retry backoff in milliseconds. Defaults to 500,
    *  clamps to [200, 5000]. Floor at 200ms prevents retry storms
@@ -3959,28 +4455,41 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
   /** Try to recover from a transient failure by re-preparing the
    *  ExoPlayer at the current position. Called from
-   *  [handlePlayerError] (auto-retry) AND from [play] (one-shot
-   *  stuck-recovery). Mirrors iOS `retryFailedItem` which does a
-   *  full AVQueuePlayer rebuild via `fullRebuildPlayerQueue`.
+   *  [handlePlayerError] (auto-retry) and from [retry] (the
+   *  consumer-facing one-shot). Mirrors iOS `retryFailedItem`, which
+   *  rebuilds the AVQueuePlayer via `fullRebuildPlayerQueue` and seeks
+   *  back to the captured position.
    *
-   *  Implementation: `setMediaItem(currentMediaItem, false) +
-   *  prepare()` rather than bare `prepare()` — the latter re-uses
-   *  the existing wedged DataSource on a "Cannot Open"-class
-   *  failure and may not actually recover. Re-setting the
-   *  MediaItem forces Media3 to construct a fresh DataSource from
-   *  the MediaSource.Factory (carries the current `httpFactory`
-   *  + cache wrapper). `resetPosition=false` preserves the
-   *  current playback position; iOS rebuild resets to 0 (mid-play
-   *  failure loses position regardless). For initial-load failures
-   *  the position is 0 anyway, so the position-preservation here
-   *  is the only intentional iOS/Android divergence. */
+   *  Implementation: remove + re-add the failed item at its index,
+   *  `seekTo` the captured position, then `prepare()` — rather than
+   *  bare `prepare()`, which re-uses the existing wedged DataSource
+   *  on a "Cannot Open"-class failure and may not actually recover.
+   *  Re-adding the item forces Media3 to construct a fresh DataSource
+   *  from the MediaSource.Factory (carries the current `httpFactory`
+   *  + cache wrapper). */
   internal fun retryFailedItem(atIndex: Int) {
-    val p = player ?: return
-    // Verify the failed item is still the current one. This also bounds the
-    // rebuild to the leading leg's active item: mid-fade the leading leg is
-    // the OUTGOING track, whose index differs from currentTrackIndex (the
-    // fade-flipped incoming track), so a retry mid-fade is skipped here.
+    // The attempt has arrived, so whatever fails next is a new failure rather
+    // than an echo of the one being retried. A scheduled attempt for the same
+    // index is withdrawn with it: left posted, it would fire after the backoff
+    // and rebuild the track a second time behind a user's own retry.
+    if (pendingRetryIndex == atIndex) {
+      pendingRetryRunnable?.let { mainHandler.removeCallbacks(it) }
+      pendingRetryIndex = -1
+      pendingRetryRunnable = null
+    }
+    // The failed item must still be the current one; a skip or a queue mutation
+    // since the failure makes the retry moot. Checked before the fade is
+    // settled, because settling is an audible cut and a retry that is about to
+    // return has no business making one.
     if (atIndex != currentTrackIndex) return
+    // Settle a fade before reading the player. `player` is the leading leg,
+    // which mid-fade holds the OUTGOING track while `currentTrackIndex` has
+    // already flipped to the incoming one — so every read below would describe
+    // a different track than the index check just approved, and a retry would
+    // rebuild and restart the track the user is leaving. Promoting first makes
+    // the leading leg the track being heard, which is the one a retry is for.
+    serviceBinder?.engine?.settlePendingFadeByPromoting()
+    val p = player ?: return
     val current = p.currentMediaItem
     if (current != null) {
       val idx = p.currentMediaItemIndex
@@ -4002,10 +4511,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     } else {
       p.prepare()
     }
-    // Resume playback if the user had been playing pre-failure.
-    // (Live-state check; the pre-failure playWhenReady wasn't
-    // captured)
-    if (!p.isPlaying) serviceBinder?.engine?.play()
+    // Resume only if playback is wanted NOW, not at failure time: a manual
+    // retry() carries no failure-time flag, and a pause during the retry
+    // backoff must win over the state the failure was scheduled under.
+    if (wantsToPlay && !p.isPlaying) serviceBinder?.engine?.play()
   }
 
   /**
@@ -4268,13 +4777,13 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     if (Looper.myLooper() == Looper.getMainLooper()) {
       body()
     } else {
-      val latch = CountDownLatch(1)
+      val done = CountDownLatch(1)
       var err: Throwable? = null
       mainHandler.post {
         try { body() } catch (t: Throwable) { err = t }
-        latch.countDown()
+        done.countDown()
       }
-      latch.await()
+      done.await()
       err?.let { throw it }
     }
   }
@@ -4299,18 +4808,45 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   companion object {
+    /** Prefs holding the eviction policy the on-disk cache was built with. */
+    private const val CACHE_PREFS_NAME = "rnqp_lookahead_cache"
+    private const val KEY_EVICTION_POLICY = "eviction_policy"
+
+    /** Marks a cache directory renamed aside and awaiting deletion. */
+    private const val DELETING_DIR_SUFFIX = ".deleting-"
+
+    /**
+     * Renamed cache directories this process is currently deleting.
+     *
+     * The sweep collects anything wearing the deleting- prefix, which is
+     * exactly the name a discard just produced — so without this it starts a
+     * second delete of a tree already being deleted, with a second database
+     * provider dropping the same index tables underneath the first.
+     *
+     * Process-wide because the cache is: a second [TrackPlayer] configured in
+     * the same process sweeps the same directory. Held only while a delete is
+     * in flight, so a directory abandoned by a previous process — the case the
+     * sweep exists for — is never claimed and is always collected.
+     */
+    private val doomedCacheDirectories = java.util.Collections.synchronizedSet(
+      mutableSetOf<String>())
+
+    private fun claimDoomedDirectory(dir: java.io.File) {
+      doomedCacheDirectories.add(dir.absolutePath)
+    }
+
+    private fun releaseDoomedDirectory(dir: java.io.File) {
+      doomedCacheDirectories.remove(dir.absolutePath)
+    }
+
+    private fun isDoomedDirectoryClaimed(dir: java.io.File): Boolean =
+      doomedCacheDirectories.contains(dir.absolutePath)
+
     /** Progress tick cadence — matches iOS 2 Hz. */
     private const val PROGRESS_TICK_INTERVAL_MS = 500L
     /** Sleep-timer countdown/fade cadence — 500ms gives a smooth 10s fade. */
     private const val SLEEP_TIMER_TICK_INTERVAL_MS = 500L
 
-    /**
-     * Disposer returned from `on*Request` registrations when the
-     * `PlaybackService` isn't bound yet. Calling it is a no-op —
-     * the registration never landed, so there's nothing to clear.
-     */
-    private val NO_OP_DISPOSER: () -> Unit = {}
-
     /** Tolerance for "bufferedPosition has reached duration" — a CBR-estimated
      *  duration or rounding can leave a sub-second gap when fully downloaded. */
     private const val FULLY_BUFFERED_EPSILON_MS = 1000L
@@ -4320,6 +4856,15 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
      *  reference one named constant. */
     private const val MS_PER_SECOND = 1000.0
 
+    /**
+     * Upper bound on how far ahead of the playhead cache eviction is blocked.
+     *
+     * Independent of the consumer's lookahead count on purpose: protecting the
+     * whole queue leaves the evictor nothing to reclaim, and the cache then
+     * grows past its budget with no ceiling.
+     */
+    private const val MAX_PROTECTED_AHEAD = 10
+
     /**
      * Tag for the verbose gapless-transition logs (item-ended /
      * item-changed / playing). All emit sites are guarded by
@@ -4328,6 +4873,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
      */
     private const val GAPLESS_LOG_TAG = "RNQP-GAPLESS"
 
+    /** Playback-source diagnostics: what the player actually reads from. */
+    private const val DIAG_TAG = "RNQP-DIAG"
+
     /** Logcat tag for player-level lifecycle warnings. Part of the
      * `QueuePlayer.<area>` hierarchy used across the lib's Android
      * sources. */
@@ -4347,6 +4895,26 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
     var current: TrackPlayer? = null
       private set
 
+    init {
+      // One process-wide listener on the cast route, forwarding to whichever
+      // instance is configured. Push-PCM sessions (AirPlay 1/2) force-degrade
+      // the active engine from Crossfade to Gapless because the wire protocol
+      // cannot mix two ExoPlayers into one sink; clearing the session
+      // re-applies the user's requested mode (so crossfade re-instates).
+      // Registered once here rather than per instance: `CastSinkRouter` is a
+      // process-wide object, and a per-instance listener kept every instance
+      // ever constructed reachable and ran the swap on all of them.
+      com.margelo.nitro.queueplayer.cast.CastSinkRouter.addRouteChangeListener { _ ->
+        val player = current ?: return@addRouteChangeListener
+        // Re-apply against the user's requested mode on every flip.
+        // `applyEngineSwapForMode` consults `CastSinkRouter.isRemoteActive`
+        // for the degrade decision, so the swap settles to the right
+        // engine for the new route state.
+        val mode = player.playbackModeState.active
+        player.mainHandler.post { player.applyEngineSwapForMode(mode) }
+      }
+    }
+
     /**
      * Classify the active-track playback source. `null` when the URL
      * is null or its scheme is neither `file://` nor `http(s)://`