crowdplaysdk 0.2.3

package/Examples/App.tsx

@@ -0,0 +1,164 @@
+// Complete crowdplaysdk reference integration in one file:
+// consent -> join -> video tiles -> live warnings -> upload progress.
+//
+// Use: create a React Native app, install crowdplaysdk (README steps
+// 1-5), replace App.tsx with this file, paste your app key below.
+
+import React, { useEffect, useRef, useState } from 'react';
+import {
+  Button, FlatList, SafeAreaView, StyleSheet, Text, TextInput, View,
+} from 'react-native';
+import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
+import type {
+  ConsentGrant, Participant, Phase, RecordingSnapshot, UploadProgress,
+} from 'crowdplaysdk';
+
+type AudioRoute = { currentOutputName: string; detectedOutputs: string[]; headphonesConnected: boolean };
+
+CrowdPlay.configure({
+  serverUrl: 'https://dashboard.crowdplay.ai',
+  appKey: 'PASTE_YOUR_APP_KEY', // from https://dashboard.crowdplay.ai
+});
+
+export default function App(): React.JSX.Element {
+  const [consent, setConsent] = useState<ConsentGrant | null>(null);
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [phaseError, setPhaseError] = useState<string | undefined>();
+  const [recordingError, setRecordingError] = useState<string | null>(null);
+  const [participants, setParticipants] = useState<Participant[]>([]);
+  const [warnings, setWarnings] = useState<Record<string, string>>({});
+  const [uploads, setUploads] = useState<UploadProgress[]>([]);
+  const [onWifi, setOnWifi] = useState(true);
+  const [snapshot, setSnapshot] = useState<RecordingSnapshot | null>(null);
+  const [route, setRoute] = useState<AudioRoute | null>(null);
+  const [onSpeaker, setOnSpeaker] = useState(false);
+  const [name, setName] = useState('');
+  const [room, setRoom] = useState('');
+  const nameRef = useRef('');
+  nameRef.current = name;
+
+  useEffect(() => {
+    const subs = [
+      CrowdPlay.addListener('phase', (p) => { setPhase(p.phase); setPhaseError(p.error); }),
+      CrowdPlay.addListener('recording', (r) => setRecordingError(r.error ?? null)),
+      CrowdPlay.addListener('participants', (p) => setParticipants(p.participants)),
+      CrowdPlay.addListener('uploads', (u) => { setUploads(u.sessions); setOnWifi(u.onWifi); }),
+      CrowdPlay.addListener('audioRoute', (r) => setRoute(r)),
+      CrowdPlay.addListener('warning', (w) =>
+        setWarnings((prev) => {
+          const next = { ...prev };
+          if (w.active) next[w.kind] = w.message; else delete next[w.kind];
+          return next;
+        })),
+    ];
+    const poll = setInterval(async () => setSnapshot(await CrowdPlay.snapshot()), 1000);
+    return () => { subs.forEach((s) => s.remove()); clearInterval(poll); };
+  }, []);
+
+  if (!consent) {
+    // REQUIRED before joining: join() throws without a ConsentGrant.
+    return <CrowdPlayConsentScreen onConsent={setConsent} />;
+  }
+
+  if (phase !== 'connected') {
+    return (
+      <SafeAreaView style={styles.screen}>
+        <Text style={styles.title}>Join a session</Text>
+        <TextInput style={styles.input} placeholder="Your name"
+          value={name} onChangeText={setName} autoCapitalize="none" />
+        <TextInput style={styles.input} placeholder="Room code"
+          value={room} onChangeText={setRoom} autoCapitalize="none"
+          onFocus={() => CrowdPlay.warmUp()} />
+        <Button
+          title={phase === 'connecting' ? 'Connecting…' : 'Join'}
+          disabled={phase === 'connecting' || !name || !room}
+          onPress={() => CrowdPlay.join({ displayName: name, roomCode: room, consent })
+            .catch((e) => setPhaseError(String(e)))} />
+        {phaseError ? <Text style={styles.error}>{phaseError}</Text> : null}
+        {uploads.map((u) => (
+          <Text key={u.sessionId} style={styles.upload}>
+            {u.sessionId}: {(u.fraction * 100).toFixed(0)}%
+            {u.isComplete ? ' done' : onWifi ? '' : ' (video waits for WiFi)'}
+            {u.failed > 0 ? '  [retry available]' : ''}
+          </Text>
+        ))}
+        {uploads.some((u) => u.failed > 0) ? (
+          <Button title="Retry uploads" onPress={() => CrowdPlay.retryUploads()} />
+        ) : null}
+      </SafeAreaView>
+    );
+  }
+
+  return (
+    <SafeAreaView style={styles.screen}>
+      {/* The session is NOT being recorded when this is non-null — always show it. */}
+      {recordingError ? (
+        <View style={styles.banner}>
+          <Text style={styles.bannerText}>NOT RECORDING: {recordingError}</Text>
+          <Button title="Retry recording" onPress={() => CrowdPlay.retryRecording()} />
+        </View>
+      ) : (
+        <Text style={styles.rec}>
+          ● REC {snapshot ? `${Math.floor(snapshot.seconds / 60)}:${String(Math.floor(snapshot.seconds % 60)).padStart(2, '0')}` : ''}
+          {snapshot ? `   mic ${snapshot.inputLevelDbfs.toFixed(0)} dBFS` : ''}
+        </Text>
+      )}
+      {Object.entries(warnings).map(([kind, message]) => (
+        <Text key={kind} style={styles.warning}>{message}</Text>
+      ))}
+
+      <View style={styles.tiles}>
+        <CrowdPlayVideoView participant="local" style={styles.selfTile} />
+        <FlatList
+          data={participants}
+          keyExtractor={(p) => p.identity}
+          renderItem={({ item }) => (
+            <View style={styles.tile}>
+              <CrowdPlayVideoView participant={item.identity} style={styles.remoteVideo} />
+              <Text style={styles.tileName}>{item.name || item.identity}</Text>
+            </View>
+          )}
+        />
+      </View>
+
+      {/* Audio output menu (D-079): standard in every build — shows the
+          device by name and lets the user flip to Speaker and back. */}
+      <View style={styles.controls}>
+        <Text>{route?.currentOutputName ?? 'audio output'}</Text>
+        <Button
+          title={onSpeaker ? 'Use device' : 'Use speaker'}
+          onPress={() => {
+            CrowdPlay.setAudioOutput(onSpeaker ? 'automatic' : 'speaker');
+            setOnSpeaker(!onSpeaker);
+          }} />
+      </View>
+      <View style={styles.controls}>
+        <Button title="Mute" onPress={() => CrowdPlay.setMicMuted(true)} />
+        <Button title="Unmute" onPress={() => CrowdPlay.setMicMuted(false)} />
+        <Button title="Leave" onPress={() => CrowdPlay.leave()} />
+      </View>
+      <Text style={styles.hint}>
+        Keep the app open after leaving until uploads reach 100%.
+      </Text>
+    </SafeAreaView>
+  );
+}
+
+const styles = StyleSheet.create({
+  screen: { flex: 1, padding: 16, gap: 8 },
+  title: { fontSize: 22, fontWeight: '600' },
+  input: { borderWidth: 1, borderColor: '#ccc', borderRadius: 8, padding: 10 },
+  error: { color: '#c00' },
+  upload: { fontVariant: ['tabular-nums'] },
+  banner: { backgroundColor: '#c00', padding: 10, borderRadius: 8 },
+  bannerText: { color: '#fff', fontWeight: '700' },
+  rec: { color: '#c00', fontWeight: '700' },
+  warning: { backgroundColor: '#fa0', padding: 6, borderRadius: 6 },
+  tiles: { flex: 1 },
+  selfTile: { width: 110, height: 150, alignSelf: 'flex-end' },
+  tile: { marginVertical: 6 },
+  remoteVideo: { width: '100%', aspectRatio: 3 / 4 },
+  tileName: { textAlign: 'center' },
+  controls: { flexDirection: 'row', justifyContent: 'space-around' },
+  hint: { textAlign: 'center', color: '#888', fontSize: 12 },
+});

package/Examples/tsconfig.json

@@ -0,0 +1,9 @@
+{
+  "extends": "../tsconfig.json",
+  "compilerOptions": {
+    "noEmit": true,
+    "paths": { "crowdplaysdk": ["../src/index"] },
+    "baseUrl": "."
+  },
+  "include": ["App.tsx"]
+}

package/README.md

@@ -0,0 +1,143 @@
+# crowdplaysdk
+
+CrowdPlay's lossless conversation capture for **React Native (iOS)**. Your app
+hosts a live video call; every participant's audio (**48 kHz / 24-bit
+unprocessed WAV**) and video (**1080p30 HEVC**) is recorded **locally, at
+full quality**, clock-aligned across participants, and delivered to CrowdPlay
+automatically — uploads retry, resume, and survive crashes.
+
+**No media ever crosses the JS bridge.** The engine is the same compiled
+native core (CrowdPlaySDK) our reference app runs; React Native drives it with
+control calls and receives state events. Recording quality is identical to
+a fully native app.
+
+## Non-technical? Paste this to your AI agent
+
+```
+I'm building this app: <YOUR APP IDEA — e.g., a tutoring app where
+students and tutors meet over video>
+
+Build it as a React Native iOS app. For the video-call feature, use the
+crowdplaysdk package.
+
+What the app is about — read carefully:
+- The app's name, screens, and flows are about MY IDEA above. The SDK
+  records calls in the background for CrowdPlay; recording is NOT the
+  app's purpose and must not be presented as it. It appears in the UI in
+  the SDK's consent screen before joining a call,
+  a small REC indicator during the call, join/leave, and a small
+  audio-output menu.
+- Keep the SDK integration minimal: consent → join/leave → call screen.
+  The call screen MUST include a small audio-output menu showing the
+  current output device by name (from the 'audioRoute' event) with a
+  switch between the device and Speaker (CrowdPlay.setAudioOutput). Do
+  NOT build upload screens, diagnostics screens, or SDK settings.
+  Uploads happen automatically in the background.
+
+- npm install crowdplaysdk
+- In ios/: pod install, then run
+    ruby node_modules/crowdplaysdk/ios/wire.rb <MyProjectName>
+  (adds the compiled CrowdPlay engine + bridge to the Xcode project)
+- Info.plist: NSMicrophoneUsageDescription, NSCameraUsageDescription,
+  UIBackgroundModes = [audio]
+- My CrowdPlay app key: <APP KEY from the CrowdPlay dashboard>
+- Follow node_modules/crowdplaysdk/llms.txt exactly: configure at
+  startup, the CrowdPlayConsentScreen before joining (join() throws
+  without a ConsentGrant), CrowdPlayVideoView tiles from the participants
+  event, and surface the warning events on the call screen.
+- Never add, pin or import LiveKit/WebRTC yourself, and never write your
+  own AVAudioSession/AVCaptureSession code — the engine owns the mic and
+  camera.
+- When done, run CrowdPlay.doctor() as a development check (not an app
+  screen) and fix anything actionable.
+- Your FINAL message must walk me through testing on my real iPhone,
+  step by step (the Simulator has no camera or mic, so nothing is proven
+  until then): plugging it in, signing/Developer Mode, running from
+  Xcode, allowing permissions, doing a ~1-minute test call, and checking
+  my session at https://dashboard.crowdplay.ai. Do not just say the
+  implementation is complete.
+```
+
+## Manual setup (iOS)
+
+1. `npm install crowdplaysdk`
+2. `cd ios && pod install`
+3. `ruby node_modules/crowdplaysdk/ios/wire.rb <YourProjectName>` —
+   idempotent; adds the CrowdPlaySDK Swift package (the compiled engine), copies
+   the three bridge files into your app target, and points the Swift
+   bridging header at the React headers. (No CocoaPod of our own: the
+   engine ships as a binary Swift package, which keeps your Podfile
+   untouched.)
+4. Info.plist: `NSMicrophoneUsageDescription`, `NSCameraUsageDescription`,
+   `UIBackgroundModes = [audio]`.
+5. Recommended, for uploads that finish while your app is suspended — in
+   your AppDelegate:
+
+   ```objc
+   // AppDelegate.mm — add #import "<YourProjectName>-Swift.h" at the top
+   - (void)application:(UIApplication *)application
+       handleEventsForBackgroundURLSession:(NSString *)identifier
+       completionHandler:(void (^)(void))completionHandler {
+     [CrowdPlayRNBackground handleWithCompletionHandler:completionHandler];
+   }
+   ```
+
+   (Swift AppDelegates call `CrowdPlaySDK.handleBackgroundURLSessionEvents(completionHandler:)`.)
+
+## Usage
+
+```tsx
+import CrowdPlay, { CrowdPlayConsentScreen, CrowdPlayVideoView } from 'crowdplaysdk';
+
+CrowdPlay.configure({ serverUrl: 'https://…', appKey: 'liva_pk_…' });
+
+// 1. Consent (REQUIRED — join() throws without it):
+<CrowdPlayConsentScreen onConsent={(grant) => setConsent(grant)} />
+
+// 2. Join — recording starts automatically:
+await CrowdPlay.join({ displayName, roomCode, consent });
+
+// 3. Render the call:
+<CrowdPlayVideoView participant="local" style={…} />           // self view
+{participants.map(p => <CrowdPlayVideoView participant={p.identity} … />)}
+
+// 4. Controls:
+await CrowdPlay.setMicMuted(true);      // mutes the call AND records silence
+await CrowdPlay.setCameraEnabled(false); // black frames, timeline continuous
+await CrowdPlay.leave();                 // stops recording; uploads continue
+
+// State: subscribe to events
+CrowdPlay.addListener('phase', …)         // idle/connecting/connected/failed
+CrowdPlay.addListener('participants', …)  // who to render tiles for
+CrowdPlay.addListener('uploads', …)       // per-session progress
+CrowdPlay.addListener('warning', …)       // micSilent / clipping / crossTalk — SHOW THESE
+CrowdPlay.addListener('recording', …)     // error ⇒ NOT capturing; offer retryRecording()
+CrowdPlay.addListener('audioRoute', …)    // current output device — drive the output menu
+CrowdPlay.setAudioOutput('speaker')       // or 'automatic' (the connected device)
+CrowdPlay.snapshot()                      // poll 1 Hz for REC timer + input level
+CrowdPlay.doctor()                        // integration self-check
+```
+
+The complete example lives in this repo's `Examples` (one file, ~170
+lines): consent → join → tiles → warnings → uploads.
+
+## Accessing recordings
+
+Your app key doubles as your data credential — see the CrowdPlay dashboard
+(browse + download per session) or the REST endpoints (`GET /sessions`,
+`GET /sessions/<id>/files`) documented in the CrowdPlaySDK README.
+
+## Requirements & limits
+
+- iOS 17+, React Native ≥ 0.71. **iOS only for now** — no Android engine
+  yet, calls to the module on other platforms throw with a clear message.
+- Real device required to record (the Simulator has no camera/mic).
+- Keep the screen awake during sessions; force-quitting the app pauses
+  uploads until next launch (they resume automatically).
+- **Slow join + glitchy first seconds = bad radio, not a bug.** Congested
+  2.4 GHz WiFi plus Bluetooth headphones (they share the antenna) slows the
+  call connect and can chop the first seconds of audio while the Bluetooth
+  link settles; capture self-heals and the rest of the session is
+  unaffected. Prefer a good network and wired headphones, and evaluate
+  quality with the app launched from the home screen — Metro/debugger
+  overhead can reproduce the same symptoms.

package/ios/CrowdPlayRNModule.swift

@@ -0,0 +1,324 @@
+import Combine
+import Foundation
+import CrowdPlaySDK
+#if canImport(React)
+import React
+#endif
+
+/// Shared native state for the RN bridge: ONE CallEngine, plus the Combine
+/// bindings and polling that translate its published state into RN events.
+/// All UI-facing state in CrowdPlaySDK is MainActor, so everything here is too;
+/// bridge methods hop onto it with Task { @MainActor }.
+@MainActor
+final class CrowdPlayRNCore {
+    static let shared = CrowdPlayRNCore()
+
+    lazy var engine = CallEngine()
+    /// Remembered so retryRecording() can restart with the same identity.
+    var displayName = ""
+
+    private weak var emitter: CrowdPlayRNModule?
+    private var cancellables: Set<AnyCancellable> = []
+    private var pollTimer: Timer?
+    private var lastParticipantsKey = ""
+    private var lastAudioRouteKey = ""
+    private var activeWarnings: Set<String> = []
+
+    func bind(_ module: CrowdPlayRNModule) {
+        emitter = module
+        guard cancellables.isEmpty else { return } // bind once; emitter may rebind
+
+        engine.$phase.sink { [weak self] phase in
+            var body: [String: Any] = ["phase": Self.name(of: phase)]
+            if case let .failed(message) = phase { body["error"] = message }
+            self?.send("crowdplay:phase", body)
+        }.store(in: &cancellables)
+
+        engine.$isRecording
+            .combineLatest(engine.$recordingStartError)
+            .sink { [weak self] isRecording, error in
+                var body: [String: Any] = ["isRecording": isRecording]
+                if let error { body["error"] = error }
+                self?.send("crowdplay:recording", body)
+            }.store(in: &cancellables)
+
+        engine.$uploads
+            .combineLatest(engine.$uploadsOnWiFi)
+            .sink { [weak self] uploads, onWifi in
+                self?.send("crowdplay:uploads", [
+                    "onWifi": onWifi,
+                    "sessions": uploads.map(Self.uploadDict),
+                ])
+            }.store(in: &cancellables)
+
+        // Participants + live capture warnings on a 1 s tick. Polling is
+        // deliberate: it is idempotent, survives reconnects, and cannot
+        // miss a transition the way delegate wiring can.
+        pollTimer?.invalidate()
+        pollTimer = Timer.scheduledTimer(withTimeInterval: 1.0, repeats: true) { _ in
+            Task { @MainActor in CrowdPlayRNCore.shared.pollTick() }
+        }
+    }
+
+    func unbind() {
+        emitter = nil
+    }
+
+    private func pollTick() {
+        guard emitter != nil else { return }
+
+        let participants = engine.room.remoteParticipants.values
+            .map { participant -> [String: Any] in
+                let identity = participant.identity?.stringValue ?? ""
+                return ["identity": identity,
+                        "name": participant.name?.isEmpty == false ? participant.name! : identity]
+            }
+            .sorted { ($0["identity"] as? String ?? "") < ($1["identity"] as? String ?? "") }
+        let key = participants.map { $0["identity"] as? String ?? "" }.joined(separator: ",")
+        if key != lastParticipantsKey {
+            lastParticipantsKey = key
+            send("crowdplay:participants", ["participants": participants])
+        }
+
+        // Audio route (D-079): the current output device by NAME plus the
+        // connected candidates, so every app can show a LivaCapture-style
+        // output menu. Emitted only on change.
+        let routeKey = "\(engine.currentOutputName)|\(engine.detectedOutputs.joined(separator: ","))|\(engine.headphonesConnected)"
+        if routeKey != lastAudioRouteKey {
+            lastAudioRouteKey = routeKey
+            send("crowdplay:audioRoute", [
+                "currentOutputName": engine.currentOutputName,
+                "detectedOutputs": engine.detectedOutputs,
+                "headphonesConnected": engine.headphonesConnected,
+            ])
+        }
+
+        let snapshot = engine.recordingSnapshot()
+        updateWarning("audioStalled",
+                      active: snapshot?.audioStalled == true,
+                      message: "Audio capture stalled — the engine is being restarted. "
+                        + "If this persists, leave and rejoin.")
+        updateWarning("micSilent",
+                      active: snapshot?.inputSilent == true && !engine.isMicMuted,
+                      message: "No sound is reaching the microphone — check the headset "
+                        + "plug or switch to the phone microphone.")
+        updateWarning("clipping",
+                      active: (snapshot?.fullScaleSamples ?? 0) > 100,
+                      message: "The microphone is clipping — audio is distorting. Move "
+                        + "the mic away or lower the input.")
+        updateWarning("crossTalk",
+                      active: engine.crossTalkRisk,
+                      message: "Playing through the loudspeaker — the other person's "
+                        + "voice is being recorded into this microphone. Use headphones.")
+        updateWarning("micPolicy",
+                      active: engine.micPolicyViolation != nil,
+                      message: engine.micPolicyViolation ?? "")
+    }
+
+    private func updateWarning(_ kind: String, active: Bool, message: String) {
+        let was = activeWarnings.contains(kind)
+        guard was != active else { return }
+        if active { activeWarnings.insert(kind) } else { activeWarnings.remove(kind) }
+        send("crowdplay:warning", ["kind": kind, "active": active, "message": message])
+    }
+
+    private func send(_ name: String, _ body: [String: Any]) {
+        emitter?.sendEvent(withName: name, body: body)
+    }
+
+    private static func name(of phase: CallEngine.Phase) -> String {
+        switch phase {
+        case .idle: "idle"
+        case .connecting: "connecting"
+        case .connected: "connected"
+        case .failed: "failed"
+        }
+    }
+
+    static func kindDict(_ counts: UploadManager.Progress.KindCounts) -> [String: Any] {
+        ["total": counts.total, "uploaded": counts.uploaded, "failed": counts.failed,
+         "bytesTotal": counts.bytesTotal, "bytesUploaded": counts.bytesUploaded]
+    }
+
+    static func uploadDict(_ progress: UploadManager.Progress) -> [String: Any] {
+        ["sessionId": progress.sessionId,
+         "fraction": progress.fraction,
+         "isComplete": progress.isComplete,
+         "failed": progress.failed,
+         "audio": kindDict(progress.cellularEligible),
+         "video": kindDict(progress.video)]
+    }
+}
+
+/// ObjC-callable hook for background upload completion. From an ObjC
+/// AppDelegate (via the app's generated -Swift.h header):
+///
+///     [CrowdPlayRNBackground handleWithCompletionHandler:completionHandler];
+///
+/// iOS eventually stops delivering background upload events to apps that
+/// skip this — uploads still finish, just less promptly.
+@objc(CrowdPlayRNBackground)
+public final class CrowdPlayRNBackground: NSObject {
+    @objc public static func handle(completionHandler: @escaping () -> Void) {
+        CrowdPlay.handleBackgroundURLSessionEvents(completionHandler: completionHandler)
+    }
+}
+
+/// The RN-visible module. Registered from CrowdPlayReactNative.m; every method
+/// hops to the MainActor core.
+@objc(CrowdPlayReactNative)
+public final class CrowdPlayRNModule: RCTEventEmitter {
+    public override static func requiresMainQueueSetup() -> Bool { true }
+
+    public override func supportedEvents() -> [String]! {
+        ["crowdplay:phase", "crowdplay:recording", "crowdplay:uploads", "crowdplay:participants", "crowdplay:warning", "crowdplay:audioRoute"]
+    }
+
+    public override func startObserving() {
+        Task { @MainActor in CrowdPlayRNCore.shared.bind(self) }
+    }
+
+    public override func stopObserving() {
+        Task { @MainActor in CrowdPlayRNCore.shared.unbind() }
+    }
+
+    @objc public func configure(_ config: NSDictionary) {
+        Task { @MainActor in
+            guard let urlString = config["serverUrl"] as? String,
+                  let url = URL(string: urlString),
+                  let appKey = config["appKey"] as? String
+            else {
+                print("[crowdplay-rn] configure ignored: serverUrl/appKey missing")
+                return
+            }
+            var configuration = CrowdPlayConfiguration(serverURL: url, appKey: appKey)
+            if let cellular = config["videoUploadsOnCellular"] as? Bool {
+                configuration.videoUploadsOnCellular = cellular
+            }
+            if let duringCall = config["uploadDuringCall"] as? Bool {
+                configuration.uploadDuringCall = duringCall
+            }
+            if let quality = config["callQuality"] as? [String: Any] {
+                var callQuality = CallQuality()
+                if let v = quality["videoWidth"] as? Int { callQuality.videoWidth = v }
+                if let v = quality["videoHeight"] as? Int { callQuality.videoHeight = v }
+                if let v = quality["videoFps"] as? Int { callQuality.videoFps = v }
+                if let v = quality["videoBitrate"] as? Int { callQuality.videoBitrate = v }
+                if let v = quality["audioBitrate"] as? Int { callQuality.audioBitrate = v }
+                configuration.callQuality = callQuality
+            }
+            CrowdPlay.configure(configuration)
+        }
+    }
+
+    @objc public func consentText(_ resolve: @escaping RCTPromiseResolveBlock,
+                                  rejecter _: @escaping RCTPromiseRejectBlock) {
+        resolve(CrowdPlayConsent.text)
+    }
+
+    @objc public func join(_ displayName: NSString, roomCode: NSString,
+                           consentGrantedAtMs: NSNumber,
+                           resolver: @escaping RCTPromiseResolveBlock,
+                           rejecter: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            let core = CrowdPlayRNCore.shared
+            core.displayName = displayName as String
+            // The consent gate, native side: a ConsentRecord is REQUIRED by
+            // the engine's join signature; the RN layer's timestamp becomes
+            // the manifest's consent evidence, hashed against the locked
+            // wording (CrowdPlayConsent.text) this SDK shipped.
+            let consent = ConsentRecord(
+                givenAt: Date(timeIntervalSince1970: consentGrantedAtMs.doubleValue / 1000)
+            )
+            await core.engine.join(displayName: displayName as String,
+                                   roomCode: roomCode as String,
+                                   consent: consent)
+            if case let .failed(message) = core.engine.phase {
+                rejecter("join_failed", message, nil)
+            } else {
+                resolver(nil)
+            }
+        }
+    }
+
+    @objc public func leave(_ resolve: @escaping RCTPromiseResolveBlock,
+                            rejecter _: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            await CrowdPlayRNCore.shared.engine.leave()
+            resolve(nil)
+        }
+    }
+
+    /// D-079: audio-output routing. "speaker" forces the loudspeaker;
+    /// "automatic" routes to the connected device (AirPods, wired, …).
+    @objc public func setAudioOutput(_ output: NSString) {
+        Task { @MainActor in
+            CrowdPlayRNCore.shared.engine.selectOutput(output == "speaker" ? .speaker : .automatic)
+        }
+    }
+
+    @objc public func setMicMuted(_ muted: Bool,
+                                  resolver: @escaping RCTPromiseResolveBlock,
+                                  rejecter _: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            let engine = CrowdPlayRNCore.shared.engine
+            if engine.isMicMuted != muted {
+                await engine.toggleMute()
+            }
+            resolver(engine.isMicMuted)
+        }
+    }
+
+    @objc public func setCameraEnabled(_ enabled: Bool,
+                                       resolver: @escaping RCTPromiseResolveBlock,
+                                       rejecter _: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            let engine = CrowdPlayRNCore.shared.engine
+            if engine.isCameraEnabled != enabled {
+                engine.toggleCamera()
+            }
+            resolver(engine.isCameraEnabled)
+        }
+    }
+
+    @objc public func retryRecording() {
+        Task { @MainActor in
+            let core = CrowdPlayRNCore.shared
+            await core.engine.retryRecording(displayName: core.displayName)
+        }
+    }
+
+    @objc public func retryUploads() {
+        Task { @MainActor in CrowdPlayRNCore.shared.engine.retryUploads() }
+    }
+
+    @objc public func warmUp() {
+        Task { @MainActor in CrowdPlay.warmUp() }
+    }
+
+    @objc public func snapshot(_ resolve: @escaping RCTPromiseResolveBlock,
+                               rejecter _: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            guard let snapshot = CrowdPlayRNCore.shared.engine.recordingSnapshot() else {
+                resolve(nil)
+                return
+            }
+            resolve([
+                "seconds": snapshot.seconds,
+                "segmentsClosed": snapshot.segmentsClosed,
+                "droppedSamples": snapshot.droppedSamples,
+                "inputLevelDbfs": snapshot.inputLevelDbfs,
+                "inputSilent": snapshot.inputSilent,
+                "fullScaleSamples": snapshot.fullScaleSamples,
+            ] as [String: Any])
+        }
+    }
+
+    @objc public func doctor(_ resolve: @escaping RCTPromiseResolveBlock,
+                             rejecter _: @escaping RCTPromiseRejectBlock) {
+        Task { @MainActor in
+            let checks = await CrowdPlay.doctor()
+            resolve(checks.map { ["id": $0.id, "passed": $0.passed, "detail": $0.detail] })
+        }
+    }
+}