Files
pipelines/app/notes/chat-floating-pane.md
T
alan cdd54c113c Float several chats and keep them working on every tab
Floating chats were stuck on other destinations: the hidden Chat tab
muted the window's hide animation, so the window stayed painted but took
no input. The reveal now uses its own ticker, each floating pane's focus
scope hangs from a FloatingFocusRoot above the destination stack, and the
windows show over every destination like the terminal.

Any number of chats can float; the shortcut, a window's X and the menu
show or hide them together. Each pane keeps its own frame (also while
docked), saved in record version 2; version 1 records still load. Drags
read the live frame so fast pointer events no longer lose movement.
2026-11-10 15:26:38 +00:00

7.8 KiB

Floating chat pane

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.

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.

Design

  • 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.

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.