Sync cefpython147-qt with cefpython147 (2026-05-09)

Squash-merge of 10 commits from cefpython147 to refresh PR #691 with
the latest fixes and enhancements developed since the last sync.

Features:
* Add native Wayland support — explicit opt-in via WindowInfo;
  X11/XWayland remains the default (9c2ae77)
* Implement RenderHandler.GetScreenInfo with HiDPI support so
  high-DPI displays report accurate device scale factors (9969797)
* examples/pysdl2: support multiple popup windows with clean
  shutdown (bb24151)

Fixes:
* Sync render_handler with current CEF API (c6f2a56)
* Guard X11 error-handler install at compile time in
  cefpython.pyx (7a65e6b)
* examples/pysdl2: window resize, HiDPI rendering, mouse drag,
  Wayland DPI handling (2aff2c9)
* examples/pysdl2: scale mouse wheel by deviceScaleFactor for
  HiDPI (3e45abd)

Refactor / docs:
* Audit cef.Initialize defaults on Linux; drop dead switches and
  stale workarounds (db13d7d)
* Correct version-tagged comments to match actual upstream
  history (bd924c4)
* Drop defensive parenthetical from sandbox History comment in
  window_utils_linux.pyx (7ae0553)

Author: linesight

api/API-index.md

@@ -347,8 +347,8 @@
 * [RenderHandler (interface)](RenderHandler.md#renderhandler-interface)
   * [GetRootScreenRect](RenderHandler.md#getrootscreenrect)
   * [GetViewRect](RenderHandler.md#getviewrect)
-  * [GetScreenRect](RenderHandler.md#getscreenrect)
   * [GetScreenPoint](RenderHandler.md#getscreenpoint)
+  * [GetScreenInfo](RenderHandler.md#getscreeninfo)
   * [OnPopupShow](RenderHandler.md#onpopupshow)
   * [OnPopupSize](RenderHandler.md#onpopupsize)
   * [OnPaint](RenderHandler.md#onpaint)

api/RenderHandler.md

@@ -15,8 +15,8 @@ Table of contents:
 * [Callbacks](#callbacks)
   * [GetRootScreenRect](#getrootscreenrect)
   * [GetViewRect](#getviewrect)
-  * [GetScreenRect](#getscreenrect)
   * [GetScreenPoint](#getscreenpoint)
+  * [GetScreenInfo](#getscreeninfo)
   * [OnPopupShow](#onpopupshow)
   * [OnPopupSize](#onpopupsize)
   * [OnPaint](#onpaint)
@@ -43,7 +43,6 @@ Off-screen rendering examples:
 
 Callbacks available in upstream CEF, but not yet exposed in CEF Python
 (see src/include/cef_render_handler.h):
-* GetScreenInfo
 * OnImeCompositionRangeChanged
 
 
@@ -74,30 +73,58 @@ Called to retrieve the view rectangle which is relative to screen
 coordinates. Return true if the rectangle was provided.
 
 
-### GetScreenRect
+### GetScreenPoint
 
 | Parameter | Type |
 | --- | --- |
 | browser | [Browser](Browser.md) |
-| rect_out | list[x,y,width,height] |
+| view_x | int |
+| view_y | int |
+| screen_coordinates_out | list[x,y] |
 | __Return__ | bool |
 
-Called to retrieve the simulated screen rectangle. Return true
-if the rectangle was provided.
+Called to retrieve the translation from view coordinates to actual
+screen coordinates. Return true if the screen coordinates were provided.
 
 
-### GetScreenPoint
+### GetScreenInfo
 
 | Parameter | Type |
 | --- | --- |
 | browser | [Browser](Browser.md) |
-| view_x | int |
-| view_y | int |
-| screen_coordinates_out | list[x,y] |
+| screen_info_out | dict |
 | __Return__ | bool |
 
-Called to retrieve the translation from view coordinates to actual
-screen coordinates. Return true if the screen coordinates were provided.
+Called to allow the client to fill in the screen info with appropriate
+values. Return true if `screen_info_out` was modified, false to let CEF
+use defaults.
+
+Fill `screen_info_out` with any of the following keys (all optional):
+
+| Key | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `device_scale_factor` | float | `1.0` | Ratio between physical and logical pixels. **Must be > 0.** |
+| `depth` | int | `24` | Screen depth in bits per pixel. |
+| `depth_per_component` | int | `8` | Bits per color component. |
+| `is_monochrome` | bool | `False` | True for black-and-white printers. |
+| `rect` | list[x,y,width,height] | unset | Display monitor rectangle in DIP. |
+| `available_rect` | list[x,y,width,height] | unset | Work-area rectangle in DIP (excludes taskbars). If only `rect` is supplied it is mirrored into `available_rect`. |
+
+If neither `rect` nor `available_rect` is supplied, CEF falls back to
+the rectangle returned by `GetViewRect` (popups may be misplaced if
+the rectangle ends up empty).
+
+**HiDPI handling:** set `device_scale_factor` to match the host
+display (e.g. `2.0` on a Retina/4K screen, `1.5` for 150% fractional
+scaling). The factor is applied to the OnPaint buffer: with a view
+rect of 800x600 and `device_scale_factor=2.0`, OnPaint receives a
+1600x1200 BGRA buffer while `width`/`height` arguments equal the
+buffer's pixel dimensions. Always upload the buffer at its actual
+pixel size and lay it out at the view's logical size to avoid
+blurry output. Call
+[Browser.NotifyScreenInfoChanged](Browser.md#notifyscreeninfochanged)
+when the device scale factor or display geometry changes (e.g. the
+window moved to a different monitor) so CEF re-queries this callback.
 
 
 ### OnPopupShow
@@ -173,6 +200,8 @@ Called when the browser's cursor has changed. If |type| is CT_CUSTOM then
 | Parameter | Type |
 | --- | --- |
 | browser | [Browser](Browser.md) |
+| x | float |
+| y | float |
 | __Return__ | void |
 
 Called when the scroll offset has changed.

docs/Knowledge-Base.md

@@ -13,10 +13,12 @@ Table of contents:
 * [How to capture Audio and Video in HTML5?](#how-to-capture-audio-and-video-in-html5)
 * [Touch and multi-touch support](#touch-and-multi-touch-support)
 * [Black or white browser screen](#black-or-white-browser-screen)
+* ["kTransientFailure: Failed to send GpuControl.CreateCommandBuffer" on Linux](#ktransientfailure-failed-to-send-gpucontrolcreatecommandbuffer-on-linux)
 * [Python crashes with "Segmentation fault" - how to debug?](#python-crashes-with-segmentation-fault---how-to-debug)
 * [Windows XP support](#windows-xp-support)
 * [Mac 32-bit support](#mac-32-bit-support)
 * [Security](#security)
+  * [Linux: enabling the Chromium sandbox (advanced)](#linux-enabling-the-chromium-sandbox-advanced)
 
 
 ## Notifications about new releases / commits
@@ -264,6 +266,33 @@ appear even after disabling GPU hardware acceleration. This is normal
 because GPU was disabled so WebGL cannot work.
 
 
+## "kTransientFailure: Failed to send GpuControl.CreateCommandBuffer" on Linux
+
+You may see a log line like this during startup, especially on Linux
+VMs and other systems without a working GPU. On VMs the line appears in
+nearly every run; on bare metal with a real GPU it is rarer:
+
+```
+ERROR:gpu/ipc/client/command_buffer_proxy_impl.cc:285] ContextResult::kTransientFailure: Failed to send GpuControl.CreateCommandBuffer.
+```
+
+**This is a Chromium-recoverable transient and can be ignored.** It is
+emitted by the renderer process when it tries to create a GPU command
+buffer before the GPU process has finished binding its IPC endpoint —
+typically a millisecond-scale race during startup, more likely on slow
+disks or when Chromium falls back from real-GL to SwiftShader. The
+compositor retries automatically; pages still render and
+`OnContextInitialized` still fires. The `kTransientFailure` label is
+Chromium's own classification — Chromium expects callers to retry, and
+they do.
+
+If a clean log is more important than hardware acceleration in your
+deployment, you can opt in to disabling the GPU process by passing
+`switches={"disable-gpu": ""}` to `cef.Initialize()`. Do not enable
+`in-process-gpu` to silence this line — it is not stable across
+multiple browser windows.
+
+
 ## Python crashes with "Segmentation fault" - how to debug?
 
 Install gdb:
@@ -347,3 +376,59 @@ A quote by Marshall Greenblatt:
 Reference: [Question on browser security](http://magpcss.org/ceforum/viewtopic.php?f=10&t=10222)
 on the CEF Forum.
 
+
+### Linux: enabling the Chromium sandbox (advanced)
+
+cefpython on Linux passes `--no-sandbox` by default
+(`_linux_apply_initialize_defaults` in `src/window_utils_linux.pyx`).
+
+Reasons for the default:
+1. cefpython does not bundle the SUID-root `chrome-sandbox` helper that
+   Chromium's namespace sandbox needs to bypass AppArmor's
+   `apparmor_restrict_unprivileged_userns=1` (the default on Ubuntu
+   23.10+, Debian 12+, and other modern distros).
+2. Without the helper, Chromium aborts at startup with
+   `FATAL: No usable sandbox!` — every cefpython app would fail to
+   launch out of the box.
+3. The most common cefpython use case is rendering the application's
+   own trusted HTML/JS as a UI surface, where the sandbox provides
+   defense-in-depth rather than primary security.
+
+If your app loads untrusted web content and you want the Chromium
+sandbox enabled, three steps are required:
+
+**1. Install the SUID-root `chrome-sandbox` helper.**
+The binary ships in the CEF binary distribution under
+`Release/chrome-sandbox`. Copy it to a stable path and set it up:
+
+```bash
+sudo cp /path/to/cef_binary_<ver>_linux64/Release/chrome-sandbox \
+        /opt/cef/chrome-sandbox
+sudo chown root:root /opt/cef/chrome-sandbox
+sudo chmod 4755 /opt/cef/chrome-sandbox
+```
+
+**2. Tell Chromium where the helper lives.** Set the
+`CHROME_DEVEL_SANDBOX` environment variable before `cef.Initialize()`:
+
+```python
+import os
+os.environ["CHROME_DEVEL_SANDBOX"] = "/opt/cef/chrome-sandbox"
+```
+
+**3. Remove cefpython's `--no-sandbox` default.** Because
+`_linux_apply_initialize_defaults` sets it via `setdefault`, passing
+`switches={"no-sandbox": ""}` to `cef.Initialize()` does not override
+it. The default has to be deleted at the source (or pop the key from
+your switches dict after init detection). The simplest path is a small
+local patch in `src/window_utils_linux.pyx` that drops the
+`cmd_switches.setdefault("no-sandbox", "")` line.
+
+After all three steps, Chromium subprocesses should launch under the
+namespace sandbox (no `--no-sandbox` in their argv, no FATAL at
+startup). Verify via the GPU process command line:
+
+```bash
+ps -Af | grep "type=gpu" | grep -v "no-sandbox"
+```
+