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:
@@ -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
|
||||
Reference in New Issue
Block a user