31f495fc18
Phase 2b.1 of docs/plans/floating-windows.md. showAppChoiceMenu is a menu panel anchored to its button on a wide app and a bottom sheet on a phone; showAppDetails is a dialog or a bottom sheet. Both are on the root navigator, and the app's width decides, so content in a narrow floating window still gets desktop popups. The probe window exercises both.
66 lines
3.6 KiB
Markdown
66 lines
3.6 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`); the terminal moves in Phase 3.
|
|
|
|
## 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.
|