react-native-audio-browser 0.2.0-next.9 → 0.2.0

package/src/types/browser.ts

@@ -56,123 +56,66 @@ export type BrowseResult = ResolvedTrack | BrowseError
 
 export type BrowserSourceCallback = (
   param: BrowserSourceCallbackParam
-) => BrowseResult | Promise<BrowseResult>
+) => Promise<BrowseResult>
 
 /**
- * Search mode — the *container vertical*: what KIND of result the user asked
- * for. Orthogonal to the filter props (`genre`/`artist`/`album`/`title`/
- * `playlist`), which say *which* item. `mode` is optional: when absent, the
- * request is unstructured (text-search `query`) or unclassified.
+ * Search mode types for structured voice search.
  *
- * - `any`: play anything sensible — "play something" / smart shuffle (query
- *   empty). Android also maps its generic "play music" focus here, since it
- *   can't isolate the music vertical the way iOS can.
- * - `song`: an individual track
- * - `playlist`: a named playlist / mix
- * - `station`: a live radio station / channel
- * - `podcast`: a podcast (series, episode, or station)
- * - `audiobook`: an audiobook
- * - `news`: news content
- * - `music`: the music vertical, as opposed to talk/podcasts/audiobooks
- *   ("play music" on iOS, via the music media type)
- * - `music-video` / `movie` / `tv-show` / `tv-show-episode`: video kinds
- *   (an audio app cannot play these; surfaced so consumers may special-case —
- *   ignoring them degrades to an unstructured search)
- *
- * NOTE: there is intentionally no `genre`/`artist`/`album` member — those are
- * filters, not result shapes. Read them from `SearchParams.genre`/`.artist`/
- * `.album` directly.
+ * - `any`: Play any content - smart shuffle or last playlist (query will be empty string)
+ * - `genre`: Search by genre
+ * - `artist`: Search by artist
+ * - `album`: Search by album
+ * - `song`: Search by song/track title
+ * - `playlist`: Search by playlist name
  *
  * @see BrowserConfiguration.search
  * @see SearchParams
  */
 export type SearchMode =
   | 'any'
+  | 'genre'
+  | 'artist'
+  | 'album'
   | 'song'
   | 'playlist'
-  | 'station'
-  | 'podcast'
-  | 'audiobook'
-  | 'news'
-  | 'music'
-  | 'music-video'
-  | 'movie'
-  | 'tv-show'
-  | 'tv-show-episode'
-
-/**
- * The media-reference axis from a voice intent.
- *
- * - `my`: the user's own collection ("play my favorites") — routed to the
- *   `search` source so the consumer resolves it against their library.
- * - `unknown`: no reference (the default; Android always emits this).
- *
- * NOTE: "currently playing" ("play this") is resolved natively (resume) and
- * never reaches the consumer, so it is not a value here.
- */
-export type MediaReference = 'my' | 'unknown'
 
 /**
- * Structured search parameters normalized from a voice/search intent — one
- * cross-platform shape (iOS SiriKit + Android MediaSession). `mode` is the
- * container vertical; the remaining fields are filters. Example mappings:
- * - "play something"              → mode='any', query="" (smart shuffle)
- * - "play music"                  → mode='music' (iOS) / 'any' (Android), query=""
- * - "play jazz"                   → genre="jazz", query="jazz" (mode undefined)
- * - "play the radishes"           → artist="the radishes", query="the radishes"
- * - "play greens by the radishes" → album="greens", artist="the radishes"
- * - "play sweet pea"              → mode='song', title="sweet pea", query="sweet pea"
- * - "play my favorites"           → reference='my', query=""
- * - "play a jazz podcast"         → mode='podcast', genre="jazz"
+ * Structured search parameters from voice commands.
+ *
+ * Voice commands are parsed by Android into structured parameters:
+ * - "play something" → mode=null, query="something"
+ * - "play music" → mode='any', query=""
+ * - "play jazz" → mode='genre', genre="jazz", query="jazz"
+ * - "play michael jackson" → mode='artist', artist="michael jackson", query="michael jackson"
+ * - "play thriller by michael jackson" → mode='album', album="thriller", artist="michael jackson"
+ * - "play billie jean" → mode='song', title="billie jean", query="billie jean"
  */
 export interface SearchParams {
-  /** Container vertical, or undefined for an unstructured / unclassified search. */
+  /** The search mode indicating what type of search is being performed, or null for unstructured search */
   mode?: SearchMode
   /**
    * The original search query string (always present, but may be empty string "").
-   * With mode='any' and empty query, return any content the user would like
+   * When mode='any' with empty string query, return any content you think the user would like
    * (e.g., recently played, favorites, or smart shuffle).
    */
   query: string
-  /** Genre filter, when the intent named one. */
+  /** Genre name for genre-specific search */
   genre?: string
-  /** Artist filter (artist / album / song intents). */
+  /** Artist name for artist/album/song search */
   artist?: string
-  /** Album filter. */
+  /** Album name for album-specific search */
   album?: string
-  /** Track title, for a song intent. */
+  /** Song title for song-specific search */
   title?: string
-  /** Playlist name, for a playlist intent. */
+  /** Playlist name for playlist-specific search */
   playlist?: string
-  /**
-   * Media-reference axis. `'my'` = resolve against the user's own collection
-   * ("play my favorites"); `'unknown'` = no reference (the default). Android
-   * always emits `'unknown'`.
-   *
-   * Resolve it however your collection lives: a `SearchSourceCallback` can read
-   * `params.reference` and return the matching tracks directly, or — when using
-   * an HTTP `TransformableRequestConfig` — branch in `transform` on
-   * `request.query.reference === 'my'` to rewrite the request toward a
-   * favorites endpoint (e.g. injecting locally-stored identifiers into the body).
-   */
-  reference: MediaReference
 }
 
 export type SearchSourceCallback = (params: SearchParams) => Promise<Track[]>
-// Sync and async transforms are SEPARATE fields (`transform` / `transformSync`),
-// never a `T | Promise<T>` union. A union lowers to a Nitro `variant<Struct,
-// Promise<Struct>>`, and an all-optional struct's `canConvert` also accepts a
-// Promise — so the async case is silently misread as an empty config. Two
-// single-typed fields keep both paths unambiguous, and the sync field allocates
-// no Promise. When both are set they run as a pipeline: async first, then sync.
 export type RequestConfigTransformer = (
   request: RequestConfig,
   routeParams?: Record<string, string>
 ) => Promise<RequestConfig>
-export type RequestConfigTransformerSync = (
-  request: RequestConfig,
-  routeParams?: Record<string, string>
-) => RequestConfig
 
 export type HttpMethod =
   | 'GET'
@@ -272,13 +215,9 @@ export interface MediaTransformParams {
  * }
  * ```
  */
-// Split sync/async — see RequestConfigTransformer. Set `transform` and/or `transformSync`.
 export type MediaRequestConfigTransformer = (
   params: MediaTransformParams
 ) => Promise<RequestConfig>
-export type MediaRequestConfigTransformerSync = (
-  params: MediaTransformParams
-) => RequestConfig
 
 /**
  * Request configuration that supports async transformation.
@@ -288,11 +227,6 @@ export type MediaRequestConfigTransformerSync = (
  * before the request is made. This is useful for adding dynamic headers,
  * signing URLs, or other request-time modifications.
  *
- * Note: when a layer provides a transform, the layer's other static fields
- * are NOT merged — the transform receives the merged config from the layers
- * below it, and its return value replaces that config entirely. Spread the
- * incoming request (`{ ...request, ... }`) to keep its fields.
- *
  * @example
  * ```typescript
  * const config: TransformableRequestConfig = {
@@ -308,46 +242,9 @@ export type MediaRequestConfigTransformerSync = (
  * ```
  */
 export interface TransformableRequestConfig extends RequestConfig {
-  /** Async per-request transform. When both are set, runs BEFORE `transformSync`. */
   transform?: RequestConfigTransformer
-  /** Sync per-request transform (no Promise allocation). When both are set, runs AFTER `transform`. */
-  transformSync?: RequestConfigTransformerSync
 }
 
-/**
- * Lazily builds the config for a `request` or `browse` layer. Reach for it when
- * the config depends on a value that changes now and then — a base URL, a
- * locale — but not on every request.
- *
- * How it differs from a `transform`: **a resolver runs once and its result is
- * cached**, then reused for every browse/search/media/artwork request — whereas a
- * `transform` runs on *every* request. The resolver re-runs only when you call
- * `invalidateAllContent()`, so call that after (say) an environment or locale
- * switch to pick up the new value.
- *
- * Return the config directly — no `async`/Promise needed in the common case — or
- * a `Promise` when you must await (e.g. fetching a token). The cached config
- * flows through the normal layering, so its `query` merges additively and its
- * `baseUrl` overrides, exactly like a static config; it may also include a
- * `transform` if you additionally need genuine per-request logic.
- *
- * @example
- * ```typescript
- * configureBrowser({
- *   // Read once and cached; re-read after the next invalidateAllContent().
- *   request: () => ({ baseUrl: currentBaseUrl() }),
- *   // Browse-only locale param, merged into every browse request's query.
- *   browse: () => ({ query: { hl: currentLocale() } }),
- * })
- *
- * // Async resolver (e.g. awaiting a token) — still runs once, then cached:
- * request: async () => ({ headers: { authorization: await freshToken() } })
- * ```
- */
-export type RequestConfigResolver = () =>
-  | TransformableRequestConfig
-  | Promise<TransformableRequestConfig>
-
 /**
  * Configuration for artwork image requests
  *
@@ -475,13 +372,13 @@ export interface MediaRequestConfig extends TransformableRequestConfig {
    *
    * Called for each track to generate the final request configuration.
    * Receives the full Track object, allowing URL generation based on
-   * track metadata (id, artist, album, src, etc.).
+   * track metadata (artist, album, src, etc.).
    *
    * The returned config is merged with base configs, then passed to
    * `transform` if provided.
    *
    * @param track - The track being requested
-   * @returns Request configuration for this specific track (sync or async)
+   * @returns Request configuration for this specific track
    *
    * @example
    * ```typescript
@@ -491,10 +388,7 @@ export interface MediaRequestConfig extends TransformableRequestConfig {
    * })
    * ```
    */
-  /** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
   resolve?: (track: Track) => Promise<RequestConfig>
-  /** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
-  resolveSync?: (track: Track) => RequestConfig
 }
 
 export interface ArtworkRequestConfig extends RequestConfig {
@@ -502,7 +396,7 @@ export interface ArtworkRequestConfig extends RequestConfig {
    * Per-track request resolution callback.
    *
    * Called for each track to generate the request configuration based on
-   * track metadata (id, artist, album, src, etc.).
+   * track metadata (artist, album, src, etc.).
    *
    * The returned config is merged with base configs, then passed to
    * `transform` if provided.
@@ -520,10 +414,7 @@ export interface ArtworkRequestConfig extends RequestConfig {
    * }
    * ```
    */
-  /** Async per-track resolution. When both are set, runs (merged) BEFORE `resolveSync`. */
   resolve?: (track: Track) => Promise<RequestConfig>
-  /** Sync per-track resolution (no Promise allocation). When both are set, runs (merged) AFTER `resolve`. */
-  resolveSync?: (track: Track) => RequestConfig
 
   /**
    * Final transformation callback for media/artwork requests.
@@ -554,10 +445,7 @@ export interface ArtworkRequestConfig extends RequestConfig {
    * }
    * ```
    */
-  /** Async final transform. When both are set, runs BEFORE `transformSync`. */
   transform?: MediaRequestConfigTransformer
-  /** Sync final transform (no Promise allocation). When both are set, runs AFTER `transform`. */
-  transformSync?: MediaRequestConfigTransformerSync
 
   /**
    * Query parameter names for automatic context injection from CarPlay/Android Auto.
@@ -585,19 +473,6 @@ export interface ArtworkRequestConfig extends RequestConfig {
   imageQueryParams?: ImageQueryParams
 }
 
-/**
- * Source for a browse container's contents.
- *
- * **Response shape (HTTP / `TransformableRequestConfig`):** the endpoint must
- * return a single **page object** — a {@link ResolvedTrack}
- * (`{ title, url?, children: Track[] }`). The `children` array holds the rows
- * shown for the container; each child is a playable leaf (`src`) or a navigable
- * sub-container (`url`). A callback / static `ResolvedTrack` returns the same
- * page object directly.
- *
- * {@link SearchSource} and {@link TabsSource} HTTP endpoints return this same
- * page shape; only the meaning of `children` differs (results / tabs).
- */
 export type BrowserSource =
   | ResolvedTrack
   | BrowserSourceCallback
@@ -628,15 +503,12 @@ export type RouteConfig = {
   artwork?: ArtworkRequestConfig
 }
 
-export type TabsSourceCallback = () => Track[] | Promise<Track[]>
+export type TabsSourceCallback = () => Promise<Track[]>
 /**
  * Tab source configuration for navigation tabs.
  *
- * When using API configuration (TransformableRequestConfig), the request path
- * defaults to '/' and the endpoint must return a page object
- * `{ title?, children: Track[] }` whose `children` are the tabs — the same
- * shape a browse endpoint returns. Callback/static sources provide `Track[]`
- * directly.
+ * When using API configuration (TransformableRequestConfig), the request path defaults to '/'
+ * and should return an array of Track objects with urls representing the tabs.
  */
 export type TabsSource =
   | Track[]
@@ -646,103 +518,30 @@ export type TabsSource =
 /**
  * Search source configuration for handling search requests.
  *
- * **Response shape (HTTP / `TransformableRequestConfig`):** the endpoint must
- * return a page object — `{ title?, children: Track[] }` — whose `children`
- * are the result rows, the same shape a browse endpoint returns. (The web
- * implementation additionally accepts a bare `Track[]` for back-compat;
- * iOS/Android do not.) Callback sources return `Track[]` directly.
- *
  * @see BrowserConfiguration.search
  */
 export type SearchSource = SearchSourceCallback | TransformableRequestConfig
 
-/**
- * How ids passed to `setFavorites` are matched against a
- * track's `src` to hydrate its `favorited` flag.
- *
- * - `'exact'`: the id must equal `src`.
- * - `'partial'`: the id matches if it appears as a complete path segment within
- *   `src` (delimited by `/`, `?`, `#`, or the string boundaries). Useful when
- *   favorites are stored as a stable identifier that is embedded in — but not
- *   equal to — the playable `src` URL.
- *
- * @example
- * ```text
- * setFavorites(['abc123'])  +  track.src = '/stream/jazz-fm/abc123'
- *
- *   'exact'    'abc123' === '/stream/jazz-fm/abc123'   → not favorited
- *   'partial'  'abc123' is the last segment of the src → favorited
- *
- * setFavorites(['https://cdn.example.com/jazz-fm/abc123.mp3'])
- *
- *   'exact'    id === src                              → favorited
- *   'partial'  id is a full segment of src             → favorited
- * ```
- */
-export type FavoritesMatchMode = 'exact' | 'partial'
-
-/**
- * Object form of the `favorite` capability — enables favoriting with an explicit
- * {@link FavoritesMatchMode}. (A bare `true` is shorthand for `{ match: 'exact' }`.)
- */
-export interface FavoriteConfig {
-  match: FavoritesMatchMode
-}
-
 export type BrowserConfiguration = {
   /**
-   * Initial navigation path. Setting this triggers initial navigation to the
-   * specified path. When unset, the first tab's URL is used; when there are
-   * no tabs either, `/`.
+   * Initial navigation path. Setting this triggers initial navigation to the specified path.
    */
   path?: string | undefined
 
   // ─── Request Defaults (applied to all requests) ────────────────────────────
 
   /**
-   * Shared request settings applied to every HTTP request (browse, search,
-   * media, artwork). Layered before the per-kind config and (for browse) the
-   * route — so request → `<kind>` → route. Specific configs override these
-   * defaults.
-   *
-   * Either a static {@link TransformableRequestConfig} (its optional `transform`
-   * runs per request), or a {@link RequestConfigResolver} thunk resolved once per
-   * content generation and re-resolved on `invalidateAllContent()`. Reach for the
-   * resolver when a value changes rarely (a base URL, an auth host) so it is read
-   * once per generation and merged natively — rather than recomputed on every
-   * browse/search/media/artwork request via a `transform`.
+   * Shared request settings applied to all HTTP requests (browse, search, media, artwork).
+   * Specific configs override these defaults.
    */
-  request?: TransformableRequestConfig | RequestConfigResolver
+  request?: TransformableRequestConfig
 
-  // ─── Per-kind request configuration ─────────────────────────────────────────
+  // ─── Content Configuration ─────────────────────────────────────────────────
 
-  /**
-   * Request shaping applied to every browse request (all routes, including the
-   * implicit default), layered between `request` and the matched route:
-   * `request` → `browse` → route. This is the browse-kind analogue of `media`
-   * and `artwork` — the place for browse-only concerns (e.g. a content-type
-   * marker query, or a locale param) that should not leak onto media/artwork.
-   *
-   * A browse path with no matching `routes` entry is fetched using
-   * `request` + `browse` applied to the path, so this also defines the default
-   * browse behaviour. Register a `routes['*']` entry only to override that
-   * default with a callback / static / bespoke config.
-   *
-   * Like `request`, this may be a static {@link TransformableRequestConfig} or a
-   * {@link RequestConfigResolver} thunk (resolved once per content generation) —
-   * e.g. a locale query param that only changes when `invalidateAllContent()` is
-   * called. A resolver's `query` is merged additively into each browse request's
-   * query, exactly as a static `query` would be.
-   */
-  browse?: TransformableRequestConfig | RequestConfigResolver
+  /** Default browse source when no matching route is found. */
+  browse?: BrowserSource
 
-  /**
-   * Media/audio stream request configuration.
-   *
-   * Unlike `request`/`browse`, this does not accept a resolver thunk. For
-   * values that change at runtime, use the shared `request` resolver (it
-   * applies to media requests too), a per-track `resolve`, or a `transform`.
-   */
+  /** Media/audio stream request configuration. */
   media?: MediaRequestConfig
 
   /**
@@ -753,9 +552,8 @@ export type BrowserConfiguration = {
    * Artwork URLs are transformed when tracks are processed (before being passed to media controllers
    * like Android Auto). This is different from media requests which are transformed at playback time.
    *
-   * Headers ARE applied to artwork requests: the library fetches CarPlay and
-   * Android Auto images in-process, and in-app consumers receive them via
-   * `artworkSource` (which carries the headers for React Native's `<Image>`).
+   * Note: Since media controllers load images directly from URLs, HTTP headers cannot be applied
+   * to artwork requests. Use query parameters for authentication tokens if your CDN supports it.
    *
    * @example
    * ```typescript
@@ -777,82 +575,41 @@ export type BrowserConfiguration = {
    */
   artwork?: ArtworkRequestConfig
 
-  /**
-   * Artwork configuration for the NOW-PLAYING surface only (lock screen / CarPlay /
-   * Android Auto now-playing) — distinct from `artwork`, which configures browse-list
-   * thumbnails. When set, the now-playing artwork is resolved from THIS config instead of
-   * `artwork`; browse lists never read it, so they're unaffected. When unset, now-playing
-   * falls back to `artwork` / the track's own `artwork`.
-   *
-   * Being a full `RequestConfig`, it supports `path`, `query`, and `headers`. The token
-   * `{id}` in any of those values is replaced with the track's `id` during resolution, and
-   * the result flows through the shared `request` layer (so a relative path gets `baseUrl`
-   * prepended). For logic that can't be expressed as a template, use `resolve(track)`.
-   *
-   * The `{id}` templating is specific to `nowPlayingArtwork` — static values
-   * in other configs are not templated. Not implemented by the web
-   * implementation.
-   *
-   * @example
-   * // 302-redirect endpoint keyed by the track id:
-   * nowPlayingArtwork: { path: '/artwork/{id}' }
-   */
-  nowPlayingArtwork?: ArtworkRequestConfig
-
   // ─── Navigation ────────────────────────────────────────────────────────────
 
   /**
    * Configuration for search functionality.
    * Enables search capabilities in the media browser, typically accessed through voice commands or search UI.
    *
-   * See the [Search guide](https://audiobrowser.dev/guide/search) for a walkthrough of
-   * modes, filters, the `reference` axis, and mixed audio/video.
-   *
    * Optional - if not provided, search functionality will be disabled.
    * Required for Android Auto/CarPlay voice search integration with support for structured voice commands.
    *
    * Search receives structured parameters from voice commands like:
-   * - "play something"          → mode='any', query="" (smart shuffle)
-   * - "play music"              → mode='music' (iOS) / 'any' (Android), query=""
-   * - "play jazz"               → genre="jazz", query="jazz" (genre is a filter, no mode)
-   * - "play the radishes"       → artist="the radishes", query="the radishes"
-   * - "play sweet pea"          → mode='song', title="sweet pea", query="sweet pea"
-   * - "play my favorites"       → reference='my', query=""
+   * - "play music" → mode='any', query=""
+   * - "play jazz" → mode='genre', genre="jazz", query="jazz"
+   * - "play michael jackson" → mode='artist', artist="michael jackson", query="michael jackson"
+   * - "play thriller by michael jackson" → mode='album', album="thriller", artist="michael jackson"
+   * - "play billie jean" → mode='song', title="billie jean", query="billie jean"
    *
    * Can be either:
-   * - SearchSourceCallback: Receives SearchParams with query + reference, plus the
-   *   optional container-vertical `mode` and the genre/artist/album/title/playlist filters
-   * - TransformableRequestConfig: API endpoint where search parameters are automatically added to request.query:
+   * - SearchSourceCallback: Receives SearchParams with query, and optional mode/artist/album/genre/title/playlist fields
+   * - TransformableRequestConfig: API endpoint where all search parameters are automatically added to request.query:
    *   - q: search query string (always present)
-   *   - mode: container vertical (any/song/playlist/station/podcast/audiobook/news/music/
-   *     music-video/movie/tv-show/tv-show-episode) - omitted for unstructured search
-   *   - reference: 'my' when the user asked for their own collection ("play my
-   *     favorites"); omitted otherwise
-   *   - artist, album, genre, title, playlist: filters, included when present
-   *
-   * These query-param keys are fixed (not configurable). If your endpoint
-   * expects different names, rename them in `transform` — it receives the params
-   * already on `request.query`, e.g. `query: { search: request.query?.q }`.
-   *
-   * Response shape: the endpoint must return a page object
-   * `{ children: Track[] }` — see {@link SearchSource}.
+   *   - mode: search mode (any/genre/artist/album/song/playlist) - omitted for unstructured search
+   *   - artist, album, genre, title, playlist: included when present
    *
    * @example
    * ```typescript
    * // Callback approach - direct access to structured parameters
    * search: async (params) => {
-   *   // "play my favorites" → resolve against the user's own collection
-   *   if (params.reference === 'my') return await getFavorites();
-   *   // Filters are read directly from their props (not derived from `mode`)
-   *   if (params.album && params.artist) {
+   *   // Use structured fields for precise searches
+   *   if (params.mode === 'artist' && params.artist) {
+   *     return await db.query('SELECT * FROM tracks WHERE artist = ?', [params.artist]);
+   *   }
+   *   if (params.mode === 'album' && params.album && params.artist) {
    *     return await db.query('SELECT * FROM tracks WHERE album = ? AND artist = ?',
    *       [params.album, params.artist]);
    *   }
-   *   if (params.artist) {
-   *     return await db.query('SELECT * FROM tracks WHERE artist = ?', [params.artist]);
-   *   }
-   *   // `mode` is the container vertical — narrow by it when present
-   *   if (params.mode === 'podcast') return await searchPodcasts(params.query);
    *   // Fall back to full-text search
    *   return await searchByQuery(params.query);
    * }
@@ -860,11 +617,11 @@ export type BrowserConfiguration = {
    * // API configuration - parameters automatically added to query string
    * search: {
    *   baseUrl: 'https://api.example.com/search',
-   *   // GET /search?q=greens&mode=album&album=greens&artist=the+radishes&limit=20
+   *   // GET /search?q=thriller&mode=album&album=thriller&artist=michael+jackson&limit=20
    *   transform(request) {
    *     return {
    *       ...request,
-   *       query: { ...request.query, limit: '20' }
+   *       query: { ...request.query, limit: 20 }
    *     };
    *   }
    * }
@@ -884,47 +641,20 @@ export type BrowserConfiguration = {
   tabs?: TabsSource
 
   /**
-   * Route-specific configurations. Maps URL path patterns to browse sources.
-   *
-   * ## Matching
-   *
-   * Patterns match on **exact segment count** — `/artists` does NOT match
-   * `/artists/123`. Segments may be:
-   * - a constant: `/favorites`
-   * - a parameter: `/albums/{id}` — captured into `routeParams.id` and passed
-   *   to callbacks and transforms
-   * - a single-segment wildcard: `*`
-   * - a tail wildcard: `/files/**` — matches any depth; the remainder is
-   *   captured into `routeParams.tail`
-   *
-   * When several patterns match, the most specific wins
-   * (constants > parameters > wildcards > tail wildcard).
-   *
-   * ## Defaults and reserved keys
-   *
-   * A path matching no route is fetched over HTTP via the `request` →
-   * `browse` layers with the path applied — most APIs only need explicit
-   * routes for exceptions. The special key `'*'` overrides that default with
-   * its own source. Keys starting with `__` are reserved for internal use.
+   * Route-specific configurations. Maps URL paths to browse sources.
+   * Routes match by prefix, most specific (most slashes) wins.
    *
-   * Note: a static `path` on a route's request config does not rewrite the
-   * request path (the navigated path is used); remap paths in a `transform`,
-   * which receives `routeParams` as its second argument.
-   *
-   * Values can be a `BrowserSource` (callback, request config, or static page
-   * object) or a `RouteConfig` with per-route `media`/`artwork` overrides.
+   * Can be a simple `BrowserSource` or extended `RouteConfig` with media/artwork overrides.
    *
    * @example
    * ```typescript
    * routes: {
-   *   '/favorites': async () => getFavoritesPage(),
-   *   '/albums/{id}': async ({ routeParams }) => fetchAlbumPage(routeParams?.id),
+   *   '/favorites': async () => getFavorites(),
+   *   '/artists': { baseUrl: 'https://music-api.com' },
    *   '/premium': {
-   *     browse: { baseUrl: 'https://premium-api.example.com' },
-   *     artwork: { baseUrl: 'https://premium-images.example.com' }
-   *   },
-   *   // Custom default for anything no other route matches:
-   *   '*': { baseUrl: 'https://api.example.com' }
+   *     browse: { baseUrl: 'https://premium-api.com' },
+   *     artwork: { baseUrl: 'https://premium-images.cdn.com' }
+   *   }
    * }
    * ```
    */
@@ -963,42 +693,34 @@ export type BrowserConfiguration = {
    */
   androidControllerOfflineError?: boolean
 
+  // ─── CarPlay Options ──────────────────────────────────────────────────────────
+
   /**
-   * Title shown (as the list's centered empty state) on CarPlay screens whose
-   * content is still loading — browse destinations while they resolve, and the
-   * startup screen while tabs load. Supply your app's localized "Loading…"
-   * string. On iOS 18.4+ the system loading spinner is shown instead.
+   * Enable the "Up Next" button on the CarPlay Now Playing screen.
    *
-   * When unset, loading screens are left blank (apart from the spinner on
-   * iOS 18.4+) rather than showing un-localized copy.
+   * When enabled, tapping "Up Next" shows the current playback queue,
+   * allowing users to see upcoming tracks and jump to a specific position.
    *
-   * @example
-   * ```typescript
-   * carPlayLoadingTitle: t('loading')
-   * ```
+   * The button is automatically hidden when the queue has only one track.
    *
+   * @default true
    * @platform ios
    */
-  carPlayLoadingTitle?: string
+  carPlayUpNextButton?: boolean
 
   /**
-   * Called when the album line on the CarPlay Now Playing screen is tapped
-   * and the active track has no {@link Track.albumUrl}. Return a browse path
-   * to navigate the CarPlay browse stack there, or `undefined` if the tap was
-   * handled (or should do nothing).
-   *
-   * The album line is tappable whenever the active track has an `albumUrl`
-   * or this callback is configured.
+   * Configure up to 5 buttons on the CarPlay Now Playing screen. These buttons
+   * are arranged using the array order from left to right.
    *
    * @example
    * ```typescript
-   * resolveAlbumUrl: (track) =>
-   *   track.album ? `/album/${slugify(track.album)}` : undefined
+   * carPlayNowPlayingButtons: ['repeat']
    * ```
    *
+   * @default []
    * @platform ios
    */
-  resolveAlbumUrl?: ResolveAlbumUrlCallback
+  carPlayNowPlayingButtons?: CarPlayNowPlayingButton[]
 
   /**
    * Callback to customize error messages for navigation errors.
@@ -1008,15 +730,12 @@ export type BrowserConfiguration = {
    *
    * @example
    * ```typescript
-   * formatNavigationError: ({ error, defaultFormatted }) => {
-   *   if (error.code === 'http-error') {
-   *     return {
-   *       title: t('error.serverError'),
-   *       message: t('error.httpMessage', { status: error.statusCode })
-   *     }
-   *   }
-   *   return defaultFormatted
-   * }
+   * formatNavigationError: (error) => ({
+   *   title: t(`error.${error.code}`),
+   *   message: error.code === 'http-error'
+   *     ? t('error.httpMessage', { status: error.statusCode })
+   *     : error.message
+   * })
    * ```
    */
   formatNavigationError?: FormatNavigationErrorCallback
@@ -1062,12 +781,11 @@ export type FormattedNavigationError = {
    */
   title: string
   /**
-   * Optional second line — the body in the error action sheet, the subtitle in
-   * the browse error/empty view. Omit it to show a title only.
+   * Message body shown below the title in the error action sheet.
    *
-   * Default value: `error.message` (omitted when that is empty).
+   * Default value: `error.message`
    */
-  message?: string
+  message: string
 }
 
 /**
@@ -1108,9 +826,3 @@ export type FormatNavigationErrorParams = {
 export type FormatNavigationErrorCallback = (
   params: FormatNavigationErrorParams
 ) => FormattedNavigationError | undefined
-
-/**
- * Maps the tapped active track to a browse path for the CarPlay album line,
- * or `undefined` to do nothing. See `resolveAlbumUrl`.
- */
-export type ResolveAlbumUrlCallback = (track: Track) => string | undefined