laguna #

laguna is a window manager client for the non-monolithic river compositor. It requires river v0.4.8 or a compatible version. It uses stable river protocols only.

This repository builds laguna only. Install river separately.

Design #

river owns Wayland clients, rendering and frame synchronisation. laguna owns 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.16
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, it reads $HOME/.config/river/laguna.zon. If both files are missing, defaults stay in place. An invalid file is fatal: laguna rejects unknown fields, so typos fail loudly at startup.

Top-level options include 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 and rules.

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, or map them at runtime. Unknown commands fail synchronously.

The normal and locked modes always exist. When you lock the session, laguna switches every seat to locked. Only locked bindings work, and 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 and do not change tile size.

laguna marks tiled windows as 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, so 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 and draws none. It also marks clients as tiled, so well-behaved clients drop their shadows as well. 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, so nothing tears. Set allow_tearing = true to let a fullscreen window that asks for tearing, such as a game, skip vsync for lower input latency. Only the fullscreen window that river shows on an output decides that output's mode. Other outputs, and the same output once the window leaves fullscreen, go back to vsync.