@cometchat/skills 4.4.1 → 5.0.0

package/skills/cometchat-flutter-v5-theming/SKILL.md

@@ -1,161 +0,0 @@
----
-name: cometchat-flutter-v5-theming
-description: "Use when customizing the visual appearance of CometChat Flutter UIKit v5 components. Triggers on CometChatThemeHelper, CometChatColorPalette, CometChatSpacing, CometChatTypography, Style classes, merge()."
-license: "MIT"
-compatibility: "cometchat_uikit_shared ^5.2.3; flutter >=2.5.0"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter v5 theme colors typography spacing dark-mode styling"
----
-
-> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
-
-# CometChat Flutter UIKit v5 — Theming & Styling
-
-How to customize the visual appearance of all CometChat v5 components.
-
-## Theme System Architecture
-
-Three layers, resolved via Flutter's `ThemeExtension` system:
-
-1. `CometChatColorPalette` — colors (primary, neutral, alert, background, text, icon, button, border)
-2. `CometChatSpacing` — spacing, padding, margin, and radius tokens
-3. `CometChatTypography` — text styles (heading1-4, body, caption1-2, button, link, title)
-
-Access via static helpers:
-```dart
-final colors = CometChatThemeHelper.getColorPalette(context);
-final spacing = CometChatThemeHelper.getSpacing(context);
-final typography = CometChatThemeHelper.getTypography(context);
-```
-
-**Important:** `getColorPalette()` creates a new object every call, resolving each token via `Theme.of(context)`. Cache in `didChangeDependencies()`, never call in `build()`.
-
-## Applying a Custom Theme
-
-Register `CometChatColorPalette` as a `ThemeExtension` on your `ThemeData`:
-
-```dart
-// ✅ CORRECT
-MaterialApp(
-  theme: ThemeData(
-    extensions: [
-      CometChatColorPalette(
-        primary: const Color(0xFF6852D6),
-        textPrimary: const Color(0xFF141414),
-        textSecondary: const Color(0xFF727272),
-      ),
-    ],
-  ),
-  darkTheme: ThemeData(
-    extensions: [
-      CometChatColorPalette(
-        primary: const Color(0xFF604CC3),
-        textPrimary: const Color(0xFFFFFFFF),
-        textSecondary: const Color(0xFFA0A0A0),
-      ),
-    ],
-  ),
-)
-```
-
-## Dark Mode
-
-```dart
-CometChatThemeMode.mode = ThemeMode.dark;   // Force dark
-CometChatThemeMode.mode = ThemeMode.system;  // Follow system
-```
-
-## Commonly Used Color Tokens
-
-| Token | Description | Light Default | Dark Default |
-|-------|-------------|---------------|--------------|
-| `primary` | Brand color | `#6852D6` | `#604CC3` |
-| `background1`–`4` | Surface backgrounds | neutral50→neutral300 | neutral50→neutral300 |
-| `textPrimary` | Main text | neutral900 | neutral900 |
-| `textSecondary` | Secondary text | neutral600 | neutral600 |
-| `borderLight` | Subtle borders | neutral200 | neutral200 |
-| `iconPrimary` | Main icons | neutral900 | neutral900 |
-| `iconSecondary` | Secondary icons | neutral500 | neutral500 |
-| `iconHighlight` | Highlighted icons | primary | primary |
-| `error` | Error states | `#F44649` | `#C73C3E` |
-| `white` / `black` | Fixed (NOT brightness-aware) | `Colors.white` / `Colors.black` | Same |
-| `transparent` | Transparent | `Colors.transparent` | Same |
-| `neutral600` | Used for date styles | — | — |
-
-Extended primary shades (`extendedPrimary50`–`900`) are auto-generated from `primary`. Override individually if needed.
-
-## Commonly Used Spacing Tokens
-
-| Token | Default |
-|-------|---------|
-| `padding` / `spacing` / `radius` | 2 |
-| `padding1` / `spacing1` / `radius1` | 4 |
-| `padding2` / `spacing2` / `radius2` | 8 |
-| `padding3` / `spacing3` / `radius3` | 12 |
-| `padding4` / `spacing4` / `radius4` | 16 |
-| `padding5` / `spacing5` / `radius5` | 20 |
-| `padding6` / `spacing6` | 24 |
-| `radiusMax` / `spacingMax` | 1000 |
-
-## Typography Tokens
-
-`CometChatTypography` provides: `heading1`–`heading4`, `body`, `caption1`, `caption2`, `button`, `link`, `title`.
-
-Each has `.bold`, `.medium`, `.regular` variants:
-```dart
-typography.body?.regular?.fontSize
-typography.heading2?.bold?.fontWeight
-typography.caption1?.regular?.fontFamily
-```
-
-## Theme Caching Pattern (from package source)
-
-All UIKit components cache theme unconditionally in `didChangeDependencies()`:
-
-```dart
-// ✅ CORRECT — matches actual package pattern
-@override
-void didChangeDependencies() {
-  super.didChangeDependencies();
-  colorPalette = CometChatThemeHelper.getColorPalette(context);
-  spacing = CometChatThemeHelper.getSpacing(context);
-  typography = CometChatThemeHelper.getTypography(context);
-}
-```
-
-Do NOT use a `_themeInitialized` flag — it prevents theme updates on system theme changes.
-
-## Component Style Classes — merge() Pattern
-
-Every component has a `CometChat{Component}Style` extending `ThemeExtension`. Resolved internally:
-
-```dart
-// Inside component's didChangeDependencies():
-style = CometChatThemeHelper.getTheme<CometChatConversationsStyle>(
-    context: context,
-    defaultTheme: CometChatConversationsStyle.of,
-).merge(widget.conversationsStyle);
-```
-
-Pass overrides via constructor:
-```dart
-CometChatConversations(
-  conversationsStyle: CometChatConversationsStyle(
-    backgroundColor: Colors.black,
-  ),
-)
-```
-
-## Gotchas
-
-- `colorPalette.white` / `black` / `transparent` are NOT brightness-aware — use `neutral50` for brightness-aware white
-- Extended primary shades auto-generated from `primary` by blending with white (light) or black (dark)
-
-## Checklist — Theming
-
-- [ ] Colors from `CometChatThemeHelper.getColorPalette(context)`, never hardcoded
-- [ ] Theme cached in `didChangeDependencies()`, not `build()`
-- [ ] Custom theme registered as `ThemeExtension` on both `theme` and `darkTheme`
-- [ ] Component styles passed via constructor props

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

@@ -1,130 +0,0 @@
----
-name: cometchat-flutter-v5-troubleshooting
-description: "Use when debugging CometChat Flutter UIKit v5 issues. Symptom-to-cause lookup, verify checks, common errors, drift detection."
-license: "MIT"
-compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_calls_uikit ^5.0.15; cometchat_uikit_shared ^5.2.3"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter v5 troubleshooting debug errors fix"
----
-
-> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
-
-# CometChat Flutter UIKit v5 — Troubleshooting
-
-Symptom-to-cause lookup and verification checks.
-
-## Init / Login Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| "Authentication null" | `CometChatUIKit.init()` not called | Call init before login/components |
-| "APP ID null" | appId not set in UIKitSettingsBuilder | Set `..appId = 'YOUR_APP_ID'` |
-| Login hangs silently | `init()` hasn't completed yet | Await init completion via `onSuccess` before calling login |
-| "ERR_INVALID_REGION" | Uppercase region | Use lowercase: `'us'`, `'eu'`, `'in'` |
-| Login succeeds but no messages load | `subscriptionType` not set | Set `..subscriptionType = CometChatSubscriptionType.allUsers` |
-
-## UI / Layout Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Theme jank during keyboard animation | `CometChatThemeHelper.getColorPalette(context)` called in `build()` | Cache in `didChangeDependencies()` |
-| Components don't reflect theme changes | Using `_themeInitialized` flag | Remove flag — cache unconditionally in `didChangeDependencies()` |
-| Hardcoded colors don't match dark mode | Using `Color(0xFF...)` instead of theme tokens | Use `colorPalette.primary`, `colorPalette.textPrimary`, etc. |
-| `colorPalette.white` doesn't change in dark mode | `white`/`black`/`transparent` are NOT brightness-aware | Use `colorPalette.neutral50` for brightness-aware white |
-
-## GetX Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| "GetX controller not found" | Using `Get.find()` before `Get.put()` | Let UIKit components manage their own controllers |
-| Controller not disposed | Manually created controller without cleanup | Use `controllerTag` or let widget manage lifecycle |
-| Multiple controller instances | Creating controller outside the widget | Let the widget's `initState()` handle `Get.put()` |
-| `Get.delete()` throws | Deleting controller that was created with `controllerTag` | Only delete if `controllerTag` was null (widget-managed) |
-
-## Listener / Event Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Duplicate events firing | Listener not removed in `dispose()` | Always remove with same ID used to register |
-| Listener ID collision | Hardcoded listener ID string | Use timestamp: `'id_${DateTime.now().millisecondsSinceEpoch}'` |
-| No typing indicators | `subscriptionType` not set | Set `CometChatSubscriptionType.allUsers` |
-| No online/offline status | `subscriptionType` not set | Same fix |
-| `ccMessageSent` not firing | Using `CometChat.sendMessage()` directly | Use `CometChatUIKit.sendTextMessage()` instead |
-| Events fire after screen disposed | Listener not removed | Remove in `dispose()` / `onClose()` |
-
-## Call Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Incoming call overlay doesn't show | `CallNavigationContext.navigatorKey` not set | Set on `MaterialApp.navigatorKey` |
-| Call buttons don't appear | `CometChatCallingExtension` not registered | Set `..callingExtension = CometChatCallingExtension()` on UIKitSettingsBuilder |
-| Call fails silently | Camera/microphone permissions not granted | Request `Permission.camera` and `Permission.microphone` |
-| Incoming calls not handled | Call listener not registered globally | Register `CallListener` + `CometChatCallEventListener` at dashboard level |
-
-## Push Notification Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| No push notifications | Token not registered | Call `CometChatNotifications.registerPushToken(PushPlatforms.FCM_FLUTTER_ANDROID, fcmToken: token, ...)` after login (`PNRegistry.registerPNService` is a v5 sample-app extension, not a kit API — must be copied in; see cometchat-flutter-v5-push) |
-| Notifications after logout | Token not unregistered | Call `CometChatNotifications.unregisterPushToken(onSuccess:, onError:)` before logout |
-| Duplicate notifications | Foreground notification shown for active conversation | Check `conversationId` match before showing |
-| VoIP call notification doesn't show | Background handler not top-level | Use `@pragma('vm:entry-point')` on top-level function |
-| Tap doesn't navigate | `CallNavigationContext.navigatorKey.currentContext` is null | Ensure `navigatorKey` is set on MaterialApp |
-| iOS VoIP token not registered | Missing VoIP background mode | Enable Voice over IP in Xcode Background Modes |
-
-## Android Build Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Release build crash | Missing ProGuard keep rules | Add `-keep class com.cometchat.** { *; }` |
-| Build fails with minSdk error | minSdk too low | Set `minSdk 24` in `android/app/build.gradle` (matches vendor sample apps; bump to 26 ONLY if calls + min-SDK runtime errors) |
-| AndroidX conflict | Missing AndroidX migration | Set BOTH `android.useAndroidX=true` AND `android.enableJetifier=true` in `gradle.properties` |
-
-## iOS Build Issues
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Camera/mic permission crash | Missing Info.plist entries | Add `NSCameraUsageDescription`, `NSMicrophoneUsageDescription` |
-| Pod install fails | Cocoapods version mismatch | Run `pod repo update` then `pod install` |
-
-## Callback Signature Errors
-
-| Symptom | Cause | Fix |
-|---------|-------|-----|
-| Type error on `CometChatUsers.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, User)?` |
-| Type error on `CometChatGroups.onItemTap` | Missing `BuildContext` parameter | Signature is `Function(BuildContext, Group)?` |
-| Type error on `CometChatConversations.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(Conversation)?` — no BuildContext |
-| Type error on `CometChatGroupMembers.onItemTap` | Extra `BuildContext` parameter | Signature is `Function(GroupMember)?` — no BuildContext |
-
-## v5 vs v6 Drift Detection
-
-If you see any of these in a v5 project, it's a v6 pattern that was accidentally used:
-
-| v6 Pattern (wrong in v5) | v5 Equivalent |
-|--------------------------|---------------|
-| `import 'package:flutter_bloc/flutter_bloc.dart'` | GetX — no BLoC in v5 |
-| `extends Bloc<Event, State>` | `extends GetxController` |
-| `extends Equatable` | Not used in v5 |
-| `ServiceLocator.get<T>()` | `Get.find<T>()` or let widget manage |
-| Single `cometchat_chat_uikit` with calls built-in | Separate `cometchat_calls_uikit` package |
-| Per-component style classes (e.g. `CometChatConversationsStyle`, `CometChatMessageListStyle`) + theme via `CometChatTheme` | Per-widget feature flags only (no BuilderSettings/BuilderColor/BuilderTypography in v5 — those are v4 leftovers) |
-| `enableCalls: true` + `CallingConfiguration()` on UIKitSettingsBuilder | `..callingExtension = CometChatCallingExtension()` |
-
-## Verify Checklist
-
-Run through this when something isn't working:
-
-- [ ] `CometChatUIKit.init()` completes before any other CometChat call
-- [ ] `subscriptionType` set in UIKitSettingsBuilder
-- [ ] `region` is lowercase
-- [ ] Theme cached in `didChangeDependencies()`, not `build()`
-- [ ] All listeners registered with unique IDs
-- [ ] All listeners removed in `dispose()` / `onClose()`
-- [ ] `CallNavigationContext.navigatorKey` set on MaterialApp
-- [ ] `CometChatCallingExtension()` set if using calls
-- [ ] Push tokens registered after login
-- [ ] Push tokens unregistered before logout
-- [ ] ProGuard rules present for release builds
-- [ ] No v6 imports (`flutter_bloc`, `equatable`, `BlocProvider` / `BlocBuilder`)

package/skills/cometchat-flutter-v5-users-groups/SKILL.md

@@ -1,152 +0,0 @@
----
-name: cometchat-flutter-v5-users-groups
-description: "Use when working with CometChat Flutter UIKit v5 user and group list components. Triggers on CometChatUsers, CometChatGroups, CometChatGroupMembers, CometChatChangeScope."
-license: "MIT"
-compatibility: "cometchat_chat_uikit ^5.2.14; cometchat_uikit_shared ^5.2.3"
-metadata:
-  author: "CometChat"
-  version: "3.0.0"
-  tags: "cometchat flutter v5 users groups members scope contacts"
----
-
-> **Ground truth:** `cometchat_chat_uikit: ^5.2` (legacy/maintenance-only; calls via raw `cometchat_calls_sdk ^5.0.2`) — pub-cache source + `ui-kit/flutter/v5`. **Official docs:** https://www.cometchat.com/docs/ui-kit/flutter/v5/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.
-
-# CometChat Flutter UIKit v5 — Users & Groups
-
-Components for displaying and managing users, groups, and group members.
-
-## CometChatUsers
-
-Displays a list of users, sorted alphabetically.
-
-### Key Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `usersRequestBuilder` | `UsersRequestBuilder?` | — | Custom fetch builder |
-| `usersStyle` | `CometChatUsersStyle` | `const CometChatUsersStyle()` | Visual styling |
-| `onItemTap` | `Function(BuildContext, User)?` | — | Tap callback (**includes BuildContext**) |
-| `onItemLongPress` | `Function(BuildContext, User)?` | — | Long press callback |
-| `subtitleView` | `Widget? Function(BuildContext, User)?` | — | Custom subtitle |
-| `title` | `String?` | — | List title |
-| `showBackButton` | `bool` | `true` | Show back button |
-| `hideSearch` | `bool` | `false` | Hide search bar |
-| `selectionMode` | `SelectionMode?` | — | Enable selection mode |
-| `onSelection` | `Function(List<User>?, BuildContext)?` | — | Selection callback |
-| `usersStatusVisibility` | `bool?` | `true` | Show online status |
-| `hideAppbar` | `bool?` | `false` | Hide app bar |
-| `appBarOptions` | `List<Widget> Function(BuildContext)?` | — | App bar trailing widgets |
-| `controllerTag` | `String?` | — | Custom GetX controller tag |
-| `stickyHeaderVisibility` | `bool?` | `false` | Show alphabetical headers |
-
-### Usage
-
-```dart
-CometChatUsers(
-  onItemTap: (context, user) {
-    Navigator.push(context, MaterialPageRoute(
-      builder: (_) => MessagesScreen(user: user),
-    ));
-  },
-)
-
-// With custom request builder
-CometChatUsers(
-  usersRequestBuilder: UsersRequestBuilder()
-    ..limit = 30
-    ..friendsOnly = true,
-)
-
-// Filter by role (e.g., AI agents)
-CometChatUsers(
-  title: "Agents",
-  usersRequestBuilder: UsersRequestBuilder()
-    ..roles = [AIConstants.aiRole],
-  onItemTap: (context, user) { ... },
-)
-```
-
-## CometChatGroups
-
-Displays a list of groups with type indicators.
-
-### Key Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `groupsRequestBuilder` | `GroupsRequestBuilder?` | — | Custom fetch builder |
-| `groupsStyle` | `CometChatGroupsStyle?` | — | Visual styling |
-| `onItemTap` | `Function(BuildContext, Group)?` | — | Tap callback (**includes BuildContext**) |
-| `onItemLongPress` | `Function(BuildContext, Group)?` | — | Long press callback |
-| `subtitleView` | `Widget? Function(BuildContext, Group)?` | — | Custom subtitle |
-| `title` | `String?` | — | List title |
-| `showBackButton` | `bool` | `true` | Show back button |
-| `hideSearch` | `bool` | `false` | Hide search bar |
-| `selectionMode` | `SelectionMode?` | — | Enable selection mode |
-| `groupTypeVisibility` | `bool` | `true` | Show group type icon |
-| `hideAppbar` | `bool?` | `false` | Hide app bar |
-| `appBarOptions` | `List<Widget> Function(BuildContext)?` | — | App bar trailing widgets |
-| `controllerTag` | `String?` | — | Custom GetX controller tag |
-
-### Usage
-
-```dart
-CometChatGroups(
-  onItemTap: (context, group) {
-    Navigator.push(context, MaterialPageRoute(
-      builder: (_) => MessagesScreen(group: group),
-    ));
-  },
-)
-```
-
-## CometChatGroupMembers
-
-Displays members of a specific group with role indicators.
-
-```dart
-CometChatGroupMembers(
-  group: group,
-  onItemTap: (member) {
-    debugPrint('Tapped: ${member.name}, role: ${member.scope}');
-  },
-)
-```
-
-Key props: `group` (required), `groupMembersRequestBuilder`, **`style`** (`CometChatGroupMembersStyle?` — prop name is `style`, NOT `groupMembersStyle`; verified `cometchat_group_members.dart:25/88`), `subtitleView`, `trailingView`, `onItemTap` (`Function(GroupMember)?` — **no BuildContext**), `selectionMode`, `onSelection` (`Function(List<GroupMember>?)?` — no BuildContext).
-
-## CometChatChangeScope
-
-Widget for changing a group member's scope/role.
-
-```dart
-CometChatChangeScope(group: group, member: member)
-```
-
-## Callback Signature Differences
-
-| Component | `onItemTap` signature |
-|-----------|----------------------|
-| `CometChatConversations` | `Function(Conversation)?` — **no BuildContext** |
-| `CometChatUsers` | `Function(BuildContext, User)?` — **has BuildContext** |
-| `CometChatGroups` | `Function(BuildContext, Group)?` — **has BuildContext** |
-| `CometChatGroupMembers` | `Function(GroupMember)?` — **no BuildContext** |
-
-This is a common source of confusion.
-
-## Anti-Patterns
-
-```dart
-// ❌ WRONG — missing BuildContext in Users/Groups onItemTap
-CometChatUsers(onItemTap: (user) { ... }) // Missing BuildContext!
-
-// ✅ CORRECT
-CometChatUsers(onItemTap: (context, user) { ... })
-CometChatGroups(onItemTap: (context, group) { ... })
-```
-
-## Checklist — Users & Groups
-
-- [ ] `onItemTap` callback signature includes `BuildContext` for Users/Groups
-- [ ] Custom request builders set appropriate limits
-- [ ] Let widgets manage their own GetX controller lifecycle