Skip to content

docs: let JupyterLite use the current Pyodide kernel, and warn when the browser has no JSPI - #259

Merged
petercorke merged 4 commits into
mainfrom
fix/jupyterlite-unpin-kernel
Nov 16, 2026
Merged

petercorke merged 4 commits into
mainfrom
fix/jupyterlite-unpin-kernel

Conversation

@petercorke

Copy link
Copy Markdown
Owner

Problem

After 1.5.0, the JupyterLite notebooks fail in Safari 27.2 (macOS): two-tanks hangs at sim.run, every notebook with an ANIMATION block does the same, temperature-control-lab fails on import control, and the kernel indicator just spins. Chrome and Firefox are fine.

Cause

The site was built with jupyterlite-pyodide-kernel==0.6.1 (Pyodide 0.27.6), pinned because Safari had no WebAssembly JSPI and newer Pyodide needs it. Safari 27 has JSPI, and the old Pyodide now hangs there. Confirmed on a Safari private window: the deployed site hangs, a local build with kernel 0.8.7 runs.

Change

  • docs.yml: kernel pin ==0.6.1 becomes >=0.8.7, and the comment explaining the pin is rewritten.
  • A banner, shown before the kernel starts, when WebAssembly.Suspending is missing: the reader is told to use Chrome or Edge, Firefox 153 or later, or Safari 27 or later, instead of watching a spinner. docs/lite/jspi-check.js is added to each built JupyterLite page by docs/lite/inject_jspi_check.py, run as a new step in docs.yml. It fails the build if it finds no pages. Three tests.

Tested

Browser Result
Safari 27.2, normal and private window two-tanks runs, import control works (local 0.8.7 build)
Safari 27.2, deployed site (old pin) hangs in sim.run
Safari 26 banner shown
Chrome incognito, Firefox 159, Waterfox 6.7.5 work

Not yet tested: the CI-built site on this PR's deploy, which also runs the injection step in CI (I ran it only locally). Please re-check Safari 27 on it.

Not in this PR

RTB has the same kernel pin and will fail the same way. The shared bootstrap template in rvc-ecosystem could carry an in-notebook version of the check, but a kernel that crashes outright never reaches a cell, so the page-level banner is the primary one.

🤖 Generated with Claude Code

petercorke and others added 4 commits November 16, 2026 14:01
…has JSPI

The jupyterlite-pyodide-kernel pin (0.6.1, Pyodide 0.27.6) existed because Safari
lacked WebAssembly JSPI. Safari 27 has it, and the old Pyodide now hangs there:
sim.run never finished and `import control` failed in the notebooks. The current
kernel (0.8.7) runs them in Safari 27.2 and Chrome.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Without JSPI the Pyodide kernel hangs or never starts, which shows only as a
spinner. A script added to each built JupyterLite page now shows a banner naming
the problem and the browsers that work.

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
@codacy-production

codacy-production Bot commented Nov 16, 2026 •

Copy link
Copy Markdown

Up to standards ✅

🟢 Issues 0 issues

Results:
0 new issues

View in Codacy

🟢 Metrics 19 complexity · 0 duplication

Metric Results
Complexity 19
Duplication 0

View in Codacy

🟢 Coverage ∅ diff coverage

Metric Results
Coverage variation Report missing for 5ad3f971
Diff coverage ✅ ∅ diff coverage

View coverage diff in Codacy

Coverage variation details
Coverable lines Covered lines Coverage
Common ancestor commit (5ad3f97) Report Missing Report Missing Report Missing
Head commit (eea7a12) 6120 5132 83.86%

Coverage variation is the difference between the coverage for the head and common ancestor commits of the pull request branch: <coverage of head commit> - <coverage of common ancestor commit>

Diff coverage details
Coverable lines Covered lines Diff coverage
Pull request (#259) 0 0 ∅ (not applicable)

Diff coverage is the percentage of lines that are covered by tests out of the coverable lines that the pull request added or modified: <covered lines added or modified>/<coverable lines added or modified> * 100%

1 Codacy didn't receive coverage data for the commit, or there was an error processing the received data. Check your integration for errors and validate that your coverage setup is correct.

NEW Get contextual insights on your PRs based on Codacy's metrics, along with PR and Jira context, without leaving GitHub. Enable AI reviewer
TIP This summary will be updated as you push new changes.

@petercorke petercorke changed the title fix: let JupyterLite use the current Pyodide kernel, and warn when the browser has no JSPI docs: let JupyterLite use the current Pyodide kernel, and warn when the browser has no JSPI Nov 16, 2026
@codecov

codecov Bot commented Nov 16, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 83.85%. Comparing base (38908f9) to head (eea7a12).
⚠️ Report is 1 commits behind head on main.

Additional details and impacted files
@@           Coverage Diff           @@
##             main     #259   +/-   ##
=======================================
  Coverage   83.85%   83.85%           
=======================================
  Files          26       26           
  Lines        6120     6120           
=======================================
  Hits         5132     5132           
  Misses        988      988           

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant