webassembly: Add minimal JSPI support and tests for Pyodide parity. - #19594

Summary

Related to @Gadgetoid's work in #19427 which formed the basis of a technical investigation found in this gist.

This PR adds minimal JavaScript Promise Integration (JSPI) to MicroPython's webassembly port. This feature will only work with browsers that support JSPI or recent versions of Node (24+) that also support it.

JavaScript Promise Integration (JSPI) is a WebAssembly standard, now shipping in V8-based browsers and coming soon to Firefox and Safari. It lets a running WebAssembly computation suspend on a JavaScript Promise and resume when it resolves. Synchronous-looking Python appears to safely block in the asynchronous browser world (result = run_sync(fetch(...))) without actually blocking the main thread or incurring Asyncify's historical penalty in binary size and speed. It is the standards-based mechanism that efficiently lets sync-shaped code interoperate cleanly with the promise-based web platform.

The PR adds jsffi.run_sync() and jsffi.can_run_sync() with Pyodide API parity, delivered as a new jspi build variant. runPythonAsync() is the sole promising entry; one suspension in flight, enforced globally; both functions exist on every build with graceful degradation.

Note: this proposal permits exactly one suspension in flight at a time - a deliberate, justified divergence from Pyodide (see the decision in section C2 of the linked gist) that trades an exotic capability for a drastically simpler / smaller implementation.

Testing

Testing is entirely contained within the webassembly port.

Prerequisits

Emscripten:

git clone https://github.com/emscripten-core/emsdk.git
cd emsdk
./emsdk install latest
./emsdk activate latest
source ./emsdk_env.sh
emcc --version           # confirms emcc is on PATH

Node (25 or later):

# Install nvm if absent; see https://github.com/nvm-sh/nvm for
# the current install command, or use your existing copy.
nvm install 26
nvm use 26

Build and test

cd ports/webassembly
make VARIANT=jspi submodules
make VARIANT=jspi
make VARIANT=jspi test

Expect emcc: warning: -sJSPI (ASYNCIFY=2) is still experimental during the build. This labels Emscripten's toolchain integration, not the JSPI standard itself (which is W3C Phase 4 and shipping in all three engine families).

NB: If you're using Node24 you'll need to add --experimental-wasm-jspi to all node commands.

Smoke tests

Start the REPL:

make VARIANT=jspi repl

Then try this:

import jsffi, js
jsffi.run_sync(js.Promise.resolve(42))

A picture is worth a thousand words:

Note: CTRL-C and exit() don't appear to work with the node based REPL.

I've also attached xterm-input-demo.zip. Copy micropython.mjs and micropython.wasm from ports/webassembly/build-jspi/ into the assets directory inside the unzipped directory, then serve the project root over HTTP (e.g. python3 -m http.server) and open index.html in a JSPI-capable browser via http://localhost:8000 (e.g. recent Chrome).

📦 xterm-input-demo.zip

This demonstrates the use of JSPI in the browser to run blocking Python code on the browser's main thread without blocking the main thread. I replace the builtin input function with one that interacts with Xterm via a promise, resolved when the user's input is submitted.

It's the canonical impossible thing - blocking input() on the browser's main thread beloved by literally every introduction to Python - working in stock-shaped Python, with no worker, no Asyncify, no SharedArrayBuffer faffing about, or incomprehensible HTTP headers. Nice'n'simple. 🙂

name = input("What is your name? ")
print(f"Hello, {name}!")

It's the two-line argument for the whole PR, and the seed of BFP's need to avoid all the web-worker complexity of PyScript via JSPI. 🎉 🤗 💪 🚀

Again, a picture is worth a thousand words:

Trade-offs and Alternatives

The resulting assets are going to be marginally bigger, but within what I suspect are acceptable limits.

Generative AI

I used generative AI tools when creating this PR, but a human has checked the code and is responsible for the code and the description above.

Specifically:

• Claude was used to read and do an initial analysis of @Gadgetoid's work in ports/webassembly: Add cooperative VM yield to the JS event loop. #19427. This was substantially re-written and edited by @ntoll into this gist.
• Once given the go-ahead, Claude was used to extract Phil's code and do an initial refactor to the smallest cut of JSPI support. This was extensively reviewed and tested by @ntoll who added revisions to the commentary contained within the code (which could/should be removed?).
• I wrote this PR description by hand.