RFC-0003 — IPC protocol
Status: accepted · proposed 2026-10-07, accepted 2026-10-09. Implemented through IPC 0.28 in core, the reference shell and SDK types; IPC 0.7–0.24 are specified as amendments to RFC-0002, 0004, 0005, 0006, 0008, 0009, 0011, 0012 and 0013.
Decision
Section titled “Decision”Use a restricted JSON-RPC 2.0 profile over an AF_UNIX SOCK_STREAM socket. JSON is inspectable, maps directly to QML/JavaScript, and keeps C++, Python and Rust clients simple. Cap’n Proto and MessagePack add code generation or binary tooling before we have evidence that control traffic needs it. Pixels, PCM audio and per-frame GPU commands never travel over this protocol.
The daemon owns the public socket and brokers shell and extension requests. The plugin owns compositor truth. The shell never calls an extension directly through a privileged backdoor. M0 implements hello, ping, subscribe, snapshot and runtime exit first; other methods return unsupported until advertised. An unadvertised method MUST return -32601, even if its schema exists.
Transport and lifecycle
Section titled “Transport and lifecycle”Socket: $XDG_RUNTIME_DIR/hyprune/$HYPRLAND_INSTANCE_SIGNATURE/control.sock. Validate the instance component against [A-Za-z0-9_.-]+; refuse unset/unsafe values. Never fall back to /tmp. Directory mode 0700, socket mode 0600, owned by the session UID. Bind without following symlinks; only remove a stale socket after proving ownership and no live listener. Check SO_PEERCRED on acceptance.
Each frame is a 4-byte unsigned big-endian byte length, followed by that many bytes of UTF-8 JSON. Length excludes the prefix. Accept lengths 1..1,048,576 inclusive. Handle partial reads and multiple frames per read. Reject zero/oversized lengths before allocating, invalid UTF-8, duplicate object keys, nesting over 64, NaN and infinity. Close on malformed transport; well-framed invalid JSON gets -32700 with null ID before close. JSON batches and client notifications are forbidden in this profile. Requests have a nonempty string ID (max 128 characters), unique while in flight; never reuse an ID on one connection. Responses have the same ID, exactly one of result/error, and no method. Only malformed-request errors may have null ID. Unsolicited server notifications have no ID.
First request MUST be session.hello within 5 seconds. It selects one exact protocol string, initially 0.1; no silent downgrade. A mismatch returns -32001 and closes. Subsequent hello returns -32600. Maximum 64 outstanding calls, 4 MiB queued output per peer, and 10 seconds to complete a received frame. Overflow disconnects the slow client; it reconnects and takes a fresh snapshot. Never block the compositor to drain a socket. Ping is optional liveness, every 10 seconds; clients reconnect after 30 seconds without a response with exponential backoff capped at 10 seconds and jitter.
Every request includes params, even when {}. Method parameters, results, notifications and state are defined in hyprune/schema/v0/ipc.schema.json. The schema admits only this protocol version’s known fields. Clients validate against their negotiated version, not whatever schema is newest on the internet.
Core methods
Section titled “Core methods”| Method | Params | Result | Required grant |
|---|---|---|---|
session.hello |
protocols: string[], client: {id, name}, capabilities: string[], optional token |
protocol, sessionId, capabilities, methods, events |
none |
session.ping |
{} |
monotonicMs |
none after hello |
state.subscribe |
topics: ["state"] |
subscriptionId, snapshot |
state.read |
state.snapshot |
subscriptionId |
snapshot |
state.read |
state.unsubscribe |
subscriptionId |
ok: true |
state.read |
world.load |
worldId, optional spawnId |
revision |
world.control |
surface.focus |
surfaceId, intent: "pointer" | "keyboard" |
revision |
surface.control |
movement.set |
modeId |
revision |
movement.control |
shell.claim |
outputs: string[] |
leaseId, revision |
shell.control |
shell.release |
leaseId |
revision |
shell.control |
shell.overlay |
leaseId, outputId, visible, exclusiveInput |
revision |
shell.control |
runtime.exit |
{} |
revision |
runtime.control |
IDs are opaque strings, scoped to the session; no memory addresses or process IDs. Installed world IDs and mode IDs are reverse-domain identifiers, never paths or shell commands. world.load resolves only installed, validated packages. Mutations serialize at the authority boundary, return only when applied (or rejected), and return the committed state revision. A successful load means the new scene is ready and atomically activated; failure leaves the old world intact. Calls have a 30-second server deadline, return -32006 if not committed by then, and MUST NOT apply after that error. After a connection loss the client must inspect state before retrying; lost responses may represent completed commands. There is no implicit retry or cancellation method in v0.
surface.focus(pointer) selects a pointer target without moving the workspace or granting keyboard focus. keyboard is an explicit user intent and may return unsupported for hidden-workspace surfaces. The plugin resolves compositor focus safely after the frame. runtime.exit leaves world mode and restores ordinary desktop input; it does not terminate Hyprland or the helper.
hello.methods is the implemented subset of the table, filtered by grants; hello.events is the supported event subset. Ping and hello are always implemented. A conforming interactive shell requires the methods listed in RFC-0008; a partial M0 core is not yet shell-conformant.
Snapshot, deltas and ordering
Section titled “Snapshot, deltas and ordering”A snapshot is {sessionId, revision, state}. revision is an integer 0..9007199254740991; restart the session before overflow. state has exactly runtime, world, surfaces, movement, shell. Runtime contains active and outputs (stable opaque output IDs). World is null or {id, spawnId}. Surfaces is an array of {id, kind, title, logicalSize: [width,height], focused}. Movement is {modeId, position: [x,y,z], orientation: [x,y,z,w]} in world coordinates. Shell is {leases: [{id, outputs, overlays: [{outputId, visible, exclusiveInput}]}]}. Surface titles are privileged session information: no state.read, no snapshot.
state.subscribe atomically captures a snapshot at revision R and registers delivery of every subsequent visible state change. Queue the response before any notification for that subscription. At most one subscription per connection (duplicate -> -32004). state.snapshot resets that subscription’s baseline in the same way: discard its unsent deltas, enqueue snapshot response, then later deltas. Previously written frames precede the response and can be discarded by a client awaiting resync.
state.delta params: {subscriptionId, sessionId, baseRevision, revision, changes}. Changes is a nonempty object containing whole replacement values for one or more of the five state keys. No JSON Patch, array-index edits or implicit merges. A revision increments on each published transaction, not each monitor render; revisions may jump when coalescing. Apply only when session matches and baseRevision equals the local revision. Replace included keys atomically and advance to revision, which MUST be greater than baseRevision. On any gap stop applying deltas, call state.snapshot, and resume after its response. Subscription IDs and all session-scoped IDs die on reconnect. Snapshots are bounded by the frame limit; reject resource creation that would exceed it with -32008 rather than publish truncated state.
Publish at most 30 state deltas/second per peer; coalesce pending replacements while preserving the original baseRevision and latest revision. Desktop actions may commit faster; their replies may precede a later coalesced delta. The shell interpolates presentation between samples (about 70 ms buffer), but never predicts grants, focus, world activation or lease ownership. Runtime simulation and input do not depend on this rate.
Other notifications:
| Event | Params | Delivery |
|---|---|---|
runtime.notice |
level: info/warning/error, code, message |
hello-complete peers with state.read; transient, not replayed |
session.revoked |
reason |
send if possible, then close immediately |
No separate surface-created event: surface lifecycle is authoritative in state. There is no persistent event replay log in v0.
Authorization and failure isolation
Section titled “Authorization and failure isolation”SO_PEERCRED proves the local UID, not extension identity. Same-UID processes are not isolated by Unix file permissions. An ordinary connection gets only ping/hello; read and control grants require a daemon-issued random 256-bit bearer token, encoded as exactly 64 lowercase hexadecimal characters. Trusted shell launch receives a token through an inherited FD, never argv, world data or logs. Tokens are bound to an approved installed client ID, daemon session, requested capability subset and expiry; hello consumes the launch token once and binds grants to the connection. Reconnect requires a new launch token from the supervisor. Client-supplied IDs are labels until authenticated. No persistent blanket token file.
The user’s local policy stores approvals for package digest + requested grants; new capabilities or changed package digest require a new approval. Daemon-supervised extension processes receive only their own socket connection/token. Sandboxing is required before advertising isolation: deny the host runtime directory, arbitrary Wayland access, host process inspection and network by default; expose only explicitly brokered FDs. Unsandboxed same-UID extensions are marked trusted and can escape the capability model through the host session. M0 loads no third-party executable extensions. The public socket never accepts GL pointers, raw input injection or arbitrary filesystem access.
Grant names are exactly state.read, world.control, surface.control, movement.control, shell.control, runtime.control. A shell may request all six, but the daemon returns only approved grants. Capability revocation closes the connection, releases leases, cancels uncommitted operations and sends session.revoked when possible. Read-only clients cannot claim overlays or move focus.
Standard errors: -32700 parse, -32600 invalid request/profile, -32601 unknown/unimplemented method, -32602 invalid params, -32603 internal. Hyprune errors: -32001 incompatible protocol; -32002 unauthorized; -32003 unknown resource; -32004 conflict/stale lease; -32005 unavailable (plugin disconnected); -32006 deadline exceeded before commit; -32007 unsupported operation; -32008 resource limit. Error data, when present, is {retryable: boolean}; never include secrets or pointers. Valid request IDs are echoed on errors. An internal failure must not crash the daemon or compositor.
Versioning and acceptance
Section titled “Versioning and acceptance”v0 names the schema family; 0.1 is its first exact wire contract. Any field or semantic change requires a new protocol identifier and matching schema/changelog, even when additive. Negotiate only implemented versions. Package format versions and protocol versions evolve independently. No stable plugin ABI is promised.
Before M1, test split/coalesced frames, malformed lengths, unauthorized methods, disconnect during mutation, snapshot/subscription races, slow consumers, revocation, reconnect after daemon restart, and hidden-workspace focus rejection. The schema validates shapes; session sequencing, grants and state transitions require runtime conformance tests.
Amendment M1: negotiated IPC 0.2
Section titled “Amendment M1: negotiated IPC 0.2”0.2 is an exact new minor contract, defined by hyprune/schema/v0.2/ipc.schema.json. Core supports both 0.1 and 0.2, preferring 0.2 when both are offered. A 0.1 peer receives only its original five state keys, methods and events. Schema library callers select validate(kind, value, method, "0.2"); the default remains 0.1. The SDK’s 0.1-mock.1 is not a real protocol and is never negotiated by core.
Rationale: the first SDK mock and shell work exposed missing camera control, destinations and routes, timed travel, UI opening, and integration data. These are world authority, not shell-local guesses. Keep the mock’s camera.set, waypoint.set, ui.open, data.publish and ui.opened/data.updated names, but replace the mock-only permission assumptions and replay model with the following contract.
Added methods
Section titled “Added methods”All mutation results contain the committed revision; camera.get instead returns {position, orientation}. Vectors are world metres, camera/point positions are eye positions, quaternions are normalized [x,y,z,w]. Zone destinations resolve to the horizontal bounds centre, minimum Y + 1.7 metres. A Target is exactly {zoneId} or {position:[x,y,z]}. No world/package paths are accepted.
| Method | Params | Grant |
|---|---|---|
camera.get |
{} |
state.read |
camera.set |
{position, orientation} |
movement.control |
waypoint.set |
{id, label, target:Target}; also {id,label,position} for mock migration |
world.control |
waypoint.clear |
{} |
world.control |
route.set |
{points:Target[]} (1–64 points) |
world.control |
route.clear |
{} |
world.control |
travel.start |
{to:Target, durationMs?:0..10000} (default 600) |
movement.control |
travel.cancel |
{} |
movement.control |
autodrive.start |
{speed?:0.1..10} metres/sec (default 3.5) |
movement.control |
autodrive.stop |
{} |
movement.control |
ui.open |
{leaseId, outputId, panel} |
shell.control |
ui.close |
{leaseId, outputId} |
shell.control |
data.publish |
{sourceId, sequence, values, ttlMs?} |
data.publish |
data.remove |
{sourceId} |
data.publish |
camera.set is an explicit placement, not simulated movement; core M1 rejects roll and pitch outside ±1.49 radians with -32007. It cancels automatic motion. travel.start atomically starts a transition and returns immediately, rather than holding an RPC open for the animation. It requires active world mode, rejects concurrent automatic movement and obstructed destinations, interpolates the camera through world geometry as an intentional warp, and commits the destination on completion. Zero duration gives reduced-motion clients instant placement and an arrived event. Cancellation leaves the camera where it is. World replacement, exit, lock, and helper failure cancel motion. autodrive.start follows the explicit route from its beginning using capsule collision checks; obstruction stops it. M1 does not perform pathfinding: authors/clients supply navigable intermediate points. Routes and waypoints are world-scoped and clear on world replacement.
Core owns hold-to-open timing: M1 consumes Tab in exploration mode, opens overview after a continuous 350 ms hold, and leaves the panel open on release. Short taps do nothing. Escape closes the overlays and cancels movement; F12 remains emergency exit. UI commands require a connection-owned lease and a member output. Open/close update lease visibility and emit the corresponding event. No opaque panel identifier executes code. M1 leases/nonexclusive overlays are implemented, but exclusiveInput:true returns -32007 until the trusted launcher supplies a verified Wayland-client association; this partial implementation must not claim full RFC-0008 interactive-shell conformance.
State and events
Section titled “State and events”The original five state keys remain. 0.2 adds two whole-replacement keys:
location:{zones, waypoint, route, autodrive, transition}. Zones are current world manifest zones. Waypoint is null or{id,label,target,position}; route contains{target,position}entries; autodrive is boolean. Transition is null or{id,outputId,phase,progress,to,monotonicMs}. The session-scoped ID remains stable throughout one operation; outputId is null before a world monitor is selected.phaseisloading,departing,travelling,arrived,failed, orcancelled. Progress is null for indeterminate loading and otherwise 0..1.tois a Target for point/zone travel, or{worldId,spawnId?}for world loading. Core timestamps every transition sample. The latest terminal transition remains in state until another transition/world replacement, so a reconnect can dismiss its warp overlay correctly.integrations:{sources:[{sourceId,sequence,values,monotonicMs,ttlMs}]}. Each entry is the last complete publication, removed on TTL expiry, explicit remove, or publisher disconnect.
Additional transient notifications are location.transition {id,outputId,phase,progress,to,monotonicMs}, ui.opened {leaseId,outputId,panel}, ui.closed {leaseId,outputId}, and data.updated {sourceId,sequence,values,monotonicMs,ttlMs}. Each also carries sessionId and revision linking it to committed state. Only subscribed state.read peers on 0.2 receive these; subscribe/snapshot responses precede future notifications. Events are presentation hints, not patches and not a replay log. A shell’s warp overlay uses transition phase/progress/to; a fresh snapshot is authoritative after any disconnect/gap. world.metadata from the mock is replaced by revisioned location.zones and location.waypoint, avoiding a second unversioned state channel. No separate camera state is needed: movement already carries the pose.
Publishing authority and bootstrap
Section titled “Publishing authority and bootstrap”data.publish is a new explicit launch-token capability. state.read never grants publishing (the mock-only mapping is retired). Source IDs must equal the authenticated client ID or be beneath its dot namespace, and one connection owns each source. Each publication completely replaces values: at most 32 scalar number/boolean/string properties, string values at most 256 characters, total values at most 16 KiB. No executable values, paths to read, host metrics collection, or network privileges are implied. Sequence is an increasing safe integer per live source. Server receipt time supplies monotonicMs; TTL is 100..60000 ms, default 5000. Maximum 32 live sources and 64 KiB aggregate serialized values, at most 10 publications/sec per source; overflow returns -32008. Ownership/stale sequence conflicts return -32004; namespace violations return -32002. Publishers should remove their source when stopping; disconnect cleanup is mandatory.
For a trusted supervised SDK process, HYPRUNE_SOCKET, HYPRUNE_CLIENT_ID, and HYPRUNE_PROTOCOL describe the connection; HYPRUNE_TOKEN_FD contains exactly 64 lowercase hex bytes plus newline and is consumed/closed once. These client bootstrap names are distinct from core’s private HYPRUNE_LAUNCH_FD JSON grant-injection pipe. Reconnect requires a newly issued token; never persist one or auto-replay mutations. Core M1’s nested launcher exercises the private grant pipe; a production process supervisor and Quickshell-native transport remain separate integration work.
Shell gap disposition
Section titled “Shell gap disposition”The shell gap notes arrived during M1. The warp sequence now includes operation ID, output, monotonic sample time, indeterminate loading and terminal failed; core flushes loading notifications while the load RPC is pending. World activation and arrival remain atomic. A disconnect detected while loading cancels the pending activation; a response lost after commit still requires snapshot reconciliation. Only one world/automatic-motion operation is active on M1’s one world monitor. F12/lock take priority; Escape cancels a pending load. Already committed timed travel may continue across requesting-client disconnect; resubscribe to recover its state.
ui.opened/ui.closed are the canonical event names, retaining SDK mock compatibility; ui.open/ui.close name the methods. Lease/output and state revision arbitrate stale events; no separate UI timer or hold progress is required. Release keeps the panel open; dismissal calls ui.close, and lease disappearance hides it. There is no acknowledgement handshake or automatic UI timeout in M1.
The remaining shell proposals are explicitly deferred: output descriptors/Wayland-name mapping (the trusted launcher must still map the selected opaque output), per-output projection/marker data, immutable world/map asset delivery and installed catalog, workspace-to-location mappings and workspace.activate, settings/approval UI, and supervisor token renewal/Wayland association. Core M1’s runtime.outputs describes the selected world monitor (retained while inactive), not all compositor outputs. These omissions must stay unavailable in the shell; they are not inferred from the new camera pose method or arbitrary package paths.
First-session amendment: negotiated IPC 0.3
Section titled “First-session amendment: negotiated IPC 0.3”v0.3/ipc.schema.json introduces shell.bind({leaseId,pid}) (shell.control) and workspace.activate({id}) (world.control), each returning {revision}. See RFC-0008 for the verified Wayland association. Only IPC 0.3 advertises these methods. Older clients retain exact five/seven-key snapshots and cannot claim new association semantics.
Two whole-replacement state keys are added: spatial:{world,map,output,projection} (all nullable) and workspaces:{currentId,locations}. World contains {id,name,places:[{id,name,position}]}; output contains {id,name,width,height,scale} describing the selected output’s pixel viewport and Wayland name. Projection and safe inline-map conventions are defined in RFC-0008. Locations contain at most 32 trusted launcher entries {id,label,worldId,spawnId}; positive integer IDs denote ordinary Hyprland workspaces. No public RPC changes that mapping or reads an arbitrary file. Workspace activation uses the compositor dispatcher outside the frame; the real active-workspace notification initiates the same atomic world-load transition, including when switched by a compositor key binding. A different spawn in the same world is also a location transition. A failed load retains the previous world and publishes failed; the compositor workspace remains the one the user selected. Switching again while loading cancels the pending activation and resolves the latest workspace after cancellation. Unmapped workspaces preserve the current world.
Map/metadata are immutable for one committed world generation. Projection timestamps may change at the bounded state delivery rate. All mutation replies and state remain revision ordered. 0.1/0.2 projections omit both new keys; no new fields appear in those frozen contracts. Credentials and peer PID remain private daemon-to-plugin context and never enter public state.
Amendment M2: IPC 0.4
Section titled “Amendment M2: IPC 0.4”IPC 0.4 adds mounts and presentation as atomic snapshot/delta keys; every
older projection remains exact. Schemas are schema/v0.4/ipc.schema.json.
mounts contains areas, normalized anchors, placementZones, workspace bindings,
durable placements, live tool instances, data objects, carriedSurfaceId and
desktopWorkspaceId. presentation contains the active atmosphere profile,
vertical FOV degrees (30–110) and quality:high|intel.
| Method | Parameters | Grant |
|---|---|---|
| workspace.bind | {id,worldId,areaId} (loaded world) |
world.control |
| workspace.focus / workspace.unfocus | {id} / {} |
surface.control |
| surface.pull / surface.return | {surfaceId} |
surface.control |
| surface.place | {surfaceId,anchorId?} |
surface.control |
| surfaces.recall | {} |
surface.control |
| placements.list | {} |
state.read |
| placements.remove | {worldId,areaId,rule:{appClass,title}} |
surface.control |
| data.object.bind | {objectId,sourceId} |
data.publish |
| atmosphere.get / atmosphere.set | {} / {profile} |
state.read / world.control |
| camera.fov | {degrees} |
movement.control |
Mutations return {revision}. placements.list returns {placements};
atmosphere.get returns {profile,quality}. Discover implemented methods in hello.
camera.get/set retain their existing pose-only shape. Atmosphere mutation can
change fog/exposure/tone/bloom; changing sky/environment assets requires immutable
package reload and returns -32007. No path received in IPC is opened.
mounts.changed {mounts} and presentation.changed {presentation} are optional
presentation hints carrying sessionId/revision; subscription state is the recovery
baseline. Surface lifecycle still comes from state. Placement relocations use
runtime.notice codes placement.relocated / placement.recalled and revisioned
placement/instance state. Older versions never receive the new events.
Amendment M3A: IPC 0.5
Section titled “Amendment M3A: IPC 0.5”IPC 0.5 adds whole-replacement state/delta keys interaction and apps.
interaction is {mode,tool,tools,noclip,cursor,taggedSurfaceId}: mode is
movement/typing/workspace/fullscreen, tool is 1–5, tools is five pointer/mount/path
slot IDs, cursor is desktop/workspace/fullscreen/director/virtual/reticle, and the
tag is a nullable opaque live surface ID. apps is at most 16 descriptors
{surfaceId,workspaceId,title,appClass,icon}. The icon is a desktop icon theme
name derived from the app class, never a path or remote URL. Titles remain
privileged by state.read. No raw input injection or configuration RPC is added.
An arbitrary durable placement retains {worldId,areaId,rule,anchorId:""} and
adds pose:{position,rotation} and size:[width,height] in metres. Authored
placements retain their existing shape and nonempty anchor ID. Restoring a user
pose revalidates its quaternion, dimensions and full collision OBB. Immutable
world packages do not change. Older 0.1–0.4 peers retain exact projections;
arbitrary placements are omitted from their lists and mount state. The local
Lua config API is separate from public IPC. Canonical schemas are v0.5.
Amendment: IPC 0.6 / M3B
Section titled “Amendment: IPC 0.6 / M3B”Exact opt-in protocol 0.6 adds closed keymap and editor snapshot/delta fields. input.get and input.preview require state.read; input.set, input.capture, and input.capture.cancel require input.control. input.set validates and atomically persists the independent file, returning the resulting revision. Preview returns canonical config, internal conflicts and mode-scoped Hyprland collision descriptions. Internal conflicts prevent save; stealing native bindings is allowed. Capture requires the active verified Director lease and records one chord/button/wheel into keymap.capture; shell edits its draft and saves through core. It never writes config files.
The schema version is 0.6; a standalone input schema validates files. Scope projection may reach 3° FOV. Older exact versions omit new fields/methods and clamp reported projection to their existing minimum. ui.opened.panel = map tells the Director to select Map. Input/editor data retain the existing bounded framing and authenticated connection authority.
Later revisions
Section titled “Later revisions”IPC 0.7 through 0.20 are specified as amendments in the RFCs they mostly affect: RFC-0002, RFC-0004, RFC-0005, RFC-0006, RFC-0008 and RFC-0009. IPC 0.21 is RFC-0012’s P1 amendment; IPC 0.22 and 0.23 are RFC-0011’s P1 and P2 amendments; IPC 0.24 is RFC-0013’s live state amendment; IPC 0.25 is RFC-0010’s companions amendment. IPC 0.26 is the amendment below; IPC 0.27 is RFC-0011’s workspace screens amendment. IPC 0.29 (draft) is RFC-0008’s motion feel amendment, with even pacing in RFC-0009. IPC 0.30 (draft) is RFC-0008’s settings presets amendment. IPC 0.31 (draft) is RFC-0014’s primitives and materials amendment. The IPC schema reference lists every version with its diff and links each to its amendment.
Amendment: IPC 0.26 (debug tool, companion pace, longer pocket list)
Section titled “Amendment: IPC 0.26 (debug tool, companion pace, longer pocket list)”Status: accepted · proposed 2026-10-13. The IPC 0.26 schema
inherits 0.25 and changes three things. There is no new method, event or grant;
session.hello reports 0.26.
Tool 9, the debug tool
Section titled “Tool 9, the debug tool”Core’s debug tool (key 9, see the keymap) shows one debug layer at a time over the
world. Until 0.26, peers saw it as tool 1 in mode normal. From 0.26 core names it:
-
toolis 1–5 or 9 ininteraction,editor,hud.poseandtool.changed;tool.changednames slot 9debug.editor.submodeis the shown layer’s id:windows,window-zones,collision,playable,paths,keep-clear,seats,visibility,steeringorplacement. -
editor.toolDefinitionslists six tools: slots 1–5 in order, then slot 9 (Primarydebug.inspect, Secondarydebug.clear, Cycletool.cycle). -
The world action
tool9(default9) is part of the keymap,input.get,input.previewandinput.set, with its conflicts and Hyprland collisions. -
Required
editor.debugTool:nullwhile another tool is out, elseField Meaning layerThe shown layer’s id (as editor.submode).labelIts name, ≤64 characters (“Collision & backstops”). index,countThe layer’s 0-based position and the number of layers; Cycle steps through them. legend≤8 {label, colour}: what each colour means;colouris sRGB[r, g, b], 0–1.cardThe info card Primary opened: 1–8 lines of ≤256 characters, or null.
Core draws the banner, legend and info card itself; a shell may use debugTool for its own tool
indicator and hints but should not draw them a second time. Peers below 0.26 keep the previous
projection: tool 1, submode normal, five tool definitions, no tool9 action, no debugTool.
Companion pace
Section titled “Companion pace”companion state gains a required pace: walk (the default) or run, the pace the companion
keeps while following. companion.mode takes an optional pace next to mode; the companion’s
Walk with me / Run with me interactions (interaction.choose) set it too. The pace is persisted
and stays across modes and companions. Peers below 0.26 see no pace and can’t send one.
Longer pocket list
Section titled “Longer pocket list”The pocket list editor.unplaced.windows and mounts.instances were capped at 16 items while
core kept every record, so a shell listed at most 16 pocketed or placed windows. In 0.26 both
allow 128 items, the existing apps limit; editor.unplaced.count allows 144 (128 windows and
the 16-item object pocket, which is unchanged). Listing the whole set was chosen over paging: the
lists are small records, publishes are deltas sent only when a key changes, and a shell needs no
extra request to show everything. Core lists the selected pocket item and the carried window
first when it has to cut a list; peers below 0.26 keep the 16-item lists and a count of at most
32.
Amendment: lease renewal and release while locked (no wire change)
Section titled “Amendment: lease renewal and release while locked (no wire change)”Status: accepted · 2026-10-14 · core 0.8.3. A session lock leaves world mode, and a shell
gives its output lease back when world mode ends. Until core 0.8.3 every method was refused
with -32005 while the compositor session was locked, shell.release included, so the lease
outlived the lock and the shell’s next shell.claim was refused with -32004 “output already
leased”: the shell had no HUD until it restarted.
shell.releaseis accepted while the session is locked; every other method is still refused with -32005 then.- A
shell.claimfrom the connection that already leases one of the requested outputs is a renewal: core ends that connection’s leases on those outputs (an open panel on them sendsui.closed) and returns a newleaseId. A claim from another connection is refused with -32004 as before.
A shell should still release its lease when world mode ends, and claim again on the next entry rather than blocking claims for the rest of the connection after one refusal.