Files
pipelines/app/lib/features/chat/conversation/chat_scroll.dart
T
alan d02d5ea11d Chat transcript: wheel and trackpad scrolling always reaches the transcript
Root causes found in release web captures (1280x800 and 560x900):
- Follow mode undid small wheel/trackpad ticks at the end: each tick is its
  own scroll, re-judged as following within 32 px and jumped back. A user
  scroll toward older rows now releases the end however small; the jump
  control appears once streamed content moves the end beyond the threshold.
- The end-of-scroll jump ran inside the position's activity switch, so a
  touch or scrollbar drag released near the end recursed without end (stack
  overflow during the gesture). The jump now runs after the notification.
- Horizontally scrolling code blocks and tables claimed diagonal trackpad
  gestures whole. HorizontalScrollView gives mostly vertical gestures to the
  enclosing list; sideways and Shift + wheel still scroll the block.
- The wheel over the floating chat bar, composer and jump control moved
  nothing. VerticalWheelForwarder scrolls the transcript from them unless
  something under the pointer claims the event.

Adds widget tests per content kind and scroll mode, follow/touch/Load older
tests, a capture-kit check (tool/capture/examples/chat-wheel-scroll.json)
with eval/expect steps, wheel dx/repeat, --params and eval: targets, a
transcript scroll probe and fixture options, and fixes the kit ignoring a
script's size. Notes in notes/chat-wheel-scroll.md.
2026-11-02 20:37:36 +00:00

159 lines
6.3 KiB
Dart

import 'dart:math' as math;
/// How close the transcript's end must be to the viewport's bottom edge before
/// the view counts as following it. A deliberate position further up is the
/// operator's own and must never be snapped back by a streamed frame.
const double chatFollowThresholdPx = 32;
/// The pixels the transcript's end still sits below the viewport's bottom edge.
///
/// Zero means the end is in view; null means the list has no content to measure.
/// A viewport that is overscrolled past the end never reports a negative
/// distance, so following is a simple threshold check.
double? chatBottomDistance({
required double maxScrollExtent,
required double pixels,
required int itemCount,
}) {
if (itemCount <= 0) return null;
return math.max(0, maxScrollExtent - pixels);
}
/// Whether the end of the transcript is at (or within the follow threshold of)
/// the viewport's bottom edge.
bool chatFollowsAt(
double? distanceFromBottom, {
required int itemCount,
double threshold = chatFollowThresholdPx,
}) =>
itemCount > 0 &&
distanceFromBottom != null &&
distanceFromBottom <= threshold;
/// Whether the view follows the end after the operator's own scroll.
///
/// A scroll toward the end follows within the threshold, so landing close to
/// the end returns to it. A scroll toward older rows releases the end unless it
/// is still exactly there: a wheel or trackpad scroll arrives as separate small
/// ticks, and treating each one as "close enough" would pin the view.
bool chatFollowsAfterScroll(
double? distanceFromBottom, {
required int itemCount,
required bool towardOlder,
double threshold = chatFollowThresholdPx,
}) => chatFollowsAt(
distanceFromBottom,
itemCount: itemCount,
threshold: towardOlder ? chatAtEndTolerancePx : threshold,
);
/// How far from the end still counts as at the end, for rounding only.
const double chatAtEndTolerancePx = 0.5;
/// Whether to offer the jump-to-latest control: only while the view is not
/// following and something is below the fold. A list that fits its viewport is
/// never offered the control, because there is nothing to return to.
bool chatShowsJumpToLatest({
required bool following,
required double? distanceFromBottom,
required int itemCount,
double threshold = chatFollowThresholdPx,
}) =>
!following &&
itemCount > 0 &&
!chatFollowsAt(
distanceFromBottom,
itemCount: itemCount,
threshold: threshold,
);
/// How many messages arrived after the operator left the bottom.
///
/// [newestAtRelease] is the id of the last message at the moment the operator
/// scrolled away. Only messages after that id count, so an older page that is
/// prepended while they read is not reported as an arrival and a delta growing
/// the held answer is not a new message. An id that no longer exists (a repair
/// replaced the transcript) reports no arrivals until the operator returns.
int chatNewMessageCount(List<String> messageIds, String? newestAtRelease) {
if (newestAtRelease == null) return 0;
final index = messageIds.lastIndexOf(newestAtRelease);
if (index < 0) return 0;
return messageIds.length - index - 1;
}
/// The jump control's words, with the web's action and the arrival count the
/// native client adds while the operator is reading above the end.
String chatJumpToLatestLabel(int newMessages) {
if (newMessages <= 0) return 'Jump to latest';
final suffix = newMessages == 1
? '1 new message'
: '$newMessages new messages';
return 'Jump to latest · $suffix';
}
/// Where a conversation's transcript is placed when it first shows.
///
/// No saved position means the operator has none of their own: open at the
/// newest content. A saved offset is kept, clamped to the current extent, so a
/// conversation whose content grew or shrank while it was closed still lands on
/// a real position. A bottom-anchored transcript measures older rows above its
/// centre, so its offsets (and [minScrollExtent]) can be negative.
double chatRestoreOffset({
required double? savedOffset,
required double maxScrollExtent,
double minScrollExtent = 0,
}) {
if (savedOffset == null) return maxScrollExtent;
return savedOffset.clamp(minScrollExtent, maxScrollExtent).toDouble();
}
/// A saved transcript position: the scroll offset and the message id of the
/// row the transcript was split at (see `chatTranscriptAnchor`), or null for a
/// top-anchored transcript whose offset counts from its first row. An offset
/// only means something measured from the same anchor.
typedef ChatScrollPosition = ({double offset, String? anchor});
/// Per-conversation transcript positions, kept while the chat list stays
/// mounted. A conversation opened again returns to the position the operator
/// left; one they never moved in opens at its newest message.
abstract interface class ChatScrollStore {
/// The position the operator left this conversation at, or null when they
/// never scrolled away from its end.
ChatScrollPosition? read(String sessionId);
/// Records a deliberate position away from the end.
void write(String sessionId, ChatScrollPosition position);
/// Forgets the position once the operator is following the end again.
void clear(String sessionId);
}
/// In-memory storage for the app's chat destination and for tests.
///
/// A surfaced position survives the conversation view being disposed and
/// reopened with the chat destination, but not a process restart. This native
/// client keeps no transcript position on disk and does not import the web's
/// storage keys.
class MemoryChatScrollStore implements ChatScrollStore {
final Map<String, ChatScrollPosition> _offsets = {};
/// A snapshot of the stored positions, so a test can tell a cleared
/// conversation from one that was never moved.
Map<String, ChatScrollPosition> get entries => Map.unmodifiable(_offsets);
@override
ChatScrollPosition? read(String sessionId) => _offsets[sessionId];
@override
void write(String sessionId, ChatScrollPosition position) {
// A top-anchored offset counts from the first row and is never negative;
// a bottom-anchored one is negative above its centre.
if (!position.offset.isFinite) return;
if (position.anchor == null && position.offset < 0) return;
_offsets[sessionId] = position;
}
@override
void clear(String sessionId) => _offsets.remove(sessionId);
}