@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-react-native-troubleshooting/SKILL.md

@@ -0,0 +1,174 @@
+---
+name: cometchat-react-native-troubleshooting
+description: "Diagnose a broken CometChat React Native integration — blank chat screen, gestures not responding, Android build failures, calls not ringing, notifications not arriving, custom UI not showing. Symptom to root cause to fix. Triggers: CometChat React Native not working, blank chat screen RN, gestures not working chat, android build fails CometChat, calls not ringing RN, my custom view isn't showing."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native troubleshooting diagnostics errors debugging"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json`.
+> Docs: `/ui-kit/react-native/troubleshooting`.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- anything is broken and the error does not say why — which on React Native is most of the time
+
+## Prerequisites & install
+None.
+
+## Read this first: RN failures usually name the wrong thing
+Three properties make React Native bugs hard to read, and all three appear below:
+- **native modules fail at MOUNT, not at build** — so the app starts, then a screen explodes
+- **the error names a peer dependency**, not CometChat — `gesture-handler`, `svg`, `video`
+- **an unknown prop is silently ignored** — no error, nothing renders
+
+So "it says nothing about CometChat" is not evidence the problem is elsewhere.
+
+## Symptom → root cause → fix
+
+### Blank chat screen, no error
+| Cause | Fix |
+|---|---|
+| rendering before `login()` resolved | gate render on a `loggedIn` flag; `init` → `login` → render |
+| `initFromSettings()` failed | you **cannot** catch it — `CometChatUIKit.initFromSettings()` swallows init errors (its rejection handler is a no-op), so `await`/`.catch()` see nothing. Instead assert on the NEXT step: `await login(...)` (which DOES reject) or check `await CometChatUIKit.getLoggedInUser()`; a bad appId/region surfaces there as an auth failure |
+| an ancestor is not `flex: 1` | every ancestor `flex: 1`; a scrolling column also needs `minHeight: 0` |
+
+### The UI renders but nothing responds to touch
+**`GestureHandlerRootView` is missing, or is not outermost, or lacks `flex: 1`.**
+No error is thrown. On bare RN also confirm `import 'react-native-gesture-handler'` is the **first
+line of `index.js`** — wrong ordering there often works in debug and crashes in release.
+
+### `NativeModule … null` / "cannot read property of null" on a chat screen
+A native peer is missing or unlinked. Install the full peer list (`core`), then `pod install` (bare)
+or a fresh development build (Expo). **Metro reload does not pick up native changes — rebuild.**
+
+### Android build fails, error never mentions CometChat
+`@react-native-async-storage/async-storage` must be `^2.1.2` — the Chat SDK requires it at load and the Calls SDK peer-requires 2.x. Unpinned resolves to 3.x, which fails `npm install @cometchat/calls-sdk-react-native@5` with ERESOLVE. Check: `npm ls @react-native-async-storage/async-storage`.
+
+### Expo: works in Expo Go until a chat screen opens
+Expo Go **cannot** load custom native modules. Use a development build (`npx expo run:ios`). There is
+no workaround.
+
+### My custom view does not appear
+**Slot props are PascalCase on RN** — `ItemView`, not `itemView`. React's casing is silently ignored:
+no error, nothing renders. Same class of bug as a typo'd prop name.
+
+### Two headers stacked on the message screen
+The navigator's header plus `CometChatMessageHeader`. Set `headerShown: false` on that screen.
+
+### The composer is hidden when the keyboard opens
+A fixed height somewhere in the ancestor chain, or the message screen is nested **inside** the tab
+navigator so the tab bar overlaps it. Put the message screen on the stack **above** the tabs.
+
+### Sending a message throws on iOS (React Native >= 0.87)
+React Native **0.87 removed `InteractionManager` from core**, and `CometChatMessageComposer` (kit
+through 5.5.0) still calls `InteractionManager.runAfterInteractions()` in four **iOS-only** branches
+of its send path. Tapping send throws and the message never leaves the device. Android is unaffected;
+so is RN <= 0.86, where the export is deprecated but still resolves — which is why the same code
+sends fine on an older app and dies on a fresh template.
+
+| Where | What you see |
+|---|---|
+| dev build | `Uncaught Error: InteractionManager has been removed from react-native core. Please refactor long tasks into smaller ones, and use 'requestIdleCallback' instead.` in `CometChatMessageComposer` -> `sendTextMessage` |
+| release build | the same line reads `undefined` -> `TypeError: Cannot read property 'runAfterInteractions' of undefined` |
+| CI | **nothing** — it typechecks, bundles and builds on both platforms; only a person tapping send sees it |
+
+Until the kit drops the call, restore a minimal implementation **before the kit loads** — the first
+import in `index.js`:
+
+```js
+// interactionManagerCompat.js — delete when the kit stops calling InteractionManager.
+const ReactNative = require('react-native');
+
+const missing = () => {
+  try {
+    return !ReactNative.InteractionManager;
+  } catch {
+    return true; // RN >= 0.87 in __DEV__: the getter throws.
+  }
+};
+
+if (missing()) {
+  Object.defineProperty(ReactNative, 'InteractionManager', {
+    configurable: true,
+    get: () => ({
+      runAfterInteractions: (task) => {
+        const run = () => (typeof task === 'function' ? task() : task && task.gen && task.gen());
+        let settle;
+        const ran = new Promise((resolve) => { settle = resolve; });
+        const timer = setTimeout(() => { run(); settle(); }, 0);   // resolve AFTER the task runs
+        return {
+          then: (onResolve, onReject) => ran.then(onResolve, onReject),
+          done: (onDone) => { ran.then(onDone); },
+          cancel: () => clearTimeout(timer),
+        };
+      },
+      createInteractionHandle: () => 0,
+      clearInteractionHandle: () => {},
+      setDeadline: () => {},
+      addListener: () => ({ remove: () => {} }),
+    }),
+  });
+}
+```
+
+### `ReferenceError: Property '<name>' doesn't exist` right after a `try`/`catch`
+Hermes loses a `catch (error)` binding that is only read inside a closure created in the same block —
+`catch (error) { setLogs((prev) => [describe(error), ...prev]) }` throws the first time the catch
+runs, while the identical code with the value read first works. It typechecks and bundles either way.
+Read the caught value into a local, then use the local inside the closure.
+
+### Calls do not ring
+| Cause | Fix |
+|---|---|
+| `CometChatIncomingCall` mounted inside one screen | mount it **once above the navigator** |
+| calls SDK installed but pods not run | `pod install` / rebuild — otherwise it crashes at first call |
+| camera/mic permission not declared | add them (`calls`), then rebuild |
+| testing on a simulator | simulators capture no camera or mic — use real devices |
+
+### Notifications never arrive
+Registered before `login()` resolved · wrong platform constant · token rotated and never re-registered
+· missing `google-services.json` / `GoogleService-Info.plist` · iOS simulator. See `push`.
+
+### A feature was "enabled" but nothing changed
+| Cause | Fix |
+|---|---|
+| dashboard toggled, code prop not set | AI features need **both**; the props default to off |
+| it is already core in v5 | reactions and mentions are on by default — nothing to enable |
+| the kit auto-renders it | `auto_rendered_ui` features need no client code |
+
+### A symbol does not compile
+Check `catalogs/rn-v5.json`. Likely a React name: `UIKitSettingsBuilder`, `login(uid)`,
+`onItemClick`, `CometChatErrorBoundary`, `CometChatDetails`, `CometChatMessagePlugin`. See the
+React→RN table in `core/references/docs-map.md`.
+
+## First moves, in order
+1. Does `init` resolve, and does `login` resolve after it? Log both.
+2. Is `GestureHandlerRootView` outermost with `flex: 1`?
+3. Is every ancestor of the kit component `flex: 1`?
+4. Did you **rebuild** after the last native change, rather than reload?
+5. Does every emitted symbol exist in the catalog?
+
+## Verify it works
+- The symptom is reproducibly gone on a device, not only in a simulator.
+- `npm run verify:fences:rn-v5` is green.
+- If the fix was a native change, a **clean** build still works.
+
+## `tsc --noEmit` reports errors inside the UI Kit, not your app
+
+The kit's `package.json` has `main: "src/index"` and ships **uncompiled `.tsx`** — there is no `lib/` and
+no `types` field. So `tsc` follows the import into the kit's own source and reports ~30 errors under
+`node_modules/@cometchat/chat-uikit-react-native/src/*.tsx` while your own code is clean.
+
+`skipLibCheck` does **not** help (it only skips `.d.ts`, and there are none here), and
+`exclude: ["node_modules"]` does not either (TypeScript still follows imports). Metro strips types, so the
+bundle and the app are fine — this only bites a CI typecheck. Scope the check to your own sources:
+
+```bash
+tsc --noEmit -p tsconfig.json 2>&1 | grep -v 'node_modules/@cometchat/'
+```

package/skills/cometchat-react-native-v5-sdk/SKILL.md

@@ -0,0 +1,150 @@
+---
+name: cometchat-react-native-v5-sdk
+description: "Add voice & video calling to a React Native app FROM SCRATCH with the headless CometChat Calls SDK v5 (`@cometchat/calls-sdk-react-native@5`) — no prebuilt UI Kit. init→login→generateToken→render `<CometChatCalls.Component>`, granular event listeners, in-call actions (mute/video/layout/record/raise-hand), meet-style session rooms AND 1:1 ringing (Chat SDK signaling + Calls SDK media). Triggers: 'add calling from scratch react native', 'standalone video call RN', 'headless calls sdk react native', 'build my own call screen', 'meeting room join by session id RN', 'one-on-one ringing call without uikit RN', 'expo video call'."
+license: "MIT"
+compatibility: "React Native 0.71+ (old architecture AND New Architecture incl. bridgeless); Node 18+; iOS 13.0+ / Xcode 14+; Android minSdk 24. @cometchat/calls-sdk-react-native@^5 (5.0.5) + 6 pinned peer deps (see Prerequisites). 1:1 ringing also needs @cometchat/chat-sdk-react-native@^4 for signaling. Bare RN and Expo prebuild/dev-client; NOT Expo Go (native WebRTC module)."
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat calls sdk v5 headless voice video webrtc react-native calling standalone ringing"
+---
+
+> **Ground truth:** `@cometchat/calls-sdk-react-native@5` + catalog `rn-calls-v5.json` (the closed symbol list — every `CometChatCalls.*` below exists in it). Official docs: `/calls/react-native/**` = **v5** · Docs MCP. Fetch exact `sessionSettings` fields, event names and action signatures from the docs (`references/docs-map.md`) — never memory. **APPEND to the user's app — additive wiring only** (`RULES.md`). This is the HEADLESS path (no UI Kit); for the prebuilt drop-in call UI use `cometchat-react-native-calls` instead.
+
+## Companion skills (read first)
+- **Standalone/headless entry** — this skill owns its own package (the Calls SDK) and has no `-core` sibling; it is self-contained for meet-style calling.
+- **For 1:1 RINGING only** it also drives the **Chat SDK** (`@cometchat/chat-sdk-react-native@4`) for call signaling — signatures fetched from docs via `references/docs-map.md` (§ "1:1 RINGING"). It does NOT depend on the React Native UI Kit.
+- **Prefer the UI Kit instead?** If the app also wants chat and a prebuilt call UI, use `cometchat-react-native-core` + `cometchat-react-native-calls` — not this skill.
+
+## Use this skill when
+"add calling from scratch / without the UI Kit", "standalone voice/video in React Native", "build my own call screen", "headless calls SDK", "meeting-room join by session id", "one-on-one ringing call". Precondition: the caller chose the **from-scratch / standalone** path (the "add calling" router asks this). If they want the prebuilt call UI, route to `cometchat-react-native-calls`.
+
+## Prerequisites & install
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+# 6 REQUIRED peer deps — versions are pinned by the SDK; do not float them
+npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
+  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
+  react-native-webrtc@124.0.7
+```
+- **1:1 ringing** additionally needs the Chat SDK for signaling: `npm install @cometchat/chat-sdk-react-native@4`
+- **iOS** — `cd ios && pod install && cd ..`. Add to `ios/<App>/Info.plist`:
+  ```xml
+  <key>NSCameraUsageDescription</key><string>Camera access is required for video calls</string>
+  <key>NSMicrophoneUsageDescription</key><string>Microphone access is required for voice and video calls</string>
+  ```
+  Xcode → target → **Signing & Capabilities → Background Modes** → **Audio, AirPlay, and Picture in Picture** (+ **Voice over IP** for ringing — `references/ringing-voip.md`).
+- **Android** — add to `android/app/src/main/AndroidManifest.xml` as `<uses-permission android:name="android.permission.X" />`:
+  `INTERNET` · `CAMERA` · `RECORD_AUDIO` · `MODIFY_AUDIO_SETTINGS` · `ACCESS_NETWORK_STATE` · `BLUETOOTH` (add `android:maxSdkVersion="30"`) · `BLUETOOTH_CONNECT`.
+  API 23+ **also requires a RUNTIME request** (`PermissionsAndroid.requestMultiple([CAMERA, RECORD_AUDIO])` or `react-native-permissions`) BEFORE starting a call. A manifest entry alone is not enough. **A call that must survive backgrounding needs the `FOREGROUND_SERVICE*` family + `WAKE_LOCK` + `POST_NOTIFICATIONS` as well — `references/ringing-voip.md` § Part 2b.**
+- **New Architecture** — works on old arch, New Architecture and bridgeless with **no extra setup**; leave `newArchEnabled` as the app needs it. The SDK ships as a legacy native module and runs through RN's interop layer, so behaviour is identical on both.
+- Credentials/env: App ID · Region · Auth Key (dev only). To fetch from the dashboard, load the CLI on demand — `npx @cometchat/skills-cli@3 auth login` → `provision use --app-id <id> --json` (`@3` pins the CLI major that matches the v5 skills). Mint **auth tokens server-side** for production; never ship the Auth Key. Rebuild the app after installing (`npx react-native run-ios` / `run-android`) — this is a native dependency, so Metro-only reload will not pick it up.
+
+## Init & login ordering (BAKED — invariant)
+`CometChatCalls.initFromSettings(...)` (once, **check the result**) → `CometChatCalls.login(uid, authKey)` **or** `loginWithAuthToken(token)` → then `generateToken` / render / listeners. Nothing renders or joins before init+login resolve.
+- **DEFAULT to `CometChatCalls.initFromSettings(settings)`** — the ai-agent / telemetry-attributed path (persists `integrationSource="ai-agent"`), parallel to the chat core (`RULES.md` §5). It is **INTENTIONALLY undocumented** (ai-agent-only, `@nodoc` — DOCS-BACKLOG F4/C1), so the `CometChatSettings` shape is **baked in `references/docs-map.md`**; pass it **INLINE** (no physical `cometchat-settings.json` file needed). The publicly-documented **`CometChatCalls.init({ appId, region })` is the FALLBACK only**.
+- **Both init entry points return a RESULT OBJECT, not a rejecting promise** — `{ success: false, error: {...} } | { success: true, error: null }`. A bare `await CometChatCalls.initFromSettings(s)` that ignores `.success` silently continues on a validation failure and the call fails later with a confusing error. **Always branch on `.success`.**
+- **v5 authenticates itself.** v4 borrowed the Chat SDK's auth token and passed it to `generateToken`; v5 has its own `login`/`loginWithAuthToken` and caches the token internally, so `generateToken(sessionId)` takes **no** auth token. Passing one is the v4 pattern.
+- Coexisting with the Chat SDK / UI Kit? Log into the Chat SDK first, then share the session: `const u = await CometChat.getLoggedinUser(); if (u) await CometChatCalls.loginWithAuthToken(u.getAuthToken());`. **The token is a User method (`getAuthToken()`) — there is NO top-level `CometChat.getUserAuthToken()` on the RN Chat SDK** (that name is on the *Calls* SDK; the migration doc's v4 tab shows it wrongly — DOCS-BACKLOG). Full note: `references/docs-map.md` § 1:1 RINGING.
+
+## Two build modes (BAKED — the router picks one)
+- **Meet-style (session room)** — Calls SDK ONLY. Everyone who renders the same `sessionId` lands in the same call: `generateToken(sessionId)` → render `<CometChatCalls.Component>`. No ringing.
+- **1:1 ringing** — Chat SDK signals, Calls SDK carries media: `CometChat.initiateCall` → peer `CallListener.onIncomingCallReceived` → `acceptCall`/`rejectCall` → `CometChatCalls.generateToken(call.getSessionId())` → render the Component. Fetch Chat-SDK signatures via `references/docs-map.md` § "1:1 RINGING".
+  > ⚠️ **RINGING ALWAYS INCLUDES VoIP — build both halves, never ask.** Signaling alone is a websocket event: it rings the callee only while their app is open, so backgrounded or killed they get nothing and the call times out (45s). Half a feature. Whenever ringing is chosen, **`references/ringing-voip.md` is REQUIRED** — emit the native VoIP setup in the SAME build and name the steps that are the user's (VoIP cert, Firebase, Xcode capabilities). Meet-style has no ringing and needs none of it.
+
+## SDK method map (BAKED closed list — from the catalog; signatures → FETCH from docs)
+- **Lifecycle:** `CometChatCalls.init` · `CometChatCalls.initFromSettings` · `CometChatCalls.login` · `CometChatCalls.loginWithAuthToken` · `CometChatCalls.logout` · `CometChatCalls.getLoggedInUser` · `CometChatCalls.getUserAuthToken` · `CometChatCalls.isUserLoggedIn` · `CometChatCalls.addLoginListener` / `removeLoginListener`
+- **Session:** `CometChatCalls.generateToken` · **`CometChatCalls.Component`** (the React component you RENDER to join — there is **no `joinSession` on React Native**) · `CometChatCalls.leaveSession` · `CometChatCalls.endSessionForAll`
+- **Events:** `CometChatCalls.addEventListener(eventName, cb, { signal? }) → unsubscribe()` (event names: FETCH the full list from `/calls/react-native/events`)
+- **In-call actions** — ⚠️ **for CUSTOM controls ONLY; the `Component` already renders all of these** (see the first pitfall). Only reach for them when the user EXPLICITLY asks to replace the built-in controls: `muteAudio`/`unmuteAudio`/`toggleAudio` · `pauseVideo`/`resumeVideo`/`toggleVideo` · `switchCamera` · `setLayout` · `startRecording`/`stopRecording`/`toggleRecording` · `startStreaming`/`stopStreaming` · `startTranscription`/`stopTranscription` · `raiseHand`/`lowerHand`/`toggleHand` · `pinParticipant`/`unpinParticipant` · `muteParticipant` · `pauseParticipantVideo` · `showParticipantList`/`hideParticipantList`/`toggleParticipantList` · `setChatButtonUnreadCount`
+- **Audio routing (RN-only):** `CometChatCalls.setAudioMode` · `CometChatCalls.AUDIO_MODE`
+- **Picture-in-picture (RN-only):** `CometChatCalls.enablePictureInPictureLayout` / `disablePictureInPictureLayout`
+- **Call logs:** the history read is the **Calls SDK** `CometChatCalls.CallLogRequestBuilder` (verified against installed `@cometchat/calls-sdk-react-native@5`, 2026-09-10) — `new CometChatCalls.CallLogRequestBuilder().setLimit(n).setAuthToken(CometChatCalls.getUserAuthToken() ?? "").build()` → `fetchNext(): Promise<CallLog[]>` — **every** `fetchNext()` needs `.setAuthToken(...)` (no auto fallback; it rejects "`Auth Token` is required"). There is **NO `CometChat.CallLogRequestBuilder` on the Chat SDK** (`@cometchat/chat-sdk-react-native`, any version) — do not emit it. `CometChatCalls.CallLog` is the log model. For the **transcript opt-in** add `.setHasTranscriptions(true)` (filters to transcribed calls and attaches transcripts) — same token. Paginated history is the read — there is no working single-call-detail method (see deprecated note).
+- **Transcription:** `CometChatCalls.Transcription` · `CometChatCalls.TranscriptRequestBuilder` · `Transcript`
+> **Deprecated v5 compat surface — do NOT emit:** `CallSettingsBuilder`, `CallAppSettingsBuilder`, `OngoingCallListener`, `startSession`, `endSession`, `switchToVideoCall`, **`getCallDetails`** (a `@deprecated`/unsupported `void` NO-OP on the v5 class — the functional `Promise<CallLog[]>` form is only on the v4-compat class; use `CallLogRequestBuilder.fetchNext()`). They still run (v5 is a drop-in for v4) but are the OLD API, and **v5-only events never reach an `OngoingCallListener`**. Use plain settings + `addEventListener` + `leaveSession`.
+> **Not on React Native at all** (present on web — emitting them is a hallucination): `joinSession`, `startScreenSharing`/`stopScreenSharing`, virtual-background methods, audio/video **device enumeration** (`getAudioInputDevices` &c.). A symbol is real **iff it's in `rn-calls-v5.json`** — confirm THERE, then fetch its signature from `references/docs-map.md`.
+
+## Listener lifecycle (BAKED)
+`addEventListener` RETURNS an unsubscribe function AND accepts `{ signal }`. Prefer one `AbortController` per screen: pass `signal` to every listener and call `controller.abort()` in the effect cleanup — one teardown, no leaks. Register listeners BEFORE the Component mounts, and call `CometChatCalls.leaveSession()` on unmount. Never leak.
+> **`CometChatCalls` is a SINGLETON with ONE active session.** Mount exactly one `Component`. Every action (`leaveSession`, `muteAudio`, `setLayout`, …) takes **no session id** — it always targets the active session. To move to another call: `leaveSession()` → await `onSessionLeft` → `generateToken(next)` → re-render with the new token.
+
+## Least-code recipe (meet-style)
+```tsx
+// STRICT-TS-CLEAN: RN exports no settings type — narrow with `as const`, or inline the object
+// in the JSX prop (as below) where contextual typing narrows it. A hoisted bare literal fails tsc.
+import { useEffect, useState } from "react";
+import { View } from "react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+// 1. once at app start — ai-agent telemetry default; init({appId,region}) is the public-doc fallback
+const res = await CometChatCalls.initFromSettings({
+  appId: APP_ID, region: REGION, credentials: { authKey: AUTH_KEY },
+});
+if (!res.success) throw new Error(res.error.message);   // Result object, NOT a rejection
+// 2. after the user authenticates
+await CometChatCalls.login(UID, AUTH_KEY);              // or loginWithAuthToken(token)
+
+function CallScreen({ sessionId }: { sessionId: string }) {
+  const [callToken, setCallToken] = useState<string | null>(null);
+
+  useEffect(() => {                                      // 3. listeners BEFORE the component mounts
+    const controller = new AbortController();
+    const { signal } = controller;
+    CometChatCalls.addEventListener("onSessionLeft", () => {/* pop the screen */}, { signal });
+    CometChatCalls.addEventListener("onParticipantJoined", (p) => {/* … */}, { signal });
+    return () => { controller.abort(); CometChatCalls.leaveSession(); };   // 6. one teardown
+  }, []);
+
+  useEffect(() => {                                      // 4. token BEFORE render
+    CometChatCalls.generateToken(sessionId)
+      .then(({ token }) => setCallToken(token))
+      .catch((e) => console.error(e.errorCode, e.errorDescription));
+  }, [sessionId]);
+
+  if (!callToken) return null;                           // or a loader
+  return (
+    <View style={{ flex: 1 }}>                           {/* MUST be sized */}
+      {/* 5. JOIN = RENDER. No joinSession on React Native. */}
+      <CometChatCalls.Component
+        callToken={callToken}
+        sessionSettings={{ sessionType: "VIDEO", layout: "TILE" }}
+      />
+      {/* NO control buttons here — the Component already renders mute/video/camera/leave/layout. */}
+    </View>
+  );
+}
+```
+Fetch the full `sessionSettings` field list from `/calls/react-native/session-settings`. On Android, request runtime CAMERA + RECORD_AUDIO permissions before this screen mounts.
+
+## Framework notes (same SDK, per-flavour glue)
+- **Bare React Native** — the recipe above verbatim. Rebuild natively after install; a Metro reload will not link the new native module.
+- **Expo** — requires **prebuild / dev-client**; **cannot run in Expo Go**. `npx expo prebuild`, then declare perms in `app.json` (`expo.ios.infoPlist` NSCamera/NSMicrophone; `expo.android.permissions` CAMERA/RECORD_AUDIO/MODIFY_AUDIO_SETTINGS/BLUETOOTH_CONNECT) — NOT by hand-editing Info.plist/AndroidManifest (a prebuild discards manual edits). Build with `npx expo run:ios` / `run:android` or EAS.
+- **Navigation** — mount the call screen as its own route. Because the SDK holds ONE session, leaving the route must `leaveSession()`; do not keep a backgrounded `Component` mounted on a hidden tab.
+
+## Common pitfalls (BAKED)
+- **Don't duplicate the built-in call controls (the #1 mistake).** `<CometChatCalls.Component>` renders a COMPLETE call UI — mute, camera, switch-camera, layout, recording, participant list, raise hand and the red leave button. Do **NOT** add your own buttons around it; they duplicate the SDK's and drift out of sync. Action methods are for CUSTOM controls ONLY (only when the user EXPLICITLY asks) — hide the built-ins first via `sessionSettings` `hide*` flags.
+- **Reaching for `joinSession`** — does not exist on RN; joining IS rendering the Component. `startSession` is the deprecated v4 path.
+- **Zero-height parent** — the Component fills its parent; inside a `View` with no `flex: 1` or explicit height it renders invisibly. The RN analogue of web's zero-dimension container.
+- **Ignoring the init Result** — `initFromSettings`/`init` resolve `{ success, error }` rather than rejecting. `await` alone hides a validation failure.
+- **Passing an auth token to `generateToken`** — the v4 pattern. In v5 you `login()` first and the SDK holds the token.
+- **Manifest permission without the runtime request** — on Android 23+ the call fails with no UI signal; there is no `getUserMedia` prompt to fall back on.
+- **Expo Go** — will never work; native module. Prebuild or dev-client only.
+- **Mounting two Components / joining while in a session** — unsupported. Leave, await `onSessionLeft`, then join.
+- **Leaked listeners / no `leaveSession`** — every listener must be unsubscribed (or its `AbortController` aborted) and `leaveSession()` called on unmount.
+- **Using `OngoingCallListener` for v5 events** — `onSessionJoined`, `onConnectionLost`, `onLeaveSessionButtonClicked`, `onCallLayoutChanged` and the `onParticipant*` family arrive ONLY via `addEventListener`; a v4 listener silently never fires for them.
+- **Inverted flags + split toggles (v4→v5)** — v4 `show*` builder methods became v5 `hide*` props (`showEndCallButton(true)` → `hideLeaveSessionButton: false`; copying a v4 snippet inverts intent); and `muteAudio(true|false)` split into `muteAudio()`/`unmuteAudio()`, `pauseVideo()`/`resumeVideo()`.
+- **Floating the peer-dep versions — install EXACTLY as written; no `^`, no latest.** The trap: `react-native-performance` 6.x is published but the SDK peer is `^5.1.2`, and a floated `^6` makes **every later `npm install` fail with `ERESOLVE`** (surfacing long after). Mismatched `react-native-webrtc` fails at native link. Verify: `npm ls react-native-performance react-native-webrtc`.
+- **Hoisting `sessionSettings` without narrowing (strict TS — the docs' own examples fail this).** `sessionType`/`layout`/`audioMode` are string-literal unions, so a hoisted object literal widens them to `string` and fails `tsc` (TS2322). **React Native exports NO settings type** — `CometChatCalls` is the package's **ONLY named export** (verified against installed `@cometchat/calls-sdk-react-native@5.0.4` `.d.ts`/`.d.mts`; there is **no importable `Transcript`/`CallLog`/settings type**), so web's "annotate as `SessionSettings`" trick is impossible. **`sessionType` is `"VOICE" | "VIDEO"` — there is NO `"AUDIO"` value** (a voice call is `sessionType: "VOICE"`). Narrow with `as const`, or keep the object inline in the JSX prop. When you DO need a model type, DERIVE it from the class: `type CallLog = InstanceType<typeof CometChatCalls.CallLog>`, and for the audio mode use `(typeof CometChatCalls.AUDIO_MODE)[keyof typeof CometChatCalls.AUDIO_MODE]`:
+  ```tsx
+  const sessionSettings = { sessionType: "VIDEO", layout: "TILE" } as const;      // ✅
+  <CometChatCalls.Component callToken={token} sessionSettings={{ sessionType: "VIDEO" }} />  // ✅ inline
+  const bad = { sessionType: "VIDEO", layout: "TILE" };                            // ❌ widens to string
+  ```
+  The join-session/ringing **Component-mount** fences now narrow with `as const` (C15 fixed there), but `/calls/react-native/session-settings` still has **illustrative** fences that hoist a bare literal (TS2322 on copy). Narrow every hoisted `sessionSettings`.
+- **Emitting ringing WITHOUT the VoIP half.** It looks complete on two open simulators and fails the first real device test. VoIP ships WITH ringing, never as a follow-up offer — see `references/ringing-voip.md`.
+- **Assuming a signature** — event names, `sessionSettings` fields and action params are FETCHED from docs, never guessed.
+
+## Verify it works
+- **Tier-1 catalog:** every `CometChatCalls.*` symbol emitted appears in `rn-calls-v5.json` (`node test-suite/scripts/verify-catalog.mjs --family rn-calls-v5`).
+- **Tier-2 fences:** the emit type-checks against the installed `@cometchat/calls-sdk-react-native@5` `.d.ts` (`test-suite/typecheck/rn-v5`).
+- **Tier-3b headless smoke:** `node test-suite/scripts/sdk-smoke.mjs --family rn-calls-v5 [--live|--dry]` covers init→login→generateToken→listener-teardown. **The media render is NOT covered** — `Component` needs a real device/simulator with native WebRTC, so the node smoke proves wiring only. Verify the actual call surface on a simulator/device, and **1:1 ringing needs TWO logged-in clients** (one client proves the outgoing half only). Flag "dry-mock only, not live-certified" honestly where true.

package/skills/cometchat-react-native-v5-sdk/references/docs-map.md

@@ -0,0 +1,127 @@
+# docs-map — `cometchat-react-native-v5-sdk` (Calls SDK v5, React Native, headless)
+
+**Doc channel — PREFER the MCP, FALL BACK to a fetch** (`RULES.md` §"Canonical doc channel"). When the
+CometChat docs MCP is connected, reach every page through it — `fetch_cometchat_doc_page("/calls/react-native/<page>")`
+for a known page, `search_cometchat_docs` for a conceptual question. When it is **not** connected, tell the user and help them add it — `claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp` (or reinstall/enable the plugin), then retry — and only if it still will not connect, fetch
+`DOCS_BASE` + the path + `.md` instead (below). **Never require the MCP** — an agent with no MCP must still
+be able to read every page here. Either way the `<path>` catalog below decides WHICH page; MCP-vs-fetch is
+only HOW.
+
+Every path below is **v5**. Do not read `node_modules` or `.d.ts` for signatures — the catalog
+(`rn-calls-v5.json`) says what EXISTS; these pages say what it takes.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+
+> Production docs (`https://www.cometchat.com/docs`). **Fetch rule:** `DOCS_BASE` + the path shown + `.md` → raw
+> Markdown, with the code fences and prop tables intact.
+>
+> Example: `{DOCS_BASE}/calls/react-native/join-session.md`
+>
+> Full page index if you need to discover a page not listed below: `{DOCS_BASE}/llms.txt`
+
+> ⚠️ **Never `search("default calling")` or `search("react native calling")` to find the ringing flow.** Search surfaces the STALE `/calls/v4/react-native/**` tree (deprecated `startSession`, `CallSettingsBuilder`, no v5 event set). Go DIRECTLY to the paths below.
+
+## Path catalog
+
+| Topic | Path | Fetch it for |
+|---|---|---|
+| Overview / architecture | `/calls/react-native/overview` | the call flow diagram, the single-active-session rules, the feature index |
+| Setup | `/calls/react-native/setup` | the 6 pinned peer deps, iOS `Info.plist` + Background Modes, Android manifest + runtime permissions, New Architecture note |
+| Authentication | `/calls/react-native/authentication` | `init` / `login` / `loginWithAuthToken` signatures and the auth-token story |
+| **Join session** | `/calls/react-native/join-session` | `generateToken(sessionId)`, `<CometChatCalls.Component callToken sessionSettings />` props, error codes |
+| Session settings | `/calls/react-native/session-settings` | the FULL `sessionSettings` field list (all `hide*` flags, `audioMode`, `idleTimeoutPeriodBeforePrompt`, `enableIOSPictureInPicture`) |
+| Actions | `/calls/react-native/actions` | exact params for `muteAudio`/`setLayout`/`switchCamera`/… |
+| Events | `/calls/react-native/events` | the AUTHORITATIVE event-name list for `addEventListener` |
+| **Ringing (1:1)** | `/calls/react-native/ringing` | the Chat-SDK signaling half — see § 1:1 RINGING below |
+| Call layouts | `/calls/react-native/call-layouts` | `TILE` / `SIDEBAR` / `SPOTLIGHT` behaviour |
+| Audio modes | `/calls/react-native/audio-modes` | `setAudioMode` + `AUDIO_MODE` values (RN-only) |
+| Recording | `/calls/react-native/recording` | dashboard gating, `autoStartRecording`, recording events |
+| Call logs | `/calls/react-native/call-logs` | history read = **Calls SDK** `new CometChatCalls.CallLogRequestBuilder()` (there is NO `CometChat.CallLogRequestBuilder` on the Chat SDK); add `.setHasTranscriptions(true)` for the transcript opt-in. `CometChatCalls.CallLog` shape. |
+| Participant management | `/calls/react-native/participant-management` | moderator actions, `endSessionForAll` vs `leaveSession` |
+| Screen sharing | `/calls/react-native/screen-sharing` | **receive-only on RN** — confirm before emitting any control |
+| Picture-in-picture | `/calls/react-native/picture-in-picture` | in-app tile vs iOS system PiP |
+| Raise hand | `/calls/react-native/raise-hand` | `raiseHand`/`lowerHand`/`toggleHand` |
+| Idle timeout | `/calls/react-native/idle-timeout` | `idleTimeoutPeriodBeforePrompt` |
+| **VoIP / background ringing** | `/calls/react-native/voip-calling` | CallKit+PushKit (iOS), ConnectionService (Android), `registerTokenForPushNotification` — see § BACKGROUND RINGING |
+| Background handling | `/calls/react-native/background-handling` | keeping an ACTIVE call alive when the app backgrounds (distinct from ringing a closed app) |
+| Migration v4→v5 | `/calls/react-native/migration-guide-v5` | the deprecated-vs-current mapping; read it when touching legacy code |
+
+## BAKED — `initFromSettings` (intentionally undocumented)
+
+`CometChatCalls.initFromSettings(settings)` is the **ai-agent / telemetry-attributed** init and the DEFAULT for this skill (persists `integrationSource="ai-agent"`). It is deliberately `@nodoc` — ai-agent-only, the same posture as `CometChatUIKit.initFromSettings` (DOCS-BACKLOG F4/C1) — so there is **no doc page to fetch**. Its shape is baked here, verified against the shipped `.d.ts` (`interface CometChatSettings`):
+
+```ts
+CometChatCalls.initFromSettings({
+  appId: string,
+  region: string,
+  credentials?: { authKey?: string },
+  callsSDK?: { adminHost?: string | null, clientHost?: string | null, host?: string | null,
+               disableSdkIdentification?: boolean | null },
+  chatSDK?: Record<string, unknown>,
+  uiKit?: Record<string, unknown>,
+})
+```
+
+Pass it **INLINE** — no physical `cometchat-settings.json` file is required. It returns a **Result object**, not a rejection:
+
+```ts
+{ success: false, error: { name: "VALIDATION_ERROR", message: string, timestamp: number } }
+| { success: true, error: null }
+```
+
+Branch on `.success`. The publicly documented `CometChatCalls.init({ appId, region })` is the **FALLBACK only** (a non-skills / doc-following context) and returns the same Result shape.
+
+## 1:1 RINGING — the Chat SDK half
+
+Ringing is signaled by the **Chat SDK** (`@cometchat/chat-sdk-react-native@4`); the Calls SDK only carries media. Fetch `/calls/react-native/ringing` **directly** for the current signatures of:
+
+- `CometChat.initiateCall(...)` — start the ring
+- `CometChat.addCallListener(UNIQUE_ID, new CometChat.CallListener({ onIncomingCallReceived, onOutgoingCallAccepted, onOutgoingCallRejected, onIncomingCallCancelled }))`
+- `CometChat.acceptCall(sessionId)` / `CometChat.rejectCall(sessionId, status)`
+- `CometChat.removeCallListener(UNIQUE_ID)` — teardown
+
+Then hand off to the media half: `CometChatCalls.generateToken(acceptedCall.getSessionId())` → render `<CometChatCalls.Component>`. **Two teardowns are required** — the Chat-SDK call listener AND the Calls-SDK event listeners + `leaveSession()`.
+
+> **Sharing the session (SDK-verified, `[not in the doc]`).** To reuse the Chat SDK login for the Calls SDK, pass the Chat user's auth token to `CometChatCalls.loginWithAuthToken(...)`. The token is a **method on the User object** — `getLoggedinUser().getAuthToken()`. **There is NO top-level `CometChat.getUserAuthToken()` on the RN Chat SDK** (only `getLoggedinUser(): Promise<User|null>`); the `getUserAuthToken` name belongs to the *Calls* SDK. The `/calls/react-native/migration-guide-v5` **v4 tab shows `CometChat.getUserAuthToken()` — that is WRONG for RN** (DOCS-BACKLOG). Read from the shipped `@cometchat/chat-sdk-react-native` `.d.ts`: `getLoggedinUser` + `User.getAuthToken()`.
+> ```ts
+> const user = await CometChat.getLoggedinUser();
+> if (user) await CometChatCalls.loginWithAuthToken(user.getAuthToken());
+> ```
+
+> **Two-client testing note.** Ringing cannot be verified from one client: it needs **two logged-in users on separate devices/simulators**. Two instances of the same build on one simulator share a session and will not ring each other. A single-client run proves the OUTGOING half only — report it that way rather than calling ringing verified.
+
+## BACKGROUND RINGING — the half that is NOT in the ringing page
+
+`/calls/react-native/ringing` gets you a call that rings **only while the callee's app is open**:
+`onIncomingCallReceived` arrives over the Chat SDK's websocket, and a backgrounded or killed app has
+no socket. Nothing errors — the callee simply never learns they were called, and the caller's call
+times out (default 45s, `initiateCall(call, timeout)`).
+
+Ringing a CLOSED app is a separate, native build. Fetch `/calls/react-native/voip-calling` for it:
+
+- **iOS** — Push Notifications + Background Modes → **Voice over IP** capability; a **VoIP Services
+  certificate** (`.p12`) uploaded to Dashboard → Notifications → Push Notifications; a native
+  **PushKit + CallKit** module (`PKPushRegistry` → `CXProvider.reportNewIncomingCall`) that hands the
+  answer/end actions back to JS.
+- **Android** — Firebase Cloud Messaging + the server key in the dashboard; a self-managed
+  **`ConnectionService`** registered in the manifest with `BIND_TELECOM_CONNECTION_SERVICE`, plus
+  `MANAGE_OWN_CALLS` and `READ_PHONE_STATE`.
+- **Both** — register the device token with `CometChat.registerTokenForPushNotification(token, { voip: true })`
+  on iOS / without the flag on Android; on answer, `CometChat.acceptCall(sessionId)` →
+  `CometChatCalls.generateToken(sessionId)` → render the Component, exactly as in the foreground flow.
+
+**Do not improvise the native module** — follow the doc. If the pack's `cometchat-react-native-push`
+skill is installed, use it for the token registration and FCM/APNs half; this page is the calls-specific
+CallKit/ConnectionService layer it points at.
+
+> **Not verifiable here.** VoIP push needs a real device, real certificates and the app backgrounded —
+> it cannot be smoke-tested, CI-tested, or tested on an iOS simulator. Treat any "ringing works" claim
+> without device evidence as unproven.
+
+## Cross-platform trap
+
+The web skill (`cometchat-js-v5-sdk`) is NOT a source of truth for React Native. Web has `joinSession(token, settings, containerEl)`, screen-share publishing, virtual backgrounds and device enumeration; **React Native has none of those**. When a web doc page and this map disagree, this map wins — and the catalog decides what exists.