@cometchat/skills 4.3.0 → 4.4.1

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

@@ -3,7 +3,6 @@ name: cometchat-native-troubleshooting
 description: "Diagnose CometChat React Native UI Kit integration failures — init/login, gesture handler, pod install, iOS privacy manifest, Android Maven, Metro cache, permissions, calls, extensions, v4-to-v5 upgrade. For push-specific symptoms see cometchat-native-push § 12."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -16,7 +15,7 @@ Teaches Claude how to diagnose and fix CometChat React Native integration failur
 
 **Read `cometchat-native-core` first** — most "why doesn't this work" issues trace to the init/login/wrapper chain explained there.
 
-Ground truth: `docs/ui-kit/react-native/troubleshooting.mdx`, `apple-privacy-manifest-guide.mdx`, `upgrading-from-v4.mdx`, and first-hand failure modes from real integrations.
+Ground truth: `docs/ui-kit/react-native/troubleshooting.mdx`, `apple-privacy-manifest-guide.mdx`, `upgrading-from-v4.mdx`, and first-hand failure modes from real integrations. **Official docs:** https://www.cometchat.com/docs/ui-kit/react-native/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 
 ---
 
@@ -90,6 +89,9 @@ done
 
 Missing peer deps → install + `pod install` (bare) or `expo install` (Expo) + rebuild.
 
+> ⚠️ **`--legacy-peer-deps` silently DROPS peers.** If the project installed with `npm install --legacy-peer-deps` (common to dodge RN peer-range conflicts), npm **skips** unmet peer deps instead of erroring — you get a "successful" install with `react-native-svg` / `gesture-handler` / `safe-area-context` / async-storage missing, then a runtime crash. Re-run the check above after any `--legacy-peer-deps` install and install the missing ones **explicitly**.
+> ⚠️ **`@cometchat/calls-lib-webrtc` is Cloudsmith-only — NOT on npm** (`npm view @cometchat/calls-lib-webrtc` → 404, verified). If a calls install fails resolving it, add the Cloudsmith tarball/registry per `cometchat-native-calls`; a plain `npm install @cometchat/calls-lib-webrtc` will never work.
+
 ---
 
 ## 2. Symptom → fix lookup tables
@@ -152,6 +154,9 @@ Quick-reference tables. Work through in order; if none match, drop into § 3 dee
 | Fast Refresh doesn't pick up new deps | Native dep change (requires rebuild) | Restart Metro + rebuild (iOS/Android) |
 | "Maximum update depth exceeded" after theme change | Theme object recreated each render | Define theme at module scope or in `useMemo(() => ..., [])` |
 | App crashes on first JS load | Entry file error (syntax or import order) | Check `index.js` — `react-native-gesture-handler` should be line 1 |
+| Unhandled promise rejection at startup with `id=0` / module-load TypeError, but chat + calls work fine | Known non-blocking init artifact from the kit/calls-sdk module-level code (F77); source-map unresolvable | **Non-blocking — do NOT chase it.** Chat and calls are fully functional. Documented as a known v4.x artifact. Don't refactor user code to "fix" it. |
+| Error banner shows literal `[object Object]` instead of a message | `setError(String(e))` / `setError(\`${e}\`)` — CometChatException stringifies to `[object Object]` | Use `e.message` (or a `formatCometChatError(e)` helper): `setError(e?.message ?? String(e))`. |
+| (Expo) Credentials/config changes don't take effect after editing app config | `expo.extra` manifest is **cached** | Restart with `npx expo start --clear`; for a dev build, rebuild. The `expo.extra` block is baked into the manifest at build/start time. |
 
 ### 2f. Theming
 
@@ -421,10 +426,10 @@ If the user is upgrading from `@cometchat/chat-uikit-react-native@4`, these are
 
 ```bash
 # 1. Update the main kit
-npm install @cometchat/chat-uikit-react-native@latest
+npm install @cometchat/chat-uikit-react-native@^5
 
 # 2. Install the full peer-dep set (v5 doesn't auto-install them like v4 did)
-npm install @cometchat/chat-sdk-react-native \
+npm install @cometchat/chat-sdk-react-native@^4 \
   @react-native-async-storage/async-storage \
   @react-native-clipboard/clipboard \
   @react-native-community/datetimepicker \
@@ -460,7 +465,8 @@ cd ios && pod install && cd ..
 
 If none of the lookup tables or deep dives apply:
 
-1. **Read the raw error.** RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
+1. **Run `cometchat doctor`** (the structured first pass — combines detect + info + verify + known-issue matching). Start here; it often pinpoints the layer (state / drift / env / deps) before you read logs.
+2. **Read the raw error.** RN errors are usually specific ("Module 'X' not found in app 'Y'" is different from "TurboModuleRegistry.getEnforcing").
 2. **Check the dev console + native logs.** For iOS: Xcode → View → Debug Area → Activate Console. For Android: `adb logcat | grep -E "cometchat|CometChat|ReactNative"`.
 3. **Search the upstream docs MCP** (`cometchat-docs` if installed).
 4. **Search the sample app** (`examples/SampleApp/` or `examples/SampleAppExpo/`) for a working version of the pattern the user is trying.

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

@@ -3,13 +3,14 @@ name: cometchat-nextjs-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into Next.js projects (App Router and Pages Router). Covers SSR prevention, provider setup, route placement, API routes, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; Next.js >=13; @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 nextjs next react ssr app-router pages-router patterns"
 ---
 
+> **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 Next.js project. Next.js is the most complex framework to integrate with because of Server-Side Rendering (SSR) and the Server Component / Client Component boundary. Every CometChat component is browser-only -- getting this wrong is the #1 source of integration failures.
@@ -72,12 +73,13 @@ import React from "react";
 import React from "react";
 ```
 
-### App Router: dynamic import from Server Components
+### App Router: dynamic import from a Client Component (Next.js 15+ rule)
 
-If you need to render a CometChat component inside a Server Component (e.g., a page that does data fetching), use `next/dynamic` with `ssr: false`:
+> ⚠️ **Next.js 15+ change (verified by runtime smoke 2026-06-02):** `dynamic(..., { ssr: false })` is **FORBIDDEN in Server Components** — Next.js 15+ throws a build error. The page that owns the dynamic-import MUST be a Client Component (`"use client"` at line 1). Otherwise the build fails with `Ecmascript file had an error` even if everything else is correct.
 
 ```tsx
-// app/messages/page.tsx (this is a Server Component)
+// app/messages/page.tsx
+"use client";   // ← REQUIRED in Next.js 15+ when using `dynamic({ ssr: false })`
 import dynamic from "next/dynamic";
 
 const ChatView = dynamic(() => import("../../components/ChatView"), {
@@ -90,7 +92,11 @@ export default function MessagesPage() {
 }
 ```
 
-The `ChatView` component itself must still have `"use client"` at the top.
+The `ChatView` component file itself must also have `"use client"` at the top. Both ends of the dynamic-import boundary need the directive.
+
+**If you cannot make the page a Client Component** (because it needs server data-fetching), wrap your data-fetching in a separate Server Component sibling and pass results down via props to a Client Component that owns the CometChat subtree.
+
+**Build still fails after applying both `"use client"` and `dynamic(... ssr:false)`?** Add `export const dynamic = "force-dynamic";` at the top of the page to opt out of static prerendering entirely (or `export const runtime = "edge";` for edge runtime). This is sometimes needed in Next.js 16 even with everything else correct — verified during 2026-06-02 smoke against Next.js 16.2.7. Skill-side suspicion: kit's module-eval-time `window` references still trip static prerender even via dynamic boundary.
 
 ### Pages Router: dynamic import
 
@@ -190,7 +196,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)
       }
     }
 
@@ -239,6 +246,13 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 
 **Note:** Importing a `"use client"` component from a Server Component is fine. Next.js renders the Server Component on the server and defers the Client Component to the browser. The `CometChatProvider` only runs its `useEffect` (and init) in the browser.
 
+> ⚠️ **Option A REQUIRES `force-dynamic` on the layout (verified — real build, Next 16.2.9 + kit 6.5.1).** Mounting the provider in `app/layout.tsx` pulls the kit module into the layout's module graph, so `next build` evaluates it during the **static prerender** of *every* route — including `/` (which imports no CometChat code) and the framework-generated `/_not-found` — and crashes with `ReferenceError: window is not defined`. `"use client"` does NOT prevent this in Next 16. The per-page `export const dynamic = "force-dynamic"` from §"Build still fails…" cannot fix it, because `/_not-found` has no page file to annotate. **The fix is to put the directive on the LAYOUT, where it cascades to all routes including `/_not-found`:**
+> ```tsx
+> // app/layout.tsx — add this alongside the provider mount
+> export const dynamic = "force-dynamic";
+> ```
+> If you would rather keep static prerendering for non-chat routes, use **Option B** (scoped route group) so `/` and `/_not-found` never import the kit — that is the cleaner choice for marketing/SSG-heavy sites.
+
 ### Where to mount: Option B -- Scoped (chat only on chat routes)
 
 Use a route group to scope the provider to chat-related routes:
@@ -836,7 +850,7 @@ If the project has a custom `pages/_document.tsx` for font preloading or third-p
 
 ## 12. Complete integration checklist (App Router)
 
-1. Install packages: `npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript`
+1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
 2. Create `.env.local` with `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY`
 3. Import `@cometchat/chat-uikit-react/css-variables.css` in `app/globals.css`
 4. Create `app/providers/CometChatProvider.tsx` with `"use client"` (section 3)
@@ -847,7 +861,7 @@ If the project has a custom `pages/_document.tsx` for font preloading or third-p
 
 ## 13. Complete integration checklist (Pages Router)
 
-1. Install packages: `npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript`
+1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
 2. Create `.env.local` with `NEXT_PUBLIC_COMETCHAT_APP_ID`, `NEXT_PUBLIC_COMETCHAT_REGION`, `NEXT_PUBLIC_COMETCHAT_AUTH_KEY`
 3. Import `@cometchat/chat-uikit-react/css-variables.css` in `pages/_app.tsx`
 4. Create `components/CometChatProvider.tsx` (section 3 code, without `"use client"`)

package/skills/cometchat-placement/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-placement
 description: "Production integration patterns -- how to add CometChat as a route, modal, drawer, embedded panel, or widget in an existing project. Teaches Claude WHERE to put chat."
 license: "MIT"
 compatibility: "@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 placement route modal drawer widget embedded integration"
 ---
 
+> **Ground truth:** `@cometchat/chat-uikit-react@^6` components composed for placement + `docs/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 you WHERE to put CometChat in an existing project. It covers five placement patterns: route, modal, drawer, embedded panel, and floating widget. Each pattern includes step-by-step instructions and complete code examples.
@@ -168,6 +169,30 @@ chat products.
 
 ---
 
+> **Composer choice for narrow/two-pane panes:** the canonical React v6 sample apps use **`CometChatCompactMessageComposer`** (not `CometChatMessageComposer`) in the two-pane messages view — it's the kit's space-optimized composer for a sidebar-width pane (`cometchat-uikit-react-v6/sample-app/src/components/CometChatMessages/CometChatMessages.tsx:85`). Both compile and work; prefer `CometChatCompactMessageComposer` for the split/two-pane layouts below and `CometChatMessageComposer` for full-width single-thread layouts.
+
+## Height & scroll — the message-view column MUST be bounded
+
+Every header+list+composer example below puts the three components as **direct
+flex children** of a `display:flex; flexDirection:column` column. That works ONLY
+if the column has a bounded height — i.e. the full chain (`html`/`body`/`#root` →
+…→ this column) uses a definite **`height`** (e.g. `#root { height: 100vh }`),
+never `min-height`, and every flex ancestor of `CometChatMessageList` has
+`minHeight: 0`. Delete the Vite/CRA starter `#root { min-height: 100vh; max-width: … }`.
+
+If the list still won't scroll (most common symptom), or you wrap the list in its
+own `<div>` for custom chrome/tabs, you hit the kit's auto-injected `.cometchat`
+element — see **`cometchat-react-patterns` → "Container height (and the flex-shrink
+trap)" Bug 3**: give the list its own wrapper class with BOTH `.your-list-wrapper
+{ flex: 1 1 0; min-height: 0; height: 100%; overflow: hidden }` (the **explicit
+`height: 100%` is required** — a flex-grow-only height is indefinite, so the kit's
+injected child collapses to content height and clips) AND a child rule
+`.your-list-wrapper > .cometchat { height: 100%; overflow: hidden }` (inline styles
+can't target the injected child). Those two rules are the single most common fix for
+"I set heights everywhere and it still won't scroll."
+
+---
+
 ## Thread replies — hidden by default in every example below
 
 Every `<CometChatMessageList ...>` in the placement patterns below
@@ -607,6 +632,17 @@ The `CometChatProvider` (or equivalent init logic) MUST be at the app root, NOT
 
 A side panel that slides in from the right. Better than a modal for ongoing conversations because the user can keep it open while browsing.
 
+> ⚠️ **Known kit-side traps in narrow containers (≤ ~480px). Mitigate, don't ignore (ENG-35702/03/04/06):**
+>
+> 1. **Unread-count badges clip at the right edge in 320px panes** — kit's conversation-list item doesn't reserve trailing padding for the pill. Workaround until the kit fix lands: target `.cometchat-conversation-list-item__badge { margin-right: 8px; flex-shrink: 0; }` in your overrides, OR widen the drawer to ≥ 480px on the inner content (use `width: min(420px, 100vw)` + 8px inner padding).
+> 2. **`Delete Conversation?` confirmation card overflows the list pane** — kit renders the dialog inside the list column instead of portalling to a top-level scrim. There's no clean CSS workaround today; if the integration depends on right-click delete, raise the drawer width above ~480px so the card fits inside.
+> 3. **Composer attachment popover (`+` button) anchors to the wrong ancestor** — opens at viewport bottom-right instead of above the trigger when mounted inside a drawer/modal. Workaround: ensure the drawer container has `position: relative` (NOT just `position: fixed`) on its inner card so absolute popovers anchor correctly. If the popover still misaligns, mount the composer in a full-screen-on-mobile variant (the `right: -100%` recipe from §"Recipe — breakpoint-aware drawer").
+> 4. **Voice recorder bubble UI is broken at kit v6.x** — the in-bubble recorder shows visual artifacts AND the pause-resume timer restarts at 00:00 instead of continuing. There is no client-side workaround; if voice messages are part of the integration's core surface, document the limitation for the customer and consider hiding the voice button (`<CometChatMessageComposer hideVoiceRecordingButton={true} />`) until the kit fix ships.
+> 5. **`CometChatMessageList` does NOT auto-resubscribe on conversation switch** — passing a new `user` or `group` prop keeps the old listeners. **Required workaround when switching conversations inside a single drawer/modal:** pass `key={user?.getUid() ?? group?.getGuid()}` to force a remount + listener re-subscribe. Without it, switching from Alice → Bob silently shows Alice's messages with Bob's header. (ENG-35702)
+> 6. **`CometChatMessageList` may render BLANK on conversations with unread messages** — kit-side data-path bug, no header or empty-state, just blank. No client-side workaround today; if the customer reports a blank list, capture the screenshot + UID/GUID + unread count and file a kit ticket. (ENG-35702 kit-side blocker)
+>
+> These are kit-side bugs filed in Linear (ENG-35702, 35703, 35704, 35706); the workarounds above are interim until the next kit release.
+
 ### Steps
 
 #### 1. Create a ChatDrawer component
@@ -688,9 +724,12 @@ export function ChatDrawer({ isOpen, onClose, targetUserId, targetGroupId }: Cha
         style={{
           position: "fixed",
           top: 0,
-          right: isOpen ? 0 : "-400px",  // matches width; slides off-screen when closed
+          // Breakpoint-aware: full-width on mobile (≤ 640px), 400px on desktop.
+          // The "-100%" closed offset slides the drawer off-screen at any width,
+          // so mobile-full-screen works without recomputing the offset (ENG-35715).
+          right: isOpen ? 0 : "-100%",
           bottom: 0,
-          width: "400px",
+          width: "min(400px, 100vw)",
           maxWidth: "100vw",
           zIndex: 1000,
           backgroundColor: "var(--cometchat-background-color-01, #fff)",

package/skills/cometchat-production/SKILL.md

@@ -3,13 +3,14 @@ name: cometchat-production
 description: "Production readiness for CometChat — server-side token auth, user management CRUD, environment hardening, and security checklist. Replaces dev-mode authKey with server-side tokens."
 license: "MIT"
 compatibility: "Node.js >=18; @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: "cometchat production auth token security user-management rest-api"
 ---
 
+> **Ground truth:** `docs/fundamentals/user-auth` + per-platform UI Kit. **Official docs:** https://www.cometchat.com/docs/fundamentals/user-auth · **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 harden a CometChat integration for production. It covers two critical areas:
@@ -71,8 +72,10 @@ The CometChat REST API requires two headers:
 
 | Key type | Where to find | Purpose | Security |
 |---|---|---|---|
-| **Auth Key** | Dashboard → Your App → API & Auth Keys → "Auth Keys" table | Client-side SDK: `CometChatUIKit.login(uid)` in dev mode | Exposed in browser. Dev only. |
-| **REST API Key** | Dashboard → Your App → API & Auth Keys → "Rest API Keys" table | Server-to-server: token generation, user CRUD, message send | Server only. Never expose to client. |
+| **Auth Key** (`authOnly` scope) | Dashboard → Your App → API & Auth Keys → "Auth Keys" table | Client-side SDK `CometChatUIKit.login(uid)` in dev mode; server-side it can **create users + mint auth tokens** (`POST /v3/users`, `POST /v3/users/{uid}/auth_tokens`) but **NOT** update/delete users | Exposed in browser. Dev only. |
+| **REST API Key** (`fullAccess` scope) | Dashboard → Your App → API & Auth Keys → "Rest API Keys" table | Server-to-server: token generation, **full** user CRUD (incl. **update/delete**), message send | Server only. Never expose to client. |
+
+> **Scope split (verified against `fundamentals/key-concepts.mdx` + the chat-apis `apikey` scope enum `fullAccess`/`authOnly`):** the Auth Key can *create & login* users and mint tokens, but **`PUT`/`DELETE /v3/users/{uid}` require a `fullAccess` REST API Key** — an `authOnly` Auth Key is rejected. So a user-management endpoint that does update/delete MUST use `COMETCHAT_REST_API_KEY`, not the Auth Key. (Heads-up: the CLI's `add-user-mgmt` / `production-auth` scaffolds currently name the server var `COMETCHAT_AUTH_KEY`; for full CRUD, populate it with — or rename it to — a `fullAccess` REST API Key. Tracked as a CLI-alignment follow-up.)
 
 The `.env` should have both for production:
 ```env
@@ -585,8 +588,12 @@ async function refreshSession(uid: string): Promise<void> {
 CometChat.addConnectionListener(
   "auth-refresh-listener",
   new CometChat.ConnectionListener({
-    onDisconnected: () => {
-      const uid = CometChatUIKit.getLoggedInUser()?.getUid();
+    onDisconnected: async () => {
+      // Web kit method is getLoggedinUser() (lowercase "i") and is ASYNC —
+      // it returns a Promise, so you must await it (you can't chain ?.getUid()
+      // on the call directly). The synchronous capital-I form is the Angular kit.
+      const me = await CometChatUIKit.getLoggedinUser();
+      const uid = me?.getUid();
       if (uid) {
         refreshSession(uid).catch((e) => {
           console.error("CometChat refresh failed; user may need to re-login", e);

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

@@ -1,15 +1,16 @@
 ---
 name: cometchat-react-calls
-description: CometChat Calls SDK integration for web React apps (Vite, CRA, Next.js, React Router, Astro). Covers @cometchat/calls-sdk-javascript install, dual-SDK init (Chat SDK + Calls SDK), getRTCToken, the kit's CometChatIncomingCall / CometChatOutgoingCall / CometChatOngoingCall components, CallButtons composition, getUserMedia permissions, browser TURN/STUN handling, and additive-vs-standalone modes.
+description: CometChat Calls SDK integration for web React apps (Vite, CRA, Next.js, React Router, Astro). Covers @cometchat/calls-sdk-javascript install, dual-SDK init (Chat SDK + Calls SDK), generateToken (v4's getRTCToken was removed in v5), the kit's CometChatIncomingCall / CometChatOutgoingCall / CometChatOngoingCall components, CallButtons composition, getUserMedia permissions, browser TURN/STUN handling, and additive-vs-standalone modes.
 license: "MIT"
 compatibility: "React >= 18, Next.js >= 13, React Router v6/v7, Astro >= 4; @cometchat/calls-sdk-javascript ^5 (v5.0.0 stable shipped; pin to `@5` because the npm `latest` dist-tag still points at v4.2.6 — see §Install); @cometchat/chat-sdk-javascript ^4.x; @cometchat/chat-uikit-react ^6.x (additive mode)"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
   tags: "cometchat react calls voice video webrtc nextjs react-router astro getRTCToken getusermedia browser-permissions vite cra"
 ---
 
+> **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/calls/javascript/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.
+
 ## ⚠️ STOP — mandatory precondition before any code
 
 **Before writing one line of code, you MUST resolve `mode = ringing | session`.** This decides which entire integration shape you scaffold — they don't share UI, navigation, or surface.
@@ -80,6 +81,25 @@ If you can't use flex (e.g. fixed-height modal), just give the container explici
 
 ---
 
+## ⚠️ Idle timeout is in MILLISECONDS (the "Are you still there? → instant exit" bug)
+
+The idle-timeout values are **milliseconds, not seconds.** This is the single most common calls-config footgun (customer-reported 2026-06): setting `idleTimeoutPeriodBeforePrompt: 180` thinking "180 seconds" means **180 ms** — so the moment you join a session alone, the "Are you still there?" prompt fires and the call exits in a fraction of a second.
+
+```ts
+// ✗ WRONG — read as 180ms / 30ms → prompt + exit almost instantly on join
+const settings = { idleTimeoutPeriodBeforePrompt: 180, idleTimeoutPeriodAfterPrompt: 30 };
+
+// ✓ RIGHT — milliseconds. (defaults: 60_000 / 120_000)
+const settings = {
+  idleTimeoutPeriodBeforePrompt: 180_000, // 180s before the prompt
+  idleTimeoutPeriodAfterPrompt: 60_000,   // 60s grace before disconnect
+};
+```
+
+Set them as `SessionSettings` **object fields** (used with `joinSession(token, settings, container)`): `{ idleTimeoutPeriodBeforePrompt: 180_000, idleTimeoutPeriodAfterPrompt: 60_000 }`. ⚠️ There are **no** `setIdleTimeoutPeriodBeforePrompt`/`AfterPrompt` builder methods — `CallSettingsBuilder` has only a single `setIdleTimeoutPeriod(ms)`; the before/after split exists **only** as the two object fields. **`idleTimeoutPeriodAfterPrompt` has a 60_000 ms (60s) minimum** — smaller values are silently clamped to 60s. To effectively disable it, use a huge value (`86_400_000` = 24h), never `0` or a tiny number. The timer only counts down when you're the **only** participant — so a single-person session/test triggers it fastest. Full recipe (prompt UI + extend/leave): `references/idle-timeout.md`.
+
+---
+
 ## ⚠️ Next.js / SSR — mandatory bundler config
 
 Both SDKs ship code that **breaks Next.js's SSR pass**:
@@ -217,10 +237,25 @@ Production-grade voice + video calling for React-family web apps. Loaded by `com
 - Framework-specific patterns: `cometchat-react-patterns` / `cometchat-nextjs-patterns` / `cometchat-react-router-patterns` / `cometchat-astro-patterns`
 
 **Ground truth:**
-- SDK source — `~/Downloads/calls-sdk/calls-sdk-javascript-5/package/`
-- Sample apps — `~/Downloads/calls-sdk/calls-sdk-javascript-5/sample-apps/{react,vue,angular,svelte,ionic}/`
+- SDK source — `calls-sdk-javascript-5/package/`
+- Sample apps — `calls-sdk-javascript-5/sample-apps/{react,vue,angular,svelte,ionic}/`
 - Public docs — https://www.cometchat.com/docs/calls/javascript/overview
 
+## When to use
+
+- React-family web apps with voice/video calling: Vite + React, Next.js (App or Pages Router), React Router v6/v7, Astro with React islands.
+- The user wants 1:1 OR group calls AND wants the calls UI surface (not pure server-side / signaling-only).
+- Either calling mode applies — ringing (kit-driven incoming call screen) OR session (meeting-room URL pattern).
+
+## When NOT to use
+
+- **Chat-only integrations (no calling at all)** — skip this skill entirely. Load only `cometchat-core` + `cometchat-react-patterns` + `cometchat-components`. Don't install `@cometchat/calls-sdk-javascript` — the calls SDK alone is ~700 KB; with the kit + chat SDK the full production bundle of a chat-**and**-calls app is ~4.8 MB JS (verified — real `vite build`). That's expected; a green build also emits benign `COMMONJS_VARIABLE_IN_ESM` warnings from the calls SDK's own code and a >500 KB chunk-size warning — these are NOT failures.
+- **Native mobile (Android / iOS / RN / Flutter)** — load the cohort-specific calls skill (`cometchat-native-calls`, `cometchat-android-v6-calls`, `cometchat-ios-calls`, `cometchat-flutter-v6-calls`). The Calls SDK is platform-specific; APIs and lifecycle differ.
+- **Angular** — load `cometchat-angular-calls`. Same underlying JS Calls SDK but wrapped in Angular Services + `@Output()` event bindings (NOT React-style callback props — verified runtime smoke 2026-06-02 caught the v4→v5 binding inversion).
+- **SDK-only (no UI Kit)** — `cometchat-react-calls` §4c covers the SDK-only path in detail; this is the right skill, but you're using a specific subset. Don't import `<CometChatCallButtons>` / `<CometChatOngoingCall>` / `<CometChatIncomingCall>` from `@cometchat/chat-uikit-react` in that mode.
+- **Server-side token-mint server work** — load `cometchat-production` for the REST-API token recipes; this skill is client-side.
+- **Visual Builder calls** — load `cometchat-core` §11 + the framework-specific patterns; the Visual Builder generates calls wiring differently.
+
 ---
 
 ## 1. The seven hard rules — web specialization
@@ -242,11 +277,13 @@ const initiated = await CometChat.initiateCall(outgoing);
 // ✓ RIGHT — join WebRTC session (Calls SDK v5)
 import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
 
-// v5 — plain SessionSettings object, no Builder
+// v5 — plain SessionSettings object, no Builder.
+// `as const` keeps the string literals narrow ("VIDEO"/"TILE") so they satisfy
+// the SDK's SessionType / Layout unions — a bare object widens them to `string`.
 const sessionSettings = {
   sessionType: "VIDEO",   // or "VOICE"
   layout: "TILE",
-};
+} as const;
 
 // v5 — generateToken takes ONLY sessionId (Calls SDK has its own auth state
 // after CometChatCalls.login(); no authToken arg needed).
@@ -288,9 +325,11 @@ function endCall() {
 
 Skipping this leaves the camera light on until the tab is closed. Same canonical bug as iOS rule 1.5.
 
-### 1.4 Server-minted auth tokens for production
+### 1.4 Calls login — the DEFAULT path needs NONE; only `directCalling`/SDK-only do
 
-In v5 the Calls SDK has **its own login step** — it no longer piggybacks on the Chat SDK's auth context implicitly. After `CometChat.login()` resolves on the chat side, call **`CometChatCalls.login(uid, apiKey)`** for dev or **`CometChatCalls.loginWithAuthToken(authToken)`** for production. The auth token is the same token your backend mints via the CometChat Create-Auth-Token API; the Calls SDK and Chat SDK accept it interchangeably.
+> ✅ **For the common case — additive ringing / default calling — do NOT call `CometChatCalls.login`.** Install the calls SDK, let the call buttons appear automatically in `CometChatMessageHeader`, and mount `<CometChatIncomingCall />` once at the app root. That's the whole wiring. **Both canonical React v6 sample apps do calls this exact way with ZERO `CometChatCalls.login`/`CometChatCalls.init`** (verified: `cometchat-uikit-react-v6/sample-app/src/components/CometChatHome/CometChatHome.tsx:1740` mounts only `<CometChatIncomingCall />`; no `CometChatCalls.login` anywhere in either sample). The kit's default `defaultCalling` mode rides the Chat SDK's signaling — adding a calls-login step here is needless plumbing, and an empty/wrong arg makes it **silently no-op**.
+
+**`CometChatCalls.login` is required ONLY for** (a) `CallWorkflow.directCalling` (conference-style 1:1) or (b) the SDK-only / custom-WebRTC surface (§4c). In those cases — and only those — the v5 Calls SDK needs its own login: after `CometChat.login()` resolves on the chat side, call **`CometChatCalls.login(uid, apiKey)`** for dev or **`CometChatCalls.loginWithAuthToken(authToken)`** for production. The auth token is the same one your backend mints via the CometChat Create-Auth-Token API; the Calls SDK and Chat SDK accept it interchangeably.
 
 ```ts
 // Dev
@@ -300,8 +339,12 @@ await CometChatCalls.login(uid, import.meta.env.VITE_COMETCHAT_API_KEY);
 await CometChatCalls.loginWithAuthToken(authTokenFromBackend);
 ```
 
+> **About `VITE_COMETCHAT_API_KEY`:** `CometChatCalls.login(uid, apiKey)` takes the app's **Auth Key** — the same value `cometchat-core` writes as `VITE_COMETCHAT_AUTH_KEY` (the env-prefix table establishes `APP_ID`/`REGION`/`AUTH_KEY`, not a separate `API_KEY`). In dev you can reuse `VITE_COMETCHAT_AUTH_KEY` here; if you prefer the `_API_KEY` name for readability, add it to your `.env` with the same Auth Key value. Don't leave it undefined — an empty arg makes the Calls login silently no-op (see the `directCalling` trap above).
+
 `cometchat-production` (web) covers the token-endpoint pattern.
 
+> ⚠️ **`CallWorkflow.directCalling` silently fails without this login.** When you opt 1:1 calls into the conference-style UI by passing `callWorkflow={CallWorkflow.directCalling}` to `<CometChatCallButtons>` / `<CometChatOngoingCall>` etc., the kit routes through the Calls SDK directly and **requires `CometChatCalls.login()` to have completed**. Without it, calls **ring for ~2 seconds then drop with no error message** — the most painful failure mode in this skill. The UI Kit's default `defaultCalling` mode does NOT have this requirement (it uses the Chat SDK's signaling). Rule when emitting `directCalling`: always include the `CometChatCalls.login(...)` call alongside the Chat login above (ENG-35709).
+
 ### 1.5 Hangup cleanup — see rule 1.3
 
 ### 1.6 Permissions — `getUserMedia` prompts
@@ -328,6 +371,69 @@ There are no manifest-level permission declarations on web. HTTPS is required
 
 Mounting it inside a route component means it disappears on navigation — calls only ring on the screen where it's mounted. That's the canonical "calls don't work" bug on web.
 
+### 1.8 Init order — Chat init → Chat login → Calls init → Calls login (ENG-35708)
+
+The order is load-bearing. Two crashes from real testers trace back to this:
+
+- **`CometChatCalls.init` before `CometChat.login` → calls integration broke.** The Calls SDK reads context from the Chat SDK that only exists once a Chat session is established. Swapping init order silently fails or returns 401s on the first `generateToken`.
+- **Crash on `Start Call` when only the Calls SDK was initialized.** No Chat SDK init at all → the ringing flow can't fire `initiateCall` because the Chat SDK isn't there.
+
+**The only correct order in additive mode (chat + calls):**
+
+```
+CometChat.init(appId, settings)
+  → CometChat.login(uid, authKey)        // OR loginWithAuthToken(token)
+  → CometChatCalls.init({appId, region})
+  → CometChatCalls.login(uid, apiKey)    // OR loginWithAuthToken(serverToken)
+```
+
+In **standalone session-mode** (`product === "voice-video"`, no chat), use ONLY the Calls SDK — never call `CometChat.init` / `CometChat.login` at all. The kit's session-mode sample doesn't import the Chat SDK; matching that shape eliminates a class of "Chat init failed mid-meeting" failures.
+
+### 1.9 Don't double-up call buttons (ENG-35708)
+
+Two testers reported call buttons appearing twice on the message screen. Cause: the kit's `<CometChatMessageHeader user={user} />` already renders `<CometChatCallButtons>` internally when a `user` prop is set (and the kit's default messages page mounts the header). Adding your own `<CometChatCallButtons user={user} />` next to either of those produces a duplicate set.
+
+**Rule before emitting `<CometChatCallButtons>`:**
+
+1. Check whether the surrounding kit component already shows them. `CometChatMessageHeader` (any path that auto-renders the header) and the kit's default messages page include call buttons by default. (Note: there is no `CometChatConversationsWithMessages` composite in v6 — it was removed.)
+2. If yes, do NOT add a second `<CometChatCallButtons>`. To swap appearance or behavior, use the kit's `messageHeaderView` slot or set the relevant `hide*` flag instead of adding another instance.
+3. If no — you're on a custom screen that does not use those kit components — then `<CometChatCallButtons user={user} />` is appropriate. Mount it once, beside the user-info block.
+
+### 1.10 `CometChatOngoingCall` expects a `callSettingsBuilder`, NOT a built `CallSettings` (ENG-35708)
+
+`CallSettingsBuilder` is not a bare export of either package — access it via the kit re-export: `import { CometChatUIKitCalls } from "@cometchat/chat-uikit-react"`, then `new CometChatUIKitCalls.CallSettingsBuilder()`. The prop shape is the **builder instance** (not the built settings object). The agent emitted:
+
+```tsx
+// ✗ Wrong — TypeScript error on the prop type
+const callSettings = new CometChatUIKitCalls.CallSettingsBuilder().enableDefaultLayout(true).build();
+<CometChatOngoingCall callSettingsBuilder={callSettings} />
+```
+
+The correct usage is:
+
+```tsx
+// ✓ Right. Verified against the kit's CometChatOngoingCallProps (6.5.x):
+//   sessionID: string            ← REQUIRED (non-optional) — omitting it TS-errors
+//   callSettingsBuilder?: ...    ← OPTIONAL; the kit defaults to new CometChatUIKitCalls.CallSettingsBuilder()
+// There is NO .setSessionID() on the builder — the session id is its OWN prop.
+// The builder holds only configuration setters (enableDefaultLayout /
+// setIsAudioOnlyCall / show*Button).
+const callSettingsBuilder = new CometChatUIKitCalls.CallSettingsBuilder()
+  .enableDefaultLayout(true)
+  .setIsAudioOnlyCall(false);
+<CometChatOngoingCall sessionID={sessionId} callSettingsBuilder={callSettingsBuilder} />
+```
+
+> **Prefer the additive path over a manual `<CometChatOngoingCall>` mount.** Mounting `<CometChatIncomingCall />` at the app root and letting the kit drive the Outgoing → Ongoing transition needs no `sessionID` plumbing and is the build-clean, recommended approach (§1.x). Reach for a manual `<CometChatOngoingCall>` only when you're building a custom call screen — and then `sessionID` is mandatory.
+
+Why this shape: the kit composes the builder with internal listeners (call-end, error, recording state) before calling `.build()`. Pre-building forecloses that composition. Pass the builder; let the kit build.
+
+> ⚠️ **`callSettingsBuilder` is a different shape on different components** (verified vs the v6 React kit source — do not assume one form):
+> - `<CometChatOngoingCall>` → a **builder instance** (`callSettingsBuilder={new CometChatUIKitCalls.CallSettingsBuilder()...}`), prop typed `typeof CometChatUIKitCalls.CallSettings`.
+> - `<CometChatCallButtons>` → a **callback**: `callSettingsBuilder={(isAudioOnlyCall, user?, group?) => new CometChatUIKitCalls.CallSettingsBuilder()...}`.
+> - `<CometChatIncomingCall>` (and Outgoing) → a **callback** taking the call: `callSettingsBuilder={(call) => new CometChatUIKitCalls.CallSettingsBuilder()...}`.
+> All three are optional — omit the prop and the kit uses its own default builder (the simplest correct path). Only the OngoingCall form takes a bare instance; passing an instance where a callback is expected is a TS error.
+
 ---
 
 ## 2. Setup
@@ -380,7 +486,10 @@ export async function initCometChat() {
 export async function loginCometChat(uid: string) {
   await CometChat.login(uid, import.meta.env.VITE_COMETCHAT_AUTH_KEY);
 
-  // v5 — Calls SDK login. Either form is fine; loginWithAuthToken is for production.
+  // v5 — Calls SDK login. ⚠ Only needed for CallWorkflow.directCalling or the
+  // SDK-only/custom-WebRTC surface (see §1.4) — for the COMMON additive/default
+  // ringing path you can OMIT this whole block (the kit rides the Chat SDK's
+  // signaling). Shown here for completeness; harmless when included with a valid key.
   if (!CometChatCalls.getLoggedInUser()) {
     await CometChatCalls.login(uid, import.meta.env.VITE_COMETCHAT_API_KEY);
     // OR: await CometChatCalls.loginWithAuthToken(serverMintedToken);
@@ -390,6 +499,8 @@ export async function loginCometChat(uid: string) {
 
 The module-level `initialized` flag prevents StrictMode double-init in React 18+ dev mode. The `getLoggedInUser()` guard prevents re-login on hot reload.
 
+> ⚠️ **Additive mode: the chat layer must init via `CometChatUIKit.init()`, not raw `CometChat.init()`.** The example above shows `CometChat.init()` for the SDK-only path. But when you use the kit's call components (`<CometChatCallButtons>` / `<CometChatIncomingCall>` / `<CometChatOngoingCall>`), they read `uiKitSettings` that **only `CometChatUIKit.init(new UIKitSettingsBuilder()…build())` sets** — your `cometchat-core` setup already does this. Initializing the chat layer with raw `CometChat.init()` instead leaves the components logging **`uiKitSettings not available`** (non-fatal — calls still connect — but a real DX smell). In additive mode, keep `CometChatUIKit.init()` as your chat init and have this calls module ADD only `CometChatCalls.init()` + `CometChatCalls.login()` on top. *(Verified by a two-user live call smoke 2026-06-04: with `CometChatUIKit.init()` the ring→accept→join flow runs with zero console errors; with raw `CometChat.init()` both sides log the warning.)*
+
 ### Framework-specific env prefixes (already covered by `cometchat-core`)
 
 | Framework | Env prefix |
@@ -464,7 +575,7 @@ When `product === "voice-video"` and there is no existing chat UI integration.
 
 ### 4a. Standalone — Session mode (meeting-room UX, no ringing)
 
-Calls SDK ONLY. NO Chat SDK. Matches the upstream sample at `~/Downloads/calls-sdk/calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-react/`. The skill scaffolds:
+Calls SDK ONLY. NO Chat SDK. Matches the upstream sample at `calls-sdk-javascript-5/sample-apps/cometchat-calls-sample-app-react/`. The skill scaffolds:
 
 1. **`cometchat/init.ts`** — `CometChatCalls.init({ appId, region, authKey })` ONLY. No `CometChat.init`, no `CometChat.login`. Pass `authKey` at init time so subsequent `CometChatCalls.login(uid)` calls need no second arg.
 2. **`cometchat/CometChatProvider.tsx`** — Runs Calls SDK init on mount, exposes `loggedInUser` via `CometChatCalls.getLoggedInUser()`, gates children on success.
@@ -487,6 +598,104 @@ Dual-SDK: Chat SDK signaling channel + Calls SDK media channel. The skill scaffo
 7. **Optional Web Push** — Service Worker registration + push subscription endpoint, if the user opts in.
 8. **HTTPS check** — warns if dev server is HTTP non-localhost.
 
+### 4c. SDK-only — without any UI Kit call components (ENG-35707)
+
+When the user wants to build their own call UI (custom controls, a custom in-call screen) but still wants ringing semantics, they're on the SDK-only path: Chat SDK for signaling + Calls SDK for media, NO `<CometChatCallButtons>` / `<CometChatOngoingCall>` / `<CometChatIncomingCall>` from the UI Kit. The previous version of this skill was UI-Kit-first and these gotchas were silent. Cover them explicitly when you scaffold this shape.
+
+#### Constants — two enums, same meaning, easy to confuse
+
+| Constant | Source | Use it for |
+|---|---|---|
+| `CometChat.CALL_TYPE.AUDIO` / `.VIDEO` | `@cometchat/chat-sdk-javascript` | The **Chat SDK** call entity — passed to `new CometChat.Call(receiver, callType, receiverType)` and to `CometChat.initiateCall`. |
+| `CometChat.RECEIVER_TYPE.USER` / `.GROUP` | `@cometchat/chat-sdk-javascript` | The **Chat SDK** call entity — passed alongside `callType`. |
+| `CometChatCalls.constants.TYPE.VOICE` / `.VIDEO` | `@cometchat/calls-sdk-javascript` | The **Calls SDK** session-type enum. Matches the `SessionSettings` `sessionType` value (`'VOICE'` / `'VIDEO'`). |
+
+These are NOT interchangeable. `CometChat.CALL_TYPE.AUDIO` (Chat SDK) ≠ `CometChatCalls.constants.TYPE.VOICE` (Calls SDK) even though they mean the same thing. Use the Chat SDK enum on the `Call` entity you pass to `initiateCall`; use the Calls SDK enum on `SessionSettings.sessionType`.
+
+> Note: `CallSettingsBuilder` has **no** `setCallType(...)` method — that lives on `CallLogRequestBuilder` (and takes `'video' | 'audio'` for filtering call logs). The audio knob for a session is `CallSettingsBuilder().setIsAudioOnlyCall(true)`, or `sessionType: 'VOICE'` in the `SessionSettings` object form. (Verified against the calls-sdk `index.d.ts`.)
+
+#### Audio-only calls — `setIsAudioOnlyCall(true)` on `CallSettingsBuilder`
+
+The audio-only knob lives on the Calls SDK's `CallSettingsBuilder`, not on the Chat SDK call entity. You set the Chat SDK call type to `AUDIO` for the ringing/signaling channel, and then ALSO set `setIsAudioOnlyCall(true)` on the call settings used for `joinSession`:
+
+```typescript
+// joinSession's 2nd arg is a SessionSettings OBJECT (NOT the output of
+// CallSettingsBuilder.build() — that's a CallSettings, accepted only by the
+// deprecated startSession). The session is carried by the `token` (from
+// generateToken(sessionId)); there is no sessionId/setSessionID in the settings.
+// Voice-only: set sessionType: 'VOICE' (the object equivalent of the v4
+// builder's setIsAudioOnlyCall(true)).
+const settings = { sessionType: 'VOICE' };
+
+const result = await CometChatCalls.joinSession(token, settings, containerRef.current);
+```
+
+Without `sessionType: 'VOICE'`, voice calls still acquire the camera (it's just not rendered) — which trips the browser permission prompt and lights the camera indicator. Always pair `CALL_TYPE.AUDIO` (Chat) + `sessionType: 'VOICE'` in the join settings (Calls) for voice calls.
+
+#### Container-mount timing — `joinSession` MUST fire after the container is in the DOM
+
+This is the most painful SDK-only failure mode. The natural site to call `joinSession` is the call-listener event `onOutgoingCallAccepted` (caller side) or `onIncomingCallReceived` → user-accepts (receiver side). But those events fire BEFORE your in-call panel has rendered — the container `<div ref={containerRef}>` is still `null`. `joinSession(token, settings, null)` throws `Container dimensions and number of tiles must be positive` (or silently no-ops in some kit versions).
+
+**Pattern: drive the container via state and join in a `useEffect` that depends on both the call state AND the container ref.**
+
+```tsx
+function CallScreen() {
+  const [phase, setPhase] = useState<"idle" | "joining" | "in-call">("idle");
+  const [callToken, setCallToken] = useState<string | null>(null);
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Step 1: register call listeners
+  useEffect(() => {
+    const listenerID = "call-screen-" + Date.now();
+    CometChat.addCallListener(listenerID, new CometChat.CallListener({
+      onOutgoingCallAccepted: async (call: any) => {
+        // DO NOT call joinSession here — the container ref is still null.
+        // Just flip the phase and let the effect below handle it.
+        const tokenRes = await CometChatCalls.generateToken(call.getSessionId(), authToken);
+        setCallToken(tokenRes.token);
+        setPhase("in-call");
+      },
+      onIncomingCallReceived: (call: any) => { /* show your accept UI */ },
+    }));
+    return () => CometChat.removeCallListener(listenerID);
+  }, []);
+
+  // Step 2: when phase flips to "in-call" AND container is mounted, join
+  useEffect(() => {
+    if (phase !== "in-call" || !callToken || !containerRef.current) return;
+    const container = containerRef.current;
+    if (container.clientWidth === 0 || container.clientHeight === 0) return; // not laid out yet
+    // session is carried by callToken (from generateToken). joinSession takes a
+    // SessionSettings OBJECT — {} uses the default layout. (Do NOT pass
+    // CallSettingsBuilder.build() here — that CallSettings type is for the
+    // deprecated startSession, and is incompatible with joinSession.)
+    CometChatCalls.joinSession(callToken, {}, container);
+  }, [phase, callToken]);
+
+  return (
+    <>
+      {phase === "in-call" && (
+        <div ref={containerRef} style={{ position: "fixed", inset: 0, width: "100vw", height: "100vh" }} />
+      )}
+    </>
+  );
+}
+```
+
+The key idea: the call-listener handler doesn't call `joinSession` directly. It updates state. The effect that depends on `phase` AND the ref runs ONLY after React has committed the container `<div>` to the DOM. This is the same race as "modal `<dialog>` mounted before `showModal()`" — it's a React/DOM-timing issue, not a SDK bug.
+
+#### Group calls vs 1:1 calls — defaults differ
+
+- **1:1 calls** use the ringing pattern: `new CometChat.Call(receiverUid, CALL_TYPE.VIDEO, RECEIVER_TYPE.USER)` → `CometChat.initiateCall(call)` → receiver gets `onIncomingCallReceived`. Default call type for a 1:1 video chat is video; for audio chat, audio.
+- **Group calls** in the UI Kit go through a **custom-message broadcast** (`CometChatCallButtons` sends `CustomMessage type="meeting"`), not `initiateCall`. SDK-only groups: send your own custom message + `CometChatCalls.joinSession` with a shared sessionId — there is no "ring a group" primitive.
+- **Group call default is voice** in the kit's `CometChatCallButtons` for groups; 1:1 default is video. If you're building custom buttons, replicate this — group calls are usually meeting-style (voice + screen share); 1:1s are usually video.
+
+Cross-reference: `cometchat-native-calls` §3 documents the same group-call custom-message pattern for React Native (memory: [[project_group_calls_kit_semantic]]).
+
+#### Container CSS — non-zero dimensions before `joinSession`
+
+Already covered in the §⚠️ "Call container — must have non-zero dimensions" callout at the top, but it bears repeating in the SDK-only flow because there's no UI Kit component wrapping the container. Inline-render the container with `position: fixed; inset: 0; width: 100vw; height: 100vh` (full-screen overlay) OR `display: flex; flex: 1; min-height: 600px` (embedded). NEVER `display: none` + toggle — the container measures zero while hidden and `joinSession` throws.
+
 ## 5. Additive integration
 
 When `cometchat-core` integration already exists. The skill:
@@ -532,6 +741,7 @@ When `cometchat-core` integration already exists. The skill:
 
 ## 8. Pointers
 
+- `references/virtual-background.md` — blur / custom image / clear (web-only; native iOS/Android don't support it)
 - `cometchat-core` — provider pattern, init guard, login order
 - `cometchat-components` — full UI Kit catalog (additive mode)
 - `cometchat-{nextjs,react,react-router,astro}-patterns` — framework-specific SSR guards, route placement