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

package/ios/Browser/BrowserManager.swift

@@ -3,89 +3,49 @@ import NitroModules
 import os.log
 
 /// Custom browser errors.
-enum BrowserError: Error {
+enum BrowserError: LocalizedError {
   case contentNotFound(path: String)
-  case httpError(code: Int, body: String)
-  case networkError(Error)
   case invalidConfiguration(String)
   case callbackError(String)
 
-  var localizedDescription: String {
+  var errorDescription: String? {
     switch self {
-    case .contentNotFound:
-      return "Content not found"
-    case let .httpError(code, body):
-      // Try to extract error message from JSON response: { "error": "message" }
-      if let data = body.data(using: .utf8),
-         let json = try? JSONSerialization.jsonObject(with: data) as? [String: Any],
-         let errorMessage = json["error"] as? String
-      {
-        return errorMessage
-      }
-      // Fall back to localized HTTP status description
-      return HTTPURLResponse.localizedString(forStatusCode: code)
-    case let .networkError(error):
-      return "Network error: \(error.localizedDescription)"
-    case let .invalidConfiguration(message):
-      return "Invalid configuration: \(message)"
-    case let .callbackError(message):
-      return message
+    case .contentNotFound: "Content not found"
+    case let .invalidConfiguration(message): "Invalid configuration: \(message)"
+    case let .callbackError(message): message
     }
   }
 }
 
-/// Core browser manager that handles navigation, search, and media browsing.
-///
-/// This class contains the main business logic for:
-/// - Route resolution and path matching with parameter extraction
-/// - HTTP API requests and response processing
-/// - JavaScript callback invocation
-/// - Fallback handling and error management
+/// The browser's state (path, content, tabs, config), its content and search caches, favorites
+/// and events. Pages come from `PageResolver`; requests go through `RequestPipeline`.
 @MainActor
 final class BrowserManager {
   // Allow creation from nonisolated contexts (e.g. HybridAudioBrowser property default)
-  nonisolated init() {}
+  nonisolated init() {
+    pages = PageResolver(requests: requests)
+  }
 
   let logger = Logger(subsystem: "com.audiobrowser", category: "BrowserManager")
 
-  // MARK: - Constants (match Kotlin companion object)
-
-  /// Internal path used for the default/root browse source
-  static let defaultRoutePath = "__default__"
-
-  /// Internal path used for navigation tabs
-  static let tabsRoutePath = "__tabs__"
-
-  /// Internal path used for search
-  static let searchRoutePath = "__search__"
-
   // MARK: - Private Properties
 
-  private let router = SimpleRouter()
-  private let httpClient = HttpClient()
-
-  // LRU cache for individual tracks - keyed by both url and src for O(1) lookup
-  private let trackCache = LRUCache<String, Track>(maxSize: 3000)
+  let requests = RequestPipeline()
+  private let pages: PageResolver
 
   // LRU cache for resolved content - keyed by path
   private let contentCache = LRUCache<String, ResolvedTrack>(maxSize: 20)
 
-  // Cache for search results
-  private var lastSearchQuery: String?
+  // Most recent search, keyed by `searchCacheKey`.
+  private var lastSearchKey: String?
   private var lastSearchResults: [Track]?
 
-  // Resolver caching: request/browse thunks resolve once per content generation.
-  private var layerGeneration = 0
-  private var resolvedLayerGeneration = -1
-  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
@@ -95,7 +55,7 @@ final class BrowserManager {
   private(set) var path: String = "/" {
     didSet {
       if oldValue != path {
-        onPathChanged?(path)
+        pathChanged.emit(path)
       }
     }
   }
@@ -103,7 +63,7 @@ final class BrowserManager {
   private(set) var content: ResolvedTrack? {
     didSet {
       // Note: Can't compare ResolvedTrack directly, always fire callback
-      onContentChanged?(content)
+      contentChanged.emit(content)
     }
   }
 
@@ -114,7 +74,7 @@ final class BrowserManager {
       // titles in a new locale), and an unchanged result must not churn the
       // CarPlay tab bar or reset its selection.
       if let tabs, !TabBarEntries.same(oldValue, tabs) {
-        onTabsChanged?(tabs)
+        tabsChanged.emit(tabs)
       }
     }
   }
@@ -124,35 +84,38 @@ final class BrowserManager {
   /// Whether configureBrowser() has been called
   private(set) var isConfigured = false
 
-  /// Browser configuration containing routes, search, tabs, and request settings.
-  var config: BrowserConfig = .init() {
-    didSet {
+  /// Browser configuration containing routes, search, tabs, and request settings. Kept on
+  /// `requests`, which every request reads.
+  var config: BrowserConfig {
+    get { requests.config }
+    set {
       isConfigured = true
-      // New config means the cached resolver results are stale.
-      layerGeneration += 1
-      onConfigChanged?(config)
+      requests.config = newValue
+      configChanged.emit(newValue)
     }
   }
 
-  // MARK: - Callbacks
+  // MARK: - Events (emitted on the main actor)
 
-  var onPathChanged: ((String) -> Void)?
-  var onContentChanged: ((ResolvedTrack?) -> Void)?
-  var onTabsChanged: (([Track]) -> Void)?
-  var onConfigChanged: ((BrowserConfig) -> Void)?
-  /// Fired when the favorite id set changes (e.g. an app/webview-originated
-  /// favorite). Lets surfaces like the CarPlay now-playing heart re-render —
-  /// they otherwise only learn of their own toggles via favorite/active-track
-  /// events, never an external change routed through `setFavorites`.
-  var onFavoritesChanged: (() -> Void)?
+  let pathChanged = Emitter<String>()
+  let contentChanged = Emitter<ResolvedTrack?>()
+  let tabsChanged = Emitter<[Track]>()
+  let configChanged = Emitter<BrowserConfig>()
+  /// The favorite id set changed, however it changed (e.g. from the app or a webview), so
+  /// surfaces like the CarPlay now-playing heart can re-render.
+  let favoritesChanged = Emitter<Void>()
 
-  /// Forwards to config.awaitTrackLoadHandler so callers don't need to
-  /// cross the MainActor boundary to access `config`.
+  /// Runs the app's `handleTrackLoad` for `event` and waits for it, both promise layers: a JS
+  /// callback returning `Promise<void>` arrives as `Promise<Promise<Void>>`. False when the app
+  /// set none.
   func awaitTrackLoadHandler(event: TrackLoadEvent) async -> Bool {
-    // awaitTrackLoadHandler manages its own MainActor dispatch internally
-    nonisolated(unsafe) let cfg = config
-    nonisolated(unsafe) let evt = event
-    return await cfg.awaitTrackLoadHandler(event: evt)
+    guard let handler = config.handleTrackLoad else { return false }
+    do {
+      try await handler(event).await().await()
+    } catch {
+      logger.error("handleTrackLoad failed: \(error.localizedDescription)")
+    }
+    return true
   }
 
   // MARK: - Favorites
@@ -162,103 +125,75 @@ final class BrowserManager {
     let newIds = Set(favorites)
     guard newIds != favoriteIds else { return }
     favoriteIds = newIds
-    onFavoritesChanged?()
+    favoritesChanged.emit(())
   }
 
-  /// 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`;
+  /// `hydrateFavorite` 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)
+    // `identity` bridges a std::string out of the C++ track, so it is bound
+    // once here rather than computed again to answer "is it favorited".
+    guard favoriteEnabled, track.favorited == nil, let identity = track.identity else { return track }
+    return track.copying(favorited: favoriteIds.contains(identity))
   }
 
-  /// 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) }
-    }
-  }
-
-  /// 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)
-  }
-
-  // MARK: - Track Cache
-
-  /// Cache a track by both url and src for O(1) lookup from either key.
-  private func cacheTrack(_ track: Track) {
-    if let url = track.url {
-      trackCache.set(url, value: track)
-    }
-    if let src = track.src {
-      trackCache.set(src, value: track)
-    }
-  }
-
-  private func cacheChildren(_ resolvedTrack: ResolvedTrack) {
-    resolvedTrack.children?.forEach { cacheTrack($0) }
+    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
 
-  /// Main navigation method - updates path and resolves content.
-  ///
-  /// Uses a navigation ID to prevent race conditions when multiple navigations
-  /// overlap. Only the most recent navigation's result is applied.
-  func navigate(_ path: String) async throws {
-    // Increment navigation ID and capture for this navigation
+  /// Loads `path` as the current page. `bypassCache` reloads it from the network and keeps the
+  /// content on screen meanwhile, for refreshing the current path. A newer load supersedes this one, and its
+  /// result or failure is dropped: every caller reports a throw, so a slow /a failing after a
+  /// fast /b succeeded would otherwise show /a's error over /b's content.
+  func load(_ path: String, bypassCache: Bool = false) async throws {
     currentNavigationId += 1
     let navigationId = currentNavigationId
-
     self.path = path
-    content = nil // Clear for loading state
-
-    let resolved = try await resolve(path)
-
-    // Only apply result if this is still the current navigation
-    guard navigationId == currentNavigationId else { return }
-
-    content = resolved
+    if bypassCache {
+      // A failed reload must not leave the stale page to be served from the cache.
+      contentCache.remove(path)
+    } else {
+      content = nil
+    }
+    do {
+      let resolved = try await resolve(path, useCache: !bypassCache)
+      guard navigationId == currentNavigationId else { return }
+      content = resolved
+    } catch {
+      guard navigationId == currentNavigationId else { return }
+      throw error
+    }
   }
 
   /// Resolves content for a path with optional caching.
@@ -271,19 +206,27 @@ final class BrowserManager {
       return hydrateChildren(cached)
     }
 
-    let resolvedTrack = try await resolveUncached(normalizedPath)
+    let resolvedTrack = try await pages.resolve(normalizedPath)
 
     // Cache the resolved content for future navigation
     contentCache.set(normalizedPath, value: resolvedTrack)
 
-    // Cache children for track lookups
-    cacheChildren(resolvedTrack)
-
     return hydrateChildren(resolvedTrack)
   }
 
   /// Invalidates the content cache for a specific path.
-  func invalidateContentCache(_ path: String) {
+  ///
+  /// Expects a *container* path. A contextual path (`…?__trackId=…`) addresses
+  /// a child, not a cache entry — entries are keyed by the stripped parent — so
+  /// passing one used to remove nothing at all, silently. Android `require`s the
+  /// same precondition; this throws so the misuse surfaces identically on both
+  /// platforms instead of no-opping on one.
+  func invalidateContentCache(_ path: String) throws {
+    guard !BrowserPathHelper.isContextual(path) else {
+      throw BrowserError.invalidConfiguration(
+        "invalidateContentCache() expects a container path, not a contextual path: \(path)",
+      )
+    }
     contentCache.remove(path)
   }
 
@@ -291,324 +234,23 @@ final class BrowserManager {
   /// Runs from `invalidateAllContent`, so re-resolve the layer thunks too.
   func clearContentCache() {
     contentCache.clear()
-    layerGeneration += 1
-  }
-
-  /// Refreshes the current path by invalidating cache and re-resolving.
-  ///
-  /// Uses navigation ID tracking to prevent race conditions.
-  func refresh() async throws {
-    // Increment navigation ID and capture for this refresh
-    currentNavigationId += 1
-    let navigationId = currentNavigationId
-
-    let currentPath = path
-    contentCache.remove(currentPath)
-    let resolved = try await resolve(currentPath, useCache: false)
-
-    // Only apply result if this is still the current navigation
-    guard navigationId == currentNavigationId else { return }
-
-    content = resolved
-  }
-
-  private func resolveUncached(_ path: String) async throws -> ResolvedTrack {
-    // Match an explicit route (or the '*' default). With no match, fall back to
-    // the implicit default: fetch the path via the request + browse config.
-    let routeEntry = (config.routes).flatMap { findBestRouteMatch(path: path, routes: $0) }
-
-    let resolvedTrack: ResolvedTrack = if let (entry, routeMatch) = routeEntry {
-      try await resolveRouteEntry(entry, path: path, params: routeMatch.params)
-    } else {
-      // Implicit default — no route config, just request → browse → fetch path.
-      try await resolveFromConfig(
-        nil, path: path, params: ["path": path],
-      )
-    }
-
-    // Validate and transform children
-    if let children = resolvedTrack.children {
-      let transformed = try await transformChildren(
-        children, parentPath: path, routeEntry: routeEntry?.0,
-      )
-      return resolvedTrack.copying(children: transformed)
-    }
-
-    return resolvedTrack
-  }
-
-  // MARK: - Route Resolution
-
-  private func findBestRouteMatch(
-    path: String,
-    routes: [NativeRouteEntry],
-  ) -> (NativeRouteEntry, RouteMatch)? {
-    // Filter out special routes
-    let browseRoutes = routes.filter {
-      $0.path != Self.tabsRoutePath &&
-        $0.path != Self.searchRoutePath &&
-        $0.path != Self.defaultRoutePath
-    }
-
-    // Try to find a matching route
-    if let match = router.findBestMatch(path: path, routes: browseRoutes) {
-      return match
-    }
-
-    // Fall back to __default__ if present
-    if let defaultRoute = routes.first(where: { $0.path == Self.defaultRoutePath }) {
-      return (defaultRoute, RouteMatch(params: ["path": path]))
-    }
-
-    return nil
-  }
-
-  private func resolveRouteEntry(
-    _ entry: NativeRouteEntry,
-    path: String,
-    params: [String: String],
-  ) async throws -> ResolvedTrack {
-    // Priority: callback > config > static
-    if let callback = entry.browseCallback {
-      let callbackParam = BrowserSourceCallbackParam(path: path, routeParams: params)
-      // BrowserSourceCallback may return a BrowseResult synchronously or via a
-      // Promise. Nitro flattens (ResolvedTrack | BrowseError) | Promise<BrowseResult>
-      // into a 3-arm variant: sync track, sync error, or a Promise resolving to a
-      // BrowseResult (which is itself a ResolvedTrack | BrowseError variant).
-      switch try await callback(callbackParam).await() {
-      case let .first(resolvedTrack):
-        return resolvedTrack
-      case let .second(browseError):
-        throw BrowserError.callbackError(browseError.error)
-      case let .third(promise):
-        switch try await promise.await() {
-        case let .first(resolvedTrack):
-          return resolvedTrack
-        case let .second(browseError):
-          throw BrowserError.callbackError(browseError.error)
-        }
-      }
-    }
-
-    if let browseConfig = entry.browseConfig {
-      return try await resolveFromConfig(
-        browseConfig, path: path, params: params,
-      )
-    }
-
-    if let staticContent = entry.browseStatic {
-      return staticContent
-    }
-
-    throw BrowserError.contentNotFound(path: path)
-  }
-
-  /// 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; `kindConfig` is nil for kinds with no per-kind config.
-  private func buildApiRequest(
-    kind kindConfig: TransformableRequestConfig?,
-    _ routeConfig: TransformableRequestConfig?,
-    path: String,
-    params: [String: String],
-    initialQuery: [String: String]? = nil,
-  ) async throws -> HttpClient.HttpRequest {
-    try await ensureLayersResolved()
-
-    var merged = RequestConfig(
-      method: nil, path: path, baseUrl: nil, headers: nil,
-      query: nil, body: nil, contentType: nil, userAgent: nil,
-    )
-    merged = try await applyLayer(resolvedRequestLayer, to: merged, params: params)
-    if let initialQuery, !initialQuery.isEmpty {
-      merged = merged.copying(query: mergeDicts(merged.query, initialQuery))
-    }
-    merged = try await applyLayer(kindConfig, to: merged, params: params)
-    merged = try await applyLayer(routeConfig, to: merged, params: params)
-
-    guard let baseUrl = merged.baseUrl else {
-      throw BrowserError.invalidConfiguration("No URL configured for route")
-    }
-    var url = BrowserPathHelper.buildUrl(baseUrl: baseUrl, path: merged.path ?? path)
-    if let query = merged.query, !query.isEmpty {
-      url = BrowserPathHelper.appendQuery(query, to: url)
-    }
-
-    return HttpClient.HttpRequest(
-      url: url,
-      method: merged.method?.stringValue ?? "GET",
-      headers: merged.headers,
-      body: merged.body,
-      contentType: merged.contentType ?? HttpClient.defaultContentType,
-      userAgent: merged.userAgent ?? HttpClient.defaultUserAgent,
+    requests.invalidateLayers()
+    // The search slot is content too: a locale switch or a re-auth changes
+    // titles, src, artwork and availability, and nothing else ever evicts it,
+    // so a repeated query returned pre-invalidation results forever.
+    lastSearchKey = nil
+    lastSearchResults = nil
+  }
+
+  /// `error` as the app's `formatNavigationError` displays it, or its default display when
+  /// there is no formatter or it fails.
+  func formatted(_ error: NavigationError, path: String) async -> FormattedNavigationError {
+    let fallback = error.defaultFormatted()
+    guard let formatter = config.formatNavigationError else { return fallback }
+    let params = FormatNavigationErrorParams(
+      error: error, defaultFormatted: fallback, path: path, kind: NavigationErrorKind(path: path),
     )
-  }
-
-  /// Resolves a browse route: a page object (`{title,url,children:[…]}`).
-  /// The browse kind layer is the cached resolved layer (`resolvedBrowseLayer`),
-  /// populated by `ensureLayersResolved()` inside `buildApiRequest`.
-  private func resolveFromConfig(
-    _ routeConfig: TransformableRequestConfig?,
-    path: String,
-    params: [String: String],
-  ) async throws -> ResolvedTrack {
-    try await ensureLayersResolved()
-    let request = try await buildApiRequest(
-      kind: resolvedBrowseLayer, 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 children = nitroResult.children {
-      logger.debug("  children: \(children.count) tracks")
-    }
-
-    return nitroResult
-  }
-
-  /// Applies one request-config layer (request / browse / route) onto a base.
-  /// A transform (async and/or sync) wins completely: it receives the base and its
-  /// result replaces it. When both are set they run as a pipeline — async first,
-  /// then sync. Otherwise the layer's static fields merge over the base. `path` is
-  /// carried from the base (only a transform may change it).
-  func applyLayer(
-    _ layer: TransformableRequestConfig?,
-    to base: RequestConfig,
-    params: [String: String],
-  ) async throws -> RequestConfig {
-    guard let layer else { return base }
-    // Run-both transform: async first, then sync (each replaces the running config).
-    // The bridge await depth — the bug-prone part — is centralised in awaitAsync/SyncConfig.
-    if layer.transform != nil || layer.transformSync != nil {
-      var result = base
-      if let transform = layer.transform { result = try await awaitAsyncConfig(transform(result, params)) }
-      if let transformSync = layer.transformSync { result = try await awaitSyncConfig(transformSync(result, params)) }
-      return result
-    }
-    return RequestConfig(
-      method: layer.method ?? base.method,
-      path: base.path,
-      baseUrl: layer.baseUrl ?? base.baseUrl,
-      headers: mergeDicts(base.headers, layer.headers),
-      query: mergeDicts(base.query, layer.query),
-      body: layer.body ?? base.body,
-      contentType: layer.contentType ?? base.contentType,
-      userAgent: layer.userAgent ?? base.userAgent,
-    )
-  }
-
-  /// Merges two optional dictionaries, with override values taking precedence.
-  /// Delegates to the pure, unit-tested `MediaResolveComposer.mergeDicts`.
-  func mergeDicts(
-    _ base: [String: String]?,
-    _ override: [String: String]?,
-  ) -> [String: String]? {
-    MediaResolveComposer.mergeDicts(base, override)
-  }
-
-  // MARK: - Layer Resolvers
-
-  /// Resolve one layer: invoke its resolver if present, else return the static
-  /// layer config unchanged. 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 — a double await.
-  private func resolveLayer(
-    config staticConfig: TransformableRequestConfig?,
-    resolver: (() -> Promise<Promise<TransformableRequestConfig>>)?,
-  ) async throws -> TransformableRequestConfig? {
-    guard let resolver else { return staticConfig }
-    return try await resolver().await().await()
-  }
-
-  /// Ensure request/browse resolvers are resolved for the current generation,
-  /// caching the results. Re-resolves after a generation bump (config change /
-  /// invalidateAllContent). Idempotent within a generation.
-  func ensureLayersResolved() async throws {
-    guard resolvedLayerGeneration != layerGeneration else { return }
-    let generation = layerGeneration
-    let req = try await resolveLayer(config: config.request, resolver: config.requestResolver)
-    let brw = try await resolveLayer(config: config.browse, resolver: config.browseResolver)
-    // Only commit if still current (a newer generation may have started during await).
-    guard generation == layerGeneration else { return }
-    resolvedRequestLayer = req
-    resolvedBrowseLayer = brw
-    resolvedLayerGeneration = generation
-  }
-
-  // MARK: - Child Transformation
-
-  private func transformChildren(
-    _ children: [Track],
-    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
-
-      if track.src != nil, track.url == nil {
-        let contextualUrl = BrowserPathHelper.build(parentPath: parentPath, trackId: track.src!)
-        transformedTrack = track.copying(url: contextualUrl)
-      }
-
-      // 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)
-      }
-
-      // 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,
-          ))
-        }
-        transformedTrack = transformedTrack.copying(imageRow: resolvedItems)
-      }
-
-      transformed.append(transformedTrack)
-    }
-
-    return transformed
+    return await (try? formatter(params).await()) ?? fallback
   }
 
   // MARK: - Search
@@ -621,71 +263,43 @@ final class BrowserManager {
     )
   }
 
-  /// Structured search. Emits `q` plus any of `mode`/`genre`/`artist`/`album`/
-  /// `title`/`playlist` that are set, mirroring Android's `executeSearchApiRequest`
-  /// and the web stub. Cached by `query`.
+  /// The cache identity of a search. Sorted so key order is stable, and
+  /// `\u{1}`-delimited so two different param sets can't serialize alike.
+  private static func searchCacheKey(_ params: SearchParams) -> String {
+    PageResolver.searchQueryParams(params)
+      .sorted { $0.key < $1.key }
+      .map { "\($0.key)=\($0.value)" }
+      .joined(separator: "\u{1}")
+  }
+
+  /// Structured search, cached by the full parameter set.
+  ///
+  /// Voice intents reuse `query` across different structures —
+  /// `MediaIntentCriteria` falls back to the structured value when there is no
+  /// spoken name, so "play jazz" (genre) and a text search for "jazz" arrive
+  /// with an identical `query` — hence `searchCacheKey` rather than `query`.
   func search(_ params: SearchParams) async throws -> ResolvedTrack {
     let query = params.query
+    let cacheKey = Self.searchCacheKey(params)
 
-    // Check cache - re-hydrate favorites since they may have changed
-    if query == lastSearchQuery, let results = lastSearchResults {
-      let hydratedResults = results.map { hydrateFavorite($0) }
-      return makeSearchResult(query: query, results: hydratedResults)
-    }
-
-    guard let routes = config.routes else {
-      throw BrowserError.contentNotFound(path: Self.searchRoutePath)
-    }
-
-    guard let searchEntry = routes.first(where: { $0.path == Self.searchRoutePath }) else {
-      throw BrowserError.contentNotFound(path: Self.searchRoutePath)
-    }
-
-    var results: [Track]
-
-    if let callback = searchEntry.searchCallback {
-      let outerPromise = callback(params)
-      let innerPromise = try await outerPromise.await()
-      results = try await innerPromise.await()
-    } else if let searchConfig = searchEntry.searchConfig {
-      // Search is its own kind — request → search route (no browse layer). The
-      // endpoint returns a bare Track array (unlike browse's page object). The
-      // search params go through `initialQuery` so they land in `request.query`
-      // (and the URL); a config with a transform only ever sees the base.
-      // Seed the search config's static path onto the base — a layer's static
-      // path never applies (carried from the base; only a transform may change
-      // it). Matches the web stub's fetchSearchResults and Android.
-      var queryParams: [String: String] = ["q": query]
-      if let mode = params.mode { queryParams["mode"] = mode.stringValue }
-      if params.reference == .my { queryParams["reference"] = "my" }
-      if let genre = params.genre { queryParams["genre"] = genre }
-      if let artist = params.artist { queryParams["artist"] = artist }
-      if let album = params.album { queryParams["album"] = album }
-      if let title = params.title { queryParams["title"] = title }
-      if let playlist = params.playlist { queryParams["playlist"] = playlist }
-
-      let request = try await buildApiRequest(
-        kind: nil, searchConfig, path: searchConfig.path ?? "", params: ["q": query],
-        initialQuery: queryParams,
-      )
-      logger.debug("Searching via API: \(request.url)")
-      let jsonTracks: [JsonTrack] = try await httpClient.requestJson(request, as: [JsonTrack].self)
-      results = jsonTracks.map { $0.toNitro() }
-    } else {
-      throw BrowserError.contentNotFound(path: Self.searchRoutePath)
+    // Check cache - hydrate favorites on the way out, since they may have
+    // changed since the search ran (the slot holds the raw results for exactly
+    // this reason — see below).
+    if cacheKey == lastSearchKey, let results = lastSearchResults {
+      return makeSearchResult(query: query, results: results)
     }
 
-    // Hydrate favorites in results
-    let hydratedResults = results.map { hydrateFavorite($0) }
+    let results = try await pages.search(params)
 
-    // Cache results
-    lastSearchQuery = query
-    lastSearchResults = hydratedResults
+    // Cache the RAW results, never the hydrated ones: hydration is one-shot
+    // (`hydrateFavorite` skips a track whose `favorited` is already set), so a
+    // hydrated slot would serve the favorites as they were at first search
+    // forever. The content cache keys on the same rule — it stores the
+    // unhydrated resolve and hydrates in `resolve()`.
+    lastSearchKey = cacheKey
+    lastSearchResults = results
 
-    // Cache individual tracks
-    hydratedResults.forEach { cacheTrack($0) }
-
-    return makeSearchResult(query: query, results: hydratedResults)
+    return makeSearchResult(query: query, results: results)
   }
 
   /// Search and return playable tracks for "play «X»" voice intents, drilling
@@ -693,37 +307,44 @@ 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 }
     }
   }
 
+  /// Wraps raw search results as a resolved page, hydrating favorites on the
+  /// way out — the single exit for `search`, so an unhydrated search page can't
+  /// be emitted (the same funnel `resolve()` gets from `hydrateChildren`).
   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.map { hydrateFavorite($0) })],
+      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,
+      icyCharset: nil,
     )
   }
 
@@ -731,55 +352,46 @@ final class BrowserManager {
 
   /// Query navigation tabs.
   func queryTabs() async throws -> [Track] {
-    guard let routes = config.routes else {
-      return []
-    }
-
-    guard let tabsEntry = routes.first(where: { $0.path == Self.tabsRoutePath }) else {
-      return []
-    }
-
-    let resolved = try await resolveRouteEntry(tabsEntry, path: Self.tabsRoutePath, params: [:])
-    let tabTracks = resolved.children ?? []
-
-    tabs = tabTracks
-    return tabTracks
+    guard let tabs = try await pages.tabs() else { return [] }
+    self.tabs = tabs
+    return tabs
   }
 
   // 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 .imageRow(let items):
-      sectionTracks = items.map { $0.toTrack() }
-    case .run(let 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")
@@ -787,10 +399,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)")
@@ -802,20 +422,6 @@ final class BrowserManager {
 
     return (tracks: playableTracks, selectedIndex: selectedIndex)
   }
-
-  // MARK: - Accessors
-
-  func getPath() -> String {
-    path
-  }
-
-  func getContent() -> ResolvedTrack? {
-    content
-  }
-
-  func getTabs() -> [Track]? {
-    tabs
-  }
 }
 
 // MARK: - TrackSelectionBrowser