react-native-audio-browser 0.2.0-next.10 → 0.2.0-next.12

package/src/types/browser-nodes.ts

@@ -1,6 +1,119 @@
 import type { CarPlaySiriListButtonPosition, HttpMethod } from './browser'
 
-export type TrackStyle = 'list' | 'grid'
+/**
+ * How a holder's *children* lay out — CSS's inner display type, honored
+ * literally (`display: 'grid'` in CSS describes the children, not the
+ * element).
+ *
+ * - `'list'` (default) — full-width rows on every surface.
+ * - `'grid'` — artwork tiles; wraps unless {@link SectionStyle.gridWrap}
+ *   is `false`. Tiles presume artwork: an artwork-less child renders a
+ *   placeholder tile plus its title. On CarPlay a *wrapping* grid needs
+ *   iOS 26+ and renders a list before that; a single-line grid renders
+ *   on every OS.
+ */
+export type StyleDisplay = 'list' | 'grid'
+
+/**
+ * How a track's artwork is rendered.
+ *
+ * - `'original'` (default) — drawn as-is.
+ * - `'stencil'` — treated as a monochrome glyph and tinted to the
+ *   surface's appearance (black in light mode, white in dark). For
+ *   monochrome logos and icons; full-color artwork should stay
+ *   `'original'`.
+ */
+export type ArtworkRendering = 'original' | 'stencil'
+
+/**
+ * The style declaration block a {@link Track} may carry: *inherited item
+ * properties* (resolved `track ?? section ?? page ?? default`, per
+ * property — they travel with the track) plus the *positional*
+ * {@link TrackStyle.display} (each holder's own children; never
+ * inherited).
+ *
+ * Rules governing every property:
+ *
+ * - **Declarations are aspirational.** Each surface renders the
+ *   properties it understands and ignores the rest — inert, never an
+ *   error.
+ * - **Presentation only.** No style property affects queue scope,
+ *   playback, or navigation: rendering may truncate what is visible, it
+ *   never changes what plays. (This is why {@link Track.disabled} is NOT
+ *   here — it carries behavior, so it lives on Track as a content fact.)
+ * - **The inheritance boundary**: a handle's block styles the handle; a
+ *   page's block is inherited by the page's descendants; nothing
+ *   inherits across resolution.
+ */
+export interface TrackStyle {
+  /**
+   * How this entity's *children* lay out. The meaning is uniform at
+   * every position; only the children differ:
+   *
+   * - On a {@link Section}: the section's children.
+   * - On a resolved page ({@link ResolvedTrack.style}): the declaration
+   *   for the whole page — a section overrides it for its own children.
+   * - On a browsable {@link Track} (the handle): the *advertised*
+   *   layout of the page it opens. Android Auto decides a page's
+   *   layout before resolving it, so it is the one reader that acts
+   *   on the handle's declaration. Declared or it doesn't exist: no
+   *   value → nothing advertised. The resolved page is the truth.
+   * - On a track rendered *playable* (`src` wins the rendering): inert —
+   *   playables open no page.
+   *
+   * Never *item*-inherited — each holder speaks only for its own
+   * children. Between containers it resolves by scope override, not
+   * inheritance: the page declares for its whole scope, a section
+   * overrides for its own children.
+   *
+   * @default 'list'
+   *
+   * @see https://developer.android.com/training/cars/media/create-media-browser/content-styles
+   */
+  display?: StyleDisplay
+
+  /**
+   * Inherited (`track ?? section ?? page`): how this item's artwork is
+   * rendered — `'stencil'` tints a monochrome glyph to the surface's
+   * light/dark appearance.
+   *
+   * @default 'original'
+   *
+   * @platform carplay
+   */
+  artworkRendering?: ArtworkRendering
+}
+
+/**
+ * A {@link Section}'s (or resolved page's) style declaration block: the
+ * *container* properties below, plus — via `extends` — a section-wide
+ * value for every inherited {@link TrackStyle} item property (and the
+ * section's own positional `display`).
+ *
+ * Container properties resolve by scope override, not inheritance: the
+ * page declares for its whole scope, a section overrides for its own
+ * children (`section ?? page ?? default`) — they never flow to items.
+ */
+export interface SectionStyle extends TrackStyle {
+  /**
+   * Whether grid tiles wrap to multiple lines. `false` renders exactly
+   * one line — the teaser shelf: a preview of a larger collection,
+   * typically paired with {@link Section.path} as the "view all" target.
+   *
+   * Rendered by CarPlay (a single line of tiles). Android Auto has no
+   * single-line tile container — its grid wraps, showing more, never
+   * less. Phone UIs typically honor `false` as a horizontal scroller.
+   *
+   * Inert unless {@link TrackStyle.display} is `'grid'`.
+   *
+   * @default true
+   *
+   * @platform carplay
+   *
+   * @see https://developer.apple.com/documentation/carplay/cplistimagerowitem
+   */
+  gridWrap?: boolean
+}
 
 /**
  * Image source for React Native's `<Image>` component.
@@ -37,12 +150,6 @@ export interface TrackRequest {
   query?: Record<string, string>
 }
 
-// export interface BrowserSection {
-//   title: string
-//   style?: BrowserItemStyle
-//   children: Track
-// }
-
 /**
  * Artwork URLs for a track that ships a different image per appearance.
  *
@@ -67,66 +174,72 @@ export interface ArtworkVariants {
 /** A single artwork URL, or one per appearance. */
 export type TrackArtwork = string | ArtworkVariants
 
-export interface ImageRowItem {
+/**
+ * A titled, styled group of Tracks within a resolved page — the unit of
+ * queue scope. Tapping a playable child queues the section it sits in,
+ * identically on every platform and screen width: rendering may truncate
+ * what is visible, it never changes what plays.
+ */
+export interface Section {
+  /** Header text. Absent = headerless group. */
+  title?: string
   /**
-   * Opaque, stable identifier for this item's track. Round-tripped like
-   * `Track.id` when the thumbnail is played (see `src`).
+   * Secondary line for the section's navigation surface — e.g. the label
+   * of the "view all" link a tile section gets on Android Auto.
    */
-  id?: string
-  /** Navigation path. Tapping this thumbnail navigates to this URL. */
-  url?: string
+  subtitle?: string
   /**
-   * Direct audio source. When present, tapping this thumbnail plays it
-   * immediately (same selection path as a playable list row) instead of
-   * navigating. Takes precedence over `url`.
+   * Presentation, separated from content. Each surface renders the
+   * declared layout's nearest supported form; on CarPlay
+   * a wrapping grid requires iOS 26+ and renders a list before that,
+   * since CarPlay's only earlier tile container truncates at a width the
+   * system doesn't report. Use the artwork `resolve` hook to supply
+   * fallback art for tile layouts.
    */
-  src?: string
-  /** Artwork URL for the thumbnail image. */
-  artwork?: string
-  /** Output only — populated by the artwork transform pipeline. */
-  readonly artworkSource?: ImageSource
-  /** Title of this item. Shown as the thumbnail caption; used for identification and accessibility. */
-  title: string
-  /** Now-playing secondary line when played via `src` (mirrors `Track.artist`). */
-  artist?: string
-  /** Now-playing album line when played via `src` (mirrors `Track.album`). */
-  album?: string
-  /** Navigation target of the album line when played via `src` (mirrors `Track.albumUrl`). */
-  albumUrl?: string
-  /** Live stream indicator when played via `src` (mirrors `Track.live`). */
-  live?: boolean
-  /** Per-item media-request override when played via `src` (mirrors `Track.request`). */
-  request?: TrackRequest
+  style?: SectionStyle
+  /**
+   * Navigation target for the section header / "view all" surface. A
+   * tile section's header tap (CarPlay) and appended "view all" link
+   * (Android Auto) navigate here. Absent = a pure preview; the header is
+   * not tappable.
+   */
+  path?: string
+  /** The section's tracks. */
+  children: Track[]
 }
 
+/**
+ * The one node type of the browse tree — every tab, folder, station,
+ * episode, and queue item is a Track. What a Track *is* follows from which
+ * address fields it carries: a {@link path} makes it **browsable** (it opens
+ * as a page), a {@link src} makes it **playable** (it can be loaded into the
+ * player); at least one of the two is required. The remaining fields are
+ * display metadata ({@link title}, {@link artist}, {@link artwork}, …) and
+ * content state ({@link favorited}, {@link live}, {@link disabled}).
+ */
 export interface Track {
   /**
    * Opaque, stable identifier for this track.
    *
+   * A track's **identity** is `id` when set (non-blank), falling back to
+   * `src`. That single rule drives every comparison the library makes:
+   * favorites matching (`setFavorites`), the CarPlay / Android Auto
+   * "now playing" row indicator, section scoping and skip-in-place, and the
+   * contextual queue re-expansion. Two tracks refer to the same item iff
+   * their identities are equal — so set `id` consistently on every surface,
+   * or on none.
+   *
    * The library never parses or derives anything from this value — it is
-   * round-tripped verbatim through `setQueue`, `getActiveTrack`, the queue, and
-   * `onActiveTrackChanged`, so consumers can recognise which item became active
-   * after an external transport change (lock screen / CarPlay / Android Auto /
-   * Bluetooth next-previous) without parsing the playable `src`.
-   *
-   * When present on a playable track it is also the track's *identity* on car
-   * browse surfaces: CarPlay's and Android Auto's "now playing" row indicator
-   * match the active track to browse rows by `id` (falling back to exact `src`
-   * equality for tracks without one). Assign ids when your playable `src`
-   * strings for the same item can differ between browse rows and loaded tracks
-   * (absolute vs relative URLs, volatile query params) — otherwise the
-   * indicator never matches.
-   *
-   * It is also handed to the per-track `MediaRequestConfig.resolve` and
-   * `ArtworkRequestConfig.resolve` hooks, so requests can be built from a stable
-   * id (e.g. supply tracks with only an `id` and synthesise `src` in `resolve`).
-   *
-   * Optional: consumers whose `url`/`src` strings are already stable across
-   * surfaces can ignore it.
-   *
-   * Note: an Android Auto item selected directly from the browse tree that the
-   * consumer never queued is identified only by `url`/`src`, so `id` may be
-   * undefined on that specific path.
+   * round-tripped verbatim through `setQueue`, `getActiveTrack`, the queue,
+   * `onActiveTrackChanged`, and `onFavoriteChanged`, and handed to the
+   * per-track `MediaRequestConfig.resolve` / `ArtworkRequestConfig.resolve`
+   * hooks so requests can be built from the stable id.
+   *
+   * Optional: consumers whose `src` strings are identical wherever the same
+   * item appears can ignore it — their identity is the `src`. Assign ids when
+   * `src` strings for the same item can differ between surfaces (absolute vs
+   * relative URLs, volatile query params), or when favorites are stored as an
+   * identifier that isn't the playable URL.
    */
   id?: string
 
@@ -134,9 +247,13 @@ export interface Track {
    * Navigation path. When present, this track is a container (tab, album, playlist, folder)
    * that can be navigated into to view its contents.
    *
-   * At least one of `url` or `src` must be defined.
+   * At least one of `path` or `src` must be defined. When both are set, current
+   * surfaces treat the track as playable — `src` wins the rendering, and the
+   * browse pipeline replaces a playable track's `path` with its contextual
+   * path — so a consumer-supplied `path` on a playable track is not reachable
+   * today.
    */
-  url?: string
+  path?: string
 
   /**
    * Direct audio source identifier. When present, this track can be played directly.
@@ -145,7 +262,7 @@ export interface Track {
    * any string (file path, custom identifier, etc.) that will be passed to
    * MediaRequestConfig.resolve to transform it into the actual media request.
    *
-   * At least one of `url` or `src` must be defined.
+   * At least one of `path` or `src` must be defined.
    */
   src?: string
 
@@ -159,7 +276,8 @@ export interface Track {
    * Pass an {@link ArtworkVariants} pair to supply genuinely different images
    * per appearance — a logo that changes colour, say. For a monochrome glyph
    * that only needs recolouring, prefer a single URL plus
-   * {@link Track.artworkCarPlayTinted}, which is one fetch instead of two.
+   * `style: { artworkRendering: 'stencil' }`, which is one fetch instead
+   * of two.
    *
    * **iOS:** supports {@link https://developer.apple.com/sf-symbols/ | SF Symbols}
    * with the `sf:` prefix and optional color params:
@@ -189,23 +307,6 @@ export interface Track {
   /** Per-track media-request override; merged last (request → media → track.request). */
   request?: TrackRequest
 
-  /**
-   * Whether this artwork should be tinted based on CarPlay's current appearance (light/dark mode).
-   *
-   * When `true`, the artwork is treated as a monochrome icon and tinted:
-   * - Light mode: tinted black for visibility on light backgrounds
-   * - Dark mode: tinted white for visibility on dark backgrounds
-   *
-   * This is useful for SVG or PNG icons that need to adapt to CarPlay's light/dark themes.
-   * Full-color artwork (album covers, logos) should not use this.
-   *
-   * **iOS CarPlay only** - Android Auto is dark-only, so content providers should
-   * provide appropriately colored icons directly (e.g., white icons).
-   *
-   * @default false
-   */
-  artworkCarPlayTinted?: boolean
-
   // type?: TrackType
   /** Primary line shown for this item, in both browse lists and now-playing. */
   title: string
@@ -231,9 +332,9 @@ export interface Track {
 
   /**
    * Browse path the {@link album} line navigates to (same path namespace as
-   * {@link url}). On CarPlay, when the active track has an `albumUrl`, its
+   * {@link path}). On CarPlay, when the active track has an `albumPath`, its
    * album line on the Now Playing screen becomes tappable and navigates the
-   * browse stack there. See also `resolveAlbumUrl` in the browser
+   * browse stack there. See also `resolveAlbumPath` in the browser
    * configuration for a dynamic fallback.
    *
    * Requires {@link album} to be set: CarPlay renders the tappable line from
@@ -241,10 +342,28 @@ export interface Track {
    *
    * @platform ios
    */
-  albumUrl?: string
+  albumPath?: string
 
+  /**
+   * Album name, shown on now-playing surfaces that have an album slot
+   * (CarPlay, Android Auto, Bluetooth metadata — the iOS lock screen has
+   * none). With {@link albumPath} set, CarPlay renders it as a tappable
+   * line that navigates there.
+   */
   album?: string
+
+  /**
+   * Longer free-form text about the item, passed to the platform's
+   * description metadata slot where one exists. Not shown on browse rows
+   * (those render {@link title} / {@link subtitle}) or the lock screen.
+   */
   description?: string
+
+  /**
+   * Genre name, passed to the platform's genre metadata slot where one
+   * exists. Catalog metadata only — the library never matches search or
+   * browse against it.
+   */
   genre?: string
 
   /**
@@ -255,30 +374,31 @@ export interface Track {
   duration?: number
 
   /**
-   * Display style for this item in Android Auto/AAOS.
-   * - 'list': Display as a list row
-   * - 'grid': Display as a grid tile
-   *
-   * On Android: when `artwork` is an `android.resource://` URI
-   * (e.g., `android.resource://com.myapp/drawable/ic_folder`), the library
-   * automatically uses 'category' styling which adds margins around the icon
-   * and enables system tinting for vector drawables.
-   *
-   * @see https://developer.android.com/training/cars/media#default-content-style
+   * The track's style declaration block: inherited item properties (a
+   * per-item override of section/page values — they travel with the
+   * track), plus the positional {@link TrackStyle.display} — on a
+   * browsable track, the advertised layout of the page it opens, read
+   * by Android Auto, which picks a page's layout before resolving it.
    */
   style?: TrackStyle
 
   /**
-   * Display style for this item's children in Android Auto/AAOS.
-   * Only applies to browsable items (containers/folders).
-   * - 'list': Display children as list rows
-   * - 'grid': Display children as grid tiles
-   *
-   * Must be set on the item when it appears as a child in a parent's list.
-   * Android Auto reads the extras at that point to determine how to display
-   * the folder's contents when navigated into.
+   * Unavailable — a content-state fact beside `favorited` and `live`,
+   * with full behavioral weight (content facts may carry behavior; style
+   * never does): a disabled track never plays — tap refused, queue
+   * expansion excludes it, voice search won't match it.
+   *
+   * Rendering ladder, never a trap: **grayed + inert** where the surface
+   * can draw it (CarPlay) → **hidden** where it can't (Android Auto) —
+   * never a normal-looking dead control. Hiding is behavior-safe because
+   * the track is inert everywhere regardless; the cost is losing the
+   * "Available at 9 PM" tease on surfaces that hide, so put the reason
+   * in the title for the ones that gray. Applied at page (re-)serve,
+   * like style.
+   *
+   * @default false
    */
-  childrenStyle?: TrackStyle
+  disabled?: boolean
 
   /**
    * Whether this track is favorited. When the `favorite` capability is enabled,
@@ -287,40 +407,31 @@ export interface Track {
   favorited?: boolean
 
   /**
-   * Group title for section headers in Android Auto/AAOS.
-   * Items with the same groupTitle are displayed under a shared section header.
-   * Items must be contiguous to form a single group.
-   */
-  groupTitle?: string
-
-  /**
-   * Whether this track is a live stream. When true, displays a "live" indicator
-   * in iOS now playing interfaces.
-   */
-  live?: boolean
-
-  /**
-   * When present, renders this track as a horizontal row of tappable artwork
-   * thumbnails instead of a standard list item.
+   * Declares this track a live broadcast rather than a file. The players
+   * detect *transport* liveness (sliding windows, buffering) themselves;
+   * this declaration drives the semantic decisions they can't infer:
    *
-   * - Track.title → row header text
-   * - Track.url → navigated when header is tapped (optional)
-   * - Each ImageRowItem → one thumbnail in the horizontal row; a thumbnail
-   *   with `src` plays immediately on tap, otherwise its `url` is navigated
+   * - **End of stream** (iOS): a live track "ending" is judged a dropped
+   *   broadcast and recovered by rejoining the edge, never a queue advance.
+   * - **Stall recovery** (iOS): a live track that runs dry reconnects at
+   *   the edge; a non-live one resumes its existing connection.
+   * - **`seekToLiveEdge()`** (all platforms): the call only acts on a
+   *   track declared live — without the declaration it is a no-op.
+   * - **Persistence** (iOS): no position is stored, so a cold-start resume
+   *   rejoins the current broadcast instead of seeking a stale timestamp.
+   * - **Now-playing** (iOS): the live indicator and live-style
+   *   (non-scrubbing) progress UI.
    *
-   * On CarPlay: maps to CPListImageRowItem. Limits visible images by display
-   * width (~4-5). Excess silently truncated. A row whose track has no `url`
-   * is a pure preview: its header is not tappable.
+   * The iOS-heavy list is deliberate, not a gap: on Android, ExoPlayer's
+   * own classification already covers these — a dropped live connection
+   * surfaces as a load error (never end-of-stream), and persistence keys
+   * off its detected liveness — so the declaration's only Android reader
+   * is the `seekToLiveEdge()` gate. Android Auto has no live badge.
    *
-   * On Android Auto: there is no image-row rendering, so the row expands into
-   * its items as grid-styled rows (artwork tiles where the host honors the
-   * per-item content-style hint, list rows otherwise) grouped under the
-   * track's title, followed by the track itself as a browsable "view all"
-   * link when it has a `url`.
-   *
-   * On app side: consumable by React Native UI for horizontal thumbnail layouts.
+   * Omitting it never breaks playback — it silently breaks these judgment
+   * calls. Declare it on every live track.
    */
-  imageRow?: ImageRowItem[]
+  live?: boolean
 }
 
 /**
@@ -333,22 +444,43 @@ export interface Track {
  * ```ts
  * // navigate() is fire-and-forget (returns void); read the resolved page
  * // from getContent() / useContent() / onContentChanged.
- * navigate('albums/abbey-road');
+ * navigate('/albums/abbey-road');
  * const resolved = getContent();
- * console.log(resolved?.url); // "albums/abbey-road"
+ * console.log(resolved?.path); // "/albums/abbey-road"
  * console.log(resolved?.title); // "Abbey Road"
- * console.log(resolved?.children); // Array of tracks in this album
+ * console.log(resolved?.sections); // the album's tracks, as sections
  * ```
  */
 export interface ResolvedTrack extends Track {
   /**
-   * URL path for this resolved track. Always present since you navigated to this location.
+   * Browse path of this resolved track. Always present since you navigated to this location.
+   */
+  path: string
+
+  /**
+   * A page is a Track that is also the container of its sections, so its
+   * block widens to {@link SectionStyle}: the declaration for the whole
+   * page. Item properties set here are inherited by every item on the
+   * page unless a section or track declares its own; the container
+   * property (`gridWrap`) and the positional `display` are the page-wide
+   * values a section overrides for its own children.
+   */
+  style?: SectionStyle
+
+  /**
+   * The page's sections — the canonical resolved shape. Every resolved page
+   * with content carries `sections`; a page authored with plain `children`
+   * resolves to a single untitled section.
    */
-  url: string
+  sections?: Section[]
 
   /**
-   * Immediate children of this track. Present for container tracks (albums, playlists, folders).
-   * Undefined for leaf tracks (individual songs without children).
+   * Authoring sugar for a flat page: equivalent to declaring one untitled,
+   * style-less section holding these tracks (which therefore takes the
+   * page block's scope-wide values, like any undeclared section). Accepted
+   * anywhere a page is authored (static routes, browse callbacks, JSON
+   * payloads); never populated on a *resolved* page — read `sections`
+   * instead.
    */
   children?: Track[]