@cometchat/skills 4.4.1 → 5.0.0

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

@@ -1,210 +0,0 @@
-# CometChat Calls Flutter SDK v4 → v5 migration (raw 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** (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 — Swap the dependency
-
-```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
-flutter pub get
-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 callAppSettings = (CallAppSettingBuilder()
-+       ..appId = 'APP_ID'
-+       ..region = 'REGION')
-+     .build();
-+ CometChatCalls.init(
-+   callAppSettings,
-+   onSuccess: (String s) {},
-+   onError: (CometChatCallsException e) {},
-+ );
-```
-
----
-
-## 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 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()
--   ..setSessionType(SessionType.video)
--   ..startWithAudioMuted(false)
--   ..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 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(RTCUser user) { /* ... */ }
--   // ...
-- }
-- 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() {
-+   CallSession.getInstance()?.removeSessionStatusListener(events);
-+   CallSession.getInstance()?.removeParticipantEventListener(events);
-+   super.dispose();
-+ }
-```
-
----
-
-## Step 6 — Start/join + control method renames + receiver shift
-
-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
-// 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.
-
----
-
-## Step 7 — GetX state preservation
-
-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(callToken, settings: callSettings);
-+     CometChatCalls.joinSession(sessionId: sessionId, sessionSettings: sessionSettings,
-+       onSuccess: (w) {}, onError: (e) {});
-    }
-
-    void endCall() async {
--     CometChatCalls.endSession();
-+     await CallSession.getInstance()?.leaveSession();
-    }
-  }
-```
-
----
-
-## Verification checklist
-
-- [ ] `pubspec.yaml` lists `cometchat_calls_sdk: ^5.0.2` and NO `cometchat_calls_uikit`
-- [ ] `flutter pub get` + `pod install` succeed
-- [ ] `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 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
-```

package/skills/cometchat-flutter-v5-calls/references/raise-hand.md

@@ -1,255 +0,0 @@
-# Raise hand on Flutter (UIKit V5, GetX-based)
-
-Same SDK conceptual API as web/native. Flutter V5 uses GetX for state management — the canonical pattern is a `GetxController` that wraps the call event listener and publishes raised-hand state via `Rx<List<RaisedParticipant>>`.
-
-**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/raise-hand
-**Read first:** `cometchat-react-calls/references/raise-hand.md` — UX shape + anti-patterns are identical; this is the V5 GetX-specific wiring.
-
----
-
-## SDK API
-
-Raise/lower hand are **instance methods on the `CallSession` singleton**, NOT static on `CometChatCalls` (`cometchat_calls_sdk-5.0.2` `src/call_session.dart:292,306`). Participant hand events arrive via `ParticipantEventListeners`, registered through `CallSession.getInstance()?.addParticipantEventListener(...)` (`src/call_session.dart:74`).
-
-```dart
-import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
-
-// Local user
-CallSession.getInstance()?.raiseHand();   // call_session.dart:292
-CallSession.getInstance()?.lowerHand();   // call_session.dart:306
-
-// Listener — implement the split ParticipantEventListeners interface
-class HandListener implements ParticipantEventListeners {
-  @override
-  void onParticipantHandRaised(Participant participant) {  // participant_event_listeners.dart:30
-    // participant.uid, participant.name (both nullable)
-  }
-
-  @override
-  void onParticipantHandLowered(Participant participant) {  // :33
-    // ...
-  }
-  // ... other ParticipantEventListeners methods (no-ops or pass-through)
-}
-
-// Register on the session singleton (inside joinSession.onSuccess):
-CallSession.getInstance()?.addParticipantEventListener(HandListener());  // :74
-
-// Settings flag — method on the (non-deprecated) SessionSettingsBuilder.
-final settings = (SessionSettingsBuilder()
-      ..hideRaiseHandButton(true))   // session_settings.dart:215
-    .build();
-```
-
----
-
-## GetX controller
-
-```dart
-import 'package:get/get.dart';
-import 'package:cometchat_calls_sdk/cometchat_calls_sdk.dart';
-
-class RaisedParticipant {
-  final String uid;
-  final String name;
-  final DateTime raisedAt;
-  RaisedParticipant({required this.uid, required this.name, required this.raisedAt});
-}
-
-class RaiseHandController extends GetxController implements ParticipantEventListeners {
-  final localRaised = false.obs;
-  final raised = <RaisedParticipant>[].obs;
-
-  void toggle() {
-    if (localRaised.value) {
-      CallSession.getInstance()?.lowerHand();
-    } else {
-      CallSession.getInstance()?.raiseHand();
-    }
-    localRaised.value = !localRaised.value;
-  }
-
-  @override
-  void onParticipantHandRaised(Participant p) {
-    // Participant.uid / .name are nullable in 5.x.
-    final uid = p.uid ?? '';
-    final entry = RaisedParticipant(
-      uid: uid, name: p.name ?? uid, raisedAt: DateTime.now(),
-    );
-    raised.removeWhere((r) => r.uid == uid);
-    raised.add(entry);
-    raised.sort((a, b) => a.raisedAt.compareTo(b.raisedAt));
-  }
-
-  @override
-  void onParticipantHandLowered(Participant p) {
-    raised.removeWhere((r) => r.uid == (p.uid ?? ''));
-  }
-
-  // ... implement other ParticipantEventListeners methods (no-ops or pass-through)
-}
-```
-
-`.obs` is GetX's reactive marker. UI rebuilds automatically when these mutate.
-
----
-
-## Toggle button widget
-
-```dart
-class RaiseHandButton extends StatelessWidget {
-  const RaiseHandButton({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    final ctrl = Get.find<RaiseHandController>();
-    return Obx(() => GestureDetector(
-      onTap: () {
-        ctrl.toggle();
-        // Announce for screen readers
-        SemanticsService.announce(
-          ctrl.localRaised.value ? 'Hand raised' : 'Hand lowered',
-          TextDirection.ltr,
-        );
-      },
-      child: Semantics(
-        button: true,
-        selected: ctrl.localRaised.value,
-        label: ctrl.localRaised.value ? 'Lower hand' : 'Raise hand',
-        child: Container(
-          padding: const EdgeInsets.all(12),
-          decoration: BoxDecoration(
-            color: ctrl.localRaised.value
-              ? const Color(0xFFFFD60A)
-              : Colors.white24,
-            borderRadius: BorderRadius.circular(32),
-          ),
-          child: Row(
-            children: [
-              const Text('✋'),
-              const SizedBox(width: 4),
-              Text(ctrl.localRaised.value ? 'Lower' : 'Raise'),
-            ],
-          ),
-        ),
-      ),
-    ));
-  }
-}
-```
-
-`SemanticsService.announce` is the Flutter equivalent of `aria-live` / `UIAccessibility.post(.announcement, ...)` — TalkBack and VoiceOver pick up the announcement.
-
-`Semantics` wrapper sets `button: true`, `selected:`, `label:` — these map to platform a11y conventions.
-
----
-
-## Raised-hands sheet (DraggableScrollableSheet)
-
-```dart
-class RaisedHandsSheet extends StatelessWidget {
-  const RaisedHandsSheet({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    final ctrl = Get.find<RaiseHandController>();
-    return DraggableScrollableSheet(
-      initialChildSize: 0.1,
-      minChildSize: 0.1,
-      maxChildSize: 0.5,
-      builder: (context, scrollController) => Container(
-        decoration: const BoxDecoration(
-          color: Colors.white,
-          borderRadius: BorderRadius.vertical(top: Radius.circular(16)),
-        ),
-        child: Obx(() => ListView(
-          controller: scrollController,
-          padding: const EdgeInsets.all(16),
-          children: [
-            Text(
-              'Raised hands (${ctrl.raised.length})',
-              style: const TextStyle(fontWeight: FontWeight.w600),
-            ),
-            const SizedBox(height: 8),
-            for (final p in ctrl.raised)
-              ListTile(
-                leading: const Text('✋', style: TextStyle(fontSize: 20)),
-                title: Text(p.name),
-                trailing: Text(
-                  '${DateTime.now().difference(p.raisedAt).inSeconds}s ago',
-                  style: const TextStyle(color: Colors.grey),
-                ),
-              ),
-          ],
-        )),
-      ),
-    );
-  }
-}
-```
-
----
-
-## Wiring to the call session
-
-```dart
-RaiseHandController? _handCtrl;
-
-@override
-void initState() {
-  super.initState();
-  _handCtrl = Get.put(RaiseHandController());
-  // NOTE: attach the listener inside joinSession.onSuccess (CallSession.getInstance()
-  // is null until the session exists). If this widget is mounted only after the
-  // session is live, attach here:
-  CallSession.getInstance()?.addParticipantEventListener(_handCtrl!);  // call_session.dart:74
-}
-
-@override
-void dispose() {
-  if (_handCtrl != null) {
-    CallSession.getInstance()?.removeParticipantEventListener(_handCtrl!);  // call_session.dart:78
-  }
-  Get.delete<RaiseHandController>();
-  super.dispose();
-}
-```
-
-The 5.x SDK identifies listeners by object identity (a `Set`), not a string ID — keep the same controller instance you registered and pass it to `removeParticipantEventListener` on dispose.
-
----
-
-## Anti-patterns
-
-Web sister reference rules apply, plus Flutter V5-specific:
-
-1. **Forgetting `Get.delete<RaiseHandController>()` on dispose.** GetX retains the controller across navigation — listeners survive past the call view, fire stale events.
-2. **`Get.put(RaiseHandController(), permanent: true)` for the call.** Lifetime is too long; controller survives logout. Use scoped `Get.put` without permanent.
-3. **Skipping `Semantics` wrapper on the button.** TalkBack reads the GestureDetector as untyped — bad a11y.
-4. **`Obx` rebuilding the entire widget tree** when only one `.obs` field changes. Wrap minimally — the `Obx` should hug only the reactive part.
-5. **DraggableScrollableSheet without `initialChildSize` < `minChildSize`** — sheet pops above the screen on render, looks broken.
-
----
-
-## Verification checklist
-
-- [ ] `RaiseHandController` is a `GetxController`
-- [ ] `localRaised` and `raised` are `.obs` reactive
-- [ ] `Obx` wraps only reactive parts of the UI
-- [ ] `Semantics` wrapper on toggle button with `button: true, selected:, label:`
-- [ ] `SemanticsService.announce` on toggle
-- [ ] Same controller instance registered via `CallSession.getInstance()?.addParticipantEventListener(ctrl)` and removed via `removeParticipantEventListener(ctrl)` on dispose
-- [ ] `Get.delete<RaiseHandController>()` in `dispose()`
-- [ ] `SessionSettingsBuilder()..hideRaiseHandButton(true)` if custom UI
-- [ ] Real-device smoke: 3 devices (mix of iOS + Android), raise from 2 → host sees both
-- [ ] TalkBack / VoiceOver announces "Hand raised" / "Hand lowered" on toggle
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/raise-hand.md` — sister reference (UX shape)
-- `cometchat-flutter-v5-calls` SKILL.md — V5 hard rules + GetX scope rules
-- `cometchat-flutter-v6-calls/references/raise-hand.md` — V6 sibling (Bloc-based — different state shape)
-- `cometchat-a11y` — Flutter Semantics + SemanticsService
-- Canonical docs: https://www.cometchat.com/docs/calls/flutter/raise-hand

package/skills/cometchat-flutter-v5-calls/references/ringing-integration.md

@@ -1,196 +0,0 @@
-# Ringing — call signaling with custom UI (Flutter V5 / GetX)
-
-Same SDK shape as web/RN. Flutter-specific deltas: GetX-controlled state, flutter_callkit_incoming for OS-level backgrounded UI, just_audio for foreground ringtone.
-
-**Read first:** `cometchat-react-calls/references/ringing-integration.md` — full architecture, hard rules.
-
----
-
-## SDK API + GetX controller
-
-```dart
-import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
-import 'package:cometchat_sdk/cometchat_sdk.dart';   // Call, CallListener (Chat SDK signaling)
-
-class CallSignalingController extends GetxController implements CallListener {
-  final incoming = Rx<Call?>(null);
-  final outgoing = Rx<Call?>(null);
-  final activeSessionId = Rx<String?>(null);
-
-  static const _listenerId = 'app';
-
-  @override
-  void onInit() {
-    super.onInit();
-    CometChat.addCallListener(_listenerId, this);
-  }
-
-  @override
-  void onIncomingCallReceived(Call call) {
-    incoming.value = call;
-  }
-
-  @override
-  void onOutgoingCallAccepted(Call call) {
-    outgoing.value = null;
-    activeSessionId.value = call.sessionId;
-  }
-
-  @override
-  void onOutgoingCallRejected(Call call) {
-    outgoing.value = null;
-  }
-
-  @override
-  void onIncomingCallCancelled(Call call) {
-    incoming.value = null;
-  }
-
-  @override
-  void onCallEndedMessageReceived(Call call) {
-    incoming.value = null;
-    outgoing.value = null;
-    activeSessionId.value = null;
-  }
-
-  Future<void> initiate(String receiverUid, {String type = 'video'}) async {
-    final call = Call(
-      receiverUid: receiverUid,
-      type: type == 'video' ? CometChatCallType.video : CometChatCallType.audio, // ctor param is `type`, not `callType`
-      receiverType: CometChatReceiverType.user,
-    );
-    // initiateCall is void + callback: the Call comes back in onSuccess, not via await.
-    CometChat.initiateCall(call,
-      onSuccess: (Call result) => outgoing.value = result,
-      onError: (CometChatException e) => debugPrint(e.message ?? ''));
-  }
-
-  Future<void> accept(Call call) async {
-    // acceptCall takes the sessionID POSITIONALLY + onSuccess/onError; it returns void.
-    CometChat.acceptCall(call.sessionId!,
-      onSuccess: (Call result) {
-        incoming.value = null;
-        activeSessionId.value = result.sessionId;
-      },
-      onError: (CometChatException e) => debugPrint(e.message ?? ''));
-  }
-
-  Future<void> reject(Call call) async {
-    // rejectCall: positional sessionID + status String + onSuccess/onError (void).
-    CometChat.rejectCall(call.sessionId!, CometChatCallStatus.rejected,
-      onSuccess: (Call result) => incoming.value = null,
-      onError: (CometChatException e) => debugPrint(e.message ?? ''));
-  }
-
-  @override
-  void onClose() {
-    CometChat.removeCallListener(_listenerId);
-    super.onClose();
-  }
-}
-```
-
-Initialize at app start via `Get.put(CallSignalingController(), permanent: true);` so the listener survives navigation.
-
----
-
-## Incoming-call overlay
-
-```dart
-class IncomingCallOverlay extends StatelessWidget {
-  const IncomingCallOverlay({super.key});
-
-  @override
-  Widget build(BuildContext context) {
-    final ctrl = Get.find<CallSignalingController>();
-
-    return Obx(() {
-      final call = ctrl.incoming.value;
-      if (call == null) return const SizedBox.shrink();
-
-      return Material(
-        color: Colors.black.withOpacity(0.85),
-        child: Center(
-          child: Column(
-            mainAxisSize: MainAxisSize.min,
-            children: [
-              CircleAvatar(
-                radius: 60,
-                backgroundImage: NetworkImage(call.callInitiator?.avatar ?? ''),
-              ),
-              const SizedBox(height: 16),
-              Text(
-                call.callInitiator?.name ?? 'Unknown',
-                style: const TextStyle(color: Colors.white, fontSize: 24),
-              ),
-              Text('Incoming ${call.type} call', style: const TextStyle(color: Colors.white70)),
-              const SizedBox(height: 32),
-              Row(
-                mainAxisAlignment: MainAxisAlignment.center,
-                children: [
-                  Semantics(
-                    label: 'Decline call',
-                    button: true,
-                    child: FloatingActionButton(
-                      backgroundColor: Colors.red,
-                      onPressed: () => ctrl.reject(call),
-                      child: const Icon(Icons.call_end),
-                    ),
-                  ),
-                  const SizedBox(width: 32),
-                  Semantics(
-                    label: 'Accept call',
-                    button: true,
-                    child: FloatingActionButton(
-                      backgroundColor: Colors.green,
-                      onPressed: () => ctrl.accept(call),
-                      child: const Icon(Icons.call),
-                    ),
-                  ),
-                ],
-              ),
-            ],
-          ),
-        ),
-      );
-    });
-  }
-}
-```
-
-Wrap above the navigator (typically in `MaterialApp.builder` or as a sibling Stack item) so it surfaces over any route.
-
----
-
-## Backgrounded ring — flutter_callkit_incoming + push (mandatory)
-
-GetX listeners only fire while the app is alive. For backgrounded/killed ring, server fires push (APNs PushKit on iOS, FCM data-message on Android) → `flutter_callkit_incoming` shows OS-level UI. See `cometchat-flutter-v5-calls/references/server-push-bridge.md`.
-
----
-
-## Anti-patterns
-
-Web sister rules apply, plus Flutter-specific:
-
-1. **`Get.put` without `permanent: true`.** Controller disposed on route change → listener gone → backgrounded calls miss.
-2. **`StatefulWidget` with `setState` instead of `Obx`.** Rx values won't trigger rebuild without `Obx` wrapper.
-3. **JS-style ringtone via `audioplayers` during a CallKit ring.** Both play at once.
-
----
-
-## Verification checklist
-
-- [ ] `Get.put(CallSignalingController(), permanent: true)` at app start
-- [ ] `IncomingCallOverlay` mounted in `MaterialApp.builder`
-- [ ] `removeCallListener` in `onClose`
-- [ ] `flutter_callkit_incoming` wired for backgrounded ring
-- [ ] Real-device smoke (iOS + Android): foreground, backgrounded, killed ring all surface UI
-
----
-
-## Pointers
-
-- `cometchat-react-calls/references/ringing-integration.md` — canonical
-- `cometchat-flutter-v5-calls/SKILL.md` — Flutter calls architecture
-- `cometchat-flutter-v5-calls/references/server-push-bridge.md` — backgrounded ring
-- Canonical docs: https://www.cometchat.com/docs/calls/flutter/ringing