xnotebook 1.0.0__tar.gz

xnotebook-1.0.0/.gitignore

@@ -0,0 +1,9 @@
+node_modules/
+__pycache__/
+*.egg-info/
+dist/
+build/
+web/node_modules/
+xnotebook/_web/
+*.out.ipynb
+.pytest_cache/

xnotebook-1.0.0/PKG-INFO

@@ -0,0 +1,151 @@
+Metadata-Version: 2.5
+Name: xnotebook
+Version: 1.0.0
+Summary: Run notebooks and scripts on sandboxed xeus wasm kernels (emscripten-forge) inside headless Chromium
+License-Expression: BSD-3-Clause
+Classifier: Framework :: Jupyter
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security
+Requires-Python: >=3.9
+Requires-Dist: typer>=0.12
+Requires-Dist: typing-extensions>=4.6
+Provides-Extra: test
+Requires-Dist: jsonschema>=4; extra == 'test'
+Requires-Dist: nbformat>=5; extra == 'test'
+Requires-Dist: pytest>=7; extra == 'test'
+Description-Content-Type: text/markdown
+
+# xnotebook
+
+Run Jupyter notebooks and scripts on **xeus wasm kernels** with **emscripten-forge**
+packages, sandboxed inside headless Chromium.
+
+```console
+$ pip install xnotebook
+$ xnb analysis.ipynb                 # writes analysis.out.ipynb
+$ xnb script.py -d numpy             # prints outputs as they come
+```
+
+The command is `xnb` (`xnotebook` works too), and the Python module is `xnotebook`.
+
+The first run downloads a pinned, sha256-verified `chrome-headless-shell`
+(about 120 MB) into the cache. No conda, Node or system browser is needed.
+
+## Dependencies
+
+Three sources are merged, and a later source wins for the same package:
+
+1. an environment file: `-e environment.yaml`
+2. the input file itself:
+   - notebook metadata `metadata.xnb`, which uses the environment.yaml schema:
+     ```json
+     "metadata": {"xnb": {"channels": ["conda-forge"], "dependencies": ["numpy", {"pip": ["six"]}]}}
+     ```
+   - or, in a `.py` script, a [PEP 723](https://peps.python.org/pep-0723/) block, where
+     `dependencies` are pip packages and `[tool.xnb]` holds conda packages and channels:
+     ```python
+     # /// script
+     # dependencies = ["six"]
+     # [tool.xnb]
+     # dependencies = ["numpy"]
+     # ///
+     ```
+3. the CLI: `-d numpy -d "pandas>=2" --pip six -c conda-forge`
+
+Channels default to `https://prefix.dev/emscripten-forge-4x` and `conda-forge`. The
+kernel comes from `--kernel`, then the notebook's `kernelspec`, then the file extension:
+
+| kernel | package | extension |
+| --- | --- | --- |
+| `xpython` | xeus-python | `.py` |
+| `xr` | xeus-r | `.R` |
+| `xlua` | xeus-lua | `.lua` |
+| `xjavascript` | xeus-javascript | `.js` |
+
+Solved environments are cached as locks. `--lock-out lock.json` saves the lock, and
+`--lock lock.json` reuses it without solving.
+
+## Widgets
+
+ipywidgets state is saved in `metadata.widgets`
+(`application/vnd.jupyter.widget-state+json`), like `jupyter nbconvert --execute` does.
+JupyterLab, nbviewer and Voila then render the widgets with the values they had at the
+end of the run. Closed widgets are dropped. Use `--no-widget-state` to turn this off.
+See `demo/widgets_demo.ipynb`.
+
+Scripts are split into cells at `# %%` markers (percent format). The comment prefix
+follows the language, so Lua uses `-- %%`.
+
+## Security model
+
+Notebook code runs in a Web Worker inside Chromium:
+
+- **Files:** the kernel sees only an in-memory filesystem, so the host disk is out of
+  reach. `--mount src:/dst` copies files in. `:rw` mounts are written back after the
+  run, and only as regular files under `src`: no symlinks, no `..`, with size caps.
+- **Network:** none for notebook code.
+  - Packages are fetched *before* any package or user code runs. Everything goes through
+    a local caching proxy that verifies each file against the lock's sha256.
+  - Then the run is **sealed**. The host firewall (CDP `Fetch` interception) denies every
+    request, the proxy refuses everything, and the kernel worker also has
+    `connect-src 'none'`.
+  - Chromium's own DNS is disabled.
+- **Processes and environment:** not available from a browser worker.
+- **OS sandbox:**
+  - Chromium's OS sandbox is used when the system allows it. Otherwise xnb warns and
+    runs with `--no-sandbox`, and `--strict` refuses to run at all.
+  - On Windows (and with `XNB_CDP_TRANSPORT=ws`), DevTools uses a loopback WebSocket
+    port instead of a pipe.
+
+## CLI
+
+```
+xnb FILE [-o OUT|-] [--inplace] [-q]
+         [-e ENV.yaml] [-d SPEC]... [--pip SPEC]... [-c CHANNEL]... [--kernel NAME]
+         [--lock FILE] [--lock-out FILE]
+         [--mount SRC:DST[:ro|rw]]... [--cwd DIR] [--stdin FILE]
+         [--timeout S] [--cell-timeout S] [--max-memory MB] [--allow-errors] [--no-widget-state] [-v]
+         [--offline] [--refresh] [--strict] [--browser-path PATH] [--cache-dir DIR] [--debug]
+xnb setup [--from chrome-headless-shell.zip]
+xnb cache {info,clean,prune}
+```
+
+Exit codes: 0 on success, 1 when a cell fails or times out, 2 for usage or setup
+errors.
+
+## Python API
+
+```python
+import xnotebook
+
+nb = xnotebook.run("analysis.ipynb", deps=["numpy"], cell_timeout=60)   # returns the executed nbformat dict
+res = xnotebook.run(nb_dict, allow_errors=True, return_result=True)     # includes status, failedCell, stats
+```
+
+## Cache
+
+The cache lives in `~/.cache/xnb` by default (`$XNB_CACHE_DIR` overrides it):
+
+- `chromium/`: the pinned browser;
+- `pkgs/<sha256>`: packages, fetched lazily and immutable;
+- `repodata/`: metadata, with ETag and a 1 h TTL;
+- `locks/`: solved environments.
+
+`--offline` uses only the cache, and `--refresh` re-solves and revalidates.
+
+## Development
+
+```console
+$ cd web && npm ci && npm run build && npm test   # bundle -> xnotebook/_web
+$ pip install -e ".[test]"
+$ pytest                                         # browser tests are skipped without Chromium
+$ python tools/pin_chromium.py 154.0.8037.57       # hashes for chromium.PINNED
+```
+
+## Known limitations
+
+- **Widgets:** the final ipywidgets state is saved as a static snapshot. Python callbacks
+  don't run when the saved notebook is opened.
+- **pip:** pure-Python wheels only.
+- **xeus-lua:** each top-level line is evaluated on its own, so `local` variables don't
+  persist across lines. Use globals.

xnotebook-1.0.0/README.md

@@ -0,0 +1,134 @@
+# xnotebook
+
+Run Jupyter notebooks and scripts on **xeus wasm kernels** with **emscripten-forge**
+packages, sandboxed inside headless Chromium.
+
+```console
+$ pip install xnotebook
+$ xnb analysis.ipynb                 # writes analysis.out.ipynb
+$ xnb script.py -d numpy             # prints outputs as they come
+```
+
+The command is `xnb` (`xnotebook` works too), and the Python module is `xnotebook`.
+
+The first run downloads a pinned, sha256-verified `chrome-headless-shell`
+(about 120 MB) into the cache. No conda, Node or system browser is needed.
+
+## Dependencies
+
+Three sources are merged, and a later source wins for the same package:
+
+1. an environment file: `-e environment.yaml`
+2. the input file itself:
+   - notebook metadata `metadata.xnb`, which uses the environment.yaml schema:
+     ```json
+     "metadata": {"xnb": {"channels": ["conda-forge"], "dependencies": ["numpy", {"pip": ["six"]}]}}
+     ```
+   - or, in a `.py` script, a [PEP 723](https://peps.python.org/pep-0723/) block, where
+     `dependencies` are pip packages and `[tool.xnb]` holds conda packages and channels:
+     ```python
+     # /// script
+     # dependencies = ["six"]
+     # [tool.xnb]
+     # dependencies = ["numpy"]
+     # ///
+     ```
+3. the CLI: `-d numpy -d "pandas>=2" --pip six -c conda-forge`
+
+Channels default to `https://prefix.dev/emscripten-forge-4x` and `conda-forge`. The
+kernel comes from `--kernel`, then the notebook's `kernelspec`, then the file extension:
+
+| kernel | package | extension |
+| --- | --- | --- |
+| `xpython` | xeus-python | `.py` |
+| `xr` | xeus-r | `.R` |
+| `xlua` | xeus-lua | `.lua` |
+| `xjavascript` | xeus-javascript | `.js` |
+
+Solved environments are cached as locks. `--lock-out lock.json` saves the lock, and
+`--lock lock.json` reuses it without solving.
+
+## Widgets
+
+ipywidgets state is saved in `metadata.widgets`
+(`application/vnd.jupyter.widget-state+json`), like `jupyter nbconvert --execute` does.
+JupyterLab, nbviewer and Voila then render the widgets with the values they had at the
+end of the run. Closed widgets are dropped. Use `--no-widget-state` to turn this off.
+See `demo/widgets_demo.ipynb`.
+
+Scripts are split into cells at `# %%` markers (percent format). The comment prefix
+follows the language, so Lua uses `-- %%`.
+
+## Security model
+
+Notebook code runs in a Web Worker inside Chromium:
+
+- **Files:** the kernel sees only an in-memory filesystem, so the host disk is out of
+  reach. `--mount src:/dst` copies files in. `:rw` mounts are written back after the
+  run, and only as regular files under `src`: no symlinks, no `..`, with size caps.
+- **Network:** none for notebook code.
+  - Packages are fetched *before* any package or user code runs. Everything goes through
+    a local caching proxy that verifies each file against the lock's sha256.
+  - Then the run is **sealed**. The host firewall (CDP `Fetch` interception) denies every
+    request, the proxy refuses everything, and the kernel worker also has
+    `connect-src 'none'`.
+  - Chromium's own DNS is disabled.
+- **Processes and environment:** not available from a browser worker.
+- **OS sandbox:**
+  - Chromium's OS sandbox is used when the system allows it. Otherwise xnb warns and
+    runs with `--no-sandbox`, and `--strict` refuses to run at all.
+  - On Windows (and with `XNB_CDP_TRANSPORT=ws`), DevTools uses a loopback WebSocket
+    port instead of a pipe.
+
+## CLI
+
+```
+xnb FILE [-o OUT|-] [--inplace] [-q]
+         [-e ENV.yaml] [-d SPEC]... [--pip SPEC]... [-c CHANNEL]... [--kernel NAME]
+         [--lock FILE] [--lock-out FILE]
+         [--mount SRC:DST[:ro|rw]]... [--cwd DIR] [--stdin FILE]
+         [--timeout S] [--cell-timeout S] [--max-memory MB] [--allow-errors] [--no-widget-state] [-v]
+         [--offline] [--refresh] [--strict] [--browser-path PATH] [--cache-dir DIR] [--debug]
+xnb setup [--from chrome-headless-shell.zip]
+xnb cache {info,clean,prune}
+```
+
+Exit codes: 0 on success, 1 when a cell fails or times out, 2 for usage or setup
+errors.
+
+## Python API
+
+```python
+import xnotebook
+
+nb = xnotebook.run("analysis.ipynb", deps=["numpy"], cell_timeout=60)   # returns the executed nbformat dict
+res = xnotebook.run(nb_dict, allow_errors=True, return_result=True)     # includes status, failedCell, stats
+```
+
+## Cache
+
+The cache lives in `~/.cache/xnb` by default (`$XNB_CACHE_DIR` overrides it):
+
+- `chromium/`: the pinned browser;
+- `pkgs/<sha256>`: packages, fetched lazily and immutable;
+- `repodata/`: metadata, with ETag and a 1 h TTL;
+- `locks/`: solved environments.
+
+`--offline` uses only the cache, and `--refresh` re-solves and revalidates.
+
+## Development
+
+```console
+$ cd web && npm ci && npm run build && npm test   # bundle -> xnotebook/_web
+$ pip install -e ".[test]"
+$ pytest                                         # browser tests are skipped without Chromium
+$ python tools/pin_chromium.py 154.0.8037.57       # hashes for chromium.PINNED
+```
+
+## Known limitations
+
+- **Widgets:** the final ipywidgets state is saved as a static snapshot. Python callbacks
+  don't run when the saved notebook is opened.
+- **pip:** pure-Python wheels only.
+- **xeus-lua:** each top-level line is evaluated on its own, so `local` variables don't
+  persist across lines. Use globals.

xnotebook-1.0.0/hatch_build.py

@@ -0,0 +1,32 @@
+"""Build the TypeScript web bundle (web/ -> xnotebook/_web) before packaging."""
+
+import os
+import shutil
+import subprocess
+from pathlib import Path
+
+from hatchling.builders.hooks.plugin.interface import BuildHookInterface
+
+
+class WebBundleHook(BuildHookInterface):
+    PLUGIN_NAME = "custom"
+
+    def initialize(self, version, build_data):
+        root = Path(self.root)
+        out = root / "xnotebook" / "_web"
+        web = root / "web"
+        if os.environ.get("XNB_SKIP_WEB_BUILD") and (out / "index.html").exists():
+            return
+        if not web.exists():
+            if (out / "index.html").exists():
+                return  # building from an sdist that already contains the bundle
+            raise RuntimeError("web/ sources missing and no prebuilt xnotebook/_web bundle")
+        npm = shutil.which("npm")
+        if npm is None:
+            if (out / "index.html").exists():
+                self.app.display_warning("npm not found; using the existing xnotebook/_web bundle")
+                return
+            raise RuntimeError("npm is required to build the web bundle")
+        if not (web / "node_modules").exists():
+            subprocess.run([npm, "ci" if (web / "package-lock.json").exists() else "install"], cwd=web, check=True)
+        subprocess.run([npm, "run", "build"], cwd=web, check=True)

xnotebook-1.0.0/pyproject.toml

@@ -0,0 +1,40 @@
+[build-system]
+requires = ["hatchling>=1.24"]
+build-backend = "hatchling.build"
+
+[project]
+name = "xnotebook"
+dynamic = ["version"]
+description = "Run notebooks and scripts on sandboxed xeus wasm kernels (emscripten-forge) inside headless Chromium"
+readme = "README.md"
+requires-python = ">=3.9"
+license = "BSD-3-Clause"
+dependencies = [
+    "typer>=0.12",
+    "typing_extensions>=4.6",
+]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "Framework :: Jupyter",
+    "Topic :: Security",
+]
+
+[project.optional-dependencies]
+test = ["pytest>=7", "nbformat>=5", "jsonschema>=4"]
+
+[project.scripts]
+xnb = "xnotebook.cli:main"
+xnotebook = "xnotebook.cli:main"
+
+[tool.hatch.version]
+path = "xnotebook/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["xnotebook"]
+artifacts = ["xnotebook/_web/**"]
+
+[tool.hatch.build.targets.sdist]
+include = ["xnotebook", "web/src", "web/build.mjs", "web/package.json", "web/package-lock.json", "web/tsconfig.json", "hatch_build.py", "tests", "README.md", "PLAN.md"]
+
+[tool.hatch.build.hooks.custom]
+path = "hatch_build.py"

xnotebook-1.0.0/tests/test_cli.py

@@ -0,0 +1,49 @@
+import re
+
+from xnotebook.cli import main
+
+ANSI = re.compile(r"\x1b\[[0-9;]*[A-Za-z]")
+
+
+def plain(text: str) -> str:
+    """Help output is coloured when the environment forces it (e.g. on CI)."""
+    return ANSI.sub("", text)
+
+
+def test_help(capsys):
+    assert main(["--help"]) == 0
+    out = plain(capsys.readouterr().out)
+    assert "run" in out and "setup" in out and "cache" in out
+
+
+def test_run_help_is_default_command(capsys):
+    assert main(["run", "--help"]) == 0
+    out = plain(capsys.readouterr().out)
+    for flag in ("--env", "--dep", "--pip", "--mount", "--offline", "--strict", "--cell-timeout"):
+        assert flag in out
+
+
+def test_version(capsys):
+    assert main(["--version"]) == 0
+    assert "xnb" in capsys.readouterr().out
+
+
+def test_missing_file(capsys):
+    assert main(["does-not-exist.ipynb"]) == 2
+    assert "no such file" in capsys.readouterr().err
+
+
+def test_inplace_requires_notebook(tmp_path, capsys):
+    f = tmp_path / "x.py"
+    f.write_text("print(1)")
+    assert main([str(f), "--inplace"]) == 2
+
+
+def test_bad_option(capsys):
+    assert main(["x.ipynb", "--no-such-flag"]) == 2
+    assert "no-such-flag" in plain(capsys.readouterr().err)
+
+
+def test_cache_info(tmp_path, capsys):
+    assert main(["cache", "info", "--cache-dir", str(tmp_path)]) == 0
+    assert str(tmp_path) in capsys.readouterr().out

xnotebook-1.0.0/tests/test_integration.py

@@ -0,0 +1,227 @@
+"""End-to-end runs in headless Chromium (network needed on a cold cache).
+
+Skipped unless Chromium is available (installed in the xnb cache, or XNB_CHROMIUM_PATH).
+Set XNB_CACHE_DIR to share a warm cache between runs.
+"""
+
+import json
+import os
+import textwrap
+
+import pytest
+
+import xnotebook
+from xnotebook import chromium
+from xnotebook.cache import Cache
+from xnotebook.session import WEB_ROOT
+
+
+def _have_browser() -> bool:
+    if not (WEB_ROOT / "index.html").exists():
+        return False
+    if os.environ.get("XNB_CHROMIUM_PATH"):
+        return True
+    try:
+        return chromium.installed_path(Cache()).exists()
+    except chromium.ChromiumError:
+        return False
+
+
+pytestmark = pytest.mark.skipif(not _have_browser(), reason="Chromium or web bundle not available")
+
+
+def nb(*cells, **metadata):
+    return {
+        "nbformat": 4,
+        "nbformat_minor": 5,
+        "metadata": {"kernelspec": {"name": "xpython", "display_name": "Python"}, **metadata},
+        "cells": [
+            {"cell_type": "code", "source": textwrap.dedent(c), "metadata": {}, "outputs": [], "execution_count": None}
+            for c in cells
+        ],
+    }
+
+
+def texts(cell):
+    out = []
+    for o in cell["outputs"]:
+        if o["output_type"] == "stream":
+            out.append(o["text"])
+        elif o["output_type"] in ("execute_result", "display_data"):
+            out.append(o["data"].get("text/plain", ""))
+        elif o["output_type"] == "error":
+            out.append(f"{o['ename']}: {o['evalue']}")
+    return "".join(out)
+
+
+def test_basic_notebook(tmp_path):
+    stdin = tmp_path / "stdin.txt"
+    stdin.write_text("World\n")
+    result = xnotebook.run(
+        nb(
+            "print('hello'); 1 + 1",
+            "import numpy as np\nint(np.arange(3).sum())",
+            "from IPython.display import display, HTML\nh = display(HTML('<b>v1</b>'), display_id=True)\nh.update(HTML('<b>v2</b>'))",
+            "import asyncio\nawait asyncio.sleep(0.05)\nprint('awaited')",
+            "print('hi', input())",
+            "1/0",
+            "print('not reached')",
+            xnb={"dependencies": ["numpy"]},
+        ),
+        stdin=str(stdin),
+        return_result=True,
+    )
+    out = result["notebook"]
+    cells = out["cells"]
+    assert texts(cells[0]) == "hello\n2"
+    assert texts(cells[1]) == "3"
+    assert cells[2]["outputs"][0]["data"]["text/html"] == "<b>v2</b>"
+    assert texts(cells[3]) == "awaited\n"
+    assert texts(cells[4]) == "hi World\n"
+    assert cells[5]["outputs"][0]["ename"] == "ZeroDivisionError"
+    assert cells[6]["outputs"] == [] and cells[6]["execution_count"] is None
+    assert result["status"] == "error" and result["failedCell"] == 5
+    assert out["metadata"]["language_info"]["name"] == "python"
+    assert result["stats"]["requests_after_seal"] == 0
+    try:
+        import nbformat
+
+        nbformat.validate(nbformat.from_dict(out))
+    except ImportError:
+        pass
+
+
+def test_escape_attempts_blocked():
+    probe = """
+        import js
+        r = js.eval('''(async () => {
+          const real = WorkerGlobalScope.prototype.fetch;
+          const out = [];
+          const proxied = location.href.replace('kernel.worker.js', 'u/' + encodeURIComponent('https://prefix.dev/'));
+          for (const u of ['https://example.com/', proxied, location.href]) {
+            try { await real.call(self, u); out.push('ESCAPED ' + u); } catch (e) { out.push('blocked'); }
+          }
+          try { const x = new XMLHttpRequest(); x.open('GET', 'https://example.com', false); x.send(); out.push('ESCAPED xhr'); }
+          catch (e) { out.push('blocked'); }
+          try { importScripts('https://example.com/x.js'); out.push('ESCAPED importScripts'); } catch (e) { out.push('blocked'); }
+          const w = new Worker(URL.createObjectURL(new Blob(["fetch('https://example.com').then(()=>postMessage('ESCAPED nested'),()=>postMessage('blocked'))"])));
+          out.push(await new Promise(res => { w.onmessage = e => res(e.data); w.onerror = () => res('blocked'); }));
+          const ws = new WebSocket('wss://example.com');
+          out.push(await new Promise(res => { ws.onopen = () => res('ESCAPED ws'); ws.onerror = () => res('blocked'); ws.onclose = () => res('blocked'); }));
+          out.push(typeof __xnbSend === 'undefined' ? 'blocked' : 'ESCAPED binding');
+          return out.join(',');
+        })()''')
+        print(await r)
+    """
+    fs = """
+        import os
+        try:
+            open('/etc/passwd').read(); print('ESCAPED passwd')
+        except OSError:
+            print('blocked')
+        print('HOME' in os.environ and os.environ['HOME'] != os.path.expanduser('~root'))
+    """
+    result = xnotebook.run(nb(probe, fs), allow_errors=True, return_result=True)
+    cells = result["notebook"]["cells"]
+    assert "ESCAPED" not in texts(cells[0]), texts(cells[0])
+    assert set(texts(cells[0]).strip().split(",")) == {"blocked"}
+    assert texts(cells[1]).startswith("blocked")
+    assert result["stats"]["requests_after_seal"] == 0
+    assert result["stats"]["proxy_blocked_after_seal"] == 0
+
+
+def test_script_pep723_mounts_and_lock(tmp_path):
+    data = tmp_path / "data"
+    data.mkdir()
+    (data / "in.txt").write_text("input")
+    out = tmp_path / "out"
+    out.mkdir()
+    script = tmp_path / "s.py"
+    script.write_text(
+        textwrap.dedent(
+            """\
+            # /// script
+            # dependencies = ["six"]
+            # ///
+            # %%
+            import six
+            print(six.__name__, open('/data/in.txt').read())
+            # %%
+            open('/data/in.txt', 'w').write('changed')
+            open('/out/result.txt', 'w').write('from kernel')
+            """
+        )
+    )
+    lock_out = tmp_path / "lock.json"
+    result = xnotebook.run(
+        script,
+        mounts=[f"{data}:/data", f"{out}:/out:rw"],
+        lock_out=lock_out,
+        return_result=True,
+    )
+    cells = result["notebook"]["cells"]
+    assert texts(cells[0]) == "six input\n"
+    assert (data / "in.txt").read_text() == "input"  # ro: untouched
+    assert (out / "result.txt").read_text() == "from kernel"
+    lock = json.loads(lock_out.read_text())
+    assert any(p.startswith("six-") for p in lock["pipPackages"])
+    # Reuse the lock offline: everything comes from the cache
+    again = xnotebook.run(script, lock=lock_out, offline=True, mounts=[f"{data}:/data", f"{out}:/out:rw"], return_result=True)
+    assert again["status"] == "ok"
+    assert again["stats"]["upstream_fetches"] == 0
+
+
+def test_cell_timeout(tmp_path):
+    result = xnotebook.run(nb("print('a')", "while True: pass", "print('b')"), cell_timeout=3, return_result=True)
+    assert result["status"] == "timeout" and result["failedCell"] == 1
+    assert result["notebook"]["cells"][1]["outputs"][-1]["ename"] == "TimeoutError"
+    assert result["notebook"]["cells"][2]["outputs"] == []
+
+
+def test_lua_kernel(tmp_path):
+    f = tmp_path / "hello.lua"
+    f.write_text('print("lua", 1 + 2)\n')
+    result = xnotebook.run(f, return_result=True)
+    assert texts(result["notebook"]["cells"][0]) == "lua 3\n"
+    assert result["notebook"]["metadata"]["kernelspec"]["name"] == "xlua"
+
+
+def test_widget_state_saved():
+    import pathlib
+
+    result = xnotebook.run(
+        nb(
+            "import ipywidgets as w\ns = w.IntSlider(value=3)\ns",
+            "s.value = 7\ntmp = w.Checkbox()\ndisplay(tmp)\ntmp.close()",
+            "w.Image(value=b'\\x89PNG\\r\\n', format='png')",
+            xnb={"dependencies": ["ipywidgets"]},
+        ),
+        return_result=True,
+    )
+    out = result["notebook"]
+    doc = out["metadata"]["widgets"]["application/vnd.jupyter.widget-state+json"]
+    views = [
+        o["data"]["application/vnd.jupyter.widget-view+json"]["model_id"]
+        for c in out["cells"]
+        for o in c["outputs"]
+        if "application/vnd.jupyter.widget-view+json" in o.get("data", {})
+    ]
+    slider, checkbox, image = views
+    assert doc["state"][slider]["state"]["value"] == 7
+    assert checkbox not in doc["state"]
+    assert doc["state"][image]["buffers"][0]["path"] == ["value"]
+    try:
+        import jsonschema
+    except ImportError:
+        return
+    schema = json.loads((pathlib.Path(__file__).parent / "widget_state.schema.json").read_text())
+    jsonschema.validate(doc, schema)
+
+
+def test_widget_state_disabled():
+    result = xnotebook.run(
+        nb("import ipywidgets as w\nw.IntSlider()", xnb={"dependencies": ["ipywidgets"]}),
+        widget_state=False,
+        return_result=True,
+    )
+    assert "widgets" not in result["notebook"]["metadata"]