From d02d5ea11d443d84d9971570c289d9236e0bc15c Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Mon, 2 Nov 2026 20:37:36 +0000 Subject: [PATCH] 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. --- .../chat/conversation/chat_scroll.dart | 20 ++ .../chat/conversation/chat_thread_view.dart | 73 ++++- .../ui/transcript/chat_markdown_view.dart | 9 +- .../ui/layout/wheel_scroll_forwarding.dart | 110 ++++++++ app/notes/chat-wheel-scroll.md | 60 ++++ .../chat/conversation/chat_scroll_test.dart | 25 ++ .../chat_thread_wheel_follow_test.dart | 160 +++++++++++ .../chat_thread_wheel_scroll_test.dart | 181 ++++++++++++ .../conversation/chat_wheel_fixtures.dart | 142 ++++++++++ .../layout/wheel_scroll_forwarding_test.dart | 181 ++++++++++++ app/tool/capture/README.md | 21 +- app/tool/capture/capture.mjs | 30 +- .../capture/examples/chat-wheel-scroll.json | 260 ++++++++++++++++++ app/tool/capture/page.mjs | 21 +- app/tool/perf/chat_scroll_fixture.dart | 152 ++++++++++ app/tool/perf/chat_scroll_probe.dart | 154 +++++++++++ app/tool/perf/perf_fixture.dart | 27 +- app/tool/search_selection_probe_entry.dart | 9 + 18 files changed, 1607 insertions(+), 28 deletions(-) create mode 100644 app/lib/ui/layout/wheel_scroll_forwarding.dart create mode 100644 app/notes/chat-wheel-scroll.md create mode 100644 app/test/features/chat/conversation/chat_thread_wheel_follow_test.dart create mode 100644 app/test/features/chat/conversation/chat_thread_wheel_scroll_test.dart create mode 100644 app/test/features/chat/conversation/chat_wheel_fixtures.dart create mode 100644 app/test/ui/layout/wheel_scroll_forwarding_test.dart create mode 100644 app/tool/capture/examples/chat-wheel-scroll.json create mode 100644 app/tool/perf/chat_scroll_fixture.dart create mode 100644 app/tool/perf/chat_scroll_probe.dart diff --git a/app/lib/features/chat/conversation/chat_scroll.dart b/app/lib/features/chat/conversation/chat_scroll.dart index e1df6f6d..9f7b93c0 100644 --- a/app/lib/features/chat/conversation/chat_scroll.dart +++ b/app/lib/features/chat/conversation/chat_scroll.dart @@ -30,6 +30,26 @@ bool chatFollowsAt( 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. diff --git a/app/lib/features/chat/conversation/chat_thread_view.dart b/app/lib/features/chat/conversation/chat_thread_view.dart index 9ded817f..cedbc475 100644 --- a/app/lib/features/chat/conversation/chat_thread_view.dart +++ b/app/lib/features/chat/conversation/chat_thread_view.dart @@ -35,6 +35,7 @@ import 'chat_thread_controller.dart'; import '../../../ui/adaptive/floating_bar_layout.dart'; import '../../../ui/adaptive/segmented_bar_overlay.dart'; import '../../../ui/layout/app_sheet_header.dart'; +import '../../../ui/layout/wheel_scroll_forwarding.dart'; import 'chat_reading_width.dart'; import 'chat_thread_header.dart'; import 'chat_transcript_anchor.dart'; @@ -211,6 +212,10 @@ class _ChatThreadViewState extends State { /// follow jumps never set it, so they cannot release the follow intent. bool _userScrolling = false; + /// The way the operator's current scroll last moved. A wheel tick or a + /// drag toward older rows is a deliberate release of the end, however small. + ScrollDirection _userDirection = ScrollDirection.idle; + /// The last measured offset. Kept separately because the scrollable can /// detach before this state is disposed; disposal still has to save where the /// operator was. @@ -434,6 +439,7 @@ class _ChatThreadViewState extends State { _distanceFromBottom = null; _newestAtRelease = null; _userScrolling = false; + _userDirection = ScrollDirection.idle; _restoring = false; _restoreOffset = null; _restoreMeasuredExtent = 0; @@ -516,10 +522,14 @@ class _ChatThreadViewState extends State { /// Adopts a measured position as the follow intent. Crossing out of the /// bottom records the newest message then, so only later arrivals are counted. - void _updateFollow(ScrollMetrics metrics) { + void _updateFollow(ScrollMetrics metrics, {bool towardOlder = false}) { final ids = _messageIds(); final distance = _distanceFor(metrics, ids.length); - final following = chatFollowsAt(distance, itemCount: ids.length); + final following = chatFollowsAfterScroll( + distance, + itemCount: ids.length, + towardOlder: towardOlder, + ); _distanceFromBottom = distance; _lastOffset = metrics.pixels; if (following == _following) return; @@ -651,6 +661,7 @@ class _ChatThreadViewState extends State { _scheduleFollow(); return false; } + if (!_following && !_userScrolling) _trackDistance(notification.metrics); if (!_following || _userScrolling || !_scroll.hasClients) return false; if (_scroll.position.pixels < _scroll.position.maxScrollExtent) { _scheduleFollow(); @@ -658,6 +669,22 @@ class _ChatThreadViewState extends State { return false; } + /// Keeps the measured distance current while the operator reads above the + /// end and content grows below them, so the jump control appears once the + /// end moves beyond the threshold (a release can start within it). + void _trackDistance(ScrollMetrics metrics) { + final ids = _messageIds(); + final distance = _distanceFor(metrics, ids.length); + bool shows(double? distance) => chatShowsJumpToLatest( + following: false, + distanceFromBottom: distance, + itemCount: ids.length, + ); + final changed = shows(distance) != shows(_distanceFromBottom); + _distanceFromBottom = distance; + if (changed) setState(() {}); + } + /// Follows only the transcript's own vertical scroll. A code fence's or /// table's horizontal scroll bubbles through this listener too and must not /// release the conversation's follow intent. @@ -667,27 +694,48 @@ class _ChatThreadViewState extends State { } if (notification is UserScrollNotification) { _userScrolling = notification.direction != ScrollDirection.idle; - if (_userScrolling) _abandonRestore(); + if (_userScrolling) { + _userDirection = notification.direction; + _abandonRestore(); + } } else if (notification is ScrollStartNotification) { if (notification.dragDetails != null) { _userScrolling = true; _abandonRestore(); } } else if (notification is ScrollUpdateNotification) { - if (_userScrolling) _updateFollow(notification.metrics); - } else if (notification is ScrollEndNotification) { if (_userScrolling) { - _updateFollow(notification.metrics); - _persistPosition(); - // Releasing a scroll within the threshold returns to the end, exactly - // like a follow check at the bottom of the web's wheel handler. - if (_following) _jumpToBottom(); + _updateFollow(notification.metrics, towardOlder: _towardOlder); } + } else if (notification is ScrollEndNotification) { + final user = _userScrolling; + final towardOlder = _towardOlder; _userScrolling = false; + _userDirection = ScrollDirection.idle; + if (user) { + _updateFollow(notification.metrics, towardOlder: towardOlder); + _persistPosition(); + // Releasing a scroll toward the end within the threshold returns to + // the end. A scroll toward older rows has already released it: every + // wheel or trackpad tick ends its own scroll, so snapping back here + // would undo each small tick and pin the view to the end. + // + // The jump waits for this notification to finish: a drag's or + // fling's end is reported while the position is still switching + // activities, and jumping inside it re-entered this handler without + // end (a stack overflow that left the gesture broken). + if (_following) { + scheduleMicrotask(() { + if (mounted && _following && !_userScrolling) _jumpToBottom(); + }); + } + } } return false; } + bool get _towardOlder => _userDirection == ScrollDirection.forward; + void _followLatest() { setState(() { _following = true; @@ -845,7 +893,7 @@ class _ChatThreadViewState extends State { ), ), ); - final column = FloatingBarOverlay( + final page = FloatingBarOverlay( bar: composerBar, child: SegmentedBarOverlay( bar: _header(context, inShellBar), @@ -1014,6 +1062,9 @@ class _ChatThreadViewState extends State { ), ), ); + // The bar, the composer and the jump control float over the transcript; + // the wheel over them scrolls it, as a page scrolls under fixed bars. + final column = VerticalWheelForwarder(controller: _scroll, child: page); if (!inShellBar) return column; // The conversation draws its own floating bar; the page shows none. final title = widget.title.trim(); diff --git a/app/lib/features/chat/ui/transcript/chat_markdown_view.dart b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart index 5f5b15d8..d456c1a3 100644 --- a/app/lib/features/chat/ui/transcript/chat_markdown_view.dart +++ b/app/lib/features/chat/ui/transcript/chat_markdown_view.dart @@ -4,6 +4,7 @@ import 'package:flutter/material.dart'; import 'package:flutter/semantics.dart'; import '../../../../ui/adaptive/host.dart'; +import '../../../../ui/layout/wheel_scroll_forwarding.dart'; import '../sessions/chat_adaptive.dart'; import 'chat_markdown.dart'; import 'chat_markdown_cache.dart'; @@ -183,8 +184,7 @@ class _ChatMarkdownViewState extends State { ), ); case MarkdownTable(header: final header, rows: final rows): - return SingleChildScrollView( - scrollDirection: Axis.horizontal, + return HorizontalScrollView( child: Table( defaultColumnWidth: const IntrinsicColumnWidth(), border: TableBorder.all(color: _dividerColor(context, cupertino)), @@ -224,10 +224,7 @@ class _ChatMarkdownViewState extends State { decoration: BoxDecoration(color: _codeFill(context, cupertino)), child: Padding( padding: const EdgeInsets.all(12), - child: SingleChildScrollView( - scrollDirection: Axis.horizontal, - child: Text(code), - ), + child: HorizontalScrollView(child: Text(code)), ), ), ], diff --git a/app/lib/ui/layout/wheel_scroll_forwarding.dart b/app/lib/ui/layout/wheel_scroll_forwarding.dart new file mode 100644 index 00000000..e3db313c --- /dev/null +++ b/app/lib/ui/layout/wheel_scroll_forwarding.dart @@ -0,0 +1,110 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter/widgets.dart'; + +/// Mouse-wheel and trackpad scrolling that reaches the page's vertical list. +/// +/// A [Scrollable] claims a pointer scroll event whenever its own axis' delta +/// can move it, and the first claim (the innermost) wins. Two cases follow +/// that make a vertical list feel stuck: +/// +/// * a horizontally scrolling code block or table takes a trackpad gesture +/// for its small sideways component, and the vertical part is dropped; +/// * controls floating over the list (a bar, a composer, a button) claim +/// nothing, so the wheel over them moves nothing. +/// +/// [HorizontalScrollView] and [VerticalWheelForwarder] hand those events to +/// the vertical list instead. + +/// Claims [event] for scrolling [position] by the event's vertical delta, +/// when that delta would move it. Returns whether it was claimed. +/// +/// The claim goes through the [PointerSignalResolver], so a scrollable deeper +/// under the pointer that claimed the event first keeps it. +bool claimVerticalWheel(PointerSignalEvent event, ScrollPosition position) { + if (event is! PointerScrollEvent) return false; + if (position.axis != Axis.vertical || !position.hasPixels) return false; + if (!position.physics.shouldAcceptUserOffset(position)) return false; + final dy = event.scrollDelta.dy; + final delta = axisDirectionIsReversed(position.axisDirection) ? -dy : dy; + if (delta == 0 || _target(position, delta) == position.pixels) return false; + GestureBinding.instance.pointerSignalResolver.register(event, (event) { + if (!position.hasPixels) return; + if (_target(position, delta) == position.pixels) return; + position.pointerScroll(delta); + (event as PointerScrollEvent).respond(allowPlatformDefault: false); + }); + return true; +} + +double _target(ScrollPosition position, double delta) => + (position.pixels + delta) + .clamp(position.minScrollExtent, position.maxScrollExtent) + .toDouble(); + +/// Whether [event] means to scroll sideways: a mostly horizontal gesture, or +/// a mouse wheel turned with the axis modifier (Shift) held. +bool isSidewaysWheel(BuildContext context, PointerScrollEvent event) { + final delta = event.scrollDelta; + if (event.kind == PointerDeviceKind.mouse) { + final modifiers = ScrollConfiguration.of(context).pointerAxisModifiers; + final pressed = HardwareKeyboard.instance.logicalKeysPressed; + if (pressed.any(modifiers.contains)) return true; + } + return delta.dx.abs() > delta.dy.abs(); +} + +/// A horizontally scrolling box (a code block, a table) inside a vertical +/// list, which leaves mostly vertical wheel and trackpad scrolling to that +/// list. A mostly sideways gesture, or Shift + wheel, scrolls this box; touch +/// drags are unchanged (the gesture arena already splits them by axis). +class HorizontalScrollView extends StatelessWidget { + const HorizontalScrollView({super.key, required this.child}); + + final Widget child; + + @override + Widget build(BuildContext context) => SingleChildScrollView( + scrollDirection: Axis.horizontal, + // Below the horizontal scrollable, so this claim comes before its own. + // Translucent: the gaps between a table's cells or a block's lines hit no + // child, yet the scrollable around them still claims the event there. + child: Listener( + behavior: HitTestBehavior.translucent, + onPointerSignal: (event) { + if (event is! PointerScrollEvent) return; + if (isSidewaysWheel(context, event)) return; + final list = Scrollable.maybeOf(context, axis: Axis.vertical); + if (list != null) claimVerticalWheel(event, list.position); + }, + child: child, + ), + ); +} + +/// Scrolls [controller]'s vertical list with a wheel or trackpad over +/// [child] (controls floating over the list) when nothing under the pointer +/// claimed the event first, as the browser scrolls a page under fixed bars. +/// A multi-line field that can still scroll its own text keeps the event. +class VerticalWheelForwarder extends StatelessWidget { + const VerticalWheelForwarder({ + super.key, + required this.controller, + required this.child, + }); + + final ScrollController controller; + final Widget child; + + @override + Widget build(BuildContext context) => Listener( + onPointerSignal: (event) { + if (event is! PointerScrollEvent || !controller.hasClients) return; + if (isSidewaysWheel(context, event)) return; + // A list with several positions (it is being swapped) is left alone. + if (controller.positions.length != 1) return; + claimVerticalWheel(event, controller.position); + }, + child: child, + ); +} diff --git a/app/notes/chat-wheel-scroll.md b/app/notes/chat-wheel-scroll.md new file mode 100644 index 00000000..2f9ccdcd --- /dev/null +++ b/app/notes/chat-wheel-scroll.md @@ -0,0 +1,60 @@ +# Chat transcript: wheel and trackpad scrolling + +Operator report (desktop browser): "while in the chat, sometimes I can't scroll." + +## Reproduction + +Release web build of `tool/search_selection_probe_entry.dart` with +`?chats=3&msgs=40,3,12&rich=1` (and `&live=400`, `&older=1`; +`tool/perf/chat_scroll_fixture.dart`), driven by `tool/capture` wheel steps +at 1280x800 and 560x900. `window.chatScrollMetrics()` reports the transcript +offset after each step (`tool/perf/chat_scroll_probe.dart`). 136 measured +steps across long, short, streaming, Load older, switched and overlay cases. + +Failed before the fix (offset unchanged, or pulled back to the end): + +- **Small wheel/trackpad ticks at the end** (|dy| below 32 px per event): + every tick was snapped back, in long and short chats, both sizes, over any + content. While a reply streamed, the ticks were pulled further down. +- **Diagonal trackpad gestures over a code block or table** that scrolls + sideways: the whole event went to the block, so the transcript did not move. +- **Wheel over the floating chat controls**: the composer (field, attach, + send), the title pill, the model control and the jump control. + +Load older, chat switching, short (top-anchored) chats and the split +(bottom-anchored) view itself scrolled correctly; no anchor or extent defect +was found. + +## Root causes and fixes + +1. Follow mode (`chat_thread_view.dart`): each wheel tick is its own scroll, + and its end re-judged "following" with the 32 px threshold, then jumped to + the end. Now a user scroll toward older rows releases the end however small + (`chatFollowsAfterScroll`); a scroll toward the end still returns within the + threshold. The jump control appears once streamed content moves the end + beyond the threshold. +2. The same end-of-scroll jump ran inside the position's activity switch: a + touch or scrollbar drag released within 32 px of the end re-entered the + handler without end (stack overflow while handling the gesture, which left + the drag broken). The jump now runs after the notification. +3. Flutter's `Scrollable` claims a pointer scroll when its own axis can move, + and the innermost claim wins. `HorizontalScrollView` + (`lib/ui/layout/wheel_scroll_forwarding.dart`, used by markdown code blocks + and tables) gives a mostly vertical gesture to the enclosing vertical list; + a mostly sideways one, or Shift + wheel, still scrolls the block. +4. `VerticalWheelForwarder` wraps the conversation page, so a wheel over its + floating bar, composer and jump control scrolls the transcript unless + something under the pointer (a composer field with its own overflow) + claims it first. + +Not changed: the shell's floating tab buttons (bottom right on wide windows) +still take no wheel; they are app navigation shared by every destination. + +## Checks + +- Widget tests: `test/features/chat/conversation/chat_thread_wheel_scroll_test.dart` + (every content kind, both scroll modes, mouse and trackpad, sideways and + Shift), `chat_thread_wheel_follow_test.dart` (streaming, touch drags, + floating controls, Load older), `test/ui/layout/wheel_scroll_forwarding_test.dart`. +- Browser check: `tool/capture/examples/chat-wheel-scroll.json` (16 + expectations; fails on the first one before the fix). diff --git a/app/test/features/chat/conversation/chat_scroll_test.dart b/app/test/features/chat/conversation/chat_scroll_test.dart index 0ee6a071..0c540900 100644 --- a/app/test/features/chat/conversation/chat_scroll_test.dart +++ b/app/test/features/chat/conversation/chat_scroll_test.dart @@ -29,6 +29,31 @@ void main() { expect(chatFollowsAt(null, itemCount: 3), isFalse); expect(chatFollowsAt(0, itemCount: 0), isFalse); }); + + test('a scroll toward older rows releases the end however small', () { + // Toward the end, landing within the threshold follows again. + expect( + chatFollowsAfterScroll(20, itemCount: 3, towardOlder: false), + isTrue, + ); + expect( + chatFollowsAfterScroll(33, itemCount: 3, towardOlder: false), + isFalse, + ); + // A wheel or trackpad tick up is the operator's: even 2 px releases. + expect( + chatFollowsAfterScroll(2, itemCount: 3, towardOlder: true), + isFalse, + ); + expect( + chatFollowsAfterScroll(0, itemCount: 3, towardOlder: true), + isTrue, + ); + expect( + chatFollowsAfterScroll(0, itemCount: 0, towardOlder: true), + isFalse, + ); + }); }); group('jump control', () { diff --git a/app/test/features/chat/conversation/chat_thread_wheel_follow_test.dart b/app/test/features/chat/conversation/chat_thread_wheel_follow_test.dart new file mode 100644 index 00000000..e4eeb310 --- /dev/null +++ b/app/test/features/chat/conversation/chat_thread_wheel_follow_test.dart @@ -0,0 +1,160 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; + +import 'chat_thread_fixtures.dart'; +import 'chat_thread_scroll_test.dart' show transcriptScroll; +import 'chat_wheel_fixtures.dart'; + +// Follow mode never fights the operator's wheel, and the wheel scrolls the +// transcript from the controls floating over it too. + +Future _open( + WidgetTester tester, + FakeChatGateway gateway, +) async { + gateway.history = (_) async => chatPage( + [...chatWheelFillers(20), chatWheelMessage(ChatWheelKind.wide, 'target')], + cursor: 'older', + hasMore: true, + ); + await openChatWheelThread(tester, gateway); + return transcriptScroll(tester).position; +} + +void main() { + testWidgets('small trackpad ticks leave a streaming reply, which no longer ' + 'pulls the view back', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + final scroll = await _open(tester, gateway); + gateway.emitEvent(chatStepFrame('running')); + gateway.emitEvent(chatTextFrame('Streaming. ', messageId: 'live')); + await tester.pump(); + await tester.pump(); + expect(scroll.pixels, closeTo(scroll.maxScrollExtent, 0.5)); + + final centre = tester.getCenter(chatWheelThread); + for (var tick = 0; tick < 3; tick++) { + await wheel( + tester, + centre, + const Offset(0, -2), + kind: PointerDeviceKind.trackpad, + ); + } + final held = scroll.pixels; + expect(held, closeTo(scroll.maxScrollExtent - 6, 0.5)); + for (var delta = 0; delta < 4; delta++) { + gateway.emitEvent( + chatTextFrame('More streamed words. ' * 20, messageId: 'live'), + ); + await tester.pump(); + await tester.pump(); + } + expect(scroll.pixels, closeTo(held, 0.5)); + expect(scroll.maxScrollExtent, greaterThan(held + 40)); + expect(find.byKey(const Key('chat-jump-to-latest')), findsOneWidget); + + // Back at the end, the stream is followed again. + await wheel(tester, centre, const Offset(0, 100000)); + gateway.emitEvent(chatTextFrame('The end. ' * 20, messageId: 'live')); + await tester.pump(); + await tester.pump(); + expect(scroll.pixels, closeTo(scroll.maxScrollExtent, 0.5)); + }); + + testWidgets('a touch drag toward older rows stays; one back down within ' + 'the threshold returns to the end', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + final scroll = await _open(tester, gateway); + final end = scroll.maxScrollExtent; + final wide = chatWheelPoint(tester, chatWheelTarget(ChatWheelKind.wide)); + + // A vertical drag over a horizontally scrolling block scrolls the list. + await tester.dragFrom(wide, const Offset(0, 120)); + await tester.pumpAndSettle(); + expect(scroll.pixels, lessThan(end - 60)); + await tester.dragFrom( + tester.getCenter(chatWheelThread), + Offset(0, -(end - scroll.pixels - 10)), + ); + await tester.pumpAndSettle(); + expect(scroll.pixels, closeTo(end, 0.5)); + + // A short drag up is the operator's: it is not snapped back. + await tester.dragFrom( + tester.getCenter(chatWheelThread), + const Offset(0, 40), + ); + await tester.pumpAndSettle(); + expect(scroll.pixels, lessThan(end - 10)); + }); + + testWidgets('the wheel over the floating bar, the composer and the jump ' + 'control scrolls the transcript', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + final scroll = await _open(tester, gateway); + await wheel( + tester, + tester.getCenter(chatWheelThread), + const Offset(0, -300), + ); + final jump = find.byKey(const Key('chat-jump-to-latest')); + expect(jump, findsOneWidget); + + for (final over in [ + find.byKey(const Key('chat-info')), + find.byKey(const Key('chat-composer-pill')), + find.byKey(const Key('chat-composer-attach')), + jump, + ]) { + final before = scroll.pixels; + await wheel(tester, tester.getCenter(over), const Offset(0, -50)); + expect(scroll.pixels, closeTo(before - 50, 0.5), reason: '$over'); + await wheel( + tester, + tester.getCenter(over), + const Offset(0, 30), + kind: PointerDeviceKind.trackpad, + ); + expect(scroll.pixels, closeTo(before - 20, 0.5), reason: '$over'); + } + }); + + testWidgets('after Load older the wheel keeps scrolling both ways', ( + tester, + ) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + final scroll = await _open(tester, gateway); + final centre = tester.getCenter(chatWheelThread); + for ( + var tick = 0; + tick < 80 && !tester.any(find.text('Load older')); + tick++ + ) { + await wheel(tester, centre, const Offset(0, -400)); + } + await tester.pumpAndSettle(); + gateway.history = (_) async => chatPage( + chatWheelFillers( + 20, + ).map((m) => {...m, 'id': 'older-${m['id']}'}).toList(), + ); + await tester.tap(find.text('Load older')); + await tester.pumpAndSettle(); + expect(find.text('Load older'), findsNothing); + + final before = scroll.pixels; + await wheel(tester, centre, const Offset(0, -120)); + expect(scroll.pixels, closeTo(before - 120, 0.5)); + await wheel(tester, centre, const Offset(0, 60)); + expect(scroll.pixels, closeTo(before - 60, 0.5)); + await wheel(tester, centre, const Offset(0, -100000)); + await tester.pumpAndSettle(); + expect(scroll.pixels, closeTo(scroll.minScrollExtent, 0.5)); + }); +} diff --git a/app/test/features/chat/conversation/chat_thread_wheel_scroll_test.dart b/app/test/features/chat/conversation/chat_thread_wheel_scroll_test.dart new file mode 100644 index 00000000..4ba0719d --- /dev/null +++ b/app/test/features/chat/conversation/chat_thread_wheel_scroll_test.dart @@ -0,0 +1,181 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; + +import 'chat_thread_fixtures.dart'; +import 'chat_thread_scroll_test.dart' show transcriptScroll; +import 'chat_wheel_fixtures.dart'; + +// Wheel and trackpad scrolling over every content kind, in both scroll modes: +// a long transcript is split at an anchor (offsets above it are negative); a +// short one with a tall newest row stays top-anchored. + +/// The horizontal scrollable inside (a code block) or around (a table) [target]. +ScrollPosition _horizontal(WidgetTester tester, Finder target) { + final scrollables = [ + find.descendant(of: target.first, matching: find.byType(Scrollable)), + find.ancestor(of: target.first, matching: find.byType(Scrollable)), + ]; + return [ + for (final finder in scrollables) + for (final element in finder.evaluate()) + ((element as StatefulElement).state as ScrollableState).position, + ].firstWhere((position) => position.axis == Axis.horizontal); +} + +void main() { + for (final device in [PointerDeviceKind.mouse, PointerDeviceKind.trackpad]) { + for (final kind in ChatWheelKind.values) { + testWidgets('split transcript: the wheel over $kind scrolls it ' + '(${device.name})', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + gateway.history = (_) async => chatPage([ + ...chatWheelFillers(20), + chatWheelMessage(kind, 'target'), + chatMessage( + 'tail', + 'user', + parts: [ + {'type': 'text', 'text': 'Thanks'}, + ], + ), + ]); + await openChatWheelThread(tester, gateway); + final scroll = transcriptScroll(tester).position; + expect(scroll.minScrollExtent, lessThan(0)); + final end = scroll.maxScrollExtent; + expect(scroll.pixels, closeTo(end, 0.5)); + final target = chatWheelTarget(kind); + + // Small ticks at the end leave it; none is snapped back. + for (var tick = 0; tick < 3; tick++) { + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(0, -4), + kind: device, + ); + } + expect(scroll.pixels, closeTo(end - 12, 0.5)); + await tester.pumpAndSettle(); + expect(scroll.pixels, closeTo(end - 12, 0.5)); + + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(0, -40), + kind: device, + ); + expect(scroll.pixels, closeTo(end - 52, 0.5)); + // A mostly vertical gesture with some sideways drift still scrolls + // the transcript, also over a code block or table that could take + // the sideways part. + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(6, -30), + kind: device, + ); + expect(scroll.pixels, closeTo(end - 82, 0.5)); + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(-6, 30), + kind: device, + ); + expect(scroll.pixels, closeTo(end - 52, 0.5)); + }); + + testWidgets('top-anchored transcript: the wheel over $kind scrolls it ' + '(${device.name})', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + gateway.history = (_) async => chatPage([ + chatMessage( + 'first', + 'user', + parts: [ + {'type': 'text', 'text': 'Show me'}, + ], + ), + chatWheelMessage(kind, 'target'), + chatMessage( + 'tall', + 'assistant', + parts: [ + {'type': 'text', 'text': 'Tall answer. ' * 600}, + ], + ), + ]); + await openChatWheelThread(tester, gateway); + final scroll = transcriptScroll(tester).position; + expect(scroll.minScrollExtent, 0); + expect(scroll.maxScrollExtent, greaterThan(200)); + // The operator's own scroll to the top releases the end. + await wheel( + tester, + tester.getCenter(chatWheelThread), + const Offset(0, -100000), + ); + await tester.pumpAndSettle(); + expect(scroll.pixels, 0); + final target = chatWheelTarget(kind); + + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(0, 4), + kind: device, + ); + expect(scroll.pixels, closeTo(4, 0.5)); + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(6, 30), + kind: device, + ); + expect(scroll.pixels, closeTo(34, 0.5)); + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(-6, -30), + kind: device, + ); + expect(scroll.pixels, closeTo(4, 0.5)); + }); + } + } + + for (final kind in [ChatWheelKind.wide, ChatWheelKind.table]) { + testWidgets('a sideways gesture or Shift + wheel over $kind scrolls it, ' + 'not the transcript', (tester) async { + final gateway = FakeChatGateway(); + addTearDown(gateway.close); + gateway.history = (_) async => + chatPage([...chatWheelFillers(20), chatWheelMessage(kind, 'target')]); + await openChatWheelThread(tester, gateway); + final scroll = transcriptScroll(tester).position; + final end = scroll.pixels; + final target = chatWheelTarget(kind); + final sideways = _horizontal(tester, target); + expect(sideways.maxScrollExtent, greaterThan(100)); + + await wheel( + tester, + chatWheelPoint(tester, target), + const Offset(40, 3), + kind: PointerDeviceKind.trackpad, + ); + expect(sideways.pixels, closeTo(40, 0.5)); + expect(scroll.pixels, closeTo(end, 0.5)); + + await tester.sendKeyDownEvent(LogicalKeyboardKey.shiftLeft); + await wheel(tester, chatWheelPoint(tester, target), const Offset(0, 30)); + await tester.sendKeyUpEvent(LogicalKeyboardKey.shiftLeft); + expect(sideways.pixels, closeTo(70, 0.5)); + expect(scroll.pixels, closeTo(end, 0.5)); + }); + } +} diff --git a/app/test/features/chat/conversation/chat_wheel_fixtures.dart b/app/test/features/chat/conversation/chat_wheel_fixtures.dart new file mode 100644 index 00000000..98acb784 --- /dev/null +++ b/app/test/features/chat/conversation/chat_wheel_fixtures.dart @@ -0,0 +1,142 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/core/api_gateway.dart'; +import 'package:pipelines_app/features/chat/conversation/chat_thread_view.dart'; +import 'package:pipelines_app/features/chat/ui/transcript/chat_attachment_gallery.dart'; +import 'package:pipelines_app/features/chat/ui/transcript/chat_injected_rows.dart'; +import 'package:pipelines_app/features/chat/ui/transcript/chat_message_view.dart'; + +import 'chat_thread_fixtures.dart'; +import 'chat_thread_scroll_test.dart' show host; + +/// The transcript content kinds a wheel can land on. +enum ChatWheelKind { text, code, wide, table, agent, notice, image } + +const _png = + 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlE' + 'QVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=='; + +const _wideLine = 'go test ./internal/server/... -run TestWheel && '; + +String _table() => + '| ${[for (var c = 0; c < 16; c++) 'Column $c'].join(' | ')} |\n' + '| ${List.filled(16, '---').join(' | ')} |\n' + '| ${[for (var c = 0; c < 16; c++) 'value $c'].join(' | ')} |'; + +/// One message drawing [kind], with id [id]. +JsonMap chatWheelMessage(ChatWheelKind kind, String id) { + JsonMap text(String role, String body, {String? messageKind}) => { + ...chatMessage( + id, + role, + parts: [ + {'type': 'text', 'name': 'reviewer', 'text': body}, + ], + ), + 'kind': ?messageKind, + }; + return switch (kind) { + ChatWheelKind.text => text('assistant', 'A plain answer paragraph. ' * 4), + ChatWheelKind.code => text( + 'assistant', + '```dart\n${List.generate(4, (l) => 'final v$l = $l;').join('\n')}\n```', + ), + ChatWheelKind.wide => text( + 'assistant', + '```sh\n${List.filled(12, _wideLine).join()}true\n```', + ), + ChatWheelKind.table => text('assistant', _table()), + ChatWheelKind.agent => text( + 'user', + '## Review\n\nAll checks passed.', + messageKind: 'agent_report', + ), + ChatWheelKind.notice => text( + 'user', + 'Background task finished.', + messageKind: 'notice', + ), + ChatWheelKind.image => chatMessage( + id, + 'user', + parts: [ + {'type': 'file', 'mime': 'image/png', 'name': 'a.png', 'uri': _png}, + {'type': 'text', 'text': 'With an image'}, + ], + ), + }; +} + +/// The widget that draws [kind] in the transcript. +Finder chatWheelTarget(ChatWheelKind kind) { + Finder code(String text) => find.ancestor( + of: find.textContaining(text), + matching: find.byType(SingleChildScrollView), + ); + return switch (kind) { + ChatWheelKind.text => find.byWidgetPredicate( + (widget) => + widget is ChatMessageView && + (widget.row['messageIds'] as List?)?.contains('target') == true, + ), + ChatWheelKind.code => code('final v0'), + ChatWheelKind.wide => code('go test'), + ChatWheelKind.table => find.byType(Table), + ChatWheelKind.agent => find.byType(ChatAgentReportCard), + ChatWheelKind.notice => find.byType(ChatSystemNoticeLine), + ChatWheelKind.image => find.byType(ChatAttachmentGallery), + }; +} + +List chatWheelFillers(int count) => [ + for (var index = 0; index < count; index++) + chatMessage( + 'f$index', + index.isEven ? 'user' : 'assistant', + parts: [ + { + 'type': 'text', + 'text': + 'Filler $index. ${List.filled(5, 'A sentence that wraps across the transcript width.').join(' ')}', + }, + ], + ), +]; + +Finder get chatWheelThread => find.byKey(const Key('chat-thread-s')); + +Future openChatWheelThread( + WidgetTester tester, + FakeChatGateway gateway, +) async { + await tester.pumpWidget( + host(ChatThreadView(gateway: gateway, sessionId: 's', onBack: () {})), + ); + await tester.pumpAndSettle(); +} + +/// The centre of [finder]'s part between the floating bar and the composer. +Offset chatWheelPoint(WidgetTester tester, Finder finder) { + final top = tester.getRect(find.byKey(const Key('chat-info'))).bottom + 4; + final bottom = + tester.getRect(find.byKey(const Key('chat-composer-pill'))).top - 4; + final shown = tester + .getRect(finder.first) + .intersect(Rect.fromLTRB(0, top, 800, bottom)); + expect(shown.height, greaterThan(8), reason: '$finder is not in view'); + return shown.center; +} + +/// One wheel or trackpad tick of [delta] at [at]. +Future wheel( + WidgetTester tester, + Offset at, + Offset delta, { + PointerDeviceKind kind = PointerDeviceKind.mouse, +}) async { + final pointer = TestPointer(1, kind); + await tester.sendEventToBinding(pointer.hover(at)); + await tester.sendEventToBinding(pointer.scroll(delta)); + await tester.pump(); +} diff --git a/app/test/ui/layout/wheel_scroll_forwarding_test.dart b/app/test/ui/layout/wheel_scroll_forwarding_test.dart new file mode 100644 index 00000000..246313b6 --- /dev/null +++ b/app/test/ui/layout/wheel_scroll_forwarding_test.dart @@ -0,0 +1,181 @@ +import 'package:flutter/gestures.dart'; +import 'package:flutter/material.dart'; +import 'package:flutter/services.dart'; +import 'package:flutter_test/flutter_test.dart'; +import 'package:pipelines_app/ui/layout/wheel_scroll_forwarding.dart'; + +Future _wheel( + WidgetTester tester, + Offset at, + Offset delta, { + PointerDeviceKind kind = PointerDeviceKind.trackpad, +}) async { + final pointer = TestPointer(1, kind); + await tester.sendEventToBinding(pointer.hover(at)); + await tester.sendEventToBinding(pointer.scroll(delta)); + await tester.pump(); +} + +void main() { + final list = ScrollController(); + tearDownAll(list.dispose); + + // A vertical list holding one wide horizontally scrolling row, under a + // floating button that is not part of the list. + Widget page({bool passThrough = true}) => MaterialApp( + home: Scaffold( + body: VerticalWheelForwarder( + controller: list, + child: Stack( + children: [ + ListView( + controller: list, + children: [ + const SizedBox(height: 200), + SizedBox( + height: 60, + child: passThrough + ? const HorizontalScrollView( + key: Key('wide'), + child: SizedBox(width: 3000, height: 60), + ) + : const SingleChildScrollView( + key: Key('wide'), + scrollDirection: Axis.horizontal, + child: SizedBox(width: 3000, height: 60), + ), + ), + const SizedBox(height: 2000), + ], + ), + Positioned( + right: 8, + bottom: 8, + child: FilledButton( + key: const Key('floating'), + onPressed: () {}, + child: const Text('Floating'), + ), + ), + ], + ), + ), + ), + ); + + ScrollPosition sideways(WidgetTester tester) => tester + .state( + find.descendant( + of: find.byKey(const Key('wide')), + matching: find.byType(Scrollable), + ), + ) + .position; + + testWidgets('a mostly vertical trackpad gesture over a wide row scrolls ' + 'the list', (tester) async { + await tester.pumpWidget(page()); + final at = tester.getCenter(find.byKey(const Key('wide'))); + await _wheel(tester, at, const Offset(5, 40)); + expect(list.offset, 40); + expect(sideways(tester).pixels, 0); + }); + + testWidgets('a plain horizontal scroller takes the whole gesture (the ' + 'defect this guards against)', (tester) async { + await tester.pumpWidget(page(passThrough: false)); + list.jumpTo(0); + final at = tester.getCenter(find.byKey(const Key('wide'))); + await _wheel(tester, at, const Offset(5, 40)); + expect(list.offset, 0); + expect(sideways(tester).pixels, 5); + }); + + testWidgets('a mostly sideways gesture or Shift + wheel scrolls the row', ( + tester, + ) async { + await tester.pumpWidget(page()); + list.jumpTo(0); + final at = tester.getCenter(find.byKey(const Key('wide'))); + await _wheel(tester, at, const Offset(40, 5)); + expect(sideways(tester).pixels, 40); + expect(list.offset, 0); + + await tester.sendKeyDownEvent(LogicalKeyboardKey.shiftLeft); + await _wheel( + tester, + at, + const Offset(0, 30), + kind: PointerDeviceKind.mouse, + ); + await tester.sendKeyUpEvent(LogicalKeyboardKey.shiftLeft); + expect(sideways(tester).pixels, 70); + expect(list.offset, 0); + }); + + testWidgets('the wheel over a control floating above the list scrolls it', ( + tester, + ) async { + await tester.pumpWidget(page()); + list.jumpTo(0); + final at = tester.getCenter(find.byKey(const Key('floating'))); + await _wheel( + tester, + at, + const Offset(0, 50), + kind: PointerDeviceKind.mouse, + ); + expect(list.offset, 50); + // At the start, an upward wheel has nothing to move and is not claimed. + list.jumpTo(0); + await _wheel( + tester, + at, + const Offset(0, -50), + kind: PointerDeviceKind.mouse, + ); + expect(list.offset, 0); + }); + + testWidgets('a multi-line field that can scroll its own text keeps the ' + 'wheel', (tester) async { + final field = ScrollController(); + addTearDown(field.dispose); + await tester.pumpWidget( + MaterialApp( + home: Scaffold( + body: VerticalWheelForwarder( + controller: list, + child: Column( + children: [ + Expanded( + child: ListView( + controller: list, + children: const [SizedBox(height: 3000)], + ), + ), + TextField( + key: const Key('field'), + scrollController: field, + maxLines: 3, + controller: TextEditingController( + text: List.generate(20, (i) => 'line $i').join('\n'), + ), + ), + ], + ), + ), + ), + ), + ); + list.jumpTo(0); + await _wheel( + tester, + tester.getCenter(find.byKey(const Key('field'))), + const Offset(0, 20), + kind: PointerDeviceKind.mouse, + ); + expect(field.offset, greaterThan(0)); + expect(list.offset, 0); + }); +} diff --git a/app/tool/capture/README.md b/app/tool/capture/README.md index 41e025c8..0217e94b 100644 --- a/app/tool/capture/README.md +++ b/app/tool/capture/README.md @@ -28,7 +28,8 @@ search hits for `release`. Build it once per change, from `app/`: URL parameters (the kit sets them from `open=` and the options): `route=`, `q=`, `platform=material|cupertino`, -`theme=light|dark`. Without `theme`, the app follows the browser's colour +`theme=light|dark`; `--params` (or a step's or script's `params`) adds fixture +options such as `chats=2&rich=1`. Without `theme`, the app follows the browser's colour scheme. `--theme` also sets that colour scheme through Chrome emulation. ## Steps @@ -45,11 +46,13 @@ In JSON, a step can also set `wait` (ms), `timeout`, `name`, `ms` and `frames`. | `waitfor=` | wait up to 10 s for the target to appear | | `type=text` | type into the focused field (or the first visible one) | | `press=Enter` | press a key: Enter, Escape, Tab, Backspace, ArrowUp or ArrowDown | -| `scroll=600` | scroll with the mouse wheel at the centre (JSON `at` sets a target) | +| `scroll=600` | scroll with the mouse wheel at the centre (JSON `at` sets a target, `dx` a horizontal delta, `repeat` and `gap` a run of ticks) | | `size=WxH` | resize without reloading | | `labels=name` | write the visible semantics labels, keys and rects to JSON | | `film=` | screencast a click for `--film-ms` (900) and write the frames plus a contact sheet | | `wait=ms` | sleep | +| `eval=` | evaluate an expression in the page and log/record its value | +| `expect=` | fail the run (status 1) unless the expression is truthy; JSON `name` labels the check | Targets: - A bare `Artifacts` or `label:Artifacts` is a semantics label (`aria-label` or @@ -58,6 +61,8 @@ Targets: - `key:list-detail-body` is a `Semantics(identifier:)`. A Flutter `Key` is not visible in the DOM. - `120,340` or `xy:120,340` is a point in CSS pixels. +- `eval:` is a point an expression in the page yields as `[x, y]`, waited + for while it yields null (e.g. `eval:JSON.parse(chatScrollTargets()).table`). When a target is missing, the step fails. The kit lists the visible labels, saves `NN-FAILED.png` and exits with status 1. @@ -105,3 +110,15 @@ In a JSON script, `{ "film": "Pipelines", "name": "tab-switch", "ms": 900, Find targets: run `labels=now` after any step and read `NN-now.json`. Look at every PNG you cite. A capture that exits 0 is not a review. + +Check a chat scroll: the full-app fixture exposes `chatScrollMetrics()` (the +open transcript's `{pixels, min, max, viewport}` as JSON; +`tool/perf/chat_scroll_probe.dart`), and `?chats=N` with `?msgs=`, `?rich=1`, +`?older=1` and `?live=N` (`tool/perf/chat_scroll_fixture.dart`) shapes the +transcripts. `tool/capture/examples/chat-wheel-scroll.json` wheels over each +content kind and expects the offset to move: + +```sh +node tool/capture/capture.mjs --build build/probe-app --out /tmp/review/chat-wheel \ + --script tool/capture/examples/chat-wheel-scroll.json +``` diff --git a/app/tool/capture/capture.mjs b/app/tool/capture/capture.mjs index 0431c07f..f2fbd71c 100644 --- a/app/tool/capture/capture.mjs +++ b/app/tool/capture/capture.mjs @@ -19,12 +19,13 @@ const USAGE = `usage: capture.mjs (--build | --url ) --out [opt options: --script --size WxH (880x1000) --platform material|cupertino --theme light|dark --q --wait --film-ms --cdp http://127.0.0.1: --probe true|false + --params steps: open=[@WxH] wait= shot= click= waitfor= type= press= scroll= size=WxH - film= labels= + film= labels= eval= expect= target: