react-native-audio-browser 0.2.0-next.2 → 0.2.0-next.21

package/src/web/util/BrowserPathHelper.ts

@@ -6,8 +6,12 @@
  * 1. System paths (prefixed with `/__`): Root, recent, and search paths
  * 2. Contextual URLs: Embed parent context in track identifiers for Media3 integration
  *
- * Contextual URL format: `{parentPath}?__trackId={trackSrc}`
- * Example: "/library/radio?__trackId=song.mp3"
+ * Contextual URL format: `{parentPath}?__trackId={trackIdentity}&__index={childIndex}`
+ * Example: "/library/radio?__trackId=song.mp3&__index=2"
+ *
+ * `__trackId` is the identity check; `__index` (the child's position on the
+ * page at stamp time) is only a tie-breaker between surfaces that carry the
+ * same identity — a stale index never selects a different track.
  *
  * This allows:
  * - Media3 to reference playable-only tracks (tracks with `src` but no `url`)
@@ -21,6 +25,9 @@ export const BrowserPathHelper = {
   /** Query parameter name for contextual track identifiers */
   CONTEXTUAL_TRACK_PARAM: '__trackId',
 
+  /** Query parameter name for the tapped child's page position (tie-breaker) */
+  CONTEXTUAL_INDEX_PARAM: '__index',
+
   /**
    * Create a search path for a given query
    */
@@ -43,13 +50,13 @@ export const BrowserPathHelper = {
   },
 
   /**
-   * Strips the __trackId parameter from a contextual URL to get the parent path.
-   * If the URL is not contextual, returns it unchanged.
+   * Strips the contextual parameters (__trackId and __index) from a contextual
+   * URL to get the parent path. If the URL is not contextual, returns it unchanged.
    *
    * @param url The URL to process
-   * @returns The URL without the __trackId parameter
+   * @returns The URL without the contextual parameters
    *
-   * Example: "/library/radio?__trackId=song.mp3" → "/library/radio"
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → "/library/radio"
    * Example: "/search?q=jazz&__trackId=song.mp3" → "/search?q=jazz"
    */
   stripTrackId(url: string): string {
@@ -62,8 +69,9 @@ export const BrowserPathHelper = {
       const isFullUrl = url.startsWith('http://') || url.startsWith('https://')
       const urlObj = new URL(url, isFullUrl ? undefined : 'http://placeholder')
 
-      // Remove the __trackId parameter
+      // Remove the contextual parameters
       urlObj.searchParams.delete(this.CONTEXTUAL_TRACK_PARAM)
+      urlObj.searchParams.delete(this.CONTEXTUAL_INDEX_PARAM)
 
       // Return the appropriate format
       if (isFullUrl) {
@@ -75,7 +83,7 @@ export const BrowserPathHelper = {
     } catch {
       // Fallback: simple string manipulation
       const paramPattern = new RegExp(
-        `[?&]${this.CONTEXTUAL_TRACK_PARAM}=[^&]*`,
+        `[?&](?:${this.CONTEXTUAL_TRACK_PARAM}|${this.CONTEXTUAL_INDEX_PARAM})=[^&]*`,
         'g'
       )
       let result = url.replace(paramPattern, '')
@@ -87,6 +95,24 @@ export const BrowserPathHelper = {
     }
   },
 
+  /**
+   * Builds a contextual URL by appending a track identifier — and optionally
+   * the tapped child's page position — to a parent path.
+   *
+   * @param parentPath The parent container path
+   * @param trackId The track identity (`id` when non-blank, else `src`)
+   * @param index The child's position on the page at stamp time (tie-breaker)
+   * @returns A contextual URL combining parent path, track ID, and index
+   *
+   * Example: build("/library", "song.mp3", 2) → "/library?__trackId=song.mp3&__index=2"
+   */
+  build(parentPath: string, trackId: string, index?: number): string {
+    const separator = parentPath.includes('?') ? '&' : '?'
+    const indexParam =
+      index === undefined ? '' : `&${this.CONTEXTUAL_INDEX_PARAM}=${index}`
+    return `${parentPath}${separator}${this.CONTEXTUAL_TRACK_PARAM}=${encodeURIComponent(trackId)}${indexParam}`
+  },
+
   /**
    * Extracts the track ID from a contextual URL.
    * Returns undefined if the URL is not contextual or doesn't contain the track ID parameter.
@@ -100,18 +126,40 @@ export const BrowserPathHelper = {
     if (!this.isContextual(path)) {
       return undefined
     }
+    return this.extractParam(path, this.CONTEXTUAL_TRACK_PARAM)
+  },
+
+  /**
+   * Extracts the stamped page index from a contextual URL, or undefined when
+   * the URL is not contextual or carries no (valid, non-negative) index.
+   *
+   * Example: "/library/radio?__trackId=song.mp3&__index=2" → 2
+   */
+  extractIndex(path: string): number | undefined {
+    if (!this.isContextual(path)) {
+      return undefined
+    }
+
+    const raw = this.extractParam(path, this.CONTEXTUAL_INDEX_PARAM)
+    if (raw === undefined || !/^\d+$/.test(raw)) {
+      return undefined
+    }
+    return Number.parseInt(raw, 10)
+  },
 
+  /**
+   * Extracts a single query parameter, handling both full URLs and paths,
+   * with a regex fallback for input the URL parser rejects.
+   */
+  extractParam(path: string, param: string): string | undefined {
     try {
-      // Parse the URL - handle both full URLs and paths
       const isFullUrl =
         path.startsWith('http://') || path.startsWith('https://')
       const urlObj = new URL(path, isFullUrl ? undefined : 'http://placeholder')
-      return urlObj.searchParams.get(this.CONTEXTUAL_TRACK_PARAM) ?? undefined
+      return urlObj.searchParams.get(param) ?? undefined
     } catch {
       // Fallback: regex extraction
-      const match = path.match(
-        new RegExp(`[?&]${this.CONTEXTUAL_TRACK_PARAM}=([^&]*)`)
-      )
+      const match = path.match(new RegExp(`[?&]${param}=([^&]*)`))
       return match?.[1] ? decodeURIComponent(match[1]) : 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.

package/website/guide/android-certificates.md

@@ -0,0 +1,409 @@
+---
+description: 'Fix Android SSLHandshakeException / "Trust anchor for certification path not found" on HTTPS streams whose server omits its intermediate certificate.'
+---
+
+# Android: SSL "Trust anchor for certification path not found" (missing intermediate certificates)
+
+**If Android playback of a radio stream (or any HTTPS audio source) fails with an
+`SSLHandshakeException` / `CertPathValidatorException` / "Trust anchor for
+certification path not found" — and the same stream plays fine on iOS and in a
+desktop browser — you are in the right place.** This is almost always a server
+that omits an intermediate certificate; the fix is to let the client chase the
+missing certificate via the leaf's Authority Information Access (AIA) pointer, and
+this guide shows the one-time Android setup that does it.
+
+## The problem
+
+Some HTTPS servers are misconfigured to send only their **leaf** certificate and
+omit the **intermediate** certificate(s) needed to chain up to a trusted root. A
+correctly configured server sends the full chain; a misconfigured one leaves the
+client to find the gap on its own.
+
+- **iOS and web browsers** recover automatically: they follow the leaf's
+  Authority Information Access (AIA) "CA Issuers" pointer to fetch the missing
+  intermediate. (This is why the stream works everywhere except Android.)
+- **Android's default trust manager does not.** It validates only what the server
+  sent, so playback of such a stream fails with:
+
+  ```
+  javax.net.ssl.SSLHandshakeException:
+    java.security.cert.CertPathValidatorException:
+      Trust anchor for certification path not found.
+  ```
+
+This affects media playback because the Android player transports audio over
+`HttpURLConnection`, which uses the process-wide default `SSLSocketFactory`.
+
+> **iOS needs no setup.** Apple's TLS stack chases AIA intermediates on its own,
+> so there is nothing to configure on iOS — this guide is Android-only.
+
+## Is this actually your problem?
+
+Before changing process-global TLS state, confirm the failing stream really is a
+missing-intermediate case and not some other TLS failure (an expired cert, an SNI
+mismatch, or a genuinely untrusted root — none of which this fix addresses).
+
+Run, against your failing stream's **host** — use just the hostname, not the full
+stream URL. If your stream URL is `https://example.com:8000/live.mp3`, the host is
+`example.com` and the port is `8000` (omit the path); plain `https://` URLs with no
+port use `443`:
+
+```sh
+openssl s_client -connect example.com:443 \
+  -servername example.com -showcerts </dev/null
+```
+
+In the output:
+
+- A **complete** chain lists two or more certificates under
+  `Certificate chain` (leaf `s:.../CN=host` then one or more issuers `i:...`) and
+  ends with `Verify return code: 0 (ok)`.
+- A **missing-intermediate** server typically shows **only one** certificate in
+  the chain and a verify error such as
+  `Verify return code: 21 (unable to verify the first certificate)` — yet the
+  leaf's AIA block contains a `CA Issuers - URI:` pointer. That combination is the
+  exact case this fix repairs.
+
+Prefer a browser? Paste the host into the [SSL Labs server
+test](https://www.ssllabs.com/ssltest/) — it flags **"Chain issues: Incomplete"**
+for this exact problem — or use [whatsmychaincert.com](https://whatsmychaincert.com/).
+
+> **Want to see a broken chain first?** `incomplete-chain.badssl.com` is a public
+> test host that deliberately omits its intermediate — the canonical example of
+> this misconfiguration. Run the command above against
+> `incomplete-chain.badssl.com:443` to see exactly what the "one certificate +
+> verify error + AIA pointer present" signature looks like before you go hunting in
+> your own stream.
+
+If the chain is complete, or there is no `CA Issuers` AIA pointer, this fix will
+**not** help — see [Caveats](#caveats).
+
+## Opt in
+
+The library ships an **additive** AIA-chasing `SSLSocketFactory` but does **not**
+install it for you — installing it sets process-global TLS state, which is a
+decision for the host application to make, not a library. Enable it by setting it
+as the default in your **existing** `MainApplication`'s `onCreate`, before any
+playback begins. `MainApplication.onCreate` runs before React Native loads and
+executes your JS bundle, so it is always early enough — no playback can have
+started yet.
+
+> Add the highlighted line to the `MainApplication` you already have (it lives at
+> `android/app/src/main/java/.../MainApplication.kt` or `.java`). **Don't create a
+> new file or a second `MainApplication` class** — just drop the call into the
+> `onCreate` you already have, after `super.onCreate()`.
+
+::: code-group
+
+```kotlin [MainApplication.kt]
+import com.audiobrowser.tls.AiaTls
+import javax.net.ssl.HttpsURLConnection
+import javax.net.ssl.SSLSocketFactory
+import android.util.Log
+
+class MainApplication : Application() {
+  override fun onCreate() {
+    super.onCreate()
+
+    try {
+      val aiaFactory = AiaTls.socketFactory()                   // [!code ++]
+      HttpsURLConnection.setDefaultSSLSocketFactory(aiaFactory) // [!code ++]
+      installedSslFactory = aiaFactory                          // [!code ++]
+    } catch (e: Exception) {
+      // Never let TLS setup block startup; playback keeps default behaviour.
+      Log.w("MainApplication", "Failed to install AIA-chasing TLS", e)
+    }
+
+    // ... the rest of your existing setup
+  }
+
+  companion object {
+    /** Kept so you can confirm the install — see "Verify it worked". */
+    var installedSslFactory: SSLSocketFactory? = null
+  }
+}
+```
+
+```java [MainApplication.java]
+import com.audiobrowser.tls.AiaTls;
+import javax.net.ssl.HttpsURLConnection;
+import javax.net.ssl.SSLSocketFactory;
+import android.util.Log;
+
+public class MainApplication extends Application {
+  /** Kept so you can confirm the install — see "Verify it worked". */
+  public static SSLSocketFactory installedSslFactory = null;
+
+  @Override
+  public void onCreate() {
+    super.onCreate();
+
+    try {
+      SSLSocketFactory aiaFactory = AiaTls.socketFactory();        // [!code ++]
+      HttpsURLConnection.setDefaultSSLSocketFactory(aiaFactory);   // [!code ++]
+      installedSslFactory = aiaFactory;                            // [!code ++]
+    } catch (Exception e) {
+      // Never let TLS setup block startup; playback keeps default behaviour.
+      Log.w("MainApplication", "Failed to install AIA-chasing TLS", e);
+    }
+
+    // ... the rest of your existing setup
+  }
+}
+```
+
+:::
+
+That's all. The player's data source picks up the process default automatically.
+`AiaTls` ships with the `react-native-audio-browser` Android module you already
+installed — the `com.audiobrowser.tls` import resolves with no extra Gradle
+dependency.
+
+> **Rebuild after adding this.** `AiaTls` is native Kotlin, so a JS-only reload
+> won't pick up the new call — do a full native rebuild:
+>
+> ```sh
+> npx react-native run-android
+> # if the build seems stale, clear Gradle first:
+> cd android && ./gradlew clean && cd .. && npx react-native run-android
+> ```
+>
+> No manifest or permission change is needed — RN apps already hold the `INTERNET`
+> permission the AIA fetch uses, and the cleartext fetch is handled for you (see
+> [The cleartext fetch is handled for you](#the-cleartext-fetch-is-handled-for-you)).
+
+## The cleartext fetch is handled for you
+
+The completed-chain check happens over HTTPS — only the side fetch of the _missing
+intermediate_ uses the leaf's `CA Issuers` URL, which CAs publish over plain
+`http://` (mandated by the CA/Browser Forum Baseline Requirements, to avoid a
+chicken-and-egg TLS dependency when fetching the very certificate needed to
+complete a TLS chain).
+
+That's a problem on most modern apps: targeting Android 9+ (API 28) **blocks
+cleartext HTTP by default**, which would silently break the fetch on release
+builds. So the library doesn't use Android's HTTP stack for it — the `http`
+intermediate fetch goes over a **raw socket**, which isn't subject to your app's
+`usesCleartextTraffic` / network-security-config policy. **You don't need to enable
+cleartext or add a network security config.**
+
+This stays safe: the fetched certificate is cryptographically verified to be the
+genuine issuer and re-validated against the system trust anchors before use, so a
+tampered response over plain HTTP can only fail the chain, never weaken it.
+
+## Verify it worked
+
+A silent success is hard to tell apart from "my problem was something else," so
+confirm it explicitly:
+
+1. **Confirm the factory is installed.** The `catch` above only logs on _failure_,
+   so **no warning at startup means it installed without throwing** — enough for a
+   simple app. But it is _not_ enough if your app uses other networking libraries:
+   `setDefaultSSLSocketFactory` is last-write-wins (see [Caveats](#caveats)), so
+   another library setting its own default afterward silently deactivates the fix
+   with no warning. The comparison below is the **only reliable check** in that
+   case. `AiaTls.socketFactory()` returns a stock TLS socket factory configured
+   with the AIA-chasing trust manager, so its _class name_ looks identical to the
+   platform default — don't try to recognise it by class. Instead compare the
+   process default against the reference the opt-in snippet stored in
+   `installedSslFactory`. Put this **after** the install `try`/`catch` (so it
+   reflects the real process default, not the value you just set), anywhere that
+   runs after startup:
+
+   ::: code-group
+
+   ```kotlin [Kotlin]
+   // place OUTSIDE the install try/catch — this tests the live process default
+   val active = HttpsURLConnection.getDefaultSSLSocketFactory() ===
+     MainApplication.installedSslFactory
+   Log.i("MainApplication", "AIA TLS active: $active")
+   ```
+
+   ```java [Java]
+   // place OUTSIDE the install try/catch — this tests the live process default
+   boolean active = HttpsURLConnection.getDefaultSSLSocketFactory()
+     == MainApplication.installedSslFactory;
+   Log.i("MainApplication", "AIA TLS active: " + active);
+   ```
+
+   :::
+
+2. **Confirm playback recovers.** Play the exact stream that previously failed.
+   It should now start, and the
+   `SSLHandshakeException: ... Trust anchor for certification path not found`
+   should no longer appear in `adb logcat`. No real broken stream on hand? Point
+   the player at a known-broken-chain source such as
+   `https://incomplete-chain.badssl.com/` to prove the wiring end-to-end before you
+   rely on it. Keep one of these around as a regression check for future upgrades.
+
+### Still failing after install?
+
+Work through these in order:
+
+1. **Is it even a missing-intermediate case?** Re-run the
+   [diagnosis](#is-this-actually-your-problem). If the chain is complete, there's
+   no `CA Issuers` AIA pointer, or the root is genuinely untrusted/expired, this
+   fix can't repair it — that's a different problem.
+2. **Did the AIA fetch fail?** When the chaser tries to fetch the intermediate and
+   can't, the library logs a warning:
+
+   ```
+   AIA CA-issuer fetch failed: http://…/issuer.crt
+   ```
+
+   Filter `adb logcat` for `AIA CA-issuer fetch failed`. If it appears, the fetch
+   was attempted but couldn't be reached — see the next point. (You do _not_ need
+   to enable cleartext; the library's fetch already bypasses that policy.)
+
+   ::: warning The logger starts with the playback service
+   The library plants its logging trees when its service first starts, so a fetch
+   that fails **before** any playback has begun logs nothing — even though the
+   socket factory is process-wide and already in use. If you see no line at all,
+   start playback once and retry, or plant your own tree at startup.
+   :::
+
+3. **Reachable from your environment?** The fetch is a plain outbound request to
+   the `CA Issuers - URI` during the handshake, so a corporate proxy, VPN,
+   firewall, or a locked-down emulator network can block it. Confirm the URL
+   resolves by fetching it yourself — `curl -I "http://…/issuer.crt"` — from the
+   same network the device is on.
+4. **Custom Network Security Config?** If your app ships a
+   `res/xml/network_security_config.xml` with custom trust anchors or pinning,
+   that's an unrelated cause of TLS failures — this fix won't override it.
+
+## How it works
+
+`AiaTls.socketFactory()` wraps the **platform default** trust manager. On the
+happy path the default accepts the server-presented chain on the first try and
+nothing extra happens. Only when the default _rejects_ a chain does it:
+
+1. read the leaf's AIA "CA Issuers" URL,
+2. fetch the missing intermediate (over a raw socket for `http` URLs, so it works
+   regardless of your cleartext policy; cached for the process lifetime),
+3. re-validate the completed chain **against the same system trust anchors**.
+
+A fetched certificate is used only if it is genuinely the issuer of the preceding
+one. Because the final decision is still the system trust manager's, this can
+**only ever add a missing intermediate — it can never weaken trust**. Untrusted,
+expired, or self-signed roots still fail exactly as before.
+
+## Caveats
+
+- **Scope.** `setDefaultSSLSocketFactory` is process-wide, so it affects every
+  `HttpURLConnection`-based TLS connection in your app, not only playback. (It
+  does not affect OkHttp or a `WebView`, which keep their own TLS stacks.) It is
+  also last-write-wins: if other code sets its own default afterwards, it
+  overrides this one.
+- **First-connection latency on broken servers.** When a server omits its
+  intermediate, the first connection performs one extra HTTP request for the
+  intermediate during the TLS handshake. Well-configured servers pay no cost. The
+  fetched intermediate is cached for the **process lifetime only**, so this
+  one-time cost recurs once per cold start for each broken server.
+- **Not a cure-all.** It only rescues servers that omit an intermediate _and_
+  publish an AIA "CA Issuers" pointer that resolves to a trusted root. Servers
+  with no AIA extension, an unreachable intermediate, or a genuinely untrusted
+  root still fail.
+- **The AIA fetch needs outbound network reachability.** Completing the chain
+  performs a plain HTTP request to the `CA Issuers` host during the handshake; a
+  proxy, VPN, or firewall that blocks it makes the fix look broken even on a
+  genuinely missing-intermediate server. See
+  [Still failing after install?](#still-failing-after-install) to diagnose.
+- **Unrelated cause: custom Network Security Config.** A
+  `res/xml/network_security_config.xml` with custom trust anchors or certificate
+  pinning is a _different_ source of TLS failures that this fix does not address.
+
+## What you are opting into
+
+Trust is never weakened. The chain is only ever _extended_, and the completed
+chain is re-validated by the platform's own trust manager against the same
+system anchors, so anything Android would have rejected is still rejected.
+
+What you are accepting is an outbound request driven by a certificate that just
+failed validation. Completing a chain means fetching the missing intermediate
+from a URL written into that certificate, so a rejected handshake can cause a
+cleartext request to a **host, port and path of the server's choosing** —
+including a loopback or LAN address — and that request is deliberately not
+subject to your app's `NetworkSecurityPolicy` (see
+[The cleartext fetch is handled for you](#the-cleartext-fetch-is-handled-for-you)).
+
+This is inherent to AIA chasing: browsers and Apple's Secure Transport do the
+same thing, which is why the servers in question work everywhere except Android.
+It is bounded rather than absent:
+
+- the fetch happens **only** when the chain does not already reach one of your
+  trust anchors, so the common non-path failures — an expired leaf, a hostname
+  mismatch — do not trigger one. (The test is on the issuer name at the top of
+  the chain, so a chain topping at a root your device does _not_ carry, such as
+  a server still serving the retired DST Root CA X3 cross-sign, is still chased
+  even if its real problem is expiry.)
+- the URL is rejected unless it is free of control characters, so it cannot
+  inject request lines of its own;
+- at most 3 distinct `CA Issuers` URLs per certificate are tried, a response is
+  capped at 1 MiB, and at most 5 redirects are followed per fetch;
+- the whole chase runs under a single 20-second wall-clock budget — every
+  connect, TLS handshake, read and redirect hop is clipped to the time
+  remaining, and nothing new starts once it has expired. So the worst case a
+  hostile certificate can inflict on one failed handshake is roughly those
+  20 seconds, plus at most one DNS lookup that was already in flight when the
+  budget expired (Java offers no timeout for name resolution, so a lookup can
+  overrun the budget by its own duration — but a new one is never started past
+  it);
+- the cache holds at most 32 entries, and only successful fetches;
+- responses are never trusted on their say-so: a fetched certificate is used
+  only if it is the genuine issuer of the certificate below it, and the
+  completed chain still has to validate.
+
+If your threat model does not allow a failed handshake to trigger an outbound
+connection at all, don't install this — or install it on a single client
+(see [Advanced: custom OkHttp client](#advanced-custom-okhttp-client)) rather
+than as the process default.
+
+## Advanced: custom OkHttp client
+
+If you manage your own HTTP client instead of changing the process default, use
+`AiaTls.trustManager()` to obtain the wrapped `X509TrustManager` and build a
+matching `SSLSocketFactory` from it. OkHttp's `sslSocketFactory(...)` needs
+**both** the factory and the trust manager:
+
+::: code-group
+
+```kotlin [Kotlin]
+import com.audiobrowser.tls.AiaTls
+import javax.net.ssl.SSLContext
+import okhttp3.OkHttpClient
+
+val trustManager = AiaTls.trustManager()
+val sslContext = SSLContext.getInstance("TLS").apply {
+  init(null, arrayOf(trustManager), null)
+}
+
+val client = OkHttpClient.Builder()
+  .sslSocketFactory(sslContext.socketFactory, trustManager)
+  .build()
+```
+
+```java [Java]
+import com.audiobrowser.tls.AiaTls;
+import javax.net.ssl.SSLContext;
+import javax.net.ssl.X509TrustManager;
+import okhttp3.OkHttpClient;
+
+X509TrustManager trustManager = AiaTls.trustManager();
+SSLContext sslContext = SSLContext.getInstance("TLS");
+sslContext.init(null, new X509TrustManager[] { trustManager }, null);
+
+OkHttpClient client = new OkHttpClient.Builder()
+  .sslSocketFactory(sslContext.getSocketFactory(), trustManager)
+  .build();
+```
+
+:::
+
+This confines AIA chasing to that one client and leaves the process default
+untouched.
+
+> **Lifecycle.** Each call to `AiaTls.socketFactory()` / `AiaTls.trustManager()`
+> builds a fresh component with its **own** fetched-intermediate cache, so build
+> once and reuse it (don't construct one per request). The components are
+> thread-safe — the fetch cache is a synchronized, bounded LRU — so a single
+> instance is safe to install as the process default or share across a client.