20 KiB
Plan: floating windows as a first-class part of the app
Written 2026-11-10 to start in a new session. Goal: one window system owned by the shell that can host any content (terminal and chats first; runs, pipelines and anything else later), instead of a chat feature and a terminal feature each faking windows in their own way.
1. Why the current floating chat is broken
All findings below are from code reading (file:line on main at 1b698a12) and
the Flutter 3.44.6 SDK source installed at /Users/alan/development/flutter.
1.1 Popups open behind the window (the bug you hit)
- A floating chat is painted through
FloatingLayer(app/lib/ui/floating/floating_layer.dart:81), anOverlayPortaltargeting the root overlay. Flutter paints a portal's child just above the overlay entry that contains the portal and below the next one (SDKwidgets/overlay.dart:1837). That entry is the router's single shell page (application/app_router.dart:141-144). So the window sits on top of the whole shell page. - But the window's content still lives inside the Chat destination. An
OverlayPortalkeeps its element-tree position, soNavigator.of,Overlay.of,ModalRoute.ofandScaffoldMessenger.offrom inside the window resolve to the detail pane's nested Navigator (shell/detail_pane_navigator.dart:57) and the shell Scaffold. Both are inside the shell page, which the window covers. - Behind the window (nearest Navigator/Overlay), on the Material path the app
uses everywhere (
ui/adaptive/platform.dart:11):- chat details (
chat_thread_view.dart:535, bottom sheet) - mode picker (
chat_mode_control.dart:86, bottom sheet) - More actions menu (
ui/adaptive/segmented_bar_overflow.dart:101,MenuAnchor) - Thinking/effort menu (
chat_effort_control.dart:161,MenuAnchor) - add-pane picker (
chat_add_pane_picker.dart:34) - turn, diff and shell-history sheets (
chat_turn_chip.dart:130) - file details, files sort and row menus (
files_details.dart:92,ui/layout/app_overflow_menu.dart:64) - image viewer, file viewer, diff and shell output pages
(
Navigator.of(context).push) - question-card dropdowns (
chat_question_option_controls.dart:134) - every
Tooltip, including the window's own Dock/Hide buttons (RawTooltiphas no root option, SDKwidgets/raw_tooltip.dart:886) - SnackBars (shell Scaffold,
shell/adaptive_shell.dart:265)
- chat details (
- Above the window (root Navigator or root overlay):
showDialog, allshowCupertino*, model picker (chat_model_control.dart:96), activity and HTML viewers, background tasks, folder picker, text selection and context menus (ContextMenuControllerinserts at the top of the root overlay). - Over another destination it is worse: the Chat destination is
Offstage, so nested popups may not paint at all.
1.2 The window is not really "outside" the Chat tab
FadeThroughStack wraps every hidden destination in Offstage,
TickerMode(false), IgnorePointer, ExcludeFocus and ExcludeSemantics
(ui/motion/fade_through_stack.dart:154-176). The floating chat escapes paint
and hit testing (overlay), and focus through a workaround (FloatingFocusRoot,
adaptive_shell.dart:429), but not:
- Tickers. An inner
TickerMode(true)cannot re-enable an outerfalse(SDKwidgets/ticker_provider.dart:239:enabled = ancestor && widget). Spinners, live elapsed time and relative times freeze inside a floating chat on another tab. Only the window's own reveal animation was patched (a privateTicker,chat_float_host.dart:259). - "Am I visible?" checks. Four places use
TickerModeas a visibility signal: system Back (detail_pane_navigator.dart:51), composer focus (chat_composer_bar.dart:265), live elapsed (ui/text/live_elapsed_builder.dart:42) and relative times (ui/text/relative_time_label.dart:56). So Ctrl+Y on another tab shows the window but its composer refuses the keyboard. - Lifetime. The shell builds a destination only after it is first visited
(
adaptive_shell.dart:63,167). Saved floating chats don't appear until you open the Chat tab once, and they vanish when Chat swaps toConnectionGate(application/chat_destination.dart:46-74).
1.3 Two half-systems
- Terminal (
features/terminal/) is mounted at shell level (TerminalSurfacearoundAdaptiveShell,application/pipelines_app.dart:724-732). It has its own chrome, move/resize, min/max, layout singleton with persistence (pipelines.terminal-layout.v1) and focus handling (terminal_focus.dart). It usesFloatingLayeronly to share stacking with chats. - Chat floats are part of
ChatWorkspaceController(chat_workspace_float.dart), hosted inside the Chat destination (chat_float_host.dart), with their own chrome (chat_float_window.dart), frames (ChatFloatFrames), store (pipelines.next.chatFloat.v1, v2 format) and duplicated focus logic. - Generic in substance but buried in features: window chrome
(
terminalFloatChrome,ChatFloatWindow), frame fitting, cascading placement, reveal animation, focus remember/restore.
2. Target design
2.1 One window layer in the shell page, not an overlay
Add a window host to the shell page, above the destination stack and the
terminal panel, as plain positioned children of a Stack. No OverlayPortal.
That single decision fixes layering structurally:
- Window content is built at shell level, so
Navigator.of(context)is the root Navigator. Sheets, menus, dropdowns and pushed pages become root routes, which paint above the shell page and so above every window. Overlay.of(context)is the root overlay. Tooltips andMenuAnchorpanels are portals of the shell page entry, so they paint after the whole page, including the windows.- Hit testing,
TickerMode, focus and semantics are no longer inherited from a hidden destination: the host is a sibling ofFadeThroughStack, not inside it.FloatingFocusRootand the private-ticker workaround go away. - Each window gets its own
ScaffoldMessenger+Scaffold(transparent), soScaffoldMessenger.offrom window content shows SnackBars inside that window. - Where to mount it: inside
TerminalSurface's stage, so the terminal panel and windows share one stack and one z-order. Thedraggable_floating_windowpackage documents the same rule: popups open above every window only when the window stack sits inside a page, not over it.
2.2 Window model (app lifetime, like TerminalHub)
WindowManager(ChangeNotifier), created inpipelines_app.dartbesideAppTerminals.WindowEntry:id,kind,contentId(chat session id, terminal, later run id),frame,minimized,maximized,visible,groupId.- Bottom-to-top order list;
active= last pressed or focused. - Operations:
open,close,raise,move,resize,minimize,maximize,toggleGroup(show/hide all windows of a kind together, the current chat behaviour),cycle. - Placement: cascading default frames, fit-to-bounds on window resize (generalize
fitChatFloat/fitTerminalFloat), and a frame kept percontentIdso a window re-opens where it was.
2.3 Kinds are plug-ins
WindowKind (registered at app start) provides:
build(context, entry)- title and icon
- chrome actions (Dock, Hide, kind-specific menu)
- minimum size
- whether it is server-scoped
- a codec for persistence
terminal and chat are the first two. run and pipeline later need only a
new kind.
2.4 Chrome, focus, keyboard
- Chrome: one
WindowFramewidget, generalized fromChatFloatWindow+terminalFloatChrome. Title-bar drag, corner resize, double-click maximize, min/max/close, reveal motion viaMotion.of, Material only (no Cupertino variant), hover cursors and tooltips. - Focus: each window has a
FocusScopeunder the host. OneWindowFocusreplacesTerminalFocusand the chat float's copy: remember on show, restore on hide, focus the active window's preferred node. - Keyboard: Alt+T / Ctrl+T / Cmd+T for the terminal and Alt+Y / Ctrl+Y /
Cmd+Y for chats remain group toggles (see the work in progress below). Add a
window-cycle chord (browsers reserve Ctrl+Tab; pick something web-safe, for
example Alt+`) and Esc to close the top transient popup only.
- Menus and tooltips name the Alt variants.
2.5 An explicit visibility signal instead of TickerMode
Add a SurfaceVisibility inherited value (shown, current), provided by
FadeThroughStack pages and by each window. Move the four TickerMode readers
(1.2) to it. This is independent of the window work and makes "is this composer
current" correct inside windows. TickerMode stays only for muting animation.
2.6 Chat content without ChatScreen
Today a pane's ChatThreadView gets most of what it needs from ChatScreen
state. The full table is in the investigation transcript; the essentials:
- Callbacks into ChatScreen:
_rowFor, model/mode/effort changes,/newfollow-up, rename, close, colour,_closePane. - Per-screen objects:
_sessionscontroller,_openedSessions,_acceptedModels, scroll and transcript caches,_composerFocus. - Scopes wrapped around the content:
ChatComposerFocusScope(screen.dart:555)ServerContext.forServer(:558)DetailPane(forShellBarScope,chat_screen_workspace.dart:393)ChatWorkspacePaneScope
Plan:
- Extract an app-lifetime
ChatRuntime(one per server scope, created beside the chat pool), holding the sessions controller, opened rows, accepted models, scroll/transcript caches, composer focus requests and the per-session action callbacks.ChatScreenbecomes a consumer of it, with no behaviour change.
- One builder,
buildChatPaneContent(runtime, sessionId, placement), that wraps the thread in the scopes above. Both the tiling and the chat window kind use it. - Float and dock keep live state by moving the same
GlobalKeyed subtree between the tiling (inside Chat) and the window host (shell level).- This is legal within one page if both moves happen in the same frame.
- Every scope the content depends on must exist at both places; that is why the builder provides them.
- Chat windows restore at app start from the runtime, not when the Chat tab
is first visited.
- A disconnected server shows a "reconnecting" state in the window instead of unmounting it.
3. Phases
Each item is one small change, independently testable, landed before the next one that depends on it. Items marked (∥) can run in parallel with their phase neighbours.
Phase 0: finish what's in flight (small, do first)
- Work in progress in
../pipelines-bar-keys(branchbar-padding-alt-keys, uncommitted; tests were interrupted):- Action bar text buttons get 12 px horizontal padding, so text sits as far
from the button edges as it does top and bottom. The pill inset added in
440995e3is removed. - Alt+Y (Option+Y by key position, like Alt+T) toggles the floating chats.
- Check:
- The fake keyboard in
chat_float_shortcut_test.dartnow overridesisLogicalKeyPressed; run its tests. - Run
tool/memwatch/full.sh 'test/features/chat test/features/terminal test/shell'. - Look at a capture of the header at 1440x900, hovering a model button.
- The fake keyboard in
- Alt+T already toggles the terminal (
terminal_shortcuts.dart:16-27); confirm on web, macOS and Linux and in menu labels.
- Action bar text buttons get 12 px horizontal padding, so text sits as far
from the button edges as it does top and bottom. The pill inset added in
- Deploy the capture fix
1b698a12(.env.examplemade every pipeline visit "partial"):./install, thenpipelines restartwhen no run is active. The running server is stillc6ab716e. - Optional stopgap until Phase 2 lands, if you want readable popups now:
- Route popups from window content to the root.
- Use
useRootOverlay: trueonSegmentedMoreButton's and the effort control'sMenuAnchor,useRootNavigator: trueinAppOverflowMenuand on the info, mode, add-pane, turn, files and file-details sheets. - Tooltips and SnackBars stay behind.
- About 8 call sites. I'd skip this unless Phase 1-2 will take more than a few days.
Phase 1: window system core (no feature moves yet)
SurfaceVisibility(2.5) and moving the four readers. (∥)WindowManager+WindowEntry+WindowKindregistry +WindowStore.WindowStoreis device-local, versioned, with per-kind codecs and server-scoped entries keyed by server.- Pure Dart plus unit tests.
WindowHostin the shell page (2.1), withWindowFramechrome (2.4), per-windowScaffoldMessenger, z-order on press/focus,WindowFocus.- A test-only window kind.
- Layering acceptance tests for every popup type, opened from inside a
window over Chat and over another destination: bottom sheet,
MenuAnchor,PopupMenuButton,DropdownButton,Tooltip,showDialog, pushed page, SnackBar, text-selection menu.- Each asserts a hit test at the popup's rect reaches the popup, not the window.
- This is the regression net the floating chat never had.
Phase 2: chats on the window system
(Per decision 4.1, Phase 1.3 already gives each window its own page
Navigator and the root-popup helpers.)
- Extract
ChatRuntime;ChatScreenuses it. Behaviour identical; existing chat tests stay green. May need 2-3 changes (state, then callbacks, then caches). buildChatPaneContentused by the tiling.chatwindow kind: float, dock, several at once, group show/hide (Alt/Ctrl/Cmd+Y), per-session frames.- Migrate the
pipelines.next.chatFloat.v1(v1 and v2) records. - Restore at startup.
- Migrate the
- Remove
ChatFloatHost,ChatWorkspaceFloat's float list,FloatingFocusRootand the chat use ofFloatingLayer.- The workspace keeps only "this pane is out in a window".
- Real-browser acceptance at 1280x800 and 1920x1080, light/dark:
- Every popup in 1.1 from a floating chat, over Chat and over Runs.
- Typing, paste (text and image), streaming spinner and elapsed time over Runs.
- Reload restores windows without visiting Chat.
Phase 2b: desktop menus instead of bottom sheets
One change per surface, each with captures of the menu open, in the tiling and in a window:
- Adaptive helpers (
showAppChoiceMenu,showAppDetails) inui/adaptive/.- On a wide layout: an anchored
MenuAnchorpanel, or a dialog/popover for details. - On a phone: the bottom sheet.
- Root-targeted, so they are always above windows.
- On a wide layout: an anchored
- Mode picker (
chat_mode_control.dart:86) and add-pane picker (chat_add_pane_picker.dart:34). - Turn, diff and shell-history sheets (
chat_turn_chip.dart:130). - Chat details (
chat_thread_view.dart:535) and file details (files_details.dart:92) as dialogs/popovers. - Files sort and row menus (
AppOverflowMenu), and runs sort (runs_filters.dart:264).
Phase 3: terminal on the window system
terminalwindow kind reusingTerminalHub. The panel mode stays a shell panel; only the floating mode becomes a window.- Migrate
pipelines.terminal-layout.v1float frame, minimized and maximized; drop the terminal's own float chrome andFloatingLayeruse. - Delete
FloatingLayerif nothing else uses it.
Phase 4: desktop window conveniences
- Window list and menu (show all, close all, bring to front).
- Window cycling chord.
- Snap to halves/corners (optional).
- Double-click title to maximize for every kind.
- Remember window size per kind.
Later: more kinds
run (run detail), pipeline (definition or graph), artifacts. Each is a new
WindowKind with a build and a codec; no changes to the host.
4. Decisions (answered 2026-11-10)
- Pages open inside the window. Opening an artifact list in a window and
clicking an artifact opens that artifact in the same window, with Back inside
the window. The same goes for image and file viewers, diffs and shell
output.
- Each window gets its own
Navigatorfor pages (it owns the window's content and back stack). - Transient popups (menus, tooltips, dialogs, sheets) must still appear
above every window and must not be clipped to the window. Window content
opens them through one set of app helpers that target the root
Navigator/Overlay, and
Tooltip/MenuAnchorneed a root-targeting wrapper becauseRawTooltiponly uses the nearest overlay. - Layering tests (Phase 1.4) cover both: pages inside, popups above.
- Each window gets its own
- Menus instead of bottom sheets on desktop (decided).
- Short choice lists become menus anchored to their button: mode, sort, add pane, turn options, file row actions, and any other list of options.
- Richer content (chat details, file details) becomes a dialog or a popover beside the button.
- Phones keep bottom sheets.
- Built into the shared popup helpers from Phase 1, so window content and the tiled app get the same behaviour (see Phase 2b).
- Window chrome: minimize and close.
- Every window gets a minimize button (the window hides; it stays in the window list and its group's show/hide chord).
- X closes that window. For a chat, closing returns nothing to the tiling; Dock stays a separate action.
- Group show/hide stays on the chords and the window menu.
- One server for now. Windows (and
ChatRuntime) are built for the current server only, but window entries and stores carry a server key, and the runtime is looked up by server, so several servers can be added later without changing the model.
5. How to run this
- The architecture items (1.2-1.4, 2.1-2.4) touch shared shell code, so they're
best done by the manager directly or with close supervision. Small leaf items
(1.1, the Phase 0 items, later kinds) fit the
Pipelines app changepipeline (v5). - Pipeline v5 now runs each run in its own worktree and lands through the
delivery gate (analysis plus
test/features test/shell test/ui test/core, about 11 minutes). - Lesson from run #299: its UI review approved text glued to a pill edge. For window work, the task prompt must name the exact states to capture (popups open over another tab, hover states). The UI review stage's prompt should be tightened to reject visible alignment and clipping defects.
- Every UI change must be checked in the real app (capture kit) in the states it touches before it is called done, including popups opened from a window. The floating chat shipped without that, and that is how this bug reached you.
6. Other open items from this session (not part of the window work)
-
Desktop polish audit (run #297,
~/.local/share/pipelines/data/artifacts/297):- floating bottom nav on desktop (rail instead)
- mixed 48/44/text control metrics in the chat bar
- bottom sheets where desktop wants menus/popovers
- narrow content on wide windows
- rotated center-stage strips
- inconsistent hover, tooltips and cursors
- no shortcut overlay
The report was thin (4 Material captures); redo it with measurements before acting.
-
Known failures excluded from the delivery gate: 44 in
app/test/application, and Gointernal/claudeandinternal/opencode. Fix them, then put those suites back in the gates of pipelines 22, 23 and 32. -
Animations inside floating chats on other tabs freeze: fixed structurally by Phase 2 (content leaves the hidden destination).
-
Copy from the terminal does not work in the web app on Linux (reported 2026-11-10). Not investigated yet: reproduce in a Linux browser, check the selection and the clipboard write, then fix.
Sources
- Flutter
OverlayPortal(paint order relative to overlay entries): https://api.flutter.dev/flutter/widgets/OverlayPortal-class.html OverlayPortal.targetsRootOverlaydeprecation andoverlayLocation: https://docs.flutter.dev/release/breaking-changes/deprecate-overlay-portal-targets-rootMenuAnchor.useRootOverlay: https://api.flutter.dev/flutter/material/MenuAnchor/useRootOverlay.htmlTickerMode: https://api.flutter.dev/flutter/widgets/TickerMode-class.html (combination rule confirmed in SDK sourcewidgets/ticker_provider.dart:239)- In-app window manager reference (per-window focus, dialogs, popups above windows only when the stack is inside a page): https://pub.dev/packages/draggable_floating_window
VisualDensitydesktop defaults: https://api.flutter.dev/flutter/material/VisualDensity-class.html