@poolse/react-native-calls 0.1.3 → 0.3.0

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

@@ -1,30 +1,183 @@
 package dev.poolse.callcore.android
 
+import android.Manifest
 import android.app.Notification
+import android.app.PendingIntent
 import android.app.Service
 import android.content.Context
 import android.content.Intent
+import android.content.pm.PackageManager
 import android.content.pm.ServiceInfo
 import android.os.Build
+import android.os.Handler
 import android.os.IBinder
+import android.os.Looper
+import android.util.Log
 import androidx.core.app.NotificationCompat
+import androidx.core.content.ContextCompat
 import dev.poolse.callcore.CallSessionPort
 
 /**
- * Keeps a live call alive when the app is backgrounded or killed:
- * a `phoneCall|microphone` foreground service that owns the ongoing
- * notification for the call's whole lifetime. Android will not reclaim
- * the process while this runs, so media keeps flowing with the screen
- * off.
+ * Keeps the process alive while a call needs it:
  *
- * [CallSessionPort] is driven by the runtime (CALL_SESSION_START/STOP);
- * the service itself holds no call logic — it is the OS contract that
- * says "a call is happening here".
+ * - **ring** mode (`phoneCall` type only) for the length of an incoming
+ *   ring, so an OEM freezer (Samsung, Android 14 cached-app freezer)
+ *   does not kill the ringtone and the ring-deadline timer of a closed
+ *   app;
+ * - **call** mode (`phoneCall|microphone`) for a live call's whole
+ *   lifetime, so media keeps flowing with the screen off.
+ *
+ * [CallSessionPort] is driven by the runtime (CALL_SESSION_START/STOP),
+ * ring mode by [CallCore]'s state reconcile; the service itself holds no
+ * call logic — it is the OS contract that says "a call is happening".
+ *
+ * Robustness rules, each one a crash seen in the field:
+ * - every `startForegroundService` MUST be answered by `startForeground`,
+ *   even if the call already ended before `onStartCommand` ran — so a
+ *   stop never calls `stopService` on a not-yet-started service; the
+ *   service starts foreground and then stops itself;
+ * - the microphone type is claimed only with RECORD_AUDIO granted
+ *   (Android 14 throws otherwise);
+ * - `startForeground` failures are caught and the service stops, never
+ *   taking the app down with it.
  */
 class CallForegroundService : Service() {
 
   override fun onBind(intent: Intent?): IBinder? = null
 
+  override fun onCreate() {
+    super.onCreate()
+    instance = this
+  }
+
+  override fun onDestroy() {
+    if (instance === this) instance = null
+    super.onDestroy()
+  }
+
+  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
+    pendingStarts = (pendingStarts - 1).coerceAtLeast(0)
+    reconcile(desired)
+    // Sticky-less: if the system kills us, the call is already gone with
+    // the process; a relaunched empty service would be a ghost.
+    return START_NOT_STICKY
+  }
+
+  /** Bring the service in line with [want]; null = stop (after honouring the start). */
+  internal fun reconcile(want: Desired?) {
+    // Always answer the start with startForeground — a placeholder ring
+    // notification if the call is already gone.
+    val ok = tryStartForeground(want ?: Desired(Mode.RING, "", "audio"))
+    if (want == null || !ok) {
+      if (pendingStarts == 0) stopNow()
+    }
+  }
+
+  internal fun stopNow() {
+    runCatching { stopForeground(STOP_FOREGROUND_REMOVE) }
+    shownId = null
+    stopSelf()
+  }
+
+  /** The notification id we are currently foreground with. */
+  private var shownId: Int? = null
+
+  /**
+   * Start (or switch) foreground. If the full type is refused — the
+   * microphone type can be, on Android 14, when the app is not in a
+   * while-in-use state — fall back to phoneCall only rather than stop:
+   * stopping dropped the ring-mode service that was already working.
+   * Stop only when even that fails.
+   */
+  private fun tryStartForeground(want: Desired): Boolean {
+    val (id, notification) = notificationFor(want)
+    val full = typeFor(want.mode)
+    val attempts = if (full != ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL) {
+      listOf(full, ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL)
+    } else listOf(full)
+    for (type in attempts) {
+      try {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.Q) startForeground(id, notification, type)
+        else startForeground(id, notification)
+        // Switching id (ring → call) leaves the old one as a plain
+        // notification; the ring is over, so remove it.
+        shownId?.takeIf { it != id }?.let { old ->
+          runCatching { getSystemService(android.app.NotificationManager::class.java).cancel(old) }
+        }
+        shownId = id
+        return true
+      } catch (t: Throwable) {
+        // ForegroundServiceStartNotAllowedException, SecurityException
+        // (missing type permission), InvalidForegroundServiceTypeException…
+        Log.e(TAG, "startForeground(${want.mode}, type=$type) failed", t)
+      }
+    }
+    return false
+  }
+
+  /**
+   * Ring mode wears the CallStyle ring notification itself (same id),
+   * so a ringing phone shows ONE notification, not the ring plus an
+   * "Incoming call" service notice. Falls back to our own if the ring
+   * surface has not posted yet.
+   */
+  private fun notificationFor(want: Desired): Pair<Int, Notification> {
+    if (want.mode == Mode.RING) {
+      AndroidRingSurface.shownRing?.let { (callId, n) ->
+        if (callId == want.callId) {
+          return with(AndroidRingSurface) { callId.notificationId() } to n
+        }
+      }
+    }
+    return NOTIFICATION_ID to buildNotification(want)
+  }
+
+  private fun typeFor(mode: Mode): Int {
+    var type = ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL
+    if (mode == Mode.CALL && Build.VERSION.SDK_INT >= Build.VERSION_CODES.R && micGranted()) {
+      type = type or ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
+    }
+    return type
+  }
+
+  private fun micGranted() =
+    ContextCompat.checkSelfPermission(this, Manifest.permission.RECORD_AUDIO) ==
+      PackageManager.PERMISSION_GRANTED
+
+  private fun buildNotification(want: Desired): Notification {
+    ensureChannel()
+    val config = CallCore.peekConfig()
+    val title: String
+    val text: String
+    if (want.mode == Mode.RING) {
+      title = "Incoming call"; text = "Ringing…"
+    } else {
+      title = "Ongoing call"; text = if (want.media == "video") "Video call" else "Voice call"
+    }
+    val builder = NotificationCompat.Builder(this, CHANNEL_ID)
+      .setSmallIcon(config?.smallIcon ?: android.R.drawable.sym_call_outgoing)
+      .setContentTitle(title)
+      .setContentText(text)
+      .setOngoing(true)
+      .setCategory(NotificationCompat.CATEGORY_CALL)
+      .setPriority(NotificationCompat.PRIORITY_LOW)
+    // Tapping the ongoing-call notification returns to the call.
+    if (want.mode == Mode.CALL) launchIntent(want.callId)?.let(builder::setContentIntent)
+    return builder.build()
+  }
+
+  private fun launchIntent(callId: String): PendingIntent? {
+    val launch = packageManager.getLaunchIntentForPackage(packageName) ?: return null
+    launch.addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
+    launch.putExtra(CallCore.EXTRA_LAUNCH_CALL, callId)
+    return PendingIntent.getActivity(
+      this,
+      NOTIFICATION_ID,
+      launch,
+      PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE,
+    )
+  }
+
   // The ongoing-call notification has its own channel, created here so it
   // exists on an OUTGOING call too — the incoming ring surface's channel
   // is only made when a ring shows, so a placed call would otherwise post
@@ -42,58 +195,86 @@ class CallForegroundService : Service() {
     )
   }
 
-  override fun onStartCommand(intent: Intent?, flags: Int, startId: Int): Int {
-    val media = intent?.getStringExtra(EXTRA_MEDIA) ?: "audio"
-    startInForeground(media)
-    // Sticky-less: if the system kills us, the call is already gone with
-    // the process; a relaunched empty service would be a ghost.
-    return START_NOT_STICKY
-  }
-
-  private fun startInForeground(media: String) {
-    ensureChannel()
-    val config = CallCore.peekConfig()
-    val notification: Notification = NotificationCompat.Builder(this, CHANNEL_ID)
-      .setSmallIcon(config?.smallIcon ?: android.R.drawable.sym_call_outgoing)
-      .setContentTitle("Ongoing call")
-      .setContentText(if (media == "video") "Video call" else "Voice call")
-      .setOngoing(true)
-      .setCategory(NotificationCompat.CATEGORY_CALL)
-      .setPriority(NotificationCompat.PRIORITY_LOW)
-      .build()
-
-    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.R) {
-      var type = ServiceInfo.FOREGROUND_SERVICE_TYPE_MICROPHONE
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.UPSIDE_DOWN_CAKE) {
-        type = type or ServiceInfo.FOREGROUND_SERVICE_TYPE_PHONE_CALL
-      }
-      startForeground(NOTIFICATION_ID, notification, type)
-    } else {
-      startForeground(NOTIFICATION_ID, notification)
-    }
-  }
+  internal enum class Mode { RING, CALL }
+  internal data class Desired(val mode: Mode, val callId: String, val media: String)
 
+  /**
+   * All companion state is touched on the main thread only (the
+   * runtime's thread and the service lifecycle's), so no locking.
+   */
   companion object : CallSessionPort {
+    private const val TAG = "PoolseCallFgs"
     private const val NOTIFICATION_ID = 0x9C0FE
-    private const val EXTRA_MEDIA = "media"
     private const val CHANNEL_ID = "poolse_ongoing_call"
 
     private lateinit var appContext: Context
+    private val main by lazy { Handler(Looper.getMainLooper()) }
+
+    private var desired: Desired? = null
+    private var instance: CallForegroundService? = null
+    /** startForegroundService calls not yet delivered to onStartCommand. */
+    private var pendingStarts = 0
 
     /** Wired once by [CallCore] so the port can start/stop the service. */
     fun attach(context: Context) { appContext = context.applicationContext }
 
-    override fun start(callId: String, media: String) {
-      val intent = Intent(appContext, CallForegroundService::class.java).putExtra(EXTRA_MEDIA, media)
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-        appContext.startForegroundService(intent)
-      } else {
-        appContext.startService(intent)
+    override fun start(callId: String, media: String) = onMain {
+      desired = Desired(Mode.CALL, callId, media)
+      launch()
+    }
+
+    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()
+    }
+
+    /** Ring mode for [callId]; a no-op while a call holds the service. */
+    fun startRing(callId: String) = onMain {
+      val d = desired
+      if (d?.mode == Mode.CALL) return@onMain
+      if (d?.mode == Mode.RING && d.callId == callId) return@onMain
+      desired = Desired(Mode.RING, callId, "audio")
+      launch()
+    }
+
+    /**
+     * The call's media became known/changed (a join's bundle said video):
+     * refresh the notification and type in place — no new start needed.
+     */
+    fun updateCall(callId: String, media: String) = onMain {
+      val d = desired
+      if (d?.mode != Mode.CALL || (d.callId == callId && d.media == media)) return@onMain
+      desired = d.copy(callId = callId, media = media)
+      if (pendingStarts == 0) instance?.reconcile(desired)
+    }
+
+    /** Leave ring mode — never touches a call that took the service over. */
+    fun stopRing() = onMain {
+      if (desired?.mode == Mode.RING) stop()
+    }
+
+    private fun launch() {
+      if (!::appContext.isInitialized) return
+      val intent = Intent(appContext, CallForegroundService::class.java)
+      try {
+        if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+          appContext.startForegroundService(intent)
+        } else {
+          appContext.startService(intent)
+        }
+        pendingStarts++
+      } catch (t: Throwable) {
+        // Background-start restriction (no FCM/user exemption at hand).
+        // A running instance can still switch type in place.
+        Log.w(TAG, "could not start the call service", t)
+        instance?.reconcile(desired)
       }
     }
 
-    override fun stop() {
-      appContext.stopService(Intent(appContext, CallForegroundService::class.java))
+    private inline fun onMain(crossinline block: () -> Unit) {
+      if (Looper.myLooper() == Looper.getMainLooper()) block() else main.post { block() }
     }
   }
 }

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

@@ -25,7 +25,12 @@ import org.json.JSONObject
  * those (one retry, then media decides).
  */
 internal class CallHttpClient(
-  private val baseUrl: String,
+  /**
+   * Read per request, not captured: a later `configure()` with another
+   * API origin (staging ↔ prod switch) takes effect on the next call
+   * without rebuilding the process-wide runtime.
+   */
+  private val baseUrl: () -> String,
   private val client: OkHttpClient = defaultClient(),
 ) : HttpPort {
 
@@ -47,8 +52,8 @@ internal class CallHttpClient(
     cb = cb,
   )
 
-  override fun reconnect(callId: String, controlToken: String, cb: (HttpResult) -> Unit) =
-    post("calls/$callId/reconnect", controlToken, body = null, cb = cb)
+  override fun reconnect(current: CallSessionBundle, cb: (HttpResult) -> Unit) =
+    post("calls/${current.callId}/reconnect", current.controlToken, body = null, current = current, cb = cb)
 
   override fun decline(callId: String, auth: String, busy: Boolean) =
     postBestEffort(
@@ -62,24 +67,26 @@ internal class CallHttpClient(
 
   // ── request/response ────────────────────────────────────────────────
 
-  private fun post(path: String, token: String, body: JSONObject?, cb: (HttpResult) -> Unit) {
-    client.newCall(request(path, token, body)).enqueue(object : Callback {
+  private fun post(
+    path: String,
+    token: String,
+    body: JSONObject?,
+    current: CallSessionBundle? = null,
+    cb: (HttpResult) -> Unit,
+  ) {
+    val req = runCatching { request(path, token, body) }.getOrElse {
+      // A malformed base URL is a configuration error, not a timeout:
+      // retrying cannot fix it.
+      cb(HttpResult.Failed("bad_url")); return
+    }
+    client.newCall(req).enqueue(object : Callback {
       override fun onFailure(call: Call, e: IOException) = cb(HttpResult.Timeout)
 
       override fun onResponse(call: Call, response: Response) {
-        response.use {
-          val payload = it.body?.string()
-          cb(
-            when (it.code) {
-              in 200..299 -> runCatching { HttpResult.Ok(parseBundle(payload)) }
-                .getOrElse { HttpResult.Timeout }
-              410 -> HttpResult.Gone
-              401, 403 -> HttpResult.AuthFailed(reasonOf(payload, it.code))
-              408, 429, in 500..599 -> HttpResult.Timeout
-              else -> HttpResult.AuthFailed("http_${it.code}")
-            },
-          )
-        }
+        val result = runCatching {
+          response.use { classify(it.code, it.body?.string(), current) }
+        }.getOrElse { HttpResult.Timeout } // body read failed mid-stream: transient
+        cb(result)
       }
     })
   }
@@ -87,7 +94,8 @@ internal class CallHttpClient(
   // ── fire-and-forget with bounded retry ──────────────────────────────
 
   private fun postBestEffort(path: String, token: String, body: JSONObject?, attempt: Int = 0) {
-    client.newCall(request(path, token, body)).enqueue(object : Callback {
+    val req = runCatching { request(path, token, body) }.getOrNull() ?: return
+    client.newCall(req).enqueue(object : Callback {
       override fun onFailure(call: Call, e: IOException) {
         if (attempt < MAX_BEST_EFFORT_RETRIES) postBestEffort(path, token, body, attempt + 1)
       }
@@ -108,44 +116,87 @@ internal class CallHttpClient(
 
   private fun request(path: String, token: String, body: JSONObject?): Request =
     Request.Builder()
-      .url("$baseUrl/v1/$path")
+      .url("${baseUrl().trimEnd('/')}/v1/$path")
       .header("Authorization", "Bearer $token")
       .header("Accept", "application/json")
       .post((body?.toString() ?: "{}").toRequestBody(JSON))
       .build()
 
-  private fun parseBundle(payload: String?): CallSessionBundle {
-    val root = JSONObject(requireNotNull(payload) { "empty success body" })
-    val call = root.getJSONObject("call")
-    val livekit = root.getJSONObject("livekit")
-    return CallSessionBundle(
-      callId = call.getString("id"),
-      conversationId = call.getString("conversation_id"),
-      conversationName = call.optStringOrNull("conversation_name"),
-      media = call.optString("media", "audio"),
-      created = root.optBoolean("created", true),
-      livekitUrl = livekit.getString("url"),
-      livekitToken = livekit.getString("token"),
-      controlToken = root.getString("control_token"),
-    )
-  }
-
-  private fun reasonOf(payload: String?, code: Int): String =
-    payload?.let { runCatching { JSONObject(it).optStringOrNull("error") }.getOrNull() }
-      ?: "http_$code"
-
-  private fun JSONObject.optStringOrNull(key: String): String? =
-    if (isNull(key)) null else optString(key, "").ifEmpty { null }
-
-  private companion object {
+  internal companion object {
     const val MAX_BEST_EFFORT_RETRIES = 3
     val JSON = "application/json; charset=utf-8".toMediaType()
 
     fun defaultClient(): OkHttpClient = OkHttpClient.Builder()
       // A call action must not hang the ring surface. Short, deliberate
-      // ceilings; the runtime retries answer/place once on top of these.
-      .callTimeout(java.time.Duration.ofSeconds(12))
+      // ceilings; the runtime retries answer/place once on top of these,
+      // and both attempts fit inside its 20 s CONNECTING watchdog.
+      .callTimeout(java.time.Duration.ofSeconds(9))
       .connectTimeout(java.time.Duration.ofSeconds(6))
       .build()
+
+    /**
+     * Status + body → [HttpResult] (CONTRACT.md §4). Pure, so it is unit
+     * tested without a network.
+     *
+     * - 2xx that will not parse is [HttpResult.Failed], NOT a timeout:
+     *   retrying an identical request returns the identical body, and
+     *   treating it as transient left the UI stuck in connecting.
+     * - 404/410: the call (or this device's place in it) is gone.
+     * - 401/403: auth refused — `failed`, never `finished`.
+     * - 503: no SFU capacity / maintenance — terminal for this attempt.
+     */
+    fun classify(code: Int, payload: String?, current: CallSessionBundle? = null): HttpResult =
+      when (code) {
+        in 200..299 -> runCatching { HttpResult.Ok(parseBundle(payload, current)) }
+          .getOrElse { HttpResult.Failed("bad_body") }
+        404, 410 -> HttpResult.Gone
+        401, 403 -> HttpResult.AuthFailed(errorCode(payload) ?: "http_$code")
+        503 -> HttpResult.Failed(errorCode(payload) ?: "http_503")
+        408, 429, in 500..599 -> HttpResult.Timeout
+        else -> HttpResult.Failed(errorCode(payload) ?: "http_$code")
+      }
+
+    /**
+     * One parser for answer, join, place AND reconnect: the server now
+     * returns the full bundle on reconnect too. An older server's
+     * reconnect answered only `{livekit:{url,token}}` (maybe a fresh
+     * `control_token`); with [current] given, that is applied onto the
+     * existing bundle instead of failing.
+     */
+    fun parseBundle(payload: String?, current: CallSessionBundle? = null): CallSessionBundle {
+      val root = JSONObject(requireNotNull(payload) { "empty success body" })
+      val livekit = root.getJSONObject("livekit")
+      val call = root.optJSONObject("call")
+      if (call == null) {
+        requireNotNull(current) { "bundle without call" }
+        return current.copy(
+          livekitUrl = livekit.optStringOrNull("url") ?: current.livekitUrl,
+          livekitToken = livekit.getString("token"),
+          controlToken = root.optStringOrNull("control_token") ?: current.controlToken,
+        )
+      }
+      return CallSessionBundle(
+        callId = call.getString("id"),
+        conversationId = call.getString("conversation_id"),
+        conversationName = call.optStringOrNull("conversation_name") ?: current?.conversationName,
+        media = call.optStringOrNull("media") ?: current?.media ?: "audio",
+        created = root.optBoolean("created", true),
+        livekitUrl = livekit.getString("url"),
+        livekitToken = livekit.getString("token"),
+        controlToken = root.optStringOrNull("control_token")
+          ?: requireNotNull(current?.controlToken) { "bundle without control_token" },
+      )
+    }
+
+    /** The server's envelope is `{"error":{"code":"…"}}`; tolerate a bare string too. */
+    fun errorCode(payload: String?): String? = payload?.let {
+      runCatching {
+        val root = JSONObject(it)
+        root.optJSONObject("error")?.optStringOrNull("code") ?: root.optStringOrNull("error")
+      }.getOrNull()
+    }
+
+    private fun JSONObject.optStringOrNull(key: String): String? =
+      if (!has(key) || isNull(key)) null else (opt(key) as? String)?.ifEmpty { null }
   }
 }

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

@@ -12,7 +12,9 @@ import dev.poolse.callcore.RingContext
  * messaging service (declared via metadata), so chat notifications and
  * everything else keep working unchanged.
  *
- * Contract: data-only messages with `type: "call"` (CONTRACT.md §5).
+ * Contract: data-only messages — rings with `type: "call"`, control
+ * pushes (`ring_ended`, `finished`) with `type: "call_event"`
+ * (CONTRACT.md §5).
  */
 class CallMessagingService : FirebaseMessagingService() {
 
@@ -22,18 +24,42 @@ class CallMessagingService : FirebaseMessagingService() {
     forwardToHost { it.onNewToken(token) }
   }
 
+  override fun onDeletedMessages() {
+    // FCM dropped queued messages; the host's own sync logic needs to know.
+    forwardToHost { it.onDeletedMessages() }
+  }
+
   override fun onMessageReceived(message: RemoteMessage) {
     val data = message.data
-    if (data["type"] != "call") {
+    // Rings ride type=call; control pushes (ring_ended, finished) ride
+    // type=call_event so old JS Android builds — which ring on ANY
+    // type=call — ignore them. Everything else belongs to the host.
+    val type = data["type"]
+    if (type != "call" && type != "call_event") {
       forwardToHost { it.onMessageReceived(message) }
       return
     }
 
-    when (data["event"]) {
-      "ring" -> data.toRingContext()?.let { CallCore.get(this).onRing(it) }
+    // Never configured on this install: nothing can answer a call, and
+    // throwing here would crash the messaging process.
+    val core = CallCore.getOrNull(this) ?: return
+    // A type=call push without an event is a legacy-shaped ring.
+    val event = data["event"]?.ifEmpty { null } ?: if (type == "call") "ring" else return
+    when (event) {
+      // ring_ended reasons: cancelled | answered_elsewhere | declined |
+      // timeout | finished. The machine only lets them end a RINGING_IN,
+      // so an answered_elsewhere echo of THIS device's own answer
+      // (optional device_id) can never end a call we already answered.
+      "ring" -> data.toRingContext()?.let(core::onRing)
       "ring_ended" -> {
         val callId = data["call_id"] ?: return
-        CallCore.get(this).onRingEnded(callId, data["reason"] ?: "finished")
+        core.onRingEnded(callId, data["reason"] ?: "finished")
+      }
+      // The call is over for everyone (CONTRACT.md §5.3). Ends an active
+      // or ringing-out call, and tears down any ring surface still up.
+      "finished" -> {
+        val callId = data["call_id"] ?: return
+        core.onCallFinished(callId, data["reason"]?.ifEmpty { null })
       }
     }
   }
@@ -57,15 +83,17 @@ class CallMessagingService : FirebaseMessagingService() {
    * Forward to the host app's declared FirebaseMessagingService so its
    * own (non-call) pushes still arrive. The host names its class in the
    * manifest: `<meta-data android:name="dev.poolse.callcore.delegate"
-   * android:value="com.app.MyMessagingService"/>`.
+   * android:value="com.app.MyMessagingService"/>` — on `<application>`
+   * (where config plugins put it), or on this service.
+   *
+   * Reading only the SERVICE's meta-data missed the application-level
+   * entry, so every chat push was silently dropped.
    */
   private fun forwardToHost(block: (FirebaseMessagingService) -> Unit) {
-    val name = runCatching {
-      packageManager.getServiceInfo(
-        android.content.ComponentName(this, CallMessagingService::class.java),
-        android.content.pm.PackageManager.GET_META_DATA,
-      ).metaData?.getString(DELEGATE_META)
-    }.getOrNull() ?: return
+    val name = delegateName() ?: run {
+      android.util.Log.w(TAG, "no $DELEGATE_META meta-data: non-call push dropped")
+      return
+    }
 
     runCatching {
       val delegate = Class.forName(name).getDeclaredConstructor().newInstance()
@@ -76,11 +104,29 @@ class CallMessagingService : FirebaseMessagingService() {
         // never crash the call path.
         delegate.attachForDelegation(this)
         block(delegate)
+      } else {
+        android.util.Log.w(TAG, "$name is not a FirebaseMessagingService")
       }
-    }
+    }.onFailure { android.util.Log.e(TAG, "delegate $name failed", it) }
+  }
+
+  private fun delegateName(): String? {
+    val pm = packageManager
+    val fromApp = runCatching {
+      pm.getApplicationInfo(packageName, android.content.pm.PackageManager.GET_META_DATA)
+        .metaData?.getString(DELEGATE_META)
+    }.getOrNull()
+    if (!fromApp.isNullOrEmpty()) return fromApp
+    return runCatching {
+      pm.getServiceInfo(
+        android.content.ComponentName(this, CallMessagingService::class.java),
+        android.content.pm.PackageManager.GET_META_DATA,
+      ).metaData?.getString(DELEGATE_META)
+    }.getOrNull()?.ifEmpty { null }
   }
 
   private companion object {
+    const val TAG = "PoolseCallFcm"
     const val DELEGATE_META = "dev.poolse.callcore.delegate"
   }
 }

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

@@ -0,0 +1,36 @@
+package dev.poolse.callcore.android
+
+import android.content.Context
+import android.view.View
+
+/**
+ * Video rendering, kept SFU-agnostic: a [dev.poolse.callcore.MediaPort]
+ * that can render video ALSO implements this; the bridge's view asks
+ * [CallCore.createVideoSurface] and never sees the SFU's types. A port
+ * without video (the signalling-only fallback) simply doesn't implement
+ * it, and the view stays empty.
+ *
+ * Main thread only — surfaces live in the view hierarchy, and the media
+ * adapter keeps its room on main.
+ */
+interface CallVideoSource {
+  fun createVideoSurface(context: Context): CallVideoSurface
+}
+
+/** One on-screen video slot, bound to a participant's camera. */
+interface CallVideoSurface {
+  /** The Android view to host; it fills its parent. */
+  val view: View
+
+  /**
+   * What to show. [participantId] is the remote's userId (SFU
+   * identity); [local] shows the self view instead. [mirror] null =
+   * the default (mirrored for the local front camera only). [fit] is
+   * `cover` or `contain`. Rebinds immediately and again whenever the
+   * underlying track appears, disappears, mutes or the room is replaced.
+   */
+  fun configure(participantId: String?, local: Boolean, mirror: Boolean?, fit: String)
+
+  /** Detach from any track and free the renderer. Idempotent. */
+  fun release()
+}