react-native-audio-browser 0.1.1 → 0.2.0-next.1

package/android/src/main/java/com/audiobrowser/http/RequestConfigBuilder.kt

@@ -2,11 +2,11 @@ package com.audiobrowser.http
 
 import com.audiobrowser.util.BrowserPathHelper
 import com.margelo.nitro.audiobrowser.ArtworkRequestConfig
-import com.margelo.nitro.audiobrowser.ImageContext
 import com.margelo.nitro.audiobrowser.MediaRequestConfig
-import com.margelo.nitro.audiobrowser.MediaTransformParams
 import com.margelo.nitro.audiobrowser.RequestConfig
+import com.margelo.nitro.audiobrowser.Track
 import com.margelo.nitro.audiobrowser.TransformableRequestConfig
+import com.margelo.nitro.core.Promise
 import java.net.URLEncoder
 import kotlinx.coroutines.Dispatchers
 import kotlinx.coroutines.withContext
@@ -43,6 +43,49 @@ object RequestConfigBuilder {
     )
   }
 
+  /**
+   * Run-both resolve composition: the async-resolved config first, then the sync-resolved merged
+   * over it (sync winning). Returns null when neither produced a config. Extracted so the merge
+   * ordering is unit-testable without Nitro callbacks; used by [applyMediaResolve] and the artwork
+   * resolve in BrowserUrlResolution.
+   */
+  fun composeResolved(asyncResolved: RequestConfig?, syncResolved: RequestConfig?): RequestConfig? {
+    return when {
+      asyncResolved == null -> syncResolved
+      syncResolved == null -> asyncResolved
+      else -> mergeConfig(asyncResolved, syncResolved)
+    }
+  }
+
+  /**
+   * Awaits an **async** config callback. It lowers to `Promise<Promise<RequestConfig>>` (bridge hop
+   * → JS promise), so it is a DOUBLE await. That depth is the bug-prone part (single-awaiting an
+   * async callback hands a `Promise` downstream — the original "empty config" bug), so it lives in
+   * exactly one place. Pairs with [awaitSyncConfig].
+   */
+  suspend fun awaitAsyncConfig(promise: Promise<Promise<RequestConfig>>): RequestConfig =
+    promise.await().await()
+
+  /** Awaits a **sync** config callback (`Promise<RequestConfig>` — a single await). */
+  suspend fun awaitSyncConfig(promise: Promise<RequestConfig>): RequestConfig = promise.await()
+
+  /** Rebuilds a [MediaRequestConfig] with [c]'s request fields, preserving callbacks. */
+  private fun MediaRequestConfig.withRequestFields(c: RequestConfig) =
+    MediaRequestConfig(
+      resolve = resolve,
+      resolveSync = resolveSync,
+      transform = transform,
+      transformSync = transformSync,
+      method = c.method,
+      path = c.path,
+      baseUrl = c.baseUrl,
+      headers = c.headers,
+      query = c.query,
+      body = c.body,
+      contentType = c.contentType,
+      userAgent = c.userAgent,
+    )
+
   suspend fun mergeConfig(
     base: RequestConfig,
     override: TransformableRequestConfig,
@@ -50,117 +93,86 @@ object RequestConfigBuilder {
     return mergeConfig(base, override, emptyMap())
   }
 
+  /**
+   * Request-Config Layer application: a transform (async and/or sync) wins completely — with both
+   * set they run as a pipeline, async first, then sync, each replacing the running config —
+   * otherwise the override's static fields merge over the base, EXCEPT `path`, which is carried
+   * from the base (only a transform may change it; mirrors iOS `applyLayer` and the web stub). A
+   * thrown transform falls back to the base.
+   */
   suspend fun mergeConfig(
     base: RequestConfig,
     override: TransformableRequestConfig,
     routeParams: Map<String, String>? = null,
   ): RequestConfig {
-    // Apply transform function if provided
-    return override.transform?.let { transformFn ->
-      try {
-        transformFn.invoke(base, routeParams).await().await() // Transform result wins completely
-      } catch (e: Exception) {
-        Timber.e(e, "Failed to apply transform function, using base config")
-        base
-      }
-    } ?: mergeConfig(base, toRequestConfig(override)) // Only merge if no transform
+    if (override.transform == null && override.transformSync == null) {
+      return mergeConfig(base, toRequestConfig(override)).copy(path = base.path)
+    }
+    return try {
+      // Async first, then sync (each replaces the running config). The bridge await
+      // depth is centralised in awaitAsync/SyncConfig.
+      var result = base
+      override.transform?.let { result = awaitAsyncConfig(it.invoke(result, routeParams)) }
+      override.transformSync?.let { result = awaitSyncConfig(it.invoke(result, routeParams)) }
+      result
+    } catch (e: Exception) {
+      Timber.e(e, "Failed to apply transform function, using base config")
+      base
+    }
   }
 
+  /**
+   * Media-kind layer application. A media config's transform/transformSync have the same shape as a
+   * [TransformableRequestConfig]'s, so this delegates to the layer overload above and rewraps — the
+   * layer semantics live in one place.
+   */
   suspend fun mergeConfig(
     base: RequestConfig,
     override: MediaRequestConfig,
     routeParams: Map<String, String>? = null,
-  ): MediaRequestConfig {
-    // Apply transform function if provided - transform result wins completely
-    val finalConfig: RequestConfig =
-      override.transform?.let { transformFn ->
-        try {
-          Timber.d("Invoking media transform for URL: ${base.path}")
-          val transformed = transformFn.invoke(base, routeParams).await().await()
-          Timber.d(
-            "Media transform result: path=${transformed.path}, baseUrl=${transformed.baseUrl}, headers=${transformed.headers}, userAgent=${transformed.userAgent}"
-          )
-          transformed
-        } catch (e: Exception) {
-          Timber.e(e, "Failed to apply media transform function, using base config")
-          base
-        }
-      }
-        ?: RequestConfig(
-          path = override.path ?: base.path,
-          method = override.method ?: base.method,
-          baseUrl = override.baseUrl ?: base.baseUrl,
-          headers = mergeHeaders(base.headers, override.headers),
-          query = mergeQuery(base.query, override.query),
-          body = override.body ?: base.body,
-          contentType = override.contentType ?: base.contentType,
-          userAgent = override.userAgent ?: base.userAgent,
-        )
-
-    // Wrap the final RequestConfig in MediaRequestConfig to preserve resolve callback
-    return MediaRequestConfig(
-      resolve = override.resolve,
-      transform = override.transform,
-      method = finalConfig.method,
-      path = finalConfig.path,
-      baseUrl = finalConfig.baseUrl,
-      headers = finalConfig.headers,
-      query = finalConfig.query,
-      body = finalConfig.body,
-      contentType = finalConfig.contentType,
-      userAgent = finalConfig.userAgent,
+  ): MediaRequestConfig =
+    override.withRequestFields(mergeConfig(base, override.asTransformable(), routeParams))
+
+  private fun MediaRequestConfig.asTransformable() =
+    TransformableRequestConfig(
+      transform = transform,
+      transformSync = transformSync,
+      method = method,
+      path = path,
+      baseUrl = baseUrl,
+      headers = headers,
+      query = query,
+      body = body,
+      contentType = contentType,
+      userAgent = userAgent,
     )
-  }
 
   /**
-   * Merges artwork request config with base config, applying transform with ImageContext.
-   * Used for artwork URL transformation where size hints are needed.
+   * Applies the per-track `media.resolve(track)` callback as the final, most-specific layer over an
+   * already request+media-layered config. The callback receives the full Track — carrying any
+   * per-track `request` override (e.g. a strict-UA sentinel the consumer swaps for a clean
+   * User-Agent) — and returns the config whose fields win.
+   *
+   * No-op when the media config has no `resolve` callback or no track is available (so the
+   * request/media layers stand). The callback may return its config synchronously (variant `first`)
+   * or via a Promise (`second`). Mirrors iOS resolveMediaTrackConfig + applyMediaResolveLayer.
    */
-  suspend fun mergeConfig(
-    base: RequestConfig,
-    override: ArtworkRequestConfig,
-    imageContext: ImageContext? = null,
-  ): ArtworkRequestConfig {
-    // Apply transform function if provided - transform result wins completely
-    val finalConfig: RequestConfig =
-      override.transform?.let { transformFn ->
-        try {
-          Timber.d("Invoking artwork transform for URL: ${base.path}")
-          val transformed = transformFn.invoke(MediaTransformParams(base, imageContext)).await().await()
-          Timber.d(
-            "Artwork transform result: path=${transformed.path}, baseUrl=${transformed.baseUrl}, headers=${transformed.headers}, userAgent=${transformed.userAgent}"
-          )
-          transformed
-        } catch (e: Exception) {
-          Timber.e(e, "Failed to apply artwork transform function, using base config")
-          base
-        }
+  suspend fun applyMediaResolve(layered: MediaRequestConfig, track: Track?): MediaRequestConfig {
+    if (track == null) return layered
+    if (layered.resolve == null && layered.resolveSync == null) return layered
+    val resolved: RequestConfig =
+      try {
+        // Async first, then sync (merged, sync winning) — via the tested helper.
+        val asyncResolved = layered.resolve?.let { awaitAsyncConfig(it.invoke(track)) }
+        val syncResolved = layered.resolveSync?.let { awaitSyncConfig(it.invoke(track)) }
+        composeResolved(asyncResolved, syncResolved) ?: return layered
+      } catch (e: Exception) {
+        Timber.e(e, "Failed to apply media.resolve, using layered config")
+        return layered
       }
-        ?: RequestConfig(
-          path = override.path ?: base.path,
-          method = override.method ?: base.method,
-          baseUrl = override.baseUrl ?: base.baseUrl,
-          headers = mergeHeaders(base.headers, override.headers),
-          query = mergeQuery(base.query, override.query),
-          body = override.body ?: base.body,
-          contentType = override.contentType ?: base.contentType,
-          userAgent = override.userAgent ?: base.userAgent,
-        )
-
-    // Wrap the final RequestConfig in ArtworkRequestConfig to preserve callbacks and query params
-    return ArtworkRequestConfig(
-      resolve = override.resolve,
-      transform = override.transform,
-      imageQueryParams = override.imageQueryParams,
-      method = finalConfig.method,
-      path = finalConfig.path,
-      baseUrl = finalConfig.baseUrl,
-      headers = finalConfig.headers,
-      query = finalConfig.query,
-      body = finalConfig.body,
-      contentType = finalConfig.contentType,
-      userAgent = finalConfig.userAgent,
-    )
+    // Resolve wins: merge it over the layered config (override-wins on every field).
+    val merged = mergeConfig(toRequestConfig(layered), resolved)
+    return layered.withRequestFields(merged)
   }
 
   fun toRequestConfig(artworkConfig: ArtworkRequestConfig): RequestConfig {

package/android/src/main/java/com/audiobrowser/model/PlaybackMetadata.kt

@@ -14,12 +14,14 @@ data class PlaybackMetadata(
 ) {
   companion object {
     /**
-     * Creates PlaybackMetadata from raw Metadata entries.
-     * Handles ICY streams specially, uses Media3's unified approach for everything else.
+     * Creates PlaybackMetadata from raw Metadata entries. Handles ICY streams specially, uses
+     * Media3's unified approach for everything else.
      */
     fun from(metadata: Metadata): PlaybackMetadata? {
       // Try ICY first (streaming-specific)
-      fromIcy(metadata)?.let { return it }
+      fromIcy(metadata)?.let {
+        return it
+      }
 
       // Use Media3's unified approach for ID3, Vorbis, QuickTime, etc.
       val builder = MediaMetadata.Builder()
@@ -69,12 +71,6 @@ data class PlaybackMetadata(
   }
 
   fun toNitro(): TimedMetadata {
-    return TimedMetadata(
-      title = title,
-      artist = artist,
-      album = album,
-      date = date,
-      genre = genre,
-    )
+    return TimedMetadata(title = title, artist = artist, album = album, date = date, genre = genre)
   }
 }

package/android/src/main/java/com/audiobrowser/model/PlayerSetupOptions.kt

@@ -3,7 +3,8 @@ package com.audiobrowser.model
 import androidx.media3.exoplayer.DefaultLoadControl
 import com.margelo.nitro.audiobrowser.AndroidAudioContentType
 import com.margelo.nitro.audiobrowser.AndroidPlayerWakeMode
-import com.margelo.nitro.audiobrowser.PartialSetupPlayerOptions
+import com.margelo.nitro.audiobrowser.Func_std__shared_ptr_Promise_std__optional_NowPlayingUpdate____FormatNowPlayingParams as NowPlayingFormatter
+import com.margelo.nitro.audiobrowser.NativeSetupPlayerOptions
 import com.margelo.nitro.audiobrowser.Variant_Boolean_AndroidAudioOffloadSettings
 import com.margelo.nitro.audiobrowser.Variant_Boolean_RetryConfig
 
@@ -22,10 +23,17 @@ sealed class RetryPolicy {
   data object Default : RetryPolicy()
 
   /** Retry indefinitely with exponential backoff */
-  data class Infinite(val maxRetryDurationMs: Long? = null) : RetryPolicy()
+  data class Infinite(
+    val maxRetryDurationMs: Long? = null,
+    val firstConnectMaxRetryDurationMs: Long? = null,
+  ) : RetryPolicy()
 
   /** Retry up to maxRetries times with exponential backoff */
-  data class Limited(val maxRetries: Int, val maxRetryDurationMs: Long? = null) : RetryPolicy()
+  data class Limited(
+    val maxRetries: Int,
+    val maxRetryDurationMs: Long? = null,
+    val firstConnectMaxRetryDurationMs: Long? = null,
+  ) : RetryPolicy()
 }
 
 /**
@@ -45,6 +53,15 @@ data class PlayerSetupOptions(
   var wakeMode: AndroidPlayerWakeMode = AndroidPlayerWakeMode.NONE,
   var audioOffload: AudioOffloadOptions? = null,
   var retryPolicy: RetryPolicy = RetryPolicy.Default,
+  // Keep the media session alive & controllable through a terminal playback error so external
+  // controllers (Android Auto) keep their transport controls instead of tearing the session down.
+  // Default on: matches iOS, where the session always survives errors.
+  var keepSessionAliveOnError: Boolean = true,
+  // Whether the player publishes/refreshes track metadata on the now-playing surface.
+  var autoUpdateNowPlayingMetadata: Boolean = true,
+  // Optional JS formatter that customizes the now-playing title/subtitle from the track + live
+  // timed metadata. When null, the default mapping is used.
+  var nowPlayingMetadataFormatter: NowPlayingFormatter? = null,
 ) {
   /**
    * Whether automatic buffer management is enabled. True when rebufferBuffer is not explicitly set
@@ -53,7 +70,7 @@ data class PlayerSetupOptions(
   val automaticBuffer: Boolean
     get() = rebufferBuffer == null
 
-  fun update(options: PartialSetupPlayerOptions) {
+  fun update(options: NativeSetupPlayerOptions) {
     // Android-specific options
     options.android?.let { android ->
       android.minBuffer?.let { minBuffer = it }
@@ -90,12 +107,27 @@ data class PlayerSetupOptions(
             if (it.value) RetryPolicy.Infinite() else RetryPolicy.Default
           }
           is Variant_Boolean_RetryConfig.Second -> {
-            RetryPolicy.Limited(
-              maxRetries = it.value.maxRetries.toInt(),
-              maxRetryDurationMs = it.value.maxRetryDurationMs?.toLong(),
-            )
+            val maxRetries = it.value.maxRetries?.toInt()
+            val maxDurationMs = it.value.maxRetryDurationMs?.toLong()
+            val firstConnectMs = it.value.firstConnectMaxRetryDurationMs?.toLong()
+            // No attempt cap = retry indefinitely, bounded only by the durations.
+            if (maxRetries == null)
+              RetryPolicy.Infinite(
+                maxRetryDurationMs = maxDurationMs,
+                firstConnectMaxRetryDurationMs = firstConnectMs,
+              )
+            else
+              RetryPolicy.Limited(
+                maxRetries = maxRetries,
+                maxRetryDurationMs = maxDurationMs,
+                firstConnectMaxRetryDurationMs = firstConnectMs,
+              )
           }
         }
     }
+
+    options.keepSessionAliveOnError?.let { keepSessionAliveOnError = it }
+    options.autoUpdateNowPlayingMetadata?.let { autoUpdateNowPlayingMetadata = it }
+    options.nowPlayingMetadataFormatter?.let { nowPlayingMetadataFormatter = it }
   }
 }

package/android/src/main/java/com/audiobrowser/model/PlayerUpdateOptions.kt

@@ -1,12 +1,11 @@
 package com.audiobrowser.model
 
-import com.margelo.nitro.audiobrowser.AndroidUpdateOptions
+import com.margelo.nitro.audiobrowser.AndroidOptions
 import com.margelo.nitro.audiobrowser.AppKilledPlaybackBehavior
 import com.margelo.nitro.audiobrowser.NativeUpdateOptions
 import com.margelo.nitro.audiobrowser.NotificationButtonLayout
+import com.margelo.nitro.audiobrowser.Options
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
-import com.margelo.nitro.audiobrowser.RatingType as NitroRatingType
-import com.margelo.nitro.audiobrowser.UpdateOptions
 import com.margelo.nitro.audiobrowser.Variant_NullType_Double
 import com.margelo.nitro.audiobrowser.Variant_NullType_NotificationButtonLayout
 
@@ -22,23 +21,29 @@ data class PlayerUpdateOptions(
 
   // Player capabilities - most enabled by default, only false values disable
   // Exceptions: bookmark, jumpForward, jumpBackward default to false
-  var capabilities: PlayerCapabilities = PlayerCapabilities(
-    play = null, pause = null, stop = null, seekTo = null,
-    skipToNext = null, skipToPrevious = null,
-    jumpForward = false, jumpBackward = false,
-    favorite = null,
-    shuffleMode = null, repeatMode = null, playbackRate = null
-  ),
+  var capabilities: PlayerCapabilities =
+    PlayerCapabilities(
+      play = null,
+      pause = null,
+      stop = null,
+      seekTo = null,
+      skipToNext = null,
+      skipToPrevious = null,
+      jumpForward = false,
+      jumpBackward = false,
+      favorite = null,
+      shuffleMode = null,
+      repeatMode = null,
+      playbackRate = null,
+    ),
 
   // Notification button layout (null = derive from capabilities)
   var notificationButtons: NotificationButtonLayout? = null,
 
   // Android-specific runtime options (all under android.* in JS)
-  var ratingType: NitroRatingType? = null,
   var appKilledPlaybackBehavior: AppKilledPlaybackBehavior =
     AppKilledPlaybackBehavior.STOP_PLAYBACK_AND_REMOVE_NOTIFICATION,
   var skipSilence: Boolean = false,
-  var shuffle: Boolean = false,
 ) {
   fun updateFromBridge(options: NativeUpdateOptions) {
     options.forwardJumpInterval?.let { forwardJumpInterval = it }
@@ -52,22 +57,15 @@ data class PlayerUpdateOptions(
         }
     }
 
-    options.capabilities?.let { newCaps ->
-      capabilities = mergeCapabilities(capabilities, newCaps)
-    }
+    options.capabilities?.let { newCaps -> capabilities = mergeCapabilities(capabilities, newCaps) }
 
     // Update Android-specific options
     options.android?.let { androidOptions ->
-      // Convert rating type
-      androidOptions.ratingType?.let { ratingType = it }
-
       androidOptions.appKilledPlaybackBehavior?.let { appKilledPlaybackBehavior = it }
 
       // Update boolean options
       androidOptions.skipSilence?.let { skipSilence = it }
 
-      androidOptions.shuffle?.let { shuffle = it }
-
       // Handle notificationButtons - variant allows distinguishing undefined from null
       androidOptions.notificationButtons?.let { variant ->
         notificationButtons =
@@ -79,33 +77,29 @@ data class PlayerUpdateOptions(
     }
   }
 
-  fun toNitro(): UpdateOptions {
-    // Create Android options
-    val androidOptions =
-      AndroidUpdateOptions(
-        appKilledPlaybackBehavior = appKilledPlaybackBehavior,
-        skipSilence = skipSilence,
-        shuffle = shuffle,
-        ratingType = ratingType,
-        notificationButtons =
-          notificationButtons?.let { Variant_NullType_NotificationButtonLayout.create(it) },
-      )
-
-    return UpdateOptions(
-      android = androidOptions,
+  /** The resolved options in their wire shape (what getOptions/onOptionsChanged report). */
+  fun toNitro(): Options {
+    return Options(
+      android =
+        AndroidOptions(
+          appKilledPlaybackBehavior = appKilledPlaybackBehavior,
+          skipSilence = skipSilence,
+          notificationButtons =
+            notificationButtons?.let { Variant_NullType_NotificationButtonLayout.create(it) },
+        ),
       forwardJumpInterval = forwardJumpInterval,
       backwardJumpInterval = backwardJumpInterval,
       progressUpdateEventInterval =
         progressUpdateEventInterval?.let { Variant_NullType_Double.create(it) },
       capabilities = capabilities,
-      iosPlaybackRates = null, // iOS-only option
+      ios = null, // iOS-only options
     )
   }
 
   /** Merge incoming capabilities with existing - only explicitly set values override */
   private fun mergeCapabilities(
     existing: PlayerCapabilities,
-    incoming: PlayerCapabilities
+    incoming: PlayerCapabilities,
   ): PlayerCapabilities {
     return PlayerCapabilities(
       play = incoming.play ?: existing.play,
@@ -119,7 +113,7 @@ data class PlayerUpdateOptions(
       favorite = incoming.favorite ?: existing.favorite,
       shuffleMode = incoming.shuffleMode ?: existing.shuffleMode,
       repeatMode = incoming.repeatMode ?: existing.repeatMode,
-      playbackRate = incoming.playbackRate ?: existing.playbackRate
+      playbackRate = incoming.playbackRate ?: existing.playbackRate,
     )
   }
 }

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

@@ -64,7 +64,10 @@ class AutomaticBufferManager(
    * media (station change).
    */
   fun reset() {
-    loadControl.resetToDefaults()
+    // The setup-provided defaults, not the media3 library defaults —
+    // resetToDefaults() silently wiped an app's fast-start buffer tuning on
+    // every queue set, station change, and seek.
+    loadControl.updateBufferConfig(defaultConfig)
     wasReady = false
     rebufferCount = 0
     playbackStartTimeMs = 0

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

@@ -0,0 +1,119 @@
+package com.audiobrowser.player
+
+import com.margelo.nitro.audiobrowser.NotificationButton
+import com.margelo.nitro.audiobrowser.NotificationButtonLayout
+import com.margelo.nitro.audiobrowser.PlayerCapabilities
+
+/**
+ * The pure decision core for Capability-gated controls: one rule for whether a control is available
+ * ([isEnabled]) and one derivation of the notification button layout ([deriveNotificationSlots]).
+ * MediaSessionCommandManager's three Media3 assemblies (external player commands, session button
+ * layout, notification commands/layout) all consume these decisions — previously each
+ * re-implemented them, and the copies had drifted.
+ */
+
+/** A user-facing control gated by a Capability. */
+enum class Control {
+  PLAY_PAUSE,
+  STOP,
+  SEEK_TO,
+  SKIP_TO_NEXT,
+  SKIP_TO_PREVIOUS,
+  JUMP_FORWARD,
+  JUMP_BACKWARD,
+  FAVORITE,
+}
+
+/**
+ * Whether a Capability-gated control is available. Everything is enabled by default and only an
+ * explicit `false` disables — except FAVORITE, which is opt-in, and PLAY_PAUSE, which is one
+ * control on every surface and only goes away when both halves are disabled.
+ */
+fun PlayerCapabilities.isEnabled(control: Control): Boolean =
+  when (control) {
+    Control.PLAY_PAUSE -> !(play == false && pause == false)
+    Control.STOP -> stop != false
+    Control.SEEK_TO -> seekTo != false
+    Control.SKIP_TO_NEXT -> skipToNext != false
+    Control.SKIP_TO_PREVIOUS -> skipToPrevious != false
+    Control.JUMP_FORWARD -> jumpForward != false
+    Control.JUMP_BACKWARD -> jumpBackward != false
+    Control.FAVORITE -> favoriteEnabled
+  }
+
+/** Notification slot, mapped to `CommandButton.SLOT_*` at Media3 assembly time. */
+enum class NotificationSlot {
+  BACK,
+  FORWARD,
+  BACK_SECONDARY,
+  FORWARD_SECONDARY,
+  OVERFLOW,
+}
+
+data class SlottedButton(val button: NotificationButton, val slot: NotificationSlot)
+
+private val NotificationButton.control: Control
+  get() =
+    when (this) {
+      NotificationButton.SKIP_TO_PREVIOUS -> Control.SKIP_TO_PREVIOUS
+      NotificationButton.SKIP_TO_NEXT -> Control.SKIP_TO_NEXT
+      NotificationButton.JUMP_BACKWARD -> Control.JUMP_BACKWARD
+      NotificationButton.JUMP_FORWARD -> Control.JUMP_FORWARD
+      NotificationButton.FAVORITE -> Control.FAVORITE
+    }
+
+/** Whether [button]'s gating Capability allows it. */
+fun PlayerCapabilities.allows(button: NotificationButton): Boolean = isEnabled(button.control)
+
+/**
+ * The single derivation of the notification button layout: an explicit [layout]'s slots filtered to
+ * allowed buttons, or — with no layout — the capability defaults: skip on the primary slots (jump
+ * falling back to a primary slot when its skip is disabled), jump on the secondary slots otherwise,
+ * favorite in overflow.
+ */
+fun deriveNotificationSlots(
+  capabilities: PlayerCapabilities,
+  layout: NotificationButtonLayout?,
+): List<SlottedButton> {
+  if (layout != null) {
+    return buildList {
+        layout.back?.let { add(SlottedButton(it, NotificationSlot.BACK)) }
+        layout.forward?.let { add(SlottedButton(it, NotificationSlot.FORWARD)) }
+        layout.backSecondary?.let { add(SlottedButton(it, NotificationSlot.BACK_SECONDARY)) }
+        layout.forwardSecondary?.let { add(SlottedButton(it, NotificationSlot.FORWARD_SECONDARY)) }
+        layout.overflow?.forEach { add(SlottedButton(it, NotificationSlot.OVERFLOW)) }
+      }
+      .filter { capabilities.allows(it.button) }
+  }
+
+  return buildList {
+    val skipPrevious = capabilities.isEnabled(Control.SKIP_TO_PREVIOUS)
+    val skipNext = capabilities.isEnabled(Control.SKIP_TO_NEXT)
+    val jumpBackward = capabilities.isEnabled(Control.JUMP_BACKWARD)
+    val jumpForward = capabilities.isEnabled(Control.JUMP_FORWARD)
+
+    // Primary slots: skip, with jump falling back when its skip is disabled.
+    if (skipPrevious) {
+      add(SlottedButton(NotificationButton.SKIP_TO_PREVIOUS, NotificationSlot.BACK))
+    } else if (jumpBackward) {
+      add(SlottedButton(NotificationButton.JUMP_BACKWARD, NotificationSlot.BACK))
+    }
+    if (skipNext) {
+      add(SlottedButton(NotificationButton.SKIP_TO_NEXT, NotificationSlot.FORWARD))
+    } else if (jumpForward) {
+      add(SlottedButton(NotificationButton.JUMP_FORWARD, NotificationSlot.FORWARD))
+    }
+
+    // Jump moves to the secondary slots when skip holds the primary.
+    if (skipPrevious && jumpBackward) {
+      add(SlottedButton(NotificationButton.JUMP_BACKWARD, NotificationSlot.BACK_SECONDARY))
+    }
+    if (skipNext && jumpForward) {
+      add(SlottedButton(NotificationButton.JUMP_FORWARD, NotificationSlot.FORWARD_SECONDARY))
+    }
+
+    if (capabilities.isEnabled(Control.FAVORITE)) {
+      add(SlottedButton(NotificationButton.FAVORITE, NotificationSlot.OVERFLOW))
+    }
+  }
+}