capacitor-plugin-playlist 0.11.0 → 0.11.2

package/README.md

@@ -24,7 +24,9 @@ Requires **Capacitor 8+** (peer dependency `@capacitor/core >= 8.0.0`).
 ### Playlist management
 
 - `setPlaylistItems` — replace entire playlist (optional position retention)
-- `addItem` / `addAllItems` — append tracks
+- `addItem` / `addAllItems` — append tracks; `addItem` accepts optional insert index (“play next”)
+- `moveItem` — reorder without disrupting current playback
+- `replaceItem` — swap track metadata/URL in place (e.g. stream → offline file)
 - `removeItem` / `removeItems` / `clearAllItems` — remove tracks
 - `getPlaylist` — snapshot of current items
 - `setLoop` — loop entire playlist when the last track completes
@@ -83,7 +85,7 @@ See [Video handoff](#video-handoff).
 ### Not supported
 
 - Shuffle
-- Reorder API
+- Audio ads / IMA integration ([#71](https://github.com/phiamo/capacitor-plugin-playlist/issues/71))
 - Mixable / low-latency game audio (use [cordova-plugin-nativeaudio](https://github.com/floatinghotpot/cordova-plugin-nativeaudio) instead)
 - Simultaneous audio mixing (lock-screen controls require exclusive audio focus)
 
@@ -443,6 +445,8 @@ See [CHANGELOG.md](./CHANGELOG.md) for version-specific fixes (0.8.8–0.10.3).
 * [`release()`](#release)
 * [`setPlaylistItems(...)`](#setplaylistitems)
 * [`addItem(...)`](#additem)
+* [`moveItem(...)`](#moveitem)
+* [`replaceItem(...)`](#replaceitem)
 * [`addAllItems(...)`](#addallitems)
 * [`removeItem(...)`](#removeitem)
 * [`removeItems(...)`](#removeitems)
@@ -552,7 +556,9 @@ Use `options.retainPosition` to keep the current track and playback position.
 addItem(options: AddItemOptions) => Promise<void>
 ```
 
-Append a single track to the end of the playlist.
+Append a single track to the end of the playlist, or insert at a 0-based index.
+When `index` is omitted the track is appended. Insertion does not interrupt playback
+of the current track.
 
 | Param         | Type                                                      |
 | ------------- | --------------------------------------------------------- |
@@ -561,6 +567,37 @@ Append a single track to the end of the playlist.
 --------------------
 
 
+### moveItem(...)
+
+```typescript
+moveItem(options: MoveItemOptions) => Promise<void>
+```
+
+Move a track from one index to another without restarting the current track.
+
+| Param         | Type                                                        |
+| ------------- | ----------------------------------------------------------- |
+| **`options`** | <code><a href="#moveitemoptions">MoveItemOptions</a></code> |
+
+--------------------
+
+
+### replaceItem(...)
+
+```typescript
+replaceItem(options: ReplaceItemOptions) => Promise<void>
+```
+
+Replace a track's metadata and source URL in place (e.g. stream URL → local file).
+When replacing the currently playing track, playback position and play/pause state are preserved.
+
+| Param         | Type                                                              |
+| ------------- | ----------------------------------------------------------------- |
+| **`options`** | <code><a href="#replaceitemoptions">ReplaceItemOptions</a></code> |
+
+--------------------
+
+
 ### addAllItems(...)
 
 ```typescript
@@ -1035,9 +1072,27 @@ that were in the previous list.
 
 #### AddItemOptions
 
-| Prop       | Type                                              |
-| ---------- | ------------------------------------------------- |
-| **`item`** | <code><a href="#audiotrack">AudioTrack</a></code> |
+| Prop        | Type                                              | Description                                 |
+| ----------- | ------------------------------------------------- | ------------------------------------------- |
+| **`item`**  | <code><a href="#audiotrack">AudioTrack</a></code> |                                             |
+| **`index`** | <code>number</code>                               | 0-based index to insert at. Omit to append. |
+
+
+#### MoveItemOptions
+
+| Prop       | Type                | Description                                |
+| ---------- | ------------------- | ------------------------------------------ |
+| **`from`** | <code>number</code> | Source index (0-based).                    |
+| **`to`**   | <code>number</code> | Destination index (0-based) after removal. |
+
+
+#### ReplaceItemOptions
+
+| Prop        | Type                                              | Description                                                                |
+| ----------- | ------------------------------------------------- | -------------------------------------------------------------------------- |
+| **`item`**  | <code><a href="#audiotrack">AudioTrack</a></code> | Replacement track data. When `trackId` is omitted the existing id is kept. |
+| **`index`** | <code>number</code>                               | Index of the track to replace (preferred over `id`).                       |
+| **`id`**    | <code>string</code>                               | Id of the track to replace.                                                |
 
 
 #### AddAllItemOptions
@@ -1189,6 +1244,8 @@ that were in the previous list.
 | **`RMXSTATUS_PLAYLIST_COMPLETED`** | <code>105</code> | The entire playlist has completed playback. After this event has been raised, the current item is set to null and the current index to -1.                                                                                                                                                                                                |
 | **`RMXSTATUS_ITEM_ADDED`**         | <code>110</code> | An item has been added to the playlist. For the setPlaylistItems and addAllItems methods, this status is raised once for every track in the collection.                                                                                                                                                                                   |
 | **`RMXSTATUS_ITEM_REMOVED`**       | <code>115</code> | An item has been removed from the playlist. For the removeItems and clearAllItems methods, this status is raised once for every track that was removed.                                                                                                                                                                                   |
+| **`RMXSTATUS_ITEM_MOVED`**         | <code>112</code> | An item has been moved within the playlist.                                                                                                                                                                                                                                                                                               |
+| **`RMXSTATUS_ITEM_REPLACED`**      | <code>113</code> | An item in the playlist has been replaced in place.                                                                                                                                                                                                                                                                                       |
 | **`RMXSTATUS_PLAYLIST_CLEARED`**   | <code>120</code> | All items have been removed from the playlist                                                                                                                                                                                                                                                                                             |
 | **`RMXSTATUS_VIEWDISAPPEAR`**      | <code>200</code> | Just for testing.. you don't need this and in fact can never receive it, the plugin is destroyed before it can be raised.                                                                                                                                                                                                                 |
 

package/android/build.gradle

@@ -1,9 +1,27 @@
+// Consuming Capacitor apps normally supply the Android/Kotlin Gradle plugin classpath from
+// their own root build.gradle. This buildscript block is only needed to run `./gradlew test`
+// standalone from this module (e.g. `npm run verify:android`); it is additive to this
+// subproject's own build-script classpath and does not affect a parent app's configuration.
+buildscript {
+    repositories {
+        google()
+        mavenCentral()
+    }
+    dependencies {
+        classpath 'com.android.tools.build:gradle:8.13.0'
+        classpath 'org.jetbrains.kotlin:kotlin-gradle-plugin:2.1.0'
+    }
+}
+
 import org.jetbrains.kotlin.gradle.dsl.JvmTarget
 
 ext {
     junitVersion = project.hasProperty('junitVersion') ? rootProject.ext.junitVersion : '4.13.2'
     androidxJunitVersion = project.hasProperty('androidxJunitVersion') ? rootProject.ext.androidxJunitVersion : '1.3.0'
     androidxEspressoCoreVersion = project.hasProperty('androidxEspressoCoreVersion') ? rootProject.ext.androidxEspressoCoreVersion : '3.7.0'
+    // Only used when this module is built standalone (e.g. `npm run verify:android`); when
+    // embedded, the consuming app's root build.gradle already sets rootProject.ext.kotlin_version.
+    kotlin_version = project.hasProperty('kotlinVersion') ? rootProject.ext.kotlinVersion : '2.1.0'
 }
 
 apply plugin: 'com.android.library'
@@ -50,6 +68,9 @@ dependencies {
     implementation fileTree(dir: 'libs', include: ['*.jar'])
     implementation project(':capacitor-android')
     testImplementation "junit:junit:$junitVersion"
+    // Real org.json implementation for plain JVM unit tests: the android.jar stub used for
+    // compilation throws "Stub!" for org.json.* at runtime outside instrumented/Robolectric tests.
+    testImplementation "org.json:json:20231013"
     androidTestImplementation "androidx.test.ext:junit:$androidxJunitVersion"
     androidTestImplementation "androidx.test.espresso:espresso-core:$androidxEspressoCoreVersion"
     implementation "androidx.core:core-ktx:1.17.0"

package/android/src/main/java/org/dwbn/plugins/playlist/PlaylistPlugin.kt

@@ -97,15 +97,19 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
     fun addItem(call: PluginCall) {
         Handler(Looper.getMainLooper()).post {
             val item: JSONObject = call.getObject("item")
+            val index: Int = call.getInt("index", -1)!!
             val playerItem: AudioTrack? = getTrackItem(item)
-            audioPlayerImpl!!.getPlaylistManager().addItem(playerItem)
-
+            audioPlayerImpl!!.getPlaylistManager().addItem(playerItem, index)
 
             if (playerItem?.trackId != null) {
+                val payload = playerItem.toDict()
+                if (index >= 0) {
+                    payload.put("index", index.coerceIn(0, audioPlayerImpl!!.playlistManager.getAllItems().size - 1))
+                }
                 onStatus(
                     RmxAudioStatusMessage.RMXSTATUS_ITEM_ADDED,
                     playerItem.trackId,
-                    playerItem.toDict()
+                    payload
                 )
             }
             call.resolve()
@@ -113,6 +117,56 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
         }
     }
 
+    @PluginMethod
+    fun moveItem(call: PluginCall) {
+        Handler(Looper.getMainLooper()).post {
+            val from: Int = call.getInt("from", -1)!!
+            val to: Int = call.getInt("to", -1)!!
+            val moved = audioPlayerImpl!!.playlistManager.moveItem(from, to)
+            if (!moved) {
+                call.reject("Index out of bounds")
+                return@post
+            }
+
+            val payload = JSONObject()
+            payload.put("from", from)
+            payload.put("to", to)
+            payload.put("currentIndex", audioPlayerImpl!!.playlistManager.currentPosition)
+            onStatus(
+                RmxAudioStatusMessage.RMXSTATUS_ITEM_MOVED,
+                audioPlayerImpl!!.playlistManager.currentItem?.trackId ?: "INVALID",
+                payload
+            )
+            call.resolve()
+            Log.i(TAG, "moveItem from=$from to=$to")
+        }
+    }
+
+    @PluginMethod
+    fun replaceItem(call: PluginCall) {
+        Handler(Looper.getMainLooper()).post {
+            val trackIndex: Int = call.getInt("index", -1)!!
+            val trackId: String = call.getString("id", "")!!
+            val item: JSONObject = call.getObject("item")
+            // An omitted trackId in the payload intentionally means "keep the existing id",
+            // so this must not be rejected the way a brand-new addItem() track would be.
+            val replacement: AudioTrack? = getTrackItem(item, requireTrackId = false)
+            val replaced = audioPlayerImpl!!.playlistManager.replaceItem(trackIndex, trackId, replacement)
+
+            if (replaced != null) {
+                onStatus(
+                    RmxAudioStatusMessage.RMXSTATUS_ITEM_REPLACED,
+                    replaced.trackId,
+                    replaced.toDict()
+                )
+                call.resolve()
+            } else {
+                call.reject("Could not find item!")
+            }
+            Log.i(TAG, "replaceItem")
+        }
+    }
+
     @PluginMethod
     fun addAllItems(call: PluginCall) {
         Handler(Looper.getMainLooper()).post {
@@ -257,13 +311,16 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
         Handler(Looper.getMainLooper()).post {
             val id: String = call.getString("id")!!
             if ("" != id) {
-                val code = id.hashCode()
-                val seekPosition = (call.getFloat("position", 0f)!! * 1000.0f).toLong()
-                audioPlayerImpl!!.playlistManager.setCurrentItem(code.toLong())
-                val handler = audioPlayerImpl!!.playlistManager.playlistHandler
-                val alreadyPlaying = handler?.currentMediaPlayer?.isPlaying == true
-                if (!audioPlayerImpl!!.tryResumeVideoHandoffInPlace(seekPosition) && !alreadyPlaying) {
-                    audioPlayerImpl!!.playlistManager.beginPlayback(seekPosition, false)
+                val playlistManager = audioPlayerImpl!!.playlistManager
+                val position = playlistManager.findTrackPosition(id)
+                if (position >= 0) {
+                    val seekPosition = (call.getFloat("position", 0f)!! * 1000.0f).toLong()
+                    playlistManager.currentPosition = position
+                    val handler = playlistManager.playlistHandler
+                    val alreadyPlaying = handler?.currentMediaPlayer?.isPlaying == true
+                    if (!audioPlayerImpl!!.tryResumeVideoHandoffInPlace(seekPosition) && !alreadyPlaying) {
+                        playlistManager.beginPlayback(seekPosition, false)
+                    }
                 }
             }
 
@@ -297,13 +354,13 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
         Handler(Looper.getMainLooper()).post {
             val id: String = call.getString("id")!!
             if ("" != id) {
-                // alternatively we could search for the item and set the current index to that item.
-                val code = id.hashCode()
-                audioPlayerImpl!!.playlistManager.setCurrentItem(code.toLong())
-
-                val seekPosition = (call.getFloat("position", 0f)!! * 1000.0f).toLong()
-
-                audioPlayerImpl!!.playlistManager.beginPlayback(seekPosition, true)
+                val playlistManager = audioPlayerImpl!!.playlistManager
+                val position = playlistManager.findTrackPosition(id)
+                if (position >= 0) {
+                    val seekPosition = (call.getFloat("position", 0f)!! * 1000.0f).toLong()
+                    playlistManager.currentPosition = position
+                    playlistManager.beginPlayback(seekPosition, true)
+                }
             }
             call.resolve()
 
@@ -475,10 +532,10 @@ public class PlaylistPlugin : Plugin(), OnStatusReportListener {
         audioPlayerImpl!!.playlistManager.clearItems()
     }
 
-    private fun getTrackItem(item: JSONObject?): AudioTrack? {
+    private fun getTrackItem(item: JSONObject?, requireTrackId: Boolean = true): AudioTrack? {
         if (item != null) {
             val track = AudioTrack(item)
-            return if (track.trackId != null) {
+            return if (!requireTrackId || track.trackId != null) {
                 track
             } else null
         }

package/android/src/main/java/org/dwbn/plugins/playlist/RmxAudioStatusMessage.java

@@ -24,6 +24,8 @@ public enum RmxAudioStatusMessage {
   RMXSTATUS_TRACK_CHANGED(100),
   RMXSTATUS_PLAYLIST_COMPLETED(105),
   RMXSTATUS_ITEM_ADDED(110),
+  RMXSTATUS_ITEM_MOVED(112),
+  RMXSTATUS_ITEM_REPLACED(113),
   RMXSTATUS_ITEM_REMOVED(115),
   RMXSTATUS_PLAYLIST_CLEARED(120),
 

package/android/src/main/java/org/dwbn/plugins/playlist/data/AudioTrack.kt

@@ -5,8 +5,15 @@ import com.devbrackets.android.playlistcore.api.PlaylistItem
 import com.devbrackets.android.playlistcore.manager.BasePlaylistManager
 import org.json.JSONException
 import org.json.JSONObject
+import java.util.concurrent.atomic.AtomicLong
 
 class AudioTrack (private val config: JSONObject) : PlaylistItem {
+    companion object {
+        private val nextPlaylistId = AtomicLong(1)
+    }
+
+    override val id: Long = nextPlaylistId.getAndIncrement()
+
     var bufferPercentFloat = 0f
         set(buff) {
             // There is a bug in MediaProgress where if bufferPercent == 100 it sets bufferPercentFloat
@@ -38,12 +45,6 @@ class AudioTrack (private val config: JSONObject) : PlaylistItem {
         return info
     }
 
-    override val id: Long
-        get() =
-            if (trackId == null) {
-                0
-            } else trackId.hashCode().toLong()
-
     val isStream: Boolean
         get() = config.optBoolean("isStream", false)
 

package/android/src/main/java/org/dwbn/plugins/playlist/manager/PlaylistManager.kt

@@ -104,28 +104,22 @@ class PlaylistManager(application: Application) :
      * List management
      */
     fun setAllItems(items: List<AudioTrack>?, options: PlaylistItemOptions) {
+        val seekStart = when {
+            options.playFromPosition >= 0 -> options.playFromPosition
+            options.retainPosition -> currentProgress?.position ?: 0
+            else -> 0
+        }
+
         clearItems()
         addAllItems(items)
         currentPosition = 0
-        // If the options said to start from a specific position, do so.
-        var seekStart: Long = 0
-        if (options.playFromPosition > 0) {
-            seekStart = options.playFromPosition
-        } else if (options.retainPosition) {
-            val progress = currentProgress
-            if (progress != null) {
-              seekStart = progress.position
-            }
-        }
 
-        // If the options said to start from a specific id, do so.
-        var idStart: String? = null
-        if (options.playFromId != null) {
-            idStart = options.playFromId
-        }
-        if (idStart != null && "" != idStart) {
-            val code = idStart.hashCode()
-            setCurrentItem(code.toLong())
+        // If the requested id exists, start there; otherwise keep the first track.
+        options.playFromId?.let { trackId ->
+            val position = findTrackPosition(trackId)
+            if (position != INVALID_POSITION) {
+                currentPosition = position
+            }
         }
 
         // We assume that if the playlist is fully loaded in one go,
@@ -135,22 +129,89 @@ class PlaylistManager(application: Application) :
         beginPlayback(seekStart, options.startPaused)
     }
 
-    fun addItem(item: AudioTrack?) {
+    fun addItem(item: AudioTrack?, index: Int = -1) {
         if (item == null) {
             return
         }
-        val countBefore = audioTracks.size;
-        audioTracks.add(item)
+        val countBefore = audioTracks.size
+        val insertIndex = if (index >= 0) {
+            index.coerceIn(0, audioTracks.size)
+        } else {
+            audioTracks.size
+        }
+
+        if (insertIndex >= audioTracks.size) {
+            audioTracks.add(item)
+        } else {
+            audioTracks.add(insertIndex, item)
+            if (currentPosition >= insertIndex && currentPosition != INVALID_POSITION) {
+                currentPosition++
+            }
+        }
         items = audioTracks
+
         if (countBefore == 0) {
             currentPosition = 0
             beginPlayback(1, true)
+        } else if (this.playlistHandler != null) {
+            this.playlistHandler!!.updateMediaControls()
+        }
+    }
+
+    fun moveItem(from: Int, to: Int): Boolean {
+        if (from < 0 || from >= audioTracks.size || to < 0 || to >= audioTracks.size) {
+            return false
         }
+        if (from == to) {
+            return true
+        }
+
+        val item = audioTracks.removeAt(from)
+        audioTracks.add(to, item)
+        items = audioTracks
+
+        currentPosition = adjustCurrentIndexForMove(currentPosition, from, to, INVALID_POSITION)
+
         if (this.playlistHandler != null) {
             this.playlistHandler!!.updateMediaControls()
         }
+        return true
+    }
+
+    fun replaceItem(index: Int, itemId: String, replacement: AudioTrack?): AudioTrack? {
+        if (replacement == null) {
+            return null
+        }
+        val resolvedIndex = resolveItemPosition(index, itemId)
+        if (resolvedIndex < 0 || resolvedIndex >= audioTracks.size) {
+            return null
+        }
+
+        val existing = audioTracks[resolvedIndex]
+        val resolvedReplacement = mergeReplacementTrackId(existing, replacement)
+
+        val isCurrent = existing == currentItem
+        val wasPlaying = isPlaying
+        val progress = currentProgress
+        val seekPosition: Long = if (progress != null) progress.position else 0
+
+        if (isCurrent && playlistHandler != null) {
+            playlistHandler!!.pause(true)
+        }
+
+        audioTracks[resolvedIndex] = resolvedReplacement
+        items = audioTracks
+
+        if (isCurrent) {
+            beginPlayback(seekPosition, !wasPlaying)
+        } else if (this.playlistHandler != null) {
+            this.playlistHandler!!.updateMediaControls()
+        }
+
+        return resolvedReplacement
     }
 
+
     fun addAllItems(its: List<AudioTrack>?) {
         val currentItem = currentItem // may be null
         audioTracks.addAll(its.orEmpty())
@@ -240,18 +301,16 @@ class PlaylistManager(application: Application) :
     }
 
     private fun resolveItemPosition(trackIndex: Int, trackId: String): Int {
-        var resolvedPosition = -1
-        if (trackIndex >= 0 && trackIndex < audioTracks.size) {
-            resolvedPosition = trackIndex
-        } else if ("" != trackId) {
-            val itemPos = getPositionForItem(trackId.hashCode().toLong())
-            if (itemPos != INVALID_POSITION) {
-                resolvedPosition = itemPos
-            }
+        return when {
+            trackIndex in audioTracks.indices -> trackIndex
+            trackId.isNotEmpty() -> findTrackPosition(trackId)
+            else -> INVALID_POSITION
         }
-        return resolvedPosition
     }
 
+    internal fun findTrackPosition(trackId: String): Int =
+        audioTracks.indexOfFirst { it.trackId == trackId }
+
     fun getVolumeLeft(): Float {
         return volumeLeft
     }
@@ -308,6 +367,41 @@ class PlaylistManager(application: Application) :
 
     companion object {
         private const val TAG = "PlaylistManager"
+
+        /**
+         * Computes the new position of the "current" item after moving an item from index
+         * [from] to index [to] (post-removal insertion semantics, i.e. matching
+         * `MutableList.removeAt(from)` followed by `MutableList.add(to, item)`).
+         *
+         * Pure function so it can be unit-tested without an Android/Application context.
+         */
+        @JvmStatic
+        fun adjustCurrentIndexForMove(currentIndex: Int, from: Int, to: Int, invalidPosition: Int): Int {
+            if (currentIndex == invalidPosition) {
+                return currentIndex
+            }
+            if (from == currentIndex) {
+                return to
+            }
+            val mid = if (from < currentIndex) currentIndex - 1 else currentIndex
+            return if (mid >= to) mid + 1 else mid
+        }
+
+        /**
+         * Builds the [AudioTrack] that should replace [existing], backfilling `trackId` from
+         * [existing] when [replacement] doesn't specify one (an omitted id signals "keep the
+         * existing id" rather than "generate a new one").
+         *
+         * Pure function so it can be unit-tested without an Android/Application context.
+         */
+        @JvmStatic
+        fun mergeReplacementTrackId(existing: AudioTrack, replacement: AudioTrack): AudioTrack {
+            val replacementConfig = replacement.toDict()
+            if (replacement.trackId.isNullOrEmpty() && existing.trackId != null) {
+                replacementConfig.put("trackId", existing.trackId)
+            }
+            return AudioTrack(replacementConfig)
+        }
     }
 
     init {

package/android/src/test/java/org/dwbn/plugins/playlist/manager/PlaylistManagerMoveTest.kt

@@ -0,0 +1,76 @@
+package org.dwbn.plugins.playlist.manager
+
+import org.junit.Assert.assertEquals
+import org.junit.Test
+
+/**
+ * Regression coverage for the currentPosition arithmetic used by [PlaylistManager.moveItem].
+ * Verified against a brute-force ground truth (simulate removeAt(from)+add(to,item) on a real
+ * list and look up the moved-tracked item's resulting index) for lists of size 2..6 and every
+ * valid (from, to, currentIndex) combination.
+ */
+class PlaylistManagerMoveTest {
+
+    private val invalid = -1
+
+    @Test
+    fun currentItem_isTheOneMoved_returnsDestinationIndex() {
+        assertEquals(2, PlaylistManager.adjustCurrentIndexForMove(0, 0, 2, invalid))
+        assertEquals(0, PlaylistManager.adjustCurrentIndexForMove(3, 3, 0, invalid))
+    }
+
+    @Test
+    fun invalidPosition_isReturnedUnchanged() {
+        assertEquals(invalid, PlaylistManager.adjustCurrentIndexForMove(invalid, 0, 2, invalid))
+    }
+
+    @Test
+    fun movingItemFromBeforeCurrent_toAtOrBeforeCurrent_shiftsCurrentLeft() {
+        // list [a,b,c,d], current = b (index 1), move a(0) -> 1: [b,a,c,d]; b is now at 0.
+        assertEquals(0, PlaylistManager.adjustCurrentIndexForMove(1, 0, 1, invalid))
+    }
+
+    @Test
+    fun movingItemFromBeforeCurrent_toAfterCurrent_leavesCurrentUnchanged() {
+        // list [a,b,c,d], current = b (index 1), move a(0) -> 3: [b,c,d,a]; b stays at 0.
+        assertEquals(0, PlaylistManager.adjustCurrentIndexForMove(1, 0, 3, invalid))
+    }
+
+    @Test
+    fun movingItemFromAfterCurrent_toAtOrBeforeCurrent_shiftsCurrentRight() {
+        // list [a,b,c,d], current = a (index 0), move c(2) -> 0: [c,a,b,d]; a is now at 1.
+        assertEquals(1, PlaylistManager.adjustCurrentIndexForMove(0, 2, 0, invalid))
+    }
+
+    @Test
+    fun movingItemFromAfterCurrent_toAfterCurrent_leavesCurrentUnchanged() {
+        // list [a,b,c,d], current = a (index 0), move c(2) -> 3: [a,b,d,c]; a stays at 0.
+        assertEquals(0, PlaylistManager.adjustCurrentIndexForMove(0, 2, 3, invalid))
+    }
+
+    @Test
+    fun bruteForce_matchesGroundTruthForAllCombinations() {
+        for (n in 2..6) {
+            val base = (0 until n).toList()
+            for (from in 0 until n) {
+                for (to in 0 until n) {
+                    if (from == to) continue
+                    val expectedArr = base.toMutableList()
+                    val moved = expectedArr.removeAt(from)
+                    expectedArr.add(to, moved)
+
+                    for (currentIndex in 0 until n) {
+                        val trackedId = base[currentIndex]
+                        val expectedNewIndex = expectedArr.indexOf(trackedId)
+                        val got = PlaylistManager.adjustCurrentIndexForMove(currentIndex, from, to, invalid)
+                        assertEquals(
+                            "n=$n from=$from to=$to currentIndex=$currentIndex",
+                            expectedNewIndex,
+                            got
+                        )
+                    }
+                }
+            }
+        }
+    }
+}

package/android/src/test/java/org/dwbn/plugins/playlist/manager/PlaylistManagerReplaceTest.kt

@@ -0,0 +1,57 @@
+package org.dwbn.plugins.playlist.manager
+
+import org.dwbn.plugins.playlist.data.AudioTrack
+import org.json.JSONObject
+import org.junit.Assert.assertEquals
+import org.junit.Assert.assertNull
+import org.junit.Test
+
+/**
+ * Regression coverage for [PlaylistManager.mergeReplacementTrackId], which decides whether a
+ * replacement track keeps its own id or inherits the id of the track it is replacing.
+ */
+class PlaylistManagerReplaceTest {
+
+    private fun track(trackId: String? = null, assetUrl: String = "https://example.com/a.mp3"): AudioTrack {
+        val json = JSONObject()
+        if (trackId != null) {
+            json.put("trackId", trackId)
+        }
+        json.put("assetUrl", assetUrl)
+        json.put("artist", "Artist")
+        json.put("album", "Album")
+        json.put("title", "Title")
+        return AudioTrack(json)
+    }
+
+    @Test
+    fun replacementWithoutTrackId_inheritsExistingTrackId() {
+        val existing = track(trackId = "existing-id")
+        val replacement = track(trackId = null, assetUrl = "https://example.com/local.mp3")
+
+        val result = PlaylistManager.mergeReplacementTrackId(existing, replacement)
+
+        assertEquals("existing-id", result.trackId)
+        assertEquals("https://example.com/local.mp3", result.mediaUrl)
+    }
+
+    @Test
+    fun replacementWithExplicitTrackId_isNotOverridden() {
+        val existing = track(trackId = "existing-id")
+        val replacement = track(trackId = "new-id")
+
+        val result = PlaylistManager.mergeReplacementTrackId(existing, replacement)
+
+        assertEquals("new-id", result.trackId)
+    }
+
+    @Test
+    fun replacementWithoutTrackId_andNoExistingTrackId_staysNull() {
+        val existing = track(trackId = null)
+        val replacement = track(trackId = null)
+
+        val result = PlaylistManager.mergeReplacementTrackId(existing, replacement)
+
+        assertNull(result.trackId)
+    }
+}