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.
This commit is contained in:
2026-11-10 18:16:07 +00:00
parent 1b698a1241
commit 132bd11fc6
+361
View File
@@ -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