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

package/ios/CarPlay/CarPlayListItemFactory.swift

@@ -154,6 +154,17 @@ final class CarPlayListItemFactory {
       item.accessoryType = .disclosureIndicator
     }
 
+    // A resolved accessorySymbol replaces the derived accessory above
+    // (accessoryImage outranks accessoryType in the SDK). 'none' — the
+    // inheritance escape — keeps the derived behavior instead.
+    if let symbol = SectionPresentation.effectiveAccessorySymbol(style ?? track.style),
+       let accessory = UIImage(systemName: symbol)
+    {
+      // `accessoryImage` is readonly on CPListItem; post-init updates go
+      // through the setter (which also clears `accessoryType`, per the SDK).
+      item.setAccessoryImage(accessory)
+    }
+
     // An unavailable track grays out and goes inert — list rows are the
     // surface that CAN draw the fact, so it shows rather than hides
     // (Track.disabled's rendering ladder).
@@ -202,6 +213,18 @@ 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 {
+      return cardImage == .background
+        ? CPListImageRowItemCardElement.maximumFullHeightImageSize
+        : CPListImageRowItemCardElement.maximumImageSize
+    }
+    return rowImageSize
+  }
+
   /// Creates the image-row item rendering a tile-presented section: a single
   /// truncating line (`.singleLineRow`) or a wrapping multi-line grid
   /// (`.wrappingGrid` — constructed on iOS 26+ only, by `SectionPresentation`).
@@ -237,42 +260,90 @@ final class CarPlayListItemFactory {
     // doesn't exist before iOS 26). nil = the legacy gridImages path.
     // @MainActor makes the closure Sendable for the artwork completion hop.
     var applyImage: (@MainActor (Int, UIImage) -> Void)?
+    // Resolved once per track, shared by element construction and the
+    // artwork loads below.
+    let resolvedStyles = tracks.map { StyleResolver.trackStyle(track: $0.style, section: style) }
     if #available(iOS 26.0, *) {
-      if singleLine {
-        // Row elements are the only tile element with a subtitle slot — the
-        // imageGridElements branch below has no equivalent, by SDK design.
-        let rowElements = tracks.map { track in
-          let element = CPListImageRowItemRowElement(
-            image: placeholder(), title: track.title, subtitle: track.subtitle,
-          )
+      // Builds a family's elements with the shared per-element tail: the
+      // disabled fact (isEnabled lives on the element base class) applied
+      // once, not per family.
+      func makeElements<Element: CPListImageRowItemElement>(
+        _ make: (Track, TrackStyle) -> Element,
+      ) -> [Element] {
+        zip(tracks, resolvedStyles).map { track, resolved in
+          let element = make(track, resolved)
           if track.disabled == true {
             element.isEnabled = false
           }
           return element
         }
-        item = CPListImageRowItem(text: section.title, elements: rowElements, allowsMultipleLines: false)
-        applyImage = { index, image in
-          guard index < rowElements.count else { return }
-          rowElements[index].image = image
+      }
+      // The image setter every element family shares (`image` is on the base
+      // class); bounds-checked against the elements the row was built with.
+      func imageApplier(_ elements: [some CPListImageRowItemElement]) -> @MainActor (Int, UIImage) -> Void {
+        { index, image in
+          guard index < elements.count else { return }
+          elements[index].image = image
         }
-      } else {
+      }
+      // 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) {
+      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).
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCardElement(
+            image: placeholder(),
+            showsImageFullHeight: resolved.cardImage == .background,
+            title: track.title,
+            subtitle: track.subtitle,
+            tintColor: resolved.cardTint.flatMap { UIColor(declaredHex: $0) },
+          )
+        }
+        item = CPListImageRowItem(
+          text: section.title, cardElements: elements, allowsMultipleLines: !singleLine,
+        )
+        applyImage = imageApplier(elements)
+      case .condensedElements:
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemCondensedElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            subtitle: track.subtitle,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
+          )
+        }
+        item = CPListImageRowItem(
+          text: section.title, 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).
-        let gridElements = tracks.map { track in
-          let element = CPListImageRowItemImageGridElement(
-            image: placeholder(), imageShape: .roundedRectangle, title: track.title,
-            accessorySymbolName: nil,
+        let elements = makeElements { track, resolved in
+          CPListImageRowItemImageGridElement(
+            image: placeholder(),
+            imageShape: resolved.imageShape == .circular ? .circular : .roundedRectangle,
+            title: track.title,
+            accessorySymbolName: SectionPresentation.effectiveAccessorySymbol(resolved),
           )
-          if track.disabled == true {
-            element.isEnabled = false
-          }
-          return element
-        }
-        item = CPListImageRowItem(text: section.title, imageGridElements: gridElements, allowsMultipleLines: true)
-        applyImage = { index, image in
-          guard index < gridElements.count else { return }
-          gridElements[index].image = image
         }
+        item = CPListImageRowItem(text: section.title, imageGridElements: elements, allowsMultipleLines: true)
+        applyImage = imageApplier(elements)
       }
     } else {
       let placeholders = tracks.map { _ in placeholder() }
@@ -310,10 +381,11 @@ final class CarPlayListItemFactory {
     for (index, track) in tracks.enumerated() {
       guard track.artwork != nil || track.artworkSource != nil else { continue }
 
+      let resolved = resolvedStyles[index]
       imageLoader?.loadArtwork(
         for: track,
-        style: StyleResolver.trackStyle(track: track.style, section: style),
-        size: Self.rowImageSize,
+        style: resolved,
+        size: Self.tileImageSize(gridTile: style.gridTile, cardImage: resolved.cardImage),
       ) { [weak item] image in
         Task { @MainActor in
           guard let item, let image else { return }

package/ios/Extension/UIApplication+ActiveScene.swift

@@ -0,0 +1,27 @@
+import UIKit
+
+extension UIApplication {
+  /// The scene showing the app's own UI: the foreground-active one, else any
+  /// connected window scene. Nil when the app has no UI scene at all (running
+  /// headless for CarPlay), which callers must handle rather than assume.
+  ///
+  /// Replaces the deprecated `UIScreen.main` / `keyWindow` idioms — and exists
+  /// once because the walk was previously written out at each use, so the two
+  /// copies had already drifted apart.
+  var activeWindowScene: UIWindowScene? {
+    let scenes = connectedScenes.compactMap { $0 as? UIWindowScene }
+    return scenes.first { $0.activationState == .foregroundActive } ?? scenes.first
+  }
+}
+
+/// The scale to rasterise at for the app's own screen.
+///
+/// `UITraitCollection.current` rather than the deprecated `UIScreen.main.scale`
+/// (also unavailable on visionOS, which the podspec targets): on the main actor
+/// it already reflects the environment being rendered for. CarPlay surfaces do
+/// NOT use this — they rasterise at `carTraitCollection.displayScale`, the car
+/// screen's own scale.
+@MainActor
+var appDisplayScale: CGFloat {
+  UITraitCollection.current.displayScale
+}

package/ios/Http/HttpClient.swift

@@ -92,8 +92,14 @@ final class HttpClient: @unchecked Sendable {
     httpRequest.headers?.forEach { name, value in
       urlRequest.setValue(value, forHTTPHeaderField: name)
     }
-    // Set User-Agent (userAgent parameter takes precedence over headers)
-    urlRequest.setValue(httpRequest.userAgent, forHTTPHeaderField: "User-Agent")
+    // An explicit `User-Agent` in `headers` wins, matching the two sibling paths
+    // (MediaLoader.buildAssetOptions and the artwork path in
+    // BrowserManager+URLResolution). `userAgent` carries a non-nil default, so
+    // overwriting unconditionally would replace a consumer's header with
+    // "react-native-audio-browser" whenever they set only the header.
+    if httpRequest.headers?["User-Agent"] == nil {
+      urlRequest.setValue(httpRequest.userAgent, forHTTPHeaderField: "User-Agent")
+    }
 
     // Add body for non-GET requests
     switch httpRequest.method.uppercased() {

package/ios/HybridAudioBrowser.swift

@@ -384,6 +384,19 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   deinit {
+    // Block-based notification observers are retained by the center until an
+    // explicit removeObserver — observer death isn't detected — so without this
+    // every JS reload strands another token + closure. They capture `self`
+    // weakly, so a stranded one no-ops rather than misbehaving; what accumulates
+    // is the tokens and a wasted main-queue dispatch per interruption / route
+    // change / media-services reset. (`volumeObservation` needs no counterpart:
+    // NSKeyValueObservation invalidates itself when this instance releases it.)
+    for observer in [interruptionObserver, routeChangeObserver, mediaServicesResetObserver]
+      .compactMap(\.self)
+    {
+      NotificationCenter.default.removeObserver(observer)
+    }
+
     // Safety net: ensure the AVPlayer is stopped if this instance is deallocated.
     let player = self.player
     if Thread.isMainThread {
@@ -574,7 +587,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   static let invalidateAllSentinel = "__rnab_invalidate_all__"
 
   public func notifyContentChanged(path: String) throws {
-    onMainActor { browserManager.invalidateContentCache(path) }
+    // Throws on a contextual path (matching Android's `require`) — the caller
+    // must pass the container path, or the invalidation silently hits nothing.
+    try onMainActor { try browserManager.invalidateContentCache(path) }
 
     // Notify external controllers (CarPlay) that content changed
     externalContentChangedEmitter.emit(path)
@@ -754,6 +769,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         guard let self else { return }
         self.applyAudioSessionCategory = applyCategory
 
+        // A re-setup REPLACES the player, so the outgoing one has to be torn down
+        // and un-published first. `TrackPlayer` has no deinit: dropping the
+        // reference alone would leave its AVPlayer and MPNowPlayingSession alive.
+        // And `playerAndConfiguredBrowser` holds the old player strongly — its
+        // `resolve` is a one-shot, so without the reset the gate would keep
+        // handing the dead player to the CarPlay controller and Siri intents,
+        // which both await it. No-op on first setup.
+        player?.destroy()
+        playerAndConfiguredBrowser.reset()
+
         // Create player with self as callbacks delegate
         player = TrackPlayer(callbacks: self)
 
@@ -853,6 +878,13 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
         if let intent = options.playWhenReady { pendingPlayWhenReady = intent }
         applyPendingPlayerState()
 
+        // Push the resolved event cadence unconditionally. `updateOptions` applies
+        // the interval only when it *differs* from the stored one, but the store
+        // outlives the player — so on a re-setup with unchanged options the new
+        // player would come up with no progress timer at all.
+        player?.setProgressUpdateInterval(playerOptions.progressUpdateEventInterval)
+        player?.setPlaybackIntervalEnabled(playbackIntervalEnabled)
+
         // Notify listeners that player is ready (e.g., CarPlay)
         playerAndConfiguredBrowser.check()
       }
@@ -917,8 +949,16 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     onMainActor { playerOptions.toOptions() }
   }
 
+  /// Stored so a re-setup can re-apply it: unlike the other runtime options this
+  /// one has no home in `playerOptions`, and the player it was pushed to does not
+  /// survive `setupPlayer`.
+  @MainActor private var playbackIntervalEnabled = false
+
   public func setPlaybackIntervalEnabled(enabled: Bool) {
-    onMainActor { player?.setPlaybackIntervalEnabled(enabled) }
+    onMainActor {
+      playbackIntervalEnabled = enabled
+      player?.setPlaybackIntervalEnabled(enabled)
+    }
   }
 
   // MARK: - Playback Control
@@ -1132,7 +1172,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   }
 
   public func setActiveTrackFavorited(favorited: Bool) throws {
-    onMainActor {
+    try onMainActor {
       guard let track = player?.currentTrack, let identity = track.identity else { return }
       guard let index = player?.currentIndex, index >= 0 else { return }
       // Optimistically reflect in the authoritative favorite set so the
@@ -1144,7 +1184,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
       // Hydration never overrides a caller-set `favorited`, so the queued
       // track must itself carry the latest explicit value (as Android's tag
       // swap and web's replaceTrack do).
-      player?.replace(index, updatedTrack)
+      try player?.replace(index, updatedTrack)
       // The ONLY emit: a favorite toggle is an in-place mutation of the active
       // track, not a transition — onPlaybackActiveTrackChanged stays
       // transition-only, and the useActiveTrack / useQueue hooks subscribe to
@@ -1303,7 +1343,7 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
     // Classify a stall by connectivity so the formatter can show "No internet connection" vs
     // "Reconnecting…" without a separate read. nil while not stalled.
     let stalled: StallReason? =
-      player.isStalled ? (networkMonitor.getOnline() ? .buffering : .offline) : nil
+      player.isStalled ? (networkMonitor.isOnline ? .buffering : .offline) : nil
     player.nowPlayingUpdater.render(
       track: track,
       timedMetadata: latestTimedMetadata,
@@ -1319,7 +1359,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   // MARK: - Network
 
   public func getOnline() throws -> Bool {
-    networkMonitor.getOnline()
+    // No `onMainActor` hop: `isOnline` is lock-protected, so this stays a
+    // cheap read on the JS thread instead of blocking on the main queue.
+    networkMonitor.isOnline
   }
 
   // MARK: - System Volume
@@ -1499,11 +1541,9 @@ public class HybridAudioBrowser: HybridAudioBrowserSpec, @unchecked Sendable {
   public func openOutputPicker() throws {
     DispatchQueue.main.async { [weak self] in
       guard let self else { return }
-      guard let windowScene = UIApplication.shared.connectedScenes
-        .compactMap({ $0 as? UIWindowScene })
-        .first(where: { $0.activationState == .foregroundActive }),
-        let window = windowScene.windows.first(where: { $0.isKeyWindow }),
-        var topController = window.rootViewController
+      guard let windowScene = UIApplication.shared.activeWindowScene,
+            let window = windowScene.windows.first(where: { $0.isKeyWindow }),
+            var topController = window.rootViewController
       else {
         self.logger.error("openOutputPicker: no active window scene / root view controller")
         return
@@ -1889,6 +1929,9 @@ extension HybridAudioBrowser: TrackPlayerCallbacks {
             return
           }
           browser.logger.info("resume: cold — restoring persisted track")
+          // Repeat / shuffle / speed come back before the queue is built — see
+          // `restorePlaybackSettings(from:)` for why that ordering matters.
+          player.restorePlaybackSettings(from: state)
           let startMs = (track.live == true) ? nil : state.positionMs
           // Match Android resume: re-expand the full queue from the track's contextual
           // path (parent container → siblings + selected index). Fall back to the single

package/ios/Model/NitroTypeStubs.swift

@@ -112,9 +112,64 @@
     }
   }
 
+  enum ImageShape: Equatable {
+    case circular
+    case roundedRectangle
+
+    init?(fromString string: String) {
+      switch string {
+      case "circular": self = .circular
+      case "rounded-rectangle": self = .roundedRectangle
+      default: return nil
+      }
+    }
+  }
+
+  enum GridTile: Equatable {
+    case plain
+    case card
+    case condensed
+
+    init?(fromString string: String) {
+      switch string {
+      case "plain": self = .plain
+      case "card": self = .card
+      case "condensed": self = .condensed
+      default: return nil
+      }
+    }
+
+    // Mirrors the generated extension (nitrogen emits `stringValue` beside
+    // `init?(fromString:)` for every string-backed enum).
+    var stringValue: String {
+      switch self {
+      case .plain: "plain"
+      case .card: "card"
+      case .condensed: "condensed"
+      }
+    }
+  }
+
+  enum CardImage: Equatable {
+    case normal
+    case background
+
+    init?(fromString string: String) {
+      switch string {
+      case "normal": self = .normal
+      case "background": self = .background
+      default: return nil
+      }
+    }
+  }
+
   struct TrackStyle: Equatable {
     var display: StyleDisplay?
     var artworkRendering: ArtworkRendering?
+    var imageShape: ImageShape?
+    var accessorySymbol: String?
+    var cardTint: String?
+    var cardImage: CardImage?
   }
 
   // Member order matches the generated init (own properties before inherited
@@ -123,8 +178,13 @@
   // `swift test` passes while the app build breaks on argument order.
   struct SectionStyle: Equatable {
     var gridWrap: Bool?
+    var gridTile: GridTile?
     var display: StyleDisplay?
     var artworkRendering: ArtworkRendering?
+    var imageShape: ImageShape?
+    var accessorySymbol: String?
+    var cardTint: String?
+    var cardImage: CardImage?
   }
 
   struct Section: Equatable {

package/ios/Player/MediaIntentCriteria.swift

@@ -126,14 +126,22 @@ public struct MediaIntentCriteria: Sendable {
 
   /// Whether `query` is effectively the host app's own name. Case- and
   /// diacritic-insensitive.
+  ///
+  /// Whole-word subset match in either direction. Siri may deliver only part of
+  /// the name ("Name" for «App Name»), so a partial match must count — but a
+  /// substring match swallowed any query appearing inside the app name, making
+  /// one-word stations unreachable by voice.
   private static func queryMatchesAppName(_ query: String, appName: String?) -> Bool {
     guard let appName else { return false }
-    let normalize: (String) -> String = {
-      $0.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)
-        .trimmingCharacters(in: .whitespacesAndNewlines)
+    let tokens: (String) -> Set<String> = {
+      Set(
+        $0.folding(options: [.diacriticInsensitive, .caseInsensitive], locale: nil)
+          .split(whereSeparator: { !$0.isLetter && !$0.isNumber })
+          .map(String.init),
+      )
     }
-    let q = normalize(query), a = normalize(appName)
+    let q = tokens(query), a = tokens(appName)
     guard !q.isEmpty, !a.isEmpty else { return false }
-    return a.contains(q) || q.contains(a)
+    return q.isSubset(of: a) || a.isSubset(of: q)
   }
 }

package/ios/Player/MediaLoader.swift

@@ -38,19 +38,28 @@ final class MediaLoader {
   func resolveAndLoad(src: String, track: Track? = nil) {
     if let resolver = mediaUrlResolver {
       mediaResolverTask?.cancel()
-      mediaResolverTask = Task {
-        self.logger.debug("resolveAndLoad: starting resolution for \(src)")
+      // `[weak self]` like the sibling load tasks below: the resolver is
+      // consumer-supplied and `cancelAll()` cannot force an in-flight `await`
+      // to return, so a strong capture let a resolver that never settles pin
+      // this loader (which also retains the task) indefinitely.
+      // `Logger` is a value type, so capturing it directly keeps the logging
+      // off `self` — and `self` weak, so a consumer resolver that never settles
+      // can't pin the loader (`cancelAll()` can't force an in-flight `await` to
+      // return).
+      let logger = logger
+      mediaResolverTask = Task { [weak self] in
+        logger.debug("resolveAndLoad: starting resolution for \(src)")
 
         guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled before start")
+          logger.debug("resolveAndLoad: cancelled before start")
           return
         }
 
-        self.logger.debug("resolveAndLoad: calling resolver...")
+        logger.debug("resolveAndLoad: calling resolver...")
         let resolved = await resolver(src, track)
 
-        guard !Task.isCancelled else {
-          self.logger.debug("resolveAndLoad: cancelled after resolver returned")
+        guard !Task.isCancelled, let self else {
+          logger.debug("resolveAndLoad: cancelled after resolver returned")
           return
         }
 
@@ -96,7 +105,7 @@ final class MediaLoader {
         .availableMetadataFormats,
       ) else { return }
 
-      guard !Task.isCancelled, pendingAsset == asset else { return }
+      guard isCurrent(pendingAsset) else { return }
 
       if !commonMetadata.isEmpty {
         delegate?.mediaLoaderDidReceiveCommonMetadata(commonMetadata)
@@ -104,19 +113,21 @@ final class MediaLoader {
 
       if !chapterLocales.isEmpty {
         for locale in chapterLocales {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let chapters = try? await pendingAsset.loadChapterMetadataGroups(
             withTitleLocale: locale,
             containingItemsWithCommonKeys: [],
           ) {
+            guard isCurrent(pendingAsset) else { return }
             delegate?.mediaLoaderDidReceiveChapterMetadata(chapters)
           }
         }
       } else {
         let duration = await (try? pendingAsset.load(.duration)) ?? .zero
         for format in metadataFormats {
-          guard !Task.isCancelled else { return }
+          guard isCurrent(pendingAsset) else { return }
           if let metadata = try? await pendingAsset.loadMetadata(for: format) {
+            guard isCurrent(pendingAsset) else { return }
             let timeRange = CMTimeRange(
               start: CMTime(seconds: 0, preferredTimescale: 1000),
               end: duration,
@@ -159,6 +170,19 @@ final class MediaLoader {
     }
   }
 
+  /// Whether `candidate` is still the load this loader cares about — checked
+  /// after EVERY await, not just once before a loop.
+  ///
+  /// Cancellation alone is not enough: it only sets a flag, and can't abort a
+  /// load already in flight inside AVFoundation (only `cancelLoading()` does,
+  /// and the track-change path deliberately doesn't call it — the old asset
+  /// still backs the playing item at that point). So a load that lands after
+  /// the track changed would otherwise attribute the old asset's metadata to
+  /// the newly loaded track.
+  private func isCurrent(_ candidate: AVURLAsset) -> Bool {
+    !Task.isCancelled && candidate == asset
+  }
+
   func cancelAll() {
     mediaResolverTask?.cancel()
     mediaResolverTask = nil

package/ios/Player/NowPlayingUpdater.swift

@@ -30,17 +30,51 @@ final class NowPlayingUpdater {
     let album: String?
   }
 
+  /// Dedupe baseline for `applyFields`. Only meaningful while it describes the
+  /// controller's current info dict, so the two are cleared together in
+  /// `clearNowPlaying()` — never separately.
   private var lastPublished: Published?
 
+  /// Empties the now-playing surface and the dedupe baseline that describes it.
+  /// One call, because clearing the dict without the baseline makes the next
+  /// publish of the SAME track dedupe against a dict that no longer holds it —
+  /// artwork lands (never deduped) but the text doesn't, and `onChanged`
+  /// never fires.
+  func clearNowPlaying() {
+    nowPlayingInfoController.clear()
+    lastPublished = nil
+    formattedTrackId = nil
+  }
+
   /// Bumped on every `render`; an async formatter result applies only if its render is still the
   /// latest (latest-render-wins — drops a result whose track skipped or whose state moved on while
   /// the formatter was in flight).
   private var renderGeneration: UInt = 0
 
+  /// The track whose *formatted* line is currently on the surface. While this
+  /// matches the rendering track, `render` skips its interim default write — see
+  /// the comment at that site. Cleared whenever the surface stops showing a
+  /// formatter result (a flash overwrites it, `clearNowPlaying` empties it).
+  private var formattedTrackId: String?
+
   init(nowPlayingInfoController: NowPlayingInfoController) {
     self.nowPlayingInfoController = nowPlayingInfoController
   }
 
+  /// Pixel width to request now-playing artwork at: the active scene's screen
+  /// width in pixels, capped at `maxArtworkPixelWidth`. With no foreground
+  /// scene (headless CarPlay) the cap stands in — every current device exceeds
+  /// it anyway, and this only sizes a CDN request.
+  private static var artworkPixelWidth: CGFloat {
+    guard let screen = UIApplication.shared.activeWindowScene?.screen else {
+      return maxArtworkPixelWidth
+    }
+    return min(screen.bounds.width * screen.scale, maxArtworkPixelWidth)
+  }
+
+  /// Mirrored by the Kotlin twin's `artworkSizePx`.
+  private static let maxArtworkPixelWidth: CGFloat = 1200
+
   /// Publishes the static, per-track fields + artwork on a track change. The title/artist/album
   /// lines are owned by `render` (routed through `applyFields` here so it dedupes against later
   /// renders).
@@ -75,6 +109,8 @@ final class NowPlayingUpdater {
     let defaultSecondary = override?.artist ?? track.artist
     let defaultAlbum = override?.album ?? track.album
 
+    let trackId = track.identity ?? track.path
+
     if let flash {
       applyFields(
         track: track,
@@ -82,10 +118,22 @@ final class NowPlayingUpdater {
         artist: flash.artist ?? defaultSecondary,
         album: flash.album ?? defaultAlbum,
       )
+      // The flash replaced the formatter's line, so the surface no longer shows
+      // one: the render that follows the flash reverting must publish the default
+      // immediately rather than sit on stale flash text awaiting the formatter.
+      formattedTrackId = nil
       return
     }
 
-    applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    // Publish the raw default only while no formatter result is on screen for this
+    // track. `render` runs on EVERY playback transition (state change, playing/
+    // buffering flip, timed-metadata tick, connectivity change); writing the
+    // default each time would flash the track title over the formatter's line
+    // until the async result lands, since the two differ by construction on a live
+    // stream (station name vs. song line).
+    if formatter == nil || formattedTrackId != trackId {
+      applyFields(track: track, title: defaultTitle, artist: defaultSecondary, album: defaultAlbum)
+    }
 
     guard let formatter else { return }
     let params = FormatNowPlayingParams(
@@ -111,6 +159,9 @@ final class NowPlayingUpdater {
             artist: formatted.artist ?? defaultSecondary,
             album: formatted.album ?? defaultAlbum,
           )
+          // A formatter result now owns the surface for this track, so later
+          // renders skip the interim default write.
+          self.formattedTrackId = trackId
         }
       }
       .catch { @Sendable [weak self] error in
@@ -152,10 +203,7 @@ final class NowPlayingUpdater {
     let artworkUrl = track.artworkSource?.uri ?? track.artwork?.url
     logger.debug("loadArtwork: \(track.title), artworkUrl: \(artworkUrl ?? "nil")")
 
-    // Now Playing artwork: use screen width in pixels, capped at 1200px
-    let screenScale = UIScreen.main.scale
-    let screenWidth = UIScreen.main.bounds.width * screenScale
-    let artworkSize = min(screenWidth, 1200)
+    let artworkSize = Self.artworkPixelWidth
     let nowPlayingSize = ImageContext(width: artworkSize, height: artworkSize)
 
     artworkLoadTask?.cancel()