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.

17.0 KB
Raw Blame
import 'dart:async';
import 'dart:math' show max;

import 'package:flutter/widgets.dart';
import 'package:xterm/core.dart';
import 'package:xterm/src/ui/infinite_scroll_view.dart';

/// AUTONOMOUS PATCH: how something other than the finger asks a full-screen
/// program to scroll — `RemoteScrollMirror` keeping the program ahead of the
/// finger — through the same pacing the finger's wheel events go through.
class RemoteScrollLink {
  void Function(int lines)? _send;
  bool Function()? _idle;
  int Function()? _cancel;
  bool Function(int direction, int count)? _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 [count] times, in one
  /// write — 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, {int count = 1}) =>
      _page?.call(direction, count) ?? false;

  /// Whether every row asked for has gone out and been answered.
  bool get idle => _idle?.call() ?? true;

  /// 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, int count) page,
  ) {
    _owner = owner;
    _send = send;
    _idle = idle;
    _cancel = cancel;
    _page = page;
  }

  void _detach(Object owner) {
    if (!identical(_owner, owner)) return;
    _owner = null;
    _send = null;
    _idle = null;
    _cancel = null;
    _page = null;
  }
}

/// Handles scrolling gestures in the alternate screen buffer. In alternate
/// screen buffer, the terminal don't have a scrollback buffer, instead, the
/// scroll gestures are converted to escape sequences based on the current
/// report mode declared by the application.
class TerminalScrollGestureHandler extends StatefulWidget {
  const TerminalScrollGestureHandler({
    super.key,
    required this.terminal,
    required this.getCellOffset,
    required this.getLineHeight,
    this.simulateScroll = true,
    this.onAltBufferScroll,
    this.physics,
    this.paced = false,
    this.onWheelsSent,
    this.link,
    this.onScrollPosition,
    this.onScrollStart,
    this.onScrollEnd,
    required this.child,
  });

  final Terminal terminal;

  /// Returns the cell offset for the pixel offset.
  final CellOffset Function(Offset) getCellOffset;

  /// Returns the pixel height of lines in the terminal.
  final double Function() getLineHeight;

  /// Whether to simulate scroll events in the terminal when the application
  /// doesn't declare it supports mouse wheel events. true by default as it
  /// is the default behavior of most terminals.
  final bool simulateScroll;

  /// When set, takes over alt-buffer scroll entirely — [terminal].mouseInput/keyInput are never
  /// called, this is asked instead. For a program that owns terminal mouse-tracking but doesn't
  /// correctly handle wheel reports itself (confirmed live: Grok's CLI echoes the raw SGR escape
  /// bytes into its own prompt as literal characters instead of scrolling), the caller supplying
  /// this hook is expected to know a backend-native way to scroll instead (tmux copy-mode) and not
  /// need the emulator's own mouse/key simulation at all.
  final void Function(bool up)? onAltBufferScroll;

  /// AUTONOMOUS PATCH: the scroll's physics, layered over the platform's — see
  /// `TerminalView.altBufferScrollPhysics`.
  final ScrollPhysics? physics;

  /// AUTONOMOUS PATCH: wheel events go out as fast as the program redraws for
  /// them, not as fast as the finger moves — see
  /// `TerminalView.altBufferScrollPaced`.
  final bool paced;

  /// AUTONOMOUS PATCH: told of each batch of wheel lines as it goes out,
  /// negative for up — see `TerminalView.altBufferScrollAnimated`.
  final void Function(int lines)? onWheelsSent;

  /// AUTONOMOUS PATCH: where something else sends its wheel lines in — see
  /// [RemoteScrollLink].
  final RemoteScrollLink? link;

  /// AUTONOMOUS PATCH: offered the scroll's position first — true takes it, and
  /// then it is not turned into wheel events here: `TerminalView.altBufferScrollMirror`,
  /// where the mirror decides what the program is asked for (through [link]).
  /// False — it cannot take it now — and the scroll goes out as wheels as ever.
  final bool Function(double pixels)? onScrollPosition;

  /// AUTONOMOUS PATCH: a scroll began, at the scrollable's [pixels]; and one
  /// ended — the finger up and any fling run out.
  final void Function(double pixels)? onScrollStart;
  final VoidCallback? onScrollEnd;

  final Widget child;

  @override
  State<TerminalScrollGestureHandler> createState() =>
      _TerminalScrollGestureHandlerState();
}

class _TerminalScrollGestureHandlerState
    extends State<TerminalScrollGestureHandler> {
  /// Whether the application is in alternate screen buffer. If false, then this
  /// widget does nothing.
  var isAltBuffer = false;

  /// The variable that tracks the line offset in last scroll event. Used to
  /// determine how many the scroll events should be sent to the terminal.
  var lastLineOffset = 0;

  /// This variable tracks the last offset where the scroll gesture started.
  /// Used to calculate the cell offset of the terminal mouse event.
  var lastPointerPosition = Offset.zero;

  /// AUTONOMOUS PATCH ([TerminalScrollGestureHandler.paced]): lines scrolled
  /// and not yet sent, negative for up.
  var _unsentLines = 0;

  /// Batches of wheel events sent that no write from the program has answered.
  var _batchesInFlight = 0;

  /// Lets the next batch go when no answer comes: a program already at the top
  /// of its history has nothing to redraw, and a scroll that waited for it
  /// would never move again.
  Timer? _answerWait;

  /// Two, so the next batch is on its way while the program redraws the last.
  static const _maxBatchesInFlight = 2;

  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,
      _queueLinkLines,
      _pacingIdle,
      _cancelLinkLines,
      _sendLinkPage,
    );
    super.initState();
  }

  @override
  void dispose() {
    widget.terminal.removeListener(_onTerminalUpdated);
    widget.link?._detach(this);
    _resetPacing();
    super.dispose();
  }

  bool _pacingIdle() => _unsentLines == 0 && _batchesInFlight == 0;

  @override
  void didUpdateWidget(covariant TerminalScrollGestureHandler oldWidget) {
    if (oldWidget.terminal != widget.terminal) {
      oldWidget.terminal.removeListener(_onTerminalUpdated);
      widget.terminal.addListener(_onTerminalUpdated);
      isAltBuffer = widget.terminal.isUsingAltBuffer;
      _resetPacing();
    } else if (!widget.paced) {
      _resetPacing();
    }
    if (!identical(oldWidget.link, widget.link)) {
      oldWidget.link?._detach(this);
      widget.link?._attach(
        this,
        _queueLinkLines,
        _pacingIdle,
        _cancelLinkLines,
        _sendLinkPage,
      );
    }
    super.didUpdateWidget(oldWidget);
  }

  void _onTerminalUpdated() {
    if (isAltBuffer != widget.terminal.isUsingAltBuffer) {
      isAltBuffer = widget.terminal.isUsingAltBuffer;
      _resetPacing();
      setState(() {});
      return;
    }
    // AUTONOMOUS PATCH: the program wrote — on the alternate buffer, its redraw
    // for the wheel events in flight — so another batch may go. Any write
    // counts: one that answers nothing only lets the next batch go sooner.
    if (_batchesInFlight > 0) {
      _batchesInFlight--;
      if (_batchesInFlight == 0) {
        _answerWait?.cancel();
        _answerWait = null;
      }
      _sendUnsentLines();
    }
  }

  /// Send a single scroll event to the terminal. If [simulateScroll] is true,
  /// then if the application doesn't recognize mouse wheel events, this method
  /// will simulate scroll events by sending up/down arrow keys.
  void _sendScrollEvent(bool up) {
    final onAltBufferScroll = widget.onAltBufferScroll;
    if (onAltBufferScroll != null) {
      onAltBufferScroll(up);
      return;
    }

    final position = widget.getCellOffset(lastPointerPosition);

    final handled = widget.terminal.mouseInput(
      up ? TerminalMouseButton.wheelUp : TerminalMouseButton.wheelDown,
      TerminalMouseButtonState.down,
      position,
    );

    if (!handled && widget.simulateScroll) {
      widget.terminal.keyInput(
        up ? TerminalKey.arrowUp : TerminalKey.arrowDown,
      );
    }
  }

  void _onScroll(double offset) {
    final currentLineOffset = offset ~/ widget.getLineHeight();

    // AUTONOMOUS PATCH: the mirror moves the screen and asks the program for
    // rows itself. Kept in step, so a switch back never sends the whole gap.
    final onScrollPosition = widget.onScrollPosition;
    if (onScrollPosition != null && onScrollPosition(offset)) {
      lastLineOffset = currentLineOffset;
      return;
    }

    final delta = currentLineOffset - lastLineOffset;

    if (widget.paced) {
      _queueLines(delta);
    } else {
      if (delta != 0) {
        widget.onWheelsSent?.call(delta);
        _lastSentSign = delta.sign;
        _sinceBatch
          ..reset()
          ..start();
      }
      for (var i = 0; i < delta.abs(); i++) {
        _sendScrollEvent(delta < 0);
      }
    }

    lastLineOffset = currentLineOffset;
  }

  /// AUTONOMOUS PATCH ([TerminalScrollGestureHandler.paced]): [delta] more
  /// lines to scroll — sent now if the program has kept up, else in the next
  /// 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;
    }
    // At most a screen waits. On a slow link the rest of a fast fling is
    // dropped, rather than played out long after the fling has stopped.
    final screen = max(1, widget.terminal.viewHeight);
    _unsentLines = (_unsentLines + delta).clamp(-screen, screen);
    _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,
  /// [count] of them together, alone: nothing waiting and nothing unanswered,
  /// so the program draws these pages by themselves. Answered like a batch of
  /// wheel events (any write from the program), and paced with them.
  bool _sendLinkPage(int direction, int count) {
    if (direction == 0 ||
        count < 1 ||
        _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);
    for (var i = 0; i < count; i++) {
      widget.terminal.keyInput(
        direction < 0 ? TerminalKey.pageUp : TerminalKey.pageDown,
      );
    }
    return true;
  }

  void _sendUnsentLines() {
    if (_unsentLines == 0 || _batchesInFlight >= _maxBatchesInFlight) return;
    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);
    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);
    }
  }

  void _onAnswerWaitOver() {
    _answerWait = null;
    _batchesInFlight = 0;
    _sendUnsentLines();
  }

  void _resetPacing() {
    _answerWait?.cancel();
    _answerWait = null;
    _gapWait?.cancel();
    _gapWait = null;
    _unsentLines = 0;
    _unsentFromLink = false;
    _batchesInFlight = 0;
  }

  @override
  Widget build(BuildContext context) {
    if (!isAltBuffer) {
      return widget.child;
    }

    return Listener(
      onPointerSignal: (event) {
        lastPointerPosition = event.position;
      },
      onPointerDown: (event) {
        lastPointerPosition = event.position;
      },
      child: NotificationListener<ScrollNotification>(
        // AUTONOMOUS PATCH: where a scroll begins and ends — for
        // [TerminalScrollGestureHandler.onScrollStart] and `onScrollEnd`. Only
        // this scrollable's own, and passed on for the page to see as well.
        onNotification: (notification) {
          if (notification.depth != 0) return false;
          if (notification is ScrollStartNotification) {
            widget.onScrollStart?.call(notification.metrics.pixels);
          } else if (notification is ScrollEndNotification) {
            widget.onScrollEnd?.call();
          }
          return false;
        },
        child: InfiniteScrollView(
          onScroll: _onScroll,
          physics: widget.physics,
          child: widget.child,
        ),
      ),
    );
  }
}