react-native-audio-browser 0.2.0-next.3 → 0.2.0-next.30

package/android/src/main/java/com/audiobrowser/browser/SectionScope.kt

@@ -1,43 +1,84 @@
 package com.audiobrowser.browser
 
-import com.margelo.nitro.audiobrowser.ImageRowItem
+import com.audiobrowser.extension.identity
+import com.margelo.nitro.audiobrowser.ResolvedTrack
+import com.margelo.nitro.audiobrowser.Section
 import com.margelo.nitro.audiobrowser.Track
 
 /**
- * Queue scope is the tapped section, not the whole page (ADR 0006): the
- * playback context a listener expects is the list they tapped in — a page
- * aggregating several sections must not leak next/previous across them.
+ * Queue scope is the tapped section, not the whole page (ADR 0006): the playback context a listener
+ * expects is the list they tapped in — a page aggregating several sections must not leak
+ * next/previous across them. Sections are structural (ADR 0010), so scoping is a lookup, not a
+ * groupTitle-run derivation.
  */
 object SectionScope {
-  sealed class Section {
-    /** The tapped id lives inside an image row's items. */
-    data class ImageRow(val items: List<ImageRowItem>) : Section()
-
-    /**
-     * The contiguous `groupTitle` run around the tapped child (items with no
-     * group title form runs of their own).
-     */
-    data class Run(val tracks: List<Track>) : Section()
-  }
+  /**
+   * The section containing the tapped identity, plus the tapped child's offset within it — non-null
+   * only when the stamped flat index pinned the exact copy.
+   */
+  data class Scoped(val section: Section, val tappedOffset: Int?)
 
   /**
-   * The section of [children] containing the playable [trackId], or null
-   * when the id is not found.
+   * The section of [sections] containing the playable [trackId] (a track identity — id when
+   * non-blank, else src), or null when not found.
+   *
+   * [tappedIndex] — the flat page position stamped into the contextual URL (children concatenated
+   * in section order) — is a tie-breaker, never an identifier: when the child at that position
+   * still carries the tapped identity, it pins which section (and which copy) was tapped; when it
+   * doesn't (the list shifted), resolution falls back to the first section containing the identity.
+   * A stale index can therefore never select a different track — at worst a different copy of the
+   * same one.
    */
-  fun section(children: List<Track>, trackId: String): Section? {
-    for (child in children) {
-      val items = child.imageRow
-      if (items != null && items.any { it.src == trackId }) {
-        return Section.ImageRow(items.toList())
+  fun scoped(sections: List<Section>, trackId: String, tappedIndex: Int? = null): Scoped? {
+    if (tappedIndex != null && tappedIndex >= 0) {
+      var start = 0
+      for (section in sections) {
+        val offset = tappedIndex - start
+        if (offset < section.children.size) {
+          if (section.children[offset].identity == trackId) {
+            return Scoped(section, offset)
+          }
+          break
+        }
+        start += section.children.size
+      }
+    }
+    for (section in sections) {
+      if (section.children.any { it.identity == trackId }) {
+        return Scoped(section, null)
       }
     }
-    val index = children.indexOfFirst { it.src == trackId }
-    if (index < 0) return null
-    val group = children[index].groupTitle
-    var start = index
-    while (start > 0 && children[start - 1].groupTitle == group) start--
-    var end = index
-    while (end + 1 < children.size && children[end + 1].groupTitle == group) end++
-    return Section.Run(children.subList(start, end + 1).toList())
+    return null
   }
 }
+
+// Page shape helpers (ADR 0010)
+
+/**
+ * One untitled section — the canonical wrap of a flat track list (`children` authoring sugar,
+ * search results — ADR 0010).
+ */
+fun untitledSection(children: Array<Track>): Section =
+  Section(title = null, style = null, path = null, children = children)
+
+/**
+ * The canonical sectioned shape: `sections` wins when present; plain `children` is authoring sugar
+ * for one untitled section.
+ */
+val ResolvedTrack.normalizedSections: List<Section>?
+  get() = sections?.toList() ?: children?.let { listOf(untitledSection(it)) }
+
+/**
+ * [normalizedSections] with the page block folded in: each section's style resolves `section ??
+ * page` per property ([StyleResolver], ADR 0011), so everything downstream sees only effective
+ * section blocks — a page is a Track that is also the container of its sections.
+ */
+fun ResolvedTrack.styleResolvedSections(): List<Section>? =
+  normalizedSections?.map { it.copy(style = StyleResolver.sectionStyle(it.style, style)) }
+
+/**
+ * The page's children concatenated in section order — the flattening that defines contextual
+ * `__index` positions and the flat views (tabs, search) of a sectioned page.
+ */
+val ResolvedTrack.flattenedChildren: List<Track>?
+  get() = normalizedSections?.flatMap { it.children.asList() }

package/android/src/main/java/com/audiobrowser/browser/StyleResolver.kt

@@ -0,0 +1,60 @@
+package com.audiobrowser.browser
+
+import com.margelo.nitro.audiobrowser.SectionStyle
+import com.margelo.nitro.audiobrowser.TrackStyle
+
+/**
+ * The one place style declarations resolve to effective values (ADR 0011).
+ *
+ * Two mechanisms, deliberately distinct:
+ * - **Inherited item properties** resolve `track ?? section ?? page`, per property — a track's own
+ *   declaration wins over the blocks that contain it.
+ * - **Container properties and the positional `display`** resolve by scope override: `section ??
+ *   page` — the page declares for its whole scope, a section overrides for its own children.
+ *   `display` is never inherited item-to-container: each holder describes its own children, and a
+ *   track's `display` is the promise for the page *it* opens, not its rendering inside this
+ *   section.
+ *
+ * Every key of `SectionStyle` must be read by [sectionStyle] and every inherited key of
+ * `TrackStyle` by [trackStyle] — Nitro flattens the spec's `extends`, so
+ * `src/style-resolution.test.ts` enforces this completeness, not the type system.
+ */
+object StyleResolver {
+  /**
+   * Folds the page block into a section's block: every `SectionStyle` key resolves `section ??
+   * page`. The result is the section's effective block; item resolution then only needs `track ??
+   * section`.
+   */
+  fun sectionStyle(section: SectionStyle?, page: SectionStyle?): SectionStyle =
+    SectionStyle(
+      display = section?.display ?: page?.display,
+      artworkRendering = section?.artworkRendering ?: page?.artworkRendering,
+      imageShape = section?.imageShape ?: page?.imageShape,
+      accessorySymbol = section?.accessorySymbol ?: page?.accessorySymbol,
+      cardTint = section?.cardTint ?: page?.cardTint,
+      cardImage = section?.cardImage ?: page?.cardImage,
+      gridWrap = section?.gridWrap ?: page?.gridWrap,
+      gridTile = section?.gridTile ?: page?.gridTile,
+    )
+
+  /**
+   * Resolves a track's effective item properties against its (page-folded) section block.
+   *
+   * No Android renderer consumes the result yet — today's only inherited property
+   * (`artworkRendering`) is CarPlay-rendered — but the resolver ships on both platforms so the
+   * completeness test can hold every future inherited key to the same rule from day one.
+   */
+  fun trackStyle(track: TrackStyle?, section: SectionStyle?): TrackStyle =
+    TrackStyle(
+      // Positional deny-list: `display` is never inherited onto an item — resolved null, so no
+      // renderer can mistake the handle's page promise for this item's own layout.
+      display = null,
+      artworkRendering = track?.artworkRendering ?: section?.artworkRendering,
+      imageShape = track?.imageShape ?: section?.imageShape,
+      // 'none' resolves like any value — a renderer treats it as "no accessory, derived
+      // behavior" (the inheritance escape). No Android surface draws these properties today.
+      accessorySymbol = track?.accessorySymbol ?: section?.accessorySymbol,
+      cardTint = track?.cardTint ?: section?.cardTint,
+      cardImage = track?.cardImage ?: section?.cardImage,
+    )
+}

package/android/src/main/java/com/audiobrowser/extension/ResolvedTrackExt.kt

@@ -2,6 +2,7 @@ package com.audiobrowser.extension
 
 import com.margelo.nitro.audiobrowser.ResolvedTrack
 import com.margelo.nitro.audiobrowser.Track
+import com.margelo.nitro.audiobrowser.TrackStyle
 
 /**
  * The Track view of a ResolvedTrack: every display/playback field carried over, the browse-only
@@ -12,24 +13,36 @@ import com.margelo.nitro.audiobrowser.Track
 fun ResolvedTrack.toTrack(): Track =
   Track(
     id = id,
-    url = url,
+    path = path,
     src = src,
     artwork = artwork,
     artworkSource = artworkSource,
     request = request,
-    artworkCarPlayTinted = artworkCarPlayTinted,
     title = title,
     subtitle = subtitle,
     artist = artist,
-    albumUrl = albumUrl,
+    albumPath = albumPath,
     album = album,
     description = description,
     genre = genre,
     duration = duration,
-    style = style,
-    childrenStyle = childrenStyle,
+    // An explicit SectionStyle → TrackStyle projection: the page's container
+    // properties (gridWrap) have no meaning on a plain Track, so they drop —
+    // Nitro flattens the spec's `extends`, making this narrowing a hand-written
+    // field list rather than an upcast (ADR 0011).
+    style =
+      style?.let {
+        TrackStyle(
+          display = it.display,
+          artworkRendering = it.artworkRendering,
+          imageShape = it.imageShape,
+          accessorySymbol = it.accessorySymbol,
+          cardTint = it.cardTint,
+          cardImage = it.cardImage,
+        )
+      },
+    disabled = disabled,
     favorited = favorited,
-    groupTitle = groupTitle,
     live = live,
-    imageRow = imageRow,
+    icyCharset = icyCharset,
   )

package/android/src/main/java/com/audiobrowser/extension/TappedTrack.kt

@@ -0,0 +1,20 @@
+package com.audiobrowser.extension
+
+import com.audiobrowser.util.BrowserPathHelper
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * The queue position of the tapped surface, for skip-in-place. Exact-surface match first: a
+ * contextual path carries the tapped page position (`__index`), so path equality pins the exact
+ * copy when the page holds the same identity more than once. The identity match remains for
+ * index-less paths (e.g. pre-stamp persisted state); an index-stamped path with no exact match
+ * returns -1, and the caller falls through to expansion, which re-scopes the queue to the tapped
+ * section (ADR 0009).
+ */
+fun Array<Track>.indexOfTappedTrack(contextualPath: String, trackId: String?): Int {
+  val index = indexOfFirst { it.path == contextualPath }
+  if (index >= 0 || BrowserPathHelper.extractIndex(contextualPath) != null || trackId == null) {
+    return index
+  }
+  return indexOfFirst { it.identity == trackId }
+}

package/android/src/main/java/com/audiobrowser/extension/TrackIdentity.kt

@@ -0,0 +1,15 @@
+package com.audiobrowser.extension
+
+import com.margelo.nitro.audiobrowser.Track
+
+/**
+ * A track's identity: the opaque `id` when present (non-blank), else the playable `src`. Two tracks
+ * refer to the same item iff their identities are equal. Browsable-only tracks (neither `id` nor
+ * `src`) have no identity — they are addressed by `path` instead.
+ *
+ * This is THE comparison rule for favorites matching, section scoping, skip-in-place, the car
+ * now-playing row indicator, and the contextual `__trackId` — see ADR 0008. Mirrors the TS
+ * `trackIdentity` helper.
+ */
+val Track.identity: String?
+  get() = id?.takeUnless { it.isBlank() } ?: src

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

@@ -1,5 +1,6 @@
 package com.audiobrowser.http
 
+import com.audiobrowser.BuildConfig
 import java.io.IOException
 import java.util.concurrent.TimeUnit
 import kotlinx.coroutines.Dispatchers
@@ -27,13 +28,29 @@ class HttpClient {
     isLenient = true
   }
 
-  private val loggingInterceptor =
+  /**
+   * Full request/response logging, for debug builds only.
+   *
+   * Timber is exposed as `api`, so whatever this logs reaches the host app's tree — a Crashlytics
+   * or Sentry breadcrumb tree included. That means credentials attached by the request-transform
+   * layer and every response body, so the interceptor is not installed in release at all: `BODY`
+   * also buffers and stringifies each response whether or not anything reads the log.
+   *
+   * The redactions apply in debug too. Logcat is shared in bug reports and screen shares.
+   */
+  private fun loggingInterceptor() =
     HttpLoggingInterceptor { message -> Timber.d(message) }
-      .apply { level = HttpLoggingInterceptor.Level.BODY }
+      .apply {
+        level = HttpLoggingInterceptor.Level.BODY
+        redactHeader("Authorization")
+        redactHeader("Proxy-Authorization")
+        redactHeader("Cookie")
+        redactHeader("Set-Cookie")
+      }
 
   private val client =
     OkHttpClient.Builder()
-      .addInterceptor(loggingInterceptor)
+      .apply { if (BuildConfig.DEBUG) addInterceptor(loggingInterceptor()) }
       .connectTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
       .readTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)
       .writeTimeout(TIMEOUT_SECONDS, TimeUnit.SECONDS)

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

@@ -0,0 +1,24 @@
+package com.audiobrowser.model
+
+import java.nio.charset.Charset
+
+/** Re-decodes an ICY `StreamTitle` with the charset the track declares. */
+internal object IcyTitle {
+  /**
+   * [title] re-decoded through ISO-8859-1 with [charset] when it is Latin-1 shaped: every char at
+   * or below U+00FF, at least one at or above U+0080. That shape is what media3's ISO-8859-1
+   * fallback yields for bytes that are not UTF-8, and also what a station that UTF-8-encoded its
+   * legacy bytes yields; ISO-8859-1 is lossless, so both re-decode. Returns [title] as is when it
+   * has another shape, is pure ASCII, or [charset] is not one the runtime can decode with.
+   */
+  fun redecode(title: String, charset: String): String {
+    var high = false
+    for (c in title) {
+      if (c.code > 0xFF) return title
+      if (c.code >= 0x80) high = true
+    }
+    if (!high) return title
+    val cs = runCatching { Charset.forName(charset) }.getOrNull() ?: return title
+    return String(title.toByteArray(Charsets.ISO_8859_1), cs)
+  }
+}

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

@@ -15,11 +15,12 @@ data class PlaybackMetadata(
   companion object {
     /**
      * Creates PlaybackMetadata from raw Metadata entries. Handles ICY streams specially, uses
-     * Media3's unified approach for everything else.
+     * Media3's unified approach for everything else. [icyCharset] is the track's declared charset
+     * for ICY titles media3 decoded as Latin-1; it never touches other metadata.
      */
-    fun from(metadata: Metadata): PlaybackMetadata? {
+    fun from(metadata: Metadata, icyCharset: String? = null): PlaybackMetadata? {
       // Try ICY first (streaming-specific)
-      fromIcy(metadata)?.let {
+      fromIcy(metadata, icyCharset)?.let {
         return it
       }
 
@@ -32,12 +33,15 @@ data class PlaybackMetadata(
     }
 
     /** Shoutcast / Icecast metadata (ICY protocol) https://cast.readme.io/docs/icy */
-    private fun fromIcy(metadata: Metadata): PlaybackMetadata? {
+    private fun fromIcy(metadata: Metadata, icyCharset: String?): PlaybackMetadata? {
       for (i in 0 until metadata.length()) {
         when (val entry = metadata[i]) {
           is IcyInfo -> {
-            if (entry.title != null) {
-              return PlaybackMetadata(title = entry.title)
+            val title = entry.title
+            if (title != null) {
+              return PlaybackMetadata(
+                title = icyCharset?.let { IcyTitle.redecode(title, it) } ?: title
+              )
             }
           }
         }

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

@@ -3,11 +3,11 @@ package com.audiobrowser.model
 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.RemoteButtonLayout
 import com.margelo.nitro.audiobrowser.Variant_NullType_Double
-import com.margelo.nitro.audiobrowser.Variant_NullType_NotificationButtonLayout
+import com.margelo.nitro.audiobrowser.Variant_NullType_RemoteButtonLayout
 
 /**
  * Update options for the AudioBrowser that can be changed at runtime. These options control player
@@ -20,7 +20,7 @@ data class PlayerUpdateOptions(
   var progressUpdateEventInterval: Double? = null,
 
   // Player capabilities - most enabled by default, only false values disable
-  // Exceptions: bookmark, jumpForward, jumpBackward default to false
+  // Exceptions: jumpForward, jumpBackward default to false
   var capabilities: PlayerCapabilities =
     PlayerCapabilities(
       play = null,
@@ -37,8 +37,8 @@ data class PlayerUpdateOptions(
       playbackRate = null,
     ),
 
-  // Notification button layout (null = derive from capabilities)
-  var notificationButtons: NotificationButtonLayout? = null,
+  // Ordered button layout (null = derive from capabilities)
+  var remoteButtonLayout: RemoteButtonLayout? = null,
 
   // Android-specific runtime options (all under android.* in JS)
   var appKilledPlaybackBehavior: AppKilledPlaybackBehavior =
@@ -66,12 +66,12 @@ data class PlayerUpdateOptions(
       // Update boolean options
       androidOptions.skipSilence?.let { skipSilence = it }
 
-      // Handle notificationButtons - variant allows distinguishing undefined from null
-      androidOptions.notificationButtons?.let { variant ->
-        notificationButtons =
+      // Handle remoteButtonLayout - variant allows distinguishing undefined from null
+      androidOptions.remoteButtonLayout?.let { variant ->
+        remoteButtonLayout =
           when (variant) {
-            is Variant_NullType_NotificationButtonLayout.First -> null
-            is Variant_NullType_NotificationButtonLayout.Second -> variant.value
+            is Variant_NullType_RemoteButtonLayout.First -> null
+            is Variant_NullType_RemoteButtonLayout.Second -> variant.value
           }
       }
     }
@@ -84,8 +84,8 @@ data class PlayerUpdateOptions(
         AndroidOptions(
           appKilledPlaybackBehavior = appKilledPlaybackBehavior,
           skipSilence = skipSilence,
-          notificationButtons =
-            notificationButtons?.let { Variant_NullType_NotificationButtonLayout.create(it) },
+          remoteButtonLayout =
+            remoteButtonLayout?.let { Variant_NullType_RemoteButtonLayout.create(it) },
         ),
       forwardJumpInterval = forwardJumpInterval,
       backwardJumpInterval = backwardJumpInterval,

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

@@ -1,19 +1,22 @@
 package com.audiobrowser.player
 
-import com.margelo.nitro.audiobrowser.NotificationButton
-import com.margelo.nitro.audiobrowser.NotificationButtonLayout
 import com.margelo.nitro.audiobrowser.PlayerCapabilities
+import com.margelo.nitro.audiobrowser.RemoteButton
+import com.margelo.nitro.audiobrowser.RemoteButtonLayout
 
 /**
- * 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
+ * The pure decision core for Capabilities: one rule for whether a Capability is enabled
+ * ([isEnabled]) and one derivation of the button layout ([deriveButtonSlots]).
+ * MediaSessionCommandManager's Media3 assemblies 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 {
+/**
+ * A control that a Capability gates. Mirrors the [PlayerCapabilities] flags Android acts on —
+ * `shuffleMode`, `repeatMode` and `playbackRate` exist on the struct but only drive CarPlay, so
+ * they have no entry here.
+ */
+enum class Capability {
   PLAY_PAUSE,
   STOP,
   SEEK_TO,
@@ -25,95 +28,145 @@ enum class Control {
 }
 
 /**
- * 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.
+ * Whether a Capability is enabled. 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
+fun PlayerCapabilities.isEnabled(capability: Capability): Boolean =
+  when (capability) {
+    Capability.PLAY_PAUSE -> !(play == false && pause == false)
+    Capability.STOP -> stop != false
+    Capability.SEEK_TO -> seekTo != false
+    Capability.SKIP_TO_NEXT -> skipToNext != false
+    Capability.SKIP_TO_PREVIOUS -> skipToPrevious != false
+    Capability.JUMP_FORWARD -> jumpForward != false
+    Capability.JUMP_BACKWARD -> jumpBackward != false
+    Capability.FAVORITE -> favoriteEnabled
   }
 
-/** Notification slot, mapped to `CommandButton.SLOT_*` at Media3 assembly time. */
-enum class NotificationSlot {
+/**
+ * The three positions Android actually offers, mapped to `CommandButton.SLOT_*` at Media3 assembly
+ * time. There is no secondary pair: every system surface flattens the layout to back, forward and
+ * overflow, so a fourth or fifth position would have nowhere to render.
+ *
+ * Media3 does define SLOT_BACK_SECONDARY and SLOT_FORWARD_SECONDARY, but `DisplayConstraints`
+ * defaults both to **0 buttons** — only a controller that opts in with `setMaxButtonsForSlot` shows
+ * them, which no system surface does.
+ */
+enum class ButtonSlot {
   BACK,
   FORWARD,
-  BACK_SECONDARY,
-  FORWARD_SECONDARY,
   OVERFLOW,
 }
 
-data class SlottedButton(val button: NotificationButton, val slot: NotificationSlot)
+data class SlottedButton(val button: RemoteButton, val slot: ButtonSlot)
 
-private val NotificationButton.control: Control
+/** The Capability gating a button. */
+private val RemoteButton.capability: Capability
   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
+      RemoteButton.SKIP_TO_PREVIOUS -> Capability.SKIP_TO_PREVIOUS
+      RemoteButton.SKIP_TO_NEXT -> Capability.SKIP_TO_NEXT
+      RemoteButton.JUMP_BACKWARD -> Capability.JUMP_BACKWARD
+      RemoteButton.JUMP_FORWARD -> Capability.JUMP_FORWARD
+      RemoteButton.FAVORITE -> Capability.FAVORITE
     }
 
 /** Whether [button]'s gating Capability allows it. */
-fun PlayerCapabilities.allows(button: NotificationButton): Boolean = isEnabled(button.control)
+fun PlayerCapabilities.allows(button: RemoteButton): Boolean = isEnabled(button.capability)
+
+/**
+ * Whether two layouts describe the same arrangement.
+ *
+ * [RemoteButtonLayout] is a generated data class whose `overflow` is an `Array`, and Kotlin
+ * data-class equality compares arrays by *reference*. Plain `==` therefore reports "changed" for
+ * two identical layouts whenever overflow is set, because every options update carries a fresh
+ * array across the bridge — which would republish the layout to Android Auto on every unrelated
+ * `updateOptions` call.
+ */
+internal fun RemoteButtonLayout?.sameAs(other: RemoteButtonLayout?): Boolean =
+  if (this == null || other == null) {
+    this == null && other == null
+  } else {
+    back == other.back && forward == other.forward && overflow.contentEquals(other.overflow)
+  }
 
 /**
- * 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.
+ * The single derivation of the button layout.
+ *
+ * The two parameters answer different questions, and only one of them is authoritative:
+ * - [capabilities] — *may* this button exist? Admission.
+ * - [layout] — *where* does it go? Arrangement.
+ *
+ * **A layout can rearrange buttons but never add one.** Every entry is filtered through [allows]
+ * regardless of its position, so naming a button whose Capability is disabled does nothing —
+ * listing `FAVORITE` while `capabilities.favorite` is off leaves it off. This is the usual
+ * surprise, because JUMP_FORWARD and JUMP_BACKWARD default to disabled: a layout full of jump
+ * buttons silently produces none until those capabilities are turned on.
+ *
+ * With no [layout], [capabilities] does both jobs — it decides membership *and* infers positions:
+ * skip takes the primary positions, jump falls back into a primary position when its skip is
+ * disabled and otherwise sits in overflow, favorite in overflow.
+ *
+ * With a [layout], each field maps to its position — `back` to BACK, `forward` to FORWARD, every
+ * `overflow` entry to OVERFLOW in order — and disabled entries drop out. A dropped entry leaves its
+ * position empty rather than promoting anything into it: turning off one capability must not
+ * silently rearrange the row.
+ *
+ * A [layout] is all-or-nothing: every field is required, so it fully describes the arrangement and
+ * nothing is merged with the capability defaults. The bridge could not support a per-field merge
+ * anyway — Nitro maps both an omitted and a null enum field to Kotlin `null`, so native cannot tell
+ * "leave this empty" from "derive this one".
+ *
+ * [capabilities] has a second job outside this function: it also drives the player and session
+ * commands, which govern what a Bluetooth remote or headset can trigger. That is why placement is
+ * purely cosmetic here — a button left out of the layout disappears from every screen while still
+ * responding to a headset.
+ *
+ * @param capabilities What the player is allowed to do. Gates every button, in both modes.
+ * @param layout Explicit placement, or null to infer placement from [capabilities].
  */
-fun deriveNotificationSlots(
+fun deriveButtonSlots(
   capabilities: PlayerCapabilities,
-  layout: NotificationButtonLayout?,
+  layout: RemoteButtonLayout?,
 ): 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)) }
+        layout.back?.let { add(SlottedButton(it, ButtonSlot.BACK)) }
+        layout.forward?.let { add(SlottedButton(it, ButtonSlot.FORWARD)) }
+        layout.overflow.forEach { add(SlottedButton(it, ButtonSlot.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)
+    val skipPrevious = capabilities.isEnabled(Capability.SKIP_TO_PREVIOUS)
+    val skipNext = capabilities.isEnabled(Capability.SKIP_TO_NEXT)
+    val jumpBackward = capabilities.isEnabled(Capability.JUMP_BACKWARD)
+    val jumpForward = capabilities.isEnabled(Capability.JUMP_FORWARD)
 
-    // Primary slots: skip, with jump falling back when its skip is disabled.
+    // Primary positions: skip, with jump falling back when its skip is disabled.
     if (skipPrevious) {
-      add(SlottedButton(NotificationButton.SKIP_TO_PREVIOUS, NotificationSlot.BACK))
+      add(SlottedButton(RemoteButton.SKIP_TO_PREVIOUS, ButtonSlot.BACK))
     } else if (jumpBackward) {
-      add(SlottedButton(NotificationButton.JUMP_BACKWARD, NotificationSlot.BACK))
+      add(SlottedButton(RemoteButton.JUMP_BACKWARD, ButtonSlot.BACK))
     }
     if (skipNext) {
-      add(SlottedButton(NotificationButton.SKIP_TO_NEXT, NotificationSlot.FORWARD))
+      add(SlottedButton(RemoteButton.SKIP_TO_NEXT, ButtonSlot.FORWARD))
     } else if (jumpForward) {
-      add(SlottedButton(NotificationButton.JUMP_FORWARD, NotificationSlot.FORWARD))
+      add(SlottedButton(RemoteButton.JUMP_FORWARD, ButtonSlot.FORWARD))
     }
 
-    // Jump moves to the secondary slots when skip holds the primary.
+    // Jump moves to overflow when skip holds the primary position.
     if (skipPrevious && jumpBackward) {
-      add(SlottedButton(NotificationButton.JUMP_BACKWARD, NotificationSlot.BACK_SECONDARY))
+      add(SlottedButton(RemoteButton.JUMP_BACKWARD, ButtonSlot.OVERFLOW))
     }
     if (skipNext && jumpForward) {
-      add(SlottedButton(NotificationButton.JUMP_FORWARD, NotificationSlot.FORWARD_SECONDARY))
+      add(SlottedButton(RemoteButton.JUMP_FORWARD, ButtonSlot.OVERFLOW))
     }
 
-    if (capabilities.isEnabled(Control.FAVORITE)) {
-      add(SlottedButton(NotificationButton.FAVORITE, NotificationSlot.OVERFLOW))
+    if (capabilities.isEnabled(Capability.FAVORITE)) {
+      add(SlottedButton(RemoteButton.FAVORITE, ButtonSlot.OVERFLOW))
     }
   }
 }