@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-ios-troubleshooting/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-ios-troubleshooting
 description: "Diagnose and fix common CometChat iOS integration issues — build errors, runtime errors, and debugging techniques."
 license: "MIT"
 compatibility: "CometChatUIKitSwift ^5; iOS 13+"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat ios troubleshooting debugging errors fixes"
 ---
 
+> **Ground truth:** `CometChatUIKitSwift ~> 5` (+ `CometChatCallsSDK ~> 5`) — Pods/SPM `.swiftinterface` + `ui-kit/ios`. **Official docs:** https://www.cometchat.com/docs/ui-kit/ios/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 This skill helps diagnose and fix common issues when integrating CometChat iOS UI Kit. It covers build errors, runtime errors, and debugging techniques.
@@ -76,7 +77,7 @@ pod 'CometChatSDK', '~> 4.0'  # Add explicitly if needed
 1. **If you need calls:**
 ```ruby
 # Podfile
-pod 'CometChatCallsSDK', '~> 4.0'
+pod 'CometChatCallsSDK', '~> 5.0'
 ```
 
 2. **If you don't need calls:**
@@ -116,6 +117,7 @@ case .onError(let error):
 **Solution:** `CometChatException` does NOT conform to Swift's `Error` protocol. Don't use `Result<T, Error>` with CometChat callbacks. Instead, use direct callbacks:
 
 ```swift
+// tier2-expect-error — this block intentionally demonstrates the compile error below
 // ❌ WRONG - Don't use Result<T, Error>
 func login(completion: @escaping (Result<User, Error>) -> Void) {
     CometChatUIKit.login(uid: uid) { result in
@@ -182,7 +184,7 @@ See `cometchat-ios-components` § 13 ("Custom MessagesVC Implementation") for th
 1. **Install the Calls SDK:**
 ```ruby
 # Podfile
-pod 'CometChatCallsSDK', '~> 4.0'
+pod 'CometChatCallsSDK', '~> 5.0'
 ```
 
 2. **Or wrap in conditional compilation:**
@@ -413,12 +415,12 @@ if let user = CometChatUIKit.getLoggedInUser() {
 3. **Check for errors:**
 ```swift
 let conversations = CometChatConversations()
-conversations.onError = { error in
+conversations.set(onError: { error in
     print("Error loading conversations: \(error.errorDescription ?? "")")
-}
-conversations.onEmpty = {
+})
+conversations.set(onEmpty: {
     print("No conversations found")
-}
+})
 ```
 
 ---
@@ -437,9 +439,9 @@ composer.set(user: user)  // Must be set!
 
 2. **Check for errors:**
 ```swift
-composer.onError = { error in
-    print("Composer error: \(error.errorDescription ?? "")")
-}
+composer.set(onError: { error in
+    print("Composer error: \((error as? CometChatException)?.errorDescription ?? "")")
+})
 ```
 
 3. **Verify network connection:**
@@ -503,7 +505,7 @@ func application(_ application: UIApplication, didRegisterForRemoteNotifications
 
 1. **CometChatCallsSDK installed?**
 ```ruby
-pod 'CometChatCallsSDK', '~> 4.0'
+pod 'CometChatCallsSDK', '~> 5.0'
 ```
 
 2. **Permissions in Info.plist?**
@@ -520,6 +522,16 @@ pod 'CometChatCallsSDK', '~> 4.0'
 
 4. **Testing on real device?** Calls don't work on simulator
 
+5. **Did you call `CometChatCalls.login(...)`?** ⚠️ **On iOS there is NO `CometChatCalls.login`** — the iOS `CometChatCallsSDK` has no `login`/`joinSession`/`SessionSettingsBuilder`. The authority is the vendored `CometChatCallsSDK.swiftinterface` (`generateToken` / `startSession` / `CallSettingsBuilder` / `CallsEventsDelegate`). The `calls-sdk-ios` repo's own `skills/` describe a *different* API and will mislead you — don't follow them. Default calling works through the UI Kit (`CometChatUIKit` calling-enabled) without a separate calls login; for custom calling, use `generateToken` → `startSession`.
+
+### Background push for calls not arriving (Privacy manifest / APNs vs FCM)
+
+**Cause:** Missing privacy manifest, or an APNs-vs-FCM provider mismatch.
+
+**Fix:**
+- Add a **`PrivacyInfo.xcprivacy`** privacy manifest to the app target (required by App Store review; its absence can also break some push/SDK behaviors).
+- Match the **provider** to your token type: if you registered an **APNs** device/VoIP token, the dashboard provider must be **APNs** (`.p8` + Team ID + Key ID, dev-vs-prod environment matching the build); if you route iOS through **FCM**, register with the FCM provider and the `FCM_IOS` platform. A token registered against the wrong provider silently never delivers. See `cometchat-ios-push`.
+
 ---
 
 ### Memory Warnings / Crashes
@@ -530,9 +542,9 @@ pod 'CometChatCallsSDK', '~> 4.0'
 
 1. **Use weak references in closures:**
 ```swift
-conversations.onItemClick = { [weak self] conversation, _ in
+conversations.set(onItemClick: { [weak self] conversation, _ in
     self?.openMessages(for: conversation)
-}
+})
 ```
 
 2. **Remove listeners when done:**
@@ -573,11 +585,19 @@ CometChatUIKit.login(uid: "user-123") { result in
 
 ## 3. Debugging Techniques
 
-### Enable CometChat Logging
+### Inspect SDK errors
+
+The CometChat iOS SDK has **no public log-level API** (there is no
+`CometChat.setLogLevel` / `AppSettingsBuilder` logging toggle). Diagnose by
+reading the `CometChatException` handed to each call's `onError` closure:
 
 ```swift
-// Add before initialization
-CometChat.setLogLevel(.debug)
+CometChat.init(appId: appID, appSettings: settings, onSuccess: { _ in
+    print("CometChat init OK")
+}, onError: { error in
+    // CometChatException → code + message (init's onError is non-optional)
+    print("init failed:", error.errorCode, error.errorDescription)
+})
 ```
 
 ### Check Connection Status
@@ -640,7 +660,7 @@ Use Charles Proxy or Proxyman to inspect CometChat API calls:
 ```swift
 // Print current state
 print("User: \(CometChatUIKit.getLoggedInUser()?.uid ?? "none")")
-print("Initialized: \(CometChatManager.shared.isInitialized)")
+print("Logged in: \(CometChatUIKit.getLoggedInUser() != nil)")
 ```
 
 ---
@@ -670,7 +690,7 @@ print("Initialized: \(CometChatManager.shared.isInitialized)")
 1. **Limit initial fetch:**
 ```swift
 let conversations = CometChatConversations()
-conversations.set(conversationsRequestBuilder: ConversationsRequest.ConversationsRequestBuilder()
+conversations.set(conversationsRequestBuilder: ConversationRequest.ConversationRequestBuilder()
     .set(limit: 20)  // Reduce initial load
 )
 ```
@@ -740,9 +760,9 @@ struct ConversationsWrapper: UIViewControllerRepresentable {
     
     func makeUIViewController(context: Context) -> CometChatConversations {
         let vc = CometChatConversations()
-        vc.onItemClick = { conversation, _ in
+        vc.set(onItemClick: { conversation, _ in
             selectedConversation = conversation
-        }
+        })
         return vc
     }
     
@@ -790,7 +810,7 @@ When something isn't working:
 7. [ ] **Check permissions:** Camera, microphone, notifications
 8. [ ] **Check main thread:** UI updates on main thread
 9. [ ] **Check completion handlers:** Wait for async operations
-10. [ ] **Enable logging:** `CometChat.setLogLevel(.debug)`
+10. [ ] **Inspect errors:** read the `CometChatException` in each call's `onError` (`errorCode` + `errorDescription`) — the SDK has no log-level toggle
 
 ---
 

package/skills/cometchat-native-bare-patterns/SKILL.md

@@ -3,7 +3,6 @@ name: cometchat-native-bare-patterns
 description: "Integration patterns for bare React Native CLI projects — pod install, Info.plist + AndroidManifest permissions, Apple privacy manifest, native module linking, Metro config."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.77; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -24,7 +23,7 @@ Teaches Claude how to integrate CometChat into a bare React Native CLI project.
 
 **Read `cometchat-native-core` first** (init/login/wrapper chain + anti-patterns), then `cometchat-native-components`, then `cometchat-native-placement`.
 
-Ground truth: `docs/ui-kit/react-native/react-native-cli-integration.mdx`, `apple-privacy-manifest-guide.mdx`, `react-native-conversation.mdx` + `react-native-one-to-one-chat.mdx` + `react-native-tab-based-chat.mdx`, and `examples/SampleApp/`.
+Ground truth: `docs/ui-kit/react-native/react-native-cli-integration.mdx`, `apple-privacy-manifest-guide.mdx`, `react-native-conversation.mdx` + `react-native-one-to-one-chat.mdx` + `react-native-tab-based-chat.mdx`, and `examples/SampleApp/`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react-native/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 
 ---
 
@@ -58,7 +57,8 @@ Ground truth: `docs/ui-kit/react-native/react-native-cli-integration.mdx`, `appl
 npm install @cometchat/chat-sdk-react-native
 npm install @cometchat/chat-uikit-react-native
 
-# Required peer deps (natively linked)
+# Natively-linked deps used by the kit + sample apps. (datetimepicker isn't a
+# declared kit peer, but every shipped sample installs it — keep it for parity.)
 npm install \
   @react-native-async-storage/async-storage \
   @react-native-clipboard/clipboard \
@@ -75,6 +75,17 @@ npm install dayjs punycode
 
 Bare RN uses autolinking, so no `react-native link` step is needed. Just confirm everything installed cleanly — if `npm install` errored mid-way, native modules won't be wired up correctly.
 
+> ⚠️ **RN 0.85+ build trap — `react-native-document-picker` v9.x breaks the Android build (ENG-35701).** The unmaintained `react-native-document-picker@9.3.1` references `GuardedResultAsyncTask`, which React Native removed in 0.85.0. If the kit pulls it in transitively (or you add it for file uploads), `:react-native-document-picker:compileDebugJavaWithJavac` fails with `cannot find symbol class GuardedResultAsyncTask`. **Swap to `@react-native-documents/document-picker` (bare RN) or `expo-document-picker` (Expo):**
+>
+> ```bash
+> # Bare RN (the maintained fork)
+> npm uninstall react-native-document-picker
+> npm install @react-native-documents/document-picker
+> cd ios && pod install && cd ..
+> ```
+>
+> Then in code, `import { pick } from '@react-native-documents/document-picker'` instead of the default export. The API surface is similar — `pick({ type: ['*/*'] })` returns a `Promise<DocumentPickerResult[]>`. See `cometchat-native-troubleshooting` §3bb for the full migration matrix.
+
 ### Optional — calling SDK
 
 Only if the user's flow includes voice / video calls:
@@ -85,9 +96,14 @@ npm install \
   @react-native-community/netinfo \
   react-native-background-timer \
   react-native-callstats \
-  react-native-webrtc
+  react-native-webrtc \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 ```
 
+> **`react-native-url-polyfill`, `react-native-performance`, and `valibot` are not in the calls-sdk `peerDependencies` array** — but the calls-sdk's `dist/polyfills/browser.js` imports them at module top, so Metro fails the bundle without them. Omitting any of the three yields `Unable to resolve module …` at startup with no app render. (Validated 2026-05-26 on `@cometchat/calls-sdk-react-native@5.0.0`.)
+
 WebRTC bloats the binary. Skip until the user actually wants calls.
 
 ---
@@ -231,9 +247,9 @@ Open `android/app/src/main/AndroidManifest.xml` and add inside `<manifest>` (bef
 
 **Merge, don't replace.** Keep the user's existing permissions for other libraries.
 
-### 3b. Android: async-storage Maven repo (REQUIRED)
+### 3b. Android: async-storage Maven repo (ONLY if you use async-storage v3+)
 
-`@react-native-async-storage/async-storage` v3+ ships a **local Maven artifact** that autolinking can't find by default. Without this fix, `./gradlew assembleDebug` fails with:
+⚠️ **Conditional — not part of the default build.** The kit does NOT pin async-storage, and the shipped sample apps use `@react-native-async-storage/async-storage@^2.2.0` (which needs none of this). This step applies **only if you opt into async-storage v3+**, whose **local Maven artifact** autolinking can't find by default — then `./gradlew assembleDebug` fails with:
 
 ```
 Could not find :react-native-async-storage_async-storage: on any of the paths.
@@ -254,7 +270,9 @@ allprojects {
 }
 ```
 
-Without this fix, the whole Android build fails early. This is a UI Kit-specific gotcha because the kit pins async-storage v3+.
+Without this fix, an async-storage-v3+ Android build fails early. (On the default async-storage v2.2.0 — what the samples ship — this isn't needed.)
+
+> **Known issue (F78) — chat-sdk 4.0.22 breaks bare RN at runtime.** Separate from the build-time Maven error above: `@cometchat/chat-sdk-react-native@4.0.22` declares `react-native@0.64.2` + async-storage as **hard deps** (4.0.21 had none), so npm installs a nested duplicate react-native inside the SDK. The app builds fine but crashes at JS startup with `Cannot read property 'CometChatThemeProvider' of undefined` (AsyncStorage native module mismatch). **Expo is unaffected.** Fix: add npm `overrides` to dedupe, or pin `@cometchat/chat-sdk-react-native@4.0.21`. Full root cause + exact `overrides` block in `cometchat-native-troubleshooting` §3bc. Tracked in ENG-35653.
 
 ### 3c. Android: Metro config for custom fonts or assets (if applicable)
 
@@ -292,8 +310,8 @@ AppRegistry.registerComponent(appName, () => App);
 // App.tsx
 import React from "react";
 import { GestureHandlerRootView } from "react-native-gesture-handler";
-import { SafeAreaProvider } from "react-native-safe-area-context";
-import { CometChatThemeProvider } from "@cometchat/chat-uikit-react-native";
+import { SafeAreaProvider, SafeAreaView } from "react-native-safe-area-context";
+import { CometChatThemeProvider, CometChatI18nProvider } from "@cometchat/chat-uikit-react-native";
 import { CometChatProvider } from "./src/providers/CometChatProvider";
 import { AppNavigator } from "./src/navigation/AppNavigator";
 import Config from "react-native-config";  // or read from an env source
@@ -303,14 +321,18 @@ export default function App() {
     <GestureHandlerRootView style={{ flex: 1 }}>
       <SafeAreaProvider>
         <CometChatThemeProvider>
-          <CometChatProvider
-            appId={Config.COMETCHAT_APP_ID!}
-            region={Config.COMETCHAT_REGION!}
-            authKey={Config.COMETCHAT_AUTH_KEY!}
-            uid="cometchat-uid-1"   // dev mode only
-          >
-            <AppNavigator />
-          </CometChatProvider>
+          <CometChatI18nProvider>
+            <CometChatProvider
+              appId={Config.COMETCHAT_APP_ID!}
+              region={Config.COMETCHAT_REGION!}
+              authKey={Config.COMETCHAT_AUTH_KEY!}
+              uid="cometchat-uid-1"   // dev mode only
+            >
+              <SafeAreaView edges={["top", "bottom"]} style={{ flex: 1 }}>
+                <AppNavigator />
+              </SafeAreaView>
+            </CometChatProvider>
+          </CometChatI18nProvider>
         </CometChatThemeProvider>
       </SafeAreaProvider>
     </GestureHandlerRootView>
@@ -318,7 +340,7 @@ export default function App() {
 }
 ```
 
-The `CometChatProvider` itself lives in `src/providers/CometChatProvider.tsx` per `cometchat-native-core` § 6 — reuse that implementation.
+The provider chain matches the kit sample app (`examples/SampleApp/App.tsx`): `CometChatI18nProvider` sits inside `CometChatThemeProvider`, and a root `SafeAreaView edges={["top", "bottom"]}` wraps the navigator. The `CometChatProvider` itself lives in `src/providers/CometChatProvider.tsx` per `cometchat-native-core` § 6 — reuse that implementation.
 
 ---
 
@@ -510,3 +532,19 @@ Use Expo + `npx expo prebuild` to generate native projects on demand. Stay on `c
 | `cometchat-native-customization` | Text formatters, events, custom views |
 | `cometchat-native-production` | Server-side auth tokens + user management |
 | `cometchat-native-troubleshooting` | pod install fails, build errors, missing modules, privacy manifest rejection |
+
+## Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the bare RN recipe diverges from the standard provider chain. Skills runs `cometchat builder export --platform react-native --json` to emit `src/config/{store.ts, config.json}` (the Zustand-backed config store + 7-field envelope JSON), then patches `App.tsx` with `useConfig` + theme derivation.
+
+**Full recipe lives in `cometchat-native-core` §"Visual Builder integration".** Bare RN-specific notes:
+
+- No `npx expo install` — install deps via `npm install` and pin manually. The 11 explicit peer-dep list applies in full (see §"Mandatory peer deps").
+- Env via `react-native-dotenv` Babel plugin — the standard bare-RN convention. Add `[['module:react-native-dotenv']]` to `babel.config.js` plugins. Import via `import { COMETCHAT_APP_ID, COMETCHAT_REGION, COMETCHAT_AUTH_KEY } from "@env"`. Add a `src/env.d.ts` type declaration so TS recognizes the `@env` module.
+- Required additional deps: `zustand`, `@react-native-async-storage/async-storage`, plus the standard 11 peers from §"Mandatory peer deps".
+- `useConfig(s => s.settings.style)` — note the selector takes `AppConfig` directly, NOT `s.config.settings.style` (Finding F6, 2026-05-21).
+- Envelope is `settings: { chatFeatures, callFeatures, layout, style, noCode }` — theme tokens live under `settings.style` (there's no `settings.theme`/`settings.agent`); the engagement feature group is `chatFeatures.deeperUserEngagement` (not `deeperEngagement`). See core §"Feature flag access".
+- The reference builder app wires gesture-handler as a top-of-file side-effect import (`import './gesture-handler';`), not a `<GestureHandlerRootView>` wrapper; its provider chain is `SafeAreaProvider → SafeAreaView → CometChatThemeProvider → CometChatI18nProvider`. The general bare provider chain above (with `GestureHandlerRootView`) is also valid — see core §"Visual Builder integration" for the reference-matched template.
+- iOS host: run `cd ios && pod install` after the deps land. B6 smoke validated: Metro bundles 4.6 MB iOS bundle clean on RN 0.81.5 + React 19.1.0.
+
+If the customer picks **In code**, ignore this section — the standard four-wrapper chain + provider pattern applies.

package/skills/cometchat-native-calls/SKILL.md

@@ -3,7 +3,6 @@ name: cometchat-native-calls
 description: CometChat Calls SDK integration for React Native (Expo managed + bare CLI). Covers @cometchat/calls-sdk-react-native install, dual-SDK init, native module linking (iOS pods, Android Gradle), VoIP push via react-native-callkeep + react-native-voip-push-notification + @react-native-firebase/messaging, CallKit on iOS / ConnectionService on Android, foreground service correctness on Android 14+, gesture handler + reanimated peer deps, Expo-specific config plugins, and additive-vs-standalone modes.
 license: "MIT"
 compatibility: "React Native >= 0.70 (>= 0.72 recommended), Expo SDK >= 49 (managed) / bare RN CLI; @cometchat/calls-sdk-react-native ^4.x; @cometchat/chat-sdk-react-native ^4.x; @cometchat/chat-uikit-react-native ^5.x (additive mode)"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
@@ -23,17 +22,19 @@ Production-grade voice + video calling for React Native (Expo managed + bare CLI
 - Framework path: `cometchat-native-expo-patterns` (managed) OR `cometchat-native-bare-patterns` (CLI)
 
 **Ground truth:**
-- SDK source — `~/Downloads/calls-sdk/calls-sdk-react-native-5/package/`
-- Sample app — `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/`
+- SDK source — `calls-sdk-react-native-5/package/`
+- Sample app — `calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/`
 - Public docs — https://www.cometchat.com/docs/calls/react-native/overview
 
 ---
 
 ## 1. Hard rules — RN specialization
 
-### 1.0 Calls SDK login is its own step (v5+)
+### 1.0 Calls SDK login — only the STANDALONE/raw-SDK path needs it
 
-The v5 Calls SDK has its own auth state, separate from the Chat SDK. After `CometChat.login(uid, AUTH_KEY)` succeeds, you MUST also call `await CometChatCalls.login(uid, AUTH_KEY)` — without it, the FIRST calls API call (`initiateCall`, `joinSession`, `generateToken`) throws **"auth token cannot be null"**. The chat skill's "login once, persist forever" pattern does NOT transfer.
+> ✅ **The additive UI-Kit path does NOT call `CometChatCalls.login`.** When calls are layered onto the RN UI Kit (the common case — `<CometChatIncomingCall>` at root + the auto call buttons in `CometChatMessageHeader`, calling extension enabled at `CometChatUIKit.init`), the kit chains the Calls-SDK auth off `CometChatUIKit.login` for you. **The canonical RN SampleApp wires calls end-to-end (incoming/outgoing/ongoing) with ZERO `CometChatCalls.login`** (verified across `examples/SampleApp` + `SampleAppWithPushNotifications`; the kit's `CometChatUIKit.login` only runs `CometChat.login`). Don't add it on the UI-Kit path — it's redundant.
+
+**`await CometChatCalls.login(uid, AUTH_KEY)` is required ONLY on the STANDALONE / raw-Calls-SDK path** (§4a/§4b — no UI Kit; you call `CometChatCalls.generateToken` / render a custom call surface directly). There the Calls SDK has its own auth state: after `CometChat.login(uid, AUTH_KEY)` succeeds, also call `await CometChatCalls.login(uid, AUTH_KEY)` — without it the first raw calls API throws **"auth token cannot be null"**. (No imperative `joinSession` on RN — see rule below.)
 
 ```ts
 import { CometChat } from "@cometchat/chat-sdk-react-native";
@@ -133,9 +134,76 @@ Required:
 - Android — runtime requests via `PermissionsAndroid.requestMultiple` for `RECORD_AUDIO`, `CAMERA`, `POST_NOTIFICATIONS` (Android 13+)
 - Expo managed — declare in `app.json` `expo.ios.infoPlist` and `expo.android.permissions`; the prebuild merges into native manifests
 
-### 1.7 IncomingCall mounted at app root
+### 1.7 IncomingCall + OutgoingCall + OngoingCall — full event-listener wiring
+
+`<CometChatIncomingCall />`, `<CometChatOutgoingCall />`, and `<CometChatOngoingCall />` are **NOT auto-mounted by each other**. The parent component must register both `CometChat.addCallListener` (SDK socket) and `CometChatUIEventHandler.addCallListener` (UI events fired by `<CometChatCallButtons>` / `<CometChatMessageHeader>`), then conditionally render whichever overlay matches current state. Validated 2026-05-26 on Pixel 3 + `@cometchat/chat-uikit-react-native@5.3.5`.
+
+Mount this wiring inside the root navigator OR in the App.tsx wrapper, ABOVE all stacks/tabs — calls only ring on screens where the listener exists.
+
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+import {
+  CometChatIncomingCall,
+  CometChatOutgoingCall,
+  CometChatOngoingCall,
+  CometChatUIEventHandler,
+} from "@cometchat/chat-uikit-react-native";
+import { StyleSheet, View } from "react-native";
+
+const CALL_LISTENER_ID = "app-call-listener";
+
+function CallSurfaces() {
+  const [outgoingCall, setOutgoingCall] = useState<CometChat.Call | null>(null);
+  const [incomingCall, setIncomingCall] = useState<CometChat.Call | null>(null);
+  const [ongoingCall, setOngoingCall] = useState<CometChat.Call | null>(null);
+
+  useEffect(() => {
+    // SDK socket — incoming + outgoing-rejected
+    CometChat.addCallListener(
+      CALL_LISTENER_ID,
+      new CometChat.CallListener({
+        onIncomingCallReceived: (call: CometChat.Call) => setIncomingCall(call),
+        onIncomingCallCancelled: () => setIncomingCall(null),
+        onOutgoingCallAccepted: () => {},
+        onOutgoingCallRejected: () => setOutgoingCall(null),
+      })
+    );
+    // UI events fired by the kit's CallButtons / MessageHeader on tap
+    CometChatUIEventHandler.addCallListener(CALL_LISTENER_ID, {
+      ccOutgoingCall: ({ call }) => setOutgoingCall(call),
+      ccCallEnded: () => {
+        setOutgoingCall(null);
+        setIncomingCall(null);
+        setOngoingCall(null);
+      },
+      ccShowOngoingCall: ({ call }) => setOngoingCall(call),
+    });
+    // Mid-call drops (peer left, network loss, server close) do NOT come through the
+    // Chat-SDK/UI-Kit channels above — they fire on the Calls SDK session events (v5).
+    // For a STANDALONE custom call surface, also register (clone skills/event-listeners):
+    //   const offLeft   = CometChatCalls.addEventListener('onSessionLeft',     () => { /* reset state */ });
+    //   const offClosed = CometChatCalls.addEventListener('onConnectionClosed', () => { /* reset state */ });
+    //   // addEventListener returns an unsubscribe fn — call offLeft()/offClosed() on cleanup.
+    // (Additive mode using the kit's <CometChatOngoingCall> handles this internally.)
+    return () => {
+      CometChat.removeCallListener(CALL_LISTENER_ID);
+      CometChatUIEventHandler.removeCallListener(CALL_LISTENER_ID);
+    };
+  }, []);
+
+  return (
+    <>
+      {incomingCall && <View style={StyleSheet.absoluteFill}><CometChatIncomingCall call={incomingCall} onDecline={() => setIncomingCall(null)} /></View>}{/* onDecline is REQUIRED on the RN kit's CometChatIncomingCall (onAccept/onError optional) */}
+      {outgoingCall && <View style={StyleSheet.absoluteFill}><CometChatOutgoingCall call={outgoingCall} /></View>}
+      {/* CometChatOngoingCall has NO `call` prop — it takes sessionID (required) + callSettingsBuilder (required) + onError? (verified vs uikit-react-native-v5 CometChatOngoingCall.tsx). CometChatIncomingCall/OutgoingCall DO take `call`. */}
+      {ongoingCall && <View style={StyleSheet.absoluteFill}><CometChatOngoingCall sessionID={ongoingCall.getSessionId()} callSettingsBuilder={new CometChatCalls.CallSettingsBuilder().setIsAudioOnlyCall(ongoingCall.getType() === "audio")} /></View>}
+    </>
+  );
+}
+```
 
-`<CometChatIncomingCall />` (additive mode) goes inside the root navigator OR in the App.tsx wrapper, ABOVE all stacks/tabs. Same rule as web — calls only ring on screens where the listener exists.
+> **Don't skip the `ccOutgoingCall` listener.** Without it, tapping the video/voice button in `<CometChatMessageHeader>` triggers the call at the SDK level (WebRTC, camera, audio init) but no overlay UI ever mounts — the user sees nothing change after the tap. This was [[project_v4_3_f75_rn_call_ui_missing]] — F75.
 
 In standalone mode, CallKit/ConnectionService own the foreground UI; `<CometChatIncomingCall />` is not used. Instead, a `react-native-callkeep` event listener at app root reports new calls to the OS.
 
@@ -350,12 +418,12 @@ export async function initCometChat() {
 
   await CometChat.init(process.env.EXPO_PUBLIC_COMETCHAT_APP_ID!, appSettings);
 
-  const callAppSettings = new CometChatCalls.CallAppSettingsBuilder()
-    .setAppId(process.env.EXPO_PUBLIC_COMETCHAT_APP_ID!)
-    .setRegion(process.env.EXPO_PUBLIC_COMETCHAT_REGION!)
-    .build();
-
-  CometChatCalls.init(callAppSettings);
+  // Calls SDK init takes a FLAT object — there is no CallAppSettingsBuilder in v5 RN.
+  await CometChatCalls.init({
+    appId: process.env.EXPO_PUBLIC_COMETCHAT_APP_ID!,
+    region: process.env.EXPO_PUBLIC_COMETCHAT_REGION!,
+    authKey: process.env.EXPO_PUBLIC_COMETCHAT_AUTH_KEY!,
+  });
 
   initialized = true;
 }
@@ -369,16 +437,16 @@ export async function initCometChat() {
 
 ### Calls SDK primitives
 
-Same names + shapes as the JavaScript SDK (Section 3 of `cometchat-react-calls`). The RN SDK adds platform-specific helpers — `CometChatCalls.setUserVideoProxy` for native track piping etc. — covered in deeper sample-app references.
+Same names + shapes as the JavaScript SDK (Section 3 of `cometchat-react-calls`). RN-relevant session helpers include `switchCamera()`, `setAudioMode(mode)`, `muteAudio()`/`unmuteAudio()`, `pauseVideo()`/`resumeVideo()` — see the SDK's custom-ui reference. (Web-only helpers like device enumeration and virtual background are not available on RN.)
 
 ### UI Kit views (additive mode — `@cometchat/chat-uikit-react-native`)
 
 | Component | Purpose |
 |---|---|
 | `<CometChatCallButtons user={u} group={g} />` | Voice + video icon row (typically inside `CometChatMessageHeader`). **Group + user semantics differ** — see callout below |
-| `<CometChatIncomingCall />` | Root-mounted listener |
-| `<CometChatOutgoingCall />` | Auto-mounted by IncomingCall on initiate |
-| `<CometChatOngoingCall />` | Active call view |
+| `<CometChatIncomingCall />` | Root-mounted; renders ringing UI for incoming call (controlled by parent state — see §1.7) |
+| `<CometChatOutgoingCall />` | Root-mounted; renders "Calling…" UI for outgoing call (controlled by parent state — see §1.7) |
+| `<CometChatOngoingCall />` | Root-mounted; renders active in-call view (controlled by parent state — see §1.7) |
 | `<CometChatCallLogs onItemClick={fn} />` | History |
 
 #### ⚠️ Group calls use message-based join, not the ringing channel (validated 2026-05-15)
@@ -418,7 +486,9 @@ When `product === "voice-video"` and there is no existing UI Kit.
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
-Calls SDK ONLY. NO Chat SDK. Matches `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/`.
+Calls SDK ONLY. NO Chat SDK. Matches `calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/`.
+
+> **⚠️ Idle timeout is in MILLISECONDS on React Native (the "instant exit on join" footgun).** Like the web SDK, the RN calls SDK's `SessionSettings` idle fields are **milliseconds, not seconds** (`calls-sdk-react-native/skills/session-settings`: `idleTimeoutPeriodBeforePrompt: 60000` ms). Setting `idleTimeoutPeriodBeforePrompt: 180` thinking "180s" means **180 ms** → the "Are you still there?" prompt fires and the session exits a fraction of a second after you join alone. Use ms: `{ idleTimeoutPeriodBeforePrompt: 180_000, idleTimeoutPeriodAfterPrompt: 60_000 }` (defaults 60_000 / 120_000). The timer only counts down when you're the **only** participant, so a solo test triggers it fastest. (Native Android/iOS/Flutter calls SDKs use **seconds** for `setIdleTimeoutPeriod`, default 300 — RN/web are the ms outliers.)
 
 **MANDATORY install set (MUST run BEFORE scaffolding files — bundle will fail with `Unable to resolve module <name>` for each one missing):**
 
@@ -575,7 +645,7 @@ When `cometchat-native-core` integration already exists. The skill:
 - [ ] CometChatUIKit.getLoggedInUser called with `.catch(() => null)` (rule 1.8.a)
 - [ ] Error rendering uses `e.message` not `String(e)` (rule 1.8.b)
 - [ ] Env-var guard: provider throws actionable error when appId/region undefined (rule 1.8.c "Also recommended")
-- [ ] Hangup path includes `endSession` + `RNCallKeep.endCall`
+- [ ] Hangup path includes `leaveSession()` (v5-canonical; `endSession` is a deprecated shim) + `RNCallKeep.endCall`
 - [ ] Module-level `initialized` flag
 
 **Runtime (real devices, both platforms):**

package/skills/cometchat-native-calls/references/add-calls-to-existing-chat.md

@@ -94,7 +94,7 @@ await CometChat.init(APP_ID, settings);
 await CometChatCalls.init({ appId: APP_ID, region: REGION });
 
 // Later, after CometChat.login:
-await CometChatCalls.login(authToken);
+await CometChatCalls.loginWithAuthToken(authToken);
 ```
 
 ---
@@ -185,7 +185,7 @@ Skipping any of these leaves zombies — call still showing in the OS as "active
 - [ ] Info.plist + AndroidManifest permissions in place
 - [ ] `foregroundServiceType` declared (Android 14+)
 - [ ] Calls init AFTER chat init
-- [ ] `CometChatCalls.login(authToken)` after chat login
+- [ ] `CometChatCalls.loginWithAuthToken(authToken)` after chat login
 - [ ] CallKeep `setup` runs on app start (post-login)
 - [ ] VoIP token registration triggered on iOS
 - [ ] FCM token registration triggered on Android

package/skills/cometchat-native-calls/references/call-layouts.md

@@ -12,23 +12,24 @@ Same SDK as web (TILE/SIDEBAR/SPOTLIGHT). RN-specific: layout switcher must be a
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
 
-const callSettings = new CallSettingsBuilder()
-  .setSessionType(CometChatCalls.constants.SESSION_TYPE.VIDEO)
-  .setLayout(CometChatCalls.constants.LAYOUT.TILE)
-  .build();
+// Layout values are the bare string literals "TILE" | "SIDEBAR" | "SPOTLIGHT".
+// There are NO top-level LAYOUT / SESSION_TYPE named exports — the SDK only exports
+// CometChatCalls. (Constants that exist are namespaced statics:
+// CometChatCalls.CALL_MODE.* and CometChatCalls.AUDIO_MODE.* — verified against
+// calls-sdk-react-native skills/session-settings.)
+// Session type is the sessionSettings.sessionType field ('VIDEO' | 'VOICE'), not an enum import.
 
-// Mid-call switch
-CometChatCalls.setLayout(CometChatCalls.constants.LAYOUT.SPOTLIGHT);
+// Mid-call switch — setLayout takes a bare string literal:
+CometChatCalls.setLayout("SPOTLIGHT"); // "TILE" | "SIDEBAR" | "SPOTLIGHT"
 
 // Listen
-CometChatCalls.addEventListener("onCallLayoutChanged", (layout) => {
+const off = CometChatCalls.addEventListener("onCallLayoutChanged", (layout) => {
   // ...
 });
+// later: off();  // addEventListener returns the unsubscribe fn
 
-// Hide kit switcher
-const settings2 = new CallSettingsBuilder()
-  .setHideChangeLayoutButton(true)
-  .build();
+// Hide the kit's change-layout button: it's a SessionSettings OBJECT field
+// (hideChangeLayoutButton), passed to <CometChatCalls.Component />, not a builder method.
 ```
 
 ---
@@ -46,8 +47,8 @@ export function LayoutSwitcher() {
 
   useEffect(() => {
     const sub = (next: string) => setLayout(next as typeof LAYOUTS[number]);
-    CometChatCalls.addEventListener("onCallLayoutChanged", sub);
-    return () => CometChatCalls.removeEventListener("onCallLayoutChanged", sub);
+    const off = CometChatCalls.addEventListener("onCallLayoutChanged", sub);
+    return () => off();
   }, []);
 
   return (
@@ -109,7 +110,7 @@ Web sister rules apply, plus RN-specific:
 
 ## Verification checklist
 
-- [ ] Initial layout via `setLayout()` on the builder
+- [ ] Layout switched via `CometChatCalls.setLayout("…")` (bare string literal)
 - [ ] Switcher uses `Pressable` with `accessibilityRole="radio"`
 - [ ] Layout listener cleaned up on unmount
 - [ ] Orientation change handled (or explicitly stable)

package/skills/cometchat-native-calls/references/call-session.md

@@ -1,6 +1,6 @@
 # Call session — joinSession with no ringing (React Native)
 
-Server-generated sessionId, both parties enter it; RN uses a **declarative `<CometChatCalls.Component>` render primitive**, NOT the imperative `joinSession(token, settings, container)` web pattern. Customer-validated against `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`.
+Server-generated sessionId, both parties enter it; RN uses a **declarative `<CometChatCalls.Component>` render primitive**, NOT the imperative `joinSession(token, settings, container)` web pattern. Customer-validated against `calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`.
 
 **Read first:** `cometchat-react-calls/references/call-session.md` — full architecture (sessionId strategies, server-side authorization, token generation). Then come back here for the RN-specific render shape.
 
@@ -178,5 +178,5 @@ iOS `Info.plist`: `NSCameraUsageDescription`, `NSMicrophoneUsageDescription`. An
 - `cometchat-react-calls/references/call-session.md` — cross-platform architecture (sessionId strategies, server authorization)
 - `cometchat-native-calls/SKILL.md` — RN seven hard rules
 - `cometchat-native-calls/references/share-invite.md` — deep-link config
-- Upstream RN sample — `~/Downloads/calls-sdk/calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`
+- Upstream RN sample — `calls-sdk-react-native-5/sample-apps/cometchat-calls-sample-app-react-native/src/pages/join-session/JoinSession.tsx`
 - Canonical docs: https://www.cometchat.com/docs/calls/react-native/join-session

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

@@ -108,11 +108,15 @@ export function CustomOngoingCallScreen({ sessionId, authToken, isAudioOnly, onC
         muted={muted}
         cameraOff={cameraOff}
         onToggleMute={() => {
-          CometChatCalls.muteAudio(!muted);
+          // No-arg methods: muteAudio() / unmuteAudio() (no boolean param).
+          if (muted) CometChatCalls.unmuteAudio();
+          else CometChatCalls.muteAudio();
           setMuted(!muted);
         }}
         onToggleCamera={() => {
-          CometChatCalls.pauseVideo(!cameraOff);
+          // No-arg methods: pauseVideo() / resumeVideo() (no boolean param).
+          if (cameraOff) CometChatCalls.resumeVideo();
+          else CometChatCalls.pauseVideo();
           setCameraOff(!cameraOff);
         }}
         onSwitchCamera={() => CometChatCalls.switchCamera()}
@@ -206,14 +210,14 @@ Without `InCallManager.stop()`, the app's other audio (music, video) routes thro
 
 For multi-party calls where you want to highlight whoever's speaking:
 
+The event is `onDominantSpeakerChanged` (there is no `onActiveSpeakerUpdated`). Use `addEventListener` (returns an unsubscribe fn) — `OngoingCallListener` is the @deprecated v4 path:
+
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onActiveSpeakerUpdated: (uid: string) => {
-    setActiveSpeakerUid(uid);
-    // Re-layout: move that uid's tile to a larger position
-  },
-  // ...
+const off = CometChatCalls.addEventListener("onDominantSpeakerChanged", (uid: string) => {
+  setActiveSpeakerUid(uid);
+  // Re-layout: move that uid's tile to a larger position
 });
+// cleanup: off();
 ```
 
 Not all SDK versions emit this event reliably; verify with the version you're on before relying on it.