Files
pipelines/app/notes/floating-windows.md
T
alan 75a61dbd8c Make the terminal's floating mode a window of the window system
Phase 3 of docs/plans/floating-windows.md. The terminal window kind reuses
TerminalHub; TerminalWindows keeps the window in step with TerminalLayout
(show opens or shows it, hide minimises it, Minimise and Close hide the
terminal). The bottom panel stays a shell panel. The first window takes the
frame and maximised state pipelines.terminal-layout.v1 saved.

The terminal's own float chrome and FloatingLayer are deleted.
2026-11-10 22:19:30 +00:00

4.7 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) 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.