Aqueous layout.toml Reference

# =============================================================================
# Aqueous layout configuration reference
# =============================================================================
#
# This optional sidecar keeps layout selection and geometry separate from
# wm.toml. Aqueous uses a small TOML-compatible parser: unknown sections, keys,
# and malformed values are ignored while recognized valid values are applied.
#
# Actual discovery order (first usable path wins):
#   1. ~/.config/aqueous/layout.toml, when $HOME is set and the file exists
#   2. $AQUEOUS_LAYOUT (~ is expanded)
#   3. [layout].path from wm.toml (relative to wm.toml)
#   4. $XDG_CONFIG_HOME/aqueous/layout.toml
#   5. /etc/xdg/aqueous/layout.toml
#
# The sidecar is applied after wm.toml. Recognized scalar and per-layout fields
# are merged one key at a time, so omitted values retain their wm.toml/default
# value. [[output]] and [[workspace]] layout mappings are also accepted here,
# but matching mappings already loaded from wm.toml are resolved first. Define
# each mapping in only one file to avoid ambiguous duplicates.
#
# Configuration is polled and hot-reloaded on the Wayland event loop. Super+R
# requests the same reload immediately.

# -----------------------------------------------------------------------------
# Global layout defaults
# -----------------------------------------------------------------------------
[layout]
# Layout used when there is no runtime, output, or workspace override.
# Accepted: tile | monocle | grid | rows | dwindle | reverse-dwindle |
#           reverse_dwindle | scrolling | float | floating | game-mode |
#           game_mode | composable
default = "tile"

# Common geometry applied to every layout. Layout-specific sections below can
# override any common field for one engine.
gaps_outer  = 8       # pixels around the usable output rectangle; >= 0
gaps_inner  = 4       # pixels between placements; >= 0
master_ratio = 0.55   # master share used by tile/dwindle/reverse-dwindle; strictly 0 < value < 1
master_count = 1      # number of windows in tile's master area; >= 1

# Border colors use 0xAARRGGBB.
border_width   = 2
border_focused = 0xFF88C0D0
border_normal  = 0xFF3B4252
border_urgent  = 0xFFBF616A

# Ask SSD-capable clients to use compositor-side decoration. CSD-only clients
# may continue to draw their own title bars.
force_ssd = false

# Optional when these settings live in wm.toml instead of this sidecar:
# path = "~/.config/aqueous/layout.toml"

# -----------------------------------------------------------------------------
# Runtime layout slots
# -----------------------------------------------------------------------------
# The set_layout_primary/secondary/tertiary/quaternary actions resolve through
# these four slots. Every slot accepts any layout ID listed above.
[layout.slots]
primary    = "tile"
secondary  = "scrolling"
tertiary   = "monocle"
quaternary = "grid"

# -----------------------------------------------------------------------------
# Composable regions
# -----------------------------------------------------------------------------
# Optional. Select `composable` as the default, a slot, or a workspace/output
# layout to divide that workspace into as many as four independent layouts.
# Region names are fixed: a, b, c, and d. Unconfigured regions are disabled.
#
# Points are normalized [x, y] coordinates in the strut-adjusted usable output:
# p1 = top-left, p2 = top-right, p3 = bottom-right, p4 = bottom-left. The four
# points must describe a non-zero, axis-aligned rectangle in clockwise order.
# Regions may touch and may leave unused space, but must not overlap. Invalid or
# incomplete region configuration makes `composable` fall back to full-area
# `tile` placement.
#
# Child layouts may be tile, monocle, grid, rows, dwindle, reverse-dwindle, scrolling, or float.
# game-mode and composable cannot be nested. Each child retains independent
# ordering, scrolling, and floating state. A region is active whenever one of
# its windows has focus, and newly managed windows join that active region.

[layout.composable.a]
layout = "tile"
p1 = [0.0, 0.0]
p2 = [0.5, 0.0]
p3 = [0.5, 1.0]
p4 = [0.0, 1.0]

[layout.composable.b]
layout = "scrolling"
p1 = [0.5, 0.0]
p2 = [1.0, 0.0]
p3 = [1.0, 1.0]
p4 = [0.5, 1.0]

# Optional custom actions in wm.toml can target a region directly:
# [keybinds.custom]
# "Super+Alt+1"       = "builtin:focus_composable:a"
# "Super+Alt+Shift+1" = "builtin:move_to_composable:a"
# Region arguments also accept b/c/d or their numeric aliases 1/2/3/4.

# -----------------------------------------------------------------------------
# Per-layout options
# -----------------------------------------------------------------------------
# Every [layout.options.<leaf-id>] section accepts the eight common
# geometry/border keys from [layout]: gaps_outer, gaps_inner, master_ratio,
# master_count,
# border_width, border_focused, border_normal, and border_urgent.
# Unknown options are ignored; there is no generic Extra option map.

[layout.options.tile]
# Master/stack layout: the first master_count windows occupy master_ratio of
# the width; remaining windows form the stack.
master_ratio = 0.55
master_count = 1

[layout.options.monocle]
# Show only the focused/current window when true. false leaves every monocle
# participant visible in its full-output stack.
hide_others = true
# Draw the configured border around the visible window.
show_borders = false

[layout.options.grid]
# Grid has no engine-only keys; common gaps and borders control it.
gaps_inner = 4

[layout.options.rows]
# Rows has no engine-only keys; common gaps and borders control it.
gaps_inner = 4

[layout.options.dwindle]
# Fraction assigned to each recursive split, strictly between 0 and 1.
split_ratio = 0.5
# First split: vertical = left/right; horizontal = top/bottom.
start_axis = "vertical" # vertical | horizontal

[layout.options.reverse-dwindle]
# Horizontal mirror of dwindle: vertical splits start on the right while
# horizontal splits still start at the top.
split_ratio = 0.5
start_axis = "vertical" # vertical | horizontal

[layout.options.scrolling]
# Width of each scrolling column as a fraction of the usable output.
column_fraction = 0.5
# Automatically pan to keep the focused column centered.
center_focused = true
# Pan to a newly managed window when it extends the column order.
follow_new_windows = true
# Quantize manual viewport movement to whole column steps.
snap_to_columns = false
# Permit the first/last column to move beyond the centered viewport bound.
allow_overscroll = true
# Milliseconds of real pointer dwell before focus follows a scrolling member.
# Keyboard navigation and pointer clicks remain immediate. Zero disables delay.
focus_follows_mouse_delay_ms = 0

[layout.options.float]
# Floating has no engine-only keys. Common borders apply; each window otherwise
# uses remembered, native, or rule-provided geometry.
border_width = 2

[layout.options.game-mode]
# Only common geometry/border keys are accepted here. Game Mode's
# remainder_layout, fallback_layout, and gaps_inner policy lives in the
# [game_mode] section of rules.toml.
gaps_inner = 4

# -----------------------------------------------------------------------------
# Output layout selection
# -----------------------------------------------------------------------------
# Optional. These blocks select a default layout for matching outputs; display
# mode/scale/position fields belong in wm.toml. Matching priority is connector
# name, then EDID, then make/model/serial metadata.
#
# [[output]]
# name   = "DP-1"
# layout = "scrolling"
#
# [[output]]
# edid   = "edid-identifier"
# make   = "Example Vendor"
# model  = "Example Display"
# serial = "1234"
# layout = "grid"

# -----------------------------------------------------------------------------
# Workspace layout selection
# -----------------------------------------------------------------------------
# workspace is 1-based. Omit output for a global workspace override, or set an
# output connector name for a more specific output/workspace mapping.
# Resolution order is runtime selection, output+workspace, workspace-only,
# output default, then [layout].default.

[[workspace]]
workspace = 1
layout = "tile"

[[workspace]]
workspace = 2
layout = "monocle"

[[workspace]]
workspace = 3
layout = "scrolling"

[[workspace]]
workspace = 4
layout = "float"

# [[workspace]]
# output = "DP-1"
# workspace = 5
# layout = "grid"