@cometchat/skills 4.3.0 → 4.4.0

package/skills/cometchat-react-calls/references/recording-screen-share.md

@@ -13,35 +13,39 @@ Recording is a paid feature gated by your CometChat plan. Enable it in **Dashboa
 ### Client-side: opt-in per session
 
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .setIsAudioOnly(false)
-  .enableRecording(true)                       // ← server starts recording when session begins
-  .setShowRecordingButton(true)                // ← user-toggleable mid-call
-  .build();
+// SessionSettings object passed to joinSession(token, settings, container).
+// These are object fields — NOT CallSettingsBuilder methods (the v4 builder had
+// enableRecording/setShowRecordingButton; v5 uses the object below).
+const settings = {
+  sessionType: 'VIDEO',          // 'VOICE' for audio-only (replaces setIsAudioOnly)
+  autoStartRecording: true,      // ← server starts recording when the session begins
+  hideRecordingButton: false,    // ← keep the user-toggleable Record button visible
+};
 ```
 
-Two flags, two behaviors:
+Two fields, two behaviors:
 
-- `enableRecording(true)` — recording starts the moment the session begins. Server-side flag.
-- `setShowRecordingButton(true)` — exposes a "Record" toggle in the default control panel. User decides when to start/stop. Custom-UI code must wire its own button.
+- `autoStartRecording: true` — recording starts the moment the session begins. Server-side flag.
+- `hideRecordingButton: false` — exposes a "Record" toggle in the default control panel. User decides when to start/stop. Custom-UI code must wire its own button (`CometChatCalls.startRecording()` / `stopRecording()` — there is no `toggleRecording()`; track state yourself and call the right one).
 
 **Compliance note:** in some jurisdictions you must notify all participants before recording starts. The default kit UI shows a small "Recording" indicator; if you're using custom UI, you must render this yourself. The skill's verification checklist flags this.
 
 ### Recording lifecycle events
 
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onRecordingStarted: (rec: unknown) => {
-    // server confirmed recording is active
-  },
-  onRecordingStopped: (rec: unknown) => {
-    // server stopped — file will appear in dashboard within ~30 seconds
-  },
-  onRecordingFailed: (error: unknown) => {
-    // surface to UI — usually plan limits or storage quota
-  },
+// v5 uses the static event bus; addEventListener returns an unsubscribe fn.
+const offStarted = CometChatCalls.addEventListener("onRecordingStarted", () => {
+  // server confirmed recording is active
 });
+const offStopped = CometChatCalls.addEventListener("onRecordingStopped", () => {
+  // server stopped — file will appear in dashboard within ~30 seconds
+});
+// Cleanup when the call ends: offStarted(); offStopped();
+//
+// NOTE: there is no `onRecordingFailed` event on the v5 bus (and no
+// onRecordingFailed member on OngoingCallListener). Plan-limit / storage-quota
+// failures surface as a rejection from generateToken/joinSession or a server
+// error — handle those, not a dedicated recording-failed callback.
 ```
 
 ### Where the recordings go
@@ -54,7 +58,7 @@ CometChat hosts the file. It appears in **Dashboard → Calls → Recordings** w
 
 ### Two roles: presenter + viewer
 
-- **Presenter** (the user sharing their screen) — calls `CometChatCalls.startScreenShare()` and receives a `MediaStream` from `getDisplayMedia`
+- **Presenter** (the user sharing their screen) — calls `CometChatCalls.startScreenSharing()`; the SDK handles `getDisplayMedia` + signaling internally
 - **Viewer** (everyone else) — sees the presenter's screen as another video tile, no special API call needed
 
 Browser support: Chrome/Edge (full), Firefox (full), Safari 13+ (full). On mobile browsers, `getDisplayMedia` is supported on iOS 16+ Safari and recent Android Chrome.
@@ -64,7 +68,7 @@ Browser support: Chrome/Edge (full), Firefox (full), Safari 13+ (full). On mobil
 ```ts
 async function startScreenShare() {
   try {
-    await CometChatCalls.startScreenShare();
+    CometChatCalls.startScreenSharing();
     // SDK handled getDisplayMedia + signaling; UI updates via onScreenShareStarted
   } catch (err: unknown) {
     if ((err as Error).name === "NotAllowedError") {
@@ -79,37 +83,34 @@ async function startScreenShare() {
 Stop sharing:
 
 ```ts
-CometChatCalls.endScreenShare();
+CometChatCalls.stopScreenSharing();
 ```
 
-The browser also fires its own "Stop sharing" button (the system overlay Chrome shows during a screen-share). The SDK listens for this too; `onScreenShareEnded` fires either way.
+The browser also fires its own "Stop sharing" button (the system overlay Chrome shows during a screen-share). The SDK listens for this too; `onScreenShareStopped` fires either way.
 
 ### Viewer — listen for screen-share events
 
 ```ts
-const listener = new CometChatCalls.OngoingCallListener({
-  onScreenShareStarted: (presenterUid: string, stream: MediaStream) => {
-    // attach the stream to a <video> element
-    if (screenShareVideoRef.current) {
-      screenShareVideoRef.current.srcObject = stream;
-    }
-  },
-  onScreenShareEnded: () => {
-    if (screenShareVideoRef.current) {
-      screenShareVideoRef.current.srcObject = null;
-    }
-  },
+// The v5 bus callbacks take NO arguments — they're notifications, not stream
+// handoffs. The SDK renders the presenter's screen as a tile in its own layout;
+// you don't receive a MediaStream to attach yourself (that was the v4 model).
+const offStart = CometChatCalls.addEventListener("onScreenShareStarted", () => {
+  setSomeoneSharing(true);
+});
+const offStop = CometChatCalls.addEventListener("onScreenShareStopped", () => {
+  setSomeoneSharing(false);
 });
+// Cleanup: offStart(); offStop();
 ```
 
-Compose the screen-share tile alongside the camera tiles in your custom layout.
+The SDK composes the screen-share tile alongside the camera tiles automatically. (Truly hand-rendering the shared stream requires the deprecated `OngoingCallListener` + `startSession` track-level path — see `custom-ui.md`.)
 
 ### Audio passthrough during screen share
 
 By default, `getDisplayMedia` captures video only. To capture system audio (for sharing a video with sound), pass `audio: true`:
 
 ```ts
-// Browser-level API — the SDK's startScreenShare wraps this internally
+// Browser-level API — the SDK's startScreenSharing wraps this internally
 const stream = await navigator.mediaDevices.getDisplayMedia({
   video: true,
   audio: true,
@@ -118,7 +119,7 @@ const stream = await navigator.mediaDevices.getDisplayMedia({
 
 Browser support is uneven — Chrome desktop has it; Firefox does not; Safari has it for tab capture but not full-screen.
 
-The Calls SDK's `startScreenShare()` does NOT request audio by default in v4. If you need audio passthrough, use the lower-level `getDisplayMedia` API directly + pipe the audio track via a custom track-add hook (covered in `custom-ui.md`).
+The Calls SDK's `startScreenSharing()` does NOT request audio by default. If you need audio passthrough, use the lower-level `getDisplayMedia` API directly + pipe the audio track via a custom track-add hook (covered in `custom-ui.md`).
 
 ---
 

package/skills/cometchat-react-calls/references/ringing-integration.md

@@ -242,7 +242,7 @@ function IncomingCallScreen({ call, onAccept, onReject }: Props) {
 - [ ] `onCallEndedMessageReceived` tears down UI when other party ends
 - [ ] `onIncomingCallCancelled` tears down UI when caller cancels mid-ring
 - [ ] Custom UI: `role="alertdialog"`, ringtone audio, accept/decline buttons with aria-labels
-- [ ] Smoke: 2 tabs, caller initiates → recipient sees custom incoming UI → accept → both join session → either ends → both UIs dismiss
+- [ ] Smoke: **two ISOLATED browser contexts** (normal + Incognito window, or two browsers/devices — NOT two tabs of one browser; the Chat SDK is a single shared session per origin, so a second tab can't be an independent callee), caller initiates → recipient sees custom incoming UI → accept → both join session → either ends → both UIs dismiss
 
 ---
 
@@ -251,5 +251,5 @@ function IncomingCallScreen({ call, onAccept, onReject }: Props) {
 - `cometchat-react-calls/SKILL.md` — architecture + seven hard rules
 - `cometchat-react-calls/references/call-session.md` — Mode 3 (joinSession with no ringing)
 - `cometchat-react-calls/references/in-call-chat.md` — chat panel during a call
-- `cometchat-react-calls/references/recording.md` — recording mid-call
+- `cometchat-react-calls/references/recording-screen-share.md` — recording mid-call
 - Canonical docs: https://www.cometchat.com/docs/calls/javascript/ringing

package/skills/cometchat-react-calls/references/share-invite.md

@@ -35,10 +35,9 @@ const callSettings = {
 ```tsx
 useEffect(() => {
   const handler = () => shareCallInvite(sessionId);
-  CometChatCalls.addEventListener("onShareInviteButtonClicked", handler);
-  return () => {
-    CometChatCalls.removeEventListener("onShareInviteButtonClicked", handler);
-  };
+  // addEventListener returns an unsubscribe fn — there is no removeEventListener.
+  const off = CometChatCalls.addEventListener("onShareInviteButtonClicked", handler);
+  return () => off();
 }, [sessionId]);
 ```
 
@@ -128,7 +127,7 @@ function CallQR({ sessionId }: { sessionId: string }) {
 2. **Wiring share before the deep-link route works.** Recipients click → 404.
 3. **`navigator.clipboard.writeText` without a manual-copy fallback.** Fails in non-https contexts (e.g., embedded iframes, dev tunnels).
 4. **Showing "Link copied!" toast even when share was cancelled.** `AbortError` is the user dismissing the share sheet — silent.
-5. **Forgetting `removeEventListener` on unmount.** Listener accumulates → multiple share sheets per click.
+5. **Forgetting to call the unsubscribe fn on unmount.** `addEventListener` returns a `() => void` — call it in cleanup (there is no `removeEventListener`). Otherwise the listener accumulates → multiple share sheets per click.
 6. **Hard-coding `https://yourapp.com`.** Use `window.location.origin` or `import.meta.env.VITE_APP_URL`.
 
 ---

package/skills/cometchat-react-calls/references/testing-calls-on-web.md

@@ -10,6 +10,25 @@ This reference covers all three. For chat-side testing patterns, see `cometchat-
 
 ---
 
+## ⚠️ Ringing-mode manual testing needs TWO ISOLATED browser contexts (not two tabs)
+
+The single most common "incoming call never rings / Accept never appears" report is a **test-setup** problem, not a code bug:
+
+**The Chat SDK is one session per browser origin.** `CometChat.login()` persists the logged-in user in **IndexedDB/localStorage keyed by `appId`** and maintains **one WebSocket per origin** — both **shared across every tab** of `localhost:5173`. Two tabs in the *same* browser therefore CANNOT hold two different logins: the second tab's login overwrites the shared session, so there is no independent callee connected to receive `onIncomingCallReceived`. A per-tab `sessionStorage` "user switcher" only changes what *your app* thinks the user is — the Chat SDK underneath is still a single shared session.
+
+- **Ringing mode (1:1 / `initiateCall` → `onIncomingCallReceived`)** → needs **two isolated contexts**: a normal window for the caller + an **Incognito/Private window** (or a different browser, or a second device) for the callee. Only then are there two distinct Chat-SDK sessions + sockets.
+- **Session/meeting mode (`joinSession` on a shared `sessionId`)** → two tabs in the *same* browser are fine — it doesn't depend on two live Chat-SDK logins; both sides just join the same session id.
+
+Sanity-check in the callee context's console — it must show the callee, not the caller:
+```js
+await CometChat.getLoggedinUser()   // → User { uid: "cometchat-uid-2", ... }
+```
+If it shows the caller's uid (or `null`), the callee isn't an independent receiver — that's the shared-session symptom.
+
+Two devices on a LAN need HTTPS for `getUserMedia` (secure-context), but the ring itself arrives over plain `localhost` in incognito.
+
+---
+
 ## 1. Unit tests — mock the SDK module
 
 Vitest's `vi.mock` with a hoisted factory:
@@ -37,8 +56,7 @@ vi.mock("@cometchat/calls-sdk-javascript", () => ({
     startSession: vi.fn(),
     endSession: vi.fn(),
     CallSettingsBuilder: class {
-      setSessionID() { return this; }
-      setIsAudioOnly() { return this; }
+      setIsAudioOnlyCall() { return this; }
       enableDefaultLayout() { return this; }
       build() { return {}; }
     },

package/skills/cometchat-react-calls/references/virtual-background.md

@@ -0,0 +1,32 @@
+# Virtual Background (web)
+
+Verified against `@cometchat/calls-sdk-javascript@5`. Web (React/Angular) is one of the few platforms that supports virtual background (native iOS/Android do not). Two ways to expose it:
+
+## A. Let the kit show its built-in setting (additive / kit components)
+
+Enable the kit's own Virtual Background button on the call settings builder — it renders a blur/image/clear picker inside the call UI, no custom code:
+
+```ts
+const settings = new CometChatCalls.CallSettingsBuilder()
+  .enableDefaultLayout(true)
+  .showVirtualBackgroundSetting(true)   // ← shows the built-in VB control
+  .build();
+```
+
+To read the current state, call `getVirtualBackground()` on a built `CallSettings` instance — it's an **instance** method on `CallSettings` (`callSettings.getVirtualBackground(): VirtualBackground`), not a `CometChatCalls` static.
+
+## B. Apply programmatically (custom call surface)
+
+Three static methods on `CometChatCalls`, callable during an active session:
+
+```ts
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+
+CometChatCalls.setVirtualBackgroundBlurLevel(50);              // blur (0–100)
+CometChatCalls.setVirtualBackgroundImage("https://…/bg.jpg");  // custom image
+CometChatCalls.clearVirtualBackground();                        // remove
+```
+
+> The older `setBackgroundBlur()` / `setBackgroundImage()` names are **deprecated** — use the `setVirtualBackground*` forms above.
+
+Verified (calls-sdk `index.d.ts`): `CallSettingsBuilder.showVirtualBackgroundSetting(boolean)`, instance `CallSettings.getVirtualBackground(): VirtualBackground`, and the statics `CometChatCalls.setVirtualBackgroundBlurLevel(number)` / `setVirtualBackgroundImage(string)` / `clearVirtualBackground()`.

package/skills/cometchat-react-patterns/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-react-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into React projects (Vite or CRA). Covers provider setup, routing, layout integration, env vars, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; Vite >=4 or react-scripts (CRA); @cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat react vite cra patterns provider routing integration"
 ---
 
+> **Ground truth:** `@cometchat/chat-uikit-react@^6` (+ `@cometchat/calls-sdk-javascript@^5`) — installed package types + `ui-kit/react`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/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 teaches Claude how to integrate CometChat into a React project that uses Vite or Create React App. These are client-only environments with no SSR, which simplifies integration significantly.
@@ -84,7 +85,12 @@ async function ensureLoggedIn(
   authToken?: string,
 ): Promise<void> {
   const existing = await CometChatUIKit.getLoggedinUser();
-  if (existing) return;
+  if (existing && existing.getUid?.() === uid) return;   // same user — done
+  // Different user logged in (account switch / logout→login-as-other): log out
+  // first, else login() silently no-ops and the app shows the old account.
+  // (Switching accounts requires an explicit logout — login() no-ops on an
+  // existing session.)
+  if (existing) await CometChatUIKit.logout();
   if (loginInFlight) {
     await loginInFlight;  // a prior mount already started login — reuse its promise
     return;
@@ -127,7 +133,8 @@ export function CometChatProvider({ children }: CometChatProviderProps) {
 
         setIsReady(true);
       } catch (e) {
-        setError(String(e));
+        setError(formatCometChatError(e)); // from cometchat-core §6 errors.ts — NOT String(e),
+                                           // which renders "[object Object]" on kit errors (ENG-35719)
       }
     }
 
@@ -474,6 +481,9 @@ CometChat components fill 100% of their container. Two visual bugs to avoid:
 
 **Bug 1 — zero height:** components render with zero height because the container has no explicit dimensions.
 **Bug 2 — message list grows past the viewport:** the list scrolls fine until it has too many messages, then pushes the composer below the fold. **This is the classic flex-shrink trap.**
+**Bug 3 — list won't scroll at all even with a bounded parent:** the height chain looks right but the list still grows/clips instead of scrolling. **Cause: the kit renders a `.cometchat` flex element as the immediate child inside your list wrapper, and `CometChatMessageList`'s own `height: 100%` only resolves if that injected element also has a height.** Inline styles can't target an auto-injected child, so you MUST add a real CSS child rule. This is the #1 cause of "I set height everywhere and it still won't scroll."
+
+**The full height chain must reach a definite height** — `html, body { height: 100% }` and `#root { height: 100vh }` (NOT `min-height` — `min-height` lets the container grow with content, so the list never gets a bound to scroll within). Vite/CRA starter CSS ships `#root { min-height: 100vh; max-width: 1280px; ... }` — delete it.
 
 The hard rule for two-pane / header+list+composer layouts: every flex container in the chain MUST have `minHeight: 0` (and `minWidth: 0` for horizontal flex). Without it, browsers default flex-children to `min-height: auto` (their intrinsic content size), so the list grows beyond the parent's bounds as messages accumulate.
 
@@ -536,9 +546,39 @@ The hard rule for two-pane / header+list+composer layouts: every flex container
 
 **Why `minHeight: 0` is non-obvious:** the W3C spec sets the default `min-height` of a flex item to `auto` (its intrinsic content height). For a scrollable list inside a flex column, this means the list refuses to shrink below its content even when the parent is bounded. Setting `minHeight: 0` on the flex parent overrides this, letting the list shrink and scroll within the bounded container instead of overflowing it.
 
+**The kit-injected `.cometchat` wrapper (the part inline styles can't fix).** `CometChatMessageList` renders a `.cometchat` flex element as its outermost node, with `.cometchat-message-list { height: 100% }` inside it. If you wrap the list in your own div, that injected `.cometchat` sits between your div and the list — and a percentage `height: 100%` resolves to `auto` against an auto-height parent, so the list grows/clips instead of scrolling. Give the list its own wrapper **class** and add a child rule (this is exactly what the kit's own sample app does — `.cometchat-message-list-wrapper > .cometchat`):
+
+```tsx
+// JSX — wrap the LIST (header/composer can stay direct siblings)
+<div style={{ display: "flex", flexDirection: "column", height: "100%", minHeight: 0 }}>
+  <CometChatMessageHeader user={user} />
+  <div className="cc-msg-list">
+    <CometChatMessageList user={user} />
+  </div>
+  <CometChatMessageComposer user={user} />
+</div>
+```
+
+```css
+/* CSS — TWO load-bearing lines, both required (verified at runtime in Chromium
+   against kit 6.5, 2026-06-13):
+   1. .cc-msg-list needs an EXPLICIT `height: 100%`, NOT just `flex: 1 1 0`. A height
+      that comes only from flex-grow is treated as INDEFINITE by Chromium/Safari, so
+      the kit's injected `.cometchat` child's `height: 100%` collapses to auto (content
+      height) and the list overflows/clips instead of scrolling. The explicit height
+      (resolving against the definite-height column) makes it definite so the % resolves.
+      `flex: 1 1 0; min-height: 0` still sizes it correctly in the column — keep them too.
+   2. The `> .cometchat` child rule — inline styles cannot target the kit's
+      auto-injected child, so it MUST live in a stylesheet. */
+.cc-msg-list { flex: 1 1 0; min-height: 0; height: 100%; overflow: hidden; }
+.cc-msg-list > .cometchat { height: 100%; overflow: hidden; }
+```
+
+> ⚠️ **The `height: 100%` on `.cc-msg-list` is non-negotiable and easy to miss.** A wrapper sized purely by `flex: 1 1 0` measures correctly (e.g. 645px) but Chromium still treats that height as *indefinite* for percentage-height children, so `.cometchat` falls back to content height (e.g. 1014px) and the messages clip silently with no scrollbar. This is the #1 "I followed the recipe and it still won't scroll" trap. The column that contains `.cc-msg-list` must itself have a definite height (the `height: 100%` + `minHeight: 0` flex column above, anchored to a definite-height `#root`).
+
 **The rule, restated as something to grep for:**
 
-> Every flex container that holds `CometChatMessageList` (directly or indirectly) MUST have `minHeight: 0` on it. Same for `minWidth: 0` on horizontal flex parents. Skip this and the layout works for short conversations and breaks for long ones.
+> Every flex container that holds `CometChatMessageList` (directly or indirectly) MUST have `minHeight: 0`. Same for `minWidth: 0` on horizontal flex parents. AND when you wrap the list, add a `.your-list-wrapper > .cometchat { height: 100%; overflow: hidden }` CSS rule for the kit's injected child — without it the list won't scroll no matter how many heights you set inline. The full chain (`html`/`body`/`#root`) must use a definite `height`, never `min-height`.
 
 ### Vite dependency optimization