Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

feat(mobile): header shows only at the end of the terminal's output

bubu-dudu20c5f70eb994
diff --git a/mobile/lib/phone/terminal_chrome_scroll.dart b/mobile/lib/phone/terminal_chrome_scroll.dart
index 2d0697d58..609c1079b 100644
--- a/mobile/lib/phone/terminal_chrome_scroll.dart
+++ b/mobile/lib/phone/terminal_chrome_scroll.dart
@@ -1,28 +1,24 @@
+import 'dart:math' as math;
+
import 'package:flutter/widgets.dart';
/// How far the terminal's header has travelled off the top, driven by scrolling.
///
-/// Scrolling forward sends it up and out at the first push; it comes back only
-/// after a real journey in the other direction.
-///
-/// ⚠️ **Leaving is about intent; coming back is about distance.** Any scroll
-/// forward hides the row — somebody reading ahead wants the screen, and wants it
-/// now. But a flick upward in the middle of a long scrollback is still the
-/// middle of a long scrollback, so the return is paid for in travel: see
-/// [_returnTravel].
+/// The header is up while the terminal sits at its newest output, and away
+/// while somebody is scrolled back into history. Scrolling back down to the end
+/// is what brings it home.
///
-/// ⚠️ **It cannot be done by position, and that was measured rather than
-/// assumed.** The obvious rule is "show the header when the content is back at
-/// offset zero", and it was written that way first. While an agent runs a
-/// full-screen program the terminal is on its ALTERNATE buffer, where scrolling
-/// moves no viewport at all — the gesture becomes arrow keys for the program,
-/// through a `Scrollable` whose extents are both infinite. Device logs showed
-/// every notification the page gets carrying `min=-Infinity max=Infinity`, so
-/// there is no zero to be near. Distance is what survives both buffers.
+/// ⚠️ **By position where there is one, by counting where there is not.** While
+/// an agent runs a full-screen program — Claude Code does — the terminal is on
+/// its ALTERNATE buffer, where scrolling moves no viewport at all: the gesture
+/// becomes wheel events for the program, through a `Scrollable` whose extents
+/// are both infinite (device logs showed `min=-Infinity max=Infinity`). The
+/// program still scrolls its own history, so there the distance scrolled back
+/// is counted instead — see [_altBack].
///
/// ⚠️ **Nothing replaces it.** `⋯` goes with the row and comes back with it;
/// Search and New agent never lived here, so a hidden header costs nothing but
-/// the actions sheet until the first scroll the other way.
+/// the actions sheet until the scroll back down.
///
/// ⚠️ **The floating mic, Search and New agent are not driven from here and
/// must not be.** They carry what the mic needs somebody to read, which is
@@ -45,12 +41,6 @@ class TerminalChromeScroll {
TerminalChromeScroll({required TickerProvider vsync})
: _header = AnimationController(
vsync: vsync,
- // ⚠️ **This one value paces the whole hand-over, which is why it is
- // longer than a plain hide would want.** The row sliding away is only half
- // of it: the three floating buttons fly out of the header on this same
- // clock, and each is staggered up to 0.2 behind the first — so the last
- // one gets barely two thirds of whatever is set here. At 200 the
- // sequence read as a snap rather than as a move.
duration: const Duration(milliseconds: 340),
);
@@ -67,31 +57,23 @@ class TerminalChromeScroll {
final AnimationController _header;
- /// How far the content must move before the header is asked to do anything.
+ /// How close to the newest output still counts as "at the end".
///
- /// ⚠️ **Not zero, and this is what keeps the header still.** A terminal that
- /// is streaming scrolls itself by a line at a time, and the finger resting on
- /// the glass reports sub-pixel wobble — either would have the row leaving on
- /// every frame of a scroll that is going nowhere.
- static const double _threshold = 6;
+ /// ⚠️ **Not zero.** A fling settles with sub-pixel error, and a finger resting
+ /// on the glass wobbles — either would flicker the row in and out at the end.
+ static const double _endSlack = 8;
- /// How far back somebody must scroll, without turning round, before the header
- /// comes home.
+ /// On the alternate buffer, how far somebody has scrolled back from the end,
+ /// in logical pixels, counted from the gestures themselves.
///
- /// ⚠️ **Much larger than [_threshold], and deliberately asymmetric.** Leaving
- /// is about intent — one push forward means "give me the screen" — where
- /// coming back is about having actually travelled: more than a phone screen's
- /// worth of content, so a stray flick upward while reading does not drag the
- /// row back over the output underneath it.
- static const double _returnTravel = 300;
-
- /// Movement in one direction since the last time the header changed its mind,
- /// in logical pixels. Reset on every reversal, so the threshold is measured
- /// per-direction rather than as a running total.
- double _travel = 0;
-
- /// Whether the scroll now running was begun by a finger. See [onNotification].
- bool _dragging = false;
+ /// ⚠️ **Counted, because there is nothing to read.** There the gesture is
+ /// turned into wheel events for the program (Claude Code scrolls its own
+ /// history this way), through a `Scrollable` with infinite extents — so the
+ /// page never learns where the program is. Scrolling up adds, scrolling down
+ /// pays it back, and paid back in full is "at the end". Floored at zero,
+ /// since the program stops at its end however hard somebody keeps scrolling
+ /// down.
+ double _altBack = 0;
/// 0 fully down, 1 fully off the top.
Animation<double> get header => _curved;
@@ -102,81 +84,46 @@ class TerminalChromeScroll {
/// it: search growing out of its bar, the keyboard coming up, a swipe landing
/// on a different agent.
void reveal() {
- _travel = 0;
- // A gesture still in flight must not carry on driving the header it was just
- // told to show — a fling running under an opening search would send it back
- // off the top behind the overlay.
- _dragging = false;
+ _altBack = 0;
_header.value = 0;
}
/// Feeds one scroll notification in. Returns false so the notification carries
/// on to anything else listening.
///
- /// ⚠️ **Only what a FINGER started gets through, and without that filter the
- /// header leaves by itself.** A terminal following its own output scrolls on
- /// every line the agent prints, and those arrive as ordinary updates: the
- /// header would fold away while somebody sat still and read, and come back the
- /// moment the agent went quiet.
- ///
- /// ⚠️ **The gate is on the START of the gesture, not on each update.** A
- /// thrown scroll keeps moving after the thumb is gone — `dragDetails` is null
- /// for every one of those frames, so testing each update would have dropped
- /// the whole fling, which is most of the distance somebody actually travels.
- /// [_dragging] carries the answer from the start notification through to the
- /// end of the ballistic run that follows it.
+ /// ⚠️ **Every update, not only the ones a finger started.** A terminal at its
+ /// end follows its own output and stays at the end, so those updates keep the
+ /// header up; one scrolled back does not follow, so they keep it away.
bool onNotification(ScrollNotification notification) {
- if (notification is ScrollStartNotification) {
- _dragging = notification.dragDetails != null;
- } else if (notification is ScrollUpdateNotification) {
- if (_dragging) _onScrolled(notification.scrollDelta ?? 0);
+ if (notification.metrics.axis != Axis.vertical) return false;
+ if (notification is ScrollUpdateNotification) {
+ _follow(notification.metrics, notification.scrollDelta ?? 0);
} else if (notification is ScrollEndNotification) {
- _dragging = false;
+ _follow(notification.metrics, 0);
}
return false;
}
- /// One scroll tick, in logical pixels. Positive is towards the newest output.
- ///
- /// ⚠️ **Distance travelled, not position, and the terminal leaves no choice.**
- /// While an agent is running a full-screen program the terminal is on its
- /// ALTERNATE buffer, and there scrolling does not move a viewport at all — the
- /// gesture is translated into arrow keys and handed to the program, through a
- /// `Scrollable` that reports `minScrollExtent: -infinity` and
- /// `maxScrollExtent: +infinity`. There is no offset zero to be near. This was
- /// established from the device rather than the source: every notification the
- /// page receives carries those infinities.
- ///
- /// So "back at the start" is measured as the only thing that survives both
- /// buffers — how far somebody has scrolled BACK, continuously, without
- /// turning round.
- void _onScrolled(double delta) {
- if (delta == 0) return;
- // ⚠️ A reversal resets the count rather than subtracting from it. Otherwise
- // a long scroll one way banks up travel that a short scroll back has to pay
- // off before anything moves, and the row ignores the first flick back.
- if (delta.isNegative != _travel.isNegative) _travel = 0;
- _travel += delta;
-
- // Going forward: away at the first deliberate push, because somebody
- // reading ahead wants the screen and wants it now.
- if (_travel >= _threshold) {
- _travel = 0;
- _header.forward();
- return;
+ void _follow(ScrollMetrics metrics, double delta) {
+ if (!metrics.hasContentDimensions || !metrics.hasPixels) return;
+ final max = metrics.maxScrollExtent;
+ final bool atEnd;
+ if (max.isFinite) {
+ _altBack = 0;
+ atEnd = metrics.pixels >= max - _endSlack;
+ } else {
+ // The alternate buffer: the program scrolls itself, so where it is can
+ // only be counted — see [_altBack].
+ _altBack = math.max(0, _altBack - delta);
+ atEnd = _altBack <= _endSlack;
}
-
- // Coming back: only after a real journey. ⚠️ [_returnTravel], not
- // [_threshold] — a flick upward in the middle of a long scrollback is still
- // the middle of it, and a header that came back there sat over output
- // nobody had scrolled to the top of.
- //
- // Several quick flicks up count the same as one long drag: the tally only
- // resets when the direction turns round or when it has paid out, so the
- // distance accumulates across the lifts that a real journey is made of.
- if (-_travel >= _returnTravel) {
- _travel = 0;
- _header.reverse();
+ if (atEnd) {
+ if (_header.status != AnimationStatus.reverse && _header.value != 0) {
+ _header.reverse();
+ }
+ } else if (_header.status != AnimationStatus.forward &&
+ _header.value != 1) {
+ _header.forward();
}
}