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.

fix(mobile): lead the key strip with a question's key hints

tony564e8c0f4626
diff --git a/mobile/lib/phone/terminal_key_bar.dart b/mobile/lib/phone/terminal_key_bar.dart
index ccd0b4d3e..bfde97ad1 100644
--- a/mobile/lib/phone/terminal_key_bar.dart
+++ b/mobile/lib/phone/terminal_key_bar.dart
@@ -47,12 +47,16 @@ import 'tty.dart';
///
/// ⚠️ **The other exception: the pane's own keys — [hints] — join the row, and
/// only then does it scroll.** They are what Codex offers on this screen and
-/// nowhere else (`ctrl+] skip`, `⌥+↓ main prompt`), so they follow the arrows
-/// on the SAME row, which scrolls sideways while they are there and brings
-/// them into view as they arrive. Never a line of their own: a second row
-/// cost the terminal a line of output, and a strip of buttons floating over
-/// the pane covered the very hints it was read off. The fixed keys keep their
-/// size either way — only how far along the row is scrolled changes.
+/// nowhere else (`shift+← to answer`, `ctrl+] skip`, `⌥+↓ main prompt`), so
+/// they LEAD the same row and push the fixed keys along it, and the row
+/// scrolls sideways while they are there. At the head, not the tail: past a
+/// row the fixed keys already fill, a queued question's `shift+← answer` sat
+/// off the edge with nothing on screen to say it was there. Claude Code's
+/// `shift+tab to cycle` is the one that follows the arrows instead — see
+/// [KeyHint.trails]. Never a line of their own: a second row cost the terminal
+/// a line of output, and a strip of buttons floating over the pane covered the
+/// very hints it was read off. The fixed keys keep their size either way —
+/// only where along the row they sit changes.
class TerminalKeyBar extends StatefulWidget {
const TerminalKeyBar({
super.key,
@@ -85,7 +89,8 @@ class TerminalKeyBar extends StatefulWidget {
/// The keys the pane's chrome offers and a phone cannot press — see
/// [parseKeyHints]. Each is drawn as the key and Codex's own word for what
/// it does, as the pane printed them, in the terminal's face — so it reads
- /// as the hint it was read off. Empty leaves the row as it always was.
+ /// as the hint it was read off. Drawn before the row's own keys, but for the
+ /// [KeyHint.trails] ones, after them. Empty leaves the row as it always was.
final List<KeyHint> hints;
/// Called after `tab` or `/` changed the prompt without the software
@@ -478,15 +483,15 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
/// How wide [_rule] is — `8 + 1 + 8`, or the single gap in its place.
double get _ruleWidth => _canSendImage ? 17 : 4;
- /// The row while the pane offers its own keys: the fixed keys, then
- /// [TerminalKeyBar.hints], scrolling sideways together; the two apart keys
- /// stay pinned past the rule.
+ /// The row while the pane offers its own keys: [TerminalKeyBar.hints] at its
+ /// head, the fixed keys, then the [KeyHint.trails] ones, scrolling sideways
+ /// together; the two apart keys stay pinned past the rule.
///
/// ⚠️ **Every fixed key keeps exactly the width [_row] gives it.** The part
/// is worked out the way the `Expanded` row divides [width] — the same keys,
- /// gaps and rule — so the keys do not shrink or move when a hint arrives:
- /// they fill the visible part of the row as they always do, and the hints
- /// start where it ends. [_revealHints] then scrolls them into view.
+ /// gaps and rule — so the keys do not shrink when a hint arrives: the hints
+ /// at the head push them along, and the ones at the tail start where the
+ /// visible part of the row ends. [_revealHints] scrolls to whichever arrived.
Widget _rowWithHints(List<_Slot> keys, List<_Slot> apart, double width) {
const gap = 4.0;
final gaps =
@@ -499,7 +504,7 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
if (!part.isFinite || part <= 0) {
return Row(children: [..._row(keys), ..._rule(), ..._row(apart)]);
}
- final hints = widget.hints;
+ final (:lead, :trail) = _split(widget.hints);
return Row(
children: [
Expanded(
@@ -508,16 +513,9 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
scrollDirection: Axis.horizontal,
child: Row(
children: [
+ if (lead.isNotEmpty) ...[..._hintRun(lead), ..._hintRule()],
..._cells(keys, part),
- // The pane's keys are not the strip's: a hairline says so,
- // the way the rule sets the phone's own two apart.
- const SizedBox(width: 6),
- Container(width: 1, height: 22, color: AppGlass.hair),
- const SizedBox(width: 6),
- for (var i = 0; i < hints.length; i++) ...[
- if (i > 0) const SizedBox(width: gap),
- _hint(hints[i]),
- ],
+ if (trail.isNotEmpty) ...[..._hintRule(), ..._hintRun(trail)],
],
),
),
@@ -528,6 +526,37 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
);
}
+ /// [hints] by where the row draws them: before its own keys, and after —
+ /// see [KeyHint.trails]. Each side keeps the order the pane printed them in.
+ static ({List<KeyHint> lead, List<KeyHint> trail}) _split(
+ List<KeyHint> hints,
+ ) => (
+ lead: [
+ for (final hint in hints)
+ if (!hint.trails) hint,
+ ],
+ trail: [
+ for (final hint in hints)
+ if (hint.trails) hint,
+ ],
+ );
+
+ /// A run of the pane's keys, each as wide as its words.
+ List<Widget> _hintRun(List<KeyHint> hints) => [
+ for (var i = 0; i < hints.length; i++) ...[
+ if (i > 0) const SizedBox(width: 4),
+ _hint(hints[i]),
+ ],
+ ];
+
+ /// The pane's keys are not the strip's: a hairline between them says so,
+ /// the way [_rule] sets the phone's own two apart.
+ List<Widget> _hintRule() => [
+ const SizedBox(width: 6),
+ Container(width: 1, height: 22, color: AppGlass.hair),
+ const SizedBox(width: 6),
+ ];
+
/// A run of keys at a fixed width each, [part] times its [_Slot.parts] —
/// [_row]'s layout, in a row that scrolls and so cannot divide itself with
/// `Expanded`.
@@ -541,17 +570,27 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
/// Keeps the fixed keys and the hints on one row.
final ScrollController _scroll = ScrollController();
- // ⚠️ **Not scrolled to the hints as the strip opens.** It was, and Claude Code
- // offers `shift+tab to cycle` on every prompt, so every open slid esc and tab
- // off the left edge — while the pane's own line said "esc to interrupt". The
- // strip opens on its own keys; hints that ARRIVE while it is open (a question's
- // keys, say) are scrolled to, and the rest are a sideways swipe away.
+ // ⚠️ **Not scrolled as the strip opens.** It was — to the end, where every
+ // hint then sat — and Claude Code offers `shift+tab to cycle` on every prompt,
+ // so every open slid esc and tab off the left edge while the pane's own line
+ // said "esc to interrupt". It opens at its head, which is where a question's
+ // keys are drawn ([KeyHint.trails]); `cycle` is a sideways swipe away. Hints
+ // that ARRIVE while it is open are scrolled to, wherever they are drawn.
@override
void didUpdateWidget(TerminalKeyBar oldWidget) {
super.didUpdateWidget(oldWidget);
if (widget.hints.isNotEmpty && !listEquals(widget.hints, oldWidget.hints)) {
- _revealHints();
+ final now = _split(widget.hints), before = _split(oldWidget.hints);
+ if (now.lead.isNotEmpty && !listEquals(now.lead, before.lead)) {
+ _revealHints(atHead: true);
+ } else if (now.lead.isEmpty &&
+ now.trail.isNotEmpty &&
+ !listEquals(now.trail, before.trail)) {
+ // ⚠️ Never away from a question's keys: with one at the head, a
+ // `cycle` arriving at the tail stays a swipe away.
+ _revealHints(atHead: false);
+ }
}
// `paste` came or went, or an image stopped (or started) counting.
final couldSendImage =
@@ -570,19 +609,25 @@ class _TerminalKeyBarState extends State<TerminalKeyBar>
super.dispose();
}
- /// Scrolls the row to its end, where the hints are, once they are laid out.
+ /// Scrolls the row to the hints that just arrived, once they are laid out:
+ /// back to its head for the ones that lead it, on to its end for the ones
+ /// that trail it.
///
/// ⚠️ **Brought into view, not left past the edge.** The fixed keys fill the
- /// visible row by design, so hints that simply joined it would start just
- /// out of sight and read as no hints at all. Only a new set of hints moves
- /// the row; the same ones redrawn leave it wherever it was swiped to.
- void _revealHints() {
+ /// visible row by design, so hints at its end would start just out of sight
+ /// and read as no hints at all — and a row already swiped along would leave
+ /// a new one at its head out of sight the same way. Only a new set of hints
+ /// moves the row; the same ones redrawn leave it wherever it was swiped to.
+ void _revealHints({required bool atHead}) {
WidgetsBinding.instance.addPostFrameCallback((_) {
if (!mounted || !_scroll.hasClients) return;
- final end = _scroll.position.maxScrollExtent;
- if (_scroll.offset == end) return;
+ final position = _scroll.position;
+ final target = atHead
+ ? position.minScrollExtent
+ : position.maxScrollExtent;
+ if (position.pixels == target) return;
_scroll.animateTo(
- end,
+ target,
duration: const Duration(milliseconds: 250),
curve: Curves.easeOut,
);
diff --git a/mobile/lib/terminal/key_hints.dart b/mobile/lib/terminal/key_hints.dart
index ab075404c..8a150752f 100644
--- a/mobile/lib/terminal/key_hints.dart
+++ b/mobile/lib/terminal/key_hints.dart
@@ -32,6 +32,16 @@ class KeyHint {
/// `main prompt`.
final String action;
+ /// Whether the key strip draws this one AFTER its own keys rather than
+ /// before them — see `TerminalKeyBar.hints`.
+ ///
+ /// ⚠️ **Only Claude Code's `shift+tab to cycle`.** It is on every prompt, so
+ /// at the head of the strip it would push the arrows off the edge for good;
+ /// at the end it is a swipe away and the strip opens as it always did. Every
+ /// other hint is a key a screen is asking for right now — a queued question's
+ /// `shift+← to answer` — and leads the strip.
+ bool get trails => _trailing.hasMatch(action);
+
@override
bool operator ==(Object other) =>
other is KeyHint &&
@@ -121,6 +131,10 @@ final RegExp _offered = RegExp(
caseSensitive: false,
);
+/// The [_offered] hints drawn after the key strip's own keys — see
+/// [KeyHint.trails].
+final RegExp _trailing = RegExp(r'^cycle\b', caseSensitive: false);
+
/// Whether a phone can already press [chord] — the software keyboard or the
/// key strip has it — so a hint for it would only repeat a key on screen.
bool _phoneHas(KeyChord chord) {
diff --git a/mobile/test/terminal_key_bar_test.dart b/mobile/test/terminal_key_bar_test.dart
index 5cf0dd3d7..c0f2a97e3 100644
--- a/mobile/test/terminal_key_bar_test.dart
+++ b/mobile/test/terminal_key_bar_test.dart
@@ -162,48 +162,124 @@ void main() {
expect(dismissals, 1);
});
- testWidgets(
- 'esc stays in view when the pane already offers keys; new ones are scrolled to',
- (tester) async {
- // Claude Code's footer offers a key on every prompt.
- final cycle = parseKeyHints([' ⏵⏵ auto mode on (shift+tab to cycle)']);
- expect(cycle, isNotEmpty);
- Widget bar(List<KeyHint> hints) => MaterialApp(
- home: Scaffold(
- body: Align(
- alignment: Alignment.bottomCenter,
- child: SizedBox(
- width: 360,
- child: TerminalKeyBar(
- terminal: terminal,
- enabled: true,
- hints: hints,
- onDismissKeyboard: () => dismissals++,
- onPromptEdited: () => edits++,
- ),
- ),
+ // Claude Code's footer offers it on every prompt.
+ final cycle = parseKeyHints([' ⏵⏵ auto mode on (shift+tab to cycle)']);
+ // Codex's queue of async questions, over the composer.
+ final queued = parseKeyHints([' ? 1 question', ' shift+← to answer']);
+ final esc = find.byKey(const ValueKey('terminal-key-esc'));
+ final right = find.byKey(const ValueKey('terminal-key-Right'));
+
+ /// The strip at a phone's width, offering [hints] as the pane would.
+ Widget hintedBar(List<KeyHint> hints) => MaterialApp(
+ home: Scaffold(
+ body: Align(
+ alignment: Alignment.bottomCenter,
+ child: SizedBox(
+ width: 360,
+ child: TerminalKeyBar(
+ terminal: terminal,
+ enabled: true,
+ hints: hints,
+ onDismissKeyboard: () => dismissals++,
+ onPromptEdited: () => edits++,
),
),
- );
- await tester.pumpWidget(bar(cycle));
+ ),
+ ),
+ );
+
+ ScrollController rowScroll(WidgetTester tester) => tester
+ .widget<SingleChildScrollView>(find.byType(SingleChildScrollView).first)
+ .controller!;
+
+ testWidgets(
+ 'a queued question\'s key leads the strip as it opens — no swipe to find it',
+ (tester) async {
+ expect(queued.single.action, 'answer');
+ await tester.pumpWidget(hintedBar(queued));
await tester.pumpAndSettle();
- final scroll = tester.widget<SingleChildScrollView>(
- find.byType(SingleChildScrollView).first,
+
+ expect(rowScroll(tester).offset, 0);
+ expect(find.text('answer').hitTestable(), findsOneWidget);
+ // Ahead of the strip's own keys, which it pushes along rather than hides.
+ expect(
+ tester.getTopRight(find.text('answer')).dx,
+ lessThan(tester.getTopLeft(esc).dx),
);
- // Opened on its own keys: esc is where the thumb expects it.
- expect(scroll.controller!.offset, 0);
+ expect(esc.hitTestable(), findsOneWidget);
+
+ await tester.tap(find.text('answer'));
+ await tester.pump();
+ expect(outbound, ['\x1b[1;2D']);
+ },
+ );
+
+ testWidgets(
+ 'esc stays in view under cycle, which trails the strip; a question\'s keys '
+ 'lead it',
+ (tester) async {
+ expect(cycle.single.action, 'cycle');
+ await tester.pumpWidget(hintedBar(cycle));
+ await tester.pumpAndSettle();
+ // Opened on its own keys: esc is where the thumb expects it, and cycle is
+ // past the arrows.
+ expect(rowScroll(tester).offset, 0);
+ expect(esc.hitTestable(), findsOneWidget);
expect(
- find.byKey(const ValueKey('terminal-key-esc')).hitTestable(),
- findsOneWidget,
+ tester.getTopLeft(find.text('cycle')).dx,
+ greaterThan(tester.getTopRight(right).dx),
);
- // A key the pane starts offering while the strip is up is brought into view.
+ // A question's key the pane starts offering takes the head; cycle keeps
+ // the tail.
final more = parseKeyHints([
' ⏵⏵ auto mode on (shift+tab to cycle) · ctrl+] main prompt',
]);
- await tester.pumpWidget(bar(more));
+ await tester.pumpWidget(hintedBar(more));
+ await tester.pumpAndSettle();
+ expect(rowScroll(tester).offset, 0);
+ expect(find.text('main prompt').hitTestable(), findsOneWidget);
+ expect(
+ tester.getTopRight(find.text('main prompt')).dx,
+ lessThan(tester.getTopLeft(esc).dx),
+ );
+ expect(
+ tester.getTopLeft(find.text('cycle')).dx,
+ greaterThan(tester.getTopRight(right).dx),
+ );
+ },
+ );
+
+ testWidgets(
+ 'keys that arrive while the strip is up are scrolled to — a question\'s '
+ 'back to the head, cycle on to the end, never away from a question',
+ (tester) async {
+ await tester.pumpWidget(hintedBar(cycle));
+ await tester.pumpAndSettle();
+ final scroll = rowScroll(tester);
+
+ // Swiped along to cycle; then a queued question arrives.
+ scroll.jumpTo(scroll.position.maxScrollExtent);
+ await tester.pump();
+ expect(scroll.offset, greaterThan(0));
+ await tester.pumpWidget(hintedBar(queued));
+ await tester.pumpAndSettle();
+ expect(scroll.offset, 0);
+ expect(find.text('answer').hitTestable(), findsOneWidget);
+
+ // cycle arriving beside it leaves the question's key in view.
+ await tester.pumpWidget(hintedBar([...queued, ...cycle]));
+ await tester.pumpAndSettle();
+ expect(scroll.offset, 0);
+ expect(find.text('answer').hitTestable(), findsOneWidget);
+
+ // With no question on the pane, cycle arriving is brought into view.
+ await tester.pumpWidget(hintedBar(const []));
+ await tester.pumpWidget(hintedBar(cycle));
await tester.pumpAndSettle();
- expect(scroll.controller!.offset, greaterThan(0));
+ expect(scroll.offset, greaterThan(0));
+ expect(scroll.offset, scroll.position.maxScrollExtent);
+ expect(find.text('cycle').hitTestable(), findsOneWidget);
},
);
}