@cometchat/skills 4.2.1 → 4.4.0

package/skills/cometchat-flutter-v5-calls/references/group-calls.md

@@ -1,12 +1,12 @@
 # Group calls — broadcast meeting pattern (Flutter V5)
 
-Group calls use a **different signaling channel than 1:1 user calls**. The Ringing flow (`CometChat.initiateCall` → `onIncomingCallReceived` on peer) is **1:1 user only**. For groups, the kit broadcasts a **custom message of type `"meeting"`** to the group; receivers see a "Join meeting" card in `CometChatMessageList` (kit) or need an explicit `MessageListener.onCustomMessageReceived` (custom UI).
+Group calls use a **different signaling channel than 1:1 user calls**. The Ringing flow (`CometChat.initiateCall` → `onIncomingCallReceived` on peer) is **1:1 user only**. For groups, broadcast a **custom message of type `"meeting"`** to the group; receivers handle it via `MessageListener.onCustomMessageReceived` and join the WebRTC session whose `sessionId = group GUID`.
 
-By-design kit behavior — same semantic across all CometChat kits.
+By-design signaling semantic — same across all CometChat kits.
 
 **Canonical docs:** https://www.cometchat.com/docs/calls/flutter/group-calls
 
-V5 specifics: Flutter V5 uses `cometchat_chat_uikit ^5.2` + `cometchat_calls_uikit ^5.0` (separate calls package). GetX-based state. The signaling semantic below is identical to Flutter V6.
+V5 specifics: Flutter V5 uses `cometchat_chat_uikit ^5.2` (GetX chat kit) + the **raw `cometchat_calls_sdk ^5.0.2`** (direct dependency) — you build a custom meeting/ongoing-call surface. The signaling semantic below is identical to Flutter V6.
 
 ---
 
@@ -15,15 +15,14 @@ V5 specifics: Flutter V5 uses `cometchat_chat_uikit ^5.2` + `cometchat_calls_uik
 ```
 Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
   │                                       │                              │
-  │ CometChatCallButtons sends            │                              │
-  │ CustomMessage(GUID, GROUP, "meeting", │                              │
-  │   { callType, sessionId })            │                              │
+  │ sendCustomMessage(GUID, GROUP,        │                              │
+  │   "meeting", { callType, sessionId }) │                              │
   ├──────────────────────────────────────>│                              │
   │                                       │ onCustomMessageReceived      │
   │                                       ├─────────────────────────────>│
   │ caller pushes OngoingCallScreen       │  receiver taps Join          │
-  │  with sessionID = groupGuid           │  → CometChatUIKitCalls       │
-  │                                       │    .startSession(...)        │
+  │  with sessionID = groupGuid           │  → CometChatCalls            │
+  │                                       │    .joinSession(...)         │
   ├──────────────────────────────────────>│ <─────────────────────────── │
   │            ───── WebRTC session active (sessionId = group GUID) ─────│
 ```
@@ -39,26 +38,13 @@ Caller (uidA, member of groupX)        CometChat                Receivers (membe
 
 ## Hard rules
 
-1. **Group calls broadcast a custom message; they do NOT use the call listener.** Custom UI must add a `MessageListener`.
+1. **Group calls broadcast a custom message; they do NOT use the call listener.** Add a `MessageListener`.
 2. **Session ID = group GUID.** Persistent.
-3. **`CometChatUIKitCalls.init()` must complete AFTER `CometChatUIKit.init()`** (CALLS_INIT_AFTER_CHAT_INIT rule from SKILL.md) — same as 1:1.
-4. **No `CometChat.endCall` for groups.** Use `CometChatUIKitCalls.endSession()` only.
+3. **`CometChatCalls.init()` must complete AFTER `CometChatUIKit.init()`** (CALLS_INIT_AFTER_CHAT_INIT rule from SKILL.md) — same as 1:1.
+4. **No `CometChat.endCall` for groups.** Use `CallSession.getInstance()?.leaveSession()` only.
 
 ---
 
-## Caller side — kit-based
-
-```dart
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
-
-// Inside a chat surface (e.g. inside CometChatMessageHeader):
-CometChatCallButtons(
-  group: group,
-)
-```
-
-Tap → kit sends meeting `CustomMessage` + pushes outgoing-call screen → transitions to ongoing call with `sessionId = group.guid`.
-
 ## Caller side — custom UI
 
 ```dart
@@ -97,10 +83,6 @@ Future<void> startGroupCall(String groupGuid, String callType) async {
 
 ---
 
-## Receiver side — kit-based
-
-`CometChatMessageList(group: group)` auto-renders the meeting message as a "Join meeting" card. Tap → kit calls `generateToken` and pushes the ongoing-call screen with `sessionId = group.guid`.
-
 ## Receiver side — custom UI
 
 ```dart
@@ -138,6 +120,19 @@ void unregisterGroupMeetingListener() {
 
 Wire register in `initState` / GetX controller `onInit`, unregister in `dispose` / `onClose`. Register AFTER `CometChatUIKit.login()` succeeds.
 
+On Join tap, join the WebRTC session with the group GUID as the sessionId (5.x raw SDK):
+
+```dart
+CometChatCalls.joinSession(            // cometchatcalls.dart:735
+  sessionId: groupGuid,                // sessionId == group GUID
+  sessionSettings: (SessionSettingsBuilder()..setTitle('Meeting')).build(),
+  onSuccess: (Widget? widget) { /* render via SizedBox.expand */ },
+  onError: (CometChatCallsException e) { /* surface */ },
+);
+```
+
+> **Legacy 4.x-kit alternative (incompatible with the 5.x calls SDK).** The old `cometchat_calls_uikit` path used `CometChatCallButtons(group: group)` for the caller, auto-rendered the meeting card in `CometChatMessageList(group: group)`, and joined via `CometChatUIKitCalls.startSession`. Those widgets are 4.x-bound and cannot run against `cometchat_calls_sdk ^5.0.2` — replicate with the custom-message + `joinSession` flow above.
+
 ---
 
 ## Edge cases
@@ -152,7 +147,7 @@ Meeting `CustomMessage.metadata.pushNotification = "meeting"` — delivered as r
 
 ### `navigatorKey` requirement (V5 too)
 
-If you use the kit's outgoing-call screen for groups, ensure `MaterialApp` has `navigatorKey: CallNavigationContext.navigatorKey` — same requirement as 1:1 (rule 1.7 in SKILL.md).
+Set `MaterialApp.navigatorKey` to a plain `GlobalKey<NavigatorState>` so the meeting flow can navigate from anywhere — same requirement as 1:1 (rule 1.7 in SKILL.md). (Do NOT use `CallNavigationContext.navigatorKey` — that is a 4.x-kit symbol.)
 
 ---
 
@@ -168,12 +163,11 @@ If you use the kit's outgoing-call screen for groups, ensure `MaterialApp` has `
 
 ## Verification checklist
 
-- [ ] If using kit caller: `CometChatCallButtons(group: group)` tap initiates meeting message
-- [ ] If using custom caller: `CometChat.sendCustomMessage` called with `type: 'meeting'`, `category: MessageCategoryConstants.custom`, `customData: {callType, sessionId}`, `metadata: { pushNotification: 'meeting' }`
-- [ ] If using kit receiver: `CometChatMessageList(group: group)` renders meeting card
-- [ ] If using custom receiver: `CometChat.addMessageListener` registered with category+type filter, AFTER login
-- [ ] `MaterialApp.navigatorKey = CallNavigationContext.navigatorKey` set (kit-driven UI path)
-- [ ] On hangup: `CometChatUIKitCalls.endSession()` only (no `CometChat.endCall`)
+- [ ] Caller: `CometChat.sendCustomMessage` called with `type: 'meeting'`, `category: MessageCategoryConstants.custom`, `customData: {callType, sessionId}`, `metadata: { pushNotification: 'meeting' }`
+- [ ] Receiver: `CometChat.addMessageListener` registered with category+type filter, AFTER login
+- [ ] Join action calls `CometChatCalls.joinSession(sessionId: groupGuid, ...)`
+- [ ] `MaterialApp.navigatorKey` is a `GlobalKey<NavigatorState>`
+- [ ] On hangup: `CallSession.getInstance()?.leaveSession()` only (no `CometChat.endCall`)
 - [ ] Late-joining tested
 - [ ] Push notifications fire for offline members
 
@@ -182,6 +176,6 @@ If you use the kit's outgoing-call screen for groups, ensure `MaterialApp` has `
 ## Pointers
 
 - `ringing-integration.md` — 1:1 user calls (different signaling channel)
-- `cometchat-flutter-v5-calls/SKILL.md` — V5 hard rules (cometchat_calls_uikit peer, Jetifier, etc.)
+- `cometchat-flutter-v5-calls/SKILL.md` — V5 hard rules (raw `cometchat_calls_sdk ^5.0.2`, Jetifier, etc.)
 - Canonical docs: https://www.cometchat.com/docs/calls/flutter/group-calls
 - Cross-platform reference (semantic ground-truth): `cometchat-react-calls/references/group-calls.md`

package/skills/cometchat-flutter-v5-calls/references/idle-timeout.md

@@ -1,6 +1,6 @@
-# Idle timeout on Flutter V5 (GetX-based)
+# Idle timeout on Flutter V5 (GetX-based, 5.x Calls SDK)
 
-Same SDK API. Flutter-specific: `CallSettingsBuilder` setter API + `showDialog` / overlay for the prompt.
+Flutter-specific: `SessionSettingsBuilder` setter API + `showDialog` / overlay for the prompt.
 
 **Canonical docs:** https://www.cometchat.com/docs/calls/flutter/idle-timeout
 **Read first:** `cometchat-react-calls/references/idle-timeout.md` — settings + archetype timeouts.
@@ -9,25 +9,26 @@ Same SDK API. Flutter-specific: `CallSettingsBuilder` setter API + `showDialog`
 
 ## SDK API
 
+In 5.x the idle period is a single value (in **seconds**) on `SessionSettingsBuilder` — `setIdleTimeoutPeriod(int timeoutSeconds)` (`cometchat_calls_sdk-5.0.2` `src/builder/session_settings.dart:185`). There is no separate before/after-prompt split.
+
 ```dart
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
 
-final settings = CallSettingsBuilder()
-  ..setIdleTimeoutPeriodBeforePrompt = 60000
-  ..setIdleTimeoutPeriodAfterPrompt = 120000;
-final builtSettings = settings.build();
+final settings = (SessionSettingsBuilder()
+      ..setIdleTimeoutPeriod(180))   // seconds — session_settings.dart:185
+    .build();
 ```
 
-Listener — implement on the GetX controller (cf. `references/raise-hand.md`):
+Listener — implement `SessionStatusListeners` on the GetX controller (cf. `references/raise-hand.md`); `onSessionTimedOut` is `src/listener/session_status_listeners.dart:22`:
 
 ```dart
-class CallController extends GetxController implements CometChatCallsEventsListener {
+class CallController extends GetxController implements SessionStatusListeners {
   @override
   void onSessionTimedOut() {
     Get.snackbar('Call ended', 'You were inactive for too long');
     Get.until((route) => route.isFirst);  // pop to home
   }
-  // ... other handlers
+  // ... other SessionStatusListeners handlers (no-ops or pass-through)
 }
 ```
 
@@ -57,8 +58,9 @@ Future<void> showIdleTimeoutPrompt(BuildContext context) async {
   );
 
   if (result == 'end') {
-    // CometChatCalls.endSession() does NOT exist on Flutter — use the CallSession instance.
-    await CallSession.getInstance().leaveSession();
+    // 5.x teardown: the CallSession INSTANCE leaveSession() (call_session.dart:272).
+    // The static CometChatCalls.endSession exists but is @Deprecated.
+    await CallSession.getInstance()?.leaveSession();
   } else {
     // 'stay' or null — reset custom timer
   }
@@ -81,7 +83,7 @@ Web sister rules apply, plus Flutter-specific:
 
 ## Verification checklist
 
-- [ ] CallSettingsBuilder sets both idle periods
+- [ ] `SessionSettingsBuilder()..setIdleTimeoutPeriod(seconds)` (single value, in seconds)
 - [ ] `onSessionTimedOut` snackbar + nav cleanup
 - [ ] Dialog `barrierDismissible: false`
 - [ ] `mounted` check before showing prompt

package/skills/cometchat-flutter-v5-calls/references/in-call-chat.md

@@ -10,20 +10,23 @@ Same SDK shape. Flutter-specific: `showModalBottomSheet` with `isScrollControlle
 ## SDK API
 
 ```dart
-import 'package:cometchat_calls_uikit/cometchat_calls_uikit.dart';
+import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
 import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
 
-// Wire chat button visibility via the call settings builder
-final settings = CallSettingsBuilder()
-  ..hideChatButton = false;
+// Wire chat button visibility via the (non-deprecated) SessionSettingsBuilder
+final settings = (SessionSettingsBuilder()
+      ..hideChatButton(false))   // session_settings.dart:299
+    .build();
 
-// In your CometChatCallsEventsListener:
+// The chat-button tap arrives on ButtonClickListeners (src/listener/button_click_listeners.dart:34),
+// registered via CallSession.getInstance()?.addButtonClickListener(...) (call_session.dart:90):
 @override
 void onChatButtonClicked() {
   Get.find<CallController>().openChat();
 }
 
-CometChatCalls.setChatButtonUnreadCount(5);
+// Unread badge — INSTANCE method on the session singleton (call_session.dart:489):
+CallSession.getInstance()?.setChatButtonUnreadCount(5);
 ```
 
 ---
@@ -68,7 +71,7 @@ class CallController extends GetxController {
       enableDrag: true,
     );
     unread.value = 0;
-    CometChatCalls.setChatButtonUnreadCount(0);
+    CallSession.getInstance()?.setChatButtonUnreadCount(0);
   }
 }
 
@@ -116,8 +119,8 @@ Web sister rules apply, plus Flutter-specific:
 
 ## Verification checklist
 
-- [ ] `hideChatButton = false` in CallSettings
-- [ ] `onChatButtonClicked` opens bottom sheet
+- [ ] `SessionSettingsBuilder()..hideChatButton(false)`
+- [ ] `onChatButtonClicked` (ButtonClickListeners, registered on `CallSession.getInstance()`) opens bottom sheet
 - [ ] `Get.bottomSheet` uses `isScrollControlled: true` + transparent barrier
 - [ ] `MediaQuery.viewInsets.bottom` padding for keyboard
 - [ ] Group resolved before opening sheet

package/skills/cometchat-flutter-v5-calls/references/migration-v4-to-v5.md

@@ -1,19 +1,24 @@
-# CometChat Calls Flutter SDK v4 → v5 migration
+# CometChat Calls Flutter SDK v4 → v5 migration (raw SDK)
 
-`cometchat_calls_uikit: ^5.0.15` is the v5 calls package for Flutter — drop-in replacement for the v4 calls SDK.
+Moving the **Calls SDK** from 4.x to **`cometchat_calls_sdk ^5.0.2`** on the Flutter V5 (GetX) chat UI Kit — per the product decision that all families use the V5 calls SDK.
 
-**Important:** This migrates the **Calls SDK** (v4 → v5), not the UI Kit cohort (V5 GetX → V6 Bloc, which is `cometchat-flutter-v6-migration`). You can be on UI Kit V5 + Calls SDK v5 — they version independently.
+**Important:** This migrates the **Calls SDK** (4.x → 5.x), not the chat UI Kit cohort (V5 GetX → V6 Bloc, which is `cometchat-flutter-v6-migration`). The chat UI Kit stays on V5 GetX; only the calls layer changes.
 
+> **Why you can't just bump `cometchat_calls_uikit`.** The latest `cometchat_calls_uikit` (5.0.16) still transitively pins `cometchat_calls_sdk ^4.2.2`, and its prebuilt call widgets (`CometChatCallButtons`/`CometChatIncomingCall`/`CometChatOutgoingCall`/`CometChatOngoingCall`) are compiled against the 4.x API. To run the 5.x calls SDK you **drop `cometchat_calls_uikit`** and integrate the **raw `cometchat_calls_sdk ^5.0.2`** directly with a custom call surface.
+
+**Substrate of record:** `~/.pub-cache/hosted/pub.dev/cometchat_calls_sdk-5.0.2/lib/`
 **Canonical docs:** https://www.cometchat.com/docs/calls/flutter/migration-guide-v5
 
 ---
 
-## Step 1 — Bump pubspec
+## Step 1 — Swap the dependency
 
-```yaml
-# pubspec.yaml
-dependencies:
-  cometchat_calls_uikit: ^5.0.15
+```diff
+  # pubspec.yaml
+  dependencies:
+    cometchat_chat_uikit: ^5.2.14     # chat UI Kit stays on V5 (GetX)
+-   cometchat_calls_uikit: ^5.0.15    # 4.x-bound — remove
++   cometchat_calls_sdk: ^5.0.2       # raw 5.x calls SDK (direct dependency)
 ```
 
 ```bash
@@ -25,110 +30,152 @@ cd ios && pod install     # if you have iOS
 
 ## Step 2 — Migrate init
 
+`init` takes a `CallAppSettings` built via `CallAppSettingBuilder` (`src/builder/call_app_settings_request.dart:36`) and runs with `onSuccess`/`onError` callbacks (`cometchatcalls.dart:172`).
+
 ```diff
 - final callSettings = CallAppSettingsBuilder()
 -   ..setAppId('APP_ID')
 -   ..setRegion('REGION');
 - await CometChatCalls.init(callSettings);
 
-+ final settings = CallAppSettings(appId: 'APP_ID', region: 'REGION');
-+ await CometChatCalls.init(settings);
++ final callAppSettings = (CallAppSettingBuilder()
++       ..appId = 'APP_ID'
++       ..region = 'REGION')
++     .build();
++ CometChatCalls.init(
++   callAppSettings,
++   onSuccess: (String s) {},
++   onError: (CometChatCallsException e) {},
++ );
 ```
 
 ---
 
-## Step 3 — Add Calls SDK login
+## Step 3 — Add the 5.x Calls SDK login
+
+4.x had no calls login (it took a per-call auth token). 5.x has its own login that caches the token internally (`cometchatcalls.dart:316`).
 
 ```dart
-// After CometChat.login completes
-final user = (await CometChatUIKit.getLoggedInUser())!;
-final authToken = user.authToken;
-await CometChatCalls.login(authToken: authToken);
+// After CometChat.login completes:
+final authToken = await CometChat.getUserAuthToken();  // static; no User.getAuthToken() method
+if (authToken != null) {
+  CometChatCalls.loginWithAuthToken(
+    authToken: authToken,
+    onSuccess: (user) {},
+    onError: (CometChatCallsException e) {},
+  );
+}
 ```
 
 ---
 
 ## Step 4 — Migrate session settings
 
+`SessionSettingsBuilder` replaces `CallSettingsBuilder` (the latter is `@Deprecated`, `src/builder/call_settings.dart:209`). Methods are chainable / cascade setters (`src/builder/session_settings.dart`).
+
 ```diff
-- final callSettings = CallSettingsBuilder()
+- final callSettings = (CallSettingsBuilder()
 -   ..setSessionType(SessionType.video)
 -   ..startWithAudioMuted(false)
--   ..showRecordingButton(true);
-
-+ final sessionSettings = SessionSettings(
-+   sessionType: SessionType.video,
-+   startAudioMuted: false,
-+   hideRecordingButton: false,    // INVERTED
-+   layout: CallLayout.tile,
-+ );
+-   ..showRecordingButton(true))
+-   .build();
+
++ final sessionSettings = (SessionSettingsBuilder()
++       ..setType(SessionType.video)        // session_settings.dart:197
++       ..startAudioMuted(false)            // :173
++       ..startVideoPaused(false)           // :167
++       ..setLayout(LayoutType.tile)        // :179
++       ..hideRecordingButton(false))       // :227 (INVERTED sense vs show*)
++     .build();
 ```
 
 ---
 
-## Step 5 — Migrate listener to event subscriptions
+## Step 5 — Migrate the listener to the 5 split listeners
+
+The single `CometChatCallsEventsListener` is `@Deprecated` (`src/listener/cometchat_calls_events_listener.dart:16`). 5.x splits events across `SessionStatusListeners`, `ParticipantEventListeners`, `MediaEventListeners`, `ButtonClickListeners`, `LayoutListeners` — registered on `CallSession.getInstance()` (after `joinSession.onSuccess`).
 
 ```diff
 - class MyEvents implements CometChatCallsEventsListener {
 -   @override
 -   void onCallEnded() { /* ... */ }
 -   @override
--   void onUserJoined(User user) { /* ... */ }
+-   void onUserJoined(RTCUser user) { /* ... */ }
 -   // ...
 - }
-- CometChatCalls.addCallsEventsListener('id', MyEvents());
-
-+ final unsub1 = CometChatCalls.addEventListener(CallEvent.sessionLeft, () { /* ... */ });
-+ final unsub2 = CometChatCalls.addEventListener(CallEvent.participantJoined, (participant) { /* ... */ });
-+ final unsub3 = CometChatCalls.addEventListener(CallEvent.participantLeft, (participant) { /* ... */ });
+- CometChatCalls.addCallsEventListeners('id', MyEvents());
+
++ class MyEvents implements SessionStatusListeners, ParticipantEventListeners {
++   @override
++   void onSessionLeft() { /* was onCallEnded */ }       // session_status_listeners.dart:10
++   @override
++   void onParticipantJoined(Participant p) { /* was onUserJoined */ }  // participant_event_listeners.dart:12
++   @override
++   void onParticipantLeft(Participant p) { /* was onUserLeft */ }      // :15
++   // ... remaining interface methods (no-ops or pass-through)
++ }
++
++ // inside joinSession.onSuccess:
++ final events = MyEvents();
++ CallSession.getInstance()?.addSessionStatusListener(events);     // call_session.dart:66
++ CallSession.getInstance()?.addParticipantEventListener(events);  // :74
 +
 + @override
 + void dispose() {
-+   unsub1.call();
-+   unsub2.call();
-+   unsub3.call();
++   CallSession.getInstance()?.removeSessionStatusListener(events);
++   CallSession.getInstance()?.removeParticipantEventListener(events);
 +   super.dispose();
 + }
 ```
 
 ---
 
-## Step 6 — Method renames + receiver shift
+## Step 6 — Start/join + control method renames + receiver shift
 
-v5 moved most call-control APIs from static methods on `CometChatCalls` to **instance methods on `CallSession`** (the singleton fetched via `CallSession.getInstance()`). The static `endSession()` is preserved as a deprecated shim — the others were removed.
+The two-step `generateToken` + `startSession` collapses into a single `joinSession` (`cometchatcalls.dart:735`). In-call controls move from static methods on `CometChatCalls` to **instance methods on `CallSession`** (the singleton via `CallSession.getInstance()`).
 
 ```diff
-// session lifecycle — receiver changes from CometChatCalls (static) to CallSession (singleton)
-- CometChatCalls.endSession()
-+ await CallSession.getInstance()?.leaveSession()
-
-// media controls — same receiver shift
-- CometChatCalls.muteAudio(true)
-+ CallSession.getInstance()?.muteAudio()
-- CometChatCalls.muteAudio(false)
-+ CallSession.getInstance()?.unmuteAudio()
-
-- CometChatCalls.startScreenShare()
-+ CallSession.getInstance()?.startScreenShare()
-
-// layout stays static
-- CometChatCalls.setMode(mode)
-+ CometChatCalls.setLayout(layout)
+// start the session
+- CometChatCalls.generateToken(sessionId, authToken, onSuccess: (t) {
+-   CometChatCalls.startSession(t.token!, callSettings, onSuccess: (w) {}, onError: (e) {});
+- }, onError: (e) {});
++ CometChatCalls.joinSession(
++   sessionId: sessionId,                 // SDK mints the call token internally
++   sessionSettings: sessionSettings,
++   onSuccess: (Widget? w) {},
++   onError: (CometChatCallsException e) {},
++ );
+
+// teardown — receiver changes from CometChatCalls (static) to CallSession (singleton)
+- CometChatCalls.endSession(onSuccess: (_) {}, onError: (e) {})
++ await CallSession.getInstance()?.leaveSession()            // call_session.dart:272
+
+// media controls — same receiver shift, now no-arg
+- CometChatCalls.muteAudio()
++ CallSession.getInstance()?.muteAudio()                     // call_session.dart:131
++ CallSession.getInstance()?.unMuteAudio()                   // :145
+- CometChatCalls.pauseVideo() / resumeVideo()
++ CallSession.getInstance()?.pauseVideo() / resumeVideo()    // :168 / :182
+
+// layout — also moves to the instance (NOT static in 5.x)
+- CometChatCalls.setLayout(CallLayout.spotlight)
++ CallSession.getInstance()?.setLayout(LayoutType.spotlight) // :394
 ```
 
-**`CallSession.getInstance()` returns `CallSession?` (nullable)** — null when there's no active session. Use `?.` to safely chain; calling on null is a no-op.
+**`CallSession.getInstance()` returns `CallSession?` (nullable)** — null when there's no active session. Use `?.` to safely chain.
 
 ---
 
 ## Step 7 — GetX state preservation
 
-If you're using GetX controllers around the calls (per `cometchat-flutter-v5-calls/SKILL.md`), the state shape doesn't change — only the underlying SDK calls. Sample diff in a GetX controller:
+If you use GetX controllers around the calls (per `cometchat-flutter-v5-calls/SKILL.md`), the state shape doesn't change — only the underlying SDK calls. Sample diff in a GetX controller:
 
 ```diff
   class CallController extends GetxController {
     void startCall(String sessionId) async {
--     await CometChatCalls.startSession(sessionId, settings: callSettings);
-+     await CometChatCalls.joinSession(sessionId, settings: sessionSettings);
+-     await CometChatCalls.startSession(callToken, settings: callSettings);
++     CometChatCalls.joinSession(sessionId: sessionId, sessionSettings: sessionSettings,
++       onSuccess: (w) {}, onError: (e) {});
     }
 
     void endCall() async {
@@ -142,19 +189,22 @@ If you're using GetX controllers around the calls (per `cometchat-flutter-v5-cal
 
 ## Verification checklist
 
-- [ ] `pubspec.yaml` lists `cometchat_calls_uikit: ^5.0.15` (or higher)
+- [ ] `pubspec.yaml` lists `cometchat_calls_sdk: ^5.0.2` and NO `cometchat_calls_uikit`
 - [ ] `flutter pub get` + `pod install` succeed
-- [ ] `CometChatCalls.login(authToken:)` called after `CometChat.login`
-- [ ] CallSettingsBuilder replaced with `SessionSettings`
-- [ ] CometChatCallsEventsListener replaced with `addEventListener`
-- [ ] Method renames applied
-- [ ] GetX controllers updated to v5 method names
-- [ ] Real-device smoke: iOS + Android, incoming/outgoing/mute/screenshare
+- [ ] `CometChatCalls.loginWithAuthToken(authToken:)` called after `CometChat.login`
+- [ ] `CallSettingsBuilder` replaced with `SessionSettingsBuilder`
+- [ ] Single `CometChatCallsEventsListener` replaced with the 5 split listeners on `CallSession.getInstance()`
+- [ ] `generateToken` + `startSession` collapsed into `joinSession(sessionId:, sessionSettings:, ...)`
+- [ ] In-call controls + `leaveSession` moved to `CallSession.getInstance()?.X()`
+- [ ] Prebuilt `cometchat_calls_uikit` call widgets removed; custom call surface in place
+- [ ] Real-device smoke: iOS + Android, incoming/outgoing/mute/layout/leave
 
 ---
 
 ## Pointers
 
 - Canonical migration: https://www.cometchat.com/docs/calls/flutter/migration-guide-v5
-- `cometchat-flutter-v5-calls/SKILL.md` — Flutter calls architecture (GetX patterns)
-- `cometchat-flutter-v6-calls/` — V6 cohort (Bloc); V6 starts on Calls SDK v5 — no migration needed
+- `cometchat-flutter-v5-calls/SKILL.md` — Flutter calls architecture on the 5.x SDK (GetX patterns)
+- `cometchat-flutter-v5-calls/references/call-session.md` — canonical 5.x SDK API surface
+- `cometchat-flutter-v6-calls/` — V6 cohort (Bloc) on the SAME 5.0.2 calls SDK
+```