From 132bd11fc66a4164a08398e3dade3a5f7dab66b6 Mon Sep 17 00:00:00 2001 From: Alan Silva Date: Tue, 10 Nov 2026 18:16:07 +0000 Subject: [PATCH] Plan floating windows as a shell-level window system Why popups open behind floating chats, why the chat float is still tied to the Chat tab, and a phased plan for one window host that terminal, chats and later runs and pipelines share. --- docs/plans/floating-windows.md | 361 +++++++++++++++++++++++++++++++++ 1 file changed, 361 insertions(+) create mode 100644 docs/plans/floating-windows.md diff --git a/docs/plans/floating-windows.md b/docs/plans/floating-windows.md new file mode 100644 index 00000000..44677489 --- /dev/null +++ b/docs/plans/floating-windows.md @@ -0,0 +1,361 @@ +# 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/Cupertino variants, + 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 + +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, + Material/Cupertino: + - 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 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 to make before Phase 2 + +1. **Pages pushed from a window** (image viewer, file viewer, diffs, shell + output): open as full-app root routes (simplest, readable), or inside the + window (needs a window-local `Navigator`, and then transient popups need a + root helper). + - Recommendation: root routes now, in-window later per kind. +2. **Sheets opened from a window** on desktop: keep bottom sheets for now (they + become root routes and are readable), and convert to anchored menus or + dialogs as part of the desktop-polish work. +3. **What the window's X does:** close this window (the chat goes back to the + tiling? closed?) versus hide the group, which is what it does today. + - Recommendation: X closes (docks) this window; the chord or menu hides the + group. +4. **Windows across servers:** with saved servers, do chat windows from several + servers coexist? + - Recommendation: yes, keyed by server; the runtime is per server scope. + +## 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 Cupertino and + 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). + +## 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