# Floating windows (window system core) Plan: `docs/plans/floating-windows.md`. The shell-level window system hosts floating chats (`notes/chat-floating-pane.md`) and the terminal's floating mode (below). `FloatingLayer`, the overlay the old windows used, is gone. ## 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 menus are `AppMenuAnchor` (`ui/adaptive/app_menu_anchor.dart`), whose panel is in the root overlay; a test rejects a bare `MenuAnchor`. - 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, 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. ## Desktop popups (Phase 2b) `ui/adaptive/app_popups.dart`: `showAppChoiceMenu` (a short list of choices: a menu panel anchored to its button on a wide app, a bottom sheet on a phone) and `showAppDetails` (richer content: a dialog, or a bottom sheet on a phone). Both are on the root navigator, so they are above every window, and the app's width decides (`usesDesktopPopups`), not the surface asking: content in a narrow window on a wide app still gets menus and dialogs. The probe window has `choice` and `details` buttons for captures. ## Terminal window (Phase 3) `features/terminal/terminal_window.dart`: the `terminal` kind (one window for the device, not a server) and `TerminalWindows`, which keeps it in step with `TerminalLayout`. The layout stays the terminal's own state (shown, panel or float, panel height); the bottom panel is still a shell panel. - Showing the terminal in float mode opens or shows the window; hiding it (Alt+T, Ctrl+`, the options menu) minimises it. The window's Minimise and Close both hide the terminal. Its shells and tabs live in `TerminalHub`, so nothing is lost either way, and the window comes back where it was. - The frame and maximised state are the window system's. The first window takes the ones `pipelines.terminal-layout.v1` saved before; that record is still written back unchanged. - The window opens only after the manager has restored its saved windows. - Captured 2026-11-11 at 1280x800 and 1920x1080, light and dark, over Chat and over Runs: the window, its options menu, tooltips, a second tab, typing, hide and show by Alt+T, maximise, move, minimise, and the frame after a reload.