This page is part of Splay's manual. Read it with its figures and navigation at https://shawntz.github.io/splay/concepts/.

Concepts

Seven nouns. The rest of the manual is verbs.

Workspace

A numbered native Space. workspaces = 5 gives you 1 to 5 across every display, and workspace 3 switches there. Each workspace has its own layout.

1 2 3 4 5 main secondary
Two displays, five workspaces, two showing.

A workspace lives on one display: the main one, unless [workspace-to-display] says otherwise. When its display leaves, it moves to the main one, windows and all, and moves back when the display returns.

Window

Tiled, floating or fullscreen.

tiled tiled tiled floating fullscreen
layout floating tiling toggles the first two, fullscreen the third.

Tiled windows share the workspace. A floating window sits where you put it, over the tiles. Fullscreen fills the workspace, above the tiles, or the share of its width fullscreen-width gives it; it is not macOS full screen. Dialogs, sheets and panels float on their own. A rule decides for anything else.

Tree

A tiled workspace is a tree. Containers lay their children along one axis, as tiles or as an accordion. The leaves are windows. In the default scrolling layout the root is the strip, and its children are the columns.

Ghostty Safari Mail Notes
workspace · tiles ↔
├── Ghostty
└── tiles ↕
    ├── Safari
    └── accordion ↔
        ├── Mail
        └── Notes
Three containers, four windows.

focus, move and join-with walk and edit it. layout sets a container’s mode and axis. flatten-workspace-tree starts over from the config.

Display

A display is matched by pattern: main, secondary, or part of its name as splay list-displays prints it. Patterns choose where a workspace lives, a display’s gaps, and a workspace’s layout while it is on that display.

[workspace-to-display]
5 = 'secondary'

[display.main]
gaps.outer.top = 44

[workspace.2.display.built-in]
layout = 'accordion'

Focus

One window has focus, and its border says so. focus left and friends move it to the nearest window that way, or in the strip to the window last focused in the column that way; with --boundaries all-monitors-outer-frame, across the display edge too. [focus-follows-mouse] moves it with the pointer instead. When the focused window closes or is minimized and macOS leaves no key window, focus goes to its workspace’s next tile. A close also repairs a redirect of the same app’s key window to another display. The next tile is the same one shown by an accordion or focused after moving a window away. This also applies when quitting the focused app removes its window and leaves no key window. A later key, click, focus command or Space switch takes precedence; dragging and merging tabs does not pull focus back. Another app’s key window, or a key window on the original display, is left alone. Empty workspaces and native full-screen Spaces have no tile to focus.

The input snapshot is taken when the departure is observed. A minimize that macOS redirects to the app’s window on another display is left alone: a late minimize notification cannot distinguish that redirect from the user’s click on that window. Minimize repair only replaces no key window or the still-reported leaving window. With a delayed notification, an earlier Escape or desktop click may not cancel that repair. Pointer movement and scrolling alone do not cancel it; focus-follows-mouse takes precedence when it actually focuses another window. Hiding an app does not trigger close/minimize repair.

Known limits on macOS 27: when departure ownership cannot be established, a same-app cross-display close redirect and a close through a discard sheet or alert are left alone. The separate alert can own the key window rather than its document. Focus stays where macOS put it; Splay does not infer ownership from an unconfirmed focus loss.

Rule

When a window opens, every [[rules]] entry that matches it runs, in order. layout floating and layout tiling decide before the window is placed. Any other command runs on it afterwards.

[[rules]]
app-id = 'com.apple.Music'
run = ['layout floating', 'move-window-to-workspace 5']

Mode

Key bindings live in modes, one active at a time. Splay starts in main. mode service switches to the bindings in [mode.service] until a binding there switches back.

[mode.main]
alt-shift-semicolon = 'mode service'

[mode.service]
esc = ['reload-config', 'mode main']
r = ['flatten-workspace-tree', 'mode main']

The menu bar menu lists each command with its key in the current mode.