react-native-audio-browser 0.1.1 → 0.2.0-next.10

package/android/src/main/java/com/audiobrowser/AudioBrowser.kt

@@ -8,6 +8,7 @@ import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
 import androidx.annotation.Keep
+import androidx.car.app.connection.CarConnection
 import androidx.lifecycle.DefaultLifecycleObserver
 import androidx.lifecycle.LifecycleOwner
 import androidx.lifecycle.ProcessLifecycleOwner
@@ -15,38 +16,41 @@ import androidx.media3.session.MediaBrowser
 import androidx.media3.session.SessionToken
 import com.audiobrowser.browser.BrowserConfig
 import com.audiobrowser.browser.BrowserManager
-import com.audiobrowser.browser.handleTrackLoad
 import com.audiobrowser.browser.CallbackException
 import com.audiobrowser.browser.ContentNotFoundException
 import com.audiobrowser.browser.HttpStatusException
 import com.audiobrowser.browser.NetworkException
+import com.audiobrowser.browser.handleTrackLoad
+import com.audiobrowser.browser.resolveMediaUrl
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
-import com.audiobrowser.http.RequestConfigBuilder
-import com.audiobrowser.model.PlaybackMetadata
 import com.audiobrowser.model.PlayerSetupOptions
 import com.audiobrowser.model.PlayerUpdateOptions
+import com.audiobrowser.player.Player
 import com.audiobrowser.util.BatteryOptimizationHelper
 import com.audiobrowser.util.BatteryWarningStore
 import com.audiobrowser.util.BrowserPathHelper
-import com.audiobrowser.util.CoilBitmapLoader
+import com.audiobrowser.util.OutputMonitor
+import com.audiobrowser.util.OutputSwitcher
 import com.audiobrowser.util.SystemVolumeMonitor
 import com.facebook.proguard.annotations.DoNotStrip
 import com.google.common.util.concurrent.ListenableFuture
 import com.margelo.nitro.NitroModules
-import com.margelo.nitro.audiobrowser.ChapterMetadata
-import com.margelo.nitro.audiobrowser.TimedMetadata
-import com.margelo.nitro.audiobrowser.TrackMetadata
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatus
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatusChangedEvent
 import com.margelo.nitro.audiobrowser.BatteryWarningPendingChangedEvent
+import com.margelo.nitro.audiobrowser.ChapterMetadata
 import com.margelo.nitro.audiobrowser.EqualizerSettings
 import com.margelo.nitro.audiobrowser.FavoriteChangedEvent
 import com.margelo.nitro.audiobrowser.FormatNavigationErrorParams
 import com.margelo.nitro.audiobrowser.FormattedNavigationError
+import com.margelo.nitro.audiobrowser.Gate
+import com.margelo.nitro.audiobrowser.GateDecision
+import com.margelo.nitro.audiobrowser.GateEvent
 import com.margelo.nitro.audiobrowser.HybridAudioBrowserSpec
-import com.margelo.nitro.audiobrowser.IosOutput
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
 import com.margelo.nitro.audiobrowser.NativeBrowserConfiguration
+import com.margelo.nitro.audiobrowser.NativeGateRequest
+import com.margelo.nitro.audiobrowser.NativeSetupPlayerOptions
 import com.margelo.nitro.audiobrowser.NativeUpdateOptions
 import com.margelo.nitro.audiobrowser.NavigationError
 import com.margelo.nitro.audiobrowser.NavigationErrorEvent
@@ -54,7 +58,7 @@ import com.margelo.nitro.audiobrowser.NavigationErrorType
 import com.margelo.nitro.audiobrowser.NowPlayingMetadata
 import com.margelo.nitro.audiobrowser.NowPlayingUpdate
 import com.margelo.nitro.audiobrowser.Options
-import com.margelo.nitro.audiobrowser.PartialSetupPlayerOptions
+import com.margelo.nitro.audiobrowser.Output
 import com.margelo.nitro.audiobrowser.Playback
 import com.margelo.nitro.audiobrowser.PlaybackActiveTrackChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackError
@@ -62,6 +66,7 @@ import com.margelo.nitro.audiobrowser.PlaybackErrorEvent
 import com.margelo.nitro.audiobrowser.PlaybackPlayWhenReadyChangedEvent
 import com.margelo.nitro.audiobrowser.PlaybackProgressUpdatedEvent
 import com.margelo.nitro.audiobrowser.PlaybackQueueEndedEvent
+import com.margelo.nitro.audiobrowser.PlaybackState
 import com.margelo.nitro.audiobrowser.PlayingState
 import com.margelo.nitro.audiobrowser.Progress
 import com.margelo.nitro.audiobrowser.RemoteJumpBackwardEvent
@@ -69,25 +74,25 @@ import com.margelo.nitro.audiobrowser.RemoteJumpForwardEvent
 import com.margelo.nitro.audiobrowser.RemotePlayIdEvent
 import com.margelo.nitro.audiobrowser.RemotePlaySearchEvent
 import com.margelo.nitro.audiobrowser.RemoteSeekEvent
-import com.margelo.nitro.audiobrowser.RemoteSetRatingEvent
 import com.margelo.nitro.audiobrowser.RemoteSkipEvent
 import com.margelo.nitro.audiobrowser.RepeatMode
 import com.margelo.nitro.audiobrowser.RepeatModeChangedEvent
-import com.margelo.nitro.audiobrowser.RequestConfig
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.SleepTimer
+import com.margelo.nitro.audiobrowser.TimedMetadata
 import com.margelo.nitro.audiobrowser.Track
-import com.margelo.nitro.audiobrowser.UpdateOptions
+import com.margelo.nitro.audiobrowser.TrackMetadata
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.TimeUnit
+import java.util.concurrent.atomic.AtomicReference
 import kotlin.coroutines.resume
 import kotlin.coroutines.resumeWithException
 import kotlin.coroutines.suspendCoroutine
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.Job
 import kotlinx.coroutines.MainScope
+import kotlinx.coroutines.cancel
 import kotlinx.coroutines.cancelChildren
-import kotlinx.coroutines.delay
 import kotlinx.coroutines.launch
 import kotlinx.coroutines.runBlocking
 import timber.log.Timber
@@ -95,6 +100,58 @@ import timber.log.Timber
 @Keep
 @DoNotStrip
 class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
+
+  /**
+   * Nitro calls this only when JS calls `dispose()` explicitly — never on runtime teardown, which
+   * is what [AudioBrowserLifecycleModule] is for. Both routes land here.
+   *
+   * The Service outlives this object, so everything registered in `init` or on connect has to be
+   * undone. Left alone, the running [Player] goes on invoking callbacks into a dead JSI runtime,
+   * and every reload strands another ServiceConnection and lifecycle observer, each retaining a
+   * BrowserManager.
+   *
+   * Runs the teardown on main: the state below is written from main-thread coroutines
+   * ([onServiceConnected], [onServiceDisconnected]), while dispose itself arrives on the JS thread
+   * or the teardown callback's thread.
+   */
+  override fun dispose() {
+    current.compareAndSet(this, null)
+    systemVolumeMonitor.destroy()
+    outputMonitor.destroy()
+    // Only when still ours: on a reload the replacement may already own the slot.
+    carConnectionTarget.compareAndSet(onCarConnectedChanged, null)
+
+    handler.post {
+      connectedService?.let { service ->
+        // Identity-guarded: both instances bind to the same singleton Service, so a late dispose
+        // must not strip the wiring a replacement has already installed.
+        if (service.player.getCallbacks() === callbacks) service.player.setCallbacks(null)
+        if (service.player.browser === this) {
+          service.player.browser = null
+          service.player.forgetBrowserRegistration()
+        }
+        if (service.onBatteryWarningPendingChanged === onBatteryWarningPending) {
+          service.onBatteryWarningPendingChanged = null
+        }
+      }
+      connectedService = null
+
+      // Dropping the reference disconnects nothing — the controller stays in the session's
+      // connected list, holding a binder and a listener.
+      mediaBrowserFuture?.let { MediaBrowser.releaseFuture(it) }
+      mediaBrowserFuture = null
+      setupPromise = null
+
+      serviceBinding.unbind(this)
+
+      ProcessLifecycleOwner.get().lifecycle.removeObserver(lifecycleObserver)
+      // After the observer removal, so this post is not the one dropped.
+      handler.removeCallbacksAndMessages(null)
+      mainScope.cancel()
+    }
+    super.dispose()
+  }
+
   private val mainScope = MainScope()
   private var navigationJob: Job? = null
   private val handler = Handler(Looper.getMainLooper())
@@ -107,14 +164,18 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     NativeBrowserConfiguration(
       path = null,
       request = null,
+      requestResolver = null,
+      browse = null,
+      browseResolver = null,
       media = null,
       artwork = null,
+      nowPlayingArtwork = null,
       routes = null,
       singleTrack = null,
       handleTrackLoad = null,
       androidControllerOfflineError = null,
-      carPlayUpNextButton = null,
-      carPlayNowPlayingButtons = null,
+      carPlayLoadingTitle = null,
+      resolveAlbumUrl = null,
       formatNavigationError = null,
     )
 
@@ -123,17 +184,31 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       setOnPathChanged { path -> onPathChanged(path) }
       setOnContentChanged { content -> onContentChanged(content) }
       setOnTabsChanged { tabs -> onTabsChanged(tabs) }
+      setOnArtworkRegistriesCleared { connectedService?.player?.browseArtworkRegistry?.clear() }
     }
 
   private val systemVolumeMonitor = SystemVolumeMonitor(context)
+  private val outputMonitor = OutputMonitor(context)
 
   // MARK: Player state
   private var updateOptions: PlayerUpdateOptions = PlayerUpdateOptions()
   private var mediaBrowserFuture: ListenableFuture<MediaBrowser>? = null
   private var setupOptions = PlayerSetupOptions()
   private var connectedService: Service? = null
+
+  private val serviceBinding = ServiceBinding(context)
+
+  /** Held rather than inlined so [dispose] can tell its own wiring from a replacement's. */
+  private val onBatteryWarningPending: (Boolean) -> Unit = { pending ->
+    post { onBatteryWarningPendingChanged(BatteryWarningPendingChangedEvent(pending)) }
+  }
   private var setupPromise: ((Unit) -> Unit)? = null
 
+  // Initial player state staged before the player exists — from setup options or the imperative
+  // setters called pre-bind. Strict last-write-wins; consumed when the player comes up.
+  private var pendingPlayWhenReady: Boolean? = null
+  private var pendingRepeatMode: RepeatMode? = null
+
   /** Post callback to main handler for consistent async delivery to JS - avoids deadlocks */
   private fun post(block: () -> Unit) = handler.post(block)
 
@@ -144,13 +219,21 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override var onNavigationError: (NavigationErrorEvent) -> Unit = {}
   override var onFormattedNavigationError: (FormattedNavigationError?) -> Unit = {}
 
+  // MARK: Gate callbacks (native→JS; set from JS, native CALLS them)
+  // Default resolver: only reachable in the init window where the native side has recorded
+  // hasResolver=true but JS hasn't yet assigned the real `resolveGate` slot. It DENIES by default
+  // (gated=true) so an active gate never serves content during that window — same fail-closed
+  // direction as the resolver-error path in [gateDecision]. The static-gate fast path skips it
+  // entirely once a resolver-less gate is set.
+  override var resolveGate: (request: NativeGateRequest) -> Promise<Promise<GateDecision>> = {
+    Promise.resolved(Promise.resolved(GateDecision(gated = true, gate = null)))
+  }
+  override var onGate: (event: GateEvent) -> Unit = {}
+
   // MARK: Player callbacks
   override var onPlaybackChanged: (data: Playback) -> Unit = {}
-  override var onRemoteBookmark: () -> Unit = {}
-  override var onRemoteDislike: () -> Unit = {}
   override var onRemoteJumpBackward: (RemoteJumpBackwardEvent) -> Unit = {}
   override var onRemoteJumpForward: (RemoteJumpForwardEvent) -> Unit = {}
-  override var onRemoteLike: () -> Unit = {}
   override var onRemoteNext: () -> Unit = {}
   override var onRemotePause: () -> Unit = {}
   override var onChapterMetadata: (chapters: Array<ChapterMetadata>) -> Unit = {}
@@ -162,6 +245,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     {}
   override var onPlaybackPlayingState: (data: PlayingState) -> Unit = {}
   override var onPlaybackProgressUpdated: (data: PlaybackProgressUpdatedEvent) -> Unit = {}
+  override var onPlaybackInterval: () -> Unit = {}
   override var onPlaybackQueueEnded: (data: PlaybackQueueEndedEvent) -> Unit = {}
   override var onPlaybackQueueChanged: (queue: Array<Track>) -> Unit = {}
   override var onPlaybackRepeatModeChanged: (data: RepeatModeChangedEvent) -> Unit = {}
@@ -171,7 +255,6 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override var onRemotePlaySearch: (RemotePlaySearchEvent) -> Unit = {}
   override var onRemotePrevious: () -> Unit = {}
   override var onRemoteSeek: (RemoteSeekEvent) -> Unit = {}
-  override var onRemoteSetRating: (RemoteSetRatingEvent) -> Unit = {}
   override var onRemoteSkip: (RemoteSkipEvent) -> Unit = {}
   override var onRemoteStop: () -> Unit = {}
   override var onOptionsChanged: (Options) -> Unit = {}
@@ -184,14 +267,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override var onBatteryOptimizationStatusChanged: (BatteryOptimizationStatusChangedEvent) -> Unit =
     {}
   override var onSystemVolumeChanged: (Double) -> Unit = {}
-  override var onIosOutputChanged: (IosOutput) -> Unit = {}
+  override var onOutputChanged: (Output) -> Unit = {}
 
   // MARK: Remote handlers
-  override var handleRemoteBookmark: (() -> Unit)? = null
-  override var handleRemoteDislike: (() -> Unit)? = null
   override var handleRemoteJumpBackward: ((RemoteJumpBackwardEvent) -> Unit)? = null
   override var handleRemoteJumpForward: ((RemoteJumpForwardEvent) -> Unit)? = null
-  override var handleRemoteLike: (() -> Unit)? = null
   override var handleRemoteNext: (() -> Unit)? = null
   override var handleRemotePause: (() -> Unit)? = null
   override var handleRemotePlay: (() -> Unit)? = null
@@ -211,12 +291,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
 
   init {
+    current.set(this)
+
     // Auto-bind to service if it's already running
     launchInScope {
       try {
         Timber.d("Attempting to auto-bind to existing AudioBrowserService from AudioBrowser")
         val intent = Intent(context, Service::class.java)
-        val bound = context.bindService(intent, this@AudioBrowser, Context.BIND_AUTO_CREATE)
+        val bound = serviceBinding.bind(intent, this@AudioBrowser)
         Timber.d("Auto-bind result: $bound")
 
         if (!bound) {
@@ -232,9 +314,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     handler.post { ProcessLifecycleOwner.get().lifecycle.addObserver(lifecycleObserver) }
 
     // Observe system volume changes
-    systemVolumeMonitor.setOnVolumeChanged { volume ->
-      post { onSystemVolumeChanged(volume) }
-    }
+    systemVolumeMonitor.setOnVolumeChanged { volume -> post { onSystemVolumeChanged(volume) } }
+
+    // Observe current audio output changes (active media route via AudioManager)
+    outputMonitor.setOnOutputChanged { output -> post { onOutputChanged(output) } }
+    outputMonitor.start()
+
+    // Observe the car connection (Android Auto / Android Automotive)
+    startCarConnectionObserver(context, handler)
   }
 
   // ============================================================================
@@ -244,8 +331,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   internal fun buildConfig(): BrowserConfig {
     return BrowserConfig(
       request = _configuration.request,
+      requestResolver = _configuration.requestResolver,
+      browse = _configuration.browse,
+      browseResolver = _configuration.browseResolver,
       media = _configuration.media,
       artwork = _configuration.artwork,
+      nowPlayingArtwork = _configuration.nowPlayingArtwork,
       routes = _configuration.routes,
       singleTrack = _configuration.singleTrack ?: false,
       androidControllerOfflineError = _configuration.androidControllerOfflineError ?: true,
@@ -253,34 +344,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   }
 
   /**
-   * Returns the artwork configuration for use by CoilBitmapLoader. This provides access to the base
-   * request config and artwork-specific config.
-   */
-  fun getArtworkConfig(): CoilBitmapLoader.ArtworkConfig? {
-    val artworkConfig = _configuration.artwork ?: return null
-    val baseConfig =
-      _configuration.request?.let { RequestConfigBuilder.toRequestConfig(it) }
-        ?: RequestConfig(null, null, null, null, null, null, null, null)
-    return CoilBitmapLoader.ArtworkConfig(baseConfig, artworkConfig)
-  }
-
-  /**
-   * Creates a request config for media URL transformation by merging base and media configs.
-   * Returns null if no media configuration is set.
+   * Media URL transformation for [com.audiobrowser.player.TransformingDataSource]. Resolution lives
+   * in [resolveMediaUrl] (browser/BrowserUrlResolution.kt); this shell owns only the blocking
+   * bridge: it runs on ExoPlayer's IO thread (TransformingDataSource.open), so blocking here is
+   * safe and intentional.
    */
   fun getMediaRequestConfig(originalUrl: String): MediaRequestConfig? {
-    val mediaConfig = _configuration.media ?: return null
-
     return try {
-      // Create base request config with the original URL as path
-      val baseConfig =
-        _configuration.request?.let { RequestConfigBuilder.toRequestConfig(it) }
-          ?: RequestConfig(null, null, null, null, null, null, null, null)
-      val urlRequestConfig = RequestConfig(null, originalUrl, null, null, null, null, null, null)
-      val mergedBaseConfig = RequestConfigBuilder.mergeConfig(baseConfig, urlRequestConfig)
-
-      // Apply media transformation
-      runBlocking { RequestConfigBuilder.mergeConfig(mergedBaseConfig, mediaConfig) }
+      runBlocking { browserManager.resolveMediaUrl(originalUrl) }
     } catch (e: Exception) {
       Timber.e(e, "Failed to transform media URL: $originalUrl")
       null
@@ -292,10 +363,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     return _configuration.routes?.any { it.path != BrowserManager.SEARCH_ROUTE_PATH } == true
   }
 
-  private fun getDefaultPath(): String? {
+  // Suspending on purpose: queryTabs() resolves tabs by invoking JS callbacks,
+  // which can only run on the JS thread. Callers MUST invoke this from a
+  // coroutine (off the JS thread) — never via runBlocking on a synchronous Nitro
+  // setter, which runs on the JS thread and would deadlock (the JS thread blocks
+  // waiting for callbacks that need that same thread to run).
+  private suspend fun getDefaultPath(): String? {
     return try {
       browserManager.config = buildConfig()
-      val tabs = runBlocking { browserManager.queryTabs() }
+      val tabs = browserManager.queryTabs()
       if (tabs.isNotEmpty()) {
         Timber.d("Using first tab as default path: ${tabs[0].url}")
         tabs[0].url
@@ -303,6 +379,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         Timber.d("Using root path as default: /")
         "/"
       }
+    } catch (e: CancellationException) {
+      throw e // Rethrow so cooperative cancellation isn't swallowed
     } catch (e: Exception) {
       Timber.e(e, "Failed to get default path, falling back to /")
       "/"
@@ -318,23 +396,25 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     set(value) {
       if (hasValidConfiguration()) {
         browserManager.config = buildConfig()
-        (value ?: getDefaultPath())?.let { path ->
-          clearNavigationError()
-
-          // Cancel previous navigation to avoid race conditions
-          navigationJob?.cancel()
-
-          navigationJob =
-            mainScope.launch {
-              try {
-                browserManager.navigate(path)
-              } catch (e: CancellationException) {
-                throw e // Rethrow to properly cancel
-              } catch (e: Exception) {
-                handleBrowserException(e, path, "setting path: $path")
-              }
+        clearNavigationError()
+
+        // Cancel previous navigation to avoid race conditions
+        navigationJob?.cancel()
+
+        // Resolve the default path inside the coroutine (getDefaultPath queries
+        // tabs via JS callbacks) so it never blocks the JS thread this setter
+        // runs on.
+        navigationJob =
+          mainScope.launch {
+            val path = value ?: getDefaultPath() ?: return@launch
+            try {
+              browserManager.navigate(path)
+            } catch (e: CancellationException) {
+              throw e // Rethrow to properly cancel
+            } catch (e: Exception) {
+              handleBrowserException(e, path, "setting path: $path")
             }
-        }
+          }
       }
     }
 
@@ -352,45 +432,54 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       // This allows Android Auto to start browsing content
       connectedService?.player?.notifyBrowserConfigurationReady()
 
-      // Navigate to initial path or default to first tab
-      (value.path ?: getDefaultPath())?.let { path ->
-        clearNavigationError()
-
-        // Cancel previous navigation to avoid race conditions
-        navigationJob?.cancel()
-
-        navigationJob =
-          mainScope.launch {
-            try {
-              browserManager.navigate(path)
-            } catch (e: CancellationException) {
-              throw e // Rethrow to properly cancel
-            } catch (e: Exception) {
-              handleBrowserException(e, path, "setting configuration path: $path")
-            }
+      clearNavigationError()
+
+      // Cancel previous navigation to avoid race conditions
+      navigationJob?.cancel()
+
+      // Navigate to the initial path, or default to the first tab. The default
+      // path is resolved inside the coroutine (getDefaultPath queries tabs via
+      // JS callbacks) so it never blocks the JS thread this setter runs on —
+      // doing it synchronously here via runBlocking deadlocked: the JS callbacks
+      // can't run because the JS thread is blocked waiting for them.
+      navigationJob =
+        mainScope.launch {
+          val path = value.path ?: getDefaultPath() ?: return@launch
+          try {
+            browserManager.navigate(path)
+          } catch (e: CancellationException) {
+            throw e // Rethrow to properly cancel
+          } catch (e: Exception) {
+            handleBrowserException(e, path, "setting configuration path: $path")
           }
-      }
+        }
     }
 
   private var navigationError: NavigationError? = null
   private var formattedNavigationError: FormattedNavigationError? = null
 
   override fun getNavigationError(): NavigationError? = navigationError
+
   override fun getFormattedNavigationError(): FormattedNavigationError? = formattedNavigationError
 
   /** Creates a default formatted error from a NavigationError */
   private fun defaultFormattedError(error: NavigationError): FormattedNavigationError {
-    val title = when (error.code) {
-      NavigationErrorType.CONTENT_NOT_FOUND -> "Content Not Found"
-      NavigationErrorType.NETWORK_ERROR -> "Network Error"
-      NavigationErrorType.HTTP_ERROR -> {
-        // Use system-localized HTTP status text (e.g., "Not Found", "Service Unavailable")
-        error.statusCode?.let { httpStatusText(it.toInt()) } ?: "Server Error"
+    val title =
+      when (error.code) {
+        NavigationErrorType.CONTENT_NOT_FOUND -> "Content Not Found"
+        NavigationErrorType.NETWORK_ERROR -> "Network Error"
+        NavigationErrorType.HTTP_ERROR -> {
+          // Use system-localized HTTP status text (e.g., "Not Found", "Service Unavailable")
+          error.statusCode?.let { httpStatusText(it.toInt()) } ?: "Server Error"
+        }
+        NavigationErrorType.CALLBACK_ERROR -> "Error"
+        NavigationErrorType.UNKNOWN_ERROR -> "Error"
+        // Not a failure — a container that resolved with no children. Neutral copy. See ADR 0001.
+        NavigationErrorType.EMPTY_CONTENT -> "Nothing here"
+        NavigationErrorType.TIMEOUT -> "Couldn't load"
       }
-      NavigationErrorType.CALLBACK_ERROR -> "Error"
-      NavigationErrorType.UNKNOWN_ERROR -> "Error"
-    }
-    return FormattedNavigationError(title, error.message)
+    // Omit an empty message so it renders as title-only (e.g. the empty-content case).
+    return FormattedNavigationError(title, error.message.takeIf { it.isNotEmpty() })
   }
 
   /** Returns localized HTTP status text for the given status code */
@@ -457,19 +546,35 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       }
       is NetworkException -> {
         Timber.e(e, "Network error $logContext")
-        setNavigationError(NavigationErrorType.NETWORK_ERROR, e.message ?: "Network request failed", path)
+        setNavigationError(
+          NavigationErrorType.NETWORK_ERROR,
+          e.message ?: "Network request failed",
+          path,
+        )
       }
       is ContentNotFoundException -> {
         Timber.e(e, "Content not found $logContext")
-        setNavigationError(NavigationErrorType.CONTENT_NOT_FOUND, e.message ?: "Content not found", path)
+        setNavigationError(
+          NavigationErrorType.CONTENT_NOT_FOUND,
+          e.message ?: "Content not found",
+          path,
+        )
       }
       is CallbackException -> {
         Timber.e(e, "Callback error $logContext")
-        setNavigationError(NavigationErrorType.CALLBACK_ERROR, e.message ?: "An error occurred", path)
+        setNavigationError(
+          NavigationErrorType.CALLBACK_ERROR,
+          e.message ?: "An error occurred",
+          path,
+        )
       }
       else -> {
         Timber.e(e, "Unexpected error $logContext")
-        setNavigationError(NavigationErrorType.UNKNOWN_ERROR, e.message ?: "An unexpected error occurred", path)
+        setNavigationError(
+          NavigationErrorType.UNKNOWN_ERROR,
+          e.message ?: "An unexpected error occurred",
+          path,
+        )
       }
     }
   }
@@ -529,10 +634,17 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
                 val index = player.tracks.indexOfFirst { it.src == trackId }
                 if (index >= 0) {
                   Timber.d("Queue already from $parentPath, skipping to index $index")
-                  handleTrackLoad(_configuration.handleTrackLoad, track, player.tracks, index.toDouble(), intercepted = {}, defaultBehavior = {
-                    player.skipTo(index)
-                    player.play()
-                  })
+                  handleTrackLoad(
+                    _configuration.handleTrackLoad,
+                    track,
+                    player.tracks,
+                    index.toDouble(),
+                    intercepted = {},
+                    defaultBehavior = {
+                      player.skipTo(index)
+                      player.play()
+                    },
+                  )
                   return@launch
                 }
               }
@@ -545,17 +657,31 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
                 Timber.d(
                   "Loading expanded queue: ${tracks.size} tracks, starting at index $startIndex"
                 )
-                handleTrackLoad(_configuration.handleTrackLoad, track, tracks, startIndex.toDouble(), intercepted = {}, defaultBehavior = {
-                  // Replace queue and seek to selected track
-                  // Use internal player methods directly to avoid blocking on main thread
-                  player.setQueue(tracks, startIndex, sourcePath = parentPath)
-                  player.play()
-                })
+                handleTrackLoad(
+                  _configuration.handleTrackLoad,
+                  track,
+                  tracks,
+                  startIndex.toDouble(),
+                  intercepted = {},
+                  defaultBehavior = {
+                    // Replace queue and seek to selected track
+                    // Use internal player methods directly to avoid blocking on main thread
+                    player.setQueue(tracks, startIndex, sourcePath = parentPath)
+                    player.play()
+                  },
+                )
                 return@launch
               } else {
                 // Fallback: just load the single track
                 Timber.w("Queue expansion failed, loading single track")
-                handleTrackLoad(_configuration.handleTrackLoad, track, arrayOf(track), 0.0, intercepted = {}, defaultBehavior = { player.load(track) })
+                handleTrackLoad(
+                  _configuration.handleTrackLoad,
+                  track,
+                  arrayOf(track),
+                  0.0,
+                  intercepted = {},
+                  defaultBehavior = { player.load(track) },
+                )
               }
             }
             // Navigate to browsable track to show browsing UI
@@ -566,7 +692,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
             // If track is playable (has src), load it into player
             track.src != null -> {
               Timber.d("Loading playable track into player: ${track.title}")
-              handleTrackLoad(_configuration.handleTrackLoad, track, arrayOf(track), 0.0, intercepted = {}, defaultBehavior = { player.load(track) })
+              handleTrackLoad(
+                _configuration.handleTrackLoad,
+                track,
+                arrayOf(track),
+                0.0,
+                intercepted = {},
+                defaultBehavior = { player.load(track) },
+              )
             }
             else -> {
               throw IllegalArgumentException("Track must have either an 'url' or an 'src' property")
@@ -580,7 +713,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       }
   }
 
-  override fun onSearch(query: String): Promise<Array<Track>> {
+  override fun search(query: String): Promise<Array<Track>> {
     return Promise.async(mainScope) {
       Timber.d("Searching for: $query")
       val searchResults = browserManager.search(query)
@@ -607,32 +740,132 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
   }
 
+  override fun invalidateAllContent() {
+    Timber.d("Invalidating all content")
+
+    // Clear all cached content so every path re-fetches fresh data
+    browserManager.clearContentCache()
+
+    // Notify external media controllers (Android Auto) to refresh subscribed paths
+    connectedService?.player?.invalidateAllContent()
+
+    // Refresh whatever the browser is currently viewing
+    mainScope.launch { browserManager.refresh() }
+  }
+
   override fun setFavorites(favorites: Array<String>) {
     browserManager.setFavorites(favorites.toList())
   }
 
+  // MARK: Gate
+
+  /** A gate decision for one request: whether to gate, and which chrome to render. */
+  data class GateOutcome(val gated: Boolean, val chrome: Gate?)
+
+  // The minimal chrome rendered when a gate is active but no override or stored
+  // default chrome exists (the resolver-only setGate overload).
+  private val builtInGate = Gate("Unavailable", null)
+
+  /**
+   * The three gate fields as one immutable triple so [gateDecision] reads them as a unit. Written
+   * from the JS thread, read from the Media3 application thread (the enforcement sites in
+   * MediaSessionCallback consult it) — hence the single field is @Volatile.
+   *
+   * Folding the three former @Volatile fields into one reference is what makes the read atomic:
+   *
+   * @Volatile gives per-field visibility but NO atomicity across a compound read, so reading three
+   *   separate volatiles in [gateDecision] could interleave with a concurrent [clearGate] and yield
+   *   a torn `(active=true, chrome=null)` state that crashed the force-unwrap at the serve sites.
+   *   One volatile reference read once cannot tear.
+   */
+  private data class GateState(val active: Boolean, val chrome: Gate?, val hasResolver: Boolean)
+
+  @Volatile private var gateState = GateState(active = false, chrome = null, hasResolver = false)
+
+  override fun setGate(gate: Gate?, hasResolver: Boolean) {
+    // Single atomic assignment — readers never see a half-updated triple.
+    gateState = GateState(active = true, chrome = gate, hasResolver = hasResolver)
+    // Re-query every subscribed parent so a connected controller (Android
+    // Auto) swaps its lists for the gate tile without reconnecting. Notify
+    // only — the content cache stays warm for when the gate clears.
+    connectedService?.player?.invalidateAllContent()
+  }
+
+  override fun clearGate() {
+    if (!gateState.active) return
+    // Single atomic assignment — readers never see a half-cleared triple.
+    gateState = GateState(active = false, chrome = null, hasResolver = false)
+    connectedService?.player?.invalidateAllContent()
+  }
+
+  /**
+   * The single gate choke point. Each enforcement site (browse / search) calls this for the current
+   * request and serves the gate chrome when [GateOutcome.gated] is true. Structurally similar to
+   * the iOS `gateDecision(for:)` helper, but note the concurrency model differs: iOS confines gate
+   * state to `@MainActor`; here the consistent read comes from snapshotting the single [gateState]
+   * reference once (see [GateState]).
+   * - No active gate → allow.
+   * - Active gate, no resolver → static fast path: gate with the stored default chrome (or built-in
+   *   if none), no JS hop.
+   * - Active gate with a resolver → ask JS per request. A resolver that throws / rejects / times
+   *   out FAILS CLOSED by design: while a gate is active the consumer has declared content blocked,
+   *   so the only safe fallback when we cannot compute the per-request decision is the gate's own
+   *   chrome — never the content. A *successful* `gated:false` still allows. Chrome order on a
+   *   gated decision: override → stored default → built-in.
+   *
+   * Every gated return guards chrome against null (`?: builtInGate`) so a gated outcome always
+   * carries a renderable chrome — the serve sites force-unwrap it.
+   */
+  suspend fun gateDecision(request: NativeGateRequest): GateOutcome {
+    // Read the whole gate triple once; a single volatile reference can't tear (see [GateState]).
+    val s = gateState
+    if (!s.active) return GateOutcome(false, null)
+    if (!s.hasResolver) return GateOutcome(true, s.chrome ?: builtInGate) // static fast path
+    val decision =
+      runCatching { resolveGate(request).await().await() }.getOrNull()
+        ?: return GateOutcome(true, s.chrome ?: builtInGate) // fail CLOSED on resolver error
+    if (!decision.gated) return GateOutcome(false, null) // explicit allow
+    return GateOutcome(true, decision.gate ?: s.chrome ?: builtInGate)
+  }
+
+  // MARK: Car connection (Android Auto / Android Automotive)
+
+  override fun isCarConnected(): Boolean = carConnected
+
+  override var onCarConnectedChanged: (Boolean) -> Unit = {}
+    set(value) {
+      field = value
+      carConnectionTarget.set(value)
+      // Immediately notify current state (the car may have connected before
+      // this JS runtime subscribed) — mirrors the iOS behavior.
+      value(carConnected)
+    }
+
   // ============================================================================
   // MARK: Player Setup and Options
   // ============================================================================
 
-  override fun setupPlayer(options: PartialSetupPlayerOptions): Promise<Unit> {
+  override fun setupPlayer(options: NativeSetupPlayerOptions): Promise<Unit> {
     return Promise.async(mainScope) {
       setupOptions.update(options)
+      // The bundled runtime options and initial state are part of the atomic launch
+      // description: stage them here, apply them together with the engine below (or at
+      // service connect). Last-write-wins with their imperative counterparts.
+      options.options?.let { updateOptions.updateFromBridge(it) }
+      options.repeatMode?.let { pendingRepeatMode = it }
+      options.playWhenReady?.let { pendingPlayWhenReady = it }
 
       connectedService?.let {
+        it.player.applyOptions(updateOptions)
         it.player.setup(setupOptions)
+        applyPendingPlayerState(it.player)
         return@async
       }
 
       // Service not connected yet, bind to service
       suspendCoroutine<Unit> { continuation ->
         Timber.d("Binding to AudioBrowserService")
-        val bound =
-          context.bindService(
-            Intent(context, Service::class.java),
-            this@AudioBrowser,
-            Context.BIND_AUTO_CREATE,
-          )
+        val bound = serviceBinding.bind(Intent(context, Service::class.java), this@AudioBrowser)
 
         if (!bound) {
           continuation.resumeWithException(
@@ -652,8 +885,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     connectedService?.let { player.applyOptions(updateOptions) }
   }
 
-  override fun getOptions(): UpdateOptions {
-    return player.getOptions().toNitro()
+  override fun getOptions(): Options {
+    // The holder is the source of truth whether or not the player exists yet — updateOptions
+    // merges into it and setup/connect applies it to the player.
+    return updateOptions.toNitro()
   }
 
   // ============================================================================
@@ -666,8 +901,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
   override fun reset() = runBlockingOnMain {
     player.stop()
-    delay(300) // Allow playback to stop
     player.clear()
+    // clear() while IDLE emits no engine event, so the state machine never
+    // leaves STOPPED — a reset queue is "nothing loaded".
+    player.setPlaybackState(PlaybackState.NONE)
   }
 
   override fun play() = runBlockingOnMain { player.play() }
@@ -679,10 +916,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override fun stop() = runBlockingOnMain { player.stop() }
 
   override fun setPlayWhenReady(playWhenReady: Boolean) = runBlockingOnMain {
-    player.playWhenReady = playWhenReady
+    // Pre-setup this stages the intent for the player to come up with — never throws.
+    connectedService?.player?.let { it.playWhenReady = playWhenReady }
+      ?: run { pendingPlayWhenReady = playWhenReady }
   }
 
-  override fun getPlayWhenReady(): Boolean = runBlockingOnMain { player.playWhenReady }
+  override fun getPlayWhenReady(): Boolean = runBlockingOnMain {
+    connectedService?.player?.playWhenReady ?: pendingPlayWhenReady ?: false
+  }
 
   override fun seekTo(position: Double) = runBlockingOnMain {
     player.seekTo((position * 1000).toLong(), TimeUnit.MILLISECONDS)
@@ -692,6 +933,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     player.seekBy((offset * 1000).toLong(), TimeUnit.MILLISECONDS)
   }
 
+  override fun seekToLiveEdge() = runBlockingOnMain { player.seekToLiveEdge() }
+
   override fun setVolume(level: Double) = runBlockingOnMain { player.volume = level.toFloat() }
 
   override fun getVolume(): Double = runBlockingOnMain { player.volume.toDouble() }
@@ -712,9 +955,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
 
   override fun getPlayingState(): PlayingState = runBlockingOnMain { player.getPlayingState() }
 
-  override fun getRepeatMode(): RepeatMode = runBlockingOnMain { player.repeatMode }
+  override fun getRepeatMode(): RepeatMode = runBlockingOnMain {
+    connectedService?.player?.repeatMode ?: pendingRepeatMode ?: RepeatMode.OFF
+  }
 
-  override fun setRepeatMode(mode: RepeatMode) = runBlockingOnMain { player.repeatMode = mode }
+  override fun setRepeatMode(mode: RepeatMode) = runBlockingOnMain {
+    // Pre-setup this stages the mode for the player to come up with — never throws.
+    connectedService?.player?.let { it.repeatMode = mode } ?: run { pendingRepeatMode = mode }
+  }
 
   override fun getShuffleEnabled(): Boolean = runBlockingOnMain { player.shuffleMode }
 
@@ -722,6 +970,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     player.shuffleMode = enabled
   }
 
+  override fun setPlaybackIntervalEnabled(enabled: Boolean) = runBlockingOnMain {
+    player.setPlaybackIntervalEnabled(enabled)
+  }
+
   override fun getPlaybackError(): PlaybackError? = runBlockingOnMain { player.playbackError }
 
   override fun retry() = runBlockingOnMain { player.prepare() }
@@ -770,9 +1022,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
   }
 
-  override fun setQueue(tracks: Array<Track>, startIndex: Double?, startPositionMs: Double?) =
+  override fun setQueue(tracks: Array<Track>, startIndex: Double?, startPosition: Double?) =
     runBlockingOnMain {
-      player.setQueue(tracks, startIndex?.toInt() ?: 0, startPositionMs?.toLong() ?: 0)
+      player.setQueue(tracks, startIndex?.toInt() ?: 0, ((startPosition ?: 0.0) * 1000).toLong())
     }
 
   override fun setActiveTrackFavorited(favorited: Boolean) = runBlockingOnMain {
@@ -804,10 +1056,20 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   // ============================================================================
 
   override fun updateNowPlaying(update: NowPlayingUpdate?) = runBlockingOnMain {
-    player.updateNowPlaying(update)
+    player.nowPlaying.updateNowPlaying(update)
+  }
+
+  override fun flashNowPlaying(update: NowPlayingUpdate, durationMs: Double) = runBlockingOnMain {
+    player.nowPlaying.flashNowPlaying(update, durationMs)
   }
 
-  override fun getNowPlaying(): NowPlayingMetadata? = runBlockingOnMain { player.getNowPlaying() }
+  override fun clearNowPlayingFlash() = runBlockingOnMain {
+    player.nowPlaying.clearNowPlayingFlash()
+  }
+
+  override fun getNowPlaying(): NowPlayingMetadata? = runBlockingOnMain {
+    player.nowPlaying.getNowPlaying()
+  }
 
   // ============================================================================
   // MARK: Network Connectivity
@@ -824,13 +1086,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   override fun setSystemVolume(volume: Double) = systemVolumeMonitor.setVolume(volume)
 
   // ============================================================================
-  // MARK: External Audio Output (iOS only, stub on Android)
+  // MARK: External Audio Output
   // ============================================================================
 
-  override fun getIosOutput(): IosOutput? = null
+  override fun getOutput(): Output? = outputMonitor.current
 
-  override fun openIosOutputPicker() {
-    // No-op on Android
+  override fun supportsOutputSwitcher(): Boolean = OutputSwitcher.isSupported()
+
+  override fun openOutputPicker() {
+    OutputSwitcher.open(context)
   }
 
   // ============================================================================
@@ -838,34 +1102,34 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   // ============================================================================
 
   override fun getEqualizerSettings(): EqualizerSettings? = runBlockingOnMain {
-    player.getEqualizerSettings()
+    player.equalizer.getSettings()
   }
 
   override fun setEqualizerEnabled(enabled: Boolean) = runBlockingOnMain {
-    player.setEqualizerEnabled(enabled)
+    player.equalizer.setEnabled(enabled)
   }
 
   override fun setEqualizerPreset(preset: String) = runBlockingOnMain {
-    player.setEqualizerPreset(preset)
+    player.equalizer.setPreset(preset)
   }
 
   override fun setEqualizerLevels(levels: DoubleArray) = runBlockingOnMain {
-    player.setEqualizerLevels(levels)
+    player.equalizer.setLevels(levels)
   }
 
   // ============================================================================
   // MARK: Sleep Timer
   // ============================================================================
 
-  override fun getSleepTimer(): SleepTimer = runBlockingOnMain { player.getSleepTimer() }
-
-  override fun setSleepTimer(seconds: Double) = runBlockingOnMain { player.setSleepTimer(seconds) }
+  override fun getSleepTimer(): SleepTimer = runBlockingOnMain { player.sleepTimer.get() }
 
-  override fun setSleepTimerToEndOfTrack() = runBlockingOnMain {
-    player.setSleepTimerToEndOfTrack()
+  override fun setSleepTimer(seconds: Double, fadeDuration: Double?) = runBlockingOnMain {
+    player.sleepTimer.setAfter(seconds, fadeDuration)
   }
 
-  override fun clearSleepTimer(): Boolean = runBlockingOnMain { player.clearSleepTimer() }
+  override fun setSleepTimerToEndOfTrack() = runBlockingOnMain { player.sleepTimer.setEndOfTrack() }
+
+  override fun clearSleepTimer(): Boolean = runBlockingOnMain { player.sleepTimer.clear() }
 
   // ============================================================================
   // MARK: Battery Optimization (Android only)
@@ -945,6 +1209,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
           player.setCallbacks(callbacks)
           player.applyOptions(updateOptions)
           player.setup(setupOptions)
+          applyPendingPlayerState(player)
           // Start observing network connectivity changes
           player.observeNetworkConnectivity(mainScope)
           // Set browser reference for media URL transformation
@@ -958,13 +1223,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         }
 
       // Wire up battery warning callback from service
-      connectedService?.onBatteryWarningPendingChanged = { pending ->
-        post {
-          this@AudioBrowser.onBatteryWarningPendingChanged(
-            BatteryWarningPendingChangedEvent(pending)
-          )
-        }
-      }
+      connectedService?.onBatteryWarningPendingChanged = onBatteryWarningPending
 
       val sessionToken = SessionToken(context, ComponentName(context, Service::class.java))
       mediaBrowserFuture = MediaBrowser.Builder(context, sessionToken).buildAsync()
@@ -974,6 +1233,21 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
   }
 
+  /**
+   * Applies initial player state staged before the player existed. Consumed on apply so a later
+   * re-setup doesn't replay stale state.
+   */
+  private fun applyPendingPlayerState(player: Player) {
+    pendingRepeatMode?.let {
+      player.repeatMode = it
+      pendingRepeatMode = null
+    }
+    pendingPlayWhenReady?.let {
+      player.playWhenReady = it
+      pendingPlayWhenReady = null
+    }
+  }
+
   override fun onServiceDisconnected(name: ComponentName) {
     mainScope.coroutineContext.cancelChildren()
     mediaBrowserFuture = null
@@ -1017,6 +1291,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         post { this@AudioBrowser.onPlaybackProgressUpdated(event) }
       }
 
+      override fun onPlaybackInterval() {
+        post { this@AudioBrowser.onPlaybackInterval() }
+      }
+
       override fun onPlaybackPlayWhenReadyChanged(event: PlaybackPlayWhenReadyChangedEvent) {
         post { this@AudioBrowser.onPlaybackPlayWhenReadyChanged(event) }
       }
@@ -1166,12 +1444,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         return handled
       }
 
-      override fun onRemoteSetRating(event: RemoteSetRatingEvent) {
-        post { this@AudioBrowser.onRemoteSetRating(event) }
-      }
-
       override fun onOptionsChanged(options: PlayerUpdateOptions) {
-        // Not currently emitted to JS
+        post { this@AudioBrowser.onOptionsChanged(options.toNitro()) }
       }
 
       override fun onFavoriteChanged(event: FavoriteChangedEvent) {
@@ -1194,4 +1468,45 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         post { this@AudioBrowser.onSleepTimerChanged(timer) }
       }
     }
+
+  companion object {
+    // Process-wide car-connection state, from the androidx.car.app
+    // CarConnection provider — the documented Android Auto / Automotive
+    // connection signal, served by the car system app. Observed ONCE per
+    // process: AudioBrowser instances are re-created on a JS reload, and a
+    // per-instance observeForever would leak each one. The latest instance's
+    // callback registers as the single notification target (mirrors the iOS
+    // static + shared-instance pattern).
+    @Volatile private var carConnected = false
+    // Compare-and-set, not @Volatile: a disposing instance clears the slot only if it still owns
+    // it, and a replacement may be claiming it at the same moment.
+    private val carConnectionTarget = AtomicReference<((Boolean) -> Unit)?>(null)
+    private var carConnectionObserverStarted = false
+
+    /**
+     * The instance the current JS runtime is using. Nitro hands out no registry, and the teardown
+     * callback has nothing to dispose without one.
+     */
+    private val current = AtomicReference<AudioBrowser?>(null)
+
+    /** Called by [AudioBrowserLifecycleModule] when the React instance is torn down. */
+    internal fun disposeCurrent() {
+      current.getAndSet(null)?.dispose()
+    }
+
+    private fun startCarConnectionObserver(context: Context, handler: Handler) {
+      // Posted to main: LiveData observation is main-thread only, and the
+      // single-start guard is then only ever touched from one thread.
+      handler.post {
+        if (carConnectionObserverStarted) return@post
+        carConnectionObserverStarted = true
+        CarConnection(context.applicationContext).type.observeForever { type ->
+          val connected = type != CarConnection.CONNECTION_TYPE_NOT_CONNECTED
+          if (connected == carConnected) return@observeForever
+          carConnected = connected
+          carConnectionTarget.get()?.invoke(connected)
+        }
+      }
+    }
+  }
 }