Add the shell window host with layering acceptance tests
Phase 1.3 and 1.4 of docs/plans/floating-windows.md. Windows are plain children of the terminal stage's stack in the shell page, outside every destination, so popups opened from one are above all of them. Each window has its own page navigator: pushed pages open inside the window, and popup routes go to the root navigator. One WindowFrame chrome (move, resize, minimise, maximise, close), a focus scope per window, a ScaffoldMessenger per window. No feature uses it yet. The capture fixture opens probe windows with ?windows=N, and window_layering_test.dart covers every popup type from a window over Chat and over another destination.
This commit is contained in:
@@ -0,0 +1,51 @@
|
||||
# Floating windows (window system core)
|
||||
|
||||
Plan: `docs/plans/floating-windows.md`. Phase 1 adds the shell-level window
|
||||
system; no feature uses it yet (chats move in Phase 2, the terminal in Phase 3).
|
||||
|
||||
## Pieces (`lib/shell/windows/`)
|
||||
|
||||
- `WindowManager` (`AppWindows.manager`): 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` (`AppWindows.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 a `MenuAnchor` in window content needs
|
||||
`useRootOverlay: true` (its panel may extend past the window).
|
||||
- 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.
|
||||
Reference in New Issue
Block a user