react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.13

package/README.md

@@ -63,7 +63,7 @@ import AudioBrowser from 'react-native-audio-browser'
 await AudioBrowser.setupPlayer()
 
 AudioBrowser.configureBrowser({
-  tabs: [{ title: 'Browse', url: '/browse' }],
+  tabs: [{ title: 'Browse', path: '/browse' }],
   routes: {
     // Every path under /browse is fetched from your API, on demand.
     '/browse/**': { baseUrl: 'https://api.example.com' }
@@ -71,15 +71,15 @@ AudioBrowser.configureBrowser({
 })
 ```
 
-Each route returns a page of children — a child with a `url` is browsable (open it for more), one with a `src` is a playable track (plus optional `artist`, `artwork`, …):
+Each route returns a page of children — a child with a `path` is browsable (open it for more), one with a `src` is a playable track (plus optional `artist`, `artwork`, …):
 
 ```jsonc
 // GET https://api.example.com/browse/jazz  →
 {
-  "url": "/browse/jazz",
+  "path": "/browse/jazz",
   "title": "Jazz",
   "children": [
-    { "title": "Smooth Floret FM", "url": "/browse/jazz/floret-fm" }, // url → open for children
+    { "title": "Smooth Floret FM", "path": "/browse/jazz/floret-fm" }, // path → open for children
     { "title": "The Stalk 88.5", "src": "https://stream.example.com/stalk.mp3" } // src → play this stream
   ]
 }
@@ -174,6 +174,16 @@ Full guides and the complete [API Reference](https://audiobrowser.dev/api/) live
 
 The example app in [`apps/example-native`](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native) browses archive.org's audio collection — in-app, on CarPlay, and on Android Auto — with search, favorites, and the gate.
 
+### For coding agents
+
+Every page is also served as raw Markdown — append `.md` to any URL, e.g.
+[`audiobrowser.dev/guide/queue.md`](https://audiobrowser.dev/guide/queue.md).
+
+- [`/llms.txt`](https://audiobrowser.dev/llms.txt) — an index of every page with a one-line summary, to pick what to read.
+- [`/llms-full.txt`](https://audiobrowser.dev/llms-full.txt) — every guide in one file.
+
+The same guide Markdown ships in the package, so it can be read straight off disk without a network fetch: `node_modules/react-native-audio-browser/website/guide/`.
+
 ## Support
 
 Questions or bugs? [Open an issue](https://github.com/radio-garden/react-native-audio-browser/issues). Release notes live in the [changelog](CHANGELOG.md).

package/android/build.gradle

@@ -158,6 +158,13 @@ repositories {
   google()
 }
 
+// Mockito's inline mock maker needs a Byte Buddy agent in the running JVM. Left to itself it
+// installs one through the JVM attach mechanism, which binds a unix socket under $TMPDIR —
+// denied inside sandboxed shells, and disabled by default on JDK 24+. Resolving the agent as its
+// own configuration lets the test JVM pre-load it with -javaagent, so no attach is needed.
+configurations {
+  mockitoAgent
+}
 
 dependencies {
   // For < 0.71, this will be from the local maven repo
@@ -210,14 +217,26 @@ dependencies {
   implementation("io.coil-kt.coil3:coil-network-okhttp:3.3.0")
 
   // Testing dependencies
+  def mockitoVersion = "5.8.0"
   testImplementation 'junit:junit:4.13.2'
-  testImplementation 'org.mockito:mockito-core:5.8.0'
+  testImplementation "org.mockito:mockito-core:${mockitoVersion}"
+  // Resolved transitively so the agent jar always matches the Byte Buddy that Mockito uses.
+  mockitoAgent "org.mockito:mockito-core:${mockitoVersion}"
   testImplementation 'org.jetbrains.kotlinx:kotlinx-coroutines-test:1.7.3'
   testImplementation 'org.robolectric:robolectric:4.11.1'
 
   api 'com.jakewharton.timber:timber:5.0.1'
 }
 
+tasks.withType(Test).configureEach {
+  def agentJar = configurations.mockitoAgent.find { it.name.startsWith("byte-buddy-agent") }
+  if (agentJar == null) {
+    throw new GradleException("No byte-buddy-agent jar in the mockitoAgent configuration; " +
+        "Mockito would fall back to runtime self-attach. Check the mockito-core coordinates.")
+  }
+  jvmArgs "-javaagent:${agentJar}"
+}
+
 if (isNewArchitectureEnabled()) {
   react {
     jsRootDir = file("../src/")

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

@@ -20,9 +20,11 @@ import com.audiobrowser.browser.CallbackException
 import com.audiobrowser.browser.ContentNotFoundException
 import com.audiobrowser.browser.HttpStatusException
 import com.audiobrowser.browser.NetworkException
+import com.audiobrowser.browser.flattenedChildren
 import com.audiobrowser.browser.handleTrackLoad
 import com.audiobrowser.browser.resolveMediaUrl
 import com.audiobrowser.extension.NumberExt.Companion.toSeconds
+import com.audiobrowser.extension.indexOfTappedTrack
 import com.audiobrowser.model.PlayerSetupOptions
 import com.audiobrowser.model.PlayerUpdateOptions
 import com.audiobrowser.player.Player
@@ -35,6 +37,7 @@ 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.ArtworkRequestConfig
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatus
 import com.margelo.nitro.audiobrowser.BatteryOptimizationStatusChangedEvent
 import com.margelo.nitro.audiobrowser.BatteryWarningPendingChangedEvent
@@ -50,6 +53,7 @@ import com.margelo.nitro.audiobrowser.HybridAudioBrowserSpec
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
 import com.margelo.nitro.audiobrowser.NativeBrowserConfiguration
 import com.margelo.nitro.audiobrowser.NativeGateRequest
+import com.margelo.nitro.audiobrowser.NativeRouteEntry
 import com.margelo.nitro.audiobrowser.NativeSetupPlayerOptions
 import com.margelo.nitro.audiobrowser.NativeUpdateOptions
 import com.margelo.nitro.audiobrowser.NavigationError
@@ -82,6 +86,7 @@ import com.margelo.nitro.audiobrowser.SleepTimer
 import com.margelo.nitro.audiobrowser.TimedMetadata
 import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TrackMetadata
+import com.margelo.nitro.audiobrowser.TransformableRequestConfig
 import com.margelo.nitro.core.Promise
 import java.util.concurrent.TimeUnit
 import java.util.concurrent.atomic.AtomicReference
@@ -121,6 +126,12 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     // Only when still ours: on a reload the replacement may already own the slot.
     carConnectionTarget.compareAndSet(onCarConnectedChanged, null)
 
+    // The runtime behind the config's JS functions is going away, but anything still holding
+    // this instance (an in-flight browse coroutine, the running player) can invoke them after
+    // it's gone — each invoke then throws instead of answering, so browse takes its error path
+    // rather than its fallback.
+    dropStaleJSCallbacks()
+
     handler.post {
       connectedService?.let { service ->
         // Identity-guarded: both instances bind to the same singleton Service, so a late dispose
@@ -129,6 +140,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
         if (service.player.browser === this) {
           service.player.browser = null
           service.player.forgetBrowserRegistration()
+          // The formatter wraps a JS callback from this instance's runtime (installed by our
+          // setup(); browser still being ours means no replacement has run setup yet). Without
+          // this, every track change until the next setup() throws into the updater's fallback.
+          service.player.nowPlaying.formatter = null
         }
         if (service.onBatteryWarningPendingChanged === onBatteryWarningPending) {
           service.onBatteryWarningPendingChanged = null
@@ -152,6 +167,20 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     super.dispose()
   }
 
+  /**
+   * Demotes the config to data-only (deep strip of every JS function field) and reverts the JS
+   * callbacks stored outside the config tree ([resolveGate]; the now-playing formatter is cleared
+   * in [dispose]'s service block, identity-guarded). Stale paths then degrade the same way as a
+   * config that never had callbacks — static request/browse layers, default error copy, fail-closed
+   * gate — instead of throwing into the error path. Mirrors iOS `dropStaleJSCallbacks`, where the
+   * same invoke is fatal rather than a throw.
+   */
+  private fun dropStaleJSCallbacks() {
+    _configuration = _configuration.strippingJSCallbacks()
+    browserManager.config = buildConfig()
+    resolveGate = defaultResolveGate
+  }
+
   private val mainScope = MainScope()
   private var navigationJob: Job? = null
   private val handler = Handler(Looper.getMainLooper())
@@ -175,7 +204,7 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       handleTrackLoad = null,
       androidControllerOfflineError = null,
       carPlayLoadingTitle = null,
-      resolveAlbumUrl = null,
+      resolveAlbumPath = null,
       formatNavigationError = null,
     )
 
@@ -220,14 +249,14 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   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
+  // Default resolver: only reachable while hasResolver=true but no live runtime has the real
+  // `resolveGate` bound — the init window before JS assigns it, or after [dispose] reverts a dead
+  // runtime's resolver. 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 resolveGate: (request: NativeGateRequest) -> Promise<Promise<GateDecision>> =
+    defaultResolveGate
   override var onGate: (event: GateEvent) -> Unit = {}
 
   // MARK: Player callbacks
@@ -373,8 +402,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       browserManager.config = buildConfig()
       val tabs = browserManager.queryTabs()
       if (tabs.isNotEmpty()) {
-        Timber.d("Using first tab as default path: ${tabs[0].url}")
-        tabs[0].url
+        Timber.d("Using first tab as default path: ${tabs[0].path}")
+        tabs[0].path
       } else {
         Timber.d("Using root path as default: /")
         "/"
@@ -612,26 +641,38 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
   }
 
   override fun navigateTrack(track: Track) {
+    // A disabled track is unavailable — it never plays, whichever surface or
+    // stale resume path delivered the selection (Track.disabled; mirrors iOS
+    // TrackSelector.select). Refused before any state changes: an inert tap
+    // must not clear an unrelated navigation error or cancel an in-flight
+    // navigation.
+    if (track.disabled == true) {
+      Timber.d("Ignoring selection of disabled track: ${track.title}")
+      return
+    }
+
     clearNavigationError()
 
     // Cancel previous navigation to avoid race conditions
     navigationJob?.cancel()
 
-    val url = track.url
+    val path = track.path
     navigationJob =
       mainScope.launch {
         try {
           when {
-            // Check if this is a contextual URL (playable-only track with queue context)
-            url != null && BrowserPathHelper.isContextual(url) -> {
-              Timber.d("Navigating to contextual track URL: $url")
+            // Check if this is a contextual path (playable-only track with queue context)
+            path != null && BrowserPathHelper.isContextual(path) -> {
+              Timber.d("Navigating to contextual track path: $path")
 
-              val parentPath = BrowserPathHelper.stripTrackId(url)
-              val trackId = BrowserPathHelper.extractTrackId(url)
+              val parentPath = BrowserPathHelper.stripTrackId(path)
+              val trackId = BrowserPathHelper.extractTrackId(path)
 
-              // Check if queue already came from this parent path - just skip to the track
+              // Check if queue already came from this parent path - just skip
+              // to the tapped surface (exact path first, identity for
+              // index-less paths — see indexOfTappedTrack)
               if (trackId != null && parentPath == player.queueSourcePath) {
-                val index = player.tracks.indexOfFirst { it.src == trackId }
+                val index = player.tracks.indexOfTappedTrack(path, trackId)
                 if (index >= 0) {
                   Timber.d("Queue already from $parentPath, skipping to index $index")
                   handleTrackLoad(
@@ -649,8 +690,8 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
                 }
               }
 
-              // Expand the queue from the contextual URL
-              val expanded = browserManager.expandQueueFromContextualUrl(url)
+              // Expand the queue from the contextual path
+              val expanded = browserManager.expandQueueFromContextualPath(path)
 
               if (expanded != null) {
                 val (tracks, startIndex) = expanded
@@ -685,9 +726,9 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
               }
             }
             // Navigate to browsable track to show browsing UI
-            url != null -> {
-              Timber.d("Navigating to browsable track: $url")
-              browserManager.navigate(url)
+            path != null -> {
+              Timber.d("Navigating to browsable track: $path")
+              browserManager.navigate(path)
             }
             // If track is playable (has src), load it into player
             track.src != null -> {
@@ -702,13 +743,13 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
               )
             }
             else -> {
-              throw IllegalArgumentException("Track must have either an 'url' or an 'src' property")
+              throw IllegalArgumentException("Track must have either a 'path' or an 'src' property")
             }
           }
         } catch (e: CancellationException) {
           throw e // Rethrow to properly cancel
         } catch (e: Exception) {
-          handleBrowserException(e, url ?: track.src ?: "", "navigating to track: ${track.title}")
+          handleBrowserException(e, path ?: track.src ?: "", "navigating to track: ${track.title}")
         }
       }
   }
@@ -717,7 +758,10 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     return Promise.async(mainScope) {
       Timber.d("Searching for: $query")
       val searchResults = browserManager.search(query)
-      searchResults.children ?: emptyArray()
+      // Flattened, not `children`: a resolved page carries its rows in
+      // `sections` (ADR 0010) and search builds exactly one untitled section,
+      // so `children` is always null here and this returned nothing at all.
+      searchResults.flattenedChildren?.toTypedArray() ?: emptyArray()
     }
   }
 
@@ -1027,12 +1071,15 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       player.setQueue(tracks, startIndex?.toInt() ?: 0, ((startPosition ?: 0.0) * 1000).toLong())
     }
 
-  override fun setActiveTrackFavorited(favorited: Boolean) = runBlockingOnMain {
+  override fun setActiveTrackFavorited(favorited: Boolean): Unit = runBlockingOnMain {
+    // Applied-result is for MediaSession honesty; the JS API stays fire-and-forget.
     player.setActiveTrackFavorited(favorited)
+    Unit
   }
 
-  override fun toggleActiveTrackFavorited() = runBlockingOnMain {
+  override fun toggleActiveTrackFavorited(): Unit = runBlockingOnMain {
     player.toggleActiveTrackFavorited()
+    Unit
   }
 
   override fun getQueue(): Array<Track> = runBlockingOnMain { player.tracks }
@@ -1494,6 +1541,11 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
       current.getAndSet(null)?.dispose()
     }
 
+    /** Shared by the [resolveGate] initializer and [dispose], which reverts to it. */
+    private val defaultResolveGate: (NativeGateRequest) -> Promise<Promise<GateDecision>> = {
+      Promise.resolved(Promise.resolved(GateDecision(gated = true, gate = null)))
+    }
+
     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.
@@ -1510,3 +1562,40 @@ class AudioBrowser : HybridAudioBrowserSpec(), ServiceConnection {
     }
   }
 }
+
+// MARK: Deep JS-callback stripping (used by dispose)
+// Functions live at every level of the config, not just the top; each type's strip nils its own.
+
+private fun NativeBrowserConfiguration.strippingJSCallbacks() =
+  copy(
+    requestResolver = null,
+    browseResolver = null,
+    handleTrackLoad = null,
+    resolveAlbumPath = null,
+    formatNavigationError = null,
+    request = request?.strippingJSCallbacks(),
+    browse = browse?.strippingJSCallbacks(),
+    media = media?.strippingJSCallbacks(),
+    artwork = artwork?.strippingJSCallbacks(),
+    nowPlayingArtwork = nowPlayingArtwork?.strippingJSCallbacks(),
+    routes = routes?.map { it.strippingJSCallbacks() }?.toTypedArray(),
+  )
+
+private fun TransformableRequestConfig.strippingJSCallbacks() =
+  copy(transform = null, transformSync = null)
+
+private fun MediaRequestConfig.strippingJSCallbacks() =
+  copy(resolve = null, resolveSync = null, transform = null, transformSync = null)
+
+private fun ArtworkRequestConfig.strippingJSCallbacks() =
+  copy(resolve = null, resolveSync = null, transform = null, transformSync = null)
+
+private fun NativeRouteEntry.strippingJSCallbacks() =
+  copy(
+    browseCallback = null,
+    browseConfig = browseConfig?.strippingJSCallbacks(),
+    searchCallback = null,
+    searchConfig = searchConfig?.strippingJSCallbacks(),
+    media = media?.strippingJSCallbacks(),
+    artwork = artwork?.strippingJSCallbacks(),
+  )