@poolse/react-native-calls 0.9.0 → 0.10.1

package/README.md

@@ -51,6 +51,26 @@ A room plays on the speaker unless a headset or Bluetooth device is in,
 and turning the camera on (`setCamera(true)`) is all it takes to go from
 voice to video.
 
+### Call waiting
+
+A call that rings while one is in progress (or while you sit in a room)
+waits beside it instead of being refused: `snapshot.waiting` carries it
+(`callId`, names, media), and the native side shows its own surface —
+CallKit's call-waiting screen on iOS, a heads-up with Decline / End &
+answer and the call-waiting beep on Android.
+
+```ts
+if (s.waiting) {
+  calls.answerWaiting(s.waiting.callId);  // ends this call, answers that one
+  calls.declineWaiting(s.waiting.callId); // its caller hears "Busy"
+}
+```
+
+Pass the `callId`: a tap that lands after the waiting call changed is
+then ignored rather than acting on a different one. If the current call
+ends on its own, the waiting call simply becomes the ringing call; left
+alone it times out as missed. A third call while one waits is busy.
+
 ### Chat notifications
 
 poolse sends message notifications itself, with the push credentials you

package/android/src/main/java/dev/poolse/callcore/CallCoreRuntime.kt

@@ -43,6 +43,9 @@ class CallCoreRuntime(
   /** Grants of rings auto-declined busy, kept until the decline fires. */
   private val busyRings = mutableMapOf<String, RingContext>()
 
+  /** The ring of the call waiting beside the current one (its grant answers or busy-declines it). */
+  private var waitingRingCtx: RingContext? = null
+
   /** The session bundle of the current call, once the server accepted. */
   private var bundle: CallSessionBundle? = null
 
@@ -110,6 +113,7 @@ class CallCoreRuntime(
     private const val T_RECONNECT = "reconnect_budget"
     private const val T_CONNECT = "connect_watchdog"
     private const val T_RING_OUT = "ring_out_backstop"
+    private const val T_WAITING = "waiting_deadline"
   }
 
   // ── inputs from adapters ────────────────────────────────────────────
@@ -122,6 +126,9 @@ class CallCoreRuntime(
   /** `room` or `call`, once the server's bundle says; null before. Runtime thread only. */
   val callKind: String? get() = bundle?.kind
 
+  /** The call waiting beside the current one, with its caller's names. Runtime thread only. */
+  val waitingRing: RingContext? get() = if (state.waiting == null) null else waitingRingCtx
+
   /** True if [callId] was already resolved here — its ring must never surface again. */
   fun isResolved(callId: String): Boolean = synchronized(resolved) { resolved.containsKey(callId) }
 
@@ -168,6 +175,18 @@ class CallCoreRuntime(
   fun answer() = post { dispatch(Event.UserAnswer) }
   fun decline() = post { dispatch(Event.UserDecline) }
   fun hangUp() = post { dispatch(Event.UserHangup) }
+  /**
+   * Call waiting: end this call and answer the one waiting. With
+   * [callId], only if that is still the call waiting (a stale tap on a
+   * surface for an earlier one must not answer a different call).
+   */
+  fun answerWaiting(callId: String? = null) = post {
+    if (callId == null || state.waiting?.callId == callId) dispatch(Event.UserAnswerWaiting)
+  }
+  /** Call waiting: turn the waiting call away (its caller hears busy). */
+  fun declineWaiting(callId: String? = null) = post {
+    if (callId == null || state.waiting?.callId == callId) dispatch(Event.UserDeclineWaiting)
+  }
 
   fun place(conversationId: String, media: String, sessionToken: String) = post {
     if (state.phase != Phase.IDLE && state.phase != Phase.ENDED) return@post
@@ -216,23 +235,30 @@ class CallCoreRuntime(
       gen++
       markResolved(before.callId)
     }
-    for (effect in effects) execute(effect, ringCtx)
+    for (effect in effects) execute(effect, ringCtx, before)
     // Retire the ring grant only after EVERY effect has had its chance
     // to use it. CONNECTING keeps it (answer + the no-bundle hangup
     // fallback still need it); CallSessionStop clears it with the rest.
     if (isTerminal(next.phase)) ring = null
     // A bundle never outlives its call — whatever ended it.
     if (isTerminal(next.phase)) { bundle = null; sessionToken = null }
+    // A waiting call that went away without becoming the current one
+    // (declined, cancelled, timed out) is resolved: its ring never again.
+    before.waiting?.let { w ->
+      if (next.waiting?.callId != w.callId && next.callId != w.callId) markResolved(w.callId)
+    }
+    if (next.waiting == null) waitingRingCtx = null
     runTimers(before, next)
     if (next != before || effects.isNotEmpty()) sink.emit(next)
   }
 
-  private fun execute(effect: Effect, ringCtx: RingContext?) {
+  private fun execute(effect: Effect, ringCtx: RingContext?, before: MachineState) {
     val g = gen
     when (effect) {
       Effect.ShowRing -> {
-        ring = ringCtx
-        ringCtx?.let(surface::show)
+        // A promoted waiting call rings with the ring already on file.
+        if (ringCtx != null) ring = ringCtx
+        ring?.let(surface::show)
       }
       Effect.DismissRing -> {
         (ring ?: ringCtx)?.let { surface.dismiss(it.callId) }
@@ -269,7 +295,8 @@ class CallCoreRuntime(
         ring?.let { http.decline(it.callId, it.grant, busy = false) }
       }
       is Effect.HttpDeclineBusy -> {
-        busyRings[effect.callId]?.let { http.decline(it.callId, it.grant, busy = true) }
+        val waitingMatch = waitingRingCtx?.takeIf { it.callId == effect.callId }
+        (busyRings[effect.callId] ?: waitingMatch)?.let { http.decline(it.callId, it.grant, busy = true) }
         markResolved(effect.callId)
       }
       Effect.HttpHangup -> {
@@ -300,6 +327,23 @@ class CallCoreRuntime(
         ring = null
         sessionToken = null
       }
+
+      Effect.ShowWaiting -> {
+        waitingRingCtx = ringCtx
+        ringCtx?.let(surface::showWaiting)
+      }
+      // The grant is NOT retired here: HTTP_DECLINE_BUSY may precede or follow.
+      Effect.DismissWaiting -> before.waiting?.let { surface.dismissWaiting(it.callId) }
+      Effect.PromoteWaiting -> {
+        // The old call is over: nothing it started may land on this one.
+        markResolved(before.callId)
+        gen++
+        bundle = null
+        sessionToken = null
+        ring = waitingRingCtx
+        waitingRingCtx = null
+        before.waiting?.let { surface.promoteWaiting(it.callId) }
+      }
     }
   }
 
@@ -369,7 +413,10 @@ class CallCoreRuntime(
   }
 
   private fun runTimers(before: MachineState, after: MachineState) {
-    if (before.phase == after.phase) return
+    runWaitingTimer(before, after)
+    // A different call in the same phase (end-and-answer while connecting)
+    // needs its own timers: the old ones belong to a retired generation.
+    if (before.phase == after.phase && before.callId == after.callId) return
     when (before.phase) {
       Phase.RINGING_IN -> timers.cancel(T_DEADLINE)
       Phase.ENDED -> timers.cancel(T_LINGER)
@@ -393,4 +440,17 @@ class CallCoreRuntime(
       else -> Unit
     }
   }
+
+  private fun runWaitingTimer(before: MachineState, after: MachineState) {
+    val was = before.waiting?.callId
+    val now = after.waiting?.callId
+    if (was == now) return
+    if (was != null) timers.cancel(T_WAITING)
+    val deadline = waitingRingCtx?.ringDeadlineEpochMs
+    if (now == null || deadline == null) return
+    val delay = (deadline - timers.nowMs()).coerceAtLeast(CLOCK_SLACK_MS)
+    // Keyed to the waiting call, not the generation: the current call may
+    // move on (connect, reconnect) while this one keeps waiting.
+    timers.schedule(T_WAITING, delay) { post { if (state.waiting?.callId == now) dispatch(Event.WaitingDeadline) } }
+  }
 }

package/android/src/main/java/dev/poolse/callcore/CallMachine.kt

@@ -24,6 +24,16 @@ enum class EndReason {
   val wire: String get() = name.lowercase()
 }
 
+/**
+ * A second call ringing while this device is on one (CONTRACT.md §7,
+ * call waiting): shown beside the current call, never instead of it.
+ */
+data class WaitingCall(
+  val callId: String,
+  val conversationId: String?,
+  val media: String,
+)
+
 /** Everything the machine knows. Immutable; transitions return a new one. */
 data class MachineState(
   val phase: Phase = Phase.IDLE,
@@ -34,6 +44,8 @@ data class MachineState(
   val reason: EndReason? = null,
   /** HTTP attempts made for the current connecting request (retry budget = 2). */
   val httpAttempts: Int = 0,
+  /** A second call ringing beside this one, if any. */
+  val waiting: WaitingCall? = null,
 ) {
   companion object { val IDLE = MachineState() }
 }
@@ -90,6 +102,13 @@ sealed interface Event {
   /** CONNECTING watchdog: neither the server nor the SFU got us in. */
   data object ConnectTimeout : Event
   data object LingerElapsed : Event
+
+  /** Call waiting: leave the current call and answer the waiting one. */
+  data object UserAnswerWaiting : Event
+  /** Call waiting: turn the waiting call away — its caller hears busy. */
+  data object UserDeclineWaiting : Event
+  /** The waiting call's ring deadline passed. */
+  data object WaitingDeadline : Event
 }
 
 /** Abstract effects — each adapter maps them to its platform. */
@@ -113,13 +132,95 @@ sealed interface Effect {
   data object MediaLeave : Effect { override val wire = "MEDIA_LEAVE" }
   data object CallSessionStart : Effect { override val wire = "CALL_SESSION_START" }
   data object CallSessionStop : Effect { override val wire = "CALL_SESSION_STOP" }
+  data object ShowWaiting : Effect { override val wire = "SHOW_WAITING" }
+  data object DismissWaiting : Effect { override val wire = "DISMISS_WAITING" }
+  /**
+   * The waiting call becomes the current one: retire the old call's
+   * grant/bundle/generation and take the waiting ring's.
+   */
+  data object PromoteWaiting : Effect { override val wire = "PROMOTE_WAITING" }
 }
 
 data class Transition(val state: MachineState, val effects: List<Effect>)
 
 object CallMachine {
 
-  fun transition(s: MachineState, e: Event): Transition = when (e) {
+  /**
+   * Phases that can hold a call waiting beside them: this device is on
+   * (or placing, or joining) a call. A second ring while one is ringING
+   * in is still busy — two rings at once is not a choice anyone can make.
+   */
+  private fun canHoldWaiting(s: MachineState) = when (s.phase) {
+    Phase.RINGING_OUT, Phase.CONNECTING, Phase.ACTIVE, Phase.RECONNECTING -> true
+    else -> false
+  }
+
+  /**
+   * The ring surface effects the end-and-answer composite skips: the
+   * waiting call goes straight from waiting to connecting, never ringing.
+   */
+  private val ringSurfaceEffects =
+    setOf<Effect>(Effect.ShowRing, Effect.RingtoneStart, Effect.RingtoneStop, Effect.DismissRing)
+
+  fun transition(s: MachineState, e: Event): Transition {
+    val w = s.waiting
+    if (w == null) {
+      return when {
+        e is Event.Ring && !e.stale && canHoldWaiting(s) && e.callId != s.callId -> Transition(
+          s.copy(waiting = WaitingCall(e.callId, e.conversationId, e.media)),
+          listOf(Effect.ShowWaiting),
+        )
+        e == Event.UserAnswerWaiting || e == Event.UserDeclineWaiting || e == Event.WaitingDeadline -> noop(s)
+        else -> single(s, e)
+      }
+    }
+
+    val cleared = s.copy(waiting = null)
+    return when {
+      e is Event.Ring -> when (e.callId) {
+        w.callId -> noop(s)
+        s.callId -> carry(single(cleared, e), w)
+        else -> if (e.stale) noop(s) else Transition(s, listOf(Effect.HttpDeclineBusy(e.callId)))
+      }
+      e is Event.RingEnded && e.callId == w.callId -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e is Event.CallFinished && e.callId == w.callId -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e == Event.WaitingDeadline -> Transition(cleared, listOf(Effect.DismissWaiting))
+      e == Event.UserDeclineWaiting ->
+        Transition(cleared, listOf(Effect.HttpDeclineBusy(w.callId), Effect.DismissWaiting))
+      e == Event.UserAnswerWaiting -> {
+        // Leaving rings the waiting call (below); answering it at once
+        // makes that ring a no-op the surface never sees.
+        val left = transition(s, Event.UserHangup)
+        if (left.state.phase != Phase.RINGING_IN || left.state.callId != w.callId) {
+          noop(s)
+        } else {
+          val answered = single(left.state, Event.UserAnswer)
+          Transition(answered.state, (left.effects + answered.effects).filterNot { it in ringSurfaceEffects })
+        }
+      }
+      else -> {
+        val t = single(cleared, e)
+        if (t.state.phase != Phase.ENDED && t.state.phase != Phase.IDLE) {
+          carry(t, w)
+        } else {
+          // The current call is over while another rings beside it: that
+          // ring is now simply THE ring (no ended screen in between).
+          Transition(
+            MachineState(
+              phase = Phase.RINGING_IN, callId = w.callId, conversationId = w.conversationId,
+              direction = Direction.INCOMING, media = w.media,
+            ),
+            t.effects + listOf(Effect.PromoteWaiting, Effect.ShowRing, Effect.RingtoneStart),
+          )
+        }
+      }
+    }
+  }
+
+  private fun carry(t: Transition, w: WaitingCall) = Transition(t.state.copy(waiting = w), t.effects)
+
+  /** The one-call machine: everything that is not about a waiting call. */
+  private fun single(s: MachineState, e: Event): Transition = when (e) {
 
     is Event.Ring -> ring(s, e)
 
@@ -351,6 +452,9 @@ object CallMachine {
 
     Event.LingerElapsed ->
       if (s.phase == Phase.ENDED) Transition(MachineState.IDLE, emptyList()) else noop(s)
+
+    // Handled by `transition`, which owns the waiting slot.
+    Event.UserAnswerWaiting, Event.UserDeclineWaiting, Event.WaitingDeadline -> noop(s)
   }
 
   private fun ring(s: MachineState, e: Event.Ring): Transition = when {
@@ -369,8 +473,9 @@ object CallMachine {
       listOf(Effect.ShowRing, Effect.RingtoneStart),
     )
 
-    // Busy with another call, in any phase: auto-decline the newcomer,
-    // whose banner still offers Join later. (Contract §7, scenario s9.)
+    // Busy ringing another call (a call in progress holds it waiting
+    // instead — see `transition`): auto-decline the newcomer, whose
+    // banner still offers Join later. (Contract §7, scenario s9.)
     else -> Transition(s, listOf(Effect.HttpDeclineBusy(e.callId)))
   }
 

package/android/src/main/java/dev/poolse/callcore/Ports.kt

@@ -86,6 +86,18 @@ interface RingSurfacePort {
   fun ringtoneStop()
   fun ringbackStart()
   fun ringbackStop()
+  /**
+   * A call waiting beside the current one: its own quiet surface (a
+   * heads-up with a waiting tone; iOS: CallKit's call-waiting UI).
+   */
+  fun showWaiting(ring: RingContext) {}
+  /** The waiting call is over (declined, cancelled, timed out). */
+  fun dismissWaiting(callId: String) {}
+  /**
+   * The waiting call becomes THE ring (SHOW_RING follows): drop its
+   * waiting surface without resolving it.
+   */
+  fun promoteWaiting(callId: String) {}
 }
 
 data class RingContext(

package/android/src/main/java/dev/poolse/callcore/android/AndroidRingSurface.kt

@@ -6,7 +6,11 @@ import android.app.PendingIntent
 import android.content.Context
 import android.content.Intent
 import android.media.AudioAttributes
+import android.media.AudioManager
 import android.media.MediaPlayer
+import android.media.ToneGenerator
+import android.os.Handler
+import android.os.Looper
 import android.media.Ringtone
 import android.media.RingtoneManager
 import android.os.Build
@@ -50,6 +54,18 @@ internal class AndroidRingSurface(
   private var ringbackWanted = false
   private var communicationReady = false
 
+  /** The call waiting beside the current one, while its surface is up. */
+  private var waitingCallId: String? = null
+  private var waitingTone: ToneGenerator? = null
+  private val main = Handler(Looper.getMainLooper())
+  private val waitingBeep = object : Runnable {
+    override fun run() {
+      if (waitingCallId == null) return
+      runCatching { waitingTone?.startTone(ToneGenerator.TONE_SUP_CALL_WAITING, WAITING_BEEP_MS) }
+      main.postDelayed(this, WAITING_BEEP_EVERY_MS)
+    }
+  }
+
   /**
    * The call's audio path is (or is no longer) in communication mode.
    * A ringback requested earlier starts now, through the call route.
@@ -134,7 +150,122 @@ internal class AndroidRingSurface(
     }
   }
 
+  /**
+   * A call waiting beside the one in progress: a quiet heads-up — not
+   * the full-screen ring, which would cover the call — with Decline and
+   * End & answer, and the call-waiting beep through the call's own
+   * audio route (the ringtone would blare over the conversation).
+   */
+  override fun showWaiting(ring: RingContext) {
+    ensureWaitingChannel()
+    val extras = ring.toBundle()
+
+    fun actionPending(action: String, requestOffset: Int): PendingIntent {
+      val intent = Intent(context, CallActionReceiver::class.java)
+        .setAction("$ACTION_PREFIX.$action")
+        .putExtra(EXTRA_RING, extras)
+      return PendingIntent.getBroadcast(
+        context,
+        ring.callId.hashCode() + requestOffset,
+        intent,
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    }
+
+    val open = context.packageManager.getLaunchIntentForPackage(context.packageName)?.let {
+      PendingIntent.getActivity(
+        context,
+        ring.callId.hashCode() + 5,
+        it.addFlags(Intent.FLAG_ACTIVITY_SINGLE_TOP or Intent.FLAG_ACTIVITY_REORDER_TO_FRONT),
+        PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+      )
+    }
+
+    // End & answer launches an ACTIVITY, like the ring's Answer: only an
+    // activity started from the tap may bring the app forward (Android
+    // 10+), and the call that connects should be seen.
+    val answerWaiting = PendingIntent.getActivity(
+      context,
+      ring.callId.hashCode() + 4,
+      Intent(context, IncomingCallActivity::class.java)
+        .putExtra(EXTRA_RING, extras)
+        .putExtra(EXTRA_WAITING_ANSWER, true)
+        .addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_CLEAR_TOP),
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+
+    val who = ring.conversationName ?: ring.callerName ?: "Someone"
+    val what = if (ring.media == "video") "video call" else "call"
+    val notification = NotificationCompat.Builder(context, WAITING_CHANNEL_ID)
+      .setSmallIcon(config.smallIcon)
+      .setCategory(NotificationCompat.CATEGORY_CALL)
+      .setPriority(NotificationCompat.PRIORITY_HIGH)
+      .setVisibility(NotificationCompat.VISIBILITY_PUBLIC)
+      .setContentTitle("$who — incoming $what")
+      .setContentText("You're on a call. Answering ends it.")
+      .setOngoing(true)
+      .setAutoCancel(false)
+      .setOnlyAlertOnce(true)
+      .apply { if (open != null) setContentIntent(open) }
+      .addAction(0, "Decline", actionPending(ACTION_WAITING_DECLINE, 3))
+      .addAction(0, "End & answer", answerWaiting)
+      // Never outlive the ring: if its ring_ended/finished push is lost,
+      // the system takes the heads-up down at the deadline anyway.
+      .setTimeoutAfter((ring.ringDeadlineEpochMs - System.currentTimeMillis()).coerceAtLeast(10_000L))
+      .build()
+
+    waitingCallId = ring.callId
+    try {
+      NotificationManagerCompat.from(context).notify(ring.callId.notificationId(), notification)
+    } catch (e: SecurityException) {
+      Log.e(TAG, "call-waiting notification refused (POST_NOTIFICATIONS?)", e)
+    }
+    startWaitingBeep()
+  }
+
+  override fun dismissWaiting(callId: String) {
+    if (waitingCallId != callId) return
+    stopWaitingBeep()
+    runCatching { NotificationManagerCompat.from(context).cancel(callId.notificationId()) }
+  }
+
+  /** SHOW_RING follows, reposting under the same id as the full ring. */
+  override fun promoteWaiting(callId: String) = dismissWaiting(callId)
+
+  private fun startWaitingBeep() {
+    main.removeCallbacks(waitingBeep)
+    if (waitingTone == null) {
+      waitingTone = runCatching { ToneGenerator(AudioManager.STREAM_VOICE_CALL, WAITING_BEEP_VOLUME) }.getOrNull()
+    }
+    main.post(waitingBeep)
+  }
+
+  private fun stopWaitingBeep() {
+    waitingCallId = null
+    main.removeCallbacks(waitingBeep)
+    runCatching { waitingTone?.stopTone(); waitingTone?.release() }
+    waitingTone = null
+  }
+
+  private fun ensureWaitingChannel() {
+    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) return
+    val manager = context.getSystemService(NotificationManager::class.java)
+    if (manager.getNotificationChannel(WAITING_CHANNEL_ID) != null) return
+    // Silent: the beep is ours, through the call route. A channel sound
+    // would play on the notification stream over the conversation.
+    manager.createNotificationChannel(
+      NotificationChannel(WAITING_CHANNEL_ID, "Calls while on a call", NotificationManager.IMPORTANCE_HIGH).apply {
+        setSound(null, null)
+        enableVibration(false)
+        lockscreenVisibility = NotificationCompat.VISIBILITY_PUBLIC
+      },
+    )
+  }
+
   override fun dismiss(callId: String) {
+    // Every teardown for a call (ring_ended, finished) also ends its
+    // waiting surface, even after a restart lost the in-memory state.
+    if (waitingCallId == callId) stopWaitingBeep()
     if (shownRing?.first == callId) shownRing = null
     runCatching { NotificationManagerCompat.from(context).cancel(callId.notificationId()) }
     // The full-screen activity is its own window: tell it to close.
@@ -222,8 +353,15 @@ internal class AndroidRingSurface(
     const val ACTION_ANSWER = "ANSWER"
     const val ACTION_DECLINE = "DECLINE"
     const val ACTION_OPEN = "OPEN"
+    const val ACTION_WAITING_ANSWER = "WAITING_ANSWER"
+    const val ACTION_WAITING_DECLINE = "WAITING_DECLINE"
+    const val WAITING_CHANNEL_ID = "poolse_call_waiting"
+    private const val WAITING_BEEP_MS = 400
+    private const val WAITING_BEEP_EVERY_MS = 3_000L
+    private const val WAITING_BEEP_VOLUME = 70
     const val EXTRA_RING = "poolse_ring"
     const val EXTRA_AUTO_ANSWER = "poolse_auto_answer"
+    const val EXTRA_WAITING_ANSWER = "poolse_waiting_answer"
     /** Package-local broadcast: the ring for [EXTRA_CALL_ID] is over. */
     const val ACTION_RING_CLOSED = "dev.poolse.callcore.RING_CLOSED"
     const val EXTRA_CALL_ID = "poolse_call_id"

package/android/src/main/java/dev/poolse/callcore/android/CallActionReceiver.kt

@@ -3,11 +3,15 @@ package dev.poolse.callcore.android
 import android.content.BroadcastReceiver
 import android.content.Context
 import android.content.Intent
+import androidx.core.app.NotificationManagerCompat
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_ANSWER
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_DECLINE
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_OPEN
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_PREFIX
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_WAITING_ANSWER
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.ACTION_WAITING_DECLINE
 import dev.poolse.callcore.android.AndroidRingSurface.Companion.EXTRA_RING
+import dev.poolse.callcore.android.AndroidRingSurface.Companion.notificationId
 
 /**
  * Answer / Decline taps on the CallStyle notification land here, as do
@@ -24,6 +28,18 @@ class CallActionReceiver : BroadcastReceiver() {
       "$ACTION_PREFIX.$ACTION_ANSWER" -> core.onUserAnswer(ring)
       "$ACTION_PREFIX.$ACTION_DECLINE" -> core.onUserDecline(ring)
       "$ACTION_PREFIX.$ACTION_OPEN" -> core.onUserOpen(ring)
+      // Call waiting: keyed to THIS call, so a stale notification can
+      // never act on a different one — and one outliving its call (a
+      // process restart) is simply taken down.
+      "$ACTION_PREFIX.$ACTION_WAITING_ANSWER", "$ACTION_PREFIX.$ACTION_WAITING_DECLINE" -> {
+        if (core.state().waiting?.callId != ring.callId) {
+          NotificationManagerCompat.from(context).cancel(ring.callId.notificationId())
+        } else if (intent.action == "$ACTION_PREFIX.$ACTION_WAITING_ANSWER") {
+          core.answerWaiting(ring.callId)
+        } else {
+          core.declineWaiting(ring.callId)
+        }
+      }
     }
   }
 }

package/android/src/main/java/dev/poolse/callcore/android/CallCore.kt

@@ -122,6 +122,23 @@ class CallCore private constructor(context: Context) {
     return bringAppToFront(ring.callId, from)
   }
 
+  /**
+   * End & answer from the call-waiting heads-up. Only for the call still
+   * waiting (a stale notification is just taken down); brings the app
+   * forward from [from], like [onUserAnswer].
+   */
+  fun onUserAnswerWaiting(ring: RingContext, from: Context? = null): Boolean {
+    if (runtime.currentState().waiting?.callId != ring.callId) {
+      runCatching {
+        androidx.core.app.NotificationManagerCompat.from(appContext)
+          .cancel(with(AndroidRingSurface) { ring.callId.notificationId() })
+      }
+      return false
+    }
+    runtime.answerWaiting(ring.callId)
+    return bringAppToFront(ring.callId, from)
+  }
+
   fun onUserDecline(ring: RingContext) {
     runtime.onRing(ring)
     runtime.decline()
@@ -142,6 +159,10 @@ class CallCore private constructor(context: Context) {
   fun answer() = runtime.answer()
   fun decline() = runtime.decline()
   fun hangUp() = runtime.hangUp()
+  /** Call waiting: end this call, answer the waiting one ([callId]: only if still that one). */
+  fun answerWaiting(callId: String? = null) = runtime.answerWaiting(callId)
+  /** Call waiting: turn the waiting call away — its caller hears busy. */
+  fun declineWaiting(callId: String? = null) = runtime.declineWaiting(callId)
   fun place(conversationId: String, media: String, sessionToken: String) =
     runtime.place(conversationId, media, sessionToken)
   fun join(callId: String, conversationId: String?, sessionToken: String) =
@@ -201,8 +222,10 @@ class CallCore private constructor(context: Context) {
       }
       resetExtras(null, null)
     } else if (state.callId != extrasCallId) {
-      // `pending:<conv>` → the server-minted id is the same call.
-      if (extrasCallId?.startsWith("pending:") == true) extrasCallId = state.callId
+      // `pending:<conv>` → the server-minted id is the same call — but
+      // only for that conversation's own placed call: a waiting call
+      // promoted over a still-pending one is a different call.
+      if (isRenameOfPending(extrasCallId, state)) extrasCallId = state.callId
       else resetExtras(state.callId, state.media)
     }
     if (state.phase != Phase.IDLE && state.media != extrasMedia) {
@@ -235,12 +258,18 @@ class CallCore private constructor(context: Context) {
       mutedSelf = mutedSelf,
       cameraOn = cameraOn,
       cameraFacing = cameraFacing,
+      waitingRing = runtime.waitingRing,
     )
     lastSnapshot = snap
     reconcileAndroid(state)
     runCatching { listener?.invoke(snap) }.onFailure { Log.w(TAG, "snapshot listener failed", it) }
   }
 
+  private fun isRenameOfPending(previous: String?, state: MachineState): Boolean =
+    previous != null && previous.startsWith("pending:") &&
+      state.direction != dev.poolse.callcore.Direction.INCOMING &&
+      previous == "pending:${state.conversationId}"
+
   private fun resetExtras(callId: String?, media: String?) {
     extrasCallId = callId
     extrasMedia = media

package/android/src/main/java/dev/poolse/callcore/android/CallForegroundService.kt

@@ -220,14 +220,22 @@ class CallForegroundService : Service() {
 
     override fun start(callId: String, media: String) = onMain {
       desired = Desired(Mode.CALL, callId, media)
-      launch()
+      launchOrSwitch()
     }
 
     override fun stop() = onMain {
       desired = null
-      // Only a started instance with nothing pending may stop now; a
-      // pending start stops itself after startForeground.
-      if (pendingStarts == 0) instance?.stopNow()
+      // Deferred to the end of this main-thread turn: a call handing over
+      // to the next (call waiting: end & answer, or a promoted ring) stops
+      // and starts in one dispatch, and must switch the RUNNING service
+      // in place — a fresh start from the background is refused on
+      // Android 12+ (and loses the microphone type on 14+). A start in
+      // the same turn sets `desired` again and this does nothing.
+      main.post {
+        // Only a started instance with nothing pending may stop now; a
+        // pending start stops itself after startForeground.
+        if (desired == null && pendingStarts == 0) instance?.stopNow()
+      }
     }
 
     /** Ring mode for [callId]; a no-op while a call holds the service. */
@@ -236,7 +244,7 @@ class CallForegroundService : Service() {
       if (d?.mode == Mode.CALL) return@onMain
       if (d?.mode == Mode.RING && d.callId == callId) return@onMain
       desired = Desired(Mode.RING, callId, "audio")
-      launch()
+      launchOrSwitch()
     }
 
     /**
@@ -255,6 +263,12 @@ class CallForegroundService : Service() {
       if (desired?.mode == Mode.RING) stop()
     }
 
+    /** A running, settled instance switches in place; otherwise start one. */
+    private fun launchOrSwitch() {
+      val running = instance
+      if (running != null && pendingStarts == 0) running.reconcile(desired) else launch()
+    }
+
     private fun launch() {
       if (!::appContext.isInitialized) return
       val intent = Intent(appContext, CallForegroundService::class.java)