Files
pipelines/docs/plans/floating-windows.md
T
alan 132bd11fc6 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.
2026-11-10 18:16:07 +00:00

18 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.

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 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

  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