@5stones/react-native-audio-browser 0.1.6 → 0.3.0

package/android/src/test/java/com/audiobrowser/browser/SimpleRouterTest.kt

@@ -7,150 +7,159 @@ class SimpleRouterTest {
 
   private val router = SimpleRouter()
 
-  @Test
-  fun `exact match works`() {
-    val routes = mapOf("/artists" to "config1")
-    val result = router.findBestMatch("/artists", routes)
+  // -- exact matches --
 
+  @Test
+  fun `matches a simple path`() {
+    val result = router.findBestMatch("/artists", mapOf("/artists" to true))
     assertNotNull(result)
     assertEquals("/artists", result!!.first)
     assertTrue(result.second.params.isEmpty())
   }
 
   @Test
-  fun `parameter extraction works`() {
-    val routes = mapOf("/artists/{id}" to "config1")
-    val result = router.findBestMatch("/artists/123", routes)
-
+  fun `matches multi-segment paths`() {
+    val result = router.findBestMatch("/artists/top/rated", mapOf("/artists/top/rated" to true))
     assertNotNull(result)
-    assertEquals("/artists/{id}", result!!.first)
-    assertEquals("123", result.second.params["id"])
+    assertEquals("/artists/top/rated", result!!.first)
   }
 
   @Test
-  fun `multiple parameters work`() {
-    val routes = mapOf("/artists/{artistId}/albums/{albumId}" to "config1")
-    val result = router.findBestMatch("/artists/123/albums/456", routes)
-
-    assertNotNull(result)
-    assertEquals("123", result!!.second.params["artistId"])
-    assertEquals("456", result.second.params["albumId"])
+  fun `returns null when no route matches`() {
+    assertNull(router.findBestMatch("/unknown", mapOf("/artists" to true)))
   }
 
   @Test
-  fun `specificity works - constants win over parameters`() {
-    val routes = mapOf("/artists/{id}" to "generic", "/artists/popular" to "specific")
-    val result = router.findBestMatch("/artists/popular", routes)
-
-    assertEquals("/artists/popular", result!!.first)
+  fun `returns null when segment count differs`() {
+    assertNull(router.findBestMatch("/artists/123", mapOf("/artists" to true)))
   }
 
   @Test
-  fun `specificity works - more segments win`() {
-    val routes = mapOf("/artists" to "short", "/artists/premium" to "longer")
-
-    val result1 = router.findBestMatch("/artists", routes)
-    assertEquals("/artists", result1!!.first)
-
-    val result2 = router.findBestMatch("/artists/premium", routes)
-    assertEquals("/artists/premium", result2!!.first)
+  fun `returns null when routes are empty`() {
+    assertNull(router.findBestMatch("/artists", emptyMap<String, Boolean>()))
   }
 
   @Test
-  fun `no match returns null`() {
-    val routes = mapOf("/artists" to "config1")
-    val result = router.findBestMatch("/songs", routes)
-
-    assertNull(result)
+  fun `treats trailing slashes the same as without`() {
+    val result = router.findBestMatch("/artists/", mapOf("/artists" to true))
+    assertNotNull(result)
+    assertEquals("/artists", result!!.first)
   }
 
-  @Test
-  fun `different segment count returns null`() {
-    val routes = mapOf("/artists/{id}" to "config1")
-    val result = router.findBestMatch("/artists/123/extra", routes)
+  // -- parameter extraction --
 
-    assertNull(result)
+  @Test
+  fun `extracts a single parameter`() {
+    val result = router.findBestMatch("/artists/123", mapOf("/artists/{id}" to true))
+    assertNotNull(result)
+    assertEquals(mapOf("id" to "123"), result!!.second.params)
   }
 
   @Test
-  fun `single wildcard matching works`() {
-    val routes = mapOf("/artists/*" to "wildcard")
-    val result = router.findBestMatch("/artists/anything", routes)
-
+  fun `extracts multiple parameters`() {
+    val result =
+      router.findBestMatch(
+        "/artists/123/albums/456",
+        mapOf("/artists/{artistId}/albums/{albumId}" to true),
+      )
     assertNotNull(result)
-    assertEquals("/artists/*", result!!.first)
-    assertTrue(result.second.params.isEmpty()) // Wildcards don't capture
+    assertEquals(mapOf("artistId" to "123", "albumId" to "456"), result!!.second.params)
   }
 
+  // -- single wildcard --
+
   @Test
-  fun `tail wildcard matching works`() {
-    val routes = mapOf("/files/**" to "allFiles")
+  fun `matches any single segment`() {
+    assertNotNull(router.findBestMatch("/artists/anything", mapOf("/artists/*" to true)))
+  }
 
-    val result1 = router.findBestMatch("/files/docs/readme.md", routes)
-    assertNotNull(result1)
-    assertEquals("docs/readme.md", result1!!.second.params["tail"])
+  @Test
+  fun `does not extract wildcard value into params`() {
+    val result = router.findBestMatch("/artists/anything", mapOf("/artists/*" to true))
+    assertTrue(result!!.second.params.isEmpty())
+  }
 
-    val result2 = router.findBestMatch("/files/images/2023/vacation.jpg", routes)
-    assertNotNull(result2)
-    assertEquals("images/2023/vacation.jpg", result2!!.second.params["tail"])
+  // -- tail wildcard --
 
-    // Also matches shorter paths
-    val result3 = router.findBestMatch("/files", routes)
-    assertNotNull(result3)
-    assertFalse(result3!!.second.params.containsKey("tail")) // No tail captured
+  @Test
+  fun `matches with no remaining segments and has no tail param`() {
+    val result = router.findBestMatch("/files", mapOf("/files/**" to true))
+    assertNotNull(result)
+    assertTrue(result!!.second.params.isEmpty())
   }
 
   @Test
-  fun `wildcard specificity works correctly`() {
-    val routes =
-      mapOf(
-        "/artists/*" to "wildcard",
-        "/artists/{id}" to "parameter",
-        "/artists/popular" to "constant",
-      )
+  fun `matches with remaining segments and captures tail`() {
+    val result = router.findBestMatch("/files/a/b/c", mapOf("/files/**" to true))
+    assertNotNull(result)
+    assertEquals(mapOf("tail" to "a/b/c"), result!!.second.params)
+  }
 
-    // Constant wins
-    val result1 = router.findBestMatch("/artists/popular", routes)
-    assertEquals("/artists/popular", result1!!.first)
+  @Test
+  fun `matches with a single remaining segment`() {
+    val result = router.findBestMatch("/files/readme.txt", mapOf("/files/**" to true))
+    assertNotNull(result)
+    assertEquals(mapOf("tail" to "readme.txt"), result!!.second.params)
+  }
 
-    // Parameter wins over wildcard for non-constant values
-    val result2 = router.findBestMatch("/artists/123", routes)
-    assertEquals("/artists/{id}", result2!!.first)
-    assertEquals("123", result2.second.params["id"])
+  @Test
+  fun `returns null when prefix segments do not match`() {
+    assertNull(router.findBestMatch("/other/a/b", mapOf("/files/**" to true)))
   }
 
   @Test
-  fun `tail wildcard specificity works`() {
-    val routes =
-      mapOf("/api/**" to "catchAll", "/api/users" to "specific", "/api/users/{id}" to "userById")
+  fun `works with parameters before tail wildcard`() {
+    val result =
+      router.findBestMatch("/api/v1/users/list", mapOf("/api/{version}/**" to true))
+    assertNotNull(result)
+    assertEquals(mapOf("version" to "v1", "tail" to "users/list"), result!!.second.params)
+  }
 
-    // Specific routes win over tail wildcard
-    val result1 = router.findBestMatch("/api/users", routes)
-    assertEquals("/api/users", result1!!.first)
+  @Test
+  fun `matches any path with bare tail wildcard pattern`() {
+    val result = router.findBestMatch("/any/path/here", mapOf("/**" to true))
+    assertNotNull(result)
+    assertEquals(mapOf("tail" to "any/path/here"), result!!.second.params)
+  }
 
-    val result2 = router.findBestMatch("/api/users/123", routes)
-    assertEquals("/api/users/{id}", result2!!.first)
+  // -- specificity --
 
-    // Tail wildcard catches unmatched paths
-    val result3 = router.findBestMatch("/api/posts/recent", routes)
-    assertEquals("/api/**", result3!!.first)
-    assertEquals("posts/recent", result3.second.params["tail"])
+  @Test
+  fun `prefers constant segments over parameters`() {
+    val routes = mapOf("/artists/{id}" to true, "/artists/top" to true)
+    val result = router.findBestMatch("/artists/top", routes)
+    assertEquals("/artists/top", result!!.first)
   }
 
   @Test
-  fun `example from plan works`() {
-    val routes =
-      mapOf("/artists" to "generic", "/artists/{id}" to "byId", "/artists/premium" to "premium")
+  fun `prefers parameters over wildcards`() {
+    val routes = mapOf("/artists/*" to true, "/artists/{id}" to true)
+    val result = router.findBestMatch("/artists/123", routes)
+    assertEquals("/artists/{id}", result!!.first)
+  }
 
-    // Test each case
-    val result1 = router.findBestMatch("/artists", routes)
-    assertEquals("/artists", result1!!.first)
+  @Test
+  fun `prefers exact match over tail wildcard`() {
+    val routes = mapOf("/api/**" to true, "/api/{version}" to true)
+    val result = router.findBestMatch("/api/v1", routes)
+    assertEquals("/api/{version}", result!!.first)
+  }
 
-    val result2 = router.findBestMatch("/artists/123", routes)
-    assertEquals("/artists/{id}", result2!!.first)
-    assertEquals("123", result2.second.params["id"])
+  @Test
+  fun `computes correct specificity for tail wildcard patterns`() {
+    // Regression test for issue #27: specificity must account for
+    // segment types before the ** wildcard.
+    val result = router.findBestMatch("/api/v1/users", mapOf("/api/v1/**" to true))
+    // constant "api" (1000) + constant "v1" (1000) + tail(1) + 3 segments = 2004
+    assertEquals(2004, result!!.second.specificity)
+  }
 
-    val result3 = router.findBestMatch("/artists/premium", routes)
-    assertEquals("/artists/premium", result3!!.first) // More specific than {id}
+  @Test
+  fun `prefers constant prefix over parameter prefix in tail wildcards`() {
+    // Second part of issue #27: with correct specificity, the constant
+    // prefix should beat the parameter prefix.
+    val routes = mapOf("/api/{version}/**" to true, "/api/v1/**" to true)
+    val result = router.findBestMatch("/api/v1/users", routes)
+    assertEquals("/api/v1/**", result!!.first)
   }
 }

package/ios/Browser/BrowserConfig.swift

@@ -1,5 +1,6 @@
 import Foundation
 import NitroModules
+import os.log
 
 /// Flattened browser configuration (matches Kotlin BrowserConfig).
 ///
@@ -33,6 +34,9 @@ struct BrowserConfig {
   /// Custom buttons for CarPlay Now Playing screen (e.g., .repeat, .favorite)
   let carPlayNowPlayingButtons: [CarPlayNowPlayingButton]
 
+  /// Custom handler for track load events (overrides default load behavior)
+  let handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)?
+
   /// Callback to customize navigation error display (for i18n)
   /// Used by CarPlay and available via `useFormattedNavigationError()` for app UI.
   let formatNavigationError: ((_ params: FormatNavigationErrorParams) -> Promise<FormattedNavigationError?>)?
@@ -43,6 +47,7 @@ struct BrowserConfig {
     artwork: ArtworkRequestConfig? = nil,
     routes: [NativeRouteEntry]? = nil,
     singleTrack: Bool = false,
+    handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)? = nil,
     androidControllerOfflineError: Bool = true,
     carPlayUpNextButton: Bool = true,
     carPlayNowPlayingButtons: [CarPlayNowPlayingButton] = [],
@@ -53,6 +58,7 @@ struct BrowserConfig {
     self.artwork = artwork
     self.routes = routes
     self.singleTrack = singleTrack
+    self.handleTrackLoad = handleTrackLoad
     self.androidControllerOfflineError = androidControllerOfflineError
     self.carPlayUpNextButton = carPlayUpNextButton
     self.carPlayNowPlayingButtons = carPlayNowPlayingButtons
@@ -66,17 +72,37 @@ struct BrowserConfig {
     artwork = config.artwork
     routes = config.routes
     singleTrack = config.singleTrack ?? false
+    handleTrackLoad = config.handleTrackLoad
     androidControllerOfflineError = config.androidControllerOfflineError ?? true
     carPlayUpNextButton = config.carPlayUpNextButton ?? true
     carPlayNowPlayingButtons = config.carPlayNowPlayingButtons ?? []
     formatNavigationError = config.formatNavigationError
   }
 
-  /// Returns true if search functionality is configured (either callback or config).
-  var hasSearch: Bool {
-    guard let routes else { return false }
-    let searchEntry = routes.first { $0.path == BrowserManager.searchRoutePath }
-    return searchEntry?.searchCallback != nil || searchEntry?.searchConfig != nil
+  // MARK: - Track Load Handler
+
+  private static let logger = Logger(subsystem: "com.audiobrowser", category: "BrowserConfig")
+
+  /// Awaits the handleTrackLoad callback using the double-Promise pattern required by Nitro.
+  ///
+  /// Nitro wraps value-returning JS callbacks in Promise<T> for thread safety, so a JS callback
+  /// returning Promise<void> becomes Promise<Promise<Void>> on the native side. Both layers
+  /// must be awaited to properly wait for the JS work to complete.
+  ///
+  /// - Returns: true if the handler was present and invoked, false if not configured
+  func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool {
+    guard let handler = handleTrackLoad else { return false }
+    do {
+      // MainActor: Nitro bridge call must be on main thread (C++ noexcept)
+      nonisolated(unsafe) let _handler = handler
+      nonisolated(unsafe) let _event = event
+      let outerPromise = await MainActor.run { _handler(_event) }
+      let innerPromise = try await outerPromise.await()
+      try await innerPromise.await()
+    } catch {
+      Self.logger.error("handleTrackLoad failed: \(error.localizedDescription)")
+    }
+    return true
   }
 }
 

package/ios/Browser/BrowserManager.swift

@@ -183,6 +183,7 @@ final class BrowserManager: @unchecked Sendable {
       favorited: isFavorited,
       groupTitle: track.groupTitle,
       live: track.live,
+      imageRow: track.imageRow,
     )
   }
 
@@ -193,6 +194,7 @@ final class BrowserManager: @unchecked Sendable {
     return ResolvedTrack(
       url: resolvedTrack.url,
       children: hydratedChildren,
+      carPlaySiriListButton: resolvedTrack.carPlaySiriListButton,
       src: resolvedTrack.src,
       artwork: resolvedTrack.artwork,
       artworkSource: resolvedTrack.artworkSource,
@@ -209,6 +211,7 @@ final class BrowserManager: @unchecked Sendable {
       favorited: resolvedTrack.favorited,
       groupTitle: resolvedTrack.groupTitle,
       live: resolvedTrack.live,
+      imageRow: resolvedTrack.imageRow,
     )
   }
 
@@ -336,6 +339,7 @@ final class BrowserManager: @unchecked Sendable {
       return ResolvedTrack(
         url: resolvedTrack.url,
         children: transformedChildren,
+        carPlaySiriListButton: resolvedTrack.carPlaySiriListButton,
         src: resolvedTrack.src,
         artwork: resolvedTrack.artwork,
         artworkSource: resolvedTrack.artworkSource,
@@ -352,6 +356,7 @@ final class BrowserManager: @unchecked Sendable {
         favorited: resolvedTrack.favorited,
         groupTitle: resolvedTrack.groupTitle,
         live: resolvedTrack.live,
+        imageRow: resolvedTrack.imageRow,
       )
     }
 
@@ -393,7 +398,8 @@ final class BrowserManager: @unchecked Sendable {
     if let callback = entry.browseCallback {
       let callbackParam = BrowserSourceCallbackParam(path: path, routeParams: params)
       // Callback returns Promise<Promise<BrowseResult>> - await both layers
-      let outerPromise = callback(callbackParam)
+      // MainActor: Nitro bridge call must be on main thread (C++ noexcept)
+      let outerPromise = await MainActor.run { callback(callbackParam) }
       let innerPromise = try await outerPromise.await()
       let result = try await innerPromise.await()
 
@@ -526,6 +532,7 @@ final class BrowserManager: @unchecked Sendable {
           favorited: track.favorited,
           groupTitle: track.groupTitle,
           live: track.live,
+          imageRow: track.imageRow,
         )
       }
 
@@ -553,6 +560,63 @@ final class BrowserManager: @unchecked Sendable {
             favorited: transformedTrack.favorited,
             groupTitle: transformedTrack.groupTitle,
             live: transformedTrack.live,
+            imageRow: transformedTrack.imageRow,
+          )
+        }
+
+        // Also resolve artwork for image row items
+        if let imageRowItems = transformedTrack.imageRow {
+          let artworkConfig = routeEntry.artwork ?? config.artwork
+          var resolvedItems: [ImageRowItem] = []
+          for item in imageRowItems {
+            // Create a minimal Track to pass to the artwork resolver
+            let itemTrack = Track(
+              url: item.url,
+              src: nil,
+              artwork: item.artwork,
+              artworkSource: nil,
+              artworkCarPlayTinted: nil,
+              title: item.title,
+              subtitle: nil,
+              artist: nil,
+              album: nil,
+              description: nil,
+              genre: nil,
+              duration: nil,
+              style: nil,
+              childrenStyle: nil,
+              favorited: nil,
+              groupTitle: nil,
+              live: nil,
+              imageRow: nil,
+            )
+            let itemImageSource = await resolver(itemTrack, artworkConfig, browseContext)
+            resolvedItems.append(ImageRowItem(
+              url: item.url,
+              artwork: item.artwork,
+              artworkSource: itemImageSource,
+              title: item.title,
+            ))
+          }
+          transformedTrack = Track(
+            url: transformedTrack.url,
+            src: transformedTrack.src,
+            artwork: transformedTrack.artwork,
+            artworkSource: transformedTrack.artworkSource,
+            artworkCarPlayTinted: transformedTrack.artworkCarPlayTinted,
+            title: transformedTrack.title,
+            subtitle: transformedTrack.subtitle,
+            artist: transformedTrack.artist,
+            album: transformedTrack.album,
+            description: transformedTrack.description,
+            genre: transformedTrack.genre,
+            duration: transformedTrack.duration,
+            style: transformedTrack.style,
+            childrenStyle: transformedTrack.childrenStyle,
+            favorited: transformedTrack.favorited,
+            groupTitle: transformedTrack.groupTitle,
+            live: transformedTrack.live,
+            imageRow: resolvedItems,
           )
         }
       }
@@ -573,6 +637,7 @@ final class BrowserManager: @unchecked Sendable {
       return ResolvedTrack(
         url: BrowserPathHelper.createSearchPath(query),
         children: hydratedResults,
+        carPlaySiriListButton: nil,
         src: nil,
         artwork: nil,
         artworkSource: nil,
@@ -589,6 +654,7 @@ final class BrowserManager: @unchecked Sendable {
         favorited: nil,
         groupTitle: nil,
         live: nil,
+        imageRow: nil,
       )
     }
 
@@ -614,7 +680,8 @@ final class BrowserManager: @unchecked Sendable {
 
     if let callback = searchEntry.searchCallback {
       // Callback returns Promise<Promise<[Track]>> - await both layers
-      let outerPromise = callback(searchParams)
+      // MainActor: Nitro bridge call must be on main thread (C++ noexcept)
+      let outerPromise = await MainActor.run { callback(searchParams) }
       let innerPromise = try await outerPromise.await()
       results = try await innerPromise.await()
     } else if let searchConfig = searchEntry.searchConfig {
@@ -637,6 +704,7 @@ final class BrowserManager: @unchecked Sendable {
     return ResolvedTrack(
       url: BrowserPathHelper.createSearchPath(query),
       children: hydratedResults,
+      carPlaySiriListButton: nil,
       src: nil,
       artwork: nil,
       artworkSource: nil,
@@ -653,6 +721,7 @@ final class BrowserManager: @unchecked Sendable {
       favorited: nil,
       groupTitle: nil,
       live: nil,
+      imageRow: nil,
     )
   }
 
@@ -743,27 +812,17 @@ final class BrowserManager: @unchecked Sendable {
         )
 
         logger.debug("resolveMediaUrl: calling transform callback...")
-        // MediaRequestConfig.transform takes (request, routeParams) - pass nil for routeParams
-        // Call the JS transform outside the task group to avoid sending-parameter
-        // data-race warnings (transform and baseRequest aren't Sendable).
-        let outerPromise = transform(baseRequest, nil)
+        // Dispatch the Nitro bridge call to MainActor to avoid C++ noexcept crashes.
+        // The generated C++ call() wrapper is noexcept, so any exception from JSI
+        // causes std::terminate. Calling from the main thread is safer for JS callbacks.
+        // Only the initial call is dispatched; awaiting happens on the background thread.
+        let outerPromise = await MainActor.run {
+          transform(baseRequest, nil)
+        }
+        logger.debug("resolveMediaUrl: awaiting outer promise...")
         let innerPromise = try await outerPromise.await()
         logger.debug("resolveMediaUrl: awaiting inner promise...")
-        let transformedConfig = try await withThrowingTaskGroup(of: RequestConfig.self) { group in
-          group.addTask { [innerPromise] in
-            return try await innerPromise.await()
-          }
-          group.addTask {
-            // Safety-net timeout: if the JS transform Promise doesn't resolve
-            // within 10s, bail out. This guards against Nitro bridge hangs when
-            // concurrent callbacks race.
-            try await Task.sleep(nanoseconds: 10_000_000_000)
-            throw CancellationError()
-          }
-          let result = try await group.next()!
-          group.cancelAll()
-          return result
-        }
+        let transformedConfig = try await innerPromise.await()
         logger.debug("resolveMediaUrl: transform complete")
 
         // Extract values immediately to Swift native types to avoid
@@ -834,6 +893,18 @@ final class BrowserManager: @unchecked Sendable {
   ///   - imageContext: Optional size context for CDN URL generation (nil at browse-time)
   /// - Returns: ImageSource ready for image loading, or nil if no artwork
   func resolveArtworkUrl(track: Track, perRouteConfig: ArtworkRequestConfig?, imageContext: ImageContext? = nil) async -> ImageSource? {
+    if let artwork = track.artwork, SFSymbolRenderer.isSFSymbol(artwork) {
+      let canvasSize: CGSize = if let w = imageContext?.width, let h = imageContext?.height {
+        CGSize(width: w, height: h)
+      } else {
+        SFSymbolRenderer.defaultCanvasSize
+      }
+      if let uri = await SFSymbolRenderer.shared.render(artwork, canvasSize: canvasSize) {
+        return ImageSource(uri: uri, method: nil, headers: nil, body: nil)
+      }
+      return nil
+    }
+
     // Determine effective artwork config: per-route overrides global
     let effectiveArtworkConfig = perRouteConfig ?? config.artwork
 
@@ -863,7 +934,8 @@ final class BrowserManager: @unchecked Sendable {
 
       // If there's a resolve callback, call it for per-track config
       if let resolve = artworkConfig.resolve {
-        let outerPromise = resolve(track)
+        // MainActor: Nitro bridge call must be on main thread (C++ noexcept)
+        let outerPromise = await MainActor.run { resolve(track) }
         let innerPromise = try await outerPromise.await()
         let resolvedConfig = try await innerPromise.await()
 
@@ -919,7 +991,10 @@ final class BrowserManager: @unchecked Sendable {
       // Transform will be called at load-time when actual display size is known
       let hasSize = imageContext?.width != nil || imageContext?.height != nil
       if let transform = artworkConfig.transform, hasSize {
-        let outerPromise = transform(MediaTransformParams(request: mergedConfig, context: imageContext))
+        // MainActor: Nitro bridge call must be on main thread (C++ noexcept)
+        let outerPromise = await MainActor.run {
+          transform(MediaTransformParams(request: mergedConfig, context: imageContext))
+        }
         let innerPromise = try await outerPromise.await()
         let transformedConfig = try await innerPromise.await()