WebKit Internals
Follow a page from its WPE platform callbacks through validated exports and into Hera’s retained image lifecycle.
The embedding separates web-engine behavior from application hosting and server presentation. WPE produces page content through the native platform adapter, the Rust crate validates and exposes that content, and the browser host connects it to the scene protocol. Keeping these boundaries explicit makes it possible to change one layer without silently taking over another layer's resource ownership.
Content Pipeline
A WebKit handle owns the native view on its GLib thread. The custom WPE view receives produced buffers through render_buffer, then the exporter either shares compatible DMA-BUF backing or creates a sealed CPU snapshot. After Rust validates the export, the host imports it on the scene connection and updates Kit's image binding.
That image becomes part of an ordinary retained scene, where Hera controls final composition and presentation. Completion feedback then travels in the reverse direction: a matching submission acknowledgment completes the producer callback, and a buffer-release notification eventually retires the held WPE image. Neither message can replace the other.
Implementation Guides
The platform adapter explains how the custom display, view, and toplevel use headless EGL infrastructure while Hera owns the visible window. Frame export and damage follows producer readiness, transport selection, immutable snapshots, and predecessor-relative rectangles. The native ABI explains dynamic loading, thread confinement, descriptor transfer, and teardown.
For the corresponding application policy, use custom hosting and frame ownership and pacing. Those guides explain which responsibilities belong in the host rather than in the reusable bridge.
Rust Responsibilities
Within crates/webkit/src, lib.rs defines the public engine handle and commands. view.rs adapts an image binding into a Kit primitive with focus and input handlers, while input.rs performs pure event translation. frame.rs converts the native descriptor into protocol metadata and checks its supported layout.
All dynamic symbols and unsafe native calls remain in ffi.rs. Its owning handle keeps the library and native view alive, copies returned strings, takes ownership of transferred FDs, and records terminal frame failures. Application code reaches those operations through the safe public handle rather than duplicating C declarations.
Native Bridge and Host Responsibilities
The native bridge divides startup and C entry points into hera_wpe.cpp, custom WPE objects into platform.cpp, buffer export into frames.cpp, and xkb/WPE event delivery into input.cpp. browser.h supplies their shared owning state, and hera_wpe.h defines the private ABI shared with Rust.
The application adds another distinct layer under apps/browser/src. Its transport module owns handshake and imports, its frame tracker correlates retained outcomes and releases, and host.rs pumps GLib while dispatching messages and UI work. The native toolbar and address model live in the UI code, keeping browser policy out of the package's platform bridge.
Extension Boundaries
A new feature should identify both the engine capability and the host responsibility it requires. For example, adding a new page interaction may need input translation and accepted-target handling, while a new export format needs validation, backing ownership, and server import support. Verify those crossings with the layered checks instead of assuming a native callback alone completes the integration.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
crates/webkit/src/lib.rscrates/webkit/src/ffi.rscrates/webkit/native/browser.hcrates/webkit/native/hera_wpe.happs/browser/src/host.rs