@cometchat/skills 4.4.2 → 5.0.0

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.

package/skills/cometchat-react-native-core/references/docs-map.md

@@ -0,0 +1,126 @@
+# docs-map — CometChat React Native v5: intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> **Fetch rule:** always build a URL as `DOCS_BASE` + the path shown, then append `.md`.
+> Never hardcode a host anywhere else; never read `node_modules`/`.d.ts`.
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + an "AI Integration Quick Reference"
+block: package, peers, key props/methods). 51 of 56 RN pages carry that block — read it FIRST.
+```
+Fetch:  {DOCS_BASE}/ui-kit/react-native/message-list.md
+```
+Fallback order: `.md` twin → if it 404s, the same URL **without** `.md` (HTML) → **never** a `.d.ts`.
+
+## Scoped React Native index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/ui-kit/react-native/llms-react-native-v5.md
+```
+A React-Native-v5-only index of every page as a `.md` link (~3k tok) — use it to discover any page
+not in the table below. Global all-products index (large, ~25k tok; last resort): `{DOCS_BASE}/llms.txt`.
+
+## SDK docs — the FALLBACK reference (a feature the UI Kit has NO component for)
+The rule of the pack: **for every feature, first check whether the UI Kit has a component/prop for it**
+(this file's table + the catalog). **If it does — USE it. If it does NOT — drop to the React Native
+Chat SDK** and call its methods directly (the SDK is already installed under the UI Kit; init/login
+already use it). Look the method up — never guess:
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+- **SDK index (scoped — PREFER this):** `{SDK_DOCS_BASE}/sdk/react-native/llms-react-native-v4.md` —
+  a **React-Native-SDK-v4-only** routing index grouped by area (Messaging · Calling · Users · Groups ·
+  AI & campaigns · Listeners · Key Concepts). Start here to find the feature's page.
+  **Do NOT use the site-wide global `llms.txt`** except as a last resort.
+- **Convention:** `{SDK_DOCS_BASE}/sdk/react-native/<page>` + `.md`.
+- ⚠️ **RN has its OWN SDK.** It is `@cometchat/chat-sdk-react-native@4`, **not**
+  `@cometchat/chat-sdk-javascript`. Never fetch `/sdk/javascript/*` for a React Native task.
+
+### SDK-fallback features (kit v5 ships NO component — this is not optional depth)
+| Need | No component because | SDK path |
+|---|---|---|
+| user / group details screen | kit v5 removed `CometChatDetails` | `/sdk/react-native/groups-overview` → `CometChat.getUser` / `getGroup` |
+| add members | kit v5 removed `CometChatAddMembers` | `/sdk/react-native/group-add-members` → `addMembersToGroup` |
+| **banned members (view + unban)** | **no UI surface at all in v5** | `/sdk/react-native/group-kick-ban-members` → `BannedMembersRequestBuilder`, `unbanGroupMember` |
+| transfer ownership | kit v5 removed `CometChatTransferOwnership` | `/sdk/react-native/transfer-group-ownership` |
+| call log detail / history / participants | kit v5 keeps only the list | **calls** SDK → `CometChatCalls.CallLogRequestBuilder` |
+
+> An app that can **ban** but cannot **view or unban** is an unclosed round-trip — ship the pair.
+
+### PATTERN SOURCE for the above — the official sample app
+The kit has no component, so do **not** invent a layout. Cite the real implementation:
+`github.com/cometchat/cometchat-uikit-react-native/tree/v5/examples/SampleApp`
+(e.g. `src/components/CometChatDetails/CometChatUserDetails.tsx`).
+⚠️ Those are sample-app **directory paths**, not kit exports — never `import` them.
+
+## Don't fetch the hot path — it's baked
+Install, the provider chain, `init → login → render`, and the drop-in props for "add chat" are BAKED
+in `cometchat-react-native-core`. Fetch ONLY for exhaustive props, long-tail components, theming
+tokens, or feature enablement.
+
+## The 80% trigger table  (URL = `{DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| setup / init / login (bare RN) | `/ui-kit/react-native/react-native-cli-integration` |
+| setup (Expo) | `/ui-kit/react-native/expo-integration` |
+| conversation list (full props) | `/ui-kit/react-native/conversations` |
+| message list | `/ui-kit/react-native/message-list` |
+| message composer | `/ui-kit/react-native/message-composer` |
+| compact composer | `/ui-kit/react-native/compact-message-composer` |
+| message header | `/ui-kit/react-native/message-header` |
+| users / groups / group members | `/ui-kit/react-native/users` · `groups` · `group-members` |
+| threads | `/ui-kit/react-native/threaded-messages-header` |
+| theming / tokens / dark mode | `/ui-kit/react-native/theme` · `colors` · `component-styling` |
+| localization | `/ui-kit/react-native/localize` |
+| events | `/ui-kit/react-native/events` |
+| calls (UI) | `/ui-kit/react-native/calling-integration` · `call-features` · `call-buttons` · `call-logs` · `incoming-call` · `outgoing-call` |
+| AI / smart replies | `/ui-kit/react-native/ai-features` |
+| full-screen recipes | `/ui-kit/react-native/react-native-conversation` · `expo-conversation` |
+| task guides | `/ui-kit/react-native/guide-new-chat` · `guide-group-chat` · `guide-search-messages` · `guide-threaded-messages` · `guide-block-unblock-user` · `guide-message-privately` |
+
+## ⚠️ DOCS-GAP protocol — flag, never silently source-fill
+If a needed component/prop/SDK method is NOT covered by the docs, **FLAG it for the developer**
+(page · section · change · reason) and record it. Do **not** quietly read the kit source and bake the
+answer as if it were documented — that hides the gap and the next agent re-derives it.
+
+**Known open gaps for React Native (tracked on ENG-38205 as `RN-G*`):** no `components/search` page ·
+reactions undocumented · no per-bubble pages · attachment cluster undocumented · `ConversationStarter`
+/ `SmartReplies` undocumented · the `DataSourceDecorator` chain undocumented · six pages **import
+symbols the kit does not export** · the events page names APIs that do not exist.
+Until those land, build from the catalog + kit source **and say so in the flag**.
+
+## ⚠️ Names that differ from the React docs — never port a React snippet
+The React UI Kit is a different package with a different API. Verified against
+`@cometchat/chat-uikit-react-native@5.4.0`:
+
+| React (do NOT use on RN) | React Native |
+|---|---|
+| `new UIKitSettingsBuilder()…build()` | a plain `UIKitSettings` **object** — there is no builder export |
+| `CometChatUIKit.login(uid)` | `CometChatUIKit.login({ uid })` — an **object** |
+| `CometChatMessagePlugin` / `PluginRegistry` | `ChatConfigurator.enable(...)` + a `DataSourceDecorator` subclass |
+| `CometChatUrlFormatter` | `CometChatUrlsFormatter` (**plural**) |
+| `CometChatCollaborativeWhiteboardBubble` | `CometChatCollaborativeWhiteBoardBubble` (**capital B**) |
+| `CometChatFlagMessageDialog` | `CometChatReportDialog` |
+| `CometChatErrorBoundary` | none — use a plain React error boundary |
+| `CometChatThreadHeader` (same name, web layout) | same name, but it is a **screen**, not a side panel |
+| CSS variables / `--cometchat-*` | `CometChatThemeProvider` + `useTheme()` |
+
+| custom message type (decorator) | [message-list]({DOCS_BASE}/ui-kit/react-native/message-list.md) — "Filtering Messages" | The FETCH half (`getAllMessageTypes` / `getAllMessageCategories`) and the after-`login()` registration order. Overriding only `getAllMessageTemplates` renders a bubble that vanishes on reload. |

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

@@ -0,0 +1,61 @@
+# layout — the React Native sizing standard
+
+`contracts.rn-v5.json` gates four capabilities on this file: `flex-fill-screen-height` ·
+`flex-min-height-0` · `safe-area-ancestor-chain` · `keyboard-avoidance`. The **principle** is the
+same as web — the kit fills its container and must not reflow between loading and loaded — but the
+**recipe** is entirely different.
+
+## There is no viewport unit, and no CSS
+`100dvh`, `min-height`, `vh`, media queries: none exist. Height comes from **flex**, and the frame
+resizes when the keyboard opens.
+
+## The four invariants
+
+### 1. Every ancestor is `flex: 1`
+A kit component fills its parent. A parent with no height collapses it to **zero** — and on RN a
+zero-size view still **exists in the tree**, so it is `toExist` but not `toBeVisible`. That is why
+the Detox specs assert visibility, never existence.
+
+```tsx
+<View style={{ flex: 1 }}>
+  <CometChatMessageList user={user} />
+</View>
+```
+
+### 2. A scrolling column also needs `minHeight: 0`
+Without it the child grows instead of scrolling, and the composer is pushed off-screen.
+
+### 3. The provider chain order is load-bearing
+Outermost first — verified against the integration and recipe pages:
+
+```tsx
+<GestureHandlerRootView style={{ flex: 1 }}>   {/* OUTERMOST, and flex:1 */}
+  <SafeAreaProvider>
+    <CometChatI18nProvider>
+      <SafeAreaView style={{ flex: 1 }}>
+        <CometChatThemeProvider>{/* screens */}</CometChatThemeProvider>
+      </SafeAreaView>
+    </CometChatI18nProvider>
+  </SafeAreaProvider>
+</GestureHandlerRootView>
+```
+
+**Omit `GestureHandlerRootView` and gestures silently stop working** — no error, no warning. Swipe
+and long-press simply do nothing. It is the single most common "renders but doesn't respond" cause.
+
+### 4. The composer must survive the keyboard
+A fixed pixel height anywhere in the chain breaks when the soft keyboard opens. Verify with the
+keyboard **up**, on a device — a simulator's hardware keyboard can hide the problem.
+
+## No side panels — one screen per route
+The web kit toggles panels with state. On a phone every surface is its own screen on a stack
+navigator, with the OS back button. Search, threads and members are **pushed screens**. Details in
+the `placement` skill.
+
+## Anti-patterns
+| Don't | Why |
+|---|---|
+| `height: 600` on a chat container | breaks on keyboard open and on every other device size |
+| a `ScrollView` wrapping `CometChatMessageList` | the list scrolls itself; nesting breaks both |
+| `NavigationContainer` outside the providers | screens mount unthemed |
+| the message screen inside the tab navigator | the tab bar overlaps the composer |

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

@@ -0,0 +1,64 @@
+# lifecycle — init → login → render on React Native
+
+## The invariant
+**`init()` must resolve before `login()`. `login()` must resolve before any component renders.**
+Out of order fails **silently** — a blank screen, no exception.
+
+## Init with `initFromSettings` (not the classic init)
+`initFromSettings` persists `integrationSource="ai-agent"` for telemetry attribution; 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
+  chatSDK: {
+    presenceSubscription: { type: "ALL_USERS" },
+    autoEstablishSocketConnection: true,
+  },
+};
+```
+
+Presence lives **inside** `chatSDK.presenceSubscription.type` — not a top-level field, and not a
+builder call. There is no `UIKitSettingsBuilder` in RN.
+
+## Guard the boot so it runs once
+React re-renders, remounts and Fast Refresh can all fire the effect again. Two `login()` calls race
+and the second can reject. Cache the **promise**, not a boolean:
+
+```tsx
+let boot: Promise<void> | null = null;
+
+export function ensureReady() {
+  if (!boot) {
+    boot = (async () => {
+      await CometChatUIKit.initFromSettings(settings);
+      await CometChatUIKit.login({ uid: UID });   // ({ authToken }) in production
+    })();
+  }
+  return boot;
+}
+```
+
+A boolean flag does **not** work: the second caller sees `false` while the first is still awaiting.
+
+## Gate the render
+```tsx
+const [ready, setReady] = useState(false);
+useEffect(() => { ensureReady().then(() => setReady(true)).catch(console.error); }, []);
+if (!ready) return null;   // or your own splash
+```
+
+Rendering before `ready` gives the blank screen above.
+
+## Logout order
+**Unregister the push token first**, then `CometChatUIKit.logout()`. Reversed, the device keeps
+receiving the previous user's notifications — a privacy incident on a shared device, not a bug.
+
+## `login` is untyped — TypeScript will not help
+`login(...args: any)` in the `.d.ts`. The two real shapes are `login({ uid })` and
+`login({ authToken })`. A wrong call compiles and fails at runtime.

package/skills/cometchat-react-native-core/references/setup-credentials.md

@@ -0,0 +1,39 @@
+# setup-credentials — App ID, Region, Auth Key on React Native
+
+## The three values
+From the CometChat dashboard: **App ID** · **Region** (`us` / `eu` / `in`) · **Auth Key**.
+They go into `CometChat.CometChatSettings` — see `lifecycle.md`.
+
+## Nothing in a mobile bundle is secret
+This is the part web habits get wrong. A React Native bundle is **not** a server:
+
+`.env` files · `react-native-config` · `Constants.expoConfig` · obfuscation · ProGuard —
+**every one ends up readable in the shipped app.** Anyone can unzip an IPA or APK.
+
+So "hide the Auth Key in an env var" is not a mitigation. It changes nothing.
+
+## Dev vs production
+
+| | Dev | Production |
+|---|---|---|
+| Login | `login({ uid })` with the Auth Key in settings | `login({ authToken })` |
+| Auth Key ships? | acceptable locally | **never** |
+| Token source | — | your backend mints a short-lived, per-user, revocable token |
+
+```tsx
+const authToken = await fetchAuthTokenFromYourBackend();
+await CometChatUIKit.login({ authToken });
+```
+
+A production build should not carry `credentials.authKey` at all.
+
+## Which UID to log in as
+Use a UID that **already exists** in your dashboard app. The CometChat sample apps seed
+`cometchat-uid-1` … `cometchat-uid-5`. **Never invent one** — login fails with a confusing error,
+and it looks like a credential problem rather than a missing user.
+
+Creating users needs the Auth Key, so `CometChat.createUser` is a **backend** call made when your own
+signup completes. A client that can create users can create *any* user.
+
+## Verify before shipping
+Build a **release** bundle, then grep it for the Auth Key. It must not be present.

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

@@ -0,0 +1,198 @@
+---
+name: cometchat-react-native-customization
+description: "Theme, restyle and extend the CometChat React Native UI Kit v5 — theme modes and color tokens, per-component style objects, view slots, and the DataSource decorator chain for custom message types. Triggers: change CometChat colors React Native, dark mode RN chat, custom message bubble RN, brand the RN chat UI, custom message type React Native, restyle the message bubble, change the chat font, add a custom bubble RN."
+license: "MIT"
+compatibility: "React Native >=0.77; @cometchat/chat-uikit-react-native ^5.4.0"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "chat cometchat react-native customization theming styling datasource decorator"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react-native@5` + catalog `rn-v5.json`.
+> Docs: `/ui-kit/react-native/theme` · `colors` · `component-styling` · `message-bubble-styling`.
+> Fetch token names and style keys from docs — never invent them.
+
+## Companion skills (read first)
+- `cometchat-react-native-core` — install, provider chain, init→login→render. Assumed, not repeated here.
+
+## Use this skill when
+- "change the chat colors" · "brand the chat UI" · "dark mode" · "restyle the bubbles"
+- "custom message type" · "render my own bubble" · "add an option to the message menu"
+
+## Prerequisites & install
+None beyond `core`. Theming needs `CometChatThemeProvider` already in the chain (see `core`).
+
+## Customization mechanism — three layers, cheapest first
+
+**There is no CSS.** No stylesheets, no `className`, no `--cometchat-*` variables. If you are
+holding a React snippet with CSS custom properties, it does not apply here.
+
+### Layer 1 — theme mode + color tokens (whole app)
+The provider takes a `theme` prop shaped `{ mode, light, dark }`. `mode` is `"light"` · `"dark"` ·
+`"auto"` — **`"auto"` is what makes the kit follow the device (OS) light/dark setting** (it reads
+`useColorScheme()`); the provider default is already `"auto"`.
+
+```tsx
+// Fixed dark for the whole app.
+<CometChatThemeProvider theme={{ mode: "dark" }}>{/* … */}</CometChatThemeProvider>
+```
+
+```tsx
+// Follow the OS, branded in BOTH schemes. mode:"auto" is the switch;
+// set BOTH light and dark or dark falls back to defaults.
+<CometChatThemeProvider
+  theme={{
+    mode: "auto",
+    light: { color: { primary: "#F76808" } },
+    dark: { color: { primary: "#F8935B" } },
+  }}
+>
+  {/* … */}
+</CometChatThemeProvider>
+```
+
+`primary` drives buttons, outgoing bubbles and active states — it is usually the only token a brand
+change needs. Other common tokens: `textPrimary`, `background1`, `neutral50`, `extendedPrimary500`.
+**Fetch the full list** from `/ui-kit/react-native/colors.md` rather than guessing a token name.
+
+To follow the OS, use **`mode: "auto"`** and set both `light` and `dark`. Without the provider,
+system theme changes are not reflected at all.
+
+### Layer 2 — per-component style objects
+Every component takes a `style` prop holding named sub-style objects — plain RN style objects,
+not CSS:
+
+```tsx
+<CometChatConversations style={{ containerStyle: { backgroundColor: "#F7F7F7" } }} />
+```
+
+The same style keys can be set globally through the theme instead, which is preferable when the
+change should apply everywhere:
+
+```tsx
+<CometChatThemeProvider theme={{ light: { conversationStyles: { /* … */ } } }}>
+```
+
+Style-key names differ per component. Fetch them from that component's page
+(`/ui-kit/react-native/component-styling.md` and the component's own page) — do not pattern-match
+from another component.
+
+### Layer 3 — read the active theme in your own views
+`useTheme()` returns the **resolved** theme (already light-or-dark per `mode`), so custom views match
+the kit without re-deriving the palette:
+
+```tsx
+import { useTheme } from "@cometchat/chat-uikit-react-native";
+import { Text } from "react-native";
+
+const Label = () => {
+  const theme = useTheme();
+  return <Text style={{ color: theme.color.textPrimary }}>Chats</Text>;
+};
+```
+
+## Custom message types — the DataSource decorator chain
+
+⚠️ **RN does NOT have the React plugin API.** `CometChatMessagePlugin` and `CometChatPluginRegistry`
+do not exist in this kit; emitting them will not compile. RN uses a decorator chain.
+
+Extend `DataSourceDecorator`, override what you need, and register it with `ChatConfigurator.enable`:
+
+```tsx
+import {
+  ChatConfigurator, DataSourceDecorator, CometChatMessageTemplate,
+} from "@cometchat/chat-uikit-react-native";
+
+const ORDER_TYPE = "order";
+
+class OrderDataSource extends DataSourceDecorator {
+  // 0. IDENTITY — REQUIRED. The base DataSourceDecorator.getId() THROWS
+  // ("Method not implemented.") and ChatConfigurator.enable() calls getId() to
+  // dedupe the registry — so a subclass without this override crashes at
+  // ChatConfigurator.enable(...), NOT at render. Return a stable, unique id.
+  getId(): string {
+    return "order_message_datasource";
+  }
+
+  // 1. RENDER — how the bubble draws.
+  getAllMessageTemplates(theme?: any, params?: any): CometChatMessageTemplate[] {
+    const templates = super.getAllMessageTemplates(theme, params);
+    // append or replace a template here
+    return templates;
+  }
+
+  // 2. FETCH — WITHOUT THESE TWO THE MESSAGE IS NEVER RETRIEVED.
+  // CometChatMessageList builds its request from them:
+  //   requestBuilder.setTypes(ChatConfigurator.dataSource.getAllMessageTypes())
+  //   requestBuilder.setCategories(ChatConfigurator.dataSource.getAllMessageCategories())
+  // A type absent from those filters is excluded server-side. The bubble appears
+  // optimistically when sent, then vanishes on reload — with no error anywhere.
+  getAllMessageTypes(): string[] {
+    return [...super.getAllMessageTypes(), ORDER_TYPE];
+  }
+
+  getAllMessageCategories(): string[] {
+    const categories = super.getAllMessageCategories();
+    return categories.includes(CometChat.CATEGORY_CUSTOM)
+      ? categories
+      : [...categories, CometChat.CATEGORY_CUSTOM];
+  }
+}
+
+// AFTER login(), not merely after init(). CometChatUIKit.login() calls enableExtensions(),
+// whose first statement is ChatConfigurator.init() — "re-initialize data source". Anything
+// registered earlier is DISCARDED, so a decorator wired at module scope, or straight after
+// init(), silently disappears.
+await CometChatUIKit.login({ uid: UID });
+ChatConfigurator.enable((source) => new OrderDataSource(source));
+```
+
+**`getId()` is REQUIRED on every `DataSourceDecorator` subclass.** It is the ONE base method that
+does not delegate to the wrapped source — the base throws `Error("Method not implemented.")`, and
+`ChatConfigurator.enable()` calls `getId()` to dedupe the registry. Omit it and registration crashes
+at `ChatConfigurator.enable(...)` with `Method not implemented.` — NOT at render, so it reads as
+unrelated. Every built-in decorator (Polls, Stickers, Translation, LinkPreview, Collaborative*)
+overrides it; yours must too, returning a stable unique string.
+
+A custom message type is **two halves, and only one of them is obvious.** Render is
+`getAllMessageTemplates` / `getMessageTemplate`. Fetch is `getAllMessageTypes` /
+`getAllMessageCategories`. Ship the render half alone and everything looks right until the first
+reload, when every message of your type is gone — no error, no warning.
+
+`DataSourceDecorator` exposes ~50 overridable methods; the ones you usually want are **`getId`**
+(mandatory — see above), `getAllMessageTemplates`, `getMessageTemplate`, **`getAllMessageTypes`**,
+**`getAllMessageCategories`**, `getMessageOptions` (the long-press menu) and
+`getAuxiliaryOptions` (composer actions). Always call `super.<method>(...)` and modify the result —
+replacing it wholesale drops every built-in message type.
+
+> **DOCS GAP (RN-G10):** `DataSourceDecorator` / `MessageDataSource` / `ExtensionsDataSource` and
+> `ChatConfigurator.enable` are **not documented** on any RN page — the docs show only mutating
+> existing templates via `getAllMessageTemplates()`. Built from the kit source; flag this to the
+> developer rather than presenting it as documented.
+>
+> **Partially closed (2026-08-20).** `ui-kit/react-native/message-list` now documents the
+> half that actually breaks builds: a custom type must be registered for **fetch**
+> (`getAllMessageTypes` / `getAllMessageCategories`), not only for render, and the decorator must
+> be registered **after `login()`** because `enableExtensions()` re-runs `ChatConfigurator.init()`.
+> Still missing: a dedicated RN custom-message-types page covering `DataSourceDecorator` /
+> `MessageDataSource` / `ExtensionsDataSource` end to end. Owner: docs.
+
+## Customizing an existing bubble without a decorator
+To restyle rather than replace, prefer the theme's bubble style keys —
+`textBubbleStyles`, `imageBubbleStyles`, `fileBubbleStyles`, `pollBubbleStyles` and siblings.
+Fetch exact keys from `/ui-kit/react-native/message-bubble-styling.md`.
+
+## Common pitfalls
+1. **Reaching for CSS** — no stylesheets, no `className`, no `--cometchat-*`. Theme object + RN styles.
+2. **Emitting the React plugin API** — does not exist; use `ChatConfigurator` + `DataSourceDecorator`.
+3. **Omitting `getId()` on a decorator** — the base throws; `ChatConfigurator.enable()` calls it → crash at registration with `Method not implemented.`
+4. **Not calling `super`** in a decorator override — silently drops all built-in templates.
+5. **Setting only `light`** when the app follows the OS — dark mode then falls back to defaults.
+6. **Guessing token or style-key names** — fetch them; a wrong key fails silently rather than erroring.
+
+## Verify it works
+- Every symbol appears in `catalogs/rn-v5.json`.
+- `npm run verify:fences:rn-v5` compiles the examples against the pinned kit.
+- On device: toggle OS dark mode and confirm the surface follows; confirm a custom template renders
+  and built-in types still render alongside it.