Fix Linux WebView first-paint and Wayland-session GTK init (#5)

Two related fixes for the same broken-on-Linux symptom — both contained
inside the package, both no-op on platforms that already work.

1. Layout participation for the inner NativeControlHost

NativeWebView is a Control (not a NativeControlHost) that adds its
inner NativeWebViewControlHost to VisualChildren after async adapter
creation. In Avalonia, adding to VisualChildren puts a control in the
visual tree but does NOT make it a layout participant — the parent
must explicitly Measure/Arrange visual children from
MeasureOverride/ArrangeOverride.

NativeWebView previously did neither, so the inner NativeControlHost's
Bounds stayed default(Rect) and the cross-platform NativeControlHost
flow's `if (bounds.Width == 0 && bounds.Height == 0) return false`
guard in TryUpdateNativeControlPosition silently skipped the call to
ShowInBounds. On Win32/macOS this is invisible because their holder
windows are visible-by-default; on X11 the holder stays 1×1 IsUnMapped,
the reparented WebKit GTK toplevel is IsUnviewable, and navigation
completes ok=True with zero pixels visible.

xwininfo on the broken case:

    Avalonia toplevel       (window size)  IsViewable
      Native-host slot      1×1            IsUnMapped       <-- bug
        Reparented GTK      200×200        IsUnviewable     <-- bug

Fix:

  - NativeWebView.MeasureOverride now drives Measure() on each
    Layoutable in VisualChildren with the size it returns.
  - A new NativeWebView.ArrangeOverride drives Arrange() on each
    Layoutable in VisualChildren to the final size.
  - InvalidateMeasure() is called immediately after
    VisualChildren.Add((Control)controlHostImpl) so the layout pass
    actually re-runs for the freshly-added child (VisualChildren.Add
    does not itself invalidate layout).

The bug was reproduced in a standalone Avalonia Sandbox without
WebView — a plain Control adding a NativeControlHost to VisualChildren
without measure/arrange, which produces the same 1×1 IsUnMapped slot
xwininfo signature. The Measure/Arrange + InvalidateMeasure shape was
verified to fix the symptom there before being applied here. xwininfo
on the Avalonia.Controls.WebView.Samples.Desktop app with this fix:
slot is the parent's bounds, IsViewable, GTK toplevel matches.

WPF code paths (Avalonia.Xpf.Controls.WebView) are unchanged — every
addition is gated behind #if AVALONIA. Verified to compile clean for
net8.0-windows / net10.0-windows.

2. Override GDK_BACKEND=x11 around GTK init

Both GtkX11WebViewAdapter and GtkOffscreenAvaloniaWebViewAdapter use
Avalonia's GTK bridge (Avalonia.X11.NativeDialogs.Gtk.StartGtk) to
initialize GTK, and both rely on X11/GDK-X11-only entry points. Under a
Wayland session the desktop typically pre-sets GDK_BACKEND=wayland, so
the bridge's gtk_init picks the Wayland backend and fails with "Unable
to initialize GTK". Consumers previously had to set GDK_BACKEND=x11 in
the shell before launching.

Add a shared helper AvaloniaGtk.EnsureX11GdkBackendForGtkInit() that
overrides GDK_BACKEND for the duration of the bridge call, then
restores the previous value. Used via `using var _ = ...` at the top
of each adapter's CreateBuilder so the override is visible at the call
site and tightly scoped to GTK init.

Notes:

- Only overrides the unset case and the implicit "wayland" case (the
  default under a Wayland session). If the user has explicitly set
  some other backend like "broadway", that's a deliberate choice in
  conflict with loading an X11-only adapter and we let gtk_init fail
  with its own error rather than silently override.

- Concurrent CreateBuilder calls share a single override window via
  refcounting: first call captures the previous env value and applies
  the override, subsequent overlapping calls only refcount, and the
  override is restored when the last scope is disposed. Without
  refcounting, two concurrent calls could each snapshot the other's
  already-overridden value and leave the env stuck at "x11".

- Environment.SetEnvironmentVariable is not sufficient on Linux: it
  updates the .NET managed env cache but does not propagate to libc's
  environ, which is what gtk_init reads via getenv. A direct libc
  setenv call is required (verified empirically — setting only the
  managed value left gtk_init still failing despite the C# side
  reading "x11"). gdk_set_allowed_backends was tried first as the
  GTK-blessed alternative but the call returned cleanly without
  constraining Avalonia's GTK init helper in practice.

Verified on KDE Neon 24.04 (Plasma 5 / X11) and Arch Linux + KDE
Plasma 6 (Wayland session, XWayland for X11) using a minimal Avalonia
12 standalone repro app: stock 12.0.0 paints blank with the slot/GTK
state above, with this PR paints first-show without any consumer-side
GDK_BACKEND=x11 in the environment.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: christopherthompson81

src/Avalonia.Controls.WebView.Core/Gtk/AvaloniaGtk.cs

@@ -6,12 +6,13 @@
 using System.Runtime.CompilerServices;
 using System.Runtime.InteropServices;
 using System.Runtime.Versioning;
+using System.Threading;
 using System.Threading.Tasks;
 using Avalonia.Logging;
 
 namespace Avalonia.Controls.Gtk;
 
-internal static class AvaloniaGtk
+internal static partial class AvaloniaGtk
 {
     static AvaloniaGtk()
     {
@@ -63,6 +64,105 @@ static AvaloniaGtk()
 
     public static bool HasSoup3 { get; }
 
+    /// <summary>
+    /// Ensures GDK_BACKEND=x11 is in effect for the duration of the bridge call that
+    /// initializes GTK in Avalonia.X11.NativeDialogs.Gtk. The X11 GTK adapters in this
+    /// package use X11/GDK-X11-only entry points and require the X11 GDK backend; under
+    /// a Wayland session GDK_BACKEND is typically pre-set to "wayland" by the desktop,
+    /// which would otherwise cause `gtk_init` to fail with "Unable to initialize GTK".
+    /// </summary>
+    /// <remarks>
+    /// Only overrides the unset case and the implicit "wayland" case (the default under
+    /// a Wayland session). If the user has explicitly set some other backend like
+    /// "broadway", that's a deliberate choice in conflict with loading an X11-only
+    /// adapter, and we let `gtk_init` fail with its own error rather than silently
+    /// override.
+    ///
+    /// `Environment.SetEnvironmentVariable` alone is insufficient on Linux — it updates
+    /// the .NET managed env cache but does not propagate to libc's environ, which is
+    /// what `gtk_init` reads via `getenv`. A direct libc `setenv` call is required.
+    ///
+    /// The returned IDisposable restores the previous env value on Dispose. By that
+    /// point GTK has already locked in its backend choice for the process, so restoring
+    /// the env doesn't switch backends — it just keeps the rest of the process's env
+    /// state clean for any unrelated code that reads GDK_BACKEND.
+    ///
+    /// Concurrent calls share a single override window via refcounting: the first call
+    /// captures the previous env value and applies the override, subsequent overlapping
+    /// calls only refcount, and the override is restored when the last scope is
+    /// disposed. Without refcounting, two concurrent CreateBuilder calls could each
+    /// snapshot the other's already-overridden value and leave the env stuck at "x11"
+    /// after both restore.
+    /// </remarks>
+    public static IDisposable EnsureX11GdkBackendForGtkInit()
+    {
+        if (!OperatingSystem.IsLinux())
+            return EmptyScope.Instance;
+
+        lock (s_overrideLock)
+        {
+            if (s_overrideCount == 0)
+            {
+                var current = Environment.GetEnvironmentVariable("GDK_BACKEND");
+                if (string.Equals(current, "x11", StringComparison.Ordinal))
+                    return EmptyScope.Instance;
+                if (current is { Length: > 0 } && !string.Equals(current, "wayland", StringComparison.Ordinal))
+                    return EmptyScope.Instance;
+
+                try { setenv("GDK_BACKEND", "x11", 1); }
+                catch (DllNotFoundException) { return EmptyScope.Instance; }
+                catch (EntryPointNotFoundException) { return EmptyScope.Instance; }
+                Environment.SetEnvironmentVariable("GDK_BACKEND", "x11");
+                s_savedBackend = current;
+            }
+            s_overrideCount++;
+        }
+        return new RestoreGdkBackendScope();
+    }
+
+    private static readonly object s_overrideLock = new();
+    private static int s_overrideCount;
+    private static string? s_savedBackend;
+
+    [LibraryImport("libc", EntryPoint = "setenv", StringMarshalling = StringMarshalling.Utf8)]
+    private static partial int setenv(string name, string value, int overwrite);
+
+    [LibraryImport("libc", EntryPoint = "unsetenv", StringMarshalling = StringMarshalling.Utf8)]
+    private static partial int unsetenv(string name);
+
+    private sealed class EmptyScope : IDisposable
+    {
+        public static readonly EmptyScope Instance = new();
+        public void Dispose() { }
+    }
+
+    private sealed class RestoreGdkBackendScope : IDisposable
+    {
+        private int _disposed;
+        public void Dispose()
+        {
+            if (Interlocked.Exchange(ref _disposed, 1) != 0)
+                return;
+            lock (s_overrideLock)
+            {
+                if (--s_overrideCount > 0)
+                    return;
+                var previous = s_savedBackend;
+                s_savedBackend = null;
+                try
+                {
+                    if (previous is null)
+                        unsetenv("GDK_BACKEND");
+                    else
+                        setenv("GDK_BACKEND", previous, 1);
+                }
+                catch (DllNotFoundException) { }
+                catch (EntryPointNotFoundException) { }
+                Environment.SetEnvironmentVariable("GDK_BACKEND", previous);
+            }
+        }
+    }
+
     public static Version? TryGetVersion()
     {
         try

src/Avalonia.Controls.WebView.Core/Gtk/GtkOffscreenAvaloniaWebViewAdapter.cs

@@ -34,6 +34,7 @@ private GtkOffscreenAvaloniaWebViewAdapter(GtkWebViewEnvironmentRequestedEventAr
     public static async Task<WebViewAdapter.OffscreenWebViewAdapterBuilder> CreateBuilder(
         GtkWebViewEnvironmentRequestedEventArgs environmentArgs)
     {
+        using var _ = EnsureX11GdkBackendForGtkInit();
         var adapter = await RunOnGlibThreadAsync(() => new GtkOffscreenAvaloniaWebViewAdapter(environmentArgs));
         return (parent) =>
         {

src/Avalonia.Controls.WebView.Core/Gtk/GtkX11WebViewAdapter.cs

@@ -28,6 +28,7 @@ private GtkX11WebViewAdapter(GtkWebViewEnvironmentRequestedEventArgs environment
     public static async Task<WebViewAdapter.NativeWebViewAdapterBuilder> CreateBuilder(
         GtkWebViewEnvironmentRequestedEventArgs environmentArgs)
     {
+        using var _ = EnsureX11GdkBackendForGtkInit();
         var adapter = await RunOnGlibThreadAsync(() => new GtkX11WebViewAdapter(environmentArgs));
         return (parent, _) =>
         {

src/Avalonia.Controls.WebView/NativeWebView.cs

@@ -466,6 +466,12 @@ private async void OnAttached()
 
 #if AVALONIA
             VisualChildren.Add((Control)controlHostImpl);
+            // VisualChildren.Add doesn't itself invalidate layout. Without an explicit
+            // invalidation here, MeasureOverride/ArrangeOverride below are never called
+            // for the freshly added child, its Bounds stay default(Rect), and the X11
+            // INativeControlHostImpl never gets non-zero bounds to map its slot at
+            // (the symptom in https://github.com/AvaloniaUI/Avalonia.Controls.WebView/issues/5).
+            InvalidateMeasure();
 #elif WPF
             IsVisibleChanged += OnIsVisibleChanged;
             var visual = (System.Windows.Media.Visual)controlHostImpl;
@@ -507,16 +513,46 @@ protected override ControlSize MeasureOverride(ControlSize availableSize)
             // Also WPF doesn't have an equivalent.
             // Keeping this hack makes some sort of a compromise, where on Ava 11.3 we have this property and and potentially reset by user if needed.
             var measured = base.MeasureOverride(availableSize);
+
+            ControlSize resolved;
 #if AVALONIA
             if (s_setSizing is not null)
-                return measured;
+                resolved = measured;
+            else
+#endif
+                resolved = new ControlSize(
+                    double.IsInfinity(availableSize.Width) ? measured.Width : availableSize.Width,
+                    double.IsInfinity(availableSize.Height) ? measured.Height : availableSize.Height);
+
+#if AVALONIA
+            // controlHostImpl is added via VisualChildren.Add, which does NOT make it a
+            // layout participant — Avalonia only measures/arranges visual children that
+            // the parent explicitly drives. Without this, the inner NativeControlHost's
+            // Bounds stay default(Rect) and the X11 INativeControlHostImpl never maps
+            // its slot. See issue #5 / PR #38.
+            foreach (var child in VisualChildren)
+            {
+                if (child is global::Avalonia.Layout.Layoutable layoutable)
+                    layoutable.Measure(resolved);
+            }
 #endif
 
-            return new ControlSize(
-                double.IsInfinity(availableSize.Width) ? measured.Width : availableSize.Width,
-                double.IsInfinity(availableSize.Height) ? measured.Height : availableSize.Height);
+            return resolved;
         }
 
+#if AVALONIA
+        protected override ControlSize ArrangeOverride(ControlSize finalSize)
+        {
+            var arranged = base.ArrangeOverride(finalSize);
+            foreach (var child in VisualChildren)
+            {
+                if (child is global::Avalonia.Layout.Layoutable layoutable)
+                    layoutable.Arrange(new global::Avalonia.Rect(arranged));
+            }
+            return arranged;
+        }
+#endif
+
         private void WithFocusOnLostFocus(object? sender, Core.IWebViewAdapterWithFocus.LostFocusDirection e)
         {
             Core.WebViewDispatcher.VerifyAccess();