Files
pipelines/app/notes/floating-windows.md
T
alan ef1c120f57 Add the Windows menu, window cycling, edge snapping and size per kind
Phase 4 of docs/plans/floating-windows.md. A bar button lists the app's
windows on every tab (show one, Show all, Minimise all, Close all). Alt+`
and Alt+Shift+` bring the next or previous window to the front. Dropping a
title at the left or right edge fills that half, at the top it maximises.
A new window of a kind opens at the size that kind was last given.
2026-11-11 00:05:16 +00:00

107 lines
6.0 KiB
Markdown

# 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.
## Window conveniences (Phase 4)
- **Windows menu** (`windows_menu_button.dart`): a bar button on every tab
while the app has windows. It lists each window (topmost first; a tick on the
active one, a minimise mark on hidden ones); choosing one shows it and brings
it to the front. Then Show all, Minimise all and Close all.
- **Cycle chord** (`window_shortcuts.dart`): Alt+` brings the next window to the
front and Alt+Shift+` the previous one, from anywhere, when two or more
windows show and no popup covers the app. Ctrl+` stays the terminal's.
- **Snapping**: dropping a title with the pointer within 6 px of the app's left
or right edge fills that half; at the top edge it maximises.
- **Size per kind**: a new window of a kind opens at the size that kind was last
given by a move or resize (not a snapped or maximised one), placed by the
cascade. Saved with the windows (`sizes`).
- Double click on a title maximises for every kind (since Phase 1).
- Captured 2026-11-11 at 1280x800 and 1920x1080, light and dark, over Chat and
over Runs: the button and its tooltip, the menu, a hovered item, choosing a
window, cycling, Minimise all, the menu with minimised windows, Show all, and
snapping left, right and to the top.