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

[mmcky]

Note

Updated 2026-08-21. Corrected the first item: the URL loaders in game_converters.py read the GameTracer .gam format (GAMReader.from_url / from_gam_url), not Gambit. The parallel-fallback items now cite both numba emscripten patches (0007 for the ufunc target, 0010 for @njit(parallel=True), shipped 2026-08-18), and a Related section links the issues that supply the "what works / what doesn't yet" content for the docs page. Scope is unchanged: documentation and error messages only.

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

Items

• Network utilities fail in the browser. fetch_nb_dependencies (via requests) and the GameTracer .gam URL loaders in game_theory/game_converters.py — GAMReader.from_url and its wrapper from_gam_url (via urllib.request) — perform socket-level HTTP, which does not exist in WASM; JS-fetch-backed shims are kernel-specific and not guaranteed in xeus-python. Both imports are already lazy (urllib.request is imported inside the classmethod and is not in sys.modules after import quantecon) so nothing breaks at import — but the calls themselves will fail obscurely in-browser. Raise a helpful platform-specific error when sys.platform == "emscripten" and document the limitation in the docstrings. Pair the new message with an Emscripten-gated assertion in ci/wasm/smoke_test.py (see Related).
• 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.
• Consider demoting requests from a hard dependency to an optional extra. Its only runtime user is fetch_nb_dependencies, which already imports it lazily. It exists as conda-forge noarch so it resolves fine in the browser either way — this is dependency hygiene, not a blocker.
• 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); 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, emscripten-forge numba 0.67.0 build 1 or later); and the wasm32 limits (coordinate with WASM: audit 32-bit intp behaviour on wasm32 (overflow guards, simplex_index wrapping, dtypes) #929).

Related

• WASM: JupyterLite proof-of-concept deployment and browser smoke suite #928 — Phase 0 smoke checklist; its per-function results table (not yet posted) 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 (simplex_grid via num_compositions_jit → comb_jit; also k_array_rank_jit); 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 — gini_coefficient runs serially in the browser under patch 0010, at O(n²) until the O(n log n) rewrite in Rewrite Gini coefficient in O(n log n) #937 (approved, awaiting merge) lands
• 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: defer eager Numba gufunc/jit compilation to first use (#930) #943 (open) defers all five import-time compiles to first call and does not fix WASM: cache=True functions that link a cache-restored callee fail with "no compiled object yet" (simplex_grid → num_compositions_jit → comb_jit) #944
• WASM: audit 32-bit intp behaviour on wasm32 (overflow guards, simplex_index wrapping, dtypes) #929 — wasm32 limits (int32 default integer, comb_jit / simplex_grid boundary at 2³¹−1, 2–4 GB memory cap shared with the whole kernel); 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 merged (2026-08-21); already defines IS_EMSCRIPTEN, so it is the home for an Emscripten-gated assertion on the new platform-specific error message. No browser job runs it yet; that runner is WASM: add a WebAssembly/JupyterLite smoke-test job to CI #933