@qusaieilouti99/call-manager 0.1.178 → 0.1.180

package/android/src/main/java/com/margelo/nitro/qusaieilouti99/callmanager/CallEngine.kt

@@ -9,7 +9,6 @@ import android.content.ComponentName
 import android.content.Context
 import android.content.Intent
 import android.graphics.Color
-import android.media.AudioAttributes
 import android.media.AudioManager
 import android.media.MediaPlayer
 import android.media.RingtoneManager
@@ -22,7 +21,6 @@ import android.os.PowerManager
 import android.os.ParcelUuid
 import android.os.VibrationEffect
 import android.os.Vibrator
-import android.telecom.CallAudioState
 import android.telecom.CallEndpoint
 import android.telecom.Connection
 import android.telecom.DisconnectCause
@@ -40,7 +38,7 @@ import android.app.KeyguardManager
 import java.util.UUID
 
 /**
- * Core call‐management engine. Manages self-managed telecom calls,
+ * Core call-management engine. Manages self-managed telecom calls,
  * audio routing, UI notifications, etc.
  *
  * Audio routing now primarily leverages Android Telecom's CallEndpoint API (API 34+),
@@ -88,7 +86,8 @@ object CallEngine {
   private var eventHandler: ((CallEventType, String) -> Unit)? = null
   private val cachedEvents = mutableListOf<Pair<CallEventType, String>>()
 
-  // Audio routing state for CallEndpoint API (API 34+)
+  // Audio routing state for CallEndpoint API (API 34+).
+  // These variables track the system's reported audio state via Telecom.
   private var currentActiveCallEndpoint: CallEndpoint? = null
   private var availableCallEndpoints: List<CallEndpoint> = emptyList()
   private var wasManuallySetAudioRoute: Boolean = false
@@ -98,6 +97,11 @@ object CallEngine {
     fun onLockScreenBypassChanged(shouldBypass: Boolean)
   }
 
+  /**
+   * Initializes the CallEngine with the application context.
+   * This should be called once in your Application's onCreate method.
+   * Subsequent calls will be ignored.
+   */
   fun initialize(context: Context) {
     synchronized(initializationLock) {
       if (isInitialized.compareAndSet(false, true)) {
@@ -105,7 +109,7 @@ object CallEngine {
         audioManager = appContext?.getSystemService(Context.AUDIO_SERVICE) as? AudioManager
         Log.d(TAG, "CallEngine initialized successfully")
         if (isCallActive()) {
-          startForegroundService()
+          startForegroundService() // Start foreground service if calls are already active (e.g., app resumed)
         }
       }
     }
@@ -113,6 +117,9 @@ object CallEngine {
 
   fun isInitialized(): Boolean = isInitialized.get()
 
+  /**
+   * Returns the application context. Throws IllegalStateException if not initialized.
+   */
   private fun requireContext(): Context {
     return appContext ?: throw IllegalStateException(
       "CallEngine not initialized. Call initialize() in Application.onCreate()"
@@ -121,6 +128,10 @@ object CallEngine {
 
   fun getContext(): Context? = appContext
 
+  /**
+   * Sets the event handler for emitting native call events to the JavaScript layer.
+   * If there are cached events, they will be emitted immediately.
+   */
   fun setEventHandler(handler: ((CallEventType, String) -> Unit)?) {
     Log.d(TAG, "setEventHandler called. Handler present: ${handler != null}")
     eventHandler = handler
@@ -133,6 +144,10 @@ object CallEngine {
     }
   }
 
+  /**
+   * Emits a call event with a JSON payload to the registered event handler.
+   * If no handler is registered, the event is cached.
+   */
   fun emitEvent(type: CallEventType, data: JSONObject) {
     Log.d(TAG, "Emitting event: $type")
     val dataString = data.toString()
@@ -144,6 +159,32 @@ object CallEngine {
     }
   }
 
+  /**
+   * Helper function to emit call events that include call metadata.
+   */
+  private fun emitCallEventWithMetadata(eventType: CallEventType, callId: String) {
+    val callInfo = activeCalls[callId] ?: return
+    val metadata = callMetadata[callId]
+
+    emitEvent(eventType, JSONObject().apply {
+      put("callId", callId)
+      put("callType", callInfo.callType)
+      put("displayName", callInfo.displayName)
+      callInfo.pictureUrl?.let { put("pictureUrl", it) }
+      metadata?.let {
+        try {
+          put("metadata", JSONObject(it))
+        } catch (e: Exception) {
+          put("metadata", it)
+        }
+      }
+    })
+  }
+
+  /**
+   * Checks if the device and Android version (API 31+) support CallStyle notifications.
+   * This is typically based on manufacturer and brand heuristics for better compatibility.
+   */
   private fun supportsCallStyleNotifications(): Boolean {
     // CallStyle notifications are available from Android S (API 31)
     if (Build.VERSION.SDK_INT < Build.VERSION_CODES.S) return false
@@ -168,6 +209,10 @@ object CallEngine {
     return isSupported
   }
 
+  /**
+   * Stops the currently playing incoming call ringtone.
+   * Called by [MyConnection.onSilence] when Telecom requests it.
+   */
   fun silenceIncomingCall() {
     Log.d(TAG, "Silencing incoming call ringtone via Connection.onSilence()")
     stopRingtone()
@@ -181,6 +226,10 @@ object CallEngine {
     lockScreenBypassCallbacks.remove(callback)
   }
 
+  /**
+   * Updates the lock screen bypass state and notifies registered callbacks.
+   * This helps manage fullscreen incoming call UI behavior.
+   */
   private fun updateLockScreenBypass() {
     val shouldBypass = isCallActive()
     if (lockScreenBypassActive != shouldBypass) {
@@ -198,11 +247,17 @@ object CallEngine {
 
   fun isLockScreenBypassActive(): Boolean = lockScreenBypassActive
 
+  /**
+   * Adds a Telecom [Connection] object to internal map for tracking.
+   */
   fun addTelecomConnection(callId: String, connection: Connection) {
     telecomConnections[callId] = connection
     Log.d(TAG, "Added Telecom Connection for callId: $callId")
   }
 
+  /**
+   * Removes a Telecom [Connection] object from internal map.
+   */
   fun removeTelecomConnection(callId: String) {
     telecomConnections.remove(callId)
     Log.d(TAG, "Removed Telecom Connection for callId: $callId")
@@ -210,11 +265,17 @@ object CallEngine {
 
   fun getTelecomConnection(callId: String): Connection? = telecomConnections[callId]
 
+  /**
+   * Sets whether the app can handle multiple concurrent calls.
+   */
   fun setCanMakeMultipleCalls(allow: Boolean) {
     canMakeMultipleCalls = allow
     Log.d(TAG, "canMakeMultipleCalls set to: $allow")
   }
 
+  /**
+   * Returns the current state of all active calls as a JSON string.
+   */
   fun getCurrentCallState(): String {
     val calls = getActiveCalls()
     val jsonArray = JSONArray()
@@ -224,6 +285,10 @@ object CallEngine {
     return jsonArray.toString()
   }
 
+  /**
+   * Reports a new incoming call to the Android Telecom framework.
+   * This initiates the incoming call UI (notification/activity overlay) and ringing.
+   */
   fun reportIncomingCall(
     context: Context,
     callId: String,
@@ -255,7 +320,7 @@ object CallEngine {
       return
     }
 
-    val isVideoCall = callType == "Video"
+    // If multiple calls are not allowed and there's an active call, hold it.
     if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) {
       activeCalls.values.forEach {
         if (it.state == CallState.ACTIVE) {
@@ -264,24 +329,24 @@ object CallEngine {
       }
     }
 
-    activeCalls[callId] =
-      CallInfo(callId, callType, displayName, pictureUrl, CallState.INCOMING)
+    activeCalls[callId] = CallInfo(callId, callType, displayName, pictureUrl, CallState.INCOMING)
     currentCallId = callId
     Log.d(TAG, "Call $callId added to activeCalls. State: INCOMING")
 
     showIncomingCallUI(callId, displayName, callType, pictureUrl)
     registerPhoneAccount()
 
-    val telecomManager =
-      requireContext().getSystemService(Context.TELECOM_SERVICE) as TelecomManager
+    val telecomManager = requireContext().getSystemService(Context.TELECOM_SERVICE) as TelecomManager
     val phoneAccountHandle = getPhoneAccountHandle()
+    val isVideoCall = callType == "Video"
+
     val extras = Bundle().apply {
       putString(MyConnectionService.EXTRA_CALL_ID, callId)
       putString(MyConnectionService.EXTRA_CALL_TYPE, callType)
       putString(MyConnectionService.EXTRA_DISPLAY_NAME, displayName)
       putBoolean(MyConnectionService.EXTRA_IS_VIDEO_CALL_BOOLEAN, isVideoCall)
       pictureUrl?.let { putString(MyConnectionService.EXTRA_PICTURE_URL, it) }
-      // TelecomManager.EXTRA_INCOMING_VIDEO_STATE is used here to hint the video state to Telecom
+      // Hint the video state to Telecom.
       putInt(TelecomManager.EXTRA_INCOMING_VIDEO_STATE, if (isVideoCall) VideoProfile.STATE_BIDIRECTIONAL else VideoProfile.STATE_AUDIO_ONLY)
     }
 
@@ -297,6 +362,10 @@ object CallEngine {
     updateLockScreenBypass()
   }
 
+  /**
+   * Initiates a new outgoing call via the Android Telecom framework.
+   * This will lead to [MyConnectionService.onCreateOutgoingConnection].
+   */
   fun startOutgoingCall(
     callId: String,
     callType: String,
@@ -316,6 +385,7 @@ object CallEngine {
       return
     }
 
+    // If multiple calls are not allowed and there's an active call, hold it.
     val isVideoCall = callType == "Video"
     if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) {
       activeCalls.values.forEach {
@@ -329,10 +399,9 @@ object CallEngine {
     currentCallId = callId
     Log.d(TAG, "Call $callId added to activeCalls. State: DIALING")
 
-    registerPhoneAccount()
+    registerPhoneAccount() // Register phone account before placing call
 
-    val telecomManager =
-      context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
+    val telecomManager = context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
     val phoneAccountHandle = getPhoneAccountHandle()
     val addressUri = Uri.fromParts(PhoneAccount.SCHEME_TEL, targetName, null)
 
@@ -366,6 +435,11 @@ object CallEngine {
     updateLockScreenBypass()
   }
 
+  /**
+   * Handles two scenarios:
+   * 1. If `callId` corresponds to an existing INCOMING call, it answers that call.
+   * 2. Otherwise, it initiates a new outgoing call and immediately transitions it to ACTIVE.
+   */
   fun startCall(
     callId: String,
     callType: String,
@@ -379,84 +453,95 @@ object CallEngine {
     if (existingCallInfo != null && existingCallInfo.state == CallState.INCOMING) {
       // Scenario 1: Call with this ID is already incoming, answer it.
       Log.d(TAG, "Call $callId is incoming, answering it directly via startCall.")
-      answerCall(callId)
-    } else {
-      // Scenario 2: Call is new or not incoming, treat as new outgoing call that is immediately active.
-      Log.d(TAG, "Call $callId is new or not incoming. Initiating as outgoing and immediately active.")
-      if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) { // Only check if multiple calls are not allowed
-          if (!validateOutgoingCallRequest()) {
-              Log.w(TAG, "Rejecting startCall as outgoing - incoming/active call exists")
-              emitEvent(CallEventType.CALL_REJECTED, JSONObject().apply {
-                  put("callId", callId)
-                  put("reason", "Cannot start new active call while incoming or active call exists")
-              })
-              return
-          }
+      answerCall(callId) // Call answerCall, which will internally call coreCallAnswered
+      return // Important: Exit here to prevent initiating a new outgoing call.
+    }
+
+    // Scenario 2: Call is new or not incoming. Treat as a new outgoing call that should be
+    // immediately active. This involves placing a Telecom call and then marking it answered.
+    Log.d(TAG, "Call $callId is new or not incoming. Initiating as outgoing and immediately active.")
+    if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) {
+      if (!validateOutgoingCallRequest()) {
+        Log.w(TAG, "Rejecting startCall as new outgoing - incoming/active call exists and multi-call is not allowed")
+        emitEvent(CallEventType.CALL_REJECTED, JSONObject().apply {
+          put("callId", callId)
+          put("reason", "Cannot start new active call while incoming or active call exists")
+        })
+        return
       }
+    }
 
-      val isVideoCall = callType == "Video"
-      if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) {
-        activeCalls.values.forEach {
-          if (it.state == CallState.ACTIVE) {
-            holdCallInternal(it.callId, heldBySystem = false)
-          }
+    val isVideoCall = callType == "Video"
+    if (!canMakeMultipleCalls && activeCalls.isNotEmpty()) {
+      activeCalls.values.forEach {
+        if (it.state == CallState.ACTIVE) {
+          holdCallInternal(it.callId, heldBySystem = false)
         }
       }
+    }
 
-      activeCalls[callId] = CallInfo(callId, callType, targetName, null, CallState.DIALING) // Temporarily DIALING for Telecom
-      currentCallId = callId
-      Log.d(TAG, "Call $callId added to activeCalls. Initial state: DIALING (for Telecom)")
+    // Temporarily set state to DIALING for Telecom to process it as an outgoing call.
+    activeCalls[callId] = CallInfo(callId, callType, targetName, null, CallState.DIALING)
+    currentCallId = callId
+    Log.d(TAG, "Call $callId added to activeCalls. Initial state: DIALING (for Telecom)")
 
+    registerPhoneAccount()
 
-      registerPhoneAccount()
+    val telecomManager = requireContext().getSystemService(Context.TELECOM_SERVICE) as TelecomManager
+    val phoneAccountHandle = getPhoneAccountHandle()
+    val addressUri = Uri.fromParts(PhoneAccount.SCHEME_TEL, targetName, null)
 
-      val telecomManager = requireContext().getSystemService(Context.TELECOM_SERVICE) as TelecomManager
-      val phoneAccountHandle = getPhoneAccountHandle()
-      val addressUri = Uri.fromParts(PhoneAccount.SCHEME_TEL, targetName, null)
+    val outgoingExtrasForConnectionService = Bundle().apply {
+      putString(MyConnectionService.EXTRA_CALL_ID, callId)
+      putString(MyConnectionService.EXTRA_CALL_TYPE, callType)
+      putString(MyConnectionService.EXTRA_DISPLAY_NAME, targetName)
+      putBoolean(MyConnectionService.EXTRA_IS_VIDEO_CALL_BOOLEAN, isVideoCall)
+      metadata?.let { putString("metadata", it) }
+    }
 
-      val outgoingExtrasForConnectionService = Bundle().apply {
-        putString(MyConnectionService.EXTRA_CALL_ID, callId)
-        putString(MyConnectionService.EXTRA_CALL_TYPE, callType)
-        putString(MyConnectionService.EXTRA_DISPLAY_NAME, targetName)
-        putBoolean(MyConnectionService.EXTRA_IS_VIDEO_CALL_BOOLEAN, isVideoCall)
-        metadata?.let { putString("metadata", it) }
-      }
+    val placeCallExtras = Bundle().apply {
+      putParcelable(TelecomManager.EXTRA_PHONE_ACCOUNT_HANDLE, phoneAccountHandle)
+      putBundle(TelecomManager.EXTRA_OUTGOING_CALL_EXTRAS, outgoingExtrasForConnectionService)
+      putBoolean(TelecomManager.EXTRA_START_CALL_WITH_SPEAKERPHONE, isVideoCall) // Hint for video calls
+      putInt(TelecomManager.EXTRA_START_CALL_WITH_VIDEO_STATE, if (isVideoCall) VideoProfile.STATE_BIDIRECTIONAL else VideoProfile.STATE_AUDIO_ONLY)
+    }
 
-      val placeCallExtras = Bundle().apply {
-        putParcelable(TelecomManager.EXTRA_PHONE_ACCOUNT_HANDLE, phoneAccountHandle)
-        putBundle(TelecomManager.EXTRA_OUTGOING_CALL_EXTRAS, outgoingExtrasForConnectionService)
-        putBoolean(TelecomManager.EXTRA_START_CALL_WITH_SPEAKERPHONE, isVideoCall) // Hint for video calls
-        putInt(TelecomManager.EXTRA_START_CALL_WITH_VIDEO_STATE, if (isVideoCall) VideoProfile.STATE_BIDIRECTIONAL else VideoProfile.STATE_AUDIO_ONLY)
-      }
+    try {
+      telecomManager.placeCall(addressUri, placeCallExtras)
+      startForegroundService()
+      bringAppToForeground()
+      keepScreenAwake(true)
+      Log.d(TAG, "Successfully reported outgoing call (to be immediately active) to TelecomManager for $callId")
 
-      try {
-        telecomManager.placeCall(addressUri, placeCallExtras)
-        startForegroundService()
-        bringAppToForeground()
-        keepScreenAwake(true)
-        Log.d(TAG, "Successfully reported outgoing call (to be immediately active) to TelecomManager for $callId")
-
-        // Immediately mark as answered for "startCall" behavior
-        coreCallAnswered(callId, isLocalAnswer = false) // isLocalAnswer = false as it's not a direct answer action from the user on an incoming call.
-      } catch (e: Exception) {
-        Log.e(TAG, "Failed to start call as active: ${e.message}", e)
-        endCallInternal(callId)
-      }
+      // Immediately mark as answered for "startCall" behavior, simulating an answered outgoing call.
+      coreCallAnswered(callId, isLocalAnswer = false)
+    } catch (e: Exception) {
+      Log.e(TAG, "Failed to start call as active: ${e.message}", e)
+      endCallInternal(callId)
     }
-
     updateLockScreenBypass()
   }
 
+  /**
+   * Called from JavaScript layer when the remote party answers an outgoing call.
+   */
   fun callAnsweredFromJS(callId: String) {
     Log.d(TAG, "callAnsweredFromJS: $callId - remote party answered")
     coreCallAnswered(callId, isLocalAnswer = false)
   }
 
+  /**
+   * Called when the local user answers an incoming call.
+   */
   fun answerCall(callId: String) {
     Log.d(TAG, "answerCall: $callId - local party answering")
     coreCallAnswered(callId, isLocalAnswer = true)
   }
 
+  /**
+   * Core logic for transitioning a call to the ACTIVE state, whether it's an incoming call
+   * being answered locally, or an outgoing call being acknowledged as answered by the remote side.
+   */
   private fun coreCallAnswered(callId: String, isLocalAnswer: Boolean) {
     Log.d(TAG, "coreCallAnswered: $callId, isLocalAnswer: $isLocalAnswer")
     val callInfo = activeCalls[callId]
@@ -467,14 +552,15 @@ object CallEngine {
 
     activeCalls[callId] = callInfo.copy(state = CallState.ACTIVE)
     currentCallId = callId
-    callStartTime = System.currentTimeMillis()
-    wasManuallySetAudioRoute = false
+    callStartTime = System.currentTimeMillis() // Record call start time
+    wasManuallySetAudioRoute = false // Reset manual audio route flag
     Log.d(TAG, "Call $callId set to ACTIVE state")
 
     stopRingtone()
     stopRingback()
-    cancelIncomingCallUI()
+    cancelIncomingCallUI() // Clear any incoming call UI/notification
 
+    // If multiple calls are not allowed, hold any other active calls.
     if (!canMakeMultipleCalls) {
       activeCalls.filter { it.key != callId }.values.forEach { otherCall ->
         if (otherCall.state == CallState.ACTIVE) {
@@ -488,62 +574,28 @@ object CallEngine {
     keepScreenAwake(true)
     updateLockScreenBypass()
 
-    setAudioMode() // Ensure audio mode is correct
+    setAudioMode() // Set audio mode to MODE_IN_COMMUNICATION for an active call.
 
-    // Set initial audio route using Telecom's CallEndpoint API
+    // Set initial audio route using Telecom's CallEndpoint API, with a slight delay.
     setInitialCallAudioRoute(callId, callInfo.callType)
 
+    // Emit the appropriate event back to JS.
     if (isLocalAnswer) {
-      emitCallAnsweredWithMetadata(callId)
+      emitCallEventWithMetadata(CallEventType.CALL_ANSWERED, callId)
     } else {
-      emitOutgoingCallAnsweredWithMetadata(callId)
+      emitCallEventWithMetadata(CallEventType.OUTGOING_CALL_ANSWERED, callId)
     }
 
     Log.d(TAG, "Call $callId successfully answered")
   }
 
-  private fun emitCallAnsweredWithMetadata(callId: String) {
-    val callInfo = activeCalls[callId] ?: return
-    val metadata = callMetadata[callId]
-
-    emitEvent(CallEventType.CALL_ANSWERED, JSONObject().apply {
-      put("callId", callId)
-      put("callType", callInfo.callType)
-      put("displayName", callInfo.displayName)
-      callInfo.pictureUrl?.let { put("pictureUrl", it) }
-      metadata?.let {
-        try {
-          put("metadata", JSONObject(it))
-        } catch (e: Exception) {
-          put("metadata", it)
-        }
-      }
-    })
-  }
-
-  private fun emitOutgoingCallAnsweredWithMetadata(callId: String) {
-    val callInfo = activeCalls[callId] ?: return
-    val metadata = callMetadata[callId]
-
-    emitEvent(CallEventType.OUTGOING_CALL_ANSWERED, JSONObject().apply {
-      put("callId", callId)
-      put("callType", callInfo.callType)
-      put("displayName", callInfo.displayName)
-      callInfo.pictureUrl?.let { put("pictureUrl", it) }
-      metadata?.let {
-        try {
-          put("metadata", JSONObject(it))
-        } catch (e: Exception) {
-          put("metadata", it)
-        }
-      }
-    })
-  }
-
   fun holdCall(callId: String) {
     holdCallInternal(callId, heldBySystem = false)
   }
 
+  /**
+   * Sets a call to held or unheld state.
+   */
   fun setOnHold(callId: String, onHold: Boolean) {
     Log.d(TAG, "setOnHold: $callId, onHold: $onHold")
     val callInfo = activeCalls[callId]
@@ -559,6 +611,9 @@ object CallEngine {
     }
   }
 
+  /**
+   * Internal logic for putting a call on hold.
+   */
   private fun holdCallInternal(callId: String, heldBySystem: Boolean) {
     Log.d(TAG, "holdCallInternal: $callId, heldBySystem: $heldBySystem")
     val callInfo = activeCalls[callId]
@@ -572,7 +627,7 @@ object CallEngine {
       wasHeldBySystem = heldBySystem
     )
 
-    telecomConnections[callId]?.setOnHold()
+    telecomConnections[callId]?.setOnHold() // Notify Telecom
     updateForegroundNotification()
     emitEvent(CallEventType.CALL_HELD, JSONObject().put("callId", callId))
     updateLockScreenBypass()
@@ -582,6 +637,9 @@ object CallEngine {
     unholdCallInternal(callId, resumedBySystem = false)
   }
 
+  /**
+   * Internal logic for unholding a call.
+   */
   private fun unholdCallInternal(callId: String, resumedBySystem: Boolean) {
     Log.d(TAG, "unholdCallInternal: $callId, resumedBySystem: $resumedBySystem")
     val callInfo = activeCalls[callId]
@@ -595,7 +653,7 @@ object CallEngine {
       wasHeldBySystem = false
     )
 
-    telecomConnections[callId]?.setActive()
+    telecomConnections[callId]?.setActive() // Notify Telecom
     updateForegroundNotification()
     emitEvent(CallEventType.CALL_UNHELD, JSONObject().put("callId", callId))
     updateLockScreenBypass()
@@ -609,12 +667,17 @@ object CallEngine {
     setMutedInternal(callId, false)
   }
 
+  /**
+   * Sets the mute state for a call. This method is typically called by [MyConnection.onMuteStateChanged]
+   * when Telecom itself reports a mute state change. It then updates AudioManager and emits an event.
+   */
   fun setMuted(callId: String, muted: Boolean) {
     setMutedInternal(callId, muted)
   }
 
-  // This method is now called by MyConnection.onMuteStateChanged which receives state from Telecom.
-  // It applies the mute state to AudioManager and emits the event.
+  /**
+   * Internal logic to apply mute state to AudioManager and emit relevant events.
+   */
   private fun setMutedInternal(callId: String, muted: Boolean) {
     val callInfo = activeCalls[callId]
     if (callInfo == null) {
@@ -642,23 +705,31 @@ object CallEngine {
     endCallInternal(callId)
   }
 
+  /**
+   * Ends all currently active calls managed by the engine.
+   */
   fun endAllCalls() {
     Log.d(TAG, "endAllCalls: Ending all active calls")
     if (activeCalls.isEmpty()) return
 
+    // Create a copy of keys to avoid ConcurrentModificationException
     activeCalls.keys.toList().forEach { callId ->
       endCallInternal(callId)
     }
 
+    // Clear all tracking maps for a clean state
     activeCalls.clear()
     telecomConnections.clear()
     callMetadata.clear()
     currentCallId = null
 
-    cleanup()
+    cleanup() // Perform final cleanup after all calls ended
     updateLockScreenBypass()
   }
 
+  /**
+   * Internal logic for ending a specific call.
+   */
   private fun endCallInternal(callId: String) {
     Log.d(TAG, "endCallInternal: $callId")
 
@@ -672,11 +743,11 @@ object CallEngine {
 
     stopRingback()
     stopRingtone()
-    cancelIncomingCallUI()
+    cancelIncomingCallUI() // Clear notification/UI if this was the incoming call
 
+    // Update currentCallId if the ended call was the current one
     if (currentCallId == callId) {
-      currentCallId =
-        activeCalls.filter { it.value.state != CallState.ENDED }.keys.firstOrNull()
+      currentCallId = activeCalls.filter { it.value.state != CallState.ENDED }.keys.firstOrNull()
     }
 
     val context = requireContext()
@@ -691,13 +762,14 @@ object CallEngine {
       Log.w(TAG, "Failed to send close broadcast: ${e.message}")
     }
 
+    // Notify Telecom that the connection is disconnected and destroy it.
     telecomConnections[callId]?.let { connection ->
-      // Disconnect and destroy the Telecom Connection
       connection.setDisconnected(DisconnectCause(DisconnectCause.LOCAL))
       connection.destroy()
       removeTelecomConnection(callId)
     }
 
+    // Perform cleanup if no active calls remain, otherwise update foreground notification.
     if (activeCalls.isEmpty()) {
       cleanup()
     } else {
@@ -706,6 +778,7 @@ object CallEngine {
 
     updateLockScreenBypass()
 
+    // Notify registered listeners that the call has ended.
     for (listener in callEndListeners) {
       mainHandler.post {
         try {
@@ -716,36 +789,39 @@ object CallEngine {
       }
     }
 
-    emitEvent(CallEventType.CALL_ENDED, JSONObject().apply {
-      put("callId", callId)
-      metadata?.let {
-        try { put("metadata", JSONObject(it)) }
-        catch (e: Exception) { put("metadata", it) }
-      }
-    })
+    emitCallEventWithMetadata(CallEventType.CALL_ENDED, callId)
   }
 
-  // ====== IMPROVED AUDIO ROUTING SYSTEM (using CallEndpoint API) ======
+  // ====== AUDIO ROUTING SYSTEM using Telecom CallEndpoint API (API 34+) ======
 
-  // Stores the currently available CallEndpoints as reported by Telecom
+  /**
+   * Called by [MyConnection] when Telecom reports a change in available audio endpoints.
+   * Updates internal state and notifies JS.
+   */
   fun onTelecomAvailableEndpointsChanged(endpoints: List<CallEndpoint>) {
       availableCallEndpoints = endpoints
       Log.d(TAG, "Available CallEndpoints updated: ${endpoints.map { "${it.endpointName}(${mapCallEndpointTypeToString(it.endpointType)})" }}")
-      emitAudioDevicesChanged()
+      emitAudioDevicesChanged() // Emit event to JS with updated list
   }
 
-  // Stores the active CallEndpoint as reported by Telecom
+  /**
+   * Called by [MyConnection] when Telecom reports a change in the active audio endpoint.
+   * Updates internal state and notifies JS.
+   */
   fun onTelecomAudioRouteChanged(callId: String, callEndpoint: CallEndpoint) {
       Log.d(TAG, "Telecom audio route changed for $callId: endpoint=${callEndpoint.endpointName} (type=${mapCallEndpointTypeToString(callEndpoint.endpointType)})")
       currentActiveCallEndpoint = callEndpoint
       emitAudioRouteChanged(mapCallEndpointTypeToString(callEndpoint.endpointType))
   }
 
+  /**
+   * Returns information about available audio devices and the current route.
+   */
   fun getAudioDevices(): AudioRoutesInfo {
+    // Collect unique device strings from available endpoints
     val devices = availableCallEndpoints.map { StringHolder(mapCallEndpointTypeToString(it.endpointType)) }.toMutableSet()
 
-    // Add common fallback endpoints if Telecom doesn't explicitly list them,
-    // although for active calls, Telecom should provide comprehensive lists.
+    // Add common fallback endpoints if Telecom doesn't explicitly list them in availableCallEndpoints.
     // This provides robustness for the JavaScript side's expected string values.
     if (!devices.any { it.value == "Earpiece" }) devices.add(StringHolder("Earpiece"))
     if (!devices.any { it.value == "Speaker" }) devices.add(StringHolder("Speaker"))
@@ -756,22 +832,27 @@ object CallEngine {
     return AudioRoutesInfo(devices.toTypedArray(), current)
   }
 
+  /**
+   * Requests Telecom to change the audio route to the specified type (e.g., "Speaker", "Earpiece").
+   * This marks the change as "manual" to prevent automatic overrides later.
+   */
   fun setAudioRoute(route: String) {
      Log.d(TAG, "setAudioRoute called: $route (manual)")
      wasManuallySetAudioRoute = true
 
      val telecomEndpointType = mapStringToCallEndpointType(route)
 
-     // Find the actual CallEndpoint object from the available list that matches the type
+     // Find the actual CallEndpoint object from the available list that matches the requested type.
+     // If not found (e.g., for generic Earpiece/Speaker), create a generic CallEndpoint.
      val targetEndpoint = availableCallEndpoints.find { it.endpointType == telecomEndpointType }
-         ?: getOrCreateGenericCallEndpoint(telecomEndpointType, route) // Fallback to create generic if not found in available list
+         ?: getOrCreateGenericCallEndpoint(telecomEndpointType, route)
 
      if (targetEndpoint != null) {
          currentCallId?.let { callId ->
              telecomConnections[callId]?.let { connection ->
                  if (connection is MyConnection) {
                      Log.d(TAG, "Requesting manual telecom audio route to: ${targetEndpoint.endpointName} (type: ${mapCallEndpointTypeToString(targetEndpoint.endpointType)})")
-                     connection.setTelecomAudioRoute(targetEndpoint)
+                     connection.setTelecomAudioRoute(targetEndpoint) // Delegate to MyConnection to make the Telecom API call.
                  } else {
                     Log.w(TAG, "Telecom connection for $callId is not MyConnection instance.")
                  }
@@ -780,9 +861,12 @@ object CallEngine {
      } else {
          Log.w(TAG, "Could not find or create a valid CallEndpoint for manual route: $route (type: $telecomEndpointType)")
      }
- }
+  }
 
-  // This method is called by MyConnection when its state becomes ACTIVE, or after startCall/startOutgoingCall.
+  /**
+   * Sets the initial audio route for a call based on its type (video/audio) and connected devices.
+   * This is only performed if a manual route hasn't already been set.
+   */
   fun setInitialCallAudioRoute(callId: String, callType: String) {
       Log.d(TAG, "Setting initial audio route for callId: $callId, type: $callType")
 
@@ -795,16 +879,16 @@ object CallEngine {
           isBluetoothDeviceConnected() -> CallEndpoint.TYPE_BLUETOOTH
           isWiredHeadsetConnected() -> CallEndpoint.TYPE_WIRED_HEADSET
           callType.equals("Video", ignoreCase = true) -> CallEndpoint.TYPE_SPEAKER
-          else -> CallEndpoint.TYPE_EARPIECE
+          else -> CallEndpoint.TYPE_EARPIECE // Default for audio calls
       }
 
-      // We should ideally pick from `availableCallEndpoints`.
-      // If none of that type are explicitly listed (e.g. for default Earpiece/Speaker),
-      // we can try to create a generic one.
+      // Try to find the exact CallEndpoint from the available list.
+      // Fallback to creating a generic one if not explicitly listed (e.g., system Earpiece/Speaker).
       val targetEndpoint = availableCallEndpoints.find { it.endpointType == targetEndpointType }
           ?: getOrCreateGenericCallEndpoint(targetEndpointType, mapCallEndpointTypeToString(targetEndpointType))
 
       if (targetEndpoint != null) {
+          // Add a slight delay to allow Telecom to fully process connection activation before routing.
           mainHandler.postDelayed({
               telecomConnections[callId]?.let { connection ->
                   if (connection is MyConnection) {
@@ -812,33 +896,44 @@ object CallEngine {
                       connection.setTelecomAudioRoute(targetEndpoint)
                   }
               } ?: Log.w(TAG, "No telecom connection found for $callId during initial route setting.")
-          }, 500L) // Small delay to allow Telecom to process connection activation
+          }, 500L)
       } else {
           Log.w(TAG, "Could not find or create a valid CallEndpoint for initial route type: $targetEndpointType")
       }
   }
 
+  /**
+   * Sets the AudioManager's mode to MODE_IN_COMMUNICATION, which is optimal for voice calls.
+   * This is called when a call becomes active.
+   */
   private fun setAudioMode() {
     audioManager?.mode = AudioManager.MODE_IN_COMMUNICATION
     Log.d(TAG, "Audio mode set to MODE_IN_COMMUNICATION")
   }
 
+  /**
+   * Resets AudioManager to normal mode when all calls have ended.
+   */
   private fun resetAudioMode() {
     if (activeCalls.isEmpty()) {
       audioManager?.let { am ->
         am.mode = AudioManager.MODE_NORMAL
+        // Explicitly stop Bluetooth SCO if active, for API 28+ devices (handled by CallEndpoint for 34+).
         if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && am.isBluetoothScoOn) {
           am.stopBluetoothSco()
         }
-        am.isSpeakerphoneOn = false
+        am.isSpeakerphoneOn = false // Ensure speakerphone is off
       }
-      currentActiveCallEndpoint = null // Reset active endpoint
+      currentActiveCallEndpoint = null // Reset active endpoint tracking
       availableCallEndpoints = emptyList() // Clear available endpoints
-      wasManuallySetAudioRoute = false
+      wasManuallySetAudioRoute = false // Reset manual flag
       Log.d(TAG, "Audio mode reset to MODE_NORMAL, audio endpoints reset.")
     }
   }
 
+  /**
+   * Maps a [CallEndpoint.TYPE_*] integer to a human-readable string.
+   */
   private fun mapCallEndpointTypeToString(type: Int): String {
       return when (type) {
           CallEndpoint.TYPE_EARPIECE -> "Earpiece"
@@ -850,6 +945,9 @@ object CallEngine {
       }
   }
 
+  /**
+   * Maps a human-readable audio route string to a [CallEndpoint.TYPE_*] integer.
+   */
   private fun mapStringToCallEndpointType(typeString: String): Int {
       return when (typeString) {
           "Earpiece" -> CallEndpoint.TYPE_EARPIECE
@@ -861,9 +959,14 @@ object CallEngine {
       }
   }
 
+  /**
+   * Creates a generic [CallEndpoint] object for common audio routes if it's not found
+   * in the list reported by Telecom. This is a fallback for basic endpoints like Earpiece/Speaker
+   * that might implicitly exist but not always be explicitly listed as "available" by Telecom
+   * (especially on older API versions within the 28-33 range that don't have CallEndpoint).
+   * Note: The `ParcelUuid` must wrap a `java.util.UUID`.
+   */
   private fun getOrCreateGenericCallEndpoint(type: Int, name: String): CallEndpoint? {
-      // This is a fallback to create a CallEndpoint if it's not explicitly in availableCallEndpoints.
-      // Useful for basic types like Earpiece/Speaker that might implicitly exist.
       return when (type) {
           CallEndpoint.TYPE_EARPIECE -> CallEndpoint(name, type, ParcelUuid(UUID.nameUUIDFromBytes("Earpiece_Default".toByteArray())))
           CallEndpoint.TYPE_SPEAKER -> CallEndpoint(name, type, ParcelUuid(UUID.nameUUIDFromBytes("Speaker_Default".toByteArray())))
@@ -873,39 +976,41 @@ object CallEngine {
       }
   }
 
-
+  /**
+   * Checks if a wired headset (including USB headsets) is currently connected.
+   * This uses modern API methods suitable for SDK 28+.
+   */
   private fun isWiredHeadsetConnected(): Boolean {
     val am = audioManager ?: return false
-    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-      val devices = am.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
-      devices.any { device ->
-        device.type == android.media.AudioDeviceInfo.TYPE_WIRED_HEADSET ||
-        device.type == android.media.AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
-        device.type == android.media.AudioDeviceInfo.TYPE_USB_HEADSET
-      }
-    } else {
-        @Suppress("DEPRECATION")
-        am.isWiredHeadsetOn
+    // getDevices(AudioManager.GET_DEVICES_OUTPUTS) is available from API 23 (M)
+    val devices = am.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+    return devices.any { device ->
+      device.type == android.media.AudioDeviceInfo.TYPE_WIRED_HEADSET ||
+      device.type == android.media.AudioDeviceInfo.TYPE_WIRED_HEADPHONES ||
+      device.type == android.media.AudioDeviceInfo.TYPE_USB_HEADSET
     }
   }
 
+  /**
+   * Checks if a Bluetooth audio device (A2DP, SCO, BLE) is currently connected.
+   * This uses modern API methods suitable for SDK 28+.
+   */
   private fun isBluetoothDeviceConnected(): Boolean {
     val am = audioManager ?: return false
-    return if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.M) {
-      val devices = am.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
-      devices.any { device ->
-        device.type == android.media.AudioDeviceInfo.TYPE_BLUETOOTH_A2DP ||
-        device.type == android.media.AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
-        device.type == android.media.AudioDeviceInfo.TYPE_BLE_HEADSET
-      }
-    } else {
-        @Suppress("DEPRECATION")
-        am.isBluetoothA2dpOn || am.isBluetoothScoOn
+    // getDevices(AudioManager.GET_DEVICES_OUTPUTS) is available from API 23 (M)
+    val devices = am.getDevices(AudioManager.GET_DEVICES_OUTPUTS)
+    return devices.any { device ->
+      device.type == android.media.AudioDeviceInfo.TYPE_BLUETOOTH_A2DP ||
+      device.type == android.media.AudioDeviceInfo.TYPE_BLUETOOTH_SCO ||
+      device.type == android.media.AudioDeviceInfo.TYPE_BLE_HEADSET
     }
   }
 
+  /**
+   * Emits an AUDIO_ROUTE_CHANGED event to the JavaScript layer.
+   */
   private fun emitAudioRouteChanged(currentRoute: String) {
-      val info = getAudioDevices() // This now uses CallEngine's internal state
+      val info = getAudioDevices() // Recalculate based on current internal state
       val deviceStrings = info.devices.map { it.value }
       val payload = JSONObject().apply {
           put("devices", JSONArray(deviceStrings))
@@ -915,6 +1020,10 @@ object CallEngine {
       Log.d(TAG, "Audio route changed: $currentRoute, available: $deviceStrings")
   }
 
+  /**
+   * Emits an AUDIO_DEVICES_CHANGED event to the JavaScript layer, indicating a change
+   * in the list of available audio devices.
+   */
   private fun emitAudioDevicesChanged() {
     val info = getAudioDevices()
     val deviceStrings = info.devices.map { it.value }
@@ -926,24 +1035,23 @@ object CallEngine {
     Log.d(TAG, "Audio devices changed: available: $deviceStrings")
   }
 
-  // Audio device callbacks are now handled by Telecom and MyConnection.
-  // The CallEngine does not directly register an AudioDeviceCallback.
-  // This part of the code is removed.
-
-  // ====== END IMPROVED AUDIO ROUTING SYSTEM ======
+  // ====== END AUDIO ROUTING SYSTEM ======
 
+  /**
+   * Manages a PARTIAL_WAKE_LOCK to keep the screen awake during calls.
+   */
   fun keepScreenAwake(keepAwake: Boolean) {
     val context = requireContext()
     val powerManager = context.getSystemService(Context.POWER_SERVICE) as PowerManager
     if (keepAwake) {
       if (wakeLock == null || wakeLock!!.isHeld.not()) {
-        // Use PARTIAL_WAKE_LOCK to keep CPU awake, SCREEN_DIM_WAKE_LOCK to keep screen on (dim)
-        // For general "keep screen awake", SCREEN_DIM_WAKE_LOCK is appropriate.
+        // Use SCREEN_DIM_WAKE_LOCK or PARTIAL_WAKE_LOCK.
+        // SCREEN_DIM_WAKE_LOCK keeps the screen on but dimmed. ACQUIRE_CAUSES_WAKEUP wakes screen if off.
         wakeLock = powerManager.newWakeLock(
           PowerManager.SCREEN_DIM_WAKE_LOCK or PowerManager.ACQUIRE_CAUSES_WAKEUP,
           "CallEngine:WakeLock"
         )
-        // Set a timeout for the wakelock to prevent indefinite drain, e.g., 10 minutes
+        // Set a timeout to prevent indefinite battery drain, e.g., 10 minutes.
         wakeLock?.acquire(10 * 60 * 1000L)
         Log.d(TAG, "Acquired SCREEN_DIM_WAKE_LOCK")
       }
@@ -960,6 +1068,10 @@ object CallEngine {
 
   fun getActiveCalls(): List<CallInfo> = activeCalls.values.toList()
   fun getCurrentCallId(): String? = currentCallId
+
+  /**
+   * Checks if there's any call currently in an active, incoming, dialing, or held state.
+   */
   fun isCallActive(): Boolean = activeCalls.any {
     it.value.state == CallState.ACTIVE ||
     it.value.state == CallState.INCOMING ||
@@ -967,21 +1079,31 @@ object CallEngine {
     it.value.state == CallState.HELD
   }
 
+  /**
+   * Validates if an outgoing call request is permissible based on current call states and
+   * multi-call allowance.
+   */
   private fun validateOutgoingCallRequest(): Boolean {
-    // Only allow outgoing call if no incoming or active call exists and multi-call not allowed
+    // An outgoing call is permitted if:
+    // - There are no incoming calls.
+    // - OR (If multiple calls are allowed), there are no active calls blocking new outgoing calls.
     return !activeCalls.any {
-      (!canMakeMultipleCalls && (it.value.state == CallState.INCOMING || it.value.state == CallState.ACTIVE))
+      it.value.state == CallState.INCOMING ||
+      (!canMakeMultipleCalls && it.value.state == CallState.ACTIVE)
     }
   }
 
-
+  /**
+   * Handles incoming call collision by rejecting the new call and emitting an event.
+   */
   private fun rejectIncomingCallCollision(callId: String, reason: String) {
     emitEvent(CallEventType.CALL_REJECTED, JSONObject().apply {
       put("callId", callId)
       put("reason", reason)
     })
 
-    // Only remove metadata if there's NO existing active call with this ID
+    // Only remove metadata if there's NO existing active call with this ID,
+    // to avoid deleting metadata for a call that Telecom already knows about.
     val existingCall = activeCalls[callId]
     if (existingCall == null) {
       callMetadata.remove(callId)
@@ -991,26 +1113,28 @@ object CallEngine {
     }
   }
 
+  /**
+   * Creates or updates the notification channel for incoming calls.
+   * On Android O (API 26) and above, notification channels are required.
+   */
   private fun createNotificationChannel() {
     val context = requireContext()
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
       val channel = NotificationChannel(
         NOTIF_CHANNEL_ID,
         "Incoming Call Channel",
-        NotificationManager.IMPORTANCE_HIGH
+        NotificationManager.IMPORTANCE_HIGH // High importance for incoming calls
       )
       channel.description = "Notifications for incoming calls"
       channel.enableLights(true)
       channel.lightColor = Color.GREEN
       channel.enableVibration(true)
-      channel.setBypassDnd(true)
-      channel.lockscreenVisibility = Notification.VISIBILITY_PUBLIC
-
-      // For Android S (API 31) and above, Telecom manages ringing for self-managed calls
-      // if it's the default dialer or an InCallService with METADATA_IN_CALL_SERVICE_RINGING.
-      // Setting sound to null here allows Telecom to take over or for us to manage manually
-      // if not relying on Telecom for ringing.
-      // Since we play ringtone manually below, ensure channel sound is null to avoid double ringing.
+      channel.setBypassDnd(true) // Bypass Do Not Disturb mode
+      channel.lockscreenVisibility = Notification.VISIBILITY_PUBLIC // Show on lock screen
+
+      // For Android S (API 31) and above, Telecom can manage ringing for self-managed calls
+      // if configured as the default dialer. Setting sound to null here allows Telecom
+      // to take over or for our manual ringtone to be the sole source.
       channel.setSound(null, null)
       channel.importance = NotificationManager.IMPORTANCE_HIGH
 
@@ -1019,6 +1143,10 @@ object CallEngine {
     }
   }
 
+  /**
+   * Decides whether to show a fullscreen overlay or a standard notification for an incoming call,
+   * based on device lock state and CallStyle notification support.
+   */
   private fun showIncomingCallUI(callId: String, callerName: String, callType: String, callerPicUrl: String?) {
     val context = requireContext()
     Log.d(TAG, "Showing incoming call UI for $callId")
@@ -1026,13 +1154,8 @@ object CallEngine {
     val useCallStyleNotification = supportsCallStyleNotifications()
     Log.d(TAG, "Using CallStyle notification: $useCallStyleNotification")
 
-    // Determine if device is locked or if CallStyle is not preferred/supported for current scenario
-    val isDeviceLocked = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) {
-        val keyguardManager = context.getSystemService(Context.KEYGUARD_SERVICE) as KeyguardManager
-        keyguardManager.isKeyguardLocked
-    } else {
-        false // Older APIs, assume no direct lock screen check needed or handled differently
-    }
+    val keyguardManager = context.getSystemService(Context.KEYGUARD_SERVICE) as KeyguardManager
+    val isDeviceLocked = keyguardManager.isKeyguardLocked
 
     if (isDeviceLocked || !useCallStyleNotification) {
       Log.d(TAG, "Device is locked or CallStyle not supported/preferred - using overlay/fallback approach")
@@ -1041,11 +1164,15 @@ object CallEngine {
       Log.d(TAG, "Device is unlocked and supports CallStyle - using enhanced notification")
       showStandardNotification(context, callId, callerName, callType, callerPicUrl)
     }
-    playRingtone()
+    playRingtone() // Play our custom ringtone regardless of notification type
   }
 
+  /**
+   * Displays a fullscreen activity overlay for incoming calls, typically on a locked screen.
+   */
   private fun showCallActivityOverlay(context: Context, callId: String, callerName: String, callType: String, callerPicUrl: String?) {
     val overlayIntent = Intent(context, CallActivity::class.java).apply {
+      // Flags to ensure the activity appears on top of the lock screen and in a new task.
       addFlags(
         Intent.FLAG_ACTIVITY_NEW_TASK or
         Intent.FLAG_ACTIVITY_CLEAR_TASK or
@@ -1056,16 +1183,17 @@ object CallEngine {
       putExtra("callerName", callerName)
       putExtra("callType", callType)
       callerPicUrl?.let { putExtra("callerAvatar", it) }
-      putExtra("LOCK_SCREEN_MODE", true)
+      putExtra("LOCK_SCREEN_MODE", true) // Hint for the activity itself
     }
 
     try {
+      // Acquire a wake lock briefly to ensure the screen turns on for the overlay.
       val powerManager = context.getSystemService(Context.POWER_SERVICE) as PowerManager
       val wakeLock = powerManager.newWakeLock(
         PowerManager.SCREEN_BRIGHT_WAKE_LOCK or PowerManager.ACQUIRE_CAUSES_WAKEUP,
         "CallEngine:LockScreenWake"
       )
-      wakeLock.acquire(5000) // Acquire for a short duration
+      wakeLock.acquire(5000) // Acquire for 5 seconds to ensure visibility
       context.startActivity(overlayIntent)
       Log.d(TAG, "Successfully launched CallActivity overlay")
     } catch (e: Exception) {
@@ -1074,10 +1202,14 @@ object CallEngine {
     }
   }
 
+  /**
+   * Displays a standard incoming call notification using Notification.Builder and potentially Notification.CallStyle.
+   */
   private fun showStandardNotification(context: Context, callId: String, callerName: String, callType: String, callerPicUrl: String?) {
-    createNotificationChannel()
+    createNotificationChannel() // Ensure channel exists
     val notificationManager = context.getSystemService(Context.NOTIFICATION_SERVICE) as NotificationManager
 
+    // Intent for tapping the notification body (goes to main call activity)
     val fullScreenIntent = Intent(context, CallActivity::class.java).apply {
       addFlags(Intent.FLAG_ACTIVITY_NEW_TASK or Intent.FLAG_ACTIVITY_SINGLE_TOP)
       putExtra("callId", callId)
@@ -1091,6 +1223,7 @@ object CallEngine {
       PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
     )
 
+    // Intent for 'Answer' action button on notification
     val answerIntent = Intent(context, CallNotificationActionReceiver::class.java).apply {
       action = "com.qusaieilouti99.callmanager.ANSWER_CALL"
       putExtra("callId", callId)
@@ -1100,6 +1233,7 @@ object CallEngine {
       PendingIntent.FLAG_UPDATE_CURRENT or PendingIntent.FLAG_IMMUTABLE
     )
 
+    // Intent for 'Decline' action button on notification
     val declineIntent = Intent(context, CallNotificationActionReceiver::class.java).apply {
       action = "com.qusaieilouti99.callmanager.DECLINE_CALL"
       putExtra("callId", callId)
@@ -1110,6 +1244,7 @@ object CallEngine {
     )
 
     val notification = if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.S && supportsCallStyleNotifications()) {
+      // Use Notification.CallStyle for modern Android versions (API 31+) for enhanced call UI.
       val person = android.app.Person.Builder()
         .setName(callerName)
         .setImportant(true)
@@ -1124,14 +1259,15 @@ object CallEngine {
           )
         )
         .setFullScreenIntent(fullScreenPendingIntent, true)
-        .setOngoing(true)
+        .setOngoing(true) // Makes the notification non-dismissable
         .setAutoCancel(false)
         .setCategory(Notification.CATEGORY_CALL)
-        .setPriority(Notification.PRIORITY_MAX)
-        .setVisibility(Notification.VISIBILITY_PUBLIC)
-        .setSound(null) // No sound for CallStyle, we manage it separately
+        .setPriority(Notification.PRIORITY_MAX) // High priority for heads-up notification
+        .setVisibility(Notification.VISIBILITY_PUBLIC) // Show on lock screen
+        .setSound(null) // Sound handled by playRingtone()
         .build()
     } else {
+      // Fallback for older Android versions (API 28-30) that don't support CallStyle directly.
       Notification.Builder(context, NOTIF_CHANNEL_ID)
         .setSmallIcon(android.R.drawable.sym_call_incoming)
         .setContentTitle("Incoming Call")
@@ -1144,13 +1280,16 @@ object CallEngine {
         .setOngoing(true)
         .setAutoCancel(false)
         .setVisibility(Notification.VISIBILITY_PUBLIC)
-        .setSound(RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE)) // Fallback for older styles
+        .setSound(RingtoneManager.getDefaultUri(RingtoneManager.TYPE_RINGTONE)) // For older styles, rely on channel/notification sound
         .build()
     }
 
     notificationManager.notify(NOTIF_ID, notification)
   }
 
+  /**
+   * Cancels the incoming call notification and stops the ringtone.
+   */
   fun cancelIncomingCallUI() {
     val context = requireContext()
     val notificationManager =
@@ -1159,8 +1298,13 @@ object CallEngine {
     stopRingtone()
   }
 
+  /**
+   * Starts the foreground service responsible for displaying persistent notification
+   * and maintaining app process priority during an active call.
+   */
   private fun startForegroundService() {
     val context = requireContext()
+    // Find the current main active call to pass its info to the service.
     val currentCall = activeCalls.values.find {
       it.state == CallState.ACTIVE ||
       it.state == CallState.INCOMING ||
@@ -1176,55 +1320,59 @@ object CallEngine {
       intent.putExtra("state", it.state.name)
     }
 
+    // Use startForegroundService for Android O (API 26) and above.
     if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
       context.startForegroundService(intent)
     } else {
+      // Fallback for older Android versions (should not be reached if minSdk is 28+).
       context.startService(intent)
     }
   }
 
+  /**
+   * Stops the foreground service.
+   */
   private fun stopForegroundService() {
     val context = requireContext()
     val intent = Intent(context, CallForegroundService::class.java)
     context.stopService(intent)
   }
 
+  /**
+   * Updates the foreground notification, typically by restarting the foreground service
+   * with updated call information.
+   */
   private fun updateForegroundNotification() {
     startForegroundService()
   }
 
+  /**
+   * Checks if the main activity of the application is currently in the foreground.
+   * Uses modern API methods suitable for SDK 28+.
+   */
   private fun isMainActivityInForeground(): Boolean {
     val context = requireContext()
-    val activityManager =
-      context.getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager
+    val activityManager = context.getSystemService(Context.ACTIVITY_SERVICE) as ActivityManager
 
-    // For API 23+, getRunningTasks is deprecated. Use UsageStatsManager or check AppTasks
-    if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.LOLLIPOP_MR1) { // LMR1 is API 22, getAppTasks available from API 21, but getRunningTasks deprecated from API 23.
-      try {
-        val tasks = activityManager.appTasks
-        if (tasks.isNotEmpty()) {
-          // get(0) is the top-most task
-          val topActivityComponentName = tasks[0].taskInfo.topActivity
-          return topActivityComponentName?.className?.contains("MainActivity") == true
-        }
-      } catch (e: Exception) {
-        Log.w(TAG, "Failed to get app tasks for foreground check: ${e.message}")
-      }
-    } else {
-      @Suppress("DEPRECATION")
-      try {
-        val tasks = activityManager.getRunningTasks(1)
-        if (tasks.isNotEmpty()) {
-          val runningTaskInfo = tasks[0]
-          return runningTaskInfo.topActivity?.className?.contains("MainActivity") == true
-        }
-      } catch (e: Exception) {
-        Log.w(TAG, "Failed to get running tasks for foreground check (deprecated): ${e.message}")
+    // getAppTasks() is available from API 21 (Lollipop), but is the recommended approach over
+    // deprecated getRunningTasks() from API 23 (Marshmallow).
+    try {
+      val tasks = activityManager.appTasks
+      if (tasks.isNotEmpty()) {
+        // The first task is usually the top-most one.
+        val topActivityComponentName = tasks[0].taskInfo.topActivity
+        return topActivityComponentName?.className?.contains("MainActivity") == true
       }
+    } catch (e: Exception) {
+      Log.w(TAG, "Failed to get app tasks for foreground check: ${e.message}")
     }
     return false
   }
 
+  /**
+   * Brings the application's main activity to the foreground.
+   * Includes logic to bypass the lock screen if there's an active call.
+   */
   private fun bringAppToForeground() {
     if (isMainActivityInForeground()) {
       Log.d(TAG, "MainActivity is already in foreground, skipping")
@@ -1241,12 +1389,14 @@ object CallEngine {
       Intent.FLAG_ACTIVITY_SINGLE_TOP
     )
 
+    // Add flag to bypass lock screen if there is an active call.
     if (isCallActive()) {
       launchIntent?.putExtra("BYPASS_LOCK_SCREEN", true)
     }
 
     try {
       context.startActivity(launchIntent)
+      // Small delay to ensure the UI has time to update its lock screen bypass state.
       Handler(Looper.getMainLooper()).postDelayed({
         updateLockScreenBypass()
       }, 100)
@@ -1255,15 +1405,19 @@ object CallEngine {
     }
   }
 
+  /**
+   * Registers a self-managed [PhoneAccount] with the Telecom framework.
+   * This is required for your app to interact with Telecom for calls.
+   */
   private fun registerPhoneAccount() {
     val context = requireContext()
-    val telecomManager =
-      context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
+    val telecomManager = context.getSystemService(Context.TELECOM_SERVICE) as TelecomManager
     val phoneAccountHandle = getPhoneAccountHandle()
 
+    // Only register if the PhoneAccount isn't already registered.
     if (telecomManager.getPhoneAccount(phoneAccountHandle) == null) {
       val phoneAccount = PhoneAccount.builder(phoneAccountHandle, "PingMe Call")
-        .setCapabilities(PhoneAccount.CAPABILITY_SELF_MANAGED)
+        .setCapabilities(PhoneAccount.CAPABILITY_SELF_MANAGED) // Declare as self-managed
         .build()
 
       try {
@@ -1275,6 +1429,9 @@ object CallEngine {
     }
   }
 
+  /**
+   * Gets the [PhoneAccountHandle] for this application's self-managed calling capabilities.
+   */
   private fun getPhoneAccountHandle(): PhoneAccountHandle {
     val context = requireContext()
     return PhoneAccountHandle(
@@ -1283,17 +1440,22 @@ object CallEngine {
     )
   }
 
+  /**
+   * Plays the default incoming call ringtone and vibrates the device.
+   */
   private fun playRingtone() {
     val context = requireContext()
     audioManager = audioManager ?: context.getSystemService(Context.AUDIO_SERVICE) as AudioManager
-    audioManager?.mode = AudioManager.MODE_RINGTONE
+    audioManager?.mode = AudioManager.MODE_RINGTONE // Set audio mode for ringing
 
     vibrator = context.getSystemService(Context.VIBRATOR_SERVICE) as? Vibrator
     vibrator?.let { v ->
-      val pattern = longArrayOf(0L, 500L, 500L)
-      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
+      val pattern = longArrayOf(0L, 500L, 500L) // Vibrate for 0.5s, pause 0.5s, loop
+      if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) { // VibrationEffect requires API 26+
         v.vibrate(VibrationEffect.createWaveform(pattern, 0))
       } else {
+        // This branch is technically for API < 26, which is below targetSdk 28+.
+        // It's retained here just for completeness of original logic.
         @Suppress("DEPRECATION")
         v.vibrate(pattern, 0)
       }
@@ -1309,29 +1471,35 @@ object CallEngine {
     }
   }
 
+  /**
+   * Stops the currently playing ringtone and cancels vibration.
+   */
   fun stopRingtone() {
     try {
       ringtone?.stop()
       Log.d(TAG, "Ringtone stopped")
     } catch (e: Exception) {
       Log.e(TAG, "Error stopping ringtone", e)
+    } finally {
+      ringtone = null
     }
-    ringtone = null
 
     vibrator?.cancel()
     vibrator = null
   }
 
+  /**
+   * Starts playing a local ringback tone.
+   */
   private fun startRingback() {
     val context = requireContext()
-    if (ringbackPlayer?.isPlaying == true) return
+    if (ringbackPlayer?.isPlaying == true) return // Don't start if already playing
 
     try {
-      val ringbackUri =
-        Uri.parse("android.resource://${context.packageName}/raw/ringback_tone")
+      val ringbackUri = Uri.parse("android.resource://${context.packageName}/raw/ringback_tone")
       ringbackPlayer = MediaPlayer.create(context, ringbackUri)
       ringbackPlayer?.apply {
-        isLooping = true
+        isLooping = true // Loop the tone
         start()
       }
       Log.d(TAG, "Ringback tone started playing")
@@ -1340,10 +1508,13 @@ object CallEngine {
     }
   }
 
+  /**
+   * Stops the currently playing ringback tone.
+   */
   private fun stopRingback() {
     try {
       ringbackPlayer?.stop()
-      ringbackPlayer?.release()
+      ringbackPlayer?.release() // Release MediaPlayer resources
     } catch (e: Exception) {
       Log.e(TAG, "Error stopping ringback: ${e.message}")
     } finally {
@@ -1351,32 +1522,42 @@ object CallEngine {
     }
   }
 
+  /**
+   * Performs general cleanup actions when all calls have ended.
+   */
   private fun cleanup() {
     Log.d(TAG, "Performing cleanup")
     stopForegroundService()
-    keepScreenAwake(false)
-    resetAudioMode()
+    keepScreenAwake(false) // Release wake lock
+    resetAudioMode() // Reset audio system
   }
 
+  /**
+   * Called when the application is about to terminate. Ensures all active calls are properly
+   * disconnected and resources are released.
+   */
   fun onApplicationTerminate() {
     Log.d(TAG, "Application terminating")
+    // Disconnect and destroy any remaining Telecom connections.
     activeCalls.keys.toList().forEach { callId ->
       telecomConnections[callId]?.let { conn ->
         conn.setDisconnected(DisconnectCause(DisconnectCause.LOCAL))
         conn.destroy()
       }
     }
+    // Clear all internal state tracking.
     activeCalls.clear()
     telecomConnections.clear()
     callMetadata.clear()
     currentCallId = null
-    cleanup()
+
+    cleanup() // Perform cleanup steps
     lockScreenBypassCallbacks.clear()
-    eventHandler = null
-    cachedEvents.clear()
-    isInitialized.set(false)
-    appContext = null
-    // Reset audio states
+    eventHandler = null // Clear event handler
+    cachedEvents.clear() // Clear cached events
+    isInitialized.set(false) // Mark as uninitialized
+    appContext = null // Release context reference
+    // Reset audio states explicitly
     currentActiveCallEndpoint = null
     availableCallEndpoints = emptyList()
     wasManuallySetAudioRoute = false