monolith

# wry backend research reports

Raw reader reports on wry (jay fork) internals, gathered for monolith planning.

Paths are relative to `/home/bolt/code/wry` at `6df16858`. Wry forked from jay at `f73b4efe` (2026-08-16).

Status

- [x] Executor core (`src/async_engine*`)

- [x] io_uring, timers, cpu_worker, task usage

- [x] DRM/KMS metal backend and frame scheduling

- [x] Wire protocol and client handling

- [x] Vulkan renderer

- [x] Tree, transactions, multiphase animations

- [x] Process model, config, tests, utilities

- [x] Smithay extension points (comparison baseline)

---

## 0. Executor core

`src/async_engine.rs`, `src/async_engine/ae_task.rs`, `src/async_engine/ae_yield.rs`, about 500 lines total.

- Single threaded, `Rc` based, nothing is `Send`. Wakers use a custom `RawWakerVTable` with a non-atomic refcount (`NumCell`), so a waker crossing threads would be UB. The cpu_worker bridges threads with eventfds instead.

- One `Box<Task>` allocation per spawn. A wake pushes a two-word `Runnable` onto a `VecDeque`. No atomics or locks anywhere on the wake path.

- Task state is a bitset (`RUNNING`, `RUN_AGAIN`, `COMPLETED`, `EMPTIED`, `CANCELLED`). A wake while running sets `RUN_AGAIN` instead of double-queueing.

- Dropping the returned `SpawnedFuture` cancels the task, so lifetimes are structured by ownership. Awaiting it yields the task's output.

- Four ordered phases, `EventHandling`, `Layout`, `PostLayout`, `Present`. `dispatch()` drains phase 0 to a fixpoint, then phase 1, and so on. Work woken into an earlier phase by a later one waits for the next pass. After all phases the iteration counter bumps and `yield_now()` waiters wake.

- `now()` / `now_rt()` are cached per pass, so everything in one pass sees the same timestamp.

- `spawn` defaults to `EventHandling`. `spawn2` pins a phase.

How the phases are used (`src/compositor.rs:598-745`). About 38 long-lived global tasks follow a dirty-queue pattern. Example `container_layout` (`src/tree/container.rs:2706`) loops on `state.pending_container_layout.pop().await` and checks a `layout_scheduled` flag. The task lives in `Phase::Layout`, so any number of requests that dirty a container during event handling collapse into one layout pass. The same pattern drives render positions, title textures, output render data, popup positioning, tree serial groups, configurables (all `PostLayout`), and screencast and present loops (`Present`). Client send tasks are `PostLayout` (`src/client/tasks.rs:27`), so events generated during a pass are flushed once after layout.

---

## 1. io_uring, timers, cpu_worker, task usage

### 1.1 io_uring layer (`src/io_uring.rs`, `src/io_uring/ops/`)

Opcodes wrapped, one module each (`src/io_uring/ops.rs:4-19`). `READ`/`WRITE` (`ops/read_write.rs:18-30`), `READ`/`WRITE` no-cancel with explicit offset (`ops/read_write_no_cancel.rs:21-58`), `WRITE` vec (`ops/read_write_vec.rs:29-86`), `WRITEV` (`ops/writev_external.rs:25-47`), `RECVMSG` (`ops/recvmsg.rs:18-83`), `SENDMSG` (`ops/sendmsg.rs:22-85`), `POLL_ADD` (`ops/poll.rs:17-42`, external callback variant `ops/poll_external.rs:35-74`), `TIMEOUT` (`ops/timeout.rs:28-44`, external `ops/timeout_external.rs:49-73`), `LINK_TIMEOUT` (`ops/timeout_link.rs:18-29`), `ACCEPT` (`ops/accept.rs:15-37`), `CONNECT` (`ops/connect.rs:19-39`), `ASYNC_CANCEL` (`ops/async_cancel.rs:16-24`), `FUTEX_WAIT`/`FUTEX_WAKE` (`ops/futex.rs:33-75`), `READ_MULTISHOT` (`ops/read_multishot.rs:49-77`). A provided buffer-ring helper exists (`buffer_ring.rs:79-173`) but outside tests is only wired to multishot reads.

Setup has no `SQPOLL` and no registered fds/buffers on the hot path. `IoUring::new` tries `SUBMIT_ALL|COOP_TASKRUN|SINGLE_ISSUER|DEFER_TASKRUN` then drops one flag at a time on `ENOSYS` (`src/io_uring.rs:131-154`), and hard-requires `NODROP` (`src/io_uring.rs:155-157`). Rings are `mmap`ed directly, queue depth 32 on both main and worker rings (`src/compositor.rs:276`, `src/cpu_worker.rs:367`).

Submit. `encode` (`src/io_uring.rs:488-525`) drains `to_encode` into the SQ while space remains, reserves two slots for `has_timeout` ops, and sets `IOSQE_IO_LINK` on the parent so the following `LINK_TIMEOUT` fires as a link (`src/io_uring.rs:516-518`, `ops/timeout_link.rs:40-46`). Used by `write` and `sendmsg` with absolute `Time` (`ops/read_write.rs:32-61`, `ops/sendmsg.rs:74-83`).

Enter/wait. `run` (`src/io_uring.rs:400-453`) is the only blocking point. An empty queue submits `0` and waits for `1` with `GETEVENTS`. Pending submits with empty `to_encode` submit `to_submit` and wait for `1`. Non-empty `to_encode` submits `u32::MAX` with no wait and loops to encode more (`src/io_uring.rs:417-424`). `yields` force `min_complete=0` (`src/io_uring.rs:425-427`). `EAGAIN|EBUSY|EINTR` are ignored, other `enter` errors are fatal (`src/io_uring.rs:438-443`). A short submit retries with a pure wait (`src/io_uring.rs:444-451`). On teardown `kill` encodes, submits `u32::MAX`, then waits until `tasks` empties (`src/io_uring.rs:594-617`).

Wakeup. Almost every awaitable op takes `pending_results.acquire()` (`src/io_uring/pending_result.rs:21-37`), stores a clone in the task, schedules a pooled task struct, and awaits it (e.g. `ops/read_write.rs:40-60`). `dispatch_completions` matches `user_data` to the task, with `CQE_F_MORE` routed to `complete_partial` for multishot and terminal CQEs routed to `task.complete` (`src/io_uring.rs:455-486`). `PendingResult::complete` stores `res` and wakes the `Waker` (`src/io_uring/pending_result.rs:66-74`). `poll` translates negative `res` to `OsError` (`src/io_uring/pending_result.rs:105-122`). Non-`Future` completions use `PollCallback`, `TimeoutCallback`, `WritevData::done`, `ReadMultishotCallback` (`ops/poll_external.rs:15-17`, `ops/timeout_external.rs:16-18`, `ops/writev_external.rs:20-24`, `ops/read_multishot.rs:28-31`).

Cancel. Dropping an op future cancels it, because the future owns a `Cancellable` whose `Drop` calls `cancel_task` (`src/io_uring.rs:527-544`, `src/io_uring.rs:640-644`). Not-yet-encoded ops complete locally with synthetic `ECANCELED` (`src/io_uring.rs:542-554`). In-kernel ops get an `ASYNC_CANCEL` by `user_data` (`ops/async_cancel.rs:16-24`, `ops/async_cancel.rs:41-44`). `is_cancel` tasks are exempt from `kill` cancellation (`src/io_uring.rs:596-604`). `PendingPoll`, `PendingTimeout`, `PendingReadMultishot` `Drop` impls do the same (`ops/poll_external.rs:25-33`, `ops/timeout_external.rs:26-34`, `ops/read_multishot.rs:39-47`). `read/write_no_cancel` instead forbids userspace cancel with an `on_drop` panic guard, for worker-thread shm I/O (`ops/read_write_no_cancel.rs:92-96`).

No epoll fallback. `CreateUring`/`NoDrop` become `CompositorError::IoUringError` and exit (`src/io_uring.rs:96-102`, `src/compositor.rs:227-241`, `src/compositor.rs:275-276`). Grep finds no epoll/calloop fallback.

### 1.2 Main loop, one iteration (`src/io_uring.rs:400-453`)

Bump `iteration`, wake `yields` wakers, then loop `eng.dispatch()` plus `dispatch_completions()` until no more CQEs were consumed. Then `encode()` queued SQEs, accumulating `to_submit`, then one `io_uring_enter` with the wait policy above. Startup order is engine, ring 32, signal handler, wheel, run-toplevel, cpu worker, eventfd cache, then `ring.run()` (`src/compositor.rs:275-286`, `src/compositor.rs:530-535`). The `compositor` future only runs backend setup. Blocking lives in the ring (`src/compositor.rs:538-588`).

Unusual. Ready futures are drained to quiescence before entering the kernel, and `Debouncer` plus `yields` let hot paths skip the blocking wait (`src/io_uring/debounce.rs:15-34`, `src/io_uring.rs:425-427`).

### 1.3 Timers

`wheel.rs` is a single-`timerfd`, heap-multiplexed wheel (`src/wheel.rs:102-114`). `Wheel::new` creates a `CLOCK_MONOTONIC` `timerfd` and spawns `dispatch` (`src/wheel.rs:117-137`). `timeout(ms)` rounds to ms, re-arms with `TFD_TIMER_ABSTIME` only if earlier than the armed expiry, pushes `{expiration,id}` on a `BinaryHeap`, and registers the waiter (`src/wheel.rs:156-194`, `src/time.rs:34-46`). `dispatch_once` does `ring.read(timerfd)` then completes every due entry and re-arms to the next live entry, skipping cancelled ids (`src/wheel.rs:218-254`). Waiters are manual `Future`s storing a `Waker` (`src/wheel.rs:65-100`). `Drop` unregisters and recycles (`src/wheel.rs:78-87`). Consumers include client shutdown 5s (`src/client/tasks.rs:35`) and cursor tick (`src/tasks/hardware_cursor.rs:17-22`).

Separately, `TimerFd::expired` is `ring.read(timerfd)` plus `timerfd_settime` programming (`src/utils/timer.rs:42-67`), used by idle, 40Hz latch, damage, config, virtual-output (`src/tasks/idle.rs:14-20`, `src/tasks/const_clock.rs:19-35`, `src/virtual_output.rs:731`). Raw `ring.timeout(nsec)` with `IORING_TIMEOUT_ABS` is used for present/vblank, transactions, sqlite, session (`src/io_uring/ops/timeout.rs:27-44`, `src/virtual_output.rs:475`, `src/output_schedule.rs:172-174`, `src/transactions.rs:453`).

### 1.4 cpu_worker (`src/cpu_worker.rs`, `src/cpu_worker/jobs/`)

One background thread named `cpu worker` with its own `AsyncEngine` plus ring depth 32 (`src/cpu_worker.rs:275-294`, `src/cpu_worker.rs:366-386`). `CpuJob::work` returns the thread-side `CpuWork`, and `completed` runs back on the main thread (`src/cpu_worker.rs:33-50`).

Main submits with `submit`, leaking the job box and queueing `Job::New{id, *mut dyn CpuWork}` on an `AsyncQueue`, returning a `PendingJob` (`src/cpu_worker.rs:323-339`). An `equeue_jobs` task moves it under lock to the shared `VecDeque` and writes the `have_new_jobs` eventfd (`src/cpu_worker.rs:249-261`). The worker `ring.read`s that eventfd and runs `CpuWork::run`. `None` completes synchronously, `Some(AsyncCpuWork)` is spawned on the worker engine until `WorkCompletion::complete` (`src/cpu_worker.rs:425-473`, `src/cpu_worker.rs:68-77`). Completion pushes the id to the shared completed queue, signals a condvar for sync waiters, and writes `have_completed_jobs` (`src/cpu_worker.rs:475-487`). The main `wait_for_completions` task `ring.read`s it and invokes `job.completed()` (`src/cpu_worker.rs:216-247`). Dropping a pending job warns, sends `Job::Cancel`, and blocks dispatching until gone. `detach` marks it abandoned (`src/cpu_worker.rs:151-204`).

Call sites, all via `cpu.submit`.

- `CloseMemWork`, munmap off-thread, detached (`src/clientmem.rs:211-215`)

- Text `RenderJob` (`src/text.rs:528`)

- Vulkan allocator `FreeJob` and `AllocJob` (`src/gfx_apis/vulkan/allocator.rs:185`, `src/gfx_apis/vulkan/allocator.rs:303`)

- shm transfers, `ImgCopyWork` for pointer-backed and `ReadWriteWork` for fd-backed mem (`src/gfx_apis/vulkan/transfer.rs:505`, `src/gfx_apis/vulkan/transfer.rs:539`, `src/cpu_worker/jobs/img_copy.rs:32-59`, `src/cpu_worker/jobs/read_write.rs:98-148`)

### 1.5 eventfd_cache (`src/eventfd_cache.rs`)

Avoids `eventfd()` churn and forgotten counter drains. Pools fds, `signaled` bools, and `Readable` callback objects (`src/eventfd_cache.rs:39-45`), with a `recycle` task spawned at creation (`src/eventfd_cache.rs:64-75`). `acquire` reuses or creates (`src/eventfd_cache.rs:77-89`). Async wait is `ring.readable` (`src/eventfd_cache.rs:97-104`). External wait reuses a pooled `Readable` through `readable_external` (`src/eventfd_cache.rs:120-137`). `Drop` of a still-signaled fd pushes it to `recycle`, which `ring.read`s each fd empty before returning it to the pool (`src/eventfd_cache.rs:156-224`). `return_signaled` recycles the bool only when the cache holds the last ref (`src/eventfd_cache.rs:208-215`). Held by `State` and passed to the copy-device registry (`src/compositor.rs:466-469`).

### 1.6 Long-lived tasks in `src/tasks/`

- `handle_backend_events`, demuxes the backend queue into connector/input/drm handlers (`src/tasks.rs:22-25`, `src/tasks/backend.rs:12-28`)

- `handle_slow_clients` / `handle_slow_ei_clients`, backpressure kills via `check_queue_size` (`src/tasks.rs:27-35`, `src/tasks/slow_clients.rs:8-28`)

- `handle_const_40hz_latch`, dummy-output latch clock (`src/tasks.rs:37-44`)

- Per-connector `ConnectorHandler`, output lifecycle (`src/tasks/connector.rs:92-98`, `src/tasks/connector.rs:113-141`)

- Per-DRM-device handler (`src/tasks/drmdev.rs:74`)

- Per-input-device handler (`src/tasks/input_device.rs:48-58`)

- `idle`, `TimerFd`-driven DPMS/idle state machine (`src/tasks/idle.rs:13-32`, `src/compositor.rs:651`)

### 1.7 Spawn survey

`eng.spawn`/`spawn2` has 175 hits in 64 files.

- `start_global_event_handlers` alone spawns about 38 named globals covering backend events, slow clients, cursor tick, layout, render positions/titles/textures, output render, managers, idle, popups, screencast, damage, matchers, seats, sqlite, sessions, transactions (`src/compositor.rs:598-745`).

- Per client, 3 tasks per Wayland client plus 2-3 per EI client (`src/client/tasks.rs:20-28`, `src/ei/ei_client/ei_tasks.rs:21-27`, `src/client.rs:258-260`).

- Acceptors/listeners are async accept loops, Wayland secure and insecure, IPC, tagged, security-context, EI (`src/acceptor.rs:144-153`, `src/acceptor.rs:168-191`, `src/ipc.rs:114`, `src/tagged_acceptor.rs:84`, `src/security_context_acceptor.rs:90-95`, `src/ei/ei_acceptor.rs:124`).

- Protocol I/O is async everywhere. dbus auth/in/out, pipewire in/out, forker in/out, xcon in/out, tool clients (`src/dbus/auth.rs:45-50`, `src/pipewire/pw_con.rs:356-359`, `src/forker.rs:123-135`, `src/xcon.rs:469-522`).

- Xwayland is `xwayland::manage` plus `XWM` plus per-transfer shm copy tasks (`src/state.rs:1636`, `src/xwayland.rs:219`, `src/xwayland/xwm.rs:1788-1901`).

- Rendering/output is phased `spawn2` layout/present work plus per-output schedule, vblank, virtual-output, backend event/present tasks (`src/compositor.rs:611-680`, `src/tasks/connector.rs:186-189`, `src/virtual_output.rs:1023-1024`, `src/backends/x.rs:359-364`, `src/backends/metal/video.rs:1221`).

- Vulkan transfer/vblank await tasks are also spawned (`src/gfx_apis/vulkan/transfer.rs:582-627`).

Rough split of non-test spawns. Client/EI/IPC/dbus/pipewire about 35, render/layout/output/present about 45, backend/connector/DRM/input/seat about 15, xwayland/X11 about 8, global compositor/timer/sqlite/config about 25.

### 1.8 Client sockets

One supervisor plus receive, send, terminate tasks per client (`src/client/tasks.rs:18-44`). Receive parses with `WlBufFdIn` over `ring.recvmsg`, including SCM_RIGHTS fds (`src/client/tasks.rs:59-93`, `src/utils/buffd/wl_buf_in.rs:52-126`). Send buffers into `OutBufferSwapchain`. `commit` moves a non-empty `cur` to `pending`, and the send task waits on `flush_request`, swaps `pending` out, and `BufFdOut::flush`es each buffer with an absolute 5s `sendmsg` linked timeout (`src/client/tasks.rs:112-147`, `src/utils/buffd/buf_out.rs:57-91`, `src/utils/buffd/buf_out.rs:102-131`, `src/io_uring/ops/sendmsg.rs:32-85`). `ECANCELED` becomes `Timeout`, `EPIPE`/`ECONNRESET` become `Closed` (`src/utils/buffd/buf_out.rs:121-130`). Slow clients are reaped when `pending` exceeds 10 (`src/utils/buffd/buf_out.rs:48-59`, `src/client.rs:520`). Direct `recvmsg`/`sendmsg` with no userspace epoll shim. Generic bidirectional connections use the same pair through `BufIo` (`src/utils/bufio.rs:101-114`, `src/utils/bufio.rs:143-179`).

Notable vs calloop. Everything above plus pooled task structs, `PendingResult` slab recycling raw pointers, link-timeouts instead of timer races, and a second full runtime on the worker thread.

---

## 2. DRM/KMS metal backend and frame scheduling

### 2.1 KMS model

Atomic only. Device init enables `DRM_CLIENT_CAP_ATOMIC` with value 2 and then probes resources, planes, CRTCs, encoders (`src/backends/metal/video.rs:2030`, `src/backends/metal/video.rs:2032`, `src/backends/metal/video.rs:2040`). It also tries `DRM_CLIENT_CAP_PLANE_COLOR_PIPELINE` and records support (`src/backends/metal/video.rs:2035`).

Desired state is `BackendConnectorState` in `backend.rs` (`src/backend.rs:785`). Committed DRM state is split into `DrmPlaneState`, `DrmCrtcState`, `DrmConnectorState` plus property structs in transaction (`src/backends/metal/transaction.rs:71`). `create_transaction` clones live `drm_state` for every non-leased plane, CRTC and connector and stores requested connector state separately (`src/backends/metal/transaction.rs:221`).

`calculate_drm_state` assigns CRTCs, primary and cursor planes, checks formats and modifiers, allocates scanout buffers when needed, and picks modes, VRR, tearing, colorspace, EOTF and HDR blobs (`src/backends/metal/transaction.rs:314`). `calculate_change` diffs new property structs against live objects with `differs` and `prepare_conditional` and only emits changed objects (`src/backends/metal/transaction.rs:902`, `src/backends/metal/transaction.rs:928`, `src/backends/metal/transaction.rs:949`). It also resets unknown or vendor default properties when asked (`src/backends/metal/transaction.rs:874`).

`TEST_ONLY` is used in the prepare path. `MetalDeviceTransaction::prepare` calls `calculate_drm_state` then `calculate_change(true,false)` (`src/backends/metal/transaction.rs:1216`). When test is true it calls `Change::test` with `DRM_MODE_ATOMIC_ALLOW_MODESET`, which adds `DRM_MODE_ATOMIC_TEST_ONLY` in `video/drm.rs` (`src/backends/metal/transaction.rs:982`, `src/video/drm.rs:1097`). Failure surfaces as `AtomicTestFailed` (`src/backend/transaction.rs:124`).

Normal apply first commits with flags 0 then retries once with `ALLOW_MODESET` after logging (`src/backends/metal/transaction.rs:993`). After a successful kernel commit it swaps new state into live `drm_state`, connector, CRTC and plane objects with `mem::swap` and bumps the connector version (`src/backends/metal/transaction.rs:1092`, `src/backends/metal/transaction.rs:1100`). Rollback keeps the pre-apply state and reapplies it with `calculate_change(false,false)` (`src/backends/metal/transaction.rs:1194`). The generic wrapper also rolls back on drop (`src/backend/transaction.rs:248`). Device init has an extra recovery loop that retries init while disabling direct scanout, non-XRGB formats and non-default modes (`src/backends/metal/video.rs:2553`, `src/backends/metal/video.rs:2589`).

### 2.2 Planes

Types are `Overlay`, `Primary` and `Cursor` (`src/backends/metal/video.rs:1023`). The transaction carries `primary` plus `cursor` per CRTC (`src/backends/metal/transaction.rs:283`). Overlay planes are explicitly discarded during assignment, so compositing uses at most primary plus cursor (`src/backends/metal/transaction.rs:360`).

Cursor uses fixed `ARGB8888` (`src/backends/metal/transaction.rs:281`) and separate double-buffered cursor scanout buffers (`src/backends/metal/video.rs:628`). Cursor enable, move and swap produce `CursorProgrammingType::Enable` or `Disable` (`src/backends/metal/present.rs:127`).

Direct scanout puts a client dmabuf on the primary plane through `add_fb` instead of the compositor render buffer. It is attempted only when enabled and when `prepare_direct_scanout` succeeds (`src/backends/metal/present.rs:901`). That path rejects cross-device buffers unless the scanout device is the render device, rejects SHM, rejects buffers with pending lazy work, checks plane format and modifier support, and caches failures by a key of buffer ID, plane, CRTC, source and destination color descriptions, intent, gamma, cursor presence and pipeline mode (`src/backends/metal/present.rs:746`, `src/backends/metal/present.rs:778`, `src/backends/metal/present.rs:845`). A failed atomic commit with direct scanout retries once as a full composite and then marks that key impossible (`src/backends/metal/present.rs:337`).

### 2.3 Frame scheduling

Each connector spawns its own `present_loop` in phase `Present` (`src/backends/metal/video.rs:1220`). Page flip events arrive on a per-device task that awaits `DrmMaster::event`, which does an io_uring read on the DRM fd and parses `DRM_EVENT_FLIP_COMPLETE` and `DRM_EVENT_CRTC_SEQUENCE` (`src/backends/metal/video.rs:2268`, `src/video/drm.rs:590`, `src/video/drm.rs:607`).

The loop waits for `present_trigger` then requires both `buffers_idle` and `crtc_idle` (`src/backends/metal/present.rs:189`). For synced flips it computes `next_vblank - pre_commit_margin - post_commit_margin` and sleeps with `ring.timeout` until that deadline (`src/backends/metal/present.rs:203`). If already past the deadline it increments the expected sequence so a missed vblank can be detected (`src/backends/metal/present.rs:210`). Tearing flips skip that wait (`src/backends/metal/present.rs:203`).

It then calls `before_latch` with either now for tearing or `next_vblank_nsec` for synced output (`src/backends/metal/present.rs:218`). It aborts if the connector version changed while yielding (`src/backends/metal/present.rs:226`). Then `present_once` latches damage, renders or selects direct scanout, waits render then scanout fences, programs the atomic commit, and on success marks CRTC busy and buffers busy (`src/backends/metal/present.rs:250`, `src/backends/metal/present.rs:314`, `src/backends/metal/present.rs:387`).

`pre_commit_margin` starts at 16ms and `post_commit_margin` starts at 1.5ms (`src/backends/metal/present.rs:145`). The pre margin tracks the per-second maximum CPU time from wakeup through latch with a geometric decay of 0.5 (`src/backends/metal/present.rs:238`, `src/backends/metal/video.rs:1208`). The post margin grows by 500us per second containing missed flips and decays toward the device minimum otherwise (`src/backends/metal/present.rs:147`, `src/backends/metal/video.rs:2425`). Expected versus actual CRTC sequence decides misses (`src/backends/metal/video.rs:2378`).

Flip completion clears `pending_flip`, promotes `next_framebuffer` to `active_framebuffer`, sets `buffers_idle`, emits presentation feedback with `HW_COMPLETION` plus `VSYNC` and `ZERO_COPY` when applicable, then sets `crtc_idle` and reschedules if damage remains (`src/backends/metal/video.rs:2368`, `src/backends/metal/video.rs:2387`, `src/backends/metal/video.rs:2406`). It also maintains `next_vblank_nsec` from flip timestamps plus refresh interval and continuously queues `CRTC_SEQUENCE` for vblank timing unless emulation is active (`src/backends/metal/video.rs:2347`, `src/backends/metal/video.rs:2418`, `src/backends/metal/video.rs:867`). If queueing sequences returns `EOPNOTSUPP` it switches that output to vblank emulation (`src/backends/metal/video.rs:881`).

`output_schedule.rs` is separate from that pacing loop. It only throttles cursor updates in VRR mode. `latched` records present time and clears awaiting-latch flags (`src/output_schedule.rs:100`). `run_once` sleeps until `last_present + cursor_delta` when VRR plus a cursor change is pending, then damages either the hardware cursor or the connector (`src/output_schedule.rs:157`, `src/output_schedule.rs:187`). Tree latch plumbing calls `schedule.latched` from `OutputNode::latched` (`src/tree/output.rs:355`).

### 2.4 VRR and tearing

State carries `vrr` and `tearing` booleans (`src/backend.rs:792`). The transaction rejects VRR on connectors without `vrr_capable` and rejects tearing without atomic async flip support (`src/backends/metal/transaction.rs:766`, `src/backends/metal/transaction.rs:772`). `vrr_capable` comes from the `vrr_capable` property (`src/backends/metal/video.rs:1423`) and async support comes from `DRM_CAP_ATOMIC_ASYNC_PAGE_FLIP` (`src/video/drm.rs:404`).

Per-frame tearing is `persistent tearing AND supports_async_commit` (`src/backends/metal/present.rs:442`). The atomic commit first tries `NONBLOCK | EVENT | ASYNC`, and on failure falls back to synced `NONBLOCK | EVENT` while also attaching `IN_FENCE_FD` and requesting `OUT_FENCE_PTR` except on Nvidia (`src/backends/metal/present.rs:572`, `src/backends/metal/present.rs:581`). Any plane geometry change or cursor plane change forces the synced path (`src/backends/metal/present.rs:493`, `src/backends/metal/present.rs:516`).

### 2.5 Color management

`metal_cm` selects a KMS programming for each frame from source and destination `ColorDescription` values plus render intent, gamma LUT, cursor presence and pipeline selection (`src/backends/metal/video/metal_cm.rs:100`). It caches programmings, matcher results and blobs (`src/backends/metal/video/metal_cm.rs:60`). A programming can set plane `COLOR_PIPELINE`, plane colorop bypass, type, interpolation, data and multiplier, and CRTC gamma LUT (`src/backends/metal/video/metal_cm.rs:127`, `src/backends/metal/video/metal_cm.rs:138`, `src/backends/metal/video/metal_cm.rs:153`). Matching logic decides whether matrix, source EOTF, destination EOTF or client gamma are needed (`src/backends/metal/video/metal_cm/metal_cm_matcher.rs:124`). The minimum LUT size considered useful is 1024 (`src/backends/metal/video/metal_cm.rs:54`). On AMD with a cursor plane it disables plane pipelines as a driver workaround (`src/backends/metal/video/metal_cm.rs:185`).

`metal_cm_paths/generated.rs` holds generated static tables of `PlaneOpKind`, matrix, LUT and multiply variants used by the matcher (`src/backends/metal/video/metal_cm/metal_cm_paths/generated.rs:12`). The handwritten wrapper defines `Path`, plane and CRTC op accessors and criteria filters (`src/backends/metal/video/metal_cm/metal_cm_paths.rs:15`).

Legacy properties are also handled. CRTC defaults include `CTM`, `DEGAMMA_LUT`, `OUT_FENCE_PTR` and AMD regamma (`src/backends/metal/video.rs:1565`). Plane defaults include AMD blend, shaper, 3D LUT, HDR multiplier, alpha, blend mode, rotation and `COLOR_PIPELINE Bypass` for non-primary planes (`src/backends/metal/video.rs:1680`). Plane pipeline use is opt-in through `use_plane_color_pipelines`, default false (`src/backends/metal/video.rs:2123`, `src/backend.rs:672`).

HDR uses connector `Colorspace` and `HDR_OUTPUT_METADATA` plus EDID-derived PQ and BT2020 support, primaries and luminance (`src/backends/metal/video.rs:1351`, `src/backends/metal/video.rs:1452`, `src/backends/metal/video.rs:1500`). The transaction creates the HDR metadata blob from EOTF, primaries and luminance (`src/backends/metal/transaction.rs:802`, `src/video/drm.rs:919`). The renderer supplies `cd`, linear and blend descriptions per frame, and `metal_cm` maps framebuffer description to output description (`src/backends/metal/present.rs:277`, `src/backends/metal/present.rs:889`).

### 2.6 Allocator and multi-GPU

Allocation is GBM based, not dumb buffers. It creates render and scanout `GbmBo` objects, imports them as gfx textures and framebuffers, and registers display framebuffers with `add_fb2` (`src/backends/metal/allocator.rs:878`, `src/backends/metal/allocator.rs:914`, `src/video/drm.rs:441`). GEM handles are cached (`src/video/drm.rs:484`). Modifier lists come from the plane `IN_FORMATS` blob, with fallback to the legacy plane format list (`src/backends/metal/video.rs:1616`, `src/video/drm.rs:531`).

Same-GPU scanout uses one BO for render and scanout (`src/backends/metal/allocator.rs:454`). Cross-GPU tries configurable prime methods in order `direct-pull`, `direct-push`, `udmabuf`, `direct-sampling` and `indirect-pull`, controlled by `WRY_PRIME_METHODS` (`src/backends/metal/allocator.rs:464`, `src/backends/metal/allocator.rs:615`, `src/backends/metal/allocator.rs:1528`). Each method intersects render write and read modifiers, plane modifiers and copy device source and destination modifiers, with copy paths forced to linear when available (`src/backends/metal/allocator.rs:1224`, `src/backends/metal/allocator.rs:1595`). Buffer kinds are direct sampling versus three copy device topologies plus direct push, which is noted as unsafe on AMD (`src/backends/metal/allocator.rs:85`, `src/backends/metal/allocator.rs:621`). Per-frame `copy_to_dev` performs the needed GPU or copy device transfer (`src/backends/metal/allocator.rs:154`).

### 2.7 Hotplug, session, lease

Hotplug watches `drm` and `input` through udev (`src/backends/metal.rs:307`). A task waits for the monitor fd with io_uring readable readiness and dispatches add versus change (`src/backends/metal/monitor.rs:42`). DRM change diffs kernel connectors against known connectors, emits `Disconnected` plus `Removed`, revokes affected leases, refreshes properties and display data, creates new connector objects and reinitializes the device (`src/backends/metal/video.rs:1844`).

Logind handling takes session control, takes each device fd, and installs pause and resume handlers (`src/backends/metal.rs:295`, `src/logind.rs:76`, `src/backends/metal/monitor.rs:402`). Pause marks the DRM device paused, hides non-desktop outputs and parks leases in `leases_to_break` (`src/backends/metal/monitor.rs:166`). Resume clears paused state, retries lease revocation, refreshes properties and reschedules presents (`src/backends/metal/monitor.rs:97`, `src/backends/metal/video.rs:2248`). Losing DRM master surfaces as `EACCES` on commit and is intentionally ignored per frame (`src/backends/metal/present.rs:379`).

Leases are supported for non-desktop outputs. Creation requires connected non-desktop connectors, allocates an unused CRTC and primary plane per connector, calls the kernel lease ioctl and emits `Unavailable` (`src/backends/metal/video.rs:264`, `src/video/drm.rs:638`). Dropping the lease object revokes it or parks it for later revocation and makes the connector available again (`src/backends/metal/video.rs:550`, `src/backends/metal/video.rs:514`).

### 2.8 Unusual choices

- Overlays are enumerated but never assigned, unlike many compositors (`src/backends/metal/transaction.rs:360`).

- Direct scanout participates in color pipeline search and has its own impossible-cache (`src/backends/metal/present.rs:778`).

- Frame timing uses two adaptive margins rather than a fixed deadline, with the pre margin from measured CPU time and the post margin from missed sequence counts (`src/backends/metal/present.rs:238`, `src/backends/metal/video.rs:2425`).

- The modeset path blocks on buffer clear and copy syncs inside transaction calculation and can synchronously poll a CRTC out fence before blanking (`src/backends/metal/transaction.rs:693`, `src/backends/metal/transaction.rs:843`).

- Init and hotplug paths reset unknown KMS properties to driver defaults, which helps against firmware or desktop leftover state (`src/backends/metal/transaction.rs:886`, `src/backends/metal/video.rs:2589`).

---

## 3. Wire protocol and client handling

### 3.1 Protocol description format

`wire/` holds a custom DSL, one file per interface. `wire/wl_surface.txt:1-8` shows `request destroy`, typed fields, `(destructor)`, `(since = 2)`, `(new)`. No XML is stored in tree. XML appears only at conversion boundaries.

The DSL parser lives in `build/wire/parser.rs:209-224` for `Type` with `Id, U32, I32, U64, U64Rev, Str, OptStr, BStr, Fixed, Fd, Bool, Array, Pod`, plus `build/wire/parser.rs:236-246` for `Message` and `build/wire/parser.rs:350-403` for message parsing.

`xml-to-wire/src/main.rs:9-14` plus `xml-to-wire/src/builder.rs:27-42` converts Wayland XML to `wire/*.txt`. Special handling maps `x_hi` plus `x_lo` pairs to `u64` or `u64_rev` (`xml-to-wire/src/builder.rs:83-106`) and maps untyped arrays or `dev_t` blobs to `array` or `pod` (`xml-to-wire/src/builder.rs:132-160`). `wire-to-xml/src/main.rs:41-60` does the reverse for debugging or interop.

The build script (`build/build.rs:53-67`) runs `wire::main` and emits to `OUT_DIR`. `build/wire.rs:497-539` scans `wire/`, parses every file, and writes `wire/mod.rs` plus one generated `wire/<iface>.rs` per interface. It also emits `id!` plus `Interface` constants (`build/wire.rs:455-494`).

A generated request type is a plain struct with `self_id` plus fields (`build/wire.rs:57-76`). Its `RequestParser` impl is emitted in `build/wire.rs:78-202`. Fixed-size messages destructure `*parser.data()` directly (`build/wire.rs:112-170`). Variable-size messages call `parser.uint`, `str`, `bstr`, `fd`, `binary` and then `parser.eof` (`build/wire.rs:171-198`).

A generated event writer implements `EventFormatter` (`build/wire.rs:203-302`). Fixed events use one `fmt.data` word array (`build/wire.rs:214-250`). Variable events use `fmt.header` plus per-field writers (`build/wire.rs:252-291`). Request and event handler traits are emitted together (`build/wire.rs:311-431`), with server traits using `Object` plus `Client` and client-side traits using `UsrObject` plus `UsrCon` (`build/wire.rs:327-348`).

Parsing is largely zero-copy. `MsgParser` borrows the `&[u32]` body plus fd queue (`src/utils/buffd/parser.rs:33-47`). `str`, `bstr`, `array`, `binary_array` return borrowed `&str`, `&BStr`, `&[u8]`, `&[T]` (`src/utils/buffd/parser.rs:96-146`, `src/utils/buffd/parser.rs:159-176`).

File descriptors travel as ancillary data. `WlBufFdIn` collects them with `recvmsg` (`src/utils/buffd/wl_buf_in.rs:110-126`). `MsgParser::fd` pops from that queue (`src/utils/buffd/parser.rs:122-127`). `MsgFormatter::fd` queues them and `write_len` records their message offset (`src/utils/buffd/formatter.rs:93-96`, `src/utils/buffd/formatter.rs:135-149`). Sending splits at fd boundaries (`src/utils/buffd/buf_out.rs:102-120`). This split-queue design is unusual relative to libwayland.

### 3.2 Object model

Each `Client` owns an `Objects` store (`src/client.rs:355`, `src/client/objects.rs:87-135`). There is one generic `registry` map plus many typed `CopyHashMap` maps for surfaces, buffers, seats and others (`src/client/objects.rs:88-134`).

ID allocation splits the space at `MIN_SERVER_ID 0xff000000` (`src/client/objects.rs:137`). Client-created IDs must be nonzero and below that bound (`src/client/objects.rs:266-282`). Server IDs are allocated from a bitset freelist (`src/client/objects.rs:235-250`, `src/client/objects.rs:314-325`).

Dispatch starts in the receive task. It reads `WlMessage obj_id message body fds` (`src/client/tasks.rs:64-72`), looks up the object (`src/client/tasks.rs:73-80`), then calls `handle_request` (`src/client/tasks.rs:81-90`). Every object forwards through `object_base!` to generated `handle_request_impl` (`src/macros.rs:41-66`). The generated dispatcher matches the opcode and emits a `version >= since` guard (`build/wire.rs:387-411`). Unknown opcodes become `InvalidMethod` (`build/wire.rs:413`, `src/client/error.rs:18-19`).

Versioning is also enforced at bind time. `WlRegistry bind` checks interface name and `version <= global.version` (`src/ifs/wl_registry.rs:64-89`). Globals expose fixed versions, for example compositor version 7 (`src/ifs/wl_compositor.rs:82-86`).

Protocol errors use `wl_display/error`.

- Unknown objects trigger `send_invalid_object` plus shutdown (`src/client/tasks.rs:73-78`, `src/ifs/wl_display.rs:79-82`).

- Unknown requests trigger `send_invalid_request` plus shutdown (`src/client.rs:394-416`, `src/ifs/wl_display.rs:68-77`).

- Handler failures trigger `send_implementation_error` plus shutdown (`src/client/tasks.rs:94-108`, `src/ifs/wl_display.rs:84-86`).

- Explicit `protocol_error` does the same (`src/client.rs:489-494`).

- Method wrapping preserves interface, id, method and source error (`src/client/error.rs:35-42`).

Lifetime uses `Rc` with explicit cycle breaking. `Object` has a default empty `break_loops` (`src/object.rs:25-27`). Client teardown calls `Objects::destroy`, which drains the generic registry through `break_loops` and clears typed maps (`src/client/objects.rs:186-233`). `ClientHolder Drop` drives that plus shutdown, activation token and timeline cleanup (`src/client.rs:320-337`). `WlSurface break_loops` drops children, dnd, cursors, transactions, feedback, viewporter and timelines (`src/ifs/wl_surface.rs:2104-2127`). Server ID removal can emit `delete_id` when symmetric deletion is active (`src/client/objects.rs:284-308`). Typed insertion and lookup go through `dedicated_add_obj!` (`src/macros.rs:341-361`), while simple objects and globals use `simple_add_obj!` and `simple_add_global!` (`src/macros.rs:363-373`). Explicit teardown instead of `Weak` everywhere is unusual relative to wayland-rs.

### 3.3 Client I/O

Input uses `WlBufFdIn` with an 8 KiB buffer and 4 KiB max message (`src/utils/buffd/wl_buf_in.rs:15-29`). It validates word alignment and `8 <= len <= 4096` (`src/utils/buffd/wl_buf_in.rs:69-77`), compacts unconsumed bytes (`src/utils/buffd/wl_buf_in.rs:100-108`), and caps queued fds at 32 (`src/utils/buffd/wl_buf_in.rs:122-124`). Error variants cover oversize, undersize, unaligned, missing and excess fds (`src/utils/buffd.rs:24-44`) with limits `BUF_SIZE 4096` and `MAX_IN_FD 32` (`src/utils/buffd.rs:46-47`).

Output uses `OutBufferSwapchain` with current, pending and free buffers (`src/utils/buffd/buf_out.rs:50-69`). Each output buffer is 8 KiB and considered full past 4 KiB (`src/utils/buffd/buf_out.rs:14`, `src/utils/buffd/buf_out.rs:42-46`). `Client::event` formats into the current buffer, commits on full, then signals the sender (`src/client.rs:496-514`). The sender swaps pending buffers and flushes with a 5 second timeout (`src/client/tasks.rs:112-132`). Used buffers are recycled through `free` (`src/client/tasks.rs:128-131`, `src/utils/buffd/buf_out.rs:62-68`).

Backpressure is bounded but not lossy for compliant clients. More than 10 pending buffers counts as over limit (`src/utils/buffd/buf_out.rs:57-60`). Over-limit clients enter the global slow queue once (`src/client.rs:505-511`). A background handler rechecks after a yield and kills still-slow clients (`src/client.rs:520-530`, `src/tasks/slow_clients.rs:9-14`). Event flushing is otherwise triggered, not synchronous after every request, as seen by the commented-out flush (`src/client/tasks.rs:91`) and trigger use (`src/client.rs:513`).

### 3.4 `clientmem.rs`

SHM pools are mapped with `mmap64`, length rounded up to page size, with an empty mapping for zero length (`src/clientmem.rs:104-124`). Read-only pools use `PROT_READ`, writable pools add `PROT_WRITE`, normally `MAP_SHARED` (`src/clientmem.rs:78-123`). Private mappings are a separate constructor (`src/clientmem.rs:68-76`).

Truncated client memory is handled with `SIGBUS`. Startup installs a `SA_SIGINFO` plus `SA_NODEFER` handler (`src/clientmem.rs:273-284`). Safe access pushes a thread-local record, runs the closure, then reports `Sigbus` if marked failed (`src/clientmem.rs:170-189`). The handler checks whether the fault address lies inside a tracked mapping (`src/clientmem.rs:241-254`), replaces that range with anonymous memory via `MAP_FIXED` (`src/clientmem.rs:255-262`), marks failure and returns (`src/clientmem.rs:266-267`), otherwise restores default and raises `SIGBUS` (`src/clientmem.rs:233-239`, `src/clientmem.rs:269`).

Sealed memfds skip the handler path. If `F_SEAL_SHRINK` plus a large enough `st_size` is observed, the mapping is marked `sigbus_impossible` (`src/clientmem.rs:89-96`). It may first extend the file with `ftruncate` (`src/clientmem.rs:105-109`). Direct pointer access is allowed only in that case, otherwise callers get an fd plus offset (`src/clientmem.rs:319-324`). Destruction unmaps inline or offloads close plus unmap to the CPU worker (`src/clientmem.rs:207-222`).

### 3.5 `leaks.rs`

`track!` registers each new `Rc` against its client (`src/leaks.rs:3-7`). Without `rc_tracking` the tracker is a zero-sized phantom (`src/leaks.rs:9-39`). With `rc_tracking` it assigns tracker IDs, installs a tracing global allocator, records allocation backtraces, and on demand groups unreleased objects by client with containing allocation and stack evidence (`src/leaks.rs:59-178`, `src/leaks.rs:193-240`, `src/leaks.rs:268-299`). This is a debug facility, not a production GC.

### 3.6 Acceptors

The primary acceptor creates two Unix stream sockets, insecure `wayland-N` and secure `wayland-N.wry`, plus a lock file, scanning `1..1000` (`src/acceptor.rs:66-132`). It unlinks stale paths, takes a nonblocking `flock`, binds, listens with backlog 4096 and stores the lock fd (`src/acceptor.rs:81-142`). It then spawns separate secure and insecure accept loops (`src/acceptor.rs:144-156`). Each accepted fd becomes a `Client` (`src/acceptor.rs:168-191`).

Tagged acceptors create extra named sockets on demand for a string tag, starting at `wayland-1000` and skipping locked names (`src/tagged_acceptor.rs:63-101`, `src/tagged_acceptor.rs:156-197`). Their metadata carries the tag and non-sandboxed status (`src/tagged_acceptor.rs:72-79`). Their accept loop is otherwise the same (`src/tagged_acceptor.rs:115-135`).

Security context acceptors do not bind. They accept from a client-supplied listen fd and watch a close fd (`src/security_context_acceptor.rs:22-31`, `src/security_context_acceptor.rs:112-137`). New clients are marked sandboxed with caller-supplied sandbox engine, app id, instance id and bounding caps (`src/security_context_acceptor.rs:59-80`, `src/security_context_acceptor.rs:122-129`). Dual secure plus insecure sockets for one compositor is jay/wry specific.

### 3.7 `wl_usr`

`wl_usr` is a Wayland client stack used by the compositor itself. `UsrCon::new` connects over a Unix socket with io_uring (`src/wl_usr.rs:99-129`). `from_socket` reserves IDs 0 and 1, installs `UsrWlDisplay` object 1, and spawns incoming plus outgoing tasks (`src/wl_usr.rs:131-187`). Outgoing requests reuse the same swapchain and formatter design as server-to-client events (`src/wl_usr.rs:260-279`, `src/wl_usr.rs:281-316`). Incoming events dispatch by object id to `handle_event`, ignoring unknown server IDs but erroring on unknown client IDs (`src/wl_usr.rs:339-357`).

Client-side objects live in `src/wl_usr/usr_ifs/`. For example `UsrWlCompositor::create_surface` sends the request and tracks the new object (`src/wl_usr/usr_ifs/usr_wl_compositor.rs:17-30`). The generated client trait uses `UsrObject`, `UsrCon` and `UsrConError` (`build/wire.rs:339-347`). The portal uses this to connect to nested displays named `wayland-*.wry` (`src/portal/ptl_display.rs:298-343`), then binds compositor, fractional scale, viewporter, dmabuf and other globals (`src/portal/ptl_display.rs:346-373`).

### 3.8 Performance notes

- Fixed messages avoid per-field calls and copy words directly. Variable strings, byte strings and arrays borrow from the input buffer.

- Small inline storage appears widely, including `SmallVec` for rects, syncs, copies and seats and `ArrayVec` for descriptor layouts, barriers and singleton broadcasts (`src/rect.rs:33`, `src/video/dmabuf.rs:327`, `src/ifs/wl_surface/commit_timeline.rs:553-561`, `src/globals.rs:410`, `src/utils/buffd/buf_in.rs:73`).

- Object maps use custom `CopyHashMap` over hashbrown with unsafe interior access (`src/utils/copyhashmap.rs:21-80`).

- Output buffers and `Buf` storage are recycled rather than reallocated in the swapchain and sender paths.

- Slow-client detection avoids blocking the compositor on a non-draining peer.

## 4. Vulkan renderer

The reader returned this one as a single dense block with fewer line citations. It is restructured here. Claims marked (verified) were spot-checked by hand. The "bridge" description was corrected, since the code gates it on `for_rendering` (`src/gfx_apis/vulkan/image.rs:535`).

### 4.1 Abstraction

The compositor is renderer-agnostic. `GfxApiOp` (`src/gfx_api.rs:115`) has `FillRect` (`:117`), `CopyTexture` (`:118`), `RoundedFillRect` (`:119`) and `RoundedCopyTexture` (`:120`). The `FillRect` struct (`src/gfx_api.rs:286`) and `CopyTexture` (`src/gfx_api.rs:304`) carry `acquire_sync` (`:309`) plus `release_sync` and `lazy` (`:318`). The rounded variants (`:323`, `:344`) mirror that shape.

- `LazyTexture` (`src/gfx_api.rs:373`) lets a backend defer work, with `perform_lazy_work` feeding a `Vec<FdSync>`.

- `AcquireSync` (`src/gfx_api.rs:426`) has `None`, `Implicit`, `FdSync` and `Unnecessary`, with `from_fd_sync` (`:434`). `ReleaseSync` (`src/gfx_api.rs:452`) is the release side.

- `GfxFramebuffer` (`src/gfx_api.rs:503`) exposes `render_with_region_impl` (`:506`) and wrappers through `:889`.

- `GfxTexture` (`src/gfx_api.rs:931`) and `GfxContext` (`src/gfx_api.rs:1030`) complete the surface, with `supports_color_management` (`:1108`) and `supports_alpha_modes` (`:1112`).

- Direct scanout filtering lives near `src/gfx_api.rs:1529`, rejecting `FillRect` (`:1536`) and `RoundedCopyTexture` (`:1540`).

A second backend exists. `create_gfx_context` (`src/gfx_apis.rs:17`) tries APIs (`:26`) as OpenGL then Vulkan, looping software false then true (`:29`), with dispatch at `:70`. The GL backend (`src/gfx_apis/gl.rs` plus `src/gfx_apis/gl/`, about 3.3k lines) is a full parallel renderer using EGL images, GL textures, and its own `TexCopyType` and `TexSourceType`.

### 4.2 Frame recording

A frame is an op list turned into one Vulkan submit. `RendererBase` in compositor code emits `FillRect` and `CopyTexture` ops, and `VulkanRenderer` executes them. `convert_ops` (`src/gfx_apis/vulkan/renderer.rs:1007`, verified) sorts by color, z order and index (`:1030`), then groups by pipeline key. `TexPipelineKey` (`src/gfx_apis/vulkan/renderer.rs:416`, verified) includes copy type, source type, alpha mode, EOTF pair, color matrix presence, grayscale and rounded. A separate `OutPipelineKey` (`:434`) covers the resolve pass.

Recording centers on `record_draws` (`src/gfx_apis/vulkan/renderer.rs:1729`), `begin_rendering` (`:1620`), `submit` (`:2393`) and `execute` (`:2475`).

- `begin_rendering` uses Vulkan 1.3 dynamic rendering with `cmd_begin_rendering` (`:1685`).

- Full-area clears use load op `CLEAR` (`:1667`), otherwise partial clears go through `cmd_clear_attachments` (`:1694`). The blend buffer pass uses `DONT_CARE` (`:1668`).

- Viewport and scissor cover the full target (`:1702`).

Vertex data uses device-addressable buffers. `tex.common.glsl` (`src/gfx_apis/vulkan/shaders/tex.common.glsl:8`) declares a `buffer_reference` `Vertices` with push-constant `Data` carrying vertices and `mul` (`:12`). This avoids vertex bindings and lets one instanced draw consume many rects from a data buffer.

Specialization uses seven constants in `frag_spec_const.glsl` (`src/gfx_apis/vulkan/shaders/frag_spec_const.glsl:4`): `src_has_alpha`, `has_alpha_multiplier`, `eotf`, `inv_eotf`, `has_matrix`, `alpha_mode` and `grayscale`. Pipeline creation consumes those as specialization constants.

Descriptors have three tiers. Device probing (`src/gfx_apis/vulkan/device.rs:433`) prefers `descriptor_heap` plus `maintenance5`, falls back to `descriptor_buffer` (`:441`), and finally legacy `push_descriptor`. Enablement (`:481`) adds heap and maintenance5 or buffer names. Features (`:490`) enable timeline semaphores, `synchronization2`, `dynamic_rendering` (`:492`), `buffer_device_address` (`:500`), plus heap or buffer features (`:538`). Color bindings are fixed in `tex_set.glsl` (`src/gfx_apis/vulkan/shaders/tex_set.glsl:4`) with `texture2D tex` plus `ColorManagementData` matrix, `EotfArgs` and `InvEotfArgs`.

Wait setup (`src/gfx_apis/vulkan/renderer.rs:2254`) imports dmabuf sync files and explicit `FdSync` into `TOP_OF_PIPE` waits. Submit uses `queue_submit2` (`:2409`) and stores `release_sync` (`:2417`). Pending frames (`:2439`) retain command buffers, images, semaphores and heap entries and spawn `await_release` on the async engine (`:2463`).

### 4.3 Upload and import

- SHM textures are created `OPTIMAL`, `SAMPLED` plus `TRANSFER_DST`, and filled from staging buffers with `BufferImageCopy2` limited to damage. `transfer.rs` computes copies with queue-family ownership barriers and granularity masks and expands for 4-byte alignment.

- The async path uses `CpuWorker` jobs `IoTransferJob` and `CopyTransferJob` (`src/gfx_apis/vulkan/transfer.rs:633`, `:642`, verified) with ring readable waits for gfx queue release. The sync path submits a buffer-image copy on the gfx queue directly.

- Dmabuf import in `image.rs` uses explicit DRM format modifier creation with per-plane fd import and `bind_image_memory2`, and checks disjoint planes and single-file reuse.

- When a dmabuf's modifier is not renderable, rendering goes into an intermediate "bridge" image and is copied out (`src/gfx_apis/vulkan/image.rs:97`, `:113`, `:535`, verified).

- Shm reuse checks dimensions and format before reallocating. Internal framebuffers, read-write images and blend buffers are cached by size.

- The blend buffer is `ABGR16161616F` (`src/gfx_apis/vulkan/format.rs:100`, verified). It holds linear working space, then an out pass resolves to the framebuffer.

- Staging shells and dmabuf host buffers reduce mapping churn.

### 4.4 Synchronization

`FdSync` (`src/gfx_api.rs:1384`) is `SyncFile` or `Syncobj`, with async wait (`:1392`), blocking wait (`:1408`), poll (`:1434`) and external ring integration (`:1474`).

- The acquire path (`src/gfx_apis/vulkan/renderer.rs:2254`) dups explicit sync files (`:2303`) and exports dmabuf sync files with `DMA_BUF_SYNC_READ` for textures (`:2313`) and `DMA_BUF_SYNC_WRITE` for the framebuffer (`:2322`), plus an extra `FdSync` list (`:2329`).

- The release path (`:2343`) attaches the submit fence or timeline point to buffer reservations (`:2357`) or imports into dmabufs (`:2361`), with a fallback warning relying on implicit sync.

- Async SHM tracking sets `last_gfx_use` (`:2381`).

- Device sync creation (`:2401`) returns a fence or timeline semaphore, and submit signals it.

- Timeline opaque fd export is probed (`src/gfx_apis/vulkan/device.rs:472`) and mapped to DRM syncobj points with a two-point validation handshake in `timeline_semaphore.rs`. Binary semaphores import `SYNC_FD` in `semaphore.rs`.

- Pending frame release uses the async engine and io_uring readable waits.

### 4.5 Memory

Memory uses gpu-alloc, not a custom allocator and not VMA. `Cargo.toml:55` pins `ash` as `jay-ash` 0.12.0, `:56` `gpu-alloc` 0.6.0 and `:57` `gpu-alloc-types` 0.3.0 (verified). `allocator.rs` wraps `AshMemoryDevice` in `VulkanAllocator` and `VulkanThreadedAllocator` with CpuWorker async alloc and free, and zeroed pages via `Config::i_am_prototyping`. Separate small caches exist for shader buffers, uniform buffers and descriptor buffers, plus size-keyed blend buffer and image caches.

### 4.6 Color management and HDR

Color work happens in shaders, driven by CPU-side color descriptions.

`tex.frag` steps in order.

1. Sample with `textureLod` (`src/gfx_apis/vulkan/shaders/tex.frag:18`).

2. Unpremultiply electrical-premultiplied inputs (`:21`).

3. Apply EOTF (`:24`) and handle optical unpremultiply.

4. Apply matrix (`:29`).

5. Optional grayscale with Rec 709 luma (`:31`).

6. Inverse EOTF (`:35`).

7. Repremultiply (`:37`).

8. Alpha multiplier (`:41`).

`out.frag` (`src/gfx_apis/vulkan/shaders/out.frag:16`) fetches from the blend buffer and repeats EOTF, matrix and inverse EOTF (`:17`).

`eotfs.glsl` defines `TF_LINEAR` through `TF_COMPOUND_POWER_2_4` (`src/gfx_apis/vulkan/shaders/eotfs.glsl:7`), with PQ (`:38`), BT1886 with four args (`:20`), ST240, log, ST428, pow and compound variants, dispatched by `apply_eotf` (`:121`) and `apply_inv_eotf` (`:139`). Alpha modes (`src/gfx_apis/vulkan/shaders/alpha_modes.glsl:4`) are premultiplied electrical, premultiplied optical and straight.

### 4.7 copy_device.rs

A separate minimal Vulkan copy engine for multi-GPU movement, used by neither screencast nor the main compositor render path. `PhysicalCopyDevice` and `CopyDevice` classify `TransferType` and direction as Blit, Intra, Download or Upload. Entry points are `create_buffer` (`src/copy_device.rs:1037`, `:1342`), `create_fixed_copy` (`:1233`) and `create_copy` (`:1242`). `State` holds `render_ctx_prime_copy_device` (`src/state.rs:277`), assigned from the DRM device (`src/state.rs:2803`). Metal allocator call sites copy render to device BOs (`src/backends/metal/allocator.rs:1149`, `:1212`, `:1235`, `:1395`), including udmabuf staging (`:1507`). Prime modifier feedback reads `render_ctx_prime_modifiers` (`src/dmabuf_feedback.rs:141`).

### 4.8 Decorations

Effects stop at rounded rectangles and borders. The rounding SDF (`src/gfx_apis/vulkan/shaders/rounding.glsl:1`) returns zero outside bounds, selects corner radius and center per quadrant, and smoothsteps distance with half-pixel width (`:24`). Shader families include `fill`, `rounded_fill`, `tex` and `rounded_tex`, plus legacy variants under `src/gfx_apis/vulkan/shaders/legacy`. No blur and no shadow passes exist. `RendererBase` emits tab bars, borders and highlights as `FillRect` and `RoundedFillRect` ops.

### 4.9 Coupling and requirements

Coupling is broad outside the Vulkan directory. `vulkan.rs`, `renderer.rs`, `image.rs`, `device.rs`, `transfer.rs`, `shm_image.rs` and `pipeline.rs` import crate `backend`, `cmm`, `gfx_api`, `theme`, `utils`, `video`, `allocator`, `state`, async engine, ring and CPU worker types. The GL context (`src/gfx_apis/gl.rs:21`) shows the same pattern. A port would carry color management, dmabuf, syncobj, timeline and worker abstractions or stub them.

- Vulkan 1.3. `VULKAN_API_VERSION` (`src/vulkan_core.rs:356`) equals `API_VERSION_1_3` (`:15`). The loader uses `libvulkan.so.1` (`:67`, `:73`).

- Required instance extensions (`src/vulkan_core.rs:268`) are `debug_utils` only.

- Required device extensions (`src/gfx_apis/vulkan/device.rs:728`) include `external_memory_fd`, `external_semaphore_fd`, `external_fence_fd`, `external_memory_dma_buf`, `queue_family_foreign`, `image_drm_format_modifier` and `push_descriptor`. Optional paths add `descriptor_heap` plus `maintenance5`, or `descriptor_buffer`.

- Shaders compile offline. `compile` (`compile-shaders/compile/src/main.rs:18`) maps frag and vert to shaderc kinds (`:33`) and writes SPIR-V (`:44`), with an include callback (`:27`) and hash tracking via `TREES` (`:9`).

### 4.10 Unusual choices

- Linear fp16 blend buffer with a separate resolve pass.

- Device-address vertex buffers fed through push constants.

- Specialization-constant-driven color pipelines.

- Damage-limited staging copies, optionally on the cpu_worker thread.

- Threaded gpu-alloc.

- Vulkan timeline semaphore to DRM syncobj point mapping.

## 5. Tree, transactions, multiphase animations (jay-port branch, NOT the reference, see round2-reports.md section 6)

### 5.1 Commit timeline

Each client owns `CommitTimelines` (`src/client.rs:229`) and each `WlSurface` owns a `CommitTimeline` (`src/ifs/wl_surface.rs:778`). Shared state is in `src/ifs/wl_surface/commit_timeline.rs:62-70`, with per-surface `own_timeline`, `effective_timeline` plus waiters for fifo, commit time, restore, serial and unmap (`src/ifs/wl_surface/commit_timeline.rs:77-87`).

`wl_surface.commit` validates release protocols then hands `PendingState` to the timeline (`src/ifs/wl_surface.rs:1286-1316`). Sync subsurface commits do not reach the timeline. They merge into the parent pending and abort (`src/ifs/wl_surface/wl_subsurface.rs:414-427`). Sync state is `sync_requested or sync_ancestor` (`src/ifs/wl_surface/wl_subsurface.rs:255-256`). Desync flushes cached child state through the timeline (`src/ifs/wl_surface/wl_subsurface.rs:287-293`).

Immediate apply happens only with no dependencies, an empty queue and no fifo barrier (`src/ifs/wl_surface/commit_timeline.rs:275-282`). Otherwise an `EntryKind::Commit` is queued. Client depth is capped at 256 with a `Depth` error (`src/ifs/wl_surface/commit_timeline.rs:58-60`, `src/ifs/wl_surface/commit_timeline.rs:283-285`).

The collector gathers acquire points, shm uploads, dmabuf presence, prime need, acquire files, commit time and restore flags (`src/ifs/wl_surface/commit_timeline.rs:243-263`, `src/ifs/wl_surface/commit_timeline.rs:963-1005`).

- Explicit acquire points come from `set_acquire_point` (`src/ifs/wl_surface/wp_linux_drm_syncobj_surface_v1.rs:59-63`).

- Implicit dmabuf fences are added as plane fds when neither syncobj sync nor sync-file acquire is present (`src/ifs/wl_surface/commit_timeline.rs:977-984`).

- Sync-file acquire is added in `src/ifs/wl_surface/commit_timeline.rs:986-988`.

- Fifo flags come from `set_barrier` and `wait_barrier` (`src/ifs/wl_surface/wp_fifo_v1.rs:43-50`).

- Commit time comes from `set_timestamp` (`src/ifs/wl_surface/wp_commit_timer_v1.rs:45-61`).

Waits are registered without blocking the main thread. Syncobj uses `wfs.wait` (`src/ifs/wl_surface/commit_timeline.rs:321-331`). Implicit fds use `ring.readable_external` (`src/ifs/wl_surface/commit_timeline.rs:340-350`). Shm uploads, prime copies, commit time, restore, serial and unmap mark `needs_flush` (`src/ifs/wl_surface/commit_timeline.rs:333-364`). The queue head is flushed when previously empty (`src/ifs/wl_surface/commit_timeline.rs:366-368`).

Queues are FIFO (`src/ifs/wl_surface/commit_timeline.rs:569-579`). The head applies only when all dependencies clear (`src/ifs/wl_surface/commit_timeline.rs:582-653`). Other clients have separate `Inner` queues, so one blocked surface does not stop another client except through explicit cross-timeline links. Parent and subsurface timelines are unified through `set_effective_timeline` (`src/ifs/wl_surface/commit_timeline.rs:1008-1034`) using `Wait` and `Signal` entries (`src/ifs/wl_surface/commit_timeline.rs:529-534`). Later wakeups go through per-client `process_flush_requests` (`src/ifs/wl_surface/commit_timeline.rs:1041-1053`).

Completion callbacks decrement counters and retry the list. This covers syncobj (`src/ifs/wl_surface/commit_timeline.rs:430-442`), shm upload (`src/ifs/wl_surface/commit_timeline.rs:453-468`), prime copy (`src/ifs/wl_surface/commit_timeline.rs:470-485`), dmabuf poll (`src/ifs/wl_surface/commit_timeline.rs:487-501`) and commit timer timeout (`src/ifs/wl_surface/commit_timeline.rs:504-521`).

Fifo barrier handling parks `Queued` commits as `Registered` and stores `fifo_waiter` (`src/ifs/wl_surface/commit_timeline.rs:600-612`). Barrier release pushes the waiter (`src/ifs/wl_surface/commit_timeline.rs:376-381`). Latch clears it for normal presentation but defers to vblank under tearing (`src/ifs/wl_surface.rs:2561-2584`), with vblank cleanup in `src/ifs/wl_surface.rs:2543-2552`. Applied commits set the barrier (`src/ifs/wl_surface.rs:1664-1688`).

Commit timer registration subtracts render plus flip margins from the requested time (`src/ifs/wl_surface/commit_timeline.rs:702-730`). It uses `ring.timeout_external` and attaches a `before_latch_listener`, then `before_latch` releases the commit when presentation time has passed (`src/ifs/wl_surface/commit_timeline.rs:405-427`, `src/ifs/wl_surface.rs:2555-2559`).

Destroy versus loop breaking is split (`src/ifs/wl_surface/commit_timeline.rs:210-235`), with dependency state discarded in `src/ifs/wl_surface/commit_timeline.rs:197-208` and destroyed timelines drained through a `Gc` entry (`src/ifs/wl_surface/commit_timeline.rs:660-663`).

### 5.2 Layout transactions

Tree mutation uses `Transactionable` and `TransactionData` (`src/transactions.rs:20-38`, `src/transactions.rs:65-71`). Any op schedules the object and triggers serial groups (`src/transactions.rs:195-209`).

`Transactions::commit` snapshots scheduled objects, surfaces and effects, creates or recycles a `Transaction` plus `Blocker`, queues surface blockers and assigns member ops (`src/transactions.rs:216-282`). Surfaces receive `UnblockCommitsUntil` (`src/transactions.rs:230-237`). Apply runs `before_apply`, member ops, `after_apply`, then recycles the transaction (`src/transactions.rs:284-299`).

`Blocker` drop schedules apply exactly once by version (`src/transactions.rs:345-359`). Timeout applies the same version after a 50ms default (`src/transactions.rs:78-80`, `src/transactions.rs:441-467`). The apply loop is separate (`src/transactions.rs:469-475`).

Per-surface blocking is in `src/transactions.rs:116-127`. `unblock_transactions_until` drops blockers at or before the committed serial (`src/transactions.rs:374-400`). `commit_is_blocked` compares `unblocked_commit` against the needed serial (`src/transactions.rs:417-419`). Disabled means tardy or zero enable count (`src/transactions.rs:421-423`). Missing acks mark `tardy`, clear blockers and force the timeout path (`src/transactions.rs:402-415`).

The commit timeline and layout transaction meet in `maybe_apply` (`src/ifs/wl_surface/commit_timeline.rs:632-638`). The surface first records the serial, then parks on `serial_waiter` if still blocked. Publication calls `serial_unblocked` through `WlSurfaceTransactionOp::UnblockCommitsUntil` (`src/ifs/wl_surface.rs:2696-2702`), with waiter release in `src/ifs/wl_surface/commit_timeline.rs:393-397`.

Each serial group tick allocates one `TreeSerial`, commits transactions, then runs configure groups (`src/tree_serial_groups.rs:18-30`). Configures are grouped by serial (`src/configurable.rs:241-280`). `schedule_configure` also adds the surface to transactions (`src/configurable.rs:91-105`). Readiness counting releases whole groups (`src/configurable.rs:170-189`, `src/configurable.rs:336-410`). Flush sends the serial and records `requested_serial` (`src/configurable.rs:218-239`). The client ack must carry at least that serial before `ready` (`src/ifs/wl_surface.rs:1307-1312`, `src/ifs/wl_surface.rs:1370-1374`). The t0061 test asserts `LiveTL` moves first while `RenderTL` stays old until commit (`src/it/tests/t0061_transactional_layout_animation.rs:35-47`).

### 5.3 Tree

Node behavior is `NodeBase` (`src/tree.rs:445-945`) with dyn wrapper `Node` (`src/tree.rs:947-968`). Visitors are in `src/tree/walker.rs:18-86`. Timelines are `LiveTL` and `RenderTL` (`src/tree.rs:976-981`), with `SplitView` maps (`src/tree.rs:984`). Links carry per-timeline validity (`src/tree.rs:985-1008`).

Layers are ordered `Display` through `OverlayStacked` (`src/tree.rs:343-365`), with linked variants in `src/tree.rs:367-385`. Concrete types include `DisplayNode` (`src/tree/display.rs:47`), `OutputNode` (`src/tree/output.rs:131`), `WorkspaceNode` (`src/tree/workspace.rs:76-98`), containers, floats, toplevels and placeholders. Parents implement `ContainingNode` (`src/tree/containing.rs:7-59`). Toplevel behavior splits into `ToplevelNodeBase` (`src/tree/toplevel.rs:366`) and `ToplevelNode` (`src/tree/toplevel.rs:81-101`).

Rendering walks the same hierarchy through `node_render` and `node_visit_children`. Examples are output (`src/tree/output.rs:2477`), container (`src/tree/container.rs:2953`), workspace (`src/tree/workspace.rs:559`), float (`src/tree/float.rs:972`), display (`src/tree/display.rs:285`) and placeholder (`src/tree/placeholder.rs:229`). The renderer starts from outputs and workspaces, then stacked layers and exit frames (`src/renderer.rs:250-303`).

### 5.4 Multiphase animations

A phase is a `MultiphasePhase` with one action plus steps (`src/presentation/multiphase.rs:204-209`). Each step is classified as horizontal or vertical move or scale (`src/presentation/multiphase.rs:1486-1509`). Diagonal or size-plus-position changes cannot be one phase and force multiphase plans.

The planning entry is `plan_no_overlap` (`src/presentation/multiphase.rs:354-356`), with forward then reversed attempts (`src/presentation/multiphase.rs:364-412`). Strategies include `SingleAction`, `SpaceThenOrthogonalGrowth`, `HierarchyOrderedScales`, `OrientationChange`, `SwapLanes` and reversed plans (`src/presentation/multiphase.rs:159-168`), tried in that order (`src/presentation/multiphase.rs:535-616`). Independent motion groups split first (`src/presentation/multiphase.rs:460-488`).

Validation checks chaining, duplicates, action counts, unknown nodes, stale starts, intra-phase overlap and final rects (`src/presentation/multiphase.rs:1280-1368`). Overlap uses linear edge deltas with rational time intervals (`src/presentation/multiphase.rs:1370-1484`).

Runtime animations store multiple `from to` segments (`src/presentation/layout_animation.rs:160-168`). Total time is duration times phase count (`src/presentation/layout_animation.rs:1292-1296`). Position interpolates within the current phase with the configured curve (`src/presentation/layout_animation.rs:1309-1319`). Interrupts retarget from the current `rect_at` (`src/presentation/layout_animation.rs:846-892`, `src/presentation/layout_animation.rs:894-952`, `src/presentation/layout_animation.rs:1112-1129`). Path validation for reversed interrupts is in `src/presentation/multiphase.rs:414-458`. Appearing windows can wait behind existing phases (`src/presentation/layout_animation.rs:976-1018`).

Ticks are per-output `LatchListener`s (`src/presentation/layout_animation.rs:257-260`, `src/presentation/layout_animation.rs:1945-1960`). Each latch damages active rects and stops when idle (`src/presentation/layout_animation.rs:1218-1248`). Ticks attach to `output.latch_event` (`src/presentation/layout_animation.rs:1250-1269`) and detach in `src/presentation/layout_animation.rs:1271-1289`. The test asserts latch drives damage and that output disconnect or reconnect changes tick count (`src/it/tests/t0061_transactional_layout_animation.rs:69-90`).

Animations are transaction effects. The trait observes pre and post trees without mutating live state (`src/transactions.rs:45-58`). Scheduling adds effects (`src/presentation/layout_animation.rs:561-738`). Single moves capture the before rect plus current visual (`src/presentation/layout_animation.rs:1472-1514`). Batches capture whole container snapshots before and after (`src/presentation/layout_animation.rs:1596-1664`), with coalescing per container (`src/presentation/layout_animation.rs:1666-1671`). Direct manipulation first cancels animations then suppresses new ones for that transaction (`src/presentation/layout_animation.rs:527-559`, `src/presentation/layout_animation.rs:1516-1522`). The test asserts no animation before publication and a multiphase spawn after (`src/it/tests/t0061_transactional_layout_animation.rs:92-127`), plus no animation for direct manipulation (`src/it/tests/t0061_transactional_layout_animation.rs:129-146`).

Old pixels use retained captures. `RetainedToplevel`, `RetainedSurface` and `RetainedContent` hold textures or colors plus subsurface offsets (`src/presentation/layout_animation.rs:107-153`). Capture clones live buffers and subsurface structure (`src/presentation/layout_animation.rs:1355-1469`). Exits expose timed frames (`src/presentation/layout_animation.rs:766-778`). Spawns expose retained frames while resizing (`src/presentation/layout_animation.rs:780-794`). Close while blocked produces no exit until timeout publication (`src/it/tests/t0061_transactional_layout_animation.rs:151-174`). Closing mid-animation hands the presented rect to the exit (`src/it/tests/t0061_transactional_layout_animation.rs:176-201`).

### 5.5 layout_animation computation and render plug-in

It computes curve samples, spawn endpoints, roll edges, batch plans, per-node visual rects, damage and retained frames. Curves include linear and flattened cubic bezier (`src/presentation/layout_animation.rs:281-323`, `src/presentation/layout_animation.rs:326-411`). Spawn endpoints cover grow, fly and roll (`src/presentation/layout_animation.rs:413-450`), with edge helpers in `src/presentation/layout_animation.rs:452-519`. Batch planning filters to moving windows, partitions groups, then plans or falls back to direct interpolation (`src/presentation/layout_animation.rs:954-1110`).

Render integration reads `visual_rect` for fullscreen, container children and mono bodies (`src/renderer.rs:311-330`, `src/renderer.rs:470-505`, `src/renderer.rs:571-589`). Exit frames render above tiled or floating stacks (`src/renderer.rs:256-274`, `src/renderer.rs:737-765`). Spawns render retained content scaled from source to target size (`src/renderer.rs:767-820`, `src/renderer.rs:822-860`). Client damage follows the presented window through `visual_damage` (`src/ifs/wl_surface.rs:1735-1752`, `src/presentation/layout_animation.rs:747-764`).

### 5.6 Tree verify

`verify_tree_invariants` checks both timelines (`src/tree/verify.rs:14-22`) and runs after idle in integration tests (`src/it/testrun.rs:198-201`). It checks output identity and dummy status, active workspace membership, workspace-to-output links, toplevel parent and workspace pointers, float workspace and display stack membership, fullscreen uniqueness and placeholder linkage, scratchpad mapping and container snapshots (`src/tree/verify.rs:72-108` and following).

Container checks include nonempty children, cached counts, child map identity, finite nonnegative factors, factor sum tolerance, focus history and backlinks, mono child placement, no pending layout and non-mono overlap (`src/tree/verify.rs:671-853`).

### 5.7 Unusual choices

- Per-client commit queues plus per-surface timelines with explicit cross-timeline signals.

- Shm upload, prime copy, dmabuf poll, fifo, commit time, restore, serial and unmap are treated uniformly as queue blockers.

- The tardy path that discards blockers and relies on timeout is pragmatic.

- A collision-free geometric planner with exact rational overlap checks drives window animation.

- Retained textures render scaled from old source size to animated target size while clients resize.

## 6. Process model, config, tests, utilities

### 6.1 Startup

- `main()` only calls `cli::main()` (`src/main.rs:138-140`). CLI parsing decides run vs control commands (`src/cli.rs:312-356`).

- Non-`run` commands drop all process capabilities immediately (`src/cli.rs:320-322`).

- `Cmd::Run` calls `start_compositor` (`src/cli.rs:327`). It resets signal handlers (`src/compositor.rs:162-164`), makes the process a child subreaper or re-execs under one (`src/compositor.rs:164`, `src/utils/clone3.rs:87-115`), snapshots capabilities (`src/compositor.rs:165`), and keeps only `CAP_SYS_NICE` for the compositor (`src/pr_caps.rs:83-115`).

- If `CAP_SYS_NICE` survived, it elevates the scheduler and moves the privileged capability onto a dedicated helper thread (`src/compositor.rs:166-172`, `src/pr_caps.rs:122-147`). The reaper child also drops caps (`src/utils/clone3.rs:116`).

- The forker is created next (`src/compositor.rs:173-174`), before logging, io_uring, threads, portal, or graphics. Later startup creates threads and io_uring state that must not be forked.

- Startup then spawns the portal helper, sleeper, profiler, and logger (`src/compositor.rs:174-184`), then builds the full `State` in `start_compositor2` (`src/compositor.rs:253-536`).

- `start_compositor2` installs the Wayland acceptor, IPC acceptor, forker environment, portal task, and compositor task, then runs io_uring (`src/compositor.rs:495-535`).

- The forker child sanitizes its environment by forcing `XDG_SESSION_TYPE=wayland` and removing `DISPLAY`/`WAYLAND_DISPLAY` (`src/forker.rs:343-348`), renames itself (`src/forker.rs:349`), takes `SIGKILL` on parent death (`src/forker.rs:350`, `src/forker.rs:584-592`), ignores `SIGCHLD` (`src/forker.rs:351-353`), and collapses its fds so only the control socket survives (`src/forker.rs:569-582`).

- `start_compositor3` selects a backend, publishes sockets, loads config, creates the default seat, starts global handlers and Xwayland, then runs the backend (`src/compositor.rs:538-588`).

- Backend order defaults to X11 then Metal (`src/compositor.rs:755-758`). Config is loaded after graphics/backend selection but before seats and Xwayland (`src/compositor.rs:565-581`).

- `RLIMIT_NOFILE` is raised to the hard limit by default (`src/compositor.rs:797-814`).

### 6.2 Forker

- `ForkerProxy::create` makes a control socketpair and calls `double_fork` (`src/forker.rs:99-119`). The parent gets a pidfd and the child enters `Forker::handle` (`src/forker.rs:114-118`).

- `double_fork` uses pidfd-carrying socketpairs so both stages reliably learn child pidfds (`src/utils/clone3.rs:24-48`, `src/utils/clone3.rs:50-85`).

- The compositor never calls `fork`/`exec` directly for clients. It queues `ServerMessage::Spawn` plus separately passed fds (`src/forker.rs:206-225`, `src/forker.rs:276-290`). The forker re-forks, remaps fds with collision handling, applies env deltas, and execs (`src/forker.rs:449-546`, `src/forker.rs:594-616`).

- It is forked early because only an early, single-threaded, pre-graphics process can safely `fork` again later. It also owns the child environment via `SetEnv` (`src/forker.rs:139-151`, `src/forker.rs:423-431`) and reports exec failures and pidfds back (`src/forker.rs:473-503`, `src/forker.rs:548-556`).

- Xwayland is one special spawn with fixed fds stderr=2, displayfd=3, listenfd=4, wm=5, wayland=6 (`src/forker.rs:170-194`).

### 6.3 Config

- Current config is in-process and typed. `ConfigProxy::default` wires the compositor handler directly to `wry_toml_config::configure` through `wry_config::_private::client::init` (`src/config.rs:255-259`).

- `init` takes a `Weak<dyn ConfigServerEndpoint>`, an `InitMessage`, and a configure function pointer (`wry-config/src/_private/client.rs:242-246`).

- Traffic consists of cloned Rust enums such as `ServerMessage`, `ClientMessage`, and `Response` (`wry-config/src/_private/ipc.rs:84-150`, `src/config/handler.rs:101-117`). `ConfigProxyHandler::send` calls `client.handle(msg.clone())` with no serialization (`src/config/handler.rs:324-328`).

- No `dlopen`/`libloading`/`config.so` loading remains in `src/config/handler.rs`. The public docs still describe a `cdylib` plus `config!` workflow (`wry-config/src/lib.rs:19-33`), but `wry-config/src/macros.rs:1-28` now only defines `try_get!`/`get!`, so that documentation looks stale.

- The high-level `wry-config` API exposes seats, windows, workspaces, video/connectors, input, keyboard, theme, timers, tasks, exec, logging, and lifecycle calls (`wry-config/src/lib.rs:61-79`, `wry-config/src/lib.rs:107-122`).

- `reload()` calls into the ambient config client (`wry-config/src/lib.rs:117-122`), becomes `ClientMessage::Reload` (`src/config/handler.rs:3714`), invokes `state.reload_config()` (`src/config/handler.rs:523-525`), and reissues `configure(true)` (`src/state.rs:2497-2502`).

- Every configure sends feature negotiation then `Configure { reload }` (`src/config.rs:240-253`).

- The TOML implementation preserves a `PersistentState` across reloads and clears ephemeral actions/rules/triggers/counters on unload (`toml-config/src/lib.rs:2118-2145`).

- Unload clears timers, pollables, and client/window matchers (`src/config/handler.rs:307-322`), while `ConfigProxy::destroy` drops the client endpoint (`src/config.rs:48-52`) and `Clear` is available as an explicit message (`src/config.rs:128-130`).

- There is a versioned `VERSION = 1` and feature list (`wry-config/src/_private.rs:21-29`, `wry-config/src/_private/ipc.rs:69-82`).

### 6.4 Xwayland

- Xwayland is started lazily. The manager allocates and listens on an X socket, exports `DISPLAY`, then waits for a readable connection attempt before launching Xwayland (`src/xwayland.rs:106-133`).

- Launch uses fixed args including `-terminate`, `-rootless`, `-displayfd 3`, `-listenfd 4`, `-wm 5`, plus optional `-enable-ei-portal` after probing `Xwayland -help` (`src/xwayland.rs:231-282`).

- The compositor creates a privileged Wayland client for the Xwayland process itself (`src/xwayland.rs:188-203`), waits for the displayfd signal (`src/xwayland.rs:205`), constructs the WM asynchronously (`src/xwayland.rs:214-219`), and supervises its pidfd (`src/xwayland.rs:220-225`).

- Window management lives in `src/xwayland/xwm.rs:1-60` and speaks X11 through the local `xcon` parser/formatter and generated `wire_xcon` bindings (`src/xcon/parser.rs`, `src/xcon/formatter.rs`, `src/xcon/consts.rs`, `src/xwayland/xwm.rs:54-60`).

- Compositor-level Xwayland supervision is one async task installed once (`src/state.rs:1630-1638`), and stopping only clears the task when the server is not running (`src/state.rs:1640-1645`).

### 6.5 Integration tests

- Tests are in-process and feature-gated (`src/compositor.rs:205-218`, `src/cli.rs:145-151`, `src/cli.rs:350-351`).

- Each test boots a fresh compositor with `TestBackend` via `start_compositor_for_test` (`src/it.rs:124-186`, `src/compositor.rs:747-754`).

- `TestBackend` provides an 800x600 virtual connector, keyboard, mouse, and test graphics context (`src/it/test_backend.rs:97-120`).

- Virtual clients connect over a real Unix socket to the test acceptor and speak Wayland through `TestTransport` (`src/it/testrun.rs:53-107`, `src/it/test_transport.rs:35-80`).

- Config is replaced by a thread-local `TestConfig` implementing the same typed config endpoint (`src/it/test_config.rs:34-113`, `src/config.rs:261-264`).

- Test mode zeroes configure/transaction timeouts (`src/compositor.rs:575-578`). Each test runs as a `Phase::Present` future with a watchdog timeout (`src/it.rs:156-172`).

- Tests run in parallel across worker threads, one isolated runtime dir per process (`src/it.rs:46-52`, `src/it.rs:77-103`).

- There are about 73 `src/it/tests/t*.rs` cases, plus protocol-object helpers under `src/it/test_ifs/` and utilities under `src/it/test_utils/`.

- Assertions cover tree geometry and focus (`src/it/tests/t0002_window.rs:9-28`), protocol behavior, session-manager state, and golden pixels. The scaled-render test renders through the real screenshot path and byte-compares QOI output (`src/it/tests/t0071_scaled_render.rs:22-60`).

### 6.6 `sm`

- `sm` is a SQLite-backed Wayland session manager (`src/sm.rs:1-56`, `src/compositor.rs:287-292`).

- It models sessions, named toplevel sessions, owners, and asynchronous acquire/rename/update/disown jobs (`src/sm.rs:66-144`, `src/sm.rs:209-228`, `src/sm.rs:359-384`).

- Toplevel state tracks output, workspace, floating rectangle, and fullscreen (`src/sm.rs:178-186`, `src/sm.rs:484-539`).

- Persistence work is scheduled as SQLite jobs and flushed by a background task (`src/sm.rs:464-475`, `src/sm.rs:681-705`).

### 6.7 Keyboard and input

- `kbvm` is an external crates.io dependency, version 0.1.7 with `compose` (`Cargo.toml:64`).

- It supplies the XKB context, RMLVO/keymap compilation, state machine, and lookup tables (`src/kbvm.rs:42-72`, `src/kbvm.rs:105-164`, `src/kbvm.rs:289-323`).

- Keymaps are sealed memfds, with a separate Xwayland-compatible rendering (`src/kbvm.rs:210-231`).

- `libinput` is used through unsafe FFI, with no evdev reimplementation. The code binds `libinput_path_create_context`, dispatch, event, fd, logging, and ref functions (`src/libinput.rs:15-26`), supplies restricted open/close callbacks (`src/libinput.rs:39-63`), forwards libinput logs (`src/libinput.rs:176-195`), and unrefs on drop (`src/libinput.rs:168-174`).

- Local `evdev` code is only a small `EVIOCGBIT` key-capability helper (`src/evdev.rs:1-34`).

### 6.8 Homegrown utilities

- `CloneCell` (`src/utils/clonecell.rs:9-55`). `UnsafeCell` cell for cheaply cloneable `Rc`/handle types in single-threaded code.

- `CopyHashMap` (`src/utils/copyhashmap.rs:21-56`). Interior-mutable hashbrown map with access counting and lockable hasher behavior.

- `NumCell` (`src/utils/numcell.rs:9-30`). `Cell` numeric wrapper with fetch-add/sub and bit operations.

- `AsyncQueue` (`src/utils/queue.rs:16-54`). Single-consumer async FIFO with waker support.

- `SyncQueue` (`src/utils/syncqueue.rs:10-37`). Non-async interior-mutable deque.

- `Stack`/`AsyncStack` (`src/utils/stack.rs:15-48`, `src/utils/stack.rs:72-99`). Interior-mutable `Vec` stacks, optionally awaitable for nonemptiness.

- `SmallMap` (`src/utils/smallmap.rs:11-58`). Small inline map with interior mutability.

- `LinkedList` (`src/utils/linkedlist.rs:13-60`). Intrusive-style doubly linked list with manual refcounts.

- `VecSet` (`src/utils/vecset.rs:4-41`). Small vector-backed set used for pressed keys and similar sets.

- `RefCounted` (`src/utils/refcounted.rs:8-40`). Manual refcount table with version bumping.

- `AsyncEvent` (`src/utils/asyncevent.rs:11-42`). Counting one-shot async trigger.

- `rc_eq`/`RcEq` (`src/utils/rc_eq.rs:5-45`). Pointer-identity equality for `Rc`.

- `ErrorFmt` (`src/utils/errorfmt.rs:5-22`). Formats chained `Error::source` output.

- `oserror` (`src/utils/oserror.rs:9-60`). Raw errno wrapper plus generated constructors/messages.

- `clone3` helpers (`src/utils/clone3.rs:24-85`). pidfd-aware fork/double-fork, reaper setup, and child supervision.

- The workspace also contains its own TOML parser, PHF maps, and wire-format codegen crates (`Cargo.toml:16`, `toml-config/src/toml/`, `toml-config/src/phf.rs`).

### 6.9 Tracy

- Profiling is behind the `tracy` Cargo feature (`Cargo.toml:105`).

- Without it, zone/frame macros compile to no-ops (`src/tracy.rs:1-16`, `src/tracy/tracy_noop.rs:21-51`).

- With it, zone names are cached in a global map and emitted through `tracy-client-sys` begin/end calls (`src/tracy/tracy_impl.rs:30-80`).

- The profiler is enabled during normal startup (`src/compositor.rs:176`).

### 6.10 Unusual choices

- Nearly everything is single-threaded `Rc` plus `UnsafeCell` interior mutability, with threads isolated to CPU work, SQLite, `CAP_SYS_NICE`, and test runners.

- Spawning is centralized in a pre-thread double-forked helper that passes fds over a socket and remaps colliding targets.

- Config, tests, and production share the same typed config traits rather than separate serialization boundaries.

- The repo vendors protocol-adjacent machinery including X11 wire parsing, Wayland buffer handling, TOML parsing, PHF maps, and XML/wire codegen.

- SQLite is a core runtime dependency for session state, not merely diagnostics.

## 7. Smithay extension points

Paths in this section are relative to shallow clones of smithay (`023b78b`, 2026-10-15) and calloop (0.14.5), prefixed `smithay/` and `calloop/`.

### 7.1 Event loop

calloop 0.14.5 uses the `polling` 3.0.0 crate rather than direct epoll calls (`calloop/Cargo.toml:26`). `Poll` holds an `Arc<Poller>` (`calloop/src/sys.rs:174`) built with `Poller::new()` (`calloop/src/sys.rs:207`). Docs describe it as OS-provided polling with epoll on Linux (`calloop/src/lib.rs:99`). No `io_uring` string appears in calloop or smithay.

The futures executor is optional behind the `executor` feature (`calloop/Cargo.toml:41`). It is implemented as `Executor<T>` plus `Scheduler<T>` (`calloop/src/sources/futures.rs:45`), built on `async-task` runnables woken through a `PingSource`. The module docs state futures need their own wakeup means and point at `LoopHandle::adapt_io` (`calloop/src/sources/futures.rs:17`).

smithay does not hard-require calloop for `wayland-server::Display`. Anvil drives clients by wrapping the display in a generic fd source with `Generic::new(display, Interest::READ, Mode::Level)` then calling `dispatch_clients` and `flush_clients` (`smithay/anvil/src/state.rs:682`, `smithay/anvil/src/udev.rs:544`). The listening socket helper is itself an `EventSource` (`smithay/src/wayland/socket.rs:95`), and other helpers merely provide `EventSource` impls.

- `DmabufSource` (`smithay/src/backend/allocator/dmabuf.rs:631`)

- `DrmDeviceNotifier` (`smithay/src/backend/drm/device/mod.rs:525`)

- `UdevBackend` (`smithay/src/backend/udev.rs:130`)

- `LibinputInputBackend` (`smithay/src/backend/libinput/mod.rs:707`)

- `X11Backend` (`smithay/src/backend/x11/mod.rs:561`)

- `WinitEventLoop` (`smithay/src/backend/winit/mod.rs:789`)

- `DrmSyncPointSource` (`smithay/src/wayland/drm_syncobj/sync_point.rs:286`)

- `SecurityContextListenerSource` (`smithay/src/wayland/security_context/listener_source.rs:36`)

- `XWayland` (`smithay/src/xwayland/xserver.rs:279`)

- `EiInput` (`smithay/src/backend/libei/mod.rs:163`)

A compositor could poll the display fd from another loop and call `dispatch_clients` plus `flush_clients` itself, at the cost of those ready-made sources and the `LoopHandle` insertion helpers used across backends and xwayland.

### 7.2 Wayland server

smithay uses `wayland-server` 0.31.13 and `wayland-backend` 0.3.15 as optional deps enabled by `wayland_frontend` (`smithay/Cargo.toml:64`, `smithay/Cargo.toml:66`, `smithay/Cargo.toml:115`). The default is the pure Rust backend. The libwayland system backend is only selected by `use_system_lib` through `wayland-backend/server_system` plus `wayland-sys` (`smithay/Cargo.toml:113`). That feature also gates `gbm?/import-wayland` and the `ImportEgl` path.

Dispatch uses `wayland-server` `Dispatch` and `GlobalDispatch`, but smithay modules expose the simpler `Dispatch2` and `GlobalDispatch2` (`smithay/src/wayland/dispatch2.rs:6`, `smithay/src/wayland/dispatch2.rs:25`), with a `delegate_dispatch2` macro (`smithay/src/wayland/dispatch2.rs:45`) that blanket-implements the upstream traits. Each protocol module documents `*State` plus `*Handler` plus `delegate_dispatch2`, for example compositor (`smithay/src/wayland/compositor/mod.rs:63`).

### 7.3 Renderer abstraction

Core traits live in `smithay/src/backend/renderer/mod.rs`.

- `Bind` (`:216`) has `bind` and `supported_formats`.

- `Texture` (`:233`) has `size`, `width`, `height` and `format`.

- `Frame` (`:270`) has `context_id`, `clear`, `draw_solid`, `render_texture_at`, `render_texture_from_to`, `transformation`, `output_size`, `wait` and `finish`.

- `Renderer` plus `RendererSuper` (`:385`, `:402`) have `context_id`, `downscale_filter`, `upscale_filter`, `set_debug_flags`, `debug_flags`, `render`, `wait`, `cleanup_texture_cache` and `invalidate_caches`.

- `Offscreen::create_buffer` (`:467`).

- `ImportMem` (`:511`) with `import_memory`, `update_memory` and `mem_formats`. `ImportMemWl` (`:479`) with `import_shm_buffer` and `shm_formats`.

- `ImportDma` (`:643`) with `dmabuf_formats`, `has_dmabuf_format` and `import_dmabuf`. `ImportDmaWl::import_dma_buffer` (`:618`). `ImportAll::import_buffer` (`:677`).

- `ExportMem` (`:747`) with `copy_framebuffer`, `copy_texture`, `can_read_texture` and `map_texture`.

- `Blit::blit` (`:808`) and `BlitFrame` (`:836`) with `blit_to` and `blit_from`.

There is no Vulkan renderer in tree. `src/backend/vulkan` only has instance and physical device helpers. Its module docs state it does not provide logical devices, rendering or memory allocation (`smithay/src/backend/vulkan/mod.rs:1`). Vulkan allocation is separate in `src/backend/allocator/vulkan`.

Multigpu is generic over `GraphicsApi` and `ApiDevice` (`smithay/src/backend/renderer/multigpu/mod.rs:728`, `:749`). A device exposes `renderer`, `renderer_mut`, `allocator` returning a `Dmabuf` allocator, `node`, plus cross-device import hints. Target selection needs `Bind<Dmabuf>` (`:328`), cross rendering needs target-side `ImportDma` (`:394`), and `early_import` needs `ImportMemWl` plus `ImportDmaWl` plus `ExportMem` (`:493`).

`OutputDamageTracker` (`smithay/src/backend/renderer/damage/mod.rs:193`) exposes `new`, `from_output`, `from_mode_source`, `mode`, `render_output`, `render_output_with_states` and `damage_output` (`:250`, `:279`, `:300`, `:317`, `:326`, `:382`, `:435`). Rendering requires `E: RenderElement<R>` and `R: Renderer`.

`Element` (`smithay/src/backend/renderer/element/mod.rs:518`) requires `id`, `current_commit`, `src`, `geometry` plus defaulted `location`, `transform`, `damage_since`, `opaque_regions`, `alpha`, `kind` and `is_framebuffer_effect`. `RenderElement` (`:572`) requires `draw` and optionally `underlying_storage` plus `capture_framebuffer`.

### 7.4 DRM

`DrmCompositor` docs (`smithay/src/backend/drm/compositor/mod.rs:1`) describe walking elements front to back, assigning overlays, then trying the top fitting element for cursor, and compositing the rest on primary with the supplied renderer. Overlays are atomic-only, with legacy limited to primary, plus `UnderlyingStorage` export and atomic test commits. Scanout permission is controlled by `FrameFlags` (`:1021`) with `ALLOW_PRIMARY_PLANE_SCANOUT`, `ALLOW_PRIMARY_PLANE_SCANOUT_ANY`, `ALLOW_OVERLAY_PLANE_SCANOUT`, `ALLOW_CURSOR_PLANE_SCANOUT`, `SKIP_CURSOR_ONLY_UPDATES`, `ALLOW_SCANOUT` and `DEFAULT`.

Frame scheduling is caller-driven. `render_frame` (`:1686`) needs `R: Renderer + Bind<Dmabuf>` and prepares planes and damage. `queue_frame` (`:2441`) queues and submits when idle. `commit_frame` (`:2487`) commits without vblank generation. `frame_submitted` (`:2618`) retires the pending frame and submits a queued one. Empty frames must be rescheduled by the caller, typically with a retrace timer.

VRR exists on surfaces as `vrr_supported`, `vrr_enabled` and `use_vrr` backed by `VRR_ENABLED` (`smithay/src/backend/drm/surface/atomic.rs:558`, `smithay/src/backend/drm/surface/gbm.rs:502`), with `VrrSupport` values including `RequiresModeset`. No tearing or async flip control, no gamma or CTM or color pipeline properties, and no render-as-late-as-possible deadline API were found in `src/backend/drm/compositor`.