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 a
3×1 default: 20% context and pane selection, 60% active work surface, and 20%
decision shelf. Keyboard focus, command-palette input, live PTY input, styled VT
cells, cursor shapes, and geometry-driven resize are wired. Remaining visible
gaps are terminal selection/scrollback, real decision-shelf actions, usage-detail
provenance, and end-to-end platform accessibility/IME.

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. A compact top 20% context band keeps all pane identities and states visible;
   the selected pane receives the accent treatment.
4. A waiting pane uses an amber semantic label in both the context band and
   attention sidebar. The label always includes words such as `NEEDS INPUT`.
5. The middle 60% gives the selected terminal or work surface uninterrupted
   reading space and retains target, harness state, dimensions, and surface tabs.
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 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.
- `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 offscreen. 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.