@cometchat/skills 4.4.2 → 5.0.0

package/skills/cometchat-flutter-v6-troubleshooting/SKILL.md

@@ -1,891 +1,67 @@
 ---
 name: cometchat-flutter-v6-troubleshooting
-description: >
-  Diagnose and fix CometChat Flutter UIKit v6 integration problems. Covers init
-  failures, login errors, UI rendering issues, keyboard problems, call failures,
-  listener leaks, theme jank, and platform-specific build errors. Use when seeing
-  errors, crashes, or unexpected behavior with CometChat components.
+description: "Diagnose a broken CometChat Flutter integration — blank screens, unbounded-height crashes, lists that don't fill, login and Region failures, calls that never ring, push that never arrives, and v5 leftovers. Symptom → cause → fix. Triggers: 'cometchat not working flutter', 'blank chat screen', 'RenderFlex unbounded height', 'login failed cometchat', 'calls not ringing', 'push not arriving'."
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.1"
+compatibility: "Flutter >=3.38.9; cometchat_chat_uikit ^6 (6.1.x, verified 6.1.0); cometchat_sdk ^5.0.6"
 metadata:
   author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter troubleshooting errors debugging crashes fixes"
+  version: "1.0.0"
+  tags: "cometchat flutter troubleshooting diagnostics errors symptoms v6"
 ---
 
-> **Ground truth:** `cometchat_chat_uikit: ^6.0` — pub-cache source + `ui-kit/flutter`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/overview · **Docs MCP:** `claude mcp add --transport http cometchat-docs https://www.cometchat.com/docs/mcp` (or fetch the URL directly without MCP). Verify symbols against the installed package/source before relying on them.
+> **Ground truth:** every cause below was confirmed against the published 6.1.0 (compiler or documented behaviour). The live page is `/ui-kit/flutter/troubleshooting` via `../cometchat-flutter-v6-core/references/docs-map.md`. The deeper per-topic tables live in core's `references/troubleshooting.md` and `references/anti-patterns.md` — this skill is the entry point that ROUTES to the right one.
 
-# CometChat Flutter UIKit v6 — Troubleshooting Guide
+## Companion skills (read first)
+- `cometchat-flutter-v6-core` — install, credentials, `init→login→render`, plus the reference tables this skill routes into. This skill ASSUMES it.
 
-Comprehensive guide for diagnosing and fixing CometChat Flutter UIKit v6 integration problems.
+## Use this skill when
+Something is already built and is not working: a blank screen, a crash, an empty list, no ring, no notification.
 
----
-
-## 1. Quick Diagnosis Flow
-
-Use this decision tree to jump to the right section:
-
-```
-What's happening?
-│
-├─ App crashes or errors on startup
-│  └─ Go to → Section 2: Init & Login Errors
-│
-├─ UI looks wrong, layout broken, keyboard issues
-│  └─ Go to → Section 3: UI Rendering Issues
-│
-├─ Calls not working, call screen blank or stuck
-│  ├─ Outgoing screen NEVER renders (peer rings, caller shows nothing) → Section 4.7 (V6 navigatorKey trap)
-│  ├─ Stuck on "Calling…" after peer accepts → Section 4.8 (upgrade to 6.0.1)
-│  └─ Otherwise → Section 4: Call Issues
-│
-├─ Events not firing, duplicate events, memory leaks
-│  └─ Go to → Section 5: Listener Issues
-│
-├─ Build fails on Android or iOS
-│  └─ Go to → Section 6: Build Errors
-│
-├─ App is slow, janky scrolling, laggy keyboard
-│  └─ Go to → Section 7: Performance Issues
-│
-└─ Platform-specific weirdness (Android/iOS/Web)
-   └─ Go to → Section 8: Platform-Specific Issues
-```
-
----
-
-## 2. Init & Login Errors
-
-### 2.1 "Authentication null"
-
-- **Symptom**: Error message `Authentication null` or `Please log in to CometChat before calling this method` when using any CometChat component or SDK call.
-- **Cause**: `CometChatUIKit.init()` was not called, or was called but not awaited before using components or calling login.
-- **Fix**: Ensure `init()` completes before any other CometChat usage:
-
-```dart
-// ✅ CORRECT — await init before anything else
-final settings = (UIKitSettingsBuilder()
-      ..appId = 'APP_ID'
-      ..region = 'us'
-      ..authKey = 'AUTH_KEY'
-      ..subscriptionType = CometChatSubscriptionType.allUsers)
-    .build();
-
-await CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) => debugPrint('Init done'),
-  onError: (e) => debugPrint('Init failed: ${e.message}'),
-);
-
-// ❌ WRONG — login before init completes (race condition)
-CometChatUIKit.init(uiKitSettings: settings);
-CometChatUIKit.login('uid');
-```
-
-### 2.2 "APP ID null"
-
-- **Symptom**: Error `APP ID null` or `appId is required` during init.
-- **Cause**: `appId` not set in `UIKitSettingsBuilder`.
-- **Fix**: Set `appId` before calling `.build()`:
-
-```dart
-final settings = (UIKitSettingsBuilder()
-      ..appId = 'YOUR_APP_ID'  // ← Must be set
-      ..region = 'us'
-      ..authKey = 'YOUR_AUTH_KEY')
-    .build();
-```
-
-### 2.3 ERR_ALREADY_LOGGED_IN
-
-- **Symptom**: Error `ERR_ALREADY_LOGGED_IN` when calling `CometChatUIKit.login()`.
-- **Cause**: Calling login when a session already exists. After `init()`, the SDK restores cached sessions automatically.
-- **Fix**: Check `CometChatUIKit.loggedInUser` after init before calling login:
-
-```dart
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    if (CometChatUIKit.loggedInUser != null) {
-      // Already logged in — skip login, go to home
-      navigateToHome();
-    } else {
-      // No session — show login screen
-      navigateToLogin();
-    }
-  },
-);
-```
-
-### 2.4 "Android internal error" on login
-
-- **Symptom**: Login fails with a vague `Android internal error` message.
-- **Cause**: Multiple possible causes — incorrect auth key, UID doesn't exist in CometChat dashboard, beta SDK bug, or network issue.
-- **Fix**:
-  1. Verify credentials are correct in the CometChat dashboard
-  2. Verify the UID exists in the dashboard
-  3. Try calling `CometChat.login(uid, authKey)` directly to isolate UIKit vs SDK issue
-  4. If using beta SDK, try the stable release
-  5. Check network connectivity and firewall rules
-
-### 2.5 Guard screen stuck on spinner
-
-- **Symptom**: App shows a loading spinner forever after init. The auth guard never resolves.
-- **Cause**: Using the callback-based `CometChat.getLoggedInUser()` after init instead of the synchronous `CometChatUIKit.loggedInUser`. The callback API silently fails when no session exists — neither `onSuccess` nor `onError` fires.
-- **Fix**: Use the synchronous check after init:
-
-```dart
-// ✅ CORRECT — synchronous check, always resolves
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    final hasUser = CometChatUIKit.loggedInUser != null;
-    setState(() {
-      _loggedIn = hasUser;
-      _initializing = false;
-    });
-  },
-);
-
-// ❌ WRONG — callback may never fire when no session exists
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) {
-    CometChat.getLoggedInUser(
-      onSuccess: (user) { /* may never fire */ },
-      onError: (e) { /* may never fire */ },
-    );
-  },
-);
-
-// ❌ ALSO WRONG — redundant native bridge round-trip
-CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) async {
-    final user = await CometChatUIKit.getLoggedInUser(); // Unnecessary!
-  },
-);
-```
-
-### 2.6 Region error (ERR_INVALID_REGION)
-
-- **Symptom**: Init fails with `ERR_INVALID_REGION`.
-- **Cause**: Region string is uppercase or not one of the valid values.
-- **Fix**: Use lowercase region string — valid values are `'us'`, `'eu'`, `'in'`:
-
-```dart
-// ✅ CORRECT
-..region = 'us'
-
-// ❌ WRONG
-..region = 'US'
-..region = 'United States'
-```
-
-### 2.7 StateError from uninitialized ServiceLocator
-
-- **Symptom**: `StateError: not initialized` when creating a BLoC manually.
-- **Cause**: Component's `ServiceLocator.instance.setup()` was not called before creating the BLoC. UIKit widgets do this automatically, but manual BLoC creation requires it.
-- **Fix**: Call setup before creating the BLoC:
-
-```dart
-// ✅ CORRECT
-ConversationsServiceLocator.instance.setup();
-final bloc = ConversationsBloc(
-  getLoggedInUserUseCase: ConversationsServiceLocator.instance.getLoggedInUserUseCase,
-);
-
-// ❌ WRONG — setup not called
-final bloc = ConversationsBloc(
-  getLoggedInUserUseCase: ConversationsServiceLocator.instance.getLoggedInUserUseCase,
-);
-```
-
----
-
-## 3. UI Rendering Issues
-
-### 3.1 Double keyboard compensation (layout jumps) — PRE-6.0.1 symptom
-
-- **Symptom**: When the keyboard opens, the message list jumps or there's extra white space. Content shifts twice — once from Flutter's Scaffold resize, once from the composer's internal keyboard handling.
-- **Cause**: A **pre-6.0.1** kit. Before kit fix **ENG-34434**, the composer did not clamp its keyboard spacing to Flutter's `viewInsets`, so a Scaffold with `resizeToAvoidBottomInset: true` (the default) double-compensated. On `^6.0.1` the composer clamps to `viewInsets`, so `true` is correct and does NOT double-compensate.
-- **Fix**: **Upgrade `cometchat_chat_uikit` to `^6.0.1`** and keep `resizeToAvoidBottomInset: true` (or omit it — `true` is the default). Setting `false` is only a stopgap on old kits you can't upgrade.
-
-```dart
-// ✅ CORRECT on ^6.0.1 — true (or omit; true is the default). Composer clamps
-//   to viewInsets (ENG-34434), so no double-compensation.
-Scaffold(
-  resizeToAvoidBottomInset: true,
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: user)),
-      CometChatMessageComposer(user: user),
-    ],
-  ),
-)
-
-// ⚠ PRE-6.0.1 STOPGAP ONLY — false suppresses the double gap on kits that
-//   predate the ENG-34434 clamp. Prefer upgrading the kit.
-Scaffold(
-  resizeToAvoidBottomInset: false,
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: user)),
-      CometChatMessageComposer(user: user),
-    ],
-  ),
-)
-```
-
-This applies everywhere the composer is used: messages screen, thread screen, or any custom screen.
-
-### 3.2 Stale user/group data
-
-- **Symptom**: User name, avatar, or group info doesn't update in real-time. Old data persists even after changes.
-- **Cause**: Passing `widget.user` or `widget.group` directly to UIKit components instead of maintaining mutable state that updates from listeners.
-- **Fix**: Keep mutable `_user`/`_group` in your State class and update from SDK listeners:
-
-```dart
-class _MessagesScreenState extends State<MessagesScreen> {
-  late User? _user;
-  late Group? _group;
-
-  @override
-  void initState() {
-    super.initState();
-    _user = widget.user;
-    _group = widget.group;
-    // Register listeners to update _user/_group on changes
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      resizeToAvoidBottomInset: true, // ^6.0.1: composer clamps to viewInsets (ENG-34434)
-      body: Column(
-        children: [
-          Expanded(child: CometChatMessageList(user: _user, group: _group)),
-          CometChatMessageComposer(user: _user, group: _group),
-        ],
-      ),
-    );
-  }
-}
-```
-
-### 3.3 No typing indicators / presence events
-
-- **Symptom**: Online/offline status never updates. Typing indicators don't appear. No presence events fire. No error is thrown.
-- **Cause**: `subscriptionType` was not set in `UIKitSettingsBuilder`. Omitting it silently disables all presence events.
-- **Fix**: Always set `subscriptionType`:
-
-```dart
-// ✅ CORRECT
-UIKitSettingsBuilder()
-  ..appId = 'APP_ID'
-  ..region = 'us'
-  ..authKey = 'AUTH_KEY'
-  ..subscriptionType = CometChatSubscriptionType.allUsers
-
-// ❌ WRONG — no error, but presence events never fire
-UIKitSettingsBuilder()
-  ..appId = 'APP_ID'
-  ..region = 'us'
-  ..authKey = 'AUTH_KEY'
-  // subscriptionType missing!
-```
-
-### 3.4 Messages not updating in real-time
-
-- **Symptom**: New messages don't appear until the screen is refreshed or re-opened.
-- **Cause**: Multiple possible causes:
-  1. SDK message listener not registered (BLoC handles this automatically — check component is mounted)
-  2. `subscriptionType` not set (see 3.3)
-  3. Component was disposed and listener removed
-- **Fix**:
-  1. Ensure `subscriptionType` is set in UIKitSettings
-  2. Verify the `CometChatMessageList` widget is mounted and not disposed
-  3. If using custom BLoC, ensure it registers `CometChat.addMessageListener()` in its constructor and removes it in `close()`
-
-### 3.5 Theme jank during keyboard animation
-
-- **Symptom**: Visible jank (stuttering, dropped frames) when the keyboard opens or closes, especially on message screens.
-- **Cause**: Theme values (`CometChatThemeHelper.getColorPalette(context)`, etc.) are being looked up inside `build()`. During keyboard animation, `MediaQuery` changes trigger rebuilds, and each lookup does expensive InheritedWidget traversal (44–95ms instead of <16ms).
-- **Fix**: Cache theme values in `didChangeDependencies()` with a `_themeInitialized` flag:
-
-```dart
-// ✅ CORRECT — cache once, reuse on every build
-class _MyWidgetState extends State<MyWidget> {
-  late CometChatColorPalette _colorPalette;
-  late CometChatSpacing _spacing;
-  late CometChatTypography _typography;
-  bool _themeInitialized = false;
-
-  @override
-  void didChangeDependencies() {
-    super.didChangeDependencies();
-    if (!_themeInitialized) {
-      _colorPalette = CometChatThemeHelper.getColorPalette(context);
-      _spacing = CometChatThemeHelper.getSpacing(context);
-      _typography = CometChatThemeHelper.getTypography(context);
-      _themeInitialized = true;
-    }
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    // Use _colorPalette, _spacing, _typography — no lookups here
-    return Container(color: _colorPalette.primary);
-  }
-}
-
-// ❌ WRONG — lookup in build causes jank during keyboard animation
-@override
-Widget build(BuildContext context) {
-  final colors = CometChatThemeHelper.getColorPalette(context); // Expensive!
-  return Container(color: colors.primary);
-}
-```
-
-### 3.6 Extra white space between composer and keyboard
-
-- **Symptom**: Visible gap between the message composer and the keyboard when it opens.
-- **Cause**: Safe area bottom padding being applied when the keyboard is open. The keyboard already covers the safe area, so adding safe area padding on top creates extra space.
-- **Fix**: Cache `MediaQuery.paddingOf(context).bottom` once in `didChangeDependencies()`. Never wrap the composer in an extra `SafeArea` widget — `CometChatMessageComposer` already handles bottom inset internally via `SliverSpacing`:
-
-```dart
-// ✅ CORRECT — cache safe area once, no extra SafeArea wrapper
-class _MessagesScreenState extends State<MessagesScreen> {
-  double _bottomSafeArea = 0;
-
-  @override
-  void didChangeDependencies() {
-    super.didChangeDependencies();
-    _bottomSafeArea = MediaQuery.paddingOf(context).bottom;
-  }
-
-  @override
-  Widget build(BuildContext context) {
-    return Scaffold(
-      resizeToAvoidBottomInset: true, // ^6.0.1: composer clamps to viewInsets (ENG-34434)
-      body: Column(
-        children: [
-          Expanded(child: CometChatMessageList(user: widget.user)),
-          CometChatMessageComposer(user: widget.user), // No SafeArea wrapper!
-        ],
-      ),
-    );
-  }
-}
-
-// ❌ WRONG — SafeArea wrapper adds bottom padding the composer already handles
-Scaffold(
-  resizeToAvoidBottomInset: true,
-  body: Column(
-    children: [
-      Expanded(child: CometChatMessageList(user: widget.user)),
-      SafeArea(  // ← Causes extra white gap when keyboard opens
-        child: CometChatMessageComposer(user: widget.user),
-      ),
-    ],
-  ),
-)
-```
-
----
-
-## 4. Call Issues
-
-### 4.1 "auth token null" on call init
-
-- **Symptom**: Calls SDK fails with `auth token null` or similar authentication error when trying to start a call.
-- **Cause**: The Calls SDK was initialized before the Chat SDK completed init and login. The Calls SDK needs the auth token from a successful chat login (rule **CALLS_INIT_AFTER_CHAT_INIT** — see `cometchat-flutter-v6-calls` §1.0).
-- **Fix**: When `..enableCalls = true` is set on `UIKitSettingsBuilder`, `CallEventService` handles both `CometChatUIKitCalls.init()` and `CometChatUIKitCalls.loginWithAuthToken()` internally — chat init must complete first. For manual integrations, gate calls init on chat init success:
-
-```dart
-// ✅ CORRECT — chat init first, calls init in onSuccess
-await CometChatUIKit.init(
-  uiKitSettings: settings,
-  onSuccess: (_) async {
-    // For manual calls integration (no ..enableCalls = true):
-    // CometChatUIKitCalls.init takes raw appId + region STRINGS (not a settings
-    // builder) and reports via callbacks — verified vs cometchat_uikit_calls.dart:9.
-    CometChatUIKitCalls.init(
-      'APP_ID',
-      'us',
-      onSuccess: (_) {},
-      onError: (e) => debugPrint('Calls init failed: $e'),
-    );
-  },
-  onError: (e) => debugPrint('Chat init failed: ${e.message}'),
-);
-
-// ❌ WRONG — calls init runs before chat init completes
-CometChatUIKit.init(uiKitSettings: settings);          // not awaited
-await CometChatUIKitCalls.init(callAppSettings);       // auth token null
-```
-
-### 4.2 "session already started"
-
-- **Symptom**: Error `session already started` when trying to join or start a call.
-- **Cause**: Two distinct causes — diagnose both:
-  1. **Duplicate `CometChatUIKitCalls.init()` within one app lifecycle.** The Calls SDK is single-init (rule **CALL_INIT_ONCE** — see `cometchat-flutter-v6-calls`). Calling init more than once (e.g., from multiple bootstrap paths, hot-restart with stale state) emits this error.
-  2. **Stale call session from a prior call** that was not ended cleanly — user navigated away without hanging up, or the app was killed mid-call.
-- **Fix**:
-
-```dart
-// ✅ CAUSE (a) — single-init guard at app boot
-bool _callsInitDone = false;
-Future<void> initCallsOnce(CallAppSettings settings) async {
-  if (_callsInitDone) return;
-  await CometChatUIKitCalls.init(settings);
-  _callsInitDone = true;
-}
-
-// ✅ CAUSE (b) — clean up the stale session via the UIKit-namespaced API.
-// The method is endSession (NOT endCall) and takes named callbacks, no sessionId
-// — verified vs cometchat_uikit_calls.dart:236.
-await CometChatUIKitCalls.endSession(
-  onSuccess: (_) {},
-  onError: (e) => debugPrint('endSession failed: $e'),
-);
-
-// ❌ WRONG — bare CometChat.endCall is the Chat SDK API, not the calls cleanup
-CometChat.endCall(sessionId, onSuccess: ..., onError: ...);
-```
-
-### 4.3 "CallManager not found" / "Calling module not found"
-
-- **Symptom**: Android native error `CallManager not found` or `CometChat Calling module not found`.
-- **Cause**: The CometChat Calling native module is not properly linked on Android. This can happen with ProGuard stripping, missing dependencies, or build configuration issues.
-- **Fix**:
-  1. Ensure ProGuard keep rules are in place (see Section 6.1)
-  2. Verify `cometchat_chat_uikit` is properly added to `pubspec.yaml`
-  3. Run `flutter clean` and rebuild
-  4. Check that `android.enableJetifier=true` is in `gradle.properties`
-
-### 4.4 "startSession null" on Android
-
-- **Symptom**: `startSession` returns null on Android with no error feedback. The call screen may appear blank or stuck.
-- **Cause**: Known Android SDK issue where `startSession` silently fails. A 5-second timeout workaround exists but provides no error feedback.
-- **Fix**: This is a known SDK-level issue. Workarounds:
-  1. Implement a timeout wrapper around `startSession` calls
-  2. Show a retry option to the user if the call screen doesn't load within 5 seconds
-  3. Check for updates to `cometchat_calls_sdk` that may fix this
-
-### 4.5 Incoming call not received
-
-- **Symptom**: Incoming calls are not shown to the receiver. The caller sees the outgoing call screen but the receiver gets nothing.
-- **Cause**: Multiple possible causes:
-  1. `subscriptionType` not set (presence/events disabled)
-  2. Push notification / VoIP setup incomplete
-  3. Call listeners not registered
-  4. App is in background without proper background handling
-- **Fix**:
-  1. Ensure `subscriptionType` is set to `CometChatSubscriptionType.allUsers`
-  2. Verify FCM/APNs push notification setup for background calls
-  3. Check that call event listeners are registered
-  4. For cross-platform issues (Android↔iOS↔React), verify all platforms are on compatible SDK versions
-
-### 4.6 Calls SDK not re-initialized after logout
-
-- **Symptom**: After logout and re-login, calls don't work. Call screens may be blank or throw errors.
-- **Cause**: The Calls SDK maintains its own session state. After `CometChatUIKit.logout()`, the Calls SDK session is invalidated but may not be properly re-initialized on the next login.
-- **Fix**: Ensure the Calls SDK is re-initialized after login. The UIKit handles this internally — if you're managing calls manually, call the Calls SDK init after each successful login.
-
-### 4.7 Outgoing call screen never renders / app shows nothing after tapping call (V6 navigatorKey trap)
-
-- **Symptom**: Caller taps the call button. The peer rings (server received the call). The caller's Flutter app shows **nothing** — no outgoing-call screen, no error in `onSuccess`/`onError`. `CometChat.initiateCall` returns successfully with a valid `sessionId`, but no UI ever appears.
-- **Cause**: `MaterialApp` is missing `navigatorKey: CallNavigationContext.navigatorKey`. The kit's `CometChatCallButtons` and outgoing-call flow navigate via `CallNavigationContext.navigatorKey.currentContext` — which is `null` until the app's `MaterialApp` is wired to that key. The failure is silent because `initiateCall` itself succeeds; only the *navigation* to the outgoing-call screen fails. **Important**: the vendor's own 6.0.1 sample app is missing this line, so customers who copied `main.dart` verbatim will hit this bug. This is the single most common customer-blocking V6 calls trap.
-- **Fix**: Wire `CallNavigationContext.navigatorKey` on the root `MaterialApp`:
-
-```dart
-// ✅ CORRECT — navigatorKey wired on MaterialApp
-import 'package:flutter/material.dart';
-import 'package:cometchat_chat_uikit/cometchat_calls_uikit.dart'
-    show CallNavigationContext;  // calls is a sub-library of cometchat_chat_uikit — there is NO separate cometchat_calls_uikit package in v6
-
-class MyApp extends StatelessWidget {
-  @override
-  Widget build(BuildContext context) {
-    return MaterialApp(
-      navigatorKey: CallNavigationContext.navigatorKey, // REQUIRED for V6 calls
-      home: const HomeScreen(),
-    );
-  }
-}
-
-// ❌ WRONG — no navigatorKey; outgoing-call screen never appears
-return MaterialApp(
-  home: const HomeScreen(),
-);
-```
+## Prerequisites & install
+None — diagnosis only.
 
-See `cometchat-flutter-v6-calls` §1.7 for the canonical wiring rule.
-
-### 4.8 Stuck on "Calling…" after peer accepts (v6.0.0-beta2 BLoC bug — fixed in 6.0.1)
-
-- **Symptom**: Outgoing call screen displays correctly, peer accepts the call, but the caller's screen stays stuck on "Calling…" and never transitions to the in-call surface. Audio/video may already be flowing in the background; only the UI state is wrong.
-- **Cause**: A known BLoC transition bug in `cometchat_chat_uikit ^6.0.0-beta2` where the outgoing → in-call state never fires. **This is FIXED in 6.0.1 GA.**
-- **Fix**: Upgrade to `cometchat_chat_uikit ^6.0.1` (or the latest 6.x):
-
-```yaml
-# pubspec.yaml
-dependencies:
-  cometchat_chat_uikit: ^6.0.1  # was ^6.0.0-beta2
-```
-
-Then run:
-
-```bash
-flutter pub get
-flutter clean
-flutter run
-```
-
-If the bug persists after upgrade, verify Section 4.7 (`navigatorKey` is still required on 6.0.1).
-
----
-
-## 5. Listener Issues
-
-### 5.1 Duplicate events (hardcoded listener IDs)
-
-- **Symptom**: Event handlers fire multiple times for a single event. Messages appear twice, typing indicators flicker.
-- **Cause**: Listener registered with a hardcoded ID. When the widget is recreated (e.g., navigation), the new listener overwrites the old one but the old widget's handler may still be referenced, or multiple instances collide.
-- **Fix**: Use a unique listener ID per widget instance:
-
-```dart
-// ✅ CORRECT — unique ID per instance
-class _MyScreenState extends State<MyScreen> with MessageListener {
-  late final String _listenerId;
-
-  @override
-  void initState() {
-    super.initState();
-    _listenerId = 'my_screen_${DateTime.now().millisecondsSinceEpoch}';
-    CometChat.addMessageListener(_listenerId, this);
-  }
-
-  @override
-  void dispose() {
-    CometChat.removeMessageListener(_listenerId);
-    super.dispose();
-  }
-}
-
-// ❌ WRONG — hardcoded ID causes collisions across instances
-CometChat.addMessageListener('messages', this); // Collision!
-```
-
-### 5.2 Listener leaks (missing dispose)
-
-- **Symptom**: Memory usage grows over time. Events fire on screens that are no longer visible. App becomes sluggish.
-- **Cause**: SDK listeners registered in `initState()` but not removed in `dispose()`.
-- **Fix**: Always remove listeners with the same ID used to register:
-
-```dart
-@override
-void dispose() {
-  CometChat.removeMessageListener(_listenerId);
-  CometChat.removeUserListener(_listenerId);
-  CometChat.removeGroupListener(_listenerId);
-  CometChat.removeCallListener(_listenerId);
-  super.dispose();
-}
-```
-
-### 5.3 No events firing (subscriptionType not set)
-
-- **Symptom**: All listeners are properly registered and removed, but no events ever fire. No errors in console.
-- **Cause**: `subscriptionType` not set in `UIKitSettingsBuilder`. This silently disables all real-time events.
-- **Fix**: Set `subscriptionType` during init:
-
-```dart
-UIKitSettingsBuilder()
-  ..subscriptionType = CometChatSubscriptionType.allUsers
-```
-
----
-
-## 6. Build Errors
-
-### 6.0 `pub get` can't resolve `cometchat_chat_uikit` ^6.x / resolves a beta
-
-- **Symptom**: `flutter pub get` fails to find `cometchat_chat_uikit ^6.0.x`, or pulls a `6.0.0-beta` instead of the GA.
-- **Cause**: Wrong package source. **The v6 GA is on pub.dev**; Cloudsmith hosts only the beta + legacy V5.
-- **Fix**: Use the default pub.dev source — `dependencies: cometchat_chat_uikit: ^6.0.2` (no `hosted:` block). Only add the Cloudsmith `hosted:` URL if you are intentionally on a beta/V5. (V6 calls fold into this one package — there is no separate `cometchat_calls_uikit` package on v6; calls types come from the `package:cometchat_chat_uikit/cometchat_calls_uikit.dart` sub-library.)
-
-### 6.05 Push token never registers / looking for `PNRegistry`
-
-- **Symptom**: Push notifications never arrive; code references a `PNRegistry` class that won't import.
-- **Cause**: `PNRegistry` is **not** a kit/SDK symbol — it's a copy-in **V5 sample-app extension** (`extension PNRegistry on CometChatService`), not exported by any `cometchat_*` package.
-- **Fix**: The real push API is `CometChatNotifications.registerPushToken(PushPlatforms.FCM_FLUTTER_ANDROID, fcmToken: token, providerId: ...)` (+ `FCM_FLUTTER_IOS` / `APNS_FLUTTER_DEVICE` / `APNS_FLUTTER_VOIP`) — call it AFTER login, and `unregisterPushToken(...)` on logout. See `cometchat-flutter-v6-push`.
-
-### 6.1 Android: ClassNotFoundException (missing ProGuard rules)
-
-- **Symptom**: Release build crashes with `ClassNotFoundException` for CometChat classes. Debug builds work fine.
-- **Cause**: R8/ProGuard strips CometChat SDK classes during release minification.
-- **Fix**: Create `android/app/proguard-rules.pro` with:
-
-```
-# CometChat — prevent R8 from stripping SDK classes
--keep class com.cometchat.** { *; }
--keep interface com.cometchat.** { *; }
-
-# Suppress warnings for Calls SDK classes referenced cross-module
--dontwarn com.cometchat.calls.CometChatRTCView$CometChatRTCViewBuilder
--dontwarn com.cometchat.calls.CometChatRTCView
--dontwarn com.cometchat.calls.CometChatRTCViewListener
--dontwarn com.cometchat.calls.model.AnalyticsSettings
--dontwarn com.cometchat.calls.model.RTCCallback
--dontwarn com.cometchat.calls.model.RTCReceiver
-```
-
-Reference it in `android/app/build.gradle`:
-
-```kotlin
-buildTypes {
-    release {
-        isMinifyEnabled = true
-        isShrinkResources = true
-        proguardFiles(
-            getDefaultProguardFile("proguard-android-optimize.txt"),
-            "proguard-rules.pro"
-        )
-    }
-}
-```
-
-### 6.2 Android: minSdk too low
-
-- **Symptom**: Build fails with error about minimum SDK version. Error mentions `minSdkVersion` incompatibility.
-- **Cause**: `minSdk` is set below 26. The `cometchat_calls_sdk` requires minSdk 26.
-- **Fix**: In `android/app/build.gradle` (or `.kts`):
-
-```kotlin
-defaultConfig {
-    minSdk = 26  // Required by cometchat_calls_sdk
-}
-```
-
-### 6.3 Android: Jetifier missing
-
-- **Symptom**: Build fails with errors about Android Support Library classes not found, or `androidx` conflicts.
-- **Cause**: `android.enableJetifier=true` not set. Transitive dependencies from the CometChat SDK use old Android Support Library references.
-- **Fix**: In `android/gradle.properties`:
-
-```properties
-android.useAndroidX=true
-android.enableJetifier=true
-```
-
-### 6.4 iOS: pod install failures
-
-- **Symptom**: `pod install` fails with dependency resolution errors, version conflicts, or missing pods.
-- **Cause**: Cocoapods cache is stale, or the Podfile needs updating.
-- **Fix**:
-
-```bash
-cd ios
-rm -rf Pods Podfile.lock
-pod repo update
-pod install --repo-update
-cd ..
-flutter clean
-flutter pub get
-```
-
-If still failing, check that the iOS deployment target in `ios/Podfile` is high enough:
-
-```ruby
-platform :ios, '13.0'  # Minimum for CometChat
-```
-
-### 6.5 iOS: missing permissions
-
-- **Symptom**: App crashes or shows blank screen when trying to access camera, microphone, or photo library on iOS.
-- **Cause**: Required permission descriptions missing from `Info.plist`.
-- **Fix**: Add to `ios/Runner/Info.plist`:
-
-```xml
-<key>NSCameraUsageDescription</key>
-<string>Camera access is needed for video calls and sending photos</string>
-<key>NSMicrophoneUsageDescription</key>
-<string>Microphone access is needed for voice and video calls</string>
-<key>NSPhotoLibraryUsageDescription</key>
-<string>Photo library access is needed for sending images</string>
-```
-
-For VoIP calls, also add:
-
-```xml
-<key>UIBackgroundModes</key>
-<array>
-    <string>voip</string>
-    <string>remote-notification</string>
-</array>
-```
-
-### 6.6 Android: KGP "legacy plugin application" warning (benign)
-
-- **Symptom**: `flutter build apk` / `flutter run` prints a warning that the CometChat plugins apply the Kotlin Gradle Plugin the legacy way (e.g. *"The Kotlin Gradle plugin was loaded multiple times…"* / legacy-plugin-application deprecation from both `cometchat_chat_uikit` and `cometchat_calls_sdk`).
-- **Cause**: kit-side — the plugins haven't migrated to the declarative `plugins {}` KGP application. It's emitted by the kit, not your project.
-- **Fix**: **None needed — this is a warning, not an error.** The build still succeeds (verified — real `flutter build apk --debug`). Don't try to "fix" it in your app; it clears when the kit updates its Gradle plugin wiring.
-
----
-
-## 7. Performance Issues
-
-### 7.1 Theme lookup in build() causing jank
-
-- **Symptom**: Dropped frames during scrolling or keyboard animation. Flutter DevTools shows long build times (44–95ms).
-- **Cause**: `CometChatThemeHelper.getColorPalette(context)` and similar calls in `build()` do expensive InheritedWidget traversal on every rebuild.
-- **Fix**: Cache theme values in `didChangeDependencies()` — see Section 3.5 for the full pattern. For child widgets, pass pre-cached theme values from the parent:
-
-```dart
-// Parent passes cached values to children
-CometChatImageBubble(
-  imageUrl: message.attachment?.fileUrl,
-  colorPalette: _colorPalette,  // Pre-cached from parent
-  spacing: _spacing,            // Pre-cached from parent
-);
-```
-
-### 7.2 Missing buildWhen optimization
-
-- **Symptom**: Entire widget tree rebuilds on every BLoC state change, even when only a small part of the state changed.
-- **Cause**: `BlocConsumer` or `BlocBuilder` without `buildWhen` — rebuilds on every state emission.
-- **Fix**: Add `buildWhen` to limit rebuilds to relevant state changes:
-
-```dart
-BlocConsumer<MessageComposerBloc, MessageComposerState>(
-  buildWhen: (previous, current) =>
-      previous.isEditMode != current.isEditMode ||
-      previous.isReplyMode != current.isReplyMode ||
-      previous.isRecordingMode != current.isRecordingMode ||
-      previous.editMessage != current.editMessage ||
-      previous.replyMessage != current.replyMessage,
-  listener: (context, state) { /* still receives ALL state changes */ },
-  builder: (context, state) { /* only rebuilds when buildWhen is true */ },
-)
-```
-
-### 7.3 O(n) lookups instead of O(1)
-
-- **Symptom**: Slow scrolling in long message lists. `findChildIndexCallback` takes too long.
-- **Cause**: Using `list.indexWhere()` (O(n)) to find messages instead of a Map-based O(1) lookup.
-- **Fix**: Maintain a `Map<int, int>` alongside the message list for O(1) index lookups:
-
-```dart
-// In BLoC — maintain O(1) lookup map
-final Map<int, int> _messageIndexMap = {};
-
-int? findMessageIndex(int messageId) => _messageIndexMap[messageId];
-
-// In SliverAnimatedList
-SliverAnimatedList(
-  findChildIndexCallback: (Key key) {
-    if (key is ValueKey<int>) {
-      final index = widget.findMessageIndex?.call(key.value) ??
-          _messages.indexWhere((m) => m.id == key.value);
-      if (index != -1) return visualPosition(index);
-    }
-    return null;
-  },
-)
-```
-
----
-
-## 8. Platform-Specific Issues
-
-### 8.1 Android-specific
+## Triage in order (cheapest first)
+1. **Does `flutter analyze` pass?** A stale v5 symbol or a wrong barrel import is a compile error, not a runtime mystery.
+2. **Did `init` AND `login` both reach `onSuccess`?** Log both. Most "blank chat" reports stop here.
+3. **Is the failing widget inside a bounded box?** The second-most-common cause, and it is always the host's container.
+4. **Is the thing you expect actually enabled** — Dashboard toggle (extensions, moderation), `uiKit.enableCalling`, a push provider?
+5. Only then look at the kit.
 
+## Symptom → cause → fix
 | Symptom | Cause | Fix |
-|---------|-------|-----|
-| Release crash `ClassNotFoundException` | Missing ProGuard rules | Add `-keep class com.cometchat.** { *; }` — see Section 6.1 |
-| Build fail `minSdk` | minSdk < 26 | Set `minSdk = 26` in `build.gradle` |
-| Build fail support library | Missing Jetifier | Add `android.enableJetifier=true` to `gradle.properties` |
-| `startSession` returns null | Known Calls SDK issue | Implement timeout + retry — see Section 4.4 |
-| `CallManager not found` | Native module not linked | Clean build + verify ProGuard + Jetifier — see Section 4.3 |
-| Audio recording stuck after permission | Permission callback race | Ensure permission is granted before starting recording; handle the permission result callback properly |
-
-### 8.2 iOS-specific
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Pod install fails | Stale cache or version conflict | `rm -rf Pods Podfile.lock && pod install --repo-update` |
-| Camera/mic crash | Missing `Info.plist` permissions | Add `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` — see Section 6.5 |
-| Media not sending | File access or permission issue | Verify `NSPhotoLibraryUsageDescription` in Info.plist; check file picker permissions |
-| App crash on iPhone 11 | Device-specific compatibility | Check iOS deployment target ≥ 13.0; verify no 32-bit dependencies |
-| VoIP calls not received in background | Missing background modes | Add `voip` and `remote-notification` to `UIBackgroundModes` in Info.plist |
-
-### 8.3 Web-specific
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Runtime error on web | Platform-specific code without `kIsWeb` guard | Wrap platform-specific code with `if (!kIsWeb)` checks |
-| Native plugins crash on web | Plugin not available on web | Use conditional imports or `kIsWeb` guards before calling native APIs |
-| CORS errors | API calls blocked by browser | Ensure CometChat API endpoints are accessible; check proxy configuration |
-
-```dart
-// ✅ CORRECT — guard platform-specific code
-import 'package:flutter/foundation.dart' show kIsWeb;
-
-if (!kIsWeb) {
-  // Native-only code (e.g., push notifications, file system access)
-  setupPushNotifications();
-}
-
-// For conditional imports:
-// lib/platform/native_service.dart — native implementation
-// lib/platform/web_service.dart — web implementation
-```
-
----
-
-## Quick Reference: Error → Fix Table
-
-| Error / Symptom | Section | One-Line Fix |
-|----------------|---------|-------------|
-| "Authentication null" | 2.1 | Call `CometChatUIKit.init()` before any usage |
-| "APP ID null" | 2.2 | Set `..appId = 'YOUR_APP_ID'` in UIKitSettingsBuilder |
-| ERR_ALREADY_LOGGED_IN | 2.3 | Check `CometChatUIKit.loggedInUser` before calling login |
-| "Android internal error" | 2.4 | Verify credentials, UID existence, try stable SDK |
-| Guard screen stuck on spinner | 2.5 | Use `CometChatUIKit.loggedInUser` synchronously after init |
-| ERR_INVALID_REGION | 2.6 | Use lowercase: `'us'`, `'eu'`, `'in'` |
-| StateError: not initialized | 2.7 | Call `ServiceLocator.instance.setup()` before creating BLoC |
-| Double keyboard compensation (pre-6.0.1) | 3.1 | Upgrade kit to `^6.0.1` (composer clamps to `viewInsets`, ENG-34434); keep `resizeToAvoidBottomInset: true`. `false` is only an old-kit stopgap |
-| No typing indicators / presence | 3.3 | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |
-| Theme jank during keyboard | 3.5 | Cache theme in `didChangeDependencies()`, not `build()` |
-| Outgoing call screen never appears | 4.7 | Wire `navigatorKey: CallNavigationContext.navigatorKey` on `MaterialApp` |
-| Stuck on "Calling…" after peer accepts | 4.8 | Upgrade `cometchat_chat_uikit` from `^6.0.0-beta2` to `^6.0.1` |
-| Duplicate events | 5.1 | Use unique listener ID per widget instance |
-| Listener leak | 5.2 | Remove listener in `dispose()` with same ID |
-| ClassNotFoundException (release) | 6.1 | Add ProGuard keep rules for `com.cometchat.**` |
-| minSdk too low | 6.2 | Set `minSdk = 26` |
-| Jetifier missing | 6.3 | Add `android.enableJetifier=true` |
-| Pod install failure | 6.4 | Delete Pods + Podfile.lock, `pod install --repo-update` |
-| Missing iOS permissions | 6.5 | Add camera/mic/photo descriptions to Info.plist |
-
----
-
-## Checklist — Every CometChat Integration
-
-Use this checklist to verify your integration is correct:
-
-- [ ] `CometChatUIKit.init()` called and awaited before any usage
-- [ ] Auth check uses `CometChatUIKit.loggedInUser` after init (not `CometChat.getLoggedInUser()`)
-- [ ] `subscriptionType` set in UIKitSettingsBuilder
-- [ ] `region` is lowercase (`'us'`, `'eu'`, `'in'`)
-- [ ] Scaffold hosting `CometChatMessageComposer` uses `resizeToAvoidBottomInset: true` (or omits it) on `^6.0.1` — composer clamps to `viewInsets` (ENG-34434); `false` is only the pre-6.0.1 stopgap
-- [ ] Theme cached in `didChangeDependencies()`, not `build()`
-- [ ] SDK listeners registered with unique ID, removed in `dispose()`
-- [ ] Colors from `CometChatThemeHelper`, never hardcoded
-- [ ] Strings from `Translations.of(context)`, never hardcoded
-- [ ] If using calls: `MaterialApp` wires `navigatorKey: CallNavigationContext.navigatorKey` (required for V6 calls, including 6.0.1)
-- [ ] If using calls on 6.0.0-beta2: upgrade to `cometchat_chat_uikit ^6.0.1` (fixes outgoing → in-call BLoC transition)
-- [ ] Android: minSdk ≥ 26, Jetifier enabled, ProGuard rules added
-- [ ] iOS: permissions in Info.plist, deployment target ≥ 13.0
-- [ ] Web: `kIsWeb` guards on platform-specific code
+|---|---|---|
+| Blank/white chat screen | A widget built before `login` resolved | Gate the first frame on init **and** login (`lifecycle.md`) |
+| `Unable to load asset: cometchat-settings.json` | Not at project root, or not registered | Add under `flutter: assets:`, re-run `flutter pub get` |
+| Crash on startup before any UI | `WidgetsFlutterBinding.ensureInitialized()` missing | Call it first in `main()` — `initFromSettings` reads an asset |
+| `RenderFlex … unbounded height` | A kit list in an unbounded parent | `Expanded`/`Flexible`, or a fixed height (`layout.md`) |
+| List renders as a zero-height sliver | Same — content-driven parent | Same |
+| Composer hidden by the keyboard | `resizeToAvoidBottomInset: false`, or nested `Scaffold`s | Leave the default `true`; one `Scaffold` per screen |
+| Header under the notch | No `SafeArea` | Wrap the body |
+| Two app bars | Your `Scaffold` `AppBar` + the widget's own | `hideAppbar: true` on the list widget |
+| Login fails instantly | Wrong **Region**, or the UID doesn't exist | Match the Dashboard region exactly; use a real UID (Dashboard → Users) |
+| Works in debug, fails in release | Obfuscation, or the settings asset not bundled | Test the release build; verify the asset ships |
+| `Undefined name 'CometChatIncomingCall'` (any call widget) | Only the chat barrel imported | Also import `…/cometchat_calls_uikit.dart` (`-calls`) |
+| Call buttons never appear | Calls not enabled on BOTH sides | `uiKit.enableCalling: true` **and** `cometchat_calls_sdk` installed |
+| Call surface opens black | Camera/mic permission missing, or a simulator | Add usage strings/permissions; test on a real device |
+| Incoming call never shows (calling on) | No `navigatorKey` on the root `MaterialApp` — kit logs *"Incoming call overlay cannot be shown"* | `navigatorKey: CallNavigationContext.navigatorKey` (`-calls`) |
+| Two incoming-call screens | Own `CallListener` + `CometChatIncomingCall` on top of the kit's `CallEventService` overlay | Remove yours — the kit presents it; customize via `CallingConfiguration` |
+| Thread replies never send | `parentMessageId` without `user:`/`group:` | Pass BOTH on the thread list *and* composer |
+| Enabled extension doesn't appear | Expecting v5 registration | v6 auto-surfaces it; confirm the Dashboard toggle, add NO code |
+| Push never arrives | No Dashboard provider, or registered before login | Configure the provider; register after login; re-register on refresh (`-push`) |
+| Previous user still gets notifications | Push token never unregistered on logout | Unregister before `logout()` |
+| Presence never updates | `subscribePresenceForAllUsers` false | Set it `true` in the settings file |
+| Messages only arrive on reopen | Socket not auto-connecting | `chatSDK.autoEstablishSocketConnection: true` |
+| Duplicate events after hot restart | Listener not removed in `dispose` | Pair every add with a remove (`-events`) |
+| `The named parameter 'x' isn't defined` on a kit widget | Following a doc page that drifted | Trust the compiler; several Flutter pages had wrong signatures — check `DOCS-BACKLOG.md` PART 4 |
+| Android build fails on minSdk | Below the floor (the docs' 24 is too low) | `minSdk = 26` — forced by `cometchat_calls_sdk`, a hard dependency of the kit |
+| iOS pod install fails | Deployment target too low | `platform :ios, '15.1'` (13.0 through calls-sdk 5.0.6), then `pod install` |
+| Everything broke after upgrading | Mixed majors / removed v5 APIs | → `cometchat-flutter-v6-migration`; never mix majors |
+
+## When the docs and the compiler disagree, the compiler wins
+Several `ui-kit/flutter` pages documented parameters that do not exist in 6.1.0 (thread header, search callbacks, style names). If a documented snippet will not compile, that is a **docs** bug: use the real signature, and flag the page (`RULES.md` §20) rather than working around it forever.
+
+## Still stuck — collect this before escalating
+Kit + SDK versions from `pubspec.lock` · the `flutter analyze` output · whether `init`/`login` reached `onSuccess` · the exact exception + stack · platform and whether it is a real device · the relevant Dashboard toggles. Most escalations are resolved by the first three.
+
+## Verify it works
+The specific symptom is gone, `flutter analyze` is clean, and the fix was to the HOST's wiring (gating, container, imports, config) — if the answer looked like "patch around the kit", re-check the table.