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): faster, steadier remote scroll for Claude Code

tonya3d36885cc0e
diff --git a/mobile/lib/state/app_state.dart b/mobile/lib/state/app_state.dart
index 7de82cc00..09f490e6c 100644
--- a/mobile/lib/state/app_state.dart
+++ b/mobile/lib/state/app_state.dart
@@ -2,7 +2,7 @@ import 'dart:async';
import 'dart:math' show Random;
import 'package:dio/dio.dart';
-import 'package:xterm/xterm.dart' show Terminal;
+import 'package:xterm/xterm.dart' show RemoteScrollMemory, Terminal;
import 'package:flutter/foundation.dart';
import 'package:flutter_riverpod/flutter_riverpod.dart';
@@ -1603,6 +1603,7 @@ class AppNotifier extends ChangeNotifier {
_forgetLaunchHold();
// Signed out from elsewhere: the kept screens go as on a sign-out here (see [logout]).
_keptScreens.clear();
+ _forgetScrollMemories();
_keptScreenStore?.clear();
unawaited(_pool?.closeAll());
_pool = null;
@@ -4553,6 +4554,7 @@ class AppNotifier extends ChangeNotifier {
sessionPreviews.removeAgent(machine.machine.machineId, agentId);
_keptScreens.remove('${machine.machine.machineId}/$agentId');
_keptScreenStore?.remove('${machine.machine.machineId}/$agentId');
+ _scrollMemories.remove('${machine.machine.machineId}/$agentId')?.clear();
agentNotices.forgetAgent((
machineId: machine.machine.machineId,
agentId: agentId,
@@ -6712,6 +6714,7 @@ class AppNotifier extends ChangeNotifier {
agentId: agent.id,
agentName: agent.name,
engineId: agent.engine,
+ scrollMemory: _scrollMemoryFor('${pane.machineId}/${agent.id}'),
client: phoneClientDescriptor(),
send: (type, payload) =>
_sendTerminalFrame(pane.machineId, type, payload),
@@ -6877,6 +6880,36 @@ class AppNotifier extends ChangeNotifier {
final _keptScreens = <String, Terminal>{};
static const _keptScreenLimit = 3;
+ /// What the terminal view's scroll mirror knew of each agent opened most
+ /// recently in this run — its rows, which of them scroll — so that a reopen,
+ /// or a keyframe, does not fetch them again ([RemoteScrollMemory]). In memory
+ /// only, as [_keptScreens] are, and cleared with them.
+ final _scrollMemories = <String, RemoteScrollMemory>{};
+
+ /// A few, not all — each holds up to two grids of 1,500 rows, about a
+ /// kilobyte a row. Eight: the pager attaches the agents either side of the
+ /// one on screen, and at four, going back to an agent a few swipes away
+ /// found its rows already let go.
+ static const _scrollMemoryLimit = 8;
+
+ /// Every agent's scroll memory forgotten — this account's terminals' rows.
+ void _forgetScrollMemories() {
+ for (final memory in _scrollMemories.values) {
+ memory.clear();
+ }
+ _scrollMemories.clear();
+ }
+
+ /// [key]'s scroll memory — `machineId/agentId` — made the most recent.
+ RemoteScrollMemory _scrollMemoryFor(String key) {
+ final memory = _scrollMemories.remove(key) ?? RemoteScrollMemory();
+ _scrollMemories[key] = memory;
+ while (_scrollMemories.length > _scrollMemoryLimit) {
+ _scrollMemories.remove(_scrollMemories.keys.first)?.clear();
+ }
+ return memory;
+ }
+
/// The visible screens of the agents opened most recently in this run, in memory only — see
/// [KeptScreenStore]. Where [_keptScreens] has no exact terminal for an agent (it holds three),
/// this has the screen it showed. Null in tests that do not hand one over.
@@ -6951,6 +6984,7 @@ class AppNotifier extends ChangeNotifier {
// Everything closing at once is a sign-out or a reset: nothing of it is kept
// ([_detachSession]'s `keepScreen`).
_keptScreens.clear();
+ _forgetScrollMemories();
final open = allPanes.toList();
for (final swarm in swarms) {
swarm.panes.clear();
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index cd7a74efe..c4b804971 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -144,6 +144,11 @@ class TerminalSession extends ChangeNotifier {
final String agentId;
String agentName;
final String? engineId;
+
+ /// What the view's scroll mirror knows of this agent's rows — kept by the app
+ /// for the agent, not the session, so it outlives every keyframe and every
+ /// reopen of it. See [RemoteScrollMemory]. Null keeps it in the view only.
+ final RemoteScrollMemory? scrollMemory;
final TerminalFrameSender send;
final TerminalBinarySender sendBinary;
@@ -187,6 +192,7 @@ class TerminalSession extends ChangeNotifier {
this.lastHeardFromMachine,
this.resyncTimeout = const Duration(seconds: 4),
this.takeover = true,
+ this.scrollMemory,
}) {
terminal = _newTerminal();
}
diff --git a/mobile/lib/widgets/terminal_panel.dart b/mobile/lib/widgets/terminal_panel.dart
index 45462383a..67e35c8cf 100644
--- a/mobile/lib/widgets/terminal_panel.dart
+++ b/mobile/lib/widgets/terminal_panel.dart
@@ -1698,6 +1698,13 @@ class _TerminalPanelState extends State<TerminalPanel>
// it in — `RemoteScrollMirror`. The slide above is
// what is left when it is off.
altBufferScrollMirror: true,
+ // Claude Code takes Page Up/Down as half a screen of its
+ // transcript at once, past its wheel's ~150 rows a
+ // second; another program may take them otherwise.
+ altBufferScrollPageKeys: session.engineId == 'claude',
+ // What the mirror knew of this agent's rows, kept by the
+ // app across keyframes and reopens.
+ altBufferScrollMemory: session.scrollMemory,
// How many redraws slid and how many jumped — the
// scroll's smoothness, for the trace.
onAltBufferScrollShift: kTypingTrace
diff --git a/mobile/third_party/xterm/lib/src/terminal_view.dart b/mobile/third_party/xterm/lib/src/terminal_view.dart
index a40156940..fa471ad8c 100644
--- a/mobile/third_party/xterm/lib/src/terminal_view.dart
+++ b/mobile/third_party/xterm/lib/src/terminal_view.dart
@@ -15,6 +15,7 @@ import 'package:xterm/src/ui/input_map.dart';
import 'package:xterm/src/ui/keyboard_listener.dart';
import 'package:xterm/src/ui/keyboard_visibility.dart';
import 'package:xterm/src/ui/render.dart';
+import 'package:xterm/src/ui/remote_scroll_mirror.dart' show RemoteScrollMemory;
import 'package:xterm/src/ui/scroll_handler.dart';
import 'package:xterm/src/ui/shortcut/actions.dart';
import 'package:xterm/src/ui/shortcut/shortcuts.dart';
@@ -66,6 +67,8 @@ class TerminalView extends StatefulWidget {
this.altBufferScrollAnimated = false,
this.onAltBufferScrollShift,
this.altBufferScrollMirror = false,
+ this.altBufferScrollPageKeys = false,
+ this.altBufferScrollMemory,
this.keepsInputAcrossTerminals = false,
this.predictsEcho = false,
});
@@ -229,6 +232,19 @@ class TerminalView extends StatefulWidget {
/// follow the program's redraws.
final bool altBufferScrollMirror;
+ /// AUTONOMOUS PATCH: with [altBufferScrollMirror], whether the program may be
+ /// scrolled a page at a time with its Page Up and Page Down keys while the
+ /// finger is far ahead of it — for a program known to take them as half a
+ /// screen of its transcript (Claude Code), and only while it shows its
+ /// prompt. See `RemoteScrollMirror._sendPage`.
+ final bool altBufferScrollPageKeys;
+
+ /// AUTONOMOUS PATCH: with [altBufferScrollMirror], what is known of this
+ /// program's rows, kept by the embedder for the program (an agent) across
+ /// the emulators a keyframe replaces and the views opened on it — see
+ /// [RemoteScrollMemory]. Null keeps it in the view only.
+ final RemoteScrollMemory? altBufferScrollMemory;
+
/// AUTONOMOUS PATCH: the keyboard's buffer — and what it is composing — is
/// kept when [terminal] is replaced, for an embedder that replaces it only
/// with the next screen of the SAME stream (a keyframe), and gives another
@@ -426,6 +442,8 @@ class TerminalViewState extends State<TerminalView> {
animateRemoteScroll: widget.altBufferScrollAnimated,
onRemoteScrollShift: widget.onAltBufferScrollShift,
mirrorRemoteScroll: widget.altBufferScrollMirror,
+ mirrorPageKeys: widget.altBufferScrollPageKeys,
+ remoteScrollMemory: widget.altBufferScrollMemory,
remoteScrollLink: _remoteScrollLink,
);
},
@@ -997,6 +1015,8 @@ class _TerminalView extends LeafRenderObjectWidget {
this.animateRemoteScroll = false,
this.onRemoteScrollShift,
this.mirrorRemoteScroll = false,
+ this.mirrorPageKeys = false,
+ this.remoteScrollMemory,
this.remoteScrollLink,
});
@@ -1038,6 +1058,10 @@ class _TerminalView extends LeafRenderObjectWidget {
final bool mirrorRemoteScroll;
+ final bool mirrorPageKeys;
+
+ final RemoteScrollMemory? remoteScrollMemory;
+
final RemoteScrollLink? remoteScrollLink;
@override
@@ -1064,6 +1088,8 @@ class _TerminalView extends LeafRenderObjectWidget {
animateRemoteScroll: animateRemoteScroll,
onRemoteScrollShift: onRemoteScrollShift,
mirrorRemoteScroll: mirrorRemoteScroll,
+ mirrorPageKeys: mirrorPageKeys,
+ remoteScrollMemory: remoteScrollMemory,
remoteScrollLink: remoteScrollLink,
);
}
@@ -1092,6 +1118,8 @@ class _TerminalView extends LeafRenderObjectWidget {
..animateRemoteScroll = animateRemoteScroll
..onRemoteScrollShift = onRemoteScrollShift
..mirrorRemoteScroll = mirrorRemoteScroll
+ ..mirrorPageKeys = mirrorPageKeys
+ ..remoteScrollMemory = remoteScrollMemory
..remoteScrollLink = remoteScrollLink;
}
}
diff --git a/mobile/third_party/xterm/lib/src/ui/remote_scroll_mirror.dart b/mobile/third_party/xterm/lib/src/ui/remote_scroll_mirror.dart
index 88d348888..ef31078a3 100644
--- a/mobile/third_party/xterm/lib/src/ui/remote_scroll_mirror.dart
+++ b/mobile/third_party/xterm/lib/src/ui/remote_scroll_mirror.dart
@@ -19,7 +19,7 @@ import 'package:xterm/src/utils/input_trace.dart';
/// So while a scroll runs, the rows that scroll — the program's own header and
/// prompt rows stay as they are — are drawn from a document of rows kept here,
/// at exactly where the finger puts them, every frame. The program is asked to
-/// scroll a few rows AHEAD of the finger ([_lead]), so the rows about to come
+/// scroll a few rows AHEAD of the finger ([_leadRows]), so the rows about to come
/// into view are usually here before they are needed; each whole frame it draws
/// is matched against the document ([_align]) and written into it. When the
/// scroll is over the program is brought back to the row on screen, and drawing
@@ -34,8 +34,24 @@ class RemoteScrollMirror {
required this.onFrame,
required this.requestLines,
required this.requestsIdle,
+ required this.cancelRequests,
+ this.pageKeysEnabled,
+ this.requestPage,
+ this.readScreen,
});
+ /// The program's whole screen now, for [_prefetch] to start from — null
+ /// when it cannot be read whole (a frame still arriving, another screen).
+ final RemoteScreen? Function()? readScreen;
+
+ /// Whether the program may be scrolled a page at a time with its Page Up and
+ /// Page Down keys at all — see [_pageOrWait].
+ final bool Function()? pageKeysEnabled;
+
+ /// Press Page Down ([direction] positive) or Page Up once, alone; false when
+ /// it was not sent.
+ final bool Function(int direction)? requestPage;
+
/// Something drawn from here moved: paint again.
final VoidCallback onFrame;
@@ -46,28 +62,154 @@ class RemoteScrollMirror {
/// Whether every row asked for has gone out and been answered.
final bool Function() requestsIdle;
- /// How many rows the program is kept ahead of the finger, at most.
- static const _lead = 10;
+ /// Rows asked for and not yet sent are not to be — returns how many, to come
+ /// off the books.
+ final int Function() cancelRequests;
+
+ /// How many rows the program is kept ahead of the finger ([_leadRows]): at
+ /// least [_leadMin], plus what the finger covers in [_leadLatency] seconds —
+ /// about a round trip and the program's redraw — and never more than
+ /// [_leadMax] or half the rows that scroll.
+ static const _leadMin = 6;
+ static const _leadMax = 16;
+ static const _leadLatency = 0.15;
+
+ /// The most rows past the last row the program was seen at that it is asked
+ /// to scroll — see [_requestRemote].
+ static const _maxAhead = 24;
+
+ /// The most rows the finger is let run past the edge of what is known — see
+ /// [_capLag].
+ static const _maxLag = 3.0;
+
+ /// A finger that moves less than this many rows has not moved: held on the
+ /// glass, it still reports a pixel or two either way.
+ static const _stillRows = 0.5;
+
+ /// Settling, a program closer than this to the row on screen is brought the
+ /// rest of the way a burst at a time, each counted from where it stopped —
+ /// see [_settleStep].
+ static const _landingRows = 8;
+
+ /// The most rows asked of the program at once while it lands: as many wheel
+ /// events as Claude Code scrolls one row each (`_exactBurst` in the scroll
+ /// handler).
+ static const _landingBurst = 4;
/// A match is believed only with at least this many rows agreeing on it…
- static const _minAgree = 4;
+ static const _minAgree = 5;
- /// …and at least this share of the rows that could show it.
- static const _minAgreeShare = 0.35;
+ /// …and at least half the rows that could show it.
+ ///
+ /// ⚠️ A wrong match writes the frame's rows into the document where they do
+ /// not belong — and the screen, drawn from it, shows rows out of order
+ /// (reported on a phone, 2026-10-06, at 4 rows and 35%). A scroll moves rows
+ /// whole, so a true match has nearly all the rows it can show agreeing; a
+ /// frame no match is sure of is let go ([_lost]) rather than guessed.
+ static const _minAgreeShare = 0.5;
/// Rows kept either side of the program's screen.
- static const _keepRows = 300;
+ ///
+ /// ⚠️ **A long session is read back over hundreds of rows.** At 300 a side,
+ /// the rows read past were let go — 618 known fell to 364 mid-read — and
+ /// scrolling back over them waited on the program again (measured on a
+ /// phone, 2026-10-06, a session hours long). A row is about a kilobyte.
+ static const _keepRows = 2000;
+
+ /// Frames running that may go unplaced while the finger scrolls before the
+ /// document starts again — see [_frame].
+ ///
+ /// ⚠️ **One frame no match is sure of is not the document gone wrong.** A
+ /// frame caught mid-redraw, or one the program drew over with a row of its
+ /// own, matches nothing; thrown away for it, every row known went, and
+ /// scrolling back over them waited on the program again (36 of 59 lost
+ /// frames came first in a scroll, the document thrown away each time,
+ /// measured on a phone, 2026-10-06). Kept through one or two, the screen
+ /// goes on from the document and the next frame says where the program is.
+ static const _maxMissesInARow = 2;
+
+ /// Rows set aside are taken back only when this many rows of a screen…
+ static const _reattachAgree = 10;
+
+ /// …or this many, when every row that could agree did (a screen of short
+ /// content, 8 of 8, was turned away at ten, measured on a phone,
+ /// 2026-10-06)…
+ static const _reattachAgreeAll = 8;
+
+ /// …and this share of those that could, show them, with no other placing
+ /// near as good — see [_reattach].
+ static const _reattachShare = 0.9;
+
+ /// While the finger moves over rows already known, the program is let fall
+ /// this far behind it at most — see [_knownFarEnough].
+ static const _lazyReach = 48;
+
+ /// A page key unanswered this long went nowhere — the program at an end of
+ /// its transcript, or the key taken by something else. Not shorter: in a
+ /// long session Claude Code took 130ms and more to draw a page (p90,
+ /// measured on a phone, 2026-10-06).
+ static const _pageWait = Duration(milliseconds: 400);
+
+ /// A page shorter than this is not worth a key: wheel events do as well.
+ static const _minPage = 6;
+
+ /// A finger faster than this, in rows a second, is scrolled after with page
+ /// keys only — see [_pageOrWait]'s `fast`.
+ static const _pageSpeed = 120.0;
+
+ /// How long the program must have drawn nothing, and the finger been off the
+ /// glass, before the rows above are fetched ahead — see [_prefetch].
+ static const _prefetchAfter = Duration(milliseconds: 1200);
+
+ /// How many rows above the screen [_prefetch] has the document reach: three
+ /// or four screens of a phone.
+ static const _prefetchRows = 120;
+
+ /// About how fast the program scrolls, in rows a second: four wheel events
+ /// every 50ms (`_exactBurst` and `_burstGap` in the scroll handler) move it
+ /// ~80, less a margin for the link.
+ static const _programRowsPerSecond = 60.0;
/// How fast the screen catches up with the finger after being held at the
/// edge of what is known, in radians a second (a critically damped spring).
static const _omega = 40.0;
- /// The longest the program gets to come back to the row on screen.
+ /// The same spring while the screen comes after rows still arriving — the
+ /// finger past the edge of what is known ([_streaming]): softer, so each
+ /// page that lands is part of one glide rather than a step of its own.
+ ///
+ /// ⚠️ **At 40 the screen jumped to each page and stopped.** Rows come in a
+ /// page (~17) at a time, every 50–130ms in a long session; at [_omega] the
+ /// screen caught up with each in ~100ms and stood waiting for the next —
+ /// moving in pulses, ~15 a second (reported on a phone as stuttering,
+ /// 2026-10-06). At 20 a landing page is spread over the time to the next:
+ /// the screen moves on at the rate the rows come in, about a page behind
+ /// the newest of them.
+ static const _omegaStream = 20.0;
+
+ /// The least time between two looks for where the rows set aside belong:
+ /// with thousands of them, one look is thousands of comparisons, and every
+ /// frame of a scroll is a new screen to look for.
+ static const _reattachEvery = Duration(milliseconds: 150);
+
+ /// How long the program must have stood still after wheel events before a
+ /// page key goes — see [_wheelsGliding].
+ static const _wheelsSettle = Duration(milliseconds: 40);
+
+ /// The longest the program gets to come back to the row on screen without
+ /// moving — see [_armSettleTimer].
static const _settleLimit = Duration(milliseconds: 1500);
/// Ask again when the program has not moved for this long and nothing is out.
static const _resyncAfter = Duration(milliseconds: 120);
+ /// A finger that has not moved for this long has stopped — see [_dropLag].
+ static const _stillAfter = Duration(milliseconds: 100);
+
+ /// How long the program must have stood still before the screen goes back to
+ /// it — see [_checkSettled].
+ static const _settleQuiet = Duration(milliseconds: 100);
+
final _clock = Stopwatch()..start();
// The grid the document is in; any change and it is dropped.
@@ -79,6 +221,15 @@ class RemoteScrollMirror {
int? _top;
int? _bottom;
+ /// Screen rows that are the program's own — a pinned prompt above, a "jump
+ /// to bottom" line below — never taken into the rows that scroll. See
+ /// [_learnFixedRows].
+ final _fixedRows = <int>{};
+
+ /// How many placed frames running each screen row outside the rows that
+ /// moved stood still in — see [_learnFixedRows].
+ final _stoodStill = <int, int>{};
+
/// What the program's screen showed last, one entry per screen row: what a
/// new frame is compared with.
List<_Row>? _lastFrame;
@@ -87,13 +238,82 @@ class RemoteScrollMirror {
int _documentMin = 0;
int _documentMax = -1;
+ /// Rows known before the document last had to start again, in their own
+ /// numbering, and the first and last of them — see [_setAside].
+ Map<int, _DocRow>? _aside;
+ int _asideMin = 0;
+ int _asideMax = -1;
+
+ /// The screen [_reattach] last looked for among the rows set aside, and when.
+ int? _reattachTried;
+ int _reattachAtMs = -1 << 30;
+
+ /// Frames running not placed while the finger scrolls, the document kept
+ /// through them — see [_maxMissesInARow].
+ int _missesInARow = 0;
+
+ /// Whether the program's last whole screen showed its prompt — when a page
+ /// key scrolls its transcript ([_promptShown]).
+ bool _pageKeysSafe = false;
+
+ /// Whether a page key was refused this scroll: wheel events from then on.
+ bool _pageKeysRefused = false;
+
+ /// A page key on its way, which way, when, from which row, and whether
+ /// nothing else was — see [_pageOrWait] and [_pageLanded].
+ bool _pageInFlight = false;
+ int _pageDirection = 0;
+ int _pageSentAtMs = 0;
+ int _pageFromRemote = 0;
+
+ /// When wheel rows were last asked, and a page last landed — see
+ /// [_wheelsGliding].
+ int _wheelsAtMs = -1 << 30;
+ int _pageLandedAtMs = -1 << 30;
+
+ /// Whether the screen is coming after rows still arriving, on the softer
+ /// spring — see [_omegaStream].
+ bool _streaming = false;
+
+ /// Where what is known is kept between emulators and views — see
+ /// [RemoteScrollMemory].
+ RemoteScrollMemory? _memory;
+
+ /// Whether rows were learned since what is known was last kept in [_memory].
+ bool _learned = false;
+
+ /// Fetching rows ahead while nobody scrolls ([_prefetch]): the timer that
+ /// starts it, whether it runs, the program's row 0 it goes to, and since when.
+ Timer? _prefetchTimer;
+ bool _prefetching = false;
+ int _prefetchGoal = 0;
+ int _prefetchStartedAtMs = 0;
+
+ /// The document row the program's transcript starts at, once a page up went
+ /// nowhere: nothing above it to fetch.
+ int? _topRow;
+
+ /// Whether the last page key went nowhere ([_expirePage]).
+ bool _pageNowhere = false;
+
+ /// The program's own rows as they were when [_prefetch] began, drawn in
+ /// place of the live ones until it is over — see [heldRow] — and the
+ /// prompt's text then, which a key typed changes.
+ final _held = <int, BufferLine>{};
+ String? _heldPrompt;
+
/// The document row of the program's screen row 0.
int _remote = 0;
/// The document row the program has been asked to show at its row 0.
int _requested = 0;
int _requestedAtMs = 0;
- int _frameAtMs = 0;
+
+ /// Which way the program was last asked to scroll: -1 up, 1 down, 0 not yet.
+ int _askedDirection = 0;
+
+ /// When a frame last showed the program's rows moved.
+ int _movedAtMs = 0;
bool _scrolling = false;
bool _active = false;
@@ -109,9 +329,15 @@ class RemoteScrollMirror {
double _lastTarget = 0;
int _direction = 0;
- /// How fast the finger — or the fling — was moving, in rows a second.
+ /// How fast the finger — or the fling — was moving, in rows a second,
+ /// measured from [_velocityPixels] at [_velocityAtMs].
double _fingerVelocity = 0;
+ double _velocityPixels = 0;
+ int _velocityAtMs = 0;
+
+ /// When the finger last moved — by [_stillRows] or more, from [_stillPixels].
int _lastMoveMs = 0;
+ double _stillPixels = 0;
double _display = 0;
double _velocity = 0;
@@ -120,10 +346,19 @@ class RemoteScrollMirror {
Duration? _lastTick;
// Trace only.
+ ({int rows, int agree, int share, int? rival})? _miss;
int _framesAligned = 0;
int _framesLost = 0;
int _clampedUpdates = 0;
+ double _lagDropped = 0;
+ int _settleAsks = 0;
+ int _rowsGuarded = 0;
+ int _rowsMended = 0;
+ int _asksSpared = 0;
+ int _rowsAsked = 0;
+ int _pagesSent = 0;
int _startedAtMs = 0;
+ int _endedAtMs = 0;
/// Whether the rows that scroll are being drawn from here.
bool get isActive => _active;
@@ -142,21 +377,43 @@ class RemoteScrollMirror {
/// Document row [row], as last seen; null when it never has been.
BufferLine? rowAt(int row) => _document[row]?.line;
+ /// The program's own screen row [row] to draw in place of the live one —
+ /// held as it was while rows are fetched ahead ([_prefetch]), so its pinned
+ /// prompt and "jump to bottom" line, which come up as the program scrolls,
+ /// do not flash on a screen nobody scrolled. Null: draw the live row.
+ BufferLine? heldRow(int row) => _held[row];
+
+ /// Where what is known is kept between emulators and views — see
+ /// [RemoteScrollMemory]. Null keeps it in this mirror only.
+ RemoteScrollMemory? get memory => _memory;
+ set memory(RemoteScrollMemory? value) {
+ if (identical(value, _memory)) return;
+ // What is known belongs to the program it was learned from: kept there.
+ reset();
+ _memory = value;
+ }
+
int get _nowMs => _clock.elapsedMilliseconds;
/// A scroll began with the scrollable at [pixels]; [screen]'s first
- /// [rowCount] rows are what the program shows now.
+ /// [rowCount] rows are what the program shows now — read only when
+ /// [screenWhole]: not while a frame of the program's is still arriving,
+ /// part old and part new (see `RenderTerminal._updateRemoteScroll`).
void begin(
double pixels,
IndexAwareCircularBuffer<BufferLine> screen,
int rowCount,
- double lineHeight,
- ) {
+ double lineHeight, {
+ bool screenWhole = true,
+ }) {
if (_scrolling) return;
if (!_sameGrid(screen, rowCount, lineHeight)) {
_forget();
_takeGrid(screen, rowCount, lineHeight);
+ _load();
}
+ // Fetching ahead gives way to the finger: what it asked is still counted.
+ _stopPrefetch();
_scrolling = true;
_settling = false;
_settleTimer?.cancel();
@@ -165,10 +422,20 @@ class RemoteScrollMirror {
_framesAligned = 0;
_framesLost = 0;
_clampedUpdates = 0;
+ _lagDropped = 0;
+ _settleAsks = 0;
+ _rowsGuarded = 0;
+ _rowsMended = 0;
+ _asksSpared = 0;
+ _rowsAsked = 0;
+ _pagesSent = 0;
+ _pageKeysRefused = false;
_resyncs = 0;
+ _missesInARow = 0;
+ if (screenWhole) _readPrompt(screen, rowCount);
// The document may be from the last scroll; the screen may have moved
// since, under output. This frame says where it is now, or that it is gone.
- _frame(screen, rowCount);
+ if (screenWhole) _frame(screen, rowCount);
_anchorPixels = pixels;
_lastPixels = pixels;
_anchorRow = _active ? _display : _remote.toDouble();
@@ -179,13 +446,18 @@ class RemoteScrollMirror {
if (!_active) _requested = _remote;
_direction = 0;
_fingerVelocity = 0;
+ _velocityPixels = pixels;
+ _velocityAtMs = _nowMs;
_lastMoveMs = _nowMs;
+ _stillPixels = pixels;
if (!_active) _display = _remote.toDouble();
_activateIfReady();
inputTrace(
() => 'mirror: begin · ${_document.length} rows known'
' (${_documentMin - _remote}..${_documentMax - _remote} from the screen)'
- ' · scrolling rows ${_top ?? '?'}..${_bottom ?? '?'}',
+ '${_aside == null ? '' : ' · ${_aside!.length} set aside'}'
+ ' · scrolling rows ${_top ?? '?'}..${_bottom ?? '?'}'
+ '${pageKeysEnabled?.call() ?? false ? ' · page keys ${_pageKeysSafe ? 'on' : 'off, no prompt on screen'}' : ''}',
);
}
@@ -194,21 +466,33 @@ class RemoteScrollMirror {
double pixels,
IndexAwareCircularBuffer<BufferLine> screen,
int rowCount,
- double lineHeight,
- ) {
- if (!_scrolling) begin(pixels, screen, rowCount, lineHeight);
+ double lineHeight, {
+ bool screenWhole = true,
+ }) {
+ if (!_scrolling) {
+ begin(pixels, screen, rowCount, lineHeight, screenWhole: screenWhole);
+ }
if (!_scrolling || _lineHeight <= 0) return;
_lastPixels = pixels;
_lastTarget = _target;
_target = _anchorRow + (pixels - _anchorPixels) / _lineHeight;
- final moved = _target - _lastTarget;
- if (moved.abs() > 1e-6) _direction = moved > 0 ? 1 : -1;
final now = _nowMs;
- final elapsed = now - _lastMoveMs;
- if (elapsed >= 4) {
- _fingerVelocity = moved * 1000 / elapsed;
+ // Moved, not merely held: a finger at rest on the glass still reports a
+ // pixel or two either way. Counted as moves, it was never still — and the
+ // screen went on catching up with it (see [_dropLag]).
+ final moved = pixels - _stillPixels;
+ if (moved.abs() >= _stillRows * _lineHeight) {
+ _direction = moved > 0 ? 1 : -1;
+ _stillPixels = pixels;
_lastMoveMs = now;
}
+ final elapsed = now - _velocityAtMs;
+ if (elapsed >= 8) {
+ _fingerVelocity =
+ (pixels - _velocityPixels) / _lineHeight * 1000 / elapsed;
+ _velocityPixels = pixels;
+ _velocityAtMs = now;
+ }
_follow();
_requestRemote();
if (_active) onFrame();
@@ -219,39 +503,123 @@ class RemoteScrollMirror {
if (!_scrolling) return;
_scrolling = false;
_direction = 0;
+ if (_missesInARow > 0) {
+ // Where the program is was never found again: it cannot be brought back
+ // to the row on screen, so the screen goes to the program's — the rows
+ // known set aside, to be taken back ([_reattach]).
+ _missesInARow = 0;
+ _lost();
+ }
if (!_active) {
- // Never shown from here: the program was only ever followed.
+ // Never shown from here: the program was only ever followed — and stops
+ // with the finger, so what waits for it is not sent.
+ _requested -= cancelRequests();
inputTrace(() => 'mirror: end · never shown from the document');
return;
}
_settling = true;
- _target = _target.roundToDouble();
- _settleTimer?.cancel();
- _settleTimer = Timer(_settleLimit, _settleTimedOut);
+ _endedAtMs = _nowMs;
+ _armSettleTimer();
+ final still = _fingerStill;
// ⚠️ Glided to the whole row, never set there: the last step of a fling is
// often bigger than what is left to the row, and following exactly would
// jump it. Starting at the finger's own speed, so the scroll does not stop
- // dead before it eases in.
+ // dead before it eases in — but only if it was still moving as it let go:
+ // the speed it last moved at, long before, glided on by itself.
if (!_chasing) {
_chasing = true;
- _velocity = _fingerVelocity.clamp(-40.0, 40.0);
+ _velocity = still ? 0.0 : _fingerVelocity.clamp(-40.0, 40.0);
}
- _requestRemote();
+ // The row the screen comes to rest on from where it is — not the row the
+ // finger got to, which the screen may be behind: see [_capLag].
+ _target = _restingRow().roundToDouble();
+ // From here the screen only glides to that row: a change in what is known
+ // is chased, never jumped by a stride the finger once took.
+ _lastTarget = _target;
+ // What still waits to go out was for where the finger was going.
+ final dropped = cancelRequests();
+ _requested -= dropped;
+ inputTrace(
+ () => 'mirror: end · finger'
+ ' ${still ? 'still' : 'at ${_fingerVelocity.round()} rows/s'}'
+ ' · resting on row ${_target.round()}'
+ ' (screen at ${_display.toStringAsFixed(1)}) · program at $_remote,'
+ ' asked to $_requested · $dropped waiting rows dropped',
+ );
+ _settleStep();
_scheduleTick();
}
+ /// The program has [_settleLimit] to come back to the row on screen — from
+ /// the last time it moved, not from when the scroll ended.
+ ///
+ /// ⚠️ **A long way back takes as long as it takes.** Over rows seen before,
+ /// the screen runs far ahead of a program that scrolls ~80 rows a second:
+ /// coming back 250 rows took 3s, and a limit from the scroll's end showed the
+ /// program's row after 1.5s — the screen jumping 130 rows by itself
+ /// (measured on a phone, 2026-10-06). The limit is for a program that has
+ /// stopped coming.
+ void _armSettleTimer() {
+ _settleTimer?.cancel();
+ _settleTimer = Timer(_settleLimit, _settleTimedOut);
+ }
+
+ /// Whether the finger has not moved [_stillRows] for [_stillAfter]: held
+ /// still, or let go without a fling.
+ bool get _fingerStill => _nowMs - _lastMoveMs >= _stillAfter.inMilliseconds;
+
+ /// The row the screen comes to rest on from where it is, moving as it is: a
+ /// critically damped spring set off at speed `v` covers `v / ω` more.
+ double _restingRow() => _clamp(_display + _velocity / _omegaNow);
+
+ /// The spring the screen moves on now — see [_omegaStream].
+ double get _omegaNow => _streaming ? _omegaStream : _omega;
+
+ /// What the screen is behind the finger is let go once the finger has
+ /// stopped: the screen comes to rest where it is, and the finger's next move
+ /// counts from there.
+ ///
+ /// ⚠️ **The screen moves only while the finger does.** Held at the edge of
+ /// what is known, the screen falls behind a fast finger, and it used to
+ /// catch up after the finger stopped — scrolling on by itself, the finger
+ /// still or already lifted (reported on a phone, 2026-10-06).
+ void _dropLag() {
+ if (!_scrolling || !_active || !_fingerStill) return;
+ final rest = _restingRow();
+ if ((_target - rest).abs() < 0.5) return;
+ _anchorRow = rest;
+ _anchorPixels = _lastPixels;
+ _target = rest;
+ _lastTarget = rest;
+ _requested -= cancelRequests();
+ _requestRemote();
+ }
+
/// A whole frame from the program: [screen]'s first [rowCount] rows.
void frame(
IndexAwareCircularBuffer<BufferLine> screen,
int rowCount,
double lineHeight,
) {
- if (!_scrolling && !_active) return;
+ if (!_scrolling && !_active) {
+ // The program drew: fetching ahead waits until it has been quiet.
+ _armPrefetch();
+ return;
+ }
if (!_sameGrid(screen, rowCount, lineHeight)) {
inputTrace(() => 'mirror: the grid changed — back to the live screen');
reset();
return;
}
+ _readPrompt(screen, rowCount);
+ if (_held.isNotEmpty && _promptText(screen, rowCount) != _heldPrompt) {
+ // A key typed while rows were fetched ahead: the program's own rows are
+ // drawn live again, and it is brought back to the row on screen.
+ inputTrace(() => 'mirror: typed into while fetching ahead — back');
+ _held.clear();
+ if (_prefetching) _endPrefetch();
+ onFrame();
+ }
_frame(screen, rowCount);
_activateIfReady();
if (!_active) {
@@ -260,14 +628,24 @@ class RemoteScrollMirror {
return;
}
_follow();
- _requestRemote();
- _checkSettled();
+ if (_prefetching) {
+ _prefetchStep();
+ } else if (_settling) {
+ _settleStep();
+ } else {
+ _requestRemote();
+ }
onFrame();
}
/// Everything dropped: the document, the scroll, the drawing from here.
void reset() {
final wasActive = _active;
+ cancelRequests();
+ _prefetchTimer?.cancel();
+ _prefetchTimer = null;
+ _stopPrefetch();
+ _save();
_scrolling = false;
_settling = false;
_settleTimer?.cancel();
@@ -275,16 +653,22 @@ class RemoteScrollMirror {
_cancelTick();
_active = false;
_chasing = false;
+ _streaming = false;
_velocity = 0;
+ _missesInARow = 0;
_forget();
if (wasActive) onFrame();
}
void dispose() {
+ _save();
_settleTimer?.cancel();
_settleTimer = null;
+ _prefetchTimer?.cancel();
+ _prefetchTimer = null;
_cancelTick();
_document.clear();
+ _aside = null;
_lastFrame = null;
}
@@ -311,13 +695,91 @@ class RemoteScrollMirror {
_columns = rowCount > 0 && screen.length > 0 ? screen[0].length : 0;
}
+ /// What is known — the rows, which of them scroll, which are the program's
+ /// own — kept in [_memory], for the next emulator or view of this program.
+ /// The rows kept are the document's, or the rows set aside, whichever are
+ /// more.
+ void _save() {
+ final memory = _memory;
+ final top = _top;
+ final bottom = _bottom;
+ if (memory == null || !_learned || _rowCount == 0) return;
+ if (top == null || bottom == null) return;
+ final aside = _aside;
+ final useAside = aside != null && aside.length > _document.length;
+ var rows = useAside ? aside : _document;
+ var rowsMin = useAside ? _asideMin : _documentMin;
+ var rowsMax = useAside ? _asideMax : _documentMax;
+ // At most [RemoteScrollMemory.rowsKept], around where the screen was.
+ if (rows.length > RemoteScrollMemory.rowsKept) {
+ final centre = useAside ? (rowsMin + rowsMax) ~/ 2 : _remote;
+ final low = centre - RemoteScrollMemory.rowsKept ~/ 2;
+ final high = low + RemoteScrollMemory.rowsKept;
+ rows = {
+ for (final entry in rows.entries)
+ if (entry.key >= low && entry.key < high) entry.key: entry.value,
+ };
+ rowsMin = math.max(rowsMin, low);
+ rowsMax = math.min(rowsMax, high - 1);
+ } else {
+ rows = Map.of(rows);
+ }
+ memory._keep(
+ _gridKey,
+ _Known(
+ rows: rows.isEmpty ? null : rows,
+ rowsMin: rowsMin,
+ rowsMax: rowsMax,
+ top: top,
+ bottom: bottom,
+ fixedRows: {..._fixedRows},
+ ),
+ );
+ _learned = false;
+ }
+
+ /// The grid the document is in, as [RemoteScrollMemory] tells grids apart.
+ String get _gridKey => '$_rowCount×$_columns@$_lineHeight';
+
+ /// What [_memory] knows of this grid: which rows scroll and which are the
+ /// program's own, at once — and the rows seen, set aside, to be found again
+ /// in what the program shows ([_reattach]). Nothing, for another grid: its
+ /// rows wrap otherwise.
+ void _load() {
+ final known = _memory?._grids[_gridKey];
+ if (known == null) return;
+ _top = known.top;
+ _bottom = known.bottom;
+ _fixedRows
+ ..clear()
+ ..addAll(known.fixedRows);
+ final rows = known.rows;
+ if (rows != null && rows.isNotEmpty) {
+ _aside = rows;
+ _asideMin = known.rowsMin;
+ _asideMax = known.rowsMax;
+ _reattachTried = null;
+ }
+ inputTrace(
+ () => 'mirror: remembered · scrolling rows $_top..$_bottom'
+ ' · ${rows?.length ?? 0} rows set aside',
+ );
+ }
+
void _forget() {
_document.clear();
_documentMin = 0;
_documentMax = -1;
+ // Rows of another grid: wrapped at another width, nothing to take back.
+ _aside = null;
+ _pageInFlight = false;
+ _topRow = null;
+ _learned = false;
_lastFrame = null;
_top = null;
_bottom = null;
+ _fixedRows.clear();
+ _stoodStill.clear();
_remote = 0;
_requested = 0;
_rowCount = 0;
@@ -329,13 +791,21 @@ class RemoteScrollMirror {
/// finds, and writes the scrolling rows into the document.
void _frame(IndexAwareCircularBuffer<BufferLine> screen, int rowCount) {
if (screen.length < rowCount) return;
- _frameAtMs = _nowMs;
final rows = [
for (var i = 0; i < rowCount; i++) _Row.of(screen[i]),
];
final last = _lastFrame;
_lastFrame = rows;
- if (last == null || last.length != rowCount) return;
+ if (last == null || last.length != rowCount) {
+ // The first screen of an emulator whose scrolling rows are known — from
+ // [_memory]: written in where it stands, and what was known before is
+ // looked for in it ([_reattach]). A scroll can start from it at once.
+ if (_top != null && _bottom != null && _document.isEmpty) {
+ _store(screen);
+ _reattach(rows);
+ }
+ return;
+ }
// The rows that differ from the last frame where they stand.
final changed = <int>[
@@ -348,22 +818,107 @@ class RemoteScrollMirror {
? changed.length
: changed.where((i) => i >= top && i <= bottom).length;
if (changedScrolling < 3) {
- // Nothing that scrolls moved: a spinner, a prompt row, a cursor.
- _store(screen);
+ // Nothing that scrolls moved: a spinner, a prompt row, a cursor — unless
+ // the program has rows asked of it still to answer: then it may be a
+ // scroll over rows too alike to tell apart, and written in where they
+ // stand, its rows would go where they do not belong. Nor while where the
+ // program is has not been found since a frame went unplaced.
+ if (_requested == _remote && requestsIdle() && _missesInARow == 0) {
+ _store(screen);
+ _reattach(rows);
+ }
return;
}
final shift = _align(rows, last, changed);
+ if (shift == null &&
+ _requested == _remote &&
+ requestsIdle() &&
+ !_pageInFlight &&
+ _missesInARow == 0) {
+ // Nothing asked of the program is on its way, so it did not scroll: its
+ // screen changed where it stands — an agent writing, a tool's result
+ // unfolding (11 of 59 frames lost, measured on a phone, 2026-10-06). The
+ // rows known around it may be stale now, so the document starts again
+ // from this screen, but where it stands: the screen does not jump. What
+ // was known is set aside, not thrown away: most of it is likely still
+ // the program's content, only moved.
+ inputTrace(
+ () => 'mirror: the screen changed where it stands — the document'
+ ' starts again from it, in place',
+ );
+ _setAside();
+ _document.clear();
+ _documentMin = 0;
+ _documentMax = -1;
+ _topRow = null;
+ _store(screen);
+ _reattach(rows);
+ return;
+ }
+ final scrolling =
+ top == null || bottom == null ? rowCount : bottom - top + 1;
+ if (shift == null && changedScrolling * 3 < scrolling) {
+ // Too few rows changed to be sure of anything: a scroll moves nearly
+ // every row, but over mostly blank rows it may not. Thrown away as lost,
+ // the document started again for a few rows redrawn; written in where
+ // they stand, a small scroll's rows went in where they did not belong.
+ // Neither: the document stays as it is, and the next frame says more.
+ inputTrace(
+ () => 'mirror: $changedScrolling rows changed, not placed'
+ ' — the document left as it is',
+ );
+ return;
+ }
if (shift == null) {
_framesLost++;
+ _traceMiss(screen, rowCount, changed.length);
+ if (_scrolling &&
+ _active &&
+ _document.isNotEmpty &&
+ _missesInARow < _maxMissesInARow) {
+ // The screen goes on from the document; the frame is not written in,
+ // and the next one says where the program is — see [_maxMissesInARow].
+ _missesInARow++;
+ inputTrace(
+ () => 'mirror: frame not placed — the document kept'
+ ' ($_missesInARow running)',
+ );
+ return;
+ }
+ _missesInARow = 0;
_lost();
_store(screen);
+ _reattach(rows);
return;
}
+ _missesInARow = 0;
_framesAligned++;
+ inputTrace(
+ () => 'mirror: placed k=${shift.rows} (expected ${_requested - _remote})'
+ ' · rows ${shift.first}..${shift.last} agreed'
+ ' ${shift.agreeing.length}/${shift.share}',
+ );
_remote += shift.rows;
+ _movedAtMs = _nowMs;
+ if (_pageInFlight) _pageLanded();
+ // Gone further than it was asked: Claude Code speeds up wheel events it
+ // reads together — as it does when busy drawing, however far apart they
+ // were sent (2,583 rows moved for 1,875 wheels, measured on a phone,
+ // 2026-10-06). The books follow it, or it is asked onwards from rows it
+ // has passed already, and runs further still. What still waits to go out
+ // would take it further again: not sent.
+ if (_askedDirection > 0 && _remote > _requested ||
+ _askedDirection < 0 && _remote < _requested) {
+ cancelRequests();
+ _requested = _remote;
+ }
+ if (_settling) _armSettleTimer();
+ _confirmRows(shift);
+ _learnFixedRows(shift, rows, last);
_widenScrollingRows(shift, rows, last);
- _store(screen);
+ _store(screen, shift);
+ _reattach(rows);
}
/// The shift that turned what is known into [rows] — [rows] screen row `i`
@@ -384,23 +939,51 @@ class RemoteScrollMirror {
}
final expected = _requested - _remote;
- final reach = _rowCount + 2 * _lead;
+ final reach = _rowCount + 2 * _leadMax;
final scores = <({int rows, int agree, int share})>[];
- for (var k = -reach; k <= reach; k++) {
- if (k == 0) continue;
- var agree = 0;
- var comparable = 0;
- for (final i in changed) {
- final signature = known(_remote + k + i);
- if (signature == null) continue;
- comparable++;
- if (signature == rows[i].signature) agree++;
- }
- if (agree >= _minAgree && agree >= comparable * _minAgreeShare) {
- scores.add((rows: k, agree: agree, share: comparable));
+ // Trace only: the closest any shift came, for when none is good enough.
+ ({int rows, int agree, int share})? closest;
+ void score(int from, int to) {
+ for (var k = from; k <= to; k++) {
+ if (k == 0) continue;
+ var agree = 0;
+ var comparable = 0;
+ for (final i in changed) {
+ final signature = known(_remote + k + i);
+ if (signature == null) continue;
+ comparable++;
+ if (signature == rows[i].signature) agree++;
+ }
+ final best = closest;
+ if (best == null || agree > best.agree) {
+ closest = (rows: k, agree: agree, share: comparable);
+ }
+ if (agree >= _minAgree && agree >= comparable * _minAgreeShare) {
+ scores.add((rows: k, agree: agree, share: comparable));
+ }
}
}
- if (scores.isEmpty) return null;
+
+ // Only as far as the program can have gone: it is never asked more than
+ // [_maxAhead] past where it was seen. Looking through the whole document
+ // found rows that repeat further off, and placed frames there.
+ score(-reach, reach);
+ if (scores.isEmpty && !useLast) {
+ final far = _alignFar(rows, reach);
+ if (far != null) return far;
+ }
+ if (scores.isEmpty) {
+ final best = closest;
+ _miss = best == null
+ ? null
+ : (
+ rows: best.rows,
+ agree: best.agree,
+ share: best.share,
+ rival: null
+ );
+ return null;
+ }
scores.sort((a, b) => b.agree.compareTo(a.agree));
final best = scores.first;
var chosen = best;
@@ -418,18 +1001,210 @@ class RemoteScrollMirror {
(s.rows - expected).abs() == (chosen.rows - expected).abs() &&
s.agree * 10 >= best.agree * 8,
);
- if (rivals.isNotEmpty) return null;
+ if (rivals.isNotEmpty) {
+ _miss = (
+ rows: chosen.rows,
+ agree: chosen.agree,
+ share: chosen.share,
+ rival: rivals.first.rows,
+ );
+ return null;
+ }
}
// The rows that moved with it: what bounds the scrolling rows.
- var first = -1;
- var lastRow = -1;
- for (final i in changed) {
- if (known(_remote + chosen.rows + i) == rows[i].signature) {
- if (first < 0) first = i;
- lastRow = i;
+ return _Shift(
+ chosen.rows,
+ [
+ for (final i in changed)
+ if (known(_remote + chosen.rows + i) == rows[i].signature) i,
+ ],
+ chosen.share,
+ );
+ }
+
+ /// [rows] placed further off than [reach] — anywhere in the document — held
+ /// to what [_reattach] is, or null.
+ ///
+ /// ⚠️ **Claude Code goes further than it is asked, now and then.** Asked 24
+ /// rows, its screen was 70 and more away (beyond [reach]) — and every time
+ /// the rows were in the document: the frame was let go, the screen jumped to
+ /// the program's, and the rows set aside for it matched that screen 34 of 34
+ /// a moment later (measured on a phone, 2026-10-06). Placed here, the screen
+ /// goes on from the document instead. Looked for this far only under
+ /// [_reattach]'s bar, never [_align]'s: rows repeat in a transcript, and a
+ /// looser match this far off placed frames among them.
+ _Shift? _alignFar(List<_Row> rows, int reach) {
+ final top = _top;
+ final bottom = _bottom;
+ if (top == null || bottom == null || _documentMax < _documentMin) {
+ return null;
+ }
+ final probe = _probeRows(rows);
+ final found = _bestPlacing(
+ probe,
+ rows,
+ _document,
+ _documentMin - _remote,
+ _documentMax - _remote,
+ skip: (k) => k.abs() <= reach,
+ );
+ if (found == null || !_sureOf(found)) return null;
+ inputTrace(
+ () => 'mirror: placed far off · k=${found.d}'
+ ' (expected ${_requested - _remote})'
+ ' · ${found.agree}/${found.share} rows agreed',
+ );
+ return _Shift(
+ found.d,
+ [
+ for (final i in probe)
+ if (_document[_remote + found.d + i]?.signature == rows[i].signature)
+ i,
+ ],
+ found.share,
+ );
+ }
+
+ /// The screen rows a placing far off is judged by: content in the rows that
+ /// scroll — not blank, not the program's own.
+ List<int> _probeRows(List<_Row> rows) {
+ final top = _top;
+ final bottom = _bottom;
+ if (top == null || bottom == null) return const [];
+ return [
+ for (var i = top; i <= bottom && i < rows.length; i++)
+ if (!rows[i].blank && !_fixedRows.contains(i)) i,
+ ];
+ }
+
+ /// The placing of [probe] rows of [rows] in [known] that most agree: screen
+ /// row `i` showing `known[_remote + i + d]`, for every `d` that puts a probe
+ /// row between [knownMin] and [knownMax] — and how many agree with the next
+ /// best placing. Null when none agrees at all.
+ ({int d, int agree, int share, int runnerUp})? _bestPlacing(
+ List<int> probe,
+ List<_Row> rows,
+ Map<int, _DocRow> known,
+ int knownMin,
+ int knownMax, {
+ bool Function(int d)? skip,
+ }) {
+ if (probe.isEmpty) return null;
+ ({int d, int agree, int share})? best;
+ var runnerUp = 0;
+ for (var d = knownMin - probe.last; d <= knownMax - probe.first; d++) {
+ if (skip != null && skip(d)) continue;
+ var agree = 0;
+ var comparable = 0;
+ for (final i in probe) {
+ final kept = known[_remote + i + d];
+ if (kept == null) continue;
+ comparable++;
+ if (kept.signature == rows[i].signature) agree++;
+ }
+ if (agree == 0) continue;
+ final current = best;
+ if (current == null || agree > current.agree) {
+ if (current != null) runnerUp = math.max(runnerUp, current.agree);
+ best = (d: d, agree: agree, share: comparable);
+ } else {
+ runnerUp = math.max(runnerUp, agree);
}
}
- return _Shift(chosen.rows, first, lastRow);
+ final found = best;
+ if (found == null) return null;
+ return (
+ d: found.d,
+ agree: found.agree,
+ share: found.share,
+ runnerUp: runnerUp,
+ );
+ }
+
+ /// Whether a placing found far off ([_bestPlacing]) leaves no doubt:
+ /// [_reattachAgree] rows agreeing — or [_reattachAgreeAll], when every row
+ /// that could agreed — and [_reattachShare] of those that could, with the
+ /// next best placing well behind.
+ bool _sureOf(({int d, int agree, int share, int runnerUp}) found) {
+ final enough = found.agree >= _reattachAgree ||
+ found.agree >= _reattachAgreeAll && found.agree == found.share;
+ return enough &&
+ found.agree >= found.share * _reattachShare &&
+ found.runnerUp * 10 < found.agree * 6;
+ }
+
+ /// The document rows [shift] found where the program now shows them: seen
+ /// moving with the content, so content ([_DocRow.confirmed]) — and a screen
+ /// row that moved with it scrolls, whatever it showed before.
+ void _confirmRows(_Shift shift) {
+ for (final i in shift.agreeing) {
+ _document[_remote + i]?.confirmed = true;
+ _stoodStill.remove(i);
+ if (_fixedRows.remove(i)) {
+ inputTrace(() => 'mirror: row $i scrolls again');
+ }
+ }
+ }
+
+ /// Rows the program keeps where they are while its content scrolls, learned
+ /// from placed frames: outside the rows that agreed, a row that stood still
+ /// in two running. One is not enough — content that came in with the scroll
+ /// may stand where a row of the same text stood, by chance, and a pinned row
+ /// covering content is told apart in [_store] meanwhile.
+ ///
+ /// ⚠️ **Taken for content, they went into the document.** Claude Code pins
+ /// the prompt of the rows on screen to row 0 once that prompt has scrolled
+ /// off, and puts a "jump to bottom" line over its last rows; the scrolling
+ /// rows were widened over both, written into the document as rows of it, and
+ /// the screen, drawn from it, showed them among the content — out of order
+ /// (`scrolling rows 0..35` six times in one session, reported on a phone,
+ /// 2026-10-06). What such a row wrote in and nothing has seen move since is
+ /// taken out again ([_purgeWrittenFrom]).
+ void _learnFixedRows(_Shift shift, List<_Row> rows, List<_Row> last) {
+ final first = shift.first;
+ final lastAgreed = shift.last;
+ if (first < 0) return;
+ for (var i = 0; i < rows.length; i++) {
+ if (i >= first && i <= lastAgreed) continue;
+ if (_fixedRows.contains(i)) continue;
+ final row = rows[i];
+ if (row.blank || row.signature != last[i].signature) {
+ _stoodStill.remove(i);
+ continue;
+ }
+ final times = (_stoodStill[i] ?? 0) + 1;
+ if (times < 2) {
+ _stoodStill[i] = times;
+ continue;
+ }
+ _stoodStill.remove(i);
+ _fixedRows.add(i);
+ _learned = true;
+ final purged = _purgeWrittenFrom(i);
+ inputTrace(
+ () => 'mirror: row $i is the program\'s own'
+ '${purged > 0 ? ' · $purged rows it wrote taken out' : ''}',
+ );
+ }
+ }
+
+ /// Document rows written from screen row [i] while it came in with a scroll,
+ /// and never seen moving since: out. A hole is drawn as nothing until the
+ /// program shows that row again — better than a row out of place.
+ int _purgeWrittenFrom(int i) {
+ final before = _document.length;
+ _document.removeWhere((_, row) => row.fromRow == i && !row.confirmed);
+ final purged = before - _document.length;
+ if (purged > 0) {
+ if (_document.isEmpty) {
+ _documentMin = 0;
+ _documentMax = -1;
+ } else {
+ _documentMin = _document.keys.reduce(math.min);
+ _documentMax = _document.keys.reduce(math.max);
+ }
+ }
+ return purged;
}
/// The scrolling rows: those the shift moved, and next to them the rows that
@@ -437,16 +1212,17 @@ class RemoteScrollMirror {
void _widenScrollingRows(_Shift shift, List<_Row> rows, List<_Row> last) {
bool stoodStill(int i) =>
!rows[i].blank && rows[i].signature == last[i].signature;
+ bool fixed(int i) => _fixedRows.contains(i);
var top = shift.first;
var bottom = shift.last;
if (top < 0) return;
// Rows come in on the side the content moves away from.
for (var n = 0; n < shift.rows.abs() && top > 0; n++) {
- if (shift.rows > 0 || stoodStill(top - 1)) break;
+ if (shift.rows > 0 || stoodStill(top - 1) || fixed(top - 1)) break;
top--;
}
for (var n = 0; n < shift.rows.abs() && bottom < _rowCount - 1; n++) {
- if (shift.rows < 0 || stoodStill(bottom + 1)) break;
+ if (shift.rows < 0 || stoodStill(bottom + 1) || fixed(bottom + 1)) break;
bottom++;
}
final known = _top != null && _bottom != null;
@@ -454,31 +1230,62 @@ class RemoteScrollMirror {
var newBottom = known ? math.max(_bottom!, bottom) : bottom;
// A row at the edge that stood still while everything else moved is the
// program's own — a status line — and not part of what scrolls.
- while (newTop < newBottom && stoodStill(newTop) && newTop < shift.first) {
+ while (newTop < newBottom &&
+ (fixed(newTop) || stoodStill(newTop) && newTop < shift.first)) {
newTop++;
}
- while (
- newBottom > newTop && stoodStill(newBottom) && newBottom > shift.last) {
+ while (newBottom > newTop &&
+ (fixed(newBottom) || stoodStill(newBottom) && newBottom > shift.last)) {
newBottom--;
}
if (newTop != _top || newBottom != _bottom) {
inputTrace(() => 'mirror: scrolling rows $newTop..$newBottom');
+ _learned = true;
}
_top = newTop;
_bottom = newBottom;
}
- /// The program's scrolling rows into the document, at [_remote].
- void _store(IndexAwareCircularBuffer<BufferLine> screen) {
+ /// The program's scrolling rows into the document, at [_remote] — moved there
+ /// by [shift], or where they stood when null.
+ void _store(IndexAwareCircularBuffer<BufferLine> screen, [_Shift? shift]) {
final top = _top;
final bottom = _bottom;
if (top == null || bottom == null) return;
+ final agreeing = shift?.agreeing.toSet() ?? const <int>{};
for (var i = top; i <= bottom; i++) {
+ // The program's own row, inside the rows that scroll: never content.
+ if (_fixedRows.contains(i)) continue;
final row = _remote + i;
final line = screen[i];
final kept = _document[row];
if (kept != null && kept.sameCells(line)) continue;
- _document[row] = _DocRow.copyOf(line);
+ final signature = _Row.of(line).signature;
+ var confirmed = agreeing.contains(i);
+ if (kept != null && kept.confirmed) {
+ if (kept.signature == signature) {
+ // The same text in other colours.
+ confirmed = true;
+ } else if (shift != null && (i < shift.first || i > shift.last)) {
+ // Content seen moving, contradicted only outside the rows that moved
+ // with this scroll: a row of the program's own over it, not yet
+ // learned for one ([_learnFixedRows]) — kept out.
+ _rowsGuarded++;
+ continue;
+ }
+ }
+ if (shift != null &&
+ kept != null &&
+ !kept.confirmed &&
+ kept.signature != signature) {
+ // Never seen moving, and now shown otherwise: put right.
+ _rowsMended++;
+ }
+ // Written where it stood (no [shift]), a row has no screen row it came in
+ // at, to be taken out by later: nothing tells it from content there.
+ _document[row] = _DocRow.copyOf(line, signature, shift == null ? null : i)
+ ..confirmed = confirmed;
+ _learned = true;
}
final first = _remote + top;
final last = _remote + bottom;
@@ -489,26 +1296,161 @@ class RemoteScrollMirror {
_documentMin = math.min(_documentMin, first);
_documentMax = math.max(_documentMax, last);
}
- // Only what a scroll could come back to.
- if (_documentMax - _documentMin > 2 * _keepRows + _rowCount) {
- final low = _remote - _keepRows;
- final high = _remote + _rowCount + _keepRows;
- _document.removeWhere((row, _) => row < low || row > high);
- _documentMin = math.max(_documentMin, low);
- _documentMax = math.min(_documentMax, high);
+ _trim();
+ }
+
+ /// Only what a scroll could come back to — around the screen as well as the
+ /// program: over rows seen before the screen runs far ahead of it, and rows
+ /// dropped from under it were drawn as nothing.
+ void _trim() {
+ if (_documentMax - _documentMin <= 2 * _keepRows + _rowCount) return;
+ final shown = _active ? _display.round() : _remote;
+ final low = math.min(_remote, shown) - _keepRows;
+ final high = math.max(_remote, shown) + _rowCount + _keepRows;
+ _document.removeWhere((row, _) => row < low || row > high);
+ _documentMin = math.max(_documentMin, low);
+ _documentMax = math.min(_documentMax, high);
+ }
+
+ /// The document put aside before it starts again, not thrown away: its rows
+ /// are still the program's content — only where they stand against the
+ /// program's screen is no longer known. [_reattach] takes them back.
+ void _setAside() {
+ if (_document.isEmpty) return;
+ final aside = _aside;
+ // The bigger of the two: a document just started again from one screen is
+ // worth less than the one set aside before it.
+ if (aside != null && aside.length >= _document.length) return;
+ _aside = Map.of(_document);
+ _asideMin = _document.keys.reduce(math.min);
+ _asideMax = _document.keys.reduce(math.max);
+ _reattachTried = null;
+ inputTrace(() => 'mirror: ${_document.length} rows set aside');
+ }
+
+ /// Rows set aside ([_setAside]) back into the document, once the program's
+ /// screen — [rows], placed at [_remote] — is found among them: then the
+ /// rest of them stand where that says. Scrolled back over, they are drawn at
+ /// once instead of waited for.
+ ///
+ /// ⚠️ **Matched across all of them, so held to more than [_align] is.** Rows
+ /// repeat in a transcript, and the further a match is looked for the likelier
+ /// one that is not the screen's (looking through the whole document placed
+ /// frames among repeated rows, measured on a phone, 2026-10-06). Taken back
+ /// only on a placing that leaves no doubt ([_sureOf]); otherwise they wait
+ /// for a frame that does. Where the program shows a row differently later,
+ /// [_store] writes over it, as it does any row it shows.
+ void _reattach(List<_Row> rows) {
+ final aside = _aside;
+ final top = _top;
+ final bottom = _bottom;
+ if (aside == null || top == null || bottom == null) return;
+ final probe = _probeRows(rows);
+ if (probe.length < _reattachAgreeAll) return;
+ // The same screen at the same place, already looked for: a spinner redrawn
+ // on it says nothing new.
+ var key = _remote;
+ for (final i in probe) {
+ key = 0x1fffffff & (key * 31 + rows[i].signature);
+ }
+ if (key == _reattachTried) return;
+ final now = _nowMs;
+ if (now - _reattachAtMs < _reattachEvery.inMilliseconds) return;
+ _reattachTried = key;
+ _reattachAtMs = now;
+ // Set-aside row `_remote + i + d` is what the screen's row `i` shows.
+ final found = _bestPlacing(
+ probe,
+ rows,
+ aside,
+ _asideMin - _remote,
+ _asideMax - _remote,
+ );
+ if (found == null || !_sureOf(found)) {
+ // Trace only, and only when the screen came close: what kept it out, to
+ // tune [_reattachAgree] and [_reattachShare] by.
+ if (found != null && found.agree * 2 >= _reattachAgree) {
+ inputTrace(
+ () => 'mirror: rows set aside not taken back — best placing'
+ ' ${found.agree}/${found.share} of ${probe.length} rows,'
+ ' next best ${found.runnerUp} · ${aside.length} set aside',
+ );
+ }
+ return;
+ }
+ var taken = 0;
+ for (final entry in aside.entries) {
+ final row = entry.key - found.d;
+ // What the document has is newer.
+ if (_document.containsKey(row)) continue;
+ // Not content seen moving, as far as [_store] is concerned: away from
+ // the rows that matched, the program may have changed since — a result
+ // unfolded, a block folded — and a row it shows differently there is
+ // written over, never kept out.
+ _document[row] = entry.value..confirmed = false;
+ taken++;
}
+ _aside = null;
+ if (taken == 0) return;
+ _documentMin = math.min(_documentMin, _asideMin - found.d);
+ _documentMax = math.max(_documentMax, _asideMax - found.d);
+ _trim();
+ inputTrace(
+ () => 'mirror: $taken rows set aside taken back'
+ ' (${found.agree}/${found.share} rows agreed)',
+ );
+ }
+
+ /// Trace only: why the frame on [screen] was not placed, and what it and the
+ /// document show at its top and bottom rows — where a program's own rows (a
+ /// pinned prompt, a "jump to bottom" line) would be.
+ void _traceMiss(
+ IndexAwareCircularBuffer<BufferLine> screen,
+ int rowCount,
+ int changed,
+ ) {
+ inputTrace(() {
+ final miss = _miss;
+ final expected = _requested - _remote;
+ final why = miss == null
+ ? 'nothing to compare with'
+ : miss.rival != null
+ ? 'k=${miss.rows} and k=${miss.rival} agree alike'
+ ' (${miss.agree}/${miss.share})'
+ : 'closest k=${miss.rows} agreed ${miss.agree}/${miss.share}';
+ String text(BufferLine? line) =>
+ line == null ? '–' : traceText(line.getText().trimRight(), max: 36);
+ final sample = [
+ for (final i in [0, 1, 2, rowCount - 3, rowCount - 2, rowCount - 1])
+ if (i >= 0 && i < rowCount)
+ '$i "${text(screen[i])}" doc "${text(_document[_remote + expected + i]?.line)}"',
+ ];
+ return 'mirror: miss · $changed rows changed · expected k=$expected · $why'
+ ' · scrolling rows ${_top ?? '?'}..${_bottom ?? '?'}'
+ ' · document ${_documentMin - _remote}..${_documentMax - _remote}'
+ ' · ${sample.join(' | ')}';
+ });
}
- /// The frame could not be placed: the program drew something else. What is
- /// known is no longer worth anything; start again from this screen.
+ /// The frame could not be placed: the program drew something else. Where
+ /// what is known stands against the screen is lost; start again from this
+ /// screen — what is known set aside, to be taken back once a later frame
+ /// shows where it stands ([_reattach]).
void _lost() {
inputTrace(() => 'mirror: frame not placed — starting again from it');
+ // The rows still waiting were counted in books that are gone.
+ cancelRequests();
+ _pageInFlight = false;
+ _stopPrefetch();
+ _setAside();
_document.clear();
+ _topRow = null;
_documentMin = 0;
_documentMax = -1;
final wasActive = _active;
_active = false;
_chasing = false;
+ _streaming = false;
_velocity = 0;
_remote = 0;
_requested = 0;
@@ -530,11 +1472,17 @@ class RemoteScrollMirror {
void _activateIfReady() {
if (_active || !_scrolling) return;
if (_top == null || _bottom == null || _lastFrame == null) return;
+ // ⚠️ Never from nothing: a scroll that began just after the document
+ // started again, before any screen was written into it, drew its rows as
+ // nothing — a blank screen for three frames (measured on a phone,
+ // 2026-10-06). The program's next frame writes one in.
+ if (_document.isEmpty || _documentMax < _documentMin) return;
// From the live screen: what is drawn does not move on the switch.
_active = true;
_display = _remote.toDouble();
_velocity = 0;
_chasing = true;
+ _streaming = false;
_scheduleTick();
inputTrace(
() => 'mirror: drawing from the document · rows $_top..$_bottom'
@@ -558,8 +1506,15 @@ class RemoteScrollMirror {
/// The screen to where the finger is — exactly, unless it is catching up.
void _follow() {
if (!_active) return;
+ _dropLag();
final goal = _clamp(_target);
- if (goal != _target) _clampedUpdates++;
+ if (goal != _target) {
+ _clampedUpdates++;
+ if (_scrolling) {
+ _capLag(goal);
+ _streaming = true;
+ }
+ }
if (!_chasing) {
final stride = (_target - _lastTarget).abs() + 1e-6;
if ((goal - _display).abs() <= stride) {
@@ -572,6 +1527,27 @@ class RemoteScrollMirror {
_scheduleTick();
}
+ /// The finger is let run at most [_maxLag] rows past the edge of what is
+ /// known, [goal]; the rest of its way is let go, and it carries on from
+ /// there.
+ ///
+ /// ⚠️ **What the screen is behind the finger, it scrolls on by itself.** A
+ /// finger faster than the program (~80 rows a second) ran hundreds of rows
+ /// ahead of the screen, held at the edge 200–264 times a scroll — which went
+ /// on at the program's pace once the finger had stopped, and on after it let
+ /// go, as if flung (reported on a phone, 2026-10-06; [_dropLag] never let it
+ /// go: a finger at rest still moved a pixel or two). Let go as it goes, the
+ /// screen stops with the finger, and turns with it at once.
+ void _capLag(double goal) {
+ final ahead = _target - goal;
+ if (ahead.abs() <= _maxLag) return;
+ final by = goal + _maxLag * ahead.sign - _target;
+ _anchorRow += by;
+ _target += by;
+ _lastTarget += by;
+ _lagDropped += by.abs();
+ }
+
void _scheduleTick() {
if (_tick != null) return;
_tick = SchedulerBinding.instance.scheduleFrameCallback(_onTick);
@@ -595,14 +1571,16 @@ class RemoteScrollMirror {
final seconds = last == null
? 1 / 60
: math.max(0, (timeStamp - last).inMicroseconds) / 1e6;
+ _dropLag();
if (_chasing) {
// A critically damped spring towards the goal, solved exactly.
final goal = _clamp(_target);
+ final omega = _omegaNow;
final x = _display - goal;
- final decay = math.exp(-_omega * seconds);
- final u = _velocity + _omega * x;
+ final decay = math.exp(-omega * seconds);
+ final u = _velocity + omega * x;
final next = (x + u * seconds) * decay;
- _velocity = (_velocity - _omega * u * seconds) * decay;
+ _velocity = (_velocity - omega * u * seconds) * decay;
// Never beyond what is known, however the speed it started with carries
// it: a row past the document would be drawn as nothing.
final at = _clamp(goal + next);
@@ -612,61 +1590,468 @@ class RemoteScrollMirror {
_display = goal;
_velocity = 0;
_chasing = false;
+ _streaming = false;
}
onFrame();
}
- _resyncIfStalled();
- _checkSettled();
- if (_active && (_chasing || _settling)) _scheduleTick();
+ if (_prefetching) {
+ _prefetchStep();
+ } else if (_settling) {
+ _settleStep();
+ } else {
+ _resyncIfStalled();
+ }
+ if (_active && (_chasing || _settling || _prefetching)) _scheduleTick();
}
/* The program */
- /// The program asked to scroll to where the finger is, and a little ahead.
+ /// Whether [screen] shows the program's prompt, for [_pageKeysSafe] — read
+ /// only for a program whose page keys are let scroll it.
+ void _readPrompt(
+ IndexAwareCircularBuffer<BufferLine> screen,
+ int rowCount,
+ ) {
+ _pageKeysSafe =
+ (pageKeysEnabled?.call() ?? false) && _promptShown(screen, rowCount);
+ }
+
+ /// Whether [screen] shows Claude Code's prompt: a row starting `❯` with a
+ /// rule (`────`) right above it, and another a few rows below — its input
+ /// box.
+ ///
+ /// ⚠️ **Not a list to choose from.** A question it asks — "Do you want to
+ /// proceed?" over "❯ 1. Yes" — has its own words above the `❯`, not a rule,
+ /// and Page Up or Down there would move the choice instead of scrolling. In
+ /// any doubt, no page keys: wheel events only ever scroll.
+ static bool _promptShown(
+ IndexAwareCircularBuffer<BufferLine> screen,
+ int rowCount,
+ ) =>
+ _promptRow(screen, rowCount) >= 0;
+
+ /// The text of the prompt's row ([_promptRow]), or null when none shows.
+ static String? _promptText(
+ IndexAwareCircularBuffer<BufferLine> screen,
+ int rowCount,
+ ) {
+ final row = _promptRow(screen, rowCount);
+ return row < 0 ? null : screen[row].getText();
+ }
+
+ /// The screen row of Claude Code's prompt — see [_promptShown] — or -1.
+ static int _promptRow(
+ IndexAwareCircularBuffer<BufferLine> screen,
+ int rowCount,
+ ) {
+ if (screen.length < rowCount) return -1;
+ bool isRule(int i) {
+ final text = screen[i].getText().trim();
+ if (text.length < 8) return false;
+ var rule = 0;
+ for (final unit in text.codeUnits) {
+ if (unit == 0x2500) rule++;
+ }
+ return rule * 10 >= text.length * 9;
+ }
+
+ final from = math.max(1, rowCount - 12);
+ for (var i = rowCount - 1; i >= from; i--) {
+ if (!screen[i].getText().trimLeft().startsWith('❯')) continue;
+ if (!isRule(i - 1)) continue;
+ for (var j = i + 1; j < rowCount && j <= i + 8; j++) {
+ if (isRule(j)) return i;
+ }
+ }
+ return -1;
+ }
+
+ /// About how many rows a page key scrolls the program: half the rows that
+ /// scroll — Claude Code's page is half its transcript's height. Only an
+ /// estimate: where a page lands, the frame says ([_pageLanded]).
+ int get _pageRowsNow {
+ final top = _top;
+ final bottom = _bottom;
+ if (top == null || bottom == null) return 0;
+ return (bottom - top + 1) ~/ 2;
+ }
+
+ /// Whether [lines] the program is to be asked go as a page key: true when
+ /// one went — or is to go, once what is on its way has landed: no wheel
+ /// events meanwhile. False leaves them to wheel events.
+ ///
+ /// ⚠️ **Wheel events top out at ~150 rows a second; a fling runs 200–400.**
+ /// Four at a time, so that each scrolls one row, the program moved 156 rows
+ /// a second (p50), and the screen waited at the edge of what is known 76
+ /// times a scroll, the finger let go 108 rows ahead (measured on a phone,
+ /// 2026-10-06, 85 of 106 scrolls at 200 rows a second or more). Claude
+ /// Code's Page Up and Down scroll half its transcript's height at once — a
+ /// jump (`scrollTo`), not a glide, and never sped up — so one key moves it
+ /// ~17 rows a round trip, and its frame still shares half a screen with the
+ /// last, to be placed by. One at a time, and alone: two drawn as one frame
+ /// would move it further than a frame can be placed.
+ ///
+ /// [fast] — the finger past the edge of what is known, or faster than
+ /// [_pageSpeed] — and rows short of a page wait for a page's worth rather
+ /// than going as wheel events.
+ ///
+ /// ⚠️ **Wheel rows trickled in kept the pages out.** Flicked again and again,
+ /// the finger was rarely a page ahead of what was asked: four wheel events
+ /// went every 50ms instead, the program glided through each over a few
+ /// frames ([_wheelsGliding]), and no page could go — 137 rows a second (p50)
+ /// against a finger at 296, the screen held at the edge most of each flick
+ /// (measured on a phone, 2026-10-06, 56 pages in 102 flicks).
+ bool _pageOrWait(int lines, {bool fast = false}) {
+ final send = requestPage;
+ if (send == null || !_pageKeysSafe || _pageKeysRefused) return false;
+ // The page on its way lands first: nothing goes with it.
+ if (_pageInFlight) return true;
+ final page = _pageRowsNow;
+ if (page < _minPage) return false;
+ if (lines.abs() < page) return fast;
+ if (!requestsIdle() || _wheelsGliding) return true;
+ final direction = lines.sign;
+ if (!send(direction)) {
+ _pageKeysRefused = true;
+ inputTrace(() => 'mirror: page key refused — wheel events from here');
+ return false;
+ }
+ _pageInFlight = true;
+ _pageNowhere = false;
+ _pageDirection = direction;
+ _pageSentAtMs = _nowMs;
+ _pageFromRemote = _remote;
+ _requested += direction * page;
+ _requestedAtMs = _nowMs;
+ _askedDirection = direction;
+ _rowsAsked += page;
+ _pagesSent++;
+ return true;
+ }
+
+ /// A frame placed while a page key was on its way: once the program has
+ /// moved its way, the page has landed — and where the frame shows it is
+ /// where it stands. A page jumps (`scrollTo`), with nothing gliding behind
+ /// it ([_wheelsGliding]) and nothing sent while it was on its way: the books
+ /// counted only an estimate of it.
+ void _pageLanded() {
+ final moved = (_remote - _pageFromRemote) * _pageDirection;
+ if (moved <= 0) return;
+ _pageInFlight = false;
+ _pageLandedAtMs = _nowMs;
+ _requested = _remote;
+ }
+
+ /// Whether the program may still be gliding through wheel rows: asked since
+ /// the last page landed, and it has moved, or they were asked, within
+ /// [_wheelsSettle].
+ ///
+ /// ⚠️ **A page lands on top of what is still to glide.** Claude Code's page
+ /// key scrolls from where its wheel rows will end up (`scrollTo` past the
+ /// pending delta), and wheel rows sped up glide on for a few frames after
+ /// they are answered: a page sent then moved it the page and the rest at
+ /// once — further than a screen, with no row in common to place by (6 of
+ /// 10 frames lost in a long session, measured on a phone, 2026-10-06).
+ bool get _wheelsGliding {
+ if (_wheelsAtMs <= _pageLandedAtMs) return false;
+ final now = _nowMs;
+ final settle = _wheelsSettle.inMilliseconds;
+ return now - _movedAtMs < settle || now - _wheelsAtMs < settle;
+ }
+
+ /// A page key unanswered for [_pageWait] went nowhere: the next may go —
+ /// and, the program not having moved, the books are put back to where it is.
+ void _expirePage() {
+ if (!_pageInFlight || _nowMs - _pageSentAtMs < _pageWait.inMilliseconds) {
+ return;
+ }
+ _pageInFlight = false;
+ _pageNowhere = _remote == _pageFromRemote;
+ if (_pageNowhere && requestsIdle()) _requested = _remote;
+ }
+
+ /* Fetching ahead */
+
+ /// [_prefetch] in [_prefetchAfter] — again from now: the program drew, the
+ /// finger was on the glass, or a scroll just ended.
+ void _armPrefetch() {
+ if (readScreen == null || !(pageKeysEnabled?.call() ?? false)) return;
+ _prefetchTimer?.cancel();
+ _prefetchTimer = Timer(_prefetchAfter, _prefetch);
+ }
+
+ /// While nobody scrolls and the program is quiet, the rows above the screen
+ /// fetched into the document — [_prefetchRows] of them — a page key at a
+ /// time, the program then brought back to the row on screen.
+ ///
+ /// ⚠️ **What has not been seen comes at the program's pace.** In a long
+ /// session Claude Code draws a page in 50–150ms: ~200 rows a second, against
+ /// a flick of 300–400 — so every scroll into rows not yet seen caught up
+ /// with their edge and waited there (measured on a phone, 2026-10-06).
+ /// Fetched while the reader reads, the rows are there when the finger goes
+ /// for them. Nothing on the screen moves meanwhile: the rows that scroll
+ /// are drawn from the document where they are, and the program's own rows
+ /// — its pinned prompt, its "jump to bottom" line, which come up as it
+ /// scrolls — held as they were ([heldRow]). Only for a program whose page
+ /// keys are let scroll it, while it shows its prompt; given way to the
+ /// finger at once ([begin]) and to a key typed ([frame]); and only once
+ /// which rows scroll is known — learned in a scroll, or remembered.
+ void _prefetch() {
+ _prefetchTimer = null;
+ if (_scrolling || _active || _prefetching) {
+ return _skipPrefetch('a scroll is on');
+ }
+ if (!(pageKeysEnabled?.call() ?? false)) {
+ return _skipPrefetch('no page keys for this program');
+ }
+ // Not from the background: the link may be parked, a page key would go
+ // nowhere, and be taken for the top of the transcript.
+ final lifecycle = SchedulerBinding.instance.lifecycleState;
+ if (lifecycle != null && lifecycle != AppLifecycleState.resumed) {
+ return _skipPrefetch('the app is not in front');
+ }
+ final now = readScreen?.call();
+ if (now == null) return _skipPrefetch('the screen cannot be read whole');
+ final screen = now.lines;
+ final rowCount = now.rowCount;
+ if (!_sameGrid(screen, rowCount, now.lineHeight)) {
+ _forget();
+ _takeGrid(screen, rowCount, now.lineHeight);
+ _load();
+ }
+ final top = _top;
+ final bottom = _bottom;
+ if (top == null || bottom == null) {
+ return _skipPrefetch('which rows scroll is not known yet');
+ }
+ _readPrompt(screen, rowCount);
+ if (!_pageKeysSafe) return _skipPrefetch('no prompt on the screen');
+ // Where the program stands now — nothing is on its way, before the frame
+ // and after it: what moved it since was output, not anything asked.
+ _requested = _remote;
+ _frame(screen, rowCount);
+ _requested = _remote;
+ if (_document.isEmpty || _documentMax < _documentMin) {
+ return _skipPrefetch('nothing written from the screen');
+ }
+ final want = _remote + top - _prefetchRows;
+ final topRow = _topRow;
+ final above = _remote + top - _documentMin;
+ if (_documentMin <= want) {
+ return _skipPrefetch('$above rows above the screen known already');
+ }
+ if (topRow != null && _documentMin <= topRow) {
+ return _skipPrefetch('the top of the transcript is known, $above above');
+ }
+ _prefetchGoal = want - top;
+ _prefetching = true;
+ _prefetchStartedAtMs = _nowMs;
+ _heldPrompt = _promptText(screen, rowCount);
+ _held.clear();
+ final promptRow = _promptRow(screen, rowCount);
+ for (var i = 0; i < rowCount; i++) {
+ if (i >= top && i <= bottom) continue;
+ // From the prompt's rule down, live: what is typed shows.
+ if (promptRow >= 0 && i >= promptRow - 1) break;
+ final line = screen[i];
+ _held[i] = BufferLine(line.length)..copyFrom(line, 0, 0, line.length);
+ }
+ _active = true;
+ _display = _remote.toDouble();
+ _target = _display;
+ _lastTarget = _target;
+ _velocity = 0;
+ _chasing = false;
+ _streaming = false;
+ _settling = false;
+ _direction = 0;
+ _fingerVelocity = 0;
+ _startedAtMs = _nowMs;
+ _framesAligned = 0;
+ _framesLost = 0;
+ _clampedUpdates = 0;
+ _lagDropped = 0;
+ _settleAsks = 0;
+ _rowsGuarded = 0;
+ _rowsMended = 0;
+ _asksSpared = 0;
+ _rowsAsked = 0;
+ _pagesSent = 0;
+ _pageKeysRefused = false;
+ _resyncs = 0;
+ _missesInARow = 0;
+ inputTrace(
+ () => 'mirror: fetching ahead · ${_remote - _prefetchGoal} rows up'
+ ' · ${_remote + top - _documentMin} known above the screen',
+ );
+ _prefetchStep();
+ _scheduleTick();
+ }
+
+ /// Trace only: why [_prefetch] fetched nothing this time.
+ void _skipPrefetch(String why) {
+ inputTrace(() => 'mirror: not fetching ahead — $why');
+ }
+
+ /// The program asked on up, a page at a time, until its screen reaches the
+ /// rows wanted — or a page goes nowhere: the top of its transcript.
+ void _prefetchStep() {
+ if (!_prefetching) return;
+ _expirePage();
+ if (!_pageInFlight && _pageNowhere) {
+ _topRow = _documentMin;
+ _endPrefetch();
+ return;
+ }
+ final remaining = _remote - _prefetchGoal;
+ if (remaining <= 0) {
+ _endPrefetch();
+ return;
+ }
+ final page = _pageRowsNow;
+ if (!_pageKeysSafe || _pageKeysRefused || page < _minPage) {
+ _endPrefetch();
+ return;
+ }
+ _pageOrWait(-math.max(page, remaining), fast: true);
+ }
+
+ /// Fetched: the program brought back to the row on screen, as a scroll that
+ /// has ended is ([_settleStep]); the held rows go once it stands there.
+ void _endPrefetch() {
+ if (!_prefetching) return;
+ _prefetching = false;
+ _pageNowhere = false;
+ final top = _top ?? 0;
+ inputTrace(
+ () => 'mirror: fetched ahead in ${_nowMs - _prefetchStartedAtMs}ms'
+ ' · ${_remote + top - _documentMin} rows above the screen known'
+ ' · $_pagesSent pages',
+ );
+ _settling = true;
+ _target = _display;
+ _lastTarget = _target;
+ _endedAtMs = _nowMs;
+ _armSettleTimer();
+ _settleStep();
+ _scheduleTick();
+ }
+
+ /// Fetching ahead given up — the finger came, or what is known went: the
+ /// held rows go, and what was asked stays on the books.
+ void _stopPrefetch() {
+ _prefetchTimer?.cancel();
+ _prefetchTimer = null;
+ _prefetching = false;
+ _pageNowhere = false;
+ if (_held.isNotEmpty) {
+ _held.clear();
+ onFrame();
+ }
+ }
+
+ /// How many rows ahead of the finger the program is asked to be — see
+ /// [_leadMin].
+ int _leadRows() {
+ final scrolling = (_bottom ?? 0) - (_top ?? 0) + 1;
+ final most = math.min(_leadMax, scrolling ~/ 2);
+ final wanted = (_leadMin + _fingerVelocity.abs() * _leadLatency).round();
+ return math.max(0, math.min(most, wanted));
+ }
+
+ /// The program asked to scroll to where the finger is, and a little ahead —
+ /// while it scrolls; once it has ended, [_settleStep].
void _requestRemote() {
- final lead = _scrolling && _active
- ? math.min(_lead, ((_bottom ?? 0) - (_top ?? 0)) ~/ 3) * _direction
- : 0;
- // Settling, the row the screen is coming to rest on — not where it is
- // on the way there.
- final goal = (_settling ? _clamp(_target).round() : _target.round()) + lead;
+ _expirePage();
+ final moving = _scrolling && _active;
+ // Held at the edge of what is known ([_capLag]), the finger is never far
+ // ahead to read ahead of: the program is asked as far as it may be.
+ final held = moving && _clamp(_target) != _target;
+ if (moving && !held && _direction != 0 && _knownFarEnough()) {
+ _asksSpared++;
+ return;
+ }
+ final lead = moving ? (held ? _maxAhead : _leadRows()) * _direction : 0;
+ final wanted = _target.round() + lead;
+ // ⚠️ **Never far past where the program was last seen.** A fling runs
+ // hundreds of rows ahead of a program that scrolls ~80 a second, and all of
+ // them were asked for at once: they went on going out for seconds after
+ // the finger let go — the screen scrolling by itself — and at the top of
+ // its history the program took none of them, so the books ran hundreds of
+ // rows wrong (measured on a phone, 2026-10-06). Asked [_maxAhead] at most
+ // past the last row seen, the rest is asked for as the program gets there:
+ // each frame asks again.
+ final goal = wanted.clamp(_remote - _maxAhead, _remote + _maxAhead);
final lines = goal - _requested;
if (lines == 0) return;
+ // While the finger moves the program is only asked onwards. Ahead of the
+ // finger it is reading ahead, and pulled back each time the finger slowed
+ // it turned round and round — Claude Code drops the first wheel of every
+ // turn, and glides on the old way a few frames first. Coming back to the
+ // row on screen is for when the scroll comes to rest.
+ if (_scrolling && _direction != 0 && lines.sign != _direction) return;
+ final fast = moving && (held || _fingerVelocity.abs() >= _pageSpeed);
+ if (_pageOrWait(lines, fast: fast)) return;
_requested = goal;
_requestedAtMs = _nowMs;
+ _askedDirection = lines.sign;
+ _rowsAsked += lines.abs();
+ _wheelsAtMs = _nowMs;
requestLines(lines);
}
- /// Rows asked for and never answered — the program was at an end, or the
- /// pacing let them go — leave the books wrong: start them again from where
- /// the program is.
+ /// Whether the finger, moving over rows already known, is far enough from
+ /// the edge of them that the program need not follow it yet.
+ ///
+ /// Every row the program is asked comes back as a whole redraw, read and
+ /// matched on this thread while the finger moves, and over known rows it
+ /// brings nothing the screen needs: they are drawn from the document. So
+ /// the program is asked only once the finger nears the edge of what is
+ /// known — soon enough for it to get there first: the lead, and what the
+ /// finger covers while the program comes to the edge at
+ /// [_programRowsPerSecond]. Never more than [_lazyReach] rows behind the
+ /// finger, either: what it is not asked now it is asked when the scroll
+ /// ends, and the live screen waits for it then.
+ bool _knownFarEnough() {
+ final top = _top;
+ final bottom = _bottom;
+ if (top == null || bottom == null || _documentMax < _documentMin) {
+ return false;
+ }
+ if ((_requested - _target).abs() > _lazyReach) return false;
+ final ahead = _direction > 0
+ ? _documentMax - (_target + bottom)
+ : (_target + top) - _documentMin;
+ // The program's row 0 at which its screen reaches the edge, and how far
+ // it has to come, onwards, to stand there.
+ final edge = _direction > 0 ? _documentMax - bottom : _documentMin - top;
+ final travel = math.max(0, (edge - _requested) * _direction);
+ final seconds = travel / _programRowsPerSecond + _leadLatency;
+ return ahead > _leadRows() + _fingerVelocity.abs() * seconds;
+ }
+
+ /// While the finger scrolls: rows asked for and never answered — the program
+ /// was at an end, or the pacing let them go — leave the books wrong: start
+ /// them again from where the program is.
void _resyncIfStalled() {
- if (_requested == _remote) return;
+ if (_settling || _requested == _remote) return;
+ // ⚠️ A page still on its way is not a program that stopped: its answer
+ // can take 150ms and more, and the scroll handler counts any batch it has
+ // waited 120ms for as answered. Put back to where the program was, the
+ // books read the page's frame, when it came, as the screen changing where
+ // it stands — and the document started again (measured on a phone,
+ // 2026-10-06). [_expirePage] says when a page went nowhere.
+ if (_pageInFlight) return;
final now = _nowMs;
- if (now - _frameAtMs < _resyncAfter.inMilliseconds) return;
+ // Not moved, rather than not drawn: an agent at work redraws its spinner
+ // every few frames, and a program at an end never moves however it draws.
+ if (now - _movedAtMs < _resyncAfter.inMilliseconds) return;
if (now - _requestedAtMs < _resyncAfter.inMilliseconds) return;
if (!requestsIdle()) return;
- if (_resyncs < _maxResyncs) {
- _resyncs++;
- _requested = _remote;
- _requestRemote();
- return;
- }
- if (!_settling) return;
- // The program will not come to the row on screen — it scrolls in steps of
- // its own, or it is at an end — so the screen goes to the program's row: a
- // glide of a row or two, rather than a jump when the settle runs out.
- inputTrace(
- () => 'mirror: settling on the program\'s row $_remote'
- ' (asked for ${_clamp(_target).round()})',
- );
+ if (_resyncs >= _maxResyncs) return;
+ _resyncs++;
_requested = _remote;
- _target = _remote.toDouble();
- if (!_chasing) {
- _chasing = true;
- _velocity = 0;
- }
- _scheduleTick();
+ _requestRemote();
}
/// Asked again this many times at most in one scroll: a program at the top
@@ -674,20 +2059,81 @@ class RemoteScrollMirror {
static const _maxResyncs = 3;
int _resyncs = 0;
- void _checkSettled() {
- if (!_active || !_settling || _chasing) return;
- if (_display != _remote.toDouble()) return;
- final took = _nowMs - _startedAtMs;
+ /// The scroll has ended: the program is brought to the row the screen rests
+ /// on — the screen never goes to the program, it waits for it — and the
+ /// screen goes back to it once it stands there.
+ ///
+ /// ⚠️ **Counted from where the program stopped, not from the books.** Rows
+ /// still on their way, and Claude Code's own glide through them, carried it
+ /// on after the finger let go — and faster than asked: it speeds up wheel
+ /// events it reads together. Asked back at once from what the books said, it
+ /// went past the row, was asked back again, and swung about it for over a
+ /// second, the screen gliding after it (measured on a phone, 2026-10-06: rows
+ /// -909, -928, -945, -926, -896, -909). Now, far off, it is kept coming as it
+ /// answers, a few rows short; a turn, and the last rows, wait until it has
+ /// stood still for [_settleQuiet], and go out a burst at a time — each wheel
+ /// one row.
+ void _settleStep() {
+ if (!_active || !_settling) return;
+ _expirePage();
+ final now = _nowMs;
+ final row = _clamp(_target).round();
+ // A page still on its way is not quiet, however long it has been out —
+ // see [_resyncIfStalled].
+ final quiet = !_pageInFlight &&
+ requestsIdle() &&
+ now - _movedAtMs >= _settleQuiet.inMilliseconds &&
+ now - _requestedAtMs >= _settleQuiet.inMilliseconds;
+ // Nothing on its way and standing still: the program is where it is,
+ // whatever was asked of it.
+ if (quiet) _requested = _remote;
+ final diff = row - _remote;
+ if (diff == 0) {
+ if (quiet && !_chasing && _display == row) _finishSettle();
+ return;
+ }
+ final sign = diff.sign;
+ final far = diff.abs() > _landingRows;
+ if (!quiet && (!far || sign != _askedDirection)) return;
+ final want = far ? row - sign * _landingBurst : row;
+ final goal = want.clamp(_remote - _maxAhead, _remote + _maxAhead);
+ var lines = goal - _requested;
+ // Asked that far already, and on its way.
+ if (lines == 0 || lines.sign != sign) return;
+ // Far off, a page at a time; the last rows, wheel events: each one row.
+ if (far && _pageOrWait(lines)) return;
+ if (!far) lines = lines.clamp(-_landingBurst, _landingBurst);
+ _requested += lines;
+ _requestedAtMs = now;
+ _askedDirection = sign;
+ _settleAsks++;
+ _rowsAsked += lines.abs();
+ _wheelsAtMs = _nowMs;
+ requestLines(lines);
+ }
+
+ /// The program stands at the row on screen: drawn from it again.
+ void _finishSettle() {
+ final now = _nowMs;
+ final took = now - _startedAtMs;
inputTrace(
- () => 'mirror: done in ${took}ms · frames placed $_framesAligned,'
- ' lost $_framesLost · held at the edge $_clampedUpdates times',
+ () => 'mirror: done in ${took}ms, settled ${now - _endedAtMs}ms after the'
+ ' finger let go · frames placed $_framesAligned,'
+ ' lost $_framesLost · held at the edge $_clampedUpdates times'
+ ' · ${_lagDropped.round()} rows the finger ran ahead let go'
+ ' · $_settleAsks asks to come back · rows kept from the program\'s'
+ ' own $_rowsGuarded, put right $_rowsMended'
+ ' · $_rowsAsked rows asked ($_pagesSent pages),'
+ ' $_asksSpared asks spared over known rows',
);
_settling = false;
_settleTimer?.cancel();
_settleTimer = null;
_active = false;
+ _held.clear();
_cancelTick();
onFrame();
+ _armPrefetch();
}
void _settleTimedOut() {
@@ -697,13 +2143,16 @@ class RemoteScrollMirror {
() => 'mirror: the program did not come back to row'
' ${_display.round()} (it is at $_remote) — showing where it is',
);
+ cancelRequests();
_settling = false;
_active = false;
_chasing = false;
_velocity = 0;
_display = _remote.toDouble();
+ _held.clear();
_cancelTick();
onFrame();
+ _armPrefetch();
}
}
@@ -735,17 +2184,28 @@ class _Row {
/// One row of the document: a copy of the line as it was drawn, kept while the
/// program's screen moves on and writes over the original.
class _DocRow {
- _DocRow(this.line, this.signature);
+ _DocRow(this.line, this.signature, this.fromRow);
- factory _DocRow.copyOf(BufferLine source) {
+ /// [source], whose [signature] is known, written from the program's screen
+ /// row [fromRow].
+ factory _DocRow.copyOf(BufferLine source, int signature, int? fromRow) {
final line = BufferLine(source.length)
..copyFrom(source, 0, 0, source.length);
- return _DocRow(line, _Row.of(line).signature);
+ return _DocRow(line, signature, fromRow);
}
final BufferLine line;
final int signature;
+ /// The program's screen row it came in at with a scroll; null when written
+ /// where it stood.
+ final int? fromRow;
+
+ /// Whether it has been seen moving with the content — found where a scroll
+ /// took it — and so is content, not a row of the program's own written in
+ /// by mistake. See [RemoteScrollMirror._learnFixedRows].
+ bool confirmed = false;
+
/// Whether [other] draws exactly this — every cell, colours included — so the
/// copy, and its recorded drawing, can stay.
bool sameCells(BufferLine other) {
@@ -762,11 +2222,86 @@ class _DocRow {
}
/// [rows]: the program's screen row `i` now shows what document row
-/// `_remote + rows + i` held; [first]..[last]: the rows that agreed.
+/// `_remote + rows + i` held; [agreeing]: the screen rows that showed it, top
+/// to bottom, of [share] that could.
class _Shift {
- const _Shift(this.rows, this.first, this.last);
+ const _Shift(this.rows, this.agreeing, this.share);
final int rows;
- final int first;
- final int last;
+ final List<int> agreeing;
+ final int share;
+
+ /// The first and last rows that agreed: what bounds the scrolling rows.
+ int get first => agreeing.isEmpty ? -1 : agreeing.first;
+ int get last => agreeing.isEmpty ? -1 : agreeing.last;
+}
+
+/// AUTONOMOUS PATCH: the program's whole screen, for [RemoteScrollMirror] to
+/// start fetching ahead from on its own — see [RemoteScrollMirror.readScreen].
+typedef RemoteScreen = ({
+ IndexAwareCircularBuffer<BufferLine> lines,
+ int rowCount,
+ double lineHeight,
+});
+
+/// AUTONOMOUS PATCH: what a [RemoteScrollMirror] knew of one program's rows —
+/// the rows seen, which rows scroll, which are the program's own — kept by the
+/// embedder for each program it shows (an agent), in memory only, and handed
+/// to every view of it (`TerminalView.altBufferScrollMemory`).
+///
+/// ⚠️ **Every new emulator threw what was known away.** A keyframe replaces
+/// the emulator — on every open, every keyboard raised or lowered, every take
+/// over — and the mirror was reset with it: the rows read were fetched again,
+/// and the first scroll after it waited 100–700ms to learn which rows scroll
+/// (measured on a phone, 2026-10-06). Kept here, a new emulator of the same
+/// grid starts knowing which rows scroll, and the rows seen are set aside, to
+/// be found again in what the program shows.
+///
+/// Kept for each grid apart, the last [gridsKept] of them: the same program
+/// is shown in a taller grid with the keyboard down and a shorter one with it
+/// up, and what is learned in one would otherwise overwrite the other.
+class RemoteScrollMemory {
+ /// How many grids are kept — the keyboard down and the keyboard up.
+ static const gridsKept = 2;
+
+ /// The most rows kept for a grid, around where the screen was: about a
+ /// kilobyte each.
+ static const rowsKept = 1500;
+
+ /// By grid ([RemoteScrollMirror._gridKey]), least recently kept first.
+ final _grids = <String, _Known>{};
+
+ /// Whether which rows scroll is known in any grid — what fetching ahead
+ /// before the first scroll needs.
+ bool get knowsScrollingRows => _grids.isNotEmpty;
+
+ void _keep(String grid, _Known known) {
+ _grids.remove(grid);
+ _grids[grid] = known;
+ while (_grids.length > gridsKept) {
+ _grids.remove(_grids.keys.first);
+ }
+ }
+
+ /// Everything known forgotten.
+ void clear() => _grids.clear();
+}
+
+/// What [RemoteScrollMemory] keeps of one grid.
+class _Known {
+ _Known({
+ required this.rows,
+ required this.rowsMin,
+ required this.rowsMax,
+ required this.top,
+ required this.bottom,
+ required this.fixedRows,
+ });
+
+ final Map<int, _DocRow>? rows;
+ final int rowsMin;
+ final int rowsMax;
+ final int top;
+ final int bottom;
+ final Set<int> fixedRows;
}
diff --git a/mobile/third_party/xterm/lib/src/ui/render.dart b/mobile/third_party/xterm/lib/src/ui/render.dart
index cab48de89..5ca060ab2 100644
--- a/mobile/third_party/xterm/lib/src/ui/render.dart
+++ b/mobile/third_party/xterm/lib/src/ui/render.dart
@@ -45,9 +45,13 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
bool animateRemoteScroll = false,
void Function(int rows)? onRemoteScrollShift,
bool mirrorRemoteScroll = false,
+ bool mirrorPageKeys = false,
RemoteScrollLink? remoteScrollLink,
+ RemoteScrollMemory? remoteScrollMemory,
}) : _terminal = terminal,
_mirrorRemoteScroll = mirrorRemoteScroll,
+ _mirrorPageKeys = mirrorPageKeys,
+ _remoteScrollMemory = remoteScrollMemory,
_remoteScrollLink = remoteScrollLink,
_devicePixelRatio = devicePixelRatio,
_animateRemoteScroll = animateRemoteScroll,
@@ -303,13 +307,45 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
RemoteScrollLink? _remoteScrollLink;
set remoteScrollLink(RemoteScrollLink? value) => _remoteScrollLink = value;
+ /// AUTONOMOUS PATCH: whether the mirror may scroll the program a page at a
+ /// time with its Page Up and Page Down keys — `TerminalView.altBufferScrollPageKeys`.
+ bool _mirrorPageKeys;
+ set mirrorPageKeys(bool value) => _mirrorPageKeys = value;
+
+ /// AUTONOMOUS PATCH: what the mirror knew of this program's rows, kept by the
+ /// embedder across emulators and views — `TerminalView.altBufferScrollMemory`.
+ RemoteScrollMemory? _remoteScrollMemory;
+ set remoteScrollMemory(RemoteScrollMemory? value) {
+ if (identical(value, _remoteScrollMemory)) return;
+ _remoteScrollMemory = value;
+ _mirror?.memory = value;
+ }
+
RemoteScrollMirror? _mirror;
- RemoteScrollMirror get _mirrorNow => _mirror ??= RemoteScrollMirror(
+ /// The screen for the mirror to fetch ahead from, when it can be read whole.
+ RemoteScreen? _mirrorScreen() {
+ if (!_canMirror || _terminal.synchronizedOutputHeld) return null;
+ return (
+ lines: _terminal.buffer.lines,
+ rowCount: _terminal.viewHeight,
+ lineHeight: _painter.cellSize.height,
+ );
+ }
+
+ RemoteScrollMirror get _mirrorNow => _mirror ??= _newMirror();
+
+ RemoteScrollMirror _newMirror() => RemoteScrollMirror(
onFrame: markNeedsPaint,
requestLines: (lines) => _remoteScrollLink?.send(lines),
requestsIdle: () => _remoteScrollLink?.idle ?? true,
- );
+ cancelRequests: () => _remoteScrollLink?.cancel() ?? 0,
+ pageKeysEnabled: () => _mirrorPageKeys,
+ requestPage: (direction) =>
+ _mirrorPageKeys &&
+ (_remoteScrollLink?.sendPage(direction) ?? false),
+ readScreen: _mirrorScreen,
+ )..memory = _remoteScrollMemory;
bool get _canMirror =>
_mirrorRemoteScroll &&
@@ -328,6 +364,7 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
_terminal.buffer.lines,
_terminal.viewHeight,
_painter.cellSize.height,
+ screenWhole: !_terminal.synchronizedOutputHeld,
);
}
@@ -343,6 +380,7 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
_terminal.buffer.lines,
_terminal.viewHeight,
_painter.cellSize.height,
+ screenWhole: !_terminal.synchronizedOutputHeld,
);
return true;
}
@@ -371,11 +409,24 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
/// The screen was laid out again: a slide starts, carries on or ends here.
void _updateRemoteScroll() {
+ // A program whose scrolling rows are remembered gets its mirror before the
+ // first scroll: it fetches ahead from the start.
+ if (_mirror == null &&
+ _mirrorRemoteScroll &&
+ _mirrorPageKeys &&
+ _remoteScrollMemory?.knowsScrollingRows == true &&
+ _canMirror) {
+ _mirrorNow;
+ }
final mirror = _mirror;
if (mirror != null) {
if (!_isWholeAltScreen) {
mirror.reset();
- } else {
+ } else if (!_terminal.synchronizedOutputHeld) {
+ // ⚠️ Never a frame still arriving: part old, part new, it was matched
+ // and written into the mirror's document as one, and rows came out of
+ // order (reported on a phone, 2026-10-06). Its end lays the screen out
+ // again, whole.
mirror.frame(
_terminal.buffer.lines,
_terminal.viewHeight,
@@ -793,7 +844,8 @@ class RenderTerminal extends RenderBox with RelayoutWhenSystemFontsChangeMixin {
_painter.paintLineCached(
canvas,
offset.translate(0, _snapLineTop(i * charHeight + _lineOffset)),
- lines[i],
+ // The program's own rows as they were, while the mirror fetches ahead.
+ mirror?.heldRow(i) ?? lines[i],
);
}
diff --git a/mobile/third_party/xterm/lib/src/ui/scroll_handler.dart b/mobile/third_party/xterm/lib/src/ui/scroll_handler.dart
index d876b3801..1018858b3 100644
--- a/mobile/third_party/xterm/lib/src/ui/scroll_handler.dart
+++ b/mobile/third_party/xterm/lib/src/ui/scroll_handler.dart
@@ -11,19 +11,39 @@ import 'package:xterm/src/ui/infinite_scroll_view.dart';
class RemoteScrollLink {
void Function(int lines)? _send;
bool Function()? _idle;
+ int Function()? _cancel;
+ bool Function(int direction)? _page;
Object? _owner;
/// Scroll the program [lines] rows, positive towards newer ones. Dropped when
/// no scroll handler is listening: the program is not on its alternate screen.
void send(int lines) => _send?.call(lines);
+ /// Press Page Down ([direction] positive) or Page Up once — only when nothing
+ /// else asked is still on its way. False when it was not sent: something is,
+ /// or nobody is listening, or the program is scrolled another way.
+ bool sendPage(int direction) => _page?.call(direction) ?? false;
+
/// Whether every row asked for has gone out and been answered.
bool get idle => _idle?.call() ?? true;
- void _attach(Object owner, void Function(int) send, bool Function() idle) {
+ /// Rows asked for and not yet sent are not sent — how many, negative for up,
+ /// so whoever asked can take them off its books. What is already on its way
+ /// still lands.
+ int cancel() => _cancel?.call() ?? 0;
+
+ void _attach(
+ Object owner,
+ void Function(int) send,
+ bool Function() idle,
+ int Function() cancel,
+ bool Function(int direction) page,
+ ) {
_owner = owner;
_send = send;
_idle = idle;
+ _cancel = cancel;
+ _page = page;
}
void _detach(Object owner) {
@@ -31,6 +51,8 @@ class RemoteScrollLink {
_owner = null;
_send = null;
_idle = null;
+ _cancel = null;
+ _page = null;
}
}
@@ -143,11 +165,60 @@ class _TerminalScrollGestureHandlerState
static const _answerWaitLimit = Duration(milliseconds: 120);
+ /// The most wheel events in one batch of the finger's own scroll; the rest go
+ /// in the next.
+ ///
+ /// ⚠️ **A batch arrives all at once, and Claude Code speeds up wheel events
+ /// that come close together** — see [_exactBurst]. 41 wheels sent as one
+ /// batch scrolled it ~200 rows instead of 41, past anything the screen could
+ /// be matched with (measured on a phone, 2026-10-06).
+ static const _maxBatchLines = 12;
+
+ /// The most wheel events in one batch from the mirror: as many as are sure to
+ /// scroll Claude Code one row each.
+ ///
+ /// Its fullscreen renderer (2.1.290, `wheelScrollAccelerationEnabled` on by
+ /// default) scrolls the first wheel event after a pause of over 40ms one row,
+ /// and each one closer than 40ms to the last 0.3 of a row more, up to 6 —
+ /// floored, so the first four are one row each (read from its code; changing
+ /// its settings is not an option, as they reach every app showing the agent).
+ ///
+ /// ⚠️ **Not more, even to catch up with a fling.** Bigger batches, counted by
+ /// that ramp (12 wheels for 26 rows), moved the program 15–30 rows between two
+ /// frames and often more than a screen — and a frame with no row in common
+ /// with the last cannot be placed: 39 of 59 frames lost (measured on a phone,
+ /// 2026-10-06). At four a batch the program moves ~80 rows a second at most,
+ /// and a fling faster than that waits at the edge of what is known.
+ static const _exactBurst = 4;
+
+ /// The least time between two batches from the mirror, so the first wheel of
+ /// each comes after a pause and scrolls one row — see [_exactBurst].
+ static const _burstGap = Duration(milliseconds: 50);
+
+ /// Since the last batch of wheel events went out.
+ final _sinceBatch = Stopwatch();
+
+ /// Sends a batch from the mirror once [_burstGap] has passed.
+ Timer? _gapWait;
+
+ /// Whether [_unsentLines] were asked for through [RemoteScrollLink] — by the
+ /// mirror, which keeps its own books of every row it asked for.
+ var _unsentFromLink = false;
+
+ /// The direction of the last wheel events sent: -1 up, 1 down, 0 none yet.
+ var _lastSentSign = 0;
+
@override
void initState() {
widget.terminal.addListener(_onTerminalUpdated);
isAltBuffer = widget.terminal.isUsingAltBuffer;
- widget.link?._attach(this, _queueLines, _pacingIdle);
+ widget.link?._attach(
+ this,
+ _queueLinkLines,
+ _pacingIdle,
+ _cancelLinkLines,
+ _sendLinkPage,
+ );
super.initState();
}
@@ -173,7 +244,13 @@ class _TerminalScrollGestureHandlerState
}
if (!identical(oldWidget.link, widget.link)) {
oldWidget.link?._detach(this);
- widget.link?._attach(this, _queueLines, _pacingIdle);
+ widget.link?._attach(
+ this,
+ _queueLinkLines,
+ _pacingIdle,
+ _cancelLinkLines,
+ _sendLinkPage,
+ );
}
super.didUpdateWidget(oldWidget);
}
@@ -239,7 +316,13 @@ class _TerminalScrollGestureHandlerState
if (widget.paced) {
_queueLines(delta);
} else {
- if (delta != 0) widget.onWheelsSent?.call(delta);
+ if (delta != 0) {
+ widget.onWheelsSent?.call(delta);
+ _lastSentSign = delta.sign;
+ _sinceBatch
+ ..reset()
+ ..start();
+ }
for (var i = 0; i < delta.abs(); i++) {
_sendScrollEvent(delta < 0);
}
@@ -253,6 +336,7 @@ class _TerminalScrollGestureHandlerState
/// batch, together with the lines scrolled while it caught up.
void _queueLines(int delta) {
if (delta == 0) return;
+ _unsentFromLink = false;
// Turned back: what still waits would carry the screen away from the finger.
if (_unsentLines != 0 && (_unsentLines < 0) != (delta < 0)) {
_unsentLines = 0;
@@ -264,16 +348,80 @@ class _TerminalScrollGestureHandlerState
_sendUnsentLines();
}
+ /// AUTONOMOUS PATCH: [lines] more from [RemoteScrollLink]. The mirror counts
+ /// every row it asks for, so none is dropped here, as [_queueLines] drops them
+ /// for the finger: a turn back nets against what still waits, and there is no
+ /// cap of a screen — the mirror bounds what it asks for itself.
+ void _queueLinkLines(int lines) {
+ if (lines == 0) return;
+ // What the finger left waiting is not the mirror's to send.
+ if (!_unsentFromLink) _unsentLines = 0;
+ _unsentFromLink = true;
+ _unsentLines += lines;
+ _sendUnsentLines();
+ }
+
+ /// AUTONOMOUS PATCH: [RemoteScrollLink.cancel] — the mirror's rows still
+ /// waiting are dropped, and how many is returned. Left to go out, they
+ /// scrolled the program on for seconds after the finger let go: the screen
+ /// moved by itself (reported on a phone, 2026-10-06).
+ int _cancelLinkLines() {
+ if (!_unsentFromLink) return 0;
+ final dropped = _unsentLines;
+ _unsentLines = 0;
+ _gapWait?.cancel();
+ _gapWait = null;
+ return dropped;
+ }
+
+ /// AUTONOMOUS PATCH: [RemoteScrollLink.sendPage] — Page Up or Page Down,
+ /// alone: nothing waiting and nothing unanswered, so the program draws this
+ /// page by itself, never two at once. Answered like a batch of wheel events
+ /// (any write from the program), and paced with them.
+ bool _sendLinkPage(int direction) {
+ if (direction == 0 || _unsentLines != 0 || _batchesInFlight > 0) {
+ return false;
+ }
+ // A program scrolled by other means than its keys.
+ if (widget.onAltBufferScroll != null) return false;
+ _batchesInFlight++;
+ _answerWait?.cancel();
+ _answerWait = Timer(_answerWaitLimit, _onAnswerWaitOver);
+ widget.terminal.keyInput(
+ direction < 0 ? TerminalKey.pageUp : TerminalKey.pageDown,
+ );
+ return true;
+ }
+
void _sendUnsentLines() {
if (_unsentLines == 0 || _batchesInFlight >= _maxBatchesInFlight) return;
- final lines = _unsentLines;
- _unsentLines = 0;
+ final fromLink = _unsentFromLink;
+ if (fromLink && _sinceBatch.isRunning && _sinceBatch.elapsed < _burstGap) {
+ _gapWait ??= Timer(_burstGap - _sinceBatch.elapsed, () {
+ _gapWait = null;
+ _sendUnsentLines();
+ });
+ return;
+ }
+ final most = fromLink ? _exactBurst : _maxBatchLines;
+ final lines = _unsentLines.clamp(-most, most);
+ final sign = lines.sign;
+ _unsentLines -= lines;
_batchesInFlight++;
_answerWait?.cancel();
_answerWait = Timer(_answerWaitLimit, _onAnswerWaitOver);
widget.onWheelsSent?.call(lines);
- for (var i = 0; i < lines.abs(); i++) {
- _sendScrollEvent(lines < 0);
+ var sent = lines.abs();
+ // Claude Code drops the first wheel event after a turn (it takes a lone one
+ // for a trackpad's bounce). The mirror counts rows, so it is sent one more
+ // to drop; the finger's own scroll just moves a row less, as it always has.
+ if (fromLink && _lastSentSign != 0 && sign != _lastSentSign) sent++;
+ _lastSentSign = sign;
+ _sinceBatch
+ ..reset()
+ ..start();
+ for (var i = 0; i < sent; i++) {
+ _sendScrollEvent(sign < 0);
}
}
@@ -286,7 +434,10 @@ class _TerminalScrollGestureHandlerState
void _resetPacing() {
_answerWait?.cancel();
_answerWait = null;
+ _gapWait?.cancel();
+ _gapWait = null;
_unsentLines = 0;
+ _unsentFromLink = false;
_batchesInFlight = 0;
}
diff --git a/mobile/third_party/xterm/lib/ui.dart b/mobile/third_party/xterm/lib/ui.dart
index bc2c8a948..256067fa0 100644
--- a/mobile/third_party/xterm/lib/ui.dart
+++ b/mobile/third_party/xterm/lib/ui.dart
@@ -8,3 +8,4 @@ export 'src/ui/shortcut/shortcuts.dart';
export 'src/ui/terminal_text_style.dart';
export 'src/ui/terminal_theme.dart';
export 'src/ui/themes.dart';
+export 'src/ui/remote_scroll_mirror.dart' show RemoteScrollMemory;