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

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -46,22 +46,29 @@ final class CarPlayListItemFactory {
 
   // MARK: - Sections
 
-  /// Whether this OS has CarPlay's wrapping tile container (the iOS 26
-  /// element API) — the capability `SectionPresentation` degrades against.
-  private static var supportsWrappingGrid: Bool {
+  /// Whether this OS has CarPlay's iOS 26 element API — the wrapping tile
+  /// container and the text-less image row `SectionPresentation` degrades
+  /// against.
+  private static var supportsElements: Bool {
     if #available(iOS 26.0, *) { return true }
     return false
   }
 
+  private static func listSection(_ items: [CPListTemplateItem], header: String?) -> CPListSection {
+    if let header {
+      return CPListSection(items: items, header: header, sectionIndexTitle: nil)
+    }
+    return CPListSection(items: items)
+  }
+
   /// Maps the page's sections 1:1 to CPListSections (ADR 0010), respecting
   /// CarPlay's section and total-item budgets. Style blocks declare the
   /// requested presentation (resolved `section ?? page` here — ADR 0011);
   /// this renders CarPlay's nearest supported form (`SectionPresentation`):
   /// - list (default): a titled/headerless section of list rows.
-  /// - single-line grid (`gridWrap: false`): a headerless section holding
-  ///   one single-line image-row item whose text is the section title — the
-  ///   tiles that fit render, the rest truncate (the platform doesn't
-  ///   report the fit).
+  /// - single-line grid (`gridWrap: false`): a section holding one
+  ///   single-line image-row item — the tiles that fit render, the rest
+  ///   truncate (the platform doesn't report the fit).
   /// - wrapping grid: a wrapping, titled tile grid on iOS 26+; a plain list
   ///   before that.
   func createSections(from resolvedTrack: ResolvedTrack) -> [CPListSection] {
@@ -84,26 +91,24 @@ final class CarPlayListItemFactory {
       guard !section.children.isEmpty else { continue }
 
       let style = StyleResolver.sectionStyle(section: section.style, page: resolvedTrack.style)
-      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsWrappingGrid)
+      let presentation = SectionPresentation(for: style, supportsWrappingGrid: Self.supportsElements)
       switch presentation {
       case .list:
         let availableSlots = maxTotalItems - totalItemCount
         let items: [CPListTemplateItem] = section.children.prefix(availableSlots).map {
           createListItem(for: $0, style: StyleResolver.trackStyle(track: $0.style, section: style))
         }
-        if let title = section.title {
-          listSections.append(CPListSection(items: items, header: title, sectionIndexTitle: nil))
-        } else {
-          listSections.append(CPListSection(items: items))
-        }
+        listSections.append(Self.listSection(items, header: section.title))
         totalItemCount += items.count
       case .singleLineRow, .wrappingGrid:
-        // Tile presentations render as one image-row item inside a
-        // headerless CPListSection, with the section title as the item's
-        // text — a headed section would render the title twice.
-        guard let item = createImageRowItem(for: section, style: style, presentation: presentation)
-        else { continue }
-        listSections.append(CPListSection(items: [item]))
+        // Tile presentations render as one image-row item in its own
+        // CPListSection. The title is drawn once: as the section's header
+        // (`SectionPresentation.tileSectionHeader`), or as the item's text.
+        let header = SectionPresentation.tileSectionHeader(section, supportsElements: Self.supportsElements)
+        guard let item = createImageRowItem(
+          for: section, text: header == nil ? section.title : nil, style: style, presentation: presentation,
+        ) else { continue }
+        listSections.append(Self.listSection([item], header: header))
         totalItemCount += 1
       }
     }
@@ -213,16 +218,25 @@ final class CarPlayListItemFactory {
     return CPListImageRowItem.maximumImageSize
   }
 
-  /// Target artwork size for one tile. Cards read their own class maximums
-  /// ('background' selects the larger full-height target); every other
-  /// family uses the shared element size.
-  private static func tileImageSize(gridTile: GridTile?, cardImage: CardImage?) -> CGSize {
-    if #available(iOS 26.0, *), gridTile == .card {
+  /// Target artwork size for one tile. Cards, image tiles and plain row
+  /// elements read their own class maximums ('background' selects the larger
+  /// full-height card target); condensed tiles use the shared element size.
+  private static func tileImageSize(
+    family: SectionPresentation.TileElementFamily, cardImage: CardImage?,
+  ) -> CGSize {
+    guard #available(iOS 26.0, *) else { return CPListImageRowItem.maximumImageSize }
+    switch family {
+    case .cardElements:
       return cardImage == .background
         ? CPListImageRowItemCardElement.maximumFullHeightImageSize
         : CPListImageRowItemCardElement.maximumImageSize
+    case .rowElements:
+      return CPListImageRowItemRowElement.maximumImageSize
+    case .imageGridElements:
+      return CPListImageRowItemImageGridElement.maximumImageSize
+    case .condensedElements:
+      return CPListImageRowItemElement.maximumImageSize
     }
-    return rowImageSize
   }
 
   /// Creates the image-row item rendering a tile-presented section: a single
@@ -231,10 +245,14 @@ final class CarPlayListItemFactory {
   ///
   /// Returns nil when nothing is drawable — every child hidden by the
   /// disabled ladder (pre-26 only; the element APIs gray instead).
+  ///
+  /// - Parameter text: the row's own title; nil when the list section's
+  ///   header carries it.
   private func createImageRowItem(
-    for section: Section, style: SectionStyle, presentation: SectionPresentation,
+    for section: Section, text rowText: String?, style: SectionStyle, presentation: SectionPresentation,
   ) -> CPListImageRowItem? {
     let singleLine = presentation == .singleLineRow
+    let family = SectionPresentation.tileFamily(for: style)
     // Disabled ladder: iOS 26 elements can draw unavailability (grayed +
     // inert, below); the legacy image row can't, so there a disabled track
     // hides — never a normal-looking dead tile.
@@ -286,14 +304,14 @@ final class CarPlayListItemFactory {
           elements[index].image = image
         }
       }
-      // The family is style-driven (`SectionPresentation.tileFamily`); both
-      // non-plain families take either wrap mode. Pre-26 the treatment drops
-      // and the layout survives (the legacy branch below).
-      switch SectionPresentation.tileFamily(for: style, singleLine: singleLine) {
+      // The family is style-driven (`SectionPresentation.tileFamily`); every
+      // family takes either wrap mode. Pre-26 the treatment drops and the
+      // layout survives (the legacy branch below).
+      switch family {
       case .cardElements:
         // Cards have no shape and no accessory slot; their knobs are the
         // tint and the image mode ('background' fills the card full-height
-        // and turns the tint into the color behind the labels).
+        // and fades the tint in behind the labels).
         let elements = makeElements { track, resolved in
           CPListImageRowItemCardElement(
             image: placeholder(),
@@ -304,7 +322,7 @@ final class CarPlayListItemFactory {
           )
         }
         item = CPListImageRowItem(
-          text: section.title, cardElements: elements, allowsMultipleLines: !singleLine,
+          text: rowText, cardElements: elements, allowsMultipleLines: !singleLine,
         )
         applyImage = imageApplier(elements)
       case .condensedElements:
@@ -318,19 +336,9 @@ final class CarPlayListItemFactory {
           )
         }
         item = CPListImageRowItem(
-          text: section.title, condensedElements: elements, allowsMultipleLines: !singleLine,
+          text: rowText, condensedElements: elements, allowsMultipleLines: !singleLine,
         )
         applyImage = imageApplier(elements)
-      case .rowElements:
-        // The only plain tile with a subtitle slot — the imageGridElements
-        // family has no equivalent, by SDK design.
-        let elements = makeElements { track, _ in
-          CPListImageRowItemRowElement(
-            image: placeholder(), title: track.title, subtitle: track.subtitle,
-          )
-        }
-        item = CPListImageRowItem(text: section.title, elements: elements, allowsMultipleLines: false)
-        applyImage = imageApplier(elements)
       case .imageGridElements:
         // imageGridElements, never the title-less gridElements: an
         // artwork-less track must keep its name on screen (ADR 0010).
@@ -342,28 +350,40 @@ final class CarPlayListItemFactory {
             accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
           )
         }
-        item = CPListImageRowItem(text: section.title, imageGridElements: elements, allowsMultipleLines: true)
+        item = CPListImageRowItem(
+          text: rowText, imageGridElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .rowElements:
+        // Titled, so an artwork-less track keeps its name on screen
+        // (ADR 0010); no shape and no accessory slot.
+        let elements = makeElements { track, _ in
+          CPListImageRowItemRowElement(
+            image: placeholder(), title: track.title, subtitle: track.subtitle,
+          )
+        }
+        item = CPListImageRowItem(
+          text: rowText, elements: elements, allowsMultipleLines: !singleLine,
+        )
         applyImage = imageApplier(elements)
       }
     } else {
       let placeholders = tracks.map { _ in placeholder() }
       // Use imageTitles variant on iOS 17.4+ to show titles below each thumbnail
       if #available(iOS 17.4, *) {
-        item = CPListImageRowItem(text: section.title ?? "", images: placeholders, imageTitles: tracks.map(\.title))
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders, imageTitles: tracks.map(\.title))
       } else {
-        item = CPListImageRowItem(text: section.title ?? "", images: placeholders)
+        item = CPListImageRowItem(text: rowText ?? "", images: placeholders)
       }
     }
 
     // Header tap → navigate to section.path ("view all"). A path-less
-    // section is a pure preview — its header tap is a no-op rather than a
-    // selection that can't resolve.
-    item.handler = { [onItemSelected] _, completion in
-      guard let path = section.path else {
-        completion()
-        return
+    // section is a pure preview and gets no handler.
+    if let path = section.path {
+      let target = Self.navigationTrack(path: path, title: section.title)
+      item.handler = { [onItemSelected] _, completion in
+        onItemSelected(target, completion)
       }
-      onItemSelected(Self.navigationTrack(path: path, title: section.title), completion)
     }
 
     // Per-tile taps select the child track directly. A disabled tile is
@@ -385,7 +405,7 @@ final class CarPlayListItemFactory {
       imageLoader?.loadArtwork(
         for: track,
         style: resolved,
-        size: Self.tileImageSize(gridTile: style.gridTile, cardImage: resolved.cardImage),
+        size: Self.tileImageSize(family: family, cardImage: resolved.cardImage),
       ) { [weak item, applyImage] image in
         Task { @MainActor in
           guard let item, let image else { return }

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/Model/NitroTypeStubs.swift

@@ -128,12 +128,14 @@
 
   enum GridTile: Equatable {
     case plain
+    case image
     case card
     case condensed
 
     init?(fromString string: String) {
       switch string {
       case "plain": self = .plain
+      case "image": self = .image
       case "card": self = .card
       case "condensed": self = .condensed
       default: return nil
@@ -145,6 +147,7 @@
     var stringValue: String {
       switch self {
       case .plain: "plain"
+      case .image: "image"
       case .card: "card"
       case .condensed: "condensed"
       }

package/ios/Tests/InertStyleDiagnosticTests.swift

@@ -74,22 +74,31 @@ struct InertStyleDiagnosticTests {
 
   @Test func imageShapeNeedsAShapedTile() {
     let list = SectionStyle(imageShape: .circular)
+    let plain = SectionStyle(display: .grid, imageShape: .circular)
     let cards = SectionStyle(gridTile: .card, display: .grid, imageShape: .circular)
     let condensed = SectionStyle(gridTile: .condensed, display: .grid, imageShape: .circular)
+    let image = SectionStyle(gridTile: .image, display: .grid, imageShape: .circular)
     #expect(findings([Section(style: list, children: [])]).count == 1)
+    #expect(findings([Section(style: plain, children: [])]).count == 1)
     #expect(findings([Section(style: cards, children: [])]).count == 1)
-    // Plain and condensed tiles both take a shape.
     #expect(findings([Section(style: condensed, children: [])]).isEmpty)
+    #expect(findings([Section(style: image, children: [])]).isEmpty)
   }
 
-  @Test func accessorySymbolIsInertOnlyOnCards() {
+  @Test func accessorySymbolNeedsAnAccessorySlot() {
     let rows = SectionStyle(accessorySymbol: "lock.fill")
+    let condensed = SectionStyle(gridTile: .condensed, display: .grid, accessorySymbol: "lock.fill")
+    let image = SectionStyle(gridTile: .image, display: .grid, accessorySymbol: "lock.fill")
+    let plain = SectionStyle(display: .grid, accessorySymbol: "lock.fill")
     let cards = SectionStyle(gridTile: .card, display: .grid, accessorySymbol: "lock.fill")
-    // List rows draw accessories; card elements have no slot for one.
     #expect(findings([Section(style: rows, children: [])]).isEmpty)
-    let found = findings([Section(style: cards, children: [])])
-    #expect(found.count == 1)
-    #expect(found[0].contains("no accessory slot"))
+    #expect(findings([Section(style: condensed, children: [])]).isEmpty)
+    #expect(findings([Section(style: image, children: [])]).isEmpty)
+    for style in [plain, cards] {
+      let found = findings([Section(style: style, children: [])])
+      #expect(found.count == 1)
+      #expect(found[0].contains("accessory slot"))
+    }
   }
 
   @Test func artworkRenderingIsNeverInert() {
@@ -114,9 +123,9 @@ struct InertStyleDiagnosticTests {
     #expect(found[0].contains("style.cardTint"))
   }
 
-  @Test func aTracksOwnShapeIsLiveInAPlainGrid() {
+  @Test func aTracksOwnShapeIsLiveInAShapedGrid() {
     let section = Section(
-      style: SectionStyle(display: .grid),
+      style: SectionStyle(gridTile: .image, display: .grid),
       children: [playable(style: TrackStyle(imageShape: .circular))],
     )
     #expect(findings([section]).isEmpty)

package/ios/Tests/JsonModelsTests.swift

@@ -162,6 +162,20 @@ struct JsonStyleTests {
     #expect(style?.cardImage == .background)
   }
 
+  @Test func decodesTheImageFamily() throws {
+    let json = Data(
+      """
+      {"path":"/home","title":"Home","sections":[
+        {"style":{"display":"grid","gridTile":"image","imageShape":"circular"},
+         "children":[{"title":"C","src":"s"}]}
+      ]}
+      """.utf8)
+    let resolved = try JSONDecoder().decode(JsonResolvedTrack.self, from: json).toNitro()
+    let style = resolved.sections?.first?.style
+    #expect(style?.gridTile == .image)
+    #expect(style?.imageShape == .circular)
+  }
+
   @Test func unknownGridTileDecodesAsNoDeclaration() throws {
     let json = Data(
       """

package/ios/Tests/SectionPresentationTests.swift

@@ -59,21 +59,29 @@ struct SectionPresentationTests {
         == .list)
   }
 
-  @Test func tileFamilyFollowsGridTileWithThePlainSplit() {
-    // Card/condensed follow the declaration in either wrap mode; the plain
-    // default splits on the wrap: single-line keeps row elements (the
-    // subtitle slot), wrapping renders the image grid.
+  @Test func tileFamilyFollowsGridTile() {
+    // The family follows the declaration alone; the wrap mode only decides
+    // whether its elements take more than one line.
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card)) == .cardElements)
     #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card), singleLine: true)
-        == .cardElements)
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .image)) == .imageGridElements)
     #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed), singleLine: false)
-        == .condensedElements)
-    #expect(SectionPresentation.tileFamily(for: nil, singleLine: true) == .rowElements)
-    #expect(SectionPresentation.tileFamily(for: nil, singleLine: false) == .imageGridElements)
-    #expect(
-      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain), singleLine: true)
-        == .rowElements)
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .condensed)) == .condensedElements)
+    #expect(SectionPresentation.tileFamily(for: nil) == .rowElements)
+    #expect(SectionPresentation.tileFamily(for: SectionStyle(gridTile: .plain)) == .rowElements)
+  }
+
+  @Test func aPathlessShelfTitlesTheSectionHeader() {
+    let viewAll = Section(title: "Popular", path: "/popular", children: [])
+    let preview = Section(title: "Popular", children: [])
+    let untitled = Section(children: [])
+    // The image row's own text carries a chevron, so it is kept for the
+    // shelf that has somewhere to go.
+    #expect(SectionPresentation.tileSectionHeader(viewAll, supportsElements: true) == nil)
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: true) == "Popular")
+    #expect(SectionPresentation.tileSectionHeader(untitled, supportsElements: true) == nil)
+    // The legacy row cannot drop its text.
+    #expect(SectionPresentation.tileSectionHeader(preview, supportsElements: false) == nil)
   }
 
   @Test func effectiveAccessorySymbol_noneAndAbsenceDrawNothing() {

package/ios/Tests/StyleResolverTests.swift

@@ -48,6 +48,11 @@ struct SectionStyleResolutionTests {
       page: SectionStyle(gridTile: .card),
     )
     #expect(overridden.gridTile == .plain)
+    let image = StyleResolver.sectionStyle(
+      section: SectionStyle(gridTile: .image),
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(image.gridTile == .image)
   }
 }
 

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)
+  }
+}