react-native-queue-player 1.0.0

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

@@ -0,0 +1,185 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.C
+import androidx.media3.common.util.UnstableApi
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+import java.nio.ByteBuffer
+import java.nio.ByteOrder
+import kotlin.math.PI
+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).
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class FFTProcessorTeeTest {
+
+  private fun makeTee(
+    fftSize: Int = 256,
+    intervalMs: Int = 1,
+    includeSamples: Boolean = false,
+    onFrame: (FloatArray, FloatArray?, Int) -> Unit,
+  ): FFTProcessorTee = FFTProcessorTee(fftSize, intervalMs, includeSamples, onFrame)
+
+  private fun pcm16Buffer(samples: ShortArray): ByteBuffer {
+    val bb = ByteBuffer.allocate(samples.size * 2).order(ByteOrder.nativeOrder())
+    for (s in samples) bb.putShort(s)
+    bb.position(0)
+    return bb
+  }
+
+  @Test
+  fun `emits a frame once enough samples land`() {
+    var calls = 0
+    var lastSampleRate = 0
+    val tee = makeTee { _, _, sampleRate ->
+      calls++
+      lastSampleRate = sampleRate
+    }
+    tee.flush(48000, 1, C.ENCODING_PCM_16BIT)
+    val n = 256
+    val samples = ShortArray(n) { (Short.MAX_VALUE * sin(2.0 * PI * 8 * it / n)).toInt().toShort() }
+    tee.handleBuffer(pcm16Buffer(samples))
+    assertEquals(1, calls)
+    assertEquals(48000, lastSampleRate)
+  }
+
+  @Test
+  fun `does not emit until fftSize samples accumulate`() {
+    var calls = 0
+    val tee = makeTee(fftSize = 512) { _, _, _ -> calls++ }
+    tee.flush(44100, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(256) { 0 }))
+    assertEquals(0, calls) // halfway, no emit
+    tee.handleBuffer(pcm16Buffer(ShortArray(256) { 100 }))
+    assertEquals(1, calls)
+  }
+
+  @Test
+  fun `intervalMs throttles back-to-back emissions`() {
+    var calls = 0
+    val tee = makeTee(fftSize = 64, intervalMs = 1000) { _, _, _ -> calls++ }
+    tee.flush(48000, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(64) { 1 }))
+    tee.handleBuffer(pcm16Buffer(ShortArray(64) { 2 }))
+    assertEquals("only the first window past the interval should emit", 1, calls)
+  }
+
+  @Test
+  fun `includeSamples=false leaves samples null on the callback`() {
+    var capturedSamples: FloatArray? = null
+    var captured = false
+    val tee = makeTee(fftSize = 128, intervalMs = 1, includeSamples = false) { _, samples, _ ->
+      captured = true
+      capturedSamples = samples
+    }
+    tee.flush(44100, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(128) { 0 }))
+    assertTrue(captured)
+    assertNull(capturedSamples)
+  }
+
+  @Test
+  fun `includeSamples=true populates samples with fftSize floats`() {
+    var capturedSamples: FloatArray? = null
+    val tee = makeTee(fftSize = 128, intervalMs = 1, includeSamples = true) { _, samples, _ ->
+      capturedSamples = samples
+    }
+    tee.flush(44100, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(128) { 1000 }))
+    assertNotNull(capturedSamples)
+    assertEquals(128, capturedSamples!!.size)
+  }
+
+  @Test
+  fun `stereo input mixes to mono via average`() {
+    var capturedSamples: FloatArray? = null
+    val tee = makeTee(fftSize = 64, intervalMs = 1, includeSamples = true) { _, samples, _ ->
+      capturedSamples = samples
+    }
+    tee.flush(44100, 2, C.ENCODING_PCM_16BIT)
+    // Interleaved L/R: [+max, -max, +max, -max, …] → mono mix → 0.
+    val interleaved = ShortArray(128)
+    for (i in 0 until 64) {
+      interleaved[i * 2] = Short.MAX_VALUE
+      interleaved[i * 2 + 1] = (-Short.MAX_VALUE.toInt()).toShort()
+    }
+    tee.handleBuffer(pcm16Buffer(interleaved))
+    assertNotNull(capturedSamples)
+    for (s in capturedSamples!!) {
+      assertTrue("mono mix of ±max should sum to ~0 (got $s)", kotlin.math.abs(s) < 0.01f)
+    }
+  }
+
+  @Test
+  fun `flush resets ring write index across stream changes`() {
+    var calls = 0
+    val tee = makeTee(fftSize = 128, intervalMs = 1) { _, _, _ -> calls++ }
+    tee.flush(44100, 1, C.ENCODING_PCM_16BIT)
+    tee.handleBuffer(pcm16Buffer(ShortArray(64) { 0 })) // half-fill
+    assertEquals(0, calls)
+    tee.flush(48000, 1, C.ENCODING_PCM_16BIT) // new stream
+    tee.handleBuffer(pcm16Buffer(ShortArray(64) { 0 })) // still half-fill on new stream
+    assertEquals("ring should reset; partial pre-flush data must not contribute", 0, calls)
+    tee.handleBuffer(pcm16Buffer(ShortArray(64) { 0 }))
+    assertEquals(1, calls)
+  }
+
+  @Test
+  fun `non-power-of-two fftSize is rejected at construction`() {
+    try {
+      makeTee(fftSize = 100) { _, _, _ -> }
+      throw AssertionError("expected IllegalArgumentException")
+    } catch (e: IllegalArgumentException) {
+      assertTrue(e.message?.contains("power of two") == true)
+    }
+  }
+
+  @Test
+  fun `24-bit packed PCM decodes to plausible Float32 range`() {
+    var capturedSamples: FloatArray? = null
+    val tee = makeTee(fftSize = 64, intervalMs = 1, includeSamples = true) { _, samples, _ ->
+      capturedSamples = samples
+    }
+    tee.flush(48000, 1, C.ENCODING_PCM_24BIT)
+    // Build a buffer of 64 mono frames at +half-scale (0x400000 little-endian).
+    val frames = 64
+    val bb = ByteBuffer.allocate(frames * 3).order(ByteOrder.nativeOrder())
+    repeat(frames) {
+      bb.put(0x00.toByte())
+      bb.put(0x00.toByte())
+      bb.put(0x40.toByte()) // 0x400000 = 2^22 = +half-scale
+    }
+    bb.position(0)
+    tee.handleBuffer(bb)
+    assertNotNull(capturedSamples)
+    for (s in capturedSamples!!) {
+      assertEquals("expected ~0.5 from +half-scale 24-bit input", 0.5f, s, 0.01f)
+    }
+  }
+
+  @Test
+  fun `does not mutate the source ByteBuffer's position or byte order`() {
+    val tee = makeTee(fftSize = 64, intervalMs = 1, includeSamples = false) { _, _, _ -> }
+    tee.flush(44100, 1, C.ENCODING_PCM_16BIT)
+    val original = pcm16Buffer(ShortArray(64) { 0 })
+    val expectedOrder = original.order()
+    val expectedPosition = original.position()
+    tee.handleBuffer(original)
+    assertEquals(expectedPosition, original.position())
+    assertEquals(expectedOrder, original.order())
+  }
+}

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

@@ -0,0 +1,112 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.datasource.cache.Cache
+import androidx.media3.datasource.cache.CacheSpan
+import androidx.media3.datasource.cache.ContentMetadata
+import androidx.media3.datasource.cache.ContentMetadataMutations
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Test
+import java.io.File
+
+/**
+ * Unit tests for [FifoCacheEvictor]'s eviction ordering. Drives the evictor's
+ * [CacheEvictor] callbacks directly against a minimal fake [Cache] whose only
+ * live method is `removeSpan` (delegates back to `onSpanRemoved`), so the tests
+ * assert insertion-order eviction without a real SimpleCache or filesystem.
+ */
+@UnstableApi
+class FifoCacheEvictorTest {
+
+  private val removed = mutableListOf<CacheSpan>()
+
+  private fun span(key: String, position: Long = 0, length: Long): CacheSpan =
+    CacheSpan(key, position, length, 0L, File("/tmp/$key-$position"))
+
+  @Test
+  fun `requiresCacheSpanTouches is false so reads never fire touches`() {
+    assertFalse(FifoCacheEvictor(1000).requiresCacheSpanTouches())
+  }
+
+  @Test
+  fun `evicts the oldest-inserted resource first`() {
+    val evictor = FifoCacheEvictor(maxBytes = 250)
+    val cache = FakeCache(evictor)
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanAdded(cache, span("c", length = 100)) // 300 > 250 → drop oldest
+    assertEquals(listOf("a"), removed.map { it.key })
+  }
+
+  @Test
+  fun `a whole track evicts together — spans of one url share insertion order`() {
+    val evictor = FifoCacheEvictor(maxBytes = 200)
+    val cache = FakeCache(evictor)
+    evictor.onSpanAdded(cache, span("a", position = 0, length = 50))
+    evictor.onSpanAdded(cache, span("a", position = 50, length = 50))
+    evictor.onSpanAdded(cache, span("b", length = 100))
+    evictor.onSpanAdded(cache, span("c", length = 100)) // 300 > 200 → both of a's spans drop first
+    assertEquals(listOf("a", "a"), removed.take(2).map { it.key })
+  }
+
+  @Test
+  fun `access order is ignored — a touched-newest but inserted-first track still evicts first`() {
+    // FIFO keys on insertion, not lastTouchTimestamp: the span with the newest
+    // touch but the oldest insertion is still the first victim.
+    val evictor = FifoCacheEvictor(maxBytes = 150)
+    val cache = FakeCache(evictor)
+    evictor.onSpanAdded(cache, CacheSpan("first", 0, 100, 9_999L, File("/tmp/first")))
+    evictor.onSpanAdded(cache, CacheSpan("second", 0, 100, 1L, File("/tmp/second"))) // 200 > 150
+    assertEquals(listOf("first"), removed.map { it.key })
+  }
+
+  @Test
+  fun `a re-added url gets a fresh newest order after its last span was evicted`() {
+    val evictor = FifoCacheEvictor(maxBytes = 150)
+    val cache = FakeCache(evictor)
+    evictor.onSpanAdded(cache, span("a", length = 100))
+    evictor.onSpanAdded(cache, span("b", length = 100)) // evicts a (its last span → key forgotten)
+    removed.clear()
+    evictor.onSpanAdded(cache, span("a", length = 100)) // a re-inserted as newest → b evicts, not a
+    assertEquals(listOf("b"), removed.map { it.key })
+  }
+
+  /** Minimal [Cache]: only `removeSpan` is live (records + calls back the evictor). */
+  private inner class FakeCache(private val evictor: FifoCacheEvictor) : Cache {
+    override fun removeSpan(span: CacheSpan) {
+      removed.add(span)
+      evictor.onSpanRemoved(this, span)
+    }
+
+    override fun getUid(): Long = throw UnsupportedOperationException()
+    override fun release() = throw UnsupportedOperationException()
+    override fun addListener(key: String, listener: Cache.Listener): java.util.NavigableSet<CacheSpan> =
+      throw UnsupportedOperationException()
+    override fun removeListener(key: String, listener: Cache.Listener) =
+      throw UnsupportedOperationException()
+    override fun getCachedSpans(key: String): java.util.NavigableSet<CacheSpan> =
+      throw UnsupportedOperationException()
+    override fun getKeys(): MutableSet<String> = throw UnsupportedOperationException()
+    override fun getCacheSpace(): Long = throw UnsupportedOperationException()
+    override fun startReadWrite(key: String, position: Long, length: Long): CacheSpan =
+      throw UnsupportedOperationException()
+    override fun startReadWriteNonBlocking(key: String, position: Long, length: Long): CacheSpan =
+      throw UnsupportedOperationException()
+    override fun startFile(key: String, position: Long, length: Long): File =
+      throw UnsupportedOperationException()
+    override fun commitFile(file: File, length: Long) = throw UnsupportedOperationException()
+    override fun releaseHoleSpan(holeSpan: CacheSpan) = throw UnsupportedOperationException()
+    override fun removeResource(key: String) = throw UnsupportedOperationException()
+    override fun isCached(key: String, position: Long, length: Long): Boolean =
+      throw UnsupportedOperationException()
+    override fun getCachedLength(key: String, position: Long, length: Long): Long =
+      throw UnsupportedOperationException()
+    override fun getCachedBytes(key: String, position: Long, length: Long): Long =
+      throw UnsupportedOperationException()
+    override fun applyContentMetadataMutations(key: String, mutations: ContentMetadataMutations) =
+      throw UnsupportedOperationException()
+    override fun getContentMetadata(key: String): ContentMetadata =
+      throw UnsupportedOperationException()
+  }
+}

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

@@ -0,0 +1,21 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.ForwardingSimpleBasePlayer
+import androidx.media3.common.Player
+import androidx.media3.common.util.UnstableApi
+
+/**
+ * Reads the delegate a [ForwardingSimpleBasePlayer] currently wraps.
+ *
+ * `getPlayer()` is `protected final` on the Media3 base class — the
+ * production code swaps the delegate via `retarget(...)` while the
+ * bound session keeps the stable wrapper identity, so tests assert the
+ * post-swap engine/cast player by reading it back here. Test-only
+ * reflection; no production accessor is added.
+ */
+internal val ForwardingSimpleBasePlayer.wrappedPlayer: Player
+  @UnstableApi
+  get() = ForwardingSimpleBasePlayer::class.java
+    .getDeclaredMethod("getPlayer")
+    .apply { isAccessible = true }
+    .invoke(this) as Player

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

@@ -0,0 +1,65 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+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])
+@UnstableApi
+class GaplessEngineLifecycleTest {
+
+  private fun makeEngine(): GaplessEngine = GaplessEngine(
+    context = ApplicationProvider.getApplicationContext(),
+  )
+
+  @Test
+  fun `empty queue returns the documented sentinel state`() {
+    val engine = makeEngine()
+    assertEquals(-1, engine.currentMediaItemIndex)
+    assertFalse(engine.isPlaying)
+    assertNull(engine.currentMediaItem)
+    assertTrue(engine.allMediaItems.isEmpty())
+  }
+
+  @Test
+  fun `release is idempotent and clears the delegate`() {
+    val engine = makeEngine()
+    val delegate = object : PlaybackEngineDelegate {
+      override fun onStateMaybeChanged(engine: PlaybackEngine, playWhenReadyReason: Int?) = Unit
+      override fun onIsPlayingChanged(engine: PlaybackEngine, isPlaying: Boolean) = Unit
+      override fun onTrackTransition(engine: PlaybackEngine, platformReason: Int) = Unit
+      override fun onActiveItemFormatChanged(engine: PlaybackEngine) = Unit
+      override fun onError(
+        engine: PlaybackEngine,
+        exception: androidx.media3.common.PlaybackException,
+      ) = Unit
+      override fun onPlaybackEnded(engine: PlaybackEngine) = Unit
+      override fun onAutoTransitionDiscontinuity(engine: PlaybackEngine) = Unit
+      override fun onCrossfadeBegin(engine: PlaybackEngine, incomingIndex: Int) = Unit
+      override fun onCrossfadeCancel(engine: PlaybackEngine, revertedIndex: Int) = Unit
+    }
+    engine.delegate = delegate
+    assertNotNull(engine.delegate)
+
+    engine.release()
+    assertNull(engine.delegate)
+
+    engine.release()
+    assertNull(engine.delegate)
+  }
+}

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

@@ -0,0 +1,154 @@
+package com.margelo.nitro.queueplayer
+
+import androidx.media3.common.util.UnstableApi
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Engine-level coverage for the ReplayGain wiring on [GaplessEngine].
+ *
+ * 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,
+ * mode-change-without-data behaviour, and the
+ * `handleReplayGainParse` cache + recompute contract.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class GaplessEngineReplayGainTest {
+
+  @After
+  fun tearDown() {
+    // Each test mutates the process-wide ReplayGainConfig; reset it
+    // so subsequent tests in the same JVM aren't dependent on order.
+    ReplayGainConfig.setMode(ReplayGainMode.OFF)
+  }
+
+  private fun makeEngine(): GaplessEngine = GaplessEngine(
+    context = ApplicationProvider.getApplicationContext(),
+  )
+
+  @Test
+  fun `fresh engine reports no replay-gain data and inactive`() {
+    val engine = makeEngine()
+    assertNull(engine.currentReplayGainData())
+    assertFalse(engine.currentReplayGainActive())
+    engine.release()
+  }
+
+  @Test
+  fun `recompute with no cached data does not crash and leaves engine inactive`() {
+    val engine = makeEngine()
+
+    ReplayGainConfig.setMode(ReplayGainMode.TRACK)
+    engine.recomputeReplayGainFromConfig()
+    assertFalse(engine.currentReplayGainActive())
+
+    ReplayGainConfig.setMode(ReplayGainMode.ALBUM)
+    engine.recomputeReplayGainFromConfig()
+    assertFalse(engine.currentReplayGainActive())
+
+    engine.release()
+  }
+
+  @Test
+  fun `handleReplayGainParse caches data and activates the engine in track mode`() {
+    val engine = makeEngine()
+    ReplayGainConfig.setMode(ReplayGainMode.TRACK)
+
+    val data = ReplayGainData(
+      trackGainDb = -6.0f,
+      trackPeak = 0.5f,
+      albumGainDb = -3.0f,
+      albumPeak = 0.8f,
+    )
+    engine.handleReplayGainParse(data)
+
+    assertEquals(data, engine.currentReplayGainData())
+    assertTrue(engine.currentReplayGainActive())
+    engine.release()
+  }
+
+  @Test
+  fun `handleReplayGainParse with album-only data is inactive in track mode`() {
+    val engine = makeEngine()
+    ReplayGainConfig.setMode(ReplayGainMode.TRACK)
+
+    val data = ReplayGainData(
+      trackGainDb = null,
+      trackPeak = null,
+      albumGainDb = -3.0f,
+      albumPeak = 0.8f,
+    )
+    engine.handleReplayGainParse(data)
+
+    assertNotNull(engine.currentReplayGainData())
+    assertFalse(
+      "track mode requires trackGainDb; album-only data is inactive",
+      engine.currentReplayGainActive()
+    )
+    engine.release()
+  }
+
+  @Test
+  fun `handleReplayGainParse with track-only data is inactive in album mode (strict no-fallback)`() {
+    val engine = makeEngine()
+    ReplayGainConfig.setMode(ReplayGainMode.ALBUM)
+
+    val data = ReplayGainData(
+      trackGainDb = -6.0f,
+      trackPeak = 0.5f,
+      albumGainDb = null,
+      albumPeak = null,
+    )
+    engine.handleReplayGainParse(data)
+
+    assertNotNull(engine.currentReplayGainData())
+    assertFalse(
+      "album mode is strict — track-only data does not fall back",
+      engine.currentReplayGainActive()
+    )
+    engine.release()
+  }
+
+  @Test
+  fun `handleReplayGainParse with null parse leaves the cache untouched`() {
+    val engine = makeEngine()
+    ReplayGainConfig.setMode(ReplayGainMode.TRACK)
+
+    val data = ReplayGainData(
+      trackGainDb = -6.0f, trackPeak = 0.5f,
+      albumGainDb = null, albumPeak = null,
+    )
+    engine.handleReplayGainParse(data)
+    assertNotNull(engine.currentReplayGainData())
+
+    // Subsequent null parse (e.g. unrelated TIT2 frame) does not wipe
+    // the previously-cached track-load RG block.
+    engine.handleReplayGainParse(null)
+    assertEquals(data, engine.currentReplayGainData())
+    assertTrue(engine.currentReplayGainActive())
+    engine.release()
+  }
+
+  // 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`).
+}

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

@@ -0,0 +1,106 @@
+package com.margelo.nitro.queueplayer
+
+import android.content.Intent
+import androidx.media3.common.util.UnstableApi
+import androidx.media3.session.MediaLibraryService
+import androidx.media3.session.MediaSession
+import androidx.test.core.app.ApplicationProvider
+import org.junit.After
+import org.junit.Assert.assertFalse
+import org.junit.Assert.assertNotNull
+import org.junit.Assert.assertNull
+import org.junit.Assert.assertSame
+import org.junit.Assert.assertTrue
+import org.junit.Test
+import org.junit.runner.RunWith
+import org.robolectric.RobolectricTestRunner
+import org.robolectric.annotation.Config
+
+/**
+ * Robolectric coverage for [HeadlessJsMediaService]'s testable
+ * surface: the default no-task `getTaskConfig` contract and the
+ * process-wide wake-lock helper.
+ *
+ * The full `onStartCommand` chain (which 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.
+ */
+@RunWith(RobolectricTestRunner::class)
+@Config(sdk = [34])
+@UnstableApi
+class HeadlessJsMediaServiceTest {
+
+  @After
+  fun tearDown() {
+    HeadlessJsMediaService.wakeLock?.let { lock ->
+      if (lock.isHeld) lock.release()
+    }
+    HeadlessJsMediaService.wakeLock = null
+  }
+
+  @Test
+  fun `default getTaskConfig returns null — services opt in by overriding`() {
+    val service = NoOpHeadlessJsMediaService()
+    assertNull(
+      "default impl returns null so subclasses without an override " +
+        "behave as a plain MediaLibraryService",
+      service.getTaskConfigForTest(Intent())
+    )
+  }
+
+  @Test
+  fun `activeTasks starts empty`() {
+    val service = NoOpHeadlessJsMediaService()
+    assertTrue(
+      "fresh service has no JS tasks scheduled",
+      service.activeTasks.isEmpty()
+    )
+  }
+
+  @Test
+  fun `acquireWakeLockNow holds at most one wake lock across re-entry`() {
+    val context = ApplicationProvider.getApplicationContext<android.content.Context>()
+    HeadlessJsMediaService.acquireWakeLockNow(context)
+    val first = HeadlessJsMediaService.wakeLock
+    assertNotNull("first acquire creates a wake lock", first)
+    assertTrue("first lock is held", first!!.isHeld)
+
+    HeadlessJsMediaService.acquireWakeLockNow(context)
+    val second = HeadlessJsMediaService.wakeLock
+    assertSame(
+      "second acquire while held does NOT replace the lock",
+      first,
+      second
+    )
+    assertTrue("lock still held after re-entry", second!!.isHeld)
+  }
+
+  @Test
+  fun `acquireWakeLockNow re-acquires after the prior lock has been released`() {
+    val context = ApplicationProvider.getApplicationContext<android.content.Context>()
+    HeadlessJsMediaService.acquireWakeLockNow(context)
+    val first = HeadlessJsMediaService.wakeLock
+    assertNotNull(first)
+    first!!.release()
+    assertFalse(first.isHeld)
+
+    HeadlessJsMediaService.acquireWakeLockNow(context)
+    val second = HeadlessJsMediaService.wakeLock
+    assertNotNull("released lock triggers a fresh acquire", second)
+    assertTrue("re-acquired lock is held", second!!.isHeld)
+  }
+
+  /** Exposes [HeadlessJsMediaService.getTaskConfig] for the test —
+   *  the protected modifier on the production member would
+   *  otherwise be unreachable from this same package because the
+   *  protected scope is class-derivation, not package, in Kotlin. */
+  internal class NoOpHeadlessJsMediaService : HeadlessJsMediaService() {
+    override fun onGetSession(
+      controllerInfo: MediaSession.ControllerInfo
+    ): MediaLibraryService.MediaLibrarySession? = null
+
+    fun getTaskConfigForTest(intent: Intent?) = getTaskConfig(intent)
+  }
+}