linux: Add support for embedded Ozone/Wayland windows

[leandromqrs]

Adds the native windowed mode on Ozone/Wayland: a browser hosted inside a window the client application owns, the way CefWindowInfo::SetAsChild already works on X11. This is issue #2804.

Before deciding whether to read the rest: this needs a decision from you before it can be finished, and it is the first item in the dependency list in that issue. The API question is the blocker, not the code.

Some context first: I posted a demo and the branch in the issue before opening this (#2804 (comment)), so this is not arriving cold. But the approach itself was not discussed there before the work started, which CONTRIBUTING asks for on architectural changes, and that was a mistake on my part. The branch exists as something concrete to react to, not as a decision already made. If the API shape below is wrong, it changes.

Demonstration

saida.webm

What is here

Five commits. The first is a Chromium patch; the rest are CEF.

chromium: Add Wayland subsurface embedding to Ozone	patch/patches/ozone_wayland_embed_2804.patch
linux: Add Wayland API and runtime platform selection	public API, cef_ozone::IsWayland()
linux: Create windowed browsers on Wayland	browser_platform_delegate_native_linux.cc
linux: Add a Wayland embedding sample	tests/cefembed_wayland
docs: Add design notes for Wayland embedding	docs/wayland_embedding.md

The design and the reasoning behind each decision are in docs/wayland_embedding.md. This description covers what you need to decide and what you should not trust.

The API decision

cef_window_info_t::parent_window carries the client's wl_surface. No new field: that member has always been an opaque native parent handle whose meaning depends on the platform (an HWND on Windows, an NSView* on macOS), and the unsigned long spelling on Linux is an artifact of X11 that holds a pointer on LP64. Existing embedders keep compiling and keep working.

The cost is the failure mode. A valid XID such as 0x2600004 is numerically indistinguishable from an address, so passing the wrong handle for the active platform is undefined rather than diagnosed. In practice the handle comes from the client's toolkit, which knows which platform it is on. If you would rather have a separate field and a diagnosable error, that is a reasonable call and this branch should change.

One member is appended, under CEF_API_ADDED(CEF_EXPERIMENTAL):

cef_xdg_surface_handle_t parent_xdg_surface;  // in, for popups

with a three-argument SetAsChild(parent, parent_xdg, bounds) alongside the existing form. May be null; popups then fall back to a degraded subsurface form, described in the docs.

An earlier revision also returned the browser's own wl_surface as an output member. It was removed, because a wl_surface is scoped to the connection the embedder already owns, so it told the embedder nothing it could act on.

The connection is passed process-wide, not per browser, because Chromium builds its WaylandConnection while initializing Ozone, inside CefInitialize and long before any CefWindowInfo exists:

CEF_EXPORT void cef_set_wayland_display(cef_wayland_display_handle_t display);

The 2020 Igalia prototype put this on CefWindowInfo; that cannot work for the reason above.

CefBrowserHost::SetWindowBounds() is new and unavoidable: a wl_subsurface receives no configure events, so the client is the only source of layout. It is declared last in the class on purpose, because the translator moves versioned members to the end of the generated struct in declaration order, and putting it earlier would shift the existing experimental set_ax_viewport_collapse.

The Chromium patch

This is what makes it not a small pull request. patch/patches/ozone_wayland_embed_2804.patch is the largest patch in the tree and the first to add files rather than only edit them. It shares the embedder's wl_display, because a wl_surface is scoped to one connection and wl_subcompositor_get_subsurface() rejects surfaces from another, and it adds a WaylandWindow subclass attached as a wl_subsurface of a bare surface with no WaylandWindow behind it. The rest is in the docs.

One thing from it belongs here rather than in the docs, because it is a bug and not a design decision. RootWindowFromWlSurface() used to read any wl_surface's user data and cast it to ui::WaylandSurface, which on a shared connection is a pointer owned by the client's toolkit. Reproduced as a GPF by moving the mouse over a client's CSD borders. The patch splits the lookup by class so that only Chromium's own surfaces resolve.

Whether the patch belongs in CEF or upstream in Chromium is your call; I have no standing to make it. I understand what carrying it costs: it has to be rebased at every milestone, and it touches files that churn. I am willing to keep it rebased for as long as it is useful. Some of it may not need to be carried at all: the surface lookup fix above is independent of embedding and could be proposed to Chromium on its own.

What it does:

• WaylandConnection adopts an externally owned wl_display. A wl_surface is scoped to one connection and wl_subcompositor_get_subsurface() rejects surfaces from another, so there is no way to parent into the client's surface without sharing the connection. Smaller than expected, since Chromium already routes its traffic through a dedicated wl_event_queue.
• WaylandEmbeddedWindow, a WaylandWindow attached as a wl_subsurface of a bare wl_surface with no WaylandWindow behind it. Registered in WaylandWindowManager like any other, which is what makes accelerated-widget lookup resolve.
• Input split by class. RootWindowFromWlSurface() resolves only Chromium's own surfaces; only the keyboard and text input cross over from the embedder's, through a separate lookup. This also closes a latent memory-safety bug: that function used to read any wl_surface's user data and cast it to ui::WaylandSurface, which on a shared connection is a pointer owned by the client's toolkit. Reproduced as a GPF by moving the mouse over a client's CSD borders.
• Activation derived from the seat and notified through the window manager, exactly as WaylandToplevelWindow does it.

The design tries hard to have no special cases. Where it diverges from the toplevel, the comment says why.

Verified

Fedora 44, GNOME 50 Wayland, two monitors at different scales, against a local build of this branch.

Rendering inside the client's window, pointer, keyboard, <select> and context menus, resize, close. IME with ibus and Intelligent Pinyin: preedit underlined in the field, candidate window next to the caret, commit landing in the input. Drag and drop in both directions, including drops over the client's own chrome still going to the client. HiDPI with fractional scaling, starting on either kind of output and dragging between them. Several browsers in one window, created, moved, hidden and closed independently, with keyboard focus following both SetFocus() and a click.

The X11 path is unchanged behaviour with the same binary.

Most of that was exercised with a separate host application rather than the sample in this branch:

https://github.com/leandromqrs/cef-wayland-embed-sample

It is an interactive suite in Rust over winit that creates and destroys browsers at runtime in all three CEF hosting modes, moves and resizes panels independently, and reports what the host saw next to what the browser saw. It also runs against stock CEF, which is what makes the comparison meaningful. The C++ tests/cefembed_wayland in this branch is the minimal reference; that one is the test rig.

34 unit tests across both layers: 30 in Ozone on the WaylandTest harness, 4 for the cef_window_info_t ABI. The 476 Wayland tests in the tree still pass with the patch applied. Each new test was verified by reintroducing the defect it covers.

Not verified

The macOS build. No machine available. Audited instead: of the 18 files this branch touches, 12 are either not compiled at all or excluded by if (is_linux) and #if defined(OS_LINUX). The six that remain hold exactly one platform-guarded symbol, SetHostBounds, guarded identically in its declaration, its definition and its call site, and SetWindowBounds, which is pure virtual in cef_browser.h but has a single implementation in a cross-platform file. The residual risk is a compile error, not a runtime defect. It is not zero, though, and your CI will find it faster than I can.

Known limitations

Two, both with their causes and the reasoning in the docs. Resizing lags the client by a frame, because wl_subsurface.set_position is double-buffered on the parent surface and the two surfaces are submitted in separate compositor frames; WaylandBubble carries the same TODO upstream (https://crbug.com/329145822). And where the client exposes no xdg_surface, popups fall back to a wl_subsurface, which cannot extend past the client's window or hold a grab, so a dropdown near an edge is clipped and clicking outside does not dismiss it. Failing instead is not available, because WaylandWindow::Create() returning null makes views destroy the widget inside Widget::Show(), which CHECKs. Both CEF and Ozone log a warning naming the limitation when the fallback is taken.

On how this was written

Written with heavy AI assistance, disclosed in the commit trailers. I take responsibility for all of it: I can explain any decision here, and the reasoning behind each is either in docs/wayland_embedding.md or in the comment next to the code.