react-native-queue-player 1.0.3 → 1.0.4

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

@@ -70,6 +70,9 @@ class PlaybackServiceCallbackTest {
     controllerInfo = MediaSession.ControllerInfo.createTestOnlyControllerInfo(
       "test-controller", 0, 0, 0, 0, false, android.os.Bundle.EMPTY, false
     )
+    // Process-wide count; reset so headless connect/disconnect assertions
+    // start from a known-disconnected state regardless of test order.
+    CarConnectionState.reset()
   }
 
   @After
@@ -87,8 +90,7 @@ class PlaybackServiceCallbackTest {
 
   // Controller-driven `Player.Command` interception (skip-next /
   // skip-previous veto, transport `system`-reason stamping) now lives
-  // on [SessionCommandForwardingPlayer]; its routing is covered in
-  // SessionCommandForwardingPlayerTest. This suite keeps the
+  // on [SessionCommandForwardingPlayer]. This suite keeps the
   // callback's connect / resumption / available-commands surface.
 
   @Test
@@ -270,9 +272,7 @@ class PlaybackServiceCallbackTest {
     // The per-controller iteration body (session.setAvailableCommands)
     // requires a live MediaController that has completed handshake,
     // which is not reachable from Robolectric without standing up a
-    // full MediaController.Builder.buildAsync() flow. End-to-end
-    // coverage of the lock-screen-greying behaviour lives in the
-    // Maestro suites for repeat-mode + queue-boundary scenarios.
+    // full MediaController.Builder.buildAsync() flow.
   }
 
   // --- TrackPlayer-side handler implementation
@@ -615,6 +615,76 @@ class PlaybackServiceCallbackTest {
     assertEquals(0, fakeEnv.headlessConnectPackages.size)
   }
 
+  // --- isCarConnected: the process-wide flag TrackPlayer.isCarConnected() reads
+
+  @Test
+  fun `CarConnectionState is disconnected with no controller attached`() {
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `headless connect marks connected, last disconnect marks disconnected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    cb.onConnect(session, gearhead)
+    assertTrue("connected after the first headless controller", CarConnectionState.isConnected())
+    cb.onDisconnected(session, gearhead)
+    assertFalse("disconnected after the last controller drops", CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `stays connected while any headless controller remains`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    val wear = controllerFor("com.google.android.wearable.app")
+    cb.onConnect(session, gearhead)
+    cb.onConnect(session, wear)
+    cb.onDisconnected(session, gearhead)
+    assertTrue("still connected with one controller remaining", CarConnectionState.isConnected())
+    cb.onDisconnected(session, wear)
+    assertFalse("disconnected once the last controller drops", CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `non-headless controller leaves the flag disconnected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val phone = controllerFor("com.example.regular.app")
+    cb.onConnect(session, phone)
+    assertFalse(CarConnectionState.isConnected())
+    cb.onDisconnected(session, phone)
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `untracked headless disconnect does not mark connected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    // A stray disconnect for a controller that never connected (service-
+    // restart edge) must not mark connected; the count floors at zero.
+    cb.onDisconnected(session, gearhead)
+    assertFalse(CarConnectionState.isConnected())
+  }
+
+  @Test
+  fun `a stray disconnect floors the count so a later connect still reads connected`() {
+    val cb = PlaybackServiceCallback(RecordingEnvironment(service))
+    val gearhead = controllerFor("com.google.android.projection.gearhead")
+    cb.onConnect(session, gearhead)
+    cb.onDisconnected(session, gearhead)
+    // Extra (stray) disconnect: the count must floor at zero, not go negative.
+    cb.onDisconnected(session, gearhead)
+    assertFalse("disconnected after the real drop", CarConnectionState.isConnected())
+    // If the stray disconnect had driven the count to -1, this connect would
+    // land it back at 0 and read disconnected.
+    cb.onConnect(session, gearhead)
+    assertTrue("connected again after a fresh attach", CarConnectionState.isConnected())
+  }
+
+  private fun controllerFor(packageName: String): MediaSession.ControllerInfo =
+    MediaSession.ControllerInfo.createTestOnlyControllerInfo(
+      packageName, 0, 0, 0, 0, false, android.os.Bundle.EMPTY, false
+    )
+
   @Test
   fun `becoming-noisy receiver unregisters in onDestroy`() {
     val handler = RecordingHandler()
@@ -691,8 +761,7 @@ class PlaybackServiceCallbackTest {
 
     override fun getCachedSkipCapability(): SkipCapability = capability
 
-    // Raw-key paths are exercised in MediaButtonDispatchTest; this
-    // suite covers the controller-driven callback routing only.
+    // This suite covers the controller-driven callback routing only.
     override fun onMediaPlay() {}
     override fun onMediaPause() {}
     override fun onMediaTogglePlayPause() {}

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

@@ -6,9 +6,7 @@ import org.junit.Test
 
 /**
  * Unit tests for [ProgressEmissionGate] — the pure throttle behind the
- * configurable / background-reduced `onProgress` cadence. Native wiring (the
- * progress tick + the ProcessLifecycleOwner observer) is covered by
- * [TrackPlayerProgressThrottleTest] and the progress demo suites.
+ * configurable / background-reduced `onProgress` cadence.
  *
  * Most tests pass `samplerPeriodMs = 0.0` to exercise exact interval semantics;
  * the jitter + quantization tests pass the production `500` to verify the

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

@@ -348,8 +348,7 @@ class TrackPlayerEventsTest {
   //
   // The measured silence gap rides on onTrackChange's 4th arg only for a
   // natural gapless auto-advance. Every other transition carries `null`.
-  // The positive numeric value (a nanoTime delta) is a native measurement
-  // verified on-device by the `gapless-album` demo suite.
+  // The positive numeric value is a native nanoTime delta.
 
   @Test
   fun `handleMediaItemTransition PLAYLIST_CHANGED reports null transitionGapMs`() {

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

@@ -20,10 +20,8 @@ import org.robolectric.annotation.Config
  * ExoPlayer timeline synchronisation (`mediaItemCount`,
  * `currentMediaItemIndex` where applicable).
  *
- * Arithmetic edge cases are covered more exhaustively in
- * [QueueMutationArithmeticTest]; these tests focus on wiring
- * correctness — that the arithmetic result is actually applied
- * to both state structures in concert.
+ * These tests focus on wiring correctness — that the arithmetic
+ * result is actually applied to both state structures in concert.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -19,8 +19,7 @@ import org.robolectric.annotation.Config
  * `initHybrid()` → JNI which the Robolectric runtime doesn't load. This
  * file pins the default and the synchronous read path
  * ([TrackPlayer.getPitchCorrectionMode]) against the canonical state
- * field; end-to-end Promise dispatch + engine wiring is exercised through
- * the demo `pitch-correction` suite.
+ * field.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -9,9 +9,8 @@ import org.robolectric.annotation.Config
 
 /**
  * `setPlaybackMode` / `getPlaybackMode` imperative spec coverage —
- * the engine-swap path is exercised at the integration layer
- * (Maestro 1+1 cycle) since Robolectric can't fully bind the
- * service + ExoPlayer to verify a real swap.
+ * the engine-swap path can't be fully bound under Robolectric, which
+ * can't stand up the service + ExoPlayer to verify a real swap.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -20,9 +20,7 @@ import org.robolectric.annotation.Config
  * [ReplayGainConfig.setMode] then asks the active engine to
  * recompute; this file pins the synchronous read path
  * ([TrackPlayer.getReplayGainMode]) round-trips with
- * [ReplayGainConfig], and the mode write is itself covered by
- * [ReplayGainConfigTest]. End-to-end Promise dispatch is exercised
- * through the demo `replaygain` Maestro suite.
+ * [ReplayGainConfig].
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -39,4 +39,32 @@ final class CarPlayCoordinator {
     self.pending = PendingBrowseRequests()
     self.loader = ArtworkLoader()
   }
+
+  // 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/CarPlaySceneDelegate.swift

@@ -122,6 +122,7 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
       self?.refreshRootTemplate()
     }
 
+    coordinator.setCarConnected(true)
     coordinator.bridge.carConnectCallback()?()
   }
 
@@ -139,6 +140,7 @@ internal class CarPlaySceneDelegate: UIResponder, CPTemplateApplicationSceneDele
     }
     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

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.
 ///

package/ios/Tests/AudioTapProviderReplayGainTests.swift

@@ -3,19 +3,15 @@ import XCTest
 @testable import QueuePlayer
 
 /// Unit tests for the ReplayGain mode + gain-math paths in
-/// `AudioTapProvider`. The metadata-extraction async path + per-item
-/// recompute walk are covered at the integration layer (auto-suite
-/// `replaygain.ts` step). These tests drive the pure
+/// `AudioTapProvider`. These tests drive the pure
 /// `computeLinearGain(data:mode:)` static helper plus the mode
 /// getter/setter round-trip.
 final class AudioTapProviderReplayGainTests: XCTestCase {
 
-  // Mode getter / setter round-trip is exercised at the integration
-  // layer (`replaygain.ts` auto-suite) — `getReplayGainMode`'s
-  // `ReplayGainMode` return type touches the Swift↔C++ interop
-  // graph, so direct equality from `@testable` XCTest can't observe
-  // it (NOTES.md §6). The pure gain-math matrix below is the unit
-  // surface; mode propagation lands in the integration tests.
+  // `getReplayGainMode`'s `ReplayGainMode` return type touches the
+  // Swift↔C++ interop graph, so direct equality from `@testable`
+  // XCTest can't observe it (NOTES.md §6). The pure gain-math matrix
+  // below is the unit surface.
 
   // MARK: - computeLinearGain — strict mode + selection
 

package/ios/Tests/CarPlayBridgeTests.swift

@@ -2,9 +2,7 @@ import XCTest
 @testable import QueuePlayer
 
 /// `CarPlayBridge` tests cover only the registration/dispose/clear
-/// state machine. Promise-await dispatch is exercised by the
-/// production scene delegate + browse builder via integration paths;
-/// the unit suite stays focused on the slot semantics. The
+/// state machine — the slot semantics. The
 /// Android-side `BrowseCallbackRegistry` exposes suspending
 /// `await*Callback()` helpers because its dispatch sites coroutine-
 /// poll for cold-start race recovery; iOS uses NotificationCenter
@@ -18,9 +16,7 @@ final class CarPlayBridgeTests: XCTestCase {
     // The browse / playFromId slot reads return a Promise of a
     // Nitrogen-bridged type, which Swift cxx-interop excludes from
     // `@testable import`. Their slots use the identical `Slot<>`
-    // machinery asserted here for connect/disconnect, and their
-    // dispatch is covered at the integration layer (scene delegate +
-    // browse builder).
+    // machinery asserted here for connect/disconnect.
     XCTAssertNil(bridge.carConnectCallback())
     XCTAssertNil(bridge.carDisconnectCallback())
   }

package/ios/Tests/CarPlayBrowseBuilderTests.swift

@@ -5,8 +5,7 @@ import XCTest
 /// Coverage for [CarPlayBrowseBuilder] — snapshot → template
 /// conversion, item count + accessory mapping, pagination against
 /// `CPListTemplate.maximumItemCount`. Direct method calls on the
-/// builder; the scene delegate's full lifecycle is covered by the
-/// CarPlay Sim manual playbook.
+/// builder; the scene delegate's full lifecycle is out of scope here.
 final class CarPlayBrowseBuilderTests: XCTestCase {
 
   private func item(

package/ios/Tests/CarPlayCoordinatorTests.swift

@@ -0,0 +1,35 @@
+import XCTest
+@testable import QueuePlayer
+
+/// `CarPlayCoordinator` connection-flag tests. The flag is written by the
+/// CarPlay scene delegate at scene attach / detach; this suite locks the
+/// get/set contract the `isCarConnected()` getter reads back.
+final class CarPlayCoordinatorTests: XCTestCase {
+
+  override func setUp() {
+    super.setUp()
+    // Shared process-wide singleton — start from a known-disconnected state
+    // regardless of test order.
+    CarPlayCoordinator.shared.setCarConnected(false)
+  }
+
+  override func tearDown() {
+    // Shared process-wide singleton — leave it disconnected so it can't
+    // leak a connected state into another suite.
+    CarPlayCoordinator.shared.setCarConnected(false)
+    super.tearDown()
+  }
+
+  func testCarConnectedFlagReflectsSetter() {
+    let coordinator = CarPlayCoordinator.shared
+
+    coordinator.setCarConnected(false)
+    XCTAssertFalse(coordinator.isCarConnected, "disconnected after setCarConnected(false)")
+
+    coordinator.setCarConnected(true)
+    XCTAssertTrue(coordinator.isCarConnected, "connected after setCarConnected(true)")
+
+    coordinator.setCarConnected(false)
+    XCTAssertFalse(coordinator.isCarConnected, "disconnected again after setCarConnected(false)")
+  }
+}