Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 20 additions & 21 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
6 changes: 3 additions & 3 deletions docs/lite/browser_check/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
```
Expand All @@ -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.
6 changes: 4 additions & 2 deletions docs/lite/browser_check/check_lite_in_browser.py
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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)
Expand Down
56 changes: 56 additions & 0 deletions docs/lite/inject_jspi_check.py
Original file line number Diff line number Diff line change
@@ -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 ``<script>`` tag for it to the
``<head>`` of each page that starts the kernel. The script shows a banner if the
browser has no WebAssembly JSPI, which the Pyodide kernel needs. Safe to run twice.
"""

import shutil
import sys
from pathlib import Path

SCRIPT = "jspi-check.js"

# the pages JupyterLite generates that can run a kernel
PAGES = ["lab", "notebooks", "tree", "repl", "consoles", "edit", "doc"]


def inject(site: Path) -> list[Path]:
"""Put the check into a built JupyterLite site.

:param site: the site's root, the folder holding ``lab/`` and ``jupyter-lite.json``
:returns: the pages that were changed
:raises FileNotFoundError: if there is no page to change, so the check cannot
silently be missing from a deployed site
"""
site = Path(site)
pages = [
site / p / "index.html" for p in PAGES if (site / p / "index.html").exists()
]
if not pages:
raise FileNotFoundError(f"no JupyterLite pages found under {site}")
shutil.copy(Path(__file__).with_name(SCRIPT), site / SCRIPT)

changed = []
for index in pages:
html = index.read_text()
if SCRIPT in html:
continue
# relative to the page, which is one folder below the site root
tag = f'<script src="../{SCRIPT}"></script>'
if "<head>" not in html:
raise ValueError(f"{index} has no <head> to add the script to")
index.write_text(html.replace("<head>", f"<head>\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}")
32 changes: 32 additions & 0 deletions docs/lite/jspi-check.js
Original file line number Diff line number Diff line change
@@ -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);
}
})();
15 changes: 6 additions & 9 deletions docs/lite/wasm_check/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
17 changes: 12 additions & 5 deletions docs/lite/wasm_check/package-lock.json

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

2 changes: 1 addition & 1 deletion docs/lite/wasm_check/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -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"
}
}
51 changes: 51 additions & 0 deletions tests/test_lite_jspi_check.py
Original file line number Diff line number Diff line change
@@ -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(
"<html>\n<head>\n<title>x</title></head>"
)
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 (
'<script src="../jspi-check.js"></script>'
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)
Loading