Frame Ownership and Pacing
Keep retained acceptance, WebKit callback completion, and exported-buffer retirement separate throughout the host lifecycle.
A WebKit frame has two consumers with different completion rules. Hera needs the exported pixels to remain valid while its retained scene can reference them, and WebKit needs feedback before it produces the next frame. The browser host connects those rules through explicit identifiers rather than treating a local binding update as permission to recycle the image.
- Export
Retain the WPE buffer and transfer a ready backing FD.
Frame - Publish
Import on the scene connection and accept its image reference.
CommitAccepted - Complete callback
Match the page commit's submission acknowledgment.
CommitAck - Retire backing
Release a replaced native image after server retirement.
BufferReleased
Frame Export and Import
The native bridge assigns a monotonically increasing frame ID and retains the corresponding WPE buffer when it exports an image. take_frame() transfers an owned FD and validated BufferDescriptor to Rust, but the bridge continues to hold the native image independently of that FD.
The host assigns a separate connection-local BufferId and imports the complete image through ImportFrameBuffer. It records the mapping from that buffer ID to the native frame ID only after the import write succeeds. This map remains necessary even after the FD itself is closed, because a later release message names the Hera buffer rather than the native frame.
Scene Reference Publication
The image binding introduces the imported ID into Kit's candidate scene. The host records which nonempty commit carries a new page frame and waits for its matching retained outcome before submitting another candidate.
When acceptance arrives, the host promotes the Kit tree and records the commit-to-frame association awaiting submission acknowledgment. If the candidate replaced an older image, it can now request ReleaseBuffer for that older buffer, since the accepted scene no longer uses that reference. The request starts retirement; it does not authorize immediate native release.
Producer Callback Completion
The host calls WebKit::frame_complete(frame_id) only after CommitAck arrives for the commit associated with that page frame. The bridge then reports the WPE buffer as rendered and permits further production. Completing the callback on local publication or retained acceptance would allow the producer to advance before the host has the required submission evidence.
Despite the method's name, this is not proof that Hera's GPU work has completed or that the display activated the page. CommitAck retains its GPU-submission meaning, and physical presentation follows its separate server lifecycle.
The host blocks another page import until the outstanding page-frame acknowledgment has been matched. It can still submit toolbar-only updates after retained acceptance, because their acknowledgment does not participate in that page-frame callback.
Backing Storage Retirement
When Hera sends BufferReleased, the host resolves its buffer-to-frame map and calls WebKit::release_frame(frame_id). The bridge then notifies WPE that the buffer is released and drops its retained reference. The same ownership rule applies to CPU snapshots as to DMA-BUF exports.
Keeping callback completion separate from backing release is essential: permission to produce the next frame does not make the current frame's storage reusable. A page that remains in the retained scene may keep its last image alive long after its callback completed.
Ownership During Frame Stalls
A pending retained candidate has an outcome deadline, since the host cannot safely keep building dependent updates without knowing its baseline. Once accepted, the host can retain one outstanding page frame indefinitely if the surface is hidden and has not reached rendering. It must not simulate an acknowledgment simply to restart production.
For terminal failures, close the Hera connection before destroying the native view. The custom host guide shows where this order is enforced, while export internals explains the WPE buffer references behind it.
Source Reference
The following files in the Hera checkout define the behavior described on this page.
apps/browser/src/frames.rsapps/browser/src/host.rscrates/webkit/src/lib.rscrates/webkit/native/hera_wpe.cppcrates/webkit/native/frames.cpp