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.

Keyboard task flow

• Arrow keys or h/j/k/l: move focus through the 2×3 pane grid.
• 1 through 6: focus a pane directly.
• 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

• One deterministic tick invalidates all six surfaces and appends bounded output to the three terminal panes. Framework adapters consume the same event trace.
• 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.
• A later PTY adapter replaces one synthetic stream without changing the UI contract. Synthetic streams stay available for repeatable performance tests.

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.