feat: add native Wayland support (explicit opt-in, X11/XWayland default)

On Wayland sessions, X11/XWayland is used by default so CEF's browser widget
is parented inside a GTK frame window that the window manager decorates normally
(title bar, resize handles, close button).

Native Wayland mode (ozone-platform=wayland) is available as an explicit opt-in
via switches={"ozone-platform": "wayland"} in cef.Initialize().  It is not
auto-selected from WAYLAND_DISPLAY because CEF's NativeWidgetDelegate
hardcodes params.remove_standard_frame=true / params.type=TYPE_CONTROL on the
standalone Wayland path, which prevents the Wayland compositor from adding
Server Side Decorations.

Key changes:
- _linux_apply_initialize_defaults(): detects wayland vs x11 mode; defaults
  to X11/XWayland; native Wayland only when ozone-platform=wayland is explicit
- Initialize(): skips GTK/X11 init and X11ErrorHandlers in Wayland mode
- CreateBrowserSync(): in Wayland mode passes parent=0 so CEF creates its own
  xdg_toplevel; in X11 mode creates a GTK frame window as before
- HideX11ShellWindow(): unmaps the empty CefWindowX11 shell that CEF creates
  alongside the NativeWidgetDelegate content window when SUPPORTS_OZONE_X11 is
  compiled in, leaving only the content-bearing Wayland window visible
- _linux_register_wayland_close_handler(): installs a DoClose callback that
  calls QuitMessageLoop() since CloseHostWindow() is a no-op on Wayland
- _linux_wayland_message_loop(): bare GLib loop driving CefDoMessageLoopWork()
  every 10 ms without any GTK window; QuitMessageLoop() calls g_main_loop_quit()
- WindowInfo.SetAsChild: suppresses spurious handle=0 warning in Wayland mode

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: linesight

src/cefpython.pyx

@@ -578,12 +578,15 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
             g_commandLineSwitches["use-angle"] = "gl"
 
     IF UNAME_SYSNAME == "Linux":
-        # Initialize GTK so GDK has a display connection before CefInitialize.
-        _linux_gtk_init()
-        # Auto-apply switches/settings required for CEF 146 on Linux/Xwayland.
-        # Uses setdefault so user-supplied values are never overwritten.
+        # Detect Wayland/X11 mode and apply switches BEFORE gtk_init so we
+        # know whether to open a GTK/X11 display connection at all.
         _linux_apply_initialize_defaults(application_settings,
                                          g_commandLineSwitches)
+        # In X11/Xwayland mode, open a GDK display connection before
+        # CefInitialize so the Ozone X11 backend can use it.
+        # In native Wayland mode, no GTK/X11 connection is needed or wanted.
+        if not _g_linux_wayland_mode:
+            _linux_gtk_init()
         # Pre-seed Chrome profile files to prevent the profile-picker keepalive
         # from blocking OnContextInitialized (Chrome 146).
         if application_settings.get("cache_path"):
@@ -694,8 +697,7 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
             Debug("CefInitialize() WARNING: OnContextInitialized not received"
                   " within 30 seconds")
 
-    if sys.platform.startswith("linux"):
-        # Install by default.
+    if sys.platform.startswith("linux") and not _g_linux_wayland_mode:
         WindowUtils.InstallX11ErrorHandlers()
 
 
@@ -799,17 +801,24 @@ def CreateBrowserSync(windowInfo=None,
     elif not isinstance(windowInfo, WindowInfo):
         raise Exception("CreateBrowserSync() failed: windowInfo: invalid object")
 
-    # On Linux, when no parent window is given, auto-create a GTK toplevel
-    # so callers need no GTK-specific code (same API as Windows/Mac).
+    # On Linux, when no parent window is given, provide a top-level window
+    # so callers need no toolkit-specific code (same API as Windows/Mac).
     _linux_toplevel_state = None
     IF UNAME_SYSNAME == "Linux":
         if windowInfo.windowType == "child" and windowInfo.parentWindowHandle == 0:
-            _linux_toplevel_state = _linux_create_toplevel(
-                    window_title or "CEF Browser")
-            windowInfo.SetAsChild(
-                    _linux_toplevel_state['xid'],
-                    [0, 0, _linux_toplevel_state['width'],
-                           _linux_toplevel_state['height']])
+            if _g_linux_wayland_mode:
+                # Native Wayland: CEF creates its own xdg_toplevel surface.
+                # Pass parent=0 with default bounds; no GTK window is needed.
+                _linux_toplevel_state = {'wayland': True}
+                windowInfo.SetAsChild(0, [0, 0, _LINUX_DEFAULT_WIDTH,
+                                            _LINUX_DEFAULT_HEIGHT])
+            else:
+                _linux_toplevel_state = _linux_create_toplevel(
+                        window_title or "CEF Browser")
+                windowInfo.SetAsChild(
+                        _linux_toplevel_state['xid'],
+                        [0, 0, _linux_toplevel_state['width'],
+                               _linux_toplevel_state['height']])
 
     if window_title and windowInfo.parentWindowHandle == 0:
         windowInfo.windowName = window_title
@@ -903,8 +912,12 @@ def CreateBrowserSync(windowInfo=None,
             and windowInfo.windowName:
         # Set window title in hello_world.py example
         IF UNAME_SYSNAME == "Linux":
-            x11.SetX11WindowTitle(cefBrowser,
-                                  PyStringToChar(windowInfo.windowName))
+            # X11 title setting uses XStoreName which requires an X11 display.
+            # Skip on native Wayland; CEF's Ozone backend propagates the page
+            # title to the compositor via xdg_toplevel_set_title automatically.
+            if not _g_linux_wayland_mode:
+                x11.SetX11WindowTitle(cefBrowser,
+                                      PyStringToChar(windowInfo.windowName))
         ELIF UNAME_SYSNAME == "Darwin":
             MacSetWindowTitle(cefBrowser,
                               PyStringToChar(windowInfo.windowName))
@@ -913,7 +926,20 @@ def CreateBrowserSync(windowInfo=None,
         if windowInfo._linux_embed_info:
             _linux_schedule_xembed(pyBrowser, windowInfo._linux_embed_info)
         if _linux_toplevel_state is not None:
-            _linux_register_window_callbacks(pyBrowser, _linux_toplevel_state)
+            if _linux_toplevel_state.get('wayland'):
+                # Native Wayland top-level: register a DoClose callback that
+                # quits the GLib loop.  On Wayland, CloseHostWindow() is a
+                # compile-time no-op, so we must exit the loop ourselves when
+                # DoClose fires (either from CloseBrowser() or xdg_toplevel.close).
+                _linux_register_wayland_close_handler(pyBrowser)
+                # When SUPPORTS_OZONE_X11 is compiled, CreateHostWindow() creates
+                # both an X11/XWayland shell window (empty) and a Wayland
+                # xdg_toplevel with the actual browser content.  Hide the empty
+                # X11 shell so only the content-bearing Wayland window is visible.
+                x11.HideX11ShellWindow(cefBrowser)
+            else:
+                # X11/XWayland top-level: attach GTK resize and close callbacks.
+                _linux_register_window_callbacks(pyBrowser, _linux_toplevel_state)
 
     return pyBrowser
 
@@ -956,13 +982,21 @@ def QuitMessageLoop():
     Debug("QuitMessageLoop()")
     IF UNAME_SYSNAME == "Linux":
         import ctypes as _ct
-        _gtk = _ct.CDLL("libgtk-3.so.0")
-        # Only call gtk_main_quit() when a GTK main loop is actually running.
-        # _on_delete() may have already called it (via gtk_main_quit directly),
-        # and calling it a second time during the drain would generate a
-        # spurious "assertion 'main_loops != NULL' failed" warning.
-        if _gtk.gtk_main_level() > 0:
-            _gtk.gtk_main_quit()
+        if _g_linux_wayland_mode:
+            # Native Wayland: quit the GLib main loop stored by
+            # _linux_wayland_message_loop().  g_main_loop_quit() is
+            # thread-safe and safe to call even from a CEF UI-thread task.
+            if _g_wayland_main_loop is not None:
+                _glib = _ct.CDLL("libglib-2.0.so.0")
+                _glib.g_main_loop_quit(_ct.c_void_p(_g_wayland_main_loop))
+        else:
+            _gtk = _ct.CDLL("libgtk-3.so.0")
+            # Only call gtk_main_quit() when a GTK main loop is actually running.
+            # _on_delete() may have already called it (via gtk_main_quit directly),
+            # and calling it a second time during the drain would generate a
+            # spurious "assertion 'main_loops != NULL' failed" warning.
+            if _gtk.gtk_main_level() > 0:
+                _gtk.gtk_main_quit()
     with nogil:
         CefQuitMessageLoop()
 

src/client_handler/x11.cpp

@@ -54,6 +54,20 @@ void SetX11WindowTitle(CefRefPtr<CefBrowser> browser, char* title) {
     XStoreName(xdisplay, xwindow, title);
 }
 
+void HideX11ShellWindow(CefRefPtr<CefBrowser> browser) {
+    // On native Wayland (ozone-platform=wayland) with SUPPORTS_OZONE_X11
+    // compiled in, CEF's CreateHostWindow() creates two separate windows:
+    //   1. An X11/XWayland top-level shell (CefWindowX11) — empty, visible
+    //   2. A Wayland xdg_toplevel (NativeWidgetDelegate) — holds the content
+    // Unmap the empty X11 shell so only the content-bearing Wayland window
+    // is visible to the user.
+    ::Window xwindow = browser->GetHost()->GetWindowHandle();
+    ::Display* xdisplay = cef_get_xdisplay();
+    if (!xdisplay || !xwindow) return;
+    XUnmapWindow(xdisplay, xwindow);
+    XFlush(xdisplay);
+}
+
 GtkWindow* CefBrowser_GetGtkWindow(CefRefPtr<CefBrowser> browser) {
   // TODO: Should return NULL when using the Views framework
   // -- REWRITTEN FOR CEF PYTHON USE CASE --

src/client_handler/x11.h

@@ -19,6 +19,7 @@ void InstallX11ErrorHandlers();
 void SetX11WindowBounds(CefRefPtr<CefBrowser> browser,
                         int x, int y, int width, int height);
 void SetX11WindowTitle(CefRefPtr<CefBrowser> browser, char* title);
+void HideX11ShellWindow(CefRefPtr<CefBrowser> browser);
 
 GtkWindow* CefBrowser_GetGtkWindow(CefRefPtr<CefBrowser> browser);
 XImage* CefBrowser_GetImage(CefRefPtr<CefBrowser> browser);

src/extern/x11.pxd

@@ -12,4 +12,5 @@ cdef extern from "client_handler/x11.h" nogil:
     void SetX11WindowBounds(CefRefPtr[CefBrowser] browser,
                             int x, int y, int width, int height)
     void SetX11WindowTitle(CefRefPtr[CefBrowser] browser, char* title)
+    void HideX11ShellWindow(CefRefPtr[CefBrowser] browser)
     XImage* CefBrowser_GetImage(CefRefPtr[CefBrowser] browser)

src/window_info.pyx

@@ -116,7 +116,11 @@ cdef class WindowInfo:
             if parentWindowHandle == 0:
                 import os as _os
                 import warnings
-                if "WAYLAND_DISPLAY" in _os.environ:
+                # In native Wayland mode, parentWindowHandle=0 is correct and
+                # expected — CEF creates its own xdg_toplevel surface.  Only
+                # warn when the user is likely using an X11-incompatible toolkit
+                # without having opted into native Wayland.
+                if "WAYLAND_DISPLAY" in _os.environ and not _g_linux_wayland_mode:
                     warnings.warn(
                         "WindowInfo.SetAsChild: parentWindowHandle is 0 on Linux "
                         "in a Wayland session. The GUI toolkit is likely using the "

src/window_utils_linux.pyx

@@ -4,6 +4,19 @@
 
 include "cefpython.pyx"
 
+# Set to True when native Wayland mode is active (ozone-platform=wayland).
+# Initialised by _linux_apply_initialize_defaults() inside Initialize().
+_g_linux_wayland_mode = False
+
+# GMainLoop* pointer (raw integer) used by _linux_wayland_message_loop().
+# Stored here so QuitMessageLoop() can call g_main_loop_quit() on it.
+_g_wayland_main_loop = None
+
+# Default size for auto-created top-level windows (X11 and Wayland paths).
+_LINUX_DEFAULT_WIDTH = 800
+_LINUX_DEFAULT_HEIGHT = 600
+
+
 class WindowUtils:
     # You have to overwrite this class and provide implementations
     # for these methods.
@@ -86,20 +99,40 @@ def _linux_get_root_xid():
 
 
 def _linux_apply_initialize_defaults(app_settings, cmd_switches):
-    """Auto-apply Linux/Xwayland CEF 146 defaults that every embedding app needs.
+    """Auto-apply Linux CEF 146 defaults that every app needs.
+
+    X11/XWayland is the default on all Linux systems (even Wayland sessions).
+    Native Wayland mode must be requested explicitly by passing
+    switches={"ozone-platform": "wayland"} to cef.Initialize().
+
+    Reason: CEF's NativeWidgetDelegate hardcodes params.remove_standard_frame=true
+    and params.type=TYPE_CONTROL for the standalone Wayland path, so the
+    compositor never adds Server Side Decorations.  In X11/XWayland mode CEF
+    parents the browser widget inside the GTK window we create, and the window
+    manager decorates the GTK frame window normally.
 
     Uses setdefault so users can still override any individual entry by passing
     it explicitly to cef.Initialize(switches={...}).
     """
+    global _g_linux_wayland_mode
     import os as _os
 
-    # Must be set before GTK is first initialized (gtk_init).  Belt-and-
-    # suspenders: also set it here in case the user forgot to set it before
-    # the cefpython3 import.
-    _os.environ.setdefault("GDK_BACKEND", "x11")
+    # Native Wayland mode only when the caller explicitly opts in.
+    _ozone_explicit = cmd_switches.get("ozone-platform", "")
+    _wayland_mode = (_ozone_explicit == "wayland")
+    _g_linux_wayland_mode = _wayland_mode
 
-    # Force X11 mode in Chrome's Ozone platform selection.
-    _os.environ.pop("WAYLAND_DISPLAY", None)
+    if not _wayland_mode:
+        # X11/Xwayland mode: force GDK and Chrome onto X11.
+        # Must be set before gtk_init() so GDK opens an X11/Xwayland display.
+        _os.environ.setdefault("GDK_BACKEND", "x11")
+        # Remove WAYLAND_DISPLAY so Chrome's Ozone platform selection picks X11.
+        _os.environ.pop("WAYLAND_DISPLAY", None)
+        cmd_switches.setdefault("ozone-platform", "x11")
+    else:
+        # Native Wayland mode: use the Ozone Wayland backend.
+        # Keep WAYLAND_DISPLAY so Chrome connects to the Wayland compositor.
+        cmd_switches.setdefault("ozone-platform", "wayland")
 
     # Point the Vulkan loader at the SwiftShader ICD shipped with CEF.
     import cefpython3 as _cef3_pkg
@@ -121,7 +154,8 @@ def _linux_apply_initialize_defaults(app_settings, cmd_switches):
 
     # Chromium switches required for stable embedded operation on CEF 146.
     sw = cmd_switches
-    # Force X11 backend (not Wayland) — cefpython uses raw X11 window handles.
+    # Ozone platform: already set above (wayland or x11); setdefault is a no-op
+    # if the user already passed ozone-platform explicitly.
     sw.setdefault("ozone-platform", "x11")
     # Bypass Zygote to avoid stack-smash crash from --change-stack-guard-on-fork.
     sw.setdefault("disable-zygote", "")
@@ -221,7 +255,7 @@ def _linux_setup_profile(cache_path):
             }, _f)
 
 
-def _linux_create_toplevel(title, width=800, height=600):
+def _linux_create_toplevel(title, width=_LINUX_DEFAULT_WIDTH, height=_LINUX_DEFAULT_HEIGHT):
     """Create a standalone GTK toplevel window for embedded browser use.
 
     Called from CreateBrowserSync when no parent window handle is given on
@@ -345,14 +379,81 @@ def _linux_register_window_callbacks(browser, ws):
                                    _del_cb, None, None, 0)
 
 
+def _linux_register_wayland_close_handler(browser):
+    """Register a DoClose callback for a native Wayland auto-created top-level window.
+
+    On Wayland with the Alloy runtime, CloseHostWindow() is a compile-time no-op
+    (guarded by #if BUILDFLAG(SUPPORTS_OZONE_X11)), so WindowDestroyed() is never
+    called and OnBeforeClose never fires through the normal CEF destroy chain.
+
+    This callback bridges the gap: when the user closes the native Wayland window
+    (xdg_toplevel.close) or when CloseBrowser(True) is called, DoClose fires.
+    We quit the GLib main loop so MessageLoop() returns and the caller can proceed
+    to cef.Shutdown().  Returning False tells CEF to proceed with the close;
+    CloseHostWindow() then no-ops, but the drain loop in
+    _linux_wayland_message_loop() handles final CEF cleanup.
+    """
+    _existing = browser.GetClientCallback("DoClose")
+
+    def _wayland_do_close(browser, **_kw):
+        suppress = False
+        if _existing:
+            try:
+                suppress = bool(_existing(browser=browser))
+            except Exception:
+                pass
+        if not suppress:
+            QuitMessageLoop()
+        return suppress
+
+    browser.SetClientCallback("DoClose", _wayland_do_close)
+
+
+def _linux_wayland_message_loop():
+    """Run a GLib main loop driving CefDoMessageLoopWork() for native Wayland.
+
+    No GTK window is involved; CEF's Ozone Wayland backend creates and owns its
+    own wl_surface.  The GLib main loop is used only as a portable timer source
+    to pump the CEF message queue every 10 ms.  QuitMessageLoop() calls
+    g_main_loop_quit() on the stored loop pointer to stop it.
+    """
+    global _g_wayland_main_loop
+    import ctypes as _ct, time as _t
+
+    _glib = _ct.CDLL("libglib-2.0.so.0")
+    _glib.g_main_loop_new.restype = _ct.c_void_p
+
+    _loop = _glib.g_main_loop_new(None, False)
+    _g_wayland_main_loop = _loop
+
+    _WorkCb = _ct.CFUNCTYPE(_ct.c_bool, _ct.c_void_p)
+    def _cef_work(_ud):
+        MessageLoopWork()
+        return True
+    _cb = _WorkCb(_cef_work)
+    g_linux_reparent_callbacks.append(_cb)
+    _glib.g_timeout_add(10, _cb, None)
+
+    _glib.g_main_loop_run(_ct.c_void_p(_loop))
+
+    for _ in range(50):
+        MessageLoopWork()
+        _t.sleep(0.01)
+
+    _glib.g_main_loop_unref(_ct.c_void_p(_loop))
+    _g_wayland_main_loop = None
+
+
 def _linux_message_loop():
-    """Run gtk_main() with a GLib timer driving CefDoMessageLoopWork().
+    """Run the appropriate message loop for the active platform backend.
 
-    Used by cef.MessageLoop() on Linux.  CEF's Ozone X11 backend requires a
-    running GLib main loop; gtk_main() provides that while the timer pumps
-    CEF's internal work queue every 10 ms.  After gtk_main() returns, pump
-    CEF briefly so browsers can close cleanly before cef.Shutdown().
+    Dispatches to the Wayland GLib loop or the GTK/X11 loop depending on
+    whether native Wayland mode was detected during Initialize().
     """
+    if _g_linux_wayland_mode:
+        _linux_wayland_message_loop()
+        return
+
     import ctypes as _ct, time as _t
 
     _gtk = _ct.CDLL("libgtk-3.so.0")