@cometchat/skills 4.3.0 → 4.4.1

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

@@ -1,36 +1,220 @@
 ---
 name: cometchat-react-push
-description: Push notifications for CometChat React UI Kit v6 in Vite / Next.js / React Router / Astro projects. Web doesn't have native push — covers Web Push (Service Worker + Push API + Notification API + VAPID keys), CometChat dashboard PushPlatform configuration, server-side webhook to send pushes when a message arrives, click-through to chat, foreground vs background handling, iOS Safari 16.4+ PWA-only quirks, and HTTPS requirements.
+description: Push notifications for CometChat React UI Kit v6 in Vite / Next.js / React Router / Astro projects. Recommended path is CometChat-native web push via Firebase Cloud Messaging for Web — `CometChatNotifications.registerPushToken(token, PushPlatforms.FCM_WEB)` + a dashboard FCM provider, so CometChat's own backend delivers new-message pushes with NO self-hosted push server. Also documents an optional advanced self-hosted Web Push fallback (Service Worker + Push API + VAPID + message-sent webhook) for projects that can't use Firebase. Covers click-through to chat, foreground vs background handling, iOS Safari 16.4+ PWA-only quirks, and HTTPS requirements.
 license: "MIT"
-compatibility: "React >= 18; Web Push API (Chrome 50+, Firefox 44+, Edge 17+, Safari 16+ desktop, Safari 16.4+ iOS PWA-only); HTTPS required (or localhost); CometChat dashboard PushPlatform configured"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
+compatibility: "React >= 18; @cometchat/chat-sdk-javascript ^4.1.10 (ships CometChatNotifications.registerPushToken + PushPlatforms.FCM_WEB); firebase modular SDK for FCM_WEB; Web Push API (Chrome 50+, Firefox 44+, Edge 17+, Safari 16+ desktop, Safari 16.4+ iOS PWA-only); HTTPS required (or localhost)"
 metadata:
   author: "CometChat"
-  version: "4.0.0"
-  tags: "cometchat react web push notifications service-worker vapid push-api notification-api ios-safari-pwa nextjs astro react-router"
+  version: "4.1.0"
+  tags: "cometchat react web push notifications fcm-web firebase cometchatnotifications registerpushtoken service-worker vapid push-api notification-api ios-safari-pwa nextjs astro react-router"
 ---
 
 ## Purpose
 
-Web Push for CometChat chat. The web has no native VoIP-push equivalent for incoming-call ringing (see `cometchat-react-calls/references/voip-and-web-push.md` for that limit), but it does have **Web Push** for new-message notifications when the user's tab is backgrounded or closed. This skill wires the full path: client subscription → server webhook → push send → notification → click-through.
+Web push for CometChat chat — new-message notifications when the user's tab is backgrounded or closed.
 
-**Not the same as the calls Web Push.** Calls Web Push tries to ring the device through a closed tab (best-effort, browser-dependent). Chat Web Push notifies on new messages — fundamentally similar plumbing, different payload + UX. Many apps need both.
+**The web DOES have CometChat-native push.** The JS Chat SDK ships a first-class web-push registration API: `CometChatNotifications.registerPushToken(token, PushPlatforms.FCM_WEB)`. Paired with a Firebase Cloud Messaging (FCM) provider configured in the CometChat dashboard, **CometChat's own backend delivers the push on every new message** — no self-hosted push server, no `web-push` lib, no VAPID server of your own, and no message-sent webhook for the basic case. This is the recommended path (§1).
+
+A self-hosted Web Push path (your own VAPID keys + push server + CometChat webhook) is documented as an advanced fallback (§7) for projects that can't or won't use Firebase. Don't reach for it unless you have to.
+
+**Not the same as the calls Web Push.** Calls Web Push tries to ring the device through a closed tab (best-effort, browser-dependent). Chat push notifies on new messages — different payload + UX. Many apps need both.
 
 **Read these other skills first:**
 - `cometchat-core` — provider pattern, login order
 - `cometchat-{react,nextjs,react-router,astro}-patterns` — framework-specific Service Worker registration
 - `cometchat-react-calls/references/voip-and-web-push.md` — calls-specific Web Push (overlap with this; both can coexist)
-- `cometchat-production` — server-minted auth tokens (push payloads should NOT contain Auth Key)
+- `cometchat-production` — server-minted auth tokens
+
+**Ground truth (verified against the JS Chat SDK source):** **Official docs:** https://www.cometchat.com/docs/notifications/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
+- `CometChatNotifications.registerPushToken(pushToken: string, platform: PushPlatforms, providerId?: string): Promise<string>` — `chat-sdk-javascript/src/Notifications/CometChatNotifications.ts:616`
+- `CometChatNotifications.unregisterPushToken(): Promise<string>` — `chat-sdk-javascript/src/Notifications/CometChatNotifications.ts:649`
+- `enum PushPlatforms { FCM_WEB = 'fcm_web' }` — `chat-sdk-javascript/src/Notifications/constants/CometChatNotificationsConstants.ts:46-47`
+- The web kit pins `@cometchat/chat-sdk-javascript ^4.1.10`, which has this API.
+- There is NO `PNPlatform` and NO `PushNotificationOptions` symbol — the real names are `PushPlatforms` and `CometChatNotifications`.
+- Firebase Cloud Messaging for Web — https://firebase.google.com/docs/cloud-messaging/js/client
+- Web Push spec / VAPID / Push API (fallback path only) — RFC 8030, RFC 8292, https://developer.mozilla.org/en-US/docs/Web/API/Push_API
+
+---
+
+## 1. Recommended: CometChat-native web push (FCM_WEB)
+
+CometChat delivers web push through **Firebase Cloud Messaging for Web**. You register the FCM device token with CometChat via the Chat SDK; CometChat's backend then sends pushes on new messages through your dashboard-configured FCM provider. No push server of yours.
+
+```
+Browser (your React app)
+  ├── firebase/messaging  — getToken() → FCM web token
+  ├── firebase-messaging-sw.js — receives background pushes (onBackgroundMessage)
+  └── CometChatNotifications.registerPushToken(token, FCM_WEB) — hands token to CometChat
+
+CometChat backend
+  └── FCM provider (dashboard) → sends push to the token on every new message
+```
+
+### 1.1 Firebase setup (one-time)
+
+1. Create a Firebase project, enable **Cloud Messaging**.
+2. Add a Web app; copy its web SDK config (`apiKey`, `projectId`, `messagingSenderId`, `appId`, …).
+3. Under **Project Settings → Cloud Messaging → Web configuration**, generate a **Web Push certificate**. This key pair is Firebase's own VAPID key — it is consumed by `getToken({ vapidKey })`. It is NOT a self-hosted VAPID server; you don't run any server for it.
+
+### 1.2 Install + initialize Firebase
+
+```bash
+npm install firebase
+```
+
+```ts
+// cometchat/firebase.ts
+import { initializeApp } from "firebase/app";
+
+export const firebaseApp = initializeApp({
+  apiKey: import.meta.env.VITE_FIREBASE_API_KEY,           // adjust prefix per framework
+  authDomain: import.meta.env.VITE_FIREBASE_AUTH_DOMAIN,
+  projectId: import.meta.env.VITE_FIREBASE_PROJECT_ID,
+  messagingSenderId: import.meta.env.VITE_FIREBASE_SENDER_ID,
+  appId: import.meta.env.VITE_FIREBASE_APP_ID,
+});
+
+export const FIREBASE_WEB_PUSH_CERT_KEY = import.meta.env.VITE_FIREBASE_VAPID_KEY; // Web Push certificate key
+```
+
+### 1.3 Service worker — `public/firebase-messaging-sw.js`
+
+The file MUST live at the origin root (`/firebase-messaging-sw.js`) — `getToken` looks for it by default, or pass an explicit `serviceWorkerRegistration`.
+
+> **Coexistence check first (P0-10).** If `detect` reported `coexistence.existing_firebase: true` or listed an existing service worker, the project already runs Firebase and/or a SW. Do NOT blindly overwrite: (a) reuse the project's existing Firebase config/app instead of a second `initializeApp` — duplicate apps fight over the FCM token; (b) if a service worker already exists at the origin root (e.g. a PWA/Workbox `sw.js`), **merge** the messaging handlers (`importScripts` + `firebase.initializeApp` + `onBackgroundMessage`) into it rather than replacing it, or register CometChat's worker at a distinct scope and pass it as `serviceWorkerRegistration` to `getToken`. Overwriting the app's worker silently kills its offline/caching logic.
+
+```js
+// public/firebase-messaging-sw.js
+importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-app-compat.js");
+importScripts("https://www.gstatic.com/firebasejs/10.12.0/firebase-messaging-compat.js");
+
+firebase.initializeApp({
+  apiKey: "…",
+  projectId: "…",
+  messagingSenderId: "…",
+  appId: "…",
+});
+
+const messaging = firebase.messaging();
+
+// Background pushes (tab closed / not focused)
+messaging.onBackgroundMessage((payload) => {
+  const { title, body } = payload.notification ?? {};
+  self.registration.showNotification(title ?? "New message", {
+    body: body ?? "",
+    icon: "/icons/chat.png",
+    tag: payload.data?.conversationId ? `chat-${payload.data.conversationId}` : undefined,
+    data: payload.data ?? {},
+  });
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  const data = event.notification.data ?? {};
+  const targetUrl = data.receiverType === "group"
+    ? `/messages?group=${data.conversationId}`
+    : `/messages?user=${data.senderUid ?? data.conversationId}`;
+  event.waitUntil(
+    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
+      for (const w of wins) {
+        if (w.url.includes(self.registration.scope)) {
+          w.focus();
+          w.postMessage({ type: "open_conversation", ...data });
+          return;
+        }
+      }
+      return clients.openWindow(targetUrl);
+    }),
+  );
+});
+```
+
+### 1.4 Register the FCM token with CometChat (after login)
+
+```ts
+// cometchat/registerFcmWebPush.ts
+import { getMessaging, getToken, onMessage } from "firebase/messaging";
+import { CometChatNotifications } from "@cometchat/chat-sdk-javascript";
+import { firebaseApp, FIREBASE_WEB_PUSH_CERT_KEY } from "./firebase";
+
+export async function registerFcmWebPush(): Promise<void> {
+  if (!("serviceWorker" in navigator) || !("Notification" in window)) return;
+
+  // Permission MUST be requested in response to a user gesture (see §2 rule).
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return;
+
+  // Register the FCM service worker.
+  const swReg = await navigator.serviceWorker.register("/firebase-messaging-sw.js");
+
+  const messaging = getMessaging(firebaseApp);
+  const fcmToken = await getToken(messaging, {
+    vapidKey: FIREBASE_WEB_PUSH_CERT_KEY,        // Firebase Web Push certificate — NOT a self-hosted VAPID server
+    serviceWorkerRegistration: swReg,
+  });
+  if (!fcmToken) return;
+
+  // Hand the token to CometChat. Its backend now delivers pushes on new messages.
+  await CometChatNotifications.registerPushToken(
+    fcmToken,
+    CometChatNotifications.PushPlatforms.FCM_WEB,
+    /* providerId */ undefined,                  // omit for "default", or pass your dashboard FCM provider id
+  );
+
+  // Foreground messages (tab focused) don't fire the SW — show them yourself if desired.
+  onMessage(messaging, (payload) => {
+    if (document.visibilityState === "visible") {
+      // e.g. toast / in-app banner instead of an OS notification
+      window.dispatchEvent(new CustomEvent("cometchat:foreground-push", { detail: payload }));
+    }
+  });
+}
+```
+
+Call it from your provider AFTER `CometChatUIKit.login(...)` resolves:
+
+```tsx
+// CometChatProvider.tsx
+useEffect(() => {
+  if (!user) return;
+  registerFcmWebPush().catch((err) => {
+    console.warn("FCM web push registration failed:", err); // never block chat — push is opt-in
+  });
+}, [user]);
+```
+
+### 1.5 Dashboard FCM provider (manual, one-time)
+
+In the CometChat dashboard: **Notifications → Push Notifications → Add FCM provider**. Upload the Firebase service-account JSON (or legacy server key) for the same Firebase project. CometChat now sends new-message pushes to every registered `FCM_WEB` token — **no webhook of yours**.
+
+### 1.6 Logout — unregister the token
+
+```ts
+import { CometChatNotifications } from "@cometchat/chat-sdk-javascript";
+
+// Call BEFORE CometChat.logout(), while the auth token is still valid.
+await CometChatNotifications.unregisterPushToken();   // CometChatNotifications.ts:649
+```
+
+> **Hard rule — register only AFTER login.** `registerPushToken` operates on the current logged-in user's auth token. Calling it before `CometChatUIKit.login(...)` resolves will fail or attach the token to nobody. Wire it inside the auth-state effect, never on page load.
 
-**Ground truth:**
-- Web Push spec — https://datatracker.ietf.org/doc/html/rfc8030
-- VAPID — https://datatracker.ietf.org/doc/html/rfc8292
-- Push API — https://developer.mozilla.org/en-US/docs/Web/API/Push_API
-- CometChat dashboard `PushNotifications` (formerly Extensions → Enhanced Push Notifications)
+> **Hard rule — `firebase-messaging-sw.js` must be at the origin root.** Place it in `public/` so it serves from `/firebase-messaging-sw.js`. In Next.js it cannot live under `app/`. See §8 for per-framework placement.
+
+> **Hard rule — iOS still needs PWA install.** FCM web push on iOS 16.4+ only works for a Home-Screen-installed PWA, exactly like the fallback path. See §9.
+
+---
+
+## 2. The permission-prompt rule (applies to both paths)
+
+Chrome / Firefox / Safari all require `Notification.requestPermission()` to run in response to a **user gesture** (a click). Calling it from a top-level `useEffect` on page load is rejected. Best pattern: an "Enable notifications" button the user clicks once, which then calls `registerFcmWebPush()` (or the fallback `registerWebPushForChat()`).
 
 ---
 
-## 1. Architecture
+## 3. Alternative / advanced: self-hosted Web Push (no Firebase)
+
+> Use this path **only** if you cannot or will not use Firebase (§1). It is more work — you run your own VAPID keys, a push server, and a CometChat message-sent webhook. CometChat's backend does NOT deliver the push for you on this path; your server does. For most apps, prefer §1.
+
+### 3.1 Architecture
 
 ```
 Browser (your React app)
@@ -47,11 +231,9 @@ Your push server (Node, Cloudflare Worker, Lambda, etc.)
   └── Sends push payload via web-push lib → browser
 ```
 
-Three pieces, all yours: client SW, push server, webhook integration. CometChat doesn't host the push server for you — its dashboard's "PushPlatform" config is for FCM/APNs (mobile), not Web Push.
+Three pieces, all yours: client SW, push server, webhook integration.
 
----
-
-## 2. Generate VAPID keys (server-side, one-time)
+### 3.2 Generate VAPID keys (server-side, one-time)
 
 VAPID = Voluntary Application Server Identification — proves to the browser that the push originated from an authorized server.
 
@@ -69,11 +251,9 @@ Private Key: 9tT...
 
 Public key → client (env var). Private key → push server only (never ship to client).
 
----
-
-## 3. Service Worker
+### 3.3 Service Worker
 
-### `public/sw.js` (Vite / CRA / React Router) or `app/sw.js` (Next.js / Astro)
+#### `public/sw.js` (Vite / CRA / React Router) or `app/sw.js` (Next.js / Astro)
 
 ```js
 // Fired when a push payload arrives
@@ -135,9 +315,7 @@ self.addEventListener("notificationclose", (event) => {
 });
 ```
 
----
-
-## 4. Client-side registration
+### 3.4 Client-side registration (self-hosted)
 
 ```ts
 // cometchat/registerWebPush.ts
@@ -193,11 +371,9 @@ useEffect(() => {
 }, [user]);
 ```
 
-**The permission prompt rule:** Chrome / Firefox / Safari all require permission requests in response to a user gesture. If you call `Notification.requestPermission()` from a top-level `useEffect` that runs on page load, browsers reject it. Best pattern: a "Enable notifications" button the user clicks once.
-
----
+The permission-prompt rule (§2) applies here too — request permission from a user gesture, not page load.
 
-## 5. Listen for SW messages in the React app
+### 3.5 Listen for SW messages in the React app
 
 ```tsx
 // CometChatProvider.tsx
@@ -216,9 +392,7 @@ useEffect(() => {
 
 When the SW posts `open_conversation`, the React app navigates to the right thread.
 
----
-
-## 6. Server-side push send
+### 3.6 Server-side push send
 
 Your push server runs on Node.js / Cloudflare Worker / Lambda / Vercel Functions. The shape:
 
@@ -287,9 +461,7 @@ app.listen(3000);
 
 The skill writes a starter version of this server file (`server/push.example.ts`) with a README pointing at env vars; the user owns the actual deployment.
 
----
-
-## 7. CometChat webhook setup (manual)
+### 3.7 CometChat webhook setup (manual)
 
 In the CometChat dashboard:
 
@@ -301,9 +473,7 @@ In the CometChat dashboard:
 
 The webhook fires for EVERY message — your server filters out the sender, dedupes per conversation, and respects user notification preferences.
 
----
-
-## 8. Webhook signature verification
+### 3.8 Webhook signature verification
 
 ```ts
 import crypto from "crypto";
@@ -323,7 +493,7 @@ Without this, anyone with your endpoint URL can flood your users with fake notif
 
 ---
 
-## 9. Browser support matrix + iOS PWA caveat
+## 4. Browser support matrix + iOS PWA caveat (both paths)
 
 | Browser | Web Push | Notification while closed | Notes |
 |---|---|---|---|
@@ -335,7 +505,7 @@ Without this, anyone with your endpoint URL can flood your users with fake notif
 | Chrome mobile | ✓ | ✓ | Aggressive throttling on Android |
 | Edge mobile | ✓ | ✓ | Same as Chrome mobile |
 
-**iOS PWA-only requirement:** iOS 16.4+ supports Web Push, but ONLY for sites added to the Home Screen as a PWA. Safari-the-browser-app does NOT receive Web Push. To unlock iOS Web Push:
+**iOS PWA-only requirement (applies to FCM_WEB too):** iOS 16.4+ supports web push, but ONLY for sites added to the Home Screen as a PWA. Safari-the-browser-app does NOT receive push. This is platform-level and applies equally to the FCM_WEB path (§1) and the self-hosted path (§3). To unlock iOS web push:
 
 1. App must have a `manifest.json` (PWA manifest)
 2. User must use Safari → Share → "Add to Home Screen"
@@ -345,39 +515,41 @@ This is a real production constraint. The skill detects whether the project ship
 
 ---
 
-## 10. Framework-specific Service Worker registration
+## 5. Framework-specific service worker placement (both paths)
+
+The FCM service worker (`firebase-messaging-sw.js`, §1) and the self-hosted SW (`sw.js`, §3) follow the same placement rules.
 
 ### Vite / React (CRA)
 
-`public/sw.js` is served from `/sw.js`. `register("/sw.js")` works directly.
+`public/firebase-messaging-sw.js` (or `public/sw.js`) is served from the origin root. `register("/firebase-messaging-sw.js")` works directly.
 
 ### Next.js (App Router)
 
-Service Workers + Next.js have a known gotcha: the SW can't be inside `app/` because Next handles those routes. Place it in `public/sw.js` and serve from `/sw.js`. Register from a `"use client"` component that runs after hydration.
+Service Workers + Next.js have a known gotcha: the SW can't be inside `app/` because Next handles those routes. Place it in `public/` and serve from the origin root. Register from a `"use client"` component that runs after hydration.
 
 ### Next.js (Pages Router)
 
-Same — `public/sw.js`.
+Same — `public/`.
 
 ### React Router
 
-`public/sw.js` works. If using SSR (loaders), the SW registration code must be guarded by `typeof window !== "undefined"`.
+`public/` works. If using SSR (loaders), the SW registration code must be guarded by `typeof window !== "undefined"`.
 
 ### Astro
 
-Place the SW at `public/sw.js`. Register from a `client:only="react"` island.
+Place the SW at `public/`. Register from a `client:only="react"` island.
 
 The framework-specific patterns skills cover the SSR guards in detail.
 
 ---
 
-## 11. HTTPS requirement
+## 6. HTTPS requirement (both paths)
 
-Service Workers + Push API both require HTTPS (or `localhost` for dev). The skill detects the dev server protocol and warns:
+Service Workers + Push API + FCM all require HTTPS (or `localhost` for dev). The skill detects the dev server protocol and warns:
 
 ```
-⚠️  Web Push requires HTTPS or localhost. Your dev server is running on http://192.168.x.x.
-   Web Push subscriptions will fail. Either:
+⚠️  Web push requires HTTPS or localhost. Your dev server is running on http://192.168.x.x.
+   Push subscriptions will fail. Either:
    - Use http://localhost (Chrome/Firefox/Safari all allow Push API on localhost), or
    - Set up HTTPS dev (mkcert, ngrok, or Vite's --https flag)
 ```
@@ -386,19 +558,23 @@ For production, the Vercel / Netlify / Cloudflare default deploys are HTTPS —
 
 ---
 
-## 12. Anti-patterns
+## 7. Anti-patterns
 
-1. **Calling `Notification.requestPermission()` on page load.** Browsers reject this. Wire to a user-clicked "Enable notifications" button.
-2. **Sending the Auth Key in push payloads.** Push payloads are visible in the SW; never include credentials. Use the user's UID as a key into your server's session store.
-3. **Missing webhook signature verification.** Without HMAC verification, anyone with the URL can spoof notifications.
-4. **Showing notifications even when the chat tab is open.** Check `clients.matchAll()` from the SW and skip if the user already has the chat focused.
-5. **Skipping the iOS PWA warning.** iOS users will silently get nothing. The skill explicitly tells them to "Add to Home Screen."
-6. **Service Worker registered before login completes.** Race conditions where the subscription exists but the server doesn't know whose UID it belongs to. Register from inside the auth state effect.
-7. **Forgetting subscription cleanup on logout.** The previous user's subscription keeps notifying them with the new user's messages. Call `subscription.unsubscribe()` and DELETE the server record on logout.
+1. **Believing "the web has no CometChat push."** It does — `CometChatNotifications.registerPushToken(token, PushPlatforms.FCM_WEB)` + a dashboard FCM provider (§1). Don't hand-roll a push server unless you've ruled out Firebase.
+2. **Inventing SDK symbols.** There is no `PNPlatform`, no `PushNotificationOptions`. The real names are `CometChatNotifications` and `PushPlatforms` (only member: `FCM_WEB`).
+3. **Calling `registerPushToken` before login.** It binds to the current logged-in user's auth token — call it only after `CometChatUIKit.login(...)` resolves.
+4. **Calling `Notification.requestPermission()` on page load.** Browsers reject this. Wire to a user-clicked "Enable notifications" button (§2).
+5. **Self-hosted path: sending the Auth Key in push payloads.** Payloads are visible in the SW; never include credentials. Use the user's UID as a key into your server's session store.
+6. **Self-hosted path: missing webhook signature verification.** Without HMAC verification, anyone with the URL can spoof notifications.
+7. **Showing notifications even when the chat tab is open.** Check `clients.matchAll()` (self-hosted) or `document.visibilityState` in `onMessage` (FCM) and skip if the user already has the chat focused.
+8. **Skipping the iOS PWA warning.** iOS users will silently get nothing. Tell them to "Add to Home Screen."
+9. **Forgetting cleanup on logout.** FCM path: call `CometChatNotifications.unregisterPushToken()` (§1.6). Self-hosted path: `subscription.unsubscribe()` + DELETE the server record (§8). Otherwise the previous user keeps getting the new user's messages.
 
 ---
 
-## 13. Logout cleanup
+## 8. Self-hosted logout cleanup
+
+(FCM_WEB logout uses `CometChatNotifications.unregisterPushToken()` — see §1.6. This is the self-hosted equivalent.)
 
 ```ts
 async function unsubscribeWebPush(uid: string): Promise<void> {
@@ -420,29 +596,39 @@ Call this from your logout flow before `CometChat.logout()`.
 
 ---
 
-## 14. Verification checklist
+## 9. Verification checklist
+
+**Recommended FCM_WEB path (§1):**
+- [ ] `firebase` installed; `firebaseApp` initialized with the web SDK config
+- [ ] Firebase Web Push certificate generated and wired as `getToken({ vapidKey })`
+- [ ] `public/firebase-messaging-sw.js` at origin root, handles `onBackgroundMessage` + `notificationclick`
+- [ ] `Notification.requestPermission()` triggered from a user gesture, not page load (§2)
+- [ ] `CometChatNotifications.registerPushToken(token, CometChatNotifications.PushPlatforms.FCM_WEB)` called AFTER `CometChatUIKit.login(...)` resolves
+- [ ] FCM provider configured in the CometChat dashboard (Notifications → Push)
+- [ ] Foreground `onMessage` does NOT pop an OS notification when the tab is focused
+- [ ] Logout flow calls `CometChatNotifications.unregisterPushToken()` before `CometChat.logout()`
+- [ ] No phantom symbols (`PNPlatform` / `PushNotificationOptions`) anywhere
 
-- [ ] `public/sw.js` (or framework equivalent) exists and listens for `push` + `notificationclick` events
-- [ ] VAPID public key in client env vars (correct framework prefix)
-- [ ] VAPID private key in server env, NOT client
-- [ ] `Notification.requestPermission()` triggered from a user gesture, not page load
-- [ ] Push subscription registered AFTER login resolves
+**Common to both paths:**
+- [ ] HTTPS or localhost only (warned otherwise)
+- [ ] `manifest.json` shipped if iOS users are expected (PWA caveat, §4)
+- [ ] Notifications dedupe per conversation via `tag` field
+
+**Self-hosted fallback path (§3) only:**
+- [ ] `public/sw.js` exists and listens for `push` + `notificationclick` events
+- [ ] VAPID public key in client env vars; private key in server env, NOT client
 - [ ] Subscription POSTed to your push server, keyed by CometChat UID
 - [ ] CometChat dashboard webhook configured for `Message sent` events
 - [ ] Webhook signature verification on the push server (HMAC SHA256)
-- [ ] Notifications dedupe per conversation via `tag` field
-- [ ] `notificationclick` focuses existing tab via `clients.matchAll` OR opens new tab
-- [ ] Foreground tab does NOT show notifications (check tab focus before `showNotification`)
 - [ ] Logout flow calls `subscription.unsubscribe()` and deletes server record
-- [ ] HTTPS or localhost only (warned otherwise)
-- [ ] `manifest.json` shipped if iOS users are expected (PWA caveat)
 - [ ] Server cleanup of dead subscriptions on 410 response
 
 ---
 
-## 15. Pointers
+## 10. Pointers
 
 - `cometchat-react-calls/references/voip-and-web-push.md` — Web Push for incoming calls (overlap; both can coexist on the same SW)
 - `cometchat-{react,nextjs,react-router,astro}-patterns` — framework-specific SSR handling
 - `cometchat-production` — auth tokens, security
-- `cometchat-troubleshooting` — Web Push debugging (chrome://serviceworker-internals, Firefox about:debugging)
+- `cometchat-troubleshooting` — web push debugging (chrome://serviceworker-internals, Firefox about:debugging)
+- Firebase Cloud Messaging for Web — https://firebase.google.com/docs/cloud-messaging/js/client

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

@@ -3,13 +3,14 @@ name: cometchat-react-router-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into React Router projects (v6 library mode and v7 framework mode). Covers SSR prevention, routing patterns, outlet nesting, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; react-router-dom ^6 or react-router ^7; @cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "chat cometchat react-router remix routing ssr patterns"
 ---
 
+> **Ground truth:** `@cometchat/chat-uikit-react@^6` (+ `@cometchat/calls-sdk-javascript@^5`) — installed package types + `ui-kit/react`. **Official docs:** https://www.cometchat.com/docs/ui-kit/react/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+
 ## Purpose
 
 This skill teaches Claude how to integrate CometChat into React Router projects. React Router exists in two distinct modes with very different integration patterns:
@@ -193,15 +194,20 @@ export default function ConversationView() {
   useEffect(() => {
     if (!conversationId) return;
 
-    // Conversation IDs follow the pattern: "user_<uid>" or "group_<guid>"
+    // NOTE: this `:conversationId` param is OUR custom URL scheme — the prefix is
+    // chosen by the navigate() in ConversationsList below ("user_<uid>" / "group_<guid>").
+    // Do NOT confuse it with CometChat's raw Conversation.getConversationId(), which
+    // for a 1:1 is "<loggedInUid>_user_<peerUid>" (the "_user_" sits in the MIDDLE,
+    // so startsWith("user_") would never match it). Both ends must agree on the
+    // custom scheme; branch only on that prefix here.
     if (conversationId.startsWith("user_")) {
-      const uid = conversationId.replace("user_", "");
+      const uid = conversationId.slice("user_".length);
       CometChat.getUser(uid).then((u) => {
         setUser(u);
         setGroup(undefined);
       });
     } else if (conversationId.startsWith("group_")) {
-      const guid = conversationId.replace("group_", "");
+      const guid = conversationId.slice("group_".length);
       CometChat.getGroup(guid).then((g) => {
         setUser(undefined);
         setGroup(g);
@@ -697,7 +703,7 @@ Do not mix v6 and v7 patterns. Detect the mode (section 1) and use the correct p
 
 ## 8. Complete integration checklist (v6 library mode)
 
-1. Install packages: `npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript`
+1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
 2. Create `.env` with `VITE_COMETCHAT_APP_ID`, `VITE_COMETCHAT_REGION`, `VITE_COMETCHAT_AUTH_KEY`
 3. Add `.env` to `.gitignore`
 4. Import `@cometchat/chat-uikit-react/css-variables.css` in `src/main.tsx`
@@ -709,7 +715,7 @@ Do not mix v6 and v7 patterns. Detect the mode (section 1) and use the correct p
 
 ## 9. Complete integration checklist (v7 framework mode)
 
-1. Install packages: `npm install @cometchat/chat-uikit-react @cometchat/chat-sdk-javascript`
+1. Install packages: `npm install @cometchat/chat-uikit-react@^6 @cometchat/chat-sdk-javascript@^4` — **⚠️ keep the `@^6` major pin; never install bare.** v7 is on npm — a bare `npm install @cometchat/chat-uikit-react` pulls it once it's tagged `latest`, and these v6 skills break against the v7 API.
 2. Create `.env` with `VITE_COMETCHAT_APP_ID`, `VITE_COMETCHAT_REGION`, `VITE_COMETCHAT_AUTH_KEY`
 3. Add `.env` to `.gitignore`
 4. Import `@cometchat/chat-uikit-react/css-variables.css` in `app/root.tsx`

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

@@ -3,7 +3,6 @@ name: cometchat-react-testing
 description: Testing patterns for CometChat React UI Kit v6 in Vite / Next.js / React Router / Astro projects. Covers Vitest + React Testing Library setup, mocking @cometchat/chat-sdk-javascript and @cometchat/chat-uikit-react, Playwright e2e for full chat flows, the chat-specific assertions (init resolves before render, error UI visible, no Auth Key in test files, css-variables.css imported once), and CI configuration. Sister skill of cometchat-react-calls/references/testing-calls-on-web.md.
 license: "MIT"
 compatibility: "React >= 18, Vitest >= 1, Vite >= 5, @testing-library/react >= 14, Playwright >= 1.40; @cometchat/chat-uikit-react ^6.x"
-allowed-tools: "shell, file-read, file-search, file-list, ask-user"
 metadata:
   author: "CometChat"
   version: "4.0.0"
@@ -19,7 +18,7 @@ Test recipes for CometChat React UI Kit integrations. Three layers — unit, com
 - `cometchat-{react,nextjs,react-router,astro}-patterns` — framework-specific render gates
 - `cometchat-react-calls/references/testing-calls-on-web.md` — the calls-specific testing patterns (this skill is for chat)
 
-**Ground truth:**
+**Ground truth:** **Official docs:** https://www.cometchat.com/docs/ui-kit/react/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP).
 - Vitest docs — https://vitest.dev/
 - React Testing Library — https://testing-library.com/docs/react-testing-library/intro
 - Playwright — https://playwright.dev/
@@ -112,7 +111,9 @@ vi.mock("@cometchat/chat-sdk-javascript", () => ({
       setRegion() { return this; }
       build() { return {}; }
     },
-    REGION: { US: "us", EU: "eu", IN: "in" },
+    // Regions are flat string statics (REGION_US/REGION_EU/REGION_IN) — there is
+    // no CometChat.REGION object. Pass the region as a plain string ("us"/"eu"/"in").
+    REGION_US: "us", REGION_EU: "eu", REGION_IN: "in",
   },
 }));
 
@@ -136,7 +137,8 @@ vi.mock("@cometchat/chat-uikit-react", () => ({
   CometChatUsers: () => null,
   CometChatGroups: () => null,
   CometChatIncomingCall: () => null,
-  CometChatThemeProvider: ({ children }: { children: React.ReactNode }) => children,
+  // NOTE: the v6 web kit has NO CometChatThemeProvider (theming is CSS-variable
+  // based) — don't mock a component that doesn't exist.
 }));
 ```
 
@@ -150,7 +152,8 @@ import "./mocks/cometchat";
 
 Override specific behaviors:
 
-```ts
+```tsx
+import { render, screen } from "@testing-library/react";
 import { CometChat } from "@cometchat/chat-sdk-javascript";
 
 it("shows error when login fails", async () => {
@@ -321,6 +324,12 @@ test("two users send messages back and forth", async ({ browser }) => {
 
 The 10-second timeout is generous — message delivery via WebSocket is usually <500ms but CI hosts have variable latency.
 
+> **Composer selectors (v6 DOM — for E2E only).** The example above uses role/placeholder selectors for readability, but the v6 kit (`@cometchat/chat-uikit-react@6.5.1`) renders the message input as a **`contenteditable` div, not a `<textarea>`** — driving it with `.fill()` on a placeholder/role can fail with "no input found". The reliable selectors (verified live, 2026-06-14):
+> - input: `.cometchat-message-composer__input[contenteditable="plaintext-only"]` → focus it, then `page.keyboard.type("…")` (or `locator.fill()` works on the contenteditable in Playwright ≥1.4x)
+> - send button: `.cometchat-message-composer__send-button`
+>
+> This is a **testing-only** fact about the rendered DOM — the §8.7 rule "never target internal `cometchat-*` class names for **styling**" still stands; for styling use the CSS variables. (Real-time delivery between two live clients measured ~1.0–1.3s reload-free in this setup.)
+
 ### Test users
 
 CometChat dev mode pre-seeds five test users (`cometchat-uid-1` through `cometchat-uid-5`). Use them in e2e — never create new users in the test app via `Auth Key` flows that leak credentials.