react-native-queue-player 1.0.3 → 1.0.6

package/android/src/test/java/com/margelo/nitro/queueplayer/TrackPlayerTransportTest.kt

@@ -155,8 +155,7 @@ class TrackPlayerTransportTest {
   fun `setPlaybackSpeedInternal round-trips through getPlaybackSpeed and applies the pitch mode`() {
     // Pitch is lib-owned, driven by the pitch-correction mode. Under the
     // default voice mode the engine holds pitch at 1.0 while the speed
-    // changes (pitch preserved). The full none/voice/music mapping is
-    // covered by PitchCorrectionTest.
+    // changes (pitch preserved).
     player.setPlaybackSpeedInternal(1.5)
     assertEquals(1.5, player.getPlaybackSpeed(), 0.001)
     assertEquals(1.0f, player.player!!.playbackParameters.pitch, 0.001f)
@@ -194,9 +193,7 @@ class TrackPlayerTransportTest {
     assertEquals(RepeatMode.TRACK, player.repeatModeState)
   }
 
-  // shuffleQueue() is covered end-to-end via the demo suite
-  // shuffle.ts steps and by exercising shuffleQueueInternal in the
-  // sibling tests below.
+  // The sibling tests below exercise shuffleQueueInternal.
 
   // --- basic play/pause/stop no-op
 

package/android/src/test/java/com/margelo/nitro/queueplayer/VisualizerKtTest.kt

@@ -19,8 +19,7 @@ import java.util.concurrent.CopyOnWriteArrayList
 /**
  * Wiring coverage for the [Visualizer] HybridObject — subscriber
  * refcount, attach/detach lifecycle against a [PlaybackEngine],
- * engine swap behaviour. Audio-thread frame emission is covered by
- * [FFTProcessorTeeTest]; this test exercises only the Hybrid surface
+ * engine swap behaviour. This test exercises only the Hybrid surface
  * and the PlaybackEngine attach contract.
  */
 @RunWith(RobolectricTestRunner::class)

package/ios/AVPlayerItemQueueItemId.swift

@@ -31,8 +31,8 @@ extension AVPlayerItem {
   /// Lib-internal identity for this AVPlayerItem. Set once at
   /// construction by `AVQueueBuilder.makeItem`; never mutated
   /// after. nil only for AVPlayerItems that did not flow through
-  /// the lib's queue construction path (e.g. raw makeItemRaw
-  /// XCTest fixtures).
+  /// the lib's queue construction path (e.g. built directly via
+  /// `makeItemRaw`).
   var queueItemId: String? {
     get { objc_getAssociatedObject(self, &queueItemIdKey) as? String }
     set {

package/ios/AVQueueBuilder.swift

@@ -3,13 +3,11 @@ import AVFoundation
 /// Builder utility for `[AVPlayerItem]` arrays, with HTTP-header +
 /// user-agent injection on remote URLs.
 ///
-/// The enum is `public` only so XCTest targets can reach the `Raw`-suffix
-/// helpers through plain `import QueuePlayer` (see NOTES.md §6 for the
-/// Swift ↔ C++ interop reason we can't rely on `@testable import`).
-/// The `Raw` helpers themselves are gated behind `@_spi(QueuePlayerTests)`
-/// so consumers who don't opt into the SPI never see them — the API
-/// surface consumers care about is the Nitrogen-integrated TrackPlayer
-/// methods, not this builder directly.
+/// The `Raw`-suffix helpers take primitive arguments so they stay clear
+/// of the Swift ↔ C++ interop boundary. They are gated behind
+/// `@_spi(QueuePlayerTests)` so consumers who don't opt into the SPI
+/// never see them — the API surface consumers care about is the
+/// Nitrogen-integrated TrackPlayer methods, not this builder directly.
 ///
 /// Constructs AVPlayerItem instances from TrackItem descriptors,
 /// applying the PlayerConfig's custom HTTP headers + user agent.
@@ -135,10 +133,10 @@ public enum AVQueueBuilder {
     item.preferredForwardBufferDuration = 0.0
   }
 
-  /// Plain-Swift item builder. Takes primitive arguments so it is directly
-  /// callable from XCTest targets without crossing the Swift ↔ C++ interop
-  /// boundary; `makeItem(for:, config:)` is the thin adapter that unpacks
-  /// the Nitrogen-generated `TrackItem` + `PlayerConfig` and delegates here.
+  /// Plain-Swift item builder. Takes primitive arguments so it stays clear
+  /// of the Swift ↔ C++ interop boundary; `makeItem(for:, config:)` is the
+  /// thin adapter that unpacks the Nitrogen-generated `TrackItem` +
+  /// `PlayerConfig` and delegates here.
   ///
   /// Gated behind `@_spi(QueuePlayerTests)` so it stays off the library's
   /// consumer-facing public surface.
@@ -171,9 +169,9 @@ public enum AVQueueBuilder {
     return item
   }
 
-  /// Plain-Swift merging core — takes primitive arguments so it is
-  /// directly callable from XCTest targets without crossing the Swift↔C++
-  /// interop boundary. `makeItemRaw(urlString:headers:userAgent:)` below
+  /// Plain-Swift merging core — takes primitive arguments so it stays
+  /// clear of the Swift↔C++ interop boundary.
+  /// `makeItemRaw(urlString:headers:userAgent:)` below
   /// calls this, and `makeItem(for:, config:)` unpacks its `PlayerConfig`
   /// argument into the same primitive pair and calls `makeItemRaw`.
   ///

package/ios/CarPlayCoordinator.swift

@@ -29,14 +29,52 @@ final class CarPlayCoordinator {
   static let shared = CarPlayCoordinator()
 
   let dataProvider: CarPlayBrowseDataProvider
+  let queueProvider: CarPlayQueueProvider
   let bridge: CarPlayBridge
   let pending: PendingBrowseRequests
   let loader: ArtworkLoader
 
   private init() {
     self.dataProvider = CarPlayBrowseDataProvider()
+    self.queueProvider = CarPlayQueueProvider()
     self.bridge = CarPlayBridge()
     self.pending = PendingBrowseRequests()
     self.loader = ArtworkLoader()
   }
+
+  // MARK: - Queue skip
+
+  /// Skip playback to a queue index. `TrackPlayer` registers this at
+  /// configure; the CarPlay scene delegate invokes it when the user
+  /// taps a row in the Up Next list. Set and called on the main thread
+  /// only, so no lock is needed.
+  var skipToIndexHandler: ((Int) -> Void)?
+
+  // MARK: - Connection state
+
+  /// Whether the CarPlay scene is currently connected. Written by
+  /// [CarPlaySceneDelegate] at scene attach / detach — the same points that
+  /// fire the `onCarConnect` / `onCarDisconnect` callbacks — and read by the
+  /// `isCarConnected()` Hybrid getter. Scene callbacks land on the main
+  /// queue; the getter can be read from any Nitro thread, so the flag is
+  /// lock-guarded.
+  ///
+  /// A media app has a single CarPlay template scene, so this is a plain
+  /// attached/detached flag rather than a connection count (the Android side
+  /// counts because its headless controllers — Auto / Wear / Assistant — can
+  /// overlap).
+  private let connectionLock = NSLock()
+  private var carConnectedFlag = false
+
+  var isCarConnected: Bool {
+    connectionLock.lock()
+    defer { connectionLock.unlock() }
+    return carConnectedFlag
+  }
+
+  func setCarConnected(_ connected: Bool) {
+    connectionLock.lock()
+    defer { connectionLock.unlock() }
+    carConnectedFlag = connected
+  }
 }

package/ios/CarPlayQueueBuilder.swift

@@ -0,0 +1,82 @@
+import CarPlay
+import UIKit
+
+/// Convert a [CarPlayQueueSnapshot] into the CarPlay "Up Next" list
+/// template shown when the user taps the Now Playing queue button.
+/// Single-section `CPListTemplate` — one `CPListItem` per queue entry,
+/// with the currently-playing entry marked via `isPlaying`.
+///
+/// Audio-app list cap: CarPlay reports the runtime row limit via
+/// `CPListTemplate.maximumItemCount`. Over-cap queues are truncated to
+/// the first N rows; the current entry's index still maps 1:1 to the
+/// list row as long as it falls inside the cap.
+///
+/// Stateless helper. The owning scene delegate pushes the returned
+/// template onto the interface controller.
+final class CarPlayQueueBuilder {
+
+  /// Maximum rows per Up Next list. Reads the SDK property so the cap
+  /// tracks whatever the running CarPlay framework enforces.
+  static var maximumItemCount: Int { CPListTemplate.maximumItemCount }
+
+  /// Build the Up Next `CPListTemplate` from [snapshot]. Each row's
+  /// tap handler invokes [skip] with that row's queue index, then the
+  /// caller pops back to Now Playing. The entry at
+  /// `snapshot.currentIndex` is marked `isPlaying`. Rows beyond
+  /// [maximumItemCount] are dropped.
+  func buildQueueTemplate(
+    snapshot: CarPlayQueueSnapshot,
+    loader: ArtworkLoader,
+    maximumItemCount: Int = CarPlayQueueBuilder.maximumItemCount,
+    skip: @escaping (Int) -> Void
+  ) -> CPListTemplate {
+    let cap = max(0, maximumItemCount)
+    let visible = snapshot.entries.prefix(cap)
+    let items = visible.enumerated().map { index, entry in
+      makeQueueItem(
+        entry: entry,
+        index: index,
+        isCurrent: index == snapshot.currentIndex,
+        loader: loader,
+        skip: skip
+      )
+    }
+    return CPListTemplate(
+      title: upNextTitle,
+      sections: [CPListSection(items: items)]
+    )
+  }
+
+  /// Build a single Up Next row. Text = entry title, detail = subtitle.
+  /// Tap fires [skip] with [index]. The current row shows the playing
+  /// indicator; artwork loads asynchronously via [loader].
+  func makeQueueItem(
+    entry: CarPlayQueueEntry,
+    index: Int,
+    isCurrent: Bool,
+    loader: ArtworkLoader,
+    skip: @escaping (Int) -> Void
+  ) -> CPListItem {
+    let listItem = CPListItem(
+      text: entry.title,
+      detailText: entry.subtitle,
+      image: nil
+    )
+    listItem.isPlaying = isCurrent
+    if let artworkUrl = entry.artworkUrl, !artworkUrl.isEmpty {
+      loader.load(uri: artworkUrl) { [weak listItem] image in
+        guard let listItem = listItem, let image = image else { return }
+        listItem.setImage(image)
+      }
+    }
+    listItem.handler = { _, completion in
+      skip(index)
+      completion()
+    }
+    return listItem
+  }
+
+  private var upNextTitle: String {
+    NSLocalizedString("Up Next", comment: "CarPlay queue list title")
+  }
+}

package/ios/CarPlayQueueProvider.swift

@@ -0,0 +1,73 @@
+import Foundation
+
+/// One queue entry mirrored for the CarPlay Up Next surface. A plain
+/// value type decoupled from the Nitro `TrackItem` — the mirror holds
+/// only what the list template renders, so the CarPlay scene reads
+/// display data without reaching back into the Hybrid.
+struct CarPlayQueueEntry {
+  let title: String
+  let subtitle: String?
+  let artworkUrl: String?
+}
+
+/// Immutable mirror of the live play queue for the CarPlay Up Next
+/// list. `currentIndex` is the index of the playing track, or -1 when
+/// nothing is current. Snapshot replacement is atomic (see
+/// [CarPlayQueueProvider]).
+struct CarPlayQueueSnapshot {
+  let entries: [CarPlayQueueEntry]
+  let currentIndex: Int
+}
+
+/// Native cache for the most-recent [CarPlayQueueSnapshot] pushed by
+/// `TrackPlayer` whenever the queue or current index changes. The
+/// CarPlay scene delegate reads from this cache to build the Up Next
+/// list so a queue-button tap does not have to round-trip through JS.
+///
+/// Snapshot replacement is atomic: a single `NSLock` guards the stored
+/// reference. Concurrent readers see either the prior snapshot in full
+/// or the new one in full, never a torn mix.
+///
+/// Update notifications: a `Notification` named
+/// [CarPlayQueueProvider.didUpdateNotification] fires on the main queue
+/// after every `setSnapshot`. The scene delegate observes it to
+/// re-evaluate the Up Next button's enabled state as the queue changes.
+final class CarPlayQueueProvider {
+
+  /// Notification posted on the main queue after `setSnapshot`.
+  static let didUpdateNotification = Notification.Name(
+    "com.margelo.nitro.queueplayer.CarPlayQueueProvider.didUpdate"
+  )
+
+  /// Replace the cached snapshot. Pass `nil` to clear. Posts
+  /// [didUpdateNotification] on the main queue (dispatched to main if
+  /// the caller is off-main) so observers re-evaluate against the new
+  /// snapshot on a stable thread.
+  func setSnapshot(_ snapshot: CarPlayQueueSnapshot?) {
+    lock.lock()
+    self.snapshot = snapshot
+    lock.unlock()
+
+    let notify = {
+      NotificationCenter.default.post(
+        name: CarPlayQueueProvider.didUpdateNotification,
+        object: self
+      )
+    }
+    if Thread.isMainThread {
+      notify()
+    } else {
+      DispatchQueue.main.async(execute: notify)
+    }
+  }
+
+  /// Read the current snapshot, or `nil` if none has been set.
+  func getSnapshot() -> CarPlayQueueSnapshot? {
+    lock.lock()
+    defer { lock.unlock() }
+    return snapshot
+  }
+
+  private var snapshot: CarPlayQueueSnapshot?
+  private let lock = NSLock()
+}

package/ios/CarPlaySceneDelegate.swift

@@ -52,11 +52,19 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
   /// delegate doesn't leak past its scene's lifetime.
   private var snapshotObserver: NSObjectProtocol?
 
+  /// Queue-mirror observer. Fires when the play queue or current index
+  /// changes so the Up Next button's enabled state re-evaluates.
+  /// Removed on scene disconnect.
+  private var queueObserver: NSObjectProtocol?
+
   /// Cached scene-construction template builder. Stateless; the
   /// live tab-bar reference above is what survives across snapshot
   /// updates.
   private let builder = CarPlayBrowseBuilder()
 
+  /// Stateless builder for the Up Next queue list template.
+  private let queueBuilder = CarPlayQueueBuilder()
+
   // MARK: - CPTemplateApplicationSceneDelegate
 
   public func templateApplicationScene(
@@ -122,6 +130,15 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
       self?.refreshRootTemplate()
     }
 
+    queueObserver = NotificationCenter.default.addObserver(
+      forName: CarPlayQueueProvider.didUpdateNotification,
+      object: coordinator.queueProvider,
+      queue: .main
+    ) { [weak self] _ in
+      self?.refreshUpNextButton()
+    }
+
+    coordinator.setCarConnected(true)
     coordinator.bridge.carConnectCallback()?()
   }
 
@@ -137,8 +154,14 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
       NotificationCenter.default.removeObserver(observer)
       snapshotObserver = nil
     }
+    if let observer = queueObserver {
+      NotificationCenter.default.removeObserver(observer)
+      queueObserver = nil
+    }
+    CPNowPlayingTemplate.shared.remove(self)
     self.interfaceController = nil
     self.rootTabBar = nil
+    CarPlayCoordinator.shared.setCarConnected(false)
     CarPlayCoordinator.shared.bridge.carDisconnectCallback()?()
     // Pending entries from this scene's session are stale — the
     // next scene attach starts from a fresh snapshot read, so
@@ -186,14 +209,65 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
   /// nav stack via `pushTemplate(CPNowPlayingTemplate.shared, ...)`
   /// is the supported path for `com.apple.developer.carplay-audio`
   /// apps; embedding the same template in a `CPTabBarTemplate` root
-  /// is NOT — that raises `NSInvalidArgumentException`. Property
-  /// mutation here is intentionally avoided — earlier iOS 26 sim
-  /// experiments setting `isUpNextButtonEnabled = false` /
-  /// `isAlbumArtistButtonEnabled = false` left the template rendering
-  /// blank; baseline defaults work.
+  /// is NOT — that raises `NSInvalidArgumentException`.
+  ///
+  /// Registers self as a `CPNowPlayingTemplateObserver` so the Up Next
+  /// button tap routes into [nowPlayingTemplateUpNextButtonTapped].
+  /// Enables only the Up Next flag + title (when the mirrored queue is
+  /// non-empty); every other Now Playing button keeps baseline defaults.
   private func configureNowPlayingTemplate() {
-    _ = CPNowPlayingTemplate.shared
-    NSLog("[RNQP-CarPlay] CPNowPlayingTemplate.shared touched")
+    CPNowPlayingTemplate.shared.add(self)
+    refreshUpNextButton()
+    NSLog("[RNQP-CarPlay] CPNowPlayingTemplate.shared configured")
+  }
+
+  /// Enable the Up Next button when the mirrored queue has entries.
+  /// Re-run from the queue-mirror observer so the button reflects the
+  /// live queue.
+  private func refreshUpNextButton() {
+    let hasQueue = !(
+      CarPlayCoordinator.shared.queueProvider.getSnapshot()?.entries.isEmpty ?? true
+    )
+    CPNowPlayingTemplate.shared.isUpNextButtonEnabled = hasQueue
+    CPNowPlayingTemplate.shared.upNextTitle = upNextTitle
+  }
+
+  private var upNextTitle: String {
+    NSLocalizedString("Up Next", comment: "CarPlay queue button title")
   }
 
 }
+
+// MARK: - CPNowPlayingTemplateObserver
+
+@available(iOS 14.0, *)
+extension CarPlaySceneDelegate: CPNowPlayingTemplateObserver {
+
+  /// Build the Up Next list from the mirrored queue snapshot and push
+  /// it. Each row taps back to Now Playing after routing the skip
+  /// through the coordinator's `skipToIndexHandler`, which `TrackPlayer`
+  /// registers. No-op when no queue is mirrored yet.
+  func nowPlayingTemplateUpNextButtonTapped(
+    _ nowPlayingTemplate: CPNowPlayingTemplate
+  ) {
+    guard let controller = interfaceController else { return }
+    // Only push from the Now Playing surface — guards against a
+    // spurious double-push if the tap re-fires while the list is up.
+    guard controller.topTemplate === CPNowPlayingTemplate.shared else { return }
+    guard let snapshot = CarPlayCoordinator.shared.queueProvider.getSnapshot(),
+          !snapshot.entries.isEmpty else {
+      return
+    }
+    let list = queueBuilder.buildQueueTemplate(
+      snapshot: snapshot,
+      loader: CarPlayCoordinator.shared.loader,
+      skip: { [weak self] index in
+        CarPlayCoordinator.shared.skipToIndexHandler?(index)
+        // Return to Now Playing — pop the Up Next list off the nav
+        // stack; the Now Playing surface is already beneath it.
+        self?.interfaceController?.popTemplate(animated: true) { _, _ in }
+      }
+    )
+    controller.pushTemplate(list, animated: true) { _, _ in }
+  }
+}

package/ios/CrossfadeEngine.swift

@@ -32,11 +32,10 @@ import Foundation
 ///   hard-cuts (no fade) for that transition. Mid-fade route
 ///   change cancels the fade synchronously.
 ///
-/// Runtime fade execution (multi-second `setVolumeRamp` schedule
-/// + standby promotion to leading at fade-end) is exercised at
-/// the demo-app integration layer; the engine's deterministic
-/// primitives (curve math, sub-ramp count, route classification,
-/// boundary fade-vs-cut decision) are unit-tested.
+/// Runtime fade execution is a multi-second `setVolumeRamp` schedule
+/// plus standby promotion to leading at fade-end, built on
+/// deterministic primitives (curve math, sub-ramp count, route
+/// classification, boundary fade-vs-cut decision).
 final class CrossfadeEngine: PlaybackEngine {
 
   // MARK: - Construction

package/ios/InputGuards.swift

@@ -16,9 +16,9 @@ import Foundation
 ///    the public API surface (matches the documented contract +
 ///    Android parity).
 ///
-/// Helpers live here as pure functions so they can be exercised by
-/// XCTest without instantiating a `TrackPlayer` (which depends on
-/// AVQueuePlayer + AVAudioSession + Nitrogen-generated types).
+/// Helpers live here as pure functions, decoupled from `TrackPlayer`
+/// (which depends on AVQueuePlayer + AVAudioSession + Nitrogen-generated
+/// types).
 ///
 /// Gated behind `@_spi(QueuePlayerTests)` so the helpers stay off
 /// the library's consumer-facing public surface — same SPI scope

package/ios/LookaheadCache.swift

@@ -810,13 +810,11 @@ public enum LookaheadCacheError: Error {
 }
 
 /// Abstraction over `LookaheadCache.download` so the prefetcher
-/// can be unit-tested with a stub conformer that records
-/// invocations without touching `URLSession`. Production code uses
-/// `LookaheadCache` itself (which conforms below).
+/// can accept an alternate conformer without touching `URLSession`.
+/// Production code uses `LookaheadCache` itself (which conforms below).
 ///
-/// Gated behind `@_spi(QueuePlayerTests)` — only consumer is the
-/// test stub. Production callers reach `LookaheadCache` directly
-/// via `LookaheadCachePrefetcher.init(cache:)`.
+/// Gated behind `@_spi(QueuePlayerTests)`. Production callers reach
+/// `LookaheadCache` directly via `LookaheadCachePrefetcher.init(cache:)`.
 @_spi(QueuePlayerTests)
 public protocol LookaheadCacheDownloader: AnyObject {
   func download(track: TrackItem, headers: [String: String]?) async throws

package/ios/LookaheadCachePrefetcher.swift

@@ -148,7 +148,7 @@ public final class LookaheadCachePrefetcher {
   }
 
   /// SPI initializer — accepts any `LookaheadCacheDownloader`
-  /// conformer so XCTest targets can inject a stub. Off the
+  /// conformer so callers can inject an alternate. Off the
   /// consumer-facing surface; production calls reach the concrete
   /// `LookaheadCache`-typed init above.
   @_spi(QueuePlayerTests)

package/ios/MilestoneTracker.swift

@@ -1,6 +1,5 @@
 /// Tracks fixed playback-progress milestones (25/50/75/90%) for the
-/// current track playthrough. Pure + deterministic (no AVFoundation), so
-/// it unit-tests directly.
+/// current track playthrough. Pure + deterministic (no AVFoundation).
 ///
 /// A threshold emits only when forward playback crosses it: `seek` moves
 /// the baseline WITHOUT emitting (so thresholds a seek jumps over are

package/ios/PlaybackErrorMapping.swift

@@ -77,24 +77,23 @@ public enum PlaybackErrorMapping {
     return result
   }
 
-  // MARK: - Test-friendly "Raw" surface
+  // MARK: - String-based "Raw" surface
   //
   // NOTES.md §6: Swift's `-cxx-interoperability-mode=default` hides
   // members of functions whose signatures touch Nitrogen-generated
   // C++-backed types when viewed from a different Swift module.
   // `classify` / `isTransient` reference `PlaybackErrorCode` — a
-  // Nitrogen type — so XCTest can't reach them directly. Provide a
-  // parallel surface that takes/returns Strings (the enum's
-  // stringValue) for unit-test access. Production code uses the
-  // typed surface above; tests use the Raw surface.
+  // Nitrogen type — so a different module can't reach them directly.
+  // This parallel surface takes/returns Strings (the enum's
+  // stringValue). Production code uses the typed surface above.
 
-  /// Test-only string-returning variant of `classify`.
+  /// String-returning variant of `classify`.
   @_spi(QueuePlayerTests)
   public static func classifyRaw(_ underlying: NSError?) -> String {
     return classify(underlying).stringValue
   }
 
-  /// Test-only string-input variant of `isTransient`.
+  /// String-input variant of `isTransient`.
   @_spi(QueuePlayerTests)
   public static func isTransientRaw(_ codeString: String) -> Bool {
     guard let code = PlaybackErrorCode(fromString: codeString) else { return false }

package/ios/PlayerStateDerivation.swift

@@ -4,8 +4,7 @@ import AVFoundation
 /// status. Shared by BOTH engines (gapless + crossfade) via
 /// `PlaybackEngine.timeControlStatus`, so the two report identical states for
 /// identical situations — no per-engine special-casing for consumers. Mirrors
-/// Android's `TransportStateTranslator`; pure + deterministic, so it unit-tests
-/// directly.
+/// Android's `TransportStateTranslator`; pure + deterministic.
 ///
 /// iOS has no native "ended" player state (unlike Android's `STATE_ENDED`), so
 /// `reachedQueueEnd` is a latch that `TrackPlayer` sets when the queue drains

package/ios/ProgressEmissionGate.swift

@@ -1,6 +1,6 @@
 /// Throttles the JS `onProgress` fan-out to a configurable cadence, with an
 /// optional reduced rate while the app is backgrounded. Pure + deterministic
-/// (the caller supplies a monotonic timestamp), so it unit-tests directly.
+/// (the caller supplies a monotonic timestamp).
 ///
 /// This gates ONLY the JS emission — the native 2 Hz sampler keeps running, so
 /// milestone detection and buffer-state recomputation stay full-rate. A tick

package/ios/QueueMutationArithmetic.swift

@@ -1,10 +1,10 @@
 import Foundation
 
 /// Pure-Swift index-shift arithmetic for queue mutations. Extracted
-/// from `TrackPlayer.swift` so the shift semantics are unit-testable
+/// from `TrackPlayer.swift` so the shift semantics stand alone,
 /// without an AVQueuePlayer. Mirrors
 /// `android/.../QueueMutationArithmetic.kt` 1:1 — same function
-/// shapes, same input/output semantics, same test matrix.
+/// shapes, same input/output semantics.
 ///
 /// The helper only computes the new `currentTrackIndex` and (for
 /// `removeFromQueue`) which original indices apply after dedup /

package/ios/QueueSkipArithmetic.swift

@@ -1,23 +1,19 @@
 /// Pure-Swift skip-index arithmetic. Extracted from `TrackPlayer.swift`
-/// so the logic can be unit-tested without crossing the Swift ↔ C++
-/// interop boundary — Nitrogen-generated types (`TrackItem`, `RepeatMode`)
-/// don't export their members to importing modules under Swift's current
-/// `-cxx-interoperability-mode=default` settings, which makes `@testable
-/// import QueuePlayer` useless for touching anything that reads Nitro
-/// types. By taking primitive arguments, these helpers stay reachable
-/// from the XCTest bundle via plain `import QueuePlayer`.
+/// so the logic stays clear of the Swift ↔ C++ interop boundary —
+/// Nitrogen-generated types (`TrackItem`, `RepeatMode`) don't export
+/// their members to importing modules under Swift's current
+/// `-cxx-interoperability-mode=default` settings. These helpers take
+/// primitive arguments instead.
 ///
 /// `TrackPlayer.computeNextIndex` / `.computePreviousIndex` instance
 /// methods are thin adapters that map the Nitrogen `RepeatMode` enum
 /// onto `QueueSkipRepeatMode` and call through here.
 
 /// Repeat-mode enum expressed in plain Swift. Value order (0/1/2)
-/// matches `RepeatModeKind` in the nitro.ts spec, so a test that
-/// asserts the raw integer is robust against accidental reordering
-/// in the Nitrogen spec.
+/// matches `RepeatModeKind` in the nitro.ts spec.
 ///
-/// Gated behind `@_spi(QueuePlayerTests)` so the XCTest-only helper
-/// surface stays off the library's consumer-facing API.
+/// Gated behind `@_spi(QueuePlayerTests)` so the helper surface stays
+/// off the library's consumer-facing API.
 @_spi(QueuePlayerTests)
 public enum QueueSkipRepeatMode: Int {
   case off = 0

package/ios/Siri/PlayMediaIntentHandler.swift

@@ -189,11 +189,7 @@ internal final class PlayMediaIntentHandler: NSObject, INPlayMediaIntentHandling
   /// Map `INPlayMediaIntent.mediaSearch` into the lib's
   /// `MediaSearchRequest` shape so the consumer's JS resolver sees
   /// the same wire format regardless of voice surface (SiriKit on
-  /// iOS, Google Assistant on Android). Coverage lives at the
-  /// Maestro integration layer (`e2e/manual/siri-cold-start.md`
-  /// S1–S5) — the return type's cxx-interop bridging blocks
-  /// `@testable import` from constructing or comparing
-  /// `MediaSearchRequest` values in XCTest.
+  /// iOS, Google Assistant on Android).
   static func buildRequest(from intent: INPlayMediaIntent) -> MediaSearchRequest {
     let mediaSearch = intent.mediaSearch
     let mediaName = mediaSearch?.mediaName ?? ""

package/ios/SleepTimerCore.swift

@@ -1,7 +1,7 @@
 import Foundation
 
 /// Pure state machine for the sleep timer — no player, volume, or timer
-/// dependencies, so it is unit-testable in isolation. The owning `TrackPlayer`
+/// dependencies, so it stands alone. The owning `TrackPlayer`
 /// drives it from a repeating native timer and applies the returned decision
 /// (volume fade, pause) to the engine.
 ///