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

package/src/native-session.tsx

@@ -0,0 +1,384 @@
+/**
+ * What a connected call needs from the device on Android, kept by the provider for its client:
+ *
+ * - The call audio (audio.ts): held from the join to the close, so the audio mode, focus and routing are a call's; two
+ *   clients (a PK battle) hold it together and the last out restores the device.
+ * - The call service: a foreground service that keeps the call's network, microphone and timers alive while the app is
+ *   in the background or the screen is off. Without it Android cuts the app's sockets about 6 s after it leaves the
+ *   foreground or the screen goes off (Phase 0 finding 3). It runs while any call is live, for every client together
+ *   (one notification), when the app's manifest declares it (the Expo plugin's callService, default on). Android lets
+ *   it start, and take new foreground service types (the camera, a screen share), only while the app is visible: it
+ *   starts on the join and is brought up to date whenever the app comes back to the front. Its notification's Leave
+ *   action, and the app being swiped away from Recents, close every client it runs for (close code 1000, `left`).
+ *   Failures reach the provider's onError as `media-unavailable` with `{ feature: 'callService' }`.
+ */
+import { useEffect, useMemo, useRef, useSyncExternalStore } from 'react';
+import type { ClientOptions, StreamClient } from '@voltkit-rtc/client';
+import { useVoltkitClient } from '@voltkit-rtc/react';
+import type { CallServiceOptions as NativeCallServiceOptions, CallServiceStatus, Spec } from './specs/NativeVoltkitRtc';
+import { listen, nativeConstants, nativeModule } from './native';
+import { callServiceFailed, describeError, logError } from './errors';
+import { audioHoldOf, speakerPreference } from './audio';
+import { localSessionOf } from './local-media';
+import { nativeVisibility } from './platform/visibility';
+import { localStream } from './platform/common';
+
+/** The call service's notification. */
+export interface CallServiceText {
+  /** Default "Call in progress". */
+  title?: string;
+  /** Default "Tap to return to the call". */
+  text?: string;
+  /** The Leave action's label. Default "Leave". */
+  leaveLabel?: string;
+}
+
+/** How the provider manages the call audio. */
+export interface AudioSessionOptions {
+  /** The loudspeaker (true, the default) or the earpiece when no headset is connected, unless setSpeakerphoneOn chose. */
+  speakerphone?: boolean;
+  /** Hold the call audio (mode, focus, routing) while the call is connected. Default true. */
+  manage?: boolean;
+}
+
+// ----------------------------------------------------------------------------------------- the call service, shared
+
+interface Want {
+  live: boolean;
+  micPublished: boolean;
+  cameraPublished: boolean;
+  sharing: boolean;
+  /** The client switches its camera off in the background, so the service needs no camera type. */
+  pauseCamera: boolean;
+  text: CallServiceText;
+  leave(): void;
+  report(error: Error): void;
+}
+
+export interface CallServiceState {
+  /** The app's manifest declares the call service (VoltkitCallService). */
+  declared: boolean;
+  /** It runs now. */
+  running: boolean;
+  /** The foreground service types it runs with: `microphone`, `mediaPlayback`, `camera`, `mediaProjection`. */
+  types: string[];
+}
+
+const NOT_DECLARED: CallServiceState = Object.freeze({ declared: false, running: false, types: Object.freeze([]) as unknown as string[] });
+
+class CallServices {
+  /**
+   * What each call wants, read afresh at every decision: a call's state is its client's, which emits no event for some
+   * changes. With how to tell the call when its state cannot be read at all.
+   */
+  private readonly wants = new Map<object, { want: () => Want; report: (error: Error) => void }>();
+  private running = false;
+  /** The call to the native module under way: a `failed` event during a start or update is its rejection's twin. */
+  private inFlight: 'start' | 'update' | 'stop' | null = null;
+  private again = false;
+  /** The options the service runs with, as sent. */
+  private applied: string | null = null;
+  /** Options a start failed for: not tried again until they change or the app comes back to the front. */
+  private failed: string | null = null;
+  private watching: (() => void) | null = null;
+  private state: CallServiceState | null = null;
+  private readonly listeners = new Set<() => void>();
+
+  set(key: object, want: (() => Want) | null, report: (error: Error) => void = () => undefined): void {
+    if (want) this.wants.set(key, { want, report });
+    else this.wants.delete(key);
+    this.reconcile();
+  }
+
+  /** Something a call publishes may have changed: decide again. */
+  changed(): void {
+    this.reconcile();
+  }
+
+  subscribe = (listener: () => void): (() => void) => {
+    this.listeners.add(listener);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  };
+
+  snapshot = (): CallServiceState => {
+    if (this.state) return this.state;
+    const module = nativeModule();
+    if (!module || !nativeConstants()?.callServiceDeclared) return NOT_DECLARED;
+    let status: CallServiceStatus = { declared: true, running: false, types: [] };
+    try {
+      status = module.getCallServiceStatus();
+    } catch (err) {
+      logError('could not read the call service\'s status', err);
+    }
+    this.state = { declared: status.declared, running: status.running, types: [...status.types] };
+    return this.state;
+  };
+
+  private publish(status: Partial<CallServiceState>): void {
+    const now = this.snapshot();
+    const next = { ...now, ...status };
+    if (next.running === now.running && next.declared === now.declared && next.types.join() === now.types.join()) return;
+    this.state = next;
+    for (const listener of [...this.listeners]) listener();
+  }
+
+  private live(): Want[] {
+    const live: Want[] = [];
+    for (const [key, { want, report }] of [...this.wants]) {
+      let w: Want;
+      try {
+        w = want();
+      } catch (err) {
+        // A client whose state cannot be read (a wrapper that throws on a read): this call is left out of the service
+        // for good, said once, and never keeps the other calls from theirs (the verifier's F3 on 0.1.1).
+        this.wants.delete(key);
+        logError('a call is left out of the call service: its client\'s state could not be read', err);
+        try {
+          report(callServiceFailed(`this call is left out, its client's state could not be read: ${describeError(err)}`));
+        } catch (reportErr) {
+          logError('onError threw', reportErr);
+        }
+        continue;
+      }
+      if (w.live) live.push(w);
+    }
+    return live;
+  }
+
+  private reconcile(): void {
+    const module = nativeModule();
+    if (!module || !nativeConstants()?.callServiceDeclared) return;
+    const live = this.live();
+    this.watch(module, live.length > 0 || this.running);
+    if (this.inFlight) {
+      this.again = true;
+      return;
+    }
+    if (live.length === 0) {
+      this.failed = null;
+      if (this.running || this.applied !== null) this.run(module, 'stop', null);
+      return;
+    }
+    const options = merged(live);
+    const key = JSON.stringify(options);
+    if ((this.running && key === this.applied) || key === this.failed) return;
+    // Android lets a foreground service start, or widen its types, only while the app is visible.
+    if (!safeVisible(module)) return;
+    this.run(module, this.running ? 'update' : 'start', options);
+  }
+
+  private run(module: Spec, what: 'start' | 'update' | 'stop', options: NativeCallServiceOptions | null): void {
+    this.inFlight = what;
+    const key = options ? JSON.stringify(options) : null;
+    const call = what === 'stop' ? module.stopCallService() : what === 'start' ? module.startCallService(options!) : module.updateCallService(options!);
+    call.then(
+      (status) => {
+        this.running = status.running;
+        this.applied = status.running ? key : null;
+        if (status.running) this.failed = null;
+        this.publish({ declared: status.declared, running: status.running, types: [...status.types] });
+      },
+      (err: unknown) => {
+        if (what === 'stop') {
+          logError('could not stop the call service', err);
+          return;
+        }
+        this.failed = key;
+        const error = callServiceFailed(describeError(err));
+        for (const want of this.live()) want.report(error);
+      },
+    ).finally(() => {
+      this.inFlight = null;
+      if (this.again) {
+        this.again = false;
+        this.reconcile();
+        return;
+      }
+      // Nothing left to keep running: stop listening until the next call.
+      if (!this.running && this.live().length === 0) this.watch(module, false);
+    });
+  }
+
+  /** Visibility and the service's own events, while a call is live or the service runs. */
+  private watch(module: Spec, on: boolean): void {
+    if (on === (this.watching !== null)) return;
+    if (!on) {
+      this.watching?.();
+      this.watching = null;
+      return;
+    }
+    const visibility = nativeVisibility(module);
+    const stops = [
+      visibility.subscribe((visible) => {
+        if (!visible) return;
+        // Back in front: try again what failed, and bring the service up to date.
+        this.failed = null;
+        this.reconcile();
+      }),
+      listen(module.onCallServiceEvent, 'onCallServiceEvent', (event) => this.onEvent(event.type, event.types, event.message)),
+    ];
+    this.watching = () => {
+      for (const stop of stops) stop();
+    };
+  }
+
+  private onEvent(type: string, types: string[], message: string): void {
+    switch (type) {
+      case 'started':
+      case 'updated':
+        this.running = true;
+        this.publish({ running: true, types: [...types] });
+        return;
+      case 'stopped':
+        this.running = false;
+        this.applied = null;
+        // Stopped from outside while a call is live: started again when the app next comes to the front, not now.
+        if (this.live().length > 0) this.failed = JSON.stringify(merged(this.live()));
+        this.publish({ running: false, types: [] });
+        this.reconcile();
+        return;
+      case 'leave':
+      case 'taskRemoved':
+        for (const want of this.live()) want.leave();
+        return;
+      case 'failed': {
+        // VoltkitCallService.runWith tells `failed` and then rejects the start or update: the rejection reports it (RN010-2).
+        if (this.inFlight === 'start' || this.inFlight === 'update') return;
+        const error = callServiceFailed(message || 'Android refused it');
+        for (const want of this.live()) want.report(error);
+        return;
+      }
+      default:
+    }
+  }
+}
+
+function safeVisible(module: Spec): boolean {
+  try {
+    return module.isAppVisible();
+  } catch {
+    return true;
+  }
+}
+
+/** What the service runs with for these calls together. */
+function merged(live: Want[]): NativeCallServiceOptions {
+  const text = [...live].reverse();
+  const pick = (field: keyof CallServiceText) => text.find((w) => w.text[field])?.text[field] ?? '';
+  return {
+    title: pick('title'),
+    text: pick('text'),
+    leaveLabel: pick('leaveLabel'),
+    // The camera type only for a call that keeps its camera on in the background.
+    pauseCamera: !live.some((w) => w.cameraPublished && !w.pauseCamera),
+    micPublished: live.some((w) => w.micPublished),
+    cameraPublished: live.some((w) => w.cameraPublished),
+    sharing: live.some((w) => w.sharing),
+  };
+}
+
+const callServices = new CallServices();
+
+/** The call service: whether the app declares it, whether it runs and with which types. */
+export function useCallService(): CallServiceState {
+  return useSyncExternalStore(callServices.subscribe, callServices.snapshot, callServices.snapshot);
+}
+
+// ---------------------------------------------------------------------------------------------- the provider's part
+
+export interface NativeSessionProps {
+  audio: AudioSessionOptions | false | undefined;
+  callService: boolean | CallServiceText | undefined;
+  /** The provider's background.pauseCamera: for a client whose own options cannot be read (see pausesCameraInBackground). */
+  pauseCamera: boolean;
+  onError: { readonly current: ((error: Error) => void) | undefined };
+}
+
+/** Rendered by the provider inside @voltkit-rtc/react's provider: keeps the call audio and the call service for its client. */
+export function NativeSession({ audio, callService, pauseCamera, onError }: NativeSessionProps): null {
+  const client = useVoltkitClient();
+  const manage = audio !== false && audio?.manage !== false;
+  const speakerphone = audio === false ? undefined : audio?.speakerphone;
+  const wantsService = callService !== false;
+  const text = useMemo(() => (typeof callService === 'object' && callService !== null ? callService : {}), [callService]);
+  const latest = useRef({ speakerphone, text, pauseCamera });
+  useEffect(() => {
+    latest.current = { speakerphone, text, pauseCamera };
+  });
+
+  // What useLocalMedia shows (the screen being shared) is recorded for as long as the provider has the client.
+  useEffect(() => (client ? localSessionOf(client).hold() : undefined), [client]);
+
+  useEffect(() => {
+    if (!client || !manage || !nativeModule()) return;
+    const hold = audioHoldOf(client, (error) => onError.current?.(error));
+    hold.retain();
+    const sync = () => {
+      const state = client.connectionState;
+      if (state === 'connected' || state === 'reconnecting') hold.acquire(speakerPreference(latest.current.speakerphone));
+      else if (state === 'closed') hold.release();
+    };
+    sync();
+    const off = client.on('connectionStateChanged', sync);
+    return () => {
+      off();
+      hold.unretain();
+    };
+  }, [client, manage, onError]);
+
+  useEffect(() => {
+    if (!client || !wantsService || !nativeModule()) return;
+    const key = {};
+    const report = (error: Error) => onError.current?.(error);
+    callServices.set(key, () => wantOf(client, latest.current, report), report);
+    const update = () => callServices.changed();
+    // publish() and a camera switch emit no event of their own: useLocalMedia's calls say so through the local session.
+    const offs = [
+      ...(['connectionStateChanged', 'localMediaChanged', 'localStreamChanged', 'screenShareStarted', 'screenShareEnded'] as const)
+        .map((event) => client.on(event, update)),
+      localSessionOf(client).subscribe(update),
+    ];
+    return () => {
+      for (const off of offs) off();
+      callServices.set(key, null);
+    };
+  }, [client, wantsService, onError]);
+
+  return null;
+}
+
+function wantOf(client: StreamClient, latest: { text: CallServiceText; pauseCamera: boolean }, report: (error: Error) => void): Want {
+  const state = client.connectionState;
+  const local = localStream(client);
+  return {
+    live: state === 'connected' || state === 'reconnecting',
+    micPublished: (local?.getAudioTracks().length ?? 0) > 0,
+    cameraPublished: (local?.getVideoTracks().length ?? 0) > 0,
+    sharing: localSessionOf(client).screen !== null,
+    pauseCamera: pausesCameraInBackground(client) ?? latest.pauseCamera,
+    text: latest.text,
+    leave: () => client.close(),
+    report,
+  };
+}
+
+/**
+ * Whether the client switches its camera off in the background, from its own options: the provider's `background` only
+ * describes a client the provider made, and an app-made one (`createClient`, the `client` prop) keeps its camera on with
+ * `pauseCamera: false` while the service was asked for no camera type, so Android cut the camera (RN010-1). The client
+ * pauses only with `pauseCameraInBackground === true` (left out, the camera runs on). Null when the options cannot be
+ * read (missing, not an object, or a read that throws: a wrapped or stubbed client): the provider's setting stands in.
+ */
+function pausesCameraInBackground(client: StreamClient): boolean | null {
+  let options: unknown;
+  try {
+    options = (client as unknown as { options?: unknown }).options;
+  } catch {
+    // A wrapper that forbids the read (a logging or sealing Proxy): not an error, the provider's setting stands in.
+    return null;
+  }
+  if (!options || typeof options !== 'object') return null;
+  return (options as ClientOptions).pauseCameraInBackground === true;
+}

package/src/native.ts

@@ -0,0 +1,84 @@
+/**
+ * This package's native module (src/specs/NativeVoltkitRtc.ts), read only through here: it is null on iOS (JavaScript
+ * only in 0.1.0), in Expo Go and wherever the app was not rebuilt after installing the package. Everything that can do
+ * without it does (JavaScript timers, AppState); what cannot raises `media-unavailable` (errors.ts).
+ */
+import { Platform } from 'react-native';
+import type { EventSubscription } from 'react-native';
+import NativeVoltkitRtc, { type AudioDevice, type Constants, type Spec } from './specs/NativeVoltkitRtc';
+import { iosUnsupported, logError, nativeMissing } from './errors';
+import type { AudioDeviceType, DeviceKind, MediaDevice } from '@voltkit-rtc/client';
+
+/** The version of this package: what getDiagnostics() reports, and what the native side was built from. */
+export const SDK_VERSION = '0.1.1';
+
+/** The native module, or null where there is none (iOS, Expo Go, an app not rebuilt). */
+export function nativeModule(): Spec | null {
+  if (Platform.OS !== 'android') return null;
+  return NativeVoltkitRtc ?? null;
+}
+
+let constants: { module: Spec; value: Constants } | null = null;
+let staleWarned = false;
+
+/** The module's constants, read once: the audio mode, screen sharing, the call service as the manifest declares them. */
+export function nativeConstants(): Constants | null {
+  const module = nativeModule();
+  if (!module) return null;
+  if (constants?.module === module) return constants.value;
+  let value: Constants;
+  try {
+    value = module.getConstants();
+  } catch (err) {
+    logError('could not read the native module\'s constants', err);
+    return null;
+  }
+  constants = { module, value };
+  if (!staleWarned && value.nativeVersion && value.nativeVersion !== SDK_VERSION) {
+    staleWarned = true;
+    // eslint-disable-next-line no-console
+    console.warn(`[voltkit-rtc] the app's native code is @voltkit-rtc/react-native ${value.nativeVersion} but its JavaScript is ${SDK_VERSION}: rebuild the app`);
+  }
+  return value;
+}
+
+/** The native module for `feature`, or the error that says why there is none. */
+export function requireNative(feature: string): Spec {
+  if (Platform.OS === 'ios') throw iosUnsupported(feature);
+  const module = nativeModule();
+  if (!module) throw nativeMissing(feature);
+  return module;
+}
+
+/** Subscribe to one of the module's events; a listener that throws is logged and the others still run. */
+export function listen<T>(
+  emitter: ((handler: (value: T) => void) => EventSubscription) | undefined,
+  name: string,
+  listener: (value: T) => void,
+): () => void {
+  if (typeof emitter !== 'function') return () => undefined;
+  const subscription = emitter((value: T) => {
+    try {
+      listener(value);
+    } catch (err) {
+      logError(`listener for ${name} threw`, err);
+    }
+  });
+  return () => subscription.remove();
+}
+
+const AUDIO_TYPES: readonly AudioDeviceType[] = ['speaker', 'earpiece', 'wiredHeadset', 'bluetooth', 'usb', 'builtinMic', 'other'];
+const KINDS: readonly DeviceKind[] = ['audioinput', 'audiooutput', 'videoinput'];
+
+/** A native audio device as the client's MediaDevice. */
+export function toMediaDevice(device: AudioDevice): MediaDevice {
+  const type = AUDIO_TYPES.includes(device.type as AudioDeviceType) ? (device.type as AudioDeviceType) : 'other';
+  const kind = KINDS.includes(device.kind as DeviceKind) ? (device.kind as DeviceKind) : 'audiooutput';
+  return { deviceId: device.deviceId, groupId: device.groupId ?? '', kind, label: device.label, type };
+}
+
+/** For tests: forget the cached constants. */
+export function resetNativeForTests(): void {
+  constants = null;
+  staleWarned = false;
+}

package/src/permissions.ts

@@ -0,0 +1,173 @@
+/**
+ * Camera, microphone and notification permissions.
+ *
+ * Android: PermissionsAndroid. `blocked` is Android's "never ask again" (the user refused twice, or chose "Don't ask
+ * again"): only the app's settings can grant it now. The notification permission (Android 13+, POST_NOTIFICATIONS,
+ * for the call service's notification) is asked only when asked for; below Android 13 there is none to ask.
+ *
+ * iOS (preview): react-native-webrtc's permissions module. iOS asks once: a refusal is `blocked` from then on.
+ *
+ * useLocalMedia().publish() asks for what it needs before any device opens, so a refusal is a `media-unavailable`
+ * error with `{ permission, status }` and the camera light never comes on. The SDK's own captures afterwards (a
+ * reconnect, a switch) only check, never ask: a dialog must not open in the background.
+ */
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { AppState, PermissionsAndroid, Platform, type Permission } from 'react-native';
+import { loadWebRTC } from './globals';
+import { logError } from './errors';
+
+/** What can be asked for. */
+export type PermissionKind = 'camera' | 'microphone' | 'notifications';
+
+/** `granted`; `denied` (not granted yet: asking may still show the dialog); `blocked` (only the settings can grant it). */
+export type PermissionStatus = 'granted' | 'denied' | 'blocked';
+
+export type PermissionStatuses<K extends PermissionKind = PermissionKind> = { [P in K]: PermissionStatus };
+
+const ANDROID: Record<PermissionKind, string> = {
+  camera: 'android.permission.CAMERA',
+  microphone: 'android.permission.RECORD_AUDIO',
+  notifications: 'android.permission.POST_NOTIFICATIONS',
+};
+
+const unique = <K extends PermissionKind>(kinds: readonly K[]): K[] => [...new Set(kinds)];
+
+/** Android 13 and later have a notification permission; below, notifications need none. */
+const notificationsNeedAsking = () => Platform.OS === 'android' && Number(Platform.Version) >= 33;
+
+/**
+ * Ask for these permissions, showing the system's dialogs for those not granted yet. Resolves with each one's status;
+ * never rejects.
+ */
+export async function requestMediaPermissions<K extends PermissionKind>(kinds: readonly K[]): Promise<PermissionStatuses<K>> {
+  const wanted = unique(kinds);
+  const out = {} as PermissionStatuses<K>;
+  if (wanted.length === 0) return out;
+  if (Platform.OS === 'android') {
+    const ask = wanted.filter((k) => k !== 'notifications' || notificationsNeedAsking());
+    for (const kind of wanted) if (!ask.includes(kind)) out[kind] = 'granted';
+    if (ask.length === 0) return out;
+    let results: Record<string, string> = {};
+    try {
+      results = (await PermissionsAndroid.requestMultiple(ask.map((k) => ANDROID[k]) as Permission[])) as Record<string, string>;
+    } catch (err) {
+      logError('could not ask for permissions', err);
+    }
+    for (const kind of ask) out[kind] = androidStatus(results[ANDROID[kind]]);
+    return out;
+  }
+  for (const kind of wanted) out[kind] = await requestIos(kind);
+  return out;
+}
+
+/** Each permission's status now, without asking. Never rejects. */
+export async function checkMediaPermissions<K extends PermissionKind>(kinds: readonly K[]): Promise<PermissionStatuses<K>> {
+  const wanted = unique(kinds);
+  const out = {} as PermissionStatuses<K>;
+  for (const kind of wanted) {
+    if (Platform.OS === 'android') {
+      if (kind === 'notifications' && !notificationsNeedAsking()) {
+        out[kind] = 'granted';
+        continue;
+      }
+      try {
+        out[kind] = (await PermissionsAndroid.check(ANDROID[kind] as Permission)) ? 'granted' : 'denied';
+      } catch (err) {
+        logError('could not check a permission', err);
+        out[kind] = 'denied';
+      }
+    } else {
+      out[kind] = await queryIos(kind);
+    }
+  }
+  return out;
+}
+
+function androidStatus(result: string | undefined): PermissionStatus {
+  if (result === 'granted') return 'granted';
+  if (result === 'never_ask_again') return 'blocked';
+  return 'denied';
+}
+
+async function queryIos(kind: PermissionKind): Promise<PermissionStatus> {
+  // The SDK shows no notification of its own on iOS: nothing to ask.
+  if (kind === 'notifications') return 'granted';
+  const webrtc = loadWebRTC();
+  if (!webrtc) return 'denied';
+  try {
+    const result = await webrtc.permissions.query({ name: kind });
+    if (result === 'granted') return 'granted';
+    return result === 'denied' ? 'blocked' : 'denied';
+  } catch (err) {
+    logError('could not check a permission', err);
+    return 'denied';
+  }
+}
+
+async function requestIos(kind: PermissionKind): Promise<PermissionStatus> {
+  const now = await queryIos(kind);
+  if (now !== 'denied') return now;
+  const webrtc = loadWebRTC();
+  if (!webrtc) return 'denied';
+  try {
+    return (await webrtc.permissions.request({ name: kind })) ? 'granted' : 'blocked';
+  } catch (err) {
+    logError('could not ask for a permission', err);
+    return 'denied';
+  }
+}
+
+export interface Permissions<K extends PermissionKind = PermissionKind> {
+  /** Each permission's status; null until first checked. Checked again whenever the app comes back to the front. */
+  statuses: PermissionStatuses<K> | null;
+  /** Every one granted. */
+  granted: boolean;
+  /** Ask for those not granted (the system's dialogs); resolves with the statuses. */
+  request(): Promise<PermissionStatuses<K>>;
+  /** Check again without asking. */
+  refresh(): Promise<PermissionStatuses<K>>;
+}
+
+/**
+ * The status of these permissions, checked on mount and whenever the app returns to the front (the user may have
+ * changed them in the settings), with `request()` to ask for them.
+ */
+export function usePermissions<K extends PermissionKind>(kinds: readonly K[]): Permissions<K> {
+  const key = unique(kinds).sort().join(',');
+  const wanted = useMemo(() => (key ? (key.split(',') as K[]) : []), [key]);
+  const [statuses, setStatuses] = useState<PermissionStatuses<K> | null>(null);
+  const live = useRef(true);
+
+  const refresh = useCallback(async () => {
+    const next = await checkMediaPermissions(wanted);
+    if (live.current) setStatuses((previous) => (same(previous, next) ? previous : next));
+    return next;
+  }, [wanted]);
+
+  const request = useCallback(async () => {
+    const next = await requestMediaPermissions(wanted);
+    if (live.current) setStatuses((previous) => (same(previous, next) ? previous : next));
+    return next;
+  }, [wanted]);
+
+  useEffect(() => {
+    live.current = true;
+    void refresh();
+    const subscription = AppState.addEventListener('change', (state) => {
+      if (state === 'active') void refresh();
+    });
+    return () => {
+      live.current = false;
+      subscription?.remove();
+    };
+  }, [refresh]);
+
+  const granted = statuses !== null && wanted.every((k) => statuses[k] === 'granted');
+  return useMemo(() => ({ statuses, granted, request, refresh }), [statuses, granted, request, refresh]);
+}
+
+function same<K extends PermissionKind>(a: PermissionStatuses<K> | null, b: PermissionStatuses<K>): boolean {
+  if (!a) return false;
+  const keys = Object.keys(b) as K[];
+  return keys.length === Object.keys(a).length && keys.every((k) => a[k] === b[k]);
+}