Documentation menu

Using the WebKit Package

Create a thread-owned engine handle, drive its event context, and connect its exported content to your application host.

The package has a small public API because it leaves transport policy to the embedding application. WebKit owns a native view, Frame represents one exported image ready for import, and WebView connects an image binding to Hera Kit layout and input. Understanding how these types cooperate is more useful than treating any one of them as a self-contained browser widget.

Package Dependency

For an application located at apps/example, add the package and the toolkit relative to that application's manifest:

[dependencies]
hera-kit = { path = "../../crates/kit" }
hera-webkit = { path = "../../crates/webkit" }

Cargo names the package hera-webkit, while Rust imports it as hera_webkit. The crate loads its native bridge dynamically, so applications can compile against the Rust API without linking WPE at Rust build time. A compatible bridge and engine are still required when the application opens a view.

View Creation and Thread Ownership

Create the handle on the thread that will also pump GLib, call the native API, and evaluate the associated UI. WebKit::open returns an Rc<WebKit>, allowing controls and the WebView to share the same thread-owned instance.

use hera_webkit::WebKit;
use std::{path::Path, rc::Rc};

fn open_page(bridge: &Path) -> Result<Rc<WebKit>, Box<dyn std::error::Error>> {
    WebKit::open(bridge, 1000, 700, "https://example.com")
}

The dimensions describe the page viewport, which should exclude any native toolbar. The bridge path identifies trusted native application code built for the deployment's ABI. Keep the returned handle on its creating thread; it cannot be sent or shared across threads through Send or Sync.

Engine Event Processing

Call iterate() regularly from the owning event loop to let GLib process load events, input, and frame production. The current native implementation drains at most 16 pending context iterations per call without blocking. The browser host schedules these calls on a four-millisecond interval while continuing to read Hera messages; this is its pumping policy, not a promise of a particular rendering rate.

After pumping, take_frame() returns Ok(None) if no image is ready or Ok(Some(frame)) with an owned descriptor and backing FD. A frame becomes visible only after your host imports it into the same Hera connection used for the scene, updates its image binding, and submits the resulting scene diff. Follow custom hosting for that sequence rather than dropping the FD into an unrelated AppHost connection.

Navigation commands share the existing view and its retained integration. The following helper validates the URI's C-string representation before asking the engine to navigate:

use hera_webkit::WebKit;

fn visit(webkit: &WebKit, uri: &str) -> Result<(), std::ffi::NulError> {
    webkit.navigate(uri)?;
    Ok(())
}

A successful navigate call means the command was delivered to the native view, not that loading finished. Continue pumping and read status(), uri(), and title() to reflect the engine's current state. back(), forward(), reload(), and stop() use the same handle; back and forward only act when the corresponding history entry is available.

The package accepts explicit URIs. The browser application's convenience rule that adds https:// to an address without a scheme belongs to its configuration and toolbar code, so another embedding should choose its own address handling deliberately.

Terminal Frame Errors

A native export or frame-validation failure makes take_frame() terminal for that view. Subsequent calls return the recorded error, which is also available through frame_error(). The host must stop using the failed view and close its Hera connection before dropping native backing, because earlier imports may still be referenced by the server.

Ordinary load failures are reported through engine status and should be distinguished from this terminal frame path. See frame ownership for the teardown order and deployment for runtime prerequisites.

Source Reference

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

  • crates/webkit/src/lib.rs
  • crates/webkit/src/ffi.rs
  • crates/webkit/src/frame.rs
  • apps/browser/src/host.rs
  • apps/browser/src/config.rs