e4f3ebdcab
Remove the separate minimise control and make the title-bar X hide windows while preserving their state and reachability. Update window behavior documentation and focused tests for chat, terminal, and window layering.
108 lines
6.0 KiB
Markdown
108 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, Maximise, the X = minimise) and resize corner.
|
|
There is no separate Minimise button; the X hides the window and keeps it.
|
|
- `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 X (minimise)
|
|
hides 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.
|