Add notebook cell renderer support

Author: root

README.md

@@ -82,6 +82,21 @@ h.set_data((0.8 * y).astype(np.float32), x=x)
 p.render()
 ```
 
+## Notebook Cell Renderer
+
+`Plot`, `Subplots`, `AlignedPlots`, and `Dashboard` implement a Jupyter widget
+MIME renderer. Put the object as the last expression in a notebook cell to
+render it directly:
+
+```python
+p = ip.Plot(width=900, height=450, title="Cell renderer")
+p.line("mid", y, x=x)
+p
+```
+
+Use `p.show()` when you want to display the plot before the last line of a cell,
+or when the final expression is a printout, table, or another object.
+
 ## Direct Web App Usage
 
 Use `@nbimplot/web` when you want ImPlot/WASM rendering in a normal browser

docs/EXAMPLES.md

@@ -12,6 +12,23 @@ import numpy as np
 import nbimplot as ip
 ```
 
+## Notebook Cell Rendering
+
+`nbimplot` plots are Jupyter widgets. If a plot-like object is the last
+expression in a notebook cell, Jupyter renders the ImPlot/WASM canvas directly:
+
+```python
+t = np.linspace(0, 20, 20_000, dtype=np.float32)
+y = np.sin(t).astype(np.float32)
+
+p = ip.Plot(width=900, height=360, title="Last Expression Render")
+p.line("signal", y, x=t)
+p
+```
+
+Use `p.show()` when the cell continues after the display call. `Subplots`,
+`AlignedPlots`, and `Dashboard` support the same last-expression display path.
+
 ## Line and In-Place Updates
 
 ```python

docs/FAST_JUPYTER_PLOTTING.md

@@ -33,6 +33,17 @@ h = p.line("signal", y, x=x)
 p.show()
 ```
 
+You can also render by leaving the plot object as the final expression in the
+cell:
+
+```python
+p = ip.Plot(width=900, height=450, title="Signal")
+p.line("signal", y, x=x)
+p
+```
+
+Use `p.show()` when displaying before additional code or printed output.
+
 ## Update Existing Data
 
 ```python

nbimplot/_plot.py

@@ -122,6 +122,32 @@ def _get_wasm_assets() -> tuple[str | None, bytes | None, str | None]:
         return _WASM_ASSET_CACHE
 
 
+def _mime_requested(mimetype: str, kwargs: dict[str, Any]) -> bool:
+    include = kwargs.get("include")
+    exclude = kwargs.get("exclude")
+    if include is not None and mimetype not in include:
+        return False
+    if exclude is not None and mimetype in exclude:
+        return False
+    return True
+
+
+def _with_text_plain(
+    bundle: tuple[dict[str, Any], dict[str, Any]] | None,
+    text: str,
+    kwargs: dict[str, Any],
+) -> tuple[dict[str, Any], dict[str, Any]] | None:
+    if bundle is None:
+        return None
+    data, metadata = bundle
+    data = dict(data)
+    if _mime_requested("text/plain", kwargs):
+        data["text/plain"] = text
+    else:
+        data.pop("text/plain", None)
+    return data, metadata
+
+
 def _to_float32_1d(data: Any, *, arg_name: str) -> np.ndarray:
     arr = np.asarray(data)
     if arr.ndim != 1:
@@ -2326,6 +2352,16 @@ def show(self) -> None:
         display(self)
         return None
 
+    def __repr__(self) -> str:
+        title = f", title={self.title!r}" if self.title else ""
+        return (
+            f"nbimplot.Plot(width={self.width}, height={self.height}{title}, "
+            f"series={len(self._series)}, primitives={len(self._primitives)}, renderer='wasm-implot')"
+        )
+
+    def _repr_mimebundle_(self, **kwargs: Any) -> tuple[dict[str, Any], dict[str, Any]] | None:
+        return _with_text_plain(super()._repr_mimebundle_(**kwargs), repr(self), kwargs)
+
     def close(self) -> None:
         if not getattr(self, "_closed", True):
             self.send({"type": "dispose"})
@@ -3065,6 +3101,16 @@ def show(self) -> None:
         self._plot.show()
         return None
 
+    def __repr__(self) -> str:
+        cls_name = type(self).__name__
+        return (
+            f"nbimplot.{cls_name}(rows={self.rows}, cols={self.cols}, title={self.title!r}, "
+            f"renderer='wasm-implot')"
+        )
+
+    def _repr_mimebundle_(self, **kwargs: Any) -> tuple[dict[str, Any], dict[str, Any]] | None:
+        return _with_text_plain(self._plot._repr_mimebundle_(**kwargs), repr(self), kwargs)
+
     def render(self) -> None:
         self._plot.render()
 

public/llms-full.txt

@@ -78,6 +78,18 @@ h = p.line("mid", y, x=x)
 p.show()
 ```
 
+Notebook cell rendering:
+
+```python
+p = ip.Plot(width=900, height=450, title="Signal")
+p.line("mid", y, x=x)
+p
+```
+
+`Plot`, `Subplots`, `AlignedPlots`, and `Dashboard` provide Jupyter widget MIME
+bundles for last-expression cell rendering. Use `p.show()` when displaying
+before later code, print output, tables, or another final expression.
+
 Update existing data:
 
 ```python

public/llms.txt

@@ -40,6 +40,11 @@ p.on_select(lambda plot, event: print(plot.indices_for_selection(event)))
 p.highlight_selection({"x_min": 0, "x_max": 1, "y_min": -1, "y_max": 1})
 ```
 
+Notebook cell rendering:
+- `Plot`, `Subplots`, `AlignedPlots`, and `Dashboard` render as Jupyter widget MIME bundles when they are the final expression in a cell.
+- Use `p` as the last line for direct cell rendering.
+- Use `p.show()` when displaying before later code, prints, tables, or another final expression.
+
 Web example:
 ```js
 import { createPlot } from "@nbimplot/web";

tests/test_plot.py

@@ -993,3 +993,40 @@ def test_show_returns_none_to_prevent_double_display():
         result = sub.show()
     assert result is None
     assert mocked_display.call_count == 1
+
+
+def test_plot_has_notebook_cell_renderer_mimebundle():
+    plot = ip.Plot(width=640, height=320, title="Cell Renderer")
+    _capture_messages(plot)
+    plot.line("mid", np.arange(5, dtype=np.float32))
+
+    bundle = plot._repr_mimebundle_()
+    assert bundle is not None
+    data, metadata = bundle
+
+    assert metadata == {}
+    assert "application/vnd.jupyter.widget-view+json" in data
+    assert data["application/vnd.jupyter.widget-view+json"]["version_major"] == 2
+    assert data["text/plain"] == (
+        "nbimplot.Plot(width=640, height=320, title='Cell Renderer', "
+        "series=1, primitives=0, renderer='wasm-implot')"
+    )
+
+    data, _ = plot._repr_mimebundle_(exclude=["text/plain"])
+    assert "text/plain" not in data
+
+
+def test_subplot_wrappers_delegate_notebook_cell_renderer():
+    sub = ip.Subplots(2, 2, title="Grid")
+    bundle = sub._repr_mimebundle_()
+    assert bundle is not None
+    data, _ = bundle
+    assert "application/vnd.jupyter.widget-view+json" in data
+    assert data["text/plain"] == "nbimplot.Subplots(rows=2, cols=2, title='Grid', renderer='wasm-implot')"
+
+    dash = ip.Dashboard(1, 2, title="Desk")
+    bundle = dash._repr_mimebundle_()
+    assert bundle is not None
+    data, _ = bundle
+    assert "application/vnd.jupyter.widget-view+json" in data
+    assert data["text/plain"] == "nbimplot.Dashboard(rows=1, cols=2, title='Desk', renderer='wasm-implot')"