3.0 KiB
3.0 KiB
Floating windows (window system core)
Plan: docs/plans/floating-windows.md. The shell-level window system hosts
floating chats (notes/chat-floating-pane.md); the terminal moves in Phase 3.
Pieces (lib/shell/windows/)
WindowManager(one perPipelinesApp): the open windows bottom to top, frames, minimised/maximised, group show/hide, cycling. Saved throughWindowStore(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'skinds): 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 aMaterialPageRoute: 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 menus are
AppMenuAnchor(ui/adaptive/app_menu_anchor.dart), whose panel is in the root overlay; a test rejects a bareMenuAnchor. - A window takes the keyboard at the press, not after it, and never from a
popup that covers the app; its content is not the current surface
(
SurfaceVisibility) while one does. - 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, andwindow_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-0and/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.