react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/ios/Browser/TrackIdTemplate.swift

@@ -0,0 +1,37 @@
+import Foundation
+
+/// `{id}` template-token substitution for request-config string values (path, query values,
+/// header values), used by artwork URL resolution so a `nowPlayingArtwork` like
+/// `{ path: "/artwork/{id}" }` resolves per track.
+///
+/// A track without a non-blank id leaves the token LITERALLY in place — the request then
+/// visibly 404s, which is intended (garbage in, garbage out with a self-describing error
+/// trail; the caller logs a single warning when `containsToken` still matches after
+/// substitution). Mirrors Android's `substituteTrackId` / `configContainsIdToken` in
+/// `BrowserUrlResolution.kt` — keep the two in sync.
+enum TrackIdTemplate {
+  static let token = "{id}"
+
+  /// Replaces the token when `id` is non-blank; otherwise returns the value unchanged
+  /// (token left literal).
+  static func substitute(_ value: String?, id: String?) -> String? {
+    guard let id, !id.isEmpty else { return value }
+    return value?.replacingOccurrences(of: token, with: id)
+  }
+
+  /// Dictionary-value variant of `substitute` (query / header values).
+  static func substitute(_ values: [String: String]?, id: String?) -> [String: String]? {
+    guard let id, !id.isEmpty else { return values }
+    return values?.mapValues { $0.replacingOccurrences(of: token, with: id) }
+  }
+
+  /// Whether the value still carries the token (an unfilled `{id}`).
+  static func containsToken(_ value: String?) -> Bool {
+    value?.contains(token) == true
+  }
+
+  /// Whether any dictionary value still carries the token.
+  static func containsToken(_ values: [String: String]?) -> Bool {
+    values?.values.contains { $0.contains(token) } == true
+  }
+}

package/ios/CarPlay/CPInterfaceController+Safe.swift

@@ -12,6 +12,10 @@ import os.log
 /// preconditions are checked up front, the underlying call always gets a
 /// completion, and every failure is logged, with an optional caller completion
 /// for call sites that chain on the result.
+///
+/// A push onto a full stack replaces the top template (`TopTemplateReplacer`).
+/// The stack mutations wait for that replacement to settle before they run,
+/// so none of them lands between its pop and its push.
 @MainActor
 extension CPInterfaceController {
   private static let stackLogger = Logger(subsystem: "com.audiobrowser", category: "TemplateStack")
@@ -26,9 +30,54 @@ extension CPInterfaceController {
   /// push — taking down the whole app, not just the CarPlay scene.
   private static let maximumStackDepth = 5
 
+  private static var topReplacerKey: UInt8 = 0
+
+  private var topReplacer: TopTemplateReplacer {
+    if let replacer = objc_getAssociatedObject(self, &Self.topReplacerKey) as? TopTemplateReplacer {
+      return replacer
+    }
+    let replacer = TopTemplateReplacer()
+    objc_setAssociatedObject(self, &Self.topReplacerKey, replacer, .OBJC_ASSOCIATION_RETAIN_NONATOMIC)
+    return replacer
+  }
+
+  private func whenStackSettled(_ mutation: @escaping (CPInterfaceController) -> Void) {
+    topReplacer.whenSettled { [weak self] in
+      guard let self else { return }
+      mutation(self)
+    }
+  }
+
+  /// Pushes `template`, skipping the raise case (already in the hierarchy). At
+  /// the depth limit it replaces the top template.
+  func safePush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+    whenStackSettled { controller in
+      let templates = controller.templates
+      guard templates.count >= Self.maximumStackDepth, !templates.contains(where: { $0 === template }) else {
+        controller.guardedPush(template, animated: animated, completion: completion)
+        return
+      }
+      controller.topReplacer.push(
+        template, replacingTopOf: GuardedTemplateStack(controller: controller), animated: animated,
+        completion: completion,
+      )
+    }
+  }
+
+  /// Replaces `expected` with `template` while `expected` is still the top template, restoring
+  /// it if the push fails; a no-op once the user has moved on.
+  func safeReplaceTop(_ expected: CPTemplate, with template: CPTemplate, animated: Bool) {
+    whenStackSettled { controller in
+      guard controller.topTemplate === expected else { return }
+      controller.topReplacer.push(
+        template, replacingTopOf: GuardedTemplateStack(controller: controller), animated: animated,
+      )
+    }
+  }
+
   /// Pushes `template`, skipping the raise cases (already in the hierarchy,
   /// stack at the depth limit).
-  func safePush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+  fileprivate func guardedPush(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)?) {
     guard !templates.contains(where: { $0 === template }) else {
       Self.stackLogger.warning("push skipped: \(Self.name(of: template)) is already in the stack")
       completion?(false, nil)
@@ -48,7 +97,7 @@ extension CPInterfaceController {
   }
 
   /// Pops the top template, skipping the raise case (nothing above the root).
-  func safePop(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+  fileprivate func guardedPop(animated: Bool, completion: ((Bool, Error?) -> Void)?) {
     guard templates.count > 1 else {
       Self.stackLogger.warning("pop skipped: already at the root template")
       completion?(false, nil)
@@ -62,65 +111,73 @@ extension CPInterfaceController {
     }
   }
 
+  /// Pops the top template, skipping the raise case (nothing above the root).
+  func safePop(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
+    whenStackSettled { controller in
+      controller.guardedPop(animated: animated, completion: completion)
+    }
+  }
+
   /// Pops back to `template`, skipping the raise case (not in the hierarchy).
   /// A no-op success when it is already the top template.
   func safePop(to template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    guard templates.contains(where: { $0 === template }) else {
-      Self.stackLogger.warning("pop(to:) skipped: \(Self.name(of: template)) is not in the stack")
-      completion?(false, nil)
-      return
-    }
-    guard topTemplate !== template else {
-      completion?(true, nil)
-      return
-    }
-    pop(to: template, animated: animated) { popped, error in
-      if let error {
-        Self.stackLogger.error("pop(to:) \(Self.name(of: template)) failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      guard controller.templates.contains(where: { $0 === template }) else {
+        Self.stackLogger.warning("pop(to:) skipped: \(Self.name(of: template)) is not in the stack")
+        completion?(false, nil)
+        return
+      }
+      guard controller.topTemplate !== template else {
+        completion?(true, nil)
+        return
+      }
+      controller.pop(to: template, animated: animated) { popped, error in
+        if let error {
+          Self.stackLogger.error("pop(to:) \(Self.name(of: template)) failed: \(error.localizedDescription)")
+        }
+        completion?(popped, error)
       }
-      completion?(popped, error)
     }
   }
 
   func safePopToRoot(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    popToRootTemplate(animated: animated) { popped, error in
-      if let error {
-        Self.stackLogger.error("popToRootTemplate failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      controller.popToRootTemplate(animated: animated) { popped, error in
+        if let error {
+          Self.stackLogger.error("popToRootTemplate failed: \(error.localizedDescription)")
+        }
+        completion?(popped, error)
       }
-      completion?(popped, error)
     }
   }
 
   func safeSetRoot(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    setRootTemplate(template, animated: animated) { set, error in
-      if let error {
-        Self.stackLogger.error("setRootTemplate \(Self.name(of: template)) failed: \(error.localizedDescription)")
+    whenStackSettled { controller in
+      controller.setRootTemplate(template, animated: animated) { set, error in
+        if let error {
+          Self.stackLogger.error("setRootTemplate \(Self.name(of: template)) failed: \(error.localizedDescription)")
+        }
+        completion?(set, error)
       }
-      completion?(set, error)
     }
   }
+}
 
-  func safePresent(_ template: CPTemplate, animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    presentTemplate(template, animated: animated) { presented, error in
-      if let error {
-        Self.stackLogger.error("presentTemplate \(Self.name(of: template)) failed: \(error.localizedDescription)")
-      }
-      completion?(presented, error)
-    }
+/// The guarded pop and push a replacement is made of, so a push that still
+/// cannot fit skips and logs rather than raising.
+@MainActor
+private struct GuardedTemplateStack: TemplateStack {
+  let controller: CPInterfaceController
+
+  var templates: [CPTemplate] {
+    controller.templates
   }
 
-  /// Dismisses the presented template, skipping when nothing is presented.
-  func safeDismiss(animated: Bool, completion: ((Bool, Error?) -> Void)? = nil) {
-    guard presentedTemplate != nil else {
-      Self.stackLogger.debug("dismiss skipped: no presented template")
-      completion?(false, nil)
-      return
-    }
-    dismissTemplate(animated: animated) { dismissed, error in
-      if let error {
-        Self.stackLogger.error("dismissTemplate failed: \(error.localizedDescription)")
-      }
-      completion?(dismissed, error)
-    }
+  func popTop(completion: @escaping (Bool, Error?) -> Void) {
+    controller.guardedPop(animated: false, completion: completion)
+  }
+
+  func push(_ template: CPTemplate, animated: Bool, completion: @escaping (Bool, Error?) -> Void) {
+    controller.guardedPush(template, animated: animated, completion: completion)
   }
 }

package/ios/CarPlay/CarPlayArtworkResolver.swift

@@ -1,107 +1,60 @@
 import Foundation
 
-/// Represents a resolved artwork image URL with optional headers.
+/// An artwork URL and the headers to fetch it with.
 struct ArtworkResolvedImage: Equatable, Sendable {
   let uri: String
   let headers: [String: String]?
 }
 
-/// Describes what action to take for loading artwork.
-/// Produced by `CarPlayArtworkResolver`, consumed by `CarPlayImageLoader`.
+/// How `CarPlayImageLoader` loads one artwork.
 enum ArtworkLoadAction: Equatable, Sendable {
-  /// Render an SF Symbol from the artwork string at the given canvas size
+  /// Render the `sf:` artwork at this canvas size.
   case sfSymbol(artwork: String, width: Double, height: Double)
-  /// Fetch an image from a URL, optionally with headers, tinting, and SVG processing
   case fetch(uri: String, headers: [String: String]?, shouldTint: Bool, isSvg: Bool)
-  /// No artwork available
   case none
 }
 
-/// Determines artwork loading strategy without UIKit dependencies.
-///
-/// Encapsulates the decision tree for how to load artwork:
-/// 1. SF Symbol artwork → render directly
-/// 2. URL resolver available → resolve, then fetch from resolved URL
-/// 3. Fallback → fetch directly from artwork/artworkSource URL
+/// Decides how CarPlay loads a track's artwork, given what the Browser layer's
+/// `resolveArtworkUrl` returned for it.
 enum CarPlayArtworkResolver {
-  /// Resolves the artwork loading strategy for a track.
-  ///
-  /// - Parameters:
-  ///   - artwork: The track's `artwork` field (may be an SF Symbol string or URL)
-  ///   - artworkSourceUri: The track's `artworkSource?.uri` field
-  ///   - artworkCarPlayTinted: Whether to apply light/dark tinting
-  ///   - targetWidth: Target width in points
-  ///   - targetHeight: Target height in points
-  ///   - displayScale: The CarPlay display scale factor
-  ///   - urlResolver: Optional closure that resolves artwork URLs (wraps BrowserManager)
-  static func resolve(
-    artwork: String?,
-    artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
-    targetWidth: Double,
-    targetHeight: Double,
-    displayScale: Double,
-    urlResolver: ((Double, Double) async -> ArtworkResolvedImage?)?,
-  ) async -> ArtworkLoadAction {
-    // 1. Primary SF symbol check
-    if let artwork, artwork.hasPrefix("sf:") {
-      return .sfSymbol(artwork: artwork, width: targetWidth, height: targetHeight)
-    }
-
-    // 2. Try URL resolution via resolver
-    if let urlResolver {
-      let pixelWidth = targetWidth * displayScale
-      let pixelHeight = targetHeight * displayScale
-      if let resolved = await urlResolver(pixelWidth, pixelHeight) {
-        guard let resolvedUrl = URL(string: resolved.uri) else {
-          return resolveDirectFallback(
-            artwork: artwork,
-            artworkSourceUri: artworkSourceUri,
-            artworkCarPlayTinted: artworkCarPlayTinted,
-            targetWidth: targetWidth,
-            targetHeight: targetHeight,
-          )
-        }
-        let isSvg = resolvedUrl.pathExtension.lowercased() == "svg"
-        return .fetch(
-          uri: resolved.uri,
-          headers: resolved.headers,
-          shouldTint: artworkCarPlayTinted ?? false,
-          isSvg: isSvg,
-        )
-      }
-    }
-
-    // 3. Direct fallback
-    return resolveDirectFallback(
-      artwork: artwork,
-      artworkSourceUri: artworkSourceUri,
-      artworkCarPlayTinted: artworkCarPlayTinted,
-      targetWidth: targetWidth,
-      targetHeight: targetHeight,
-    )
+  /// Whether to ask the Browser layer at all: CarPlay renders an SF Symbol itself.
+  static func needsResolve(artwork: String?) -> Bool {
+    !isSFSymbol(artwork)
   }
 
-  private static func resolveDirectFallback(
+  /// An SF Symbol renders; otherwise the resolved URL is fetched, falling back to the track's
+  /// `artwork`, then its `artworkSource` with that source's headers. `stencil` tints the image
+  /// to the surface's appearance.
+  static func action(
     artwork: String?,
-    artworkSourceUri: String?,
-    artworkCarPlayTinted: Bool?,
-    targetWidth: Double,
-    targetHeight: Double,
+    artworkSource: ArtworkResolvedImage?,
+    resolved: ArtworkResolvedImage?,
+    stencil: Bool,
+    width: Double,
+    height: Double,
   ) -> ArtworkLoadAction {
-    guard let directUri = artwork ?? artworkSourceUri else { return .none }
-
-    if directUri.hasPrefix("sf:") {
-      return .sfSymbol(artwork: directUri, width: targetWidth, height: targetHeight)
+    if isSFSymbol(artwork), let artwork {
+      return .sfSymbol(artwork: artwork, width: width, height: height)
+    }
+    if let resolved, let action = fetch(resolved, stencil: stencil) {
+      return action
+    }
+    let direct = artwork.map { ArtworkResolvedImage(uri: $0, headers: nil) } ?? artworkSource
+    guard let direct else { return .none }
+    if isSFSymbol(direct.uri) {
+      return .sfSymbol(artwork: direct.uri, width: width, height: height)
     }
+    return fetch(direct, stencil: stencil) ?? .none
+  }
 
-    guard let directUrl = URL(string: directUri) else { return .none }
-    let isSvg = directUrl.pathExtension.lowercased() == "svg"
+  private static func fetch(_ image: ArtworkResolvedImage, stencil: Bool) -> ArtworkLoadAction? {
+    guard let url = URL(string: image.uri) else { return nil }
     return .fetch(
-      uri: directUri,
-      headers: nil,
-      shouldTint: artworkCarPlayTinted ?? false,
-      isSvg: isSvg,
+      uri: image.uri, headers: image.headers, shouldTint: stencil, isSvg: url.pathExtension.lowercased() == "svg",
     )
   }
+
+  private static func isSFSymbol(_ artwork: String?) -> Bool {
+    artwork?.hasPrefix("sf:") == true
+  }
 }