libaura-webview: Web pages in AURA

libs/aura-webview provides the AURA element WebView: a full Chromium page in the scene graph, using the Chromium Embedded Framework (CEF). The page supports touch interaction and communicates with C++ code through a WebChannel. Custom JavaScript can be injected into any page.

WebView {
    id: page
    url: "https://example.org"
    script: "document.addEventListener('DOMContentLoaded', () => { ... })"
    size: parent.width - 48, parent.height - 104
}

Example and tests: tests/ui-webview/webview.aura and tests/test_webview.cpp.

Building

• Download: Without AURA_CEF_ROOT, the build downloads the “minimal” distribution from Spotify's CDN (cef-builds.spotifycdn.com): approximately 330 MB (x86_64) or 430 MB (arm64). SHA1 checksums are in cmake/Cef.cmake.
• Cache: For development, download and unpack it once, for example under ~/.cache/aura/cef/, then use -DAURA_CEF_ROOT=~/.cache/aura/cef/cef_binary_<version>_<platform>_minimal.
• Wrapper: The build compiles libcef_dll_wrapper (the C++ API over libcef.so's C API) from the distribution's sources, using our compiler.
• Runtime directory: build/<preset>/cef/ contains symlinks to libcef.so and the resources (*.pak, icudtl.dat, v8_context_snapshot.bin, locales/), plus the aura-webview-helper executable. Programs locate libcef.so through their rpath; the directory can be overridden at runtime with AURA_WEBVIEW_DIR.

Architecture

• Rendering: CEF renders off-screen in software (ozone-platform=headless, without GPU) into a BGRA buffer. The node draws it as a Skia image, with open dropdowns (<select>) above it. No X11 or Wayland server is required, which suits a kiosk using KMS/DRM.
• Threads: CEF runs its own message loop (multi_threaded_message_loop). A new image wakes the application (Application::wakeUp), and aura-view detects it through frameCount().
• Startup: CEF starts with the first WebView; the browser starts on its first draw, when the node knows its size. A WebView that is never displayed costs nothing.
• Input: Press, drag, and release are forwarded to the page as touch events. Chromium turns them into taps and inertial scrolling. Links with target=_blank open in the same view.
• Cache: Each process has its own /tmp/aura-webview-<pid> directory (with cef.log), removed by shutdown(). Cookies and data do not survive a restart.

WebChannel and scripts

Every page has window.aura before its own scripts run.

const sum = await aura.call("add", 2, 3);   // JavaScript -> C++, Promise
aura.on("cart", (value) => render(value));  // C++ -> JavaScript

#include "aura/webview/webview.h"

dialog->page->handle("add", [](const auto& args) {
	return AuraJson(args[0].toInt() + args[1].toInt());
});
dialog->page->emit("cart", {{"items", 3}});
dialog->page->runJavaScript("document.body.style.zoom = 1.2");
dialog->page->addUserScript("window.kiosk = true;");

• Values: JSON (AuraJson). Arguments to aura.call arrive as an array.
• Handlers: They run on the UI thread and may access the scene graph and application state. An exception rejects the Promise with its message; an unknown name does the same.
• emit, runJavaScript: Apply to the currently loaded page; otherwise they do nothing.
• Scripts: addUserScript() and AURA's script: run in every new document in the view, in the main frame, before the page's own scripts. Adding a script or changing script also executes it immediately in the current page. An error goes to the page's console and does not prevent the other scripts from running.
• Transport: CEF's message router (auraQuery) for calls, ExecuteJavaScript for events, and process messages for script lists.

Application integration

int main(int argc, char** argv)
{
	// Before building the first UI: register WebView for the loader;
	// locale: Chromium language (default en-US)
	aura::webview::setup(argc, argv, {.locale = "de"});
	...
	aura::webview::shutdown();  // closes all browsers and stops CEF
}

aura-view initializes CEF when built with WebView (aura::webview then defines the preprocessor symbol AURA_WITH_WEBVIEW). Without the library, the loader reports “element type 'WebView' is not part of this program” and uses the compiled version. A file containing WebView can only be compiled if the program links aura::webview.

Preview (aura-view, VS Code)

• Built with WebView: aura-view displays WebViews in its window, with --render, and in the server.
• --render: Waits until the page has not repainted for 1.5 s (at most 20 s).
• Server: While a WebView is open, it reports animating, and the extension requests an image approximately every 33 ms. A response only contains a PNG if Chromium has repainted.
• Interaction: A click is a tap. Dragging with the mouse button pressed scrolls; the move command was added for this. Pausing playback in the preview also pauses the page.
• Setting: The preview's aura-view (aura.preview.command) must be built with WebView.

Tests

aura_webview_tests (tests/test_webview.cpp, tests/ui-webview/webview.aura) builds a dialog containing a WebView once through compiled code and once through the loader. It loads a data: page without network access and checks:

• The result of aura.call,
• Errors and unknown handlers,
• The script defined in AURA,
• emit and runJavaScript,
• The page's pixels in the node.

Runtime and integration

• The target system needs the system libraries required by the selected CEF distribution, along with its resources and locales.
• The integration currently starts CEF with no_sandbox. Account for that when selecting and embedding web content.
• Touch interaction is forwarded to Chromium; validate keyboard, IME and scaling requirements for the particular application.
• The CEF distribution contains Chromium and other third-party components. Their license notices belong with the distribution; see Dependencies & licenses.