@cometchat/skills 4.4.2 → 5.0.1

package/skills/cometchat-react-native-core/SKILL.md

@@ -0,0 +1,335 @@
+---
+name: cometchat-react-native-core
+description: "Foundational rules for the CometChat React Native UI Kit v5 — install and the exact native peer deps, the provider chain, init → login → render ordering, the component map, and the production-ready core chat surface. Read this first for any React Native CometChat task. Triggers: add chat to my React Native app, CometChat React Native setup, Expo chat, RN chat UI kit, integrate CometChat RN, log out of chat RN, add a logout button, chat lifecycle React Native."
+license: "MIT"
+compatibility: "Node.js >=18; React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0; @cometchat/chat-sdk-react-native ^4.0.28; optional @cometchat/calls-sdk-react-native ^5.0.4"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native expo core rules initialization provider native"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json` (216 public symbols) +
+> `features.rn-v5.json`. Official docs: <https://www.cometchat.com/docs/ui-kit/react-native/overview> ·
+> scoped index `…/ui-kit/react-native/llms-react-native-v5.md`. Verify every symbol against the catalog;
+> fetch signatures from docs (`references/docs-map.md`); never trust memory.
+>
+> ⚠️ **React Native is NOT React.** Different package, different API, native views instead of DOM.
+> A React UI Kit snippet will not compile here. `references/docs-map.md` ends with the verified
+> React → React Native name table — read it before porting anything.
+
+## Use this skill when
+- "add chat to my React Native app" · "integrate CometChat in Expo" · "RN chat UI"
+- any React Native CometChat task — it is the assumed base for every other `cometchat-react-native-*` skill
+
+## Prerequisites & install
+
+**One package per platform.** Never mix `@cometchat/chat-uikit-react` (web) into an RN app.
+
+```bash
+npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
+```
+
+Then the **native peer deps — required, not optional.** Verified against `5.4.0` + the integration pages:
+
+```bash
+npm install @react-native-clipboard/clipboard \
+  react-native-gesture-handler react-native-svg react-native-video react-native-localize \
+  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs
+# Expo also needs: punycode
+```
+
+`cd ios && pod install` for bare RN. **A missing native module fails at MOUNT, not at build** — the
+error names a NativeModule, not CometChat, so it reads as unrelated.
+
+⚠️ **React Native >= 0.87:** RN removed `InteractionManager` from core and the kit (through 5.5.0)
+still calls it in the composer's iOS send path, so **sending a message throws on iOS** — it builds,
+typechecks and bundles clean. Fix and shim: `cometchat-react-native-troubleshooting` -> *Sending a
+message throws on iOS*.
+
+
+## Setup & credentials (essentials — full detail: `references/setup-credentials.md`)
+1. **Detect** the project: Expo (`app.json`/`app.config.js`) or bare RN (`metro.config.js`). Reuse an existing `.cometchat/config.json` or env if present — skip re-setup.
+2. **version_conflict — STOP** if `@cometchat/chat-uikit-react-native` is already in `package.json` at a non-v5 major; reconcile first, never mix majors (`RULES.md`).
+3. **Credentials — OFFER the dashboard fetch FIRST** (never silently "paste it yourself" — AUDIT-039). Offer both, defaulting to fetch: **(a) dashboard fetch (recommended)** — `npx @cometchat/skills-cli@3 auth login`, pick an EXISTING app (`provision list --json`; never auto-create), `provision use --app-id <id> --json` writes `.cometchat/config.json`; **(b) manual paste** from Dashboard → Credentials (dev-only Auth Key). **Then the SKILL writes the env (§4)** — the CLI stops at the fetch; env-writing and codegen are the SKILL's job. Full flow: `references/setup-credentials.md`.
+4. **Write env**: bare RN → `.env` (read via `react-native-config`); Expo → `.env` (read via `Constants.expoConfig.extra` or `process.env`). Gitignore it; never echo the Auth Key. Prod → server-minted auth token, not the Auth Key. **Nothing in a mobile bundle is secret** (IPA/APK are readable) — see `references/setup-credentials.md`.
+5. **Authorize** = `initFromSettings` then `login` both resolve; auth error is almost always the wrong Region.
+
+## Integration ordering (BAKED — invariant)
+
+**`init()` must resolve before `login()`. `login()` must resolve before you render any component.**
+Breaking it gives a blank screen, not an error.
+
+Use **`initFromSettings`**, not the classic `init` — it persists `integrationSource="ai-agent"`
+so CometChat can attribute the integration. The classic init does not (AUDIT-084), and a machine
+gate enforces this.
+
+```tsx
+import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+const settings: CometChat.CometChatSettings = {
+  appId: APP_ID,
+  region: REGION,
+  credentials: { authKey: AUTH_KEY }, // dev only — production mints an auth token server-side
+  chatSDK: {
+    presenceSubscription: { type: "ALL_USERS" },
+    autoEstablishSocketConnection: true,
+  },
+};
+
+await CometChatUIKit.initFromSettings(settings);
+await CometChatUIKit.login({ uid: UID });   // or ({ authToken }) in production
+```
+
+Note the shape: presence moves **into** `chatSDK.presenceSubscription.type` — it is not a
+top-level field and not a builder call.
+
+⚠️ **Two shapes that differ from React and will not compile if ported:**
+- settings is a **plain object** — there is no `UIKitSettingsBuilder` export in RN
+- `login` takes an **object**: `login({ uid })`, not `login(uid)`
+
+Use an existing UID from your dashboard (the sample apps seed `cometchat-uid-1`). Never invent one.
+
+## The provider chain (BAKED — order is load-bearing)
+
+Outermost first. Verified against the integration + recipe pages:
+
+```tsx
+<GestureHandlerRootView style={{ flex: 1 }}>
+  <SafeAreaProvider>
+    <CometChatI18nProvider>
+      <SafeAreaView style={{ flex: 1 }}>
+        <CometChatThemeProvider>
+          {/* screens */}
+        </CometChatThemeProvider>
+      </SafeAreaView>
+    </CometChatI18nProvider>
+  </SafeAreaProvider>
+</GestureHandlerRootView>
+```
+
+**`GestureHandlerRootView` is outermost and must carry `flex: 1`.** Omit it and swipe / long-press
+silently do nothing — no error, no warning. It is the single most common "the UI renders but nothing
+responds" cause on RN.
+
+## Sizing — flex, never viewport units
+
+There is no `100dvh` and no CSS. The rule: **every ancestor of a kit component is `flex: 1`**, and a
+scrolling column also needs `minHeight: 0`. A fixed pixel height breaks when the soft keyboard opens.
+The composer must remain visible with the keyboard up — verify on a device, not only a simulator.
+
+## Component / API map (BAKED closed list — from `catalogs/rn-v5.json`)
+
+| Need | Component |
+|---|---|
+| conversation list | `CometChatConversations` |
+| message pane | `CometChatMessageHeader` · `CometChatMessageList` · `CometChatMessageComposer` |
+| compact composer | `CometChatCompactMessageComposer` |
+| threads | `CometChatThreadHeader` |
+| search | `CometChatSearch` |
+| users / groups / members | `CometChatUsers` · `CometChatGroups` · `CometChatGroupMembers` |
+| calls | `CometChatCallButtons` · `CometChatIncomingCall` · `CometChatOutgoingCall` · `CometChatOngoingCall` · `CometChatCallLogs` |
+| theming / i18n | `CometChatThemeProvider` + `useTheme()` · `CometChatI18nProvider` |
+| extension chain | `ChatConfigurator` + `DataSourceDecorator` |
+
+Anything not in `catalogs/rn-v5.json` **does not exist** — do not emit it. Notably absent in v5:
+`CometChatErrorBoundary`, `CometChatDetails`, `CometChatAddMembers`, `CometChatBannedMembers`,
+`CometChatTransferOwnership`, and every `*WithMessages` composite. See `references/docs-map.md`
+for the SDK-fallback path for each.
+
+## Callback names — RN uses `Press`, not `Click`
+
+| Component | Wire these |
+|---|---|
+| `CometChatConversations` | `onItemPress` · `onSearchBarClicked` · `onError` |
+| `CometChatMessageList` | `onThreadRepliesPress` · `onError` |
+| `CometChatMessageHeader` | `showBackButton` (default `false`) + `onBack` · `onError` |
+| `CometChatSearch` | `onBack` · `onConversationClicked` · `onMessageClicked` |
+
+React's `onItemClick` / `onThreadRepliesClick` do not exist here.
+
+> ⚠️ **On `CometChatGroupMembers`, `onError` takes NO argument** in kits up to **5.5.0** —
+> `onError?: () => void`, unlike every other list. Type the handler with a parameter there and it fails
+> with TS2322. Write `onError={() => …}` and show the failure with the `ErrorView` slot, which needs no
+> error object. Fixed in the kit (uikit-react-native#1452); once that ships, the parameter is available
+> and this note goes away.
+
+## Golden path — the production-ready core surface
+
+The default for an unscoped "add chat". **One screen per route on a stack navigator with a real back
+button** — never two panes side by side, and never a web-style side panel.
+
+```tsx
+// ChatScreen.tsx — the message pane
+import {
+  CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer,
+} from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+import { View } from "react-native";
+
+export const ChatScreen = ({ user, group, onBack }: {
+  user?: CometChat.User; group?: CometChat.Group; onBack: () => void;
+}) => (
+  <View style={{ flex: 1 }}>
+    {/* showBackButton defaults to FALSE on RN — without it onBack never fires */}
+    <CometChatMessageHeader user={user} group={group} showBackButton onBack={onBack} />
+    <CometChatMessageList user={user} group={group} />
+    <CometChatMessageComposer user={user} group={group} />
+  </View>
+);
+```
+
+```tsx
+// ConversationsScreen.tsx — the list, wired to open the pane
+import { CometChatConversations, CometChatUiKitConstants } from "@cometchat/chat-uikit-react-native";
+import { CometChat } from "@cometchat/chat-sdk-react-native";
+
+export const ConversationsScreen = ({ onOpen }: {
+  onOpen: (user?: CometChat.User, group?: CometChat.Group) => void;
+}) => (
+  <CometChatConversations
+    onItemPress={(conversation: CometChat.Conversation) => {
+      const isUser =
+        conversation.getConversationType() ===
+        CometChatUiKitConstants.ConversationTypeConstants.user;
+      isUser
+        ? onOpen(conversation.getConversationWith() as CometChat.User, undefined)
+        : onOpen(undefined, conversation.getConversationWith() as CometChat.Group);
+    }}
+  />
+);
+```
+
+### The core surface is FOUR things, not two
+
+`contracts.rn-v5.json` → `core-chat-surface` mandates all four by default, and the reviewer's G1
+gate fails an emit that ships fewer. A list ↔ message pane is **half the surface**:
+
+| Capability | Component | Wire |
+|---|---|---|
+| conversations | `CometChatConversations` | `onItemPress` |
+| messages | `CometChatMessageHeader` + `List` + `Composer` | `showBackButton` + `onBack` |
+| **threaded replies** | `CometChatThreadHeader` | `onThreadRepliesPress` → push a thread screen |
+| **search** | `CometChatSearch` | `showSearchBar={true}` **+** `onSearchBarClicked` → push a search screen |
+
+On RN both are **pushed screens**, not side panels. Search is opt-out only, and must cover the
+global (list) case *and* the in-chat case scoped to the open conversation.
+
+```tsx
+// message pane — thread entry point
+<CometChatMessageList
+  user={user}
+  group={group}
+  onThreadRepliesPress={(message) => openThread(message)}
+/>
+
+// conversation list — search entry point.
+// showSearchBar defaults to FALSE on RN (it is true on React), so the callback alone
+// silently ships a surface with no search. Both props, always.
+<CometChatConversations
+  onItemPress={open}
+  showSearchBar={true}
+  onSearchBarClicked={() => openSearch()}
+/>
+```
+
+The callbacks above are only the **entry points**. `openThread` and `openSearch` push screens, and
+those screens are where the two mandated components actually render — emit both, or the surface
+has tap targets that lead nowhere:
+
+```tsx
+// ThreadScreen — what openThread(message) pushes to.
+// parentMessageId is typed `string` on the list and `string | number` on the composer,
+// so the list needs .toString().
+function ThreadScreen({ route, navigation }) {
+  const { parentMessage, user, group } = route.params;
+  return (
+    <View style={{ flex: 1, minHeight: 0 }}>
+      <CometChatThreadHeader parentMessage={parentMessage} />
+      <CometChatMessageList
+        user={user}
+        group={group}
+        parentMessageId={parentMessage.getId().toString()}
+      />
+      <CometChatMessageComposer
+        user={user}
+        group={group}
+        parentMessageId={parentMessage.getId()}
+      />
+    </View>
+  );
+}
+```
+
+```tsx
+// SearchScreen — what openSearch() pushes to.
+// Omit uid/guid for the GLOBAL case (from the conversation list); pass one to scope the
+// search to the open conversation. Both cases are mandated — one screen serves both.
+function SearchScreen({ route, navigation }) {
+  const { user, group } = route.params ?? {};
+  return (
+    <CometChatSearch
+      onBack={() => navigation.goBack()}
+      uid={user?.getUid()}
+      guid={group?.getGuid()}
+      onConversationClicked={(conversation) => navigation.navigate("Messages", { conversation })}
+      onMessageClicked={(message) => navigation.navigate("Messages", { message })}
+      onError={(e) => console.error(e)}
+    />
+  );
+}
+```
+
+> **Search:** `CometChatSearch` is documented at `{DOCS_BASE}/ui-kit/react-native/search` (fetch it
+> via `references/docs-map.md`); wire `onConversationClicked` / `onMessageClicked` and its `onBack`.
+> (Formerly tracked as gap RN-G1 — the page has since been published.)
+
+**Every affordance that is visible by default is wired or hidden.** A tap target that does nothing is
+a defect, and so is an opened surface with no way back — if you open search or a thread, wire its
+`onBack` in the same edit.
+
+## Deep references (load only when the task needs them)
+- `references/docs-map.md` — intent → the exact docs page; the SDK-fallback table; the React→RN name table. **Read before porting any React snippet.**
+- `references/component-props.md` — baked props + **PascalCase view slots** per drop-in, and the defaults that differ from React (`showSearchBar` is `false` here). **Read before placing custom UI** — it goes in a slot, never as a sibling.
+- `references/anti-patterns.md` — the 13 failures that actually break an RN integration, each with why its error names the wrong thing.
+- `references/lifecycle.md` — `initFromSettings` → login → render, and the promise-cached boot guard (a boolean flag does not work).
+- `references/layout.md` — the four sizing invariants the `core-chat-surface` contract gates on.
+- `references/dependencies.md` — the exact peer set + the native config that is not optional (Podfile modular headers, gesture-handler import order).
+- `references/setup-credentials.md` — dev vs production auth, and why nothing in a mobile bundle is secret.
+
+## Common pitfalls
+1. **Missing `GestureHandlerRootView`** — gestures silently dead. Outermost, `flex: 1`.
+2. **Rendering before `login()` resolves** — blank screen, no error.
+3. **Porting React code** — `UIKitSettingsBuilder`, `login(uid)`, `onItemClick`, CSS, `document.*`: none exist here.
+4. **Fixed heights** — breaks on keyboard open. Use `flex: 1` + `minHeight: 0`.
+5. **Shipping the Auth Key** — dev only; production mints an auth token server-side.
+
+## Verify it works
+- Every emitted symbol appears in `catalogs/rn-v5.json`.
+- Code compiles against the pinned kit: `npm run verify:fences:rn-v5`.
+- Oracles agree with the kit and docs: `npm run verify:sync:rn-v5`.
+- **`tsc --noEmit` in the APP is not clean, and that is not the app's bug.** The kit ships raw
+  `src/*.tsx` as its `main`/`module` with no built declarations, so TypeScript follows the import and
+  typechecks the kit itself (`NodeJS` namespace, implicit `any`, `isolatedModules` re-exports,
+  `User | null`, and on RN 0.87 a `RefObject<TextInputType>` mismatch). Gate on the **Metro bundle**
+  instead — `npx react-native bundle --platform ios|android --dev false --entry-file index.js
+  --bundle-output /dev/null` — and if you want a typecheck, filter the kit's own files out of the
+  output. Never "fix" node_modules, and never report the app as failing typecheck because of them.
+- **Getting the app to actually RUN on a shared machine.** React Native asks for Metro on port 8081
+  and takes whatever answers: another project's packager serves a foreign bundle, and the app dies
+  with `Invariant Violation: TurboModuleRegistry.getEnforcing('PlatformConstants')` — a version
+  mismatch that reads like a missing native module. iOS: point the app at your packager with
+  `xcrun simctl spawn <udid> defaults write <bundle-id> RCT_jsLocation "localhost:<port>"`
+  (`RCT_METRO_PORT` does not change the runtime URL). Android: `adb reverse tcp:8081 tcp:<port>`, and
+  when that silently does nothing — it does on some emulators — embed the bundle instead:
+  `npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output
+  android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res`, then
+  `run-android`. Remove that file before going back to Fast Refresh.
+- On a device: chat fills the screen, the composer survives the keyboard, back works, gestures respond.
+
+## Explain what you built (REQUIRED close)
+Tell the user briefly: **(1) what I wired** (3–5 bullets, NAME the files); **(2) decisions & why**, flagging dev-only AS dev-only (the **Auth Key** is dev-only → server-minted auth token for production; the `<uid>` you used; Expo vs bare RN path); **(3) what I did NOT touch** (additive — navigation/auth/styles intact). Then **offer these THREE options as a selectable choice and WAIT — do not auto-continue:**
+- **① Add another feature** — check what's already wired; ASK which Dashboard extensions are enabled; suggest 3–4 gaps (**calls · push · AI smart replies · polls · stickers · translation · notification feed**). Never suggest reactions or mentions — they are ON by default in v5. → `cometchat-react-native-features` / `cometchat-react-native-calls` / `cometchat-react-native-push`.
+- **② Customize theming** — ask for brand color / light-dark → `cometchat-react-native-customization`.
+- **③ Test it manually** — hand it back so they run it on a device.

package/skills/cometchat-react-native-core/references/anti-patterns.md

@@ -0,0 +1,79 @@
+# anti-patterns — what breaks a CometChat React Native integration
+
+Every entry here is a failure **observed in this codebase**, not a generic warning. Ordered by how
+often it bites and how misleading its error is.
+
+## The meta-pattern: RN errors name the wrong culprit
+Three properties make RN bugs hard to read, and all of them appear below:
+- **native modules fail at MOUNT, not build** — the app starts, then a screen explodes
+- **the error names a peer dependency**, not CometChat — `gesture-handler`, `svg`, Ruby, generated C++
+- **an unknown prop is silently ignored** — no error, nothing renders
+
+So "the error doesn't mention CometChat" is evidence of nothing.
+
+---
+
+## 1. Porting React code
+The React UI Kit is a **different package with a different API**. These do not exist on RN:
+
+| React | React Native |
+|---|---|
+| `new UIKitSettingsBuilder()…build()` | a plain `CometChatSettings` object |
+| `CometChatUIKit.login(uid)` | `login({ uid })` — an **object** |
+| `onItemClick` · `onThreadRepliesClick` | `onItemPress` · `onThreadRepliesPress` |
+| `itemView` · `trailingView` (camelCase) | `ItemView` · `TrailingView` (**PascalCase**) |
+| `CometChatMessagePlugin` / `PluginRegistry` | `ChatConfigurator` + `DataSourceDecorator` |
+| `CometChatErrorBoundary` | none — use a plain React error boundary |
+| `setCallingEnabled(true)` | **nothing** — installing the calls package IS the switch |
+| CSS variables / `className` | `CometChatThemeProvider` + `useTheme()` |
+
+**The PascalCase one is the nastiest**: an unknown prop throws nothing and renders nothing, so the
+custom UI just never appears.
+
+## 2. Same prop name, opposite default
+`showSearchBar` is **`true` on React** and **`false` on React Native**. Wiring
+`onSearchBarClicked` without `showSearchBar={true}` ships a surface where search can never be
+reached — and it compiles, and every symbol exists. See `component-props.md`.
+
+## 3. Missing `GestureHandlerRootView`
+Gestures silently stop working. No error. It must be **outermost** and carry `flex: 1`.
+On bare RN, `import 'react-native-gesture-handler'` must also be the **first line of `index.js`** —
+wrong ordering often works in debug and **crashes in release**.
+
+## 4. Rendering before `login()` resolves
+Blank screen, no exception. Gate the render; cache the boot **promise**, not a boolean
+(`lifecycle.md`).
+
+## 5. Fixed heights
+Breaks the moment the soft keyboard opens. `flex: 1` everywhere, `minHeight: 0` on scrolling
+columns (`layout.md`).
+
+## 6. Web-shaped layout
+Side panels, two panes side by side, state-toggled views. On a phone every surface is its own
+**screen** on a stack navigator with the OS back button (`placement`).
+
+## 7. Two headers
+The navigator's header plus `CometChatMessageHeader`. Set `headerShown: false` on that screen.
+
+## 8. Hand-rolling what the kit ships
+A `TextInput` composer, a `FlatList` of messages, a `react-native-image-picker` flow. All exist as
+drop-ins. Custom UI goes **in a view slot**, never as a sibling above the component.
+
+## 9. Shipping the Auth Key
+No client-side hiding works. Production mints an auth token server-side (`setup-credentials.md`).
+
+## 10. Leaking listeners
+Every `add*Listener(id, …)` needs `remove*Listener(id)` on teardown. The **SDK** holds the
+listener, not React, so it survives unmount — the top cause of duplicate messages, and it worsens
+the longer the app runs.
+
+## 11. Ban without unban
+`CometChatGroupMembers` lists **active** members only, and v5 ships no banned-members UI. An app
+that can ban but not view or unban is an unclosed round trip.
+
+## 12. Believing a simulator
+Calls need camera and mic; push needs delivery to a backgrounded or killed app. **Neither works on
+a simulator.** A green simulator run proves the screens render, not that the feature works.
+
+## 13. Reloading after a native change
+Metro reload only refreshes JavaScript. New native module, Gradle edit or plist change ⇒ **rebuild**.

package/skills/cometchat-react-native-core/references/component-props.md

@@ -0,0 +1,105 @@
+# component-props — BAKED stable props + view slots for the React Native v5 drop-ins
+
+Verified against `@cometchat/chat-uikit-react-native@5.4.0` **source**, not prose. Exhaustive prop
+lists still come from the docs (`docs-map.md`); this file bakes the ones you need on the hot path
+and the ones that are traps.
+
+## THE RULE — custom UI goes in the component's OWN view slot, NEVER as a sibling on top
+A custom header, search icon or action button rendered *above* a list double-renders the header and
+breaks scrolling. Put it in the component's slot so the component keeps its own layout, scroll and
+empty/error states.
+
+⚠️ **RN slot props are PascalCase** (`ItemView`, `TrailingView`). React's camelCase form is
+**silently ignored** — no error, nothing renders.
+
+---
+
+## ⚠️ Defaults that differ from React — verified from source
+
+| Prop | React | **React Native** | Consequence |
+|---|---|---|---|
+| `showSearchBar` | `true` | **`false`** | **The search bar is HIDDEN by default.** `onSearchBarClicked` can never fire unless you also pass `showSearchBar={true}`. Wiring the callback alone silently ships a surface with no search. |
+| `showSmartReplies` | `false` | `false` | same |
+| `showConversationStarters` | `false` | `false` | same |
+| `showConversationSummaryButton` | `false` | `false` | same |
+| `showMarkAsUnreadOption` | `false` | `false` | same |
+
+Every `show*` prop is opt-**in**; every `hide*` prop is opt-**out**. When a feature "does nothing
+after enabling it in the dashboard", the missing `show*` prop is the usual cause.
+
+---
+
+## CometChatConversations
+**Props:** `onItemPress(conversation)` · `onItemLongPress` · `onSearchBarClicked` · `onSelection` ·
+`onError` · `onEmpty` · `onLoad` · `showSearchBar` (**default `false`**) · `hideHeader` ·
+`hideBackButton` · `hideError` · `disableSoundForMessages` · `conversationsRequestBuilder`.
+
+**View slots (PascalCase):** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` ·
+`TrailingView` · `SearchView` · `EmptyView` · `ErrorView` · `LoadingView`.
+
+> **Search in the list → `showSearchBar={true}` + `onSearchBarClicked` → push a search screen.**
+> Both, or search is invisible.
+
+> **Scope the list with `conversationsRequestBuilder`.** 1:1-only app →
+> `.setConversationType("user")`; groups-only → `.setConversationType("group")`.
+> ⚠️ **Pass the builder INSTANCE, not `.build()`** — the kit calls `.build()` internally
+> (`CometChatConversations.tsx:1670`), and the RN docs say so explicitly. Passing the built object
+> breaks the list.
+> ```tsx
+> import { CometChat } from "@cometchat/chat-sdk-react-native";
+> <CometChatConversations
+>   conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setLimit(30)}
+> />
+> ```
+
+## CometChatUsers / CometChatGroups
+**Props:** `onItemPress` · `onError` · `onEmpty` · `onLoad` · `usersRequestBuilder` /
+`groupsRequestBuilder` (same instance-not-`.build()` rule).
+**Slots:** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` ·
+`EmptyView` · `ErrorView` · `LoadingView`.
+
+## CometChatMessageHeader
+**Props:** `user` · `group` · `onBack` · `onError` · `showBackButton` · `hideVoiceCallButton` ·
+`hideVideoCallButton` · `hideNewChatButton` · `hideChatHistoryButton` ·
+`showConversationSummaryButton` (**default `false`**) · `onConversationSummaryPress`.
+**Slots:** `ItemView` · `TitleView` · `SubtitleView` · `LeadingView` · `TrailingView` ·
+`AuxiliaryButtonView`.
+
+> Call buttons render here **by default** — do not also mount `CometChatCallButtons` in the header
+> or they double up.
+
+## CometChatMessageList
+**Props:** `user` · `group` · `onThreadRepliesPress` · `onError` · `onEmpty` · `onLoad` ·
+`messageRequestBuilder` · `reactionsRequestBuilder` · `showSmartReplies` (**default `false`**) ·
+`showConversationStarters` (**default `false`**) · `showMarkAsUnreadOption` (**default `false`**) ·
+plus `hide*` toggles for every message option (`hideReplyInThreadOption`, `hideReactionOption`,
+`hideCopyMessageOption`, `hideDeleteMessageOption`, `hideEditMessageOption`,
+`hideMessagePrivatelyOption`, `hideTranslateMessageOption`, `hideFlagMessageOption`,
+`hideMessageInfoOption`, `hideShareMessageOption`, `hideTimestamp`, `hideGroupActionMessages`).
+**Slots:** `HeaderView` · `FooterView` · `EmptyView` · `ErrorView` · `LoadingView` ·
+`messageBubbleView` · `NewMessageIndicatorView`.
+
+> **Threads:** `onThreadRepliesPress` → push a screen with `CometChatThreadHeader`. Not
+> `onThreadRepliesClick` (React's name), and not a side panel.
+> **AI features need BOTH** the dashboard toggle **and** the `show*` prop — the prop is `false` by default.
+
+## CometChatMessageComposer
+**Props:** `user` · `group` · `disableTypingEvents` · `disableMentions` · `disableMentionAll` ·
+`disableSoundForOutgoingMessages` · `hideAttachmentButton` · `hideSendButton` ·
+`hideVoiceRecordingButton` · `hideStickersButton` · `hideAuxiliaryButtons` · plus per-attachment
+toggles (`hideImageAttachmentOption`, `hideVideoAttachmentOption`, `hideFileAttachmentOption`,
+`hideAudioAttachmentOption`, `hideCameraOption`, `hidePollsAttachmentOption`,
+`hideCollaborativeDocumentOption`, `hideCollaborativeWhiteboardOption`).
+**Slots:** `HeaderView` · `SendButtonView` · `AuxiliaryButtonView` · `CustomView`.
+
+> The composer owns attachments. A hand-rolled `react-native-image-picker` flow means the built-in
+> was missed.
+
+## CometChatSearch
+**Props:** `onBack` · `onConversationClicked` · `onMessageClicked` · `onError` ·
+`hideBackButton` · `conversationsRequestBuilder` · `messagesRequestBuilder`.
+
+> Opened from `onSearchBarClicked` as a **pushed screen**. Wire `onBack` in the same edit — an
+> opened surface with no way back is a dead end.
+> **In-chat search must be SCOPED** to the open conversation via the request builders; unscoped, a
+> header search leaks whole-app results.

package/skills/cometchat-react-native-core/references/dependencies.md

@@ -0,0 +1,62 @@
+# dependencies — the exact React Native peer set
+
+Verified against `@cometchat/chat-uikit-react-native@5.4.0` `package.json` + the integration pages.
+**Take this list verbatim — do not infer it.** A missing native module fails at **mount**, not at
+build, and the error names the peer (`gesture-handler`, `svg`, `video`), never CometChat.
+
+```bash
+npm install @cometchat/chat-uikit-react-native@5 @cometchat/chat-sdk-react-native@4
+npm install @react-native-clipboard/clipboard \
+  react-native-svg react-native-video react-native-localize react-native-gesture-handler \
+  react-native-safe-area-context @react-native-async-storage/async-storage@^2.1.2 dayjs
+```
+
+**Expo also needs `punycode`.** Bare RN then needs `cd ios && pod install`; Expo needs a fresh
+development build (`npx expo run:ios`) — **Expo Go cannot load custom native modules.**
+
+## Native config that is NOT optional
+
+| Platform | Requirement | Failure if missed |
+|---|---|---|
+| bare RN, iOS | two `modular_headers` lines in `ios/Podfile` (below) | **`pod install` fails outright** |
+| bare RN, both | `import 'react-native-gesture-handler'` as the **first line of `index.js`** | works in debug, **crashes in release** |
+| Expo | permissions in `app.json` (never in `ios/`/`android/` — prebuild overwrites them) | permission prompts never appear |
+
+```ruby title="ios/Podfile"
+target 'YourApp' do
+  pod 'SPTPersistentCache', :modular_headers => true
+  pod 'DVAssetLoaderDelegate', :modular_headers => true
+  # …
+end
+```
+
+The kit is a **Swift** pod depending on two pods that define no module, so a static-library build —
+the RN default — cannot link it. Both official CometChat sample apps carry exactly these two lines;
+the integration docs do not mention them (**RN-G14**).
+
+## Optional — calling
+```bash
+npm install @cometchat/calls-sdk-react-native@5
+# 6 REQUIRED peer deps — the calls SDK's declared peerDependencies. Pinned; do NOT float them.
+npm install @react-native-async-storage/async-storage@^2.1.2 react-native-background-timer@^2.4.1 \
+  react-native-performance@^5.1.2 react-native-svg@^15.12.0 react-native-url-polyfill@2.0.0 \
+  react-native-webrtc@124.0.7
+```
+⚠️ **Not** `@cometchat/calls-sdk-javascript` — that is the web package.
+⚠️ **`react-native-url-polyfill` + `react-native-performance` are BUNDLE-critical**, not runtime-optional:
+the UIKit does a module-scope `require("@cometchat/calls-sdk-react-native")` (`CallingPackage.ts`), so
+Metro resolves the calls SDK's peers even for a **chat-only** build — if the calls SDK is present in
+`package.json`, a missing `url-polyfill`/`performance` fails the Metro bundle with "Unable to resolve module".
+⚠️ Keep `react-native-performance` on **5.x** — 6.x is published and a floated `^6` makes every later
+`npm install` fail with ERESOLVE. (`@react-native-community/netinfo` and `react-native-callstats` are
+NOT declared peers of the calls SDK — do not add them for calling.)
+Floors: Android `minSdkVersion 24`, iOS deployment target `13.0` (the calls SDK podspec requires 13.0). Below them the build fails.
+
+## Version floors
+React Native **0.77+**. `@cometchat/chat-sdk-react-native@4` requires
+`@react-native-async-storage/async-storage` (it ships as a direct dependency, but autolinking needs
+it present and pod-installed).
+
+## After any native change — rebuild
+Metro reload only refreshes JavaScript. A new native module, a Gradle edit or a plist change needs a
+full rebuild. "I installed it and nothing changed" is almost always a missed rebuild.