Files
pipelines/docs/plans/floating-windows.md
T

21 KiB

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.

Status (2026-11-11)

Phases 0 to 4 are on main; e9fa1b6e (through Phase 3) is deployed. Details and what was checked: app/notes/floating-windows.md and app/notes/chat-floating-pane.md. Open: the items in section 6, and these found on the way:

  • A tooltip of a window that is not on top can be covered by a window above it.
  • The Cupertino code is still in the app; new work is Material only.
  • "Pipelines app change" v6: a failed land gate ends the run instead of going back to implement, transport errors use up the UI review's visit limit, and implement runs only the task's named tests, so a removed Cupertino branch breaks tests elsewhere that only the gate sees. Runs 303-306 all failed this way and were finished by hand.

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 GlobalKeyed 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).

  • Center stage with the file explorer open is cramped (reported 2026-11-11): the stage width must account for the open explorer.

  • The file explorer forgets where it was (reported 2026-11-11): closing and reopening it should return to the folder it showed, not the start.

  • Copy from the terminal does not work in the web app on Linux (reported 2026-11-10). Likely cause: the only copy key there was Ctrl+Shift+C, which a browser keeps for its developer tools. Fixed 2026-11-11: Ctrl+C copies a selection, Ctrl+Insert too. Covered by widget tests on the Linux platform; not yet confirmed in a Linux browser.

Sources