The long-lived mantle process. Owns capabilities, idle-notify, PAM, polkit, session processes, the file watcher and the control socket; spawns the Renderer and respawns it after a crash. See CLI.
Renderer
The mantle-renderer process: the Lua VM, the scene, the Wayland client and painting. One per generation. See runtime.
Generation
One Renderer process and its Lua VM. Only a Renderer replacement (after a crash) starts a new one; a reload does not.
Instance directory
$XDG_RUNTIME_DIR/mantle/<pid>-<start ms>/, one per running mantle: control socket, log, lock file, icon spools. mantle list, log, set, toggle and call pick one. See which shell.
Check mode
mantle check: evaluates and lays out the config with no Wayland, no subprocesses and no state writes; it lays out once with every capability nil, then once per sample set: first values, alternate values and empty lists. See what check covers.
Session process
A session_process program the Supervisor owns. Survives reloads and Renderer replacement; stopped at shutdown with its declared signal, then SIGKILL after 5 s. A process.run child, by contrast, dies at the next reload.
One run of shell.lua and the modules it requires, producing the surface list.
In-place reload
A re-evaluation in the same generation and VM, then one apply. See runtime.
Surface fingerprint
A declaration’s creation-time fields (panel: id, layer, anchor, output, namespace; other roles: id). A change rebuilds that surface; other edits update it live.
Evaluation-scoped registration
action, on_change and idle-threshold callbacks, cleared before each evaluation because they close over its locals. The timers an evaluation arms go live only when its result applies. See what survives a reload.
Rollback
A failed evaluation or reload keeps the previous scene; a failed live update keeps the previous tree of each surface it broke. What stays registered: runtime.
Rescue
mantle.rescue, { is_rescue, error_log }, set while the shell runs on a scene it could not replace. See runtime.
A top-level declaration returned by shell.lua, with one role and one or more instances. See surfaces.
Surface role
panel (layer-shell), window (xdg_toplevel), popup (xdg_popup) or lock (session lock).
Surface instance
One mapped copy of a surface. Per-output panels and locks are keyed {id}@{output}; windows, popups and output = "active" panels use the bare id.
Structural property
A property read once per evaluation to make a structural decision, so it refuses a signal: any node’s id; a panel’s layer, anchor, output, namespace; a popup’s parent.
Lock surface
The lock declaration’s instance on one output, alive only while the session is locked.
An element in a surface’s tree: row, text, list and the other kinds.
Node identity
How a node is matched across evaluations, scoped to its parent: sibling id or list key (which wins), else position among id-less siblings. An unmatched node is new and starts fresh.
Paint-only property
A property whose change repaints without relayout (opacity, colours, radius, shadows, blurs, transforms, progress). Its tweens tick without a layout pass.
Shader node
shader: a config .frag drawn as a node. Editing the file reloads.
A node that takes keyboard focus: a textfield, or a node with on_click or submits_secure and a nonempty accessible_name. Tab walks them; Enter and Space activate. See keyboard controls.
Keyboard focus
The surface the compositor sends keys to, plus the popups shown under it. Only its controls take keys. See panel.
Path node
path: vector commands filled or stroked in the node’s box, without an SVG file.
A reactive value. Pass it to a property to keep that property live; :get() is a snapshot. See signals.
Derived signal
A signal computed from others: :map, computed, delay, pulse. See derived signals.
Named state
A state(name, initial) signal, keyed by name. Survives reloads until a scalar initial changes; lost with the generation. mantle set and toggle write it.
Input signal
An engine-written, name-keyed signal: hover, hover_rect, pointer, scroll, geometry. Survives reloads like named state.
Change handler
An on_change(fn) callback, run with the current and previous payload on each capability, rescue or screens push, or on a state after a write changes it.
Persistent table
persistent_table: a JSON file read as signals and written one key at a time.
Idle threshold
An inactivity duration with idle and resume callbacks, registered on mantle.idle and cancellable by its handle.
Idle inhibit
A hold that stops idle actions, shared by the config and org.freedesktop.ScreenSaver clients.
A backend owning one slice of platform state and its actions, read in Lua as mantle.<name>. See capabilities.
Capability start
The first mantle.<name> read (or secure_submit naming it) starts the backend for the Supervisor’s lifetime. mantle.idle starts on its first method call; lock and the polkit controller exist from boot.
Snapshot
A capability’s full state, pushed on change. An equal payload is not pushed again, except for tray and notifications, whose icon files change in place.
Push
A capability sending a new snapshot. Every property reading that capability re-resolves.
Hydration
The Supervisor replaying its last snapshots to a new generation. Before its first snapshot a capability reads nil.
Action
A capability method such as mantle.audio:set_volume(sink.id, 50), fire and forget; or action(name, fn), which exposes Lua to mantle call.
Mantle namespace
The mantle table: capabilities, plus the Renderer’s screens, rescue, version, config_dir and pid.
Secure submit
A secret text field sending its buffer straight to a capability action, never through Lua. See secure fields.
Toplevel window
Another application’s window, listed by the windows capability. Not the window surface role.
Do-not-disturb
A notifications toggle that silences non-critical sounds. It does not filter the feed.