feat(maestro): preview the highlighted session in the web pane
Moving the sidebar highlight (keyboard or hover) now shows that session in the content pane without opening it: its own tab comes forward, or a throwaway tab carries it. The layout, the saved layout and the daemon's focus report are all left untouched, and the keyboard stays in the list. Contract in docs/PREVIEW.md.
This commit is contained in:
@@ -0,0 +1,71 @@
|
||||
# PREVIEW.md — the sidebar preview contract
|
||||
|
||||
One rule for what the content pane shows while the operator is only moving
|
||||
around the sidebar, so the web client and the TUI behave the same. Read this
|
||||
before changing either. If the behaviour needs to change, change it here first.
|
||||
|
||||
## The rule
|
||||
|
||||
Highlighting a session in the sidebar shows that session in the content pane,
|
||||
as if it were focused, **without focusing it and without changing the layout**.
|
||||
Moving the highlight elsewhere puts back exactly what was on screen before.
|
||||
|
||||
A preview is a view, not a state. Nothing about it is durable:
|
||||
|
||||
- The layout is byte-for-byte identical before the preview and after it ends.
|
||||
- Nothing is persisted while a preview is up (the web client's layout is saved
|
||||
to `localStorage`; a preview never reaches it).
|
||||
- The daemon is never told the previewed pane is focused, so a preview never
|
||||
clears a session's `AwaitingInput` glow (`docs/SIDEBAR.md`).
|
||||
- The keyboard stays in the sidebar: the previewed terminal is on screen but
|
||||
does not take focus, so the next `j`/`k` still walks the list.
|
||||
|
||||
## Where the preview is shown
|
||||
|
||||
| The previewed session is… | What happens |
|
||||
|---|---|
|
||||
| Already in a pane, in the active tab | That pane comes forward (its tab's focus moves to it). |
|
||||
| Already in a pane, in another tab | That tab is brought forward. The active tab is restored when the preview ends. |
|
||||
| Not in any pane | A throwaway tab carries it. It is removed when the preview ends. |
|
||||
|
||||
The throwaway tab never counts as an open session: the tab bar does not appear
|
||||
because of it, the mobile shell does not switch away from the session list for
|
||||
it, and the sidebar does not mark the session as open.
|
||||
|
||||
## What ends a preview
|
||||
|
||||
- The highlight moves to another session — that session is previewed instead.
|
||||
- The highlight leaves every session (a folder row, or the list losing the
|
||||
keyboard, or the pointer leaving the list): the previous view comes back.
|
||||
- Any real layout change (split, close, new tab, tab switch, drag): the preview
|
||||
is discarded first, so a throwaway tab is never baked into the arrangement.
|
||||
|
||||
## What commits a preview
|
||||
|
||||
Choosing the previewed session — clicking or pressing Enter on its row,
|
||||
clicking into its pane, or handing the keyboard to the pane (web: `Tab` from
|
||||
the list; TUI: the attach binding) — keeps exactly what is on screen. A
|
||||
throwaway tab becomes a real one; a focus move inside an existing tab stands.
|
||||
Nothing moves a second time on commit.
|
||||
|
||||
## Timing
|
||||
|
||||
A preview follows the highlight closely enough to be usable as a way to look
|
||||
around, and lags a pointer enough not to flash rows crossed on the way
|
||||
somewhere else.
|
||||
|
||||
| Trigger | Delay |
|
||||
|---|---|
|
||||
| Keyboard step (`j`/`k`, arrows) | 60 ms |
|
||||
| Pointer hover (web, mouse only — never touch) | 150 ms |
|
||||
| Clearing (highlight left every session) | same delay as the trigger that set it |
|
||||
|
||||
Touch has no hover, and a tap already opens a session, so touch never previews.
|
||||
|
||||
## Cost
|
||||
|
||||
A previewed session that no pane holds needs a live attach. Both clients keep
|
||||
it connected after the preview ends — the web client parks it in the connection
|
||||
pool's LRU, the TUI keeps its emulator until it falls out of the preview
|
||||
budget — so stepping back onto a row is instant rather than re-fetching
|
||||
scrollback.
|
||||
Reference in New Issue
Block a user