docs(flutter): AI-agent docs layer — scoped LLM indexes, Quick References, and kit-vs-docs fixes - #483
Merged
raj-dubey1 merged 12 commits intoAug 25, 2026
Conversation
Every ```dart fence on ui-kit/flutter was compiled against the PUBLISHED
cometchat_chat_uikit 6.1.0. These three pages did not compile as written, so an
agent (or a developer) following them emits code that does not build.
guide-threaded-messages.mdx
- CometChatThreadedHeader(message:) -> (parentMessage:, loggedInUser:). `message`
is not a parameter and BOTH of the others are required.
- onThreadRepliesClick signature: the typedef is
void Function(BaseMessage, BuildContext, {CometChatMessageTemplate? template}).
- summary table repeated the wrong parameter.
threaded-messages-header.mdx
- onThreadRepliesClick optional named arg is `template`, not `bubbleView`.
- REMOVED the onBack and onError sections — CometChatThreadedHeader has neither.
Replaced with the host-owned navigation pattern (a pushed route gets its back
button from the screen's AppBar), plus a messageActionView example, which is
the callback the widget actually exposes.
- Bubble View: the widget has no `bubbleView` parameter — that lives on
CometChatMessageTemplate, passed via `template`. Rewrote the example.
- Style: backgroundColor/replyCountTextColor ->
bubbleContainerBackGroundColor/countTextColor.
search.mdx
- onConversationItemClick/onMessageItemClick -> onConversationClicked/
onMessageClicked (8 occurrences incl. section headings).
- conversationItemView parameter ORDER was reversed: the signature is
Widget? Function(BuildContext, Conversation).
- messageItemView does not exist — message results are overridden per TYPE
(searchTextMessageView / searchImageMessageView / searchVideoMessageView /
searchFileMessageView / searchAudioMessageView), each (BuildContext, message).
- onError used e.message; OnError = Function(Exception e) has no .message.
- Style: searchBoxBackgroundColor/searchBoxBorderRadius ->
searchBackgroundColor/searchBorderRadius.
All 22 fences on these three pages now compile clean.
Also adds FLUTTER-V6-DOCS-AUDIT.md — the full sweep: 374 fences across all 54
pages, 90 errors on 26 pages (6 of them expected on upgrading-from-v5, which
intentionally shows v5 code). The errors are dominated by systematic patterns
rather than one-off typos:
17 view slots missing the trailing BuildContext v6 added
17 undefined symbols (CometChatErrorAlertStyle, CometChatConfig, ...)
13 undefined named parameters (renamed style/props)
10 onError handlers using e.message on a plain Exception
6 stale package:cometchat_uikit_shared imports
4 CometChatUIKit.getDataSource() — removed with the v6 DataSource architecture
The remaining pages are NOT fixed in this commit; the audit lists them with
counts so they can be worked through deliberately.
Recommend adding a snippet compile pass to docs CI — the engine used here
(typecheck-fences-dart.mjs in cometchat-skills) found all 90 in one run and
filters host placeholders, so it is CI-safe.
Completes the sweep started in db83207. Every ```dart fence on all 54 ui-kit/flutter pages was compiled against the published cometchat_chat_uikit 6.1.0; each fix was re-compiled before commit. 352 of 374 fences now compile clean and 0 kit-API errors remain (the 22 uncounted are multi-expression illustrative blocks that do not parse standalone; the tool lists them on every run rather than dropping them silently, and spot-checks confirmed they use real APIs). upgrading-from-v5 is excluded by design — its "before" snippets are v5. Systematic fixes: - View slots gained a trailing BuildContext in v6; docs showed v5 arity (17). On message-header the first two params were ALSO swapped — the real signature is (Group?, User?, BuildContext) while the docs named them (user, group), which is why user.status / group.membersCount looked broken. Both fields are real; only the names were wrong. - onError handlers used e.message where the typedef is Function(Exception e) (10). getting-started deliberately untouched — init/login's onError really is CometChatException, so error.message is correct there. - getDataSource() -> MessageTemplateUtils (removed with the v6 DataSource). - CometChatUIKit.blockUsers/unblockUsers -> CometChat.blockUser/unblockUser (singular, still list-taking). - onSelection takes one argument; onItemTap is (context, item) on Users/Groups but (item) on Conversations/GroupMembers — the kit itself is inconsistent, so each page now matches its own widget. - CometChatMessageOption.onClick -> onItemClick(message, state). - Renamed style/props: searchBox*->search*, replyCountTextColor->countTextColor, groupMembersStyle->style, leadingView->leadingStateView, errorAlertStyle->attachmentErrorAlertStyle; dropped declineButtonText and messageHeaderBloc/typingIndicatorStyle/onError, which do not exist. - Non-existent symbols: CometChatCallLogDetails, CometChatErrorAlertStyle, CometChatAttachmentErrorSnackBarStyle, CometChatConstants (-> CometChatCallType / CometChatUserStatus), CometChatAiAssistantBubbleStyle (real class capitalises AI). Structural rewrites: - search: conversationItemView had its parameters REVERSED; messageItemView does not exist (results override per type: searchTextMessageView, searchImage...). - threaded-messages-header: no bubbleView on the widget (it is on CometChatMessageTemplate via `template`), no onBack/onError. - custom-text-formatter-guide: the example subclassed an abstract class without its five required members and used a getFormattedText / CometChatTextFormatterResult API that does not exist — rewritten against the real getAttributedText / AttributedText. - localize: mixed an aliased import with unprefixed symbols and imported package:cometchat_uikit_shared, which no longer resolves. FLUTTER-V6-DOCS-AUDIT.md updated with the before/after and the exact CI command.
…MessageSent The v6 Events page kept the subscription boilerplate but lost the per-event list that v4 and v5 both carry, so a reader could see how to attach a listener but not what there was to listen for. - restores all seven CometChatMessageEvents entries - documents the emit direction: a message sent with CometChat.send*Message rather than through CometChatMessageComposer must emit ccMessageSent, or an already-mounted CometChatMessageList never shows it (CometChat does not deliver a client its own sends over the real-time listener, so the list only picks them up on its next fetch - invisible when a chat screen is opened fresh each time, visible as soon as a list stays mounted) - notes the MessageStatus name collision: ccMessageSent takes the core constants enum, the barrel exports a different enum of the same name, so the import needs a prefix - for overriding as well as emitting - adds the missing flutter/material import to the listener example Snippets compiled against cometchat_chat_uikit 6.1.0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
The v6 Flutter pages documented 150 props across the twelve component tables. The widgets actually expose 494. An agent reading these pages either invented a prop name that would not compile or missed a capability the kit already ships and hand-rolled it. Tables are now generated from the pinned cometchat_chat_uikit 6.1.0 and each prop is verified against the analyzer before being listed, so nothing here is a guess. - 150 -> 494 documented props across 12 pages - 127 existing hand-written descriptions preserved; only type and default were taken from source, so no editorial work was lost - 23 documented props REMOVED - the analyzer reports them as undefined on the widget (showBackButton/placeholder on Search, disableTypingIndicator and hideUserStatus on MessageHeader, title and hideMessageComposer on ThreadedHeader, and others). Same defect class as the earlier thread/search signature fixes - 2 genuine type corrections: MessageHeader.backButton is a WidgetBuilder, not a Widget; Conversations.disableSoundForMessages is nullable Only the widget's own table was touched. Filter, style and option-visibility tables on the same pages describe request builders and style objects and were left alone. 158 rows land with no description - neither the page nor the kit's /// comments had one. Those are listed as a writing worklist; filling them in on the kit fields is preferable, since the generator harvests those comments. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…istener removal From an inventory of barrel-exported members that appear nowhere in the docs. events.mdx: - NEW Call Events section. The page had none at all, so ccOutgoingCall, ccCallAccepted, ccCallRejected and ccCallEnded were undiscoverable along with addCallEventsListener/removeCallEventsListener - Message Events: onFormMessageReceived, onSchedulerMessageReceived, onCustomInteractiveMessageReceived - Conversation Events: ccUpdateConversation, with the override in the example - UI Events: requestComposerFocus, lockBottomPadding, unlockBottomPadding connection-status.mdx: - removeConnectionListener documented; the page explained how to add a connection listener and never how to remove one - fixed the snippet's own typo, addConnctionListener -> addConnectionListener Every signature compiled against cometchat_chat_uikit 6.1.0 and cometchat_sdk 5.0.6: the four call events, the three message callbacks, ccUpdateConversation and the three UI events were all implemented against their real mixins in a probe that analyzes clean. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Found by the new docs-grounding linter: cometchat-flutter-v6-customization asserted that CometChatTheme is now only a mergeThemeExtensions helper, and the docs never mentioned the method - a RULES.md 20 violation that predates the linter and that nothing would have caught. Documented rather than labelled as a stopgap, because the claim is correct and the API is genuinely useful: assigning extensions: replaces whatever an ancestor ThemeData provided, so theming a subtree silently drops inherited extensions unless you merge. CometChatTheme holds no palette of its own; the helper is the whole class. Snippet compiled against cometchat_chat_uikit 6.1.0. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Flutter was the only platform with none. On the skills-v5-temp base, react has 128 Quick References and 3 llms indexes, android 112/2, angular 81/1, react-native 56/2, ios 34/2 - and flutter 0 and 0. This closes the index half. Structure and conventions follow the reference PRs for the same feature: cometchat#446 (React v7), cometchat#466 (JS SDK), cometchat#471 (Angular v5), cometchat#476 (React Native). Unlisted rather than hidden, for the reason those PRs give: in Mintlify hidden auto-applies noindex, which would drop the page from search and from the auto global llms.txt - and the whole point is that an agent can discover it. Not registered in docs.json, same as every prior index. ui-kit/flutter/llms-flutter-v6.mdx 70 links, all 54 UI Kit pages sdk/flutter/llms-flutter-v5.mdx 58 links, all 52 SDK pages Both are 100 percent page coverage with zero dead links, verified by resolving every href against the tree. The Platform rules section is the part that carries real weight, and every claim in it was verified against cometchat_chat_uikit 6.1.0 rather than recalled: - TWO barrels with different surfaces. Chat widgets do not resolve from the calls barrel and vice versa, so a screen showing both imports both. This is the most common Flutter-specific compile failure. - Lists need a bounded box or layout throws at render, not at build. - Kit widgets paint their own surface; the app ThemeData does not reach inside. - Theming is ThemeExtension, and registering on only one of light/dark silently leaves the other on kit defaults. - v5's CometChatUIKit.getDataSource() is gone; v6 uses MessageTemplateUtils. - Custom message types need addTemplate, not templates - templates only registers the bubble and the message is filtered out before it can render, with no error. A hand-rolled MessagesRequestBuilder does not help because the list always overrides uid/guid/types/categories on it. - Messages sent with CometChat.send*Message must emit ccMessageSent or a mounted list never shows them. - SDK: onSuccess AND onError are both required - compile-checked, omitting onError is missing_required_argument. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ent pages Flutter had 0 of these while react has 128, android 112, angular 81, react-native 56 and ios 34. This closes the UI Kit half. Format follows the reference PRs (cometchat#446, cometchat#466, cometchat#471, cometchat#476): an Accordion straight after the frontmatter, a Field/Value table, and rows that let an agent decide whether the page is worth opening at all. Generated from the compiler-verified prop tables rather than hand-written, so every prop named here provably exists on the widget and the row cannot drift from the kit on the next release. 35 in-page anchors, all resolving. Two rows are Flutter-specific and are the reason a generic template would not have done: - Import carries the RIGHT BARREL per widget. Calling widgets resolve only from cometchat_calls_uikit.dart, so call-buttons, incoming-call, outgoing-call and call-logs also get an explicit Barrel row saying so. Importing a calling widget from the chat barrel is the most common Flutter compile failure and no other platform has this split. - Layout warns that list widgets fill their parent and need an Expanded or a sized box, because the failure is an unbounded-height throw at render rather than a build error. Plus the two traps found by building on the kit: message-list carries the addTemplate-not-templates rule, and message-composer carries the ccMessageSent requirement for messages sent outside it. Classification is by TYPE, not name, after three passes got it wrong: messagesRequestBuilder ends in Builder but is data, hideThreadView ends in View but is a bool toggle, headerView is a HeaderFooterBuilder typedef with neither Widget nor Function in its name, and onError is typed OnError? so only the on-plus-capital convention identifies it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…ree broken snippets fixed Completes the Quick Reference set for Flutter: 14 UI Kit pages landed earlier, 38 SDK pages here - the same count React Native shipped. Key methods and Key classes are extracted from each page's OWN dart fences and ranked by how often the page uses them, so the rows describe what the page actually teaches rather than a generic API list. Every extracted method was then put to the analyzer, and that is what turned up the snippet bugs below. 263 links and reference anchors, all resolving. The Constraints row carries the one thing true of nearly every call on this platform and that no Promise-based SDK's docs can say: onSuccess and onError are BOTH required, and awaiting the call alone gives you nothing to act on. Three phantom methods the pages documented, none of which exist on CometChat: - login-listeners: addLoginListener -> addloginListener. The SDK really does spell it with a lowercase l while removeLoginListener uses a capital L, so the page's snippet could not compile. Added a note, because the inconsistency is surprising enough that a reader will assume the doc is the typo. - reactions: removeMessageReactionListener -> removeMessageListener. The page registers a MESSAGE listener and then removed a reaction listener that has never existed; reaction events arrive through the message listener. - receive-messages: getUnreadMessageCountForUser does not exist on Flutter at all - there is no per-user variant, only ForAllUsers and ForGroup. Replaced the two pseudo-code snippets (they were positional, the real API is named parameters) with getUnreadMessageCountForAllUsers plus a map lookup. markAsUnread was flagged too but is correct in place: it appears in upgrading-from-v4-guide only as a note that v5 removed it. Worth noting these survived the earlier 90-to-0 audit because that gate ran over ui-kit pages only; the SDK pages have never been compile-checked. All three replacements compile against cometchat_sdk 5.0.6. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…te at sdk pages The 90-to-0 audit ran over ui-kit pages only. Pointing the same Tier-2 gate at sdk/flutter found six kit-API errors; two were correct-as-written and four were real. reactions.mdx was written against an API that does not exist: - message.getReactions() -> message.reactions. getReactions() exists only on internal request/API classes, never on BaseMessage. Also .reactions is non-nullable, so no null-aware access is needed. - MessageReaction is not a class in this SDK. ReactionRequest.fetchNext returns List<Reaction>, so the loop variable and the updateMessageWithReactionInfo parameter are both Reaction. Fixed the two loops, the prose, and the helper snippet. delivery-read-receipts.mdx: markConversationAsDelivered and markConversationAsRead each take TWO positional arguments (conversationWithId, conversationType) plus required onSuccess/onError. Both snippets passed a single Conversation object, which cannot compile. Replaced with the id plus CometChatConversationType form. Correct as written, left alone: the two upgrading-from-v4-guide errors are Before-v4 snippets demonstrating removed APIs, exactly like upgrading-from-v5 on the ui-kit side. That page needs the same --exclude the ui-kit gate already gives its migration page. After the fixes: 52 files, 163 fences, 139 analyzed, 0 kit-API errors. 24 fences still parse in no shape and are NOT checked - a real coverage gap on this page set, not a pass. Every replacement compiles against cometchat_sdk 5.0.6. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
…Kit pages Correcting an earlier claim. I said the Quick Reference set was closed after the 14 component pages; rechecking against the platforms in the reference PRs shows it was not. Measured on CURRENT-version pages only - earlier counts were inflated by v4/v5 archive subdirectories that git grep matched recursively: ui-kit/react-native 56 of 56 sdk/react-native 44 of 54 ui-kit/ios 34 of 52 sdk/ios 52 of 61 ui-kit/android 33 of 62 sdk/android 46 of 55 ui-kit/react 29 of 40 ui-kit/flutter 14 of 54 <- lowest of any platform React Native has one on every single UI Kit page, guides and hubs included, so component-only coverage was not the convention. This takes flutter to 54 of 54. Non-component pages get page-appropriate rows rather than a fixed schema, which is what the other platforms do: guides name Key widgets, Init and Related; theming names the mechanism and its constraints; hub pages route. Classes and methods are extracted from each page's own fences and ranked by use, with a fallback to inline code spans for the seven hub pages that carry no fences at all - a stub block on those would have been worse than none. Six pages carry a hand-written row for something no extraction can know: theme-introduction and component-styling explain that a kit widget paints its own surface so the app ThemeData never reaches inside; message-template carries the addTemplate-not-templates rule; customization-datasource records that getDataSource is gone in v6; events carries the ccMessageSent requirement; and upgrading-from-v5 notes its Before snippets are v5 and are meant not to compile. 122 links and anchors across the 54 blocks, all resolving. Fence gate still clean at 355 analyzed, 0 kit-API errors. sdk/flutter stays at 38 of 52 by design: the 14 without a block are conceptual and hub pages, which cometchat#476 deliberately left alone on React Native for the same reason. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Closes the known gap this PR shipped with. Every prop row on the twelve component pages now carries a description; there are zero "—" cells left. CometChatMessageList 64 CometChatSearch 35 (was 35 of 35 empty) CometChatGroupMembers 34 CometChatUsers 25 The descriptions are not written into the pages by hand. They come from /// comments added to the kit fields themselves in cometchat-team/chat-uikit-flutter#581, and the table generator harvests them - so the docs pick up future edits on the next run instead of drifting from the kit. That PR takes the kit to 1033 of 1033 constructor fields documented across 81 widgets, so the same regeneration will fill descriptions well beyond these twelve pages once it lands. Tables stay pinned to the published 6.1.0 API. Only descriptions were taken from the newer source; no field was added, removed or retyped, so the pages continue to describe the version people actually have. Existing hand-written descriptions were left alone - only cells reading "—" were touched. One thing worth noting for anyone regenerating: the harvest keeps the whole /// comment when it fits a table cell rather than cutting at the first sentence. Cutting lost the half that mattered on the props that most need it - addTemplate read "Merges templates with the defaults." and dropped the clause explaining that it also folds the type into the fetch filter, which is the entire reason to prefer it over templates. Fence gate clean at 355 analyzed, 0 kit-API errors. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Everything Flutter needs for the v6 skills pack to route through the docs, plus the kit-vs-docs
corrections found while building on the pack.
Structure and conventions follow the reference PRs for the same feature: #446
(React v7), #466 (JS SDK), #471 (Angular v5), #476 (React Native).
1. Scoped LLM indexes
ui-kit/flutter/llms-flutter-v6.mdx— 70 links, all 54 UI Kit pagessdk/flutter/llms-flutter-v5.mdx— 58 links, all 52 SDK pagesUnlisted rather than hidden, for the reason #446/#466/#471 give: in Mintlify
hiddenauto-appliesnoindex, which would drop the page from search and from the auto global llms.txt. Not registered in
docs.json, same as every prior index. Zero dead links — every href was resolved against the tree.The Platform rules section is the part that carries weight, and every claim was verified against
cometchat_chat_uikit 6.1.0rather than recalled. The one with no equivalent on any other platform:two barrels with different surfaces. Chat widgets do not resolve from
cometchat_calls_uikit.dartand calling widgets do not resolve fromcometchat_chat_uikit.dart, soa screen showing both imports both. It is the most common Flutter-specific compile failure.
2. AI Integration Quick References
54 of 54 UI Kit pages · 38 of 52 SDK pages.
Flutter had none. React Native carries one on every UI Kit page, so component-only coverage was not
the convention.
provably exists and the rows cannot drift from the kit on release.
Importcarries the rightbarrel per widget, and the four calling widgets get an explicit
Barrelrow.The 14 SDK pages without a block are conceptual and hub pages — #476 left the React Native
equivalents alone for the same reason.
3. Fixes found by auditing the kit against the docs
Every symbol verified by compiling against the shipped kit and SDK.
UI Kit — 90 kit-API errors across 26 of 54 pages, now 0. Wrong parameter names, wrong callback
signatures, and params that do not exist (
CometChatThreadedHeader.onBack/onError, theonThreadRepliesClicksignature, non-existent search callbacks).Props: 150 documented → 494. The widgets expose 494; the pages documented 150. An agent either
invented a prop name that would not compile or missed a capability and hand-rolled it. Generated
from source and verified against the analyzer — which matters, because this kit declares
CometChatMessageListtwice and the copy carrying the nicer doc comments is the one the barrel doesnot export. 23 documented props removed as undefined on the widget; 2 real type corrections
(
MessageHeader.backButtonis aWidgetBuilder, not aWidget).Events — the v6 page dropped the per-event list that v4 and v5 both carry. Restored all seven
message events, added the missing Call Events section (four events and their listener
registration were undiscoverable),
ccUpdateConversation, and three UI events. Also documented theemit direction: a message sent with
CometChat.send*Messagerather than throughCometChatMessageComposermust emitccMessageSent, or an already-mountedCometChatMessageListnever shows it. That failure is invisible when a chat screen is opened fresh each time and appears
the moment a list stays mounted.
SDK snippets — the earlier audit ran over
ui-kitonly. Pointing the same gate atsdk/flutterfound seven more:
addLoginListener→addloginListener(the SDK really does spell it with a lowercaselwhileremoveLoginListeneruses a capitalL)removeMessageReactionListener→removeMessageListener(reaction events arrive on the messagelistener; the page registered one and removed another)
getUnreadMessageCountForUserdoes not exist on Flutter at all — there is no per-user variantmessage.getReactions()→message.reactions;MessageReactionis not a class in this SDKmarkConversationAsDelivered/markConversationAsReadeach take two positional argumentsmarkAsUnreadand theupgrading-from-v4-guideerrors were checked and left alone — they arecorrect in place, appearing only as notes about removed v4 APIs.
Verification
Known gaps, stated rather than hidden
nor the kit's own
///comments had prose. Best fixed on the kit fields: the generator harveststhose comments, so a source fix reaches the docs on the next run. Concentrated in
CometChatMessageList(64) andCometChatSearch(35/35).coverage — unverified, not verified. Four of the checked fences were broken, so I would expect
more in there.
upgrading-from-v4-guideneeds a gate--exclude, the same oneupgrading-from-v5alreadyhas on the UI Kit side.
CometChatMessageEvents.ccMessageSentis public API whoseparameter enum is not exported from the package barrel — and the barrel exports a different enum
of the same name — so the documented call needs an internal
src/import under a prefix. The pagecarries that workaround until the kit exports it.