fix(llc, core, ui): isolate channel state from sub-route wraps and smooth thread-open scroll

A small cluster of related issues that surfaced together while
investigating thread-page UX. All four are independent bugs touching
the LLC, core, and the vendored SPL.

- `Channel.getMessagesById` was merging fetched messages into
  `ChannelState.messages` as a side effect. Resolving a thread parent
  for an in-channel reply would silently inject the parent into the
  loaded channel window, typically at index 0. The fetch is now pure
  — callers that want to refresh the loaded window can pipe the
  response through `ChannelClientState.updateMessage`.
- `StreamChannel.getMessage` previously hit the network for any
  message not in `channel.state.messages`, ignoring thread replies
  and pinned messages. Cache lookup now also scans
  `channel.state.threads.values` and `channel.state.pinnedMessages`.
- Added `StreamChannel.value` constructor for wrapping an
  already-initialized channel purely to expose it via
  `StreamChannel.of` to a sub-route or overlay (thread page, channel
  info screen, long-press modal, attachment viewer). Skips the
  channel-page positioning the default constructor runs, which would
  otherwise overwrite the parent route's loaded window.
- `MessageListCore` no longer reloads the parent channel from its
  dispose path when the disposing instance is in thread mode — a
  thread's lifecycle shouldn't be touching the channel's loaded
  window.
- `MessageListCore` no longer refetches thread replies on first
  attach when `state.threads[parentId]` is already populated.
  WebSocket events keep that cache live; the redundant fetch caused
  a merge-rebuild flicker on warm cache.
- `ScrollablePositionedList._startScroll` waits one frame for
  `itemPositions` to be published when it's empty. Previously a
  `scrollTo` requested from a post-frame callback right after mount
  would fall through to the dual-controller teleport path even for
  nearby targets, fake-scrolling two screens for what should have
  been a short animation. Matches the Compose `LazyListState`
  pattern of suspending until first composition before scrolling.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: xsahil03x

packages/stream_chat/CHANGELOG.md

@@ -8,6 +8,7 @@
 
 🐞 Fixed
 
+- Fixed `Channel.getMessagesById` mutating the loaded channel window as a side effect of fetching.
 - Fixed `StreamChatClient.queryDrafts` not forwarding the `filter` argument to the API.
 
 - Coalesced concurrent `queryChannels` calls with identical parameters via an in-flight cache.

packages/stream_chat/lib/src/client/channel.dart

@@ -1801,10 +1801,7 @@ class Channel {
     List<String> messageIDs,
   ) async {
     _checkInitialized();
-    final res = await _client.getMessagesById(id!, type, messageIDs);
-    final messages = res.messages;
-    state!.updateChannelState(state!.channelState.copyWith(messages: messages));
-    return res;
+    return _client.getMessagesById(id!, type, messageIDs);
   }
 
   /// Translate a message by given [messageId] and [language].

packages/stream_chat_flutter/CHANGELOG.md

@@ -2,6 +2,9 @@
 
 🐞 Fixed
 
+- Fixed `ScrollablePositionedList.scrollTo` taking the long-distance teleport path when called
+  immediately after mount (before `itemPositions` had been published). It now waits one frame
+  for layout, then animates the real pixel distance.
 - Fixed `StreamMessageListView` not auto-scrolling to the bottom on the user's own outgoing message
   until the server confirmed it.
 - Fixed `StreamMessageListView` tripping `A RenderViewport exceeded its maximum number of layout

packages/stream_chat_flutter/lib/scrollable_positioned_list/src/scrollable_positioned_list.dart

@@ -750,6 +750,16 @@ class _ScrollablePositionedListState extends State<ScrollablePositionedList>
     Curve curve = Curves.linear,
     required List<double> opacityAnimationWeights,
   }) async {
+    // If `itemPositions` hasn't been published yet (e.g. a scroll requested
+    // from a post-frame callback right after mount), the in-viewport branch
+    // below would miss the target and fall through to the dual-controller
+    // teleport path — even when the target is actually a few items away.
+    // Wait one frame so layout can report positions, then proceed.
+    if (primary.itemPositionsNotifier.itemPositions.value.isEmpty) {
+      await SchedulerBinding.instance.endOfFrame;
+      if (!mounted) return;
+    }
+
     final direction = index > primary.target ? 1 : -1;
     final itemPosition =
         primary.itemPositionsNotifier.itemPositions.value.firstWhereOrNull(

packages/stream_chat_flutter_core/CHANGELOG.md

@@ -1,7 +1,16 @@
 ## Upcoming
 
+✅ Added
+
+- Added `StreamChannel.value` — exposes an already-initialized channel without running channel-page
+  positioning. Use it for sub-route and overlay wraps.
+
 🐞 Fixed
 
+- Fixed `StreamChannel.getMessage` hitting the network for thread replies and pinned messages
+  already in local state.
+- Fixed `MessageListCore` reloading the parent channel from its dispose path when running in
+  thread mode.
 - Fixed `StreamChannel.reloadChannel` merging the latest page on top of the previously loaded
   window instead of replacing it. The reload now matches a fresh open of the channel.
 

packages/stream_chat_flutter_core/lib/src/message_list_core.dart

@@ -305,7 +305,7 @@ class MessageListCoreState extends State<MessageListCore> {
   @override
   void dispose() {
     _teardownController(widget.messageListController);
-    _reloadChannelIfNeeded();
+    if (!_isThreadConversation) _reloadChannelIfNeeded();
     super.dispose();
   }
 }

packages/stream_chat_flutter_core/lib/src/stream_channel.dart

@@ -45,7 +45,33 @@ class StreamChannel extends StatefulWidget {
     this.initialMessageId,
     this.errorBuilder = _defaultErrorBuilder,
     this.loadingBuilder = _defaultLoadingBuilder,
-  });
+  }) : _shouldPosition = true;
+
+  /// Exposes an already-initialized [channel] to descendants without
+  /// repositioning the loaded window on mount.
+  ///
+  /// Use this when wrapping a channel in a sub-route or overlay for context
+  /// access only — e.g. a thread page, channel info screen, long-press
+  /// modal, or attachment viewer. The default constructor would otherwise
+  /// re-run channel-page positioning and overwrite the parent route's
+  /// loaded window.
+  ///
+  /// The [channel] must already be initialized via [Channel.watch];
+  /// descendants depend on `channel.state` being non-null.
+  ///
+  /// See also:
+  ///
+  ///  * [StreamChannel.new], which initializes the channel and positions it
+  ///    on mount.
+  const StreamChannel.value({
+    super.key,
+    required this.child,
+    required this.channel,
+  })  : showLoading = false,
+        initialMessageId = null,
+        errorBuilder = _defaultErrorBuilder,
+        loadingBuilder = _defaultLoadingBuilder,
+        _shouldPosition = false;
 
   /// The child of the widget
   final Widget child;
@@ -65,6 +91,10 @@ class StreamChannel extends StatefulWidget {
   /// Widget builder used in case an error occurs while building the channel.
   final ErrorWidgetBuilder errorBuilder;
 
+  // Whether to position the loaded window on mount (initialMessageId,
+  // last-read, or latest). Only false for StreamChannel.value.
+  final bool _shouldPosition;
+
   static Widget _defaultLoadingBuilder(BuildContext context) {
     final backgroundColor = _getDefaultBackgroundColor(context);
     return Material(
@@ -675,16 +705,43 @@ class StreamChannelState extends State<StreamChannel> {
     );
   }
 
-  ///
+  /// Returns the message with the given [messageId].
   Future<Message> getMessage(String messageId) async {
-    var message = channel.state?.messages.firstWhereOrNull(
-      (it) => it.id == messageId,
+    if (_findCachedMessage(messageId) case final cached?) return cached;
+
+    final response = await channel.getMessagesById([messageId]);
+    return response.messages.firstWhere(
+      (m) => m.id == messageId,
+      orElse: () => throw StateError('Message "$messageId" not found'),
     );
-    if (message == null) {
-      final response = await channel.getMessagesById([messageId]);
-      message = response.messages.first;
+  }
+
+  // Scans cached locations in decreasing hit-likelihood, returning on the
+  // first match. Plain for-loops over `firstWhereOrNull`/`expand` to avoid
+  // per-call closure and iterable allocations.
+  Message? _findCachedMessage(String messageId) {
+    final state = channel.state;
+    if (state == null) return null;
+
+    // Hot path: regular channel messages in the loaded window.
+    for (final message in state.messages) {
+      if (message.id == messageId) return message;
     }
-    return message;
+
+    // Thread replies — only helps when `messageId` is itself a reply; thread
+    // parents live in `state.messages`, not under `state.threads`.
+    for (final replies in state.threads.values) {
+      for (final message in replies) {
+        if (message.id == messageId) return message;
+      }
+    }
+
+    // Pinned messages can sit outside the loaded window, so check them last.
+    for (final message in state.pinnedMessages) {
+      if (message.id == messageId) return message;
+    }
+
+    return null;
   }
 
   /// Query channel members.
@@ -790,6 +847,10 @@ class StreamChannelState extends State<StreamChannel> {
     // Otherwise, we first initialize the channel if it's not yet initialized.
     if (channel.state == null) await channel.watch();
 
+    // If the widget was created using the StreamChannel.value constructor,
+    // we skip positioning so the already-loaded channel state is kept intact.
+    if (!widget._shouldPosition) return;
+
     // First we try to load the channel at the initial message if
     // 'initialMessageId' is provided in the widget.
     if (widget.initialMessageId case final initialMessageId?) {