@cometchat/skills 4.0.0 → 4.2.0

package/skills/cometchat-react-calls/references/testing-calls-on-web.md

@@ -0,0 +1,198 @@
+# Testing calls on web
+
+Calls are the hardest CometChat surface to unit-test because they touch native browser APIs (`getUserMedia`, `RTCPeerConnection`) that don't exist in jsdom. Three layers, three strategies:
+
+1. **Unit tests** — mock the entire Calls SDK; assert your code calls the right methods in the right order.
+2. **Component tests** — Vitest + React Testing Library; mock `getUserMedia` and `RTCPeerConnection`; assert your custom UI renders correctly given mocked SDK events.
+3. **E2E tests** — Playwright with the headless WebRTC flag; real two-tab call between two test users.
+
+This reference covers all three. For chat-side testing patterns, see `cometchat-react-testing` (sibling skill).
+
+---
+
+## 1. Unit tests — mock the SDK module
+
+Vitest's `vi.mock` with a hoisted factory:
+
+```ts
+// __tests__/CallButton.test.tsx
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
+import { CallButton } from "../src/components/CallButton";
+
+vi.mock("@cometchat/chat-sdk-javascript", () => ({
+  CometChat: {
+    initiateCall: vi.fn().mockResolvedValue({ getSessionId: () => "session-123" }),
+    Call: vi.fn((uid, type, recv) => ({ uid, type, recv })),
+    CALL_TYPE: { VOICE: "voice", VIDEO: "video" },
+    RECEIVER_TYPE: { USER: "user" },
+  },
+}));
+
+vi.mock("@cometchat/calls-sdk-javascript", () => ({
+  CometChatCalls: {
+    init: vi.fn(),
+    generateToken: vi.fn().mockResolvedValue({ token: "rtc-token" }),
+    startSession: vi.fn(),
+    endSession: vi.fn(),
+    CallSettingsBuilder: class {
+      setSessionID() { return this; }
+      setIsAudioOnly() { return this; }
+      enableDefaultLayout() { return this; }
+      build() { return {}; }
+    },
+  },
+}));
+
+beforeEach(() => vi.clearAllMocks());
+
+describe("CallButton", () => {
+  it("initiates a video call when video button clicked", async () => {
+    const { CometChat } = await import("@cometchat/chat-sdk-javascript");
+    render(<CallButton user={{ uid: "alice" }} />);
+
+    await fireEvent.click(screen.getByLabelText("Start video call"));
+
+    expect(CometChat.initiateCall).toHaveBeenCalledWith(
+      expect.objectContaining({ uid: "alice", type: "video" }),
+    );
+  });
+});
+```
+
+---
+
+## 2. Component tests — mock `getUserMedia` + `RTCPeerConnection`
+
+For tests that exercise your custom UI's reaction to track-arrived events:
+
+```ts
+// vitest.setup.ts
+import { vi } from "vitest";
+
+beforeAll(() => {
+  // jsdom doesn't have navigator.mediaDevices — polyfill it
+  Object.defineProperty(navigator, "mediaDevices", {
+    writable: true,
+    value: {
+      getUserMedia: vi.fn().mockResolvedValue({
+        getTracks: () => [
+          { kind: "audio", stop: vi.fn() },
+          { kind: "video", stop: vi.fn() },
+        ],
+      }),
+      getDisplayMedia: vi.fn().mockResolvedValue({ getTracks: () => [{ stop: vi.fn() }] }),
+      enumerateDevices: vi.fn().mockResolvedValue([]),
+    },
+  });
+
+  // Polyfill RTCPeerConnection
+  (global as Record<string, unknown>).RTCPeerConnection = class {
+    addTrack = vi.fn();
+    addEventListener = vi.fn();
+    createOffer = vi.fn().mockResolvedValue({ sdp: "fake-offer", type: "offer" });
+    createAnswer = vi.fn().mockResolvedValue({ sdp: "fake-answer", type: "answer" });
+    setLocalDescription = vi.fn();
+    setRemoteDescription = vi.fn();
+    close = vi.fn();
+  };
+});
+```
+
+Reference this in `vitest.config.ts`:
+
+```ts
+export default defineConfig({
+  test: {
+    setupFiles: ["./vitest.setup.ts"],
+    environment: "jsdom",
+  },
+});
+```
+
+---
+
+## 3. E2E tests — Playwright with WebRTC enabled
+
+Playwright supports real WebRTC in headless mode with the right Chromium flag:
+
+```ts
+// playwright.config.ts
+import { defineConfig } from "@playwright/test";
+
+export default defineConfig({
+  use: {
+    launchOptions: {
+      args: [
+        "--use-fake-ui-for-media-stream",          // auto-grants getUserMedia
+        "--use-fake-device-for-media-stream",      // synthetic camera (animated pattern)
+        "--allow-running-insecure-content",
+      ],
+    },
+  },
+});
+```
+
+Then a two-page test exercises the full call flow:
+
+```ts
+import { test, expect, type Page } from "@playwright/test";
+
+async function login(page: Page, uid: string) {
+  await page.goto("/");
+  await page.evaluate((uid) => localStorage.setItem("cc-test-uid", uid), uid);
+  await page.reload();
+  await expect(page.getByTestId("logged-in-banner")).toBeVisible();
+}
+
+test("alice calls bob; bob answers; both see two-way video", async ({ browser }) => {
+  const aliceCtx = await browser.newContext();
+  const bobCtx = await browser.newContext();
+  const alice = await aliceCtx.newPage();
+  const bob = await bobCtx.newPage();
+
+  await login(alice, "cometchat-uid-1");
+  await login(bob, "cometchat-uid-2");
+
+  // Alice clicks call on Bob's profile
+  await alice.goto("/users/cometchat-uid-2");
+  await alice.getByLabel("Start video call").click();
+
+  // Bob's IncomingCall overlay appears
+  await expect(bob.getByText("Incoming call from")).toBeVisible({ timeout: 10_000 });
+  await bob.getByRole("button", { name: "Accept" }).click();
+
+  // Both see the ongoing-call view
+  await expect(alice.getByTestId("ongoing-call")).toBeVisible();
+  await expect(bob.getByTestId("ongoing-call")).toBeVisible();
+
+  // Verify two video elements are playing (synthetic streams)
+  const aliceVideos = await alice.locator("video").count();
+  expect(aliceVideos).toBeGreaterThanOrEqual(2);   // local + remote
+
+  // Hangup
+  await alice.getByRole("button", { name: "End" }).click();
+  await expect(alice.getByTestId("ongoing-call")).not.toBeVisible();
+  await expect(bob.getByTestId("ongoing-call")).not.toBeVisible();
+});
+```
+
+**Synthetic stream gotcha:** the `--use-fake-device-for-media-stream` flag makes Chrome stream a green-and-blue animated pattern. Real cameras / mics are NOT used, so you cannot assert "this video shows the user's face." You CAN assert "two video elements with `srcObject` set," which is what 90% of tests need.
+
+---
+
+## CI gotchas
+
+- **Linux GPU + WebRTC:** GitHub Actions Ubuntu runners have headless Chrome but no GPU. Pass `--disable-gpu` if you see WebRTC errors about GPU process crash; the synthetic stream still works.
+- **Test isolation:** real CometChat App ID + Auth Key in CI. Use a dedicated test app (Dashboard → New App → "ci-tests"); don't reuse production credentials.
+- **Rate limits:** the CometChat backend rate-limits `initiateCall` per user. Tests that loop call/hangup quickly hit limits; throttle to ~5 calls/minute per test UID or rotate UIDs (`cometchat-uid-1` through `cometchat-uid-5` are pre-seeded).
+- **Cleanup:** kill any active calls between tests via `CometChatCalls.leaveSession()` in afterEach. Stale sessions cause the next test's `initiateCall` to fail.
+
+---
+
+## What NOT to mock
+
+- **Don't mock `useEffect` cleanup.** It's where rule 1.3's track-stop happens; mocking hides bugs in the cleanup path.
+- **Don't mock `navigator.mediaDevices` to return synchronous values.** Real APIs are async; mocks should be too, otherwise you mask race conditions in your real code.
+- **Don't mock the kit components themselves** (`<CometChatIncomingCall />` etc.) for unit tests — they're tested by CometChat. Mock the SDK that the kit calls.

package/skills/cometchat-react-calls/references/voip-and-web-push.md

@@ -0,0 +1,165 @@
+# VoIP push on web — there isn't any
+
+Web browsers do not have VoIP push. You cannot ring a user whose tab is closed. The closest equivalents are:
+
+1. **Web Push** (Service Worker + Push API + Notification API) — can fire a system-level notification while the browser is open even if the tab is backgrounded. Limitations:
+   - Service Worker must be installed (one prior visit required)
+   - User must have granted notification permission
+   - Browser must be running (Chrome/Edge can deliver to closed tabs IF the browser process is alive; Safari requires Safari to be running; Firefox stops Service Workers aggressively)
+   - Does NOT bypass closed browser. Production calling apps on web pair this with email/SMS fallback for missed calls.
+
+2. **Email/SMS missed-call fallback** — server-side. When a call rings unanswered for ~30 seconds, send a "missed call from X" email/SMS with a deep link back into the app.
+
+This reference covers Web Push end-to-end. Email/SMS is out of scope (server-side only, not skill-scaffoldable).
+
+---
+
+## Web Push setup (Service Worker + push subscription)
+
+### 1. Generate VAPID keys (server-side, one-time)
+
+```bash
+npx web-push generate-vapid-keys
+```
+
+Stores public + private keys. Public goes to the client; private stays on the push server.
+
+### 2. Register the Service Worker
+
+`public/sw.js`:
+
+```js
+self.addEventListener("push", (event) => {
+  if (!event.data) return;
+  const payload = event.data.json();
+  if (payload.type !== "incoming_call") return;
+
+  event.waitUntil(
+    self.registration.showNotification("Incoming call", {
+      body: `${payload.callerName} is calling`,
+      icon: "/icons/call.png",
+      tag: `call-${payload.sessionId}`,           // dedupe — only one ring per session
+      requireInteraction: true,                    // don't auto-dismiss
+      data: { sessionId: payload.sessionId, callerUid: payload.callerUid },
+    }),
+  );
+});
+
+self.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  event.waitUntil(
+    clients.matchAll({ type: "window", includeUncontrolled: true }).then((wins) => {
+      // Focus existing tab if open, otherwise open a new one
+      for (const w of wins) {
+        if (w.url.includes(self.registration.scope)) {
+          w.focus();
+          w.postMessage({ type: "incoming_call_click", ...event.notification.data });
+          return;
+        }
+      }
+      return clients.openWindow(`/calls/incoming?sessionId=${event.notification.data.sessionId}`);
+    }),
+  );
+});
+```
+
+### 3. Register from the app
+
+```ts
+// cometchat/registerWebPush.ts
+const VAPID_PUBLIC = import.meta.env.VITE_VAPID_PUBLIC_KEY;
+
+export async function registerWebPushForCalls(uid: string): Promise<void> {
+  if (!("serviceWorker" in navigator) || !("PushManager" in window)) return;
+
+  const reg = await navigator.serviceWorker.register("/sw.js");
+  const permission = await Notification.requestPermission();
+  if (permission !== "granted") return;
+
+  const subscription = await reg.pushManager.subscribe({
+    userVisibleOnly: true,
+    applicationServerKey: urlBase64ToUint8Array(VAPID_PUBLIC),
+  });
+
+  // Send subscription to YOUR server, keyed by uid
+  await fetch("/api/push/subscribe", {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ uid, subscription }),
+  });
+}
+
+function urlBase64ToUint8Array(base64: string): Uint8Array {
+  const padding = "=".repeat((4 - (base64.length % 4)) % 4);
+  const raw = atob((base64 + padding).replace(/-/g, "+").replace(/_/g, "/"));
+  return Uint8Array.from(raw, (c) => c.charCodeAt(0));
+}
+```
+
+### 4. Listen for SW messages in your React app
+
+```tsx
+// CometChatProvider.tsx
+useEffect(() => {
+  const handler = (event: MessageEvent) => {
+    if (event.data?.type === "incoming_call_click") {
+      // Navigate to the call screen and let CometChatIncomingCall pick it up
+      navigate(`/calls/incoming?sessionId=${event.data.sessionId}`);
+    }
+  };
+  navigator.serviceWorker.addEventListener("message", handler);
+  return () => navigator.serviceWorker.removeEventListener("message", handler);
+}, [navigate]);
+```
+
+### 5. Server-side push send (signaling integration)
+
+Your CometChat backend (or webhook listener) detects an incoming call event and sends Web Push to the receiver's subscription:
+
+```ts
+// server (Node.js) — runs when CometChat fires the call.received webhook
+import webpush from "web-push";
+
+webpush.setVapidDetails("mailto:you@example.com", VAPID_PUBLIC, VAPID_PRIVATE);
+
+async function sendIncomingCallPush(receiverUid: string, sessionId: string, callerName: string, callerUid: string) {
+  const subs = await getSubscriptionsForUid(receiverUid);  // your DB
+  await Promise.allSettled(
+    subs.map((sub) =>
+      webpush.sendNotification(sub, JSON.stringify({
+        type: "incoming_call",
+        sessionId,
+        callerName,
+        callerUid,
+      })),
+    ),
+  );
+}
+```
+
+The webhook setup itself is server-side; the skill scaffolds the client side and points users at this template for the server.
+
+---
+
+## Browser support matrix
+
+| Browser | Push API | Notification while tab closed | Service Worker terminated background |
+|---|---|---|---|
+| Chrome/Edge desktop | ✓ | ✓ if browser process alive | After ~30s idle |
+| Chrome/Edge mobile | ✓ | ✓ | Aggressive; Web Push is best-effort |
+| Firefox desktop | ✓ | ✓ | After ~30s idle |
+| Safari 16+ desktop | ✓ | ✓ if Safari running | Tighter |
+| Safari iOS 16.4+ | ✓ | Only when added to Home Screen as PWA | N/A — PWA only |
+| Mobile Web (any) | Limited | Often not delivered when browser killed | OS-driven |
+
+**Bottom line:** Web Push is "best-effort ring" — it works often enough to be worth wiring, but production calling apps must have a missed-call email/SMS fallback. The skill warns the user about this explicitly during scaffold.
+
+---
+
+## When NOT to bother with Web Push
+
+- Internal tools where users keep the tab open during work hours — `<CometChatIncomingCall />` mounted at root rings the tab itself, which is enough.
+- Apps where the call surface is a route the user navigates to deliberately (telehealth waiting room) — the ring happens when they arrive on the route; they don't need to be paged.
+- Greenfield projects that haven't shipped to production yet — add it later when missed-calls become a real complaint.
+
+The dispatcher's Step 3 in `cometchat-react-calls/SKILL.md` asks the user whether to scaffold Web Push. Default = no for "just exploring" / "messaging app" intents; default = yes for "support" / "marketplace" intents (where users may receive a call without expecting it).

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

@@ -3,7 +3,7 @@ name: cometchat-react-patterns
 description: "Framework-specific patterns for integrating CometChat React UI Kit v6 into React projects (Vite or CRA). Covers provider setup, routing, layout integration, env vars, and common pitfalls."
 license: "MIT"
 compatibility: "Node.js >=18; React >=18; Vite >=4 or react-scripts (CRA); @cometchat/chat-uikit-react ^6; @cometchat/chat-sdk-javascript ^4"
-allowed-tools: "executeBash, readFile, fileSearch, listDirectory"
+allowed-tools: "shell, file-read, file-search, file-list"
 metadata:
   author: "CometChat"
   version: "3.0.0"
@@ -468,30 +468,78 @@ Vite's HMR replaces modules without a full page reload. CometChat's SDK holds a
 
 However, if you change the provider file itself during development, HMR may re-execute the module. The `initialized` flag prevents double-init, but the WebSocket connection from the previous module instance may linger. If you see duplicate messages or connection issues during development, do a full page reload (`Ctrl+Shift+R`).
 
-### Container height
+### Container height (and the flex-shrink trap that breaks chat layouts)
 
-CometChat components fill 100% of their container. The most common visual bug is components rendering with zero height because their container has no explicit dimensions. Always ensure the chat container has a height:
+CometChat components fill 100% of their container. Two visual bugs to avoid:
+
+**Bug 1 — zero height:** components render with zero height because the container has no explicit dimensions.
+**Bug 2 — message list grows past the viewport:** the list scrolls fine until it has too many messages, then pushes the composer below the fold. **This is the classic flex-shrink trap.**
+
+The hard rule for two-pane / header+list+composer layouts: every flex container in the chain MUST have `minHeight: 0` (and `minWidth: 0` for horizontal flex). Without it, browsers default flex-children to `min-height: auto` (their intrinsic content size), so the list grows beyond the parent's bounds as messages accumulate.
 
 ```tsx
-/* CORRECT: explicit height */
+/* ✓ CORRECT: explicit height for a single-component surface */
 <div style={{ height: "100vh" }}>
   <CometChatConversations ... />
 </div>
 
-/* CORRECT: flex layout with bounded parent */
+/* ✓ CORRECT: header + list + composer with the flex-shrink trap fixed */
 <div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
   <nav>...</nav>
-  <div style={{ flex: 1 }}>
-    <CometChatConversations ... />
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minHeight: 0,        // ← THIS IS THE HARD RULE — without it, list grows past the viewport
+  }}>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageHeader user={user} />
+    </div>
+    <div style={{ flex: "1 1 0", minHeight: 0, overflow: "hidden" }}>
+      <CometChatMessageList user={user} />
+    </div>
+    <div style={{ flex: "0 0 auto" }}>
+      <CometChatMessageComposer user={user} />
+    </div>
   </div>
 </div>
 
-/* WRONG: no height constraint -- component collapses to zero */
+/* ✓ CORRECT: two-pane (sidebar + active chat) — both axes need min-{width,height}: 0 */
+<div style={{ display: "flex", height: "100vh" }}>
+  <div style={{ width: 360, display: "flex", flexDirection: "column" }}>
+    <CometChatConversations onItemClick={...} />
+  </div>
+  <div style={{
+    flex: 1,
+    display: "flex",
+    flexDirection: "column",
+    minWidth: 0,         // ← horizontal flex parent: prevents content from forcing horizontal scroll
+    minHeight: 0,        // ← vertical flex (the inner column): prevents the list-overflow bug
+  }}>
+    {/* header / list / composer wrapped as above */}
+  </div>
+</div>
+
+/* ✗ WRONG: no height constraint — component collapses to zero */
 <div>
   <CometChatConversations ... />
 </div>
+
+/* ✗ WRONG: flex parent without minHeight: 0 — list grows past the viewport once
+   you accumulate more messages than fit on-screen. Composer falls off the bottom. */
+<div style={{ display: "flex", flexDirection: "column", height: "100vh" }}>
+  <CometChatMessageHeader user={user} />
+  <CometChatMessageList user={user} />          {/* takes intrinsic content height */}
+  <CometChatMessageComposer user={user} />     {/* gets pushed below the fold */}
+</div>
 ```
 
+**Why `minHeight: 0` is non-obvious:** the W3C spec sets the default `min-height` of a flex item to `auto` (its intrinsic content height). For a scrollable list inside a flex column, this means the list refuses to shrink below its content even when the parent is bounded. Setting `minHeight: 0` on the flex parent overrides this, letting the list shrink and scroll within the bounded container instead of overflowing it.
+
+**The rule, restated as something to grep for:**
+
+> Every flex container that holds `CometChatMessageList` (directly or indirectly) MUST have `minHeight: 0` on it. Same for `minWidth: 0` on horizontal flex parents. Skip this and the layout works for short conversations and breaks for long ones.
+
 ### Vite dependency optimization
 
 Vite pre-bundles dependencies for faster dev startup. CometChat's packages are large and may trigger Vite's "new dependency found, reloading" message on first load. This is normal and only happens once. If it causes issues, you can pre-include the packages: