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

package/src/web/browser/assertBrowsePageShape.ts

@@ -13,14 +13,16 @@ export function assertBrowsePageShape(
   if (Array.isArray(response)) {
     throw new Error(
       `Browse endpoint for "${path}" returned a JSON array; expected a ` +
-        `page object { title, children?: Track[] }. Wrap the rows in a ` +
-        `\`children\` array.`
+        `page object { title, sections?: Section[], children?: Track[] }. ` +
+        `Wrap the rows in a \`children\` array (one untitled section) or ` +
+        `group them into \`sections\`.`
     )
   }
   if (response === null || typeof response !== 'object') {
     throw new Error(
       `Browse endpoint for "${path}" returned ${JSON.stringify(response)}; ` +
-        `expected a page object { title, children?: Track[] }.`
+        `expected a page object { title, sections?: Section[], ` +
+        `children?: Track[] }.`
     )
   }
   return response as ResolvedTrack

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

@@ -5,10 +5,10 @@ import { classifyTrackNavigation } from './classifyTrackNavigation'
 const track = (fields: Partial<Track>): Track => fields as Track
 
 describe('classifyTrackNavigation', () => {
-  it('classifies a contextual url, exposing parent path and track id', () => {
+  it('classifies a contextual path, exposing parent path and track id', () => {
     expect(
       classifyTrackNavigation(
-        track({ url: '/library/radio?__trackId=song.mp3' })
+        track({ path: '/library/radio?__trackId=song.mp3' })
       )
     ).toEqual({
       kind: 'contextual',
@@ -17,25 +17,27 @@ describe('classifyTrackNavigation', () => {
     })
   })
 
-  it('classifies a non-contextual url as a browse navigation', () => {
-    expect(classifyTrackNavigation(track({ url: '/library/radio' }))).toEqual({
+  it('classifies a non-contextual path as a browse navigation', () => {
+    expect(classifyTrackNavigation(track({ path: '/library/radio' }))).toEqual({
       kind: 'browse'
     })
   })
 
-  it('classifies a track with src but no url as playable', () => {
+  it('classifies a track with src but no path as playable', () => {
     expect(classifyTrackNavigation(track({ src: 'song.mp3' }))).toEqual({
       kind: 'playable'
     })
   })
 
-  it('prefers browse over playable when a url is present', () => {
+  it('prefers browse over playable when a path is present', () => {
     expect(
-      classifyTrackNavigation(track({ url: '/library/radio', src: 'song.mp3' }))
+      classifyTrackNavigation(
+        track({ path: '/library/radio', src: 'song.mp3' })
+      )
     ).toEqual({ kind: 'browse' })
   })
 
-  it('classifies a track with neither url nor src as invalid', () => {
+  it('classifies a track with neither path nor src as invalid', () => {
     expect(classifyTrackNavigation(track({}))).toEqual({ kind: 'invalid' })
   })
 })

package/src/web/browser/classifyTrackNavigation.ts

@@ -4,10 +4,10 @@ import { BrowserPathHelper } from '../util/BrowserPathHelper'
 /**
  * How a selected track should be navigated, decided purely from its shape:
  * - `contextual` — a playable track carrying its parent queue context in a
- *   contextual URL (`{parentPath}?__trackId={src}`); expand/skip within that queue.
- * - `browse` — a browsable track (has a `url` that isn't contextual); drill in.
- * - `playable` — a bare playable track (`src`, no `url`); load and play it alone.
- * - `invalid` — neither `url` nor `src`; nothing to do.
+ *   contextual path (`{parentPath}?__trackId={src}`); expand/skip within that queue.
+ * - `browse` — a browsable track (has a `path` that isn't contextual); drill in.
+ * - `playable` — a bare playable track (`src`, no `path`); load and play it alone.
+ * - `invalid` — neither `path` nor `src`; nothing to do.
  */
 export type TrackNavigation =
   | { kind: 'contextual'; parentPath: string; trackId: string | undefined }
@@ -21,15 +21,15 @@ export type TrackNavigation =
  * caller; this only decides which action applies.
  */
 export function classifyTrackNavigation(track: Track): TrackNavigation {
-  const url = track.url
-  if (url && BrowserPathHelper.isContextual(url)) {
+  const path = track.path
+  if (path && BrowserPathHelper.isContextual(path)) {
     return {
       kind: 'contextual',
-      parentPath: BrowserPathHelper.stripTrackId(url),
-      trackId: BrowserPathHelper.extractTrackId(url)
+      parentPath: BrowserPathHelper.stripTrackId(path),
+      trackId: BrowserPathHelper.extractTrackId(path)
     }
   }
-  if (url) return { kind: 'browse' }
+  if (path) return { kind: 'browse' }
   if (track.src) return { kind: 'playable' }
   return { kind: 'invalid' }
 }

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

@@ -5,7 +5,11 @@ describe('parseSearchResponse', () => {
   it('extracts children from a page-object response', () => {
     const tracks = [{ src: '/a', title: 'A' }]
     expect(
-      parseSearchResponse({ url: '/search', title: 'Search', children: tracks })
+      parseSearchResponse({
+        path: '/search',
+        title: 'Search',
+        children: tracks
+      })
     ).toEqual(tracks)
   })
 
@@ -15,7 +19,9 @@ describe('parseSearchResponse', () => {
   })
 
   it('returns [] for a page object with no children', () => {
-    expect(parseSearchResponse({ url: '/search', title: 'Search' })).toEqual([])
+    expect(parseSearchResponse({ path: '/search', title: 'Search' })).toEqual(
+      []
+    )
   })
 
   it('returns [] for null / non-object responses', () => {

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

@@ -0,0 +1,91 @@
+import { describe, it, expect } from 'vitest'
+import type { ResolvedTrack, Track } from '../../types'
+import { flattenSections, normalizePage, sectionContaining } from './sections'
+
+const track = (src: string): Track => ({ title: src, src })
+
+describe('normalizePage', () => {
+  it('wraps plain children into one untitled section', () => {
+    const page: ResolvedTrack = {
+      path: '/p',
+      title: 'P',
+      children: [track('a'), track('b')]
+    }
+    const normalized = normalizePage(page)
+    expect(normalized.sections).toEqual([
+      { children: [track('a'), track('b')] }
+    ])
+    expect(normalized.children).toBeUndefined()
+  })
+
+  it('prefers sections when present and strips children', () => {
+    const page: ResolvedTrack = {
+      path: '/p',
+      title: 'P',
+      sections: [{ title: 'S', children: [track('a')] }],
+      children: [track('zzz')]
+    }
+    const normalized = normalizePage(page)
+    expect(normalized.sections).toEqual([
+      { title: 'S', children: [track('a')] }
+    ])
+    expect(normalized.children).toBeUndefined()
+  })
+
+  it('leaves a childless page without sections', () => {
+    expect(normalizePage({ path: '/p', title: 'P' }).sections).toBeUndefined()
+  })
+})
+
+describe('flattenSections', () => {
+  it('concatenates children in section order', () => {
+    const flat = flattenSections([
+      { title: 'A', children: [track('a1'), track('a2')] },
+      { children: [track('b1')] }
+    ])
+    expect(flat.map((t) => t.src)).toEqual(['a1', 'a2', 'b1'])
+  })
+})
+
+describe('sectionContaining', () => {
+  const sections = [
+    { title: 'First', children: [track('dup'), track('x')] },
+    { title: 'Second', children: [track('y'), track('dup'), track('z')] }
+  ]
+
+  it('falls back to the first section containing the identity', () => {
+    const scoped = sectionContaining(sections, 'dup', undefined)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+    expect(scoped?.tappedOffset).toBeUndefined()
+  })
+
+  it('pins the tapped section via the flat index', () => {
+    // Flat index 3 = second section, offset 1.
+    const scoped = sectionContaining(sections, 'dup', 3)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['y', 'dup', 'z'])
+    expect(scoped?.tappedOffset).toBe(1)
+  })
+
+  it('ignores a stale index whose child no longer matches', () => {
+    const scoped = sectionContaining(sections, 'dup', 1)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+    expect(scoped?.tappedOffset).toBeUndefined()
+  })
+
+  it('ignores an out-of-range index', () => {
+    const scoped = sectionContaining(sections, 'dup', 99)
+    expect(scoped?.tracks.map((t) => t.src)).toEqual(['dup', 'x'])
+  })
+
+  it('returns undefined for a vanished identity', () => {
+    expect(sectionContaining(sections, 'gone', 0)).toBeUndefined()
+  })
+
+  it('pins the exact copy of a within-section duplicate', () => {
+    const playlist = [
+      { children: [track('a'), track('b'), track('a'), track('c')] }
+    ]
+    const scoped = sectionContaining(playlist, 'a', 2)
+    expect(scoped?.tappedOffset).toBe(2)
+  })
+})

package/src/web/browser/sections.ts

@@ -0,0 +1,72 @@
+import type { ResolvedTrack, Section, Track } from '../../types'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
+
+/**
+ * Normalizes a resolved page to the canonical sectioned shape (ADR 0010):
+ * `sections` wins when present; plain `children` is authoring sugar for one
+ * untitled section. The output never carries `children` — there is exactly
+ * one structure downstream code hydrates, transforms, and scopes against.
+ */
+export function normalizePage(content: ResolvedTrack): ResolvedTrack {
+  const { children, sections, ...rest } = content
+  const normalized =
+    sections ?? (children !== undefined ? [{ children }] : undefined)
+  return { ...rest, sections: normalized }
+}
+
+/**
+ * The page's children concatenated in section order — the flattening that
+ * defines the contextual `__index` positions (ADR 0009/0010) and the flat
+ * views (tabs, search) of a sectioned page.
+ */
+export function flattenSections(sections: Section[] | undefined): Track[] {
+  return sections?.flatMap((section) => section.children) ?? []
+}
+
+/**
+ * The page's tracks as one flat list, normalizing first — the flat view
+ * (tabs, search) of a page in either authored shape. Mirrors the native
+ * `flattenedChildren` accessors.
+ */
+export function flattenedChildren(page: ResolvedTrack): Track[] {
+  return flattenSections(normalizePage(page).sections)
+}
+
+/**
+ * The section of the page containing the playable `trackId` (a track
+ * identity: id when non-blank, else src), or undefined when not found.
+ *
+ * `tappedIndex` — the flat page position stamped into the contextual URL —
+ * is a tie-breaker, never an identifier: when the child at that position
+ * still carries the tapped identity, it pins which section (and which copy,
+ * via `tappedOffset`) was tapped; when it doesn't (the list shifted),
+ * resolution falls back to the first section containing the identity. A
+ * stale index can therefore never select a different track — at worst a
+ * different copy of the same one.
+ */
+export function sectionContaining(
+  sections: Section[],
+  trackId: string,
+  tappedIndex: number | undefined
+): { tracks: Track[]; tappedOffset?: number } | undefined {
+  if (tappedIndex !== undefined && tappedIndex >= 0) {
+    let start = 0
+    for (const section of sections) {
+      const offset = tappedIndex - start
+      if (offset < section.children.length) {
+        const tapped = section.children[offset]
+        if (tapped && getTrackIdentity(tapped) === trackId) {
+          return { tracks: section.children, tappedOffset: offset }
+        }
+        break
+      }
+      start += section.children.length
+    }
+  }
+  for (const section of sections) {
+    if (section.children.some((track) => getTrackIdentity(track) === trackId)) {
+      return { tracks: section.children }
+    }
+  }
+  return undefined
+}

package/src/web/player/NowPlayingManager.ts

@@ -1,6 +1,7 @@
 import type { NowPlayingUpdate, NowPlayingMetadata } from '../../features'
 import type { Track } from '../../types'
 import { artworkUrl } from '../../utils/artwork'
+import { getTrackIdentity } from '../../utils/getTrackIdentity'
 
 /**
  * Manages now playing metadata overrides.
@@ -37,7 +38,7 @@ export class NowPlayingManager {
           album: update.album ?? currentTrack.album,
           artwork: artworkUrl(currentTrack.artwork),
           description: currentTrack.description,
-          mediaId: currentTrack.src ?? currentTrack.url,
+          mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
           genre: currentTrack.genre,
           duration
         }
@@ -47,7 +48,7 @@ export class NowPlayingManager {
           album: currentTrack.album,
           artwork: artworkUrl(currentTrack.artwork),
           description: currentTrack.description,
-          mediaId: currentTrack.src ?? currentTrack.url,
+          mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
           genre: currentTrack.genre,
           duration
         }
@@ -74,7 +75,7 @@ export class NowPlayingManager {
       album: this.override?.album ?? currentTrack.album,
       artwork: artworkUrl(currentTrack.artwork),
       description: currentTrack.description,
-      mediaId: currentTrack.src ?? currentTrack.url,
+      mediaId: getTrackIdentity(currentTrack) ?? currentTrack.path,
       genre: currentTrack.genre,
       duration
     }

package/src/web/util/BrowserPathHelper.test.ts

@@ -0,0 +1,52 @@
+import { describe, it, expect } from 'vitest'
+import { BrowserPathHelper } from './BrowserPathHelper'
+
+describe('BrowserPathHelper contextual URL round-trip', () => {
+  it('round-trips a src carrying its own query params', () => {
+    // A src carrying its own query string (signed CDN URL) must survive the
+    // build → extract/strip round-trip: an unescaped `&` would split the src
+    // into stray query params, truncating the trackId and polluting the
+    // parent path.
+    const src = 'https://cdn.example.com/stream.mp3?token=abc&exp=1699999999'
+    const url = BrowserPathHelper.build('/library', src)
+    expect(BrowserPathHelper.extractTrackId(url)).toBe(src)
+    expect(BrowserPathHelper.stripTrackId(url)).toBe('/library')
+  })
+
+  it('round-trips a src with equals and plus', () => {
+    const src = 'https://cdn.example.com/a+b.mp3?sig=x=y'
+    const url = BrowserPathHelper.build('/library', src)
+    expect(BrowserPathHelper.extractTrackId(url)).toBe(src)
+    expect(BrowserPathHelper.stripTrackId(url)).toBe('/library')
+  })
+
+  it('preserves unrelated parent query params when stripping', () => {
+    const src = 'https://cdn.example.com/stream.mp3?token=abc&exp=1'
+    const url = BrowserPathHelper.build('/search?q=jazz', src)
+    expect(BrowserPathHelper.extractTrackId(url)).toBe(src)
+    expect(BrowserPathHelper.stripTrackId(url)).toBe('/search?q=jazz')
+  })
+
+  it('round-trips the stamped index alongside the trackId', () => {
+    const src = 'https://cdn.example.com/stream.mp3?token=abc&exp=1'
+    const url = BrowserPathHelper.build('/library', src, 3)
+    expect(BrowserPathHelper.extractTrackId(url)).toBe(src)
+    expect(BrowserPathHelper.extractIndex(url)).toBe(3)
+    expect(BrowserPathHelper.stripTrackId(url)).toBe('/library')
+  })
+
+  it('extracts no index from an index-less contextual URL', () => {
+    const url = BrowserPathHelper.build('/library', 'song.mp3')
+    expect(BrowserPathHelper.extractIndex(url)).toBeUndefined()
+  })
+
+  it('extracts no index from a non-contextual or malformed-index URL', () => {
+    expect(BrowserPathHelper.extractIndex('/library')).toBeUndefined()
+    expect(
+      BrowserPathHelper.extractIndex('/library?__trackId=song.mp3&__index=x')
+    ).toBeUndefined()
+    expect(
+      BrowserPathHelper.extractIndex('/library?__trackId=song.mp3&__index=-1')
+    ).toBeUndefined()
+  })
+})

package/src/web/util/BrowserPathHelper.ts

@@ -6,8 +6,12 @@
  * 1. System paths (prefixed with `/__`): Root, recent, and search paths
  * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
  *
- * Contextual URL format: `{parentPath}?__trackId={trackSrc}`
- * Example: "/library/radio?__trackId=song.mp3"
+ * Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}`
+ * Example: "/library/radio?__trackId=song.mp3&__index=2"
+ *
+ * `__trackId` is the identity check; `__index` (the child's position on the
+ * page at stamp time) is only a tie-breaker between surfaces that carry the
+ * same identity — a stale index never selects a different track.
  *
  * This allows:
  * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
@@ -21,6 +25,9 @@ export const BrowserPathHelper = {
   /** Query parameter name for contextual track identifiers */
   CONTEXTUAL_TRACK_PARAM: '__trackId',
 
+  /** Query parameter name for the tapped child's page position (tie-breaker) */
+  CONTEXTUAL_INDEX_PARAM: '__index',
+
   /**
    * Create a search path for a given query
    */
@@ -43,13 +50,13 @@ export const BrowserPathHelper = {
   },
 
   /**
-   * Strips the __trackId parameter from a contextual URL to get the parent path.
-   * If the URL is not contextual, returns it unchanged.
+   * Strips the contextual parameters (__trackId and __index) from a contextual
+   * URL to get the parent path. If the URL is not contextual, returns it unchanged.
    *
    * @param url The URL to process
-   * @returns The URL without the __trackId parameter
+   * @returns The URL without the contextual parameters
    *
-   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio"
    * Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
    */
   stripTrackId(url: string): string {
@@ -62,8 +69,9 @@ export const BrowserPathHelper = {
       const isFullUrl = url.startsWith('http://') || url.startsWith('https://')
       const urlObj = new URL(url, isFullUrl ? undefined : 'http://placeholder')
 
-      // Remove the __trackId parameter
+      // Remove the contextual parameters
       urlObj.searchParams.delete(this.CONTEXTUAL_TRACK_PARAM)
+      urlObj.searchParams.delete(this.CONTEXTUAL_INDEX_PARAM)
 
       // Return the appropriate format
       if (isFullUrl) {
@@ -75,7 +83,7 @@ export const BrowserPathHelper = {
     } catch {
       // Fallback: simple string manipulation
       const paramPattern = new RegExp(
-        `[?&]${this.CONTEXTUAL_TRACK_PARAM}=[^&]*`,
+        `[?&](?:${this.CONTEXTUAL_TRACK_PARAM}|${this.CONTEXTUAL_INDEX_PARAM})=[^&]*`,
         'g'
       )
       let result = url.replace(paramPattern, '')
@@ -87,6 +95,24 @@ export const BrowserPathHelper = {
     }
   },
 
+  /**
+   * Builds a contextual URL by appending a track identifier — and optionally
+   * the tapped child's page position — to a parent path.
+   *
+   * @param parentPath The parent container path
+   * @param trackId The track identity (`id` when non-blank, else `src`)
+   * @param index The child's position on the page at stamp time (tie-breaker)
+   * @returns A contextual URL combining parent path, track ID, and index
+   *
+   * Example: build("/library", "song.mp3", 2) → "/library?__trackId=song.mp3&__index=2"
+   */
+  build(parentPath: string, trackId: string, index?: number): string {
+    const separator = parentPath.includes('?') ? '&' : '?'
+    const indexParam =
+      index === undefined ? '' : `&${this.CONTEXTUAL_INDEX_PARAM}=${index}`
+    return `${parentPath}${separator}${this.CONTEXTUAL_TRACK_PARAM}=${encodeURIComponent(trackId)}${indexParam}`
+  },
+
   /**
    * Extracts the track ID from a contextual URL.
    * Returns undefined if the URL is not contextual or doesn't contain the track ID parameter.
@@ -100,18 +126,40 @@ export const BrowserPathHelper = {
     if (!this.isContextual(path)) {
       return undefined
     }
+    return this.extractParam(path, this.CONTEXTUAL_TRACK_PARAM)
+  },
+
+  /**
+   * Extracts the stamped page index from a contextual URL, or undefined when
+   * the URL is not contextual or carries no (valid, non-negative) index.
+   *
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+   */
+  extractIndex(path: string): number | undefined {
+    if (!this.isContextual(path)) {
+      return undefined
+    }
+
+    const raw = this.extractParam(path, this.CONTEXTUAL_INDEX_PARAM)
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+      return undefined
+    }
+    return Number.parseInt(raw, 10)
+  },
 
+  /**
+   * Extracts a single query parameter, handling both full URLs and paths,
+   * with a regex fallback for input the URL parser rejects.
+   */
+  extractParam(path: string, param: string): string | undefined {
     try {
-      // Parse the URL - handle both full URLs and paths
       const isFullUrl =
         path.startsWith('http://') || path.startsWith('https://')
       const urlObj = new URL(path, isFullUrl ? undefined : 'http://placeholder')
-      return urlObj.searchParams.get(this.CONTEXTUAL_TRACK_PARAM) ?? undefined
+      return urlObj.searchParams.get(param) ?? undefined
     } catch {
       // Fallback: regex extraction
-      const match = path.match(
-        new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=([^&]*)`)
-      )
+      const match = path.match(new RegExp(`[?&]${param}=([^&]*)`))
       return match?.[1] ? decodeURIComponent(match[1]) : undefined
     }
   },

package/website/guide/android-auto.md

@@ -0,0 +1,114 @@
+---
+description: 'Put your browse tree and playback on the Android Auto car screen: the automotive app descriptor, the manifest entries the library merges in, and "Hey Google, play…" voice search.'
+---
+
+# Android Auto
+
+## Overview
+
+Android Auto shows your [browse tree](/guide/basic-usage) on the car screen and plays through the same player as your app. Two systems drive it:
+
+1. **Browse tree** — Android Auto reads your content from a `MediaBrowserService`, which mirrors your browser routes. The library ships this service.
+2. **Voice search** — "Hey Google, play…" arrives as a `MEDIA_PLAY_FROM_SEARCH` intent, which the library routes to your `search` source.
+
+Unlike CarPlay — which needs entitlements and scene delegates — Android Auto needs almost no app-side code. The library's own `AndroidManifest.xml` declares the media-browser service, the media session, the voice-search intent filter, and the foreground-service permissions, and those **merge into your app automatically**. You only have to declare your app as an automotive media app.
+
+## Setup
+
+### 1. Declare the automotive app descriptor
+
+Add this `<meta-data>` inside the `<application>` tag of your app's `AndroidManifest.xml`:
+
+```xml
+<meta-data
+    android:name="com.google.android.gms.car.application"
+    android:resource="@xml/automotive_app_desc" />
+```
+
+### 2. Add the descriptor resource
+
+Create `android/app/src/main/res/xml/automotive_app_desc.xml`:
+
+```xml
+<automotiveApp>
+    <uses name="media"/>
+</automotiveApp>
+```
+
+That's the whole setup. The `MediaBrowserService`, media session, `MEDIA_PLAY_FROM_SEARCH` intent filter, headless service for background playback, and `FOREGROUND_SERVICE` / `FOREGROUND_SERVICE_MEDIA_PLAYBACK` permissions all come from the library's merged manifest — you don't declare them yourself.
+
+## Voice search
+
+Google Assistant requests ("play some jazz", "play the radishes") arrive as a `MEDIA_PLAY_FROM_SEARCH` intent. The library normalizes it into the same structured `SearchParams` your in-app and Siri searches use and calls your `search` source — no extra manifest setup, since the library declares the intent filter.
+
+Android sends a subset of what iOS does: the query plus music focuses (genre / artist / album), always with `reference: 'unknown'`. See [Search](/guide/search) for how to resolve these requests and the cross-platform differences.
+
+## Browse display
+
+Android Auto reads a page's layout from the **parent item** that opens it — before the page resolves. So the layout is declared in two places: on the parent item (a tab, or a row on another page) and on the page itself.
+
+```ts
+// The parent item — a tab, or a row on another page. Android Auto
+// reads the layout from here, before the page resolves.
+{
+  title: 'Stations',
+  path: '/browse/stations',
+  style: { display: 'grid' }, // layout of the page this opens ('list' is the default)
+}
+
+// The page it opens — the ResolvedTrack served for '/browse/stations':
+{
+  path: '/browse/stations',
+  title: 'Stations',
+  style: { display: 'grid' },   // the page-wide declaration
+  children: [ /* the tiles */ ]
+}
+```
+
+- **`style.display` on the parent item** — `'list'` (rows) or `'grid'` (tiles). Below the root this is the only layout signal Android Auto honors, and it is only sent when you declare it — leave it off and the page renders as a list. In dev mode the library warns when an all-grid page is opened from a parent item with no declared `display`. (A section's "view all" page needs no declaration of its own: it reuses the section's `style`.)
+- **Sections** — declare `sections` on the page to group its tracks under headers; each [`Section`](/api/types/browser-nodes/#section)'s `title` renders as a header above its children, plus a "view all" link built from the section's `path` and `subtitle`.
+
+::: warning AAOS lays out the whole page from the parent item's `display`
+On AOSP-based Android Automotive units — including mainstream cars' OEM skins — the parent item's `display` is the **only** below-root layout signal honored: the whole page renders as list or grid, uniformly. Per-section `display` differences (a single-line grid above a list, say) render on CarPlay and projected Android Auto, but an AAOS unit shows the page in the single declared layout. There is no way to describe a mixed page there — pick the layout that suits its dominant section, or split the content across pages. `gridWrap: false` also has no single-line container there: the grid wraps, showing more, never less.
+:::
+
+```ts
+sections: [
+  {
+    title: 'Live now',
+    children: [
+      { title: 'Morning Show', src: '…' },
+      { title: 'Afternoon Drive', src: '…' }
+    ]
+  },
+  { title: 'Up next', children: [{ title: 'Late Night Jazz', src: '…' }] }
+]
+```
+
+## Now Playing buttons
+
+The buttons on the Now Playing screen come from the same
+[`remoteButtonLayout`](/guide/remote-controls#button-layout-android) that drives the
+notification — there's no car-specific option. Two behaviors are particular to
+the car, though:
+
+- **The head unit has the last word.** Slots are a preference. A unit with a
+  spare position may promote the first `overflow` entry onto the main row, so
+  a button you placed in overflow can still appear beside play/pause.
+- **Fewer buttons, cleaner row.** If you want just
+  `jump-back │ play/pause │ jump-forward`, leave the rest out of the layout
+  entirely — they keep working from the steering wheel and headset regardless.
+
+## Testing
+
+Test in a real car, or in Google's **Desktop Head Unit (DHU)** emulator:
+
+1. Install the **Android Auto Desktop Head Unit emulator** from the SDK Manager (_SDK Tools → Android Auto Desktop Head Unit emulator_).
+2. In the phone's **Android Auto** settings, enable Developer Mode (tap the version 10×), then **"Start head unit server"**.
+3. Connect the phone over USB and run the DHU.
+
+See Google's [Test Android Auto apps with DHU](https://developer.android.com/training/cars/testing/dhu) for the full walkthrough. Your app appears under the media apps — browse the tree, exercise voice search, and verify artwork, grid/list styles, and section headers.
+
+## Reference
+
+See the [example app](https://github.com/radio-garden/react-native-audio-browser/tree/main/apps/example-native/android) for a complete working manifest and descriptor.