tile-manager/AGENTS.md

AGENTS.md

Project intent

This repository is for building a Rust Wayland tiling compositor, not an X11 window manager.

The intended progression is:

1. nested compositor first
2. single output first
3. single workspace first
4. single tiling layout first
5. standalone session later

Use smithay as the foundation unless the user explicitly directs otherwise.

Working rules

• Prefer small, staged changes that match the roadmap in README.md and GUIDE.md.
• Do not jump straight to DRM/KMS, multi-monitor, XWayland, animations, or IPC unless the current lower stage is already solid.
• Keep compositor integration code near the edges of the codebase.
• Keep layout, workspace, and focus logic in plain Rust types that are testable without Smithay-heavy setup.
• Prefer one feature-complete path over many half-implemented systems.

Early priorities

When implementing the compositor, the preferred order is:

1. event loop boots
2. Wayland client connects
3. XDG toplevel maps
4. one surface renders
5. keyboard and pointer input work
6. one tiling layout works
7. workspaces work
8. multi-output works
9. standalone session works

Dependency guidance

Expected direct crates for the early stages:

• smithay
• calloop
• tracing
• tracing-subscriber
• xkbcommon
• anyhow
• thiserror
• bitflags

Possible later crates:

• serde
• toml
• clap
• zbus

Code structure guidance

Prefer a layout like:

src/
  main.rs
  app.rs
  state.rs
  backend/
  input/
  layout/
  shell/
  render/
  workspace/
  config/

Guidelines:

• backend/ should isolate nested vs tty/session-specific code.
• layout/ should not depend heavily on Smithay types.
• shell/ should handle XDG/toplevel lifecycle.
• render/ should translate compositor state into frame output.
• workspace/ should own workspace and window placement policy.

Documentation guidance

• If the architecture changes materially, update README.md.
• If the build progression or crate recommendations change materially, update GUIDE.md.
• Keep docs practical and staged rather than aspirational.

Validation guidance

• Prefer targeted checks over broad guesses.
• If code is added, run the narrowest useful verification command available.
• If verification is not possible, state that explicitly.