Intelligence Modes

PaneLayoutIntelligenceMode is a coarse-grained preset that tells the layout planner what the user is trying to do right now. It is not a theme or a skin — it changes the math that decides which pane shrinks first, which splits are collapsible, and how aggressively the planner normalizes ratios.

The four modes

pub enum PaneLayoutIntelligenceMode {
    Focus,
    Compare,
    Monitor,
    Compact,
}

Where modes live in the stack

  User presses the cycle key / right-clicks the pane header
                         │
                         ▼
           runtime layer picks a new mode
                         │
                         ▼
      PaneTree::plan_intelligence_mode(mode, anchor_id)
                         │
                         ▼
           returns Vec<PaneOperation> — usually
           a sequence of SetSplitRatio + NormalizeRatios
                         │
                         ▼
      caller applies each op through the journaler
                         │
                         ▼
           tree reshapes; timeline records the reshape

The planner returns operations, not rectangles. This preserves the invariant that every layout change is a journaled operation — modes are not a “secret mutation” channel.

Right-click cycling

The showcase and reference UIs bind the intelligence mode to a right- click on the pane title bar (or a keybind like Ctrl-Shift-M). Cycling order is the declaration order above: Focus → Compare → Monitor → Compact → Focus …. Each transition runs plan_intelligence_mode with the currently-focused pane as the anchor.

What each mode actually does

Focus

The anchor pane grows to take as much space as its constraints allow. Siblings contract to their minimums. If sibling constraints have collapsible = true, they are candidates for removal in a subsequent normalization pass.

  Before (equal thirds):        After Focus on middle:

  ┌───┬───┬───┐                 ┌─┬───────┬─┐
  │ A │ B │ C │                 │A│   B   │C│
  └───┴───┴───┘                 └─┴───────┴─┘

Compare

The anchor pane and its immediate sibling are resized to a 50/50 split; all other ratios are normalized to reduced form. Useful for diff views and A/B comparisons.

  Before:                       After Compare on B:

  ┌───┬─┬───────┐               ┌─────┬─────┐
  │ A │B│   C   │               │  A  │  B  │
  └───┴─┴───────┘               └─────┴─────┘
   (C may close if collapsible)

Monitor

Reserves the top of the layout for a strip pane (a ticker, a live metric, a log tail) and gives the rest of the vertical budget to the main content. The anchor is the “main content” pane; the strip is the ancestor split at axis Horizontal if present.

  ┌────────────────────────┐    ← ticker strip, minimum height
  ├────────────────────────┤
  │                        │
  │    primary viewport    │    ← anchor; grows to fill
  │                        │
  └────────────────────────┘

Compact

Lowers all minimums to the smallest render-safe value, enables the collapsible flag on non-anchor panes, and normalizes ratios. Used on very narrow terminals or when the user signals “give me more of something I care about.”

Worked example

use ftui_layout::pane::{PaneLayoutIntelligenceMode, PaneTree};
 
let mut tree = /* build some tree */;
let anchor = tree.focused_leaf().unwrap();
 
let ops = tree.plan_intelligence_mode(
    PaneLayoutIntelligenceMode::Focus,
    anchor,
);
 
for (i, op) in ops.into_iter().enumerate() {
    tree.apply_operation((i as u64) + 1, op)?;
}

The planner can return zero operations if the tree is already in the shape the mode wants. That’s a valid outcome — the caller should not fabricate a cosmetic operation just to have something to journal.

When is each mode actually useful?

Pitfalls

Where to go next