Messages and Surfaces
Create client-owned surfaces, follow their geometry, and distinguish ordinary client requests from shell operations.
The two message enums, ClientToServer and ServerToClient, describe requests and events whose lifecycles continue over the connection. A client therefore needs to dispatch events according to their meaning, rather than assuming that every request is followed immediately by one uniform reply.
Surface Lifecycle
To add UI to the composition, send CreateSurface { name } and retain the ID returned by SurfaceCreated. The server may subsequently send SurfaceChanged with authoritative dimensions, including dimensions imposed by composition. When the surface is no longer needed, DestroySurface requests teardown and SurfaceDestroyed confirms its removal.
Clients send scene commits for surfaces they own. A surface ID does not grant authority to modify another client's retained nodes.
Shell Notifications
The shell receives surface announcements containing the surface ID, owning client ID, and optional name. It can compose application surfaces using SurfaceView nodes and respond to input requests.
Input requests also pass through shell policy. A client uses RequestInput to ask for ownership, which the shell can observe through SurfaceRequestedInput. The shell-controlled workflow grants focus through GrantInputFocus, so making a request does not itself give a client global focus.
An authenticated shell can request CloseApplication to forcibly terminate the process owning a surface, including that process's other windows. The resulting surface-destruction notifications confirm cleanup. A vanished target is already closed and succeeds as a no-op; a failed termination can instead report ApplicationCloseFailed.
Rendering Progress
Rendering progress is reported at several boundaries. CommitAccepted and CommitRejected resolve whether a scene update entered retained state, after which CommitAck can report its GPU submission. Frame timing is reported independently: FrameScheduled provides an advisory estimate, while FramePresented identifies a display activation.
Dispatch these messages according to the outcome they identify. A generic Error, for example, carries no commit correlation and cannot determine which pending candidate should be rejected. The commit outcomes guide explains the state needed to handle those distinctions.
Resources and Input
Other resources and event streams have their own completion rules. Buffer retirement ends with BufferReleased, while device input arrives through InputEvent with its destination surface and optional selected node. Changes in keyboard ownership are delivered through KeyboardFocusChanged before subsequent key traffic for that ownership.
Read the enum definitions when implementing exhaustive dispatch. Adding a wire variant is a contract change even if an existing application does not use that variant.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/protocol/src/messages.rscrates/server/src/client/surfaces.rscrates/server/src/client/shell.rscrates/server/src/client/process.rs