Describe floating chats on the window system in the notes
This commit is contained in:
+66
-120
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user