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

package/ios/Browser/{BrowserManager+URLResolution.swift → RequestPipeline.swift}

@@ -1,9 +1,151 @@
 import Foundation
 import NitroModules
+import os.log
+
+/// Builds and runs the browser's HTTP requests: the Request-Config Layers for browse, search,
+/// media and artwork, and the API fetches.
+@MainActor
+final class RequestPipeline {
+  let logger = Logger(subsystem: "com.audiobrowser", category: "RequestPipeline")
+  private let httpClient = HttpClient()
+  /// The request/browse thunks resolve once per content generation.
+  private let layers = GenerationMemo<ResolvedLayers>()
+
+  /// Set by `BrowserManager`; a new config resolves the layers again.
+  var config = BrowserConfig() {
+    didSet { layers.invalidate() }
+  }
+
+  nonisolated init() {}
+
+  /// Resolves the request and browse layers again on next use (e.g. after a locale change).
+  func invalidateLayers() {
+    layers.invalidate()
+  }
+
+  struct ResolvedLayers {
+    let request: TransformableRequestConfig?
+    let browse: TransformableRequestConfig?
+  }
+
+  /// The request and browse layers of the current config: each resolver's result, or the
+  /// static layer when it has none. The resolvers run one after the other, request first, as on
+  /// Android and web, and a config change or `clearContentCache` while they run resolves them
+  /// again.
+  func resolvedLayers() async throws -> ResolvedLayers {
+    try await layers.value { [weak self] in
+      guard let self else { throw CancellationError() }
+      // Read on every run: a retry after a config change must resolve the new config's layers.
+      let config = self.config
+      // The resolver is Promise-only (the TS layer wraps a sync-or-async thunk in
+      // Promise.resolve), so its result is the JS promise behind the bridge promise.
+      let request = try await config.requestResolver?().await().await() ?? config.request
+      let browse = try await config.browseResolver?().await().await() ?? config.browse
+      return ResolvedLayers(request: request, browse: browse)
+    }
+  }
+
+  /// Applies one Request-Config Layer (request / browse / route) onto `base`: its transforms
+  /// (async, then sync) when it has any, else its static fields (`RequestLayer.apply`).
+  func applyLayer(
+    _ layer: TransformableRequestConfig?,
+    to base: RequestConfig,
+    params: [String: String],
+  ) async throws -> RequestConfig {
+    guard let layer else { return base }
+    var transforms: [nonisolated(nonsending)(RequestConfig) async throws -> RequestConfig] = []
+    if let transform = layer.transform {
+      transforms.append { try await self.awaitAsyncConfig(transform($0, params)) }
+    }
+    if let transformSync = layer.transformSync {
+      transforms.append { try await self.awaitSyncConfig(transformSync($0, params)) }
+    }
+    let fields = RequestConfig(
+      method: layer.method, path: nil, baseUrl: layer.baseUrl, headers: layer.headers,
+      query: layer.query, body: layer.body, contentType: layer.contentType, userAgent: layer.userAgent,
+    )
+    return try await RequestLayer.apply(fields, transforms: transforms, to: base)
+  }
+
+  /// Builds the HTTP request for an API-backed route by layering
+  /// request → kind → route configs. `initialQuery` seeds request-level query
+  /// params (e.g. search q/mode/…) onto the base before the route layer, so they
+  /// survive into `request.query` even when a layer's transform "wins
+  /// completely" (it is handed only the base, so the route config's own static
+  /// query would otherwise be dropped). `routeConfig` is nil for the implicit
+  /// browse default; `kind` names the per-kind layer, nil for kinds with none. The request and
+  /// kind layers come from one resolution; `routeConfig` from the caller's config.
+  func buildApiRequest(
+    kind: KeyPath<ResolvedLayers, TransformableRequestConfig?>?,
+    _ routeConfig: TransformableRequestConfig?,
+    path: String,
+    params: [String: String],
+    initialQuery: [String: String]? = nil,
+  ) async throws -> HttpClient.HttpRequest {
+    var merged = RequestConfig(
+      method: nil, path: path, baseUrl: nil, headers: nil,
+      query: nil, body: nil, contentType: nil, userAgent: nil,
+    )
+    let layers = try await resolvedLayers()
+    merged = try await applyLayer(layers.request, to: merged, params: params)
+    if let initialQuery, !initialQuery.isEmpty {
+      merged = merged.copying(query: RequestLayer.mergeDicts(merged.query, initialQuery))
+    }
+    merged = try await applyLayer(kind.flatMap { layers[keyPath: $0] }, to: merged, params: params)
+    merged = try await applyLayer(routeConfig, to: merged, params: params)
+
+    guard merged.baseUrl != nil else {
+      throw BrowserError.invalidConfiguration("No URL configured for route")
+    }
+    return HttpClient.HttpRequest(
+      url: RequestLayer.buildUrl(merged, defaultPath: path),
+      method: merged.method?.stringValue ?? "GET",
+      headers: merged.headers,
+      body: merged.body,
+      contentType: merged.contentType ?? HttpClient.defaultContentType,
+      userAgent: merged.userAgent ?? HttpClient.defaultUserAgent,
+    )
+  }
+
+  /// Fetches a page object (`{title,path,children:[…]}`) through the request → browse → route
+  /// layers.
+  func fetchPage(
+    _ routeConfig: TransformableRequestConfig?,
+    path: String,
+    params: [String: String],
+  ) async throws -> ResolvedTrack {
+    let request = try await buildApiRequest(
+      kind: \.browse, routeConfig, path: path, params: params,
+    )
+
+    logger.debug("Resolving content from API")
+    logger.debug("  path: \(path)")
+    logger.debug("  url: \(request.url)")
+
+    let result: JsonResolvedTrack = try await httpClient.requestJson(request, as: JsonResolvedTrack.self)
+    let nitroResult = result.toNitro()
+
+    logger.debug("Resolved: \(nitroResult.title)")
+    if let sections = nitroResult.normalizedSections {
+      logger.debug("  children: \(sections.reduce(0) { $0 + $1.children.count }) tracks")
+    }
 
-// MARK: - URL Resolution
+    return nitroResult
+  }
+
+  /// Fetches a search route's bare Track array through the request → search route layers. The
+  /// search params go through `initialQuery`, so they reach the URL even when a transform wins;
+  /// the config's static path seeds the base, since a layer's static path never applies.
+  func fetchSearch(_ searchConfig: TransformableRequestConfig, params: SearchParams) async throws -> [Track] {
+    let request = try await buildApiRequest(
+      kind: nil, searchConfig, path: searchConfig.path ?? "", params: ["q": params.query],
+      initialQuery: PageResolver.searchQueryParams(params),
+    )
+    logger.debug("Searching via API: \(request.url)")
+    let jsonTracks: [JsonTrack] = try await httpClient.requestJson(request, as: [JsonTrack].self)
+    return jsonTracks.map { $0.toNitro() }
+  }
 
-extension BrowserManager {
   // MARK: - Media URL Resolution
 
   /// Resolves a media URL using the configured media transform.
@@ -11,7 +153,7 @@ extension BrowserManager {
   ///
   /// Resolution layers, least- to most-specific: shared `request` layer →
   /// `media` transform / static fields → `media.resolve(track)`. The final
-  /// `resolve` layer (if configured) is merged last via `mergeRequestConfig`,
+  /// `resolve` layer (if configured) is merged last,
   /// so its fields win. The `track` is only used to feed `resolve`; we do NOT
   /// auto-merge `track.request` here.
   func resolveMediaUrl(_ originalUrl: String, track: Track? = nil) async -> MediaResolvedUrl {
@@ -23,9 +165,8 @@ extension BrowserManager {
     // `media` config is present, so a relative src still gets baseUrl.
     let baseRequest: RequestConfig
     do {
-      try await ensureLayersResolved()
       baseRequest = try await applyLayer(
-        resolvedRequestLayer,
+        resolvedLayers().request,
         to: RequestConfig(
           method: nil, path: originalUrl, baseUrl: nil, headers: nil,
           query: nil, body: nil, contentType: nil, userAgent: nil,
@@ -56,8 +197,8 @@ extension BrowserManager {
       if let mediaConfig = config.media {
         merged = try await applyMediaLayer(mediaConfig, to: merged)
       }
-      merged = applyMediaResolveLayer(base: merged, resolve: resolveLayer)
-      let finalUrl = buildUrl(from: merged)
+      if let resolveLayer { merged = RequestLayer.merge(merged, resolveLayer) }
+      let finalUrl = RequestLayer.buildUrl(merged)
       logger.debug("Media URL resolved: \(originalUrl) -> \(finalUrl)")
       return MediaResolvedUrl(
         url: finalUrl,
@@ -70,46 +211,21 @@ extension BrowserManager {
     }
   }
 
-  /// Media-kind Request-Config Layer application: a transform (async and/or sync)
-  /// wins completely — async first, then sync, each result copied out of the Nitro
-  /// bridge immediately (extractConfig, via awaitAsync/SyncConfig) — otherwise the
-  /// media config's static fields merge over the base with `path` carried from the
-  /// base (only a transform may change it). The same rule as `applyLayer`; matches
-  /// the web stub and Android.
+  /// The media kind's Request-Config Layer over `base`: its transforms, when it has any, else
+  /// its static fields (`RequestLayer.apply`).
   private func applyMediaLayer(_ media: MediaRequestConfig, to base: RequestConfig) async throws -> RequestConfig {
-    if media.transform != nil || media.transformSync != nil {
-      var result = base
-      if let transform = media.transform {
-        result = try await awaitAsyncConfig(transform(result, nil))
-      }
-      if let transformSync = media.transformSync {
-        result = try await awaitSyncConfig(transformSync(result, nil))
-      }
-      return result
+    var transforms: [nonisolated(nonsending)(RequestConfig) async throws -> RequestConfig] = []
+    if let transform = media.transform {
+      transforms.append { try await self.awaitAsyncConfig(transform($0, nil)) }
     }
-    let staticMerged = mergeRequestConfig(
-      base: base,
-      override: RequestConfig(
-        method: media.method,
-        path: media.path,
-        baseUrl: media.baseUrl,
-        headers: media.headers,
-        query: media.query,
-        body: media.body,
-        contentType: media.contentType,
-        userAgent: media.userAgent,
-      ),
-    )
-    return RequestConfig(
-      method: staticMerged.method,
-      path: base.path,
-      baseUrl: staticMerged.baseUrl,
-      headers: staticMerged.headers,
-      query: staticMerged.query,
-      body: staticMerged.body,
-      contentType: staticMerged.contentType,
-      userAgent: staticMerged.userAgent,
+    if let transformSync = media.transformSync {
+      transforms.append { try await self.awaitSyncConfig(transformSync($0, nil)) }
+    }
+    let fields = RequestConfig(
+      method: media.method, path: nil, baseUrl: media.baseUrl, headers: media.headers,
+      query: media.query, body: media.body, contentType: media.contentType, userAgent: media.userAgent,
     )
+    return try await RequestLayer.apply(fields, transforms: transforms, to: base)
   }
 
   /// Invokes the consumer-supplied `media.resolve`/`resolveSync(track)` and merges
@@ -122,17 +238,7 @@ extension BrowserManager {
     if let resolve = media.resolve { asyncResolved = try await awaitAsyncConfig(resolve(track)) }
     var syncResolved: RequestConfig?
     if let resolveSync = media.resolveSync { syncResolved = try await awaitSyncConfig(resolveSync(track)) }
-    return MediaResolveComposer.composeResolved(
-      async: asyncResolved, sync: syncResolved,
-      combine: { self.mergeRequestConfig(base: $0, override: $1) },
-    )
-  }
-
-  /// Merges the resolve layer (most specific, override-wins) over `base`.
-  /// A no-op when `resolve` is nil.
-  private func applyMediaResolveLayer(base: RequestConfig, resolve: RequestConfig?) -> RequestConfig {
-    guard let resolve else { return base }
-    return mergeRequestConfig(base: base, override: resolve)
+    return RequestLayer.mergeResolved(async: asyncResolved, sync: syncResolved)
   }
 
   // MARK: - Artwork URL Resolution
@@ -176,9 +282,8 @@ extension BrowserManager {
       // Base config via the shared `request` layer (its transform runs for
       // artwork too), with track.artwork as the default path. Artwork then
       // shapes further via its own resolve / static fields / transform.
-      try await ensureLayersResolved()
       var mergedConfig = try await applyLayer(
-        resolvedRequestLayer,
+        resolvedLayers().request,
         to: RequestConfig(
           method: nil, path: track.artwork?.url, baseUrl: nil, headers: nil,
           query: nil, body: nil, contentType: nil, userAgent: nil,
@@ -200,18 +305,15 @@ extension BrowserManager {
         contentType: artworkConfig.contentType,
         userAgent: artworkConfig.userAgent,
       )
-      mergedConfig = mergeRequestConfig(base: mergedConfig, override: artworkStaticConfig)
+      mergedConfig = RequestLayer.merge(mergedConfig, artworkStaticConfig)
 
       if artworkConfig.resolve != nil || artworkConfig.resolveSync != nil {
         var asyncResolved: RequestConfig?
         if let resolve = artworkConfig.resolve { asyncResolved = try await awaitAsyncConfig(resolve(track)) }
         var syncResolved: RequestConfig?
         if let resolveSync = artworkConfig.resolveSync { syncResolved = try await awaitSyncConfig(resolveSync(track)) }
-        if let resolved = MediaResolveComposer.composeResolved(
-          async: asyncResolved, sync: syncResolved,
-          combine: { self.mergeRequestConfig(base: $0, override: $1) },
-        ) {
-          mergedConfig = mergeRequestConfig(base: mergedConfig, override: resolved)
+        if let resolved = RequestLayer.mergeResolved(async: asyncResolved, sync: syncResolved) {
+          mergedConfig = RequestLayer.merge(mergedConfig, resolved)
         } else if track.artwork == nil {
           // A resolver ran but produced nothing, and there's no artwork URL either
           // → no artwork (matches the web stub).
@@ -232,20 +334,7 @@ extension BrowserManager {
 
         if !contextQuery.isEmpty {
           logger.debug("Adding image query params: \(contextQuery)")
-          var existingQuery = mergedConfig.query ?? [:]
-          for (key, value) in contextQuery {
-            existingQuery[key] = value
-          }
-          mergedConfig = RequestConfig(
-            method: mergedConfig.method,
-            path: mergedConfig.path,
-            baseUrl: mergedConfig.baseUrl,
-            headers: mergedConfig.headers,
-            query: existingQuery,
-            body: mergedConfig.body,
-            contentType: mergedConfig.contentType,
-            userAgent: mergedConfig.userAgent,
-          )
+          mergedConfig = mergedConfig.copying(query: RequestLayer.mergeDicts(mergedConfig.query, contextQuery))
         }
       }
 
@@ -262,17 +351,21 @@ 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 {
         return nil
       }
 
-      let uri = buildUrl(from: mergedConfig)
+      let uri = RequestLayer.buildUrl(mergedConfig)
 
       // Build headers map, merging explicit headers with userAgent
       var headers = mergedConfig.headers ?? [:]
@@ -280,6 +373,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(
@@ -295,38 +392,18 @@ extension BrowserManager {
     }
   }
 
-  // MARK: - URL Building
-
-  private func buildUrl(from config: RequestConfig) -> String {
-    let path = config.path ?? ""
-    let baseUrl = config.baseUrl
-
-    var url = BrowserPathHelper.buildUrl(baseUrl: baseUrl, path: path)
-
-    // Add query parameters if any
-    if let query = config.query, !query.isEmpty {
-      url = BrowserPathHelper.appendQuery(query, to: url)
-    }
-
-    return url
-  }
-
   // MARK: - Config Utilities
 
   /// 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,
@@ -350,7 +427,6 @@ extension BrowserManager {
 
   /// Extracts all values from a RequestConfig into a new instance to avoid
   /// memory corruption in Nitro's Swift-C++ bridge when the Promise is deallocated.
-  /// Internal so `applyLayer` (in BrowserManager.swift) can copy transform results.
   func extractConfig(_ config: RequestConfig) -> RequestConfig {
     RequestConfig(
       method: config.method,
@@ -363,18 +439,14 @@ extension BrowserManager {
       userAgent: config.userAgent,
     )
   }
+}
 
-  /// Merges two RequestConfig objects, with override values taking precedence.
-  private func mergeRequestConfig(base: RequestConfig, override: RequestConfig) -> RequestConfig {
-    RequestConfig(
-      method: override.method ?? base.method,
-      path: override.path ?? base.path,
-      baseUrl: override.baseUrl ?? base.baseUrl,
-      headers: mergeDicts(base.headers, override.headers),
-      query: mergeDicts(base.query, override.query),
-      body: override.body ?? base.body,
-      contentType: override.contentType ?? base.contentType,
-      userAgent: override.userAgent ?? base.userAgent,
-    )
+extension RequestConfig: RequestFields {}
+
+extension RequestPipeline: MediaResolving {
+  /// Runs the `nowPlayingArtwork` config for every playing track, id or not: an id-less track
+  /// leaves an `{id}` token unfilled, so the request visibly fails rather than being skipped.
+  func resolveNowPlayingArtwork(track: Track, imageContext: ImageContext?) async -> ImageSource? {
+    await resolveArtworkUrl(track: track, perRouteConfig: config.nowPlayingArtwork, imageContext: imageContext)
   }
 }

package/ios/Browser/SearchDrillIn.swift

@@ -1,18 +1,18 @@
 import Foundation
 
 /// A search result that may or may not be directly playable. `src` is the
-/// playable stream; `url` is a browsable container path. Abstracting these two
+/// playable stream; `path` is a browsable container path. Abstracting these two
 /// fields keeps the drill-in decision free of the Nitro `Track` type so it can
 /// be unit-tested.
 protocol PlayableSearchItem {
   var src: String? { get }
-  var url: String? { get }
+  var path: String? { get }
 }
 
 enum SearchDrillIn {
   /// Picks the playable items for a "play «X»" voice search.
   ///
-  /// If the first result is browsable-only (a `url` container with no `src` — a
+  /// If the first result is browsable-only (a `path` container with no `src` — a
   /// place/genre page), drills into it via `resolveChildren` and uses its
   /// playable children, so we play the first station *inside* the page rather
   /// than skipping the page for a later inline station. Falls back to the flat
@@ -20,13 +20,13 @@ enum SearchDrillIn {
   /// yields nothing. Returns nil when nothing is playable.
   static func playable<Item: PlayableSearchItem>(
     from children: [Item],
-    resolveChildren: sending (String) async throws -> [Item]
+    resolveChildren: sending (String) async throws -> [Item],
   ) async throws -> [Item]? {
     guard !children.isEmpty else { return nil }
 
     let candidates: [Item]
-    if let first = children.first, first.src == nil, let url = first.url {
-      let drilled = try await resolveChildren(url).filter { $0.src != nil }
+    if let first = children.first, first.src == nil, let path = first.path {
+      let drilled = try await resolveChildren(path).filter { $0.src != nil }
       candidates = drilled.isEmpty ? children : drilled
     } else {
       candidates = children
@@ -37,7 +37,7 @@ enum SearchDrillIn {
   }
 }
 
-// The real Nitro `Track` already carries `src`/`url`; conform it for the app
+// The real Nitro `Track` already carries `src`/`path`; conform it for the app
 // build. (The testable target builds without NitroModules and uses a stub item.)
 #if canImport(NitroModules)
   extension Track: PlayableSearchItem {}

package/ios/Browser/SectionScope.swift

@@ -1,35 +1,69 @@
 // 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.
 enum SectionScope {
-  enum Section {
-    /// The tapped id lives inside an image row's items.
-    case imageRow([ImageRowItem])
-    /// The contiguous `groupTitle` run around the tapped child (items with
-    /// no group title form runs of their own).
-    case run([Track])
+  /// The section containing the tapped identity, plus the tapped child's
+  /// offset within it — non-nil only when the stamped flat index pinned the
+  /// exact copy.
+  struct Scoped {
+    let section: Section
+    let tappedOffset: Int?
   }
 
-  /// The section of `children` containing the playable `trackId`, or nil
-  /// when the id is not found.
-  static func section(of children: [Track], containing trackId: String) -> Section? {
-    for child in children {
-      if let items = child.imageRow, items.contains(where: { $0.src == trackId }) {
-        return .imageRow(items)
+  /// The section of `sections` containing the playable `trackId` (a track
+  /// identity: id when non-blank, else src), or nil 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.
+  static func scoped(
+    in sections: [Section],
+    containing trackId: String,
+    tappedIndex: Int? = nil,
+  ) -> Scoped? {
+    if let tappedIndex, tappedIndex >= 0 {
+      var start = 0
+      for section in sections {
+        let offset = tappedIndex - start
+        if offset < section.children.count {
+          if section.children[offset].identity == trackId {
+            return Scoped(section: section, tappedOffset: offset)
+          }
+          break
+        }
+        start += section.children.count
       }
     }
-    guard let index = children.firstIndex(where: { $0.src == trackId }) else {
-      return nil
-    }
-    let group = children[index].groupTitle
-    var start = index
-    while start > 0, children[start - 1].groupTitle == group {
-      start -= 1
-    }
-    var end = index
-    while end + 1 < children.count, children[end + 1].groupTitle == group {
-      end += 1
+    for section in sections {
+      if section.children.contains(where: { $0.identity == trackId }) {
+        return Scoped(section: section, tappedOffset: nil)
+      }
     }
-    return .run(Array(children[start ... end]))
+    return nil
+  }
+}
+
+// MARK: - Page shape helpers (ADR 0010)
+
+extension ResolvedTrack {
+  /// The canonical sectioned shape: `sections` wins when present; plain
+  /// `children` is authoring sugar for one untitled section.
+  var normalizedSections: [Section]? {
+    if let sections { return sections }
+    guard let children else { return nil }
+    return [.untitled(children)]
+  }
+
+  /// 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.
+  var flattenedChildren: [Track]? {
+    normalizedSections.map { $0.flatMap(\.children) }
   }
 }

package/ios/Browser/StyleResolver.swift

@@ -0,0 +1,58 @@
+#if canImport(NitroModules)
+  import NitroModules
+#endif
+
+/// 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(section:page:)`
+/// and every inherited key of `TrackStyle` by `trackStyle(track:section:)` —
+/// Nitro flattens the spec's `extends`, so `src/style-resolution.test.ts`
+/// enforces this completeness, not the type system.
+enum 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`.
+  static func sectionStyle(section: SectionStyle?, page: SectionStyle?) -> SectionStyle {
+    // Argument order is the generated init's (own properties before inherited
+    // ones — Nitro flattens `extends` own-props-first); the stub mirrors it.
+    SectionStyle(
+      gridWrap: section?.gridWrap ?? page?.gridWrap,
+      gridTile: section?.gridTile ?? page?.gridTile,
+      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,
+    )
+  }
+
+  /// Resolves a track's effective item properties against its (page-folded)
+  /// section block.
+  static func trackStyle(track: TrackStyle?, section: SectionStyle?) -> TrackStyle {
+    TrackStyle(
+      // Positional deny-list: `display` is never inherited onto an item —
+      // resolved nil, so no renderer can mistake the handle's page promise
+      // for this item's own layout.
+      display: nil,
+      artworkRendering: track?.artworkRendering ?? section?.artworkRendering,
+      imageShape: track?.imageShape ?? section?.imageShape,
+      // `'none'` resolves like any value — it is the renderer that treats it
+      // as "no accessory, derived behavior" (the inheritance escape).
+      accessorySymbol: track?.accessorySymbol ?? section?.accessorySymbol,
+      cardTint: track?.cardTint ?? section?.cardTint,
+      cardImage: track?.cardImage ?? section?.cardImage,
+    )
+  }
+}

package/ios/Browser/TabBarEntries.swift

@@ -1,15 +1,21 @@
 /// Compares the tab-list fields the CarPlay tab bar actually renders.
 enum TabBarEntries {
-  /// Whether two tab lists produce identical tab-bar entries — title, url,
-  /// and the artwork inputs of `applyTabBarEntry`. Used to suppress
+  /// Whether two tab lists produce identical tab-bar entries — title, path,
+  /// the artwork inputs of `applyTabBarEntry`, and `disabled`. Used to suppress
   /// `tabsChanged` when a tabs re-query (e.g. from `invalidateAllContent()`)
   /// resolves to the same entries, so an unchanged result never churns the
   /// tab bar or resets its selection.
+  ///
+  /// `disabled` counts even though it renders nothing itself: a disabled tab is
+  /// filtered out of the tab bar entirely (`showTabBar`), so a tab flipping it
+  /// with otherwise-identical fields changes which tabs exist. Omitting it here
+  /// swallowed the emit, and the tab never appeared or disappeared.
   static func same(_ old: [Track]?, _ new: [Track]) -> Bool {
     guard let old, old.count == new.count else { return false }
     return zip(old, new).allSatisfy {
-      $0.title == $1.title && $0.url == $1.url && $0.artwork == $1.artwork
+      $0.title == $1.title && $0.path == $1.path && $0.artwork == $1.artwork
         && $0.artworkSource?.uri == $1.artworkSource?.uri
+        && $0.disabled == $1.disabled
     }
   }
 }