fix(docs): pin jupyterlite-pyodide-kernel==0.6.1, matching RTB and bdsim

.github/workflows/docs.yml

@@ -139,8 +139,26 @@ jobs:
           PY
 
       - name: Build JupyterLite site
+        # jupyterlite-pyodide-kernel is pinned deliberately -- NOT for wasm-ABI
+        # matching (MVTB is pure Python, unlike RTB's compiled-extension pin of
+        # the same version, for a different reason). Newer kernel releases bundle
+        # Pyodide >=0.27.7, which turned WebAssembly JSPI ("stack switching") on
+        # by default for run_until_complete(). Browsers without JSPI support
+        # (Safari has none as of 2026-08; Firefox only behind a flag) either
+        # crash the kernel outright or, with the enableRunUntilComplete: false
+        # workaround, turn run_until_complete into a fire-and-forget no-op --
+        # letting a cell's package/import machinery run before an install has
+        # actually finished landing (confirmed live on bdsim: intermittent
+        # ModuleNotFoundError despite a successful-looking install cell).
+        # jupyterlite-pyodide-kernel==0.6.1 bundles Pyodide 0.27.6, genuinely
+        # predating this whole mechanism -- matches RTB's and bdsim's existing
+        # pins. Installing jupyterlite-core directly rather than the jupyterlite
+        # metapackage: the metapackage requires jupyterlite-core>=0.8.1, which
+        # conflicts with this pin's jupyterlite-core<0.7.0 requirement.
+        # Once Safari (and Firefox out-of-flag) ship JSPI, revisit this pin --
+        # and docs/lite/wasm_check/package.json's matching pyodide npm pin.
         run: |
-          pip install jupyterlite-core jupyterlite-pyodide-kernel jupyter-server
+          pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server
           cd docs/lite && jupyter lite build --output-dir ../build/html/lite
 
       - name: Package notebooks zip

docs/lite/wasm_check/README.md

@@ -59,12 +59,15 @@ more reliable than the first one.
 
 ## Version pinning
 
-`package.json` pins the `pyodide` npm package to the same version confirmed
-working in real-browser testing (`314.0.3`, corresponding to the Pyodide runtime
-that `jupyterlite-pyodide-kernel` currently bundles). If that drifts out of sync
-with what the real deployed site actually uses, this check could pass while the
-real site fails, or vice versa — see the toolbox-maintainer notes on JupyterLite
-version pairing for why that pairing matters and isn't self-healing.
+`package.json` pins the `pyodide` npm package to `0.27.6`, matching
+`docs.yml`'s deliberate `jupyterlite-pyodide-kernel==0.6.1` pin (see that
+workflow's own comment for the full reasoning: newer kernel releases bundle a
+JSPI-dependent Pyodide that either crashes or silently races on browsers
+without JSPI support, e.g. Safari as of 2026-08). These two pins have to move
+together — if one changes without the other, this check silently stops
+representing what the real deployed site actually runs, which could let it
+pass while the real site fails, or vice versa. Once that kernel pin is
+revisited, this one needs updating in the same change.
 
 ## Reusing this for another toolbox
 

docs/lite/wasm_check/package.json

@@ -4,6 +4,6 @@
   "type": "module",
   "description": "Real-Pyodide (Node.js) dependency-completeness check for the JupyterLite install path -- see check_pyodide_install.mjs and README.md.",
   "dependencies": {
-    "pyodide": "314.0.3"
+    "pyodide": "0.27.6"
   }
 }