[Linux/X11] WebView remains blank until OS window resize due to asynchronous GTK adapter creation after first layout pass

[pardont]

On Linux X11, NativeWebView.OnAttached() creates the GTK adapter asynchronously, after the first layout pass. The adapter never receives the current Bounds, so the X11 child window stays at the default 200×200 size and WebKit renders into a hidden corner.

Workaround: subscribe to AdapterCreated, toggle IsVisible once → triggers TryGetAdapter()?.SizeChanged(Bounds.Size).

Expected: adapter should receive current bounds immediately after creation.

Handler to fix the bug:

public sealed class AvaloniaWebViewSizeFixHandler
    : Avalonia.Controls.Maui.Handlers.WebViewHandler
{
    protected override void ConnectHandler(Control platformView)
    {
        base.ConnectHandler(platformView);
        if (platformView is NativeWebView nwv)
            nwv.AdapterCreated += OnNativeAdapterCreated;
    }

    protected override void DisconnectHandler(Control platformView)
    {
        if (platformView is NativeWebView nwv)
            nwv.AdapterCreated -= OnNativeAdapterCreated;
        base.DisconnectHandler(platformView);
    }

    private static void OnNativeAdapterCreated(object? sender, WebViewAdapterEventArgs e)
    {
        if (sender is not NativeWebView nwv) return;

        // DispatcherPriority.Background: let the in-flight layout / arrange settle first
        // so when we toggle IsVisible the IsVisibleProperty handler reads a fully-laid-out
        // Bounds. Doing it synchronously here would race with the same layout pass that
        // produced the empty Bounds in the first place.
        UIThread.UIThread.Post(() =>
        {
            // If the page already navigated away before this tick fires, toggling
            // IsVisible is a harmless no-op (NativeWebView's property handler still posts
            // a SizeChanged but TryGetAdapter will return null), so no extra guard needed.
            var was = nwv.IsVisible;
            nwv.IsVisible = !was;
            nwv.IsVisible = was;
        }, DispatcherPriority.Background);
    }
}

[drasticactions]

I believe this is a bug in the GTKWebView code in Avalonia.Controls.WebView.

The code we've tested Avalonia.Controls.Maui with is the WpeWebView Implementation I added, which should work in your usecase without this hack. You should try installing wpewebkit in your distro and using that implementation instead.

e. I'm updating the docs for this to make it clear that WPEWebKit is the first and preferred method for using the webview on Linux.

[pardont]

I tested this on Debian 11 and Ubuntu 20.04 devices. On Debian 11, libwpewebkit-1.0-3 is installed. In both environments, the WebView falls back to WebKitGTK.

Is there a version requirement for WPE WebKit? Does it require at least libwpewebkit-2.0-1 to work properly?

[drasticactions]

@pardont Yes, it requires at least libwpewebkit-2.0-1. When I wrote it I was developing it on top of wpewebkit 2.52 so that version and up should work with it. Older 2.x versions should work since AFAIK there are no breaking changes with the bindings for them, at least going back to 2.4x, but older builds most likely won't, and 1.x won't at all.

Arch supports the newest versions out of the box, and the newest versions of the major distributions should have a 2.x build available in some form. For older distros, you would need to compile it yourself.

As for this issue, I'm still thinking about what to do. The root issue is the GTKWebKit in Avalonia.Controls.Webview, your workaround is hacking it to work right, but if you ran it normally in an Avalonia app (as in, not using these handlers, just using the webview itself), it wouldn't work unless you did something similar. So fixing it here with a workaround here would be wrong, but IMO I also would rather not support GTKWebKit at all, since it was never really supported as a NativeWebView for Linux, and NativeControlHost in X11 for Avalonia can be a PITA. The wpewebkit version is texture-backed, and was added so we would have a proper webview for Linux that worked.

Most likely I'm going to migrate this issue to Avalonia.Controls.Webview.

[pardont]

Understood. Our software needs to support both old and new systems. Since the minimum required version libwpewebkit-2.0-1 cannot be installed on older systems, it's unavoidable to use WPE WebKit on newer systems and fall back to WebKitGTK on older ones. We hope this bug can be fixed in the WebKitGTK backend.

[drasticactions]

We hope this bug can be fixed in the WebKitGTK backend

GTKWebKit wasn't supported in NativeWebView in Avalonia.Controls.WebView, only for NativeWebDialog. It technically was set up as the default NativeWebView, but wasn't supported. I, personally, would rather get rid of GTKWebKit support altogether for NativeWebView than have a fallback for something that doesn't work.

I honestly would not hold my breath on it working or working correctly in general. I would encourage you to compile WPEWebKit for the platforms you're using.