@q9labsai/chalk-react-native 4.1.16 → 5.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Q9Labs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING FROM,
+OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,52 +1,157 @@
 # @q9labsai/chalk-react-native
 
-React Native bindings and native platform adapters for Chalk.
+React Native bindings, native platform adapters and the drop-in call view for Chalk.
 
-The root package exports exactly:
+## Install
 
-- Components: `Chalk`, `Entrance`.
-- Context: `ChalkProvider`, `useSpaceClient`.
-- Snapshot hooks: `useCan`, `useChat`, `useConnection`, `useMedia`,
-  `useParticipants`, `useReactions`, `useSelf`, and `useWhiteboard`.
-- Types: `ChalkFeatures`, `ChalkProps`, `ChalkTheme`, `ChalkThemeTokens`,
-  `SpaceLayout`, `EntranceProps`, `EntranceSettings`, and `ChalkProviderProps`.
+Install the SDK with every native module it needs as a peer, at the versions your Expo SDK pins:
+
+```sh
+npx expo install @q9labsai/chalk-client @q9labsai/chalk-react-native @cloudflare/react-native-webrtc react-native-webview react-native-reanimated react-native-worklets react-native-gesture-handler react-native-safe-area-context react-native-svg expo-audio expo-haptics expo-clipboard expo-document-picker expo-file-system
+```
+
+The app must also embed the Figtree font (Regular, Medium, SemiBold and Bold) with the `expo-font` config plugin.
+
+The root package exports:
+
+- Call view: `Chalk`, `ChalkProps`, `Permission`, `ColorScheme`, and `Palette`.
+- Before the call: `ChalkArrival`, `ChalkArrivalProps`, and `ArrivalState`.
+- Context: `ChalkProvider`, `useSpaceClient`, and `ChalkProviderProps`.
+- Snapshot hooks: `useCan`, `useChat`, `useConnection`, `useMedia`, `useParticipants`, `useReactions`, `useRecording`, `useSelf`, and `useWhiteboard`.
+- Invite helpers: `extractSpaceInviteFromLink`, `getClipboardInviteSuggestion`, `parseSpaceInviteLink`, `buildChalkInviteLink`, and `SpaceInviteLink`.
+
+Use `ChalkProvider` instead of `Chalk` to build your own call UI. It receives a `SpaceClient`. Components inside the provider can read snapshots with the hooks and access client actions through `useSpaceClient`. The application owns joining, leaving, disposing the client, and rendering its UI.
+
+## Call view
+
+`Chalk` draws the whole call: header, stage, dock, sheets, menus and toasts. It fills the screen it's given, joins muted with the camera off, and keeps every control inside the safe area in portrait and landscape. It covers the call while it joins or reconnects, and shows a page when the call is over.
+
+```tsx
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { Chalk, type ColorScheme } from "@q9labsai/chalk-react-native";
+import { useState } from "react";
+
+export function DesignReview({ client, onLeave, onRejoin }: { readonly client: SpaceClient; readonly onLeave: () => void; readonly onRejoin: () => void }) {
+  const [colorScheme, setColorScheme] = useState<ColorScheme>("dark");
+  const [soundsEnabled, setSoundsEnabled] = useState(true);
+  return <Chalk callName="Design review" client={client} colorScheme={colorScheme} inviteLink="https://chalk.example/design-review" onColorSchemeChange={setColorScheme} onLeave={onLeave} onRejoin={onRejoin} onSoundsEnabledChange={setSoundsEnabled} soundsEnabled={soundsEnabled} />;
+}
+```
+
+`Chalk` lays out the call itself, so the stage needs no props. It switches between Spotlight and Grid, moves the active speaker into the spotlight, and sizes screen shares to their shape. iPad uses the phone layout in 5.0.0.
+
+| Prop                    | Type                                 | What it does                                                                                                                                                                                                          |
+| ----------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `client`                | `SpaceClient`                        | The call's client. The app creates it with `createNativeSpaceClient` and disposes it. `Chalk` joins it.                                                                                                               |
+| `displayName`           | `string`                             | The name others see. Without it, the server's stored name is used.                                                                                                                                                    |
+| `callName`              | `string`                             | The call's name in the header, such as "Q9 team". Tapping it opens the call details.                                                                                                                                  |
+| `inviteLink`            | `string`                             | The call's link. More offers to copy and share it, and the call details show it with copy, share and a QR code. Without it, they leave those rows out.                                                                |
+| `colorScheme`           | `"dark" \| "light"`                  | The call's look. Dark by default.                                                                                                                                                                                     |
+| `onColorSchemeChange`   | `(colorScheme: ColorScheme) => void` | Called when the person changes the look in the call details.                                                                                                                                                          |
+| `soundsEnabled`         | `boolean`                            | Call sounds. On by default.                                                                                                                                                                                           |
+| `onSoundsEnabledChange` | `(enabled: boolean) => void`         | Called when the person turns call sounds on or off.                                                                                                                                                                   |
+| `onLeave`               | `() => void`                         | Called when the person is done with the call: from Home on the page that shows after they leave, the call ends, it fails, or they were removed.                                                                       |
+| `onRejoin`              | `() => void`                         | Called when the person chooses Rejoin or Try again on a page that shows after they leave, the call ends, or it fails. Give the arrival back and render `Chalk` again with a new client, since the old one can't join. |
+| `onOpenSettings`        | `(permission: Permission) => void`   | Called just before Open Settings takes the person to the system settings to allow the microphone or camera.                                                                                                           |
+| `resumedAfterSettings`  | `Permission`                         | Set when the app opens the call again after Open Settings. The call says "Rejoining" and then that it can use the device now.                                                                                         |
+
+`Permission` is `"microphone" | "camera"`.
+
+Leaving no longer calls `onLeave` straight away. The "You left" page shows first, with Rejoin and Home, and only Home calls `onLeave`. This is a breaking change from 4.x.
+
+Rejoin and Try again call `onRejoin`, not `onLeave`. Give the arrival back there, then render `Chalk` again with a new client. The client that left or ended can't join the call a second time.
+
+The person can switch the look and call sounds from the call details. The example keeps both in state. To keep the person's choice, store both through the change callbacks and pass them back on the next launch. Load them before you render `Chalk`, so the first frame already has the right theme.
+
+### After a permission change
+
+When the microphone or camera isn't allowed, the call shows a notice with Open Settings. iOS restarts the app when a permission changes, so the call is gone when the person comes back. Store the call in `onOpenSettings`, and on the next launch open it again with `resumedAfterSettings`:
 
 ```tsx
-import { Chalk } from "@q9labsai/chalk-react-native";
+import type { SpaceClient } from "@q9labsai/chalk-client";
+import { Chalk, type Permission } from "@q9labsai/chalk-react-native";
 
-export function SpaceScreen() {
-  return <Chalk displayName="Taylor" getAccess={getAccess} logoUrl="https://example.com/logo.png" space="design-review" theme={{ colorScheme: "dark", accent: "#14b8a6" }} />;
+type ResumableCallProps = {
+  readonly client: SpaceClient;
+  readonly resumed?: Permission;
+  readonly saveResume: (permission: Permission) => void;
+  readonly onLeave: () => void;
+  readonly onRejoin: () => void;
+};
+
+export function ResumableCall({ client, resumed, saveResume, onLeave, onRejoin }: ResumableCallProps) {
+  return <Chalk callName="Design review" client={client} onLeave={onLeave} onOpenSettings={saveResume} onRejoin={onRejoin} resumedAfterSettings={resumed} />;
 }
 ```
 
-`Chalk` can instead receive an existing `SpaceClient` through `client`. Set
-`entrance={false}` to join immediately; an absent display name is omitted from
-the join request. The native experience has focus, grid, and presentation
-layouts, and `features.settings` is enabled unless explicitly set to `false`.
+Clear the stored call once you read it, so a later launch doesn't rejoin.
+
+## Before the call lets you in
+
+`ChalkArrival` draws the screens before `Chalk` joins, for a call that asks the host first. Render it in place of `Chalk` while the arrival is pending (`state="knocking"`), after the host denies it (`"refused"`), or when the call is full (`"full"`). Render `Chalk` once the person is let in.
 
-## Feedback
+```tsx
+import { type ArrivalState, ChalkArrival } from "@q9labsai/chalk-react-native";
 
-The Space action menu includes Feedback. It captures only the Chalk-owned native
-view, shows a removable or refreshable preview, and sends bounded Journey,
-trace, runtime, and diagnostic context directly to Chalk. Capture failures and
-unsupported macOS native capture never block the message.
+export function Arrival({ state, onCancel, onRetry }: { readonly state: ArrivalState; readonly onCancel: () => void; readonly onRetry: () => void }) {
+  return <ChalkArrival callName="Design review" onCancel={onCancel} onRetry={onRetry} state={state} />;
+}
+```
 
-The host app must install the `react-native-view-shot` peer dependency.
-Embedded products use the default `embedded` source; Chalk's mobile app
-configures `chalk_mobile`.
+| Prop          | Type                                | What it does                                                                                                                                     |
+| ------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `state`       | `"knocking" \| "refused" \| "full"` | Which screen to show: "Asking to join" with Cancel, "The host didn't let you in" with Ask again, or "This call is full" with Try again and Home. |
+| `callName`    | `string`                            | The call's name, such as "Q9 team".                                                                                                              |
+| `colorScheme` | `"dark" \| "light"`                 | Dark by default, like `Chalk`.                                                                                                                   |
+| `onCancel`    | `() => void`                        | Stops waiting: Cancel while knocking, Home when the call is full, and Android back.                                                              |
+| `onRetry`     | `() => void`                        | Knocks again after a refusal, or tries again once a full call has room.                                                                          |
+| `recording`   | `boolean`                           | Shows recording consent while knocking on a recorded call.                                                                                       |
 
-The platform subpaths (`android`, `ios`, `ios-phone`, `ios-pad`, and `macos`)
-export the same public surface as the root package.
+## Your own screens
+
+`@q9labsai/chalk-react-native/ui` gives an app's own screens, such as its Home or name step, the same look as the call. Wrap them in `ChalkUI`, which provides the theme, safe areas, sheets, menus and toasts, and build them from the call's primitives.
+
+```tsx
+import { ChalkText, ChalkUI, PillButton } from "@q9labsai/chalk-react-native/ui";
+
+export function Home({ onStart }: { readonly onStart: () => void }) {
+  return (
+    <ChalkUI colorScheme="dark">
+      <ChalkText>Start a call or join with a link.</ChalkText>
+      <PillButton label="Start a call" onPress={onStart} />
+    </ChalkUI>
+  );
+}
+```
+
+The entry exports:
+
+- Frame: `ChalkUI` and `ChalkUIProps`.
+- Theme: `useTheme`, `Theme`, `fixed`, `fontFamilies`, `radii`, `type`, `ColorScheme`, `Palette`, and `useDeviceLayout`.
+- Icons: `Icon` and `IconName`.
+- Primitives: `ChalkText`, `IconButton`, `PillButton`, `BottomSheet`, `SheetGroup`, `SheetRow`, `Menu`, `MenuItem`, `Switch`, `SegmentedControl`, `CopyButton`, `FaceAvatar`, `useToasts`, `announce`, `usePressAnimation`, and `Limbo`.
 
 ## Native client adapter
 
-For advanced lifecycle ownership, import the React Native implementation seam
-from `@q9labsai/chalk-react-native/client`. It exposes only
-`createNativeSpaceClient` and `NativeSpaceClientOptions`; it does not add a
-second root binding shape.
+`@q9labsai/chalk-react-native/client` exports `createNativeSpaceClient` and `NativeSpaceClientOptions`. The native client connects Chalk to React Native media and application lifecycle APIs.
 
 ```tsx
 import { createNativeSpaceClient } from "@q9labsai/chalk-react-native/client";
 
 const client = createNativeSpaceClient({ space: "design-review", getAccess });
 ```
+
+The `runtime`, `clipboard`, `diagnostics`, and `invites` subpaths expose native runtime information, clipboard access, diagnostics state, and invite parsing respectively.
+
+## Development entry
+
+`@q9labsai/chalk-react-native/dev` is for development only. `setMeasurementRegistry` reports each call surface's frame and declared style by testID, and `setDevScenario` opens a sheet or menu and draws fake video in tiles. Require it behind `__DEV__`, so Metro leaves it out of release bundles:
+
+```js
+if (__DEV__) {
+  const { setDevScenario } = require("@q9labsai/chalk-react-native/dev");
+  setDevScenario({ sheet: "more" });
+}
+```
+
+Don't import it at the top of a file. A static import puts it in every bundle.

package/android/src/main/AndroidManifest.xml

@@ -19,6 +19,7 @@
       android:name=".ChalkSpaceForegroundService"
       android:enabled="true"
       android:exported="false"
-      android:foregroundServiceType="camera|microphone" />
+      android:foregroundServiceType="camera|microphone"
+      android:stopWithTask="true" />
   </application>
 </manifest>

package/android/src/main/java/ai/q9labs/chalk/reactnative/ChalkSpaceForegroundService.java

@@ -1,74 +1,140 @@
 package ai.q9labs.chalk.reactnative;
 
+import android.Manifest;
 import android.app.Notification;
 import android.app.NotificationChannel;
 import android.app.NotificationManager;
+import android.app.PendingIntent;
 import android.app.Service;
+import android.content.ComponentName;
 import android.content.Context;
 import android.content.Intent;
+import android.content.pm.PackageManager;
 import android.content.pm.ServiceInfo;
 import android.os.Build;
 import android.os.IBinder;
+import android.util.Log;
 
 import androidx.core.app.NotificationCompat;
+import androidx.core.content.ContextCompat;
 
+/**
+ * Keeps a call's microphone and camera working in the background. Android 11 and later cut off a
+ * background app's audio and video input unless a foreground service of that type runs. Android 14
+ * throws when a type's permission is missing, so the service declares only the types granted.
+ */
 public class ChalkSpaceForegroundService extends Service {
-    static final String ACTION_START = "ai.q9labs.chalk.reactnative.action.START_BACKGROUND_SPACE";
-    static final String ACTION_STOP = "ai.q9labs.chalk.reactnative.action.STOP_BACKGROUND_SPACE";
-    static final String EXTRA_SPACE_NAME = "spaceName";
-    static final String EXTRA_PARTICIPANT_NAME = "participantName";
-    static final String EXTRA_CAMERA_OFF = "cameraOff";
-    private static final String CHANNEL_ID = "chalk_space_background";
+    private static final String TAG = "ChalkCallService";
+    private static final String CHANNEL_ID = "chalk_call_background";
     private static final int NOTIFICATION_ID = 19487;
 
+    // Main thread only, like the service's own callbacks. Android crashes the app when a service started
+    // with startForegroundService() stops before it calls startForeground(), so nothing outside the service
+    // stops it: a stop asks the live service to stop through stopSelfResult(), which does nothing while a
+    // newer start is still on its way, and every delivered start promotes first, then stops if the call is over.
+    private static boolean wanted;
+    private static ChalkSpaceForegroundService live;
+    private int lastStartId = NO_START;
+    private static final int NO_START = -1;
+
+    /** Asks for the service on the main thread. Returns false when nothing is granted or Android refuses the start. */
+    static boolean requestStart(Context context) {
+        if (grantedForegroundTypes(context) == 0) {
+            return false;
+        }
+        wanted = true;
+        Intent intent = new Intent(context, ChalkSpaceForegroundService.class);
+        try {
+            ComponentName started = Build.VERSION.SDK_INT >= Build.VERSION_CODES.O ? context.startForegroundService(intent) : context.startService(intent);
+            return started != null;
+        } catch (RuntimeException error) {
+            Log.w(TAG, "Couldn't start the call's foreground service", error);
+            return false;
+        }
+    }
+
+    /** Stops the service on the main thread once its latest start has promoted it. */
+    static void requestStop() {
+        wanted = false;
+        if (live != null && live.lastStartId != NO_START) {
+            live.stopSelfResult(live.lastStartId);
+        }
+    }
+
+    /** The foreground types the person has granted: microphone and camera, or 0 when neither is granted. */
+    static int grantedForegroundTypes(Context context) {
+        int types = 0;
+        if (isGranted(context, Manifest.permission.RECORD_AUDIO)) {
+            types |= ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE;
+        }
+        if (isGranted(context, Manifest.permission.CAMERA)) {
+            types |= ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
+        }
+        return types;
+    }
+
+    private static boolean isGranted(Context context, String permission) {
+        return ContextCompat.checkSelfPermission(context, permission) == PackageManager.PERMISSION_GRANTED;
+    }
+
     @Override
     public IBinder onBind(Intent intent) {
         return null;
     }
 
+    @Override
+    public void onCreate() {
+        super.onCreate();
+        live = this;
+    }
+
     @Override
     public int onStartCommand(Intent intent, int flags, int startId) {
-        String action = intent != null ? intent.getAction() : null;
-        if (ACTION_STOP.equals(action)) {
-            stopForeground(STOP_FOREGROUND_REMOVE);
-            stopSelf();
+        lastStartId = startId;
+        int foregroundTypes = grantedForegroundTypes(this);
+        if (foregroundTypes == 0) {
+            stopSelfResult(startId);
             return START_NOT_STICKY;
         }
 
         ensureNotificationChannel();
-
-        String spaceName = intent != null ? intent.getStringExtra(EXTRA_SPACE_NAME) : null;
-        String participantName = intent != null ? intent.getStringExtra(EXTRA_PARTICIPANT_NAME) : null;
-        boolean cameraOff = intent != null && intent.getBooleanExtra(EXTRA_CAMERA_OFF, false);
-        Notification notification = buildNotification(spaceName, participantName, cameraOff);
+        Notification notification = buildNotification();
 
         try {
             if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
-                int foregroundType = ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE;
-                if (!cameraOff) {
-                    foregroundType |= ServiceInfo.FOREGROUND_SERVICE_TYPE_CAMERA;
-                }
-                startForeground(NOTIFICATION_ID, notification, foregroundType);
+                startForeground(NOTIFICATION_ID, notification, foregroundTypes);
             } else {
                 startForeground(NOTIFICATION_ID, notification);
             }
         } catch (RuntimeException error) {
-            stopSelf();
+            Log.w(TAG, "Couldn't start the call's foreground service", error);
+            stopSelfResult(startId);
+            return START_NOT_STICKY;
+        }
+
+        if (!wanted) {
+            stopSelfResult(startId);
         }
 
-        return START_STICKY;
+        // Not sticky: a call can't resume after the process is killed, so a restart would leave a notification with no call behind it.
+        return START_NOT_STICKY;
     }
 
-    private Notification buildNotification(String spaceName, String participantName, boolean cameraOff) {
-        String title = spaceName != null && !spaceName.trim().isEmpty() ? spaceName.trim() : "Chalk Space in progress";
-        String subtitle = participantName != null && !participantName.trim().isEmpty() ? participantName.trim() : "Your Space stays live in the background";
-        String detail = cameraOff ? "Audio stays live while you multitask." : "Video and audio stay live while you multitask.";
+    @Override
+    public void onDestroy() {
+        if (live == this) {
+            live = null;
+        }
+        stopForeground(STOP_FOREGROUND_REMOVE);
+        super.onDestroy();
+    }
 
+    private Notification buildNotification() {
         return new NotificationCompat.Builder(this, CHANNEL_ID)
                 .setCategory(NotificationCompat.CATEGORY_CALL)
-                .setContentTitle(title)
-                .setContentText(subtitle)
-                .setStyle(new NotificationCompat.BigTextStyle().bigText(detail))
+                .setContentTitle("Chalk call in progress")
+                .setContentText("Tap to return to the call")
+                .setContentIntent(openAppIntent())
                 .setForegroundServiceBehavior(NotificationCompat.FOREGROUND_SERVICE_IMMEDIATE)
                 .setOngoing(true)
                 .setOnlyAlertOnce(true)
@@ -77,6 +143,14 @@ public class ChalkSpaceForegroundService extends Service {
                 .build();
     }
 
+    private PendingIntent openAppIntent() {
+        Intent launch = getPackageManager().getLaunchIntentForPackage(getPackageName());
+        if (launch == null) {
+            return null;
+        }
+        return PendingIntent.getActivity(this, 0, launch, PendingIntent.FLAG_UPDATE_CURRENT | PendingIntent.FLAG_IMMUTABLE);
+    }
+
     private void ensureNotificationChannel() {
         if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
             return;
@@ -87,8 +161,8 @@ public class ChalkSpaceForegroundService extends Service {
             return;
         }
 
-        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, "Chalk background Space", NotificationManager.IMPORTANCE_LOW);
-        channel.setDescription("Keeps Chalk Spaces active while the app is in the background");
+        NotificationChannel channel = new NotificationChannel(CHANNEL_ID, "Chalk call", NotificationManager.IMPORTANCE_LOW);
+        channel.setDescription("Keeps the microphone and camera on while Chalk is in the background");
         manager.createNotificationChannel(channel);
     }
 }

package/android/src/main/kotlin/ai/q9labs/chalk/reactnative/ChalkAndroidConnectionServicePackage.kt

@@ -9,6 +9,8 @@ class ChalkAndroidConnectionServicePackage : ReactPackage {
   override fun createNativeModules(reactContext: ReactApplicationContext): List<NativeModule> {
     return listOf(
       ChalkAndroidConnectionServiceModule(reactContext),
+      ChalkAudioRouteModule(reactContext),
+      ChalkCallServiceModule(reactContext),
     )
   }
 

package/android/src/main/kotlin/ai/q9labs/chalk/reactnative/ChalkAudioRouteModule.kt

@@ -0,0 +1,138 @@
+package ai.q9labs.chalk.reactnative
+
+import android.content.Context
+import android.media.AudioDeviceCallback
+import android.media.AudioDeviceInfo
+import android.media.AudioManager
+import android.os.Build
+import android.os.Handler
+import android.os.Looper
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.WritableMap
+import com.facebook.react.modules.core.DeviceEventManagerModule
+
+/**
+ * Lists the call's audio outputs and switches between them. Android 12 and later pick any
+ * communication device (earpiece, speaker, wired or Bluetooth headset); older versions switch
+ * only between the earpiece and the speaker.
+ */
+class ChalkAudioRouteModule(
+  private val reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+  private val audioManager = reactContext.getSystemService(Context.AUDIO_SERVICE) as AudioManager
+  private val handler = Handler(Looper.getMainLooper())
+  private var listening = false
+
+  private val deviceCallback = object : AudioDeviceCallback() {
+    override fun onAudioDevicesAdded(addedDevices: Array<out AudioDeviceInfo>) = emit()
+    override fun onAudioDevicesRemoved(removedDevices: Array<out AudioDeviceInfo>) = emit()
+  }
+  // Created only on Android 12 and later, where the listener type exists.
+  private val communicationListener by lazy { AudioManager.OnCommunicationDeviceChangedListener { emit() } }
+
+  override fun getName(): String = "ChalkAudioRouteModule"
+
+  override fun getConstants(): Map<String, Any> = mapOf("eventName" to EVENT_NAME)
+
+  @ReactMethod
+  fun addListener(eventName: String) {
+    if (listening) return
+    listening = true
+    audioManager.registerAudioDeviceCallback(deviceCallback, handler)
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      audioManager.addOnCommunicationDeviceChangedListener(reactContext.mainExecutor, communicationListener)
+    }
+  }
+
+  @ReactMethod
+  fun removeListeners(count: Int) {
+    // The listeners stay until the module goes away; NativeEventEmitter needs this method.
+  }
+
+  override fun invalidate() {
+    if (listening) {
+      audioManager.unregisterAudioDeviceCallback(deviceCallback)
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+        audioManager.removeOnCommunicationDeviceChangedListener(communicationListener)
+      }
+    }
+    super.invalidate()
+  }
+
+  @ReactMethod
+  fun getRoutes(promise: Promise) {
+    promise.resolve(snapshot())
+  }
+
+  @ReactMethod
+  fun selectRoute(id: String, promise: Promise) {
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      val device = audioManager.availableCommunicationDevices.firstOrNull { routeId(it) == id }
+      if (device == null || !audioManager.setCommunicationDevice(device)) {
+        promise.reject("audio_route_failed", "Couldn't switch the audio output to $id.")
+        return
+      }
+    } else {
+      @Suppress("DEPRECATION")
+      audioManager.isSpeakerphoneOn = id == SPEAKER
+    }
+    promise.resolve(snapshot())
+  }
+
+  private fun emit() {
+    if (!reactContext.hasActiveReactInstance()) return
+    reactContext.getJSModule(DeviceEventManagerModule.RCTDeviceEventEmitter::class.java).emit(EVENT_NAME, snapshot())
+  }
+
+  private fun snapshot(): WritableMap {
+    val routes = Arguments.createArray()
+    val result = Arguments.createMap()
+    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S) {
+      for (device in audioManager.availableCommunicationDevices) {
+        val kind = kindOf(device.type) ?: continue
+        routes.pushMap(route(routeId(device), kind, if (kind == "bluetooth" || kind == "wired") device.productName.toString() else ""))
+      }
+      result.putString("selected", audioManager.communicationDevice?.let { routeId(it) } ?: EARPIECE)
+    } else {
+      routes.pushMap(route(EARPIECE, EARPIECE, ""))
+      routes.pushMap(route(SPEAKER, SPEAKER, ""))
+      @Suppress("DEPRECATION")
+      result.putString("selected", if (audioManager.isSpeakerphoneOn) SPEAKER else EARPIECE)
+    }
+    result.putArray("routes", routes)
+    return result
+  }
+
+  private fun route(id: String, kind: String, name: String): WritableMap =
+    Arguments.createMap().apply {
+      putString("id", id)
+      putString("kind", kind)
+      putString("name", name)
+    }
+
+  private fun routeId(device: AudioDeviceInfo): String =
+    when (device.type) {
+      AudioDeviceInfo.TYPE_BUILTIN_EARPIECE -> EARPIECE
+      AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> SPEAKER
+      else -> device.id.toString()
+    }
+
+  private fun kindOf(type: Int): String? =
+    when (type) {
+      AudioDeviceInfo.TYPE_BUILTIN_EARPIECE -> EARPIECE
+      AudioDeviceInfo.TYPE_BUILTIN_SPEAKER -> SPEAKER
+      AudioDeviceInfo.TYPE_BLUETOOTH_SCO, AudioDeviceInfo.TYPE_BLE_HEADSET -> "bluetooth"
+      AudioDeviceInfo.TYPE_WIRED_HEADSET, AudioDeviceInfo.TYPE_WIRED_HEADPHONES, AudioDeviceInfo.TYPE_USB_HEADSET -> "wired"
+      else -> null
+    }
+
+  private companion object {
+    const val EVENT_NAME = "ChalkAudioRouteChanged"
+    const val EARPIECE = "earpiece"
+    const val SPEAKER = "speaker"
+  }
+}

package/android/src/main/kotlin/ai/q9labs/chalk/reactnative/ChalkCallServiceModule.kt

@@ -0,0 +1,32 @@
+package ai.q9labs.chalk.reactnative
+
+import android.os.Handler
+import android.os.Looper
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+
+/** Starts and stops the foreground service that keeps a call's microphone and camera working in the background. */
+class ChalkCallServiceModule(
+  private val reactContext: ReactApplicationContext,
+) : ReactContextBaseJavaModule(reactContext) {
+  override fun getName(): String = "ChalkCallService"
+
+  /** Resolves false when the person hasn't granted the microphone or camera, or when Android refuses the start. The call continues either way. */
+  @ReactMethod
+  fun start(promise: Promise) {
+    // The service keeps its start and stop state on the main thread, where its own callbacks run.
+    mainThread.post { promise.resolve(ChalkSpaceForegroundService.requestStart(reactContext)) }
+  }
+
+  @ReactMethod
+  fun stop(promise: Promise) {
+    mainThread.post {
+      ChalkSpaceForegroundService.requestStop()
+      promise.resolve(null)
+    }
+  }
+
+  private val mainThread = Handler(Looper.getMainLooper())
+}

package/dist/android/call-service.d.ts

@@ -0,0 +1,4 @@
+/** Starts the Android foreground service for the call. Resolves false when there's nothing to keep running (no microphone or camera permission) or Android refused the start. */
+export declare function startAndroidCallService(): Promise<boolean>;
+export declare function stopAndroidCallService(): Promise<void>;
+//# sourceMappingURL=call-service.d.ts.map

package/dist/android/call-service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"call-service.d.ts","sourceRoot":"","sources":["../../src/android/call-service.ts"],"names":[],"mappings":"AASA,iLAAiL;AACjL,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,OAAO,CAAC,CAGhE;AAED,wBAAsB,sBAAsB,IAAI,OAAO,CAAC,IAAI,CAAC,CAG5D"}

package/dist/avatar/FaceAvatar.d.ts

@@ -0,0 +1,19 @@
+import { type SharedValue } from "react-native-reanimated";
+export type FaceAvatarProps = {
+    readonly name: string;
+    readonly size: number;
+    /** `bold` is the 3D style for tiles; `subtle` is for rows, pills, chat and toasts. */
+    readonly style?: "bold" | "subtle";
+    /** Live speaking level from 0 to 1. While it moves, the face bobs and the mouth opens. */
+    readonly level?: SharedValue<number>;
+    /** Eyes drift on their own every 1.8 s, as on the mockup's touch devices. Off for small avatars. */
+    readonly lookAround?: boolean;
+    readonly testID?: string;
+};
+/**
+ * A Facehash avatar drawn natively. The face blinks on its own rhythm, reacts to the speaking
+ * level, and turns to the front for a moment when touched. All motion runs on the UI thread and
+ * stops with reduced motion. Decorative: the parent names the person.
+ */
+export declare const FaceAvatar: import("react").MemoExoticComponent<({ name, size, style, level, lookAround, testID }: FaceAvatarProps) => React.JSX.Element>;
+//# sourceMappingURL=FaceAvatar.d.ts.map

package/dist/avatar/FaceAvatar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FaceAvatar.d.ts","sourceRoot":"","sources":["../../src/avatar/FaceAvatar.tsx"],"names":[],"mappings":"AAGA,OAAiB,EAAwH,KAAK,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAK3L,MAAM,MAAM,eAAe,GAAG;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,sFAAsF;IACtF,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACnC,0FAA0F;IAC1F,QAAQ,CAAC,KAAK,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,oGAAoG;IACpG,QAAQ,CAAC,UAAU,CAAC,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAWF;;;;GAIG;AACH,eAAO,MAAM,UAAU,yFAAiG,eAAe,KAAG,KAAK,CAAC,GAAG,CAAC,OAAO,CAwGzJ,CAAC"}

package/dist/avatar/tile-avatar-size.d.ts

@@ -0,0 +1,3 @@
+/** A camera-off tile's avatar is 42 % of the tile's shorter side, between 32 and 150 pt. */
+export declare function tileAvatarSize(width: number, height: number): number;
+//# sourceMappingURL=tile-avatar-size.d.ts.map

package/dist/avatar/tile-avatar-size.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tile-avatar-size.d.ts","sourceRoot":"","sources":["../../src/avatar/tile-avatar-size.ts"],"names":[],"mappings":"AAAA,4FAA4F;AAC5F,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAEpE"}