Documentation menu

Input and Focus

Route device input through server-owned seat policy and the scene that was confirmed on the display.

Hera routes device input according to the composition controlled by the server. The server reads the devices, the composer resolves the receiving surface and node, and the client handles the resulting application action. Keeping target selection alongside display geometry helps ensure that an interaction reaches the interface the user sees.

Hit Testing and Displayed Geometry

Target selection begins with the latest scene confirmed as presented by the renderer. A newer submitted scene may still be waiting for GPU execution or display activation, so using it immediately could send an event to a control that has not yet appeared on screen.

Hit testing applies surface placement, node transforms, clipping, and HitKind. A client should preserve the supplied target and coordinate provenance rather than repeat a hit test against a newer speculative tree.

Pointer Provenance

A pointer event can carry the server's targeting result in PointerTarget, including the node, retained commit, and target-local coordinates. Those coordinates account for placement and transforms that a surface-local position alone cannot express. Clients need to preserve that distinction when content is scaled, rotated, or embedded within another surface.

Hera Kit's host only retains target metadata that matches its confirmed commit and node. Input from another scene version must not accidentally activate a callback associated with different accepted geometry.

Touch Stream Continuity

Touch targeting continues beyond the initial hit test. Each contact keeps its Start target until End or Cancel, and a packet groups changes for one start target. Consumers must preserve point order so that, for example, a Cancel is processed before a subsequent Start reuses the same contact ID.

Treating each move as a fresh hit test would transfer an in-progress gesture between controls and break cancellation semantics.

Keyboard Focus and Application Lifetime

When keyboard ownership moves between surfaces, KeyboardFocusChanged reports the loss before the gain, and later key events on each connection follow its notification. Existing key streams remain with their original ownership rather than transferring to the newly focused surface.

Within the focused surface, the toolkit makes a further decision about which control receives keyboard actions. That local focus can change independently of the server's choice of surface, and losing surface focus does not destroy or deactivate the application.

See input protocol and Hera Kit input.

Source Reference

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

  • crates/server/src/input/mod.rs
  • crates/composer/src/input/hit_test.rs
  • crates/composer/src/input/seat/mod.rs
  • crates/kit/src/host/mod.rs