From 9d533fcad97748d6269f702cf8429ed2def03c6a Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 10 Nov 2026 21:43:37 +0000 Subject: [PATCH] Describe floating chats on the window system in the notes --- app/notes/chat-floating-pane.md | 186 ++++++++++++-------------------- app/notes/floating-windows.md | 12 ++- 2 files changed, 74 insertions(+), 124 deletions(-) diff --git a/app/notes/chat-floating-pane.md b/app/notes/chat-floating-pane.md index f74cb939..55fa714b 100644 --- a/app/notes/chat-floating-pane.md +++ b/app/notes/chat-floating-pane.md @@ -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). diff --git a/app/notes/floating-windows.md b/app/notes/floating-windows.md index c15a477d..954a7ea3 100644 --- a/app/notes/floating-windows.md +++ b/app/notes/floating-windows.md @@ -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.