cositos 0.1.0__py3-none-any.whl

cositos/__init__.py

@@ -0,0 +1,40 @@
+"""cositos: binding-free anywidget-style backend core."""
+
+from cositos.buffers import put_buffers, remove_buffers
+from cositos.embed import embed_html, embed_snippet, write_html
+from cositos.model import Widget
+from cositos.protocol import (
+    PROTOCOL_VERSION,
+    build_comm_open,
+    build_custom,
+    build_update,
+    parse_message,
+)
+from cositos.serialize import (
+    check_references,
+    dump_document,
+    dump_model,
+    load_document,
+    load_model,
+)
+from cositos.transport import Transport
+
+__all__ = [
+    "PROTOCOL_VERSION",
+    "Transport",
+    "Widget",
+    "build_comm_open",
+    "build_custom",
+    "build_update",
+    "check_references",
+    "dump_document",
+    "dump_model",
+    "embed_html",
+    "embed_snippet",
+    "load_document",
+    "load_model",
+    "parse_message",
+    "put_buffers",
+    "remove_buffers",
+    "write_html",
+]

cositos/buffers.py

@@ -0,0 +1,129 @@
+"""Binary-buffer split/merge, faithful to widget protocol v2 (nested buffer_paths).
+
+A "binary" value is ``bytes``, ``bytearray``, or ``memoryview``. On the wire, binary
+values are stripped out of the JSON state into a parallel ``buffers`` list, and their
+locations recorded in ``buffer_paths``. A path ending in a dict key is *removed* from
+the state; a path ending in a list index is replaced by ``None`` so positions are kept.
+"""
+
+from __future__ import annotations
+
+import sys
+from collections.abc import Iterable
+from typing import Any
+
+BinaryType = (bytes, bytearray, memoryview)
+
+#: Max container nesting depth `remove_buffers` will descend before raising a clear error
+#: (rather than an opaque ``RecursionError``). Deeper widget state is pathological.
+_MAX_DEPTH = 500
+
+
+def _items(substate: Any) -> Iterable[tuple[Any, Any]]:
+    """Yield ``(key, value)`` pairs for a list (index keys) or dict (str keys)."""
+    if isinstance(substate, (list, tuple)):
+        return enumerate(substate)
+    return substate.items()  # type: ignore[no-any-return]
+
+
+def _clone(substate: Any) -> Any:
+    return list(substate) if isinstance(substate, (list, tuple)) else dict(substate)
+
+
+def _extract_binary(clone: Any, key: Any) -> None:
+    """Blank a binary slot: ``None`` for list indices, remove for dict keys."""
+    if isinstance(clone, list):
+        clone[key] = None
+    else:
+        del clone[key]
+
+
+def _handle_item(
+    substate: Any,
+    clone: Any,
+    key: Any,
+    value: Any,
+    path: list[Any],
+    buffer_paths: list[list[Any]],
+    buffers: list[Any],
+    ancestors: tuple[int, ...],
+    depth: int,
+) -> Any:
+    """Process one ``(key, value)``; return the (possibly newly created) clone."""
+    if isinstance(value, BinaryType):
+        clone = clone if clone is not None else _clone(substate)
+        _extract_binary(clone, key)
+        buffers.append(value)
+        buffer_paths.append([*path, key])
+    elif isinstance(value, (list, tuple, dict)):
+        new_value = _separate(value, [*path, key], buffer_paths, buffers, ancestors, depth + 1)
+        if new_value is not value:
+            clone = clone if clone is not None else _clone(substate)
+            clone[key] = new_value
+    return clone
+
+
+def _separate(
+    substate: Any,
+    path: list[Any],
+    buffer_paths: list[list[Any]],
+    buffers: list[Any],
+    ancestors: tuple[int, ...] = (),
+    depth: int = 0,
+) -> Any:
+    """Recurse into dicts/lists, extracting binary values. Returns a cloned substate.
+
+    Clones a container only when it actually changes, mirroring the ipywidgets
+    algorithm so untouched subtrees keep their identity. A container that appears among
+    its own ancestors is a cycle, and nesting beyond :data:`_MAX_DEPTH` is capped — both
+    raise a clear :class:`ValueError` naming the path rather than a ``RecursionError``
+    (cositos-915). Shared but acyclic subtrees (a DAG) are fine: only the current
+    ancestor chain is checked, not every visited node.
+    """
+    if not isinstance(substate, (list, tuple, dict)):
+        return substate
+    if depth > _MAX_DEPTH:
+        raise ValueError(f"state nesting exceeds {_MAX_DEPTH} levels at path {path}")
+    if id(substate) in ancestors:
+        raise ValueError(f"cyclic reference detected in state at path {path}")
+    ancestors = (*ancestors, id(substate))
+
+    clone: Any = None
+    for key, value in _items(substate):
+        clone = _handle_item(
+            substate, clone, key, value, path, buffer_paths, buffers, ancestors, depth
+        )
+    return clone if clone is not None else substate
+
+
+def remove_buffers(state: Any) -> tuple[Any, list[list[Any]], list[Any]]:
+    """Return ``(state_without_buffers, buffer_paths, buffers)``.
+
+    Nesting is capped at :data:`_MAX_DEPTH`; the interpreter recursion limit is
+    temporarily raised so that cap (a clear error) trips before a raw ``RecursionError``.
+    """
+    buffer_paths: list[list[Any]] = []
+    buffers: list[Any] = []
+    needed = (_MAX_DEPTH + 2) * 2 + 200  # ~2 frames per nesting level, plus headroom
+    old_limit = sys.getrecursionlimit()
+    try:
+        if old_limit < needed:
+            sys.setrecursionlimit(needed)
+        stripped = _separate(state, [], buffer_paths, buffers)
+    finally:
+        sys.setrecursionlimit(old_limit)
+    return stripped, buffer_paths, buffers
+
+
+def put_buffers(state: Any, buffer_paths: list[list[Any]], buffers: list[Any]) -> None:
+    """Inverse of :func:`remove_buffers`; mutates ``state`` in place.
+
+    ``buffer_paths`` and ``buffers`` must be the same length (``strict=True``); a mismatch
+    raises :class:`ValueError` rather than silently leaving a placeholder in ``state`` or
+    dropping a buffer (cositos-y07). This matches :func:`encode_buffers_base64`.
+    """
+    for path, buffer in zip(buffer_paths, buffers, strict=True):
+        obj = state
+        for key in path[:-1]:
+            obj = obj[key]
+        obj[path[-1]] = buffer

cositos/contrib/__init__.py

@@ -0,0 +1,13 @@
+"""Optional, Python-only conveniences that sit *outside* the fixture-certified core.
+
+Everything under :mod:`cositos.contrib` may depend on the wider Python widget ecosystem
+(notably ``ipywidgets``). None of it is imported by :mod:`cositos` itself, so the pure,
+cross-language-portable core stays free of those dependencies. Import from here explicitly:
+
+    from cositos.contrib import harvest, harvest_html
+"""
+
+from cositos.contrib.controls import dropdown, hbox, int_slider, vbox
+from cositos.contrib.harvest import harvest, harvest_html
+
+__all__ = ["harvest", "harvest_html", "int_slider", "dropdown", "vbox", "hbox"]

cositos/contrib/controls.py

@@ -0,0 +1,175 @@
+"""A real, unmodified ``@jupyter-widgets/controls``/``base`` catalog — an optional extension.
+
+cositos' anti-goal is *reimplementing* the ipywidgets widget zoo (``docs/widgets.md``);
+this module does not reimplement it. It reuses the real frontend verbatim by building
+:data:`~cositos.serialize.ModelEntry` state dicts that carry the zoo's own identity
+(``_model_name``/``_model_module``/``_view_name``/``_view_module`` etc., pinned at module
+version ``2.0.0`` — the same choice already made by ``examples/composition/build.py``).
+``cositos.protocol.build_comm_open``/``cositos.model.Widget.send_state`` already merge
+``{**anywidget_defaults, **state}``, so a caller-supplied real-widget identity reaches the
+wire with zero core changes
+(``.wai/projects/cositos-core/research/2026-07-09-research-real-controls-widgets-as-optional-extension.md``,
+findings 1–3).
+
+Scope is intentionally trimmed (YAGNI) to exactly ``IntSlider``, ``Dropdown``, ``VBox``,
+``HBox`` and their required companion models — see
+``.wai/projects/cositos-core/designs/2026-07-09-design-controls-catalog-schema-and-scope.md``
+for the full catalog schema and the id-uniqueness rule this module implements (every call
+mints fresh companion-model ids; the catalog's own placeholder strings are never reused as
+real ids — :func:`cositos.serialize.dump_document` rejects duplicate ``model_id``s).
+
+**No ``ipywidgets``/``anywidget`` Python package is required.** This module builds plain
+state dicts from a static JSON catalog (``fixtures/controls-catalog.json``) plus the
+stdlib (``json``, ``uuid``) — it never imports either package (see
+``tests/test_contrib_controls.py::test_module_imports_no_optional_widget_packages`` for
+the automated guard). Manually re-verified 2026-07-09 in a fresh venv with neither
+``ipywidgets`` nor ``anywidget`` installed (``pip install -e .`` only): building and
+serializing an ``int_slider``/``vbox`` tree through :func:`cositos.serialize.dump_document`
+and :func:`cositos.embed.embed_html` succeeded.
+
+**Deliberately exempt from an OpenSpec requirement.** This mirrors
+:mod:`cositos.contrib.harvest`, the existing contrib precedent: contrib modules are
+optional, additive wrappers over the pure core (already OpenSpec-covered under
+``openspec/specs/{embed,protocol,serialization}``) and do not themselves gain a spec.
+
+**Correction to the design note, found by the real-browser check this ticket's acceptance
+criteria required (not by reading the source alone):** ``Dropdown``'s ``options``,
+``value``, and ``label`` traits carry no ``sync=True`` tag in ipywidgets
+(``widget_selection.py``) — only ``_options_labels`` (label strings) and ``index`` are on
+the wire. A first catalog draft that put ``options``/``value`` straight into state
+rendered an empty, unselectable ``<select>`` in a real browser; :func:`dropdown` below
+translates its ergonomic ``options``/``value`` parameters into the real
+``_options_labels``/``index`` wire fields.
+
+**Accepted, documented risk (unresolved from the research note):** the pinned
+``2.0.0`` module version for ``@jupyter-widgets/controls``/``base`` is verified against
+the CDN ``@jupyter-widgets/html-manager`` (static export) and a bare subprocess
+``ipykernel`` comm (live kernel) — *not* against a real, currently-installed JupyterLab's
+bundled ``@jupyter-widgets`` frontend extension version. Treat that combination as an
+open risk specifically for the live-in-JupyterLab case until it is checked.
+"""
+
+from __future__ import annotations
+
+import json
+import uuid
+from pathlib import Path
+from typing import Any
+
+from cositos.serialize import ModelEntry
+
+__all__ = ["int_slider", "dropdown", "vbox", "hbox"]
+
+_CATALOG_PATH = (
+    Path(__file__).resolve().parent.parent.parent.parent / "fixtures" / "controls-catalog.json"
+)
+
+
+def _load_catalog() -> dict[str, Any]:
+    return json.loads(_CATALOG_PATH.read_text())  # type: ignore[no-any-return]
+
+
+_CATALOG = _load_catalog()
+
+
+def _mint_id(root_id: str, role: str) -> str:
+    return f"{root_id}-{role}"
+
+
+def _identity(spec: dict[str, Any]) -> dict[str, Any]:
+    return {
+        "_model_name": spec["model_name"],
+        "_model_module": spec["model_module"],
+        "_model_module_version": spec["model_module_version"],
+        "_view_name": spec["view_name"],
+        "_view_module": spec["view_module"],
+        "_view_module_version": spec["view_module_version"],
+    }
+
+
+def _build(
+    catalog_key: str,
+    overrides: dict[str, Any],
+    *,
+    model_id: str | None = None,
+) -> list[ModelEntry]:
+    """Build one catalog entry's widget + its freshly id'd companion models.
+
+    The widget's own entry is always first in the returned list, followed by one entry
+    per companion (order matches the catalog's ``companions`` list). Every companion gets
+    a fresh id derived from this call's root id — never the catalog's literal
+    placeholder string — per the design note's id-uniqueness rule.
+    """
+    spec = _CATALOG[catalog_key]
+    root_id = model_id or uuid.uuid4().hex
+
+    state = dict(spec["default_state"])
+    companion_entries: list[ModelEntry] = []
+    for companion in spec["companions"]:
+        key = companion["key_in_default_state"]
+        companion_id = _mint_id(root_id, key)
+        state[key] = f"IPY_MODEL_{companion_id}"
+        companion_state = {
+            "_model_name": companion["model_name"],
+            "_model_module": companion["model_module"],
+            "_model_module_version": companion["model_module_version"],
+            "_view_name": companion["view_name"],
+            "_view_module": companion["view_module"],
+            "_view_module_version": companion["view_module_version"],
+        }
+        companion_entries.append((companion_id, companion_state))
+
+    state.update(overrides)
+    widget_state = {**_identity(spec), **state}
+    return [(root_id, widget_state), *companion_entries]
+
+
+def int_slider(value: int = 0, min: int = 0, max: int = 100, **overrides: Any) -> list[ModelEntry]:
+    """A real ``@jupyter-widgets/controls`` ``IntSliderModel`` + its style/layout companions."""
+    return _build("int_slider", {"value": value, "min": min, "max": max, **overrides})
+
+
+def dropdown(options: Any, value: Any = None, **overrides: Any) -> list[ModelEntry]:
+    """A real ``@jupyter-widgets/controls`` ``DropdownModel`` + its style/layout companions.
+
+    ``options``/``value`` are the ergonomic, ipywidgets-``Dropdown``-constructor-shaped
+    inputs; on the wire only ``_options_labels`` (the label strings) and ``index`` are
+    synced traits (``Dropdown``'s own ``options``/``value``/``label`` traits carry no
+    ``sync=True`` tag in ipywidgets' source — confirmed empirically: a naive catalog entry
+    that put ``options``/``value`` straight into state rendered an empty, unselectable
+    dropdown in a real browser). Pass ``index=`` directly in ``overrides`` to bypass the
+    ``value``-to-``index`` lookup (e.g. when ``value`` is unhashable or repeated).
+    """
+    labels = [str(option) for option in options]
+    index = overrides.pop("index", None)
+    if index is None and value is not None:
+        str_value = str(value)
+        index = labels.index(str_value) if str_value in labels else None
+    return _build("dropdown", {"_options_labels": labels, "index": index, **overrides})
+
+
+def _box(catalog_key: str, children: list[list[ModelEntry]], **overrides: Any) -> list[ModelEntry]:
+    child_refs = [f"IPY_MODEL_{child[0][0]}" for child in children]
+    own = _build(catalog_key, {"children": child_refs, **overrides})
+    descendants = [entry for child in children for entry in child]
+    return own + descendants
+
+
+def vbox(children: list[list[ModelEntry]], **overrides: Any) -> list[ModelEntry]:
+    """A real ``@jupyter-widgets/controls`` ``VBoxModel`` laying out ``children`` vertically.
+
+    ``children`` is a list of previously built entries-lists (e.g. the output of
+    :func:`int_slider`/:func:`dropdown`/:func:`vbox`/:func:`hbox`) — this widget's
+    ``children`` trait references each child's root id, and the returned entries list
+    flattens in every descendant so the whole tree serializes as one document.
+    """
+    return _box("vbox", children, **overrides)
+
+
+def hbox(children: list[list[ModelEntry]], **overrides: Any) -> list[ModelEntry]:
+    """A real ``@jupyter-widgets/controls`` ``HBoxModel`` laying out ``children`` horizontally.
+
+    See :func:`vbox` for the ``children`` composition contract (identical, horizontal
+    layout only).
+    """
+    return _box("hbox", children, **overrides)

cositos/contrib/harvest.py

@@ -0,0 +1,86 @@
+"""Wrap an *existing* ipywidgets tree as a cositos :data:`~cositos.serialize.Document`.
+
+The reuse insight this module packages: ``ipywidgets.embed.embed_data(views=[w])`` already
+walks a widget and its transitive children and returns a ``manager_state`` that is, byte
+for byte, a cositos v2 Widget-State :data:`~cositos.serialize.Document`. So any app or
+library built on ipywidgets — including anywidget-based plotting widgets (plotly
+``FigureWidget``, altair ``JupyterChart``) — can be serialized, round-tripped, and
+statically embedded through cositos with **no core changes**. This is the thin,
+Python-only, optional wrapper over that call; it never enters the pure core.
+
+``embed_data`` is the current, supported entry point; the older ``Widget.widgets`` global
+registry is deprecated and must not be used.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from cositos.embed import embed_html
+from cositos.serialize import Document
+
+if TYPE_CHECKING:  # pragma: no cover - typing only
+    from ipywidgets import Widget
+
+__all__ = ["harvest", "harvest_html"]
+
+
+def _embed_data(widgets: tuple[Any, ...]) -> dict[str, Any]:
+    """Call ``ipywidgets.embed.embed_data`` for ``widgets`` with clear failures.
+
+    Always passes ``drop_defaults=False``. ``embed_data``'s own default
+    (``drop_defaults=True``) compares each synced trait's *current* value against its
+    *class-level default* and omits it when they match — but a widget that bundles its
+    own frontend commonly declares that content (``_esm``/``_css``) as the trait's class
+    default rather than setting it per instance (Plotly's ``FigureWidget`` and Altair's
+    ``JupyterChart`` both do this). ``drop_defaults=True`` then silently drops ``_esm``
+    from the harvested state, and the CDN anywidget runtime's ``AnyView`` throws
+    (``isHref(undefined)``) instead of rendering (cositos-b2t). ``harvest``'s own
+    docstring promise — a verbatim capture — requires the non-dropping default anyway.
+
+    Raises
+    ------
+    ImportError
+        If ipywidgets is not installed (this is an optional dependency of contrib).
+    ValueError
+        If no widget was given (an empty document is never what a caller wants here).
+    """
+    if not widgets:
+        raise ValueError("harvest requires at least one widget to serialize")
+    try:
+        from ipywidgets.embed import embed_data
+    except ImportError as exc:  # pragma: no cover - exercised only without ipywidgets
+        raise ImportError(
+            "cositos.contrib.harvest requires ipywidgets; install it with "
+            "`pip install ipywidgets` (or the cositos 'oracle' extra)"
+        ) from exc
+    data: dict[str, Any] = embed_data(views=list(widgets), drop_defaults=False)
+    return data
+
+
+def harvest(*widgets: Widget) -> Document:
+    """Return a cositos :data:`~cositos.serialize.Document` for existing ipywidgets ``widgets``.
+
+    Captures each widget and its transitive children (children are held by reference as
+    ``"IPY_MODEL_<id>"`` strings, exactly like a natively built cositos document). The
+    result round-trips through :func:`cositos.serialize.load_document` /
+    :func:`~cositos.serialize.dump_document` and renders via
+    :func:`cositos.embed.embed_html`.
+
+    For static export prefer :func:`harvest_html`, which renders only the top-level
+    widgets as views (a widget expands to extra layout/style models that have no view).
+    """
+    document: Document = _embed_data(widgets)["manager_state"]
+    return document
+
+
+def harvest_html(*widgets: Widget, **embed_kwargs: Any) -> str:
+    """Serialize ``widgets`` and render them to a self-contained static HTML page.
+
+    Only the passed top-level ``widgets`` become rendered views; their auxiliary
+    layout/style models are embedded as state but not turned into (viewless) view scripts.
+    ``embed_kwargs`` are forwarded to :func:`cositos.embed.embed_html` (e.g. ``title``).
+    """
+    data = _embed_data(widgets)
+    view_ids = [spec["model_id"] for spec in data["view_specs"]]
+    return embed_html(data["manager_state"], views=view_ids, **embed_kwargs)

cositos/embed.py

@@ -0,0 +1,128 @@
+"""Static-HTML export: render a serialized widget :data:`Document` to a self-contained page.
+
+Reuses the stock ipywidgets embed format \u2014 a ``application/vnd.jupyter.widget-state+json``
+block plus per-view ``widget-view+json`` scripts \u2014 rendered by the CDN-hosted
+``@jupyter-widgets/html-manager``. The anywidget model/view module resolves from jsDelivr
+at render time, so no frontend is bundled and no kernel is needed to display a saved UI.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from collections.abc import Iterable
+from pathlib import Path
+from typing import Any
+
+from cositos.protocol import ANYWIDGET_MODULE_VERSION, view_identity
+from cositos.serialize import Document
+
+STATE_MIMETYPE = "application/vnd.jupyter.widget-state+json"
+VIEW_MIMETYPE = "application/vnd.jupyter.widget-view+json"
+
+_DEFAULT_HTML_MANAGER_VERSION = "1"
+_REQUIREJS_URL = "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"
+_EMBED_AMD_URL = "https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@{v}/dist/embed-amd.js"
+_EMBED_URL = "https://cdn.jsdelivr.net/npm/@jupyter-widgets/html-manager@{v}/dist/embed.js"
+
+# Neutralise the only sequences that can break out of a <script> element, per
+# https://html.spec.whatwg.org/multipage/scripting.html#restrictions-for-contents-of-script-elements
+_SCRIPT_ESCAPE = re.compile(r"<(script|/script|!--)", re.IGNORECASE)
+
+
+def _escape_script(text: str) -> str:
+    return _SCRIPT_ESCAPE.sub(r"\\u003c\1", text)
+
+
+def with_view_identity(document: Document) -> Document:
+    """Return a copy of ``document`` with anywidget *view* identity merged into each
+    model's ``state`` — the form the CDN html-manager needs to render.
+
+    Every static-render surface (this module's :func:`embed_html`, and the
+    nbconvert/Quarto/JupyterBook builder) routes its document through here.
+
+    The pure serialization codec (:func:`cositos.serialize.dump_document`) stays a lossless
+    save/restore of user state and carries no rendering identity — exactly like the live
+    comm path keeps view identity out of stored state. Static rendering is the analog of
+    the live ``build_comm_open`` path, so this is where the html-manager's required view
+    identity (``_view_name`` etc.) is injected, else the CDN manager cannot pick a view
+    class and the page renders only a JS error (cositos-mx7). Host-set state wins over the
+    injected defaults.
+    """
+    records = document.get("state", {})
+    enriched = {}
+    for model_id, record in records.items():
+        version = record.get("model_module_version", ANYWIDGET_MODULE_VERSION)
+        enriched[model_id] = {
+            **record,
+            "state": {**view_identity(version), **record.get("state", {})},
+        }
+    return {**document, "state": enriched}
+
+
+def embed_snippet(
+    document: Document,
+    *,
+    views: Iterable[str] | None = None,
+    requirejs: bool = True,
+    html_manager_version: str = _DEFAULT_HTML_MANAGER_VERSION,
+) -> str:
+    """Render the embed *snippet* (loader + state + view scripts), without an HTML wrapper.
+
+    Use this to drop a widget into an existing page (a Quarto/blog cell, a template). See
+    :func:`embed_html` for a complete standalone page.
+    """
+    document = with_view_identity(document)
+    model_ids = list(views) if views is not None else list(document.get("state", {}))
+    state_block = _escape_script(json.dumps(document, indent=2))
+    view_blocks = "\n".join(
+        f'<script type="{VIEW_MIMETYPE}">\n'
+        + _escape_script(json.dumps({"version_major": 2, "version_minor": 0, "model_id": mid}))
+        + "\n</script>"
+        for mid in model_ids
+    )
+    loader = _loader(requirejs, html_manager_version)
+    return f'{loader}\n<script type="{STATE_MIMETYPE}">\n{state_block}\n</script>\n{view_blocks}\n'
+
+
+def embed_html(
+    document: Document,
+    *,
+    views: Iterable[str] | None = None,
+    title: str = "cositos widgets",
+    requirejs: bool = True,
+    html_manager_version: str = _DEFAULT_HTML_MANAGER_VERSION,
+) -> str:
+    """Render ``document`` (a :func:`cositos.serialize.dump_document` result) to a full page.
+
+    ``views`` selects which model ids get a rendered view (default: every model in the
+    document). The full state is always embedded so a referenced model is present for a
+    container to resolve. Note that a reference (``"IPY_MODEL_<id>"``) only resolves to a
+    child model when the *holding* model declares a widget-reference trait — plain
+    anywidget (``AnyModel``) widgets do not, so refs between them stay literal strings. See
+    ``examples/composition/`` for the controls-container recipe that does resolve.
+    """
+    snippet = embed_snippet(
+        document, views=views, requirejs=requirejs, html_manager_version=html_manager_version
+    )
+    return (
+        '<!DOCTYPE html>\n<html lang="en">\n<head>\n'
+        '    <meta charset="UTF-8">\n'
+        f"    <title>{title}</title>\n"
+        "</head>\n<body>\n"
+        f"{snippet}"
+        "</body>\n</html>\n"
+    )
+
+
+def write_html(path: str | Path, document: Document, **kwargs: Any) -> None:
+    """Write :func:`embed_html` output for ``document`` to ``path``."""
+    Path(path).write_text(embed_html(document, **kwargs))
+
+
+def _loader(requirejs: bool, version: str) -> str:
+    embed_url = (_EMBED_AMD_URL if requirejs else _EMBED_URL).format(v=version)
+    script = f'<script src="{embed_url}" crossorigin="anonymous"></script>'
+    if requirejs:
+        return f'<script src="{_REQUIREJS_URL}" crossorigin="anonymous"></script>\n{script}'
+    return script

cositos/jupyter.py

@@ -0,0 +1,98 @@
+"""Jupyter host adapter: a :class:`~cositos.transport.Transport` over the ``comm`` package.
+
+This is the piece that plugs the pure protocol core into a real Jupyter kernel
+(ipykernel, and anything else that provides ``comm``). It mirrors what
+anywidget's ``open_comm``/``ReprMimeBundle`` do, but stays a thin Transport so the core
+remains kernel-agnostic.
+
+Usage in a kernel::
+
+    from cositos import Widget
+    from cositos.jupyter import CommTransport
+
+    state = {"_esm": ESM, "value": 0}
+    store = dict(state)
+    widget = Widget(
+        CommTransport(),
+        get_state=lambda: dict(store),
+        set_state=store.update,
+    )
+    widget.open()          # sends comm_open over the kernel's iopub
+    widget.mimebundle()    # -> display via _repr_mimebundle_
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any, Callable
+
+if TYPE_CHECKING:  # pragma: no cover
+    from comm.base_comm import BaseComm
+
+
+class CommTransport:
+    """Adapt the ``comm`` package to the cositos :class:`Transport` protocol.
+
+    The comm is created lazily on the first ``comm_open`` send, carrying the initial
+    state exactly as the protocol requires (no separate open + update round-trip).
+    """
+
+    supports_receive: bool = True
+
+    def __init__(self) -> None:
+        self._comm: BaseComm | None = None
+        self._pending: Callable[[dict[str, Any], list[Any]], None] | None = None
+
+    @property
+    def comm_id(self) -> str:
+        """The comm id (widget ``model_id``); empty until opened."""
+        return self._comm.comm_id if self._comm is not None else ""
+
+    def send(
+        self,
+        msg_type: str,
+        content: dict[str, Any],
+        buffers: list[Any] | None = None,
+        metadata: dict[str, Any] | None = None,
+    ) -> None:
+        if msg_type == "comm_open":
+            self._open(content, buffers or [], metadata or {})
+        elif msg_type == "comm_msg":
+            self._require_comm().send(data=content, buffers=buffers or None)
+        elif msg_type == "comm_close":
+            self._require_comm().close()
+        else:  # pragma: no cover - defensive
+            raise ValueError(f"Unknown comm message type: {msg_type!r}")
+
+    def on_message(self, callback: Callable[[dict[str, Any], list[Any]], None]) -> None:
+        if self._comm is None:
+            # Registered before open() created the comm; wire it up on open.
+            self._pending = callback
+            return
+        self._bind(callback)
+
+    # -- internals -------------------------------------------------------------
+
+    def _open(self, content: dict[str, Any], buffers: list[Any], metadata: dict[str, Any]) -> None:
+        import comm  # noqa: PLC0415
+
+        self._comm = comm.create_comm(
+            target_name="jupyter.widget",
+            data=content,
+            metadata=metadata,
+            buffers=buffers or None,
+        )
+        if self._pending is not None:
+            self._bind(self._pending)
+            self._pending = None
+
+    def _bind(self, callback: Callable[[dict[str, Any], list[Any]], None]) -> None:
+        def _on_msg(msg: dict[str, Any]) -> None:
+            data = msg["content"]["data"]
+            callback(data, msg.get("buffers", []))
+
+        self._require_comm().on_msg(_on_msg)
+
+    def _require_comm(self) -> BaseComm:
+        if self._comm is None:  # pragma: no cover - defensive
+            raise RuntimeError("comm not opened; call Widget.open() first")
+        return self._comm