river handles Wayland clients, rendering and frame synchronisation. laguna handles window management: tags, focus, keybindings, layout policy and window rules. The two programs communicate over the stable river-window-management-v1 protocol. laguna configures input over the stable river input protocols.

Requirements #

Zig 0.17
wayland
wayland-protocols
xkbcommon 1.12 or newer
pkg-config
scdoc (man pages)

Build and install #

zig build -Doptimize=ReleaseSafe --prefix ~/.local install

Run #

Start river from your session startup command.
Start laguna from $XDG_CONFIG_HOME/river/init or $HOME/.config/river/init.

Configuration #

laguna reads its configuration from $XDG_CONFIG_HOME/river/laguna.zon. If that file is missing, laguna reads $HOME/.config/river/laguna.zon. If both files are missing, defaults stay in place. An invalid file stops laguna at startup. laguna rejects unknown fields, so a typo produces an error instead of a silent misconfiguration.

The configuration has these top-level options: main_ratio, main_count, main_location, attach_mode, output_attach_mode, spawn_tagmask, border_width, border_color_focused, border_color_unfocused, focus_follows_cursor, csd, allow_tearing, cursor_warp, xcursor_theme, repeat, keyboard_layout, keyboard_layout_file, modes, inputs, rules and osd. The optional osd block shows a small box in the middle of the screen. The box shows the number of the lowest visible tag when the focused tags change.

See example/laguna.zon for a complete annotated configuration with keybindings, input settings, rules and theme.

Reload the configuration without restarting by sending SIGHUP to the laguna process:

pkill -HUP laguna

Commands #

Bind commands in the modes section of the configuration. You can also map them at runtime. An unknown command fails straight away with an error.

The normal and locked modes always exist. When you lock the session, laguna switches every seat to locked. Only locked bindings work. Other keys reach the lock screen. Unlocking restores the previous mode.

exit, close
focus-view, zoom, swap, snap
set-focused-tags, toggle-focused-tags
set-view-tags, toggle-view-tags
focus-previous-tags, send-to-previous-tags
focus-output, send-to-output
declare-mode, enter-mode
map, map-pointer, unmap, unmap-pointer
main-ratio, main-count, main-location
attach-mode, default-attach-mode, output-attach-mode
move, resize, toggle-float, toggle-fullscreen
rule-add, rule-del
spawn, spawn-tagmask
set-repeat, input, keyboard-layout, keyboard-layout-file
border-width, border-color-focused, border-color-unfocused
focus-follows-cursor, set-cursor-warp, xcursor-theme, csd, allow-tearing

Layout #

Tiled windows fill the usable output area with no gaps. Borders draw above window content. They do not change tile size.

laguna tells each tiled window that it is tiled and maximized. The Wayland xdg-shell protocol requires a maximized window to take exactly the size laguna proposes. Terminals therefore keep the full tile size, even when it is not a whole number of character cells. A client that ignores this leaves a strip that shows what is behind it. river clips each tiled window to its tile. A window larger than its tile never covers its neighbours.

Floating windows always stay above tiled windows. A move-view or resize-view pointer binding makes a tiled window float. The move, resize and snap commands do the same. The window stays where you drop it.

Title bars #

Windows have no title bar by default. laguna asks every window to use server-side decorations. laguna draws none itself. It also marks clients as tiled. Clients that follow the protocol then drop their shadows. A window that draws its own title bar shows a restore button while tiled, because laguna marks it maximized. laguna ignores that button.

To let clients draw their own title bars, set csd = true. To do this for some windows only, add a csd rule. A client that only supports client-side decorations draws its own title bar regardless of csd.

Tearing #

Every output uses vsync by default. Nothing tears. Set allow_tearing = true to let a fullscreen window skip vsync. A window that asks for tearing, such as a game, then runs with lower input latency. Only the fullscreen window that river shows on an output decides that output's mode. Other outputs stay on vsync. The same output goes back to vsync once the window leaves fullscreen.

Limits #

laguna does not support features that have no protocol:

external layout generators
compositor background and cursor hiding
lid-switch bindings
keyboard groups

Clone this repository

laguna #

Design #