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

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

@@ -293,6 +293,10 @@ class MessageListCoreState extends State<MessageListCore> {
     // If the channel is up to date, we don't need to reload it.
     if (_upToDate) return;
 
+    // Thread conversations share the parent channel; reloading from a
+    // disposing thread would clobber the channel page state.
+    if (_isThreadConversation) return;
+
     try {
       return await _streamChannel?.reloadChannel();
     } catch (_) {

packages/stream_chat_flutter_core/lib/src/stream_channel.dart

@@ -45,7 +45,30 @@ class StreamChannel extends StatefulWidget {
     this.initialMessageId,
     this.errorBuilder = _defaultErrorBuilder,
     this.loadingBuilder = _defaultLoadingBuilder,
-  });
+  }) : _shouldPosition = true;
+
+  /// Exposes a [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.
+  ///
+  /// 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 +88,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 +702,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 +844,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?) {