react-native-audio-browser 0.2.0-next.22 → 0.2.0-next.23

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,43 @@ 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,
+      )
+    }
+  }
+
   /// 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 +86,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,41 +100,54 @@ 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)
     }
   }
 
@@ -124,3 +175,22 @@ extension CPInterfaceController {
     }
   }
 }
+
+/// 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
+  }
+
+  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/TopTemplateReplacer.swift

@@ -0,0 +1,96 @@
+import Foundation
+import os.log
+
+/// The stack mutations a top-template replacement is made of:
+/// `CPInterfaceController` in the app, a fake in tests.
+@MainActor
+protocol TemplateStack {
+  associatedtype Template: AnyObject
+
+  /// Root first.
+  var templates: [Template] { get }
+
+  /// Unanimated.
+  func popTop(completion: @escaping (Bool, Error?) -> Void)
+  func push(_ template: Template, animated: Bool, completion: @escaping (Bool, Error?) -> Void)
+}
+
+/// Pushes onto a full template stack by replacing its top template — an
+/// unanimated pop, then the push — and holds back every other stack mutation
+/// until both have completed. See "Template Depth" in
+/// `website/guide/carplay.md`.
+@MainActor
+final class TopTemplateReplacer {
+  private let logger = Logger(subsystem: "com.audiobrowser", category: "TemplateStack")
+  private var deferred: [() -> Void] = []
+
+  /// True from the pop until the push completes.
+  private(set) var isReplacing = false
+
+  /// Runs `mutation` now, or — while a replacement is in flight — once it has
+  /// settled, after the mutations that arrived before it.
+  func whenSettled(_ mutation: @escaping () -> Void) {
+    guard isReplacing else {
+      mutation()
+      return
+    }
+    deferred.append(mutation)
+  }
+
+  /// Pushes `template` onto `stack` in place of its top template. When the
+  /// push fails, the popped template is pushed back, so the user stays where
+  /// they were. `completion` reports the push of `template` itself.
+  ///
+  /// Refuses a stack with nothing above the root to replace, and a call made
+  /// while a replacement is in flight: route it through `whenSettled`.
+  func push<Stack: TemplateStack>(
+    _ template: Stack.Template,
+    replacingTopOf stack: Stack,
+    animated: Bool,
+    completion: ((Bool, Error?) -> Void)? = nil,
+  ) {
+    let templates = stack.templates
+    guard !isReplacing, templates.count > 1, let top = templates.last else {
+      logger.error("push skipped: \(Self.name(of: template)) has no template to replace (\(templates.count) templates)")
+      completion?(false, nil)
+      return
+    }
+    isReplacing = true
+    logger.info("push at the depth limit: replacing the top, \(Self.name(of: top)), with \(Self.name(of: template))")
+
+    stack.popTop { [self] popped, error in
+      guard popped else {
+        logger.error("replace abandoned: pop failed, \(Self.name(of: template)) not pushed (\(stack.templates.count) templates)")
+        settle(completion, pushed: false, error: error)
+        return
+      }
+      stack.push(template, animated: animated) { [self] pushed, error in
+        guard !pushed else {
+          settle(completion, pushed: true, error: error)
+          return
+        }
+        logger.error("replace failed: \(Self.name(of: template)) not pushed, restoring \(Self.name(of: top))")
+        stack.push(top, animated: false) { [self] restored, _ in
+          if !restored {
+            logger.error("replace failed: \(Self.name(of: top)) not restored (\(stack.templates.count) templates)")
+          }
+          settle(completion, pushed: false, error: error)
+        }
+      }
+    }
+  }
+
+  private func settle(_ completion: ((Bool, Error?) -> Void)?, pushed: Bool, error: Error?) {
+    // Still replacing here, so a mutation the completion issues queues behind
+    // the ones that arrived during the replacement.
+    completion?(pushed, error)
+    isReplacing = false
+    while !isReplacing, !deferred.isEmpty {
+      deferred.removeFirst()()
+    }
+  }
+
+  private static func name(of template: AnyObject) -> String {
+    String(describing: type(of: template))
+  }
+}

package/ios/Tests/TopTemplateReplacerTests.swift

@@ -0,0 +1,172 @@
+import Foundation
+import Testing
+
+@testable import AudioBrowserTestable
+
+private final class Page {
+  let name: String
+  init(_ name: String) { self.name = name }
+}
+
+/// A template stack whose mutations complete only when the test steps them,
+/// the way CarPlay's complete on a later run-loop turn.
+@MainActor
+private final class FakeStack: TemplateStack {
+  private(set) var templates: [Page]
+  private(set) var calls: [String] = []
+  var failingPushes: Set<String> = []
+  var failsPop = false
+  private var pending: [() -> Void] = []
+
+  init(_ names: String...) {
+    templates = names.map(Page.init)
+  }
+
+  var names: [String] {
+    templates.map(\.name)
+  }
+
+  func popTop(completion: @escaping (Bool, Error?) -> Void) {
+    calls.append("pop")
+    pending.append { [self] in
+      guard !failsPop else {
+        completion(false, nil)
+        return
+      }
+      templates.removeLast()
+      completion(true, nil)
+    }
+  }
+
+  func push(_ template: Page, animated: Bool, completion: @escaping (Bool, Error?) -> Void) {
+    calls.append("push \(template.name)\(animated ? " animated" : "")")
+    pending.append { [self] in
+      guard !failingPushes.contains(template.name) else {
+        completion(false, nil)
+        return
+      }
+      templates.append(template)
+      completion(true, nil)
+    }
+  }
+
+  func step() {
+    pending.removeFirst()()
+  }
+
+  func run() {
+    while !pending.isEmpty {
+      step()
+    }
+  }
+}
+
+@Suite("TopTemplateReplacer")
+@MainActor
+struct TopTemplateReplacerTests {
+  private let replacer = TopTemplateReplacer()
+  private let stack = FakeStack("tabs", "A", "B", "C", "D")
+
+  @Test func replacesTheTopPageAndKeepsTheRest() {
+    var result: Bool?
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true) { pushed, _ in result = pushed }
+    stack.run()
+
+    #expect(stack.names == ["tabs", "A", "B", "C", "E"])
+    #expect(stack.calls == ["pop", "push E animated"])
+    #expect(result == true)
+    #expect(!replacer.isReplacing)
+  }
+
+  @Test func thePushWaitsForThePopToComplete() {
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true)
+    #expect(stack.calls == ["pop"])
+    stack.step()
+    #expect(stack.calls == ["pop", "push E animated"])
+  }
+
+  @Test func aMutationArrivingMidReplacementRunsOnceItHasSettled() {
+    var seen: [[String]] = []
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true)
+    stack.step()
+    replacer.whenSettled { seen.append(stack.names) }
+    #expect(seen.isEmpty)
+    stack.run()
+
+    #expect(seen == [["tabs", "A", "B", "C", "E"]])
+  }
+
+  @Test func deferredMutationsRunInArrivalOrderBehindASecondReplacement() {
+    var order: [String] = []
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true)
+    replacer.whenSettled { [replacer, stack] in
+      order.append("F")
+      replacer.push(Page("F"), replacingTopOf: stack, animated: true)
+    }
+    replacer.whenSettled { order.append("after F: \(stack.names.last ?? "")") }
+    stack.run()
+
+    #expect(stack.names == ["tabs", "A", "B", "C", "F"])
+    #expect(order == ["F", "after F: F"])
+  }
+
+  @Test func aMutationIssuedByTheCompletionQueuesBehindEarlierArrivals() {
+    var order: [String] = []
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true) { [replacer] _, _ in
+      replacer.whenSettled { order.append("from completion") }
+    }
+    replacer.whenSettled { order.append("arrived mid-replacement") }
+    stack.run()
+
+    #expect(order == ["arrived mid-replacement", "from completion"])
+  }
+
+  @Test func aFailedPopLeavesTheStackAsItWas() {
+    stack.failsPop = true
+    var result: Bool?
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true) { pushed, _ in result = pushed }
+    stack.run()
+
+    #expect(stack.names == ["tabs", "A", "B", "C", "D"])
+    #expect(stack.calls == ["pop"])
+    #expect(result == false)
+    #expect(!replacer.isReplacing)
+  }
+
+  @Test func aFailedPushRestoresThePoppedPage() {
+    stack.failingPushes = ["E"]
+    let top = stack.templates[4]
+    var result: Bool?
+    var ranAfter = false
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true) { pushed, _ in result = pushed }
+    replacer.whenSettled { ranAfter = true }
+    stack.run()
+
+    #expect(stack.names == ["tabs", "A", "B", "C", "D"])
+    #expect(stack.templates[4] === top)
+    #expect(stack.calls == ["pop", "push E animated", "push D"])
+    #expect(result == false)
+    #expect(ranAfter)
+  }
+
+  @Test func aFailedRestoreStillSettles() {
+    stack.failingPushes = ["E", "D"]
+    var result: Bool?
+    replacer.push(Page("E"), replacingTopOf: stack, animated: true) { pushed, _ in result = pushed }
+    stack.run()
+
+    #expect(stack.names == ["tabs", "A", "B", "C"])
+    #expect(result == false)
+    #expect(!replacer.isReplacing)
+  }
+
+  @Test func refusesAStackWithNothingAboveTheRoot() {
+    let rootOnly = FakeStack("tabs")
+    var result: Bool?
+    replacer.push(Page("E"), replacingTopOf: rootOnly, animated: true) { pushed, _ in result = pushed }
+
+    #expect(rootOnly.calls.isEmpty)
+    #expect(result == false)
+    #expect(!replacer.isReplacing)
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.22",
+  "version": "0.2.0-next.23",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",

package/website/guide/carplay.md

@@ -601,6 +601,36 @@ Return a browse path to enable the album line for that track, or `undefined` to
 CarPlay renders the tappable album/artist button as a **separate line built from the track's `album`** (visible as the third metadata line, with a chevron). Tracks without an `album` have no string for CarPlay to turn into a button — the artist line alone is never tappable. Set `album` on any track that should offer album-line navigation. See [Now Playing](/guide/now-playing) for the full field-by-surface rendering matrix.
 :::
 
+## Template Depth
+
+CarPlay limits an audio app's template stack to **five templates, the tab bar included** (CarPlay App Programming Guide, p. 15), so the stack is full four pushes in. Now Playing and Up Next each take a slot like any list. A browse tree with a fixed shape (tabs → show → episodes) never gets there; one that can be drilled without end — a place, a place near it, a place near that — does.
+
+At the limit, the library replaces the **top** page with the new one, so a push always lands:
+
+```
+[tabs, A, B, C, D]  + push E
+[tabs, A, B, C, E]
+```
+
+- **Forward never blocks.** A deeper list, Now Playing and Up Next all open at full depth.
+- **Back skips one page.** From `E` it goes to `C`: `D`, the page the listener came from, is the one that was replaced. Below full depth, back works as usual.
+- **The swap is a pop and a push.** CarPlay can't replace a template in place, so the library pops the top one without animation and then pushes the new one.
+
+Each replacement is logged under the `com.audiobrowser` subsystem, category `TemplateStack`:
+
+```
+push at the depth limit: replacing the top, CPListTemplate, with CPListTemplate
+```
+
+To watch for it on the simulator:
+
+```sh
+xcrun simctl spawn booted log stream --level info \
+  --predicate 'subsystem == "com.audiobrowser" AND category == "TemplateStack"'
+```
+
+An `error` line in that category means the pop or the push failed; it names the template involved.
+
 ## Testing
 
 Test your app in the `CarPlay Simulator.app`, which is part of the [Additional Tools for Xcode](https://developer.apple.com/download/all/?q=additional%20tools%20for%20xcode). Siri voice search works there, so you can exercise the full intent flow without a car. CarPlay support on the iOS Simulator can be a little flaky — if something looks broken, retry or fall back to a physical device for final verification.