codefig 0.17.0__py3-none-any.whl

codefig/charts.py

@@ -0,0 +1,1806 @@
+"""Embedded mini charts drawn by codefig itself (v0.7.0) — no matplotlib.
+
+* :class:`StackedBarChart` — one or more stacked bars (vertical or horizontal), segment
+  names beside the last bar (``labels="side"``), as a swatch key (``"legend"``) or
+  inside the segments (``"inside"``); optional value axis.
+* :class:`LineChart` — one or more series with optional markers, axes, a few ticks and
+  end-of-line series labels (no legend box needed).
+* :class:`GroupedBarChart` (v0.8.0) — clustered bars per category, swatch legend.
+* :class:`Sparkline` — a tiny axis-free line (``LineChart`` preset) for inline trends.
+
+v0.8.0: ``yscale="log"`` / ``xscale="log"`` axes (:class:`Scale`), light ``grid=``
+lines (``theme.grid_color``), ``errors=`` bars (symmetric or ``(minus, plus)``).
+
+All text uses the theme's size roles (ticks / labels = ``theme.small_size``, never below
+the paper theme's 6 pt) and colours come from the theme palette / accents, so a chart
+inside a figure passes ``fig.lint()`` like any other node. Sizes are theme lengths;
+``width`` / ``height`` override the plot area.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Mapping, Optional, Sequence, Tuple, Union
+
+from .node import Node
+from .styles import themed
+from .textutil import measure_text
+
+Number = Union[int, float]
+
+
+def _nice_ticks(lo: float, hi: float, n: int = 3) -> List[float]:
+    """About ``n`` round tick values covering [lo, hi]."""
+    if hi <= lo:
+        return [lo]
+    raw = (hi - lo) / max(1, n - 1)
+    mag = 10 ** math.floor(math.log10(raw))
+    step = min((m * mag for m in (1, 2, 2.5, 5, 10) if m * mag >= raw), default=raw)
+    t0 = math.floor(lo / step + 1e-9) * step
+    out = []
+    v = t0
+    while v <= hi + step * 1e-6:
+        if v >= lo - step * 1e-6:
+            out.append(round(v, 10))
+        v += step
+    return out
+
+
+def _tick_n(length: float, fs: float, vertical: bool = True, label_w: float = 0.0,
+            lo: int = 3, hi: int = 5) -> int:
+    """v0.9.0: how many nice ticks (≈ ``lo``..``hi``) fit along an axis of ``length``:
+    vertical axes need ~2.2 font heights per tick, horizontal ones the label width plus
+    1.5 font sizes."""
+    need = fs * 2.2 if vertical else label_w + fs * 1.5
+    n = lo
+    for k in range(lo, hi + 1):
+        if length / (k - 1) >= need:
+            n = k
+    return n
+
+
+def _nice_hi(lo: float, hi: float, n: int = 3) -> float:
+    """v0.9.0: the first nice tick at or above ``hi`` (so a value axis ends on a
+    labelled tick instead of stopping just past the last one)."""
+    if hi <= lo:
+        return hi
+    raw = (hi - lo) / max(1, n - 1)
+    mag = 10 ** math.floor(math.log10(raw))
+    step = min((m * mag for m in (1, 2, 2.5, 5, 10) if m * mag >= raw), default=raw)
+    return round(math.ceil(hi / step - 1e-9) * step, 10)
+
+
+def _fmt(v: float) -> str:
+    if abs(v - round(v)) < 1e-9:
+        return f"{int(round(v))}"
+    return f"{v:g}"
+
+
+def _spread(centres: List[float], h: float, lo: float, hi: float) -> List[float]:
+    """Push label centres apart to at least ``h`` (keeps order, stays in [lo, hi])."""
+    if not centres:
+        return []
+    order = sorted(range(len(centres)), key=lambda i: centres[i])
+    ys = [centres[i] for i in order]
+    for k in range(1, len(ys)):
+        ys[k] = max(ys[k], ys[k - 1] + h)
+    over = ys[-1] - hi
+    if over > 0:
+        ys = [y - over for y in ys]
+        for k in range(len(ys) - 2, -1, -1):
+            ys[k] = min(ys[k], ys[k + 1] - h)
+    out = [0.0] * len(ys)
+    for k, i in enumerate(order):
+        out[i] = max(lo, ys[k]) if k == 0 else ys[k]
+    return out
+
+
+def _nice_range(lo: float, hi: float, n: int = 3) -> Tuple[float, float, float]:
+    """v0.10.0: round ``[lo, hi]`` outwards to a common nice step with at most ``n - 1``
+    intervals (both ends on labelled ticks) → (lo, hi, step)."""
+    if hi <= lo:
+        return lo, hi, 1.0
+    raw = (hi - lo) / max(1, n - 1)
+    mag = 10 ** math.floor(math.log10(raw))
+    for e in (mag / 10, mag, mag * 10, mag * 100):
+        for m in (1, 2, 2.5, 5):
+            st = m * e
+            a = math.floor(lo / st + 1e-9) * st
+            b = math.ceil(hi / st - 1e-9) * st
+            if round((b - a) / st) <= max(1, n - 1):
+                return round(a, 10), round(b, 10), st
+    return lo, hi, raw
+
+
+def _fmt_values(values: Sequence[float], log: bool = False) -> List[str]:
+    """v0.9.0: value labels with one shared number of decimals (≤ 2), so 66 and 61.2
+    print as 66.0 and 61.2 next to each other."""
+    if log:
+        return [_fmt_si(v) for v in values]
+    d = 0
+    for v in values:
+        for k in range(3):
+            if abs(v * 10 ** k - round(v * 10 ** k)) < 1e-6:
+                d = max(d, k)
+                break
+        else:
+            d = 2
+    return [f"{v:.{d}f}" for v in values]
+
+
+def _fmt_si(v: float) -> str:
+    """Compact tick text for log axes: 0.01, 1, 10, 1k, 10k, 1M, 1G."""
+    for div, suf in ((1e9, "G"), (1e6, "M"), (1e3, "k")):
+        if abs(v) >= div:
+            return _fmt(round(v / div, 6)) + suf
+    return _fmt(round(v, 10))
+
+
+def _125(v: float, down: bool) -> float:
+    """Nearest 1, 2 or 5 × 10^k at or below (``down``) / above ``v`` (> 0)."""
+    e = math.floor(math.log10(v) + 1e-9)
+    cands = [m * 10.0 ** k for k in (e - 1, e, e + 1) for m in (1, 2, 5)]
+    if down:
+        return max(c for c in cands if c <= v * (1 + 1e-9))
+    return min(c for c in cands if c >= v * (1 - 1e-9))
+
+
+class Scale:
+    """Value → [0, 1] mapping for chart axes: ``kind="linear"`` or ``"log"`` (base 10).
+
+    Linear ranges are extended to round ticks; log ranges to whole decades. ``ticks()``
+    gives about ``n`` round values (decades on log axes; 1-2-5 steps inside one decade).
+    """
+
+    def __init__(self, lo: float, hi: float, kind: str = "linear", *, nice: bool = True,
+                 n: int = 3, fixed_lo: bool = False, fixed_hi: bool = False) -> None:
+        if kind not in ("linear", "log"):
+            raise ValueError("scale must be 'linear' or 'log'")
+        self.kind, self.n = kind, n
+        self.step: Optional[float] = None
+        if kind == "log":
+            if lo <= 0 or hi <= 0:
+                raise ValueError("log scale needs positive values (set ymin= / xmin= > 0)")
+            if nice:  # snap to 1-2-5 × 10^k (not whole decades: no empty top decade)
+                lo = lo if fixed_lo else _125(lo, down=True)
+                hi = hi if fixed_hi else _125(hi, down=False)
+            if hi <= lo:
+                hi = lo * 10.0
+        else:
+            if hi <= lo:
+                hi = lo + 1.0
+            if nice and lo != 0 and not fixed_lo and not fixed_hi:
+                lo, hi, self.step = _nice_range(lo, hi, n)  # off-zero range (v0.10.0)
+            elif nice and not fixed_hi:
+                hi = max(hi, _nice_hi(lo, hi, n))
+            elif nice and lo != 0 and not fixed_lo:  # v0.12.0: fixed top, off-zero floor
+                lo2, _h, st = _nice_range(lo, hi, n)  # snap the floor to a tick
+                lo = min(lo, lo2)
+        self.lo, self.hi = float(lo), float(hi)
+
+    def norm(self, v: float) -> float:
+        if self.kind == "log":
+            v = max(v, self.lo * 1e-6)
+            return (math.log10(v) - math.log10(self.lo)) / (math.log10(self.hi) - math.log10(self.lo))
+        return (v - self.lo) / (self.hi - self.lo)
+
+    def ticks(self) -> List[float]:
+        if self.kind == "linear":
+            if self.step:
+                k = int(round((self.hi - self.lo) / self.step))
+                return [round(self.lo + i * self.step, 10) for i in range(k + 1)]
+            return _nice_ticks(self.lo, self.hi, self.n)
+        e0 = math.ceil(math.log10(self.lo) - 1e-9)
+        e1 = math.floor(math.log10(self.hi) + 1e-9)
+        dec = [10.0 ** e for e in range(e0, e1 + 1)]
+        if len(dec) >= 2:
+            step = max(1, math.ceil((len(dec) - 1) / 4))  # ≤ 5 decade ticks
+            return dec[::step]
+        out = [m * 10.0 ** e for e in range(e0 - 1, e1 + 1) for m in (1, 2, 5)]
+        return [v for v in out if self.lo * (1 - 1e-9) <= v <= self.hi * (1 + 1e-9)]
+
+    def fmt(self, v: float) -> str:
+        return _fmt_si(v) if self.kind == "log" else _fmt(v)
+
+
+def _err_pairs(errors: Any, n: int) -> List[Tuple[float, float]]:
+    """Normalise error bars: a number for all points, or one entry per point — a number
+    (symmetric), a ``(minus, plus)`` pair, or None."""
+    if errors is None:
+        return [(0.0, 0.0)] * n
+    if isinstance(errors, (int, float)):  # one symmetric error for every point
+        return [(abs(float(errors)), abs(float(errors)))] * n
+    out = []
+    for e in list(errors)[:n]:
+        if e is None:
+            out.append((0.0, 0.0))
+        elif isinstance(e, (tuple, list)):
+            if len(e) != 2:
+                raise ValueError("asymmetric error must be (minus, plus)")
+            out.append((abs(float(e[0])), abs(float(e[1]))))
+        else:
+            out.append((abs(float(e)), abs(float(e))))
+    return out + [(0.0, 0.0)] * (n - len(out))
+
+
+def _grid_axes(grid: Any, default: str = "y") -> Tuple[bool, bool]:
+    """``grid=`` False | True | "x" | "y" | "both" → (x lines, y lines)."""
+    if grid in (False, None):
+        return False, False
+    if grid is True:
+        grid = default
+    if grid not in ("x", "y", "both"):
+        raise ValueError("grid must be False, True, 'x', 'y' or 'both'")
+    return grid in ("x", "both"), grid in ("y", "both")
+
+
+def _draw_errbar(buf: List[str], x: float, y_lo: float, y_hi: float, cap: float, color: str,
+                 width: float, horizontal: bool = False) -> None:
+    """One error bar (whisker + caps). Vertical by default; ``horizontal`` swaps axes."""
+    from .render_svg import draw_line
+
+    if horizontal:
+        draw_line(buf, y_lo, x, y_hi, x, stroke=color, stroke_width=width)
+        for yy in (y_lo, y_hi):
+            draw_line(buf, yy, x - cap, yy, x + cap, stroke=color, stroke_width=width)
+        return
+    draw_line(buf, x, y_lo, x, y_hi, stroke=color, stroke_width=width)
+    for yy in (y_lo, y_hi):
+        draw_line(buf, x - cap, yy, x + cap, yy, stroke=color, stroke_width=width)
+
+
+def _ref_list(ref: Any) -> List[Tuple[float, Optional[str]]]:
+    """``ref=`` → [(value, label)]: a number, ``(value, label)`` or a list of those."""
+    if ref is None:
+        return []
+    if isinstance(ref, (int, float)):
+        return [(float(ref), None)]
+    if isinstance(ref, tuple) and len(ref) == 2 and isinstance(ref[1], (str, type(None))):
+        return [(float(ref[0]), ref[1])]
+    out: List[Tuple[float, Optional[str]]] = []
+    for r in ref:
+        out.extend(_ref_list(r))
+    return out
+
+
+def _bar_fills(spec: Any, rows: List[List[float]], cats: List[str], series: List[str],
+               colors: List[str]) -> List[List[str]]:
+    """``bar_colors=`` → a fill per (category, series); defaults to the series colour."""
+    out = [[colors[s] for s in range(len(r))] for r in rows]
+    if spec is None:
+        return out
+    if isinstance(spec, Mapping):
+        for k, col in spec.items():
+            if isinstance(k, tuple):
+                c, s_ = k
+                ci = cats.index(c) if isinstance(c, str) else int(c)
+                si = series.index(s_) if isinstance(s_, str) else int(s_)
+                out[ci][si] = col
+            else:
+                ci = cats.index(k) if isinstance(k, str) else int(k)
+                out[ci] = [col] * len(out[ci])
+        return out
+    for ci, col in enumerate(list(spec)[: len(rows)]):
+        if col is None:
+            continue
+        if isinstance(col, str):
+            out[ci] = [col] * len(out[ci])
+        else:
+            for si, cc in enumerate(list(col)[: len(out[ci])]):
+                if cc is not None:
+                    out[ci][si] = cc
+    return out
+
+
+def _gapped_line(buf: List[str], x0: float, y0: float, x1: float, y1: float,
+                 holes: Sequence[Tuple[float, float, float, float]], pad: float = 1.0,
+                 **kw: Any) -> None:
+    """v0.9.0: an axis-parallel gridline broken where it would run through a label box."""
+    from .render_svg import draw_line
+
+    horiz = abs(y0 - y1) < 1e-9
+    a, b = (min(x0, x1), max(x0, x1)) if horiz else (min(y0, y1), max(y0, y1))
+    cuts = []
+    for hx, hy, hw, hh in holes:
+        if horiz and hy - pad < y0 < hy + hh + pad:
+            cuts.append((hx - pad, hx + hw + pad))
+        elif not horiz and hx - pad < x0 < hx + hw + pad:
+            cuts.append((hy - pad, hy + hh + pad))
+    segs, cur = [], a
+    for c0, c1 in sorted(cuts):
+        if c0 > cur:
+            segs.append((cur, min(c0, b)))
+        cur = max(cur, c1)
+    if cur < b:
+        segs.append((cur, b))
+    for s0, s1 in segs:
+        if s1 - s0 > 0.3:
+            if horiz:
+                draw_line(buf, s0, y0, s1, y0, **kw)
+            else:
+                draw_line(buf, x0, s0, x0, s1, **kw)
+
+
+def _err_cap(theme: Any, floor: float = 0.0) -> float:
+    """Cap half-width for error bars: theme ``err_cap`` (≥ ``floor``)."""
+    return max(theme.L(getattr(theme, "err_cap", 2.2)), floor)
+
+
+def _rot_text(buf: List[str], theme: Any, s: str, cx: float, cy: float, fs: float) -> None:
+    from .render_svg import draw_text
+
+    sub: List[str] = []
+    draw_text(sub, s, cx + fs * 0.35, cy, font_size=fs, anchor="middle", fill=theme.text_color)
+    buf.append(f'<g transform="rotate(-90 {cx:.2f} {cy:.2f})">')
+    buf.extend(sub)
+    buf.append("</g>")
+
+
+class _Chart(Node):
+    """Shared text helpers."""
+
+    def _fs(self) -> float:
+        return float(self.font_size) if getattr(self, "font_size", None) else self.theme.small_size
+
+    def _tw(self, s: str) -> Tuple[float, float]:
+        return measure_text(s, self._fs())
+
+    def _text(self, buf: List[str], s: str, x: float, cy: float, anchor: str = "start",
+              color: Optional[str] = None) -> None:
+        from .render_svg import draw_text
+
+        fs = self._fs()
+        draw_text(buf, s, x, cy + fs * 0.35, font_size=fs, anchor=anchor,
+                  fill=color or self.theme.text_color)
+
+
+class StackedBarChart(_Chart):
+    """Stacked bars: ``StackedBarChart({"Matmul": 2, "Mask": 4, "Softmax": 4})``.
+
+    data: a mapping (one bar, segment → value), a list of mappings (one per bar), or a
+    list of value lists with ``segments=`` names.
+    categories: bar names (tick labels under / beside each bar).
+    horizontal: bars grow to the right instead of up.
+    labels: ``"side"`` (each segment named beside the last bar that contains it — bars
+    whose segments are missing from the last bar get their names in a widened gap —
+    spread so names never collide), ``"legend"`` (a swatch key column right of the plot),
+    ``"inside"`` (names inside segments that fit) or ``None``. values: print each
+    segment's value inside it when it fits.
+    axis: draw a value axis with ~3 round ticks; axis_label: its title.
+    grid: light value gridlines (``True``; theme ``grid_color``).
+    errors: one error per bar on its total — a number (symmetric) or ``(minus, plus)``.
+    colors: one per segment (default: theme palette, cycled).
+    ``segment_port(bar, seg, side)`` → a port on one segment; ``bar_port(bar, side)`` → the
+    whole bar.
+    """
+
+    bar_len = themed(90.0)
+    bar_thick = themed(18.0)
+    bar_gap = themed(10.0)
+
+    def __init__(self, data: Any, *, segments: Optional[Sequence[str]] = None,
+                 categories: Optional[Sequence[str]] = None, horizontal: bool = False,
+                 labels: Optional[str] = "side", values: bool = False, axis: bool = False,
+                 axis_label: Optional[str] = None, colors: Optional[Sequence[str]] = None,
+                 max_value: Optional[float] = None, length: Optional[float] = None,
+                 thickness: Optional[float] = None, gap: Optional[float] = None,
+                 font_size: Optional[float] = None, stroke: Optional[str] = None,
+                 grid: Any = False, errors: Optional[Sequence[Any]] = None,
+                 **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        if labels not in ("side", "legend", "inside", None):
+            raise ValueError("labels must be side|legend|inside|None")
+        if isinstance(data, Mapping):
+            data = [data]
+        rows: List[List[float]] = []
+        names: List[str] = list(segments or [])
+        dup = sorted({n for n in names if names.count(n) > 1})
+        if dup:
+            raise ValueError(f"StackedBarChart segments must be unique (repeated: {dup}); "
+                             "name repeated phases apart (e.g. 'decode 1', 'decode 2') and "
+                             "share a colour with colors=[...]")
+        for d in data:
+            if isinstance(d, Mapping):
+                for k in d:
+                    if k not in names:
+                        names.append(str(k))
+        for d in data:
+            if isinstance(d, Mapping):
+                rows.append([float(d.get(k, 0.0)) for k in names])
+            else:
+                rows.append([float(v) for v in d])
+        if not rows or not any(rows):
+            raise ValueError("StackedBarChart needs at least one bar")
+        nseg = max(len(r) for r in rows)
+        self.rows = [r + [0.0] * (nseg - len(r)) for r in rows]
+        self.segments = (names + [f"s{i}" for i in range(len(names), nseg)])[:nseg]
+        self.categories = list(categories or [])
+        self.horizontal = bool(horizontal)
+        self.labels = labels
+        self.values = bool(values)
+        self.axis = bool(axis)
+        self.axis_label = axis_label
+        pal = list(colors or self.theme.palette)
+        self.colors = [pal[i % len(pal)] for i in range(nseg)]
+        self.max_value = max_value
+        self.bar_len = length
+        self.bar_thick = thickness
+        self.bar_gap = gap
+        self.font_size = font_size
+        self.stroke = stroke
+        self.grid = grid
+        _grid_axes(grid)
+        self.errors = _err_pairs(errors, len(self.rows)) if errors is not None else None
+
+    # -- geometry -------------------------------------------------------------------
+    def _vmax(self) -> float:
+        tops = [sum(r) + (self.errors[i][1] if self.errors else 0.0) for i, r in enumerate(self.rows)]
+        top = max(tops)
+        if self.max_value is not None:
+            return float(self.max_value)
+        if self.axis or self.grid:
+            return max(top, _nice_hi(0.0, top, self._tick_n()))
+        return top
+
+    def _side_hosts(self) -> Dict[int, List[int]]:
+        """bar → segments named beside it (``labels="side"``): each segment is named at the
+        last bar (vertical) / first bar (horizontal, names above) that contains it."""
+        hosts: Dict[int, List[int]] = {}
+        n = len(self.rows)
+        order = range(n - 1, -1, -1) if not self.horizontal else range(n)
+        for k in range(len(self.segments)):
+            for b in order:
+                if self.rows[b][k] > 0:
+                    hosts.setdefault(b, []).append(k)
+                    break
+        return hosts
+
+    def _side_w(self, ks: Sequence[int]) -> float:
+        return max((self._tw(self.segments[k])[0] for k in ks), default=0.0)
+
+    def _gaps(self) -> List[float]:
+        """Spacing after each bar (index b → gap between bar b and b + 1)."""
+        n = len(self.rows)
+        g = self._gap()
+        out = [g] * max(0, n - 1)
+        if self.labels == "side":
+            lg = self.theme.L(4.0)
+            fs = self._fs()
+            for b, ks in self._side_hosts().items():
+                if not self.horizontal and b < n - 1:
+                    out[b] = max(out[b], self._side_w(ks) + lg * 2.5)
+                elif self.horizontal and b > 0:
+                    out[b - 1] = max(out[b - 1], fs * 1.25 + lg)
+        return out
+
+    def _offsets(self) -> List[float]:
+        pos = self._lead()
+        offs = []
+        gaps = self._gaps()
+        for b in range(len(self.rows)):
+            offs.append(pos)
+            pos += float(self.bar_thick) + (gaps[b] if b < len(gaps) else 0.0)
+        return offs
+
+    def _tick_n(self) -> int:
+        if self.horizontal:
+            top = max(sum(r) for r in self.rows)
+            return _tick_n(float(self.bar_len), self._fs(), False, self._tw(_fmt(round(top, 1)))[0])
+        return _tick_n(float(self.bar_len), self._fs())
+
+    def _ticks(self) -> List[float]:
+        return _nice_ticks(0.0, self._vmax(), self._tick_n())
+
+    def _extents(self) -> Dict[str, float]:
+        """Margins around the plot area: left, right, top, bottom."""
+        fs = self._fs()
+        gap = self.theme.L(4.0)
+        m = {"l": 0.0, "r": 0.0, "t": 0.0, "b": 0.0}
+        cat_w = max((self._tw(c)[0] for c in self.categories), default=0.0)
+        cat_h = fs * 1.25 if self.categories else 0.0
+        if self.horizontal:
+            m["l"] = cat_w + gap if self.categories else 0.0
+        else:
+            m["b"] = cat_h + gap * 0.5 if self.categories else 0.0
+        if self.labels == "side":
+            hosts = self._side_hosts()
+            if self.horizontal:
+                if 0 in hosts:
+                    m["t"] = fs * 1.25 * 1.0 + gap * 0.5  # names above the top bar
+            elif len(self.rows) - 1 in hosts:
+                m["r"] = self._side_w(hosts[len(self.rows) - 1]) + gap * 1.5
+        if self.axis:
+            tw = max(self._tw(_fmt(t))[0] for t in self._ticks())
+            if self.horizontal:
+                m["b"] += fs * 1.25 + gap * 0.5 + (fs * 1.25 if self.axis_label else 0.0)
+            else:
+                m["l"] += tw + gap + self.theme.L(1.0) + (fs * 1.25 + gap * 0.5 if self.axis_label else 0.0)
+        if self.labels == "legend":  # swatch key as a column right of the plot
+            m["r"] += gap * 1.5 + max(it[2] for it in self._legend_items())
+        if self.errors and not self.horizontal:
+            m["t"] = max(m["t"], self.theme.L(1.0))
+        return m
+
+    def _gap(self) -> float:
+        """Bar spacing, widened so category names under vertical bars never collide."""
+        g = float(self.bar_gap)
+        if not self.horizontal and self.categories:
+            cw = max(self._tw(c)[0] for c in self.categories)
+            g = max(g, cw - float(self.bar_thick) + self.theme.L(4.0))
+        return g
+
+    def _legend_items(self) -> List[Tuple[str, str, float]]:
+        sw = self._fs()
+        return [(s, c, sw + self.theme.L(2.0) + self._tw(s)[0]) for s, c in zip(self.segments, self.colors)]
+
+    def _legend_h(self) -> float:
+        return self._fs() * 1.25 * len(self.segments)
+
+    def _lead(self) -> float:
+        """Inset of the first vertical bar so its category name clears the value axis."""
+        if self.horizontal or not self.categories or not self.axis:
+            return 0.0
+        return max(0.0, self._tw(self.categories[0])[0] / 2 - float(self.bar_thick) / 2
+                   + self.theme.L(1.0))
+
+    def _plot_size(self) -> Tuple[float, float]:
+        across = self._offsets()[-1] + float(self.bar_thick)
+        return (self.bar_len, across) if self.horizontal else (across, self.bar_len)
+
+    def _measure(self) -> Tuple[float, float]:
+        pw, ph = self._plot_size()
+        m = self._extents()
+        w = pw + m["l"] + m["r"]
+        h = ph + m["t"] + m["b"]
+        if self.labels == "legend":
+            h = max(h, self._legend_h() + m["t"])
+        if self.horizontal and self.labels == "side":
+            # segment names above a bar may extend past the plot on the right
+            w = max(w, m["l"] + self._side_label_extent())
+        return w, h
+
+    def _side_label_extent(self) -> float:
+        vmax = self._vmax() or 1.0
+        ext = 0.0
+        for b, ks in self._side_hosts().items():
+            row = self.rows[b]
+            for k in ks:
+                mid = (sum(row[:k]) + row[k] / 2) / vmax * self.bar_len
+                ext = max(ext, mid + self._tw(self.segments[k])[0] / 2)
+        return ext
+
+    def _plot_origin(self) -> Tuple[float, float, float, float]:
+        g = self.geom
+        pw, ph = self._plot_size()
+        m = self._extents()
+        mw, mh = self._measure()
+        body = ph + m["t"] + m["b"]
+        return g.x + (g.w - mw) / 2 + m["l"], g.y + (g.h - mh) / 2 + (mh - body) / 2 + m["t"], pw, ph
+
+    def segment_rect(self, bar: int, seg: int) -> Tuple[float, float, float, float]:
+        """(x, y, w, h) of one segment (layout coordinates)."""
+        px, py, pw, ph = self._plot_origin()
+        vmax = self._vmax() or 1.0
+        row = self.rows[bar]
+        a = sum(row[:seg]) / vmax * self.bar_len
+        b = sum(row[: seg + 1]) / vmax * self.bar_len
+        off = self._offsets()[bar]
+        if self.horizontal:
+            return px + a, py + off, b - a, self.bar_thick
+        base = py + ph
+        return px + off, base - b, self.bar_thick, b - a
+
+    def bar_rect(self, bar: int) -> Tuple[float, float, float, float]:
+        rs = [self.segment_rect(bar, k) for k in range(len(self.segments))]
+        x0 = min(r[0] for r in rs)
+        y0 = min(r[1] for r in rs)
+        x1 = max(r[0] + r[2] for r in rs)
+        y1 = max(r[1] + r[3] for r in rs)
+        return x0, y0, x1 - x0, y1 - y0
+
+    def segment_port(self, bar: int, seg: int, side: str = "right"):
+        """Port on segment ``seg`` of bar ``bar`` (left | right | top | bottom)."""
+        from .edges import Port
+
+        if not (0 <= bar < len(self.rows) and 0 <= seg < len(self.segments)):
+            raise IndexError("segment out of range")
+        return Port(self, kind="custom", side=side, index=bar * 1000 + seg)
+
+    def bar_port(self, bar: int, side: str = "top"):
+        """Port on the whole bar ``bar``."""
+        from .edges import Port
+
+        if not 0 <= bar < len(self.rows):
+            raise IndexError("bar out of range")
+        return Port(self, kind="custom", side=side, index=-1 - bar)
+
+    def resolve_custom_port(self, side: str, idx: int = 0, at: float = 0.5):
+        if idx < 0:
+            x, y, w, h = self.bar_rect(-1 - idx)
+        else:
+            x, y, w, h = self.segment_rect(idx // 1000, idx % 1000)
+        return {"left": (x, y + h * at, "left"), "right": (x + w, y + h * at, "right"),
+                "top": (x + w * at, y, "up"), "bottom": (x + w * at, y + h, "down")}.get(
+            side, (x + w / 2, y + h / 2, "right"))
+
+    # -- drawing --------------------------------------------------------------------
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_line, draw_rect
+
+        th = self.theme
+        fs = self._fs()
+        px, py, pw, ph = self._plot_origin()
+        px, py = px + ox, py + oy
+        gap = th.L(4.0)
+        stroke = self.stroke or th.stroke
+        sw = th.stroke_width
+        vmax = self._vmax() or 1.0
+        if _grid_axes(self.grid)[1] or _grid_axes(self.grid)[0]:  # value gridlines, behind bars
+            for t in self._ticks():
+                if t <= 0:
+                    continue
+                if self.horizontal:
+                    x = px + t / vmax * pw
+                    draw_line(buf, x, py, x, py + ph, stroke=th.grid_color, stroke_width=sw)
+                else:
+                    y = py + ph - t / vmax * ph
+                    draw_line(buf, px, y, px + pw, y, stroke=th.grid_color, stroke_width=sw)
+        for b, row in enumerate(self.rows):
+            for k, v in enumerate(row):
+                if v <= 0:
+                    continue
+                x, y, w, h = self.segment_rect(b, k)
+                draw_rect(buf, x + ox, y + oy, w, h, fill=self.colors[k], stroke=stroke, stroke_width=sw)
+                txt = None
+                if self.labels == "inside":
+                    txt = self.segments[k]
+                elif self.values:
+                    txt = _fmt(v)
+                if txt:
+                    tw, _ = self._tw(txt)
+                    if tw + th.L(3.0) <= w and fs * 1.1 <= h:
+                        self._text(buf, txt, x + ox + w / 2, y + oy + h / 2, anchor="middle")
+                    else:
+                        from .notices import note
+
+                        note(self, txt, "did not fit inside its segment and was not drawn "
+                             "(use labels='side' / 'legend', or a longer / thicker bar)")
+        if self.errors:
+            for b, (lo, hi) in enumerate(self.errors):
+                if lo <= 0 and hi <= 0:
+                    continue
+                x, y, w, h = self.bar_rect(b)
+                tot = sum(self.rows[b])
+                cap = min(w if not self.horizontal else h, float(self.bar_thick)) * 0.25
+                if self.horizontal:
+                    a, z = (px + (tot - lo) / vmax * pw, px + (tot + hi) / vmax * pw)
+                    _draw_errbar(buf, y + oy + h / 2, a, z, cap, stroke, sw, horizontal=True)
+                else:
+                    a, z = (py + ph - (tot - lo) / vmax * ph, py + ph - (tot + hi) / vmax * ph)
+                    _draw_errbar(buf, x + ox + w / 2, a, z, cap, stroke, sw)
+        # category labels
+        for b, c in enumerate(self.categories[: len(self.rows)]):
+            x, y, w, h = self.bar_rect(b)
+            if self.horizontal:
+                self._text(buf, c, px - gap, y + oy + h / 2, anchor="end")
+            else:
+                self._text(buf, c, x + ox + w / 2, py + ph + gap * 0.5 + fs * 0.6, anchor="middle")
+        # side labels: every segment named once, beside the bar that hosts it
+        if self.labels == "side":
+            for host, ks in sorted(self._side_hosts().items()):
+                mids, items = [], []
+                for k in ks:
+                    x, y, w, h = self.segment_rect(host, k)
+                    mids.append((x + w / 2) if self.horizontal else (y + h / 2))
+                    items.append(k)
+                if self.horizontal:
+                    x, y, w, h = self.bar_rect(host)
+                    ty = y + oy - gap * 0.5 - fs * 0.6
+                    for k, cx in zip(items, mids):
+                        self._text(buf, self.segments[k], cx + ox, ty, anchor="middle")
+                else:
+                    ys = _spread(mids, fs * 1.2, py - oy, py - oy + ph)
+                    x, _y, w, _h = self.bar_rect(host)
+                    lx = x + w + gap * 1.5
+                    for k, cy0, cy in zip(items, mids, ys):
+                        if self.grid:  # knock gridlines out behind the name
+                            tw_ = self._tw(self.segments[k])[0]
+                            draw_rect(buf, lx + ox - th.L(1.0), cy + oy - fs * 0.6, tw_ + th.L(2.0),
+                                      fs * 1.2, fill="#ffffff", stroke="none", stroke_width=0)
+                        if abs(cy - cy0) > 0.5:  # leader to the segment it names
+                            draw_line(buf, x + w + ox + th.L(0.5), cy0 + oy, lx + ox - th.L(1.0),
+                                      cy + oy, stroke=th.muted_color, stroke_width=sw)
+                        self._text(buf, self.segments[k], lx + ox, cy + oy)
+        # value axis
+        if self.axis:
+            ticks = self._ticks()
+            tl = th.L(3.0)
+            if self.horizontal:
+                ay = py + ph + th.L(2.0)
+                draw_line(buf, px, ay, px + pw, ay, stroke=stroke, stroke_width=sw)
+                for t in ticks:
+                    x = px + t / vmax * pw
+                    draw_line(buf, x, ay, x, ay + tl, stroke=stroke, stroke_width=sw)
+                    self._text(buf, _fmt(t), x, ay + tl + fs * 0.6, anchor="middle")
+                if self.axis_label:
+                    self._text(buf, self.axis_label, px + pw / 2, ay + tl + fs * 1.85, anchor="middle")
+            else:
+                ax = px - th.L(2.0)
+                draw_line(buf, ax, py, ax, py + ph, stroke=stroke, stroke_width=sw)
+                for t in ticks:
+                    y = py + ph - t / vmax * ph
+                    draw_line(buf, ax - tl, y, ax, y, stroke=stroke, stroke_width=sw)
+                    self._text(buf, _fmt(t), ax - tl - th.L(2.0), y, anchor="end")
+                if self.axis_label:
+                    tw = max(self._tw(_fmt(t))[0] for t in ticks)
+                    cx = ax - tl - th.L(2.0) - tw - gap * 0.5 - fs * 0.5
+                    _rot_text(buf, th, self.axis_label, cx, py + ph / 2, fs)
+        if self.labels == "legend":  # top segment first, like the stack
+            items = list(reversed(self._legend_items())) if not self.horizontal else self._legend_items()
+            x = px + pw + gap * 1.5
+            lh = fs * 1.25
+            y = py + ph / 2 - lh * (len(items) - 1) / 2
+            s = fs * 0.9
+            for name, col, _w in items:
+                draw_rect(buf, x, y - s / 2, s, s, fill=col, stroke=stroke, stroke_width=sw)
+                self._text(buf, name, x + s + th.L(2.0), y)
+                y += lh
+
+
+class LineChart(_Chart):
+    """Line chart: ``LineChart({"vLLM": [1, 3, 7], "ours": [1, 2, 3]}, x=[1, 2, 4])``.
+
+    series: mapping name → y values (or one list). x: shared x values (default 0..n-1).
+    markers: dot at every point. axis: x / y axes with ~3 round ticks each;
+    xlabel / ylabel: axis titles. labels: ``"end"`` puts each series name at its last point
+    (spread so names never collide), ``None`` hides them. colors: per series (default:
+    theme accents). ymin / ymax: value range (default: nice-rounded data range; see
+    ``zero``). zero: linear y axis includes 0 — ``"auto"`` (default, theme
+    ``chart_zero``: yes unless all data is above half its maximum), ``True`` or ``False``.
+    fill: shade the area under a single series. ``point_port(series, i)`` → a port on a
+    data point (for callouts / edges).
+    xscale / yscale: ``"linear"`` (default) or ``"log"`` (base 10; decade ticks 1, 10,
+    100, 1k …; values must be > 0). grid: light gridlines — ``True`` (= ``"y"``), ``"x"``,
+    ``"both"``. errors: mapping series → per-point error, each a number (symmetric) or a
+    ``(minus, plus)`` pair (asymmetric); drawn as capped whiskers in the series colour.
+    error_style: ``"bars"`` (default), ``"band"`` (a shaded band between the lower and
+    upper values, theme ``band_opacity``) or ``"both"``. Caps are at least theme
+    ``err_cap`` wide and stick out beyond the markers, so errors smaller than a marker
+    (common on log axes at paper size) still read as a tight bar. Value axes get up to
+    ~5 nice ticks when the plot is tall / wide enough (~3 at the default paper size).
+
+    v0.13.0: ``width=`` is the chart's *total* width in pt — axis ticks, the y label and
+    the end labels / legend included — so ``LineChart(..., width=70)`` really is 70 pt
+    wide; ``plot_width=`` sets the plot area alone (the old meaning of ``width=``).
+    ``height=`` is the plot height. ``labels="legend"`` draws a line-swatch key instead
+    of end labels: ``legend="right"`` (default, a column right of the plot),
+    ``"inside-top-left"`` or ``"inside-top-right"`` (inside the plot corner).
+    """
+
+    plot_w = themed(110.0)
+    plot_h = themed(60.0)
+
+    def __init__(self, series: Any, *, x: Optional[Sequence[Number]] = None, markers: bool = True,
+                 axis: bool = True, xlabel: Optional[str] = None, ylabel: Optional[str] = None,
+                 labels: Optional[str] = "end", colors: Optional[Sequence[str]] = None,
+                 ymin: Optional[float] = None, ymax: Optional[float] = None, fill: bool = False,
+                 width: Optional[float] = None, height: Optional[float] = None,
+                 font_size: Optional[float] = None, line_width: Optional[float] = None,
+                 xscale: str = "linear", yscale: str = "linear", grid: Any = False,
+                 errors: Optional[Mapping[str, Sequence[Any]]] = None,
+                 error_style: str = "bars", zero: Any = None,
+                 plot_width: Optional[float] = None, legend: Optional[str] = None,
+                 **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        if legend not in (None, "right", "inside-top-left", "inside-top-right"):
+            raise ValueError("legend must be 'right', 'inside-top-left' or 'inside-top-right'")
+        self.legend_pos = legend or "right"
+        if width is not None and plot_width is not None:
+            raise TypeError("LineChart: pass width= (total) or plot_width= (plot area), not both")
+        self._outer_w = None if width is None else float(width)
+        if zero not in (None, "auto", True, False):
+            raise ValueError("zero must be 'auto', True or False")
+        self.zero = zero
+        if error_style not in ("bars", "band", "both"):
+            raise ValueError("error_style must be 'bars', 'band' or 'both'")
+        self.error_style = error_style
+        if xscale not in ("linear", "log") or yscale not in ("linear", "log"):
+            raise ValueError("xscale / yscale must be 'linear' or 'log'")
+        if not isinstance(series, Mapping):
+            series = {"": list(series)}
+        self.series = {str(k): [float(v) for v in vs] for k, vs in series.items()}
+        if not self.series or not any(self.series.values()):
+            raise ValueError("LineChart needs at least one non-empty series")
+        n = max(len(v) for v in self.series.values())
+        self.x = [float(v) for v in x] if x is not None else [float(i) for i in range(n)]
+        if labels not in ("end", "legend", None):
+            raise ValueError("labels must be 'end', 'legend' or None")
+        self.markers = bool(markers)
+        self.axis = bool(axis)
+        self.xlabel, self.ylabel = xlabel, ylabel
+        self.labels = labels
+        pal = list(colors or (self.theme.accents if len(self.series) > 1 else self.theme.accents[:1]))
+        self.colors = [pal[i % len(pal)] for i in range(len(self.series))]
+        self.ymin, self.ymax = ymin, ymax
+        self.fill = bool(fill)
+        self.plot_w = plot_width
+        self.plot_h = height
+        self.font_size = font_size
+        self.line_width = line_width
+        self.xscale, self.yscale = xscale, yscale
+        self.grid = grid
+        _grid_axes(grid)
+        errors = dict(errors or {})
+        unknown = [k for k in errors if str(k) not in self.series]
+        if unknown:
+            raise ValueError(f"errors for unknown series {unknown}")
+        self.errors = {str(k): _err_pairs(v, len(self.series[str(k)])) for k, v in errors.items()}
+        if xscale == "log" and min(self.x) <= 0:
+            raise ValueError("xscale='log' needs x > 0")
+        if yscale == "log" and min(v for vs in self.series.values() for v in vs) <= 0:
+            raise ValueError("yscale='log' needs y > 0")
+
+    def _ybounds(self) -> Tuple[List[float], List[float]]:
+        lows, highs = [], []
+        for name, vs in self.series.items():
+            es = self.errors.get(name) or [(0.0, 0.0)] * len(vs)
+            for v, (m, p) in zip(vs, es):
+                lo = v - m
+                lows.append(lo if (self.yscale != "log" or lo > 0) else v)
+                highs.append(v + p)
+        return lows, highs
+
+    def _yscale(self) -> Scale:
+        lows, highs = self._ybounds()
+        if self.yscale == "log":
+            lo = self.ymin if self.ymin is not None else min(lows)
+        else:
+            lo = self.ymin if self.ymin is not None else (
+                min(0.0, min(lows)) if self._with_zero(min(lows), max(highs)) else min(lows))
+        hi = self.ymax if self.ymax is not None else max(highs)
+        return Scale(lo, hi, self.yscale, nice=self.axis or self.yscale == "log",
+                     n=_tick_n(float(self.plot_h), self._fs()),
+                     fixed_lo=self.ymin is not None, fixed_hi=self.ymax is not None)
+
+    def _with_zero(self, lo: float, hi: float) -> bool:
+        """Linear y axis: include 0? ``zero=True`` / ``False`` force it; ``"auto"`` (theme
+        ``chart_zero``) keeps 0 for area fills, data that crosses / touches 0, and data
+        whose minimum is under half its maximum — data far from zero gets a nice
+        off-zero range instead (bar charts always keep 0)."""
+        z = self.zero if self.zero is not None else getattr(self.theme, "chart_zero", "auto")
+        if z is True or z is False:
+            return z
+        if self.fill or lo <= 0 or hi <= 0:
+            return True
+        return lo < 0.5 * hi
+
+    def _xscale(self) -> Scale:
+        lo, hi = min(self.x), max(self.x)
+        return Scale(lo, hi if hi > lo else (lo * 10 if self.xscale == "log" else lo + 1.0),
+                     self.xscale, nice=False)
+
+    def _yrange(self) -> Tuple[float, float]:
+        sc = self._yscale()
+        return sc.lo, sc.hi
+
+    def _xrange(self) -> Tuple[float, float]:
+        sc = self._xscale()
+        return sc.lo, sc.hi
+
+    def _xticks(self) -> List[float]:
+        if len(self.x) <= 6:
+            return list(self.x)
+        if self.xscale == "log":
+            return self._xscale().ticks()
+        lo, hi = self._xrange()
+        lw = max(self._tw(_fmt(v))[0] for v in (lo, hi))
+        return _nice_ticks(lo, hi, _tick_n(float(self.plot_w), self._fs(), False, lw, hi=6))
+
+    def _margins(self) -> Dict[str, float]:
+        fs = self._fs()
+        gap = self.theme.L(3.0)
+        m = {"l": 0.0, "r": 0.0, "t": fs * 0.6 if self.labels else self.theme.L(2.0), "b": 0.0}
+        if self.axis:
+            ys = self._yscale()
+            m["l"] = max(self._tw(ys.fmt(t))[0] for t in ys.ticks()) + gap * 2
+            m["b"] = fs * 1.25 + gap * 1.5
+            if self.ylabel:
+                m["l"] += fs * 1.25 + gap * 0.5
+            if self.xlabel:
+                m["b"] += fs * 1.25
+        else:
+            m["l"] = m["b"] = self.theme.L(2.0)
+        if self.labels == "end" and any(self.series):
+            off = max(gap * 1.2, self._end_clear())
+            m["r"] = max(self._tw(k)[0] for k in self.series) + off + gap * 0.3 if any(k for k in self.series) else 0.0
+        elif self.labels == "legend" and any(k for k in self.series):
+            m["t"] = self.theme.L(2.0)
+            if self.legend_pos == "right":
+                m["r"] = gap * 1.5 + self._legend_w()
+        return m
+
+    def _legend_rows(self) -> List[Tuple[str, str]]:
+        return [(k, self.colors[i]) for i, k in enumerate(self.series) if k]
+
+    def _pt_abs(self, xv: float, yv: float, px: float, py: float) -> Tuple[float, float]:
+        return (px + self._xscale().norm(xv) * self.plot_w,
+                py + self.plot_h - self._yscale().norm(yv) * self.plot_h)
+
+    def _swatch(self) -> float:
+        return self.theme.L(10.0)
+
+    def _legend_w(self) -> float:
+        rows = self._legend_rows()
+        if not rows:
+            return 0.0
+        return self._swatch() + self.theme.L(2.5) + max(self._tw(k)[0] for k, _c in rows)
+
+    def _fit_width(self) -> None:
+        """``width=`` (total) → plot width = width − axis / label margins."""
+        if self._outer_w is None:
+            return
+        from .notices import note
+
+        m = self._margins()
+        floor = self.theme.L(30.0)
+        want = self._outer_w - m["l"] - m["r"]
+        self.plot_w = max(floor, want)
+        if want < floor:
+            note(self, f"width={self._outer_w:g}",
+                 f"leaves no room for the plot: axes + labels take {m['l'] + m['r']:.0f} pt, "
+                 f"so the chart is {floor + m['l'] + m['r']:.0f} pt wide — use "
+                 "labels='legend', shorter series names or a larger width=")
+
+    def _measure(self) -> Tuple[float, float]:
+        self._fit_width()
+        m = self._margins()
+        return self.plot_w + m["l"] + m["r"], self.plot_h + m["t"] + m["b"]
+
+    def _origin(self) -> Tuple[float, float]:
+        g = self.geom
+        m = self._margins()
+        mw, mh = self._measure()
+        return g.x + (g.w - mw) / 2 + m["l"], g.y + (g.h - mh) / 2 + m["t"]
+
+    def _pt(self, xv: float, yv: float) -> Tuple[float, float]:
+        px, py = self._origin()
+        return (px + self._xscale().norm(xv) * self.plot_w,
+                py + self.plot_h - self._yscale().norm(yv) * self.plot_h)
+
+    def point(self, series: Union[str, int], i: int) -> Tuple[float, float]:
+        """Layout coordinates of data point ``i`` of ``series`` (name or index)."""
+        name = list(self.series)[series] if isinstance(series, int) else series
+        return self._pt(self.x[i], self.series[name][i])
+
+    def point_port(self, series: Union[str, int], i: int, side: str = "top"):
+        """Port at a data point; ``side`` only sets the edge's approach direction."""
+        from .edges import Port
+
+        idx = series if isinstance(series, int) else list(self.series).index(series)
+        return Port(self, kind="custom", side=side, index=idx * 100000 + int(i))
+
+    def resolve_custom_port(self, side: str, idx: int = 0, at: float = 0.5):
+        x, y = self.point(idx // 100000, idx % 100000)
+        r = self.theme.L(2.5)
+        d = {"top": (0, -r, "up"), "bottom": (0, r, "down"), "left": (-r, 0, "left"),
+             "right": (r, 0, "right")}.get(side, (0, -r, "up"))
+        return x + d[0], y + d[1], d[2]
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle, draw_line, draw_path, draw_text
+
+        th = self.theme
+        fs = self._fs()
+        px, py = self._origin()
+        stroke = th.stroke
+        sw = th.stroke_width
+        lw = self.line_width if self.line_width is not None else th.edge_width
+        gap = th.L(3.0)
+        ysc, xsc = self._yscale(), self._xscale()
+        gx, gy = _grid_axes(self.grid)
+        if gy:
+            for t in ysc.ticks():
+                _x, y = self._pt(xsc.lo, t)
+                if abs(y - (py + self.plot_h)) > 0.5:
+                    draw_line(buf, px + ox, y + oy, px + ox + self.plot_w, y + oy,
+                              stroke=th.grid_color, stroke_width=sw)
+        if gx:
+            for t in self._xticks():
+                x, _y = self._pt(t, ysc.lo)
+                if abs(x - px) > 0.5:
+                    draw_line(buf, x + ox, py + oy, x + ox, py + oy + self.plot_h,
+                              stroke=th.grid_color, stroke_width=sw)
+        if self.axis:
+            ax0, ay0 = px + ox, py + oy + self.plot_h
+            draw_line(buf, ax0, ay0, ax0 + self.plot_w, ay0, stroke=stroke, stroke_width=sw)
+            draw_line(buf, ax0, py + oy, ax0, ay0, stroke=stroke, stroke_width=sw)
+            tl = th.L(2.5)
+            for t in ysc.ticks():
+                _x, y = self._pt(xsc.lo, t)
+                draw_line(buf, ax0 - tl, y + oy, ax0, y + oy, stroke=stroke, stroke_width=sw)
+                self._text(buf, ysc.fmt(t), ax0 - tl - th.L(2.0), y + oy, anchor="end")
+            for t in self._xticks():
+                x, _y = self._pt(t, ysc.lo)
+                draw_line(buf, x + ox, ay0, x + ox, ay0 + tl, stroke=stroke, stroke_width=sw)
+                self._text(buf, xsc.fmt(t), x + ox, ay0 + tl + fs * 0.7, anchor="middle")
+            if self.xlabel:
+                self._text(buf, self.xlabel, ax0 + self.plot_w / 2, ay0 + tl + fs * 1.95, anchor="middle")
+            if self.ylabel:
+                tw = max(self._tw(ysc.fmt(t))[0] for t in ysc.ticks())
+                cx = ax0 - tl - th.L(2.0) - tw - gap * 0.5 - fs * 0.5
+                _rot_text(buf, th, self.ylabel, cx, py + oy + self.plot_h / 2, fs)
+        ends = []
+        for k, (name, ys) in enumerate(self.series.items()):
+            col = self.colors[k]
+            pts = [self._pt(self.x[i], v) for i, v in enumerate(ys) if i < len(self.x)]
+            pts = [(x + ox, y + oy) for x, y in pts]
+            if not pts:
+                continue
+            d = "M " + " L ".join(f"{x:.2f},{y:.2f}" for x, y in pts)
+            if self.fill and len(self.series) == 1:
+                base = py + oy + self.plot_h
+                area = d + f" L {pts[-1][0]:.2f},{base:.2f} L {pts[0][0]:.2f},{base:.2f} Z"
+                draw_path(buf, area, fill=col, stroke="none", stroke_width=0, opacity=0.18)
+            spans = []  # (x, y_lo, y_hi) per point with an error
+            for i, (m_, p_) in enumerate(self.errors.get(name, [])):
+                if i >= len(pts):
+                    continue
+                v = ys[i]
+                lo_v = v - m_ if (self.yscale != "log" or v - m_ > 0) else ysc.lo
+                _x, y_lo = self._pt(self.x[i], lo_v)
+                _x, y_hi = self._pt(self.x[i], v + p_)
+                spans.append((pts[i][0], y_lo + oy, y_hi + oy, m_ > 0 or p_ > 0))
+            if spans and self.error_style in ("band", "both") and len(spans) >= 2:
+                up = " L ".join(f"{x:.2f},{yh:.2f}" for x, _yl, yh, _e in spans)
+                dn = " L ".join(f"{x:.2f},{yl:.2f}" for x, yl, _yh, _e in reversed(spans))
+                draw_path(buf, f"M {up} L {dn} Z", fill=col, stroke="none", stroke_width=0,
+                          opacity=getattr(th, "band_opacity", 0.18))
+            draw_path(buf, d, fill="none", stroke=col, stroke_width=lw)
+            mr = th.L(2.0)
+            if self.error_style in ("bars", "both"):
+                cap = _err_cap(th, (mr + th.L(getattr(th, "err_cap_out", 1.4)))
+                               if self.markers else 0.0)
+                for x, y_lo, y_hi, has in spans:
+                    if has:
+                        _draw_errbar(buf, x, y_lo, y_hi, cap, col, sw)
+            if self.markers:
+                for x, y in pts:
+                    draw_circle(buf, x, y, mr, fill=col)
+            ends.append((name, col, pts[-1]))
+        if self.labels == "end":
+            named = [(n, c, p) for n, c, p in ends if n]
+            ys = _spread([p[1] for _n, _c, p in named], fs * 1.2, py + oy - fs, py + oy + self.plot_h + fs)
+            # clear the last marker and its error cap
+            off = max(gap * 1.2, self._end_clear())
+            for (name, col, (x, y)), ly in zip(named, ys):
+                self._text(buf, name, x + off, ly, color=col if col != th.text_color else None)
+        elif self.labels == "legend":
+            self._draw_line_legend(buf, px + ox, py + oy, lw)
+
+    def _draw_line_legend(self, buf: List[str], px: float, py: float, lw: float) -> None:
+        from .render_svg import draw_circle, draw_line, draw_rect
+
+        th = self.theme
+        rows = self._legend_rows()
+        if not rows:
+            return
+        fs = self._fs()
+        gap = th.L(3.0)
+        rh = fs * 1.3
+        sw_len = self._swatch()
+        w, h = self._legend_w(), rh * len(rows)
+        if self.legend_pos == "right":
+            x0 = px + self.plot_w + gap * 1.5
+            y0 = py + self.plot_h / 2 - h / 2
+        else:
+            pad = th.L(2.0)
+            y0 = py + pad
+            x0 = px + pad if self.legend_pos == "inside-top-left" else px + self.plot_w - pad - w
+            draw_rect(buf, x0 - pad / 2, y0 - pad / 2, w + pad, h + pad, fill="#ffffff",
+                      stroke="none", stroke_width=0, opacity=0.85)
+            hit = any(x0 - ox_ <= x <= x0 + w and y0 <= y <= y0 + h
+                      for name in self.series for i, v in enumerate(self.series[name])
+                      if i < len(self.x)
+                      for x, y, ox_ in [(*self._pt_abs(self.x[i], v, px, py), 0.0)])
+            if hit:
+                from .notices import note
+
+                note(self, "legend", "inside the plot covers data points; use the other "
+                     "inside corner or legend='right'", level="info")
+        for i, (name, col) in enumerate(rows):
+            cy = y0 + rh * (i + 0.5)
+            draw_line(buf, x0, cy, x0 + sw_len, cy, stroke=col, stroke_width=lw)
+            if self.markers:
+                draw_circle(buf, x0 + sw_len / 2, cy, th.L(2.0), fill=col)
+            self._text(buf, name, x0 + sw_len + th.L(2.5), cy)
+
+    def _end_clear(self) -> float:
+        """Distance from the last point to its end label: marker + error cap + a gap."""
+        th = self.theme
+        c = th.L(2.0) if self.markers else 0.0
+        if self.errors and self.error_style in ("bars", "both"):
+            c = max(c, _err_cap(th, (th.L(2.0) + th.L(getattr(th, "err_cap_out", 1.4)))
+                                if self.markers else 0.0))
+        return c + th.L(2.0)
+
+
+class GroupedBarChart(_Chart):
+    """Grouped (clustered) bars: ``GroupedBarChart({"A100": {"vLLM": 3, "ours": 5}, ...})``.
+
+    data: mapping category → mapping series → value, or a list of value lists (one per
+    category) with ``series=`` names. categories: group names under each cluster (default:
+    the mapping keys). labels: ``"legend"`` (swatch key column right of the plot, default)
+    or ``None``. axis: value axis with round ticks (default on); axis_label: its title.
+    yscale: ``"linear"`` (from 0) or ``"log"`` (decades; values > 0). grid: light value
+    gridlines. errors: same shape as ``data`` — per bar a number or ``(minus, plus)``.
+    values: print each value above its bar. colors: per series (default: theme palette).
+    ``bar_port(category, series, side)`` → a port on one bar (indices or names).
+    horizontal (v0.9.0): bars grow to the right, category names on the left, the value
+    axis at the bottom. The value axis gets up to ~5 nice ticks when it is long enough.
+
+    v0.12.0: negative values grow down (left) from the zero line. ``baseline=1.0``
+    draws bars from that value instead of 0 (speed-ups: 0.8× grows down, 1.7× up).
+    ``ref=1.0`` / ``ref=(1.0, "baseline")`` / a list of those: dashed reference lines.
+    ``bar_colors=`` per-bar fills: a list per category (a colour, or a list per series)
+    or ``{category: colour}`` / ``{(category, series): colour}``. ``value_format="{:.1f}×"``
+    (or a callable) formats ``values=True`` labels; ``value_pos="inside"`` puts them inside
+    the bar end (falling back outside, with a CF-TXT-011 info, when they don't fit).
+    ``legend="inside-top-left"`` / ``"inside-top-right"`` draws the swatch key inside
+    the plot instead of in a column to the right.
+
+    v0.13.0: ``min_value=`` / ``max_value=`` pin the value-axis floor / top (bars are
+    clipped to that range), e.g. ``min_value=5.75, max_value=6.05`` for a zoomed axis.
+    A ``ref=`` equal to ``baseline`` dashes the baseline itself (it used to stay solid).
+    """
+
+    bar_len = themed(70.0)
+    bar_thick = themed(9.0)
+    bar_gap = themed(10.0)
+
+    def __init__(self, data: Any, *, series: Optional[Sequence[str]] = None,
+                 categories: Optional[Sequence[str]] = None, labels: Optional[str] = "legend",
+                 axis: bool = True, axis_label: Optional[str] = None, yscale: str = "linear",
+                 grid: Any = False, errors: Any = None, values: bool = False,
+                 colors: Optional[Sequence[str]] = None, max_value: Optional[float] = None,
+                 length: Optional[float] = None, thickness: Optional[float] = None,
+                 gap: Optional[float] = None, font_size: Optional[float] = None,
+                 stroke: Optional[str] = None, horizontal: bool = False,
+                 baseline: float = 0.0, ref: Any = None, bar_colors: Any = None,
+                 value_format: Any = None, value_pos: str = "outside",
+                 legend: Optional[str] = None, min_value: Optional[float] = None,
+                 **kwargs: Any) -> None:
+        super().__init__(**kwargs)
+        self.min_value = None if min_value is None else float(min_value)
+        if self.min_value is not None and max_value is not None and self.min_value >= max_value:
+            raise ValueError("GroupedBarChart: min_value must be below max_value")
+        self.horizontal = bool(horizontal)
+        if labels not in ("legend", None):
+            raise ValueError("labels must be 'legend' or None")
+        if legend not in (None, "right", "inside-top-left", "inside-top-right"):
+            raise ValueError("legend must be 'right', 'inside-top-left' or 'inside-top-right'")
+        if value_pos not in ("outside", "inside"):
+            raise ValueError("value_pos must be 'outside' or 'inside'")
+        self.legend_pos = legend or "right"
+        self.baseline = float(baseline)
+        self.value_format, self.value_pos = value_format, value_pos
+        self.refs = _ref_list(ref)
+        if yscale not in ("linear", "log"):
+            raise ValueError("yscale must be 'linear' or 'log'")
+        names: List[str] = list(series or [])
+        cats: List[str] = list(categories or [])
+        rows: List[List[float]] = []
+        if isinstance(data, Mapping):
+            for c, d in data.items():
+                if not categories:
+                    cats.append(str(c))
+                if isinstance(d, Mapping):
+                    for k in d:
+                        if str(k) not in names:
+                            names.append(str(k))
+            for d in data.values():
+                rows.append([float(d.get(k, 0.0)) for k in names] if isinstance(d, Mapping)
+                            else [float(v) for v in d])
+        else:
+            rows = [[float(v) for v in r] for r in data]
+        if not rows or not any(any(r) for r in rows):
+            raise ValueError("GroupedBarChart needs at least one value")
+        ns = max(len(r) for r in rows)
+        self.rows = [r + [0.0] * (ns - len(r)) for r in rows]
+        self.series = (names + [f"s{i}" for i in range(len(names), ns)])[:ns]
+        self.categories = cats
+        if yscale == "log" and min(v for r in self.rows for v in r) <= 0:
+            raise ValueError("yscale='log' needs values > 0")
+        if yscale == "log" and self.baseline <= 0:
+            self.baseline = 0.0  # log bars grow from the axis floor
+        self.labels, self.axis, self.axis_label = labels, bool(axis), axis_label
+        self.yscale, self.grid, self.values = yscale, grid, bool(values)
+        _grid_axes(grid)
+        self.errors: List[List[Tuple[float, float]]] = []
+        if errors is not None:
+            if isinstance(errors, Mapping):
+                errs = [[(e.get(k) if isinstance(e, Mapping) else e) for k in self.series]
+                        if isinstance(e, Mapping) else list(e) for e in errors.values()]
+            else:
+                errs = [list(e) for e in errors]
+            self.errors = [_err_pairs(e, ns) for e in errs] + \
+                [[(0.0, 0.0)] * ns] * max(0, len(self.rows) - len(errs))
+        pal = list(colors or self.theme.palette)
+        self.colors = [pal[i % len(pal)] for i in range(ns)]
+        self.bar_fills = _bar_fills(bar_colors, self.rows, self.categories, self.series,
+                                    self.colors)
+        self.max_value = max_value
+        self.bar_len, self.bar_thick, self.bar_gap = length, thickness, gap
+        self.font_size, self.stroke = font_size, stroke
+
+    # -- geometry -------------------------------------------------------------------
+    def _scale(self) -> Scale:
+        his = [v + (self.errors[c][s][1] if self.errors else 0.0)
+               for c, r in enumerate(self.rows) for s, v in enumerate(r)]
+        los = [v - (self.errors[c][s][0] if self.errors else 0.0)
+               for c, r in enumerate(self.rows) for s, v in enumerate(r)]
+        refs = [r for r, _l in self.refs]
+        if self.yscale == "log":
+            lo = min(x for x in los + [min(min(r) for r in self.rows)] + refs if x > 0)
+            if self.baseline > 0:
+                lo = min(lo, self.baseline)
+        else:
+            lo = min([self.baseline] + los + refs)
+            if self.baseline == 0:
+                lo = min(lo, 0.0)
+        hi = float(self.max_value) if self.max_value is not None else max(his + refs + [self.baseline])
+        if self.min_value is not None:  # v0.13.0: explicit axis floor
+            lo = self.min_value
+            if self.yscale == "log" and lo <= 0:
+                raise ValueError("min_value must be > 0 with yscale='log'")
+            hi = max(hi, lo + 1e-9)
+        if self.horizontal:
+            n = _tick_n(float(self.bar_len), self._fs(), False, self._tw(_fmt_si(hi))[0])
+        else:
+            n = _tick_n(float(self.bar_len), self._fs())
+        return Scale(lo, hi, self.yscale, nice=True, n=n, fixed_hi=self.max_value is not None,
+                     fixed_lo=self.min_value is not None)
+
+    def _inner(self) -> float:
+        """Space between bars of one group; widened so ``values=True`` labels never touch."""
+        g = self.theme.L(1.0)
+        if self.values and self.horizontal:  # value labels beside bars: one text line each
+            g = max(g, self._fs() * 1.05 - float(self.bar_thick))
+        if self.values and not self.horizontal:
+            sc = self._scale()
+            vw = max(self._tw(t)[0] for r in self._value_texts() for t in r)
+            g = max(g, vw - float(self.bar_thick) + self.theme.L(2.0))
+        return g
+
+    def _group_w(self) -> float:
+        n = len(self.series)
+        return n * float(self.bar_thick) + (n - 1) * self._inner()
+
+    def _gap(self) -> float:
+        g = float(self.bar_gap)
+        if self.horizontal:  # category names stacked on the left: one text line per group
+            if self.categories:
+                g = max(g, self._fs() * 1.25 - self._group_w() + self.theme.L(2.0))
+            return g
+        if self.categories:
+            cw = max(self._tw(c)[0] for c in self.categories)
+            g = max(g, cw - self._group_w() + self.theme.L(4.0))
+        return g
+
+    def _lead(self) -> float:
+        """Inset of the first group so its category name / value labels clear the axis."""
+        lead = self.theme.L(2.0)
+        if self.horizontal:
+            return lead
+        if self.categories:
+            lead = max(lead, self._tw(self.categories[0])[0] / 2 - self._group_w() / 2
+                       + self.theme.L(1.0))
+        if self.values:
+            vw = self._tw(self._value_texts()[0][0])[0]
+            lead = max(lead, (vw - float(self.bar_thick)) / 2 + self.theme.L(2.0))
+        return lead
+
+    def _legend_items(self) -> List[Tuple[str, str, float]]:
+        sw = self._fs()
+        return [(s, c, sw + self.theme.L(2.0) + self._tw(s)[0]) for s, c in zip(self.series, self.colors)]
+
+    def _margins(self) -> Dict[str, float]:
+        fs = self._fs()
+        gap = self.theme.L(4.0)
+        sc = self._scale()
+        m = {"l": 0.0, "r": 0.0, "t": fs * 0.6, "b": 0.0}
+        if self.horizontal:
+            m["t"] = self.theme.L(2.0) + (fs * 1.3 if any(l for _r, l in self.refs) else 0.0)
+            if self.categories:
+                m["l"] = max(self._tw(c)[0] for c in self.categories) + gap * 0.75
+            m["l"] += self._neg_room_h()
+            if self.axis:
+                m["b"] = fs * 1.25 + gap * 0.5 + (fs * 1.25 if self.axis_label else 0.0)
+                m["r"] = self._tw(sc.fmt(sc.ticks()[-1]))[0] / 2
+            if self.values:
+                # how far the furthest value label (past its bar / whisker) runs beyond the
+                # plot end — bars that stop short of the axis end need no extra room
+                txt = self._value_texts()
+                over = max([(sc.norm(v + (self.errors[c][s][1] if self.errors else 0.0)) - 1.0)
+                            * float(self.bar_len) + self.theme.L(3.0) + self._tw(txt[c][s])[0]
+                            for c, r in enumerate(self.rows) for s, v in enumerate(r)
+                            if not self._down(c, s) and self.value_pos != "inside"] + [0.0])
+                m["r"] = max(m["r"], over)
+            if self.labels == "legend" and not self.legend_pos.startswith("inside"):
+                m["r"] += gap * 1.5 + max(it[2] for it in self._legend_items())
+            return m
+        if self.categories:
+            m["b"] = fs * 1.25 + gap * 0.5
+        m["b"] += self._neg_room()
+        if self.axis:
+            m["l"] = max(self._tw(sc.fmt(t))[0] for t in sc.ticks()) + gap + self.theme.L(1.0) + \
+                (fs * 1.25 + gap * 0.5 if self.axis_label else 0.0)
+        if self.values:
+            m["t"] = max(m["t"], fs * 1.3)
+        m["r"] = self._ref_label_w()
+        if self.labels == "legend" and not self.legend_pos.startswith("inside"):
+            m["r"] += gap * 1.5 + max(it[2] for it in self._legend_items())
+        return m
+
+    def _plot_size(self) -> Tuple[float, float]:
+        n = len(self.rows)
+        across = self._lead() * 2 + n * self._group_w() + (n - 1) * self._gap()
+        if self.horizontal:
+            return float(self.bar_len), across
+        return across, float(self.bar_len)
+
+    def _measure(self) -> Tuple[float, float]:
+        pw, ph = self._plot_size()
+        m = self._margins()
+        h = ph + m["t"] + m["b"]
+        if self.labels == "legend" and not self.legend_pos.startswith("inside"):
+            h = max(h, self._fs() * 1.25 * len(self.series) + m["t"])
+        return pw + m["l"] + m["r"], h
+
+    def _origin(self) -> Tuple[float, float]:
+        g = self.geom
+        m = self._margins()
+        mw, mh = self._measure()
+        pw, ph = self._plot_size()
+        body = ph + m["t"] + m["b"]
+        return g.x + (g.w - mw) / 2 + m["l"], g.y + (g.h - mh) / 2 + (mh - body) / 2 + m["t"]
+
+    def _idx(self, cat: Union[int, str], ser: Union[int, str]) -> Tuple[int, int]:
+        c = self.categories.index(cat) if isinstance(cat, str) else int(cat)
+        s = self.series.index(ser) if isinstance(ser, str) else int(ser)
+        if not (0 <= c < len(self.rows) and 0 <= s < len(self.series)):
+            raise IndexError("bar out of range")
+        return c, s
+
+    def bar_rect(self, cat: Union[int, str], ser: Union[int, str]) -> Tuple[float, float, float, float]:
+        """(x, y, w, h) of one bar (layout coordinates)."""
+        c, s = self._idx(cat, ser)
+        px, py = self._origin()
+        sc = self._scale()
+        L = float(self.bar_len)
+        b = self._base_n(sc)
+        v = min(1.0, max(0.0, sc.norm(self.rows[c][s])))  # clipped to min_value / max_value
+        if self.horizontal:
+            y = py + self._lead() + c * (self._group_w() + self._gap()) + \
+                s * (float(self.bar_thick) + self._inner())
+            return px + min(b, v) * L, y, abs(v - b) * L, float(self.bar_thick)
+        x = px + self._lead() + c * (self._group_w() + self._gap()) + s * (float(self.bar_thick) + self._inner())
+        return x, py + L - max(b, v) * L, float(self.bar_thick), abs(v - b) * L
+
+    def _base_n(self, sc: Scale) -> float:
+        """Normalised position of the line bars grow from (0 / ``baseline`` / axis floor)."""
+        if self.yscale == "log" and self.baseline <= 0:
+            return 0.0
+        return min(1.0, max(0.0, sc.norm(self.baseline)))
+
+    def _base_dash(self, sc: Scale) -> Optional[str]:
+        """v0.13.0: ``ref=`` on the baseline value dashes the baseline itself."""
+        bn = self._base_n(sc)
+        return "3,2" if any(abs(sc.norm(r) - bn) < 1e-6 for r, _l in self.refs) else None
+
+    def _down(self, c: int, s: int) -> bool:
+        return self.rows[c][s] < self.baseline and not (self.yscale == "log" and self.baseline <= 0)
+
+    def bar_port(self, cat: Union[int, str], ser: Union[int, str], side: str = "top"):
+        """Port on one bar (``side`` left | right | top | bottom)."""
+        from .edges import Port
+
+        c, s = self._idx(cat, ser)
+        return Port(self, kind="custom", side=side, index=c * 1000 + s)
+
+    def value_coord(self, v: float) -> float:
+        """Layout coordinate of value ``v`` on the value axis (y; x when ``horizontal``)."""
+        px, py = self._origin()
+        L = float(self.bar_len)
+        n = self._scale().norm(float(v))
+        return px + n * L if self.horizontal else py + L - n * L
+
+    @property
+    def baseline_y(self) -> float:
+        """Layout y of the line bars grow from (x when ``horizontal``); see :meth:`value_coord`."""
+        sc = self._scale()
+        px, py = self._origin()
+        L = float(self.bar_len)
+        b = self._base_n(sc)
+        return px + b * L if self.horizontal else py + L - b * L
+
+    def value_anchor(self, v: float, side: str = "right", at: Optional[float] = None):
+        """Port at value ``v`` on the value axis, for edges / notes pointing at a level.
+
+        ``side`` is where on the plot the port sits: ``left`` | ``right`` (plot edges at the
+        height of ``v``; vertical charts) or ``top`` | ``bottom`` (horizontal charts).
+        ``at`` (0–1) slides it across the plot instead, e.g. ``at=0.5`` for the plot middle.
+        """
+        from .edges import Port
+
+        self.__dict__.setdefault("_vanchors", []).append((float(v), at))
+        return Port(self, kind="custom", side=side, index=-len(self._vanchors))
+
+    def resolve_custom_port(self, side: str, idx: int = 0, at: float = 0.5):
+        if idx < 0:  # value_anchor
+            v, a2 = self._vanchors[-1 - idx]
+            px, py = self._origin()
+            pw, ph = self._plot_size()
+            q = self.value_coord(v)
+            if self.horizontal:
+                f = a2 if a2 is not None else 0.0
+                return (q, py + f * ph, "up") if side == "top" else \
+                    (q, py + ph - (a2 if a2 is not None else 0.0) * ph, "down")
+            if a2 is not None:
+                return px + a2 * pw, q, side if side in ("left", "right") else "right"
+            return (px, q, "left") if side == "left" else (px + pw, q, "right")
+        x, y, w, h = self.bar_rect(idx // 1000, idx % 1000)
+        return {"left": (x, y + h * at, "left"), "right": (x + w, y + h * at, "right"),
+                "top": (x + w * at, y, "up"), "bottom": (x + w * at, y + h, "down")}.get(
+            side, (x + w / 2, y, "up"))
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_line, draw_rect
+
+        th = self.theme
+        fs = self._fs()
+        px, py = self._origin()
+        px, py = px + ox, py + oy
+        pw, ph = self._plot_size()
+        gap = th.L(4.0)
+        stroke = self.stroke or th.stroke
+        sw = th.stroke_width
+        sc = self._scale()
+        if self.horizontal:
+            self._draw_h(buf, ox, oy, px, py, pw, ph, sc, stroke, sw, fs, gap)
+            return
+        vals = self._value_spots(ox, oy, px, py, pw, ph, sc)  # (text, x, cy, anchor, colour)
+        holes = [(cx - self._tw(t)[0] / 2, cy - self._tw(t)[1] / 2, self._tw(t)[0], self._tw(t)[1])
+                 for t, cx, cy, _a, _c in vals]
+        holes += self._legend_holes(px, py, pw, ph)
+        if any(_grid_axes(self.grid)):
+            for t in sc.ticks():
+                y = py + ph - sc.norm(t) * ph
+                if abs(y - (py + ph)) > 0.5:
+                    _gapped_line(buf, px, y, px + pw, y, holes, stroke=th.grid_color,
+                                 stroke_width=sw)
+        self._draw_refs(buf, px, py, pw, ph, sc, holes, ox, oy)
+        for c, row in enumerate(self.rows):
+            for s, v in enumerate(row):
+                x, y, w, h = self.bar_rect(c, s)
+                if h > 0.05:
+                    draw_rect(buf, x + ox, y + oy, w, h, fill=self.bar_fills[c][s], stroke=stroke,
+                              stroke_width=sw)
+                if self.errors:
+                    lo, hi = self.errors[c][s]
+                    if lo > 0 or hi > 0:
+                        lo_v = v - lo if (self.yscale != "log" or v - lo > 0) else sc.lo
+                        _draw_errbar(buf, x + ox + w / 2, py + ph - sc.norm(lo_v) * ph,
+                                     py + ph - sc.norm(v + hi) * ph, self._cap(w), stroke, sw)
+        for t, cx, cy, a, col in vals:
+            self._text(buf, t, cx, cy, anchor=a, color=col)
+        cat_y = py + ph + gap * 0.5 + fs * 0.6 + self._neg_room()
+        for c, name in enumerate(self.categories[: len(self.rows)]):
+            x0 = self.bar_rect(c, 0)[0]
+            self._text(buf, name, x0 + ox + self._group_w() / 2, cat_y, anchor="middle")
+        # baseline (zero / baseline= value) + value axis
+        yb = py + ph - self._base_n(sc) * ph
+        draw_line(buf, px, yb, px + pw, yb, stroke=stroke, stroke_width=sw,
+                  dasharray=self._base_dash(sc))
+        if self.axis:
+            tl = th.L(3.0)
+            ax = px
+            draw_line(buf, ax, py, ax, py + ph, stroke=stroke, stroke_width=sw)
+            for t in sc.ticks():
+                y = py + ph - sc.norm(t) * ph
+                draw_line(buf, ax - tl, y, ax, y, stroke=stroke, stroke_width=sw)
+                self._text(buf, sc.fmt(t), ax - tl - th.L(2.0), y, anchor="end")
+            if self.axis_label:
+                tw = max(self._tw(sc.fmt(t))[0] for t in sc.ticks())
+                cx = ax - tl - th.L(2.0) - tw - gap * 0.5 - fs * 0.5
+                _rot_text(buf, th, self.axis_label, cx, py + ph / 2, fs)
+        if self.labels == "legend":
+            if self.legend_pos.startswith("inside"):
+                lx, ly, _w, _h = self._legend_box(px, py, pw, ph)
+                self._draw_legend(buf, lx, ly + _h / 2, stroke, sw)
+            else:
+                self._draw_legend(buf, px + pw + self._ref_label_w() + gap * 1.5, py + ph / 2,
+                                  stroke, sw)
+
+    # -- v0.12.0 helpers --------------------------------------------------------------
+    def _neg_room(self) -> float:
+        """Extra room under the plot for value labels of bars that grow down."""
+        if self.horizontal or not self.values or self.value_pos == "inside":
+            return 0.0
+        sc = self._scale()
+        ph = float(self.bar_len)
+        need = 0.0
+        for c, row in enumerate(self.rows):
+            for s, v in enumerate(row):
+                if self._down(c, s):
+                    lo = v - (self.errors[c][s][0] if self.errors else 0.0)
+                    below = sc.norm(lo) * ph  # distance of the bar end above the plot floor
+                    need = max(need, self._fs() * 1.25 - below)
+        return max(0.0, need)
+
+    def _legend_box(self, px: float, py: float, pw: float, ph: float) -> Tuple[float, float, float, float]:
+        items = self._legend_items()
+        lh = self._fs() * 1.25
+        w = max(it[2] for it in items)
+        h = lh * len(items)
+        pad = self.theme.L(3.0)
+        left = px + pad + self.theme.L(2.0)
+        right = px + pw - pad - w
+        y = py + pad * 0.5
+        first, second = (left, right) if self.legend_pos == "inside-top-left" else (right, left)
+        if self._legend_clear(first, y, w, h, px, py):
+            return first, y, w, h
+        if self._legend_clear(second, y, w, h, px, py):
+            return second, y, w, h
+        from .notices import note
+
+        note(self, "legend", "inside the plot overlaps bars at both top corners; raise "
+             "max_value= or use legend='right'", level="warn")
+        return first, y, w, h
+
+    def _legend_clear(self, x: float, y: float, w: float, h: float, px: float, py: float) -> bool:
+        """True when a legend box at (x, y) clears every bar and value label."""
+        dx, dy = px - self._origin()[0], py - self._origin()[1]
+        p = self.theme.L(1.5)
+        fs = self._fs()
+        txt = self._value_texts()
+        boxes = []
+        for c, row in enumerate(self.rows):
+            for s_ in range(len(row)):
+                bx, by, bw, bh = self.bar_rect(c, s_)
+                bx, by = bx + dx, by + dy
+                if self.values and not self.horizontal and self.value_pos != "inside":
+                    by, bh = by - fs * 1.25, bh + fs * 1.25
+                    tw = self._tw(txt[c][s_])[0]  # v0.12.0: the label may be wider than the bar
+                    if tw > bw:
+                        bx, bw = bx + bw / 2 - tw / 2, tw
+                if self.values and self.horizontal and self.value_pos != "inside":
+                    bw += self._tw(txt[c][s_])[0] + self.theme.L(3.0)
+                boxes.append((bx, by, bw, bh))
+        return not any(bx < x + w + p and x - p < bx + bw and by < y + h + p and y - p < by + bh
+                       for bx, by, bw, bh in boxes)
+
+    def _legend_holes(self, px: float, py: float, pw: float, ph: float) -> List[Tuple[float, float, float, float]]:
+        if self.labels != "legend" or not self.legend_pos.startswith("inside"):
+            return []
+        x, y, w, h = self._legend_box(px, py, pw, ph)
+        p = self.theme.L(1.5)
+        return [(x - p, y - p, w + 2 * p, h + 2 * p)]
+
+    def _ref_label_w(self) -> float:
+        labs = [l for _r, l in self.refs if l]
+        return max(self._tw(l)[0] for l in labs) + self.theme.L(3.0) if labs else 0.0
+
+    def _draw_refs(self, buf: List[str], px: float, py: float, pw: float, ph: float, sc: Scale,
+                   holes: List[Tuple[float, float, float, float]], ox: float = 0.0,
+                   oy: float = 0.0) -> None:
+        """Dashed reference lines across the plot, each label just outside the plot end
+        (right of a horizontal line; above a vertical one) so bars never cover it."""
+        th = self.theme
+        fs = self._fs()
+        bn = self._base_n(sc)
+        for r, lab_ in self.refs:
+            n = sc.norm(r)
+            on_base = abs(n - bn) < 1e-6  # the baseline itself is drawn dashed (_base_dash)
+            if self.horizontal:
+                x = px + n * pw
+                if lab_:
+                    self._text(buf, lab_, x, py - fs * 0.75, anchor="middle", color=th.muted_color)
+                if not on_base:
+                    _gapped_line(buf, x, py, x, py + ph, holes, stroke=th.muted_color,
+                                 stroke_width=th.stroke_width, dasharray="3,2")
+            else:
+                y = py + ph - n * ph
+                if lab_:
+                    self._text(buf, lab_, px + pw + th.L(2.0), y, color=th.muted_color)
+                if not on_base:
+                    _gapped_line(buf, px, y, px + pw, y, holes, stroke=th.muted_color,
+                                 stroke_width=th.stroke_width, dasharray="3,2")
+
+    def _value_spots(self, ox: float, oy: float, px: float, py: float, pw: float, ph: float,
+                     sc: Scale) -> List[Tuple[str, float, float, str, Optional[str]]]:
+        """Where each ``values=True`` label goes: outside the bar end (past its whisker),
+        or inside it with ``value_pos="inside"`` when it fits (else outside + a notice)."""
+        from .notices import note
+        from .primitives import _luma
+
+        if not self.values:
+            return []
+        th = self.theme
+        fs = self._fs()
+        txt = self._value_texts()
+        out = []
+        for c, row in enumerate(self.rows):
+            for s, v in enumerate(row):
+                x, y, w, h = self.bar_rect(c, s)
+                x, y = x + ox, y + oy
+                down = self._down(c, s)
+                t = txt[c][s]
+                tw = self._tw(t)[0]
+                lo_e, hi_e = self.errors[c][s] if self.errors else (0.0, 0.0)
+                if self.value_pos == "inside":
+                    fits = (tw + th.L(2.0) <= w and fs * 1.2 <= h) if not self.horizontal else \
+                        (tw + th.L(3.0) <= w and fs * 1.05 <= h)
+                    if fits:
+                        col = "#ffffff" if _luma(self.bar_fills[c][s]) < 0.5 else None
+                        if self.horizontal:
+                            if down:
+                                out.append((t, x + th.L(1.5), y + h / 2, "start", col))
+                            else:
+                                out.append((t, x + w - th.L(1.5), y + h / 2, "end", col))
+                        else:
+                            cy = (y + h - fs * 0.65) if down else (y + fs * 0.65)
+                            out.append((t, x + w / 2, cy, "middle", col))
+                        continue
+                    note(self, t, "did not fit inside its bar; drawn outside it", level="info")
+                if self.horizontal:
+                    if down:
+                        end = px + sc.norm(v - lo_e) * pw if lo_e > 0 else x
+                        out.append((t, end - th.L(3.0), y + h / 2, "end", None))
+                    else:
+                        end = px + sc.norm(v + hi_e) * pw if hi_e > 0 else x + w
+                        out.append((t, end + th.L(3.0), y + h / 2, "start", None))
+                else:
+                    if down:
+                        yy = py + ph - sc.norm(v - lo_e) * ph if lo_e > 0 else y + h
+                        out.append((t, x + w / 2, yy + fs * 0.6, "middle", None))
+                    else:
+                        yy = py + ph - sc.norm(v + hi_e) * ph if hi_e > 0 else y
+                        out.append((t, x + w / 2, yy - fs * 0.6, "middle", None))
+        return out
+
+    def _value_texts(self) -> List[List[str]]:
+        f = self.value_format
+        if f is not None:
+            fn = f if callable(f) else (lambda v, _f=str(f): _f.format(v))
+            return [[str(fn(v)) for v in row] for row in self.rows]
+        flat = _fmt_values([v for row in self.rows for v in row], self.yscale == "log")
+        out, k = [], 0
+        for row in self.rows:
+            out.append(flat[k:k + len(row)])
+            k += len(row)
+        return out
+
+    def _cap(self, thick: float) -> float:
+        return max(thick * 0.3, min(_err_cap(self.theme), thick * 0.45))
+
+    def _draw_legend(self, buf: List[str], x: float, cy: float, stroke: str, sw: float) -> None:
+        from .render_svg import draw_rect
+
+        fs = self._fs()
+        lh = fs * 1.25
+        items = self._legend_items()
+        y = cy - lh * (len(items) - 1) / 2
+        s_ = fs * 0.9
+        for name, col, _w in items:
+            draw_rect(buf, x, y - s_ / 2, s_, s_, fill=col, stroke=stroke, stroke_width=sw)
+            self._text(buf, name, x + s_ + self.theme.L(2.0), y)
+            y += lh
+
+    def _draw_h(self, buf: List[str], ox: float, oy: float, px: float, py: float, pw: float,
+                ph: float, sc: Scale, stroke: str, sw: float, fs: float, gap: float) -> None:
+        """horizontal=True: bars to the right, categories left, value axis below."""
+        from .render_svg import draw_line, draw_rect
+
+        th = self.theme
+        vals = self._value_spots(ox, oy, px, py, pw, ph, sc)
+        holes = [((x if a == "start" else x - self._tw(t)[0] if a == "end" else x - self._tw(t)[0] / 2),
+                  cy - self._tw(t)[1] / 2, self._tw(t)[0], self._tw(t)[1])
+                 for t, x, cy, a, _c in vals]
+        holes += self._legend_holes(px, py, pw, ph)
+        if any(_grid_axes(self.grid, default="x")):
+            for t in sc.ticks():
+                x = px + sc.norm(t) * pw
+                if abs(x - px) > 0.5:
+                    _gapped_line(buf, x, py, x, py + ph, holes, stroke=th.grid_color,
+                                 stroke_width=sw)
+        self._draw_refs(buf, px, py, pw, ph, sc, holes, ox, oy)
+        for c, row in enumerate(self.rows):
+            for s, v in enumerate(row):
+                x, y, w, h = self.bar_rect(c, s)
+                if w > 0.05:
+                    draw_rect(buf, x + ox, y + oy, w, h, fill=self.bar_fills[c][s], stroke=stroke,
+                              stroke_width=sw)
+                if self.errors:
+                    lo, hi = self.errors[c][s]
+                    if lo > 0 or hi > 0:
+                        lo_v = v - lo if (self.yscale != "log" or v - lo > 0) else sc.lo
+                        _draw_errbar(buf, y + oy + h / 2, px + sc.norm(lo_v) * pw,
+                                     px + sc.norm(v + hi) * pw, self._cap(h), stroke, sw,
+                                     horizontal=True)
+        for t, x, cy, a, col in vals:
+            self._text(buf, t, x, cy, anchor=a, color=col)
+        cat_x = px - gap * 0.75 - self._neg_room_h()
+        for c, name in enumerate(self.categories[: len(self.rows)]):
+            y0 = self.bar_rect(c, 0)[1]
+            self._text(buf, name, cat_x, y0 + oy + self._group_w() / 2, anchor="end")
+        xb = px + self._base_n(sc) * pw
+        draw_line(buf, xb, py, xb, py + ph, stroke=stroke, stroke_width=sw,
+                  dasharray=self._base_dash(sc))  # baseline
+        if self.axis:
+            tl = th.L(3.0)
+            ay = py + ph
+            draw_line(buf, px, ay, px + pw, ay, stroke=stroke, stroke_width=sw)
+            for t in sc.ticks():
+                x = px + sc.norm(t) * pw
+                draw_line(buf, x, ay, x, ay + tl, stroke=stroke, stroke_width=sw)
+                self._text(buf, sc.fmt(t), x, ay + tl + fs * 0.7, anchor="middle")
+            if self.axis_label:
+                self._text(buf, self.axis_label, px + pw / 2, ay + tl + fs * 1.95, anchor="middle")
+        if self.labels == "legend":
+            if self.legend_pos.startswith("inside"):
+                lx, ly, _w, _h = self._legend_box(px, py, pw, ph)
+                self._draw_legend(buf, lx, ly + _h / 2, stroke, sw)
+                return
+            m = self._margins()
+            xl = px + pw + m["r"] - (gap * 1.5 + max(it[2] for it in self._legend_items())) + gap * 1.5
+            self._draw_legend(buf, xl, py + ph / 2, stroke, sw)
+
+    def _neg_room_h(self) -> float:
+        """horizontal: extra room left of the plot for labels of bars that grow left."""
+        if not self.values or self.value_pos == "inside":
+            return 0.0
+        sc = self._scale()
+        L = float(self.bar_len)
+        txt = self._value_texts()
+        need = 0.0
+        for c, row in enumerate(self.rows):
+            for s, v in enumerate(row):
+                if self._down(c, s):
+                    lo = v - (self.errors[c][s][0] if self.errors else 0.0)
+                    need = max(need, self._tw(txt[c][s])[0] + self.theme.L(3.0) - sc.norm(lo) * L)
+        # v0.12.0: a clear gap between a negative value label and the category names, so
+        # "GSM8K −2.0" does not read as one phrase
+        return need + self.theme.L(6.0) if need > 0 else 0.0
+
+
+class Sparkline(LineChart):
+    """Tiny axis-free trend line: ``Sparkline([3, 5, 4, 8, 7])`` (last point marked).
+
+    width / height default to a word-sized strip; ``color`` one colour; ``fill`` shades
+    under the line; ``last=False`` hides the end dot.
+    """
+
+    plot_w = themed(40.0)
+    plot_h = themed(12.0)
+
+    def __init__(self, values: Sequence[Number], *, color: Optional[str] = None, last: bool = True,
+                 fill: bool = False, width: Optional[float] = None, height: Optional[float] = None,
+                 **kwargs: Any) -> None:
+        super().__init__({"": list(values)}, markers=False, axis=False, labels=None,
+                         colors=[color] if color else None, fill=fill, plot_width=width,
+                         height=height,
+                         ymin=min(values) if values else 0.0, **kwargs)
+        self.last = bool(last)
+
+    def _margins(self) -> Dict[str, float]:
+        r = self.theme.L(2.5)
+        return {"l": r, "r": r, "t": r, "b": r}
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle
+
+        super().draw(buf, ox, oy)
+        if self.last:
+            ys = list(self.series.values())[0]
+            x, y = self._pt(self.x[len(ys) - 1], ys[-1])
+            draw_circle(buf, x + ox, y + oy, self.theme.L(2.2), fill=self.colors[0])