@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-react-calls/references/custom-ui.md

@@ -1,247 +0,0 @@
-# Custom call UI on web
-
-When the kit's default `<CometChatOngoingCall />` doesn't fit your app's design system, drop down to the Calls SDK directly. Two escalation paths:
-
-1. **Style the kit's component** — pass style props / CSS variable overrides. Cheapest. Covers most cases.
-2. **Build your own surface on the SDK** — drive the session directly with your own DOM container. Maximum control. The kit doesn't render anything; you do.
-
-> ⚠️ **Two join APIs — pick by which settings type you build.** `joinSession(token, sessionSettings, container)` is the v5 canonical and takes a **`SessionSettings` object** (the `hide*` / `sessionType` / `layout` flags). It does **not** accept the output of `CallSettingsBuilder.build()` — those are incompatible types. The `CallSettingsBuilder` (with `enableDefaultLayout(false)`, `setCallListener`, etc.) produces a `CallSettings` consumed only by the **deprecated** `startSession(token, callSettings, container)`. So: **hybrid / hide-chrome custom UI → object + `joinSession`** (preferred); **fully-custom render-your-own-tiles (`enableDefaultLayout(false)`) → builder + `startSession`** (the one path where the deprecated call is still required, because `enableDefaultLayout` lives only on the builder).
-
-This reference covers path 2 — full custom UI on the SDK. Path 1 is in the kit's component documentation (see `cometchat-customization`).
-
----
-
-## Architecture
-
-```
-Your React component
-├── Local user video (mic + camera preview)         ← <video> element + getUserMedia
-├── Remote participant video tile(s)                ← <video> elements piped from Calls SDK
-├── Custom control panel (mute, end, switch cam)    ← buttons calling SDK methods
-└── Layout (full-screen / picture-in-picture / grid) ← your CSS
-```
-
-The Calls SDK gives you:
-
-- A `RTCMultiConnection`-like internal connection it manages
-- Track-add events (when a participant's track arrives)
-- Track-remove events
-- Methods to mute/unmute, switch camera, end session
-- A `htmlElement` you pass to `startSession` — **required** — where the SDK draws the call surface. With `enableDefaultLayout(false)`, the SDK still uses this container for internal video elements; your custom UI overlays on top via absolute positioning, OR you keep the container hidden and use the listener events to drive your own `<video>` elements (advanced; see "Advanced — bypassing the SDK's container" below).
-
----
-
-## Hooking into track events
-
-```tsx
-// CustomOngoingCallView.tsx
-import { useEffect, useRef } from "react";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-interface Props {
-  sessionId: string;
-  authToken: string;
-  onCallEnded: () => void;
-}
-
-export function CustomOngoingCallView({ sessionId, authToken, onCallEnded }: Props) {
-  const localVideoRef = useRef<HTMLVideoElement>(null);
-  const remoteVideoRef = useRef<HTMLVideoElement>(null);
-
-  useEffect(() => {
-    // ⚠️ CometChatCalls.OngoingCallListener is @deprecated (use addEventListener).
-    // It's only here because enableDefaultLayout(false) + startSession require it.
-    const callListener = new CometChatCalls.OngoingCallListener({
-      onUserListUpdated: (userList: unknown) => {
-        // userList = current participants — re-render your custom roster
-      },
-      onCallEnded: () => {
-        cleanup();
-        onCallEnded();
-      },
-      onCallEndButtonPressed: () => {
-        // User clicked YOUR end button — we still have to call endSession
-        CometChatCalls.leaveSession();
-      },
-      onError: (error: unknown) => {
-        console.error("Call error:", error);
-      },
-      onCallSwitchedToVideo: (call: unknown) => {
-        // remote upgraded the call from voice to video
-      },
-      onMediaDeviceListUpdated: (devices: unknown) => {
-        // user plugged in headphones, etc.
-      },
-    });
-
-    // ⚠️ CallSettingsBuilder method names (verified against calls-sdk-javascript@5):
-    //   - there is NO .setSessionID() on the builder — sessionId flows through
-    //     generateToken(sessionId) below, NOT the builder
-    //   - it's .setIsAudioOnlyCall(bool), not .setIsAudioOnly()
-    //   - it's .setCallListener(listener), not .setCallEventListener()
-    const settings = new CometChatCalls.CallSettingsBuilder()
-      .setIsAudioOnlyCall(false)
-      .enableDefaultLayout(false)            // ← key: we render the UI ourselves
-      .setCallListener(callListener)
-      .build();
-
-    // v5 generateToken takes ONLY sessionId — authToken is internal after CometChatCalls.login().
-    CometChatCalls.generateToken(sessionId).then((tokenRes) => {
-      // htmlElement is REQUIRED — pass a container the SDK can draw into.
-      // With custom UI you typically render your own <video> elements; the
-      // container can be hidden but must still be a real DOM node.
-      const container = document.getElementById("calls-container")!;
-      // This example builds CallSettings via CallSettingsBuilder (enableDefaultLayout(false)),
-      // so it MUST use startSession — joinSession only accepts a SessionSettings object,
-      // not the builder's CallSettings output. startSession is deprecated but is the only
-      // consumer of enableDefaultLayout(false)-style fully-custom settings.
-      CometChatCalls.startSession(tokenRes.token, settings, container);
-    });
-
-    return () => cleanup();
-
-    function cleanup() {
-      // leaveSession is v5 canonical — endSession() is deprecated (still works as a shim).
-      CometChatCalls.leaveSession();
-      if (localVideoRef.current) localVideoRef.current.srcObject = null;
-      if (remoteVideoRef.current) remoteVideoRef.current.srcObject = null;
-    }
-  }, [sessionId, authToken, onCallEnded]);
-
-  return (
-    <div className="ongoing-call">
-      <video ref={remoteVideoRef} autoPlay playsInline className="remote-tile" />
-      <video ref={localVideoRef} autoPlay playsInline muted className="local-tile" />
-      <ControlPanel
-        onMute={() => CometChatCalls.muteAudio()}
-        onUnmute={() => CometChatCalls.unmuteAudio()}
-        onCameraOff={() => CometChatCalls.pauseVideo()}
-        onCameraOn={() => CometChatCalls.resumeVideo()}
-        onSwitchCamera={() => CometChatCalls.switchCamera()}
-        onEnd={() => {
-          CometChatCalls.leaveSession();
-          onCallEnded();
-        }}
-      />
-    </div>
-  );
-}
-```
-
----
-
-## Custom control panel — the canonical mute/end/camera buttons
-
-```tsx
-function ControlPanel(props: {
-  onMute: () => void;
-  onUnmute: () => void;
-  onCameraOff: () => void;
-  onCameraOn: () => void;
-  onSwitchCamera: () => void;
-  onEnd: () => void;
-}) {
-  const [muted, setMuted] = useState(false);
-  const [cameraOff, setCameraOff] = useState(false);
-
-  return (
-    <div className="control-panel">
-      <button onClick={() => { muted ? props.onUnmute() : props.onMute(); setMuted(!muted); }}>
-        {muted ? "Unmute" : "Mute"}
-      </button>
-      <button onClick={() => { cameraOff ? props.onCameraOn() : props.onCameraOff(); setCameraOff(!cameraOff); }}>
-        {cameraOff ? "Camera on" : "Camera off"}
-      </button>
-      <button onClick={props.onSwitchCamera}>Switch camera</button>
-      <button onClick={props.onEnd} className="end-call">End</button>
-    </div>
-  );
-}
-```
-
-The SDK methods (`muteAudio`/`unmuteAudio`, `pauseVideo`/`resumeVideo`, `switchCamera`) propagate to all participants via the SDK's signaling — you don't manage track state yourself.
-
-> ⚠️ **These are no-argument methods.** `muteAudio(): void` / `pauseVideo(): void` — there is NO boolean parameter. `CometChatCalls.muteAudio(false)` does **not** unmute (the arg is ignored — it still mutes). Use the explicit pair: `muteAudio()` / `unmuteAudio()` and `pauseVideo()` / `resumeVideo()`. (There is **no** `toggleAudio()` / `toggleVideo()` in the v5 SDK — track the muted/paused state yourself and call the matching method of the pair.)
-
-> ⚠️ **Optimistic local state desyncs.** A control panel that only flips its own `useState` on click (as the example above does) will show a stale label whenever mute/camera/screen-share change from *outside* your bar — a join-muted call (`startAudioMuted`), the browser's own "Stop sharing" button, or another surface. Reconcile by subscribing to the SDK's media events and driving state from them: `onAudioMuted` / `onAudioUnMuted` / `onVideoPaused` / `onVideoResumed` / `onScreenShareStarted` / `onScreenShareStopped` / `onRecordingStarted` / `onRecordingStopped`. Seed the initial state from your join options so the first render is correct too.
-
----
-
-## Two custom-panel models — and the `hideHeaderPanel` footgun
-
-There are **two** ways to put your own controls on a call, and they are very different:
-
-**Model A — fully custom (`enableDefaultLayout(false)`).** The SDK draws nothing; you render every tile, every button, the whole surface. That's the path above. It leans on **two deprecated V5 APIs** — `startSession` (the only consumer of builder-produced `CallSettings`) and the `CometChatCalls.OngoingCallListener` accessor (the SDK marks it `@deprecated → use addEventListener`) — because `enableDefaultLayout(false)` exists only on the builder and has no `SessionSettings`-object equivalent. Use it only when you truly must render your own video tiles, and accept owning a11y, recording/screen-share plumbing, and the eventual migration off these shims. **For everything else, prefer Model B — it's 100% current V5 (`joinSession` + object + `addEventListener`).**
-
-**Model B — hybrid (keep the SDK layout, replace only the bottom bar).** Far cheaper and far more common. You keep the SDK's default layout but pass `SessionSettings` flags to `joinSession` to hide just the control bar, then render your own bar over it:
-
-```ts
-const settings = {
-  sessionType: 'VIDEO',
-  layout: 'TILE',
-  hideControlPanel: true,   // ← hide ONLY the bottom control bar; render your own
-  // hideHeaderPanel: true,  // ← ⚠️ DO NOT add this unless you mean it (see below)
-};
-await CometChatCalls.joinSession(token, settings, container);
-```
-
-> ⚠️ **`hideHeaderPanel: true` silently disables Virtual Background, In-Call Chat, and the Participant List.** Those three features live in the SDK's **header** panel, not the control bar. If you set `hideHeaderPanel: true` to "clean up" a custom-bar call, you remove them with no replacement — and there are **no plain `CometChatCalls` static methods** to rebuild VB or in-call chat in your own bar (VB is exposed only as call-session instance methods / action constants like `setBackgroundBlur`, not statics). So a custom *control* bar should hide only `hideControlPanel`; leave `hideHeaderPanel` false so VB / chat / participant-list stay reachable. Real customer bug, 2026-06: ticking a "custom control panel" option flipped both flags and made VB + chat vanish.
-
-If you genuinely don't want the header either, you're back in Model A territory — own those features yourself.
-
-### Participant count from a custom bar
-
-Don't derive the roster from `onParticipantJoined` / `onParticipantLeft` increments — those fire only for participants who join/leave **after** you, so a counter seeded at 0 (or 1) **undercounts when you join a call already in progress**. Subscribe to the authoritative full-list event instead:
-
-```ts
-CometChatCalls.addEventListener('onParticipantListChanged', (list) =>
-  setParticipants(Math.max(1, list.length)),  // list includes the local user
-);
-```
-
----
-
-## Local preview (before the call connects)
-
-For a "ringing" UI where the local user sees their own camera before the receiver picks up:
-
-```tsx
-useEffect(() => {
-  let stream: MediaStream | null = null;
-  navigator.mediaDevices.getUserMedia({ video: true, audio: true }).then((s) => {
-    stream = s;
-    if (localVideoRef.current) localVideoRef.current.srcObject = s;
-  }).catch((err) => {
-    if (err.name === "NotAllowedError") setError("Camera/mic permission denied");
-    if (err.name === "NotFoundError") setError("No camera or mic on this device");
-  });
-
-  return () => {
-    stream?.getTracks().forEach((t) => t.stop());     // CRITICAL — release tracks (rule 1.3)
-    if (localVideoRef.current) localVideoRef.current.srcObject = null;
-  };
-}, []);
-```
-
-Once `startSession` runs, the SDK takes over the camera/mic — release your preview stream first or you'll have two consumers fighting over the device.
-
----
-
-## Layout customization
-
-The Calls SDK is layout-agnostic when `enableDefaultLayout(false)`. You compose remote tiles in any CSS layout:
-
-- **Spotlight** — one large remote tile + small thumbnails for others. Track who's speaking via the `onDominantSpeakerChanged` event (NOT `onActiveSpeakerUpdated` — that name doesn't exist) and swap the spotlight.
-- **Grid** — CSS grid with auto-fit columns, 1-N participant tiles equally sized.
-- **Picture-in-picture** — small floating remote video that survives navigation. Mount it in a portal at the layout root (similar to `<CometChatIncomingCall />`).
-
----
-
-## When to NOT go custom
-
-- Default kit UI works for 80% of apps; custom is a real engineering investment.
-- Recording / screen-share / participant-management features require deeper SDK plumbing — `references/recording-screen-share.md` covers them but custom-UI authors must wire all of them themselves.
-- Kit components handle accessibility (keyboard nav, ARIA roles, focus traps) — custom must replicate.
-- The kit is updated when CometChat ships breaking SDK changes; custom code is yours to migrate.
-
-The dispatcher asks the user whether to go custom (defaults to "no — use kit") and only loads this reference when they say yes.

package/skills/cometchat-react-calls/references/device-management.md

@@ -1,210 +0,0 @@
-# Device management on web
-
-Camera / mic / speaker enumeration + switching mid-call. SDK exposes `getAudioInputDevices()` / `getVideoInputDevices()` / `getAudioOutputDevices()` plus `setAudioInputDevice(deviceId)` etc. Browser handles the underlying `navigator.mediaDevices.enumerateDevices()` plumbing.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/javascript/device-management
-**Use it for:** "I'm on AirPods, switch from laptop mic"; "this monitor's webcam is bad, use the external one"; pre-call device picker; in-call settings menu.
-
----
-
-## SDK API
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-// Enumerate — these getters are SYNCHRONOUS (they return arrays, not promises;
-// do NOT `await` them).
-const mics = CometChatCalls.getAudioInputDevices();
-const speakers = CometChatCalls.getAudioOutputDevices();
-const cameras = CometChatCalls.getVideoInputDevices();
-
-// Currently selected
-const currentMic = CometChatCalls.getCurrentAudioInputDevice();
-
-// Switch (mid-call OK) — also synchronous, return void.
-CometChatCalls.setAudioInputDevice(deviceId);
-CometChatCalls.setAudioOutputDevice(deviceId);
-CometChatCalls.setVideoInputDevice(deviceId);
-
-// Listen for device changes (user plugs in headphones, etc.). The valid event
-// keys are onAudioInputDevicesChanged / onAudioOutputDevicesChanged /
-// onVideoInputDevicesChanged (there is NO "onAudioModesUpdated"). addEventListener
-// returns an unsubscribe function — there is no removeEventListener.
-const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", (devices) => {
-  // re-enumerate; show toast "AirPods connected"
-});
-// later: off();
-```
-
-Each device is a standard `MediaDeviceInfo` (the SDK types are `AudioInputDevice = MediaDeviceInfo & { kind: 'audioinput' }`, etc.). The fields you use:
-```ts
-// deviceId: string   ← the ID you pass to setAudioInputDevice() (NOT `id`)
-// label:    string   ← "Built-in Microphone" / "AirPods Pro" (empty until mic permission granted)
-// kind:     'audioinput' | 'videoinput' | 'audiooutput'
-```
-
----
-
-## Pre-call device picker
-
-```tsx
-import { useEffect, useState } from "react";
-import { CometChatCalls } from "@cometchat/calls-sdk-javascript";
-
-function DevicePicker({ onConfirm }: { onConfirm: () => void }) {
-  // Devices are MediaDeviceInfo objects — use `deviceId`, NOT `id`.
-  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
-  const [cameras, setCameras] = useState<MediaDeviceInfo[]>([]);
-  const [speakers, setSpeakers] = useState<MediaDeviceInfo[]>([]);
-  const [selectedMic, setSelectedMic] = useState<string>();
-  const [selectedCamera, setSelectedCamera] = useState<string>();
-  const [selectedSpeaker, setSelectedSpeaker] = useState<string>();
-
-  useEffect(() => {
-    async function load() {
-      // Devices have empty labels until permission is granted; trigger getUserMedia first
-      try {
-        await navigator.mediaDevices.getUserMedia({ audio: true, video: true });
-      } catch {
-        // permission denied — labels will be empty; offer settings link
-      }
-
-      // These getters are SYNCHRONOUS — no await / Promise.all needed.
-      const m = CometChatCalls.getAudioInputDevices();
-      const c = CometChatCalls.getVideoInputDevices();
-      const s = CometChatCalls.getAudioOutputDevices();
-      setMics(m); setCameras(c); setSpeakers(s);
-
-      setSelectedMic(CometChatCalls.getCurrentAudioInputDevice()?.deviceId ?? m[0]?.deviceId);
-      setSelectedCamera(CometChatCalls.getCurrentVideoInputDevice()?.deviceId ?? c[0]?.deviceId);
-      setSelectedSpeaker(CometChatCalls.getCurrentAudioOutputDevice()?.deviceId ?? s[0]?.deviceId);
-    }
-    load();
-  }, []);
-
-  function confirm() {
-    // setters are synchronous, return void
-    if (selectedMic) CometChatCalls.setAudioInputDevice(selectedMic);
-    if (selectedCamera) CometChatCalls.setVideoInputDevice(selectedCamera);
-    if (selectedSpeaker) CometChatCalls.setAudioOutputDevice(selectedSpeaker);
-    onConfirm();
-  }
-
-  return (
-    <form>
-      <label>
-        Microphone
-        <select value={selectedMic} onChange={(e) => setSelectedMic(e.target.value)}>
-          {mics.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Mic ${d.deviceId.slice(0, 6)}`}</option>)}
-        </select>
-      </label>
-      <label>
-        Camera
-        <select value={selectedCamera} onChange={(e) => setSelectedCamera(e.target.value)}>
-          {cameras.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Camera ${d.deviceId.slice(0, 6)}`}</option>)}
-        </select>
-      </label>
-      <label>
-        Speaker
-        <select value={selectedSpeaker} onChange={(e) => setSelectedSpeaker(e.target.value)}>
-          {speakers.map(d => <option key={d.deviceId} value={d.deviceId}>{d.label || `Speaker ${d.deviceId.slice(0, 6)}`}</option>)}
-        </select>
-      </label>
-      <button type="button" onClick={confirm}>Join call</button>
-    </form>
-  );
-}
-```
-
-**Empty labels gotcha:** browsers return empty `label` strings until permission is granted. Trigger `getUserMedia` once before enumerating to populate labels.
-
----
-
-## Hot-swap during a call (settings menu)
-
-```tsx
-function InCallDeviceSettings() {
-  const [showMenu, setShowMenu] = useState(false);
-  const [mics, setMics] = useState<MediaDeviceInfo[]>([]);
-
-  useEffect(() => {
-    if (!showMenu) return;
-    // getAudioInputDevices() is synchronous — returns an array, no .then().
-    setMics(CometChatCalls.getAudioInputDevices());
-
-    // addEventListener returns an unsubscribe fn — call it to clean up
-    // (there is no removeEventListener on the SDK).
-    const off = CometChatCalls.addEventListener("onAudioInputDevicesChanged", () => {
-      setMics(CometChatCalls.getAudioInputDevices());
-    });
-    return () => off();
-  }, [showMenu]);
-
-  function selectMic(id: string) {
-    CometChatCalls.setAudioInputDevice(id);   // synchronous, returns void
-    setShowMenu(false);
-  }
-
-  return (
-    <div>
-      <button onClick={() => setShowMenu(s => !s)}>Mic ▾</button>
-      {showMenu && (
-        <ul role="menu">
-          {mics.map(d => (
-            <li key={d.deviceId}>
-              <button role="menuitem" onClick={() => selectMic(d.deviceId)}>{d.label}</button>
-            </li>
-          ))}
-        </ul>
-      )}
-    </div>
-  );
-}
-```
-
-`onAudioInputDevicesChanged` (and `onAudioOutputDevicesChanged` / `onVideoInputDevicesChanged`) fire when the user plugs in headphones, AirPods connect, etc. Re-enumerate on the event.
-
----
-
-## Bluetooth / AirPods routing
-
-Browsers expose Bluetooth speakers in `getAudioOutputDevices()`. Selecting one calls `HTMLMediaElement.setSinkId()` under the hood — works in Chrome/Edge/Firefox, NOT in Safari (Safari uses system audio routing only).
-
-```ts
-// Detect Safari (limited device-output support)
-const safari = /^((?!chrome|android).)*safari/i.test(navigator.userAgent);
-if (safari) {
-  // Hide speaker selection; show "Use system audio" hint
-}
-```
-
----
-
-## Anti-patterns
-
-1. **Calling `getAudioInputDevices` before requesting permission.** Returns devices with empty `label` strings — UI shows "undefined" or empty entries.
-2. **Caching device list.** Devices change (plug/unplug). Re-enumerate on every menu open AND on `onAudioInputDevicesChanged`.
-3. **Hardcoding the first device as default.** Browsers may sort differently (built-in vs USB). Read `getCurrent*Device` first; only fall back to first if no current selection.
-4. **Switching speakers in Safari.** `setAudioOutputDevice` silently fails. Detect Safari and hide the speaker picker (or show a "iOS uses system routing" tooltip).
-5. **No listener cleanup on unmount.** Event accumulates listeners on remount; spam every device change.
-
----
-
-## Verification checklist
-
-- [ ] Permission requested before enumeration (empty-label fix)
-- [ ] `getCurrent*Device()` used as default in pickers
-- [ ] `onAudioInputDevicesChanged` listener for hot-swap detection (unsubscribe via the returned fn)
-- [ ] Listener cleanup on unmount
-- [ ] Safari speaker picker hidden / fallback message
-- [ ] Browser smoke: plug/unplug headphones during call, picker updates
-- [ ] AirPods smoke: connect AirPods → "AirPods" appears in mic + speaker lists
-- [ ] Multi-camera smoke: USB webcam + built-in, switch between
-
----
-
-## Pointers
-
-- `cometchat-react-calls` SKILL.md — the seven hard rules
-- `references/custom-ui.md` — full custom call UI integration
-- Canonical docs: https://www.cometchat.com/docs/calls/javascript/device-management