RFC-0002 — Core runtime
Status: accepted · proposed 2026-10-07, accepted 2026-10-09. Implemented in core through IPC 0.19, including the presentation-driven tick amendment; the optional world renderer (RFC-0009) is implemented through phase 1, default off.
Decision: a small plugin and a helper
Section titled “Decision: a small plugin and a helper”Core ships a Hyprland plugin and hypruned, a per-session user daemon. The plugin owns only work that requires compositor authority or the live graphics context: capture, input dispatch, GPU resources, scene rendering and final state commits. The daemon owns public IPC, grants, package discovery/validation, supervision, filesystem work and persistence. Both belong in core so their private bridge can evolve together without becoming a public SDK ABI.
The daemon starts the reference shell or an explicitly configured alternative with scoped launch credentials. It never loads third-party code into Hyprland. M0 may keep trusted camera simulation in the plugin; loading, parsing and expensive geometry processing must leave its render callbacks. Do not put all rendering into a second compositor: that sacrifices direct window integration and creates a second input authority. Do not put package managers or sockets with blocking I/O inside the plugin.
Authority and the private bridge
Section titled “Authority and the private bridge”The plugin is authoritative for runtime, output IDs, focus, surfaces and player pose. The daemon is authoritative for grants, installed package identity and shell leases; lease effects become visible only after plugin acknowledgement. The daemon composes the public state and assigns revisions after acknowledgement. No speculative success response.
Use a private inherited Unix socketpair from a core-owned launcher/adapter handshake, or an equivalently authenticated private connection if Hyprland loads the plugin first. Pin a private bridge version to the core build. Messages carry a session epoch, bounded command ID, operation and deadline; responses distinguish applied/rejected. No GL pointers, compositor objects or client buffer pointers cross processes. Exact private encoding is internal to core and not RFC-0003. Public IPC compatibility does not imply private bridge compatibility.
If the daemon dies, a plugin watchdog releases input grabs and restores ordinary desktop presentation within 1 second. If the plugin unloads or Hyprland exits, the daemon invalidates the session, disconnects clients and closes leases. Reconnection starts a new session and snapshot; do not replay pending mutations. A core-owned compositor binding for emergency exit always works without the shell or daemon. World mode must not interfere with the session lock; locking cancels interaction and stops captures immediately.
Thread ownership
Section titled “Thread ownership”| Owner | Allowed work | Forbidden work |
|---|---|---|
| Hyprland event/render thread | Compositor API, GL object creation/destruction, guarded scene drawing, queued input/focus application | Blocking IPC, file access, parsing large assets, extension code |
| Core CPU workers | Immutable glTF decode, collision build, navigation preparation | Compositor objects or GL context access |
| Daemon loop/workers | Framing, authentication, registry, validation, persistence, process supervision | Calling Hyprland internals or mutating plugin memory |
| Extension process | Granted broker APIs, its own computation and optional approved Wayland surface | Native plugin hooks, raw seat ownership |
Use bounded queues and immutable scene snapshots. Workers publish prepared CPU assets with generation IDs; stale generations are discarded after world reload/unload. Only the render owner uploads and retires GPU resources. No detached threads retaining plugin pointers. Shutdown stops submissions, cancels workers, joins them, drains safe cleanup and unregisters hooks before unloading code.
Render-pass rule (non-negotiable)
Section titled “Render-pass rule (non-negotiable)”Inside a Hyprland render pass, only draw using already prepared resources and read an immutable frame snapshot. Any operation that might trigger compositor rendering MUST be queued until the outer pass is fully unwound. This includes cursor visibility/shape changes, workspace changes, focus operations, window snapshot FBO capture, layer mapping/unmapping and teardown of compositor-owned resources.
A callback named “post windows” is still inside the pass. It is not a safe deferred phase. Queue work to the event loop after outer endRender, assert render nesting depth is zero, and make the required graphics context current via the supported adapter before capture/upload/cleanup. A nested snapshot render must skip Hyprune’s pass through a scoped capture/reentrancy guard. Never assume a zero-delay timer by itself proves the phase is safe. The adapter’s exact hook must be verified against the pinned Hyprland build.
The prototype’s hardware cursor update re-entered rendering and corrupted the active monitor render state, later crashing in CMonitor::useFP16. A software cursor in nested tests concealed it. Test both nested and real DRM sessions before declaring this solved.
Frame graph and budgets
Section titled “Frame graph and budgets”The diagram on Architecture shows the ownership boundary. Per frame:
- After previous outer frame: process bounded deferred compositor operations, update capture leases, unsuspend participating clients, deliver eligible frame callbacks, refresh dirty captures, stage budgeted GPU uploads. Write next immutable frame state.
- Simulation: fixed 60 Hz trusted movement/physics, at most four catch-up steps, then drop excess elapsed time and report overrun (for live input, superseded by the presentation-driven tick; recording and replay keep fixed steps). Input timestamps use a monotonic clock. Late worker results retain the prior valid scene; never block a frame.
- World pass: render opaque geometry to owned color/depth buffers, then transparent geometry, resolve MSAA if enabled. Apply world lighting and tone mapping once.
- Surface pass: sample compositor-approved window textures with the capture’s geometry/UV snapshot; depth-test against world geometry. Preserve desktop color through a separate output transform, with no artistic bloom/exposure on application pixels.
- Composite: present world + surfaces in the room output/workspace below top/overlay shell layers. Preserve compositor GL state through the adapter’s scoped state guard; never clear unrelated outputs or their damage.
- End outer frame: collect bounded timing/damage data, enqueue future work, return to Hyprland. The deferred phase starts only after Hyprland has completed its own render teardown.
Initial engineering budgets: 2 ms per frame for incremental GPU uploads, 4 ms capture work, 512 MiB world GPU assets, 256 MiB capture cache; all measured and configurable downwards. These are targets, not performance claims. Reuse previous textures under load, evict unfocused captures first and report degraded freshness. Avoid glFinish, synchronous readbacks and full-scene recapture. Multi-monitor simulation advances once per tick, not once per output.
Live windows and capture
Section titled “Live windows and capture”Hidden workspaces suspend clients and suppress frame callbacks. An explicit capture lease identifies windows visible on an active world surface; the adapter must call the supported equivalent of setSuspended(false) and pace frame callbacks for those clients while needed. Snapshotting alone does not keep a browser/video alive. Restore prior suspension behavior and release leases on hide, disconnect, lock, close and world exit. Idle or obscured world surfaces do not get an unlimited capture exemption.
Track damage/committed buffer identity and geometry generation; unchanged windows reuse textures. Bound capture cadence by visibility and screen descriptor maxFps. Each captured texture carries matching logical size, crop, scale, transform and surface-tree offsets. Do not combine yesterday’s texture with today’s window geometry. Weak compositor handles are resolved on the owner thread; dead handles produce an unavailable surface, never a stale pointer dereference.
Acceptance and implementation order
Section titled “Acceptance and implementation order”M0: exact Hyprland compatibility gate, unload-safe plugin, static original world, deferred queue assertions, emergency exit and daemon hello/snapshot. M1: live window capture with hidden-workspace liveness, input routing, shell leases and full RFC-0003 control. M2: validated world swaps and sandboxed extension hosts. M3: measured multi-output behavior and external conformance.
Required failure tests: cursor changes under hardware cursor rendering, nested snapshot recursion, workspace switch during capture, daemon/shell death, window close mid-drag, output removal, scene reload with pending worker results, repeated plugin unload/reload, session lock, and capture/VRAM saturation. Core must document actual support; this RFC is not evidence that these tests pass yet.
Amendment M3A: deferred interaction effects
Section titled “Amendment M3A: deferred interaction effects”Hand input and transitions update pure gesture/camera state. Capture leases,
client size configures, native focus, seat enter/motion/button/axis delivery,
workspace tiling and cursor visibility execute through tracked doLater callbacks
or the deferred simulation tick with render nesting zero. A pass draws prepared
surfaces only. Child buffers are leased directly; no recursive compositor
snapshot rendering is required. GL state is scoped for world and workspace FBOs.
Cursor visibility changes only when the desired hide/show state changes. Native
cursor shape requests remain compositor-owned. A nested software-cursor result
is never evidence of hardware-plane safety; core documents the supervised DRM
transition checklist before supervised live testing. Unload cancels queued work and removes
retained pass elements before resources or hooks retire.
Proposed M4 amendment: optional world renderer
Section titled “Proposed M4 amendment: optional world renderer”RFC-0009 proposes a hypruned-supervised optional
GPU renderer. It amends scene-rendering placement only: the plugin retains
compositor authority, input, capture, native surfaces and final composition.
Default in-process rendering and the render-phase rule remain mandatory.
Its private pose/buffer/fence protocol is not public IPC or an extension SDK;
power admission and prepared local fallback are shipping gates. See its staged
M4 plan and measured limitations before treating the spike as desktop support.
Amendment: IPC 0.13 authoring-camera authority
Section titled “Amendment: IPC 0.13 authoring-camera authority”camera.author is a separate launch capability for trusted dev/photo tooling,
never a normal shell grant. In active world control camera.photo accepts metre
position, normalized quaternion orientation, vertical fov (5–140 degrees),
optional NDC lensShift (two components −2..2), and fixed renderScale (0.25–1).
One connection owns the hold. Updates by that connection replace the lens; other
writers cannot take it over. camera.release, disconnect and world exit restore
the prior camera; loading another world resets to its spawn. Movement/look/scope
cannot overwrite a held lens. Captures and debug remain usable. All ownership
changes happen in the owner event loop, outside the render pass.
camera.get on 0.13 returns actual pose, roll radians, vertical FOV, lensShift,
held boolean and renderScale (null if not held). Lens shift moves the optical axis
to NDC (x,y) (+right/+up); roll uses local +Z. The same camera basis/projection
serves scene, sky, rays and core/shell marker projections. Older camera.get keeps
its two-field shape. A photo hold uses the local renderer for exact frame pose;
it does not restart the world or compositor. Recorded camera frames optionally
include roll/shift, defaulting to zero for old files; camera replay preserves them.
IPC 0.15 correction: unzoned mount instances and reconnects
Section titled “IPC 0.15 correction: unzoned mount instances and reconnects”mounts.instances[].areaId is optional. A window floating in a newly entered
world may have no home/placement zone; omit the field in that case. When
present it remains a nonempty slug. Empty strings are invalid. This applies to
snapshots, deltas and mounts.changed. Earlier negotiated schemas retain their
required field, so core omits unzoned mount-instance metadata for those clients;
their ordinary surface/app records remain available.
A trusted launcher may renew credentials through a private inherited channel.
The live supervisor verifies each request’s kernel-supplied PID/UID against its
actual launcher child, then requests a fresh grant from hypruned on a separate
inherited channel. Grants expire after 30 seconds, are bound to the client ID
and launcher PID, and can be consumed once. Renewal cannot add capabilities:
it is restricted to the original launch manifest, at most 8 requests/second,
4096 per launch and 64 outstanding grants. No public IPC issuance method, token
file, command-line secret or QML credential is introduced. down terminates the
supervisor and closes both channels.
Amendment: presentation-driven simulation tick (no wire change)
Section titled “Amendment: presentation-driven simulation tick (no wire change)”Implemented in core on 2026-10-10. A fixed 16 ms timer beat against the display’s
presentation rate, so a shown frame advanced by zero, one or two steps, and mouse look
was applied once per timer tick. The tick is now queued, outside the render pass, on
each presented event of the active monitor; the timer drives ticks only while nothing
is presented. Movement and look use the frame’s measured time, capped at 4/60 s; the
walker and flight sub-step by distance (at most 2 ms of motion per step), so a fast run
cannot pass through thin walls. Recording and replay keep exact fixed 60 Hz steps.
A frame-rate target below the display rate renders new frames on every n-th presentation (n = round(refresh / target)), evenly; those intentional repeats do not count as queue pressure. Interpolating between fixed steps and automatic slowdowns on queue depth were tried and rejected. Measurements: frame-interval variation 0.087 to 0.004 at the default, turning unevenness 0.182 to 0.022, and a steady 30 FPS when GPU-bound; input to first new frame stays 8–10 ms at 60 FPS (progress).