From 9246f346ccbc8f7db2fcb2284c417d8c19c62fb5 Mon Sep 17 00:00:00 2001
From: Jichen Li <42854324+Roy-Kid@users.noreply.github.com>
Date: Sat, 4 Jul 2026 15:58:31 +0800
Subject: [PATCH 01/17] =?UTF-8?q?feat(render):=20rewrite=20VL=E2=86=92matp?=
 =?UTF-8?q?lotlib=20as=20a=20staged=20tree-walking=20interpreter=20(#1)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Replace the ad-hoc per-mark render.py prototype with a small interpreter
package (molplot.vlmpl) structured as four compiler passes: normalize →
bind scales → dispatch marks → finalize axes. Mark encoders read typed
channels instead of hardcoded field names, so marks and scales are extensible.

Fixes two Vega-Lite → matplotlib parity gaps the prototype had:
- positional scales are applied: log axes (scale.type) and explicit domains
  (scale.domain → axis limits) now reach the figure.
- per-layer transform filters are honoured, so a plain line chart no longer
  draws the stray marker-layer points; the detail channel splits series that
  share a legend colour.

render.py becomes a thin shim re-exporting molplot.vlmpl.render, preserving the
public molplot.render API. Adds test_vlmpl.py for the fixed behaviour.
---
 python/src/molplot/render.py         | 265 +--------------------------
 python/src/molplot/vlmpl/__init__.py |  18 ++
 python/src/molplot/vlmpl/axes.py     |  47 +++++
 python/src/molplot/vlmpl/data.py     |  52 ++++++
 python/src/molplot/vlmpl/interp.py   |  49 +++++
 python/src/molplot/vlmpl/marks.py    | 200 ++++++++++++++++++++
 python/src/molplot/vlmpl/model.py    | 154 ++++++++++++++++
 python/src/molplot/vlmpl/scales.py   |  67 +++++++
 python/tests/test_vlmpl.py           |  61 ++++++
 9 files changed, 658 insertions(+), 255 deletions(-)
 create mode 100644 python/src/molplot/vlmpl/__init__.py
 create mode 100644 python/src/molplot/vlmpl/axes.py
 create mode 100644 python/src/molplot/vlmpl/data.py
 create mode 100644 python/src/molplot/vlmpl/interp.py
 create mode 100644 python/src/molplot/vlmpl/marks.py
 create mode 100644 python/src/molplot/vlmpl/model.py
 create mode 100644 python/src/molplot/vlmpl/scales.py
 create mode 100644 python/tests/test_vlmpl.py

diff --git a/python/src/molplot/render.py b/python/src/molplot/render.py
index 07edec3..41ee121 100644
--- a/python/src/molplot/render.py
+++ b/python/src/molplot/render.py
@@ -1,263 +1,18 @@
-"""Vega-Lite → matplotlib renderer.
+"""Vega-Lite → matplotlib rendering — public entry point.
 
-Reads a self-contained Vega-Lite spec (the kind :mod:`molplot.specs` emits) and
-draws it with matplotlib under the unified preset style. This is the concrete
-mechanism behind "convert between the web and matplotlib via the Vega-Lite
-intermediate language": build one spec, render it in the browser *or* here for a
-publication figure.
+The implementation is the tree-walking interpreter in :mod:`molplot.vlmpl`
+(normalize → bind scales → dispatch marks → finalize axes). This module keeps
+the historical ``molplot.render`` import path stable.
 
-The translator targets the mark/encoding shapes MolPlot emits (line / point /
-bar / gantt). It is spec-driven (it reads fields and colour scales from the
-encoding) but not a general Vega-Lite engine — for pixel-exact web parity of an
-arbitrary spec, use ``vl-convert`` instead (see :func:`molplot.to_png`).
+Build one Vega-Lite spec with :mod:`molplot.specs` and render it in the browser
+(vega-embed / RawChart) *or* here to a publication figure — the equivalence is
+the whole point of routing through the Vega-Lite intermediate language. For
+pixel-exact web parity of an arbitrary spec, use ``vl-convert`` via
+:func:`molplot.to_png`.
 """
 
 from __future__ import annotations
 
-from contextlib import nullcontext
-from datetime import datetime
-from typing import Any, Sequence
-
-from .preset import DEFAULT_PRESET, Mode
-from .style import style as _style
+from .vlmpl import render
 
 __all__ = ["render"]
-
-
-def _ensure_ax(ax: Any) -> tuple[Any, Any]:
-    import matplotlib.pyplot as plt
-
-    if ax is not None:
-        return ax.figure, ax
-    fig, ax = plt.subplots()
-    return fig, ax
-
-
-def _field(enc: dict[str, Any], channel: str) -> str | None:
-    c = enc.get(channel)
-    return c.get("field") if isinstance(c, dict) else None
-
-
-def _color_lookup(color_enc: dict[str, Any] | None) -> tuple[str, dict[Any, str] | str | None]:
-    """Return (kind, mapping). kind in {'nominal','quantitative','none'}."""
-    if not isinstance(color_enc, dict):
-        return "none", None
-    if color_enc.get("type") == "quantitative":
-        scale = color_enc.get("scale") or {}
-        return "quantitative", scale.get("scheme")
-    scale = color_enc.get("scale")
-    if isinstance(scale, dict) and "domain" in scale and "range" in scale:
-        return "nominal", dict(zip(scale["domain"], scale["range"]))
-    return "literal", None  # field value *is* the colour
-
-
-def _scale_map(enc_channel: dict[str, Any] | None) -> dict[Any, float] | None:
-    if not isinstance(enc_channel, dict):
-        return None
-    scale = enc_channel.get("scale")
-    if isinstance(scale, dict) and "domain" in scale and "range" in scale:
-        return dict(zip(scale["domain"], scale["range"]))
-    return None
-
-
-def _values(node: dict[str, Any], top: list[dict[str, Any]]) -> list[dict[str, Any]]:
-    data = node.get("data")
-    if isinstance(data, dict) and isinstance(data.get("values"), list):
-        return data["values"]
-    return top
-
-
-def _as_num_time(v: Any) -> float:
-    import matplotlib.dates as mdates
-
-    if isinstance(v, (int, float)):
-        return float(v)
-    return mdates.date2num(datetime.fromisoformat(str(v).replace("Z", "+00:00")))
-
-
-def _draw_line(ax: Any, rows: list[dict[str, Any]], enc: dict[str, Any]) -> bool:
-    xf, yf = _field(enc, "x"), _field(enc, "y")
-    kind, cmap = _color_lookup(enc.get("color"))
-    color_field = _field(enc, "color")
-    width_map = _scale_map(enc.get("strokeWidth"))
-    op_map = _scale_map(enc.get("opacity"))
-    groups: dict[Any, list[dict[str, Any]]] = {}
-    for r in rows:
-        groups.setdefault(r.get(color_field) if color_field else None, []).append(r)
-    labelled = False
-    for key, grp in groups.items():
-        grp = sorted(grp, key=lambda r: r[xf])
-        color = cmap.get(key) if isinstance(cmap, dict) else None
-        lw = width_map.get(key) if width_map else None
-        alpha = op_map.get(key) if op_map else None
-        ax.plot(
-            [r[xf] for r in grp],
-            [r[yf] for r in grp],
-            label=None if key is None else str(key),
-            color=color,
-            linewidth=lw,
-            alpha=alpha,
-        )
-        labelled = labelled or key is not None
-    return labelled
-
-
-def _draw_point(ax: Any, rows: list[dict[str, Any]], enc: dict[str, Any], mark: dict[str, Any]) -> bool:
-    xf, yf = _field(enc, "x"), _field(enc, "y")
-    kind, cmap = _color_lookup(enc.get("color"))
-    cf = _field(enc, "color")
-    xs = [r[xf] for r in rows]
-    ys = [r[yf] for r in rows]
-    size = mark.get("size", 36)
-    if kind == "quantitative" and cf:
-        sc = ax.scatter(xs, ys, c=[r[cf] for r in rows], cmap=cmap, s=size)
-        ax.figure.colorbar(sc, ax=ax)
-    elif kind == "nominal" and isinstance(cmap, dict) and cf:
-        ax.scatter(xs, ys, c=[cmap.get(r[cf]) for r in rows], s=size)
-    elif kind == "literal" and cf:
-        ax.scatter(xs, ys, c=[r[cf] for r in rows], s=size)
-    else:
-        ax.scatter(xs, ys, color=mark.get("color"), s=size)
-    return False
-
-
-def _draw_bar(ax: Any, rows: list[dict[str, Any]], enc: dict[str, Any]) -> bool:
-    horizontal = _field(enc, "y") == "cat" or (enc.get("y", {}).get("field") == "cat")
-    cat_enc = enc["y"] if horizontal else enc["x"]
-    val_enc = enc["x"] if horizontal else enc["y"]
-    cat_f, val_f = cat_enc["field"], val_enc["field"]
-    _, cmap = _color_lookup(enc.get("color"))
-    color_field = _field(enc, "color")
-    stacked = bool(val_enc.get("stack"))
-    grouped = "xOffset" in enc or "yOffset" in enc
-    overlay = isinstance(enc.get("opacity"), dict) and "value" in enc["opacity"]
-
-    cats = list(dict.fromkeys(r[cat_f] for r in rows))
-    keys = list(dict.fromkeys(r[color_field] for r in rows)) if color_field else [None]
-    cat_idx = {c: i for i, c in enumerate(cats)}
-    import numpy as np
-
-    pos = np.arange(len(cats), dtype=float)
-    bottoms = np.zeros(len(cats))
-    nkeys = max(1, len(keys))
-    band = 0.8
-    bar_w = band / nkeys if grouped else band
-    for gi, key in enumerate(keys):
-        vals = np.zeros(len(cats))
-        for r in rows:
-            if color_field and r[color_field] != key:
-                continue
-            vals[cat_idx[r[cat_f]]] = r[val_f]
-        color = cmap.get(key) if isinstance(cmap, dict) else None
-        label = None if key is None else str(key)
-        if grouped:
-            offs = pos - band / 2 + bar_w * (gi + 0.5)
-        else:
-            offs = pos
-        if horizontal:
-            ax.barh(offs, vals, height=bar_w, left=bottoms if stacked else None, color=color, label=label, alpha=0.65 if overlay else None)
-        else:
-            ax.bar(offs, vals, width=bar_w, bottom=bottoms if stacked else None, color=color, label=label, alpha=0.65 if overlay else None)
-        if stacked:
-            bottoms += vals
-    if horizontal:
-        ax.set_yticks(pos)
-        ax.set_yticklabels([str(c) for c in cats])
-    else:
-        ax.set_xticks(pos)
-        ax.set_xticklabels([str(c) for c in cats])
-    return bool(color_field)
-
-
-def _draw_gantt(ax: Any, rows: list[dict[str, Any]], enc: dict[str, Any]) -> bool:
-    _, cmap = _color_lookup(enc.get("color"))
-    color_field = _field(enc, "color")
-    op_map = _scale_map(enc.get("opacity"))
-    op_field = _field(enc, "opacity")
-    y_sort = enc.get("y", {}).get("sort")
-    labels = list(y_sort) if y_sort else list(dict.fromkeys(r["label"] for r in rows))
-    ypos = {lbl: i for i, lbl in enumerate(labels)}
-    seen: set[Any] = set()
-    for r in rows:
-        start, end = _as_num_time(r["start"]), _as_num_time(r["end"])
-        color = cmap.get(r.get(color_field)) if isinstance(cmap, dict) else None
-        alpha = op_map.get(r.get(op_field)) if op_map else None
-        lbl = r.get(color_field)
-        ax.barh(ypos[r["label"]], end - start, left=start, height=0.6, color=color, alpha=alpha, label=None if lbl in seen else str(lbl))
-        seen.add(lbl)
-    ax.set_yticks(range(len(labels)))
-    ax.set_yticklabels(labels)
-    is_time = rows and not isinstance(rows[0]["start"], (int, float))
-    if is_time:
-        import matplotlib.dates as mdates
-
-        ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M"))
-    return bool(color_field)
-
-
-def _apply_axis_titles(ax: Any, enc: dict[str, Any]) -> None:
-    x = enc.get("x", {})
-    y = enc.get("y", {})
-    xt = (x.get("axis") or {}).get("title") if isinstance(x, dict) else None
-    yt = (y.get("axis") or {}).get("title") if isinstance(y, dict) else None
-    if xt:
-        ax.set_xlabel(xt)
-    if yt:
-        ax.set_ylabel(yt)
-
-
-def _draw_layer(ax: Any, layer: dict[str, Any], top_rows: list[dict[str, Any]], top_enc: dict[str, Any]) -> bool:
-    rows = _values(layer, top_rows)
-    enc = {**top_enc, **(layer.get("encoding") or {})}
-    mark = layer.get("mark")
-    mtype = mark.get("type") if isinstance(mark, dict) else mark
-    if not rows:
-        return False
-    if mtype == "line":
-        return _draw_line(ax, rows, enc)
-    if mtype == "point":
-        return _draw_point(ax, rows, enc, mark if isinstance(mark, dict) else {})
-    if mtype == "bar":
-        # temporal x + x2 → gantt; otherwise a categorical bar chart.
-        if "x2" in enc:
-            return _draw_gantt(ax, rows, enc)
-        return _draw_bar(ax, rows, enc)
-    return False
-
-
-def render(
-    spec: dict[str, Any],
-    *,
-    preset: str = DEFAULT_PRESET,
-    mode: Mode = "light",
-    ax: Any = None,
-    apply_style: bool = True,
-):
-    """Render a Vega-Lite spec to matplotlib. Returns ``(figure, axes)``.
-
-    >>> spec = molplot.line_spec([{ "id": "a", "x": [0,1,2], "y": [1,3,2] }])
-    >>> fig, ax = molplot.render(spec)
-    """
-    ctx = _style(preset, mode) if apply_style else nullcontext()
-    with ctx:
-        fig, ax = _ensure_ax(ax)
-        top_rows = _values(spec, [])
-        top_enc = spec.get("encoding") or {}
-        any_legend = False
-        if "layer" in spec:
-            for layer in spec["layer"]:
-                any_legend = _draw_layer(ax, layer, top_rows, top_enc) or any_legend
-        else:
-            any_legend = _draw_layer(ax, spec, top_rows, top_enc)
-        _apply_axis_titles(ax, top_enc)
-        # Show a legend only when the spec asked for one.
-        color_enc = top_enc.get("color") if isinstance(top_enc.get("color"), dict) else None
-        if not color_enc and "layer" in spec:
-            for layer in spec["layer"]:
-                ce = (layer.get("encoding") or {}).get("color")
-                if isinstance(ce, dict):
-                    color_enc = ce
-                    break
-        if any_legend and isinstance(color_enc, dict) and color_enc.get("legend") is not None:
-            ax.legend()
-    return fig, ax
diff --git a/python/src/molplot/vlmpl/__init__.py b/python/src/molplot/vlmpl/__init__.py
new file mode 100644
index 0000000..1696706
--- /dev/null
+++ b/python/src/molplot/vlmpl/__init__.py
@@ -0,0 +1,18 @@
+"""Vega-Lite → matplotlib interpreter.
+
+A small tree-walking interpreter whose *source language* is Vega-Lite and whose
+*target machine* is matplotlib. Four passes, each a classic compiler stage:
+
+1. :mod:`.model` — normalize the raw spec into a typed, immutable AST (frontend).
+2. :mod:`.scales` — bind scales: colour maps, numeric maps, positional axes.
+3. :mod:`.marks` — dispatch each mark to an encoder that emits artists (codegen).
+4. :mod:`.axes` — finalize titles, scales, and legend (link).
+
+The public entry is :func:`molplot.render`.
+"""
+
+from __future__ import annotations
+
+from .interp import render
+
+__all__ = ["render"]
diff --git a/python/src/molplot/vlmpl/axes.py b/python/src/molplot/vlmpl/axes.py
new file mode 100644
index 0000000..4700732
--- /dev/null
+++ b/python/src/molplot/vlmpl/axes.py
@@ -0,0 +1,47 @@
+"""Finalize an Axes after all marks are drawn: axis titles, positional scales
+(log / explicit domain — the step the old prototype dropped), and the legend.
+Runs once per render so cross-layer axis state is resolved in one place.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .model import Unit
+from .scales import apply_positional
+
+
+def apply_axes(ax: Any, units: list[Unit], labelled: bool) -> None:
+    enc = _merged_encoding(units)
+    x, y = enc.get("x"), enc.get("y")
+    if x is not None and x.axis_title:
+        ax.set_xlabel(x.axis_title)
+    if y is not None and y.axis_title:
+        ax.set_ylabel(y.axis_title)
+    apply_positional(ax, "x", x)
+    apply_positional(ax, "y", y)
+    _apply_legend(ax, units, labelled)
+
+
+def _merged_encoding(units: list[Unit]) -> dict:
+    """First-seen channel across layers (shared x/y live at the spec root and
+    appear identically in every unit after normalization)."""
+    merged: dict = {}
+    for unit in units:
+        for name, channel in unit.encoding.items():
+            merged.setdefault(name, channel)
+    return merged
+
+
+def _apply_legend(ax: Any, units: list[Unit], labelled: bool) -> None:
+    """Show a categorical legend only when a colour channel asked for one and
+    labelled artists exist. Quantitative colour uses a colourbar, added when the
+    point mark is drawn, so it is skipped here."""
+    color = next(
+        (u.encoding["color"] for u in units if u.encoding.get("color") and u.encoding["color"].wants_legend),
+        None,
+    )
+    if color is None or color.type == "quantitative":
+        return
+    if labelled:
+        ax.legend()
diff --git a/python/src/molplot/vlmpl/data.py b/python/src/molplot/vlmpl/data.py
new file mode 100644
index 0000000..4eac285
--- /dev/null
+++ b/python/src/molplot/vlmpl/data.py
@@ -0,0 +1,52 @@
+"""Data-space helpers: apply a unit's transforms to its rows and coerce
+temporal values to matplotlib date numbers. Kept separate so mark encoders
+receive plain, already-filtered row dicts and never re-implement filtering.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+
+def apply_transforms(rows: tuple, transforms: tuple) -> list[dict]:
+    """Return the rows that survive a unit's ``transform`` list.
+
+    Only ``filter`` transforms are meaningful for a static figure; this is what
+    gates the line spec's marker layer (``oneOf: []`` → draw nothing), so a
+    plain line chart shows no stray marker points.
+    """
+    out = list(rows)
+    for t in transforms:
+        f = t.get("filter") if isinstance(t, dict) else None
+        if isinstance(f, dict):
+            out = _apply_filter(out, f)
+    return out
+
+
+def _apply_filter(rows: list[dict], f: dict) -> list[dict]:
+    field = f.get("field")
+    if field is None:
+        return rows
+    if "oneOf" in f:
+        allowed = set(f["oneOf"])
+        return [r for r in rows if r.get(field) in allowed]
+    if "equal" in f:
+        target = f["equal"]
+        return [r for r in rows if r.get(field) == target]
+    return rows
+
+
+def is_temporal(v: Any) -> bool:
+    """A value that is not already numeric is treated as a timestamp."""
+    return not isinstance(v, (int, float))
+
+
+def as_number(v: Any) -> float:
+    """Coerce a value that may be an ISO-8601 timestamp to a plottable number;
+    pass ints/floats through unchanged."""
+    if isinstance(v, (int, float)):
+        return float(v)
+    import matplotlib.dates as mdates
+
+    return float(mdates.date2num(datetime.fromisoformat(str(v).replace("Z", "+00:00"))))
diff --git a/python/src/molplot/vlmpl/interp.py b/python/src/molplot/vlmpl/interp.py
new file mode 100644
index 0000000..35bacab
--- /dev/null
+++ b/python/src/molplot/vlmpl/interp.py
@@ -0,0 +1,49 @@
+"""The interpreter driver.
+
+Walks a Vega-Lite spec end to end: normalize into typed units, apply the unified
+preset style, dispatch each unit's mark onto the axes, then finalize the axes
+(titles, scales, legend). This is the implementation behind ``molplot.render``.
+"""
+
+from __future__ import annotations
+
+from contextlib import nullcontext
+from typing import Any
+
+from ..preset import DEFAULT_PRESET, Mode
+from ..style import style as _style
+from .axes import apply_axes
+from .marks import encode
+from .model import normalize
+
+
+def _ensure_ax(ax: Any) -> tuple[Any, Any]:
+    import matplotlib.pyplot as plt
+
+    if ax is not None:
+        return ax.figure, ax
+    return plt.subplots()
+
+
+def render(
+    spec: dict[str, Any],
+    *,
+    preset: str = DEFAULT_PRESET,
+    mode: Mode = "light",
+    ax: Any = None,
+    apply_style: bool = True,
+):
+    """Render a Vega-Lite spec to matplotlib. Returns ``(figure, axes)``.
+
+    >>> spec = molplot.line_spec([{"id": "a", "x": [0, 1, 2], "y": [1, 3, 2]}])
+    >>> fig, ax = molplot.render(spec)
+    """
+    units = normalize(spec)
+    ctx = _style(preset, mode) if apply_style else nullcontext()
+    with ctx:
+        fig, ax = _ensure_ax(ax)
+        labelled = False
+        for unit in units:
+            labelled = encode(ax, unit) or labelled
+        apply_axes(ax, units, labelled)
+    return fig, ax
diff --git a/python/src/molplot/vlmpl/marks.py b/python/src/molplot/vlmpl/marks.py
new file mode 100644
index 0000000..d8f06d5
--- /dev/null
+++ b/python/src/molplot/vlmpl/marks.py
@@ -0,0 +1,200 @@
+"""Mark encoders — the interpreter's emit pass.
+
+One encoder per Vega-Lite mark type, registered in :data:`MARK_ENCODERS`. Each
+reads *typed channels* off the unit (``enc["x"].field``) rather than hardcoded
+field names, so the same encoder serves any spec that uses the mark. Every
+encoder returns whether it drew legend-eligible (labelled) artists.
+
+Adding a mark = write an encoder and register it here.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .data import apply_transforms, as_number, is_temporal
+from .model import Unit
+from .scales import color_map, numeric_map
+
+
+def _draw_line(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    xf = enc["x"].field
+    yf = enc["y"].field
+    color = enc.get("color")
+    cf = color.field if color else None
+    cmap = color_map(color)
+    detail = enc.get("detail")
+    df = detail.field if detail else None
+    width_map = numeric_map(enc.get("strokeWidth"))
+    op_map = numeric_map(enc.get("opacity"))
+    uniform_width = mark.get("strokeWidth")
+    uniform_opacity = mark.get("opacity")
+
+    # A polyline per (colour, detail) pair: detail splits series that share a
+    # legend colour (e.g. repeated runs) without merging their points.
+    groups: dict[Any, list[dict]] = {}
+    order: list[Any] = []
+    for r in rows:
+        key = (r.get(cf) if cf else None, r.get(df) if df else None)
+        if key not in groups:
+            groups[key] = []
+            order.append(key)
+        groups[key].append(r)
+
+    labelled = False
+    seen_labels: set = set()
+    for cval, _dval in order:
+        grp = sorted(groups[(cval, _dval)], key=lambda r: r[xf])
+        color_v = cmap.mapping.get(cval) if cmap.kind == "nominal" else None
+        lw = width_map.get(cval) if width_map else uniform_width
+        alpha = op_map.get(cval) if op_map else uniform_opacity
+        # Same colour → one merged legend entry (mirrors Vega legend merging).
+        label = str(cval) if cval is not None and cval not in seen_labels else None
+        if label is not None:
+            seen_labels.add(cval)
+        ax.plot(
+            [r[xf] for r in grp],
+            [r[yf] for r in grp],
+            label=label,
+            color=color_v,
+            linewidth=lw,
+            alpha=alpha,
+        )
+        labelled = labelled or cval is not None
+    return labelled
+
+
+def _draw_point(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    if not rows:
+        return False
+    xf = enc["x"].field
+    yf = enc["y"].field
+    color = enc.get("color")
+    cf = color.field if color else None
+    cmap = color_map(color)
+    xs = [r[xf] for r in rows]
+    ys = [r[yf] for r in rows]
+    size = mark.get("size", 36)
+    alpha = mark.get("opacity")
+    if cmap.kind == "quantitative" and cf:
+        sc = ax.scatter(xs, ys, c=[r[cf] for r in rows], cmap=cmap.mapping, s=size, alpha=alpha)
+        if color.wants_legend:
+            ax.figure.colorbar(sc, ax=ax)
+    elif cmap.kind == "nominal" and cf:
+        ax.scatter(xs, ys, c=[cmap.mapping.get(r[cf]) for r in rows], s=size, alpha=alpha)
+    elif cmap.kind == "literal" and cf:
+        ax.scatter(xs, ys, c=[r[cf] for r in rows], s=size, alpha=alpha)
+    else:
+        ax.scatter(xs, ys, color=mark.get("color"), s=size, alpha=alpha)
+    return False
+
+
+def _draw_bar(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    import numpy as np
+
+    x, y = enc.get("x"), enc.get("y")
+    horizontal = y is not None and y.type == "nominal"
+    cat_ch = y if horizontal else x
+    val_ch = x if horizontal else y
+    cat_f, val_f = cat_ch.field, val_ch.field
+    color = enc.get("color")
+    color_field = color.field if color else None
+    cmap = color_map(color)
+    stacked = bool(val_ch.stack)
+    grouped = "xOffset" in enc or "yOffset" in enc
+    opacity = enc.get("opacity")
+    overlay_alpha = opacity.value if (opacity is not None and opacity.is_value) else None
+
+    cats = list(dict.fromkeys(r[cat_f] for r in rows))
+    keys = list(dict.fromkeys(r[color_field] for r in rows)) if color_field else [None]
+    cat_idx = {c: i for i, c in enumerate(cats)}
+    pos = np.arange(len(cats), dtype=float)
+    bottoms = np.zeros(len(cats))
+    band = 0.8
+    bar_w = band / max(1, len(keys)) if grouped else band
+
+    for gi, key in enumerate(keys):
+        vals = np.zeros(len(cats))
+        for r in rows:
+            if color_field and r[color_field] != key:
+                continue
+            vals[cat_idx[r[cat_f]]] = r[val_f]
+        color_v = cmap.mapping.get(key) if cmap.kind == "nominal" else None
+        label = None if key is None else str(key)
+        offs = pos - band / 2 + bar_w * (gi + 0.5) if grouped else pos
+        if horizontal:
+            ax.barh(offs, vals, height=bar_w, left=bottoms if stacked else None, color=color_v, label=label, alpha=overlay_alpha)
+        else:
+            ax.bar(offs, vals, width=bar_w, bottom=bottoms if stacked else None, color=color_v, label=label, alpha=overlay_alpha)
+        if stacked:
+            bottoms += vals
+
+    if horizontal:
+        ax.set_yticks(pos)
+        ax.set_yticklabels([str(c) for c in cats])
+    else:
+        ax.set_xticks(pos)
+        ax.set_xticklabels([str(c) for c in cats])
+    return bool(color_field)
+
+
+def _draw_interval(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    """A bar with an ``x2`` (or ``y2``) span — the Gantt case, generalized: a
+    bar whose start and end both come from data instead of a baseline."""
+    if not rows:
+        return False
+    color = enc.get("color")
+    color_field = color.field if color else None
+    cmap = color_map(color)
+    opacity = enc.get("opacity")
+    op_field = opacity.field if opacity else None
+    op_map = numeric_map(opacity)
+    y = enc.get("y")
+    y_field = y.field if y and y.field else "label"
+    labels = list(y.sort) if (y and y.sort) else list(dict.fromkeys(r[y_field] for r in rows))
+    ypos = {lbl: i for i, lbl in enumerate(labels)}
+    xf = enc["x"].field if enc.get("x") else "start"
+    x2f = enc["x2"].field if enc.get("x2") else "end"
+
+    seen: set = set()
+    for r in rows:
+        start, end = as_number(r[xf]), as_number(r[x2f])
+        color_v = cmap.mapping.get(r.get(color_field)) if cmap.kind == "nominal" else None
+        alpha = op_map.get(r.get(op_field)) if op_map else None
+        group = r.get(color_field)
+        label = None if group in seen or group is None else str(group)
+        ax.barh(ypos[r[y_field]], end - start, left=start, height=0.6, color=color_v, alpha=alpha, label=label)
+        seen.add(group)
+
+    ax.set_yticks(range(len(labels)))
+    ax.set_yticklabels([str(lbl) for lbl in labels])
+    if rows and is_temporal(rows[0][xf]):
+        import matplotlib.dates as mdates
+
+        ax.xaxis.set_major_formatter(mdates.DateFormatter("%H:%M"))
+    return bool(color_field)
+
+
+def _draw_bar_or_interval(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    if "x2" in enc or "y2" in enc:
+        return _draw_interval(ax, rows, enc, mark)
+    return _draw_bar(ax, rows, enc, mark)
+
+
+MARK_ENCODERS = {
+    "line": _draw_line,
+    "point": _draw_point,
+    "circle": _draw_point,
+    "square": _draw_point,
+    "bar": _draw_bar_or_interval,
+}
+
+
+def encode(ax: Any, unit: Unit) -> bool:
+    """Draw one unit's mark; returns whether it produced labelled artists.
+    Unknown marks are skipped (returns False)."""
+    encoder = MARK_ENCODERS.get(unit.mark)
+    if encoder is None:
+        return False
+    rows = apply_transforms(unit.rows, unit.transforms)
+    return encoder(ax, rows, unit.encoding, unit.mark_props)
diff --git a/python/src/molplot/vlmpl/model.py b/python/src/molplot/vlmpl/model.py
new file mode 100644
index 0000000..7ab3d01
--- /dev/null
+++ b/python/src/molplot/vlmpl/model.py
@@ -0,0 +1,154 @@
+"""Typed Vega-Lite AST + normalization — the interpreter frontend.
+
+Turns a raw Vega-Lite dict into an immutable list of :class:`Unit` (one per
+layer), each carrying the encoding it should draw with (top-level channels
+merged with the layer's own overrides), its inline data rows, its mark type and
+properties, and any transforms. This is the *only* module that understands
+Vega-Lite's structure — layering and channel inheritance; everything downstream
+sees a flat, field-name-agnostic ``Unit``.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+# Sentinel: distinguishes "no value channel / no constant" from an explicit None.
+_UNSET: Any = object()
+
+
+@dataclass(frozen=True)
+class Scale:
+    """A resolved Vega-Lite ``scale`` object (positional, colour, or size)."""
+
+    type: str | None = None
+    domain: list | None = None
+    range: list | None = None
+    scheme: str | None = None
+    zero: bool | None = None
+    padding_inner: float | None = None
+
+    @classmethod
+    def parse(cls, raw: Any) -> "Scale | None":
+        if not isinstance(raw, dict):
+            return None
+        dom = raw.get("domain")
+        rng = raw.get("range")
+        return cls(
+            type=raw.get("type"),
+            domain=list(dom) if isinstance(dom, (list, tuple)) else None,
+            range=list(rng) if isinstance(rng, (list, tuple)) else None,
+            scheme=raw.get("scheme"),
+            zero=raw.get("zero"),
+            padding_inner=raw.get("paddingInner"),
+        )
+
+
+@dataclass(frozen=True)
+class Channel:
+    """A resolved encoding channel (``x``, ``color``, ``opacity``, …)."""
+
+    name: str
+    field: str | None = None
+    type: str | None = None
+    scale: Scale | None = None
+    axis_title: str | None = None
+    legend: Any = None
+    sort: tuple | None = None
+    stack: bool | None = None
+    value: Any = _UNSET
+
+    @property
+    def wants_legend(self) -> bool:
+        """Vega shows a legend/colourbar only when ``legend`` is non-null."""
+        return self.legend is not None
+
+    @property
+    def is_value(self) -> bool:
+        """True for a constant channel like ``{"value": 0.65}``."""
+        return self.value is not _UNSET
+
+    @classmethod
+    def parse(cls, name: str, raw: Any) -> "Channel":
+        if not isinstance(raw, dict):
+            return cls(name=name)
+        axis = raw.get("axis")
+        sort = raw.get("sort")
+        return cls(
+            name=name,
+            field=raw.get("field"),
+            type=raw.get("type"),
+            scale=Scale.parse(raw.get("scale")),
+            axis_title=axis.get("title") if isinstance(axis, dict) else None,
+            legend=raw.get("legend"),
+            sort=tuple(sort) if isinstance(sort, (list, tuple)) else None,
+            stack=raw.get("stack"),
+            value=raw.get("value", _UNSET),
+        )
+
+
+@dataclass(frozen=True)
+class Unit:
+    """One drawable view: a mark plus the channels and rows that feed it."""
+
+    mark: str | None
+    mark_props: dict
+    encoding: dict  # channel name -> Channel
+    rows: tuple  # inline data rows (dicts)
+    transforms: tuple  # raw Vega-Lite transform dicts
+
+
+def _mark_of(node: dict) -> tuple[str | None, dict]:
+    mark = node.get("mark")
+    if isinstance(mark, dict):
+        return mark.get("type"), dict(mark)
+    return mark, {}
+
+
+def _rows_of(node: dict, inherited: tuple) -> tuple:
+    data = node.get("data")
+    if isinstance(data, dict) and isinstance(data.get("values"), list):
+        return tuple(data["values"])
+    return inherited
+
+
+def _encoding_of(raw: dict | None) -> dict:
+    return {name: Channel.parse(name, ch) for name, ch in (raw or {}).items()}
+
+
+def normalize(spec: dict) -> list[Unit]:
+    """Flatten a Vega-Lite spec into drawable units.
+
+    A ``layer`` spec yields one unit per layer, each inheriting the spec's
+    top-level ``encoding`` and ``data`` (its own channels win). A single-view
+    spec yields one unit. Handles both shapes MolPlot emits: layered line specs
+    and top-level scatter / bar / gantt specs.
+    """
+    top_rows = _rows_of(spec, ())
+    top_enc_raw = spec.get("encoding") or {}
+    layers = spec.get("layer")
+    if isinstance(layers, list):
+        units: list[Unit] = []
+        for layer in layers:
+            merged = {**top_enc_raw, **(layer.get("encoding") or {})}
+            mark, props = _mark_of(layer)
+            units.append(
+                Unit(
+                    mark=mark,
+                    mark_props=props,
+                    encoding=_encoding_of(merged),
+                    rows=_rows_of(layer, top_rows),
+                    transforms=tuple(layer.get("transform") or ()),
+                )
+            )
+        return units
+    mark, props = _mark_of(spec)
+    return [
+        Unit(
+            mark=mark,
+            mark_props=props,
+            encoding=_encoding_of(top_enc_raw),
+            rows=top_rows,
+            transforms=tuple(spec.get("transform") or ()),
+        )
+    ]
diff --git a/python/src/molplot/vlmpl/scales.py b/python/src/molplot/vlmpl/scales.py
new file mode 100644
index 0000000..7dbf904
--- /dev/null
+++ b/python/src/molplot/vlmpl/scales.py
@@ -0,0 +1,67 @@
+"""Scale binding — the interpreter's semantic pass.
+
+Turns typed channels into the things matplotlib needs: colour lookups, numeric
+maps for per-series stroke width / opacity, and positional-axis configuration
+(log scaling and explicit domain limits). Applying positional scales is exactly
+the step the ad-hoc renderer skipped, so log axes and fixed domains were lost.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Any
+
+from .model import Channel
+
+
+@dataclass(frozen=True)
+class ColorMap:
+    """Resolved colour encoding.
+
+    ``kind`` is one of ``nominal`` (``mapping`` is a value→hex dict),
+    ``quantitative`` (``mapping`` is a colour-scheme name for a cmap),
+    ``literal`` (the field value *is* the colour), or ``none``.
+    """
+
+    kind: str
+    mapping: Any = None
+
+
+def color_map(channel: Channel | None) -> ColorMap:
+    if channel is None:
+        return ColorMap("none")
+    if channel.type == "quantitative":
+        return ColorMap("quantitative", channel.scale.scheme if channel.scale else None)
+    scale = channel.scale
+    if scale and scale.domain is not None and scale.range is not None:
+        return ColorMap("nominal", dict(zip(scale.domain, scale.range)))
+    return ColorMap("literal")
+
+
+def numeric_map(channel: Channel | None) -> dict | None:
+    """A value→number map for a per-field ``strokeWidth`` / ``opacity`` channel
+    (domain/range scale). Returns None when the channel carries no such scale.
+    """
+    if channel is None or channel.scale is None:
+        return None
+    scale = channel.scale
+    if scale.domain is not None and scale.range is not None:
+        return dict(zip(scale.domain, scale.range))
+    return None
+
+
+def apply_positional(ax: Any, axis: str, channel: Channel | None) -> None:
+    """Apply a positional channel's scale to ``ax``: ``log`` scaling and an
+    explicit numeric ``domain`` → axis limits. ``axis`` is ``"x"`` or ``"y"``.
+    Categorical (nominal/ordinal) and temporal channels carry no numeric domain
+    and are left to the mark encoder / autoscaling.
+    """
+    if channel is None or channel.scale is None:
+        return
+    scale = channel.scale
+    set_scale = ax.set_xscale if axis == "x" else ax.set_yscale
+    set_lim = ax.set_xlim if axis == "x" else ax.set_ylim
+    if scale.type == "log":
+        set_scale("log")
+    if scale.domain is not None and channel.type in (None, "quantitative"):
+        set_lim(scale.domain[0], scale.domain[-1])
diff --git a/python/tests/test_vlmpl.py b/python/tests/test_vlmpl.py
new file mode 100644
index 0000000..cae5fb2
--- /dev/null
+++ b/python/tests/test_vlmpl.py
@@ -0,0 +1,61 @@
+"""Behavioural contract for the Vega-Lite → matplotlib interpreter that the
+ad-hoc ``render.py`` prototype did not satisfy: positional scales (log / domain)
+must reach the axis, and per-layer ``transform`` filters must be honoured so a
+plain line chart draws no stray marker points.
+"""
+
+import matplotlib.pyplot as plt
+
+import molplot
+
+
+def teardown_function():
+    plt.close("all")
+
+
+def test_log_scale_reaches_the_axis():
+    spec = molplot.line_spec([{"id": "a", "x": [1, 10, 100], "y": [1, 2, 3]}], x_log=True)
+    _, ax = molplot.render(spec)
+    assert ax.get_xscale() == "log"
+
+
+def test_linear_scale_is_the_default():
+    spec = molplot.line_spec([{"id": "a", "x": [1, 2, 3], "y": [1, 2, 3]}])
+    _, ax = molplot.render(spec)
+    assert ax.get_xscale() == "linear"
+
+
+def test_scale_domain_sets_axis_limits():
+    spec = molplot.line_spec([{"id": "a", "x": [0, 1, 2], "y": [0, 1, 2]}], y_domain=[0, 10])
+    _, ax = molplot.render(spec)
+    assert ax.get_ylim() == (0.0, 10.0)
+
+
+def test_plain_line_draws_no_marker_points():
+    # The line spec always carries a second point layer gated by a
+    # ``transform: [{filter: {field: 'key', oneOf: []}}]``. With no
+    # lines+markers series the filter matches nothing, so a faithful
+    # interpreter draws zero collections.
+    spec = molplot.line_spec([{"id": "a", "x": [0, 1, 2], "y": [0, 1, 2]}])
+    _, ax = molplot.render(spec)
+    assert len(ax.collections) == 0
+
+
+def test_lines_plus_markers_draws_points():
+    spec = molplot.line_spec([{"id": "a", "x": [0, 1, 2], "y": [0, 1, 2], "mode": "lines+markers"}])
+    _, ax = molplot.render(spec)
+    assert len(ax.lines) == 1
+    assert len(ax.collections) >= 1
+
+
+def test_detail_channel_splits_lines_without_extra_legend_series():
+    # Two datapoints sharing a label but differing on the detail field ``s``
+    # must not be merged into one polyline.
+    spec = molplot.line_spec(
+        [
+            {"id": "run1", "label": "trial", "x": [0, 1], "y": [0, 1]},
+            {"id": "run2", "label": "trial", "x": [0, 1], "y": [1, 2]},
+        ]
+    )
+    _, ax = molplot.render(spec)
+    assert len(ax.lines) == 2

From c8b32e3b00bc9b90647837fb9f23ef5f5a9dbd21 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 10 Jul 2026 11:33:49 +0800
Subject: [PATCH 02/17] feat(core): pan/zoom with per-axis wheel targeting
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Every chart now declares one scale-bound interval selection per continuous
axis. Drag pans, a wheel over an axis gutter zooms that axis alone,
shift+wheel zooms every bound axis, double click resets. A bare wheel over
the plot is left untouched so an enclosing panel still scrolls.

Band scales (bar's category axis, gantt's task axis) get no param at all —
Vega-Lite refuses to bind a discrete domain — so they are inert by
construction rather than by special case.

Three Vega constraints drove the shape of this:

- Selection params must sit on exactly one unit layer. At the top level of a
  layered spec Vega-Lite copies them into every layer and Vega then throws
  "Duplicate signal name" at parse time, while vl.compile() stays silent.
  specs.test.ts compiles each spec and asserts no duplicate signal names.

- `bind: "scales"` defaults its wheel stream to `source: "scope"` — the plot
  group. Axes render with pointer-events: none, so an axis wheel falls
  through to the SVG root and never enters that group. Switching to `view:`
  catches it, and keeps sibling charts on the page from reacting.

- A Vega event filter is compiled without the signal scope object: it may
  call x()/y() but throws `ReferenceError: _ is not defined` on any signal
  read. That rules out `y() > height`, so VegaChart resolves the pointer
  against the scenegraph's axis bounds and hands the spec a boolean flag.
  `|| event.shiftKey` keeps the spec self-sufficient for a raw vegaEmbed.

The classification is a pure function (axisChannelAt) tested with plain
rectangles: grid boxes coincide with the plot rect, legends never carry
role "axis", and a wheel below a bottom legend must stay inert.

Marks are now clipped, without which a zoomed mark paints over the axes.

`params` is inert on paper: render.py reads only encoding/layer/mark, so the
matplotlib translator and vl-convert draw the initial view.
---
 core/src/chart_base.ts             | 116 ++++++++++++++++++++++-
 core/src/specs.ts                  | 100 +++++++++++++++++++-
 core/tests/_fake_vega.ts           |  27 ++++++
 core/tests/axis_hover_zoom.test.ts |  73 +++++++++++++++
 core/tests/line_chart.test.ts      |  21 ++++-
 core/tests/scatter_chart.test.ts   |   5 +-
 core/tests/specs.test.ts           | 146 ++++++++++++++++++++++++++++-
 python/src/molplot/specs.py        |  74 +++++++++++++--
 python/tests/test_render.py        |   3 +
 python/tests/test_specs.py         |  56 +++++++++++
 10 files changed, 605 insertions(+), 16 deletions(-)
 create mode 100644 core/tests/axis_hover_zoom.test.ts

diff --git a/core/src/chart_base.ts b/core/src/chart_base.ts
index dd01667..b9138bb 100644
--- a/core/src/chart_base.ts
+++ b/core/src/chart_base.ts
@@ -1,14 +1,37 @@
-import type { VegaLiteSpec } from "./specs";
+import {
+  type VegaLiteSpec,
+  ZOOM_EVENT_FLAG,
+  type ZoomChannel,
+  zoomParamsOf,
+} from "./specs";
 import { type ChartTheme, resolveTheme } from "./theme";
 import type { ThemeMode } from "./types";
 import { loadVegaEmbed, type VegaEmbed } from "./vega_loader";
 
+/** A scenegraph item's box, in the plot rectangle's coordinate frame. */
+export interface Bounds {
+  x1: number;
+  x2: number;
+  y1: number;
+  y2: number;
+}
+
+interface SceneItem {
+  role?: string;
+  bounds?: Bounds;
+  items?: SceneItem[];
+}
+
 /** Minimal shape of the vega-embed result we depend on. */
 interface EmbedResult {
   view: {
     data(name: string, values?: unknown[]): unknown;
     resize(): { run(): unknown };
     run(): unknown;
+    /** Top-left of the plot rectangle within the rendered element. */
+    origin(): number[];
+    signal(name: string): unknown;
+    scenegraph(): { root: SceneItem };
     addEventListener(
       type: string,
       handler: (e: unknown, item: unknown) => void,
@@ -17,6 +40,50 @@ interface EmbedResult {
   };
 }
 
+/** A wheel event carrying the axis-gutter flags the zoom params filter on. */
+type ZoomWheelEvent = WheelEvent & {
+  [ZOOM_EVENT_FLAG.x]?: boolean;
+  [ZOOM_EVENT_FLAG.y]?: boolean;
+};
+
+/**
+ * Which axis, if any, the pointer sits on. All coordinates share the plot
+ * rectangle's frame: its interior is `[0, width] × [0, height]`, so an axis
+ * governing x lies above or below it and one governing y lies beside it.
+ *
+ * `axes` must be the `role: "axis"` scenegraph items. Vega emits one per axis
+ * plus one per grid; a grid's box *is* the plot edge, so its centre lands on
+ * the boundary and it classifies as neither gutter. Legends carry
+ * `role: "legend"` and never reach here — a legend drawn under the x axis
+ * (gantt) must stay inert.
+ */
+export function axisChannelAt(
+  axes: Bounds[],
+  x: number,
+  y: number,
+  width: number,
+  height: number,
+): ZoomChannel | null {
+  if (x >= 0 && x <= width && y >= 0 && y <= height) return null;
+  for (const box of axes) {
+    if (x < box.x1 || x > box.x2 || y < box.y1 || y > box.y2) continue;
+    const centreY = (box.y1 + box.y2) / 2;
+    if (centreY > height || centreY < 0) return "x";
+    const centreX = (box.x1 + box.x2) / 2;
+    if (centreX < 0 || centreX > width) return "y";
+  }
+  return null;
+}
+
+/** Boxes of every axis Vega drew, in the plot rectangle's frame. */
+function axisBounds(root: SceneItem): Bounds[] {
+  const out: Bounds[] = [];
+  for (const frame of root.items ?? [])
+    for (const item of frame.items ?? [])
+      if (item.role === "axis" && item.bounds) out.push(item.bounds);
+  return out;
+}
+
 /**
  * Shared lifecycle for every chart: lazy vega-embed load, spec→embed render,
  * cheap streaming data updates (`view.data(name, rows)`), rAF-debounced
@@ -36,6 +103,10 @@ export abstract class VegaChart {
   protected readonly mountPromise: Promise<void>;
   private resizeObserver: ResizeObserver | null = null;
   private themeObserver: MutationObserver | null = null;
+  private detachAxisZoom: (() => void) | null = null;
+  /** The element Vega rendered into, and whether its spec declares zoom params. */
+  private rendered: Element | null = null;
+  private zoomable = false;
   private resizeRaf: number | null = null;
   private lastW = 0;
   private lastH = 0;
@@ -51,6 +122,7 @@ export abstract class VegaChart {
     this.presetName = presetName;
     this.mountPromise = this.mount();
     this.setupResizeObserver();
+    this.detachAxisZoom = this.bindAxisHoverZoom();
     if (this.themeMode === "auto") this.setupThemeObserver();
   }
 
@@ -76,10 +148,13 @@ export abstract class VegaChart {
     }
     this.resizeObserver?.disconnect();
     this.themeObserver?.disconnect();
+    this.detachAxisZoom?.();
     this.resizeObserver = null;
     this.themeObserver = null;
+    this.detachAxisZoom = null;
     this.result?.view.finalize();
     this.result = null;
+    this.rendered = null;
   }
 
   /** Build the Vega-Lite spec for the current state + theme. */
@@ -119,6 +194,7 @@ export abstract class VegaChart {
     const spec = this.buildSpec(theme, { width, height });
     this.result?.view.finalize();
     this.result = null;
+    this.rendered = null;
     const result = (await this.embed(this.container, spec as never, {
       actions: false,
       renderer: "svg",
@@ -134,9 +210,47 @@ export abstract class VegaChart {
         ?.datum;
       if (datum) this.onDatum(datum);
     });
+    // A spec that never went through a builder (RawChart) has no zoom params,
+    // so its wheels can skip the hit test entirely.
+    this.zoomable = zoomParamsOf(spec).length > 0;
+    this.rendered = this.container.querySelector("svg");
     this.result = result;
   }
 
+  /**
+   * Wheel over an axis zooms that axis alone. The spec's zoom params filter on
+   * flags this stamps, because a Vega event filter cannot read the `width` /
+   * `height` signals it would need to locate the pointer itself — see
+   * `ZOOM_EVENT_FLAG` in `specs.ts`.
+   *
+   * Bound once for the chart's life: the listener sits on `container`, which
+   * vega-embed renders into but never replaces.
+   *
+   * Passive, capture phase, and it never calls `preventDefault()`. Consuming
+   * the wheel is Vega's job and it only does so for a wheel its own selector
+   * matched, which is why an unmatched wheel still scrolls the enclosing panel.
+   */
+  private bindAxisHoverZoom(): () => void {
+    const onWheel = (event: Event): void => {
+      if (!this.zoomable || !this.result || !this.rendered) return;
+      const { view } = this.result;
+      const rect = this.rendered.getBoundingClientRect();
+      const [originX, originY] = view.origin();
+      const wheel = event as ZoomWheelEvent;
+      const channel = axisChannelAt(
+        axisBounds(view.scenegraph().root),
+        wheel.clientX - rect.left - originX,
+        wheel.clientY - rect.top - originY,
+        view.signal("width") as number,
+        view.signal("height") as number,
+      );
+      if (channel) wheel[ZOOM_EVENT_FLAG[channel]] = true;
+    };
+    const options = { capture: true, passive: true };
+    this.container.addEventListener("wheel", onWheel, options);
+    return () => this.container.removeEventListener("wheel", onWheel, options);
+  }
+
   /** Push the current datasets into a freshly embedded view. */
   private feed(result: EmbedResult): void {
     const data = this.datasets();
diff --git a/core/src/specs.ts b/core/src/specs.ts
index b971f16..3589ed8 100644
--- a/core/src/specs.ts
+++ b/core/src/specs.ts
@@ -21,6 +21,80 @@ export interface SpecSize {
 
 const FALLBACK_STATUS_COLOR = "#a3a3a3";
 
+/** Continuous channels that can carry a scale binding. */
+export type ZoomChannel = "x" | "y";
+
+/** One scale-bound interval selection per zoomable axis. */
+export const ZOOM_PARAM = { x: "zoomX", y: "zoomY" } as const;
+
+/**
+ * Flags `VegaChart` stamps on a wheel event to say which axis gutter the
+ * pointer is over.
+ *
+ * A Vega event filter is compiled without the signal scope object, so it can
+ * call the geometry functions (`x()`, `y()`) but throws `ReferenceError: _ is
+ * not defined` the moment it reads a signal. That rules out the expression the
+ * region test wants — `y() > height` — because `height` is a signal. Hence the
+ * test happens where the geometry is knowable and arrives here as a boolean.
+ */
+export const ZOOM_EVENT_FLAG = {
+  x: "molplotZoomX",
+  y: "molplotZoomY",
+} as const;
+
+/** A scale-bound interval selection, one per zoomable axis. */
+export interface ZoomParam {
+  name: string;
+  bind: "scales";
+  select: { type: "interval"; encodings: ZoomChannel[]; zoom: string };
+}
+
+/**
+ * The zoom params a builder attached, wherever it legally placed them: top
+ * level for a unit spec, `layer[0]` for a layered one. Empty for a spec that
+ * never went through a builder (`RawChart`).
+ */
+export function zoomParamsOf(spec: VegaLiteSpec): ZoomParam[] {
+  const layers = spec.layer as { params?: ZoomParam[] }[] | undefined;
+  return (spec.params as ZoomParam[]) ?? layers?.[0]?.params ?? [];
+}
+
+/**
+ * Pan/zoom, one param per continuous axis: drag pans, wheel over an axis
+ * gutter zooms that axis alone, Shift+wheel zooms every bound axis, double
+ * click resets.
+ *
+ * The `view:` source matters. Vega-Lite's default for a scale binding is
+ * `scope` — the plot group — but axes render with `pointer-events: none`, so a
+ * wheel over an axis falls through to the SVG root and never enters that
+ * group. `view:` listens on the chart's own element instead, which both catches
+ * the axis wheel and keeps sibling charts on the page from reacting to it.
+ *
+ * `|| event.shiftKey` keeps the spec self-sufficient: Shift+wheel zooms even
+ * when nobody is stamping the event (a raw `vegaEmbed` of this spec, the docs).
+ *
+ * `bind: "scales"` attaches a `domainRaw` signal that outranks the computed
+ * domain, so `zero` / `nice` / an explicit `domain` still choose the *initial*
+ * view and the interaction owns the view from then on.
+ *
+ * Pass only continuous channels; binding a band scale warns "Scale bindings are
+ * currently only supported for scales with unbinned, continuous domains."
+ *
+ * Inert outside the browser: the matplotlib translator and vl-convert both
+ * ignore `params` and render the initial view.
+ */
+function interactionParams(channels: ZoomChannel[]): ZoomParam[] {
+  return channels.map((channel) => ({
+    name: ZOOM_PARAM[channel],
+    select: {
+      type: "interval",
+      encodings: [channel],
+      zoom: `view:wheel![event.${ZOOM_EVENT_FLAG[channel]} || event.shiftKey]`,
+    },
+    bind: "scales",
+  }));
+}
+
 /** Strip undefined so specs compare cleanly in tests and serialize small. */
 function clean<T extends Record<string, unknown>>(obj: T): T {
   for (const k of Object.keys(obj)) {
@@ -145,6 +219,10 @@ export function lineSpec(
     encoding: xy,
     layer: [
       {
+        // Params belong to exactly one unit layer. At the top level of a
+        // layered spec Vega-Lite copies them into every layer and Vega then
+        // throws "Duplicate signal name" while compiling stays silent.
+        params: interactionParams(["x", "y"]),
         mark: lineMark,
         encoding: lineEncoding,
       },
@@ -154,12 +232,13 @@ export function lineSpec(
           type: "point",
           filled: true,
           size: theme.geometry.markerSize ** 2,
+          clip: true,
         },
         encoding: { color: colorEnc },
       },
       {
         // Invisible wide hit target → precise hover tooltip + click datum.
-        mark: { type: "point", opacity: 0, size: 160 },
+        mark: { type: "point", opacity: 0, size: 160, clip: true },
         encoding: {
           color: colorEnc,
           tooltip: [
@@ -199,11 +278,13 @@ export function scatterSpec(
 
   const layers: Record<string, unknown>[] = [
     {
+      params: interactionParams(["x", "y"]),
       data: { name: "table" },
       mark: clean({
         type: "point",
         filled: true,
         size: markSize,
+        clip: true,
         color: colorEnc
           ? undefined
           : ((marker.color as string) ?? theme.palette[0]),
@@ -236,6 +317,7 @@ export function scatterSpec(
         size: markSize * 4,
         stroke: theme.highlightRing,
         strokeWidth: 2,
+        clip: true,
       },
       encoding: {
         x: { field: "x", type: "quantitative" },
@@ -312,7 +394,14 @@ export function barSpec(
   });
 
   const layers: Record<string, unknown>[] = [
-    { data: { name: "table" }, mark: { type: "bar" }, encoding: barEncoding },
+    {
+      // Only the value axis is continuous; the category axis is a band scale
+      // and cannot take a scale binding.
+      params: interactionParams([valChannel]),
+      data: { name: "table" },
+      mark: { type: "bar", clip: true },
+      encoding: barEncoding,
+    },
   ];
 
   // Optional line-over-bars overlay (fed via the "line" dataset).
@@ -320,7 +409,7 @@ export function barSpec(
   if (hasLine) {
     layers.push({
       data: { name: "line" },
-      mark: { type: "line", point: true, strokeWidth: 2 },
+      mark: { type: "line", point: true, strokeWidth: 2, clip: true },
       encoding: {
         [catChannel]: { field: "cat", type: "nominal" },
         [valChannel]: { field: "val", type: "quantitative" },
@@ -373,7 +462,10 @@ export function ganttSpec(
     height,
     autosize: { type: "fit", contains: "padding" },
     data: { name: "table" },
-    mark: { type: "bar", cornerRadius: 2 },
+    // A unit spec, so the params sit at the top level. Only the temporal axis
+    // is continuous; the task-label axis is a band scale.
+    params: interactionParams(["x"]),
+    mark: { type: "bar", cornerRadius: 2, clip: true },
     encoding: {
       x: {
         field: "start",
diff --git a/core/tests/_fake_vega.ts b/core/tests/_fake_vega.ts
index 648a3aa..28f8f0e 100644
--- a/core/tests/_fake_vega.ts
+++ b/core/tests/_fake_vega.ts
@@ -1,5 +1,32 @@
 import type { VegaEmbed } from "../src/vega_loader";
 
+/** A container element carrying a live count of its bound listeners. */
+export type FakeContainer = HTMLElement & { listenerCount(): number };
+
+/**
+ * A container stub honouring the slice of the element contract `VegaChart`
+ * relies on: it binds a wheel listener for axis-hover zoom and queries the
+ * rendered `<svg>`. Headless runs never render, so `querySelector` returns null
+ * and the handler bails. `dims()` supplies its own fallback size, so there is
+ * no `getBoundingClientRect` to stub.
+ *
+ * The pointer classification itself is pure — see `axisChannelAt` — and is
+ * tested directly rather than through this double.
+ */
+export function makeFakeContainer(): FakeContainer {
+  const listeners = new Set<EventListener>();
+  return {
+    addEventListener: (_type: string, fn: EventListener) => {
+      listeners.add(fn);
+    },
+    removeEventListener: (_type: string, fn: EventListener) => {
+      listeners.delete(fn);
+    },
+    querySelector: () => null,
+    listenerCount: () => listeners.size,
+  } as unknown as FakeContainer;
+}
+
 /**
  * A stub vega-embed that records the spec it would render and the data pushed
  * into the view, and lets tests fire a synthetic click. Mirrors the old
diff --git a/core/tests/axis_hover_zoom.test.ts b/core/tests/axis_hover_zoom.test.ts
new file mode 100644
index 0000000..2b1a053
--- /dev/null
+++ b/core/tests/axis_hover_zoom.test.ts
@@ -0,0 +1,73 @@
+import { describe, expect, it } from "@rstest/core";
+import { axisChannelAt, type Bounds } from "../src/chart_base";
+
+/**
+ * `axisChannelAt` decides which axis a wheel is over. Everything else in the
+ * axis-hover path is a three-line adapter from the Vega scenegraph, so this is
+ * where the behaviour is pinned — with plain rectangles, no DOM, no browser.
+ *
+ * Boxes are in the plot rectangle's frame: its interior is [0, W] x [0, H].
+ * The numbers below are the real ones Vega emits for a 343x133 plot.
+ */
+const W = 343;
+const H = 133;
+
+const bottomAxis: Bounds = { x1: -1, x2: 344, y1: 132, y2: 165 };
+const leftAxis: Bounds = { x1: -46, x2: 1, y1: -5, y2: 138 };
+// Vega emits a grid group per axis whose box *is* the plot edge.
+const bottomGrid: Bounds = { x1: 0, x2: W, y1: H, y2: H };
+const leftGrid: Bounds = { x1: 0, x2: 0, y1: 0, y2: H };
+
+const ALL = [bottomGrid, leftGrid, bottomAxis, leftAxis];
+const at = (x: number, y: number, axes: Bounds[] = ALL) =>
+  axisChannelAt(axes, x, y, W, H);
+
+describe("axisChannelAt", () => {
+  it("ignores the plot interior so the wheel scrolls the page", () => {
+    expect(at(W / 2, H / 2)).toBeNull();
+    expect(at(0, 0)).toBeNull();
+    expect(at(W, H)).toBeNull();
+  });
+
+  it("claims x on the bottom axis and y on the left axis", () => {
+    expect(at(W / 2, H + 14)).toBe("x");
+    expect(at(-14, H / 2)).toBe("y");
+  });
+
+  it("never classifies a grid, whose box is the plot edge itself", () => {
+    // Grids overlap the interior, so they must lose to the early return; feed
+    // them alone to prove they never claim a channel on their own either.
+    expect(at(W / 2, H, [bottomGrid])).toBeNull();
+    expect(at(0, H / 2, [leftGrid])).toBeNull();
+  });
+
+  it("leaves a legend drawn under the x axis inert", () => {
+    // Vega tags legends role:"legend", so they never reach here. A wheel below
+    // the bottom axis therefore lands outside every axis box.
+    expect(at(W / 2, 200)).toBeNull();
+  });
+
+  it("ignores the corner beside and below the plot", () => {
+    expect(at(-14, H + 14)).toBeNull();
+  });
+
+  it("prefers x when an axis box spans both gutters", () => {
+    // leftAxis reaches y = -5..138, past the plot's bottom edge; the pointer at
+    // its lower-left corner is inside its box but the box is a y gutter.
+    expect(at(-20, H + 2)).toBe("y");
+  });
+
+  it("classifies a top axis as x", () => {
+    const topAxis: Bounds = { x1: -1, x2: 344, y1: -34, y2: 1 };
+    expect(at(W / 2, -14, [topAxis])).toBe("x");
+  });
+
+  it("classifies a right axis as y", () => {
+    const rightAxis: Bounds = { x1: W - 1, x2: W + 46, y1: -5, y2: 138 };
+    expect(at(W + 14, H / 2, [rightAxis])).toBe("y");
+  });
+
+  it("claims nothing when the chart drew no axes", () => {
+    expect(at(-14, H / 2, [])).toBeNull();
+  });
+});
diff --git a/core/tests/line_chart.test.ts b/core/tests/line_chart.test.ts
index 97d260c..eae16c5 100644
--- a/core/tests/line_chart.test.ts
+++ b/core/tests/line_chart.test.ts
@@ -1,12 +1,18 @@
 import { afterEach, beforeEach, describe, expect, it } from "@rstest/core";
 import { LineChart } from "../src/line_chart";
 import { __setVegaEmbedForTesting } from "../src/vega_loader";
-import { type FakeVega, makeFakeVega } from "./_fake_vega";
+import {
+  type FakeContainer,
+  type FakeVega,
+  makeFakeContainer,
+  makeFakeVega,
+} from "./_fake_vega";
 
-const container = {} as unknown as HTMLElement;
+let container: FakeContainer;
 let fake: FakeVega;
 
 beforeEach(() => {
+  container = makeFakeContainer();
   fake = makeFakeVega();
   __setVegaEmbedForTesting(fake.embed);
 });
@@ -79,4 +85,15 @@ describe("LineChart", () => {
     chart.dispose();
     expect(fake.finalized).toBe(1);
   });
+
+  it("binds one axis-hover wheel listener and drops it on dispose", async () => {
+    // The listener lives on the container, which survives every re-embed, so
+    // setAxisRange (which re-embeds) must not add a second one.
+    const chart = new LineChart(container, { series: [{ id: "a" }] });
+    await chart.ready();
+    await chart.setAxisRange("x", [0, 1]);
+    expect(container.listenerCount()).toBe(1);
+    chart.dispose();
+    expect(container.listenerCount()).toBe(0);
+  });
 });
diff --git a/core/tests/scatter_chart.test.ts b/core/tests/scatter_chart.test.ts
index 52ea089..86aea80 100644
--- a/core/tests/scatter_chart.test.ts
+++ b/core/tests/scatter_chart.test.ts
@@ -1,12 +1,13 @@
 import { afterEach, beforeEach, describe, expect, it } from "@rstest/core";
 import { ScatterChart } from "../src/scatter_chart";
 import { __setVegaEmbedForTesting } from "../src/vega_loader";
-import { type FakeVega, makeFakeVega } from "./_fake_vega";
+import { type FakeVega, makeFakeContainer, makeFakeVega } from "./_fake_vega";
 
-const container = {} as unknown as HTMLElement;
+let container: HTMLElement;
 let fake: FakeVega;
 
 beforeEach(() => {
+  container = makeFakeContainer();
   fake = makeFakeVega();
   __setVegaEmbedForTesting(fake.embed);
 });
diff --git a/core/tests/specs.test.ts b/core/tests/specs.test.ts
index 06c46ce..5543346 100644
--- a/core/tests/specs.test.ts
+++ b/core/tests/specs.test.ts
@@ -1,5 +1,14 @@
 import { describe, expect, it } from "@rstest/core";
-import { barSpec, ganttSpec, lineSpec, scatterSpec } from "../src/specs";
+import { compile } from "vega-lite";
+import {
+  barSpec,
+  ganttSpec,
+  lineSpec,
+  scatterSpec,
+  ZOOM_EVENT_FLAG,
+  ZOOM_PARAM,
+  zoomParamsOf,
+} from "../src/specs";
 import { resolveTheme } from "../src/theme";
 
 // biome-ignore lint/suspicious/noExplicitAny: spec is intentionally loosely typed JSON
@@ -7,6 +16,40 @@ const S = (o: unknown) => o as any;
 
 const light = resolveTheme("light");
 
+/** Compile through the real Vega-Lite, collecting warnings and every signal
+ * name in the emitted Vega spec (top level plus nested group marks). */
+function compiled(spec: unknown) {
+  const warnings: string[] = [];
+  const logger = {
+    level: () => logger,
+    warn: (...a: unknown[]) => {
+      warnings.push(a.join(" "));
+      return logger;
+    },
+    info: () => logger,
+    debug: () => logger,
+    error: () => logger,
+  };
+  // biome-ignore lint/suspicious/noExplicitAny: vega-lite's compile takes a TopLevelSpec
+  const out = compile(spec as any, { logger: logger as any });
+  const names: string[] = [];
+  // biome-ignore lint/suspicious/noExplicitAny: walking untyped Vega output
+  const walk = (node: any) => {
+    for (const s of node.signals ?? []) names.push(s.name);
+    for (const m of node.marks ?? []) if (m.type === "group") walk(m);
+  };
+  walk(out.spec);
+  const duplicates = names.filter((n, i) => names.indexOf(n) !== i);
+  return { vega: S(out.spec), warnings, duplicates };
+}
+
+type Mark = { clip?: boolean };
+
+/** Every mark in the spec tree, whether the spec is layered or a unit spec. */
+// biome-ignore lint/suspicious/noExplicitAny: spec is loosely typed JSON
+const marksOf = (spec: any): Mark[] =>
+  spec.layer ? spec.layer.map((l: { mark: Mark }) => l.mark) : [spec.mark];
+
 describe("lineSpec", () => {
   it("carries the schema, preset config and named data", () => {
     const spec = S(
@@ -137,3 +180,104 @@ describe("ganttSpec", () => {
     expect(spec.encoding.color.scale.range).toEqual(["#22c55e"]);
   });
 });
+
+describe("pan/zoom interaction", () => {
+  const specs = {
+    line: () =>
+      lineSpec({ series: [{ id: "a", mode: "lines+markers" }] }, light),
+    scatter: () =>
+      scatterSpec({ points: [{ x: 0, y: 0 }], xAxis: {}, yAxis: {} }, light),
+    bar: () =>
+      barSpec({ series: [{ id: "a", points: [{ x: "c", y: 1 }] }] }, light),
+    gantt: () =>
+      ganttSpec(
+        {
+          tasks: [{ id: "t", label: "L", start: 0, end: 1, statusGroup: "ok" }],
+          statusColors: { ok: "#22c55e" },
+        },
+        light,
+      ),
+  };
+
+  const cases = Object.entries(specs);
+  const channels = (spec: unknown) =>
+    zoomParamsOf(S(spec)).map((p) => p.select.encodings[0]);
+
+  it.each(
+    cases,
+  )("%s declares one scale binding per zoomable axis", (_k, make) => {
+    for (const param of zoomParamsOf(S(make()))) {
+      expect(param.bind).toBe("scales");
+      expect(param.select.type).toBe("interval");
+      // One param drives exactly one scale, which is what lets a wheel over a
+      // single axis gutter zoom that axis alone.
+      expect(param.select.encodings).toHaveLength(1);
+      const channel = param.select.encodings[0];
+      expect(param.name).toBe(ZOOM_PARAM[channel]);
+      // `view:` (not the default `scope`) is what lets a wheel over an axis
+      // reach the selection at all — axes render with pointer-events: none,
+      // outside the plot group. `VegaChart` stamps the flag; `|| shiftKey`
+      // keeps the spec self-sufficient when nobody stamps it.
+      expect(param.select.zoom).toBe(
+        `view:wheel![event.${ZOOM_EVENT_FLAG[channel]} || event.shiftKey]`,
+      );
+    }
+  });
+
+  it.each(cases)("%s clips every mark to the plot rect", (_k, make) => {
+    // Without clip a zoomed-in mark paints over the axes.
+    for (const mark of marksOf(S(make()))) expect(mark.clip).toBe(true);
+  });
+
+  it.each([
+    ["line", ["x", "y"]],
+    ["scatter", ["x", "y"]],
+    // The remaining axis of each is a band scale, which cannot take a binding.
+    ["bar", ["y"]],
+    ["gantt", ["x"]],
+  ] as const)("%s binds only its continuous channels", (key, want) => {
+    expect(channels(specs[key]())).toEqual(want);
+  });
+
+  it("follows the value axis when a bar chart is horizontal", () => {
+    const horizontal = barSpec(
+      { series: [{ id: "a", points: [] }], orientation: "h" },
+      light,
+    );
+    expect(channels(horizontal)).toEqual(["x"]);
+  });
+
+  it.each(cases)("%s compiles without duplicate Vega signals", (_k, make) => {
+    // A selection param at the top level of a *layered* spec is copied into
+    // every layer; Vega then throws "Duplicate signal name" at parse time while
+    // vl.compile() stays silent. Only a browser (or this test) catches it.
+    expect(compiled(make()).duplicates).toEqual([]);
+  });
+
+  it.each(cases)("%s never binds a discrete scale", (_k, make) => {
+    // Listing a band channel in `encodings` logs "Scale bindings are currently
+    // only supported for scales with unbinned, continuous domains." (ganttSpec
+    // emits unrelated opacity/legend warnings, so match on this one only.)
+    const { warnings } = compiled(make());
+    expect(warnings.filter((w) => w.includes("Scale binding"))).toEqual([]);
+  });
+
+  it("lets the interaction override zero/nice and an explicit domain", () => {
+    // `bind: "scales"` adds domainRaw, which wins over the computed domain at
+    // runtime — so rangemode/tozero still picks the *initial* view only.
+    const spec = lineSpec(
+      {
+        series: [{ id: "a" }],
+        xAxis: { rangemode: "tozero" },
+        yAxis: { range: [0, 5] },
+      },
+      light,
+    );
+    const { vega } = compiled(spec);
+    const scale = (n: string) =>
+      vega.scales.find((s: { name: string }) => s.name === n);
+    expect(scale("x").domainRaw).toEqual({ signal: `${ZOOM_PARAM.x}["x"]` });
+    expect(scale("y").domainRaw).toEqual({ signal: `${ZOOM_PARAM.y}["y"]` });
+    expect(scale("y").domain).toEqual([0, 5]);
+  });
+});
diff --git a/python/src/molplot/specs.py b/python/src/molplot/specs.py
index 2cfd4b3..914ed71 100644
--- a/python/src/molplot/specs.py
+++ b/python/src/molplot/specs.py
@@ -13,11 +13,59 @@
 from .preset import DEFAULT_PRESET, Mode, resolve
 from .vega_config import vega_config
 
-__all__ = ["line_spec", "scatter_spec", "bar_spec", "gantt_spec", "VL_SCHEMA"]
+__all__ = [
+    "line_spec",
+    "scatter_spec",
+    "bar_spec",
+    "gantt_spec",
+    "zoom_params_of",
+    "VL_SCHEMA",
+    "ZOOM_PARAM",
+    "ZOOM_EVENT_FLAG",
+]
 
 VL_SCHEMA = "https://vega.github.io/schema/vega-lite/v5.json"
 _FALLBACK_STATUS = "#a3a3a3"
 
+#: One scale-bound interval selection per zoomable axis.
+ZOOM_PARAM = {"x": "zoomX", "y": "zoomY"}
+
+#: Flags the TS ``VegaChart`` stamps on a wheel event to name the axis gutter
+#: the pointer is over. A Vega event filter is compiled without the signal scope
+#: object, so it may call ``x()`` / ``y()`` but throws on any signal read — which
+#: rules out the ``y() > height`` the region test would otherwise want.
+ZOOM_EVENT_FLAG = {"x": "molplotZoomX", "y": "molplotZoomY"}
+
+
+def zoom_params_of(spec: dict[str, Any]) -> list[dict[str, Any]]:
+    """The zoom params a builder attached, wherever it legally placed them: top
+    level for a unit spec, ``layer[0]`` for a layered one. Mirrors
+    ``zoomParamsOf`` in ``core/src/specs.ts``."""
+    return spec.get("params") or spec["layer"][0]["params"]
+
+
+def _interaction_params(channels: Sequence[str]) -> list[dict[str, Any]]:
+    """Pan/zoom, one param per continuous axis. Mirrors ``interactionParams``
+    in ``core/src/specs.ts``: drag pans, a wheel over one axis gutter zooms that
+    axis, Shift+wheel zooms every bound axis, double click resets.
+
+    Web-only: :func:`molplot.render.render` and ``vl-convert`` both ignore
+    ``params`` and draw the initial view. ``channels`` must name only continuous
+    channels — a band scale cannot take a scale binding.
+    """
+    return [
+        {
+            "name": ZOOM_PARAM[channel],
+            "select": {
+                "type": "interval",
+                "encodings": [channel],
+                "zoom": f"view:wheel![event.{ZOOM_EVENT_FLAG[channel]} || event.shiftKey]",
+            },
+            "bind": "scales",
+        }
+        for channel in channels
+    ]
+
 
 def _clean(d: dict[str, Any]) -> dict[str, Any]:
     return {k: v for k, v in d.items() if v is not None}
@@ -118,10 +166,13 @@ def line_spec(
                 "y": {"field": "y", "type": "quantitative", "axis": _axis(y_label), "scale": _scale(y_log, y_domain)},
             },
             "layer": [
-                {"mark": line_mark, "encoding": line_encoding},
+                # Params belong to exactly one unit layer: at the top level of a
+                # layered spec Vega-Lite copies them into every layer and Vega
+                # then throws "Duplicate signal name" at parse time.
+                {"params": _interaction_params(["x", "y"]), "mark": line_mark, "encoding": line_encoding},
                 {
                     "transform": [{"filter": {"field": "key", "oneOf": marker_keys}}],
-                    "mark": {"type": "point", "filled": True, "size": theme["geometry"]["markerSize"] ** 2},
+                    "mark": {"type": "point", "filled": True, "size": theme["geometry"]["markerSize"] ** 2, "clip": True},
                     "encoding": {"color": color_enc},
                 },
             ],
@@ -167,11 +218,12 @@ def scatter_spec(
         color_enc = {"field": "c", "type": "nominal", "scale": None, "legend": None}
 
     mark_size = (size or theme["geometry"]["markerSize"]) ** 2
-    mark = _clean({"type": "point", "filled": True, "size": mark_size, "color": None if color_enc else (color if isinstance(color, str) else theme["palette"][0])})
+    mark = _clean({"type": "point", "filled": True, "size": mark_size, "clip": True, "color": None if color_enc else (color if isinstance(color, str) else theme["palette"][0])})
     spec = _base(preset, mode, width, height)
     spec.update(
         {
             "data": {"values": rows},
+            "params": _interaction_params(["x", "y"]),
             "mark": mark,
             "encoding": _clean(
                 {
@@ -230,7 +282,15 @@ def bar_spec(
         }
     )
     spec = _base(preset, mode, width, height)
-    spec.update({"data": {"values": rows}, "mark": {"type": "bar"}, "encoding": encoding})
+    # Only the value axis is continuous; the category axis is a band scale.
+    spec.update(
+        {
+            "data": {"values": rows},
+            "params": _interaction_params([val_channel]),
+            "mark": {"type": "bar", "clip": True},
+            "encoding": encoding,
+        }
+    )
     return spec
 
 
@@ -279,7 +339,9 @@ def gantt_spec(
     spec.update(
         {
             "data": {"values": rows},
-            "mark": {"type": "bar", "cornerRadius": 2},
+            # Only the temporal axis is continuous; the task-label axis is a band scale.
+            "params": _interaction_params(["x"]),
+            "mark": {"type": "bar", "cornerRadius": 2, "clip": True},
             "encoding": {
                 "x": {"field": "start", "type": "temporal", "axis": _axis(x_label), "title": None},
                 "x2": {"field": "end"},
diff --git a/python/tests/test_render.py b/python/tests/test_render.py
index 245011c..18bd63d 100644
--- a/python/tests/test_render.py
+++ b/python/tests/test_render.py
@@ -17,6 +17,9 @@ def test_render_line_draws_one_line_per_series():
             {"id": "b", "x": [0, 1, 2], "y": [2, 1, 4]},
         ]
     )
+    # The builder attaches web-only pan/zoom params; the paper renderer must
+    # ignore them and draw the initial view.
+    assert molplot.specs.zoom_params_of(spec)
     fig, ax = molplot.render(spec)
     assert len(ax.lines) == 2
 
diff --git a/python/tests/test_specs.py b/python/tests/test_specs.py
index 02ab189..bc8400b 100644
--- a/python/tests/test_specs.py
+++ b/python/tests/test_specs.py
@@ -54,3 +54,59 @@ def test_vega_config_matches_preset_palette():
     cfg = molplot.vega_config("molplot")
     assert cfg["range"]["category"][0] == "#1f77b4"
     assert cfg["axis"]["grid"] is True
+
+
+from molplot.specs import ZOOM_EVENT_FLAG, ZOOM_PARAM, zoom_params_of
+
+
+def _marks_of(spec):
+    """Every mark in the spec tree, layered or unit. Mirrors `marksOf` in
+    core/tests/specs.test.ts."""
+    return [layer["mark"] for layer in spec["layer"]] if "layer" in spec else [spec["mark"]]
+
+
+def _channels(spec):
+    return [p["select"]["encodings"][0] for p in zoom_params_of(spec)]
+
+
+def _all_specs():
+    return {
+        "line": molplot.line_spec([{"id": "a", "x": [0, 1], "y": [1, 2]}]),
+        "scatter": molplot.scatter_spec([0, 1], [0, 1]),
+        "bar": molplot.bar_spec(["a"], [{"id": "s", "values": [1]}]),
+        "gantt": molplot.gantt_spec([{"id": "t", "label": "L", "start": 0, "end": 1, "status": "ok"}], {"ok": "#22c55e"}),
+    }
+
+
+def test_every_chart_declares_one_scale_bound_param_per_zoomable_axis():
+    """The interaction is part of the portable spec, so the TS and Python
+    builders must emit it identically (see core/tests/specs.test.ts)."""
+    for spec in _all_specs().values():
+        for param in zoom_params_of(spec):
+            channel = param["select"]["encodings"][0]
+            assert param["name"] == ZOOM_PARAM[channel]
+            assert param["bind"] == "scales"
+            assert param["select"]["type"] == "interval"
+            # One param per scale is what lets an axis-gutter wheel zoom one axis.
+            assert len(param["select"]["encodings"]) == 1
+            # `view:` reaches the axes (they render pointer-events: none, outside
+            # the plot group); the shift clause keeps the spec self-sufficient.
+            flag = ZOOM_EVENT_FLAG[channel]
+            assert param["select"]["zoom"] == f"view:wheel![event.{flag} || event.shiftKey]"
+
+
+def test_only_continuous_channels_are_bound():
+    specs = _all_specs()
+    assert _channels(specs["line"]) == ["x", "y"]
+    assert _channels(specs["scatter"]) == ["x", "y"]
+    # The remaining axis of each is a band scale, which cannot take a binding.
+    assert _channels(specs["bar"]) == ["y"]
+    assert _channels(specs["gantt"]) == ["x"]
+    horizontal = molplot.bar_spec(["a"], [{"id": "s", "values": [1]}], orientation="h")
+    assert _channels(horizontal) == ["x"]
+
+
+def test_marks_are_clipped_to_the_plot_rect():
+    """Without clip a zoomed-in mark paints over the axes."""
+    for spec in _all_specs().values():
+        assert all(mark["clip"] is True for mark in _marks_of(spec))

From 8c29b7db75875666a2f02e6434df5e85881a8ae7 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 10 Jul 2026 11:34:04 +0800
Subject: [PATCH 03/17] feat(page): npm run dev, and spell the gestures out in
 the gallery
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

`npm run dev` now aliases dev:page, so the gallery starts from the repo root
like every other MolCrafts package.

Zoom is gated on hovering an axis or holding shift, neither of which is
discoverable. The header names the four gestures, and each card says which
of its axes can be zoomed — bar and gantt zoom only one, because the other
is a band scale.
---
 CLAUDE.md        |  2 +-
 package.json     |  1 +
 page/src/App.tsx | 37 +++++++++++++++++++++++++++++++++----
 3 files changed, 35 insertions(+), 5 deletions(-)

diff --git a/CLAUDE.md b/CLAUDE.md
index bcfb413..843b797 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -57,7 +57,7 @@ on Vega-Lite so a single spec is portable between the browser and matplotlib.
 ```bash
 npm install
 npm run build:presets    # regenerate generated preset artifacts from presets/*.json
-npm run dev:page         # demo gallery at localhost:3000
+npm run dev              # demo gallery at localhost:3000 (alias of dev:page)
 npm run build:core       # rslib → core/dist (npm publish artifact)
 npm run typecheck        # core + page
 npm test                 # core (rstest, node) + python (pytest)
diff --git a/package.json b/package.json
index 5fa1a73..4f5c808 100644
--- a/package.json
+++ b/package.json
@@ -15,6 +15,7 @@
     "build:core": "npm run build -w core",
     "build:page": "npm run build -w page",
     "build:all": "npm run build:core && npm run build:page",
+    "dev": "npm run dev:page",
     "dev:page": "npm run dev -w page",
     "typecheck:core": "npm run typecheck -w core",
     "typecheck:page": "npm run typecheck -w page",
diff --git a/page/src/App.tsx b/page/src/App.tsx
index dabc0fb..8289503 100644
--- a/page/src/App.tsx
+++ b/page/src/App.tsx
@@ -9,6 +9,15 @@ import { useEffect, useRef, useState } from "react";
 type Kind = "line" | "scatter" | "bar" | "gantt";
 type Disposable = { dispose(): void };
 
+/** Only continuous scales can be bound to the pan/zoom selection, so a chart
+ * with a category (band) axis zooms along one axis only. */
+const AXES_HINT: Record<Kind, string> = {
+  line: "zooms x + y",
+  scatter: "zooms x + y",
+  bar: "zooms y — the category axis is a band scale",
+  gantt: "zooms time — the task axis is a band scale",
+};
+
 function build(kind: Kind, el: HTMLElement, preset: string): Disposable {
   switch (kind) {
     case "line": {
@@ -130,11 +139,19 @@ function ChartCard({ kind, preset }: { kind: Kind; preset: string }) {
         padding: 12,
       }}
     >
-      <h3
-        style={{ margin: "0 0 8px", fontSize: 13, textTransform: "capitalize" }}
+      <div
+        style={{
+          display: "flex",
+          alignItems: "baseline",
+          gap: 8,
+          margin: "0 0 8px",
+        }}
       >
-        {kind}
-      </h3>
+        <h3 style={{ margin: 0, fontSize: 13, textTransform: "capitalize" }}>
+          {kind}
+        </h3>
+        <span style={{ opacity: 0.5, fontSize: 11 }}>{AXES_HINT[kind]}</span>
+      </div>
       <div ref={ref} style={{ height: 260, width: "100%" }} />
     </div>
   );
@@ -172,6 +189,18 @@ export function App() {
           Vega-Lite charts, unified preset — the same specs render to matplotlib
           in Python.
         </span>
+        <span
+          style={{
+            flexBasis: "100%",
+            opacity: 0.6,
+            fontSize: 12,
+            marginTop: 4,
+          }}
+        >
+          <b>wheel over an axis</b> to zoom that axis · <b>drag</b> to pan ·{" "}
+          <b>shift + wheel</b> to zoom both · <b>double click</b> to reset. A
+          wheel over the plot itself is left alone so the page still scrolls.
+        </span>
         <div
           style={{
             marginLeft: "auto",

From 7991091f21004258daf325be4e45ebba1778608b Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 10 Jul 2026 11:34:20 +0800
Subject: [PATCH 04/17] docs: zensical landing page and GitHub Pages deploy
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Moves zensical.toml onto the [project] schema and gives docs/index.md a hero
front matter block (kicker, install command, npm/PyPI/licence badges).

Adds a `doc` dependency group to python/pyproject.toml pinning zensical and
the shared molcrafts-zensical-theme, and a Pages workflow that builds the
site from that group alone — the docs are hand-written Markdown, so the job
needs neither Node, the preset compiler, nor a wheel.
---
 .github/workflows/docs.yml |  66 ++++++++++++++++++++
 docs/index.md              | 122 +++++++++++++++++++++++++++++++++----
 python/pyproject.toml      |  11 ++++
 zensical.toml              |  71 ++++++++++++---------
 4 files changed, 227 insertions(+), 43 deletions(-)
 create mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
new file mode 100644
index 0000000..1be5d2e
--- /dev/null
+++ b/.github/workflows/docs.yml
@@ -0,0 +1,66 @@
+name: Deploy docs to GitHub Pages
+
+# Builds the Zensical site (docs/ + the shared molcrafts theme) and publishes it
+# to https://molcrafts.github.io/molplot/. The docs are hand-written Markdown —
+# Zensical just reads the .md files under docs/ — so this job needs neither Node,
+# the TS `core/` build, the preset compiler, nor a Python wheel. It installs the
+# `doc` dependency group from python/pyproject.toml (zensical + the theme, both
+# on PyPI) and nothing else.
+#
+# One-time repo setup: Settings -> Pages -> Build and deployment -> Source =
+# "GitHub Actions" (this workflow provides the artifact + deployment).
+
+on:
+  push:
+    branches: [master]
+    paths:
+      - "docs/**"
+      - "zensical.toml"
+      - "python/pyproject.toml"
+      - ".github/workflows/docs.yml"
+  workflow_dispatch:
+
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Serialize deployments; let an in-flight publish finish rather than cancelling.
+concurrency:
+  group: pages
+  cancel-in-progress: false
+
+jobs:
+  build:
+    # Canonical repo only — forks have no Pages target, so skip there (matches
+    # the fork -> PR workflow: origin = Roy-Kid, upstream = MolCrafts).
+    if: github.repository == 'MolCrafts/molplot'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: astral-sh/setup-uv@v6
+      - name: Build site
+        # Install the doc group into a venv under python/, then build from the
+        # repo root where zensical.toml lives — it writes the site to ./site.
+        run: |
+          cd python
+          uv venv
+          source .venv/bin/activate
+          uv pip install --group doc
+          cd ..
+          zensical build
+      - uses: actions/configure-pages@v5
+      - uses: actions/upload-pages-artifact@v3
+        with:
+          path: site
+
+  deploy:
+    needs: build
+    if: github.repository == 'MolCrafts/molplot'
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - id: deployment
+        uses: actions/deploy-pages@v4
diff --git a/docs/index.md b/docs/index.md
index 7cdce97..d1c24e9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,18 +1,56 @@
-# MolPlot
+---
+title: MolPlot
+description: Unified scientific charting — Vega-Lite on the web, scienceplots on paper, one preset.
+hide:
+  - navigation
+  - toc
+hero:
+  kicker: MolPlot Manual
+  title: MolPlot
+  description: One preset, one intermediate language, two renderers. Describe a chart once as a Vega-Lite spec; render it in the browser with vega-embed and to a matplotlib figure over scienceplots — sharing palette, type scale, and grid between a dashboard and a manuscript.
+  install:
+    label: Install
+    command: pip install molcrafts-molplot
+  badges:
+    - img: https://img.shields.io/npm/v/@molcrafts/molplot?color=4f46e5&label=npm
+      href: https://www.npmjs.com/package/@molcrafts/molplot
+      alt: npm version
+    - img: https://img.shields.io/pypi/v/molcrafts-molplot?color=4f46e5&label=pypi
+      href: https://pypi.org/project/molcrafts-molplot/
+      alt: PyPI version
+    - img: https://img.shields.io/badge/license-BSD--3--Clause-blue.svg
+      href: https://github.com/MolCrafts/molplot/blob/master/LICENSE
+      alt: License BSD-3-Clause
+  actions:
+    - label: Get started
+      href: getting-started/
+      style: primary
+    - label: Unified Preset
+      href: getting-started/preset/
+    - label: API Reference
+      href: api/
+---
 
-Unified scientific charting for the MolCrafts stack. **One preset, one
-intermediate language, two renderers.**
+<h1 class="molcrafts-sr-only">MolPlot</h1>
 
-- **Web** — `@molcrafts/molplot` renders [Vega-Lite](https://vega.github.io/vega-lite/)
-  specs in the browser via `vega-embed`.
-- **Paper** — `molcrafts-molplot` wraps [scienceplots](https://github.com/garrettj403/SciencePlots)
-  and renders the *same* Vega-Lite spec to matplotlib.
+<div class="molcrafts-manual-home" markdown>
 
-A chart is described once as a Vega-Lite JSON spec (the portable intermediate
-language). The unified preset — defined once in `presets/*.json` — compiles to a
-Vega-Lite `config` on the web and to matplotlib `rcParams` (over scienceplots) in
-Python, so a dashboard chart and a manuscript figure share palette, type scale,
-and grid.
+<section class="molcrafts-manual-section molcrafts-manual-section--compact" markdown>
+
+<div class="molcrafts-manual-section__header" markdown>
+
+<span class="molcrafts-manual-eyebrow">At a glance</span>
+
+## The same chart, in the browser and on paper
+
+</div>
+
+A chart is described once as a [Vega-Lite](https://vega.github.io/vega-lite/)
+spec — the portable intermediate language. The **web** package renders it live;
+the **Python** package renders the *same* spec to a matplotlib figure over
+[scienceplots](https://github.com/garrettj403/SciencePlots). Both read one
+preset, so a dashboard and a manuscript figure share palette, type scale, and
+grid.
 
 ```
                       presets/*.json   ← single source of truth
@@ -24,4 +62,62 @@ and grid.
   vega-embed (web)              render() → matplotlib (paper)
 ```
 
-See [Getting Started](getting-started/index.md).
+</section>
+
+<section class="molcrafts-manual-section" markdown>
+
+<div class="molcrafts-manual-section__header" markdown>
+
+<span class="molcrafts-manual-eyebrow">Two renderers</span>
+
+## Pick your surface
+
+</div>
+
+<dl class="molcrafts-feature-matrix" markdown>
+<dt>Web — <code>@molcrafts/molplot</code></dt>
+<dd markdown>Imperative TypeScript chart classes (`LineChart`, `ScatterChart`, `BarChart`, `GanttChart`, `RawChart`) that build a Vega-Lite spec and render it via `vega-embed`. The Vega runtime is lazy and externalized — consumers that never draw a chart never bundle it. `npm install @molcrafts/molplot`.</dd>
+<dt>Paper — <code>molcrafts-molplot</code></dt>
+<dd markdown>A scienceplots wrapper that injects the same preset into matplotlib `rcParams` and renders the *same* Vega-Lite spec to a figure. One-call `line` / `scatter` / `bar` / `gantt`, plus a `use()` / `style()` context manager. `pip install molcrafts-molplot`.</dd>
+<dt>One preset</dt>
+<dd markdown>`presets/*.json` is the single source of truth, compiled to a typed TS const, a Python dict, and `.mplstyle` files. Edit the JSON once; both renderers pick up the change.</dd>
+</dl>
+
+</section>
+
+<section class="molcrafts-manual-section molcrafts-manual-section--compact" markdown>
+
+<div class="molcrafts-manual-section__header" markdown>
+
+<span class="molcrafts-manual-eyebrow">Find your page</span>
+
+## The manual in four chapters
+
+</div>
+
+<nav class="molcrafts-manual-index" aria-label="Manual chapters">
+  <a href="getting-started/">
+    <span>01</span>
+    <strong>Getting Started</strong>
+    <em>Install both packages and draw your first chart on the web and in matplotlib.</em>
+  </a>
+  <a href="getting-started/preset/">
+    <span>02</span>
+    <strong>Unified Preset</strong>
+    <em>The single source of truth: how one JSON preset compiles to a Vega-Lite config and matplotlib rcParams.</em>
+  </a>
+  <a href="getting-started/web/">
+    <span>03</span>
+    <strong>Web (Vega-Lite)</strong>
+    <em>The imperative chart classes, streaming updates, and click handling in the browser.</em>
+  </a>
+  <a href="getting-started/python/">
+    <span>04</span>
+    <strong>Python (scienceplots)</strong>
+    <em>Styling matplotlib with the preset and rendering the same spec to a publication figure.</em>
+  </a>
+</nav>
+
+</section>
+
+</div>
diff --git a/python/pyproject.toml b/python/pyproject.toml
index c04fa6a..40362af 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -36,6 +36,17 @@ dev = [
     "pytest-cov",
 ]
 
+# Docs are built with Zensical from the single site config at ../zensical.toml
+# (the docs tree lives under ../docs/). That config sets `theme.name =
+# "molcrafts"` — the shared MolCrafts brand extension, on PyPI — so the docs
+# build is reproducible from this group alone.
+[dependency-groups]
+doc = [
+    "zensical>=0.0.45",
+    # The molcrafts docs theme (zensical.toml sets `theme.name = "molcrafts"`).
+    "molcrafts-zensical-theme>=0.1.0",
+]
+
 [project.urls]
 Homepage = "https://github.com/MolCrafts/molplot"
 Repository = "https://github.com/MolCrafts/molplot"
diff --git a/zensical.toml b/zensical.toml
index b5c1730..8ee1d32 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -1,33 +1,44 @@
+[project]
+site_name = "MolPlot"
+site_description = "Unified scientific charting: Vega-Lite on the web, scienceplots on paper, one preset."
+site_url = "https://molcrafts.github.io/molplot/"
+repo_url = "https://github.com/MolCrafts/molplot"
+repo_name = "MolCrafts/molplot"
+copyright = "Copyright &copy; 2026 MolCrafts"
 docs_dir = "docs"
 site_dir = "site"
 
-[site]
-name = "MolPlot"
-description = "Unified scientific charting: Vega-Lite on the web, scienceplots on paper, one preset."
-
-[theme]
-palette = "indigo"
-
-[[nav]]
-title = "Home"
-path = "index.md"
-
-[[nav]]
-title = "Getting Started"
-path = "getting-started/index.md"
-
-[[nav]]
-title = "Unified Preset"
-path = "getting-started/preset.md"
-
-[[nav.children]]
-title = "Web (Vega-Lite)"
-path = "getting-started/web.md"
-
-[[nav.children]]
-title = "Python (scienceplots)"
-path = "getting-started/python.md"
-
-[[nav]]
-title = "API"
-path = "api/index.md"
+# Markdown extensions are intentionally not listed: Zensical's built-in default
+# set (admonition, attr_list, def_list, footnotes, md_in_html, toc permalink,
+# pymdownx.{arithmatex,details,emoji,highlight,inlinehilite,superfences,tabbed,
+# tasklist}, and more) already covers everything these docs use — the tabbed
+# web/Python blocks, admonitions, and fenced code.
+
+nav = [
+  { "Home" = "index.md" },
+  { "Getting Started" = "getting-started/index.md" },
+  { "Unified Preset" = [
+    "getting-started/preset.md",
+    { "Web (Vega-Lite)" = "getting-started/web.md" },
+    { "Python (scienceplots)" = "getting-started/python.md" },
+  ] },
+  { "API Reference" = "api/index.md" },
+]
+
+# Shared MolCrafts theme (github.com/MolCrafts/molcrafts-zensical-theme). Provides
+# the brand palette, light/dark schemes, navigation features, and the home-page
+# hero/manual-home component system used by docs/index.md. The package must be
+# installed to build (see the `doc` dependency group in python/pyproject.toml).
+[project.theme]
+name = "molcrafts"
+language = "en"
+
+# Selects the molplot accent (indigo) for links, hovers, and hero eyebrows.
+[project.extra.molcrafts]
+product = "molplot"
+accent = "#4f46e5"                        # primary (主) — molplot signature colour
+accent_soft = "rgba(79, 70, 229, 0.14)"   # secondary (副) — soft fill behind it
+
+[[project.extra.social]]
+icon = "fontawesome/brands/github"
+link = "https://github.com/MolCrafts/molplot"

From b60708b8061d64d2330a2d42334a0ff0f1f5a28d Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 10 Jul 2026 11:34:54 +0800
Subject: [PATCH 05/17] chore(release): v0.1.1
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Lock the npm package, the Python package and the workspace root to one
version — the v* tag fires release-core.yml and release-python.yml together,
so a mismatch would publish two different versions under one tag.
---
 core/package.json     | 2 +-
 package.json          | 2 +-
 python/pyproject.toml | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/core/package.json b/core/package.json
index 93e7ef6..d4780e8 100644
--- a/core/package.json
+++ b/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@molcrafts/molplot",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "type": "module",
   "exports": {
     ".": {
diff --git a/package.json b/package.json
index 4f5c808..44a459c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "molplot",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "MolPlot — Vega-Lite scientific charting with a unified, matplotlib-portable preset",
   "author": "Roy Kid",
   "license": "BSD-3-Clause",
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 40362af..44507fe 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "molcrafts-molplot"
-version = "0.1.0"
+version = "0.1.1"
 description = "Unified scientific charting: scienceplots + a matplotlib-portable Vega-Lite preset"
 readme = "README.md"
 license = "BSD-3-Clause"

From 2d9bcecfe367268686c7287fd59cb11ff76ac2d9 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 10 Jul 2026 11:46:49 +0800
Subject: [PATCH 06/17] fix(docs): drop the GitHub Pages workflow, point the
 site at Cloudflare
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The workflow was copied from molpack, which still publishes to
molcrafts.github.io. This repo has no Pages site, so `actions/configure-pages`
failed on the first push to master with "Get Pages site failed".

Docs here deploy the way molpy and molvis do: Cloudflare builds the Zensical
site straight from the repo, and neither of those ships a docs workflow. So
remove ours and move site_url onto the same <name>.molcrafts.org convention.

The `doc` dependency group stays — the Cloudflare build installs zensical and
the shared molcrafts theme from it.
---
 .github/workflows/docs.yml | 66 --------------------------------------
 zensical.toml              |  2 +-
 2 files changed, 1 insertion(+), 67 deletions(-)
 delete mode 100644 .github/workflows/docs.yml

diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
deleted file mode 100644
index 1be5d2e..0000000
--- a/.github/workflows/docs.yml
+++ /dev/null
@@ -1,66 +0,0 @@
-name: Deploy docs to GitHub Pages
-
-# Builds the Zensical site (docs/ + the shared molcrafts theme) and publishes it
-# to https://molcrafts.github.io/molplot/. The docs are hand-written Markdown —
-# Zensical just reads the .md files under docs/ — so this job needs neither Node,
-# the TS `core/` build, the preset compiler, nor a Python wheel. It installs the
-# `doc` dependency group from python/pyproject.toml (zensical + the theme, both
-# on PyPI) and nothing else.
-#
-# One-time repo setup: Settings -> Pages -> Build and deployment -> Source =
-# "GitHub Actions" (this workflow provides the artifact + deployment).
-
-on:
-  push:
-    branches: [master]
-    paths:
-      - "docs/**"
-      - "zensical.toml"
-      - "python/pyproject.toml"
-      - ".github/workflows/docs.yml"
-  workflow_dispatch:
-
-permissions:
-  contents: read
-  pages: write
-  id-token: write
-
-# Serialize deployments; let an in-flight publish finish rather than cancelling.
-concurrency:
-  group: pages
-  cancel-in-progress: false
-
-jobs:
-  build:
-    # Canonical repo only — forks have no Pages target, so skip there (matches
-    # the fork -> PR workflow: origin = Roy-Kid, upstream = MolCrafts).
-    if: github.repository == 'MolCrafts/molplot'
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v6
-      - uses: astral-sh/setup-uv@v6
-      - name: Build site
-        # Install the doc group into a venv under python/, then build from the
-        # repo root where zensical.toml lives — it writes the site to ./site.
-        run: |
-          cd python
-          uv venv
-          source .venv/bin/activate
-          uv pip install --group doc
-          cd ..
-          zensical build
-      - uses: actions/configure-pages@v5
-      - uses: actions/upload-pages-artifact@v3
-        with:
-          path: site
-
-  deploy:
-    needs: build
-    if: github.repository == 'MolCrafts/molplot'
-    runs-on: ubuntu-latest
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
-    steps:
-      - id: deployment
-        uses: actions/deploy-pages@v4
diff --git a/zensical.toml b/zensical.toml
index 8ee1d32..3d742a4 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -1,7 +1,7 @@
 [project]
 site_name = "MolPlot"
 site_description = "Unified scientific charting: Vega-Lite on the web, scienceplots on paper, one preset."
-site_url = "https://molcrafts.github.io/molplot/"
+site_url = "https://molplot.molcrafts.org/"
 repo_url = "https://github.com/MolCrafts/molplot"
 repo_name = "MolCrafts/molplot"
 copyright = "Copyright &copy; 2026 MolCrafts"

From 8ff1b30ca6c3b4c105c65450af4e22bd1a5e03fb Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 24 Jul 2026 10:46:33 +0200
Subject: [PATCH 07/17] refactor: rework core chart sizing/config; rename page
 demo to example

---
 CLAUDE.md                           |  12 +-
 README.md                           |   6 +-
 core/src/chart_base.ts              |  16 +-
 core/src/element.ts                 |  89 +++++++++-
 core/src/index.ts                   |   2 +
 core/src/raw_chart.ts               |  99 +++++++++++-
 core/src/specs.ts                   |  21 ++-
 core/src/theme.ts                   |  65 ++++++--
 core/tests/element.test.ts          | 166 ++++++++++++++++++-
 core/tests/preset.test.ts           |  30 ++++
 docs/getting-started/web.md         |   9 ++
 {page => example}/package.json      |   2 +-
 {page => example}/rsbuild.config.ts |   6 +-
 example/src/App.tsx                 | 142 ++++++++++++++++
 {page => example}/src/index.tsx     |   0
 {page => example}/tsconfig.json     |   0
 package-lock.json                   |  46 +++---
 package.json                        |   8 +-
 page/src/App.tsx                    | 243 ----------------------------
 19 files changed, 650 insertions(+), 312 deletions(-)
 rename {page => example}/package.json (96%)
 rename {page => example}/rsbuild.config.ts (70%)
 create mode 100644 example/src/App.tsx
 rename {page => example}/src/index.tsx (100%)
 rename {page => example}/tsconfig.json (100%)
 delete mode 100644 page/src/App.tsx

diff --git a/CLAUDE.md b/CLAUDE.md
index 843b797..fe42513 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -47,7 +47,7 @@ on Vega-Lite so a single spec is portable between the browser and matplotlib.
 | Preset compiler | `scripts/build-presets.mjs` |
 | TS chart engine | `core/src/` |
 | TS tests | `core/tests/` |
-| Demo gallery | `page/src/` |
+| Web Component example | `example/src/` |
 | Python package | `python/src/molplot/` |
 | Python tests | `python/tests/` |
 | Docs | `docs/` |
@@ -57,9 +57,9 @@ on Vega-Lite so a single spec is portable between the browser and matplotlib.
 ```bash
 npm install
 npm run build:presets    # regenerate generated preset artifacts from presets/*.json
-npm run dev              # demo gallery at localhost:3000 (alias of dev:page)
+npm run dev              # Web Component example at localhost:3000
 npm run build:core       # rslib → core/dist (npm publish artifact)
-npm run typecheck        # core + page
+npm run typecheck        # core + example
 npm test                 # core (rstest, node) + python (pytest)
 npm run lint             # biome check --write
 cd python && pytest      # python only
@@ -67,14 +67,14 @@ cd python && pytest      # python only
 
 ## Monorepo structure
 
-npm workspaces: `["core", "page"]`. `python/` is a separate hatchling package
-(not an npm workspace). `page/` bundles `@molcrafts/molplot` from **source** via
+npm workspaces: `["core", "example"]`. `python/` is a separate hatchling package
+(not an npm workspace). `example/` bundles `@molcrafts/molplot` from **source** via
 an rsbuild alias; each package's `dist/` is for publish only.
 
 | Package | Path | Purpose |
 |---------|------|---------|
 | `@molcrafts/molplot` | `core/` | Vega-Lite chart classes + spec builders + theme |
-| `page` | `page/` | React 19 demo gallery |
+| `example` | `example/` | React 19 Web Component playground |
 | `molcrafts-molplot` (PyPI) | `python/` | scienceplots wrapper + VL→matplotlib renderer |
 
 ## Critical invariants
diff --git a/README.md b/README.md
index bf0cf2b..7944edd 100644
--- a/README.md
+++ b/README.md
@@ -27,7 +27,7 @@ molplot/
 ├── presets/            # canonical design tokens (single source of truth) + JSON schema
 ├── scripts/            # build-presets.mjs — compiles presets → per-package artifacts
 ├── core/               # @molcrafts/molplot — Vega-Lite chart classes (TypeScript)
-├── page/               # demo gallery (React 19 + rsbuild)
+├── example/            # Web Component example (React 19 + rsbuild)
 ├── python/             # molcrafts-molplot — scienceplots wrapper + VL→matplotlib
 └── docs/               # zensical docs
 ```
@@ -62,8 +62,8 @@ fig, ax = molplot.render(spec)               # same spec → matplotlib figure
 ```bash
 npm install
 npm run build:presets    # regenerate preset artifacts from presets/*.json
-npm run dev:page         # demo gallery at localhost:3000
-npm run typecheck        # core + page
+npm run dev:example      # Web Component example at localhost:3000
+npm run typecheck        # core + example
 npm test                 # core (rstest) + python (pytest)
 npm run lint             # biome
 ```
diff --git a/core/src/chart_base.ts b/core/src/chart_base.ts
index b9138bb..b7e28e8 100644
--- a/core/src/chart_base.ts
+++ b/core/src/chart_base.ts
@@ -296,6 +296,14 @@ export abstract class VegaChart {
     return { width, height };
   }
 
+  /** Whether a ResizeObserver measurement requires a full re-embed. */
+  protected resizeChanged(
+    previous: { width: number; height: number },
+    next: { width: number; height: number },
+  ): boolean {
+    return previous.width !== next.width || previous.height !== next.height;
+  }
+
   private setupResizeObserver(): void {
     if (typeof ResizeObserver === "undefined") return;
     this.resizeObserver = new ResizeObserver(() => {
@@ -304,7 +312,13 @@ export abstract class VegaChart {
         this.resizeRaf = null;
         if (this.disposed) return;
         const { width, height } = this.dims();
-        if (width === this.lastW && height === this.lastH) return;
+        if (
+          !this.resizeChanged(
+            { width: this.lastW, height: this.lastH },
+            { width, height },
+          )
+        )
+          return;
         void this.render();
       });
     });
diff --git a/core/src/element.ts b/core/src/element.ts
index ef27b31..0320326 100644
--- a/core/src/element.ts
+++ b/core/src/element.ts
@@ -26,8 +26,9 @@ import type { ThemeMode } from "./types";
  * ```
  *
  * Attributes: `preset` (unified preset name, default the molplot preset),
- * `theme` (`auto` | `light` | `dark`, default `auto`), and `spec` (inline JSON,
- * a one-line alternative to the script block).
+ * `theme` (`auto` | `light` | `dark`, default `auto`), `interactive` (`false`
+ * disables the default pan/zoom bindings), and `spec` (inline JSON, a one-line
+ * alternative to the script block).
  */
 
 /**
@@ -53,6 +54,52 @@ function parseTheme(value: string | null): ThemeMode {
   return value === "light" || value === "dark" ? value : "auto";
 }
 
+/** Interaction is on by default; accept common false-like HTML values. */
+export function parseInteractive(value: string | null): boolean {
+  if (value === null || value === "") return true;
+  return !["false", "0", "off", "none"].includes(value.toLowerCase());
+}
+
+/** Parse `4:3`, `4/3`, or a numeric width:height ratio. */
+export function parseAspect(value: string | null): number {
+  if (!value) return 4 / 3;
+  const parts = value.split(/[:/]/).map(Number);
+  const ratio =
+    parts.length === 2 && parts[0] && parts[1]
+      ? parts[0] / parts[1]
+      : Number(value);
+  return Number.isFinite(ratio) && ratio > 0 ? ratio : 4 / 3;
+}
+
+const ELEMENT_STYLE_ID = "molplot-element-defaults";
+
+function installElementStyles(): void {
+  if (typeof document === "undefined") return;
+  if (document.getElementById(ELEMENT_STYLE_ID)) return;
+  const style = document.createElement("style");
+  style.id = ELEMENT_STYLE_ID;
+  style.textContent = `
+:where([data-molplot-chart]) {
+  display: block;
+  position: relative;
+  box-sizing: border-box;
+  width: min(100%, var(--molplot-width, 28rem));
+  aspect-ratio: var(--molplot-aspect, 16 / 10);
+  /* Inner air so axis titles clear the host edge without eating the plot. */
+  padding: 0.5rem;
+  overflow: hidden;
+}
+:where([data-molplot-chart]) > :where(.molplot-chart__surface) {
+  position: absolute;
+  inset: 0.5rem;
+  min-width: 0;
+  min-height: 0;
+  overflow: hidden;
+}
+`;
+  document.head.appendChild(style);
+}
+
 /**
  * Register the `<molplot-chart>` custom element. Idempotent and browser-only:
  * a no-op when there is no `customElements` registry (SSR/Node) or the tag is
@@ -67,14 +114,24 @@ export function defineMolplotChart(tag = "molplot-chart"): void {
   )
     return;
   if (customElements.get(tag)) return;
+  installElementStyles();
 
   class MolplotChartElement extends HTMLElement {
-    static readonly observedAttributes = ["spec", "preset", "theme"];
+    static readonly observedAttributes = [
+      "spec",
+      "preset",
+      "theme",
+      "interactive",
+      "width",
+      "aspect",
+    ];
 
     private chart: RawChart | null = null;
     private surface: HTMLElement | null = null;
 
     connectedCallback(): void {
+      this.setAttribute("data-molplot-chart", "");
+      this.applySizing();
       this.mount();
     }
 
@@ -82,7 +139,8 @@ export function defineMolplotChart(tag = "molplot-chart"): void {
       this.teardown();
     }
 
-    attributeChangedCallback(): void {
+    attributeChangedCallback(name: string): void {
+      if (name === "width" || name === "aspect") this.applySizing();
       // Attributes are also set before the first connect; only react once live.
       if (this.isConnected && this.chart) {
         this.teardown();
@@ -96,6 +154,7 @@ export function defineMolplotChart(tag = "molplot-chart"): void {
       // Render into a dedicated child so the base class's `querySelector("svg")`
       // and ResizeObserver have a stable host — never the sibling <script>.
       surface.style.display = "block";
+      surface.className = "molplot-chart__surface";
       this.appendChild(surface);
       this.surface = surface;
 
@@ -108,7 +167,15 @@ export function defineMolplotChart(tag = "molplot-chart"): void {
       const preset =
         (this.getAttribute("preset") as PresetName | null) ?? undefined;
       const theme = parseTheme(this.getAttribute("theme"));
-      this.chart = new RawChart(surface, { spec, preset, theme });
+      const interactive = parseInteractive(this.getAttribute("interactive"));
+      const aspectRatio = parseAspect(this.getAttribute("aspect"));
+      this.chart = new RawChart(surface, {
+        spec,
+        preset,
+        theme,
+        interactive,
+        aspectRatio,
+      });
       void this.chart.ready().then(() => {
         if (this.chart) this.dispatchEvent(new CustomEvent("molplot:ready"));
       });
@@ -120,6 +187,18 @@ export function defineMolplotChart(tag = "molplot-chart"): void {
       this.surface?.remove();
       this.surface = null;
     }
+
+    private applySizing(): void {
+      const width = this.getAttribute("width");
+      const aspect = this.getAttribute("aspect");
+      if (width) this.style.setProperty("--molplot-width", width);
+      else this.style.removeProperty("--molplot-width");
+      if (aspect) {
+        this.style.setProperty("--molplot-aspect", aspect.replace(":", " / "));
+      } else {
+        this.style.removeProperty("--molplot-aspect");
+      }
+    }
   }
 
   customElements.define(tag, MolplotChartElement);
diff --git a/core/src/index.ts b/core/src/index.ts
index c013fcb..55d42c6 100644
--- a/core/src/index.ts
+++ b/core/src/index.ts
@@ -47,6 +47,8 @@ export {
   CHART_DEFAULT_COLOR,
   CHART_PALETTE,
   type ChartTheme,
+  fontScaleForWidth,
+  MOLPLOT_DESIGN_WIDTH,
   resolveTheme,
   vegaConfig,
 } from "./theme";
diff --git a/core/src/raw_chart.ts b/core/src/raw_chart.ts
index 4517f17..3977164 100644
--- a/core/src/raw_chart.ts
+++ b/core/src/raw_chart.ts
@@ -1,7 +1,11 @@
 import { VegaChart } from "./chart_base";
 import type { PresetName } from "./preset";
-import type { VegaLiteSpec } from "./specs";
-import { type ChartTheme, vegaConfig } from "./theme";
+import {
+  interactionParams,
+  type VegaLiteSpec,
+  type ZoomChannel,
+} from "./specs";
+import { type ChartTheme, fontScaleForWidth, vegaConfig } from "./theme";
 import type { ThemeMode } from "./types";
 
 /**
@@ -27,18 +31,28 @@ export interface RawChartConfig {
   preset?: PresetName;
   /** Theme mode. `auto` (default) tracks `<html class="dark">`. */
   theme?: ThemeMode;
+  /** Add scale-bound pan/zoom controls when the spec has none. Default: true. */
+  interactive?: boolean;
+  /** Responsive width:height ratio. Default: 4 / 3. */
+  aspectRatio?: number;
 }
 
 export class RawChart extends VegaChart {
   private spec: VegaLiteSpec;
+  private interactive: boolean;
+  private aspectRatio: number;
 
   constructor(container: HTMLElement, config: RawChartConfig) {
     super(container, config.theme ?? "auto", config.preset);
     this.spec = config.spec;
+    this.interactive = config.interactive ?? true;
+    this.aspectRatio = config.aspectRatio ?? 4 / 3;
   }
 
   async update(config: RawChartConfig): Promise<void> {
     this.spec = config.spec;
+    this.interactive = config.interactive ?? true;
+    this.aspectRatio = config.aspectRatio ?? 4 / 3;
     await this.rerender();
   }
 
@@ -46,17 +60,94 @@ export class RawChart extends VegaChart {
     return {};
   }
 
+  protected resizeChanged(
+    previous: { width: number; height: number },
+    next: { width: number; height: number },
+  ): boolean {
+    // With the default 4:3 size, height is derived exclusively from width.
+    // SVG axes can perturb an auto-height DOM box, but that is render output,
+    // not an input resize. Ignoring it prevents ResizeObserver → re-embed loops.
+    if (this.spec?.height === undefined) return previous.width !== next.width;
+    return super.resizeChanged(previous, next);
+  }
+
   protected buildSpec(
     theme: ChartTheme,
     sizeHint: { width: number; height: number },
   ): VegaLiteSpec {
     const spec = this.spec ?? {};
+    const channels = this.interactive ? continuousChannels(spec) : [];
+    // Prefer the host box height when the element has a real layout size so a
+    // 4:3 (or author aspect) frame is fully painted — not a short SVG floating
+    // in a taller white box. Fall back to width/aspect for headless/zero-size.
+    const derivedHeight = Math.max(
+      1,
+      Math.round(sizeHint.width / this.aspectRatio),
+    );
+    const height =
+      sizeHint.height > 1
+        ? Math.max(1, Math.round(sizeHint.height))
+        : derivedHeight;
+    const scale = fontScaleForWidth(sizeHint.width);
+    const baseConfig = vegaConfig(theme, scale);
+    const authorConfig =
+      spec.config && typeof spec.config === "object"
+        ? (spec.config as Record<string, unknown>)
+        : null;
+    // `fit` + `contains: "padding"`: width/height are the outer SVG box
+    // (axes + legends + pad). Multi-legend specs stay inside the host without
+    // overlapping titles when type sizes stay moderate.
     return {
       $schema: "https://vega.github.io/schema/vega-lite/v5.json",
       width: sizeHint.width,
-      height: sizeHint.height,
+      height,
+      autosize: { type: "fit", contains: "padding" },
       ...spec,
-      config: (spec.config as Record<string, unknown>) ?? vegaConfig(theme),
+      ...(channels.length > 0 && spec.params === undefined
+        ? { params: interactionParams(channels) }
+        : {}),
+      // Always inject the scaled preset; deep-merge author config so partial
+      // docs overrides (font sizes) do not wipe palette / axis colours.
+      config: authorConfig
+        ? deepMergeConfig(baseConfig, authorConfig)
+        : baseConfig,
     };
   }
 }
+
+/** Deep-merge plain config objects (arrays / scalars replaced, objects merged). */
+function deepMergeConfig(
+  base: Record<string, unknown>,
+  over: Record<string, unknown>,
+): Record<string, unknown> {
+  const out: Record<string, unknown> = { ...base };
+  for (const [key, value] of Object.entries(over)) {
+    const prev = out[key];
+    if (
+      value !== null &&
+      typeof value === "object" &&
+      !Array.isArray(value) &&
+      prev !== null &&
+      typeof prev === "object" &&
+      !Array.isArray(prev)
+    ) {
+      out[key] = deepMergeConfig(
+        prev as Record<string, unknown>,
+        value as Record<string, unknown>,
+      );
+    } else {
+      out[key] = value;
+    }
+  }
+  return out;
+}
+
+function continuousChannels(spec: VegaLiteSpec): ZoomChannel[] {
+  const encoding = spec.encoding as
+    | Record<string, { type?: string } | undefined>
+    | undefined;
+  return (["x", "y"] as const).filter((channel) => {
+    const type = encoding?.[channel]?.type;
+    return type === "quantitative" || type === "temporal";
+  });
+}
diff --git a/core/src/specs.ts b/core/src/specs.ts
index 3589ed8..ca39a6e 100644
--- a/core/src/specs.ts
+++ b/core/src/specs.ts
@@ -1,6 +1,6 @@
 import type { BarChartConfig, BarSeriesConfig } from "./bar_chart";
 import type { GanttChartConfig } from "./gantt_chart";
-import { type ChartTheme, vegaConfig } from "./theme";
+import { type ChartTheme, fontScaleForWidth, vegaConfig } from "./theme";
 import type { AxisConfig, LineChartConfig, ScatterChartConfig } from "./types";
 
 /**
@@ -83,7 +83,7 @@ export function zoomParamsOf(spec: VegaLiteSpec): ZoomParam[] {
  * Inert outside the browser: the matplotlib translator and vl-convert both
  * ignore `params` and render the initial view.
  */
-function interactionParams(channels: ZoomChannel[]): ZoomParam[] {
+export function interactionParams(channels: ZoomChannel[]): ZoomParam[] {
   return channels.map((channel) => ({
     name: ZOOM_PARAM[channel],
     select: {
@@ -129,6 +129,15 @@ function size(spec: SpecSize | undefined): {
   return { width: spec?.width ?? "container", height: spec?.height ?? 300 };
 }
 
+/** Preset config with type scaled to the host width when known. */
+function themedConfig(
+  theme: ChartTheme,
+  width: number | "container",
+): Record<string, unknown> {
+  const scale = typeof width === "number" ? fontScaleForWidth(width) : 1;
+  return vegaConfig(theme, scale);
+}
+
 /** LINE — one path per series, per-series width/opacity via nominal scales. */
 export function lineSpec(
   config: LineChartConfig,
@@ -211,7 +220,7 @@ export function lineSpec(
 
   return clean({
     $schema: VL_SCHEMA,
-    config: vegaConfig(theme),
+    config: themedConfig(theme, width),
     width,
     height,
     autosize: { type: "fit", contains: "padding" },
@@ -328,7 +337,7 @@ export function scatterSpec(
 
   return clean({
     $schema: VL_SCHEMA,
-    config: vegaConfig(theme),
+    config: themedConfig(theme, width),
     width,
     height,
     autosize: { type: "fit", contains: "padding" },
@@ -421,7 +430,7 @@ export function barSpec(
 
   return clean({
     $schema: VL_SCHEMA,
-    config: vegaConfig(theme),
+    config: themedConfig(theme, width),
     width,
     height,
     autosize: { type: "fit", contains: "padding" },
@@ -457,7 +466,7 @@ export function ganttSpec(
 
   return clean({
     $schema: VL_SCHEMA,
-    config: vegaConfig(theme),
+    config: themedConfig(theme, width),
     width,
     height,
     autosize: { type: "fit", contains: "padding" },
diff --git a/core/src/theme.ts b/core/src/theme.ts
index 0830d72..97da943 100644
--- a/core/src/theme.ts
+++ b/core/src/theme.ts
@@ -76,18 +76,48 @@ export function resolveTheme(mode: ThemeMode, presetName?: string): ChartTheme {
   };
 }
 
+/**
+ * Paper design width (matches `view.continuousWidth`). At this width the
+ * preset type scale (≈9–12 px) is correct for a 3.5″ figure; wider web hosts
+ * need a scale factor so axis labels stay readable.
+ */
+export const MOLPLOT_DESIGN_WIDTH = 320;
+
+/**
+ * Scale factor for screen / docs hosts.
+ *
+ * Paper preset is ~9–12 px at {@link MOLPLOT_DESIGN_WIDTH}. Docs want roughly
+ * 1.5–1.8× as a floor so labels stay readable without eating the plot area
+ * (multi-legend charts need room). Track width up to 2× on wide hosts.
+ */
+export function fontScaleForWidth(width: number): number {
+  if (!Number.isFinite(width) || width <= 0) return 1.6;
+  const tracked = width / MOLPLOT_DESIGN_WIDTH;
+  return Math.min(2, Math.max(1.5, tracked));
+}
+
 /**
  * Build the Vega-Lite `config` object for a theme. This is the *single*
  * place the unified preset is injected into a spec — the exact counterpart of
  * the matplotlib rcParams the Python package applies, so a spec rendered in
  * the browser and the same spec rendered by scienceplots share palette, type
  * scale, and grid styling.
+ *
+ * @param fontScale - multiplies every type size (1 = paper preset). Web
+ *   hosts should pass {@link fontScaleForWidth} so labels track the chart size.
  */
-export function vegaConfig(theme: ChartTheme): Record<string, unknown> {
+export function vegaConfig(
+  theme: ChartTheme,
+  fontScale = 1,
+): Record<string, unknown> {
+  const scale = Number.isFinite(fontScale) && fontScale > 0 ? fontScale : 1;
+  const px = (n: number) => Math.round(n * scale * 10) / 10;
+  // Modest outer pad — large pads + multi-legend + fixed box crushes the plot.
+  const pad = Math.max(6, Math.round(6 * scale));
   return {
     background: "transparent",
     font: theme.font.family,
-    padding: 4,
+    padding: { left: pad, right: pad, top: pad, bottom: pad },
     axis: {
       labelColor: theme.font.color,
       titleColor: theme.font.color,
@@ -95,29 +125,46 @@ export function vegaConfig(theme: ChartTheme): Record<string, unknown> {
       domainColor: theme.axis.tickColor,
       gridColor: theme.axis.gridColor,
       gridWidth: 0.5,
-      labelFontSize: theme.fontSize.tick,
-      titleFontSize: theme.fontSize.label,
+      labelFontSize: px(theme.fontSize.tick),
+      titleFontSize: px(theme.fontSize.label),
       labelFont: theme.font.family,
       titleFont: theme.font.family,
+      titlePadding: Math.round(6 * scale),
+      labelPadding: Math.round(3 * scale),
       grid: true,
-      tickSize: 4,
+      tickSize: Math.max(4, Math.round(3.5 * scale)),
+      labelLimit: Math.round(160 * scale),
+      titleLimit: Math.round(200 * scale),
+      labelOverlap: true,
+      labelFlush: true,
     },
     legend: {
       labelColor: theme.font.color,
       titleColor: theme.font.color,
-      labelFontSize: theme.fontSize.legend,
-      titleFontSize: theme.fontSize.legend,
+      labelFontSize: px(theme.fontSize.legend),
+      titleFontSize: px(theme.fontSize.legend),
       labelFont: theme.font.family,
       titleFont: theme.font.family,
       symbolType: "circle",
+      titleLimit: Math.round(160 * scale),
+      labelLimit: Math.round(120 * scale),
+      padding: Math.round(4 * scale),
+      offset: Math.round(6 * scale),
+      rowPadding: Math.round(2 * scale),
+      columnPadding: Math.round(4 * scale),
+      symbolSize: Math.round(48 * scale),
     },
     title: {
       color: theme.font.color,
-      fontSize: theme.fontSize.title,
+      fontSize: px(theme.fontSize.title),
       font: theme.font.family,
       fontWeight: 600,
     },
-    view: { stroke: null, continuousWidth: 320, continuousHeight: 200 },
+    view: {
+      stroke: null,
+      continuousWidth: MOLPLOT_DESIGN_WIDTH,
+      continuousHeight: 200,
+    },
     line: { strokeWidth: theme.geometry.lineWidth },
     point: { size: theme.geometry.markerSize * theme.geometry.markerSize },
     bar: { discreteBandSize: undefined },
diff --git a/core/tests/element.test.ts b/core/tests/element.test.ts
index 20280eb..86f1508 100644
--- a/core/tests/element.test.ts
+++ b/core/tests/element.test.ts
@@ -1,5 +1,5 @@
 import { afterEach, beforeEach, describe, expect, it } from "@rstest/core";
-import { parseSpec } from "../src/element";
+import { parseAspect, parseInteractive, parseSpec } from "../src/element";
 import { RawChart } from "../src/raw_chart";
 import { __setVegaEmbedForTesting } from "../src/vega_loader";
 import {
@@ -12,6 +12,15 @@ import {
 let container: FakeContainer;
 let fake: FakeVega;
 
+class InspectableRawChart extends RawChart {
+  resizeWouldRender(
+    previous: { width: number; height: number },
+    next: { width: number; height: number },
+  ): boolean {
+    return this.resizeChanged(previous, next);
+  }
+}
+
 beforeEach(() => {
   container = makeFakeContainer();
   fake = makeFakeVega();
@@ -67,6 +76,27 @@ describe("parseSpec", () => {
   });
 });
 
+describe("parseInteractive", () => {
+  it("defaults to on and accepts false-like attribute values", () => {
+    expect(parseInteractive(null)).toBe(true);
+    expect(parseInteractive("")).toBe(true);
+    expect(parseInteractive("true")).toBe(true);
+    expect(parseInteractive("false")).toBe(false);
+    expect(parseInteractive("OFF")).toBe(false);
+    expect(parseInteractive("0")).toBe(false);
+  });
+});
+
+describe("parseAspect", () => {
+  it("accepts ratio strings and falls back to 4:3", () => {
+    expect(parseAspect(null)).toBeCloseTo(4 / 3);
+    expect(parseAspect("16:9")).toBeCloseTo(16 / 9);
+    expect(parseAspect("3/2")).toBeCloseTo(3 / 2);
+    expect(parseAspect("1.5")).toBeCloseTo(1.5);
+    expect(parseAspect("invalid")).toBeCloseTo(4 / 3);
+  });
+});
+
 // The element renders its parsed spec through RawChart — cover that path (and
 // the new preset/theme fields) directly against the fake embed.
 describe("RawChart (the element's renderer)", () => {
@@ -75,7 +105,10 @@ describe("RawChart (the element's renderer)", () => {
       spec: {
         mark: "line",
         data: { values: [{ x: 0, y: 1 }] },
-        encoding: { x: { field: "x" }, y: { field: "y" } },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+        },
       },
     });
     await chart.ready();
@@ -83,18 +116,143 @@ describe("RawChart (the element's renderer)", () => {
     const drawn = fake.specs[0] as Record<string, unknown>;
     expect(drawn.mark).toBe("line");
     expect(drawn.data).toEqual({ values: [{ x: 0, y: 1 }] });
+    expect(drawn.autosize).toEqual({ type: "fit", contains: "padding" });
+    expect(drawn.params as unknown[]).toHaveLength(2);
     // Unified preset injected as config when the spec carries none.
     expect(drawn.config).toBeTruthy();
     chart.dispose();
   });
 
-  it("respects a spec that carries its own config", async () => {
+  it("can disable default interactions", async () => {
+    const chart = new RawChart(container, {
+      spec: {
+        mark: "line",
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+        },
+      },
+      interactive: false,
+    });
+    await chart.ready();
+    expect((fake.specs[0] as Record<string, unknown>).params).toBeUndefined();
+    chart.dispose();
+  });
+
+  it("uses the host box height when layout size is available", async () => {
+    let measuredHeight = 120;
+    container.getBoundingClientRect = () =>
+      ({ width: 400, height: measuredHeight }) as DOMRect;
+    const chart = new RawChart(container, {
+      spec: {
+        mark: "line",
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+        },
+      },
+    });
+    await chart.ready();
+    expect(fake.specs[0]?.width).toBe(400);
+    // Host box height wins over width/aspect so the frame fills the layout box.
+    expect(fake.specs[0]?.height).toBe(120);
+
+    // Width-only resize re-renders; height feedback is ignored at default ratio
+    // (see resizeChanged). Force a width change to re-measure.
+    measuredHeight = 900;
+    container.getBoundingClientRect = () =>
+      ({ width: 500, height: measuredHeight }) as DOMRect;
+    await chart.resize();
+    expect(fake.specs[1]?.width).toBe(500);
+    expect(fake.specs[1]?.height).toBe(900);
+    chart.dispose();
+  });
+
+  it("ignores height-only ResizeObserver feedback at the default ratio", async () => {
+    const chart = new InspectableRawChart(container, {
+      spec: { mark: "line" },
+    });
+    await chart.ready();
+    expect(
+      chart.resizeWouldRender(
+        { width: 400, height: 300 },
+        { width: 400, height: 900 },
+      ),
+    ).toBe(false);
+    expect(
+      chart.resizeWouldRender(
+        { width: 400, height: 300 },
+        { width: 500, height: 900 },
+      ),
+    ).toBe(true);
+    chart.dispose();
+  });
+
+  it("still responds to height changes when the spec authors a height", async () => {
+    const chart = new InspectableRawChart(container, {
+      spec: { mark: "point", height: 180 },
+    });
+    await chart.ready();
+    expect(
+      chart.resizeWouldRender(
+        { width: 400, height: 180 },
+        { width: 400, height: 240 },
+      ),
+    ).toBe(true);
+    chart.dispose();
+  });
+
+  it("respects an explicitly authored height", async () => {
+    const chart = new RawChart(container, {
+      spec: { mark: "point", height: 180 },
+    });
+    await chart.ready();
+    expect(fake.specs[0]?.height).toBe(180);
+    chart.dispose();
+  });
+
+  it("derives height from aspect ratio when the host box height is tiny", async () => {
+    // chart_base maps height 0 → fallback 320; height 1 keeps the path that
+    // lets RawChart derive from width / aspectRatio.
+    container.getBoundingClientRect = () =>
+      ({ width: 400, height: 1 }) as DOMRect;
+    const chart = new RawChart(container, {
+      spec: { mark: "point" },
+      aspectRatio: 16 / 9,
+    });
+    await chart.ready();
+    expect(fake.specs[0]?.width).toBe(400);
+    expect(fake.specs[0]?.height).toBe(225);
+    chart.dispose();
+  });
+
+  it("preserves explicitly authored interaction params", async () => {
+    const params = [{ name: "pick", select: "point" }];
+    const chart = new RawChart(container, {
+      spec: {
+        mark: "point",
+        params,
+        encoding: { x: { field: "x", type: "quantitative" } },
+      },
+    });
+    await chart.ready();
+    expect((fake.specs[0] as Record<string, unknown>).params).toBe(params);
+    chart.dispose();
+  });
+
+  it("deep-merges author config into the scaled preset", async () => {
     const ownConfig = { background: "red" };
     const chart = new RawChart(container, {
       spec: { mark: "point", config: ownConfig },
     });
     await chart.ready();
-    expect((fake.specs[0] as Record<string, unknown>).config).toBe(ownConfig);
+    const config = (fake.specs[0] as Record<string, unknown>).config as {
+      background?: string;
+      range?: { category?: unknown };
+    };
+    expect(config.background).toBe("red");
+    // Preset tokens remain after merge (not wiped by partial author config).
+    expect(config.range?.category).toBeTruthy();
     chart.dispose();
   });
 
diff --git a/core/tests/preset.test.ts b/core/tests/preset.test.ts
index 8aa15a3..3a461d5 100644
--- a/core/tests/preset.test.ts
+++ b/core/tests/preset.test.ts
@@ -43,4 +43,34 @@ describe("vegaConfig", () => {
     expect(c.axis.grid).toBe(true);
     expect(typeof c.axis.labelFontSize).toBe("number");
   });
+
+  it("scales type sizes for wide web hosts while keeping paper at 1×", () => {
+    const theme = resolveTheme("light");
+    // biome-ignore lint/suspicious/noExplicitAny: loose VL config shape
+    const paper = vegaConfig(theme, 1) as any;
+    // biome-ignore lint/suspicious/noExplicitAny: loose VL config shape
+    const screen = vegaConfig(theme, 1.6) as any;
+    expect(screen.axis.labelFontSize).toBeCloseTo(
+      paper.axis.labelFontSize * 1.6,
+      5,
+    );
+    expect(screen.axis.titleFontSize).toBeCloseTo(
+      paper.axis.titleFontSize * 1.6,
+      5,
+    );
+    expect(screen.title.fontSize).toBeCloseTo(paper.title.fontSize * 1.6, 5);
+  });
+});
+
+describe("fontScaleForWidth", () => {
+  it("is 1 at the paper design width and grows for wider hosts", async () => {
+    const { fontScaleForWidth, MOLPLOT_DESIGN_WIDTH } = await import(
+      "../src/theme"
+    );
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH)).toBe(1.5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.2)).toBeCloseTo(1.5, 5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.8)).toBeCloseTo(1.8, 5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 3)).toBe(2);
+    expect(fontScaleForWidth(0)).toBe(1.6);
+  });
 });
diff --git a/docs/getting-started/web.md b/docs/getting-started/web.md
index f01e59e..aeebb16 100644
--- a/docs/getting-started/web.md
+++ b/docs/getting-started/web.md
@@ -37,6 +37,15 @@ chart.dispose();
 | `GanttChart` | time-spanning bars by status group | `update`, `onTaskClick` |
 | `RawChart` | render an arbitrary Vega-Lite spec | `update({ spec })` |
 
+## Web Component
+
+The self-registering `@molcrafts/molplot/elements` bundle provides a compact
+`<molplot-chart>` with a 4:3 default aspect ratio. Scale-bound pan and zoom are
+enabled by default for quantitative and temporal axes. Set
+`interactive="false"` to render a static chart. Low-specificity component CSS
+keeps the default width at or below `28rem` with compact padding, while allowing
+host styles to override every default.
+
 ## Spec builders
 
 Need the spec without a DOM (SSR, tests, shipping to Python)? Use the pure
diff --git a/page/package.json b/example/package.json
similarity index 96%
rename from page/package.json
rename to example/package.json
index b391339..dcd19d7 100644
--- a/page/package.json
+++ b/example/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "page",
+  "name": "example",
   "version": "0.1.0",
   "private": true,
   "type": "module",
diff --git a/page/rsbuild.config.ts b/example/rsbuild.config.ts
similarity index 70%
rename from page/rsbuild.config.ts
rename to example/rsbuild.config.ts
index 8d0a4c5..46bb68c 100644
--- a/page/rsbuild.config.ts
+++ b/example/rsbuild.config.ts
@@ -2,8 +2,8 @@ import path from "node:path";
 import { defineConfig } from "@rsbuild/core";
 import { pluginReact } from "@rsbuild/plugin-react";
 
-// The demo bundles @molcrafts/molplot from source (not dist) so edits to the
-// core hot-reload here, mirroring the molvis page/ setup.
+// The example bundles @molcrafts/molplot from source (not dist), so edits to
+// the Web Component hot-reload without publishing or rebuilding the package.
 export default defineConfig({
   plugins: [pluginReact()],
   source: {
@@ -19,5 +19,5 @@ export default defineConfig({
     watchFiles: [{ paths: [path.resolve(import.meta.dirname, "../core/src")] }],
   },
   server: { port: 3000 },
-  html: { title: "MolPlot Gallery" },
+  html: { title: "MolPlot Web Component Example" },
 });
diff --git a/example/src/App.tsx b/example/src/App.tsx
new file mode 100644
index 0000000..efc28e3
--- /dev/null
+++ b/example/src/App.tsx
@@ -0,0 +1,142 @@
+import { defineMolplotChart } from "@molcrafts/molplot";
+import { createElement, useEffect, useState } from "react";
+
+defineMolplotChart();
+
+const ENERGY_SPEC = JSON.stringify({
+  mark: { type: "line", point: true },
+  data: {
+    values: [
+      { step: 0, energy: 1 },
+      { step: 1, energy: 0.66 },
+      { step: 2, energy: 0.48 },
+      { step: 3, energy: 0.35 },
+      { step: 4, energy: 0.29 },
+    ],
+  },
+  encoding: {
+    x: {
+      field: "step",
+      type: "quantitative",
+      title: "Simulation step",
+    },
+    y: {
+      field: "energy",
+      type: "quantitative",
+      title: "Energy (a.u.)",
+    },
+  },
+});
+
+export function App() {
+  const [preset, setPreset] = useState("molplot");
+  const [dark, setDark] = useState(false);
+  const [interactive, setInteractive] = useState(true);
+
+  useEffect(() => {
+    document.documentElement.classList.toggle("dark", dark);
+  }, [dark]);
+
+  const foreground = dark ? "#e8eee9" : "#14271d";
+  const background = dark ? "#101813" : "#f5f7f5";
+  const surface = dark ? "#17231b" : "#ffffff";
+  const rule = dark ? "#385044" : "#cad5ce";
+
+  return (
+    <main
+      style={{
+        minHeight: "100vh",
+        boxSizing: "border-box",
+        padding: "32px 20px",
+        background,
+        color: foreground,
+        fontFamily: "Inter, ui-sans-serif, system-ui, sans-serif",
+      }}
+    >
+      <div style={{ width: "min(100%, 760px)", margin: "0 auto" }}>
+        <header style={{ marginBottom: 20 }}>
+          <div
+            style={{
+              fontSize: 11,
+              fontWeight: 700,
+              letterSpacing: "0.12em",
+              textTransform: "uppercase",
+              opacity: 0.58,
+            }}
+          >
+            Local development
+          </div>
+          <h1 style={{ margin: "6px 0 4px", fontSize: 26 }}>
+            MolPlot Web Component Example
+          </h1>
+          <p style={{ margin: 0, fontSize: 14, opacity: 0.68 }}>
+            This page imports <code>core/src</code> directly. Changes hot-reload
+            without an npm release.
+          </p>
+        </header>
+
+        <section
+          style={{
+            display: "flex",
+            flexWrap: "wrap",
+            gap: 16,
+            alignItems: "center",
+            marginBottom: 16,
+            padding: "10px 12px",
+            border: `1px solid ${rule}`,
+            borderRadius: 8,
+            background: surface,
+          }}
+        >
+          <label style={{ fontSize: 13 }}>
+            Preset{" "}
+            <select
+              value={preset}
+              onChange={(event) => setPreset(event.target.value)}
+            >
+              <option value="molplot">molplot</option>
+              <option value="molplot-paper">molplot-paper</option>
+            </select>
+          </label>
+          <label style={{ fontSize: 13 }}>
+            <input
+              type="checkbox"
+              checked={interactive}
+              onChange={(event) => setInteractive(event.target.checked)}
+            />{" "}
+            interactive
+          </label>
+          <label style={{ fontSize: 13 }}>
+            <input
+              type="checkbox"
+              checked={dark}
+              onChange={(event) => setDark(event.target.checked)}
+            />{" "}
+            dark
+          </label>
+        </section>
+
+        <section
+          style={{
+            padding: 6,
+            border: `1px solid ${rule}`,
+            borderRadius: 10,
+            background: surface,
+          }}
+        >
+          {createElement("molplot-chart", {
+            preset,
+            theme: dark ? "dark" : "light",
+            interactive: String(interactive),
+            spec: ENERGY_SPEC,
+          })}
+        </section>
+
+        <p style={{ margin: "12px 2px 0", fontSize: 12, opacity: 0.62 }}>
+          Drag to pan · wheel over an axis to zoom · Shift + wheel zooms both
+          axes · double-click resets.
+        </p>
+      </div>
+    </main>
+  );
+}
diff --git a/page/src/index.tsx b/example/src/index.tsx
similarity index 100%
rename from page/src/index.tsx
rename to example/src/index.tsx
diff --git a/page/tsconfig.json b/example/tsconfig.json
similarity index 100%
rename from page/tsconfig.json
rename to example/tsconfig.json
diff --git a/package-lock.json b/package-lock.json
index 861fc65..eaec9c1 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -10,7 +10,7 @@
       "license": "BSD-3-Clause",
       "workspaces": [
         "core",
-        "page"
+        "example"
       ],
       "devDependencies": {
         "@biomejs/biome": "2.4.16",
@@ -34,6 +34,24 @@
         "typescript": "^6.0.3"
       }
     },
+    "example": {
+      "version": "0.1.0",
+      "dependencies": {
+        "@molcrafts/molplot": "*",
+        "react": "^19.2.6",
+        "react-dom": "^19.2.6",
+        "vega": "^5.30.0",
+        "vega-embed": "^6.29.0",
+        "vega-lite": "^5.21.0"
+      },
+      "devDependencies": {
+        "@rsbuild/core": "^2.0.8",
+        "@rsbuild/plugin-react": "^2.0.0",
+        "@types/react": "^19.0.0",
+        "@types/react-dom": "^19.0.0",
+        "typescript": "^6.0.3"
+      }
+    },
     "node_modules/@ast-grep/napi": {
       "version": "0.37.0",
       "resolved": "https://registry.npmjs.org/@ast-grep/napi/-/napi-0.37.0.tgz",
@@ -1785,6 +1803,10 @@
         "node": ">=6"
       }
     },
+    "node_modules/example": {
+      "resolved": "example",
+      "link": true
+    },
     "node_modules/fast-json-patch": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/fast-json-patch/-/fast-json-patch-3.1.1.tgz",
@@ -1856,10 +1878,6 @@
         }
       }
     },
-    "node_modules/page": {
-      "resolved": "page",
-      "link": true
-    },
     "node_modules/react": {
       "version": "19.2.7",
       "resolved": "https://registry.npmjs.org/react/-/react-19.2.7.tgz",
@@ -2573,24 +2591,6 @@
       "engines": {
         "node": ">=12"
       }
-    },
-    "page": {
-      "version": "0.1.0",
-      "dependencies": {
-        "@molcrafts/molplot": "*",
-        "react": "^19.2.6",
-        "react-dom": "^19.2.6",
-        "vega": "^5.30.0",
-        "vega-embed": "^6.29.0",
-        "vega-lite": "^5.21.0"
-      },
-      "devDependencies": {
-        "@rsbuild/core": "^2.0.8",
-        "@rsbuild/plugin-react": "^2.0.0",
-        "@types/react": "^19.0.0",
-        "@types/react-dom": "^19.0.0",
-        "typescript": "^6.0.3"
-      }
     }
   }
 }
diff --git a/package.json b/package.json
index f753047..c2452b1 100644
--- a/package.json
+++ b/package.json
@@ -7,18 +7,18 @@
   "private": true,
   "workspaces": [
     "core",
-    "page"
+    "example"
   ],
   "scripts": {
     "build:presets": "node scripts/build-presets.mjs",
     "check:presets": "node scripts/build-presets.mjs --check",
     "build:core": "npm run build -w core",
-    "build:page": "npm run build -w page",
+    "build:page": "npm run build -w example",
     "build:all": "npm run build:core && npm run build:page",
     "dev": "npm run dev:page",
-    "dev:page": "npm run dev -w page",
+    "dev:page": "npm run dev -w example",
     "typecheck:core": "npm run typecheck -w core",
-    "typecheck:page": "npm run typecheck -w page",
+    "typecheck:page": "npm run typecheck -w example",
     "typecheck": "npm run typecheck:core && npm run typecheck:page",
     "test:core": "npm run test -w core",
     "test:python": "bash scripts/run-python-tests.sh",
diff --git a/page/src/App.tsx b/page/src/App.tsx
deleted file mode 100644
index 8289503..0000000
--- a/page/src/App.tsx
+++ /dev/null
@@ -1,243 +0,0 @@
-import {
-  BarChart,
-  GanttChart,
-  LineChart,
-  ScatterChart,
-} from "@molcrafts/molplot";
-import { useEffect, useRef, useState } from "react";
-
-type Kind = "line" | "scatter" | "bar" | "gantt";
-type Disposable = { dispose(): void };
-
-/** Only continuous scales can be bound to the pan/zoom selection, so a chart
- * with a category (band) axis zooms along one axis only. */
-const AXES_HINT: Record<Kind, string> = {
-  line: "zooms x + y",
-  scatter: "zooms x + y",
-  bar: "zooms y — the category axis is a band scale",
-  gantt: "zooms time — the task axis is a band scale",
-};
-
-function build(kind: Kind, el: HTMLElement, preset: string): Disposable {
-  switch (kind) {
-    case "line": {
-      const xs = Array.from({ length: 60 }, (_, i) => i);
-      return new LineChart(el, {
-        preset,
-        showLegend: true,
-        xAxis: { label: "step" },
-        yAxis: { label: "energy" },
-        series: [
-          {
-            id: "total",
-            label: "E total",
-            initialPoints: xs.map((x) => ({ x, y: -10 + Math.sin(x / 6) })),
-          },
-          {
-            id: "kin",
-            label: "E kinetic",
-            mode: "lines+markers",
-            initialPoints: xs.map((x) => ({ x, y: 2 + Math.cos(x / 5) })),
-          },
-        ],
-      });
-    }
-    case "scatter": {
-      const pts = Array.from({ length: 200 }, (_, i) => ({
-        x: Math.cos(i) * (1 + i / 200),
-        y: Math.sin(i) * (1 + i / 200),
-        customdata: i,
-      }));
-      return new ScatterChart(el, {
-        preset,
-        points: pts,
-        xAxis: { label: "PC1" },
-        yAxis: { label: "PC2" },
-        marker: {
-          color: pts.map((_, i) => i),
-          colorscale: "viridis",
-          showscale: true,
-        },
-      });
-    }
-    case "bar": {
-      return new BarChart(el, {
-        preset,
-        mode: "stack",
-        showLegend: true,
-        xAxis: { label: "quarter" },
-        yAxis: { label: "runs" },
-        series: [
-          {
-            id: "ok",
-            label: "succeeded",
-            points: ["Q1", "Q2", "Q3", "Q4"].map((x, i) => ({ x, y: 8 + i })),
-          },
-          {
-            id: "fail",
-            label: "failed",
-            points: ["Q1", "Q2", "Q3", "Q4"].map((x, i) => ({
-              x,
-              y: 3 - (i % 2),
-            })),
-          },
-        ],
-      });
-    }
-    case "gantt": {
-      const t0 = Date.UTC(2026, 0, 1);
-      const hr = 3600_000;
-      return new GanttChart(el, {
-        preset,
-        statusColors: {
-          done: "#22c55e",
-          running: "#3b82f6",
-          queued: "#a3a3a3",
-        },
-        statusOpacity: { queued: 0.5 },
-        tasks: [
-          {
-            id: "a",
-            label: "prep",
-            start: t0,
-            end: t0 + 4 * hr,
-            statusGroup: "done",
-          },
-          {
-            id: "b",
-            label: "simulate",
-            start: t0 + 4 * hr,
-            end: t0 + 12 * hr,
-            statusGroup: "running",
-          },
-          {
-            id: "c",
-            label: "analyze",
-            start: t0 + 12 * hr,
-            end: t0 + 16 * hr,
-            statusGroup: "queued",
-          },
-        ],
-      });
-    }
-  }
-}
-
-function ChartCard({ kind, preset }: { kind: Kind; preset: string }) {
-  const ref = useRef<HTMLDivElement>(null);
-  useEffect(() => {
-    const el = ref.current;
-    if (!el) return;
-    const chart = build(kind, el, preset);
-    return () => chart.dispose();
-  }, [kind, preset]);
-  return (
-    <div
-      style={{
-        border: "1px solid rgba(128,128,128,0.3)",
-        borderRadius: 8,
-        padding: 12,
-      }}
-    >
-      <div
-        style={{
-          display: "flex",
-          alignItems: "baseline",
-          gap: 8,
-          margin: "0 0 8px",
-        }}
-      >
-        <h3 style={{ margin: 0, fontSize: 13, textTransform: "capitalize" }}>
-          {kind}
-        </h3>
-        <span style={{ opacity: 0.5, fontSize: 11 }}>{AXES_HINT[kind]}</span>
-      </div>
-      <div ref={ref} style={{ height: 260, width: "100%" }} />
-    </div>
-  );
-}
-
-export function App() {
-  const [preset, setPreset] = useState("molplot");
-  const [dark, setDark] = useState(false);
-
-  useEffect(() => {
-    document.documentElement.classList.toggle("dark", dark);
-    document.body.style.background = dark ? "#111113" : "#ffffff";
-    document.body.style.color = dark ? "#e5e5e5" : "#111827";
-  }, [dark]);
-
-  return (
-    <main
-      style={{
-        fontFamily: "Inter, system-ui, sans-serif",
-        maxWidth: 1100,
-        margin: "0 auto",
-        padding: 24,
-      }}
-    >
-      <header
-        style={{
-          display: "flex",
-          alignItems: "baseline",
-          gap: 16,
-          flexWrap: "wrap",
-        }}
-      >
-        <h1 style={{ fontSize: 20, margin: 0 }}>MolPlot Gallery</h1>
-        <span style={{ opacity: 0.6, fontSize: 12 }}>
-          Vega-Lite charts, unified preset — the same specs render to matplotlib
-          in Python.
-        </span>
-        <span
-          style={{
-            flexBasis: "100%",
-            opacity: 0.6,
-            fontSize: 12,
-            marginTop: 4,
-          }}
-        >
-          <b>wheel over an axis</b> to zoom that axis · <b>drag</b> to pan ·{" "}
-          <b>shift + wheel</b> to zoom both · <b>double click</b> to reset. A
-          wheel over the plot itself is left alone so the page still scrolls.
-        </span>
-        <div
-          style={{
-            marginLeft: "auto",
-            display: "flex",
-            gap: 12,
-            alignItems: "center",
-          }}
-        >
-          <label style={{ fontSize: 12 }}>
-            preset&nbsp;
-            <select value={preset} onChange={(e) => setPreset(e.target.value)}>
-              <option value="molplot">molplot</option>
-              <option value="molplot-paper">molplot-paper</option>
-            </select>
-          </label>
-          <label style={{ fontSize: 12 }}>
-            <input
-              type="checkbox"
-              checked={dark}
-              onChange={(e) => setDark(e.target.checked)}
-            />{" "}
-            dark
-          </label>
-        </div>
-      </header>
-      <section
-        style={{
-          display: "grid",
-          gridTemplateColumns: "repeat(auto-fit, minmax(420px, 1fr))",
-          gap: 16,
-          marginTop: 20,
-        }}
-      >
-        {(["line", "scatter", "bar", "gantt"] as Kind[]).map((k) => (
-          <ChartCard key={k} kind={k} preset={preset} />
-        ))}
-      </section>
-    </main>
-  );
-}

From 28444c47a9c8c7fa6d32c90d04e8b44ff8fd544c Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Fri, 24 Jul 2026 12:01:46 +0200
Subject: [PATCH 08/17] ci: prek + tox gates with tox in pyproject dev

Unify local hooks and CI on `uv run --extra dev tox -e lint|py`.
tox lives in optional-dependencies dev; prek language: system.
---
 .gitignore              | 3 +++
 .pre-commit-config.yaml | 3 +++
 2 files changed, 6 insertions(+)

diff --git a/.gitignore b/.gitignore
index 62e28c8..1006add 100644
--- a/.gitignore
+++ b/.gitignore
@@ -21,3 +21,6 @@ site/
 # OS / editors
 .DS_Store
 *.log
+
+.tox/
+.venv/
diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
index 5dcfd9c..cea7e8d 100644
--- a/.pre-commit-config.yaml
+++ b/.pre-commit-config.yaml
@@ -1,3 +1,6 @@
+# Managed by prek: `prek install`
+default_install_hook_types: [pre-commit, pre-push]
+
 # Local hooks mirror .github/workflows/ci.yml job-for-job so a green pre-push
 # means a green CI. See CLAUDE.md "Build & test".
 repos:

From d10609977e9ac4d32b6dba4fa62c929ff1de82ff Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 18:53:05 +0200
Subject: [PATCH 09/17] feat: scale-bar and arrow annotations (VL layers)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Add portable annotation layers (scaleBar |———|, arrow) in TS and Python.
RawChart/fence top-level `annotations` expand before render; matplotlib
gains rule/text mark encoders. Bump to 0.1.4.
---
 README.md                              |  19 ++
 core/package.json                      |   2 +-
 core/src/annotations.ts                | 316 +++++++++++++++++++++++++
 core/src/chart_base.ts                 |  47 ++--
 core/src/index.ts                      |  18 +-
 core/src/raw_chart.interactive.test.ts |  68 ++++++
 core/src/raw_chart.ts                  |  78 +++++-
 core/tests/annotations.test.ts         |  74 ++++++
 core/tests/element.test.ts             |  32 ++-
 python/pyproject.toml                  |  24 +-
 python/src/molplot/__init__.py         |  11 +-
 python/src/molplot/annotations.py      | 271 +++++++++++++++++++++
 python/src/molplot/vlmpl/interp.py     |   6 +-
 python/src/molplot/vlmpl/marks.py      |  48 ++++
 zensical.toml                          |   2 +-
 15 files changed, 967 insertions(+), 49 deletions(-)
 create mode 100644 core/src/annotations.ts
 create mode 100644 core/src/raw_chart.interactive.test.ts
 create mode 100644 core/tests/annotations.test.ts
 create mode 100644 python/src/molplot/annotations.py

diff --git a/README.md b/README.md
index 7944edd..e5a4c7c 100644
--- a/README.md
+++ b/README.md
@@ -72,6 +72,25 @@ The generated preset files (`core/src/presets/generated.ts`,
 `python/src/molplot/presets/*`) are committed and guarded in CI — run
 `npm run build:presets` after editing any `presets/*.json` and commit the result.
 
+## Documentation
+
+Full manual: [docs.molcrafts.org/molplot](https://docs.molcrafts.org/molplot/)
+(sources in [`docs/`](docs/)):
+
+- [Getting started](https://docs.molcrafts.org/molplot/getting-started/)
+- [Unified preset](https://docs.molcrafts.org/molplot/getting-started/preset/)
+- [Web (Vega-Lite)](https://docs.molcrafts.org/molplot/getting-started/web/)
+- [Python (scienceplots)](https://docs.molcrafts.org/molplot/getting-started/python/)
+- [Charts in Markdown](https://docs.molcrafts.org/molplot/getting-started/markdown/)
+- [API reference](https://docs.molcrafts.org/molplot/api/)
+
+```bash
+# local preview
+pip install -e ./python  # or: pip install molcrafts-molplot
+pip install "zensical>=0.0.53" "molcrafts-zensical-theme>=0.2.5"
+zensical serve
+```
+
 ## License
 
 BSD-3-Clause
diff --git a/core/package.json b/core/package.json
index 89962d1..4431f80 100644
--- a/core/package.json
+++ b/core/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@molcrafts/molplot",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "type": "module",
   "exports": {
     ".": {
diff --git a/core/src/annotations.ts b/core/src/annotations.ts
new file mode 100644
index 0000000..0b07c82
--- /dev/null
+++ b/core/src/annotations.ts
@@ -0,0 +1,316 @@
+import type { VegaLiteSpec } from "./specs";
+
+/**
+ * Chart annotations — portable Vega-Lite layers for paper/web.
+ *
+ * - {@link ScaleBarAnnotation}: a `|———|` scale bar in data coordinates
+ * - {@link ArrowAnnotation}: a directed arrow (rule + tip) with optional label
+ *
+ * Pass via `withAnnotations(spec, …)` or a top-level `annotations` array on a
+ * RawChart / fence spec (stripped before vega-embed).
+ */
+
+export type ScaleBarAnnotation = {
+  kind: "scaleBar";
+  /** Data-coordinate start of the bar (x for horizontal, y for vertical). */
+  x: number;
+  y: number;
+  /** Length in data units along the bar axis. */
+  length: number;
+  label?: string;
+  color?: string;
+  strokeWidth?: number;
+  orientation?: "horizontal" | "vertical";
+  /**
+   * End-cap half-length in data units on the perpendicular axis.
+   * Defaults to a small fraction of `length` (or absolute fallback).
+   */
+  tick?: number;
+};
+
+export type ArrowAnnotation = {
+  kind: "arrow";
+  /** Tail (start). */
+  x: number;
+  y: number;
+  /** Tip (end). */
+  x2: number;
+  y2: number;
+  label?: string;
+  color?: string;
+  strokeWidth?: number;
+  /** Tip mark size (Vega point size, area in px²). Default 55. */
+  tipSize?: number;
+};
+
+export type Annotation = ScaleBarAnnotation | ArrowAnnotation;
+
+function cleanLayer(layer: Record<string, unknown>): VegaLiteSpec {
+  for (const k of Object.keys(layer)) {
+    if (layer[k] === undefined) delete layer[k];
+  }
+  return layer as VegaLiteSpec;
+}
+
+function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
+  const color = a.color ?? "#14271d";
+  const sw = a.strokeWidth ?? 1.6;
+  const horizontal = (a.orientation ?? "horizontal") === "horizontal";
+  const tick =
+    a.tick ??
+    (Number.isFinite(a.length) && a.length !== 0
+      ? Math.abs(a.length) * 0.08
+      : 0.05);
+
+  const layers: VegaLiteSpec[] = [];
+
+  if (horizontal) {
+    const x0 = a.x;
+    const x1 = a.x + a.length;
+    const mid = (x0 + x1) / 2;
+    layers.push(
+      cleanLayer({
+        data: { values: [{ x: x0, x2: x1, y: a.y }] },
+        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          x2: { field: "x2" },
+          y: { field: "y", type: "quantitative" },
+        },
+      }),
+      cleanLayer({
+        data: {
+          values: [
+            { x: x0, y: a.y - tick, y2: a.y + tick },
+            { x: x1, y: a.y - tick, y2: a.y + tick },
+          ],
+        },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+          y2: { field: "y2" },
+        },
+      }),
+    );
+    if (a.label) {
+      layers.push(
+        cleanLayer({
+          data: { values: [{ x: mid, y: a.y, label: a.label }] },
+          mark: {
+            type: "text",
+            dy: 12,
+            fontSize: 11,
+            color,
+            align: "center",
+            baseline: "top",
+          },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" },
+            text: { field: "label", type: "nominal" },
+          },
+        }),
+      );
+    }
+  } else {
+    const y0 = a.y;
+    const y1 = a.y + a.length;
+    const mid = (y0 + y1) / 2;
+    layers.push(
+      cleanLayer({
+        data: { values: [{ x: a.x, y: y0, y2: y1 }] },
+        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+          y2: { field: "y2" },
+        },
+      }),
+      cleanLayer({
+        data: {
+          values: [
+            { x: a.x - tick, x2: a.x + tick, y: y0 },
+            { x: a.x - tick, x2: a.x + tick, y: y1 },
+          ],
+        },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          x2: { field: "x2" },
+          y: { field: "y", type: "quantitative" },
+        },
+      }),
+    );
+    if (a.label) {
+      layers.push(
+        cleanLayer({
+          data: { values: [{ x: a.x, y: mid, label: a.label }] },
+          mark: {
+            type: "text",
+            dx: 10,
+            fontSize: 11,
+            color,
+            align: "left",
+            baseline: "middle",
+          },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" },
+            text: { field: "label", type: "nominal" },
+          },
+        }),
+      );
+    }
+  }
+
+  return layers;
+}
+
+function arrowLayers(a: ArrowAnnotation): VegaLiteSpec[] {
+  const color = a.color ?? "#14271d";
+  const sw = a.strokeWidth ?? 1.6;
+  const tipSize = a.tipSize ?? 55;
+  // Vega point `angle` is degrees clockwise from north; atan2 is from +x CCW.
+  const angleDeg = (Math.atan2(a.y2 - a.y, a.x2 - a.x) * 180) / Math.PI + 90;
+
+  const layers: VegaLiteSpec[] = [
+    cleanLayer({
+      data: {
+        values: [{ x: a.x, y: a.y, x2: a.x2, y2: a.y2 }],
+      },
+      mark: { type: "rule", strokeWidth: sw, color, strokeCap: "round" },
+      encoding: {
+        x: { field: "x", type: "quantitative" },
+        y: { field: "y", type: "quantitative" },
+        x2: { field: "x2" },
+        y2: { field: "y2" },
+      },
+    }),
+    cleanLayer({
+      data: {
+        values: [{ x: a.x2, y: a.y2, angle: angleDeg }],
+      },
+      mark: {
+        type: "point",
+        shape: "triangle",
+        filled: true,
+        size: tipSize,
+        color,
+      },
+      encoding: {
+        x: { field: "x", type: "quantitative" },
+        y: { field: "y", type: "quantitative" },
+        angle: { field: "angle", type: "quantitative" },
+      },
+    }),
+  ];
+
+  if (a.label) {
+    const mx = (a.x + a.x2) / 2;
+    const my = (a.y + a.y2) / 2;
+    layers.push(
+      cleanLayer({
+        data: { values: [{ x: mx, y: my, label: a.label }] },
+        mark: {
+          type: "text",
+          dy: -8,
+          fontSize: 11,
+          color,
+          align: "center",
+          baseline: "bottom",
+        },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+          text: { field: "label", type: "nominal" },
+        },
+      }),
+    );
+  }
+
+  return layers;
+}
+
+/** Expand annotations into Vega-Lite unit layers (own data, no shared scales). */
+export function annotationLayers(annotations: Annotation[]): VegaLiteSpec[] {
+  const out: VegaLiteSpec[] = [];
+  for (const a of annotations) {
+    if (a.kind === "scaleBar") out.push(...scaleBarLayers(a));
+    else if (a.kind === "arrow") out.push(...arrowLayers(a));
+  }
+  return out;
+}
+
+/**
+ * Merge annotation layers into a unit or layered Vega-Lite spec.
+ * Unit specs become layered; existing `layer` arrays are appended to.
+ */
+export function withAnnotations(
+  spec: VegaLiteSpec,
+  annotations: Annotation[] | undefined | null,
+): VegaLiteSpec {
+  if (!annotations?.length) return spec;
+  const extra = annotationLayers(annotations);
+  if (!extra.length) return spec;
+
+  if (Array.isArray(spec.layer)) {
+    return {
+      ...spec,
+      layer: [...(spec.layer as VegaLiteSpec[]), ...extra],
+    };
+  }
+
+  // Unit → layered. Keep top-level data only if the unit layer still needs it
+  // via inheritance; copy unit fields into layer[0] for a self-contained base.
+  const { mark, encoding, data, transform, params, ...rest } = spec as Record<
+    string,
+    unknown
+  >;
+
+  if (mark !== undefined || encoding !== undefined) {
+    const baseLayer: VegaLiteSpec = {};
+    if (data !== undefined) baseLayer.data = data;
+    if (mark !== undefined) baseLayer.mark = mark;
+    if (encoding !== undefined) baseLayer.encoding = encoding;
+    if (transform !== undefined) baseLayer.transform = transform;
+    if (params !== undefined) baseLayer.params = params;
+    return {
+      ...rest,
+      layer: [baseLayer, ...extra],
+    } as VegaLiteSpec;
+  }
+
+  // Already a multi-view / facet without unit marks — attach layers only.
+  return {
+    ...spec,
+    layer: extra,
+  };
+}
+
+/**
+ * Pull a top-level `annotations` key off a fence/RawChart payload and merge.
+ * Returns `{ spec, annotations }` where `spec` has no `annotations` field.
+ */
+export function takeAnnotations(spec: VegaLiteSpec): {
+  spec: VegaLiteSpec;
+  annotations: Annotation[];
+} {
+  const raw = (spec as { annotations?: unknown }).annotations;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    if ("annotations" in spec) {
+      const { annotations: _drop, ...rest } = spec as Record<string, unknown>;
+      return { spec: rest as VegaLiteSpec, annotations: [] };
+    }
+    return { spec, annotations: [] };
+  }
+  const annotations = raw.filter(
+    (a): a is Annotation =>
+      !!a &&
+      typeof a === "object" &&
+      ((a as Annotation).kind === "scaleBar" ||
+        (a as Annotation).kind === "arrow"),
+  );
+  const { annotations: _drop, ...rest } = spec as Record<string, unknown>;
+  return { spec: rest as VegaLiteSpec, annotations };
+}
diff --git a/core/src/chart_base.ts b/core/src/chart_base.ts
index b7e28e8..d25208a 100644
--- a/core/src/chart_base.ts
+++ b/core/src/chart_base.ts
@@ -218,17 +218,15 @@ export abstract class VegaChart {
   }
 
   /**
-   * Wheel over an axis zooms that axis alone. The spec's zoom params filter on
-   * flags this stamps, because a Vega event filter cannot read the `width` /
-   * `height` signals it would need to locate the pointer itself — see
-   * `ZOOM_EVENT_FLAG` in `specs.ts`.
+   * Wheel interaction for scale zoom:
+   * - Axis gutter → that axis alone (classic molplot behaviour)
+   * - Plot interior → both continuous axes (embed-friendly; chat ScrollAreas
+   *   no longer need Shift+wheel for a first useful zoom)
+   * - Shift+wheel still works via the VL filter without flags
    *
-   * Bound once for the chart's life: the listener sits on `container`, which
-   * vega-embed renders into but never replaces.
-   *
-   * Passive, capture phase, and it never calls `preventDefault()`. Consuming
-   * the wheel is Vega's job and it only does so for a wheel its own selector
-   * matched, which is why an unmatched wheel still scrolls the enclosing panel.
+   * Bound once on `container` (vega-embed never replaces it). Non-passive so
+   * we can `preventDefault` and stop the host page/chat from scrolling when
+   * a zoom actually applies.
    */
   private bindAxisHoverZoom(): () => void {
     const onWheel = (event: Event): void => {
@@ -237,16 +235,33 @@ export abstract class VegaChart {
       const rect = this.rendered.getBoundingClientRect();
       const [originX, originY] = view.origin();
       const wheel = event as ZoomWheelEvent;
+      const width = view.signal("width") as number;
+      const height = view.signal("height") as number;
+      const localX = wheel.clientX - rect.left - originX;
+      const localY = wheel.clientY - rect.top - originY;
       const channel = axisChannelAt(
         axisBounds(view.scenegraph().root),
-        wheel.clientX - rect.left - originX,
-        wheel.clientY - rect.top - originY,
-        view.signal("width") as number,
-        view.signal("height") as number,
+        localX,
+        localY,
+        width,
+        height,
       );
-      if (channel) wheel[ZOOM_EVENT_FLAG[channel]] = true;
+      if (channel) {
+        wheel[ZOOM_EVENT_FLAG[channel]] = true;
+        wheel.preventDefault();
+        return;
+      }
+      // Plot interior: stamp both flags so ordinary wheel zooms the chart
+      // (otherwise only gutter hits or Shift+wheel did anything).
+      const inPlot =
+        localX >= 0 && localX <= width && localY >= 0 && localY <= height;
+      if (inPlot || wheel.shiftKey) {
+        wheel[ZOOM_EVENT_FLAG.x] = true;
+        wheel[ZOOM_EVENT_FLAG.y] = true;
+        wheel.preventDefault();
+      }
     };
-    const options = { capture: true, passive: true };
+    const options: AddEventListenerOptions = { capture: true, passive: false };
     this.container.addEventListener("wheel", onWheel, options);
     return () => this.container.removeEventListener("wheel", onWheel, options);
   }
diff --git a/core/src/index.ts b/core/src/index.ts
index 55d42c6..24ae57c 100644
--- a/core/src/index.ts
+++ b/core/src/index.ts
@@ -1,5 +1,16 @@
 // Chart classes (imperative, framework-agnostic) ---------------------------
 
+// Annotations (scale bar, arrows) -----------------------------------------
+export type {
+  Annotation,
+  ArrowAnnotation,
+  ScaleBarAnnotation,
+} from "./annotations";
+export {
+  annotationLayers,
+  takeAnnotations,
+  withAnnotations,
+} from "./annotations";
 export type {
   BarChartConfig,
   BarClickEvent,
@@ -8,10 +19,7 @@ export type {
   BarSeriesConfig,
 } from "./bar_chart";
 export { BarChart } from "./bar_chart";
-// Web Component — register `<molplot-chart>` in the browser. These are plain
-// functions that touch the DOM only when called, so importing the library stays
-// side-effect-free and SSR-safe (no top-level `class extends HTMLElement`). The
-// self-registering browser bundle is the `./elements` subpath.
+// Web Component — register `<molplot-chart>` in the browser.
 export { defineMolplotChart, parseSpec } from "./element";
 export type {
   GanttChartConfig,
@@ -32,7 +40,7 @@ export {
 export type { RawChartConfig } from "./raw_chart";
 export { RawChart } from "./raw_chart";
 export { ScatterChart } from "./scatter_chart";
-// Vega-Lite spec builders — the portable intermediate language --------------
+// Vega-Lite spec builders -------------------------------------------------
 export {
   barSpec,
   ganttSpec,
diff --git a/core/src/raw_chart.interactive.test.ts b/core/src/raw_chart.interactive.test.ts
new file mode 100644
index 0000000..1d10fdf
--- /dev/null
+++ b/core/src/raw_chart.interactive.test.ts
@@ -0,0 +1,68 @@
+/**
+ * RawChart must inject zoom params for layered agent/LLM specs (encoding on
+ * layer[0], not top-level) and must not skip empty ``params: []``.
+ */
+
+import { describe, expect, it } from "@rstest/core";
+import { interactionParams } from "./specs";
+
+// Mirror the pure helpers used by RawChart (kept local so the test stays
+// free of DOM / vega-embed).
+type ZoomChannel = "x" | "y";
+
+function continuousChannels(spec: Record<string, unknown>): ZoomChannel[] {
+  const top = spec.encoding as
+    | Record<string, { type?: string } | undefined>
+    | undefined;
+  const layers = Array.isArray(spec.layer)
+    ? (spec.layer as { encoding?: Record<string, { type?: string }> }[])
+    : [];
+  const encoding =
+    top ?? layers.find((layer) => layer?.encoding)?.encoding ?? undefined;
+  return (["x", "y"] as const).filter((channel) => {
+    const type = encoding?.[channel]?.type;
+    return type === "quantitative" || type === "temporal";
+  });
+}
+
+function mergeZoomParams(existing: unknown, zoom: ReturnType<typeof interactionParams>) {
+  const zoomNames = new Set(zoom.map((p) => p.name));
+  const kept: unknown[] = [];
+  if (Array.isArray(existing)) {
+    for (const p of existing) {
+      const name =
+        p && typeof p === "object" && "name" in p
+          ? String((p as { name: unknown }).name)
+          : "";
+      if (name && zoomNames.has(name as "zoomX" | "zoomY")) continue;
+      kept.push(p);
+    }
+  }
+  return [...kept, ...zoom];
+}
+
+describe("RawChart interactive injection (layered agent specs)", () => {
+  it("finds continuous channels on layer[0].encoding", () => {
+    const channels = continuousChannels({
+      layer: [
+        {
+          encoding: {
+            x: { field: "N", type: "quantitative" },
+            y: { field: "Rg", type: "quantitative" },
+          },
+        },
+      ],
+    });
+    expect(channels).toEqual(["x", "y"]);
+  });
+
+  it("merges zoom params over empty params:[]", () => {
+    const zoom = interactionParams(["x", "y"]);
+    const merged = mergeZoomParams([], zoom);
+    expect(merged).toHaveLength(2);
+    expect(merged.map((p) => (p as { name: string }).name)).toEqual([
+      "zoomX",
+      "zoomY",
+    ]);
+  });
+});
diff --git a/core/src/raw_chart.ts b/core/src/raw_chart.ts
index 3977164..0f848e2 100644
--- a/core/src/raw_chart.ts
+++ b/core/src/raw_chart.ts
@@ -1,3 +1,4 @@
+import { takeAnnotations, withAnnotations } from "./annotations";
 import { VegaChart } from "./chart_base";
 import type { PresetName } from "./preset";
 import {
@@ -75,7 +76,9 @@ export class RawChart extends VegaChart {
     theme: ChartTheme,
     sizeHint: { width: number; height: number },
   ): VegaLiteSpec {
-    const spec = this.spec ?? {};
+    // Strip top-level `annotations` and expand to VL layers (scale bar / arrow).
+    const taken = takeAnnotations({ ...(this.spec ?? {}) });
+    const spec = withAnnotations(taken.spec, taken.annotations);
     const channels = this.interactive ? continuousChannels(spec) : [];
     // Prefer the host box height when the element has a real layout size so a
     // 4:3 (or author aspect) frame is fully painted — not a short SVG floating
@@ -94,27 +97,71 @@ export class RawChart extends VegaChart {
       spec.config && typeof spec.config === "object"
         ? (spec.config as Record<string, unknown>)
         : null;
+    const config = authorConfig
+      ? deepMergeConfig(baseConfig, authorConfig)
+      : baseConfig;
+
     // `fit` + `contains: "padding"`: width/height are the outer SVG box
     // (axes + legends + pad). Multi-legend specs stay inside the host without
     // overlapping titles when type sizes stay moderate.
-    return {
+    const base: VegaLiteSpec = {
       $schema: "https://vega.github.io/schema/vega-lite/v5.json",
       width: sizeHint.width,
       height,
       autosize: { type: "fit", contains: "padding" },
       ...spec,
-      ...(channels.length > 0 && spec.params === undefined
-        ? { params: interactionParams(channels) }
-        : {}),
-      // Always inject the scaled preset; deep-merge author config so partial
-      // docs overrides (font sizes) do not wipe palette / axis colours.
-      config: authorConfig
-        ? deepMergeConfig(baseConfig, authorConfig)
-        : baseConfig,
+      config,
+    };
+
+    if (channels.length === 0) return base;
+
+    const zoom = interactionParams(channels);
+    // Layered agent/LLM specs put encoding on layer[0]; zoom params must live
+    // on a *unit* layer (top-level params on layered specs are illegal /
+    // duplicate). Unit specs take top-level params.
+    const layers = Array.isArray(spec.layer)
+      ? (spec.layer as Record<string, unknown>[])
+      : null;
+    if (layers && layers.length > 0) {
+      const nextLayers = layers.map((layer, i) => {
+        if (i !== 0) return layer;
+        return {
+          ...layer,
+          params: mergeZoomParams(layer.params, zoom),
+        };
+      });
+      // Drop any top-level params so we don't duplicate zoom signal names.
+      const { params: _drop, ...rest } = base;
+      return { ...rest, layer: nextLayers };
+    }
+
+    return {
+      ...base,
+      params: mergeZoomParams(spec.params, zoom),
     };
   }
 }
 
+/** Keep author params; replace/add molplot zoom binds by name. */
+function mergeZoomParams(
+  existing: unknown,
+  zoom: ReturnType<typeof interactionParams>,
+): unknown[] {
+  const zoomNames = new Set(zoom.map((p) => p.name));
+  const kept: unknown[] = [];
+  if (Array.isArray(existing)) {
+    for (const p of existing) {
+      const name =
+        p && typeof p === "object" && "name" in p
+          ? String((p as { name: unknown }).name)
+          : "";
+      if (name && zoomNames.has(name as "zoomX" | "zoomY")) continue;
+      kept.push(p);
+    }
+  }
+  return [...kept, ...zoom];
+}
+
 /** Deep-merge plain config objects (arrays / scalars replaced, objects merged). */
 function deepMergeConfig(
   base: Record<string, unknown>,
@@ -142,10 +189,19 @@ function deepMergeConfig(
   return out;
 }
 
+/**
+ * Continuous x/y channels from a unit spec **or** the first layer of a
+ * layered spec (agent/LLM VL almost always uses ``layer``).
+ */
 function continuousChannels(spec: VegaLiteSpec): ZoomChannel[] {
-  const encoding = spec.encoding as
+  const top = spec.encoding as
     | Record<string, { type?: string } | undefined>
     | undefined;
+  const layers = Array.isArray(spec.layer)
+    ? (spec.layer as { encoding?: Record<string, { type?: string }> }[])
+    : [];
+  const encoding =
+    top ?? layers.find((layer) => layer?.encoding)?.encoding ?? undefined;
   return (["x", "y"] as const).filter((channel) => {
     const type = encoding?.[channel]?.type;
     return type === "quantitative" || type === "temporal";
diff --git a/core/tests/annotations.test.ts b/core/tests/annotations.test.ts
new file mode 100644
index 0000000..c34abd7
--- /dev/null
+++ b/core/tests/annotations.test.ts
@@ -0,0 +1,74 @@
+import { describe, expect, it } from "@rstest/core";
+import {
+  annotationLayers,
+  takeAnnotations,
+  withAnnotations,
+  type Annotation,
+} from "../src/annotations";
+
+describe("annotations", () => {
+  it("builds a horizontal scale bar as rule + end-caps (+ optional label)", () => {
+    const layers = annotationLayers([
+      {
+        kind: "scaleBar",
+        x: 10,
+        y: 1,
+        length: 20,
+        label: "20 τ",
+      },
+    ]);
+    expect(layers.length).toBe(3);
+    expect((layers[0].mark as { type: string }).type).toBe("rule");
+    expect((layers[1].mark as { type: string }).type).toBe("rule");
+    expect((layers[2].mark as { type: string }).type).toBe("text");
+  });
+
+  it("builds an arrow as rule + tip (+ optional label)", () => {
+    const layers = annotationLayers([
+      {
+        kind: "arrow",
+        x: 0,
+        y: 0,
+        x2: 1,
+        y2: 1,
+        label: "diffusive",
+      },
+    ]);
+    expect(layers.length).toBe(3);
+    expect((layers[0].mark as { type: string }).type).toBe("rule");
+    expect((layers[1].mark as { type: string }).type).toBe("point");
+    expect((layers[2].mark as { type: string }).type).toBe("text");
+  });
+
+  it("withAnnotations converts a unit spec into a layered one", () => {
+    const unit = {
+      mark: "line",
+      data: { values: [{ t: 1, msd: 1 }] },
+      encoding: {
+        x: { field: "t", type: "quantitative" },
+        y: { field: "msd", type: "quantitative" },
+      },
+    };
+    const anns: Annotation[] = [
+      { kind: "scaleBar", x: 1, y: 0.5, length: 2, label: "2" },
+    ];
+    const layered = withAnnotations(unit, anns);
+    expect(Array.isArray(layered.layer)).toBe(true);
+    const layers = layered.layer as unknown[];
+    expect(layers.length).toBeGreaterThan(1);
+    expect(layered.mark).toBeUndefined();
+  });
+
+  it("takeAnnotations strips the top-level key", () => {
+    const { spec, annotations } = takeAnnotations({
+      mark: "point",
+      annotations: [
+        { kind: "arrow", x: 0, y: 0, x2: 1, y2: 1 },
+        { kind: "nope" },
+      ],
+    } as never);
+    expect(annotations).toHaveLength(1);
+    expect(annotations[0].kind).toBe("arrow");
+    expect("annotations" in spec).toBe(false);
+  });
+});
diff --git a/core/tests/element.test.ts b/core/tests/element.test.ts
index 86f1508..3ae9442 100644
--- a/core/tests/element.test.ts
+++ b/core/tests/element.test.ts
@@ -226,7 +226,7 @@ describe("RawChart (the element's renderer)", () => {
     chart.dispose();
   });
 
-  it("preserves explicitly authored interaction params", async () => {
+  it("keeps authored params and merges zoom binds for continuous axes", async () => {
     const params = [{ name: "pick", select: "point" }];
     const chart = new RawChart(container, {
       spec: {
@@ -236,7 +236,35 @@ describe("RawChart (the element's renderer)", () => {
       },
     });
     await chart.ready();
-    expect((fake.specs[0] as Record<string, unknown>).params).toBe(params);
+    const out = (fake.specs[0] as Record<string, unknown>).params as {
+      name: string;
+    }[];
+    expect(out.map((p) => p.name)).toEqual(
+      expect.arrayContaining(["pick", "zoomX"]),
+    );
+    chart.dispose();
+  });
+
+  it("injects zoom params on layer[0] for layered agent specs", async () => {
+    const chart = new RawChart(container, {
+      interactive: true,
+      spec: {
+        layer: [
+          {
+            mark: "point",
+            encoding: {
+              x: { field: "N", type: "quantitative" },
+              y: { field: "Rg", type: "quantitative" },
+            },
+          },
+        ],
+      },
+    });
+    await chart.ready();
+    const layers = (fake.specs[0] as { layer: { params?: { name: string }[] }[] })
+      .layer;
+    expect(layers[0].params?.map((p) => p.name)).toEqual(["zoomX", "zoomY"]);
+    expect((fake.specs[0] as { params?: unknown }).params).toBeUndefined();
     chart.dispose();
   });
 
diff --git a/python/pyproject.toml b/python/pyproject.toml
index 4160878..149f783 100644
--- a/python/pyproject.toml
+++ b/python/pyproject.toml
@@ -1,10 +1,10 @@
 [build-system]
-requires = ["hatchling"]
-build-backend = "hatchling.build"
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
 
 [project]
 name = "molcrafts-molplot"
-version = "0.1.3"
+version = "0.1.4"
 description = "Unified scientific charting: scienceplots + a matplotlib-portable Vega-Lite preset"
 readme = "README.md"
 license = "BSD-3-Clause"
@@ -14,7 +14,6 @@ keywords = ["matplotlib", "scienceplots", "vega-lite", "charting", "visualizatio
 classifiers = [
     "Development Status :: 3 - Alpha",
     "Intended Audience :: Science/Research",
-    "License :: OSI Approved :: BSD License",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.10",
     "Programming Language :: Python :: 3.11",
@@ -40,8 +39,8 @@ dev = [
 # Paper charting remains this package (`import molplot`).
 [dependency-groups]
 doc = [
-    "zensical>=0.0.45",
-    "molcrafts-zensical-theme>=0.2.2",
+    "zensical>=0.0.53",
+    "molcrafts-zensical-theme>=0.2.5",
     "molcrafts-molplot",
 ]
 
@@ -49,12 +48,15 @@ doc = [
 Homepage = "https://github.com/MolCrafts/molplot"
 Repository = "https://github.com/MolCrafts/molplot"
 
-[tool.hatch.build.targets.wheel]
-packages = ["src/molplot"]
-artifacts = ["src/molplot/presets/*.mplstyle"]
+[tool.setuptools]
+package-dir = { "" = "src" }
 
-[tool.hatch.build.targets.sdist]
-include = ["/src", "/README.md"]
+[tool.setuptools.packages.find]
+where = ["src"]
+
+# Style sheets generated from presets/*.json — ship them with the package.
+[tool.setuptools.package-data]
+molplot = ["presets/*.mplstyle"]
 
 [tool.pytest.ini_options]
 testpaths = ["tests"]
diff --git a/python/src/molplot/__init__.py b/python/src/molplot/__init__.py
index 1342cf0..735f2e5 100644
--- a/python/src/molplot/__init__.py
+++ b/python/src/molplot/__init__.py
@@ -21,6 +21,11 @@
 
 from __future__ import annotations
 
+from .annotations import (
+    annotation_layers,
+    take_annotations,
+    with_annotations,
+)
 from .charts import bar, gantt, line, scatter
 from .convert import to_png, to_svg
 from .palette import color, cycle, default_color, diverging, palette, sequential
@@ -30,7 +35,7 @@
 from .style import available, register, science_base, style, use
 from .vega_config import vega_config
 
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 # Register the generated *.mplstyle files so `plt.style.use("molplot")` works.
 register()
@@ -63,6 +68,10 @@
     "gantt_spec",
     "vega_config",
     "VL_SCHEMA",
+    # annotations
+    "annotation_layers",
+    "with_annotations",
+    "take_annotations",
     # render
     "render",
     "line",
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
new file mode 100644
index 0000000..f3fe46e
--- /dev/null
+++ b/python/src/molplot/annotations.py
@@ -0,0 +1,271 @@
+"""Chart annotations — portable Vega-Lite layers (mirrors core/src/annotations.ts).
+
+Kinds:
+  * ``scaleBar`` — a ``|———|`` bar in data coordinates
+  * ``arrow``    — directed arrow (rule + tip) with optional label
+
+Use :func:`with_annotations` on any unit/layered VL dict, or put an
+``annotations`` list on a fence / RawChart payload (stripped before render).
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Literal, Mapping, Sequence, TypedDict
+
+__all__ = [
+    "ScaleBarAnnotation",
+    "ArrowAnnotation",
+    "Annotation",
+    "annotation_layers",
+    "with_annotations",
+    "take_annotations",
+]
+
+
+class ScaleBarAnnotation(TypedDict, total=False):
+    kind: Literal["scaleBar"]
+    x: float
+    y: float
+    length: float
+    label: str
+    color: str
+    strokeWidth: float
+    orientation: Literal["horizontal", "vertical"]
+    tick: float
+
+
+class ArrowAnnotation(TypedDict, total=False):
+    kind: Literal["arrow"]
+    x: float
+    y: float
+    x2: float
+    y2: float
+    label: str
+    color: str
+    strokeWidth: float
+    tipSize: float
+
+
+Annotation = ScaleBarAnnotation | ArrowAnnotation
+
+
+def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
+    color = a.get("color") or "#14271d"
+    sw = a.get("strokeWidth") or 1.6
+    horizontal = (a.get("orientation") or "horizontal") == "horizontal"
+    length = float(a["length"])
+    tick = a.get("tick")
+    if tick is None:
+        tick = abs(length) * 0.08 if length else 0.05
+    x, y = float(a["x"]), float(a["y"])
+    layers: list[dict[str, Any]] = []
+
+    if horizontal:
+        x0, x1 = x, x + length
+        mid = (x0 + x1) / 2
+        layers.append(
+            {
+                "data": {"values": [{"x": x0, "x2": x1, "y": y}]},
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "x2": {"field": "x2"},
+                    "y": {"field": "y", "type": "quantitative"},
+                },
+            }
+        )
+        layers.append(
+            {
+                "data": {
+                    "values": [
+                        {"x": x0, "y": y - tick, "y2": y + tick},
+                        {"x": x1, "y": y - tick, "y2": y + tick},
+                    ]
+                },
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "y": {"field": "y", "type": "quantitative"},
+                    "y2": {"field": "y2"},
+                },
+            }
+        )
+        if a.get("label"):
+            layers.append(
+                {
+                    "data": {"values": [{"x": mid, "y": y, "label": a["label"]}]},
+                    "mark": {
+                        "type": "text",
+                        "dy": 12,
+                        "fontSize": 11,
+                        "color": color,
+                        "align": "center",
+                        "baseline": "top",
+                    },
+                    "encoding": {
+                        "x": {"field": "x", "type": "quantitative"},
+                        "y": {"field": "y", "type": "quantitative"},
+                        "text": {"field": "label", "type": "nominal"},
+                    },
+                }
+            )
+    else:
+        y0, y1 = y, y + length
+        mid = (y0 + y1) / 2
+        layers.append(
+            {
+                "data": {"values": [{"x": x, "y": y0, "y2": y1}]},
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "y": {"field": "y", "type": "quantitative"},
+                    "y2": {"field": "y2"},
+                },
+            }
+        )
+        layers.append(
+            {
+                "data": {
+                    "values": [
+                        {"x": x - tick, "x2": x + tick, "y": y0},
+                        {"x": x - tick, "x2": x + tick, "y": y1},
+                    ]
+                },
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "x2": {"field": "x2"},
+                    "y": {"field": "y", "type": "quantitative"},
+                },
+            }
+        )
+        if a.get("label"):
+            layers.append(
+                {
+                    "data": {"values": [{"x": x, "y": mid, "label": a["label"]}]},
+                    "mark": {
+                        "type": "text",
+                        "dx": 10,
+                        "fontSize": 11,
+                        "color": color,
+                        "align": "left",
+                        "baseline": "middle",
+                    },
+                    "encoding": {
+                        "x": {"field": "x", "type": "quantitative"},
+                        "y": {"field": "y", "type": "quantitative"},
+                        "text": {"field": "label", "type": "nominal"},
+                    },
+                }
+            )
+    return layers
+
+
+def _arrow_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
+    color = a.get("color") or "#14271d"
+    sw = a.get("strokeWidth") or 1.6
+    tip_size = a.get("tipSize") or 55
+    x, y = float(a["x"]), float(a["y"])
+    x2, y2 = float(a["x2"]), float(a["y2"])
+    angle = math.degrees(math.atan2(y2 - y, x2 - x)) + 90
+    layers: list[dict[str, Any]] = [
+        {
+            "data": {"values": [{"x": x, "y": y, "x2": x2, "y2": y2}]},
+            "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "round"},
+            "encoding": {
+                "x": {"field": "x", "type": "quantitative"},
+                "y": {"field": "y", "type": "quantitative"},
+                "x2": {"field": "x2"},
+                "y2": {"field": "y2"},
+            },
+        },
+        {
+            "data": {"values": [{"x": x2, "y": y2, "angle": angle}]},
+            "mark": {
+                "type": "point",
+                "shape": "triangle",
+                "filled": True,
+                "size": tip_size,
+                "color": color,
+            },
+            "encoding": {
+                "x": {"field": "x", "type": "quantitative"},
+                "y": {"field": "y", "type": "quantitative"},
+                "angle": {"field": "angle", "type": "quantitative"},
+            },
+        },
+    ]
+    if a.get("label"):
+        layers.append(
+            {
+                "data": {
+                    "values": [
+                        {"x": (x + x2) / 2, "y": (y + y2) / 2, "label": a["label"]}
+                    ]
+                },
+                "mark": {
+                    "type": "text",
+                    "dy": -8,
+                    "fontSize": 11,
+                    "color": color,
+                    "align": "center",
+                    "baseline": "bottom",
+                },
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "y": {"field": "y", "type": "quantitative"},
+                    "text": {"field": "label", "type": "nominal"},
+                },
+            }
+        )
+    return layers
+
+
+def annotation_layers(annotations: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    out: list[dict[str, Any]] = []
+    for a in annotations:
+        kind = a.get("kind")
+        if kind == "scaleBar":
+            out.extend(_scale_bar_layers(a))
+        elif kind == "arrow":
+            out.extend(_arrow_layers(a))
+    return out
+
+
+def with_annotations(
+    spec: dict[str, Any],
+    annotations: Sequence[Mapping[str, Any]] | None,
+) -> dict[str, Any]:
+    """Merge annotation layers into a unit or layered Vega-Lite spec."""
+    if not annotations:
+        return spec
+    extra = annotation_layers(annotations)
+    if not extra:
+        return spec
+    if isinstance(spec.get("layer"), list):
+        return {**spec, "layer": [*spec["layer"], *extra]}
+    if "mark" in spec or "encoding" in spec:
+        base = {
+            k: spec[k]
+            for k in ("data", "mark", "encoding", "transform", "params")
+            if k in spec
+        }
+        rest = {k: v for k, v in spec.items() if k not in base}
+        return {**rest, "layer": [base, *extra]}
+    return {**spec, "layer": extra}
+
+
+def take_annotations(spec: dict[str, Any]) -> tuple[dict[str, Any], list[Annotation]]:
+    """Pull top-level ``annotations`` off a payload; return ``(spec, list)``."""
+    raw = spec.get("annotations")
+    if not isinstance(raw, list) or not raw:
+        cleaned = {k: v for k, v in spec.items() if k != "annotations"}
+        return cleaned, []
+    annotations: list[Annotation] = [
+        a  # type: ignore[misc]
+        for a in raw
+        if isinstance(a, dict) and a.get("kind") in ("scaleBar", "arrow")
+    ]
+    cleaned = {k: v for k, v in spec.items() if k != "annotations"}
+    return cleaned, annotations
diff --git a/python/src/molplot/vlmpl/interp.py b/python/src/molplot/vlmpl/interp.py
index 35bacab..09492e5 100644
--- a/python/src/molplot/vlmpl/interp.py
+++ b/python/src/molplot/vlmpl/interp.py
@@ -10,6 +10,7 @@
 from contextlib import nullcontext
 from typing import Any
 
+from ..annotations import take_annotations, with_annotations
 from ..preset import DEFAULT_PRESET, Mode
 from ..style import style as _style
 from .axes import apply_axes
@@ -38,7 +39,10 @@ def render(
     >>> spec = molplot.line_spec([{"id": "a", "x": [0, 1, 2], "y": [1, 3, 2]}])
     >>> fig, ax = molplot.render(spec)
     """
-    units = normalize(spec)
+    cleaned, annotations = take_annotations(spec)
+    if annotations:
+        cleaned = with_annotations(cleaned, annotations)
+    units = normalize(cleaned)
     ctx = _style(preset, mode) if apply_style else nullcontext()
     with ctx:
         fig, ax = _ensure_ax(ax)
diff --git a/python/src/molplot/vlmpl/marks.py b/python/src/molplot/vlmpl/marks.py
index d8f06d5..8cd823f 100644
--- a/python/src/molplot/vlmpl/marks.py
+++ b/python/src/molplot/vlmpl/marks.py
@@ -181,12 +181,60 @@ def _draw_bar_or_interval(ax: Any, rows: list[dict], enc: dict, mark: dict) -> b
     return _draw_bar(ax, rows, enc, mark)
 
 
+def _draw_rule(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    """Rule segments: (x,y)→(x2,y) or (x,y)→(x,y2) or both endpoints free."""
+    if not rows:
+        return False
+    color = mark.get("color")
+    lw = mark.get("strokeWidth", 1.5)
+    for r in rows:
+        x = enc.get("x")
+        y = enc.get("y")
+        x2 = enc.get("x2")
+        y2 = enc.get("y2")
+        x0 = r[x.field] if x and x.field else r.get("x")
+        y0 = r[y.field] if y and y.field else r.get("y")
+        x1 = r[x2.field] if x2 and x2.field else (r.get("x2", x0))
+        y1 = r[y2.field] if y2 and y2.field else (r.get("y2", y0))
+        ax.plot([x0, x1], [y0, y1], color=color, linewidth=lw, solid_capstyle="butt")
+    return False
+
+
+def _draw_text(ax: Any, rows: list[dict], enc: dict, mark: dict) -> bool:
+    if not rows:
+        return False
+    xf = enc["x"].field if enc.get("x") else "x"
+    yf = enc["y"].field if enc.get("y") else "y"
+    tf = enc["text"].field if enc.get("text") else "label"
+    color = mark.get("color")
+    size = mark.get("fontSize", 10)
+    # Approximate Vega dy (px down) as a small data offset is hard; use annotate.
+    dy = mark.get("dy", 0) or 0
+    dx = mark.get("dx", 0) or 0
+    for r in rows:
+        ax.annotate(
+            str(r.get(tf, "")),
+            xy=(r[xf], r[yf]),
+            xytext=(dx, -dy if dy else 0),
+            textcoords="offset points",
+            color=color,
+            fontsize=size,
+            ha=mark.get("align", "center"),
+            va={"top": "top", "bottom": "bottom", "middle": "center"}.get(
+                mark.get("baseline", "middle"), "center"
+            ),
+        )
+    return False
+
+
 MARK_ENCODERS = {
     "line": _draw_line,
     "point": _draw_point,
     "circle": _draw_point,
     "square": _draw_point,
     "bar": _draw_bar_or_interval,
+    "rule": _draw_rule,
+    "text": _draw_text,
 }
 
 
diff --git a/zensical.toml b/zensical.toml
index 07f226c..e9e534b 100644
--- a/zensical.toml
+++ b/zensical.toml
@@ -1,7 +1,7 @@
 [project]
 site_name = "MolPlot"
 site_description = "Unified scientific charting: Vega-Lite on the web, scienceplots on paper, one preset."
-site_url = "https://molplot.molcrafts.org/"
+site_url = "https://docs.molcrafts.org/molplot/"
 repo_url = "https://github.com/MolCrafts/molplot"
 repo_name = "MolCrafts/molplot"
 copyright = "Copyright &copy; 2026 MolCrafts"

From 7af3cc24ef56eeacc2b648f3506fc67db1b7d8b2 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 19:15:10 +0200
Subject: [PATCH 10/17] feat(annotations): log-friendly scaleBar (x2,
 tickRatio)

Support absolute x2/y2 ends and geometric tickRatio for log axes;
region labels use Times italic.
---
 core/src/annotations.ts           | 62 ++++++++++++++++++++++++-------
 python/src/molplot/annotations.py | 39 ++++++++++++++-----
 2 files changed, 78 insertions(+), 23 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 0b07c82..237d69d 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -24,8 +24,18 @@ export type ScaleBarAnnotation = {
   /**
    * End-cap half-length in data units on the perpendicular axis.
    * Defaults to a small fraction of `length` (or absolute fallback).
+   * Prefer {@link tickRatio} on log scales.
    */
   tick?: number;
+  /**
+   * Geometric end-cap half-span on log axes: cap runs from
+   * `y / tickRatio` to `y * tickRatio` (horizontal bar). Default none.
+   */
+  tickRatio?: number;
+  /** Absolute end (overrides `x + length` when set). */
+  x2?: number;
+  /** Absolute end for a vertical bar (overrides `y + length` when set). */
+  y2?: number;
 };
 
 export type ArrowAnnotation = {
@@ -56,18 +66,30 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
   const color = a.color ?? "#14271d";
   const sw = a.strokeWidth ?? 1.6;
   const horizontal = (a.orientation ?? "horizontal") === "horizontal";
-  const tick =
-    a.tick ??
-    (Number.isFinite(a.length) && a.length !== 0
-      ? Math.abs(a.length) * 0.08
-      : 0.05);
-
+  const font = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif";
   const layers: VegaLiteSpec[] = [];
 
   if (horizontal) {
     const x0 = a.x;
-    const x1 = a.x + a.length;
+    const x1 =
+      a.x2 ?? a.x + (Number.isFinite(a.length) ? (a.length as number) : 0);
     const mid = (x0 + x1) / 2;
+    const yLo =
+      a.tickRatio != null
+        ? a.y / a.tickRatio
+        : a.y -
+          (a.tick ??
+            (Number.isFinite(a.length) && a.length
+              ? Math.abs(a.length) * 0.08
+              : 0.05));
+    const yHi =
+      a.tickRatio != null
+        ? a.y * a.tickRatio
+        : a.y +
+          (a.tick ??
+            (Number.isFinite(a.length) && a.length
+              ? Math.abs(a.length) * 0.08
+              : 0.05));
     layers.push(
       cleanLayer({
         data: { values: [{ x: x0, x2: x1, y: a.y }] },
@@ -81,8 +103,8 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
       cleanLayer({
         data: {
           values: [
-            { x: x0, y: a.y - tick, y2: a.y + tick },
-            { x: x1, y: a.y - tick, y2: a.y + tick },
+            { x: x0, y: yLo, y2: yHi },
+            { x: x1, y: yLo, y2: yHi },
           ],
         },
         mark: { type: "rule", strokeWidth: sw, color },
@@ -100,7 +122,9 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
           mark: {
             type: "text",
             dy: 12,
-            fontSize: 11,
+            fontSize: 12,
+            font,
+            fontStyle: "italic",
             color,
             align: "center",
             baseline: "top",
@@ -115,8 +139,16 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
     }
   } else {
     const y0 = a.y;
-    const y1 = a.y + a.length;
+    const y1 =
+      a.y2 ?? a.y + (Number.isFinite(a.length) ? (a.length as number) : 0);
     const mid = (y0 + y1) / 2;
+    const tick =
+      a.tick ??
+      (Number.isFinite(a.length) && a.length
+        ? Math.abs(a.length) * 0.08
+        : 0.05);
+    const xLo = a.tickRatio != null ? a.x / a.tickRatio : a.x - tick;
+    const xHi = a.tickRatio != null ? a.x * a.tickRatio : a.x + tick;
     layers.push(
       cleanLayer({
         data: { values: [{ x: a.x, y: y0, y2: y1 }] },
@@ -130,8 +162,8 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
       cleanLayer({
         data: {
           values: [
-            { x: a.x - tick, x2: a.x + tick, y: y0 },
-            { x: a.x - tick, x2: a.x + tick, y: y1 },
+            { x: xLo, x2: xHi, y: y0 },
+            { x: xLo, x2: xHi, y: y1 },
           ],
         },
         mark: { type: "rule", strokeWidth: sw, color },
@@ -149,7 +181,9 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
           mark: {
             type: "text",
             dx: 10,
-            fontSize: 11,
+            fontSize: 12,
+            font,
+            fontStyle: "italic",
             color,
             align: "left",
             baseline: "middle",
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
index f3fe46e..bd7918b 100644
--- a/python/src/molplot/annotations.py
+++ b/python/src/molplot/annotations.py
@@ -28,11 +28,14 @@ class ScaleBarAnnotation(TypedDict, total=False):
     x: float
     y: float
     length: float
+    x2: float
+    y2: float
     label: str
     color: str
     strokeWidth: float
     orientation: Literal["horizontal", "vertical"]
     tick: float
+    tickRatio: float
 
 
 class ArrowAnnotation(TypedDict, total=False):
@@ -50,20 +53,29 @@ class ArrowAnnotation(TypedDict, total=False):
 Annotation = ScaleBarAnnotation | ArrowAnnotation
 
 
+_SERIF = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif"
+
+
 def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     color = a.get("color") or "#14271d"
     sw = a.get("strokeWidth") or 1.6
     horizontal = (a.get("orientation") or "horizontal") == "horizontal"
-    length = float(a["length"])
+    length = float(a["length"]) if a.get("length") is not None else 0.0
     tick = a.get("tick")
     if tick is None:
         tick = abs(length) * 0.08 if length else 0.05
+    tick_ratio = a.get("tickRatio")
     x, y = float(a["x"]), float(a["y"])
     layers: list[dict[str, Any]] = []
 
     if horizontal:
-        x0, x1 = x, x + length
+        x0 = x
+        x1 = float(a["x2"]) if a.get("x2") is not None else x + length
         mid = (x0 + x1) / 2
+        if tick_ratio is not None:
+            y_lo, y_hi = y / float(tick_ratio), y * float(tick_ratio)
+        else:
+            y_lo, y_hi = y - tick, y + tick
         layers.append(
             {
                 "data": {"values": [{"x": x0, "x2": x1, "y": y}]},
@@ -79,8 +91,8 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
             {
                 "data": {
                     "values": [
-                        {"x": x0, "y": y - tick, "y2": y + tick},
-                        {"x": x1, "y": y - tick, "y2": y + tick},
+                        {"x": x0, "y": y_lo, "y2": y_hi},
+                        {"x": x1, "y": y_lo, "y2": y_hi},
                     ]
                 },
                 "mark": {"type": "rule", "strokeWidth": sw, "color": color},
@@ -98,7 +110,9 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                     "mark": {
                         "type": "text",
                         "dy": 12,
-                        "fontSize": 11,
+                        "fontSize": 12,
+                        "font": _SERIF,
+                        "fontStyle": "italic",
                         "color": color,
                         "align": "center",
                         "baseline": "top",
@@ -111,8 +125,13 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                 }
             )
     else:
-        y0, y1 = y, y + length
+        y0 = y
+        y1 = float(a["y2"]) if a.get("y2") is not None else y + length
         mid = (y0 + y1) / 2
+        if tick_ratio is not None:
+            x_lo, x_hi = x / float(tick_ratio), x * float(tick_ratio)
+        else:
+            x_lo, x_hi = x - tick, x + tick
         layers.append(
             {
                 "data": {"values": [{"x": x, "y": y0, "y2": y1}]},
@@ -128,8 +147,8 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
             {
                 "data": {
                     "values": [
-                        {"x": x - tick, "x2": x + tick, "y": y0},
-                        {"x": x - tick, "x2": x + tick, "y": y1},
+                        {"x": x_lo, "x2": x_hi, "y": y0},
+                        {"x": x_lo, "x2": x_hi, "y": y1},
                     ]
                 },
                 "mark": {"type": "rule", "strokeWidth": sw, "color": color},
@@ -147,7 +166,9 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                     "mark": {
                         "type": "text",
                         "dx": 10,
-                        "fontSize": 11,
+                        "fontSize": 12,
+                        "font": _SERIF,
+                        "fontStyle": "italic",
                         "color": color,
                         "align": "left",
                         "baseline": "middle",

From da77b6a29cc96839b8c0c35175544330ff66a680 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 19:20:03 +0200
Subject: [PATCH 11/17] =?UTF-8?q?feat(type):=202=C3=97=20paper=20floor=20+?=
 =?UTF-8?q?=20width-tracking=20fonts;=20roman=20labels?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

fontScaleForWidth is 2–3× (200% at design width). Axis/text marks use
normal Times style; annotation labels no longer italic or fixed px.
---
 core/src/annotations.ts           | 10 ++++------
 core/src/theme.ts                 | 31 +++++++++++++++++++++----------
 core/tests/preset.test.ts         | 13 +++++++------
 python/src/molplot/annotations.py | 10 ++++------
 4 files changed, 36 insertions(+), 28 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 237d69d..64d317c 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -121,13 +121,12 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
           data: { values: [{ x: mid, y: a.y, label: a.label }] },
           mark: {
             type: "text",
-            dy: 12,
-            fontSize: 12,
+            dy: -10,
             font,
-            fontStyle: "italic",
+            fontStyle: "normal",
             color,
             align: "center",
-            baseline: "top",
+            baseline: "bottom",
           },
           encoding: {
             x: { field: "x", type: "quantitative" },
@@ -181,9 +180,8 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
           mark: {
             type: "text",
             dx: 10,
-            fontSize: 12,
             font,
-            fontStyle: "italic",
+            fontStyle: "normal",
             color,
             align: "left",
             baseline: "middle",
diff --git a/core/src/theme.ts b/core/src/theme.ts
index 97da943..6d06ff2 100644
--- a/core/src/theme.ts
+++ b/core/src/theme.ts
@@ -86,14 +86,16 @@ export const MOLPLOT_DESIGN_WIDTH = 320;
 /**
  * Scale factor for screen / docs hosts.
  *
- * Paper preset is ~9–12 px at {@link MOLPLOT_DESIGN_WIDTH}. Docs want roughly
- * 1.5–1.8× as a floor so labels stay readable without eating the plot area
- * (multi-legend charts need room). Track width up to 2× on wide hosts.
+ * Paper preset is ~9–12 px at {@link MOLPLOT_DESIGN_WIDTH}. Docs use a **2×**
+ * floor (200% of paper) and track host width so labels/ticks grow on large
+ * pages (cap 3×). Fixed px in a fence `config` freeze type size — prefer
+ * leaving sizes to this scale.
  */
 export function fontScaleForWidth(width: number): number {
-  if (!Number.isFinite(width) || width <= 0) return 1.6;
+  if (!Number.isFinite(width) || width <= 0) return 2;
   const tracked = width / MOLPLOT_DESIGN_WIDTH;
-  return Math.min(2, Math.max(1.5, tracked));
+  // 2× paper at design width; scales with page width up to 3×.
+  return Math.min(3, Math.max(2, 2 * tracked));
 }
 
 /**
@@ -129,12 +131,14 @@ export function vegaConfig(
       titleFontSize: px(theme.fontSize.label),
       labelFont: theme.font.family,
       titleFont: theme.font.family,
-      titlePadding: Math.round(6 * scale),
-      labelPadding: Math.round(3 * scale),
+      titleFontStyle: "normal",
+      labelFontStyle: "normal",
+      titlePadding: Math.round(8 * scale),
+      labelPadding: Math.round(4 * scale),
       grid: true,
-      tickSize: Math.max(4, Math.round(3.5 * scale)),
-      labelLimit: Math.round(160 * scale),
-      titleLimit: Math.round(200 * scale),
+      tickSize: Math.max(5, Math.round(4 * scale)),
+      labelLimit: Math.round(220 * scale),
+      titleLimit: Math.round(280 * scale),
       labelOverlap: true,
       labelFlush: true,
     },
@@ -159,6 +163,13 @@ export function vegaConfig(
       fontSize: px(theme.fontSize.title),
       font: theme.font.family,
       fontWeight: 600,
+      fontStyle: "normal",
+    },
+    text: {
+      font: theme.font.family,
+      fontSize: px(theme.fontSize.label),
+      color: theme.font.color,
+      fontStyle: "normal",
     },
     view: {
       stroke: null,
diff --git a/core/tests/preset.test.ts b/core/tests/preset.test.ts
index 3a461d5..db7863a 100644
--- a/core/tests/preset.test.ts
+++ b/core/tests/preset.test.ts
@@ -63,14 +63,15 @@ describe("vegaConfig", () => {
 });
 
 describe("fontScaleForWidth", () => {
-  it("is 1 at the paper design width and grows for wider hosts", async () => {
+  it("is 2× paper at design width and grows with host (cap 3×)", async () => {
     const { fontScaleForWidth, MOLPLOT_DESIGN_WIDTH } = await import(
       "../src/theme"
     );
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH)).toBe(1.5);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.2)).toBeCloseTo(1.5, 5);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.8)).toBeCloseTo(1.8, 5);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 3)).toBe(2);
-    expect(fontScaleForWidth(0)).toBe(1.6);
+    // 200% of paper at design width; tracks page size up to 3×.
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH)).toBe(2);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.2)).toBeCloseTo(2.4, 5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.8)).toBe(3);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 3)).toBe(3);
+    expect(fontScaleForWidth(0)).toBe(2);
   });
 });
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
index bd7918b..2907d00 100644
--- a/python/src/molplot/annotations.py
+++ b/python/src/molplot/annotations.py
@@ -109,13 +109,12 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                     "data": {"values": [{"x": mid, "y": y, "label": a["label"]}]},
                     "mark": {
                         "type": "text",
-                        "dy": 12,
-                        "fontSize": 12,
+                        "dy": -10,
                         "font": _SERIF,
-                        "fontStyle": "italic",
+                        "fontStyle": "normal",
                         "color": color,
                         "align": "center",
-                        "baseline": "top",
+                        "baseline": "bottom",
                     },
                     "encoding": {
                         "x": {"field": "x", "type": "quantitative"},
@@ -166,9 +165,8 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                     "mark": {
                         "type": "text",
                         "dx": 10,
-                        "fontSize": 12,
                         "font": _SERIF,
-                        "fontStyle": "italic",
+                        "fontStyle": "normal",
                         "color": color,
                         "align": "left",
                         "baseline": "middle",

From 3cd117ab40aae469425db61dd9c3f2b56aee3178 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 19:27:47 +0200
Subject: [PATCH 12/17] =?UTF-8?q?feat:=20along-curve=20scaleBar=20+=20larg?=
 =?UTF-8?q?er=20docs=20fontScale=20(3=E2=80=934.5=C3=97)?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

scaleBar orientation=along draws a chord with log-space perpendicular
caps (matplotlib-style). fontScaleForWidth floor 3× paper, cap 4.5×.
---
 core/src/annotations.ts           | 131 ++++++++++++++++++++++++++----
 core/src/theme.ts                 |  12 ++-
 core/tests/annotations.test.ts    |  20 +++++
 core/tests/preset.test.ts         |  13 ++-
 python/src/molplot/annotations.py |  85 ++++++++++++++++++-
 5 files changed, 227 insertions(+), 34 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 64d317c..54a9c92 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -12,30 +12,36 @@ import type { VegaLiteSpec } from "./specs";
 
 export type ScaleBarAnnotation = {
   kind: "scaleBar";
-  /** Data-coordinate start of the bar (x for horizontal, y for vertical). */
+  /** Start of the bar (data coords). */
   x: number;
   y: number;
-  /** Length in data units along the bar axis. */
-  length: number;
+  /**
+   * Length along a horizontal/vertical axis. Ignored when both
+   * {@link x2} and {@link y2} are set (matplotlib-style chord on a curve).
+   */
+  length?: number;
   label?: string;
   color?: string;
   strokeWidth?: number;
-  orientation?: "horizontal" | "vertical";
   /**
-   * End-cap half-length in data units on the perpendicular axis.
-   * Defaults to a small fraction of `length` (or absolute fallback).
-   * Prefer {@link tickRatio} on log scales.
+   * `horizontal` / `vertical` axis-aligned bars, or `along` for a free
+   * segment (x,y)→(x2,y2) with end-caps ⊥ in log–log space (default when
+   * both ends are given).
    */
+  orientation?: "horizontal" | "vertical" | "along";
+  /** Linear end-cap half-length (axis-aligned modes). */
   tick?: number;
-  /**
-   * Geometric end-cap half-span on log axes: cap runs from
-   * `y / tickRatio` to `y * tickRatio` (horizontal bar). Default none.
-   */
+  /** Geometric end-cap half-span on log axes (axis-aligned modes). */
   tickRatio?: number;
-  /** Absolute end (overrides `x + length` when set). */
+  /** End x (with y2: chord along curve). */
   x2?: number;
-  /** Absolute end for a vertical bar (overrides `y + length` when set). */
+  /** End y (with x2: chord along curve). */
   y2?: number;
+  /**
+   * Log-space half-length of end-caps for `along` chords (default 0.18).
+   * Caps are perpendicular to the segment in (ln x, ln y).
+   */
+  capLog?: number;
 };
 
 export type ArrowAnnotation = {
@@ -62,13 +68,102 @@ function cleanLayer(layer: Record<string, unknown>): VegaLiteSpec {
   return layer as VegaLiteSpec;
 }
 
+/** End-cap endpoints ⊥ to (x0,y0)→(x1,y1) in log–log space (matplotlib-like). */
+function logPerpCap(
+  x: number,
+  y: number,
+  x0: number,
+  y0: number,
+  x1: number,
+  y1: number,
+  s: number,
+): { x: number; y: number; x2: number; y2: number } {
+  const dx = Math.log(x1 / x0);
+  const dy = Math.log(y1 / y0);
+  const n = Math.hypot(dx, dy) || 1;
+  const px = (-dy / n) * s;
+  const py = (dx / n) * s;
+  return {
+    x: Math.exp(Math.log(x) + px),
+    y: Math.exp(Math.log(y) + py),
+    x2: Math.exp(Math.log(x) - px),
+    y2: Math.exp(Math.log(y) - py),
+  };
+}
+
 function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
   const color = a.color ?? "#14271d";
-  const sw = a.strokeWidth ?? 1.6;
-  const horizontal = (a.orientation ?? "horizontal") === "horizontal";
+  const sw = a.strokeWidth ?? 1.8;
   const font = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif";
   const layers: VegaLiteSpec[] = [];
 
+  // Matplotlib-style chord on a curve: both ends fully specified.
+  const along =
+    a.orientation === "along" ||
+    (a.x2 != null &&
+      a.y2 != null &&
+      a.orientation !== "horizontal" &&
+      a.orientation !== "vertical");
+
+  if (along && a.x2 != null && a.y2 != null) {
+    const x0 = a.x;
+    const y0 = a.y;
+    const x1 = a.x2;
+    const y1 = a.y2;
+    const midX = Math.exp(0.5 * (Math.log(x0) + Math.log(x1)));
+    const midY = Math.exp(0.5 * (Math.log(y0) + Math.log(y1)));
+    const s = a.capLog ?? 0.18;
+    const c0 = logPerpCap(x0, y0, x0, y0, x1, y1, s);
+    const c1 = logPerpCap(x1, y1, x0, y0, x1, y1, s);
+    layers.push(
+      cleanLayer({
+        data: { values: [{ x: x0, y: y0, x2: x1, y2: y1 }] },
+        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+          x2: { field: "x2" },
+          y2: { field: "y2" },
+        },
+      }),
+      cleanLayer({
+        data: { values: [c0, c1] },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", type: "quantitative" },
+          y: { field: "y", type: "quantitative" },
+          x2: { field: "x2" },
+          y2: { field: "y2" },
+        },
+      }),
+    );
+    if (a.label) {
+      layers.push(
+        cleanLayer({
+          data: {
+            values: [{ x: midX, y: midY * 1.55, label: a.label }],
+          },
+          mark: {
+            type: "text",
+            font,
+            fontStyle: "normal",
+            color,
+            align: "center",
+            baseline: "bottom",
+          },
+          encoding: {
+            x: { field: "x", type: "quantitative" },
+            y: { field: "y", type: "quantitative" },
+            text: { field: "label", type: "nominal" },
+          },
+        }),
+      );
+    }
+    return layers;
+  }
+
+  const horizontal = (a.orientation ?? "horizontal") === "horizontal";
+
   if (horizontal) {
     const x0 = a.x;
     const x1 =
@@ -80,7 +175,7 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
         : a.y -
           (a.tick ??
             (Number.isFinite(a.length) && a.length
-              ? Math.abs(a.length) * 0.08
+              ? Math.abs(a.length as number) * 0.08
               : 0.05));
     const yHi =
       a.tickRatio != null
@@ -88,7 +183,7 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
         : a.y +
           (a.tick ??
             (Number.isFinite(a.length) && a.length
-              ? Math.abs(a.length) * 0.08
+              ? Math.abs(a.length as number) * 0.08
               : 0.05));
     layers.push(
       cleanLayer({
@@ -144,7 +239,7 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
     const tick =
       a.tick ??
       (Number.isFinite(a.length) && a.length
-        ? Math.abs(a.length) * 0.08
+        ? Math.abs(a.length as number) * 0.08
         : 0.05);
     const xLo = a.tickRatio != null ? a.x / a.tickRatio : a.x - tick;
     const xHi = a.tickRatio != null ? a.x * a.tickRatio : a.x + tick;
diff --git a/core/src/theme.ts b/core/src/theme.ts
index 6d06ff2..4e836e8 100644
--- a/core/src/theme.ts
+++ b/core/src/theme.ts
@@ -86,16 +86,14 @@ export const MOLPLOT_DESIGN_WIDTH = 320;
 /**
  * Scale factor for screen / docs hosts.
  *
- * Paper preset is ~9–12 px at {@link MOLPLOT_DESIGN_WIDTH}. Docs use a **2×**
- * floor (200% of paper) and track host width so labels/ticks grow on large
- * pages (cap 3×). Fixed px in a fence `config` freeze type size — prefer
- * leaving sizes to this scale.
+ * Paper is ~9–12 px at {@link MOLPLOT_DESIGN_WIDTH}. Docs need much larger
+ * type (axis title / tick / annotation) — floor **3×** paper at design width,
+ * track host width up to **4.5×**. Fixed `fontSize` in a fence freezes size.
  */
 export function fontScaleForWidth(width: number): number {
-  if (!Number.isFinite(width) || width <= 0) return 2;
+  if (!Number.isFinite(width) || width <= 0) return 3;
   const tracked = width / MOLPLOT_DESIGN_WIDTH;
-  // 2× paper at design width; scales with page width up to 3×.
-  return Math.min(3, Math.max(2, 2 * tracked));
+  return Math.min(4.5, Math.max(3, 3 * tracked));
 }
 
 /**
diff --git a/core/tests/annotations.test.ts b/core/tests/annotations.test.ts
index c34abd7..57434fd 100644
--- a/core/tests/annotations.test.ts
+++ b/core/tests/annotations.test.ts
@@ -23,6 +23,26 @@ describe("annotations", () => {
     expect((layers[2].mark as { type: string }).type).toBe("text");
   });
 
+  it("builds an along-curve chord with log-perp end-caps", () => {
+    const layers = annotationLayers([
+      {
+        kind: "scaleBar",
+        orientation: "along",
+        x: 0.18,
+        y: 0.0324,
+        x2: 0.65,
+        y2: 0.4225,
+        label: "ballistic",
+      },
+    ]);
+    expect(layers.length).toBe(3);
+    const bar = layers[0].data as { values: { x2: number; y2: number }[] };
+    expect(bar.values[0].x2).toBeCloseTo(0.65);
+    expect(bar.values[0].y2).toBeCloseTo(0.4225);
+    const caps = layers[1].data as { values: unknown[] };
+    expect(caps.values).toHaveLength(2);
+  });
+
   it("builds an arrow as rule + tip (+ optional label)", () => {
     const layers = annotationLayers([
       {
diff --git a/core/tests/preset.test.ts b/core/tests/preset.test.ts
index db7863a..9d5cfdb 100644
--- a/core/tests/preset.test.ts
+++ b/core/tests/preset.test.ts
@@ -63,15 +63,14 @@ describe("vegaConfig", () => {
 });
 
 describe("fontScaleForWidth", () => {
-  it("is 2× paper at design width and grows with host (cap 3×)", async () => {
+  it("is 3× paper at design width and grows with host (cap 4.5×)", async () => {
     const { fontScaleForWidth, MOLPLOT_DESIGN_WIDTH } = await import(
       "../src/theme"
     );
-    // 200% of paper at design width; tracks page size up to 3×.
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH)).toBe(2);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.2)).toBeCloseTo(2.4, 5);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.8)).toBe(3);
-    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 3)).toBe(3);
-    expect(fontScaleForWidth(0)).toBe(2);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH)).toBe(3);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.2)).toBeCloseTo(3.6, 5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 1.8)).toBe(4.5);
+    expect(fontScaleForWidth(MOLPLOT_DESIGN_WIDTH * 3)).toBe(4.5);
+    expect(fontScaleForWidth(0)).toBe(3);
   });
 });
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
index 2907d00..1b15b9f 100644
--- a/python/src/molplot/annotations.py
+++ b/python/src/molplot/annotations.py
@@ -56,10 +56,33 @@ class ArrowAnnotation(TypedDict, total=False):
 _SERIF = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif"
 
 
+def _log_perp_cap(
+    x: float, y: float, x0: float, y0: float, x1: float, y1: float, s: float
+) -> dict[str, float]:
+    import math
+
+    dx = math.log(x1 / x0)
+    dy = math.log(y1 / y0)
+    n = math.hypot(dx, dy) or 1.0
+    px, py = (-dy / n) * s, (dx / n) * s
+    return {
+        "x": math.exp(math.log(x) + px),
+        "y": math.exp(math.log(y) + py),
+        "x2": math.exp(math.log(x) - px),
+        "y2": math.exp(math.log(y) - py),
+    }
+
+
 def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
+    import math
+
     color = a.get("color") or "#14271d"
-    sw = a.get("strokeWidth") or 1.6
-    horizontal = (a.get("orientation") or "horizontal") == "horizontal"
+    sw = a.get("strokeWidth") or 1.8
+    orient = a.get("orientation") or "horizontal"
+    x2, y2 = a.get("x2"), a.get("y2")
+    along = orient == "along" or (
+        x2 is not None and y2 is not None and orient not in ("horizontal", "vertical")
+    )
     length = float(a["length"]) if a.get("length") is not None else 0.0
     tick = a.get("tick")
     if tick is None:
@@ -68,6 +91,64 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     x, y = float(a["x"]), float(a["y"])
     layers: list[dict[str, Any]] = []
 
+    if along and x2 is not None and y2 is not None:
+        x0, y0, x1, y1 = x, y, float(x2), float(y2)
+        mid_x = math.exp(0.5 * (math.log(x0) + math.log(x1)))
+        mid_y = math.exp(0.5 * (math.log(y0) + math.log(y1)))
+        s = float(a.get("capLog") or 0.18)
+        layers.append(
+            {
+                "data": {"values": [{"x": x0, "y": y0, "x2": x1, "y2": y1}]},
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "y": {"field": "y", "type": "quantitative"},
+                    "x2": {"field": "x2"},
+                    "y2": {"field": "y2"},
+                },
+            }
+        )
+        layers.append(
+            {
+                "data": {
+                    "values": [
+                        _log_perp_cap(x0, y0, x0, y0, x1, y1, s),
+                        _log_perp_cap(x1, y1, x0, y0, x1, y1, s),
+                    ]
+                },
+                "mark": {"type": "rule", "strokeWidth": sw, "color": color},
+                "encoding": {
+                    "x": {"field": "x", "type": "quantitative"},
+                    "y": {"field": "y", "type": "quantitative"},
+                    "x2": {"field": "x2"},
+                    "y2": {"field": "y2"},
+                },
+            }
+        )
+        if a.get("label"):
+            layers.append(
+                {
+                    "data": {
+                        "values": [{"x": mid_x, "y": mid_y * 1.55, "label": a["label"]}]
+                    },
+                    "mark": {
+                        "type": "text",
+                        "font": _SERIF,
+                        "fontStyle": "normal",
+                        "color": color,
+                        "align": "center",
+                        "baseline": "bottom",
+                    },
+                    "encoding": {
+                        "x": {"field": "x", "type": "quantitative"},
+                        "y": {"field": "y", "type": "quantitative"},
+                        "text": {"field": "label", "type": "nominal"},
+                    },
+                }
+            )
+        return layers
+
+    horizontal = orient == "horizontal"
     if horizontal:
         x0 = x
         x1 = float(a["x2"]) if a.get("x2") is not None else x + length

From 1c9d39dd55c53dd8cb59fa6d35d152faddad90e7 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 19:33:46 +0200
Subject: [PATCH 13/17] fix(annotations): offsetLog for along-curve scale bars
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Translate the bar along the log-space path normal (default 0.42) so it
does not overlap the curve; end-caps remain ⊥ to the bar.
---
 core/src/annotations.ts           | 66 ++++++++++++++++++++++++-------
 core/tests/annotations.test.ts    | 12 ++++--
 python/src/molplot/annotations.py | 37 ++++++++++++-----
 3 files changed, 86 insertions(+), 29 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 54a9c92..f4ba4f4 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -38,10 +38,16 @@ export type ScaleBarAnnotation = {
   /** End y (with x2: chord along curve). */
   y2?: number;
   /**
-   * Log-space half-length of end-caps for `along` chords (default 0.18).
-   * Caps are perpendicular to the segment in (ln x, ln y).
+   * Log-space half-length of end-caps for `along` chords (default 0.16).
+   * Caps are perpendicular to the bar in (ln x, ln y).
    */
   capLog?: number;
+  /**
+   * Log-space offset of an `along` bar from the chord (x,y)→(x2,y2),
+   * along the path normal so the bar does not sit on the curve (default 0.42).
+   * Set 0 to draw on the chord itself.
+   */
+  offsetLog?: number;
 };
 
 export type ArrowAnnotation = {
@@ -106,15 +112,47 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
       a.orientation !== "vertical");
 
   if (along && a.x2 != null && a.y2 != null) {
-    const x0 = a.x;
-    const y0 = a.y;
-    const x1 = a.x2;
-    const y1 = a.y2;
-    const midX = Math.exp(0.5 * (Math.log(x0) + Math.log(x1)));
-    const midY = Math.exp(0.5 * (Math.log(y0) + Math.log(y1)));
-    const s = a.capLog ?? 0.18;
-    const c0 = logPerpCap(x0, y0, x0, y0, x1, y1, s);
-    const c1 = logPerpCap(x1, y1, x0, y0, x1, y1, s);
+    // Chord on the curve (reference), then translate along the log-normal so
+    // the visible bar is parallel and does not overlap the path.
+    const rx0 = a.x;
+    const ry0 = a.y;
+    const rx1 = a.x2;
+    const ry1 = a.y2;
+    const dx = Math.log(rx1 / rx0);
+    const dy = Math.log(ry1 / ry0);
+    const n = Math.hypot(dx, dy) || 1;
+    const ux = dx / n;
+    const uy = dy / n;
+    // Prefer the normal that raises mid-y (above the curve on log–log plots).
+    let side = 1;
+    {
+      const midYPlus = Math.exp(
+        0.5 * (Math.log(ry0) + Math.log(ry1)) + ux * 0.1,
+      );
+      const midYMinus = Math.exp(
+        0.5 * (Math.log(ry0) + Math.log(ry1)) - ux * 0.1,
+      );
+      // offset uses perp (-uy, ux); mid log-y shift is ±ux * s
+      if (midYMinus > midYPlus) side = -1;
+    }
+    const sOff = a.offsetLog ?? 0.42;
+    const ox = -uy * sOff * side;
+    const oy = ux * sOff * side;
+    const x0 = Math.exp(Math.log(rx0) + ox);
+    const y0 = Math.exp(Math.log(ry0) + oy);
+    const x1 = Math.exp(Math.log(rx1) + ox);
+    const y1 = Math.exp(Math.log(ry1) + oy);
+    const sCap = a.capLog ?? 0.16;
+    const c0 = logPerpCap(x0, y0, x0, y0, x1, y1, sCap);
+    const c1 = logPerpCap(x1, y1, x0, y0, x1, y1, sCap);
+    // Label further out along the same normal.
+    const sLab = sOff + 0.32;
+    const lx = Math.exp(
+      0.5 * (Math.log(rx0) + Math.log(rx1)) + -uy * sLab * side,
+    );
+    const ly = Math.exp(
+      0.5 * (Math.log(ry0) + Math.log(ry1)) + ux * sLab * side,
+    );
     layers.push(
       cleanLayer({
         data: { values: [{ x: x0, y: y0, x2: x1, y2: y1 }] },
@@ -140,16 +178,14 @@ function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
     if (a.label) {
       layers.push(
         cleanLayer({
-          data: {
-            values: [{ x: midX, y: midY * 1.55, label: a.label }],
-          },
+          data: { values: [{ x: lx, y: ly, label: a.label }] },
           mark: {
             type: "text",
             font,
             fontStyle: "normal",
             color,
             align: "center",
-            baseline: "bottom",
+            baseline: "middle",
           },
           encoding: {
             x: { field: "x", type: "quantitative" },
diff --git a/core/tests/annotations.test.ts b/core/tests/annotations.test.ts
index 57434fd..4890d96 100644
--- a/core/tests/annotations.test.ts
+++ b/core/tests/annotations.test.ts
@@ -23,7 +23,7 @@ describe("annotations", () => {
     expect((layers[2].mark as { type: string }).type).toBe("text");
   });
 
-  it("builds an along-curve chord with log-perp end-caps", () => {
+  it("offsets along-curve bars off the path with log-perp end-caps", () => {
     const layers = annotationLayers([
       {
         kind: "scaleBar",
@@ -32,13 +32,17 @@ describe("annotations", () => {
         y: 0.0324,
         x2: 0.65,
         y2: 0.4225,
+        offsetLog: 0.42,
         label: "ballistic",
       },
     ]);
     expect(layers.length).toBe(3);
-    const bar = layers[0].data as { values: { x2: number; y2: number }[] };
-    expect(bar.values[0].x2).toBeCloseTo(0.65);
-    expect(bar.values[0].y2).toBeCloseTo(0.4225);
+    const bar = layers[0].data as {
+      values: { x: number; y: number; x2: number; y2: number }[];
+    };
+    // Bar is translated off the chord — not the raw endpoints.
+    expect(bar.values[0].x).not.toBeCloseTo(0.18, 2);
+    expect(bar.values[0].y).not.toBeCloseTo(0.0324, 2);
     const caps = layers[1].data as { values: unknown[] };
     expect(caps.values).toHaveLength(2);
   });
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
index 1b15b9f..ec2cb56 100644
--- a/python/src/molplot/annotations.py
+++ b/python/src/molplot/annotations.py
@@ -92,10 +92,26 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     layers: list[dict[str, Any]] = []
 
     if along and x2 is not None and y2 is not None:
-        x0, y0, x1, y1 = x, y, float(x2), float(y2)
-        mid_x = math.exp(0.5 * (math.log(x0) + math.log(x1)))
-        mid_y = math.exp(0.5 * (math.log(y0) + math.log(y1)))
-        s = float(a.get("capLog") or 0.18)
+        # Reference chord on the curve → translate along log-normal (offset)
+        # so the bar is parallel and does not overlap the path.
+        rx0, ry0, rx1, ry1 = x, y, float(x2), float(y2)
+        dx = math.log(rx1 / rx0)
+        dy = math.log(ry1 / ry0)
+        n = math.hypot(dx, dy) or 1.0
+        ux, uy = dx / n, dy / n
+        side = 1
+        # Prefer the normal that raises mid-y on log–log plots.
+        if math.exp(0.5 * (math.log(ry0) + math.log(ry1)) - ux * 0.1) > math.exp(
+            0.5 * (math.log(ry0) + math.log(ry1)) + ux * 0.1
+        ):
+            side = -1
+        s_off = float(a.get("offsetLog") if a.get("offsetLog") is not None else 0.42)
+        ox, oy = -uy * s_off * side, ux * s_off * side
+        x0 = math.exp(math.log(rx0) + ox)
+        y0 = math.exp(math.log(ry0) + oy)
+        x1 = math.exp(math.log(rx1) + ox)
+        y1 = math.exp(math.log(ry1) + oy)
+        s_cap = float(a.get("capLog") or 0.16)
         layers.append(
             {
                 "data": {"values": [{"x": x0, "y": y0, "x2": x1, "y2": y1}]},
@@ -112,8 +128,8 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
             {
                 "data": {
                     "values": [
-                        _log_perp_cap(x0, y0, x0, y0, x1, y1, s),
-                        _log_perp_cap(x1, y1, x0, y0, x1, y1, s),
+                        _log_perp_cap(x0, y0, x0, y0, x1, y1, s_cap),
+                        _log_perp_cap(x1, y1, x0, y0, x1, y1, s_cap),
                     ]
                 },
                 "mark": {"type": "rule", "strokeWidth": sw, "color": color},
@@ -126,18 +142,19 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
             }
         )
         if a.get("label"):
+            s_lab = s_off + 0.32
+            lx = math.exp(0.5 * (math.log(rx0) + math.log(rx1)) + -uy * s_lab * side)
+            ly = math.exp(0.5 * (math.log(ry0) + math.log(ry1)) + ux * s_lab * side)
             layers.append(
                 {
-                    "data": {
-                        "values": [{"x": mid_x, "y": mid_y * 1.55, "label": a["label"]}]
-                    },
+                    "data": {"values": [{"x": lx, "y": ly, "label": a["label"]}]},
                     "mark": {
                         "type": "text",
                         "font": _SERIF,
                         "fontStyle": "normal",
                         "color": color,
                         "align": "center",
-                        "baseline": "bottom",
+                        "baseline": "middle",
                     },
                     "encoding": {
                         "x": {"field": "x", "type": "quantitative"},

From 601a3fa2a8a4361bd65e5858f191f7c836150b5f Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 19:49:46 +0200
Subject: [PATCH 14/17] feat(annotations): scale_bar/arrow factories
 (matplotlib |-| model)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

One scale_bar() owns spine + both end-caps + label — never hand-draw
caps. Mirrors FancyArrowPatch(arrowstyle='|-|') / AnchoredSizeBar.
---
 core/src/annotations.ts           |  38 +++-
 core/src/index.ts                 |   2 +
 python/src/molplot/__init__.py    |   6 +-
 python/src/molplot/annotations.py | 294 ++++++++++++++++++++++--------
 4 files changed, 262 insertions(+), 78 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index f4ba4f4..0a6e145 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -1,15 +1,45 @@
 import type { VegaLiteSpec } from "./specs";
 
 /**
- * Chart annotations — portable Vega-Lite layers for paper/web.
+ * Chart annotations — one object owns a complete artist (matplotlib model).
  *
- * - {@link ScaleBarAnnotation}: a `|———|` scale bar in data coordinates
- * - {@link ArrowAnnotation}: a directed arrow (rule + tip) with optional label
+ * - {@link scaleBar} / `kind: "scaleBar"` ≈ `FancyArrowPatch(arrowstyle='|-|')`
+ *   — spine + both end-caps + label. Never hand-draw caps as separate layers.
+ * - {@link arrow} / `kind: "arrow"` ≈ `annotate(..., arrowstyle='->')`.
  *
  * Pass via `withAnnotations(spec, …)` or a top-level `annotations` array on a
- * RawChart / fence spec (stripped before vega-embed).
+ * RawChart / fence spec (expanded to VL layers; stripped before vega-embed).
  */
 
+/** Factory: one complete `|———|` (spine + ⊥ caps + label). */
+export function scaleBar(
+  partial: Omit<ScaleBarAnnotation, "kind">,
+): ScaleBarAnnotation {
+  const hasEnds = partial.x2 != null && partial.y2 != null;
+  return {
+    color: "#18432b",
+    strokeWidth: 1.8,
+    orientation: hasEnds ? "along" : "horizontal",
+    offsetLog: hasEnds ? 0.42 : undefined,
+    capLog: hasEnds ? 0.16 : undefined,
+    ...partial,
+    kind: "scaleBar",
+  };
+}
+
+/** Factory: one complete arrow (shaft + tip + optional label). */
+export function arrow(
+  partial: Omit<ArrowAnnotation, "kind">,
+): ArrowAnnotation {
+  return {
+    color: "#18432b",
+    strokeWidth: 1.6,
+    tipSize: 55,
+    ...partial,
+    kind: "arrow",
+  };
+}
+
 export type ScaleBarAnnotation = {
   kind: "scaleBar";
   /** Start of the bar (data coords). */
diff --git a/core/src/index.ts b/core/src/index.ts
index 24ae57c..ee75dc2 100644
--- a/core/src/index.ts
+++ b/core/src/index.ts
@@ -8,6 +8,8 @@ export type {
 } from "./annotations";
 export {
   annotationLayers,
+  arrow,
+  scaleBar,
   takeAnnotations,
   withAnnotations,
 } from "./annotations";
diff --git a/python/src/molplot/__init__.py b/python/src/molplot/__init__.py
index 735f2e5..50f1755 100644
--- a/python/src/molplot/__init__.py
+++ b/python/src/molplot/__init__.py
@@ -23,6 +23,8 @@
 
 from .annotations import (
     annotation_layers,
+    arrow,
+    scale_bar,
     take_annotations,
     with_annotations,
 )
@@ -68,7 +70,9 @@
     "gantt_spec",
     "vega_config",
     "VL_SCHEMA",
-    # annotations
+    # annotations (matplotlib-style: one call = full artist)
+    "scale_bar",
+    "arrow",
     "annotation_layers",
     "with_annotations",
     "take_annotations",
diff --git a/python/src/molplot/annotations.py b/python/src/molplot/annotations.py
index ec2cb56..f972b7a 100644
--- a/python/src/molplot/annotations.py
+++ b/python/src/molplot/annotations.py
@@ -1,11 +1,15 @@
-"""Chart annotations — portable Vega-Lite layers (mirrors core/src/annotations.ts).
+"""Chart annotations — one call draws a complete artist (mirrors TS).
 
-Kinds:
-  * ``scaleBar`` — a ``|———|`` bar in data coordinates
-  * ``arrow``    — directed arrow (rule + tip) with optional label
+Design follows matplotlib:
 
-Use :func:`with_annotations` on any unit/layered VL dict, or put an
-``annotations`` list on a fence / RawChart payload (stripped before render).
+* ``scale_bar(...)`` ≈ ``FancyArrowPatch(..., arrowstyle='|-|')`` plus a
+  label — **one** object owns the spine, both end-caps, and the text.
+  Callers never draw caps by hand.
+* ``arrow(...)`` ≈ ``ax.annotate(..., arrowprops=dict(arrowstyle='->'))``.
+
+Expand with :func:`with_annotations` / a top-level ``annotations`` list on a
+Vega-Lite fence or :class:`RawChart` payload. The expansion always emits
+bar + caps + label as a single unit.
 """
 
 from __future__ import annotations
@@ -17,6 +21,8 @@
     "ScaleBarAnnotation",
     "ArrowAnnotation",
     "Annotation",
+    "scale_bar",
+    "arrow",
     "annotation_layers",
     "with_annotations",
     "take_annotations",
@@ -24,6 +30,8 @@
 
 
 class ScaleBarAnnotation(TypedDict, total=False):
+    """One complete ``|———|`` (spine + ⊥ caps + optional label)."""
+
     kind: Literal["scaleBar"]
     x: float
     y: float
@@ -33,9 +41,11 @@ class ScaleBarAnnotation(TypedDict, total=False):
     label: str
     color: str
     strokeWidth: float
-    orientation: Literal["horizontal", "vertical"]
+    orientation: Literal["horizontal", "vertical", "along"]
     tick: float
     tickRatio: float
+    capLog: float
+    offsetLog: float
 
 
 class ArrowAnnotation(TypedDict, total=False):
@@ -52,15 +62,121 @@ class ArrowAnnotation(TypedDict, total=False):
 
 Annotation = ScaleBarAnnotation | ArrowAnnotation
 
-
 _SERIF = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif"
 
 
+def scale_bar(
+    x: float,
+    y: float,
+    *,
+    x2: float | None = None,
+    y2: float | None = None,
+    length: float | None = None,
+    label: str | None = None,
+    orientation: Literal["horizontal", "vertical", "along"] | None = None,
+    offset: float = 0.42,
+    capsize: float = 0.16,
+    color: str = "#18432b",
+    linewidth: float = 1.8,
+    tick: float | None = None,
+    tick_ratio: float | None = None,
+) -> ScaleBarAnnotation:
+    """Build one complete ``|———|`` annotation (matplotlib ``arrowstyle='|-|'``).
+
+    Parameters
+    ----------
+    x, y
+        Start in data coordinates. For ``orientation='along'`` this is a point
+        **on the curve** (reference chord start).
+    x2, y2
+        End of the chord (required for ``along``; optional for axis-aligned
+        when ``length`` is given).
+    length
+        Axis-aligned length when ``x2``/``y2`` are omitted.
+    label
+        Text drawn with the bar (Times roman). Owned by this artist — do not
+        add a separate text layer.
+    orientation
+        ``'along'`` — chord parallel to ``(x,y)→(x2,y2)``, offset off the
+        path by ``offset`` in log–log space, end-caps ⊥ bar (default when
+        both ends are given).
+        ``'horizontal'`` / ``'vertical'`` — axis-aligned size bar.
+    offset
+        Log-space normal offset from the reference chord (``along`` only).
+        Default ``0.42`` so the bar does not sit on the curve. ``0`` = on chord.
+    capsize
+        Log-space half-length of each end-cap (``along``). Default ``0.16``.
+    color, linewidth
+        Stroke style for spine and caps together.
+
+    Returns
+    -------
+    ScaleBarAnnotation
+        Pass inside ``annotations=[...]`` or to :func:`with_annotations`.
+        Expansion yields spine + both caps + label — never hand-draw caps.
+    """
+    if orientation is None:
+        orientation = (
+            "along"
+            if x2 is not None and y2 is not None
+            else "horizontal"
+        )
+    out: ScaleBarAnnotation = {
+        "kind": "scaleBar",
+        "x": float(x),
+        "y": float(y),
+        "color": color,
+        "strokeWidth": float(linewidth),
+        "orientation": orientation,
+    }
+    if x2 is not None:
+        out["x2"] = float(x2)
+    if y2 is not None:
+        out["y2"] = float(y2)
+    if length is not None:
+        out["length"] = float(length)
+    if label is not None:
+        out["label"] = label
+    if orientation == "along":
+        out["offsetLog"] = float(offset)
+        out["capLog"] = float(capsize)
+    if tick is not None:
+        out["tick"] = float(tick)
+    if tick_ratio is not None:
+        out["tickRatio"] = float(tick_ratio)
+    return out
+
+
+def arrow(
+    x: float,
+    y: float,
+    x2: float,
+    y2: float,
+    *,
+    label: str | None = None,
+    color: str = "#18432b",
+    linewidth: float = 1.6,
+    tip_size: float = 55,
+) -> ArrowAnnotation:
+    """Build one complete arrow (matplotlib ``arrowstyle='->'``)."""
+    out: ArrowAnnotation = {
+        "kind": "arrow",
+        "x": float(x),
+        "y": float(y),
+        "x2": float(x2),
+        "y2": float(y2),
+        "color": color,
+        "strokeWidth": float(linewidth),
+        "tipSize": float(tip_size),
+    }
+    if label is not None:
+        out["label"] = label
+    return out
+
+
 def _log_perp_cap(
     x: float, y: float, x0: float, y0: float, x1: float, y1: float, s: float
 ) -> dict[str, float]:
-    import math
-
     dx = math.log(x1 / x0)
     dy = math.log(y1 / y0)
     n = math.hypot(dx, dy) or 1.0
@@ -74,9 +190,8 @@ def _log_perp_cap(
 
 
 def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
-    import math
-
-    color = a.get("color") or "#14271d"
+    """Expand **one** scaleBar into spine + caps + label (internal)."""
+    color = a.get("color") or "#18432b"
     sw = a.get("strokeWidth") or 1.8
     orient = a.get("orientation") or "horizontal"
     x2, y2 = a.get("x2"), a.get("y2")
@@ -92,30 +207,33 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     layers: list[dict[str, Any]] = []
 
     if along and x2 is not None and y2 is not None:
-        # Reference chord on the curve → translate along log-normal (offset)
-        # so the bar is parallel and does not overlap the path.
         rx0, ry0, rx1, ry1 = x, y, float(x2), float(y2)
         dx = math.log(rx1 / rx0)
         dy = math.log(ry1 / ry0)
         n = math.hypot(dx, dy) or 1.0
         ux, uy = dx / n, dy / n
         side = 1
-        # Prefer the normal that raises mid-y on log–log plots.
         if math.exp(0.5 * (math.log(ry0) + math.log(ry1)) - ux * 0.1) > math.exp(
             0.5 * (math.log(ry0) + math.log(ry1)) + ux * 0.1
         ):
             side = -1
-        s_off = float(a.get("offsetLog") if a.get("offsetLog") is not None else 0.42)
+        s_off = float(a["offsetLog"]) if a.get("offsetLog") is not None else 0.42
         ox, oy = -uy * s_off * side, ux * s_off * side
         x0 = math.exp(math.log(rx0) + ox)
         y0 = math.exp(math.log(ry0) + oy)
         x1 = math.exp(math.log(rx1) + ox)
         y1 = math.exp(math.log(ry1) + oy)
-        s_cap = float(a.get("capLog") or 0.16)
+        s_cap = float(a["capLog"]) if a.get("capLog") is not None else 0.16
+        # spine
         layers.append(
             {
                 "data": {"values": [{"x": x0, "y": y0, "x2": x1, "y2": y1}]},
-                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
+                "mark": {
+                    "type": "rule",
+                    "strokeWidth": sw,
+                    "color": color,
+                    "strokeCap": "butt",
+                },
                 "encoding": {
                     "x": {"field": "x", "type": "quantitative"},
                     "y": {"field": "y", "type": "quantitative"},
@@ -124,6 +242,7 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                 },
             }
         )
+        # both end-caps (owned by this scale_bar — not a separate API call)
         layers.append(
             {
                 "data": {
@@ -143,8 +262,12 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
         )
         if a.get("label"):
             s_lab = s_off + 0.32
-            lx = math.exp(0.5 * (math.log(rx0) + math.log(rx1)) + -uy * s_lab * side)
-            ly = math.exp(0.5 * (math.log(ry0) + math.log(ry1)) + ux * s_lab * side)
+            lx = math.exp(
+                0.5 * (math.log(rx0) + math.log(rx1)) + -uy * s_lab * side
+            )
+            ly = math.exp(
+                0.5 * (math.log(ry0) + math.log(ry1)) + ux * s_lab * side
+            )
             layers.append(
                 {
                     "data": {"values": [{"x": lx, "y": ly, "label": a["label"]}]},
@@ -168,7 +291,7 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     horizontal = orient == "horizontal"
     if horizontal:
         x0 = x
-        x1 = float(a["x2"]) if a.get("x2") is not None else x + length
+        x1 = float(x2) if x2 is not None else x + length
         mid = (x0 + x1) / 2
         if tick_ratio is not None:
             y_lo, y_hi = y / float(tick_ratio), y * float(tick_ratio)
@@ -177,7 +300,12 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
         layers.append(
             {
                 "data": {"values": [{"x": x0, "x2": x1, "y": y}]},
-                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
+                "mark": {
+                    "type": "rule",
+                    "strokeWidth": sw,
+                    "color": color,
+                    "strokeCap": "butt",
+                },
                 "encoding": {
                     "x": {"field": "x", "type": "quantitative"},
                     "x2": {"field": "x2"},
@@ -221,66 +349,73 @@ def _scale_bar_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
                     },
                 }
             )
+        return layers
+
+    # vertical
+    y0 = y
+    y1 = float(y2) if y2 is not None else y + length
+    mid = (y0 + y1) / 2
+    if tick_ratio is not None:
+        x_lo, x_hi = x / float(tick_ratio), x * float(tick_ratio)
     else:
-        y0 = y
-        y1 = float(a["y2"]) if a.get("y2") is not None else y + length
-        mid = (y0 + y1) / 2
-        if tick_ratio is not None:
-            x_lo, x_hi = x / float(tick_ratio), x * float(tick_ratio)
-        else:
-            x_lo, x_hi = x - tick, x + tick
-        layers.append(
-            {
-                "data": {"values": [{"x": x, "y": y0, "y2": y1}]},
-                "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "butt"},
-                "encoding": {
-                    "x": {"field": "x", "type": "quantitative"},
-                    "y": {"field": "y", "type": "quantitative"},
-                    "y2": {"field": "y2"},
-                },
-            }
-        )
+        x_lo, x_hi = x - tick, x + tick
+    layers.append(
+        {
+            "data": {"values": [{"x": x, "y": y0, "y2": y1}]},
+            "mark": {
+                "type": "rule",
+                "strokeWidth": sw,
+                "color": color,
+                "strokeCap": "butt",
+            },
+            "encoding": {
+                "x": {"field": "x", "type": "quantitative"},
+                "y": {"field": "y", "type": "quantitative"},
+                "y2": {"field": "y2"},
+            },
+        }
+    )
+    layers.append(
+        {
+            "data": {
+                "values": [
+                    {"x": x_lo, "x2": x_hi, "y": y0},
+                    {"x": x_lo, "x2": x_hi, "y": y1},
+                ]
+            },
+            "mark": {"type": "rule", "strokeWidth": sw, "color": color},
+            "encoding": {
+                "x": {"field": "x", "type": "quantitative"},
+                "x2": {"field": "x2"},
+                "y": {"field": "y", "type": "quantitative"},
+            },
+        }
+    )
+    if a.get("label"):
         layers.append(
             {
-                "data": {
-                    "values": [
-                        {"x": x_lo, "x2": x_hi, "y": y0},
-                        {"x": x_lo, "x2": x_hi, "y": y1},
-                    ]
+                "data": {"values": [{"x": x, "y": mid, "label": a["label"]}]},
+                "mark": {
+                    "type": "text",
+                    "dx": 10,
+                    "font": _SERIF,
+                    "fontStyle": "normal",
+                    "color": color,
+                    "align": "left",
+                    "baseline": "middle",
                 },
-                "mark": {"type": "rule", "strokeWidth": sw, "color": color},
                 "encoding": {
                     "x": {"field": "x", "type": "quantitative"},
-                    "x2": {"field": "x2"},
                     "y": {"field": "y", "type": "quantitative"},
+                    "text": {"field": "label", "type": "nominal"},
                 },
             }
         )
-        if a.get("label"):
-            layers.append(
-                {
-                    "data": {"values": [{"x": x, "y": mid, "label": a["label"]}]},
-                    "mark": {
-                        "type": "text",
-                        "dx": 10,
-                        "font": _SERIF,
-                        "fontStyle": "normal",
-                        "color": color,
-                        "align": "left",
-                        "baseline": "middle",
-                    },
-                    "encoding": {
-                        "x": {"field": "x", "type": "quantitative"},
-                        "y": {"field": "y", "type": "quantitative"},
-                        "text": {"field": "label", "type": "nominal"},
-                    },
-                }
-            )
     return layers
 
 
 def _arrow_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
-    color = a.get("color") or "#14271d"
+    color = a.get("color") or "#18432b"
     sw = a.get("strokeWidth") or 1.6
     tip_size = a.get("tipSize") or 55
     x, y = float(a["x"]), float(a["y"])
@@ -289,7 +424,12 @@ def _arrow_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
     layers: list[dict[str, Any]] = [
         {
             "data": {"values": [{"x": x, "y": y, "x2": x2, "y2": y2}]},
-            "mark": {"type": "rule", "strokeWidth": sw, "color": color, "strokeCap": "round"},
+            "mark": {
+                "type": "rule",
+                "strokeWidth": sw,
+                "color": color,
+                "strokeCap": "round",
+            },
             "encoding": {
                 "x": {"field": "x", "type": "quantitative"},
                 "y": {"field": "y", "type": "quantitative"},
@@ -318,13 +458,18 @@ def _arrow_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
             {
                 "data": {
                     "values": [
-                        {"x": (x + x2) / 2, "y": (y + y2) / 2, "label": a["label"]}
+                        {
+                            "x": (x + x2) / 2,
+                            "y": (y + y2) / 2,
+                            "label": a["label"],
+                        }
                     ]
                 },
                 "mark": {
                     "type": "text",
                     "dy": -8,
-                    "fontSize": 11,
+                    "font": _SERIF,
+                    "fontStyle": "normal",
                     "color": color,
                     "align": "center",
                     "baseline": "bottom",
@@ -340,6 +485,7 @@ def _arrow_layers(a: Mapping[str, Any]) -> list[dict[str, Any]]:
 
 
 def annotation_layers(annotations: Sequence[Mapping[str, Any]]) -> list[dict[str, Any]]:
+    """Expand each annotation into its full set of VL layers."""
     out: list[dict[str, Any]] = []
     for a in annotations:
         kind = a.get("kind")
@@ -373,7 +519,9 @@ def with_annotations(
     return {**spec, "layer": extra}
 
 
-def take_annotations(spec: dict[str, Any]) -> tuple[dict[str, Any], list[Annotation]]:
+def take_annotations(
+    spec: dict[str, Any],
+) -> tuple[dict[str, Any], list[Annotation]]:
     """Pull top-level ``annotations`` off a payload; return ``(spec, list)``."""
     raw = spec.get("annotations")
     if not isinstance(raw, list) or not raw:

From 2447675053bc15c1c77fd12f0e557c8d979cb51a Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 20:24:03 +0200
Subject: [PATCH 15/17] fix: restore pan/zoom on layered charts; runtime
 scaleBar overlay
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Zoom params bind at top-level when encoding is shared (docs layered
specs); layer0-only placement left bind:scales inert. Scale bars/arrows
are drawn as a screen-space SVG overlay from Vega scales after layout
and on pan/zoom — not pre-baked VL geometry.
---
 core/src/annotations.ts                | 715 ++++++++++---------------
 core/src/chart_base.ts                 |  13 +-
 core/src/index.ts                      |   3 +-
 core/src/raw_chart.interactive.test.ts |  84 ++-
 core/src/raw_chart.ts                  | 137 +++--
 core/tests/annotations.test.ts         |  93 +---
 6 files changed, 456 insertions(+), 589 deletions(-)

diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 0a6e145..3c39fb5 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -1,509 +1,340 @@
-import type { VegaLiteSpec } from "./specs";
-
 /**
- * Chart annotations — one object owns a complete artist (matplotlib model).
+ * Chart annotations — matplotlib-style artists drawn in **screen space**.
+ *
+ * Vega-Lite has no `annotate` / `arrowstyle='|-|'`. Geometry that must stay
+ * visually perpendicular (log axes, non-square panels) is computed at render
+ * time from Vega's scale functions, not pre-baked into VL layers.
  *
- * - {@link scaleBar} / `kind: "scaleBar"` ≈ `FancyArrowPatch(arrowstyle='|-|')`
- *   — spine + both end-caps + label. Never hand-draw caps as separate layers.
- * - {@link arrow} / `kind: "arrow"` ≈ `annotate(..., arrowstyle='->')`.
+ * - {@link scaleBar}: complete `|———|` (spine + both caps + label)
+ * - {@link arrow}: shaft + tip + optional label
  *
- * Pass via `withAnnotations(spec, …)` or a top-level `annotations` array on a
- * RawChart / fence spec (expanded to VL layers; stripped before vega-embed).
+ * Put an `annotations` array on the RawChart / fence payload. RawChart strips
+ * it before embed and paints an SVG overlay after layout / on pan-zoom.
  */
 
-/** Factory: one complete `|———|` (spine + ⊥ caps + label). */
-export function scaleBar(
-  partial: Omit<ScaleBarAnnotation, "kind">,
-): ScaleBarAnnotation {
-  const hasEnds = partial.x2 != null && partial.y2 != null;
-  return {
-    color: "#18432b",
-    strokeWidth: 1.8,
-    orientation: hasEnds ? "along" : "horizontal",
-    offsetLog: hasEnds ? 0.42 : undefined,
-    capLog: hasEnds ? 0.16 : undefined,
-    ...partial,
-    kind: "scaleBar",
-  };
-}
-
-/** Factory: one complete arrow (shaft + tip + optional label). */
-export function arrow(
-  partial: Omit<ArrowAnnotation, "kind">,
-): ArrowAnnotation {
-  return {
-    color: "#18432b",
-    strokeWidth: 1.6,
-    tipSize: 55,
-    ...partial,
-    kind: "arrow",
-  };
-}
-
 export type ScaleBarAnnotation = {
   kind: "scaleBar";
-  /** Start of the bar (data coords). */
+  /** Start in data coordinates (on the curve for `along`). */
   x: number;
   y: number;
-  /**
-   * Length along a horizontal/vertical axis. Ignored when both
-   * {@link x2} and {@link y2} are set (matplotlib-style chord on a curve).
-   */
+  /** End in data coordinates (with `x2`/`y2` → along-curve bar). */
+  x2?: number;
+  y2?: number;
+  /** Axis-aligned length when only one end is given. */
   length?: number;
   label?: string;
   color?: string;
+  /** Stroke width in CSS px. Default 1.8. */
   strokeWidth?: number;
   /**
-   * `horizontal` / `vertical` axis-aligned bars, or `along` for a free
-   * segment (x,y)→(x2,y2) with end-caps ⊥ in log–log space (default when
-   * both ends are given).
+   * `along` (default when both ends set): bar parallel to (x,y)→(x2,y2).
+   * `horizontal` / `vertical`: axis-aligned size bar.
    */
   orientation?: "horizontal" | "vertical" | "along";
-  /** Linear end-cap half-length (axis-aligned modes). */
-  tick?: number;
-  /** Geometric end-cap half-span on log axes (axis-aligned modes). */
-  tickRatio?: number;
-  /** End x (with y2: chord along curve). */
-  x2?: number;
-  /** End y (with x2: chord along curve). */
-  y2?: number;
   /**
-   * Log-space half-length of end-caps for `along` chords (default 0.16).
-   * Caps are perpendicular to the bar in (ln x, ln y).
+   * Screen-space offset of an `along` bar from the chord, as a fraction of
+   * the shorter plot side (default 0.05). Keeps the bar off the curve.
    */
-  capLog?: number;
+  offset?: number;
   /**
-   * Log-space offset of an `along` bar from the chord (x,y)→(x2,y2),
-   * along the path normal so the bar does not sit on the curve (default 0.42).
-   * Set 0 to draw on the chord itself.
+   * End-cap half-length in screen px (default 8).
    */
-  offsetLog?: number;
+  capSize?: number;
+  /** Label font size in px (default 14). */
+  fontSize?: number;
 };
 
 export type ArrowAnnotation = {
   kind: "arrow";
-  /** Tail (start). */
   x: number;
   y: number;
-  /** Tip (end). */
   x2: number;
   y2: number;
   label?: string;
   color?: string;
   strokeWidth?: number;
-  /** Tip mark size (Vega point size, area in px²). Default 55. */
+  /** Tip size in px (default 8). */
   tipSize?: number;
+  fontSize?: number;
 };
 
 export type Annotation = ScaleBarAnnotation | ArrowAnnotation;
 
-function cleanLayer(layer: Record<string, unknown>): VegaLiteSpec {
-  for (const k of Object.keys(layer)) {
-    if (layer[k] === undefined) delete layer[k];
-  }
-  return layer as VegaLiteSpec;
+/** Factory: one complete `|———|`. */
+export function scaleBar(
+  partial: Omit<ScaleBarAnnotation, "kind">,
+): ScaleBarAnnotation {
+  const hasEnds = partial.x2 != null && partial.y2 != null;
+  return {
+    color: "#18432b",
+    strokeWidth: 1.8,
+    orientation: hasEnds ? "along" : "horizontal",
+    offset: 0.05,
+    capSize: 8,
+    fontSize: 14,
+    ...partial,
+    kind: "scaleBar",
+  };
 }
 
-/** End-cap endpoints ⊥ to (x0,y0)→(x1,y1) in log–log space (matplotlib-like). */
-function logPerpCap(
-  x: number,
-  y: number,
-  x0: number,
-  y0: number,
-  x1: number,
-  y1: number,
-  s: number,
-): { x: number; y: number; x2: number; y2: number } {
-  const dx = Math.log(x1 / x0);
-  const dy = Math.log(y1 / y0);
-  const n = Math.hypot(dx, dy) || 1;
-  const px = (-dy / n) * s;
-  const py = (dx / n) * s;
+/** Factory: one complete arrow. */
+export function arrow(
+  partial: Omit<ArrowAnnotation, "kind">,
+): ArrowAnnotation {
   return {
-    x: Math.exp(Math.log(x) + px),
-    y: Math.exp(Math.log(y) + py),
-    x2: Math.exp(Math.log(x) - px),
-    y2: Math.exp(Math.log(y) - py),
+    color: "#18432b",
+    strokeWidth: 1.6,
+    tipSize: 8,
+    fontSize: 14,
+    ...partial,
+    kind: "arrow",
   };
 }
 
-function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
-  const color = a.color ?? "#14271d";
-  const sw = a.strokeWidth ?? 1.8;
-  const font = "Times New Roman, Times, STIX Two Text, STIXGeneral, serif";
-  const layers: VegaLiteSpec[] = [];
-
-  // Matplotlib-style chord on a curve: both ends fully specified.
-  const along =
-    a.orientation === "along" ||
-    (a.x2 != null &&
-      a.y2 != null &&
-      a.orientation !== "horizontal" &&
-      a.orientation !== "vertical");
-
-  if (along && a.x2 != null && a.y2 != null) {
-    // Chord on the curve (reference), then translate along the log-normal so
-    // the visible bar is parallel and does not overlap the path.
-    const rx0 = a.x;
-    const ry0 = a.y;
-    const rx1 = a.x2;
-    const ry1 = a.y2;
-    const dx = Math.log(rx1 / rx0);
-    const dy = Math.log(ry1 / ry0);
-    const n = Math.hypot(dx, dy) || 1;
-    const ux = dx / n;
-    const uy = dy / n;
-    // Prefer the normal that raises mid-y (above the curve on log–log plots).
-    let side = 1;
-    {
-      const midYPlus = Math.exp(
-        0.5 * (Math.log(ry0) + Math.log(ry1)) + ux * 0.1,
-      );
-      const midYMinus = Math.exp(
-        0.5 * (Math.log(ry0) + Math.log(ry1)) - ux * 0.1,
-      );
-      // offset uses perp (-uy, ux); mid log-y shift is ±ux * s
-      if (midYMinus > midYPlus) side = -1;
-    }
-    const sOff = a.offsetLog ?? 0.42;
-    const ox = -uy * sOff * side;
-    const oy = ux * sOff * side;
-    const x0 = Math.exp(Math.log(rx0) + ox);
-    const y0 = Math.exp(Math.log(ry0) + oy);
-    const x1 = Math.exp(Math.log(rx1) + ox);
-    const y1 = Math.exp(Math.log(ry1) + oy);
-    const sCap = a.capLog ?? 0.16;
-    const c0 = logPerpCap(x0, y0, x0, y0, x1, y1, sCap);
-    const c1 = logPerpCap(x1, y1, x0, y0, x1, y1, sCap);
-    // Label further out along the same normal.
-    const sLab = sOff + 0.32;
-    const lx = Math.exp(
-      0.5 * (Math.log(rx0) + Math.log(rx1)) + -uy * sLab * side,
-    );
-    const ly = Math.exp(
-      0.5 * (Math.log(ry0) + Math.log(ry1)) + ux * sLab * side,
-    );
-    layers.push(
-      cleanLayer({
-        data: { values: [{ x: x0, y: y0, x2: x1, y2: y1 }] },
-        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          y: { field: "y", type: "quantitative" },
-          x2: { field: "x2" },
-          y2: { field: "y2" },
-        },
-      }),
-      cleanLayer({
-        data: { values: [c0, c1] },
-        mark: { type: "rule", strokeWidth: sw, color },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          y: { field: "y", type: "quantitative" },
-          x2: { field: "x2" },
-          y2: { field: "y2" },
-        },
-      }),
-    );
-    if (a.label) {
-      layers.push(
-        cleanLayer({
-          data: { values: [{ x: lx, y: ly, label: a.label }] },
-          mark: {
-            type: "text",
-            font,
-            fontStyle: "normal",
-            color,
-            align: "center",
-            baseline: "middle",
-          },
-          encoding: {
-            x: { field: "x", type: "quantitative" },
-            y: { field: "y", type: "quantitative" },
-            text: { field: "label", type: "nominal" },
-          },
-        }),
-      );
+/**
+ * Pull top-level `annotations` off a payload (ignored by Vega-Lite).
+ * Returns a clean VL-shaped object plus the annotation list.
+ */
+export function takeAnnotations(spec: Record<string, unknown>): {
+  spec: Record<string, unknown>;
+  annotations: Annotation[];
+} {
+  const raw = spec.annotations;
+  if (!Array.isArray(raw) || raw.length === 0) {
+    if ("annotations" in spec) {
+      const { annotations: _drop, ...rest } = spec;
+      return { spec: rest, annotations: [] };
     }
-    return layers;
+    return { spec, annotations: [] };
   }
+  const annotations = raw.filter(
+    (a): a is Annotation =>
+      !!a &&
+      typeof a === "object" &&
+      ((a as Annotation).kind === "scaleBar" ||
+        (a as Annotation).kind === "arrow"),
+  );
+  const { annotations: _drop, ...rest } = spec;
+  return { spec: rest, annotations };
+}
 
-  const horizontal = (a.orientation ?? "horizontal") === "horizontal";
+/** Minimal view surface needed to project data → SVG pixels. */
+export interface AnnotationView {
+  /** Vega scale: data value → plot-local pixel. */
+  scale(name: string): ((v: number) => number) | undefined;
+  /** Top-left of the plot rectangle inside the SVG. */
+  origin(): number[];
+  signal(name: string): unknown;
+}
 
-  if (horizontal) {
-    const x0 = a.x;
-    const x1 =
-      a.x2 ?? a.x + (Number.isFinite(a.length) ? (a.length as number) : 0);
-    const mid = (x0 + x1) / 2;
-    const yLo =
-      a.tickRatio != null
-        ? a.y / a.tickRatio
-        : a.y -
-          (a.tick ??
-            (Number.isFinite(a.length) && a.length
-              ? Math.abs(a.length as number) * 0.08
-              : 0.05));
-    const yHi =
-      a.tickRatio != null
-        ? a.y * a.tickRatio
-        : a.y +
-          (a.tick ??
-            (Number.isFinite(a.length) && a.length
-              ? Math.abs(a.length as number) * 0.08
-              : 0.05));
-    layers.push(
-      cleanLayer({
-        data: { values: [{ x: x0, x2: x1, y: a.y }] },
-        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          x2: { field: "x2" },
-          y: { field: "y", type: "quantitative" },
-        },
-      }),
-      cleanLayer({
-        data: {
-          values: [
-            { x: x0, y: yLo, y2: yHi },
-            { x: x1, y: yLo, y2: yHi },
-          ],
-        },
-        mark: { type: "rule", strokeWidth: sw, color },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          y: { field: "y", type: "quantitative" },
-          y2: { field: "y2" },
-        },
-      }),
-    );
-    if (a.label) {
-      layers.push(
-        cleanLayer({
-          data: { values: [{ x: mid, y: a.y, label: a.label }] },
-          mark: {
-            type: "text",
-            dy: -10,
-            font,
-            fontStyle: "normal",
-            color,
-            align: "center",
-            baseline: "bottom",
-          },
-          encoding: {
-            x: { field: "x", type: "quantitative" },
-            y: { field: "y", type: "quantitative" },
-            text: { field: "label", type: "nominal" },
-          },
-        }),
-      );
-    }
-  } else {
-    const y0 = a.y;
-    const y1 =
-      a.y2 ?? a.y + (Number.isFinite(a.length) ? (a.length as number) : 0);
-    const mid = (y0 + y1) / 2;
-    const tick =
-      a.tick ??
-      (Number.isFinite(a.length) && a.length
-        ? Math.abs(a.length as number) * 0.08
-        : 0.05);
-    const xLo = a.tickRatio != null ? a.x / a.tickRatio : a.x - tick;
-    const xHi = a.tickRatio != null ? a.x * a.tickRatio : a.x + tick;
-    layers.push(
-      cleanLayer({
-        data: { values: [{ x: a.x, y: y0, y2: y1 }] },
-        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          y: { field: "y", type: "quantitative" },
-          y2: { field: "y2" },
-        },
-      }),
-      cleanLayer({
-        data: {
-          values: [
-            { x: xLo, x2: xHi, y: y0 },
-            { x: xLo, x2: xHi, y: y1 },
-          ],
-        },
-        mark: { type: "rule", strokeWidth: sw, color },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          x2: { field: "x2" },
-          y: { field: "y", type: "quantitative" },
-        },
-      }),
-    );
-    if (a.label) {
-      layers.push(
-        cleanLayer({
-          data: { values: [{ x: a.x, y: mid, label: a.label }] },
-          mark: {
-            type: "text",
-            dx: 10,
-            font,
-            fontStyle: "normal",
-            color,
-            align: "left",
-            baseline: "middle",
-          },
-          encoding: {
-            x: { field: "x", type: "quantitative" },
-            y: { field: "y", type: "quantitative" },
-            text: { field: "label", type: "nominal" },
-          },
-        }),
-      );
-    }
-  }
+const SVG_NS = "http://www.w3.org/2000/svg";
+const OVERLAY_ATTR = "data-molplot-annotations";
 
-  return layers;
+function lineEl(
+  x1: number,
+  y1: number,
+  x2: number,
+  y2: number,
+  color: string,
+  width: number,
+): SVGLineElement {
+  const el = document.createElementNS(SVG_NS, "line");
+  el.setAttribute("x1", String(x1));
+  el.setAttribute("y1", String(y1));
+  el.setAttribute("x2", String(x2));
+  el.setAttribute("y2", String(y2));
+  el.setAttribute("stroke", color);
+  el.setAttribute("stroke-width", String(width));
+  el.setAttribute("stroke-linecap", "butt");
+  return el;
 }
 
-function arrowLayers(a: ArrowAnnotation): VegaLiteSpec[] {
-  const color = a.color ?? "#14271d";
-  const sw = a.strokeWidth ?? 1.6;
-  const tipSize = a.tipSize ?? 55;
-  // Vega point `angle` is degrees clockwise from north; atan2 is from +x CCW.
-  const angleDeg = (Math.atan2(a.y2 - a.y, a.x2 - a.x) * 180) / Math.PI + 90;
+function textEl(
+  x: number,
+  y: number,
+  text: string,
+  color: string,
+  fontSize: number,
+): SVGTextElement {
+  const el = document.createElementNS(SVG_NS, "text");
+  el.setAttribute("x", String(x));
+  el.setAttribute("y", String(y));
+  el.setAttribute("fill", color);
+  el.setAttribute("font-size", String(fontSize));
+  el.setAttribute(
+    "font-family",
+    "Times New Roman, Times, STIX Two Text, STIXGeneral, serif",
+  );
+  el.setAttribute("font-style", "normal");
+  el.setAttribute("text-anchor", "middle");
+  el.setAttribute("dominant-baseline", "middle");
+  el.textContent = text;
+  return el;
+}
 
-  const layers: VegaLiteSpec[] = [
-    cleanLayer({
-      data: {
-        values: [{ x: a.x, y: a.y, x2: a.x2, y2: a.y2 }],
-      },
-      mark: { type: "rule", strokeWidth: sw, color, strokeCap: "round" },
-      encoding: {
-        x: { field: "x", type: "quantitative" },
-        y: { field: "y", type: "quantitative" },
-        x2: { field: "x2" },
-        y2: { field: "y2" },
-      },
-    }),
-    cleanLayer({
-      data: {
-        values: [{ x: a.x2, y: a.y2, angle: angleDeg }],
-      },
-      mark: {
-        type: "point",
-        shape: "triangle",
-        filled: true,
-        size: tipSize,
-        color,
-      },
-      encoding: {
-        x: { field: "x", type: "quantitative" },
-        y: { field: "y", type: "quantitative" },
-        angle: { field: "angle", type: "quantitative" },
-      },
-    }),
-  ];
+/**
+ * Paint annotations into `svg` using the live Vega scales (screen-correct).
+ * Idempotent: replaces any previous overlay group. `pointer-events: none`
+ * so pan/zoom on the plot still works.
+ */
+export function drawAnnotations(
+  svg: SVGSVGElement,
+  view: AnnotationView,
+  annotations: Annotation[],
+): void {
+  svg.querySelector(`[${OVERLAY_ATTR}]`)?.remove();
+  if (!annotations.length) return;
 
-  if (a.label) {
-    const mx = (a.x + a.x2) / 2;
-    const my = (a.y + a.y2) / 2;
-    layers.push(
-      cleanLayer({
-        data: { values: [{ x: mx, y: my, label: a.label }] },
-        mark: {
-          type: "text",
-          dy: -8,
-          fontSize: 11,
-          color,
-          align: "center",
-          baseline: "bottom",
-        },
-        encoding: {
-          x: { field: "x", type: "quantitative" },
-          y: { field: "y", type: "quantitative" },
-          text: { field: "label", type: "nominal" },
-        },
-      }),
-    );
-  }
+  const xScale = view.scale("x");
+  const yScale = view.scale("y");
+  if (!xScale || !yScale) return;
 
-  return layers;
-}
+  const [ox, oy] = view.origin();
+  const width = Number(view.signal("width")) || 0;
+  const height = Number(view.signal("height")) || 0;
+  if (width <= 0 || height <= 0) return;
+
+  const toPx = (x: number, y: number): [number, number] => [
+    ox + xScale(x),
+    oy + yScale(y),
+  ];
+
+  const g = document.createElementNS(SVG_NS, "g");
+  g.setAttribute(OVERLAY_ATTR, "");
+  g.setAttribute("style", "pointer-events: none");
 
-/** Expand annotations into Vega-Lite unit layers (own data, no shared scales). */
-export function annotationLayers(annotations: Annotation[]): VegaLiteSpec[] {
-  const out: VegaLiteSpec[] = [];
   for (const a of annotations) {
-    if (a.kind === "scaleBar") out.push(...scaleBarLayers(a));
-    else if (a.kind === "arrow") out.push(...arrowLayers(a));
+    if (a.kind === "scaleBar") drawScaleBar(g, a, toPx, width, height);
+    else if (a.kind === "arrow") drawArrow(g, a, toPx);
   }
-  return out;
+
+  svg.appendChild(g);
 }
 
-/**
- * Merge annotation layers into a unit or layered Vega-Lite spec.
- * Unit specs become layered; existing `layer` arrays are appended to.
- */
-export function withAnnotations(
-  spec: VegaLiteSpec,
-  annotations: Annotation[] | undefined | null,
-): VegaLiteSpec {
-  if (!annotations?.length) return spec;
-  const extra = annotationLayers(annotations);
-  if (!extra.length) return spec;
+function drawScaleBar(
+  g: SVGGElement,
+  a: ScaleBarAnnotation,
+  toPx: (x: number, y: number) => [number, number],
+  plotW: number,
+  plotH: number,
+): void {
+  const color = a.color ?? "#18432b";
+  const sw = a.strokeWidth ?? 1.8;
+  const capHalf = a.capSize ?? 8;
+  const fontSize = a.fontSize ?? 14;
+  const orient =
+    a.orientation ??
+    (a.x2 != null && a.y2 != null ? "along" : "horizontal");
+
+  let x0 = a.x;
+  let y0 = a.y;
+  let x1: number;
+  let y1: number;
 
-  if (Array.isArray(spec.layer)) {
-    return {
-      ...spec,
-      layer: [...(spec.layer as VegaLiteSpec[]), ...extra],
-    };
+  if (orient === "along" && a.x2 != null && a.y2 != null) {
+    x1 = a.x2;
+    y1 = a.y2;
+  } else if (orient === "vertical") {
+    x1 = a.x;
+    y1 = a.y2 ?? a.y + (a.length ?? 0);
+  } else {
+    x1 = a.x2 ?? a.x + (a.length ?? 0);
+    y1 = a.y;
   }
 
-  // Unit → layered. Keep top-level data only if the unit layer still needs it
-  // via inheritance; copy unit fields into layer[0] for a self-contained base.
-  const { mark, encoding, data, transform, params, ...rest } = spec as Record<
-    string,
-    unknown
-  >;
+  let [px0, py0] = toPx(x0, y0);
+  let [px1, py1] = toPx(x1, y1);
 
-  if (mark !== undefined || encoding !== undefined) {
-    const baseLayer: VegaLiteSpec = {};
-    if (data !== undefined) baseLayer.data = data;
-    if (mark !== undefined) baseLayer.mark = mark;
-    if (encoding !== undefined) baseLayer.encoding = encoding;
-    if (transform !== undefined) baseLayer.transform = transform;
-    if (params !== undefined) baseLayer.params = params;
-    return {
-      ...rest,
-      layer: [baseLayer, ...extra],
-    } as VegaLiteSpec;
+  // Screen-space direction along the bar
+  let dx = px1 - px0;
+  let dy = py1 - py0;
+  const len = Math.hypot(dx, dy) || 1;
+  const tx = dx / len;
+  const ty = dy / len;
+  // Screen-space normal (rotate 90°)
+  let nx = -ty;
+  let ny = tx;
+  // Prefer normal that points "up" on screen (smaller y in SVG)
+  if (ny > 0) {
+    nx = -nx;
+    ny = -ny;
   }
 
-  // Already a multi-view / facet without unit marks — attach layers only.
-  return {
-    ...spec,
-    layer: extra,
-  };
+  if (orient === "along") {
+    const offsetPx =
+      (a.offset ?? 0.05) * Math.min(plotW, plotH);
+    px0 += nx * offsetPx;
+    py0 += ny * offsetPx;
+    px1 += nx * offsetPx;
+    py1 += ny * offsetPx;
+  }
+
+  // Spine
+  g.appendChild(lineEl(px0, py0, px1, py1, color, sw));
+  // Caps ⊥ spine in screen space
+  g.appendChild(
+    lineEl(
+      px0 + nx * capHalf,
+      py0 + ny * capHalf,
+      px0 - nx * capHalf,
+      py0 - ny * capHalf,
+      color,
+      sw,
+    ),
+  );
+  g.appendChild(
+    lineEl(
+      px1 + nx * capHalf,
+      py1 + ny * capHalf,
+      px1 - nx * capHalf,
+      py1 - ny * capHalf,
+      color,
+      sw,
+    ),
+  );
+
+  if (a.label) {
+    const mx = (px0 + px1) / 2 + nx * (capHalf + fontSize * 0.7);
+    const my = (py0 + py1) / 2 + ny * (capHalf + fontSize * 0.7);
+    g.appendChild(textEl(mx, my, a.label, color, fontSize));
+  }
 }
 
-/**
- * Pull a top-level `annotations` key off a fence/RawChart payload and merge.
- * Returns `{ spec, annotations }` where `spec` has no `annotations` field.
- */
-export function takeAnnotations(spec: VegaLiteSpec): {
-  spec: VegaLiteSpec;
-  annotations: Annotation[];
-} {
-  const raw = (spec as { annotations?: unknown }).annotations;
-  if (!Array.isArray(raw) || raw.length === 0) {
-    if ("annotations" in spec) {
-      const { annotations: _drop, ...rest } = spec as Record<string, unknown>;
-      return { spec: rest as VegaLiteSpec, annotations: [] };
-    }
-    return { spec, annotations: [] };
+function drawArrow(
+  g: SVGGElement,
+  a: ArrowAnnotation,
+  toPx: (x: number, y: number) => [number, number],
+): void {
+  const color = a.color ?? "#18432b";
+  const sw = a.strokeWidth ?? 1.6;
+  const tip = a.tipSize ?? 8;
+  const [px0, py0] = toPx(a.x, a.y);
+  const [px1, py1] = toPx(a.x2, a.y2);
+  g.appendChild(lineEl(px0, py0, px1, py1, color, sw));
+
+  const dx = px1 - px0;
+  const dy = py1 - py0;
+  const len = Math.hypot(dx, dy) || 1;
+  const ux = dx / len;
+  const uy = dy / len;
+  // Arrowhead as two short lines
+  const hx = -ux * tip + -uy * tip * 0.5;
+  const hy = -uy * tip + ux * tip * 0.5;
+  const hx2 = -ux * tip + uy * tip * 0.5;
+  const hy2 = -uy * tip + -ux * tip * 0.5;
+  g.appendChild(lineEl(px1, py1, px1 + hx, py1 + hy, color, sw));
+  g.appendChild(lineEl(px1, py1, px1 + hx2, py1 + hy2, color, sw));
+
+  if (a.label) {
+    const fontSize = a.fontSize ?? 14;
+    g.appendChild(
+      textEl(
+        (px0 + px1) / 2,
+        (py0 + py1) / 2 - fontSize,
+        a.label,
+        color,
+        fontSize,
+      ),
+    );
   }
-  const annotations = raw.filter(
-    (a): a is Annotation =>
-      !!a &&
-      typeof a === "object" &&
-      ((a as Annotation).kind === "scaleBar" ||
-        (a as Annotation).kind === "arrow"),
-  );
-  const { annotations: _drop, ...rest } = spec as Record<string, unknown>;
-  return { spec: rest as VegaLiteSpec, annotations };
 }
diff --git a/core/src/chart_base.ts b/core/src/chart_base.ts
index d25208a..cd1b182 100644
--- a/core/src/chart_base.ts
+++ b/core/src/chart_base.ts
@@ -23,7 +23,7 @@ interface SceneItem {
 }
 
 /** Minimal shape of the vega-embed result we depend on. */
-interface EmbedResult {
+export interface EmbedResult {
   view: {
     data(name: string, values?: unknown[]): unknown;
     resize(): { run(): unknown };
@@ -31,10 +31,12 @@ interface EmbedResult {
     /** Top-left of the plot rectangle within the rendered element. */
     origin(): number[];
     signal(name: string): unknown;
+    /** Named scale: data value → plot-local pixel (undefined if missing). */
+    scale(name: string): ((value: number) => number) | undefined;
     scenegraph(): { root: SceneItem };
     addEventListener(
       type: string,
-      handler: (e: unknown, item: unknown) => void,
+      handler: (e: unknown, item?: unknown) => void,
     ): void;
     finalize(): void;
   };
@@ -215,8 +217,15 @@ export abstract class VegaChart {
     this.zoomable = zoomParamsOf(spec).length > 0;
     this.rendered = this.container.querySelector("svg");
     this.result = result;
+    this.afterRender(result);
   }
 
+  /**
+   * Hook after a successful embed (subclasses: annotation overlays, etc.).
+   * Default no-op.
+   */
+  protected afterRender(_result: EmbedResult): void {}
+
   /**
    * Wheel interaction for scale zoom:
    * - Axis gutter → that axis alone (classic molplot behaviour)
diff --git a/core/src/index.ts b/core/src/index.ts
index ee75dc2..8f205b6 100644
--- a/core/src/index.ts
+++ b/core/src/index.ts
@@ -7,11 +7,10 @@ export type {
   ScaleBarAnnotation,
 } from "./annotations";
 export {
-  annotationLayers,
   arrow,
+  drawAnnotations,
   scaleBar,
   takeAnnotations,
-  withAnnotations,
 } from "./annotations";
 export type {
   BarChartConfig,
diff --git a/core/src/raw_chart.interactive.test.ts b/core/src/raw_chart.interactive.test.ts
index 1d10fdf..c96d5dc 100644
--- a/core/src/raw_chart.interactive.test.ts
+++ b/core/src/raw_chart.interactive.test.ts
@@ -1,31 +1,34 @@
 /**
- * RawChart must inject zoom params for layered agent/LLM specs (encoding on
- * layer[0], not top-level) and must not skip empty ``params: []``.
+ * RawChart interactive injection helpers (mirrored pure logic).
  */
 
 import { describe, expect, it } from "@rstest/core";
 import { interactionParams } from "./specs";
 
-// Mirror the pure helpers used by RawChart (kept local so the test stays
-// free of DOM / vega-embed).
 type ZoomChannel = "x" | "y";
 
 function continuousChannels(spec: Record<string, unknown>): ZoomChannel[] {
   const top = spec.encoding as
-    | Record<string, { type?: string } | undefined>
+    | Record<string, { type?: string; field?: string } | undefined>
     | undefined;
   const layers = Array.isArray(spec.layer)
-    ? (spec.layer as { encoding?: Record<string, { type?: string }> }[])
+    ? (spec.layer as {
+        encoding?: Record<string, { type?: string; field?: string }>;
+      }[])
     : [];
-  const encoding =
-    top ?? layers.find((layer) => layer?.encoding)?.encoding ?? undefined;
+  const layerEnc = layers.find((layer) => layer?.encoding)?.encoding;
   return (["x", "y"] as const).filter((channel) => {
-    const type = encoding?.[channel]?.type;
-    return type === "quantitative" || type === "temporal";
+    const type = top?.[channel]?.type ?? layerEnc?.[channel]?.type;
+    if (type === "quantitative" || type === "temporal") return true;
+    const field = top?.[channel]?.field ?? layerEnc?.[channel]?.field;
+    return Boolean(field && top?.[channel]);
   });
 }
 
-function mergeZoomParams(existing: unknown, zoom: ReturnType<typeof interactionParams>) {
+function mergeZoomParams(
+  existing: unknown,
+  zoom: ReturnType<typeof interactionParams>,
+) {
   const zoomNames = new Set(zoom.map((p) => p.name));
   const kept: unknown[] = [];
   if (Array.isArray(existing)) {
@@ -41,7 +44,19 @@ function mergeZoomParams(existing: unknown, zoom: ReturnType<typeof interactionP
   return [...kept, ...zoom];
 }
 
-describe("RawChart interactive injection (layered agent specs)", () => {
+/** Where zoom params should be placed for a given spec shape. */
+function zoomPlacement(spec: Record<string, unknown>): "top" | "layer0" | "none" {
+  const channels = continuousChannels(spec);
+  if (channels.length === 0) return "none";
+  const layers = Array.isArray(spec.layer) ? spec.layer : null;
+  const topEncoding =
+    spec.encoding && typeof spec.encoding === "object" ? spec.encoding : null;
+  if (layers && layers.length > 0 && topEncoding) return "top";
+  if (layers && layers.length > 0) return "layer0";
+  return "top";
+}
+
+describe("RawChart interactive injection", () => {
   it("finds continuous channels on layer[0].encoding", () => {
     const channels = continuousChannels({
       layer: [
@@ -56,6 +71,51 @@ describe("RawChart interactive injection (layered agent specs)", () => {
     expect(channels).toEqual(["x", "y"]);
   });
 
+  it("reads continuous type from top encoding when fields are on layers", () => {
+    const channels = continuousChannels({
+      encoding: {
+        x: { type: "quantitative", scale: { type: "log" } },
+        y: { type: "quantitative", scale: { type: "log" } },
+      },
+      layer: [
+        {
+          encoding: {
+            x: { field: "x" },
+            y: { field: "y" },
+          },
+        },
+      ],
+    });
+    expect(channels).toEqual(["x", "y"]);
+  });
+
+  it("places zoom params at top when encoding is shared on a layered chart", () => {
+    expect(
+      zoomPlacement({
+        encoding: {
+          x: { type: "quantitative" },
+          y: { type: "quantitative" },
+        },
+        layer: [{ encoding: { x: { field: "x" }, y: { field: "y" } } }],
+      }),
+    ).toBe("top");
+  });
+
+  it("places zoom params on layer0 when only unit layers have encoding", () => {
+    expect(
+      zoomPlacement({
+        layer: [
+          {
+            encoding: {
+              x: { field: "N", type: "quantitative" },
+              y: { field: "Rg", type: "quantitative" },
+            },
+          },
+        ],
+      }),
+    ).toBe("layer0");
+  });
+
   it("merges zoom params over empty params:[]", () => {
     const zoom = interactionParams(["x", "y"]);
     const merged = mergeZoomParams([], zoom);
diff --git a/core/src/raw_chart.ts b/core/src/raw_chart.ts
index 0f848e2..203fdc1 100644
--- a/core/src/raw_chart.ts
+++ b/core/src/raw_chart.ts
@@ -1,5 +1,9 @@
-import { takeAnnotations, withAnnotations } from "./annotations";
-import { VegaChart } from "./chart_base";
+import {
+  type Annotation,
+  drawAnnotations,
+  takeAnnotations,
+} from "./annotations";
+import { type EmbedResult, VegaChart } from "./chart_base";
 import type { PresetName } from "./preset";
 import {
   interactionParams,
@@ -10,51 +14,45 @@ import { type ChartTheme, fontScaleForWidth, vegaConfig } from "./theme";
 import type { ThemeMode } from "./types";
 
 /**
- * Escape hatch: render an arbitrary Vega-Lite spec verbatim. Now that the
- * intermediate language *is* Vega-Lite, "render whatever upstream emitted"
- * (an LLM agent, a saved report, a Python-built spec shipped to the browser)
- * is a first-class path — the same spec the Python package can render to
- * matplotlib. The unified preset `config` is injected unless the spec already
- * carries its own.
- *
- * NOTE (migration): the former plotly-based `RawChart` accepted
- * `{data, layout, config}` plotly JSON. That is not portable to Vega; callers
- * that fed plotly specs must now supply a Vega-Lite spec via `config.spec`.
+ * Escape hatch: render an arbitrary Vega-Lite spec. Optional top-level
+ * `annotations` (molplot extension) are stripped before embed and painted
+ * as a screen-space SVG overlay after layout / on pan-zoom.
  */
 export interface RawChartConfig {
-  /** A Vega-Lite top-level spec. Inline `data.values` is rendered as-is. */
+  /** A Vega-Lite top-level spec (plus optional `annotations`). */
   spec: VegaLiteSpec;
-  /**
-   * Which unified preset to inject as the spec `config` when the spec carries
-   * none. Defaults to the default preset — the same tokens the Python package
-   * applies. A spec with its own `config` is always respected verbatim.
-   */
   preset?: PresetName;
-  /** Theme mode. `auto` (default) tracks `<html class="dark">`. */
   theme?: ThemeMode;
-  /** Add scale-bound pan/zoom controls when the spec has none. Default: true. */
+  /** Scale-bound pan/zoom when the spec has continuous x/y. Default true. */
   interactive?: boolean;
-  /** Responsive width:height ratio. Default: 4 / 3. */
+  /** Responsive width:height ratio. Default 4 / 3. */
   aspectRatio?: number;
 }
 
 export class RawChart extends VegaChart {
-  private spec: VegaLiteSpec;
-  private interactive: boolean;
-  private aspectRatio: number;
+  private spec: VegaLiteSpec = {};
+  private interactive = true;
+  private aspectRatio = 4 / 3;
+  private annotations: Annotation[] = [];
 
   constructor(container: HTMLElement, config: RawChartConfig) {
     super(container, config.theme ?? "auto", config.preset);
-    this.spec = config.spec;
-    this.interactive = config.interactive ?? true;
-    this.aspectRatio = config.aspectRatio ?? 4 / 3;
+    this.applyConfig(config);
   }
 
   async update(config: RawChartConfig): Promise<void> {
-    this.spec = config.spec;
+    this.applyConfig(config);
+    await this.rerender();
+  }
+
+  private applyConfig(config: RawChartConfig): void {
+    const taken = takeAnnotations({
+      ...((config.spec ?? {}) as Record<string, unknown>),
+    });
+    this.spec = taken.spec as VegaLiteSpec;
+    this.annotations = taken.annotations;
     this.interactive = config.interactive ?? true;
     this.aspectRatio = config.aspectRatio ?? 4 / 3;
-    await this.rerender();
   }
 
   protected datasets(): Record<string, unknown[]> {
@@ -65,24 +63,45 @@ export class RawChart extends VegaChart {
     previous: { width: number; height: number },
     next: { width: number; height: number },
   ): boolean {
-    // With the default 4:3 size, height is derived exclusively from width.
-    // SVG axes can perturb an auto-height DOM box, but that is render output,
-    // not an input resize. Ignoring it prevents ResizeObserver → re-embed loops.
     if (this.spec?.height === undefined) return previous.width !== next.width;
     return super.resizeChanged(previous, next);
   }
 
+  /** Paint scale bars / arrows after embed and whenever scales move. */
+  protected afterRender(result: EmbedResult): void {
+    this.paintAnnotations(result);
+    // Redraw overlay when the user pans/zooms (scales change).
+    const view = result.view;
+    const redraw = (): void => {
+      requestAnimationFrame(() => this.paintAnnotations(result));
+    };
+    view.addEventListener("wheel", redraw);
+    view.addEventListener("mousedown", () => {
+      const move = (): void => redraw();
+      const up = (): void => {
+        window.removeEventListener("mousemove", move);
+        window.removeEventListener("mouseup", up);
+        redraw();
+      };
+      window.addEventListener("mousemove", move);
+      window.addEventListener("mouseup", up);
+    });
+    view.addEventListener("dblclick", redraw);
+  }
+
+  private paintAnnotations(result: EmbedResult): void {
+    if (!this.annotations.length) return;
+    const svg = this.container.querySelector("svg");
+    if (!svg) return;
+    drawAnnotations(svg, result.view, this.annotations);
+  }
+
   protected buildSpec(
     theme: ChartTheme,
     sizeHint: { width: number; height: number },
   ): VegaLiteSpec {
-    // Strip top-level `annotations` and expand to VL layers (scale bar / arrow).
-    const taken = takeAnnotations({ ...(this.spec ?? {}) });
-    const spec = withAnnotations(taken.spec, taken.annotations);
+    const spec = { ...(this.spec ?? {}) } as VegaLiteSpec;
     const channels = this.interactive ? continuousChannels(spec) : [];
-    // Prefer the host box height when the element has a real layout size so a
-    // 4:3 (or author aspect) frame is fully painted — not a short SVG floating
-    // in a taller white box. Fall back to width/aspect for headless/zero-size.
     const derivedHeight = Math.max(
       1,
       Math.round(sizeHint.width / this.aspectRatio),
@@ -101,9 +120,6 @@ export class RawChart extends VegaChart {
       ? deepMergeConfig(baseConfig, authorConfig)
       : baseConfig;
 
-    // `fit` + `contains: "padding"`: width/height are the outer SVG box
-    // (axes + legends + pad). Multi-legend specs stay inside the host without
-    // overlapping titles when type sizes stay moderate.
     const base: VegaLiteSpec = {
       $schema: "https://vega.github.io/schema/vega-lite/v5.json",
       width: sizeHint.width,
@@ -116,12 +132,24 @@ export class RawChart extends VegaChart {
     if (channels.length === 0) return base;
 
     const zoom = interactionParams(channels);
-    // Layered agent/LLM specs put encoding on layer[0]; zoom params must live
-    // on a *unit* layer (top-level params on layered specs are illegal /
-    // duplicate). Unit specs take top-level params.
     const layers = Array.isArray(spec.layer)
       ? (spec.layer as Record<string, unknown>[])
       : null;
+    const topEncoding =
+      spec.encoding && typeof spec.encoding === "object"
+        ? (spec.encoding as Record<string, unknown>)
+        : null;
+
+    // Shared top-level encoding (docs layered charts): bind:scales must be
+    // top-level or pan/zoom never attaches to the shared axes.
+    if (layers && layers.length > 0 && topEncoding) {
+      return {
+        ...base,
+        params: mergeZoomParams(spec.params, zoom),
+      };
+    }
+
+    // Encoding only on unit layers: params live on the first unit layer.
     if (layers && layers.length > 0) {
       const nextLayers = layers.map((layer, i) => {
         if (i !== 0) return layer;
@@ -130,7 +158,6 @@ export class RawChart extends VegaChart {
           params: mergeZoomParams(layer.params, zoom),
         };
       });
-      // Drop any top-level params so we don't duplicate zoom signal names.
       const { params: _drop, ...rest } = base;
       return { ...rest, layer: nextLayers };
     }
@@ -190,20 +217,24 @@ function deepMergeConfig(
 }
 
 /**
- * Continuous x/y channels from a unit spec **or** the first layer of a
- * layered spec (agent/LLM VL almost always uses ``layer``).
+ * Continuous x/y channels: merge top-level encoding (type/scale) with the
+ * first layer that declares fields (docs layered charts often split these).
  */
 function continuousChannels(spec: VegaLiteSpec): ZoomChannel[] {
   const top = spec.encoding as
-    | Record<string, { type?: string } | undefined>
+    | Record<string, { type?: string; field?: string } | undefined>
     | undefined;
   const layers = Array.isArray(spec.layer)
-    ? (spec.layer as { encoding?: Record<string, { type?: string }> }[])
+    ? (spec.layer as {
+        encoding?: Record<string, { type?: string; field?: string }>;
+      }[])
     : [];
-  const encoding =
-    top ?? layers.find((layer) => layer?.encoding)?.encoding ?? undefined;
+  const layerEnc = layers.find((layer) => layer?.encoding)?.encoding;
   return (["x", "y"] as const).filter((channel) => {
-    const type = encoding?.[channel]?.type;
-    return type === "quantitative" || type === "temporal";
+    const type = top?.[channel]?.type ?? layerEnc?.[channel]?.type;
+    if (type === "quantitative" || type === "temporal") return true;
+    // Field on a layer + scale/type on top still counts as continuous.
+    const field = top?.[channel]?.field ?? layerEnc?.[channel]?.field;
+    return Boolean(field && (top?.[channel]?.type || top?.[channel]));
   });
 }
diff --git a/core/tests/annotations.test.ts b/core/tests/annotations.test.ts
index 4890d96..e86f25c 100644
--- a/core/tests/annotations.test.ts
+++ b/core/tests/annotations.test.ts
@@ -1,86 +1,23 @@
 import { describe, expect, it } from "@rstest/core";
 import {
-  annotationLayers,
+  scaleBar,
   takeAnnotations,
-  withAnnotations,
   type Annotation,
 } from "../src/annotations";
 
 describe("annotations", () => {
-  it("builds a horizontal scale bar as rule + end-caps (+ optional label)", () => {
-    const layers = annotationLayers([
-      {
-        kind: "scaleBar",
-        x: 10,
-        y: 1,
-        length: 20,
-        label: "20 τ",
-      },
-    ]);
-    expect(layers.length).toBe(3);
-    expect((layers[0].mark as { type: string }).type).toBe("rule");
-    expect((layers[1].mark as { type: string }).type).toBe("rule");
-    expect((layers[2].mark as { type: string }).type).toBe("text");
-  });
-
-  it("offsets along-curve bars off the path with log-perp end-caps", () => {
-    const layers = annotationLayers([
-      {
-        kind: "scaleBar",
-        orientation: "along",
-        x: 0.18,
-        y: 0.0324,
-        x2: 0.65,
-        y2: 0.4225,
-        offsetLog: 0.42,
-        label: "ballistic",
-      },
-    ]);
-    expect(layers.length).toBe(3);
-    const bar = layers[0].data as {
-      values: { x: number; y: number; x2: number; y2: number }[];
-    };
-    // Bar is translated off the chord — not the raw endpoints.
-    expect(bar.values[0].x).not.toBeCloseTo(0.18, 2);
-    expect(bar.values[0].y).not.toBeCloseTo(0.0324, 2);
-    const caps = layers[1].data as { values: unknown[] };
-    expect(caps.values).toHaveLength(2);
-  });
-
-  it("builds an arrow as rule + tip (+ optional label)", () => {
-    const layers = annotationLayers([
-      {
-        kind: "arrow",
-        x: 0,
-        y: 0,
-        x2: 1,
-        y2: 1,
-        label: "diffusive",
-      },
-    ]);
-    expect(layers.length).toBe(3);
-    expect((layers[0].mark as { type: string }).type).toBe("rule");
-    expect((layers[1].mark as { type: string }).type).toBe("point");
-    expect((layers[2].mark as { type: string }).type).toBe("text");
-  });
-
-  it("withAnnotations converts a unit spec into a layered one", () => {
-    const unit = {
-      mark: "line",
-      data: { values: [{ t: 1, msd: 1 }] },
-      encoding: {
-        x: { field: "t", type: "quantitative" },
-        y: { field: "msd", type: "quantitative" },
-      },
-    };
-    const anns: Annotation[] = [
-      { kind: "scaleBar", x: 1, y: 0.5, length: 2, label: "2" },
-    ];
-    const layered = withAnnotations(unit, anns);
-    expect(Array.isArray(layered.layer)).toBe(true);
-    const layers = layered.layer as unknown[];
-    expect(layers.length).toBeGreaterThan(1);
-    expect(layered.mark).toBeUndefined();
+  it("scaleBar factory defaults to along when both ends are set", () => {
+    const a = scaleBar({
+      x: 0.18,
+      y: 0.03,
+      x2: 0.65,
+      y2: 0.42,
+      label: "ballistic",
+    });
+    expect(a.kind).toBe("scaleBar");
+    expect(a.orientation).toBe("along");
+    expect(a.offset).toBe(0.05);
+    expect(a.capSize).toBe(8);
   });
 
   it("takeAnnotations strips the top-level key", () => {
@@ -90,9 +27,9 @@ describe("annotations", () => {
         { kind: "arrow", x: 0, y: 0, x2: 1, y2: 1 },
         { kind: "nope" },
       ],
-    } as never);
+    });
     expect(annotations).toHaveLength(1);
-    expect(annotations[0].kind).toBe("arrow");
+    expect((annotations[0] as Annotation).kind).toBe("arrow");
     expect("annotations" in spec).toBe(false);
   });
 });

From 8fe188d2d9fcb73561c5e208100662c8123233d2 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 22:06:21 +0200
Subject: [PATCH 16/17] fix(annotations): pure VL layers + layer0 zoom (no
 duplicate signals)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Expand scaleBar/arrow into rule/text layers that share chart scales so they
pan/zoom with the plot. Put bind:scales params on layer[0] only — top-level
params with multi-layer specs make Vega-Lite emit duplicate zoom signals and
vega.parse fails (chart invisible).

Move interactive unit test out of src/ so dist stays free of *.test.js.
Ignore staged docs/assets in biome.
---
 .gitignore                                    |   2 +
 biome.json                                    |   2 +
 core/rslib.config.ts                          |   1 +
 core/src/annotations.ts                       | 505 ++++++++++--------
 core/src/chart_base.ts                        |   4 +-
 core/src/index.ts                             |   3 +-
 core/src/raw_chart.ts                         |  75 +--
 core/tests/annotations.test.ts                | 124 ++++-
 core/tests/element.test.ts                    |   5 +-
 .../raw_chart.interactive.test.ts             |  36 +-
 10 files changed, 437 insertions(+), 320 deletions(-)
 rename core/{src => tests}/raw_chart.interactive.test.ts (78%)

diff --git a/.gitignore b/.gitignore
index 1006add..cd6d5c1 100644
--- a/.gitignore
+++ b/.gitignore
@@ -17,6 +17,8 @@ build/
 
 # Docs
 site/
+# Staged from core/dist for local zensical; rebuild stages fresh.
+docs/assets/molplot/
 
 # OS / editors
 .DS_Store
diff --git a/biome.json b/biome.json
index 45a246f..7fe3d18 100644
--- a/biome.json
+++ b/biome.json
@@ -9,6 +9,8 @@
       "!**/.rslib",
       "!**/out",
       "!**/site",
+      "!**/docs/assets",
+      "!**/.cache",
       "!**/*.css",
       "!**/presets/generated.ts"
     ]
diff --git a/core/rslib.config.ts b/core/rslib.config.ts
index f383ca9..392eebf 100644
--- a/core/rslib.config.ts
+++ b/core/rslib.config.ts
@@ -7,6 +7,7 @@ export default defineConfig({
       bundle: false,
       dts: true,
       source: {
+        // Sources only (`tests/` lives outside; do not put `*.test.ts` under src/).
         entry: { index: "./src/**" },
       },
       output: {
diff --git a/core/src/annotations.ts b/core/src/annotations.ts
index 3c39fb5..f1def97 100644
--- a/core/src/annotations.ts
+++ b/core/src/annotations.ts
@@ -1,46 +1,41 @@
 /**
- * Chart annotations — matplotlib-style artists drawn in **screen space**.
+ * Chart annotations as **Vega-Lite layers** (not a separate overlay).
  *
- * Vega-Lite has no `annotate` / `arrowstyle='|-|'`. Geometry that must stay
- * visually perpendicular (log axes, non-square panels) is computed at render
- * time from Vega's scale functions, not pre-baked into VL layers.
+ * Vega-Lite has no `annotate` / `arrowstyle='|-|'` and no official plugin
+ * system for annotations (research prototypes only). We expand a small
+ * molplot extension (`annotations: [...]`) into ordinary `rule` / `text`
+ * layers so they live in the VL scenegraph and **pan/zoom with the chart**.
  *
- * - {@link scaleBar}: complete `|———|` (spine + both caps + label)
- * - {@link arrow}: shaft + tip + optional label
- *
- * Put an `annotations` array on the RawChart / fence payload. RawChart strips
- * it before embed and paints an SVG overlay after layout / on pan-zoom.
+ * Caps are axis-aligned ticks in data space (VL-native). Perfect screen-space
+ * right angles on log axes would need post-layout pixel math and an overlay
+ * that is hard to keep in sync with `bind: scales`.
  */
 
+import type { VegaLiteSpec } from "./specs";
+
 export type ScaleBarAnnotation = {
   kind: "scaleBar";
-  /** Start in data coordinates (on the curve for `along`). */
+  /** Start (data coords). For `along`, a point on the curve. */
   x: number;
   y: number;
-  /** End in data coordinates (with `x2`/`y2` → along-curve bar). */
   x2?: number;
   y2?: number;
-  /** Axis-aligned length when only one end is given. */
   length?: number;
   label?: string;
   color?: string;
-  /** Stroke width in CSS px. Default 1.8. */
   strokeWidth?: number;
   /**
-   * `along` (default when both ends set): bar parallel to (x,y)→(x2,y2).
-   * `horizontal` / `vertical`: axis-aligned size bar.
+   * `along` — chord (x,y)→(x2,y2), optionally shifted in data space.
+   * `horizontal` / `vertical` — axis-aligned size bar.
    */
   orientation?: "horizontal" | "vertical" | "along";
   /**
-   * Screen-space offset of an `along` bar from the chord, as a fraction of
-   * the shorter plot side (default 0.05). Keeps the bar off the curve.
+   * Multiplicative y-shift for `along` bars (default 1.4) so the bar sits
+   * above the curve on log–y plots without leaving the VL scenegraph.
    */
-  offset?: number;
-  /**
-   * End-cap half-length in screen px (default 8).
-   */
-  capSize?: number;
-  /** Label font size in px (default 14). */
+  yOffset?: number;
+  /** End-cap half-length as a fraction of local y (log-friendly). Default 0.25. */
+  capFrac?: number;
   fontSize?: number;
 };
 
@@ -53,48 +48,37 @@ export type ArrowAnnotation = {
   label?: string;
   color?: string;
   strokeWidth?: number;
-  /** Tip size in px (default 8). */
-  tipSize?: number;
   fontSize?: number;
 };
 
 export type Annotation = ScaleBarAnnotation | ArrowAnnotation;
 
-/** Factory: one complete `|———|`. */
 export function scaleBar(
   partial: Omit<ScaleBarAnnotation, "kind">,
 ): ScaleBarAnnotation {
   const hasEnds = partial.x2 != null && partial.y2 != null;
   return {
     color: "#18432b",
-    strokeWidth: 1.8,
+    strokeWidth: 2,
     orientation: hasEnds ? "along" : "horizontal",
-    offset: 0.05,
-    capSize: 8,
+    yOffset: 1.4,
+    capFrac: 0.25,
     fontSize: 14,
     ...partial,
     kind: "scaleBar",
   };
 }
 
-/** Factory: one complete arrow. */
-export function arrow(
-  partial: Omit<ArrowAnnotation, "kind">,
-): ArrowAnnotation {
+export function arrow(partial: Omit<ArrowAnnotation, "kind">): ArrowAnnotation {
   return {
     color: "#18432b",
     strokeWidth: 1.6,
-    tipSize: 8,
     fontSize: 14,
     ...partial,
     kind: "arrow",
   };
 }
 
-/**
- * Pull top-level `annotations` off a payload (ignored by Vega-Lite).
- * Returns a clean VL-shaped object plus the annotation list.
- */
 export function takeAnnotations(spec: Record<string, unknown>): {
   spec: Record<string, unknown>;
   annotations: Annotation[];
@@ -102,7 +86,7 @@ export function takeAnnotations(spec: Record<string, unknown>): {
   const raw = spec.annotations;
   if (!Array.isArray(raw) || raw.length === 0) {
     if ("annotations" in spec) {
-      const { annotations: _drop, ...rest } = spec;
+      const { annotations: _d, ...rest } = spec;
       return { spec: rest, annotations: [] };
     }
     return { spec, annotations: [] };
@@ -114,227 +98,288 @@ export function takeAnnotations(spec: Record<string, unknown>): {
       ((a as Annotation).kind === "scaleBar" ||
         (a as Annotation).kind === "arrow"),
   );
-  const { annotations: _drop, ...rest } = spec;
+  const { annotations: _d, ...rest } = spec;
   return { spec: rest, annotations };
 }
 
-/** Minimal view surface needed to project data → SVG pixels. */
-export interface AnnotationView {
-  /** Vega scale: data value → plot-local pixel. */
-  scale(name: string): ((v: number) => number) | undefined;
-  /** Top-left of the plot rectangle inside the SVG. */
-  origin(): number[];
-  signal(name: string): unknown;
-}
-
-const SVG_NS = "http://www.w3.org/2000/svg";
-const OVERLAY_ATTR = "data-molplot-annotations";
-
-function lineEl(
-  x1: number,
-  y1: number,
-  x2: number,
-  y2: number,
-  color: string,
-  width: number,
-): SVGLineElement {
-  const el = document.createElementNS(SVG_NS, "line");
-  el.setAttribute("x1", String(x1));
-  el.setAttribute("y1", String(y1));
-  el.setAttribute("x2", String(x2));
-  el.setAttribute("y2", String(y2));
-  el.setAttribute("stroke", color);
-  el.setAttribute("stroke-width", String(width));
-  el.setAttribute("stroke-linecap", "butt");
-  return el;
-}
-
-function textEl(
-  x: number,
-  y: number,
-  text: string,
-  color: string,
-  fontSize: number,
-): SVGTextElement {
-  const el = document.createElementNS(SVG_NS, "text");
-  el.setAttribute("x", String(x));
-  el.setAttribute("y", String(y));
-  el.setAttribute("fill", color);
-  el.setAttribute("font-size", String(fontSize));
-  el.setAttribute(
-    "font-family",
-    "Times New Roman, Times, STIX Two Text, STIXGeneral, serif",
-  );
-  el.setAttribute("font-style", "normal");
-  el.setAttribute("text-anchor", "middle");
-  el.setAttribute("dominant-baseline", "middle");
-  el.textContent = text;
-  return el;
+function clean(layer: Record<string, unknown>): VegaLiteSpec {
+  for (const k of Object.keys(layer)) {
+    if (layer[k] === undefined) delete layer[k];
+  }
+  return layer as VegaLiteSpec;
 }
 
 /**
- * Paint annotations into `svg` using the live Vega scales (screen-correct).
- * Idempotent: replaces any previous overlay group. `pointer-events: none`
- * so pan/zoom on the plot still works.
+ * Expand annotations into VL layers (rule / text). These join the chart
+ * scenegraph so pan/zoom applies automatically.
  */
-export function drawAnnotations(
-  svg: SVGSVGElement,
-  view: AnnotationView,
-  annotations: Annotation[],
-): void {
-  svg.querySelector(`[${OVERLAY_ATTR}]`)?.remove();
-  if (!annotations.length) return;
-
-  const xScale = view.scale("x");
-  const yScale = view.scale("y");
-  if (!xScale || !yScale) return;
-
-  const [ox, oy] = view.origin();
-  const width = Number(view.signal("width")) || 0;
-  const height = Number(view.signal("height")) || 0;
-  if (width <= 0 || height <= 0) return;
-
-  const toPx = (x: number, y: number): [number, number] => [
-    ox + xScale(x),
-    oy + yScale(y),
-  ];
-
-  const g = document.createElementNS(SVG_NS, "g");
-  g.setAttribute(OVERLAY_ATTR, "");
-  g.setAttribute("style", "pointer-events: none");
-
+export function annotationLayers(annotations: Annotation[]): VegaLiteSpec[] {
+  const out: VegaLiteSpec[] = [];
   for (const a of annotations) {
-    if (a.kind === "scaleBar") drawScaleBar(g, a, toPx, width, height);
-    else if (a.kind === "arrow") drawArrow(g, a, toPx);
+    if (a.kind === "scaleBar") out.push(...scaleBarLayers(a));
+    else if (a.kind === "arrow") out.push(...arrowLayers(a));
   }
+  return out;
+}
+
+/** Merge annotation layers into a unit or layered VL spec. */
+export function withAnnotations(
+  spec: VegaLiteSpec,
+  annotations: Annotation[] | undefined | null,
+): VegaLiteSpec {
+  if (!annotations?.length) return spec;
+  const extra = annotationLayers(annotations);
+  if (!extra.length) return spec;
 
-  svg.appendChild(g);
+  if (Array.isArray(spec.layer)) {
+    return { ...spec, layer: [...(spec.layer as VegaLiteSpec[]), ...extra] };
+  }
+  if (spec.mark !== undefined || spec.encoding !== undefined) {
+    const { mark, encoding, data, transform, params, ...rest } = spec as Record<
+      string,
+      unknown
+    >;
+    const base: VegaLiteSpec = {};
+    if (data !== undefined) base.data = data;
+    if (mark !== undefined) base.mark = mark;
+    if (encoding !== undefined) base.encoding = encoding;
+    if (transform !== undefined) base.transform = transform;
+    if (params !== undefined) base.params = params;
+    return { ...rest, layer: [base, ...extra] } as VegaLiteSpec;
+  }
+  return { ...spec, layer: extra };
 }
 
-function drawScaleBar(
-  g: SVGGElement,
-  a: ScaleBarAnnotation,
-  toPx: (x: number, y: number) => [number, number],
-  plotW: number,
-  plotH: number,
-): void {
+function scaleBarLayers(a: ScaleBarAnnotation): VegaLiteSpec[] {
   const color = a.color ?? "#18432b";
-  const sw = a.strokeWidth ?? 1.8;
-  const capHalf = a.capSize ?? 8;
+  const sw = a.strokeWidth ?? 2;
   const fontSize = a.fontSize ?? 14;
   const orient =
-    a.orientation ??
-    (a.x2 != null && a.y2 != null ? "along" : "horizontal");
-
-  let x0 = a.x;
-  let y0 = a.y;
-  let x1: number;
-  let y1: number;
+    a.orientation ?? (a.x2 != null && a.y2 != null ? "along" : "horizontal");
+  const layers: VegaLiteSpec[] = [];
+  const q = { type: "quantitative" as const };
 
   if (orient === "along" && a.x2 != null && a.y2 != null) {
-    x1 = a.x2;
-    y1 = a.y2;
-  } else if (orient === "vertical") {
-    x1 = a.x;
-    y1 = a.y2 ?? a.y + (a.length ?? 0);
-  } else {
-    x1 = a.x2 ?? a.x + (a.length ?? 0);
-    y1 = a.y;
-  }
-
-  let [px0, py0] = toPx(x0, y0);
-  let [px1, py1] = toPx(x1, y1);
+    // Lift the whole bar above the curve in data y (works on linear & log-y).
+    const yMul = a.yOffset ?? 1.4;
+    const x0 = a.x;
+    const x1 = a.x2;
+    const y0 = a.y * yMul;
+    const y1 = a.y2 * yMul;
+    const capFrac = a.capFrac ?? 0.25;
+    // Vertical caps in data space (VL-native; pan/zoom with scales).
+    const c0lo = y0 / (1 + capFrac);
+    const c0hi = y0 * (1 + capFrac);
+    const c1lo = y1 / (1 + capFrac);
+    const c1hi = y1 * (1 + capFrac);
+    const midX = Math.sqrt(x0 * x1); // geometric mid for log-x
+    const midY = Math.sqrt(y0 * y1) * (1 + capFrac * 0.5);
 
-  // Screen-space direction along the bar
-  let dx = px1 - px0;
-  let dy = py1 - py0;
-  const len = Math.hypot(dx, dy) || 1;
-  const tx = dx / len;
-  const ty = dy / len;
-  // Screen-space normal (rotate 90°)
-  let nx = -ty;
-  let ny = tx;
-  // Prefer normal that points "up" on screen (smaller y in SVG)
-  if (ny > 0) {
-    nx = -nx;
-    ny = -ny;
+    layers.push(
+      clean({
+        data: { values: [{ x: x0, y: y0, x2: x1, y2: y1 }] },
+        mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
+        encoding: {
+          x: { field: "x", ...q },
+          y: { field: "y", ...q },
+          x2: { field: "x2" },
+          y2: { field: "y2" },
+        },
+      }),
+      clean({
+        data: {
+          values: [
+            { x: x0, y: c0lo, y2: c0hi },
+            { x: x1, y: c1lo, y2: c1hi },
+          ],
+        },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", ...q },
+          y: { field: "y", ...q },
+          y2: { field: "y2" },
+        },
+      }),
+    );
+    if (a.label) {
+      layers.push(
+        clean({
+          data: { values: [{ x: midX, y: midY, label: a.label }] },
+          mark: {
+            type: "text",
+            fontSize,
+            font: "Times New Roman, Times, STIX Two Text, serif",
+            fontStyle: "normal",
+            color,
+            align: "center",
+            baseline: "bottom",
+          },
+          encoding: {
+            x: { field: "x", ...q },
+            y: { field: "y", ...q },
+            text: { field: "label", type: "nominal" },
+          },
+        }),
+      );
+    }
+    return layers;
   }
 
-  if (orient === "along") {
-    const offsetPx =
-      (a.offset ?? 0.05) * Math.min(plotW, plotH);
-    px0 += nx * offsetPx;
-    py0 += ny * offsetPx;
-    px1 += nx * offsetPx;
-    py1 += ny * offsetPx;
+  if (orient === "vertical") {
+    const y1 = a.y2 ?? a.y + (a.length ?? 0);
+    const mid = (a.y + y1) / 2;
+    const tick = Math.abs(y1 - a.y) * 0.08 || a.x * 0.05;
+    layers.push(
+      clean({
+        data: { values: [{ x: a.x, y: a.y, y2: y1 }] },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", ...q },
+          y: { field: "y", ...q },
+          y2: { field: "y2" },
+        },
+      }),
+      clean({
+        data: {
+          values: [
+            { x: a.x - tick, x2: a.x + tick, y: a.y },
+            { x: a.x - tick, x2: a.x + tick, y: y1 },
+          ],
+        },
+        mark: { type: "rule", strokeWidth: sw, color },
+        encoding: {
+          x: { field: "x", ...q },
+          x2: { field: "x2" },
+          y: { field: "y", ...q },
+        },
+      }),
+    );
+    if (a.label) {
+      layers.push(
+        clean({
+          data: { values: [{ x: a.x, y: mid, label: a.label }] },
+          mark: {
+            type: "text",
+            dx: 10,
+            fontSize,
+            font: "Times New Roman, Times, serif",
+            color,
+            align: "left",
+            baseline: "middle",
+          },
+          encoding: {
+            x: { field: "x", ...q },
+            y: { field: "y", ...q },
+            text: { field: "label", type: "nominal" },
+          },
+        }),
+      );
+    }
+    return layers;
   }
 
-  // Spine
-  g.appendChild(lineEl(px0, py0, px1, py1, color, sw));
-  // Caps ⊥ spine in screen space
-  g.appendChild(
-    lineEl(
-      px0 + nx * capHalf,
-      py0 + ny * capHalf,
-      px0 - nx * capHalf,
-      py0 - ny * capHalf,
-      color,
-      sw,
-    ),
-  );
-  g.appendChild(
-    lineEl(
-      px1 + nx * capHalf,
-      py1 + ny * capHalf,
-      px1 - nx * capHalf,
-      py1 - ny * capHalf,
-      color,
-      sw,
-    ),
+  // horizontal
+  const x1 = a.x2 ?? a.x + (a.length ?? 0);
+  const mid = (a.x + x1) / 2;
+  const capFrac = a.capFrac ?? 0.25;
+  const yLo = a.y / (1 + capFrac);
+  const yHi = a.y * (1 + capFrac);
+  layers.push(
+    clean({
+      data: { values: [{ x: a.x, x2: x1, y: a.y }] },
+      mark: { type: "rule", strokeWidth: sw, color, strokeCap: "butt" },
+      encoding: {
+        x: { field: "x", ...q },
+        x2: { field: "x2" },
+        y: { field: "y", ...q },
+      },
+    }),
+    clean({
+      data: {
+        values: [
+          { x: a.x, y: yLo, y2: yHi },
+          { x: x1, y: yLo, y2: yHi },
+        ],
+      },
+      mark: { type: "rule", strokeWidth: sw, color },
+      encoding: {
+        x: { field: "x", ...q },
+        y: { field: "y", ...q },
+        y2: { field: "y2" },
+      },
+    }),
   );
-
   if (a.label) {
-    const mx = (px0 + px1) / 2 + nx * (capHalf + fontSize * 0.7);
-    const my = (py0 + py1) / 2 + ny * (capHalf + fontSize * 0.7);
-    g.appendChild(textEl(mx, my, a.label, color, fontSize));
+    layers.push(
+      clean({
+        data: { values: [{ x: mid, y: yHi, label: a.label }] },
+        mark: {
+          type: "text",
+          dy: -4,
+          fontSize,
+          font: "Times New Roman, Times, serif",
+          color,
+          align: "center",
+          baseline: "bottom",
+        },
+        encoding: {
+          x: { field: "x", ...q },
+          y: { field: "y", ...q },
+          text: { field: "label", type: "nominal" },
+        },
+      }),
+    );
   }
+  return layers;
 }
 
-function drawArrow(
-  g: SVGGElement,
-  a: ArrowAnnotation,
-  toPx: (x: number, y: number) => [number, number],
-): void {
+function arrowLayers(a: ArrowAnnotation): VegaLiteSpec[] {
   const color = a.color ?? "#18432b";
   const sw = a.strokeWidth ?? 1.6;
-  const tip = a.tipSize ?? 8;
-  const [px0, py0] = toPx(a.x, a.y);
-  const [px1, py1] = toPx(a.x2, a.y2);
-  g.appendChild(lineEl(px0, py0, px1, py1, color, sw));
-
-  const dx = px1 - px0;
-  const dy = py1 - py0;
-  const len = Math.hypot(dx, dy) || 1;
-  const ux = dx / len;
-  const uy = dy / len;
-  // Arrowhead as two short lines
-  const hx = -ux * tip + -uy * tip * 0.5;
-  const hy = -uy * tip + ux * tip * 0.5;
-  const hx2 = -ux * tip + uy * tip * 0.5;
-  const hy2 = -uy * tip + -ux * tip * 0.5;
-  g.appendChild(lineEl(px1, py1, px1 + hx, py1 + hy, color, sw));
-  g.appendChild(lineEl(px1, py1, px1 + hx2, py1 + hy2, color, sw));
-
+  const fontSize = a.fontSize ?? 14;
+  const q = { type: "quantitative" as const };
+  const layers: VegaLiteSpec[] = [
+    clean({
+      data: {
+        values: [{ x: a.x, y: a.y, x2: a.x2, y2: a.y2 }],
+      },
+      mark: { type: "rule", strokeWidth: sw, color, strokeCap: "round" },
+      encoding: {
+        x: { field: "x", ...q },
+        y: { field: "y", ...q },
+        x2: { field: "x2" },
+        y2: { field: "y2" },
+      },
+    }),
+  ];
   if (a.label) {
-    const fontSize = a.fontSize ?? 14;
-    g.appendChild(
-      textEl(
-        (px0 + px1) / 2,
-        (py0 + py1) / 2 - fontSize,
-        a.label,
-        color,
-        fontSize,
-      ),
+    layers.push(
+      clean({
+        data: {
+          values: [
+            {
+              x: (a.x + a.x2) / 2,
+              y: (a.y + a.y2) / 2,
+              label: a.label,
+            },
+          ],
+        },
+        mark: {
+          type: "text",
+          dy: -8,
+          fontSize,
+          font: "Times New Roman, Times, serif",
+          color,
+          align: "center",
+          baseline: "bottom",
+        },
+        encoding: {
+          x: { field: "x", ...q },
+          y: { field: "y", ...q },
+          text: { field: "label", type: "nominal" },
+        },
+      }),
     );
   }
+  return layers;
 }
diff --git a/core/src/chart_base.ts b/core/src/chart_base.ts
index cd1b182..d53b8b3 100644
--- a/core/src/chart_base.ts
+++ b/core/src/chart_base.ts
@@ -221,8 +221,8 @@ export abstract class VegaChart {
   }
 
   /**
-   * Hook after a successful embed (subclasses: annotation overlays, etc.).
-   * Default no-op.
+   * Hook after a successful embed. Default no-op.
+   * Annotations are VL layers (see `withAnnotations`), not a post-render overlay.
    */
   protected afterRender(_result: EmbedResult): void {}
 
diff --git a/core/src/index.ts b/core/src/index.ts
index 8f205b6..ee75dc2 100644
--- a/core/src/index.ts
+++ b/core/src/index.ts
@@ -7,10 +7,11 @@ export type {
   ScaleBarAnnotation,
 } from "./annotations";
 export {
+  annotationLayers,
   arrow,
-  drawAnnotations,
   scaleBar,
   takeAnnotations,
+  withAnnotations,
 } from "./annotations";
 export type {
   BarChartConfig,
diff --git a/core/src/raw_chart.ts b/core/src/raw_chart.ts
index 203fdc1..0dbc8a8 100644
--- a/core/src/raw_chart.ts
+++ b/core/src/raw_chart.ts
@@ -1,9 +1,5 @@
-import {
-  type Annotation,
-  drawAnnotations,
-  takeAnnotations,
-} from "./annotations";
-import { type EmbedResult, VegaChart } from "./chart_base";
+import { takeAnnotations, withAnnotations } from "./annotations";
+import { VegaChart } from "./chart_base";
 import type { PresetName } from "./preset";
 import {
   interactionParams,
@@ -14,9 +10,8 @@ import { type ChartTheme, fontScaleForWidth, vegaConfig } from "./theme";
 import type { ThemeMode } from "./types";
 
 /**
- * Escape hatch: render an arbitrary Vega-Lite spec. Optional top-level
- * `annotations` (molplot extension) are stripped before embed and painted
- * as a screen-space SVG overlay after layout / on pan-zoom.
+ * Render a Vega-Lite spec. Optional top-level `annotations` (molplot
+ * extension) expand into ordinary VL layers so they pan/zoom with the chart.
  */
 export interface RawChartConfig {
   /** A Vega-Lite top-level spec (plus optional `annotations`). */
@@ -33,7 +28,6 @@ export class RawChart extends VegaChart {
   private spec: VegaLiteSpec = {};
   private interactive = true;
   private aspectRatio = 4 / 3;
-  private annotations: Annotation[] = [];
 
   constructor(container: HTMLElement, config: RawChartConfig) {
     super(container, config.theme ?? "auto", config.preset);
@@ -46,11 +40,7 @@ export class RawChart extends VegaChart {
   }
 
   private applyConfig(config: RawChartConfig): void {
-    const taken = takeAnnotations({
-      ...((config.spec ?? {}) as Record<string, unknown>),
-    });
-    this.spec = taken.spec as VegaLiteSpec;
-    this.annotations = taken.annotations;
+    this.spec = (config.spec ?? {}) as VegaLiteSpec;
     this.interactive = config.interactive ?? true;
     this.aspectRatio = config.aspectRatio ?? 4 / 3;
   }
@@ -67,40 +57,15 @@ export class RawChart extends VegaChart {
     return super.resizeChanged(previous, next);
   }
 
-  /** Paint scale bars / arrows after embed and whenever scales move. */
-  protected afterRender(result: EmbedResult): void {
-    this.paintAnnotations(result);
-    // Redraw overlay when the user pans/zooms (scales change).
-    const view = result.view;
-    const redraw = (): void => {
-      requestAnimationFrame(() => this.paintAnnotations(result));
-    };
-    view.addEventListener("wheel", redraw);
-    view.addEventListener("mousedown", () => {
-      const move = (): void => redraw();
-      const up = (): void => {
-        window.removeEventListener("mousemove", move);
-        window.removeEventListener("mouseup", up);
-        redraw();
-      };
-      window.addEventListener("mousemove", move);
-      window.addEventListener("mouseup", up);
-    });
-    view.addEventListener("dblclick", redraw);
-  }
-
-  private paintAnnotations(result: EmbedResult): void {
-    if (!this.annotations.length) return;
-    const svg = this.container.querySelector("svg");
-    if (!svg) return;
-    drawAnnotations(svg, result.view, this.annotations);
-  }
-
   protected buildSpec(
     theme: ChartTheme,
     sizeHint: { width: number; height: number },
   ): VegaLiteSpec {
-    const spec = { ...(this.spec ?? {}) } as VegaLiteSpec;
+    // Expand annotations → VL layers (scenegraph), then inject zoom params.
+    const taken = takeAnnotations({
+      ...((this.spec ?? {}) as Record<string, unknown>),
+    });
+    const spec = withAnnotations(taken.spec as VegaLiteSpec, taken.annotations);
     const channels = this.interactive ? continuousChannels(spec) : [];
     const derivedHeight = Math.max(
       1,
@@ -135,21 +100,13 @@ export class RawChart extends VegaChart {
     const layers = Array.isArray(spec.layer)
       ? (spec.layer as Record<string, unknown>[])
       : null;
-    const topEncoding =
-      spec.encoding && typeof spec.encoding === "object"
-        ? (spec.encoding as Record<string, unknown>)
-        : null;
-
-    // Shared top-level encoding (docs layered charts): bind:scales must be
-    // top-level or pan/zoom never attaches to the shared axes.
-    if (layers && layers.length > 0 && topEncoding) {
-      return {
-        ...base,
-        params: mergeZoomParams(spec.params, zoom),
-      };
-    }
 
-    // Encoding only on unit layers: params live on the first unit layer.
+    // Layered charts (incl. annotation rule/text layers): put zoom params on
+    // the first unit layer only. Top-level `params` + multiple layers makes
+    // Vega-Lite emit duplicate selection signals (`zoomX_x`, …); vega.parse
+    // then throws and the whole chart fails to render. Layer-0 params still
+    // bind shared x/y scales (domainRaw), so pan/zoom and annotation layers
+    // move together.
     if (layers && layers.length > 0) {
       const nextLayers = layers.map((layer, i) => {
         if (i !== 0) return layer;
diff --git a/core/tests/annotations.test.ts b/core/tests/annotations.test.ts
index e86f25c..fbe924c 100644
--- a/core/tests/annotations.test.ts
+++ b/core/tests/annotations.test.ts
@@ -1,35 +1,121 @@
 import { describe, expect, it } from "@rstest/core";
 import {
+  annotationLayers,
   scaleBar,
   takeAnnotations,
-  type Annotation,
+  withAnnotations,
 } from "../src/annotations";
 
 describe("annotations", () => {
-  it("scaleBar factory defaults to along when both ends are set", () => {
-    const a = scaleBar({
-      x: 0.18,
-      y: 0.03,
-      x2: 0.65,
-      y2: 0.42,
-      label: "ballistic",
-    });
-    expect(a.kind).toBe("scaleBar");
-    expect(a.orientation).toBe("along");
-    expect(a.offset).toBe(0.05);
-    expect(a.capSize).toBe(8);
+  it("scaleBar expands to VL rule + cap + label layers", () => {
+    const layers = annotationLayers([
+      scaleBar({
+        x: 0.18,
+        y: 0.03,
+        x2: 0.65,
+        y2: 0.42,
+        label: "ballistic",
+      }),
+    ]);
+    expect(layers.length).toBe(3);
+    expect((layers[0].mark as { type: string }).type).toBe("rule");
+    expect((layers[1].mark as { type: string }).type).toBe("rule");
+    expect((layers[2].mark as { type: string }).type).toBe("text");
+  });
+
+  it("withAnnotations appends layers so marks pan with the chart", () => {
+    const out = withAnnotations(
+      {
+        layer: [
+          {
+            mark: "line",
+            encoding: {
+              x: { field: "x", type: "quantitative" },
+              y: { field: "y", type: "quantitative" },
+            },
+          },
+        ],
+      },
+      [scaleBar({ x: 1, y: 1, x2: 2, y2: 2, label: "a" })],
+    );
+    expect(Array.isArray(out.layer)).toBe(true);
+    expect((out.layer as unknown[]).length).toBe(1 + 3);
   });
 
-  it("takeAnnotations strips the top-level key", () => {
+  it("takeAnnotations strips the extension key", () => {
     const { spec, annotations } = takeAnnotations({
       mark: "point",
-      annotations: [
-        { kind: "arrow", x: 0, y: 0, x2: 1, y2: 1 },
-        { kind: "nope" },
-      ],
+      annotations: [{ kind: "scaleBar", x: 0, y: 0, length: 1 }],
     });
     expect(annotations).toHaveLength(1);
-    expect((annotations[0] as Annotation).kind).toBe("arrow");
     expect("annotations" in spec).toBe(false);
   });
+
+  it("layered annotations + layer0 zoom params compile without duplicate signals", async () => {
+    // Regression: top-level params + multi-layer → VL emits duplicate
+    // zoomX_x / zoomY_y signals and vega.parse throws (chart invisible).
+    const { compile } = await import("vega-lite");
+    const { parse } = await import("vega");
+    const { interactionParams } = await import("../src/specs");
+
+    const expanded = withAnnotations(
+      {
+        encoding: {
+          x: {
+            type: "quantitative",
+            scale: { type: "log", domain: [0.1, 100] },
+          },
+          y: {
+            type: "quantitative",
+            scale: { type: "log", domain: [0.008, 120] },
+          },
+        },
+        layer: [
+          {
+            data: {
+              values: [
+                { x: 0.1, y: 0.01 },
+                { x: 1, y: 1 },
+                { x: 10, y: 10 },
+              ],
+            },
+            mark: { type: "line" },
+            encoding: { x: { field: "x" }, y: { field: "y" } },
+          },
+        ],
+      },
+      [
+        scaleBar({
+          x: 0.18,
+          y: 0.03,
+          x2: 0.65,
+          y2: 0.42,
+          label: "ballistic",
+        }),
+      ],
+    );
+    const layers = (expanded.layer as Record<string, unknown>[]).map(
+      (layer, i) =>
+        i === 0 ? { ...layer, params: interactionParams(["x", "y"]) } : layer,
+    );
+    const full = {
+      $schema: "https://vega.github.io/schema/vega-lite/v5.json",
+      width: 400,
+      height: 225,
+      encoding: expanded.encoding,
+      layer: layers,
+    };
+    const compiled = compile(full as never).spec as {
+      signals?: { name: string }[];
+      scales?: { name: string; domainRaw?: unknown }[];
+    };
+    const names = (compiled.signals ?? []).map((s) => s.name);
+    const dups = names.filter((n, i) => names.indexOf(n) !== i);
+    expect(dups).toEqual([]);
+    expect(
+      compiled.scales?.find((s) => s.name === "x")?.domainRaw,
+    ).toBeTruthy();
+    // Must parse: this is what vega-embed does.
+    expect(() => parse(compiled as never)).not.toThrow();
+  });
 });
diff --git a/core/tests/element.test.ts b/core/tests/element.test.ts
index 3ae9442..f99c185 100644
--- a/core/tests/element.test.ts
+++ b/core/tests/element.test.ts
@@ -261,8 +261,9 @@ describe("RawChart (the element's renderer)", () => {
       },
     });
     await chart.ready();
-    const layers = (fake.specs[0] as { layer: { params?: { name: string }[] }[] })
-      .layer;
+    const layers = (
+      fake.specs[0] as { layer: { params?: { name: string }[] }[] }
+    ).layer;
     expect(layers[0].params?.map((p) => p.name)).toEqual(["zoomX", "zoomY"]);
     expect((fake.specs[0] as { params?: unknown }).params).toBeUndefined();
     chart.dispose();
diff --git a/core/src/raw_chart.interactive.test.ts b/core/tests/raw_chart.interactive.test.ts
similarity index 78%
rename from core/src/raw_chart.interactive.test.ts
rename to core/tests/raw_chart.interactive.test.ts
index c96d5dc..fdf3138 100644
--- a/core/src/raw_chart.interactive.test.ts
+++ b/core/tests/raw_chart.interactive.test.ts
@@ -3,7 +3,7 @@
  */
 
 import { describe, expect, it } from "@rstest/core";
-import { interactionParams } from "./specs";
+import { interactionParams } from "../src/specs";
 
 type ZoomChannel = "x" | "y";
 
@@ -45,13 +45,14 @@ function mergeZoomParams(
 }
 
 /** Where zoom params should be placed for a given spec shape. */
-function zoomPlacement(spec: Record<string, unknown>): "top" | "layer0" | "none" {
+function zoomPlacement(
+  spec: Record<string, unknown>,
+): "top" | "layer0" | "none" {
   const channels = continuousChannels(spec);
   if (channels.length === 0) return "none";
   const layers = Array.isArray(spec.layer) ? spec.layer : null;
-  const topEncoding =
-    spec.encoding && typeof spec.encoding === "object" ? spec.encoding : null;
-  if (layers && layers.length > 0 && topEncoding) return "top";
+  // Multi-layer always uses layer0 — top-level params duplicate VL selection
+  // signals when annotation (or any extra) layers are present.
   if (layers && layers.length > 0) return "layer0";
   return "top";
 }
@@ -89,7 +90,7 @@ describe("RawChart interactive injection", () => {
     expect(channels).toEqual(["x", "y"]);
   });
 
-  it("places zoom params at top when encoding is shared on a layered chart", () => {
+  it("places zoom params on layer0 when encoding is shared on a layered chart", () => {
     expect(
       zoomPlacement({
         encoding: {
@@ -98,7 +99,7 @@ describe("RawChart interactive injection", () => {
         },
         layer: [{ encoding: { x: { field: "x" }, y: { field: "y" } } }],
       }),
-    ).toBe("top");
+    ).toBe("layer0");
   });
 
   it("places zoom params on layer0 when only unit layers have encoding", () => {
@@ -116,6 +117,27 @@ describe("RawChart interactive injection", () => {
     ).toBe("layer0");
   });
 
+  it("places zoom params on layer0 when annotation layers are present", () => {
+    expect(
+      zoomPlacement({
+        encoding: {
+          x: { type: "quantitative" },
+          y: { type: "quantitative" },
+        },
+        layer: [
+          { encoding: { x: { field: "x" }, y: { field: "y" } } },
+          {
+            mark: "rule",
+            encoding: {
+              x: { field: "x", type: "quantitative" },
+              y: { field: "y", type: "quantitative" },
+            },
+          },
+        ],
+      }),
+    ).toBe("layer0");
+  });
+
   it("merges zoom params over empty params:[]", () => {
     const zoom = interactionParams(["x", "y"]);
     const merged = mergeZoomParams([], zoom);

From 58c14808f7903d07081082c8325be0524d428e37 Mon Sep 17 00:00:00 2001
From: Roy Kid <lijichen365@gmail.com>
Date: Wed, 5 Aug 2026 22:12:21 +0200
Subject: [PATCH 17/17] release: v0.1.4

Annotations as pure Vega-Lite layers (scaleBar/arrow); zoom params on
layer[0] so multi-layer charts parse without duplicate signals. Docs
pan/zoom with regime markers.
---
 package.json | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/package.json b/package.json
index c2452b1..685bfb6 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "molplot",
-  "version": "0.1.3",
+  "version": "0.1.4",
   "description": "MolPlot \u2014 Vega-Lite scientific charting with a unified, matplotlib-portable preset",
   "author": "Roy Kid",
   "license": "BSD-3-Clause",