@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-ios-calls/references/callkit-and-pushkit.md

@@ -0,0 +1,353 @@
+# CallKit + PushKit on iOS — the canonical implementation
+
+iOS is the only platform where the OS owns the incoming-call UI. CallKit + PushKit isn't optional for production — without them, calls don't ring on locked devices and Apple rejects production builds. This reference is the full implementation; the SKILL.md sketches it, here is the code.
+
+---
+
+## Why two frameworks
+
+| Framework | Role |
+|---|---|
+| **PushKit** | Receives high-priority VoIP push payloads, even when the app is terminated. Separate from APNs. |
+| **CallKit** | Presents the system incoming-call UI (lock-screen, even on locked device), reports call state to the OS, integrates with Phone app's "Recents" list. |
+
+Combined: a VoIP push wakes the app via PushKit; the app immediately reports the call to CallKit; CallKit takes over and shows the system UI.
+
+---
+
+## Apple Developer setup (one-time, manual)
+
+The skill cannot automate these:
+
+1. **Create a VoIP Services certificate** in Apple Developer portal → Certificates → "+" → VoIP Services.
+2. **Pin to the bundle ID** of your app.
+3. **Download the .p12** and convert to .pem if your push server needs it (`openssl pkcs12 -in cert.p12 -out cert.pem -nodes`).
+4. **Upload to your push server.** This is a SEPARATE certificate from your standard APNs cert.
+
+The skill prints these steps and waits for the user to confirm before proceeding.
+
+---
+
+## Xcode setup
+
+In the target's "Signing & Capabilities":
+
+1. Click "+" → "Push Notifications" → adds the entitlement.
+2. Click "+" → "Background Modes" → check:
+   - ☑ Audio, AirPlay, and Picture in Picture
+   - ☑ Voice over IP
+   - ☑ Remote notifications
+
+Verify the resulting `Info.plist` has:
+
+```xml
+<key>UIBackgroundModes</key>
+<array>
+  <string>audio</string>
+  <string>voip</string>
+  <string>remote-notification</string>
+</array>
+<key>NSMicrophoneUsageDescription</key>
+<string>So you can talk during voice and video calls.</string>
+<key>NSCameraUsageDescription</key>
+<string>So you can be seen during video calls.</string>
+```
+
+---
+
+## App entry — register PushKit + CallKit
+
+### SwiftUI (`@main App`)
+
+```swift
+import SwiftUI
+import PushKit
+import CallKit
+import CometChatSDK
+import CometChatCallsSDK
+
+@main
+struct YourApp: App {
+  @StateObject private var callManager = CallManager.shared
+
+  var body: some Scene {
+    WindowGroup {
+      ContentView()
+        .onAppear {
+          CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { isInitialized, error in
+            guard error == nil else { return }
+            CometChatCalls.init(callAppSettings: callAppSettings) { _ in
+              callManager.registerForPushKit()                     // wait for SDK ready
+            }
+          }
+        }
+    }
+  }
+}
+```
+
+### UIKit (`AppDelegate`)
+
+```swift
+import UIKit
+import PushKit
+import CallKit
+
+@main
+class AppDelegate: UIResponder, UIApplicationDelegate {
+  func application(_ app: UIApplication, didFinishLaunchingWithOptions options: [UIApplication.LaunchOptionsKey: Any]?) -> Bool {
+    CometChat.init(appId: Secrets.cometchatAppID, appSettings: appSettings) { _, error in
+      guard error == nil else { return }
+      CometChatCalls.init(callAppSettings: callAppSettings) { _ in
+        CallManager.shared.registerForPushKit()
+      }
+    }
+    return true
+  }
+}
+```
+
+---
+
+## CallManager — the shared state holder
+
+```swift
+import PushKit
+import CallKit
+import CometChatCallsSDK
+
+class CallManager: NSObject, ObservableObject {
+  static let shared = CallManager()
+
+  private let pushRegistry = PKPushRegistry(queue: .main)
+  private let provider: CXProvider
+  private let callController = CXCallController()
+
+  private override init() {
+    let config = CXProviderConfiguration(localizedName: "YourApp")
+    config.supportsVideo = true
+    config.maximumCallGroups = 1
+    config.maximumCallsPerCallGroup = 1
+    config.supportedHandleTypes = [.generic]
+    config.iconTemplateImageData = UIImage(named: "CallKitIcon")?.pngData()
+    config.ringtoneSound = "ringtone.caf"
+
+    self.provider = CXProvider(configuration: config)
+    super.init()
+    provider.setDelegate(self, queue: .main)
+  }
+
+  func registerForPushKit() {
+    pushRegistry.delegate = self
+    pushRegistry.desiredPushTypes = [.voIP]
+  }
+
+  func reportIncomingCall(uuid: UUID, callerName: String, callerUid: String, hasVideo: Bool) {
+    let update = CXCallUpdate()
+    update.remoteHandle = CXHandle(type: .generic, value: callerUid)
+    update.localizedCallerName = callerName
+    update.hasVideo = hasVideo
+
+    provider.reportNewIncomingCall(with: uuid, update: update) { error in
+      if let error = error {
+        print("Failed to report incoming call: \(error)")
+      }
+    }
+  }
+}
+```
+
+---
+
+## PushKit delegate — the 5-second rule
+
+```swift
+extension CallManager: PKPushRegistryDelegate {
+  func pushRegistry(_ registry: PKPushRegistry, didUpdate credentials: PKPushCredentials, for type: PKPushType) {
+    guard type == .voIP else { return }
+    let token = credentials.token.map { String(format: "%02x", $0) }.joined()
+    // Send this token to your server, keyed by the logged-in CometChat UID
+    Task {
+      await sendVoipTokenToServer(token: token, uid: CometChat.getLoggedInUser()?.uid ?? "")
+    }
+  }
+
+  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
+    guard type == .voIP else { completion(); return }
+
+    // CRITICAL: report to CallKit IMMEDIATELY. iOS terminates apps that delay this >~5s.
+    let data = payload.dictionaryPayload["data"] as? [String: Any] ?? [:]
+    let sessionId = data["sessionId"] as? String ?? UUID().uuidString
+    let callerName = data["callerName"] as? String ?? "Unknown"
+    let callerUid = data["callerUid"] as? String ?? ""
+    let hasVideo = (data["callType"] as? String) == "video"
+
+    let uuid = UUID(uuidString: sessionId) ?? UUID()
+    reportIncomingCall(uuid: uuid, callerName: callerName, callerUid: callerUid, hasVideo: hasVideo)
+
+    // Store sessionId for later when CXAnswerCallAction fires
+    self.pendingSessionIds[uuid] = sessionId
+
+    completion()                     // ← tell iOS we're done
+  }
+
+  // iOS may invalidate the token (OS upgrade, app reinstall)
+  func pushRegistry(_ registry: PKPushRegistry, didInvalidatePushTokenFor type: PKPushType) {
+    // Token will re-register; wait for didUpdate
+  }
+}
+```
+
+**The 5-second rule:** Apple's `PKPushRegistry` documentation says you must call `reportNewIncomingCall` "promptly." Practical limit: ~5 seconds. If you exceed it, iOS terminates your app process and won't deliver future VoIP pushes for ~24 hours (apologies, no public retry mechanism).
+
+---
+
+## CallKit delegate — answer + end actions
+
+```swift
+extension CallManager: CXProviderDelegate {
+  func providerDidReset(_ provider: CXProvider) {
+    // OS reset everything — clean up local state
+    pendingSessionIds.removeAll()
+  }
+
+  func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
+    // User tapped "Answer" on the lock screen
+    guard let sessionId = pendingSessionIds[action.callUUID] else {
+      action.fail()
+      return
+    }
+
+    Task {
+      do {
+        // Accept via Chat SDK
+        try await CometChat.acceptCall(sessionID: sessionId)
+
+        // Configure AVAudioSession for voice/video call audio
+        try AVAudioSession.sharedInstance().setCategory(.playAndRecord, mode: .voiceChat)
+        try AVAudioSession.sharedInstance().setActive(true)
+
+        // Build session settings via SessionSettingsBuilder (matches upstream
+        // ringing sample at calls-sdk-ios-5/sample-apps/cometchat-calls-sample-
+        // app-ringing-ios/CometChatCallsRinging/CallView.swift).
+        let settings = SessionSettingsBuilder()
+          .setTitle("CometChat Call")
+          .startVideoPaused(false)
+          .startAudioMuted(false)
+          .build()
+
+        // Single-call joinSession(sessionID:callSetting:container:) — the SDK
+        // generates the token internally. Do NOT call generateToken separately.
+        // Container is the UIView the ongoing-call UI will be drawn into.
+        CometChatCalls.joinSession(
+          sessionID: sessionId,
+          callSetting: settings,
+          container: callContainerView   // a UIView with measurable bounds
+        ) { success in
+          // Register listeners on the resulting CallSession AFTER onSuccess
+          let session = CometChatCallsSDK.CallSession.shared
+          session.addSessionStatusListener(callListener)
+          session.addButtonClickListener(callListener)
+          action.fulfill()                  // tell CallKit we answered successfully
+        } onError: { error in
+          print("joinSession failed: \(error?.errorDescription ?? "unknown")")
+          action.fail()
+        }
+
+        // Navigate the app's UI to the ongoing-call screen
+        await MainActor.run {
+          // ...your nav logic — push the view that hosts callContainerView...
+        }
+      } catch {
+        action.fail()
+      }
+    }
+  }
+
+  func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
+    // User tapped "End" or call ended remotely.
+    // Use CallSession.shared.leaveSession() — `CometChatCalls.endSession()`
+    // doesn't exist on iOS (matches upstream ringing sample).
+    CometChatCallsSDK.CallSession.shared.leaveSession()
+
+    // CRITICAL: deactivate audio session (rule 1.5)
+    do {
+      try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+    } catch {
+      // log but don't block
+    }
+
+    pendingSessionIds.removeValue(forKey: action.callUUID)
+    action.fulfill()
+  }
+
+  func provider(_ provider: CXProvider, perform action: CXSetMutedCallAction) {
+    CometChatCalls.muteAudio(action.isMuted)
+    action.fulfill()
+  }
+}
+```
+
+---
+
+## Outgoing calls — also through CallKit
+
+For caller-initiated calls, report via `CXStartCallAction` so the call appears in the iOS Phone app's Recents:
+
+```swift
+extension CallManager {
+  func startOutgoingCall(receiverUid: String, callType: CallType) {
+    let uuid = UUID()
+    let handle = CXHandle(type: .generic, value: receiverUid)
+    let action = CXStartCallAction(call: uuid, handle: handle)
+    action.isVideo = (callType == .video)
+
+    let transaction = CXTransaction(action: action)
+    callController.request(transaction) { error in
+      if let error = error {
+        print("Failed to start outgoing call: \(error)")
+      }
+    }
+  }
+}
+
+extension CallManager {
+  // CXProviderDelegate
+  func provider(_ provider: CXProvider, perform action: CXStartCallAction) {
+    Task {
+      do {
+        let outgoing = Call(receiverUid: action.handle.value, receiverType: .user,
+                           callType: action.isVideo ? .video : .voice)
+        let initiated = try await CometChat.initiateCall(call: outgoing)
+        pendingSessionIds[action.callUUID] = initiated.sessionID
+        provider.reportOutgoingCall(with: action.callUUID, startedConnectingAt: nil)
+        action.fulfill()
+      } catch {
+        action.fail()
+      }
+    }
+  }
+}
+```
+
+This gives the user a "Calling..." UI in the iOS system. When the receiver accepts, `provider.reportOutgoingCall(connectedAt:)` switches the UI to "Connected."
+
+---
+
+## Common failure modes
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| App terminates 5s after PushKit delivery | Async work before `reportNewIncomingCall` | Report first, then do anything else |
+| "VoIP services not available" at registry setup | Background Modes capability missing | Add VoIP capability in Xcode and rebuild |
+| Token never registers | App not signed with VoIP-capable provisioning profile | Re-download provisioning profile |
+| Call rings but answering does nothing | `CXAnswerCallAction` delegate doesn't fail/fulfill | Always call `action.fulfill()` or `action.fail()` |
+| Music doesn't resume after hangup | Missing `setActive(false, .notifyOthersOnDeactivation)` | Add to `CXEndCallAction` handler |
+| Lock-screen rings but unlocking shows wrong screen | App didn't navigate to ongoing-call view in `CXAnswerCallAction` | Navigate inside the action handler |
+| Outgoing call never shows "Calling..." UI | Started via `initiateCall` directly without `CXStartCallAction` | Use `CXTransaction` flow |
+
+---
+
+## Testing without a push server
+
+Same workaround as RN — call `CallManager.shared.reportIncomingCall(...)` from a debug button. Bypasses PushKit entirely. Useful for testing the in-app + CallKit-UI flow but doesn't exercise the lock-screen ring (which requires PushKit delivery to an unlocked or terminated app).

package/skills/cometchat-ios-calls/references/custom-ui.md

@@ -0,0 +1,322 @@
+# Custom call UI on iOS
+
+Same shape as the other families' custom-ui references. iOS-specific because of CallKit interplay (rule 1.7: CallKit owns standalone-mode incoming UI, so custom in-app incoming UI is additive-mode-only) and AVFoundation routing.
+
+---
+
+## Two paths
+
+1. **Style the kit's `CometChatOngoingCall`** UIViewController via theming + property overrides. Cheapest. Covers most apps.
+2. **Build your own UIViewController on the SDK** — direct `CometChatCalls.joinSession` with your own UIView containers. Maximum control.
+
+This reference covers path 2.
+
+---
+
+## Architecture
+
+```
+Your UIViewController
+├── containerView for remote participant(s)    ← UIView the SDK draws into
+├── localPreviewView                            ← AVCaptureVideoPreviewLayer or SDK preview
+├── controlPanel (mute / camera / end / switch)
+└── statusLabel (call state, duration)
+```
+
+The Calls SDK draws video into UIViews you provide. You don't render WebRTC tracks yourself (unlike web/RN where you wire `<video>` elements).
+
+---
+
+## Custom OngoingCallViewController
+
+```swift
+import UIKit
+import AVFoundation
+import CometChatCallsSDK
+
+class CustomOngoingCallViewController: UIViewController {
+  private let containerView = UIView()
+  private let localPreviewView = UIView()
+  private lazy var controlPanel = ControlPanelView()
+  private let statusLabel = UILabel()
+
+  private let sessionID: String
+  private let isAudioOnly: Bool
+  private var listener: CometChatCallsEventsListener?
+
+  init(sessionID: String, isAudioOnly: Bool) {
+    self.sessionID = sessionID
+    self.isAudioOnly = isAudioOnly
+    super.init(nibName: nil, bundle: nil)
+    modalPresentationStyle = .fullScreen
+  }
+
+  required init?(coder: NSCoder) { fatalError() }
+
+  override func viewDidLoad() {
+    super.viewDidLoad()
+    view.backgroundColor = .black
+    setupLayout()
+    startCall()
+  }
+
+  override func viewWillDisappear(_ animated: Bool) {
+    super.viewWillDisappear(animated)
+    cleanup()
+  }
+
+  private func startCall() {
+    listener = self
+    // Build SessionSettings — match upstream sample shape.
+    // For custom UI, you typically build your own controls and just need the SDK
+    // to feed video tiles into your container. enableDefaultLayout is not part
+    // of SessionSettings — disable individual default-UI elements via the
+    // hide* setters on SessionSettingsBuilder if you want a minimal surface.
+    let settings = SessionSettingsBuilder()
+      .setTitle(isAudioOnly ? "Voice Call" : "Video Call")
+      .startVideoPaused(isAudioOnly)
+      .startAudioMuted(false)
+      .build()
+
+    // Configure audio session BEFORE joining
+    try? configureAudioSession()
+
+    // Single-call joinSession(sessionID:callSetting:container:) — the SDK
+    // generates the token internally. NO separate generateToken call.
+    CometChatCalls.joinSession(
+      sessionID: sessionID,
+      callSetting: settings,
+      container: containerView
+    ) { [weak self] success in
+      guard let self = self else { return }
+      // Register listeners on the resulting CallSession AFTER onSuccess.
+      let session = CometChatCallsSDK.CallSession.shared
+      session.addSessionStatusListener(self.listener)
+      session.addButtonClickListener(self.listener)
+    } onError: { error in
+      print("joinSession failed: \(error?.errorDescription ?? "unknown")")
+    }
+  }
+
+  private func configureAudioSession() throws {
+    let session = AVAudioSession.sharedInstance()
+    try session.setCategory(
+      .playAndRecord,
+      mode: isAudioOnly ? .voiceChat : .videoChat,
+      options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker]
+    )
+    try session.setActive(true)
+  }
+
+  private func cleanup() {
+    // CometChatCalls.endSession() does NOT exist on iOS — use CallSession.shared.leaveSession()
+    CometChatCallsSDK.CallSession.shared.leaveSession()
+    try? AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
+  }
+
+  private func setupLayout() {
+    [containerView, localPreviewView, controlPanel, statusLabel].forEach {
+      $0.translatesAutoresizingMaskIntoConstraints = false
+      view.addSubview($0)
+    }
+
+    NSLayoutConstraint.activate([
+      containerView.topAnchor.constraint(equalTo: view.topAnchor),
+      containerView.leadingAnchor.constraint(equalTo: view.leadingAnchor),
+      containerView.trailingAnchor.constraint(equalTo: view.trailingAnchor),
+      containerView.bottomAnchor.constraint(equalTo: view.bottomAnchor),
+
+      localPreviewView.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16),
+      localPreviewView.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
+      localPreviewView.widthAnchor.constraint(equalToConstant: 120),
+      localPreviewView.heightAnchor.constraint(equalToConstant: 160),
+
+      controlPanel.bottomAnchor.constraint(equalTo: view.safeAreaLayoutGuide.bottomAnchor, constant: -16),
+      controlPanel.leadingAnchor.constraint(equalTo: view.leadingAnchor, constant: 16),
+      controlPanel.trailingAnchor.constraint(equalTo: view.trailingAnchor, constant: -16),
+      controlPanel.heightAnchor.constraint(equalToConstant: 80),
+
+      statusLabel.topAnchor.constraint(equalTo: view.safeAreaLayoutGuide.topAnchor, constant: 16),
+      statusLabel.centerXAnchor.constraint(equalTo: view.centerXAnchor),
+    ])
+  }
+}
+
+extension CustomOngoingCallViewController: CometChatCallsEventsListener {
+  func onCallEnded() {
+    DispatchQueue.main.async { [weak self] in
+      self?.cleanup()
+      self?.dismiss(animated: true)
+    }
+  }
+
+  func onUserListUpdated(_ users: [Any]) {
+    DispatchQueue.main.async { [weak self] in
+      self?.statusLabel.text = "\(users.count) participants"
+    }
+  }
+
+  func onError(_ error: Error) {
+    print("Call error: \(error)")
+  }
+}
+```
+
+The `DispatchQueue.main.async` wrapping is the iOS equivalent of NgZone.run on Angular — SDK callbacks fire on background queues; UI updates must be on main.
+
+---
+
+## Control panel
+
+```swift
+final class ControlPanelView: UIView {
+  let muteButton = UIButton(type: .system)
+  let cameraButton = UIButton(type: .system)
+  let switchCameraButton = UIButton(type: .system)
+  let endButton = UIButton(type: .system)
+
+  var onMute: (() -> Void)?
+  var onCamera: (() -> Void)?
+  var onSwitch: (() -> Void)?
+  var onEnd: (() -> Void)?
+
+  override init(frame: CGRect) {
+    super.init(frame: frame)
+    backgroundColor = UIColor(white: 0, alpha: 0.4)
+    layer.cornerRadius = 40
+
+    let stack = UIStackView(arrangedSubviews: [muteButton, cameraButton, switchCameraButton, endButton])
+    stack.distribution = .equalCentering
+    stack.alignment = .center
+    stack.translatesAutoresizingMaskIntoConstraints = false
+    addSubview(stack)
+
+    NSLayoutConstraint.activate([
+      stack.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 16),
+      stack.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -16),
+      stack.centerYAnchor.constraint(equalTo: centerYAnchor),
+    ])
+
+    muteButton.setTitle("Mute", for: .normal)
+    cameraButton.setTitle("Cam", for: .normal)
+    switchCameraButton.setTitle("Flip", for: .normal)
+    endButton.setTitle("End", for: .normal)
+    endButton.tintColor = .red
+
+    muteButton.addAction(UIAction { [weak self] _ in self?.onMute?() }, for: .touchUpInside)
+    cameraButton.addAction(UIAction { [weak self] _ in self?.onCamera?() }, for: .touchUpInside)
+    switchCameraButton.addAction(UIAction { [weak self] _ in self?.onSwitch?() }, for: .touchUpInside)
+    endButton.addAction(UIAction { [weak self] _ in self?.onEnd?() }, for: .touchUpInside)
+  }
+
+  required init?(coder: NSCoder) { fatalError() }
+}
+```
+
+Wire actions in the VC:
+
+```swift
+override func viewDidLoad() {
+  super.viewDidLoad()
+  // ...
+  controlPanel.onMute = { [weak self] in
+    guard let self = self else { return }
+    self.muted.toggle()
+    CometChatCalls.muteAudio(self.muted)
+  }
+  controlPanel.onCamera = { [weak self] in
+    guard let self = self else { return }
+    self.cameraOff.toggle()
+    CometChatCalls.pauseVideo(self.cameraOff)
+  }
+  controlPanel.onSwitch = { CometChatCalls.switchCamera() }
+  controlPanel.onEnd = { [weak self] in
+    self?.cleanup()
+    self?.dismiss(animated: true)
+  }
+}
+```
+
+---
+
+## Local preview before connect
+
+```swift
+private lazy var captureSession = AVCaptureSession()
+private lazy var previewLayer = AVCaptureVideoPreviewLayer(session: captureSession)
+
+private func startLocalPreview() {
+  guard let device = AVCaptureDevice.default(.builtInWideAngleCamera, for: .video, position: .front),
+        let input = try? AVCaptureDeviceInput(device: device) else { return }
+
+  captureSession.addInput(input)
+  previewLayer.frame = localPreviewView.bounds
+  previewLayer.videoGravity = .resizeAspectFill
+  localPreviewView.layer.addSublayer(previewLayer)
+
+  DispatchQueue.global(qos: .userInitiated).async {
+    self.captureSession.startRunning()
+  }
+}
+
+private func stopLocalPreview() {
+  captureSession.stopRunning()
+  previewLayer.removeFromSuperlayer()
+}
+```
+
+Stop the preview BEFORE `joinSession` — the SDK takes over the camera and your `AVCaptureSession` will fight with it.
+
+---
+
+## SwiftUI hosting
+
+Wrap with `UIViewControllerRepresentable` (see `references/swiftui-uikit-hosting.md`):
+
+```swift
+struct CustomOngoingCallView: UIViewControllerRepresentable {
+  let sessionID: String
+  let isAudioOnly: Bool
+
+  func makeUIViewController(context: Context) -> CustomOngoingCallViewController {
+    CustomOngoingCallViewController(sessionID: sessionID, isAudioOnly: isAudioOnly)
+  }
+
+  func updateUIViewController(_ vc: CustomOngoingCallViewController, context: Context) {}
+}
+```
+
+Present via `.fullScreenCover` (NOT `.sheet`).
+
+---
+
+## Picture-in-picture
+
+iOS supports PiP for video calls via `AVPictureInPictureController`:
+
+```swift
+import AVKit
+
+class CustomOngoingCallViewController {
+  private var pipController: AVPictureInPictureController?
+
+  func setupPiP() {
+    guard AVPictureInPictureController.isPictureInPictureSupported() else { return }
+    let layer = AVSampleBufferDisplayLayer()
+    containerView.layer.addSublayer(layer)
+    let contentSource = AVPictureInPictureController.ContentSource(sampleBufferDisplayLayer: layer, playbackDelegate: self)
+    pipController = AVPictureInPictureController(contentSource: contentSource)
+    pipController?.canStartPictureInPictureAutomaticallyFromInline = true
+  }
+}
+```
+
+Setting up PiP for WebRTC video is involved — the SDK doesn't expose a `CMSampleBuffer` stream directly. For most apps, `enableDefaultLayout(true)` and let the kit's PiP work; custom UI authors who need PiP can use `CometChatPictureInPicture` (kit class) as a hybrid — kit's PiP, custom rest of UI.
+
+---
+
+## When NOT to go custom
+
+The kit's `CometChatOngoingCall` covers 80% of apps. Custom is for design-system requirements that the kit's theming + property overrides can't reach. Same calculus as web/RN/Angular.
+
+The dispatcher asks before scaffolding custom and defaults to "no — use kit."