lumbridge-code/docs/UX_VERTICAL_SLICE.md

# Decisive native workspace vertical slice

## Outcome

The slice must let an engineer notice one waiting agent, move focus to it from
the keyboard, inspect the request, and choose a safe next action without losing
the state of five other busy surfaces. It is a product interaction test and a
framework decision gate, not a decorative dashboard.

## Current-run audit

The first 2026-08-31 GPUI baseline proved six-surface density but gave every
pane equal visual priority. The current slice replaces that dashboard with one,
three, or five cmux-style vertical panels according to available width. Every
panel owns its own 20% context region, 60% work surface, and 20% decision shelf.
Keyboard focus, command-palette input, live PTY input, styled VT cells, cursor
shapes, geometry-driven resize, and retained-history navigation are wired.
Remaining visible gaps are terminal text selection and mouse modes, real
decision-shelf actions, usage-detail provenance, and end-to-end platform
accessibility/IME.

Panel lifecycle is now visible in the slice: every panel has a Detach action,
the workspace bar has Add panel, and the sidebar exposes Detached sessions for
reattachment. The wording is deliberate because panel removal keeps its session
alive; termination is not exposed as a visually equivalent close action.

Screenshots for the audit are stored outside Git under
`~/shots/2026-08/lumbridge-ui-audit/`. Accessibility and IME correctness cannot
be established from screenshots and remain explicit runtime gates.

## Preserved design language

- Near-black blue surfaces with one cool-blue action accent.
- Thin borders and compact spacing; no elevated card shadows.
- Text carries most hierarchy. Color is supplementary and never the only state
  signal.
- Monospace content inside terminal surfaces; system UI typography elsewhere.
- Dense information, but only the focused or waiting surface becomes prominent.

## Orca reference, translated for Lumbridge

The visual reference is the MIT-licensed Orca repository at researched commit
`02a7742406a5a84fb372d6255d5a4367421990bd`. Its screenshots are product
research, not source assets for Lumbridge. We adapt these interaction patterns:

- a worktree/task-first sidebar whose rows show state without becoming large
  cards;
- a quiet top tab strip for mixed terminal, Markdown, browser, and review
  surfaces;
- a small responsive number of self-contained vertical panels, instead of
  either one ultrawide terminal or a dense equal-card dashboard;
- narrow contextual tools, such as files, review, or Buzz, that can collapse
  when the terminal needs the space;
- usage and agent state at the edge of the workspace rather than in modal
  account pages.

Lumbridge deliberately differs where its product model differs: remote runtime
ownership is always visible, `needs input` receives a dedicated attention path,
usage includes provenance and uncertainty, and Buzz is a signed collaboration
surface rather than a hosted Lumbridge control plane.

## Visual hierarchy

1. The top bar names the current workspace, repository/branch, and command
   palette shortcut.
2. The sidebar starts with a compact `ATTENTION` group, followed by workspaces
   and remote hosts. It does not become a notification feed.
3. The top 20% of every visible panel keeps that pane's identity, surfaces,
   execution target, context, goal, and state visible; the selected panel
   receives the accent treatment.
4. A waiting pane uses an amber semantic label in both its panel context region
   and the attention sidebar. The label always includes words such as
   `NEEDS INPUT`.
5. The middle 60% of every panel gives its terminal or work surface uninterrupted
   height. The selected panel alone owns keyboard input.
6. The footer groups connection state, selected-harness identity, usage-window
   provenance, and burn forecast into readable regions.
7. The selected pane has a quiet surface strip for Terminal, Browser, Tools,
   Context, Goal, and Review. Switching surfaces keeps one pane identity.
8. Every panel has a compact decision shelf below its work surface. It labels
   whether suggestions are inert or review is required; no choice is visually
   conflated with an approved action.

## Keyboard task flow

- `Alt+Arrow` or `Alt+h/j/k/l`: move selection through the pane topology while
  leaving ordinary terminal arrows and text available to the PTY.
- `Alt+1` through `Alt+6`: focus a pane directly while leaving terminal digits
  available to the PTY.
- `Alt+Shift+N`: add or reattach the next panel in the deterministic slice.
- `Alt+Shift+W`: detach the selected panel while its session keeps running.
- `Cmd+K` on macOS or `Ctrl+K` on Linux: open the command palette.
- `Shift+PageUp/PageDown`: move the selected live terminal through retained
  history; `Shift+Home/End` jumps to the history top/live bottom.
- Typing while the palette is open changes its query; arrows change the result;
  `Enter` runs it; `Escape` closes it and restores pane focus.
- `Enter` on a waiting agent opens its request detail. Approval remains a
  separate explicit action and is never triggered by focusing the pane.
- `Escape` closes transient UI before it changes workspace state.

Every command is represented by the shared interaction model so GPUI and Floem
receive the same state transitions and tests.

## Decisive workload

- Three terminal panes consume ordered output from independent local PTYs in a
  pane-indexed runtime registry while each deterministic tick updates the three
  non-terminal surfaces. One, three, or five are visible according to available
  width; the all-deterministic constructor remains available for framework
  comparison and replay tests.
- One pane enters and leaves `needs input` through a deterministic event.
- Markdown, browser-boundary, and review panes update counters without using a
  web application shell.
- The model records actions, revisions, six-surface updates, and bounded terminal
  line counts. Framework adapters label each measured timing stage explicitly;
  element-build timing is never presented as display-present timing.
- The PTY actor replaces exactly one synthetic stream without changing focus or
  layout contracts. Synthetic streams stay available for repeatable performance
  tests. Live bytes are parsed into VT state and coalesced native paint runs;
  deterministic fixture text makes no terminal-emulation claim.

## Hard gates

- Every focus movement and palette command is unit tested without a window.
- Focus and `needs input` remain distinguishable in monochrome screenshots.
- The current-GPUI input probe preserves composed Unicode and multi-codepoint
  graphemes. Real candidate-window placement still requires Linux/macOS testing.
- The accessibility tree names each pane, selected state, execution target, and
  waiting state.
- Six streams remain responsive while the palette is open.
- Closing the UI never implies that a runtime-owned session has stopped.