crowdplaysdk 0.5.1 → 0.6.0

package/README.md

@@ -60,13 +60,39 @@ https://github.com/symbiateam/crowdplaysdk
 
 ## Setup (iOS)
 
-Requirements: iOS 17+, React Native 0.71 or newer, a real device to test
-(the Simulator has no camera or mic), and an **app key** from CrowdPlay.
+Requirements: iOS 17+, React Native 0.71 or newer (Expo SDK 50 or newer
+for the config plugin), a real device to test (the Simulator has no camera
+or mic), and an **app key** from CrowdPlay.
 iOS only for now; calls to the module on other platforms throw with a
 clear message.
 
 **1. Install the package and wire the engine.**
 
+Expo (managed, prebuild or EAS Build, including app builders such as X1):
+
+```bash
+npm install crowdplaysdk
+```
+
+then add the plugin to `app.json` and rebuild (`npx expo prebuild`, a
+development build, or `eas build`):
+
+```json
+"plugins": ["crowdplaysdk"]
+```
+
+That line is the whole native setup. The plugin adds the microphone and
+camera usage strings and the audio background mode to Info.plist, raises
+the iOS deployment target to 17.0, and wires the compiled engine into the
+Xcode project at prebuild time. Options: `["crowdplaysdk", { "audioOnly":
+true }]` skips the camera string; `microphonePermission` and
+`cameraPermission` set your own wording. Expo Go cannot load native
+modules, so the call, the consent text and recording only work in a
+development build or a TestFlight build; the JavaScript side shows
+placeholders in Expo Go instead of crashing.
+
+Bare React Native (no Expo):
+
 ```bash
 npm install crowdplaysdk
 cd ios && pod install
@@ -75,11 +101,14 @@ ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
 ```
 
 `wire.rb` is idempotent. It adds the compiled CrowdPlaySDK Swift package,
-copies the three bridge files into your app target, and points the Swift
-bridging header at the React headers. There is no CocoaPod of our own, so
-your Podfile stays untouched.
+copies the three bridge files into your app target, points the Swift
+bridging header at the React headers, raises the app target to iOS 17 and
+keeps explicit Swift modules on for the app target (React Native 0.8x turns
+them off project-wide on Xcode 26, which breaks importing the compiled
+engine). There is no CocoaPod of our own, so your Podfile stays untouched.
 
-**2. Declare permissions in Info.plist.**
+**2. Declare permissions in Info.plist** (bare React Native only; the Expo
+plugin does this for you).
 
 ```
 NSMicrophoneUsageDescription = "Records your microphone during sessions."
@@ -87,8 +116,8 @@ NSCameraUsageDescription     = "Records your camera during sessions."
 UIBackgroundModes            = [audio]
 ```
 
-**3. Let uploads finish while the app is suspended** (recommended). In your
-AppDelegate:
+**3. Let uploads finish while the app is suspended** (recommended, both
+paths). In your AppDelegate:
 
 ```objc
 // AppDelegate.mm, with #import "<YourProjectName>-Swift.h" at the top

package/app.plugin.js

@@ -0,0 +1,186 @@
+// Expo config plugin for crowdplaysdk (D-121).
+//
+//   app.json:  "plugins": ["crowdplaysdk"]
+//          or  "plugins": [["crowdplaysdk", { "audioOnly": true }]]
+//
+// That line is the whole native setup for an Expo app (managed, prebuild or
+// EAS Build). At `expo prebuild` time it:
+//   1. adds the microphone (and camera) usage strings and the `audio`
+//      background mode to Info.plist, only where the app has not set them;
+//   2. raises ios.deploymentTarget to 17.0 (the engine requires iOS 17);
+//   3. runs ios/wire.rb against the generated Xcode project, exactly as a
+//      bare React Native builder would by hand: it adds the compiled
+//      CrowdPlaySDK Swift package (pinned to the engine release the bridge
+//      was compiled against), copies the three bridge files into the app
+//      target and points the bridging header at the React headers.
+// Step 3 runs in Expo's `finalized` mod, after every other mod has written
+// the pbxproj and Info.plist, so nothing in config-plugins rewrites the
+// project afterwards; `pod install` (which runs later) integrates through
+// the same Xcodeproj gem and keeps the package reference.
+//
+// Props (all optional):
+//   audioOnly            true: no camera usage string is added
+//   microphonePermission the NSMicrophoneUsageDescription text
+//   cameraPermission     the NSCameraUsageDescription text
+//   backgroundAudio      false: do not add the `audio` background mode
+//
+// Requires Expo SDK 50 or newer (the `finalized` mod) and a Ruby with the
+// xcodeproj gem, which every CocoaPods install provides; EAS Build images
+// ship both. Expo Go cannot load native modules, so the call, the consent
+// text and recording only work in a development build or a TestFlight
+// build; the JavaScript side degrades instead of crashing there.
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { spawnSync } = require('child_process');
+const pkg = require('./package.json');
+
+let configPlugins;
+try {
+  configPlugins = require('expo/config-plugins');
+} catch (e) {
+  configPlugins = require('@expo/config-plugins');
+}
+const {
+  withInfoPlist, withPodfileProperties, withFinalizedMod, createRunOncePlugin, IOSConfig,
+} = configPlugins;
+
+const MIC_DEFAULT = 'Records your microphone during sessions.';
+const CAMERA_DEFAULT = 'Records your camera during sessions.';
+const MIN_IOS = 17;
+const REACT_IMPORTS = [
+  '#import <React/RCTBridgeModule.h>',
+  '#import <React/RCTEventEmitter.h>',
+  '#import <React/RCTViewManager.h>',
+];
+
+function withCrowdPlayInfoPlist(config, props) {
+  return withInfoPlist(config, (config) => {
+    const plist = config.modResults;
+    if (!plist.NSMicrophoneUsageDescription) {
+      plist.NSMicrophoneUsageDescription = props.microphonePermission || MIC_DEFAULT;
+    }
+    if (props.audioOnly !== true && !plist.NSCameraUsageDescription) {
+      plist.NSCameraUsageDescription = props.cameraPermission || CAMERA_DEFAULT;
+    }
+    if (props.backgroundAudio !== false) {
+      if (!Array.isArray(plist.UIBackgroundModes)) plist.UIBackgroundModes = [];
+      if (!plist.UIBackgroundModes.includes('audio')) plist.UIBackgroundModes.push('audio');
+    }
+    return config;
+  });
+}
+
+function withCrowdPlayDeploymentTarget(config) {
+  return withPodfileProperties(config, (config) => {
+    const current = parseFloat(config.modResults['ios.deploymentTarget'] || '0');
+    if (!(current >= MIN_IOS)) config.modResults['ios.deploymentTarget'] = `${MIN_IOS}.0`;
+    return config;
+  });
+}
+
+/** The Xcode project name: Expo names the .xcodeproj after the app, and
+ * modRequest.projectName carries it; fall back to a glob when it does not. */
+function resolveProjectName(modRequest) {
+  const { projectName, projectRoot, platformProjectRoot } = modRequest;
+  if (projectName && fs.existsSync(path.join(platformProjectRoot, `${projectName}.xcodeproj`))) {
+    return projectName;
+  }
+  const found = IOSConfig.Paths.getXcodeProjectPath(projectRoot);
+  return path.basename(found, '.xcodeproj');
+}
+
+/** A Ruby that can load the xcodeproj gem: the one on PATH, the one that
+ * runs `pod`, or Bundler's when the project has a Gemfile. */
+function findRuby(platformProjectRoot) {
+  const candidates = [{ cmd: 'ruby', args: [] }];
+  const pod = spawnSync('which', ['pod'], { encoding: 'utf8' });
+  if (pod.status === 0) {
+    try {
+      const shebang = fs.readFileSync(pod.stdout.trim(), 'utf8').split('\n')[0];
+      const m = /^#!\s*(\S+)(?:\s+(\S+))?/.exec(shebang);
+      if (m) {
+        const cmd = m[1].endsWith('/env') ? m[2] : m[1];
+        if (cmd && cmd !== 'ruby') candidates.push({ cmd, args: [] });
+      }
+    } catch (e) { /* not a script; ignore */ }
+  }
+  if (fs.existsSync(path.join(platformProjectRoot, 'Gemfile')) ||
+      fs.existsSync(path.join(platformProjectRoot, '..', 'Gemfile'))) {
+    candidates.push({ cmd: 'bundle', args: ['exec', 'ruby'] });
+  }
+  for (const c of candidates) {
+    const probe = spawnSync(c.cmd, [...c.args, '-e', "require 'xcodeproj'"], {
+      cwd: platformProjectRoot, encoding: 'utf8',
+    });
+    if (probe.status === 0) return c;
+  }
+  return null;
+}
+
+/** wire.rb creates the bridging header only when the target has none. Expo's
+ * template already has one (a comment-only file), so add the React imports
+ * the bridge files need to whatever header the project points at. */
+function ensureBridgingHeaderImports(platformProjectRoot, projectName) {
+  const pbxproj = path.join(platformProjectRoot, `${projectName}.xcodeproj`, 'project.pbxproj');
+  if (!fs.existsSync(pbxproj)) return;
+  const text = fs.readFileSync(pbxproj, 'utf8');
+  const headers = new Set();
+  const re = /SWIFT_OBJC_BRIDGING_HEADER\s*=\s*"?([^";]+)"?\s*;/g;
+  let m;
+  while ((m = re.exec(text)) !== null) headers.add(m[1].trim());
+  for (const rel of headers) {
+    const file = path.join(platformProjectRoot, rel);
+    if (!fs.existsSync(file)) continue;
+    const body = fs.readFileSync(file, 'utf8');
+    if (body.includes('React/RCTBridgeModule.h')) continue;
+    const sep = body.length === 0 || body.endsWith('\n') ? '' : '\n';
+    fs.writeFileSync(file, body + sep + REACT_IMPORTS.join('\n') + '\n');
+  }
+}
+
+function withCrowdPlayWire(config) {
+  return withFinalizedMod(config, ['ios', async (config) => {
+    const { introspect, platformProjectRoot } = config.modRequest;
+    if (introspect) return config;
+    const projectName = resolveProjectName(config.modRequest);
+    const ruby = findRuby(platformProjectRoot);
+    if (!ruby) {
+      throw new Error(
+        'crowdplaysdk: no Ruby with the xcodeproj gem was found, so the CrowdPlay ' +
+        'engine could not be wired into the Xcode project. The gem ships with every ' +
+        'CocoaPods install; locally run `gem install xcodeproj --user-install` and ' +
+        'prebuild again. EAS Build images already have it.',
+      );
+    }
+    const wire = path.join(__dirname, 'ios', 'wire.rb');
+    const r = spawnSync(ruby.cmd, [...ruby.args, wire, projectName], {
+      cwd: platformProjectRoot, encoding: 'utf8',
+    });
+    if (r.status !== 0) {
+      throw new Error(
+        `crowdplaysdk: ios/wire.rb failed (exit ${r.status}) while wiring the CrowdPlay ` +
+        `engine into ${projectName}.xcodeproj.\n${r.stdout || ''}${r.stderr || ''}`,
+      );
+    }
+    for (const line of (r.stdout || '').split('\n')) {
+      if (line.startsWith('+')) console.log(`crowdplaysdk: ${line}`);
+    }
+    ensureBridgingHeaderImports(platformProjectRoot, projectName);
+    return config;
+  }]);
+}
+
+const withCrowdPlay = (config, props) => {
+  const p = props && typeof props === 'object' ? props : {};
+  if (typeof withFinalizedMod !== 'function') {
+    throw new Error('crowdplaysdk: the Expo config plugin needs Expo SDK 50 or newer.');
+  }
+  config = withCrowdPlayInfoPlist(config, p);
+  config = withCrowdPlayDeploymentTarget(config);
+  config = withCrowdPlayWire(config);
+  return config;
+};
+
+module.exports = createRunOncePlugin(withCrowdPlay, pkg.name, pkg.version);

package/ios/wire.rb

@@ -1,12 +1,15 @@
-# Wires crowdplaysdk into an iOS app project. Run from your app's
-# ios/ directory after `pod install`:
+# Wires crowdplaysdk into an iOS app project. Expo apps never run this by
+# hand: the package's config plugin (app.plugin.js) runs it during
+# `expo prebuild`. Bare React Native apps run it from ios/ after
+# `pod install`:
 #
 #   ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
 #
 # What it does (idempotent; safe to re-run):
 #   1. adds the CrowdPlaySDK Swift package (compiled engine) to the project
 #   2. copies the three bridge files into your app group + target
-#   3. creates/points the Swift bridging header at the React headers
+#   3. creates/points the Swift bridging header at the React headers, raises
+#      the app target to iOS 17 and keeps explicit Swift modules ON for it
 #
 # Requires the `xcodeproj` gem (ships with CocoaPods installs; otherwise
 # `gem install xcodeproj`).
@@ -22,10 +25,12 @@ rescue LoadError
 end
 
 SDK_URL = 'https://github.com/symbiateam/crowdplaysdk'
-# The ENGINE release this bridge was tested against. The npm package
-# version may be AHEAD of this (bridge/docs fixes ship without a new
-# engine binary); that is deliberate, not drift.
-SDK_VERSION = '0.4.0'
+# The ENGINE release this bridge compiles against. The npm version may run
+# ahead of it only while the bridge uses no newer engine symbols; since
+# D-103 the bridge calls 0.5.0 APIs, and npm 0.5.0 to 0.5.2 shipped with
+# this still at 0.4.0, which broke every install (D-121). publish_rn.sh now
+# compiles the bridge against exactly this release before publishing.
+SDK_VERSION = '0.5.2'
 BRIDGE_FILES = ['CrowdPlayRNModule.swift', 'CrowdPlayRNVideoView.swift', 'CrowdPlayReactNative.m'].freeze
 
 project_name = ARGV[0] or abort 'usage: ruby wire.rb <YourProjectName>'
@@ -73,6 +78,16 @@ target.build_configurations.each do |config|
   if current.nil? || current.to_f < 17.0
     config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = '17.0'
   end
+  # React Native's pod post-install (react_native_pods.rb, RN 0.8x with the
+  # prebuilt React Native core) sets SWIFT_ENABLE_EXPLICIT_MODULES = NO at the
+  # PROJECT level for Xcode 26. With implicit modules the app target never
+  # receives the module map for _AtomicsShims, a C module of swift-atomics
+  # that the compiled engine's Swift interface imports, and every Swift file
+  # in the app fails with "missing required module '_AtomicsShims'" (measured
+  # on Expo SDK 57 / RN 0.86 / Xcode 26.6, D-121). A TARGET-level YES wins
+  # over the project-level NO, survives pod install, and only touches the app
+  # target; the same build passes with it.
+  config.build_settings['SWIFT_ENABLE_EXPLICIT_MODULES'] = 'YES'
   next if config.build_settings['SWIFT_OBJC_BRIDGING_HEADER']
 
   header_name = "#{project_name}-Bridging-Header.h"

package/lib/ConsentScreen.d.ts

@@ -1,7 +1,7 @@
 /**
  * Drop-in consent screen. Shows CrowdPlay's locked consent wording (fetched from
  * the native SDK so it can never drift from what the manifest records), a link
- * to the full CrowdPlay Terms of Use and Privacy Notice, a switch, and a
+ * to the full CrowdPlay Terms of Use and Privacy Policy, a switch, and a
  * continue button that only enables once the participant agrees. Yields the
  * ConsentGrant that join() requires.
  *

package/lib/ConsentScreen.js

@@ -2,7 +2,7 @@
 /**
  * Drop-in consent screen. Shows CrowdPlay's locked consent wording (fetched from
  * the native SDK so it can never drift from what the manifest records), a link
- * to the full CrowdPlay Terms of Use and Privacy Notice, a switch, and a
+ * to the full CrowdPlay Terms of Use and Privacy Policy, a switch, and a
  * continue button that only enables once the participant agrees. Yields the
  * ConsentGrant that join() requires.
  *
@@ -70,21 +70,17 @@ function CrowdPlayConsentScreen({ onConsent, style }) {
         };
     }, []);
     return (<react_native_1.View style={[styles.container, style]}>
-      <react_native_1.Text style={styles.title}>Recording consent</react_native_1.Text>
-      {text === null ? (<react_native_1.ActivityIndicator />) : (<react_native_1.Text style={styles.body}>{text}</react_native_1.Text>)}
+      <react_native_1.Text style={styles.title}>Before you join</react_native_1.Text>
       <react_native_1.Pressable accessibilityRole="link" onPress={() => void react_native_1.Linking.openURL(index_1.CROWDPLAY_TERMS_URL)}>
-        <react_native_1.Text style={styles.link}>Read the Terms of Use and Privacy Notice</react_native_1.Text>
+        <react_native_1.Text style={styles.link}>Read the Terms of Use and Privacy Policy</react_native_1.Text>
       </react_native_1.Pressable>
       <react_native_1.View style={styles.row}>
         <react_native_1.Switch value={agreed} onValueChange={(value) => {
             setAgreed(value);
             setAgreedAtMs(value ? Date.now() : null);
         }}/>
-        <react_native_1.Text style={styles.agree}>I have read and agree to the CrowdPlay Terms of Use and Privacy Notice.</react_native_1.Text>
+        {text === null ? <react_native_1.ActivityIndicator /> : <react_native_1.Text style={styles.agree}>{text}</react_native_1.Text>}
       </react_native_1.View>
-      <react_native_1.Text style={styles.note}>
-        Recording starts automatically when you join, and ends when you leave.
-      </react_native_1.Text>
       <react_native_1.Pressable accessibilityRole="button" disabled={!agreed || agreedAtMs === null} onPress={() => {
             if (agreedAtMs !== null)
                 onConsent({ grantedAtMs: agreedAtMs });

package/lib/VideoView.js

@@ -18,7 +18,24 @@ exports.CrowdPlayVideoView = CrowdPlayVideoView;
 const react_1 = __importDefault(require("react"));
 const react_native_1 = require("react-native");
 const NativeCrowdPlayVideoView = (0, react_native_1.requireNativeComponent)('CrowdPlayVideoView');
+/** The native module and the native view ship in the same bridge files, so
+ * a missing module means a build without the engine: Expo Go, or a preview
+ * that never ran the config plugin. Rendering the native view there throws
+ * at render time; a labelled placeholder keeps the rest of the screen
+ * usable and says what is going on. */
+function nativeAvailable() {
+    return react_native_1.NativeModules.CrowdPlayReactNative != null;
+}
 function CrowdPlayVideoView(props) {
     const { participant, mirror, ...rest } = props;
+    if (!nativeAvailable()) {
+        return (<react_native_1.View {...rest} style={[placeholder.box, rest.style]}>
+        <react_native_1.Text style={placeholder.label}>CrowdPlay video needs a device build</react_native_1.Text>
+      </react_native_1.View>);
+    }
     return (<NativeCrowdPlayVideoView participant={participant} mirror={mirror ?? participant === 'local'} {...rest}/>);
 }
+const placeholder = react_native_1.StyleSheet.create({
+    box: { backgroundColor: '#222222', alignItems: 'center', justifyContent: 'center', padding: 8 },
+    label: { color: '#dddddd', fontSize: 12, textAlign: 'center' },
+});

package/lib/VoiceView.d.ts

@@ -17,6 +17,16 @@ export interface VoiceActivity {
     /** 0…1, smoothed (fast attack, slow release). */
     energy: number;
 }
+/** Raw payload of the 'voiceActivity' event (the native fast stream that
+ * runs only while useVoiceActivity() or CrowdPlayVoiceView is mounted). */
+export interface VoiceActivityEvent {
+    agentPresent: boolean;
+    agentSpeaking: boolean;
+    agentLevel: number;
+    localLevelDbfs: number | null;
+    localSpeaking: boolean;
+    connected: boolean;
+}
 /** Live phase + energy from the call engine. Subscribing starts the native
  * fast stream; the last unmount stops it. */
 export declare function useVoiceActivity(): VoiceActivity;

package/lib/index.d.ts

@@ -20,6 +20,7 @@
  * native layer requires the consent record structurally; there is no code
  * path that records without it.
  */
+import type { VoiceActivityEvent, VoiceCaption } from './VoiceView';
 /** Live-call (Path A) quality. The RECORDING is always 1080p30 + 24-bit WAV
  * regardless; raising these trades upload + thermal headroom (which the
  * recording needs on long sessions) for a prettier live picture. Values are
@@ -191,6 +192,13 @@ export interface CrowdPlayEvents {
         name: string;
         argumentsJSON: string;
     };
+    /** Voice-AI activity (agent present/speaking, local level). Flows ONLY
+     * while the native fast stream is running, which useVoiceActivity() and
+     * CrowdPlayVoiceView start on mount and stop on unmount; prefer those. */
+    voiceActivity: VoiceActivityEvent;
+    /** The latest live transcript line from the voice agent; see
+     * useLatestCaption(). */
+    caption: VoiceCaption;
 }
 export type CrowdPlayEventName = keyof CrowdPlayEvents;
 declare const CrowdPlay: {
@@ -262,4 +270,4 @@ export default CrowdPlay;
 export { CrowdPlayConsentScreen } from './ConsentScreen';
 export { CrowdPlayVideoView } from './VideoView';
 export { CrowdPlayVoiceView, VoiceReactive, useVoiceActivity, useLatestCaption } from './VoiceView';
-export type { CrowdPlayVoiceViewProps, VoiceActivity, VoicePhase, VoiceCaption } from './VoiceView';
+export type { CrowdPlayVoiceViewProps, VoiceActivity, VoiceActivityEvent, VoicePhase, VoiceCaption } from './VoiceView';

package/lib/index.js

@@ -30,10 +30,11 @@ exports.CROWDPLAY_TERMS_URL = 'https://dashboard.crowdplay.ai/legal/terms.pdf';
 function native() {
     const module = react_native_1.NativeModules.CrowdPlayReactNative;
     if (!module) {
-        throw new Error("crowdplaysdk: native module not found. iOS setup: add the CrowdPlaySDK " +
-            "Swift package (https://github.com/symbiateam/crowdplaysdk) to your Xcode " +
-            "project and add the two bridge files from node_modules/crowdplaysdk/ios " +
-            "to your app target; see the package README. " +
+        throw new Error("crowdplaysdk: native module not found. Expo: add \"crowdplaysdk\" to " +
+            "\"plugins\" in app.json and rebuild (npx expo prebuild, a development " +
+            "build, or eas build); Expo Go cannot load native modules. Bare React " +
+            "Native: run ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName> " +
+            "from ios/ after pod install; see the package README. " +
             (react_native_1.Platform.OS !== 'ios' ? `(platform '${react_native_1.Platform.OS}' is not supported yet; iOS only.)` : ''));
     }
     return module;

package/llms.txt

@@ -50,8 +50,8 @@ its video calls invisibly; recording is infrastructure, not identity:
 
 1. NEVER add, pin, import, or update LiveKit, WebRTC, or any
    react-native-webrtc package. The correct engine ships as a compiled
-   binary that ios/wire.rb installs. Adding your own causes duplicate
-   symbols or silently breaks capture.
+   binary that the Expo config plugin (or ios/wire.rb) installs. Adding
+   your own causes duplicate symbols or silently breaks capture.
 2. NEVER write AVAudioSession / AVAudioEngine / AVCaptureSession code (or
    add audio-session-touching RN packages like react-native-incall-manager)
    in an app using this SDK. The engine owns the microphone and camera.
@@ -67,6 +67,27 @@ its video calls invisibly; recording is infrastructure, not identity:
 
 ## Integration procedure
 
+Steps 1 to 4 depend on the project type. Everything from step 5 on is the
+same for both.
+
+EXPO (managed, prebuild or EAS Build; app builders such as X1):
+1.  npm install crowdplaysdk
+2.  app.json: add "crowdplaysdk" to the "plugins" array, or
+    ["crowdplaysdk", { "audioOnly": true }] for an audio-only app.
+    That is the WHOLE native setup: at prebuild the plugin adds the
+    microphone and camera usage strings and the audio background mode to
+    Info.plist (only where the app has not set them), raises the iOS
+    deployment target to 17.0, and wires the compiled engine into the
+    Xcode project. Do not add those Info.plist keys or any native code
+    yourself. Expo SDK 50 or newer.
+3.  Rebuild: npx expo prebuild, a development build, or eas build.
+4.  Expo Go and any preview that never ran the plugin cannot load native
+    modules: there the consent text, the call and recording fail with a
+    clear error and the video view shows a placeholder. That is EXPECTED;
+    do not debug it and never remove the package or the plugin to make a
+    preview pass. Everything else works in preview.
+
+BARE REACT NATIVE (no Expo):
 1.  npm install crowdplaysdk
 2.  cd ios && pod install        (installs RN's own pods; CrowdPlay has none)
 3.  gem install xcodeproj --user-install   (one-time; wire.rb needs it
@@ -74,9 +95,12 @@ its video calls invisibly; recording is infrastructure, not identity:
     ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>
     Idempotent. It: adds the CrowdPlaySDK binary Swift package to the Xcode
     project, copies the three native bridge files into the app target,
-    creates/points the Swift bridging header at the React headers, and
-    raises the iOS deployment target to 17.0 if the RN template left it
-    lower. Rerun it any time; it never duplicates.
+    creates/points the Swift bridging header at the React headers, raises
+    the iOS deployment target to 17.0 if the RN template left it lower, and
+    sets SWIFT_ENABLE_EXPLICIT_MODULES = YES on the app target (React Native
+    0.8x sets it to NO project-wide on Xcode 26, and with implicit modules
+    the compiled engine's interface cannot be imported). Rerun it any time;
+    it never duplicates. Never undo that setting to fix an unrelated error.
 4.  Info.plist: NSMicrophoneUsageDescription, NSCameraUsageDescription,
     UIBackgroundModes = [audio]. A missing usage string makes iOS kill
     the app at first mic/camera access (uncatchable).
@@ -117,6 +141,11 @@ its video calls invisibly; recording is infrastructure, not identity:
     detail names its own fix. NOTE: on a fresh install the "permissions"
     check reports "not requested yet (NORMAL)"; iOS prompts at first join.
     That is not an integration bug; only a DENIED state needs action.
+    KNOWN ENGINE BUG: on engine 0.5.1 and 0.5.2 the "consent_terms" check
+    fails on every device (the engine's own hash bookkeeping, fixed in
+    engine 0.5.3 / crowdplaysdk 0.6.1). Nothing in your app causes it and
+    nothing in your app fixes it; the consent screen and the recorded
+    consent are correct. Every other check in that run is valid.
 11. Hand off (REQUIRED final message): the Simulator has no camera or
     mic, so nothing is proven until the app runs on a real iPhone. Do
     not end with "the implementation is complete"; your FINAL message

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "crowdplaysdk",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "CrowdPlay lossless conversation capture for React Native (iOS). Studio-grade per-participant recording during live video calls, delivered to CrowdPlay automatically.",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",
   "files": [
+    "app.plugin.js",
     "lib",
     "src",
     "ios",
@@ -29,12 +30,18 @@
     "recording",
     "video-call",
     "lossless",
-    "crowdplay"
+    "crowdplay",
+    "expo"
   ],
   "peerDependencies": {
     "react": "*",
     "react-native": "*"
   },
+  "peerDependenciesMeta": {
+    "expo": {
+      "optional": true
+    }
+  },
   "devDependencies": {
     "@types/react": "^18.2.0",
     "react": "18.2.0",

package/src/ConsentScreen.tsx

@@ -1,7 +1,7 @@
 /**
  * Drop-in consent screen. Shows CrowdPlay's locked consent wording (fetched from
  * the native SDK so it can never drift from what the manifest records), a link
- * to the full CrowdPlay Terms of Use and Privacy Notice, a switch, and a
+ * to the full CrowdPlay Terms of Use and Privacy Policy, a switch, and a
  * continue button that only enables once the participant agrees. Yields the
  * ConsentGrant that join() requires.
  *
@@ -43,14 +43,9 @@ export function CrowdPlayConsentScreen({ onConsent, style }: CrowdPlayConsentScr
 
   return (
     <View style={[styles.container, style]}>
-      <Text style={styles.title}>Recording consent</Text>
-      {text === null ? (
-        <ActivityIndicator />
-      ) : (
-        <Text style={styles.body}>{text}</Text>
-      )}
+      <Text style={styles.title}>Before you join</Text>
       <Pressable accessibilityRole="link" onPress={() => void Linking.openURL(CROWDPLAY_TERMS_URL)}>
-        <Text style={styles.link}>Read the Terms of Use and Privacy Notice</Text>
+        <Text style={styles.link}>Read the Terms of Use and Privacy Policy</Text>
       </Pressable>
       <View style={styles.row}>
         <Switch
@@ -60,11 +55,8 @@ export function CrowdPlayConsentScreen({ onConsent, style }: CrowdPlayConsentScr
             setAgreedAtMs(value ? Date.now() : null);
           }}
         />
-        <Text style={styles.agree}>I have read and agree to the CrowdPlay Terms of Use and Privacy Notice.</Text>
+        {text === null ? <ActivityIndicator /> : <Text style={styles.agree}>{text}</Text>}
       </View>
-      <Text style={styles.note}>
-        Recording starts automatically when you join, and ends when you leave.
-      </Text>
       <Pressable
         accessibilityRole="button"
         disabled={!agreed || agreedAtMs === null}

package/src/VideoView.tsx

@@ -11,7 +11,7 @@
  */
 
 import React from 'react';
-import { requireNativeComponent, type ViewProps } from 'react-native';
+import { NativeModules, requireNativeComponent, StyleSheet, Text, View, type ViewProps } from 'react-native';
 
 export interface CrowdPlayVideoViewProps extends ViewProps {
   /** "local" for the self-view, or a remote participant's identity. */
@@ -23,8 +23,24 @@ export interface CrowdPlayVideoViewProps extends ViewProps {
 
 const NativeCrowdPlayVideoView = requireNativeComponent<CrowdPlayVideoViewProps>('CrowdPlayVideoView');
 
+/** The native module and the native view ship in the same bridge files, so
+ * a missing module means a build without the engine: Expo Go, or a preview
+ * that never ran the config plugin. Rendering the native view there throws
+ * at render time; a labelled placeholder keeps the rest of the screen
+ * usable and says what is going on. */
+function nativeAvailable(): boolean {
+  return NativeModules.CrowdPlayReactNative != null;
+}
+
 export function CrowdPlayVideoView(props: CrowdPlayVideoViewProps): React.JSX.Element {
   const { participant, mirror, ...rest } = props;
+  if (!nativeAvailable()) {
+    return (
+      <View {...rest} style={[placeholder.box, rest.style]}>
+        <Text style={placeholder.label}>CrowdPlay video needs a device build</Text>
+      </View>
+    );
+  }
   return (
     <NativeCrowdPlayVideoView
       participant={participant}
@@ -33,3 +49,8 @@ export function CrowdPlayVideoView(props: CrowdPlayVideoViewProps): React.JSX.El
     />
   );
 }
+
+const placeholder = StyleSheet.create({
+  box: { backgroundColor: '#222222', alignItems: 'center', justifyContent: 'center', padding: 8 },
+  label: { color: '#dddddd', fontSize: 12, textAlign: 'center' },
+});

package/src/VoiceView.tsx

@@ -22,7 +22,9 @@ export interface VoiceActivity {
   energy: number;
 }
 
-interface VoiceActivityEvent {
+/** Raw payload of the 'voiceActivity' event (the native fast stream that
+ * runs only while useVoiceActivity() or CrowdPlayVoiceView is mounted). */
+export interface VoiceActivityEvent {
   agentPresent: boolean;
   agentSpeaking: boolean;
   agentLevel: number;

package/src/index.ts

@@ -22,6 +22,7 @@
  */
 
 import { NativeEventEmitter, NativeModules, Platform } from 'react-native';
+import type { VoiceActivityEvent, VoiceCaption } from './VoiceView';
 
 // ---------------------------------------------------------------------------
 // Types
@@ -186,6 +187,13 @@ export interface CrowdPlayEvents {
   /** The voice AI asked the app to run a tool (D-103). Prefer
    * CrowdPlay.onAgentToolCall(), which answers for you. */
   agentToolCall: { callId: string; name: string; argumentsJSON: string };
+  /** Voice-AI activity (agent present/speaking, local level). Flows ONLY
+   * while the native fast stream is running, which useVoiceActivity() and
+   * CrowdPlayVoiceView start on mount and stop on unmount; prefer those. */
+  voiceActivity: VoiceActivityEvent;
+  /** The latest live transcript line from the voice agent; see
+   * useLatestCaption(). */
+  caption: VoiceCaption;
 }
 
 export type CrowdPlayEventName = keyof CrowdPlayEvents;
@@ -210,6 +218,9 @@ interface NativeCrowdPlay {
   setAudioOutput(output: string): void;
   snapshot(): Promise<RecordingSnapshot | null>;
   doctor(): Promise<DoctorCheck[]>;
+  /** Start/stop the 'voiceActivity' fast stream (useVoiceActivity owns this). */
+  startVoiceActivityUpdates(): void;
+  stopVoiceActivityUpdates(): void;
   addListener(eventName: string): void;
   removeListeners(count: number): void;
 }
@@ -218,10 +229,11 @@ function native(): NativeCrowdPlay {
   const module = NativeModules.CrowdPlayReactNative as NativeCrowdPlay | undefined;
   if (!module) {
     throw new Error(
-      "crowdplaysdk: native module not found. iOS setup: add the CrowdPlaySDK " +
-        "Swift package (https://github.com/symbiateam/crowdplaysdk) to your Xcode " +
-        "project and add the two bridge files from node_modules/crowdplaysdk/ios " +
-        "to your app target; see the package README. " +
+      "crowdplaysdk: native module not found. Expo: add \"crowdplaysdk\" to " +
+        "\"plugins\" in app.json and rebuild (npx expo prebuild, a development " +
+        "build, or eas build); Expo Go cannot load native modules. Bare React " +
+        "Native: run ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName> " +
+        "from ios/ after pod install; see the package README. " +
         (Platform.OS !== 'ios' ? `(platform '${Platform.OS}' is not supported yet; iOS only.)` : '')
     );
   }
@@ -408,4 +420,4 @@ export default CrowdPlay;
 export { CrowdPlayConsentScreen } from './ConsentScreen';
 export { CrowdPlayVideoView } from './VideoView';
 export { CrowdPlayVoiceView, VoiceReactive, useVoiceActivity, useLatestCaption } from './VoiceView';
-export type { CrowdPlayVoiceViewProps, VoiceActivity, VoicePhase, VoiceCaption } from './VoiceView';
+export type { CrowdPlayVoiceViewProps, VoiceActivity, VoiceActivityEvent, VoicePhase, VoiceCaption } from './VoiceView';