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 2026-08-31 GPUI baseline succeeds at calm density: the six surfaces are easy
to scan, typography is consistent, and local/remote targets remain visible. It
fails the task flow in four important ways:

1. all panes have equal visual priority, so `NEEDS INPUT` is too easy to miss;
2. no pane exposes visible keyboard focus or selection;
3. the command palette affordance has no interaction behind it;
4. status and usage text in the footer is too quiet to explain provenance or
   confidence at a glance.

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;
- one primary work surface with optional splits, instead of forcing every
  surface into an equal dashboard tile;
- 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 active pane receives a two-pixel accent edge plus a quiet tinted header.
4. A waiting pane uses an amber semantic label and remains visible when another
   pane is selected. The label always includes words such as `NEEDS INPUT`.
5. Pane headers expose title, execution target, harness state, and unread count
   in a stable order.
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. A compact decision shelf may show local-analyst choices below the work
   surface. It labels its model/provider, trace scope, and whether suggestions
   are inert; no choice is visually conflated with an approved action.

## Keyboard task flow

- `Alt+Arrow` or `Alt+h/j/k/l`: move focus through the 2×3 pane grid 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.
- `Cmd+K` on macOS or `Ctrl+K` on Linux: open the command palette.
- 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

- In the first actor integration, one terminal pane consumes ordered output from
  a real local PTY while each deterministic tick updates the other five
  surfaces. 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. Raw lines do not claim terminal-emulation fidelity.

## 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.