Roadmap: path to the go-to Flutter chat package (audit follow-ups)

[hooshyar]

Tracking issue from a full package audit. Thesis: this package already has the features (streaming, markdown, LaTeX, RTL, agents/actions, voice, rich widgets) — the differentiator for "go-to" status is trust: every documented knob works, no leaks, deps honest, docs match code. The dominant theme across the issue history is documented parameters that silently do nothing (#40, #30, #18, #20, #9, #38, #24, #28, #3, #6).

Status (updated 2026-09-03): Everything checked below has shipped, most of it through v2.17.0 (live on pub.dev). Current state: analyze --fatal-infos clean, 434 tests green (426 package + 8 example, the latter now running in CI for the first time), pub publish --dry-run clean, confirmed 160/160 pub points. See the comment below for a detailed progress update since the last one.

✅ Phase 0 — Trust & correctness

• Dead FileUploadOptions.fileDisplayBuilder (fileDisplayBuilder #40) — now threaded to MessageAttachment.
• AiContextController.watchNotifier listener leak → removed on dispose; returns a disposer.
• ContextAwareChatController disposes the sub-controllers it creates.
• TextPainter disposal on bubble-measure & ghost-overlay hot paths.
• SmartChatInput removes listeners on dispose.
• Packaging: .pubignore trims internal logs/dirs/images; pubspec screenshots: (verified 494 KB archive, heavy/internal files excluded).
• SDK floor corrected to Flutter >=3.27 / Dart >=3.6 (root cause of 报错，SDK^3.5.3;flutter_gen_ai_chat_ui: ^1.3.0 #7/Error: The method 'withValues' isn't defined for the class 'Color'. #12).
• Deprecation shims name a v3.0.0 removal target.
• Clean analyze on current stable (cacheExtent deprecation, unreachable switch default).

✅ Phase 0.5 — "Every parameter is wired" sweep

• customBubbleBuilder docs drift (customBubbleBuilder Invalid settings #18/customBubbleBuilder isn't defined #30): added MessageOptions.bubbleBuilder (4-arg, wraps defaultBubble) + README fix.
• scrollController (The parameter scrollController didn't use #20): confirmed wired.
• Finish the sweep across all remaining knobs + a test asserting each documented knob has a visible effect.

Phase 1 — Quality gates

• CI version-consistency guard (pubspec ↔ README).
• Accessibility: localizable InputOptions.sendButtonTooltip on the icon-only send button (+test).
• Release automation: OIDC tag-triggered pub publish workflow.
• Golden tests (bubble / welcome / streaming / code-block / RTL).
• Broader a11y: tap-target sizing (send button <48dp) + full labeledTapTargetGuideline compliance.
• CI SDK matrix — resolved the dev/consumer floor discrepancy (see below) and, as a bonus, the matrix's floor leg found the documented Flutter floor was ALSO wrong for two unrelated dependency reasons; corrected to >=3.35.0.

Phase 2 — Developer experience & docs

• Cookbook (doc/cookbook/) with recipes for the recurring questions (Thinking bubble.. and Response #37, I want to keep the WelcomeMessage permanently. How can I achieve that? #8, reverse order of messages #19, Custome welcome message builder overlay issue #22, streaming, stop-generating, attachments fileDisplayBuilder #40, theming, RTL); all snippets verified against the API; linked from README.
• Example gallery: a demo screen per feature, plus a live web demo (deployed via GitHub Pages, auto-redeploys on push).
• Doc/code drift CI check — tool/check_doc_drift.dart, wired into CI.

Phase 3 — Feature leadership

• Brand theme presets CustomThemeExtension.chatgpt()/.claude()/.gemini() (+dark:) — the README headline as a one-liner (+test).
• First-class composite "thinking → streamed answer" message API (Thinking bubble.. and Response #37). (Pattern documented in cookbook; a dedicated factory is the next step.)
• Full attachments lifecycle: built-in lightbox/preview/multi-file/progress (builds on fileDisplayBuilder #40).
• Persistence + lazy pagination for long threads (Prevent AiChatWidget from auto-scrolling entire response into view — top of long replies gets hidden #13).
• Polished default renderers for the tool-call/agent surface.

Phase 4 — Ecosystem

• Provider adapters (OpenAI / Anthropic / Gemini / Ollama) as examples or sibling packages — wire a stream into ChatMessagesController in ~10 lines, keeping heavy deps out of core.

---

Audit + implementation generated with Claude Code.

[hooshyar]

Status update: the audit branch claude/flutter-package-audit-auwamr is now merged to main (83bb6ea), integrated with the newer streaming reveal-pacing fix and dependency upgrades. Verified post-merge: dart analyze --fatal-infos clean, dart format clean, 372 tests green, pub publish --dry-run passes at 501 KB (generated doc/api/ now excluded from the tarball).

Everything checked in Phase 0 / 0.5 / 1 / 2 / 3 above is on main targeting 2.15.0. The cacheExtent deprecation (the exact cause of the current 130/160 pub score — 30/50 on static analysis) is suppressed with a documented ignore since scrollCacheExtent requires Flutter 3.41+ while our floor is 3.27, so the score should recover to 150/160+ on the next publish.

Remaining unchecked items (golden tests, tap-target a11y, SDK-matrix CI, example gallery, doc-drift CI, composite thinking-message API, attachments lifecycle, pagination/persistence, agent renderers, provider adapters) roll forward as the post-2.15.0 backlog.

[hooshyar]

2.15.0 is published on pub.dev (2026-07-10) — everything checked above is now shipped. Phase 0, 0.5 (minus the full knob-sweep test), 1 (minus goldens/SDK-matrix), 2 (cookbook), and the Phase 3 brand presets are live. #40 closed.

Release-engineering notes from the publish:

• The OIDC tag-publish workflow authenticated fine but pub.dev rejected it: "publishing from github is not enabled" — the one-time enablement on pub.dev → package admin → Automated publishing (tag pattern v{{version}}) still needs doing before the next release can ship by tag. This release went out via local dart pub publish.
• Two publish blockers were found and fixed on main: an invalid tag glob made publish.yml fail on every push, and the root .gitignore self-ignoring .gitignore tripped pub's validation (fatal under --force).

Next up from the unchecked backlog, in leverage order: golden tests, tap-target a11y, the composite thinking→answer message API (#37), example gallery, provider adapters.

[hooshyar]

Progress update on Phase 0.5's knob sweep — "every documented parameter actually has a visible effect."

Systematic pass (script cross-referencing every declared field against test coverage, then manually verified against actual call sites, not just test presence) found and resolved 8 issues so far, all on main:

Fixed (real, wireable features that were silently no-ops):

• AiChatWidget.paginationConfig — the top-level shortcut was never read at all; pagination only worked via messageListOptions.paginationConfig.
• AiChatWidget.padding — "Padding around the entire widget" had zero effect.
• AiChatWidget.markdownStyleSheet — same bug shape as paginationConfig, never merged into the effective MessageOptions.
• LoadingConfig.typingIndicatorColor / .typingIndicatorSize — documented but never threaded into the actual typing-dots widget.
• PaginationConfig.enableHapticFeedback — never called HapticFeedback anywhere.

Deprecated (superseded or no longer meaningful, pointing at what actually works):

• AiChatWidget.aiName → use aiUser.name (always was the real source of truth).
• AiChatWidget.enableAnimation → each animation aspect now has its own dedicated flag (enableMarkdownStreaming, streamingWordByWord, streamingFadeInEnabled).
• PaginationConfig.loadingIndicatorOffset / .loadMoreIndicator → superseded by MessageListOptions.isLoadingMore / PaginationConfig.loadingBuilder.

Caught before it shipped: the #42 fix's first implementation used a persistent GlobalKey per message list item to measure scroll position — that crashed the moment the list was actually scrolled via jumpTo/drag (not just via animated Scrollable.ensureVisible, which is all the initial tests exercised). Replaced with a plain element-tree walk; added a permanent regression test. This never reached pub.dev.

All additive/deprecation-only, zero breaking changes. Test count: 372 → 388.

Remaining from the sweep: MessageOptions/InputOptions/CustomThemeExtension haven't had the same pass yet, and PaginationConfig.scrollThreshold is confirmed dead too but needs a deliberate design call (wiring it naively would change default load-more-trigger timing for long lists) rather than a blind fix. Will pick this back up after some of the other roadmap items below.

[hooshyar]

Progress update on Phase 0.5's knob sweep — the biggest finding yet.

CustomThemeExtension was a complete no-op. Theme.of(context).extension<CustomThemeExtension>() was called nowhere in the widget tree — the entire theme extension (all 11 color knobs) and by extension the README-marketed .chatgpt()/.claude()/.gemini() brand presets had zero visual effect, no matter what a consumer set on ThemeData.extensions. The existing test only verified the extension round-tripped through ThemeData, never that anything actually read it back out.

Fixed on main (fd8b661): wired as a fallback layer — chatBackground → the overall chat surface, messageBubbleColor/userBubbleColor/messageTextColor → bubbles and their text, inputBackgroundColor/inputBorderColor/inputTextColor/hintTextColor → the input field, sendButtonColor → the send button icon, backToBottomButtonColor → the scroll-to-bottom icon. Each is consulted only when the more specific BubbleStyle/MessageOptions/InputOptions value is unset, so explicit per-widget colors still win and nothing changes for existing consumers who haven't opted into a theme. Visually verified with a new golden (chatgpt_theme_preset.png) — compare against the existing default_bubble.png baseline.

Also this round: InputOptions.autocorrect was a real dead field (now wired), and deprecated 6 more confirmed-dead/superseded fields (InputOptions.textDirection/.inputTextDirection/.positionedLeft/.positionedRight/.positionedBottom/.positionedTop, MessageOptions.timestampSpacing/.maxReactions/.reactionSize/.enableQuickReply) — full reasoning in the CHANGELOG. Removed 2 fully dead duplicate ThemeProvider files found along the way.

This closes out the MessageOptions/InputOptions/CustomThemeExtension sweep that was left open from the last update. 425/425 tests green, will ship in the next release.

[hooshyar]

Progress update — a lot has shipped since the last comment, through v2.17.0 (live on pub.dev now).

Phase 1 — Quality gates, now complete:

• Golden tests (5 baselines: default bubble, welcome message, mid-stream, code block, RTL).
• Full a11y tap-target sweep: found and fixed 2 real icon-only targets under 48×48 (send button, scroll-to-bottom button) via empirical meetsGuideline testing.
• CI SDK matrix, and it earned its keep immediately: the floor leg found the documented Flutter floor (>=3.27.0) had never actually resolved for a real consumer — first because flutter_streaming_text_markdown needs characters >=1.4.0 (unavailable below Flutter 3.29.0), then, after fixing that, because google_fonts ^8.1.0's own floor is >=3.35.0 (the real binding constraint). Corrected to >=3.35.0 in 2.17.0. If you were on Flutter 3.27.x-3.34.x, flutter pub get was already failing on this package before today — this only makes the declared number honest.

Phase 2 — Docs/DX, now complete:

• Example gallery: added the 2 missing demo screens (attachments, voice input) and shipped a live web demo (GitHub Pages, auto-redeploys on every relevant push).
• Doc/code drift CI check (tool/check_doc_drift.dart): scans every README/AGENTS.md dart snippet for ClassName.member(...) calls and verifies each resolves to a real factory/named/static member in lib/ — the exact failure mode the historical ONBOARDING_AUDIT.md found by hand is now caught automatically.

Also since the last update:

• CustomThemeExtension complete-no-op bug fixed (mentioned in the prior comment, now released).
• Removed the shimmer dependency entirely (hand-rolled the loading-widget sweep effect) — was about to start costing pana dependency-freshness points.
• Added a real performance-benchmark suite (test/performance/) backing the README's throughput claims with actual numbers instead of unverified marketing copy.
• Confirmed 160/160 pub points on a clean, uncontended pana run.
• v2.16.2 and v2.17.0 both shipped through the now-working GitHub Actions OIDC auto-publish (no manual dart pub publish step).

Still open (Phase 3/4, lower urgency): the composite thinking→answer message API, full attachments lifecycle (lightbox/multi-file), long-thread persistence + lazy pagination (#13), agent/tool-call renderer polish, and provider adapter examples (OpenAI/Anthropic/Gemini/Ollama). Tracked in docs/AWARD-PLAN.md and the backlog/tasks/ decomposition, ranked by value/effort — will keep working through them in that order.

434 tests green (426 package + 8 example), analyze --fatal-infos clean, dart pub publish --dry-run clean.