@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-react-native-v5-sdk/references/ringing-voip.md

@@ -0,0 +1,369 @@
+# Background ringing & background calls — the native half
+
+Two DIFFERENT problems that get confused. Read the one you need.
+
+| Problem | You need | Page |
+|---|---|---|
+| Callee's phone must ring while their app is **closed** | **VoIP push** + a native dialer (CallKit / ConnectionService) | `/calls/react-native/voip-calling` |
+| A call already in progress must **survive backgrounding** | Background modes + a foreground service | `/calls/react-native/background-handling` |
+
+Foreground ringing (`onIncomingCallReceived` over the Chat SDK websocket) is in the main SKILL. It works
+only while the callee's app is open. Everything below is what makes ringing behave like a real phone call.
+
+> **Where this comes from.** Almost everything here is transcribed from the two CometChat pages above —
+> the Swift/Java modules, the manifest entries, the certificate and Firebase steps, the permission lists and
+> the platform-behaviour tables. Three things are **not** from those pages and are labelled **`[not in the
+> doc]`** inline so you can check them yourself:
+> 1. the **typed token API** (`CometChatNotifications.registerPushToken` / `PushPlatforms` /
+>    `unregisterPushToken`) — read from the shipped `@cometchat/chat-sdk-react-native` `.d.ts`; the doc page
+>    still shows the legacy `CometChat.registerTokenForPushNotification` (DOCS-BACKLOG **C16**);
+> 2. **register-after-login / unregister-on-logout** — from the pack's own `cometchat-react-native-push`
+>    skill; this page has no logout step at all;
+> 3. the **`reportNewIncomingCall` termination rule** — Apple platform behaviour, not a CometChat claim.
+>
+> Nothing here is written from memory: if it is not on a CometChat page it is either in the SDK's types or
+> labelled as outside guidance.
+
+---
+
+# PART 1 — Ringing a CLOSED app (VoIP push)
+
+The Chat SDK's call listener needs a live socket. A killed or backgrounded app has none, so the server must
+wake it with a **push**, and the OS must show a **native call screen**. That is platform work — not JS.
+
+## 1a. iOS — VoIP push + CallKit
+
+**Capabilities** (Xcode → target → Signing & Capabilities): add **Push Notifications**, add
+**Background Modes**, enable **Voice over IP**.
+
+**Certificate:** Apple Developer → Certificates, Identifiers & Profiles → create a **VoIP Services
+Certificate** → download, install, export the `.p12`. Upload it (with its password) in the CometChat
+Dashboard under **Notifications → Push Notifications**.
+
+**Native module** — PushKit receives the wake-up, CallKit draws the system call UI:
+
+```swift
+// ios/CallKitManager.swift
+import CallKit
+import PushKit
+
+@objc(CallKitManager)
+class CallKitManager: NSObject, CXProviderDelegate, PKPushRegistryDelegate {
+  static let shared = CallKitManager()
+  private let provider: CXProvider
+  private let callController = CXCallController()
+  private var voipRegistry: PKPushRegistry?
+
+  override init() {
+    let config = CXProviderConfiguration()
+    config.supportsVideo = true
+    config.maximumCallsPerCallGroup = 1
+    config.supportedHandleTypes = [.generic]
+    provider = CXProvider(configuration: config)
+    super.init()
+    provider.setDelegate(self, queue: nil)
+  }
+
+  @objc func registerForVoIPPushes() {
+    voipRegistry = PKPushRegistry(queue: .main)
+    voipRegistry?.delegate = self
+    voipRegistry?.desiredPushTypes = [.voIP]
+  }
+
+    // Token → hand to JS → CometChatNotifications.registerPushToken(token, APNS_REACT_NATIVE_VOIP)
+  func pushRegistry(_ registry: PKPushRegistry, didUpdate pushCredentials: PKPushCredentials, for type: PKPushType) {
+    let token = pushCredentials.token.map { String(format: "%02x", $0) }.joined()
+    NotificationCenter.default.post(name: NSNotification.Name("VoIPTokenReceived"), object: nil, userInfo: ["token": token])
+  }
+
+  // The wake-up. You MUST report an incoming call here or iOS kills the app.
+  func pushRegistry(_ registry: PKPushRegistry, didReceiveIncomingPushWith payload: PKPushPayload, for type: PKPushType, completion: @escaping () -> Void) {
+    guard type == .voIP else { return }
+    let callerId   = payload.dictionaryPayload["callerId"]   as? String ?? "Unknown"
+    let callerName = payload.dictionaryPayload["callerName"] as? String ?? "Unknown"
+    let hasVideo   = payload.dictionaryPayload["hasVideo"]   as? Bool   ?? false
+    let update = CXCallUpdate()
+    update.remoteHandle = CXHandle(type: .generic, value: callerId)
+    update.localizedCallerName = callerName
+    update.hasVideo = hasVideo
+    provider.reportNewIncomingCall(with: UUID(), update: update) { _ in completion() }
+  }
+
+  func providerDidReset(_ provider: CXProvider) {}
+
+  func provider(_ provider: CXProvider, perform action: CXAnswerCallAction) {
+    NotificationCenter.default.post(name: NSNotification.Name("CallKitAnswerCall"), object: nil,
+                                    userInfo: ["callUUID": action.callUUID.uuidString])
+    action.fulfill()
+  }
+
+  func provider(_ provider: CXProvider, perform action: CXEndCallAction) {
+    NotificationCenter.default.post(name: NSNotification.Name("CallKitEndCall"), object: nil,
+                                    userInfo: ["callUUID": action.callUUID.uuidString])
+    action.fulfill()
+  }
+}
+```
+
+> ⚠️ **`reportNewIncomingCall` is not optional** — **`[not in the doc]`**, this is Apple's own PushKit rule:
+> iOS terminates an app that accepts a VoIP push without reporting a call. The CometChat page shows the call
+> being reported but does not say why it is mandatory. Report first, then do the CometChat work.
+
+## 1b. Android — FCM + a self-managed ConnectionService
+
+**Firebase:** add Firebase to the Android project, then in `android/app/build.gradle`:
+
+```groovy
+dependencies { implementation 'com.google.firebase:firebase-messaging:23.0.0' }
+```
+
+Upload the Firebase server key in the CometChat Dashboard under **Notifications → Push Notifications**.
+
+**ConnectionService** — registers the app as a self-managed dialer so the system rings:
+
+```java
+// android/app/src/main/java/com/yourapp/CallConnectionService.java
+package com.yourapp;
+
+import android.telecom.Connection;
+import android.telecom.ConnectionRequest;
+import android.telecom.ConnectionService;
+import android.telecom.PhoneAccountHandle;
+import android.telecom.TelecomManager;
+
+public class CallConnectionService extends ConnectionService {
+  @Override
+  public Connection onCreateIncomingConnection(PhoneAccountHandle h, ConnectionRequest request) {
+    CallConnection connection = new CallConnection();
+    connection.setConnectionProperties(Connection.PROPERTY_SELF_MANAGED);
+    connection.setCallerDisplayName(request.getExtras().getString("callerName"), TelecomManager.PRESENTATION_ALLOWED);
+    connection.setRinging();
+    return connection;
+  }
+
+  @Override
+  public Connection onCreateOutgoingConnection(PhoneAccountHandle h, ConnectionRequest request) {
+    CallConnection connection = new CallConnection();
+    connection.setConnectionProperties(Connection.PROPERTY_SELF_MANAGED);
+    connection.setDialing();
+    return connection;
+  }
+}
+```
+
+`AndroidManifest.xml`:
+
+```xml
+<uses-permission android:name="android.permission.MANAGE_OWN_CALLS" />
+<uses-permission android:name="android.permission.READ_PHONE_STATE" />
+
+<service
+    android:name=".CallConnectionService"
+    android:permission="android.permission.BIND_TELECOM_CONNECTION_SERVICE"
+    android:exported="true">
+  <intent-filter><action android:name="android.telecom.ConnectionService" /></intent-filter>
+</service>
+```
+
+## 1c. Register the token (both platforms)
+
+> ⚠️ **`[not in the doc]` — the doc page uses the LEGACY token API.** `/calls/react-native/voip-calling` shows
+> `CometChat.registerTokenForPushNotification(token, { voip: true })` — an untyped `settings` bag with no
+> platform enum and no unregister counterpart. The SDK ships a **typed** replacement with a dedicated VoIP
+> platform, and it is what the pack's `cometchat-react-native-push` skill uses. Prefer it. (DOCS-BACKLOG C16)
+
+```tsx
+import { CometChatNotifications } from "@cometchat/chat-sdk-react-native";
+
+const { PushPlatforms } = CometChatNotifications;
+
+// iOS VoIP pushes are a DIFFERENT platform from ordinary iOS pushes — an app that rings AND sends
+// message notifications registers two tokens on two platforms.
+async function registerVoIPToken(token: string, platform: "ios" | "android"): Promise<void> {
+  try {
+    await CometChatNotifications.registerPushToken(
+      token,
+      platform === "ios" ? PushPlatforms.APNS_REACT_NATIVE_VOIP   // the PushKit token
+                         : PushPlatforms.FCM_REACT_NATIVE_ANDROID,
+    );
+  } catch (error) {
+    console.error("VoIP token registration failed", error);
+  }
+}
+
+// On logout — otherwise the next user on this device inherits the previous user's calls.
+await CometChatNotifications.unregisterPushToken();
+```
+
+Register **after login** — a token registered with no logged-in user is attached to nobody. Re-register on
+token refresh, and unregister on logout. **`[not in the doc]`** — this ordering comes from the pack's
+`cometchat-react-native-push` skill; the VoIP page states no login ordering and has no logout step.
+
+## 1d. Answer from the native call screen → join the session
+
+The OS answer action comes back to JS; from there it is the SAME flow as foreground ringing:
+
+> ⚠️ **`CallKitManager` is iOS-ONLY and emits EXACTLY three events** — `VoIPTokenReceived`,
+> `CallKitAnswerCall`, `CallKitEndCall`. Subscribing to any other name throws at runtime:
+> ``` `FcmTokenReceived` is not a supported event type for CallKitManager ```. In particular **the Android
+> FCM token does NOT arrive through this module** — see § Android token below.
+
+```tsx
+import { useEffect } from "react";
+import { NativeEventEmitter, NativeModules, Platform } from "react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+export default function useVoIPPush(onToken: (t: string) => void) {
+  useEffect(() => {
+    if (Platform.OS !== "ios") return;                 // Android: see § Android token
+    const emitter = new NativeEventEmitter(NativeModules.CallKitManager);
+
+    // The iOS token arrives HERE — PushKit hands it to Swift, Swift posts it, this consumes it.
+    // Without this listener the Swift side emits into nothing and no token is ever registered.
+    const tok = emitter.addListener("VoIPTokenReceived", (d: { token: string }) => {
+      void registerVoIPToken(d.token, "ios");
+    });
+
+    const answer = emitter.addListener("CallKitAnswerCall", async (data: { sessionId: string }) => {
+      await CometChat.acceptCall(data.sessionId);                       // signaling
+      const { token } = await CometChatCalls.generateToken(data.sessionId); // media
+      onToken(token);                                                    // render <CometChatCalls.Component>
+    });
+
+    const end = emitter.addListener("CallKitEndCall", () => CometChatCalls.leaveSession());
+
+    return () => { tok.remove(); answer.remove(); end.remove(); };
+  }, [onToken]);
+}
+```
+
+### Android token — a DIFFERENT source
+
+**`[not in the doc]`** — the VoIP page says to add Firebase but never says where the token comes from. It is
+**not** an event on `CallKitManager` (that module is iOS-only). It comes from your messaging library, the
+same one the pack's `cometchat-react-native-push` skill uses:
+
+```tsx
+import messaging from "@react-native-firebase/messaging";
+
+// once, after login
+const fcmToken = await messaging().getToken();
+await registerVoIPToken(fcmToken, "android");
+
+// and whenever Firebase rotates it
+const unsub = messaging().onTokenRefresh((t) => registerVoIPToken(t, "android"));
+```
+
+So the two platforms differ in **where the token comes from**, not in what you do with it: iOS via the
+PushKit → Swift → `VoIPTokenReceived` chain, Android via `messaging().getToken()`. Both end at the same
+`registerPushToken` call with their own `PushPlatforms` value.
+
+---
+
+# PART 2 — Keeping an ACTIVE call alive in the background
+
+Different problem: the call already started and the user switches apps or locks the screen.
+
+## 2a. iOS
+
+**Background Modes** → **Audio, AirPlay, and Picture in Picture** (add **Voice over IP** too if using Part 1).
+The SDK configures the audio session itself; override only if you need to:
+
+```swift
+// ios/AppDelegate.swift
+import AVFoundation
+
+try? AVAudioSession.sharedInstance().setCategory(
+  .playAndRecord, mode: .voiceChat,
+  options: [.allowBluetooth, .allowBluetoothA2DP, .defaultToSpeaker])
+try? AVAudioSession.sharedInstance().setActive(true)
+```
+
+| Scenario | iOS behaviour |
+|---|---|
+| App backgrounded | Audio continues, **video pauses** |
+| Phone call arrives | Call audio interrupted, resumes after |
+| Screen locked | Audio continues |
+
+## 2b. Android — the permissions most integrations miss
+
+```xml
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MICROPHONE" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_CAMERA" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PLAYBACK" />
+<uses-permission android:name="android.permission.FOREGROUND_SERVICE_MEDIA_PROJECTION" />
+<uses-permission android:name="android.permission.WAKE_LOCK" />
+<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />
+```
+
+Android 10+ requires a **foreground service** for a call to continue in the background. The SDK ships
+`com.cometchat.calls.services.CometChatOngoingCallService` and declares it in its own manifest, so it merges
+into your app automatically — **you normally declare nothing**. Only if you must override it:
+
+```xml
+<service android:name="com.cometchat.calls.services.CometChatOngoingCallService"
+         android:foregroundServiceType="camera|microphone|mediaProjection|mediaPlayback" />
+```
+
+Wake locks are managed by the SDK. Do not add your own.
+
+| Scenario | Android behaviour |
+|---|---|
+| App backgrounded | Audio continues **via the foreground service** |
+| Phone call arrives | Call audio may be interrupted |
+| Screen off | Audio continues (wake lock) |
+
+## 2c. App-state + connection wiring
+
+```tsx
+import { useEffect, useRef } from "react";
+import { AppState, AppStateStatus } from "react-native";
+import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
+
+export default function useBackgroundCall(onEnded: () => void) {
+  const appState = useRef(AppState.currentState);
+
+  useEffect(() => {
+    const sub = AppState.addEventListener("change", (next: AppStateStatus) => {
+      if (appState.current.match(/active/) && next === "background") CometChatCalls.enablePictureInPictureLayout();
+      else if (appState.current === "background" && next === "active") CometChatCalls.disablePictureInPictureLayout();
+      appState.current = next;
+    });
+    return () => sub.remove();
+  }, []);
+
+  useEffect(() => {
+    const controller = new AbortController();
+    const { signal } = controller;
+    CometChatCalls.addEventListener("onConnectionLost", () => {}, { signal });      // show "reconnecting"
+    CometChatCalls.addEventListener("onConnectionRestored", () => {}, { signal });  // hide it
+    CometChatCalls.addEventListener("onConnectionClosed", onEnded, { signal });
+    return () => controller.abort();
+  }, [onEnded]);
+}
+```
+
+---
+
+## Verifying this — and what "verified" honestly means
+
+**None of Part 1 can be tested here.** VoIP push needs a real device, real certificates, and the app
+genuinely backgrounded or killed. It does not work on an iOS Simulator (APNs is absent), it cannot run in CI,
+and the pack's `sdk-smoke` cannot mount native code. Any "ringing works" claim without a two-device run on
+real hardware is **unproven** — say so rather than implying coverage.
+
+Test matrix that actually proves it:
+
+| Check | How |
+|---|---|
+| Token registered | log the token, confirm registration resolves AFTER login |
+| Push arrives, app backgrounded | background the callee app, call from device 2 → native call UI appears |
+| Push arrives, app KILLED | swipe the callee app away, call → app wakes and rings |
+| Answer → media | accept from the OS screen → `<CometChatCalls.Component>` mounts and audio flows |
+| Reject / timeout | reject, and separately let it ring out (default 45s) |
+| Call survives backgrounding | during an active call, background the app → audio continues |
+
+**Two live clients are required** for every row. Two instances of the same build on one simulator share a
+session and will not ring each other.

package/skills/cometchat-react-v7-calls/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: cometchat-react-v7-calls
+description: "Add voice & video calling to a React app with the CometChat v7 UI Kit — install the Calls SDK, enable calling on the UIKit settings, mount the incoming-call surface, and wire 1:1 ring / group join. Bakes the real gotchas (ms idle-timeout, zero-dimension call surface, Next.js SSR, no group-ring, HTTPS/getUserMedia). Triggers: 'add voice and video calls', 'add calling to my chat', 'enable video call', 'add call buttons', 'show call logs', 'cometchat calling react'."
+license: "MIT"
+compatibility: "React >=18 <21; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0); @cometchat/chat-sdk-javascript ^4.1.9; @cometchat/calls-sdk-javascript ^5 (5.0.0 — separate, NOT bundled)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react calls voice video calling webrtc v7 uikit"
+---
+
+> **Ground truth:** calling is part of `@cometchat/chat-uikit-react@7` (the call UI ships INSIDE the kit — there is no separate calls-UI package), but the WebRTC engine is a SEPARATE, NOT-bundled dependency: `@cometchat/chat-uikit-react@^7` + `@cometchat/chat-sdk-javascript@^4.1.9` + **`@cometchat/calls-sdk-javascript@^5`** (major 5 — distinct from the chat SDK's v4). Every `CometChat*` symbol below exists in the `web-v7` catalog. Exhaustive props + advanced call surfaces are FETCHED from the docs `.md` twins via `cometchat-react-v7-core/references/docs-map.md`. **APPEND to the user's app — additive wiring only** (`RULES.md`).
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, credentials, `init→login→render`, `CometChatProvider`. This skill ASSUMES it (calling is enabled on the SAME init).
+- `cometchat-react-v7-components` — the component catalog (message header the call buttons live in).
+- `cometchat-react-v7-features` — `voice-video-calls` is the feature entry; this skill is its operational depth.
+
+## Use this skill when
+"add voice & video calls", "add calling to my chat", "enable video call", "add call buttons", "show call logs". Precondition: chat is already integrated (core done) — calling rides on the same init/login.
+
+## Prerequisites & install
+Core setup done (init + login + `CometChatProvider`). Calling adds ONE package:
+```bash
+npm install @cometchat/calls-sdk-javascript@5
+```
+> The Calls SDK is **major 5** (not the chat SDK's v4) and is **NOT bundled** by the UI Kit — if it isn't installed, every call affordance stays hidden. Do not "upgrade" `@cometchat/chat-sdk-javascript` to a non-existent v7; it stays `^4.1.9`.
+
+## Enable calling (BAKED — the two-part contract, the #1 gotcha)
+Calling is OFF until BOTH are true: the Calls SDK is installed (above) **and** calling is turned ON in the init settings. Since the core inits via **`CometChatUIKit.initFromSettings`** (telemetry — `RULES.md` §5 / AUDIT-084), enable calling IN the SAME settings object with a truthy **`uiKit.callsSDK`**:
+```tsx
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+
+await CometChatUIKit.initFromSettings({
+  appId: APP_ID, region: REGION,
+  credentials: { authKey: AUTH_KEY },                        // dev-only; prod → server-minted auth token
+  chatSDK: { presenceSubscription: { type: "ALL_USERS" } },
+  uiKit: { callsSDK: {} },   // ← turns calling ON (the initFromSettings equivalent of setCallingEnabled(true))
+});
+```
+> **How calling maps in the initFromSettings path (verified vs the compiled 7.1.x kit; DOCS-GAP).** The kit computes `callingEnabled = !!settings.uiKit.callsSDK`, so a **truthy `uiKit.callsSDK`** is the `initFromSettings` equivalent of `UIKitSettingsBuilder().setCallingEnabled(true)` — WITHOUT it, call buttons + incoming-call render nothing. The docs don't yet document this shape (owner: **docs** — confirm with a live call). The classic path still works — `CometChatUIKit.init(new UIKitSettingsBuilder()…setCallingEnabled(true).build())` — but it SKIPS the ai-agent telemetry attribution, so prefer `initFromSettings`.
+> No separate `CometChatUIKitCalls.init()` is needed for the default path. (`CometChatUIKitCalls` is the kit's namespace for advanced call-settings builders; reach for it only on a custom surface — FETCH then.) `initFromSettings` routes the Calls SDK internally — do NOT call raw `CometChat.init()`.
+
+## Wire the UI (BAKED — least-code path)
+Two moves cover ringing end-to-end:
+1. **Mount `CometChatIncomingCall` ONCE at the app root** (above your routes). It self-manages visibility — renders nothing when idle, rings on an inbound call — so **no conditional wrapper**. It attaches its own SDK listeners.
+   ```tsx
+   import { CometChatIncomingCall } from "@cometchat/chat-uikit-react";
+   // at the app shell, inside CometChatProvider, above the router:
+   <CometChatIncomingCall />
+   ```
+2. **Let `CometChatMessageHeader` surface the call buttons.** When a `user`/`group` is selected, the header composes voice/video call buttons itself once calling is enabled — you usually mount NOTHING extra. Only drop a standalone `CometChatCallButtons user={user}` (1:1) or `group={group}` on a CUSTOM header that has no `CometChatMessageHeader`. **Never mount both** — a standalone `CometChatCallButtons` next to a `CometChatMessageHeader` duplicates the buttons.
+
+**Call logs** (optional history surface): `CometChatCallLogs` on a sidebar or a `/calls` route (`onItemClick`, `onCallButtonClicked`, `callLogRequestBuilder`). It does NOT auto-refresh on a new call — remount to refresh. **It shows the kit's "OOPS! …" screen when call logs aren't available — and, verified live, it renders that from its OWN INTERNAL error state WITHOUT throwing, so a host `CometChatErrorBoundary`/`fallbackView` CANNOT override it and `onError` may not fire. A fallbackView is NOT the fix (AUDIT-162).** **Enabling calling is NOT sufficient for `CometChatCallLogs`:** call-logs availability is a SEPARATE plan/capability gate — an app can have calling ON (Voice/Video buttons render) yet `CometChatCallLogs` still "OOPS" because call-logs isn't in the plan. **The only reliable protection is to GATE the Calls tab on real call-logs AVAILABILITY** (a one-time SDK probe you own — `new CometChatCalls.CallLogRequestBuilder().setLimit(1).setAuthToken(await CometChatUIKitCalls.generateToken(...)).build().fetchNext()`, show the tab only on success — or your known plan), NOT merely on calling being enabled; default the tab OFF so a plain app never dead-ends. **Import discipline (AUDIT-204): `CallLogRequestBuilder` is NOT a named export of `@cometchat/calls-sdk-javascript` — it is a STATIC on the `CometChatCalls` default-export class** (verified vs calls-sdk 5.0.5 `dist/index.d.ts`): use `import { CometChatCalls } from "@cometchat/calls-sdk-javascript"; new CometChatCalls.CallLogRequestBuilder()…` — a `import { CallLogRequestBuilder } from "@cometchat/calls-sdk-javascript"` FAILS (TS2614). `generateToken` is on `CometChatUIKitCalls` (from `@cometchat/chat-uikit-react`). (Gated Calls-tab recipe with the full probe + imports: `../cometchat-react-v7-placement/references/recipes.md` Combined-app recipe.)
+
+### 1:1 rings, groups JOIN (BAKED — no group-ring)
+- **1:1:** call buttons → the kit initiates a call → the recipient's root `CometChatIncomingCall` RINGS → accept → the ongoing-call surface. The kit drives outgoing → ongoing for you.
+- **Group:** call buttons on a group send a **group-call meeting message** into the chat; members **JOIN** from that message. There is **no "ring the whole group" primitive** — surface the join affordance, never wait for a ring.
+
+## Custom call surfaces (FETCH — don't bake)
+For anything past the default ring/join — a custom ongoing-call screen (`CometChatOngoingCall`), a bespoke call manager (`CometChatOutgoingCall`), idle-timeout tuning, screen-share, picture-in-picture, device selection, recording, virtual background — FETCH the exact props/API from the docs `.md` twins via `cometchat-react-v7-core/references/docs-map.md` (rows: `call-buttons` · `incoming-call` · `outgoing-call` · `call-logs` · `calls-setup` · `calls-react-integration` · the per-feature Calls-SDK pages). These props change; never emit them from memory or read `.d.ts`.
+
+## Common pitfalls (BAKED — these bite in production)
+- **Idle-timeout is in MILLISECONDS.** `180` = 180 ms, so the "are you still there?" prompt fires and exits instantly. Use `180_000` for 3 minutes. (Exact v7 field/clamp → FETCH the idle-timeout page.)
+- **Zero-dimension call surface = crash/blank.** A custom ongoing-call container with 0 width/height throws or renders nothing (e.g. `h-full` on an auto-height flex parent). Give the call surface a content-INDEPENDENT height + width per the reflow-free-surface standard (`../cometchat-react-v7-core/references/layout.md`) — a pinned flex chain with `min-height:0`, or a `100dvw/100dvh` overlay. Same class of bug as the chat-collapse/reflow issue: the kit call UI fills its parent, so a content-driven box collapses or grows-into-place.
+- **`Container dimensions and number of tiles must be positive` on leave (non-fatal).** Even the kit's DEFAULT ongoing-call dialog logs this error from a Jitsi `ResizeObserver` as the dialog collapses to 0×0 while unmounting on "Leave session". It's a Calls-SDK teardown race — **non-fatal: the app recovers to the chat surface** — but it's an uncaught console error every hang-up, so a strict "no console errors" gate must allowlist/filter it. Owner: uikit/calls-sdk (not a host bug). Don't try to "fix" it host-side.
+- **HTTPS required.** `getUserMedia` (camera/mic) only works on `localhost` or HTTPS — calling silently no-ops on a plain-HTTP non-localhost origin.
+- **Next.js SSR.** Render CometChat (and especially the calls SDK) client-only: `"use client"` + `dynamic(() => import(...), { ssr: false })`. If the build then fails with `Can't resolve 'fs'` / `'path'`, add a webpack fallback (`config.resolve.fallback = { fs: false, path: false }`) — a Calls-SDK-v5 bundling quirk. See `cometchat-react-v7-core/references/ssr.md`.
+- **Cleanup on custom surfaces.** On a hand-rolled ongoing-call screen, end the session and stop the tracks (`stream.getTracks().forEach(t => t.stop())`) on hangup/unmount or the camera light stays on. The kit-driven `CometChatIncomingCall`/ongoing flow handles this for you — prefer it.
+- **Screen-share / PiP / device-select / recording / virtual-background are NOT on by default** — each is separate wiring on its own Calls-SDK page. Don't claim the default screen includes them.
+
+## Verify it works
+Calling is enabled (SDK installed + `uiKit:{callsSDK:{}}` on `initFromSettings` — the `initFromSettings` equivalent of the classic `setCallingEnabled(true)`); a 1:1 call from the header buttons RINGS the other user's root `CometChatIncomingCall`; accept connects audio+video in a non-collapsed surface; a group call posts a join message (no ring); hang-up releases the camera/mic (light off). If call buttons never appear: the SDK isn't installed or calling isn't enabled. If the call screen is blank: the container is zero-dimension or the origin isn't HTTPS.
+
+**Close (after it builds):** end with the shared 3-option selectable menu and WAIT for the pick — **① add another feature** (suggest a few not-yet-wired) · **② customize theming** · **③ test it manually** (stop; let the user check). Same contract as the `cometchat-react-v7-core` close (`RULES.md` §19).

package/skills/cometchat-react-v7-components/SKILL.md

@@ -0,0 +1,72 @@
+---
+name: cometchat-react-v7-components
+description: "The React v7 UI Kit component catalog — which drop-in components exist and how to compose/swap them (conversations, messages, users, groups, threads, calling, bubbles). Triggers: 'what cometchat components are there', 'customize the message list', 'swap the message bubble', 'add a users list'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.1"
+  tags: "cometchat react components uikit catalog v7"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Component names below are from the live v7 components docs (see `../cometchat-react-v7-core/references/docs-map.md` → `/ui-kit/react/components-overview`). Status: **catalog-verified vs installed 7.1.0 (exports-only `web-v7.json`).** Fetch each component's prop table from its **`.md` twin** (`../cometchat-react-v7-core/references/docs-map.md`) — do NOT bake it; never read `.d.ts`.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, credentials, `init→login→render`, provider. This skill ASSUMES it.
+
+## Use this skill when
+Choosing, composing, or swapping UI Kit components; "which components exist"; customizing a list/message/bubble.
+
+## Prerequisites & install
+Covered by core. This skill adds no new package.
+
+## Component catalog (BAKED closed list — from live v7 docs; confirm vs web-v7.json)
+Conversations & lists: `CometChatConversations`, `CometChatUsers`, `CometChatGroups`, `CometChatGroupMembers`.
+Messages: `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`, `CometChatMessageBubble`, `CometChatThreadHeader`, `CometChatMessageInformation`, `CometChatReactions`, `CometChatReactionList`.
+Message bubbles: `CometChatTextBubble`, `CometChatImagesBubble`, `CometChatVideosBubble`, `CometChatAudiosBubble`, `CometChatVoiceNoteBubble`, `CometChatFilesBubble`, `CometChatPollBubble`, `CometChatStickerBubble`, `CometChatCollaborativeDocumentBubble`, `CometChatCollaborativeWhiteboardBubble`, `CometChatCardBubble`, `CometChatGroupActionBubble`, `CometChatCallActionBubble`, `CometChatCallBubble`.
+Calling UI: `CometChatCallButtons`, `CometChatIncomingCall`, `CometChatOutgoingCall`, `CometChatOngoingCall`, `CometChatCallLogs`.
+Search & AI: `CometChatSearch`, `CometChatAIAssistantChat`, `CometChatSmartReplies`, `CometChatConversationStarter`, `CometChatConversationSummary`.
+Moderation / notifications feed: `CometChatModerationView`, `CometChatNotificationFeed`, `CometChatFlagMessageDialog` (end-user report/flag dialog).
+Interactive/dialogs: `CometChatCreatePoll` (poll-authoring dialog; pairs with `CometChatPollBubble`).
+Base/util: `CometChatProvider`, `CometChatAvatar`, `CometChatButton`, `CometChatFullScreenViewer`, `CometChatConfirmDialog`, `CometChatContextMenu`, `CometChatErrorBoundary`.
+> This is the closed list — if a name isn't here (and in `web-v7.json`), it does not exist; do not use it.
+> **Phantoms removed 2026-07-30 (AUDIT-008 — reviewer G0 catalog sweep vs installed `@cometchat/chat-uikit-react@7.1.0` `.d.ts`).** These names were in earlier drafts but DO NOT exist in v7 — never emit them: `CometChatTypingIndicator` (typing renders inside `CometChatMessageHeader`; `CometChatTypingDisplay` is a *type*, not a component), `CometChatEmojiKeyboard` (emoji is the built-in EMOJI button in `CometChatMessageComposer`), `CometChatMediaRecorder` (voice recording is built into `CometChatMessageComposer`, `hideVoiceRecordingButton` default false), `CometChatListItem` (list items are internal item-views of the list components), `CometChatToast` (no standalone toast component). Note `CometChatNotifications` is a **Chat SDK** class (`@cometchat/chat-sdk-javascript`, push token registration) — NOT a UI Kit component; don't render it.
+
+## Swap / compose slots
+- v7 components are **compound components**: compose behavior via namespace sub-components (e.g. `Root`, `View`, `EmptyState`) and prop-driven slots rather than deep prop sprawl. Fetch the exact composition API + props from the component's **`.md` twin** (`../cometchat-react-v7-core/references/docs-map.md`) before emitting — never the `.d.ts`.
+- **Custom UI goes in a component's view slot, INSIDE it — never as a sibling on top.** Stable props + view slots for the 4 drop-ins are baked in `../cometchat-react-v7-core/references/component-props.md` (Conversations `headerView`/`searchView`, MessageHeader `trailingView`/`auxiliaryButtonView`, MessageList `headerView`/`footerView`, Composer `auxiliaryButtonView`/`headerView`) — use them before hand-rolling or hanging controls outside the component.
+- Prefer configuring the highest-level component (e.g. `CometChatConversations`) over rebuilding it from base components.
+- **Reuse built-in triggers before hand-rolling UI.** Map each requested action to an existing prop/callback/slot FIRST; only add custom buttons when none exists. Discovery order: prop table + each prop's "when to use it" note in docs → if undescribed, fetch the component's `.md` twin (`../cometchat-react-v7-core/references/docs-map.md`) → then custom. Known wiring points: `CometChatMessageHeader` `onItemClick` (open user/group profile on header click) and `onSearchOptionClicked` (built-in search button, `showSearchOption` default `true`); `CometChatConversations` `onSearchBarClicked` (conversation search); `CometChatMessageList` `onThreadRepliesClick` (thread panel). See AUDIT-006.
+
+## Creating a group (host-composed — NO kit component; offer ALL THREE types incl. password)
+v7 ships **no `CometChatCreateGroup` component** — the create-group form is HOST-BUILT. Build it from the **`guide-group-chat-setup`** guide (docs-map "Task guides"), which shows the full form. **It MUST offer all THREE group types — Public · Private · Password-protected — not just public/private (AUDIT-081).** The Password type REQUIRES a password field; create the group with the Chat SDK (symbols verified vs installed 7.x SDK):
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+// type ∈ CometChat.GROUP_TYPE.PUBLIC | .PRIVATE | .PASSWORD   ("public" | "private" | "password")
+const group = new CometChat.Group(guid, groupName, CometChat.GROUP_TYPE.PASSWORD, password); // 4th arg = password (REQUIRED for the PASSWORD type)
+await CometChat.createGroup(group);
+```
+Show the password input ONLY when the Password type is chosen, and require it before submit (public/private need no password). Dropping the Password option (offering only public/private) is a create-group defect — the SDK (`Group(guid, name, type, password?)`, `GROUP_TYPE.PASSWORD`) and the guide both support it.
+
+## Banned members — view + unban (SDK fallback; NO kit component or UI-Kit doc)
+The group-details contract requires **`view-banned-members`**, but v7 ships **no banned-members drop-in** — `CometChatGroupMembers` shows only ACTIVE members (it exposes the ban ACTION via `hideBanMemberOption`, not a banned view), and the UI-Kit guide/component docs don't cover viewing banned users (AUDIT-082). So surface them via the **Chat SDK** (UI-Kit-first → SDK-fallback, `RULES.md` §13; symbols verified vs installed 7.x SDK + documented at `sdk/javascript/group-kick-ban-members`). Add a **scope-gated** "Banned members" affordance in group details (admins/owners only):
+```tsx
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+// FETCH — paginate by calling fetchNext() again on the SAME request object (max limit 100)
+const req = new CometChat.BannedMembersRequestBuilder(guid).setLimit(30).build(); // .setSearchKeyword(kw) optional
+const banned = await req.fetchNext();          // Promise<CometChat.GroupMember[]>
+
+// UNBAN (admin/owner only), then refresh the list
+await CometChat.unbanGroupMember(guid, uid);   // Promise<boolean>
+```
+Gate the whole affordance on the logged-in user's group scope (`admin`/`owner`) — a plain member shouldn't see it. Render the banned list with an "Unban" action per row (refresh on success). Mirrors the official sample app's "Banned Members" section (the `sample_banned_members` string). This closes the ban round-trip: ban (in `CometChatGroupMembers`) → view banned → unban.
+
+## Common pitfalls (BAKED)
+- **Default-on affordances that need stitching.** A drop-in can render a live-looking control BY DEFAULT that no-ops until the host wires a callback + companion panel. When FETCHing props, flag these and either wire or hide them — never let one dead-end. Known cases (v7): `CometChatConversations` `showSearchBar` (default `true`) only client-side-filters loaded names → wire `onSearchBarClicked`→`CometChatSearch` or set `showSearchBar={false}`; `CometChatMessageList` thread-reply indicator → wire `onThreadRepliesClick` + thread panel or set `hideReplyInThreadOption`. See `features.json` `needs_stitching` and AUDIT.md.
+- Emitting a **contracted** component (e.g. `CometChatConversations`, `CometChatGroupMembers`) without its FULL `contracts.json` min_capabilities ships an incomplete/inconsistent screen — include the full minimum every time (a group details screen MUST have view/add/kick/ban/banned/scope).
+- **Create-group form offering only Public/Private (AUDIT-081).** No kit create-group component exists, so the form is host-built — it MUST include the **Password-protected** type (with a password field required on submit), not just public/private. See "Creating a group" above.
+- Referencing a component that isn't in the catalog (phantom). Rebuilding a drop-in from base parts when a prop/slot exists. Assuming v6 prop names — v7 changed the composition model; fetch current props.
+
+## Verify it works
+The component renders and its data populates (list fills, message sends). If it's empty, confirm it's inside `CometChatProvider` with a logged-in user.