@poolse/react-native-calls 0.2.0 → 0.4.0

package/ios/Module/PoolseCallVideoView.swift

@@ -0,0 +1,62 @@
+import ExpoModulesCore
+import UIKit
+
+/// `<CallVideoView>` on iOS: a thin host for the core's LiveKitVideoSurface.
+/// All binding logic lives in the media adapter; this view forwards props
+/// and ties the surface's lifetime to the window.
+public final class PoolseCallVideoView: ExpoView {
+  private var surface: LiveKitVideoSurface?
+
+  var participantId: String?
+  var local = false
+  var mirror: Bool?
+  var fit = "cover"
+
+  public required init(appContext: AppContext? = nil) {
+    super.init(appContext: appContext)
+    backgroundColor = .clear
+    clipsToBounds = true
+  }
+
+  public override func didMoveToWindow() {
+    super.didMoveToWindow()
+    if window != nil { attachSurface() } else { detachSurface() }
+  }
+
+  public override func layoutSubviews() {
+    super.layoutSubviews()
+    surface?.frame = bounds
+  }
+
+  private func attachSurface() {
+    guard surface == nil else { return }
+    // No core yet (never configured): stay empty; a later prop update retries.
+    guard let core = CallCore.peek() else { return }
+    let s = core.createVideoSurface()
+    s.frame = bounds
+    s.autoresizingMask = [.flexibleWidth, .flexibleHeight]
+    addSubview(s)
+    surface = s
+    apply()
+  }
+
+  func detachSurface() {
+    guard let s = surface else { return }
+    surface = nil
+    s.release()
+    s.removeFromSuperview()
+  }
+
+  func apply() {
+    guard let s = surface else {
+      if window != nil { attachSurface() }
+      return
+    }
+    s.configure(participantId: participantId, local: local, mirror: mirror, fit: fit == "contain" ? "contain" : "cover")
+  }
+
+  deinit {
+    // UIKit objects must be torn down on main; deinit of a view runs there.
+    surface?.release()
+  }
+}

package/ios/Module/PoolseCallsAppDelegateSubscriber.swift

@@ -0,0 +1,16 @@
+import ExpoModulesCore
+import UIKit
+
+/// Registers PushKit at launch, before React Native starts — the only
+/// point early enough for a VoIP push that cold-launches a killed app.
+/// Registered via expo-module.config.json "appDelegateSubscribers", so an
+/// Expo host (AppDelegate: ExpoAppDelegate) needs no AppDelegate edit.
+public class PoolseCallsAppDelegateSubscriber: ExpoAppDelegateSubscriber {
+  public func application(
+    _ application: UIApplication,
+    didFinishLaunchingWithOptions launchOptions: [UIApplication.LaunchOptionsKey: Any]? = nil
+  ) -> Bool {
+    PoolseCallsSetup.registerVoipEarly()
+    return true
+  }
+}

package/ios/Module/PoolseCallsModule.swift

@@ -0,0 +1,111 @@
+import ExpoModulesCore
+
+/// The React Native face of the native call core on iOS — PoolseCallsModule.kt's
+/// twin, with the same names, arity and return shapes (src/index.ts is shared).
+/// Deliberately thin: commands go to CallCore, snapshots stream out.
+///
+/// Nothing here throws before `configure`: reads return idle, commands no-op.
+public class PoolseCallsModule: Module {
+  public func definition() -> ModuleDefinition {
+    Name("PoolseCalls")
+
+    Events("onCallState", "onVoipToken")
+
+    // Normally done at launch by PoolseCallsAppDelegateSubscriber; this is
+    // the backstop for a host whose AppDelegate does not forward to Expo.
+    OnCreate {
+      PoolseCallsSetup.registerVoipEarly()
+    }
+
+    OnStartObserving {
+      CallCore.listener = { [weak self] snapshot in
+        self?.sendEvent("onCallState", ["snapshot": snapshot ?? NSNull()])
+      }
+      VoipPush.tokenListener = { [weak self] token in
+        self?.sendEvent("onVoipToken", ["token": token, "environment": PoolseCallsModule.environment()])
+      }
+    }
+
+    OnStopObserving {
+      CallCore.listener = nil
+      VoipPush.tokenListener = nil
+    }
+
+    AsyncFunction("configure") { (apiBaseUrl: String, options: [String: Any]?) in
+      let env = (options?["apnsEnvironment"] as? String).flatMap { $0 == "production" || $0 == "sandbox" ? $0 : nil }
+      CallCore.configure(
+        apiBaseUrl: apiBaseUrl,
+        ringback: options?["ringback"] as? String,
+        apnsEnvironment: env
+      )
+      // Materialise the core now (and PushKit, if launch did not), so a
+      // call already in flight (cold answer) is visible to getCallState.
+      PoolseCallsSetup.registerVoipEarly()
+      _ = CallCore.getOrNull()
+    }.runOnQueue(.main)
+
+    Function("getCallState") { () -> [String: Any] in
+      ["snapshot": CallCore.peek()?.snapshot() ?? NSNull()]
+    }
+
+    AsyncFunction("place") { (conversationId: String, media: String, sessionToken: String) in
+      CallCore.getOrNull()?.place(conversationId: conversationId, media: media, sessionToken: sessionToken)
+    }.runOnQueue(.main)
+
+    AsyncFunction("join") { (callId: String, conversationId: String?, sessionToken: String) in
+      CallCore.getOrNull()?.join(callId: callId, conversationId: conversationId, sessionToken: sessionToken)
+    }.runOnQueue(.main)
+
+    Function("answer") { onCore { $0.answer() } }
+    Function("decline") { onCore { $0.decline() } }
+    Function("hangUp") { onCore { $0.hangUp() } }
+    Function("setMuted") { (muted: Bool) in onCore { $0.setMuted(muted) } }
+    Function("setCamera") { (on: Bool) in onCore { $0.setCamera(on) } }
+    Function("switchCamera") { onCore { $0.switchCamera() } }
+    Function("setSpeaker") { (on: Bool) in onCore { $0.setSpeaker(on) } }
+
+    // Socket forwarding (open app): idempotent with the push path.
+    Function("onRingEnded") { (callId: String, reason: String) in
+      onCore { $0.onRingEnded(callId: callId, reason: reason) }
+    }
+    Function("onCallFinished") { (callId: String, reason: String?) in
+      let r = (reason?.isEmpty ?? true) ? nil : reason
+      onCore { $0.onCallFinished(callId: callId, reason: r) }
+    }
+
+    // Android-only concepts: CallKit owns the lock-screen ring on iOS.
+    Function("canUseFullScreenIntent") { () -> Bool in true }
+    Function("openFullScreenIntentSettings") { () -> Void in }
+
+    Function("getVoipToken") { () -> [String: Any]? in
+      guard let token = VoipPush.shared.token else { return nil }
+      return ["token": token, "environment": PoolseCallsModule.environment()]
+    }
+
+    // <CallVideoView>: a participant's (or our own) camera.
+    View(PoolseCallVideoView.self) {
+      ViewName("PoolseCallVideo")
+      Prop("participantId") { (view: PoolseCallVideoView, id: String?) in view.participantId = id }
+      Prop("local") { (view: PoolseCallVideoView, local: Bool?) in view.local = local ?? false }
+      Prop("mirror") { (view: PoolseCallVideoView, mirror: Bool?) in view.mirror = mirror }
+      Prop("fit") { (view: PoolseCallVideoView, fit: String?) in view.fit = fit ?? "cover" }
+      OnViewDidUpdateProps { (view: PoolseCallVideoView) in view.apply() }
+    }
+  }
+
+  /// The configured APNs environment; unconfigured → the build's default.
+  static func environment() -> String {
+    if let env = CallCore.apnsEnvironment { return env }
+    #if DEBUG
+    return "sandbox"
+    #else
+    return "production"
+    #endif
+  }
+}
+
+/// Run on main against the core; a no-op when never configured.
+private func onCore(_ block: @escaping (CallCore) -> Void) {
+  let run = { if let core = CallCore.getOrNull() { block(core) } }
+  if Thread.isMainThread { run() } else { DispatchQueue.main.async(execute: run) }
+}

package/ios/Platform/CallCore.swift

@@ -0,0 +1,464 @@
+import AVFoundation
+import CallKit
+import Foundation
+import UIKit
+
+/// The host-supplied configuration, persisted so a PushKit cold wake
+/// (no JS, no configure call) rebuilds the same core from disk.
+struct CallCoreConfig {
+  var apiBaseUrl: String
+  var ringback: String?
+  /// `production` | `sandbox` — the APNs environment the VoIP token
+  /// belongs to. Not reliably readable at runtime, so the host says it.
+  var apnsEnvironment: String?
+}
+
+/// The composition root and the single native entry point — CallCore.kt
+/// for iOS. PushKit, CallKit's provider actions and the React Native
+/// bridge all come through here: one runtime, one answer/decline path.
+///
+/// It also owns what the pure machine does not carry but a truthful
+/// snapshot needs (roster, conversation name, self mute/camera, audio
+/// route), and reconciles CallKit against every final snapshot.
+///
+/// Main thread only, except `snapshot()` / `peek()`.
+final class CallCore {
+  // MARK: statics
+
+  private static let defaults = UserDefaults(suiteName: "dev.poolse.callcore") ?? .standard
+  private static let configLock = NSLock()
+  private static var _config: CallCoreConfig?
+  private static var instance: CallCore?
+
+  static var config: CallCoreConfig? {
+    configLock.lock(); defer { configLock.unlock() }
+    return _config
+  }
+
+  /// The bridge's snapshot subscriber; process-level so JS may subscribe before configure.
+  static var listener: (([String: Any]?) -> Void)?
+
+  /// Configure and PERSIST (see CallCore.kt). Re-configuring swaps in place:
+  /// HTTP and the ringback read the config per use.
+  static func configure(apiBaseUrl: String, ringback: String?, apnsEnvironment: String?) {
+    let trimmed = apiBaseUrl.hasSuffix("/") ? String(apiBaseUrl.dropLast()) : apiBaseUrl
+    defaults.set(trimmed, forKey: "apiBaseUrl")
+    defaults.set(ringback, forKey: "ringback")
+    defaults.set(apnsEnvironment, forKey: "apnsEnvironment")
+    configLock.lock()
+    _config = CallCoreConfig(apiBaseUrl: trimmed, ringback: ringback, apnsEnvironment: apnsEnvironment)
+    configLock.unlock()
+  }
+
+  /// The APNs environment last configured (persisted), if any.
+  static var apnsEnvironment: String? {
+    config?.apnsEnvironment ?? defaults.string(forKey: "apnsEnvironment")
+  }
+
+  private static func restoreConfig() {
+    guard config == nil, let url = defaults.string(forKey: "apiBaseUrl") else { return }
+    configLock.lock()
+    _config = CallCoreConfig(apiBaseUrl: url,
+                             ringback: defaults.string(forKey: "ringback"),
+                             apnsEnvironment: defaults.string(forKey: "apnsEnvironment"))
+    configLock.unlock()
+  }
+
+  /// The core, or nil if this install was never configured. Main thread.
+  static func getOrNull() -> CallCore? {
+    if let i = instance { return i }
+    restoreConfig()
+    guard config != nil else { return nil }
+    let core = CallCore()
+    instance = core
+    return core
+  }
+
+  /// The live core if one exists — never creates.
+  static func peek() -> CallCore? { instance }
+
+  // MARK: parts
+
+  private let callKit = CallKitController.shared
+  private var mediaPort: LiveKitMediaPort!
+  private var runtime: CallCoreRuntime!
+  private var ringback: Ringback!
+  private var surfaceAdapter: SurfaceAdapter!
+  private var eventsAdapter: EventsAdapter!
+
+  // Snapshot extras (main thread).
+  private var extrasCallId: String?
+  private var extrasMedia: String?
+  private var roster: [SnapshotParticipant] = []
+  private var conversationName: String?
+  private var mutedSelf = false
+  private var cameraOn = false
+  private var cameraFacing: String?
+  private var audioRoute: String?
+
+  /// ring_ended reasons seen per call — the CallKit end reason.
+  private var ringEndReasons: [String: String] = [:]
+  /// The user ended from our UI (JS): end CallKit with a transaction.
+  private var localEnd = false
+
+  private let snapshotLock = NSLock()
+  private var lastSnapshot: [String: Any]?
+
+  private init() {
+    ringback = Ringback(resourceName: { CallCore.config?.ringback })
+    eventsAdapter = EventsAdapter()
+    mediaPort = LiveKitMediaPort(events: eventsAdapter)
+    surfaceAdapter = SurfaceAdapter()
+    runtime = CallCoreRuntime(
+      http: CallHttpClient(baseUrl: { CallCore.config?.apiBaseUrl ?? "" }),
+      media: mediaPort,
+      surface: surfaceAdapter,
+      session: surfaceAdapter,
+      timers: MainQueueTimerPort(),
+      sink: BlockSnapshotSink { [weak self] state in self?.onState(state) }
+    )
+    eventsAdapter.core = self
+    surfaceAdapter.core = self
+    callKit.actions = self
+  }
+
+  // MARK: - native entry points
+
+  func onRing(_ ring: RingContext) { runtime.onRing(ring) }
+
+  func onRingEnded(callId: String, reason: String) {
+    onMain { [self] in
+      ringEndReasons[callId] = reason
+      runtime.onRingEnded(callId: callId, reason: reason)
+      reconcileCallKitSoon()
+    }
+  }
+
+  func onCallFinished(callId: String, reason: String?) {
+    onMain { [self] in
+      runtime.onCallFinished(callId: callId, reason: reason)
+      reconcileCallKitSoon()
+    }
+  }
+
+  /// False once this ring is resolved here or past its deadline (+ clock slack).
+  func isRingLive(_ ring: RingContext) -> Bool {
+    let now = Int64(Date().timeIntervalSince1970 * 1000)
+    return !runtime.isResolved(ring.callId) && ring.ringDeadlineEpochMs + CallCoreRuntime.CLOCK_SLACK_MS > now
+  }
+
+  /// Reconcile CallKit after everything queued so far has run.
+  func reconcileCallKitSoon() {
+    runtime.post { [weak self] in
+      guard let self = self else { return }
+      self.reconcileCallKit(self.runtime.currentState())
+    }
+  }
+
+  // MARK: - bridge-driven actions (any thread)
+
+  func answer() { runtime.answer() }
+
+  func decline() {
+    onMain { [self] in
+      localEnd = true
+      runtime.decline()
+    }
+  }
+
+  func hangUp() {
+    onMain { [self] in
+      localEnd = true
+      runtime.hangUp()
+    }
+  }
+
+  func place(conversationId: String, media: String, sessionToken: String) {
+    onMain { [self] in
+      localEnd = false
+      runtime.place(conversationId: conversationId, media: media, sessionToken: sessionToken)
+    }
+  }
+
+  func join(callId: String, conversationId: String?, sessionToken: String) {
+    onMain { [self] in
+      localEnd = false
+      runtime.join(callId: callId, conversationId: conversationId, sessionToken: sessionToken)
+    }
+  }
+
+  func setMuted(_ muted: Bool) {
+    onMain { [self] in
+      applyMuted(muted)
+      if let id = runtime.currentState().callId { callKit.requestMute(callId: id, muted: muted) }
+    }
+  }
+
+  private func applyMuted(_ muted: Bool) {
+    mutedSelf = muted
+    runtime.setMuted(muted)
+    runtime.reemit()
+  }
+
+  /// Not optimistic: cameraOn flips when the media adapter reports it published.
+  func setCamera(_ on: Bool) { runtime.setCamera(on) }
+
+  func switchCamera() { runtime.switchCamera() }
+
+  func setSpeaker(_ on: Bool) {
+    onMain { [self] in
+      audioRoute = on ? "speaker" : "earpiece" // optimistic; the adapter reports the real one
+      runtime.setSpeaker(on)
+      runtime.reemit()
+    }
+  }
+
+  /// A video slot for the native view. Main thread.
+  func createVideoSurface() -> LiveKitVideoSurface { mediaPort.createVideoSurface() }
+
+  /// The contract Snapshot (nil = idle), safe from any thread.
+  func snapshot() -> [String: Any]? {
+    snapshotLock.lock(); defer { snapshotLock.unlock() }
+    return lastSnapshot
+  }
+
+  private func onMain(_ block: @escaping () -> Void) {
+    if Thread.isMainThread { block() } else { DispatchQueue.main.async(execute: block) }
+  }
+
+  // MARK: - snapshot assembly (main)
+
+  fileprivate func onState(_ state: MachineState) {
+    if state.phase == .idle {
+      if extrasCallId != nil { mediaPort.leave() }
+      resetExtras(nil, nil)
+    } else if state.callId != extrasCallId {
+      if extrasCallId?.hasPrefix("pending:") == true {
+        if let old = extrasCallId, let new = state.callId { callKit.rename(from: old, to: new) }
+        extrasCallId = state.callId
+      } else {
+        resetExtras(state.callId, state.media)
+      }
+    }
+    if state.phase != .idle && state.media != extrasMedia {
+      if extrasMedia != nil { audioRoute = nil }
+      extrasMedia = state.media
+    }
+    if let name = runtime.conversationName { conversationName = name }
+
+    let snap = state.toSnapshot(
+      conversationName: conversationName,
+      participants: roster,
+      audioRoute: audioRoute ?? (state.media == "video" ? "speaker" : "earpiece"),
+      mutedSelf: mutedSelf,
+      cameraOn: cameraOn,
+      cameraFacing: cameraFacing
+    )
+    snapshotLock.lock(); lastSnapshot = snap; snapshotLock.unlock()
+    reconcileCallKit(state)
+    reconcileDevice(state)
+    CallCore.listener?(snap)
+  }
+
+  private func resetExtras(_ callId: String?, _ media: String?) {
+    extrasCallId = callId
+    extrasMedia = media
+    roster = []
+    conversationName = nil
+    mutedSelf = false
+    cameraOn = false
+    cameraFacing = nil
+    audioRoute = nil
+  }
+
+  /// CallKit follows the FINAL state of each dispatch.
+  private func reconcileCallKit(_ state: MachineState) {
+    let terminal = state.phase == .idle || state.phase == .ended
+    for t in callKit.liveCalls {
+      let isCurrent = !terminal && t.callId == state.callId
+      if isCurrent {
+        switch state.phase {
+        case .connecting, .active, .reconnecting, .ringingOut:
+          // Answered from the app's own UI: tell CallKit (audio follows).
+          if !t.outgoing && !t.answered && state.direction == .incoming { callKit.requestAnswer(callId: t.callId) }
+          if t.outgoing && state.phase == .active { callKit.reportConnected(callId: t.callId) }
+          callKit.updateTitle(callId: t.callId, title: conversationName, video: state.media == "video")
+        default:
+          break
+        }
+        continue
+      }
+      // Not the call the machine is in (ended, busy-declined, superseded).
+      // Terminal: whatever CallKit still shows is the call that just ended.
+      let reason = endReason(for: t, state: state, current: terminal || t.callId == state.callId)
+      callKit.end(t, reason: reason)
+    }
+    if terminal {
+      localEnd = false
+      if let id = state.callId { ringEndReasons.removeValue(forKey: id) }
+      if ringEndReasons.count > 16 { ringEndReasons.removeAll() }
+    }
+  }
+
+  /// nil = ended locally (end transaction); else how it ended remotely.
+  private func endReason(for t: CallKitController.Tracked, state: MachineState, current: Bool) -> CXCallEndedReason? {
+    if current && localEnd && state.reason != .failed && state.reason != .connectionLost { return nil }
+    if !t.answered && !t.outgoing {
+      switch ringEndReasons[t.callId] {
+      case "answered_elsewhere": return .answeredElsewhere
+      case "declined": return .declinedElsewhere
+      case "timeout": return .unanswered
+      case "cancelled", "finished": return .remoteEnded
+      default: break
+      }
+      if !current { return .unanswered } // busy-declined / never taken
+    }
+    guard current else { return .remoteEnded }
+    switch state.reason {
+    case .noAnswer?, .busyAll?: return .unanswered
+    case .connectionLost?, .failed?: return .failed
+    case .left?: return localEnd ? nil : .remoteEnded
+    default: return .remoteEnded
+    }
+  }
+
+  /// Screen off at the ear: only for an audio call on the earpiece.
+  private func reconcileDevice(_ state: MachineState) {
+    let inCall = state.phase == .active || state.phase == .reconnecting ||
+      state.phase == .ringingOut || state.phase == .connecting
+    let route = audioRoute ?? (state.media == "video" ? "speaker" : "earpiece")
+    let want = inCall && state.media == "audio" && route == "earpiece"
+    if UIDevice.current.isProximityMonitoringEnabled != want { UIDevice.current.isProximityMonitoringEnabled = want }
+  }
+
+  // MARK: - ports' callbacks
+
+  fileprivate func sessionStart(callId: String, media: String) {
+    guard callKit.tracked(callId: callId) == nil else { return } // an answered incoming call
+    let state = runtime.currentState()
+    callKit.startOutgoing(callId: callId, handle: state.conversationId ?? callId, title: runtime.conversationName,
+                          video: media == "video") { [weak self] in
+      // CallKit refused: the call goes on without the system UI.
+      self?.mediaPort.activateAudioWithoutCallKit(media: media)
+    }
+  }
+
+  fileprivate func showRing(_ ring: RingContext) {
+    // Usually already reported by the push path; idempotent.
+    callKit.reportIncoming(ring: ring)
+  }
+
+  fileprivate var ringbackPlayer: Ringback { ringback }
+
+  // MediaEvents → runtime
+  fileprivate func mediaConnected() { runtime.onMediaConnected() }
+  fileprivate func mediaFailed() { runtime.onMediaFailed() }
+  fileprivate func mediaLost() { runtime.onMediaLost() }
+  fileprivate func mediaReconnecting() { runtime.onMediaReconnecting() }
+  fileprivate func mediaRecovered() { runtime.onMediaRecovered() }
+  fileprivate func remoteJoined() { runtime.onRemoteJoined() }
+  fileprivate func participants(_ p: [SnapshotParticipant]) {
+    runtime.post { [weak self] in self?.roster = p }
+    runtime.reemit()
+  }
+  fileprivate func route(_ r: String) {
+    runtime.post { [weak self] in self?.audioRoute = r }
+    runtime.reemit()
+  }
+  fileprivate func localCamera(on: Bool, facing: String?) {
+    runtime.post { [weak self] in self?.cameraOn = on; self?.cameraFacing = facing }
+    runtime.reemit()
+  }
+}
+
+// MARK: - CallKit actions
+
+extension CallCore: CallKitActions {
+  func callKitAnswer(callId: String) {
+    let s = runtime.currentState()
+    guard s.callId == callId, s.phase == .ringingIn else { return }
+    runtime.answer()
+  }
+
+  func callKitEnd(callId: String) {
+    let s = runtime.currentState()
+    guard s.callId == callId || (s.callId?.hasPrefix("pending:") == true) else { return }
+    localEnd = true
+    if s.phase == .ringingIn { runtime.decline() } else { runtime.hangUp() }
+  }
+
+  func callKitSetMuted(callId: String, muted: Bool) {
+    guard muted != mutedSelf else { return }
+    applyMuted(muted)
+  }
+
+  func callKitAudioActivated(_ session: AVAudioSession) {
+    mediaPort.audioActivated(session, media: runtime.currentState().media)
+    ringback.sessionActivated()
+  }
+
+  func callKitAudioDeactivated(_ session: AVAudioSession) {
+    ringback.stop()
+    mediaPort.audioDeactivated()
+  }
+
+  func callKitReset() {
+    let s = runtime.currentState()
+    guard s.phase != .idle && s.phase != .ended else { return }
+    localEnd = true
+    if s.phase == .ringingIn { runtime.decline() } else { runtime.hangUp() }
+  }
+}
+
+// MARK: - port adapters
+
+/// RingSurfacePort + CallSessionPort: CallKit. The ringtone is CallKit's;
+/// dismissal and session end are reconciled from the final state.
+private final class SurfaceAdapter: RingSurfacePort, CallSessionPort {
+  weak var core: CallCore?
+
+  func show(ring: RingContext) { core?.showRing(ring) }
+  func dismiss(callId: String) {}
+  func ringtoneStart() {}
+  func ringtoneStop() {}
+  func ringbackStart() { core?.ringbackPlayer.start() }
+  func ringbackStop() { core?.ringbackPlayer.stop() }
+
+  func start(callId: String, media: String) { core?.sessionStart(callId: callId, media: media) }
+  func stop() { core?.ringbackPlayer.stop() }
+}
+
+private final class EventsAdapter: MediaEvents {
+  weak var core: CallCore?
+
+  func onConnected() { core?.mediaConnected() }
+  func onFailed() { core?.mediaFailed() }
+  func onLost() { core?.mediaLost() }
+  func onReconnecting() { core?.mediaReconnecting() }
+  func onRecovered() { core?.mediaRecovered() }
+  func onRemoteJoined() { core?.remoteJoined() }
+  func onParticipants(_ participants: [SnapshotParticipant]) { core?.participants(participants) }
+  func onAudioRoute(_ route: String) { core?.route(route) }
+  func onLocalCamera(on: Bool, facing: String?) { core?.localCamera(on: on, facing: facing) }
+}
+
+/// Host-facing entry points.
+@objc(PoolseCalls)
+public final class PoolseCallsSetup: NSObject {
+  /// Create the PushKit registry (and the CallKit provider, and the core
+  /// if this install was ever configured). Idempotent; main thread.
+  ///
+  /// Called automatically from `PoolseCallsAppDelegateSubscriber`'s
+  /// didFinishLaunching (registered through expo-module.config.json), so
+  /// an Expo host needs NO AppDelegate edit. A non-Expo host calls this
+  /// from its own `application(_:didFinishLaunchingWithOptions:)`.
+  @objc public static func registerVoipEarly() {
+    if !Thread.isMainThread {
+      DispatchQueue.main.async { registerVoipEarly() }
+      return
+    }
+    _ = CallKitController.shared
+    _ = CallCore.getOrNull()
+    VoipPush.shared.register()
+  }
+}