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.