feat: generate islands from notebook IR (#9988)

Adds `MarimoIslandGenerator.from_ir(...)` so callers can construct
island exports from `NotebookSerialization` directly. This way,
downstream exporters like quarto-marimo, jupyter-book-marimo and
mdx-marimo mostly only need to worry about parsing their source format
and mapping it to marimo IR.

Disabled and transitively disabled cells are marked nonreactive.

---------

Co-authored-by: Myles Scolnick <myles@marimo.io>

Author: peter-gy

marimo/_islands/_island_generator.py

@@ -13,19 +13,24 @@
 from marimo._ast.app_config import _AppConfig
 from marimo._ast.cell import Cell, CellConfig
 from marimo._ast.compiler import compile_cell
+from marimo._ast.load import load_notebook_ir
 from marimo._messaging.cell_output import CellOutput
 from marimo._output.utils import uri_encode_component
+from marimo._schemas.serialization import NotebookSerialization
 from marimo._session.notebook import AppFileManager, load_notebook
 from marimo._types.ids import CellId_t
+from marimo._utils.marimo_path import MarimoPath
 from marimo._version import __version__
 
 if sys.platform == "win32":  # handling for windows
     asyncio.set_event_loop_policy(asyncio.WindowsSelectorEventLoopPolicy())
 
 if TYPE_CHECKING:
+    from marimo._ast.models import CellData
     from marimo._session.state.session_view import SessionView
 
 LOGGER = _loggers.marimo_logger()
+IN_MEMORY_FILENAME = "<marimo>.py"
 
 
 class MarimoIslandStub:
@@ -255,6 +260,11 @@ def __init__(self, app_id: str = "main"):
         # resolve to the notebook rather than to the host process.
         self._source_filename: str | None = None
 
+    @property
+    def stubs(self) -> tuple[MarimoIslandStub, ...]:
+        """Return a snapshot of the generated per-cell island renderers."""
+        return tuple(self._stubs)
+
     @staticmethod
     def from_file(
         filename: str,
@@ -290,6 +300,49 @@ def from_file(
 
         return generator
 
+    @staticmethod
+    def _from_ir(
+        notebook: NotebookSerialization,
+        *,
+        app_id: str = "main",
+        filepath: str | None = None,
+        display_code: bool = False,
+    ) -> MarimoIslandGenerator:
+        """Create a generator from serialized marimo notebook data.
+
+        Args:
+            notebook: Serialized notebook IR.
+            app_id: App identifier written to rendered island DOM.
+            filepath: Source path used for `__file__` and `mo.notebook_dir()`.
+            display_code: Whether generated stubs render code by default.
+        """
+        ir_filepath = filepath if filepath is not None else notebook.filename
+        source_filename = _source_filename(ir_filepath)
+        app = load_notebook_ir(
+            notebook,
+            filepath=_load_filepath(source_filename or ir_filepath),
+        )
+
+        generator = MarimoIslandGenerator(app_id=app_id)
+        generator._source_filename = source_filename
+        internal_app = InternalApp(app)
+        generator._app = internal_app
+        generator._config = internal_app.config
+        cells = list(generator._app.cell_manager.cell_data())
+        disabled_cell_ids = _disabled_cell_ids(cells)
+        generator._stubs = [
+            MarimoIslandStub(
+                cell_id=data.cell_id,
+                app_id=generator._app_id,
+                code=data.code,
+                display_code=display_code,
+                is_reactive=data.cell_id not in disabled_cell_ids,
+            )
+            for data in cells
+        ]
+
+        return generator
+
     def add_code(
         self,
         code: str,
@@ -597,3 +650,36 @@ def render_html(
 
 def remove_empty_lines(text: str) -> str:
     return "\n".join([line for line in text.split("\n") if line.strip() != ""])
+
+
+def _source_filename(filename: str | None) -> str | None:
+    if filename is None or filename == IN_MEMORY_FILENAME:
+        return None
+    return os.path.abspath(filename)
+
+
+def _load_filepath(filename: str | None) -> str:
+    if filename and MarimoPath.is_valid_path(filename):
+        return filename
+    return IN_MEMORY_FILENAME
+
+
+def _disabled_cell_ids(cell_data: list[CellData]) -> set[CellId_t]:
+    from marimo._runtime.dataflow.graph import DirectedGraph
+
+    disabled_cell_ids = {
+        data.cell_id for data in cell_data if data.cell is None
+    }
+    graph = DirectedGraph()
+
+    for data in cell_data:
+        cell = data.cell
+        if cell is not None:
+            graph.register_cell(data.cell_id, cell._cell)
+
+    for data in cell_data:
+        cell = data.cell
+        if cell is not None and graph.is_disabled(data.cell_id):
+            disabled_cell_ids.add(data.cell_id)
+
+    return disabled_cell_ids

tests/_islands/test_island_generator.py

@@ -1,6 +1,6 @@
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, get_type_hints
 
 import pytest
 
@@ -9,6 +9,11 @@
 from marimo._islands._island_generator import (
     MarimoIslandGenerator,
 )
+from marimo._schemas.serialization import (
+    AppInstantiation,
+    CellDef,
+    NotebookSerialization,
+)
 from tests.mocks import snapshotter
 
 if TYPE_CHECKING:
@@ -17,6 +22,19 @@
 snapshot = snapshotter(__file__)
 
 
+def _notebook(
+    cells: list[CellDef],
+    *,
+    options: dict[str, object] | None = None,
+    filename: str | None = None,
+) -> NotebookSerialization:
+    return NotebookSerialization(
+        app=AppInstantiation(options=options or {}),
+        cells=cells,
+        filename=filename,
+    )
+
+
 def test_add_code():
     generator = MarimoIslandGenerator()
     generator.add_code("print('Hello, World!')")
@@ -243,6 +261,235 @@ def __(mo):
     assert str(other_dir / "nb.py") not in data
 
 
+async def test_from_ir_builds_notebook_serialization() -> None:
+    notebook = _notebook(
+        [
+            CellDef(code="import marimo as mo"),
+            CellDef(code='mo.md("# Hello, IR!")'),
+        ],
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook, app_id="page-a")
+    stubs = generator.stubs
+
+    assert len(stubs) == 2
+    assert stubs[0].code == "import marimo as mo"
+    assert stubs[1].code == 'mo.md("# Hello, IR!")'
+    body_html = generator.render_body(include_init_island=False)
+    assert 'data-app-id="page-a"' in body_html
+    for cell_id in generator._app.cell_manager.cell_ids():
+        assert f'data-cell-id="{cell_id}"' in body_html
+
+    await generator.build()
+
+    stub = generator.stubs[1]
+    assert stub.output is not None
+    assert "Hello, IR!" in stub.output.data
+
+
+def test_stubs_returns_read_only_snapshot() -> None:
+    generator = MarimoIslandGenerator()
+    generator.add_code("x = 1")
+
+    stubs = generator.stubs
+    assert len(stubs) == 1
+    assert stubs[0].code == "x = 1"
+
+    generator.add_code("y = 2")
+    assert len(stubs) == 1
+    assert len(generator.stubs) == 2
+
+
+def test_from_ir_type_hints_resolve() -> None:
+    hints = get_type_hints(MarimoIslandGenerator._from_ir)
+
+    assert hints["notebook"] is NotebookSerialization
+    assert hints["return"] is MarimoIslandGenerator
+
+
+def test_from_ir_applies_display_code_to_stubs() -> None:
+    notebook = _notebook([CellDef(code="x = 1")])
+
+    generator = MarimoIslandGenerator._from_ir(
+        notebook,
+        display_code=True,
+    )
+
+    html = generator.stubs[0].render()
+    assert "<marimo-cell-code hidden>" not in html
+    assert "x = 1" in html
+
+
+def test_from_ir_preserves_app_config() -> None:
+    notebook = _notebook(
+        [],
+        options={"width": "medium", "app_title": "IR App"},
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook)
+
+    body_html = generator.render_body()
+    assert 'style="margin: auto; max-width: 1110px;"' in body_html
+
+    html = generator.render_html()
+    assert "<title> IR App </title>" in html
+
+
+def test_from_ir_sanitizes_markdown_app_config() -> None:
+    notebook = _notebook(
+        [],
+        options={"width": "medium", "author": "Marimo"},
+        filename="notebook.md",
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook)
+
+    body_html = generator.render_body()
+    assert 'style="margin: auto; max-width: 1110px;"' in body_html
+
+
+async def test_from_ir_propagates_ir_filename_to_cells(tmp_path: Path) -> None:
+    notebook_file = tmp_path / "nb.py"
+    notebook_file.write_text("")
+    notebook = _notebook(
+        [
+            CellDef(code="import marimo as mo"),
+            CellDef(
+                code=('mo.md(f"FILE={__file__} | DIR={mo.notebook_dir()}")')
+            ),
+        ],
+        filename=str(notebook_file),
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook)
+    await generator.build()
+
+    captured = generator.stubs[1].output
+    assert captured is not None
+    data = captured.data
+    assert str(notebook_file) in data, (
+        f"expected __file__ to resolve to {notebook_file}, got: {data}"
+    )
+    assert str(notebook_file.parent) in data, (
+        f"expected notebook_dir() to resolve to {notebook_file.parent}, "
+        f"got: {data}"
+    )
+
+
+async def test_from_ir_resolves_relative_path_at_capture_time(
+    tmp_path: Path,
+) -> None:
+    import os
+
+    notebook_dir = tmp_path / "notebooks"
+    notebook_dir.mkdir()
+    notebook_file = notebook_dir / "nb.py"
+    notebook_file.write_text("")
+    notebook = _notebook(
+        [
+            CellDef(code="import marimo as mo"),
+            CellDef(code='mo.md(f"FILE={__file__}")'),
+        ],
+    )
+    other_dir = tmp_path / "elsewhere"
+    other_dir.mkdir()
+
+    original_cwd = os.getcwd()
+    try:
+        os.chdir(notebook_dir)
+        generator = MarimoIslandGenerator._from_ir(notebook, filepath="nb.py")
+        os.chdir(other_dir)
+        await generator.build()
+    finally:
+        os.chdir(original_cwd)
+
+    captured = generator.stubs[1].output
+    assert captured is not None
+    data = captured.data
+    assert str(notebook_file) in data, (
+        f"expected __file__ to resolve to {notebook_file}, got: {data}"
+    )
+    assert str(other_dir / "nb.py") not in data
+
+
+async def test_from_ir_filepath_overrides_ir_filename(
+    tmp_path: Path,
+) -> None:
+    ir_file = tmp_path / "ir.py"
+    source_file = tmp_path / "source.ipynb"
+    ir_file.write_text("")
+    source_file.write_text("")
+    notebook = _notebook(
+        [
+            CellDef(code="import marimo as mo"),
+            CellDef(
+                code=('mo.md(f"FILE={__file__} | DIR={mo.notebook_dir()}")')
+            ),
+        ],
+        filename=str(ir_file),
+    )
+
+    generator = MarimoIslandGenerator._from_ir(
+        notebook, filepath=str(source_file)
+    )
+    await generator.build()
+
+    captured = generator.stubs[1].output
+    assert captured is not None
+    data = captured.data
+    assert str(source_file) in data, (
+        f"expected __file__ to resolve to {source_file}, got: {data}"
+    )
+    assert str(source_file.parent) in data, (
+        f"expected notebook_dir() to resolve to {source_file.parent}, "
+        f"got: {data}"
+    )
+    assert str(ir_file) not in data
+
+
+async def test_from_ir_preserves_disabled_cell_config() -> None:
+    notebook = _notebook(
+        [
+            CellDef(code="'disabled output'", options={"disabled": True}),
+            CellDef(code="'active output'"),
+        ],
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook)
+
+    body_html = generator.render_body(include_init_island=False)
+    assert 'data-reactive="false"' in body_html
+    assert 'data-reactive="true"' in body_html
+
+    await generator.build()
+
+    disabled_stub = generator.stubs[0]
+    active_stub = generator.stubs[1]
+    assert disabled_stub.output is None
+    assert active_stub.output is not None
+    assert "active output" in active_stub.output.data
+
+
+async def test_from_ir_marks_transitively_disabled_cells_static() -> None:
+    notebook = _notebook(
+        [
+            CellDef(code="x = 1", options={"disabled": True}),
+            CellDef(code="x + 1"),
+        ],
+    )
+
+    generator = MarimoIslandGenerator._from_ir(notebook)
+
+    rendered = [stub.render() for stub in generator.stubs]
+    assert all('data-reactive="false"' in html for html in rendered)
+    assert "x%20%2B%201" not in rendered[1]
+
+    await generator.build()
+
+    assert generator.stubs[0].output is None
+    assert generator.stubs[1].output is None
+
+
 def test_render_head():
     generator = MarimoIslandGenerator()
     head_html = generator.render_head()