Ongoing

FocusWM

Systems Engineer · 2026 · 4 Months · 2 people · 3 min read

A memory-safe, high-performance Wayland compositor written in Rust that implements a master-stack tiling engine, multi-output management, and a tag-based window grouping system.

Overview

Developed FocusWM, a functional Wayland compositor from scratch using Rust and the Smithay library. The project brings the efficiency of traditional master-stack tiling to the modern Wayland protocol, eliminating legacy X11 overhead. It manages surface roles, input focus, and client-side decorations while maintaining a strict minimalist footprint.

Problem

Modern Wayland compositors are either overly complex or require massive configuration trees. I sought to build a 'functional-as-config' compositor that provides the rock-solid stability of memory safety while maintaining the specific master-stack layout logic where a primary window occupies the focal area and secondary windows stack vertically.

Constraints

  • Must be entirely memory-safe to prevent common compositor-level crashes
  • Requires native multi-output support via Wayland's xdg-output protocol
  • Must implement a tag-based visibility system (bitmask) for workspace management
  • Must minimize input-to-photon latency through direct kernel modesetting (KMS)

Approach

Utilized the Smithay framework to handle low-level DRM/KMS and libinput operations. I designed a custom state machine to manage Wayland surfaces and implemented a layout engine that recalculates window geometries based on a master-area ratio. For configuration, I utilized Rust's compilation unit to define keybindings directly, ensuring type-safe command execution.

Key Decisions

Master-Stack Tiling Engine

Reasoning:

To maximize productivity, I implemented a layout where the screen is split into two halves: a master area and a stack. This removes the cognitive load of manual window placement. I used a simple mathematical ratio to calculate geometries, allowing for instantaneous resizing of the entire stack when the master window is adjusted.

Alternatives considered:
  • Tree-based Tiling (Increased complexity in state management)
  • Floating-only (Inefficient for large-scale development workflows)

Tag-based Bitmask Visibility

Reasoning:

Instead of traditional workspaces, windows are assigned bits in a 32-bit integer. This allows a window to exist on multiple 'workspaces' simultaneously and enables the user to view multiple tags at once by applying a bitwise OR to the visibility mask.

Alternatives considered:
  • Linear Workspaces (Less flexible for complex project management)
  • Dynamic Tags (Harder to map to physical keybindings efficiently)

Tech Stack

  • Rust
  • Smithay
  • Wayland-rs
  • Libinput
  • DRM/KMS

Result & Impact

  • Zero segmentation faults/buffer overflows
    Memory Safety
  • < 15MB RAM
    Idle RAM Usage
  • Native refresh rate with zero tearing
    Performance

FocusWM successfully modernized the minimalist tiling experience. By moving to Wayland, I achieved perfect frame synchronization and eliminated the 'screen tearing' inherent in legacy protocols. The use of Rust ensured that the compositor remains stable even when handling complex multi-monitor hot-plugging scenarios.

Learnings

  • Wayland's surface-based architecture is significantly more asynchronous than legacy window-based models.
  • Handling input events at the compositor level requires a deep understanding of libinput and seat management.
  • Rust's ownership model is a perfect fit for managing the lifecycle of Wayland globals and client resources.

Additional Context

The most critical part of the project was the Surface Management logic. Unlike older protocols where the server handles most window attributes, a Wayland compositor is responsible for everything from rendering the cursor to calculating offsets for popups. By leveraging Smithay’s Space API, I was able to map Wayland surfaces to global coordinates and ensure that xdg_shell popups always remained relative to their parent windows.

The implementation of the Master-Stack Layout was the core technical hurdle. The engine monitors the number of active windows on a specific tag; if a single window is present, it is set to full screen (). When a second window is added, the screen is split based on a configurable mfact (master factor).

The stack logic then recursively tiles all remaining windows into the vertical space on the right, ensuring that no screen real estate is wasted and the workflow remains centered on the primary task.

All projects