From 7dc054763b12fc607673a462c17638f8fa41835c Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Thu, 12 Nov 2026 01:04:09 +0000 Subject: [PATCH] Cycle floating chats with Ctrl+Tab Route Ctrl+Tab and Ctrl+Shift+Tab between visible floating chat windows while preserving tiled-pane and terminal tab behavior. Add regression coverage and document the shortcut semantics. --- .../features/chat/chat_screen_workspace.dart | 5 +- app/lib/features/chat/screen.dart | 1 + .../chat/windows/chat_window_tabs.dart | 39 ++++++ .../features/chat/windows/chat_windows.dart | 40 +++++- app/notes/chat-floating-pane.md | 25 ++++ .../chat/chat_floating_pane_test.dart | 117 ++++++++++++++++++ 6 files changed, 224 insertions(+), 3 deletions(-) create mode 100644 app/lib/features/chat/windows/chat_window_tabs.dart diff --git a/app/lib/features/chat/chat_screen_workspace.dart b/app/lib/features/chat/chat_screen_workspace.dart index 5f0d6cc2..b5c2bdb4 100644 --- a/app/lib/features/chat/chat_screen_workspace.dart +++ b/app/lib/features/chat/chat_screen_workspace.dart @@ -147,11 +147,14 @@ mixin _ChatScreenWorkspace on State { /// focus. Over a single pane it swaps in the chat shown before this one /// instead, and back again (see [_toggleRecentChat]). Command+Tab stays /// with the operating system's application switcher. While the app's - /// terminal is shown, Ctrl+Tab moves between its tabs instead. + /// terminal is shown, Ctrl+Tab moves between its tabs instead. While a + /// floating chat window holds the keyboard, Ctrl+Tab cycles those windows + /// (see [ChatWindows]). bool _cycleChatKey(KeyEvent event) { final keyboard = HardwareKeyboard.instance; if (event is! KeyDownEvent || TerminalScope.peek(context)?.claimsTabKeys == true || + keyboardWindow()?.entry.kind == chatWindowKind || event.logicalKey != LogicalKeyboardKey.tab || !keyboard.isControlPressed || keyboard.isMetaPressed || diff --git a/app/lib/features/chat/screen.dart b/app/lib/features/chat/screen.dart index 77b66fd5..d3544afa 100644 --- a/app/lib/features/chat/screen.dart +++ b/app/lib/features/chat/screen.dart @@ -1,5 +1,6 @@ import 'chat_pane_content.dart'; import 'chat_runtime.dart'; +import 'windows/chat_window_tabs.dart'; import 'windows/chat_windows.dart'; import 'workspace/federated_workspace_store.dart'; import '../../core/servers/chat/federated_chat_gateway.dart'; diff --git a/app/lib/features/chat/windows/chat_window_tabs.dart b/app/lib/features/chat/windows/chat_window_tabs.dart new file mode 100644 index 00000000..4bcc9763 --- /dev/null +++ b/app/lib/features/chat/windows/chat_window_tabs.dart @@ -0,0 +1,39 @@ +import 'package:flutter/services.dart'; +import 'package:flutter/widgets.dart'; + +import '../../../shell/windows/window_entry.dart'; +import '../../../shell/windows/window_scope.dart'; + +/// The step Ctrl+Tab (1) or Ctrl+Shift+Tab (-1) moves between floating chat +/// windows, or null for any other key. Command+Tab stays with the system. +int? chatWindowTabStep(KeyEvent event, HardwareKeyboard keyboard) { + if (event is! KeyDownEvent || + event.logicalKey != LogicalKeyboardKey.tab || + !keyboard.isControlPressed || + keyboard.isMetaPressed || + keyboard.isAltPressed) { + return null; + } + return keyboard.isShiftPressed ? -1 : 1; +} + +/// The window [step] away from the window [currentId] in [visible] (bottom +/// to top), wrapping around. Null when [currentId] is not listed or there is +/// no other window to move to. +WindowEntry? chatWindowAfter( + List visible, + String currentId, + int step, +) { + final at = visible.indexWhere((w) => w.id == currentId); + if (at < 0 || visible.length < 2) return null; + return visible[(at + step) % visible.length]; +} + +/// The floating window whose content holds the keyboard, if one does. Read +/// from the focused node's ancestors, so it needs no reference to the host. +WindowScope? keyboardWindow() { + final context = FocusManager.instance.primaryFocus?.context; + if (context == null) return null; + return context.findAncestorWidgetOfExactType(); +} diff --git a/app/lib/features/chat/windows/chat_windows.dart b/app/lib/features/chat/windows/chat_windows.dart index 247dd879..c2c7fb59 100644 --- a/app/lib/features/chat/windows/chat_windows.dart +++ b/app/lib/features/chat/windows/chat_windows.dart @@ -8,11 +8,13 @@ import '../../../shell/list_detail_policy.dart'; import '../../../shell/windows/window_entry.dart'; import '../../../shell/windows/window_kind.dart'; import '../../../shell/windows/window_manager.dart'; +import '../../terminal/terminal_scope.dart'; import '../chat_runtime.dart'; import '../domain/chat_commands.dart'; import '../workspace/chat_float_shortcut.dart'; import '../workspace/chat_float_store.dart'; import 'chat_window_content.dart'; +import 'chat_window_tabs.dart'; const chatWindowKind = 'chat'; @@ -79,7 +81,9 @@ class ChatWindows { if (_started) return; _started = true; manager.kinds.register(kind); - FocusManager.instance.addEarlyKeyEventHandler(_key); + FocusManager.instance + ..addEarlyKeyEventHandler(_key) + ..addEarlyKeyEventHandler(_tabKey); runtime.addSessionReplacedListener(_replacedElsewhere); runtime.sessions.addListener(_rowsChanged); manager.addListener(_rowsChanged); @@ -89,7 +93,9 @@ class ChatWindows { void dispose() { if (!_started) return; _started = false; - FocusManager.instance.removeEarlyKeyEventHandler(_key); + FocusManager.instance + ..removeEarlyKeyEventHandler(_key) + ..removeEarlyKeyEventHandler(_tabKey); runtime.removeSessionReplacedListener(_replacedElsewhere); runtime.sessions.removeListener(_rowsChanged); manager.removeListener(_rowsChanged); @@ -224,6 +230,36 @@ class ChatWindows { if (event is KeyDownEvent) manager.toggleOrRaiseGroup(chatWindowKind); return KeyEventResult.handled; } + + /// Ctrl+Tab and Ctrl+Shift+Tab while a floating chat window holds the + /// keyboard: the next (previous) visible chat window, in stacking order and + /// wrapping, comes to the top. The window host then gives it the keyboard, + /// its composer. Left alone when another window or the tiling has the + /// keyboard, when the terminal claims tab keys, or with one window. + KeyEventResult _tabKey(KeyEvent event) { + final step = chatWindowTabStep(event, HardwareKeyboard.instance); + if (step == null || !_wide) return KeyEventResult.ignored; + final scope = keyboardWindow(); + if (scope == null || + scope.entry.kind != chatWindowKind || + _terminalClaimsTabs()) { + return KeyEventResult.ignored; + } + final target = chatWindowAfter( + windows.where(manager.isVisible).toList(), + scope.entry.id, + step, + ); + if (target == null) return KeyEventResult.ignored; + manager.raise(target.id); + return KeyEventResult.handled; + } + + bool _terminalClaimsTabs() { + final context = FocusManager.instance.primaryFocus?.context; + return context != null && + TerminalScope.peek(context)?.claimsTabKeys == true; + } } class _Never implements Listenable { diff --git a/app/notes/chat-floating-pane.md b/app/notes/chat-floating-pane.md index 54407bbc..e17dcb38 100644 --- a/app/notes/chat-floating-pane.md +++ b/app/notes/chat-floating-pane.md @@ -29,6 +29,14 @@ every destination and come back at app start without Chat being opened. terminal). On macOS Ctrl+Y in a terminal always goes to the shell. - **Focus**: a window that shows or comes to the top puts the keyboard in its composer; hiding the last window gives it back to what had it. +- **Cycle**: while a floating chat window's content holds the keyboard (a + composer, a Files page inside it), Ctrl+Tab brings the next visible chat + window to the top and Ctrl+Shift+Tab the previous one, wrapping round. The + order is the stacking order, bottom to top, and the window's composer takes + the keyboard. Command+Tab stays with the system. With the tiling focused, + Ctrl+Tab still cycles its panes; while the terminal claims tab keys (shown) + it switches terminal tabs. Alt+` (`windowCycleShortcut`) still cycles every + kind of window, not only chats. - **Popups**: sheets, dialogs, menus and tooltips opened from a floating chat are above every window. Files opens as a page inside the window, and a file opened from it stays in the window. Because the window's own title bar names @@ -60,6 +68,23 @@ every destination and come back at app start without Chat being opened. ## Checks +- Focused, 2026-11-12, `tool/memwatch/full.sh` with + `test/features/chat/chat_floating_pane_test.dart` and + `test/features/terminal/terminal_chat_tab_test.dart`: 16 passed, 0 failed. + New in the first: Ctrl+Tab and Ctrl+Shift+Tab over three floating chats + (order, wrap, composer focus, Command+Tab ignored); with the tiling focused + Ctrl+Tab moves the active pane and leaves the windows alone, and with one + window focused it does nothing; a terminal that claims tab keys keeps + Ctrl+Tab over a focused chat window. +- `tool/analyze.sh` on the changed paths: clean. +- Affected states: two or more floating chats; one floating chat; tiling + focused; a window focused with the terminal shown (claimed); Command+Tab. +- Not covered: the terminal's own tab switching (the test app has no terminal + surface), real browser or device keys, and captures (ui-review's). +- Observed, not changed: in the widget harness, floating from a pane's More + menu does not leave the keyboard in the new window's composer (the window + takes it); the chord and Ctrl+Tab do. + - `test/features/chat/chat_floating_pane_test.dart` (the Chat screen with the window host), `test/features/chat/windows/chat_windows_test.dart`, `test/features/chat/workspace/chat_workspace_float_test.dart`, diff --git a/app/test/features/chat/chat_floating_pane_test.dart b/app/test/features/chat/chat_floating_pane_test.dart index d5b13fea..9ae25bda 100644 --- a/app/test/features/chat/chat_floating_pane_test.dart +++ b/app/test/features/chat/chat_floating_pane_test.dart @@ -11,6 +11,7 @@ import 'package:pipelines_app/features/chat/windows/chat_windows.dart'; import 'package:pipelines_app/features/chat/workspace/chat_float_store.dart'; import 'package:pipelines_app/features/chat/workspace/chat_workspace.dart'; import 'package:pipelines_app/features/chat/workspace/chat_workspace_store.dart'; +import 'package:pipelines_app/features/terminal/terminal_scope.dart'; import 'package:pipelines_app/shell/windows/window_frame.dart'; import 'package:pipelines_app/shell/windows/window_host.dart'; import 'package:pipelines_app/shell/windows/window_kind.dart'; @@ -48,6 +49,16 @@ class _Store implements WindowStore { } } +class _ClaimingTerminal implements TerminalActions { + const _ClaimingTerminal(); + @override + void toggle() {} + @override + bool get claimsTabKeys => true; + @override + Future openAt(ApiGateway gateway, String cwd) async => null; +} + class _TerminalKind extends WindowKind { @override String get key => 'terminal'; @@ -105,6 +116,7 @@ class _App { WidgetTester tester, { Size size = const Size(1800, 1000), bool terminalSurface = false, + bool terminalClaimsTabs = false, }) async { tester.view.physicalSize = size; tester.view.devicePixelRatio = 1; @@ -124,6 +136,13 @@ class _App { ); await tester.pumpWidget( MaterialApp( + // A terminal that shows its tabs: it claims Ctrl+Tab. + builder: terminalClaimsTabs + ? (context, child) => TerminalScope( + actions: const _ClaimingTerminal(), + child: child!, + ) + : null, home: Scaffold( body: Stack( fit: StackFit.expand, @@ -218,6 +237,19 @@ Future _chord(WidgetTester tester) async { await tester.pumpAndSettle(); } +/// Ctrl+Tab, or Ctrl+Shift+Tab with [shift]. +Future _tab(WidgetTester tester, {bool shift = false}) async { + await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); + if (shift) await tester.sendKeyDownEvent(LogicalKeyboardKey.shiftLeft); + await tester.sendKeyEvent(LogicalKeyboardKey.tab); + if (shift) await tester.sendKeyUpEvent(LogicalKeyboardKey.shiftLeft); + await tester.sendKeyUpEvent(LogicalKeyboardKey.controlLeft); + await tester.pumpAndSettle(); +} + +bool _composerFocused(WidgetTester tester, String id) => + tester.widget(_input(id)).focusNode.hasPrimaryFocus; + Future _controlChord(WidgetTester tester) async { await tester.sendKeyDownEvent(LogicalKeyboardKey.controlLeft); await tester.sendKeyEvent(LogicalKeyboardKey.keyY); @@ -452,6 +484,91 @@ void main() { await app.stop(tester); }); + testWidgets('Ctrl+Tab and Ctrl+Shift+Tab cycle the floating chat windows, ' + 'each composer taking the keyboard', (tester) async { + await _saved('a', 'b', 'c'); + final app = _App(_Store()); + await app.start(tester); + await _menu(tester, 'b', 'Float (Alt+Y)'); + await _menu(tester, 'c', 'Float (Alt+Y)'); + await _menu(tester, 'a', 'Float (Alt+Y)'); + expect(app.floating, ['b', 'c', 'a']); + + // Command+Tab belongs to the system. + await tester.sendKeyDownEvent(LogicalKeyboardKey.metaLeft); + await tester.sendKeyEvent(LogicalKeyboardKey.tab); + await tester.sendKeyUpEvent(LogicalKeyboardKey.metaLeft); + await tester.pumpAndSettle(); + expect(app.floating, ['b', 'c', 'a']); + + await _tab(tester); + expect(app.floating, ['c', 'a', 'b']); + expect(_composerFocused(tester, 'b'), isTrue); + // Past the top, the bottom window comes up again. + await _tab(tester); + expect(app.floating, ['a', 'b', 'c']); + expect(_composerFocused(tester, 'c'), isTrue); + await _tab(tester, shift: true); + expect(app.floating, ['a', 'c', 'b']); + expect(_composerFocused(tester, 'b'), isTrue); + await _tab(tester, shift: true); + expect(app.floating, ['a', 'b', 'c']); + expect(_composerFocused(tester, 'c'), isTrue); + expect(tester.takeException(), isNull); + await app.stop(tester); + }); + + testWidgets('with the tiling focused Ctrl+Tab cycles its panes and leaves ' + 'the windows alone', (tester) async { + await _saved('a', 'b', 'c'); + final app = _App(_Store()); + await app.start(tester); + await _menu(tester, 'c', 'Float (Alt+Y)'); + expect(app.floating, ['c']); + final controller = _workspace(tester); + + await tester.tapAt(tester.getCenter(_input('a'))); + await tester.pump(); + expect(controller.activePane?.sessionId, 'a'); + await _tab(tester); + expect(controller.activePane?.sessionId, 'b'); + expect(_composerFocused(tester, 'b'), isTrue); + expect(app.floating, ['c']); + + // With a window focused, the panes stay where they are; a single window + // has nothing to cycle to. + await tester.tapAt(tester.getCenter(_input('c'))); + await tester.pump(); + expect(_composerFocused(tester, 'c'), isTrue); + await _tab(tester); + expect(controller.activePane?.sessionId, 'b'); + expect(app.floating, ['c']); + expect(tester.takeException(), isNull); + await app.stop(tester); + }); + + testWidgets('a terminal that claims tab keys keeps Ctrl+Tab over a focused ' + 'floating chat', (tester) async { + await _saved('a', 'b', 'c'); + final app = _App(_Store()); + await app.start(tester, terminalClaimsTabs: true); + await _menu(tester, 'b', 'Float (Alt+Y)'); + await _menu(tester, 'c', 'Float (Alt+Y)'); + expect(app.floating, ['b', 'c']); + await tester.tapAt(tester.getCenter(_input('c'))); + await tester.pump(); + expect(_composerFocused(tester, 'c'), isTrue); + + // The terminal's tabs get the key (its own handler is not in this app); + // neither the windows nor the panes move. + await _tab(tester); + expect(app.floating, ['b', 'c']); + expect(_composerFocused(tester, 'c'), isTrue); + expect(_workspace(tester).activePane?.sessionId, 'a'); + expect(tester.takeException(), isNull); + await app.stop(tester); + }); + testWidgets('a floating chat types, runs its tickers, hides and shows over ' 'another destination', (tester) async { await _saved('a', 'b');