@cometchat/skills 3.0.0 → 4.0.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-production/SKILL.md

@@ -539,6 +539,66 @@ A simpler approach: if any CometChat operation returns a 401 or auth error, re-f
 
 **Guard refresh calls with the same concurrency pattern.** If two components both see a 401 at the same time, two `loginWithAuthToken` calls race and the SDK throws *"Please wait until the previous login request ends."* Route token refresh through the same `ensureLoggedIn(uid, authToken)` helper defined in `cometchat-core`'s provider pattern — the module-level `loginInFlight` promise dedupes concurrent refreshes automatically.
 
+Concrete refresh handler — pair the helper from `cometchat-core` with the connection listener and a token-refetch path:
+
+```typescript
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+
+// Module-level — shared across every refresh attempt.
+// Identical shape to the one in cometchat-core § 2.
+let refreshInFlight: Promise<unknown> | null = null;
+
+async function refreshSession(uid: string): Promise<void> {
+  if (refreshInFlight) {
+    // Another component already triggered a refresh — wait for it,
+    // don't fire a second loginWithAuthToken.
+    await refreshInFlight;
+    return;
+  }
+
+  refreshInFlight = (async () => {
+    // 1. Fetch a fresh token from your server endpoint.
+    //    Your existing useCometChatToken hook (Step 1) calls /api/cometchat-token.
+    //    Extract that fetch into a helper so the refresh path can reuse it.
+    const res = await fetch("/api/cometchat-token", {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ uid }),
+    });
+    if (!res.ok) throw new Error(`Token refresh failed: ${res.status}`);
+    const { token } = (await res.json()) as { token: string };
+
+    // 2. Re-authenticate with the new token. SDK swaps the in-memory
+    //    session — no full reload needed.
+    await CometChatUIKit.loginWithAuthToken(token);
+  })();
+
+  try {
+    await refreshInFlight;
+  } finally {
+    refreshInFlight = null;
+  }
+}
+
+// Wire it into the connection listener so a disconnect triggers refresh.
+CometChat.addConnectionListener(
+  "auth-refresh-listener",
+  new CometChat.ConnectionListener({
+    onDisconnected: () => {
+      const uid = CometChatUIKit.getLoggedInUser()?.getUid();
+      if (uid) {
+        refreshSession(uid).catch((e) => {
+          console.error("CometChat refresh failed; user may need to re-login", e);
+        });
+      }
+    },
+  }),
+);
+```
+
+`refreshInFlight` mirrors `loginInFlight` from `cometchat-core` § 2 — same dedup pattern, separate promise so the initial-login and refresh paths don't accidentally serialize against each other. If the same component renders in StrictMode AND a 401 arrives during the second mount, the listener and the provider effect can both touch the SDK without colliding.
+
 ---
 
 ## 5. User management patterns

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;