Build infrastructure

Deeper notes on the browser-runtime build stack (JupyterLite, xeus, Voici), CI solver constraints, and Python-version support.

JupyterLite

JupyterLite is a Jupyter distribution that runs entirely in the browser. Python kernels run client-side, either using the Pyodide-based default kernel or, when the jupyterlite-xeus extension is enabled, using a xeus-python WebAssembly kernel.

JupyterLite xeus UI

The notebooks UI is brought by the --apps notebooks option of jupyter lite build. It is necessary that the venv in which that command is run does not contain the notebooks python package. JupyterLite’s own docs make clear that supported Notebook/JupyterLab versions are tied to the jupyterlite-core release line.

In order to be able to use the “File->Open” menu of the Notebooks UI, one needs to add the app tree to the build command.

JupyterLite Xeus notes for CI

  • Channels currently used are environment.yml:

    • https://conda.anaconda.org/conda-forge

    • https://repo.prefix.dev/emscripten-forge-dev

  • Keep following xeus dependencies to avoid solver drift and to keep notebook compatibility:

    • xeus-python, xeus-python-shell, xeus-python-shell-lite

    • ipywidgets, ipyleaflet,orjson, pycparser, yarl, shapely, flexpolyline

  • pycparser is expected to come from conda-forge as a noarch package (pyh... build string), while orjson is expected from emscripten-forge-dev (e.g. wasm build 3.11.3).

  • If CI fails with Could not solve for environment specs mentioning pycparser or xeus-python-shell-lite, verify the specs send to micromamba first. You can use the --micromamba option of create_env.py (in xeus.sh)

  • Application code remains injectable per commit through:

    • --XeusAddon.mounts="$ROOT_DIR/src/here_search_demo:/lib/python3.13/site-packages/here_search_demo".

  • emscripten-forge provides conda-style packages for WebAssembly (emscripten-wasm32), enabling Python and scientific stacks in the browser. Delivery channels:

    emscripten-forge-4x

    emscripten-forge-dev

    Stability (intended)

    higher

    lower

    Updates

    slower

    faster

    Fix availability

    delayed

    immediate

    • when very accurate routes are needed, we use the pyproj package. pyproj build _2 in emscripten-forge-4x preventing us to use this channel. This needs to be reported. The build in emscripten-forge-dev is working, so we can use that channel for now. Root cause: broken PROJ data bundle → Transformer.from_crs fails

Voici

Voici reuses the same xeus kernel stack, but it builds an app-style dashboard output instead of the full JupyterLite shell. It is built by the same script and command path as JupyterLite:

jupyterlite_build/xeus.sh

This sheel script builds:

  • the xeus JupyterLite lab & notebooks site under workspace/

  • the xeus Voici app for notebooks/basic-demo.ipynb under workspace/voici/

By default, JupyterLite uses the browser storage to store settings and site preferences. It is sometimes helpful to clear in the browser settings the 127.0.0.1 site data to not use a stale state.

Reference:

  • https://jupyterlite.readthedocs.io/en/stable/

  • https://emscripten-forge.org/blog/

  • https://xeus-python-kernel.readthedocs.io/en/latest/

Python 3.14 & 3.15

here-search-demo can be used in JupyterLab running Python 3.14 or 3.15 JupyterLab. Notebooks on Python 3.15 are very slow at the time of writing (25/6/2026). Jupyter Xeus isnot supported by the emscripten-forge recipe for Python 3.14 or 3.15 yet.: emscripten-forge recipe for python is currently at 3.13.1, not 3.14.

If Xeus support for Python 3.14 is enabled (see recipe), the --XeusAddon.mounts option of jupyterlite_build/xeus.sh needs to be updated to point to the correct site-packages path.

brew upgrade pyenv
pyenv install --list | grep 3.15