@cometchat/skills 4.1.0 → 4.2.0

package/skills/cometchat-native-calls/references/group-calls.md

@@ -0,0 +1,291 @@
+# Group calls (meetings) on React Native
+
+1:1 calls are most of what apps need. Group calls — multi-party meetings with 3-N participants — have a different set of failure modes: capacity limits, network bandwidth scaling, active-speaker UI, roster management, moderation (mute-all, kick), and capacity warnings. This reference covers them.
+
+The Calls SDK supports group calls natively; the kit's `CometChatOngoingCall` component handles up to ~10 participants well. Beyond that, custom UI (`references/custom-ui.md`) becomes necessary.
+
+---
+
+## Signaling architecture — meeting-message broadcast, NOT call ringing
+
+**Critical to read first.** Group calls do NOT use the Ringing channel (`CometChat.initiateCall` → `onIncomingCallReceived`). That channel is **1:1 user calls only**. The kit broadcasts a **custom message of type `"meeting"`** to the group; receivers see a "Join meeting" card in their `<CometChatMessageList />` (kit) or need an explicit `onCustomMessageReceived` listener (custom UI).
+
+Confirmed against kit source 2026-05-15: `node_modules/@cometchat/chat-uikit-react-native/src/calls/CometChatCallButtons/CometChatCallButtons.tsx:138-201`.
+
+```
+Caller (uid-A, member of group-X)        CometChat                Receivers (members of group-X)
+  │                                          │                              │
+  │ <CometChatCallButtons group={x}>         │                              │
+  │ → CometChatUIKit.sendCustomMessage(      │                              │
+  │     CustomMessage(GUID, GROUP,           │                              │
+  │       "meeting",                         │                              │
+  │       { callType, sessionId }))          │                              │
+  ├─────────────────────────────────────────>│                              │
+  │                                          │ onCustomMessageReceived      │
+  │                                          ├─────────────────────────────>│ (each receiver's
+  │                                          │                              │  MessageListener)
+  │                                          │                              │
+  │ caller mounts <CometChatOngoingCall      │   receiver taps "Join"       │
+  │   sessionID={GUID} />                    │   → joinSession(GUID)        │
+  │                                          │ <─────────────────────────── │
+  │            ───── WebRTC session active (sessionId = group GUID) ─────   │
+```
+
+| Channel | 1:1 user calls | Group calls |
+|---|---|---|
+| Signaling API | `CometChat.initiateCall(call)` | `CometChat.sendCustomMessage(meetingMessage)` |
+| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` (category=CATEGORY_CUSTOM + type="meeting") |
+| Session ID | server-generated unique per call | the group's GUID (persistent) |
+| Ring/decline | yes — `acceptCall` / `rejectCall` | no — receivers join or ignore |
+| Auto-cancel timeout | yes (45s default) | no — meeting persists in chat history |
+
+**Implication for custom-UI receivers:** if your app doesn't render `<CometChatMessageList group={g}>` (the kit auto-renders meeting cards there), you must register your OWN `MessageListener`:
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+CometChat.addMessageListener(
+  "APP_ROOT_GROUP_MEETING_LISTENER",
+  new CometChat.MessageListener({
+    onCustomMessageReceived: (msg: CometChat.CustomMessage) => {
+      if (msg.getCategory() !== CometChat.CATEGORY_CUSTOM) return;
+      if (msg.getType() !== "meeting") return;
+      const customData = msg.getCustomData() as { callType?: "audio" | "video"; sessionId?: string };
+      const sessionId = customData.sessionId ?? msg.getReceiverId();
+      const callType = customData.callType ?? "video";
+      // Show YOUR custom incoming-meeting UI (toast, badge, or full screen)
+    },
+  }),
+);
+```
+
+**Implication for the `<CometChatIncomingCall />` overlay:** it does NOT fire for group meetings. It only listens on the 1:1 call channel. Custom UI for "incoming group meeting" must be built on top of `onCustomMessageReceived`.
+
+This semantic surfaced on 2026-05-15 when Pixel 3 (kit-based RN) → Angular (custom UI) was tested; Angular received nothing because it only registered `addCallListener`. By design, not a bug.
+
+---
+
+## Initiating a group call
+
+Group calls are tied to a CometChat group — the SDK uses the group's GUID as the session ID:
+
+```ts
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+const group = await CometChat.getGroup(guid);
+
+// initiate a video call to the group
+const call = new CometChat.Call(group.getGuid(), CometChat.CALL_TYPE.VIDEO, CometChat.RECEIVER_TYPE.GROUP);
+const initiated = await CometChat.initiateCall(call);
+
+// All currently-online group members receive an incoming-call notification
+```
+
+Different from 1:1: the receiver is the GROUP, not a single user. Anyone in the group can join via `acceptCall` until the call ends.
+
+---
+
+## Capacity limits
+
+CometChat plan-driven. Common ceilings:
+
+| Plan | Max participants per call |
+|---|---|
+| Free | 5 |
+| Developer | 10 |
+| Production | 25 |
+| Enterprise | configurable up to 100 |
+
+The SDK doesn't reject calls at capacity — it just stops admitting new joiners with `OngoingCallListener.onError` firing on the would-be joiner's side. Surface this to the user:
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onError: (error: { code: string; message: string }) => {
+    if (error.code === "ERR_CALL_FULL") {
+      Alert.alert("Call is full", "This meeting has reached its participant limit.");
+    }
+  },
+});
+```
+
+---
+
+## Roster — who's in the call
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onUserListUpdated: (users: Array<{ uid: string; name: string; avatar?: string }>) => {
+    // Re-render the participant strip
+    setParticipants(users);
+  },
+});
+```
+
+Fires whenever a participant joins or leaves. The roster includes the local user — filter them out of the "remote participants" UI:
+
+```ts
+const localUid = CometChat.getLoggedinUser()?.getUid();
+const remoteParticipants = users.filter((u) => u.uid !== localUid);
+```
+
+---
+
+## Active speaker detection
+
+The SDK fires `onActiveSpeakerUpdated` when the dominant audio source changes:
+
+```ts
+const listener = new CometChatCalls.OngoingCallListener({
+  onActiveSpeakerUpdated: (uid: string) => {
+    setActiveSpeakerUid(uid);
+  },
+});
+```
+
+Use this to drive a "spotlight" layout — large tile for the active speaker, small thumbnails for the rest:
+
+```tsx
+function SpotlightLayout({ participants, activeSpeakerUid }: Props) {
+  const speaker = participants.find((p) => p.uid === activeSpeakerUid) ?? participants[0];
+  const others = participants.filter((p) => p.uid !== speaker?.uid);
+
+  return (
+    <View style={styles.spotlight}>
+      <ParticipantTile participant={speaker} large />
+      <ScrollView horizontal>
+        {others.map((p) => (
+          <ParticipantTile key={p.uid} participant={p} small />
+        ))}
+      </ScrollView>
+    </View>
+  );
+}
+```
+
+**Throttle re-layout** — `onActiveSpeakerUpdated` can fire multiple times per second in a noisy room. Debounce the layout swap to ~500ms minimum, otherwise tiles jitter.
+
+---
+
+## Mute-all / kick / raise hand — moderator actions
+
+These require the local user to be a group **owner** or **moderator** (CometChat group scopes):
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+// Mute a specific participant (moderator action — kicks them off audio)
+async function mutParticipant(uid: string) {
+  await CometChatCalls.muteUser(uid);
+}
+
+// Mute everyone except local user
+async function muteAll() {
+  for (const p of participants) {
+    if (p.uid === localUid) continue;
+    await CometChatCalls.muteUser(p.uid);
+  }
+}
+
+// Kick a participant out of the call
+async function kickParticipant(uid: string) {
+  await CometChatCalls.removeUser(uid);
+}
+
+// Local user "raises hand" — signals to moderator
+async function raiseHand() {
+  await CometChatCalls.raiseHand();
+  // The moderator's onUserRaisedHand listener fires
+}
+```
+
+**Permission check** — call these only if the local user has moderator scope:
+
+```ts
+const localScope = group.getScope();        // "admin" | "moderator" | "participant"
+const canModerate = localScope === "admin" || localScope === "moderator";
+```
+
+Don't render mute-all/kick buttons for non-moderators.
+
+---
+
+## Bandwidth scaling — quality vs participant count
+
+WebRTC mesh topology (every peer connects to every other peer) doesn't scale. CometChat uses an SFU (Selective Forwarding Unit) for group calls — your client uploads one stream, downloads N streams.
+
+Practical bandwidth (per local user, video on):
+
+| Participants | Upload | Download |
+|---|---|---|
+| 2 | 1 Mbps | 1 Mbps |
+| 5 | 1 Mbps | 5 Mbps |
+| 10 | 1 Mbps | 10 Mbps |
+| 25 | 1 Mbps | 25 Mbps |
+
+Mobile networks struggle past 10. The skill recommends:
+
+- Cap default participant count at 10 for mobile-only audiences
+- Auto-disable video for participants beyond the spotlight + 4 most-recent speakers (custom UI)
+- Switch to audio-only mode if the device's battery drops below 20% (`expo-battery` or custom native module)
+
+```ts
+// auto-downgrade to audio-only on low battery
+import * as Battery from "expo-battery";
+
+const level = await Battery.getBatteryLevelAsync();
+if (level < 0.2) {
+  await CometChatCalls.pauseVideo(true);
+  Alert.alert("Battery saver", "Video paused to save battery.");
+}
+```
+
+---
+
+## Joining a group call already in progress
+
+If User A starts the call and the group has 5 members, the other 4 receive an incoming-call notification. But what about User B who logs in DURING the call?
+
+The CometChat backend stores active call state. A joining user can query:
+
+```ts
+const ongoing = await CometChat.getActiveCall();
+if (ongoing && ongoing.getReceiverType() === CometChat.RECEIVER_TYPE.GROUP) {
+  // Show "Join meeting" button — call is in progress
+}
+```
+
+Use this to render a "Join meeting" button on the group screen during an active call. The kit's `CometChatMessageHeader` does this automatically when the group has an active call.
+
+---
+
+## Anti-patterns
+
+1. **Rendering tiles for every participant.** At 25 people, you have 25 `<RTCView />` instances; that's where RN's bridge starts choking. Render the active speaker + max 6 thumbnails.
+2. **Updating layout on every `onActiveSpeakerUpdated`.** Debounce to 500ms minimum.
+3. **Allowing non-moderators to call `muteUser` / `removeUser`.** SDK rejects, but the UI shouldn't expose buttons for it.
+4. **No bandwidth warning.** A user on cellular joining a 10-person call burns their data plan in minutes. Show a "Switch to audio-only" prompt at the threshold.
+5. **Forgetting to filter local user from the roster.** "Speaking with myself" tile.
+6. **Initiating group calls without group membership check.** Non-members get "ERR_NOT_GROUP_MEMBER" silently.
+
+---
+
+## Verification checklist
+
+- [ ] Active-speaker handler debounced (≥500ms)
+- [ ] Roster filters out local user
+- [ ] Moderator buttons hidden for non-moderator scopes
+- [ ] Capacity error surfaces in UI when join fails
+- [ ] Bandwidth warning at participant count threshold (configurable)
+- [ ] Battery-saver downgrade hook (optional, recommended)
+- [ ] `getActiveCall()` checked on group screen mount
+- [ ] Maximum N tiles rendered (clamp + overflow indicator: "+5 more")
+- [ ] Real-device smoke: 5+ participants on real cellular network for 5+ minutes
+
+---
+
+## Pointers
+
+- `references/custom-ui.md` — building custom multi-tile layouts on the SDK
+- `references/recording-screen-share.md` — recording group calls (server-side composition handles the layout)
+- `references/voip-push-end-to-end.md` — push for group call invitations
+- `cometchat-native-calls` SKILL.md — base hard rules

package/skills/cometchat-native-calls/references/idle-timeout.md

@@ -0,0 +1,128 @@
+# Idle timeout on React Native
+
+Same SDK API as web — `setIdleTimeoutPeriodBeforePrompt` + `setIdleTimeoutPeriodAfterPrompt` on CallSettings, `onSessionTimedOut` event. RN-specific deltas are background-handling integration (call doesn't time out while the app is foregrounded; needs special handling in background) and the alert UI surface.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/idle-timeout
+**Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings shape + recommended timeouts per archetype + custom prompt pattern.
+
+---
+
+## SDK API
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+const settings = new CometChatCalls.CallSettingsBuilder()
+  .setSessionID(sessionId)
+  .setIdleTimeoutPeriodBeforePrompt(60_000)
+  .setIdleTimeoutPeriodAfterPrompt(120_000)
+  .build();
+
+CometChatCalls.addEventListener("onSessionTimedOut", () => {
+  navigation.navigate("Home");
+  Alert.alert("Call ended", "You were inactive for too long");
+});
+```
+
+---
+
+## RN-specific: app state + idle interaction
+
+**Background gotcha:** when the user backgrounds your app while the call is active, the idle timer keeps running. From the user's perspective, they backgrounded for 30s and came back to a "you've been timed out" screen. Bad UX.
+
+Pause the timer when the app backgrounds:
+
+```ts
+import { AppState } from "react-native";
+
+useEffect(() => {
+  const sub = AppState.addEventListener("change", (state) => {
+    if (state === "active") {
+      // App came back to foreground — reset alone-since timer
+      // (Without SDK API to pause; reconfigure call settings is the workaround)
+    } else if (state === "background") {
+      // Pause your custom timer (Pattern A in the web ref)
+    }
+  });
+  return () => sub.remove();
+}, []);
+```
+
+If you're using the kit's default idle prompt UI, this is harder — kit doesn't expose a "pause timer" API. Use Pattern B from the web ref (long SDK timeouts + custom prompt + custom timer that respects AppState).
+
+---
+
+## Custom prompt — Alert vs Modal
+
+`Alert.alert` is OS-native but blocks the call UI fully:
+
+```ts
+useEffect(() => {
+  if (!showPrompt) return;
+  const subscription = Alert.alert(
+    "Still there?",
+    "You're alone in this call. It'll end in 60 seconds.",
+    [
+      { text: "Stay", onPress: dismiss, style: "cancel" },
+      { text: "End now", onPress: () => CometChatCalls.leaveSession(), style: "destructive" },
+    ],
+    { cancelable: false },
+  );
+}, [showPrompt]);
+```
+
+`Modal` lets you keep the call surface visible:
+
+```tsx
+<Modal
+  visible={showPrompt}
+  transparent
+  animationType="fade"
+  onRequestClose={dismiss}
+>
+  <View style={styles.overlay}>
+    <View style={styles.dialog} accessible accessibilityRole="alert">
+      <Text style={styles.title}>Still there?</Text>
+      <Text>You're alone in this call. It'll end in 60 seconds.</Text>
+      <View style={styles.row}>
+        <TouchableOpacity onPress={dismiss}><Text>Stay</Text></TouchableOpacity>
+        <TouchableOpacity onPress={() => CometChatCalls.leaveSession()}>
+          <Text style={{ color: "red" }}>End now</Text>
+        </TouchableOpacity>
+      </View>
+    </View>
+  </View>
+</Modal>
+```
+
+`accessibilityRole="alert"` is the RN equivalent of web's `role="alertdialog"`. TalkBack / VoiceOver pause to announce.
+
+---
+
+## Anti-patterns
+
+Web sister reference rules apply, plus RN-specific:
+
+1. **Idle timer running during background.** User backgrounds, comes back to "timed out." Pause via AppState listener.
+2. **Using `Alert.alert` inside `useEffect`.** Blocks the call surface; can stack multiple alerts on rapid state changes. Use `Modal` for in-call UI.
+3. **Forgetting `Modal` `accessible accessibilityRole="alert"`.** Screen readers miss the announcement.
+
+---
+
+## Verification checklist
+
+- [ ] CallSettings sets both idle periods
+- [ ] `onSessionTimedOut` navigates user away cleanly
+- [ ] Custom prompt uses `Modal` with `accessibilityRole="alert"`, OR `Alert.alert` for OS-native
+- [ ] AppState listener pauses custom timer on `background`
+- [ ] Real-device smoke: backgroound app for 30s, return → call still active (timer paused correctly)
+- [ ] Real-device smoke: 2 devices, hangup from one → timer fires on the other after configured delay
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/idle-timeout.md` — sister reference (settings, archetype timeouts, custom prompt pattern)
+- `cometchat-native-calls` SKILL.md
+- `references/voip-push-end-to-end.md` — interaction with VoIP push (background-mode call activation)
+- Canonical docs: https://www.cometchat.com/docs/calls/react-native/idle-timeout

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

@@ -0,0 +1,143 @@
+# In-call chat on React Native
+
+Same SDK API as web. RN-specific: BottomSheet panel UX (matches mobile patterns) + `Keyboard.dismiss()` lifecycle awareness when entering call.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/in-call-chat
+**Read first:** `cometchat-react-calls/references/in-call-chat.md` — group-as-session architecture + UX patterns + the four anti-patterns.
+
+---
+
+## SDK API
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+const settings = new CometChatCalls.CallSettingsBuilder()
+  .setSessionID(sessionId)
+  .hideChatButton(false)
+  .build();
+
+CometChatCalls.addEventListener("onChatButtonClicked", () => setOpen(true));
+CometChatCalls.setChatButtonUnreadCount(5);
+```
+
+Same as web. The group-as-session pattern (using a group with GUID == sessionID) carries over.
+
+---
+
+## BottomSheet panel — RN canonical UX
+
+```tsx
+import BottomSheet, { BottomSheetView } from "@gorhom/bottom-sheet";
+import { useRef, useEffect, useState } from "react";
+import { View, TextInput, TouchableOpacity, Text } from "react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+import {
+  CometChatMessageList,
+  CometChatMessageComposer,
+} from "@cometchat/chat-uikit-react-native";
+
+interface Props { sessionId: string; }
+
+function InCallChatSheet({ sessionId }: Props) {
+  const sheetRef = useRef<BottomSheet>(null);
+  const [group, setGroup] = useState<CometChat.Group>();
+  const [unread, setUnread] = useState(0);
+
+  useEffect(() => {
+    const handler = () => sheetRef.current?.snapToIndex(1);
+    CometChatCalls.addEventListener("onChatButtonClicked", handler);
+    return () => CometChatCalls.removeEventListener("onChatButtonClicked", handler);
+  }, []);
+
+  useEffect(() => {
+    CometChat.getGroup(sessionId).then(setGroup).catch(() => {});
+  }, [sessionId]);
+
+  // Track unread + clear on open (same logic as web; cite sister)
+  // ...
+
+  if (!group) return null;
+
+  return (
+    <BottomSheet
+      ref={sheetRef}
+      snapPoints={["10%", "75%"]}
+      index={-1}                                 // start closed
+      onChange={(i) => {
+        if (i >= 1) {
+          setUnread(0);
+          CometChatCalls.setChatButtonUnreadCount(0);
+        }
+      }}
+    >
+      <BottomSheetView style={{ flex: 1 }}>
+        {/* flex-1 + minHeight:0 wrap pattern still applies on RN */}
+        <View style={{ flex: 1, minHeight: 0 }}>
+          <CometChatMessageList group={group} hideReplyInThreadOption />
+        </View>
+        <CometChatMessageComposer group={group} />
+      </BottomSheetView>
+    </BottomSheet>
+  );
+}
+```
+
+`@gorhom/bottom-sheet` is already a peer dep of the kit when RN calls are integrated (via `react-native-gesture-handler` + `react-native-reanimated`).
+
+---
+
+## Keyboard handling
+
+When the chat sheet opens, the user types — keyboard appears, pushes call surface up. Two options:
+
+### A — Use `KeyboardAvoidingView`
+
+```tsx
+<KeyboardAvoidingView
+  behavior={Platform.OS === "ios" ? "padding" : "height"}
+  style={{ flex: 1 }}
+>
+  <BottomSheet ...>
+    {/* ... */}
+  </BottomSheet>
+</KeyboardAvoidingView>
+```
+
+### B — Use `keyboardVerticalOffset` from BottomSheet
+
+Most BottomSheet libs have explicit keyboard handling. `@gorhom/bottom-sheet` v4+ ships `keyboardBehavior` and `keyboardBlurBehavior` options.
+
+Critical: ensure the call's WebRTC video doesn't reflow when keyboard opens (already covered by `resizeToAvoidBottomInset: false` rule for iOS; on Android use `android:windowSoftInputMode="adjustNothing"` in the manifest for the call activity).
+
+---
+
+## Anti-patterns
+
+Web sister rules apply, plus RN-specific:
+
+1. **Default `windowSoftInputMode="adjustResize"`** on Android. Keyboard appears, the entire screen resizes — call's WebRTC view squishes, looks broken.
+2. **`@gorhom/bottom-sheet` outside `GestureHandlerRootView`.** Sheet doesn't respond to drag gestures. Wrap your app's root in `GestureHandlerRootView` (also a kit requirement; see `cometchat-native-calls` SKILL.md).
+3. **Chat sheet fullscreen by default.** Hides the call view; participants can't see who's talking. Default to ~30% snap, expand on demand.
+
+---
+
+## Verification checklist
+
+- [ ] `@gorhom/bottom-sheet` in deps
+- [ ] `GestureHandlerRootView` wraps the app
+- [ ] BottomSheet has 2+ snap points (peek + expanded)
+- [ ] AndroidManifest: call activity has `windowSoftInputMode="adjustNothing"` or `"adjustPan"`
+- [ ] iOS Scaffold: `resizeToAvoidBottomInset: false` (RN's equivalent: KeyboardAvoidingView with right behavior)
+- [ ] Real-device smoke: keyboard opens during chat, call view doesn't reflow
+- [ ] Real-device smoke: 2 devices in call, send message from one → badge appears in other
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/in-call-chat.md` — sister web reference (group-as-session pattern)
+- `cometchat-native-calls` SKILL.md — the seven hard rules
+- `cometchat-android-v5-calls/references/in-call-chat.md` — Android V5 sibling
+- Canonical docs: https://www.cometchat.com/docs/calls/react-native/in-call-chat

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

@@ -0,0 +1,72 @@
+# Calls SDK v4 → v5 migration (React Native)
+
+`@cometchat/calls-sdk-react-native@5` is a drop-in replacement for v4. Same migration shape as web; RN deltas focus on the native modules that calls SDK depends on.
+
+**Read first:** `cometchat-react-calls/references/migration-v4-to-v5.md` — canonical step-by-step (init, login, settings, events, methods).
+
+---
+
+## Step 1 — Bump the package + native modules
+
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+cd ios && pod install
+```
+
+If you upgraded `react-native-webrtc` along with the calls SDK, run:
+
+```bash
+# iOS
+cd ios && rm -rf Pods Podfile.lock && pod install
+# Android (Gradle handles it on next build)
+```
+
+---
+
+## Step 2 — Verify native dependencies are still valid
+
+Calls SDK v5 doesn't change the native module list, but versions matter. Check `package.json`:
+
+```json
+{
+  "dependencies": {
+    "@cometchat/calls-sdk-react-native": "^5.0.0",
+    "react-native-webrtc": ">=124",
+    "react-native-incall-manager": ">=4",
+    "react-native-callstats": ">=3",
+    "@react-native-community/netinfo": "*"
+  }
+}
+```
+
+If any of these are stale, calls may fail silently with WebRTC negotiation errors.
+
+---
+
+## Migration steps (same as web)
+
+1. Migrate init to plain object
+2. Add `CometChatCalls.login(authToken)` after `CometChat.login`
+3. Replace `CallSettingsBuilder` with plain `sessionSettings` object — **watch inverted booleans** (`show*` → `hide*`)
+4. Replace `OngoingCallListener` with `addEventListener` calls
+5. Rename methods: `endSession` → `leaveSession`, `startSession` → `joinSession`, `setMode` → `setLayout`
+6. Cleanup: `addEventListener` returns an unsubscribe — call it on unmount
+
+---
+
+## Verification checklist
+
+- [ ] All canonical steps from `cometchat-react-calls/references/migration-v4-to-v5.md`
+- [ ] `pod install` re-run after upgrade
+- [ ] Native modules at compatible versions
+- [ ] Real-device test: 2 phones (iOS + Android), incoming call, mute, screen-share, end
+- [ ] CallKeep + VoipPushNotification still register tokens correctly
+- [ ] Background incoming call (recipient app killed) still rings
+
+---
+
+## Pointers
+
+- Canonical migration: `cometchat-react-calls/references/migration-v4-to-v5.md`
+- `cometchat-native-calls/SKILL.md` — RN seven hard rules
+- https://www.cometchat.com/docs/calls/react-native/migration-guide-v5