Writing a WebKit Host
Coordinate GLib, Hera Kit, and one Hera connection so page imports and scene publication share the same resource namespace.
The supplied browser uses a custom host because WebKit frame production adds transport responsibilities beyond ordinary view evaluation. Its event loop owns the engine, the Kit UI loop, and the scene connection on one thread, allowing native calls and resource bookkeeping to follow the same ordered lifecycle.
Start from apps/browser/src/host.rs when implementing a comparable embedding. The public WebView primitive composes with Kit, but it cannot import buffers into an independently owned AppHost connection or decide which server acknowledgment belongs to a native frame.
Session and UI Initialization
The host completes the Hera hello and surface exchange before constructing its WebKit instance. It derives the page viewport from the initial surface proposal, then creates bindings for the current page image, status, and address. The resulting AppCore uses a reconciler namespace derived from that surface ID, keeping scene-node identity associated with the connection's surface.
After dispatching UiCommand::SurfaceCreated, the host can evaluate the native toolbar and web view through UiLoop. All WebKit references and callbacks remain on this thread. An asynchronous runtime handles socket waiting without moving the UI model or GLib context onto another worker.
Event Pump and Transport Progress
The browser uses a skipped-tick interval to call WebKit::iterate regularly while a select! also receives server messages and shutdown. Pumping gives the engine a chance to produce frames and change load state; reading the socket allows retained outcomes and releases to unblock the next stage.
Status and URI changes update the native model only when their values change. This avoids requesting a Kit evaluation merely because the host checked the engine's state again. After either a pump or message dispatch, the host attempts any eligible pending UI render.
Image Import Ordering
When frame bookkeeping permits another import, the host takes one native Frame, allocates a fresh buffer ID, and determines whether predecessor-relative damage is usable. It then sends ImportFrameBuffer with that descriptor and the frame's FD on the same connection that will carry the scene commit.
Only a successful write registers the import in local bookkeeping. The host can then update the image binding and let Kit produce a diff that references the new buffer. An ID imported on another connection has a different namespace and cannot be substituted into this scene.
Outcome Dispatch
CommitAccepted resolves the matching Kit candidate and advances the host's confirmed input lineage. If it replaced a page image, the host requests release of the old buffer without freeing the old native image yet. A matching CommitAck later completes the callback for the page frame associated with that commit, while BufferReleased independently permits native backing release.
The host allows one retained candidate at a time. Once that candidate is accepted, native UI changes may still produce commits while the page frame awaits its submission acknowledgment. Such toolbar-only commits must not accidentally complete the outstanding WebKit frame; frame ownership explains the separate maps used for that correlation.
Page and Native Layout Resizing
On an authoritative SurfaceChanged, derive the available page dimensions after subtracting native chrome. The browser clamps each dimension to at least one pixel and rejects viewports beyond its 8192-pixel limit, then resizes WebKit, updates the image's intended extent, and dispatches the new surface size to Kit.
The previous page image can remain visible during this transition. Retaining its backing until release lets Hera temporarily scale that content rather than requiring a blank region while WebKit renders the new viewport.
Connection and Backing Teardown
A rejected browser scene, terminal frame error, or generic transport error ends the current host session. On every exit path, the browser explicitly drops the Hera connection before dropping the host and its native view. This order prevents the producer from recycling backing while the server still treats the connection's imports as valid.
The browser bounds startup and writes and gives a pending retained outcome ten seconds to arrive. It deliberately does not impose that same deadline after acceptance: an occluded page can wait for rendering without losing its retained image or receiving a fabricated callback completion.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
apps/browser/src/host.rsapps/browser/src/transport.rsapps/browser/src/frames.rscrates/kit/src/threading/mod.rs