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

package/ios/Tests/QueueManagerTests.swift

@@ -120,6 +120,41 @@ struct NextTests {
     #expect(q.shuffleOrder.shuffled == order)
   }
 
+  /// A queue reorder permutes positions, not identities, so it must leave the
+  /// shuffled playback order alone. Re-inserting at a random shuffle position
+  /// would silently reshuffle under the listener.
+  @Test func shuffle_moveKeepsThePlaybackOrder() {
+    for target in 0 ..< 5 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e"))
+      q.shuffleEnabled = true
+      let before = q.shuffleOrder.shuffled.map { q.tracks[$0].id }
+
+      _ = try? q.move(fromIndex: 0, toIndex: target)
+
+      #expect(q.shuffleOrder.shuffled.map { q.tracks[$0].id } == before)
+    }
+  }
+
+  /// The same hazard as `shuffle_startTrackLeadsTheOrder`, reached by moving the
+  /// *playing* track: a random re-insert can drop it last in the shuffle order,
+  /// which reads as `isLastInPlaybackOrder` and ends the queue at the next track
+  /// boundary with tracks still unplayed.
+  @Test func shuffle_movingCurrentTrackDoesNotEndTheQueue() {
+    for target in 1 ..< 6 {
+      let q = QueueManager()
+      q.setQueue(tracks("a", "b", "c", "d", "e", "f"), initialIndex: 0)
+      q.shuffleEnabled = true // pins "a" first in the order
+      #expect(!q.isLastInPlaybackOrder)
+
+      _ = try? q.move(fromIndex: 0, toIndex: target)
+
+      #expect(q.currentTrack?.id == "a")
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+    }
+  }
+
   @Test func shuffle_visitsAllTracks() {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c", "d"))
@@ -382,6 +417,25 @@ struct AddTests {
     #expect(q.tracks[2].id == "c")
     #expect(q.tracks[3].id == "d")
   }
+
+  /// Filling an empty queue must pin the start track to the head of the shuffle
+  /// order, exactly as `setQueue` does — `insert(at:count:)` places new indices
+  /// at random positions, so without the pin the start track can land last and
+  /// the queue reports end-of-queue as soon as it finishes. `shuffleEnabled`'s
+  /// didSet only re-pins on the off→on edge, so shuffle-already-on gets nothing
+  /// from it.
+  @Test func toEmptyQueue_withShuffleAlreadyOn_startTrackLeadsTheOrder() {
+    for start in 0 ..< 6 {
+      let q = QueueManager()
+      q.shuffleEnabled = true
+      q.add(tracks("a", "b", "c", "d", "e", "f"), initialIndex: start)
+
+      #expect(q.shuffleOrder.isFirst(start))
+      #expect(!q.isLastInPlaybackOrder)
+      #expect(q.nextTracks.count == 5)
+      #expect(q.previousTracks.isEmpty)
+    }
+  }
 }
 
 // MARK: - Mutations: addAt()
@@ -414,6 +468,18 @@ struct AddAtTests {
     #expect(q.currentIndex == 0)
   }
 
+  /// Same pinning requirement as `add()` into an empty queue — see its twin.
+  @Test func toEmptyQueue_withShuffleAlreadyOn_startTrackLeadsTheOrder() throws {
+    let q = QueueManager()
+    q.shuffleEnabled = true
+    try q.addAt(tracks("a", "b", "c", "d", "e", "f"), at: 0)
+
+    #expect(q.shuffleOrder.isFirst(0))
+    #expect(!q.isLastInPlaybackOrder)
+    #expect(q.nextTracks.count == 5)
+    #expect(q.previousTracks.isEmpty)
+  }
+
   @Test func invalidIndex_throws() {
     let q = QueueManager()
     q.setQueue(tracks("a"))
@@ -691,10 +757,10 @@ struct ClearTests {
 @Suite("replace & removeUpcomingTracks")
 @MainActor
 struct OtherMutationTests {
-  @Test func replace_updatesTrackAtIndex() {
+  @Test func replace_updatesTrackAtIndex() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"))
-    q.replace(1, Track(id: "B"))
+    try q.replace(1, Track(id: "B"))
     #expect(q.tracks[1].id == "B")
   }
 
@@ -738,10 +804,10 @@ struct OtherMutationTests {
     #expect(q.tracks[0].id == "a")
   }
 
-  @Test func replace_currentTrack_reflectsInCurrentTrack() {
+  @Test func replace_currentTrack_reflectsInCurrentTrack() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b", "c"), initialIndex: 1)
-    q.replace(1, Track(id: "B"))
+    try q.replace(1, Track(id: "B"))
     #expect(q.currentTrack?.id == "B")
     #expect(q.currentIndex == 1)
   }
@@ -926,12 +992,12 @@ struct DelegateTests {
     #expect(spy.calls.count == 1)
   }
 
-  @Test func queueDidChangeTracks_firesOnReplace() {
+  @Test func queueDidChangeTracks_firesOnReplace() throws {
     let q = QueueManager()
     q.setQueue(tracks("a", "b"))
     let spy = DelegateSpy()
     q.delegate = spy
-    q.replace(0, Track(id: "A"))
+    try q.replace(0, Track(id: "A"))
     #expect(spy.calls.count == 1)
   }
 

package/ios/Tests/RemoteCommandControllerTests.swift

@@ -136,6 +136,22 @@ struct RemoteCommandControllerTests {
     #expect(center.previousTrackCommand.isEnabled)
   }
 
+  /// The handler properties must not capture the controller strongly. Assigning a
+  /// bare method reference (`= handlePlayCommandDefault`) curries to
+  /// `{ [self] in self.method($0) }`, and storing that back on self is a permanent
+  /// cycle — one leaked controller per player instance, across every JS reload.
+  @Test func doesNotRetainItselfThroughHandlers() {
+    weak var weakController: RemoteCommandController?
+    autoreleasepool {
+      let (controller, _) = makeController()
+      // Forces every lazy handler to initialize, which is what closes the cycle.
+      controller.enable(commands: RemoteCommand.all())
+      controller.disableAll()
+      weakController = controller
+    }
+    #expect(weakController == nil)
+  }
+
   @Test func shuffleAndRepeatStateSurviveCommandCenterSwitch() {
     let (controller, _) = makeController()
     let center = MPRemoteCommandCenter.shared()

package/ios/Tests/SectionPresentationTests.swift

@@ -58,4 +58,33 @@ struct SectionPresentationTests {
       SectionPresentation(for: style(display: nil, gridWrap: false), supportsWrappingGrid: true)
         == .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.
+    #expect(
+      SectionPresentation.tileFamily(for: SectionStyle(gridTile: .card), singleLine: true)
+        == .cardElements)
+    #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)
+  }
+
+  @Test func effectiveAccessorySymbol_noneAndAbsenceDrawNothing() {
+    // A declared symbol draws; 'none' (the inheritance escape) and absence
+    // both fall back to the derived accessory.
+    #expect(
+      SectionPresentation.effectiveAccessorySymbol(TrackStyle(accessorySymbol: "lock.fill"))
+        == "lock.fill")
+    #expect(
+      SectionPresentation.effectiveAccessorySymbol(TrackStyle(accessorySymbol: "none")) == nil)
+    #expect(SectionPresentation.effectiveAccessorySymbol(TrackStyle()) == nil)
+    #expect(SectionPresentation.effectiveAccessorySymbol(nil) == nil)
+  }
 }

package/ios/Tests/StyleResolverTests.swift

@@ -33,6 +33,21 @@ struct SectionStyleResolutionTests {
     #expect(resolved.display == nil)
     #expect(resolved.artworkRendering == nil)
     #expect(resolved.gridWrap == nil)
+    #expect(resolved.gridTile == nil)
+  }
+
+  @Test func gridTileResolvesByScopeOverride() {
+    // A page-wide card treatment; one section opts back to plain tiles.
+    let inherited = StyleResolver.sectionStyle(
+      section: nil,
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(inherited.gridTile == .card)
+    let overridden = StyleResolver.sectionStyle(
+      section: SectionStyle(gridTile: .plain),
+      page: SectionStyle(gridTile: .card),
+    )
+    #expect(overridden.gridTile == .plain)
   }
 }
 
@@ -64,4 +79,49 @@ struct TrackStyleResolutionTests {
     )
     #expect(resolved.display == nil)
   }
+
+  @Test func imageShapeInheritsAndOverridesPerItem() {
+    // Section-wide circular (an artists shelf); one album overrides.
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(imageShape: .circular),
+    )
+    #expect(inherited.imageShape == .circular)
+    let overridden = StyleResolver.trackStyle(
+      track: TrackStyle(imageShape: .roundedRectangle),
+      section: SectionStyle(imageShape: .circular),
+    )
+    #expect(overridden.imageShape == .roundedRectangle)
+  }
+
+  @Test func accessorySymbolInheritsAndNoneResolvesAsAValue() {
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(accessorySymbol: "lock.fill"),
+    )
+    #expect(inherited.accessorySymbol == "lock.fill")
+    // 'none' is the inheritance escape — it must survive resolution intact
+    // (the renderer, not the resolver, maps it to "no accessory").
+    let escaped = StyleResolver.trackStyle(
+      track: TrackStyle(accessorySymbol: "none"),
+      section: SectionStyle(accessorySymbol: "lock.fill"),
+    )
+    #expect(escaped.accessorySymbol == "none")
+  }
+
+  @Test func cardPropertiesInheritAndOverridePerItem() {
+    // Section-wide tint/mode; one card overrides its image mode.
+    let inherited = StyleResolver.trackStyle(
+      track: nil,
+      section: SectionStyle(accessorySymbol: nil, cardTint: "#1e3a8a", cardImage: .background),
+    )
+    #expect(inherited.cardTint == "#1e3a8a")
+    #expect(inherited.cardImage == .background)
+    let overridden = StyleResolver.trackStyle(
+      track: TrackStyle(cardImage: .normal),
+      section: SectionStyle(cardTint: "#1e3a8a", cardImage: .background),
+    )
+    #expect(overridden.cardImage == .normal)
+    #expect(overridden.cardTint == "#1e3a8a")
+  }
 }

package/ios/Tests/Support/TestTypes.swift

@@ -185,6 +185,7 @@ final class MockSleepTimerHandling: SleepTimerHandling {
   var onComplete: (() -> Void)?
   var onFadeStart: ((_ duration: TimeInterval) -> Void)?
   var onFadeCancel: (() -> Void)?
+  var onChanged: ((SleepTimerState) -> Void)?
   var trackChangedCallCount = 0
   var trackPlayedToEndCallCount = 0
   var clearCallCount = 0
@@ -196,6 +197,12 @@ final class MockSleepTimerHandling: SleepTimerHandling {
 
   func onTrackChanged() { trackChangedCallCount += 1 }
   func onTrackPlayedToEnd() { trackPlayedToEndCallCount += 1 }
+
+  // Consumer-facing surface — unused by the coordinator tests, present only to
+  // satisfy the protocol. Add recorders alongside the tests that need them.
+  func get() -> SleepTimerState? { nil }
+  func set(seconds _: TimeInterval, fadeDuration _: TimeInterval?) {}
+  func setToEndOfTrack() {}
 }
 
 // MARK: - Mock RetryHandling

package/ios/TrackPlayer.swift

@@ -136,7 +136,7 @@ class TrackPlayer {
   var previousTracks: [Track] { coordinator.previousTracks }
   var isLastInPlaybackOrder: Bool { coordinator.isLastInPlaybackOrder }
   var playbackActive: Bool { coordinator.playbackActive }
-  var sleepTimerManager: SleepTimerManager { coordinator.sleepTimerManager as! SleepTimerManager }
+  var sleepTimerManager: any SleepTimerHandling { coordinator.sleepTimerManager }
   var queue: QueueManager { coordinator.queue }
   var loadSeekCoordinator: LoadSeekCoordinator { coordinator.loadSeekCoordinator }
   var playingStateManager: PlayingStateManager { coordinator.playingStateManager }
@@ -195,12 +195,14 @@ class TrackPlayer {
     return seconds.isNaN ? 0 : seconds
   }
 
+  /// The current item's duration, or 0 when it has none (a live stream).
+  ///
+  /// Don't reintroduce `item.asset.duration`: it is deprecated as of the iOS 16
+  /// minimum and blocks the main actor fetching a remote asset's duration. Read
+  /// on every progress tick.
   var duration: Double {
     guard let item = avPlayer.currentItem else { return 0.0 }
 
-    if !item.asset.duration.seconds.isNaN {
-      return item.asset.duration.seconds
-    }
     if !item.duration.seconds.isNaN {
       return item.duration.seconds
     }
@@ -252,8 +254,22 @@ class TrackPlayer {
   var rate: Float {
     get { coordinator.rate }
     set {
+      // A non-positive rate leaves the player unable to play at all — and would
+      // poison the next play() through `defaultRate` below. Rejected here, at
+      // the one setter every source funnels through (JS, remote command, CarPlay
+      // rate cycling, a restored snapshot), rather than at each of them.
+      guard newValue > 0 else { return }
       coordinator.rate = newValue
-      avPlayer.rate = newValue
+      // Assigning a nonzero `AVPlayer.rate` IS `play()` — so setting the speed
+      // while paused would start audible playback behind the user's back, with
+      // `playWhenReady` still false (the lock screen would read "paused" over
+      // sound). On Android and web the speed control is independent of the play
+      // intent; this keeps iOS the same.
+      avPlayer.defaultRate = newValue
+      if playWhenReady { avPlayer.rate = newValue }
+      // Same reason as the repeat/shuffle edges below — a speed changed while
+      // paused would otherwise not reach the snapshot the cold resume restores.
+      persistPlaybackState()
     }
   }
 
@@ -312,17 +328,6 @@ class TrackPlayer {
     coordinator.load(track, playWhenReady: playWhenReady)
   }
 
-  func togglePlaying() {
-    switch avPlayer.timeControlStatus {
-    case .playing, .waitingToPlayAtSpecifiedRate:
-      pause()
-    case .paused:
-      play()
-    @unknown default:
-      fatalError("Unknown AVPlayer.timeControlStatus")
-    }
-  }
-
   func play() { coordinator.play() }
   func pause() { coordinator.pause() }
   func togglePlayback() { coordinator.togglePlayback() }
@@ -456,13 +461,17 @@ class TrackPlayer {
     )
   }
 
+  /// Empties the queue and the published now-playing info. Unlinking the
+  /// session belongs in `destroy()`: `avPlayer` survives a clear, and only
+  /// `setupAVPlayer()` re-links.
   func clear() {
     coordinator.clear()
-    nowPlayingInfoController.unlinkPlayer()
   }
 
   func destroy() {
     clear()
+    // The player is going away for good — now the session must go with it.
+    nowPlayingInfoController.unlinkPlayer()
     // An AVPlayer retains its time observers: one left registered is still attached when the
     // player is released, and outlives this object.
     playerTimeObserver.unregisterForBoundaryTimeEvents()
@@ -550,10 +559,12 @@ class TrackPlayer {
 
     nowPlayingInfoController.linkPlayer(avPlayer)
 
+    // Stage the rate unconditionally, so a freshly recreated player carries it
+    // before anything plays — `rate`'s setter holds the same invariant, and on
+    // the playWhenReady branch below `defaultRate` was previously left at 1.0.
+    avPlayer.defaultRate = rate
     if playWhenReady {
       startPlayback()
-    } else {
-      avPlayer.defaultRate = rate
     }
   }
 
@@ -755,13 +766,28 @@ extension TrackPlayer {
       PersistedPlaybackState(
         track: JsonTrack(from: track),
         positionMs: positionMs,
-        repeatMode: repeatMode.persistedString,
+        repeatMode: repeatMode.stringValue,
         shuffleEnabled: shuffleEnabled,
         playbackSpeed: rate,
       ),
     )
   }
 
+  /// Applies the player settings a snapshot carries — the inverse of
+  /// `persistPlaybackState()`, and the twin of the Kotlin store's `restore()`.
+  ///
+  /// Call BEFORE building the queue: `setQueue` rebuilds the shuffle order
+  /// pinned to the starting track, so shuffle has to be set for that order to
+  /// be the one playback uses (and the mode events then precede the
+  /// queue-changed event, as on Android). An unrecognized repeat mode restores
+  /// as `.off` rather than failing the whole resume over one field; a
+  /// non-positive speed is rejected by `rate`'s own setter.
+  func restorePlaybackSettings(from state: PersistedPlaybackState) {
+    repeatMode = RepeatMode(fromString: state.repeatMode) ?? .off
+    shuffleEnabled = state.shuffleEnabled
+    rate = state.playbackSpeed
+  }
+
   /// Start a 5 s repeating save while playback is active. A previous task is
   /// cancelled first so there is never more than one running at a time.
   private func startPeriodicSave() {
@@ -781,17 +807,6 @@ extension TrackPlayer {
   }
 }
 
-private extension RepeatMode {
-  /// String representation stored in `PersistedPlaybackState.repeatMode`.
-  var persistedString: String {
-    switch self {
-    case .off: "off"
-    case .track: "track"
-    case .queue: "queue"
-    }
-  }
-}
-
 // MARK: - PlaybackEffectHandler
 
 extension TrackPlayer: PlaybackEffectHandler {
@@ -857,15 +872,23 @@ extension TrackPlayer: PlaybackEffectHandler {
   }
 
   func clearNowPlaying() {
-    nowPlayingInfoController.clear()
+    nowPlayingUpdater.clearNowPlaying()
   }
 
+  // Both persist: a snapshot is otherwise only written on track load, on pause,
+  // and every 5s while playing, so a mode toggled while paused was lost — the
+  // cold-start resume would restore the value from before the toggle. Android
+  // persists on every setting change (`PlayerListener.onRepeatModeChanged` /
+  // `onShuffleModeEnabledChanged`); these are the same two edges, and the
+  // coordinator only calls them on a real change.
   func updateRemoteRepeatMode(_ mode: RepeatMode) {
     remoteCommandController.updateRepeatMode(mode)
+    persistPlaybackState()
   }
 
   func updateRemoteShuffleMode(_ enabled: Bool) {
     remoteCommandController.updateShuffleMode(enabled)
+    persistPlaybackState()
   }
 
   func updateSkipAvailability(canNext: Bool, canPrevious: Bool) {
@@ -884,8 +907,8 @@ extension TrackPlayer: TrackSelectionPlayer {}
 // MARK: - Queue Methods (thin forwarders)
 
 extension TrackPlayer {
-  func replace(_ index: Int, _ track: Track) {
-    coordinator.replace(index, track)
+  func replace(_ index: Int, _ track: Track) throws {
+    try coordinator.replace(index, track)
   }
 
   func setQueue(

package/ios/Util/NetworkMonitor.swift

@@ -11,13 +11,36 @@ final class NetworkMonitor: @unchecked Sendable {
   private let monitor: NWPathMonitor
   private let queue = DispatchQueue(label: "com.audiobrowser.networkmonitor")
 
-  /// Current network connectivity state. Must only be set on main thread.
-  private(set) var isOnline: Bool = false {
-    didSet {
-      if oldValue != isOnline {
-        logger.notice("Network status changed: \(oldValue) -> \(self.isOnline)")
-        onChanged?(isOnline)
-      }
+  /// Guards `_isOnline` only. Never held across `onChanged` — see `apply`.
+  private let lock = NSLock()
+  private var _isOnline = false
+
+  /// Current network connectivity state. Readable from any thread: the value is
+  /// lock-protected rather than confined, so callers on the JS thread (Nitro's
+  /// `getOnline`) don't have to block on a main-queue hop to read a Bool.
+  ///
+  /// The broadcast is main-confined even though the value isn't — `onChanged`
+  /// fans out to the JS bridge, a now-playing re-render and a player reload, so
+  /// it must not run under the lock (reentrancy) or off the main actor.
+  var isOnline: Bool {
+    lock.lock()
+    defer { lock.unlock() }
+    return _isOnline
+  }
+
+  /// Stores a new status and, if it actually changed, broadcasts on main —
+  /// outside the lock.
+  private func apply(_ newStatus: Bool) {
+    lock.lock()
+    let changed = _isOnline != newStatus
+    let oldValue = _isOnline
+    _isOnline = newStatus
+    lock.unlock()
+
+    guard changed else { return }
+    logger.notice("Network status changed: \(oldValue) -> \(newStatus)")
+    DispatchQueue.main.async { [weak self] in
+      self?.onChanged?(newStatus)
     }
   }
 
@@ -31,29 +54,23 @@ final class NetworkMonitor: @unchecked Sendable {
   init() {
     monitor = NWPathMonitor()
 
-    // Set up handler before starting
-    monitor.pathUpdateHandler = { [weak self] path in
-      let newStatus = path.status == .satisfied
-      DispatchQueue.main.async { [weak self] in
-        self?.isOnline = newStatus
-      }
-    }
-
-    // Start monitoring
-    monitor.start(queue: queue)
-
-    // Read initial state after starting (currentPath is now valid)
+    // Seed BEFORE `start`. `start` publishes `self` to the monitor queue, so any
+    // write after it races the handler's locked write — and would clobber a real
+    // update with a `currentPath` the monitor hasn't finished evaluating. Nothing
+    // recovers from that: the handler has already fired, `onChanged` isn't wired
+    // until setupPlayer, and the stale value then drives `getOnline()`, the JS
+    // event, and RetryManager's offline parking until the next genuine path
+    // change. Seeding first is a best-effort guess; the handler fires shortly
+    // after `start` and is the authoritative last writer.
     let initialStatus = monitor.currentPath.status == .satisfied
     logger.notice("NetworkMonitor initialized, initial isOnline=\(initialStatus)")
-    isOnline = initialStatus
-  }
+    _isOnline = initialStatus
 
-  // MARK: - Public Methods
+    monitor.pathUpdateHandler = { [weak self] path in
+      self?.apply(path.status == .satisfied)
+    }
 
-  /// Gets the current network connectivity state.
-  /// - Returns: true if device is online, false otherwise
-  func getOnline() -> Bool {
-    isOnline
+    monitor.start(queue: queue)
   }
 
   /// Stops monitoring and cleans up resources.

package/ios/Util/SFSymbolRenderer.swift

@@ -11,13 +11,21 @@ final class SFSymbolRenderer: @unchecked Sendable {
   @MainActor static let shared = SFSymbolRenderer()
   static let defaultCanvasSize = CGSize(width: 200, height: 200)
 
+  /// Bumped whenever the rendering below changes (symbol point-size factor,
+  /// centering, tinting, background fill). It is part of the cache filename
+  /// because `.cachesDirectory` survives app updates and the existence check is
+  /// the only cache validation — without a version key, every device that had
+  /// rendered a symbol once would keep serving the OLD pixels forever after a
+  /// render change.
+  private static let renderVersion = 1
+
   private let logger = Logger(subsystem: "com.audiobrowser", category: "SFSymbolRenderer")
   private let scale: CGFloat
   private let cacheDirectory: URL
 
   @MainActor
   private init() {
-    scale = UIScreen.main.scale
+    scale = appDisplayScale
 
     let caches = FileManager.default.urls(for: .cachesDirectory, in: .userDomainMask)[0]
     cacheDirectory = caches.appendingPathComponent("sf-symbols", isDirectory: true)
@@ -45,7 +53,8 @@ final class SFSymbolRenderer: @unchecked Sendable {
     let safeArtwork = artworkValue.unicodeScalars
       .filter { CharacterSet.alphanumerics.contains($0) || $0 == "_" }
       .map(String.init).joined()
-    let fileName = "\(safeArtwork)_\(Int(canvasSize.width))x\(Int(canvasSize.height))_\(Int(scale))x"
+    let fileName =
+      "\(safeArtwork)_\(Int(canvasSize.width))x\(Int(canvasSize.height))_\(Int(scale))x_v\(Self.renderVersion)"
     let fileURL = cacheDirectory.appendingPathComponent("\(fileName).png")
 
     if FileManager.default.fileExists(atPath: fileURL.path) {
@@ -139,4 +148,17 @@ extension UIColor {
       self.init(white: 0, alpha: 1)
     }
   }
+
+  /// Failable form for *declared* colors (`style.cardTint`): anything but a
+  /// 3- or 6-digit hex value is nil, so an unparseable declaration degrades
+  /// to "no declaration" (the system default) instead of rendering black —
+  /// matching how unknown enum values decode. `init(hex:)` keeps its lenient
+  /// black fallback for the `sf:` artwork params it has always served.
+  convenience init?(declaredHex hex: String) {
+    let digits = hex.trimmingCharacters(in: CharacterSet(charactersIn: "#"))
+    guard [3, 6].contains(digits.count),
+          digits.allSatisfy(\.isHexDigit)
+    else { return nil }
+    self.init(hex: hex)
+  }
 }

package/ios/Util/SVGProcessor.swift

@@ -4,7 +4,14 @@ import UIKit
 
 /// Kingfisher processor that renders SVG data to UIImage using SwiftDraw.
 struct SVGProcessor: ImageProcessor {
-  let identifier = "com.audiobrowser.svgprocessor"
+  /// Kingfisher keys its cache on `identifier` alone (`ImageCache.computedKey`),
+  /// and `.scaleFactor` never enters that key — so the render parameters have to,
+  /// or two different rasterizations of the same URL would collide. Today only
+  /// CarPlay rasterizes SVGs (one screen, one scale), so this is insurance
+  /// against a second call site rather than a live fix.
+  var identifier: String {
+    "com.audiobrowser.svgprocessor(\(size?.width ?? -1)x\(size?.height ?? -1)@\(scale))"
+  }
 
   /// Target size for rendering (in points). If nil, uses SVG's intrinsic size.
   let size: CGSize?
@@ -15,7 +22,7 @@ struct SVGProcessor: ImageProcessor {
   @MainActor
   init(size: CGSize? = nil, scale: CGFloat? = nil) {
     self.size = size
-    self.scale = scale ?? UIScreen.main.scale
+    self.scale = scale ?? appDisplayScale
   }
 
   func process(item: ImageProcessItem, options _: KingfisherParsedOptionsInfo) -> KFCrossPlatformImage? {

package/lib/commonjs/features/playback/progress.js

@@ -101,7 +101,8 @@ function usePolledProgress(updateInterval = 1000) {
       poll();
     };
     const stop = () => {
-      clearTimeout(timer);
+      // Guarded: React Native types clearTimeout(handle: number) — no undefined.
+      if (timer !== undefined) clearTimeout(timer);
       timer = undefined;
       unsubscribeState?.();
       unsubscribeState = undefined;

package/lib/commonjs/features/playback/progress.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","require","_reactNative","_native","_NativeUpdatedValue","_useNativeUpdatedValue","_state","getProgress","nativeBrowser","onProgressUpdated","exports","NativeUpdatedValue","emitterize","cb","onPlaybackProgressUpdated","useProgress","useNativeUpdatedValue","usePolledProgress","updateInterval","state","setState","useState","position","duration","buffered","useEffect","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","onPlaybackChanged","addListener","stop","clearTimeout","appStateSub","AppState","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":";;;;;;;;;AAAA,IAAAA,MAAA,GAAAC,OAAA;AACA,IAAAC,YAAA,GAAAD,OAAA;AACA,IAAAE,OAAA,GAAAF,OAAA;AACA,IAAAG,mBAAA,GAAAH,OAAA;AACA,IAAAI,sBAAA,GAAAJ,OAAA;AACA,IAAAK,MAAA,GAAAL,OAAA;AAEA;;AAiBA;AACA;AACA;;AAMA;;AAEA;AACA;AACA;AACA;AACA;AACO,SAASM,WAAWA,CAAA,EAAa;EACtC,OAAOC,qBAAa,CAACD,WAAW,CAAC,CAAC;AACpC;;AAEA;;AAEA;AACA;AACA;AACA;AACA;AACO,MAAME,iBAAiB,GAAAC,OAAA,CAAAD,iBAAA,GAC5BE,sCAAkB,CAACC,UAAU,CAC1BC,EAAE,IAAML,qBAAa,CAACM,yBAAyB,GAAGD,EACrD,CAAC;;AAEH;;AAEA;AACA;AACA;AACA;AACA;AACA;AACO,SAASE,WAAWA,CAAA,EAAa;EACtC,OAAO,IAAAC,4CAAqB,EAACT,WAAW,EAAEE,iBAAiB,CAAC;AAC9D;;AAEA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACA;AACO,SAASQ,iBAAiBA,CAACC,cAAc,GAAG,IAAI,EAAY;EACjE,MAAM,CAACC,KAAK,EAAEC,QAAQ,CAAC,GAAG,IAAAC,eAAQ,EAAW;IAC3CC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE,CAAC;IACXC,QAAQ,EAAE;EACZ,CAAC,CAAC;EAEF,IAAAC,gBAAS,EAAC,MAAM;IACd,IAAIC,KAAgD;IACpD,IAAIC,gBAA0C;IAE9C,MAAMC,MAAM,GAAGA,CAAA,KAAM;MACnB,IAAI;QACF,MAAM;UAAEN,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CAAC,GAAGjB,WAAW,CAAC,CAAC;QAEtDa,QAAQ,CAAES,YAAY,IACpBP,QAAQ,KAAKO,YAAY,CAACP,QAAQ,IAClCC,QAAQ,KAAKM,YAAY,CAACN,QAAQ,IAClCC,QAAQ,KAAKK,YAAY,CAACL,QAAQ,GAC9BK,YAAY,GACZ;UAAEP,QAAQ;UAAEC,QAAQ;UAAEC;QAAS,CACrC,CAAC;MACH,CAAC,CAAC,MAAM;QACN;MAAA;IAEJ,CAAC;IAED,MAAMM,IAAI,GAAGA,CAAA,KAAM;MACjBF,MAAM,CAAC,CAAC;MACRF,KAAK,GAAGK,UAAU,CAACD,IAAI,EAAEZ,cAAc,CAAC;IAC1C,CAAC;;IAED;IACA;IACA;IACA,MAAMc,KAAK,GAAGA,CAAA,KAAM;MAClB,IAAIN,KAAK,KAAKO,SAAS,EAAE;MACzBN,gBAAgB,GAAGO,wBAAiB,CAACC,WAAW,CAACP,MAAM,CAAC;MACxDE,IAAI,CAAC,CAAC;IACR,CAAC;IAED,MAAMM,IAAI,GAAGA,CAAA,KAAM;MACjBC,YAAY,CAACX,KAAK,CAAC;MACnBA,KAAK,GAAGO,SAAS;MACjBN,gBAAgB,GAAG,CAAC;MACpBA,gBAAgB,GAAGM,SAAS;IAC9B,CAAC;IAED,MAAMK,WAAW,GAAGC,qBAAQ,CAACC,gBAAgB,CAAC,QAAQ,EAAGC,IAAI,IAAK;MAChE,IAAIA,IAAI,KAAK,QAAQ,EAAET,KAAK,CAAC,CAAC,MACzBI,IAAI,CAAC,CAAC;IACb,CAAC,CAAC;IAEF,IAAIG,qBAAQ,CAACV,YAAY,KAAK,QAAQ,EAAEG,KAAK,CAAC,CAAC;IAE/C,OAAO,MAAM;MACXI,IAAI,CAAC,CAAC;MACNE,WAAW,CAACI,MAAM,CAAC,CAAC;IACtB,CAAC;EACH,CAAC,EAAE,CAACxB,cAAc,CAAC,CAAC;EAEpB,OAAOC,KAAK;AACd","ignoreList":[]}
+{"version":3,"names":["_react","require","_reactNative","_native","_NativeUpdatedValue","_useNativeUpdatedValue","_state","getProgress","nativeBrowser","onProgressUpdated","exports","NativeUpdatedValue","emitterize","cb","onPlaybackProgressUpdated","useProgress","useNativeUpdatedValue","usePolledProgress","updateInterval","state","setState","useState","position","duration","buffered","useEffect","timer","unsubscribeState","update","currentState","poll","setTimeout","start","undefined","onPlaybackChanged","addListener","stop","clearTimeout","appStateSub","AppState","addEventListener","next","remove"],"sourceRoot":"../../../../src","sources":["features/playback/progress.ts"],"mappings":"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","ignoreList":[]}

package/lib/commonjs/features/playback/rate.js

@@ -20,8 +20,15 @@ function getRate() {
 
 /**
  * Sets the playback rate.
+ *
+ * The rate is a speed multiplier, not a transport control — it is independent
+ * of play/pause, and setting it while paused never starts playback. Use
+ * {@link play} / {@link pause} for that.
+ *
  * @param rate - The playback rate to change to, where 0.5 would be half speed,
- * 1 would be regular speed, 2 would be double speed etc.
+ * 1 would be regular speed, 2 would be double speed etc. Must be greater than
+ * zero; platforms disagree on what a non-positive rate does (iOS ignores it,
+ * Android throws, web stalls the element), so treat it as unsupported.
  */
 function setRate(rate) {
   _native.nativeBrowser.setRate(rate);