* Linux browser: WPE WebKit at the display's rate, frames shared with GPUI as dma-bufs The sidebar browser on Linux ran WebKitGTK in an offscreen window: every frame went through the CPU, over a pipe, into a new GPUI image, so pages topped out near 60 fps whatever the display, and large ones fell well below. Zeron now carries its own WPE WebKit platform (browser/linux/wpe.c) and runs it in the helper when the build and the system have WPE WebKit 2.50+: - WebKit renders on the GPU GPUI draws with, into dma-bufs in a DRM format modifier GPUI's Vulkan device imports. GPUI copies only each frame's damaged regions into the page's atlas tile, on the GPU (zeronsh/zui#18). - Where the driver renders no layout Vulkan imports, the helper reads frames back with OpenGL ES into a sealed memfd. Without a GPU, WebKit renders on the CPU into shared memory. Both update the tile in place. - GPUI's frame callbacks are the pages' vblank: WebKit hears a frame is on screen at most once per display refresh, so pages run at 60, 144 or 240 Hz and never render frames the display won't show. Hidden pages, and pages replaced by their error, get none. - WebKit runs copy, cut and paste itself, sets the pointer's cursor, and sees click counts and the pointer leaving the page. If the WPE helper can't start, the session uses WebKitGTK. Its helper now renders at the output's scale (it rendered 4x the pixels at 1.5x on Wayland and downscaled them) and sends Cairo's surface as-is instead of converting it through GdkPixbuf, which took most of its CPU. A helper that crashes, sends a message Zeron can't read or is still being written by a forked child (ETXTBSY) is stopped, replaced or retried; the tests run the real helper on every render node, in every layout its driver renders, read back and in shared memory, at 60, 144 and 240 Hz. * Linux browser bench: shown frames, pacing, copies, press latency, memory `ZERON_BROWSER_BENCH` measured one page's frame rate and CPU. It now loads a fresh document for each of a 2D canvas, WebGL 2, scrolling, a CSS spinner and, with `ZERON_BROWSER_BENCH_VIDEO`, a 60 fps video, and records for each: the page's frame rate, when GPUI painted every new frame, the bytes copied into the page's tile from CPU memory and between GPU buffers, CPU, PSS and NVIDIA GPU memory for Zeron and for WebKit's processes, and a capture. It then times 40 presses from GPUI's input to the frame showing them, and measures an idle page. `ZERON_BROWSER_BENCH_WIDTH` sizes the browser. The counts are kept only in fixture builds (`browser-fixture`), for both engines, so WebKitGTK and every WPE path are measured the same way. `ZERON_BROWSER_DMABUF=readback` keeps WebKit on the GPU but reads its frames back, the path GPUs that render no importable layout take. * Linux browser bench: WebGL page checks a WebGL 1 context too The WebGL page's benchInfo() clears a WebGL 1 context and reads a pixel back, so a bench run records that both WebGL versions render. * Linux browser: rustfmt the WPE engine and its tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com> * Linux browser: a paste without text clears WPE's clipboard copy The WPE helper kept the last clipboard text Zeron shared, and Zeron shared only text. Pasting with an image or nothing on the system clipboard then inserted that earlier text, possibly into another page. Zeron now shares the clipboard on every paste, and empty text clears the helper's copy. build.rs embeds an empty WPE helper, as when WPE is missing, if wpe.c does not compile against the installed development files (an older GBM), and detects them again when PKG_CONFIG_PATH changes. probe_gpu releases the GBM device and render node it opened when the GPU is unusable. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com> * Linux browser fixture: rustfmt Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com> * Linux browser docs: the WPE vblank check needs a compositor that answers idle frame callbacks Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com> --------- Co-authored-by: Wing <44917547+wingleeio@users.noreply.github.com> Co-authored-by: Claude Opus 5.5 <noreply@anthropic.com> Co-authored-by: zeronsh[bot] <346184242+zeronsh[bot]@users.noreply.github.com>
6.5 KiB
Browser on Linux
Zeron renders the sidebar browser with WPE WebKit when the build includes its helper and the system has its runtime, and with WebKitGTK otherwise. Either engine runs in a helper process that Zeron starts when a page is first opened. The main application links to neither, so other app features remain available if the browser runtime is missing. Both use a persistent website-data context shared by tabs and windows in the same Zeron profile. Persistent cookies, localStorage and IndexedDB survive closing tabs and restarting Zeron. See browser profiles and login persistence for storage locations, profile isolation, and regression tests.
GPUI draws the helper's frames alongside the rest of the app rather than embedding a separate native browser window. Both X11 and Wayland use this path, including clipping, sidebar transitions, tooltips, and frosted overlays.
WPE WebKit
The WPE helper is Zeron's own WPE platform: WebKit renders pages on the GPU GPUI uses, and GPUI shows its frames at the display's refresh rate without copying them through the CPU.
- GPUI's Vulkan device reports the buffer layouts (DRM format modifiers) it can import. WebKit renders into one of those that EGL can also render, and GPUI copies only each frame's damaged regions from the shared dma-buf into its atlas, on the GPU.
- Where no layout suits both, as when the driver can render none that Vulkan imports, the helper reads frames back with OpenGL ES into shared memory. Without a usable GPU, WebKit renders on the CPU into shared memory.
- GPUI's frame callbacks are the pages' vblank. Like a compositor, GPUI tells WebKit a frame is on screen at most once per display refresh, so pages animate at the display's rate, 60 Hz or 240 Hz, and never render frames the display would not show. A hidden page, or one Zeron replaces with its error, gets no vblanks at all.
If the WPE helper cannot start, for instance because its runtime is missing, Zeron uses WebKitGTK for the rest of the session.
The WPE helper needs WPE WebKit 2.50 or later with the WPE Platform API, JSON-GLib, GBM, EGL, OpenGL ES 2 and xkbcommon. On Arch Linux:
sudo pacman -S wpewebkit json-glib mesa libglvnd libxkbcommon
A build embeds the WPE helper when pkg-config finds wpe-webkit-2.0 >= 2.50, wpe-platform-2.0, json-glib-1.0, gbm, egl, glesv2 and xkbcommon. Otherwise it prints a warning and the browser uses WebKitGTK. The release workflows install only the WebKitGTK packages, so release builds currently use WebKitGTK.
WebKitGTK
WebKitGTK requires the distribution's WebKitGTK 4.1 and JSON-GLib runtime packages, including when using a prebuilt Zeron release. The Linux installer does not currently install or validate these dependencies; install them separately before opening a browser tab.
On Ubuntu or Debian:
sudo apt install libwebkit2gtk-4.1-0 libjson-glib-1.0-0
On Fedora:
sudo dnf install webkit2gtk4.1 json-glib
The WebKitGTK helper sends CPU-addressable frames, so animated pages incur frame-copy and texture-upload work.
For development, install the development packages in addition to the normal GPUI build dependencies. These provide the webkit2gtk-4.1 and json-glib-1.0 pkg-config modules used to compile the helper.
On Ubuntu or Debian:
sudo apt install libwebkit2gtk-4.1-dev libjson-glib-dev
On Fedora:
sudo dnf install webkit2gtk4.1-devel json-glib-devel
The build embeds the small helper executables, which are extracted to the user's cache directory when needed. WebKit itself stays system-managed and receives security updates through the distribution.
HTTP(S) links in chat open new Browser tabs in their conversation. If the runtime cannot start, the tab shows the browser error; use Open in external browser from the transcript link's context menu or the Browser toolbar's external-open button. See transcript link interactions and fixtures.
Environment variables
| Variable | Effect |
|---|---|
ZERON_BROWSER_ENGINE=wpe or gtk |
Use that engine, without falling back to the other. |
ZERON_BROWSER_DMABUF=0 |
WPE WebKit renders on the CPU into shared memory. |
ZERON_BROWSER_DMABUF=readback |
WPE WebKit renders on the GPU, and the helper reads its frames back into shared memory. |
ZERON_WPE=0 |
At build time, leave the WPE helper out. |
ZERON_WPE_HELPER=<path> |
Debug builds run this WPE helper instead of the embedded one. |
Tests and benchmarks
The end-to-end tests run the real WPE helper, so they need its runtime:
cargo test -p zeron-ui --lib browser::linux -- --include-ignored --test-threads=1
They render pages on every render node in every layout its driver renders, read back and in shared memory, and check that pages follow vblanks at 60, 144 and 240 Hz however often GPUI paints. ZERON_TEST_RENDER_NODE=/dev/dri/renderD128 picks the GPU for the tests that take one; without it they use the first render node that renders, or shared memory when none does.
The browser fixture drives the whole app on a desktop session. It needs an unlocked session with keyboard focus for its clipboard checks, or ZERON_BROWSER_FIXTURE_UNFOCUSED=1 to skip them. On Wayland, ZERON_BROWSER_CAPTURE_COMMAND names a program that captures the fixture's window into the PNG path it is given:
cargo build -p zeron-ui --example browser-fixture --features browser-fixture
ZERON_BROWSER_ENGINE=wpe ZERON_BROWSER_CAPTURE_COMMAND=./capture.sh \
target/debug/examples/browser-fixture /tmp/browser-fixture
It checks input, clipboard, menus, resizes and captures, and fails if an animating page falls behind the display (WebKitGTK: behind 60 Hz), stops getting vblanks once shown again, or WebKit keeps more than six buffers for one page. On Wayland, GPUI's frames, and so the page's vblanks, wait for the compositor's frame callbacks; the nested weston that scripts/test-linux-browser.sh runs answers none for a commit without damage, so its WPE run fails the vblank check, while cage (wlroots) passes it. ZERON_BROWSER_BENCH=<seconds> instead measures pages that repaint their whole viewport every frame (a 2D canvas, WebGL 2, scrolling) or a small part of it (a CSS spinner), a 60 fps video when ZERON_BROWSER_BENCH_VIDEO names an MP4, how long a press takes to reach a painted frame, and an idle page. It writes to bench.json the page's frame rate, when GPUI painted each frame, the bytes copied to show them, and the CPU, memory and NVIDIA GPU memory Zeron and WebKit use. ZERON_BROWSER_BENCH_WIDTH sets the browser's width in logical pixels.