diff --git a/app/lib/features/terminal/terminal_shortcuts.dart b/app/lib/features/terminal/terminal_shortcuts.dart index 2dbdf0ae..2e3c169b 100644 --- a/app/lib/features/terminal/terminal_shortcuts.dart +++ b/app/lib/features/terminal/terminal_shortcuts.dart @@ -6,8 +6,11 @@ import 'package:flutter/services.dart'; /// handlers, so inside the terminal they toggle rather than reaching the /// shell (whose Ctrl+T, transpose-chars, is then not available) and inside /// text fields they toggle rather than type. +/// +/// A held chord's repeats match too (and are swallowed); only its first +/// press toggles. bool terminalToggleShortcut(KeyEvent event, HardwareKeyboard keyboard) { - if (event is! KeyDownEvent) return false; + if (event is KeyUpEvent) return false; final control = keyboard.isControlPressed; final meta = keyboard.isMetaPressed; final alt = keyboard.isAltPressed; @@ -25,9 +28,9 @@ bool terminalToggleShortcut(KeyEvent event, HardwareKeyboard keyboard) { } /// The step Ctrl+Tab (1) or Ctrl+Shift+Tab (-1) moves between terminal -/// tabs, or null for any other key. +/// tabs (again as it repeats), or null for any other key. int? terminalTabShortcut(KeyEvent event, HardwareKeyboard keyboard) { - if (event is! KeyDownEvent || + if (event is KeyUpEvent || event.logicalKey != LogicalKeyboardKey.tab || !keyboard.isControlPressed || keyboard.isMetaPressed || diff --git a/app/lib/features/terminal/terminal_surface.dart b/app/lib/features/terminal/terminal_surface.dart index cddcc8a1..347553ae 100644 --- a/app/lib/features/terminal/terminal_surface.dart +++ b/app/lib/features/terminal/terminal_surface.dart @@ -135,7 +135,7 @@ class _TerminalSurfaceState extends State if (!mounted) return KeyEventResult.ignored; final keyboard = HardwareKeyboard.instance; if (terminalToggleShortcut(event, keyboard)) { - toggle(); + if (event is KeyDownEvent) toggle(); return KeyEventResult.handled; } final step = terminalTabShortcut(event, keyboard); diff --git a/app/notes/terminal-panel.md b/app/notes/terminal-panel.md index dc09a5ed..0deb4f82 100644 --- a/app/notes/terminal-panel.md +++ b/app/notes/terminal-panel.md @@ -10,9 +10,47 @@ keeps running when the panel is hidden, the app navigates or reloads, and menu): *Bottom panel* docks under the app (the app shrinks above it, never hidden under it); *Floating window* is a window over the app. Both are toggled by the bar's Terminal button (every destination's bar ends - with it) and **Ctrl+`** (Cmd+` is the macOS window switcher). The - shortcut is a global key handler, so it toggles even while the terminal - has the keyboard. + with it) and the shortcuts below. Opening it with no terminal yet (once + every machine's list has arrived) starts one, as New terminal does. +- **Shortcuts** (`terminal_shortcuts.dart`, handled by the surface as a + `FocusManager` early key handler, so they work wherever focus is, including + inside the terminal and in the chat composer, and neither receives the key): + - **Alt+T** (Option+T), **Ctrl+T**, **Cmd+T** (Meta+T) and **Ctrl+`** + show or hide the terminal in the selected mode; on a narrow window they + open and close the full-screen page. Only the one modifier counts + (Ctrl+Shift+T, Ctrl+Alt+T pass through); Option+T, which types † on a + Mac, is also matched by key position. Cmd+` stays the macOS window + switcher. **The shell's own Ctrl+T (transpose-chars) no longer reaches + it** while this binding is on. + - **Ctrl+Tab / Ctrl+Shift+Tab**, while the terminal is shown (panel, + window or narrow page), select the next / previous terminal tab, wrapping, + and focus it. This deliberately overrides the chat's Ctrl+Tab pane + cycling while the terminal is open (`TerminalActions.claimsTabKeys`, + checked by `chat_screen_workspace.dart`); hidden, Ctrl+Tab cycles chat + panes as before. + - **Browsers** keep some of these: a normal Chrome/Safari/Firefox tab + never receives Cmd+T (new tab) or Ctrl+Tab / Ctrl+Shift+Tab (switch + tabs), and outside macOS Ctrl+T is new tab too. The web build therefore + lists only Ctrl+T (macOS), Alt/Option+T and Ctrl+` in the button tooltip + and the ⋮ menu (`TerminalShortcutLabels`), and no tab keys; the handlers + stay on, so an installed app window that does deliver a key still works. + Native macOS/Linux/Android-with-keyboard builds get all of them and list + them. +- **Focus:** whenever the terminal shows (shortcut, button, a reload that + restores it, a mode change, un-minimising, a tab change by pointer, key or + New terminal) the selected tab's emulator gets the keyboard: the body is a + `FocusScope` the surface focuses after the frame, and the emulator + autofocuses inside it (`terminal_focus.dart`). Hiding gives the keyboard + back at once to what had it before opening (the composer, a field), if the + terminal still has it; the narrow page's route restores focus itself. +- **Motion:** `Motion.standard` (200 ms, `Motion.curve` in, ease-in-cubic + out), played on the app clock the animation-speed setting dilates, and zero + under reduced motion (`Motion.of`). The bottom panel keeps its full height + and slides up from the bottom edge with a slight fade (opacity 0.4 to 1) + while the app above shrinks with it frame by frame (no jump, and the + emulator is not resized during the motion); the floating window scales + from 92 % and fades in its own place. During the hide motion the terminal + stays mounted but takes no pointer or focus (`terminal_stage.dart`). - **Bottom panel:** resized by dragging its top edge (the app's `AdaptiveResizeGrip`; arrow keys too, slider semantics); its height is remembered. The panel always leaves the app at least 160 px. @@ -40,7 +78,8 @@ keeps running when the panel is hidden, the app navigates or reloads, and from its retained output. A dropped connection resumes after the last byte held; a restarted server (new stream) is read again from its start. - **Keyboard:** a focused terminal gets every key (Ctrl-C, Esc, Tab, arrows, - Ctrl-letters); paste is Cmd-V (Apple) or Ctrl-V/Ctrl-Shift-V. Clicking + Ctrl-letters) except the shortcuts above (Ctrl+T, Alt+T, Cmd+T, Ctrl+`, + and Ctrl+Tab while shown); paste is Cmd-V (Apple) or Ctrl-V/Ctrl-Shift-V. Clicking elsewhere moves focus away normally. - No terminal request is sent until the terminal is first shown (or a terminal is opened): each connection sends one request at a time, so the @@ -129,14 +168,15 @@ data?, after?}`. `internal/server/terminal_{manager,supervise,process,tmux,clients,title,cwd,handlers}.go`, `websocket.go`; tests `terminal_ws_test.go`, `terminal_restart_test.go`, `internal/pipeline/terminals_test.go`; `docs/cli.md`. -- App: `lib/features/terminal/` (`terminal_{info,stream,tab,hub,machines,layout,scope,surface,panel,float,page,body,tab_strip,menu,toggle_button,open_action}.dart`), +- App: `lib/features/terminal/` (`terminal_{info,stream,tab,hub,listing,machines,layout,scope,surface,stage,focus,shortcuts,panel,float,float_frame,page,body,tab_strip,menu,toggle_button,open_action}.dart`), `lib/application/app_terminals.dart`, `pipelines_app.dart`, `bootstrap.dart`, `lib/shell/adaptive_shell.dart` (`barActions`), `lib/features/settings/settings_terminal_section.dart` (+ screen/topic pages), `lib/features/chat/conversation/chat_thread_view.dart` (Open in terminal), `lib/features/chat/files/files_panel.dart` (folder action), `lib/features/chat/shell/chat_shell_terminals.dart` (`ChatShellInputPipe` - made public). Tests `test/features/terminal/`. Probe fixture + made public), `lib/features/chat/chat_screen_workspace.dart` (Ctrl+Tab + yields to a shown terminal). Tests `test/features/terminal/`. Probe fixture `tool/perf/terminal_fixture.dart` (`?terminals=1`, `?terminal=panel|float`). ## Verification @@ -206,3 +246,48 @@ Go 1.x / Flutter 3.44.6, macOS host, tmux 3.7c (/opt/homebrew/bin/tmux). input lines logged: 0 KEEP in log: 0 ``` + +### Toggle shortcuts, focus and motion (2026-11-09) + +- Fixed on the way: the previous Ctrl+` handler was a `HardwareKeyboard` + handler, which does not stop the focus tree, so a focused terminal also + received the backquote. The shortcuts are now `FocusManager` early key + handlers; a widget test asserts no `terminal_input` for each chord and no + input from a held chord's repeats. +- `tool/memwatch/full.sh test/features/terminal`: `PASS: 38 passed` + (each of Alt+T, Ctrl+T, Cmd+T, Ctrl+` toggling the panel and the window + from a text field and from inside the terminal; Option+T (†) by key + position; Shift / second modifier ignored; held chord toggles once; focus + on show, on reload restore and on pointer tab change; focus back to the + field on hide; Ctrl+Tab / Ctrl+Shift+Tab cycling and wrapping only while + shown; auto-start of a terminal when none; narrow page open/close/focus/ + Ctrl+Tab; panel slide with the app shrinking mid-way, window scale+fade, + hide keeps it mounted, animation-speed dilation, reduced motion instant; + labels per platform; with `ChatScreen`: Ctrl+Tab cycles panes when hidden, + terminal tabs when shown, and the composer gets the keyboard back). +- `tool/memwatch/full.sh test/shell`: `PASS: 128 passed`. + `tool/memwatch/full.sh test/features/chat`: `PASS: 1144 passed, 0 failed`. +- `tool/analyze.sh`: clean. `flutter build web`: built. + `FLUTTER_XCODE_ARCHS=arm64 flutter build macos`: built (35.1MB). +- Real Chrome (`tool/capture`, probe `?terminals=1`, 1280x820; the kit's + film step gained `film=press:` to film a key press), inspected: + `/tmp/terminal-toggle/panel/02-panel-show-sheet.png`, + `/tmp/terminal-toggle/panel-warm/01-panel-show-warm-sheet.png` (269 ms + frame: panel half way up, app above shrunk), `panel/07-panel-hide-sheet.png` + (183 ms frame mid-slide), `panel/03-focused-after-alt-t.png`, + `panel/04-typed.png` (`pwd` typed straight after Alt+T), + `panel/05-ctrl-tab.png`, `panel/06-ctrl-shift-tab.png`; + `/tmp/terminal-toggle/float/02-float-hide-sheet.png` (178 ms, scaled and + faded), `float/04-float-show-sheet.png` (164 ms), `float/05-float-focused.png`, + `float/06-menu-shortcuts.png` (web on macOS lists "Show or hide: Ctrl+T, + Option+T, Ctrl+`", no tab keys); `/tmp/terminal-toggle/chat/0{1..4}-*.png` + (composer "draft ", Alt+T, `ls` typed in the terminal, Ctrl+Tab to `~`, + Alt+T, `ok` lands in the composer: "draft ok", no stray `t`/`†`). +- Not verified: CDP key events are delivered to the page directly, past the + browser's own shortcuts, so the captures cannot show which chords a real + browser keeps; the list above follows the browsers' documented reserved + shortcuts (Cmd+T, Ctrl+T outside macOS, Ctrl+Tab, Ctrl+Shift+Tab). OS-level + keys via `osascript`/System Events were not permitted (it waited on the + automation permission), so neither real Chrome nor the native macOS + build's Cmd+T was driven by real keystrokes; native behaviour is verified + by widget tests only. diff --git a/app/test/features/terminal/terminal_shortcuts_test.dart b/app/test/features/terminal/terminal_shortcuts_test.dart index 0088c534..f703ac73 100644 --- a/app/test/features/terminal/terminal_shortcuts_test.dart +++ b/app/test/features/terminal/terminal_shortcuts_test.dart @@ -65,6 +65,33 @@ void main() { } } + test('Option+T on a Mac, which types †, toggles by key position', () { + const event = KeyDownEvent( + physicalKey: PhysicalKeyboardKey.keyT, + logicalKey: LogicalKeyboardKey(0x2020), + character: '†', + timeStamp: Duration.zero, + ); + expect(terminalToggleShortcut(event, _AltHeld()), isTrue); + }); + + testWidgets('holding the chord toggles once and types nothing', ( + tester, + ) async { + await pumpTerminalApp(tester, hub: hub, layout: layout); + await tester.sendKeyDownEvent(LogicalKeyboardKey.altLeft); + await tester.sendKeyDownEvent(LogicalKeyboardKey.keyT); + await tester.pumpAndSettle(); + expect(terminalFocused(key('term_a')), isTrue); + await tester.sendKeyRepeatEvent(LogicalKeyboardKey.keyT); + await tester.sendKeyRepeatEvent(LogicalKeyboardKey.keyT); + await tester.sendKeyUpEvent(LogicalKeyboardKey.keyT); + await tester.sendKeyUpEvent(LogicalKeyboardKey.altLeft); + await tester.pumpAndSettle(); + expect(layout.visible, isTrue); + expect(mac.bodies('terminal_input'), isEmpty); + }); + testWidgets('Shift or a second modifier leaves T alone', (tester) async { await pumpTerminalApp(tester, hub: hub, layout: layout); for (final modifiers in [ @@ -213,3 +240,15 @@ void main() { expect(windowsWeb.button, 'Terminal (Alt+T)'); }); } + +/// A keyboard on which only Alt (Option) is held. +class _AltHeld extends HardwareKeyboard { + @override + bool get isAltPressed => true; + @override + bool get isControlPressed => false; + @override + bool get isMetaPressed => false; + @override + bool get isShiftPressed => false; +} diff --git a/app/tool/capture/README.md b/app/tool/capture/README.md index 7610ad78..fba6e78d 100644 --- a/app/tool/capture/README.md +++ b/app/tool/capture/README.md @@ -55,7 +55,7 @@ In JSON, a step can also set `wait` (ms), `timeout`, `name`, `ms` and `frames`. | `drag=>dx,dy` | press on the target, move by dx,dy in `steps` (12) moves `gap` (16) ms apart, release (JSON `dx`, `dy`, `steps`, `gap`; `hold: true` keeps the button down to capture mid-drag) | | `size=WxH` | resize without reloading | | `labels=name` | write the visible semantics labels, keys and rects to JSON | -| `film=` | screencast a click for `--film-ms` (900) and write the frames plus a contact sheet | +| `film=` | screencast a click for `--film-ms` (900) and write the frames plus a contact sheet; `film=press:Alt+t` films a key chord (as `press=`) instead | | `wait=ms` | sleep | | `files=a.ttf[,b.ttf]` | answer the next file chooser the page opens with these files (paths relative to the working directory); put it before the click that opens the picker | | `swipe=>dx,dy` | one-finger touch swipe (needs `--touch true`, which emulates a touch screen once semantics is on) | diff --git a/app/tool/capture/capture.mjs b/app/tool/capture/capture.mjs index f0039439..2955dccc 100644 --- a/app/tool/capture/capture.mjs +++ b/app/tool/capture/capture.mjs @@ -175,7 +175,8 @@ try { case 'tabs': await save(file(value || 'tabs', 'json'), JSON.stringify(await browser.targets(), null, 2)); break; case 'labels': await save(file(value || 'labels', 'json'), JSON.stringify(await page.labels(), null, 2)); break; case 'film': { - const name = step.name ?? `film-${describe(parseTarget(value)).replace(/\W+/g, '-').replace(/^-|-$/g, '')}`; + const what = String(value).startsWith('press:') ? String(value) : describe(parseTarget(value)); + const name = step.name ?? `film-${what.replace(/\W+/g, '-').replace(/^-|-$/g, '')}`; const frames = await page.film(value, Number(step.ms ?? opts['film-ms'])); const dir = join(out, name.replace(/[^\w.-]+/g, '_')); await mkdir(dir, { recursive: true }); diff --git a/app/tool/capture/page.mjs b/app/tool/capture/page.mjs index 6dcc692e..f510ae5a 100644 --- a/app/tool/capture/page.mjs +++ b/app/tool/capture/page.mjs @@ -207,7 +207,9 @@ export function flutterPage(browser, log, { touch = false } = {}) { // viewport before another screencast, otherwise Chrome can crop frames. await send('Page.bringToFront'); await resize(viewport.width, viewport.height); - const point = await locate(target); + // `press:Alt+t` films a key chord instead of a click. + const chord = typeof target === 'string' && target.startsWith('press:') ? target.slice(6) : null; + const point = chord ? null : await locate(target); const frames = []; const ack = (p) => { frames.push({ data: p.data, t: p.metadata.timestamp }); @@ -217,7 +219,8 @@ export function flutterPage(browser, log, { touch = false } = {}) { await send('Page.startScreencast', { format: 'png', everyNthFrame: 1, maxWidth: viewport.width, maxHeight: viewport.height }); await delay(300); const clickAt = Date.now() / 1000; - await tap(point); + if (chord) await this.press(chord); + else await tap(point); await delay(ms); await send('Page.stopScreencast'); await delay(100);