@cometchat/skills 4.4.2 → 5.0.1

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

@@ -0,0 +1,74 @@
+# lifecycle — init, login, provider (React v7)
+
+## Init must happen once (StrictMode double-init)
+Init is async and must complete before any `CometChat*` component renders. React 18 StrictMode runs effects twice in dev, so guard by caching the init **PROMISE — NOT a boolean**. A boolean set BEFORE `await init()` lets StrictMode's second call see `true` and return BEFORE init has actually resolved → the app renders / logs in against an un-initialized SDK and throws **"CometChatUIKit: Not initialized"** on first load (AUDIT-047). Cache the promise so every concurrent caller awaits the SAME init (mirrors the login in-flight promise below):
+```typescript
+// initFromSettings resolves to CometChat.User | null (a resumed session or null), so type the cached
+// promise as Promise<unknown> — assigning it into Promise<void> is a TS2322 error under strict TS.
+let initPromise: Promise<unknown> | null = null;
+function initCometChat(): Promise<unknown> {
+  if (!APP_ID || !REGION || !AUTH_KEY) throw new Error("CometChat credentials empty — check .env + prefix (VITE_/NEXT_PUBLIC_/PUBLIC_) and restart the dev server.");
+  if (!initPromise) {
+    // initFromSettings sets integrationSource="ai-agent" for telemetry attribution (routes the Calls SDK too) — AUDIT-084.
+    initPromise = CometChatUIKit.initFromSettings({   // cache the PROMISE (never a boolean flipped before the await)
+      appId: APP_ID, region: REGION,
+      credentials: { authKey: AUTH_KEY },                        // dev only — prod: server-minted auth token (login below)
+      chatSDK: { presenceSubscription: { type: "ALL_USERS" } },  // = subscribePresenceForAllUsers()
+    });
+  }
+  return initPromise;                              // 2nd StrictMode call awaits the SAME init → never early-returns before ready
+}
+```
+Call init in `useEffect` (Next.js/Astro/React Router SSR) or at the entry file before `createRoot` (Vite/CRA — `main.tsx` only runs in the browser). Never call init during render (infinite re-render).
+
+## Login — safe SEQUENTIALLY, not CONCURRENTLY
+Sequential: a second `login()` after the first completes returns the cached user. Concurrent: a second `login()` while the first is in-flight throws **"Please wait until the previous login request ends."** — exactly what StrictMode's double-effect triggers. Guard with a module-level in-flight promise:
+```typescript
+let loginInFlight: Promise<unknown> | null = null;
+async function ensureLoggedIn(uid: string, authToken?: string) {
+  const existing = CometChatUIKit.getLoggedInUser();   // SYNC getter, capital "In" — no await (see the note below)
+  if (existing && existing.getUid?.() === uid) return;         // same user → done
+  if (existing) await CometChatUIKit.logout();                 // switching accounts needs explicit logout
+  if (loginInFlight) { await loginInFlight; return; }          // concurrent → reuse pending promise
+  loginInFlight = authToken ? CometChatUIKit.loginWithAuthToken(authToken) : CometChatUIKit.login(uid);
+  try { await loginInFlight; } finally { loginInFlight = null; }
+}
+```
+Call `ensureLoggedIn()` from the provider/effect, not `login()` directly. A cached promise (not a boolean) lets all callers `await` the same request.
+
+## Dev-only: `ensureDevUser` — create-if-missing a sample user, then log in (a guaranteed valid session)
+For a fast dev start you can't reliably pre-check whether `cometchat-uid-1` exists (`getUser` needs a session, and you only have the Auth Key — not the REST key for a server-side lookup). So **create-if-missing then login** — one deterministic path, valid on any app (fresh/sample/empty/custom), no 5-way probe. **DEV-ONLY** — prod uses a real user + a server-minted token via `loginWithAuthToken`.
+```typescript
+import { CometChat } from "@cometchat/chat-sdk-javascript";   // for CometChat.User
+// CometChatUIKit.createUser(user) uses the Auth Key configured in init — verified vs 7.1.0.
+async function ensureDevUser(uid = "cometchat-uid-1", name = "Demo User") {
+  try {
+    const u = new CometChat.User(uid);
+    u.setName(name);
+    await CometChatUIKit.createUser(u);          // creates it if missing (dev; uses the init Auth Key)
+  } catch {
+    // already-exists is EXPECTED and fine — the user is there; fall through to login.
+  }
+  await ensureLoggedIn(uid);                      // now guaranteed to succeed
+}
+```
+
+## Get the current logged-in UID (never hardcode)
+```typescript
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+// preferred — sync, after login completes (most app code):
+const myUid = CometChatUIKit.getLoggedInUser()?.getUid();      // UI Kit, capital "In" → CometChat.User | null (sync)
+// fallback — async, when the SDK was initialized directly / session may still be restoring:
+const myUid2 = (await CometChat.getLoggedinUser())?.getUid();  // SDK namespace, lowercase "in" → Promise<CometChat.User | null>
+```
+> Two DIFFERENT methods on two DIFFERENT owners: the **sync** getter is `CometChatUIKit.getLogged**In**User()` (UI Kit, capital "In"); the **async** getter is `CometChat.getLogged**in**User()` (SDK namespace, lowercase "in"). `CometChatUIKit` has NO async `getLoggedinUser` — that was a v6 assumption. Verified against installed 7.1.0 (`index.d.ts` line 617 + the kit's own doc note).
+
+## Production login
+Fetch a per-user token from YOUR backend (CometChat REST API with your server AUTH_TOKEN), then `await CometChatUIKit.loginWithAuthToken(token)`. Never hardcode auth keys in shipped source.
+
+## Logout
+`await CometChatUIKit.logout();` — clears the local session; call on app sign-out.
+
+## Reusable provider
+Wrap init + login + ready-gate in a `CometChatProvider` so components mount only after login resolves; keep the module-level `initPromise`/`loginInFlight` promises (cache the PROMISE, not a boolean — AUDIT-047) so StrictMode doesn't double-fire or race ahead of a not-yet-resolved init. Mount the provider at a STABLE ancestor (not remounted per route/toggle) so init/login survive navigation. (Pretty-print errors — don't `String(error)` raw; surface the code/message.)

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

@@ -0,0 +1,58 @@
+# setup-credentials — detect, credentials, authorize (React v7)
+
+## 1. Detect project (package / config / framework)
+- Confirm `package.json` has `react`. Identify the bundler → env prefix:
+  - **Vite** → `.env`, `import.meta.env.VITE_*`
+  - **Create React App** → `.env`, `process.env.REACT_APP_*`
+  - **Next.js** → `.env.local`, `process.env.NEXT_PUBLIC_*`
+  - **Astro (React)** → `.env`, `import.meta.env.PUBLIC_*`
+  - **React Router (Vite)** → `.env`, `VITE_*`
+- Reuse existing config: a prior `.cometchat/config.json` or already-set `*_COMETCHAT_APP_ID` → reuse, skip re-setup, don't re-provision or re-ask.
+
+## 2. version_conflict — STOP gate
+If `@cometchat/chat-uikit-react` is installed at a non-v7 major (e.g. v6), STOP. Surface it, reconcile (upgrade to v7, or load the matching-version skills), then continue. Never mix majors.
+
+## 3. Credentials — fetch from the dashboard (offer it), or paste manually
+> **The CLI is a DASHBOARD/API client only, loaded ON DEMAND (AUDIT-059).** The `@cometchat/skills-cli` tool does exactly THREE things: `auth` (dashboard login), `provision` (fetch an app's App ID/Region/Auth Key from the dashboard), and `config` (local cred state). It knows NOTHING about React/frameworks/UI Kit and does NOT write env files, detect the project, or generate code — **the SKILL owns all of that** (detection = §1 by reading the repo; env-writing = §4; codegen = the golden path). Only load the CLI when the user opts into fetching from the dashboard.
+
+> **OFFER the dashboard fetch; don't default to manual paste (AUDIT-039).** When credentials are missing, present BOTH paths and default to the fetch: *"I can fetch your App ID / Region / Auth Key by logging into your CometChat dashboard (I'll load the CometChat CLI to do it), or you can paste them manually — which do you prefer?"* **Only if the user picks the fetch do you load/run the CLI** (below); a manual paste never touches the CLI. **Never silently skip to "paste them yourself," and never end the build with a "to finish, add credentials manually" TODO.**
+
+> **The CLI.** Load it on demand with **`npx @cometchat/skills-cli@3` `<cmd>`** (public npm — no auth needed; `@3` pins the CLI major that matches the v5 skills). Below, `<cli>` = that full invocation. (Distinct from `@cometchat/skills`, which only installs these skills.)
+
+**Fetch path (user opted in).** Let each command block — do NOT background or race them.
+1. **Check auth:** `<cli> auth status --json` → `logged-in` | `logged-out`.
+2. **Log in (if logged-out):** `<cli> auth login` — opens the dashboard in the browser (device-auth), polls, stores the bearer in the OS keychain. (`auth signup` for a brand-new account.) Surface terminal errors verbatim (`ACCESS_DENIED` / `EXPIRED` / `TIMEOUT` / `ABORTED`) and stop; don't retry silently.
+3. **Pick the app — REUSE first, ASK with CURATED options, never auto-create:** if a `.cometchat/config.json` or env App ID already exists, use it and SKIP. Otherwise `<cli> provision list --json` returns the raw list — **the SKILL curates it; never dump a long table.** Present a selectable prompt of ≤4 options: the **TOP 3** apps ranked by relevance (framework match, then most-recent; name · region · App ID) **+ "Show all N apps"**; the free-text/"Other" answer = **paste an App ID/name manually**. Only on "Show all" list them all. No selectable prompts → the same as a numbered list (1–3, 4=show all, 5=manual) and WAIT. **NEVER dump all N as the primary prompt** (the 29-apps-in-a-table regression). **NEVER auto-create an app** — only on explicit request, confirming the name; zero apps → ask first.
+4. **Fetch the credentials:** `<cli> provision use --app-id "<id>" --json` (or `provision run`) authenticates and returns `{ appId, region, authKey }` for that app **and writes a framework-neutral `.cometchat/config.json`** — it does NOT write any env file and takes NO `--framework` flag (that's the skill's job, §4). The Auth Key is returned so the skill can write it into the env; treat it as a secret (never echo it back to the user).
+5. **Reuse existing:** a prior `.cometchat/config.json` or an already-set `*_COMETCHAT_APP_ID` → reuse, skip re-provision.
+
+**Manual path** (user prefers, or the CLI can't run): Dashboard → Your App → Credentials → App ID, Region (`us`/`eu`/`in`), Auth Key (**dev only**). If neither path yields them, ASK and WAIT — never proceed with placeholders.
+
+**Then the SKILL writes the env** from the config.json / returned creds — §4 (right prefix for the detected bundler) — and gitignores it. The CLI stops at "here are your credentials + a neutral config.json."
+
+**Enable dashboard-gated features** (reactions, polls, translation, AI copilot, moderation, …) — the CLI does this (it's a dashboard/API op): `<cli> features list` shows the app's extensions + enabled state; `<cli> features enable <id>` / `disable <id>` flips the toggle via the management API (reads the App ID from `.cometchat/config.json`). Or do it manually in the **Dashboard** (Extensions / AI). Either way, YOU still wire the client component/prop (see `cometchat-react-v7-features`); the CLI only flips the dashboard toggle. Fetch current dashboard steps from the feature's `docs_topic`. (AUDIT-070 restored `features`.)
+
+Production: mint a per-user **auth token** from your backend and use `loginWithAuthToken` — never ship the Auth Key to the client. The token endpoint is host code the SKILL scaffolds (or follow CometChat's docs); it is not a CLI step.
+
+## 4. Env variables (three)
+| Suffix | Required | Notes |
+|---|---|---|
+| `COMETCHAT_APP_ID` | yes | dashboard App ID |
+| `COMETCHAT_REGION` | yes | `us` / `eu` / `in` |
+| `COMETCHAT_AUTH_KEY` | dev only | replace with auth tokens in prod |
+
+Prefix per bundler (Vite `VITE_`, CRA `REACT_APP_`, Next `NEXT_PUBLIC_`, Astro `PUBLIC_`). **The SKILL writes this env file** from the credentials (fetched into `.cometchat/config.json`, or pasted) — the CLI does not. **Then ENSURE the env file is gitignored (AUDIT-048): Vite/CRA scaffolds ignore only `*.local` (NOT `.env`), so an un-ignored `.env` with the Auth Key is a committable secret — verify/append `.env` to `.gitignore` for Vite/CRA/Astro; Next's `.env.local` is gitignored by default.** Restart the dev server after editing `.env`. Fail loud if any var is empty — an empty credential surfaces later as a cryptic `ERROR_API_KEY_NOT_FOUND`.
+
+## 5. Authorize / verify
+Credentials are valid when `CometChatUIKit.initFromSettings(settings)` resolves and `login()`/`loginWithAuthToken()` succeeds for a UID that exists in the app (see §6). Auth error on init/login → most commonly a **Region mismatch**; re-check the dashboard values. Do not render until login resolves.
+
+## 6. Which user to log in as (the login UID) — do NOT invent one
+`login(uid)` authenticates as a user that **must already exist** in your CometChat app; it does **not** create one. Never hardcode a guessed UID — even the current docs sample `cometchat-uid-1` is **not guaranteed to exist in this app**. Logging in as a missing UID fails (user-not-found) and the screen stays blank.
+- **Never suggest a legacy/guessed sample UID.** Do **NOT** offer `superhero1` (or `superhero1..5`, `cc-user-*`, or any other remembered "classic sample" set) — those are NOT seeded in modern apps and only mislead the user. When you ASK, do not fabricate candidate UIDs from memory. The ONLY tentative suggestion allowed is `cometchat-uid-1..5`, and only labelled *"if this is a freshly-created app"* — never presented as a known-good login for THIS app.
+- **Use a real UID:** Dashboard → your app → **Users** tab lists every UID. A freshly created / sample app is pre-seeded with sample users (`cometchat-uid-1`…`cometchat-uid-5`). ASK the user; prefer their own answer over any suggestion.
+- **The login-UID prompt is DETERMINISTIC — ALWAYS present these SELECTABLE options, in this order (AUDIT-068/069):**
+  1. **`cometchat-uid-1` — create-if-missing then login** *(dev, recommended for a fast start)*. Wire login as **create-if-missing then login** (`ensureDevUser` in `lifecycle.md`) so it's GUARANTEED valid on ANY app (fresh/sample/empty/custom). Don't "probe uid-1→uid-5": you can't check existence before login (`getUser` needs a session; we only hold the Auth Key), so probing = up to 5 login attempts — create-if-missing is ONE deterministic call. DEV-ONLY (prod → server-minted per-user tokens).
+  2. **Paste your own UID** — for a real/custom app with existing users (Dashboard → Users); the free-text / "Other" answer. **No user is created** on this path.
+  > This is a SKILL prompt (login-UID is the skill's job) — the CLI has no part in it. Keep it consistent run-to-run: option 1 (`cometchat-uid-1`, create-if-missing) must ALWAYS be present. Never suggest `superhero1`/legacy sample UIDs.
+- **Create one (dev):** Dashboard → Users → **Add User** (set a UID, e.g. `alice`), then `login("alice")`. Programmatic creation (SDK `createUser` client-side, or the REST `POST /v3/users` with the REST API Key server-side) — fetch the exact signature/endpoint from docs; never ship the Auth Key to a client.
+- **Production:** don't hardcode a sample UID. Per real end-user, create a matching CometChat user server-side (REST API + API key, using your own id as the UID), then log in with a per-user **auth token** from your backend → `loginWithAuthToken(token)` (§3).

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

@@ -0,0 +1,11 @@
+# ssr — server-side rendering safety (React v7)
+
+All UI Kit components are browser-only (they touch `window`/`document` on import). Rendering them on the server crashes. Prevent per framework:
+
+- **Next.js App Router:** `dynamic(() => import("./ChatView"), { ssr: false })` is **NOT allowed in a Server Component** (App Router build error: *"ssr: false is not allowed with next/dynamic in Server Components"*). Put the `dynamic(...)` call inside a `"use client"` module — e.g. a small `"use client"` wrapper that does the `dynamic(..., { ssr: false })` and renders it, then import that wrapper from your server page/layout. (The chat file itself must also be `"use client"`.)
+- **Next.js Pages Router:** `dynamic(() => import("../components/CometChatNoSSR"), { ssr: false })`.
+- **Astro:** `<ChatPanel client:only="react" />` — prevents render during static build.
+- **React Router v7 (SSR):** `React.lazy()` + `Suspense`, gated on a mounted flag (`useEffect(() => setMounted(true), [])`; `if (!mounted) return null`).
+- **Vite / CRA:** no SSR — import and use directly.
+
+Detail belongs to `cometchat-react-v7-patterns` (framework glue); this is the core-level safety summary.

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

@@ -0,0 +1,52 @@
+# theming — CSS at the core level (React v7)
+
+Import the UI Kit CSS ONCE at the app root; theme via `--cometchat-*` variables. v7 also supports a `theme` prop on `CometChatProvider` and a `useTheme` hook with `light`/`dark` + `data-theme`.
+
+```tsx
+// import once at the highest level (main.tsx / app/layout.tsx / global css)
+import "@cometchat/chat-uikit-react/styles";   // v7.1.0 CSS entry (package exports "./styles" -> dist/index.css)
+```
+The CSS-only `./styles` export has no type declaration, so on TypeScript 6 (`noUncheckedSideEffectImports` defaults ON — it's not a `strict` thing; opt-in on 5.6–5.9) that import errors with **TS2882 "Cannot find module or type declarations for side-effect import of '@cometchat/chat-uikit-react/styles'."** (verified vs TS 6.0.3). Ship this ambient declaration as a REAL file the app can copy — `src/cometchat.d.ts` (any `.d.ts` picked up by `tsconfig` `include`) — so the import type-checks (AUDIT-013):
+```typescript
+// src/cometchat.d.ts — lets TS accept the CSS-only "./styles" side-effect import (TS2882 otherwise)
+declare module "@cometchat/chat-uikit-react/styles";
+```
+```css
+/* theme-INDEPENDENT tokens (identical in light & dark) may sit on the bare class */
+.cometchat { --cometchat-font-family: "Inter", sans-serif; }
+/* theme-DEPENDENT tokens (every colour) MUST be scoped to the data-theme ATTRIBUTE,
+   NOT the bare `.cometchat` class — see the gotcha below. */
+.cometchat[data-theme="light"] { --cometchat-primary-color: #6851d6; }
+.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
+```
+- **Scope colour tokens to `data-theme`, not bare `.cometchat` (AUDIT-033).** The provider renders `<div data-theme="light|dark" class="cometchat">`, but several components (verified: `CometChatSearch`; also popovers/portaled surfaces) render their OWN nested `<div class="cometchat …">` **with NO `data-theme`**. A colour token on the bare `.cometchat` class therefore ALSO matches that nested wrapper and **re-pins the light value on its subtree** — so in dark mode the search (etc.) stays light while everything else goes dark. Put per-theme colours on `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]`: the nested wrapper matches neither and simply **inherits** the provider's theme. Use `.cometchat[data-theme="dark"]` (the SAME element) — NOT `[data-theme="dark"] .cometchat` (a descendant that matches nothing → silent no-op). To retint a kit internal per theme, use `[data-theme="dark"] .cometchat-<bem>` (the kit's own convention). Depth: `cometchat-react-v7-customization`.
+- Never target internal class names (e.g. `.cometchat-message-bubble__wrapper`) — not public API, changes between versions. Use `--cometchat-*` variables (or documented BEM classes for per-component scoping).
+- Import overrides AFTER the kit CSS.
+- **Per-surface background tokens.** Some surfaces paint an opaque background from their OWN token, so a wrapper background can't reach them — override that surface's token instead. Two common ones (verified vs 7.1.0): the message list paints `--cometchat-message-list-bg` (default `-03`, `dist/index.css:4243`) and the thread header paints `--cometchat-thread-header-background` (falls back to `-01`, `dist/index.css:12727`; not set in `:root`, so setting it directly is the clean way to tint the thread header specifically). Differentiating the thread panel from the main list uses exactly this — see the thread recipe in `cometchat-react-v7-customization` (message-list-bg is the required step; thread-header-background is an optional header-only tint).
+
+## Follow the system (OS) light/dark theme (recommended default)
+The `theme` prop is `"light" | "dark"` and **defaults to `light`** — the UI Kit does **NOT** read the OS `prefers-color-scheme` and there is **no `theme="system"`** (AUDIT-004). For a fresh integration, sync the theme to the OS by default (least surprise) with a small SSR-guarded hook, and pass it to `CometChatProvider`:
+
+```tsx
+import { useEffect, useState } from "react";
+import { CometChatProvider } from "@cometchat/chat-uikit-react";
+
+function useSystemTheme(): "light" | "dark" {
+  const read = () =>
+    typeof window !== "undefined" &&
+    window.matchMedia?.("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  const [theme, setTheme] = useState<"light" | "dark">(read);   // SSR: renders "light", corrects on hydrate
+  useEffect(() => {
+    const mq = window.matchMedia("(prefers-color-scheme: dark)");
+    const onChange = () => setTheme(mq.matches ? "dark" : "light");
+    mq.addEventListener("change", onChange);                    // live-updates when the OS theme flips
+    return () => mq.removeEventListener("change", onChange);
+  }, []);
+  return theme;
+}
+
+// <CometChatProvider theme={useSystemTheme()}> … </CometChatProvider>
+```
+For an explicit user toggle instead of OS-follow, use `useTheme()` (`{ theme, setTheme }`). Next.js/SSR: `window.matchMedia` must stay guarded — see `references/ssr.md`.
+
+Full theming depth (token list, per-component BEM, dark mode switching): `cometchat-react-v7-customization`.

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

@@ -0,0 +1,84 @@
+---
+name: cometchat-react-v7-customization
+description: "Theme and brand the React v7 UI Kit — light/dark mode, CSS custom-property design tokens, per-component style overrides. Triggers: 'change chat colors', 'dark mode chat', 'match my brand', 'customize cometchat theme', 'override message list styles'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react customization theming css-variables v7"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. Theming mechanism below is from the live v7 theming docs (see core `references/docs-map.md` → `/ui-kit/react/theming`). Status: **catalog-verified vs installed 7.1.0 (exports-only web-v7.json).** Fetch the full `--cometchat-*` token list from the theming **`.md` twin** (`{DOCS_BASE}/ui-kit/react/theming.md`, via `docs-map.md`) — do NOT bake it.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, provider, `init→login→render`. This skill ASSUMES it.
+
+## Use this skill when
+Branding/theming: colors, fonts, light/dark mode, or per-component style overrides.
+
+## Prerequisites & install
+Covered by core. No new package.
+
+## Customization mechanism (BAKED — v7)
+- **Design tokens = CSS custom properties**, all prefixed `--cometchat-*`, scoped to the `.cometchat` wrapper.
+- **Light/dark:** built-in `light` (default) and `dark`, selected via the `theme` prop on `CometChatProvider` and the `data-theme` attribute on the wrapper. Runtime switching via the `useTheme` hook.
+- **Follow the OS theme:** the `theme` prop is `"light" | "dark"` only and defaults to `light` — there is **no `theme="system"`** and the kit does NOT read `prefers-color-scheme` (AUDIT-004). To follow the system light/dark setting, sync the `theme` prop to `window.matchMedia("(prefers-color-scheme: dark)")` (with a `change` listener, SSR-guarded). Recommended as the default for a fresh integration. Full recipe: `cometchat-react-v7-core/references/theming.md`.
+- **Import order:** import your overrides AFTER the UI Kit styles (import UI Kit CSS ONCE at root).
+
+```tsx
+import { CometChatProvider, useTheme } from "@cometchat/chat-uikit-react";
+import "./cometchat-overrides.css";   // AFTER the kit styles
+
+<CometChatProvider theme="dark"><>{/* your chat UI */}</></CometChatProvider>
+```
+```css
+.cometchat { --cometchat-font-family: "Inter", sans-serif; }             /* theme-INDEPENDENT tokens only */
+.cometchat[data-theme="light"] { --cometchat-primary-color: #e91e63; }   /* per-theme COLOURS → data-theme attr */
+.cometchat[data-theme="dark"]  { --cometchat-primary-color: #bb86fc; }
+.cometchat-message-list { /* BEM class to scope tokens per component */ }
+```
+> **Per-theme COLOURS go on the `data-theme` element — NOT the bare `.cometchat` class (AUDIT-033).** `CometChatProvider` renders one wrapper `<div data-theme="light|dark" class="cometchat">` (compiled bundle: `jsx("div",{ "data-theme": internalTheme, className: "cometchat" })`), and the kit defines its tokens on `[data-theme=light]` / `[data-theme=dark]`. **But several components render their OWN nested `<div class="cometchat …">` with NO `data-theme`** — verified for `CometChatSearch` (also popovers / portaled surfaces). So a colour on the bare `.cometchat` class ALSO lands on that nested wrapper and **re-pins the base (light) value there**: in dark mode the search stays light while everything else goes dark. Scope per-theme colours to `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]` so the nested wrapper matches neither and **inherits** the provider's theme. Keep only theme-independent tokens (font-family, radii) on bare `.cometchat`. (Earlier docs claimed `[data-theme="dark"] .cometchat` matches nothing — that's wrong: it DOES match those nested wrappers. It's still not the right selector for brand tokens; use the `.cometchat[data-theme]` form above.) To retint a kit INTERNAL per theme, use the kit's own pattern — `[data-theme="dark"] .cometchat-message-list { … }`.
+
+## What's swappable
+- Global tokens on `.cometchat` (primary color, fonts, radii, spacing — fetch the full token names from the theming `.md` twin).
+- Per-theme overrides via `[data-theme="..."]`.
+- Per-component scoping via BEM classes (`.cometchat-conversations`, `.cometchat-message-list`, …).
+- Exact token names/defaults: fetch the theming `.md` twin (`{DOCS_BASE}/ui-kit/react/theming.md`, via core `references/docs-map.md`) — do NOT bake the token table.
+
+### Differentiating a nested surface — an opaque sub-surface needs its OWN var override (BAKED — verified vs 7.1.0)
+**Rule (general).** A kit sub-surface that paints an OPAQUE background does NOT inherit a wrapper's background — its own opaque paint covers whatever the wrapper set. To differentiate a nested surface you MUST override THAT surface's own background CSS variable (scoped on an ancestor — it cascades into the variable, no internal-class override needed), not just set a background on the wrapper.
+
+**The thread panel is the canonical case.** Verified in the 7.1.0 CSS: `.cometchat-message-list` paints `background: var(--cometchat-message-list-bg)` (default `var(--cometchat-background-color-03)`); `.cometchat-thread-header` and `.cometchat-message-composer` paint their own opaque `var(--cometchat-background-color-01)`. So the thread's message list renders `-03` — the SAME shade as the main list, and different from its own header/composer — and a background on the thread wrapper alone can't fix it (the list covers it). **Override the list's own token on the thread wrapper:**
+```css
+/* the div you wrap CometChatThreadHeader + thread CometChatMessageList + CometChatMessageComposer in */
+.cc-thread-panel {
+  --cometchat-message-list-bg: var(--cometchat-background-color-01); /* matches the thread header/composer; differs from the main list's -03 */
+  border-left: 1px solid var(--cometchat-border-color-default, #e8e8e8); /* optional divider from the main pane (-default = neutral-300 = #e8e8e8 light / #383838 dark) */
+}
+```
+`--cometchat-background-color-01` is `#ffffff` (light) / `#141414` (dark) and `-03` is `#f5f5f5` (light) / `#272727` (dark) — so the override visibly separates the thread list from the main list in BOTH themes while matching the thread header/composer. Same trick for any per-surface background: scope the surface's OWN token on the wrapper, never override the kit's internal `.cometchat-*` element classes (`core/references/anti-patterns.md` #7/#12/#16).
+
+> **Tinting the thread HEADER specifically — use its dedicated token.** `.cometchat-thread-header` paints `background: var(--cometchat-thread-header-background, var(--cometchat-background-color-01, #fff))` (verified vs 7.1.0 — `dist/index.css:12727`; the token is NOT defined in `:root`, only referenced with that fallback chain). So if you want to give the thread HEADER its own tint (a different shade from the list/composer, e.g. a subtly darker panel header), set `--cometchat-thread-header-background` directly on the thread wrapper — cleaner and more targeted than leaning on the `-01` fallback:
+> ```css
+> .cc-thread-panel {
+>   --cometchat-message-list-bg: var(--cometchat-background-color-01);  /* REQUIRED — repaints the thread LIST (opaque, covers the wrapper) */
+>   --cometchat-thread-header-background: var(--cometchat-background-color-02);  /* OPTIONAL — tints ONLY the thread header, independent of the list */
+> }
+> ```
+> The `--cometchat-message-list-bg` override above is still **required** — the header token only paints the header; it does not touch the opaque message list. Use `--cometchat-thread-header-background` only when you want the header a *different* shade from the list; if you want them to match, the header already inherits `-01` and needs no override.
+
+## Structural customization — view slots & composition (beyond tokens)
+Theming changes how it LOOKS (tokens); changing WHAT renders is **view slots** + composition, not CSS. Every list/message component exposes view-slot props to inject custom UI **IN** the component (never as a sibling on top): e.g. Conversations `headerView` / `searchView`; MessageHeader `trailingView` / `auxiliaryButtonView`; MessageList `headerView` / `footerView`; Composer `auxiliaryButtonView` / `headerView`. Baked slot map: `cometchat-react-v7-core/references/component-props.md`. For the exhaustive per-component slot list, fetch the component's `.md` twin (`core/references/docs-map.md`) — do NOT read `.d.ts`. (Custom message **bubbles** are a separate capability — the message **plugin** architecture; see `cometchat-react-v7-features` + `COVERAGE.md`.)
+
+## Common pitfalls (BAKED)
+- Importing UI Kit CSS more than once, or overrides BEFORE the kit styles (specificity lost). Hardcoding hex in components instead of tokens. Assuming v6 theme classes — v7 uses `--cometchat-*` tokens + `data-theme`; fetch current names.
+- **Writing a per-theme override as `[data-theme="dark"] .cometchat { … }` — it matches NOTHING and silently no-ops.** The provider puts `data-theme` and `class="cometchat"` on the SAME div, so there is no `.cometchat` nested inside a `[data-theme]` ancestor. Use `.cometchat[data-theme="dark"]` (same element) for brand tokens, or `[data-theme="dark"] .cometchat-<bem>` (ancestor + kit-internal descendant, the kit's own pattern) to retint an internal. (Verified vs 7.1.0.)
+- **Hand-write brand/per-theme overrides — do NOT put per-theme tokens (colors, background, font) on bare `:root` (AUDIT-049/057).** A background or font pinned on `:root` has LOWER specificity than the kit's own `.cometchat[data-theme]` tokens, so it either loses (font silently doesn't apply) or forces the light value even in dark mode (breaks the OS-follow default, AUDIT-004/033). Scope every per-theme token to `.cometchat[data-theme="light"]` / `.cometchat[data-theme="dark"]` (theme-independent tokens like radii can stay on bare `.cometchat`). Theming is the SKILL's job — hand-write the scoped CSS (there is no CLI codegen for it).
+- **Setting a background on a WRAPPER to differentiate a nested surface, and expecting it to show.** An opaque kit sub-surface (the message list paints its own `--cometchat-message-list-bg`) covers the wrapper background — the wrapper bg only shows through non-opaque children. To differentiate the sub-surface, override THAT surface's own token (above), never the wrapper alone and never its internal `.cometchat-*` class. This is why the thread message-list keeps looking undifferentiated from the main list even after a thread-wrapper background is set (AUDIT-020/024).
+- **Assuming the kit follows the OS theme — it doesn't.** `theme` defaults to `light` and there's no `theme="system"`; a plain integration ignores the user's OS dark-mode setting. Sync to `prefers-color-scheme` if OS-follow is wanted (AUDIT-004).
+
+## Verify it works
+Your theme / `--cometchat-*` overrides apply in the running app (colors, light/dark), and the kit CSS is imported once at the app root.
+
+**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** (further tweaks) · **③ test it manually** (stop; let the user check). Tailor suggestions to what's not yet done. Same contract as the `cometchat-react-v7-core` close (`RULES.md` §19).

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

@@ -0,0 +1,92 @@
+---
+name: cometchat-react-v7-features
+description: "Enable a specific CometChat feature in a React v7 app — reactions, polls, stickers, mentions, translation, link preview, smart replies and other AI, calls, push notifications, moderation. Looks the feature up in the features.json oracle, then wires enablement. Triggers: 'add reactions', 'enable polls', 'turn on smart replies', 'enable message translation', 'add voice/video calling'."
+license: "MIT"
+compatibility: "React >=18; @cometchat/chat-uikit-react ^7 (7.1.x, verified 7.1.0)"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react features extensions ai calls push moderation v7"
+---
+
+> **Ground truth:** the feature existence oracle is `features.json` (pack root). A feature a user asks for MUST be an `id` there — if it's not listed, it does not exist; do not invent it. Exact enablement steps + current dashboard nav + config keys: FETCH from the feature's `docs_topic` (docs flag dashboard paths as fragile). UI component names come from the `web-v7` catalog. Status: **oracle curated from live docs 2026-07-29; entries marked VERIFY need confirming before shipping enablement steps.**
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — install, credentials, `init→login→render`, provider. This skill ASSUMES it.
+- `cometchat-react-v7-components` — the component catalog features render through.
+
+## Use this skill when
+The user wants to turn ON a specific capability: "add reactions", "enable polls", "turn on smart replies", "add push notifications", "enable message translation", "add calling", "add moderation".
+
+## Prerequisites & install
+Core setup done (credentials + init/login). Most features add no package; `voice-video-calls` needs the separate calls package.
+
+## Enable a feature (BODY — the oracle-driven flow)
+1. **Look it up in `features.json`.** Match the request to a feature `id`. Not listed → tell the user it isn't an available feature (don't invent one).
+2. **Branch on `category` + `enablement`:**
+   - `default` / `auto` → the SDK-side capability is on, but **check `needs_stitching` first**. If `needs_stitching: true`, the drop-in renders a default-ON affordance that is INERT/partial until the host wires it — you MUST either stitch it (callback + companion panel/component) or hide it; never leave it dead-ending (see the "Default-on affordances" pitfall). Otherwise nothing to enable — point at the `ui_components` if they want to surface/customize it.
+   - `extension` + `dashboard-extension` → enable the extension, then wire the client. **Two ways to enable: (a) via the CLI — `npx @cometchat/skills-cli@3 features enable <id>` flips the dashboard toggle via the API (reads the App ID from `.cometchat/config.json`; `features list` shows current state); OR (b) manually in the CometChat Dashboard → Extensions.** Offer the CLI (faster), fall back to the dashboard. The CLI only flips the toggle — YOU still wire the client component/prop. FETCH the current dashboard steps from `docs_topic` — do not bake the path.
+   - `ai` → enable via **dashboard-toggle** (AI User Copilot) AND wire the code prop — NOT zero-code (AUDIT-009). The toggle can be flipped by the CLI too — `@cometchat/skills-cli@3 features enable <id>` (an AI feature may first need an OpenAI key set on the app; the CLI reports that). Then wire the props: The copilot props DEFAULT TO OFF, so nothing appears until you set them: smart-reply → `showSmartReplies` on `CometChatMessageList` (default false; renders in the list FOOTER, not the composer); conversation-starter → `showConversationStarters` on `CometChatMessageList` (default false); conversation-summary → `showConversationSummaryButton` + `onSummaryClick` on `CometChatMessageHeader` (default false). These are `needs_stitching:true`. Only `ai-assistant` renders a distinct component (`CometChatAIAssistantChat`). Plan-gating is often 'unknown' — verify, don't assert.
+   - `package-install` (calls) → install the separate calls package (FETCH the exact coordinate/version from `docs_topic`), then wire the `ui_components`.
+   - **No UI Kit component (SDK-backed feature)** → the capability exists in the SDK but the UI Kit ships NO component for it (AI agents, campaigns, advanced/AI moderation, bots, webhooks, transient messages). Wire it from the **JavaScript Chat SDK** directly — look the exact method up in `cometchat-react-v7-core/references/docs-map.md` → **SDK docs** (the `llms.txt` index → the feature's page → its **AI-Integration-Quick-Reference accordion** for the method signatures; e.g. AI agents → `CometChat.addAIAssistantListener(...)`). This is the UI-Kit-first / SDK-fallback rule (`RULES.md`) — don't skip the feature and don't hand-roll what the SDK already exposes.
+   - `dashboard-only` (moderation) → configured ENTIRELY in the dashboard; emit **ZERO moderation UI code (AUDIT-078)**. Its `ui_components` (`CometChatModerationView` / `CometChatFlagMessageDialog`) are **AUTO-RENDERED / INTERNAL**, NOT host-wired: the kit auto-shows the moderation **footer** for blocked/pending messages (`CometChatMessageList hideModerationView` defaults false = shown), and the message list already ships a **built-in "Report message" option** that opens the flag dialog internally. So do **NOT** hand-roll a custom Report option (plugin `getOptions`) and do **NOT** mount `CometChatFlagMessageDialog` yourself — that duplicates the built-in. The only work is in the **Dashboard**: set up the Rules Engine (auto block/flag on send) + turn ON **Report Message / Report User**; the kit then surfaces everything with no code. (Rules Engine is not a classic extension → the CLI can't toggle it; give the user the dashboard steps.)
+3. **Wire the UI** using only the feature's `ui_components` (they exist in the `web-v7` catalog); fetch exact props from each component's `.md` twin (`cometchat-react-v7-core/references/docs-map.md`). **If the feature is a whole TASK with an end-to-end guide (check the docs-map "Task guides (recipes)" section — e.g. group chat, search, threads, new-chat, message-privately, block/unblock), BUILD FROM the guide and COMPARE your implementation against it for completeness — then apply the hardening deltas on top (docs-maximal; docs-map). No matching guide? → wire the `ui_components` the normal way (above) + fetch props; the guide is an enhancement, not required.**
+4. **Respect VERIFY notes** — any entry noting VERIFY (or an `ai`/`e2e-encryption`/`moderation` entry) must be confirmed against live docs for plan-gating and exact slugs before you emit steps.
+
+## Advanced / extensibility recipes (curated — verified against installed 7.1.x types)
+
+### Custom message types → the message-plugin architecture
+v7 replaces v6's `CometChatMessageTemplate` with **plugins**. A custom message type is an object implementing `CometChatMessagePlugin` (`id`, `messageTypes`, `messageCategories`, `renderBubble`), registered on the provider. The `plugins` prop is MERGED with `defaultPlugins` internally — pass ONLY your extras; use `removePlugins` to override a built-in type.
+```tsx
+import { CometChatProvider } from "@cometchat/chat-uikit-react";
+import type { CometChatMessagePlugin } from "@cometchat/chat-uikit-react";
+
+const productCardPlugin: CometChatMessagePlugin = {
+  id: "product-card",
+  messageTypes: ["product_card"],      // your custom SDK message type
+  messageCategories: ["custom"],
+  renderBubble: (message) => <div className="product-card">{message.getSender().getName()}</div>,
+};
+
+<CometChatProvider plugins={[productCardPlugin]}>
+  <div>{/* your chat UI */}</div>
+</CometChatProvider>
+```
+> `CometChatProvider` REQUIRES `children`. Optional plugin-interface hooks: `getOptions`, `getLastMessagePreview`, `renderHeaderView`/`renderFooterView`, `getTextFormatters`. This is provider-level config — there's no standalone screen to render.
+
+### Text formatters / rich text
+The default text plugin already applies **@mentions, URLs, and markdown**. Add CUSTOM formatting by subclassing the abstract `CometChatTextFormatter` (`id` + `getRegex()` + `format()`) and passing it via the `textFormatters` prop on `CometChatMessageComposer` (input) and the bubble components — it is **NOT** a prop on `CometChatMessageList`. The built-in formatters (`CometChatMentionsFormatter`, `CometChatUrlFormatter`, `CometChatMarkdownFormatter`, `CometChatRichTextFormatter`) have **no-arg constructors**.
+```tsx
+import { CometChatMessageComposer, CometChatTextFormatter } from "@cometchat/chat-uikit-react";
+
+class HashtagFormatter extends CometChatTextFormatter {
+  readonly id = "hashtag-formatter";
+  getRegex() { return /#(\w+)/g; }
+  format(text: string) { return text.replace(this.getRegex(), '<span class="hashtag">#$1</span>'); }
+}
+
+<CometChatMessageComposer textFormatters={[new HashtagFormatter()]} />
+```
+> **The message LIST ignores these props** — its text bubbles use the text plugin's `getTextFormatters()` (default markdown + mentions + URL). To format hashtags in the list too, override that method via the provider: `plugins={[{ ...CometChatTextPlugin, getTextFormatters: () => [new CometChatMarkdownFormatter(), new CometChatMentionsFormatter(), new CometChatUrlFormatter(), new HashtagFormatter()] }]}` (provider plugins precede the defaults, so it wins; verified vs 7.1.0).
+> **RTE toolbar ≠ `textFormatters` (AUDIT-051).** The **rich-text editor TOOLBAR** (bold/italic/underline/lists/links buttons in the composer) is a SEPARATE feature: toggle it with the `enableRichTextEditor` PROP on `CometChatMessageComposer` — `<CometChatMessageComposer enableRichTextEditor />` — a prop, NOT a component swap. (There is **no** `CometChatCompactMessageComposer` in v7 — that was a v6 phantom.) `textFormatters` above is for CUSTOM inline formatters (hashtags, @mentions, custom markup); they're orthogonal and can be used together. (There is no CLI shortcut — the skill sets the `enableRichTextEditor` prop directly.)
+
+### Calls / push operational depth
+**Calls now has its own skill — `cometchat-react-v7-calls`.** For "add voice/video calling", route there: it bakes the install (`@cometchat/calls-sdk-javascript@5`, not bundled), the calling-on switch (`uiKit:{callsSDK:{}}` on `CometChatUIKit.initFromSettings` — the `initFromSettings` equivalent of the classic `setCallingEnabled(true)`), the root `CometChatIncomingCall` wiring, 1:1-rings-vs-group-joins, and the gotchas (idle-timeout in **ms**, zero-dimension call surface, Next.js SSR + webpack fallback, no group-ring, HTTPS/`getUserMedia`).
+**Push notifications → the `cometchat-react-v7-push` skill** (thin + docs-first: it fetches CometChat's notifications docs and bakes the hardening deltas + SDK symbols). Route "add push" there — do NOT re-derive push here (single source).
+
+## Common pitfalls (BAKED)
+- **Default-on affordances that need stitching** (`features.json` `needs_stitching: true`). Some drop-ins render a live-looking control BY DEFAULT that no-ops until the host wires it — do NOT treat these as "already on, nothing to do":
+  - `CometChatConversations` search bar (`showSearchBar` default `true`) only client-side-filters already-loaded conversation names — it is NOT real search. Wire `onSearchBarClicked` → open `CometChatSearch`, or hide it with `showSearchBar={false}`. (Real search may also need a Dashboard toggle — VERIFY.)
+  - `CometChatMessageList` thread-reply indicator / "Reply in Thread" no-ops until `onThreadRepliesClick` opens a thread panel (`CometChatThreadHeader` + `CometChatMessageList parentMessageId` + `CometChatMessageComposer parentMessageId`) — wire it or hide with `hideReplyInThreadOption`.
+  - Rule: never emit a default-on affordance that dead-ends. Either wire the destination or hide the trigger.
+- Emitting a feature/component below its `contracts.json` minimum (e.g. group details without ban/kick/scope) — always cover the full min_capabilities (deterministic minimum, same every prompt).
+- Claiming a feature that isn't in `features.json` (phantom feature) — the #1 hallucination here.
+- Emitting a baked dashboard nav path — it rots; FETCH it.
+- Rendering a feature's UI component without enabling its extension first (renders empty/no-ops).
+- **Hand-rolling moderation UI (AUDIT-078).** Moderation is dashboard-only AND auto-surfaced: the kit renders the moderation footer for blocked/pending messages and the message list already ships a built-in "Report message" option (which opens the flag dialog internally). Do NOT add a custom Report option (plugin `getOptions`) or mount `CometChatModerationView`/`CometChatFlagMessageDialog` yourself — that duplicates the built-in. Emit ZERO moderation UI code; the only work is the Dashboard Rules Engine + Report Message/User toggles.
+- Assuming an AI/E2EE feature is available on every plan — it's plan-gated; verify.
+
+## Verify it works
+The enabled feature actually works in the running app (reactions appear, a poll sends, smart replies show, etc.) and any Dashboard toggle it needs is ON. If it renders empty, the extension/feature likely isn't enabled in the CometChat Dashboard.
+
+**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).

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

@@ -0,0 +1,39 @@
+---
+name: cometchat-react-v7-migration
+description: "Upgrade a React app from CometChat UI Kit v6 → v7 (`@cometchat/chat-uikit-react` ^6 → ^7). Reads the repo's CometChat usage, applies the breaking-change map (deps, symbol renames, RxJS events → `useCometChatEvents`, DataSource → plugins, templates → plugins, theme prop, calling), fetches the prop-by-prop guide, and verifies the build. Triggers: 'upgrade my v6 uikit to v7', 'migrate cometchat react v6 to v7', 'upgrade @cometchat/chat-uikit-react to v7', 'cometchat v6 to v7', 'bump cometchat uikit'."
+license: "MIT"
+compatibility: "React >=18 <21; FROM @cometchat/chat-uikit-react ^6 → ^7 (7.1.x, verified 7.1.0); @cometchat/chat-sdk-javascript ^4.1.13 (peer); dompurify ^3.3.1 required (install explicitly); rxjs removed"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react migration upgrade v6 v7 uikit"
+---
+
+> **Ground truth:** migrates a React app **FROM `@cometchat/chat-uikit-react@6` TO `@7`**. v7 target symbols are catalog-verified vs installed 7.1.0; the v6→v7 breaking-change map is BAKED in `references/migration-guide.md` (distilled from the official migration docs + a real v6.5.4→v7.1.0 export diff). The exhaustive prop-by-prop table is FETCHED from the docs migration `.md` twins. **APPEND/transform the user's code — never wipe it; work on a branch and confirm before bulk edits** (`RULES.md`).
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — the v7 init/login/render + `CometChatProvider` the migrated app lands on. This skill ASSUMES it.
+- `cometchat-react-v7-components` — the v7 component catalog (the target names).
+
+## Use this skill when
+"upgrade my v6 UI Kit to v7", "migrate CometChat React v6→v7", "bump `@cometchat/chat-uikit-react` to v7". Precondition: the project currently has `@cometchat/chat-uikit-react@6`.
+
+## Migration workflow (BAKED)
+1. **Detect the starting point.** Confirm `package.json` has `@cometchat/chat-uikit-react@6` (already `@7` → STOP, nothing to migrate). Note the bundler (Vite/Next/CRA/React-Router/Astro → env prefix, per `cometchat-react-v7-patterns`) and whether the app uses calls / `rxjs` events / `DataSource` / message templates. **Work on a branch; transform in place, never delete the user's code.**
+2. **Update dependencies.** `npm install @cometchat/chat-uikit-react@7 @cometchat/chat-sdk-javascript@^4.1.13 dompurify@^3.3.1` then `npm uninstall rxjs` (v7 drops rxjs; **`dompurify` is required** — the kit imports it at runtime; install it explicitly per the official docs, even though it's in the kit's `dependencies`). If the app uses calling, bump the Calls SDK to the v7 major: `npm install @cometchat/calls-sdk-javascript@5` (v7 pins `^5.x` — verified; it is NOT the same major as the v6-era build). Enabling calling also moves: on the mandated `initFromSettings` path use `uiKit:{callsSDK:{}}` (not the classic `setCallingEnabled(true)`).
+3. **Scan the repo for v6 usage.** Grep for the removed/renamed symbols + patterns from `references/migration-guide.md`: `CometChatDocumentBubble`, `CometChatCompactMessageComposer`, `CometChatUrlsFormatter`, `CometChatTextHighlightFormatter`, any `*Events` (`CometChatMessageEvents`/`CometChatGroupEvents`/`CometChatCallEvents`/`CometChatUserEvents`/`CometChatConversationEvents`/`CometChatUIEvents`), `DataSource`/`DataSourceDecorator`/`ChatConfigurator`, `CometChatMessageTemplate` / `templates` prop, `textFormatters` prop **on `CometChatMessageList`/`CometChatConversations`** (gone from the lists in v7 — `textFormatters` itself is NOT removed; see pitfalls), `hideError`/`disableLoadingState` props, `data-theme` attribute, **localization** (`getLocalizedString(...)`, `CometChatLocalize`, unprefixed i18n keys like `group_info` that v7 moved under `sample_` — §7), `CometChatUIKitLoginListener`, and the removed standalone components (`CometChatEmojiKeyboard`/`CometChatMediaRecorder`/`CometChatToast`/`CometChatListItem`/`CometChatNotificationBadge`). Produce the concrete change list.
+4. **Apply the breaking-change map** (`references/migration-guide.md`): symbol renames, RxJS `*Events` → the `useCometChatEvents` hook, `DataSource`/`ChatConfigurator` → `CometChatMessagePlugin` + the `plugins` prop, `templates` prop → plugins (`textFormatters` is NOT removed — relocate it, see pitfalls), `data-theme` → the `theme` prop, calling → `uiKit:{callsSDK:{}}` on `initFromSettings` (step 2), **localization → the v7 method + map v6 keys to the bundled `sample_*` keys (or register via the INSTANCE method `CometChatLocalize.getSharedInstance()?.addTranslation(...)` — NOT a static) — see `migration-guide.md` §7; look up the EXACT key in the uikit source (`resources/<lang>/translation.json`) / docs / GitHub, never guess**. For any component's exact prop change NOT in the baked map, FETCH the prop-by-prop table via `cometchat-react-v7-core/references/docs-map.md` → `migration-property-changes`.
+5. **Wrap the chat tree in `CometChatProvider`** if it isn't already (v7 requires it above the components; init/login stay imperative and unchanged).
+6. **Verify.** Build/typecheck passes; NO v6 symbols remain (grep the removed names); the app renders inside `CometChatProvider`; migrated events/plugins/calling work. Reuse `cometchat-react-v7-core` "Verify it works".
+
+## Common pitfalls (BAKED)
+- **Leftover `rxjs` event subscriptions** — v6 `*Events.<x>.subscribe()` do NOT fire in v7; convert every one to `useCometChatEvents((event) => …)` (SDK + UI events share one bus). Publish via `usePublishEvent()`.
+- **Forgetting `CometChatProvider`** — v7 components read it; symptom = context/"not initialized" errors even though init ran.
+- **`CometChatMessageTemplate` / `templates` props** — removed from components; move custom message rendering to a `CometChatMessagePlugin` passed via `plugins`. **`textFormatters` is NOT removed** — it stays a prop in v7 (verified vs 7.1.0) on `CometChatMessageComposer`, the bubble components (Text/Image/Video/Audio/File/…), `CometChatSearch` and `CometChatMessageInformation`, but it is GONE from `CometChatMessageList`/`CometChatConversations`. Keep it as a prop on those components. The list's bubbles take formatters from the text plugin's `getTextFormatters()`, so to keep a v6 list-level formatter, override that one method — `plugins={[{ ...CometChatTextPlugin, getTextFormatters: () => [/* defaults + yours */] }]}` (provider plugins precede the defaults, so it wins).
+- **Dependency drift** — missing the new `dompurify` peer dep, or leftover `rxjs`, breaks the build; do both halves of step 2.
+- **Calling silently off** — v7 needs calling turned on in the init settings (`uiKit: { callsSDK: {} }` via `CometChatUIKit.initFromSettings`; or the classic `.setCallingEnabled(true)` on `UIKitSettingsBuilder`) — not a provider prop; without it, call buttons hide and the Calls SDK never loads.
+- **Bubble routing** — the message list now defaults to the multi-attachment bubbles (`CometChatImageBubble`→`CometChatImagesBubble`, singular `CometChatFileBubble` still ships); code that imported singular bubble names for the list default may need the plural.
+- **Don't mass-remove `hideError`** — it's removed from list components but **retained on `CometChatMessageComposer`**; `textFormatters` likewise still exists on the message-bubble components. Scope the removals; don't blanket-strip.
+
+## Verify it works
+Build/typecheck is green; a repo-wide grep finds NO removed v6 symbols (`CometChatDocumentBubble`, `CometChatCompactMessageComposer`, `*Events`, `DataSource`, `DataSourceDecorator`, `ChatConfigurator`, `CometChatMessageTemplate`, `CometChatUIKitLoginListener`); the app renders inside `CometChatProvider`; and any migrated events / plugins / calling work. Full prop-by-prop reference: fetch `migration-property-changes` via `cometchat-react-v7-core/references/docs-map.md`.

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.