# 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`), an `OverlayPortal` targeting the root overlay. Flutter paints a portal's child **just above the overlay entry that contains the portal and below the next one** (SDK `widgets/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 `OverlayPortal` keeps its element-tree position, so `Navigator.of`, `Overlay.of`, `ModalRoute.of` and `ScaffoldMessenger.of` from 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 (`RawTooltip` has no root option, SDK `widgets/raw_tooltip.dart:886`) - SnackBars (shell Scaffold, `shell/adaptive_shell.dart:265`) - Above the window (root Navigator or root overlay): `showDialog`, all `showCupertino*`, model picker (`chat_model_control.dart:96`), activity and HTML viewers, background tasks, folder picker, text selection and context menus (`ContextMenuController` inserts 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 outer `false` (SDK `widgets/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 private `Ticker`, `chat_float_host.dart:259`). - **"Am I visible?" checks.** Four places use `TickerMode` as 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 to `ConnectionGate` (`application/chat_destination.dart:46-74`). ### 1.3 Two half-systems - **Terminal** (`features/terminal/`) is mounted at shell level (`TerminalSurface` around `AdaptiveShell`, `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 uses `FloatingLayer` only 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 and `MenuAnchor` panels 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 of `FadeThroughStack`, not inside it. `FloatingFocusRoot` and the private-ticker workaround go away. - Each window gets its own `ScaffoldMessenger` + `Scaffold` (transparent), so `ScaffoldMessenger.of` from 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. The `draggable_floating_window` package 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 in `pipelines_app.dart` beside `AppTerminals`. - `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 per `contentId` so 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 `WindowFrame` widget, generalized from `ChatFloatWindow` + `terminalFloatChrome`. Title-bar drag, corner resize, double-click maximize, min/max/close, reveal motion via `Motion.of`, Material only (no Cupertino variant), hover cursors and tooltips. - **Focus:** each window has a `FocusScope` under the host. One `WindowFocus` replaces `TerminalFocus` and 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, `/new` follow-up, rename, close, colour, `_closePane`. - **Per-screen objects:** `_sessions` controller, `_openedSessions`, `_acceptedModels`, scroll and transcript caches, `_composerFocus`. - **Scopes wrapped around the content:** - `ChatComposerFocusScope` (`screen.dart:555`) - `ServerContext.forServer` (`:558`) - `DetailPane` (for `ShellBarScope`, `chat_screen_workspace.dart:393`) - `ChatWorkspacePaneScope` Plan: 1. **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. - `ChatScreen` becomes a consumer of it, with no behaviour change. 2. **One builder,** `buildChatPaneContent(runtime, sessionId, placement)`, that wraps the thread in the scopes above. Both the tiling and the chat window kind use it. 3. **Float and dock** keep live state by moving the same `GlobalKey`ed 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. 4. **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) 1. **Work in progress in `../pipelines-bar-keys`** (branch `bar-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 `440995e3` is removed. - Alt+Y (Option+Y by key position, like Alt+T) toggles the floating chats. - **Check:** - The fake keyboard in `chat_float_shortcut_test.dart` now overrides `isLogicalKeyPressed`; 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. - **Alt+T** already toggles the terminal (`terminal_shortcuts.dart:16-27`); confirm on web, macOS and Linux and in menu labels. 2. **Deploy the capture fix** `1b698a12` (`.env.example` made every pipeline visit "partial"): `./install`, then `pipelines restart` when no run is active. The running server is still `c6ab716e`. 3. **Optional stopgap** until Phase 2 lands, if you want readable popups now: - Route popups from window content to the root. - Use `useRootOverlay: true` on `SegmentedMoreButton`'s and the effort control's `MenuAnchor`, `useRootNavigator: true` in `AppOverflowMenu` and 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) 1. **`SurfaceVisibility`** (2.5) and moving the four readers. (∥) 2. **`WindowManager` + `WindowEntry` + `WindowKind` registry + `WindowStore`.** - `WindowStore` is device-local, versioned, with per-kind codecs and server-scoped entries keyed by server. - Pure Dart plus unit tests. 3. **`WindowHost` in the shell page** (2.1), with `WindowFrame` chrome (2.4), per-window `ScaffoldMessenger`, z-order on press/focus, `WindowFocus`. - A test-only window kind. 4. **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.) 1. **Extract `ChatRuntime`;** `ChatScreen` uses it. Behaviour identical; existing chat tests stay green. May need 2-3 changes (state, then callbacks, then caches). 2. **`buildChatPaneContent` used by the tiling.** 3. **`chat` window 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. 4. **Remove** `ChatFloatHost`, `ChatWorkspaceFloat`'s float list, `FloatingFocusRoot` and the chat use of `FloatingLayer`. - The workspace keeps only "this pane is out in a window". 5. **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: 1. **Adaptive helpers** (`showAppChoiceMenu`, `showAppDetails`) in `ui/adaptive/`. - On a wide layout: an anchored `MenuAnchor` panel, or a dialog/popover for details. - On a phone: the bottom sheet. - Root-targeted, so they are always above windows. 2. **Mode picker** (`chat_mode_control.dart:86`) and add-pane picker (`chat_add_pane_picker.dart:34`). 3. **Turn, diff and shell-history sheets** (`chat_turn_chip.dart:130`). 4. **Chat details** (`chat_thread_view.dart:535`) and file details (`files_details.dart:92`) as dialogs/popovers. 5. **Files sort and row menus** (`AppOverflowMenu`), and runs sort (`runs_filters.dart:264`). ### Phase 3: terminal on the window system 1. **`terminal` window kind** reusing `TerminalHub`. The panel mode stays a shell panel; only the floating mode becomes a window. 2. **Migrate `pipelines.terminal-layout.v1`** float frame, minimized and maximized; drop the terminal's own float chrome and `FloatingLayer` use. 3. **Delete `FloatingLayer`** if 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) 1. **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 `Navigator` for 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`/`MenuAnchor` need a root-targeting wrapper because `RawTooltip` only uses the nearest overlay. - Layering tests (Phase 1.4) cover both: pages inside, popups above. 2. **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). 3. **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. 4. **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 change` pipeline (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 Go `internal/claude` and `internal/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.targetsRootOverlay` deprecation and `overlayLocation`: https://docs.flutter.dev/release/breaking-changes/deprecate-overlay-portal-targets-root - `MenuAnchor.useRootOverlay`: https://api.flutter.dev/flutter/material/MenuAnchor/useRootOverlay.html - `TickerMode`: https://api.flutter.dev/flutter/widgets/TickerMode-class.html (combination rule confirmed in SDK source `widgets/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 - `VisualDensity` desktop defaults: https://api.flutter.dev/flutter/material/VisualDensity-class.html