Files
pipelines/public/plan.md
T
2026-11-13 18:01:24 +00:00

129 lines
7.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Floating chat windows on every destination
## Behaviour
On desktop, one visible floating chat window remains the same interactive
window on Chat, Pipelines, Runs, Search, and Settings. On every destination its
title bar moves it, each supported edge and corner resizes it, pressing it
focuses and raises it, Minimise hides it without losing content/state, and the
chat action closes or docks it exactly as on Chat. Geometry, focus/order,
minimised state, content, and close/dock state changed on either side of a tab
switch must be retained when returning to Chat and when leaving Chat again.
Do not change window painting, chrome, animation, size limits, persistence
schema, or narrow-layout policy.
## Investigation before editing
Reproduce in the desktop browser fixture with a real `ChatWindows` window, not
the generic probe window: open/float a chat, then visit Pipelines, Runs, Search,
and Settings in both directions. For each destination attempt title movement,
all four edge drags and all four corner drags, focus/raise, Minimise/restore,
and close/dock. Record the hit-tested widget ancestry, whether the gesture
callback runs, `WindowManager.setFrame(save: false)` and `commit` calls,
notifications, the mounted `WindowHost`/`WindowLayer`, and the visible
`WindowEntry.frame` before and after. Repeat Chat → destination → Chat and the
reverse direction. This evidence must identify whether the host/layer placement,
gesture arena, pointer barrier, missing handle, or manager rebuild/state route
is the cause before choosing the fix.
## Files, functions, and existing code to reuse
- `app/lib/application/pipelines_app.dart` (`_buildShell`), `app/lib/shell/adaptive_shell.dart`,
`app/lib/ui/motion/fade_through_stack.dart`, and
`app/lib/features/terminal/terminal_surface.dart`/`terminal_stage.dart`:
trace the actual stack and destination/terminal layering. Keep exactly one
app-lifetime `WindowManager` and `WindowHost` above every destination, with
popup layering and terminal composition unchanged.
- `app/lib/shell/windows/window_host.dart`: retain its shared-manager listener,
focus restoration, visibility, animation, bounds calculation, and
`WindowLayer` creation. Ensure the mounted host receives input on all five
destinations and rebuilds from the same manager.
- `app/lib/shell/windows/window_layer.dart`: reuse `_move`, `_resize`, clamping,
fractional-delta accumulation, `setFrame(save: false)`, `commit`, focus/raise,
and minimise callbacks. If evidence shows edge routing is missing, extend
resize geometry to directional deltas (left/right/top/bottom) while retaining
the existing minimum-size and bounds fitting.
- `app/lib/shell/windows/window_frame.dart`: retain the title
`GestureDetector` and current `WindowResizeCorner`. Add hit-test-only handles
for all supported edges and corners (left, right, top, bottom, and the four
corners), with the correct resize cursor and directional callback. Keep
painted visuals, outline, handle touch size, and maximised-window exclusion
unchanged; do not add visible edge chrome.
- `app/lib/shell/windows/window_manager.dart` and
`app/lib/features/chat/windows/chat_windows.dart`: retain shared frame
replacement/notification, server scoping, focus/raise, minimise, close/dock,
saved-frame semantics, and chat subscriptions. Change routing or ownership
only where the reproduction proves it stale or Chat-only.
- `app/tool/search_selection_probe_entry.dart` and
`app/tool/capture/window_probe.dart` only as needed for fixture plumbing:
add a deterministic real-chat setup/open-float control and destination
navigation. Do not use `?windows=N` probe windows as evidence for this bug.
Reuse the existing server-shaped `chat_sessions`, `chat_create`,
`chat_messages`, and chat subscription replies.
## UI states, layouts, and fixture evidence
At 1600 px desktop, light and dark, show Chat plus each of Pipelines, Runs,
Search, and Settings with one floating chat, two overlapping chats (raise the
lower one), minimised/restored group, and close/dock. For each destination
capture the title drag, each edge and corner resize in progress and committed,
focus raise, and the Chat → destination → Chat geometry round trip. Use the
fixture controls `?chatWindow=1` (real deterministic floated chat),
`?chatWindows=2` (overlap), `?chatState=empty|loading|error|long`, and
`?chatTitle=long`; `loading` must hold the `chat_messages` reply until the
capture step, `error` must return a server-shaped error, `empty` must return
the current empty history, and `long` must return deterministic long message
content/title. Capture the normal populated state too, and document the exact
route/rail/bar action used to select each destination.
At 430 px phone, light and dark, verify Chat and each supported destination
with the same empty/loading/error/long controls: floating windows remain
hidden/managed exactly as before, no edge handles appear, and the normal
navigation bar/rail and terminal surfaces are unchanged. Capture 1.3× text for
title/layout text. No new popup, sheet, or visual window control is added.
## Data and edge cases
Use existing frame clamping, host bounds, kind minimum size, and async save.
Cover fractional pointer deltas; each edge and corner shrinking to minimum
size; windows at every host boundary; overlapping windows; maximised windows
(no resize); hidden/minimised groups; long titles (ellipsise as today);
empty/loading/error chat content; chat replacement/dock/close; server-scoped
IDs; and unavailable or malformed fixture replies. Do not alter API envelopes,
server scoping, saved-frame format, or introduce fake production fallbacks.
## Acceptance and regression tests
1. Reproduction notes identify the actual cause and show the real fixture
working on Pipelines, Runs, Search, and Settings, not only one alternate
tab.
2. On each of those four destinations, named widget tests assert:
`titleDragMovesWindow`, `leftEdgeResizeChangesFrame`,
`rightEdgeResizeChangesFrame`, `topEdgeResizeChangesFrame`,
`bottomEdgeResizeChangesFrame`, `topLeftCornerResizeChangesFrame`,
`topRightCornerResizeChangesFrame`, `bottomLeftCornerResizeChangesFrame`,
and `bottomRightCornerResizeChangesFrame`. Each asserts the manager entry
and rendered frame, including directional movement and minimum clamping.
3. Named tests assert `pressRaisesAndFocusesWindow`,
`minimiseRestorePreservesContent`, and `closeOrDockMatchesChatAction`.
A named `geometryPersistsAcrossEveryDestination` test changes geometry on
each non-Chat destination, switches to Chat and back, and repeats for a
Chat-originated change.
4. Extend `app/test/shell/windows/window_host_test.dart` and/or
`window_rebuild_test.dart` for host/layer and all directional handles;
extend `app/test/features/chat/windows/chat_windows_test.dart` only for
chat-specific persistence or close/dock assertions. Keep tests on the
shared manager, not a duplicate controller.
5. From `app/`, run only focused checks through
`tool/memwatch/full.sh test test/shell/windows test/features/chat/windows`,
then `tool/analyze.sh` and the relevant fixture/browser capture checks.
Inspect every cited capture; widget tests are not browser evidence.
## Risks and must not change
Do not put the host below an active destination layer, introduce a second
manager, let `FadeThroughStack` remount it, or save only while Chat is mounted.
Preserve popup/route layering, focus restoration, terminal windows, navigation,
server isolation, theme/chrome, animation, accessibility labels, appearance,
phone behaviour, and every existing Chat interaction.