Documentation menu

Input, Focus, and DOM Interaction

Translate accepted Hera input into WPE events while coordinating native controls and focus inside the web page.

The web view receives input through the same server-targeted scene as native Hera Kit controls. The host first preserves the event's target provenance, Kit selects the accepted handler, and the package translates that handler's input into WPE events. This keeps pointer geometry tied to the composed page region rather than to an independent engine window.

Local Pointer Geometry

WebView requests pointer capture and gives its handler access to captured or server-selected target-local coordinates. The translator prefers captured geometry during an ongoing interaction, falling back to the target's local position when available. It does not substitute the event's surface-local coordinates if neither source exists, because those coordinates may include toolbar placement or other transforms outside the page.

The browser also uses Kit's InputLineage before dispatch. A displayed page can be older than the newest accepted buffer after a paint-only update, so compatible lineage can preserve that targeting relationship without accepting arbitrary geometry from a different layout.

Mouse and Wheel Events

The package maps pointer movement, down, up, and cancellation into named native input kinds, carrying timestamps, button identity, modifiers, and local position. The bridge maintains pressed-button state for WPE and releases tracked buttons when pointer cancellation ends the interaction.

Wheel input needs a unit and direction conversion. Hera reports steps, while the bridge supplies smooth WPE scroll events in pixels; the current Rust translator negates each axis and multiplies it by 40 pixels per step. Keep that policy shared across both axes when changing the translation so horizontal and vertical scrolling remain consistent.

Native and DOM Focus

A pointer down requests Kit focus for the web view, and its focus-change callback calls WebKit::focus. While that view holds local focus, the browser routes Tab keys directly to the engine so DOM traversal can move among page elements rather than handing every Tab to Kit's native-control traversal.

Surface keyboard ownership remains controlled by Hera. When the host receives a surface focus loss, it dispatches the Kit notification and tells the engine it lost focus. The native bridge releases held keys, clears pressed-button state, and updates WPE focus so stale interaction state does not remain attached to the page.

Keyboard Translation

The public WebKit::input_event path accepts server-translated keyboard events. The Rust translator forwards the evdev key code, modifier bits, and a Unicode value when the text payload contains exactly one Unicode scalar. The native bridge converts the key code to xkb space with an offset of eight and preserves the pressed symbol for its corresponding release.

The bridge currently creates a US xkb map for fallback symbol lookup; server-supplied Unicode handles the single-scalar text path. This combination is not a general text-service or IME integration. Composition, touch, and native clipboard behavior need additional hosting support before applications can rely on them.

Interaction Verification

Translation tests can establish local coordinates, wheel conversion, and key data without opening WPE. Native smoke tests then exercise DOM click delivery against a real engine, and the browser's input probe covers the server-targeted host path. Use these layers together when changing focus or targeting; successful raw event conversion alone does not establish correct control ownership.

Source Reference

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

  • crates/webkit/src/view.rs
  • crates/webkit/src/input.rs
  • crates/webkit/native/input.cpp
  • apps/browser/src/host.rs
  • apps/browser/tests/input-probe.rs