@cometchat/skills 4.2.1 → 4.4.0

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

@@ -3,7 +3,6 @@ name: cometchat-native-theming
 description: "CometChatThemeProvider + CometChatI18nProvider — color tokens, typography, dark mode, per-component style overrides, and localization (18 built-in languages + custom translations). The JS theme object replaces CSS variables."
 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 theme and localize the React Native UI Kit via `CometChatT
 
 **Read `cometchat-native-core` first** (the wrapper chain that includes `CometChatThemeProvider`) before this skill. `cometchat-native-components` § 13 covers per-component `style={}` overrides, which are a sibling concern to theming.
 
-Ground truth: `docs/ui-kit/react-native/theme.mdx`, `colors.mdx`, `component-styling.mdx`, `message-bubble-styling.mdx`, and `packages/ChatUiKit/src/theme/type.ts` (the canonical type definitions).
+Ground truth: `docs/ui-kit/react-native/theme.mdx`, `colors.mdx`, `component-styling.mdx`, `message-bubble-styling.mdx`, and `packages/ChatUiKit/src/theme/type.ts` (the canonical type definitions). **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).
 
 ---
 
@@ -308,10 +307,18 @@ The theme has a `typography` block with tokens per role:
   theme={{
     light: {
       typography: {
-        heading1: { fontFamily: "Inter-Bold", fontSize: 28, fontWeight: "700" },
-        heading2: { fontFamily: "Inter-SemiBold", fontSize: 20 },
-        body1: { fontFamily: "Inter-Regular", fontSize: 15 },
-        caption1: { fontFamily: "Inter-Regular", fontSize: 12 },
+        fontFamily: "Inter",   // flat string — the global family
+        // Every role EXCEPT `fontFamily`/`link` is a variant object with
+        // `bold` / `medium` / `regular`, each an RN TextStyle:
+        heading1: {
+          bold:    { fontFamily: "Inter-Bold", fontSize: 28, fontWeight: "700" },
+          medium:  { fontFamily: "Inter-SemiBold", fontSize: 28, fontWeight: "600" },
+          regular: { fontFamily: "Inter-Regular", fontSize: 28, fontWeight: "400" },
+        },
+        body: {
+          regular: { fontFamily: "Inter-Regular", fontSize: 15 },
+        },
+        link: { fontFamily: "Inter-Regular", fontSize: 15 }, // `link` is a flat TextStyle
         // ... etc
       },
     },
@@ -319,7 +326,7 @@ The theme has a `typography` block with tokens per role:
 >
 ```
 
-Common tokens: `heading1`, `heading2`, `heading3`, `heading4`, `body1`, `body2`, `caption1`, `caption2`, `button1`, `button2`. Each follows the RN `TextStyle` shape — `fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`.
+Common tokens: `title`, `heading1`, `heading2`, `heading3`, `heading4`, `body`, `caption1`, `caption2`, `button` (there is NO `body1/body2/button1/button2`). Each of these is a **variant object** `{ bold, medium, regular }` where each weight is an RN `TextStyle` (`fontFamily`, `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`). The two exceptions — `fontFamily` and `link` — are flat (a string and a single `TextStyle` respectively).
 
 ### Custom font setup
 
@@ -345,18 +352,17 @@ Beyond color / typography, the theme has per-component style blocks for fine con
         containerStyle: { backgroundColor: "#FAFAFA" },
       },
       messageHeaderStyles: {
-        titleStyle: { fontSize: 18 },
+        titleTextStyle: { fontSize: 18 },   // key is titleTextStyle, NOT titleStyle
       },
       messageListStyles: {
         containerStyle: { padding: 8 },
-        sendBubbleStyle: {
-          backgroundColor: "#F76808",
-          textStyle: { color: "#FFFFFF" },
-        },
-        receiveBubbleStyle: {
-          backgroundColor: "#F5F5F5",
-          textStyle: { color: "#141414" },
-        },
+        // Bubble styling is NESTED — the keys are `incomingMessageBubbleStyles`
+        // and `outgoingMessageBubbleStyles` (each a DeepPartial<BubbleStyles>
+        // with `containerStyle`/`textBubbleStyles`/… — there is no flat
+        // `sendBubbleStyle`/`receiveBubbleStyle` with backgroundColor+textStyle).
+        // For simple bubble color changes, prefer the color tokens in §7
+        // (sendBubbleBackground / receiveBubbleBackground) — cleaner than the
+        // per-component bubble blocks.
       },
       messageComposerStyles: {
         containerStyle: { backgroundColor: "#FFF", borderTopWidth: 1, borderTopColor: "#E8E8E8" },
@@ -366,7 +372,7 @@ Beyond color / typography, the theme has per-component style blocks for fine con
 >
 ```
 
-Common component-style keys: `conversationStyles`, `usersStyles`, `groupsStyles`, `groupMembersStyles`, `messageHeaderStyles`, `messageListStyles`, `messageComposerStyles`, `threadHeaderStyles`, `callButtonsStyles`, `callLogsStyles`.
+Common component-style keys (exact names from `theme/type.ts`): `conversationStyles`, `userStyles`, `groupStyles`, `groupMemberStyle` (singular "Member" + singular "Style"), `messageHeaderStyles`, `messageListStyles`, `messageComposerStyles`, `threadHeaderStyles`, `callButtonStyles` (no "s" after "Button"), `callLogsStyles`. Note the irregular pluralization — `userStyles`/`groupStyles` are singular-noun, and `groupMemberStyle`/`callButtonStyles` don't follow the `*Styles` pattern.
 
 Each block has the same nested shape as the component's `style` prop (see `cometchat-native-components` § 13).
 
@@ -436,17 +442,18 @@ Overriding the bubble tokens directly is cleaner than doing it via `messageListS
 <CometChatThemeProvider
   theme={{
     light: {
+      // Roles: title, heading1-4, body, caption1, caption2, button (NO body1/body2/button1/button2).
+      // Each role is a VARIANT object { bold, medium, regular } — not a flat { fontFamily }.
+      // Verified vs uikit-react-native-v5 theme/default/typography.ts.
       typography: {
-        heading1: { fontFamily: "Inter-Bold" },
-        heading2: { fontFamily: "Inter-SemiBold" },
-        heading3: { fontFamily: "Inter-SemiBold" },
-        heading4: { fontFamily: "Inter-Medium" },
-        body1: { fontFamily: "Inter-Regular" },
-        body2: { fontFamily: "Inter-Regular" },
-        caption1: { fontFamily: "Inter-Regular" },
-        caption2: { fontFamily: "Inter-Regular" },
-        button1: { fontFamily: "Inter-SemiBold" },
-        button2: { fontFamily: "Inter-Medium" },
+        heading1: { bold: { fontFamily: "Inter-Bold" } },
+        heading2: { bold: { fontFamily: "Inter-SemiBold" } },
+        heading3: { medium: { fontFamily: "Inter-SemiBold" } },
+        heading4: { medium: { fontFamily: "Inter-Medium" } },
+        body: { regular: { fontFamily: "Inter-Regular" } },
+        caption1: { regular: { fontFamily: "Inter-Regular" } },
+        caption2: { regular: { fontFamily: "Inter-Regular" } },
+        button: { medium: { fontFamily: "Inter-Medium" } },
       },
     },
   }}
@@ -467,8 +474,9 @@ function CustomTitle({ user }: any) {
   return (
     <Text style={{
       color: theme.color.textPrimary,
-      fontFamily: theme.typography.heading3.fontFamily,
-      fontSize: theme.typography.heading3.fontSize,
+      // heading3 is a variant object — read a weight (regular/medium/bold):
+      fontFamily: theme.typography.heading3.regular.fontFamily,
+      fontSize: theme.typography.heading3.regular.fontSize,
     }}>
       {user.getName()}
     </Text>
@@ -597,6 +605,23 @@ Calling `useCometChatTranslation()` from a component rendered OUTSIDE `CometChat
 
 ---
 
+## Sound Manager — custom notification & call sounds
+
+Sounds are a **behavioral** customization (not styling) — driven by `CometChatSoundManager`, exported from the kit. The UI Kit plays the built-in cues automatically; use this to override or trigger them. Sound-event keys are passed as strings. (Docs: ui-kit/react-native/sound-manager.)
+
+```tsx
+import { CometChatSoundManager } from "@cometchat/chat-uikit-react-native";
+
+// Play a default cue — keys: incomingMessage | incomingMessageFromOther
+//                              | outgoingMessage | incomingCall | outgoingCall
+CometChatSoundManager.play("incomingMessage");
+
+// Stop whatever is playing
+CometChatSoundManager.pause();
+```
+
+> RN audio assets differ from web URLs — for custom sounds, follow the per-platform asset guidance in ui-kit/react-native/sound-manager rather than passing a web URL.
+
 ## 10. Anti-patterns
 
 1. **Don't pass non-hex colors.** `"rgb(...)"`, `"rgba(...)"`, named colors, or `hsl(...)` will break the kit's internal color math (used to derive `extendedPrimary`). Use `"#RRGGBB"` or `"#RRGGBBAA"` (opacity via alpha).

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
 
@@ -286,6 +291,68 @@ After updating:
 2. Rebuild the archive
 3. Resubmit
 
+### 3bb. `react-native-document-picker` build failure on RN 0.85+ (F70)
+
+**Symptom:** Android debug build fails with a hard Java compile error inside `react-native-document-picker`'s source — typically `cannot find symbol class GuardedResultAsyncTask`.
+
+**Root cause:** `react-native-document-picker` references `GuardedResultAsyncTask`, which React Native removed from its Android internals in 0.85. The package is unmaintained — the last useful release predates RN 0.85.
+
+**Fix:** uninstall it and switch to a maintained alternative if document picking is needed.
+
+```bash
+# Uninstall the broken package
+npm uninstall react-native-document-picker
+
+# For Expo apps — official maintained pick
+npx expo install expo-document-picker
+
+# For bare RN — maintained community fork
+npm install @react-native-documents/picker
+```
+
+`cometchat verify` flags this combination automatically (`rn_doc_picker_compat` check) — runs as part of every verify since v4.3.0.
+
+### 3bc. `Cannot read property 'CometChatThemeProvider' of undefined` on bare RN (F78 — chat-sdk 4.0.22 packaging regression)
+
+**Symptom (bare RN only):** the app builds cleanly (`BUILD SUCCESSFUL`) but crashes at JS startup with `TypeError: Cannot read property 'CometChatThemeProvider' of undefined`. The error often links to RN's own AsyncStorage troubleshooting text ("Make sure your project's `package.json` depends on `@react-native-async-storage/async-storage`…").
+
+**This is NOT the §3b Maven-repo build failure** — that one fails the Gradle build. F78 builds fine, then crashes at runtime.
+
+**Root cause (confirmed):** `@cometchat/chat-sdk-react-native` **4.0.22** declares `react`, `react-native@0.64.2`, and `@react-native-async-storage/async-storage@^1.13.4` as **hard `dependencies`** (4.0.21 had none). npm therefore installs **nested duplicate copies inside the SDK**:
+
+```
+node_modules/@cometchat/chat-sdk-react-native/node_modules/
+  ├── react-native/               → 0.64.2   (duplicate of your app's 0.85.x)
+  └── @react-native-async-storage/async-storage/  → 1.24.0
+```
+
+Two react-native copies = two native-module registries. The SDK's persistence code resolves AsyncStorage against its nested 1.24.0 copy, whose native module isn't the one your app autolinked → `RCTAsyncStorage` not found → the kit's `theme` module throws during evaluation → `CometChatThemeProvider` ends up `undefined`. **Expo is unaffected** because its resolver dedupes react-native to a single copy; bare RN installs the nested copy.
+
+Confirm you're hit by it:
+```bash
+ls node_modules/@cometchat/chat-sdk-react-native/node_modules/react-native/package.json && echo "F78: nested RN present"
+```
+
+**Fix — pick one (both verified to remove the nested install):**
+
+1. **npm `overrides`** (keep chat-sdk 4.0.22) — add to the app's `package.json`, then reinstall:
+   ```jsonc
+   "overrides": {
+     "@cometchat/chat-sdk-react-native": {
+       "react": "$react",
+       "react-native": "$react-native",
+       "@react-native-async-storage/async-storage": "$@react-native-async-storage/async-storage"
+     }
+   }
+   ```
+   yarn uses the equivalent top-level `resolutions`.
+2. **Pin the known-good SDK:** `npm i @cometchat/chat-sdk-react-native@4.0.21` (zero deps → no nesting).
+3. **Prefer Expo** for greenfield — the Expo cohort is fresh-validated and never hits this.
+
+After applying (1) or (2): `rm -rf node_modules && npm install`, then verify the nested `react-native` is gone with the `ls` check above. Tried and confirmed **NOT** to fix it: downgrading async-storage, `newArchEnabled=false`, clean rebuild, Metro `--reset-cache` — none address the duplicate-RN root cause.
+
+The permanent fix is SDK-side (move react/react-native to `peerDependencies`) — tracked in **ENG-35653**.
+
 ### 3c. Metro cache issues (post-dep-install "not found" errors)
 
 Happens when you `npm install` a native module and Metro's bundler still has the old module graph cached.
@@ -398,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:
@@ -855,3 +869,31 @@ If the project has a custom `pages/_document.tsx` for font preloading or third-p
 6. Create `pages/messages.tsx` with dynamic import (section 6)
 7. Add a `<Link href="/messages">Messages</Link>` to the layout's nav
 8. Verify: `npm run build` should succeed without SSR errors
+
+## 14. Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the Next.js recipe diverges based on App Router vs Pages Router. Skills runs `cometchat builder export --platform react --output <target>` to download the canonical `src/CometChat/` + patch settings in one step.
+
+**Full recipe lives in `cometchat-core` §11 "Visual Builder integration".** This section is a pointer + Next.js-specific gotchas:
+
+### App Router (recommended for Visual Builder)
+
+- Run `cometchat builder export --platform react --output src/app/CometChat --json`.
+- Create `src/app/CometChatNoSSR/CometChatNoSSR.tsx` (client component, init + login + render).
+- Create `src/app/CometChatAppWrapper.tsx` with `"use client"` + `dynamic(() => import("../app/CometChatNoSSR/CometChatNoSSR"), { ssr: false })`.
+- Import the wrapper in `src/app/page.tsx`.
+- **Patch `src/app/CometChat/context/CometChatContext.tsx`** to use `'../../../../package.json'` (4 levels up) instead of canonical's `'../../../package.json'` (3 levels). **Finding F16** — depth differs because the directory moved into `src/app/`.
+
+### Pages Router (NOT recommended)
+
+**Finding F17** (2026-05-22): Next.js Pages Router enforces "global CSS imports only in `pages/_app.tsx`". The canonical `src/CometChat/` has 25+ component-level CSS imports — Pages Router rejects the build. App Router tolerates this; Pages Router does not. Recommend App Router instead.
+
+If a customer insists on Pages Router + Visual Builder, the only workaround is to convert all 25+ canonical CSS files into CSS Modules — heavy customer-side work. Not validated in v4.3.0.
+
+### Both routers
+
+- Use `process.env.NEXT_PUBLIC_COMETCHAT_*` (NOT `import.meta.env.*` which is Vite-only).
+- Pin `@cometchat/chat-uikit-react@6.4.3` + `@cometchat/calls-sdk-javascript@4.2.5`.
+- `package.json` needs `cometChatCustomConfig` block (Finding F2).
+
+If the customer picks **In code**, ignore this section.

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);