Documentation menu

WebKit Verification and Troubleshooting

Use Rust checks, real-engine smoke tests, and the browser session to isolate failures at their actual boundary.

A WebKit embedding spans pure translation, a dynamically loaded native library, an engine process, and Hera's retained scene connection. Verify those layers separately before drawing conclusions about the full display path. A mock bridge can validate Rust ownership behavior without proving that a deployed engine produces compatible buffers, while a native export test can pass without exercising Hera presentation.

Check Rust Integration

The app-owned build helper can run the browser and package suites in the ARM64 Hera builder:

podman run --rm -v "$PWD":/work hera-builder:latest \
  bash -lc 'cd /work && apps/browser/scripts/build-rust.sh --test'

These suites cover configuration, frame descriptor validation, ABI handling, input translation, host behavior, and the separation of callback completion from buffer release. The helper uses the same SDK configuration as the application build, so cached dependencies and an appropriate target test execution environment are prerequisites.

When changing the tracker, preserve checks that UI-only acknowledgments cannot complete a page frame, mismatched retained outcomes do not consume a pending candidate, and accepted hidden frames can wait without an invented submission acknowledgment.

Exercise a Real Engine

Build native smoke tests against the intended WPE installation and run them where EGL and the WebKit process environment are available:

apps/browser/scripts/build-native.sh -DHERA_WPE_ENABLE_TESTS=ON
LD_LIBRARY_PATH="$HERA_WPE_PREFIX/lib${LD_LIBRARY_PATH:+:$LD_LIBRARY_PATH}" \
  ctest --test-dir target/wpe-native --output-on-failure

CMake registers the normal exporter and a forced-CPU variant. The smoke executable opens a real page, checks exported FD backing, completes callbacks, resizes the viewport, and verifies a DOM click. It also sends scroll and key events and destroys the view with its final exported image still retained.

These tests drive completion and release themselves and do not require a Hera server. Their success establishes native production and lifetime behavior, not server composition or physical display activation. The environment must support the engine's process sandbox; the production launcher keeps that sandbox in use.

Verify the Browser in a Hera Session

Run the browser with its matching bridge and engine, then exercise navigation, page input, native toolbar focus, scrolling, and window resize. Compare the default transport with --cpu, and independently compare normal damage with HERA_WEBKIT_FULL_DAMAGE=1 when investigating stale pixels.

The repository's integration test remains a required gate for cross-boundary changes, but its current RN mount-and-ack check does not validate the WebKit page path. Use the package's checks and a representative browser session in addition to that gate when modifying this integration.

Startup and Loading Failures

An ABI or symbol error points first to the Rust application and libhera-wpe.so pair. A subprocess launch failure points toward the deployed WPE prefix and resources, while EGL initialization points toward render-node access and driver setup. Confirm these prerequisites before diagnosing the Hera image node.

Load failures appear in status and native logs, whereas web-process termination and export failures can end frame production. Treat the recorded terminal error as a session boundary and close the Hera connection before destroying native backing.

Stalled Frames and Stale Content

If production stops after one frame, trace the native frame ID through import, its associated scene commit, retained acceptance, and matching CommitAck. Completing the wrong callback or using acceptance in place of submission breaks pacing. If the page is hidden, retaining one outstanding accepted frame may be expected until the server renders it.

For stale pixels, confirm the actual export transport and compare full damage before changing history rules. For incorrect pointer placement, inspect target-local geometry and input lineage; using surface coordinates can accidentally include native toolbar offsets. The frame guide and input guide explain the required evidence at those boundaries.

Source Reference

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

  • apps/browser/scripts/build-rust.py
  • apps/browser/src/frames.rs
  • apps/browser/src/host/tests.rs
  • crates/webkit/src/ffi/tests.rs
  • crates/webkit/native/tests/smoke.cpp
  • crates/webkit/native/CMakeLists.txt
  • scripts/integration_test.py