react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.12

package/android/src/main/java/com/audiobrowser/player/MediaSessionCallback.kt

@@ -12,6 +12,10 @@ import androidx.media3.session.SessionCommand
 import androidx.media3.session.SessionError
 import androidx.media3.session.SessionResult
 import com.audiobrowser.browser.handleTrackLoad
+import com.audiobrowser.browser.normalizedSections
+import com.audiobrowser.browser.styleResolvedSections
+import com.audiobrowser.browser.untitledSection
+import com.audiobrowser.extension.indexOfTappedTrack
 import com.audiobrowser.extension.toTrack
 import com.audiobrowser.util.BrowserPathHelper
 import com.audiobrowser.util.RatingFavorites
@@ -27,6 +31,8 @@ import com.margelo.nitro.audiobrowser.NativeGateRequest
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
 import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 import com.margelo.nitro.audiobrowser.SearchParams
+import com.margelo.nitro.audiobrowser.Section
+import com.margelo.nitro.audiobrowser.StyleDisplay
 import com.margelo.nitro.audiobrowser.Track
 import kotlinx.coroutines.CancellationException
 import kotlinx.coroutines.CoroutineScope
@@ -191,12 +197,17 @@ class MediaSessionCallback(private val player: Player) :
     command: SessionCommand,
     args: Bundle,
   ): ListenableFuture<SessionResult> {
-    // Handle favorite button tap
+    // Handle favorite button tap. Report an honest result: a success here makes
+    // the controller flip its heart optimistically, so a no-op (no current
+    // track) must say INVALID_STATE instead of success-then-revert.
     if (command.customAction == MediaSessionCommandManager.CUSTOM_ACTION_FAVORITE) {
-      val currentFavorited = player.currentTrack?.favorited ?: false
-      Timber.d("Favorite button tapped - toggling from $currentFavorited to ${!currentFavorited}")
-      player.setActiveTrackFavorited(!currentFavorited)
-      return Futures.immediateFuture(SessionResult(SessionResult.RESULT_SUCCESS))
+      val applied = player.toggleActiveTrackFavorited()
+      Timber.d("Favorite button tapped - toggle applied=$applied")
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
     }
 
     if (commandManager.handleCustomCommand(command, player)) {
@@ -212,8 +223,16 @@ class MediaSessionCallback(private val player: Player) :
   ): ListenableFuture<SessionResult> {
     // A heart rating from a controller (e.g. Google Assistant "I like this") toggles the
     // now-playing favorite. setActiveTrackFavorited fires onFavoriteChanged so the consumer
-    // persists it — the same path as the notification / CarPlay heart button.
-    RatingFavorites.favoritedFor(rating)?.let { player.setActiveTrackFavorited(it) }
+    // persists it — the same path as the notification / CarPlay heart button. Report an honest
+    // result (see onCustomCommand): INVALID_STATE when there is no current track to favorite.
+    RatingFavorites.favoritedFor(rating)?.let { favorited ->
+      val applied = player.setActiveTrackFavorited(favorited)
+      return Futures.immediateFuture(
+        SessionResult(
+          if (applied) SessionResult.RESULT_SUCCESS else SessionResult.RESULT_ERROR_INVALID_STATE
+        )
+      )
+    }
     return super.onSetRating(session, controller, rating)
   }
 
@@ -238,13 +257,11 @@ class MediaSessionCallback(private val player: Player) :
     }
 
     if (params?.isRecent == true) {
-      // TODO: support recent queries through something like onRecent and return a MediaItem with
-      // .setMediaId("__RECENT__") here - when onRecent is not configured we can keep returning an
-      // error here:
-
-      // The service currently does not support playback resumption. Tell System UI by returning
-      // an error of type 'RESULT_ERROR_NOT_SUPPORTED' for a `params.isRecent` request. See
-      // https://github.com/androidx/media/issues/355
+      // Playback resumption is served by media3 itself: it intercepts System UI's EXTRA_RECENT
+      // root request internally and answers through onPlaybackResumption, so that request never
+      // reaches this callback. Any other browser asking for a recent root gets
+      // ERROR_NOT_SUPPORTED — there is no browsable recents tree; recents are ordinary consumer
+      // content (a tab or route).
       return Futures.immediateFuture(LibraryResult.ofError(SessionError.ERROR_NOT_SUPPORTED))
     }
 
@@ -271,7 +288,7 @@ class MediaSessionCallback(private val player: Player) :
     params: MediaLibraryService.LibraryParams?,
   ): ListenableFuture<LibraryResult<ImmutableList<MediaItem>>> {
     Timber.d(
-      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSearchPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
+      "onGetChildren: {parentId: $parentId, page: $page, pageSize: $pageSize, isSpecialPath: ${BrowserPathHelper.isSpecialPath(parentId)} }"
     )
     return scope.future {
       // Wait for browser to be registered if it's not available yet
@@ -325,30 +342,28 @@ class MediaSessionCallback(private val player: Player) :
 
       try {
         val children =
-          if (parentId == BrowserPathHelper.RECENT_PATH) {
-            // TODO: implement recent media items
-            emptyList<MediaItem>()
-          } else if (parentId == BrowserPathHelper.ROOT_PATH) {
+          if (parentId == BrowserPathHelper.ROOT_PATH) {
             // Return tabs as root children (limited to 4 for automotive platform compatibility)
             // TODO: Check what Android Auto does with empty tabs list - may need to return error?
-            val tabs = browserManager.queryTabs()
+            // Disabled tabs hide (Track.disabled) — filtered before the cap so
+            // an unavailable tab never costs an available one its slot.
+            val tabs = browserManager.queryTabs().filterNot { it.disabled == true }
             if (tabs.size > 4) {
               Timber.w(
                 "Root has ${tabs.size} tabs; dropping ${tabs.size - 4} (Android Auto root limit)"
               )
             }
-            toMediaItems(tabs.take(4))
+            toFlatMediaItems(tabs.take(4))
           } else {
-            // Resolve the specific path and get its children
+            // Resolve the specific path and flatten its sections to MediaItems
+            // (paths are already set to contextual paths). Section styles come
+            // page-folded (`section ?? page`, ADR 0011).
             val resolvedTrack = browserManager.resolve(parentId)
-
-            // Convert children to MediaItems (url is already set to contextual URL)
-            val trackChildren =
-              resolvedTrack.children
-                ?: throw IllegalStateException(
-                  "Expected browsed ResolvedTrack to have a children array"
-                )
-            toMediaItems(trackChildren.toList())
+            val sections =
+              resolvedTrack.styleResolvedSections()
+                ?: throw IllegalStateException("Expected browsed ResolvedTrack to have sections")
+            browserManager.warnIfGridPageLacksPromise(parentId, sections)
+            toMediaItems(sections)
           }
 
         LibraryResult.ofItemList(ImmutableList.copyOf(children.paginate(page, pageSize)), params)
@@ -402,19 +417,45 @@ class MediaSessionCallback(private val player: Player) :
   }
 
   /**
-   * Converts tracks to MediaItems for browse delivery, routing http(s) artwork through the
-   * content:// provider so Android Auto can load it via the ArtworkContentProvider. Image-row
-   * tracks (a CarPlay-only rendering) are expanded into their items as regular grouped rows first —
-   * see [TrackFactory.expandImageRows].
+   * Flattens a page's sections to MediaItems for browse delivery — the Media3 boundary where
+   * sections die (ADR 0010): the MediaBrowser protocol has no section node, so each child is
+   * stamped with its owning section's title/style hints. A grid-displayed section with a `path`
+   * gains a browsable "view all" link under the same header. Http(s) artwork routes through the
+   * content:// provider so Android Auto can load it via the ArtworkContentProvider.
    */
-  private fun toMediaItems(tracks: List<Track>): List<MediaItem> {
+  private fun toMediaItems(sections: List<Section>): List<MediaItem> {
     val registry = player.browseArtworkRegistry
     val authority = com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-    return TrackFactory.expandImageRows(tracks).map {
-      TrackFactory.toBrowseMediaItem(it, registry, authority)
+    return sections.flatMap { section ->
+      // Android Auto has no disabled affordance, so an unavailable track hides
+      // — never a normal-looking dead row (Track.disabled's rendering ladder).
+      val visibleChildren = section.children.filter { it.disabled != true }
+      val items =
+        visibleChildren.map { TrackFactory.toBrowseMediaItem(it, registry, authority, section) }
+      val isTileSection = section.style?.display == StyleDisplay.GRID
+      // No "view all" under an empty section — CarPlay skips empty sections
+      // outright, and a lone navigation tile under a header is a dead end.
+      if (isTileSection && section.path != null && visibleChildren.isNotEmpty()) {
+        items +
+          TrackFactory.toBrowseMediaItem(
+            TrackFactory.navigationTrack(section),
+            registry,
+            authority,
+            section,
+          )
+      } else {
+        items
+      }
     }
   }
 
+  /**
+   * Flat lists (tabs, search results) convert as one untitled list section — which contributes no
+   * group or style hints — so exactly one Track→MediaItem path exists at the Media3 boundary.
+   */
+  private fun toFlatMediaItems(tracks: List<Track>): List<MediaItem> =
+    toMediaItems(listOf(untitledSection(tracks.toTypedArray())))
+
   override fun onGetItem(
     session: MediaLibraryService.MediaLibrarySession,
     browser: MediaSession.ControllerInfo,
@@ -451,7 +492,7 @@ class MediaSessionCallback(private val player: Player) :
         return@future LibraryResult.ofItem(createGateMediaItem(outcome.chrome!!), null)
       }
 
-      if (mediaId == BrowserPathHelper.ROOT_PATH || mediaId == BrowserPathHelper.RECENT_PATH) {
+      if (mediaId == BrowserPathHelper.ROOT_PATH) {
         return@future LibraryResult.ofItem(
           MediaItem.Builder()
             .setMediaId(mediaId)
@@ -466,7 +507,7 @@ class MediaSessionCallback(private val player: Player) :
       // Wait for browser to be registered if it's not available yet
       val browserManager = player.awaitBrowser().browserManager
 
-      // Serve tracks from the track cache first (keyed by url and src). Besides avoiding an HTTP
+      // Serve tracks from the track cache first (keyed by path and src). Besides avoiding an HTTP
       // resolve, this keeps item identity correct for contextual mediaIds: resolve() strips
       // __trackId and would return the *parent container's* metadata as the item.
       val browseAuthority =
@@ -628,7 +669,12 @@ class MediaSessionCallback(private val player: Player) :
       try {
         // Execute search (automatically caches results at /__search?q=query)
         val searchResults = browserManager.search(query)
-        val resultCount = searchResults.children?.size ?: 0
+        // Count what onGetSearchResult will actually serve: disabled tracks
+        // hide on Android Auto, so they must not inflate the announced count.
+        val resultCount =
+          searchResults.normalizedSections?.sumOf { section ->
+            section.children.count { it.disabled != true }
+          } ?: 0
 
         Timber.d("Search completed: $resultCount results for query '$query'")
 
@@ -681,14 +727,9 @@ class MediaSessionCallback(private val player: Player) :
       try {
         // Get cached search results from BrowserManager
         browserManager.getCachedSearchResults(query)?.let { tracks ->
-          // Convert to MediaItems
-          val searchAuthority =
-            com.audiobrowser.util.ArtworkUris.authorityFor(player.context.packageName)
-          val mediaItems =
-            tracks.map { track ->
-              Timber.d("Search result: ${track.title} (url=${track.url}, src=${track.src})")
-              TrackFactory.toBrowseMediaItem(track, player.browseArtworkRegistry, searchAuthority)
-            }
+          // Through the shared browse conversion, so search results get the
+          // same artwork routing as browse rows.
+          val mediaItems = toFlatMediaItems(tracks.toList())
 
           val paginatedItems = mediaItems.paginate(page, pageSize)
           Timber.d("Returning ${paginatedItems.size} search results")
@@ -737,26 +778,28 @@ class MediaSessionCallback(private val player: Player) :
 
       val browserManager = audioBrowser.browserManager
 
-      // A single tapped item resolves to the contextual url of the list it was
+      // A single tapped item resolves to the contextual path of the list it was
       // tapped in: directly for contextual mediaIds, via the track cache for
-      // stable-id mediaIds (see BrowserManager.contextualUrlFor). A search
+      // stable-id mediaIds (see BrowserManager.contextualPathFor). A search
       // selection is not a list tap — its queue comes from the search results
       // (resolveMediaItemsForPlayback), never from a browsed container.
-      val singleContextualUrl =
+      val singleContextualPath =
         mediaItems
           .singleOrNull()
           ?.takeIf { it.requestMetadata.searchQuery == null }
-          ?.let { browserManager.contextualUrlFor(it.mediaId) }
+          ?.let { browserManager.contextualPathFor(it.mediaId) }
 
       // Check if this is a single item from the current queue source
-      if (singleContextualUrl != null) {
-        val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
-        val trackId = BrowserPathHelper.extractTrackId(singleContextualUrl)
+      if (singleContextualPath != null) {
+        val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
+        val trackId = BrowserPathHelper.extractTrackId(singleContextualPath)
 
-        // Check if queue already came from this parent path - just skip to the track
+        // Check if queue already came from this parent path - just skip to the
+        // tapped surface (exact path first, identity for index-less paths —
+        // see indexOfTappedTrack)
         if (trackId != null && parentPath == player.queueSourcePath) {
           val queueTracks = withContext(Dispatchers.Main) { player.tracks }
-          val index = queueTracks.indexOfFirst { it.src == trackId }
+          val index = queueTracks.indexOfTappedTrack(singleContextualPath, trackId)
           if (index >= 0) {
             Timber.d("Queue already from $parentPath, skipping to index $index")
             val track = queueTracks[index]
@@ -788,9 +831,10 @@ class MediaSessionCallback(private val player: Player) :
         result.startIndex.toDouble(),
         ::currentPlayerState,
       ) {
-        // If this was a contextual URL expansion, track the source path (only for default behavior)
-        if (singleContextualUrl != null) {
-          val parentPath = BrowserPathHelper.stripTrackId(singleContextualUrl)
+        // If this was a contextual path expansion, track the source path (only for default
+        // behavior)
+        if (singleContextualPath != null) {
+          val parentPath = BrowserPathHelper.stripTrackId(singleContextualPath)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
         }
         result
@@ -829,6 +873,15 @@ class MediaSessionCallback(private val player: Player) :
             throw IllegalStateException("No playback state to resume")
           }
 
+      // The persisted track can carry `disabled` — it became unavailable after
+      // it was saved. A disabled track never plays, resumption included
+      // (Track.disabled); failing the future refuses without touching the
+      // player.
+      if (state.track.disabled == true) {
+        Timber.w("Refusing resumption of disabled track: ${state.track.title}")
+        throw IllegalStateException("Persisted track is disabled")
+      }
+
       // isForPlayback == false is the device-boot-time notification case: network may be
       // unavailable and we must not start playback. Return just the locally-stored track with its
       // already-local metadata; skip the settings restore and network queue expansion below.
@@ -844,14 +897,14 @@ class MediaSessionCallback(private val player: Player) :
       // restore() sets player properties which must happen on main thread
       withContext(Dispatchers.Main) { player.playbackStateStore.restore() }
 
-      val url = state.track.url
-      Timber.d("Resuming from url=$url, positionMs=${state.positionMs}")
+      val path = state.track.path
+      Timber.d("Resuming from path=$path, positionMs=${state.positionMs}")
 
       // Wait for browser to be available (JS needs to have configured it)
       val browserManager = player.awaitBrowser().browserManager
 
-      // Try to expand the URL into a full queue
-      val expanded = url?.let { browserManager.expandQueueFromContextualUrl(it) }
+      // Try to expand the path into a full queue
+      val expanded = path?.let { browserManager.expandQueueFromContextualPath(it) }
 
       if (expanded != null) {
         val (tracks, selectedIndex) = expanded
@@ -859,9 +912,9 @@ class MediaSessionCallback(private val player: Player) :
           "Restored ${tracks.size} tracks, starting at index $selectedIndex at ${state.positionMs}ms"
         )
 
-        // Track the source path if this was a contextual URL expansion
-        if (BrowserPathHelper.isContextual(url)) {
-          val parentPath = BrowserPathHelper.stripTrackId(url)
+        // Track the source path if this was a contextual path expansion
+        if (BrowserPathHelper.isContextual(path)) {
+          val parentPath = BrowserPathHelper.stripTrackId(path)
           withContext(Dispatchers.Main) { player.queueSourcePath = parentPath }
         }
 

package/android/src/main/java/com/audiobrowser/player/NowPlayingUpdater.kt

@@ -1,5 +1,6 @@
 package com.audiobrowser.player
 
+import com.audiobrowser.extension.identity
 import com.audiobrowser.util.url
 import com.margelo.nitro.audiobrowser.FormatNowPlayingParams
 import com.margelo.nitro.audiobrowser.NowPlayingMetadata
@@ -105,10 +106,11 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
   private var lastPublished: Published? = null
 
   /**
-   * The track id whose now-playing artwork has been resolved (or is being resolved), so a
-   * `nowPlayingArtwork` resolve runs once per track instead of on every render.
+   * The track identity (id-or-src, falling back to path — same key as [Published]) whose
+   * now-playing artwork has been resolved (or is being resolved), so a `nowPlayingArtwork` resolve
+   * runs once per track — id-less tracks included — instead of on every render.
    */
-  private var artworkResolvedForTrackId: String? = null
+  private var artworkResolvedForTrack: String? = null
 
   /** Size hint (px, square) for now-playing artwork. Mirrors iOS (screen-width-capped to 1200). */
   private val artworkSizePx = 1200.0
@@ -164,7 +166,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
       duration = track.duration,
       artwork = track.artwork?.url,
       description = track.description,
-      mediaId = track.src ?: track.url,
+      mediaId = track.src ?: track.path,
       genre = track.genre,
     )
   }
@@ -227,7 +229,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
     // default on null/throw.
     val activeFormatter = if (enabled) formatter else null
     if (activeFormatter != null) {
-      val capturedId = track.src ?: track.url
+      val capturedId = track.src ?: track.path
       // Gate the raw load-control signal to the buffering state so `stalled` is correct on its
       // own: ExoPlayer's rebuffering flag is polled on a different cadence than state transitions
       // and can linger true into the PLAYING transition as a rebuffer recovers. Classify by
@@ -266,7 +268,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
           formatted != null &&
             current != null &&
             currentIdx != null &&
-            (current.src ?: current.url) == capturedId &&
+            (current.src ?: current.path) == capturedId &&
             renderGeneration == generation
         ) {
           applyFields(
@@ -293,7 +295,7 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
     // the same fields are recomputed often; an unconditional stamp would churn the MediaSession
     // (and flicker Android Auto / now-playing) for no visible change. Keyed on the track identity
     // so a new track with a coincidentally identical line still publishes.
-    val published = Published(index, track.src ?: track.url, title, secondaryLine, album)
+    val published = Published(index, track.identity ?: track.path, title, secondaryLine, album)
     if (published == lastPublished) return
     lastPublished = published
 
@@ -307,28 +309,23 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
 
   /**
    * Resolves the playing track's now-playing artwork and stamps it onto the playing media item.
-   * Guarded exactly like iOS: only when `nowPlayingArtwork` is configured AND the track has a
-   * non-empty id (so the `{id}` token never resolves to an empty string). Otherwise the existing
-   * artworkUri — which came from `artwork` (browse list path) — is left in place.
+   * Runs for EVERY playing track when `nowPlayingArtwork` is configured — id or not, exactly like
+   * iOS (an id-less track leaves any `{id}` token unfilled; the resolver warns and the request
+   * visibly 404s). Without a config, the existing artworkUri — which came from `artwork` (browse
+   * list path) — is left in place.
    */
   private fun maybeResolveArtwork(track: Track) {
-    val trackId =
-      track.id?.takeIf { it.isNotEmpty() }
-        ?: run {
-          // No id → skip nowPlayingArtwork entirely; keep the existing (browse) artworkUri.
-          artworkResolvedForTrackId = null
-          return
-        }
-
     if (!surface.hasNowPlayingArtworkConfig) {
       // No now-playing artwork config (or no browser) → fall back to the existing artworkUri.
-      artworkResolvedForTrackId = null
+      artworkResolvedForTrack = null
       return
     }
 
-    // Already resolved (or resolving) for this track id — avoid a redundant resolve per render.
-    if (artworkResolvedForTrackId == trackId) return
-    artworkResolvedForTrackId = trackId
+    // Already resolved (or resolving) for this track — avoid a redundant resolve per render.
+    // Keyed on track identity (id-or-src, falling back to path) so id-less tracks dedupe too.
+    val trackKey = track.identity ?: track.path
+    if (trackKey != null && artworkResolvedForTrack == trackKey) return
+    artworkResolvedForTrack = trackKey
 
     scope.launch {
       val uri =
@@ -336,10 +333,10 @@ class NowPlayingUpdater(private val surface: NowPlayingSurface, private val scop
           ?: return@launch
 
       // Apply only if still the same track (a fast skip must not be overwritten by a stale
-      // result).
+      // result), compared on the same identity key the resolve was launched under.
       val currentIdx = surface.currentIndex ?: return@launch
       val current = surface.currentTrack ?: return@launch
-      if (current.id != trackId) return@launch
+      if ((current.identity ?: current.path) != trackKey) return@launch
 
       surface.stampArtwork(currentIdx, current, uri)
     }

package/android/src/main/java/com/audiobrowser/player/PlaybackStateStore.kt

@@ -5,6 +5,9 @@ import android.content.SharedPreferences
 import androidx.core.content.edit
 import androidx.media3.common.C
 import com.audiobrowser.util.artworkOf
+import com.audiobrowser.util.toArtworkRendering
+import com.audiobrowser.util.toStyleDisplay
+import com.audiobrowser.util.toWireString
 import com.audiobrowser.util.url
 import com.margelo.nitro.audiobrowser.PlaybackState
 import com.margelo.nitro.audiobrowser.RepeatMode
@@ -18,12 +21,12 @@ import org.json.JSONObject
 import timber.log.Timber
 
 /**
- * Persists playback state for resumption after app restart. Stores the current track URL, position,
- * and player settings to enable playback resumption via MediaButtonReceiver (Bluetooth play button,
- * etc.).
+ * Persists playback state for resumption after app restart. Stores the current track (including its
+ * path), position, and player settings to enable playback resumption via MediaButtonReceiver
+ * (Bluetooth play button, etc.).
  *
  * Settings (repeatMode, shuffleEnabled, playbackSpeed) are auto-persisted when set via properties.
- * Position/URL are persisted via save() on pause or track change.
+ * Position/track are persisted via save() on pause or track change.
  */
 class PlaybackStateStore(private val player: Player) {
   private val prefs: SharedPreferences =
@@ -32,7 +35,7 @@ class PlaybackStateStore(private val player: Player) {
   /**
    * Persisted playback state for resumption.
    *
-   * @param track The track being played (includes url for queue expansion)
+   * @param track The track being played (includes path for queue expansion)
    * @param positionMs The playback position in milliseconds (C.TIME_UNSET for default/live edge)
    * @param repeatMode The repeat mode setting
    * @param shuffleEnabled Whether shuffle mode was enabled
@@ -148,78 +151,11 @@ class PlaybackStateStore(private val player: Player) {
     Timber.d("Saved position: positionMs=0 (queue ended)")
   }
 
-  private fun trackToJson(track: Track): String =
-    JSONObject()
-      .apply {
-        put("id", track.id)
-        put("url", track.url)
-        put("src", track.src)
-        put("title", track.title)
-        put("subtitle", track.subtitle)
-        put("artist", track.artist)
-        put("albumUrl", track.albumUrl)
-        put("album", track.album)
-        put("artwork", track.artwork?.url)
-        put("description", track.description)
-        put("genre", track.genre)
-        put("duration", track.duration)
-        put("style", track.style?.name)
-        put("childrenStyle", track.childrenStyle?.name)
-        put("favorited", track.favorited)
-        put("groupTitle", track.groupTitle)
-        put("live", track.live)
-      }
-      .toString()
-
-  private fun trackFromJson(json: String): Track? =
-    runCatching {
-        val obj = JSONObject(json)
-        Track(
-          id = obj.optString("id").takeIf { it.isNotEmpty() },
-          url = obj.optString("url").takeIf { it.isNotEmpty() },
-          src = obj.optString("src").takeIf { it.isNotEmpty() },
-          title = obj.getString("title"),
-          subtitle = obj.optString("subtitle").takeIf { it.isNotEmpty() },
-          artist = obj.optString("artist").takeIf { it.isNotEmpty() },
-          albumUrl = obj.optString("albumUrl").takeIf { it.isNotEmpty() },
-          album = obj.optString("album").takeIf { it.isNotEmpty() },
-          artwork = artworkOf(obj.optString("artwork").takeIf { it.isNotEmpty() }),
-          artworkSource = null, // Not persisted - will be re-transformed on browse
-          artworkCarPlayTinted = null, // iOS-only, not persisted
-          description = obj.optString("description").takeIf { it.isNotEmpty() },
-          genre = obj.optString("genre").takeIf { it.isNotEmpty() },
-          duration =
-            if (obj.has("duration") && !obj.isNull("duration")) obj.getDouble("duration") else null,
-          style =
-            obj
-              .optString("style")
-              .takeIf { it.isNotEmpty() }
-              ?.let { runCatching { TrackStyle.valueOf(it) }.getOrNull() },
-          childrenStyle =
-            obj
-              .optString("childrenStyle")
-              .takeIf { it.isNotEmpty() }
-              ?.let { runCatching { TrackStyle.valueOf(it) }.getOrNull() },
-          favorited =
-            if (obj.has("favorited") && !obj.isNull("favorited")) obj.getBoolean("favorited")
-            else null,
-          groupTitle = obj.optString("groupTitle").takeIf { it.isNotEmpty() },
-          live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
-          // Not persisted: on resumption the contextual URL is re-browsed
-          // (expandQueueFromContextualUrl), which re-parses each track's request
-          // from the API's current response and re-caches it.
-          request = null,
-          imageRow = null, // Not persisted
-        )
-      }
-      .onFailure { e -> Timber.w(e, "Failed to parse persisted track JSON") }
-      .getOrNull()
-
   /**
    * Restores player settings from persisted state and returns the state for queue setup.
    *
    * Applies repeatMode, shuffleMode, and playbackSpeed to the player. The caller is responsible for
-   * using the returned url and positionMs to set up the playback queue.
+   * using the returned path and positionMs to set up the playback queue.
    *
    * @return PersistedState if available, null otherwise
    */
@@ -255,6 +191,90 @@ class PlaybackStateStore(private val player: Player) {
   }
 
   companion object {
+    // Internal (not private) so the round-trip is testable without a Player.
+    internal fun trackToJson(track: Track): String =
+      JSONObject()
+        .apply {
+          put("id", track.id)
+          put("path", track.path)
+          put("src", track.src)
+          put("title", track.title)
+          put("subtitle", track.subtitle)
+          put("artist", track.artist)
+          put("albumPath", track.albumPath)
+          put("album", track.album)
+          put("artwork", track.artwork?.url)
+          put("description", track.description)
+          put("genre", track.genre)
+          put("duration", track.duration)
+          // The style block persists as its wire shape (nested object, wire
+          // strings) and `disabled` beside it: a restored queue keeps its
+          // visible fidelity across process death (ADR 0011).
+          put(
+            "style",
+            track.style?.let { style ->
+              JSONObject().apply {
+                put("display", style.display?.toWireString())
+                put("artworkRendering", style.artworkRendering?.toWireString())
+              }
+            },
+          )
+          put("disabled", track.disabled)
+          put("favorited", track.favorited)
+          put("live", track.live)
+        }
+        .toString()
+
+    internal fun trackFromJson(json: String): Track? =
+      runCatching {
+          val obj = JSONObject(json)
+          Track(
+            id = obj.optString("id").takeIf { it.isNotEmpty() },
+            path = obj.optString("path").takeIf { it.isNotEmpty() },
+            src = obj.optString("src").takeIf { it.isNotEmpty() },
+            title = obj.getString("title"),
+            subtitle = obj.optString("subtitle").takeIf { it.isNotEmpty() },
+            artist = obj.optString("artist").takeIf { it.isNotEmpty() },
+            albumPath = obj.optString("albumPath").takeIf { it.isNotEmpty() },
+            album = obj.optString("album").takeIf { it.isNotEmpty() },
+            artwork = artworkOf(obj.optString("artwork").takeIf { it.isNotEmpty() }),
+            artworkSource = null, // Not persisted - will be re-transformed on browse
+            description = obj.optString("description").takeIf { it.isNotEmpty() },
+            genre = obj.optString("genre").takeIf { it.isNotEmpty() },
+            duration =
+              if (obj.has("duration") && !obj.isNull("duration")) obj.getDouble("duration")
+              else null,
+            // Tolerant (ADR 0011): a snapshot written before the block model —
+            // `style` as an enum-name string — is not an object, so optJSONObject
+            // yields null and the track restores without a declaration.
+            style =
+              obj
+                .optJSONObject("style")
+                ?.let { style ->
+                  TrackStyle(
+                    display = style.optString("display").toStyleDisplay(),
+                    artworkRendering = style.optString("artworkRendering").toArtworkRendering(),
+                  )
+                }
+                // An empty block collapses to "no declaration" — one shape on
+                // every platform, matching the browse decoders.
+                ?.takeIf { it.display != null || it.artworkRendering != null },
+            disabled =
+              if (obj.has("disabled") && !obj.isNull("disabled")) obj.getBoolean("disabled")
+              else null,
+            favorited =
+              if (obj.has("favorited") && !obj.isNull("favorited")) obj.getBoolean("favorited")
+              else null,
+            live = if (obj.has("live") && !obj.isNull("live")) obj.getBoolean("live") else null,
+            // Not persisted: on resumption the contextual path is re-browsed
+            // (expandQueueFromContextualPath), which re-parses each track's request
+            // from the API's current response and re-caches it.
+            request = null,
+          )
+        }
+        .onFailure { e -> Timber.w(e, "Failed to parse persisted track JSON") }
+        .getOrNull()
+
     private const val PREFS_NAME = "audio_browser_playback_state_v3"
     private const val KEY_POSITION_MS = "position_ms"
     private const val KEY_REPEAT_MODE = "repeat_mode"