react-native-queue-player 1.0.3 → 1.0.4

package/android/src/main/java/com/margelo/nitro/queueplayer/BufferStateTranslator.kt

@@ -9,7 +9,7 @@ import androidx.media3.common.Player
  *
  * Extracted from [TrackPlayer.computeBufferState] so the discriminator
  * between an initial `BUFFERING` load and a mid-playback `STALLED`
- * rebuffer is unit-testable without a live ExoPlayer, matching the
+ * rebuffer stands alone without a live ExoPlayer, matching the
  * [TransportStateTranslator] pattern.
  */
 internal object BufferStateTranslator {

package/android/src/main/java/com/margelo/nitro/queueplayer/CarConnectionState.kt

@@ -0,0 +1,46 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.annotation.VisibleForTesting
+import java.util.concurrent.atomic.AtomicInteger
+
+/**
+ * Process-wide count of attached headless (automotive) controllers, backing
+ * the `isCarConnected()` getter. Holds the same "a car is connected" state
+ * the `onCarConnect` / `onCarDisconnect` events transition between, so a
+ * consumer that missed the connect event — because it fired before the
+ * consumer registered its handler in this process — can still gate car-only
+ * work (e.g. browse-snapshot pushes) on the current connection.
+ *
+ * The count is process-scoped rather than tied to a [PlaybackService]
+ * instance so it stays correct across a service restart while a controller
+ * remains attached: the new instance's `onConnect` and the dying instance's
+ * late `onConnect`/`onDisconnected` all mutate this single source of truth, so
+ * the getter can't momentarily read disconnected mid-handoff. It is
+ * floor-guarded so a stray disconnect can't drive it negative, and process
+ * death clears it (a fresh process starts disconnected), which is correct.
+ *
+ * Only [PlaybackServiceCallback] mutates this — at the same headless
+ * connect / disconnect points that drive the events. This count is separate
+ * from that callback's per-instance counter, which stays per-service so the
+ * events keep their per-session first/last edge semantics.
+ */
+internal object CarConnectionState {
+  private val count = AtomicInteger(0)
+
+  fun isConnected(): Boolean = count.get() > 0
+
+  /** A headless controller attached. */
+  fun retain() {
+    count.incrementAndGet()
+  }
+
+  /** A headless controller detached; never drops below zero. */
+  fun release() {
+    count.updateAndGet { if (it > 0) it - 1 else 0 }
+  }
+
+  @VisibleForTesting
+  fun reset() {
+    count.set(0)
+  }
+}

package/android/src/main/java/com/margelo/nitro/queueplayer/Equalizer.kt

@@ -25,9 +25,7 @@ import com.margelo.nitro.core.Promise
  * The JS-facing methods that mutate state return `Promise<Unit>`
  * via `Promise.async` per the spec, but each delegates to a
  * synchronous `*Internal` method that owns the actual mutation.
- * Unit tests target the synchronous core; the async wrapper is a
- * JS-interface adapter and is exercised at integration via demo
- * Maestro.
+ * The async wrapper is a thin JS-interface adapter.
  *
  * Listener registries follow the same shape as other event
  * listeners on this lib: stable numeric IDs returned via the

package/android/src/main/java/com/margelo/nitro/queueplayer/HeadlessJsMediaService.kt

@@ -141,8 +141,7 @@ public abstract class HeadlessJsMediaService :
   /**
    * The host's [ReactHost]. Returns `null` when the host
    * `Application` does not implement [ReactApplication] — production
-   * Expo / RN consumers always do; the null branch covers the
-   * Robolectric / unit-test path where the application is a stub.
+   * Expo / RN consumers always do.
    */
   protected val reactHost: ReactHost?
     get() = (application as? ReactApplication)?.reactHost
@@ -151,8 +150,7 @@ public abstract class HeadlessJsMediaService :
    * The live [ReactContext] from the consumer app's [ReactHost], or
    * `null` when no context has been created yet (the service kicks
    * one off via [createReactContextAndScheduleTask] in that case) OR
-   * when the host application isn't a [ReactApplication] at all (e.g.
-   * unit-test stubs).
+   * when the host application isn't a [ReactApplication] at all.
    */
   protected val reactContext: ReactContext?
     get() = reactHost?.currentReactContext

package/android/src/main/java/com/margelo/nitro/queueplayer/LookaheadCacheWriter.kt

@@ -285,9 +285,8 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
    * cache state.
    *
    * `runCatching` swallows the "Method myLooper in android.os.Looper
-   * not mocked" exception that fires under plain-JUnit (the writer's
-   * pure-orchestration tests deliberately avoid Robolectric to stay
-   * fast); production reads the looper normally.
+   * not mocked" exception that fires on a JVM host without the Android
+   * framework present; production reads the looper normally.
    */
   private fun requireMainThread() {
     val onMain = runCatching {
@@ -429,12 +428,11 @@ class LookaheadCacheWriter @VisibleForTesting internal constructor(
         // Errors (OutOfMemoryError etc.) propagate — those are
         // not transient and shouldn't be hidden.
         //
-        // Log via runCatching: android.util.Log is not stubbed in
-        // plain-JUnit test runs (the writer's pure-orchestration
-        // tests deliberately avoid Robolectric), so a Log.w call
-        // would throw "Method w in android.util.Log not mocked"
-        // and terminate the prefetch loop. Production reads this
-        // log normally; tests get a silent no-op.
+        // Log via runCatching: on a JVM host without the Android
+        // framework present, android.util.Log is not stubbed, so a
+        // Log.w call would throw "Method w in android.util.Log not
+        // mocked" and terminate the prefetch loop. Production reads
+        // this log normally.
         runCatching { Log.w(TAG, "Lookahead prefetch failed for ${track.url}: ${e.message}") }
       }
 

package/android/src/main/java/com/margelo/nitro/queueplayer/MilestoneTracker.kt

@@ -2,8 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Tracks fixed playback-progress milestones (25/50/75/90%) for the
- * current track playthrough. Pure + deterministic (no Media3), so it
- * unit-tests directly.
+ * current track playthrough. Pure + deterministic (no Media3).
  *
  * A threshold emits only when forward playback crosses it: [seek] moves
  * the baseline WITHOUT emitting (so thresholds a seek jumps over are

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackService.kt

@@ -150,8 +150,8 @@ class PlaybackService : HeadlessJsMediaService() {
      * [PendingIntentBuffer] TTL: ~3 s for bridge boot + ~17 s of
      * headroom for the consumer's network calls before the controller
      * surfaces "no results" and the user retries. The two platforms'
-     * cold-start windows are deliberately the same so the manual
-     * playbook reads identically on iPhone + Android.
+     * cold-start windows are deliberately kept the same so the
+     * behaviour is identical on iPhone + Android.
      */
     private const val HEADLESS_DISPATCH_TIMEOUT_MS = 20_000L
 
@@ -1455,10 +1455,9 @@ class PlaybackService : HeadlessJsMediaService() {
   override fun getTaskConfig(intent: Intent?): com.facebook.react.jstasks.HeadlessJsTaskConfig? {
     val action = intent?.action ?: return null
     if (action !in HEADLESS_WAKE_ACTIONS) return null
-    // Robolectric / non-ReactApplication hosts cannot spawn a JS
-    // task — short-circuit here so `Arguments.createMap()` never
-    // has to load the React native libs that aren't on the test
-    // classpath.
+    // Non-ReactApplication hosts cannot spawn a JS task —
+    // short-circuit here so `Arguments.createMap()` never has to load
+    // the React native libs such a host lacks.
     if ((application as? com.facebook.react.ReactApplication) == null) return null
     // Belt-and-braces: if a wake intent somehow lands while a React
     // context is already alive (foreground app, prior wake already

package/android/src/main/java/com/margelo/nitro/queueplayer/PlaybackServiceCallback.kt

@@ -73,7 +73,7 @@ internal class PlaybackServiceCallback(
      *  package (Android Auto, Wear OS, Google Assistant) connects.
      *  Production wires the React-context cold-start through here so
      *  "Hey Google, play …" works from a phone with the app killed.
-     *  Default no-op so unit-test setups without a service can fall
+     *  Default no-op so callers without a wired service fall
      *  through harmlessly. */
     fun onHeadlessControllerConnect(packageName: String) {}
 
@@ -287,6 +287,9 @@ internal class PlaybackServiceCallback(
   ): MediaSession.ConnectionResult {
     if (controller.packageName in HEADLESS_ELIGIBLE_PACKAGES) {
       val previousCount = headlessControllerCount.getAndIncrement()
+      // A headless controller is now attached — record it in the process-wide
+      // count the `isCarConnected()` getter reads.
+      CarConnectionState.retain()
       environment.onHeadlessControllerConnect(controller.packageName)
       // Fire onCarConnect only on the FIRST headless controller of
       // this service-lifetime session — subsequent connects (Wear
@@ -348,6 +351,10 @@ internal class PlaybackServiceCallback(
       } else if (previousCount > 0 && remaining == 0) {
         environment.onHeadlessControllerDisconnect()
       }
+      // Drop this controller from the process-wide connection count the
+      // `isCarConnected()` getter reads (floor-guarded against a stray
+      // disconnect, so it can't go negative).
+      CarConnectionState.release()
     }
     super.onDisconnected(session, controller)
   }

package/android/src/main/java/com/margelo/nitro/queueplayer/ProgressEmissionGate.kt

@@ -3,7 +3,7 @@ package com.margelo.nitro.queueplayer
 /**
  * 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/android/src/main/java/com/margelo/nitro/queueplayer/QueueMutationArithmetic.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure-Kotlin index-shift arithmetic for queue mutations. Extracted
- * from [TrackPlayer] so the shift semantics are unit-testable without
+ * from [TrackPlayer] so the shift semantics stand alone without
  * an ExoPlayer. Mirrors (and lightly supersedes) the inline math
  * inside iOS `TrackPlayer.swift`'s `addToQueueBody` /
  * `removeFromQueueBody` / `moveInQueueBody` — the iOS backlog carries

package/android/src/main/java/com/margelo/nitro/queueplayer/QueueSkipArithmetic.kt

@@ -4,7 +4,7 @@ package com.margelo.nitro.queueplayer
  * Pure-Kotlin skip-index arithmetic. Mirrors the iOS sibling
  * `ios/QueueSkipArithmetic.swift` 1-for-1.
  *
- * Extracted from [TrackPlayer] so the logic is unit-testable without
+ * Extracted from [TrackPlayer] so the logic stands alone without
  * instantiating an ExoPlayer. [TrackPlayer.computeNextIndex] /
  * [TrackPlayer.computePreviousIndex] are thin adapters that translate
  * the Nitrogen-generated [RepeatMode] enum into [QueueSkipRepeatMode]

package/android/src/main/java/com/margelo/nitro/queueplayer/RemoteCommandDeduper.kt

@@ -29,7 +29,7 @@ package com.margelo.nitro.queueplayer
  *
  * Bias is toward emitting: when in doubt, act rather than swallow a real press.
  *
- * Pure and time-injected ([nowUptimeMs] is passed in) so it unit-tests without an
+ * Pure and time-injected ([nowUptimeMs] is passed in), so it needs no
  * Android runtime. [shouldEmit] is `@Synchronized` so it is safe regardless of
  * which thread an emit site runs on (today they are all main-thread-confined).
  */

package/android/src/main/java/com/margelo/nitro/queueplayer/SleepTimerCore.kt

@@ -2,7 +2,7 @@ package com.margelo.nitro.queueplayer
 
 /**
  * Pure state machine for the sleep timer — no player, volume, or handler
- * dependencies, so it is unit-testable in isolation. The owning [TrackPlayer]
+ * dependencies, so it stands alone. The owning [TrackPlayer]
  * drives it from a repeating main-looper runnable and applies the returned
  * decision (volume fade, pause) to the engine.
  *

package/android/src/main/java/com/margelo/nitro/queueplayer/TrackPlayer.kt

@@ -46,10 +46,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   // --- Stored state
   //
   // Mirrors iOS TrackPlayer.swift's "Stored state" block. Field
-  // visibility is `internal` + `@VisibleForTesting` so Robolectric
-  // tests can observe lifecycle transitions without going through
-  // the JNI-backed Nitro Promise machinery (which does not load in
-  // the JVM unit-test runtime).
+  // visibility is `internal` + `@VisibleForTesting` so lifecycle
+  // transitions can be observed without going through the JNI-backed
+  // Nitro Promise machinery (which does not load on a plain JVM).
 
   /**
    * `true` after [configureInternal] has bound + configured the
@@ -158,8 +157,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private var lastEmittedFormatMediaItem: MediaItem? = null
 
   // The fields below are written on main (via `onMain` / `syncMain`
-  // from the Promise adapter path, or directly from Robolectric tests
-  // which run on main). They are read off-main by the synchronous
+  // from the Promise adapter path). They are read off-main by the synchronous
   // snapshot accessors — `getCurrentTrackIndex`, `getQueue` —
   // dispatched on the JS thread by Nitro. `@Volatile` gives the
   // read path a happens-before edge on the most recent main-thread
@@ -581,7 +579,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   private val progressEmissionGate = ProgressEmissionGate()
   // ProcessLifecycleOwner observer driving the gate's background state. Held in
   // a nullable field so a re-configureInternal without an intervening
-  // destroyInternal (Robolectric) is a no-op instead of leaking a second
+  // destroyInternal is a no-op instead of leaking a second
   // observer. Registered in configureInternal, removed in destroyInternal.
   private var progressLifecycleObserver: DefaultLifecycleObserver? = null
   private val errorListeners = ListenerRegistry<(PlaybackError) -> Unit>()
@@ -866,11 +864,10 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Lifecycle configure body. `internal` so Robolectric tests can
-   * exercise it without the Nitro Promise path. Callers MUST hop
-   * to the main thread first — ExoPlayer construction binds to the
-   * calling Looper. Production path goes through `onMain`; tests
-   * run on Robolectric's main-thread dispatcher.
+   * Lifecycle configure body. `internal`, bypassing the Nitro Promise
+   * path. Callers MUST hop to the main thread first — ExoPlayer
+   * construction binds to the calling Looper. Production path goes
+   * through `onMain`.
    *
    * Builds the ExoPlayer with a [MediaSource.Factory] that attaches
    * the config's HTTP headers + User-Agent on every network request.
@@ -879,9 +876,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
    * Per the universal auto-destroy contract every `configure()` call
    * tears the player down upstream so this body is purely
    * constructive — `player` is guaranteed null on entry from the
-   * production path. Robolectric tests that drive `configureInternal`
-   * directly are responsible for calling `destroyInternal` first
-   * between configures.
+   * production path. Any caller driving `configureInternal` directly
+   * must call `destroyInternal` first between configures.
    */
   @VisibleForTesting
   @MainThread
@@ -2442,9 +2438,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   /**
    * Main-thread body for [setPlaybackSpeed]. The engine applies the
    * active pitch-correction mode's pitch alongside the speed (voice/music
-   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`
-   * so Robolectric exercises the cast + speed-application logic rather than
-   * just bypassing through `ExoPlayer.playbackParameters`.
+   * preserve pitch; none lets it follow rate). Exposed `@VisibleForTesting`;
+   * centralizes the cast + speed-application logic rather than routing
+   * straight through `ExoPlayer.playbackParameters`.
    *
    * Diverges from iOS: on iOS `player.rate = Float(rate)` implicitly
    * starts playback when the player was paused. Android's
@@ -3032,6 +3028,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   override fun onCarDisconnect(callback: () -> Unit): () -> Unit =
     deferredRegister { it.registerOnCarDisconnect(callback) }
 
+  override fun isCarConnected(): Boolean = CarConnectionState.isConnected()
+
   override fun onServiceReady(
     callback: (reason: ServiceReadyReason) -> Unit
   ): () -> Unit = deferredRegister { it.registerOnServiceReady(callback) }
@@ -4157,11 +4155,9 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: stash a [TrackChangeReason] that the next
+   * Stash a [TrackChangeReason] that the next
    * [handleMediaItemTransition] with `REASON_SEEK` will consume.
-   * Production code reaches this field via `skipTo*Internal`
-   * bodies; the hook just lets Robolectric tests simulate the
-   * stash without driving a real skip + ExoPlayer seek.
+   * Production code reaches this field via `skipTo*Internal` bodies.
    */
   @VisibleForTesting
   internal fun setPendingTrackChangeReasonForTest(reason: TrackChangeReason?) {
@@ -4169,9 +4165,8 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
   }
 
   /**
-   * Test hook: reset the [lastReportedState] dedup edge so
-   * [emitStateIfChanged] tests can force an emit from an already-
-   * NONE state without going through a real Player.Listener fire.
+   * Reset the [lastReportedState] dedup edge, forcing [emitStateIfChanged]
+   * to emit from an already-NONE state without a real Player.Listener fire.
    */
   @VisibleForTesting
   internal fun resetLastReportedStateForTest() {
@@ -4250,8 +4245,7 @@ class TrackPlayer : HybridTrackPlayerSpec(), PlaybackEngineDelegate {
 
     /**
      * Decide which [ServiceReadyReason] (if any) to dispatch on a
-     * fresh service-bind. Pure function so the reason-decision logic
-     * is unit-testable without spinning up a service controller.
+     * fresh service-bind. Pure function — no service controller needed.
      *
      *  - First-ever bind ([prior] == null): [ServiceReadyReason.FIRST_BIND].
      *  - Bind against a different binder identity:

package/android/src/main/java/com/margelo/nitro/queueplayer/TransportStateTranslator.kt

@@ -7,8 +7,8 @@ import androidx.media3.common.Player
  * isPlaying, playWhenReady, playbackSuppressionReason, hasTracks,
  * currentTrackIndex)` tuple to the library's [PlayerState] enum.
  *
- * Extracted from [TrackPlayer.getStateInternal] so every branch is
- * unit-testable without a live ExoPlayer. Matches the pattern of
+ * Extracted from [TrackPlayer.getStateInternal] so every branch
+ * stands alone without a live ExoPlayer. Matches the pattern of
  * [QueueSkipArithmetic] + [QueueMutationArithmetic] — TrackPlayer
  * is a thin adapter that reads the live player's state and
  * delegates the translation here.

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

@@ -14,12 +14,9 @@ import java.lang.reflect.Field
 /**
  * Unit coverage for [AudioPipelineRenderersFactory] construction — it wraps a
  * caller-supplied [androidx.media3.common.audio.AudioProcessorChain] and leaves
- * the produced sink at 16-bit (float output off). The engines drive end-to-end exercise of
- * `buildAudioSink` via `ExoPlayer.Builder.build()` in
- * [GaplessEngineLifecycleTest] / [CrossfadeEngineLifecycleTest]; `buildAudioSink`
+ * the produced sink at 16-bit (float output off). `buildAudioSink`
  * itself is `protected` on [DefaultRenderersFactory] and cannot be called
- * outside the Media3 internal call path. Chain composition + order is covered by
- * [PitchAwareAudioProcessorChainTest].
+ * outside the Media3 internal call path.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -9,10 +9,7 @@ import org.junit.Test
 /**
  * Pure-Kotlin coverage for [BrowseCallbackRegistry]'s slot-replace
  * + dispose semantics. The Promise-typed callbacks are stored as
- * function references; tests use simple stand-in lambdas — actual
- * dispatch coverage lives at the integration layer
- * (`PlaybackServiceCallbackSearchTest` for the search dispatch
- * path; future Maestro flows for end-to-end Auto cold-wake).
+ * function references; tests use simple stand-in lambdas.
  */
 @UnstableApi
 class BrowseCallbackRegistryTest {

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

@@ -15,8 +15,7 @@ import org.robolectric.annotation.Config
 /**
  * Lifecycle + fade-math coverage for [CrossfadeEngine].
  *
- * Audible verification of the dual-player crossfade runs at the
- * Maestro / demo-app integration layer; this suite exercises:
+ * This suite exercises:
  * empty-state sentinels, role-swap arithmetic, equal-power gain
  * curve, duration-clamp formula, manual-skip cancellation,
  * release idempotence + delegate clearing.

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

@@ -24,9 +24,7 @@ import org.robolectric.annotation.Config
  * Media3 metadata dispatch is not emulated by Robolectric without
  * playback, so the listener body composes its work through the
  * engine-internal `handleReplayGainParse(isA, parsed)` helper which
- * these tests drive directly with synthetic [ReplayGainData]. The
- * pure-math piece is covered in [ReplayGainGainTest]; end-to-end
- * propagation lands in the demo app's `replaygain` Maestro suite.
+ * these tests drive directly with synthetic [ReplayGainData].
  * This file covers the no-data baseline + the per-leg
  * `handleReplayGainParse` cache + recompute contract.
  */
@@ -173,8 +171,6 @@ class CrossfadeEngineReplayGainTest {
 
   // The per-leg cache-clear-on-transition path lives inline in each
   // leg's `Player.Listener.onMediaItemTransition` body. Robolectric
-  // does not drive that callback without real playback; integration
-  // coverage is in `RNQP-Demo/src/tests/suites/replaygain.ts` (steps
-  // `cross-track-active-updates` +
-  // `skip-next-mid-playback-resets-from-stale-cache`).
+  // does not drive that callback without real playback, so it is out
+  // of scope here.
 }

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

@@ -13,8 +13,7 @@ import org.robolectric.annotation.Config
 /**
  * State-mirror coverage for [EqualizerEngine] on the API 28+ path.
  * Robolectric stubs the audio-effect subsystem at this SDK level so
- * `attach` exercises the construction path without throwing; the
- * audible effect is verified at integration via demo Maestro.
+ * `attach` exercises the construction path without throwing.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -16,9 +16,7 @@ import org.robolectric.annotation.Config
 /**
  * Wiring coverage for the `Equalizer` HybridObject — engine
  * selection, JS-facing surface routing through the synchronous
- * `*Internal` core, listener registry behaviour. The audible
- * effect is verified at the integration layer via demo Maestro
- * once the engine is hooked to ExoPlayer's audio session.
+ * `*Internal` core, listener registry behaviour.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [34])

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

@@ -13,9 +13,8 @@ import org.robolectric.annotation.Config
  * State-mirror coverage for [EqualizerLegacyEngine] on the API <28 path.
  * Robolectric's audio-effect shadow doesn't model the hardware-side
  * band centre frequencies + gain range; the band-mapping + dB↔mB
- * conversion are the test-reachable invariants. Real audible effect
- * verified at user-led API 26 emulator playbook (legacy API
- * behaviour varies per OEM).
+ * conversion are the invariants this covers. Legacy AudioEffect
+ * behaviour varies per OEM.
  */
 @RunWith(RobolectricTestRunner::class)
 @Config(sdk = [27])

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])