@q9labsai/chalk-react-native 4.1.17 → 5.0.1

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/build.gradle

@@ -41,3 +41,38 @@ dependencies {
   implementation("com.facebook.react:react-android")
   implementation("androidx.core:core:1.16.0")
 }
+
+def compatibilityClasses = layout.buildDirectory.dir("compatibility/classes")
+def compileCompatibility = tasks.register("compileModuleApiCompatibility", JavaCompile) {
+  source fileTree("compatibility") { include "*.java" }
+  classpath = files()
+  destinationDirectory = compatibilityClasses
+  sourceCompatibility = "17"
+  targetCompatibility = "17"
+}
+
+// Check the bytecode RN actually reflects, including inferred/private/synthetic getters.
+tasks.register("checkModuleApiCompatibility", JavaExec) {
+  dependsOn compileCompatibility, "compileDebugKotlin", "compileDebugJavaWithJavac",
+      "compileDebugUnitTestKotlin"
+  classpath = files(compatibilityClasses)
+  mainClass = "ModuleApiCompatibility"
+  doFirst {
+    def manifest = layout.buildDirectory.file("compatibility/classpath.txt").get().asFile
+    def paths = [android.bootClasspath.first(),
+        tasks.named("compileDebugUnitTestKotlin").get().destinationDirectory.get().asFile,
+        tasks.named("compileDebugKotlin").get().destinationDirectory.get().asFile,
+        tasks.named("compileDebugJavaWithJavac").get().destinationDirectory.get().asFile]
+    paths.addAll(configurations.debugCompileClasspath.files)
+    manifest.text = paths.collect { it.absolutePath }.join("\n")
+    def platforms = [android.defaultConfig.minSdkVersion.apiLevel, 30].unique().collect {
+      new File(android.sdkDirectory, "platforms/android-${it}/android.jar")
+    }
+    platforms.each {
+      if (!it.isFile()) throw new GradleException("Install compatibility platform: sdkmanager 'platforms;${it.parentFile.name}'")
+    }
+    args = [manifest.absolutePath, layout.buildDirectory.dir("compatibility/dependencies").get().asFile.absolutePath] + platforms*.absolutePath
+  }
+}
+
+tasks.named("check").configure { dependsOn "checkModuleApiCompatibility" }

package/android/compatibility/ModuleApiCompatibility.java

@@ -0,0 +1,215 @@
+import java.io.*;
+import java.net.*;
+import java.nio.file.*;
+import java.util.*;
+import java.util.jar.JarFile;
+import java.util.regex.Pattern;
+import java.util.zip.ZipFile;
+
+/** Runs without Android initialization: RN reflects private and synthetic members too. */
+public final class ModuleApiCompatibility {
+  private static final Set<String> ROOTS = Set.of(
+      "com/facebook/react/bridge/NativeModule", "com/facebook/react/uimanager/ViewManager");
+  private static final Pattern TYPE = Pattern.compile("L([^;]+);");
+
+  record Member(String name, String descriptor) {}
+  record ClassInfo(String name, List<String> parents, List<Member> members) {}
+
+  private static ClassInfo readClass(InputStream stream) throws IOException {
+    try (var in = new DataInputStream(stream)) {
+      if (in.readInt() != 0xcafebabe) throw new IOException("Not a class file");
+      in.skipNBytes(4);
+      Object[] pool = new Object[in.readUnsignedShort()];
+      for (int i = 1; i < pool.length; i++) {
+        switch (in.readUnsignedByte()) {
+          case 1 -> pool[i] = in.readUTF();
+          case 7 -> pool[i] = in.readUnsignedShort();
+          case 3, 4, 9, 10, 11, 12, 17, 18 -> in.skipNBytes(4);
+          case 5, 6 -> { in.skipNBytes(8); i++; }
+          case 8, 16, 19, 20 -> in.skipNBytes(2);
+          case 15 -> in.skipNBytes(3);
+          default -> throw new IOException("Unknown constant pool entry");
+        }
+      }
+      in.readUnsignedShort();
+      String name = (String) pool[(int) pool[in.readUnsignedShort()]];
+      var parents = new ArrayList<String>();
+      int superclass = in.readUnsignedShort();
+      if (superclass != 0) parents.add((String) pool[(int) pool[superclass]]);
+      int interfaces = in.readUnsignedShort();
+      for (int i = 0; i < interfaces; i++) {
+        parents.add((String) pool[(int) pool[in.readUnsignedShort()]]);
+      }
+      var members = new ArrayList<Member>();
+      // Both field_info and method_info have the same layout.
+      for (int kind = 0; kind < 2; kind++) {
+        int count = in.readUnsignedShort();
+        for (int i = 0; i < count; i++) {
+          in.readUnsignedShort();
+          members.add(new Member((String) pool[in.readUnsignedShort()],
+              (String) pool[in.readUnsignedShort()]));
+          int attributes = in.readUnsignedShort();
+          for (int j = 0; j < attributes; j++) {
+            in.readUnsignedShort();
+            in.skipNBytes(Integer.toUnsignedLong(in.readInt()));
+          }
+        }
+      }
+      return new ClassInfo(name, parents, members);
+    }
+  }
+
+  private static boolean reflected(String name, ClassLoader classes, Map<String, Boolean> cache)
+      throws IOException {
+    if (ROOTS.contains(name)) return true;
+    if (cache.containsKey(name)) return cache.get(name);
+    var stream = classes.getResourceAsStream(name + ".class");
+    if (stream == null) throw new IOException("Missing hierarchy class: " + name);
+    var info = readClass(stream);
+    for (String parent : info.parents()) {
+      if (reflected(parent, classes, cache)) {
+        cache.put(name, true);
+        return true;
+      }
+    }
+    cache.put(name, false);
+    return false;
+  }
+
+  private static Set<String> platformTypes(Path jar) throws IOException {
+    try (var zip = new JarFile(jar.toFile())) {
+      var types = new HashSet<String>();
+      zip.stream().filter(e -> e.getName().endsWith(".class"))
+          .forEach(e -> types.add(e.getName().replaceFirst("\\.class$", "")));
+      return types;
+    }
+  }
+
+  private static List<String> check(ClassInfo info, ClassLoader runtime,
+      Set<String> compileTypes, Set<String> supportedTypes) throws ClassNotFoundException {
+    var errors = new ArrayList<String>();
+    for (var member : info.members()) {
+      var types = TYPE.matcher(member.descriptor());
+      while (types.find()) {
+        String type = types.group(1);
+        // Also covers Java platform types that the host JDK could otherwise mask.
+        if (compileTypes.contains(type) && !supportedTypes.contains(type)) {
+          errors.add(member.name() + member.descriptor() + " missing " + type);
+        }
+      }
+    }
+    try {
+      Class<?> module = Class.forName(info.name().replace('/', '.'), false, runtime);
+      try { module.getDeclaredMethods(); }
+      catch (LinkageError e) { errors.add("getDeclaredMethods: " + e); }
+      try { module.getDeclaredFields(); }
+      catch (LinkageError e) { errors.add("getDeclaredFields: " + e); }
+    } catch (LinkageError e) {
+      errors.add("class loading: " + e);
+    }
+    return errors;
+  }
+
+  private static List<ClassInfo> classes(Path directory) throws IOException {
+    try (var files = Files.walk(directory)) {
+      var result = new ArrayList<ClassInfo>();
+      for (Path file : files.filter(p -> p.toString().endsWith(".class")).sorted().toList()) {
+        result.add(readClass(Files.newInputStream(file)));
+      }
+      return result;
+    }
+  }
+
+  private static URLClassLoader loader(List<Path> paths) throws MalformedURLException {
+    var urls = new ArrayList<URL>();
+    for (Path path : paths) urls.add(path.toUri().toURL());
+    return new URLClassLoader(urls.toArray(URL[]::new), ClassLoader.getPlatformClassLoader());
+  }
+
+  public static void main(String[] args) throws Exception {
+    // Gradle writes paths one per line, avoiding command-line length limits.
+    List<Path> paths = Files.readAllLines(Path.of(args[0])).stream().map(Path::of).toList();
+    Path compilePlatform = paths.get(0);
+    Path fixtureDirectory = paths.get(1);
+    List<Path> moduleDirectories = paths.subList(2, 4);
+    var dependencies = new ArrayList<Path>();
+    Path extracted = Path.of(args[1]);
+    Files.createDirectories(extracted);
+    for (Path path : paths.subList(4, paths.size())) {
+      if (!path.toString().endsWith(".aar")) { dependencies.add(path); continue; }
+      try (var aar = new ZipFile(path.toFile())) {
+        for (var entry : aar.stream().filter(e -> e.getName().endsWith(".jar")).toList()) {
+          Path jar = extracted.resolve(dependencies.size() + ".jar");
+          try (var stream = aar.getInputStream(entry)) {
+            Files.copy(stream, jar, StandardCopyOption.REPLACE_EXISTING);
+          }
+          dependencies.add(jar);
+        }
+      }
+    }
+    var ownClasses = new ArrayList<ClassInfo>();
+    for (Path directory : moduleDirectories) {
+      if (Files.isDirectory(directory)) ownClasses.addAll(classes(directory));
+    }
+    if (ownClasses.isEmpty()) throw new AssertionError("No compiled SDK classes");
+    var classpath = new ArrayList<Path>(moduleDirectories);
+    classpath.add(fixtureDirectory);
+    classpath.addAll(dependencies);
+    var hierarchyPath = new ArrayList<Path>(classpath);
+    hierarchyPath.add(compilePlatform);
+    Set<String> compileTypes = platformTypes(compilePlatform);
+    try (var hierarchy = loader(hierarchyPath)) {
+      var cache = new HashMap<String, Boolean>();
+      var modules = new ArrayList<ClassInfo>();
+      for (var info : ownClasses) {
+        if (reflected(info.name(), hierarchy, cache)) modules.add(info);
+      }
+      if (modules.isEmpty()) throw new AssertionError("No React Native modules/view managers");
+      var fixtures = classes(fixtureDirectory);
+      var expected = Map.of(
+          "OriginalListenerModule", "AudioManager$OnCommunicationDeviceChangedListener",
+          "FactoryInferredModule", "AudioManager$OnCommunicationDeviceChangedListener",
+          "ModeListenerViewManager", "AudioManager$OnModeChangedListener");
+      int failures = 0;
+      for (int index = 2; index < args.length; index++) {
+        Path platform = Path.of(args[index]);
+        Set<String> supportedTypes = platformTypes(platform);
+        var runtimePath = new ArrayList<Path>();
+        runtimePath.add(platform);
+        runtimePath.addAll(classpath);
+        try (var runtime = loader(runtimePath)) {
+          for (var module : modules) {
+            var errors = check(module, runtime, compileTypes, supportedTypes);
+            for (String error : errors) System.err.println(platform + ": " + module.name() + ": " + error);
+            if (!errors.isEmpty()) failures++;
+          }
+          int rejected = 0;
+          for (var fixture : fixtures) {
+            String simpleName = fixture.name().substring(fixture.name().lastIndexOf('/') + 1);
+            if (!expected.containsKey(simpleName)) continue;
+            if (!reflected(fixture.name(), hierarchy, cache)) {
+              throw new AssertionError("Fixture is not a module/view manager: " + simpleName);
+            }
+            var errors = check(fixture, runtime, compileTypes, supportedTypes);
+            String missing = expected.get(simpleName);
+            if (supportedTypes.contains("android/media/" + missing)) {
+              if (!errors.isEmpty()) throw new AssertionError("Supported fixture failed: " + simpleName + ": " + errors);
+              rejected++;
+              System.out.println("EXPECTED PASS " + platform.getParent().getFileName() + " " + simpleName);
+              continue;
+            }
+            if (errors.stream().noneMatch(e -> e.contains("missing android/media/" + missing))
+                || errors.stream().noneMatch(e -> e.contains("getDeclaredMethods: java.lang.NoClassDefFoundError"))) {
+              throw new AssertionError("Unsafe fixture escaped: " + simpleName + ": " + errors);
+            }
+            rejected++;
+            System.out.println("EXPECTED FAIL " + platform.getParent().getFileName() + " " + simpleName + ": " + errors);
+          }
+          if (rejected != expected.size()) throw new AssertionError("Missing negative fixtures");
+          System.out.println("Checked " + modules.size() + " SDK modules/view managers against " + platform);
+        }
+      }
+      if (args.length < 3 || failures != 0) throw new AssertionError("Incompatible SDK classes: " + failures);
+    }
+  }
+}

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);
     }
 }