Skip to content

A reactive notebook for Python — run reproducible experiments, query with SQL, execute as a script, deploy as an app, and version with git. Stored as pure Python. All in a modern, AI-native editor.

Support anywidget's descriptor API (`MimeBundleDescriptor`) (#8972)

Trevor Manz2a9f4b182cc5
diff --git a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
index 9df7882156..e22d7ae837 100644
--- a/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
+++ b/frontend/src/plugins/impl/anywidget/AnyWidgetPlugin.tsx
@@ -4,7 +4,6 @@
import type { AnyWidget } from "@anywidget/types";
import { useEffect, useRef } from "react";
import { z } from "zod";
-import { RANDOM_ID_ATTR } from "@/core/dom/ui-element-constants";
import { useAsyncData } from "@/hooks/useAsyncData";
import type { HTMLElementNotDerivedFromRef } from "@/hooks/useEventListener";
import { createPlugin } from "@/plugins/core/builder";
@@ -145,18 +144,10 @@ const AnyWidgetSlot = (props: IPluginProps<ModelIdRef, Data>) => {
return <ErrorBanner error={error} />;
}
- // Find the closest parent element with an attribute of `random-id`
- const randomId = props.host
- .closest(`[${RANDOM_ID_ATTR}]`)
- ?.getAttribute(RANDOM_ID_ATTR);
- const key = randomId ?? jsUrl;
-
return (
<LoadedSlot
- // Use the a key to force a re-render when the randomId (or jsUrl) changes
- // Plugins may be stateful and we cannot make assumptions that we won't be
- // so it is safer to just re-render.
- key={key}
+ // Force remount when the widget module or model changes (cell re-run).
+ key={`${jsHash}:${modelId}`}
widget={jsModule.default}
modelId={modelId}
host={host}
diff --git a/marimo/_output/formatters/anywidget_formatters.py b/marimo/_output/formatters/anywidget_formatters.py
index 2ef3752336..90f5e6a9dd 100644
--- a/marimo/_output/formatters/anywidget_formatters.py
+++ b/marimo/_output/formatters/anywidget_formatters.py
@@ -15,6 +15,13 @@ class AnyWidgetFormatter(FormatterFactory):
import anywidget # type: ignore [import-not-found]
from marimo._output import formatting
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+
+ # Patch the comm library so anywidget's descriptor API
+ # (MimeBundleDescriptor) creates comms that work in marimo.
+ patch_comm_create()
@formatting.formatter(anywidget.AnyWidget)
def _from(lmap: anywidget.AnyWidget) -> tuple[KnownMimeType, str]:
diff --git a/marimo/_output/formatters/repr_formatters.py b/marimo/_output/formatters/repr_formatters.py
index 9848010225..75f8329354 100644
--- a/marimo/_output/formatters/repr_formatters.py
+++ b/marimo/_output/formatters/repr_formatters.py
@@ -8,6 +8,8 @@ from marimo._output.formatters.iframe import maybe_wrap_in_iframe
from marimo._plugins.core.media import io_to_data_url
from marimo._utils.methods import is_callable_method
+_WIDGET_VIEW_KEY = "application/vnd.jupyter.widget-view+json"
+
MEDIA_MIME_PREFIXES = (
"image/",
"audio/",
@@ -16,6 +18,65 @@ MEDIA_MIME_PREFIXES = (
)
+def _maybe_as_anywidget_html(
+ contents: dict[str, Any],
+) -> Optional[tuple[KnownMimeType, str]]:
+ """If the mimebundle is for an anywidget, return ``text/html``.
+
+ Converts ``application/vnd.jupyter.widget-view+json`` mimebundles
+ into the same ``<marimo-anywidget>`` HTML that ``mo.ui.anywidget()``
+ produces. Works for any comm whose open state included ``_esm``
+ (both descriptor-based and ipywidgets-based anywidgets).
+
+ Traditional (non-anywidget) jupyter widgets are left untouched so
+ the frontend can show its error banner.
+ """
+ widget_view = contents.get(_WIDGET_VIEW_KEY)
+ if not isinstance(widget_view, dict):
+ return None
+ model_id = widget_view.get("model_id")
+ if not model_id:
+ return None
+
+ # Look up the comm and get the _esm that was stashed during open.
+ try:
+ from marimo._plugins.ui._impl.anywidget.init import (
+ WIDGET_COMM_MANAGER,
+ )
+ except Exception:
+ return None
+
+ comm = WIDGET_COMM_MANAGER.comms.get(model_id) # type: ignore[arg-type]
+ if comm is None or not comm.esm:
+ return None
+
+ import marimo._output.data.data as mo_data
+ from marimo._plugins.core.web_component import build_ui_plugin
+ from marimo._utils.code import hash_code
+
+ js_url = mo_data.js(comm.esm).url
+ js_hash = hash_code(comm.esm)
+
+ inner = build_ui_plugin(
+ component_name="marimo-anywidget",
+ initial_value={"model_id": model_id},
+ label=None,
+ args={
+ "js-url": js_url,
+ "js-hash": js_hash,
+ },
+ )
+ # Wrap in <marimo-ui-element> so the plugin gets proper lifecycle
+ # management (remount on re-run via random-id change).
+ html = (
+ f"<marimo-ui-element object-id='{model_id}' "
+ f"random-id='{model_id}'>"
+ f"{inner}"
+ f"</marimo-ui-element>"
+ )
+ return ("text/html", html)
+
+
def maybe_get_repr_formatter(
obj: Any,
) -> Optional[Callable[[Any], tuple[KnownMimeType, str]]]:
@@ -95,6 +156,15 @@ def maybe_get_repr_formatter(
f"data:{mime_key};base64,{data}"
)
+ # If this is an anywidget descriptor-based widget,
+ # produce <marimo-anywidget> HTML (same as mo.ui.anywidget)
+ # instead of the raw mimebundle. Traditional jupyter
+ # widgets pass through as the mimebundle (error banner).
+ if isinstance(contents, dict):
+ anywidget_result = _maybe_as_anywidget_html(contents)
+ if anywidget_result is not None:
+ return anywidget_result
+
# Remove text/plain from the mimebundle if it's present
# since there are other representations available
# N.B. We cannot pass this as an argument to the method
diff --git a/marimo/_plugins/ui/_impl/anywidget/comm_provider.py b/marimo/_plugins/ui/_impl/anywidget/comm_provider.py
new file mode 100644
index 0000000000..c5771aab1b
--- /dev/null
+++ b/marimo/_plugins/ui/_impl/anywidget/comm_provider.py
@@ -0,0 +1,106 @@
+# Copyright 2026 Marimo. All rights reserved.
+"""Comm backend for the ``comm`` library.
+
+Patches ``comm.create_comm`` so that anywidget's descriptor API
+(``MimeBundleDescriptor``) creates comms that broadcast through
+marimo's notification system instead of being silent no-ops.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Optional, Union
+from uuid import uuid4
+
+from marimo._loggers import marimo_logger
+from marimo._plugins.ui._impl.anywidget.init import (
+ WIDGET_COMM_MANAGER,
+ CommLifecycleItem,
+)
+from marimo._plugins.ui._impl.comm import MarimoComm
+from marimo._runtime.context import ContextNotInitializedError, get_context
+from marimo._types.ids import WidgetModelId
+
+LOGGER = marimo_logger()
+
+
+def _is_anywidget_comm(
+ target_name: str, data: Optional[dict[str, Any]]
+) -> bool:
+ """Check if this comm is being opened by anywidget.
+
+ anywidget's ``open_comm`` always uses ``target_name="jupyter.widget"``
+ and includes ``_model_module: "anywidget"`` in the state.
+ """
+ if target_name != "jupyter.widget":
+ return False
+ if data is None:
+ return False
+ state = data.get("state", {})
+ return bool(state.get("_model_module") == "anywidget")
+
+
+def patch_comm_create() -> None:
+ """Replace ``comm.create_comm`` with a marimo-backed implementation.
+
+ Only intercepts comms created by anywidget (identified by
+ ``target_name`` and ``_model_module``). All other comms fall
+ through to a no-op ``DummyComm``.
+
+ This is idempotent -- calling it multiple times is safe.
+ """
+ try:
+ import comm
+ from comm import DummyComm
+ except ImportError:
+ return
+
+ def _marimo_create_comm(
+ *,
+ target_name: str = "comm",
+ data: Optional[dict[str, Any]] = None,
+ metadata: Optional[dict[str, Any]] = None,
+ buffers: Optional[list[Any]] = None,
+ comm_id: Optional[str] = None,
+ **kwargs: Any,
+ ) -> Union[MarimoComm, DummyComm]:
+ if not _is_anywidget_comm(target_name, data):
+ LOGGER.warning(
+ "comm.create_comm called with target_name=%r but "
+ "not recognized as anywidget; returning no-op comm",
+ target_name,
+ )
+ return DummyComm(
+ target_name=target_name,
+ data=data,
+ metadata=metadata,
+ buffers=buffers,
+ comm_id=comm_id,
+ **kwargs,
+ )
+
+ resolved_id = WidgetModelId(comm_id or uuid4().hex)
+
+ if data is not None:
+ # Tag with method="open" so MarimoComm._broadcast creates a
+ # ModelOpen (not ModelUpdate) on first send.
+ data = {**data, "method": "open"}
+
+ c = MarimoComm(
+ comm_id=resolved_id,
+ comm_manager=WIDGET_COMM_MANAGER,
+ target_name=target_name,
+ data=data,
+ metadata=metadata,
+ buffers=buffers,
+ **kwargs,
+ )
+ # Register lifecycle cleanup so the comm is closed when
+ # the cell is re-run or deleted.
+ try:
+ ctx = get_context()
+ ctx.cell_lifecycle_registry.add(CommLifecycleItem(c))
+ except ContextNotInitializedError:
+ pass
+ return c
+
+ comm.create_comm = _marimo_create_comm # type: ignore[assignment]
diff --git a/marimo/_plugins/ui/_impl/comm.py b/marimo/_plugins/ui/_impl/comm.py
index b42ef76c08..d52b2b6708 100644
--- a/marimo/_plugins/ui/_impl/comm.py
+++ b/marimo/_plugins/ui/_impl/comm.py
@@ -165,6 +165,12 @@ class MarimoComm:
) -> None:
"""Open the comm and send initial state."""
LOGGER.debug("Opening comm %s", self.comm_id)
+ # Stash anywidget ESM info from the open state so it can be
+ # looked up later by model_id (used by repr_formatters to
+ # produce <marimo-anywidget> HTML).
+ state = (data or {}).get("state", {})
+ esm = state.get("_esm")
+ self.esm: Optional[str] = esm if isinstance(esm, str) and esm else None
self.comm_manager.register_comm(self)
try:
self._broadcast(data or {}, buffers or [])
diff --git a/marimo/_runtime/runner/hooks_post_execution.py b/marimo/_runtime/runner/hooks_post_execution.py
index c825aa694e..a4c237b21c 100644
--- a/marimo/_runtime/runner/hooks_post_execution.py
+++ b/marimo/_runtime/runner/hooks_post_execution.py
@@ -265,13 +265,19 @@ def _store_reference_to_output(
) -> None:
del ctx
- # Stores a reference to the output if it contains a UIElement;
- # this is required to make RPCs work for unnamed UI elements.
+ # Stores a reference to the output if it contains a UIElement
+ # (required for RPCs on unnamed UI elements) or if it has a
+ # _repr_mimebundle_ method (required to keep descriptor-based
+ # anywidgets alive — their comm is closed on GC).
+ # The _repr_mimebundle_ check is intentionally broad; the cost
+ # is just one extra reference that's cleared on re-run.
if isinstance(run_result.output, UIElement):
cell.set_output(run_result.output)
elif run_result.output is not None:
if contains_instance(run_result.output, UIElement):
cell.set_output(run_result.output)
+ elif callable(getattr(run_result.output, "_repr_mimebundle_", None)):
+ cell.set_output(run_result.output)
def _store_state_reference(
diff --git a/tests/_plugins/ui/_impl/anywidget/test_comm_provider.py b/tests/_plugins/ui/_impl/anywidget/test_comm_provider.py
new file mode 100644
index 0000000000..96551a905b
--- /dev/null
+++ b/tests/_plugins/ui/_impl/anywidget/test_comm_provider.py
@@ -0,0 +1,164 @@
+# Copyright 2026 Marimo. All rights reserved.
+from __future__ import annotations
+
+import pytest
+
+from marimo._dependencies.dependencies import DependencyManager
+
+HAS_DEPS = DependencyManager.anywidget.has() and DependencyManager.has("comm")
+
+
[email protected](not HAS_DEPS, reason="anywidget/comm not installed")
+class TestPatchCommCreate:
+ @staticmethod
+ def test_patches_comm_create() -> None:
+ import comm
+
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+
+ original = comm.create_comm
+ patch_comm_create()
+ assert comm.create_comm is not original
+ # Restore
+ comm.create_comm = original
+
+ @staticmethod
+ def test_anywidget_comm_returns_marimo_comm() -> None:
+ import comm
+
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+ from marimo._plugins.ui._impl.comm import MarimoComm
+
+ original = comm.create_comm
+ patch_comm_create()
+ try:
+ c = comm.create_comm(
+ target_name="jupyter.widget",
+ data={
+ "state": {
+ "_model_module": "anywidget",
+ "_model_name": "AnyModel",
+ "_esm": "export default {}",
+ },
+ "buffer_paths": [],
+ },
+ )
+ assert isinstance(c, MarimoComm)
+ assert c.esm == "export default {}"
+ c.close()
+ finally:
+ comm.create_comm = original
+
+ @staticmethod
+ def test_non_anywidget_comm_returns_dummy() -> None:
+ import comm
+ from comm import DummyComm
+
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+
+ original = comm.create_comm
+ patch_comm_create()
+ try:
+ c = comm.create_comm(
+ target_name="some.other.target",
+ data={"state": {"foo": "bar"}},
+ )
+ assert isinstance(c, DummyComm)
+ finally:
+ comm.create_comm = original
+
+ @staticmethod
+ def test_idempotent() -> None:
+ import comm
+
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+
+ original = comm.create_comm
+ patch_comm_create()
+ first = comm.create_comm
+ patch_comm_create()
+ second = comm.create_comm
+ # Second patch wraps the first — both should work
+ assert first is not original
+ assert second is not original
+ comm.create_comm = original
+
+
[email protected](not HAS_DEPS, reason="anywidget/comm not installed")
+class TestMaybeAsAnywidgetHtml:
+ @staticmethod
+ def test_produces_html_for_anywidget_mimebundle() -> None:
+ import comm
+
+ from marimo._output.formatters.repr_formatters import (
+ _maybe_as_anywidget_html,
+ )
+ from marimo._plugins.ui._impl.anywidget.comm_provider import (
+ patch_comm_create,
+ )
+
+ original = comm.create_comm
+ patch_comm_create()
+ try:
+ esm = (
+ "export default { render({ el }) { el.textContent = 'hi'; } }"
+ )
+ c = comm.create_comm(
+ target_name="jupyter.widget",
+ data={
+ "state": {
+ "_model_module": "anywidget",
+ "_model_name": "AnyModel",
+ "_esm": esm,
+ },
+ "buffer_paths": [],
+ },
+ )
+ model_id = c.comm_id
+
+ contents = {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": model_id,
+ "version_major": 2,
+ },
+ }
+ result = _maybe_as_anywidget_html(contents)
+ assert result is not None
+ mime, html = result
+ assert mime == "text/html"
+ assert "marimo-anywidget" in html
+ assert "marimo-ui-element" in html
+ assert str(model_id) in html
+ c.close()
+ finally:
+ comm.create_comm = original
+
+ @staticmethod
+ def test_returns_none_for_non_anywidget() -> None:
+ from marimo._output.formatters.repr_formatters import (
+ _maybe_as_anywidget_html,
+ )
+
+ contents = {
+ "application/vnd.jupyter.widget-view+json": {
+ "model_id": "nonexistent",
+ "version_major": 2,
+ },
+ }
+ assert _maybe_as_anywidget_html(contents) is None
+
+ @staticmethod
+ def test_returns_none_for_no_widget_view() -> None:
+ from marimo._output.formatters.repr_formatters import (
+ _maybe_as_anywidget_html,
+ )
+
+ assert _maybe_as_anywidget_html({"text/plain": "hello"}) is None