Restore in-browser (marimo WASM / Pyodide) tutorials and library support post-0.6.0
- 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
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