@cometchat/skills 4.0.0 → 4.2.0

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

@@ -0,0 +1,190 @@
+# Group calls — broadcast meeting pattern (Flutter V6)
+
+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).
+
+By-design kit behavior — same semantic across all CometChat kits.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/group-calls
+
+V6 specifics: Flutter V6 folds calls into `cometchat_chat_uikit ^6.0.0-beta2` (no separate calls package). Bloc-based state. **At v6.0.0-beta2, the outgoing-call → in-call transition is broken for 1:1 calls** (vendor bug — see SKILL.md §1.7); this affects group meetings too if customers use the kit's outgoing-call UI. The custom-UI approach is more reliable on V6 today.
+
+---
+
+## Architecture
+
+```
+Caller (uidA, member of groupX)        CometChat                Receivers (members of groupX)
+  │                                       │                              │
+  │ CometChatCallButtons / custom code    │                              │
+  │ sends CustomMessage(GUID, GROUP,      │                              │
+  │   "meeting", { callType, sessionId }) │                              │
+  ├──────────────────────────────────────>│                              │
+  │                                       │ onCustomMessageReceived      │
+  │                                       ├─────────────────────────────>│
+  │ caller pushes OngoingCall screen      │  receiver taps Join          │
+  │  with sessionID = groupGuid           │  → joinSession(GUID)         │
+  ├──────────────────────────────────────>│ <─────────────────────────── │
+  │            ───── WebRTC session active (sessionId = group GUID) ─────│
+```
+
+| Channel | 1:1 user calls | Group calls |
+|---|---|---|
+| Signaling | `CometChat.initiateCall(call, callback)` | `CometChat.sendCustomMessage(message, callback)` (type="meeting") |
+| Receiver event | `CallListener.onIncomingCallReceived` | `MessageListener.onCustomMessageReceived` |
+| Session ID | server-generated unique | group's GUID (persistent) |
+
+---
+
+## Hard rules
+
+1. **Group calls broadcast a custom message; they do NOT use the call listener.** Custom UI must add a `MessageListener`.
+2. **Session ID = group GUID.** Persistent.
+3. **V6 vendor bug applies to groups too** (SKILL.md §1.7) — kit's outgoing-call screen does not reliably transition to ongoing-call surface. Prefer custom UI for groups on v6.0.0-beta2.
+4. **`navigatorKey: CallNavigationContext.navigatorKey` required on MaterialApp** if using ANY kit-driven call UI path (group or 1:1) — same as the SKILL rule.
+5. **No `CometChat.endCall` for groups.** Use `CometChatUIKitCalls.endSession()` only.
+
+---
+
+## Caller side — kit-based
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+
+CometChatCallButtons(
+  group: group,
+)
+```
+
+Tap → kit sends meeting `CustomMessage` + opens outgoing-call screen.
+
+> **⚠️ At v6.0.0-beta2, the outgoing→in-call transition is broken** (vendor — SKILL §1.7). Caller may see "Calling..." indefinitely after kit-driven group call. **Workaround**: use the custom-UI path below until vendor fix lands.
+
+## Caller side — custom UI (RECOMMENDED on v6.0.0-beta2)
+
+```dart
+import 'package:flutter_chat_sdk/flutter_chat_sdk.dart';
+
+Future<void> startGroupCall(BuildContext context, String groupGuid, String callType) async {
+  final sessionId = groupGuid;
+  final customData = {'callType': callType, 'sessionId': sessionId};
+
+  final meetingMessage = CustomMessage(
+    receiverUid: groupGuid,
+    receiverType: CometChatReceiverType.group,
+    customData: customData,
+    type: 'meeting',
+  )
+    ..category = MessageCategoryConstants.custom
+    ..metadata = {
+      'incrementUnreadCount': true,
+      'pushNotification': 'meeting',
+      ...customData,
+    };
+
+  await CometChat.sendCustomMessage(
+    meetingMessage,
+    onSuccess: (msg) {
+      // Caller navigates to YOUR OngoingCall screen (not the kit's)
+      Navigator.of(context).pushNamed('/ongoing-call', arguments: {
+        'sessionId': sessionId,
+        'callType': callType,
+      });
+    },
+    onError: (e) {/* surface error */},
+  );
+}
+```
+
+Then in your custom `/ongoing-call` screen, call `CometChatUIKitCalls.startSession(callToken, callSettings, ...)` against your own RTC view — same primitives the kit uses internally, but you control the navigation.
+
+---
+
+## Receiver side — kit-based
+
+`CometChatMessageList(group: group)` (or whichever message-list widget V6 ships) auto-renders the meeting message as a "Join meeting" card. Tap → kit calls `generateToken` + pushes the ongoing-call screen.
+
+> Same v6.0.0-beta2 caveat applies — if the kit's ongoing-call transition is broken, receivers may also see "Connecting…" indefinitely. Prefer custom join flow.
+
+## Receiver side — custom UI (RECOMMENDED)
+
+```dart
+import 'package:flutter_chat_sdk/flutter_chat_sdk.dart';
+
+const groupMeetingListenerId = 'APP_ROOT_GROUP_MEETING_LISTENER';
+
+class MeetingListener {
+  void register({required void Function(IncomingMeetingInfo) onIncoming}) {
+    CometChat.addMessageListener(
+      groupMeetingListenerId,
+      MessageListener(
+        onCustomMessageReceived: (msg) {
+          if (msg.category != MessageCategoryConstants.custom) return;
+          if (msg.type != 'meeting') return;
+
+          final customData = msg.customData ?? {};
+          onIncoming(IncomingMeetingInfo(
+            sessionId: customData['sessionId'] as String? ?? msg.receiverUid,
+            callType: customData['callType'] as String? ?? 'video',
+            fromUid: msg.sender?.uid ?? 'unknown',
+            groupGuid: msg.receiverUid,
+          ));
+        },
+      ),
+    );
+  }
+
+  void unregister() => CometChat.removeMessageListener(groupMeetingListenerId);
+}
+```
+
+In a Bloc-based app, dispatch an event into your CallBloc; the listener's `onIncoming` callback wraps the Bloc emit.
+
+Register AFTER `CometChatUIKit.login` succeeds (e.g. in the auth Bloc's `_onLoginSuccess` state transition).
+
+---
+
+## Edge cases
+
+### V6 vendor blocker context
+
+This SKILL.md notes that V6 calling is partially-blocked at v6.0.0-beta2 — specifically the outgoing-call → in-call screen transition. **Production Flutter customers should stay on V5** for both 1:1 and group calls until the vendor fixes the V6 BLoC handler. Group calls on V6 inherit the same blocker.
+
+### Late joining
+
+Meeting persists in chat. Tap any time to join.
+
+### Push notifications
+
+Meeting `CustomMessage.metadata.pushNotification = "meeting"` — delivered as regular FCM/APNs. To get CallKit/ConnectionService ring on iOS/Android, intercept the push and route to `flutter_callkit_incoming` manually.
+
+---
+
+## Anti-patterns
+
+1. **Only `CometChat.addCallListener` registered.** Won't fire for groups.
+2. **Relying on V6 kit's outgoing-call screen for groups on v6.0.0-beta2.** Vendor blocker. Use custom navigation.
+3. **`CometChat.endCall(sessionId)` after group hangup.** No call entity.
+4. **`MessageListener` registered before login.** Silently dropped.
+5. **Skipping `navigatorKey` setup** for any kit-driven call path.
+
+---
+
+## Verification checklist
+
+- [ ] V6 SKILL.md §1.7 `navigatorKey` requirement met (MaterialApp has CallNavigationContext.navigatorKey)
+- [ ] If kit caller: `CometChatCallButtons(group: group)` — but verify outgoing-call transition works post-vendor-fix
+- [ ] If custom caller: `CometChat.sendCustomMessage(type: 'meeting', category: custom, customData: {callType, sessionId})`
+- [ ] If kit receiver: `CometChatMessageList(group: group)` — see V6 vendor blocker caveat
+- [ ] If custom receiver: `CometChat.addMessageListener` registered AFTER login with category+type filter
+- [ ] On hangup: `CometChatUIKitCalls.endSession()` only
+- [ ] Late-joining tested
+- [ ] Push notifications fire for offline members
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v6-calls/SKILL.md` §1.7 — `navigatorKey` requirement + V6 vendor blocker context
+- `ringing-integration.md` — 1:1 user calls (different channel)
+- Cross-platform reference (semantic ground-truth): `cometchat-react-calls/references/group-calls.md`
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/group-calls

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

@@ -0,0 +1,80 @@
+# Idle timeout on Flutter V6 (Bloc-based)
+
+Same SDK API as V5; Bloc-based wiring. Read `cometchat-flutter-v5-calls/references/idle-timeout.md` first.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/idle-timeout
+
+---
+
+## SDK API + listener bridge
+
+Same `CallSettingsBuilder` setters as V5. Listener via Bloc bridge (cf. `cometchat-flutter-v6-calls/references/raise-hand.md`):
+
+```dart
+abstract class CallEvent {}
+class _SessionTimedOut extends CallEvent {}
+
+class CallBloc extends Bloc<CallEvent, CallState> implements CometChatCallsEventsListener {
+  CallBloc() : super(const CallState()) {
+    on<_SessionTimedOut>(_onTimedOut);
+    CometChatCalls.addCallEventListener('call-bloc', this);
+  }
+
+  @override
+  void onSessionTimedOut() {
+    add(_SessionTimedOut());
+  }
+
+  void _onTimedOut(_SessionTimedOut event, Emitter<CallState> emit) {
+    emit(state.copyWith(timedOut: true));
+  }
+
+  @override
+  Future<void> close() {
+    CometChatCalls.removeCallEventListener('call-bloc');
+    return super.close();
+  }
+}
+```
+
+UI listens for `state.timedOut`:
+
+```dart
+BlocListener<CallBloc, CallState>(
+  listenWhen: (prev, curr) => !prev.timedOut && curr.timedOut,
+  listener: (context, state) async {
+    ScaffoldMessenger.of(context).showSnackBar(
+      const SnackBar(content: Text('Call ended due to inactivity')),
+    );
+    Navigator.of(context).popUntil((route) => route.isFirst);
+  },
+  child: /* call surface */,
+)
+```
+
+`BlocListener` is one-shot side effects (navigation, snackbars). `listenWhen` ensures the listener only fires on the transition.
+
+---
+
+## Custom prompt — same showDialog as V5
+
+Identical code; cite V5 sister reference.
+
+---
+
+## Verification checklist
+
+- [ ] CallSettingsBuilder sets both idle periods
+- [ ] CallBloc bridges `onSessionTimedOut` to `_SessionTimedOut` event
+- [ ] BlocListener with `listenWhen` triggers nav + snackbar
+- [ ] Bloc `close()` removes the listener
+- [ ] Real-device smoke: same as V5
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/idle-timeout.md` — V5 sister
+- `cometchat-flutter-v6-calls` SKILL.md — V6 hard rules
+- `cometchat-flutter-v6-calls/references/raise-hand.md` — Bloc-bridge sibling pattern
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/idle-timeout

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

@@ -0,0 +1,122 @@
+# In-call chat on Flutter V6 (Bloc)
+
+Same SDK shape; Bloc-driven open/unread state.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/in-call-chat
+**Read first:** `cometchat-flutter-v5-calls/references/in-call-chat.md` — sheet pattern + group-as-session helper.
+
+---
+
+## State + bloc
+
+```dart
+class InCallChatState extends Equatable {
+  final bool open;
+  final int unread;
+  final Group? group;
+  const InCallChatState({this.open = false, this.unread = 0, this.group});
+  InCallChatState copyWith({bool? open, int? unread, Group? group}) =>
+    InCallChatState(open: open ?? this.open, unread: unread ?? this.unread, group: group ?? this.group);
+  @override List<Object?> get props => [open, unread, group?.guid];
+}
+
+abstract class InCallChatEvent {}
+class InitChat extends InCallChatEvent { final String sessionId; InitChat(this.sessionId); }
+class OpenChat extends InCallChatEvent {}
+class CloseChat extends InCallChatEvent {}
+class _MessageReceived extends InCallChatEvent {}
+
+class InCallChatBloc extends Bloc<InCallChatEvent, InCallChatState> {
+  InCallChatBloc() : super(const InCallChatState()) {
+    on<InitChat>(_onInit);
+    on<OpenChat>(_onOpen);
+    on<CloseChat>(_onClose);
+    on<_MessageReceived>(_onReceived);
+  }
+
+  Future<void> _onInit(InitChat event, Emitter<InCallChatState> emit) async {
+    final group = await ensureCallGroup(event.sessionId);
+    emit(state.copyWith(group: group));
+  }
+
+  void _onOpen(OpenChat event, Emitter<InCallChatState> emit) {
+    emit(state.copyWith(open: true, unread: 0));
+    CometChatCalls.setChatButtonUnreadCount(0);
+  }
+
+  void _onClose(OpenChat event, Emitter<InCallChatState> emit) {
+    emit(state.copyWith(open: false));
+  }
+
+  void _onReceived(_MessageReceived event, Emitter<InCallChatState> emit) {
+    if (state.open) return;
+    final next = state.unread + 1;
+    emit(state.copyWith(unread: next));
+    CometChatCalls.setChatButtonUnreadCount(next);
+  }
+}
+```
+
+---
+
+## Triggering open from SDK event
+
+In your `CometChatCallsEventsListener` impl:
+
+```dart
+@override
+void onChatButtonClicked() {
+  context.read<InCallChatBloc>().add(OpenChat());
+}
+```
+
+---
+
+## Sheet UI
+
+Same `showModalBottomSheet` shape as V5. Use `BlocSelector` to react to `state.open`:
+
+```dart
+BlocListener<InCallChatBloc, InCallChatState>(
+  listenWhen: (prev, curr) => !prev.open && curr.open,
+  listener: (context, state) {
+    if (state.group == null) return;
+    showModalBottomSheet(
+      context: context,
+      isScrollControlled: true,
+      barrierColor: Colors.transparent,
+      builder: (_) => InCallChatPanel(group: state.group!),
+    ).whenComplete(() {
+      context.read<InCallChatBloc>().add(CloseChat());
+    });
+  },
+  child: /* call surface */,
+)
+```
+
+---
+
+## Anti-patterns
+
+V5 sister rules apply, plus V6-specific:
+
+1. **`BlocBuilder` instead of `BlocListener` for opening the sheet.** BlocBuilder is for rebuilding UI; sheet-open is a one-shot side effect → BlocListener.
+2. **`listenWhen` omitted.** Sheet opens on every state change.
+
+---
+
+## Verification checklist
+
+- [ ] InCallChatBloc with `InitChat`, `OpenChat`, `CloseChat`, `_MessageReceived` events
+- [ ] BlocListener with `listenWhen` for the open transition
+- [ ] `showModalBottomSheet.whenComplete` dispatches `CloseChat`
+- [ ] Real-device smoke: same as V5
+
+---
+
+## Pointers
+
+- `cometchat-flutter-v5-calls/references/in-call-chat.md` — V5 sister (sheet pattern)
+- `cometchat-flutter-v6-calls` SKILL.md
+- `cometchat-flutter-v6-calls/references/raise-hand.md` — Bloc bridge sibling
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/in-call-chat

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

@@ -0,0 +1,268 @@
+# Raise hand on Flutter (UIKit V6, Bloc-based)
+
+Same SDK conceptual API as V5; the difference is state management — V6 uses `flutter_bloc` rather than GetX. The reactive shape is `RaiseHandBloc → emit(state)` where state is an immutable record of `localRaised + raisedParticipants`.
+
+**Canonical docs:** https://www.cometchat.com/docs/calls/flutter/raise-hand
+**Read first:** `cometchat-flutter-v5-calls/references/raise-hand.md` — UX shape is identical; this is the V6 Bloc translation.
+
+---
+
+## SDK API (same as V5)
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
+
+CometChatCalls.raiseHand();
+CometChatCalls.lowerHand();
+
+// In a CometChatCallsEventsListener implementation:
+@override
+void onParticipantHandRaised(Participant p) { /* ... */ }
+@override
+void onParticipantHandLowered(Participant p) { /* ... */ }
+
+final settings = CallSettingsBuilder()..hideRaiseHandButton = true;
+```
+
+---
+
+## Bloc setup
+
+```dart
+import 'package:bloc/bloc.dart';
+import 'package:equatable/equatable.dart';
+import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart';
+
+// State
+class RaiseHandState extends Equatable {
+  final bool localRaised;
+  final List<RaisedParticipant> raised;
+  const RaiseHandState({this.localRaised = false, this.raised = const []});
+
+  RaiseHandState copyWith({bool? localRaised, List<RaisedParticipant>? raised}) =>
+    RaiseHandState(
+      localRaised: localRaised ?? this.localRaised,
+      raised: raised ?? this.raised,
+    );
+
+  @override
+  List<Object> get props => [localRaised, raised];
+}
+
+class RaisedParticipant extends Equatable {
+  final String uid;
+  final String name;
+  final DateTime raisedAt;
+  const RaisedParticipant({required this.uid, required this.name, required this.raisedAt});
+  @override
+  List<Object> get props => [uid, name, raisedAt];
+}
+
+// Events
+abstract class RaiseHandEvent {}
+class ToggleHand extends RaiseHandEvent {}
+class _ParticipantRaised extends RaiseHandEvent {
+  final Participant participant;
+  _ParticipantRaised(this.participant);
+}
+class _ParticipantLowered extends RaiseHandEvent {
+  final Participant participant;
+  _ParticipantLowered(this.participant);
+}
+```
+
+---
+
+## Bloc implementation
+
+```dart
+class RaiseHandBloc extends Bloc<RaiseHandEvent, RaiseHandState>
+    implements CometChatCallsEventsListener {
+
+  RaiseHandBloc() : super(const RaiseHandState()) {
+    on<ToggleHand>(_onToggle);
+    on<_ParticipantRaised>(_onParticipantRaised);
+    on<_ParticipantLowered>(_onParticipantLowered);
+
+    // Self-register as the call event listener
+    CometChatCalls.addCallEventListener('raise-hand-bloc', this);
+  }
+
+  void _onToggle(ToggleHand event, Emitter<RaiseHandState> emit) {
+    if (state.localRaised) {
+      CometChatCalls.lowerHand();
+    } else {
+      CometChatCalls.raiseHand();
+    }
+    emit(state.copyWith(localRaised: !state.localRaised));
+  }
+
+  void _onParticipantRaised(_ParticipantRaised event, Emitter<RaiseHandState> emit) {
+    final entry = RaisedParticipant(
+      uid: event.participant.uid,
+      name: event.participant.name,
+      raisedAt: DateTime.now(),
+    );
+    final next = [...state.raised.where((r) => r.uid != entry.uid), entry];
+    next.sort((a, b) => a.raisedAt.compareTo(b.raisedAt));
+    emit(state.copyWith(raised: next));
+  }
+
+  void _onParticipantLowered(_ParticipantLowered event, Emitter<RaiseHandState> emit) {
+    final next = state.raised.where((r) => r.uid != event.participant.uid).toList();
+    emit(state.copyWith(raised: next));
+  }
+
+  // CometChatCallsEventsListener — bridge to Bloc events
+  @override
+  void onParticipantHandRaised(Participant p) {
+    add(_ParticipantRaised(p));
+  }
+
+  @override
+  void onParticipantHandLowered(Participant p) {
+    add(_ParticipantLowered(p));
+  }
+
+  // ... implement other CometChatCallsEventsListener methods (no-ops or pass-through)
+
+  @override
+  Future<void> close() {
+    CometChatCalls.removeCallEventListener('raise-hand-bloc');
+    return super.close();
+  }
+}
+```
+
+The bridge pattern: the bloc IS the SDK listener. SDK callbacks call `add()` on the bloc, which dispatches an event handler that emits new state. This keeps Bloc's "single source of truth" intact — no parallel state outside the bloc.
+
+---
+
+## Toggle button widget
+
+```dart
+class RaiseHandButton extends StatelessWidget {
+  const RaiseHandButton({super.key});
+
+  @override
+  Widget build(BuildContext context) {
+    return BlocBuilder<RaiseHandBloc, RaiseHandState>(
+      buildWhen: (prev, curr) => prev.localRaised != curr.localRaised,
+      builder: (context, state) => Semantics(
+        button: true,
+        selected: state.localRaised,
+        label: state.localRaised ? 'Lower hand' : 'Raise hand',
+        child: GestureDetector(
+          onTap: () {
+            context.read<RaiseHandBloc>().add(ToggleHand());
+            SemanticsService.announce(
+              state.localRaised ? 'Hand lowered' : 'Hand raised',
+              TextDirection.ltr,
+            );
+          },
+          child: Container(
+            padding: const EdgeInsets.all(12),
+            decoration: BoxDecoration(
+              color: state.localRaised ? const Color(0xFFFFD60A) : Colors.white24,
+              borderRadius: BorderRadius.circular(32),
+            ),
+            child: Row(
+              children: [
+                const Text('✋'),
+                const SizedBox(width: 4),
+                Text(state.localRaised ? 'Lower' : 'Raise'),
+              ],
+            ),
+          ),
+        ),
+      ),
+    );
+  }
+}
+```
+
+`buildWhen` ensures the button only rebuilds when `localRaised` changes — not on every roster update. Performance discipline matters in a video call.
+
+---
+
+## Raised-hands sheet
+
+Same `DraggableScrollableSheet` shape as V5; bind via `BlocBuilder` instead of `Obx`:
+
+```dart
+BlocBuilder<RaiseHandBloc, RaiseHandState>(
+  buildWhen: (prev, curr) => prev.raised != curr.raised,
+  builder: (context, state) => ListView(
+    children: [
+      Text('Raised hands (${state.raised.length})'),
+      for (final p in state.raised)
+        ListTile(leading: const Text('✋'), title: Text(p.name)),
+    ],
+  ),
+)
+```
+
+`buildWhen` again — only rebuild when the roster changes, not on toggle.
+
+---
+
+## Wiring to the call screen
+
+```dart
+class CallScreen extends StatelessWidget {
+  @override
+  Widget build(BuildContext context) {
+    return BlocProvider(
+      create: (_) => RaiseHandBloc(),
+      child: Scaffold(
+        body: Stack(
+          children: [
+            // ... call surface (CometChatOngoingCall)
+            const Positioned(bottom: 100, right: 20, child: RaiseHandButton()),
+            const RaisedHandsSheet(),
+          ],
+        ),
+      ),
+    );
+  }
+}
+```
+
+`BlocProvider(create:)` scopes the bloc to the screen — disposed automatically on screen pop.
+
+---
+
+## Anti-patterns
+
+Web sister reference rules apply, plus V6-specific:
+
+1. **`buildWhen` omitted.** Every state change rebuilds every BlocBuilder — lots of unnecessary work during a call. Add `buildWhen` for narrow rebuilds.
+2. **Mutating `state.raised` directly** instead of creating a new list. `Equatable` props compare via `==`; mutation doesn't trigger rebuild.
+3. **Calling `CometChatCalls.raiseHand()` outside the bloc.** Bypasses the state machine; UI doesn't update. Always go through `add(ToggleHand())`.
+4. **Adding the SDK listener in `initState`** instead of the bloc constructor. Component-level lifecycle ≠ Bloc lifecycle. Bloc `close()` is the canonical place to clean up.
+
+---
+
+## Verification checklist
+
+- [ ] `RaiseHandBloc` extends `Bloc<RaiseHandEvent, RaiseHandState>`
+- [ ] `RaiseHandState` extends `Equatable` with proper `props`
+- [ ] Bloc registers itself as `CometChatCallsEventsListener` in constructor
+- [ ] Bloc `close()` removes the listener
+- [ ] `BlocProvider(create:)` scopes the bloc to the call screen
+- [ ] `buildWhen` on every BlocBuilder narrows rebuilds
+- [ ] `Semantics` + `SemanticsService.announce` for a11y
+- [ ] `hideRaiseHandButton: true` in CallSettings if custom UI
+- [ ] Real-device smoke: 3 devices (iOS + Android), 2 raise hands, host sees both
+- [ ] Hot-reload smoke: trigger raise → save code → bloc state survives (bloc is created via `create:`, persists across hot reload)
+
+---
+
+## Pointers
+
+- `cometchat-react-calls/references/raise-hand.md` — sister reference (UX shape)
+- `cometchat-flutter-v5-calls/references/raise-hand.md` — V5 sibling (GetX-based)
+- `cometchat-flutter-v6-calls` SKILL.md — V6 hard rules + Bloc patterns
+- `cometchat-a11y` — Flutter Semantics + SemanticsService
+- Canonical docs: https://www.cometchat.com/docs/calls/flutter/raise-hand