Files
pipelines/app/notes/floating-windows.md
T
alan fdc730422d Host floating chats on the shell window system
Phase 2.3 and 2.4 of docs/plans/floating-windows.md. A floating chat is a
window of the chat kind over the app's WindowManager, built from the
app-lifetime ChatRuntime, so it shows over every destination and at start
without the Chat destination being built. Float and Dock move the same
keyed view between the tiling and the window host. The pipelines app keeps
one runtime and one ChatWindows; saved chatFloat records (v1 and v2) are
brought over once.

ChatFloatHost, ChatFloatWindow, the float frames and binding, the
controller's float list and FloatingFocusRoot are gone; the workspace only
asks whether a chat is out in a window. Every MenuAnchor targets the root
overlay (guarded by a test), and menus and tooltips name the Alt chords.
2026-11-10 21:17:40 +00:00

2.8 KiB

Floating windows (window system core)

Plan: docs/plans/floating-windows.md. Phase 1 adds the shell-level window system; no feature uses it yet (chats move in Phase 2, the terminal in Phase 3).

Pieces (lib/shell/windows/)

  • WindowManager (one per PipelinesApp): the open windows bottom to top, frames, minimised/maximised, group show/hide, cycling. Saved through WindowStore (pipelines.windows.v1), one record for every server; server-scoped windows carry their server key and only the current server's are listed.
  • WindowKind (registered on the manager's kinds): what a kind of window builds, its title, icon, title-bar actions, minimum size and saved data.
  • WindowHost: the windows as plain children of the terminal stage's stack, in the shell page (not an overlay above it), outside every destination.
  • WindowLayer / WindowFrame: one window's card, title bar (drag, double click to maximise, kind actions, Minimise, Maximise, Close) and resize corner.
  • WindowNavigator: each window's own page stack.
  • WindowFocus: a focus scope per window; the keyboard follows the top window and returns to what had it when the last one hides.
  • WindowScope.maybeOf(context): non-null inside a window.

Layering rules

  • A page pushed with Navigator.of(context).push(MaterialPageRoute) from window content opens inside the window (Back inside it). It must be a MaterialPageRoute: the window's page transitions are what draw a page inside the content area.
  • A PopupRoute (bottom sheet, dialog, popup menu, dropdown) pushed on the window's navigator is sent to the root navigator, so it is above every window and never clipped to one.
  • The window's navigator covers the whole host so popups anchored to a button measure in app coordinates and tooltips paint outside the window; only the content area takes input. So a MenuAnchor in window content needs useRootOverlay: true (its panel may extend past the window).
  • Known limit: a tooltip of a window that is not on top can be covered by a window above it where they overlap (tooltips paint in their own window's overlay). Pressing a window raises it, so menus are not affected.

Checks

  • test/shell/windows/: manager, store, host behaviour, and window_layering_test.dart, the acceptance net for every popup type from a window, over Chat and over another destination.
  • Real app: the capture fixture opens probe windows with ?windows=N (tool/capture/window_probe.dart). Captured 2026-11-10 at 1280x800 and 1920x1080, light and dark, over /chat/perf-chat-0 and /runs/7: sheet, dialog, MenuAnchor, popup menu, dropdown, content and title-bar tooltips, hover, SnackBar, pushed page and Back, raise, move, maximise, minimise.
  • Not captured in the browser: the text-selection menu (the kit has no right-click); covered by the layering test only.