Files
pipelines/app/notes/chat-floating-pane.md
T

76 lines
4.5 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) when another chat stays in the tiling; the last tiled chat
cannot float. 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, Minimise,
Maximise and Close.
- **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.
- **Minimise** hides that window; the chord brings it back.
- **Close (X)** closes the window and returns nothing 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.
- **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
- `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).