react-native-audio-browser 0.2.0-next.11 → 0.2.0-next.13

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,40 @@ 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.
    *
    * @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
@@ -366,13 +392,12 @@ export class BrowserManager {
       }
     }
 
-    // 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
-    }
+    })
   }
 
   /**
@@ -400,35 +425,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 +500,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)
@@ -592,6 +625,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 +693,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,7 +723,8 @@ 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.
@@ -724,44 +762,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 +849,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 +873,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 +910,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 +936,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()
+  })
+})

package/src/web/browser/FavoriteManager.ts

@@ -1,14 +1,16 @@
 import type { Track, ResolvedTrack } from '../../types'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
 
 /**
- * Manages favorite state for tracks.
+ * Manages favorite state for tracks, keyed by track identity (`id` when set,
+ * falling back to `src` — see getTrackIdentity / ADR 0008).
  * Matches Android's favorite hydration behavior.
  */
 export class FavoriteManager {
   private favorites = new Set<string>()
 
   /**
-   * Sets the favorites cache from an array of track src values.
+   * Sets the favorites cache from an array of track identities.
    * This is typically called when favorites are loaded from storage.
    */
   setFavorites(favorites: string[]): void {
@@ -16,24 +18,27 @@ export class FavoriteManager {
   }
 
   /**
-   * Checks if a track is favorited based on its src.
+   * Checks if a track is favorited based on its identity.
    */
-  isFavorited(src: string): boolean {
-    return this.favorites.has(src)
+  isFavorited(track: Track): boolean {
+    const identity = getTrackIdentity(track)
+    return identity !== undefined && this.favorites.has(identity)
   }
 
   /**
-   * Adds a track src to the favorites cache.
+   * Adds a track to the favorites cache under its identity.
    */
-  addFavorite(src: string): void {
-    this.favorites.add(src)
+  addFavorite(track: Track): void {
+    const identity = getTrackIdentity(track)
+    if (identity !== undefined) this.favorites.add(identity)
   }
 
   /**
-   * Removes a track src from the favorites cache.
+   * Removes a track from the favorites cache under its identity.
    */
-  removeFavorite(src: string): void {
-    this.favorites.delete(src)
+  removeFavorite(track: Track): void {
+    const identity = getTrackIdentity(track)
+    if (identity !== undefined) this.favorites.delete(identity)
   }
 
   /**
@@ -48,8 +53,7 @@ export class FavoriteManager {
     if (track.favorited !== undefined && track.favorited !== null) return track
     if (this.favorites.size === 0) return track
 
-    const isFavorited = track.src ? this.favorites.has(track.src) : false
-    if (!isFavorited) return track
+    if (!this.isFavorited(track)) return track
 
     return {
       ...track,
@@ -58,22 +62,23 @@ export class FavoriteManager {
   }
 
   /**
-   * Hydrates favorites on all children of a ResolvedTrack.
-   * Matches Android's hydrateChildren behavior.
+   * Hydrates favorites on all tracks of a resolved page.
+   * Matches Android's hydrateChildren behavior. Pages reach hydration
+   * normalized (ADR 0010), so `sections` is the only structure to walk.
    *
-   * @param resolvedTrack ResolvedTrack with children to hydrate
-   * @returns ResolvedTrack with favorited properties set on children
+   * @param resolvedTrack Resolved page to hydrate
+   * @returns Resolved page with favorited properties set on its tracks
    */
   hydrateChildren(resolvedTrack: ResolvedTrack): ResolvedTrack {
-    const children = resolvedTrack.children
-    if (!children) return resolvedTrack
+    const { sections } = resolvedTrack
+    if (!sections) return resolvedTrack
 
-    const hydratedChildren = children.map((track) =>
-      this.hydrateFavorite(track)
-    )
     return {
       ...resolvedTrack,
-      children: hydratedChildren
+      sections: sections.map((section) => ({
+        ...section,
+        children: section.children.map((track) => this.hydrateFavorite(track))
+      }))
     }
   }
 }

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

@@ -3,7 +3,7 @@ import { assertBrowsePageShape } from './assertBrowsePageShape'
 
 describe('assertBrowsePageShape', () => {
   it('passes a page object through unchanged', () => {
-    const page = { url: '/x', title: 'X', children: [] }
+    const page = { path: '/x', title: 'X', children: [] }
     expect(assertBrowsePageShape(page, '/x')).toBe(page)
   })