Skip to content
sammwyyPublic

About

Minimal Wayland compositor

Resources

Stars

5 stars

Watchers

0 watching

Forks

Repository files navigation

Blair

A small, modern Wayland compositor that leaves the desktop yours.

Warning

Blair is under active development and is not yet intended for production or daily use.

Blair handles windows, workspaces, input, outputs, and session plumbing while leaving the rest to you. Choose your own bar, wallpaper, launcher, notifications, and shell. Coconut is an optional companion shell, never a requirement.

Highlights

  • Native Wayland compositor with nested Winit and direct DRM/KMS backends
  • Damage-tracked rendering, hardware cursors, and DRM overlay planes
  • Per-output workspaces and configurable tiling or floating layouts
  • Layered TOML configuration with safe hot reload
  • Configurable outputs, input, focus, decorations, autostart, and animations
  • D-Bus APIs for shells, panels, launchers, and external tools
  • Modern Wayland protocols including layer-shell, dmabuf, screencopy, and data control

Quick start

Create ~/.config/blair/config.toml:

[[autostart]]
command = "waybar"
restart = true

[[autostart]]
command = "swaybg -i ~/Pictures/wallpaper.png"

[[autostart]]
command = "mako"

[[bindings]]
keys = ["SUPER", "RETURN"]
exec = "foot"

[[bindings]]
keys = ["SUPER", "Q"]
action = "close"

No shell or main client is required. Use blair --run foot to start a one-off application for the current session; repeat --run when needed.

Configuration

Every setting is optional. Defaults provide click-to-focus, focused new windows, ten workspaces, automatic output selection, and animations.

Workspaces and layout

[[bindings]]
keys = ["SUPER", "1"]
action = "workspace"
value = 1

[workspaces]
count = 10
dynamic = false
wrap = true

[window]
layout = "tiling" # floating | tiling
work_area_padding = 16
gap = 8
master_ratio = 0.55

Workspaces are global identities, while each output displays a different one. Floating windows open centered; tiling assigns the first window a master column and stacks the rest beside it.

Rules and appearance

[[rules]]
app_id = "pavucontrol"
floating = true
size = [700, 500]

[decorations]
mode = "auto" # server | hybrid | client | auto | none
border_width = 2
corner_radius = 8
titlebar_height = 28

mode = "hybrid" forces server-side decoration negotiation, but leaves the client at its original size and draws only the configured window controls over its top-right corner. It does not draw a titlebar, title text, icon, border, or draggable server region.

Rules match app_id, title, or regex and can set layout, workspace, output, size, position, opacity, stacking, and decorations.

Outputs, input, and motion

[outputs."DP-1"]
enabled = true
mode = "2560x1440@165"
position = [0, 0]
scale = 1.0
vrr = true

[input.touchpad]
tap = true
natural_scroll = false
disable_while_typing = true

[animations]
enabled = true

Without explicit output entries, Blair uses a safe automatic profile. Cursor settings fall back to XCURSOR_THEME and XCURSOR_SIZE and are passed to applications Blair starts.

general.output_mode = "auto" is the default. It selects the monitor's preferred mode, or the highest resolution and refresh rate when the monitor does not mark one. mode = "auto" on an output does the same. A saved WIDTHxHEIGHT@REFRESH mode takes precedence. output_mode = "initial" with general.initial_output_size = [1366, 768] requests that size instead. Physical outputs advertise all their supported modes through Wayland and DisplayInfo on D-Bus. ApplyDisplayMode previews a supported size and refresh rate for 15 seconds; ConfirmDisplayMode saves it in the user configuration, while RevertDisplayMode or the timeout restores the previous mode. Nested outputs report their host window size and do not offer physical mode changes. The DRM backend currently activates one connector; these controls apply to that output.

Development

DEVELOPMENT.md covers the required checkout layout, native dependencies for Arch, Debian/Ubuntu, Fedora/RHEL, and openSUSE, the distinction between libseat and seatd, testing, and local installation.

For a nested local session:

RUST_LOG=blair=debug,warn cargo run -p blair

Configuration model

--profile user is the default. Later TOML layers override earlier ones:

built-in defaults
/etc/blair/config.toml
/etc/blair/conf.d/*.toml
~/.config/blair/config.toml
~/.config/blair/conf.d/*.toml

--profile <id> loads /etc/blair/profiles/<id>.toml over the built-in defaults and does not read the user directory. Kiosk mode is general.kiosk in that file. Settings changed at runtime are stored only for the user profile.

Blair validates every layer before applying it, so an invalid edit preserves the previous configuration. See the bundled example for the full schema.

Architecture

Area Implementation
Compositor Smithay, XDG shell/decoration, layer-shell, clipboard and DnD
Backends Winit nested development; DRM/KMS, libinput, and libseat direct sessions
Rendering GLES2, damage tracking, DRM planes, shader-based decorations
Integration Transport-neutral CompositorApi, Transport, and EventChannel
Default transport Optional D-Bus (integrations.dbus = true)

Blair supports the core Wayland protocols plus xdg-shell, xdg-decoration, layer-shell, linux-dmabuf, presentation-time, fractional-scale, screencopy, data control, and KDE server decoration. Tools that use wlr-screencopy, such as grim and wf-recorder, use the configured screen-capture permission policy.

The D-Bus service is org.blair.Compositor at /org/blair/Compositor, using the org.blair.Compositor1 interface. It exposes window and workspace control, outputs, settings, shortcuts, screenshots, and render statistics.

Screen capture permissions

integrations.screencopy governs both wlr-screencopy requests and the org.blair.Compositor1.Screenshot D-Bus method:

Policy Behavior
ask (default) Ask Coconut's permission service; deny if unavailable.
ask-safe Ask the service; allow if unavailable.
allow Allow capture without a permission prompt.
deny Reject requests without contacting the permission service.

Install the current Coconut permission portal alongside Blair. The cancellable native protocol uses BeginRequest, WaitRequest, and CancelRequest on org.coconut.Permissions1. An older portal without those methods is treated as unavailable. Install the updated portal before running the updated compositor.

The compositor identifies Wayland clients from their socket credentials and D-Bus callers from their bus credentials. Subjects are executable paths or Flatpak application IDs. The caller cannot supply a different application's identity to the screenshot method.

Authorization is asynchronous, with at most 64 outstanding requests. A prompt for one application does not block requests for another or unrelated D-Bus methods. Admission rejects overload under every policy that uses the service; ask-safe does not bypass a full local authorization queue. Ordinary D-Bus calls have a separate limit of 128 pending compositor replies.

Capture verdicts use a bounded completion table and the compositor's wakeup source, so a full general command queue cannot discard them. Transport shutdown resolves pending requests using their configured unavailable-service policy. Frame destruction and client disconnection cancel the corresponding request. The portal closes a shared prompt only after its final waiter is cancelled. D-Bus client disconnection cancels its pending screenshot consent as well.

Validation includes private D-Bus service tests and Wayland protocol tests:

cargo test --workspace
cargo clippy --workspace --all-targets --no-deps -- -D warnings
cargo fmt --all -- --check

The capture lifecycle tests do not require a GPU. Tests marked as requiring EGL remain opt-in for native rendering validation.

Recovery

If a session becomes unresponsive, switch to a TTY with Ctrl+Alt+F2 and run:

pkill -9 blair

Session logs live in $XDG_STATE_HOME/blair/compositor.log or, by default, ~/.local/state/blair.

License

Blair is distributed under the Apache License 2.0.

About

Minimal Wayland compositor

Resources

Stars

5 stars

Watchers

0 watching

Forks

Releases

Packages

Contributors

Languages