@cometchat/skills 4.2.1 → 4.4.0

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

@@ -6,14 +6,15 @@ description: >
   Use when the user wants custom bubbles, custom headers, custom list items, custom
   message actions, or custom message types.
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "shell, file-read, file-search, file-list, grep"
+compatibility: "cometchat_chat_uikit ^6.0.1"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter customization bubbles templates formatters datasource"
 ---
 
+> **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.
+
 # CometChat Flutter UIKit v6 — Customization Guide
 
 Four tiers of customization, from lightest to deepest.
@@ -41,8 +42,11 @@ CometChatConversations(
   listItemView: (Conversation conversation) => MyCustomConversationTile(conversation),
 
   // Replace individual slots
-  subtitleView: (BuildContext context, Conversation conversation) =>
-      Text(conversation.lastMessage?.text ?? ''),
+  subtitleView: (BuildContext context, Conversation conversation) {
+    final last = conversation.lastMessage;
+    final preview = last is TextMessage ? last.text : '';
+    return Text(preview);
+  },
   trailingView: (Conversation conversation) =>
       Icon(Icons.chevron_right),
   leadingView: (BuildContext context, Conversation conversation) =>
@@ -107,8 +111,8 @@ CometChatMessageHeader(
 CometChatMessageList(
   user: user,
   group: group,
-  headerView: (context, state) => MyCustomListHeader(),
-  footerView: (context, state) => MyCustomListFooter(),
+  headerView: (context, {user, group, parentMessageId}) => MyCustomListHeader(),
+  footerView: (context, {user, group, parentMessageId}) => MyCustomListFooter(),
   emptyStateView: (context) => Center(child: Text('Start a conversation')),
   emptyChatGreetingView: (context) => WelcomeWidget(),
   loadingStateView: (context) => ShimmerList(),
@@ -122,11 +126,11 @@ CometChatMessageList(
 CometChatMessageComposer(
   user: user,
   group: group,
-  headerView: (context, state) => ReplyPreviewBanner(),
-  footerView: (context, state) => SuggestedActionsBar(),
-  auxiliaryButtonView: (context, user, group, composerState) =>
+  headerView: (context, user, group, id) => ReplyPreviewBanner(),
+  footerView: (context, user, group, id) => SuggestedActionsBar(),
+  auxiliaryButtonView: (context, user, group, id) =>
       IconButton(icon: Icon(Icons.gif), onPressed: () {}),
-  secondaryButtonView: (context, user, group, composerState) =>
+  secondaryButtonView: (context, user, group, id) =>
       IconButton(icon: Icon(Icons.attach_file), onPressed: () {}),
   sendButtonView: Icon(Icons.send, color: Colors.blue),
 )
@@ -156,7 +160,7 @@ CometChatMessageList(
   messagesRequestBuilder: MessagesRequestBuilder()
     ..uid = user.uid
     ..limit = 50
-    ..hideDeletedMessages = true
+    ..hideDeleted = true
     ..searchKeyword = 'invoice'
     ..categories = [MessageCategoryConstants.message]
     ..types = [MessageTypeConstants.text, MessageTypeConstants.image],
@@ -195,7 +199,7 @@ CometChatGroupMembers(
   group: group,
   groupMembersRequestBuilder: GroupMembersRequestBuilder(group.guid)
     ..limit = 30
-    ..scopes = [GroupMemberScope.admin, GroupMemberScope.moderator],
+    ..scopes = [CometChatMemberScope.admin, CometChatMemberScope.moderator],
 )
 ```
 
@@ -271,10 +275,16 @@ class CometChatMessageTemplate {
     this.bottomView,          // below contentView
     this.statusInfoView,      // receipts/time area
     this.threadView,          // thread reply indicator
-    this.replyView,           // quoted reply preview
+    this.replyView,           // quoted-reply preview area (3-arg builder, NO additionalConfigurations)
     this.options,             // long-press menu options
   });
 }
+
+// `replyView` exists on BOTH CometChatMessageTemplate (template-level, signature
+// `(BaseMessage, BuildContext, BubbleAlignment)`) AND on CometChatMessageBubble
+// (the widget slot). Verified: only the clean_architecture template is exported
+// (shared_ui/src/clean_architecture/data/models/cometchat_message_template.dart:79)
+// — the legacy shared_ui/src/models/ copy without replyView is NOT exported.
 ```
 
 Override templates on `CometChatMessageList`:
@@ -327,6 +337,55 @@ CometChatMessageOption(
 )
 ```
 
+### Custom attachment options — the builder REPLACES, so spread the defaults
+
+`CometChatMessageComposer.attachmentOptions` is a `ComposerActionsBuilder` — `List<CometChatMessageComposerAction> Function(BuildContext, User?, Group?, Map<String,dynamic>? id)`. **Whatever list you return becomes the entire menu**; there is no merge. To add one option while keeping photo/video/audio/file/poll, seed the list from `ComposerAttachmentUtils.getAttachmentOptions(...)`.
+
+> ⚠️ **`ComposerAttachmentUtils` is NOT exported from the package barrel** (`cometchat_chat_uikit.dart`) — verified by `dart analyze` against published `cometchat_chat_uikit 6.0.1`. The normal `import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';` does **not** expose it; you must add a **deep import** of the internal path:
+> ```dart
+> import 'package:cometchat_chat_uikit/chat_ui/src/message_composer/utils/composer_attachment_utils.dart';
+> ```
+> This is an internal (`src/`) path — it works on 6.0.1 but is not part of the public API contract, so it may move across patch versions. There is no public accessor for the default attachment list in V6; this deep import is the only way to seed the defaults.
+
+```dart
+import 'package:cometchat_chat_uikit/cometchat_chat_uikit.dart';
+import 'package:cometchat_chat_uikit/chat_ui/src/message_composer/utils/composer_attachment_utils.dart'; // ComposerAttachmentUtils (not barrel-exported)
+
+CometChatMessageComposer(
+  attachmentOptions: (context, user, group, id) => [
+    ...ComposerAttachmentUtils.getAttachmentOptions(context, id, null), // defaults
+    CometChatMessageComposerAction(
+      id: 'location',
+      title: 'Send Location',
+      onItemClick: (ctx, u, g) { /* pick + send (below) */ },
+    ),
+  ],
+)
+```
+
+```dart
+// ❌ returns ONLY your option — every default attachment disappears
+attachmentOptions: (context, user, group, id) => [locationAction],
+```
+
+### Sending a custom message — use the UIKit path, not the raw SDK
+
+A `contentView`/`BubbleFactory` only renders the type; send the message with **`CometChatUIKit.sendCustomMessage(...)`**, not `CometChat.sendCustomMessage(...)`. The UIKit wrapper sets `muid` + sender and fires `ccMessageSent`, which makes the new bubble **append** to the open list. The raw SDK call skips those, giving a recipient error and a realtime bubble that **replaces** an existing one (no `muid` dedup).
+
+```dart
+final message = CustomMessage(
+  receiverUid: user.uid,
+  receiverType: ReceiverTypeConstants.user,   // or .group
+  type: 'location',                           // matches the template type
+  customData: {'lat': 19.07, 'lng': 72.87},
+);
+// ✅ kit path — sets muid + sender, emits ccMessageSent → list appends
+await CometChatUIKit.sendCustomMessage(message);
+// ❌ await CometChat.sendCustomMessage(message);  // recipient error + realtime replace
+```
+
+Verified (v6, `dart analyze` vs published 6.0.1): `ComposerAttachmentUtils.getAttachmentOptions(BuildContext, Map?, AdditionalConfigurations?)` (composer_attachment_utils.dart:254 — **NOT barrel-exported; requires the deep import above**), `CometChatUIKit.sendCustomMessage(CustomMessage)`, `CustomMessage(receiverUid:, receiverType:, type:, customData:)`, `CometChatMessageComposerAction(id:, title:, icon:, style:, onItemClick:(BuildContext,User?,Group?))` (cometchat_message_composer_action.dart:23), `CometChatMessageOption(id:, title:, icon:, onItemClick:(BaseMessage,CometChatMessageListControllerProtocol), messageOptionSheetStyle:)` (cometchat_message_option.dart:21), `CometChatMessageTemplate({required type, required category, bubbleView, headerView, contentView, footerView, bottomView, statusInfoView, threadView, replyView, options})` (clean_architecture/data/models/cometchat_message_template.dart:23), `CometChatMessageList(templates:, addTemplate:)` (chat_ui/.../message_list/widgets/cometchat_message_list.dart:46-47).
+
 ## 5. Tier 4: BubbleFactory & DataSource
 
 ### BubbleFactory
@@ -427,9 +486,7 @@ class LocationBubbleFactory extends BubbleFactory<CustomMessage> {
 
 Merge your custom factories with the defaults using `CometChatMessageTemplate.addTemplate` on the message list, or by providing a custom `templates` list that includes a `contentView` for your custom type.
 
-The `CometChatMessageBubble` widget supports two modes:
-- Smart mode: pass `message` and the factory registry resolves the content widget via `BubbleFactory.getFactoryKey(message)` → O(1) map lookup.
-- Manual mode: pass `contentView` directly — bypasses the factory.
+`CometChatMessageBubble` is a pure slot widget — it accepts pre-built `contentView`, `headerView`, `footerView`, `replyView`, `threadView`, `bottomView`, `statusInfoView`, and `leadingView` widgets. It does NOT resolve message types via a factory registry; factory resolution happens one layer up, inside `CometChatMessageList`, which picks the right template based on `category_type` and invokes that template's `contentView` builder.
 
 ```dart
 // Using addTemplate to register a custom type alongside defaults
@@ -450,17 +507,22 @@ CometChatMessageList(
 
 ### DataSource Pattern
 
+> **V6 ≠ V5 here.** V6 has **no** `ChatConfigurator`, `DataSource`/`DataSourceDecorator`, `ExtensionsDataSource`, `CometChatUIKit.getDataSource()`, or `getAllMessageTemplates()` override-and-register flow — that GetX-era framework is **V5-only** (verified absent in the v6 clone). In V6 you merge custom templates with the widget-level `addTemplate:` prop and customize data fetching by supplying a custom BLoC. Don't carry the V5 decorator recipe over.
+
 Each component follows Clean Architecture with its own data source layer. The data sources abstract SDK calls behind interfaces:
 
 ```dart
-// Example: ConversationsRemoteDataSource
+// Example: ConversationsRemoteDataSource (full real interface)
 abstract class ConversationsRemoteDataSource {
-  Future<List<Conversation>> getConversations({ConversationsRequest? request});
-  Future<void> deleteConversation(String conversationWith);
+  Future<List<Conversation>> getConversations({int limit = 30, String? fromId});
+  Future<Conversation?> getConversation(String conversationWith, String conversationType);
+  Future<void> deleteConversation(String conversationWith, String conversationType);
+  Future<void> markMessageAsRead(BaseMessage message);
+  Future<Conversation?> updateConversation(BaseMessage message);
 }
 
 class ConversationsRemoteDataSourceImpl implements ConversationsRemoteDataSource {
-  // Delegates to CometChat SDK
+  // Delegates to CometChat SDK — must implement ALL five methods above.
 }
 ```
 
@@ -569,10 +631,12 @@ void didChangeDependencies() {
   }
 }
 
-// Pass to children
+// Pass to children — CometChatMessageBubble exposes colorPalette + spacing only
 CometChatMessageBubble(
   colorPalette: _colorPalette,  // pre-cached, zero lookups in child
   spacing: _spacing,
+  // For typography, read CometChatThemeHelper.getTypography(context) in the
+  // parent and use it directly inside the slot widgets you pass in.
 )
 ```
 
@@ -607,7 +671,7 @@ CometChatMessageList(
     CometChatMessageTemplate(
       type: MessageTypeConstants.text,
       category: MessageCategoryConstants.message,
-      contentView: (msg, ctx, align, {additionalConfigurations}) => Text(msg.text),
+      contentView: (msg, ctx, align, {additionalConfigurations}) => Text(msg is TextMessage ? msg.text : ''),
       // options: null — no long-press menu at all!
     ),
   ],
@@ -634,15 +698,19 @@ return Container(color: colorPalette?.primary ?? Colors.blue);
 ```
 
 ```dart
-// ❌ WRONG — forgetting resizeToAvoidBottomInset: false on Scaffold with composer
+// ✅ CORRECT on ^6.0.1 — true (or omit; true is the default). The composer
+//   clamps the keyboard height to viewInsets (kit fix ENG-34434), so true does
+//   NOT double-compensate.
 Scaffold(
+  resizeToAvoidBottomInset: true,
   body: Column(children: [
     Expanded(child: CometChatMessageList(user: user)),
     CometChatMessageComposer(user: user),
   ]),
 )
 
-// ✅ CORRECT
+// ⚠ PRE-6.0.1 ONLY — false was the stopgap before the clamp landed. On ^6.0.1
+//   this is unnecessary; if you still see a double keyboard gap, upgrade the kit.
 Scaffold(
   resizeToAvoidBottomInset: false,
   body: Column(children: [
@@ -660,7 +728,11 @@ Scaffold(
 - [ ] Custom `BubbleFactory.build()` uses the passed `colorPalette`/`typography`/`spacing` params, not hardcoded values
 - [ ] Style overrides use `merge()` pattern, not constructor replacement
 - [ ] Theme lookups cached in `didChangeDependencies()` with `_themeInitialized` flag
-- [ ] `Scaffold` containing `CometChatMessageComposer` has `resizeToAvoidBottomInset: false`
+- [ ] `Scaffold` containing `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
 - [ ] Custom `CometChatMessageOption.onItemClick` handles both `BaseMessage` and the controller protocol
 - [ ] Request builders set `limit` to a reasonable value (default 30–50)
 - [ ] Mutable `_user`/`_group` state copies passed to UIKit components, not `widget.user`/`widget.group`
+
+## Sound (in-app message + call sounds)
+
+Sound is a customization sub-dimension. The UI Kit plays incoming/outgoing message + call sounds via `CometChatSoundManager` — mute it, swap custom audio, or play a specific sound. The full API + recipe lives in **`cometchat-flutter-v6-theming`** (Sound section). Verify the access path against the installed kit before relying on it.

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

@@ -12,14 +12,15 @@ description: >
   addMessageListener, removeMessageListener, ChatSDKEventInitializer,
   or any real-time update handling in CometChat.
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.0-beta2; cometchat_sdk ^4.1.2"
-allowed-tools: "shell, file-read, file-search, file-list, grep"
+compatibility: "cometchat_chat_uikit ^6.0.1; cometchat_sdk ^5.0.1"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter events listeners real-time typing receipts presence"
 ---
 
+> **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.
+
 # CometChat Flutter UIKit — Events & Listeners
 
 Two event systems: SDK listeners (from CometChat server) and UI events (from UIKit components).

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

@@ -7,21 +7,27 @@ description: >
   what needs UIKitSettings flags, what's enabled by `cometchat apply-feature <id>`,
   and what needs manual dashboard configuration (third-party API keys).
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.0-beta2"
-allowed-tools: "shell, file-read, file-search, file-list, grep"
+compatibility: "cometchat_chat_uikit ^6.0.1"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter features calls reactions stickers ai smart-replies extensions"
 ---
 
+> **Ground truth:** `cometchat_chat_uikit: ^6.0` + `packages/registry/v6/features/catalog.json`. (Official docs linked below.) Verify symbols against the installed package/source before relying on them.
+
+> **Also serves Flutter V5** for feature *enablement*: there is no separate `cometchat-flutter-v5-features`. The `apply-feature` CLI + 5-tier taxonomy here are identical for V5 (enablement is the SDK/dashboard path, version-independent). Only the in-UI wiring differs — for V5's GetX-based surfaces, follow `cometchat-flutter-v5-customization` / `-calls` for the widget side. V5 is legacy/maintenance-only.
+
 # CometChat Flutter UIKit v6 — Features
 
 How to enable, configure, and disable features in `cometchat_chat_uikit`.
 
 ## 1. Feature Categories
 
-Every feature falls into one of three categories:
+> **Canonical public feature-availability matrix:** [Features & Extensions Guide](https://www.cometchat.com/docs/fundamentals/features-and-extensions-guide) — the authoritative source for which integration method (UI Kit / UI Kit Builder / Widget Builder / SDK) supports each feature + dashboard setup + whether code is required. It **outranks the local `catalog.json` snapshot on conflict**; consult it (WebFetch or docs MCP) for any availability decision.
+
+
+Every feature falls into one of these categories (the product's "work needed" model — Core/zero-setup · Builder-enabled · Config-only · Config+settings · SDK-integrated). **Key rule:** the only category that needs **client code** is the SDK-integrated one (a few extensions like Bitly / message shortcuts) — and for those **the implementation lives in the docs** (fetch + adapt it, don't hand-roll). Everything in the table below except such SDK-integrated extensions is enable-and-done (no code):
 
 | Category | What it means | Example features | How to enable |
 |---|---|---|---|
@@ -29,7 +35,7 @@ Every feature falls into one of three categories:
 | **UIKitSettings flag** | Set a property on `UIKitSettingsBuilder` before `CometChatUIKit.init()` | Voice/video calls (`enableCalls: true`), presence/typing (`subscriptionType`) | Set the flag → init |
 | **Extension** | Backend extension, pure boolean toggle. CLI flips via the dashboard API. | Polls, stickers, message translation, link preview, collaborative document, collaborative whiteboard, image moderation, thumbnail generation | `cometchat apply-feature <id> --app-id <X>` → restart app |
 | **AI feature** | Backend AI feature requiring an OpenAI API key on the app's AI settings | Smart replies, conversation starters, conversation summary | `cometchat apply-feature <id> --app-id <X> --openai-key sk-...` → restart app |
-| **Dashboard-only** | Third-party API key / multi-field config the user must enter themselves | Giphy, Stipop, Tenor, Chatwoot, Intercom, Disappearing Messages, Message Shortcuts | Open https://app.cometchat.com → Extensions → enter config → enable |
+| **Dashboard-only** | Third-party API key / multi-field config the user must enter themselves | Giphy, Stipop, Tenor, Chatwoot, Intercom, Disappearing Messages, Message Shortcuts | Open https://app.cometchat.com → Chat & Messaging → Features → enter config → enable |
 
 ## 2. Auto-Enabled Features
 
@@ -107,7 +113,7 @@ cometchat apply-feature smart-replies --app-id <your-app-id> --openai-key sk-...
 
 Requires `cometchat auth login` once per machine. Once enabled, the UIKit auto-wires the UI.
 
-For dashboard-only extensions (Giphy, Stipop, Tenor, Chatwoot, Intercom — they need third-party API keys / webhooks), use https://app.cometchat.com → Extensions.
+For dashboard-only extensions (Giphy, Stipop, Tenor, Chatwoot, Intercom — they need third-party API keys / webhooks), use https://app.cometchat.com → Chat & Messaging → Features.
 
 | Extension | UI surface when enabled | Extension directory |
 |---|---|---|
@@ -248,7 +254,10 @@ The composer's WYSIWYG toolbar is the active formatting system. Configure via:
 CometChatMessageComposer(
   user: user,
   group: group,
-  richTextConfiguration: RichTextConfiguration(...),
+  // There is NO `richTextConfiguration` param. The real rich-text props are:
+  enableRichTextFormatting: true,
+  showRichTextFormattingOptions: true,
+  // hideRichTextFormattingOptions: <Set<FormatType>>,   // optional
   richTextToolbarView: (context) => CustomToolbar(),
   onRichTextFormatApplied: (formatType) { },
 )

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

@@ -12,14 +12,15 @@ description: >
   smart replies, conversation starters, or resizeToAvoidBottomInset. Also use when
   the user asks about building a chat screen, message input, or message display.
 license: "MIT"
-compatibility: "cometchat_chat_uikit ^6.0.0-beta2; flutter_bloc ^8.1.0"
-allowed-tools: "shell, file-read, file-search, file-list, grep"
+compatibility: "cometchat_chat_uikit ^6.0.1; flutter_bloc ^8.1.0"
 metadata:
   author: "CometChat"
   version: "3.0.0"
   tags: "cometchat flutter messages composer header bubbles keyboard rich-text"
 ---
 
+> **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.
+
 # CometChat Flutter UIKit — Messages
 
 The messages screen is composed of three components: `CometChatMessageHeader`, `CometChatMessageList`, and `CometChatMessageComposer`.
@@ -27,38 +28,47 @@ The messages screen is composed of three components: `CometChatMessageHeader`, `
 ## Complete Messages Screen
 
 ```dart
+final colorPalette = CometChatThemeHelper.getColorPalette(context);
 Scaffold(
-  resizeToAvoidBottomInset: false, // REQUIRED — composer handles keyboard internally
+  resizeToAvoidBottomInset: true, // matches sample app; composer clamps to viewInsets (ENG-34434)
   appBar: CometChatMessageHeader(
     user: user,
     group: group,
     onBack: () => Navigator.pop(context),
   ),
-  body: Column(
-    children: [
-      Expanded(
-        child: CometChatMessageList(
-          user: user,
-          group: group,
-          textFormatters: [
-            CometChatMentionsFormatter(user: user, group: group),
-            MarkdownTextFormatter(),
-            CometChatUrlFormatter(),
-            CometChatPhoneNumberFormatter(),
-            CometChatEmailFormatter(),
-          ],
-        ),
-      ),
-      CometChatMessageComposer(
-        user: user,
-        group: group,
-        textFormatters: [
-          CometChatMentionsFormatter(user: user, group: group),
-          MarkdownTextFormatter(),
-          CometChatUrlFormatter(),
+  body: SafeArea(
+    top: false, // Header is the appBar — top inset already handled; keep bottom inset
+    child: Container(
+      color: colorPalette.background3,
+      child: Column(
+        children: [
+          Expanded(
+            child: CometChatMessageList(
+              user: user,
+              group: group,
+              textFormatters: [
+                CometChatMentionsFormatter(user: user, group: group),
+                MarkdownTextFormatter(),
+                CometChatUrlFormatter(),
+                CometChatPhoneNumberFormatter(),
+                CometChatEmailFormatter(),
+              ],
+            ),
+          ),
+          CometChatMessageComposer(
+            user: user,
+            group: group,
+            textFormatters: [
+              CometChatMentionsFormatter(user: user, group: group),
+              MarkdownTextFormatter(),
+              CometChatUrlFormatter(),
+              CometChatPhoneNumberFormatter(),
+              CometChatEmailFormatter(),
+            ],
+          ),
         ],
       ),
-    ],
+    ),
   ),
 )
 ```
@@ -81,6 +91,42 @@ Displays messages with `SliverAnimatedList`, O(1) lookups, and keyboard-aware sp
 | `hideDateSeparator` | `bool` | Hide date headers |
 | `textFormatters` | `List<CometChatTextFormatter>` | Formatters for message text |
 | `onThreadRepliesClick` | `Function(BaseMessage, BuildContext, {template})` | Thread navigation callback |
+| `messagesRequestBuilder` | `MessagesRequestBuilder?` | Customize the underlying message query (see below) |
+
+### MessagesRequestBuilder — customizing the message query
+
+`CometChatMessageList` accepts a `messagesRequestBuilder` prop that lets you customize the underlying SDK request — page size, filters, search, etc. The class lives in the Chat SDK (`package:cometchat_sdk/cometchat_sdk.dart`) and exposes 30+ fluent setters. Common setters:
+
+| Setter | Purpose |
+|--------|---------|
+| `setLimit(int)` | Page size (default 30, max 100) |
+| `setTypes(List<String>)` | Restrict to message types (e.g. `['text', 'image']`) |
+| `setCategories(List<String>)` | Restrict to categories (e.g. `['message', 'custom']`) |
+| `setHideMessagesFromBlockedUsers(bool)` | Drop messages from blocked users |
+| `setSearchKeyword(String)` | Server-side keyword search |
+| `setTags(List<String>)` | Filter by message tags |
+| `setHasAttachments(bool)` | Only messages with file attachments |
+| `setHasLinks(bool)` | Only messages containing links |
+| `setHideReplies(bool)` | Exclude threaded replies from the main list |
+| `setHideDeleted(bool)` | Exclude deleted messages |
+| `setHideQuotedMessages(bool)` | Exclude quoted-reply messages |
+| `setUpdatedAfter(DateTime)` | Only messages updated after this DateTime |
+| `setUpdatesOnly(bool)` | Return only updates, not new messages |
+| `setParentMessageId(int)` | Fetch a thread's replies |
+| `setMentionedUIDs(List<String>)` | Messages mentioning specific users |
+| `setHasMentions(bool)` | Only messages with any mention |
+
+Example — limit to 30, hide messages from blocked users, restrict to text + image:
+
+```dart
+CometChatMessageList(
+  user: user,
+  messagesRequestBuilder: MessagesRequestBuilder()
+    ..setLimit(30)
+    ..setHideMessagesFromBlockedUsers(true)
+    ..setTypes(['text', 'image']),
+)
+```
 
 ### MessageListBloc Events
 
@@ -149,6 +195,8 @@ BlocConsumer<MessageComposerBloc, MessageComposerState>(
 )
 ```
 
+The actual filter in `cometchat_message_composer.dart` also covers `editMessage` / `replyMessage` target changes and panel transitions (`headerPanel`, `footerPanel`, `previewPanel`, `lockedBottomPadding`, `isActiveStreaming`). The snippet above shows the three primary mode flags for brevity — if you subclass or wrap the composer, copy the full predicate from `cometchat_message_composer.dart` so edit/reply targets and panels also trigger rebuilds.
+
 ## CometChatMessageHeader
 
 Shows user/group info, typing indicators, and optional call buttons.
@@ -172,12 +220,14 @@ CometChatMessageHeader(
 
 ## Keyboard-Aware Spacing
 
-`SliverSpacing` handles keyboard interaction:
+The composer coordinates with the keyboard internally — it tracks the native keyboard height and **clamps it to Flutter's `viewInsets`** (kit fix ENG-34434) so it does NOT add its own inset on top of the Scaffold's. The list's spacing then reacts to the same `viewInsets`:
 - At bottom: keyboard pushes list up (normal behavior)
 - Scrolled up: list stays still, only composer moves
 - Safe area: only added when keyboard is closed
 
-This is why `resizeToAvoidBottomInset: false` is mandatory.
+Because of that clamp, **set `resizeToAvoidBottomInset: true`** (or omit it — `true` is the Scaffold default), which is exactly what the kit's official sample app does (`messages_screen.dart` omits it → defaults `true`; `thread_screen.dart` sets it `true` explicitly).
+
+> Version note: on kits **before ENG-34434 (pre-6.0.1)** the composer did NOT clamp, so `true` double-compensated and `false` was the workaround. On `^6.0.1` (what this skill targets) `true` is correct. If you ever see a double keyboard gap, you're on an older kit — upgrade, or set `false` as a stopgap.
 
 ## Message Bubbles
 
@@ -230,24 +280,35 @@ await CometChatUIKit.sendCustomMessage(
 ```dart
 CometChatMessageList(
   onThreadRepliesClick: (message, ctx, {template}) {
+    final colorPalette = CometChatThemeHelper.getColorPalette(context);
     Navigator.push(context, MaterialPageRoute(
       builder: (_) => Scaffold(
-        resizeToAvoidBottomInset: false,
-        body: Column(
-          children: [
-            CometChatThreadedHeader(
-              parentMessage: message,
-              loggedInUser: CometChatUIKit.loggedInUser!,
-            ),
-            Expanded(child: CometChatMessageList(
-              user: user, group: group,
-              parentMessageId: message.id,
-            )),
-            CometChatMessageComposer(
-              user: user, group: group,
-              parentMessageId: message.id,
+        resizeToAvoidBottomInset: true,
+        body: SafeArea(
+          child: Container(
+            color: colorPalette.background3,
+            child: Column(
+              children: [
+                CometChatThreadedHeader(
+                  parentMessage: message,
+                  loggedInUser: CometChatUIKit.loggedInUser!,
+                ),
+                Expanded(child: CometChatMessageList(
+                  user: user, group: group,
+                  parentMessageId: message.id,
+                  // Scope the list to this thread only: exclude the parent and
+                  // request just the replies for message.id.
+                  withParent: false,
+                  messagesRequestBuilder: MessagesRequestBuilder()
+                    ..parentMessageId = message.id,
+                )),
+                CometChatMessageComposer(
+                  user: user, group: group,
+                  parentMessageId: message.id,
+                ),
+              ],
             ),
-          ],
+          ),
         ),
       ),
     ));
@@ -257,7 +318,7 @@ CometChatMessageList(
 
 ## Gotchas
 
-- Forgetting `resizeToAvoidBottomInset: false` causes double keyboard compensation — the most common bug when integrating the messages screen. This applies to thread screens too — any Scaffold containing a `CometChatMessageComposer` must set it to `false`.
+- Use `resizeToAvoidBottomInset: true` (or omit — it's the default), matching the kit sample app. On `^6.0.1` the composer clamps the keyboard height to Flutter's `viewInsets` (ENG-34434), so `true` does NOT double-compensate. Only on pre-6.0.1 kits did `true` cause a double keyboard gap (where `false` was the workaround) — if you see that gap, upgrade the kit.
 - `textFormatters` should be the same list for both `CometChatMessageList` and `CometChatMessageComposer` to ensure consistent rendering.
 - The rich text system has 3 implementations but only WYSIWYG is active at runtime. Bug fixes go in `rich_text_editing_controller.dart`, not the clean architecture module.
 - `goToMessageId` loads messages around that ID, not from the beginning. The list may not have older messages loaded.
@@ -272,27 +333,17 @@ CometChatMessageList(
 ## Anti-Patterns
 
 ```dart
-// ❌ WRONG — missing resizeToAvoidBottomInset
+// ❌ WRONG — list not wrapped in Expanded (unbounded height → won't scroll / overflow)
 Scaffold(
   body: Column(children: [
-    Expanded(child: CometChatMessageList(user: user)),
+    CometChatMessageList(user: user),          // needs Expanded
     CometChatMessageComposer(user: user),
   ]),
 )
 
-// ❌ WRONG — thread screen with resizeToAvoidBottomInset: true
-Scaffold(
-  resizeToAvoidBottomInset: true, // Double compensation!
-  body: Column(children: [
-    CometChatThreadedHeader(parentMessage: message, loggedInUser: user),
-    Expanded(child: CometChatMessageList(user: user, parentMessageId: message.id)),
-    CometChatMessageComposer(user: user, parentMessageId: message.id),
-  ]),
-)
-
-// ✅ CORRECT — both messages and thread screens
+// ✅ CORRECT — both messages and thread screens (matches the kit sample app)
 Scaffold(
-  resizeToAvoidBottomInset: false,
+  resizeToAvoidBottomInset: true, // (or omit — true is the default; composer clamps to viewInsets, ENG-34434)
   body: Column(children: [
     Expanded(child: CometChatMessageList(user: user)),
     CometChatMessageComposer(user: user),
@@ -323,11 +374,11 @@ CometChatMessageComposer(textFormatters: formatters)
 
 ## Checklist
 
-- [ ] Scaffold has `resizeToAvoidBottomInset: false`
+- [ ] Scaffold has `resizeToAvoidBottomInset: true` (or omitted — default; matches the sample app)
 - [ ] Both list and composer have matching `textFormatters`
 - [ ] Mutable `_user`/`_group` state copies, not `widget.user`/`widget.group`
 - [ ] `onThreadRepliesClick` navigates to thread screen with `parentMessageId`
-- [ ] Thread screen Scaffold also has `resizeToAvoidBottomInset: false` (same rule as messages screen)
+- [ ] Thread screen Scaffold also uses `resizeToAvoidBottomInset: true` (same as messages screen)
 - [ ] SDK listeners update `_user`/`_group` for block/kick/scope changes
 - [ ] Colors from `CometChatThemeHelper`, cached in `didChangeDependencies()`
 - [ ] If using SDK listener mixins with `Action`, import UIKit `as cc` to avoid Flutter name conflict