b4d67d6ba8
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.
132 lines
8.1 KiB
Markdown
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).
|