Scene Operations
Publish an ordered, atomic change to a surface’s retained nodes.
A client changes a surface by sending a Commit that identifies the surface, assigns the change a commit ID, and supplies an ordered sequence of DiffOps. The server applies those operations to a candidate scene and validates the complete result before publishing it, so other work cannot observe a partially applied update.
Scene Structure Operations
Structural updates begin with a root descriptor supplied through SetRoot. To extend the hierarchy, AddNode inserts a descriptor beneath a parent, optionally at a chosen index. Existing children can be arranged through Reorder, while RemoveNode deletes a node together with its subtree.
When a framework needs to move an existing subtree, it can use DetachNode to unlink the node while preserving its descendants. AttachNode then mounts either a new descriptor or an existing detached node from the same surface. For a reattachment, the supplied descriptor replaces the node's kind and properties while retaining its descendants.
Do not translate a temporary detach into deletion when the mounting framework intends to move an existing subtree.
Property and Content Updates
UpdateNode identifies an existing node and carries a NodePropertiesPatch, an optional replacement NodeKind, and an optional NodeKindPatch. Use the field semantics in the protocol rather than serializing an ad hoc property dictionary.
Patch fields distinguish leaving a value alone from explicitly changing or clearing it. An absent field preserves the previous value; for an optional property, a nested option can express removal. For example, box_style: None preserves the style, whereas box_style: Some(None) clears it. Optional path fill and stroke use the same convention.
Animatable fields distinguish an immediate assignment from an interpolation. The composer owns interpolation state and frame-time sampling.
Supported Content
Node content describes what the server will draw within the resolved geometry. A View carries rectangular paint, radius, and border styling, while an Image refers to an imported connection-local buffer and its source dimensions. A TextRun supplies positioned glyphs with their paint, font key, and size. The remaining kinds extend the scene with an embedded SurfaceView or immutable Path geometry and styling.
Text has already been shaped when it reaches this boundary. Its GlyphInstance::advance and offset values use screen coordinates, where x increases to the right and y increases downward. A shaper working in font coordinates must invert its y offsets before encoding the run so that the server places each glyph correctly.
Confirmed Scene Baseline
Generate future diffs against accepted state, and correlate outcomes by both surface and commit ID. If the server rejects a candidate, its operations must not become the assumed baseline for the next diff.
Continue with commit outcomes and Hera Kit reconciliation.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/protocol/src/scene/diff.rscrates/protocol/src/scene/nodes.rscrates/graph/src/lib.rs