@cometchat/skills 4.3.0 → 4.4.1

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

@@ -33,25 +33,25 @@ No code needed beyond CallKit setup. The skill defaults to this path for standal
 
 ---
 
-## SDK-managed PiP layout — `CallSession.shared.enablePictureInPictureLayout()`
+## SDK-managed PiP — `CometChatCalls.enterPIPMode()` / `exitPIPMode()`
 
-> **Audit 2026-05-14, confirmed against `https://www.cometchat.com/docs/calls/ios/picture-in-picture.md`:** The iOS Calls SDK v5.x exposes two methods to toggle the SDK's INTERNAL compact layout — it does NOT expose video frames or a `CMSampleBuffer` pipeline to drive a host-app `AVPictureInPictureController`. An earlier draft of this doc cited `CometChatCalls.attachPictureInPictureLayer(layer)` / `detachPictureInPictureLayer()` — **those symbols do not exist on CometChatCallsSDK v5.x**.
+> **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-style" layout | `CallSession.shared.enablePictureInPictureLayout()` |
-| Switch back to full layout | `CallSession.shared.disablePictureInPictureLayout()` |
+| 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
-CallSession.shared.enablePictureInPictureLayout()
+CometChatCalls.enterPIPMode()
 
 // When they tap to expand back, or before hangup
-CallSession.shared.disablePictureInPictureLayout()
+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.
@@ -61,29 +61,29 @@ This is **NOT iOS system-level PiP** (the floating window that survives backgrou
 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 compact layout API** (above) for in-app minimization. Acceptable UX for foreground-only flows.
+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 compact layout
+### Toggle button for SDK PiP mode
 
 ```swift
 @IBAction func toggleCompactLayout(_ sender: UIButton) {
   if isCompact {
-    CallSession.shared.disablePictureInPictureLayout()
+    CometChatCalls.exitPIPMode()
   } else {
-    CallSession.shared.enablePictureInPictureLayout()
+    CometChatCalls.enterPIPMode()
   }
   isCompact.toggle()
 }
 ```
 
-This switches the SDK's call surface between full and compact 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.
+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 compact-layout API for in-app PiP-style minimization.
+> **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.
 
 ---
 
@@ -185,11 +185,11 @@ When the call ends:
 
 ```swift
 func endCall() {
-  // Switch SDK back to default layout BEFORE ending the session, otherwise
-  // a re-init of the SDK can inherit compact-layout state on the next call.
-  CallSession.shared.disablePictureInPictureLayout()
+  // 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()
 
-  CallSession.shared.leaveSession()   // ends the WebRTC session
+  CometChatCalls.endSession()   // ends the WebRTC session (EXISTS in v5)
 
   do {
     try AVAudioSession.sharedInstance().setActive(false, options: .notifyOthersOnDeactivation)
@@ -203,7 +203,7 @@ If you ALSO drove a host-app `AVPictureInPictureController` (against an external
 
 ## Anti-patterns
 
-1. **Using `CometChatCalls.attachPictureInPictureLayer(layer)` / `detachPictureInPictureLayer()`** — these symbols **do not exist** on `CometChatCallsSDK` v5.x. Confirmed against the SDK docs 2026-05-14. Use `CallSession.shared.enable/disablePictureInPictureLayout()` instead.
+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.
@@ -216,9 +216,9 @@ If you ALSO drove a host-app `AVPictureInPictureController` (against an external
 - [ ] `audio` in `UIBackgroundModes` (Info.plist)
 - [ ] Background Modes capability includes "Audio, AirPlay, and Picture in Picture"
 
-**SDK compact-layout path (in-app PiP, no system-level PiP):**
-- [ ] `CallSession.shared.enablePictureInPictureLayout()` called to enter compact mode
-- [ ] `CallSession.shared.disablePictureInPictureLayout()` called BEFORE `leaveSession()` on hangup
+**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)
 

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

@@ -1,239 +1,26 @@
-# Raise hand on iOS
+# Raise hand on iOS — NOT supported on the iOS Calls SDK v5
 
-Native CometChatCallsSDK exposes the same conceptual API as the JS SDK — `raiseHand()` / `lowerHand()` plus delegate callbacks. The wow piece is wiring it into UIKit / SwiftUI cleanly + the system-level UX (CallKit doesn't show raised-hand state on the lock screen, so the in-app surface is the canonical place).
+**Raise-hand is not available on the iOS `CometChatCallsSDK` v5.** Do not emit any of these — none of them exist on the SDK:
 
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/raise-hand
-**Read first:** `cometchat-react-calls/references/raise-hand.md` — UX shape + anti-patterns are identical; this reference is the iOS-specific Swift wiring.
+- `CometChatCalls.raiseHand()` / `CometChatCalls.lowerHand()`
+- `onParticipantHandRaised` / `onParticipantHandLowered` (no such `CallsEventsDelegate` callbacks)
+- any `setShowRaiseHandButton` / `enableRaiseHand` builder flag
 
----
-
-## SDK API
-
-```swift
-import CometChatCallsSDK
-
-// Local user
-CometChatCalls.raiseHand()
-CometChatCalls.lowerHand()
-
-// Listener — set via the call event listener attached at session start
-class CallListener: NSObject, CometChatCallsEventsListener {
-  func onParticipantHandRaised(_ participant: Participant) {
-    // participant.uid, participant.name
-  }
-  func onParticipantHandLowered(_ participant: Participant) {
-    // ...
-  }
-}
-
-// Settings flag
-let settings = CallSettingsBuilder()
-  .setSessionType(.video)
-  .hideRaiseHandButton(true)
-  .build()
-```
-
----
-
-## SwiftUI integration — observable state holder
-
-```swift
-import SwiftUI
-import Combine
-import CometChatCallsSDK
-
-struct RaisedParticipant: Identifiable {
-  let id: String         // uid
-  let name: String
-  let raisedAt: Date
-}
-
-final class RaiseHandState: ObservableObject {
-  @Published var localRaised: Bool = false
-  @Published var raised: [RaisedParticipant] = []
-
-  func toggle() {
-    if localRaised {
-      CometChatCalls.lowerHand()
-    } else {
-      CometChatCalls.raiseHand()
-    }
-    localRaised.toggle()
-  }
-
-  func handle(participantRaised p: Participant) {
-    DispatchQueue.main.async {
-      let entry = RaisedParticipant(id: p.uid, name: p.name, raisedAt: Date())
-      self.raised.removeAll { $0.id == p.uid }
-      self.raised.append(entry)
-      self.raised.sort { $0.raisedAt < $1.raisedAt }
-    }
-  }
-
-  func handle(participantLowered p: Participant) {
-    DispatchQueue.main.async {
-      self.raised.removeAll { $0.id == p.uid }
-    }
-  }
-}
-```
-
-`DispatchQueue.main.async` wraps SDK callbacks — same rule as elsewhere in iOS calls integrations (cf. `references/group-calls.md`). Without it, `@Published` updates from a background queue cause UI thread warnings + skipped re-renders.
-
----
-
-## Toggle button (SwiftUI)
-
-```swift
-struct RaiseHandButton: View {
-  @ObservedObject var state: RaiseHandState
-
-  var body: some View {
-    Button(action: state.toggle) {
-      Label(state.localRaised ? "Lower" : "Raise hand",
-            systemImage: state.localRaised ? "hand.raised.fill" : "hand.raised")
-    }
-    .buttonStyle(.bordered)
-    .tint(state.localRaised ? .yellow : .white)
-    .accessibilityLabel(state.localRaised ? "Lower hand" : "Raise hand")
-    .accessibilityAddTraits(state.localRaised ? .isSelected : [])
-    .onChange(of: state.localRaised) { newValue in
-      UIAccessibility.post(notification: .announcement, argument:
-        newValue ? "Hand raised" : "Hand lowered")
-    }
-  }
-}
-```
-
-`UIAccessibility.post(.announcement, ...)` is the iOS equivalent of web's `aria-live` and RN's `AccessibilityInfo.announceForAccessibility`. VoiceOver picks it up.
-
----
-
-## Raised-hands sheet (SwiftUI)
+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.
 
-```swift
-struct RaisedHandsSheet: View {
-  @ObservedObject var state: RaiseHandState
+## If a customer asks for raise-hand on iOS
 
-  var body: some View {
-    VStack(alignment: .leading, spacing: 12) {
-      Text("Raised hands (\(state.raised.count))")
-        .font(.headline)
-      if state.raised.isEmpty {
-        Text("No hands raised").foregroundColor(.secondary)
-      } else {
-        ForEach(state.raised) { p in
-          HStack {
-            Text("✋").font(.title2)
-            Text(p.name).font(.body)
-            Spacer()
-            Text(secondsAgo(p.raisedAt))
-              .font(.caption)
-              .foregroundColor(.secondary)
-          }
-          .padding(.vertical, 4)
-        }
-      }
-    }
-    .padding()
-    .presentationDetents([.fraction(0.3), .medium])
-  }
-
-  func secondsAgo(_ t: Date) -> String {
-    "\(Int(Date().timeIntervalSince(t)))s ago"
-  }
-}
-```
-
-`.presentationDetents([.fraction(0.3), .medium])` is iOS 16+ — gives the user two snap heights, matching the BottomSheet pattern from RN.
-
----
-
-## UIKit pattern
-
-For UIKit projects (the kit's default surface):
-
-```swift
-class CallViewController: UIViewController {
-  private let state = RaiseHandState()
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    // ... attach state to call event listener at session start
-  }
-
-  @objc private func raiseHandTapped() {
-    state.toggle()
-    // Update the UIBarButtonItem appearance
-    raiseHandButton.image = UIImage(systemName: state.localRaised ? "hand.raised.fill" : "hand.raised")
-    raiseHandButton.tintColor = state.localRaised ? .systemYellow : .label
-  }
-
-  func presentRaisedHandsSheet() {
-    let host = UIHostingController(rootView: RaisedHandsSheet(state: state))
-    if #available(iOS 15.0, *) {
-      host.sheetPresentationController?.detents = [.medium(), .large()]
-    }
-    present(host, animated: true)
-  }
-}
-```
-
-`UIHostingController(rootView:)` lets you embed a SwiftUI sheet in a UIKit nav stack. `sheetPresentationController.detents` is the iOS 15+ pull-up sheet API.
-
----
-
-## Toast announcement for the host
-
-iOS has no native toast — use `UNUserNotificationCenter` for an in-call banner-style notification, OR a custom view:
-
-```swift
-extension RaiseHandState {
-  func showRaisedNotification(for p: Participant) {
-    let banner = UIView()
-    banner.backgroundColor = .systemYellow.withAlphaComponent(0.95)
-    let label = UILabel()
-    label.text = "✋ \(p.name) raised their hand"
-    label.textColor = .black
-    label.font = .systemFont(ofSize: 14, weight: .medium)
-    // ...add to view, animate down from top, dismiss after 4s
-  }
-}
-```
-
-Or use a third-party lib like `NotificationBannerSwift`. Custom is fine; just don't use `UNUserNotificationCenter` (which is system-level and feels out of place for in-call signals).
-
----
-
-## Anti-patterns
-
-Web sister reference rules apply, plus iOS-specific:
-
-1. **`@Published` updates from non-main queue.** SwiftUI warns "publishing changes from background threads is not allowed." Always wrap SDK callbacks in `DispatchQueue.main.async`.
-2. **Forgetting `accessibilityAddTraits(.isSelected)` on the toggle button.** VoiceOver doesn't announce "selected" state without it.
-3. **Using `UNUserNotificationCenter`** for in-call raise-hand alerts. System-level; feels wrong. Use a custom banner.
-4. **`removeAll { $0.id == p.uid }` then `append` without sort.** When a participant raises again after lowering, position in queue should reset to "now"; current code already does the right thing, but easy to break by reordering operations.
-
----
+There is no SDK affordance to wire. The options are:
 
-## Verification checklist
+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.
 
-- [ ] `RaiseHandState` is an `ObservableObject`
-- [ ] All SDK callbacks wrap in `DispatchQueue.main.async`
-- [ ] Toggle button has `accessibilityLabel` + `accessibilityAddTraits(.isSelected)` when raised
-- [ ] `UIAccessibility.post(.announcement, ...)` on toggle
-- [ ] Raised-hands list sorted by `raisedAt` ascending
-- [ ] `hideRaiseHandButton: true` in CallSettings if custom UI
-- [ ] Real-device smoke: 3 iPhones in same call, host sees both raised
-- [ ] VoiceOver smoke: enable VoiceOver, raise hand, hear "Hand raised" announcement
+Do NOT scaffold a `CometChatCalls.raiseHand()` call path; it will not compile.
 
 ---
 
 ## Pointers
 
-- `cometchat-react-calls/references/raise-hand.md` — sister reference (UX shape)
-- `cometchat-ios-calls` SKILL.md — the seven hard rules
-- `references/group-calls.md` — group call iOS architecture
-- `references/swiftui-uikit-hosting.md` — embedding SwiftUI sheets in UIKit
-- `cometchat-a11y` — UIAccessibility patterns
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/raise-hand
+- `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

@@ -18,40 +18,34 @@ Same as web/RN — enable in **Dashboard → Chat & Messaging → Calls → Reco
 import CometChatCallsSDK
 
 let settings = CallSettingsBuilder()
-  .setSessionType(.video)
   .setIsAudioOnly(false)
-  .enableRecording(true)              // server starts recording on session start
-  .setShowRecordingButton(true)       // user-toggleable mid-call
+  .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)
 
-```swift
-class CustomOngoingCallViewController: UIViewController {
-  @IBOutlet weak var recBadge: UIView!
+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).
 
-  func setupCallListener() {
-    let listener = CometChatCallsEventsListener()
-    listener.onRecordingStarted = { [weak self] in
-      DispatchQueue.main.async { self?.recBadge.isHidden = false }
-    }
-    listener.onRecordingStopped = { [weak self] in
-      DispatchQueue.main.async { self?.recBadge.isHidden = true }
-    }
-    listener.onRecordingFailed = { [weak self] error in
-      DispatchQueue.main.async {
-        let alert = UIAlertController(title: "Recording failed",
-                                       message: error.message,
-                                       preferredStyle: .alert)
-        alert.addAction(UIAlertAction(title: "OK", style: .default))
-        self?.present(alert, animated: true)
-      }
+```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
@@ -100,7 +94,7 @@ CometChat hosts the file. Same as web/RN — accessible via dashboard UI or REST
 
 ## Screen sharing — iOS Calls SDK v5.x does NOT support INITIATING
 
-**Audit finding 2026-05-14, confirmed against `https://www.cometchat.com/docs/calls/ios/screen-sharing.md`:** the iOS Calls SDK explicitly does not support initiating screen sharing. iOS callers can RECEIVE incoming screen shares from web/Android peers (via the `onParticipantStartedScreenShare` listener + `Call.isPresenting` property — see "Viewer" section below) but cannot SEND.
+**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.
 
@@ -108,8 +102,8 @@ The symbols previously documented in this file (`CometChatCalls.startScreenShare
 
 | Direction | Status | API |
 |---|---|---|
-| Receive screen share (iOS callee) | ✅ supported | `OngoingCallListener.onParticipantStartedScreenShare` + `Call.isPresenting` |
-| Initiate screen share (iOS caller → others) | ❌ NOT supported by CometChatCallsSDK v5.x | n/a |
+| 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:
 
@@ -193,93 +187,17 @@ class CustomOngoingCallViewController: UIViewController {
 
 When the user taps the picker, iOS shows the system broadcast UI listing your extension. They tap it; the extension activates; capture begins.
 
-### Step 5 — SampleHandler.swift implementation (FICTIONAL — SDK doesn't support this)
-
-> **⚠️ Audit 2026-05-14**: the symbols below (`CometChatCalls.startScreenShareBroadcast`, `processBroadcastVideoFrame`, `processBroadcastAudioFrame`, `endScreenShareBroadcast`) **do not exist on CometChatCallsSDK v5.x**. The vendor docs at `https://www.cometchat.com/docs/calls/ios/screen-sharing.md` state explicitly: *"The iOS Calls SDK does not support initiating screen sharing."* This code path will not compile. Kept here only to document what the architecture would look like if a future SDK version added support.
-
-The extension entry point. Receives audio + video sample buffers from iOS:
-
-```swift
-import ReplayKit
-import CometChatCallsSDK
-
-class SampleHandler: RPBroadcastSampleHandler {
+### Steps 5–6 — SDK frame bridge: NOT available
 
-  override func broadcastStarted(withSetupInfo setupInfo: [String : NSObject]?) {
-    // Read the active session ID + auth token from the App Group
-    let groupId = "group.com.yourcompany.yourapp.broadcast"
-    let defaults = UserDefaults(suiteName: groupId)
-
-    guard let sessionId = defaults?.string(forKey: "cometchat.sessionId"),
-          let authToken = defaults?.string(forKey: "cometchat.authToken") else {
-      finishBroadcastWithError(NSError(domain: "CometChat", code: 1,
-                                        userInfo: [NSLocalizedDescriptionKey: "No active session"]))
-      return
-    }
-
-    // Initialize the Calls SDK in screen-share mode for this session
-    // (the SDK provides a setup helper; verify the exact symbol against installed CometChatCallsSDK)
-    CometChatCalls.startScreenShareBroadcast(sessionID: sessionId, authToken: authToken)
-  }
-
-  override func processSampleBuffer(_ sampleBuffer: CMSampleBuffer, with sampleBufferType: RPSampleBufferType) {
-    switch sampleBufferType {
-    case .video:
-      CometChatCalls.processBroadcastVideoFrame(sampleBuffer)
-    case .audioApp:
-      CometChatCalls.processBroadcastAudioFrame(sampleBuffer, type: .app)
-    case .audioMic:
-      CometChatCalls.processBroadcastAudioFrame(sampleBuffer, type: .mic)
-    @unknown default:
-      break
-    }
-  }
-
-  override func broadcastFinished() {
-    CometChatCalls.endScreenShareBroadcast()
-  }
-}
-```
-
-**Confirmed against the SDK docs 2026-05-14**: these symbols are NOT present in CometChatCallsSDK v5.x. The code above is illustrative only.
-
-### Step 6 — Main app: pre-write session state to App Group before starting (FICTIONAL — see audit note above)
-
-In the main app's call code, before triggering the broadcast picker:
-
-```swift
-func prepareScreenShare(sessionId: String, authToken: String) {
-  let groupId = "group.com.yourcompany.yourapp.broadcast"
-  let defaults = UserDefaults(suiteName: groupId)
-  defaults?.set(sessionId, forKey: "cometchat.sessionId")
-  defaults?.set(authToken, forKey: "cometchat.authToken")
-  defaults?.synchronize()
-}
-```
-
-Now when the user taps the picker, the extension can read this state on launch.
+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
 
-Same pattern as RN/web. Listen for `onScreenShareStarted` and render the screen track in a dedicated view:
+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).
 
-```swift
-listener.onScreenShareStarted = { [weak self] presenterUid in
-  DispatchQueue.main.async {
-    self?.showScreenShareView(presenterUid: presenterUid)
-  }
-}
-
-listener.onScreenShareEnded = { [weak self] in
-  DispatchQueue.main.async {
-    self?.hideScreenShareView()
-  }
-}
-```
-
-The screen-share track renders in the SDK's container; for custom UI, the SDK exposes the track via `MediaStream` events the same way regular video is delivered.
+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.
 
 ---
 
@@ -291,7 +209,7 @@ The screen-share track renders in the SDK's container; for custom UI, the SDK ex
 | "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 `onRecordingStarted/Stopped` and render badge |
+| 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 |
 
 ---
@@ -311,23 +229,18 @@ The screen-share track renders in the SDK's container; for custom UI, the SDK ex
 
 **Recording:**
 - [ ] Dashboard plan includes recording feature
-- [ ] `enableRecording(true)` on `CallSettingsBuilder`
-- [ ] `onRecordingStarted` / `onRecordingStopped` listeners wired
+- [ ] `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
-- [ ] `onRecordingFailed` surfaces user-facing alert
-
-**Screen share — receiver side only (iOS Calls SDK v5.x cannot INITIATE):**
-- [ ] `OngoingCallListener.onParticipantStartedScreenShare` wired
-- [ ] `OngoingCallListener.onParticipantEndedScreenShare` wired
-- [ ] UI surfaces incoming-share state to the user (e.g. tile resize, presenter badge)
-- [ ] `Call.isPresenting` read where needed to gate UI affordances
-- [ ] Sender-side screen-share architecture (Broadcast Extension, SampleHandler) NOT implemented against current SDK — the symbols don't exist (per audit 2026-05-14)
-
-**Real-device smoke:**
-- [ ] Tap broadcast picker → consent dialog → screen share begins
-- [ ] Other participants see the shared screen
-- [ ] End screen share via system overlay → returns to camera view
-- [ ] Hangup ends broadcast even if user didn't manually stop sharing
+
+**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)
 
 ---
 

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

@@ -1,6 +1,6 @@
 # Ringing — call signaling with custom UI (iOS)
 
-iOS-specific deltas: PushKit + CallKit are mandatory for backgrounded ring delivery; foreground ringing uses CometChatCallsEventsListener; AVAudioSession routing.
+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.
 
@@ -12,41 +12,42 @@ iOS-specific deltas: PushKit + CallKit are mandatory for backgrounded ring deliv
 import CometChatSDK
 import CometChatCallsSDK
 
-let call = Call(receiverUid: receiverUid, callType: .video, receiverType: .user)
-CometChat.initiateCall(call: call) { result in
-  switch result {
-  case .success(let outgoing): self.showOutgoingCallScreen(outgoing)
-  case .onError(let err): print("Initiate failed:", err)
-  }
-}
+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
 
-Implement `CometChatCallsEventsListener` and register at app start:
+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: CometChatCallsEventsListener {
-  func onIncomingCallReceived(call: Call) {
+class AppCallListener: NSObject, CometChatCallDelegate {
+  func onIncomingCallReceived(incomingCall: Call?, error: CometChatException?) {
+    guard let call = incomingCall else { return }
     DispatchQueue.main.async { showIncomingCallScreen(call) }
   }
-  func onOutgoingCallAccepted(call: Call) {
+  func onOutgoingCallAccepted(acceptedCall: Call?, error: CometChatException?) {
+    guard let call = acceptedCall else { return }
     DispatchQueue.main.async { startCallSession(sessionId: call.sessionId) }
   }
-  func onIncomingCallCancelled(call: Call) {
+  func onIncomingCallCancelled(canceledCall: Call?, error: CometChatException?) {
     DispatchQueue.main.async { dismissIncomingCallScreen() }
   }
-  func onOutgoingCallRejected(call: Call) {
+  func onOutgoingCallRejected(rejectedCall: Call?, error: CometChatException?) {
     DispatchQueue.main.async { dismissOutgoingCallScreen() }
   }
-  func onCallEndedMessageReceived(call: Call) {
+  func onCallEndedMessageReceived(endedCall: Call?, error: CometChatException?) {
     DispatchQueue.main.async { teardownCallUI() }
   }
 }
 
-CometChat.addCallListener(id: "app", listener: AppCallListener())
+CometChat.addCallListener("app", AppCallListener())   // positional labels
 ```
 
 Add this in `AppDelegate.didFinishLaunchingWithOptions` AFTER `CometChat.init` succeeds.