1# Configuration
2
3NeferWL reads `$XDG_CONFIG_HOME/neferwl/config` (or `~/.config/neferwl/config`). `neferwl --config <path>` selects another file; `neferwl validate-config [path]` checks one without starting the compositor.
4
5## Format
6
7- One `key = value` per line; `#` starts a comment.
8- Lists are comma-separated; booleans are `on` / `off`.
9- A missing file or key means the default. An invalid line logs a warning and keeps that key's default; the rest of the file still applies. A duplicate key warns and the last one wins.
10- Every key applies live when the file is saved; windows stay open. `startup` and `xwayland` take effect at the next start.
11
12## Keys
13
14| Key | Default | Meaning |
15|---|---|---|
16| `keyboard.layout`, `.variant`, `.options` | empty | xkb names, e.g. `fr`, `caps:escape` |
17| `keyboard.repeat-rate` / `repeat-delay` | `25` / `600` | Key repeat per second / delay in ms |
18| `keyboard.cmd` | `super` | Modifier that `cmd` means in binds: `super`, `alt` or `ctrl` |
19| `terminal` | `$TERMINAL`, or `foot` if unset/empty | Command for automatic requests and `spawn-terminal`; whitespace-separated |
20| `terminal.auto-open` | `first` | `first`: one request for the initial numbered workspace per session; `all`: visible empty workspaces without slots, with retry protection; `off`: none. `--no-terminal` disables automatic requests for this run only |
21| `startup` | none | Command run once at session start; repeat the key for more |
22| `xwayland` | `xwayland-satellite` | X11 support; `off` disables it |
23| `background` | `#111111` | Solid background color |
24| `border.width` | `2` | Lines between visible neighboring tiles and around non-fullscreen floats, in logical pixels; `0` hides them |
25| `floating.dim` | `0.3` | Black veil over tiles and lower layers when a native floating window above the tiles or the stash is visible, and over the background and lower layers behind the overview; opacity 0 to 1 |
26| `stash.width` | `80` | Width of the selected stashed window, over the tiles, in percent of the usable width; 10 to 90 (`80%` works too). The rest is split between both sides, where the neighbors show. Its height is 80% of the usable height |
27| `stash.gap` | `2` | Space between the selected stashed window and its neighbors, in percent of the usable width; 0 to 10. The neighbors show from there to the screen edge: with the defaults, 8% of each. A gap as wide as the side margin hides them |
28| `stash.dim` | `0.5` | Black veil over the stash neighbors, borders included; opacity 0 to 1 |
29| `stash.capture` | `on` | `on`: a window opened while the stash is shown joins its end, selected; `toggle-window-stash` tiles it as a new column. `off`: new windows always tile |
30| `border.active` / `border.inactive` | `#808080` / `#111111` | Colors for focused / other window lines; only the focused output lights up |
31| `layout.gaps` | `0` | Space between windows |
32| `layout.max-columns` | `2` | Columns that share the screen before scrolling |
33| `layout.overflow` | `scroll` | Past the max: `scroll` right, `fixed` spiral split, or `cascade` into vertically scrolling bands |
34| `layout.<output>.max-columns`, `.overflow` | layout values | Per-screen layout: connector (`DP-2`) or monitor key |
35| `layout.presets` | `1/3, 1/2, 2/3, 1` | Widths for `cycle-column-width` (scroll overflow) |
36| `touchpad.natural-scroll` | `off` | Content follows the fingers, for two-finger scroll and three-finger swipes (see [Touchpad](#touchpad)) |
37| `touchpad.tap` | `on` | Tap to click: one finger left, two right, three middle |
38| `touchpad.accel-speed` | `0` | Touchpad pointer speed, from `-1` (slowest) to `1` (fastest) |
39| `touchpad.accel-profile` | `adaptive` | `adaptive`: faster finger moves go further; `flat`: constant speed |
40| `touchpad.left-handed` | `off` | Swaps the left and right touchpad buttons |
41| `touchpad.scroll-factor` | `1` | Multiplies two-finger scroll distance, above `0` up to `10` |
42| `mouse.natural-scroll` | `off` | Wheel scrolling moves the content with the wheel instead of against it. `mouse.*` applies to every pointer that is not a touchpad: mice, trackballs, trackpoints |
43| `mouse.accel-speed` | `0` | Mouse pointer speed, from `-1` (slowest) to `1` (fastest) |
44| `mouse.accel-profile` | `adaptive` | `adaptive`: faster moves go further; `flat`: constant speed |
45| `mouse.left-handed` | `off` | Swaps the left and right mouse buttons |
46| `cursor.hide-after` | `5s` | Hides the pointer cursor after this long without motion; the next motion shows it. 100ms to 1h, or `off` |
47| `animations` | `off` | **Experimental.** `on` animates changes; `off` makes every change instant and the three-finger swipe no longer follows the fingers: swipe landings, scrolling, workspace switches, window moves and resizes, drag drops, workspaces sent to another monitor, the overview, windows opening and closing, the stash showing and hiding, the focus pulse |
48| `animations.speed` | `normal` | Speed of every spring (not the focus pulse): `slow`, `normal` or `fast` (a view move lands in about 260, 180 or 130 ms), or a number relative to `normal`, from `0.1` (10× slower) to `10` (10× faster) |
49| `focus.follow-move` | `off` | Follow a column moved to another workspace |
50| `focus.animation` | `pulse` | Focus indicator on a window that keeps the focus for 150 ms: `pulse` (brief rise and fall) or `off`. Skipped for fullscreen windows, a window alone on screen (e.g. a maximized column), the overview and a window focused as it opens. Off while `animations = off` |
51| `focus.effect` | `screen` | What the focus indicator draws: `screen` brightens the window slightly, visible on black too. HDR (PQ) client content is not brightened on HDR outputs |
52| `focus.strength` | `0.04` | Peak of the focus effect, `0.01` to `0.2`: black reaches about 10/255 at `0.04` |
53| `workspace.<name>.*` | none | Named workspaces are outside the numbered list; use the overview to show an occupied one, or a `workspace <name>` bind to show it and toggle back |
54| `workspace.<name>.monitor` | focused output | Home monitor: connector (`DP-2`) or monitor key. A `workspace <name>` bind focuses it there. Unset, or while home is absent, the workspace comes to the focused output; it returns home when it reconnects |
55| `workspace.<name>.size` | `inherit` | Logical `WxH` viewport, centered on the monitor; inherits monitor size by default and always keeps its scale |
56| `workspace.<name>.max-columns`, `.overflow` | screen values | Per-workspace layout |
57| `workspace.<name>.column.<N>` | none | Slot: `<width>, <command>` |
58| `output.<name>` | preferred | `WxH`, `WxH@Hz`, `preferred` or `off` |
59| `output.<name>.scale` | `1` | 1 to 4, e.g. `1.5` or `4/3` |
60| `output.<name>.transform` | `normal` | `normal`, `90`, `180`, `270`, `flipped`, `flipped-90`, `flipped-180`, `flipped-270`; 90/270 swap the output's width and height |
61| `output.<name>.primary` | `off` | Gets focus and pointer at startup |
62| `output.<name>.right-of` / `.left-of` / `.above` / `.below` | automatic | Connector to place the output against, e.g. `DP-1` |
63| `output.<name>.offset` | `0` | Logical px along the shared edge, −65536 to 65536; see [Output placement](#output-placement) |
64| `output.<name>.hdr` | `off` | Turns on HDR10 on capable outputs; otherwise falls back to SDR (reason in the log) |
65| `output.<name>.sdr-brightness` | `203` | How bright SDR desktop content appears in HDR, in nits (80–1000) |
66| `render.direct-scanout` | `on` | Fullscreen buffers straight to the display |
67| `render.tearing` / `render.vrr` | `on` / `on` | Tearing: games in direct scanout. VRR: any fullscreen window covering the output |
68| `render.vrr-flip-gap` | `1ms` | Under VRR, a game frame commits at least this long after the previous flip, so it does not wait for the panel's slowest refresh (0 to 10ms; `0` turns it off) |
69| `performance.realtime` | `on` | Request real-time scheduling for output and input threads |
70| `log.level` / `log.debug` | `info` / empty | Log level / debug components or `all` |
71| `bind.<keys>` | see below | Action for a key combo; `none` removes a default |
72
73## Output placement
74
75Without relations, outputs sit left to right in config order, top-aligned. A relation places an output against another one; `offset` slides it along the shared edge so the pointer crosses where the screens really meet.
76
77```ini
78output.DP-2.right-of = DP-1
79output.DP-2.offset = 360    # DP-2 starts 360 px lower than DP-1's top
80```
81
82```
83┌────────────┐
84│            │┌─────────┐
85│    DP-1    ││  DP-2   │
86│ 2560x1440  ││1920x1080│
87│            │└─────────┘
88└────────────┘
89```
90
91Placement, offsets and monitor navigation use the rotated size: a 2560x1440 output with `transform = 90` is 1440 wide and 2560 tall at scale 1. Rotated outputs always compose, with no direct scanout or overlay planes.
92
93Rules:
94
95- `offset` moves down for `right-of`/`left-of` and right for `above`/`below`; negative moves the other way.
96- Sizes are logical: the layout follows scale changes on its own.
97- An output whose reference is not connected is placed automatically until the reference returns.
98- Cycles and invalid values are ignored with a warning in the log.
99- Positions and transforms set by kanshi, wdisplays or wlr-randr win until the next config reload.
100- `focus-monitor-*`, `move-workspace-to-monitor-*` and column moves past the edge go to the output on that side.
101
102Two rows of three, with DP-1 as the base:
103
104```
105┌────────┐┌────────────┐┌────────┐
106│  DP-4  ││   HDMI-1   ││  DP-5  │
107└────────┘└────────────┘└────────┘
108┌────────┐┌────────────┐┌────────┐
109│  DP-2  ││    DP-1    ││  DP-3  │
110└────────┘└────────────┘└────────┘
111```
112
113```ini
114# Bottom row: 1080p sides, bottoms aligned with DP-1 (1440 - 1080 = 360)
115output.DP-2.left-of = DP-1
116output.DP-2.offset = 360
117output.DP-3.right-of = DP-1
118output.DP-3.offset = 360
119
120# Top row: 1200p sides, bottoms aligned with HDMI-1 (1440 - 1200 = 240)
121output.HDMI-1.above = DP-1
122output.DP-4.left-of = HDMI-1
123output.DP-4.offset = 240
124output.DP-5.right-of = HDMI-1
125output.DP-5.offset = 240
126```
127
128## Workspace size
129
130A workspace inherits its monitor size unless `workspace.<name>.size` sets a logical `WxH`. Its viewport is centered, and columns, maximization, floating windows and fullscreen use that real layout size—not scaled overview previews. Oversized dimensions are limited to the monitor; reserved layer zones still reduce usable space. Monitor mode and scale stay unchanged. Omit `size` or use `inherit` to restore the default. Workspace transitions involving a smaller viewport switch without the vertical slide, keeping scrolling columns inside their frame. Fullscreen inside a smaller viewport uses composition rather than output-covering direct scanout, so fullscreen-game VRR/tearing eligibility does not apply.
131
132```ini
133workspace.presentation.size = 1920x1080
134bind.Cmd+p = workspace presentation
135```
136
137## Touchpad
138
139With `animations = on`, a three-finger swipe follows the fingers and moves one step at most, so a quick swipe never skips a column or a workspace:
140
141- Left or right scrolls the columns (`scroll` overflow) to the next column edge; the focus moves to a column fully on screen.
142- Up or down slides to the next numbered workspace in scroll and fixed layouts.
143- In [Cascade](#cascade), up/down scrolls one band and left/right switches workspaces.
144
145The view sticks a little near each step and catches up between them. Past the next step it resists; lift and swipe again to go further. When the fingers lift, a quick swipe goes on to the next step and a slow one settles on the closest.
146
147In scroll and fixed layouts with `natural-scroll = off`, a swipe left shows the columns to the left and a swipe up shows the workspace above. `natural-scroll = on` moves the content with the fingers, so both are reversed.
148
149With `animations = off`, nothing moves during the swipe: when the fingers lift, a quick or long enough swipe navigates content or workspaces along the layout's axes. Cascade band swipes stop at the first and last band.
150
151Over the shown stash a sideways swipe slides it with the fingers, with a stop on each window, and moves one window at most. In scroll and fixed layouts where the view cannot scroll (a floating or fullscreen window, fixed overflow, or a named workspace), a quick swipe runs `focus-column-left/right` or `focus-workspace-up/down` when the fingers lift. Cascade keeps horizontal workspace navigation; vertical band swipes do nothing while a floating or fullscreen window has focus.
152
153Two-finger scroll goes to the window under the pointer with the touchpad's timestamps, so apps with kinetic scrolling keep their inertia.
154
155## HDR
156
157`output.<name>.hdr = on` sends HDR10 (BT.2020, PQ) to displays whose EDID and connector support it. The desktop stays SDR content, shown at `sdr-brightness` nits.
158
159HDR-aware Wayland clients, including games through Vulkan WSI, browsers, and video players, can present HDR through `wp_color_manager_v1` and `wp_color_representation_v1`. Some apps require HDR to be enabled in their own settings. X11 clients stay SDR.
160
161Hardware-decoded video can use NV12 (8-bit) or P010 (10-bit) DMA-BUF subsurfaces with BT.601/709/2020 coefficients, full or limited range, and chroma-location type 0. The Vulkan device must support sampling the format/modifier with per-plane views; planes in one DMA-BUF use one memory import, while separate plane buffers additionally require Vulkan DISJOINT support. Unsupported formats are not offered. Confirm hardware decoding and the advertised DMA-BUF formats when testing an app.
162
163- Fullscreen HDR buffers (10-bit, PQ) go straight to the display unchanged.
164- Opaque SDR (sRGB) buffers also skip composition on HDR outputs when the KMS plane has a colour pipeline (`DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE`): sRGB curve, `sdr-brightness`, BT.709 to BT.2020, PQ, the same maths as composition. This applies to a fullscreen window (direct scanout) and to a lone window on an overlay plane. The compositor looks for that chain on each plane, whatever the driver; amdgpu on recent kernels has it. Without it, with alpha, with YUV or extended-linear content, SDR windows are composed, and the log gives the reason (`hdr_sdr_content`, `yuv`). When the driver refuses a pipeline (tested once per plane, buffer format and cursor state), the window is composed with reason `color_refused`.
165- Composed frames and every modeset leave the planes' pipeline on Bypass.
166- A VT switch resets the pipeline first: before the seat is disabled, each output that applies a pipeline commits Bypass (at most 100 ms are spent waiting for it, then the switch goes on and a warning is logged). The pipeline survives a master change, and a client without `DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE` cannot clear it. A crash or `kill -9` cannot do this reset: the next DRM master inherits the pipeline, with its colours distorted, until a client that sets the cap commits a modeset (or this compositor starts again).
167- Windowed and otherwise composed HDR content keeps its full range in a linear fp16 image before PQ output; the display tone-maps it according to its EDID metadata. SDR surfaces are blended in linear light on HDR outputs, so antialiased edges may look slightly different than sRGB-space blending. Dim veils (`floating.dim`, `stash.dim`) darken SDR white as much as on an SDR output; brighter HDR highlights stay a little brighter.
168- Screenshots and capture use opaque 8-bit sRGB. HDR capture applies GPU tone mapping and reduces out-of-sRGB gamut: values below 90% of SDR reference white stay unchanged, while brighter values are compressed to preserve highlight differences (SDR reference white maps to about 245/255 when capturing an HDR output, versus 255/255 on an SDR output). This capture-only transform does not change HDR display output.
169- The display gets the metadata from its own EDID, not the client's MaxCLL/MaxFALL.
170
171HDR requires DRM HDR connector properties, suitable KMS planes, and Vulkan fp16 composition and 10-bit export formats/features. Unsupported capabilities fall back to SDR. NVIDIA is not supported yet (tested status).
172
173## Binds
174
175`bind.<keys> = <action>`. Modifiers: `cmd` (see `keyboard.cmd`), `shift`, `ctrl`, `alt`, `super`.
176
177- Keys are what the active layout prints: `cmd+é` on AZERTY. Write `=`, `#` and space by name: `cmd+equal`, `cmd+numbersign`, `cmd+space`.
178- `code:N` is a physical key (evdev code), the same on every layout: `code:2` to `code:10` are the digit row 1 to 9.
179- Other keys use their xkb keysym name, case-sensitive (`wev` shows it). Media keys have no default bind:
180
181  ```
182  bind.XF86AudioRaiseVolume = spawn wpctl set-volume -l 1.0 @DEFAULT_AUDIO_SINK@ 5%+
183  bind.XF86AudioLowerVolume = spawn wpctl set-volume @DEFAULT_AUDIO_SINK@ 5%-
184  bind.XF86AudioMute = spawn wpctl set-mute @DEFAULT_AUDIO_SINK@ toggle
185  bind.XF86MonBrightnessUp = spawn brightnessctl set +5%
186  bind.XF86MonBrightnessDown = spawn brightnessctl set 5%-
187  ```
188- `none` removes a default bind.
189- `spawn <command>` runs a program without a shell; see [Running commands](desktop.md#running-commands).
190
191### Cascade
192
193Set `layout.overflow = cascade` globally, per output, or on a named workspace. Columns fill equal-width cells, up to `max-columns` per band, then continue in a fresh band below. Incomplete bands keep empty cells. New columns append last; closing a column compacts the following bands. Each band fills the usable height after panel reservations.
194
195Left/right focus follows column order across band boundaries. Up/down visits stacked windows first, then the closest column in the adjacent band. Column width presets and resizing do nothing; window height shares still apply. Maximizing a column hides its same-band siblings until focus moves or maximization ends.
196
197Three-finger vertical swipes scroll bands; horizontal swipes switch workspaces. Scroll and fixed workspaces retain their existing gesture axes. A switch keeps the source workspace's axis throughout its transition; the destination's axes apply to the next gesture. The `focus-workspace-up/down` commands still mean previous/next workspace, even when the transition is horizontal. Four-finger and stash gestures keep their existing behaviour.
198
199The overview presents bands vertically in one workspace card, with workspace neighbors arranged horizontally. Long previews center on the selected band. The stash keeps its smaller, independently scaled pile on the left; when present, it occupies the previous workspace's left-hand peek. Keyboard and gesture navigation still reach that workspace. Selecting a window reveals its band. Cascade supports dropping onto tiles, but not gap insertion or edge scrolling during a drag.
200
201### Actions
202
203| Action | Effect |
204|---|---|
205| `spawn <command>` | Run a program |
206| `spawn-terminal` | Run `terminal` |
207| `close-window` | Close the focused window |
208| `toggle-fullscreen` | Fullscreen the focused window. An app that asks for fullscreen in its first second (e.g. a Wine launcher that remembered a monitor-sized window) opens in a column instead; later requests are honoured. Fullscreen is exclusive, whether from this bind or the app: nothing is drawn above it but a surface taking the keyboard (a locker). Bars, notifications and other windows wait hidden until it leaves; a window opening meanwhile waits hidden too. The window's own dialogs are the exception: a dialog it opens (a file chooser, a screen-sharing or permission request from the desktop portal) shows over it with the focus, and a focus move goes back to the fullscreen window without leaving fullscreen. Fullscreen stays in place: the window keeps its column. Focusing another window of the workspace (`focus-column-left/right`, `focus-window-up/down`, an activation or the overview) leaves fullscreen; the app's own fullscreen requests are then refused until it is focused again. In fixed overflow, an app's own request applies only while it has the focus. A taskbar request brings the window on screen with the focus first |
209| `toggle-window-stash` | Move the focused tile to the end of the workspace's [stash](#stash), shown and selected; on a stashed window, send it back to its former column, width and maximized or expanded state when possible. A native dialog becomes a new tiled column. A fullscreen window must leave fullscreen first |
210| `toggle-floating` | Make the focused tile a [free floating window](#free-floating-windows) at its current size, centred; on a floating window, send it back to its former place in the columns (a native dialog becomes a new column). Does nothing on a stashed or fullscreen window |
211| `toggle-stash-visible` | Hide the stash and give the focus back to the tiles, or show it again with the focus on its selected window. Native dialogs stay as they are. Over a fullscreen window, shows the stash on top with the focus; the window stays fullscreen behind (composed, so no direct scanout while the stash shows) and is back when the stash hides or the focus leaves it. `toggle-window-stash` or `toggle-fullscreen` on a stashed window there leaves that fullscreen for it. New windows never join or show over it; the fullscreen window's own dialogs show above it |
212| `toggle-overview` | Open the [overview](#overview), or close it on the selected window |
213| `maximize-column` | Toggle full usable width for the focused column, preserving gaps and its saved width; in fixed overflow, other columns are hidden until focus moves or it is toggled off. On a window that made itself fullscreen (e.g. a Wine app at monitor size), it first returns the window to its column |
214| `cycle-column-width` | Step through `layout.presets`. In fixed overflow, toggle the focused column to `max-columns - 1` cells in place; the other columns stack on each side in the last cell. One column is expanded at a time |
215| `focus-column-left/right` | Focus the neighbor column; at the edge, the neighbor monitor. In fixed overflow, the neighbor on screen. From a fullscreen window, the neighbor column comes first and fullscreen ends; at the edge it stays |
216| `focus-window-up/down` | Focus in the column; past the edge, the next workspace. In fixed overflow, the column on screen above or below comes first. Up at the top brings back a covering float put behind the columns. From a fullscreen window, a window above or below comes first and fullscreen ends |
217| `move-column-left/right` | Move the focused column |
218| `move-window-up/down` | Move the focused window up or down in its column; focus follows it |
219| `set-column-width <+N%\|-N%>` | Widen or narrow the focused column by N% of the usable width (1-100), between 10% and 100%. The new width stays until changed; `cycle-column-width` then restarts at the first preset. Does nothing in fixed overflow |
220| `set-window-height <+N%\|-N%>` | Give the focused window N% more or less of its column's height; the other rows give or take it in proportion. Each row keeps at least 10%. A window joining or leaving the column resets equal rows. Does nothing past 9 rows |
221| `consume-or-expel-window-left/right` | A lone window joins the neighbor column; a stacked one leaves for a new column |
222| `focus-workspace <N>` / `focus-workspace-up/down` | Show a numbered or neighbor workspace |
223| `workspace <name>` | Toggle a named workspace |
224| `move-column-to-workspace <N>` / `-up/-down` | Move the focused column |
225| `move-window-to-workspace <N>` / `-up/-down` | Move only the focused window |
226| `focus-monitor-left/right` / `focus-monitor-up/down` | Focus the neighbor monitor in that direction |
227| `move-workspace-to-monitor-left/right` / `move-workspace-to-monitor-up/down` | Move the workspace to the neighbor monitor in that direction; it gets a new home |
228| `move-workspace-up/down` | Swap the current numbered workspace with its neighbor; the view follows it. It never passes the empty workspace at the end |
229| `scale-up` / `scale-down` | Zoom the whole display; one second after the last press, the scale is saved to `output.<name>.scale` and a notification confirms it (`notify-send`) |
230| `quit` | Exit NeferWL |
231
232### Stash
233
234Each workspace has a stash: a horizontal strip of windows set aside with `toggle-window-stash`, in the order they arrived. The selected window is centred over the tiles, `stash.width` of the usable width (80% by default) and 80% of its height. Its left and right neighbors sit `stash.gap` beside it and show up to the screen edges, dimmed (`stash.dim`); a click on one selects it. The others wait off screen.
235
236While the stash has the focus, `focus-column-left/right` and the three-finger swipe move through it, sliding the view, and stop at its ends; `focus-window-up/down` do nothing. Hide it with `toggle-stash-visible`, or with a four-finger swipe down or up, to get back to the tiles; a swipe down shows it again. Scripts see each stashed window's place, and whether the stash is hidden, in the [state file](desktop.md#state-for-scripts).
237
238Native floating windows are not in the stash: they stay centred in the usable output area. A window-sized float that fills that area (within two border widths plus two logical pixels per axis) stays below the columns when you focus a tile; `focus-window-up` at the top of a column raises it again. It does not hide bars or pin focus. Small dialogs and file pickers always stay above the columns; shrinking a float promotes it above them. Real fullscreen remains exclusive, except for the fullscreen window's own dialogs. A dialog belongs to a window through `xdg_toplevel.set_parent`, or through `zxdg_importer_v2` when another program opens it, as the desktop portal does.
239
240### Free floating windows
241
242`toggle-floating` lifts the focused tile out of its column into a free floating window. NeferWL sets its size, and it stays where you put it, kept inside the usable area. Its place is relative to the screen, so it keeps it on another workspace or monitor of any size.
243
244On a free floating window, `move-column-left/right` and `move-window-up/down` move it by 50 logical pixels, and `set-column-width`/`set-window-height` resize it by a share of the usable width or height. `toggle-window-stash` stashes it and brings it back floating at the same place. `toggle-floating` returns it to its column.
245
246### Moving windows with the pointer
247
248Hold `cmd` and drag with the left button to move the window under the pointer; drag with the right button to resize a floating window from its bottom-right corner. Apps that drag their own title bar or edges (`xdg_toplevel.move`/`resize`) do the same without `cmd`. The window gets no pointer events while you drag, and `Escape` cancels the drag.
249
250A floating window follows the pointer and becomes a [free floating window](#free-floating-windows). A tile stays in place until you release the button. Until then, a bar or frame in `border.active` color shows where it will land:
251
252- top or bottom quarter of a window: stack it above or below that window;
253- middle of a window: swap the two columns (a window from a stacked column becomes a new column there);
254- in scroll overflow, the gap between two columns: a new column there. Moving the pointer against the left or right edge scrolls the workspace one column at a time.
255
256The drop can be on another monitor; focus follows the window. There, the middle of a window puts it in a new column at that place: only columns of the same workspace swap. A full `fixed` workspace has no room for a new column, so the window stacks in the outlined one.
257
258### Overview
259
260`toggle-overview` shows scaled previews of the current workspace, including over fullscreen windows, over a background darkened by `floating.dim`. Windows keep their size and previews show their last frames. Covering floats and windows hidden behind a maximized column in `fixed` overflow appear as cards: the on-screen item is in front, hidden columns share one spiral-layout card, up to two cards behind peek above it, and passed cards peek below. Neighbor workspaces show dimmed stacks. Each monitor has one overview; workspace neighbors are vertical in scroll/fixed and horizontal when the current workspace uses Cascade. A named workspace appears directly below the numbered workspace from which its `workspace <name>` bind was invoked. Invoking it from another numbered workspace updates this placement; browsing the overview does not. Several named workspaces attached to the same numbered workspace follow configuration order, with horizontal rules separating their group from numbered rows. Named-to-named binds reuse the source's numbered attachment. Unattached named workspaces follow the last occupied numbered row, or the first row if all numbered workspaces are empty. The selected workspace stays centred and its immediate neighbors follow its workspace-navigation axis; stash cards retain their own scale. Empty workspaces are skipped unless currently selected or serving as the invocation anchor of a visible named row. Named workspaces remain outside the numbered list and normal workspace up/down navigation. Smaller floats, such as dialogs, stay hidden. A fullscreen floating window, or any fullscreen window with `fixed` overflow, is its workspace's front card, with the windows it hides behind it; `scroll` overflow keeps its columns selectable in one card. Choosing the fullscreen window keeps it fullscreen; choosing another window leaves fullscreen.
261
262| Key | Action |
263| --- | --- |
264| `h` / `l`, `left` / `right` | Move within a front column-group card; left of its first tile enters the stash. Left on a single-window card sends it behind, or enters the stash when none is behind; right does nothing on a single card. |
265| `k` / `j`, `up` / `down` | Browse cards within the selected stash pile; otherwise bring the next card above / previous card below to the front, then change workspace at the stack boundary |
266| `return` | Show the selected front card; picking a hidden column moves the maximization to it. Other rows shown keep their focus, maximization and float order |
267| `escape` | Return to the original workspace; every row shown keeps its focus, maximization and float order |
268
269The focus binds (`focus-column-left/right`, `focus-window-up/down`, `cmd+arrows` by default) move the selection like these keys. In the overview, `focus-workspace-up/down` also traverse cards before crossing workspace rows, including named ones, except inside a selected stash pile.
270
271Each workspace's [stash](#stash), hidden or not, shows as a pile of cards on the left of its row, which stays centred unless it would overlap the pile: its selected window in front, up to three others behind it, dimmed. In the pile, `k` / `j` or up/down browse stash cards and stop at either end without changing workspace. Right (`l`) leaves the pile immediately; left (`h`) stays in the pile. On a stash-only workspace, right deselects the pile so up/down can change workspace. Browsing brings the selected card to the front without reordering the stash. `return` or a click on a card closes the overview with the stash shown on that window.
272
273A four-finger swipe up opens the overview, or hides the [stash](#stash) when it is shown, and a swipe down closes the overview on the selection (with the overview closed, a swipe down shows or hides the stash), whatever `touchpad.natural-scroll` says. Two-finger scrolling belongs to applications and never navigates the overview; previews do not accept application input. Three fingers move the selection during the gesture, following `touchpad.natural-scroll`: horizontally, a short distance selects the next app and further movement repeats at a longer distance; vertically, one step per gesture selects a stack card or changes workspace. Inside a selected stash pile, vertical movement browses its cards and horizontal movement enters or leaves the pile. Lifting resets the gesture without an extra step; cancellation keeps selections already made. The mouse wheel moves one step per notch, following `mouse.natural-scroll`. Three-finger navigation, the wheel and keyboard navigation share the same pile boundaries.
274
275Return or a click on a front tile or peeking card commits it; card changes remain provisional until then. `close-window` targets the selected preview. Move-to-workspace binds (`move-column-to-workspace*`, `move-window-to-workspace*`) move the selected preview at once and keep the overview open; with `focus.follow-move`, the selection follows it. Escape does not undo a move, and the row that received the window keeps it focused. A selected stash card, or a row with no preview, does not move. Other window mutation binds (moving within the row, resizing, maximizing, fullscreen and stash toggles) and moving a workspace to another monitor are disabled while the overview is open. Workspace and monitor navigation, launch and quit binds remain active.
276
277### Default binds
278
279With `keyboard.cmd = alt`, the `cmd+alt+…` binds have the same keys as `cmd+…` and are dropped with a warning; with `keyboard.cmd = ctrl`, so are the `cmd+ctrl+…` ones. Bind those actions to other keys.
280
281| Keys | Action |
282|---|---|
283| `cmd+return` | `spawn-terminal` |
284| `cmd+left` | `focus-column-left` |
285| `cmd+right` | `focus-column-right` |
286| `cmd+up` | `focus-window-up` |
287| `cmd+down` | `focus-window-down` |
288| `cmd+shift+left` | `move-column-left` |
289| `cmd+shift+right` | `move-column-right` |
290| `cmd+h` | `focus-column-left` |
291| `cmd+l` | `focus-column-right` |
292| `cmd+k` | `focus-window-up` |
293| `cmd+j` | `focus-window-down` |
294| `cmd+shift+h` | `move-column-left` |
295| `cmd+shift+l` | `move-column-right` |
296| `cmd+bracketleft` | `consume-or-expel-window-left` |
297| `cmd+bracketright` | `consume-or-expel-window-right` |
298| `cmd+shift+up` / `cmd+shift+k` | `move-window-up` |
299| `cmd+shift+down` / `cmd+shift+j` | `move-window-down` |
300| `cmd+alt+left` / `cmd+alt+h` | `set-column-width -10%` |
301| `cmd+alt+right` / `cmd+alt+l` | `set-column-width +10%` |
302| `cmd+alt+up` / `cmd+alt+k` | `set-window-height -10%` |
303| `cmd+alt+down` / `cmd+alt+j` | `set-window-height +10%` |
304| `cmd+r` | `cycle-column-width` |
305| `cmd+f` | `maximize-column` |
306| `cmd+shift+f` | `toggle-fullscreen` |
307| `cmd+s` | `toggle-stash-visible` |
308| `cmd+shift+s` | `toggle-window-stash` |
309| `cmd+shift+space` | `toggle-floating` |
310| `cmd+o` | `toggle-overview` |
311| `cmd+q` | `close-window` |
312| `ctrl+alt+backspace` | `quit` |
313| `ctrl+cmd+space` | `spawn fuzzel` |
314| `cmd+pageup` | `focus-workspace-up` |
315| `cmd+pagedown` | `focus-workspace-down` |
316| `cmd+shift+pageup` | `move-column-to-workspace-up` |
317| `cmd+shift+pagedown` | `move-column-to-workspace-down` |
318| `cmd+code:2` | `focus-workspace 1` |
319| `cmd+code:3` | `focus-workspace 2` |
320| `cmd+code:4` | `focus-workspace 3` |
321| `cmd+code:5` | `focus-workspace 4` |
322| `cmd+code:6` | `focus-workspace 5` |
323| `cmd+code:7` | `focus-workspace 6` |
324| `cmd+code:8` | `focus-workspace 7` |
325| `cmd+code:9` | `focus-workspace 8` |
326| `cmd+code:10` | `focus-workspace 9` |
327| `cmd+shift+code:2` | `move-column-to-workspace 1` |
328| `cmd+shift+code:3` | `move-column-to-workspace 2` |
329| `cmd+shift+code:4` | `move-column-to-workspace 3` |
330| `cmd+shift+code:5` | `move-column-to-workspace 4` |
331| `cmd+shift+code:6` | `move-column-to-workspace 5` |
332| `cmd+shift+code:7` | `move-column-to-workspace 6` |
333| `cmd+shift+code:8` | `move-column-to-workspace 7` |
334| `cmd+shift+code:9` | `move-column-to-workspace 8` |
335| `cmd+shift+code:10` | `move-column-to-workspace 9` |
336| `cmd+ctrl+left` | `focus-monitor-left` |
337| `cmd+ctrl+right` | `focus-monitor-right` |
338| `cmd+ctrl+up` / `cmd+ctrl+k` | `focus-monitor-up` |
339| `cmd+ctrl+down` / `cmd+ctrl+j` | `focus-monitor-down` |
340| `cmd+ctrl+h` | `focus-monitor-left` |
341| `cmd+ctrl+l` | `focus-monitor-right` |
342| `cmd+ctrl+shift+left` | `move-workspace-to-monitor-left` |
343| `cmd+ctrl+shift+right` | `move-workspace-to-monitor-right` |
344| `cmd+ctrl+shift+h` | `move-workspace-to-monitor-left` |
345| `cmd+ctrl+shift+l` | `move-workspace-to-monitor-right` |
346| `cmd+ctrl+shift+up` / `cmd+ctrl+shift+k` | `move-workspace-up` |
347| `cmd+ctrl+shift+down` / `cmd+ctrl+shift+j` | `move-workspace-down` |
348| `cmd+code:13` | `scale-up` |
349| `cmd+code:12` | `scale-down` |