fix: settle a thread stranded outside its scroll range

[divyanshub024]

Summary

Fixes the thread stranding at a scroll offset outside its range: the newest message clipped under the list's bottom edge with blank space beneath (a short, fitting thread), or a blank band above the oldest (a long one).

• Flutter keeps an offset that has already left the range. RangeMaintainingScrollPhysics stops enforcing the boundary once a position is out of range and carries the overshoot as the range shrinks; only the next gesture's ballistic pulls it back. The keyboard is the way in: a drag dismisses it (the default keyboardDismissBehavior), the viewport grows mid-gesture while a reply is still growing, and the range collapses under the offset.
• FlowThread now clamps an idle position back into range. It runs on every metrics change and on every scroll end, since the range collapses mid-gesture (when a jump would fight the physics) and a gesture merely ending changes no metrics. Each covers the other's blind spot.
• The list gets its own controller when the host passes none; the correction needs a position. A host sharing one controller across lists opts out of the settle.

Screenshots

Interaction only; the fix removes a broken state rather than changing a drawn one. The original report's screenshot (reply cut mid-screen, blank below) is the before.

How this was verified

• iPhone 17 Pro simulator, example app: send with the keyboard up, drag the thread to dismiss it while the reply streams; the reply stays pinned above the composer, and the settled thread reads from the top. Repeated with a long thread.
• flutter analyze clean at the root and in example/ and playground/; dart format . applied.

Checklist

• flutter analyze lib and flutter analyze in example/ and playground/ are clean
• dart format . applied
• Exercised in the playground — with a stage demo added or updated if this is a new component or variant
• Any new entry under dependencies: in pubspec.yaml is flutter.dev-published, forces no configuration on hosts that never use the feature, and is argued in this PR
• Nothing model-facing — no prompts, schemas, or provider/network calls
• New public API is exported from lib/flow_ui.dart and documented in docs/ and the README table
• CHANGELOG.md updated for user-facing changes, with breaking changes called out
• PR title follows conventional commits (feat:, fix:, refactor:, docs:, chore:)

---

Note

Low Risk
Localized scroll-position correction in the thread widget; avoids fighting in-flight scroll physics with explicit guards.

Overview
Fixes FlowThread leaving the conversation scrolled to an invalid offset after the viewport grows (e.g. keyboard dismissed on drag while a reply is still streaming), which could clip the newest message or show blank space above the oldest.

Adds _settleIfOff: when metrics show the list idle and outside range (with a small tolerance), it jumpTo-clamps pixels between min/max extent on the post-frame callback, skipping active gestures and duplicate work via _settling. Settlement runs from ScrollMetricsNotification (inside existing _handleMetrics) and a new outer ScrollEndNotification listener so mid-gesture range collapse and gesture-end cases are both covered. Position is resolved from the notification’s ScrollableState, so hosts can keep sharing an external ScrollController.

CHANGELOG.md documents the user-facing fix.

^{Reviewed by Cursor Bugbot for commit 1ee0935. Bugbot is set up for automated code reviews on this repo. Configure here.}

[cursor]

Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.

^{❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.}

^{Reviewed by Cursor Bugbot for commit bc923e1. Configure here.}

[divyanshub024]

Folded into #37, which now targets main with these commits unchanged.