@poolse/react-native-calls 0.2.0 → 0.4.0

package/ios/Core/CallMachine.swift

@@ -0,0 +1,304 @@
+import Foundation
+
+// The call state machine — contract cv 1, CONTRACT.md §7. Direct port of
+// android/.../callcore/CallMachine.kt. Pure: no I/O, no platform, no time.
+// Pinned by contracts/call-core/vectors.json — change the vectors first.
+
+/// Inputs, named exactly as in the contract and vectors.
+public enum Event: Equatable {
+  /// A ring from push or socket — treated identically. `stale`: deadline passed. Never surface.
+  case ring(callId: String, conversationId: String? = nil, media: String = "audio", stale: Bool = false)
+  case ringEnded(callId: String, reason: String)
+  /// The server finished the call; `reason` only colours an unanswered caller's ended screen.
+  case callFinished(callId: String, reason: String? = nil)
+  case userAnswer
+  case userDecline
+  case userPlace(callId: String, conversationId: String? = nil, media: String = "audio")
+  case userJoin(callId: String, conversationId: String? = nil)
+  case userHangup
+  /// Server accepted answer/join/place. `created=false` on place: an existing live call (became a join).
+  case httpOk(created: Bool = true)
+  case httpGone
+  case httpTimeout
+  /// Terminal refusal that is NOT "the call is over" (401/403, 503, unparseable 2xx).
+  case httpFailed(code: String = "failed")
+  case mediaConnected
+  case mediaFailed
+  case mediaLost
+  /// The SFU is recovering on its own. Show it; do not rejoin.
+  case mediaReconnecting
+  case mediaRecovered
+  case remoteJoined
+  /// Caller side: every ring resolved without anyone joining.
+  case allRingsResolved(outcome: String)
+  case ringDeadline
+  case reconnectBudgetElapsed
+  /// CONNECTING watchdog.
+  case connectTimeout
+  case lingerElapsed
+}
+
+/// Abstract effects — each adapter maps them to its platform.
+public enum Effect: Equatable {
+  case showRing, dismissRing, ringtoneStart, ringtoneStop, ringbackStart, ringbackStop
+  case httpAnswer, httpJoin, httpPlace, httpDecline
+  case httpDeclineBusy(callId: String)
+  case httpHangup, httpReconnect, mediaJoin, mediaLeave, callSessionStart, callSessionStop
+
+  public var wire: String {
+    switch self {
+    case .showRing: return "SHOW_RING"
+    case .dismissRing: return "DISMISS_RING"
+    case .ringtoneStart: return "RINGTONE_START"
+    case .ringtoneStop: return "RINGTONE_STOP"
+    case .ringbackStart: return "RINGBACK_START"
+    case .ringbackStop: return "RINGBACK_STOP"
+    case .httpAnswer: return "HTTP_ANSWER"
+    case .httpJoin: return "HTTP_JOIN"
+    case .httpPlace: return "HTTP_PLACE"
+    case .httpDecline: return "HTTP_DECLINE"
+    case .httpDeclineBusy(let callId): return "HTTP_DECLINE_BUSY:\(callId)"
+    case .httpHangup: return "HTTP_HANGUP"
+    case .httpReconnect: return "HTTP_RECONNECT"
+    case .mediaJoin: return "MEDIA_JOIN"
+    case .mediaLeave: return "MEDIA_LEAVE"
+    case .callSessionStart: return "CALL_SESSION_START"
+    case .callSessionStop: return "CALL_SESSION_STOP"
+    }
+  }
+}
+
+public struct Transition: Equatable {
+  public let state: MachineState
+  public let effects: [Effect]
+  public init(_ state: MachineState, _ effects: [Effect]) {
+    self.state = state
+    self.effects = effects
+  }
+}
+
+private extension MachineState {
+  func with(phase: Phase? = nil, reason: EndReason?? = nil, direction: Direction?? = nil,
+            httpAttempts: Int? = nil) -> MachineState {
+    var c = self
+    if let phase = phase { c.phase = phase }
+    if let reason = reason { c.reason = reason }
+    if let direction = direction { c.direction = direction }
+    if let httpAttempts = httpAttempts { c.httpAttempts = httpAttempts }
+    return c
+  }
+}
+
+public enum CallMachine {
+
+  public static func transition(_ s: MachineState, _ e: Event) -> Transition {
+    switch e {
+
+    case let .ring(callId, conversationId, media, stale):
+      return ring(s, callId: callId, conversationId: conversationId, media: media, stale: stale)
+
+    case let .ringEnded(callId, _):
+      if s.phase == .ringingIn && callId == s.callId {
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing])
+      }
+      return noop(s)
+
+    case let .callFinished(callId, reason):
+      guard callId == s.callId else { return noop(s) }
+      switch s.phase {
+      case .ringingIn:
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing])
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(ringOutcome(reason))),
+                          [.ringbackStop, .mediaLeave, .callSessionStop])
+      case .active, .reconnecting, .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.finished)), [.mediaLeave, .callSessionStop])
+      case .ended:
+        let outcome = ringOutcome(reason)
+        if s.direction == .outgoing && s.reason == .finished && outcome != .finished {
+          return Transition(s.with(reason: .some(outcome)), [])
+        }
+        return noop(s)
+      default:
+        return noop(s)
+      }
+
+    case .userAnswer:
+      if s.phase == .ringingIn {
+        return Transition(s.with(phase: .connecting, direction: .some(.incoming), httpAttempts: 1),
+                          [.ringtoneStop, .dismissRing, .httpAnswer, .callSessionStart])
+      }
+      return noop(s)
+
+    case .userDecline:
+      if s.phase == .ringingIn {
+        return Transition(.IDLE, [.ringtoneStop, .dismissRing, .httpDecline])
+      }
+      return noop(s)
+
+    case let .userPlace(callId, conversationId, media):
+      if s.phase == .idle || s.phase == .ended {
+        return Transition(MachineState(phase: .connecting, callId: callId, conversationId: conversationId,
+                                       direction: .outgoing, media: media, httpAttempts: 1),
+                          [.httpPlace, .callSessionStart])
+      }
+      return noop(s)
+
+    case let .userJoin(callId, conversationId):
+      if s.phase == .idle || s.phase == .ended {
+        return Transition(MachineState(phase: .connecting, callId: callId, conversationId: conversationId,
+                                       direction: .joined, httpAttempts: 1),
+                          [.httpJoin, .callSessionStart])
+      }
+      return noop(s)
+
+    case .userHangup:
+      switch s.phase {
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(.cancelled)),
+                          [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+      case .active, .reconnecting, .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.left)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case let .httpOk(created):
+      if s.phase != .connecting { return noop(s) }
+      if s.direction == .outgoing && created {
+        return Transition(s.with(phase: .ringingOut), [.mediaJoin, .ringbackStart])
+      }
+      if s.direction == .outgoing && !created {
+        return Transition(s.with(direction: .some(.joined)), [.mediaJoin])
+      }
+      return Transition(s, [.mediaJoin])
+
+    case .httpGone:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.finished)), [.callSessionStop])
+      case .reconnecting:
+        return Transition(s.with(phase: .ended, reason: .some(.left)), [.mediaLeave, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .httpTimeout:
+      if s.phase != .connecting { return noop(s) }
+      if s.httpAttempts < 2 {
+        let retry: Effect
+        switch s.direction {
+        case .outgoing?: retry = .httpPlace
+        case .joined?: retry = .httpJoin
+        default: retry = .httpAnswer
+        }
+        return Transition(s.with(httpAttempts: s.httpAttempts + 1), [retry])
+      }
+      return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+
+    case .httpFailed:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+      case .reconnecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.mediaLeave, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .connectTimeout:
+      if s.phase == .connecting {
+        return Transition(s.with(phase: .ended, reason: .some(.failed)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      }
+      return noop(s)
+
+    case .mediaConnected:
+      switch s.phase {
+      case .connecting, .reconnecting: return Transition(s.with(phase: .active), [])
+      default: return noop(s)
+      }
+
+    case .mediaFailed:
+      switch s.phase {
+      case .connecting:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)), [.httpHangup, .callSessionStop])
+      case .ringingOut:
+        return Transition(s.with(phase: .ended, reason: .some(.failed)),
+                          [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+      default:
+        return noop(s)
+      }
+
+    case .mediaLost:
+      switch s.phase {
+      case .active: return Transition(s.with(phase: .reconnecting), [.httpReconnect])
+      case .reconnecting: return Transition(s, [.httpReconnect])
+      default: return noop(s)
+      }
+
+    case .mediaReconnecting:
+      return s.phase == .active ? Transition(s.with(phase: .reconnecting), []) : noop(s)
+
+    case .mediaRecovered:
+      return s.phase == .reconnecting ? Transition(s.with(phase: .active), []) : noop(s)
+
+    case .remoteJoined:
+      return s.phase == .ringingOut ? Transition(s.with(phase: .active), [.ringbackStop]) : noop(s)
+
+    case let .allRingsResolved(outcome):
+      guard s.phase == .ringingOut else { return noop(s) }
+      let reason: EndReason
+      switch outcome {
+      case "busy_all": reason = .busyAll
+      case "no_answer": reason = .noAnswer
+      case "cancelled": reason = .cancelled
+      default: reason = .declinedAll
+      }
+      return Transition(s.with(phase: .ended, reason: .some(reason)),
+                        [.ringbackStop, .mediaLeave, .httpHangup, .callSessionStop])
+
+    case .ringDeadline:
+      return s.phase == .ringingIn ? Transition(.IDLE, [.ringtoneStop, .dismissRing]) : noop(s)
+
+    case .reconnectBudgetElapsed:
+      if s.phase == .reconnecting {
+        return Transition(s.with(phase: .ended, reason: .some(.connectionLost)),
+                          [.mediaLeave, .httpHangup, .callSessionStop])
+      }
+      return noop(s)
+
+    case .lingerElapsed:
+      return s.phase == .ended ? Transition(.IDLE, []) : noop(s)
+    }
+  }
+
+  private static func ring(_ s: MachineState, callId: String, conversationId: String?, media: String,
+                           stale: Bool) -> Transition {
+    if stale { return noop(s) }
+    // Already showing this very ring (push + socket race): one surface.
+    if s.phase == .ringingIn && callId == s.callId { return noop(s) }
+    // A fresh ring on idle — or over a lingering ended screen.
+    if s.phase == .idle || s.phase == .ended {
+      return Transition(MachineState(phase: .ringingIn, callId: callId, conversationId: conversationId,
+                                     direction: .incoming, media: media),
+                        [.showRing, .ringtoneStart])
+    }
+    // Busy with another call: auto-decline the newcomer.
+    return Transition(s, [.httpDeclineBusy(callId: callId)])
+  }
+
+  /// A finish push's reason, read as the caller's unanswered outcome.
+  private static func ringOutcome(_ reason: String?) -> EndReason {
+    switch reason {
+    case "no_answer"?, "timeout"?: return .noAnswer
+    case "declined_all"?, "declined"?: return .declinedAll
+    case "busy_all"?: return .busyAll
+    case "cancelled"?: return .cancelled
+    default: return .finished
+    }
+  }
+
+  private static func noop(_ s: MachineState) -> Transition { Transition(s, []) }
+}

package/ios/Core/PORTS_READY.md

@@ -0,0 +1,93 @@
+# iOS call core — ports & runtime API (ready to code against)
+
+Swift port of `android/.../callcore/{Ports,CallMachine,CallCoreRuntime}.kt`.
+Foundation only, main-thread confined, no Sendable. All types `public`.
+
+## Ports (ios/Core/Ports.swift)
+
+```swift
+protocol HttpPort: AnyObject {
+  func answer(callId: String, grant: String, cb: @escaping (HttpResult) -> Void)
+  func join(callId: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  func place(conversationId: String, media: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  func decline(callId: String, auth: String, busy: Bool)
+  func hangup(callId: String, controlToken: String)
+  func reconnect(current: CallSessionBundle, cb: @escaping (HttpResult) -> Void)
+}
+enum HttpResult { case ok(CallSessionBundle), gone, timeout, authFailed(code: String), failed(code: String) }
+struct CallSessionBundle { callId, conversationId, conversationName?, media, created, livekitUrl, livekitToken, controlToken }
+
+protocol MediaPort: AnyObject {
+  func join(bundle: CallSessionBundle); func leave()
+  func setMuted(_ muted: Bool); func setCamera(_ on: Bool); func switchCamera(); func setSpeaker(_ on: Bool)
+}
+protocol RingSurfacePort: AnyObject {
+  func show(ring: RingContext); func dismiss(callId: String)
+  func ringtoneStart(); func ringtoneStop(); func ringbackStart(); func ringbackStop()
+}
+struct RingContext { callId, conversationId, conversationName?, callerName?, media, grant, ringDeadlineEpochMs: Int64 }
+protocol CallSessionPort: AnyObject { func start(callId: String, media: String); func stop() }
+protocol SnapshotSink: AnyObject { func emit(state: MachineState) }   // BlockSnapshotSink { state in ... } helper
+protocol TimerPort: AnyObject {
+  func nowMs() -> Int64
+  func schedule(key: String, delayMs: Int64, fire: @escaping () -> Void)  // same key replaces
+  func cancel(key: String)
+}
+// State values: Phase (.idle .ringingIn .ringingOut .connecting .active .reconnecting .ended),
+// Direction (.incoming .outgoing .joined), EndReason (.left .finished .declinedAll .busyAll
+// .noAnswer .cancelled .connectionLost .failed; `.wire` = "declined_all" etc.),
+// MachineState { phase, callId?, conversationId?, direction?, media, reason?, httpAttempts }
+```
+
+Provided implementations in Core: `CallHttpClient` (HttpPort, URLSession),
+`MainQueueTimerPort()` (TimerPort on DispatchQueue.main, epoch nowMs), `BlockSnapshotSink { state in }`.
+
+## Runtime (ios/Core/CallCoreRuntime.swift)
+
+```swift
+let rt = CallCoreRuntime(
+  http: HttpPort, media: MediaPort, surface: RingSurfacePort,
+  session: CallSessionPort, timers: TimerPort, sink: SnapshotSink,
+  executor: ((@escaping () -> Void) -> Void)? = nil)  // default: inline if on main thread, else DispatchQueue.main.async
+
+rt.currentState() -> MachineState
+rt.conversationName: String?          // bundle's, else the ring's (main thread)
+rt.isResolved(_ callId: String) -> Bool
+rt.post(_ block: @escaping () -> Void)
+
+// inputs
+rt.onRing(_ ctx: RingContext)          // push (PushKit) or socket — same path
+rt.onRingEnded(callId:reason:)
+rt.onCallFinished(callId:reason:)      // reason: String? = nil
+rt.answer(); rt.decline(); rt.hangUp()
+rt.place(conversationId:media:sessionToken:)
+rt.join(callId:conversationId:sessionToken:)   // conversationId: String?
+rt.allRingsResolved(_ outcome: String)
+rt.onMediaConnected(); rt.onMediaFailed(); rt.onMediaLost()
+rt.onMediaReconnecting(); rt.onMediaRecovered(); rt.onRemoteJoined()
+rt.setMuted(_:); rt.setCamera(_:); rt.switchCamera(); rt.setSpeaker(_:)
+rt.reemit()                            // re-emit current state (roster/route changed)
+```
+
+Constants: `CallCoreRuntime.ENDED_LINGER_MS` (2500), `RECONNECT_BUDGET_MS` (25000),
+`CONNECT_WATCHDOG_MS` (20000), `RING_OUT_BACKSTOP_MS` (75000), `CLOCK_SLACK_MS` (10000), `RESOLVED_LRU` (32).
+
+The sink receives the MachineState after every change; IDLE means "no call" (emit `snapshot: null`).
+Ended state lingers 2.5 s, then IDLE is emitted.
+
+## HTTP client (ios/Core/CallHttpClient.swift)
+
+```swift
+CallHttpClient(baseUrl: @escaping () -> String, session: URLSession = CallHttpClient.defaultSession())
+// baseUrl read per request (staging/prod switch). 9 s total timeout. Static classify/parseBundle/errorCode are pure.
+```
+
+## Snapshot (ios/Core/SnapshotEncoding.swift)
+
+```swift
+struct SnapshotParticipant { userId, externalId, speaking, muted, cameraOn }
+MachineState.toSnapshot(conversationName: String? = nil,
+  participants: [SnapshotParticipant] = [], audioRoute: String = "earpiece",
+  mutedSelf: Bool = false, cameraOn: Bool = false, cameraFacing: String? = nil) -> [String: Any]?
+// nil for IDLE. conversationName nil -> NSNull; reason / cameraFacing omitted when nil.
+```

package/ios/Core/Ports.swift

@@ -0,0 +1,193 @@
+import Foundation
+
+// The seams between the pure machine and the platform. Direct port of
+// android/.../callcore/Ports.kt (plus the state value types from
+// CallMachine.kt). Everything is main-thread confined: adapters may call
+// back from any thread — the runtime hops onto DispatchQueue.main.
+
+// MARK: - HTTP (CONTRACT.md §4 — the three doors)
+
+public protocol HttpPort: AnyObject {
+  /// POST /calls/:id/answer with the ring grant.
+  func answer(callId: String, grant: String, cb: @escaping (HttpResult) -> Void)
+  /// POST /calls/:id/join with a session token.
+  func join(callId: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  /// POST /conversations/:id/calls with a session token.
+  func place(conversationId: String, media: String, sessionToken: String, cb: @escaping (HttpResult) -> Void)
+  /// POST /calls/:id/decline — grant or session; fire-and-forget with retry.
+  func decline(callId: String, auth: String, busy: Bool)
+  /// POST /calls/:id/hangup with the call-control token; fire-and-forget with retry.
+  func hangup(callId: String, controlToken: String)
+  /// POST /calls/:id/reconnect with the call-control token. Answers with the
+  /// FULL bundle; `current` lets an older server's `{livekit:{url,token}}`
+  /// refresh be applied onto it.
+  func reconnect(current: CallSessionBundle, cb: @escaping (HttpResult) -> Void)
+}
+
+public enum HttpResult: Equatable {
+  /// 2xx: the CallSessionBundle (or reconnect's token refresh).
+  case ok(CallSessionBundle)
+  /// 404/410 — the call is finished (or this device was superseded).
+  case gone
+  /// Timeout / transient network failure.
+  case timeout
+  /// 401/403 — grant spent, expired, or wrong device. Terminal.
+  case authFailed(code: String)
+  /// Terminal but not auth: 503, another 4xx, or an unparseable 2xx.
+  case failed(code: String)
+}
+
+public struct CallSessionBundle: Equatable {
+  public var callId: String
+  public var conversationId: String
+  public var conversationName: String?
+  public var media: String
+  public var created: Bool
+  public var livekitUrl: String
+  public var livekitToken: String
+  public var controlToken: String
+
+  public init(callId: String, conversationId: String, conversationName: String?, media: String,
+              created: Bool, livekitUrl: String, livekitToken: String, controlToken: String) {
+    self.callId = callId
+    self.conversationId = conversationId
+    self.conversationName = conversationName
+    self.media = media
+    self.created = created
+    self.livekitUrl = livekitUrl
+    self.livekitToken = livekitToken
+    self.controlToken = controlToken
+  }
+}
+
+// MARK: - Media
+
+/// LiveKit (or any SFU) — media only, no lifecycle opinions.
+public protocol MediaPort: AnyObject {
+  func join(bundle: CallSessionBundle)
+  func leave()
+  func setMuted(_ muted: Bool)
+  func setCamera(_ on: Bool)
+  func switchCamera()
+  /// Loudspeaker (`true`) or back to the private route (`false`).
+  func setSpeaker(_ on: Bool)
+}
+
+// MARK: - Ring surface
+
+/// The ring UX. iOS: CallKit report + tones.
+public protocol RingSurfacePort: AnyObject {
+  func show(ring: RingContext)
+  func dismiss(callId: String)
+  func ringtoneStart()
+  func ringtoneStop()
+  func ringbackStart()
+  func ringbackStop()
+}
+
+public struct RingContext: Equatable {
+  public var callId: String
+  public var conversationId: String
+  public var conversationName: String?
+  public var callerName: String?
+  public var media: String
+  public var grant: String
+  public var ringDeadlineEpochMs: Int64
+
+  public init(callId: String, conversationId: String, conversationName: String?, callerName: String?,
+              media: String, grant: String, ringDeadlineEpochMs: Int64) {
+    self.callId = callId
+    self.conversationId = conversationId
+    self.conversationName = conversationName
+    self.callerName = callerName
+    self.media = media
+    self.grant = grant
+    self.ringDeadlineEpochMs = ringDeadlineEpochMs
+  }
+}
+
+// MARK: - Session / snapshots / time
+
+/// Android: the phoneCall foreground service. iOS: the CallKit session / audio session.
+public protocol CallSessionPort: AnyObject {
+  func start(callId: String, media: String)
+  func stop()
+}
+
+/// Snapshots out — the bridge turns these into JS events (IDLE → null).
+public protocol SnapshotSink: AnyObject {
+  func emit(state: MachineState)
+}
+
+/// Closure-backed SnapshotSink convenience.
+public final class BlockSnapshotSink: SnapshotSink {
+  private let block: (MachineState) -> Void
+  public init(_ block: @escaping (MachineState) -> Void) { self.block = block }
+  public func emit(state: MachineState) { block(state) }
+}
+
+/// Time, injectable: real adapter uses DispatchQueue.main; tests a fake.
+public protocol TimerPort: AnyObject {
+  func nowMs() -> Int64
+  /// Scheduling an existing key replaces it.
+  func schedule(key: String, delayMs: Int64, fire: @escaping () -> Void)
+  func cancel(key: String)
+}
+
+// MARK: - Machine state value types (CallMachine.kt)
+
+public enum Phase: String, CaseIterable {
+  case idle = "IDLE"
+  case ringingIn = "RINGING_IN"
+  case ringingOut = "RINGING_OUT"
+  case connecting = "CONNECTING"
+  case active = "ACTIVE"
+  case reconnecting = "RECONNECTING"
+  case ended = "ENDED"
+}
+
+public enum Direction: String {
+  case incoming = "INCOMING"
+  case outgoing = "OUTGOING"
+  case joined = "JOINED"
+}
+
+public enum EndReason: String {
+  case left = "LEFT"
+  case finished = "FINISHED"
+  case declinedAll = "DECLINED_ALL"
+  case busyAll = "BUSY_ALL"
+  case noAnswer = "NO_ANSWER"
+  case cancelled = "CANCELLED"
+  case connectionLost = "CONNECTION_LOST"
+  case failed = "FAILED"
+
+  /// Wire form: lowercase snake (e.g. "declined_all").
+  public var wire: String { rawValue.lowercased() }
+}
+
+/// Everything the machine knows. Immutable value; transitions return a new one.
+public struct MachineState: Equatable {
+  public var phase: Phase
+  public var callId: String?
+  public var conversationId: String?
+  public var direction: Direction?
+  public var media: String
+  public var reason: EndReason?
+  /// HTTP attempts made for the current connecting request (retry budget = 2).
+  public var httpAttempts: Int
+
+  public init(phase: Phase = .idle, callId: String? = nil, conversationId: String? = nil,
+              direction: Direction? = nil, media: String = "audio", reason: EndReason? = nil,
+              httpAttempts: Int = 0) {
+    self.phase = phase
+    self.callId = callId
+    self.conversationId = conversationId
+    self.direction = direction
+    self.media = media
+    self.reason = reason
+    self.httpAttempts = httpAttempts
+  }
+
+  public static var IDLE: MachineState { MachineState() }
+}

package/ios/Core/SnapshotEncoding.swift

@@ -0,0 +1,75 @@
+import Foundation
+
+/// One remote participant as the JS `Snapshot.participants[]` entry.
+public struct SnapshotParticipant: Equatable {
+  /// The LiveKit identity.
+  public var userId: String
+  public var externalId: String
+  public var speaking: Bool
+  public var muted: Bool
+  /// True only with a published, subscribed, unmuted camera track.
+  public var cameraOn: Bool
+
+  public init(userId: String, externalId: String, speaking: Bool, muted: Bool, cameraOn: Bool) {
+    self.userId = userId
+    self.externalId = externalId
+    self.speaking = speaking
+    self.muted = muted
+    self.cameraOn = cameraOn
+  }
+
+  public var dictionary: [String: Any] {
+    ["userId": userId, "externalId": externalId, "speaking": speaking, "muted": muted, "cameraOn": cameraOn]
+  }
+}
+
+public extension Phase {
+  var wire: String {
+    switch self {
+    case .idle: return "idle"
+    case .ringingIn: return "ringing_in"
+    case .ringingOut: return "ringing_out"
+    case .connecting: return "connecting"
+    case .active: return "active"
+    case .reconnecting: return "reconnecting"
+    case .ended: return "ended"
+    }
+  }
+}
+
+public extension Direction {
+  var wire: String { rawValue.lowercased() }
+}
+
+public extension MachineState {
+  /// The one place a MachineState becomes the contract's `Snapshot`
+  /// (CONTRACT.md §8; mirrors SnapshotJson.kt and src/index.ts). Returns nil
+  /// for idle: the bridge sends `{ snapshot: null }`. The roster/route/self
+  /// fields are merged in by the bridge from the media adapter.
+  /// `conversationName` nil → NSNull; `reason`/`cameraFacing` omitted when nil.
+  func toSnapshot(conversationName: String? = nil,
+                  participants: [SnapshotParticipant] = [],
+                  audioRoute: String = "earpiece",
+                  mutedSelf: Bool = false,
+                  cameraOn: Bool = false,
+                  cameraFacing: String? = nil) -> [String: Any]? {
+    if phase == .idle { return nil }
+    var out: [String: Any] = [
+      "cv": 1,
+      "callId": callId.map { $0 as Any } ?? NSNull(),
+      "conversationId": conversationId.map { $0 as Any } ?? NSNull(),
+      "conversationName": conversationName.map { $0 as Any } ?? NSNull(),
+      "direction": (direction ?? .incoming).wire,
+      "media": media,
+      "phase": phase.wire,
+      "participants": participants.map { $0.dictionary },
+      "audioRoute": audioRoute,
+      "mutedSelf": mutedSelf,
+      "cameraOn": cameraOn,
+    ]
+    if let reason = reason { out["reason"] = reason.wire }
+    // Optional in the contract: present only while a camera is published.
+    if let cameraFacing = cameraFacing { out["cameraFacing"] = cameraFacing }
+    return out
+  }
+}