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
33 changes: 14 additions & 19 deletions .github/workflows/docs.yml
Original file line number Diff line number Diff line change
Expand Up @@ -141,28 +141,23 @@ 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.
# 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. Safari 27
# ships JSPI, and the old Pyodide then misbehaved there (the kernel never
# finished starting). A browser with no JSPI (Safari before 27; Firefox
# before 153) is now told so by a banner, added below, not supported by a pin.
# Installing jupyterlite-core directly rather than the jupyterlite metapackage.
# Keep docs/lite/wasm_check/package.json's pyodide in step with the Pyodide
# that the kernel bundles (0.8.7 bundles 314.0.6).
run: |
pip install jupyterlite-core "jupyterlite-pyodide-kernel==0.6.1" jupyter-server
pip install jupyterlite-core "jupyterlite-pyodide-kernel>=0.8.7" jupyter-server
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

# Real browsers, pre-deploy: gates publishing, so skipped for pull_request
# (which only builds). The Node/Pyodide check above covers dependency
# drift; this covers JupyterLab itself starting (before any kernel exists)
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 @@ -59,15 +59,12 @@ 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 that
`jupyterlite-pyodide-kernel` 0.8.7 bundles (`docs.yml` requires `>=0.8.7`). The two have
to move together: if one changes without the other, this check silently stops
representing what the real deployed site runs, which could let it pass while the real
site fails, or vice versa. When `docs.yml`'s kernel floor is raised to a release that
bundles a different Pyodide, update this pin in the same change.

## Reusing this for another toolbox

Expand Down
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