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): implement software keyboard support with TerminalKeyBar and control chord handling

Dev jacobe95b379785d4
diff --git a/desktop/third_party/xterm/README.autonomous.md b/desktop/third_party/xterm/README.autonomous.md
index 0f705cf47..7b2f5e975 100644
--- a/desktop/third_party/xterm/README.autonomous.md
+++ b/desktop/third_party/xterm/README.autonomous.md
@@ -154,3 +154,19 @@ it if one is dropped.
`--flag` stay syntax rather than typography. Regression:
`mobile/test/terminal_ime_input_test.dart`, the only build that reaches the
mobile branch.
+
+10. **Return does not leave the line it just sent sitting in the prompt**
+ (`lib/src/ui/custom_text_edit.dart`). iOS answers the Return key by calling
+ `performAction` and then inserting the `\n` into its own buffer anyway:
+ `shouldChangeTextInRange:` returns YES for the default return key
+ (`FlutterTextInputPlugin.mm`). So an editing value the terminal has ALREADY
+ acted on arrives right after the action — by which point
+ `resetEditingState` has emptied the mirror, so the diff retyped the whole
+ line into the pty and followed it with a literal LF. A TUI reads that as
+ Ctrl+J, a soft newline rather than a submit, so the message the user just
+ sent reappeared in the prompt underneath its own answer. That one value is
+ now recognised by its shape, dropped, and the native buffer put back on the
+ state the action left. It is one shot, so real typing after a submit is
+ never swallowed, and Android performs its editor action without the second
+ insert so nothing there matches. Regression:
+ `mobile/test/terminal_ime_input_test.dart`.
diff --git a/desktop/third_party/xterm/lib/src/ui/custom_text_edit.dart b/desktop/third_party/xterm/lib/src/ui/custom_text_edit.dart
index 204184186..f2c4cf46b 100644
--- a/desktop/third_party/xterm/lib/src/ui/custom_text_edit.dart
+++ b/desktop/third_party/xterm/lib/src/ui/custom_text_edit.dart
@@ -264,14 +264,47 @@ class CustomTextEditState extends State<CustomTextEdit> with TextInputClient {
return null;
}
+ /// The native buffer's text at the moment the terminal accepted an action.
+ ///
+ /// iOS answers Return by calling [performAction] and then inserting the
+ /// newline into its own buffer anyway: `shouldChangeTextInRange:` returns YES
+ /// for the default return key (Flutter's `FlutterTextInputPlugin.mm`). So a
+ /// value the terminal has ALREADY acted on arrives right after the action —
+ /// and by then [resetEditingState] has emptied the mirror, so diffing it
+ /// retypes the whole line into the pty and follows it with a literal LF,
+ /// which a TUI reads as Ctrl+J: a soft newline, not a submit. The line the
+ /// user just sent is left sitting in the prompt underneath its own answer.
+ ///
+ /// Android performs the editor action without that second insert, and nothing
+ /// it does send matches the shape [_consumeActionEcho] checks for.
+ String? _pendingActionEcho;
+
@override
void updateEditingValue(TextEditingValue value) {
+ if (_consumeActionEcho(value)) return;
_applyEditingValue(
value,
hasTextMutation: value.text != _currentEditingState.text,
);
}
+ /// Drops the newline described by [_pendingActionEcho] and puts the native
+ /// buffer back on the state the action left, so the line the terminal was
+ /// already sent cannot be typed a second time.
+ ///
+ /// One shot: whatever arrives first after an action disarms this, so real
+ /// typing that follows a submit is never swallowed.
+ bool _consumeActionEcho(TextEditingValue value) {
+ final submitted = _pendingActionEcho;
+ _pendingActionEcho = null;
+ if (submitted == null) return false;
+ // The newline either lands on the buffer the action was performed on, or
+ // after this side's reset has already emptied it — whichever wins the race.
+ if (value.text != '$submitted\n' && value.text != '\n') return false;
+ _connection?.setEditingState(_currentEditingState);
+ return true;
+ }
+
void _applyEditingValue(
TextEditingValue value, {
required bool hasTextMutation,
@@ -339,7 +372,9 @@ class CustomTextEditState extends State<CustomTextEdit> with TextInputClient {
@override
void performAction(TextInputAction action) {
- // print('performAction $action');
+ // Captured before the handler runs: it is what the pty has been sent, and
+ // what iOS is about to append its newline to. See [_pendingActionEcho].
+ _pendingActionEcho = _currentEditingState.text;
widget.onAction(action);
}
diff --git a/mobile/lib/phone/terminal_key_bar.dart b/mobile/lib/phone/terminal_key_bar.dart
new file mode 100644
index 000000000..95be7cf36
--- /dev/null
+++ b/mobile/lib/phone/terminal_key_bar.dart
@@ -0,0 +1,179 @@
+import 'package:flutter/material.dart';
+import 'package:flutter/services.dart';
+import 'package:lucide_icons_flutter/lucide_icons.dart';
+import 'package:xterm/xterm.dart';
+
+import 'package:harness_mobile/shared/theme/app_theme.dart';
+
+/// The keys a phone keyboard does not have, in a strip above the one it does.
+///
+/// A pane is driven by `esc`, `tab`, the arrows and `ctrl` far more than by
+/// anything the alphabet offers — interrupting Claude Code, cycling its modes,
+/// walking shell history, `^C`. None of them exist on a software keyboard, so
+/// until this strip a phone could type at an agent but could not DRIVE one.
+///
+/// It appears with the keyboard and goes away with it: the terminal is short
+/// enough on a phone that two rows of chrome are worth their height only while
+/// someone is actually typing.
+class TerminalKeyBar extends StatelessWidget {
+ const TerminalKeyBar({
+ super.key,
+ required this.terminal,
+ required this.enabled,
+ required this.controlArmed,
+ required this.onControlToggle,
+ required this.onDismissKeyboard,
+ });
+
+ final Terminal terminal;
+
+ /// False while the stream is not accepting input — the strip stays visible
+ /// (it moves with the keyboard, and a row that vanished would take the
+ /// keyboard's place with it) but dims and stops answering.
+ final bool enabled;
+
+ /// Whether the next character typed leaves as a control chord. Owned by the
+ /// session, which is also what spends it — see `TerminalSession.armControl`.
+ final bool controlArmed;
+ final ValueChanged<bool> onControlToggle;
+ final VoidCallback onDismissKeyboard;
+
+ void _send(void Function() action) {
+ if (!enabled) return;
+ HapticFeedback.selectionClick();
+ action();
+ }
+
+ @override
+ Widget build(BuildContext context) {
+ AppTheme.watch(context);
+ final top = <Widget>[
+ _key(label: 'esc', onTap: () => terminal.keyInput(TerminalKey.escape)),
+ _key(label: 'tab', onTap: () => terminal.keyInput(TerminalKey.tab)),
+ for (final char in const ['~', '|', '/', '-'])
+ _key(label: char, onTap: () => terminal.textInput(char)),
+ _key(
+ icon: LucideIcons.arrowLeft300,
+ semanticLabel: 'Left',
+ onTap: () => terminal.keyInput(TerminalKey.arrowLeft),
+ ),
+ _key(
+ icon: LucideIcons.arrowUp300,
+ semanticLabel: 'Up',
+ onTap: () => terminal.keyInput(TerminalKey.arrowUp),
+ ),
+ _key(
+ icon: LucideIcons.arrowDown300,
+ semanticLabel: 'Down',
+ onTap: () => terminal.keyInput(TerminalKey.arrowDown),
+ ),
+ _key(
+ icon: LucideIcons.arrowRight300,
+ semanticLabel: 'Right',
+ onTap: () => terminal.keyInput(TerminalKey.arrowRight),
+ ),
+ // Not a key the pty ever hears about: it puts the keyboard away, which on
+ // a phone is the only way to read a full screen of output.
+ _key(
+ icon: LucideIcons.chevronDown300,
+ semanticLabel: 'Hide keyboard',
+ alwaysEnabled: true,
+ onTap: onDismissKeyboard,
+ ),
+ ];
+ final bottom = <Widget>[
+ _key(
+ label: 'ctrl',
+ held: controlArmed,
+ onTap: () => onControlToggle(!controlArmed),
+ ),
+ for (final digit in const ['1', '2', '3', '4', '5', '6', '7', '8', '9', '0'])
+ _key(label: digit, onTap: () => terminal.textInput(digit)),
+ ];
+
+ return ExcludeFocus(
+ // ⚠️ Load-bearing. Every key here is a tap target inside a focus scope the
+ // TERMINAL owns: a focusable one would take the focus on tap, the input
+ // connection would close, and the keyboard this strip is attached to
+ // would leave with it on the first `esc`.
+ child: DecoratedBox(
+ decoration: BoxDecoration(
+ color: AppPalette.panelBg,
+ border: Border(top: BorderSide(color: AppGlass.hair)),
+ ),
+ child: Padding(
+ padding: const EdgeInsets.all(6),
+ // Held out of the app-wide text scale like the composer's own type:
+ // at a large scale eleven keys across a phone stop fitting the row.
+ child: MediaQuery.withNoTextScaling(
+ child: Column(
+ mainAxisSize: MainAxisSize.min,
+ children: [_row(top), const SizedBox(height: 6), _row(bottom)],
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+
+ Widget _row(List<Widget> keys) => Row(
+ children: [
+ for (var index = 0; index < keys.length; index++) ...[
+ if (index > 0) const SizedBox(width: 4),
+ Expanded(child: keys[index]),
+ ],
+ ],
+ );
+
+ Widget _key({
+ String? label,
+ IconData? icon,
+ String? semanticLabel,
+ bool held = false,
+ bool alwaysEnabled = false,
+ required VoidCallback onTap,
+ }) {
+ assert((label == null) != (icon == null), 'a key carries one of the two');
+ final live = enabled || alwaysEnabled;
+ final foreground = held
+ ? AppPalette.accentOnSurface
+ : live
+ ? AppPalette.textPrimary
+ : AppPalette.textFaint;
+ return Semantics(
+ button: true,
+ label: semanticLabel ?? label,
+ // Named so a test can reach the icon keys, which carry no text.
+ key: ValueKey('terminal-key-${semanticLabel ?? label}'),
+ child: GestureDetector(
+ behavior: HitTestBehavior.opaque,
+ onTap: alwaysEnabled ? onTap : () => _send(onTap),
+ child: AnimatedContainer(
+ duration: const Duration(milliseconds: 120),
+ curve: Curves.easeOut,
+ height: 34,
+ alignment: Alignment.center,
+ decoration: BoxDecoration(
+ color: held ? AppSurface.accentWash : AppGlass.surfaceFill,
+ borderRadius: BorderRadius.circular(7),
+ border: Border.all(
+ color: held ? AppPalette.accentOnSurface : AppGlass.lift,
+ ),
+ ),
+ child: icon != null
+ ? Icon(icon, size: 16, color: foreground)
+ : Text(
+ label!,
+ maxLines: 1,
+ style: TextStyle(
+ fontSize: 13,
+ height: 1,
+ color: foreground,
+ fontWeight: FontWeight.w500,
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+}
diff --git a/mobile/lib/phone/terminal_page.dart b/mobile/lib/phone/terminal_page.dart
index 91fccda4c..8b12b530b 100644
--- a/mobile/lib/phone/terminal_page.dart
+++ b/mobile/lib/phone/terminal_page.dart
@@ -14,6 +14,7 @@ import 'phone_header.dart';
import 'phone_sheet.dart';
import 'phone_status.dart';
import 'status_pill.dart';
+import 'terminal_key_bar.dart';
/// One agent's terminal, filling the phone. The header says whose it is and whether it is live;
/// everything below it is the same [TerminalPanel] a desktop tile draws, minus that tile's own
@@ -93,6 +94,12 @@ class _TerminalPageState extends State<TerminalPage>
/// claiming has been off for as long as the keyboard has been visible.
bool _claimSpent = false;
+ /// Whether the software keyboard is up, and with it [TerminalKeyBar].
+ ///
+ /// Read from [View] for the reason [didChangeMetrics] gives: MediaQuery's
+ /// bottom inset is pinned at zero inside this page.
+ bool _keyboardUp = false;
+
@override
void initState() {
super.initState();
@@ -122,11 +129,20 @@ class _TerminalPageState extends State<TerminalPage>
// The FIRST frame of the keyboard rising is enough — it need not finish.
// Spending the claim this early is the point: it is off long before any
// Back press can arrive.
- if (View.of(context).viewInsets.bottom > 0 && !_claimSpent) {
- setState(() => _claimSpent = true);
- }
+ final up = View.of(context).viewInsets.bottom > 0;
+ final claim = _claimSpent || up;
+ if (up == _keyboardUp && claim == _claimSpent) return;
+ setState(() {
+ _keyboardUp = up;
+ _claimSpent = claim;
+ });
}
+ /// Puts the keyboard away without leaving the page — the `⌄` key on
+ /// [TerminalKeyBar]. Dropping focus is what closes the input connection;
+ /// xterm reopens it on the next tap in the pane.
+ void _dismissKeyboard() => FocusManager.instance.primaryFocus?.unfocus();
+
/// The composer starts OPEN here, and the phone owns that answer rather than the pane.
///
@override
@@ -263,6 +279,21 @@ class _TerminalPageState extends State<TerminalPage>
// never had anyway.
),
),
+ // The bottom of this page IS just above the keyboard:
+ // `PhoneShell`'s Scaffold has already resized for it —
+ // the same resize that empties this page's MediaQuery
+ // insets (see [didChangeMetrics]).
+ if (_keyboardUp && session != null)
+ ListenableBuilder(
+ listenable: session,
+ builder: (context, _) => TerminalKeyBar(
+ terminal: session.terminal,
+ enabled: session.acceptsInput,
+ controlArmed: session.controlArmed,
+ onControlToggle: session.armControl,
+ onDismissKeyboard: _dismissKeyboard,
+ ),
+ ),
],
),
),
diff --git a/mobile/lib/terminal/control_chord.dart b/mobile/lib/terminal/control_chord.dart
new file mode 100644
index 000000000..3b82f16df
--- /dev/null
+++ b/mobile/lib/terminal/control_chord.dart
@@ -0,0 +1,21 @@
+/// What `Ctrl` + a character sends down a pty.
+///
+/// A software keyboard has no modifier to hold and produces TEXT rather than
+/// key events, so a phone cannot reach a control chord the way a keymap does.
+/// The pane's key bar arms the modifier instead and the next character typed is
+/// translated here, on its way out — see [TerminalSession.armControl].
+String? controlChordFor(String character) {
+ final runes = character.runes;
+ if (runes.length != 1) return null;
+ final code = runes.first;
+
+ // The control block IS the printable block minus 0x40, in order: @ A-Z [ \ ] ^ _
+ if (code >= 0x40 && code <= 0x5f) return String.fromCharCode(code - 0x40);
+ // A phone types lowercase, and Ctrl has never cared about case.
+ if (code >= 0x61 && code <= 0x7a) return String.fromCharCode(code - 0x60);
+ // The two that table cannot reach, and that shells lean on anyway.
+ if (code == 0x20) return '\x00'; // Ctrl+Space — NUL, set-mark in emacs/readline
+ if (code == 0x3f) return '\x7f'; // Ctrl+? — DEL
+
+ return null;
+}
diff --git a/mobile/lib/terminal/terminal_session.dart b/mobile/lib/terminal/terminal_session.dart
index 12b7c5618..a29e38623 100644
--- a/mobile/lib/terminal/terminal_session.dart
+++ b/mobile/lib/terminal/terminal_session.dart
@@ -7,6 +7,7 @@ import 'package:flutter/foundation.dart';
import 'package:xterm/xterm.dart';
import '../core/crash_log.dart';
+import 'control_chord.dart';
import 'terminal_binary.dart';
import 'terminal_input.dart';
import 'terminal_viewport.dart';
@@ -795,6 +796,35 @@ class TerminalSession extends ChangeNotifier {
result.onResize = (width, height, _, _) => resize(width, height);
}
+ /// Whether the next character typed leaves as a control chord.
+ ///
+ /// The phone's key bar has a `ctrl` KEY where a desktop has a modifier to
+ /// hold down. Nothing on a software keyboard can be held while another key is
+ /// pressed, and the characters it produces arrive as TEXT rather than as key
+ /// events, so the translation cannot live in a keymap. It happens here
+ /// instead — the one point every keystroke crosses on its way to the pty.
+ bool get controlArmed => _controlArmed;
+ bool _controlArmed = false;
+
+ /// Arms, or clears, the modifier described by [controlArmed].
+ void armControl(bool armed) {
+ if (_controlArmed == armed) return;
+ _controlArmed = armed;
+ notifyListeners();
+ }
+
+ /// Spends [controlArmed] on [data].
+ ///
+ /// One shot, and spent on whatever arrives next whether or not it has a chord:
+ /// the alternative is a modifier that silently stays armed across a keystroke
+ /// it could not translate, and then eats a later one.
+ String _spendArmedControl(String data) {
+ if (!_controlArmed) return data;
+ _controlArmed = false;
+ notifyListeners();
+ return controlChordFor(data) ?? data;
+ }
+
/// Sends a composed message as one turn.
///
/// This does NOT write bytes into the pane. It sends the same `message` frame the web client
@@ -1004,6 +1034,7 @@ class TerminalSession extends ChangeNotifier {
void _onTerminalOutput(String data) {
if (!acceptsInput || data.isEmpty) return;
+ data = _spendArmedControl(data);
final bytes = utf8.encode(data);
final isBoundary =
data.contains('\r') ||
diff --git a/mobile/test/control_chord_test.dart b/mobile/test/control_chord_test.dart
new file mode 100644
index 000000000..87639fcdd
--- /dev/null
+++ b/mobile/test/control_chord_test.dart
@@ -0,0 +1,112 @@
+import 'dart:convert';
+import 'dart:typed_data';
+
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/terminal/control_chord.dart';
+import 'package:harness_mobile/terminal/terminal_binary.dart';
+import 'package:harness_mobile/terminal/terminal_session.dart';
+
+void main() {
+ test('a letter takes its place in the control block, in either case', () {
+ expect(controlChordFor('c'), '\x03');
+ expect(controlChordFor('C'), '\x03');
+ expect(controlChordFor('a'), '\x01');
+ expect(controlChordFor('z'), '\x1a');
+ });
+
+ test('so does the punctuation the block actually covers', () {
+ expect(controlChordFor('['), '\x1b'); // Ctrl+[ IS Escape
+ expect(controlChordFor('@'), '\x00');
+ expect(controlChordFor(' '), '\x00'); // set-mark, in readline and emacs
+ expect(controlChordFor('?'), '\x7f');
+ });
+
+ test('anything no chord names is refused rather than mangled', () {
+ expect(controlChordFor(''), isNull);
+ expect(controlChordFor('hi'), isNull); // an IME commit, not a keystroke
+ expect(controlChordFor('é'), isNull);
+ expect(controlChordFor('😀'), isNull);
+ });
+
+ group('an armed session', () {
+ const streamId = '00112233-4455-6677-8899-aabbccddeeff';
+ late List<({String type, Map<String, dynamic> payload})> sent;
+ late List<TerminalBinaryFrame> binarySent;
+ late TerminalSession session;
+
+ setUp(() {
+ sent = [];
+ binarySent = [];
+ session = TerminalSession(
+ machineId: 'machine-1',
+ agentId: 'agent-1',
+ agentName: 'backend-api',
+ engineId: 'claude',
+ send: (type, payload) async {
+ sent.add((type: type, payload: Map<String, dynamic>.from(payload)));
+ return true;
+ },
+ sendBinary: (frame) async {
+ binarySent.add(frame);
+ return true;
+ },
+ );
+ });
+
+ tearDown(() => session.dispose());
+
+ /// Input opens on the first KEYFRAME, not on the ready frame: until a
+ /// screen has arrived there is nothing to type into.
+ Future<void> ready() async {
+ await session.open(initialCols: 100, initialRows: 30);
+ await session.handleFrame('terminal_ready', {
+ 'requestId': sent.single.payload['requestId'],
+ 'protocolVersion': 3,
+ 'streamId': streamId,
+ 'agentId': 'agent-1',
+ });
+ await session.handleBinary(
+ TerminalBinaryFrame(
+ kind: TerminalBinaryKind.keyframe,
+ streamId: streamId,
+ seq: 0,
+ bytes: Uint8List.fromList(utf8.encode('prompt> ')),
+ compressed: false,
+ cols: 100,
+ rows: 30,
+ ),
+ );
+ expect(session.acceptsInput, isTrue);
+ }
+
+ /// Typing is batched behind a short window; this waits it out.
+ Future<String> typed(String text) async {
+ binarySent.clear();
+ session.terminal.textInput(text);
+ await Future<void>.delayed(const Duration(milliseconds: 40));
+ return binarySent.map((frame) => utf8.decode(frame.bytes)).join();
+ }
+
+ test('sends the next character as a chord, then disarms', () async {
+ await ready();
+
+ session.armControl(true);
+ expect(await typed('c'), '\x03');
+ expect(session.controlArmed, isFalse);
+
+ // The one after it is ordinary text again — a phone `ctrl` is a key
+ // pressed once, not a modifier anyone can keep held down.
+ expect(await typed('c'), 'c');
+ });
+
+ test('spends the modifier even on a keystroke it cannot translate', () async {
+ await ready();
+
+ session.armControl(true);
+ // An IME commit, not a keystroke. Left alone, and the modifier goes with
+ // it rather than lying in wait for a later character.
+ expect(await typed('hôm'), 'hôm');
+ expect(session.controlArmed, isFalse);
+ });
+ });
+}
diff --git a/mobile/test/terminal_ime_input_test.dart b/mobile/test/terminal_ime_input_test.dart
index f61a06742..9308896e2 100644
--- a/mobile/test/terminal_ime_input_test.dart
+++ b/mobile/test/terminal_ime_input_test.dart
@@ -86,6 +86,47 @@ void main() {
variant: TargetPlatformVariant.all(),
);
+ testWidgets(
+ 'Return submits once, and the newline iOS appends after it is not typed '
+ 'into the pty',
+ (tester) async {
+ final terminal = newTerminal();
+ final outbound = <String>[];
+ terminal.onOutput = outbound.add;
+ await pumpTerminal(tester, terminal);
+
+ tester.testTextInput.updateEditingValue(
+ const TextEditingValue(
+ text: 'hi',
+ selection: TextSelection.collapsed(offset: 2),
+ ),
+ );
+ await tester.pump();
+ expect(outbound, ['hi']);
+ outbound.clear();
+
+ // UIKit answers Return by calling the action FIRST...
+ await tester.testTextInput.receiveAction(TextInputAction.newline);
+ await tester.pump();
+
+ // ...and then inserting the `\n` into its own buffer anyway, which comes
+ // back as an editing value the terminal has already acted on.
+ tester.testTextInput.updateEditingValue(
+ const TextEditingValue(
+ text: 'hi\n',
+ selection: TextSelection.collapsed(offset: 3),
+ ),
+ );
+ await tester.pump();
+
+ // Only the Enter. Replaying that value would retype the whole line and
+ // then a literal LF, which a TUI reads as Ctrl+J — a soft newline, not a
+ // submit — leaving the line sitting in the prompt.
+ expect(outbound, ['\r']);
+ },
+ variant: TargetPlatformVariant.only(TargetPlatform.iOS),
+ );
+
testWidgets(
'Telex sends the composed word, not the letters it was typed from',
(tester) async {
diff --git a/mobile/test/terminal_key_bar_test.dart b/mobile/test/terminal_key_bar_test.dart
new file mode 100644
index 000000000..adff08e12
--- /dev/null
+++ b/mobile/test/terminal_key_bar_test.dart
@@ -0,0 +1,93 @@
+import 'package:flutter/material.dart';
+import 'package:flutter_test/flutter_test.dart';
+import 'package:harness_mobile/phone/terminal_key_bar.dart';
+import 'package:xterm/xterm.dart';
+
+void main() {
+ late Terminal terminal;
+ late List<String> outbound;
+ late List<bool> armings;
+ late int dismissals;
+
+ setUp(() {
+ terminal = Terminal(maxLines: 200, reflowEnabled: false)..resize(80, 12);
+ outbound = [];
+ armings = [];
+ dismissals = 0;
+ terminal.onOutput = outbound.add;
+ });
+
+ Future<void> pumpBar(
+ WidgetTester tester, {
+ bool enabled = true,
+ bool controlArmed = false,
+ }) async {
+ await tester.pumpWidget(
+ MaterialApp(
+ home: Scaffold(
+ body: Align(
+ alignment: Alignment.bottomCenter,
+ child: TerminalKeyBar(
+ terminal: terminal,
+ enabled: enabled,
+ controlArmed: controlArmed,
+ onControlToggle: armings.add,
+ onDismissKeyboard: () => dismissals++,
+ ),
+ ),
+ ),
+ ),
+ );
+ }
+
+ Future<void> tapKey(WidgetTester tester, String name) async {
+ await tester.tap(find.byKey(ValueKey('terminal-key-$name')));
+ await tester.pump();
+ }
+
+ testWidgets('the keys a software keyboard has no room for reach the pty', (
+ tester,
+ ) async {
+ await pumpBar(tester);
+
+ await tapKey(tester, 'esc');
+ await tapKey(tester, 'tab');
+ await tapKey(tester, 'Up');
+ await tapKey(tester, '~');
+ await tapKey(tester, '7');
+
+ expect(outbound, ['\x1b', '\t', '\x1b[A', '~', '7']);
+ });
+
+ testWidgets('ctrl is handed to the session, which owns the modifier', (
+ tester,
+ ) async {
+ await pumpBar(tester);
+
+ await tapKey(tester, 'ctrl');
+
+ // Nothing goes down the wire: the chord is made from the NEXT character,
+ // and only the session sees that one arrive.
+ expect(outbound, isEmpty);
+ expect(armings, [true]);
+
+ await pumpBar(tester, controlArmed: true);
+ await tapKey(tester, 'ctrl');
+ expect(armings, [true, false]);
+ });
+
+ testWidgets('a stream that takes no input answers nothing — except the key '
+ 'that puts the keyboard away', (tester) async {
+ await pumpBar(tester, enabled: false);
+
+ await tapKey(tester, 'esc');
+ await tapKey(tester, 'ctrl');
+ expect(outbound, isEmpty);
+ expect(armings, isEmpty);
+
+ // Hiding the keyboard is this page's own business, not the pane's, and it
+ // is the way back to a full screen of output — it works either way.
+ await tapKey(tester, 'Hide keyboard');
+ expect(dismissals, 1);
+ });
+}
diff --git a/mobile/third_party/xterm/README.autonomous.md b/mobile/third_party/xterm/README.autonomous.md
index c63917ca1..8f6c37cf8 100644
--- a/mobile/third_party/xterm/README.autonomous.md
+++ b/mobile/third_party/xterm/README.autonomous.md
@@ -163,3 +163,19 @@ it if one is dropped.
desktop reads images through `NativeClipboard` on ⌘V instead — mirroring it
there would have been an inert change carrying a privacy decision made for
a platform that never sees it.
+
+11. **Return does not leave the line it just sent sitting in the prompt**
+ (`lib/src/ui/custom_text_edit.dart`). iOS answers the Return key by calling
+ `performAction` and then inserting the `\n` into its own buffer anyway:
+ `shouldChangeTextInRange:` returns YES for the default return key
+ (`FlutterTextInputPlugin.mm`). So an editing value the terminal has ALREADY
+ acted on arrives right after the action — by which point
+ `resetEditingState` has emptied the mirror, so the diff retyped the whole
+ line into the pty and followed it with a literal LF. A TUI reads that as
+ Ctrl+J, a soft newline rather than a submit, so the message the user just
+ sent reappeared in the prompt underneath its own answer. That one value is
+ now recognised by its shape, dropped, and the native buffer put back on the
+ state the action left. It is one shot, so real typing after a submit is
+ never swallowed, and Android performs its editor action without the second
+ insert so nothing there matches. Regression:
+ `mobile/test/terminal_ime_input_test.dart`.
diff --git a/mobile/third_party/xterm/lib/src/ui/custom_text_edit.dart b/mobile/third_party/xterm/lib/src/ui/custom_text_edit.dart
index 8f6f4ef99..b29aa59bb 100644
--- a/mobile/third_party/xterm/lib/src/ui/custom_text_edit.dart
+++ b/mobile/third_party/xterm/lib/src/ui/custom_text_edit.dart
@@ -294,14 +294,47 @@ class CustomTextEditState extends State<CustomTextEdit> with TextInputClient {
return null;
}
+ /// The native buffer's text at the moment the terminal accepted an action.
+ ///
+ /// iOS answers Return by calling [performAction] and then inserting the
+ /// newline into its own buffer anyway: `shouldChangeTextInRange:` returns YES
+ /// for the default return key (Flutter's `FlutterTextInputPlugin.mm`). So a
+ /// value the terminal has ALREADY acted on arrives right after the action —
+ /// and by then [resetEditingState] has emptied the mirror, so diffing it
+ /// retypes the whole line into the pty and follows it with a literal LF,
+ /// which a TUI reads as Ctrl+J: a soft newline, not a submit. The line the
+ /// user just sent is left sitting in the prompt underneath its own answer.
+ ///
+ /// Android performs the editor action without that second insert, and nothing
+ /// it does send matches the shape [_consumeActionEcho] checks for.
+ String? _pendingActionEcho;
+
@override
void updateEditingValue(TextEditingValue value) {
+ if (_consumeActionEcho(value)) return;
_applyEditingValue(
value,
hasTextMutation: value.text != _currentEditingState.text,
);
}
+ /// Drops the newline described by [_pendingActionEcho] and puts the native
+ /// buffer back on the state the action left, so the line the terminal was
+ /// already sent cannot be typed a second time.
+ ///
+ /// One shot: whatever arrives first after an action disarms this, so real
+ /// typing that follows a submit is never swallowed.
+ bool _consumeActionEcho(TextEditingValue value) {
+ final submitted = _pendingActionEcho;
+ _pendingActionEcho = null;
+ if (submitted == null) return false;
+ // The newline either lands on the buffer the action was performed on, or
+ // after this side's reset has already emptied it — whichever wins the race.
+ if (value.text != '$submitted\n' && value.text != '\n') return false;
+ _connection?.setEditingState(_currentEditingState);
+ return true;
+ }
+
void _applyEditingValue(
TextEditingValue value, {
required bool hasTextMutation,
@@ -369,7 +402,9 @@ class CustomTextEditState extends State<CustomTextEdit> with TextInputClient {
@override
void performAction(TextInputAction action) {
- // print('performAction $action');
+ // Captured before the handler runs: it is what the pty has been sent, and
+ // what iOS is about to append its newline to. See [_pendingActionEcho].
+ _pendingActionEcho = _currentEditingState.text;
widget.onAction(action);
}