react-native-queue-player 1.0.2 → 1.0.4

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

@@ -19,8 +19,7 @@ import kotlin.math.sin
  * Unit coverage for [FFTProcessorTee] — buffer ingestion across PCM
  * encodings, intervalMs throttling, includeSamples flag, and
  * multi-channel mixdown. The Tee callback contract is mocked
- * directly; integration with Media3's audio chain is verified at the
- * Maestro layer (no Robolectric harness for ExoPlayer audio output).
+ * directly.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -15,8 +15,6 @@ import org.robolectric.annotation.Config
 /**
  * Lifecycle smoke coverage for [GaplessEngine] — empty-state
  * sentinels and the idempotent / delegate-clearing release contract.
- * Behavioural coverage of transport / queue mutation runs through
- * the existing TrackPlayer integration suites + Maestro flows.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -19,10 +19,8 @@ import org.robolectric.annotation.Config
  * Real Media3 metadata dispatch is not emulated by Robolectric
  * without playback, so the listener body composes its work through
  * the engine-internal `handleReplayGainParse` helper which these
- * tests drive directly with synthetic [ReplayGainData]. The
- * pure-math piece of the pipeline is covered in [ReplayGainGainTest];
- * end-to-end propagation lands in the demo app's `replaygain`
- * Maestro suite. This file covers the no-data baseline,
+ * tests drive directly with synthetic [ReplayGainData].
+ * This file covers the no-data baseline,
  * mode-change-without-data behaviour, and the
  * `handleReplayGainParse` cache + recompute contract.
  */
@@ -147,8 +145,5 @@ class GaplessEngineReplayGainTest {
 
   // The cache-clear-on-transition path lives inline in the
   // `Player.Listener.onMediaItemTransition` body. Robolectric does not
-  // drive that callback without real playback, so the contract is
-  // covered at the integration layer by `RNQP-Demo/src/tests/suites/
-  // replaygain.ts` (steps `cross-track-active-updates` +
-  // `skip-next-mid-playback-resets-from-stale-cache`).
+  // drive that callback without real playback.
 }

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

@@ -21,11 +21,9 @@ import org.robolectric.annotation.Config
  * surface: the default no-task `getTaskConfig` contract and the
  * process-wide wake-lock helper.
  *
- * The full `onStartCommand` chain (which routes through Media3's
+ * The full `onStartCommand` chain routes through Media3's
  * `MediaLibraryService.onStartCommand` and into native code that
- * Robolectric can't satisfy) is exercised end-to-end by
- * [PlaybackServiceLifecycleTest] (which subclasses into the new
- * `HeadlessJsMediaService` base) plus the Maestro demo cycle.
+ * Robolectric can't satisfy, so it is out of scope here.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -26,11 +26,10 @@ import org.robolectric.annotation.Config
  *   both produce items — the file/remote routing difference is a
  *   DataSource.Factory concern, not a MediaItem concern).
  *
- * Factory-building is exercised by type only (the internal
+ * Factory-building is checked by type only (the internal
  * `DefaultHttpDataSource.Factory` is configured via a builder chain
  * whose effective state is hard to read back without reflection —
- * the factory is wired into ExoPlayer at construction time and
- * exercised implicitly through the TrackPlayer lifecycle tests).
+ * the factory is wired into ExoPlayer at construction time).
  *
  * @Config sdk=34 — Robolectric 4.11.1's max supported SDK.
  */

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

@@ -5,9 +5,7 @@ import org.junit.Test
 
 /**
  * Unit tests for [MilestoneTracker] — the pure 25/50/75/90% crossing
- * logic behind `onPlaybackMilestone`. Native wiring (progress tick,
- * seek, track-change reset) is covered by the `playback-milestones`
- * demo suite.
+ * logic behind `onPlaybackMilestone`.
  */
 class MilestoneTrackerTest {
 

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

@@ -7,8 +7,7 @@ import org.junit.Assert.assertEquals
 import org.junit.Test
 
 /**
- * Pure-mapping coverage for [NowPlayingFormatExtractor]. The full
- * `extract(player:)` path is exercised through demo suites; these
+ * Pure-mapping coverage for [NowPlayingFormatExtractor]. These
  * tests pin the codec / container tables so the JS-visible enum can't
  * drift without a test failure.
  */

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

@@ -17,7 +17,7 @@ import org.robolectric.annotation.Config
 /**
  * Routing coverage for [PitchAwareAudioProcessorChain]: which stretcher is
  * actually stretching for each [PitchCorrectionMode] and speed. The native
- * stretch itself is covered on-device; these assert only the mode gate, which
+ * stretch itself runs on-device; these assert only the mode gate, which
  * runs without the native library.
  *
  * Note Signalsmith is intentionally ALWAYS active on the float path (so Media3's

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

@@ -10,8 +10,8 @@ import org.robolectric.annotation.Config
  * Unit coverage for [PitchCorrection.playbackParameters], the pure mapping
  * from a [PitchCorrectionMode] + speed to Media3 [androidx.media3.common.PlaybackParameters].
  *
- * Engine wiring (which player the params land on) is covered by the
- * auto-suite `pitch-correction.ts` step.
+ * Engine wiring (which player the params land on) is out of scope for
+ * this pure test.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -111,6 +111,8 @@ class SleepTimerCoreTest {
     assertTrue(converted.stateChanged)
     assertFalse(t.isEndOfTrack)
     assertTrue(t.isActive)
+    // Deadline lands AT the boundary (tail=50s), not 1s past it.
+    assertEquals(2000L + 50_000L, t.deadlineEpochMs)
   }
 
   @Test
@@ -122,4 +124,43 @@ class SleepTimerCoreTest {
     assertNull(t.deadlineEpochMs)
     assertNull(t.remainingSeconds(0))
   }
+
+  @Test
+  fun `end-of-track fires a pause at the track-end signal`() {
+    val t = SleepTimerCore()
+    t.armEndOfTrack()
+    // Fires at the real track-end signal, before any tail conversion and even
+    // when the duration was never known (never ticked).
+    val fired = t.fireAtTrackEnd()
+    assertTrue(fired.pauseNow)
+    assertTrue(fired.stateChanged)
+    assertFalse(t.isActive)
+  }
+
+  @Test
+  fun `end-of-track signal fires after tail conversion`() {
+    val t = SleepTimerCore()
+    t.armEndOfTrack()
+    t.tick(1000, trackDurationSec = 200.0, trackPositionSec = 150.0) // converts to fade
+    val fired = t.fireAtTrackEnd()
+    assertTrue(fired.pauseNow)
+    assertFalse(t.isActive)
+  }
+
+  @Test
+  fun `fireAtTrackEnd is idempotent`() {
+    val t = SleepTimerCore()
+    t.armEndOfTrack()
+    t.fireAtTrackEnd()
+    assertFalse(t.fireAtTrackEnd().pauseNow)
+  }
+
+  @Test
+  fun `fireAtTrackEnd ignores a duration timer`() {
+    val t = SleepTimerCore()
+    t.armDuration(seconds = 60.0, nowMs = 0)
+    val fired = t.fireAtTrackEnd()
+    assertFalse(fired.pauseNow)
+    assertTrue(t.isActive)
+  }
 }

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

@@ -4,8 +4,7 @@ import AVFoundation
 /// to the AVAudioSession `Mode` + `CategoryOptions` used during
 /// `AudioSession.activate()`.
 ///
-/// Pure function; no instance state. Mirrors `PlaybackErrorMapping`
-/// + `InterruptionEventMapping`.
+/// Pure function; no instance state. Mirrors `PlaybackErrorMapping`.
 ///
 /// `audioContentType == .speech` triggers two effects:
 /// 1. AVAudioSession mode flips to `.spokenAudio` (per Apple HIG —

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