Files
pipelines/app/notes/chat-floating-pane.md
T
alan b4d67d6ba8 Cycle Ctrl-Tab through available chats
When a tiled workspace has one chat pane, navigate the sidebar chat order while preserving pane state and composer focus. Keep pane and floating-window cycling behavior for their existing layouts, and update shortcut documentation and coverage.
2026-11-13 12:23:52 +00:00

132 lines
8.1 KiB
Markdown

# Floating chats
On a wide layout a chat can leave the split tiling and float in a window over
the app. The windows belong to the shell's window system
(`notes/floating-windows.md`), not to the Chat destination: they show over
every destination and come back at app start without Chat being opened.
## Behaviour
- **Float**: a tiled pane's More menu offers `Float (Alt+Y)` (`Option+Y` on
Apple platforms), the last tiled chat too; floating it leaves the tiling
empty and returns to the list. A chat list row's More menu offers the same
Float: a tiled chat leaves the tiling, a chat with a window shows it, any
other chat opens in a new window. Any number of chats can float. A new window opens where that
chat's window last was, else at the default frame stepped 32 px per chat
window already open.
- **Window**: drag the title bar to move, the lower right corner to resize,
double click the title to maximise. The title bar has Dock, Maximise and
the X.
- **Dock** puts the chat back into the tiling, right of the active pane. When
the Chat destination is not built it opens the chat there instead.
- **X** (tooltip and semantics: Minimise) hides that window, keeping its state;
it stays listed in the Windows menu and the chord brings it back. It never
closes the window, the chat or the tiling: nothing returns to the tiling.
The chat itself is not closed on the server.
- **Chord**: Alt+Y, Ctrl+Y, and Cmd+Y on Apple platforms (`chatFloatShortcut`).
With chat windows open it hides or shows all of them. With none it floats the
active tiled pane, when that pane can float and Chat has the keyboard;
otherwise the key is left alone (so Ctrl+Y stays the shell's yank in a
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**: Ctrl+Tab and Ctrl+Shift+Tab move between the chats the user can
see, and never bring up one that is not shown.
- **While any chat window is shown** (not minimised, its group shown), the
keys cycle those windows only, from wherever the keyboard is in Chat: a
window's composer, a Files page inside it, or the tiling (the chat list
included). From a window, the next (previous) shown window in open order
comes to the top, wrapping round. From the tiling, Ctrl+Tab takes the
top-most shown window to the top first. Either way the window's composer
takes the keyboard. Open order is the order the windows were opened (a
restored window keeps its saved place), so a raise does not change the
cycle; the stacking order does change on a raise.
- **With no chat window focused**, Ctrl+Tab cycles the tiled panes and the
keys focus the chosen pane's composer. With exactly one tiled pane it
cycles all open chats in sidebar order, replacing that pane while keeping
its transcript and draft; closed, hidden-on-this-device and floating
chats are skipped. With two or more panes it cycles the panes only.
- Command+Tab stays with the system. While the terminal claims tab keys
(shown) Ctrl+Tab switches terminal tabs. A keyboard held by another window
(a run, terminal) is left to that window. 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
the chat, the More menu has `Chat details`.
- **Layout inside a window**: the chat is laid out for the window's size, so a
narrow window gets the compact action bar.
- **Narrow layouts**: no Float, the chord passes through, and chat windows are
hidden (kept, with their state) until the app is wide again.
## How
- `ChatRuntime` (`features/chat/chat_runtime.dart`), one per server scope, kept
by `PipelinesApp`: the session list controller, opened rows, accepted models,
transcript positions and caches, composer focus requests.
- `buildChatPaneContent` (`chat_pane_content.dart`) builds a conversation with
its scopes, keyed by `ChatRuntime.viewKey`. The tiling and the chat window
kind both use it, so Float and Dock move the same live view (transcript,
scroll, draft, running turn) between them in one frame.
- `ChatWindows` (`features/chat/windows/`): the `chat` `WindowKind`, the chord,
Dock, and what `/new` and `/close` do to a chat in a window. It reads the
session list for its windows' rows when the Chat destination is not built.
- The workspace controller keeps no floating chats. `detach` takes a pane out,
`dock` puts a chat back, and `showOutside` lets it show a chat's window
instead of opening that chat a second time. A chat is drawn once: if the
tiling holds a chat that also has a window, the window closes.
- **Saved state**: chat windows are entries of `pipelines.windows.v1`, carrying
their server key. The older `pipelines.next.chatFloat.v1` record (versions 1
and 2) is read once at start and turned into windows.
## Checks
- Focused, 2026-11-13, `tool/memwatch/full.sh` over
`test/features/chat/chat_floating_pane_test.dart`,
`test/features/chat/chat_keyboard_focus_test.dart`,
`test/features/chat/chat_control_tab_test.dart`,
`test/features/chat/windows/chat_windows_test.dart`,
`test/features/terminal/terminal_chat_tab_test.dart`, the keyboard
shortcuts registry test and related Ctrl+Tab users: 70 passed, 0 failed.
This included `tool/memwatch/full.sh` over
`test/shell/destination_shortcuts_test.dart`,
`test/shell/tab_history_back_test.dart`, `test/shell/search_escape_test.dart`
and `test/features/chat/shell/chat_shell_terminal_test.dart`: 26 passed,
0 failed.
- Floating-window Ctrl+Tab and Ctrl+Shift+Tab over three floating chats cycle
in open order, not stacking order (order, wrap, composer focus, Command+Tab
ignored). With the tiling focused, a single tiled pane cycles the open,
device-visible sidebar chats and skips closed, hidden and floating chats;
multiple tiled panes cycle panes. A terminal that claims tab keys keeps
Ctrl+Tab over a focused chat window.
- Changed: a single tiled pane now cycles the open, device-visible sidebar
chats in list order, skips closed, hidden-on-this-device and floating chats,
wraps in both directions, and focuses the replacement composer. Multiple
panes and focused floating windows retain their existing cycles.
- `tool/analyze.sh` on `lib/features/chat` and the three chat test files:
clean.
- Affected states: a single tiled pane with open chats; shown or minimised
floating chats; two or more tiled panes; a focused floating window; 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`,
`chat_float_shortcut_test.dart`, `test/features/chat/chat_runtime_test.dart`.
- Real app (capture kit, 2026-11-10/11, 1280x800 and 1920x1080, light and
dark), from a floating chat over Chat and over Runs: chat details, model
dialog, mode sheet, thinking menu, More menu, title-bar and control tooltips,
typing; Files page with its sort menu, row menu and tooltip, a file opened
inside the window; reload restoring the window over Runs without visiting
Chat; hide and show by chord, maximise, minimise, Dock; a live turn
animating over Runs; the Turn changes page, a diff opened from it and a shell
command's full-screen page, each inside the window; a question card.
- Not captured: paste of text or an image, a question-card dropdown (the
fixture's question has radio options), the image viewer, and the
text-selection menu (the kit has no right-click).