Isaac Freund's Blog

Separating the Wayland Compositor and Window Manager

2026-03-15T00:00:00Z

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:

River 0.3.0, Waylock 1.0.0, Status Update

2024-04-16T00:00:00Z

Things have been a bit quiet on this blog recently. I spent most of 2023 writing my bachelor’s thesis and finishing up my degree. That’s all wrapped up now though, which means I’ve finally had time to wrap up some other things for my open source projects.

River 0.3.0

The river 0.3.0 release has finally been tagged! This one’s been in the pipeline for quite a while, it’s been over a year since 0.2.0 was released and river has seen significant improvements since then. The past few months I’ve done my best to fix as many bugs as possible but a non-bugfix release always entails new code reaching a lot of people with diverse setups. If you find a bug in river please open an issue.

The biggest change in river 0.3.0 is not immediately visible: river 0.3.0 uses the wlroots scene graph API and has see a lot of internal improvements related to that transition. An initial version of the wlroots scene graph API was landed in wlroots over two years ago and has seen steady improvement since. I helped to push it forward in upstream wlroots over the years and am very happy to finally be using it in river. It brings finely-grained damage tracking and other performance optimizations to river which should positively impact battery life and make running river with software rendering bearable.

Aside from that more behind-the-scenes work, river 0.3.0 brings many nice usability enhancements. There is now a “rules system” for automatically assigning tags to new windows and performing other actions. The input-method-v2 and text-input-v3 protocols are supported, allowing use of alternative input software for users that speak a language not well supported by western keyboards. River also now has basic support for drawing tablet input. For a full list of changes, see the release notes here

Thank you to everyone who has contributed code and bug reports to river! River would not be where it is today without you.

In other river news, the upstream river repository has moved to https://codeberg.org/river/river. Github is a proprietary platform with interests increasingly misaligned with my values. Free and open source software like river should not require contributors to have a github account or interact with github in any way. There is still a read-only mirror of the river repository on github for now to ease the transition, it may be dropped eventually if/when I decide to delete my personal github account.

River also now has a page here on my website, I’ve written a bit about my future plans for river there if you’re curious :) River also has gained a written Code of Conduct documenting the existing standards and moderation practice. Luckily, we have a wonderful community and haven’t yet had to deal with any notable unacceptable behavior I’m aware of.

Waylock 1.0.0

There haven’t been any breaking changes to waylock in over a year and I’m happy with its feature set. Therefore, I’ve tagged a stable 1.0 release. The only change since the last waylock release is the addition of the -ready-fd flag contributed by tiosgz. This is an alternative to the -fork-on-lock flag for notification that waylock has successfully locked the session. The new flag is compatible with the readiness notification protocol used by the s6 and dinit service managers as well as being more flexible than -fork-on-lock for use in scripting.

Don’t be alarmed if waylock development slows down to a snail’s pace after this release. I consider it to be feature complete and as long as there are no bugs found there is little reason to make changes. I will of course continue to update it to be compatible with new Zig releases as needed.

Website Rewrite

You may have noticed that my website looks a bit different than it used to and has a few new pages. I’d been wanting to add some new pages for a while but had entirely forgotten how to use hugo. Since I didn’t like hugo very much in practice anyways, I decided to switch to something more transparent and chose Bagatto. It has been lovely to work with and I’m much more confident that I’ll remember how to modify and extend my website years from now. Source code here for the curious. This was also my first time using Janet (or any lispy language) for anything “real” and I found the experience very pleasant.

Donate

If my work on river and waylock adds value to your life and you’d like to support me financially you can find donation information here.

May 2022 Status Update

2022-05-23T00:00:00Z

Welcome back to my blog, it’s been a while. Over the past few months I’ve been busier with other aspects of my life than expected, hence the lack of status updates. Despite that, I’ve made progress on various fronts.

Waylock 0.4.0 and Rewrite

Yesterday I finally released waylock 0.4.0 which has been rewritten in Zig. It now uses the ext-session-lock-v1 protocol, which I worked on earlier this year and discussed in my February 2022 update. Unfortunately, river itself does not yet support this protocol. The work is already done and there’s been a pull request implementing it open for quite some time, the only thing I’m waiting on is a wlroots release including the session lock implementation. I intend to spend some more time working on upstream wlroots to help tie up various loose ends before 0.16.0 and further develop the scene graph API.

Rewriting waylock from Rust into Zig has made me think once again about the different trade-offs made by the two languages and their ecosystems. Looking at the Rust code I wrote several years ago I am rather appalled by how many dependencies it has. If I’ve managed to use the cargo tooling correctly, I count 48 crates that waylock 0.3.5 depends on in addition to linking the system libxkbcommon and PAM libraries. That is a lot of code running inside my application that I never read let alone seriously audited.

To compare, waylock 0.4.0 depends only on libwayland, libxkbcommon, and PAM as well as thin Zig bindings I have written to make their APIs a bit more type safe.

This is also reflected in the binary size of waylock 0.3.5 vs 0.4.0. A stripped release build of the Rust version weighs in at 1.7MiB or, if the native Rust Wayland implementation is replaced by linking libwayland, 1.6MiB. A stripped “release-safe” build of the Zig version with all runtime safety checks and assertions enabled is just 69KiB.

If this makes you wonder what all that extra code in the Rust version was doing, waylock 0.3.5 did have a few more features than 0.4.0 such as reading a config file. However, even after removing the config file feature out of curiosity, the Rust version was still 1.5MiB.

The only real answer I have to this question is that the Rust version and its dependencies do a lot of abstraction, and that abstractions are seldom “zero cost” in practice despite what people may tell you.

zig-wayland Improvements

Rewriting waylock in Zig also led me to reexamine some aspects of zig-wayland, particularly regarding its usage in client applications. The scanner (which generates zig bindings from XML protocol specifications) now requires the user to explicitly request code generation for each global Wayland interface used. For example, the application must now call e.g.

scanner.generate("wl_compositor", 4);

as part of its build process, passing the global interface name and the version for which to generate code. In this example the wl_surface.offset request would not be generated as it is only available since version 5.

(If you’re not familiar with Wayland, wl_surface is created through wl_compositor and inherits its version, see the Wayland docs on protocol versioning for more information.)

This solves the outstanding forward compatibility issue and allows building against newer system Wayland protocol versions than the application supports.

The knowledge of what maximum version a client application supports at compile time allows us to make another improvement as well. One of the most common Wayland client bugs I’ve seen in clients using libwayland is passing the interface version received from the server in the wl_registry.global event straight to wl_registry_bind(). A forwards compatible client must check the version advertised by the server against the maximum version the client supports, otherwise the client will be terminated when the server sends events unknown to the client.

This is a particularly nasty bug because everything will work fine until your software is around long enough for Wayland protocols to evolve. For example, Chromium recently fixed this bug. I’ve also written this bug a few times myself, including in previous Rust versions of waylock.

That’s why it’s pretty cool that zig-wayland now makes this bug impossible. Since we know the maximum version the client supports at build time, it’s trivial to insert the required version check into the generated code for zig-wayland’s wl_registry_bind() equivalent as a safeguard.

River Progress

River has also gained some nice new features recently:

Automatic cursor hiding after a timeout or when typing was contributed by Duncan Overbruck. On moving the cursor after it has been hidden it will be shown again.

Initial support for the idle-inhibit protocol was contributed by dfangx. No longer shall swayidle put your monitor to sleep while watching a movie in mpv!

Mapping of lid and tablet switches was contributed by Peter Kaplan. Now you can have a command run when you close the lid of your laptop!

Peter Kaplan also contributed a very nice feature for people switching between multiple keyboard layouts: layout independent mappings. The riverctl map command has gained a -layout option taking an index into the list of layouts set with XKB_DEFAULT_LAYOUT. If passed, keyboard input will always be interpreted using the given layout, ignoring the currently active xkb layout.

Note that these features are not yet available in a released version of river, only on the git master branch. I plan to release river 0.2.0 shortly after wlroots 0.16.0 is released.

Thanks for reading and till next time!

February 2022 Status Update

2022-02-11T00:00:00Z

Hello again! It’s been nearly a month and a half since my last status update. Since I hope to fall into a monthly rhythm with these this is a decent start, look for the next one around the middle of March. I’ve also gotten a proper Atom Feed set up for this blog now for those of you using feed readers of some kind.

I spent a fair bit of time over the past month an a half working on a better screenlocking protocol for Wayland. This resulted in the ext-session-lock-v1 protocol which was merged into the upstream wayland-protocols repository three weeks ago. This marks the first upstream Wayland protocol I have written and the first protocol in the ext- namespace to be accepted into wayland-protocols!

The ext-session-lock-v1 protocol makes it possible for lockscreens implemented outside of the Wayland compositor to be far more secure, compared to the status quo wlr-input-inhibitor-v1 plus wlr-layer-shell-v1 solution that has been used by swaylock and waylock thus far. Currently if, for example, swaylock crashes while the session is locked then the session will no longer be locked. With ext-session-lock-v1, the session does not unlock if the client crashes. Furthermore, hotplugging outputs is inherently racy with the current solution which means that a few frames of the unlocked session may be visible if a monitor is plugged in while the session is locked. Again, with ext-session-lock-v1 this problem is solved.

Many thanks to Simon Ser for the excellent code reviews of the protocol and wlroots implementation, as well as for updating swaylock to use ext-session-lock-v1. I’ve implemented ext-session-lock-v1 for river but am waiting for the 0.16.0 wlroots release to merge it as river tracks the latest wlroots release not the master branch. I’ve also started rewriting waylock from the ground up in Zig with a much higher focus on security and benefiting from the experience I’ve gained over the past 2 years of doing this stuff. Until that work is complete I recommend using swaylock instead.

The goal of this work is to ensure, to the best of my ability, that jwz doesn’t have to say “I told you so” about screen locking on my Wayland compositor. Once the security problem has been satisfactorily solved I want to explore making fun graphics possible without compromising security, but that may take me a long time to get around to.

I released river 0.1.3 about a week ago. It includes quite a few bug fixes, so if you’re not yet using river 0.1.3 and wlroots 0.15.1 I’d highly recommend upgrading. I also decided to change river’s license from GPL-3.0-or-later to GPL-3.0-only with this release, primarily because I decided that I do not feel comfortable licensing software under a hypothetical future license version which is outside my control. What if I disagree with the changes made? I’m happy with locking in on version 3 of the GPL for river as there’s no real need to worry about the compatibility benefits of the “or later” clause as river is not a library.

That’s all for now, see you all in March!

2021 Year's End Status Update

2022-01-01T00:00:00Z

Hello all! This is my first ever status update so I’ve ambitiously decided to cover all of 2021. In the future I intend to write these updates on a monthly basis and provide a bit more detail. Since so much has happened in the past year I’ll be leaving out a lot, but here are some of the highlights.

In January I spent most of my time on river, fixing bugs and implementing an experimental river-options protocol.

FOSDEM 2021 took place online during first weekend of February and I gave a talk on my type safe Zig bindings for wlroots/libwayland. Around the same time I got sucked into Andrew Kelley’s work applying data oriented design principles to Zig’s Abstract Syntax Tree. I collaborated with him on the data structure that became std.MultiArrayList and contributed a significant amount of code to his PR branch. Andrew gave a talk on this subject at Handmade Seattle later on in November which I highly recommend checking out if you haven’t seen it yet.

In March I joined the team working on TigerBeetle and got paid to write Zig code for the first time. I also contributed to Andrew’s further application of data oriented design to the ZIR memory layout.

In April my stalwart collaborator Leon Plickat and I finally got the river-layout protocol merged to master branch. We’d been discussing and working on this off and on for ~6 months at that point so it was really great to get it merged and start daily driving it. As is normal with such large changes, there were still some rough edges to be smoothed out and I bumped the protocol to version 2 and removed the river-options protocol shortly afterwards.

One of the critical missing features for river at this point in time was damage tracking support to improve performance and save battery life. To remedy this I implemented basic yes/no damage tracking in May.

Zig 0.8.0 was released in the first week of June, which included several improvements I made to Zig’s handling of linking libc. These improvements directly affected users building river, solving a few long-standing issues on that front. Around this time I also started to think about a first river release and resumed my effort to properly package zig software for void Linux. This lead to a series of zig patches to allow for cross compilation while linking system libraries and integration into void Linux’s build system.

In July I focused on stabilizing and simplifying river’s behavior, aiming for consistency and predictability. As part of this, I further simplified our layout protocol and cleaned up all of river’s user-facing interfaces. The goal was to get a first release out the door, but unfortunately exams got in the way.

Throughout August and September I had relatively little time for my open source work as I was busy with exams at my university. I did however manage to keep up with bug reports from river’s small but steadily growing number of users fairly well. In retrospect, it was nice to allow bug reports to trickle in for another couple months before tagging the first release as the end result was much more polished.

I ended up changing domains for my personal website and email from ifreund.xyz to isaacfreund.com after reading this post in October. It makes me sad that this is the way things are, but I’d rather die on a different hill. I set up GitHub Sponsors and Liberapay around this time and was pleasantly surprised to immediately see some support. Thank you to all my current sponsors, you are helping make my open source work sustainable in the long term!

On the river front, I spent October fixing every bug I could and finally tagged the river 0.1.0 release on November 2nd. If you haven’t yet seen my blog post introducing river you may want to check that out. Later in November my focus shifted to helping push the new wlroots scene graph API forward, getting tinywl using it as well as other improvements.

This wlroots work carried on into December, when wlroots 0.15.0 was released. As it so happened, Zig 0.9.0 was released only a few days later. Thus, river 0.1.1 and river 0.1.2 were released in quick succession, fixing several bugs and updating the wlroots and Zig version requirements.

I also ended up starting and finishing a tiny new project in December, dumb_runtime_dir, to replace my older, more complex rundird project. This is useful on systems that do not run logind, opting for a simpler alternative such as seatd instead.

2021 was an action packed year for me, I’m very happy looking back on the progress I’ve made on river and the surrounding open source ecosystem. Here’s to another year of work towards building my ideal Linux graphical environment in 2022!

Introducing River, a Dynamic Tiling Wayland Compositor

2021-11-03T00:00:00Z

In the spring of 2020 I found myself hooked on Wayland thanks to sway but increasingly frustrated with the i3 style window management sway implements. I tried several of the other more mature Wayland compositors including hikari and Wayfire but didn’t enjoy them any more than sway. I wanted dynamic tiling window management similar to dwm but on Wayland and without dwm’s configuration through patching the source code approach.

As I had a newfound abundance of free time at home in front of my computer thanks to the global pandemic that was ramping up that spring, I decided to write my own Wayland compositor. Thus, river was born.

Features

The core guiding principle in river’s design is that its behavior should be predictable. This means keeping things as simple as possible, reducing implicit state the user must keep in their head while using river.

River’s window management is based on a linear stack of windows much like dwm. These windows are arranged by a separate program called a layout generator. Users are encouraged to write and share their own layout generators, they are simply Wayland clients which implement a custom river-layout-v3 protocol. You can find links to several nice ones on this wiki page. River also ships with a layout generator, rivertile, that provides a few simple layouts for those who don’t need anything custom or fancy.

Instead of traditional workspaces, river supports tags. Each window may be assigned one or more tags and multiple tags may be displayed at once. Again, this behavior is strongly influenced by dwm.

All configuration and control of river happens at runtime through the riverctl tool. It can be used to create keybindings, move focus between windows, set the border color, etc. River doesn’t have any traditional configuration file, instead it runs an arbitrary executable on startup which is generally a shell script invoking riverctl to setup the user’s desired configuration.

River 0.1.0

I’ve been using river as my daily driver for well over a year now, and am happy to announce the first release today, river 0.1.0. In recent months there has been little churn in river’s codebase and it is currently quite stable and bug free. Because of this, people seem to have started using it. As I plan to cause a lot more churn on the master branch in the near future which will inevitably create new bugs and break people’s configuration, this is the perfect time for a release.

I’d like to thank everyone who has contributed code, documentation and bug reports to river. In particular, thanks to Leon Henrik Plickat for his consistent, high quality collaboration since the early days of the project. Without all of you this release would not have been possible.

The Future of River

Although I consider river useful enough today to tag a first release, it is not yet complete. The core functionality and standard use cases are well supported but river is not yet nearly as flexible as I would like it to be. I have several ideas that I plan to try out to improve river’s flexibility and ease of customization, but this will take time. For this reason, users should expect widely breaking changes to how river is configured and controlled before we approach a stable 1.0 release. Fear not though, the core functionality and spirit of river are here to stay!

If you’d like to contribute financially to my work on river, please consider sponsoring me on GitHub Sponsors or Liberapay. To those already donating, thank you so much for your support!