@cometchat/skills 3.1.0 → 4.1.0

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

@@ -0,0 +1,433 @@
+---
+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: "executeBash, readFile, fileSearch, listDirectory, AskUserQuestion"
+metadata:
+  author: "CometChat"
+  version: "3.0.0"
+  tags: "cometchat react-native troubleshooting metro pods permissions upgrade"
+---
+
+## Purpose
+
+Teaches Claude how to diagnose and fix CometChat React Native integration failures. Covers every category of failure I've seen across Expo + bare RN, with an up-front triage flow so Claude asks the right questions before assuming a fix.
+
+**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.
+
+---
+
+## 1. Triage — read project state before guessing
+
+When the user reports a problem, gather facts before proposing a fix. Ask + run these first:
+
+### 1a. Which framework?
+
+```bash
+# Expo or bare?
+grep -E '"expo":|"expo-router":' package.json
+ls -d ios android 2>/dev/null   # bare RN has these dirs at root
+ls app.json app.config.js 2>/dev/null
+```
+
+- `expo` in dependencies + no `ios/android` folders → **Expo managed** → route to `cometchat-native-expo-patterns`
+- `ios/` + `android/` folders at root → **bare RN** → route to `cometchat-native-bare-patterns`
+- Both (`expo` + `ios/android`) → bare-after-prebuild. Treat as bare.
+
+### 1b. Is the wrapper chain correct?
+
+```bash
+# Confirm four wrappers in entry file
+grep -E "GestureHandlerRootView|SafeAreaProvider|CometChatThemeProvider|CometChatProvider" \
+  App.tsx index.js index.ts app/_layout.tsx 2>/dev/null
+```
+
+If any are missing, that's almost certainly the cause. See `cometchat-native-core` § 3.
+
+### 1c. Is `react-native-gesture-handler` imported first?
+
+```bash
+# Must be line 1 (or 2 with a shebang) of entry
+head -5 index.js index.ts App.tsx app/_layout.tsx 2>/dev/null
+```
+
+If the import is missing or below React, swipe gestures and bottom sheets silently break — often only in release builds.
+
+### 1d. Is init complete before login?
+
+```bash
+grep -A 10 "CometChatUIKit.init" src/providers/CometChatProvider.tsx 2>/dev/null
+```
+
+Look for the init-then-login sequence with an `await` or module-level `initialized` flag. Fire-and-forget init is a common cause of "components don't render."
+
+### 1e. Pod install state (iOS)
+
+```bash
+ls ios/Pods/ | head -5 2>/dev/null       # should list dozens of pods
+cat ios/Podfile.lock | head -3 2>/dev/null
+```
+
+If `ios/Pods/` is missing or sparse, native modules aren't linked. `cd ios && pod install && cd ..` is the fix.
+
+### 1f. Package deps
+
+```bash
+# Check the full UI Kit peer-dep set is installed
+for dep in \
+  @cometchat/chat-sdk-react-native \
+  @cometchat/chat-uikit-react-native \
+  react-native-gesture-handler \
+  react-native-safe-area-context \
+  react-native-svg \
+  @react-native-async-storage/async-storage; do
+  node -e "try{require.resolve('$dep'); console.log('✓ $dep')}catch(e){console.log('✗ MISSING: $dep')}"
+done
+```
+
+Missing peer deps → install + `pod install` (bare) or `expo install` (Expo) + rebuild.
+
+---
+
+## 2. Symptom → fix lookup tables
+
+Quick-reference tables. Work through in order; if none match, drop into § 3 deep-dives.
+
+### 2a. Initialization + login
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `CometChatUIKit.init()` fails silently | Invalid `APP_ID` / `REGION` / `AUTH_KEY` | Re-verify from dashboard → your app → Credentials |
+| Components render nothing after login | `init()` not awaited before mount | Use the provider pattern from `cometchat-native-core` § 6 with `isReady` gating |
+| Blank screen, no errors | Component mounted before init completed | Conditionally render: `if (!isReady) return null` |
+| `getLoggedInUser()` returns `null` | Login not called or session expired | Call `CometChatUIKit.login({ uid })` after init resolves |
+| Login fails: "UID not found" | User doesn't exist in CometChat | Create via dashboard, SDK, or REST API. For dev, use `cometchat-uid-1` through `cometchat-uid-5` (pre-seeded) |
+| "Please wait until the previous login request ends" | `login()` called concurrently (React StrictMode double-mount / navigation remount) | Use the `ensureLoggedIn` module-level promise guard from `cometchat-native-core` § 2 |
+| `sendTextMessage()` fails | Not logged in or invalid receiver | Verify `getLoggedInUser()` returns a user + receiver user/group object exists |
+| Production build exposes Auth Key | Using `authKey` in production | Switch to server-minted auth tokens via `login({ authToken })`. See `cometchat-native-production` |
+
+### 2b. Gesture handler + wrapper chain
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Composer swipe gestures not working | `import "react-native-gesture-handler"` not at TOP of entry file | Move to line 1 of `index.js` / `index.ts` / Expo Router's `app/_layout.tsx` |
+| BottomSheet doesn't open on swipe | Missing `GestureHandlerRootView` wrapper | Wrap at app root with `<GestureHandlerRootView style={{ flex: 1 }}>` |
+| Content overlaps status bar / home indicator | Missing `SafeAreaProvider` | Wrap inside `GestureHandlerRootView` with `<SafeAreaProvider>` |
+| Theme tokens return undefined | Missing `CometChatThemeProvider` | Add wrapper. See `cometchat-native-core` § 3 for the full chain |
+| "Couldn't find SafeArea context" error | `SafeAreaView` used outside `SafeAreaProvider` | Add `SafeAreaProvider` at root, or use plain `View` inside chat screens |
+| Release build: swipe/gesture broken, dev build fine | `react-native-gesture-handler` not line 1 (some bundlers defer it) | Move to line 1 unconditionally |
+
+### 2c. iOS build failures
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `No such module 'RNGestureHandler'` | Pods not installed | `cd ios && pod install && cd ..` + rebuild |
+| `Undefined symbol: _OBJC_CLASS_$_RNCAsyncStorage` | Pods out of sync after `npm install` | `cd ios && pod install && cd ..` |
+| `TurboModuleRegistry.getEnforcing(...)` crash at runtime | Native module not linked | `cd ios && pod install && cd ..` + reset Metro cache (`--reset-cache`) |
+| App Store rejection `ITMS-91053` | Missing Apple Privacy Manifest | Add `ios/<App>/PrivacyInfo.xcprivacy` with 4 API types. See `cometchat-native-bare-patterns` § 2c |
+| Simulator build fails: "arm64 excluded" | Architecture mismatch on Apple Silicon | Add `EXCLUDED_ARCHS[sdk=iphonesimulator*]` post_install in Podfile. See `cometchat-native-features` § 3c |
+| Camera/mic permission dialog doesn't appear | Missing `NSCameraUsageDescription` / `NSMicrophoneUsageDescription` | Add to `ios/<App>/Info.plist` (bare) or `app.json` `ios.infoPlist` (Expo) |
+| iOS build fails: "deployment target too low" | Calls SDK needs 12+ | Set `IPHONEOS_DEPLOYMENT_TARGET = '12.0'` in Podfile post_install |
+| Expo Go crashes: "Main module field cannot be resolved" | Expo Go doesn't support native modules | Use dev builds: `npx expo run:ios` or `eas build --profile development` |
+
+### 2d. Android build failures
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `Could not find :react-native-async-storage_async-storage:` | Local Maven repo entry missing | Add to `android/build.gradle` `allprojects.repositories` — see `cometchat-native-bare-patterns` § 3b |
+| Build crashes on launch | `compileSdkVersion` too low | Set `compileSdkVersion` to 33+ and `minSdkVersion` to 24+ in `android/app/build.gradle` |
+| "Permission denied" when picking photos | Missing Android permissions | Add `READ_MEDIA_IMAGES` (API 33+) or `READ_EXTERNAL_STORAGE` (API ≤32) to `AndroidManifest.xml` |
+| "Camera permission denied" | Missing permission in manifest or runtime denial | Add `CAMERA` to `AndroidManifest.xml` + verify runtime-grant flow |
+| Gradle sync fails after `npm install` | Native module autolinking stale | `cd android && ./gradlew clean && cd ..` then rebuild |
+| `Unable to delete file: ...node_modules/...` | Metro lockfile on Windows (if cross-OS) | Restart Metro + IDE |
+
+### 2e. Metro / JS runtime
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| "Unable to resolve module ..." for a dep that IS installed | Metro cache stale | Stop Metro, run with `--reset-cache`: `npx react-native start --reset-cache` or `npx expo start --clear` |
+| 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 |
+
+### 2f. Theming
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Theme overrides don't apply | Missing `CometChatThemeProvider` wrapper | Add at app root. See `cometchat-native-theming` § 2 |
+| Dark mode doesn't switch when system toggled | `mode` hardcoded to `"light"` / `"dark"` | Omit the `mode` field to follow system |
+| Custom color shows as fallback | Color not a hex string | Use `#RRGGBB` format. `rgb()` / named colors / `hsl()` break the extendedPrimary auto-derivation |
+| Custom font shows system default (iOS) / crashes (Android) | Font not loaded before render | Gate the provider on font loading (Expo `useFonts` or bare `react-native-asset`) |
+| Icon color not changing via `imageStyle` | Only `tintColor`, `height`, `width` work on default SVG icons | Use `tintColor`. Other props are ignored for built-in icons |
+| `useTheme()` returns undefined | Called outside `CometChatThemeProvider` | Ensure the component is a descendant of the provider |
+
+### 2g. Components
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Slot view (`TitleView`, `LeadingView`, etc.) renders nothing | Slot returned `null` / `undefined` | Slot must return valid JSX |
+| Empty message list despite sent messages | `user` vs `group` prop mixed up | Pass exactly one of `user` OR `group` — never both, never neither |
+| "Reply in Thread" option does nothing when tapped | Thread panel not wired | Set `hideReplyInThreadOption` (see `cometchat-native-components` § 11) OR wire a thread panel (§ 2b) |
+| `onItemPress` callback not firing | Wrong prop name (RN uses `Press` not `Click`) | It's `onItemPress`, not `onItemClick` — web and RN diverge here |
+| Conversations list empty but data exists | Wrong request builder | Check `conversationsRequestBuilder` filters (tags, types) |
+| List components collapse to zero height | Container has no bounded height | Wrap in `<View style={{ flex: 1 }}>` or explicit `height: N`. See `cometchat-native-placement` Hard rule #8 |
+| Component renders but data never loads | User/group passed as UID string instead of `CometChat.User`/`Group` instance | `await CometChat.getUser(uid)` first, pass the resolved object |
+
+### 2h. Calling
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Call buttons missing from MessageHeader | `@cometchat/calls-sdk-react-native` not installed | Install + rebuild. See `cometchat-native-features` § 3 |
+| Incoming call UI doesn't show | `CometChatIncomingCall` not mounted or listener not registered | Register `CometChat.addCallListener(...)` and mount `<CometChatIncomingCall>` at app root |
+| Call connects but no audio/video | Missing Podfile settings or Android SDK versions | Check `IPHONEOS_DEPLOYMENT_TARGET = 12.0` + Android `minSdkVersion = 24` |
+| WebRTC errors on load | Missing peer deps | Install `react-native-webrtc` + `@react-native-community/netinfo` + `react-native-background-timer` + `react-native-callstats` |
+| Call crashes on Android after accept | Permissions denied at runtime | Request `RECORD_AUDIO` + `CAMERA` runtime permissions before call |
+| `onIncomingCallReceived` silent | Listener registered before login completes | Register the listener INSIDE the `useEffect` that runs after login |
+
+### 2i. Extensions
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Polls option missing from composer | Extension not enabled in dashboard | `cometchat features enable polls --json` or toggle in dashboard → Features |
+| Stickers not rendering | Sticker extension not enabled | Same as above — enable via CLI |
+| Extension enabled but UI doesn't appear | Cached session — hard reload needed | Stop Metro, clear cache (`--reset-cache`), rebuild |
+| Extension says enabled but `auto_wired_in_uikit: false` | Needs `extensions` field on `CometChatUIKit.init({ ... })` | Add `extensions: [new StickersExtension(), ...]` to the init settings — see `cometchat-native-features` § 2 |
+| Message translation "Translate" option missing | Extension not enabled | Enable `MessageTranslation` via CLI / dashboard |
+
+### 2j. AI features
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| AI suggestions don't appear | AI feature not enabled in dashboard | Enable via dashboard → AI → individual feature |
+| Smart Replies not showing | Smart Replies extension off | Enable via CLI: `cometchat features enable smart-replies` |
+| Conversation Starter missing | Feature off + no conversation context | Enable feature + ensure chat has at least one previous message |
+
+### 2k. Localization
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| UI text not translated | Language code mismatch | Use full codes like `en-US`, not short `en` |
+| Auto-detection not working | `react-native-localize` missing | Install: `npm install react-native-localize` + pod install |
+| Custom translations not applied | Missing `CometChatI18nProvider` | Wrap app inside `CometChatThemeProvider` with `<CometChatI18nProvider>` |
+
+### 2l. Events
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| Listener doesn't fire | Wrong event name | Check `docs/events.mdx` for exact event names (e.g., `ccMessageSent` not `onMessageSent`) |
+| Listener fires twice | Duplicate registration (common with hot reload / remount) | Remove in `useEffect` cleanup: `return () => CometChatUIEventHandler.removeMessageListener(id)` |
+| Listener ID collision | Hardcoded ID reused across components | Use a unique constant per component: `const LISTENER_ID = "APP_SCREEN_LISTENER"` |
+| Call events not received | `CometChat.addCallListener` registered before login | Move registration into `useEffect` after login completes |
+
+### 2m. Production / auth tokens
+
+| Symptom | Likely cause | Fix |
+|---|---|---|
+| `login({ authToken })` fails: "user does not exist" | User not created in CometChat before token mint | Create user server-side via REST API on your signup flow. See `cometchat-native-production` § 6 |
+| Token endpoint returns 401 | Backend auth check failing | Verify `Authorization: Bearer <jwt>` header is attached to the fetch |
+| 429 rate limit on token endpoint | Minting tokens too often (e.g. per screen mount) | Cache client-side, reuse until expiry. See `cometchat-native-production` § 10 |
+| SDK disconnects after a few hours | Token expired | Wire `onDisconnected` listener to re-fetch + re-login. See `cometchat-native-production` § 5c |
+| `CometChatUIKit.loginWithAuthToken` not found | Wrong API name | It's `CometChatUIKit.login({ authToken })` — same method as dev, different key |
+
+---
+
+## 3. Deep dives on common failures
+
+### 3a. "The most common 'why is my chat blank' bug"
+
+CometChat components fill 100% of their parent's height. If the parent has no bounded height, the components render at 0px and look empty.
+
+Diagnostic:
+
+```bash
+grep -B5 -A5 "CometChatMessageList\|CometChatConversations" src/**/*.tsx | grep -B2 -A2 "style"
+```
+
+Look for the message list's parent. One of these must be true:
+
+- Parent has `flex: 1`
+- Parent has an explicit `height: N`
+- Parent is a flex column with the list getting `flex: 1`
+
+Broken example:
+```tsx
+<ScrollView>
+  <CometChatMessageList user={user} />   {/* ← ScrollView doesn't constrain height */}
+</ScrollView>
+```
+
+Fixed:
+```tsx
+<View style={{ flex: 1 }}>
+  <CometChatMessageList user={user} hideReplyInThreadOption />
+</View>
+```
+
+### 3b. Apple Privacy Manifest rejection (`ITMS-91053`)
+
+Apple's App Store Connect rejects RN apps that use certain APIs without declaring them in `PrivacyInfo.xcprivacy`. The CometChat kit (through React Native + `react-native-video`) triggers 4 of these APIs.
+
+Full manifest content is in `cometchat-native-bare-patterns` § 2c. Required reason codes:
+
+| API | Code |
+|---|---|
+| FileTimestamp | `C617.1` |
+| UserDefaults | `CA92.1` |
+| SystemBootTime | `35F9.1` |
+| DiskSpace | `E174.1` |
+
+If the user's rejection email lists OTHER API categories, their app uses additional Apple APIs through other SDKs (analytics, crash reporters, etc.). Add those codes too — the CometChat-specific 4 aren't exhaustive for all apps.
+
+After updating:
+1. `cd ios && pod install && cd ..`
+2. Rebuild the archive
+3. Resubmit
+
+### 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.
+
+```bash
+# Full reset
+watchman watch-del-all 2>/dev/null          # watchman (if installed)
+rm -rf $TMPDIR/metro-*                       # Metro cache on macOS
+rm -rf $TMPDIR/haste-map-*                   # Haste cache on macOS
+rm -rf node_modules
+npm install
+cd ios && pod install && cd ..               # iOS only
+npx react-native start --reset-cache         # bare
+# OR for Expo:
+npx expo start --clear
+```
+
+If the error persists after a clean cache + pod install, the native module isn't autolinked. Check `react-native.config.js` for exclusions.
+
+### 3d. "App crashes on first launch" — entry file order
+
+`index.js` MUST have `import "react-native-gesture-handler"` as line 1. Not line 2. Not after a `// comment`. Not after a `"use strict"`. Literally line 1.
+
+Wrong:
+```js
+import React from "react";              // ← line 1
+import "react-native-gesture-handler";  // ← line 2 — TOO LATE
+```
+
+Right:
+```js
+import "react-native-gesture-handler";  // ← line 1
+import React from "react";
+```
+
+For Expo Router, the same rule applies to `app/_layout.tsx`.
+
+### 3e. Push notification issues
+
+Push setup is covered end-to-end in `cometchat-native-push`. That skill
+has:
+
+- § 3 APNs p8 setup (Apple Developer portal)
+- § 4 FCM setup (Firebase project + service account)
+- § 5 CometChat dashboard provider upload (dev + prod for iOS)
+- § 7 Client registration with `CometChatNotifications.registerPushToken(token, platform, providerId)` (the correct API — not `CometChat.registerTokenForPushNotification`)
+- § 9 Foreground display + tap-to-deep-link handlers
+- § 12 Troubleshooting table mapping symptoms to fixes (production APNs cert missing, token registered before login, Expo Go can't receive push, etc.)
+
+When diagnosing a push issue, route the user to `cometchat-native-push § 12`
+rather than re-triaging here.
+
+---
+
+## 4. v4 → v5 upgrade gotchas
+
+If the user is upgrading from `@cometchat/chat-uikit-react-native@4`, these are the common breakages. Full migration guide: `docs/upgrading-from-v4.mdx`.
+
+| v4 | v5 | Notes |
+|---|---|---|
+| `CometChatContext` provider | `CometChatThemeProvider` + `CometChatI18nProvider` | Split into theme + i18n providers |
+| `<CometChatConversationsWithMessages>` composite | `<CometChatConversations>` + navigate to separate screen | Composite component removed; use two-screen navigation pattern |
+| `theme` prop on components | Theme via `CometChatThemeProvider` only | Per-component theme prop removed |
+| `Palette` object | Color tokens under `theme.color` | Renamed + restructured |
+| `onClick` callback names | `onPress` callback names | React Native convention |
+| `CometChat.login(uid, authKey)` | `CometChatUIKit.login({ uid })` | Object-form argument |
+| Native deps in `peerDependencies` | Must explicitly install peer deps | See `cometchat-native-core` § 9 |
+| Single NPM package for calls | Separate `@cometchat/calls-sdk-react-native` package | Calls broken out |
+
+### Upgrade sequence
+
+```bash
+# 1. Update the main kit
+npm install @cometchat/chat-uikit-react-native@latest
+
+# 2. Install the full peer-dep set (v5 doesn't auto-install them like v4 did)
+npm install @cometchat/chat-sdk-react-native \
+  @react-native-async-storage/async-storage \
+  @react-native-clipboard/clipboard \
+  @react-native-community/datetimepicker \
+  react-native-gesture-handler react-native-localize \
+  react-native-safe-area-context react-native-svg \
+  react-native-video dayjs punycode
+
+# 3. iOS
+cd ios && pod install && cd ..
+
+# 4. Android — add the local Maven repo for async-storage
+#    (see cometchat-native-bare-patterns § 3b)
+
+# 5. Entry file — add `import "react-native-gesture-handler"` as line 1
+#    (new requirement in v5)
+
+# 6. Replace `<CometChatContext>` with the 4-wrapper chain
+#    (see cometchat-native-core § 3)
+
+# 7. Split composite components — e.g. `<CometChatConversationsWithMessages>`
+#    becomes two screens with navigation
+
+# 8. Rename `onClick*` → `onPress*` throughout
+
+# 9. Replace `Palette` → theme tokens
+
+# 10. Rebuild + test
+```
+
+---
+
+## 5. Escalation — when the above doesn't solve it
+
+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").
+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.
+5. **If the issue is a kit bug**, file at https://github.com/cometchat/cometchat-uikit-react-native/issues with a minimal repro.
+
+---
+
+## 6. Hard rules (diagnostic best-practice)
+
+1. **Don't assume — triage first.** § 1 gets the framework, wrapper chain, pod state, and dep list before proposing a fix. A "I don't see messages" could be 10 different things.
+2. **Don't suggest "try reinstalling node_modules" as a first step.** It's rarely the actual fix and it takes minutes; check the entry file, wrapper chain, and pod state first.
+3. **Always verify against the ground-truth doc** (`troubleshooting.mdx`). If a user's symptom matches a table row, use the doc's fix verbatim — don't paraphrase.
+4. **Never guess a fix that requires code changes without first gathering facts.** Changing code based on a wrong hypothesis wastes user time.
+5. **When recommending a rebuild, say why + what to rebuild.** "pod install + rebuild iOS" is more useful than "try rebuilding."
+6. **If a symptom matches the Apple Privacy Manifest rejection, always paste the full 4-code XML.** Don't describe it; show it.
+
+---
+
+## Skill routing reference
+
+| Skill | When to route |
+|---|---|
+| `cometchat-native-core` | Most "doesn't work" bugs trace back here — init/login/wrapper chain |
+| `cometchat-native-components` | Wrong prop / slot view / request builder |
+| `cometchat-native-placement` | Blank chat / bounded-height issues |
+| `cometchat-native-expo-patterns` | Expo-specific build errors (dev client required, `expo install`) |
+| `cometchat-native-bare-patterns` | Bare RN build errors (pod install, Android Maven, privacy manifest) |
+| `cometchat-native-theming` | Theme not applying, dark mode not switching, font not loading |
+| `cometchat-native-features` | Calls don't work, extension UI missing after enable |
+| `cometchat-native-customization` | Formatter not rendering, listener not firing, template not showing |
+| `cometchat-native-production` | 401 on token fetch, user-does-not-exist on login |
+| `cometchat-native-troubleshooting` | This skill — cross-category diagnosis + v4→v5 upgrade |

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

@@ -340,8 +340,8 @@ export default function MessagesPage() {
           <>
             {selectedUser && <CometChatMessageHeader user={selectedUser} />}
             {selectedGroup && <CometChatMessageHeader group={selectedGroup} />}
-            {selectedUser && <CometChatMessageList user={selectedUser} />}
-            {selectedGroup && <CometChatMessageList group={selectedGroup} />}
+            {selectedUser && <CometChatMessageList user={selectedUser} hideReplyInThreadOption={true} />}
+            {selectedGroup && <CometChatMessageList group={selectedGroup} hideReplyInThreadOption={true} />}
             {selectedUser && <CometChatMessageComposer user={selectedUser} />}
             {selectedGroup && <CometChatMessageComposer group={selectedGroup} />}
           </>
@@ -434,14 +434,14 @@ export default function ChatView() {
         {selectedUser && (
           <>
             <CometChatMessageHeader user={selectedUser} />
-            <CometChatMessageList user={selectedUser} />
+            <CometChatMessageList user={selectedUser} hideReplyInThreadOption={true} />
             <CometChatMessageComposer user={selectedUser} />
           </>
         )}
         {selectedGroup && (
           <>
             <CometChatMessageHeader group={selectedGroup} />
-            <CometChatMessageList group={selectedGroup} />
+            <CometChatMessageList group={selectedGroup} hideReplyInThreadOption={true} />
             <CometChatMessageComposer group={selectedGroup} />
           </>
         )}
@@ -503,7 +503,7 @@ export function ChatDrawer({ isOpen, onClose, targetUserId }: ChatDrawerProps) {
           <>
             <CometChatMessageHeader user={user} />
             <div style={{ flex: 1, overflow: "hidden" }}>
-              <CometChatMessageList user={user} />
+              <CometChatMessageList user={user} hideReplyInThreadOption={true} />
             </div>
             <CometChatMessageComposer user={user} />
           </>

package/skills/cometchat-placement/SKILL.md

@@ -1278,6 +1278,34 @@ These rules apply to ALL placement patterns. Violating any of them causes integr
 
 6. **Every CometChat container must have explicit dimensions.** Components fill 100% of their parent. If the parent has no height, the components collapse to zero. Always set `height`, `min-height`, or use flex/grid layout with a bounded container.
 
+6a. **Flex parents that hold a `CometChatMessageList` MUST set `minHeight: 0`** (and `minWidth: 0` for horizontal flex parents). The W3C default `min-height: auto` makes flex children refuse to shrink below their intrinsic content size — so once the conversation grows past the viewport, the list pushes the composer below the fold and the layout breaks. **This is the canonical chat-layout bug** — works fine for short conversations, breaks for long ones. The fix is one CSS property; the diagnosis takes hours if you don't know the rule.
+
+```tsx
+/* ✓ CORRECT — header + list + composer with the flex-shrink trap fixed */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <div style={{ flex: 1, display: "flex", flexDirection: "column", minHeight: 0 }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageHeader user={user} />
+    </div>
+    <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+      <CometChatMessageList user={user} hideReplyInThreadOption />
+    </div>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageComposer user={user} />
+    </div>
+  </div>
+</div>
+
+/* ✗ WRONG — list grows past the viewport once messages exceed visible area */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <CometChatMessageHeader user={user} />
+  <CometChatMessageList user={user} />          {/* takes intrinsic height, no scroll */}
+  <CometChatMessageComposer user={user} />     {/* falls off the bottom */}
+</div>
+```
+
+The wrap-each-component-in-a-flex-sized-div pattern is what makes this work. Don't pass the kit components directly as flex children — wrap them.
+
 7. **Resolve target users/groups before rendering CometChat components.** Use `CometChat.getUser(uid)` or `CometChat.getGroup(guid)` to get the full `CometChat.User` or `CometChat.Group` object. Do not pass a raw UID string to `user` props -- they expect object instances.
 
 8. **For SSR frameworks, wrap CometChat components appropriately.** See the `cometchat-core` skill, section 5 (SSR safety), for framework-specific patterns.

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

@@ -468,30 +468,78 @@ Vite's HMR replaces modules without a full page reload. CometChat's SDK holds a
 
 However, if you change the provider file itself during development, HMR may re-execute the module. The `initialized` flag prevents double-init, but the WebSocket connection from the previous module instance may linger. If you see duplicate messages or connection issues during development, do a full page reload (`Ctrl+Shift+R`).
 
-### Container height
+### Container height (and the flex-shrink trap that breaks chat layouts)
 
-CometChat components fill 100% of their container. The most common visual bug is components rendering with zero height because their container has no explicit dimensions. Always ensure the chat container has a height:
+CometChat components fill 100% of their container. Two visual bugs to avoid:
+
+**Bug 1 — zero height:** components render with zero height because the container has no explicit dimensions.
+**Bug 2 — message list grows past the viewport:** the list scrolls fine until it has too many messages, then pushes the composer below the fold. **This is the classic flex-shrink trap.**
+
+The hard rule for two-pane / header+list+composer layouts: every flex container in the chain MUST have `minHeight: 0` (and `minWidth: 0` for horizontal flex). Without it, browsers default flex-children to `min-height: auto` (their intrinsic content size), so the list grows beyond the parent's bounds as messages accumulate.
 
 ```tsx
-/* CORRECT: explicit height */
+/* ✓ CORRECT: explicit height for a single-component surface */
 <div style={{ height: "100vh" }}>
   <CometChatConversations ... />
 </div>
 
-/* CORRECT: flex layout with bounded parent */
+/* ✓ CORRECT: header + list + composer with the flex-shrink trap fixed */
 <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
   <nav>...</nav>
-  <div style={{ flex: 1 }}>
-    <CometChatConversations ... />
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minHeight: 0,        // ← THIS IS THE HARD RULE — without it, list grows past the viewport
+  }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageHeader user={user} />
+    </div>
+    <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+      <CometChatMessageList user={user} />
+    </div>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageComposer user={user} />
+    </div>
   </div>
 </div>
 
-/* WRONG: no height constraint -- component collapses to zero */
+/* ✓ CORRECT: two-pane (sidebar + active chat) — both axes need min-{width,height}: 0 */
+<div style={{ display: "flex", height: "100vh" }}>
+  <div style={{ width: 360, display: "flex", flexDirection: "column" }}>
+    <CometChatConversations onItemClick={...} />
+  </div>
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minWidth: 0,         // ← horizontal flex parent: prevents content from forcing horizontal scroll
+    minHeight: 0,        // ← vertical flex (the inner column): prevents the list-overflow bug
+  }}>
+    {/* header / list / composer wrapped as above */}
+  </div>
+</div>
+
+/* ✗ WRONG: no height constraint — component collapses to zero */
 <div>
   <CometChatConversations ... />
 </div>
+
+/* ✗ WRONG: flex parent without minHeight: 0 — list grows past the viewport once
+   you accumulate more messages than fit on-screen. Composer falls off the bottom. */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <CometChatMessageHeader user={user} />
+  <CometChatMessageList user={user} />          {/* takes intrinsic content height */}
+  <CometChatMessageComposer user={user} />     {/* gets pushed below the fold */}
+</div>
 ```
 
+**Why `minHeight: 0` is non-obvious:** the W3C spec sets the default `min-height` of a flex item to `auto` (its intrinsic content height). For a scrollable list inside a flex column, this means the list refuses to shrink below its content even when the parent is bounded. Setting `minHeight: 0` on the flex parent overrides this, letting the list shrink and scroll within the bounded container instead of overflowing it.
+
+**The rule, restated as something to grep for:**
+
+> Every flex container that holds `CometChatMessageList` (directly or indirectly) MUST have `minHeight: 0` on it. Same for `minWidth: 0` on horizontal flex parents. Skip this and the layout works for short conversations and breaks for long ones.
+
 ### Vite dependency optimization
 
 Vite pre-bundles dependencies for faster dev startup. CometChat's packages are large and may trigger Vite's "new dependency found, reloading" message on first load. This is normal and only happens once. If it causes issues, you can pre-include the packages:

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

@@ -215,8 +215,8 @@ export default function ConversationView() {
     <>
       {user && <CometChatMessageHeader user={user} />}
       {group && <CometChatMessageHeader group={group} />}
-      {user && <CometChatMessageList user={user} />}
-      {group && <CometChatMessageList group={group} />}
+      {user && <CometChatMessageList user={user} hideReplyInThreadOption={true} />}
+      {group && <CometChatMessageList group={group} hideReplyInThreadOption={true} />}
       {user && <CometChatMessageComposer user={user} />}
       {group && <CometChatMessageComposer group={group} />}
     </>
@@ -326,25 +326,10 @@ export const useCometChat = () => useContext(CometChatContext);
 let initialized = false;
 let loginInFlight: Promise<unknown> | null = null;
 
-async function ensureLoggedIn(
-  uid: string,
-  authToken?: string,
-): Promise<void> {
-  const existing = await CometChatUIKit.getLoggedinUser();
-  if (existing) return;
-  if (loginInFlight) {
-    await loginInFlight;
-    return;
-  }
-  loginInFlight = authToken
-    ? CometChatUIKit.loginWithAuthToken(authToken)
-    : CometChatUIKit.login(uid);
-  try {
-    await loginInFlight;
-  } finally {
-    loginInFlight = null;
-  }
-}
+// `ensureLoggedIn` is defined inside `setup()` below so it can close over
+// the dynamically-imported `CometChatUIKit`. Hoisting it to module scope
+// would `ReferenceError` because the static import is intentionally
+// removed (SSR safety) — `CometChatUIKit` only exists inside the await.
 
 export function CometChatProvider({ children }: { children: React.ReactNode }) {
   const [isReady, setIsReady] = useState(false);
@@ -358,6 +343,23 @@ export function CometChatProvider({ children }: { children: React.ReactNode }) {
           "@cometchat/chat-uikit-react"
         );
 
+        async function ensureLoggedIn(uid: string, authToken?: string): Promise<void> {
+          const existing = await CometChatUIKit.getLoggedinUser();
+          if (existing) return;
+          if (loginInFlight) {
+            await loginInFlight;
+            return;
+          }
+          loginInFlight = authToken
+            ? CometChatUIKit.loginWithAuthToken(authToken)
+            : CometChatUIKit.login(uid);
+          try {
+            await loginInFlight;
+          } finally {
+            loginInFlight = null;
+          }
+        }
+
         if (!initialized) {
           initialized = true;