Skip to content

Prototype marimo-WASM explorable embedded in handbook chapter 1

Task

Prototype one marimo notebook exported to standalone WASM HTML and embed it in handbook chapter 1. Goal is to validate the pattern (handbook chapter + embedded explorable) before scaling it across chapters.

Why this is the right first prototype

  • Chapter 1 is "Interactivity as a research medium" — having a real interactive in the chapter is necessary, not decorative.
  • marimo is already in Arash's stack (marimo-pair skill exists).
  • marimo export html-wasm produces a single HTML file that runs in-browser with no backend, embeddable in mkdocs-material via iframe or direct include.
  • Quick fail-fast signal: if marimo-WASM doesn't embed cleanly in mkdocs, fall back to static figures and a "open notebook" link before investing in 6 more chapters.

Suggested explorable

A task graph + worklog scheduler simulation:

  • User defines a small task graph (3–5 nodes with edges) via Python code in a marimo cell
  • A reactive cell shows the dependency graph rendered (graphviz or networkx)
  • Another reactive cell shows the dispatch order the worklog scheduler would compute, with fake "running" / "complete" badges advancing as the user steps through
  • Optional: a slider for WORKLOG_QUEUE_CONCURRENCY showing how the parallelism changes the timeline

This is content-meaningful (teaches a real worklog concept) and visually compelling enough to anchor the chapter.

Steps

  1. Create marimo notebook under projio/docs/handbook/01-interactivity-as-medium/explorable.py (or wherever projio's convention is for notebook source).
  2. Author the cells as described above. Use marimo-pair skill if working interactively.
  3. Export: marimo export html-wasm explorable.py -o explorable.html.
  4. Embed in mkdocs: include via iframe in chapter 1's index page, sized to fit. Test on the projio docs build.
  5. Validate:
  6. Renders correctly in browser
  7. Reactive updates work (no Python backend needed)
  8. File size acceptable (< few MB)
  9. Mobile/responsive sanity check

Acceptance

  • One working marimo-WASM explorable embedded in handbook chapter 1
  • mkdocs build succeeds with the embed
  • Chapter 1 reads as "frame + explorable + commentary" not "prose with broken HTML"
  • Decision logged: continue with marimo-WASM for other chapters, or fall back

Open questions

  • How does marimo-WASM interact with mkdocs-material's nav/search? May need iframe wrapper.
  • Bundle size — if marimo-WASM is heavy per page, consider one shared explorable per "part" rather than per chapter.
  • Citation: the Deep Research PDF lists Marimo as a reactive notebook in the survey; reference appropriately.

Reference

  • Idea note: docs/log/idea/idea-arash-20260507-221835-382557.md (full handbook architecture and tool decisions)
  • Deep Research PDF: chapter 1 frame source
  • Marimo docs: https://marimo.io/ (export html-wasm command)