@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-react-v7-migration/references/migration-guide.md

@@ -0,0 +1,119 @@
+# migration-guide — CometChat React UI Kit v6 → v7 (BAKED breaking-change map)
+
+Distilled from the official migration docs (`ui-kit/react/migration-overview` + `migration-property-changes`) and a real **v6.5.4 → v7.1.0** export diff. Bake this map; **fetch the exhaustive prop-by-prop table** from `migration-property-changes` (docs-map) for anything not covered here. v6 names appear in tables/prose (they no longer exist in v7); v7 code is the target.
+
+## 0. What actually changed
+v7 is a rewrite that keeps **init/login and most component props compatible**, but replaces global singletons with React-native patterns. Five real breaks: (1) deps (incl. Calls SDK v4→v5 and the dropped `./css-variables.css` export), (2) RxJS events → a hook, (3) `DataSource`/`ChatConfigurator` → plugins, (4) `CometChatMessageTemplate`/`templates` props → plugins (**`textFormatters` is NOT removed** — it just relocated off `CometChatMessageList` to the composer/bubbles), (5) a handful of symbol renames (incl. `CometChatUIKit.getLoggedinUser()` async → `getLoggedInUser()` sync). Plus: wrap in `CometChatProvider`, `theme` prop, calling on via `uiKit:{callsSDK:{}}` (initFromSettings) / classic `.setCallingEnabled(true)`.
+
+## 1. Dependencies
+```bash
+npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.13 dompurify@^3.3.1
+npm uninstall rxjs   # v7 drops the rxjs dependency
+```
+| Package | v6 | v7 |
+|---|---|---|
+| `@cometchat/chat-uikit-react` | `^6.x` | `^7.0.0` |
+| `@cometchat/chat-sdk-javascript` | `^4.x` | `^4.1.13` (peer) |
+| `react` | `>=18` | `>=18 <21` |
+| `dompurify` | — | **`^3.3.1` — v7 needs it** (the kit imports it at runtime). It's in the kit's `dependencies`, but **install it explicitly** (the official docs do) — transitive-only resolution breaks in strict/pnpm/bundler setups. |
+| `@cometchat/calls-sdk-javascript` (if calling) | `^4.x` | **`^5.x`** — bump the major (`npm install @cometchat/calls-sdk-javascript@5`); v7 pins `^5.x` (verified). NOT the same major as v6-era, so it is NOT "unchanged". |
+| `rxjs` | required | **removed** |
+| **CSS import** | `import "@cometchat/chat-uikit-react/css-variables.css"` | **that export is GONE in v7** — use `import "@cometchat/chat-uikit-react/styles"` (the only CSS export; package `exports` = `.` + `./styles`). A leftover `css-variables.css` import fails to resolve. See `cometchat-react-v7-core/references/theming.md`. |
+
+## 2. Symbol removals / renames (v6 → v7) — verified vs a real v6.5.4 → v7.1.0 EXPORT diff
+> **Init class is `CometChatUIKit` in BOTH v6 and v7 — no casing change.** `CometChatMessageComposer` and `CometChatMessageList` etc. keep the same names. Below are the ACTUAL removed/renamed public exports.
+
+| v6 symbol | v7 | Action |
+|---|---|---|
+| `CometChatDocumentBubble` | — (removed) | **REMOVED.** Not a rename: v6 shipped `CometChatDocumentBubble` AND `CometChatFileBubble` side by side; v7 keeps `CometChatFileBubble` (unchanged) and drops `CometChatDocumentBubble`. |
+| `CometChatCompactMessageComposer` | `CometChatMessageComposer layout="compact"` | removed as a component (→ the composer's `layout` prop) |
+| `CometChatMessageTemplate` | plugin `renderBubble()` (see §4) | removed |
+| `CometChatMessageEvents`, `CometChatGroupEvents`, `CometChatCallEvents`, `CometChatUserEvents`, `CometChatConversationEvents`, `CometChatUIEvents` | `useCometChatEvents` / `usePublishEvent` (see §3) | removed (RxJS) |
+| `CometChatUIKitLoginListener` | removed (init/login is imperative; gate on `getLoggedInUser()`) | removed |
+| `CometChatUIKit.getLoggedinUser()` (async, lowercase "in") | `CometChatUIKit.getLoggedInUser()` (**capital "In", SYNCHRONOUS**, returns `CometChat.User \| null`) | **RENAMED + return-type change.** v6's `getLoggedinUser()` returned a `Promise`; v7's `getLoggedInUser()` is sync — drop the `await`/`.then()` and read the return value directly. (The Chat SDK still has the async `CometChat.getLoggedinUser()`; the UIKit wrapper is the one that changed.) |
+| `CometChatEmojiKeyboard`, `CometChatMediaRecorder` | built into `CometChatMessageComposer` | removed |
+| `CometChatToast`, `CometChatListItem`, `CometChatNotificationBadge` | internal to their host components | removed |
+| `CometChatUrlsFormatter` | `CometChatUrlFormatter` | rename (plural→singular; `id="url-formatter"`) |
+| `CometChatTextHighlightFormatter` | — (removed) | **REMOVED** (no direct replacement). v7 formatter set: `CometChatTextFormatter` · `CometChatMentionsFormatter` · `CometChatUrlFormatter` · `CometChatMarkdownFormatter` · `CometChatRichTextFormatter`. |
+| monolithic prop bags | composable **slot props** (`*RootProps`/`*HeaderProps`/`*ItemProps`) | additive — flat props still work |
+
+> The message list's DEFAULT bubble routing moved to the multi-attachment bubbles: `CometChatImageBubble`→`CometChatImagesBubble`, `CometChatVideoBubble`→`CometChatVideosBubble`, `CometChatFileBubble`→`CometChatFilesBubble`, `CometChatAudioBubble`→`CometChatAudiosBubble`/`CometChatVoiceNoteBubble`. The singular bubbles still ship for standalone use — only the list's routing changed.
+
+## 3. RxJS events → the unified event hook
+v6 exposed per-domain RxJS Subjects; v7 merges SDK + UI events into one bus.
+```diff
+- import { CometChatMessageEvents } from "@cometchat/chat-uikit-react";
+- CometChatMessageEvents.ccMessageSent.subscribe((data) => { /* … */ });
+```
+```tsx
+import { useCometChatEvents } from "@cometchat/chat-uikit-react";
+useCometChatEvents((event) => {
+  if (event.type === "ui:message/sent") { /* … */ }
+}, []); // 2nd arg (React.DependencyList) is REQUIRED
+// publish: const publish = usePublishEvent(); publish({ /* … */ });
+```
+
+## 4. DataSource / ChatConfigurator → plugins
+```diff
+- class MyDecorator extends DataSourceDecorator { getTextMessageBubble() { /* … */ } }
+- ChatConfigurator.enable(new MyDecorator());
+```
+```tsx
+const MyPlugin: CometChatMessagePlugin = {
+  id: "my-plugin",
+  messageTypes: ["custom-type"],
+  messageCategories: ["custom"],
+  renderBubble(message, context) { return <MyBubble message={message} />; },
+  getOptions(message, context) { return []; },
+  getLastMessagePreview(message, loggedInUser, t) { return "Preview text"; }, // optional; (message, loggedInUser, t?)
+};
+<CometChatProvider plugins={[MyPlugin]}><div>{/* your chat UI */}</div></CometChatProvider>   // `children` is REQUIRED
+```
+The `templates` prop is removed → move custom message rendering to a plugin. **`textFormatters` is NOT removed** (verified vs 7.1.0): it's still a prop on `CometChatMessageComposer`, the bubble components, `CometChatSearch` and `CometChatMessageInformation` — but NOT on `CometChatMessageList`/`CometChatConversations`. The list's text bubbles are rendered by the text plugin, which reads its own `getTextFormatters()` (default: markdown + mentions + URL), so a v6 list-level formatter moves to an override of that one method:
+```tsx
+import { CometChatProvider, CometChatTextPlugin, CometChatMarkdownFormatter, CometChatMentionsFormatter, CometChatUrlFormatter } from "@cometchat/chat-uikit-react";
+// HashtagFormatter = the app's own CometChatTextFormatter subclass (the migrated v6 formatter)
+const textPlugin = { ...CometChatTextPlugin, getTextFormatters: () => [new CometChatMarkdownFormatter(), new CometChatMentionsFormatter(), new CometChatUrlFormatter(), new HashtagFormatter()] };
+<CometChatProvider plugins={[textPlugin]}><div>{/* your chat UI */}</div></CometChatProvider>;   // provider plugins precede defaultPlugins → this wins
+```
+Full plugin API: fetch `plugins/overview` (docs-map).
+
+## 5. Component prop changes (the common ones — exhaustive table = fetch `migration-property-changes`)
+| Pattern | v6 | v7 |
+|---|---|---|
+| View prop type | `JSX.Element` | `ReactNode` (compatible) |
+| Date format type | `CalendarObject` | `CometChatDateFormatConfig` (same shape) |
+| Error UI | `hideError` prop (removed from lists; **retained on `CometChatMessageComposer`**) | `errorView` prop (pass custom error UI) |
+| Loading UI | `disableLoadingState` prop | `loadingView` prop (pass custom loading UI) |
+| Message templates | `templates` prop | plugins (§4) |
+| Text formatters on LIST components | `textFormatters` prop (message list / conversations) | no list prop — override the text plugin's `getTextFormatters()` (§4); the `textFormatters` PROP remains on the composer, bubbles, `CometChatSearch`, `CometChatMessageInformation` |
+| Bubbles | presentational (`src`/`text`/`isSentByMe` required) | self-extracting — pass `message`; overrides optional |
+
+## 6. Provider, theming, calling (minor)
+- **Provider (required):** wrap the chat tree in `CometChatProvider` (init/login stay imperative + unchanged from v6).
+- **Theming:** same CSS variables; `data-theme="dark"` attribute → `theme="dark"` prop on `CometChatProvider` (or the `useTheme()` hook).
+- **Calling:** enable in the init settings — `uiKit: { callsSDK: {} }` passed to `CometChatUIKit.initFromSettings` (the classic `new UIKitSettingsBuilder()…setCallingEnabled(true).build()` + `init()` still works but skips the ai-agent telemetry path). Not a provider prop. Without it, call UI hides + the Calls SDK doesn't load.
+- **Localization:** v7 localizes via `CometChatProvider` (auto `LocaleProvider`); switch language with its `locale` prop (`<CometChatProvider locale="fr">`). `init` / `setCurrentLanguage` / `addTranslation` are **INSTANCE** methods on `CometChatLocalize`, NOT statics — reach the live instance with `CometChatLocalize.getSharedInstance()` (e.g. `CometChatLocalize.getSharedInstance()?.addTranslation({ "en-us": { … } })`, **nested per-language** `Record<lang, Record<key,string>>`; other config via `getSharedInstance()?.init({ translationsForLanguage, timezone, calendarObject, … })`). **Don't `new CometChatLocalize(...)`** — the provider reads only the shared instance (registered by `CometChatUIKit.init*` / the provider), so a constructed one isn't wired to the UI; and the `locale` prop (default `"en-us"`) is applied on mount/change, overriding an earlier `init({ language })`. Read strings via the `useLocale()` hook. **Some KEYS changed v6→v7** — a stale v6 key falls through to the raw string (`getLocalizedString` returns the key on a miss), so a snake_case token like `group_info` in the UI = a missing key. Re-verify any custom translation keys against v7; never render a key literally.
+
+## 7. Localization migration (the `sample_` raw-key trap) — EDIT the app
+**Symptom:** the UI renders raw keys like `group_info`, `add_members`, `delete_chat`, `view_members`, `banned_members` (snake_case) instead of "Group Info" etc. **Cause:** v7 **namespaced the sample-app strings under a `sample_` prefix**, so the v6 unprefixed keys now MISS and `getLocalizedString` returns the raw key.
+
+**Fix the client's app (this skill edits it):**
+1. Find every localization key the app uses — `getLocalizedString("<key>")`, custom panel/button/tab labels, any hardcoded `sample_*`/unprefixed key.
+2. **Look up the EXACT v7 key — never guess.** The kit ships them in its source: `@cometchat/chat-uikit-react` → `src/resources/CometChatLocalize/resources/<lang>/translation.json` (en-us default), also the public GitHub repo + the localization docs `.md`. The sample-app strings are prefixed **`sample_`** — ~77 of them (`sample_group_info` = "Group Info", `sample_add_members`, `sample_delete_chat`, `sample_view_members`, `sample_banned_members`, `sample_delete_and_exit`, `sample_delete_chat_confirm`, `sample_delete_exit_confirm`, `sample_add_1_member`/`sample_add_n_members`, `sample_create_group`, `sample_block_contact`, …).
+3. **Two strategies (prefer A — keeps it bundled):**
+   - **A — map to the bundled `sample_` key:** `getLocalizedString("group_info")` → `getLocalizedString("sample_group_info")`. Resolves from the kit's built-in translations; no registration.
+   - **B — keep the app's key + register the value** (only if the key isn't in the kit): `addTranslation` is an INSTANCE method — `CometChatLocalize.getSharedInstance()?.addTranslation({ "en-us": { group_info: "Group Info", add_members: "Add Members" /* … */ } })` (nested per-language), once at startup after the provider mounts.
+4. **Migrate the init to the v7 method:** `CometChatProvider` auto-localizes (default en-us); switch language with its `locale` prop (`<CometChatProvider locale="fr">`). `init` / `setCurrentLanguage` are INSTANCE methods (`CometChatLocalize.getSharedInstance()?.setCurrentLanguage(lang)`), NOT statics. Drop any obsolete v6 localization init.
+5. **Verify:** build/typecheck passes and no snake_case token renders as a label when you open the app.
+
+## Removed concepts → replacement
+| v6 | v7 |
+|---|---|
+| `DataSource` / `DataSourceDecorator` | `CometChatMessagePlugin` |
+| `ChatConfigurator.enable()` | `plugins` prop on `CometChatProvider` |
+| `*Events` (RxJS) | `useCometChatEvents` / `usePublishEvent` |
+| `CometChatMessageTemplate` | plugin `renderBubble()` |
+| `*Configuration` objects | direct props on compound sub-components |
+
+> For anything not listed, fetch the prop-by-prop reference: `migration-property-changes` and `migration-overview` (via `cometchat-react-v7-core/references/docs-map.md`). Do NOT guess a v6→v7 mapping — verify against the docs.

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

@@ -0,0 +1,43 @@
+---
+name: cometchat-react-v7-patterns
+description: "Framework wiring for the React v7 UI Kit across Vite, Create React App, Next.js, React Router (incl. Remix), and Astro — provider placement, env vars, routing, SSR/islands and build pitfalls. Triggers: 'cometchat with vite', 'cometchat in next.js', 'cometchat in react router', 'cometchat in remix', 'cometchat in astro', 'env vars not working', 'cometchat provider setup', 'SSR window is not defined'."
+license: "MIT"
+compatibility: "React >=18; Vite >=4 / CRA / Next.js >=13 / react-router(-dom) ^6–7 / Astro >=3 (@astrojs/react); @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react patterns vite nextjs cra react-router remix astro provider env ssr v7"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Framework mechanics (env prefixes, SSR) are baked framework knowledge; kit symbols come from `cometchat-react-v7-core`. Status: **catalog-verified vs installed 7.1.0 (exports-only web-v7.json).**
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, provider, `init→login→render`. This skill ASSUMES it.
+
+## Use this skill when
+Wiring the UI Kit into a specific React toolchain, or debugging env/routing/SSR issues.
+
+## Prerequisites & install
+Covered by core. No new package.
+
+## Framework wiring (BAKED — the delta per toolchain; full recipe = fetch the docs integration page)
+- **Vite:** env in `.env` with `VITE_` prefix; read via `import.meta.env.VITE_COMETCHAT_*`. init/login in an app-startup effect; mount `CometChatProvider` above the chat routes. **Brownfield gotcha (AUDIT-037/066):** if the `vite/client` types aren't wired, `import.meta.env` is untyped → strict-TS build fails `TS2339: Property 'env' does not exist on ImportMeta`. Scaffolds wire `vite/client` differently by Vite version — older ones ship `src/vite-env.d.ts` (`/// <reference types="vite/client" />`), newer ones (Vite 8+) put `"vite/client"` in the `types` array of `tsconfig.app.json`. **Don't assume either is present — CHECK, then ensure `vite/client` is referenced:** add `/// <reference types="vite/client" />` at the top of the env-reading file (self-contained, works regardless of Vite version), or add `"vite/client"` to `tsconfig.app.json` `compilerOptions.types`, or create `src/vite-env.d.ts`.
+- **Create React App:** env with `REACT_APP_` prefix; read via `process.env.REACT_APP_*`.
+- **Next.js:** client-only kit — put init/login + `CometChatProvider` in a Client Component (`"use client"`); env in `.env.local` with `NEXT_PUBLIC_*`. Guard browser-only code so it never runs during SSR (App Router AND Pages Router).
+- **React Router / Remix:** two modes — **v6 library mode** (routing inside a Vite/CRA app, no SSR, `VITE_` env) wires like Vite; **v7 framework mode** (SSR, the Remix successor — a legacy `@remix-run/react` app maps here) has Next-like SSR concerns → render the chat client-only (client guard / `clientLoader` / a `<ClientOnly>`), `VITE_` env. Provider above the routed outlet.
+- **Astro:** the kit is a React **island** — mount it with `client:only="react"` (never SSR it); env with `PUBLIC_` prefix (`import.meta.env.PUBLIC_COMETCHAT_*`). One island owns init/login + provider + chat.
+- Keep `CometChatProvider` at a stable ancestor so init/login survive navigation (see `-placement`).
+> **Full per-framework recipe:** fetch the docs integration page via `cometchat-react-v7-core/references/docs-map.md` — `integration-react` · `integration-nextjs` · `integration-react-router` · `integration-astro` (+ the `next-*` / `react-router-*` / `astro-*` layout recipes). Bake only the deltas above; fetch the rest.
+
+## Framework pitfalls (BAKED)
+- **SSR frameworks (Next.js · React Router v7 framework mode · Astro):** `window is not defined` / hydration errors when the kit renders on the server → render the chat **client-only** (`"use client"` in Next; `client:only="react"` in Astro; a client guard / `clientLoader` in React Router v7) and defer init to `useEffect`/the browser.
+- **Astro:** using `client:load`/`client:visible` (they SSR the component first) instead of `client:only="react"` → server-render crash.
+- Wrong env prefix for the toolchain (Vite/React-Router `VITE_` · CRA `REACT_APP_` · Next `NEXT_PUBLIC_` · Astro `PUBLIC_`) → values are `undefined` at runtime.
+- Importing UI Kit CSS in multiple entry points (import once at root).
+- Auth key shipped to the client in production — use server-side token exchange (`RULES.md`).
+
+## Common pitfalls (BAKED)
+See above; also `version_conflict` STOP (v6 installed) per core.
+
+## Verify it works
+The app builds and chat renders on your framework (Vite / Next / React Router / Astro) with the correct env prefix and SSR guards (`"use client"` / `ssr:false` where needed).

package/skills/cometchat-react-v7-placement/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: cometchat-react-v7-placement
+description: "Where CometChat chat goes in a React app shell and how to wire each layout — full-screen, sidebar/split, popup/widget, or embedded in an existing page. Triggers: 'add chat as a sidebar', 'full screen chat page', 'chat popup widget', 'embed chat in my dashboard'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.1.0"
+  tags: "cometchat react placement layout uikit v7"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Uses only components defined in `cometchat-react-v7-core`/`-components` (from live v7 docs). Status: **catalog-verified vs installed 7.1.0 (exports-only web-v7.json).** Fetch layout-specific props from the component's **`.md` twin** (`../cometchat-react-v7-core/references/docs-map.md`).
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, `init→login→render`, provider. This skill ASSUMES it.
+- `cometchat-react-v7-components` — the component catalog this composes.
+
+## Use this skill when
+Deciding/​wiring WHERE chat lives — and either (a) **growing the core surface into the whole combined chat app** (selector tabs ↔ messages ↔ details/thread/search side panel + incoming call) when the user asks for the full app, or (b) a scoped-down sidebar/split, popup/floating widget, or embedded panel. Triggers: "build a full chat app", "add users/groups/calls tabs and a side panel", "add chat as a sidebar", "full screen chat page", "chat popup widget", "embed chat in my dashboard". Note: a plain unscoped "add chat" defaults to the production-ready CORE surface (list ↔ message pane) in `cometchat-react-v7-core` — grow to the combined app below only on request.
+
+## Prerequisites & install
+Covered by core. No new package.
+
+## Placement patterns (BAKED) — each composes core components
+- **Core surface (THE DEFAULT for an unscoped "add chat") — production-ready, but lean.** Inside `CometChatErrorBoundary` → ONE `CometChatProvider`, a **two-column** layout: a `CometChatConversations` LIST ↔ a MESSAGE pane (`CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer`), sized per `../cometchat-react-v7-core/references/layout.md`, with the **thread-replies panel** and the **in-chat scoped message search** wired by DEFAULT (opt-out only) and the global conversation search bar wired-or-hidden, collapsing to one pane on mobile. One small host state object coordinates {selected conversation, which side view (thread | in-chat-search | none)}. Complete and wired — NOT a bare demo — but NOT the whole app. See the "Core-surface recipe" below.
+- **Grow to the full combined app (on request) — the whole app the official sample ships.** When the user asks for the full app, grow the core surface into a **three-column** layout, all under `CometChatErrorBoundary` → ONE `CometChatProvider`: a SELECTOR column (the list for the active tab — `CometChatConversations` / `CometChatUsers` / `CometChatGroups` / `CometChatCallLogs` — + a tab bar), a MESSAGE pane, and a mutually-exclusive SIDE panel (user/group details, a thread `CometChatThreadHeader` + list/composer, or a scoped `CometChatSearch`), plus `CometChatIncomingCall` mounted at root. One host state object coordinates {active tab, selected user/group, thread parent, which side panel}. It is the UNION of the core surface + these growths — see the "Combined-app recipe (grow target)" below. Least-code = reach for these drop-ins (HOW).
+- **Sidebar / split:** conversations list in a fixed side panel; the message pane fills the rest. Selection state links list → message pane. (Scoped-down variant.)
+- **Popup / floating widget:** a toggle button mounts the chat panel in an overlay; keep `CometChatProvider` mounted at app root so init/login persist across open/close. (Scoped-down variant.)
+- **Embedded panel:** drop the message components into an existing page region; reuse the host layout/containers. (Scoped-down variant.)
+
+> Default to the CORE surface for a plain "add chat"; grow to the full combined app when the user asks for the whole app; honor an explicit smaller scope (the narrower three).
+
+
+## Recipes (FETCH — `references/recipes.md`)
+The two production recipes — full TSX + the 3-column CSS — live in `references/recipes.md` (progressive disclosure; load it when you build):
+- **Core-surface recipe** — THE DEFAULT for a plain "add chat": `CometChatErrorBoundary` → one `CometChatProvider` → two-column list ↔ message pane, thread panel + in-chat scoped search wired by default, mobile one-pane collapse.
+- **Combined-app recipe** — the GROW target (whole app, on request): three columns (selector tabs ↔ message pane ↔ mutually-exclusive details/thread/search side panel) + `CometChatIncomingCall`.
+
+Both encode the same invariants — **keep them when you emit the code**:
+> **Selection has THREE obligations (AUDIT-079)** — a selection that only opens a pane is a dead-end: (1) render the pane; (2) REFLECT it in the list (pass `activeConversation`/`activeUser`/`activeGroup` so the row highlights); (3) every opened side panel is CLOSEABLE (wire `onBack`/`onClose`).
+> **A list-header action ("New chat"/"Create group") goes in the list's `headerView`** — which REPLACES the default header, so render the title AND the button together inside it — NOT a sibling above the list (AUDIT-083; pattern in `../cometchat-react-v7-core/references/component-props.md`).
+
+Both satisfy the reflow-free-surface standard (`../cometchat-react-v7-core/references/layout.md`) and collapse to one pane on mobile (below). The recipes use the `useIsMobile` hook defined in the **Responsive / mobile** section below.
+
+## Responsive / mobile — one screen at a time (MANDATORY for any multi-pane layout)
+Every pattern above that shows more than one pane (full-screen two-pane, sidebar/split, list+thread/detail) MUST collapse to a SINGLE screen at a time on small viewports — a fixed side-by-side layout that squashes on a phone is a defect (`RULES.md` §14), not a style choice. The kit has **no responsive shell** (no `WithMessages`/`CometChatUI`); you compose it from the same selection state, gated by a breakpoint.
+- **Mobile = a navigation stack:** conversations list → tap a conversation → the message pane REPLACES the list full-screen → tap the header → the profile/thread panel REPLACES the message pane. Wide viewport → the SAME state renders side-by-side.
+- **Reuse the built-in back button (don't hand-roll one):** `CometChatMessageHeader` ships `hideBackButton` (default `false`) + `onBack()`. On mobile wire `onBack` to clear the selection (pop to the list) and keep the button visible; on wide set `hideBackButton` (the list is always there).
+
+```tsx
+// SSR-guarded breakpoint hook
+function useIsMobile(query = "(max-width: 768px)") {
+  const read = () => typeof window !== "undefined" && window.matchMedia(query).matches;
+  const [m, setM] = useState(read);
+  useEffect(() => {
+    const mq = window.matchMedia(query);
+    const on = () => setM(mq.matches);
+    mq.addEventListener("change", on);
+    return () => mq.removeEventListener("change", on);
+  }, [query]);
+  return m;
+}
+
+// Mobile: render exactly ONE pane based on state; wide: render them side-by-side.
+const isMobile = useIsMobile();
+if (isMobile) {
+  if (detail && selected) return <DetailOrThread onClose={() => setDetail(null)} />;
+  if (selected) return (
+    <MessagePane>
+      <CometChatMessageHeader {...target} hideBackButton={false} onBack={() => setSelected(null)} />
+      {/* list + composer */}
+    </MessagePane>
+  );
+  return <CometChatConversations onItemClick={pick} />;   // list only
+}
+// wide → the two/three-pane layout, header with hideBackButton
+```
+Native (RN/Flutter): use the platform navigator (stack navigation) — one screen per route — not a web split view.
+
+## Layout wiring per placement
+- **Every placement satisfies the reflow-free-surface standard (`../cometchat-react-v7-core/references/layout.md`)** — pin a content-INDEPENDENT height (full-screen → `100dvh`; sidebar/split → the panes take a viewport or flex/grid-supplied height; popup/embedded → a fixed height e.g. `600px` or a sized grid/flex cell — **never `min-height`/`auto`**), prepare the ancestor chain, and size the columns with `min-height:0`/`overflow:hidden`. The kit fills its parent, so a content-driven container both collapses the chat to ~0px AND grows-into-place as content loads (the two named failure modes).
+- Keep `CometChatProvider` at a stable ancestor (not remounted per route/toggle) so init+login survive navigation.
+- Manage the selected conversation/user/group in host state and pass it to the message components. Fetch the exact selection props from the component's `.md` twin (`../cometchat-react-v7-core/references/docs-map.md`).
+- Reuse the app's existing routing/layout; add wiring, never rewrite (`RULES.md`).
+- **Open an overlay/companion IN the pane its trigger lives in — not full-screen (AUDIT-014).** Search opened from the `CometChatConversations` search bar (`onSearchBarClicked` → `CometChatSearch`) renders **in the conversations list column, over the list** — the message pane stays visible; `onBack`/result-click returns to the list. Do NOT take over the whole screen (it hides the conversation the user was reading). Header search (`onSearchOptionClicked`, scoped by `uid`/`guid`) opens the same way. A full-screen replacement is correct ONLY on a **mobile single-pane** (§ responsive), where the search IS the list-level screen. Same principle for any pane-rooted affordance (thread/profile open in the side panel, not full-screen on desktop).
+
+```tsx
+// Wide: the LEFT column shows search when open, else the list — message pane stays.
+const listColumn = searchOpen
+  ? <CometChatSearch onBack={() => setSearchOpen(false)} onConversationClicked={pick} onMessageClicked={jump} />
+  : <CometChatConversations showSearchBar onSearchBarClicked={() => setSearchOpen(true)} onItemClick={pick} />;
+// <aside className="list-column">{listColumn}</aside> <main>{messagePane}</main>
+// Mobile (single-pane): if (searchOpen) render <CometChatSearch/> full-screen (it's the list screen).
+```
+
+## Common pitfalls (BAKED)
+- Remounting `CometChatProvider` on every route/toggle (re-triggers init/login). Rendering the message pane before a conversation is selected. Nesting multiple providers.
+- **Shipping a fixed side-by-side layout with no small-viewport collapse** — the #1 layout defect. On a phone the list + message panes squash and tapping a conversation does nothing visible. Always add the mobile single-pane branch above and wire the header's built-in `onBack` (AUDIT-011).
+- **Not wrapping the surface in `CometChatErrorBoundary`** — a render error in any kit component then blanks the whole page (white screen) instead of showing a localized fallback + retry. Both recipes above wrap the surface; keep it.
+- **A surface that grows into place as content loads (load-transition reflow)** — small while the list loads, then jumps to full size. The box is content-driven, not pinned: satisfy `layout.md` (pinned `100dvh`, prepared ancestor chain, `min-height:0` columns) and let the kit's own `loadingView`/`emptyView` fill the pinned box — don't gate the surface behind your own placeholder→chat swap (AUDIT-023).
+- **Over-delivering the whole combined app on a plain "add chat"** — the default is the Core-surface recipe (list ↔ message pane); grow to the Combined-app recipe (selector tabs + side panel + incoming call) only when the user asks for the whole app.
+
+## Verify it works
+Chat renders in the chosen layout inside a `CometChatErrorBoundary`, and on a narrow viewport it collapses to ONE pane at a time (list → message → back) — no squashed side-by-side panes on a phone. Default "add chat" ⇒ the Core-surface recipe (list ↔ message pane, sized, affordances wired-or-hidden); the whole combined app (tabs + side panel + incoming call) is the grow target for an explicit full-app ask.
+
+**Close (after it builds):** end with the shared 3-option selectable menu and WAIT for the pick — **① add another feature** (suggest a few not-yet-wired) · **② customize theming** · **③ test it manually** (stop; let the user check). Same contract as the `cometchat-react-v7-core` close (`RULES.md` §19).