Files
lumbridge-code/docs/UX_VERTICAL_SLICE.md
karti 3409cabb80
CI / rust (push) Successful in 2m10s
feat: add persistent dynamic panels
2026-08-31 18:43:36 -07:00

7.1 KiB
Raw Permalink Blame History

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 opens an Add Panel chooser for Terminal, Browser, Markdown, and Review, and the sidebar and chooser expose Detached sessions for reattachment. Created panels are inserted beside the selection and receive a monotonic identity persisted with their ordering and attachment state in local SQLite. 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: open the Add Panel chooser; 14 create a typed panel.
  • 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.

The six seed surfaces still replay through the shared interaction model so GPUI and Floem retain a comparable benchmark. Dynamic product panels use the GPUI panel registry until that contract moves into the framework-neutral UI crate.

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.