# Spec: BSP pane layout (resize every pane in both dimensions)

Status: **draft / in progress** · Branch: `feat/bsp-pane-layout`

## Motivation

Today the window layout is two scalars over a *fixed* 3-pane arrangement
(`layout::Layout { pty_pct, roster_width, zoom }`):

- `pty_pct` — sandbox terminal's share of body **height** (chat takes the rest).
- `roster_width` — roster column **width** in cells.

Consequences the user hit:

1. **No sandbox → almost nothing adjustable.** `body_areas` only creates the
   chat/terminal vertical split `if app.sandbox.is_some()`. Without a sandbox the
   chat owns the whole body, so the only live dimension is the roster *width*.
   The `↑/↓` keys still call `grow_pty`/`shrink_pty`, but with no terminal pane
   to trade height against, nothing moves.
2. **Each pane is locked to one axis.** The terminal only changes height (always
   full width); the roster only changes width (always full height). You can't,
   e.g., make the terminal narrower or give the roster its own height.

Goal: let the user resize **each pane in both width and height**, using the
standard BSP (binary space-partition) pane-tree model (tmux/i3-style).
Researched in chat: ratatui core has no interactive-resize/BSP primitive (only
the Cassowary/`kasuari` solver + the "store-percent, mutate, re-solve" pattern);
the `ratkit` crate's `ResizableGrid` proves the BSP-tree approach. We roll a
small in-repo tree (option 2 from the research) so the PTY-resync integration
stays first-class and we take no new dependency.

## Model

Replace the two scalars with a binary tree. Leaves are the three *semantic*
panes; internal nodes are splits with an axis + ratio.

```rust
pub enum PaneKind { Chat, Roster, Terminal }

pub enum Axis { Horizontal, Vertical } // H: side-by-side (|), V: stacked (—)

pub enum Node {
    Leaf(PaneKind),
    Split { axis: Axis, ratio: u16, a: Box<Node>, b: Box<Node> },
    // `ratio` = percent of the split given to `a` (10..=90).
}

pub struct Layout {
    root: Node,
    zoom: Zoom,        // unchanged: Normal | Term | Chat (F4 fullscreen)
    roster_seed: u16,  // theme-provided default roster width, for rebuilds
}
```

### Default arrangement (reproduces today's look)

With a sandbox present:

```
Split(H, ratio=roster_split,            // left column | roster (right, full height)
   a = Split(V, ratio=chat_pct,         // chat (top) / terminal (bottom)
        a = Leaf(Chat),
        b = Leaf(Terminal)),
   b = Leaf(Roster))
```

Without a sandbox the Terminal leaf is absent, so the tree collapses to:

```
Split(H, ratio=roster_split, a = Leaf(Chat), b = Leaf(Roster))
```

The tree is rebuilt (preserving ratios where possible) when the Terminal pane
appears (`/sbx launch`) or disappears (`/sbx stop`), and when the roster is
hidden/shown. Ratios are stored as percentages and clamped to `[10, 90]`.

## Geometry (single source of truth)

`layout.rs` owns recursive area computation; `ui.rs::body_areas` becomes a thin
wrapper so `draw` and `pane_at` keep sharing one geometry.

```rust
pub struct Regions {                 // computed for a given body Rect
    pub panes: Vec<(PaneKind, Rect)>,// one per visible leaf
    pub dividers: Vec<Divider>,      // for mouse hit-testing (phase 5)
}
pub fn regions(&self, body: Rect) -> Regions;
pub fn rect_of(&self, body: Rect, kind: PaneKind) -> Option<Rect>;
```

`Zoom::Term`/`Zoom::Chat` short-circuit `regions` exactly like today (one pane
fills the body; the other leaves are omitted).

## Resize semantics (keyboard)

A pane is selected via `F5` (cycle) or mouse click (`pane_at`). Then arrows
resize the **nearest ancestor split on the matching axis**:

- `↑` / `↓` → nearest ancestor `Split{axis: Vertical}` of the focused leaf;
  grow/shrink that leaf's side of the split.
- `←` / `→` → nearest ancestor `Split{axis: Horizontal}`.

This makes *every* pane adjustable on both axes wherever such an ancestor
exists. If no ancestor on that axis exists (e.g. only Chat+Roster, press `↑`),
emit a one-line hint instead of silently doing nothing — fixes consequence (1).

```rust
pub fn resize_focused(&mut self, pane: PaneKind, dir: Dir, step: u16) -> ResizeOutcome;
// ResizeOutcome::Moved | ::NoAxisHere  (caller turns the latter into a sys hint)
```

## PTY integration (the critical wrinkle)

Today `sbx_dims(term_w, term_h, pty_pct)` derives the PTY grid from the height
scalar and assumes **full width**. In the tree model the terminal can be any
rect, so the grid must come from the Terminal leaf's actual `Rect`:

```rust
fn sbx_grid(term_w: u16, term_h: u16, layout: &Layout) -> Option<(u16, u16)> {
    let body = body_rect(term_w, term_h);          // minus top bar + input
    layout.rect_of(body, PaneKind::Terminal)
        .map(|r| (r.height.saturating_sub(2).max(1), r.width.saturating_sub(2).max(1)))
}
```

Every existing `sbx_dims(...)` call site (run loop ~926, command handlers
~1865/1971) switches to `sbx_grid`, and `announced_dims = None` still forces a
re-sync after any resize — so the shared PTY rebroadcasts new dims to the room
exactly as before. **This now also lets terminal *width* changes propagate**,
which the old code couldn't express.

## Persistence (presets)

`/layout save|load|list|rm|reset` keep working; the on-disk TOML now serializes
the tree instead of two scalars (`layouts/<slug>.toml`). Old single-scalar
preset files are not migrated (presets are throwaway; `reset` rebuilds default).
`serde` derives on `Node`/`Axis`/`PaneKind` handle (de)serialization.

## Out of scope (phase 5, optional, follow-up)

- **Mouse-drag dividers.** `Regions.dividers` + `hit_threshold` are scaffolded
  now; drag handling (hover highlight, `dragging_split`) lands later. Keyboard
  resize is the phase-1..4 deliverable.
- Arbitrary user-created splits / moving a pane to a new position. The tree
  supports it, but the UI only exposes the three named panes for now.

## Work plan

1. **layout.rs** — tree types, default/rebuild builders, `regions`/`rect_of`,
   `resize_focused`, clamps, zoom, `describe`, serde, presets. Unit tests
   (geometry sums to body, resize honors clamps, no-axis case, serde round-trip,
   sandbox add/remove rebuild).
2. **ui.rs** — `body_areas`→tree `regions`; `pane_at` via `regions`; draw each
   leaf; `edit_decor` marker on the focused pane.
3. **app.rs** — `sbx_grid` replaces `sbx_dims`; key handler resizes both axes via
   `resize_focused` (+ hint on `NoAxisHere`); `cycle_focus` over *present* panes;
   F4 zoom + `announced_dims` re-sync unchanged.
4. **docs** — in-app `/help` LAYOUT cluster + README "Window layout" updated to
   describe both-axis resize and the no-axis hint.
5. *(optional)* mouse-drag dividers.

## Acceptance

- `cargo test` green; `cargo build` warning-free.
- No sandbox: selecting Chat and pressing `←/→` resizes vs. roster; `↑/↓` prints
  the "no pane to trade height with — launch a sandbox" hint.
- Sandbox up: Chat/Terminal resize in **both** axes; roster width still works;
  terminal width changes now re-sync the PTY grid to the room.
- `/layout save` + `/layout load` round-trips the new tree.
- F4 fullscreen + `Ctrl+R` reconnect re-announce unchanged.