BSP Tiling

Automatic Binary Space Partitioning window layout with manual control

Overview

TUIOS implements automatic window tiling using Binary Space Partitioning (BSP), an algorithm that recursively divides screen space to fit windows efficiently. Unlike rigid grid-based tiling, BSP adapts to any number of windows and allows fine-grained control over splits.

Throughout this guide, Ctrl+B refers to the default leader key. This is configurable via the leader_key option in your config file.

Key Advantages

Flexible Layout

Works with any number of windows, not limited to powers of 2

Custom Sizing

Each window can have a different size based on your needs

Manual Control

Full control over split direction at any level of the tree

Persistent State

Per-workspace configuration survives sessions

Enable Tiling

Toggle tiling mode in Window Management Mode:

t                    # Toggle tiling on/off
Ctrl+B Space         # Alternative: prefix + Space
Ctrl+B t t           # Via tiling prefix menu

The status bar shows “TILING” when enabled.

Auto-Tiling Behavior

When tiling is enabled, TUIOS automatically positions new windows:

1. First window: Takes full screen
2. Second window: Splits vertically (side-by-side)
3. Third window: Splits horizontally (top/bottom on right side)
4. Fourth+ windows: Spiral pattern (alternating V/H splits)

This spiral layout balances screen space naturally as you add windows.

The dock shows the next split direction when tiling is active: V (vertical) or H (horizontal). This helps predict where the next window will appear.

BSP Concepts

The Split Tree

Internally, TUIOS maintains a binary tree for each workspace:

Root Split (Vertical)
├── Window 1 (left half)
└── Split (Horizontal)
    ├── Window 2 (top-right quarter)
    └── Window 3 (bottom-right quarter)

Each split has:

• Direction: Vertical (left/right) or Horizontal (top/bottom)
• Ratio: How space is divided (default 0.5 = 50/50)

Per-Workspace State

Each workspace maintains its own BSP tree. Switching workspaces preserves the tiling configuration on both sides.

See Workspaces for details on multi-workspace usage.

Manual Split Control

Rather than relying on automatic placement, you can manually split the focused window:

Create Splits

Ctrl+B -             # Split horizontally (current window → top/bottom)
Ctrl+B | or \        # Split vertically (current window → left/right)

This divides the focused window’s space in half, placing the focused window in one half and preparing space for a new window in the other half.

1. Create first window

   Press n in Window Management Mode

2. Split it vertically

   Press Ctrl+B |

3. Create new window

   Press n - appears in right half

4. Focus left and split horizontally

   Press Tab to focus left window, then Ctrl+B -

5. Create third window

   Press n - appears below left window

Result: Three windows in an L-shaped layout.

Rotate Split Direction

Change an existing split’s direction:

Ctrl+B R             # Rotate split at focused window

This toggles the split containing the focused window between vertical and horizontal.

Before

┌─────┬─────┐
│  A  │  B  │
└─────┴─────┘
Vertical split (side-by-side)

Preselection

Preselection lets you control where the next window spawns relative to the focused window.

Preselection Commands

Alt+h                # Next window appears left of focused (Linux)
Alt+l                # Next window appears right of focused
Alt+k                # Next window appears above focused
Alt+j                # Next window appears below focused

On macOS, use Option+h/j/k/l instead of Alt.

After preselecting, create a window normally with n. The preselection is consumed and resets.

Preselection Workflow

Creating a sidebar layout:

1. Start with one window

   Press n to create initial window

2. Preselect left

   Press Alt+h (or Ctrl+B Shift+H)

3. Create narrow sidebar

   Press n - new window appears on left

4. Resize sidebar

   Press < multiple times to make sidebar narrow

5. Focus main window and preselect below

   Press Tab then Alt+j

6. Create terminal below

   Press n - appears below main area

Result: Sidebar on left, main area on right with terminal below it.

Preselection is particularly useful for:

• Creating asymmetric layouts
• Building UI patterns (sidebar + main + footer)
• Inserting windows into specific locations in complex layouts

Window Swapping

Rearrange windows without changing the underlying split structure:

Swap Commands

Shift+H or Ctrl+Left      # Swap with window to the left
Shift+L or Ctrl+Right     # Swap with window to the right
Shift+K or Ctrl+Up        # Swap with window above
Shift+J or Ctrl+Down      # Swap with window below

Swapping exchanges two windows’ positions in the BSP tree while preserving their sizes.

Focus vs Swap:

• h/j/k/l or arrow keys: Move focus between windows
• Shift+H/J/K/L or Ctrl+arrows: Swap windows

Mouse users can drag windows in tiling mode - dragging one window onto another swaps them.

Resizing in BSP Mode

BSP allows resizing along any split boundary.

Master Ratio Adjustment

Control the size of the main window area (typically the leftmost window):

> or Shift+.             # Grow master area (from right edge)
< or Shift+,             # Shrink master area (from right edge)

. (period)               # Grow master area (from left edge)
, (comma)                # Shrink master area (from left edge)

Adjustment increment: 5% per keypress.

Height Adjustment

Control the vertical split ratio of the focused window:

} or Shift+]             # Grow height (from bottom edge)
{ or Shift+[             # Shrink height (from bottom edge)

] (right bracket)        # Grow height (from top edge)
[ (left bracket)         # Shrink height (from top edge)

Edge-Based Resizing

The distinction between edges matters in complex layouts:

Right Edge (< / >)

Moves the right boundary of the master area, affects right-side windows

Left Edge (, / .)

Moves the left boundary of the master area, affects left-side windows

Bottom Edge ({ / })

Moves the bottom boundary of focused window

Top Edge ([ / ])

Moves the top boundary of focused window

This allows fine control in complex layouts where multiple splits exist.

Equalize Splits

Reset all splits to equal proportions:

Ctrl+B =                 # Equalize all splits

This sets all split ratios to 50/50 throughout the entire tree, giving all windows equal space based on their position.

Useful when you’ve made many resize adjustments and want to start fresh with balanced spacing.

Practical Workflows

Workflow 1: Development Environment

Classic three-pane layout (editor + terminal + logs):

# Start tiling
t

# Create editor window
n
i
vim main.go
Ctrl+B d

# Preselect right for terminal
Alt+l    # or Ctrl+B Shift+L
n
i
go run .
Ctrl+B d

# Focus terminal and preselect below for logs
Tab
Alt+j    # or Ctrl+B Shift+J
n
i
tail -f logs/app.log

Result:

┌──────────┬──────────┐
│          │ Terminal │
│  Editor  ├──────────┤
│          │   Logs   │
└──────────┴──────────┘

Workflow 2: Wide Monitor Layout

For ultrawide monitors, create a three-column layout:

t
n                        # First window (full)
Ctrl+B |                 # Split vertically
n                        # Second window (right)
Tab                      # Focus first (left)
Ctrl+B |                 # Split left side vertically
n                        # Third window (middle)

# Adjust widths for 1:2:1 ratio
Tab Tab                  # Focus rightmost
<<                       # Shrink right column
Tab Tab                  # Focus leftmost  
..                       # Shrink left column

Result: Left sidebar, main area, right sidebar.

Workflow 3: Dashboard Grid

Four equal quadrants:

t
n  # Create 4 windows quickly
n
n
n
Ctrl+B =                 # Equalize all splits

Result:

┌─────┬─────┐
│  1  │  2  │
├─────┼─────┤
│  3  │  4  │
└─────┴─────┘

Workflow 4: CI/CD Monitor

Vertically stacked log viewers:

t
n                        # First log
Ctrl+B -                 # Split horizontally
n                        # Second log
Ctrl+B -                 # Split horizontally again
n                        # Third log
Ctrl+B =                 # Equal height

Result: Three equal horizontal strips.

Remote Control

Control tiling via CLI for automation:

# Toggle tiling in running session
tuios run-command ToggleTiling

# Enable tiling
tuios send-keys t

# Create window, split, and position
tuios run-command NewWindow "editor"
tuios send-keys "ctrl+b,|"
tuios run-command NewWindow "terminal"

# Equalize splits
tuios send-keys "ctrl+b,="

Implementation Details

Source Code

BSP implementation is in internal/layout/bsp.go:

• TileNode struct - Binary tree node with split type and ratio
• InsertWindow() - Auto-placement using spiral scheme
• RemoveWindow() - Tree cleanup when windows close
• ApplyLayout() - Recursive rectangle calculation

Workspace tiling state is managed in internal/app/workspace.go:

• TileVisibleWorkspaceWindows() - Tiles only the current workspace
• WorkspaceTrees[workspaceNum] - Per-workspace BSP trees
• WorkspaceHasCustom[workspaceNum] - Manual split tracking

Automatic Scheme

Default scheme: SchemeSpiral (spiral pattern).

When auto-tiling:

1. First window → root leaf
2. Second window → root becomes vertical split, two leaves
3. Third+ windows → finds the largest window, splits it (alternating directions)

Split Ratio Storage

Each internal node stores a ratio (default 0.5):

• Represents the fraction of space given to left/top child
• Range: 0.3 to 0.7 (enforced to prevent unusable layouts)
• Adjustable via resize commands

State Persistence

In daemon mode, BSP state is serialized and restored across sessions:

• Tree structure
• Split ratios
• Custom layout flags
• Master ratios

See Sessions for persistence details.

Troubleshooting

Windows Not Tiling

Check tiling is enabled

Status bar should show “TILING”. Press t to toggle.

Check workspace

Each workspace has independent tiling state. Try pressing t on the current workspace.

Too many windows

BSP handles any number of windows, but with 10+ windows, individual window size becomes impractical. Consider using multiple workspaces.

Unexpected Layout After Resize

Reset to balanced layout:

Ctrl+B =                 # Equalize all splits

Verify focused window: Resize operations affect the split containing the focused window. Make sure the correct window is focused.

Swap Not Working

Check direction: Swap commands are directional. If there’s no window in the specified direction, nothing happens.

Try mouse drag: Mouse dragging always swaps if you drag one window onto another.

Preselection Not Applied

Preselection is one-time: After creating a window, preselection resets. You need to preselect again for the next window.

Cancel preselection: Press Esc in Window Management Mode to cancel a preselection without creating a window.

Related Documentation

• Workspaces - Each workspace has independent tiling state
• Keybindings - Complete keybinding list for tiling
• Configuration - Customize tiling behavior
• Architecture - Technical details on BSP implementation

Comparison with Other Tiling Algorithms

BSP vs. Grid

Grid Tiling

• Fixed positions (1, 2, 3, 4… windows)
• Wasted space with odd numbers
• Predictable but inflexible

BSP Tiling (TUIOS)

• Recursive splits adapt to any number
• No wasted space
• Full control over layout

BSP vs. Manual Tiling

Some window managers require you to manually tile every window. TUIOS offers both:

• Auto-tiling for quick layouts
• Manual splits and preselection for precise control

You can mix approaches: start with auto-tiling, then use manual splits to refine.