@cometchat/skills 4.2.1 → 4.4.0

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

@@ -3,7 +3,6 @@ name: cometchat-native-core
 description: "Shared rules for CometChat React Native UI Kit v5. Always loaded alongside framework (expo/bare) and placement skills. Read this first."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5; @cometchat/chat-sdk-react-native ^4"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -16,7 +15,7 @@ This is the foundational skill for every CometChat React Native UI Kit v5 integr
 
 **Read this skill first, before any framework (`cometchat-native-expo-patterns` / `cometchat-native-bare-patterns`) or placement skill.**
 
-Ground-truth sources: `docs/ui-kit/react-native/overview.mdx`, `react-native-cli-integration.mdx`, `expo-integration.mdx`, `methods.mdx`, and `@cometchat/chat-uikit-react-native@5.3.3`'s `src/index.ts`.
+Ground-truth sources: `docs/ui-kit/react-native/overview.mdx`, `react-native-cli-integration.mdx`, `expo-integration.mdx`, `methods.mdx`, and `@cometchat/chat-uikit-react-native@5.3.8`'s `src/index.ts` (file-based `initFromSettings` GA). **Official docs:** https://www.cometchat.com/docs/ui-kit/react-native/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 
 ---
 
@@ -30,7 +29,55 @@ CometChatUIKit.init(settings)   →   CometChatUIKit.login({ uid })   →   rend
 
 Breaking this order produces a blank screen, a "CometChat is not initialized" runtime error, or a hung login. No exceptions.
 
-### UIKitSettings — the init object
+### File-based init with `cometchat-settings.json` (recommended)
+
+> **Version requirement (ENG-35866 — Skills Telemetry).** `CometChatUIKit.initFromSettings(settings)` reads a `cometchat-settings.json` object and lets the SDK self-report `integrationSource = "ai-agent"` to `/user_sessions`. It ships GA in **`@cometchat/chat-uikit-react-native >= 5.3.8`** + **`@cometchat/chat-sdk-react-native >= 4.0.25`** (npm `latest`). On an older UI Kit the method does not exist — use the flat-object `init()` **fallback** below.
+
+**Step 1 — create `cometchat-settings.json` at the project root.** Fill `appId` / `region` / `credentials.authKey` from the CLI `provision setup` output; leave everything else at the defaults below. Single source of credentials — no second copy to keep in sync.
+
+```json
+{
+  "appId": "APP_ID_HERE",
+  "region": "us",
+  "credentials": {
+    "authKey": "AUTH_KEY_HERE"
+  },
+  "chatSDK": {
+    "presenceSubscription": {
+      "type": "ALL_USERS",
+      "roles": []
+    },
+    "autoEstablishSocketConnection": true,
+    "adminHost": null,
+    "clientHost": null
+  },
+  "callsSDK": {
+    "host": null,
+    "adminHost": null,
+    "clientHost": null,
+    "callsHost": null
+  },
+  "uiKit": {
+    "subscribePresenceForAllUsers": true
+  }
+}
+```
+
+**Step 2 — init by importing the JSON.** Metro bundles JSON imports natively (no extra config), so the file is read at build time exactly like the web kit:
+
+```tsx
+// initFromSettings ships GA in @cometchat/chat-uikit-react-native >= 5.3.8 (ENG-35866)
+import { CometChatUIKit } from "@cometchat/chat-uikit-react-native";
+import cometchatSettings from "../cometchat-settings.json"; // adjust path to the file's location
+
+await CometChatUIKit.initFromSettings(cometchatSettings);
+// then: CometChatUIKit.login({ uid }) — see §2
+```
+
+- **Do NOT gitignore `cometchat-settings.json`.** The dev-mode `authKey` ships in the JS bundle either way; production integrations use server-minted auth tokens.
+- The init-once flag + "init before first render" rules below apply unchanged — just swap the `init({...})` call for `initFromSettings(cometchatSettings)`.
+
+### UIKitSettings — the init object (fallback — UI Kit before file-based init)
 
 The v5 RN UI Kit's `init()` takes a flat `UIKitSettings` object (NOT a `UIKitSettingsBuilder` like the web kit). Pass fields directly:
 
@@ -60,6 +107,16 @@ async function initCometChat(): Promise<void> {
   if (initialized) return;
   initialized = true;
 
+  // Fail loud if env vars didn't load (EXPO_PUBLIC_* not set, or a config
+  // module returning undefined). Empty creds otherwise surface later as a
+  // cryptic init/login failure that's hard to trace. (audit P0-5)
+  if (!APP_ID || !REGION || !AUTH_KEY) {
+    throw new Error(
+      "CometChat credentials are empty — check your EXPO_PUBLIC_* env (or config module) " +
+        "and restart Metro with --reset-cache after editing it.",
+    );
+  }
+
   await CometChatUIKit.init({
     appId: APP_ID,
     region: REGION,
@@ -80,12 +137,19 @@ Put the init call in a top-level `useEffect` (preferred — the provider pattern
 ### Development mode
 
 ```tsx
-const user = await CometChatUIKit.getLoggedInUser();
+let user;
+try {
+  user = await CometChatUIKit.getLoggedInUser();
+} catch (e: any) {
+  if (e?.code !== "NOT_FOUND") throw e;   // no-session is the expected "first run" path
+}
 if (!user) {
   await CometChatUIKit.login({ uid: "cometchat-uid-1" });  // note: OBJECT form
 }
 ```
 
+**⚠️ `getLoggedInUser()` THROWS `code: "NOT_FOUND"` when there's no session** — it does NOT return `null`. An uncaught throw here is the #1 cause of "app stuck on splash screen" — the provider's `setReady(true)` never fires. Always wrap in try/catch and treat `NOT_FOUND` as the normal first-run path. (Validated on `@cometchat/chat-uikit-react-native@5.3.5`, kit source `CometChatUIKit.getLoggedInUser`.)
+
 **⚠️ `login()` takes an object `{ uid: "..." }` on React Native**, not a bare string like on the web. Passing `"cometchat-uid-1"` directly silently fails.
 
 Every new CometChat app ships 5 pre-seeded test users — `cometchat-uid-1` through `cometchat-uid-5`. Use one for development.
@@ -104,7 +168,12 @@ Guard with a module-level in-flight promise, same pattern as the web skill:
 let loginInFlight: Promise<unknown> | null = null;
 
 async function ensureLoggedIn(uid: string, authToken?: string): Promise<void> {
-  const existing = await CometChatUIKit.getLoggedInUser();
+  let existing;
+  try {
+    existing = await CometChatUIKit.getLoggedInUser();
+  } catch (e: any) {
+    if (e?.code !== "NOT_FOUND") throw e;   // first-run path
+  }
   if (existing) return;
   if (loginInFlight) {
     await loginInFlight;   // reuse the pending promise
@@ -253,7 +322,12 @@ let initialized = false;
 let loginInFlight: Promise<unknown> | null = null;
 
 async function ensureLoggedIn(uid: string, authToken?: string): Promise<void> {
-  const existing = await CometChatUIKit.getLoggedInUser();
+  let existing;
+  try {
+    existing = await CometChatUIKit.getLoggedInUser();
+  } catch (e: any) {
+    if (e?.code !== "NOT_FOUND") throw e;   // first-run path
+  }
   if (existing) return;
   if (loginInFlight) {
     await loginInFlight;
@@ -376,17 +450,35 @@ npm install \
   @cometchat/chat-sdk-react-native \
   @cometchat/chat-uikit-react-native \
   react-native-gesture-handler \
-  react-native-safe-area-context
+  react-native-safe-area-context \
+  @react-native-clipboard/clipboard \
+  react-native-svg \
+  react-native-video \
+  react-native-localize \
+  punycode
 ```
 
+> The kit's declared peer deps include `@react-native-clipboard/clipboard`, `react-native-svg`, `react-native-video`, and `react-native-localize` (it imports all four) — install them or the bundle fails at runtime. `react-native-safe-area-context` is also required (imported by several components) though not formally declared.
+
+> **Why `punycode` — still REQUIRED on 5.3.7 (kit 5.3.7's markdown path needs it).** The kit's `CometChatAIAssistantMessageBubble` pulls in `react-native-markdown-display` → `markdown-it@^10` → `linkify-it@^2`, which does `require('punycode')`. **React Native / Metro does not bundle Node core modules**, so Metro can't resolve `punycode` unless you install the userland package → otherwise the bundle fails with `Unable to resolve module punycode`. (This is NOT version-gone-from-Node — it's RN not shipping Node core libs; affects any kit whose markdown/AI path is reachable, incl. 5.3.5 AND 5.3.7.) **Verified 2026-06-14 on a real `expo export`: Expo SDK 56 + RN 0.85.3 + kit 5.3.7 FAILED on `punycode` until the userland package was installed**, then bundled clean (5.5 MB Hermes). Keep `punycode` in the install list — it is load-bearing whenever any feature that renders markdown / the AI Assistant bubble is reachable.
+
 > Note: `react-native-reanimated` is NOT a peer dependency of the kit (verified against `@cometchat/chat-uikit-react-native@5.x` `peerDependencies`). Add it only if your own app uses it for other animations.
 
-Expo adds `expo-av` / `expo-image-picker` depending on which features you enable. Calls require the separate package:
+Expo adds `expo-av` / `expo-image-picker` depending on which features you enable. Calls require the separate package PLUS the WebRTC native peers AND the polyfill peers the calls-sdk imports but doesn't declare:
 
 ```bash
-npm install @cometchat/calls-sdk-react-native
+npm install @cometchat/calls-sdk-react-native \
+  @react-native-community/netinfo \
+  react-native-callstats \
+  react-native-webrtc \
+  react-native-background-timer \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 ```
 
+> `@react-native-community/netinfo`, `react-native-callstats`, and `react-native-webrtc` are the WebRTC native peers; `react-native-background-timer`, `react-native-url-polyfill/auto`, and `react-native-performance` are imported at the top of the calls-sdk `dist/polyfills/browser.js`, and `valibot` is consumed deeper in the calls state machine. The polyfill peers + valibot are NOT in the calls-sdk `peerDependencies` array — they fail at bundle resolution if missing. (Validated 2026-05-26 on `@cometchat/calls-sdk-react-native@5.0.0`.) Then run `npx expo prebuild` (Expo) or `cd ios && pod install` (bare) so the native modules get autolinked into the next debug build. This mirrors the lists in `cometchat-native-features` / `cometchat-native-expo-patterns` / `cometchat-native-bare-patterns` — see `cometchat-native-calls` for full calls setup.
+
 See `cometchat-native-features` for when to add the calls SDK.
 
 ---
@@ -405,3 +497,183 @@ See `cometchat-native-features` for when to add the calls SDK.
 | `cometchat-native-customization` | When customizing components (text formatters, events, DataSource) |
 | `cometchat-native-production` | When setting up server-side auth + user management |
 | `cometchat-native-troubleshooting` | When diagnosing build errors, runtime failures, permission issues |
+
+## Visual Builder integration
+
+When the dispatcher's Step 3.1 sets `customize=visual` and the framework maps to builder platform `react-native`, skills runs **`cometchat builder export --platform react-native`** — a single CLI command that downloads the canonical static template ZIP from `preview.cometchat.com/downloads/cometchat-builder-react-native.zip`, fetches the per-builder settings JSON via `GET /vcb/builders/{id}`, applies F3 + F10 missing-field defaults, and writes the result to `--output` (default: `src/config/`).
+
+The canonical app uses a **Zustand-backed config store** (`src/config/store.ts`) that exposes `useConfig(selector)` — components read theme tokens and feature flags reactively. The exported `config.json` carries the **envelope shape** `{ builderId, name, type, createdAt, updatedAt, expiresAt, settings: { chatFeatures, callFeatures, layout, style, noCode, agent } }` — the store reads `config.settings.*` from it (verified 2026-06-14 against a live `builder export --platform react-native`). Theme tokens live under `settings.style` (`{ theme, color, typography }`) — there is **no `settings.theme`** key. `settings.agent` (`{ chatHistory, newChat, agentIcon, showAgentIcon }`) IS present (AI-agent config).
+
+This is intentionally lighter than the React web copy (full `src/CometChat/` directory). The RN builder repo is a QR-driven sample with custom navigation that doesn't fit cleanly into the customer's existing navigator. So `builder export` extracts the **configuration plumbing only** (per the repo's own README §"Integration in Your Existing React Native App"), then skills writes a minimal wrapper that consumes the config in the customer's existing four-wrapper chain.
+
+### 1. Run `cometchat builder export`
+
+```bash
+cometchat builder export --platform react-native --json
+```
+
+Defaults to `--output src/config/`. The command writes:
+
+| File | Content |
+|---|---|
+| `src/config/store.ts` | Zustand store with full `AppConfig` typings, AsyncStorage persistence, `useConfig<T>(selector)` hook, `useConfigStore`. Verbatim from canonical ZIP. |
+| `src/config/config.json` | **Envelope-shape JSON** `{ builderId, name, type, createdAt, updatedAt, expiresAt, settings: { chatFeatures, callFeatures, layout, style, noCode, agent } }`. There is **no `theme` key** (theme tokens live under `settings.style.{theme,color,typography}`); `settings.agent` (`{chatHistory,newChat,agentIcon,showAgentIcon}`) IS present (verified live 2026-06-14). Settings come from `GET /vcb/builders/{id}`. `inAppSounds` / `mentionAll` are **CLI-injected defaults** (not returned by the builder). **No SKILLS-AUTO-GENERATED sentinel** (JSON forbids `//` comments). |
+
+Resync = re-run the same command with `--force` (full re-download + replace). See `cometchat-core` §11.6 for the resync contract.
+
+### Files patched
+
+| Path | Patch |
+|---|---|
+| `package.json` | `npm install zustand @react-native-async-storage/async-storage` — required by the copied `store.ts`. Then the normal `cometchat-native-{bare,expo}-patterns` deps (11 explicit peers on bare, `npx expo install` list on Expo). If `useConfig(state => state.settings.callFeatures.*).oneOnOne*` returns true, also add `@cometchat/calls-sdk-react-native@5.0.0` + the Cloudsmith `@cometchat/calls-lib-webrtc` tarball per `cometchat-native-calls`. |
+| Entry — `App.tsx` (bare) / `app/_layout.tsx` (Expo Router) | Init UI Kit + wrap the provider chain (`SafeAreaProvider → SafeAreaView → CometChatThemeProvider → CometChatI18nProvider`) with `theme` derived from `useConfig`. Template below. |
+| `App.tsx` line 1 (bare) / app entry (Expo Router) | Gesture-handler side-effect import. The reference app uses `import './gesture-handler';` (a local shim file) as the **first import in `App.tsx`** — not in `index.js`. Bare CLI projects without that shim use `import 'react-native-gesture-handler';` instead. Either form must be the top-of-file side-effect import. |
+| `index.js` (bare) | App registration. The reference wraps `<App />` in `<AppErrorBoundary><ActiveChatProvider>` before `AppRegistry.registerComponent`. Preserve the customer's existing `index.js` registration; only add these wrappers if you also copy the corresponding files. |
+| `src/utils/AppConstants.tsx` (canonical pattern) OR `.env` (Step 2c convention) | Credentials. Skills writes the canonical path the customer already had from §2 (Expo: `process.env.EXPO_PUBLIC_*`; bare: `@env` via `react-native-dotenv`). |
+| `ios/Podfile` + `ios/<App>/Info.plist` (bare) or `app.json` plugins (Expo) | Camera + microphone usage descriptions if any `callFeatures.voiceAndVideoCalling.*` is true. |
+
+### Entry-file init pattern (bare RN / Expo)
+
+```tsx
+// App.tsx
+import './gesture-handler'; // line 1, before any other import — gesture-handler side-effect
+                            // (bare CLI w/o the shim file: `import 'react-native-gesture-handler';`)
+import React, { useEffect, useState } from 'react';
+import { Platform } from 'react-native';
+import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
+import {
+  CometChatUIKit,
+  UIKitSettings,
+  CometChatThemeProvider,
+  CometChatI18nProvider,
+  CometChatTheme,
+} from '@cometchat/chat-uikit-react-native';
+import { CometChat } from '@cometchat/chat-sdk-react-native';
+import type { DeepPartial } from '@cometchat/chat-uikit-react-native/src/shared/helper/types';
+
+import { useConfig } from './src/config/store';
+import RootStackNavigator from './src/navigation/RootStackNavigator'; // your existing navigator
+
+// Map builder font name → platform-specific PostScript / asset name.
+// Verbatim from the canonical `App.tsx` inside the React Native Visual Builder
+// ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-react-native.zip).
+const FONT_MAP: Record<string, { regular: string; medium: string; bold: string }> = {
+  'times new roman': {
+    regular: Platform.OS === 'ios' ? 'TimesNewRomanPSMT' : 'times_new_roman_regular',
+    medium: Platform.OS === 'ios' ? 'TimesNewRomanPSMT' : 'times_new_roman_medium',
+    bold: Platform.OS === 'ios' ? 'TimesNewRomanPS-BoldMT' : 'times_new_roman_bold',
+  },
+  inter: {
+    regular: Platform.OS === 'ios' ? 'Inter-Regular' : 'inter_regular',
+    medium: Platform.OS === 'ios' ? 'Inter-Medium' : 'inter_medium',
+    bold: Platform.OS === 'ios' ? 'Inter-Bold' : 'inter_bold',
+  },
+  roboto: {
+    regular: Platform.OS === 'ios' ? 'Roboto-Regular' : 'roboto_regular',
+    medium: Platform.OS === 'ios' ? 'Roboto-Medium' : 'roboto_medium',
+    bold: Platform.OS === 'ios' ? 'Roboto-Bold' : 'roboto_bold',
+  },
+};
+
+export default function App() {
+  const styleConfig = useConfig(state => state.settings.style);
+  const [isReady, setIsReady] = useState(false);
+
+  useEffect(() => {
+    // RN kit takes a FLAT UIKitSettings object — there is NO UIKitSettingsBuilder
+    // on react-native (see §1; the builder is web-only). Using it throws
+    // "UIKitSettingsBuilder is not a constructor".
+    CometChatUIKit.init({
+      appId: process.env.EXPO_PUBLIC_COMETCHAT_APP_ID!,
+      region: process.env.EXPO_PUBLIC_COMETCHAT_REGION!,
+      authKey: process.env.EXPO_PUBLIC_COMETCHAT_AUTH_KEY!,
+      subscriptionType: "ALL_USERS",
+    }).then(() => setIsReady(true)).catch(console.error);
+  }, []);
+
+  const fontKey = styleConfig.typography.font.toLowerCase().trim();
+  const fontVariants = FONT_MAP[fontKey] ?? FONT_MAP.inter;
+
+  const theme: { light: DeepPartial<CometChatTheme>; dark: DeepPartial<CometChatTheme> } = {
+    light: {
+      color: {
+        primary: styleConfig.color.brandColor,
+        textPrimary: styleConfig.color.primaryTextLight,
+        textSecondary: styleConfig.color.secondaryTextLight,
+      },
+      typography: { fontFamily: fontVariants.regular },
+    },
+    dark: {
+      color: {
+        primary: styleConfig.color.brandColor,
+        textPrimary: styleConfig.color.primaryTextDark,
+        textSecondary: styleConfig.color.secondaryTextDark,
+      },
+      typography: { fontFamily: fontVariants.regular },
+    },
+  };
+
+  if (!isReady) return null;
+
+  return (
+    <SafeAreaProvider>
+      <SafeAreaView edges={['top', 'bottom']} style={{ flex: 1 }}>
+        <CometChatThemeProvider theme={theme}>
+          <CometChatI18nProvider>
+            <RootStackNavigator />
+          </CometChatI18nProvider>
+        </CometChatThemeProvider>
+      </SafeAreaView>
+    </SafeAreaProvider>
+  );
+}
+```
+
+**Critical:**
+
+- `useConfig(state => state.settings.style)` is the canonical hook — **not** a static `import` of the JSON. The store hydrates from AsyncStorage on first read; importing the JSON directly would freeze the initial values and skip QR-update / resync flows that may follow.
+- `CometChatThemeProvider`'s `theme` prop takes a `{ light, dark }` object (NOT a string like `"dark"`). The string-form `theme="dark"` was a v4-era shape and was removed in `chat-uikit-react-native@5+`.
+- The reference app's provider chain is `SafeAreaProvider → SafeAreaView → CometChatThemeProvider → CometChatI18nProvider`, and gesture-handler is wired as a **top-of-file side-effect import** (`import './gesture-handler';` on App.tsx line 1) — **not** as a `<GestureHandlerRootView>` wrapper. Match this. (If you deliberately add `<GestureHandlerRootView style={{ flex: 1 }}>` as the outermost wrapper for extra hardening, that is also valid — but it is not what the reference ships, so don't present it as required.) Skipping safe areas, theming, i18n, or the gesture-handler import breaks gestures, safe areas, theming, or i18n — and fails silently in dev.
+- `CometChatUIKit.init(settings)` returns a Promise — `isReady` gate before render prevents `RootStackNavigator` from mounting chat components before init resolves.
+- The canonical RN builder app also registers a `CometChat.addCallListener` at the App level (handles incoming calls / busy / cancelled / ended). When `callFeatures.voiceAndVideoCalling.*` is true, copy that listener block verbatim from the canonical `App.tsx` inside the React Native Visual Builder ZIP (download from https://preview.cometchat.com/downloads/cometchat-builder-react-native.zip) (look for `'app'` listener id).
+
+### Feature flag access
+
+Components throughout the customer's app can read flags reactively:
+
+```tsx
+const reactionsEnabled = useConfig(s => s.settings.chatFeatures.deeperUserEngagement.reactions);
+const audioCallsEnabled = useConfig(
+  s => s.settings.callFeatures.voiceAndVideoCalling.oneOnOneVoiceCalling,
+);
+```
+
+Hide buttons / disable composer actions / skip mounting components based on these. The full `AppConfig` typings are in the copied `src/config/store.ts`.
+
+### Resync flow
+
+The "Re-sync visual builder" iteration menu option (see `cometchat/SKILL.md § Step 7`) is a one-command re-run:
+
+```bash
+cometchat builder export --platform react-native --force --json
+```
+
+`--force` is required (it explicitly authorizes replacing the existing `src/config/`). The command re-downloads the canonical static template, re-fetches the per-builder settings, and replaces the directory entirely.
+
+Per the SKILLS-AUTO-GENERATED contract (see `cometchat-core` §11.6): customer hand-edits inside `src/config/` are lost on resync. Override via `App.tsx` (outside `src/config/`) or via the `useConfig` selector pattern documented in §"Theme derivation".
+
+The customer reloads the dev build (`r` in Metro) — `useConfig` rehydrates from AsyncStorage on next mount.
+
+### Calls + builder
+
+> **Version note (intentional divergence):** the reference builder app `builder-apps/uikit-builder-app-react-native` still ships `@cometchat/calls-sdk-react-native@^4.3.0` (no `@cometchat/calls-lib-webrtc`; it uses `react-native-webrtc` directly). Skills intentionally targets **calls SDK v5** per the calls-v5-canonical policy. If you diff the reference app, don't "correct" the skill back to 4.3.0 — the v5 guidance below is deliberate.
+
+If `callFeatures.voiceAndVideoCalling.*` is true:
+1. Add `@cometchat/calls-sdk-react-native@5.0.0` + the Cloudsmith `@cometchat/calls-lib-webrtc` tarball (per `cometchat-native-calls`).
+2. Wire `CometChat.addCallListener` + `CometChatUIEventHandler.addCallListener` in `App.tsx` — copy the listener block verbatim from the canonical app's `App.tsx`.
+3. Mount `<CometChatIncomingCall>` between `<CometChatI18nProvider>` and `<RootStackNavigator>` when an `incomingCall` ref is set. The full pattern is in the canonical `App.tsx`.
+4. Configure iOS PushKit + Android FCM data-message wiring — defer to `cometchat-native-push` and invoke it after the Visual Builder section completes.
+
+### What is NOT honored in v1
+
+`noCode.docked` (floating-widget shape) and `layout.withSideBar` don't have RN-native equivalents — RN uses tabs / stacks, not sidebars. The canonical `RootStackNavigator` from the builder repo IS NOT copied — the customer's existing navigator stays. Layout-tab features like `layout.tabs: ['chats','calls','users','groups']` need the customer's existing `bottom-tabs` navigator to add those tabs manually (skills can do this in a follow-up `cometchat-native-placement` flow). Theme + typography + chat features + call features ARE honored via `useConfig`.

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

@@ -3,7 +3,6 @@ name: cometchat-native-customization
 description: "Customize the CometChat React Native UI Kit without forking — four-tier model: props → request builders → text formatters + message templates → DataSource decorators + event bus."
 license: "MIT"
 compatibility: "Node.js >=18; React Native >=0.70; @cometchat/chat-uikit-react-native ^5"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -25,7 +24,7 @@ Tier 4 — DataSource decorators + Events  (last resort, powerful)
 
 **Read `cometchat-native-components` first** — the catalog is the source of truth for prop names, slot views, and event listener names that this skill builds on.
 
-Ground truth: `docs/ui-kit/react-native/custom-text-formatter-guide.mdx`, `mentions-formatter-guide.mdx`, `shortcut-formatter-guide.mdx`, `url-formatter-guide.mdx`, `events.mdx`, `methods.mdx`, `property-changes.mdx`, and the kit's source at `packages/ChatUiKit/src/shared/formatters/` and `packages/ChatUiKit/src/shared/events/`.
+Ground truth: `docs/ui-kit/react-native/custom-text-formatter-guide.mdx`, `mentions-formatter-guide.mdx`, `shortcut-formatter-guide.mdx`, `url-formatter-guide.mdx`, `events.mdx`, `methods.mdx`, `property-changes.mdx`, and the kit's source at `packages/ChatUiKit/src/shared/formatters/` and `packages/ChatUiKit/src/shared/events/`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react-native/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 
 ---
 
@@ -96,8 +95,10 @@ function CustomTitle({ user }: any) {
   return (
     <Text style={{
       color: theme.color.textPrimary,
-      fontFamily: theme.typography.heading3.fontFamily,
-      fontSize: theme.typography.heading3.fontSize,
+      // heading3 is a VARIANT { bold, medium, regular } — read a weight, not a flat field
+      // (verified vs uikit-react-native-v5 theme/default/typography.ts)
+      fontFamily: theme.typography.heading3.regular.fontFamily,
+      fontSize: theme.typography.heading3.regular.fontSize,
     }}>
       {user?.getName()}
     </Text>
@@ -213,7 +214,7 @@ class HashtagFormatter extends CometChatTextFormatter {
   constructor() {
     super();
     this.setTrackingCharacter("#");              // optional — triggers suggestion list
-    this.setRegexPatterns([/\B#(\w+)\b/g]);       // all matches get formatted
+    this.setRegexPatterns(/\B#(\w+)\b/g);         // takes a SINGLE RegExp, not an array (verified vs CometChatTextFormatter.ts: setRegexPatterns(regexPattern: RegExp))
   }
 
   // Called for each bubble's text; return string | JSX
@@ -273,7 +274,11 @@ const formatters = [
 
 ### 3b. Custom message template — entire custom bubble
 
-For rendering a totally custom message type (interactive cards, scheduling, forms), use `CometChatMessageTemplate`.
+For rendering a totally custom message type (interactive cards, scheduling, forms), use the kit's `CometChatMessageTemplate`.
+
+> **Wrong-namespace trap (verified against kit source):** the template class is `CometChatMessageTemplate`, exported from `@cometchat/chat-uikit-react-native` (`packages/ChatUiKit/src/shared/modals/CometChatMessageTemplate.ts:116`; re-exported at `src/index.ts:47`). **There is NO `CometChat.MessageTemplate`** on the Chat SDK — `new CometChat.MessageTemplate(...)` does not exist. Always import the class from the UI Kit.
+
+The constructor takes a **single options object** (`packages/ChatUiKit/src/shared/modals/CometChatMessageTemplate.ts:213-237`). View slots are **PascalCase** (`ContentView`, `BottomView`, `BubbleView`, `HeaderView`, `LeadingView`, `StatusInfoView`, `FooterView`, `ReplyView`); `options` is lowercase. The `options` callback signature is `(loggedInUser, message, theme, group?)` — note the **`theme` argument** before `group` (`CometChatMessageTemplate.ts:202-207`, invoked at `CometChatMessageList.tsx:3484` as `template.options(loggedInUser, item, mergedTheme, group)`).
 
 ```tsx
 import {
@@ -290,26 +295,116 @@ const pollTemplate = new CometChatMessageTemplate({
   BottomView: (message, alignment) => (
     <PollVoteCounts message={message} />
   ),
-  options: (loggedInUser, message, group) => [
+  options: (loggedInUser, message, theme, group) => [
     /* CometChatMessageOption[] — custom long-press menu items */
   ],
 });
+```
 
-<CometChatMessageList
-  user={selectedUser}
-  templates={[pollTemplate, ...defaultTemplates]}   // merge with defaults
-  hideReplyInThreadOption
-/>
+**Register by MERGING with the defaults — never replace.** The defaults accessor is `getAllMessageTemplates(theme, additionalParams?)` and it **requires the kit theme** (`packages/ChatUiKit/src/shared/framework/DataSource.ts:168`; impl at `MessageDataSource.tsx:1732`). The data source is reached via either `ChatConfigurator.getDataSource()` (`ChatConfigurator.ts:24`) or the equivalent `CometChatUIKit.getDataSource()` (`CometChatUIKit.ts:380`). Pass the theme from `useTheme()`:
+
+```tsx
+import {
+  ChatConfigurator,
+  useTheme,
+} from "@cometchat/chat-uikit-react-native";
+
+function Chat({ selectedUser }: any) {
+  const theme = useTheme();
+  // getAllMessageTemplates REQUIRES the theme arg
+  const defaults = ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
+
+  return (
+    <CometChatMessageList
+      user={selectedUser}
+      templates={[pollTemplate, ...defaults]}   // append your type, keep all built-ins
+      hideReplyInThreadOption
+    />
+  );
+}
 ```
 
-Getting the default templates to merge with:
+If you pass only `templates={[pollTemplate]}` you will REPLACE the built-in text/image/video/file/group-action templates and the conversation will render blank for every non-custom message. Always spread `...defaults`.
+
+### 3c. Override an existing type's bubble (text / image)
+
+To change how a *built-in* type renders (e.g. a custom text bubble), don't write a new type — get the default templates, find the matching one by `type`, swap its `ContentView`, and pass the whole array back via `templates`. This preserves every other type and keeps the type's default `options`, `ReplyView`, etc.
 
 ```tsx
-import { ChatConfigurator } from "@cometchat/chat-uikit-react-native";
-const defaults = ChatConfigurator.getDataSource().getAllMessageTemplates();
-<CometChatMessageList templates={[pollTemplate, ...defaults]} />
+import { ChatConfigurator, useTheme, CometChatUiKitConstants } from "@cometchat/chat-uikit-react-native";
+
+function Chat({ selectedUser }: any) {
+  const theme = useTheme();
+  const templates = ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
+
+  // type values come from CometChatUiKitConstants.MessageTypeConstants
+  const textTemplate = templates.find(
+    (t) => t.type === CometChatUiKitConstants.MessageTypeConstants.text,
+  );
+  if (textTemplate) {
+    textTemplate.ContentView = (message, alignment) => (
+      <MyCustomTextBubble message={message} alignment={alignment} />
+    );
+  }
+
+  return (
+    <CometChatMessageList
+      user={selectedUser}
+      templates={templates}   // mutated-in-place array — full default set, one view swapped
+      hideReplyInThreadOption
+    />
+  );
+}
 ```
 
+`ContentView`'s signature is `(messageObject: CometChat.BaseMessage, alignment: MessageBubbleAlignmentType) => JSX.Element | null` (`CometChatMessageTemplate.ts:131-134`). Branch on `alignment === "left" | "right"` if you want incoming-vs-outgoing variants.
+
+### 3d. Add a Forward-style long-press option to an existing type
+
+A long-press menu item is a **`CometChatMessageOption`** — a plain object type (`id`, `title`, optional `icon`, `onPress`, `CustomView`, `style`), defined at `packages/ChatUiKit/src/shared/modals/CometChatMessageOption.ts:6-18`, exported from `src/index.ts:45`.
+
+> **Wrong-namespace trap:** there is **no `CometChatActionsIcon` / `CometChatActionsView`** in the RN kit (that is the web kit's class — grep of `packages/ChatUiKit/src` returns zero hits). In RN, an option is the `CometChatMessageOption` object literal.
+
+Append yours by overriding the type's template `options` callback. Call the default-options accessor first, then add your item — append, don't replace:
+
+```tsx
+import {
+  ChatConfigurator,
+  useTheme,
+  CometChatUiKitConstants,
+} from "@cometchat/chat-uikit-react-native";
+import type { CometChatMessageOption } from "@cometchat/chat-uikit-react-native";
+
+function Chat({ selectedUser }: any) {
+  const theme = useTheme();
+  const templates = ChatConfigurator.getDataSource().getAllMessageTemplates(theme);
+
+  const textTemplate = templates.find(
+    (t) => t.type === CometChatUiKitConstants.MessageTypeConstants.text,
+  );
+  if (textTemplate) {
+    textTemplate.options = (loggedInUser, message, t, group) => {
+      // default long-press options for this message (reply, edit, delete, copy, ...)
+      const defaults = ChatConfigurator.getDataSource().getMessageOptions(
+        loggedInUser, message, t, group,
+      );
+      const forward: CometChatMessageOption = {
+        id: "forward",
+        title: "Forward",
+        onPress: (msg) => forwardMessage(msg),
+      };
+      return [...defaults, forward];   // append, keep the built-ins
+    };
+  }
+
+  return (
+    <CometChatMessageList user={selectedUser} templates={templates} hideReplyInThreadOption />
+  );
+}
+```
+
+The default-options accessor is `getMessageOptions(loggedInUser, messageObject, theme, group?, additionalParams?)` (`DataSource.ts:57-63`; impl `MessageDataSource.tsx:587`). It returns `CometChatMessageOption[]`. The template's `options` callback is invoked by the list as `template.options(loggedInUser, item, mergedTheme, group)` (`CometChatMessageList.tsx:3484`).
+
 ### When to use text formatter vs message template
 
 | Use formatter (Tier 3a) | Use template (Tier 3b) |
@@ -395,8 +490,11 @@ class MyDataSource extends DataSourceDecorator {
     return builder;
   }
 
-  getMessageTemplate() {
-    const defaults = super.getMessageTemplate();
+  // To register a custom type kit-wide, override getAllMessageTemplates —
+  // it returns the ARRAY. (getMessageTemplate(type, category, theme, ...)
+  // returns a SINGLE template-or-null, so don't merge an array there.)
+  getAllMessageTemplates(theme: any, additionalParams?: any) {
+    const defaults = super.getAllMessageTemplates(theme, additionalParams);
     return [myCustomTemplate, ...defaults];
   }
 }
@@ -488,19 +586,39 @@ You can also use `WebFetch` on the URLs above. The docs MCP does NOT index the s
 ### "Render custom avatars for all users based on their department"
 **Tier 1** — `LeadingView` slot on `CometChatConversations` + `CometChatUsers` + `CometChatMessageHeader`.
 
-### "Disable the file attachment option"
-**Tier 1** — filter the `attachmentOptions` prop on `CometChatMessageComposer`:
+### "Add a custom attachment option (or remove one)"
+**Tier 1** — the `attachmentOptions` prop on `CometChatMessageComposer`. **RN's signature is a single destructured object** `({ user, group, composerId }) => CometChatMessageComposerAction[]` (`CometChatMessageComposer.tsx:237-245`) — NOT the web kit's `(user, group) => ...`. Each action is a `CometChatMessageComposerAction` (a type, not a class: `id`, `title`, `icon`, `onPress`, `CustomView`, `style` — `shared/helper/types/index.ts:17`, exported as a type at `src/index.ts:43`).
+
+Get the defaults to append to / filter from via `getAttachmentOptions(theme, user, group, composerId?, additionalParams?)` (`DataSource.ts:215`; impl `MessageDataSource.tsx:2123`):
 
 ```tsx
-<CometChatMessageComposer
-  user={user}
-  attachmentOptions={(user, group) => {
-    const defaults = /* default actions from ChatConfigurator */;
-    return defaults.filter((opt) => opt.id !== "attachment-file");
-  }}
-/>
+import { ChatConfigurator, useTheme } from "@cometchat/chat-uikit-react-native";
+import type { CometChatMessageComposerAction } from "@cometchat/chat-uikit-react-native";
+
+function Composer({ user, group }: any) {
+  const theme = useTheme();
+  return (
+    <CometChatMessageComposer
+      user={user}
+      group={group}
+      attachmentOptions={({ user, group, composerId }) => {
+        const defaults = ChatConfigurator.getDataSource().getAttachmentOptions(
+          theme, user, group, composerId,
+        );
+        const custom: CometChatMessageComposerAction = {
+          id: "send-location",
+          title: "Location",
+          onPress: (u, g) => sendLocation(u, g),
+        };
+        return [...defaults, custom];   // append; or .filter(...) to remove one
+      }}
+    />
+  );
+}
 ```
 
+To **disable** an option instead, return `defaults.filter((opt) => opt.id !== "...")`.
+
 ### "Show only message types that contain the word 'urgent'"
 **Tier 2** — `messageRequestBuilder` with `.setSearchKeyword("urgent")`.
 
@@ -548,7 +666,7 @@ const EMOJI_MAP: Record<string, string> = {
 class EmojiShortcodeFormatter extends CometChatTextFormatter {
   constructor() {
     super();
-    this.setRegexPatterns([/:[a-z_]+:/g]);
+    this.setRegexPatterns(/:[a-z_]+:/g);   // SINGLE RegExp, not an array
   }
 
   getFormattedText(input: string | null | React.ReactNode) {
@@ -592,3 +710,7 @@ import { TEXT_FORMATTERS } from "./formatters";
 | `cometchat-native-customization` | This skill — four-tier triage + custom formatters / templates / DataSource / events |
 | `cometchat-native-production` | When customization depends on production auth (token refresh, user-ID mapping) |
 | `cometchat-native-troubleshooting` | Formatter doesn't apply, listener fires twice, slot view renders nothing, template not showing |
+
+## Sound (in-app message + call sounds)
+
+Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-native-theming`** (Sound section). Verify the access path against the installed kit before relying on it.