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:
Miguel Palhas
2026-09-03 10:42:53 +01:00
parent b36d571b21
commit f6b2cf3ab4
10 changed files with 598 additions and 26 deletions
+71
View File
@@ -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.