diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e68ee96d8..081e7bd60 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -126,39 +126,38 @@ jobs: PY - name: Build JupyterLite site - # jupyterlite-pyodide-kernel is pinned deliberately -- NOT just for - # wasm-ABI matching with the cp312 wheel fetched above, but because - # 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 MVTB's and bdsim's - # existing pins. See the toolbox-maintainer skill's JupyterLite - # version-pinning section for the full story before bumping this. - # Once Safari (and Firefox out-of-flag) ship JSPI, revisit this pin - # across RTB/MVTB/bdsim together. + # jupyterlite-pyodide-kernel is a floor, not an exact pin. It was pinned to + # 0.6.1 (Pyodide 0.27.6) while Safari had no WebAssembly JSPI ("stack + # switching"), which newer Pyodide's run_until_complete() needs: without it + # the kernel crashed, and the workaround (enableRunUntilComplete: false) + # made imports fail intermittently. Safari 27 ships JSPI, and the old + # Pyodide then hung there (the kernel never finished starting). 0.8.7 + # bundles Pyodide 314.0.6 (Python 3.14). There is no wasm ABI to match: + # RTB installs a pure py3-none-any wheel. A browser without JSPI (Safari + # before 27, Firefox before 153) is told so by a banner, which the next + # step adds, instead of being supported by a pin. + # Keep the pyodide version in docs/lite/wasm_check/package.json equal to the + # one this kernel bundles, or that check stops representing the real site. # ipympl is installed here, in the build environment, so that the # jupyter-matplotlib extension is bundled into the site: the notebooks # use %matplotlib ipympl, and without the extension a figure is blank. # (The notebooks install ipympl itself into the in-browser kernel.) run: | - pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl + pip install jupyterlite-core "jupyterlite-pyodide-kernel>=0.8.7" jupyter-server ipympl cd docs/lite && jupyter lite build --output-dir ../build/html/lite + - name: Add the browser capability check to JupyterLite + # a banner, before the kernel starts, if the browser has no WebAssembly JSPI + run: python docs/lite/inject_jspi_check.py docs/build/html/lite + - name: Check JupyterLite in a real browser (install, widgets, animation) # Builds a small site with the wheel built above and one notebook, opens it in # Chromium, and checks that the site installs that wheel (not the last release # from PyPI), draws an ipywidgets slider and an ipympl figure, and that a # trajectory animates while its cell is running. See - # docs/lite/browser_check/. Informational (continue-on-error) until it has - # run green on main, then remove that line so that it blocks the deploy. - continue-on-error: true + # docs/lite/browser_check/. It blocks the deploy: it was informational + # (continue-on-error) until it had run green on main, and while it was, a + # failure after the kernel was unpinned showed as a green job. timeout-minutes: 20 run: | pip install playwright diff --git a/docs/lite/browser_check/README.md b/docs/lite/browser_check/README.md index 9799e4f21..b1c2a5dc1 100644 --- a/docs/lite/browser_check/README.md +++ b/docs/lite/browser_check/README.md @@ -22,7 +22,7 @@ passed on `main`. To run it yourself: ```bash pip install playwright && playwright install chromium -pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl +pip install jupyterlite-core "jupyterlite-pyodide-kernel>=0.8.7" jupyter-server ipympl RTB_PURE_WHEEL=1 python -m build --wheel --outdir docs/lite/pypi python docs/lite/browser_check/check_lite_in_browser.py ``` @@ -31,5 +31,5 @@ python docs/lite/browser_check/check_lite_in_browser.py page when a check fails. The run takes about two minutes: most of it is building the site and downloading Pyodide's packages in the browser. -The kernel version is pinned in `docs.yml` (`jupyterlite-pyodide-kernel==0.6.1`) for -browsers without WebAssembly JSPI; see the comment there before changing it. +The kernel version is a floor in `docs.yml` (`jupyterlite-pyodide-kernel>=0.8.7`); see the +comment there for why it is no longer an exact pin. diff --git a/docs/lite/browser_check/check_lite_in_browser.py b/docs/lite/browser_check/check_lite_in_browser.py index e70f235da..e8fa1128e 100755 --- a/docs/lite/browser_check/check_lite_in_browser.py +++ b/docs/lite/browser_check/check_lite_in_browser.py @@ -22,7 +22,7 @@ Usage:: pip install playwright && playwright install chromium - pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server ipympl + pip install jupyterlite-core "jupyterlite-pyodide-kernel>=0.8.7" jupyter-server ipympl RTB_PURE_WHEEL=1 python -m build --wheel --outdir docs/lite/pypi python docs/lite/browser_check/check_lite_in_browser.py @@ -254,9 +254,11 @@ def main() -> int: errors: list[str] = [] page.on("pageerror", lambda e: errors.append(str(e)[:200])) try: + # no "&reset": a fresh context has no saved workspace to clear, and + # with JupyterLite 0.8 "reset" stops the notebook from opening page.goto( "http://localhost:8890/lab/index.html" - "?path=browser_check.ipynb&reset", + "?path=browser_check.ipynb", wait_until="load", ) passed = run_checks(page, args.timeout, args.min_frames) diff --git a/docs/lite/inject_jspi_check.py b/docs/lite/inject_jspi_check.py new file mode 100644 index 000000000..90d2815a8 --- /dev/null +++ b/docs/lite/inject_jspi_check.py @@ -0,0 +1,56 @@ +"""Add the browser JSPI check to every page of a built JupyterLite site. + +Run after ``jupyter lite build``:: + + python inject_jspi_check.py ../build/html/lite + +It copies ``jspi-check.js`` to the site root and adds a ``' + if "
" not in html: + raise ValueError(f"{index} has no to add the script to") + index.write_text(html.replace("", f"\n {tag}", 1)) + changed.append(index) + return changed + + +if __name__ == "__main__": + if len(sys.argv) != 2: + sys.exit(__doc__) + for path in inject(Path(sys.argv[1])): + print(f"added {SCRIPT} to {path}") diff --git a/docs/lite/jspi-check.js b/docs/lite/jspi-check.js new file mode 100644 index 000000000..576401f64 --- /dev/null +++ b/docs/lite/jspi-check.js @@ -0,0 +1,32 @@ +// Warn, before the Python kernel starts, if the browser cannot run it. +// +// The Pyodide kernel waits for asynchronous work (package installs, the plotting +// backend) using WebAssembly JSPI, JavaScript Promise Integration. Without it the +// kernel does not start or never finishes a cell, and the page just shows a spinner. +// Chrome and Edge have had JSPI for a while, Firefox has it from 153 and Safari from 27. This banner +// says so, instead of leaving the reader to guess. It is added to each JupyterLite +// page by inject_jspi_check.py after the site is built. +(function () { + "use strict"; + if (typeof WebAssembly !== "undefined" && typeof WebAssembly.Suspending === "function") { + return; + } + function show() { + var bar = document.createElement("div"); + bar.setAttribute("role", "alert"); + bar.style.cssText = + "position:fixed;top:0;left:0;right:0;z-index:2147483647;padding:12px 16px;" + + "background:#fff3cd;color:#3d2e00;border-bottom:2px solid #b58900;" + + "font:15px/1.4 system-ui,sans-serif"; + bar.textContent = + "This browser cannot run the Python notebooks here: it lacks WebAssembly " + + "JSPI (JavaScript Promise Integration), so the kernel will hang or fail to start. " + + "Use a current Chrome or Edge, Firefox 153 or later, or Safari 27 or later."; + document.body.appendChild(bar); + } + if (document.body) { + show(); + } else { + document.addEventListener("DOMContentLoaded", show); + } +})(); diff --git a/docs/lite/wasm_check/README.md b/docs/lite/wasm_check/README.md index 511a87364..bfe5ee9e2 100644 --- a/docs/lite/wasm_check/README.md +++ b/docs/lite/wasm_check/README.md @@ -62,12 +62,9 @@ more reliable than the first one. ## Version pinning -`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. +`package.json` pins the `pyodide` npm package to `314.0.6`, the Pyodide (Python 3.14) +that `jupyterlite-pyodide-kernel` 0.8.7 bundles; `docs.yml` installs that kernel as a +floor (`>=0.8.7`). These two have to move together: if the kernel moves to a newer +Pyodide and this pin does not, the check silently stops representing what the real +deployed site runs, and can pass while the site fails, or the reverse. The kernel's +`PYODIDE_VERSION` is in `jupyterlite_pyodide_kernel/constants.py`. diff --git a/docs/lite/wasm_check/package-lock.json b/docs/lite/wasm_check/package-lock.json index 9a3d58c44..970edfa75 100644 --- a/docs/lite/wasm_check/package-lock.json +++ b/docs/lite/wasm_check/package-lock.json @@ -6,15 +6,22 @@ "": { "name": "rtb-wasm-check", "dependencies": { - "pyodide": "0.27.6" + "pyodide": "314.0.6" } }, + "node_modules/@types/emscripten": { + "version": "1.41.6", + "resolved": "https://registry.npmjs.org/@types/emscripten/-/emscripten-1.41.6.tgz", + "integrity": "sha512-uN+9i8bFT5CUcZfyIEYDrSueACEyKGbUs5kC/72DGlZZoinh84sJfVV0i8UOJD1asdzkvLPBRrKs41kZ8MdEXg==", + "license": "MIT" + }, "node_modules/pyodide": { - "version": "0.27.6", - "resolved": "https://registry.npmjs.org/pyodide/-/pyodide-0.27.6.tgz", - "integrity": "sha512-ahiSHHs6iFKl2f8aO1wALINAlMNDLAtb44xCI87GQyH2tLDk8F8VWip3u1ZNIyglGSCYAOSFzWKwS1f9gBFVdg==", - "license": "Apache-2.0", + "version": "314.0.6", + "resolved": "https://registry.npmjs.org/pyodide/-/pyodide-314.0.6.tgz", + "integrity": "sha512-BKDTJyIqFxC4BExLqeRS3f5xvXZIjOt8C3zGLN/Cc7tFxSwvKVhVkchQQ2AGLOtR4YrVOIFxbV8poyDOOmWwxQ==", + "license": "MPL-2.0", "dependencies": { + "@types/emscripten": "^1.41.4", "ws": "^8.5.0" }, "engines": { diff --git a/docs/lite/wasm_check/package.json b/docs/lite/wasm_check/package.json index 83de48a82..1b210a18e 100644 --- a/docs/lite/wasm_check/package.json +++ b/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": "0.27.6" + "pyodide": "314.0.6" } } diff --git a/tests/test_lite_jspi_check.py b/tests/test_lite_jspi_check.py new file mode 100644 index 000000000..cd547ec88 --- /dev/null +++ b/tests/test_lite_jspi_check.py @@ -0,0 +1,51 @@ +"""The JupyterLite browser check is added to every kernel page of a built site.""" + +import importlib.util +from pathlib import Path + +import pytest + +LITE = Path(__file__).parent.parent / "docs" / "lite" + + +@pytest.fixture(scope="module") +def inject(): + spec = importlib.util.spec_from_file_location( + "inject_jspi_check", LITE / "inject_jspi_check.py" + ) + module = importlib.util.module_from_spec(spec) + spec.loader.exec_module(module) + return module + + +def make_site(root: Path, pages=("lab", "notebooks")) -> Path: + for page in pages: + (root / page).mkdir(parents=True) + (root / page / "index.html").write_text( + "\n\n