cosanlab / cosanlab/nltools

Restore in-browser (marimo WASM / Pyodide) tutorials and library support post-0.6.0

Open
#487 2 comments 0 reactions 0 assignees View on GitHub
enhancement
Dominant language
Python
Stars
130
Forks
48
Avg merge
6h 42m
Merged PRs (30d)
34

Description

## Summary

In-browser support was **deferred out of v0.6.0** so the release could ship (`453a2c4b` on `0.6.0-fixes`). Everything removed is preserved intact on the backup branch **[`0.6.1-browser`](https://github.com/cosanlab/nltools/tree/0.6.1-browser)** (forked from `5eefd193`, the last commit with all of it). This issue tracks bringing it back in a 0.6.x release.

## What was removed (and lives on `0.6.1-browser`)

**Docs / tutorial pipeline**
- `scripts/build_marimo_wasm.py` — `marimo export html-wasm` of every tutorial, served next to the MyST site
- `docs-wasm` poe task and the `docs-build` / `docs-deploy.yml` steps that ran it (release-only WASM bake + `BASE_URL` link rewriting)
- The per-notebook WASM plumbing: `IN_WASM` detection, the micropip install cell (`wasm_ready` sentinel), `seed_resources` cells (`seeded` sentinel), `browser_*` seeder cells with `if IN_WASM: … else:` loaders, "Running live in your browser" admonitions, `pyodide-http` in the PEP 723 headers

**Library**
- `nltools.templates.seed_resources` and the Pyodide/IDBFS fetch path in `nltools/templates/fetch.py` (`_fetch_pyodide`, `_ensure_idbfs_mounted`, `_syncfs`, the `"pyodide" in sys.modules` branches in `fetch_resource` / `list_resources`)
- `nltools.datasets.PAIN_RESOURCES`, `EMOTION_METADATA`, `emotion_resources()` — the pre-seeding manifests
- `nltools/tests/pyodide/` (node + Pyodide smoke runner), the `pyodide` CI job, the `test-pyodide` poe task

## Why it was deferred

The WASM path was the most fragile part of the docs build and had no test coverage of the exported pages. Three coupled Pyodide 0.27.7 issues had to be worked around and will need re-verifying against whatever Pyodide marimo ships when this is revived:

1. Never inject a `file://` wheel into the PEP 723 header — marimo bakes the header into the browser micropip list (#455 follow-up).
2. Export with `--no-execute` — `--execute` freezes the dev env's resolved dep versions into that list, which Pyodide can't provide.
3. marimo never re-runs a cell that errored, so a single install cell must `await micropip.install` the whole stack UNPINNED (except `nilearn==0.13.1`) and every importing cell must depend on a `wasm_ready` sentinel.

Related: #455 (iplot / niivue under WASM).

## Plan for revival

- [ ] Rebase / cherry-pick `0.6.1-browser` onto post-0.6.0 `master` (expect conflicts in the 8 tutorial notebooks — they were rewritten as plain marimo notebooks; the WASM cells should be re-added as thin `hide_code=True` cells rather than reverting the notebooks)
- [ ] Decide whether the tutorials should target **molab** instead of self-hosted WASM pages (would make most of the pipeline unnecessary; needs `nltools` on PyPI at the target version)
- [ ] Re-verify the exported pages in a real browser (playwright-cli on served `docs/_build/html`), not just the node smoke runner
- [ ] Reinstate the `pyodide` CI job only if it can be made non-advisory

Contributor guide

Open the contributing guide

Research direction

Compare the 0.6.1-browser branch with post-0.6.0 master, starting with scripts/build_marimo_wasm.py, docs-build/docs-deploy.yml, the eight tutorial notebooks, and nltools/templates/fetch.py. Run the restored docs and pyodide tasks, then verify exported pages in a real browser; done means the chosen WASM or molab path works without regressing current tutorials and library support.

Written by the indexing model from the issue text.

Assessment

Tech stack
python
Domain
build-system, documentation, testing
Issue type
Feature
Difficulty
5/5
Estimated time
Over a week
Activity status
Active
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.