1# jupyterlite-numbl-kernel
3Run [**numbl**](https://numbl.org), numerical computing with **MATLAB
4syntax**, in [JupyterLite](https://jupyterlite.readthedocs.io/) notebooks,
5**entirely in the browser**, with no server, no kernel process, and nothing
6for the reader to install.
8numbl is an open-source numerical-computing engine, written in TypeScript,
9that uses MATLAB syntax, so `.m` code runs unchanged. This kernel runs a
10numbl session in a Web Worker in the page: variables persist across cells,
11console output streams into the running cell, plots render as figures in cell
12outputs (including interactive 3-D), the `mip` package manager can install
13numbl packages from GitHub, and `.m` files next to the notebook are part of
14the workspace (named functions, called from cells). Everything runs
15client-side.
17**Demo site:**
18<https://concept-collection.github.io/jupyterlite-numbl-kernel/> (deployed
19from this repo via GitHub Pages; see `.github/workflows/deploy.yml`)
21## Why
23This kernel is a proof of concept that a numbl notebook can be a static web
24page: hostable on GitHub Pages, shareable as a link, and executable by anyone
25with a browser. Because numbl uses MATLAB syntax and needs no MATLAB/Octave
26install (or any server process), the same `.m` code that would otherwise
27require a licensed product behind a server just runs in the tab.
29## How it works
31Three small pieces, all in this repo:
33- **Kernel** (`src/kernel.ts`): implements JupyterLite's `BaseKernel` from
34 `@jupyterlite/services`. Before each `execute_request`, `.m` files in the
35 notebook's directory (read via the JupyterLite contents manager) are
36 synced into the numbl session; the cell source then runs against the
37 session's persistent workspace (`createNumblSession` /
38 `session.execute` from `numbl/browser`, a Web Worker that numbl manages).
39 Output streams back as `stream` messages; the run's plot instructions are
40 published as `display_data` with the mime type
41 `application/vnd.numbl.figure+json`.
42- **Figure renderer** (`src/mime.tsx`): a JupyterLab mime renderer for that
43 mime type: it replays the instructions through numbl's figures reducer and
44 mounts numbl's React `FigureView` (from `numbl/graphics`). Outputs are
45 plain JSON, so saved notebooks re-render wherever the extension is
46 installed.
47- **Kernel registration** (`src/index.ts`): registers the kernelspec with
48 JupyterLite's `IKernelSpecs`.
50## Build a site with it
52```bash
53pip install jupyterlite-core jupyterlite-numbl-kernel
54jupyter lite build --contents my-notebooks --output-dir dist
55# dist/ is a static site; serve it anywhere
56```
58The `demo/` directory in this repo contains the demo site sources
59(notebooks + requirements); `.github/workflows/deploy.yml` builds and
60deploys it to GitHub Pages. The `demo/content/advanced/` folder holds a
61systematic seven-notebook tour of the language (data types, matrices,
62control flow, linear algebra, data structures, numerical methods, and
63plotting).
65### Always-fresh content (demo choice)
67JupyterLite caches content in two layers that both defeat redeploys:
691. It copies notebooks into the browser's IndexedDB on first visit, and that
70 local copy then wins over the deployed files **even after a redeploy**.
712. Its **service worker** is an offline caching proxy for the app itself and
72 for content files, so it can keep serving the old app and old notebooks
73 after a redeploy until it happens to update.
75Since this is a demo, `demo/jupyter-lite.json` neutralizes both: it uses
76JupyterLite's in-memory storage (so every reload re-seeds the latest
77deployed notebooks) and disables the service-worker plugin (which the numbl
78kernel doesn't need, since it reads content on the main thread, not via the
79service worker's kernel drive):
81```json
82{
83 "jupyter-config-data": {
84 "enableMemoryStorage": true,
85 "contentsStorageDrivers": ["memoryStorageDriver"],
86 "settingsStorageDrivers": ["memoryStorageDriver"],
87 "workspacesStorageDrivers": ["memoryStorageDriver"],
88 "disabledExtensions": [
89 "@jupyterlite/application-extension:service-worker-manager"
90 ]
91 }
92}
93```
95The trade-off is that a visitor's edits live only for the session and are
96discarded on reload. A visitor who loaded the site **before** the service
97worker was disabled still has it registered and must clear browser data
98(or `Help > Clear Browser Data`) once to get past it. For a real deployment where users should keep their
99work, omit these keys (the default persistent storage) and bump
100`contentsStorageName` when you want to force-refresh shipped content.
101numbl's own package cache (installed via `mip`) lives in a separate
102IndexedDB store and is unaffected, so `mip`-installed packages still
103persist across reloads.
105## Limitations (proof of concept)
107- **No interrupt**: a runaway cell can only be stopped by restarting the
108 kernel (restart works and gives a fresh workspace). Cooperative
109 cancellation exists in numbl but needs `SharedArrayBuffer`, i.e.
110 cross-origin isolation headers, which plain GitHub Pages doesn't set.
111- **No `input()`** (stdin), for the same reason.
112- **Figures are per-cell** (like inline matplotlib): each cell renders the
113 figures its own commands produce; `hold on` does not span cells.
114- **Named function definitions are not supported inside cells** (a numbl
115 REPL limitation): anonymous functions work, and named functions belong in
116 `.m` files next to the notebook (see `demo/content/statsutils.m`), which
117 this kernel syncs into the session automatically.
118- The `.m`-file sync is **one-way**: deleting a `.m` file from the file
119 browser leaves its function defined until the kernel restarts, and files
120 written by cell code (e.g. via `fopen`) don't appear back in the file
121 browser.
122- **uihtml** components render display-only; the MATLAB↔HTML event bridge
123 is not wired into outputs yet.
124- numbl itself is not MATLAB: it covers a large, tested subset of the
125 language and toolbox surface. See [numbl](https://numbl.org) for scope.
127## Development
129Requires Python ≥ 3.9 and NodeJS ≥ 20, and `numbl >= 0.4.14` on npm (the
130first release with the incremental `session.execute` browser API). To
131develop against an unreleased numbl checkout, run `npm pack` there and
132point the `numbl` dependency at the tarball.
134```bash
135python -m venv .venv && source .venv/bin/activate
136pip install "jupyterlab~=4.6.0" "jupyterlite-core==0.8.1"
138jlpm install
139jlpm build # tsc + labextension (dev)
140pip install -e . # editable install, registers the labextension
142# Build and serve the demo site locally
143pip install -r demo/requirements.txt
144jupyter lite build --lite-dir demo --contents content --output-dir demo/_output
145python -m http.server -d demo/_output 8000
146```
148`jlpm watch` rebuilds on change during development.
150## License
152Apache-2.0. Built on [numbl](https://numbl.org) and
153the [JupyterLite](https://github.com/jupyterlite/jupyterlite) kernel API;
154scaffolding follows the
155[jupyterlite/echo-kernel](https://github.com/jupyterlite/echo-kernel)
156template.