# monolith plan

Crate layout and milestones. Decisions behind them are in `decisions.md`.

## Crates

The hard logic lives in crates with no smithay dependency, so it compiles fast and takes headless property tests.

| crate | smithay | contents |
|---|---|---|
| `planner` | no | multiphase planner, geometry, invariants, property tests |
| `motion` | no | beziers with exact `t`, best-effort velocity handoff, timelines sampled at presentation time |
| `layout` | no | tags (model B), homeless, slotmap tree, row stacking, expand, floating, scratchpads, commands, target rects |
| `config` | no | TOML schema, parsing, reload diffing, window rules |
| `ipc` | no | versioned JSONL message types shared by compositor and CLI |
| `render-vk` | yes | Vulkan renderer implementing smithay's renderer traits |
| `protocols` | yes | protocols monolith writes itself (ext-workspace, later tearing-control, output management, foreign-toplevel management, gamma) |
| `testkit` | yes | headless backend, sctk test clients, golden images, tree invariants |
| `monolith` (bin) | yes | state, shell glue, backends, frame scheduler, stage pipeline, `msg` and `spawn` subcommands |

`motion` and `planner` stay separate. The frame scheduler starts inside the binary.

## Backends

- **Nested** runs inside another Wayland compositor and is supported for the life of the project, not just during early development. It renders into dmabufs and attaches them to a host `wl_surface` through linux-dmabuf, so nested and DRM share one render-to-dmabuf path. Nested paces from the host's wp_presentation feedback, DRM from page-flip events, and clients get no wp_presentation from either yet. smithay's winit backend is EGL/GLES-only, so it is not used.
- **DRM** on bare metal from M5.
- **Headless** for `testkit`.

## Milestones

| # | milestone | notes |
|---|---|---|
| M0 | Scaffolding. jj repo, flake (crane, devshell, lavapipe), workspace skeleton, `nix flake check` gate, Tracy feature | |
| M1 | Planner spike. `planner` and `motion`, new planner for diagonal, cross-output and large merge groups, property tests over random layouts and interrupt sequences, plan visualiser | parallel with M2 |
| M2 | Nested compositor with the Vulkan renderer. Nested host backend, smithay renderer traits, shm and dmabuf import, xdg-shell, one output, one tag, lavapipe golden tests | proves the renderer |
| M3 | `layout` and tags. Model B, homeless, row stacking, expand, floating, scratchpads and sticky, ext-workspace, JSONL IPC and CLI, TOML config with reload, window rules | still nested |
| M4 | Animation integration. Planner wired in, presentation-time sampling, clamp-to-edge snapshots, spawn and close, transition-shader hook | |
| M5 | DRM backend. udev, libinput, session, smithay DRM compositor, deadline scheduler from flip timestamps, explicit sync, VRR with cursor throttling, hotplug and replug restore. Tested on NVIDIA and Intel | first bare metal |
| M6 | Daily-driver gate. layer-shell, session-lock, idle notify and inhibit, xdg-activation with launch context, lazy Xwayland, data-control, image-copy-capture and portals | switch from wry here |
| M7 | Performance. Off-thread shm upload, commit blockers, fullscreen direct scanout, SCHED_RR, global-priority queues, measured against the targets | |
| M8 | Gaming. smithay tearing patches, tearing-control, keyboard-shortcuts-inhibit, pointer constraints, cursor policy while tearing | |
| Later | Custom shaders, deck mode, i3-style titles, HDR and color, hybrid GPUs, output management, gamma | |