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

package/nitrogen/generated/shared/c++/TrackStyle.hpp

@@ -32,10 +32,17 @@
 namespace margelo::nitro::audiobrowser { enum class StyleDisplay; }
 // Forward declaration of `ArtworkRendering` to properly resolve imports.
 namespace margelo::nitro::audiobrowser { enum class ArtworkRendering; }
+// Forward declaration of `ImageShape` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class ImageShape; }
+// Forward declaration of `CardImage` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class CardImage; }
 
 #include "StyleDisplay.hpp"
 #include <optional>
 #include "ArtworkRendering.hpp"
+#include "ImageShape.hpp"
+#include <string>
+#include "CardImage.hpp"
 
 namespace margelo::nitro::audiobrowser {
 
@@ -46,10 +53,14 @@ namespace margelo::nitro::audiobrowser {
   public:
     std::optional<StyleDisplay> display     SWIFT_PRIVATE;
     std::optional<ArtworkRendering> artworkRendering     SWIFT_PRIVATE;
+    std::optional<ImageShape> imageShape     SWIFT_PRIVATE;
+    std::optional<std::string> accessorySymbol     SWIFT_PRIVATE;
+    std::optional<std::string> cardTint     SWIFT_PRIVATE;
+    std::optional<CardImage> cardImage     SWIFT_PRIVATE;
 
   public:
     TrackStyle() = default;
-    explicit TrackStyle(std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering): display(display), artworkRendering(artworkRendering) {}
+    explicit TrackStyle(std::optional<StyleDisplay> display, std::optional<ArtworkRendering> artworkRendering, std::optional<ImageShape> imageShape, std::optional<std::string> accessorySymbol, std::optional<std::string> cardTint, std::optional<CardImage> cardImage): display(display), artworkRendering(artworkRendering), imageShape(imageShape), accessorySymbol(accessorySymbol), cardTint(cardTint), cardImage(cardImage) {}
 
   public:
     friend bool operator==(const TrackStyle& lhs, const TrackStyle& rhs) = default;
@@ -66,13 +77,21 @@ namespace margelo::nitro {
       jsi::Object obj = arg.asObject(runtime);
       return margelo::nitro::audiobrowser::TrackStyle(
         JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display"))),
-        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))
       );
     }
     static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::TrackStyle& arg) {
       jsi::Object obj(runtime);
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "display"), JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::toJSI(runtime, arg.display));
       obj.setProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::toJSI(runtime, arg.artworkRendering));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "imageShape"), JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::toJSI(runtime, arg.imageShape));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.accessorySymbol));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardTint"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.cardTint));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "cardImage"), JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::toJSI(runtime, arg.cardImage));
       return obj;
     }
     static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
@@ -85,6 +104,10 @@ namespace margelo::nitro {
       }
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::StyleDisplay>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "display")))) return false;
       if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ArtworkRendering>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "artworkRendering")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::ImageShape>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "imageShape")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "accessorySymbol")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardTint")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::CardImage>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "cardImage")))) return false;
       return true;
     }
   };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.2.0-next.12",
+  "version": "0.2.0-next.14",
   "description": "react-native-audio-browser is a react native package built with Nitro",
   "keywords": [
     "react-native",
@@ -31,6 +31,7 @@
     "ios/**/*.mm",
     "ios/**/*.cpp",
     "ios/**/*.swift",
+    "website/guide",
     "*.podspec",
     "README.md"
   ],
@@ -46,23 +47,27 @@
   "scripts": {
     "android:format": "yarn workspace example-native android:format",
     "android:format:check": "yarn workspace example-native android:format:check",
+    "android:gradle-stop": "yarn workspace example-native android:gradle-stop",
     "android:ide": "yarn workspace example-native android:ide",
     "android:logs": "react-native log-android",
     "android:test": "yarn workspace example-native android:test",
+    "android:types": "yarn workspace example-native android:types",
     "build": "yarn prepare",
     "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
     "codegen": "node codegen/index.js --logLevel=\"debug\" && node post-script.cjs && node codegen/strip-struct-equality.cjs && yarn build",
     "prepare": "bob build && yarn hooks:install",
     "hooks:install": "git config core.hooksPath .githooks || exit 0",
     "example": "yarn workspace example-native",
+    "ci:android": "yarn android:format:check && yarn android:types && yarn android:test",
     "ci:format": "oxfmt --check --ignore-path .gitignore --ignore-path .oxfmtignore .",
     "ci:format:ios": "swiftformat --lint ios",
+    "ci:ios": "yarn ci:format:ios && yarn ios:test",
     "ci:lint": "oxlint --type-aware src",
     "format": "oxfmt --write --ignore-path .gitignore --ignore-path .oxfmtignore .",
     "ios:format": "swiftformat ios",
     "ios:ide": "yarn workspace example-native ios:ide",
     "ios:rebuild": "yarn workspace example-native ios:rebuild",
-    "ios:test": "swift test",
+    "ios:test": "swift test --disable-sandbox",
     "lint": "oxlint --fix",
     "release": "semantic-release",
     "test": "vitest run",

package/src/features/browser-config.ts

@@ -289,6 +289,7 @@ export function toNativeConfig(
     singleTrack: config.singleTrack,
     handleTrackLoad: config.handleTrackLoad,
     androidControllerOfflineError: config.androidControllerOfflineError,
+    viewMoreTitle: config.viewMoreTitle,
     carPlayLoadingTitle: config.carPlayLoadingTitle,
     resolveAlbumPath: config.resolveAlbumPath,
     formatNavigationError: config.formatNavigationError

package/src/features/playback/progress.ts

@@ -118,7 +118,8 @@ export function usePolledProgress(updateInterval = 1000): Progress {
     }
 
     const stop = () => {
-      clearTimeout(timer)
+      // Guarded: React Native types clearTimeout(handle: number) — no undefined.
+      if (timer !== undefined) clearTimeout(timer)
       timer = undefined
       unsubscribeState?.()
       unsubscribeState = undefined

package/src/features/playback/rate.ts

@@ -14,8 +14,15 @@ export function getRate(): number {
 
 /**
  * Sets the playback rate.
+ *
+ * The rate is a speed multiplier, not a transport control — it is independent
+ * of play/pause, and setting it while paused never starts playback. Use
+ * {@link play} / {@link pause} for that.
+ *
  * @param rate - The playback rate to change to, where 0.5 would be half speed,
- * 1 would be regular speed, 2 would be double speed etc.
+ * 1 would be regular speed, 2 would be double speed etc. Must be greater than
+ * zero; platforms disagree on what a non-positive rate does (iOS ignores it,
+ * Android throws, web stalls the element), so treat it as unsupported.
  */
 export function setRate(rate: number): void {
   nativeBrowser.setRate(rate)

package/src/style-resolution.test.ts

@@ -3,7 +3,12 @@ import { join } from 'node:path'
 import { describe, expect, it } from 'vitest'
 
 /**
- * Inheritance-completeness guard for the style declaration block (ADR 0011).
+ * Completeness guards for the style declaration block (ADR 0011) — the checks
+ * Nitro's `extends`-flattening took out of the type system, in two parts:
+ * every key must be *resolved* by each platform's `StyleResolver`, and every
+ * key must be *accounted for* by each platform's `InertStyleDiagnostic`.
+ *
+ * Part one — inheritance completeness.
  *
  * `SectionStyle extends TrackStyle` in the spec, but Nitro flattens `extends`
  * into independent structs on every platform — so nothing in any type system
@@ -137,3 +142,69 @@ for (const resolver of RESOLVERS) {
     })
   })
 }
+
+/**
+ * Part two — diagnostic completeness.
+ *
+ * The block model traded compile-time invalid-combination errors for
+ * inertness, and the dev-mode `InertStyleDiagnostic` is the recovery. It is
+ * exposed to the same flattening problem as the resolvers, one level up: a
+ * key added to the spec has no type-system tie to the diagnostic's rule set,
+ * so a property could ship whose inert combinations nobody is warned about.
+ *
+ * Each platform therefore dispositions the whole vocabulary — every key is a
+ * `Property` with an inertness rule, `alwaysRenderable`, or `positional` —
+ * and this test reads those three declarations and asserts set equality with
+ * the spec, both directions: a new key must be dispositioned, and a key
+ * deleted from the spec must not linger in the rule set.
+ */
+const DIAGNOSTICS = [
+  {
+    file: 'ios/Browser/InertStyleDiagnostic.swift',
+    // `case gridWrap`, up to the first member after the case list.
+    ruled: (source: string) =>
+      keysIn(
+        source,
+        /enum Property[\s\S]*?var isItemProperty/,
+        /^\s*case (\w+)$/gm
+      )
+  },
+  {
+    file: 'android/src/main/java/com/audiobrowser/browser/InertStyleDiagnostic.kt',
+    // `GRID_WRAP("gridWrap", …)`, up to the `;` that ends the entry list.
+    ruled: (source: string) =>
+      keysIn(source, /enum class Property[\s\S]*?;/, /\w+\("(\w+)"/g)
+  }
+]
+
+/** The capture group of every `pattern` match within the first `region`. */
+function keysIn(source: string, region: RegExp, pattern: RegExp): string[] {
+  const found = region.exec(source)
+  expect(found, `region ${region} not found`).not.toBeNull()
+  return [...found![0].matchAll(pattern)].flatMap((match) =>
+    match[1] === undefined ? [] : [match[1]]
+  )
+}
+
+for (const diagnostic of DIAGNOSTICS) {
+  describe(diagnostic.file, () => {
+    // Comment-free, so prose naming a key doesn't pass for dispositioning it.
+    const source = stripComments(
+      readFileSync(join(ROOT, diagnostic.file), 'utf8')
+    )
+    // The two lists are spelled `alwaysRenderable`/`positional` in Swift and
+    // SCREAMING_CASE in Kotlin; both hold bare string literals.
+    const listed = [
+      ...source.matchAll(
+        /(?:alwaysRenderable|ALWAYS_RENDERABLE|positional|POSITIONAL)\s*=[^\n]*/gi
+      )
+    ].flatMap((match) =>
+      [...match[0].matchAll(/"(\w+)"/g)].map((key) => key[1])
+    )
+
+    it('dispositions every key of the block, and only those', () => {
+      const dispositioned = [...diagnostic.ruled(source), ...listed]
+      expect(new Set(dispositioned)).toEqual(new Set(sectionKeys))
+    })
+  })
+}

package/src/types/browser-native.ts

@@ -14,7 +14,8 @@ import type {
   HandleTrackLoadCallback,
   MediaRequestConfig,
   SearchSourceCallback,
-  TransformableRequestConfig
+  TransformableRequestConfig,
+  ViewMoreTitleCallback
 } from './browser'
 import type { ResolvedTrack } from './browser-nodes'
 
@@ -73,6 +74,9 @@ export interface NativeBrowserConfiguration {
   singleTrack?: boolean
   handleTrackLoad?: HandleTrackLoadCallback
   androidControllerOfflineError?: boolean
+  // Title of the "view more" row appended to a pathed section where the header
+  // can't be tapped (Android Auto). Absent = native's "View more" default.
+  viewMoreTitle?: ViewMoreTitleCallback
 
   // CarPlay options
   carPlayLoadingTitle?: string

package/src/types/browser-nodes.ts

@@ -25,6 +25,50 @@ export type StyleDisplay = 'list' | 'grid'
  */
 export type ArtworkRendering = 'original' | 'stencil'
 
+/**
+ * The shape a 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) — artwork tiles with a title.
+ * - `'card'` — a larger card with title/subtitle and a
+ *   {@link TrackStyle.cardTint} color; its image mode is
+ *   {@link TrackStyle.cardImage}. Cards have no shape.
+ * - `'condensed'` — a denser cell carrying title + subtitle; takes
+ *   {@link TrackStyle.imageShape} and {@link TrackStyle.accessorySymbol}
+ *   like a plain tile.
+ *
+ * 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' | 'card' | 'condensed'
+
+/**
+ * How a card tile uses its image.
+ *
+ * - `'normal'` (default) — image above the labels;
+ *   {@link TrackStyle.cardTint} colors a gradient behind the labels.
+ * - `'background'` — the image fills the card full-height with the labels
+ *   overlaid; `cardTint` becomes the color 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
@@ -82,6 +126,58 @@ export interface TrackStyle {
    * @platform carplay
    */
   artworkRendering?: ArtworkRendering
+
+  /**
+   * Inherited (`track ?? section ?? page`): the shape a 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
+   * grid renders it next. Inert where the presentation has no shape
+   * (list rows, 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, leading the title on an iOS 26 grid
+   * tile (placement is the platform's choice per surface). 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'`) — a gradient behind the labels, or the
+   * color behind them 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
 }
 
 /**
@@ -113,6 +209,20 @@ export interface SectionStyle extends TrackStyle {
    * @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
 }
 
 /**
@@ -183,11 +293,6 @@ export type TrackArtwork = string | ArtworkVariants
 export interface Section {
   /** Header text. Absent = headerless group. */
   title?: string
-  /**
-   * Secondary line for the section's navigation surface — e.g. the label
-   * of the "view all" link a tile section gets on Android Auto.
-   */
-  subtitle?: string
   /**
    * Presentation, separated from content. Each surface renders the
    * declared layout's nearest supported form; on CarPlay
@@ -198,10 +303,20 @@ export interface Section {
    */
   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.
+   * 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).
    */
   path?: string
   /** The section's tracks. */

package/src/types/browser.ts

@@ -931,6 +931,41 @@ export type BrowserConfiguration = {
    */
   androidControllerOfflineError?: boolean
 
+  /**
+   * Titles the "view more" row appended to a `Section` that carries a
+   * `Section.path` on surfaces whose section header cannot be tapped —
+   * Android Auto, today the only one.
+   *
+   * Leave it unset and the row is titled "View more" — the library's in-code
+   * default, the same arrangement `formatNavigationError` has. Set this to
+   * localize it: it is re-resolved once per content generation, so
+   * `invalidateAllContent()` after an in-app language switch picks up the new
+   * copy without reconfiguring the browser. That is why it is a callback rather
+   * than a plain string — an app whose locale is its own, not the system's,
+   * cannot express that with a value frozen at configure time.
+   *
+   * One string for every section by design — the row is a fallback for a
+   * surface that cannot draw a link in its header, so per-section wording would
+   * be ceremony most consumers never see rendered.
+   *
+   * For wording that varies by section — "View all 42 albums", "See every
+   * episode" — author the link yourself instead: append an ordinary browsable
+   * {@link Track} to the section's `children`, titled however you like, and
+   * leave `Section.path` unset so this row doesn't also appear. Since the
+   * row is Android-only, that branch is an ordinary platform check on the
+   * content you emit; CarPlay never sees the extra row.
+   *
+   * @default 'View more'
+   *
+   * @example
+   * ```typescript
+   * viewMoreTitle: () => t('View more')
+   * ```
+   *
+   * @platform android
+   */
+  viewMoreTitle?: ViewMoreTitleCallback
+
   /**
    * Title shown (as the list's centered empty state) on CarPlay screens whose
    * content is still loading — browse destinations while they resolve, and the
@@ -1093,3 +1128,6 @@ export type FormatNavigationErrorCallback = (
  * or `undefined` to do nothing. See `resolveAlbumPath`.
  */
 export type ResolveAlbumPathCallback = (track: Track) => string | undefined
+
+/** Supplies the title of the appended "view more" row. See `viewMoreTitle`. */
+export type ViewMoreTitleCallback = () => string

package/src/web/TrackPlayer/QueueManager.test.ts

@@ -160,6 +160,35 @@ describe('QueueManager', () => {
       expect(q.nextIndex()).toBeUndefined()
     })
 
+    // Filling a queue that had no current track: the order is shuffled with
+    // nothing to lead it, so the track that becomes current can land anywhere —
+    // last included, which reads as end-of-queue from the very first track.
+    it('leads the order with the start track when setTracks fills an empty queue', () => {
+      const fresh = new QueueManager()
+      fresh.setShuffleEnabled(true) // shuffle already on, queue still empty
+      fresh.setTracks(tracks(4))
+      fresh.currentIndex = 2 // the start index
+
+      // identity order [0,1,2,3] re-pinned on 2 → [2,1,0,3]
+      expect(fresh.previousIndex()).toBeUndefined()
+      expect(fresh.nextIndex()).toBe(1)
+    })
+
+    it('leads the order with the start track when insert fills an empty queue', () => {
+      const fresh = new QueueManager()
+      fresh.setShuffleEnabled(true)
+      const random = vi.spyOn(Math, 'random').mockReturnValue(0.999)
+      try {
+        fresh.insert(tracks(4)) // slotted in at the order's end → [0,1,2,3]
+      } finally {
+        random.mockRestore()
+      }
+      fresh.currentIndex = 3 // would sit LAST in the order without the re-pin
+
+      expect(fresh.nextIndex()).toBe(1)
+      expect(fresh.previousIndex()).toBeUndefined()
+    })
+
     it('keeps every track at its shuffle position across a move', () => {
       q.currentIndex = 1
       q.move(1, 3) // tracks [s0,s2,s3,s1]; order remapped to [0,3,1,2]

package/src/web/TrackPlayer/QueueManager.ts

@@ -63,8 +63,22 @@ export class QueueManager {
   }
 
   set currentIndex(index: number | undefined) {
+    const hadNoCurrent = this._currentIndex === undefined
     this._lastIndex = this._currentIndex
     this._currentIndex = index
+
+    // A queue with no current track has an order that was shuffled with nothing
+    // to lead it — `setTracks` clears the index before regenerating, and
+    // `insert` drops new indices at random positions — so the track that then
+    // becomes current can sit anywhere, including last. That reads as
+    // end-of-queue immediately: `nextIndex` is undefined from the first track,
+    // so auto-advance fires onQueueEnded after one track. Re-pin at the moment
+    // the queue gains a current track. Safe as a setter hook here because the
+    // tracks are always in place before the index is assigned (both `setTracks`
+    // and `insert` run first).
+    if (hadNoCurrent && index !== undefined && this._shuffleEnabled) {
+      this.regenerateShuffleOrder()
+    }
   }
 
   get lastIndex(): number | 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. A section that carries a `path` also gets a browsable "view more" row appended after its children, navigating there. No header is tappable on Android Auto at any `display`, so the row is the only affordance the section's `path` has here; its title comes from the [`viewMoreTitle`](/api/types/browser/#viewmoretitle) browser option, defaulting to `"View more"` — one wording for every section. For per-section copy (`"View all 42 albums"`), leave `path` unset and append your own browsable `Track` to `children` instead, titled however you like; this page's content is Android-only anyway, so CarPlay never sees it.
+
+::: 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.