# tile-manager

A Rust Wayland tiling compositor project, built in small stages.

The target is a simple desktop tile manager in the same general space as Hyprland or niri, but with a much narrower first scope:

1. nested compositor first
2. one output first
3. one workspace first
4. one tiling layout first

This project should grow in the same order a Codecrafters-style guide would teach it: build the minimum working compositor, then add input, tiling, workspaces, multi-output, and finally standalone session support and polish.

## Scope

This is not an X11 window manager.

It is intended to become a Wayland compositor that can:

1. accept Wayland clients
2. track windows, focus, outputs, and workspaces
3. process keyboard and pointer input
4. render surfaces
5. apply a tiling layout

## Planned Stack

Primary Rust crates:

- `smithay`: Wayland compositor foundation
- `calloop`: event loop
- `xkbcommon`: keyboard layout and modifiers
- `tracing`: structured logging
- `tracing-subscriber`: log output/filtering
- `anyhow`: application-level error handling
- `thiserror`: typed internal errors
- `bitflags`: internal state flags

Likely later additions:

- `serde` + `toml`: config loading
- `clap`: CLI flags
- `zbus`: desktop integration
- XWayland-related Smithay features: X11 app support

## Development Order

### Stage 0: Nested compositor

Start inside an existing desktop session before touching DRM/KMS.

Goal:

- boot the compositor
- open a Wayland client
- confirm logs and state changes

### Stage 1: Event loop and Wayland server

Implement:

1. logging setup
2. `calloop::EventLoop`
3. Wayland display state
4. core Smithay globals

Deliverable:

- the process starts and stays alive cleanly

### Stage 2: XDG toplevel support

Implement:

1. compositor state
2. shared memory support
3. XDG shell support
4. seat support

Deliverable:

- a client can create a toplevel surface

### Stage 3: Internal state model

Add plain Rust types for:

- compositor state
- outputs
- seats
- workspaces
- windows
- tile layout state

Deliverable:

- stable state snapshots after every map/unmap/focus/layout event

### Stage 4: Render one output

Implement:

1. one output
2. solid background
3. mapped surface rendering
4. frame presentation

Deliverable:

- one client is visible on screen

### Stage 5: Input and bindings

Implement:

1. keyboard input
2. pointer input
3. compositor modifier handling
4. a few core commands

Minimum commands:

- spawn terminal
- close focused window
- cycle focus

### Stage 6: Tiling

Start with one layout only.

Recommended first layouts:

1. equal columns
2. master-stack

Deliverable:

- new windows retile the workspace correctly

### Stage 7: Workspaces

Implement:

1. workspace switching
2. moving windows between workspaces
3. independent workspace layout state

### Stage 8: Multi-output

Implement:

1. output tracking
2. per-output active workspace
3. correct focus and new-window placement

### Stage 9: Standalone session

Only after the nested compositor is solid, add:

1. DRM/KMS
2. libinput
3. session/seat handling
4. VT switching

### Stage 10: Polish

Later features:

- config file
- IPC
- floating windows
- fullscreen
- layer-shell support
- screencopy
- animations
- XWayland

## Suggested Layout

```text
src/
  main.rs
  app.rs
  state.rs
  backend/
    mod.rs
    nested.rs
    tty.rs
  input/
    mod.rs
    keyboard.rs
    pointer.rs
    bindings.rs
  layout/
    mod.rs
    columns.rs
    master.rs
  shell/
    mod.rs
    xdg.rs
    window.rs
  render/
    mod.rs
    scene.rs
  workspace/
    mod.rs
  config/
    mod.rs
```

Guiding rule:

- keep Smithay integration near the edges
- keep layout and workspace logic in plain Rust types

## System Dependencies

The final compositor will also need Linux graphics/input libraries, depending on backend choice:

- `libwayland`
- `libxkbcommon`
- `libudev`
- `libinput`
- `libdrm`
- `gbm`
- `egl` / `gles2`
- `pixman`
- `xwayland` for X11 clients

## References

- Smithay docs: https://docs.rs/smithay/latest/smithay/
- Smithay project docs: https://smithay.github.io/smithay/smithay/
- wayland-server docs: https://smithay.github.io/wayland-rs/wayland_server/
- calloop docs: https://docs.rs/calloop/latest/calloop/
- xkbcommon docs: https://docs.rs/xkbcommon/latest/xkbcommon/

## Status

Right now the repo is still at the very beginning. The current documentation is the roadmap.

For a fuller step-by-step build guide, see [GUIDE.md](/home/henry/rust-projects/tile-manager/GUIDE.md).