From 82cfd43f75a80b89a55990fe0bb1ffe963d6a718 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 08:22:41 +1000 Subject: [PATCH 1/4] docs(lite): add the JSPI browser check, not yet switched on Ported from bdsim (PR 259). jspi-check.js shows a banner before the kernel starts if the browser has no WebAssembly JSPI, and inject_jspi_check.py adds it to each page of a built JupyterLite site; both are tested. It is not run by docs.yml yet. RTB's site is still pinned to kernel 0.6.1 (Pyodide 0.27.6), which works without JSPI, so the banner would wrongly warn Safari 26 and Firefox before 153 today. The CI step that enables it belongs in the change that unpins the kernel (Issue 941). Co-Authored-By: Claude Sonnet 5.5 --- docs/lite/inject_jspi_check.py | 56 ++++++++++++++++++++++++++++++++++ docs/lite/jspi-check.js | 32 +++++++++++++++++++ tests/test_lite_jspi_check.py | 51 +++++++++++++++++++++++++++++++ 3 files changed, 139 insertions(+) create mode 100644 docs/lite/inject_jspi_check.py create mode 100644 docs/lite/jspi-check.js create mode 100644 tests/test_lite_jspi_check.py 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/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\nx" + ) + return root + + +def test_script_added_to_each_page(inject, tmp_path): + site = make_site(tmp_path) + changed = inject.inject(site) + assert len(changed) == 2 + assert (site / "jspi-check.js").exists() + for page in ("lab", "notebooks"): + assert ( + '' + in (site / page / "index.html").read_text() + ) + + +def test_running_twice_adds_it_once(inject, tmp_path): + site = make_site(tmp_path) + inject.inject(site) + assert inject.inject(site) == [] + assert (site / "lab" / "index.html").read_text().count("jspi-check.js") == 1 + + +def test_empty_site_is_an_error(inject, tmp_path): + with pytest.raises(FileNotFoundError): + inject.inject(tmp_path) From d997a4c9ef01f09d3d4cc6950f39f78652b5f11d Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 08:40:06 +1000 Subject: [PATCH 2/4] ci(docs): unpin the JupyterLite kernel and switch on the browser banner jupyterlite-pyodide-kernel was pinned to 0.6.1 (Pyodide 0.27.6) because Safari had no WebAssembly JSPI. Safari 27 ships JSPI, and the old Pyodide then hangs there (found in bdsim, Issue 941). It is now a floor, >=0.8.7, which bundles Pyodide 314.0.6 (Python 3.14). RTB installs a pure py3-none-any wheel, so there is no wasm ABI to match. A browser without JSPI gets the banner added in the previous commit, run by a new docs.yml step after the site build. The Node install check moves to pyodide 314.0.6 with its lockfile; with the current pure wheel it passes (import, fkine, analytic IK, inline animation). Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/docs.yml | 35 +++++++++---------- docs/lite/browser_check/README.md | 6 ++-- .../browser_check/check_lite_in_browser.py | 2 +- docs/lite/wasm_check/README.md | 15 ++++---- docs/lite/wasm_check/package-lock.json | 17 ++++++--- docs/lite/wasm_check/package.json | 2 +- 6 files changed, 40 insertions(+), 37 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index e68ee96d8..b142920be 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -126,31 +126,30 @@ 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 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..4c54a0b23 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 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" } } From c0e816c53c1283986619794770372d5451b58413 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 09:08:11 +1000 Subject: [PATCH 3/4] fix(docs): open the browser-check notebook without 'reset' With JupyterLite 0.8 (kernel 0.8.7), lab/index.html?path=...&reset shows the Launcher and never opens the notebook, so the check timed out waiting for it. Without '&reset' the notebook opens in about 2 seconds. A fresh browser context has no saved workspace to reset, so nothing is lost. The whole check now passes locally on Pyodide 314.0.6 in Chromium. Co-Authored-By: Claude Sonnet 5.5 --- docs/lite/browser_check/check_lite_in_browser.py | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/lite/browser_check/check_lite_in_browser.py b/docs/lite/browser_check/check_lite_in_browser.py index 4c54a0b23..e8fa1128e 100755 --- a/docs/lite/browser_check/check_lite_in_browser.py +++ b/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) From 6c7e8a8a6fa57dd794696e57e6121b42bb5b6bd0 Mon Sep 17 00:00:00 2001 From: Peter Corke Date: Wed, 18 Nov 2026 11:50:01 +1000 Subject: [PATCH 4/4] ci(docs): make the real-browser check block the deploy It was informational until it had run green on main, and it has: on main with kernel 0.6.1, and on this branch with 0.8.7. While informational, its failure on the first run of this branch showed as a green job and was only found by reading the log. Co-Authored-By: Claude Sonnet 5.5 --- .github/workflows/docs.yml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b142920be..081e7bd60 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -155,9 +155,9 @@ jobs: # 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