atrium — Docs
docs/concepts/panes.md

Panes and the tiling mosaic layout

How atrium tiles terminals, agents, editors, and browsers into one room — splits, subtabs, drag-to-rearrange, and the pane lifecycle.

Inside a room, panes are arranged in a mosaic — a binary tree of horizontal and vertical splits, with panes at the leaves. You can split, swap, resize, maximize, and group panes without leaving the keyboard. The Glossary explains how panes, subtabs, and rooms relate.

Splitting

Keyboard examples below use macOS notation. See Shortcuts for Windows bindings.

  • Cmd+D splits the focused pane right (horizontal split — new pane to the right).
  • Cmd+Shift+D splits the focused pane down (vertical split — new pane below).
  • Drag a pane header onto another pane's edge to drop into that zone (left, right, top, bottom).
  • Drop onto the center of another pane's header to stack the pane as a subtab.

Resizing, swapping, equalizing

  • Drag split dividers with the mouse or trackpad.
  • Right-click a split divider for Swap, Equalize, and Lock/unlock.
  • Maximize a pane (double-click its divider or use the pane header menu) to hide siblings. Restore with the same action.

Focus and navigation

  • Cmd+[ / Cmd+] cycle focus to the previous / next pane within the room.
  • Click any pane to focus it. The focused pane shows a subtle accent ring.
  • atrium pane focus <id> from the CLI.

Subtabs

Panes can be grouped under one header slot. Drop a pane onto another pane's header to stack them, or choose New Subtab from the Pane menu.

  • Click a subtab to switch to it.
  • Drag a subtab within its strip to reorder it, or out to a split, another group, a room, a wing, or a sidebar dock. Dropping it on a composer inserts a reference.
  • Close a subtab with the × button; the group stays alive as long as another subtab exists.
The grouped tile's header represents the whole group. Drag that header to move every member together, or right-click it for New subtab, split, maximize, move to a new room, and Close group. Closing a group asks once for its members. A sidebar resident holds one pane, so dock an individual subtab rather than the whole group. While a room is maximized, subtab dragging only reorders the strip.

Room rows and Activity cards can also be dragged onto a pane's edge to make a split, or its center to add a subtab. A drop on the chat composer inserts a reference to the item instead.

Pane identity

Each pane has an immutable UUID. The pane header displays an auto-generated title (for example editor: main.rs or Claude Code — session abc123). Override it with atrium pane rename <id> --name <name>; the custom title is persisted with the pane.

Lifecycle

  • Create — opened by a keyboard shortcut, drag gesture, launcher action, or atrium pane create.
  • Hide — a pane that sits in a room other than the active room is kept in the DOM so its state (scrollback, editor buffer, running process) survives instant switching.
  • Unmount — after 10 seconds hidden, a pane's React components are unmounted to free memory. State is preserved and restored on remount.
  • Close — Cmd+W or atrium pane close <id>. Closing a pane with unsaved changes or a running process prompts for confirmation.
  • Error isolation — a crash in one pane does not propagate to other panes or the app shell.

Popout

Any non-browser pane can be popped out of the mosaic into a floating overlay layered above the mosaic but below toasts and dialogs. The pop-out button lives in the pane header; once detached, the pane keeps the same header (focus ring, split, search, close) so it behaves exactly like an in-mosaic pane — just floating. Popped panes can be docked back, hidden, or shown all-at-once via Expose mode. Position, size, and which panes are out persist across restarts. See Shortcuts → Pane popout for the full keyboard surface.

Persistence

The entire mosaic tree for each room is serialized to that room's snapshot. Pane-specific state (cwd, scrollback, session ID, editor buffer position, browser URL and history) lives in per-pane JSON inside the project snapshot. See Persistence & recovery.

File drop

Drag a file from Finder onto atrium:

  • Dropped on the app with no existing pane for that file → opens an editor pane for it.
  • Dropped on a pane's header → opens the file as a subtab under that header.
  • Dropped on a pane's edge zone → opens the file as a new split.
atrium intercepts macOS drag-and-drop at the OS level; some web drag events do not fire. The UI uses pointer events to preview drop zones.