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

package/lib/typescript/src/types/browser-native.d.ts

@@ -5,7 +5,7 @@
  * into separate optional properties to reduce generated code complexity.
  * Users should use BrowserConfiguration, not these types directly.
  */
-import type { ArtworkRequestConfig, BrowserSourceCallback, ResolveAlbumUrlCallback, FormatNavigationErrorCallback, HandleTrackLoadCallback, MediaRequestConfig, SearchSourceCallback, TransformableRequestConfig } from './browser';
+import type { ArtworkRequestConfig, BrowserSourceCallback, ResolveAlbumPathCallback, FormatNavigationErrorCallback, HandleTrackLoadCallback, MediaRequestConfig, SearchSourceCallback, TransformableRequestConfig, ViewMoreTitleCallback } from './browser';
 import type { ResolvedTrack } from './browser-nodes';
 type NativeRequestConfigResolver = () => Promise<TransformableRequestConfig>;
 /**
@@ -38,8 +38,9 @@ export interface NativeBrowserConfiguration {
     singleTrack?: boolean;
     handleTrackLoad?: HandleTrackLoadCallback;
     androidControllerOfflineError?: boolean;
+    viewMoreTitle?: ViewMoreTitleCallback;
     carPlayLoadingTitle?: string;
-    resolveAlbumUrl?: ResolveAlbumUrlCallback;
+    resolveAlbumPath?: ResolveAlbumPathCallback;
     formatNavigationError?: FormatNavigationErrorCallback;
 }
 export {};

package/lib/typescript/src/types/browser-native.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser-native.d.ts","sourceRoot":"","sources":["../../../../src/types/browser-native.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,uBAAuB,EACvB,6BAA6B,EAC7B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC3B,MAAM,WAAW,CAAA;AAClB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAMpD,KAAK,2BAA2B,GAAG,MAAM,OAAO,CAAC,0BAA0B,CAAC,CAAA;AAE5E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IAEZ,cAAc,CAAC,EAAE,qBAAqB,CAAA;IACtC,YAAY,CAAC,EAAE,0BAA0B,CAAA;IACzC,YAAY,CAAC,EAAE,aAAa,CAAA;IAE5B,cAAc,CAAC,EAAE,oBAAoB,CAAA;IACrC,YAAY,CAAC,EAAE,0BAA0B,CAAA;IAEzC,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IAKb,OAAO,CAAC,EAAE,0BAA0B,CAAA;IACpC,eAAe,CAAC,EAAE,2BAA2B,CAAA;IAG7C,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,cAAc,CAAC,EAAE,2BAA2B,CAAA;IAC5C,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,iBAAiB,CAAC,EAAE,oBAAoB,CAAA;IAQxC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAG3B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IAGvC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,qBAAqB,CAAC,EAAE,6BAA6B,CAAA;CACtD"}
+{"version":3,"file":"browser-native.d.ts","sourceRoot":"","sources":["../../../../src/types/browser-native.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,KAAK,EACV,oBAAoB,EACpB,qBAAqB,EACrB,wBAAwB,EACxB,6BAA6B,EAC7B,uBAAuB,EACvB,kBAAkB,EAClB,oBAAoB,EACpB,0BAA0B,EAC1B,qBAAqB,EACtB,MAAM,WAAW,CAAA;AAClB,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAA;AAMpD,KAAK,2BAA2B,GAAG,MAAM,OAAO,CAAC,0BAA0B,CAAC,CAAA;AAE5E;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,CAAA;IAEZ,cAAc,CAAC,EAAE,qBAAqB,CAAA;IACtC,YAAY,CAAC,EAAE,0BAA0B,CAAA;IACzC,YAAY,CAAC,EAAE,aAAa,CAAA;IAE5B,cAAc,CAAC,EAAE,oBAAoB,CAAA;IACrC,YAAY,CAAC,EAAE,0BAA0B,CAAA;IAEzC,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAA;CAC/B;AAED;;;GAGG;AACH,MAAM,WAAW,0BAA0B;IACzC,IAAI,CAAC,EAAE,MAAM,CAAA;IAKb,OAAO,CAAC,EAAE,0BAA0B,CAAA;IACpC,eAAe,CAAC,EAAE,2BAA2B,CAAA;IAG7C,MAAM,CAAC,EAAE,0BAA0B,CAAA;IACnC,cAAc,CAAC,EAAE,2BAA2B,CAAA;IAC5C,KAAK,CAAC,EAAE,kBAAkB,CAAA;IAC1B,OAAO,CAAC,EAAE,oBAAoB,CAAA;IAC9B,iBAAiB,CAAC,EAAE,oBAAoB,CAAA;IAQxC,MAAM,CAAC,EAAE,gBAAgB,EAAE,CAAA;IAG3B,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,eAAe,CAAC,EAAE,uBAAuB,CAAA;IACzC,6BAA6B,CAAC,EAAE,OAAO,CAAA;IAGvC,aAAa,CAAC,EAAE,qBAAqB,CAAA;IAGrC,mBAAmB,CAAC,EAAE,MAAM,CAAA;IAC5B,gBAAgB,CAAC,EAAE,wBAAwB,CAAA;IAC3C,qBAAqB,CAAC,EAAE,6BAA6B,CAAA;CACtD"}

package/lib/typescript/src/types/browser-nodes.d.ts

@@ -1,5 +1,223 @@
 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 shape an image or condensed grid tile's artwork is cropped to.
+ *
+ * - `'rounded-rectangle'` (default) — the standard tile crop.
+ * - `'circular'` — the standard presentation for *people* (artists, hosts,
+ *   DJs). Shape encodes the kind of item, so mixed grids legitimately
+ *   render circular artists next to rounded albums.
+ *
+ * Named after Apple's `imageShape` parameter (a platform passthrough), and
+ * deliberately without a grid prefix: every tile presentation that takes a
+ * shape reads the same property.
+ */
+export type ImageShape = 'circular' | 'rounded-rectangle';
+/**
+ * The kind of tile a grid renders.
+ *
+ * - `'plain'` (default) — large artwork tiles with a title and subtitle
+ *   below. No shape and no accessory.
+ * - `'image'` — artwork tiles with a title and no subtitle; takes
+ *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}.
+ *   The grid of round tiles for people is `'image'` with
+ *   `imageShape: 'circular'`.
+ * - `'card'` — a larger card with title/subtitle and a
+ *   {@link TrackStyle.cardTint} color; its image mode is
+ *   {@link TrackStyle.cardImage}. Cards have no shape and no accessory.
+ * - `'condensed'` — a denser cell carrying title + subtitle beside a small
+ *   image; takes {@link TrackStyle.imageShape} and
+ *   {@link TrackStyle.accessorySymbol}.
+ *
+ * Element families are mutually exclusive within a container, so this is
+ * a container property — hence the enum, and the `grid` prefix.
+ */
+export type GridTile = 'plain' | 'image' | 'card' | 'condensed';
+/**
+ * How a card tile uses its image.
+ *
+ * - `'normal'` (default) — a square image inset above the labels;
+ *   {@link TrackStyle.cardTint} colors the whole card.
+ * - `'background'` — the image fills the card full-height with the labels
+ *   overlaid; `cardTint` fades in behind them. Selects the larger artwork
+ *   target size.
+ *
+ * An enum rather than a boolean: it names the card's image mode and
+ * leaves room for future modes.
+ */
+export type CardImage = 'normal' | 'background';
+/**
+ * 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;
+    /**
+     * Inherited (`track ?? section ?? page`): the shape an image or
+     * condensed grid tile's artwork is cropped to — `'circular'` for people,
+     * the default `'rounded-rectangle'` for everything else. Shape follows
+     * the item wherever it travels: a circular artist stays circular in
+     * whatever shaped grid renders it next. Inert where the presentation has
+     * no shape (list rows, plain and card tiles, pre-26 CarPlay, Android
+     * Auto).
+     *
+     * @default 'rounded-rectangle'
+     *
+     * @platform carplay
+     */
+    imageShape?: ImageShape;
+    /**
+     * Inherited (`track ?? section ?? page`): an SF Symbol name drawn as
+     * the item's accessory wherever the current presentation supports one —
+     * the trailing edge of a list row or an iOS 26 condensed tile, leading
+     * the title on an image tile (placement is the platform's choice per
+     * surface); plain and card tiles have no slot for one. A resolved
+     * symbol replaces the derived accessory (the disclosure chevron a
+     * browsable row gets); `'none'` clears an inherited value, restoring
+     * the derived behavior — inheritance has no other escape, and no SF
+     * Symbol is named `none`, so the sentinel is collision-free. Inert off
+     * CarPlay.
+     *
+     * @platform carplay
+     */
+    accessorySymbol?: string;
+    /**
+     * Inherited (`track ?? section ?? page`): the card treatment's tint
+     * color (hex, e.g. `'#1e3a8a'`) — the card's own color, or the color
+     * that fades in behind the labels when {@link TrackStyle.cardImage} is
+     * `'background'`. Card-prefixed: inert unless the container renders
+     * `gridTile: 'card'`.
+     *
+     * @platform carplay
+     */
+    cardTint?: string;
+    /**
+     * Inherited (`track ?? section ?? page`): how a card tile uses its
+     * image — see {@link CardImage}. Uniform via the section value,
+     * mixable per card. Inert unless the container renders
+     * `gridTile: 'card'`.
+     *
+     * @default 'normal'
+     *
+     * @platform carplay
+     */
+    cardImage?: CardImage;
+}
+/**
+ * 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;
+    /**
+     * The kind of tile this container's grid renders — see
+     * {@link GridTile}. A container property (element families are
+     * container-homogeneous), resolved by scope override
+     * (`section ?? page`), never per item. Inert unless
+     * {@link TrackStyle.display} is `'grid'`, and on CarPlay before
+     * iOS 26 (where the treatment drops and the layout survives).
+     *
+     * @default 'plain'
+     *
+     * @platform carplay
+     */
+    gridTile?: GridTile;
+}
 /**
  * Image source for React Native's `<Image>` component.
  * Contains all information needed to load an image, including URL transformation
@@ -50,74 +268,89 @@ 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`).
+     * 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.
      */
-    id?: string;
-    /** Navigation path. Tapping this thumbnail navigates to this URL. */
-    url?: string;
+    style?: SectionStyle;
     /**
-     * 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`.
+     * Navigation target for the section's "view all" affordance — the
+     * fuller page this section is a teaser for. Absent = a self-contained
+     * section: the header is a plain label, not a link.
+     *
+     * The surface picks the form (ADR 0010), and each carries the copy
+     * itself — a `path` never adds words to the section:
+     *
+     * - **CarPlay** — a tile section's row draws a disclosure chevron and
+     *   the whole row navigates. A list section renders no affordance:
+     *   CarPlay has no "see all" idiom for one, and an invented row would
+     *   spend an item from the template's cap.
+     * - **Android Auto** — no header is tappable at any display, so the
+     *   section gets an appended browsable row, titled by the global
+     *   `viewMoreTitle` browser option ("View more" by default).
      */
-    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;
+    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;
     /**
      * 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.
      *
@@ -125,7 +358,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;
     /**
@@ -138,7 +371,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:
@@ -165,22 +399,6 @@ export interface Track {
     readonly artworkSource?: ImageSource;
     /** 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;
     /** Primary line shown for this item, in both browse lists and now-playing. */
     title: string;
     /**
@@ -202,9 +420,9 @@ export interface Track {
     artist?: string;
     /**
      * 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
@@ -212,9 +430,25 @@ 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;
     /**
      * Duration in seconds, as catalog metadata for app UI (e.g. an episode
@@ -223,67 +457,75 @@ 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
+     * 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.
      *
-     * 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.
+     * @default false
      */
-    childrenStyle?: TrackStyle;
+    disabled?: boolean;
     /**
      * Whether this track is favorited. When the `favorite` capability is enabled,
      * displays a filled/empty heart icon in media controllers (notification, Android Auto).
      */
     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.
-     *
-     * - 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
+     * 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:
      *
-     * 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.
+     * - **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 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`.
+     * 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 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;
+    /**
+     * Byte encoding of this track's ICY `StreamTitle` when it is not UTF-8, as
+     * an IANA label (`'windows-1251'`, `'windows-874'`, …). Some Shoutcast /
+     * Icecast stations send titles in a legacy code page; ICY declares no
+     * encoding, so the player's UTF-8 decode fails and falls back to Latin-1,
+     * showing mojibake. With this set, a title that came out Latin-1 shaped
+     * (every char at or below U+00FF, some at or above U+0080) is re-decoded
+     * through ISO-8859-1 with the given charset; this also repairs stations
+     * that UTF-8 encoded their legacy bytes. A title already in another script
+     * or pure ASCII is left alone. Applies to ICY only: ID3 and HLS timed
+     * metadata declare their own encoding and are never touched. A label the
+     * platform cannot decode with is ignored.
+     */
+    icyCharset?: string;
 }
 /**
  * A Track that has been resolved with its children through browsing.
@@ -295,21 +537,40 @@ 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[];
     /**