e4f3ebdcab
Remove the separate minimise control and make the title-bar X hide windows while preserving their state and reachability. Update window behavior documentation and focused tests for chat, terminal, and window layering.
104 lines
6.3 KiB
Markdown
104 lines
6.3 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**: 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
|
|
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-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`,
|
|
`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).
|