docs(linux): correct version-tagged comments with actual upstream history

Three comments in src/cefpython.pyx and src/window_info.pyx carried
"CEF 123+" or "CEF 146+" attributions that were imprecise (added by
the user during cefpython 123/146 bring-up rather than reflecting an
actual upstream behavior change at those versions).  Replaced each
with a comment grounded in the real upstream commit and the actual
mechanism observed.

- CreateBrowserSync: CefCurrentlyOn(TID_UI) comment — the public API
  has always returned false + LOG(WARNING) when no task runner is
  registered (libcef/common/task_impl.cc:13).  Drop the "CEF 146+" tag
  and explain why cefpython's defer-until-OnContextInitialized flow
  reaches this code before BrowserThread::UI is established.

- CreateBrowserSync: OnContextInitialized defer comment — the wait
  requirement comes from CEF commit 691c9c2 ("Wait for
  CefBrowserContext initialization", 2021-04-14, issue #2969), not
  CEF 123.  Symptom is the renderer's first IPC message
  (blink.mojom.WidgetHost) being rejected before host bindings are
  wired.  Strategy section now documents that Linux skips the manual
  pump deliberately to keep Initialize() non-blocking — empirical
  testing on current cefpython shows the pump *does* fire
  OnContextInitialized in 2-3s on both Ozone X11 and Wayland, so the
  historical "needs gtk_main()" claim is no longer accurate, but we
  still skip to avoid the latency.

- window_info.pyx: drop the four duplicate
  "# CEF 123+: must request Alloy runtime" lines and consolidate into
  one function-level note in SetCefWindowInfo.  The runtime_style
  field on cef_window_info_t actually arrived in CEF commit dca0435d2
  ("chrome: Add support for Alloy style browsers and windows", issue
  #3681, 2024-04-17), first shipping in CEF branch 6422
  (~Chromium 125, May 2024) — well after CEF 123, where the field
  did not exist.  The note also explains why Alloy style is required:
  chrome bootstrap default (since branch 6478) makes windowed parent
  windows default to Chrome style, which can't be parented via
  SetAsChild and would change the callback model.

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

Author: linesight

src/cefpython.pyx

@@ -676,12 +676,18 @@ def Initialize(applicationSettings=None, commandLineSwitches=None, **kwargs):
     # Use a generous ceiling (30s) for CI environments where utility
     # subprocesses (storage service) crash and delay context initialization.
     if ret:
-        # On Linux, skip this pump entirely: the Ozone X11 backend needs
-        # gtk_main() (a blocking GLib main loop) running before
-        # OnContextInitialized can fire.  The external caller (hello_world.py,
-        # test harnesses) must enter gtk_main() immediately after Initialize()
-        # and drive the loop via the GLib timer callback.
-        # On Windows/macOS, pump up to 30 s as before.
+        # On Linux, skip this pump entirely.  Empirical testing shows manual
+        # CefDoMessageLoopWork() *does* fire OnContextInitialized within 2-3s
+        # on both Ozone X11 and Ozone Wayland in the current cefpython
+        # configuration, so the historical "needs gtk_main()" claim is no
+        # longer accurate — but we still skip it deliberately to keep
+        # Initialize() non-blocking on Linux.  The user enters
+        # cef.MessageLoop() (gtk_main on X11, GLib loop on Wayland) right
+        # after Initialize() returns; OnContextInitialized fires there and
+        # BrowserProcessHandler_OnContextInitialized drains
+        # g_pending_browsers.  This avoids a 2-3s startup latency hit on
+        # the common case and a 30s block in edge cases.
+        # On Windows/macOS, pump up to 30s as before.
         IF UNAME_SYSNAME != "Linux":
             for _ in range(3000):
                 with nogil:
@@ -731,11 +737,34 @@ def CreateBrowserSync(windowInfo=None,
     # plus its own thread checks internally, so a Python-side assert
     # would only catch the same condition with a worse error message.
 
-    # Defer browser creation until OnContextInitialized fires inside MessageLoop.
-    # In CEF 123+, browser creation before OnContextInitialized causes
-    # blink.mojom.WidgetHost rejection and renderer shows no content.
-    # Initialize() pumps the loop for up to 30s; if still not initialized
-    # (e.g. slow CI), pump an additional 30s before giving up.
+    # Defer browser creation until OnContextInitialized fires.
+    #
+    # CefBrowserContext initialization is asynchronous: it is not finished
+    # when CefInitialize() returns, especially when external_message_pump
+    # is in use (our default — see _linux_apply_initialize_defaults).  The
+    # OnContextInitialized callback is the documented signal that the
+    # browser context is ready (see upstream CEF commit 691c9c2 "Wait for
+    # CefBrowserContext initialization", 2021-04-14, issue #2969 — added
+    # the explicit wait when Chrome runtime introduced async Profile init).
+    #
+    # Calling CefBrowserHost::CreateBrowserSync before that point lets the
+    # renderer come up before its host bindings are wired, and the
+    # browser-process side then rejects the renderer's first IPC message
+    # with a "blink.mojom.WidgetHost" / "Message N rejected by interface"
+    # mojo error.  The visible symptom is a blank page.
+    #
+    # Strategy:
+    #   * Windows / macOS: cefpython.Initialize() already pumps up to 30s
+    #     waiting for OnContextInitialized.  If a caller reaches
+    #     CreateBrowserSync earlier anyway (slow CI, custom Initialize
+    #     override), pump another 30s here before giving up.
+    #   * Linux (X11 and Wayland Ozone backends): skip the local pump,
+    #     mirroring Initialize().  The deferred path always works: queue
+    #     the request and let BrowserProcessHandler_OnContextInitialized
+    #     drain it once cef.MessageLoop() starts the GLib loop.
+    # When this falls through still uninitialised, queue the request in
+    # g_pending_browsers for the OnContextInitialized handler to drain
+    # once the loop is actually running.
     if not g_context_initialized:
         Debug("CreateBrowserSync(): OnContextInitialized not yet received,"
               " pumping message loop")

src/window_info.pyx

@@ -8,6 +8,26 @@ cdef void SetCefWindowInfo(
         CefWindowInfo& cefWindowInfo,
         WindowInfo windowInfo
         ) except *:
+    # Note on runtime_style = CEF_RUNTIME_STYLE_ALLOY (set below in every
+    # windowed branch):
+    #
+    # The cef_window_info_t.runtime_style field was added in CEF
+    # commit dca0435d2 "chrome: Add support for Alloy style browsers
+    # and windows" (issue #3681, 2024-04-17, first shipping in CEF
+    # branch 6422 / Chromium 125).  See the enum doc in
+    # include/internal/cef_types_runtime.h: Chrome style provides the
+    # full Chrome UI; Alloy style provides the content-layer view with
+    # additional client callbacks and supports windowless rendering.
+    #
+    # Since the chrome bootstrap (the default for CEF builds since
+    # branch 6478 / Chromium 125) makes windowed parent windows default
+    # to Chrome style, cefpython must opt back into Alloy style
+    # explicitly.  Without it, SetAsChild() would get a Chrome-style
+    # Views window that can't be parented into the host GTK/Qt window,
+    # and the LifeSpanHandler / RequestHandler / etc. callbacks
+    # cefpython exposes would not fire as expected.  Off-screen
+    # rendering is documented to always use Alloy style anyway, but the
+    # field is harmless to set there too.
     if not windowInfo.windowType:
         raise Exception("WindowInfo: windowType is not set")
 
@@ -42,7 +62,6 @@ cdef void SetCefWindowInfo(
             cefWindowInfo.SetAsChild(
                     <CefWindowHandle>windowInfo.parentWindowHandle,
                     windowRect)
-            # CEF 123+: must request Alloy runtime for native windowed rendering.
             cefWindowInfo.runtime_style = CEF_RUNTIME_STYLE_ALLOY
         ELIF UNAME_SYSNAME == "Darwin":
             x = int(windowInfo.windowRect[0])
@@ -63,7 +82,6 @@ cdef void SetCefWindowInfo(
             cefWindowInfo.SetAsChild(
                     <CefWindowHandle>windowInfo.parentWindowHandle,
                     windowRect)
-            # CEF 123+: must request Alloy runtime for native windowed rendering.
             cefWindowInfo.runtime_style = CEF_RUNTIME_STYLE_ALLOY
 
     # POPUP WINDOW - Windows only
@@ -73,7 +91,6 @@ cdef void SetCefWindowInfo(
             cefWindowInfo.SetAsPopup(
                     <CefWindowHandle>windowInfo.parentWindowHandle,
                     windowName)
-            # CEF 123+: must request Alloy runtime for native windowed rendering.
             cefWindowInfo.runtime_style = CEF_RUNTIME_STYLE_ALLOY
 
     if windowInfo.windowType == "offscreen":