@cometchat/skills 4.4.2 → 5.0.1

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

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

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

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

package/skills/cometchat-react-v7-placement/references/recipes.md

@@ -0,0 +1,354 @@
+# Placement recipes — `cometchat-react-v7-placement`
+
+The two production placement recipes for the React v7 UI Kit, loaded on demand (the SKILL entry carries the pattern matrix + invariants; this file carries the full code). Every symbol is catalog-verified vs installed 7.1.0 and the compositions compile against 7.1.0. Both recipes use the `useIsMobile` hook from the **Responsive / mobile** section of `../SKILL.md`.
+
+## Core-surface recipe (BAKED) — THE DEFAULT for an unscoped "add chat" (production-ready, lean)
+`CometChatErrorBoundary` wraps the surface; one `CometChatProvider` at a stable ancestor; a small state object drives a `CometChatConversations` LIST ↔ a MESSAGE pane; the **thread-replies panel is wired by DEFAULT** (opt-out only) and the search affordance is wired-or-hidden; it collapses to one pane on mobile. No selector tabs, no details/search side panel, no incoming call — those are the GROWTHS (see the Combined-app recipe below); the thread panel, however, is part of the default surface. Uses the same `useIsMobile` hook + column CSS defined further down.
+
+```tsx
+import { useReducer } from "react";
+import {
+  CometChatErrorBoundary,
+  CometChatConversations, CometChatMessageHeader, CometChatMessageList,
+  CometChatMessageComposer, CometChatThreadHeader, CometChatSearch,
+} from "@cometchat/chat-uikit-react";
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+// ONE small state object: the selected conversation + which side view is open.
+type Side = "none" | "thread" | "search" | "chat-search";  // "search"=GLOBAL (over the list column); "chat-search"=IN-CHAT search SCOPED to the open chat (side panel) — never one shared state (AUDIT-041/044)
+type S = { user?: CometChat.User; group?: CometChat.Group; thread?: CometChat.BaseMessage; side: Side };
+type A =
+  | { t: "user"; v?: CometChat.User } | { t: "group"; v?: CometChat.Group }
+  | { t: "thread"; v?: CometChat.BaseMessage } | { t: "side"; v: Side };
+function reducer(s: S, a: A): S {
+  switch (a.t) {
+    case "user": return { ...s, user: a.v, group: undefined, side: "none", thread: undefined };
+    case "group": return { ...s, group: a.v, user: undefined, side: "none", thread: undefined };
+    case "thread": return { ...s, thread: a.v, side: "thread" };
+    case "side": return { ...s, side: a.v };
+  }
+}
+
+function CoreChatSurface() {
+  const isMobile = useIsMobile();                 // the SSR-guarded breakpoint hook below
+  const [s, dispatch] = useReducer(reducer, { side: "none" });
+  const target = s.user ? { user: s.user } : s.group ? { group: s.group } : undefined;
+  const hasChat = !!target;
+
+  const list = (
+    <aside className="list-column">
+      {s.side === "search" ? (
+        // GLOBAL search — OVER the list column (AUDIT-014), NO uid/guid; wire the round-trip (AUDIT-017)
+        <CometChatSearch
+          onBack={() => dispatch({ t: "side", v: "none" })}
+          onConversationClicked={(e) => {
+            const w = e.conversation.getConversationWith();
+            if (w instanceof CometChat.User) dispatch({ t: "user", v: w });
+            else if (w instanceof CometChat.Group) dispatch({ t: "group", v: w });
+          }}
+          onMessageClicked={(e) => {/* select the conversation of e.message, then jump to it */}}
+        />
+      ) : (
+        <CometChatConversations
+          onItemClick={(c) => {
+            const e = c.getConversationWith();
+            if (e instanceof CometChat.User) dispatch({ t: "user", v: e });
+            else if (e instanceof CometChat.Group) dispatch({ t: "group", v: e });
+          }}
+          onSearchBarClicked={() => dispatch({ t: "side", v: "search" })}   // GLOBAL search → OVER this column (or set showSearchBar={false})
+        />
+      )}
+    </aside>
+  );
+
+  const messagePane = target && (
+    <main className="message-pane">
+      <CometChatMessageHeader
+        {...target}
+        hideBackButton={!isMobile}
+        onBack={() => dispatch({ t: "user", v: undefined })}
+        showSearchOption
+        onSearchOptionClicked={() => dispatch({ t: "side", v: "chat-search" })}  // IN-CHAT search → SCOPED (side panel), NOT global
+      />
+      <CometChatMessageList {...target} onThreadRepliesClick={(m) => dispatch({ t: "thread", v: m })} />
+      <CometChatMessageComposer {...target} />
+      {/* call buttons (header) + attach/emoji/voice (composer) are built-in defaults — pass nothing */}
+    </main>
+  );
+
+  // thread + in-chat (scoped) search → side panel; GLOBAL search → over the list column (desktop) / full-screen (mobile single pane)
+  const sidePanel = hasChat && s.side !== "none" && s.side !== "search" && (   // "search" (GLOBAL) lives in the list column, not here
+    <aside className="side-column">
+      {s.side === "thread" && s.thread && (
+        <>
+          <CometChatThreadHeader parentMessage={s.thread} onClose={() => dispatch({ t: "side", v: "none" })} />
+          <CometChatMessageList {...target!} parentMessageId={s.thread.getId()} />
+          <CometChatMessageComposer {...target!} parentMessageId={s.thread.getId()} />
+        </>
+      )}
+      {s.side === "chat-search" && (   // IN-CHAT search — SCOPED to the open conversation (uid/guid + searchIn), NOT global (AUDIT-041)
+        <CometChatSearch
+          uid={s.user?.getUid()}
+          guid={s.group?.getGuid()}
+          searchIn={["messages"]}
+          onBack={() => dispatch({ t: "side", v: "none" })}
+          onMessageClicked={(e) => {/* jump to e.message in the open chat */}}
+        />
+      )}
+    </aside>
+  );
+
+  // wide → list + message (+ side); mobile → ONE pane at a time
+  return (
+    <CometChatErrorBoundary>
+      <div className="cc-app" style={{ height: "100dvh", width: "100%", display: "flex", overflow: "hidden" }}>
+        {(!isMobile || !hasChat) && list}
+        {(!isMobile || hasChat) && (isMobile && s.side !== "none" ? sidePanel : messagePane)}
+        {!isMobile && sidePanel}
+      </div>
+    </CometChatErrorBoundary>
+  );
+}
+```
+Mount `<CoreChatSurface/>` inside your `CometChatProvider` (kept at a stable ancestor). **Ship the same column CSS below** — the root sizing alone leaves the columns collapsed. Every symbol is catalog-verified and the composition compiles against 7.1.0. To GROW this into the whole app (selector tabs + details/thread/search side panel + incoming call), see the Combined-app recipe next.
+
+## Combined-app recipe (BAKED) — the GROW target (load on request, when the user wants the whole app)
+Grow the core surface into the whole app. One `CometChatProvider` at a stable ancestor, wrapped in `CometChatErrorBoundary`; one state object drives three columns; every affordance sits on the component's built-in trigger (never a hand-rolled button); the side panel is a single mutually-exclusive slot. (For a plain "add chat", emit the leaner Core-surface recipe above instead.)
+> **Selection has THREE obligations, not one (AUDIT-079) — a selection that only opens a pane is a composition dead-end:** (1) **render** the target pane; (2) **REFLECT** it in the list as the active item — pass `activeConversation` / `activeUser` / `activeGroup` back to the list so the selected row highlights (the kit ships these props; without them the user can't tell what's selected); (3) make every opened side panel **CLOSEABLE** — wire `onBack`/`onClose` AND make sure a close CONTROL actually renders. Most components render their own back/close button (thread header `onClose`, search `onBack`), but **do NOT assume it** — `CometChatGroupMembers` in 7.2.0 renders NO default back button (only the "Members" title), so the host must supply the close via `headerView` (AUDIT-203). An opened panel with no *reachable* close is the SAME defect as an unwired trigger — §12 round-trip. All three are in the recipe below.
+> **A list-header action ("New chat" / "Create group") goes in the list's `headerView`, NOT a sibling above it — and re-render the title (AUDIT-083).** `CometChatConversations`/`CometChatGroups`/`CometChatUsers` only expose `headerView`, which REPLACES the whole default header (including the "Chats"/"Groups"/"Users" title) — so render the title AND your button together inside it. Placing the button ABOVE the list is the sibling-on-top defect (§13 / `../cometchat-react-v7-core/references/component-props.md` → "List-header actions" for the exact pattern).
+> **A Calls tab must be GATED ON REAL AVAILABILITY, not baked-always-on (AUDIT-162).** `CometChatCallLogs` shows the kit's raw "OOPS!" screen when call-logs are unavailable — and, verified live, it renders that from its OWN INTERNAL error state WITHOUT throwing, so a host `CometChatErrorBoundary`/`fallbackView` CANNOT override it. A fallbackView is NOT the remedy. The recipe therefore gates the Calls TAB on a `callLogsAvailable` flag and omits the tab unless call-logs is CONFIRMED available. Two INDEPENDENT gates: `callingEnabled` (`uiKit:{callsSDK:{}}`) governs the header call BUTTONS; `callLogsAvailable` (a SEPARATE plan/capability gate — enabled ≠ available; proven live) governs the Calls-logs tab. Confirm availability with a one-time SDK probe you own (CallLogRequestBuilder → fetchNext()) or your known plan; default the tab OFF.
+
+```tsx
+import { useReducer } from "react";
+import {
+  CometChatErrorBoundary,
+  CometChatConversations, CometChatUsers, CometChatGroups, CometChatCallLogs,
+  CometChatMessageHeader, CometChatMessageList, CometChatMessageComposer,
+  CometChatThreadHeader, CometChatSearch, CometChatGroupMembers, CometChatIncomingCall,
+} from "@cometchat/chat-uikit-react";
+import { CometChat } from "@cometchat/chat-sdk-javascript";
+
+// ONE state object coordinates the whole app (tab · selection · thread · side panel).
+type Side = "none" | "details" | "thread" | "search" | "chat-search";  // "search"=GLOBAL (over the list column); "chat-search"=IN-CHAT search SCOPED to the open chat (side panel) — NEVER one shared state (AUDIT-041/044)
+// `conversation` is kept ALONGSIDE user/group so the Conversations list can REFLECT the selection
+// (activeConversation) — selection has 3 obligations: render the pane, HIGHLIGHT the active item, and
+// make every opened panel CLOSEABLE (RULES §12; AUDIT-079).
+type S = { tab: "chats"|"users"|"groups"|"calls"; user?: CometChat.User; group?: CometChat.Group; conversation?: CometChat.Conversation; thread?: CometChat.BaseMessage; side: Side };
+type A =
+  | { t: "tab"; v: S["tab"] } | { t: "user"; v?: CometChat.User; conv?: CometChat.Conversation } | { t: "group"; v?: CometChat.Group; conv?: CometChat.Conversation }
+  | { t: "thread"; v?: CometChat.BaseMessage } | { t: "side"; v: Side };
+function reducer(s: S, a: A): S {
+  switch (a.t) {
+    case "tab": return { ...s, tab: a.v };
+    case "user": return { ...s, user: a.v, group: undefined, conversation: a.conv, side: "none", thread: undefined };
+    case "group": return { ...s, group: a.v, user: undefined, conversation: a.conv, side: "none", thread: undefined };
+    case "thread": return { ...s, thread: a.v, side: "thread" };
+    case "side": return { ...s, side: a.v };
+  }
+}
+
+// `callLogsAvailable` = is the CALL-LOGS capability actually available on this app's PLAN? Compute it in
+// the app shell and pass it in. It is SEPARATE from "calling enabled": enabling calling
+// (`uiKit:{callsSDK:{}}`, which surfaces the header call buttons — that happens at init, NOT here) does
+// NOT imply call-logs is available (proven live). The Calls-logs TAB is gated on THIS flag because
+// `CometChatCallLogs` shows the kit's internal "OOPS!" (which no host fallbackView can override) when
+// call-logs is unavailable. Compute it with a one-time SDK probe you own (CallLogRequestBuilder with the
+// logged-in USER's auth token → fetchNext(); see `useCallLogsAvailable` below) or your known plan; default
+// false so a plain app never ships a dead-ending Calls tab.
+function CombinedChatApp({ callLogsAvailable = false }: { callLogsAvailable?: boolean }) {
+  const isMobile = useIsMobile();                 // the SSR-guarded breakpoint hook below
+  const [s, dispatch] = useReducer(reducer, { tab: "chats", side: "none" });
+  const target = s.user ? { user: s.user } : s.group ? { group: s.group } : undefined;
+  const hasChat = !!target;
+  // The tabs to render — Calls is included ONLY when call-logs is CONFIRMED AVAILABLE (a real gate, not a
+  // comment, and NOT merely "calling enabled" — enabled ≠ available).
+  const tabs: S["tab"][] = callLogsAvailable
+    ? ["chats", "users", "groups", "calls"]
+    : ["chats", "users", "groups"];
+
+  const selector = (
+    <aside className="list-column">
+      {s.side === "search" ? (
+        // GLOBAL search (all conversations + messages) — renders OVER the list column (AUDIT-014), NO uid/guid;
+        // wire the FULL round-trip (AUDIT-017): onBack + result clicks close it and select the hit.
+        <CometChatSearch
+          onBack={() => dispatch({ t: "side", v: "none" })}
+          onConversationClicked={(e) => {
+            const w = e.conversation.getConversationWith();
+            if (w instanceof CometChat.User) dispatch({ t: "user", v: w });
+            else if (w instanceof CometChat.Group) dispatch({ t: "group", v: w });
+          }}
+          onMessageClicked={(e) => {/* select the conversation of e.message, then jump to it */}}
+        />
+      ) : (
+        <>
+          {/* Tab bar — render the GATED `tabs` (Calls absent unless calling is enabled). This is the
+              real wiring, not a TODO: a button per tab that dispatches the tab change. */}
+          <nav className="cc-tabbar">
+            {tabs.map((t) => (
+              <button
+                key={t}
+                className={s.tab === t ? "cc-tab cc-tab--active" : "cc-tab"}
+                onClick={() => dispatch({ t: "tab", v: t })}
+              >
+                {t}
+              </button>
+            ))}
+          </nav>
+          {s.tab === "chats" && (
+            <CometChatConversations
+              activeConversation={s.conversation}   /* REFLECT the selection — highlights the open chat in the list (AUDIT-079) */
+              onItemClick={(c) => {
+                const e = c.getConversationWith();
+                if (e instanceof CometChat.User) dispatch({ t: "user", v: e, conv: c });
+                else if (e instanceof CometChat.Group) dispatch({ t: "group", v: e, conv: c });
+              }}
+              onSearchBarClicked={() => dispatch({ t: "side", v: "search" })}   // GLOBAL search → OVER this column
+            />
+          )}
+          {s.tab === "users" && <CometChatUsers activeUser={s.user} onItemClick={(u) => dispatch({ t: "user", v: u })} />}
+          {s.tab === "groups" && <CometChatGroups activeGroup={s.group} onItemClick={(g) => dispatch({ t: "group", v: g })} />}
+          {/* Calls tab — GATE ON REAL AVAILABILITY, not merely "calling enabled" (AUDIT-063 + AUDIT-162).
+              `CometChatCallLogs` renders the kit's raw "OOPS! …" screen whenever call-logs are unavailable,
+              and — verified live — it does so from its OWN INTERNAL error state WITHOUT THROWING, so an
+              outer `CometChatErrorBoundary`/`fallbackView` CANNOT override it (fallbackView never fires).
+              A `fallbackView` is therefore NOT the remedy here. Two facts to design around:
+                (1) Calling being ENABLED (the calls skill's `uiKit:{callsSDK:{}}`, which surfaces the header
+                    Voice/Video buttons) is NECESSARY to offer the tab but NOT SUFFICIENT — call-logs is a
+                    SEPARATE plan/capability gate (proven live: header call buttons present, tab still "OOPS").
+                (2) There is NO host-side way to replace the internal "OOPS!". So the ONLY reliable
+                    protection is to NOT surface the Calls tab until call-logs is confirmed AVAILABLE.
+              So gate `callLogsAvailable` on an actual availability check (a one-time SDK probe you own —
+              build a CallLogRequestBuilder with the logged-in USER's auth token (NOT a generateToken()
+              call token) → fetchNext(), and only flip the flag on success), or on your known
+              plan. Compute it in the app shell and pass it down as `callLogsAvailable`. */}
+          {callLogsAvailable && s.tab === "calls" && <CometChatCallLogs />}
+        </>
+      )}
+    </aside>
+  );
+
+  const messagePane = target && (
+    <main className="message-pane">
+      <CometChatMessageHeader
+        {...target}
+        hideBackButton={!isMobile}
+        onBack={() => dispatch({ t: "user", v: undefined })}
+        onItemClick={() => dispatch({ t: "side", v: "details" })}       // header → details side panel
+        showSearchOption
+        onSearchOptionClicked={() => dispatch({ t: "side", v: "chat-search" })}  // IN-CHAT search → SCOPED to THIS chat (side panel), NOT global
+      />
+      <CometChatMessageList {...target} onThreadRepliesClick={(m) => dispatch({ t: "thread", v: m })} />
+      <CometChatMessageComposer {...target} />
+      {/* call buttons (header) + attach/emoji/voice (composer) are built-in defaults — pass nothing */}
+    </main>
+  );
+
+  const sidePanel = hasChat && s.side !== "none" && s.side !== "search" && (   // "search" (GLOBAL) lives in the selector column, not here
+    <aside className="side-column">
+      {s.side === "thread" && s.thread && (
+        <>
+          <CometChatThreadHeader parentMessage={s.thread} onClose={() => dispatch({ t: "side", v: "none" })} />
+          <CometChatMessageList {...target!} parentMessageId={s.thread.getId()} />
+          <CometChatMessageComposer {...target!} parentMessageId={s.thread.getId()} />
+        </>
+      )}
+      {s.side === "chat-search" && (   // IN-CHAT search — SCOPED to the open conversation (uid/guid + searchIn), NOT global (AUDIT-041)
+        <CometChatSearch
+          uid={s.user?.getUid()}
+          guid={s.group?.getGuid()}
+          searchIn={["messages"]}
+          onBack={() => dispatch({ t: "side", v: "none" })}
+          onMessageClicked={(e) => {/* jump to e.message in the open chat */}}
+        />
+      )}
+      {s.side === "details" && s.group && (
+        // WIRE THE CLOSE — the HOST OWNS IT with its OWN chrome bar, as a SIBLING ABOVE the component
+        // (AUDIT-203). Verified vs installed 7.2.0: CometChatGroupMembers renders NO default back button
+        // (its default header is title-only; `CometChatGroupMembersRootProps` has `onBack?` but NO
+        // hideBackButton/showBackButton) AND it does NOT honor a `headerView` slot at runtime — it renders
+        // only `__search-bar` + `__list`, so a `headerView` back button never appears (re-verified live).
+        // Therefore the ONLY reliable close is a HOST SIBLING chrome bar, not the component's slot. Keep
+        // `onBack` too (harmless; fires if a future kit renders its own back button).
+        <>
+          <div className="cc-side-header" style={{ display: "flex", alignItems: "center", gap: 8, padding: "0 12px", height: 56, flex: "0 0 auto" }}>
+            <button aria-label="Back" onClick={() => dispatch({ t: "side", v: "none" })}>←</button>
+            <h3 style={{ margin: 0 }}>Members</h3>
+          </div>
+          <div style={{ flex: "1 1 0", minHeight: 0 }}>
+            <CometChatGroupMembers group={s.group} onBack={() => dispatch({ t: "side", v: "none" })} />
+          </div>
+        </>
+      )}
+      {/* user details = host-composed from CometChatAvatar + SDK (no single kit drop-in) — it MUST include
+          its OWN close control that dispatches side:"none" (same round-trip rule; don't leave it dead-ending). */}
+    </aside>
+  );
+
+  // wide → 3 columns; mobile → ONE pane at a time (side replaces message replaces list)
+  return (
+    <CometChatErrorBoundary>
+      <div className="cc-app" style={{ height: "100dvh", width: "100%", display: "flex", overflow: "hidden" }}>
+        {(!isMobile || !hasChat) && selector}
+        {(!isMobile || hasChat) && (isMobile && s.side !== "none" ? sidePanel : messagePane)}
+        {!isMobile && sidePanel}
+        <CometChatIncomingCall />
+      </div>
+    </CometChatErrorBoundary>
+  );
+}
+```
+**Ship this CSS too — the 3-column layout is NOT complete without it, and it must satisfy the reflow-free-surface standard (`../cometchat-react-v7-core/references/layout.md`: prepared ancestor chain · pinned `100dvh` · `min-height:0` columns).** Sizing the root alone leaves the columns collapsing to content and growing as it loads. Values proven from the official sample app (`styles/App.css`):
+```css
+/* (a) prepare/reset the ancestor chain FIRST — see layout.md */
+html, body, #root { height: 100%; margin: 0; padding: 0; }
+#root { max-width: none; text-align: left; display: block; }
+body { display: block; place-items: normal; }
+.cc-app { overflow: hidden; }              /* (b) cap to the pinned 100dvh on the wrapper */
+.cc-app * { box-sizing: border-box; }
+/* (c) selector + side panel: fixed-ish width, full height, min-height:0 = scroll not grow */
+.cc-app .list-column,
+.cc-app .side-column { display: flex; flex-direction: column; height: 100%; width: 30%; max-width: 420px; flex-shrink: 0; min-height: 0; }
+.cc-app .message-pane { display: flex; flex-direction: column; height: 100%; flex: 1; min-width: 0; min-height: 0; overflow: hidden; }
+/* let the kit list fill the column below your tab bar */
+.cc-app .list-column .cometchat-list__body,
+.cc-app .side-column .cometchat-list__body { flex: 1; min-height: 0; }
+/* host tab bar (your chrome, not the kit) */
+.cc-tabbar { display: flex; gap: 2px; padding: 6px; flex: 0 0 auto; }
+.cc-tab { flex: 1; text-transform: capitalize; padding: 8px 4px; border: 0; border-radius: 6px; background: transparent; cursor: pointer; font: inherit; }
+.cc-tab--active { background: var(--cometchat-primary-color, #6851d6); color: #fff; }
+/* friendly "unavailable" fallback for a capability-gated surface (e.g. call-logs) — NOT the raw kit "OOPS!" */
+.cc-unavailable { padding: 24px; text-align: center; color: var(--cometchat-text-color-secondary, #727272); }
+```
+Mount `<CombinedChatApp callLogsAvailable={/* call-logs confirmed available */} />` inside your `CometChatProvider` (kept at a stable ancestor). It defaults `false`: the header call buttons are enabled at INIT (`uiKit:{callsSDK:{}}` in the calls skill), not via a prop here; `callLogsAvailable` (a SEPARATE plan gate — calling-enabled ≠ call-logs-available) governs the Calls-logs tab, which is omitted unless confirmed available so a plain app never ships a dead-ending "OOPS!" tab. A host `CometChatErrorBoundary`/`fallbackView` does NOT help for `CometChatCallLogs` — it renders its own internal "OOPS!" without throwing (verified live), so gating is the only reliable protection. Every symbol above is catalog-verified and the composition compiles against 7.1.0. Full composition rationale + the complete placement map: the factory's `FULL-APP-BLUEPRINT.md`.
+
+### The `callLogsAvailable` probe (BAKED — with the EXACT imports, AUDIT-204)
+Compute `callLogsAvailable` with a one-time SDK probe you own, then pass it into `<CombinedChatApp>`. **Import discipline: `CallLogRequestBuilder` is NOT a named export of `@cometchat/calls-sdk-javascript` — it is a STATIC on the `CometChatCalls` default-export class** (verified vs calls-sdk 5.0.5 `dist/index.d.ts`: `static CallLogRequestBuilder: typeof CallLogRequestBuilder`; the package default-exports the `CometChatCalls` namespace). A naive `import { CallLogRequestBuilder } from "@cometchat/calls-sdk-javascript"` FAILS to compile (TS2614). Use the static. **`setAuthToken` takes the logged-in USER's auth token** — the call-log request sends it as the `authToken` header, exactly as the kit's own `CometChatCallLogs` does (`loggedInUser.getAuthToken()`); a `generateToken()` CALL/session token is the wrong credential, so a probe built on it always fails and the tab never shows. And on a RESTORED session `initFromSettings` does not await the Calls-SDK init, so wait (bounded) for `CometChatUIKit.isCallingReady()` before probing:
+```tsx
+import { useEffect, useState } from "react";
+import { CometChatUIKit } from "@cometchat/chat-uikit-react";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";   // ← CallLogRequestBuilder is a STATIC on this, NOT a named import
+
+export function useCallLogsAvailable(): boolean {
+  const [available, setAvailable] = useState(false);
+  useEffect(() => {
+    let cancelled = false;
+    (async () => {
+      try {
+        for (let i = 0; i < 40 && !cancelled && !CometChatUIKit.isCallingReady(); i++) await new Promise((r) => setTimeout(r, 250));
+        const me = CometChatUIKit.getLoggedInUser();
+        if (cancelled || !me || !CometChatUIKit.isCallingReady()) return;   // calling off / SSR / not ready ⇒ stays OFF
+        const req = new CometChatCalls.CallLogRequestBuilder()      // ← static access — the ONLY form that compiles
+          .setLimit(1).setAuthToken(me.getAuthToken()).build();     // USER auth token — NOT a generateToken() call token
+        await req.fetchNext();                                      // resolves ⇒ call-logs available; throws/402 ⇒ not on plan
+        if (!cancelled) setAvailable(true);
+      } catch {
+        if (!cancelled) setAvailable(false);                        // default OFF ⇒ no dead-ending Calls tab
+      }
+    })();
+    return () => { cancelled = true; };
+  }, []);
+  return available;
+}
+// then: const callLogsAvailable = useCallLogsAvailable(); <CombinedChatApp callLogsAvailable={callLogsAvailable} />
+```

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

@@ -0,0 +1,84 @@
+---
+name: cometchat-react-v7-production
+description: "Ship a CometChat React v7 integration safely — server-minted auth tokens instead of the Auth Key, correct env prefixes per bundler, bundle hygiene, and a pre-launch checklist. Triggers: 'is this production ready', 'auth token instead of auth key react', 'secure my cometchat react setup', 'production build config react', 'going live checklist react', 'harden cometchat before launch'."
+license: "MIT"
+compatibility: "@cometchat/chat-uikit-react ^7 (7.1.x–7.2.x verified); React 18–19; Vite / Next.js / CRA / React Router / Astro"
+metadata:
+  author: "CometChat"
+  version: "1.0.0"
+  tags: "cometchat react v7 production security auth-token hardening deployment"
+---
+
+> **Ground truth:** `@cometchat/chat-uikit-react@7`. The auth-token / login API is FETCHED from the docs via `cometchat-react-v7-core/references/docs-map.md` (`/ui-kit/react/integration-react` + the JS SDK auth pages); the REST auth-token endpoint is `{DOCS_BASE}/rest-api/auth-tokens`. **The React UI Kit docs have no single production-hardening page** — this checklist is the pack's own guidance from `RULES.md` §4 (Credentials) + what the kit ships, labelled as such, not presented as documented. Tracked DOCS GAP.
+
+## Companion skills (read first)
+- `cometchat-react-v7-core` — `references/setup-credentials.md` + `references/lifecycle.md` cover the dev credential flow this replaces and the init→login→render order.
+- `cometchat-react-v7-patterns` — the per-bundler env prefix + build specifics referenced below.
+- `cometchat-security` — the enterprise auth model this client-side hardening plugs into: wiring your IdP / SSO into the token flow (your IdP → your server → mint the CometChat auth token; CometChat is **not** an IdP), token expiry/refresh + re-login, RBAC roles + group (SBAC) scopes, and Auth Key vs auth token vs REST API Key. Load it for a security review or any SSO question.
+
+## Use this skill when
+Moving off the development setup: going live, a security review, or "is this safe to ship."
+
+## The one thing that matters
+**Never ship the Auth Key in the browser bundle.**
+
+The Auth Key can mint a session for **any user in your app**. Every `VITE_`/`NEXT_PUBLIC_`/`REACT_APP_`/`PUBLIC_`-prefixed value is compiled into JavaScript your users download — so an Auth Key there is public. Anyone can read it, log in as any UID, and read every conversation.
+
+| | Development | Production |
+| --- | --- | --- |
+| Login | `CometChatUIKit.login(uid)` | `CometChatUIKit.loginWithAuthToken(token)` |
+| Auth Key | in the client env | **absent from the bundle** |
+| Token source | n/a | your backend, per authenticated user |
+| REST API Key | never client-side | server only |
+
+## The production login flow
+1. Your app authenticates the user (your own auth — CometChat is not an identity provider).
+2. Your **server** calls CometChat's REST API with the **REST API Key** to mint an auth token for that user's UID (`{DOCS_BASE}/rest-api/auth-tokens`).
+3. The server returns the token to the browser over an authenticated request.
+4. The app calls `loginWithAuthToken(token)`.
+
+```tsx
+// the endpoint derives the UID from the SERVER session — never from a query param
+const res = await fetch("/api/cometchat-token", { credentials: "include" });
+const { authToken } = await res.json();
+await CometChatUIKit.loginWithAuthToken(authToken);
+```
+Accepting `?uid=` (or any client-supplied UID) lets a caller impersonate anyone. The UID must come from the server-side session.
+
+## Env prefix — do NOT ship the key
+Init reads the Auth Key from the client env in development. Production must set it empty and log in with a token instead. The prefix is bundler-specific (`cometchat-react-v7-patterns`): Vite `VITE_`, Next `NEXT_PUBLIC_` (`.env.local`), CRA `REACT_APP_`, Astro `PUBLIC_`. App ID and Region are not secrets — they identify the app; the Auth Key is the secret. **Grep the built bundle to be certain:**
+```bash
+npm run build && grep -rll "<your-auth-key>" dist/ build/ .next/ 2>/dev/null && echo "LEAK" || echo "clean"
+```
+Run that in CI — a stray `.env` or a wrong prefix ships the key silently.
+
+## Also before launch
+- **Users are created server-side**, as part of your signup — not from the browser (no `createUser` with the Auth Key in client code).
+- **Log out properly**: `await CometChatUIKit.logout()`, then clear derived React state and unregister push tokens (`cometchat-react-v7-push`).
+- **HTTPS everywhere** — required for calls (`getUserMedia`) and push.
+- **Pin the kit** to an exact or `~` range so a minor cannot change component behaviour under you.
+- **Keep `CometChatErrorBoundary`** wrapping the surface so a render error shows a fallback, not a white screen (it is not the initializer — init/login still run first).
+- **SSR/StrictMode:** guard init+login so React 18/19 StrictMode's double-invoke does not race two logins (`cometchat-react-v7-patterns`); never init during SSR — gate on the client.
+- **Region must match** the dashboard app in every build.
+- **Enable dashboard extensions/AI on the PRODUCTION app**, not just dev.
+
+## Pre-launch checklist
+- [ ] Auth Key absent from the production bundle (grep-verified in CI)
+- [ ] `loginWithAuthToken` in production; UID from the server session
+- [ ] REST API Key server-side only
+- [ ] Correct env prefix for the bundler; `.env` gitignored
+- [ ] HTTPS, valid certificate
+- [ ] Logout clears session, React state and push tokens
+- [ ] Kit version pinned; `CometChatErrorBoundary` in place
+- [ ] Dashboard extensions/AI enabled for the production app
+- [ ] Tested against the production app's credentials
+
+## Common pitfalls
+1. **Auth Key in the production bundle** — the critical one; wrong env prefix is the usual cause.
+2. **Token endpoint trusting a client-supplied UID** — impersonation.
+3. **Init/login run during SSR or twice under StrictMode** — races and "already logged in" errors.
+4. **Dashboard configured on the dev app only** — features silently missing in production.
+5. **No logout teardown** — the next user inherits the session or the push token.
+
+## Verify it works
+Production build contains no Auth Key (grep) · login works via token · a tampered UID is rejected by the server · logout fully clears · calls and push work over HTTPS · features enabled on the production app.