@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-ios-calls/references/picture-in-picture.md

@@ -1,246 +0,0 @@
-# Picture-in-Picture on iOS
-
-iOS supports PiP for video calls via `AVPictureInPictureController` (iOS 14+) or via CallKit's auto-PiP (iOS 14+ when CallKit reports a video call). For most production calling apps, **CallKit handles PiP for free** — if you've integrated CallKit (rule 1.7 in the SKILL.md), iOS auto-PiPs your call when the user backgrounds the app.
-
-The `AVPictureInPictureController` path is only needed for non-CallKit foreground-only calls (rare — most production apps use CallKit).
-
----
-
-## CallKit auto-PiP — the simplest path
-
-If your app integrates CallKit (rule 1.7, mandatory for VoIP push standalone mode), iOS auto-handles PiP. When the user presses Home during an active call:
-
-1. iOS automatically captures the call's video stream
-2. The CallKit-managed call enters PiP mode
-3. The PiP window floats above all apps, even system UI
-4. Tapping the PiP window foregrounds your app
-
-No code needed beyond CallKit setup. The skill defaults to this path for standalone-mode calls.
-
-### Required entitlements
-
-```xml
-<!-- Info.plist — already required by CallKit -->
-<key>UIBackgroundModes</key>
-<array>
-  <string>audio</string>
-  <string>voip</string>
-  <string>remote-notification</string>
-</array>
-```
-
-`audio` background mode is what lets the call's audio continue while in PiP. Without it, video PiP works but audio cuts.
-
----
-
-## SDK-managed PiP — `CometChatCalls.enterPIPMode()` / `exitPIPMode()`
-
-> **Verified against `CometChatCallsSDK` v5 Swift interface:** the SDK exposes two STATIC methods on `CometChatCalls` to toggle its internal picture-in-picture mode — `CometChatCalls.enterPIPMode()` and `CometChatCalls.exitPIPMode()`. There is NO `CallSession.shared.enablePictureInPictureLayout()` (no `CallSession` type exists), and NO `CometChatCalls.attachPictureInPictureLayer(layer)` / `detachPictureInPictureLayer()`. The SDK does NOT expose video frames or a `CMSampleBuffer` pipeline to drive a host-app `AVPictureInPictureController`.
-
-### What works today
-
-| Goal | API |
-|---|---|
-| Switch the SDK's call surface to compact PiP mode | `CometChatCalls.enterPIPMode()` |
-| Switch back to full layout | `CometChatCalls.exitPIPMode()` |
-
-```swift
-import CometChatCallsSDK
-
-// When the user taps "minimize" in the call UI
-CometChatCalls.enterPIPMode()
-
-// When they tap to expand back, or before hangup
-CometChatCalls.exitPIPMode()
-```
-
-This is **NOT iOS system-level PiP** (the floating window that survives backgrounding). It's an in-app compact layout. For true OS-level PiP (floating call window across all apps + lock screen), see the CallKit path above.
-
-### Custom system-level PiP via `AVPictureInPictureController` — NOT directly supported
-
-Driving iOS system-level PiP via `AVPictureInPictureController` requires feeding video frames to an `AVSampleBufferDisplayLayer`. The Calls SDK does not expose its WebRTC video track for this — the peer-connection handle is internal. Three options:
-
-1. **Recommended: use CallKit** (rule 1.7 SKILL.md). CallKit-managed VoIP calls get auto-PiP for free — no `AVPictureInPictureController` plumbing needed.
-2. **Use the SDK's PiP-mode API** (above — `enterPIPMode()`/`exitPIPMode()`) for in-app minimization. Acceptable UX for foreground-only flows.
-3. **Roll your own WebRTC bridge.** Requires forking/patching the SDK to expose the underlying `RTCMediaStream` — not recommended.
-
-### Required capability (CallKit path)
-
-In Xcode → Signing & Capabilities → Background Modes → ensure **Audio, AirPlay, and Picture in Picture** is checked. CallKit needs this; without it, CallKit's auto-PiP doesn't fire even with a CallKit-managed call.
-
-### Toggle button for SDK PiP mode
-
-```swift
-@IBAction func toggleCompactLayout(_ sender: UIButton) {
-  if isCompact {
-    CometChatCalls.exitPIPMode()
-  } else {
-    CometChatCalls.enterPIPMode()
-  }
-  isCompact.toggle()
-}
-```
-
-This switches the SDK's call surface between full and compact PiP layouts. The compact view shows local + remote video tiles in a smaller container; useful when you want to free screen space for other UI but keep the call visible.
-
-> **Note**: `AVPictureInPictureController` + KVO on `isPictureInPicturePossible` patterns (previously documented here) are not applicable because the SDK does not expose the video frames `AVPictureInPictureController` requires. Use the CallKit path for system-level PiP, or this `enterPIPMode()`/`exitPIPMode()` API for in-app PiP-style minimization.
-
----
-
-## SwiftUI integration
-
-Wrap the UIKit view controller as a `UIViewControllerRepresentable`:
-
-```swift
-struct PiPCallView: UIViewControllerRepresentable {
-  let sessionID: String
-
-  func makeUIViewController(context: Context) -> CustomOngoingCallViewController {
-    let vc = CustomOngoingCallViewController(sessionID: sessionID)
-    return vc
-  }
-
-  func updateUIViewController(_ vc: CustomOngoingCallViewController, context: Context) {}
-}
-```
-
-Use in your SwiftUI app:
-
-```swift
-struct CallScreen: View {
-  let sessionID: String
-
-  var body: some View {
-    PiPCallView(sessionID: sessionID)
-      .ignoresSafeArea()
-  }
-}
-```
-
----
-
-## Auto-PiP on backgrounding (manual path)
-
-iOS 14+ supports auto-PiP from inline AVKit playback. For active calls:
-
-```swift
-pipController?.canStartPictureInPictureAutomaticallyFromInline = true
-```
-
-Combined with the `audio` background mode, this gives you the same behavior as CallKit auto-PiP: press Home → call enters PiP → audio + video continue.
-
----
-
-## Delegate methods
-
-```swift
-extension CustomOngoingCallViewController: AVPictureInPictureControllerDelegate {
-  func pictureInPictureControllerWillStartPictureInPicture(_ pip: AVPictureInPictureController) {
-    // Hide your in-page video (it duplicates with PiP)
-    sampleBufferDisplayLayer?.isHidden = true
-  }
-
-  func pictureInPictureControllerDidStartPictureInPicture(_ pip: AVPictureInPictureController) {
-    // PiP is active
-  }
-
-  func pictureInPictureController(_ pip: AVPictureInPictureController,
-                                    failedToStartPictureInPictureWithError error: Error) {
-    print("PiP failed:", error)
-  }
-
-  func pictureInPictureControllerDidStopPictureInPicture(_ pip: AVPictureInPictureController) {
-    sampleBufferDisplayLayer?.isHidden = false
-  }
-
-  func pictureInPictureController(_ pip: AVPictureInPictureController,
-                                    restoreUserInterfaceForPictureInPictureStopWithCompletionHandler completion: @escaping (Bool) -> Void) {
-    // User tapped the PiP window — restore the full call screen
-    if let nav = self.navigationController {
-      nav.popToRootViewController(animated: true)
-    }
-    completion(true)
-  }
-}
-```
-
-`restoreUserInterfaceForPictureInPictureStopWithCompletionHandler` is critical — without it, tapping the PiP window restores nothing.
-
----
-
-## Lock screen + PiP
-
-When the device is locked during a call:
-
-- **CallKit-managed call:** PiP appears on the lock screen as part of the CallKit incoming-call card. Audio continues; video shows in the lock-screen UI.
-- **Manual `AVPictureInPictureController`:** PiP cannot show on the lock screen. The video pauses; audio continues if `audio` background mode is set.
-
-Standalone-mode VoIP apps must use CallKit for the lock-screen video story to work.
-
----
-
-## Hangup cleanup
-
-When the call ends:
-
-```swift
-func endCall() {
-  // Exit PiP mode BEFORE ending the session, otherwise a re-init of the SDK
-  // can inherit compact-layout state on the next call.
-  CometChatCalls.exitPIPMode()
-
-  CometChatCalls.endSession()   // ends the WebRTC session (EXISTS in v5)
-
-  do {
-    try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
-  } catch {}
-}
-```
-
-If you ALSO drove a host-app `AVPictureInPictureController` (against an external video source), call `pipController?.stopPictureInPicture()` before tearing down. The CometChat SDK has no awareness of that controller.
-
----
-
-## Anti-patterns
-
-1. **Using `CometChatCalls.attachPictureInPictureLayer(layer)` / `detachPictureInPictureLayer()`, or any `CallSession.shared.*PictureInPictureLayout()` call** — none of these symbols exist on `CometChatCallsSDK` v5 (there is no `CallSession` type). Use `CometChatCalls.enterPIPMode()` / `CometChatCalls.exitPIPMode()` instead.
-2. **Manual `AVPictureInPictureController` for VoIP apps without CallKit.** Lock-screen ringing breaks; the SDK does not expose its video pipeline so the PiP window won't render the call. Use CallKit.
-3. **No `audio` background mode.** Audio cuts when the app backgrounds, regardless of PiP path.
-4. **Mixing SDK compact-layout with host-driven `AVPictureInPictureController`.** Two competing PiP surfaces — the SDK's compact layout fights the user's manual PiP, both look broken. Pick one.
-
----
-
-## Verification checklist
-
-- [ ] CallKit integrated (rule 1.7 in SKILL.md) — gives you PiP for free
-- [ ] `audio` in `UIBackgroundModes` (Info.plist)
-- [ ] Background Modes capability includes "Audio, AirPlay, and Picture in Picture"
-
-**SDK PiP-mode path (in-app PiP, no system-level PiP):**
-- [ ] `CometChatCalls.enterPIPMode()` called to enter compact mode
-- [ ] `CometChatCalls.exitPIPMode()` called BEFORE `endSession()` on hangup
-- [ ] UI button to toggle between full/compact layouts
-- [ ] NOT used together with a host-app `AVPictureInPictureController` (see anti-pattern #4)
-
-**Real-device smoke (CallKit path):**
-- [ ] Press Home during call → PiP appears (auto via CallKit)
-- [ ] Audio continues through PiP transition
-- [ ] Tap PiP window → app foregrounds, full call screen restored
-- [ ] Lock device → PiP visible on lock screen (CallKit only)
-- [ ] Hangup ends call cleanly; no stuck PiP window
-
-**Real-device smoke (SDK compact-layout path):**
-- [ ] Tap "minimize" → SDK switches to compact layout in-app
-- [ ] Tap "expand" → SDK switches back to full layout
-- [ ] Hangup from compact layout cleanly ends call
-
----
-
-## Pointers
-
-- `references/callkit-and-pushkit.md` — CallKit gives PiP for free
-- `references/avaudiosession-routing.md` — audio routing during PiP transitions
-- `references/swiftui-uikit-hosting.md` — SwiftUI hosting of the UIKit PiP view controller
-- `cometchat-native-calls/references/picture-in-picture.md` — sister reference (RN bridges to the same iOS APIs)
-- `cometchat-react-calls/references/picture-in-picture.md` — Web PiP (different APIs but same UX shape)
-- `cometchat-ios-calls` SKILL.md — base hard rules

package/skills/cometchat-ios-calls/references/raise-hand.md

@@ -1,26 +0,0 @@
-# Raise hand on iOS — NOT supported on the iOS Calls SDK v5
-
-**Raise-hand is not available on the iOS `CometChatCallsSDK` v5.** Do not emit any of these — none of them exist on the SDK:
-
-- `CometChatCalls.raiseHand()` / `CometChatCalls.lowerHand()`
-- `onParticipantHandRaised` / `onParticipantHandLowered` (no such `CallsEventsDelegate` callbacks)
-- any `setShowRaiseHandButton` / `enableRaiseHand` builder flag
-
-The `CallsEventsDelegate` surface in v5 (verified against `CometChatCallsSDK` swiftinterface:29-54) is: `onSessionTimeout()`, `onCallEnded()`, `onCallEndButtonPressed()`, plus the participant/media events in BOTH a current TYPED form and a DEPRECATED `NSDictionary`/`NSArray` form — `onUserJoined(rtcUser:)`, `onUserLeft(rtcUser:)`, `onUserListChanged(rtcUsers:)`, `onAudioModeChanged(mode:)`, `onUserMuted(rtcMutedUser:)`, `onRecordingToggled(recordingInfo:)`, `onCallSwitchedToVideo(callSwitchedInfo:)`. Prefer the typed forms (`RTCUser`, `RTCMutedUser`, `RTCRecordingInfo`, `CallSwitchRequestInfo`, `CallAudioMode`). There is NO hand-raise event of any spelling.
-
-## If a customer asks for raise-hand on iOS
-
-There is no SDK affordance to wire. The options are:
-
-1. **Build it out-of-band over the Chat SDK.** Send a custom message / transient message (e.g. `TransientMessage` or a typed `CustomMessage`) from the raising user, and have each client render a hand badge from those messages. This is app-level state the Calls SDK is not involved in.
-2. **Defer to web/Android** if the meeting must have first-class raise-hand and those platforms support it.
-3. **Wait for vendor support** — track the CometChat iOS Calls SDK release notes.
-
-Do NOT scaffold a `CometChatCalls.raiseHand()` call path; it will not compile.
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/raise-hand.md` — web raise-hand (the feature shape, where it IS supported)
-- `cometchat-ios-calls` SKILL.md — base hard rules

package/skills/cometchat-ios-calls/references/recording-screen-share.md

@@ -1,252 +0,0 @@
-# Recording + screen-share on iOS
-
-Recording is server-side (same as every family). Screen-share on iOS requires a **separate Xcode target** — the iOS Broadcast Upload Extension — because Apple sandboxes screen capture in a separate process. This is the most involved screen-share integration of any family.
-
-For SDK semantics + browser-side details, read `cometchat-react-calls/references/recording-screen-share.md` first. This reference is the iOS-specific manual setup and bridge code.
-
----
-
-## Recording
-
-### Server-side: dashboard gate
-
-Same as web/RN — enable in **Dashboard → Chat & Messaging → Calls → Recording**. Client flag is no-op without it.
-
-### Client-side flag
-
-```swift
-import CometChatCallsSDK
-
-let settings = CallSettingsBuilder()
-  .setIsAudioOnly(false)
-  .setStartRecordingOnCallStart(true)   // auto-start recording on session start
-  .setShowRecordingButton(true)         // show the kit's user-toggleable REC button
-  .build()
-```
-
-There is no `setSessionType` and no `enableRecording` on the iOS v5 builder. Auto-start is `setStartRecordingOnCallStart(_:)`; button visibility is `setShowRecordingButton(_:)`. To toggle recording programmatically mid-call, use the static `CometChatCalls.startRecording()` / `CometChatCalls.stopRecording()`.
-
-### Lifecycle events (REC indicator)
-
-The iOS Calls SDK v5 has a SINGLE recording callback — `onRecordingToggled(info:)` on `CallsEventsDelegate` (swiftinterface label is `info:`, payload is an `NSDictionary`). There is no `onRecordingStarted`/`onRecordingStopped`/`onRecordingFailed` split, and the delegate is a protocol you conform to (not an object with assignable closure properties).
-
-```swift
-extension CustomOngoingCallViewController: CallsEventsDelegate {
-  // swiftinterface: onRecordingToggled(info: NSDictionary)
-  func onRecordingToggled(info: NSDictionary) {
-    DispatchQueue.main.async { [weak self] in
-      // info carries the current recording state + initiating user.
-      // Drive the REC badge from your own isRecording flag toggled here.
-      self?.isRecording.toggle()
-      self?.recBadge.isHidden = !(self?.isRecording ?? false)
-    }
-  }
-}
-```
-
-Wire the delegate via `CallSettingsBuilder.setDelegate(self)` or `CometChatCalls.addCallEventListener(observerId:delegate:)`. There is no separate recording-failure callback — surface failures from your own start/stop call sites if you toggle programmatically.
-
-The badge: a small "REC" pill with a blinking red dot. Must be visible to all participants — compliance requirement (CCPA, GDPR Art. 6/7, two-party-consent US states).
-
-```swift
-final class RecBadgeView: UIView {
-  override init(frame: CGRect) {
-    super.init(frame: frame)
-    backgroundColor = UIColor(white: 0, alpha: 0.6)
-    layer.cornerRadius = 4
-
-    let dot = UILabel()
-    dot.text = "●"
-    dot.textColor = .systemRed
-    dot.font = .systemFont(ofSize: 12)
-    dot.translatesAutoresizingMaskIntoConstraints = false
-
-    let label = UILabel()
-    label.text = "REC"
-    label.textColor = .white
-    label.font = .systemFont(ofSize: 12, weight: .semibold)
-    label.translatesAutoresizingMaskIntoConstraints = false
-
-    addSubview(dot)
-    addSubview(label)
-    NSLayoutConstraint.activate([
-      dot.leadingAnchor.constraint(equalTo: leadingAnchor, constant: 6),
-      dot.centerYAnchor.constraint(equalTo: centerYAnchor),
-      label.leadingAnchor.constraint(equalTo: dot.trailingAnchor, constant: 4),
-      label.trailingAnchor.constraint(equalTo: trailingAnchor, constant: -6),
-      label.centerYAnchor.constraint(equalTo: centerYAnchor),
-    ])
-
-    // Blink animation
-    UIView.animate(withDuration: 0.8, delay: 0, options: [.repeat, .autoreverse], animations: {
-      dot.alpha = 0.3
-    })
-  }
-  required init?(coder: NSCoder) { fatalError() }
-}
-```
-
-### Recording retrieval
-
-CometChat hosts the file. Same as web/RN — accessible via dashboard UI or REST API from your server. Never expose recording URLs to the iOS client.
-
----
-
-## Screen sharing — iOS Calls SDK v5.x does NOT support INITIATING
-
-**Confirmed against the v5 `CometChatCallsSDK` Swift interface:** the iOS Calls SDK does not support initiating screen sharing. iOS callees can RECEIVE incoming screen shares from web/Android peers — the SDK renders the incoming screen track into the session view automatically — but `CallsEventsDelegate` exposes NO dedicated screen-share callback (no `onScreenShareStarted`/`onScreenShareEnded`, no `onParticipantStartedScreenShare`, no `OngoingCallListener`). iOS cannot SEND.
-
-The symbols previously documented in this file (`CometChatCalls.startScreenShareBroadcast`, `processBroadcastVideoFrame`, `processBroadcastAudioFrame`, `endScreenShareBroadcast`) **do not exist** on `CometChatCallsSDK` v5.x. If you've copied these from an earlier draft of this doc, they will not compile against the actual SDK.
-
-### What works today
-
-| Direction | Status | API |
-|---|---|---|
-| Receive screen share (iOS callee) | ✅ supported (rendered by the SDK into the session view) | no dedicated callback — the screen track renders like any remote video |
-| Initiate screen share (iOS caller → others) | ❌ NOT supported by CometChatCallsSDK v5 | n/a |
-
-For applications that need iOS users to share their screen today, the practical options are:
-
-1. **Defer screen-share initiation to web/Android peers.** Document that iOS callers are receive-only for screen content.
-2. **Wait for vendor support.** Track the CometChat iOS Calls SDK release notes; this is a known gap.
-3. **Build your own WebRTC bridge** in a Broadcast Upload Extension and attach a manual video track to the underlying peer connection. The CometChat session is a WebRTC peer connection internally, but the SDK does not expose the peer-connection handle, so this requires forking/patching the SDK — not recommended.
-
-### Architecture pieces that remain valid (for future SDK support)
-
-Steps 1–4 below (Broadcast Upload Extension target, App Groups capability, `RPBroadcastProcessModeSampleBuffer` Info.plist, `RPSystemBroadcastPickerView`) are all valid iOS-level setup that any future SDK adding sender-side screen-share would also require. Kept here for reference. **Skip Steps 5–6 (SampleHandler.swift + App-Group state pre-write) — they reference SDK symbols that do not exist.**
-
-iOS sandboxes screen capture inside a separate process. To share (IF the SDK supported it), you would need:
-
-1. **A Broadcast Upload Extension target** in your Xcode project
-2. **An App Group capability** shared between the main app and the extension
-3. **An RPSystemBroadcastPickerView** (provided by ReplayKit) that lets the user start sharing
-4. **A WebRTC bridge in the extension** that pipes captured frames into the Calls SDK session
-
-Apple doesn't allow main-app screen capture for privacy reasons; this Extension architecture is unavoidable.
-
-### Step 1 — Create the Broadcast Upload Extension
-
-Xcode → File → New → Target → **Broadcast Upload Extension**.
-
-- Product Name: `YourAppBroadcastExtension`
-- Bundle Identifier: `com.yourcompany.YourApp.BroadcastExtension`
-- Embed in Application: YourApp
-
-Xcode generates a `SampleHandler.swift` with stub methods.
-
-### Step 2 — App Group
-
-Both the main target AND the extension target need this capability.
-
-Main app target → Signing & Capabilities → + Capability → **App Groups** → enable `group.com.yourcompany.yourapp.broadcast`.
-
-Extension target → same capability, same group identifier.
-
-### Step 3 — Info.plist for the extension
-
-The extension's `Info.plist` (auto-generated by Xcode) must have:
-
-```xml
-<key>NSExtension</key>
-<dict>
-  <key>NSExtensionPointIdentifier</key>
-  <string>com.apple.broadcast-services-upload</string>
-  <key>NSExtensionPrincipalClass</key>
-  <string>$(PRODUCT_MODULE_NAME).SampleHandler</string>
-  <key>RPBroadcastProcessMode</key>
-  <string>RPBroadcastProcessModeSampleBuffer</string>
-</dict>
-```
-
-`RPBroadcastProcessModeSampleBuffer` is critical — without it, the extension receives audio/video data in a different format that doesn't fit the Calls SDK's bridge.
-
-### Step 4 — RPSystemBroadcastPickerView in the call screen
-
-```swift
-import ReplayKit
-
-class CustomOngoingCallViewController: UIViewController {
-  private lazy var broadcastPicker: RPSystemBroadcastPickerView = {
-    let picker = RPSystemBroadcastPickerView(frame: CGRect(x: 0, y: 0, width: 50, height: 50))
-    picker.preferredExtension = "com.yourcompany.YourApp.BroadcastExtension"
-    picker.showsMicrophoneButton = false           // SDK handles mic
-    return picker
-  }()
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    // Find and customize the actual button inside the picker (Apple's API restriction)
-    if let button = broadcastPicker.subviews.compactMap({ $0 as? UIButton }).first {
-      button.setImage(UIImage(systemName: "rectangle.on.rectangle.angled"), for: .normal)
-    }
-    view.addSubview(broadcastPicker)
-    // Layout broadcastPicker as part of your control panel
-  }
-}
-```
-
-When the user taps the picker, iOS shows the system broadcast UI listing your extension. They tap it; the extension activates; capture begins.
-
-### Steps 5–6 — SDK frame bridge: NOT available
-
-iOS cannot INITIATE screen share (receive-only). `CometChatCallsSDK` v5.x exposes no frame-bridge API (`startScreenShareBroadcast`/`processBroadcastVideoFrame`/`processBroadcastAudioFrame`/`endScreenShareBroadcast` are all absent), so there is no `SampleHandler` pipeline to write — defer screen-share initiation to web/Android peers.
-
----
-
-## Viewer — receiving someone else's screen share
-
-When a web/Android peer starts sharing, the iOS Calls SDK renders the incoming screen track into the session `view` you passed to `startSession` — exactly like any other remote video tile. There is **no** `onScreenShareStarted`/`onScreenShareEnded` callback on `CallsEventsDelegate` to hook (those symbols do not exist on iOS v5).
-
-If you need to react to participant changes around a screen share (e.g. relayout), use the typed participant callbacks — `onUserJoined(rtcUser:)`, `onUserLeft(rtcUser:)`, `onUserListChanged(rtcUsers:)` (swiftinterface:35,38,41 — `RTCUser` objects). For default-UI integrations no code is required: the SDK handles the screen-track layout for you.
-
----
-
-## Common failure modes
-
-| Symptom | Cause | Fix |
-|---|---|---|
-| Picker doesn't show your extension | Bundle ID mismatch in `preferredExtension` | Match the extension target's Bundle ID exactly |
-| "No active session" finishBroadcastWithError | App Group identifier mismatch | Both targets must use the same `group.*` identifier |
-| Extension launches but no video on remote side | Missing `RPBroadcastProcessModeSampleBuffer` in extension Info.plist | Add it |
-| Recording flag set but no recording in dashboard | Plan doesn't include recording, or dashboard toggle off | Enable in dashboard |
-| REC badge missing | Custom UI — must render manually | Subscribe to `onRecordingToggled(info:)` and render badge |
-| Screen share doesn't end on call hangup | `broadcastFinished` not triggering | Manually call `RPBroadcastController.shared.finishBroadcast(...)` from main app on hangup |
-
----
-
-## Anti-patterns
-
-1. **Embedding screen-share logic in the main app target.** iOS doesn't allow it — must be a separate extension.
-2. **App Groups with mismatched identifiers.** Extension can't see main app state; broadcast finishes immediately.
-3. **`RPSystemBroadcastPickerView` with hidden button via removeFromSuperview.** Apple may reject the build for App Store. Customize via subview iteration only.
-4. **No REC indicator.** Compliance violation in two-party-consent jurisdictions.
-5. **Trying to access recording files from the device.** They're not local — server-only access via REST API.
-6. **Implementing the SampleHandler.broadcastStarted/processSampleBuffer/broadcastFinished pipeline against CometChatCallsSDK v5.x.** Per the audit above, the SDK does not expose `startScreenShareBroadcast`, `processBroadcastVideoFrame`, `processBroadcastAudioFrame`, or `endScreenShareBroadcast`. Steps 5–6 of this doc are kept for reference but will not compile against the actual SDK today.
-
----
-
-## Verification checklist
-
-**Recording:**
-- [ ] Dashboard plan includes recording feature
-- [ ] `setStartRecordingOnCallStart(true)` and/or `setShowRecordingButton(true)` on `CallSettingsBuilder` (no `enableRecording`)
-- [ ] `onRecordingToggled(info:)` listener wired (single callback — no Started/Stopped/Failed split)
-- [ ] REC badge visible to all participants when active
-
-**Screen share — receiver side only (iOS Calls SDK v5 cannot INITIATE):**
-- [ ] No code required for default UI — the SDK renders the incoming screen track into the session view
-- [ ] No `onScreenShareStarted`/`onScreenShareEnded`/`onParticipantStartedScreenShare`/`OngoingCallListener` referenced (none exist on iOS v5)
-- [ ] Sender-side screen-share architecture (Broadcast Extension, SampleHandler) NOT implemented against current SDK — the symbols don't exist
-
-**Real-device smoke (receive-only — iOS cannot INITIATE screen share):**
-- [ ] When a participant on another platform (web/Android) shares their screen, it renders in the iOS call view
-- [ ] No sender-side broadcast picker/UI is shown on iOS (there is no initiation API in the v5 SDK)
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/recording-screen-share.md` — sister reference (SDK semantics, browser semantics, server-side recording retrieval)
-- `cometchat-native-calls/references/recording-screen-share.md` — RN reference (same Broadcast Upload Extension pattern; this iOS version is more detailed)
-- `references/group-calls.md` — recording group calls (server composition handles layout)
-- `cometchat-ios-calls` SKILL.md — base hard rules

package/skills/cometchat-ios-calls/references/ringing-integration.md

@@ -1,143 +0,0 @@
-# Ringing — call signaling with custom UI (iOS)
-
-iOS-specific deltas: PushKit + CallKit are mandatory for backgrounded ring delivery; foreground ringing uses the Chat SDK's `CometChatCallDelegate` (NOT the Calls SDK's `CallsEventsDelegate`); AVAudioSession routing.
-
-**Read first:** `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules.
-
----
-
-## SDK API
-
-```swift
-import CometChatSDK
-import CometChatCallsSDK
-
-let call = Call(receiverId: receiverUid, callType: .video, receiverType: .user)
-CometChat.initiateCall(call: call, onSuccess: { outgoing in
-  self.showOutgoingCallScreen(outgoing)
-}, onError: { err in
-  print("Initiate failed:", err)
-})
-```
-
----
-
-## Foreground listener
-
-Ringing/signaling events live on the Chat SDK's `CometChatCallDelegate` (its callbacks take TWO params: the call and an error). Implement it and register at app start with the positional `CometChat.addCallListener(_:_:)`:
-
-```swift
-class AppCallListener: NSObject, CometChatCallDelegate {
-  func onIncomingCallReceived(incomingCall: Call?, error: CometChatException?) {
-    guard let call = incomingCall else { return }
-    DispatchQueue.main.async { showIncomingCallScreen(call) }
-  }
-  func onOutgoingCallAccepted(acceptedCall: Call?, error: CometChatException?) {
-    guard let call = acceptedCall else { return }
-    DispatchQueue.main.async { startCallSession(sessionId: call.sessionId) }
-  }
-  func onIncomingCallCancelled(canceledCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { dismissIncomingCallScreen() }
-  }
-  func onOutgoingCallRejected(rejectedCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { dismissOutgoingCallScreen() }
-  }
-  func onCallEndedMessageReceived(endedCall: Call?, error: CometChatException?) {
-    DispatchQueue.main.async { teardownCallUI() }
-  }
-}
-
-CometChat.addCallListener("app", AppCallListener())   // positional labels
-```
-
-Add this in `AppDelegate.didFinishLaunchingWithOptions` AFTER `CometChat.init` succeeds.
-
----
-
-## Backgrounded ring — PushKit + CallKit (mandatory)
-
-iOS requires PushKit + CallKit for ring delivery when the app is backgrounded or killed. The foreground listener does NOT fire in those states. See `cometchat-ios-calls/references/server-apns-pushkit.md` for the server template.
-
-PushKit delegate flow:
-1. `pushRegistry(_:didReceiveIncomingPushWith:for:completion:)` fires
-2. Within ~5s, call `CXProvider.reportNewIncomingCall(with:update:)` — Apple revokes VoIP entitlement after 3 missed reports
-3. CallKit shows the system incoming-call UI
-4. User taps Accept → `provider(_:perform:CXAnswerCallAction)` fires → start CometChat session
-
----
-
-## SwiftUI incoming-call screen
-
-```swift
-struct IncomingCallScreen: View {
-  let call: Call
-  let onAccept: () -> Void
-  let onReject: () -> Void
-
-  var body: some View {
-    ZStack {
-      Color.black.opacity(0.85).ignoresSafeArea()
-      VStack(spacing: 24) {
-        AsyncImage(url: URL(string: call.callInitiator?.avatar ?? ""))
-          .frame(width: 120, height: 120)
-          .clipShape(Circle())
-        Text(call.callInitiator?.name ?? "Unknown")
-          .font(.title)
-        Text("Incoming \(call.type.rawValue) call")
-          .foregroundStyle(.secondary)
-        HStack(spacing: 32) {
-          Button(action: onReject) {
-            Image(systemName: "phone.down.fill")
-              .padding(20)
-              .background(Color.red, in: Circle())
-              .foregroundStyle(.white)
-          }
-          .accessibilityLabel("Decline call")
-          Button(action: onAccept) {
-            Image(systemName: "phone.fill")
-              .padding(20)
-              .background(Color.green, in: Circle())
-              .foregroundStyle(.white)
-          }
-          .accessibilityLabel("Accept call")
-        }
-      }
-      .foregroundStyle(.white)
-    }
-  }
-}
-```
-
-For backgrounded ring, CallKit's UI takes over — your SwiftUI screen only fires for foreground rings.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus iOS-specific:
-
-1. **Listener registered before `CometChat.init`.** Crash. Always register after init's success block.
-2. **Skipping PushKit + CallKit.** Backgrounded calls don't ring. Apple may also revoke VoIP entitlement if you ship with `pushType: .voIP` registered but no CallKit reporting.
-3. **Updating UI from listener callback's thread.** SDK fires off main; always `DispatchQueue.main.async` for UI updates.
-4. **Playing AVAudioPlayer ringtone during CallKit ring.** CallKit plays system ringtone; double-up is jarring.
-
----
-
-## Verification checklist
-
-- [ ] Foreground listener registered after `CometChat.init` resolves
-- [ ] PushKit registry initialized + .p8 key configured
-- [ ] CallKit `CXProvider.reportNewIncomingCall` fires within 5s of push
-- [ ] All listener callbacks dispatch to main queue
-- [ ] `removeCallListener` in app teardown
-- [ ] Real-device smoke: foreground ring, backgrounded ring (push), killed-app ring (push) all surface UI
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/ringing-integration.md` — canonical
-- `cometchat-ios-calls/SKILL.md` — seven hard rules
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — PushKit server-side
-- `cometchat-ios-calls/references/callkit-and-pushkit.md` — CallKit details
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/ringing