Create browser from OnContextInitialized instead of polling for context init

Under CEF's Chrome runtime the browser context initializes asynchronously:
CefBrowserProcessHandler::OnContextInitialized() fires after the message loop
starts, not when CefInitialize() returns (upstream CEF issue #2969). The
Chrome runtime became the only runtime after the Alloy runtime was removed in
CEF M128, so a browser can no longer be created immediately after
cef.Initialize() -- doing so brings the renderer up before its host bindings
are wired and the page renders blank.

Replace the polling / deferred-creation workaround in CefInitialize() and
CreateBrowserSync() with the pattern CEF's own cefsimple sample uses: create
the browser from an "OnContextInitialized" global client callback, registered
before cef.Initialize(). CreateBrowserSync() stays synchronous and now raises
a clear, actionable error when called before the context is initialized
instead of silently rendering a blank page.

- Expose "OnContextInitialized" as a global client callback
  (SetGlobalClientCallback), invoked from the browser process handler.
- Migrate the unit-test harness (main_test, osr_test, issue517) and all
  examples. Windowed GUI examples embed the browser only once both the window
  is realized and the context is initialized (event-driven, no polling).

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

Author: linesight

examples/gtk2.py

@@ -33,11 +33,28 @@
 MESSAGE_LOOP_CEF = 2  # Pass --message-loop-cef flag to script on Linux
 g_message_loop = None
 
+# Under CEF's Chrome runtime the browser context initializes asynchronously,
+# so a browser can only be created after OnContextInitialized has fired. These
+# module-level helpers coordinate that: embed_browser() defers itself until the
+# context is ready, and the callback below runs any deferred embed.
+g_context_initialized = False
+g_pending_embed = None
+
+
+def _on_context_initialized():
+    global g_context_initialized
+    g_context_initialized = True
+    if g_pending_embed is not None:
+        g_pending_embed()
+
 
 def main():
     check_versions()
     sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
     configure_message_loop()
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized",
+                                _on_context_initialized)
     cef.Initialize()
     gobject.threads_init()
     Gtk2Example()
@@ -108,6 +125,13 @@ def __init__(self):
             gobject.timeout_add(10, self.on_timer)
 
     def embed_browser(self):
+        global g_pending_embed
+        if not g_context_initialized:
+            # Chrome runtime initializes the browser context asynchronously;
+            # embed once OnContextInitialized fires (see main()).
+            g_pending_embed = self.embed_browser
+            return
+        g_pending_embed = None
         windowInfo = cef.WindowInfo()
         size = self.main_window.get_size()
         rect = [0, 0, size[0], size[1]]

examples/gtk3.py

@@ -34,6 +34,21 @@
     from gi.repository import GdkX11
 
 
+# Under CEF's Chrome runtime the browser context initializes asynchronously,
+# so a browser can only be created after OnContextInitialized has fired. These
+# module-level helpers coordinate that: embed_browser() defers itself until the
+# context is ready, and the callback below runs any deferred embed.
+g_context_initialized = False
+g_pending_embed = None
+
+
+def _on_context_initialized():
+    global g_context_initialized
+    g_context_initialized = True
+    if g_pending_embed is not None:
+        g_pending_embed()
+
+
 def main():
     print("[gkt3.py] CEF Python {ver}".format(ver=cef.__version__))
     print("[gkt3.py] Python {ver} {arch}".format(
@@ -47,6 +62,9 @@ def main():
         # > Python[57738:d07] _createMenuRef called with existing principal
         # > MenuRef already associated with menu
         sys.excepthook = cef.ExceptHook  # To shutdown CEF processes on error
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized",
+                                _on_context_initialized)
     cef.Initialize()
     app = Gtk3Example()
     SystemExit(app.run(sys.argv))
@@ -112,6 +130,13 @@ def on_activate(self, *_):
         self.window.resize(*self.window.get_default_size())
 
     def embed_browser(self):
+        global g_pending_embed
+        if not g_context_initialized:
+            # Chrome runtime initializes the browser context asynchronously;
+            # embed once OnContextInitialized fires (see main()).
+            g_pending_embed = self.embed_browser
+            return
+        g_pending_embed = None
         window_info = cef.WindowInfo()
         # TODO: on Mac pass rect[x, y, width, height] to SetAsChild
         window_info.SetAsChild(self.get_handle())

examples/hello_world.py

@@ -18,9 +18,20 @@ def main():
     check_versions()
     sys.excepthook = cef.ExceptHook  # shut down all CEF processes on error
     settings = {}
+
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so the browser must be created from the
+        # OnContextInitialized callback rather than immediately after
+        # cef.Initialize(). This matches CEF's cefsimple sample.
+        cef.CreateBrowserSync(url="https://www.google.com/",
+                              window_title="Hello World!")
+
+    # Register the callback before cef.Initialize(): OnContextInitialized can
+    # fire during cef.Initialize() itself.
+    cef.SetGlobalClientCallback("OnContextInitialized",
+                                on_context_initialized)
     cef.Initialize(settings=settings)
-    cef.CreateBrowserSync(url="https://www.google.com/",
-                          window_title="Hello World!")
     cef.MessageLoop()
     cef.Shutdown()
 

examples/pysdl2.py

@@ -104,6 +104,18 @@ def die(msg):
             "       To install type: pip install pyobjc")
 
 
+# Under CEF's Chrome runtime the browser context initializes asynchronously,
+# so the (off-screen) browser can only be created after OnContextInitialized
+# has fired. This flag is set by the callback registered before
+# cef.Initialize().
+g_context_initialized = False
+
+
+def _on_context_initialized():
+    global g_context_initialized
+    g_context_initialized = True
+
+
 def main():
     """
     Parses input, initializes everything and then runs the main loop of the
@@ -193,6 +205,9 @@ def main():
         # Tweaking OSR performance (Issue #240)
         "windowless_frame_rate": frameRate
     }
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized",
+                                _on_context_initialized)
     cef.Initialize(settings={"windowless_rendering_enabled": True},
                    switches=switches)
 
@@ -296,6 +311,14 @@ def _detect_device_scale_factor(window, renderer):
     # RenderHandler instances, creating SDL windows for popups lazily.
     renderHandler = MetaRenderHandler(renderer, width, height - headerHeight,
                                       deviceScaleFactor, rendererFlags)
+    # Create the browser instance. Unlike the windowed examples (which embed
+    # the browser from an event callback), this linear off-screen example
+    # creates it inline, so ensure the CEF context has finished initializing
+    # first. On most platforms it already has by this point (it initializes
+    # during cef.Initialize()); otherwise let the message loop run until
+    # OnContextInitialized fires.
+    while not g_context_initialized:
+        cef.MessageLoopWork()
     # Create the browser instance
     browser = cef.CreateBrowserSync(window_info,
                                     url="https://www.google.com/",

examples/qt.py

@@ -74,6 +74,21 @@
 HEIGHT = 600
 
 
+# Under CEF's Chrome runtime the browser context initializes asynchronously,
+# so a browser can only be created after OnContextInitialized has fired. These
+# module-level helpers coordinate that: embedBrowser() defers itself until the
+# context is ready, and the callback below runs any deferred embed.
+g_context_initialized = False
+g_pending_embed = None
+
+
+def _on_context_initialized():
+    global g_context_initialized
+    g_context_initialized = True
+    if g_pending_embed is not None:
+        g_pending_embed()
+
+
 def main():
     check_versions()
     sys.excepthook = cef.ExceptHook  # To shutdown all CEF processes on error
@@ -92,6 +107,9 @@ def main():
         "devtools": True,
     }
 
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized",
+                                _on_context_initialized)
     cef.Initialize(settings)
     app = CefApplication(sys.argv)
     main_window = MainWindow()
@@ -248,6 +266,13 @@ def focusOutEvent(self, event):
             self.browser.SetFocus(False)
 
     def embedBrowser(self):
+        global g_pending_embed
+        if not g_context_initialized:
+            # Chrome runtime initializes the browser context asynchronously;
+            # embed once OnContextInitialized fires (see main()).
+            g_pending_embed = self.embedBrowser
+            return
+        g_pending_embed = None
         if LINUX and PYQT5:
             # On Linux with PyQt5, QX11EmbedContainer is gone; the Qt-native
             # equivalent is to host CEF in a QWindow (hidden_window) wrapped in

examples/screenshot.py

@@ -97,8 +97,15 @@ def main():
         # Tweaking OSR performance (Issue #240)
         "windowless_frame_rate": 30,  # Default frame rate in CEF is 30
     }
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so create the browser here rather than right after
+        # cef.Initialize().
+        create_browser(browser_settings)
+
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized", on_context_initialized)
     cef.Initialize(settings=settings, switches=switches)
-    create_browser(browser_settings)
     cef.MessageLoop()
     cef.Shutdown()
     print("[screenshot.py] Opening screenshot with default application")

examples/snippets/cookies.py

@@ -7,13 +7,19 @@
 
 
 def main():
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so create the browser here rather than right after
+        # cef.Initialize().
+        browser = cef.CreateBrowserSync(
+            url="https://www.google.com/",
+            window_title="Cookies")
+        browser.SetClientHandler(LoadHandler())
+
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized", on_context_initialized)
     cef.Initialize()
-    browser = cef.CreateBrowserSync(
-        url="https://www.google.com/",
-        window_title="Cookies")
-    browser.SetClientHandler(LoadHandler())
     cef.MessageLoop()
-    del browser
     cef.Shutdown()
 
 

examples/snippets/crossdomain_bindings.py

@@ -37,17 +37,24 @@
 
 def main():
     print(__doc__)
+
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so create the browser here rather than right after
+        # cef.Initialize().
+        browser = cef.CreateBrowserSync(
+            url=TARGET_URL,
+            window_title="Cross-domain JS binding test")
+        handler = CrossDomainHandler(browser)
+        browser.SetClientHandler(handler)
+        bindings = cef.JavascriptBindings()
+        bindings.SetFunction("OnTargetPageReady", handler["_OnTargetPageReady"])
+        browser.SetJavascriptBindings(bindings)
+
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized", on_context_initialized)
     cef.Initialize()
-    browser = cef.CreateBrowserSync(url=TARGET_URL,
-                                    window_title="Cross-domain JS binding test")
-    handler = CrossDomainHandler(browser)
-    browser.SetClientHandler(handler)
-    bindings = cef.JavascriptBindings()
-    bindings.SetFunction("OnTargetPageReady", handler["_OnTargetPageReady"])
-    browser.SetJavascriptBindings(bindings)
     cef.MessageLoop()
-    del handler
-    del browser
     cef.Shutdown()
 
 

examples/snippets/javascript_bindings.py

@@ -38,16 +38,22 @@
 
 
 def main():
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so create the browser here rather than right after
+        # cef.Initialize().
+        browser = cef.CreateBrowserSync(url=cef.GetDataUrl(g_htmlcode),
+                                        window_title="Javascript Bindings")
+        browser.SetClientHandler(LoadHandler())
+        bindings = cef.JavascriptBindings()
+        bindings.SetFunction("py_function", py_function)
+        bindings.SetFunction("py_callback", py_callback)
+        browser.SetJavascriptBindings(bindings)
+
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized", on_context_initialized)
     cef.Initialize()
-    browser = cef.CreateBrowserSync(url=cef.GetDataUrl(g_htmlcode),
-                                    window_title="Javascript Bindings")
-    browser.SetClientHandler(LoadHandler())
-    bindings = cef.JavascriptBindings()
-    bindings.SetFunction("py_function", py_function)
-    bindings.SetFunction("py_callback", py_callback)
-    browser.SetJavascriptBindings(bindings)
     cef.MessageLoop()
-    del browser
     cef.Shutdown()
 
 

examples/snippets/javascript_errors.py

@@ -40,10 +40,17 @@
 
 
 def main():
+    def on_context_initialized():
+        # Under CEF's Chrome runtime the browser context initializes
+        # asynchronously, so create the browser here rather than right after
+        # cef.Initialize().
+        browser = cef.CreateBrowserSync(url=cef.GetDataUrl(g_htmlcode),
+                                        window_title="Javascript Errors")
+        browser.SetClientHandler(DisplayHandler())
+
+    # Register before cef.Initialize(); OnContextInitialized may fire during it.
+    cef.SetGlobalClientCallback("OnContextInitialized", on_context_initialized)
     cef.Initialize()
-    browser = cef.CreateBrowserSync(url=cef.GetDataUrl(g_htmlcode),
-                                    window_title="Javascript Errors")
-    browser.SetClientHandler(DisplayHandler())
     cef.MessageLoop()
     cef.Shutdown()