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

package/ios/Browser/BrowserConfig.swift

@@ -48,9 +48,9 @@ struct BrowserConfig {
   let carPlayLoadingTitle: String?
 
   /// Resolves a browse path for the CarPlay Now Playing album line when the
-  /// active track has no albumUrl. Invoked on track changes (not at tap) so
+  /// active track has no albumPath. Invoked on track changes (not at tap) so
   /// the album line only becomes tappable when a destination exists.
-  let resolveAlbumUrl: ((_ track: Track) -> Promise<String?>)?
+  let resolveAlbumPath: ((_ track: Track) -> Promise<String?>)?
 
   /// Custom handler for track load events (overrides default load behavior)
   let handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)?
@@ -72,7 +72,7 @@ struct BrowserConfig {
     handleTrackLoad: ((_ event: TrackLoadEvent) -> Promise<Promise<Void>>)? = nil,
     androidControllerOfflineError: Bool = true,
     carPlayLoadingTitle: String? = nil,
-    resolveAlbumUrl: ((_ track: Track) -> Promise<String?>)? = nil,
+    resolveAlbumPath: ((_ track: Track) -> Promise<String?>)? = nil,
     formatNavigationError: ((_ params: FormatNavigationErrorParams) -> Promise<FormattedNavigationError?>)? = nil,
   ) {
     self.request = request
@@ -87,7 +87,7 @@ struct BrowserConfig {
     self.handleTrackLoad = handleTrackLoad
     self.androidControllerOfflineError = androidControllerOfflineError
     self.carPlayLoadingTitle = carPlayLoadingTitle
-    self.resolveAlbumUrl = resolveAlbumUrl
+    self.resolveAlbumPath = resolveAlbumPath
     self.formatNavigationError = formatNavigationError
   }
 
@@ -105,10 +105,31 @@ struct BrowserConfig {
     handleTrackLoad = config.handleTrackLoad
     androidControllerOfflineError = config.androidControllerOfflineError ?? true
     carPlayLoadingTitle = config.carPlayLoadingTitle
-    resolveAlbumUrl = config.resolveAlbumUrl
+    resolveAlbumPath = config.resolveAlbumPath
     formatNavigationError = config.formatNavigationError
   }
 
+  /// A copy of this config with every JS-provided function dropped — at every
+  /// level, not just the top; each nested type's strip below nils its own —
+  /// keeping the static fields (URLs, headers, routes' shape). Makes the config
+  /// safe to hold after its JS runtime is gone: callers take their
+  /// static/built-in fallback paths (a callback-only route degrades to its
+  /// no-content path). See `HybridAudioBrowser.dropStaleJSCallbacks` for why
+  /// invoking a stale callback is fatal.
+  func strippingJSCallbacks() -> BrowserConfig {
+    BrowserConfig(
+      request: request?.strippingJSCallbacks(),
+      browse: browse?.strippingJSCallbacks(),
+      media: media?.strippingJSCallbacks(),
+      artwork: artwork?.strippingJSCallbacks(),
+      nowPlayingArtwork: nowPlayingArtwork?.strippingJSCallbacks(),
+      routes: routes?.map { $0.strippingJSCallbacks() },
+      singleTrack: singleTrack,
+      androidControllerOfflineError: androidControllerOfflineError,
+      carPlayLoadingTitle: carPlayLoadingTitle,
+    )
+  }
+
   // MARK: - Track Load Handler
 
   private static let logger = Logger(subsystem: "com.audiobrowser", category: "BrowserConfig")
@@ -139,3 +160,79 @@ struct BrowserConfig {
 // MARK: - NativeRouteEntry + RouteEntry conformance
 
 extension NativeRouteEntry: RouteEntry {}
+
+// MARK: - Deep JS-callback stripping
+
+// The generated structs are get-only from Swift, so each strip rebuilds the
+// value through the memberwise initializer with the function fields nil'd.
+
+private extension TransformableRequestConfig {
+  func strippingJSCallbacks() -> TransformableRequestConfig {
+    TransformableRequestConfig(
+      transform: nil,
+      transformSync: nil,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension MediaRequestConfig {
+  func strippingJSCallbacks() -> MediaRequestConfig {
+    MediaRequestConfig(
+      resolve: nil,
+      resolveSync: nil,
+      transform: nil,
+      transformSync: nil,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension ArtworkRequestConfig {
+  func strippingJSCallbacks() -> ArtworkRequestConfig {
+    ArtworkRequestConfig(
+      resolve: nil,
+      resolveSync: nil,
+      transform: nil,
+      transformSync: nil,
+      imageQueryParams: imageQueryParams,
+      method: method,
+      path: path,
+      baseUrl: baseUrl,
+      headers: headers,
+      query: query,
+      body: body,
+      contentType: contentType,
+      userAgent: userAgent,
+    )
+  }
+}
+
+private extension NativeRouteEntry {
+  func strippingJSCallbacks() -> NativeRouteEntry {
+    NativeRouteEntry(
+      path: path,
+      browseCallback: nil,
+      browseConfig: browseConfig?.strippingJSCallbacks(),
+      browseStatic: browseStatic,
+      searchCallback: nil,
+      searchConfig: searchConfig?.strippingJSCallbacks(),
+      media: media?.strippingJSCallbacks(),
+      artwork: artwork?.strippingJSCallbacks(),
+    )
+  }
+}

package/ios/Browser/BrowserManager+URLResolution.swift

@@ -262,10 +262,14 @@ extension BrowserManager {
       }
 
       // Substitute the `{id}` template token with the track's id across path/query/header values.
-      // (Configs without the token are unaffected — e.g. browse artwork.) Only when the track has an id.
-      if let id = track.id, !id.isEmpty {
-        mergedConfig = substituteTrackId(in: mergedConfig, id: id)
-      }
+      // (Configs without the token are unaffected — e.g. browse artwork.) A track without a
+      // non-blank id leaves the token LITERALLY in place — the request then visibly 404s, which
+      // is intended (self-describing error trail) — with a single warning logged below once the
+      // URL is built.
+      mergedConfig = substituteTrackId(in: mergedConfig, id: track.id)
+      let hasUnfilledIdToken = TrackIdTemplate.containsToken(mergedConfig.path)
+        || TrackIdTemplate.containsToken(mergedConfig.query)
+        || TrackIdTemplate.containsToken(mergedConfig.headers)
 
       // Build final URL - if no path after merging, no artwork to transform
       guard mergedConfig.path != nil else {
@@ -280,6 +284,10 @@ extension BrowserManager {
         headers["User-Agent"] = userAgent
       }
 
+      if hasUnfilledIdToken {
+        logger.warning("nowPlayingArtwork: track has no id — '{id}' left unfilled in \(uri)")
+      }
+
       logger.debug("Artwork URL transformed: \(track.artwork?.url ?? "nil") -> \(uri)")
 
       return ImageSource(
@@ -315,18 +323,14 @@ extension BrowserManager {
 
   /// Replaces the `{id}` token with the track id in a request config's path, query values, and
   /// header values. Used so a `nowPlayingArtwork` like `{ path: "/artwork/{id}" }` resolves.
-  private func substituteTrackId(in config: RequestConfig, id: String) -> RequestConfig {
-    func sub(_ s: String?) -> String? { s?.replacingOccurrences(of: "{id}", with: id) }
-    func subDict(_ d: [String: String]?) -> [String: String]? {
-      guard let d else { return nil }
-      return d.mapValues { $0.replacingOccurrences(of: "{id}", with: id) }
-    }
-    return RequestConfig(
+  /// A nil/blank id leaves the values unchanged (token left literal — see TrackIdTemplate).
+  private func substituteTrackId(in config: RequestConfig, id: String?) -> RequestConfig {
+    RequestConfig(
       method: config.method,
-      path: sub(config.path),
+      path: TrackIdTemplate.substitute(config.path, id: id),
       baseUrl: config.baseUrl,
-      headers: subDict(config.headers),
-      query: subDict(config.query),
+      headers: TrackIdTemplate.substitute(config.headers, id: id),
+      query: TrackIdTemplate.substitute(config.query, id: id),
       body: config.body,
       contentType: config.contentType,
       userAgent: config.userAgent,

package/ios/Browser/BrowserManager.swift

@@ -77,12 +77,12 @@ final class BrowserManager {
   var resolvedRequestLayer: TransformableRequestConfig?
   private var resolvedBrowseLayer: TransformableRequestConfig?
 
-  // Set of favorited track identifiers (src)
+  // Set of favorited track identities (id when non-blank, else src).
   private var favoriteIds: Set<String> = []
 
-  // Favorite match mode, propagated from the player's `favorite` capability.
-  // nil = favoriting disabled (no row hearts). Set via setFavoriteMatch.
-  private var favoriteMatch: FavoritesMatchMode?
+  // Whether favoriting is enabled, propagated from the player's `favorite`
+  // capability. false = no row hearts. Set via setFavoriteEnabled.
+  private var favoriteEnabled = false
 
   // Navigation tracking to prevent race conditions
   private var currentNavigationId: Int = 0
@@ -162,62 +162,49 @@ final class BrowserManager {
     onFavoritesChanged?()
   }
 
-  /// Sets the favorite match mode (propagated from the `favorite` capability).
-  /// nil disables row-heart hydration.
-  func setFavoriteMatch(_ match: FavoritesMatchMode?) {
-    favoriteMatch = match
+  /// Enables/disables favoriting (propagated from the `favorite` capability).
+  /// false disables row-heart hydration.
+  func setFavoriteEnabled(_ enabled: Bool) {
+    favoriteEnabled = enabled
   }
 
-  /// Optimistically reflects a local favorite toggle for `src` in the match set,
-  /// needing no consumer-specific id extraction: favoriting inserts `src` (which
-  /// matches itself under either mode). Removal mirrors `isFavorite`'s match
-  /// semantics — partial drops every id that is a path segment of `src` (the
-  /// channel uid, and self-heals stray ids); exact (or disabled) drops only
-  /// `src`, so unrelated exact favorites that happen to be a segment of `src`
-  /// aren't collaterally lost. The consumer reconciles `favoriteIds` to its
-  /// canonical ids on the next `setFavorites`; `isFavorite(src:)` gives the same
-  /// answer before and after, so the now-playing heart stays responsive.
-  func setFavorited(src: String, favorited: Bool) {
+  /// Optimistically reflects a local favorite toggle in the favorite set, keyed
+  /// by the track's identity (id when non-blank, else src). The consumer
+  /// reconciles `favoriteIds` to its canonical set on the next `setFavorites`;
+  /// `isFavorite` gives the same answer before and after, so the now-playing
+  /// heart stays responsive.
+  func setFavorited(identity: String, favorited: Bool) {
     if favorited {
-      favoriteIds.insert(src)
-    } else if favoriteMatch == .partial {
-      favoriteIds = favoriteIds.filter { !BrowserPathHelper.containsSegment(src, $0) }
+      favoriteIds.insert(identity)
     } else {
-      favoriteIds.remove(src)
+      favoriteIds.remove(identity)
     }
   }
 
   /// Hydrates the favorited field on a track based on the favoriteIds set.
   /// No-op unless favoriting is enabled (the `favorite` capability). Only
-  /// playable (src-bearing) tracks are favoritable; the flag is set to true OR
-  /// false so non-favorited tracks still show an (empty) heart. Local
-  /// favoriteIds take precedence over API-provided values.
+  /// identity-bearing tracks (id or src) are favoritable; the flag is set to
+  /// true OR false so non-favorited tracks still show an (empty) heart. A
+  /// caller-set `favorited` wins — API/consumer-provided values are never
+  /// overwritten (matches Android and web).
   func hydrateFavorite(_ track: Track) -> Track {
-    guard let match = favoriteMatch, let src = track.src else { return track }
-
-    let isFavorited = isFavorite(src: src, match: match)
-
-    // Only create a new track if the favorited state differs
-    if track.favorited == isFavorited { return track }
-
-    return track.copying(favorited: isFavorited)
+    guard favoriteEnabled, track.favorited == nil, track.identity != nil else { return track }
+    return track.copying(favorited: isFavorite(track))
   }
 
-  /// Whether `src` is favorited under the given match mode.
-  private func isFavorite(src: String, match: FavoritesMatchMode) -> Bool {
-    switch match {
-    case .exact:
-      favoriteIds.contains(src)
-    case .partial:
-      favoriteIds.contains { BrowserPathHelper.containsSegment(src, $0) }
-    }
+  /// Whether the track's identity is in the favorite set.
+  private func isFavorite(_ track: Track) -> Bool {
+    track.identity.map(favoriteIds.contains) ?? false
   }
 
-  /// Hydrates favorites on all children of a ResolvedTrack.
+  /// Hydrates favorites on all tracks of a resolved page. Pages reach
+  /// hydration normalized (ADR 0010), so `sections` is the only structure
+  /// to walk.
   private func hydrateChildren(_ resolvedTrack: ResolvedTrack) -> ResolvedTrack {
-    guard let children = resolvedTrack.children else { return resolvedTrack }
-    let hydratedChildren = children.map { hydrateFavorite($0) }
-    return resolvedTrack.copying(children: hydratedChildren)
+    guard let sections = resolvedTrack.sections else { return resolvedTrack }
+    return resolvedTrack.copying(sections: sections.map { section in
+      section.copying(children: section.children.map { hydrateFavorite($0) })
+    })
   }
 
   // MARK: - Navigation
@@ -304,12 +291,14 @@ final class BrowserManager {
       )
     }
 
-    // Validate and transform children
-    if let children = resolvedTrack.children {
-      let transformed = try await transformChildren(
-        children, parentPath: path, routeEntry: routeEntry?.0,
+    // Normalize to the canonical sectioned shape (children sugar → one
+    // untitled section — ADR 0010), then validate and transform. The output
+    // never carries `children`.
+    if let sections = resolvedTrack.normalizedSections {
+      let transformed = try await transformSections(
+        sections, parentPath: path, routeEntry: routeEntry?.0,
       )
-      return resolvedTrack.copying(children: transformed)
+      return resolvedTrack.copying(sections: transformed, children: .some(nil))
     }
 
     return resolvedTrack
@@ -426,7 +415,7 @@ final class BrowserManager {
     )
   }
 
-  /// Resolves a browse route: a page object (`{title,url,children:[…]}`).
+  /// Resolves a browse route: a page object (`{title,path,children:[…]}`).
   /// The browse kind layer is the cached resolved layer (`resolvedBrowseLayer`),
   /// populated by `ensureLayersResolved()` inside `buildApiRequest`.
   private func resolveFromConfig(
@@ -447,8 +436,8 @@ final class BrowserManager {
     let nitroResult = result.toNitro()
 
     logger.debug("Resolved: \(nitroResult.title)")
-    if let children = nitroResult.children {
-      logger.debug("  children: \(children.count) tracks")
+    if let sections = nitroResult.normalizedSections {
+      logger.debug("  children: \(sections.reduce(0) { $0 + $1.children.count }) tracks")
     }
 
     return nitroResult
@@ -525,65 +514,51 @@ final class BrowserManager {
 
   // MARK: - Child Transformation
 
-  private func transformChildren(
-    _ children: [Track],
+  private func transformSections(
+    _ sections: [Section],
     parentPath: String,
     routeEntry: NativeRouteEntry?,
-  ) async throws -> [Track] {
-    var transformed: [Track] = []
-
-    for track in children {
-      // Validate track has stable identifier. A track carrying an imageRow is
-      // exempt: a url-less row is a pure preview — never selected, navigated
-      // to, or cached (its items carry their own identity).
-      if track.url == nil, track.src == nil, track.imageRow?.isEmpty != false {
-        throw BrowserError.invalidConfiguration(
-          "Track must have either 'url' or 'src' for stable identification: \(track.title)",
-        )
-      }
-
-      var transformedTrack = track
+  ) async throws -> [Section] {
+    var transformed: [Section] = []
+    // The contextual index is the flat page position — children concatenated
+    // in section order (ADR 0009/0010).
+    var flatIndex = 0
+
+    for section in sections {
+      var transformedChildren: [Track] = []
+
+      for track in section.children {
+        let index = flatIndex
+        flatIndex += 1
+
+        // Validate track has stable identifier.
+        if track.path == nil, track.src == nil {
+          throw BrowserError.invalidConfiguration(
+            "Track must have either 'path' or 'src' for stable identification: \(track.title)",
+          )
+        }
 
-      if track.src != nil, track.url == nil {
-        let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: track.src!)
-        transformedTrack = track.copying(url: contextualUrl)
-      }
+        var transformedTrack = track
 
-      // Resolve artwork URL at browse-time (no size context)
-      let artworkConfig = routeEntry?.artwork ?? config.artwork
-      if let imageSource = await resolveArtworkUrl(track: transformedTrack, perRouteConfig: artworkConfig) {
-        transformedTrack = transformedTrack.copying(artworkSource: imageSource)
-      }
+        if track.src != nil, track.path == nil {
+          // src != nil guarantees a non-nil identity (id when non-blank, else src).
+          // The flat page position rides along as a duplicate-identity tie-breaker.
+          let contextualPath = BrowserPathHelper.build(
+            parentPath: parentPath, trackId: track.identity!, index: index,
+          )
+          transformedTrack = track.copying(path: contextualPath)
+        }
 
-      // Resolve artwork for image row items
-      if let imageRowItems = transformedTrack.imageRow {
-        var resolvedItems: [ImageRowItem] = []
-        for item in imageRowItems {
-          let itemImageSource = await resolveArtworkUrl(track: item.toTrack(), perRouteConfig: artworkConfig)
-          // Playable items get a contextual URL like any list row, so a
-          // thumbnail tap expands into its section's queue instead of a
-          // queue of one (ADR 0006).
-          let itemUrl = item.url ?? item.src.map {
-            BrowserPathHelper.build(parentPath: parentPath, trackId: $0)
-          }
-          resolvedItems.append(ImageRowItem(
-            id: item.id,
-            url: itemUrl,
-            src: item.src,
-            artwork: item.artwork,
-            artworkSource: itemImageSource,
-            title: item.title,
-            artist: item.artist,
-            album: item.album,
-            albumUrl: item.albumUrl,
-            live: item.live,
-            request: item.request,
-          ))
+        // Resolve artwork URL at browse-time (no size context)
+        let artworkConfig = routeEntry?.artwork ?? config.artwork
+        if let imageSource = await resolveArtworkUrl(track: transformedTrack, perRouteConfig: artworkConfig) {
+          transformedTrack = transformedTrack.copying(artworkSource: imageSource)
         }
-        transformedTrack = transformedTrack.copying(imageRow: resolvedItems)
+
+        transformedChildren.append(transformedTrack)
       }
 
-      transformed.append(transformedTrack)
+      transformed.append(section.copying(children: transformedChildren))
     }
 
     return transformed
@@ -668,37 +643,40 @@ final class BrowserManager {
   /// station. Decision in `SearchDrillIn.playable`; mirrors Android's
   /// `searchPlayable`.
   func searchPlayable(_ params: SearchParams) async throws -> [Track]? {
-    let children = try await (search(params).children) ?? []
-    return try await SearchDrillIn.playable(from: children) { [self] url in
-      logger.debug("First search result is browsable-only, resolving: \(url)")
-      return try await (resolve(url).children) ?? []
+    // Voice search never matches a disabled track (Track.disabled) — filtered
+    // before drill-in so an unavailable first result can't capture the play.
+    let children = try await ((search(params).flattenedChildren) ?? [])
+      .filter { $0.disabled != true }
+    return try await SearchDrillIn.playable(from: children) { [self] path in
+      logger.debug("First search result is browsable-only, resolving: \(path)")
+      return try await ((resolve(path).flattenedChildren) ?? []).filter { $0.disabled != true }
     }
   }
 
   private func makeSearchResult(query: String, results: [Track]) -> ResolvedTrack {
+    // Search results are a flat list; as a resolved page they are one
+    // untitled section (ADR 0010).
     ResolvedTrack(
-      url: BrowserPathHelper.createSearchPath(query),
-      children: results,
+      path: BrowserPathHelper.createSearchPath(query),
+      style: nil,
+      sections: [.untitled(results)],
+      children: nil,
       carPlaySiriListButton: nil,
       id: nil,
       src: nil,
       artwork: nil,
       artworkSource: nil, request: nil,
-      artworkCarPlayTinted: nil,
       title: "Search: \(query)",
       subtitle: nil,
       artist: nil,
-      albumUrl: nil,
+      albumPath: nil,
       album: nil,
       description: nil,
       genre: nil,
       duration: nil,
-      style: nil,
-      childrenStyle: nil,
+      disabled: nil,
       favorited: nil,
-      groupTitle: nil,
       live: nil,
-      imageRow: nil,
     )
   }
 
@@ -715,7 +693,8 @@ final class BrowserManager {
     }
 
     let resolved = try await resolveRouteEntry(tabsEntry, path: Self.tabsRoutePath, params: [:])
-    let tabTracks = resolved.children ?? []
+    // Tabs are a flat list, not a page — a sectioned tabs source flattens.
+    let tabTracks = resolved.flattenedChildren ?? []
 
     tabs = tabTracks
     return tabTracks
@@ -723,38 +702,39 @@ final class BrowserManager {
 
   // MARK: - Queue Expansion (for CarPlay/external controllers)
 
-  /// Expands a contextual URL to a full queue of playable tracks.
-  func expandQueueFromContextualUrl(_ url: String) async throws -> (tracks: [Track], selectedIndex: Int)? {
-    guard BrowserPathHelper.isContextual(url) else { return nil }
+  /// Expands a contextual path to a full queue of playable tracks.
+  func expandQueueFromContextualPath(_ path: String) async throws -> (tracks: [Track], selectedIndex: Int)? {
+    guard BrowserPathHelper.isContextual(path) else { return nil }
 
-    let parentPath = BrowserPathHelper.stripTrackId(url)
-    guard let trackId = BrowserPathHelper.extractTrackId(url) else { return nil }
+    let parentPath = BrowserPathHelper.stripTrackId(path)
+    guard let trackId = BrowserPathHelper.extractTrackId(path) else { return nil }
 
-    logger.debug("Expanding queue from contextual URL")
-    logger.debug("  url: \(url)")
+    logger.debug("Expanding queue from contextual path")
+    logger.debug("  path: \(path)")
     logger.debug("  parentPath: \(parentPath)")
     logger.debug("  trackId: \(trackId)")
 
     // Resolve the parent container
     let resolved = try await resolve(parentPath, useCache: true)
-    guard let children = resolved.children else { return nil }
-
-    // Queue scope is the tapped section, not the whole page (ADR 0006). An
-    // id that no longer appears on the page aborts the expansion — the
-    // caller falls back to the stored single track (matching Android);
-    // silently queueing the changed list would resume the wrong station.
-    let sectionTracks: [Track]
-    switch SectionScope.section(of: children, containing: trackId) {
-    case let .imageRow(items):
-      sectionTracks = items.map { $0.toTrack() }
-    case let .run(tracks):
-      sectionTracks = tracks
-    case nil:
+    guard let sections = resolved.normalizedSections else { return nil }
+
+    // Queue scope is the tapped section, not the whole page (ADR 0006). The
+    // stamped flat index pins which section (and which copy) was tapped when
+    // the same identity appears more than once; it is only a tie-breaker —
+    // a stale index falls back to the first identity match. An id that no
+    // longer appears on the page at all aborts the expansion — the caller
+    // falls back to the stored single track (matching Android); silently
+    // queueing the changed list would resume the wrong station.
+    let tappedIndex = BrowserPathHelper.extractIndex(path)
+    guard let scoped = SectionScope.scoped(in: sections, containing: trackId, tappedIndex: tappedIndex) else {
       return nil
     }
+    let sectionTracks = scoped.section.children
+    let tappedOffset = scoped.tappedOffset
 
-    // Filter to playable tracks (have src)
-    let playableTracks = sectionTracks.filter { $0.src != nil }
+    // Filter to playable tracks (have src). A disabled track is unavailable —
+    // queue expansion excludes it, so auto-advance never meets one.
+    let playableTracks = sectionTracks.filter { $0.src != nil && $0.disabled != true }
     guard !playableTracks.isEmpty else { return nil }
 
     logger.debug("Found \(playableTracks.count) playable tracks")
@@ -762,10 +742,18 @@ final class BrowserManager {
       logger.debug("  [\(index)] \(track.title) - src: \(track.src ?? "nil")")
     }
 
-    // Find selected track index
-    // Unreachable in practice (the section was found BY this id), but a miss
-    // must abort rather than silently start the queue at the wrong track.
-    guard let selectedIndex = playableTracks.firstIndex(where: { $0.src == trackId }) else {
+    // Find selected track index: the pinned copy when the stamp survived,
+    // else the first identity match. A miss must abort rather than silently
+    // start the queue at the wrong track (unreachable in practice — the
+    // section was found BY this id).
+    let selectedIndex: Int
+    if let tappedOffset, sectionTracks[tappedOffset].src != nil, sectionTracks[tappedOffset].disabled != true {
+      selectedIndex =
+        sectionTracks.prefix(through: tappedOffset)
+          .count(where: { $0.src != nil && $0.disabled != true }) - 1
+    } else if let index = playableTracks.firstIndex(where: { $0.identity == trackId }) {
+      selectedIndex = index
+    } else {
       return nil
     }
     logger.debug("Selected track index: \(selectedIndex)")