Documentation menu

Backend Integration and Migration

Use raw scene and hosting APIs explicitly when a specialized client needs control below ordinary view authoring.

Specialized integrations sometimes need access below the public view-authoring layer, for example to host Kit on another transport or arrange surfaces in a shell. hera_kit::backend provides that access through the evaluated client tree, raw node builders, layout and reconciliation types, and AppCore.

Public and Backend API Boundaries

Most applications can let AppHost evaluate impl View descriptions and maintain their state through bindings. A backend integration takes on more of that work by constructing UiNodes, managing raw geometry, or driving threading::UiLoop directly. Choose this boundary when the integration actually needs those responsibilities.

These are still client-side operations. Raw node access does not move display rendering out of Hera's server.

Authoring API Migration

Older custom views that implemented View::build(rt, env) -> UiNode should move their application composition into View::body(cx) -> Result<impl View, ViewError>. In that public API, rectangle(paint) replaces ordinary view(paint) authoring, and view_fn supplies a closure body. Reserve backend::node_fn for closures that deliberately construct raw nodes.

Raw tree types such as UiNode, NodeBuilder, and AppCore now require explicit backend imports. Their geometry setters, .node_frame, .node_offset, and .node_opacity, replace stored node values. The public .frame, .offset, and .opacity names remain compositional modifiers, making the distinction visible at the call site.

The raw grid_row helper belongs to backend construction. It is not a root-level public component alongside grid.

Custom UI Loops

Dispatch commands in server order, call render_pending, send the candidate diff, and deliver its matching accepted or rejected outcome before publishing another candidate. Preserve target provenance and bounded transport pressure.

Even when evaluation produces no wire changes, publishing the local candidate can refresh its callbacks and ownership. Nonempty candidates instead need a matching retained outcome before the host advances its baseline. A generic transport error provides no such correlation and cannot safely substitute for rejection.

Accepted State Inspection

AppCore::inspect() exposes the accepted tree, layout, coordinate information, mounted storage, and focusability. It is useful for debugging geometry without confusing a speculative candidate with the current accepted baseline.

See reconciliation internals before implementing an alternate host.

Source Reference

The following files in the Hera checkout define the behavior described on this page.

  • crates/kit/src/backend.rs
  • crates/kit/src/app/mod.rs
  • crates/kit/src/threading/mod.rs
  • crates/kit/README.md