react-native-nitro-player 1.7.0-alpha.3 → 1.7.0-alpha.5

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaSessionCallbackFactory.kt

@@ -3,18 +3,22 @@
 package com.margelo.nitro.nitroplayer.media
 
 import android.net.Uri
+import android.os.Handler
+import android.os.Looper
 import android.provider.MediaStore
 import androidx.media3.common.MediaItem
 import androidx.media3.common.MediaMetadata
+import androidx.media3.common.Player
+import androidx.media3.common.Timeline
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.session.MediaSession
 import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionResult
 import com.google.common.util.concurrent.Futures
 import com.google.common.util.concurrent.ListenableFuture
+import com.google.common.util.concurrent.SettableFuture
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
-import com.margelo.nitro.nitroplayer.core.loadPlaylist
 import com.margelo.nitro.nitroplayer.playlist.Playlist
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 import kotlinx.coroutines.CoroutineScope
@@ -43,7 +47,8 @@ object MediaSessionCallbackFactory {
                 MediaSession.ConnectionResult
                     .AcceptedResultBuilder(session)
                     .setAvailableSessionCommands(
-                        MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS,
+                        service.trackPlayerCore?.mediaSessionManager?.sessionCommands()
+                            ?: MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS,
                     ).setAvailablePlayerCommands(
                         MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS,
                     ).build()
@@ -74,7 +79,7 @@ object MediaSessionCallbackFactory {
                             val playlistId = mediaId.substring(0, colonIdx)
                             val trackId = mediaId.substring(colonIdx + 1)
                             val playlist = playlistManager.getPlaylist(playlistId)
-                            val track = playlist?.tracks?.find { it.id == trackId }
+                            val track = playlist?.tracks?.getOrNull(playlistManager.indexOfTrackRef(playlistId, trackId))
                             if (track != null) {
                                 updated.add(createMediaItem(track, mediaId))
                             } else {
@@ -105,10 +110,7 @@ object MediaSessionCallbackFactory {
                 // it against loaded playlists before falling through.
                 val voiceMatch = resolveVoiceSearch(mediaItems, playlistManager)
                 if (voiceMatch != null) {
-                    val (playlistId, items, trackIndex) = voiceMatch
-                    service.trackPlayerCore?.let { core ->
-                        scope.launch { core.loadPlaylist(playlistId, trackIndex) }
-                    }
+                    val (_, items, trackIndex) = voiceMatch
                     return Futures.immediateFuture(
                         MediaSession.MediaItemsWithStartPosition(items, trackIndex, startPositionMs),
                     )
@@ -127,15 +129,15 @@ object MediaSessionCallbackFactory {
                         val trackId = firstMediaId.substring(colonIdx + 1)
                         val playlist = playlistManager.getPlaylist(playlistId)
                         if (playlist != null) {
-                            val trackIndex = playlist.tracks.indexOfFirst { it.id == trackId }
+                            val trackIndex = playlistManager.indexOfTrackRef(playlistId, trackId)
                             if (trackIndex >= 0) {
-                                service.trackPlayerCore?.let { core ->
-                                    scope.launch { core.loadPlaylist(playlistId, trackIndex) }
-                                }
+                                val seen = mutableSetOf<String>()
                                 val playlistMediaItems =
                                     playlist.tracks
-                                        .map { track -> createMediaItem(track, "$playlistId:${track.id}") }
-                                        .toMutableList()
+                                        .mapIndexed { i, track ->
+                                            val ref = if (seen.add(track.id)) track.id else "${track.id}#$i"
+                                            createMediaItem(track, "$playlistId:$ref")
+                                        }.toMutableList()
                                 return Futures.immediateFuture(
                                     MediaSession.MediaItemsWithStartPosition(
                                         playlistMediaItems,
@@ -150,31 +152,107 @@ object MediaSessionCallbackFactory {
                     NitroPlayerLogger.log("MediaSessionCallback") { "Error in onSetMediaItems: ${e.message}" }
                 }
 
-                // If a voice query was issued but found nothing, return an
-                // explicit failure so the controller (Assistant) surfaces a
-                // spoken error instead of silently no-oping. Without this the
-                // Auto QA bot reports "no music played or error message shown".
-                if (mediaItems.isNotEmpty() && mediaItems[0].requestMetadata.searchQuery != null) {
-                    return Futures.immediateFailedFuture(
-                        UnsupportedOperationException("No matching tracks for voice search"),
-                    )
-                }
+                // No match in loaded playlists: try the app's search, else fail so Assistant speaks an error
+                val voiceQuery = mediaItems.firstOrNull()?.requestMetadata?.searchQuery
+                if (voiceQuery != null) return searchAndPlay(service, playlistManager, scope, voiceQuery, startPositionMs)
 
                 return Futures.immediateFuture(
                     MediaSession.MediaItemsWithStartPosition(mediaItems, startIndex, startPositionMs),
                 )
             }
 
+            // Car "start music automatically" on a cold start: play what the app restores once its JS is up
+            override fun onPlaybackResumption(
+                mediaSession: MediaSession,
+                controller: MediaSession.ControllerInfo,
+                isForPlayback: Boolean,
+            ): ListenableFuture<MediaSession.MediaItemsWithStartPosition> {
+                service.trackPlayerCore?.startJsRuntimeIfNeeded()
+                MediaLibraryManager.getInstance(service).requestResumption()
+                val future = SettableFuture.create<MediaSession.MediaItemsWithStartPosition>()
+                val player = mediaSession.player
+                val handler = Handler(Looper.getMainLooper())
+                lateinit var listener: Player.Listener
+                lateinit var timeout: Runnable
+                val finish = {
+                    player.removeListener(listener)
+                    handler.removeCallbacks(timeout)
+                    val item = player.currentMediaItem
+                    if (item != null) {
+                        future.set(MediaSession.MediaItemsWithStartPosition(listOf(item), 0, player.currentPosition))
+                    } else {
+                        future.setException(UnsupportedOperationException("Nothing to resume"))
+                    }
+                }
+                listener =
+                    object : Player.Listener {
+                        override fun onTimelineChanged(
+                            timeline: Timeline,
+                            reason: Int,
+                        ) {
+                            if (player.currentMediaItem != null) finish()
+                        }
+                    }
+                timeout = Runnable { finish() }
+                player.addListener(listener)
+                handler.postDelayed(timeout, RESUMPTION_TIMEOUT_MS)
+                return future
+            }
+
             override fun onCustomCommand(
                 session: MediaSession,
                 controller: MediaSession.ControllerInfo,
                 customCommand: SessionCommand,
                 args: android.os.Bundle,
-            ): ListenableFuture<SessionResult> =
-                Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+            ): ListenableFuture<SessionResult> {
+                val manager = service.trackPlayerCore?.mediaSessionManager
+                if (manager?.handlesSessionButton(customCommand.customAction) == true) {
+                    manager.onSessionButtonPress?.invoke(customCommand.customAction)
+                }
+                return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+            }
         }
     }
 
+    // Asks the app's search, which can look past the loaded playlists; plays the first result naming a playlist track
+    private fun searchAndPlay(
+        service: NitroPlayerPlaybackService,
+        playlistManager: PlaylistManager,
+        scope: CoroutineScope,
+        query: String,
+        startPositionMs: Long,
+    ): ListenableFuture<MediaSession.MediaItemsWithStartPosition> {
+        val future = SettableFuture.create<MediaSession.MediaItemsWithStartPosition>()
+        scope.launch {
+            val match =
+                MediaLibraryManager
+                    .getInstance(service)
+                    .search(query)
+                    ?.firstNotNullOfOrNull { resolveTrack(it.id, playlistManager) }
+            if (match == null) {
+                future.setException(UnsupportedOperationException("No matching tracks for voice search"))
+                return@launch
+            }
+            val (playlist, index) = match
+            val items = playlist.tracks.map { createMediaItem(it, "${playlist.id}:${it.id}") }
+            future.set(MediaSession.MediaItemsWithStartPosition(items, index, startPositionMs))
+        }
+        return future
+    }
+
+    private fun resolveTrack(
+        mediaId: String,
+        playlistManager: PlaylistManager,
+    ): Pair<Playlist, Int>? {
+        val colonIndex = mediaId.indexOf(':')
+        if (colonIndex <= 0) return null
+        val playlist = playlistManager.getPlaylist(mediaId.substring(0, colonIndex)) ?: return null
+        val index = playlistManager.indexOfTrackRef(playlist.id, mediaId.substring(colonIndex + 1))
+        return if (index >= 0) playlist to index else null
+    }
+
+    private const val RESUMPTION_TIMEOUT_MS = 10_000L
+
     private data class VoiceMatch(
         val playlistId: String,
         val items: List<MediaItem>,

package/android/src/main/java/com/margelo/nitro/nitroplayer/media/MediaSessionManager.kt

@@ -1,10 +1,13 @@
 package com.margelo.nitro.nitroplayer.media
 
 import android.content.Context
+import android.os.Bundle
 import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.session.CommandButton
 import androidx.media3.session.MediaSession
+import androidx.media3.session.SessionCommand
+import androidx.media3.session.SessionCommands
 import com.margelo.nitro.nitroplayer.R
 import com.margelo.nitro.nitroplayer.TrackItem
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
@@ -45,6 +48,36 @@ class MediaSessionManager(
     private var remoteSkipForwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
     private var remoteSkipBackwardIntervalMs: Long = DEFAULT_REMOTE_SKIP_INTERVAL_MS
 
+    /** App-defined button; [icon] is a CommandButton.ICON_* constant. */
+    data class SessionButton(
+        val action: String,
+        val title: String,
+        val icon: Int,
+    )
+
+    private var sessionButtons: List<SessionButton> = emptyList()
+
+    @Volatile var onSessionButtonPress: ((action: String) -> Unit)? = null
+
+    fun sessionCommands(): SessionCommands =
+        MediaSession.ConnectionResult.DEFAULT_SESSION_COMMANDS
+            .buildUpon()
+            .apply { sessionButtons.forEach { add(SessionCommand(it.action, Bundle.EMPTY)) } }
+            .build()
+
+    fun handlesSessionButton(action: String): Boolean = sessionButtons.any { it.action == action }
+
+    fun setSessionButtons(buttons: List<SessionButton>) {
+        sessionButtons = buttons
+        val session = mediaSession ?: return
+        // A controller only shows or presses a button whose command it was granted; the notification one feeds Android Auto
+        val commands = sessionCommands()
+        (session.connectedControllers + listOfNotNull(session.mediaNotificationControllerInfo)).distinct().forEach {
+            session.setAvailableCommands(it, commands, MediaSession.ConnectionResult.DEFAULT_PLAYER_COMMANDS)
+        }
+        updateMediaButtonPreferences()
+    }
+
     init {
         updateMediaButtonPreferences()
     }
@@ -79,10 +112,21 @@ class MediaSessionManager(
 
     private fun updateMediaButtonPreferences() {
         val session = mediaSession ?: return
-        // Preferences replace Media3's default layout — prev/next must be declared or they vanish
-        val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() }
+        // Preferences replace Media3's default layout — prev/next must be declared or they vanish.
+        // Compact only shows BACK / play-pause / FORWARD, so the ±N skips go to OVERFLOW; left in
+        // the forward slot they push Next out of the compact notification entirely.
+        val preserved = session.mediaButtonPreferences.filterNot { it.isManagedButton() || it.sessionCommand != null }
+        val custom =
+            sessionButtons.map {
+                CommandButton
+                    .Builder(it.icon)
+                    .setDisplayName(it.title)
+                    .setSessionCommand(SessionCommand(it.action, Bundle.EMPTY))
+                    .setSlots(CommandButton.SLOT_OVERFLOW)
+                    .build()
+            }
         session.setMediaButtonPreferences(
-            listOf(previousTrackButton(), skipBackButton(), skipForwardButton(), nextTrackButton()) + preserved,
+            listOf(previousTrackButton(), nextTrackButton()) + custom + listOf(skipBackButton(), skipForwardButton()) + preserved,
         )
     }
 
@@ -90,6 +134,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(CommandButton.ICON_PREVIOUS)
             .setPlayerCommand(Player.COMMAND_SEEK_TO_PREVIOUS)
+            .setSlots(CommandButton.SLOT_BACK)
             .setDisplayName(context.getString(R.string.nitro_player_previous_track))
             .build()
 
@@ -97,6 +142,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(CommandButton.ICON_NEXT)
             .setPlayerCommand(Player.COMMAND_SEEK_TO_NEXT)
+            .setSlots(CommandButton.SLOT_FORWARD)
             .setDisplayName(context.getString(R.string.nitro_player_next_track))
             .build()
 
@@ -104,6 +150,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(skipBackIcon(remoteSkipBackwardIntervalMs))
             .setPlayerCommand(Player.COMMAND_SEEK_BACK)
+            .setSlots(CommandButton.SLOT_OVERFLOW)
             .setDisplayName(
                 context.getString(
                     R.string.nitro_player_skip_back_seconds,
@@ -115,6 +162,7 @@ class MediaSessionManager(
         CommandButton
             .Builder(skipForwardIcon(remoteSkipForwardIntervalMs))
             .setPlayerCommand(Player.COMMAND_SEEK_FORWARD)
+            .setSlots(CommandButton.SLOT_OVERFLOW)
             .setDisplayName(
                 context.getString(
                     R.string.nitro_player_skip_forward_seconds,

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

@@ -2,11 +2,16 @@ package com.margelo.nitro.nitroplayer.media
 
 import android.app.PendingIntent
 import android.content.Intent
+import android.net.Uri
 import android.os.Binder
 import android.os.Handler
 import android.os.IBinder
 import android.os.Looper
 import androidx.media3.cast.CastPlayer
+import androidx.media3.common.C
+import androidx.media3.common.ForwardingPlayer
+import androidx.media3.common.MediaItem
+import androidx.media3.common.Player
 import androidx.media3.common.util.UnstableApi
 import androidx.media3.exoplayer.ExoPlayer
 import androidx.media3.session.DefaultMediaNotificationProvider
@@ -14,7 +19,12 @@ import androidx.media3.session.MediaSession
 import androidx.media3.session.MediaSessionService
 import com.google.android.gms.cast.framework.CastContext
 import com.margelo.nitro.nitroplayer.core.NitroPlayerLogger
+import com.margelo.nitro.nitroplayer.core.checkUpcomingTracksForUrls
 import com.margelo.nitro.nitroplayer.core.TrackPlayerCore
+import com.margelo.nitro.nitroplayer.core.playFromMediaId
+import com.margelo.nitro.nitroplayer.core.playOnQueue
+import com.margelo.nitro.nitroplayer.core.skipToNextOnQueue
+import com.margelo.nitro.nitroplayer.core.skipToPreviousOnQueue
 import com.margelo.nitro.nitroplayer.playlist.PlaylistManager
 
 /**
@@ -51,6 +61,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
     // ── Created in onCreate ────────────────────────────────────────────────
     private lateinit var player: ExoPlayer
     private var mediaSession: MediaSession? = null
+    private lateinit var sessionPlayer: Player
     private var notificationProvider: DefaultMediaNotificationProvider? = null
     private val mainHandler = Handler(Looper.getMainLooper())
 
@@ -81,10 +92,79 @@ class NitroPlayerPlaybackService : MediaSessionService() {
         // Build ExoPlayer on main looper (default)
         player = ExoPlayerBuilder.build(this)
 
+        // The timeline is a window over the logical queue, so ExoPlayer's own prev/next would
+        // only ever move inside it — remote Previous seeks to 0 instead of the previous track.
+        // Route the remote controls through the same logical skips JS uses.
+        sessionPlayer =
+            object : ForwardingPlayer(player) {
+                override fun seekToPrevious() {
+                    trackPlayerCore?.skipToPreviousOnQueue() ?: super.seekToPrevious()
+                }
+
+                override fun seekToPreviousMediaItem() {
+                    trackPlayerCore?.skipToPreviousOnQueue() ?: super.seekToPreviousMediaItem()
+                }
+
+                override fun seekToNext() {
+                    trackPlayerCore?.skipToNextOnQueue() ?: super.seekToNext()
+                }
+
+                override fun seekToNextMediaItem() {
+                    trackPlayerCore?.skipToNextOnQueue() ?: super.seekToNextMediaItem()
+                }
+
+                // A controller's pick would otherwise load every track at once, bypassing the window and lazy URLs
+                override fun setMediaItems(
+                    mediaItems: MutableList<MediaItem>,
+                    resetPosition: Boolean,
+                ) {
+                    if (!playFromController(mediaItems, 0)) super.setMediaItems(mediaItems, resetPosition)
+                }
+
+                override fun setMediaItems(
+                    mediaItems: MutableList<MediaItem>,
+                    startIndex: Int,
+                    startPositionMs: Long,
+                ) {
+                    if (!playFromController(mediaItems, startIndex)) super.setMediaItems(mediaItems, startIndex, startPositionMs)
+                }
+
+                // Queued behind the load above, in the order the controller sent them
+                override fun prepare() {
+                    trackPlayerCore?.let { core -> core.enqueue { core.exo.prepare() } } ?: super.prepare()
+                }
+
+                override fun play() {
+                    trackPlayerCore?.let { core -> core.enqueue { core.playOnQueue() } } ?: super.play()
+                }
+
+                // Transcoded streams lack a length header, so ExoPlayer reads them as live: no bar or position in the car
+                override fun isCurrentMediaItemLive(): Boolean = super.isCurrentMediaItemLive() && knownDurationMs() == null
+
+                override fun getDuration(): Long = super.getDuration().takeIf { it != C.TIME_UNSET } ?: knownDurationMs() ?: C.TIME_UNSET
+
+                private fun knownDurationMs(): Long? = currentMediaItem?.mediaMetadata?.durationMs?.takeIf { it > 0 }
+
+                private fun playFromController(
+                    mediaItems: List<MediaItem>,
+                    startIndex: Int,
+                ): Boolean {
+                    val mediaId = mediaItems.getOrNull(maxOf(startIndex, 0))?.mediaId ?: return false
+                    if (mediaId == currentMediaItem?.mediaId && playerError == null) {
+                        // Re-picking a song still waiting for its URL asks the app for it again
+                        if (currentMediaItem?.localConfiguration?.uri == Uri.EMPTY) {
+                            trackPlayerCore?.let { core -> core.enqueue { core.checkUpcomingTracksForUrls(core.lookaheadCount, force = true) } }
+                        }
+                        return true
+                    }
+                    return trackPlayerCore?.playFromMediaId(mediaId) == true
+                }
+            }
+
         // Build MediaSession
         val playlistManager = PlaylistManager.getInstance(this)
         mediaSession = MediaSession
-            .Builder(this, player)
+            .Builder(this, sessionPlayer)
             .setCallback(MediaSessionCallbackFactory.create(this, playlistManager))
             .apply { buildSessionActivity()?.let { setSessionActivity(it) } }
             .build()
@@ -119,6 +199,7 @@ class NitroPlayerPlaybackService : MediaSessionService() {
                     castContext = castContext,
                     castPlayer = castPlayer,
                     localPlayer = player,
+                    localSessionPlayer = sessionPlayer,
                     mediaSession = mediaSession!!,
                     mainHandler = mainHandler,
                 )

package/android/src/main/java/com/margelo/nitro/nitroplayer/playlist/PlaylistManager.kt

@@ -1,6 +1,7 @@
 package com.margelo.nitro.nitroplayer.playlist
 
 import android.content.Context
+import com.margelo.nitro.JNIOnLoad
 import com.margelo.nitro.core.AnyMap
 import com.margelo.nitro.nitroplayer.QueueOperation
 import com.margelo.nitro.nitroplayer.TrackItem
@@ -59,6 +60,8 @@ class PlaylistManager private constructor(
     }
 
     init {
+        // Persisted extraPayloads are AnyMaps; a process started without JS has not loaded Nitro's JNI yet
+        JNIOnLoad.initializeNativeNitro()
         // Synchronous so no mutation can race a late async load and be clobbered
         loadPlaylistsFromFile()
     }
@@ -136,6 +139,18 @@ class PlaylistManager private constructor(
      */
     fun getPlaylist(playlistId: String): Playlist? = playlists[playlistId]
 
+    /** "trackId" or, for a repeated track, "trackId#index" as the car browser lists it; -1 when it is not in the playlist. */
+    fun indexOfTrackRef(
+        playlistId: String,
+        trackRef: String,
+    ): Int {
+        val tracks = playlists[playlistId]?.tracks ?: return -1
+        val exact = tracks.indexOfFirst { it.id == trackRef }
+        if (exact >= 0) return exact
+        val index = trackRef.substringAfterLast('#', "").toIntOrNull() ?: return -1
+        return index.takeIf { tracks.getOrNull(it)?.id == trackRef.substringBeforeLast('#') } ?: -1
+    }
+
     /**
      * Get all playlists
      */
@@ -249,6 +264,61 @@ class PlaylistManager private constructor(
         return true
     }
 
+    /** Removed count; null when the playlist does not exist. Unknown ids are ignored. */
+    fun removeTracksFromPlaylist(
+        playlistId: String,
+        trackIds: List<String>,
+    ): Int? {
+        val ids = trackIds.toHashSet()
+        var removed = 0
+        val found =
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                val tracks = playlist.tracks.toMutableList()
+                val before = tracks.size
+                if (tracks.removeAll { it.id in ids }) {
+                    removed = before - tracks.size
+                    playlist.copy(tracks = tracks)
+                } else {
+                    playlist
+                }
+            } != null
+        if (!found) return null
+        if (removed > 0) {
+            scheduleSave()
+            notifyPlaylistChanged(playlistId, QueueOperation.REMOVE)
+            NitroPlayerMediaBrowserService.getInstance()?.onPlaylistUpdated(playlistId)
+        }
+        return removed
+    }
+
+    /** Fisher-Yates; [firstTrackId] is pinned at index 0. Null when the playlist does not exist. */
+    fun shufflePlaylist(
+        playlistId: String,
+        firstTrackId: String?,
+    ): Boolean? {
+        var changed = false
+        val found =
+            playlists.computeIfPresent(playlistId) { _, playlist ->
+                val tracks = playlist.tracks.toMutableList()
+                val pinned = tracks.indexOfFirst { it.id == firstTrackId }.takeIf { it >= 0 }?.let { tracks.removeAt(it) }
+                tracks.shuffle()
+                pinned?.let { tracks.add(0, it) }
+                if (tracks.map { it.id } == playlist.tracks.map { it.id }) {
+                    playlist
+                } else {
+                    changed = true
+                    playlist.copy(tracks = tracks)
+                }
+            } != null
+        if (!found) return null
+        if (changed) {
+            scheduleSave()
+            notifyPlaylistChanged(playlistId, QueueOperation.UPDATE)
+            NitroPlayerMediaBrowserService.getInstance()?.onPlaylistUpdated(playlistId)
+        }
+        return changed
+    }
+
     /**
      * Update entire track objects across all playlists
      * Matches by track.id and replaces the entire track object
@@ -317,6 +387,11 @@ class PlaylistManager private constructor(
         return true
     }
 
+    /** Mirrors the core's current playlist (playSong bypasses loadPlaylist); Android Auto and persistence read this. */
+    fun setCurrentPlaylistId(playlistId: String?) {
+        currentPlaylistId = playlistId
+    }
+
     /**
      * Get the current playlist ID
      */

package/ios/cast/CastQueueDiff.swift

@@ -0,0 +1,58 @@
+// Pure receiver-queue diff: no Cast SDK types, no operation ever contains the current item.
+
+import Foundation
+
+enum CastQueueOp: Equatable {
+  case remove([String])
+  case insert([String])
+  case moveToEnd([String])
+  case moveBefore([String], anchor: String)
+}
+
+enum CastQueueDiff {
+  /// Converges in at most 4 ops. Caller guarantees `currentId` occurs exactly once in both lists.
+  static func nextOp(existing: [String], desired: [String], currentId: String) -> CastQueueOp? {
+    let desiredSet = Set(desired)
+    let existingSet = Set(existing)
+
+    let toRemove = existing.filter { !desiredSet.contains($0) }
+    if !toRemove.isEmpty { return .remove(toRemove) }
+
+    let toInsert = desired.filter { !existingSet.contains($0) }
+    if !toInsert.isEmpty { return .insert(toInsert) }
+
+    if existing == desired { return nil }
+    guard let cur = desired.firstIndex(of: currentId) else { return nil }
+
+    let after = Array(desired[(cur + 1)...])
+    if !after.isEmpty, Array(existing.suffix(after.count)) != after { return .moveToEnd(after) }
+
+    let before = Array(desired[..<cur])
+    if !before.isEmpty, Array(existing.prefix(before.count)) != before {
+      return .moveBefore(before, anchor: currentId)
+    }
+    return nil
+  }
+
+  static func apply(_ op: CastQueueOp, to existing: [String]) -> [String] {
+    switch op {
+    case .remove(let ids):
+      let dropped = Set(ids)
+      return existing.filter { !dropped.contains($0) }
+    case .insert(let ids):
+      return existing + ids
+    case .moveToEnd(let ids):
+      let moved = Set(ids)
+      return existing.filter { !moved.contains($0) } + ids
+    case .moveBefore(let ids, let anchor):
+      let moved = Set(ids)
+      var out: [String] = []
+      out.reserveCapacity(existing.count)
+      for id in existing where !moved.contains(id) {
+        if id == anchor { out.append(contentsOf: ids) }
+        out.append(id)
+      }
+      return out
+    }
+  }
+}