lumbridge-code/docs/decisions/0021-sidebar-composition.md

0021: The sidebar answers four questions, and its layout is data

Status: accepted; rebuilt and live.

The old rail showed a frozen ATTENTION · 1 over a five-entry worktree list naming a developer's machines, and a Buzz card asserting a connection to a crate the binary did not depend on. All of that is gone (decision 0018's commit and the truth pass before it). What replaces it starts from a question rather than from a list of things we happened to know.

The four questions

A workspace multiplexer's rail exists to answer, in this order:

1. What needs me? — NEEDS YOU
2. What am I running? — WORKSPACE
3. What did I set aside? — DETACHED
4. Where does it run, and what will stop me? — HOSTS, QUOTA

Anything that answers none of those does not belong in the rail. That is the test the worktree list failed, and it is the test any future addition has to pass.

WORKSPACE is deliberately flat. A Repository → Worktree → Pane tree is the obvious shape and every level above Pane would be a second fixture, because lumbridge-git does not exist. The depth field and the disclosure column are reserved so the tree can arrive without moving every row.

Layout is data

sidebar/model.rs holds no renderer types. flatten(&SidebarInput, &SidebarState) -> Vec<SidebarRow> is a pure function, so which sections exist, what collapsing hides, what the filter keeps and where the keyboard cursor lands are ordinary tests in CI. sidebar/view.rs renders and decides nothing.

Two rules that came out of writing the tests rather than the view:

• The cursor is a RowKey, not an index. An index is wrong the moment a row above it disappears — a pane exits, a filter narrows — and quietly pointing at a different row than the one the user was looking at is worse than losing the cursor. An unknown key restarts at the top.
• Every header renders, even for an empty section, and every empty section says what empty means. Positions then never move under the pointer because something appeared above.

The empty state under a filter is "No match in this section" and does not quote what was typed. The sidebar is the part of the window that gets screenshotted and shared.

One selection language

Rest transparent, hover surface_raised, selected surface_active, keyboard cursor a one-pixel border — accent when the rail has the keyboard, border when it does not. Before this the attention cards darkened on hover while the worktree rows lightened, so the same gesture meant two different things a hundred pixels apart.

Every row has the same slots — disclosure, indicator, kind, label, meta — always reserved. A row that omitted its indicator column pulled its label left and broke the vertical line the eye follows.

One indicator per row, by precedence: faulted, then waiting, then quota nearly spent, then finished, then working. A row showing two of those tells you to look, which you already knew, and hides which one to act on.

What the layout work actually caught

Flexbox shrinks proportionally, so the longest string wins. The attention row's reason is longer than its title, and the row rendered as Te… Exited with code 7 · observed — it had thrown away the one word that says which pane to look at. Titles now carry a minimum width and the meta yields first. Three quota rows all read CLAUDE CODE with the scope truncated off the end, naming the same thing three times and identifying none of them; the harness name is now printed once per group, as the footer already did.

Both were found by screenshot, not by review.

The keyboard

secondary-alt-b toggles, secondary-alt-s moves the keyboard into the rail, secondary-alt-a jumps to the next pane that is certainly waiting. Inside the rail, arrows and j/k move, space peeks and stays, enter activates and hands the keyboard to what it opened, escape leaves.

The critical part is a guard, not a feature: on_key_down returns before it encodes anything for a terminal while the sidebar owns the keyboard. Without it a bare j would be written into whatever pane happened to be selected while the user believed they were walking a list.

Resizing

The rail drags between 200 and 480 pixels, applied live. Widening it really can drop the workspace from three panes to one, because decision 0009 measures its thresholds after the sidebar — that is correct, and hiding it until release would make the result look like a bug. The PTYs are told once, on release: a resize per mouse-move would be a SIGWINCH storm through the runtime's bounded queues.

The drag is owned by the root element rather than by the handle. A child that only sees events inside its own five pixels cannot follow a pointer across the window.

Not in this pass

• Persistence. Width, collapsed sections and visibility return to defaults on restart. They belong in their own snapshot, separate from the workspace blob so the two fail closed independently.
• Virtualisation. The list renders every row. At the number of panes a person has open this is not measurable; it becomes real when a host has fifty.
• HOSTS beyond the local machine. Two states only, live or not. Connecting, retrying and unreachable are unbuildable until lumbridge-remote exists, and shipping them would be the Buzz card again in a Rust enum.
• Accessibility. describe produces the sentence for each row and is tested; there is nothing to attach it to until the adapter in decision 0017 lands.

Behaviour studied

Zed's project panel (GPL — behaviour only, no code read for reuse), Zellij's cursor clamping after deletion (MIT), bb's thread-list indicator precedence (MIT), Orca's host list (MIT). Nothing was copied; the row anatomy, the precedence chain and the key-cursor rule are convergent answers to the same problems.