@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,101 @@
+---
+name: cometchat-react-v7-core
+description: "Add CometChat chat to a React app end-to-end — detect the project, get & verify dashboard credentials, init→login→render with CometChatProvider, and the drop-in conversation UI. The core knowledge every other React v7 skill builds on. Triggers: 'add chat to my react app', 'integrate cometchat react', 'set up cometchat credentials', 'show conversations and messages'."
+license: "MIT"
+compatibility: "Node.js >=18; React >=18; Vite >=4 / CRA / Next.js; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0); @cometchat/chat-sdk-javascript ^4.1.9"
+metadata:
+  author: "CometChat"
+  version: "1.3.0"
+  tags: "cometchat react core chat integration uikit v7 setup credentials"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7` + `@cometchat/chat-sdk-javascript@^4.1.9`. Symbols sourced from live v7 docs. This file is the THIN map loaded every run; deep detail is in `references/*` loaded ONLY when the task needs it. Anything marked **[v7-verify]** is a v6 carry-over to confirm against v7 docs/catalog before shipping.
+
+<!-- core is the companion the other react v7 skills read; it has no Companion block of its own. -->
+
+## Use this skill when
+"add chat to my React app", "set up CometChat credentials", "integrate CometChat in React", "show a conversations + messages UI", "build a full chat app". An unscoped "add chat" means a **production-ready core chat surface** (a `CometChatConversations` list ↔ a message pane, wrapped in `CometChatErrorBoundary`, sized, affordances wired-or-hidden, mobile collapse) — NOT a bare two-pane demo, and NOT the whole combined app. See the golden path below. It **grows on request** (users/groups/calls tabs, a details/thread/search side panel, calls) to the full combined app — that recipe lives in `cometchat-react-v7-placement`.
+
+## Install
+`npm i @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@4 dompurify` (keep the `@7`/`@4` major pins — a bare install resolves to `latest` and can pull the wrong major). `dompurify` is required by the kit — the docs install includes it. Voice/video calling also needs `@cometchat/calls-sdk-javascript` (see `cometchat-react-v7-features`).
+
+## Setup & credentials (essentials — full detail: `references/setup-credentials.md`)
+1. **Detect** React + bundler (Vite→`VITE_`, CRA→`REACT_APP_`, Next→`NEXT_PUBLIC_`/`.env.local`). Reuse existing `.cometchat`/env if present (skip re-setup).
+2. **version_conflict — STOP** if a non-v7 UI Kit is installed; reconcile first (never mix majors — `RULES.md`).
+3. **Credentials — OFFER the dashboard fetch FIRST, default to it** (never silently "paste it yourself", never defer to a "to finish, add them yourself" TODO — AUDIT-039). Reuse existing `.cometchat`/env if present (skip). Else offer both, defaulting to fetch: **(a) dashboard fetch (recommended)** — load the CLI on demand: `npx @cometchat/skills-cli@3 auth login`, **pick an EXISTING app** (`provision list --json`; **never auto-create**), `provision use --app-id <id> --json` returns the creds + writes a neutral `.cometchat/config.json` (NOT an env file); **(b) manual paste** — Dashboard → Credentials (dev-only Auth Key). **Then the SKILL writes the framework env (§4)** — the CLI stops at the fetch; framework detection, env-writing, and codegen are the SKILL's job, never the CLI's (AUDIT-059). Ask & wait if the user must choose or the CLI can't run. Full flow: `references/setup-credentials.md`.
+4. **Write env** (correct prefix), gitignore it, never echo the Auth Key. Prod → server-side auth token, not the Auth Key.
+5. **Authorize** = `init()` + `login()` resolve; auth error usually means wrong Region.
+
+## Integration ordering (BAKED — invariant; docs: "init() must resolve before login()")
+`init()` once at startup → `login(UID)` after init resolves (guard with the sync `CometChatUIKit.getLoggedInUser()`) → render inside `CometChatProvider`.
+
+```tsx
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+// initFromSettings (NOT the classic UIKitSettingsBuilder init) sets integrationSource="ai-agent"
+// for telemetry attribution — and routes the Calls SDK through initFromSettings too (AUDIT-084).
+await CometChatUIKit.initFromSettings({
+  appId: import.meta.env.VITE_COMETCHAT_APP_ID,
+  region: import.meta.env.VITE_COMETCHAT_REGION,
+  credentials: { authKey: import.meta.env.VITE_COMETCHAT_AUTH_KEY }, // dev only; prod → server-minted auth token
+  chatSDK: { presenceSubscription: { type: "ALL_USERS" } },         // = the classic subscribePresenceForAllUsers()
+});                                                                  // must resolve first
+if (!CometChatUIKit.getLoggedInUser()) await CometChatUIKit.login(UID);   // sync getter — capital "In"
+```
+> Init once + StrictMode double-init, concurrent-login guard, and the reusable provider: `references/lifecycle.md`.
+> **Which UID?** `login()` needs a user that ALREADY EXISTS — never invent/hardcode a guessed one. ASK, or take one from Dashboard → **Users** (fresh apps seed `cometchat-uid-1…`). **Never suggest `superhero1..5` or any remembered "classic sample" UID (not seeded in modern apps); don't fabricate UIDs from memory — the only tentative suggestion is `cometchat-uid-1`, labelled "if this is a fresh app."** Prod → per-user auth token + `loginWithAuthToken`. Detail: `references/setup-credentials.md` §6.
+
+## Component / API map (BAKED closed list)
+Init/provider: `CometChatUIKit`, `UIKitSettingsBuilder`, `CometChatProvider`, `CometChatErrorBoundary` (wraps the surface — production must-have). Core-surface drop-ins: `CometChatConversations`, `CometChatMessageHeader`, `CometChatMessageList`, `CometChatMessageComposer`; wired affordances `CometChatThreadHeader`, `CometChatSearch`. Grow set (added on request): `CometChatUsers`, `CometChatGroups`, `CometChatCallLogs`, `CometChatGroupMembers`, `CometChatIncomingCall`.
+
+## Hot-path props (BAKED — the golden path needs NO fetch)
+The ~12 props you actually wire for "add chat". Do NOT fetch docs for these; do NOT read `.d.ts`.
+- `CometChatConversations`: `onItemClick(conversation)` (select → drives the message pane) · `activeConversation` · `showSearchBar` (default `true`; wire `onSearchBarClicked`→`CometChatSearch` or set `false`) · `selectionMode` (default `"none"`) · `conversationsRequestBuilder` — **scope the list to the REQUEST**: a 1:1/DM-only ask → `new CometChat.ConversationsRequestBuilder().setLimit(30).setConversationType("user")` so the app's seeded groups don't show (`"group"` for groups-only); pass the builder INSTANCE, not `.build()`. **`.setLimit(n)` is REQUIRED on a custom builder** — without it the list renders the kit's "something went wrong" state (verified 7.2.0, AUDIT-245; STOPGAP: the docs' filter-recipe table omits it — remove this note once that docs recipe is fixed). See the data-scope note below.
+- `CometChatMessageHeader`: `onItemClick` (open profile) · `showSearchOption` (default `true`) + `onSearchOptionClicked` → **open a SCOPED `CometChatSearch` (`uid`/`guid` of the current chat) in the side panel (in-chat message search, default-on; opt-out via `showSearchOption={false}`)** · `hideBackButton` (default `false`) + `onBack` (mobile → pop to list).
+- `CometChatMessageList`: `onThreadRepliesClick(message)` → **open the thread panel (DEFAULT — threaded replies ship with a first-time "add chat")**; `hideReplyInThreadOption` ONLY if the user explicitly opts out of threads.
+- `CometChatMessageComposer`: `placeholder` (default `"Type a message..."`); a plain send needs no props.
+- `CometChatProvider`: `theme` (`"light"` default — no OS-follow; sync to `prefers-color-scheme`, see `references/theming.md`).
+> **Stable props + view slots for the 4 drop-ins are BAKED in `references/component-props.md`** — use them: custom UI goes IN the component's slot (search → Conversations `headerView` / MessageHeader `trailingView`), NEVER as a sibling on top. Exhaustive/rare props or any OTHER component → fetch its `.md` twin via `references/docs-map.md`; NEVER read `node_modules/.d.ts`. Full catalog: `cometchat-react-v7-components`.
+
+
+## Golden path — the production-ready CORE surface (default for an unscoped "add chat"; grows on request)
+Setup → guarded init/login → wrap the app in `CometChatProvider` **inside `CometChatErrorBoundary`** → build the core surface: a `CometChatConversations` LIST ↔ a MESSAGE pane (`CometChatMessageHeader` + `CometChatMessageList` + `CometChatMessageComposer`) for the selected conversation, a small host state object coordinating {selected conversation, side view: thread | in-chat-search | none}, collapsing to one pane on mobile. Complete and wired but LEAN — NOT a bare two-pane demo, NOT the whole combined app. Reuse existing routing/layout/auth; add files + wiring only, never rewrite. Least-code = reach for the drop-ins/slots (HOW). **The compile-verified TSX + the required column CSS live in `references/layout.md` (sizing) and `cometchat-react-v7-placement/references/recipes.md` (the Core-surface recipe) — build from those; this entry stays the thin map.**
+
+Wire every default-on affordance so nothing dead-ends, and keep these INVARIANTS:
+- **Threads are DEFAULT** (ship with a first-time "add chat"). Wire `CometChatMessageList onThreadRepliesClick(m)` → a thread panel (`CometChatThreadHeader` + a thread `CometChatMessageList` + `CometChatMessageComposer`) with a close/back round-trip. **The thread list AND composer take BOTH the current target (`user` OR `group`, same as the main pane) AND `parentMessageId`; passing `parentMessageId` ALONE silently NEVER SENDS (AUDIT-060).** Set `hideReplyInThreadOption` only on explicit opt-out. **Differentiate the thread MESSAGE LIST** (not just the wrapper): scope `--cometchat-message-list-bg: var(--cometchat-background-color-01)` on the thread wrapper — the list paints its own opaque bg so a wrapper bg can't reach it (verified vs 7.1.0; recipe in `cometchat-react-v7-customization`).
+- **Two searches, both default-on, both need the FULL round-trip (AUDIT-017).** GLOBAL conversation search over the LIST column (`CometChatConversations onSearchBarClicked` → `CometChatSearch`, no uid/guid — or `showSearchBar={false}`); IN-CHAT scoped search in the SIDE PANEL (`CometChatMessageHeader showSearchOption` default `true` → `onSearchOptionClicked` → `CometChatSearch` with the current `uid`/`guid`, mutually exclusive with the thread). Each renders a back button (`onBack`) you MUST wire to close + return, PLUS `onConversationClicked`/`onMessageClicked` to select the hit — a companion you open, you must also close. (Real server-side search may also need a Dashboard toggle — VERIFY.)
+- **SIZE per the ONE standard — `references/layout.md`.** The kit fills its parent and ships its own `loadingView`/`emptyView`, so a broken-looking surface is a HOST container-sizing defect (a content-driven box), not a kit bug — two modes: static collapse (~0px sliver) and load-transition reflow (grows into place as content loads). Satisfy the 5 invariants: prepare/RESET the ancestor chain (`html,body,#root{height:100%;margin:0}` + undo the Vite/CRA/Next scaffold center+cap+pad, AUDIT-019/035) · pin the surface to a content-INDEPENDENT `100dvh` (never `min-height`/`auto`) · size COLUMNS with `min-height:0`/`overflow:hidden` (scroll, don't grow the parent) · let the kit loading state fill the pinned box · no `transform`/`filter` ancestors. The 2-column CSS is in `layout.md`; the 3-column/embedded/popup/sidebar recipes in `cometchat-react-v7-placement`. Keep `CometChatProvider` WRAPPING `.cc-app`, not inside it (the `.cometchat` wrapper breaks the row — AUDIT-036).
+- **Match data scope to the REQUEST (AUDIT-038).** A 1:1/DM-only ask must NOT show the app's seeded groups — scope with the built-in `conversationsRequestBuilder` prop (pass the `CometChat.ConversationsRequestBuilder` INSTANCE, `.setLimit(30).setConversationType("user")` — `setLimit` required; `"group"` for groups-only; **reuse the prop, don't hand-roll a client-side filter**), and scope the selector to match (no Groups tab on a 1:1-only app). A generic unscoped "add chat" keeps BOTH. Example in `references/component-props.md`.
+- **Theme:** the kit defaults to `light` and does NOT follow the OS (no `theme="system"`) — sync `CometChatProvider theme=` to `prefers-color-scheme` by default (`references/theming.md`, AUDIT-004).
+- **Reuse built-in triggers — don't hand-roll buttons (AUDIT-006).** Wire the props components already expose; custom UI goes IN the component's view slot (search icon → Conversations `headerView` / MessageHeader `trailingView`), NEVER a sibling on top (slot map: `references/component-props.md`). Unclear prop → fetch its `.md` twin (`references/docs-map.md`), never the `.d.ts`.
+- **`CometChatErrorBoundary` wraps the surface** (children required; optional `onError`/`fallbackView`/`componentName`) — a render error then shows a localized fallback + retry, not a blank white screen. It is NOT the initializer (init/login still happen first). Leave header call buttons + composer attach/emoji/voice as built-in defaults; do NOT turn on gated extensions/AI/plugins; do NOT add selector tabs / a details or scoped-search side panel / call logs / incoming call (those are the GROWTHS) unless asked — **but the thread panel IS part of the default.** **Prod auth: `loginWithAuthToken` with a per-user server-minted token; the Auth Key is dev-only** (`references/lifecycle.md`).
+
+**Grows on request → the full combined app** (users/groups/calls **tabs**, a details/thread/scoped-search **side panel**, `CometChatIncomingCall` at root, **calls**, individual **features**) — the UNION of these growths. The compile-verified combined-app recipe (with the required column CSS + `CometChatErrorBoundary`) is baked in **`cometchat-react-v7-placement`**; build the grown app from it. A user who scopes DOWN (embed/popup/sidebar) → the matching `cometchat-react-v7-placement` variant.
+
+## Deep references (load ONLY when the task needs them — keeps this file light on run)
+- `references/setup-credentials.md` — detect, config reuse, version_conflict, dashboard creds, env, authorize.
+- `references/lifecycle.md` — init-once + StrictMode, concurrent-login guard (`ensureLoggedIn`), get-current-UID (sync vs async), prod auth-token, logout, the full `CometChatProvider`.
+- `references/layout.md` — **the ONE reflow-free-surface sizing standard** (the 5 invariants: prepared ancestor chain · pinned content-independent height · `min-height:0` columns · kit loading state inside the pinned box = NO load-transition reflow · no `transform`/`filter` ancestors). `placement` + `calls` reference it too — change sizing rules HERE.
+- `references/ssr.md` — Next.js / Astro / React Router SSR safety (`"use client"`, `ssr:false`, `client:only`).
+- `references/theming.md` — CSS import-once + `--cometchat-*` variables (depth: `cometchat-react-v7-customization`).
+- Localization / RTL / accessibility → the cross-family **`cometchat-i18n`** + **`cometchat-a11y`** skills. Don't render a raw key (`group_info`) — the provider auto-wires localization. React theme tokens: `references/theming.md`.
+- `references/anti-patterns.md` — the 15 real-bug anti-patterns (incl. `transform`/Tailwind overlay bug, container dimensions, **scaffold-boilerplate** = centered/capped/gutter-boxed chat (#15), **global-CSS-leak** = centered names / expanding header, **raw-i18n-key** rendering).
+- `references/dependencies.md` — packages, major pins, `CometChat.*` SDK types, bundle-size cost transparency.
+- `references/component-props.md` — **BAKED stable props + view slots** for the 4 drop-ins (where custom UI goes IN each component — search → Conversations `headerView`, MessageHeader `trailingView`, etc.).
+- `references/docs-map.md` — intent → the exact docs `.md` twin to fetch (replaces reading `.d.ts`); **for a whole feature/task, its "Task guides (recipes)" section says to BUILD FROM the official guide + COMPARE your implementation against it (docs-maximal), then apply the hardening deltas.**
+- Symptom → cause → fix (blank screen, SSR `window is not defined`, ~0px collapse, kit error state, empty lists, events not firing, `version_conflict`) → the **`cometchat-react-v7-troubleshooting`** skill.
+
+> **Visual Builder (VCB) is out of scope.** If asked to integrate a VCB export, point to the CometChat Visual Builder docs (via `references/docs-map.md`); don't hand-roll a builder-export flow.
+
+## Common pitfalls (top 4 — full list in `references/anti-patterns.md`)
+version_conflict (v6 installed) · wrong Region or env prefix · Auth Key shipped to prod client · rendering/login before init resolves.
+
+## Verify it works
+Start the app → confirm `init()` then `login()` resolve → the `CometChatConversations` list renders inside `CometChatProvider` (itself inside `CometChatErrorBoundary`) at full size (not a collapsed sliver); open a conversation → the message pane loads and messages send/receive; **clicking "reply in thread" opens the thread panel (default) and its back/close returns to the list** (hidden only if the user opted out), and the thread's MESSAGE LIST reads as a distinct surface matching its own header/composer (not the same shade as the main list — the `--cometchat-message-list-bg` override is scoped on the thread wrapper); **clicking the message-header search icon opens an in-chat search in the side panel scoped to THAT conversation (default), with back to close**; the conversations search bar is wired-or-hidden (no dead-ends); on a narrow viewport it collapses to one pane at a time (list → message → thread/search → back). Blank white screen ⇒ something rendered before `init()` resolved, the Region / env prefix is wrong, or an unbounded render error escaped (add `CometChatErrorBoundary`). A list + message pane with no sizing / no error boundary / dead-ending affordances ⇒ under-delivery (see the golden path). Growing to the full app (tabs + side panel + incoming call) ⇒ verify per `cometchat-react-v7-placement`.
+
+## Explain what you built (REQUIRED close)
+After it builds + verifies, don't dump silently — tell the user briefly: **(1) what I wired** (3–5 bullets, NAME the files); **(2) decisions & why**, flagging dev-only AS dev-only (dev **Auth Key** → server auth token for prod; the `<uid>`; OS-follow theme); **(3) what I did NOT touch** (additive — routing/auth/styles intact). Then **(4) offer these THREE options as a SELECTABLE choice and WAIT for the user's pick — do NOT auto-continue:**
+- **① Add another feature** → **first check what's ALREADY there, then suggest only the GAP (AUDIT-043).** Read what's wired (the emitted code you built) and ASK which dashboard-gated extensions are already enabled (you can't reliably read per-app dashboard state — don't assume OFF). SUGGEST 3–4 grow-set items that are NEITHER wired NOR already enabled (voice/video **calls** · **search** · **threads** if off · **push** · **AI/smart-replies** · **moderation** · polls/stickers/translation) — **never re-suggest something already on (e.g. translation already enabled in the dashboard)**. **Do NOT suggest `reactions` or `mentions` — they are ON BY DEFAULT in v7 (core messaging; their dashboard extensions are "(Legacy)", already in core — AUDIT-077); if the user asks, say they're already on and offer to customize them.** Then build the chosen one (→ `cometchat-react-v7-features` / `cometchat-react-v7-calls`).
+- **② Customize theming** → ask whether they already have a **preset / brand theme** (a brand color, light/dark, or match an existing design system) or want to talk through the options, then wire it (→ `cometchat-react-v7-customization`).
+- **③ Test it manually** → do NOTHING further — hand it back so the user runs and checks it themselves.
+
+A PARKED capability (push · migration · SDK-only) → isn't in this pack yet: say so honestly + link CometChat's docs. **This 3-option close runs after EVERY implementation (`RULES.md` §19 / AUDIT-040).**

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

@@ -0,0 +1,19 @@
+# anti-patterns — real bugs, do NOT do these (React v7)
+
+1. **No `init()` during render** — async + side effects → infinite re-render. Use `useEffect` or pre-`createRoot`.
+2. **Import the UI Kit CSS once** — duplicate imports = specificity conflicts + doubled variables.
+3. **No render before init completes** — components assume the SDK is initialized ("CometChat is not initialized"). Gate with the provider/ready-state.
+4. **Never hardcode `AUTH_KEY`** — env var in dev; auth token in prod.
+5. **Guard concurrent `login()`** — safe sequentially only; overlap throws "Please wait until the previous login request ends." Cache a module-level in-flight promise (`ensureLoggedIn`, see `lifecycle.md`).
+6. **No server-side render** of components — `"use client"` (Next), `client:only="react"` (Astro). See `ssr.md`.
+7. **Don't target internal CSS classes** — use `--cometchat-*` variables.
+8. **Container needs a content-INDEPENDENT height** — components fill 100% of the container, so a content-driven box both collapses to ~0px (static collapse) AND grows-into-place as content loads (load-transition reflow). Pin it (`100dvh` / a fixed height / a sized grid-flex cell — never `min-height`/`auto`) with a prepared ancestor chain, and size the columns `min-height:0`. The ONE sizing standard: `layout.md`.
+9. **Don't re-init on route change** — init once at app level; re-init flickers + drops WebSockets.
+10. **Don't invent component names** — check `cometchat-react-v7-components` (and `web-v7.json`). A wrong name (e.g. `<CometChatMessenger>`) is a build error.
+11. **No `transform` on a container wrapping chat** — a non-`none` `transform` creates a containing block for `position: fixed` descendants; the UI Kit renders overlays (options menu, emoji picker, file preview, reactions, thread panel) as `position: fixed` and expects them anchored to the viewport. **This includes Tailwind `translate-x-*`/`-translate-y-*`/`scale-*`/`rotate-*`/`transition-transform`** — all compile to `transform` and clip/offset the overlays. Also `filter`, `perspective`, `backdrop-filter`, `will-change: transform`. **Fix:** animate `right`/`left` offset (or `margin-right`) instead of transform — in Tailwind toggle `right-0` ↔ `right-[-420px]` with `transition-[right]`. See `cometchat-react-v7-placement` drawer/widget patterns.
+12. **Don't let host global CSS leak into the `.cometchat` subtree.** The kit's layout is self-contained and correct by default (verified vs 7.1.0): `.cometchat-conversations__header` is `flex-shrink:0` / `min-height:64px` (fixed — **NOT `flex:1`**), `.cometchat-conversations__list` is `flex:1`, and list-item titles are **left-aligned**. So if the **conversations header expands to fill height**, or **list-item names render centered**, the cause is a global style bleeding onto kit elements — a `text-align:center` / `align-items:center` / `flex:1` / CSS reset / Tailwind base on an ancestor — or an override of an internal class, NOT the kit. **Fix:** scope global CSS away from the `.cometchat` subtree (no `text-align`/flex-centering/`flex` on the kit's ancestors), never override the internal BEM classes (`.cometchat-*__header`/`__item-*`/`__list` — customize via `--cometchat-*` vars + view slots, #7), and give the mount container an explicit height so `.cometchat-conversations__root { height:100% }` resolves (#8).
+13. **Never render a raw localization key as a label** — the kit localizes via `CometChatProvider`; a snake_case token in the UI (`group_info`, `add_members`) is a missing/wrong key or a literal-key render. Use the kit component or `useLocale().getLocalizedString(key)`. See the `cometchat-i18n` skill.
+14. **Don't `import { CometChat }` just for types** — the SDK namespace is an **ambient global**, so `CometChat.User`/`CometChat.Group`/`CometChat.BaseMessage` resolve as types with NO import. A value import used only in type positions fails the Vite React-TS template's strict config (`noUnusedLocals` + `verbatimModuleSyntax`) with `TS6133: 'CometChat' is declared but its value is never read` — and `import type { CometChat }` does **not** fix it (the type comes from the global, not the import). **Rule:** import `CometChat` **only** when you use it as a value (`msg instanceof CometChat.User`, `CometChat.CometChatHelper.getConversationFromMessage(...)`, `new CometChat.GroupMembersRequestBuilder(...)`); for type-only usage, drop the import and use the ambient global. (AUDIT-007.)
+15. **Full-page chat: clear the scaffold boilerplate CSS (the #2 "UI looks broken" defect).** A fresh Vite/CRA/Next app ships template CSS that **centers, width-caps, and pads the root** — Vite's `#root { max-width:1280px; margin:0 auto; padding:2rem; text-align:center }` + `body { display:flex; place-items:center }` (CRA `App.css`, Next `globals.css` have analogues). Drop a `100dvh` chat surface into that and it renders as a **centered ~1280px padded box with big side gutters, message bubbles/overlays clipping off the edge** ("exceeding the viewport / broken"). **Fix:** before the chat CSS, reset it — `html, body, #root { height:100%; margin:0; padding:0 }` + `#root { max-width:none; text-align:left; display:block }` + remove `body{place-items:center}`; give `.cc-app` `overflow:hidden` and the message column `min-width:0; min-height:0; overflow:hidden`. (Verified reproduction: a capped/centered `#root` shoves chat into a ~729px gutter-boxed island; the reset makes it full-bleed. AUDIT-019.) This is invariant (a) of the reflow-free-surface standard — full rule + the load-transition-reflow mode: `layout.md`.
+16. **Don't expect an OPAQUE kit sub-surface to inherit a wrapper's background — override the sub-surface's OWN CSS variable.** `.cometchat-message-list` paints an opaque `background: var(--cometchat-message-list-bg)` (default `--cometchat-background-color-03`), so a background set on a wrapping `div` is COVERED by the list and never shows — the list stays the same shade regardless of the wrapper. Canonical case: the **thread panel** — its header/composer paint their own opaque `--cometchat-background-color-01`, so the thread message list looks like the MAIN list (both `-03`) and different from its own header/composer, even after you give the thread wrapper a background. **Fix:** scope the surface's OWN token on the wrapper — `.cc-thread-panel { --cometchat-message-list-bg: var(--cometchat-background-color-01); }` (cascades into the list; matches the thread header/composer, differs from the main list's `-03`; verified vs 7.1.0). Generalizes to any opaque sub-surface: differentiate it by overriding ITS background variable, not the wrapper's, and never the internal `.cometchat-*` class (#7/#12). (AUDIT-020/024; depth: `cometchat-react-v7-customization`.)
+17. **Don't write a per-theme override as `[data-theme="dark"] .cometchat { … }` — it matches nothing.** `CometChatProvider` renders ONE wrapper — `<div data-theme="light|dark" class="cometchat">` (verified vs 7.1.0: compiled bundle `jsx("div",{ "data-theme": internalTheme, className: "cometchat" })`) — and the kit defines its tokens on `:root, [data-theme=light]` / `[data-theme=dark]`. So `data-theme` and `.cometchat` are the SAME element; the descendant selector `[data-theme="dark"] .cometchat` looks for a `.cometchat` NESTED inside a `[data-theme]` ancestor, which doesn't exist → the rule silently no-ops (a correct-looking override that does nothing). **Fix:** for a per-theme BRAND token use the same-element selector `.cometchat[data-theme="dark"] { --cometchat-primary-color: … }` (or bare `[data-theme="dark"]`); to retint a kit INTERNAL per theme use `[data-theme="dark"] .cometchat-<bem> { … }` — the wrapper as ancestor, a BEM class as the descendant, which is exactly how the kit writes its own dark rules (e.g. `[data-theme=dark] .cometchat-tooltip`). Never target internal BEM for tokens (#7). (AUDIT-025; depth: `cometchat-react-v7-customization`.)

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

@@ -0,0 +1,82 @@
+# component-props — BAKED stable props + view slots for the React v7 drop-ins
+
+The high-value, STABLE props **and view slots** for the core drop-in components — baked here (not
+fetched) because getting the slots wrong is the #1 recurring UI defect. Verified against live v7
+docs (`components/*.md`). Exhaustive/rare props still come from a component's `.md` twin
+(`docs-map.md`), but **these — especially the VIEW SLOTS — are baked.**
+
+## THE RULE — custom UI goes in the component's OWN view slot, NEVER as a sibling on top
+A search icon, extra action button, banner, or custom header belongs **inside** the component via
+its slot (below). Do **NOT** render it as a sibling element above/beside the component. Rendering
+a search control "on top of" the conversation list instead of in its `headerView`, or above the
+message header instead of in its `trailingView`, is a defect — fix it by using the slot.
+
+> **List-header actions ("New chat" / "Create group" / "+") go in `headerView` — but `headerView` REPLACES the whole default header, so RE-RENDER the title (AUDIT-083).** The list components (`CometChatConversations` / `CometChatUsers` / `CometChatGroups`) show a default header with a **title** ("Chats"/"Users"/"Groups") by default. Their only header slot is `headerView`, which replaces that ENTIRE header — so if you drop a bare button into `headerView` you LOSE the title. Render BOTH: the title (re-created) AND your action button. Do NOT place the button as a sibling above the list (the defect this rule fixes).
+> ```tsx
+> import { useLocale } from "@cometchat/chat-uikit-react";
+> const { getLocalizedString } = useLocale();
+> <CometChatGroups
+>   headerView={
+>     <div style={{ display: "flex", alignItems: "center", justifyContent: "space-between", padding: "0 12px", height: 56 }}>
+>       <h3 style={{ margin: 0 }}>{getLocalizedString("groups")}</h3>   {/* re-render the default title */}
+>       <button aria-label="Create group" onClick={openCreateGroup}>＋</button>  {/* the action, right of the title */}
+>     </div>
+>   }
+>   onItemClick={openGroup}
+> />
+> ```
+> Same for a **"New chat"** button on `CometChatConversations` (title `"chats"`) and `CometChatUsers` (title `"users"`). (Use `useLocale().getLocalizedString(...)` for the title so it stays localized; `<h3>Chats</h3>` is fine if you don't localize.)
+
+---
+
+## CometChatConversations
+**Props:** `onItemClick(conversation)` · `onSearchBarClicked` · `showSearchBar` (default `true`) · `selectionMode` (default `"none"`) · `activeConversation` · `onSelect` · `conversationsRequestBuilder` (scope which conversations load) · `searchRequestBuilder` (scope server-side search) · hide toggles (`hideReceipts`, `hideUserStatus`, `hideGroupType`, `hideDeleteConversation`).
+**View slots (inject custom UI INSIDE the component):**
+- `headerView: ReactNode` — the **entire header area**. → **Custom header controls (a search icon, filter, custom title) go HERE.**
+- `searchView: ReactNode` — the search bar within the header.
+- `itemView(conversation)` · `leadingView` · `titleView` · `subtitleView` · `trailingView` — per row.
+- `options(conversation) => CometChatConversationOption[]` — per-row context-menu actions.
+- `loadingView` · `emptyView` · `errorView` — list states.
+> **Search icon in the conversation list header → put it in `headerView`** (or wire `onSearchBarClicked` → `CometChatSearch` rendered in the list column). NOT a sibling on top of the list.
+> **Scope the list to the request via `conversationsRequestBuilder` (a `CometChat.ConversationsRequestBuilder`).** A **1:1 / DM-only** app → `.setLimit(30).setConversationType("user")` (hides the app's seeded groups); **groups-only** → `.setLimit(30).setConversationType("group")`. **Always include `.setLimit(n)`** — a builder without it renders the kit's error state instead of the list (verified 7.2.0, 2026-09-12, AUDIT-245; STOPGAP until the docs' filter-recipe table adds it). **Pass the builder INSTANCE, not `.build()`** — the kit builds it internally; passing the built object breaks the list (verified vs live v7 `conversations.md`: "Pass the builder instance — not the result of `.build()`"; AUDIT-038). `searchRequestBuilder` scopes server-side search the same way. A generic unscoped "add chat" → OMIT it (show both users and groups). Don't add a Groups tab to a 1:1-only app.
+> ```tsx
+> import { CometChat } from "@cometchat/chat-sdk-javascript";
+> <CometChatConversations conversationsRequestBuilder={new CometChat.ConversationsRequestBuilder().setLimit(30).setConversationType("user")} />
+> ```
+
+## CometChatUsers / CometChatGroups (selector-tab lists)
+**Props — REFLECT the selection (active state):** `onItemClick(user|group)` · **`activeUser` / `activeGroup`** — pass the currently-selected user/group so the list HIGHLIGHTS the open row (the analogue of `CometChatConversations activeConversation`). In a selector-tabs app you MUST pass these; without them the list shows **no active state** and the user can't tell which item is open (AUDIT-079). Also `usersRequestBuilder` / `groupsRequestBuilder` to scope the list, and the same view slots (`headerView`, `itemView`, `titleView`/`subtitleView`/`trailingView`, `options`, `loadingView`/`emptyView`/`errorView`).
+> **Selection has THREE obligations (AUDIT-079):** (1) render the pane, (2) reflect it via `active*` (here), (3) close every panel it opens (round-trip — see `CometChatGroupMembers`/`CometChatSearch`/`CometChatThreadHeader` `onBack`/`onClose`). Wiring only (1) is a composition dead-end.
+
+## CometChatSearch (the companion opened from `onSearchBarClicked`)
+**Props (wire the full round-trip — open AND close):** `onBack()` — **fired by the default back button; wire it to CLOSE search and return to the list (the same state that opened it), or the back button dead-ends** · `onConversationClicked(event)` and `onMessageClicked(event)` — result clicks; wire to **close search + select the result** · `hideBackButton` (default `false`) · `uid`/`guid` (scope to one conversation) · `searchIn` (`["conversations","messages"]`) · `loadingView`/`emptyView`/`errorView`.
+> **You opened it — you must close it.** Rendering `CometChatSearch` without `onBack` is the #1 search defect (AUDIT-017): the back button shows but does nothing. Minimal wiring: `const [searching, setSearching] = useState(false)` → open on `onSearchBarClicked`, `onBack={() => setSearching(false)}`, and on `onConversationClicked`/`onMessageClicked` set the selected conversation + `setSearching(false)`.
+>
+> **TWO searches — both default-on:** (1) **GLOBAL** (all conversations) — from `CometChatConversations onSearchBarClicked`, rendered OVER the list column, NO `uid`/`guid`; (2) **IN-CHAT / SCOPED** (this conversation only) — from `CometChatMessageHeader onSearchOptionClicked`, rendered in the **side panel** (same slot as the thread, mutually exclusive), **scoped with `uid`/`guid`** so it only searches the open chat (the official `CometChatHome` sample pattern). The side panel is ONE mutually-exclusive slot: opening scoped search closes the thread and vice-versa. Full side-panel recipe (both searches wired, with the round-trip): `../../cometchat-react-v7-placement/references/recipes.md`.
+
+## CometChatMessageHeader
+**Props:** `onItemClick` (open profile) · `onBack` + `hideBackButton` (default `false`) · `showSearchOption` (default `true`) + `onSearchOptionClicked` · `showConversationSummaryButton` + `onSummaryClick`.
+**View slots:**
+- `trailingView: ReactNode` — the header **right side** (replaces call buttons + overflow menu). → **Custom action buttons (search, call, custom icon) go HERE.**
+- `auxiliaryButtonView: ReactNode` — auxiliary button area.
+- `leadingView` · `titleView` · `subtitleView` — replace avatar / name / status.
+- Compound sub-components for granular control: `Avatar`, `Title`, `Subtitle`, `CallButtons`, `SearchButton`, `SummaryButton`, `OverflowMenu`, `AuxiliaryButtons`.
+> **A custom search/action icon in the message header → put it in `trailingView`** (or `auxiliaryButtonView`), or use the built-in `showSearchOption` + `onSearchOptionClicked`. NOT a sibling above the header.
+
+## CometChatMessageList
+**Props:** `onThreadRepliesClick(message)` · `hideReplyInThreadOption` · `showSmartReplies` (default `false`; footer) · `showConversationStarters` (default `false`; footer when empty) · hide toggles (`hideReceipts`, `hideDateSeparator`, `hideReactionOption`, …).
+**View slots:**
+- `bubbleView(message, loggedInUser)` — replace an entire message bubble.
+- `headerView: ReactNode` — banner **above** the scroll container. → **A custom banner/notice goes HERE.**
+- `footerView: ReactNode` — area **below** the scroll (smart replies render here).
+- `loadingView` · `emptyView` · `errorView`.
+
+## CometChatMessageComposer
+**Props:** `placeholder` (default `"Type a message..."`) · `onSendButtonClick(message, mode)` · `enterKeyBehavior` (`"send" | "newline" | "none"`) · `enableMultipleAttachments` · `disableTypingEvents` · `disableMentions` · `layout` (`"compact" | "multiline"`).
+**View slots:**
+- `headerView: ReactNode` — area **above** the input (reply-preview, banner). → **Custom composer header goes HERE.**
+- `auxiliaryButtonView: ReactNode` — extra buttons in the actions area **before** send. → **A custom action button goes HERE.**
+- `sendButtonView` · `attachmentButtonIconView` · `voiceRecordingButtonIconView` · `emojiButtonIconView` — swap specific icons/buttons.
+
+---
+For any component NOT above, or exhaustive props → fetch the component's `.md` twin (`docs-map.md`). But for these four, **use the slots above** — don't render custom controls outside the component.

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

@@ -0,0 +1,23 @@
+# dependencies — packages, pins, SDK types (React v7)
+
+## Packages (two)
+```json
+{ "@cometchat/chat-uikit-react": "^7", "@cometchat/chat-sdk-javascript": "^4" }
+```
+UI Kit = the React components; SDK = the `CometChat` namespace (types + methods).
+> **Keep the `@^7` / `@^4` major pins — never a bare `npm install @cometchat/chat-uikit-react`.** A bare install resolves to `latest`; these skills teach v7, so an unpinned install can pull the wrong major and break the integration.
+
+## SDK types you'll use
+```typescript
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+CometChat.User          // a chat user
+CometChat.Group         // a chat group
+CometChat.Conversation  // wraps a User or Group
+CometChat.BaseMessage   // any message
+CometChat.TextMessage   // a text message
+CometChat.getUser(uid): Promise<CometChat.User>
+CometChat.getGroup(guid): Promise<CometChat.Group>
+```
+
+## Cost transparency (disclose when integrating into a new project) — **[v7-verify numbers]**
+The v6 kit added ~2.8 MB JS (~860 KB gzip), ~860 KB CSS, ~1.5 MB Roboto fonts (9 weights). Re-measure for v7. If the app already loads custom fonts, override `--cometchat-font-family` to skip preloading kit fonts. For evaluators: pricing at cometchat.com/pricing (free tier for dev/test); data export via REST (`GET /v3/users|groups|messages`) — no lock-in.

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

@@ -0,0 +1,117 @@
+# docs-map — CometChat React v7: intent → the exact docs page to fetch
+
+## Reaching docs — PREFER the CometChat docs MCP; fetch is the fallback
+The canonical doc channel is the **first-party CometChat docs MCP** — tools `search_cometchat_docs`,
+`fetch_cometchat_doc_page`, and `get_cometchat_implementation_bundle`. **If those tools are connected,
+use them instead of a raw web fetch:**
+- **Find the page** → `search_cometchat_docs(query, version?)` — replaces browsing the scoped `llms-*` index.
+- **Read the page** → `fetch_cometchat_doc_page(path)` — pass the SAME `<path>` the tables below list
+  (the conversations page path for your platform); the MCP resolves the `.md` twin and returns raw Markdown.
+  A full `https://…/docs/<path>` URL also works.
+- **A whole feature/recipe** → `get_cometchat_implementation_bundle(...)` is **NON-AUTHORITATIVE** — curated STATIC recipes that can lag the live docs (verified stale vs v7: e.g. `CometChatConversationsWithMessages`, `css-variables.css`). Treat any bundle as a hint only: RECONCILE it against the `fetch_cometchat_doc_page` result + the pack's hardening; never emit bundle code verbatim.
+
+The MCP reads whatever docs environment it is pointed at (production by default; a preview when repointed),
+so it also carries the environment-swap concern below — no hardcoded host on the skill side.
+
+**If the MCP tools are NOT connected:** add it (`claude mcp add --transport http cometchat-docs https://mcp.cometchat.com/mcp`, or reinstall/enable the plugin) and retry; only if it still will not connect, fall back to a plain fetch via `DOCS_BASE` (defined next).
+Either way the `<path>` catalog in this file is the source of truth for WHICH page — MCP-vs-fetch is only HOW.
+
+## DOCS_BASE — the fetch FALLBACK entry point (⚠️ SWAP HERE to change environments)
+```
+DOCS_BASE = https://www.cometchat.com/docs
+```
+> **Fetch rule:** always build a URL as `DOCS_BASE` + the path shown, then append `.md`.
+> Never hardcode a host anywhere else; never read `node_modules`/`.d.ts`.
+
+## The convention
+`DOCS_BASE` + `<path>` + `.md` → raw Markdown (verbatim code + an "AI Integration Quick Reference"
+JSON block: prop names, types, defaults).
+```
+Fetch:  {DOCS_BASE}/ui-kit/react/components/conversations.md
+```
+Fallback order: `.md` twin → if it 404s, the same URL **without** `.md` (HTML) → **never** a `.d.ts`.
+
+## Scoped React v7 index (prefer over the global llms.txt)
+```
+{DOCS_BASE}/ui-kit/react/llms-react-v7.md
+```
+A React-v7-only index of every page as a `.md` link (~3k tok) — use it to discover any page not in
+the table below. Global all-products index (large, ~25k tok; last resort): `{DOCS_BASE}/llms.txt`.
+
+## SDK docs — the FALLBACK reference (a feature the UI Kit has NO component for)
+The rule of the pack: **for every feature, first check whether the UI Kit has a component/prop for it
+(this file's table + `component-props.md` + the catalog). If it does — USE it. If it does NOT** (e.g.
+AI agents, campaigns, advanced/AI moderation, transient messages, bots, webhooks, low-level presence)
+**— drop to the JavaScript Chat SDK and call its methods directly** (the SDK library is already
+installed under the UI Kit; init/login already use it). Look the method up in the SDK docs — never guess:
+```
+SDK_DOCS_BASE = https://www.cometchat.com/docs
+```
+- **SDK index (scoped — PREFER this):** `{SDK_DOCS_BASE}/sdk/javascript/llms-javascript-v4.md` — a **JS-SDK-v4-only** routing index of every SDK page as a `.md` twin, grouped by area (Messaging · Calling · Users · Groups · **AI, campaigns & webhooks: AI Moderation · AI Agents · AI Copilot · Campaigns · Webhooks** · Real-time Listeners · Key Concepts · …). Start here to find the feature's page. **Do NOT use the site-wide global `{SDK_DOCS_BASE}/llms.txt`** (all products, far larger) except as a last resort if the scoped index 404s — mirrors the React scoped-index rule above.
+- **Convention:** `{SDK_DOCS_BASE}/sdk/javascript/<page>` then append `.md` for the raw Markdown twin. Each SDK page opens with an **"AI Integration Quick Reference" accordion** (Package · Import · **Key methods**) — read that FIRST for the exact method names/signatures, then the tables + TS/JS examples below.
+- **Example:** AI agents → `{SDK_DOCS_BASE}/sdk/javascript/ai-agents.md` → `CometChat.addAIAssistantListener(id, …)`, `CometChat.AIAssistantMessage`, `CometChat.AIToolCall`, `getAssistantMessageData()`, …
+> Never hand-roll a feature that exists in the UI Kit OR the SDK, and never guess an SDK method — look it up in the SDK index → the page's Quick-Reference accordion.
+
+## Don't fetch the hot path — it's baked
+Install, `init → login → render`, the provider, and the ~12 drop-in props for "add chat" are BAKED
+in `cometchat-react-v7-core`. Fetch ONLY for exhaustive props / view-slots / long-tail components /
+theming tokens / feature enablement.
+
+## The 80% trigger table  (URL = `{DOCS_BASE}` + path, then append `.md`)
+| Intent | Path (append `.md`) |
+|---|---|
+| setup / init / login / render | `/ui-kit/react/integration-react` |
+| Next.js / React Router / Astro setup | `/ui-kit/react/integration-nextjs` · `-react-router` · `-astro` |
+| conversation list (full props) | `/ui-kit/react/components/conversations` |
+| message list | `/ui-kit/react/components/message-list` |
+| message composer | `/ui-kit/react/components/message-composer` |
+| message header | `/ui-kit/react/components/message-header` |
+| users / groups / group members | `/ui-kit/react/components/users` · `groups` · `group-members` |
+| threads | `/ui-kit/react/components/thread-header` |
+| message search | `/ui-kit/react/components/search` |
+| reactions | `/ui-kit/react/components/reactions` |
+| message bubbles (swap/custom) | `/ui-kit/react/components/<x>-bubble` (text/image/video/audio/file/poll/sticker/card…) |
+| voice/video call buttons | `/ui-kit/react/components/call-buttons` |
+| incoming / outgoing call UI | `/ui-kit/react/components/incoming-call` · `outgoing-call` |
+| call logs | `/ui-kit/react/components/call-logs` |
+| calls setup / enable calling (calls-setup) | `/ui-kit/react/integration-react` · Calls SDK: `/calls/javascript/setup` |
+| custom call surface / joinSession (calls-react-integration) | `/calls/javascript/react-integration` |
+| screen-share · recording · device-select · idle-timeout · virtual-bg | `/calls/javascript/screen-sharing` · `recording` · `device-management` · `idle-timeout` · `virtual-background` |
+| AI assistant | `/ui-kit/react/components/ai-assistant-chat` |
+| web push setup (push-overview / web-push) | `/notifications/push-overview` · `/notifications/web-push-notifications` |
+| notification preferences / mute (notification-preferences) | `/notifications/preferences` |
+| theming / CSS `--cometchat-*` tokens | `/ui-kit/react/theming` |
+| plugins | `/ui-kit/react/plugins/overview` |
+| event system | `/ui-kit/react/event-system` |
+| full component list | `/ui-kit/react/components-overview` |
+| v6→v7 migration / upgrade | `/ui-kit/react/migration-overview` · `/ui-kit/react/migration-property-changes` |
+
+## Task guides (recipes) — for a whole FEATURE, BUILD FROM the guide + COMPARE against it (docs-maximal)
+For a TASK/feature ask (a whole capability, not just one component's props), the docs ship **full end-to-end
+guides**. **Discover them from the scoped llms index's "Task guides (recipes)" section**
+(`{DOCS_BASE}/ui-kit/react/llms-react-v7.md`) — the index is the source of truth (new guides appear there;
+do NOT bake this list). At time of writing it lists: `guide-new-chat-creation` · `guide-group-chat-setup` ·
+`guide-search-messages` · `guide-threaded-messages` · `guide-message-privately` · `guide-block-unblock-user`.
+**Use the matching guide TWO ways — prefer it over baked recipe prose wherever a guide exists:**
+1. **As the implementation SOURCE** — fetch `{DOCS_BASE}/ui-kit/react/<guide>.md` and build the feature from
+   the official recipe. **Adapt it ADDITIVELY** into the user's app (reuse their routing/auth/layout; never
+   drop in the guide's standalone shell).
+2. **As a COMPLETENESS + CORRECTNESS check** — after you emit, DIFF your implementation against the guide:
+   did you cover every component, prop, step, and affordance it shows? Fill any gap. This is the docs-sourced
+   completeness oracle (richer + more current than a baked minimum).
+> **Then apply the baked HARDENING DELTAS on top — the guide is the BASELINE, not the whole truth.** The
+> guides do NOT carry the audit lessons: thread list/composer need the conversation **`user`/`group` AND**
+> `parentMessageId` (AUDIT-060); in-chat search must be **scoped** (`uid`/`guid`) vs global (AUDIT-041);
+> container **sizing** (`100dvh` + column CSS); wrap in **`CometChatErrorBoundary`**; roster lists **double
+> under StrictMode** (dev); **wire-or-hide** every default-on affordance. Build from the guide, then correct
+> with these. (Several audits were literally GAPS in the official guide — the guide gets you complete, the
+> deltas get you correct.)
+
+**No matching guide in the index? → continue EXACTLY as before** — build from the pack's baked golden-path /
+recipe (`FULL-APP-BLUEPRINT`, placement recipes, `component-props.md`) and fetch each component's `.md` twin
+for exact props. **The guide is an ENHANCEMENT when present, never a hard dependency** — a feature without a
+task guide is built the normal way, not blocked.
+
+## Not in the table?
+Fetch the scoped index (`{DOCS_BASE}/ui-kit/react/llms-react-v7.md`), pick the page, fetch its `.md`.
+Never guess a path; never read `.d.ts`; never answer props from memory.

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

@@ -0,0 +1,150 @@
+# layout — the reflow-free chat surface (the ONE sizing standard)
+
+The single source of truth for how a CometChat surface is SIZED so it renders full-size
+from the first frame and never reflows. `core`, `placement`, and `calls` POINT here
+instead of each re-stating the CSS — change the rule once, here.
+
+> **The kit is NOT the problem.** Every UI Kit component fills its parent by design
+> (`height:100%` / flex-fill) and ships its OWN loading/empty state
+> (`loadingView` / `emptyView` slots). A surface that starts small and grows, or collapses
+> to ~0px, is a HOST **container-sizing** defect, not a kit bug: the host box is
+> **content-driven** instead of **pinned**. Pin the box and the kit renders full-size
+> immediately and swaps loading→loaded INSIDE a stable box — zero shift.
+
+## The named failure modes
+
+Two distinct sizing defects, one root cause (a content-driven box the kit then fills):
+
+1. **Static collapse** — the surface renders as a ~0px sliver / crammed top-left, because
+   the mount container (or an ancestor) has no resolved height. (The #1 "UI looks broken"
+   report; anti-patterns #8.)
+2. **Load-transition reflow** *(named here for the first time)* — the surface is SMALL
+   while the conversation list loads, then GROWS to full size once content arrives; height
+   and/or width expand WITH content instead of being pinned. It looks broken and can
+   misplace the UI. Root cause: the box is **content-driven** (ancestor chain not
+   `height:100%`, or the container uses `min-height`/`auto`, or an intermediate wrapper
+   isn't sized), so before content loads there is nothing to give the box its size — the
+   kit fills "nothing," and only grows as messages/list items arrive. **A pinned box with
+   a prepared ancestor chain is full-size from frame 1; the kit's own loading state fills
+   it; the swap to loaded causes NO reflow.**
+
+## The five invariants (a reflow-free surface satisfies ALL)
+
+**(a) Prepare the ancestor chain.** Make `html, body, #root` full-height so a
+`100dvh`/`100%` on your container has a non-zero chain to resolve against:
+```css
+html, body, #root { height: 100%; margin: 0; }
+```
+A bare app usually has NONE of these → every descendant height resolves against `0`. A
+fresh Vite/CRA/Next scaffold has the OPPOSITE problem — it CENTERS + width-caps + pads
+`#root` (`max-width:1280px; margin:0 auto; padding:2rem; text-align:center` +
+`body{display:flex; place-items:center}`), gutter-boxing chat into a centered island with
+content clipping off the edge. **Watch for a WIDTH-PINNED root, not just `max-width`
+(AUDIT-035):** some scaffolds pin `#root { width: 1126px; margin: 0 auto; border-inline: … }`
+— nulling only `max-width` leaves the fixed `width`, so the surface stays gutter-boxed on
+desktop AND overflows horizontally on a phone. Reset `width` (and `min-height`/`border`) too.
+Either way, RESET/PREPARE the root before the chat CSS — add what's missing AND undo the
+scaffold cruft (AUDIT-019/035):
+```css
+#root { width: auto; max-width: none; min-height: 0; border: 0; text-align: left; display: block; }  /* undo cap/center/pad AND a width-pin */
+body  { display: block; place-items: normal; min-width: 0; }   /* undo body flex-centering */
+*, *::before, *::after { box-sizing: border-box; }
+```
+
+**(b) Pin the surface to a content-INDEPENDENT height.** The surface box's height must NOT
+depend on its content. Full-page → `height: 100dvh` (a stable viewport height). Embedded →
+a **fixed height** (e.g. `600px`) or a **sized grid/flex CELL** that supplies one. **Never
+`min-height` and never `auto`** on the surface box — those grow with content and are the
+load-transition reflow. `100dvh` (dynamic viewport height) beats `100vh` on mobile (no jump
+when the URL bar hides).
+
+**(c) Size the columns/panes.** Sizing the root is NOT enough — the columns are the kit's
+actual parents and must resolve a height + a bounded width, or the kit fills content size
+and the surface crams into the top-left:
+```css
+.cc-app        { display: flex; height: 100dvh; width: 100%; overflow: hidden; }
+.cc-app .list-column  { width: 320px; flex-shrink: 0; height: 100%; }
+.cc-app .message-pane { flex: 1 1 0; min-width: 0; min-height: 0; height: 100%;
+                        display: flex; flex-direction: column; overflow: hidden; }
+```
+**`min-height: 0` + `min-width: 0`** are load-bearing: a flex child's default
+`min-height:auto` refuses to shrink below its content, so a long list/message GROWS the
+parent (reflow + overflow) instead of scrolling inside it. `min-height:0` lets the child
+**scroll, not grow the parent**; `min-width:0` + `overflow:hidden` stop horizontal spill.
+
+**Keep `CometChatProvider` OUT of the flex chain, and don't rely on `height:100%` in a flex
+chain (AUDIT-036).** `CometChatProvider` renders a `<div class="cometchat">` wrapper. Put it
+OUTSIDE the sized `.cc-app` (wrap the whole surface) — NOT between `.cc-app` and the columns:
+a wrapper there becomes an unsized block in the flex row, so the columns stop forming a row
+and the pane's height chain collapses (measured live: the message pane shrank to just its
+65px header). The `height:100%` in (c) above works ONLY because `.cc-app` is a fixed
+`100dvh` box (a definite height for `%` to resolve against). If you add an **app bar above
+the surface** so `.cc-app` becomes a flex *child* (`flex:1`) instead of a fixed `100dvh`
+box, its height is flex-derived/indefinite and `height:100%` on the columns collapses to
+content — drive heights through the flex chain instead: every level `display:flex` +
+`flex:1 1 0` + `min-height:0` (stretch, not `height:100%`), give the provider's `.cometchat`
+wrapper `flex:1 1 0; min-height:0; display:flex`, and flex the list vs composer explicitly
+(list `flex:1 1 0; min-height:0`, composer `flex:0 0 auto`).
+
+**(d) Render the kit's OWN loading state inside the pinned box — no load-transition
+reflow.** The surface must be **full-size BEFORE content loads, not grow into it.** Because
+(a)–(c) pin the box independently of content, the kit's built-in loading/empty state
+(`loadingView` / `emptyView` — the components ship them) renders as a **full-size
+skeleton**, and when real data arrives the loaded view swaps in **inside the same box with
+zero shift.** Do NOT gate the whole surface behind your own "is it loaded yet?" flag that
+mounts a small placeholder then a big chat — that IS the reflow. Mount the sized surface
+immediately; let each component show its own loading state in place.
+
+**(e) No `transform` / `filter` on ancestors.** A non-`none` `transform`, `filter`,
+`backdrop-filter`, `perspective`, or `will-change:transform` on any ancestor of the chat
+creates a containing block that clips the kit's `position:fixed` overlays (options menu,
+emoji picker, reactions, thread panel, call screen) — and Tailwind `translate-*`/`scale-*`/
+`rotate-*`/`transition-transform` all compile to `transform`. Animate `right`/`left`/width
+instead (anti-patterns #11). Also: don't let host global CSS (`text-align`/flex-centering/
+`flex`/a reset/Tailwind base) leak onto the `.cometchat` subtree — it mis-sizes kit
+internals; scope it away and customize via `--cometchat-*` vars + view slots (anti-patterns
+#12), never by overriding internal BEM classes.
+
+## The minimal full-page recipe (put it BEFORE the chat CSS)
+
+Assemble the three CSS blocks above in order — (a) prepare/RESET the ancestor chain FIRST,
+then (b) pin `.cc-app` to `100dvh`, then (c) size the columns with `min-height:0` (= scroll,
+don't grow). That exact stack (nothing more) is the full-page recipe.
+
+For the grown three-column app the same invariants hold with an extra `.side-column`
+(fixed-ish width, `height:100%`, `min-height:0`) — the full 3-column CSS is in
+`cometchat-react-v7-placement` (the Combined-app recipe), which references THIS standard for
+the invariants.
+
+## Embedded (not full-page)
+
+Opt out of `100dvh`, keep invariants (a),(c),(d),(e): give the surface box a **fixed
+height** (`height:600px`) or drop it into a **sized grid/flex cell** whose track supplies a
+resolved height (`grid-template-rows: 1fr` on a `100dvh` parent, or a flex parent with the
+region `flex:1; min-height:0`). Never a `min-height`/`auto` region — same reflow. See the
+`placement` embedded/popup/sidebar variants.
+
+## The invariant, per platform (this file is the WEB recipe)
+
+The PRINCIPLE is universal — every platform's UI Kit fills its container and must not
+reflow between loading and loaded, so every platform pins a content-independent box and
+lets the kit's own loading state fill it. The RECIPE differs:
+- **web (react/angular):** this file — `100dvh` + the prepared/reset ancestor chain + the
+  `min-height:0` columns + no `transform`/`filter` on ancestors + the kit's
+  `loadingView`/`emptyView` inside the pinned box.
+- **mobile (rn/flutter/native), when those packs exist:** the equivalent — flex-fill /
+  `Expanded`/`match_parent` to a stable screen size, safe-area insets, keyboard-avoidance
+  so the composer doesn't reflow the list, and the kit's own loading state inside the
+  pinned screen. Each platform's `core`/`placement` bakes its own `layout` recipe and
+  inherits the SAME contract (`prepared-ancestor-chain`, `pinned-viewport-height`,
+  `no-load-transition-reflow`, `column-min-height-0` — the web tokens; a platform renames
+  the mechanism, not the invariant). See the factory `RULES.md` "Layout / sizing" rule.
+
+## Verify (advisory, human check)
+
+Full-size from the FIRST frame (a full-height skeleton, not a small box that grows); no
+reflow when the conversation list finishes loading (the box doesn't change size); no ~0px
+collapse; no horizontal scrollbar at wide (1280) or narrow (720) widths
+(`scrollWidth > innerWidth` ⇒ broken); overlays (menus, emoji, thread, call) anchor to the
+viewport (no `transform`/`filter` ancestor). If it grows into place, an ancestor is
+content-driven — walk (a)→(c).