@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-react-calls/references/device-management.md

@@ -12,32 +12,35 @@ Camera / mic / speaker enumeration + switching mid-call. SDK exposes `getAudioIn
 ```ts
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-// Enumerate
-const mics = await CometChatCalls.getAudioInputDevices();
-const speakers = await CometChatCalls.getAudioOutputDevices();
-const cameras = await CometChatCalls.getVideoInputDevices();
+// Enumerate — these getters are SYNCHRONOUS (they return arrays, not promises;
+// do NOT `await` them).
+const mics = CometChatCalls.getAudioInputDevices();
+const speakers = CometChatCalls.getAudioOutputDevices();
+const cameras = CometChatCalls.getVideoInputDevices();
 
 // Currently selected
 const currentMic = CometChatCalls.getCurrentAudioInputDevice();
 
-// Switch (mid-call OK)
-await CometChatCalls.setAudioInputDevice(deviceId);
-await CometChatCalls.setAudioOutputDevice(deviceId);
-await CometChatCalls.setVideoInputDevice(deviceId);
+// Switch (mid-call OK) — also synchronous, return void.
+CometChatCalls.setAudioInputDevice(deviceId);
+CometChatCalls.setAudioOutputDevice(deviceId);
+CometChatCalls.setVideoInputDevice(deviceId);
 
-// Listen for device changes (user plugs in headphones, etc.)
-CometChatCalls.addEventListener("onAudioModesUpdated", (devices) => {
+// Listen for device changes (user plugs in headphones, etc.). The valid event
+// keys are onAudioInputDevicesChanged / onAudioOutputDevicesChanged /
+// onVideoInputDevicesChanged (there is NO "onAudioModesUpdated"). addEventListener
+// returns an unsubscribe function — there is no removeEventListener.
+const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", (devices) => {
   // re-enumerate; show toast "AirPods connected"
 });
+// later: off();
 ```
 
-Each device looks like:
+Each device is a standard `MediaDeviceInfo` (the SDK types are `AudioInputDevice = MediaDeviceInfo & { kind: 'audioinput' }`, etc.). The fields you use:
 ```ts
-interface MediaDevice {
-  id: string;          // browser-assigned ID
-  label: string;       // "Built-in Microphone", "AirPods Pro"
-  // ... other fields per browser
-}
+// deviceId: string   ← the ID you pass to setAudioInputDevice() (NOT `id`)
+// label:    string   ← "Built-in Microphone" / "AirPods Pro" (empty until mic permission granted)
+// kind:     'audioinput' | 'videoinput' | 'audiooutput'
 ```
 
 ---
@@ -48,12 +51,11 @@ interface MediaDevice {
 import { useEffect, useState } from "react";
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-interface MediaDevice { id: string; label: string; }
-
 function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
-  const [mics, setMics] = useState<MediaDevice[]>([]);
-  const [cameras, setCameras] = useState<MediaDevice[]>([]);
-  const [speakers, setSpeakers] = useState<MediaDevice[]>([]);
+  // Devices are MediaDeviceInfo objects — use `deviceId`, NOT `id`.
+  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
+  const [cameras, setCameras] = useState<MediaDeviceInfo[]>([]);
+  const [speakers, setSpeakers] = useState<MediaDeviceInfo[]>([]);
   const [selectedMic, setSelectedMic] = useState<string>();
   const [selectedCamera, setSelectedCamera] = useState<string>();
   const [selectedSpeaker, setSelectedSpeaker] = useState<string>();
@@ -67,24 +69,24 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
         // permission denied — labels will be empty; offer settings link
       }
 
-      const [m, c, s] = await Promise.all([
-        CometChatCalls.getAudioInputDevices(),
-        CometChatCalls.getVideoInputDevices(),
-        CometChatCalls.getAudioOutputDevices(),
-      ]);
+      // These getters are SYNCHRONOUS — no await / Promise.all needed.
+      const m = CometChatCalls.getAudioInputDevices();
+      const c = CometChatCalls.getVideoInputDevices();
+      const s = CometChatCalls.getAudioOutputDevices();
       setMics(m); setCameras(c); setSpeakers(s);
 
-      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.id ?? m[0]?.id);
-      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.id ?? c[0]?.id);
-      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.id ?? s[0]?.id);
+      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.deviceId ?? m[0]?.deviceId);
+      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.deviceId ?? c[0]?.deviceId);
+      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.deviceId ?? s[0]?.deviceId);
     }
     load();
   }, []);
 
-  async function confirm() {
-    if (selectedMic) await CometChatCalls.setAudioInputDevice(selectedMic);
-    if (selectedCamera) await CometChatCalls.setVideoInputDevice(selectedCamera);
-    if (selectedSpeaker) await CometChatCalls.setAudioOutputDevice(selectedSpeaker);
+  function confirm() {
+    // setters are synchronous, return void
+    if (selectedMic) CometChatCalls.setAudioInputDevice(selectedMic);
+    if (selectedCamera) CometChatCalls.setVideoInputDevice(selectedCamera);
+    if (selectedSpeaker) CometChatCalls.setAudioOutputDevice(selectedSpeaker);
     onConfirm();
   }
 
@@ -93,19 +95,19 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
       <label>
         Microphone
         <select value={selectedMic} onChange={(e) => setSelectedMic(e.target.value)}>
-          {mics.map(d => <option key={d.id} value={d.id}>{d.label || `Mic ${d.id.slice(0, 6)}`}</option>)}
+          {mics.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Mic ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <label>
         Camera
         <select value={selectedCamera} onChange={(e) => setSelectedCamera(e.target.value)}>
-          {cameras.map(d => <option key={d.id} value={d.id}>{d.label || `Camera ${d.id.slice(0, 6)}`}</option>)}
+          {cameras.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Camera ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <label>
         Speaker
         <select value={selectedSpeaker} onChange={(e) => setSelectedSpeaker(e.target.value)}>
-          {speakers.map(d => <option key={d.id} value={d.id}>{d.label || `Speaker ${d.id.slice(0, 6)}`}</option>)}
+          {speakers.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Speaker ${d.deviceId.slice(0, 6)}`}</option>)}
         </select>
       </label>
       <button type="button" onClick={confirm}>Join call</button>
@@ -123,21 +125,23 @@ function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
 ```tsx
 function InCallDeviceSettings() {
   const [showMenu, setShowMenu] = useState(false);
-  const [mics, setMics] = useState<MediaDevice[]>([]);
+  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
 
   useEffect(() => {
     if (!showMenu) return;
-    CometChatCalls.getAudioInputDevices().then(setMics);
-    
-    const onModesUpdated = () => {
-      CometChatCalls.getAudioInputDevices().then(setMics);
-    };
-    CometChatCalls.addEventListener("onAudioModesUpdated", onModesUpdated);
-    return () => CometChatCalls.removeEventListener("onAudioModesUpdated", onModesUpdated);
+    // getAudioInputDevices() is synchronous — returns an array, no .then().
+    setMics(CometChatCalls.getAudioInputDevices());
+
+    // addEventListener returns an unsubscribe fn — call it to clean up
+    // (there is no removeEventListener on the SDK).
+    const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", () => {
+      setMics(CometChatCalls.getAudioInputDevices());
+    });
+    return () => off();
   }, [showMenu]);
 
-  async function selectMic(id: string) {
-    await CometChatCalls.setAudioInputDevice(id);
+  function selectMic(id: string) {
+    CometChatCalls.setAudioInputDevice(id);   // synchronous, returns void
     setShowMenu(false);
   }
 
@@ -147,8 +151,8 @@ function InCallDeviceSettings() {
       {showMenu && (
         <ul role="menu">
           {mics.map(d => (
-            <li key={d.id}>
-              <button role="menuitem" onClick={() => selectMic(d.id)}>{d.label}</button>
+            <li key={d.deviceId}>
+              <button role="menuitem" onClick={() => selectMic(d.deviceId)}>{d.label}</button>
             </li>
           ))}
         </ul>
@@ -158,7 +162,7 @@ function InCallDeviceSettings() {
 }
 ```
 
-`onAudioModesUpdated` fires when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
+`onAudioInputDevicesChanged` (and `onAudioOutputDevicesChanged` / `onVideoInputDevicesChanged`) fire when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
 
 ---
 
@@ -179,7 +183,7 @@ if (safari) {
 ## Anti-patterns
 
 1. **Calling `getAudioInputDevices` before requesting permission.** Returns devices with empty `label` strings — UI shows "undefined" or empty entries.
-2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioModesUpdated`.
+2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioInputDevicesChanged`.
 3. **Hardcoding the first device as default.** Browsers may sort differently (built-in vs USB). Read `getCurrent*Device` first; only fall back to first if no current selection.
 4. **Switching speakers in Safari.** `setAudioOutputDevice` silently fails. Detect Safari and hide the speaker picker (or show a "iOS uses system routing" tooltip).
 5. **No listener cleanup on unmount.** Event accumulates listeners on remount; spam every device change.
@@ -190,7 +194,7 @@ if (safari) {
 
 - [ ] Permission requested before enumeration (empty-label fix)
 - [ ] `getCurrent*Device()` used as default in pickers
-- [ ] `onAudioModesUpdated` listener for hot-swap detection
+- [ ] `onAudioInputDevicesChanged` listener for hot-swap detection (unsubscribe via the returned fn)
 - [ ] Listener cleanup on unmount
 - [ ] Safari speaker picker hidden / fallback message
 - [ ] Browser smoke: plug/unplug headphones during call, picker updates

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

@@ -106,19 +106,17 @@ async function startGroupCall(guid: string, callType: "audio" | "video") {
   const authToken = loggedInUser.getAuthToken();
   const { token: callToken } = await CometChatCalls.generateToken(sessionId);
 
-  const callSettings = new CometChatCalls.CallSettingsBuilder()
-    .setIsAudioOnlyCall(callType === "audio")
-    .enableDefaultLayout(true)
-    .setCallListener(
-      new CometChatCalls.OngoingCallListener({
-        onCallEnded: () => { /* hangup UI */ },
-        onError: (err) => { /* show error */ },
-      }),
-    )
-    .build();
+  // joinSession takes a SessionSettings OBJECT (NOT CallSettingsBuilder.build() —
+  // that CallSettings is for the deprecated startSession). Events come from the
+  // static addEventListener bus, not OngoingCallListener.
+  const settings = { sessionType: callType === "audio" ? "VOICE" : "VIDEO" };
+  const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => {
+    /* hangup UI */
+  });
+  // later, on teardown: offClosed();
 
   // 3. Mount the WebRTC view into your container element
-  await CometChatCalls.joinSession(callToken, callSettings, containerElement);
+  await CometChatCalls.joinSession(callToken, settings, containerElement);
 }
 ```
 
@@ -182,17 +180,14 @@ async function joinGroupCall(sessionId: string, callType: "audio" | "video", con
   const authToken = loggedInUser!.getAuthToken();
   const { token: callToken } = await CometChatCalls.generateToken(sessionId);
 
-  const callSettings = new CometChatCalls.CallSettingsBuilder()
-    .setIsAudioOnlyCall(callType === "audio")
-    .enableDefaultLayout(true)
-    .setCallListener(
-      new CometChatCalls.OngoingCallListener({
-        onCallEnded: () => { /* hangup UI */ },
-      }),
-    )
-    .build();
-
-  await CometChatCalls.joinSession(callToken, callSettings, container);
+  // SessionSettings OBJECT for joinSession (not CallSettingsBuilder output).
+  const settings = { sessionType: callType === "audio" ? "VOICE" : "VIDEO" };
+  const offClosed = CometChatCalls.addEventListener("onConnectionClosed", () => {
+    /* hangup UI */
+  });
+  // later, on teardown: offClosed();
+
+  await CometChatCalls.joinSession(callToken, settings, container);
 }
 ```
 
@@ -259,4 +254,4 @@ Since meetings don't ring, there's no "missed call" entity. If you want missed-m
 - `call-session.md` — pure session-mode (URL-based, no chat-side signaling at all)
 - `cometchat-react-calls/SKILL.md` rule 1.7 — IncomingCall mount (1:1 only; group calls don't use this)
 - Canonical docs: https://www.cometchat.com/docs/calls/javascript/group-calls
-- Kit source (verified 2026-05-15): `node_modules/@cometchat/chat-uikit-react-native/src/calls/CometChatCallButtons/CometChatCallButtons.tsx:138-201`
+- Kit source (web React): `@cometchat/chat-uikit-react` → `src/components/Calling/CometChatCallButtons/CometChatCallButtons.tsx` (group call buttons send the `meeting` custom message)

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

@@ -9,22 +9,34 @@ Auto-ends calls where the local user is the only remaining participant. Two time
 
 ## SDK API
 
+> ⚠️ **VALUES ARE IN MILLISECONDS.** `idleTimeoutPeriodBeforePrompt: 180` is **180 ms**, not 180 seconds — so the prompt fires the instant you join alone and the call exits in a fraction of a second (real customer bug, 2026-06). Always `* 1000`: 3 minutes = `180_000`.
+
+Two equivalent ways to set it — **match whichever your join path uses:**
+
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .setIdleTimeoutPeriodBeforePrompt(60_000)   // 60s — first warning fires
-  .setIdleTimeoutPeriodAfterPrompt(120_000)   // 120s — session ends if no response
-  .build();
+// (a) SessionSettings OBJECT — the session-mode path: joinSession(token, settings, container)
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 180_000,  // 180s before the "still there?" prompt
+  idleTimeoutPeriodAfterPrompt: 60_000,    // 60s grace (this is the SDK MINIMUM)
+};
+await CometChatCalls.joinSession(token, settings, containerRef.current);
+
+// (b) Builder — the kit's callSettingsBuilder prop. ⚠️ The builder has ONLY a
+// single .setIdleTimeoutPeriod(ms) — there are NO setIdleTimeoutPeriodBeforePrompt /
+// setIdleTimeoutPeriodAfterPrompt builder methods. The before/after-prompt SPLIT
+// exists only as the SessionSettings object fields in form (a) above.
+const builder = new CometChatCalls.CallSettingsBuilder()
+  .setIdleTimeoutPeriod(180_000);
 
 CometChatCalls.addEventListener("onSessionTimedOut", () => {
   // Navigate away, show "session ended" UI
 });
 ```
 
-| Setting | Default | Min | Use case |
+| Setting | Default | Min | Unit |
 |---|---|---|---|
-| `idleTimeoutPeriodBeforePrompt` | 60_000 (60s) | 0 (immediate) | Time alone before the "still there?" prompt |
-| `idleTimeoutPeriodAfterPrompt` | 120_000 (120s) | 60_000 (60s) | Grace period after the prompt before forced disconnect |
+| `idleTimeoutPeriodBeforePrompt` | 60_000 (60s) | — (don't use 0 / tiny — instant prompt) | **milliseconds** |
+| `idleTimeoutPeriodAfterPrompt` | 120_000 (120s) | **60_000 (60s)** — smaller is silently clamped to 60s | **milliseconds** |
 
 The SDK shows the prompt overlay automatically (kit's default UI). For custom UI you handle the prompt yourself.
 
@@ -132,10 +144,11 @@ function CustomCallView() {
 ### Pattern B — Long timeouts + custom prompt only
 
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setIdleTimeoutPeriodBeforePrompt(86_400_000)   // 24 hours — effectively disabled
-  .setIdleTimeoutPeriodAfterPrompt(86_400_000)
-  .build();
+// SessionSettings object for joinSession (these before/after fields are object-only).
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 86_400_000,   // 24 hours — effectively disabled
+  idleTimeoutPeriodAfterPrompt: 86_400_000,
+};
 ```
 
 Then implement your own timeout via Pattern A. Useful when you want UX-customized prompts instead of the SDK's default overlay.

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

@@ -10,10 +10,9 @@ Text messaging during a video/voice call. SDK provides the chat button in the co
 ## SDK API
 
 ```ts
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideChatButton(false)               // show the kit's built-in chat button
-  .build();
+// SessionSettings object passed to joinSession(token, settings, container).
+// hideChatButton is a SessionSettings field, not a CallSettingsBuilder method.
+const settings = { hideChatButton: false };   // show the kit's built-in chat button
 
 CometChatCalls.addEventListener("onChatButtonClicked", () => {
   // Open your chat panel
@@ -56,7 +55,7 @@ async function joinCallGroup(sessionId: string): Promise<void> {
 }
 ```
 
-Wire this into your call-start flow: after `startSession` succeeds, `joinCallGroup`.
+Wire this into your call-start flow: after `joinSession` succeeds, `joinCallGroup`.
 
 ---
 
@@ -83,8 +82,9 @@ function InCallChatPanel({ sessionId }: InCallChatPanelProps) {
   // Listen for the SDK's button click
   useEffect(() => {
     const handler = () => setOpen(true);
-    CometChatCalls.addEventListener("onChatButtonClicked", handler);
-    return () => CometChatCalls.removeEventListener("onChatButtonClicked", handler);
+    // addEventListener returns an unsubscribe fn — there is no removeEventListener.
+    const off = CometChatCalls.addEventListener("onChatButtonClicked", handler);
+    return () => off();
   }, []);
 
   // Resolve the group object for the message list

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

@@ -35,8 +35,8 @@ If you're using CometChat UI Kits, this is enough — the kit's calls integratio
 v5 introduces a dedicated Calls SDK auth step. After the user logs into the Chat SDK, call:
 
 ```ts
-const authToken = (await CometChat.getLoggedinUser())!.getAuthToken();
-await CometChatCalls.login(authToken);
+const authToken = (await CometChat.getLoggedInUser())!.getAuthToken();
+await CometChatCalls.loginWithAuthToken(authToken);  // login() takes a uid; use loginWithAuthToken for a token
 ```
 
 After this, `generateToken()` and `joinSession()` no longer need an authToken parameter.
@@ -120,11 +120,10 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 
 - CometChatCalls.startScreenShare()
 + CometChatCalls.startScreenSharing()
-
-- CometChatCalls.enterPIPMode()
-+ CometChatCalls.enablePictureInPictureLayout()
 ```
 
+> PiP rename: v4's `enterPIPMode()` became the static `CometChatCalls.enablePictureInPictureLayout()` in v5 (paired with `disablePictureInPictureLayout()`). Note the `onPictureInPictureLayoutEnabled` / `...Disabled` **callbacks are on `MobileSDKEvents`, not `WebSDKEvents`** — they are NOT subscribable via `CometChatCalls.addEventListener` on the web SDK (verified in `@cometchat/calls-sdk-javascript` `index.d.ts`: `MobileSDKEvents` vs `WebSDKEvents`). On **web**, prefer browser-native picture-in-picture — see `references/picture-in-picture.md`.
+
 ---
 
 ## Step 7 — `startSession` → `joinSession`
@@ -134,14 +133,13 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 -   CometChatCalls.startSession(token, callSettings, container);
 - });
 
-+ CometChatCalls.generateToken(sessionId).then((token) => {
++ CometChatCalls.generateToken(sessionId).then(({ token }) => {
 +   CometChatCalls.joinSession(token, sessionSettings, container);
 + });
-+
-+ // Or — pass the sessionId directly (no manual token mint):
-+ CometChatCalls.joinSession(sessionId, sessionSettings, container);
 ```
 
+> `joinSession`'s first arg is the **callToken** (from `generateToken`), not a sessionId — there is no token-free join. `generateToken` resolves to `{ token }`, so destructure it.
+
 ---
 
 ## Removed methods (no v5 replacement)
@@ -154,7 +152,7 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 ## Verification checklist
 
 - [ ] `package.json` lists `@cometchat/calls-sdk-javascript@^5`
-- [ ] `await CometChatCalls.login(authToken)` called after `CometChat.login`
+- [ ] `await CometChatCalls.loginWithAuthToken(authToken)` called after `CometChat.login`
 - [ ] `OngoingCallListener` removed; granular `addEventListener` calls in place with cleanup
 - [ ] `startSession` replaced with `joinSession`
 - [ ] `endSession` replaced with `leaveSession`
@@ -169,4 +167,4 @@ After this, `generateToken()` and `joinSession()` no longer need an authToken pa
 - Canonical migration guide: https://www.cometchat.com/docs/calls/javascript/migration-guide-v5
 - `cometchat-react-calls/SKILL.md` — current architecture (v5)
 - `cometchat-react-calls/references/call-layouts.md` — layout enum migration
-- `cometchat-react-calls/references/recording.md` — recording events migration
+- `cometchat-react-calls/references/recording-screen-share.md` — recording events migration

package/skills/cometchat-react-calls/references/raise-hand.md

@@ -31,10 +31,11 @@ CometChatCalls.addEventListener("onParticipantHandLowered", (participant) => {
 The SDK ships a built-in raise-hand button in the default control panel. Hide it via call settings if you're rolling custom UI:
 
 ```ts
-const callSettings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideRaiseHandButton(true)         // suppress the SDK's button — your UI takes over
-  .build();
+// SessionSettings object passed to joinSession(token, settings, container).
+// hideRaiseHandButton is a SessionSettings field — NOT a CallSettingsBuilder
+// method, and there is no setSessionID (the session is carried by the token
+// from generateToken(sessionId)).
+const settings = { hideRaiseHandButton: true };  // suppress the SDK's button — your UI takes over
 ```
 
 ---
@@ -108,12 +109,13 @@ function RaisedHandsList() {
       });
     };
 
-    CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-    CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
+    // addEventListener returns an unsubscribe fn — there is no removeEventListener.
+    const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+    const offLowered = CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
 
     return () => {
-      CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
-      CometChatCalls.removeEventListener("onParticipantHandLowered", onLowered);
+      offRaised();
+      offLowered();
     };
   }, []);
 
@@ -144,8 +146,8 @@ useEffect(() => {
   const onRaised = (p: { name: string }) => {
     toast.info(`${p.name} raised their hand`, { duration: 4000 });
   };
-  CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-  return () => CometChatCalls.removeEventListener("onParticipantHandRaised", onRaised);
+  const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
+  return () => offRaised();
 }, []);
 ```
 
@@ -194,10 +196,8 @@ If using the kit's `<CometChatOngoingCall />` and want raise-hand off entirely (
 ```tsx
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-const settings = new CometChatCalls.CallSettingsBuilder()
-  .setSessionID(sessionId)
-  .hideRaiseHandButton(true)
-  .build();
+// SessionSettings object for joinSession (hideRaiseHandButton is an object field).
+const settings = { hideRaiseHandButton: true };
 ```
 
 For 1:1 calls, default to hidden. For group calls > 5 participants, default to shown.

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