fix(cef): auto-disable prewarm webview on Wayland/XWayland to prevent X_ConfigureWindow BadWindow crash

[M3gA-Mind]

Summary

• Adds cef_prewarm_enabled(env_override, wayland_display_set) pure predicate that auto-disables the CEF cold-start prewarm webview when WAYLAND_DISPLAY is set and OPENHUMAN_CEF_PREWARM is not explicitly configured.
• The prewarm RunEvent::Ready block is updated to call the predicate, reading WAYLAND_DISPLAY on Linux and logging the reason for disabling (Wayland auto-guard vs. explicit env var).
• Users can opt back in with OPENHUMAN_CEF_PREWARM=1 if CEF subprocess-level X error handling improves.
• Adds 7 unit tests for the pure predicate covering all branches.

Root cause

On Wayland/XWayland (e.g. KDE Plasma 6), the CEF cold-start prewarm child webview (spawn_cef_prewarm) positions itself at (-20000, -20000) off-screen. CEF's render subprocess issues X_ConfigureWindow against that child webview's XWindow before XWayland has fully realized it, producing a fatal BadWindow error. The main-process silent X error handler (install_silent_x_error_handler) does not intercept subprocess errors — each CEF subprocess is a separate process with its own (default, fatal) Xlib error handler.

Setting OPENHUMAN_CEF_PREWARM=0 fully avoids the crash, confirming the prewarm path is the source.

Changes

File	Change
app/src-tauri/src/lib.rs	Add cef_prewarm_enabled() predicate; update RunEvent::Ready prewarm block; add 7 unit tests

Test plan

• cargo test --manifest-path app/src-tauri/Cargo.toml -- prewarm — 10 tests pass (7 new)
• cargo check --manifest-path app/src-tauri/Cargo.toml — clean
• cargo fmt --manifest-path app/src-tauri/Cargo.toml -- --check — clean

Hardware tests (require a Wayland-capable Linux system — not automatable in CI):

• Manual verification on KDE Wayland/XWayland: when WAYLAND_DISPLAY is set, the log shows [cef-prewarm] auto-disabled: WAYLAND_DISPLAY is set and the window stays up indefinitely.
• On X11 (no WAYLAND_DISPLAY): prewarm spawns normally, [cef-prewarm] hidden warmup webview spawned is logged.
• With OPENHUMAN_CEF_PREWARM=1 on Wayland: explicit opt-in is honored, prewarm spawns.

The unit tests for cef_prewarm_enabled() cover all three branches (default, explicit disable, explicit enable) including the Wayland guard, providing the regression coverage required by the acceptance criteria.

Related

Closes #2463

[coderabbitai]

📝 Walkthrough

Walkthrough

This PR adds a decision helper and startup integration to disable the CEF prewarm webview on Linux Wayland/XWayland, addressing crash #2463. The predicate function controls prewarm based on environment override and Wayland detection, with integration into startup and test coverage ensuring the decision matrix is correct.

Changes

CEF prewarm Wayland auto-disable

Layer / File(s)	Summary
CEF prewarm decision helper app/src-tauri/src/lib.rs	cef_prewarm_enabled(env_override, wayland_display_set) implements the decision matrix: explicit disable tokens ("0", "false", "off") disable prewarm; non-disable explicit values enable it; unset env + Wayland disables prewarm by default.
Startup integration and Wayland logging app/src-tauri/src/lib.rs	Startup computes wayland_display_set (Linux only), reads OPENHUMAN_CEF_PREWARM env, gates prewarm spawn via the decision helper, and logs when Wayland auto-disables prewarm with env override guidance.
Unit test coverage for decision matrix app/src-tauri/src/lib.rs	Tests validate defaults, Wayland auto-disable, case-insensitive disable tokens, explicit enable overrides on Wayland, and unrecognized values enabling prewarm.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Possibly related issues

• CEF prewarm webview triggers a fatal X_ConfigureWindow BadWindow crash on Wayland #2463: Directly addresses the BadWindow crash on Wayland by gating the CEF prewarm webview creation, which was the root cause identified when OPENHUMAN_CEF_PREWARM=0 resolved the crash.

Possibly related PRs

• tinyhumansai/openhuman#2103: Shares the same startup-guard pattern using WAYLAND_DISPLAY environment checks in app/src-tauri/src/lib.rs for Linux display-server detection.

Suggested reviewers

• graycyrus

Poem

🐰 A prewarm so eager, yet Wayland said "nay,"
Now a helper decides if to spawn or delay,
With BadWindow crashes now keeping at bay,
The 1×1 webview learns when to play! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title directly describes the main change: auto-disabling CEF prewarm on Wayland/XWayland to prevent a crash, which aligns with the changeset's core objective of adding a decision helper and conditional startup logic.
Linked Issues check	✅ Passed	The PR implements all core coding requirements from issue #2463: adding the cef_prewarm_enabled predicate [#2463], conditional disable logic on Wayland detection [#2463], informational logging for auto-disable [#2463], and comprehensive unit tests [#2463].
Out of Scope Changes check	✅ Passed	All changes are scoped to the prewarm predicate logic, conditional startup flow, and related unit tests in lib.rs, directly addressing the CEF prewarm crash mitigation without unrelated modifications.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

_{Comment @coderabbitai help to get the list of available commands and usage tips.}