Files
pipelines/app/notes/floating-windows.md
T
alan a99f7014f5 Add the shell window host with layering acceptance tests
Phase 1.3 and 1.4 of docs/plans/floating-windows.md. Windows are plain
children of the terminal stage's stack in the shell page, outside every
destination, so popups opened from one are above all of them. Each window
has its own page navigator: pushed pages open inside the window, and popup
routes go to the root navigator. One WindowFrame chrome (move, resize,
minimise, maximise, close), a focus scope per window, a ScaffoldMessenger
per window.

No feature uses it yet. The capture fixture opens probe windows with
?windows=N, and window_layering_test.dart covers every popup type from a
window over Chat and over another destination.
2026-11-10 20:48:31 +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 (AppWindows.manager): 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 (AppWindows.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.