@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-native-calls/references/picture-in-picture.md

@@ -1,276 +0,0 @@
-# Picture-in-Picture on React Native
-
-Both Android and iOS support PiP for video calls — but the integration paths are different. Android exposes `PictureInPictureParams` via `Activity` APIs; iOS exposes `AVPictureInPictureController` (and CallKit handles it for VoIP calls). RN bridges both via native modules.
-
----
-
-## Android — Activity-level PiP
-
-Android PiP is an Activity attribute. The activity declares it supports PiP, and you transition into PiP by calling `enterPictureInPictureMode()` from native (RN exposes a bridge).
-
-### Manifest
-
-```xml
-<!-- android/app/src/main/AndroidManifest.xml -->
-<activity
-  android:name=".MainActivity"
-  android:supportsPictureInPicture="true"
-  android:configChanges="screenSize|smallestScreenSize|screenLayout|orientation|keyboardHidden">
-  <!-- ... -->
-</activity>
-```
-
-`configChanges` is critical — without it, Android destroys + recreates the activity on PiP transition, which kills the WebRTC connection.
-
-### Bridge
-
-`react-native-webrtc` ships a helper module (in some versions) for entering PiP. If your version doesn't have it, write a tiny native module:
-
-```kotlin
-// android/app/src/main/java/com/yourapp/PictureInPictureModule.kt
-package com.yourapp
-
-import android.app.PictureInPictureParams
-import android.os.Build
-import android.util.Rational
-import com.facebook.react.bridge.ReactApplicationContext
-import com.facebook.react.bridge.ReactContextBaseJavaModule
-import com.facebook.react.bridge.ReactMethod
-import com.facebook.react.bridge.Promise
-
-class PictureInPictureModule(reactContext: ReactApplicationContext) : ReactContextBaseJavaModule(reactContext) {
-  override fun getName() = "PictureInPicture"
-
-  @ReactMethod
-  fun enterPip(promise: Promise) {
-    val activity = currentActivity
-    if (activity == null) {
-      promise.reject("NO_ACTIVITY", "No current activity")
-      return
-    }
-    if (Build.VERSION.SDK_INT < Build.VERSION_CODES.O) {
-      promise.reject("UNSUPPORTED", "Android < 8.0 doesn't support PiP")
-      return
-    }
-
-    val aspectRatio = Rational(16, 9)
-    val params = PictureInPictureParams.Builder()
-      .setAspectRatio(aspectRatio)
-      .build()
-
-    val ok = activity.enterPictureInPictureMode(params)
-    if (ok) promise.resolve(null) else promise.reject("FAILED", "Couldn't enter PiP")
-  }
-}
-```
-
-Register in `MainApplication.kt`:
-
-```kotlin
-override fun getPackages(): List<ReactPackage> {
-  val packages = PackageList(this).packages
-  packages.add(PictureInPicturePackage())          // your package wrapping the module
-  return packages
-}
-```
-
-### React side
-
-```ts
-import { NativeModules, Platform } from "react-native";
-
-const PictureInPicture = NativeModules.PictureInPicture;
-
-async function enterPiP() {
-  if (Platform.OS !== "android") return;
-  try {
-    await PictureInPicture.enterPip();
-  } catch (err) {
-    console.warn("PiP failed:", err);
-  }
-}
-```
-
-### Listening for PiP transitions
-
-On Android, the activity gets `onPictureInPictureModeChanged` callback. RN exposes this via `AppState`:
-
-```ts
-import { AppState, type AppStateStatus } from "react-native";
-
-useEffect(() => {
-  const handler = (state: AppStateStatus) => {
-    // 'background' fires when entering PiP on some Android versions
-    // 'active' fires on returning
-    if (state === "active") {
-      // restore full UI
-    }
-  };
-  const sub = AppState.addEventListener("change", handler);
-  return () => sub.remove();
-}, []);
-```
-
-Better — emit a custom event from your native module on `onPictureInPictureModeChanged` and listen in JS:
-
-```ts
-import { NativeEventEmitter, NativeModules } from "react-native";
-
-const emitter = new NativeEventEmitter(NativeModules.PictureInPicture);
-useEffect(() => {
-  const sub = emitter.addListener("pipModeChanged", ({ inPip }: { inPip: boolean }) => {
-    setInPip(inPip);
-  });
-  return () => sub.remove();
-}, []);
-```
-
----
-
-## iOS — CallKit handles it for VoIP calls
-
-The simplest iOS PiP path: **don't write any.** If you've integrated CallKit (rule 1.2 in the SKILL.md, mandatory for standalone-mode VoIP), iOS auto-handles PiP for active video calls when the user backgrounds the app. The system shows your CallKit-reported call in a small floating window.
-
-For non-CallKit calls (in-foreground only), you need `AVPictureInPictureController`. This is involved on iOS because `AVPictureInPictureController` requires an `AVSampleBufferDisplayLayer` — it doesn't work directly with `<RTCView />`.
-
-### AVPictureInPictureController bridge
-
-`react-native-webrtc` ≥ 119 ships an `RTCVideoView` that supports PiP via a system-managed display layer. The bridge:
-
-```ts
-import { RTCView } from "react-native-webrtc";
-
-// react-native-webrtc 119+
-<RTCView
-  streamURL={remoteStream.toURL()}
-  style={styles.remoteVideo}
-  pictureInPicture={true}
-  onPictureInPictureStart={() => setInPip(true)}
-  onPictureInPictureStop={() => setInPip(false)}
-/>
-```
-
-Older versions: write a wrapper around `AVPictureInPictureController` and a `WebRTCVideoView` subclass that exposes its `AVSampleBufferDisplayLayer` to the controller. Substantial native work; deferring to CallKit is the right call for most apps.
-
-### Info.plist
-
-Background modes must include `audio` (rule 1.3 in the SKILL.md). PiP itself doesn't need a separate capability; it inherits from "audio" + active call.
-
----
-
-## App state preservation across PiP
-
-When the app enters PiP (Android) or background-with-active-call (iOS), the call state must persist. Practical rules:
-
-1. **Don't tear down the WebRTC connection** on `componentWillUnmount` of the call screen. The screen survives PiP; tearing down kills the call.
-2. **Hide the in-page video** when PiP is active — same rule as web. Two videos rendering = bad UX, double battery.
-3. **Restore on PiP exit** — listen to `pipModeChanged` and re-render the full call surface.
-
-```tsx
-function CallScreen() {
-  const [inPip, setInPip] = useState(false);
-
-  return (
-    <View style={[styles.container, inPip && styles.minimalPip]}>
-      <RTCView
-        streamURL={remoteStream?.toURL()}
-        style={inPip ? styles.pipFullSize : styles.normalSize}
-        pictureInPicture={true}
-        onPictureInPictureStart={() => setInPip(true)}
-        onPictureInPictureStop={() => setInPip(false)}
-      />
-      {!inPip && <ControlPanel onEnd={endCall} />}
-    </View>
-  );
-}
-```
-
-The control panel is only visible in non-PiP mode; PiP is video-only by design.
-
----
-
-## Auto-PiP on app backgrounding
-
-Common UX: user presses Home button or switches apps → call auto-enters PiP so video keeps playing.
-
-### Android
-
-In `MainActivity.kt`:
-
-```kotlin
-override fun onUserLeaveHint() {
-  super.onUserLeaveHint()
-  // User pressed Home — auto-enter PiP if a call is active
-  if (isCallActive() && Build.VERSION.SDK_INT >= Build.VERSION_CODES.O) {
-    enterPictureInPictureMode(PictureInPictureParams.Builder().build())
-  }
-}
-
-private fun isCallActive(): Boolean {
-  // bridge to JS state — store this in a SharedPreferences flag
-  return getSharedPreferences("call", MODE_PRIVATE).getBoolean("active", false)
-}
-```
-
-JS side: write the flag whenever the call starts/ends:
-
-```ts
-import { NativeModules } from "react-native";
-
-useEffect(() => {
-  NativeModules.PictureInPicture.setCallActive(true);
-  return () => NativeModules.PictureInPicture.setCallActive(false);
-}, []);
-```
-
-### iOS
-
-CallKit handles this — if you've reported the call to CallKit (rule 1.2), iOS auto-PiPs on background. No bridge code needed for the auto-PiP path.
-
-For non-CallKit calls (rare in production calling apps), use `react-native-webrtc`'s `pictureInPicture` prop with auto-enter behavior at the native level.
-
----
-
-## Anti-patterns
-
-1. **Skipping `configChanges` on the manifest activity.** PiP transition destroys + recreates the activity → call dies.
-2. **Tearing down WebRTC in PiP transition.** Same outcome — call dies.
-3. **No iOS Background Modes `audio` capability.** PiP video plays without sound; user thinks it's broken.
-4. **Auto-PiP on every app background, including non-call screens.** User opens settings, comes back to a PiP'd home screen. Gate on `isCallActive()`.
-5. **Rendering control panel inside PiP window.** PiP windows are small; controls don't fit. Hide them.
-6. **Using two separate `<RTCView />` instances** — one for normal, one for PiP. The `pictureInPicture` prop on a single view is the right pattern.
-7. **iOS PiP without CallKit.** Doesn't work for backgrounded calls — only foregrounded. CallKit is required for "real" PiP.
-
----
-
-## Verification checklist
-
-**Android:**
-- [ ] `android:supportsPictureInPicture="true"` on the activity
-- [ ] `android:configChanges` includes screenSize/smallestScreenSize/screenLayout/orientation
-- [ ] Native PiP module registered + bridged
-- [ ] `onUserLeaveHint` auto-PiP gated on `isCallActive()`
-- [ ] PiP entry uses 16:9 aspect ratio (or matches stream resolution)
-- [ ] PiP mode change emits to JS; controls hidden in PiP
-
-**iOS:**
-- [ ] CallKit integrated (rule 1.2 in SKILL.md)
-- [ ] Background Modes: audio + voip + remote-notification
-- [ ] `react-native-webrtc` ≥ 119 if using `pictureInPicture` prop
-- [ ] PiP transitions don't tear down call
-
-**Real-device smoke:**
-- [ ] Android: press Home during call → PiP appears, video keeps playing, audio continues
-- [ ] Android: tap PiP window → call screen restored, controls visible
-- [ ] iOS: press Home during call → CallKit-managed PiP appears
-- [ ] iOS: tap PiP → app foregrounds, full call screen visible
-
----
-
-## Pointers
-
-- `references/custom-ui.md` — composing custom call surfaces (PiP integration via the `pictureInPicture` prop pattern)
-- `references/voip-push-end-to-end.md` — CallKit which handles iOS PiP for free
-- `cometchat-android-v5-calls/references/picture-in-picture.md` — Android-native PiP reference (deeper Android-specific patterns)
-- `cometchat-react-calls/references/picture-in-picture.md` — Web PiP (different APIs but same UX shape)
-- `cometchat-native-calls` SKILL.md — base hard rules

package/skills/cometchat-native-calls/references/raise-hand.md

@@ -1,205 +0,0 @@
-# Raise hand on React Native
-
-Same SDK API as web (`@cometchat/calls-sdk-react-native` exposes the same calls). The difference is the UI surface — native components instead of HTML, RN re-renders with state, no `aria-pressed` (use `accessibilityState` instead).
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/react-native/raise-hand
-**Read first:** `cometchat-react-calls/references/raise-hand.md` — the integration shape and anti-patterns are identical; this reference covers RN-specific wiring.
-
----
-
-## SDK API
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-CometChatCalls.raiseHand();
-CometChatCalls.lowerHand();
-
-// addEventListener returns an unsubscribe function — capture it, call it in cleanup.
-const off = CometChatCalls.addEventListener("onParticipantHandRaised", (p) => { ... });
-// later: off();
-
-// Button visibility is a SessionSettings OBJECT field, not a builder method:
-const settings = {
-  hideRaiseHandButton: true,
-};
-```
-
----
-
-## RN-specific UX patterns
-
-### Toggle button (TouchableOpacity)
-
-```tsx
-import { useState } from "react";
-import { TouchableOpacity, Text, AccessibilityInfo } from "react-native";
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-function RaiseHandButton() {
-  const [raised, setRaised] = useState(false);
-
-  function toggle() {
-    if (raised) {
-      CometChatCalls.lowerHand();
-      setRaised(false);
-      AccessibilityInfo.announceForAccessibility("Hand lowered");
-    } else {
-      CometChatCalls.raiseHand();
-      setRaised(true);
-      AccessibilityInfo.announceForAccessibility("Hand raised");
-    }
-  }
-
-  return (
-    <TouchableOpacity
-      onPress={toggle}
-      accessibilityRole="button"
-      accessibilityState={{ selected: raised }}
-      accessibilityLabel={raised ? "Lower hand" : "Raise hand"}
-      style={{
-        padding: 12,
-        borderRadius: 32,
-        backgroundColor: raised ? "#FFD60A" : "rgba(255,255,255,0.2)",
-      }}
-    >
-      <Text style={{ color: raised ? "#000" : "#FFF" }}>
-        ✋ {raised ? "Lower" : "Raise"}
-      </Text>
-    </TouchableOpacity>
-  );
-}
-```
-
-`AccessibilityInfo.announceForAccessibility` is the RN equivalent of web's `aria-live` regions — TalkBack / VoiceOver pick up the announcement. This is the canonical RN a11y pattern (cf. `cometchat-a11y`).
-
-### Raised-hands roster (BottomSheet pattern)
-
-For a host's "raised hands" list, the natural RN UX is a bottom sheet rather than a permanent sidebar (vertical phone screens are tight on horizontal real estate):
-
-```tsx
-import { useEffect, useRef, useState } from "react";
-import { View, Text, FlatList } from "react-native";
-import BottomSheet from "@gorhom/bottom-sheet";
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-interface RaisedParticipant { uid: string; name: string; raisedAt: number; }
-
-function RaisedHandsSheet() {
-  const sheetRef = useRef<BottomSheet>(null);
-  const [raised, setRaised] = useState<Map<string, RaisedParticipant>>(new Map());
-
-  useEffect(() => {
-    const onRaised = (p: { uid: string; name: string }) => {
-      setRaised(prev => new Map(prev).set(p.uid, { ...p, raisedAt: Date.now() }));
-      // Auto-expand the sheet on first hand raised
-      if (raised.size === 0) sheetRef.current?.snapToIndex(1);
-    };
-    const onLowered = (p: { uid: string }) => {
-      setRaised(prev => {
-        const next = new Map(prev);
-        next.delete(p.uid);
-        return next;
-      });
-    };
-
-    // addEventListener returns an unsubscribe fn; collect them and call on cleanup.
-    const offRaised = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-    const offLowered = CometChatCalls.addEventListener("onParticipantHandLowered", onLowered);
-    return () => {
-      offRaised();
-      offLowered();
-    };
-  }, [raised.size]);
-
-  const sorted = Array.from(raised.values()).sort((a, b) => a.raisedAt - b.raisedAt);
-
-  return (
-    <BottomSheet ref={sheetRef} snapPoints={["10%", "40%"]} index={raised.size > 0 ? 1 : 0}>
-      <View style={{ padding: 16 }}>
-        <Text style={{ fontWeight: "600", marginBottom: 8 }}>
-          Raised hands ({raised.size})
-        </Text>
-        <FlatList
-          data={sorted}
-          keyExtractor={(p) => p.uid}
-          renderItem={({ item }) => (
-            <Text style={{ paddingVertical: 6 }}>
-              ✋ {item.name}
-            </Text>
-          )}
-        />
-      </View>
-    </BottomSheet>
-  );
-}
-```
-
-`@gorhom/bottom-sheet` is the canonical RN bottom-sheet library; if you've already integrated CometChat the kit's setup includes its peer deps (`react-native-gesture-handler`, `react-native-reanimated`).
-
-### Toast for the host
-
-```tsx
-import Toast from "react-native-toast-message";
-
-useEffect(() => {
-  const onRaised = (p: { name: string }) => {
-    Toast.show({
-      type: "info",
-      text1: `${p.name} raised their hand`,
-      visibilityTime: 4000,
-      position: "top",
-    });
-  };
-  const off = CometChatCalls.addEventListener("onParticipantHandRaised", onRaised);
-  return () => off();
-}, []);
-```
-
----
-
-## When to gate raise-hand UI
-
-Same rule as web: hide for 1:1 calls. Gate on participant count:
-
-```tsx
-const showRaiseHand = participants.length > 2;
-return showRaiseHand ? <RaiseHandButton /> : null;
-```
-
----
-
-## Anti-patterns
-
-Same shape as web (cf. sister reference) plus RN-specific:
-
-1. **Forgetting `accessibilityRole="button"`.** TouchableOpacity defaults to "image" or no role — TalkBack reads it wrong. Always set the role.
-2. **`Toast.show` from inside the SDK callback without UI-thread guarantee.** Toast lib usually handles this, but if you use a custom toast, wrap in `requestAnimationFrame` or check that the call from the SDK callback is on the JS thread.
-3. **BottomSheet with a single snap-point.** Use 2 snaps so users can collapse without dismissing entirely.
-4. **Animating the raise-hand badge with Reanimated `withSpring`** in a video-call context. CPU-intensive; can stutter the WebRTC pipeline. Use `withTiming` with short durations or skip the animation.
-
----
-
-## Verification checklist
-
-- [ ] `raiseHand()` / `lowerHand()` wired to your toggle button
-- [ ] Both event listeners registered + cleaned up
-- [ ] `accessibilityState`, `accessibilityRole`, `accessibilityLabel` on the toggle button
-- [ ] `AccessibilityInfo.announceForAccessibility` on state change
-- [ ] Roster sorted by `raisedAt` ascending
-- [ ] `hideRaiseHandButton: true` in CallSettings if custom UI
-- [ ] Real-device smoke: 3 devices in same call, hand-raise from 2 → host's BottomSheet shows both
-- [ ] iOS device: VoiceOver announces "Hand raised" / "Hand lowered"
-- [ ] Android device: TalkBack announces same
-- [ ] Visual at 360×640 (small Android phone) — button + sheet still legible
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/raise-hand.md` — sister reference (same SDK, web-flavored UI)
-- `cometchat-native-calls` SKILL.md — the seven hard rules
-- `references/group-calls.md` — group call architecture
-- `references/custom-ui.md` — RN custom call UI
-- `cometchat-a11y` — RN announcement patterns
-- Canonical docs: https://www.cometchat.com/docs/calls/react-native/raise-hand

package/skills/cometchat-native-calls/references/recording-screen-share.md

@@ -1,169 +0,0 @@
-# Recording + screen-share on React Native
-
-Both features live in the Calls SDK; both have RN-specific gotchas the kit's defaults don't handle. Sister of `cometchat-react-calls/references/recording-screen-share.md` — same SDK semantics, different platform plumbing for screen capture.
-
----
-
-## Recording
-
-### Server-side: dashboard gate
-
-Recording is a paid feature on most CometChat plans. Enable in **Dashboard → Chat & Messaging → Calls → Recording**. The client-side flag below is a no-op without it.
-
-### Client-side: opt-in per session
-
-```ts
-import { CometChatCalls } from "@cometchat/calls-sdk-react-native";
-
-// Audio vs video + recording are SessionSettings OBJECT fields (v5), not builder methods.
-// enableRecording()/setShowRecordingButton() do not exist on the v5 RN SDK.
-const sessionSettings = {
-  sessionType: "VIDEO",       // "VIDEO" | "AUDIO" — replaces the v4 setIsAudioOnlyCall builder
-  autoStartRecording: true,   // server starts recording when the session begins
-  hideRecordingButton: false, // show the in-call recording toggle (kit's default UI)
-};
-```
-
-### Recording lifecycle events
-
-`CometChatCalls.OngoingCallListener` is still re-exported but is the v4-era path — **@deprecated, prefer `CometChatCalls.addEventListener(...)`** (which returns an unsubscribe fn). Only `onRecordingStarted` / `onRecordingStopped` exist; there is no `onRecordingFailed`.
-
-```ts
-// Preferred (v5): addEventListener returns the unsubscribe fn.
-const offStarted = CometChatCalls.addEventListener("onRecordingStarted", () => {
-  // Update UI — show a "REC" indicator (compliance requirement in some jurisdictions)
-  setRecording(true);
-});
-const offStopped = CometChatCalls.addEventListener("onRecordingStopped", () => {
-  setRecording(false);
-});
-// cleanup: offStarted(); offStopped();
-// NOTE: there is no onRecordingFailed event in the v5 RN SDK — do not listen for it.
-```
-
-### REC indicator (compliance)
-
-In some regions, you must visually notify all participants when recording is active. The kit's default `CometChatOngoingCall` shows a small "Recording" badge. Custom UI must render this:
-
-```tsx
-{recording && (
-  <View style={styles.recBadge}>
-    <Text style={styles.recDot}>●</Text>
-    <Text style={styles.recLabel}>REC</Text>
-  </View>
-)}
-```
-
-Don't omit this — the legal exposure is real (CCPA, GDPR, two-party-consent US states).
-
-### Where the recordings go
-
-CometChat hosts the file. It appears in **Dashboard → Calls → Recordings** with a download link. There is no client-side download API — the file isn't exposed to the device for security/compliance reasons.
-
-For programmatic access:
-
-```ts
-// Server-side — your backend with the dashboard bearer token
-const res = await fetch(
-  `https://${region}.api-management.cometchat.io/v3/apps/${appId}/recordings`,
-  { headers: { Authorization: `Bearer ${dashboardToken}` } },
-);
-const recordings = await res.json();
-```
-
-The skill points users at this REST endpoint; it doesn't generate client code (recordings shouldn't be downloadable from the device).
-
----
-
-## Screen sharing
-
-**Initiating a screen share from React Native is NOT supported.** Per the docs (`docs/calls/react-native/screen-sharing.mdx`): RN devices can only **view** screen shares started by participants on other platforms (web/desktop). There is no `startScreenSharing()` / `stopScreenSharing()` / `CometChatCalls.startScreenShare()` API on RN, no iOS Broadcast Extension flow, and no Android MediaProjection flow exposed by this SDK. Do not write screen-share-initiation code for RN.
-
-### Viewer — receive / view a screen share
-
-When a participant shares their screen from another platform, the kit's default `CometChatOngoingCall` UI auto-renders the screen-share tile (it switches to Sidebar layout automatically). Listen for screen-share events only to drive custom UI.
-
-Two receive-path event channels exist (verified against the calls-sdk-react-native clone `skills/event-listeners/SKILL.md`):
-
-```ts
-// Participant events — fire with the remote participant who shared:
-const offStart = CometChatCalls.addEventListener("onParticipantStartedScreenShare", (participant) => {
-  setScreenSharePresenter(participant.name);
-});
-const offStop = CometChatCalls.addEventListener("onParticipantStoppedScreenShare", () => {
-  setScreenSharePresenter(null);
-});
-// cleanup: offStart(); offStop();
-
-// Media-event channel (received from a web participant), no payload:
-CometChatCalls.addEventListener("onScreenShareStarted", () => { /* show screen-share tile */ });
-CometChatCalls.addEventListener("onScreenShareStopped", () => { /* restore prior layout */ });
-```
-
-Custom-UI viewer composition:
-
-```tsx
-function CustomCallView() {
-  const [screenSharePresenter, setScreenSharePresenter] = useState<string | null>(null);
-  const [participants, setParticipants] = useState<Participant[]>([]);
-
-  return (
-    <View style={styles.container}>
-      {screenSharePresenter ? (
-        <ScreenShareView presenterUid={screenSharePresenter} />
-      ) : (
-        <ParticipantTilesGrid participants={participants} />
-      )}
-    </View>
-  );
-}
-```
-
-When someone shares their screen, switch the layout to "screen share + participant strip"; switch back when they stop.
-
----
-
-## Recording + screen-share together
-
-Server-side recording captures whatever video composition the SFU is forwarding. When a (web/desktop) participant is screen-sharing, the recording shows their screen. When they stop, it switches back to the camera composition.
-
-You don't compose this client-side — the server handles it. Custom UI just needs to render the screen-share track when present (receive path).
-
----
-
-## Anti-patterns
-
-1. **Trying to INITIATE a screen share from RN.** Not supported — there is no `startScreenSharing()`, iOS Broadcast Extension flow, or Android MediaProjection flow on this SDK. RN can only view shares from other platforms.
-2. **No "REC" indicator in custom UI.** Compliance violation in two-party-consent jurisdictions.
-3. **Trying to download recordings from the device.** They live on CometChat's servers. Use the dashboard or REST API.
-4. **`autoStartRecording: true` without dashboard gate.** SessionSettings flag silently no-ops; user thinks recording is active when it isn't.
-5. **Not handling the screen-share-stopped event in custom UI.** Layout doesn't switch back; viewer sees the last screen-share frame frozen.
-
----
-
-## Verification checklist
-
-**Recording:**
-- [ ] Dashboard gate enabled (Recording feature on the plan)
-- [ ] `autoStartRecording: true` in the SessionSettings object (NOT a builder method)
-- [ ] `onRecordingStarted` / `onRecordingStopped` listeners wired via `addEventListener`
-- [ ] "REC" indicator visible to all participants when active
-
-**Screen share (RN = VIEW-only; initiation not supported):**
-- [ ] Custom UI: layout switches to screen-share view on `onParticipantStartedScreenShare` / `onScreenShareStarted`
-- [ ] Custom UI: layout switches back on `onParticipantStoppedScreenShare` / `onScreenShareStopped`
-
-**Real-device smoke:**
-- [ ] A web/desktop participant starts a screen share → it renders on the RN device
-- [ ] That participant stops sharing → RN view returns to camera composition smoothly
-- [ ] Recording starts, "REC" shows, recording appears in dashboard within ~30 seconds
-
----
-
-## Pointers
-
-- `references/custom-ui.md` — building custom call surfaces with screen-share viewer
-- `references/group-calls.md` — group calls + screen share interplay (one share at a time)
-- `references/voip-push-end-to-end.md` — push payloads
-- `cometchat-native-calls` SKILL.md — base hard rules
-- `cometchat-react-calls/references/recording-screen-share.md` — sister web reference (same SDK semantics)