@voltkit-rtc/react-native 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,1609 @@
-# Temporary Holding Version
+# @voltkit-rtc/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native SDK for [VoltKit RTC](https://voltkit.in/rtc): video and voice
+calls, audio rooms and chat in a React Native app, on Android, with iOS in
+preview. It has the hooks of [`@voltkit-rtc/react`](https://voltkit.in/docs/react-sdk),
+so a React call screen ports by changing the import and its markup, and runs
+the browser SDK [`@voltkit-rtc/client`](https://voltkit.in/docs/client-sdk) on
+react-native-webrtc, with what a phone adds: camera and microphone permissions
+asked before a device opens, audio routing to the earpiece, the loudspeaker and
+headsets, a call service that keeps a call going in the background, native
+timers so a reconnect still happens with the screen off, video views, and an
+Expo config plugin.
+
+**Tested on Android (emulator, API 37.1); iOS in preview; earpiece and
+Bluetooth routing tested in unit tests, not on hardware.** See
+[Testing status](#testing-status).
+
+| | |
+| --- | --- |
+| **Provider** | `VoltkitProvider` |
+| **Hooks** | `useRoom` `useConnectionState` `useParticipants` `useRemoteTracks` `useLocalMedia` `useNetworkQuality` `useWalletLow` `useVoltkitEvent` `useVoltkitClient` |
+| **Media hooks** | `useAudioLevels` `useActiveSpeakers` `useIsSpeaking` `useStreamFallback` `usePublishFallback` `useMediaWarnings` `useCpuConstrained` `useDevices` |
+| **Audio, permissions and the call service** | `useAudioOutput` `setSpeakerphoneOn` `selectAudioOutput` `usePermissions` `requestMediaPermissions` `checkMediaPermissions` `useCallService` |
+| **Components** | `VideoTrack` `AudioTrack` |
+| **Functions** | `createClient` `reactNativeClientOptions` `reactNativePlatform` `preflight` `registerVoltkitGlobals` |
+| **Constants** | `SDK_VERSION` |
+
+Your backend mints a short-lived room token with
+[`@voltkit-rtc/server`](https://voltkit.in/docs/server-sdk) (or the Python, Go,
+PHP or Java server SDK) and hands the app `{ token, wsUrl }`. The API secret
+never reaches the app.
+
+Contents: [Install](#install) ·
+[Permissions](#permissions) ·
+[Quick start](#quick-start) ·
+[VoltkitProvider](#voltkitprovider) ·
+[Hooks](#hooks) ·
+[VideoTrack and AudioTrack](#videotrack-and-audiotrack) ·
+[Audio routing](#audio-routing) ·
+[Calls in the background](#calls-in-the-background) ·
+[Screen sharing](#screen-sharing) ·
+[Chat](#chat) ·
+[Moderation](#moderation-seats-and-audio-rooms) ·
+[Tokens and wallet](#token-refresh-and-wallet-notices) ·
+[Your own client](#your-own-client) ·
+[Errors](#errors) ·
+[Troubleshooting](#troubleshooting) ·
+[iOS preview](#ios-preview) ·
+[Testing status](#testing-status) ·
+[Help](#help)
+
+## Install
+
+### Bare React Native
+
+```bash
+npm install @voltkit-rtc/react-native @voltkit-rtc/react @voltkit-rtc/client react-native-webrtc
+npx react-native run-android      # the package has native Android code: build the app again
+```
+
+`@voltkit-rtc/client`, `@voltkit-rtc/react` and react-native-webrtc are peer
+dependencies, installed beside the SDK so the app, the hooks and the video views
+share one copy of each. Autolinking finds the package. Nothing goes into
+`MainApplication` or `MainActivity`: a startup provider in the package sets up
+react-native-webrtc's audio before it starts, and release builds need no
+ProGuard or R8 rules of your own (the SDK carries the one react-native-webrtc
+155.0.1 needs). Types are included; ES modules and CommonJS both work.
+
+**TypeScript.** Nothing to add to `tsconfig.json`: the SDK's streams and
+tracks are typed by shape (`MediaStreamLike` and `MediaStreamTrackLike`,
+react-native-webrtc's `MediaStream` and `MediaStreamTrack`), so
+`useLocalMedia().stream?.getVideoTracks()[0]` and a remote track's `track`
+compile with `@react-native/typescript-config` as it comes, without the DOM
+library, and under Expo's `tsconfig.base` alike.
+
+| Requirement | Value |
+| --- | --- |
+| React Native | 0.82 or newer, with the New Architecture; tested with 0.88.0 and Hermes |
+| React | 19.1 or newer |
+| react-native-webrtc | 155.0.1 or a later 155.x |
+| `@voltkit-rtc/client` | 0.9.13 or a later 0.9.x |
+| `@voltkit-rtc/react` | 0.1.1 or a later 0.1.x |
+| Android | minSdk 24 (Android 7.0), react-native-webrtc's minimum |
+| Expo | SDK 58 or newer, in a development build; not Expo Go |
+| iOS | Preview: see [iOS preview](#ios-preview) |
+| Licence | MIT |
+
+**Globals.** Importing `@voltkit-rtc/react-native` registers
+react-native-webrtc's WebRTC classes as globals, which mediasoup-client needs
+(`registerVoltkitGlobals()`), so there is no `registerGlobals()` of your own to
+call. Calling it again does nothing, and it returns `false` without throwing
+where react-native-webrtc's native module is missing (Expo Go, an app not built
+again): the provider then reports that through `onError`.
+
+**One WebRTC per app.** Do not add a second WebRTC build: a fork of
+react-native-webrtc, such as `@livekit/react-native-webrtc` or
+`@stream-io/react-native-webrtc`, or a native SDK that bundles its own, such as
+VoltKit's Android SDK `in.voltkit:voltkit-rtc`. Two copies of libwebrtc in one
+APK clash on native symbols, and two call engines compete for the microphone
+and the audio routing.
+
+### Expo (development builds)
+
+```bash
+npx expo install @voltkit-rtc/react-native @voltkit-rtc/react @voltkit-rtc/client react-native-webrtc expo-dev-client
+```
+
+Add the SDK's config plugin to `app.json` (or `app.config.ts`). It writes the
+Android permissions, the call service and the `in.voltkit.rtc.*` meta-data into
+the manifest, and the usage strings and background modes into `Info.plist`, so
+you edit no native file:
+
+```json
+{
+  "expo": {
+    "plugins": [
+      [
+        "@voltkit-rtc/react-native",
+        {
+          "cameraPermission": "Your camera is shown to the people in your call.",
+          "microphonePermission": "Your microphone is heard by the people in your call."
+        }
+      ]
+    ]
+  }
+}
+```
+
+| Option | Default | What it does |
+| --- | --- | --- |
+| `cameraPermission`, `microphonePermission` | the app's own `Info.plist` text, else `Allow $(PRODUCT_NAME) to use your camera in calls.` (`... microphone ...`) | The iOS prompts (`NSCameraUsageDescription`, `NSMicrophoneUsageDescription`) |
+| `android.camera` | `true` | Declares `CAMERA`, with the camera features marked as not required (`uses-feature android:required="false"`), so Google Play does not hide the app from devices without them. `false` for an app that never publishes video |
+| `android.callService` | `true` | Declares the [call service](#calls-in-the-background) and its permissions. `false` declares no foreground service: nothing to declare to Google Play, but a call drops a few seconds after the app leaves the screen |
+| `android.callServiceCamera` | `false` | Adds the `camera` type and `FOREGROUND_SERVICE_CAMERA`, for an app that keeps the camera on in the background (`background={{ pauseCamera: false }}`) |
+| `android.screenShare` | `false` | Turns on react-native-webrtc's screen-capture service for [screen sharing](#screen-sharing), with `FOREGROUND_SERVICE_MEDIA_PROJECTION` and the `mediaProjection` type on the call service |
+| `android.audioMode` | `"communication"` | `"media"` for an app whose users only listen: see [Audio routing](#audio-routing) |
+| `android.hardwareEchoCancellation` | `true` | The phone's own echo canceller and noise suppressor, where it has them |
+| `ios.backgroundAudio` | `true` | Adds `audio` to `UIBackgroundModes`, so a call keeps its sound in the background |
+| `ios.voip` | `false` | Adds `voip` to `UIBackgroundModes`, for an app that integrates CallKit itself |
+
+Then `npx expo run:android` builds the app with its native code and installs it;
+from then on `npx expo start` serves your JavaScript to that build with fast
+refresh. Build again after installing or upgrading the SDK or
+react-native-webrtc, and after changing the plugin's options, with
+`npx expo prebuild --clean` first. Your app's `blockedPermissions` win over the
+plugin, which warns at prebuild when a block leaves the call service or the
+screen-capture service unable to run. **Expo Go cannot run the SDK**: it is one
+app with the native modules Expo ships, and react-native-webrtc and this SDK
+bring native code of their own. In Expo Go nothing crashes: the provider
+reports `media-unavailable` with `data.reason` `webrtc-missing` and a message
+that says it needs a development build. Everything about Expo, EAS Build and
+release builds: https://voltkit.in/docs/react-native-expo.
+
+## Permissions
+
+Android, in `android/app/src/main/AndroidManifest.xml`; the Expo plugin writes
+these for you:
+
+```xml
+<uses-permission android:name="android.permission.RECORD_AUDIO" />
+<!-- Only if you publish video: -->
+<uses-permission android:name="android.permission.CAMERA" />
+
+<!-- Google Play reads RECORD_AUDIO and CAMERA as hardware the app cannot do without, and hides the app from
+     devices without them, unless the manifest marks them as not required. The camera entries go with CAMERA. -->
+<uses-feature android:name="android.hardware.microphone" android:required="false" />
+<uses-feature android:name="android.hardware.camera" android:required="false" />
+<uses-feature android:name="android.hardware.camera.autofocus" android:required="false" />
+<uses-feature android:name="android.hardware.camera.front" android:required="false" />
+```
+
+`INTERNET`, `ACCESS_NETWORK_STATE` and `MODIFY_AUDIO_SETTINGS` come with the
+SDK's own manifest, and Bluetooth headsets need no Bluetooth permission. The
+[call service](#calls-in-the-background) has entries of its own.
+
+iOS (preview), in your app's `Info.plist`:
+
+```xml
+<key>NSCameraUsageDescription</key>
+<string>Your camera is shown to the people in your call.</string>
+<key>NSMicrophoneUsageDescription</key>
+<string>Your microphone is heard by the people in your call.</string>
+```
+
+`publish()` asks for what it is about to open, the microphone and the camera,
+before any device opens; a viewer who only watches is never asked. A refusal
+rejects `publish()` with `RpcError` `media-unavailable`, with `data.permission`
+(`'camera'` or `'microphone'`) and `data.status`: `'denied'` when the system may
+ask again, `'blocked'` once the user has refused for good (on Android, after
+choosing "Don't allow" twice), when only the app's settings can grant it.
+
+To ask earlier, on a screen before the call,
+`requestMediaPermissions(['camera', 'microphone'])` shows the system's dialogs
+for those not granted yet and resolves to each one's status: `'granted'`,
+`'denied'` (the dialog may still show) or `'blocked'`. It never rejects.
+`checkMediaPermissions(kinds)` reads the statuses without asking, and
+`usePermissions(kinds)` keeps them as state, checked again whenever the app
+comes back to the front (the user may have changed them in the settings). On
+Android 13 and later, ask for `'notifications'` too, so the call's notification
+shows in the notification shade; the call works without it, and older Android
+versions have nothing to ask:
+
+```tsx
+import { Button, Linking, Text, View } from 'react-native';
+import { requestMediaPermissions, usePermissions } from '@voltkit-rtc/react-native';
+
+/** A screen before the call: the camera and microphone, and the call notification on the way. */
+export function BeforeTheCall({ onReady }: { onReady: () => void }) {
+  const media = usePermissions(['camera', 'microphone']);
+  const blocked = media.statuses?.camera === 'blocked' || media.statuses?.microphone === 'blocked';
+
+  async function ask() {
+    const statuses = await media.request();
+    await requestMediaPermissions(['notifications']);
+    if (statuses.camera === 'granted' && statuses.microphone === 'granted') onReady();
+  }
+
+  return (
+    <View>
+      {blocked && <Text>Allow the camera and microphone in Settings to join in.</Text>}
+      <Button title={blocked ? 'Open Settings' : 'Continue'} onPress={blocked ? () => void Linking.openSettings() : ask} />
+    </View>
+  );
+}
+```
+
+The SDK's own captures afterwards, such as a reconnect that opens the devices
+again or a camera switch, only check and never ask: a dialog must not open in
+the background.
+
+## Quick start
+
+**1. A token from your backend.** Ask your endpoint right before joining, with
+your app's own sign-in. [Token server](https://voltkit.in/docs/token-server)
+builds the endpoint in several languages:
+
+```ts
+// token.ts
+export type Credentials = { token: string; wsUrl: string };
+
+export async function fetchCredentials(callId: string, accessToken: string): Promise<Credentials> {
+  const res = await fetch(`https://api.example.com/calls/${encodeURIComponent(callId)}/token`, {
+    method: 'POST',
+    headers: { Authorization: `Bearer ${accessToken}` }, // your app's sign-in, never the RTC secret
+  });
+  if (!res.ok) throw new Error(`Could not get a token (${res.status}).`);
+  return (await res.json()) as Credentials;
+}
+```
+
+Tokens are short-lived (ten minutes by default), and the service refreshes them
+during the session. Production `wsUrl`s start with `wss://`: Android refuses
+`ws://` and `http://` in a release build unless the app allows cleartext
+traffic, so allow it only for a test server on your own network, in a debug
+build.
+
+**2. A call screen.** The client side of a call: join, your camera and
+microphone, everyone's video, mute, camera off, flip, loudspeaker and leave.
+Remote sound needs no component: react-native-webrtc plays it.
+
+```tsx
+// CallScreen.tsx
+import { useState } from 'react';
+import { Button, StyleSheet, Text, View } from 'react-native';
+import {
+  VideoTrack,
+  VoltkitProvider,
+  useAudioOutput,
+  useLocalMedia,
+  useRemoteTracks,
+  useRoom,
+  type ClosedReason,
+} from '@voltkit-rtc/react-native';
+import { fetchCredentials, type Credentials } from './token';
+
+const ENDED: Record<ClosedReason, string> = {
+  left: 'You left the call.',
+  kicked: 'You were removed from the call.',
+  'room-closed': 'The call has ended.',
+  replaced: 'You joined this call from another device.',
+  'gave-up': 'The connection was lost.',
+};
+
+export function CallScreen({ callId, accessToken }: { callId: string; accessToken: string }) {
+  const [credentials, setCredentials] = useState<Credentials | null>(null);
+  const [attempt, setAttempt] = useState(0);
+  const [notice, setNotice] = useState<string | null>(null);
+  const [busy, setBusy] = useState(false);
+
+  async function join() {
+    setBusy(true);
+    setNotice(null);
+    try {
+      setCredentials(await fetchCredentials(callId, accessToken));
+      setAttempt((n) => n + 1); // a new key: a new provider with a fresh client
+    } catch (err) {
+      setNotice((err as Error).message);
+    } finally {
+      setBusy(false);
+    }
+  }
+
+  if (!credentials) {
+    return (
+      <View style={styles.center}>
+        {notice && <Text>{notice}</Text>}
+        <Button title={busy ? 'Joining…' : 'Join the call'} onPress={join} disabled={busy} />
+      </View>
+    );
+  }
+
+  return (
+    <VoltkitProvider
+      key={attempt}
+      wsUrl={credentials.wsUrl}
+      token={credentials.token}
+      onError={(err) => console.warn('[voltkit]', err.message)} // warnings too: see Errors
+      onClosed={(reason) => {
+        setCredentials(null);
+        setNotice(ENDED[reason]);
+      }}
+    >
+      <Call onRetry={join} />
+    </VoltkitProvider>
+  );
+}
+
+function Call({ onRetry }: { onRetry: () => void }) {
+  const { state, info, error, leave } = useRoom();
+  const local = useLocalMedia();
+  const audio = useAudioOutput();
+  const videos = useRemoteTracks({ kind: 'video' });
+  const [problem, setProblem] = useState<string | null>(null);
+  const report = (err: Error) => setProblem(err.message);
+
+  if (state === 'idle' && error) {
+    return (
+      <View style={styles.center}>
+        <Text>Could not join: {error.message}</Text>
+        <Button title="Try again" onPress={onRetry} />
+      </View>
+    );
+  }
+  if (state === 'idle' || state === 'connecting') {
+    return (
+      <View style={styles.center}>
+        <Text>Joining…</Text>
+      </View>
+    );
+  }
+
+  const canPublish = info?.role === 'host' || info?.role === 'cohost';
+  const camera = local.stream?.getVideoTracks()[0];
+
+  return (
+    <View style={styles.screen}>
+      {state === 'reconnecting' && <Text>Reconnecting…</Text>}
+      {problem && <Text>{problem}</Text>}
+
+      <View style={styles.tiles}>
+        {camera && <VideoTrack track={camera} mirror={local.facingMode === 'user'} style={styles.tile} />}
+        {videos.map((t) => (
+          <VideoTrack key={t.producerId} track={t.track} producerId={t.producerId} objectFit="cover" style={styles.tile} />
+        ))}
+      </View>
+
+      <View style={styles.controls}>
+        {canPublish && !local.stream && (
+          <Button title="Start camera and microphone" onPress={() => local.publish().catch(report)} />
+        )}
+        {local.stream && (
+          <>
+            <Button title={local.micEnabled ? 'Mute' : 'Unmute'} onPress={() => local.setMicEnabled(!local.micEnabled).catch(report)} />
+            <Button title={local.camEnabled ? 'Camera off' : 'Camera on'} onPress={() => local.setCamEnabled(!local.camEnabled).catch(report)} />
+            <Button title="Flip" onPress={() => local.switchCamera().catch(report)} />
+          </>
+        )}
+        {audio.supported && (
+          <Button
+            title={audio.speakerphone ? 'Earpiece' : 'Loudspeaker'}
+            onPress={() => audio.setSpeakerphoneOn(!audio.speakerphone).catch(report)}
+          />
+        )}
+        <Button title="Leave" onPress={leave} />
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  center: { flex: 1, alignItems: 'center', justifyContent: 'center', gap: 12 },
+  screen: { flex: 1, backgroundColor: '#000' },
+  tiles: { flex: 1, flexDirection: 'row', flexWrap: 'wrap' },
+  tile: { width: '50%', aspectRatio: 3 / 4 },
+  controls: { flexDirection: 'row', flexWrap: 'wrap', justifyContent: 'center', gap: 8, padding: 12 },
+});
+```
+
+**3. The app:**
+
+```tsx
+// App.tsx
+import { View } from 'react-native';
+import { CallScreen } from './CallScreen';
+
+export default function App() {
+  // Your own sign-in gives the access token; the call id comes from your app's data.
+  return (
+    <View style={{ flex: 1 }}>
+      <CallScreen callId="call-42" accessToken="your-session-token" />
+    </View>
+  );
+}
+```
+
+What each part does:
+
+- **The provider** makes the client, connects it, and closes it when it
+  unmounts. On joining it takes the phone's call audio (call mode, audio focus,
+  where sound plays) and, if the app declares it, starts the
+  [call service](#calls-in-the-background); it lets both go when the call ends.
+  `onError` hears what is not the answer to a call you made: warnings, a call
+  service that could not start, and in Expo Go the missing native code.
+  `onClosed` says why a session ended. A closed session stays closed, so joining
+  again mounts a new provider (a new `key`) with a fresh token.
+- **`publish()`** asks for the microphone and camera permissions, then opens the
+  devices and publishes them; only hosts and co-hosts may. With no options it
+  sends the highest quality the project allows, 1080p unless your project's
+  settings say otherwise. That is your users' mobile data and your egress: pass
+  `{ quality: '720p' }` where they matter more than the picture.
+- **Your own tile** is mirrored while the front camera is in use. `producerId`
+  on a remote `VideoTrack` turns on adaptive video: it is received at the size
+  it is laid out, and paused while it is hidden or the app is in the background.
+- **The loudspeaker button** moves call audio between the loudspeaker and the
+  earpiece; a connected headset still wins. Calls start on the loudspeaker. For
+  a voice call held to the ear, pass `audio={{ speakerphone: false }}` to the
+  provider.
+- **The hooks follow the client.** After `setMicEnabled(false)`, `micEnabled`
+  is false in every component that uses `useLocalMedia()`, and a reconnect
+  shows as `reconnecting` without unmounting anything.
+
+## VoltkitProvider
+
+`<VoltkitProvider>` holds one `StreamClient` for the components below it. It is
+the React SDK's provider underneath, so every re-exported hook works below it,
+and its props are `VoltkitProviderProps`: the React provider's, plus three of
+its own.
+
+| Prop | Type | |
+| --- | --- | --- |
+| `wsUrl` | `string` | the room's WebSocket URL, from your backend with the token |
+| `token` | `string` | a room token your backend minted |
+| `connect` | `boolean` | connect the client when it is idle; default `true`. With `false`, call `useRoom().connect()` yourself |
+| `onConnected` | `(result: JoinResult) => void` | after every successful join: the first, and each automatic reconnect |
+| `onError` | `(error: Error) => void` | every `error` event (warnings included), a failed connect, a token the session refused, a call service that could not start, and missing native code |
+| `onClosed` | `(reason: ClosedReason) => void` | the session ended for good: `left`, `kicked`, `room-closed`, `gave-up` or `replaced` |
+| `client` | `StreamClient \| null` | a client you made with `createClient` and own, used instead of `wsUrl` and `token`; never closed by the provider |
+| `clientOptions` | `ClientOptions` | options for the client the provider makes, laid over React Native's own. Read once, when the client is made, like `token` |
+| `audio` | `AudioSessionOptions \| false` | the call audio: `speakerphone` (the loudspeaker, `true`, the default, or the earpiece, `false`, when no headset is connected, unless `setSpeakerphoneOn` chose) and `manage` (default `true`). `false`, or `manage: false`, leaves the phone's audio mode, focus and routing to your app |
+| `background` | `BackgroundOptions` | what switches off while the app is in the background: the camera (`pauseCamera`, default `true`) and the microphone (`pauseMic`, default `false`) |
+| `callService` | `boolean \| CallServiceText` | start the [call service](#calls-in-the-background) when the call connects, if the app declares it. Default `true`; `false` never starts it; an object changes the notification's words: `title` ("Call in progress"), `text` ("Tap to return to the call") and `leaveLabel` ("Leave") |
+| `children` | `ReactNode` | |
+
+- **The client it makes** has the options
+  `reactNativeClientOptions({ background, clientOptions })` returns: the
+  mediasoup handler (`ReactNative106`), the React Native platform
+  (`reactNativePlatform()`), and `background` as the client's
+  `pauseCameraInBackground` and `pauseMicInBackground`, with the `clientOptions`
+  you give laid over them. A client you make yourself for the `client` prop
+  comes from `createClient` (see [Your own client](#your-own-client)): a plain
+  `new StreamClient(...)` would look for a browser.
+- **Where the native code is missing,** nothing throws and the hooks keep their
+  defaults: in Expo Go, or an app not built again after installing
+  react-native-webrtc, the provider makes no client and `onError` gets
+  `media-unavailable` with `data.reason` `webrtc-missing`; on Android without
+  the SDK's own native module, `data.reason` is `native-missing`, and the call
+  works without background calls, audio routing and native timers.
+- **A new `token` for the same session** (the same project, room and identity,
+  read from the token without verifying it: the server does that) goes to the
+  live session with `updateToken`, with no reconnect: that is how you
+  [refresh a token](#token-refresh-and-wallet-notices). A token for another room
+  or identity closes the client and makes one for the new session. A new `wsUrl`
+  replaces the client, and taking `token` or `wsUrl` away closes it.
+- **A closed session stays closed.** To join again, render the provider with a
+  new `key` and a fresh token, as the call screen does.
+- **With `client`** the provider uses yours as it is: it connects it when it is
+  idle (unless `connect` is `false`) and never closes it.
+- **The callbacks are always the latest** you passed. A client the provider lets
+  go of, on unmount or for a new `wsUrl`, reports nothing more.
+- **StrictMode** runs effects twice in development. The provider then makes a
+  client, closes it before it connects, and makes the one it keeps: one socket,
+  one connect, nothing left open.
+
+## Hooks
+
+The hooks are the React SDK's, with the same names, returns and defaults. Every
+hook returns its default until the provider has a client, then follows the
+client and renders again only when what it returns has changed. A hook outside
+any `VoltkitProvider` does not throw: it keeps returning its default.
+
+| Hook | Returns | Default |
+| --- | --- | --- |
+| `useRoom()` | `RoomState`: `client`, `info`, `state`, `error`, `connect()`, `leave()` | `state` is `'idle'`; `client`, `info` and `error` are null |
+| `useConnectionState()` | `'idle'`, `'connecting'`, `'connected'`, `'reconnecting'` or `'closed'` | `'idle'` |
+| `useParticipants()` | `ParticipantInfo[]`: everyone in the room, you included | `[]` |
+| `useRemoteTracks(filter?)` | `RemoteTrack[]`: every track this client receives, `producerId`, `identity`, `kind`, `source`, `track`, `paused`; the filter takes `identity`, `kind` and `source` | `[]` |
+| `useLocalMedia()` | `LocalMedia`: your camera, microphone and screen, and the calls that change them, with `switchCamera()` and `facingMode` | nothing published |
+| `useNetworkQuality()` | `NetworkQuality`: `level`, `rttMs`, `lossPct`, `availableKbps`, about every 3 s | `null` |
+| `useWalletLow()` | `WalletLowState`: `active`, `remainingSeconds`, `notice` | not active |
+| `useVoltkitEvent(event, handler)` | nothing: calls `handler` for each event while mounted | |
+| `useVoltkitClient()` | the provider's `StreamClient` | `null` |
+| `useAudioOutput()` | `AudioOutput`: `supported`, `outputs`, `current`, `speakerphone`, `select(deviceId)`, `setSpeakerphoneOn(on)`: see [Audio routing](#audio-routing) | not supported |
+| `usePermissions(kinds)` | `Permissions`: `statuses` (each `'granted'`, `'denied'` or `'blocked'`), `granted`, `request()`, `refresh()`: see [Permissions](#permissions) | `statuses` is null until first checked |
+| `useCallService()` | `CallServiceState`: `declared`, `running`, `types`: see [Calls in the background](#calls-in-the-background) | not declared |
+
+The media hooks are the React SDK's too: `useAudioLevels()` (every
+participant's sound level, `speaking` included), `useActiveSpeakers()` (who is
+speaking, most active first), `useIsSpeaking(identity)` (renders only when it
+changes, so it suits every tile), `useStreamFallback(producerId)` (why a remote
+video is held back on a poor connection: `'bandwidth'`, `'audio-protection'`,
+or null), `usePublishFallback()`, `useMediaWarnings()` (`mic-silent`,
+`camera-fps-low`, `camera-interrupted`, `mic-interrupted`),
+`useCpuConstrained()` and `useDevices(kind?)`. Two differences on a phone:
+
+- **Sound levels** are read from the connection's statistics every 500 ms,
+  where a browser reads them about four times a second, so `useAudioLevels`,
+  `useActiveSpeakers` and `useIsSpeaking` change twice a second.
+- **`useDevices`** lists the cameras (`'videoinput'`, each with `facing`:
+  `front`, `back` or `external`), the microphones (`'audioinput'`) and, on
+  Android, the outputs (`'audiooutput'`), each with its `type`. For an output
+  picker, `useAudioOutput()` is simpler.
+
+```tsx
+import { StyleSheet, Text, View } from 'react-native';
+import { VideoTrack, useIsSpeaking, useStreamFallback } from '@voltkit-rtc/react-native';
+import type { RemoteTrack } from '@voltkit-rtc/react-native';
+
+/** One remote video, with a speaking ring and a note while a poor connection holds the video back. */
+export function Tile({ track }: { track: RemoteTrack }) {
+  const speaking = useIsSpeaking(track.identity);
+  const held = useStreamFallback(track.producerId);
+  return (
+    <View style={[styles.tile, speaking && styles.speaking]}>
+      {held ? (
+        <Text style={styles.note}>{track.identity}: poor connection</Text>
+      ) : (
+        <VideoTrack track={track.track} producerId={track.producerId} style={styles.video} />
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  tile: { width: '50%', aspectRatio: 3 / 4 },
+  speaking: { borderWidth: 2, borderColor: '#22c55e' },
+  video: { flex: 1 },
+  note: { padding: 8 },
+});
+```
+
+`useVoltkitClient()` is the provider's client, for everything the hooks do not
+wrap: chat (`sendMessage`, `getMessages`), moderation (`raiseHand`, `promote`,
+`forceMute`, `kick`, `endRoom`), seats (`claim`, `release`, `blockSlot`),
+`switchDevice`, `getDiagnostics`. Its methods, events and options are the
+browser SDK's: https://voltkit.in/docs/client-sdk.
+
+### useLocalMedia
+
+`useLocalMedia(): LocalMedia` is your camera, microphone and screen.
+
+| State | |
+| --- | --- |
+| `stream` | your camera and microphone as published (`client.local`), or null: a `MediaStreamLike` (react-native-webrtc's stream, by shape), so `stream.getVideoTracks()[0]` is the camera for a `VideoTrack` |
+| `publishing` | anything is published: camera, microphone or screen |
+| `micEnabled`, `camEnabled` | switched on |
+| `audioQuality`, `videoQuality`, `videoFrameRate` | what is sent, after the project's limits: `'std'` or `'hd'`; `'1080p'`, `'720p'` or `'480p'`; `30` or `60` |
+| `screenSharing`, `screenStream` | the screen being shared (a `MediaStreamLike`), for a preview |
+| `permissions` | `MediaPermissions`: what this project lets this client publish. Offer only these |
+| `facingMode` | `'user'` (front) or `'environment'` (back): the camera in use; null without a camera |
+
+| Call | |
+| --- | --- |
+| `publish(options?)` | ask for the permissions, then open the camera and microphone and publish them (hosts and cohosts) |
+| `unpublish()` | stop publishing everything, screen included, and release the devices |
+| `setMicEnabled(on)`, `setCamEnabled(on)` | switch one off or on; viewers are told |
+| `setAudioQuality(quality)` | `'std'` or `'hd'` while live; resolves to the quality in use |
+| `setVideoQuality(quality)` | while live; raises the camera's capture first when it is smaller; resolves to the quality used |
+| `setVideoFrameRate(frameRate)` | `30` or `60` while live; resolves to the frame rate used |
+| `switchCamera()` | front and back on the same track and producer, so viewers see no gap; resolves `true` when the front camera is now in use. `media-unavailable` before a camera is published |
+| `startScreenShare(options?)`, `stopScreenShare()` | Android screen sharing, after the system's consent: see [Screen sharing](#screen-sharing) |
+
+**`publish(options?: LocalPublishOptions)`** takes the browser SDK's
+`PublishOptions` (`quality`, `frameRate`, `audioQuality`, `layers`, `codec`,
+`degradationPreference`) plus:
+
+| Option | Default | |
+| --- | --- | --- |
+| `audio` | `true` | `true` for VoltKit's microphone settings, `false` for no microphone, or your own constraints, used as given |
+| `video` | `true` | `true` for the quality's frame and frame rate, `false` for no camera, or your own constraints |
+| `facingMode` | `'user'` | `'user'` (front) or `'environment'` (back): which camera to open. `switchCamera()` flips it while live |
+
+What it captures: the frame of `quality` (1080p 1920×1080, 720p 1280×720, 480p
+854×480) at `frameRate` (30 unless you ask for 60), and an echo-cancelled,
+noise-suppressed microphone, stereo for `audioQuality: 'hd'`. `quality`
+defaults to the highest the project allows: the best picture, and the most
+data. A phone sends two copies of its camera, half and full size, so each
+viewer receives the one their connection can carry; `codec: 'auto'` picks H.264
+only where the phone has a hardware H.264 encoder, and VP8 everywhere else.
+60 fps is delivered only when the capture source provides it. Phone makers
+usually keep 60 fps for their own camera app, so most apps get 30 fps;
+`setVideoFrameRate(60)` then resolves to `30` with a `frame-rate-fallback`
+warning. Every quality and its data use: https://voltkit.in/docs/video-quality.
+
+```tsx
+import { useLocalMedia } from '@voltkit-rtc/react-native';
+
+export function useBackCameraFirst() {
+  const local = useLocalMedia();
+  return async function start(): Promise<boolean> {
+    await local.publish({ facingMode: 'environment', quality: '720p' }); // start on the back camera
+    return local.switchCamera(); // resolves true: the front camera is in use now
+  };
+}
+```
+
+Any camera: `useDevices('videoinput')` lists them, each with `facing`, and
+`client.switchDevice('videoinput', deviceId)` switches the published one. An id
+no camera has rejects with `bad-params`; a switch that fails rejects with
+`camera-failed`, and the old camera stays on air. Microphones:
+`useDevices('audioinput')` lists them, and
+`client.switchDevice('audioinput', deviceId)` records from another one, such as
+a wired headset's, without opening a new track.
+
+Before opening any device, `publish` refuses with an `RpcError`: see
+[When publishing fails](#when-publishing-fails).
+
+## VideoTrack and AudioTrack
+
+### VideoTrack
+
+`<VideoTrack track ...>` shows one video track in a native view
+(react-native-webrtc's `RTCView`), sized by `style`. Its props are
+`VideoTrackProps`:
+
+| Prop | |
+| --- | --- |
+| `track` | the video to show: a remote track's `track`, or your own camera, `useLocalMedia().stream?.getVideoTracks()[0]`. Nothing while null or undefined. A `MediaStreamTrackLike`: react-native-webrtc's track by shape, which a remote track's `track` fits as the client types it, so no DOM library is needed |
+| `producerId` | a remote video's `producerId`: the client then receives it at the size this view is laid out, and pauses it at the server while the view is not `visible` or the app is in the background (adaptive stream). Leave it out for your own camera |
+| `mirror` | flip it horizontally, as people expect to see their own front camera |
+| `objectFit` | `'cover'` (the default) fills the view and crops the edges; `'contain'` shows the whole picture, with bars |
+| `zOrder` | which of two overlapping video views is drawn on top, as for `RTCView`: 0 for a full-screen video, 1 for a preview over it |
+| `visible` | `false` while the view is off screen or covered: with `producerId`, the video is paused at the server until it is `true` again. Default `true` |
+| `onDimensionsChange` | called with the video's width and height when its first frame arrives and when they change |
+| `style`, `testID` | as for any view |
+
+Each track is shown through one native stream that the SDK makes, shares
+between the views of that track, and releases before the client closes the
+connection the track came on. Do not wrap tracks in `new MediaStream()` for an
+`RTCView` of your own: react-native-webrtc ends the app when a stream is
+released after its track's connection has closed, which happens on every
+reconnect and when a call ends. A view that shows no frame within 3 s mounts
+its native view again once (react-native-webrtc issue 1611, black video).
+
+### AudioTrack
+
+Remote sound plays by itself, so a call needs no `AudioTrack`. Render one only
+to change one person's volume, or to mute them on this phone. It renders
+nothing. Its props are `AudioTrackProps`:
+
+| Prop | |
+| --- | --- |
+| `track` | a remote audio track. Nothing while null or undefined |
+| `volume` | 0 to 1 (clamped), this track's playback volume, where 1 is the track as received. Unset leaves it as it is |
+| `muted` | silence this track here only; it plays again when the prop is `false` or the component unmounts |
+
+```tsx
+import { AudioTrack, useRemoteTracks } from '@voltkit-rtc/react-native';
+
+/** One person's microphone at half volume on this phone; everyone else plays as received. */
+export function QuietVoice({ identity }: { identity: string }) {
+  const [mic] = useRemoteTracks({ identity, source: 'mic' });
+  return mic ? <AudioTrack track={mic.track} volume={0.5} /> : null;
+}
+```
+
+## Audio routing
+
+While a client is connected, the SDK runs the phone's call audio: it switches to
+call mode, takes audio focus, and plays sound on a Bluetooth headset, else a
+wired or USB headset, else the loudspeaker or the earpiece. When the last
+client closes, it puts everything back as it found it. Two clients in one app,
+such as the two rooms of a PK battle, share it.
+
+```tsx
+import { Pressable, Text, View } from 'react-native';
+import { useAudioOutput } from '@voltkit-rtc/react-native';
+
+const NAMES: Record<string, string> = { speaker: 'Loudspeaker', earpiece: 'Phone', wiredHeadset: 'Headset', bluetooth: 'Bluetooth', usb: 'USB' };
+
+export function OutputPicker() {
+  const audio = useAudioOutput();
+  if (!audio.supported) return null; // false on iOS (preview) and in the media audio mode
+  return (
+    <View>
+      {audio.outputs.map((device) => (
+        <Pressable key={device.deviceId} onPress={() => void audio.select(device.deviceId)}>
+          <Text style={{ fontWeight: device.deviceId === audio.current?.deviceId ? 'bold' : 'normal' }}>
+            {device.label || NAMES[device.type ?? ''] || device.deviceId}
+          </Text>
+        </Pressable>
+      ))}
+    </View>
+  );
+}
+```
+
+- **`useAudioOutput(): AudioOutput`**: `supported` (outputs can be chosen:
+  Android with the SDK's native module, in the `communication` audio mode),
+  `outputs` (`MediaDevice[]`: the loudspeaker, the earpiece, and the headsets
+  connected now, each with `deviceId`, `label` and `type`: `speaker`,
+  `earpiece`, `wiredHeadset`, `bluetooth`, `usb` or `other`), `current` (where
+  call audio plays now, or null while no call holds the audio), `speakerphone`
+  (the loudspeaker is in use or, before a call, preferred), `select(deviceId)`
+  and `setSpeakerphoneOn(on)`. Headsets that come and go are followed.
+- **`select(deviceId)`** plays call audio on that output while it stays
+  connected, even over a headset; an output that is not there rejects with
+  `bad-params`. **`setSpeakerphoneOn(true)`** picks the loudspeaker when no
+  headset is connected, and `false` the earpiece; a headset still wins. Both are
+  also plain functions, `selectAudioOutput(deviceId)` and
+  `setSpeakerphoneOn(on)`, which work before any client exists, so a screen
+  before the call can set them: the choice holds for the calls joined later.
+  They reject with `media-unavailable` on iOS (`data.platform` `'ios'`) and
+  where the SDK's native module is missing.
+- **`client.switchDevice('audiooutput', deviceId)`**, from `useVoltkitClient()`,
+  does what `select` does.
+- **Android 12 and later** route call audio with `setCommunicationDevice`. On
+  Android 7 to 11, Bluetooth call audio goes over SCO, which some headsets and
+  car kits refuse. A headset that refuses, or says nothing for 3 seconds, is
+  passed over: call audio goes to the next output, and that headset is not
+  tried again until the user picks it, a device is added, or the call ends.
+- **No Bluetooth permission** is needed: the routing goes through Android's
+  `AudioManager`.
+- **Echo on one phone model.** The phone's own echo canceller and noise
+  suppressor are used where it has them. If one model echoes, turn them off with
+  the Expo plugin's `android.hardwareEchoCancellation: false` (or the
+  `in.voltkit.rtc.HW_AEC` meta-data, below), and WebRTC's own echo canceller
+  does the work.
+- **Apps whose users only listen** can set the audio mode to `media` (the
+  plugin's `android.audioMode`, or the `in.voltkit.rtc.AUDIO_MODE` meta-data):
+  sound plays at the media volume and on Bluetooth's high-quality profile, with
+  no earpiece, and outputs follow the system: `useAudioOutput().supported` is
+  false, and `select` and `switchDevice('audiooutput', ...)` reject with
+  `bad-params`. It is fixed for the life of the app's process: never use it
+  where anyone may speak, since a listener brought on stage would echo.
+- **`audio={{ manage: false }}`** on the provider leaves the phone's audio mode,
+  focus and routing to your app.
+- **The emulator** has only the loudspeaker. Earpiece and Bluetooth routing are
+  tested in unit tests, not on hardware: test them on a phone.
+
+In a React Native app without Expo, the audio settings are meta-data in
+`AndroidManifest.xml`, read once when the app starts. These are the defaults:
+
+```xml
+<application>
+  <!-- communication (calls and audio rooms) or media (listen-only apps) -->
+  <meta-data android:name="in.voltkit.rtc.AUDIO_MODE" android:value="communication" />
+  <!-- the phone's own echo canceller and noise suppressor, where it has them -->
+  <meta-data android:name="in.voltkit.rtc.HW_AEC" android:value="true" />
+  <!-- react-native-webrtc's screen-capture service: see Screen sharing -->
+  <meta-data android:name="in.voltkit.rtc.SCREEN_SHARE" android:value="false" />
+</application>
+```
+
+On iOS (preview) the SDK does not route audio: `useAudioOutput().supported` is
+false, and `setSpeakerphoneOn` and `selectAudioOutput` reject with
+`media-unavailable` (`data.platform` is `'ios'`).
+
+## Calls in the background
+
+Android stops a call that has gone to the background unless the app runs a
+foreground service that it started while it was visible:
+
+- **The network.** Without one, Android cut the test app's connections about
+  6 seconds after it went to the background or the screen went off, and the
+  call dropped (measured on the Android emulator while building this SDK).
+- **The microphone.** An app in the background records silence unless a
+  foreground service is running, which from Android 11 must have the
+  `microphone` type.
+- **Timers.** React Native's JavaScript timers stop in the background and while
+  the screen is off. The SDK runs the client's own timers natively (the
+  reconnect backoff, the connection checks), so with the service keeping the
+  app alive, a call still reconnects with the screen off.
+
+The SDK's foreground service, `VoltkitCallService`, keeps the call going. The
+provider starts it when the call connects, while the app is visible, and stops
+it when the call ends. It is not in the SDK's own manifest: the app declares
+it, so an app that never runs calls in the background has nothing to declare
+to Google Play.
+
+### Declaring the call service
+
+In an Expo app, the config plugin declares it unless you set
+`android.callService` to `false`. In a React Native app without Expo, add this
+to `android/app/src/main/AndroidManifest.xml`, then build the app again:
+
+```xml
+<manifest xmlns:android="http://schemas.android.com/apk/res/android">
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+  <uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+  <!-- Android 13+: shows the call notification in the notification shade (ask for it at run time). -->
+  <uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+
+  <application>
+    <!-- Inside your existing <application> element. -->
+    <service
+      android:name="com.voltkit.rtc.reactnative.VoltkitCallService"
+      android:exported="false"
+      android:foregroundServiceType="microphone|mediaPlayback" />
+  </application>
+</manifest>
+```
+
+The service picks its foreground service types from what the app declares,
+what the user has granted and what the call publishes:
+
+| Type | When the service runs with it |
+| --- | --- |
+| `microphone` | `RECORD_AUDIO` is granted: the call keeps its microphone |
+| `mediaPlayback` | otherwise: a listener, who keeps hearing the call |
+| `camera` | only if you declare it, with `FOREGROUND_SERVICE_CAMERA`, and keep the camera on in the background with `background={{ pauseCamera: false }}` (for a client you made, its own `createClient(..., { background: { pauseCamera: false } })`: the service reads the client's setting) |
+| `mediaProjection` | only while a screen share is live, if you declare it (with `FOREGROUND_SERVICE_MEDIA_PROJECTION` on Android 14 and later) |
+
+`useCallService(): CallServiceState` says whether the app declares the service
+(`declared`), whether it runs (`running`) and with which types (`types`). If it
+cannot start, because a permission is missing from the manifest or the app was
+already in the background, `onError` gets `media-unavailable` with
+`data.feature` set to `'callService'` and a message that names what is missing.
+The call goes on, in the foreground only. `callService={false}` on the provider
+never starts it.
+
+```tsx
+import { Text } from 'react-native';
+import { useCallService } from '@voltkit-rtc/react-native';
+
+/** A line for a settings screen: whether this build keeps calls going in the background. */
+export function BackgroundCallsNote() {
+  const service = useCallService();
+  if (!service.declared) return <Text>Calls end when the app leaves the screen in this build.</Text>;
+  if (!service.running) return <Text>The call runs in the foreground only right now.</Text>;
+  return <Text>Call service running with {service.types.join(', ')}.</Text>;
+}
+```
+
+### What happens in the background
+
+The app counts as in the background while none of its activities is started,
+as Android's process lifecycle says. A permission dialog or the screen-share
+consent dialog on top of the app does not count. In the background:
+
+- **Received videos** shown with a `producerId` pause at the server, so they use
+  no data, and resume when the app returns. The sound keeps playing.
+- **The camera** switches off, so viewers see the camera off rather than a
+  frozen picture, and back on when the app returns, unless the user or a
+  moderator switched it meanwhile. `background={{ pauseCamera: false }}` keeps
+  it on, which needs the service's `camera` type; without it Android stops a
+  background app's camera anyway.
+- **The microphone** keeps sending, as a call needs. `background={{ pauseMic: true }}`
+  switches it off too; leave that off for calls.
+- **What the user switches** while the app is in the background is theirs to
+  keep. A camera that comes on air there through something started before (a
+  publish finishing, a reconnect publishing again) is held off until the app
+  returns.
+
+### The notification
+
+While the service runs, Android shows its notification: "Call in progress",
+"Tap to return to the call", and a Leave button. Tapping it opens the app;
+Leave ends the call (`onClosed` gets `left`, and the others see you leave).
+Change the words on the provider:
+
+```tsx
+import type { ReactNode } from 'react';
+import { VoltkitProvider } from '@voltkit-rtc/react-native';
+
+export function CallProvider({ wsUrl, token, children }: { wsUrl: string; token: string; children: ReactNode }) {
+  return (
+    <VoltkitProvider
+      wsUrl={wsUrl}
+      token={token}
+      callService={{ title: 'Call with Asha', text: 'Tap to return to the call', leaveLabel: 'Hang up' }}
+    >
+      {children}
+    </VoltkitProvider>
+  );
+}
+```
+
+The small icon is your app's drawable named `voltkit_call_notification_icon`
+(or `notification_icon`, or `ic_notification`), and the SDK's own white handset
+when there is none; never the launcher icon, which Android would draw as a
+solid square. On Android 13 and later the notification shows in the
+notification shade only if the user allowed notifications; the service runs
+either way. Swiping the app away from the recent apps ends the call: the others
+see you leave, and the service stops.
+
+### Google Play's declaration
+
+An app that targets Android 14 or later and declares foreground service types
+declares each type in Play Console, under **Monitor and improve → App
+content**: what the feature does, what happens to the user if the task is
+deferred or interrupted, and a link to a video that shows a user starting the
+feature. For the call service, for example:
+
+- **Microphone:** "Keeps the user's call audio going when they switch apps or
+  turn the screen off during a call they started." The video starts a call,
+  goes to the home screen, and keeps talking.
+- **Media playback:** "Keeps a call audible for a listener who leaves the app."
+  The video joins a room as a listener, goes to the home screen, and keeps
+  listening.
+- **Camera** and **media projection**, if you declare them: the camera kept on
+  in the background, and screen sharing.
+
+Without the service (the plugin's `android.callService: false`, or no
+`<service>` block) there is nothing to declare, and a call drops about 6
+seconds after the app leaves the screen.
+
+### Xiaomi, Redmi and POCO phones
+
+Some phone makers' battery savers stop background apps beyond what Android
+itself does, and Xiaomi's are known for it. VoltKit has tested the call service
+on the Android emulator, not on these phones. If calls end in the background on
+them although `useCallService().running` was true, ask users to set your app's
+battery saver to "No restrictions" in the app's settings, and to allow
+Autostart.
+
+### iOS
+
+In the iOS preview there is no call service. Calls that keep their sound in the
+background need the `audio` background mode (`UIBackgroundModes`), which the
+Expo plugin adds unless you set `ios.backgroundAudio` to `false`. VoltKit has
+not tested background calls on iOS.
+
+## Screen sharing
+
+Screen sharing runs on Android, through react-native-webrtc's screen-capture
+service. Turn it on with the Expo plugin's `android.screenShare: true`, or in a
+React Native app without Expo add the permission and the meta-data, and the
+`mediaProjection` type to the call service:
+
+```xml
+<!-- FOREGROUND_SERVICE is in the call service's entries above; react-native-webrtc's service needs it too. -->
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+
+<application>
+  <meta-data android:name="in.voltkit.rtc.SCREEN_SHARE" android:value="true" />
+  <service
+    android:name="com.voltkit.rtc.reactnative.VoltkitCallService"
+    android:exported="false"
+    android:foregroundServiceType="microphone|mediaPlayback|mediaProjection" />
+</application>
+```
+
+```tsx
+import { Button } from 'react-native';
+import { RpcError } from '@voltkit-rtc/client';
+import { useLocalMedia } from '@voltkit-rtc/react-native';
+
+export function ShareScreenButton({ onProblem }: { onProblem: (text: string) => void }) {
+  const local = useLocalMedia();
+
+  async function toggle() {
+    try {
+      if (local.screenSharing) await local.stopScreenShare();
+      else await local.startScreenShare(); // Android asks the user first
+    } catch (err) {
+      const code = err instanceof RpcError ? err.code : '';
+      if (code === 'screen-share-denied') return; // the user said no: nothing to show
+      if (code === 'screen-share-service-required') onProblem('Screen sharing is not set up in this build.');
+      else if (code === 'screen-share-unsupported') onProblem('Screen sharing needs Android.');
+      else onProblem('Could not share the screen.');
+    }
+  }
+
+  return <Button title={local.screenSharing ? 'Stop sharing' : 'Share screen'} onPress={toggle} />;
+}
+```
+
+- Android asks the user before every share; on recent versions they choose one
+  app or the entire screen. The screen goes out beside the camera as a second
+  video, with `source` `screen`, and without sound.
+- Stopping from the status bar or the notification ends the share too
+  (`screenShareEnded`), and from Android 15 QPR1 the system also ends it when
+  the screen locks. The SDK stops react-native-webrtc's screen-capture service
+  when a share ends.
+- `screen-share-service-required`: the build does not have the screen-capture
+  service. `screen-share-denied`: the user cancelled.
+  `screen-share-unsupported`: iOS. `screen-share-active`: a share is already
+  running or starting. `screen-share-failed`: the capture could not start, with
+  the reason in the message.
+
+## Chat
+
+There are no chat hooks: chat is on the client the provider holds. Listen with
+`useVoltkitEvent` and send with `useVoltkitClient()`:
+
+```tsx
+import { useState } from 'react';
+import { Button, FlatList, Text, TextInput, View } from 'react-native';
+import { RpcError, type ChatMessage } from '@voltkit-rtc/client';
+import { useVoltkitClient, useVoltkitEvent } from '@voltkit-rtc/react-native';
+
+export function Chat() {
+  const client = useVoltkitClient();
+  const [messages, setMessages] = useState<ChatMessage[]>([]);
+  const [draft, setDraft] = useState('');
+  const [notice, setNotice] = useState<string | null>(null);
+
+  useVoltkitEvent('message', (m) => setMessages((list) => [...list, m])); // yours included
+  useVoltkitEvent('messageDeleted', ({ id }) => setMessages((list) => list.filter((m) => m.id !== id)));
+
+  async function send() {
+    if (!client || !draft.trim()) return;
+    try {
+      await client.sendMessage(draft);
+      setDraft('');
+      setNotice(null);
+    } catch (err) {
+      if (err instanceof RpcError && err.code === 'chat-muted') setNotice('A moderator has muted you in this chat.');
+      else if (err instanceof RpcError && err.code === 'rate-limited') setNotice('Slow down a little.');
+      else setNotice('Your message was not sent.');
+    }
+  }
+
+  return (
+    <View style={{ flex: 1 }}>
+      <FlatList
+        data={messages}
+        keyExtractor={(m) => m.id}
+        renderItem={({ item }) => (
+          <Text>
+            <Text style={{ fontWeight: 'bold' }}>{item.from}</Text> {item.text}
+          </Text>
+        )}
+      />
+      {notice && <Text>{notice}</Text>}
+      <TextInput value={draft} onChangeText={setDraft} onSubmitEditing={() => void send()} placeholder="Message" />
+      <Button title="Send" onPress={() => void send()} disabled={!client} />
+    </View>
+  );
+}
+```
+
+Render it inside the provider. A `Text` shows a message as text, whatever it
+contains. `client.getMessages({ limit: 50 })` returns earlier messages. Chat
+without a room uses `ChatClient` from `@voltkit-rtc/client`. Direct messages,
+moderation and history: https://voltkit.in/docs/chat.
+
+## Moderation, seats and audio rooms
+
+Everything that is not state is on the client: `useVoltkitClient()` returns it,
+and `useVoltkitEvent()` listens to any of its events. A listener raises a hand
+with `raiseHand()`, the host brings them on stage with
+`promote(identity, 'cohost')`, and a moderator uses
+`forceMute(identity, 'audio')`, `kick(identity, reason)` and `endRoom()`; seats
+are `claim(key)`, `release(key)` and `blockSlot(key)`. The service enforces
+each one from the role in the token.
+
+```tsx
+import { useState } from 'react';
+import { Button, Text, View } from 'react-native';
+import { useVoltkitClient, useVoltkitEvent } from '@voltkit-rtc/react-native';
+
+/** For the host: who raised a hand, and a button to bring each one on stage. */
+export function RaisedHands() {
+  const client = useVoltkitClient();
+  const [hands, setHands] = useState<string[]>([]);
+
+  useVoltkitEvent('handRaised', ({ identity, handRaised }) =>
+    setHands((list) => [...list.filter((i) => i !== identity), ...(handRaised ? [identity] : [])]),
+  );
+
+  return (
+    <View>
+      {hands.map((identity) => (
+        <View key={identity}>
+          <Text>{identity} raised a hand</Text>
+          <Button title="Bring on stage" onPress={() => void client?.promote(identity, 'cohost')} />
+        </View>
+      ))}
+    </View>
+  );
+}
+```
+
+For a voice call held to the ear, give the provider
+`audio={{ speakerphone: false }}` and publish the microphone alone with
+`publish({ video: false })`. One-to-one voice calls and group audio rooms, with
+a stage, seats and chat, are built on https://voltkit.in/docs/voice-calls and
+https://voltkit.in/docs/audio-rooms; their calls have the same names here.
+
+## Token refresh and wallet notices
+
+The service sends the session a fresh token over its connection by itself, so
+usually there is nothing to do. When it cannot (an older server, or a project
+that is out of credit, at a usage limit or suspended), the client fires
+`tokenExpiring` about a minute before its token expires. Mint a new one and
+render the provider with it:
+
+```tsx
+import { useVoltkitEvent } from '@voltkit-rtc/react-native';
+import { fetchCredentials } from './token';
+
+// Inside the provider, beside <Call />:
+// <RefreshToken callId={callId} accessToken={accessToken} onToken={(token) => setCredentials((c) => (c ? { ...c, token } : c))} />
+export function RefreshToken(props: { callId: string; accessToken: string; onToken: (token: string) => void }) {
+  useVoltkitEvent('tokenExpiring', async () => {
+    try {
+      const { token } = await fetchCredentials(props.callId, props.accessToken);
+      props.onToken(token);
+    } catch {
+      // The session keeps its token: only a reconnect after it has expired needs a new one.
+    }
+  });
+  return null;
+}
+```
+
+The provider sees a new token for the same session and hands it to the live
+session with `updateToken`, with no reconnect. A refresh the server refuses
+(`bad-token`) is reported through `onError`, and the session keeps its own
+token.
+
+With the VoltKit Wallet, the session is warned while the credits the project
+may spend cover less than about a minute. `useWalletLow()` turns the warnings
+into state:
+
+```tsx
+import { Text } from 'react-native';
+import { useWalletLow } from '@voltkit-rtc/react-native';
+
+export function CreditBanner() {
+  const { active, remainingSeconds } = useWalletLow();
+  if (!active) return null;
+  return <Text accessibilityRole="alert">Call credit runs out in about {remainingSeconds} s.</Text>;
+}
+```
+
+A recharge clears it. If the credits run out, the room closes: `onClosed` gets
+`room-closed`, and `roomClosed` carries the reason `quota-exhausted`.
+Flat-minute (legacy) projects get `usageLimit` instead:
+`useVoltkitEvent('usageLimit', ({ endsAt }) => ...)`.
+
+## Your own client
+
+`createClient(wsUrl, token, options?)` makes a `StreamClient` for React Native,
+not yet connected: pass it to the provider's `client` prop, or call `connect()`
+yourself, and `close()` it when you are done, since the provider never closes a
+client it was given. The background pause and the call service's types follow
+that client's own `background` options; the provider's `background` prop only
+describes a client the provider makes. `CreateClientOptions` is
+`{ background?: BackgroundOptions; clientOptions?: ClientOptions }`. It throws
+`media-unavailable` (`webrtc-missing`) where react-native-webrtc's native module
+is missing. Never make one with `new StreamClient(...)` alone, which would look
+for a browser.
+
+```tsx
+import { useEffect, useState, type ReactNode } from 'react';
+import { VoltkitProvider, createClient } from '@voltkit-rtc/react-native';
+import type { StreamClient } from '@voltkit-rtc/react-native';
+
+/** A client the app owns: the second room of a PK battle, a client kept across screens. */
+export function OwnClient({ wsUrl, token, children }: { wsUrl: string; token: string; children: ReactNode }) {
+  const [client, setClient] = useState<StreamClient | null>(null);
+  useEffect(() => {
+    const own = createClient(wsUrl, token, { background: { pauseCamera: false } });
+    setClient(own);
+    return () => {
+      void own.close();
+    };
+  }, [wsUrl, token]);
+  return <VoltkitProvider client={client}>{children}</VoltkitProvider>;
+}
+```
+
+`reactNativeClientOptions(options?)` returns the `ClientOptions` such a client
+is made with: `handlerName: 'ReactNative106'`, `platform: reactNativePlatform()`,
+`pauseCameraInBackground` and `pauseMicInBackground` from `background`, and then
+your `clientOptions`, which win. `reactNativePlatform()` is the platform the
+client runs on in React Native (`ClientOptions.platform` of `@voltkit-rtc/client`
+0.9.12): capture, devices and audio routing, streams and their release order,
+the app's visibility from the process lifecycle, the network, and native
+timers. One object per process, shared by every client; `createClient` and the
+provider pass it for you.
+
+## Errors
+
+Errors and warnings are `RpcError`s from `@voltkit-rtc/client` with a
+machine-readable `code` (`ErrorCode`): switch on the code, never the message.
+`data` carries the details, such as which permission was refused. Warnings
+(`frame-rate-fallback`, `audio-quality-not-allowed`, ...) change nothing else
+and need no action. Every code: https://voltkit.in/docs/errors.
+
+| Where | What arrives |
+| --- | --- |
+| `onError` on the provider | every `error` event from the client, failures and warnings alike, a failed connect, a token the session refused, and a call service that could not start |
+| `useRoom().error` | the last of those, until a join succeeds |
+| the promise of the call | `useRoom().connect()`, `publish()`, `switchCamera()` and every other `useLocalMedia()` call, `select` and `setSpeakerphoneOn`, and the client's own calls such as `sendMessage()`, reject with the error |
+| `onClosed` | the session ended for good, and why |
+
+`VideoTrack` and `AudioTrack` throw nothing. Without a client (outside a
+provider, or before it has made one) every `useLocalMedia()` call rejects with
+`not-connected`. Where react-native-webrtc's native code is missing, the
+provider makes no client at all: only `onError` hears it, with
+`media-unavailable` and `data.reason` `webrtc-missing`, while
+`useRoom().state` stays `idle`, so log `onError` while you develop.
+
+### When joining fails
+
+The provider connects once and does not retry a connect that failed: `onError`
+and `useRoom().error` get the error, and the state goes back to `idle`.
+`isTerminalError(code)` from `@voltkit-rtc/client` says whether the same token
+would be refused again. Turn the code into words for the user:
+
+```ts
+import { RpcError, isTerminalError } from '@voltkit-rtc/client';
+
+export function joinProblem(err: Error): { text: string; canRetry: boolean } {
+  const code = err instanceof RpcError ? err.code : '';
+  switch (code) {
+    case 'bad-token':
+    case 'no-token':
+      return { text: 'Your session expired. Join again.', canRetry: true }; // a fresh token fixes it
+    case 'room-ended':
+    case 'no-room':
+      return { text: 'This call has ended.', canRetry: false };
+    case 'kicked':
+      return { text: 'You were removed from this call.', canRetry: false };
+    case 'quota-exhausted':
+    case 'daily-limit-reached':
+    case 'monthly-limit-reached':
+    case 'tenant-suspended':
+    case 'billing-unavailable':
+      return { text: 'Calls are unavailable right now.', canRetry: false }; // your project's account, not the user
+    case 'participant-quota':
+    case 'no-capacity':
+      return { text: 'The call is full right now. Try again in a moment.', canRetry: true };
+    default:
+      return { text: 'Could not connect. Check your connection and try again.', canRetry: !isTerminalError(code) };
+  }
+}
+```
+
+### When publishing fails
+
+`publish()` refuses before it opens any device, so the camera light never comes
+on for a publish that cannot happen:
+
+| `code` | When |
+| --- | --- |
+| `media-unavailable` | a permission was refused: `data.permission` and `data.status`, see [Permissions](#permissions) |
+| `not-connected` | the session is not connected, or there is no client yet |
+| `forbidden` | your role is not `host` or `cohost` |
+| `source-already-published` | a camera and microphone are already published, or a publish is under way: `unpublish()` first |
+| `media-disabled` | the project switched that kind off. Check `permissions.audio` and `permissions.video`, or pass `audio: false` or `video: false` |
+
+A camera or microphone that another app holds, or that fails to open, rejects
+with `media-unavailable`, with `data.reason` set to the capture error's name (or
+`capture-failed`) and its words in the message: offer audio only with
+`publish({ video: false })`. The other calls refuse with codes too:
+`setMicEnabled(true)` and `setCamEnabled(true)` with `force-muted` while a
+moderator holds that device off, `switchCamera()` with `media-unavailable`
+before a camera is published, and `startScreenShare()` with the
+[screen-share codes](#screen-sharing).
+
+```ts
+import { RpcError } from '@voltkit-rtc/client';
+
+type MediaProblem = {
+  permission?: 'camera' | 'microphone';
+  status?: 'denied' | 'blocked';
+  reason?: string;
+  feature?: string;
+  platform?: string;
+};
+
+/** Words for a media-unavailable error, or null for any other error. */
+export function mediaProblem(err: unknown): string | null {
+  if (!(err instanceof RpcError) || err.code !== 'media-unavailable') return null;
+  const data = (err.data ?? {}) as MediaProblem;
+  if (data.permission) return data.status === 'blocked' ? `Allow the ${data.permission} in Settings.` : `The ${data.permission} is needed.`;
+  if (data.reason === 'webrtc-missing') return 'This build cannot make calls. Install the latest version of the app.';
+  if (data.feature === 'callService') return 'Calls may stop when you leave the app.';
+  return 'The camera or microphone is not available.';
+}
+```
+
+### Codes from React Native
+
+| `code` | What happened | What to do |
+| --- | --- | --- |
+| `media-unavailable` with `data.permission` | the user refused the camera or microphone; `data.status` is `denied` or `blocked` | ask again, or send them to the app's settings (`Linking.openSettings()`) when it is `blocked` |
+| `media-unavailable` with `data.reason` `webrtc-missing` | the app has no react-native-webrtc native code: Expo Go, or an app not built again after installing the SDK. The message says it needs a development build | build the app again; use a development build, not Expo Go |
+| `media-unavailable` with `data.reason` `native-missing` | the SDK's own native module is not in the app (Android): background calls, audio routing and native timers are off; `data.feature` names what asked | build the app again |
+| `media-unavailable` with another `data.reason` | the camera or microphone could not open: the reason is the capture error's name, or `capture-failed` | offer audio only, or try again |
+| `media-unavailable` with `data.feature` `callService` | the call service could not start: a manifest entry is missing, or the app was in the background | add what the message names; the call goes on in the foreground |
+| `media-unavailable` with `data.platform` `ios` | audio routing on iOS: `setSpeakerphoneOn`, `selectAudioOutput` or `switchDevice('audiooutput', ...)` | leave the control out on iOS |
+| `camera-failed` | the camera could not switch; the old one stays on air | try again |
+| `bad-params` | an id no camera, microphone or output has, or an output chosen in the `media` audio mode | use an id from `useDevices` or `useAudioOutput` |
+| `screen-share-service-required`, `screen-share-denied`, `screen-share-unsupported`, `screen-share-active`, `screen-share-failed` | screen sharing is not set up in the build, the user cancelled, iOS, a share is already starting, or the capture could not start | see [Screen sharing](#screen-sharing) |
+| `music-unavailable` | in-app music needs a browser | leave it out of the app |
+
+### Reconnection
+
+The client reconnects by itself, with backoff, and publishes your camera and
+microphone again when it is back. `useConnectionState()` and `useRoom().state`
+go to `reconnecting`, then back to `connected`: keep the call on screen and say
+it is reconnecting. A network change, such as Wi-Fi to mobile data, is handled
+the same way: the media path is repaired where it can be (the
+`mediaReconnecting` event), or the client rejoins. The SDK also listens to
+Android's network callback, so a reconnect waiting out its backoff tries again
+as soon as the network is back, also with the screen off while the call service
+runs. If it cannot reconnect, `onError` gets why (`reconnect-gave-up`, or a
+refusal such as `room-ended`), then `onClosed` gets `gave-up`, `room-closed` or
+`kicked`.
+
+## Troubleshooting
+
+Named after what the build, the log or the user shows. Echo, silence, frozen
+video and blocked connections, which are the same on every platform:
+https://voltkit.in/docs/troubleshooting.
+
+### `WebRTC native module not found`
+
+react-native-webrtc's own error when its native code is not in the app. The app
+was not built again after `npm install`: run `npx react-native run-android`, or
+make a new development build. Expo Go cannot load it at all.
+
+### "needs a development build"
+
+The SDK's `media-unavailable` error when native code is missing: `data.reason`
+is `webrtc-missing` for react-native-webrtc's module, and `native-missing` for
+the SDK's own. The app runs in Expo Go, or was not built again after installing
+or upgrading the packages. Nothing crashes; build the app again.
+
+### "the app's native code is @voltkit-rtc/react-native ... rebuild the app"
+
+A warning in the log when the app's native code was built from another version
+of the SDK than its JavaScript (`SDK_VERSION`): the package was upgraded without
+building the app again, or a development build is older than the JavaScript it
+loads. Build the app again.
+
+### `ERROR: R8: Missing class org.webrtc.Dav1dDecoder$Natives`
+
+A release build with react-native-webrtc 155.0.1 fails with
+`Missing class org.webrtc.Dav1dDecoder$Natives (referenced from: org.webrtc.Dav1dDecoder$Natives org.webrtc.Dav1dDecoderJni.get() and 2 other contexts)`.
+The WebRTC build it brings references a class it does not ship, and nothing
+calls it. `@voltkit-rtc/react-native`'s R8 rules silence it, so with the SDK
+installed release builds need nothing more. If you see it, the build is not
+using the SDK's rules: add the line to `android/app/proguard-rules.pro`, or in
+Expo to `expo-build-properties`' `android.extraProguardRules`:
+
+```text
+-dontwarn org.webrtc.Dav1dDecoder$Natives
+```
+
+### The call drops about 6 seconds after the app goes to the background
+
+Or after the screen turns off. The call service is not running: Android cuts
+the app's network a few seconds after it leaves the screen. Check
+`useCallService()`: `declared` false means the manifest has no `<service>`
+block, or the Expo plugin's `android.callService` is `false`; `running` false
+with `declared` true means it could not start, and `onError` said why
+(`data.feature` is `callService`). It must start while the app is visible,
+which the provider does when the call connects. See
+[Calls in the background](#calls-in-the-background), and for Xiaomi phones
+[their battery settings](#xiaomi-redmi-and-poco-phones).
+
+### `No video stream for react tag`
+
+react-native-webrtc's `RTCView` logs this when it is handed a stream it cannot
+find, and shows black (react-native-webrtc issue 1611). Show video with
+`VideoTrack`, which makes the native stream for each track itself and keeps it
+while the track is shown. If you render `RTCView` yourself, make one stream per
+track, keep it while the view is shown, and never release it after the call has
+ended.
+
+### `forgot to call registerGlobals()`
+
+mediasoup-client's warning, or `UnsupportedError: device not supported`, when
+`@voltkit-rtc/client` runs in React Native without the SDK: react-native-webrtc's
+globals are not registered and no handler is named. Import
+`@voltkit-rtc/react-native` before anything that uses the client (it registers
+them), and make clients with `createClient` or the provider, never with
+`new StreamClient(...)`.
+
+### `Media projections require a foreground service of type ServiceInfo.FOREGROUND_SERVICE_TYPE_MEDIA_PROJECTION`
+
+Android 14 refuses screen capture that starts without a running screen-capture
+service. With the SDK, sharing in a build without the service fails before
+that, with `screen-share-service-required`: turn on the Expo plugin's
+`android.screenShare`, or add the meta-data and permission from
+[Screen sharing](#screen-sharing), and build the app again.
+
+### `MissingForegroundServiceTypeException: Starting FGS without a type`
+
+Android 14 throws this when an app starts a foreground service whose manifest
+entry has no `android:foregroundServiceType`. There the SDK's call service
+never starts without a type: if its `<service>` entry declares neither
+`microphone` nor `mediaPlayback`, it does not start, and `onError` gets
+`media-unavailable` (`data.feature` `callService`) saying so. If you copied a
+foreground service for calls from another SDK's guide, remove it:
+`VoltkitCallService` does that job.
+
+### Silence or a black picture on the emulator
+
+The Android emulator's microphone records silence, and its cameras are
+simulated and slow. Test publishing sound and video on a phone; on the
+emulator, check receiving from a browser in the same room.
+
+### No earpiece on the emulator
+
+The emulator has only the loudspeaker, so `useAudioOutput().outputs` lists one
+output and `setSpeakerphoneOn(false)` has nowhere else to go. Test the earpiece
+and headsets on a phone.
+
+### Echo on one phone model
+
+Turn off the phone's own echo canceller with the Expo plugin's
+`android.hardwareEchoCancellation: false` (or `in.voltkit.rtc.HW_AEC` set to
+`false`) and build again; WebRTC's own canceller takes over. A headset or the
+earpiece removes echo entirely.
+
+### Google Play rejects the app for 16 KB page sizes
+
+Google Play requires apps that target Android 15 and later to support 16 KB
+memory pages. The WebRTC build that react-native-webrtc 155 brings is 16 KB
+aligned, as react-native-webrtc's maintainers say and VoltKit's emulator build
+(x86_64) showed; a rejection usually means a second copy of WebRTC from another
+SDK in the app. Look for more than one `libjingle_peerconnection_so.so` (or
+another SDK's WebRTC library) in the APK, and check the alignment with
+`zipalign -c -P 16 -v 4 app-release.apk`, which ends with
+"Verification successful".
+
+### `CLEARTEXT communication ... not permitted`
+
+The `wsUrl` (or your token endpoint) is `ws://` or `http://`, which Android
+refuses in a release build. Production URLs are `wss://` and `https://`. For a
+test server on your own network, allow cleartext for that host in a debug build
+only.
+
+### Build problems
+
+| Message | Fix |
+| --- | --- |
+| `@voltkit-rtc/react-native needs react-native-webrtc: npm install react-native-webrtc, then rebuild the app` | install react-native-webrtc, a peer dependency, then build again |
+| `Duplicate class org.webrtc...` | another package bundles WebRTC's Java classes, such as a react-native-webrtc fork or a native call SDK: remove it |
+| `minSdkVersion 23 cannot be smaller than version 24` | raise `minSdkVersion` to 24 (in Expo, with `expo-build-properties`) |
+| `@voltkit-rtc/react-native: the Expo config plugin's build, plugin/build, is missing` | the app uses a checkout of the SDK, not the published package: run `npm run build:plugin` in `react-native-sdk`, then prebuild again |
+| Prebuild warns `» android: @voltkit-rtc/react-native android.callService: ...` or `... android.screenShare: ...` | a `blockedPermissions` conflict: the service needs a permission your app blocks, which the warning names. Unblock it, or turn the option off |
+
+## iOS preview
+
+iOS is JavaScript only in 0.1.0: the SDK has no native iOS module, and
+react-native-webrtc's iOS code does the media (`cd ios && pod install` installs
+it). It is written to run there, but VoltKit has not compiled or run it on an
+iPhone or a simulator, so treat it as a preview.
+
+- **Works as on Android, untested:** joining, publishing and receiving, the
+  hooks, `VideoTrack`, chat, moderation and reconnection. Permissions go through
+  react-native-webrtc's permission requests (iOS asks once: a refusal is
+  `blocked` from then on), and the app counts as visible unless iOS reports it
+  in the background.
+- **Android only:** audio routing (`useAudioOutput().supported` is false;
+  `setSpeakerphoneOn` and `selectAudioOutput` reject with `media-unavailable`,
+  `data.platform` `'ios'`), the call service (`useCallService().declared` is
+  false), and screen sharing (`screen-share-unsupported`).
+- **Info.plist:** `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`,
+  and `UIBackgroundModes` with `audio` for calls that keep their sound in the
+  background. The Expo plugin writes them.
+- **CocoaPods** plans to stop accepting new pods on its trunk on 2 December
+  2026. react-native-webrtc's iOS WebRTC build comes from it, so follow
+  react-native-webrtc's notes for its later versions.
+
+The Flutter SDK (`voltkit_rtc`) supports iOS 13 and later. Write to
+contact@voltkit.in to try the React Native SDK on iOS with us.
+
+## Testing status
+
+**Tested on Android (emulator, API 37.1); iOS in preview; earpiece and
+Bluetooth routing tested in unit tests, not on hardware.** Tested with:
+
+| | Version |
+| --- | --- |
+| React Native | 0.88.0, New Architecture, Hermes |
+| React | 19.3.0 |
+| react-native-webrtc | 155.0.1 (WebRTC `org.jitsi:webrtc` 155.0.1) |
+| Expo | SDK 58 (`expo` 58.0.19), development build, R8-minified release build |
+| `@voltkit-rtc/client` | 0.9.13 |
+| `@voltkit-rtc/react` | 0.1.1 |
+| Android | the Android emulator (a Pixel 10 Pro AVD, x86_64, API 37.1, Google Play image); earpiece and Bluetooth routing in unit tests, not on hardware |
+| iOS | not tested: preview |
+
+What ran before this release, in this order:
+
+- **Unit tests.** The JavaScript (`npm test`, Jest with React Native's preset
+  and react-native-webrtc's native side mocked): the provider against a real
+  client, a fake signalling server and a fake mediasoup handler (connect,
+  publish, close with code 1000); the release order of the native streams
+  behind `VideoTrack` on a reconnect, a kick and a closed room; publish and
+  view races; permissions refused before any capture; the call audio held by
+  one client and by two, and given back; the call service's start, update,
+  stop, Leave and swipe-away; the `media` audio mode; the iOS preview's
+  refusals; `preflight`; and the Expo plugin's manifest and Info.plist output,
+  snapshot by snapshot, including a real `expo config --type introspect`. The
+  Android module (JVM tests): the output choice (earpiece, loudspeaker, wired
+  and USB headsets, Bluetooth), the Bluetooth SCO link and its timeout, the
+  call service and its types, the native timers, the network watch, the
+  preferred microphone and the manifest meta-data. The client
+  (`@voltkit-rtc/client`'s own suite, with a React Native fake platform): no
+  DOM global touched, every stream and track released over 50 cycles,
+  statistics-based audio levels, adaptive stream from a view's size, camera
+  switching, platform timers, and the background pause, ported case by case
+  from the Android SDK's device test and the Flutter SDK's lifecycle tests.
+- **The client under a React Native-like platform against the real controller
+  and media node** (`make -C voltkit-rtc rn-core-live`): a camera consumer at
+  the real temporal layers, a reconnect in under a second, every received track
+  released through the platform while the connection is live, every platform
+  timer cleared after `close()`, no DOM or host-timer use, no token kept where a
+  serialized client would show it.
+- **On the emulator**, the example app's R8 release build (Hermes) driven by the
+  in-app scenario runner (`make -C voltkit-rtc rn-device-e2e`), against the real
+  controller and media node: 44 of the 48 scenarios in the device suite passed
+  on the release build and none failed. They cover joining, leaving and the
+  close codes; reconnects after a network cut, a path change, a long stay in
+  the background and a token refresh; the camera and microphone published, with
+  viewers decoding every top-layer frame; dynacast and adaptive stream; the
+  camera switch; permissions; the loss of audio focus; the background pause and
+  the call service through 120 s in the background and with the screen off;
+  screen sharing; the pre-call check; a Chromium peer across the LAN; and the
+  `media` audio mode. Logcat showed no fatal exception, no
+  `No video stream for react tag` and no unexpected `E ReactNativeJS` line.
+  The other four are limits of the emulator or the test harness, with the
+  evidence recorded, not faults found in the SDK: the publisher fallback (the
+  emulator's microphone is silent, so Opus sent 72 packets in the 15 s window
+  where the check needs 150), tracks ending under Android's camera and
+  microphone privacy toggles (the AVD restricts the camera and silences the
+  microphone without ending either track), a scripted tap of the notification's
+  Leave action (the action is in the notification and the leave-to-close path
+  is unit-tested on both sides; uiautomator cannot read a shade whose
+  chronometer redraws it every second), and the swipe away from Recents (on
+  this image Android delivered the removal to the service 4.6 to 10.6 s after
+  the gesture, or not within 20 s; whenever it arrives, the SDK closes the
+  client at once).
+- **Not on hardware**: the earpiece, Bluetooth and wired headsets, the phone's
+  own echo canceller and encoders, and real microphone levels (the emulator's
+  microphone records silence, so publishing sound is checked by the bytes sent
+  and the node's ingress). iOS was not compiled or run.
+
+## Help
+
+Documentation: https://voltkit.in/docs/react-native-sdk (the guide),
+https://voltkit.in/docs/react-native-sdk-reference (every export, prop and
+option), https://voltkit.in/docs/react-native-expo (the config plugin,
+development builds and EAS) and the tutorial
+https://voltkit.in/guides/add-video-calling-to-a-react-native-app. Questions
+and bug reports: contact@voltkit.in.
+
+For a support ticket, attach the client's diagnostics snapshot. It names the
+SDK (`SDK_VERSION`), react-native-webrtc and the Android version, and holds no
+token and no media:
+
+```tsx
+import { Button, Share } from 'react-native';
+import { useVoltkitClient } from '@voltkit-rtc/react-native';
+
+export function ShareDiagnostics() {
+  const client = useVoltkitClient();
+  async function share() {
+    if (!client) return;
+    await Share.share({ message: JSON.stringify(await client.getDiagnostics()) });
+  }
+  return <Button title="Share diagnostics" onPress={share} />;
+}
+```
+
+`preflight(wsUrl, token, options?)` is a pre-call check: it joins with a client
+of its own, publishes the microphone for a few seconds when its permission is
+already granted (it asks for nothing; pass `media` to test streams of your own),
+and resolves to a `PreflightReport` of how media travelled, the round trip,
+loss, upload and any device problem. It never rejects: read `report.ok`, and the
+steps say what failed. Give it a token for a test room of its own, since the
+same identity joining anywhere replaces its live call.
+
+```ts
+import { preflight } from '@voltkit-rtc/react-native';
+
+export async function checkBeforeTheCall(wsUrl: string, token: string): Promise<string> {
+  const report = await preflight(wsUrl, token, { durationMs: 4000 });
+  if (report.ok) return `Ready: ${report.level ?? 'unknown'} (${report.rttMs ?? '?'} ms, ${report.lossPct ?? '?'} % loss)`;
+  const failed = report.steps.find((step) => !step.ok);
+  return `Not ready: ${failed?.name ?? 'unknown'} ${failed?.error ?? ''}`.trim();
+}
+```
+
+## Licence
+
+MIT