WASM: document browser limitations and raise helpful platform-specific errors

[mmcky]

Note

Updated 2026-09-09. Item 1 is withdrawn — it was wrong. Network calls work in the browser; @oyamad demonstrated both call paths in xeus-python on 2026-09-06 and the reasoning is in the comment below. PR #948 was built on the old text before anyone tested it. Item 3 is moved out of this issue (no WASM rationale left, and it is entangled with the util/notebooks.py deprecation question for 0.12.0). Items 2 and 4 stand and are unchanged in substance. The 2026-08-21 revision and the original text are in the edit history.

Part of #925 (Phase 1). Documentation and error-message work — no behaviour changes on native platforms.

Items

• Network utilities fail in the browser. Withdrawn 2026-09-09 — the premise was false. The original text claimed fetch_nb_dependencies and the GameTracer .gam URL loaders "perform socket-level HTTP, which does not exist in WASM", and that JS-fetch-backed shims are "kernel-specific and not guaranteed in xeus-python". Both calls in fact work in xeus-python today: urllib3 has shipped native Emscripten support since 2.2.0 and enables it automatically when sys.platform is emscripten, substituting EmscriptenHTTPConnection over XMLHttpRequest (or fetch on a worker thread for streaming), and requests sits on urllib3. emscripten-forge reached the same conclusion months ago and retired requests-wasm-polyfill as redundant (Drop requests-wasm-polyfill? emscripten-forge/recipes#782). Do not add a sys.platform == "emscripten" guard here — that condition is exactly what switches urllib3 onto its browser transport, so the guard would fire precisely when the network path is being enabled. If a friendlier error is still wanted later, the shape to aim for is wrapping a failure that actually occurs rather than refusing before trying, and it is better attempted once WASM: Host a WASM testbed site under the QuantEcon org #950 / WASM: add a WebAssembly/JupyterLite smoke-test job to CI #933 give us a browser kernel where a real failure can be observed.
• probvec docstring. parallel=True (the default) silently executes serially on Emscripten. Two numba emscripten patches produce this: patch 0007 falls back from the target='parallel' ufunc target to 'cpu' (the path probvec takes), and patch 0010 (Fallback Numba parallel JIT to serial on Emscripten emscripten-forge/recipes#6293, merged 2026-08-18, shipped as numba 0.67.0 build 1) compiles @njit(parallel=True) serially and forces NUMBA_NUM_THREADS=1. A one-line note keeps the documented contract honest. This is the part of PR WASM: raise OSError for network calls on Emscripten (#931) #948 that should land — it is correct and independent of everything above.
• Consider demoting requests from a hard dependency to an optional extra. Moved out of this issue and out of WASM: browser support for QuantEcon.py (Numba + JupyterLite) — tracking issue #925 on 2026-09-09. requests resolves for the browser and now demonstrably works there, so this is ordinary dependency hygiene rather than browser work. It is also entangled with the separate question of deprecating quantecon/util/notebooks.py in 0.12.0 and dropping requests altogether; if that goes ahead this item is moot. It should be tracked with that decision, not here.
• A short "QuantEcon.py in the browser" docs page. The supported stack (JupyterLite + xeus-python + emscripten-forge); what works (sourced from the per-function results table WASM: JupyterLite proof-of-concept deployment and browser smoke suite #928 is meant to record — note that this now includes the network utilities); what does not work yet (the jitted-generator hang, WASM: support_enumeration and vertex_enumeration hang in the browser — root cause is jitted generators (numba.np.linalg._LAPACK verified working) #927, and the warm-cache cache=True failure, WASM: cache=True functions that link a cache-restored callee fail with "no compiled object yet" (simplex_grid → num_compositions_jit → comb_jit) #944); single-threaded execution — all Numba parallelism is silently serialised in the browser (guvectorize target='parallel' via patch 0007; @njit(parallel=True) / prange and NUMBA_NUM_THREADS=1 via patch 0010); and the wasm32 limits (coordinate with WASM: audit 32-bit intp behaviour on wasm32 (overflow guards, simplex_index wrapping, dtypes) #929).

Testing note

Smoke tests for this issue must assert capabilities, not guards. PR #948's two Emscripten-gated tests asserted that our own sys.platform branch raises OSError — which the new code did unconditionally — so they would have passed in the browser and locked the defect in. Assert what the platform can actually do (from_url returns a 3-player game) so the test is able to disagree with us.

Related

• PR WASM: raise OSError for network calls on Emscripten (#931) #948 — implements the withdrawn item 1; needs cutting back to the probvec docstring note. Hold the rework until the util/notebooks.py deprecation question settles
• WASM: Host a WASM testbed site under the QuantEcon org #950 — QuantEcon-hosted JupyterLite testbed; the place a claim like item 1 should have been checked in seconds, and where the docs page's "what works" list can be verified
• WASM: JupyterLite proof-of-concept deployment and browser smoke suite #928 — Phase 0 smoke checklist; its per-function results table is the source for the "what works" section of the docs page
• WASM: support_enumeration and vertex_enumeration hang in the browser — root cause is jitted generators (numba.np.linalg._LAPACK verified working) #927 — jitted generators hang on first call in the browser, so support_enumeration and vertex_enumeration never return (LAPACK itself is verified working); no upstream report yet. The docs page should list both as not working
• WASM: cache=True functions that link a cache-restored callee fail with "no compiled object yet" (simplex_grid → num_compositions_jit → comb_jit) #944 — on a warm session, a cache=True caller whose callee was restored from the persistent cache fails with RuntimeError: no compiled object yet; reported upstream as Numba: RuntimeError: no compiled object yet emscripten-forge/recipes#6309 (open); decision is to wait for upstream
• WASM: remove @njit(parallel=True) from gini_coefficient via an O(n log n) rewrite #926 / PR Rewrite Gini coefficient in O(n log n) #937 — merged 2026-09-09; gini_coefficient is now the O(n log n) closed form, so the browser no longer runs a serial O(n²) loop
• WASM: reduce import-time eager Numba compilation #930 / PR WASM: defer eager Numba gufunc/jit compilation to first use (#930) #943 — import time: patch 0007 also disables cache=True for @vectorize / @guvectorize, so the four eagerly compiled gufuncs recompile every session
• WASM: audit 32-bit intp behaviour on wasm32 (overflow guards, simplex_index wrapping, dtypes) #929 — wasm32 limits (32-bit default integer, comb_jit / simplex_grid boundary, 2–4 GB memory cap); documentation-only, and its second task hands the user-facing wording to this issue
• ci/wasm/smoke_test.py — on main since PR WASM: JupyterLite environment config and browser smoke suite #938. No browser job runs it yet; that runner is WASM: add a WebAssembly/JupyterLite smoke-test job to CI #933

[oyamad]

In fact, GAMReader.from_url works on the public demo https://notebook.link/@anutosh491/numba-ecosystem:

import quantecon.game_theory as gt
url = 'https://raw.githubusercontent.com/QuantEcon/QuantEcon.py/main/' + \
      'quantecon/game_theory/tests/game_files/minimum_effort_game.gam'
g = gt.GAMReader.from_url(url)
print(g)

3-player NormalFormGame with payoff profile array:
[[[[  1.,   1.,   1.],   [  1.,   1.,  -9.],   [  1.,   1., -19.]],
  [[  1.,  -9.,   1.],   [  1.,  -9.,  -9.],   [  1.,  -9., -19.]],
  [[  1., -19.,   1.],   [  1., -19.,  -9.],   [  1., -19., -19.]]],

 [[[ -9.,   1.,   1.],   [ -9.,   1.,  -9.],   [ -9.,   1., -19.]],
  [[ -9.,  -9.,   1.],   [  2.,   2.,   2.],   [  2.,   2.,  -8.]],
  [[ -9., -19.,   1.],   [  2.,  -8.,   2.],   [  2.,  -8.,  -8.]]],

 [[[-19.,   1.,   1.],   [-19.,   1.,  -9.],   [-19.,   1., -19.]],
  [[-19.,  -9.,   1.],   [ -8.,   2.,   2.],   [ -8.,   2.,  -8.]],
  [[-19., -19.,   1.],   [ -8.,  -8.,   2.],   [  3.,   3.,   3.]]]]

And request works as well:

import requests
r = requests.get("https://raw.githubusercontent.com/QuantEcon/QuantEcon.notebooks/master/dependencies/auto.csv")
print(r.status_code, len(r.content))

200 4117

[mmcky]

Item 1 is wrong and is withdrawn. Thanks @oyamad for the runs above — they falsify the premise this issue was written on, and PR #948 was built on it before anyone tested it.

The claim was that fetch_nb_dependencies and GAMReader.from_url "perform socket-level HTTP, which does not exist in WASM", and that JS-fetch-backed shims are "kernel-specific and not guaranteed in xeus-python". Both calls in fact work in xeus-python today. urllib3 has shipped native Emscripten support since 2.2.0 and, per its documentation, enables it automatically when sys.platform is emscripten — substituting EmscriptenHTTPConnection over XMLHttpRequest, or fetch on a worker thread for streaming. requests sits on urllib3, so fetch_nb_dependencies inherits it. emscripten-forge reached the same conclusion months ago: requests-wasm-polyfill was retired as redundant (emscripten-forge/recipes#782).

The sharp edge is that sys.platform == "emscripten" is the exact condition that switches urllib3 onto its browser transport, so a guard keyed on it fires precisely when the network path is being enabled. Shipping PR #948 as written would have removed working functionality.

Item 3 (demote requests to an optional extra) loses its WASM rationale too. requests resolves fine in the browser and now works there, so this is ordinary dependency hygiene rather than browser work — and it is entangled with the open question of deprecating quantecon/util/notebooks.py in 0.12.0. Moving it out of this issue and out of the #925 tracker.

Items 2 and 4 stand. The probvec docstring note is correct and independent — patch 0007 does remap target='parallel' to 'cpu', so parallel=True genuinely executes serially. That is the part of PR #948 that should land. The browser-limitations docs page is unaffected, except that it should no longer list the network utilities as broken.

Two process notes, because the interesting part is how this got as far as a merge-ready PR:

The two smoke tests in PR #948 would have passed in the browser and locked the defect in. They assert that from_url raises OSError on Emscripten, which the new code does unconditionally — so the test verifies our own guard rather than the platform. Asserting the capability instead (from_url returns a 3-player game) would have failed loudly and correctly. Worth adopting as a rule for ci/wasm/smoke_test.py.

And the underlying cause is that we have no cheap way to check a browser claim: every browser fact in this campaign was gathered by hand in a third-party demo, and #928's evidence table still has 9 of 14 rows marked "not yet run". #950 and #933 are what change that. #925 now carries an evidence marker on every claim so that "inferred" is visible before it becomes a PR.