Describe floating chats on the window system in the notes

This commit is contained in:
2026-11-10 21:43:37 +00:00
parent 16afda3634
commit 9d533fcad9
2 changed files with 74 additions and 124 deletions
+66 -120
View File
@@ -1,129 +1,75 @@
# Floating chat pane
# Floating chats
On a wide layout chats can leave the split tiling and float in windows over
the app, like the floating terminal. Ctrl+Y (Cmd+Y on macOS) shows or hides
all of them together, on every destination.
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 (Ctrl+Y)` (`Cmd+Y` on Apple
platforms) when another chat stays in the tiling. The last tiled chat cannot
float, because the tiling would be empty. Any number of chats can float;
floating one shows every floating chat. A new window opens at the default
frame stepped 32 px down and right per window already floating.
- **Show / hide**: the chord, a window's X and the menu's `Hide floating chats`
show or hide all floating windows at once. Each window keeps its own frame,
so they come back exactly where they were.
- **Window**: you drag it by its title bar and resize it from the lower right
corner. The title bar has Dock and Hide buttons. The window keeps its frame
inside the app when the browser window resizes (`fitChatFloat`). Grow and fade
in, and shrink and fade out, use `Motion.standard` through `Motion.of`, so
reduced motion and the animation speed apply. Each window animates on its
own, so a chat floated while others show grows in alone.
- **Floating chat's menu**: Dock (back into the tiling, right of the active pane,
which it becomes; the others keep floating), `Hide floating chats (Ctrl+Y)`,
and Close pane (removes it from the workspace; no backend close). If the last
tiled pane closes, the oldest floating chat docks in its place.
- **Shortcut**: Ctrl+Y on every platform, and Cmd+Y on macOS and iOS. It is an
early key handler, so it works from a composer or the terminal; Y, Shift+Y and
Alt+Y still type. When no chat floats, Ctrl+Y floats the tiled pane that has
the keyboard. When no pane has the keyboard, or that pane cannot float, the
chord is left alone. So in the terminal Ctrl+Y stays the shell's yank until a
chat floats. After that, on Windows, Linux and web, Ctrl+Y toggles even from
the terminal (yank is unavailable there, as with Ctrl+T). On macOS, Ctrl+Y in
a `TypingSurface` (terminal) always goes to the shell, and Cmd+Y toggles.
- **Focus**: showing the chat focuses its composer. Hiding it gives the keyboard
back to whatever had it before (as `TerminalFocus` does), otherwise the
keyboard is unfocused.
- **Where it shows**: on a wide layout, over every destination (Runs,
Pipelines, Settings...), like the floating terminal. The windows move,
resize, type, hide and dock there as on Chat. On narrow or phone layouts the
menu item is absent and the chord passes through; floating chats stay
floating, unpainted, with their state, and reappear when the window is wide
again.
- **Other destinations (how)**: the shell hides a destination with
`FadeThroughStack` (muted tickers, no input, no focus). The windows already
paint and hit-test in the root overlay; the host also re-enables tickers
around each window (`TickerMode`) and parents each floating pane's
`FocusScope` on the shell's `FloatingFocusRoot`
(`ui/floating/floating_layer.dart`, above the destination stack), so a
hidden destination's `ExcludeFocus` does not take its keyboard. Before this,
leaving Chat started the hide animation on a muted ticker: the window stayed
painted but ignored input, so it could not be moved or closed.
- **Persistence**: `pipelines.next.chatFloat.v1` is stored device-locally and
scoped like the workspace layout. Record version 2 holds the floating panes
(id and session, oldest first, at most 12), whether they are shown, and a
frame per pane id. A docked pane keeps its frame, so floating it again
returns it to the same place; a closed pane's frame is dropped. Version 1
records (one pane, one frame) still load. It is restored after the workspace
layout. A saved float whose session is already open is dropped.
- **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.
## Design
## How
- `ChatWorkspaceController` keeps the floating panes outside the tree
(`chat_workspace_float.dart`, a `part` with the `ChatWorkspaceFloat`
extension: `floatingPanes`, `isFloating`, `dock(paneId)`, `restoreFloats`).
`panes` and `paneCount` stay tiled-only. A pane keeps its id through float,
hide and dock. Frames live in `ChatFloatFrames` (by pane id).
- `ChatWorkspace` gives each pane's content a `GlobalKey`. A floating chat is
that same keyed subtree, built by `ChatFloatHost` inside the workspace, so the
`ChatThreadView` State, draft, scroll and running turn move with it and are
not rebuilt. Its inherited context and focus tree stay in the workspace.
- `FloatingLayer` (`lib/ui/floating/`) paints a layer in the root overlay
through `OverlayPortal`. The chat window covers the whole app. The terminal's
floating window now uses the same layer, so the two share one z-order: the
last one pressed, focused or opened is on top. Without an overlay (bare
widget tests) the layer paints in place.
- New files: `chat_float_{host,window,binding,store,shortcut}.dart`,
`chat_workspace_float.dart`, `chat_screen_float.dart` and
`ui/floating/floating_layer.dart`. Existing files changed: workspace
controller hooks (open, split, close, replace, restore), the
`ChatWorkspace.floatFrame` parameter and keyed content, the pane controls and
`/close` and `/new` handling in `screen.dart`, the persistence wiring in
`chat_screen_workspace.dart`, and `terminal_stage.dart`.
## Not done
- The sidebar's "visible" highlight does not count floating chats.
- Floating windows need the Chat destination to have been built; the shell
builds every destination up front, so this holds today.
- Cmd+Y in a browser on macOS may be taken by the browser (History) before the
app sees it. Ctrl+Y works there.
- `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
### Multiple floats, every destination (2026-11-10)
- `tool/memwatch/full.sh 'test/features/chat/chat_floating_pane_test.dart test/features/chat/workspace test/ui/floating'`:
93 passed, 0 failed. `tool/analyze.sh lib test/features/chat`: clean.
- New tests: several floats toggled together by the chord and restored to
their frames, docking one keeps the other (`chat_floating_pane_test.dart`);
a float over another destination (a real `FadeThroughStack` page switch)
is hit-testable, drags, takes focus and typing, and hides by chord and its
X; controller, record v1/v2 and per-pane frame tests
(`chat_workspace_float_test.dart`).
- Fixed on the way: a drag read the frame from the last build, so several
pointer events in one frame lost movement; and a never-moved window's
cascaded frame shifted when another window docked (frames are now placed
when a chat floats).
### Single float (earlier)
- `tool/analyze.sh lib test/features/chat test/ui test/features/terminal`: clean
after the merge with main (pane moves, a410b9e5). In the merge, Float sits in
the pane menu right after the Move items.
- `tool/memwatch/full.sh 'test/features/chat test/features/terminal test/shell test/ui/floating'`:
1395 passed, 0 failed; peak 1936 MB; 592 s. New tests are
`test/features/chat/workspace/chat_workspace_float_test.dart` (controller,
record and binding), `chat_float_shortcut_test.dart` (chord, typing Y,
terminal and macOS, narrow), `test/features/chat/chat_floating_pane_test.dart`
(menu Float and Dock keep the `ChatThreadView` State and draft, reload,
narrow) and `test/ui/floating/floating_layer_test.dart` (z-order and click
pass-through).
- Real-Chrome captures used the fixture (`chats=3&rich=1&colors=1`) at
1280x800 and are in `/tmp/float-cap/c/`: the pane menu with Float, the
floating chat with a typed draft, the chat hidden by Control+y with focus back
in the tiled composer, two films of the chord, and the floating chat over the
terminal panel. Headless Chrome reports macOS, so the label reads `Cmd+Y` and
Control+y also toggles. Not captured: the chat floating over a floating
(rather than panel) terminal.
- `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).
+8 -4
View File
@@ -1,7 +1,7 @@
# Floating windows (window system core)
Plan: `docs/plans/floating-windows.md`. Phase 1 adds the shell-level window
system; no feature uses it yet (chats move in Phase 2, the terminal in Phase 3).
Plan: `docs/plans/floating-windows.md`. The shell-level window system hosts
floating chats (`notes/chat-floating-pane.md`); the terminal moves in Phase 3.
## Pieces (`lib/shell/windows/`)
@@ -31,8 +31,12 @@ system; no feature uses it yet (chats move in Phase 2, the terminal in Phase 3).
and never clipped to one.
- The window's navigator covers the whole host so popups anchored to a button
measure in app coordinates and tooltips paint outside the window; only the
content area takes input. So a `MenuAnchor` in window content needs
`useRootOverlay: true` (its panel may extend past the window).
content area takes input. So menus are `AppMenuAnchor`
(`ui/adaptive/app_menu_anchor.dart`), whose panel is in the root overlay; a
test rejects a bare `MenuAnchor`.
- A window takes the keyboard at the press, not after it, and never from a
popup that covers the app; its content is not the current surface
(`SurfaceVisibility`) while one does.
- Known limit: a tooltip of a window that is not on top can be covered by a
window above it where they overlap (tooltips paint in their own window's
overlay). Pressing a window raises it, so menus are not affected.