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

package/website/guide/errors.md

@@ -0,0 +1,310 @@
+---
+description: 'Playback errors versus navigation errors: how each surfaces, what the automatic retry budget does, and how to show an advisory error while it retries.'
+---
+
+# Errors
+
+Two different things can fail, and they surface separately:
+
+- **Playback errors** — a track or stream won't play. See
+  [Playback errors](#playback-errors).
+- **Navigation errors** — browsing/resolving content failed (a route errored,
+  the network dropped, a server returned non-2xx). See
+  [Navigation errors](#navigation-errors).
+
+For playback, the library can also **retry automatically** — transient failures
+recover on their own, and while it retries the error is surfaced as _advisory_
+so your UI can say what's wrong over the spinner. See
+[Automatic retry](#automatic-retry).
+
+The UI snippets import `View` / `Text` / `Button` from `react-native`; everything
+else is from `react-native-audio-browser`.
+
+## Playback errors
+
+When the active track fails, the [playback state](/guide/playback#playback-state)
+becomes `'error'` and a [`PlaybackError`](/api/features/errors/#playbackerror) is
+available. Read it reactively with
+[`usePlaybackError()`](/api/features/errors/#useplaybackerror) — it returns the
+current error, or `undefined` once playback recovers.
+
+`PlaybackError` is `{ kind, code, message, statusCode?, retrying? }`. **Branch
+on `kind`**:
+
+| Field        | Use it for                                                                                                                                                                       |
+| ------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `kind`       | Everything user-facing. A normalized classification both platforms map onto — see the table below.                                                                               |
+| `code`       | Diagnostics and telemetry **only**. Platform-specific and unstable: loader cases on iOS (`failed-to-load`, …), lower-cased ExoPlayer names on Android (`io-bad-http-status`, …). |
+| `message`    | Logs. Hard-coded developer English, e.g. _"Failed to load audio track"_.                                                                                                         |
+| `statusCode` | The HTTP status, when the failure came from a response.                                                                                                                          |
+| `retrying`   | `true` while [automatic retry](#automatic-retry) is still working on the failure — the error is advisory, not final. See [Errors while retrying](#errors-while-retrying).        |
+
+::: warning Don't show `message` to listeners
+It is developer English and it is never localized. Map `kind` to your own copy
+instead — the same error reaches the lock screen and the car, where a technical
+string is especially jarring.
+:::
+
+`kind` is one of:
+
+| `kind`           | Meaning                                                                                                         | Retrying help?   |
+| ---------------- | --------------------------------------------------------------------------------------------------------------- | ---------------- |
+| `'offline'`      | The device had no connection at the moment of failure. The stream may be fine.                                  | Once back online |
+| `'unreachable'`  | The host could not be reached: DNS failure, refused connection, timeout, or a connection dropped while loading. | Maybe            |
+| `'not-found'`    | The server said this stream is gone (HTTP 404 / 410).                                                           | No               |
+| `'rejected'`     | The server refused the request (HTTP 401 / 403) — geo-blocking, an expired token.                               | No               |
+| `'server-error'` | The server responded 5xx. Usually transient.                                                                    | Maybe            |
+| `'unplayable'`   | Fetched, but not playable: unknown container, unsupported codec, decoder failure.                               | No               |
+| `'stalled'`      | Playback had started, then stopped, and the player exhausted its recovery budget.                               | Maybe            |
+| `'unknown'`      | Could not be classified. Inspect `code`.                                                                        | Maybe            |
+
+Codes that name no cause stay `'unknown'` rather than being guessed into a
+friendlier bucket — a wrong classification misleads the listener _and_ poisons
+your telemetry aggregates.
+
+Map `kind` to your own localized copy. How finely you split is a product
+decision — collapsing several kinds onto one line is fine, as long as the
+listener can still tell _"fix your connection"_ from _"this one is gone"_ from
+_"try again in a minute"_:
+
+```tsx
+import { View, Text, Button } from 'react-native'
+import { usePlaybackError, retry } from 'react-native-audio-browser'
+import type { PlaybackErrorKind } from 'react-native-audio-browser'
+
+function errorLine(kind: PlaybackErrorKind): string {
+  switch (kind) {
+    case 'offline':
+      return t('…your "check your connection" copy')
+    // Both transient — worth another try, so they can share a line.
+    case 'unreachable':
+    case 'server-error':
+      return t('…your "could not reach it" copy')
+    // Both permanent — retrying will not help.
+    case 'not-found':
+    case 'rejected':
+      return t('…your "not available" copy')
+    case 'unplayable':
+      return t('…your "cannot be played" copy')
+    case 'stalled':
+      return t('…your "connection lost" copy')
+    case 'unknown':
+      return t('…your generic fallback copy')
+  }
+}
+
+function PlaybackErrorView() {
+  const error = usePlaybackError()
+  if (!error) return null
+  return (
+    <View>
+      <Text>{errorLine(error.kind)}</Text>
+      <Button title="Try again" onPress={() => retry()} />
+    </View>
+  )
+}
+```
+
+Leaving off the `default` case is deliberate: TypeScript then tells you when a
+new `kind` is added, instead of it silently falling into a generic line.
+
+Outside React, use `getPlaybackError()` for a snapshot or
+[`onPlaybackError`](/api/features/errors/#onplaybackerror) to subscribe. The same
+error is also passed to the [Now Playing formatter](/guide/now-playing#the-formatter-derived-continuous),
+so you can show it on the lock screen / car too.
+
+### Manual retry
+
+[`retry()`](/api/features/errors/#retry) re-attempts the current item — it only
+does something while the state is `'error'`. It's the action behind a "Try again"
+button, and what you call after [automatic retry](#automatic-retry) has given up.
+It begins a fresh load with fresh retry budgets, exactly as if the listener had
+re-selected the track (a plain play command from `'error'` does the same).
+
+## Automatic retry
+
+Configure [`setupPlayer({ retry })`](/guide/configuration) to recover from
+transient **load** failures (network blips, timeouts, a live stream dropping
+mid-play) with exponential backoff. It's **off by default**, and it's native
+only — the web implementation has no automatic retry, so every web error is
+terminal:
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+// Retry with the default duration budgets (12s / 2 min, see below):
+await setupPlayer({ retry: true })
+
+// Or bound it yourself:
+await setupPlayer({
+  retry: {
+    maxRetries: 5,
+    maxRetryDurationMs: 60_000,
+    firstConnectMaxRetryDurationMs: 8_000
+  }
+})
+```
+
+Which failures qualify is nearly the same on iOS and Android: HTTP 408 and
+429, plus server errors — every 5xx on iOS, the common four (500, 502, 503, 504) on Android; transport failures (DNS, timeouts, a dropped connection);
+and anything the platform couldn't classify, which is assumed transient
+rather than fatal.
+Permanent failures are never retried — 403 / 404, and media that can't be
+parsed or decoded.
+
+### Two duration budgets
+
+Retry state is tracked per **load** — one track's playback session, created
+when a track becomes current (selection, queue advance, skip) _or restarted
+from a terminal error_ (`retry()`, or any play command while in `'error'`),
+and surviving every automatic retry of that track. A new load starts fresh
+budgets; retries within it don't.
+
+How long the player keeps trying depends on one piece of evidence: **has this
+load ever produced audio?**
+
+| Situation                                     | Budget                                            | Why                                                                                                                                                               |
+| --------------------------------------------- | ------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **First connect** — the load has never played | `firstConnectMaxRetryDurationMs`, default **12s** | A stream that fails before ever playing is usually dead, and the listener is actively waiting for a verdict — seconds, not minutes.                               |
+| **Recovery** — the load played, then failed   | `maxRetryDurationMs`, default **2 min**           | Playback proved the stream works. Drops are usually transient (tunnels, network handovers, a station's encoder restarting) and patience recovers them unattended. |
+
+While the device is **offline**, the first-connect budget does not apply: the
+player parks and retries the moment connectivity returns, so a stream started
+in a tunnel still plays when the network comes back. Any offline observation
+resets the first-connect clock entirely — after restoration the load gets
+another full first-connect window, because the clock only ever measures a
+contiguous online stretch. `maxRetryDurationMs` is different: it is a
+wall-clock ceiling that **includes** offline time, deliberately — it exists so
+playback can't surprise the listener by resuming after a long time offline.
+
+`maxRetries` additionally caps the retry attempts of a load, counted across
+both budgets and across offline/online transitions. (One Android caveat: for
+segmented formats like HLS, ExoPlayer counts attempts per internal loadable —
+playlist and segments separately — so an attempt cap is less predictable there;
+prefer the duration budgets as the bound you rely on.)
+
+Backoff delays grow `1s → 1.5s → 2.3s → 3.4s → 5s` (capped). Once a budget is
+exhausted the state lands on `'error'`, where your `PlaybackErrorView` and
+[`retry()`](#manual-retry) take over. Restarting from `'error'` — via
+`retry()` or any play command — begins a **new load** of the same track:
+fresh budgets, starting with the first-connect one. The tap behaves exactly
+like re-selecting the track.
+
+### Errors while retrying
+
+While the retry loop is working, the player doesn't go silent: each failure is
+classified and surfaced immediately through
+[`onPlaybackChanged`](/api/features/playback/#onplaybackchanged) /
+[`usePlayback()`](/guide/playback#playback-state), attached to the current
+non-terminal state (`'loading'` / `'buffering'`, or `'paused'`) with
+`retrying: true`. Show it as advisory — the cause over a spinner — because the
+next attempt may still succeed:
+
+```tsx
+const { state, error } = usePlayback()
+
+if (error?.retrying) {
+  // Still trying: provisional copy, keep the spinner.
+} else if (state === 'error') {
+  // Gave up: final copy, offer retry().
+}
+```
+
+`onPlaybackError` and `usePlaybackError()` stay **terminal-only**: they fire on
+_both_ edges of the `'error'` state — entering it (with the error) and leaving
+it (with `error: undefined`; the hook returns `undefined` again). Advisory
+errors never pass through them. The same advisory error also reaches the
+[Now Playing formatter](/guide/now-playing#the-formatter-derived-continuous),
+so the lock screen and the car can show it too.
+
+Advisory emissions are deduplicated by **classification** (`kind`, plus the
+HTTP status when there is one) — never by the raw native `message`. The scope
+is the current advisory episode: consecutive identical failures within one
+retry sequence produce a single event rather than one per backoff tick, and the
+dedupe resets once the advisory clears (recovery, track change, or hardening
+into the terminal error).
+
+## Navigation errors
+
+When resolving a browse path fails, a
+[`NavigationError`](/api/features/errors/#navigationerror) is produced. Read the
+raw error (with `code` and HTTP details) via
+[`useNavigationError()`](/api/features/errors/#usenavigationerror), or subscribe
+with `onNavigationError` / snapshot with `getNavigationError()`.
+
+`NavigationError` is `{ code, message, statusCode?, statusCodeSuccess? }`, where
+`code` is one of:
+
+| `code`                | Meaning                                                                                       |
+| --------------------- | --------------------------------------------------------------------------------------------- |
+| `'content-not-found'` | No route for the path, or the route returned no content (a config issue, not an HTTP 404).    |
+| `'network-error'`     | The request failed (connection error, timeout, no internet).                                  |
+| `'http-error'`        | Server returned non-2xx (or 2xx but parsing failed) — see `statusCode` / `statusCodeSuccess`. |
+| `'callback-error'`    | Your browse callback returned an error (e.g. auth/subscription required).                     |
+| `'empty-content'`     | The path resolved but the page has no tracks (empty Favorites, no search results).            |
+| `'timeout'`           | Resolution didn't finish in time.                                                             |
+| `'unknown-error'`     | An unexpected error (e.g. invalid configuration).                                             |
+
+### Showing navigation errors
+
+For display, prefer
+[`useFormattedNavigationError()`](/api/features/errors/#useformattednavigationerror)
+— it returns a ready-to-show [`FormattedNavigationError`](/api/features/errors/#formattednavigationerror)
+(`{ title, message? }`). The **same** formatted error drives the CarPlay and
+Android Auto error dialogs, so your in-app and in-car messages stay consistent:
+
+```tsx
+import { Text } from 'react-native'
+import { useFormattedNavigationError } from 'react-native-audio-browser'
+
+function BrowseError() {
+  const error = useFormattedNavigationError()
+  if (!error) return null
+  const detail = error.message ? ` — ${error.message}` : ''
+  return (
+    <Text>
+      {error.title}
+      {detail}
+    </Text>
+  )
+}
+```
+
+Without configuration you get sensible English defaults. To localize or override
+specific cases, set `formatNavigationError` in
+[`configureBrowser`](/guide/browser) — return `defaultFormatted` for the cases
+you don't want to change:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+configureBrowser({
+  formatNavigationError: ({ error, defaultFormatted, path }) => {
+    if (error.code === 'http-error') {
+      return {
+        title: 'Server error',
+        message: `Request failed (${error.statusCode})`
+      }
+    }
+    return defaultFormatted // keep the default for everything else
+  }
+  // ...tabs, routes
+})
+```
+
+Use the raw `useNavigationError()` when you need to branch on `code` /
+`statusCode`; use `useFormattedNavigationError()` when you just need a title and
+message to render.
+
+## API summary
+
+| API                                                               | Purpose                                                                                                                                             |
+| ----------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `usePlaybackError()` / `getPlaybackError()`                       | The current playback error (`{ kind, code, message, statusCode?, retrying? }`) — branch on `kind`.                                                  |
+| `onPlaybackError`                                                 | Subscribe to terminal playback errors outside React (fires on entering/leaving `'error'`; advisory retrying errors arrive via `onPlaybackChanged`). |
+| `retry()`                                                         | Re-attempt the current item (while state is `'error'`).                                                                                             |
+| `setupPlayer({ retry })`                                          | Automatic retry with two duration budgets: first-connect (12s) and recovery (2 min). Off by default.                                                |
+| `useNavigationError()` / `getNavigationError()`                   | The raw navigation error (`code`, `statusCode`, …).                                                                                                 |
+| `onNavigationError`                                               | Subscribe to navigation errors outside React.                                                                                                       |
+| `useFormattedNavigationError()` / `getFormattedNavigationError()` | Display-ready `{ title, message? }`, shared with CarPlay / Android Auto.                                                                            |
+| `configureBrowser({ formatNavigationError })`                     | Customize / localize the formatted messages.                                                                                                        |

package/website/guide/favorites.md

@@ -0,0 +1,154 @@
+---
+description: 'Let listeners heart the active track from the now-playing screen, notification, CarPlay, and Android Auto, and surface a Favorites tab and voice command.'
+---
+
+# Favorites
+
+**Favorites** let a listener mark the active track with a heart — on the now-playing screen, the notification, CarPlay, and Android Auto — and let you surface a "Favorites" tab and a "play my favorites" voice command. The library tracks favorite _state_ (which track is favorited, and keeping the heart in sync everywhere); **your app owns the collection** (where favorites are stored and how they persist).
+
+## Enabling favorites
+
+Favoriting is off until you enable the `favorite` capability in `setupPlayer` (or `updateOptions`):
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+await setupPlayer({
+  capabilities: { favorite: true }
+})
+```
+
+The identifiers you pass to [`setFavorites`](#hydrating-favorite-state) are compared against each track's **identity**: its `id` when set, falling back to its `src`. Store the same stable identifier you put in `Track.id` — or, for tracks without ids, the full `src`:
+
+```ts
+import { setFavorites } from 'react-native-audio-browser'
+
+// track = { id: 'abc123', src: 'https://stream.example.com/jazz.mp3' }
+setFavorites(['abc123']) // matches by id
+
+// id-less track = { src: 'https://stream.example.com/jazz.mp3' }
+setFavorites(['https://stream.example.com/jazz.mp3']) // matches by src
+```
+
+## Hydrating favorite state
+
+The library keeps a native cache of which tracks are favorited, so it paints hearts across browse rows and the Now Playing heart without a round-trip to JS — and **without your content API having to know which tracks are favorites**. Declare your favorites once with `setFavorites`; the library stamps `favorited` on any track whose [identity](#enabling-favorites) matches, wherever that track appears. Your content endpoints stay favorites-agnostic — they return the same tracks for everyone, and favorite state lives entirely in your app/user storage.
+
+```ts
+import { setFavorites } from 'react-native-audio-browser'
+
+// string[] of track identities: ids, or src URLs for id-less tracks
+const favorites = await loadFavoritesFromStorage()
+setFavorites(favorites)
+```
+
+You only need `setFavorites` for the initial hydrate. After that, taps on the system heart and calls to [`setActiveTrackFavorited`](#favoriting-from-your-own-ui) update the cache for you.
+
+Your API can also return `favorited: true` on a track directly. A caller-set flag always wins over hydration for display — the library never overwrites it — but it does **not** fill the favorites cache: it only affects the response it arrived in, so other appearances of the same track stay unhearted. Treat `setFavorites` as the source of truth, and server-supplied `favorited` as a per-response display override.
+
+## Favoriting from system controls
+
+With the capability enabled, a heart appears on the now-playing surfaces. Add it to the Android notification and the CarPlay now-playing screen explicitly:
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+await setupPlayer({
+  capabilities: { favorite: true },
+  android: {
+    remoteButtonLayout: {
+      back: 'skip-to-previous',
+      forward: 'skip-to-next',
+      overflow: ['favorite']
+    }
+  },
+  ios: { carPlayNowPlayingButtons: ['favorite'] }
+})
+```
+
+When the listener taps a system heart, the library updates its cache and the UI, then emits `onFavoriteChanged` so **you can persist the change** to your storage or backend:
+
+```ts
+import { onFavoriteChanged } from 'react-native-audio-browser'
+
+const unsubscribe = onFavoriteChanged.addListener(({ track, favorited }) => {
+  if (favorited) addToFavorites(track)
+  else removeFromFavorites(track)
+})
+```
+
+The native side has already updated the now-playing heart by the time this fires, so your handler just persists the change — then refreshes the rest (see [Keep it in sync](#keep-it-in-sync)).
+
+## Favoriting from your own UI
+
+To drive favoriting from an in-app button (rather than a system control), set or toggle the active track's state directly. These update the same cache and system hearts:
+
+```ts
+import {
+  setActiveTrackFavorited,
+  toggleActiveTrackFavorited
+} from 'react-native-audio-browser'
+
+setActiveTrackFavorited(true)
+toggleActiveTrackFavorited()
+```
+
+These are the programmatic counterpart to a system heart tap — persist the result yourself, the same way you would in `onFavoriteChanged`.
+
+## Surfacing favorites
+
+How you surface favorites in your [browse tree](/guide/basic-usage) is up to you — a top-level tab, a nested entry, or a group within a larger list. Whatever the placement, point its route at the listener's favorited tracks:
+
+```ts
+import { configureBrowser } from 'react-native-audio-browser'
+
+configureBrowser({
+  tabs: [
+    { title: 'Browse', path: '/browse' },
+    { title: 'Favorites', path: '/favorites' }
+  ],
+  routes: {
+    '/favorites': async () => ({
+      path: '/favorites',
+      title: 'Favorites',
+      // your stored favorites, as a Track[]
+      children: await loadFavoriteTracks()
+    })
+  }
+})
+```
+
+Resolve it however your collection lives — from local storage, or from your API (with an HTTP route that posts your stored identifiers). It renders natively on CarPlay and Android Auto like any other browse content.
+
+### Keep it in sync
+
+The library caches each browse route, so the `/favorites` route keeps showing its old contents until you tell it to re-fetch. **Whenever the favorites collection changes** — a system heart tap, your own UI, or a sync from another device — do two things:
+
+```ts
+import { setFavorites, notifyContentChanged } from 'react-native-audio-browser'
+
+// refresh the hearts (favorited flag)
+setFavorites(updatedIds)
+// re-fetch the /favorites content
+notifyContentChanged('/favorites')
+```
+
+These hit two different caches: `setFavorites` updates the `favorited` flag wherever a track appears, while [`notifyContentChanged(path)`](/api/) re-runs the route handler for that one path and refreshes any surface currently showing it. (Use `invalidateAllContent()` instead only when _everything_ should re-fetch — e.g. a locale switch or sign-out.) Driving both from a single place that observes your favorites list — rather than from each individual toggle — keeps every source of change covered.
+
+## Searching within favorites
+
+Voice intents can target the favorites collection — both "play my favorites" and a scoped search like "play my jazz". These arrive at your `search` source with `reference: 'my'`. See [Search → Playing the user's own collection](/guide/search#playing-the-users-own-collection) for how to resolve them against a local or server collection.
+
+## API summary
+
+| API                                                              | Purpose                                                                                                                                                             |
+| ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `capabilities: { favorite: true }`                               | Enable favoriting and the system hearts.                                                                                                                            |
+| `setFavorites(ids)`                                              | Hydrate the favorites cache; ids match each track's identity (`id`, falling back to `src`).                                                                         |
+| `track.favorited`                                                | Per-track display flag; a caller-set value wins over hydration but does not fill the cache.                                                                         |
+| `setActiveTrackFavorited(bool)` / `toggleActiveTrackFavorited()` | Favorite the active track from your own UI.                                                                                                                         |
+| `onFavoriteChanged`                                              | Subscribe to system heart taps to persist the change.                                                                                                               |
+| `notifyContentChanged('/favorites')`                             | Re-fetch the `/favorites` content after the collection changes.                                                                                                     |
+| `'favorite'` in `android.remoteButtonLayout`                     | Heart in the Android notification, Android Auto, and the system media controls. A layout replaces the defaults wholesale, so list the other buttons you still want. |
+| `ios.carPlayNowPlayingButtons: ['favorite']`                     | Heart on the CarPlay now-playing screen.                                                                                                                            |
+| `search` source with `reference: 'my'`                           | Resolve "play my favorites" / favorites search.                                                                                                                     |

package/website/guide/gate.md

@@ -0,0 +1,143 @@
+---
+description: 'Block premium, login-only, or region-locked content on CarPlay and Android Auto with a short message — without touching your in-app UI or interrupting playback.'
+---
+
+# Gate
+
+When part of your catalog is premium, login-only, or region-locked, you need a way to block it on the car surfaces — without building a separate UI for them. That's what a **Gate** is: you hand the library a short message, and it shows that in place of the browse content on **CarPlay** and **Android Auto**, and can turn away voice searches.
+
+One rule worth keeping in mind: **a Gate blocks _finding_, never _hearing_.** Whatever is already playing keeps going, "resume" and "play this" still work by voice, and the queue and now-playing are left alone.
+
+Two things it never touches:
+
+- **Your own in-app browse UI.** The Gate only covers content the _library_ serves; the screens you draw in your app are yours to gate with your own paywall.
+- **Playback.** It lives on the find/resolve path, so audio is never interrupted.
+
+It follows that the Gate is **iOS and Android only**. On web `setGate` and `clearGate` are no-ops and `onGate` never fires — there's no CarPlay or Android Auto surface to cover, and in-app browse UI was never the Gate's job on any platform. Calling them from shared code is safe and does nothing.
+
+::: warning Voice search isn't only a "car" thing
+A Siri request ("Hey Siri, play jazz on App") can come from the phone or lock screen, not just CarPlay — and it still goes through the Gate. That's why the common setup below **gates browsing but lets search through**: voice-play keeps working everywhere, while the car's browse tabs stay walled off.
+:::
+
+## Setting a gate
+
+```ts
+import { setGate, clearGate } from 'react-native-audio-browser'
+
+setGate({ title: 'Premium', message: 'Subscribe to browse in the car.' })
+// …later, when the user is entitled:
+clearGate()
+```
+
+[`setGate`](/api/features/gate/#setgate) raises the gate (or updates it in place); [`clearGate`](/api/features/gate/#cleargate) drops it and the real content returns. Set it before the car connects and it'll be there the moment it does. A gate is global and singular — calling `setGate` again replaces the current one.
+
+A Gate is **independent** of `setupPlayer` and `configureBrowser` — call `setGate` any time after import. The usual lifecycle is: set it once at startup, then `clearGate` (or re-`setGate`) whenever the user's entitlement changes (purchase, login, logout).
+
+A gate is just a title and an optional message. How it renders depends on the surface:
+
+- **CarPlay** — a full-page centered message.
+- **Android Auto** — one non-playable list tile: the **title** as its main line, the **message** as the subtitle (newlines collapse to spaces). It's a tile, not a full page like CarPlay, so keep both short.
+
+There's no action button: Android Auto can't show one, and a car surface can't run a purchase flow anyway (see [Reacting to gate hits](#reacting-to-gate-hits) for the deferred-upsell pattern).
+
+::: warning Updating a live gate resets CarPlay navigation
+Calling `setGate` while a gate is already up replaces it in place — but on CarPlay it pops any drilled-in navigation back to the tab root. Harmless for a set-once gate; worth knowing if you update the message mid-session.
+:::
+
+## Gating some requests, not others
+
+Pass a [**resolver**](/api/features/gate/#gateresolver) as the second argument. The library calls it for every browse navigation and every search, and your return value decides what happens:
+
+- return **`false`** — let the request through
+- return **`true`** — gate it with the default message (the first `setGate` argument)
+- return a [**gate object**](/api/features/gate/#gate) `{ title, message? }` — gate it with a different message, just for this one
+
+The [request](/api/features/gate/#gaterequest) tells you what's being asked: `request.kind` is `'browse'` or `'search'`. A browse request carries a `request.path`; a search request carries `request.params` (the parsed query — see the [Search](/guide/search) guide).
+
+The common case — **gate browsing, but leave search open** — so users can still play by voice:
+
+```ts
+setGate(
+  { title: 'Premium', message: 'Subscribe to browse in the car.' },
+  (request) => request.kind === 'browse'
+)
+```
+
+::: warning The resolver is synchronous
+A resolver returns `Gate | boolean` — never a Promise — so you can't `await` an auth check inside it. Rather than check entitlement in the resolver, drive the gate from a single place: gate while locked, `clearGate` once entitled.
+
+```ts
+const gateBrowsing = () =>
+  setGate(
+    { title: 'Premium', message: 'Subscribe to browse in the car.' },
+    (request) => request.kind === 'browse' // gate browse, allow search
+  )
+
+if (!isEntitled()) gateBrowsing() // your code, at startup
+
+// entitlement changed (purchase / login / logout):
+function onEntitlementChange(entitled: boolean) {
+  entitled ? clearGate() : gateBrowsing() // refresh the car surfaces
+}
+```
+
+:::
+
+Because the resolver sees the request, you can also gate by path — block one premium branch while the rest stays open — or show a different message per request:
+
+```ts
+setGate({ title: 'Premium', message: 'Subscribe to unlock.' }, (request) => {
+  if (request.kind === 'search') return false // search allowed
+  if (request.path.startsWith('/premium')) return true // gate this branch
+  return false // everything else
+})
+```
+
+A search request carries `request.params` — the parsed query (`query`, `genre`, `artist`, … — see [Search](/guide/search)) — so you can gate only premium queries:
+
+```ts
+setGate({ title: 'Premium', message: 'Subscribe to unlock.' }, (request) => {
+  if (request.kind === 'search') {
+    return request.params.genre === 'premium' // gate premium genres
+  }
+  return request.path.startsWith('/premium')
+})
+```
+
+You can also pass **only** a resolver, with no default message — return a gate object for full control, or `true` to fall back to the generic built-in chrome. That fallback is a title only (`"Unavailable"`, no body), so on CarPlay its message area is blank — pass a default gate or return a gate object if you want body copy.
+
+```ts
+setGate((request) => request.kind === 'browse')
+```
+
+If the resolver throws, the gate **fails closed** — the library gates the request rather than leak content. A deliberate `return false` is the only thing that lets a request through.
+
+## Reacting to gate hits
+
+You can't complete a purchase on CarPlay or Android Auto — so the pattern is to **record** that a user bumped into the gate and surface the upsell next time your phone app opens. Subscribe to [`onGate`](/api/features/gate/#ongate):
+
+```ts
+import { onGate } from 'react-native-audio-browser'
+
+// addListener returns an unsubscribe function — keep it and call it to
+// clean up.
+const unsubscribe = onGate.addListener((event) => {
+  // event.reason ('browse' | 'search') is the same axis as the resolver's
+  // request.kind. The event carries only the reason, not the path/params.
+  recordGateHit() // your own persisted flag
+})
+```
+
+In a component, wire it through `useEffect` so it unsubscribes on unmount:
+
+```tsx
+useEffect(() => onGate.addListener((event) => recordGateHit()), [])
+```
+
+`onGate` fires **once per gated serve**, whether the gate is static or resolver-driven. There's no de-duplication, so poking around a gated car UI fires several events — debounce on your side (once per session, per day, whatever fits) if you don't want them all.
+
+Then, on your next app launch, read the flag and show the upsell:
+
+```ts
+if (consumeGateHit()) showPremiumUpsell() // your code: read + clear flag
+```

package/website/guide/getting-started.md

@@ -0,0 +1,46 @@
+---
+description: 'Install react-native-audio-browser and its react-native-nitro-modules peer dependency, then complete the iOS and Android native setup.'
+---
+
+# Getting Started
+
+## Installation
+
+The library requires **React Native 0.76 or newer** (with the New Architecture enabled) and React 18.2+. `react-native-nitro-modules` is a required peer dependency — install it alongside:
+
+::: code-group
+
+```bash [npm]
+npm install react-native-audio-browser react-native-nitro-modules
+```
+
+```bash [yarn]
+yarn add react-native-audio-browser react-native-nitro-modules
+```
+
+```bash [pnpm]
+pnpm add react-native-audio-browser react-native-nitro-modules
+```
+
+```bash [bun]
+bun add react-native-audio-browser react-native-nitro-modules
+```
+
+:::
+
+## Basic Setup
+
+```ts
+import { setupPlayer } from 'react-native-audio-browser'
+
+// Initialize the player once at startup
+await setupPlayer()
+```
+
+> The library exposes both named exports (`import { setupPlayer }`) and a default namespace (`import AudioBrowser from '…'; AudioBrowser.setupPlayer()`). The guides use the named form throughout.
+
+## Next Steps
+
+- [Basic Usage](/guide/basic-usage) - Learn how to play audio and build navigation trees
+- [Android Auto](/guide/android-auto) - Set up Android Auto integration
+- [CarPlay](/guide/carplay) - Set up CarPlay integration