400 lines
20 KiB
Markdown
400 lines
20 KiB
Markdown
# 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
|