Traditional Wayland compositors have a monolithic architecture that combines the compositor and window manager into a single program. This has the downside of requiring Wayland window managers to do the significant work of implementing an entire Wayland compositor as well.
The new 0.4.0 release of river, a non-monolithic Wayland compositor, breaks from this traditional architecture and splits the window manager into a separate program. There are already many window managers compatible with river.
The stable river-window-management-v1 protocol gives window managers full control over window position, keybindings, and all other window management policy while river itself provides frame-perfect rendering, good performance, and all the low-level plumbing required.
This blog post gives a high level overview of the design decisions behind this protocol. This is roughly the same information I presented in my FOSDEM 2026 Talk.
Display Server, Compositor, Window Manager
The traditional Wayland architecture combines three separate roles in the compositor process:
Display Server: Route input events from the kernel to windows and give the kernel buffers to display.
Compositor: Combine all buffers from visible windows into a single buffer to be displayed by the kernel.
Window Manager: Arrange windows, define keybindings, other user-facing behavior.
To understand why Wayland compositors thus far have chosen to combine these roles, it is first necessary to understand some of the fundamental problems with X11’s architecture that Wayland was designed to solve.
With the X11 protocol, the display server is a separate process from the compositor and window manager:
Following the steps taken from a user clicking on a button in a window to the change in the window’s displayed content is quite informative. Referring to the numbers in the diagram above:
The user clicks on a button in a window.
The kernel sends an input event to the display server.
The display server decides which window to route the input event to. Already there is a problem here: since the display server is not aware of the compositor’s scene graph it cannot be 100% sure which window is rendered under the user’s mouse at the time of the click. The display server makes its best guess and sends the event to a window.
The window submits a new buffer to the display server.
The display server passes the window’s new buffer on to the compositor.
The compositor combines the window’s new buffer with the rest of the user’s desktop and sends the new buffer to the display server.
The display server passes the compositor’s new buffer to the kernel.
With this architecture, the display server is acting as an unnecessary middle-man between the kernel, X11 windows, and compositor. This results in unnecessary roundtrips between the display server and compositor, adding latency to every frame.
The traditional Wayland architecture eliminates these unnecessary roundtrips and solves the input routing problem mentioned in step 2. by combining the display server and compositor into a single process:
Traditionally, Wayland compositors have taken on the role of the window manager as well, but this is not in fact a necessary step to solve the architectural problems with X11. Although, I do not know for sure why the original Wayland authors chose to combine the window manager and Wayland compositor, I assume it was simply the path of least resistance. It is not trivial to design a window management protocol that keeps all the advantages of Wayland, but it’s certainly possible.
Window Management Protocol Design Constraints
The river-window-management-v1 protocol is designed to give window managers maximum control without losing any of the key advantages of Wayland. Specifically, the window management protocol must not require a roundtrip every frame or every input event. There should be no input latency penalty compared to the traditional monolithic Wayland architecture when, for example, typing into a terminal emulator or playing a game.
Furthermore, the Wayland ideal of “frame perfection” must be upheld. To illustrate what frame perfection means in the context of window management, consider the following example: several windows are in a tiled layout taking up the entire display area and a new window is opened. The window manager decides to add the new window to the tiled layout, resizing and rearranging the existing windows to make space.
In this case, frame perfection means that the user must not see a frame where there is a gap in the tiled layout or where windows are overlapping and have dimensions that do not fit cleanly with their neighbors. Achieving frame perfection here requires waiting to render the new state until all windows have submitted buffers with the newly requested dimensions.
Note however that frame perfection is only achievable if the windows are drawn by well-implemented programs. The compositor cannot delay rendering the new state forever while waiting for windows to submit new buffers, delaying too long makes things feel less responsive to the user rather than smoother. To solve this the compositor uses a short timeout. If windows are too slow, frame perfection is not possible.
Window Management State Machine
The river-window-management-v1 protocol divides the state managed by the window manager into two disjoint categories: window management state and rendering state.
Window management state influences the communication between the compositor and individual windows. It includes window dimensions, fullscreen state, keyboard focus, keyboard bindings, etc.
Rendering state on the other hand only affects the rendered output of the compositor and does not influence communication between the compositor and individual windows. It includes the position and rendering order of windows, server-side decorations, window cropping, etc.
To achieve frame perfection, the modifications made to this state by the window manager are batched into atomic updates by the river-window-management-v1 protocol. Changes to window management state can only occur during a “manage sequence” and changes to rendering state can only occur during a “render sequence.”
As seen in the state machine above, the compositor initiates manage/render sequences and no roundtrip with the window manager is required when no window-management-related state has changed. In other words, the window manager stays idle while the user is, for example, typing into a terminal and is woken up again when, for example, the user triggers a window manager keybinding or a new window is opened.
At the same time, frame perfection is possible even with complex tiled layouts or server-side decorations rendered by the window manager. The compositor handles all the synchronization work with the windows and the window manager only needs to, for example, adjust the position of windows or size of its server side decorations to adapt to the new window dimensions.
This state machine is not really a new idea, something similar can be found hiding inside most existing Wayland compositors including river-classic and sway for example. In a way, this state machine is a clarification and formalization of the internal architecture used by older river versions. It is the result of 6+ years of experience working on river and slowly refining the architecture over time.
Motivation
Separating the Wayland compositor and window manager greatly lowers the barrier to entry for writing a Wayland window manager. Window manager authors can focus on window management policy without needing to implement an entire Wayland compositor as well. While libraries such as wlroots make writing a compositor somewhat easier, it remains a great deal of work. Writing a Wayland compositor is not a weekend project, but with the new river-window-management-v1 protocol writing a basic but usable Wayland window manager over the weekend is now very possible.
The window manager developer experience is also greatly improved. A window manager crash does not cause the Wayland session to be lost. Window managers can be restarted and switched between. Debugging a window manager is much less of an ordeal than debugging a Wayland compositor. Anyone who has written a Wayland compositor knows the pain of debugging issues that only reproduce when running on “bare metal” (i.e. using DRM/KMS directly), one might be forced to ssh in from a different computer to figure out what has gone wrong.
Furthermore, window managers can be implemented in slow, high-level, garbage-collected languages without sacrificing compositor performance/latency. Having a garbage collector in the compositor is great way to miss frame deadlines and cause input latency spikes. However, since the river-window-management-v1 protocol does not require a round-trip with the window manager every frame, having a garbage collector in the window manager does not really matter. I don’t have any performance issues daily driving my slow, garbage-collected window manager on a >10 year old ThinkPad x220.
Wayland currently does not come close to the diversity of X11 window managers. I believe that separating the Wayland compositor and window manager will change this and I see the beginnings of this change with the 15 window managers already written for river!
Limitations
The river-window-management-v1 protocol does not support use-cases that deviate from the traditional, 2D desktop paradigm. This means no VR support for example.
Crazy visual effects like wobbly windows are also out of scope for river currently, though simple animations already work well. I am open to exploring custom shaders to give window managers more control over rendering eventually but don’t expect that to happen for a year or two at the earliest, there are other priorities for now.
I am not aware of any limitations river places on window management policy that cannot be resolved by extending the protocol. If you are developing a window manager and have a use-case that river does not yet support please open an issue and we will figure out how to get it supported!
Roadmap
With the 0.4.0 release, river is already more than featureful enough to daily drive in combination with a window manager of your choice. Furthermore, the river-window-management-v1 protocol is stable, we do not break window managers.
The best way to get a sense of what features are planned to be added in the future is to look at the accepted label on our issue tracker.
As far as what needs to happen before river 1.0.0, I want to explore some ideas for how to improve the UX of starting and switching between river compatible window managers. All window managers written for river 0.4.0 will remain compatible with river 1.0.0 and beyond, but I may need to make minor breaking changes to river’s CLI depending on how those plans work out. In any case, expect the next major river release to be 1.0.0!
Donate
Unfortunately, the current pace of river’s development is not sustainable without more financial support. If my work on river adds value to your life please consider setting up a recurring donation through liberapay. You can also support me with a one-time or monthly donation on github sponsors or ko-fi though I prefer liberapay as it is run by a non-profit. Thank you for your support!
Gallery
To make all this talk about window managers a bit more tangible, please enjoy these screenshots of window managers running under river. Note that this selection is heavily biased towards the most visually interesting window managers, there are plenty of other excellent window managers to choose from!
Canoe - Stacking window manager with classic look and feel:
reka - An Emacs-based window manager for river (similar to EXWM):
tarazed - A powerful and distraction-free desktop experience:
rhine - Recursive and modular window management with animations:
Instagram Engineering
Shopify Engineering