pyobservablejs 0.0.0rc1__tar.gz

pyobservablejs-0.0.0rc1/.gitignore

@@ -0,0 +1,11 @@
+node_modules
+.venv
+dist
+docs/_build
+.DS_Store
+
+# Python
+__pycache__
+.ipynb_checkpoints
+
+src/pyobservablejs/static

pyobservablejs-0.0.0rc1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Peter Ferenc Gyarmati
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyobservablejs-0.0.0rc1/PKG-INFO

@@ -0,0 +1,179 @@
+Metadata-Version: 2.4
+Name: pyobservablejs
+Version: 0.0.0rc1
+Summary: Observable JavaScript notebooks as reusable Python widgets
+Project-URL: Homepage, https://github.com/peterg-y/pyobservablejs
+Project-URL: Source, https://github.com/peterg-y/pyobservablejs
+Project-URL: Issues, https://github.com/peterg-y/pyobservablejs/issues
+Author-email: Peter Ferenc Gyarmati <dev.petergy@gmail.com>
+Maintainer-email: Peter Ferenc Gyarmati <dev.petergy@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: anywidget,jupyter,marimo,notebooks,observable,visualization
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: <3.15,>=3.10
+Requires-Dist: anywidget>=0.11.0
+Requires-Dist: traitlets>=5
+Description-Content-Type: text/markdown
+
+# pyobservablejs
+
+Observable JavaScript notebooks as Python widgets.
+
+`pyobservablejs` renders Observable JavaScript cells from Python and runs them with
+Observable Notebook Kit in the browser. Python owns the notebook model, synced
+OJS variables, and cell widgets. TypeScript owns Notebook Kit evaluation,
+rendering, and runtime metadata.
+
+```python
+import pyobservablejs as obs
+
+rows = [
+    {"letter": "A", "frequency": 0.0812},
+    {"letter": "B", "frequency": 0.0149},
+    {"letter": "C", "frequency": 0.0271},
+    {"letter": "D", "frequency": 0.0432},
+    {"letter": "E", "frequency": 0.1202},
+]
+
+obs.Notebook(
+    obs.md("# Letter frequencies"),
+    obs.ojs("""
+    Plot.plot({
+      height: 260,
+      marginLeft: 48,
+      y: {grid: true, label: "frequency"},
+      marks: [
+        Plot.ruleY([floor]),
+        Plot.barY(rows, {x: "letter", y: "frequency", tip: true})
+      ]
+    })
+    """),
+    variables={"rows": rows, "floor": 0.04},
+)
+```
+
+## Install
+
+```sh
+pip install pyobservablejs
+```
+
+or:
+
+```sh
+uv add pyobservablejs
+```
+
+`pyobservablejs` supports Python 3.10 through 3.14.
+
+## Notebook Model
+
+- `obs.Notebook(...)` builds a Notebook Kit notebook from Python-authored cells.
+- `variables={...}` sets OJS variables. A matching notebook variable is overridden.
+- `notebook.update_variables(...)` pushes Python-side changes into the live OJS
+  runtime.
+- `name="..."` gives Python a stable name for a cell.
+- `notebook.values` and `notebook.cell("name").value` read browser-synchronized
+  outputs after rendering.
+- `notebook.graph` exposes Notebook Kit-derived cell definitions, references, and
+  dependency edges.
+
+Cell helpers keep the source mode explicit:
+
+| Helper          | Source mode           |
+| --------------- | --------------------- |
+| `obs.ojs(...)`  | Observable JavaScript |
+| `obs.js(...)`   | ES module JavaScript  |
+| `obs.md(...)`   | Markdown              |
+| `obs.html(...)` | HTML                  |
+
+```python
+notebook = obs.Notebook(
+    obs.md("# Inputs"),
+    obs.ojs('viewof gain = Inputs.range([0, 11], {value: 5})', name="gain"),
+    obs.ojs("double = gain * 2", name="double"),
+)
+
+notebook.cell("gain")
+```
+
+After the notebook or cell widget has rendered in the browser, read the synced
+value from a later Python cell:
+
+```python
+notebook.value("double")
+```
+
+## Source Notebooks
+
+Load Notebook Kit HTML from a string:
+
+```python
+from pathlib import Path
+
+path = Path("chart.html")
+notebook = obs.Notebook.from_html(
+    path.read_text(encoding="utf-8"),
+    base_path=path.parent,
+)
+```
+
+Local `FileAttachment(...)` references and relative JavaScript imports are
+embedded by default so the widget can move between notebook frontends.
+
+Load a public ObservableHQ notebook by URL, slug, or id:
+
+```python
+notebook = obs.Notebook.from_observablehq("https://observablehq.com/@mbostock/saving-svg")
+```
+
+Remote `FileAttachment(...)` entries are registered as URL-backed attachments,
+so Plot notebooks and examples with uploaded files can render in the widget.
+Pass `variables={...}` to override variables in a loaded notebook with Python values.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Examples](docs/examples.md)
+- [Tutorials](docs/tutorials/index.md)
+- [Concepts](docs/concepts.md)
+- [Architecture](docs/architecture.md)
+- [Widget composition](docs/composition.md)
+- [API reference](docs/api.md)
+- [Development](docs/development.md)
+
+## Built On
+
+- [anywidget](https://anywidget.dev) and traitlets for widget composition and
+  synced state
+- [Observable Notebook Kit](https://github.com/observablehq/notebook-kit) and
+  [@observablehq/runtime](https://github.com/observablehq/runtime) for cell
+  transpilation and browser execution
+- [Shiki](https://shiki.style/) for pinned source highlighting
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, workbench notebooks,
+and the check commands used before sending changes for review.
+
+## Acknowledgements
+
+`pyobservablejs` builds on [Observable Notebook Kit](https://github.com/observablehq/notebook-kit)
+and [@observablehq/runtime](https://github.com/observablehq/runtime).
+[`pyobsplot`](https://github.com/juba/pyobsplot) informed the Python-to-OJS
+variable API.
+
+Thanks to [@manzt](https://github.com/manzt) (Trevor Manz) for the composable
+anywidgets demo that helped shape the widget design.
+
+## License
+
+MIT

pyobservablejs-0.0.0rc1/README.md

@@ -0,0 +1,154 @@
+# pyobservablejs
+
+Observable JavaScript notebooks as Python widgets.
+
+`pyobservablejs` renders Observable JavaScript cells from Python and runs them with
+Observable Notebook Kit in the browser. Python owns the notebook model, synced
+OJS variables, and cell widgets. TypeScript owns Notebook Kit evaluation,
+rendering, and runtime metadata.
+
+```python
+import pyobservablejs as obs
+
+rows = [
+    {"letter": "A", "frequency": 0.0812},
+    {"letter": "B", "frequency": 0.0149},
+    {"letter": "C", "frequency": 0.0271},
+    {"letter": "D", "frequency": 0.0432},
+    {"letter": "E", "frequency": 0.1202},
+]
+
+obs.Notebook(
+    obs.md("# Letter frequencies"),
+    obs.ojs("""
+    Plot.plot({
+      height: 260,
+      marginLeft: 48,
+      y: {grid: true, label: "frequency"},
+      marks: [
+        Plot.ruleY([floor]),
+        Plot.barY(rows, {x: "letter", y: "frequency", tip: true})
+      ]
+    })
+    """),
+    variables={"rows": rows, "floor": 0.04},
+)
+```
+
+## Install
+
+```sh
+pip install pyobservablejs
+```
+
+or:
+
+```sh
+uv add pyobservablejs
+```
+
+`pyobservablejs` supports Python 3.10 through 3.14.
+
+## Notebook Model
+
+- `obs.Notebook(...)` builds a Notebook Kit notebook from Python-authored cells.
+- `variables={...}` sets OJS variables. A matching notebook variable is overridden.
+- `notebook.update_variables(...)` pushes Python-side changes into the live OJS
+  runtime.
+- `name="..."` gives Python a stable name for a cell.
+- `notebook.values` and `notebook.cell("name").value` read browser-synchronized
+  outputs after rendering.
+- `notebook.graph` exposes Notebook Kit-derived cell definitions, references, and
+  dependency edges.
+
+Cell helpers keep the source mode explicit:
+
+| Helper          | Source mode           |
+| --------------- | --------------------- |
+| `obs.ojs(...)`  | Observable JavaScript |
+| `obs.js(...)`   | ES module JavaScript  |
+| `obs.md(...)`   | Markdown              |
+| `obs.html(...)` | HTML                  |
+
+```python
+notebook = obs.Notebook(
+    obs.md("# Inputs"),
+    obs.ojs('viewof gain = Inputs.range([0, 11], {value: 5})', name="gain"),
+    obs.ojs("double = gain * 2", name="double"),
+)
+
+notebook.cell("gain")
+```
+
+After the notebook or cell widget has rendered in the browser, read the synced
+value from a later Python cell:
+
+```python
+notebook.value("double")
+```
+
+## Source Notebooks
+
+Load Notebook Kit HTML from a string:
+
+```python
+from pathlib import Path
+
+path = Path("chart.html")
+notebook = obs.Notebook.from_html(
+    path.read_text(encoding="utf-8"),
+    base_path=path.parent,
+)
+```
+
+Local `FileAttachment(...)` references and relative JavaScript imports are
+embedded by default so the widget can move between notebook frontends.
+
+Load a public ObservableHQ notebook by URL, slug, or id:
+
+```python
+notebook = obs.Notebook.from_observablehq("https://observablehq.com/@mbostock/saving-svg")
+```
+
+Remote `FileAttachment(...)` entries are registered as URL-backed attachments,
+so Plot notebooks and examples with uploaded files can render in the widget.
+Pass `variables={...}` to override variables in a loaded notebook with Python values.
+
+## Documentation
+
+- [Quickstart](docs/quickstart.md)
+- [Examples](docs/examples.md)
+- [Tutorials](docs/tutorials/index.md)
+- [Concepts](docs/concepts.md)
+- [Architecture](docs/architecture.md)
+- [Widget composition](docs/composition.md)
+- [API reference](docs/api.md)
+- [Development](docs/development.md)
+
+## Built On
+
+- [anywidget](https://anywidget.dev) and traitlets for widget composition and
+  synced state
+- [Observable Notebook Kit](https://github.com/observablehq/notebook-kit) and
+  [@observablehq/runtime](https://github.com/observablehq/runtime) for cell
+  transpilation and browser execution
+- [Shiki](https://shiki.style/) for pinned source highlighting
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for local setup, workbench notebooks,
+and the check commands used before sending changes for review.
+
+## Acknowledgements
+
+`pyobservablejs` builds on [Observable Notebook Kit](https://github.com/observablehq/notebook-kit)
+and [@observablehq/runtime](https://github.com/observablehq/runtime).
+[`pyobsplot`](https://github.com/juba/pyobsplot) informed the Python-to-OJS
+variable API.
+
+Thanks to [@manzt](https://github.com/manzt) (Trevor Manz) for the composable
+anywidgets demo that helped shape the widget design.
+
+## License
+
+MIT

pyobservablejs-0.0.0rc1/js/build.mjs

@@ -0,0 +1,22 @@
+import * as esbuild from "esbuild";
+
+const args = new Set(process.argv.slice(2));
+
+const options = {
+	assetNames: "widget",
+	bundle: true,
+	entryNames: "widget",
+	entryPoints: ["js/widget/index.ts"],
+	format: "esm",
+	minify: true,
+	outdir: "src/pyobservablejs/static",
+	sourcemap: args.has("--sourcemap=inline") ? "inline" : false,
+};
+
+if (args.has("--watch")) {
+	const context = await esbuild.context(options);
+	await context.watch();
+	console.log("Watching widget sources...");
+} else {
+	await esbuild.build(options);
+}

pyobservablejs-0.0.0rc1/js/css.d.ts

@@ -0,0 +1 @@
+declare module "*.css";

pyobservablejs-0.0.0rc1/js/graph.test.ts

@@ -0,0 +1,121 @@
+// @vitest-environment jsdom
+
+import { toNotebook } from "@observablehq/notebook-kit";
+import { describe, expect, test } from "vitest";
+import { createNotebookGraph } from "./observable/graph";
+
+describe("notebook graph metadata", () => {
+	test("uses Notebook Kit transpile metadata for references, outputs, and edges", () => {
+		const notebook = toNotebook({
+			cells: [
+				{ id: 1, mode: "ojs", value: "a = 1" },
+				{ id: 2, mode: "ojs", value: "b = a + rows.length" },
+				{ id: 3, mode: "ojs", value: "viewof gain = Inputs.range([0, 10])" },
+				{ id: 4, mode: "ojs", value: "gain * b" },
+			],
+		});
+
+		const graph = createNotebookGraph(notebook, ["a", "b", "gain", "readout"]);
+
+		expect(graph.cells.map((cell) => cell.defines)).toEqual([["a"], ["b"], ["gain"], []]);
+		expectMembers(graph.cells[1]?.references, ["a", "rows"]);
+		expect(graph.cells[2]?.output).toBe("viewof$gain");
+		expect(graph.cells[2]?.runtime_outputs).toEqual(["viewof$gain"]);
+		expect(graph.cells[2]?.autoview).toBe(true);
+		expect(graph.edges).toHaveLength(3);
+		expect(graph.edges).toContainEqual({ from: 1, to: 2, variable: "a" });
+		expect(graph.edges).toContainEqual({ from: 3, to: 4, variable: "gain" });
+		expect(graph.edges).toContainEqual({ from: 2, to: 4, variable: "b" });
+	});
+
+	test("preserves raw JS declarations separately from visible variables", () => {
+		const notebook = toNotebook({
+			cells: [{ id: 1, mode: "js", value: "const x = 1;\nconst y = 2;" }],
+		});
+
+		const graph = createNotebookGraph(notebook);
+
+		expectMembers(graph.cells[0]?.defines, ["x", "y"]);
+		expectMembers(graph.cells[0]?.outputs, ["x", "y"]);
+		expectMembers(graph.cells[0]?.runtime_outputs, ["x", "y"]);
+		expect(graph.cells[0]?.output).toBe(null);
+	});
+
+	test("records mutable aliases used by Notebook Kit references", () => {
+		const notebook = toNotebook({
+			cells: [
+				{ id: 1, mode: "ojs", value: "mutable count = 0" },
+				{ id: 2, mode: "ojs", value: "count + 1" },
+				{ id: 3, mode: "ojs", value: "mutable count" },
+			],
+		});
+
+		const graph = createNotebookGraph(notebook);
+
+		expect(graph.cells[0]?.defines).toEqual(["count"]);
+		expect(graph.cells[0]?.output).toBe("mutable count");
+		expectMembers(graph.cells[0]?.runtime_outputs, ["mutable count", "mutable$count"]);
+		expect(graph.cells[0]?.automutable).toBe(true);
+		expect(graph.edges).toHaveLength(2);
+		expect(graph.edges).toContainEqual({ from: 1, to: 2, variable: "count" });
+		expect(graph.edges).toContainEqual({ from: 1, to: 3, variable: "mutable$count" });
+	});
+
+	test("uses Notebook Kit output metadata for module, template, SQL, and hidden cells", () => {
+		const notebook = toNotebook({
+			cells: [
+				{ id: 1, mode: "js", value: "const answer = 42;", output: "answer" },
+				{ id: 2, mode: "md", value: "# Title", output: "title" },
+				{ id: 3, mode: "html", value: "<b>Hi</b>", output: "node" },
+				{ id: 4, mode: "sql", value: "select 1 as x", output: "rows" },
+				{ id: 5, mode: "ojs", value: "hidden = answer + 1", hidden: true },
+			],
+		});
+
+		const graph = createNotebookGraph(notebook);
+
+		expect(graph.cells[0]?.defines).toEqual(["answer"]);
+		expect(graph.cells[0]?.outputs).toEqual(["answer"]);
+		expect(graph.cells[0]?.output).toBe("answer");
+		expect(graph.cells[1]?.defines).toEqual(["title"]);
+		expect(graph.cells[1]?.references).toEqual(["md"]);
+		expect(graph.cells[2]?.defines).toEqual(["node"]);
+		expect(graph.cells[2]?.references).toEqual(["html"]);
+		expect(graph.cells[3]?.defines).toEqual(["rows"]);
+		expect(graph.cells[3]?.output).toBe("viewof$rows");
+		expect(graph.cells[3]?.runtime_outputs).toEqual(["viewof$rows"]);
+		expect(graph.cells[3]?.autoview).toBe(true);
+		expect(graph.cells[4]?.defines).toEqual(["hidden"]);
+		expect(graph.cells[4]?.autodisplay).toBe(false);
+		expect(graph.edges).toContainEqual({ from: 1, to: 5, variable: "answer" });
+	});
+
+	test("keeps imported Observable variables as plural outputs", () => {
+		const notebook = toNotebook({
+			cells: [{ id: 1, mode: "ojs", value: 'import {foo} from "./foo.js"' }],
+		});
+
+		const graph = createNotebookGraph(notebook);
+
+		expect(graph.cells[0]?.defines).toEqual(["foo"]);
+		expect(graph.cells[0]?.outputs).toEqual(["foo"]);
+	});
+
+	test("keeps graph entries for cells with transpile errors", () => {
+		const notebook = toNotebook({
+			cells: [{ id: 1, mode: "ojs", value: "answer =" }],
+		});
+
+		const graph = createNotebookGraph(notebook);
+
+		expect(graph.cells[0]?.id).toBe(1);
+		expect(graph.cells[0]?.defines).toEqual([]);
+		expect(graph.cells[0]?.error).toEqual(expect.any(String));
+		expect(graph.cells[0]?.error).not.toBe("");
+	});
+});
+
+function expectMembers(actual: string[] | undefined, expected: string[]): void {
+	expect(actual).toHaveLength(expected.length);
+	expect(actual).toEqual(expect.arrayContaining(expected));
+}

pyobservablejs-0.0.0rc1/js/highlight.test.ts

@@ -0,0 +1,18 @@
+// @vitest-environment jsdom
+
+import { toCell } from "@observablehq/notebook-kit";
+import { describe, expect, test } from "vitest";
+import { SELECTORS } from "./widget/dom-contract";
+import { renderSource } from "./widget/highlight";
+
+describe("source rendering", () => {
+	test("preserves source text and accessible source labeling", () => {
+		const controller = new AbortController();
+		const panel = renderSource(toCell({ id: 1, mode: "ojs", value: "answer = 42" }), controller.signal);
+		const source = panel.querySelector<HTMLPreElement>(SELECTORS.source);
+
+		expect(source?.textContent).toBe("answer = 42");
+		expect(source?.getAttribute("aria-label")).toBe("OJS source");
+		controller.abort();
+	});
+});

pyobservablejs-0.0.0rc1/js/model/types.ts

@@ -0,0 +1,31 @@
+import type { RenderProps } from "@anywidget/types";
+import type { NotebookGraph } from "../observable/types";
+import type { AttachmentInfo } from "../runtime/types";
+
+// Trait names match src/pyobservablejs/_notebook.py, including underscored wire traits.
+
+export type WidgetModel = {
+	role?: "notebook" | "cell";
+	_cell_id?: string;
+	name?: string;
+	source?: string;
+	spec?: Record<string, unknown>;
+	attachments?: Record<string, AttachmentInfo>;
+	base_url?: string;
+	_variables?: Record<string, unknown>;
+	_variable_update?: {
+		seq?: number;
+		kind?: "set" | "replace";
+		values?: Record<string, unknown>;
+	};
+	_graph?: NotebookGraph;
+	_values?: Record<string, unknown>;
+	_value_names?: string[];
+	options?: {
+		show_source?: boolean;
+		observable_markdown_compatibility?: boolean;
+	};
+	_cell_widgets?: string[];
+};
+
+export type WidgetAnyModel = RenderProps<WidgetModel>["model"];

pyobservablejs-0.0.0rc1/js/model/values.ts

@@ -0,0 +1,21 @@
+import type { RenderProps } from "@anywidget/types";
+import type { WidgetModel } from "./types";
+
+export type AnyWidgetModel = RenderProps<WidgetModel>["model"];
+
+export function readModelVariableNames(model: AnyWidgetModel): string[] {
+	const value = model.get("_value_names");
+	return Array.isArray(value) ? value.filter((name): name is string => typeof name === "string") : [];
+}
+
+export function readModelVariables(model: AnyWidgetModel): Record<string, unknown> {
+	const value = model.get("_values");
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+	return value;
+}
+
+export function readNotebookVariables(model: AnyWidgetModel): Record<string, unknown> {
+	const value = model.get("_variables");
+	if (value === null || typeof value !== "object" || Array.isArray(value)) return {};
+	return value;
+}

pyobservablejs-0.0.0rc1/js/observable/graph.ts

@@ -0,0 +1,89 @@
+import { transpile, type Notebook } from "@observablehq/notebook-kit";
+import type { CellGraph, NotebookGraph } from "./types";
+
+type Definition = ReturnType<typeof transpile>;
+
+export function createNotebookGraph(notebook: Notebook, names: readonly string[] = []): NotebookGraph {
+	const cells = notebook.cells.map((cell, index) => createCellGraph(cell, index, names[index] ?? ""));
+	const definitions = new Map<string, CellGraph[]>();
+	for (const cell of cells) {
+		for (const name of definedNames(cell)) {
+			const existing = definitions.get(name);
+			if (existing) existing.push(cell);
+			else definitions.set(name, [cell]);
+		}
+	}
+
+	const edges = cells.flatMap((target) =>
+		target.references.flatMap((name) =>
+			(definitions.get(name) ?? [])
+				.filter((source) => source.id !== target.id)
+				.map((source) => ({
+					from: source.id,
+					to: target.id,
+					variable: name,
+				})),
+		),
+	);
+
+	return { cells, edges };
+}
+
+export function exposedVariableNames(definition: Definition): string[] {
+	if (definition.output) {
+		if (definition.autoview) return [unprefix(definition.output, "viewof$")];
+		if (definition.automutable) return [unprefix(definition.output, "mutable ")];
+		return [definition.output];
+	}
+	return definition.outputs ?? [];
+}
+
+export function unprefix(value: string, prefix: string): string {
+	return value.startsWith(prefix) ? value.slice(prefix.length) : value;
+}
+
+function createCellGraph(notebookCell: Notebook["cells"][number], index: number, name: string): CellGraph {
+	try {
+		const definition = transpile(notebookCell, { resolveLocalImports: true });
+		return {
+			id: notebookCell.id,
+			index,
+			name,
+			mode: notebookCell.mode,
+			defines: exposedVariableNames(definition),
+			references: definition.inputs ?? [],
+			output: definition.output ?? null,
+			outputs: definition.outputs ?? [],
+			runtime_outputs: runtimeOutputs(definition),
+			autodisplay: definition.autodisplay === true,
+			autoview: definition.autoview === true,
+			automutable: definition.automutable === true,
+		};
+	} catch (error) {
+		return {
+			id: notebookCell.id,
+			index,
+			name,
+			mode: notebookCell.mode,
+			defines: [],
+			references: [],
+			output: null,
+			outputs: [],
+			runtime_outputs: [],
+			autodisplay: false,
+			autoview: false,
+			automutable: false,
+			error: error instanceof Error ? `${error.name}: ${error.message}` : String(error),
+		};
+	}
+}
+
+function runtimeOutputs(definition: Definition): string[] {
+	if (!definition.output) return definition.outputs ?? [];
+	if (definition.automutable) return [definition.output, `mutable$${unprefix(definition.output, "mutable ")}`];
+	return [definition.output];
+}
+
+function definedNames(cell: CellGraph): string[] {
+	return Array.from(new Set([...cell.defines, ...cell.runtime_outputs]));
+}