@cometchat/skills 4.2.1 → 4.3.0

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

@@ -80,12 +80,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 +111,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 +265,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 +393,26 @@ 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 \
+  punycode
 ```
 
+> **Why `punycode`?** The kit's `CometChatAIAssistantMessageBubble` pulls in `markdown-it`, which does `require('punycode')`. Node 22+ removed `punycode` from core, so Metro can't resolve it without the userland package. Missing it = bundle 500 with `Unable to resolve module punycode`. (Validated 2026-05-26 on `@cometchat/chat-uikit-react-native@5.3.5` + Expo SDK 56 + RN 0.85.3.)
+
 > 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 four 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-background-timer \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 ```
 
+> The calls-sdk `dist/polyfills/browser.js` imports `react-native-background-timer`, `react-native-url-polyfill/auto`, and `react-native-performance` at module top; `valibot` is consumed deeper in the calls state machine. None are 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 three native modules get autolinked into the next debug build.
+
 See `cometchat-native-features` for when to add the calls SDK.
 
 ---
@@ -405,3 +431,180 @@ 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, settings: {...} }` — the store reads `config.settings.*` from it (F9 envelope finding, verified 2026-05-22 against the canonical Zustand store).
+
+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: ..., settings: { chatFeatures: ..., callFeatures: ..., theme: ..., agent: ... } }`. Settings come from `GET /vcb/builders/{id}`; missing fields (`inAppSounds`, `mentionAll`) defaulted by the CLI. **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 four-wrapper chain with `<CometChatThemeProvider theme={builderTheme}>` derived from `useConfig`. Template below. |
+| `index.js` (bare) or app entry (Expo Router managed) | `import 'react-native-gesture-handler';` on line 1 (this skill's four-wrapper rule — non-negotiable, applies to every RN integration regardless of customization mode). |
+| `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'; // bare RN: line 1, before any other import
+import React, { useEffect, useState } from 'react';
+import { Platform } from 'react-native';
+import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';
+import { GestureHandlerRootView } from 'react-native-gesture-handler';
+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(() => {
+    const settings = new UIKitSettings.UIKitSettingsBuilder()
+      .setAppId(process.env.EXPO_PUBLIC_COMETCHAT_APP_ID!)
+      .setRegion(process.env.EXPO_PUBLIC_COMETCHAT_REGION!)
+      .setAuthKey(process.env.EXPO_PUBLIC_COMETCHAT_AUTH_KEY!)
+      .subscribePresenceForAllUsers()
+      .build();
+    CometChatUIKit.init(settings).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 (
+    <GestureHandlerRootView style={{ flex: 1 }}>
+      <SafeAreaProvider>
+        <SafeAreaView edges={['top', 'bottom']} style={{ flex: 1 }}>
+          <CometChatThemeProvider theme={theme}>
+            <CometChatI18nProvider>
+              <RootStackNavigator />
+            </CometChatI18nProvider>
+          </CometChatThemeProvider>
+        </SafeAreaView>
+      </SafeAreaProvider>
+    </GestureHandlerRootView>
+  );
+}
+```
+
+**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 four-wrapper rule still applies: `GestureHandlerRootView → SafeAreaProvider → CometChatThemeProvider → CometChatI18nProvider`. Skipping any of the four 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.deeperEngagement.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
+
+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-expo-patterns/SKILL.md

@@ -90,7 +90,10 @@ npm install dayjs punycode
 If the user's flow includes voice / video calls (the `cometchat-native-features` skill's § Calls gates this):
 
 ```bash
-npm install @cometchat/calls-sdk-react-native
+npm install @cometchat/calls-sdk-react-native \
+  react-native-url-polyfill \
+  react-native-performance \
+  valibot
 npx expo install \
   @react-native-community/netinfo \
   react-native-background-timer \
@@ -98,6 +101,8 @@ npx expo install \
   react-native-webrtc
 ```
 
+> **`react-native-url-polyfill`, `react-native-performance`, and `valibot` are not in the calls-sdk `peerDependencies` array** — but the calls-sdk's `dist/polyfills/browser.js` imports them at module top, so Metro fails the bundle without them. Omitting any of the three yields `Unable to resolve module …` at startup with no app render. (Validated 2026-05-26 on `@cometchat/calls-sdk-react-native@5.0.0` + Expo SDK 56.)
+
 Skip these until the user actually wants calls. Adding WebRTC to an Expo project bloats the prebuild and requires extra permissions — don't speculatively enable it.
 
 ---
@@ -500,3 +505,17 @@ Push notifications need additional setup (APNs + FCM + maybe `expo-notifications
 | `cometchat-native-customization` | Text formatters, events, custom views |
 | `cometchat-native-production` | Server-side auth tokens + user management |
 | `cometchat-native-troubleshooting` | Prebuild failures, Expo Go errors, keyboard issues, blank chat |
+
+## Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the Expo recipe diverges from the standard provider chain. Skills runs `cometchat builder export --platform react-native --json` to emit `src/config/{store.ts, config.json}` (the Zustand-backed config store + 7-field envelope JSON), then patches `App.tsx` with `useConfig` + theme derivation.
+
+**Full recipe lives in `cometchat-native-core` §"Visual Builder integration".** Expo-specific notes:
+
+- Use `npx expo install` for the deps (not raw `npm install`) — Expo SDK pins compatible versions.
+- Env via `process.env.EXPO_PUBLIC_COMETCHAT_*` (no extra Babel plugin needed; Expo handles this).
+- Required additional deps beyond the standard provider set: `zustand`, `@react-native-async-storage/async-storage`.
+- `useConfig(s => s.settings.style)` — note the selector takes `AppConfig` directly, NOT `s.config.settings.style` (the `.config.` wrapper is internal to the Zustand store — Finding F6, 2026-05-21).
+- A2 smoke validated: Metro bundles 10.8 MB iOS export clean on Expo SDK 54.
+
+If the customer picks **In code**, ignore this section — the standard four-wrapper chain + provider pattern from §"Provider chain" applies.

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

@@ -207,63 +207,86 @@ android {
 }
 ```
 
-### 3d — Register the call listener at app root
+### 3d — Register the call listeners at app root (incoming + outgoing + ongoing)
 
-The incoming-call UI only shows up if you've registered a listener to pick up call events. Add this once at the app root (typically in `App.tsx` or Expo Router's `_layout.tsx`):
+All three call surfaces — `<CometChatIncomingCall>`, `<CometChatOutgoingCall>`, `<CometChatOngoingCall>` — are parent-controlled. None auto-mount the others. The parent must register **both** `CometChat.addCallListener` (SDK socket; surfaces incoming calls from the network) **and** `CometChatUIEventHandler.addCallListener` (UI event bus; surfaces outgoing calls fired by `<CometChatCallButtons>` / `<CometChatMessageHeader>`). Add this once at the app root (typically in `App.tsx` or Expo Router's `_layout.tsx`). Validated 2026-05-26 against `@cometchat/chat-uikit-react-native@5.3.5` end-to-end on Pixel 3 ([[project_v4_3_f75_rn_call_ui_missing]]).
 
 ```tsx
-import React, { useEffect, useRef, useState } from "react";
+import React, { useEffect, useState } from "react";
+import { StyleSheet, View } from "react-native";
 import { CometChat } from "@cometchat/chat-sdk-react-native";
-import { CometChatIncomingCall } from "@cometchat/chat-uikit-react-native";
+import {
+  CometChatIncomingCall,
+  CometChatOutgoingCall,
+  CometChatOngoingCall,
+  CometChatUIEventHandler,
+} from "@cometchat/chat-uikit-react-native";
+
+const CALL_LISTENER_ID = "APP_CALL_LISTENER";
 
 function CallEventsProvider({ children }: { children: React.ReactNode }) {
-  const [callReceived, setCallReceived] = useState(false);
-  const incomingCall = useRef<CometChat.Call | null>(null);
-  const LISTENER_ID = "APP_CALL_LISTENER";
+  const [incomingCall, setIncomingCall] = useState<CometChat.Call | null>(null);
+  const [outgoingCall, setOutgoingCall] = useState<CometChat.Call | null>(null);
+  const [ongoingCall, setOngoingCall] = useState<CometChat.Call | null>(null);
 
   useEffect(() => {
+    // SDK socket — incoming side
     CometChat.addCallListener(
-      LISTENER_ID,
+      CALL_LISTENER_ID,
       new CometChat.CallListener({
-        onIncomingCallReceived: (call) => {
-          incomingCall.current = call;
-          setCallReceived(true);
-        },
-        onOutgoingCallAccepted: (call) => {
-          // navigate to the ongoing-call screen
-        },
-        onOutgoingCallRejected: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
-        onIncomingCallCancelled: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
-        onCallEndedMessageReceived: () => {
-          incomingCall.current = null;
-          setCallReceived(false);
-        },
+        onIncomingCallReceived: (call: CometChat.Call) => setIncomingCall(call),
+        onIncomingCallCancelled: () => setIncomingCall(null),
+        onOutgoingCallAccepted: () => {},   // kit owns the transition
+        onOutgoingCallRejected: () => setOutgoingCall(null),
       })
     );
-    return () => CometChat.removeCallListener(LISTENER_ID);
+    // UI event bus — outgoing side (fired by CallButtons / MessageHeader)
+    CometChatUIEventHandler.addCallListener(CALL_LISTENER_ID, {
+      ccOutgoingCall: ({ call }) => setOutgoingCall(call),
+      ccCallEnded: () => {
+        setOutgoingCall(null);
+        setIncomingCall(null);
+        setOngoingCall(null);
+      },
+      ccShowOngoingCall: ({ call }) => setOngoingCall(call),
+    });
+    return () => {
+      CometChat.removeCallListener(CALL_LISTENER_ID);
+      CometChatUIEventHandler.removeCallListener(CALL_LISTENER_ID);
+    };
   }, []);
 
   return (
     <>
       {children}
-      {callReceived && incomingCall.current && (
-        <CometChatIncomingCall
-          call={incomingCall.current}
-          onAccept={() => { /* navigate to ongoing-call screen */ }}
-          onDecline={() => setCallReceived(false)}
-        />
+      {incomingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          <CometChatIncomingCall
+            call={incomingCall}
+            onDecline={() => setIncomingCall(null)}
+            onError={() => setIncomingCall(null)}
+          />
+        </View>
+      )}
+      {outgoingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          <CometChatOutgoingCall call={outgoingCall} />
+        </View>
+      )}
+      {ongoingCall && (
+        <View style={StyleSheet.absoluteFill}>
+          <CometChatOngoingCall call={ongoingCall} />
+        </View>
       )}
     </>
   );
 }
 ```
 
+> **DO NOT pass `onAccept` to `<CometChatIncomingCall>`** — short-circuits the kit's internal `acceptCall` + OngoingCall transition. The kit fires `ccShowOngoingCall` after `acceptCall` resolves; the listener above wires that into `setOngoingCall`, which mounts `<CometChatOngoingCall>`. Handle only `onDecline` + `onError` here. See `cometchat-native-calls` §1.8.c.
+
+> **DO NOT skip `CometChatUIEventHandler.addCallListener`.** Without it, tapping video/voice on `<CometChatMessageHeader>` fires WebRTC + camera at the native layer but no overlay UI ever mounts — the user sees nothing change after the tap. This was [[project_v4_3_f75_rn_call_ui_missing]] (F75).
+
 Wrap the app (inside the existing provider chain, below `CometChatProvider`):
 
 ```tsx

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

@@ -286,6 +286,68 @@ After updating:
 2. Rebuild the archive
 3. Resubmit
 
+### 3bb. `react-native-document-picker` build failure on RN 0.85+ (F70)
+
+**Symptom:** Android debug build fails with a hard Java compile error inside `react-native-document-picker`'s source — typically `cannot find symbol class GuardedResultAsyncTask`.
+
+**Root cause:** `react-native-document-picker` references `GuardedResultAsyncTask`, which React Native removed from its Android internals in 0.85. The package is unmaintained — the last useful release predates RN 0.85.
+
+**Fix:** uninstall it and switch to a maintained alternative if document picking is needed.
+
+```bash
+# Uninstall the broken package
+npm uninstall react-native-document-picker
+
+# For Expo apps — official maintained pick
+npx expo install expo-document-picker
+
+# For bare RN — maintained community fork
+npm install @react-native-documents/picker
+```
+
+`cometchat verify` flags this combination automatically (`rn_doc_picker_compat` check) — runs as part of every verify since v4.3.0.
+
+### 3bc. `Cannot read property 'CometChatThemeProvider' of undefined` on bare RN (F78 — chat-sdk 4.0.22 packaging regression)
+
+**Symptom (bare RN only):** the app builds cleanly (`BUILD SUCCESSFUL`) but crashes at JS startup with `TypeError: Cannot read property 'CometChatThemeProvider' of undefined`. The error often links to RN's own AsyncStorage troubleshooting text ("Make sure your project's `package.json` depends on `@react-native-async-storage/async-storage`…").
+
+**This is NOT the §3b Maven-repo build failure** — that one fails the Gradle build. F78 builds fine, then crashes at runtime.
+
+**Root cause (confirmed):** `@cometchat/chat-sdk-react-native` **4.0.22** declares `react`, `react-native@0.64.2`, and `@react-native-async-storage/async-storage@^1.13.4` as **hard `dependencies`** (4.0.21 had none). npm therefore installs **nested duplicate copies inside the SDK**:
+
+```
+node_modules/@cometchat/chat-sdk-react-native/node_modules/
+  ├── react-native/               → 0.64.2   (duplicate of your app's 0.85.x)
+  └── @react-native-async-storage/async-storage/  → 1.24.0
+```
+
+Two react-native copies = two native-module registries. The SDK's persistence code resolves AsyncStorage against its nested 1.24.0 copy, whose native module isn't the one your app autolinked → `RCTAsyncStorage` not found → the kit's `theme` module throws during evaluation → `CometChatThemeProvider` ends up `undefined`. **Expo is unaffected** because its resolver dedupes react-native to a single copy; bare RN installs the nested copy.
+
+Confirm you're hit by it:
+```bash
+ls node_modules/@cometchat/chat-sdk-react-native/node_modules/react-native/package.json && echo "F78: nested RN present"
+```
+
+**Fix — pick one (both verified to remove the nested install):**
+
+1. **npm `overrides`** (keep chat-sdk 4.0.22) — add to the app's `package.json`, then reinstall:
+   ```jsonc
+   "overrides": {
+     "@cometchat/chat-sdk-react-native": {
+       "react": "$react",
+       "react-native": "$react-native",
+       "@react-native-async-storage/async-storage": "$@react-native-async-storage/async-storage"
+     }
+   }
+   ```
+   yarn uses the equivalent top-level `resolutions`.
+2. **Pin the known-good SDK:** `npm i @cometchat/chat-sdk-react-native@4.0.21` (zero deps → no nesting).
+3. **Prefer Expo** for greenfield — the Expo cohort is fresh-validated and never hits this.
+
+After applying (1) or (2): `rm -rf node_modules && npm install`, then verify the nested `react-native` is gone with the `ls` check above. Tried and confirmed **NOT** to fix it: downgrading async-storage, `newArchEnabled=false`, clean rebuild, Metro `--reset-cache` — none address the duplicate-RN root cause.
+
+The permanent fix is SDK-side (move react/react-native to `peerDependencies`) — tracked in **ENG-35653**.
+
 ### 3c. Metro cache issues (post-dep-install "not found" errors)
 
 Happens when you `npm install` a native module and Metro's bundler still has the old module graph cached.

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

@@ -855,3 +855,31 @@ If the project has a custom `pages/_document.tsx` for font preloading or third-p
 6. Create `pages/messages.tsx` with dynamic import (section 6)
 7. Add a `<Link href="/messages">Messages</Link>` to the layout's nav
 8. Verify: `npm run build` should succeed without SSR errors
+
+## 14. Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the Next.js recipe diverges based on App Router vs Pages Router. Skills runs `cometchat builder export --platform react --output <target>` to download the canonical `src/CometChat/` + patch settings in one step.
+
+**Full recipe lives in `cometchat-core` §11 "Visual Builder integration".** This section is a pointer + Next.js-specific gotchas:
+
+### App Router (recommended for Visual Builder)
+
+- Run `cometchat builder export --platform react --output src/app/CometChat --json`.
+- Create `src/app/CometChatNoSSR/CometChatNoSSR.tsx` (client component, init + login + render).
+- Create `src/app/CometChatAppWrapper.tsx` with `"use client"` + `dynamic(() => import("../app/CometChatNoSSR/CometChatNoSSR"), { ssr: false })`.
+- Import the wrapper in `src/app/page.tsx`.
+- **Patch `src/app/CometChat/context/CometChatContext.tsx`** to use `'../../../../package.json'` (4 levels up) instead of canonical's `'../../../package.json'` (3 levels). **Finding F16** — depth differs because the directory moved into `src/app/`.
+
+### Pages Router (NOT recommended)
+
+**Finding F17** (2026-05-22): Next.js Pages Router enforces "global CSS imports only in `pages/_app.tsx`". The canonical `src/CometChat/` has 25+ component-level CSS imports — Pages Router rejects the build. App Router tolerates this; Pages Router does not. Recommend App Router instead.
+
+If a customer insists on Pages Router + Visual Builder, the only workaround is to convert all 25+ canonical CSS files into CSS Modules — heavy customer-side work. Not validated in v4.3.0.
+
+### Both routers
+
+- Use `process.env.NEXT_PUBLIC_COMETCHAT_*` (NOT `import.meta.env.*` which is Vite-only).
+- Pin `@cometchat/chat-uikit-react@6.4.3` + `@cometchat/calls-sdk-javascript@4.2.5`.
+- `package.json` needs `cometChatCustomConfig` block (Finding F2).
+
+If the customer picks **In code**, ignore this section.

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

@@ -573,3 +573,16 @@ When integrating CometChat into a React (Vite/CRA) project, follow these steps i
 9. Add a "Messages" link to the existing nav
 
 **Do not skip step 6.** The provider must wrap the app root so init happens once, regardless of which route or modal opens chat.
+
+## 9. Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, the React-on-Vite/CRA recipe diverges from the code-driven path described above. Instead of authoring a `CometChatProvider`, skills runs `cometchat builder export --platform react --json` to download the canonical `src/CometChat/` directory + patch `CometChatSettings.ts` with the customer's per-builder configuration. Then patches `src/main.tsx` (Vite) or `src/index.tsx` (CRA) to mount `<CometChatApp />`.
+
+**Full recipe lives in `cometchat-core` §11 "Visual Builder integration".** This section is a pointer + Vite/CRA-specific gotchas:
+
+- **`cometchat builder export --platform react`** is the single command — replaces the v4.2 era "fetch JSON + manually copy" pattern. Defaults to `--output src/CometChat`. Resync = same command with `--force`. See `cometchat-core` §11.1.
+- **Vite 7+ tsconfig is auto-relaxed by `cometchat apply`** (Finding F35, 2026-05-22) — `verbatimModuleSyntax`, `noUnusedLocals`, `noUnusedParameters`, `erasableSyntaxOnly` all set to `false`. CRA's defaults are already permissive — no change needed for CRA. For Visually path, also set `resolveJsonModule: true` + `allowJs: true` per cometchat-core §11.2.
+- **`package.json` needs `cometChatCustomConfig`** block (Finding F2). The canonical context reads `packageJson.cometChatCustomConfig.{name, version, production}`.
+- **Pinned versions**: `@cometchat/chat-uikit-react@6.4.3` + `@cometchat/calls-sdk-javascript@4.2.5` (per the canonical README; newer versions may drift from the copied CometChat/ API surface).
+
+If the customer picks **In code**, ignore this section — sections 1-8 above are the path. (`cometchat apply` auto-patches tsconfig for both paths per F35.)

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

@@ -257,6 +257,8 @@ This works because `useNavigate` returns a stable function that CometChat's call
 
 React Router v7 in framework mode is a full meta-framework with SSR, file-system routing, loaders, and actions. It has the same SSR concerns as Next.js: CometChat components cannot run on the server.
 
+> **Visual Builder support on RR v7**: as of v4.3.0 (F19 fix), `cometchat builder export --platform react` post-extract codemod patches the canonical's type-as-value imports so Rolldown (Vite 7+ / RR v7's bundler) builds clean. Previously this combo failed with `[MISSING_EXPORT] "CometChatSettingsInterface" is not exported`. The patched canonical drops into `app/CometChat/` and builds in <1s (691ms client + 59ms server). No additional config required.
+
 ### SSR prevention
 
 v7 renders components on the server by default. CometChat components will crash during server rendering. Use a `ClientOnly` wrapper:
@@ -717,3 +719,34 @@ Do not mix v6 and v7 patterns. Detect the mode (section 1) and use the correct p
 8. Create `app/routes/messages.tsx` with `ClientOnly` + lazy import (section 3)
 9. Add a "Messages" link to the layout's nav
 10. Verify: loaders/actions contain NO CometChat imports
+
+## 10. Visual Builder integration (v4.3)
+
+If the customer picks **Visually** in dispatcher Step 3.1, skills runs `cometchat builder export --platform react --output <target>` to download the canonical `src/CometChat/` + patch settings in one step.
+
+**Full recipe lives in `cometchat-core` §11 "Visual Builder integration".** This section is a pointer + React Router-specific gotchas:
+
+### Framework mode (v7 default)
+
+- Run `cometchat builder export --platform react --output app/CometChat --json`.
+- Create the chat route as `app/routes/chat.client.tsx` — the `.client.tsx` suffix skips SSR for this file.
+- Register the route in `app/routes.ts` via `route("chat", "routes/chat.client.tsx")`.
+
+### Data mode (library, v6/v7)
+
+- Run `cometchat builder export --platform react --output src/CometChat --json` (default).
+- Same Vite-based init pattern as plain Vite + React (see `cometchat-react-patterns` §9).
+
+### ✓ Rolldown handled (Finding F19, fixed in v4.3.0)
+
+React Router v7's Vite 7+ build uses **Rolldown**, which rejects the canonical CometChat/'s type-as-value imports (e.g. `import { CometChatSettingsInterface } from "../context/CometChatContext"` used in type-only positions) with `[MISSING_EXPORT] "CometChatSettingsInterface" is not exported`. Webpack-based bundlers (CRA, Next.js classic) and rollup (Astro, older Vite) tolerate it as a warning.
+
+**This is fixed in v4.3.0.** After `cometchat builder export --platform react`, the CLI runs a post-extract codemod (`applyReactRolldownFix`) that rewrites the affected imports with the inline `type` modifier so Rolldown builds clean (verified <1s: 691ms client + 59ms server). No customer action or config required — RR v7 + Visual Builder builds out of the box.
+
+### Both modes
+
+- Pin `@cometchat/chat-uikit-react@6.4.3` + `@cometchat/calls-sdk-javascript@4.2.5`.
+- `package.json` needs `cometChatCustomConfig` block (Finding F2).
+- Vite 7+ `tsconfig.app.json` requires the relaxation set from `cometchat-core` §11.2.
+
+If the customer picks **In code**, ignore this section.