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

package/src/web/browser/BrowserManager.ts

@@ -2,18 +2,26 @@ import type { NavigationErrorType } from '../../features'
 import type {
   Track,
   ResolvedTrack,
+  Section,
   TransformableRequestConfig
 } from '../../types'
 import type { NativeBrowserConfiguration } from '../../types/browser-native'
 import type { HttpClient } from '../http/HttpClient'
 import type { FavoriteManager } from './FavoriteManager'
 import type { NavigationErrorManager } from './NavigationErrorManager'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
 import { assertedNotNullish } from '../../utils/validation'
 import { RequestConfigBuilder } from '../http/RequestConfigBuilder'
 import { SimpleRouter } from '../SimpleRouter'
 import { BrowserPathHelper } from '../util/BrowserPathHelper'
 import { assertBrowsePageShape } from './assertBrowsePageShape'
 import { parseSearchResponse } from './parseSearchResponse'
+import {
+  flattenSections,
+  flattenedChildren,
+  normalizePage,
+  sectionContaining
+} from './sections'
 
 /**
  * Manages browser navigation, route resolution, and content loading.
@@ -158,14 +166,13 @@ export class BrowserManager {
     // Determine initial path
     let initialPath = value.path
 
-    // If no path specified, try to get first tab URL
+    // If no path specified, try to get first tab path
     if (!initialPath) {
       const tabsRoute = value.routes?.find((r) => r.path === '__tabs__')
-      if (tabsRoute?.browseStatic?.children?.[0]?.url) {
-        initialPath = tabsRoute.browseStatic.children[0].url
-      } else {
-        initialPath = '/'
-      }
+      const staticTabs = tabsRoute?.browseStatic
+        ? flattenedChildren(tabsRoute.browseStatic)
+        : []
+      initialPath = staticTabs[0]?.path ?? '/'
     }
 
     if (initialPath) {
@@ -182,16 +189,16 @@ export class BrowserManager {
   }
 
   /**
-   * Navigates to a track's URL.
+   * Navigates to a track's path.
    */
   async navigateTrack(track: Track): Promise<void> {
     this.navigationErrorManager.clearNavigationError()
-    const url = track.url
-    if (!url) {
-      console.warn('Track has no URL to navigate to')
+    const path = track.path
+    if (!path) {
+      console.warn('Track has no path to navigate to')
       return
     }
-    await this.navigate(url)
+    await this.navigate(path)
   }
 
   /**
@@ -247,23 +254,15 @@ export class BrowserManager {
         return
       }
 
-      // Add contextual URLs to non-search content (matches Android behavior where
-      // search() bypasses the resolve() contextual URL logic).
-      // Shallow copy to avoid mutating the original config object (e.g., browseStatic
-      // from routes), which would break search that reads from the same source.
-      if (content?.children && !isSearchPath) {
+      // Resolution returns canonical sectioned pages; add contextual paths
+      // to non-search content (matches Android behavior where search()
+      // bypasses the resolve() contextual-path logic). Copies avoid mutating
+      // the original config object (e.g., browseStatic from routes), which
+      // would break search that reads from the same source.
+      if (content?.sections && !isSearchPath) {
         content = {
           ...content,
-          children: content.children.map((track) => {
-            // If track has src, always add/update contextual URL with current path context
-            // This matches Android's BrowserManager.kt:436-441
-            if (track.src) {
-              const contextualUrl = `${path}?__trackId=${encodeURIComponent(track.src)}`
-              return { ...track, url: contextualUrl }
-            }
-            // Return a shallow copy in attempt to avoid mutating original config objects
-            return { ...track }
-          })
+          sections: this.addContextualPaths(path, content.sections)
         }
       }
 
@@ -314,13 +313,43 @@ export class BrowserManager {
     }
   }
 
+  /**
+   * Stamps contextual paths onto a page's sections. A playable track gets a
+   * contextual path carrying its identity (id ?? src) so the queue can be
+   * re-expanded from it later, plus its flat page position (children
+   * concatenated in section order — ADR 0009/0010) as a duplicate-identity
+   * tie-breaker. Non-playable tracks are shallow-copied to avoid mutating
+   * original config objects (e.g., browseStatic from routes).
+   */
+  private addContextualPaths(path: string, sections: Section[]): Section[] {
+    let index = 0
+    return sections.map((section) => ({
+      ...section,
+      children: section.children.map((track) => {
+        const flatIndex = index++
+        const identity = getTrackIdentity(track)
+        if (track.src && identity) {
+          return {
+            ...track,
+            path: BrowserPathHelper.build(path, identity, flatIndex)
+          }
+        }
+        return { ...track }
+      })
+    }))
+  }
+
   /**
    * Resolves search content from a search path.
-   * Returns a ResolvedTrack with raw children (no contextual URLs).
+   * Returns a canonical sectioned page — one untitled section of raw search
+   * results (no contextual URLs), like the native `makeSearchResult`.
    * Matches Android's BrowserManager.search() which bypasses resolve() entirely.
    *
+   * A failed search propagates, so `navigate` turns it into a navigation error
+   * the way it does a failed browse resolve.
+   *
    * @param searchPath The search path (format: /__search?q=query)
-   * @returns ResolvedTrack containing search results as children
+   * @returns ResolvedTrack containing search results as one untitled section
    */
   private async resolveSearchContent(
     searchPath: string
@@ -353,26 +382,17 @@ export class BrowserManager {
     }
     // Handle request config-based search via the shared layered fetch.
     else if (searchRoute.searchConfig) {
-      try {
-        searchResults = await this.fetchSearchResults(
-          searchRoute.searchConfig,
-          {
-            q: query
-          }
-        )
-      } catch (error) {
-        console.error('Search failed:', error)
-        return undefined
-      }
+      searchResults = await this.fetchSearchResults(searchRoute.searchConfig, {
+        q: query
+      })
     }
 
-    // Create ResolvedTrack with raw children
-    // Search callbacks should return fresh tracks without contextual URLs (like Android)
-    return {
-      url: searchPath,
+    // Search callbacks should return fresh tracks without contextual paths (like Android)
+    return normalizePage({
+      path: searchPath,
       title: `Search: ${query}`,
       children: searchResults
-    }
+    })
   }
 
   /**
@@ -383,10 +403,13 @@ export class BrowserManager {
   private async transformArtworkForContent(
     content: ResolvedTrack
   ): Promise<ResolvedTrack> {
+    // No short-circuit on a missing artwork config: Android gates per *track*
+    // (`artworkConfig == null && track.artwork == null`), so a track carrying a
+    // plain `artwork` URL still gets an `artworkSource`. Returning early here
+    // meant an app with no `artwork` block never populated the field at all —
+    // `resolveArtworkSourceAsync` already handles the no-config case the way
+    // `resolveArtworkUrl` does on Android.
     const artworkConfig = this._configuration.artwork
-    if (!artworkConfig) {
-      return content
-    }
     // The shared request layer applies to artwork too — use the resolved layer
     // (resolver result or static config) so a resolver-only config still works.
     await this.ensureLayersResolved()
@@ -400,35 +423,40 @@ export class BrowserManager {
         artworkConfig
       )
 
-    // Transform children artwork
-    let transformedChildren: Track[] | undefined
-    if (content.children) {
-      transformedChildren = await Promise.all(
-        content.children.map(async (track) => {
-          const artworkSource =
-            await RequestConfigBuilder.resolveArtworkSourceAsync(
-              track,
-              requestConfig,
-              artworkConfig
-            )
-          if (artworkSource && !track.artworkSource) {
-            return { ...track, artworkSource }
-          }
-          return track
-        })
+    // Transform children artwork, section by section
+    const transformTrack = async (track: Track): Promise<Track> => {
+      const artworkSource =
+        await RequestConfigBuilder.resolveArtworkSourceAsync(
+          track,
+          requestConfig,
+          artworkConfig
+        )
+      if (artworkSource && !track.artworkSource) {
+        return { ...track, artworkSource }
+      }
+      return track
+    }
+    let transformedSections: Section[] | undefined
+    if (content.sections) {
+      transformedSections = await Promise.all(
+        content.sections.map(async (section) => ({
+          ...section,
+          children: await Promise.all(section.children.map(transformTrack))
+        }))
       )
     }
 
     return {
       ...content,
       artworkSource: parentArtworkSource ?? content.artworkSource,
-      children: transformedChildren ?? content.children
+      sections: transformedSections ?? content.sections
     }
   }
 
   /**
    * Resolves content from a route using browseCallback, browseStatic, or browseConfig.
-   * Single source of truth for route resolution logic.
+   * Single source of truth for route resolution logic. Returns canonical
+   * sectioned pages (normalizePage) — consumers never see authored `children`.
    *
    * @param route The route configuration to resolve
    * @param path The path being navigated to
@@ -470,23 +498,26 @@ export class BrowserManager {
         )
         return undefined
       }
-      return result
+      return normalizePage(result)
     }
 
-    // Handle static ResolvedTrack route
+    // Handle static ResolvedTrack route (normalizePage also copies, so the
+    // config object itself is never handed out)
     if (route.browseStatic) {
-      return route.browseStatic
+      return normalizePage(route.browseStatic)
     }
 
     // Handle request config-based route via the layered request → browse → route
     // chain (matches native's resolveRouteEntry → resolveFromConfig).
     if (route.browseConfig) {
       try {
-        return await this.resolveFromConfig(
-          this._configuration.browse,
-          route.browseConfig,
-          path,
-          routeParams
+        return normalizePage(
+          await this.resolveFromConfig(
+            this._configuration.browse,
+            route.browseConfig,
+            path,
+            routeParams
+          )
         )
       } catch (error: unknown) {
         console.error(`Failed to resolve ${errorContext}:`, error)
@@ -498,6 +529,24 @@ export class BrowserManager {
     return undefined
   }
 
+  /**
+   * Ensures the request layer is resolved for the current generation and
+   * returns it — the resolver's result when a `requestResolver` is configured,
+   * else the static `request`.
+   *
+   * Consumers outside the browse path (media URL building, artwork) must reach
+   * the request layer through this rather than reading `configuration.request`,
+   * or a resolver-only config silently loses its baseUrl, headers and transform
+   * exactly where a credential is needed. Mirrors Android's
+   * `BrowserManager.resolvedRequestConfig()`, which carries the same warning.
+   */
+  async resolvedRequestConfig(): Promise<
+    TransformableRequestConfig | undefined
+  > {
+    await this.ensureLayersResolved()
+    return this._resolvedRequest
+  }
+
   /**
    * Ensures the request/browse layer configs are resolved for the current
    * generation. Any present resolver is invoked once per generation and the
@@ -573,7 +622,7 @@ export class BrowserManager {
    * `request → search` chain (search is its own kind — no browse layer). The
    * query params are seeded on the base so they survive both the static merge
    * and a search `transform`. Shared by `resolveSearchContent` (navigating to a
-   * search path) and `SearchManager` (the voice/`onSearch` API), so the ladder
+   * search path) and `SearchManager` (the voice/`search` API), so the ladder
    * isn't duplicated. Errors propagate to the caller.
    */
   async fetchSearchResults(
@@ -592,6 +641,8 @@ export class BrowserManager {
 
   /**
    * Resolves content for a specific path using configured routes.
+   * Like the native resolve pipelines, the returned page is canonical
+   * sectioned shape — `children` sugar is normalized away at this seam.
    */
   private async resolveContent(
     path: string
@@ -658,11 +709,13 @@ export class BrowserManager {
       this._configuration.browseResolver
     ) {
       try {
-        return await this.resolveFromConfig(
-          this._configuration.browse,
-          undefined,
-          path,
-          { path }
+        return normalizePage(
+          await this.resolveFromConfig(
+            this._configuration.browse,
+            undefined,
+            path,
+            { path }
+          )
         )
       } catch (error: unknown) {
         console.error('Failed to resolve default browse content:', error)
@@ -686,12 +739,14 @@ export class BrowserManager {
     }
 
     const result = await this.resolveRouteContent(tabsRoute, '/', {}, 'Tabs')
-    const tabs = result?.children ?? []
+    // Tabs are a flat list, not a page — a sectioned tabs source flattens.
+    const tabs = result ? flattenSections(result.sections) : []
 
     // Transform artwork URLs on tabs via the async resolver so the shared
     // request layer (incl. its transform) applies, matching content/search.
+    // Gated per track inside the resolver, as on Android — see
+    // `transformArtworkForContent`.
     const artworkConfig = this._configuration.artwork
-    if (!artworkConfig) return tabs
     // Resolved request layer (resolver or static), matching content/search.
     await this.ensureLayersResolved()
     const requestConfig = this._resolvedRequest
@@ -724,44 +779,79 @@ export class BrowserManager {
   /**
    * Expands a queue from a contextual URL.
    * Resolves the parent container to get all siblings.
-   * Matches Android's BrowserManager.expandQueueFromContextualUrl() behavior.
+   * Matches Android's BrowserManager.expandQueueFromContextualPath() behavior.
    *
-   * @param contextualUrl The contextual URL (format: /path?__trackId=trackSrc)
+   * @param contextualPath The contextual path (format: /path?__trackId=trackSrc)
    * @returns Object with tracks and selectedIndex, or undefined if expansion fails
    */
-  async expandQueueFromContextualUrl(
-    contextualUrl: string
+  async expandQueueFromContextualPath(
+    contextualPath: string
   ): Promise<{ tracks: Track[]; selectedIndex: number } | undefined> {
-    const trackId = BrowserPathHelper.extractTrackId(contextualUrl)
+    const trackId = BrowserPathHelper.extractTrackId(contextualPath)
     if (!trackId) return undefined
 
     try {
       // Resolve the parent container to get all siblings
-      const parentPath = BrowserPathHelper.stripTrackId(contextualUrl)
+      const parentPath = BrowserPathHelper.stripTrackId(contextualPath)
       const parentResolvedTrack = await this.resolveContent(parentPath)
-      const children = parentResolvedTrack?.children
+      const rawSections = parentResolvedTrack?.sections
 
-      if (!children || children.length === 0) {
+      if (!rawSections || rawSections.every((s) => s.children.length === 0)) {
         console.warn('Parent has no children, cannot expand queue')
         return undefined
       }
 
-      // Filter to only playable tracks (tracks with src)
-      const playableTracks = children.filter((track) => track.src != null)
+      // Stamp contextual paths so queued tracks carry their own queue context
+      // (navigate() stamps the displayed page the same way).
+      const sections = this.addContextualPaths(parentPath, rawSections)
+
+      // 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; a stale index
+      // falls back to the first identity match. An identity that no longer
+      // appears on the page aborts the expansion — the caller falls back to
+      // the single track.
+      const tappedIndex = BrowserPathHelper.extractIndex(contextualPath)
+      const scoped = sectionContaining(sections, trackId, tappedIndex)
+      if (!scoped) {
+        console.warn(
+          `Track with identity='${trackId}' not found on parent page`
+        )
+        return undefined
+      }
+
+      // Filter to only playable tracks (tracks with src). A disabled track is
+      // unavailable — queue expansion excludes it, so auto-advance never
+      // meets one (Track.disabled).
+      const isQueueable = (track: Track) =>
+        track.src != null && track.disabled !== true
+      const playableTracks = scoped.tracks.filter(isQueueable)
 
       if (playableTracks.length === 0) {
-        console.warn('Parent has no playable tracks, cannot expand queue')
+        console.warn('Section has no playable tracks, cannot expand queue')
         return undefined
       }
 
-      // Find the index of the selected track in the playable tracks array
-      const selectedIndex = playableTracks.findIndex(
-        (track) => track.src === trackId
-      )
+      // Selected position: the pinned copy when the stamp survived, else
+      // the first identity match.
+      let selectedIndex = -1
+      if (scoped.tappedOffset !== undefined) {
+        const tapped = scoped.tracks[scoped.tappedOffset]
+        if (tapped != null && isQueueable(tapped)) {
+          selectedIndex =
+            scoped.tracks.slice(0, scoped.tappedOffset + 1).filter(isQueueable)
+              .length - 1
+        }
+      }
+      if (selectedIndex < 0) {
+        selectedIndex = playableTracks.findIndex(
+          (track) => getTrackIdentity(track) === trackId
+        )
+      }
 
       if (selectedIndex < 0) {
         console.warn(
-          `Track with src='${trackId}' not found in playable children`
+          `Track with identity='${trackId}' not found in playable children`
         )
         return undefined
       }
@@ -776,7 +866,7 @@ export class BrowserManager {
       return { tracks: playableTracks, selectedIndex }
     } catch (error) {
       console.error(
-        `Error expanding queue from contextual URL: ${contextualUrl}`,
+        `Error expanding queue from contextual path: ${contextualPath}`,
         error
       )
       return undefined
@@ -800,23 +890,31 @@ export class BrowserManager {
     startPositionMs: number,
     searchQuery?: string
   ): Promise<{ tracks: Track[]; startIndex: number; startPositionMs: number }> {
-    // Single track: check for search context or contextual URL
+    // Single track: check for search context or contextual path
     if (tracks.length === 1) {
       const track = assertedNotNullish(tracks[0])
-      const trackUrl = track.url
+      const trackPath = track.path
 
       // If search query present, expand search results
       if (searchQuery) {
-        // Execute search (will hit cache if already performed)
+        // Execute search (will hit cache if already performed). Disabled
+        // tracks never play, so they never enter a search-built queue
+        // (Track.disabled — mirrors both native platforms).
         const searchResults = await this.resolveSearchContent(
           BrowserPathHelper.createSearchPath(searchQuery)
         )
-        const searchTracks = searchResults?.children
+        const searchTracks = flattenSections(searchResults?.sections).filter(
+          (t) => t.disabled !== true
+        )
 
-        if (searchTracks && searchTracks.length > 0) {
-          // Find the selected track in search results
+        if (searchTracks.length > 0) {
+          // Find the selected track in search results by path or identity
+          // (matches Android's three-way mediaId match)
+          const identity = getTrackIdentity(track)
           const selectedIdx = searchTracks.findIndex(
-            (t) => t.url === trackUrl || t.src === track.src
+            (t) =>
+              t.path === trackPath ||
+              (identity !== undefined && getTrackIdentity(t) === identity)
           )
 
           if (selectedIdx >= 0) {
@@ -829,14 +927,14 @@ export class BrowserManager {
         }
       }
 
-      // Check if contextual URL - expand from parent
+      // Check if contextual path - expand from parent
       // Note: The queueSourcePath optimization is handled by the caller (NativeAudioBrowser.navigateTrackAsync)
       // which has access to the existing queue and can skip to the track directly.
       // This matches Android where MediaSessionCallback handles the optimization before calling
       // BrowserManager.resolveMediaItemsForPlayback.
-      if (trackUrl && BrowserPathHelper.isContextual(trackUrl)) {
-        const parentPath = BrowserPathHelper.stripTrackId(trackUrl)
-        const expanded = await this.expandQueueFromContextualUrl(trackUrl)
+      if (trackPath && BrowserPathHelper.isContextual(trackPath)) {
+        const parentPath = BrowserPathHelper.stripTrackId(trackPath)
+        const expanded = await this.expandQueueFromContextualPath(trackPath)
 
         if (expanded) {
           // Store source path for optimization by caller on next invocation
@@ -855,13 +953,13 @@ export class BrowserManager {
   }
 
   /**
-   * Gets the default navigation path (first tab URL or '/').
+   * Gets the default navigation path (first tab path or '/').
    */
   private getDefaultPath(): string {
     // Try to get first tab as default path
     if (this._tabs && this._tabs.length > 0) {
       const firstTab = this._tabs[0]
-      return firstTab?.url ?? '/'
+      return firstTab?.path ?? '/'
     }
     return '/'
   }

package/src/web/browser/FavoriteManager.test.ts

@@ -0,0 +1,84 @@
+import { describe, expect, it } from 'vitest'
+import type { Track } from '../../types'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
+import { FavoriteManager } from './FavoriteManager'
+
+const withId: Track = {
+  id: 'abc123',
+  src: 'https://cdn.example.com/streams/abc123.mp3?token=x',
+  title: 'With id'
+}
+const srcOnly: Track = {
+  src: 'https://cdn.example.com/streams/plain.mp3',
+  title: 'Src only'
+}
+
+describe('getTrackIdentity', () => {
+  it('is the id when set', () => {
+    expect(getTrackIdentity(withId)).toBe('abc123')
+  })
+
+  it('falls back to src when id is absent or blank', () => {
+    expect(getTrackIdentity(srcOnly)).toBe(srcOnly.src)
+    expect(getTrackIdentity({ id: '', src: 's' })).toBe('s')
+  })
+
+  it('is undefined for a browsable-only track', () => {
+    expect(getTrackIdentity({ title: 'Folder' } as Track)).toBeUndefined()
+  })
+})
+
+describe('FavoriteManager identity matching', () => {
+  it('matches a stored id against track.id, not src', () => {
+    const manager = new FavoriteManager()
+    manager.setFavorites(['abc123'])
+    expect(manager.hydrateFavorite(withId).favorited).toBe(true)
+    // The id does not substring-match into another track's src
+    expect(manager.hydrateFavorite(srcOnly).favorited).toBeUndefined()
+  })
+
+  it('matches a stored src for id-less tracks', () => {
+    const manager = new FavoriteManager()
+    manager.setFavorites([srcOnly.src!])
+    expect(manager.hydrateFavorite(srcOnly).favorited).toBe(true)
+  })
+
+  it('does not src-match a track whose id takes identity precedence', () => {
+    const manager = new FavoriteManager()
+    manager.setFavorites([withId.src!])
+    // identity of withId is its id, so a stored src must NOT match
+    expect(manager.hydrateFavorite(withId).favorited).toBeUndefined()
+  })
+
+  it('never overwrites a caller-set favorited flag', () => {
+    const manager = new FavoriteManager()
+    manager.setFavorites(['abc123'])
+    const preset: Track = { ...withId, favorited: false }
+    expect(manager.hydrateFavorite(preset).favorited).toBe(false)
+  })
+
+  it('add/remove key the cache by identity', () => {
+    const manager = new FavoriteManager()
+    manager.addFavorite(withId)
+    expect(manager.isFavorited(withId)).toBe(true)
+    // Same identity, different src (volatile query param) still matches
+    expect(
+      manager.isFavorited({ ...withId, src: 'https://other.example/x.mp3' })
+    ).toBe(true)
+    manager.removeFavorite(withId)
+    expect(manager.isFavorited(withId)).toBe(false)
+  })
+
+  it('hydrateChildren stamps favorited across a normalized page', () => {
+    const manager = new FavoriteManager()
+    manager.setFavorites(['abc123'])
+    const page = manager.hydrateChildren({
+      path: '/list',
+      title: 'List',
+      sections: [{ children: [withId, srcOnly] }]
+    })
+    const tracks = page.sections?.[0]?.children
+    expect(tracks?.[0]?.favorited).toBe(true)
+    expect(tracks?.[1]?.favorited).toBeUndefined()
+  })
+})