Skip to content

Web views over WPE WebKit - #2

Merged
colemancda merged 19 commits into
masterfrom
feature/webview
Nov 16, 2026
Merged

colemancda merged 19 commits into
masterfrom
feature/webview

Conversation

@colemancda

Copy link
Copy Markdown
Member

Implements AppRuntime's web view contracts (WebContent, WebContentDelegate; WebKit.md) on Linux with WPE WebKit, and draws WebView nodes in the player. It follows Perry's approach (Sources/PerryUIKit/WPE.swift).

ExampleWeb on Linux

Debian 13

Ubuntu 26.04 doesn't package WPE WebKit; Debian 13 has 2.48. The dev image and CI move to swift:6.4.2-trixie:

  • Debian's SDL is 3.2 and PureSwift/SDL needs 3.4, so Scripts/build-sdl3.sh builds SDL 3.4.20 from source (offscreen driver only) for both.
  • WPE is installed as runtime packages only (libwpewebkit-2.0-1, libwpebackend-fdo-1.0-1, libwayland-server0), since the host loads it at run time.
  • WebKit's bubblewrap sandbox can't make namespaces in a container, so the image's runs and CI set WEBKIT_DISABLE_SANDBOX_THIS_IS_DANGEROUS=1. The host itself leaves the sandbox on.
  • A .dockerignore keeps the build context down to the SDL script.

How

  • LinuxWebKit, a new host module.
    • It dlopens libwpe, WPEBackend-fdo, libwayland-server, WPE WebKit, GLib and GObject locally (RTLD_LOCAL); the host links no WebKit. Without WPE, a page fails each load saying so.
    • WPEBackend-fdo runs in its SHM mode, so every frame arrives as a wl_shm buffer. Each is turned from premultiplied BGRA to RGBA for Cacao's Image(pixels:). There's no GL.
    • GLib's main context runs on the main loop every 8 ms while there are pages.
  • The contract on WebKitWebView.
    • Signals: load-changed, load-failed, load-failed-with-tls-errors, decide-policy, and notify::uri|title|estimated-load-progress.
    • The URL is reported only once a navigation commits or follows a redirect, because WebKit's uri changes as soon as a load is asked for.
    • Cancelled or replaced navigations aren't failures.
    • GErrors map to WebError.Code.
    • shouldNavigate is asked for every navigation and new window except the guest's own loads. New windows load in the same page.
    • loadResource stays inside the bundle's resources/.
    • Scripts' results come back as JSON via jsc_value_to_json.
  • Without network. Remote loads and remote navigations fail with notPermitted, and everything else goes through a proxy on a .invalid host, so remote subresources can't load.
  • The view (Sources/LinuxUI/HostWebView.swift):
    • It gives the page its size in points and the display scale, and makes it visible while on screen.
    • Drag is the primary button, and hover moves the pointer.
    • Click focuses the page. Keys go to the page as XKB keysyms, which WPE turns into text.
    • HostNodeViews moves to its own file and gains the WebView case.
  • The packager knows the contracts, and treats network as a capability this host serves.

Not yet

  • Wheel scrolling. Cacao sends the wheel only to its own scroll views. Pages scroll with the keyboard.
  • alert, confirm and prompt. WebKit's defaults apply, which show nothing.
  • Permission requests are left to WebKit's defaults, which deny them.
  • Touches, and buttons other than the primary.
  • Main-frame flag. WPE doesn't say which frame a navigation is in, so isMainFrame is always true.
  • Running inside a launcher sandbox. This is the open question WebKit.md names.

Tested

On Debian 13 in Docker, all suites pass:

  • LinuxWebKitTests, 13 tests in WPE:

    • loading HTML and the order of events;
    • scripts' JSON results, undefined, and exceptions;
    • navigations asked about, refused and allowed, then back;
    • bundle resources, including a missing one;
    • a refused connection, and remote loads without network;
    • a frame's pixels, a click, typing with Enter, and a resize;
    • error mapping, schemes, and libwpe's struct layouts.

    All WebKit calls run on one thread, which WebKit takes as its main thread.

  • The other suites: LinuxUI 43 (1 skipped, as before), Packager 21, Graphics 10, Host 12, Bluetooth 12.

End to end: AppRuntime's ExampleWeb was built as a linux-arm64 slice with network and run in linux-app-host with CACAO_SCREENSHOT_DELAY=10. That's the screenshot above: swift.org with the redirect followed, and the page title under it. A delayed screenshot of a page that had stopped changing never came, so I pushed a fix straight to Cacao's develop (PureSwift/Cacao@ebcd57b): Cacao now draws a frame once the delay has passed.

@colemancda
colemancda merged commit 976ffad into master Nov 16, 2026
2 checks passed
@colemancda
colemancda deleted the feature/webview branch November 16, 2026 20:12
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant