monolith

# monolith design decisions

Running log of settled decisions and open questions. Research backing lives in `research/`.

## Settled

### Project

- smithay based, Vulkan renderer, EUPL. jay/wry are reference only, nothing is copied.

- calloop event loop. jay's async runtime is not ported. Its phase ordering (event handling, layout, post-layout, present) is reproduced as fixed stages in the post-dispatch pipeline.

- No programmable layouts. TOML config, no scripting.

- Tree nodes and windows live in generational slotmaps referenced by typed keys, not `Rc` graphs.

### Tags

- Each window carries exactly one tag. Several tags can be viewed at once.

- Tag names are global, view state is per output (model B). "View on all outputs" is a command built on top.

- A "homeless" tag is immutable and always viewed. New windows land there unless a rule or launch context says otherwise. Hiding a window means moving it to an unviewed tag.

- Windows are bound to an output. New homeless windows go to the output that was active when the spawn was requested.

- Launch context. Windows are placed on the tag and output that were active when they were launched, not where focus is when they map. Child windows and windows of child processes inherit the parent's tag and output. A compositor `spawn` command is acceptable as the launch path.

- Layout state is per tag-on-output.

- Unplug moves windows to an output viewing their tag, otherwise the tag is disabled there. Replug restores windows that left because of the unplug.

- Tag order is invocation order, remembered, with a reordering command.

- Sticky flag exists. Scratchpads are floating sticky sets of windows. Addressing a scratchpad cycles on, next window, ..., off, with dimensions kept. A sticky scratchpad stays on the output it was last summoned to. A dismiss-scratchpad command takes an optional target, defaulting to the last active.

- Tags are exposed through ext-workspace-v1, one group per output, one workspace per tag per output.

### Layout

- Tree per tag-on-output, edited by the user, not derived from window count.

- Child splits run on the axis opposite their parent. Flipping orientation transposes the whole tree. Orientation is presentation only.

- Viewing several tags stacks each tag's tree as a row (or column when flipped), in invocation order. Each tag keeps its own split ratios. No positional L/C/R merging.

- An "expand" command at any tree level lets one window or subtree fill its slot. Autotiling on merge is a possible experiment.

- Floating windows allowed. No pure floating mode.

- A "deck" monocle (stacked windows with visible edges, selected window popped out) is a later container mode.

### Animation

- Animate by default. No animation under tearing or for fullscreen scanout, or the texture freezes until done.

- Bezier curves with velocity-matched retargeting on interrupt. Springs may be supported too.

- Every animation, and every phase of a multiphase plan, takes exactly its configured `t`. Plan length is `phases * t`.

- Interruption restarts from the current visual position and must stay continuous under repeated interruption.

- wry `master` (8b7ad7e6) is a worked example of multiphase rules, not law. monolith needs a new planner that handles diagonal moves, cross-output moves and large tag-merge motion groups.

- Old textures are held during resize, oversize areas fill clamp-to-edge. Alpha blending and transition shaders (wipe, crossfade) are allowed for content swaps.

- Animation starts without waiting for clients. A short timeout is acceptable.

- Sample animations at predicted presentation time.

- Geometry is subpixel (floats), rounded to physical pixels only at render.

### Rendering

- Individually rounded corners, borders, custom transition shaders (niri style). No user-facing transparency, blur or shadows. Normal alpha blending of client content is supported.

- Fullscreen drops rounding.

### Decorations

- Server-side only, no titlebars in v1. Minimal i3-style titles possibly later.

- Advertise xdg-decoration and org_kde_kwin_server_decoration_manager defaulting to SERVER. Claim server-side and draw only borders.

- Send all four tiled states plus xdg-shell v7 constrained states (niri's "no CSD" signal).

### IPC

- Wayland protocols for things bars consume (ext-workspace, foreign-toplevel).

- Control and scripting over a unix socket speaking versioned JSONL.

### Hardware and performance

- NVIDIA first, must also work on Intel and AMD. An old Intel laptop is available for testing.

- Hybrid laptops out of v1, but per-output render GPU stays in the data model.

- VRR soon. HDR later, with room left in the color path.

- Targets. Compositor CPU per frame p99 under 0.5 ms. Render to scanout at most 1 vblank with deadline scheduling. Fullscreen direct scanout plus tearing adds zero compositor frames. No dropped animation frames at 360 Hz.

- lavapipe golden tests render to plain Vulkan images, not dmabuf.

### Taken from jay/wry (as designs)

1. Deadline frame scheduler, running from flip timestamps on NVIDIA.

2. Off-thread shm upload with commit blocked until done.

3. Vulkan renderer internals, with syncobj handled via DRM ioctls plus binary sync_file semaphores.

4. Commit blocker taxonomy.

5. Two-timeline tree, transactions.

6. In-process integration test harness.

7. Small items (SCHED_RR with reset-on-fork, Tracy, KMS hygiene, VRR cursor throttling, lazy Xwayland).

## Open

- None. Crates and milestones are in `plan.md`.

## Settled late

- Interrupts replan, they never stack. No plan-length cap.

- Velocity matching is best-effort, applied only where the replan continues the current axis.

- Launch context resolves through a graceful ranking. Window rule, xdg-activation token, parent toplevel, tracked systemd scope or cgroup, PID ancestry, focus at map time. The target is where the user was when the launch command began. Windows placed on an unviewed tag mark it urgent.

- Nested sessions are a first-class, permanently supported backend.

- Input hit-tests against final layout geometry, never animated geometry.

- smithay is pinned by git rev. The repo uses jj.

## Deferred

- Tearing. At the scanout milestone, carry rebased smithay #1948, #1949 and #1325 as patches and push them upstream.