@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-ios-calls/references/in-call-chat.md

@@ -1,179 +0,0 @@
-# In-call chat on iOS
-
-> **The iOS Calls SDK v5 has NO in-call chat button.** There is no `setHideChatButton` on `CallSettingsBuilder`, no `onChatButtonClicked` callback on `CallsEventsDelegate`, and no `CometChatCalls.setChatButtonUnreadCount(_:)`. None of these symbols exist — do not emit them.
-
-In-call chat is therefore an **app-level composition**, not an SDK feature: you add your OWN chat button to your call UI, and present a sheet hosting the kit's `CometChatMessageList` + `CometChatMessageComposer` over a group keyed to the call's session ID. The Calls SDK is not involved.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/in-call-chat
-**Read first:** `cometchat-react-calls/references/in-call-chat.md` — group-as-session architecture + anti-patterns.
-
----
-
-## Your own chat button (the SDK provides none)
-
-Add a button to your call control panel and present the sheet yourself. Track unread count in your own state (from a `CometChat.addMessageListener` on the session group) — there is no SDK badge API.
-
-```swift
-import CometChatSDK
-
-// In your call UIViewController:
-let chatButton = UIButton(type: .system)
-chatButton.addAction(UIAction { [weak self] _ in
-  self?.presentChatSheet()        // present on main; you're already on main here
-}, for: .touchUpInside)
-
-// Unread badge: maintain your own count from a message listener on the session group,
-// and update chatButton's badge view. There is no CometChatCalls.setChatButtonUnreadCount.
-```
-
----
-
-## Sheet presentation (iOS 15+)
-
-```swift
-import UIKit
-
-class CallViewController: UIViewController {
-  func presentChatSheet() {
-    let chatVC = InCallChatViewController(sessionId: sessionId)
-    let nav = UINavigationController(rootViewController: chatVC)
-
-    if #available(iOS 15.0, *) {
-      if let sheet = nav.sheetPresentationController {
-        sheet.detents = [.medium(), .large()]
-        sheet.prefersGrabberVisible = true
-        sheet.preferredCornerRadius = 16
-      }
-    }
-
-    present(nav, animated: true)
-  }
-}
-```
-
-`.detents = [.medium(), .large()]` is iOS 15+'s pull-up sheet API. Matches the BottomSheet UX from RN/Flutter.
-
----
-
-## InCallChatViewController
-
-```swift
-class InCallChatViewController: UIViewController {
-  let sessionId: String
-  private var group: Group?
-  private var listenerId: String!
-
-  init(sessionId: String) {
-    self.sessionId = sessionId
-    super.init(nibName: nil, bundle: nil)
-    self.title = "Chat"
-  }
-  required init?(coder: NSCoder) { fatalError() }
-
-  override func viewDidLoad() {
-    super.viewDidLoad()
-    listenerId = "in-call-chat-\(sessionId)"
-
-    Task {
-      do {
-        group = try await ensureGroup(sessionId: sessionId)
-        try await joinGroup(sessionId: sessionId)
-        await MainActor.run {
-          self.embedMessageList()
-        }
-      } catch {
-        print("Failed to set up in-call chat:", error)
-      }
-    }
-  }
-
-  override func viewWillDisappear(_ animated: Bool) {
-    super.viewWillDisappear(animated)
-    // Clear YOUR unread count on close (no SDK badge API exists).
-    NotificationCenter.default.post(name: .inCallChatClosed, object: nil)
-  }
-
-  private func embedMessageList() {
-    guard let group = group else { return }
-    // The kit's CometChatMessageList is a UIViewController
-    let messageList = CometChatMessageList()
-    messageList.group = group
-    addChild(messageList)
-    view.addSubview(messageList.view)
-    // ... AutoLayout pinning to fill view
-    messageList.didMove(toParent: self)
-
-    // Composer
-    let composer = CometChatMessageComposer()
-    composer.group = group
-    addChild(composer)
-    view.addSubview(composer.view)
-    // ... AutoLayout pinning to bottom
-    composer.didMove(toParent: self)
-  }
-}
-
-func ensureGroup(sessionId: String) async throws -> Group {
-  do {
-    return try await fetchGroup(sessionId)   // CometChat.getGroup wrapper
-  } catch {
-    let group = Group(guid: sessionId, name: "Call \(sessionId)", groupType: .public, password: "")
-    return try await createGroup(group)
-  }
-}
-```
-
----
-
-## Audio ducking when keyboard opens
-
-iOS auto-ducks call audio when the system keyboard opens (the kit handles this). For custom UI you may want to maintain unducked audio for the whole call — explicit override:
-
-```swift
-NotificationCenter.default.addObserver(
-  forName: UIResponder.keyboardWillShowNotification,
-  object: nil, queue: .main
-) { _ in
-  // Re-assert non-ducking audio category
-  try? AVAudioSession.sharedInstance().setCategory(
-    .playAndRecord,
-    mode: .voiceChat,
-    options: [.allowBluetooth, .defaultToSpeaker]
-  )
-}
-```
-
-Most apps don't need this; the kit's defaults are sensible. Override only if user testing surfaces the audio ducking as confusing.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus iOS-specific:
-
-1. **Wiring `setHideChatButton` / `onChatButtonClicked` / `setChatButtonUnreadCount`.** None exist on iOS v5. Present your own button + sheet; track unread in your own state.
-2. **`present(nav, animated: true)` from background queue.** Crash. Always main queue.
-3. **Mutating `group` from background.** `group` updates must be on main; `Task { @MainActor in ... }` or `DispatchQueue.main.async`.
-4. **Forgetting `dismiss(animated: true)` on call end.** Sheet stays up over the post-call screen — looks broken.
-
----
-
-## Verification checklist
-
-- [ ] Your OWN chat button presents the sheet (no `setHideChatButton`/`onChatButtonClicked`/`setChatButtonUnreadCount` — none exist)
-- [ ] Sheet presented on main queue
-- [ ] `UISheetPresentationController` with `[.medium(), .large()]` detents (iOS 15+)
-- [ ] `CometChatMessageList` + `CometChatMessageComposer` embedded as child VCs
-- [ ] Sheet dismissed on call end
-- [ ] Real-device smoke: 2 iPhones in call, send message → badge in other
-- [ ] Sheet drag-down dismisses cleanly
-- [ ] Lock-screen smoke: backgrounded → return → chat sheet still visible if open
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/in-call-chat.md` — sister web reference (group-as-session pattern)
-- `cometchat-ios-calls` SKILL.md — the seven hard rules
-- `references/swiftui-uikit-hosting.md` — embedding SwiftUI sheets
-- Canonical docs: https://www.cometchat.com/docs/calls/ios/in-call-chat

package/skills/cometchat-ios-calls/references/migration-v4-to-v5.md

@@ -1,196 +0,0 @@
-# CometChat Calls iOS SDK v4 → v5 migration
-
-`CometChatCallsSDK` v5 keeps the same session model as v4 — a per-session call token, a `CallSettingsBuilder`, and a static `CometChatCalls` facade. There is **no** `CometChatCalls.login`, **no** `CallSession`/`CallSession.shared`, and **no** `SessionSettings` struct. Auth is per-session via `generateToken`.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/ios/migration-guide-v5
-
-> Every symbol below is verified against the v5 `CometChatCallsSDK` Swift interface. Do NOT introduce `CallSession`, `joinSession`, `SessionSettings`, `SessionSettingsBuilder`, `CometChatCallsEventsListener`, `muteAudio`/`pauseVideo`, `setLayout`, or `startScreenShare` — none of these exist in v5.
-
----
-
-## Step 1 — Bump the SDK
-
-**SwiftPM:** Update the `CometChatCallsSDK` package version pin to `5.0.0` or higher.
-
-**CocoaPods:**
-```ruby
-# Podfile
-pod 'CometChatCallsSDK', '~> 5.0'
-```
-
-```bash
-pod install --repo-update
-```
-
----
-
-## Step 2 — Init
-
-Init takes a `CallAppSettings` built with `CallAppSettingsBuilder`, passed under the `callsAppSettings:` label (note the `s` — `callsAppSettings`, not `callAppSettings`).
-
-```swift
-let callAppSettings = CallAppSettingsBuilder()
-  .setAppId("APP_ID")
-  .setRegion("REGION")
-  .build()
-
-CometChatCalls.init(callsAppSettings: callAppSettings, onSuccess: { _ in
-  // ready
-}, onError: { error in
-  // surface error
-})
-```
-
-There is no async/await `init(with:)` form and no `CallAppSettings.Builder()` nested type — use `CallAppSettingsBuilder()`.
-
----
-
-## Step 3 — Auth is per-session (no Calls SDK login)
-
-> **There is NO `CometChatCalls.login` and NO `CometChatCalls.getLoggedInUser` in v5.** Do not call them — they do not exist on the Calls SDK.
-
-Authentication is per call session. Get a call token immediately before starting a session:
-
-```swift
-// Chat SDK still owns the user session. Get its auth token from the Chat SDK:
-let authToken = CometChat.getUserAuthToken()   // CometChatSDK — User has NO `authToken` property
-
-CometChatCalls.generateToken(authToken: authToken, sessionID: sessionID, onSuccess: { token in
-  // `token` is the call token you pass to startSession
-}, onError: { error in
-  // surface error
-})
-```
-
-`generateToken` is `CometChatCalls.generateToken(authToken:sessionID:onSuccess:onError:)`.
-
----
-
-## Step 4 — Session settings (`CallSettingsBuilder`, not `SessionSettings`)
-
-> **There is NO `SessionSettings` struct and NO `SessionSettingsBuilder`.** Use `CallSettingsBuilder().build()` which returns `CallSettings`.
-
-```swift
-let callSettings = CallSettingsBuilder()
-  .setIsAudioOnly(false)               // was setSessionType(.video) — there is no setSessionType
-  .setStartAudioMuted(false)
-  .setStartVideoMuted(false)
-  .setShowRecordingButton(true)        // NOT inverted — there is no hideRecordingButton
-  .setMode(.default)                   // setMode(_ value: DisplayModes) — swiftinterface:281 (.default/.single/.spotlight); NSString overload is deprecated
-  .setDelegate(self)                   // self conforms to CallsEventsDelegate
-  .build()
-```
-
-There is no `setLayout`, no `setHideChatButton`, no `enableRecording`. Recording-button visibility is `setShowRecordingButton(_:)`; auto-record on start is `setStartRecordingOnCallStart(_:)`.
-
----
-
-## Step 5 — Start / end the session
-
-> **There is NO `joinSession` and NO `CallSession`.** The lifecycle is `generateToken` → `startSession` → `endSession`, all static on `CometChatCalls`.
-
-```swift
-// `view` is the UIView the SDK renders the call into.
-CometChatCalls.startSession(callToken: token, callSetting: callSettings, view: callView, onSuccess: { _ in
-  // session started
-}, onError: { error in
-  // surface error
-})
-
-// End the call:
-CometChatCalls.endSession()             // EXISTS in v5 — do not say it doesn't
-```
-
----
-
-## Step 6 — Events: `CallsEventsDelegate`, not `CometChatCallsEventsListener`
-
-> **The listener protocol is `CallsEventsDelegate`.** `CometChatCallsEventsListener` does not exist. There is no `addEventListener(.someEnum)` granular-subscription API.
-
-```swift
-// v5: implement the CallsEventsDelegate protocol (callbacks are @objc optional).
-// Prefer the TYPED forms below (swiftinterface:29-54); the NSDictionary/NSArray
-// overloads still exist but are DEPRECATED.
-extension MyCallController: CallsEventsDelegate {
-  func onSessionTimeout()                                          { /* idle timeout — swiftinterface:30 */ }
-  func onCallEnded()                                               { /* ... */ }
-  func onCallEndButtonPressed()                                    { /* ... */ }
-  func onUserJoined(rtcUser: RTCUser)                              { /* swiftinterface:35 */ }
-  func onUserLeft(rtcUser: RTCUser)                                { /* swiftinterface:38 */ }
-  func onUserListChanged(rtcUsers: [RTCUser])                      { /* swiftinterface:41 */ }
-  func onAudioModeChanged(mode: [CallAudioMode])                   { /* swiftinterface:44 */ }
-  func onCallSwitchedToVideo(callSwitchedInfo: CallSwitchRequestInfo) { /* swiftinterface:47 */ }
-  func onUserMuted(rtcMutedUser: RTCMutedUser)                     { /* swiftinterface:50 */ }
-  func onRecordingToggled(recordingInfo: RTCRecordingInfo)         { /* one callback — no Started/Stopped/Failed split — swiftinterface:53 */ }
-}
-
-// Register either via the builder (setDelegate, Step 4) or:
-CometChatCalls.addCallEventListener(observerId: "my-id", delegate: self)
-```
-
-There is no `onScreenShareStarted`/`onScreenShareEnded`, no `onChatButtonClicked`, no `onActiveSpeakerUpdated`, and no layout-change callback in v5.
-
----
-
-## Step 7 — In-call control method names
-
-```diff
-- CometChatCalls.muteAudio(true)       // phantom
-+ CometChatCalls.audioMuted(true)      // mute
-+ CometChatCalls.audioMuted(false)     // unmute
-
-- CometChatCalls.pauseVideo(true)      // phantom
-+ CometChatCalls.videoPaused(true)
-+ CometChatCalls.videoPaused(false)
-
-  CometChatCalls.switchCamera()        // unchanged
-
-- CometChatCalls.setMode(mode)         // setMode is on CallSettingsBuilder, not the runtime facade
-+ // layout is fixed at session start via CallSettingsBuilder.setMode(_:) — there is no runtime setLayout
-
-  CometChatCalls.startRecording()      // recording control
-  CometChatCalls.stopRecording()
-
-  CometChatCalls.enterPIPMode()        // PiP — NOT CallSession.shared.enablePictureInPictureLayout
-  CometChatCalls.exitPIPMode()
-```
-
-Local screen-share initiation is **not** available on the iOS Calls SDK v5 — there is no `startScreenShare`.
-
----
-
-## Chat SDK signaling (ringing mode) — verify these too
-
-```diff
-- Call(receiverUid: uid, receiverType: .user, callType: .video)
-+ Call(receiverId: uid, callType: .video, receiverType: .user)   // CometChatSDK arg order
-
-- callType: .voice
-+ callType: .audio                     // CallType is .audio / .video / .audioVideo — there is no .voice
-
-- CometChat.login(UID:..., authKey:...)  // still correct; there is NO loginAsync
-```
-
-Call delegate is `CometChatCallDelegate` with two-param callbacks, e.g. `onIncomingCallReceived(incomingCall:error:)`; register with `CometChat.addCallListener(_:_:)` (positional labels).
-
----
-
-## Verification checklist
-
-- [ ] Podfile / Package.swift updated to `~> 5.0`
-- [ ] `pod install --repo-update` (CocoaPods) or SwiftPM resolved cleanly
-- [ ] NO `CometChatCalls.login` anywhere — auth is per-session via `generateToken`
-- [ ] `CallSettingsBuilder().build()` used; no `SessionSettings`/`SessionSettingsBuilder`
-- [ ] `CallsEventsDelegate` implemented; no `CometChatCallsEventsListener`, no `addEventListener(.enum)`
-- [ ] Lifecycle is `generateToken` → `startSession` → `endSession`; no `joinSession`, no `CallSession.shared`
-- [ ] Controls use `audioMuted`/`videoPaused`/`enterPIPMode`/`exitPIPMode`
-- [ ] `Call(receiverId:callType:receiverType:)` arg order; `CallType` has no `.voice`
-- [ ] Real-device smoke: incoming call from iPhone → answer → mute → end
-
----
-
-## Pointers
-
-- Canonical migration: https://www.cometchat.com/docs/calls/ios/migration-guide-v5
-- `cometchat-ios-calls/SKILL.md` — seven hard rules (still apply post-v5)
-- `cometchat-ios-calls/references/server-apns-pushkit.md` — PushKit setup (unchanged in v5)

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