diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml index b02b70e4..2792bebb 100644 --- a/.github/workflows/docs.yml +++ b/.github/workflows/docs.yml @@ -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) diff --git a/docs/lite/inject_jspi_check.py b/docs/lite/inject_jspi_check.py new file mode 100644 index 00000000..90d2815a --- /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 00000000..576401f6 --- /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 960ac5d7..12dd2da0 100644 --- a/docs/lite/wasm_check/README.md +++ b/docs/lite/wasm_check/README.md @@ -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 diff --git a/docs/lite/wasm_check/package-lock.json b/docs/lite/wasm_check/package-lock.json index 8084d3b4..7def68e3 100644 --- a/docs/lite/wasm_check/package-lock.json +++ b/docs/lite/wasm_check/package-lock.json @@ -6,15 +6,22 @@ "": { "name": "mvtb-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 9d2767d3..ab564d91 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 00000000..cd547ec8 --- /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