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

package/website/guide/sleep-timer.md

@@ -0,0 +1,268 @@
+---
+description: 'Stop playback after a fixed time or at the end of the current track, counted down natively so it fires with the app backgrounded or the screen off.'
+---
+
+# Sleep Timer
+
+A **sleep timer** stops playback on its own after a set time — the classic
+"fall asleep to the radio" feature. The library runs the timer natively, so it
+keeps counting down and fires even when your app is backgrounded or the screen
+is off. There are two kinds:
+
+- **Time-based** — pause after a fixed number of seconds (e.g. "in 30 minutes").
+- **End of track** — pause when the current track finishes playing.
+
+Only one timer is active at a time; setting a new one replaces the old.
+
+## Setting a timer
+
+Call `setSleepTimer` with a duration in **seconds**. This example stops playback
+after 30 minutes:
+
+```ts
+import { setSleepTimer } from 'react-native-audio-browser'
+
+setSleepTimer(30 * 60)
+```
+
+Most UIs offer a few presets rather than a free-form duration — multiply the
+minutes you show by 60:
+
+```ts
+const PRESETS_MINUTES = [15, 30, 45, 60]
+
+setSleepTimer(PRESETS_MINUTES[1] * 60) // 30 minutes
+```
+
+To pause when the current track ends instead of after a fixed time, use
+`setSleepTimerToEndOfTrack`:
+
+```ts
+import { setSleepTimerToEndOfTrack } from 'react-native-audio-browser'
+
+setSleepTimerToEndOfTrack()
+```
+
+When the timer completes, the library **pauses** playback (it doesn't stop or
+tear the player down). Pressing play resumes as normal.
+
+## Fading out
+
+Pass a `fadeDuration` (in seconds) to ramp the volume down to silence as the
+timer runs out — a gentler finish than an abrupt pause:
+
+```ts
+// Stop in 30 minutes, fading the last 20 seconds to silence.
+setSleepTimer(30 * 60, { fadeDuration: 20 })
+```
+
+The fade always ends exactly at the deadline (if `fadeDuration` is longer than
+the timer itself, it's clamped to the timer's length). Once playback pauses, the
+library restores the pre-fade volume, so the next time the listener hits play it
+starts at normal loudness.
+
+During the fade the timer takes priority: seeking or skipping plays into the
+remaining ramp rather than cancelling it. Only pausing, or clearing/replacing
+the timer, stops the fade. The countdown keeps ticking throughout, so you can
+show a "fading out" hint once `secondsLeft` drops to `fadeDuration` (see the
+[complete example](#a-complete-screen)).
+
+## Clearing a timer
+
+`clearSleepTimer` cancels the active timer. It returns `true` if a timer was
+actually cleared, or `false` if none was set:
+
+```ts
+import { clearSleepTimer } from 'react-native-audio-browser'
+
+clearSleepTimer()
+```
+
+## Reading the timer in your UI
+
+Use the `useSleepTimer` hook to show a live countdown. It re-renders every
+second and returns:
+
+- For a time-based timer: `{ time, secondsLeft }`, where `time` is the deadline
+  (epoch milliseconds) and `secondsLeft` counts down to `0`.
+- For an end-of-track timer: `{ sleepWhenPlayedToEnd: true }`.
+- `undefined` when no timer is active.
+
+```tsx
+import { useSleepTimer } from 'react-native-audio-browser'
+
+function SleepTimerLabel() {
+  const timer = useSleepTimer()
+
+  if (!timer) return <Text>No sleep timer</Text>
+  if ('sleepWhenPlayedToEnd' in timer) {
+    return <Text>Stopping at end of track</Text>
+  }
+
+  const minutes = Math.floor(timer.secondsLeft / 60)
+  const seconds = timer.secondsLeft % 60
+  return (
+    <Text>
+      Sleeping in {minutes}m {seconds}s
+    </Text>
+  )
+}
+```
+
+The countdown only ticks while the app is in the foreground — `secondsLeft`
+doesn't advance in the background (the native timer still fires on time
+regardless). The only reason to care is to avoid pointless per-second re-renders
+while backgrounded: derive the `inactive` flag from React Native's `AppState`
+and pass it in. You can also tune the refresh rate with `updateInterval`
+(milliseconds, default `1000`):
+
+```tsx
+import { useEffect, useState } from 'react'
+import { AppState } from 'react-native'
+import { useSleepTimer } from 'react-native-audio-browser'
+
+function useAppInactive() {
+  const [inactive, setInactive] = useState(
+    () => AppState.currentState !== 'active'
+  )
+  useEffect(() => {
+    const sub = AppState.addEventListener('change', (state) =>
+      setInactive(state !== 'active')
+    )
+    return () => sub.remove()
+  }, [])
+  return inactive
+}
+
+// In a component: pause the countdown updates while backgrounded.
+const timer = useSleepTimer({ inactive: useAppInactive() })
+```
+
+### Just need to know if one is set?
+
+If you only want to toggle a button's appearance, `useSleepTimerActive` is a
+lighter-weight hook that returns a boolean and doesn't re-render every second:
+
+```tsx
+import { useSleepTimerActive } from 'react-native-audio-browser'
+
+function SleepTimerButton() {
+  const active = useSleepTimerActive()
+  return <Icon name={active ? 'timer-on' : 'timer-off'} />
+}
+```
+
+## A complete screen
+
+Putting it together — preset durations, an end-of-track option, an off button,
+and a live countdown that switches to a "fading out" hint as the fade begins:
+
+```tsx
+import { View, Button, Text } from 'react-native'
+import {
+  setSleepTimer,
+  setSleepTimerToEndOfTrack,
+  clearSleepTimer,
+  useSleepTimer
+} from 'react-native-audio-browser'
+
+const PRESETS_MINUTES = [15, 30, 45, 60]
+const FADE_SECONDS = 20
+
+function SleepTimerScreen() {
+  const timer = useSleepTimer()
+
+  return (
+    <View>
+      {PRESETS_MINUTES.map((minutes) => (
+        <Button
+          key={minutes}
+          title={`${minutes} min`}
+          onPress={() =>
+            setSleepTimer(minutes * 60, { fadeDuration: FADE_SECONDS })
+          }
+        />
+      ))}
+      <Button
+        title="End of track"
+        onPress={() => setSleepTimerToEndOfTrack()}
+      />
+      <Button title="Off" onPress={() => clearSleepTimer()} />
+
+      <Status timer={timer} fadeSeconds={FADE_SECONDS} />
+    </View>
+  )
+}
+
+function Status(props: {
+  timer: ReturnType<typeof useSleepTimer>
+  fadeSeconds: number
+}) {
+  const { timer, fadeSeconds } = props
+  if (!timer) return <Text>No sleep timer</Text>
+  if ('sleepWhenPlayedToEnd' in timer) {
+    return <Text>Stopping at end of track</Text>
+  }
+  if (timer.secondsLeft <= fadeSeconds) return <Text>Fading out…</Text>
+
+  const minutes = Math.floor(timer.secondsLeft / 60)
+  const seconds = timer.secondsLeft % 60
+  return (
+    <Text>
+      Sleeping in {minutes}m {seconds}s
+    </Text>
+  )
+}
+```
+
+When the timer fires (or is cleared), `useSleepTimer` returns `undefined` and
+the countdown stops on its own — so `Status` falls back to "No sleep timer"
+without any extra handling on your part.
+
+## Outside of React
+
+If you're not in a component, read the current timer with `getSleepTimer` or
+subscribe to changes with `onSleepTimerChanged`. Note that `getSleepTimer`
+returns the raw timer state (`{ time }` in epoch milliseconds, or
+`{ sleepWhenPlayedToEnd }`, or `null`) — it doesn't compute `secondsLeft`; that
+convenience is added by the `useSleepTimer` hook.
+
+```ts
+import { getSleepTimer, onSleepTimerChanged } from 'react-native-audio-browser'
+
+getSleepTimer() // { time } | { sleepWhenPlayedToEnd } | null
+
+// addListener returns a cleanup function — call it to unsubscribe.
+const unsubscribe = onSleepTimerChanged.addListener((timer) => {
+  console.log('sleep timer is now', timer)
+})
+
+// later, when you no longer need updates:
+unsubscribe()
+```
+
+## Behavior and edge cases
+
+- **Setting replaces, it doesn't stack.** Calling any setter while a timer is
+  running swaps it for the new one — there's only ever a single active timer.
+- **Not persisted across launches.** The timer lives in memory. If the app is
+  killed (or the OS reclaims it), the timer is gone on next launch — it does not
+  resume. Persist your own "timer set at" value if you need to restore the UI.
+- **No input validation.** `seconds` is passed straight through to the native
+  scheduler, which isn't clamped — a value of `0` or a negative number fires
+  essentially immediately (pausing right away). Validate in your own UI if that
+  matters.
+- **Nothing throws.** Every function here is synchronous; the setters return
+  `void` and `clearSleepTimer` returns a boolean. No `try/catch` needed.
+
+## API summary
+
+| API                                             | Purpose                                                         |
+| ----------------------------------------------- | --------------------------------------------------------------- |
+| `setSleepTimer(seconds, { fadeDuration? })`     | Pause playback after `seconds`, optionally fading out.          |
+| `setSleepTimerToEndOfTrack()`                   | Pause when the current track finishes.                          |
+| `clearSleepTimer()`                             | Cancel the active timer; returns `true` if one was cleared.     |
+| `getSleepTimer()`                               | Read the raw timer state (no `secondsLeft`).                    |
+| `onSleepTimerChanged`                           | Subscribe to timer changes outside React; returns a cleanup fn. |
+| `useSleepTimer({ updateInterval?, inactive? })` | Live state with a `secondsLeft` countdown.                      |
+| `useSleepTimerActive()`                         | Boolean: is any timer set?                                      |

package/website/guide/track.md

@@ -0,0 +1,247 @@
+---
+description: 'The Track shape — the single unit of content: required fields, identity, metadata, and artwork, used for browse rows, queue items, and lock-screen metadata.'
+---
+
+# Track
+
+A **Track** is the one unit of content in the library. The same object describes a row in a browse list, an item in the playback queue, and the metadata on the lock screen — so once you know the Track shape, you can read and build content everywhere.
+
+A Track is just a plain object. The only required field is `title`, plus **at least one** of `path` (browsable) or `src` (playable):
+
+```ts
+const station: Track = {
+  title: 'Smooth Floret FM',
+  src: 'https://example.com/floret.mp3'
+}
+```
+
+A real track usually carries more — identity, metadata, and artwork:
+
+```ts
+const episode: Track = {
+  id: 'atp-545',
+  title: 'Episode 545',
+  artist: 'Accidental Tech Podcast',
+  album: 'ATP',
+  artwork: 'https://example.com/atp.jpg',
+  duration: 7200,
+  src: 'https://example.com/atp/545.mp3'
+}
+```
+
+This guide is the field-by-field reference. For _where_ tracks come from (routes, callbacks, HTTP) see the [Browser](/guide/browser) guide.
+
+## Browsable, playable, or both
+
+Two fields decide what a Track _does_. A Track must set at least one of them, and may set both:
+
+| Field  | Makes the track | Effect                                               |
+| ------ | --------------- | ---------------------------------------------------- |
+| `path` | **browsable**   | a container — tapping it navigates into its children |
+| `src`  | **playable**    | a leaf — the player can stream it                    |
+
+```ts
+// Browsable: a folder you navigate into
+{ title: 'Jazz', path: '/browse/jazz' }
+
+// Playable: a station you stream
+{ title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' }
+
+// Both: a podcast episode you can open *and* play
+{ title: 'Episode 42', path: '/episodes/42', src: 'https://…/42.mp3' }
+```
+
+`src` is usually an absolute audio URL, but it can be any string — a file path or your own identifier — that you turn into a real request in `media.resolve` (see [Browser → Media and artwork](/guide/browser#media-and-artwork)).
+
+## Identity: `id`
+
+`id` is an **opaque, stable identifier** you control. The library never parses it — it round-trips verbatim through `setQueue`, the queue, `getActiveTrack`, and `onActiveTrackChanged`.
+
+Why it matters: when playback moves by an _external_ control — a lock-screen / CarPlay / Android Auto / Bluetooth next-or-previous — you find out which of _your_ items became active by matching its `id`, without re-parsing the `src`:
+
+```ts
+// the callback gets a PlaybackActiveTrackChangedEvent — use event.track
+const unsubscribe = onActiveTrackChanged.addListener((event) => {
+  const episode = myEpisodes.find((e) => e.id === event.track?.id)
+  // …update your UI for `episode`
+})
+```
+
+The event also carries `index`, `lastTrack`, and `lastIndex`; `addListener` returns an unsubscribe function.
+
+`id` is also passed to the per-track `resolve` hooks, so you can set `src` to the same stable identifier and synthesise the real request/artwork from it at request time.
+
+::: tip `id` is optional
+A track's identity is its `id`, falling back to `src` — so if the same item's `src` string is identical wherever it appears, you can skip `id` entirely. Set ids consistently across your content or not at all: identity is compared whole, and a row carrying an `id` never matches a track without one.
+:::
+
+## Display fields
+
+These set the text shown across surfaces. Only `title` is required.
+
+| Field                   | Shown where                                                                  |
+| ----------------------- | ---------------------------------------------------------------------------- |
+| `title`                 | primary line — browse rows **and** now-playing (required)                    |
+| `subtitle`              | secondary line in **browse lists** only                                      |
+| `artist`                | secondary line on **now-playing / lock screen**; the head-unit "artist" slot |
+| `album`                 | album name (and gates the tappable album line — see `albumPath`)             |
+| `genre` / `description` | extra metadata                                                               |
+| `duration`              | catalog metadata in seconds, for your UI                                     |
+
+::: warning `subtitle` and `artist` are separate — neither falls back to the other
+`subtitle` drives browse-list rows; `artist` drives the now-playing line and Bluetooth metadata. Set each one for the surface you want it on.
+:::
+
+`duration` is **catalog metadata only** (e.g. an episode list) — it does _not_ drive the now-playing scrubber. Every surface derives elapsed/remaining from the player itself.
+
+## Artwork
+
+Set `artwork` to an image URL. It's transformed through your [artwork configuration](/guide/browser#media-and-artwork) and the ready-to-render result comes back on the **output-only** `artworkSource`, shaped for React Native's `<Image>`:
+
+```tsx
+<Image source={track.artworkSource} />
+```
+
+Don't set `artworkSource` yourself — the library populates it.
+
+**SF Symbols (iOS).** Prefix `artwork` with `sf:` to use a system symbol, with optional colors — `bg` (background, transparent if omitted) and `fg` (symbol, black if omitted):
+
+```ts
+{
+  title: 'Favorites',
+  path: '/favorites',
+  artwork: 'sf:heart.fill?bg=#FF0090&fg=#fff'
+}
+```
+
+On CarPlay, an SF Symbol with no explicit colors adapts to light/dark mode automatically.
+
+**Tinting (`style: { artworkRendering: 'stencil' }`).** For monochrome icons, declare this so CarPlay tints them per appearance — black in light mode, white in dark. Use it for icons, not full-color album art. iOS CarPlay only; Android Auto is dark-only, so ship appropriately-colored (e.g. white) icons there. On Android, an `android.resource://…` artwork URI combines with any declared `display` the library forwards to select Android Auto's icon treatment of that layout (icon margins + system tinting for vector drawables).
+
+**Light and dark images.** When the appearances need genuinely different artwork rather than the same shape recolored, set `artwork` to an [`ArtworkVariants`](/api/types/browser-nodes/#artworkvariants) pair — `{ light, dark }`. CarPlay adapts between them in place; everywhere that needs a single image uses `dark`. See [Artwork → Light and dark](/guide/artwork#light-and-dark-artwork).
+
+## Per-track request override
+
+[`request`](/api/types/browser-nodes/#trackrequest) is a **narrow** per-track override for _how_ this track's audio request is made — merged last, after the shared `request` and `media` layers:
+
+```ts
+{
+  title: 'Member Stream',
+  src: 'https://example.com/members/floret.mp3',
+  request: { headers: { authorization: 'Bearer …' } }
+}
+```
+
+It carries only `userAgent`, `headers`, and `query` — deliberately **not** `baseUrl` / `path` / `method` / `body`, so a track (often server-sourced) can customise _how_ it's fetched but can't repoint its own host or verb. Like every field, it round-trips verbatim through the queue.
+
+## Presentation on native surfaces
+
+Optional fields that change how a Track renders on CarPlay / Android Auto. Each surface applies the ones it supports; an unsupported field is a no-op, never an error.
+
+| Field                                      | Effect                                                                 | Platform                   |
+| ------------------------------------------ | ---------------------------------------------------------------------- | -------------------------- |
+| `style: { display: 'list' \| 'grid' }`     | on a browsable track: the layout of the page it opens                  | Android Auto / AAOS        |
+| `style: { artworkRendering: 'stencil' }`   | tint monochrome artwork to the surface appearance                      | CarPlay                    |
+| `style: { imageShape: 'circular' }`        | crop `'image'` and `'condensed'` tile artwork circular (people)        | CarPlay (iOS 26+)          |
+| `style: { accessorySymbol: '…' }`          | SF Symbol accessory; `'none'` restores the derived accessory           | CarPlay                    |
+| `style: { cardTint: '…', cardImage: '…' }` | card color and image mode, when the section renders `gridTile: 'card'` | CarPlay (iOS 26+)          |
+| `disabled`                                 | unavailable: never plays; grayed where drawable, hidden elsewhere      | all                        |
+| `favorited`                                | filled/empty heart (needs the `favorite` capability)                   | Android Auto, notification |
+| `live`                                     | a "live" indicator                                                     | iOS now-playing            |
+| `albumPath`                                | make the now-playing album line tappable                               | CarPlay                    |
+| `icyCharset`                               | decode ICY titles a station sends in a legacy code page                | iOS, Android               |
+
+A couple of constraints worth knowing:
+
+- **`display` goes on the browsable track as it appears in its parent's list** — Android Auto reads it there, before the page resolves, to decide how to lay out the page once you navigate in. It is only sent when you declare it — the library never infers it from the page's content. The drilled-into page's own sections override it per section via their `style`.
+- **`albumPath` requires `album`** (CarPlay renders the tappable line from album metadata), and pairs with `resolveAlbumPath` in the [Browser config](/guide/browser).
+
+```ts
+// This track as it appears in its parent's list (no children here — the
+// page supplies those): it declares the layout of the page it opens.
+{
+  path: '/genres',
+  title: 'Genres',
+  // the page this opens lays out as tiles in Android Auto
+  style: { display: 'grid' }
+}
+```
+
+## Sections — grouping and tile layouts
+
+A Track appears in two roles. As a **row** in its parent's list it's a handle: its own `style.display` only advertises the layout of the page it opens (see [above](#presentation-on-native-surfaces)). Once resolved, that same Track **is the page** — a [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack) — and that is when it carries `sections`.
+
+Headers and layout belong to the container role: declare them on the page's [`Section`](/api/types/browser-nodes/#section)s (`{ title?, subtitle?, style?, path?, children }`), never on the rows. A section groups tracks under a header, and its `style` block's `display` picks their layout: `'list'` rows (the default) or `'grid'` artwork tiles — wrapping unless `gridWrap: false` keeps them to a single line. The section's `path` is the navigation target for its header / "view all" surface; without one the header is a plain label, not a link — the section is self-contained.
+
+A tile with `src` **plays immediately on tap** (same selection path as a playable list row — a station app can make tiles play their station directly); otherwise its `path` is navigated. Tiles are ordinary Tracks, so playable ones carry the now-playing fields any track would (`id`, `artist`, `album`, `albumPath`, `live`, `request`). Tapping a playable child queues **its section** on every surface (see [Playback behavior](/guide/browser#playback-behavior)):
+
+```ts
+{
+  path: '/home',
+  title: 'Home',
+  sections: [
+    {
+      title: 'Featured',
+      style: { display: 'grid', gridWrap: false },
+      path: '/browse/featured', // header tap → the full list
+      children: [
+        { title: 'Jazz', path: '/browse/jazz', artwork: 'https://…/jazz.jpg' },
+        {
+          title: 'Beacon FM',
+          src: 'https://audio.example.com/beacon.mp3', // tap plays it
+          artist: 'Springfield',
+          live: true,
+          artwork: 'https://…/beacon.jpg'
+        }
+      ]
+    },
+    { title: 'All stations', children: [...] }
+  ]
+}
+```
+
+Each surface renders a declaration as its nearest supported form — CarPlay truncates a single-line grid (`gridWrap: false`) at the tiles that fit, Android Auto's grid always wraps, app UIs typically render a horizontal scroller — see [Browser → Presentation](/guide/browser#presentation) for the full rundown.
+
+## ResolvedTrack — a resolved page
+
+A [**`ResolvedTrack`**](/api/types/browser-nodes/#resolvedtrack) is the same Track plus its resolved content — the page the browser is currently showing. Its `path` is always present, and `sections` is the [`Section`](/api/types/browser-nodes/#section)`[]` to render (optional — a leaf page has none). A page authored with a plain `children` list resolves to a single untitled section: `children` is authoring sugar, never populated on resolved output — read `sections`.
+
+Navigation is **fire-and-forget**: `navigate(path)` returns `void`. Read the resolved page from `useContent()` (or `getContent()` / `onContentChanged`):
+
+```tsx
+import { navigate, useContent } from 'react-native-audio-browser'
+
+navigate('/browse/jazz') // moves the browser to this path
+
+function JazzPage() {
+  const page = useContent() // ResolvedTrack | undefined
+  // each section: { title?, style?, path?, children: Track[] }
+  return <List sections={page?.sections ?? []} /> // sections may be undefined
+}
+```
+
+A `ResolvedTrack` may also set [`carPlaySiriListButton`](/api/types/browser/#carplaysirilistbuttonposition)`: 'top' | 'bottom'` to show the "Ask Siri to Play" cell on that page (needs Siri wiring — see [CarPlay](/guide/carplay)).
+
+## Using tracks in your code
+
+Tracks flow through the queue and playback API. A minimal playable track needs just `title` + `src`:
+
+```ts
+import { setQueue, play, useActiveTrack } from 'react-native-audio-browser'
+
+setQueue([
+  { title: 'Smooth Floret FM', src: 'https://example.com/floret.mp3' },
+  { title: 'The Stalk 88.5', src: 'https://example.com/stalk.mp3' }
+])
+play()
+```
+
+`load(track)` plays a single track, `add(tracks)` appends to the queue, and `getActiveTrack()` / `useActiveTrack()` read what's playing now (with its `artworkSource` populated for your UI). See [Basic Usage](/guide/basic-usage) for the full queue and playback API.
+
+## Where to go next
+
+- **[Browser](/guide/browser)** — where tracks come from: tabs, routes, sources.
+- **[Now Playing](/guide/now-playing)** — how a track's fields drive the lock-screen / car metadata.
+- **[Favorites](/guide/favorites)** — the `favorited` field and the heart button.
+
+For the exact types — every field and its JSDoc — see [`Track`](/api/types/browser-nodes/#track) and [`ResolvedTrack`](/api/types/browser-nodes/#resolvedtrack) in the API reference.

package/ios/Bridge.h

@@ -1,8 +0,0 @@
-//
-//  Bridge.h
-//  audio-browser
-//
-//  Created by puckey on 10/12/2025
-//
-
-#pragma once

package/ios/Browser/MediaResolveComposer.swift

@@ -1,114 +0,0 @@
-import Foundation
-
-/// Pure, Nitro-free composition logic for the media `resolve` layer.
-///
-/// The two pieces that need testing in isolation from the Nitro bridge are:
-///  1. the variant unwrap — `resolve(track)` returns a `RequestConfig` either
-///     synchronously (`.first`) or via a `Promise` (`.second`); both arms must
-///     yield the same `RequestConfig`; and
-///  2. the merge — the resolved config is layered over the base with
-///     override-wins per field (and per-key dict merge for headers/query).
-///
-/// Production (`BrowserManager+URLResolution.swift`) builds the Nitro
-/// `RequestConfig` values and calls into `MediaResolveComposer.merge` /
-/// `.unwrap`; the SPM test target exercises the same functions against the
-/// stub `RequestConfigLike` value type. Keeping the logic here (rather than in
-/// the Nitro-only extension) is what makes it reachable from tests.
-enum MediaResolveComposer {
-  /// A minimal field set mirroring `RequestConfig`, used so the merge logic can
-  /// be expressed once and shared between the Nitro types and the test stub.
-  struct RequestConfigLike: Equatable {
-    var method: String?
-    var path: String?
-    var baseUrl: String?
-    var headers: [String: String]?
-    var query: [String: String]?
-    var body: String?
-    var contentType: String?
-    var userAgent: String?
-
-    init(
-      method: String? = nil,
-      path: String? = nil,
-      baseUrl: String? = nil,
-      headers: [String: String]? = nil,
-      query: [String: String]? = nil,
-      body: String? = nil,
-      contentType: String? = nil,
-      userAgent: String? = nil,
-    ) {
-      self.method = method
-      self.path = path
-      self.baseUrl = baseUrl
-      self.headers = headers
-      self.query = query
-      self.body = body
-      self.contentType = contentType
-      self.userAgent = userAgent
-    }
-  }
-
-  /// The unwrapped result of a `resolve(track)` variant.
-  enum ResolveVariant<Config> {
-    /// `.first` — a synchronous config.
-    case sync(Config)
-    /// `.second` — a config delivered via an async closure (a Promise in prod).
-    case async(() async throws -> Config)
-  }
-
-  /// Unwraps a sync/async config into a concrete config, awaiting the async arm
-  /// if needed. (Production no longer uses a Nitro variant — `resolve`/`resolveSync`
-  /// are separate fields — but this stays as a pure, testable composition helper.)
-  static func unwrap<Config>(_ variant: ResolveVariant<Config>) async throws -> Config {
-    switch variant {
-    case let .sync(config):
-      config
-    case let .async(makeConfig):
-      try await makeConfig()
-    }
-  }
-
-  /// Run-both resolve composition: the async-resolved config first, then the
-  /// sync-resolved merged over it (sync winning) via `combine`. `nil` when neither
-  /// produced a config. Generic so it is shared verbatim by production (Nitro
-  /// `RequestConfig` + `mergeRequestConfig`) and tests (`RequestConfigLike` +
-  /// `merge`) — one implementation, exercised on both sides.
-  static func composeResolved<C>(
-    async asyncResolved: C?,
-    sync syncResolved: C?,
-    combine: (C, C) -> C,
-  ) -> C? {
-    switch (asyncResolved, syncResolved) {
-    case (nil, nil): nil
-    case let (value?, nil): value
-    case let (nil, value?): value
-    case let (a?, s?): combine(a, s)
-    }
-  }
-
-  /// Override-wins per-field merge. Headers and query merge per-key (override
-  /// key wins). Matches `BrowserManager.mergeRequestConfig`.
-  static func merge(base: RequestConfigLike, override: RequestConfigLike) -> RequestConfigLike {
-    RequestConfigLike(
-      method: override.method ?? base.method,
-      path: override.path ?? base.path,
-      baseUrl: override.baseUrl ?? base.baseUrl,
-      headers: mergeDicts(base.headers, override.headers),
-      query: mergeDicts(base.query, override.query),
-      body: override.body ?? base.body,
-      contentType: override.contentType ?? base.contentType,
-      userAgent: override.userAgent ?? base.userAgent,
-    )
-  }
-
-  /// Per-key dict merge with override-wins; nil-safe (returns the non-nil side,
-  /// or nil when both are nil). Matches `BrowserManager.mergeDicts`.
-  static func mergeDicts(_ base: [String: String]?, _ override: [String: String]?) -> [String: String]? {
-    switch (base, override) {
-    case (nil, nil): nil
-    case let (base?, nil): base
-    case let (nil, override?): override
-    case let (base?, override?): base.merging(override) { _, new in new }
-    }
-  }
-}

package/ios/CarPlay/ImageRowItem+CarPlay.swift

@@ -1,19 +0,0 @@
-import Foundation
-import NitroModules
-
-// MARK: - ImageRowItem → Track Conversion
-
-extension ImageRowItem {
-  /// Creates a minimal Track from an ImageRowItem for reuse with item selection and artwork loading.
-  /// A `src`-bearing item becomes a playable track (thumbnail tap plays it); otherwise the
-  /// track only navigates via `url`.
-  func toTrack() -> Track {
-    Track(
-      id: id, url: url, src: src, artwork: artwork.map { .first($0) },
-      artworkSource: artworkSource, request: request,
-      artworkCarPlayTinted: nil, title: title, subtitle: nil, artist: artist,
-      albumUrl: albumUrl, album: album, description: nil, genre: nil, duration: nil, style: nil,
-      childrenStyle: nil, favorited: nil, groupTitle: nil, live: live, imageRow: nil,
-    )
-  }
-}