Settings › Appearance › Layout brings the three panels back as an option beside the grid

[davidbudac]

The grid replaced the three panels in 0.34 and some people want the columns back; Settings › Appearance › Layout now switches between the GRID and the PANELS, live, with the grid still the default.

Contents: 1. The problem · 2. What changed · 3. How it looks · 4. How it works · 5. Risk · 6. Technical overview · 7. Notes

1. The problem

0.34 made the GRID the whole screen and removed the PROJECTS | WORKTREES | SESSIONS columns. The list layout (worktree_layout) helped, but #108 asks for the columns themselves, and so does a second reader there.

can we bring the old view as part of the "appearance" settings? — @kaminskypavel, #108

the list layout is better, but the previous column layout was just more intuitive — @cstromquist, #108

2. What changed

• A Layout row — pick the grid or the panels
  • Settings › Appearance › Layout: grid (default) or panels; layout in config.json
  • cycles live, no restart
  • the selected project, worktree and session carry across the switch, and so does the session in the pane
• The three columns — PROJECTS | WORKTREES | SESSIONS beside the TERMINAL PANE
  • PROJECTS lists every project and stands in for the PROJECT TABS
  • WORKTREES lists the checkouts, then OPEN PRS and ISSUES, each folding on a click
  • SESSIONS lists RECENT, TERMINALS, PULL REQUESTS and a folded ARCHIVED group
  • the footer breadcrumb reads project ▸ worktree ▸ session
• Keys and mouse — the panel walk, on the keys the grid already has
  • h/l and Tab cross the columns, j/k walk a column, Enter drills in and attaches
  • Space opens the FOLLOW-UP MODAL, ^F full-screens, Shift+A folds ARCHIVED, ]/[ walk attention
  • x, 1–9, +, ` and ^` have nothing to act on and the footer says so
  • a click selects a row, a second click is Enter; the wheel scrolls a column under a cursor that stays put, as the grid's does
  • ? lists the panels' keys while the panels are up
• Unchanged. With layout at grid — or absent — nothing draws or answers differently: every branch this adds tests App::panels.
• Not in the panels yet
  • draggable splitters and collapsible rails; the columns are 20 / 22 / 32 wide
  • recent-prompt lines under a session row, unread counts on a PR row
  • the cards' own extras: last prompt, line counts, the header's PR and issue counts, the pane's terminal strip
  • Settings › Hotkeys hints still use the grid's words
  • the ARCHIVED open state is shared, so leaving it open in the panels shows the archived list back on the grid

3. How it looks

The PANELS: three launches in api-server, the SESSIONS cursor on the one asking a question, live in the pane

? with the panels up: THE COLUMNS in place of the grid's cards and tabs

Captured with make shot SCENE=panels (and KEYS="?") at 190x50, rendered on Linux with DejaVu Sans Mono because the harness's Menlo path is macOS-only.

4. How it works

flowchart LR
  cfg["config.json: layout"] --> apply["apply_config"]
  apply --> flag["App::panels"]
  sel["sel_project / sel_worktree / sel_session"]:::shared
  flag -->|grid| lv["ui::launcher_view::draw"]
  flag -->|panels| pv["ui::panels_view::draw"]:::new
  sel --> lv
  sel --> pv
  key["handle_key"] -->|"launcher_grid()"| lh["launcher::handle_action"]
  key -->|"panels_active()"| ph["event_loop::panels::handle_action"]:::new
  ph -->|"falls through"| walk["panel walk kept under the grid: move_selection, focus_walk, activate"]
  walk --> sel
  wheel["mouse wheel"] --> cs["panels::ColumnScroll"]:::new
  cs --> pv
  classDef new fill:#1f6feb,color:#fff
  classDef shared fill:#8250df,color:#fff

Loading

5. Risk

Verdict: 🟢 Low risk — TUI only and opt-in; the grid's paths gain one boolean test each.

	Level	Why
🔒 Security & production	Low	no new surface: no ClientRequest, no PROTOCOL VERSION bump, no DAEMON, store or hook change, no new file written; one new string key in config.json
⚡ Performance	Low	grid frames add one App::panels test in draw_screen, handle_key, the wheel arm and draw_terminal; a panels frame builds three short line lists from the lists the grid already indexes
🧩 Fit with the codebase	Medium	follows the worktree_layout setting and the launcher / launcher_view module split, but it makes Focus::Projects / Focus::Worktrees and their key arms reachable again — the code #91's follow-up meant to delete — and the panels' help repeats about 25 lines of the grid's help text rather than restructure its tables

Rollback: git revert of the three commits; a layout key already written to a config.json is not removed by the revert.

6. Technical overview

• Mechanism. layout resolves to App::panels in apply_config. App::launcher_grid() gains && !self.panels, which by itself routes keys past the grid's handler to the panel match handle_key kept; App::panels_active() picks the draw. Both layouts read the same three cursors, so there is no second selection to keep in step. App::panels_scroll holds one ColumnScroll per column for the wheel.
• Files. crates/nebula-tui/src/panels.rs — the model: column widths, each column's lines, ColumnScroll; crates/nebula-tui/src/ui/panels_view.rs — the drawing, hit targets and the panels' help sections; crates/nebula-tui/src/event_loop/panels.rs — the grid-owned keys' panel meaning, row clicks, the wheel, 15 tests; crates/nebula-tui/src/config.rs — the layout key and its Appearance row; app.rs, ui.rs, event_loop.rs — branch points only, 93 added lines between them.
• Why not restore the old drawing from before 0.34. That code carried the Workspaces bar, splitter and rail state and three-row pills; this draws flat one-line rows on today's lists and helpers, so it stays in three new files.
• Why not a third worktree_layout value. That row lays out a band inside the grid; the panels replace the PROJECT TABS and the grid together.
• Gate. cargo fmt --all -- --check clean. cargo clippy -p nebula-tui --all-targets: 10 warnings, all on lines this does not touch, the same on main. Tests: cargo test --workspace --no-fail-fast on Linux: every suite passes (e2e_pty 29/29, nebula-daemon 304, nebula-core 33, nebula-tui lib 1257) except three tests that fail the same way without this branch — e2e_tui's tui_drag_past_the_pane_top_autoscrolls_and_copies_the_run and nebula_open_from_inside_a_session_raises_the_file_tabs fail on main at 0f98b95 too, and one of nebula-tui's ipc::tests::kill_stops_a_skewed_daemon_whose_pidfile_is_gone / branch_switch git tests fails intermittently under a parallel run and passes alone. Two more lib tests (question_mark_ignores_menus_without_session_rows, the_harness_picker_is_no_wider_than_its_rows_and_keeps_its_keys_in_the_footer) fail when the suite runs inside an SSH session, on main as well. Not run on macOS.

7. Notes

• Two commits of feature and one string fix over v0.42.0; no conflicts with main at 0f98b95.
• New tests: 19 unit tests in the panels modules, layout_defaults_to_the_grid_cycles_and_persists in config.rs, and two in e2e_tui.rs (tui_panels_walk_projects_worktrees_and_sessions, tui_layout_setting_switches_grid_and_panels_live).
• docs/configuration.md, docs/keys.md and docs/sessions.md follow; a panels scene joins the SCREENSHOT HARNESS.
• Workspaces are not part of this.
• Closes what happened to the new layout? #108.

🤖 Generated with Claude Code