codefig 0.17.0__py3-none-any.whl

codefig/primitives.py

@@ -0,0 +1,2721 @@
+"""Drawable primitives: Box, Text, Arrow, Matrix, DotGrid, Strip, Ellipsis, Group, Spacer, Brace, CircleHighlight."""
+
+from __future__ import annotations
+
+import re
+
+import math
+
+from typing import Dict, Any, List, Optional, Sequence, Tuple, Union
+
+from .node import BoxGeom, Col, Container, Node, Row
+from .styles import DEFAULT_THEME, Theme, current_theme, normalize_pad, theme_default, themed
+from .textutil import expand_subscripts, markup_lines, measure_text, split_lines, xml_escape
+
+
+def paint_dot_grid(
+    buf: List[str],
+    x: float,
+    y: float,
+    w: float,
+    h: float,
+    *,
+    pitch: float = 8.0,
+    r: float = 1.4,
+    color: str = "#888888",
+    opacity: float = 0.55,
+    inset: float = 2.0,
+) -> None:
+    """Fill a rectangle with a regular lattice of dots (no clipPath needed)."""
+    from .render_svg import draw_circle
+
+    if w <= 0 or h <= 0 or pitch <= 0:
+        return
+    x0 = x + inset
+    y0 = y + inset
+    x1 = x + w - inset
+    y1 = y + h - inset
+    if x1 <= x0 or y1 <= y0:
+        return
+    # Center lattice so edges look even
+    nx = max(1, int((x1 - x0) / pitch) + 1)
+    ny = max(1, int((y1 - y0) / pitch) + 1)
+    # Recompute pitch to fit evenly when possible
+    span_x = x1 - x0
+    span_y = y1 - y0
+    if nx > 1:
+        dx = span_x / (nx - 1)
+    else:
+        dx = 0.0
+        x0 = (x0 + x1) / 2
+    if ny > 1:
+        dy = span_y / (ny - 1)
+    else:
+        dy = 0.0
+        y0 = (y0 + y1) / 2
+    # Prefer declared pitch when span is large enough
+    if nx > 1 and abs(dx - pitch) > 0.01:
+        # use floor count at pitch, margin-centered
+        nx = max(1, int(span_x / pitch) + 1)
+        used = (nx - 1) * pitch if nx > 1 else 0.0
+        x0 = x + inset + max(0.0, (span_x - used) / 2)
+        dx = pitch if nx > 1 else 0.0
+    if ny > 1 and abs(dy - pitch) > 0.01:
+        ny = max(1, int(span_y / pitch) + 1)
+        used = (ny - 1) * pitch if ny > 1 else 0.0
+        y0 = y + inset + max(0.0, (span_y - used) / 2)
+        dy = pitch if ny > 1 else 0.0
+    for j in range(ny):
+        cy = y0 + j * dy
+        for i in range(nx):
+            cx = x0 + i * dx
+            draw_circle(buf, cx, cy, r, fill=color, opacity=opacity)
+
+
+def paint_strip(
+    buf: List[str],
+    x: float,
+    y: float,
+    w: float,
+    h: float,
+    *,
+    direction: str = "horizontal",  # horizontal|vertical
+    stripe: float = 6.0,
+    colors: Sequence[str] = ("#e8e8e8", "#ffffff"),
+    opacity: float = 1.0,
+) -> None:
+    """Paint alternating horizontal or vertical stripes inside a rect."""
+    from .render_svg import draw_rect
+
+    if w <= 0 or h <= 0 or stripe <= 0:
+        return
+    cols = list(colors) if colors else ["#e8e8e8", "#ffffff"]
+    n = len(cols)
+    if direction in ("vertical", "v", "col"):
+        i = 0
+        cx = x
+        while cx < x + w - 0.01:
+            bw = min(stripe, x + w - cx)
+            draw_rect(
+                buf, cx, y, bw, h,
+                fill=cols[i % n], stroke="none", stroke_width=0,
+                opacity=opacity,
+            )
+            cx += stripe
+            i += 1
+    else:
+        i = 0
+        cy = y
+        while cy < y + h - 0.01:
+            bh = min(stripe, y + h - cy)
+            draw_rect(
+                buf, x, cy, w, bh,
+                fill=cols[i % n], stroke="none", stroke_width=0,
+                opacity=opacity,
+            )
+            cy += stripe
+            i += 1
+
+
+def _paint_node_pattern(buf: List[str], pattern: Any, x: float, y: float, w: float, h: float) -> None:
+    """Paint a DotGrid / Strip (or duck-typed) pattern into a rectangle."""
+    if pattern is None:
+        return
+    if hasattr(pattern, "paint"):
+        pattern.paint(buf, x, y, w, h)
+        return
+    name = type(pattern).__name__
+    if name == "DotGrid":
+        paint_dot_grid(
+            buf, x, y, w, h,
+            pitch=getattr(pattern, "pitch", 8.0),
+            r=getattr(pattern, "r", 1.4),
+            color=getattr(pattern, "color", "#888888"),
+            opacity=getattr(pattern, "opacity", 0.55),
+            inset=getattr(pattern, "inset", 2.0),
+        )
+    elif name == "Strip":
+        paint_strip(
+            buf, x, y, w, h,
+            direction=getattr(pattern, "direction", "horizontal"),
+            stripe=getattr(pattern, "stripe", 6.0),
+            colors=getattr(pattern, "colors", ("#e8e8e8", "#ffffff")),
+            opacity=getattr(pattern, "opacity", 1.0),
+        )
+
+
+class Spacer(Node):
+    """Empty space of ``w`` × ``h`` pt inside a Row/Col: ``Row([a, Spacer(w=12), b])``."""
+
+    def __init__(self, w: float = 0.0, h: float = 0.0, **kwargs: Any) -> None:
+        super().__init__(min_w=w, min_h=h, **kwargs)
+        self._w, self._h = w, h
+
+    def _measure(self) -> Tuple[float, float]:
+        return self._w, self._h
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        return
+
+
+def _resolve_fs(fs: Any, theme: Theme, default: Optional[float] = None) -> float:
+    """Requested size (number | callable(theme) | None → default/theme.font_size),
+    snapped to the theme's size roles."""
+    if callable(fs):
+        fs = fs(theme)
+    if fs is None:
+        fs = default if default is not None else theme.font_size
+    return theme.snap(float(fs))
+
+
+class Text(Node):
+    """Plain text label (rich-text / math markup allowed); sizes snap to theme roles.
+
+    ``align="left" | "center" (default) | "right"`` aligns the lines of a multi-line
+    label against each other (and the text inside a wider slot); ``rotate=`` degrees
+    clockwise (``-90`` reads bottom→top); ``font_size`` is pt at final size.
+    Scripts: ``x_{i}`` / ``x^{2}`` / ``x^+`` (an unbraced single sign), stacked
+    ``x_{i}^{+}``; a literal ``*`` inside a script is ``\\*`` (``P^{\\*}``).
+    """
+
+    color = theme_default("text_color")
+
+    def __init__(
+        self,
+        text: str,
+        *,
+        font_size: Optional[float] = None,
+        mono: bool = False,
+        weight: str = "normal",
+        color: Optional[str] = None,
+        align: str = "center",  # left|center|right — text alignment within box
+        rotate: float = 0.0,  # degrees, clockwise (SVG); -90 reads bottom→top
+        italic: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.text = text
+        self.font_size = font_size
+        self.mono = mono
+        self.weight = weight
+        self.color = color
+        self.text_align = align
+        self.rotate = float(rotate or 0.0)
+        self.italic = bool(italic)
+
+    def _fs(self) -> float:
+        return _resolve_fs(self.font_size, self.theme)
+
+    def _plain_size(self) -> Tuple[float, float]:
+        return measure_text(self.text, self._fs(), mono=self.mono, weight=self.weight,
+                            italic=self.italic)
+
+    def _measure(self) -> Tuple[float, float]:
+        w, h = self._plain_size()
+        if not self.rotate:
+            return w, h
+        # Layout reserves the axis-aligned bbox of the rotated text block.
+        a = math.radians(self.rotate)
+        c, s_ = abs(math.cos(a)), abs(math.sin(a))
+        return w * c + h * s_, w * s_ + h * c
+
+    def ink_box(self) -> Tuple[float, float, float, float]:
+        """Tight page-space (x, y, w, h) around the drawn glyphs (used for knockout)."""
+        g = self.geom
+        fs = self._fs()
+        lines = markup_lines(self.text) if self.text else [""]
+        lh = fs * 1.25
+        total_h = len(lines) * lh
+        pw = max((measure_text(ln, fs, mono=self.mono, weight=self.weight, italic=self.italic)[0]
+                  for ln in lines), default=0.0)
+        if self.rotate:
+            ph = self._plain_size()[1]
+            cx, cy = g.x + g.w / 2, g.y + g.h / 2
+            bx, by, bw, bh = cx - self._plain_size()[0] / 2, cy - ph / 2, self._plain_size()[0], ph
+        else:
+            bx, by, bw, bh = g.x, g.y, g.w, g.h
+        if self.text_align == "left":
+            x0 = bx
+        elif self.text_align == "right":
+            x0 = bx + bw - pw
+        else:
+            x0 = bx + (bw - pw) / 2
+        top = by + (bh - total_h) / 2 + 0.18 * fs
+        bot = by + (bh - total_h) / 2 + (len(lines) - 1) * lh + 1.22 * fs
+        if not self.rotate:
+            return x0, top, pw, bot - top
+        a = math.radians(self.rotate)
+        ca, sa = math.cos(a), math.sin(a)
+        cx, cy = g.x + g.w / 2, g.y + g.h / 2
+        xs, ys = [], []
+        for px, py in ((x0, top), (x0 + pw, top), (x0, bot), (x0 + pw, bot)):
+            dx, dy = px - cx, py - cy
+            xs.append(cx + dx * ca - dy * sa)
+            ys.append(cy + dx * sa + dy * ca)
+        return min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys)
+
+    def baseline_offset(self) -> float:
+        """Top of measured box → first-line baseline (vertically centered text)."""
+        fs = self._fs()
+        _w, h = self.measure()
+        lines = markup_lines(self.text) if self.text else [""]
+        lh = fs * 1.25
+        total_h = max(len(lines), 1) * lh
+        return (h - total_h) / 2 + fs
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_text
+
+        g = self.geom
+        fs = self._fs()
+        lines = markup_lines(self.text)
+        lh = fs * 1.25
+        total_h = len(lines) * lh
+        if self.rotate:
+            # Draw the unrotated block centred on the node, then rotate about the centre.
+            pw, ph = self._plain_size()
+            cx, cy = g.x + ox + g.w / 2, g.y + oy + g.h / 2
+            bx, by, bw, bh = cx - pw / 2, cy - ph / 2, pw, ph
+            buf.append(f'<g transform="rotate({self.rotate:.2f} {cx:.2f} {cy:.2f})">')
+        else:
+            bx, by, bw, bh = g.x + ox, g.y + oy, g.w, g.h
+        y0 = by + (bh - total_h) / 2 + fs
+        start = len(buf)
+        for i, line in enumerate(lines):
+            tw, _ = measure_text(line, fs, mono=self.mono, weight=self.weight, italic=self.italic)
+            if self.text_align == "left":
+                tx = bx
+            elif self.text_align == "right":
+                tx = bx + bw - tw
+            else:
+                tx = bx + (bw - tw) / 2
+            draw_text(
+                buf,
+                line,
+                tx,
+                y0 + i * lh,
+                font_size=fs,
+                mono=self.mono,
+                weight=self.weight,
+                fill=self.color,
+                family=self.theme.mono_family if self.mono else None,
+                italic=self.italic,
+            )
+        if self.rotate:
+            buf.append("</g>")
+
+
+class Box(Node):
+    """Labeled rectangle — the workhorse primitive.
+
+    v0.4.0: ``icon=`` ("gpu" or an :class:`~codefig.icon.Icon`) sits beside / above the
+    label (``icon_pos`` left | right | top | bottom); ``badge=`` puts a small icon in a
+    corner (``badge_pos`` top-left | top-right | bottom-left | bottom-right), e.g. a
+    snowflake for a frozen module. ``fill=`` also takes :class:`~codefig.fills.Gradient`
+    / :class:`~codefig.fills.Split`. Subclasses in :mod:`codefig.shapes` reuse all of it.
+
+    v0.5.0: ``step=`` (int, str or :class:`~codefig.steps.Step`) puts a numbered step
+    badge (①) straddling the ``step_pos`` corner (top-left | top-right | bottom-left |
+    bottom-right). The badge is a **hard** child node, so check_overlaps() reports it
+    if it pokes into a neighbour. Example: ``Box("Retrieve", step=1)``.
+
+    v0.7.0: ``pattern=`` (``DotGrid()`` / ``Strip()``) is knocked out behind the label by
+    default (``pattern_clear=True``) so dots or stripes never run through the text; pass
+    ``pattern_clear=False`` for the old full-bleed texture.
+
+    v0.12.0: ``label_rotate=90`` (reads bottom-to-top) or ``-90`` (top-to-bottom) turns
+    the label (and subtitle); the box is measured with the turned label, so a tall thin
+    box fits it. ``border=`` ``"solid" | "dashed" | "dotted" | "none"`` (or a dash
+    string like ``"4 2"``) sets the outline style; ``pad=`` takes a number, ``(v, h)``
+    or ``(top, right, bottom, left)`` as in CSS.
+    """
+
+    def __init__(
+        self,
+        text: str = "",
+        *,
+        fill: Optional[Any] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        rounded: Optional[bool] = None,
+        radius: Optional[float] = None,
+        pad: Optional[Any] = None,
+        padding: Optional[Any] = None,
+        text_margin: Optional[float] = None,
+        font_size: Optional[float] = None,
+        mono: bool = False,
+        weight: str = "normal",
+        text_color: Optional[str] = None,
+        min_w: float = 0.0,
+        min_h: float = 0.0,
+        width: Optional[float] = None,
+        height: Optional[float] = None,
+        w: Optional[Any] = None,
+        h: Optional[Any] = None,
+        aspect: Optional[float] = None,
+        max_w: Optional[float] = None,
+        max_h: Optional[float] = None,
+        pattern: Optional[Any] = None,
+        pattern_clear: bool = True,
+        subtitle: Optional[str] = None,
+        subtitle_size: Optional[float] = None,
+        subtitle_color: Optional[str] = None,
+        icon: Any = None,
+        icon_pos: str = "left",
+        icon_size: Optional[float] = None,
+        icon_color: Optional[str] = None,
+        icon_gap: Optional[float] = None,
+        badge: Any = None,
+        badge_pos: str = "top-left",
+        badge_size: Optional[float] = None,
+        badge_color: Optional[str] = None,
+        step: Any = None,
+        step_pos: str = "top-left",
+        label_rotate: float = 0,
+        **kwargs: Any,
+    ) -> None:
+        from ._validate import check_enum
+        label_rotate = check_enum("primitives(label_rotate)", label_rotate, (0, 90, -90, 270))
+        self.label_rotate = -90 if label_rotate == 270 else int(label_rotate)
+        # subtitle: smaller secondary line(s) under the main text (title + detail)
+        self.subtitle = subtitle
+        self.subtitle_size = subtitle_size
+        self.subtitle_color = subtitle_color
+        # width/height are aliases for numeric w/h (kept for BC)
+        sw = w if w is not None else width
+        sh = h if h is not None else height
+        super().__init__(
+            min_w=min_w, min_h=min_h, max_w=max_w, max_h=max_h,
+            w=sw, h=sh, aspect=aspect, **kwargs,
+        )
+        self.text = text
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.rounded = rounded
+        self.radius = radius
+        raw = padding if padding is not None else pad
+        self._pad_raw = None if raw is None else normalize_pad(raw)
+        self.text_margin = None if text_margin is None else float(text_margin)
+        self.font_size = font_size
+        self.mono = mono
+        self.weight = weight
+        self.text_color = text_color
+        # BC aliases — preferred path is Node.size_w / size_h
+        self.fixed_w = width if width is not None else (
+            float(w) if isinstance(w, (int, float)) else None
+        )
+        self.fixed_h = height if height is not None else (
+            float(h) if isinstance(h, (int, float)) else None
+        )
+        self.pattern = pattern
+        self.pattern_clear = bool(pattern_clear)
+        from ._validate import check_enum
+        icon_pos = check_enum("primitives(icon_pos)", icon_pos, ("left", "right", "top", "bottom"))
+        from ._validate import check_enum
+        badge_pos = check_enum("primitives(badge_pos)", badge_pos, _BADGE_POS)
+        from .icon import as_icon
+
+        self.icon = as_icon(icon, size=icon_size, color=icon_color, theme=self._theme)
+        self.icon_pos = icon_pos
+        self.icon_size = icon_size
+        self.icon_color = icon_color
+        self.icon_gap = icon_gap
+        self.badge = as_icon(badge, size=badge_size, color=badge_color, theme=self._theme)
+        self.badge_pos = badge_pos
+        self.badge_size = badge_size
+        self.badge_color = badge_color
+        # v0.5.0: numbered step badge (①) straddling a corner — a hard child node
+        from ._validate import check_enum
+        step_pos = check_enum("primitives(step_pos)", step_pos, _BADGE_POS)
+        from .steps import as_step
+
+        self.step = as_step(step, theme=self._theme)
+        self.step_pos = step_pos
+        if self.step is not None:
+            self.step.parent = self
+
+    # lazy theme defaults (resolved against the active theme at layout time)
+    @property
+    def fill(self) -> Any:
+        """Explicit ``fill=``; else the category colour; else ``theme.fill_default``."""
+        v = self.__dict__.get("_td_fill")
+        if v is not None:
+            return v
+        cat = self.__dict__.get("category")
+        if cat is not None:
+            from .styles import category_style
+
+            return category_style(str(cat), self.theme)[0]
+        return self.theme.fill_default
+
+    @fill.setter
+    def fill(self, v: Any) -> None:
+        self.__dict__["_td_fill"] = v
+
+    @property
+    def pattern(self) -> Any:
+        """Explicit ``pattern=``; else the category's automatic hatch (≥ 5 categories)."""
+        v = self.__dict__.get("_pattern")
+        if v is not None:
+            return v
+        cat = self.__dict__.get("category")
+        if cat is not None:
+            from .legend import hatch_pattern
+            from .styles import category_style
+
+            spec = category_style(str(cat), self.theme)[1]
+            return hatch_pattern(spec) if spec else None
+        return None
+
+    @pattern.setter
+    def pattern(self, v: Any) -> None:
+        self.__dict__["_pattern"] = v
+
+    @property
+    def rounded(self) -> bool:
+        """Resolve the default corner shape against the active theme."""
+        value = self.__dict__.get("_rounded")
+        return self.theme.box_rounded if value is None else value
+
+    @rounded.setter
+    def rounded(self, value: Optional[bool]) -> None:
+        self.__dict__["_rounded"] = value
+
+    @property
+    def stroke(self) -> str:
+        """Explicit outline or the category's themed shade."""
+        value = self.__dict__.get("_box_stroke")
+        if value is not None:
+            return value
+        if self.category is not None and self.theme.category_stroke is not None:
+            from .styles import shade
+            return shade(self.fill, self.theme.category_stroke)
+        return self.theme.stroke
+
+    @stroke.setter
+    def stroke(self, value: Optional[str]) -> None:
+        self.__dict__["_box_stroke"] = value
+    stroke_width = theme_default("stroke_width")
+    text_margin = theme_default("text_margin")
+    text_color = theme_default("text_color")
+
+    @property
+    def padding(self) -> Tuple[float, float, float, float]:
+        """(top, right, bottom, left) inner padding (theme default unless given)."""
+        raw = self.__dict__.get("_pad_raw")
+        if raw is not None:
+            return raw
+        th = self.theme
+        if th.box_pad is not None:
+            v, h = th.box_pad
+            return (float(v), float(h), float(v), float(h))
+        return normalize_pad(th.pad)
+
+    @padding.setter
+    def padding(self, value: Any) -> None:
+        self.__dict__["_pad_raw"] = None if value is None else normalize_pad(value)
+
+    @property
+    def pad(self) -> float:
+        return sum(self.padding) / 4.0
+
+    @pad.setter
+    def pad(self, value: Any) -> None:
+        self.padding = value
+
+    def _fs(self) -> float:
+        return _resolve_fs(self.font_size, self.theme)
+
+    def baseline_offset(self) -> float:
+        """Top → first-line baseline for labeled boxes (text vertically centered)."""
+        if not self.text:
+            return self.measure()[1] * 0.5
+        fs = self._fs()
+        _w, h = self.measure()
+        lines = markup_lines(self.text)
+        lh = fs * 1.25
+        total_h = len(lines) * lh
+        return (h - total_h) / 2 + fs
+
+    def optical_nudge(self) -> float:
+        """Rounded/pill boxes look heavier — nudge up ~4% of height for optical align."""
+        if self.rounded:
+            return self.measure()[1] * 0.04
+        return 0.0
+
+    def _inset(self) -> Tuple[float, float, float, float]:
+        pt, pr, pb, pl = self.padding
+        m = self.text_margin
+        return pt + m, pr + m, pb + m, pl + m
+
+    def _sub_fs(self) -> float:
+        return _resolve_fs(self.subtitle_size, self.theme, self._fs() * 0.82)
+
+    # ---- content block: label (+ subtitle) and optional icon ----------------------
+    def _text_size(self) -> Tuple[float, float]:
+        tw, th = self._text_size_upright()
+        if getattr(self, "label_rotate", 0):
+            return th, tw
+        return tw, th
+
+    def _text_size_upright(self) -> Tuple[float, float]:
+        tw, th = measure_text(self.text, self._fs(), mono=self.mono, weight=self.weight) if self.text else (0.0, self._fs())
+        if self.subtitle:
+            sw_, sh_ = measure_text(self.subtitle, self._sub_fs(), mono=self.mono)
+            tw, th = max(tw, sw_), th + sh_ + self._fs() * 0.15
+        return tw, th
+
+    def _icon_px(self) -> float:
+        if self.icon is None:
+            return 0.0
+        if self.icon.size is not None:
+            return self.icon.size
+        has_label = bool(self.text or self.subtitle)
+        return round(self._fs() * (1.45 if has_label and self.icon_pos in ("left", "right") else 1.9), 1)
+
+    def _icon_gap(self) -> float:
+        return self.icon_gap if self.icon_gap is not None else self._fs() * 0.4
+
+    def _content_size(self) -> Tuple[float, float]:
+        tw, th = self._text_size()
+        if self.icon is None:
+            return tw, th
+        s = self._icon_px()
+        if not (self.text or self.subtitle):
+            return s, s
+        g = self._icon_gap()
+        if self.icon_pos in ("left", "right"):
+            return s + g + tw, max(s, th)
+        return max(s, tw), s + g + th
+
+    def _badge_px(self) -> float:
+        if self.badge is None:
+            return 0.0
+        return self.badge.size if self.badge.size is not None else round(self._fs() * 1.15, 1)
+
+    def _frame_size(self, iw: float, ih: float) -> Tuple[float, float]:
+        """Outer size for an inner (label) rectangle — identity for a rectangle;
+        shapes (:mod:`codefig.shapes`) grow it so the label fits inside the outline."""
+        return iw, ih
+
+    def _text_rect(self, x: float, y: float, w: float, h: float) -> Tuple[float, float, float, float]:
+        """Inner rectangle the label is centred in (whole box for a rectangle)."""
+        return x, y, w, h
+
+    def _measure(self) -> Tuple[float, float]:
+        tw, th = self._content_size()
+        it, ir, ib, il = self._inset()
+        b = self._badge_px()
+        reserve = (b + self.theme.L(3.0)) if b else 0.0  # symmetric, keeps the label centred
+        w, h = self._frame_size(tw + il + ir + 2 * reserve, th + it + ib)
+        if (self.text or self.subtitle) and self.theme.box_min_h:
+            h = max(h, self.theme.box_min_h)
+        if self.fixed_w is not None:
+            w = self.fixed_w
+        if self.fixed_h is not None:
+            h = self.fixed_h
+        return w, h
+
+    def _draw_frame(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        from .render_svg import draw_rect
+
+        r = 0.0
+        if self.rounded:
+            r = self.radius if self.radius is not None else self.theme.corner_radius
+        draw_rect(
+            buf,
+            x,
+            y,
+            w,
+            h,
+            fill=self.fill,
+            stroke=self._border_stroke(self.stroke),
+            stroke_width=self.stroke_width,
+            radius=r,
+            dasharray=self._dash(self.stroke_width),
+        )
+        if self.pattern is not None:
+            self._paint_pattern(buf, x, y, w, h)
+
+    def _pattern_hole(self, x: float, y: float, w: float, h: float):
+        """Label rectangle (+ a small pad) the pattern leaves clear, or None."""
+        if not getattr(self, "pattern_clear", True) or not (self.text or self.subtitle):
+            return None
+        tx, ty, tw, th = self._text_rect(x, y, w, h)
+        cw, ch = self._content_size()
+        pad = self.theme.L(2.0)
+        cx, cy = tx + tw / 2, ty + th / 2
+        return (cx - cw / 2 - pad, cy - ch / 2 - pad * 0.6, cw + 2 * pad, ch + 1.2 * pad)
+
+    def _paint_pattern(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        """Paint ``pattern=`` clipped away from the label (v0.7.0, ``pattern_clear``)."""
+        hole = self._pattern_hole(x, y, w, h)
+        if hole is None:
+            _paint_node_pattern(buf, self.pattern, x, y, w, h)
+            return
+        from .edges import knockout_clip
+
+        cid = knockout_clip(buf, [hole])
+        buf.append(f'<g clip-path="url(#{cid})">')
+        _paint_node_pattern(buf, self.pattern, x, y, w, h)
+        buf.append("</g>")
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        self._draw_frame(buf, x, y, g.w, g.h)
+        self._draw_content(buf, *self._text_rect(x, y, g.w, g.h))
+        self._draw_step(buf, ox, oy)
+
+    # ---- v0.5.0 corner step badge -------------------------------------------------
+    def children(self) -> Sequence[Node]:
+        step = getattr(self, "step", None)
+        return (step,) if step is not None else ()
+
+    def _layout_children(self) -> None:
+        step = getattr(self, "step", None)
+        if step is None:
+            return
+        g = self.geom
+        d = step.diameter()
+        inset = d * 0.15  # ~35 % of the badge sits outside the corner
+        cx = g.x + inset if self.step_pos.endswith("left") else g.right - inset
+        cy = g.y + inset if self.step_pos.startswith("top") else g.bottom - inset
+        step.layout(cx - d / 2, cy - d / 2, d, d)
+
+    def _draw_step(self, buf: List[str], ox: float, oy: float) -> None:
+        step = getattr(self, "step", None)
+        if step is not None:
+            step.draw(buf, ox, oy)
+
+    def _draw_content(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        if self.badge is not None:
+            b = self._badge_px()
+            m = self.theme.L(3.0) + self.stroke_width / 2
+            bx = x + m if self.badge_pos.endswith("left") else x + w - m - b
+            by = y + m if self.badge_pos.startswith("top") else y + h - m - b
+            self.badge.paint(buf, bx, by, b, b)
+        if self.icon is not None:
+            s = self._icon_px()
+            cw, ch = self._content_size()
+            bx, by = x + (w - cw) / 2, y + (h - ch) / 2
+            has_label = bool(self.text or self.subtitle)
+            g = self._icon_gap() if has_label else 0.0
+            tw, th = self._text_size() if has_label else (0.0, 0.0)
+            col = self.icon.color or self.icon_color or self.text_color
+            if self.icon_pos == "left":
+                self.icon.paint(buf, bx, by + (ch - s) / 2, s, s, color=col)
+                x, w = bx + s + g, tw
+            elif self.icon_pos == "right":
+                self.icon.paint(buf, bx + tw + g, by + (ch - s) / 2, s, s, color=col)
+                x, w = bx, tw
+            elif self.icon_pos == "top":
+                self.icon.paint(buf, bx + (cw - s) / 2, by, s, s, color=col)
+                y, h = by + s + g, th
+            else:
+                self.icon.paint(buf, bx + (cw - s) / 2, by + th + g, s, s, color=col)
+                y, h = by, th
+        self._draw_label(buf, x, y, w, h)
+
+    def _draw_label(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        from .render_svg import draw_text
+
+        if not self.text:
+            return
+        rot = getattr(self, "label_rotate", 0)
+        if rot:
+            cx, cy = x + w / 2, y + h / 2
+            buf.append(f'<g transform="rotate({-rot} {cx:.2f} {cy:.2f})">')
+            x, y, w, h = cx - h / 2, cy - w / 2, h, w
+        try:
+            self._draw_label_upright(buf, x, y, w, h)
+        finally:
+            if rot:
+                buf.append("</g>")
+
+    def _draw_label_upright(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        from .render_svg import draw_text
+
+        fs = self._fs()
+        lines = markup_lines(self.text)
+        lh = fs * 1.25
+        total_h = len(lines) * lh
+        if self.subtitle:
+            sfs = self._sub_fs()
+            slines = markup_lines(self.subtitle)
+            sub_h = len(slines) * sfs * 1.25
+            gap = fs * 0.15
+            y0 = y + (h - total_h - gap - sub_h) / 2 + fs
+            sy0 = y0 - fs + total_h + gap + sfs
+            for i, line in enumerate(slines):
+                tw, _ = measure_text(line, sfs, mono=self.mono)
+                draw_text(buf, line, x + (w - tw) / 2, sy0 + i * sfs * 1.25, font_size=sfs,
+                          mono=self.mono, fill=self.subtitle_color or self.text_color,
+                          family=self.theme.mono_family if self.mono else None)
+        else:
+            y0 = y + (h - total_h) / 2 + fs
+        for i, line in enumerate(lines):
+            tw, _ = measure_text(line, fs, mono=self.mono, weight=self.weight)
+            tx = x + (w - tw) / 2
+            draw_text(
+                buf,
+                line,
+                tx,
+                y0 + i * lh,
+                font_size=fs,
+                mono=self.mono,
+                weight=self.weight,
+                fill=self.text_color,
+                family=self.theme.mono_family if self.mono else None,
+            )
+
+
+_BADGE_POS = ("top-left", "top-right", "bottom-left", "bottom-right")
+
+
+class Ellipsis(Text):
+    """An ellipsis glyph ("…", "⋯", "⋮") between repeated items."""
+
+    def __init__(self, text: str = "…", **kwargs: Any) -> None:
+        kwargs.setdefault("font_size", lambda th: th.F(18))
+        super().__init__(text, **kwargs)
+
+
+
+class DotGrid(Node):
+    """
+    Dot lattice fill — standalone node or `pattern=` on Box/Group.
+
+    Useful for cache / buffer / memory regions in research figures.
+    """
+
+    def __init__(
+        self,
+        *,
+        pitch: float = 8.0,
+        r: float = 1.4,
+        color: str = "#5dade2",
+        opacity: float = 0.55,
+        inset: float = 2.0,
+        fill: Optional[str] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        min_w: float = 48.0,
+        min_h: float = 36.0,
+        width: Optional[float] = None,
+        height: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(min_w=min_w, min_h=min_h, **kwargs)
+        self.pitch = float(pitch)
+        self.r = float(r)
+        self.color = color
+        self.opacity = float(opacity)
+        self.inset = float(inset)
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.fixed_w = width
+        self.fixed_h = height
+
+    def paint(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        paint_dot_grid(
+            buf, x, y, w, h,
+            pitch=self.pitch, r=self.r, color=self.color,
+            opacity=self.opacity, inset=self.inset,
+        )
+
+    def _measure(self) -> Tuple[float, float]:
+        w = self.fixed_w if self.fixed_w is not None else self.min_w
+        h = self.fixed_h if self.fixed_h is not None else self.min_h
+        return w, h
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect
+
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        if self.fill or self.stroke:
+            sw = self.stroke_width if self.stroke_width is not None else (
+                self.theme.stroke_width if self.stroke else 0.0
+            )
+            draw_rect(
+                buf, x, y, g.w, g.h,
+                fill=self.fill or "none",
+                stroke=self.stroke or "none",
+                stroke_width=sw if self.stroke else 0,
+            )
+        self.paint(buf, x, y, g.w, g.h)
+
+
+class Strip(Node):
+    """
+    Alternating horizontal / vertical stripe background.
+
+    Standalone node or `pattern=` on Box/Group (e.g. buffer bands).
+    """
+
+    def __init__(
+        self,
+        *,
+        direction: str = "horizontal",  # horizontal|vertical
+        stripe: float = 6.0,
+        colors: Sequence[str] = ("#d6eaf8", "#ffffff"),
+        opacity: float = 1.0,
+        fill: Optional[str] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        min_w: float = 48.0,
+        min_h: float = 36.0,
+        width: Optional[float] = None,
+        height: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(min_w=min_w, min_h=min_h, **kwargs)
+        self.direction = direction
+        self.stripe = float(stripe)
+        self.colors = tuple(colors)
+        self.opacity = float(opacity)
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.fixed_w = width
+        self.fixed_h = height
+
+    def paint(self, buf: List[str], x: float, y: float, w: float, h: float) -> None:
+        paint_strip(
+            buf, x, y, w, h,
+            direction=self.direction, stripe=self.stripe,
+            colors=self.colors, opacity=self.opacity,
+        )
+
+    def _measure(self) -> Tuple[float, float]:
+        w = self.fixed_w if self.fixed_w is not None else self.min_w
+        h = self.fixed_h if self.fixed_h is not None else self.min_h
+        return w, h
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect
+
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        # Base fill under stripes if provided
+        if self.fill:
+            draw_rect(buf, x, y, g.w, g.h, fill=self.fill, stroke="none", stroke_width=0)
+        self.paint(buf, x, y, g.w, g.h)
+        if self.stroke:
+            sw = self.stroke_width if self.stroke_width is not None else self.theme.stroke_width
+            draw_rect(
+                buf, x, y, g.w, g.h,
+                fill="none", stroke=self.stroke, stroke_width=sw,
+            )
+
+
+def draw_styled_line(buf: List[str], st: Any, x1: float, y1: float, x2: float, y2: float) -> None:
+    """Straight shaft with the resolved end / start heads of ``st`` (ResolvedEdgeStyle)."""
+    from .render_svg import angle_of, draw_head, draw_line
+
+    eh, sh = st.end_head, st.start_head
+    L = math.hypot(x2 - x1, y2 - y1) or 1.0
+    ux, uy = (x2 - x1) / L, (y2 - y1) / L
+    se = min(eh.setback(st.width), L * 0.45) if eh is not None and eh.visible else 0.0
+    ss = min(sh.setback(st.width), L * 0.45) if sh is not None and sh.visible else 0.0
+    draw_line(buf, x1 + ux * ss, y1 + uy * ss, x2 - ux * se, y2 - uy * se, stroke=st.color,
+              stroke_width=st.width, opacity=st.opacity, dasharray=st.dasharray(), marker_end=False)
+    draw_head(buf, x2, y2, angle_of(x1, y1, x2, y2), eh, color=st.color, opacity=st.opacity,
+              stroke_width=st.width)
+    draw_head(buf, x1, y1, angle_of(x2, y2, x1, y1), sh, color=st.color, opacity=st.opacity,
+              stroke_width=st.width)
+
+
+class Arrow(Node):
+    """
+    Connector arrow.
+
+    Heads: ``head=`` / ``tail=`` shape names or ``Head(...)`` (see Edge),
+    ``head_size`` / ``head_length`` / ``head_width`` / ``hollow`` / ``head_fill``.
+
+    - Default: short vertical (or horizontal) shaft with arrowhead — used inside Stack/Row.
+    - loop=True: U-shaped feedback path drawn around a sibling reference box (approx).
+    - label: optional mid-shaft text.
+    """
+
+    loop_span = themed(80.0)
+
+    def __init__(
+        self,
+        label: Optional[str] = None,
+        *,
+        direction: str = "down",  # down|up|left|right
+        length: Optional[float] = None,
+        loop: bool = False,
+        loop_side: str = "right",  # right|left
+        loop_span: Optional[float] = None,
+        color: Optional[str] = None,
+        stroke: Optional[str] = None,
+        opacity: Optional[float] = None,
+        alpha: Optional[float] = None,
+        width: Optional[float] = None,
+        stroke_width: Optional[float] = None,
+        head_size: Optional[float] = None,
+        style: Any = None,
+        head: Any = None,
+        tail: Any = None,
+        head_length: Optional[float] = None,
+        head_width: Optional[float] = None,
+        hollow: Optional[bool] = None,
+        head_fill: Optional[str] = None,
+        label_side: Optional[str] = None,  # above|below (horizontal), left|right (vertical)
+        label_size: Optional[float] = None,
+        label_color: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.tail = tail
+        self.head_length = head_length
+        self.head_width = head_width
+        self.hollow = hollow
+        self.head_fill = head_fill
+        if label_side is not None and label_side not in ("above", "below", "left", "right"):
+            raise ValueError("Arrow label_side must be above|below|left|right")
+        self.label_side = label_side
+        self.label_size = label_size
+        self.label_color = label_color
+        self.label = label
+        self.direction = direction
+        self.length = length
+        self.loop = loop
+        self.loop_side = loop_side
+        self.loop_span = loop_span
+        self.color = color
+        self.stroke = stroke
+        self.opacity = opacity
+        self.alpha = alpha
+        self.width = width
+        self.sw = stroke_width
+        self.head_size = head_size
+        self.line_style = style
+        self.head = head
+
+    def _measure(self) -> Tuple[float, float]:
+        _L = self.theme.L
+        th = self.theme
+        sw = self.sw if self.sw is not None else th.stroke_width
+        if self.loop:
+            # Thin vertical strip; pair with grow=1 in a Row for full-height feedback.
+            return _L(28.0), self.loop_span
+        length = self.length if self.length is not None else _L(22.0)
+        if self.label and self.label_side is not None:
+            lw, lh = self._label_size_wh()
+            gap = th.edge_label_gap * 0.5
+            if self.direction in ("down", "up"):
+                return 12.0 + gap + lw, max(length, lh)
+            return max(length, lw + _L(4)), lh + gap + _L(12.0)
+        label_w, label_h = (0.0, 0.0)
+        if self.label:
+            label_w, label_h = measure_text(self.label, th.font_size * 0.9)
+        if self.direction in ("down", "up"):
+            return max(_L(12.0), label_w + _L(8)), length + (label_h if self.label else 0)
+        return length + (label_w if self.label else 0), max(_L(12.0), label_h + _L(8))
+
+    def _label_fs(self) -> float:
+        return self.label_size if self.label_size is not None else self.theme.font_size * 0.9
+
+    def _label_size_wh(self) -> Tuple[float, float]:
+        return measure_text(self.label or "", self._label_fs())
+
+    def _draw_side_label(self, buf: List[str], x: float, y: float, st: Any) -> None:
+        _L = self.theme.L
+        """Arrow with label_side: shaft + label block beside it (never crossing)."""
+        g = self.geom
+        lw, lh = self._label_size_wh()
+        gap = self.theme.edge_label_gap * 0.5
+        side = self.label_side
+        if self.direction in ("down", "up"):
+            sx = x + _L(6) if side == "right" else x + g.w - _L(6)
+            ya, yb = (y + _L(2), y + g.h - _L(2)) if self.direction == "down" else (y + g.h - _L(2), y + _L(2))
+            seg = (sx, ya, sx, yb)
+            lx = sx + _L(6) + gap if side == "right" else sx - _L(6) - gap - lw
+            ly = y + (g.h - lh) / 2
+            align = "left" if side == "right" else "right"
+        else:
+            sy = y + g.h - _L(6) if side == "above" else y + _L(6)
+            xa, xb = (x + _L(2), x + g.w - _L(2)) if self.direction == "right" else (x + g.w - _L(2), x + _L(2))
+            seg = (xa, sy, xb, sy)
+            lx = x + (g.w - lw) / 2
+            ly = y if side == "above" else y + _L(12.0) + gap
+            align = "center"
+        self._shaft(buf, st, *seg)
+        t = Text(self.label, font_size=self._label_fs(), color=self.label_color or st.color,
+                 align=align, theme=self._theme)
+        t.geom = BoxGeom(lx, ly, lw, lh)
+        t.draw(buf)
+
+    def _shaft(self, buf: List[str], st: Any, x1: float, y1: float, x2: float, y2: float) -> None:
+        draw_styled_line(buf, st, x1, y1, x2, y2)
+
+    def _style(self):
+        from .styles import resolve_edge_style
+        return resolve_edge_style(
+            self.theme,
+            color=self.color,
+            stroke=self.stroke,
+            opacity=self.opacity,
+            alpha=self.alpha,
+            width=self.width,
+            stroke_width=self.sw,
+            head_size=self.head_size,
+            style=self.line_style,
+            head=self.head,
+            tail=self.tail,
+            head_length=self.head_length,
+            head_width=self.head_width,
+            hollow=self.hollow,
+            head_fill=self.head_fill,
+        )
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        _L = self.theme.L
+        from .render_svg import draw_text
+
+        g = self.geom
+        th = self.theme
+        st = self._style()
+        x, y = g.x + ox, g.y + oy
+
+        def shaft(x1, y1, x2, y2):
+            draw_styled_line(buf, st, x1, y1, x2, y2)
+
+        if self.loop:
+            cx = x + g.w / 2
+            shaft(cx, y, cx, y + g.h)
+            return
+        if self.label and self.label_side is not None:
+            self._draw_side_label(buf, x, y, st)
+            return
+
+        if self.direction == "down":
+            cx = x + g.w / 2
+            y1, y2 = y + _L(2), y + g.h - _L(2)
+            shaft(cx, y1, cx, y2)
+            if self.label:
+                tw, _ = measure_text(self.label, th.font_size * 0.9)
+                draw_text(buf, self.label, cx - tw / 2 + _L(10), (y1 + y2) / 2,
+                          font_size=th.font_size * 0.9, fill=st.color, opacity=st.opacity)
+        elif self.direction == "up":
+            cx = x + g.w / 2
+            shaft(cx, y + g.h - _L(2), cx, y + _L(2))
+        elif self.direction == "right":
+            cy = y + g.h / 2
+            x1, x2 = x + _L(2), x + g.w - _L(2)
+            shaft(x1, cy, x2, cy)
+            if self.label:
+                tw, _ = measure_text(self.label, th.font_size * 0.9)
+                draw_text(buf, self.label, (x1 + x2) / 2 - tw / 2, cy - _L(4),
+                          font_size=th.font_size * 0.9, fill=st.color, opacity=st.opacity)
+        else:
+            cy = y + g.h / 2
+            shaft(x + g.w - _L(2), cy, x + _L(2), cy)
+
+
+class LoopArrow(Node):
+    """
+    Feedback loop drawn beside content. Place as an overlay sibling via
+    Figure annotations, or use alongside a Row([content, LoopArrow(...)]).
+    For MVP, draws a path from bottom to top along its allocated strip.
+    """
+
+    def __init__(
+        self,
+        *,
+        side: str = "right",
+        strip: float = 36.0,
+        width: Optional[float] = None,
+        label: Optional[str] = None,
+        color: Optional[str] = None,
+        stroke: Optional[str] = None,
+        opacity: Optional[float] = None,
+        alpha: Optional[float] = None,
+        stroke_width: Optional[float] = None,
+        head_size: Optional[float] = None,
+        style: Optional[str] = None,
+        head: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        # BC: width= used to mean strip; if width looks like a strip (>= 10) and
+        # stroke_width unset, treat it as strip. Prefer strip= + width= for stroke.
+        super().__init__(**kwargs)
+        self.side = side
+        strip_w = strip
+        sw = stroke_width if stroke_width is not None else None
+        if width is not None and sw is None and width >= 10:
+            strip_w = width
+            sw = None
+        elif width is not None:
+            sw = width if sw is None else sw
+        self.strip_width = strip_w
+        self.label = label
+        self.color = color
+        self.stroke = stroke
+        self.opacity = opacity
+        self.alpha = alpha
+        self.sw = sw
+        self.width = sw  # stroke width alias for _style
+        self.head_size = head_size
+        self.line_style = style
+        self.head = head
+        self.grow = kwargs.get("grow", 1.0)
+
+    def _measure(self) -> Tuple[float, float]:
+        return self.strip_width, 40.0
+
+    def _label_fs(self) -> float:
+        return self.label_size if self.label_size is not None else self.theme.font_size * 0.9
+
+    def _label_size_wh(self) -> Tuple[float, float]:
+        return measure_text(self.label or "", self._label_fs())
+
+    def _draw_side_label(self, buf: List[str], x: float, y: float, st: Any) -> None:
+        """Arrow with label_side: shaft + label block beside it (never crossing)."""
+        g = self.geom
+        lw, lh = self._label_size_wh()
+        gap = self.theme.edge_label_gap * 0.5
+        side = self.label_side
+        if self.direction in ("down", "up"):
+            sx = x + 6 if side == "right" else x + g.w - 6
+            ya, yb = (y + 2, y + g.h - 2) if self.direction == "down" else (y + g.h - 2, y + 2)
+            seg = (sx, ya, sx, yb)
+            lx = sx + 6 + gap if side == "right" else sx - 6 - gap - lw
+            ly = y + (g.h - lh) / 2
+            align = "left" if side == "right" else "right"
+        else:
+            sy = y + g.h - 6 if side == "above" else y + 6
+            xa, xb = (x + 2, x + g.w - 2) if self.direction == "right" else (x + g.w - 2, x + 2)
+            seg = (xa, sy, xb, sy)
+            lx = x + (g.w - lw) / 2
+            ly = y if side == "above" else y + 12.0 + gap
+            align = "center"
+        self._shaft(buf, st, *seg)
+        t = Text(self.label, font_size=self._label_fs(), color=self.label_color or st.color,
+                 align=align, theme=self._theme)
+        t.geom = BoxGeom(lx, ly, lw, lh)
+        t.draw(buf)
+
+    def _shaft(self, buf: List[str], st: Any, x1: float, y1: float, x2: float, y2: float) -> None:
+        draw_styled_line(buf, st, x1, y1, x2, y2)
+
+    def _style(self):
+        from .styles import resolve_edge_style
+        return resolve_edge_style(
+            self.theme,
+            color=self.color,
+            stroke=self.stroke,
+            opacity=self.opacity,
+            alpha=self.alpha,
+            width=self.sw,
+            stroke_width=self.sw,
+            head_size=self.head_size,
+            style=self.line_style,
+            head=self.head,
+        )
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import angle_of, draw_arrowhead, draw_path, draw_text
+
+        g = self.geom
+        th = self.theme
+        st = self._style()
+        x, y = g.x + ox, g.y + oy
+        if self.side == "right":
+            x1 = x + 4
+            x2 = x + g.w - 6
+            pts = [(x1, y + g.h - 4), (x2, y + g.h - 4), (x2, y + 4), (x1, y + 4)]
+        else:
+            x1 = x + g.w - 4
+            x2 = x + 6
+            pts = [(x1, y + g.h - 4), (x2, y + g.h - 4), (x2, y + 4), (x1, y + 4)]
+        d = f"M {pts[0][0]:.2f},{pts[0][1]:.2f} " + " ".join(
+            f"L {px:.2f},{py:.2f}" for px, py in pts[1:]
+        )
+        draw_path(
+            buf, d, stroke=st.color, stroke_width=st.width,
+            opacity=st.opacity, dasharray=st.dasharray(),
+        )
+        if st.head != "none":
+            draw_arrowhead(
+                buf, pts[-1][0], pts[-1][1],
+                angle_of(pts[-2][0], pts[-2][1], pts[-1][0], pts[-1][1]),
+                size=st.head_size, color=st.color, opacity=st.opacity, shape=st.head,
+            )
+        if self.label:
+            tw, _ = measure_text(self.label, th.font_size * 0.85)
+            draw_text(
+                buf, self.label, x + (g.w - tw) / 2, y + g.h / 2,
+                font_size=th.font_size * 0.85, fill=st.color, opacity=st.opacity,
+            )
+
+
+# ---- colour maps (heatmaps) ---------------------------------------------------
+
+CMAPS: Dict[str, List[str]] = {
+    "Blues": ["#f7fbff", "#c6dbef", "#6baed6", "#2171b5", "#08306b"],
+    "Reds": ["#fff5f0", "#fcbba1", "#fb6a4a", "#cb181d", "#67000d"],
+    "Greens": ["#f7fcf5", "#c7e9c0", "#74c476", "#238b45", "#00441b"],
+    "Oranges": ["#fff5eb", "#fdd0a2", "#fd8d3c", "#d94801", "#7f2704"],
+    "Purples": ["#fcfbfd", "#dadaeb", "#9e9ac8", "#6a51a3", "#3f007d"],
+    "Greys": ["#ffffff", "#d9d9d9", "#969696", "#525252", "#000000"],
+    "viridis": ["#440154", "#3b528b", "#21918c", "#5ec962", "#fde725"],
+    "magma": ["#000004", "#51127c", "#b73779", "#fc8961", "#fcfdbf"],
+    "RdBu": ["#b2182b", "#ef8a62", "#f7f7f7", "#67a9cf", "#2166ac"],
+    "YlOrRd": ["#ffffcc", "#fed976", "#fd8d3c", "#e31a1c", "#800026"],
+}
+
+
+def _hex_rgb(c: str) -> Tuple[float, float, float]:
+    c = c.lstrip("#")
+    if len(c) == 3:
+        c = "".join(ch * 2 for ch in c)
+    return int(c[0:2], 16), int(c[2:4], 16), int(c[4:6], 16)
+
+
+def cmap_color(cmap: Any, t: float) -> str:
+    """Colour at ``t`` ∈ [0, 1] of a named map (see ``CMAPS``) or a list of stops."""
+    stops = CMAPS[cmap] if isinstance(cmap, str) else list(cmap)
+    if isinstance(cmap, str) and cmap not in CMAPS:
+        raise ValueError(f"unknown cmap {cmap!r}; one of {sorted(CMAPS)} or a list of colours")
+    t = 0.0 if t != t else min(1.0, max(0.0, float(t)))
+    if len(stops) == 1:
+        return stops[0]
+    pos = t * (len(stops) - 1)
+    i = min(int(pos), len(stops) - 2)
+    f = pos - i
+    a, b = _hex_rgb(stops[i]), _hex_rgb(stops[i + 1])
+    r, g, bl = (round(a[k] + (b[k] - a[k]) * f) for k in range(3))
+    return f"#{r:02x}{g:02x}{bl:02x}"
+
+
+def _luma(c: str) -> float:
+    try:
+        r, g, b = _hex_rgb(c)
+    except Exception:
+        return 1.0
+    return (0.299 * r + 0.587 * g + 0.114 * b) / 255.0
+
+
+def _cell_lookup(spec: Any, r: int, c: int, rows: int, cols: int = 0) -> Any:
+    """Per-cell value from callable(r, c) / {(r, c): v} / 2-D list / 1-D list (a 1-row
+    strip, or — v0.13.0 — a 1-column strip: ``Matrix(3, 1, cell_labels=["", "x", ""])``)."""
+    if spec is None:
+        return None
+    if callable(spec):
+        return spec(r, c)
+    if isinstance(spec, dict):
+        return spec.get((r, c))
+    try:
+        row = spec[r]
+    except (IndexError, TypeError, KeyError):
+        return None
+    if isinstance(row, (list, tuple)):
+        return row[c] if c < len(row) else None
+    if cols == 1 and rows > 1:  # 1-D list down a single column
+        return row if c == 0 else None
+    if rows == 1 and r == 0:  # 1-D list for a single-row strip
+        try:
+            return spec[c]
+        except (IndexError, TypeError):
+            return None
+    return None
+
+
+_MATRIX_LABEL_POS = ("left", "right", "top", "bottom", "top-right", "top-left", "bottom-right")
+
+
+class Matrix(Node):
+    """
+    Grid of cells: attention maps, KV blocks, token strips, heatmaps and tables.
+
+    Geometry: square ``cell`` (default) or ``cell_w`` / ``cell_h`` (a number or
+    ``"content"`` — each column as wide as its widest label, e.g. token strips).
+    v0.12.0: ``cell_w`` / ``cell_h`` may also be a list — one size per column / row
+    (``cell_h=[12, 12, 24]``). ``row_splits=[3]`` / ``col_splits=[2, 4]`` open an
+    extra gap before those row / column indices (block-sparse layouts);
+    ``split_style="gap"`` (default) leaves it empty, ``"line"`` / ``"dashed"`` /
+    ``"dotted"`` draw a divider through it; ``split_gap=`` sets its width (0 allowed).
+    v0.13.0: ``continuous=True`` draws one block — no cell gaps or rounded cells, a
+    single outer frame, internal rules only at the splits (``split_style`` defaults to
+    ``"dashed"`` there): ``Matrix(6, 2, continuous=True, row_splits=[3, 4])``.
+    ``label=`` sits at ``label_pos`` = ``"left"`` (default) | ``"right"`` | ``"top"`` |
+    ``"bottom"`` | ``"top-right"`` (a superscript-style corner label, e.g. a
+    transpose ``label="T", label_pos="top-right"``) | ``"top-left"`` | ``"bottom-right"``.
+    Corner labels default to the theme's script size; ``label_size=`` overrides.
+    ``row_span(i, j)`` / ``col_span(i, j)`` give anchor pairs for ``Brace(span=)`` /
+    ``Dim`` over rows / columns i..j. Labels cut with "…" to fit a cell are reported
+    by lint CF-TXT-011.
+
+    Per-cell content (each spec may be a callable ``(r, c) -> v``, a dict
+    ``{(r, c): v}``, a 2-D list, or a 1-D list for a single-row or single-column strip):
+
+    * ``cell_labels`` — text (rich markup works: ``"**K**"``, ``"[color=#c00]x[/]"``)
+    * ``cell_fill`` — colour; ``heat=`` values + ``cmap`` / ``vmin`` / ``vmax``
+      colour cells by value (``heat_labels="{:.2f}"`` prints them; ``colorbar=True``
+      adds a scale bar on the right, ``"bottom"`` below)
+    * ``cell_marks`` — vector glyphs ``check | cross | dot | circle | dash``
+    * ``cell_border`` — ``solid | dashed | dotted | "4 2"`` per cell (``border=`` = all)
+    * ``cell_style`` — dict per cell overriding fill / text_color / weight / border /
+      stroke / mark at once
+
+    Tables: ``header_rows`` / ``header_cols`` (counts) give the first rows / cols
+    ``header_fill`` and bold text. ``outlines=[(r0, c0, r1, c1[, colour])]`` frame
+    cell blocks. highlight_rows / highlight_cols, row/col labels and a side label
+    work as before. ``legend={colour: "meaning"}`` feeds an auto Legend.
+    """
+
+    cell = themed(16.0)
+    cell_pad = themed(4.0)
+    gap = themed(2.0)
+    highlight_width = themed(2.5, "SW")
+    cell_stroke_width = themed(1.2, "SW")
+    cell_radius = themed(2.0)
+    outline_width = themed(2.0, "SW")
+    stroke = theme_default("stroke")
+    highlight_stroke = theme_default("highlight")
+    label_gap = theme_default("label_gap")
+    cell_text_color = theme_default("text_color")
+
+    def __init__(
+        self,
+        rows: int = 3,
+        cols: int = 3,
+        *,
+        cell: Optional[float] = None,
+        cell_w: Any = None,
+        cell_h: Any = None,
+        cell_pad: Optional[float] = None,
+        gap: Optional[float] = None,
+        fill: str = "#c9b3e6",
+        stroke: Optional[str] = None,
+        highlight_rows: Optional[Sequence[int]] = None,
+        highlight_cols: Optional[Sequence[int]] = None,
+        highlight_stroke: Optional[str] = None,
+        highlight_width: Optional[float] = None,
+        cell_labels: Any = None,
+        row_labels: Optional[Sequence[str]] = None,
+        col_labels: Optional[Sequence[str]] = None,
+        label: Optional[str] = None,
+        label_pos: str = "left",  # left|right|top|bottom
+        label_gap: Optional[float] = None,
+        aspect: Optional[float] = None,
+        w: Optional[Any] = None,
+        h: Optional[Any] = None,
+        max_w: Optional[float] = None,
+        max_h: Optional[float] = None,
+        cell_fill: Any = None,
+        cell_stroke_width: Optional[float] = None,
+        cell_radius: Optional[float] = None,
+        cell_font_size: Optional[float] = None,
+        cell_text_color: Optional[str] = None,
+        cell_weight: str = "normal",
+        cell_mono: bool = False,
+        cell_marks: Any = None,
+        mark_color: Optional[str] = None,
+        cell_border: Any = None,
+        cell_style: Any = None,
+        heat: Any = None,
+        cmap: Any = "Blues",
+        vmin: Optional[float] = None,
+        vmax: Optional[float] = None,
+        heat_labels: Any = None,
+        colorbar: Any = False,
+        colorbar_label: Optional[str] = None,
+        colorbar_ticks: int = 3,
+        colorbar_format: str = "{:g}",
+        header_rows: int = 0,
+        header_cols: int = 0,
+        header_fill: str = "#e8e8e8",
+        header_weight: str = "bold",
+        outlines: Optional[Sequence[Any]] = None,
+        outline_color: Optional[str] = None,
+        outline_width: Optional[float] = None,
+        outline_border: Any = None,
+        label_weight: str = "bold",
+        label_size: Optional[float] = None,
+        row_splits: Optional[Sequence[int]] = None,
+        col_splits: Optional[Sequence[int]] = None,
+        split_style: str = "gap",
+        split_gap: Optional[float] = None,
+        continuous: bool = False,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(w=w, h=h, aspect=aspect, max_w=max_w, max_h=max_h, **kwargs)
+        from ._validate import check_enum
+        split_style = check_enum("primitives(split_style)", split_style, ("gap", "line", "solid", "dashed", "dotted"))
+        from ._validate import check_enum
+        label_pos = check_enum("primitives(label_pos)", label_pos, _MATRIX_LABEL_POS)
+        # v0.13.0: one continuous block — no gaps, square cells, a single outer frame,
+        # internal rules only at the splits (dashed by default)
+        self.continuous = bool(continuous)
+        if self.continuous:
+            if gap is None:
+                gap = 0.0
+            if cell_radius is None:
+                cell_radius = 0.0
+            if split_gap is None:
+                split_gap = 0.0
+            if split_style == "gap":
+                split_style = "dashed"
+        self.row_splits = sorted({int(i) for i in (row_splits or []) if 0 < int(i) < int(rows)})
+        self.col_splits = sorted({int(i) for i in (col_splits or []) if 0 < int(i) < int(cols)})
+        self.split_style = "line" if split_style == "solid" else split_style
+        self.split_gap = split_gap
+        for nm, v, n in (("cell_w", cell_w, cols), ("cell_h", cell_h, rows)):
+            if isinstance(v, (list, tuple)):
+                if len(v) != int(n):
+                    raise ValueError(f"{nm} list needs one size per {'column' if nm == 'cell_w' else 'row'} "
+                                     f"({int(n)}), got {len(v)}")
+                if any(float(x) <= 0 for x in v):
+                    raise ValueError(f"{nm} sizes must be positive")
+        # cell_fill: per-cell colour — callable(r, c) -> colour|None, 2-D list,
+        # or {(r, c): colour}; None / missing entries fall back to ``fill``.
+        if cell_fill is not None and not isinstance(cell_fill, (str, list, tuple, dict)) and not callable(cell_fill):
+            raise ValueError("Matrix(cell_fill): expected a colour, sequence, mapping or callable")
+        self.cell_fill = (lambda r, c: cell_fill) if isinstance(cell_fill, str) else cell_fill
+        self.cell_stroke_width = cell_stroke_width
+        self.cell_radius = cell_radius
+        self.cell_font_size = cell_font_size
+        self.cell_text_color = cell_text_color
+        self.cell_weight = cell_weight
+        self.cell_mono = bool(cell_mono)
+        self.cell_marks = cell_marks
+        self.mark_color = mark_color
+        self.cell_border = cell_border
+        self.cell_style = cell_style
+        self.label_weight = label_weight
+        self.label_size = label_size
+        self.rows = int(rows)
+        self.cols = int(cols)
+        self.cell = cell
+        self.cell_w = cell_w
+        self.cell_h = cell_h
+        self.cell_pad = cell_pad
+        self.gap = gap
+        self.fill = fill
+        self.stroke = stroke
+        self.highlight_rows = set(highlight_rows or [])
+        self.highlight_cols = set(highlight_cols or [])
+        self.highlight_stroke = highlight_stroke
+        self.highlight_width = highlight_width
+        self.cell_labels = cell_labels
+        self.row_labels = row_labels
+        self.col_labels = col_labels
+        self.label = label
+        self.label_pos = label_pos
+        self.label_gap = None if label_gap is None else float(label_gap)
+        self.heat = heat
+        self.cmap = cmap
+        self.heat_labels = heat_labels
+        self.colorbar = "right" if colorbar is True else (colorbar or None)
+        if self.colorbar not in (None, "right", "bottom"):
+            raise ValueError("colorbar must be True, 'right', 'bottom' or False")
+        self.colorbar_label = colorbar_label
+        self.colorbar_ticks = max(2, int(colorbar_ticks))
+        self.colorbar_format = colorbar_format
+        self.header_rows = int(header_rows)
+        self.header_cols = int(header_cols)
+        self.header_fill = header_fill
+        self.header_weight = header_weight
+        self.outlines = list(outlines or [])
+        self.outline_color = outline_color
+        self.outline_width = outline_width
+        self.outline_border = outline_border
+        self.vmin, self.vmax = vmin, vmax
+        if heat is not None:
+            vals = [v for r in range(self.rows) for c in range(self.cols)
+                    for v in [_cell_lookup(heat, r, c, self.rows, self.cols)] if v is not None]
+            if not vals:
+                raise ValueError("heat= has no values for this grid")
+            self.vmin = min(vals) if vmin is None else float(vmin)
+            self.vmax = max(vals) if vmax is None else float(vmax)
+        if self.cell_w == "content" or self.cell_h == "content":
+            pass
+        elif self.cell_w is not None and not isinstance(self.cell_w, (list, tuple)) \
+                and float(self.cell_w) <= 0:
+            raise ValueError("cell_w must be positive, a list or 'content'")
+
+    # ---- per-cell resolution -------------------------------------------------
+    def _style(self, r: int, c: int) -> dict:
+        st = _cell_lookup(self.cell_style, r, c, self.rows, self.cols)
+        return dict(st) if isinstance(st, dict) else {}
+
+    def is_header(self, r: int, c: int) -> bool:
+        return r < self.header_rows or c < self.header_cols
+
+    def heat_at(self, r: int, c: int) -> Optional[float]:
+        return _cell_lookup(self.heat, r, c, self.rows, self.cols) if self.heat is not None else None
+
+    def fill_at(self, r: int, c: int) -> str:
+        """Resolved fill colour of cell (r, c)."""
+        st = self._style(r, c)
+        if st.get("fill"):
+            return st["fill"]
+        col = _cell_lookup(self.cell_fill, r, c, self.rows, self.cols)
+        if col:
+            return col
+        v = self.heat_at(r, c)
+        if v is not None:
+            span = (self.vmax - self.vmin) or 1.0
+            return cmap_color(self.cmap, (v - self.vmin) / span)
+        if self.is_header(r, c):
+            return self.header_fill
+        return self.fill
+
+    def label_at(self, r: int, c: int) -> Optional[str]:
+        lab = _cell_lookup(self.cell_labels, r, c, self.rows, self.cols)
+        if lab is None and self.heat_labels and self.heat is not None:
+            v = self.heat_at(r, c)
+            if v is not None:
+                fmt = self.heat_labels if isinstance(self.heat_labels, str) else "{:.2g}"
+                lab = fmt.format(v)
+        return None if lab is None or lab == "" else str(lab)
+
+    def mark_at(self, r: int, c: int) -> Optional[str]:
+        st = self._style(r, c)
+        if st.get("mark"):
+            return st["mark"]
+        m = _cell_lookup(self.cell_marks, r, c, self.rows, self.cols)
+        if m is True:
+            return "check"
+        if m is False:
+            return "cross"
+        return m or None
+
+    def border_at(self, r: int, c: int) -> Any:
+        st = self._style(r, c)
+        if "border" in st:
+            return st["border"]
+        b = _cell_lookup(self.cell_border, r, c, self.rows, self.cols)
+        return b if b is not None else self.border
+
+    def _cell_fs(self) -> float:
+        if self.cell_font_size is not None:
+            return float(self.cell_font_size)
+        if isinstance(self.cell_h, (list, tuple)):
+            h = min(float(v) for v in self.cell_h)
+        else:
+            h = self.cell if self.cell_h in (None, "content") else float(self.cell_h)
+        if self.cell_w != "content" and self.cell_h != "content" and (
+                "_track" in self.__dict__ or "_track_r" in self.__dict__):
+            # v0.11.0: shared tracks resized the cells; the label font follows them
+            ws = self._col_ws() + self._row_hs()
+            h = max(h, min(ws)) if ws else h
+        return min(h * 0.55, self.theme.F(11.0))
+
+    def _label_w(self, r: int, c: int) -> float:
+        lab = self.label_at(r, c)
+        if not lab:
+            return 0.0
+        st = self._style(r, c)
+        weight = st.get("weight") or (self.header_weight if self.is_header(r, c) else self.cell_weight)
+        return measure_text(lab, self._cell_fs(), mono=self.cell_mono, weight=weight)[0]
+
+    # ---- geometry ------------------------------------------------------------
+    def _col_ws(self) -> List[float]:
+        track = self.__dict__.get("_track")
+        if track is not None:  # align_columns(): shared column tracks
+            return list(track["ws"])
+        rtrack = self.__dict__.get("_track_r")
+        if rtrack is not None and rtrack.get("h"):  # align_rows() kept square cells square
+            return [float(rtrack["h"])] * self.cols
+        cached = self.__dict__.get("_cw_cache")
+        if cached is not None and cached[0] == self._measured:
+            return cached[1]
+        if self.cell_w == "content":
+            out = []
+            for c in range(self.cols):
+                need = max((self._label_w(r, c) for r in range(self.rows)), default=0.0)
+                out.append(max(need + 2 * self.cell_pad, self._cell_fs() * 1.4))
+        elif isinstance(self.cell_w, (list, tuple)):
+            out = [float(v) for v in self.cell_w]
+        else:
+            out = [float(self.cell_w if self.cell_w is not None else self.cell)] * self.cols
+        self.__dict__["_cw_cache"] = (self._measured, out)
+        return out
+
+    def _row_hs(self) -> List[float]:
+        rtrack = self.__dict__.get("_track_r")
+        if rtrack is not None:  # align_rows(): shared row tracks
+            return list(rtrack["ws"])
+        track = self.__dict__.get("_track")
+        if track is not None and track.get("h"):
+            return [float(track["h"])] * self.rows
+        if self.cell_h == "content" or (self.cell_h is None and self.cell_w == "content"):
+            h = self._cell_fs() * 1.25 + 1.2 * self.cell_pad
+        elif isinstance(self.cell_h, (list, tuple)):
+            return [float(v) for v in self.cell_h]
+        elif self.cell_h is not None:
+            h = float(self.cell_h)
+        else:
+            h = self.cell
+        return [h] * self.rows
+
+    def _col_w(self, c: int) -> float:
+        ws = self._col_ws()
+        return ws[max(0, min(self.cols - 1, c))]
+
+    def _row_h(self, r: int) -> float:
+        hs = self._row_hs()
+        return hs[max(0, min(self.rows - 1, r))]
+
+    def _split_w(self) -> float:
+        """Extra room a row / column split adds (on top of the normal ``gap``)."""
+        if self.split_gap is not None:
+            return float(self.split_gap)
+        return self.theme.L(4.0)
+
+    def _col_x(self, c: int) -> float:
+        """Offset of column ``c``'s left edge from the grid origin."""
+        ws = self._col_ws()
+        c = max(0, min(self.cols, c))
+        return sum(ws[:c]) + c * self.gap + sum(1 for k in self.col_splits if k <= c) * self._split_w()
+
+    def _row_y(self, r: int) -> float:
+        hs = self._row_hs()
+        r = max(0, min(self.rows, r))
+        return sum(hs[:r]) + r * self.gap + sum(1 for k in self.row_splits if k <= r) * self._split_w()
+
+    def _grid_size(self) -> Tuple[float, float]:
+        w = sum(self._col_ws()) + max(0, self.cols - 1) * self.gap + len(self.col_splits) * self._split_w()
+        h = sum(self._row_hs()) + max(0, self.rows - 1) * self.gap + len(self.row_splits) * self._split_w()
+        return w, h
+
+    def row_span(self, i: int, j: int) -> Tuple[Any, Any]:
+        """Anchor pair covering rows ``i``..``j`` (for ``Brace(span=)`` / ``Dim``)."""
+        return (self.row_anchor(min(i, j)), self.row_anchor(max(i, j)))
+
+    def col_span(self, i: int, j: int) -> Tuple[Any, Any]:
+        """Anchor pair covering columns ``i``..``j`` (for ``Brace(span=)`` / ``Dim``)."""
+        return (self.col_anchor(min(i, j)), self.col_anchor(max(i, j)))
+
+    def _colorbar_space(self) -> Tuple[float, float]:
+        """(right, bottom) extra space for the colorbar."""
+        if not self.colorbar or self.heat is None:
+            return 0.0, 0.0
+        fs = self.theme.small_size if self.theme.font_sizes else self.theme.font_size * 0.75
+        ticks = self._colorbar_tick_values()
+        tw = max(measure_text(self.colorbar_format.format(t), fs)[0] for t in ticks)
+        lab_w = lab_h = 0.0
+        if self.colorbar_label:
+            lab_w, lab_h = measure_text(self.colorbar_label, fs)
+        if self.colorbar == "right":
+            L = self.theme.L
+            return L(8 + 10 + 3) + tw + (lab_h + L(4) if self.colorbar_label else 0.0), 0.0
+        L = self.theme.L
+        return 0.0, L(8 + 8 + 3) + fs * 1.2 + (lab_h + L(2) if self.colorbar_label else 0.0)
+
+    def _colorbar_tick_values(self) -> List[float]:
+        n = self.colorbar_ticks
+        lo, hi = float(self.vmin), float(self.vmax)
+        return [lo + (hi - lo) * i / (n - 1) for i in range(n)]
+
+    def _label_space(self) -> Tuple[float, float, float, float]:
+        """left, top, right, bottom padding for labels (uses label_gap)."""
+        th = self.theme
+        lg = self.label_gap
+        left = top = right = bottom = 0.0
+        fs = th.font_size * 0.9
+        if self.row_labels:
+            max_w = max(measure_text(s, fs)[0] for s in self.row_labels)
+            left = max(left, max_w + lg)
+        if self.col_labels:
+            top = max(top, fs * 1.2 + lg)
+        cb_r, cb_b = self._colorbar_space()
+        if self.label:
+            lfs = self._label_fs()
+            tw, thh = measure_text(self.label, lfs, weight=self.label_weight)
+            if self.label_pos in ("top-right", "top-left", "bottom-right"):
+                cg = lg * 0.4
+                if self.label_pos == "top-left":
+                    left = max(left, tw + cg)
+                else:
+                    right = max(right, tw + cg)
+                if self.label_pos == "bottom-right":
+                    bottom = max(bottom, lfs * 0.45)
+                else:
+                    top = max(top, 0.0)
+            elif self.label_pos == "left":
+                left = max(left, tw + lg)
+            elif self.label_pos == "right":
+                right = max(right, tw + lg)
+            elif self.label_pos == "top":
+                top = max(top, thh + lg)
+            else:
+                bottom = max(bottom, thh + lg)
+        if self.label and self.label_pos == "right":
+            right += cb_r
+        else:
+            right = max(right, cb_r)
+        if self.label and self.label_pos == "bottom":
+            bottom += cb_b
+        else:
+            bottom = max(bottom, cb_b)
+        return left, top, right, bottom
+
+    def _label_fs(self) -> float:
+        th = self.theme
+        if self.label_size is not None:
+            return float(self.label_size)
+        if self.label_pos in ("top-right", "top-left", "bottom-right"):
+            return th.script_size(th.font_size)
+        return th.font_size
+
+    def _measure(self) -> Tuple[float, float]:
+        self.__dict__.pop("_cw_cache", None)
+        gw, gh = self._grid_size()
+        l, t, r, b = self._label_space()
+        return gw + l + r, gh + t + b
+
+    def _grid_origin(self) -> Tuple[float, float]:
+        """Top-left of the cell grid inside geom (matches draw())."""
+        g = self.geom
+        l, t, r, b = self._label_space()
+        gw, gh = self._grid_size()
+        gx = g.x + l + max(0.0, (g.w - l - r - gw) / 2)
+        gy = g.y + t + max(0.0, (g.h - t - b - gh) / 2)
+        return gx, gy
+
+    def _row_center_y(self, row: int) -> float:
+        _gx, gy = self._grid_origin()
+        row = max(0, min(self.rows - 1, row))
+        return gy + self._row_y(row) + self._row_h(row) / 2
+
+    def _col_center_x(self, col: int) -> float:
+        gx, _gy = self._grid_origin()
+        col = max(0, min(self.cols - 1, col))
+        return gx + self._col_x(col) + self._col_w(col) / 2
+
+    def col_at(self, x: float) -> int:
+        """Index of the column whose centre is nearest to page coordinate ``x``."""
+        return min(range(self.cols), key=lambda c: abs(self._col_center_x(c) - x))
+
+    def row_at(self, y: float) -> int:
+        return min(range(self.rows), key=lambda r: abs(self._row_center_y(r) - y))
+
+    def resolve_row_port(self, row: int, side: str = "right") -> Tuple[float, float, str]:
+        gx, gy = self._grid_origin()
+        gw, _gh = self._grid_size()
+        cy = self._row_center_y(row)
+        half = self._row_h(row) / 2
+        side = (side or "right").replace("-", "_")
+        # outer_left / outer_right: the node's outer edge (beyond row labels), so
+        # arrowheads stop before the labels instead of covering them
+        if side == "outer_left":
+            return self.geom.x, cy, "left"
+        if side == "outer_right":
+            return self.geom.right, cy, "right"
+        if side == "left":
+            return gx, cy, "left"
+        if side == "right":
+            return gx + gw, cy, "right"
+        if side == "center":
+            return gx + gw / 2, cy, "right"
+        # top/bottom of that row's cell strip
+        if side == "top":
+            return gx + gw / 2, cy - half, "up"
+        return gx + gw / 2, cy + half, "down"
+
+    def resolve_col_port(self, col: int, side: str = "top") -> Tuple[float, float, str]:
+        gx, gy = self._grid_origin()
+        _gw, gh = self._grid_size()
+        cx = self._col_center_x(col)
+        half = self._col_w(col) / 2
+        side = side or "top"
+        if side == "top":
+            return cx, gy, "up"
+        if side == "bottom":
+            return cx, gy + gh, "down"
+        if side == "left":
+            return cx - half, gy + gh / 2, "left"
+        if side == "right":
+            return cx + half, gy + gh / 2, "right"
+        return cx, gy + gh / 2, "down"
+
+    def resolve_cell_port(
+        self, row: int, col: int, side: str = "right"
+    ) -> Tuple[float, float, str]:
+        cx = self._col_center_x(col)
+        cy = self._row_center_y(row)
+        hw, hh = self._col_w(col) / 2, self._row_h(row) / 2
+        if side == "left":
+            return cx - hw, cy, "left"
+        if side == "right":
+            return cx + hw, cy, "right"
+        if side == "top":
+            return cx, cy - hh, "up"
+        if side == "bottom":
+            return cx, cy + hh, "down"
+        return cx, cy, "right"
+
+    def row_port(self, row: int, side: str = "right") -> "Port":
+        """Anchor at the center of matrix row `row` on the given side of the grid.
+
+        side: left|right|center|top|bottom, or outer_left|outer_right (outside the
+        row labels / side label)."""
+        from .edges import Port
+
+        return Port(self, kind="row", side=side, index=row)
+
+    def col_port(self, col: int, side: str = "top") -> "Port":
+        """Anchor at the center of matrix column `col` on the given side of the grid."""
+        from .edges import Port
+
+        return Port(self, kind="col", side=side, index=col)
+
+    def cell_port(self, row: int, col: int, side: str = "right") -> "Port":
+        """Anchor on one side of cell (row, col)."""
+        from .edges import Port
+
+        return Port(self, kind="cell", side=side, index=row, col_index=col)
+
+    # ---- constraint anchors (coordinate-free) ---------------------------------
+    def row_anchor(self, row: int) -> "MatrixRowRef":
+        """Anchor set for row ``row``: ``.cy`` / ``.top`` / ``.bottom`` (row strip),
+        ``.left`` / ``.right`` (grid edges). Use with same_y / align / place."""
+        from .constraints import MatrixRowRef
+
+        return MatrixRowRef(self, row)
+
+    def col_anchor(self, col: int) -> "MatrixColRef":
+        from .constraints import MatrixColRef
+
+        return MatrixColRef(self, col)
+
+    def cell_anchor(self, row: int, col: int) -> "MatrixCellRef":
+        from .constraints import MatrixCellRef
+
+        return MatrixCellRef(self, row, col)
+
+    def resolve_cell_range_port(
+        self, r0: int, r1: int, side: str = "right"
+    ) -> Tuple[float, float, str]:
+        """Midpoint of an inclusive row range on the given grid side."""
+        r0 = max(0, min(self.rows - 1, int(r0)))
+        r1 = max(0, min(self.rows - 1, int(r1)))
+        if r1 < r0:
+            r0, r1 = r1, r0
+        y0 = self._row_center_y(r0)
+        y1 = self._row_center_y(r1)
+        cy = (y0 + y1) / 2.0
+        gx, gy = self._grid_origin()
+        gw, gh = self._grid_size()
+        side = side or "right"
+        if side == "left":
+            return gx, cy, "left"
+        if side == "right":
+            return gx + gw, cy, "right"
+        if side == "top":
+            return gx + gw / 2, min(y0, y1) - self._row_h(r0) / 2, "up"
+        if side == "bottom":
+            return gx + gw / 2, max(y0, y1) + self._row_h(r1) / 2, "down"
+        return gx + gw / 2, cy, "right"
+
+    def cell_range_port(self, r0: int, r1: int, side: str = "right") -> "Port":
+        """Anchor at the vertical midpoint of rows [r0, r1] on `side`."""
+        from .edges import Port
+
+        return Port(self, kind="cell_range", side=side, index=r0, end_index=r1)
+
+    def legend_entries(self) -> List[Any]:
+        """Keys for an auto Legend: ``legend={colour: label | Key}``, ``legend="label"``,
+        a ``Key`` or a list of Keys."""
+        from .legend import Key
+
+        lg = self.legend
+        if not lg:
+            return []
+        if isinstance(lg, str):
+            return [Key(lg, fill=self.fill, stroke=self.stroke, border=self.border)]
+        if isinstance(lg, Key):
+            return [lg]
+        if isinstance(lg, (list, tuple)):
+            return [k for k in lg if isinstance(k, Key)]
+        return [lab if isinstance(lab, Key) else Key(lab, fill=col, stroke=self.stroke)
+                for col, lab in dict(lg).items()]
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_mark, draw_rect, draw_text
+        from .styles import border_dasharray
+
+        g = self.geom
+        th = self.theme
+        l, t, r, b = self._label_space()
+        gw, gh = self._grid_size()
+        # Center grid inside geom accounting for labels
+        gx = g.x + ox + l + max(0, (g.w - l - r - gw) / 2)
+        gy = g.y + oy + t + max(0, (g.h - t - b - gh) / 2)
+        fs = self._cell_fs()
+
+        for i in range(self.rows):
+            for j in range(self.cols):
+                cx = gx + self._col_x(j)
+                cy = gy + self._row_y(i)
+                cw, ch = self._col_w(j), self._row_h(i)
+                st = self._style(i, j)
+                hi = i in self.highlight_rows or j in self.highlight_cols
+                sw = self.highlight_width if hi else float(st.get("stroke_width", self.cell_stroke_width))
+                stroke = self.highlight_stroke if hi else st.get("stroke", self.stroke)
+                bd = self.border_at(i, j)
+                if bd == "none" or (self.continuous and not hi):
+                    stroke = "none"
+                fill = self.fill_at(i, j)
+                draw_rect(
+                    buf,
+                    cx,
+                    cy,
+                    cw,
+                    ch,
+                    fill=fill,
+                    stroke=stroke,
+                    stroke_width=sw,
+                    radius=self.cell_radius,
+                    dasharray=border_dasharray(bd, sw) if bd not in (None, "none") else None,
+                )
+                mark = self.mark_at(i, j)
+                if mark:
+                    mc = st.get("mark_color") or self.mark_color or (
+                        "#ffffff" if _luma(fill) < 0.45 else th.text_color)
+                    draw_mark(buf, mark, cx + cw / 2, cy + ch / 2, min(cw, ch) * 0.62, color=mc)
+                lab = self.label_at(i, j)
+                if lab and not mark:
+                    weight = st.get("weight") or (
+                        self.header_weight if self.is_header(i, j) else self.cell_weight)
+                    color = st.get("text_color") or (
+                        self.cell_text_color if (self.heat is None or self.heat_at(i, j) is None
+                                                 or _luma(fill) >= 0.5) else "#ffffff")
+                    full = lab
+                    lab, tw, lfs = _fit_cell_label(lab, cw, ch, fs, self.cell_mono, weight, th)
+                    if lab != full:
+                        from .notices import note
+
+                        note(self, full, f"cut to '{lab}' to fit its cell (widen cell_w= or "
+                             "use cell_w='content')")
+                    if self.cell_font_size is None and self.cell_w is None and self.cell_h is None \
+                            and lfs == fs:
+                        ty = cy + ch * 0.72
+                    else:
+                        ty = cy + ch / 2 + lfs * 0.36
+                    draw_text(buf, lab, cx + (cw - tw) / 2, ty, font_size=lfs, fill=color,
+                              weight=weight, mono=self.cell_mono,
+                              family=th.mono_family if self.cell_mono else None)
+
+        for spec in self.outlines:
+            r0, c0, r1, c1 = (int(v) for v in spec[:4])
+            col = spec[4] if len(spec) > 4 else (self.outline_color or self.highlight_stroke)
+            x0 = gx + self._col_x(min(c0, c1))
+            y0 = gy + self._row_y(min(r0, r1))
+            x1 = gx + self._col_x(max(c0, c1)) + self._col_w(max(c0, c1))
+            y1 = gy + self._row_y(max(r0, r1)) + self._row_h(max(r0, r1))
+            p = self.gap / 2 + self.outline_width / 2
+            draw_rect(buf, x0 - p, y0 - p, x1 - x0 + 2 * p, y1 - y0 + 2 * p, fill="none",
+                      stroke=col, stroke_width=self.outline_width, radius=self.cell_radius + self.theme.L(1),
+                      dasharray=border_dasharray(self.outline_border, self.outline_width))
+
+        if self.continuous:
+            draw_rect(buf, gx, gy, gw, gh, fill="none", stroke=self.stroke,
+                      stroke_width=self.cell_stroke_width, radius=0)
+        if self.split_style != "gap" and (self.row_splits or self.col_splits):
+            from .render_svg import draw_line
+
+            da = {"line": None, "dashed": "3,2", "dotted": "1,1.5"}[self.split_style]
+            ssw = self.cell_stroke_width
+            for k in self.row_splits:
+                y = gy + self._row_y(k) - (self.gap + self._split_w()) / 2
+                draw_line(buf, gx, y, gx + gw, y, stroke=th.muted_color, stroke_width=ssw, dasharray=da)
+            for k in self.col_splits:
+                x = gx + self._col_x(k) - (self.gap + self._split_w()) / 2
+                draw_line(buf, x, gy, x, gy + gh, stroke=th.muted_color, stroke_width=ssw, dasharray=da)
+
+        lfs = th.font_size * 0.9
+        if self.row_labels:
+            for i, lab in enumerate(self.row_labels):
+                if i >= self.rows:
+                    break
+                tw, _ = measure_text(lab, lfs)
+                cy = gy + self._row_y(i) + self._row_h(i) / 2 + lfs * 0.36
+                draw_text(buf, lab, gx - self.label_gap - tw, cy, font_size=lfs)
+
+        if self.col_labels:
+            for j, lab in enumerate(self.col_labels):
+                if j >= self.cols:
+                    break
+                tw, _ = measure_text(lab, lfs)
+                cx = gx + self._col_x(j) + (self._col_w(j) - tw) / 2
+                draw_text(buf, lab, cx, gy - self.label_gap * 0.5, font_size=lfs)
+
+        if self.colorbar and self.heat is not None:
+            self._draw_colorbar(buf, gx, gy, gw, gh, l, r, b)
+
+        if self.label:
+            lfs = self._label_fs()
+            tw, _ = measure_text(self.label, lfs, weight=self.label_weight)
+            cg = self.label_gap * 0.4
+            if self.label_pos == "top-right":
+                draw_text(buf, self.label, gx + gw + cg, gy + lfs * 0.8,
+                          font_size=lfs, weight=self.label_weight)
+            elif self.label_pos == "top-left":
+                draw_text(buf, self.label, gx - cg - tw, gy + lfs * 0.8,
+                          font_size=lfs, weight=self.label_weight)
+            elif self.label_pos == "bottom-right":
+                draw_text(buf, self.label, gx + gw + cg, gy + gh + lfs * 0.35,
+                          font_size=lfs, weight=self.label_weight)
+            elif self.label_pos == "left":
+                draw_text(buf, self.label, gx - self.label_gap - tw, gy + gh / 2 + lfs / 3,
+                          font_size=lfs, weight=self.label_weight)
+            elif self.label_pos == "right":
+                draw_text(buf, self.label, gx + gw + self.label_gap, gy + gh / 2 + lfs / 3,
+                          font_size=lfs, weight=self.label_weight)
+            elif self.label_pos == "top":
+                draw_text(buf, self.label, gx + (gw - tw) / 2, gy - self.label_gap,
+                          font_size=lfs, weight=self.label_weight)
+            else:
+                draw_text(buf, self.label, gx + (gw - tw) / 2,
+                          gy + gh + self.label_gap + lfs * 0.85,
+                          font_size=lfs, weight=self.label_weight)
+
+    def _draw_colorbar(self, buf, gx, gy, gw, gh, l, r, b) -> None:
+        from .render_svg import draw_rect, draw_text
+
+        th = self.theme
+        L, SW = th.L, th.SW
+        fs = th.small_size if th.font_sizes else th.font_size * 0.75
+        n = 24
+        ticks = self._colorbar_tick_values()
+        lo, hi = float(self.vmin), float(self.vmax)
+        span = (hi - lo) or 1.0
+        if self.colorbar == "right":
+            extra = 0.0
+            if self.label and self.label_pos == "right":
+                extra = measure_text(self.label, self.label_size or self.theme.font_size,
+                                     weight=self.label_weight)[0] + self.label_gap
+            bx, by, bw, bh = gx + gw + extra + L(8), gy, L(10.0), gh
+            for k in range(n):  # top = vmax
+                draw_rect(buf, bx, by + bh * k / n, bw, bh / n + 0.4,
+                          fill=cmap_color(self.cmap, 1 - (k + 0.5) / n), stroke="none",
+                          stroke_width=0)
+            draw_rect(buf, bx, by, bw, bh, fill="none", stroke="#444", stroke_width=SW(0.8))
+            for tv in ticks:
+                ty = by + bh * (1 - (tv - lo) / span)
+                buf.append(f'<line x1="{bx + bw:.2f}" y1="{ty:.2f}" x2="{bx + bw + L(2):.2f}" '
+                           f'y2="{ty:.2f}" stroke="#444" stroke-width="{SW(0.8):g}" />')
+                draw_text(buf, self.colorbar_format.format(tv), bx + bw + L(3), ty + fs * 0.35,
+                          font_size=fs, fill="#333333")
+            if self.colorbar_label:
+                tw_ = max(measure_text(self.colorbar_format.format(t), fs)[0] for t in ticks)
+                lw_, _ = measure_text(self.colorbar_label, fs)
+                lx = bx + bw + L(3) + tw_ + L(4) + fs * 0.5
+                ly = by + bh / 2
+                buf.append(f'<g transform="rotate(90 {lx:.2f} {ly:.2f})">')
+                draw_text(buf, self.colorbar_label, lx - lw_ / 2, ly + fs * 0.35, font_size=fs,
+                          fill="#333333")
+                buf.append("</g>")
+        else:
+            extra = 0.0
+            if self.label and self.label_pos == "bottom":
+                extra = measure_text(self.label, self.label_size or self.theme.font_size)[1] + self.label_gap
+            bx, by, bw, bh = gx, gy + gh + extra + L(8), gw, L(8.0)
+            for k in range(n):
+                draw_rect(buf, bx + bw * k / n, by, bw / n + 0.4, bh,
+                          fill=cmap_color(self.cmap, (k + 0.5) / n), stroke="none", stroke_width=0)
+            draw_rect(buf, bx, by, bw, bh, fill="none", stroke="#444", stroke_width=SW(0.8))
+            for tv in ticks:
+                tx = bx + bw * (tv - lo) / span
+                lab = self.colorbar_format.format(tv)
+                tw_, _ = measure_text(lab, fs)
+                draw_text(buf, lab, tx - tw_ / 2, by + bh + L(3) + fs * 0.85, font_size=fs,
+                          fill="#333333")
+            if self.colorbar_label:
+                lw_, _ = measure_text(self.colorbar_label, fs)
+                draw_text(buf, self.colorbar_label, bx + (bw - lw_) / 2,
+                          by + bh + L(3) + fs * 2.1, font_size=fs, fill="#333333")
+
+
+def _fit_cell_label(lab: str, cw: float, ch: float, fs: float, mono: bool, weight: str,
+                    th: Any) -> Tuple[str, float, float]:
+    """v0.11.0: make a cell label fit its cell (``(label, width, font size)``).
+
+    A label wider than the cell, or taller than the row (shared tracks squeeze cells
+    in both directions: ``align_columns`` narrows columns, ``align_rows`` shortens
+    rows, and square cells follow the other axis), first shrinks to at most 75 % of
+    the cell font, then is cut with "…". Numbers (``0.91``, ``12 %``, ``4.2B``) are
+    never cut: they shrink to 60 % instead. Labels that fit are untouched."""
+    lfs = fs
+    if ch > 0 and lfs * 1.05 > ch:
+        lfs = max(fs * 0.75, ch / 1.05)
+    tw = measure_text(lab, lfs, mono=mono, weight=weight)[0]
+    room = cw - th.L(1.0)
+    if tw > cw - th.L(0.5) and room > 0:
+        numeric = _NUMERIC.match(lab.strip()) is not None
+        floor = fs * (0.6 if numeric else 0.75)  # "0.…" would hide the value
+        lfs = max(floor, min(lfs, lfs * room / max(tw, 1e-6)))
+        if numeric:
+            tw = measure_text(lab, lfs, mono=mono, weight=weight)[0]
+        else:
+            lab, tw = _ellipsize(lab, room, lfs, mono, weight)
+    return lab, tw, lfs
+
+
+_NUMERIC = re.compile(r"^[-+−]?[$€£]?\d[\d.,]*\s?[%kKMGBTx×]?$")
+
+
+def _ellipsize(lab: str, room: float, fs: float, mono: bool, weight: str) -> Tuple[str, float]:
+    """v0.10.0: cut ``lab`` to fit ``room`` pt, ending in "…" (whole label if it fits)."""
+    tw = measure_text(lab, fs, mono=mono, weight=weight)[0]
+    if tw <= room:
+        return lab, tw
+    for k in range(len(lab) - 1, 0, -1):
+        cand = lab[:k].rstrip() + "…"
+        tw = measure_text(cand, fs, mono=mono, weight=weight)[0]
+        if tw <= room:
+            return cand, tw
+    return "…", measure_text("…", fs, mono=mono, weight=weight)[0]
+
+
+class TokenStrip(Matrix):
+    """A row of token cells sized to their text — vLLM / StreamingLLM token rows.
+
+    ``TokenStrip(["Four", "score", "and"], fills={0: "#fde"}, marks=…)``; any Matrix
+    option (``heat=``, ``outlines=``, ``label=``…) also works.
+    ``fills`` / ``marks`` / ``borders`` take a list or ``{index: value}``;
+    ``cell_border=`` is accepted as an alias of ``borders=`` (v0.13.0).
+    ``orientation="vertical"`` (v0.13.0) stacks the tokens top-to-bottom (a token
+    *column*); ``token_port`` / ``token_span`` follow the orientation.
+    An empty token (``""`` / ``None``) is as wide as a typical token in the strip
+    (the median non-empty width) instead of a sliver; ``cell_w=[...]`` sets widths
+    exactly.
+    """
+
+    def __init__(self, tokens: Sequence[Optional[str]], *, fills: Any = None, marks: Any = None,
+                 borders: Any = None, cell_h: Any = None, gap: float = 0.0,
+                 cell_radius: float = 0.0, fill: str = "#ffffff",
+                 orientation: str = "horizontal", **kwargs: Any) -> None:
+        toks = ["" if t is None else str(t) for t in tokens]
+        from ._validate import check_enum
+        orientation = check_enum("primitives(orientation)", orientation, ("horizontal", "vertical"))
+        if "cell_border" in kwargs:
+            if borders is not None:
+                raise TypeError("TokenStrip: pass borders= or its alias cell_border=, not both")
+            borders = kwargs.pop("cell_border")
+        vertical = orientation == "vertical"
+        self.orientation = orientation
+
+        def per_index(spec: Any) -> Any:
+            if spec is None or callable(spec):
+                return spec
+            if isinstance(spec, (str, tuple)):  # one value for every token
+                return lambda r, c, _v=spec: _v
+            if isinstance(spec, dict):
+                return {((int(k), 0) if vertical else (0, int(k))): v for k, v in spec.items()}
+            return [[v] for v in spec] if vertical else [list(spec)]
+
+        kwargs.setdefault("cell_w", "content")
+        if cell_h is None:
+            cell_h = "content"
+        n = len(toks)
+        rows, cols = (n, 1) if vertical else (1, n)
+        labels = [[t] for t in toks] if vertical else [toks]
+        super().__init__(rows, cols, cell_labels=labels, cell_fill=per_index(fills),
+                         cell_marks=per_index(marks), cell_border=per_index(borders),
+                         cell_h=cell_h, gap=gap, cell_radius=cell_radius, fill=fill, **kwargs)
+        self.tokens = toks
+
+    def _col_ws(self) -> List[float]:
+        out = super()._col_ws()
+        if self.orientation == "horizontal" and self.cell_w == "content" \
+                and self.__dict__.get("_track") is None:
+            full = sorted(w for w, t in zip(out, self.tokens) if t.strip())
+            if full and len(full) < len(out):
+                med = full[len(full) // 2]
+                out = [max(w, med) if not t.strip() else w for w, t in zip(out, self.tokens)]
+            elif not full:
+                h = self._row_hs()[0] if self.rows else 0.0
+                out = [max(w, h * 1.5) for w in out]
+        return out
+
+    def _idx(self, i: int) -> Tuple[int, int]:
+        return (i, 0) if self.orientation == "vertical" else (0, i)
+
+    def token_port(self, i: int, side: Optional[str] = None) -> "Port":
+        if side is None:
+            side = "left" if self.orientation == "vertical" else "top"
+        r, c = self._idx(i)
+        return self.cell_port(r, c, side)
+
+    def token_anchor(self, i: int) -> "MatrixCellRef":
+        r, c = self._idx(i)
+        return self.cell_anchor(r, c)
+
+    def token_span(self, i: int, j: int) -> Tuple[Any, Any]:
+        """Anchor pair covering tokens ``i``..``j`` (for ``Brace(span=)`` / ``Dim``)."""
+        if self.orientation == "vertical":
+            return self.row_span(i, j)
+        return self.col_span(i, j)
+
+
+class Table(Matrix):
+    """Data table with header row / column: ``Table([["", "A", "B"], ["x", 1, 2]],
+    header_rows=1, header_cols=1)``. Cells are sized to their content; ``True`` /
+    ``False`` cells render as ✓ / ✗ marks (``marks=False`` keeps them as text)."""
+
+    def _cell_fs(self) -> float:
+        if self.cell_font_size is not None:
+            return float(self.cell_font_size)
+        return self.theme.F(11.0)
+
+    def __init__(self, data: Sequence[Sequence[Any]], *, header_rows: int = 1,
+                 header_cols: int = 0, marks: bool = True, gap: float = 0.0,
+                 cell_radius: float = 0.0, fill: str = "#ffffff",
+                 cell_font_size: Optional[float] = None, **kwargs: Any) -> None:
+        rows = [list(r) for r in data]
+        n_rows, n_cols = len(rows), max((len(r) for r in rows), default=0)
+        if not n_rows or not n_cols:
+            raise ValueError("Table needs at least one non-empty row")
+        labels = [[("" if v is None or isinstance(v, bool) and marks else str(v))
+                   for v in r] + [""] * (n_cols - len(r)) for r in rows]
+        mark_map = {(i, j): ("check" if v else "cross") for i, r in enumerate(rows)
+                    for j, v in enumerate(r) if isinstance(v, bool) and marks}
+        kwargs.setdefault("cell_w", "content")
+        kwargs.setdefault("cell_h", "content")
+        kwargs.setdefault("cell_pad", 6.0)
+        kwargs.setdefault("cell_stroke_width", 0.8)
+        mark_colors = {}
+        user_style = kwargs.pop("cell_style", None)
+
+        def style(r: int, c: int) -> dict:
+            st = dict(_cell_lookup(user_style, r, c, n_rows, n_cols) or {})
+            if (r, c) in mark_map and "mark_color" not in st:
+                st["mark_color"] = "#1e8449" if mark_map[(r, c)] == "check" else "#c0392b"
+            return st
+
+        super().__init__(n_rows, n_cols, cell_labels=labels, cell_marks=mark_map or None,
+                         header_rows=header_rows, header_cols=header_cols, gap=gap,
+                         cell_radius=cell_radius, fill=fill, cell_style=style,
+                         cell_font_size=cell_font_size,
+                         **kwargs)
+        self.data = rows
+
+
+class Group(Container):
+    """Nested titled container with border — for Transformer blocks, attention heads, etc.
+
+    Defaults come from the theme: ``fill`` = ``theme.group_fill`` (``fill=None`` → no
+    fill), ``stroke`` / ``stroke_width`` = the theme's group stroke, ``pad`` ≈ 10 px
+    classic / 5.5 pt paper.
+
+    ``border=`` (every node takes it): ``"solid"`` (default) | ``"dashed"`` | ``"dotted"`` |
+    ``"dashdot"`` | ``"none"`` | a dash pattern ``"4 2"`` / ``(4, 2)`` — e.g. a dashed
+    "optional stage" frame: ``Group([...], title="cache", border="dashed")``.
+    ``pad=`` is a number, ``(vertical, horizontal)`` or ``(top, right, bottom, left)`` (CSS
+    order). ``title=`` uses the theme *title* role (8 pt paper); a ``Text`` with the same
+    ``font_size`` and ``**bold**`` looks as large, so keep inner labels at 7 pt.
+
+    ``title_pos=``: ``"top"`` (default, above the frame) | ``"bottom"`` | ``"inside-top"``;
+    ``title_align=``: ``"center"`` (default) | ``"left"`` | ``"right"`` — or both at once,
+    ``title_pos="top-left"`` (v0.13.0; also ``"bottom-right"``, ``"inside-top-left"`` …).
+    The same two options work on every container (``Row``/``Col``/``Stack``).
+    """
+
+    fill = theme_default("group_fill")
+    stroke = theme_default("stroke")
+    stroke_width = theme_default(lambda th: th.group_stroke or th.stroke_width)
+
+    @property
+    def padding(self):  # type: ignore[override]
+        raw = self.__dict__.get("_gpad")
+        if raw is None:
+            return normalize_pad(self.theme.L(10.0) * self.theme.pad_scale)
+        return normalize_pad(raw)
+
+    @padding.setter
+    def padding(self, v) -> None:
+        self.__dict__["_gpad_set"] = v
+
+    @property
+    def pad(self):  # type: ignore[override]
+        return sum(self.padding) / 4.0
+
+    @pad.setter
+    def pad(self, v) -> None:
+        pass
+
+    def __init__(
+        self,
+        kids: Optional[Sequence[Node]] = None,
+        *,
+        title: Optional[str] = None,
+        title_pos: str = "top",
+        fill: Optional[str] = "auto",
+        stroke: Optional[str] = None,
+        rounded: bool = True,
+        pad: Any = None,
+        gap: Optional[float] = None,
+        direction: str = "column",
+        align: str = "center",
+        justify: str = "start",
+        title_gap: Optional[float] = None,
+        stroke_width: Optional[float] = None,
+        title_align: str = "center",
+        **kwargs: Any,
+    ) -> None:
+        self.__dict__["_gpad"] = kwargs.pop("padding", None) if pad is None else pad
+        kwargs["title_align"] = title_align
+        super().__init__(
+            kids,
+            direction=direction,
+            gap=gap,
+            pad=0.0,
+            align=align,
+            justify=justify,
+            title_gap=title_gap,
+            fill=None if fill == "auto" else (fill or "none"),
+            stroke=stroke,
+            stroke_width=stroke_width,
+            rounded=rounded,
+            title=title,
+            title_pos=title_pos,
+            **kwargs,
+        )
+
+
+
+class Brace(Node):
+    """
+    Tall curly / square / round brace — for grouping (e.g. panel (d) o_i).
+
+    Place beside content in a Row/Col. ``side`` is the direction the brace **tip**
+    points: ``side="left"`` draws ``{`` (tip on the left, arms open to the right),
+    ``"right"`` draws ``}``, ``"top"`` / ``"bottom"`` the horizontal versions.
+    Content the brace groups goes on the arms side; the tip points away from it.
+
+    ``label``: drawn on the arms side by default (``label_at="open"``, between the
+    brace and whatever follows it); ``label_at="tip"`` puts it beyond the tip — the
+    usual "}  label" annotation: ``Row([content, Brace("6 layers", side="right",
+    label_at="tip")])``. ``span=(a, b)`` draws the brace over a sub-range only:
+    two anchors, e.g. ``m.row_span(0, 2)`` / ``m.col_span(1, 3)`` on a Matrix or
+    ``strip.token_span(2, 5)`` on a TokenStrip.
+    """
+
+    strip = themed(28.0)
+
+    def __init__(
+        self,
+        label: Optional[str] = None,
+        *,
+        side: str = "left",  # left|right|top|bottom — open toward content
+        style: str = "curly",  # curly|square|round
+        strip: Optional[float] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        label_gap: Optional[float] = None,
+        grow: Optional[float] = None,
+        span: Optional[Tuple[Any, Any]] = None,
+        font_size: Optional[float] = None,
+        weight: str = "bold",
+        label_color: Optional[str] = None,
+        label_at: str = "open",
+        **kwargs: Any,
+    ) -> None:
+        # v0.13.0: a span brace is drawn over its span, so its layout slot stays small
+        # along the brace (it no longer stretches a Col / pushes captions down)
+        kwargs.setdefault("grow", (0.0 if span is not None else 1.0) if grow is None else grow)
+        super().__init__(**kwargs)
+        from ._validate import check_enum
+        side = check_enum("primitives(side)", side, ("left", "right", "top", "bottom"))
+        from ._validate import check_enum
+        label_at = check_enum("primitives(label_at)", label_at, ("open", "tip"))
+        self.label_at = label_at
+        if span is not None and len(span) != 2:
+            raise ValueError("Brace span must be a pair of anchors")
+        self.span = span
+        self.font_size = font_size
+        self.weight = weight
+        self.label_color = label_color
+        self.label = label
+        self.side = side
+        self.style = style
+        self.strip = strip
+        self.stroke = stroke
+        self.sw = stroke_width
+        self.label_gap = label_gap
+
+    def _fs(self) -> float:
+        return self.font_size if self.font_size is not None else self.theme.font_size
+
+    def _span(self) -> Optional[Tuple[float, float]]:
+        """Page-space (lo, hi) of ``span`` along the brace axis, clamped to geom."""
+        if self.span is None:
+            return None
+        from .constraints import as_anchor
+
+        axis = "x" if self.side in ("top", "bottom") else "y"
+        a = as_anchor(self.span[0], axis, "start").value()
+        b = as_anchor(self.span[1], axis, "end").value()
+        lo, hi = min(a, b), max(a, b)
+        return lo, hi
+
+    def _measure(self) -> Tuple[float, float]:
+        th = self.theme
+        fs = self._fs()
+        lg = float(th.label_gap if self.label_gap is None else self.label_gap)
+        label_w = label_h = 0.0
+        if self.label:
+            label_w, label_h = measure_text(self.label, fs, weight=self.weight)
+        along = th.L(48.0)
+        if self.span is not None:
+            along = 0.0
+        if self.side in ("left", "right"):
+            w = self.strip + (label_w + lg if self.label else 0.0)
+            return w, max(along, label_h + th.L(2) if self.span is not None else label_h + th.L(8))
+        h = self.strip + (label_h + lg if self.label else 0.0)
+        return max(along, label_w + th.L(2) if self.span is not None else label_w + th.L(8)), h
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_path, draw_text
+
+        from .node import BoxGeom
+
+        g = self.geom
+        th = self.theme
+        fs = self._fs()
+        sp = self._span()
+        if sp is not None:  # draw over the spanned sub-range only (label follows)
+            if self.side in ("top", "bottom"):
+                g = BoxGeom(sp[0], g.y, sp[1] - sp[0], g.h)
+            else:
+                g = BoxGeom(g.x, sp[0], g.w, sp[1] - sp[0])
+        x, y = g.x + ox, g.y + oy
+        stroke = self.stroke or th.stroke
+        sw = float(self.sw if self.sw is not None else th.stroke_width)
+        lg = float(th.label_gap if self.label_gap is None else self.label_gap)
+
+        # Brace body occupies `strip` along the cross axis; label outside.
+        if self.side in ("left", "right"):
+            label_w = 0.0
+            if self.label:
+                label_w, _ = measure_text(self.label, fs, weight=self.weight)
+            if (self.side == "left") == (self.label_at == "open"):
+                # label right of the strip
+                bx0 = x
+                bw = self.strip
+                if self.label:
+                    draw_text(
+                        buf, self.label,
+                        x + bw + lg,
+                        y + g.h / 2 + fs / 3,
+                        font_size=fs, weight=self.weight, fill=self.label_color or stroke,
+                    )
+            else:
+                # label left of the strip
+                bx0 = x + (label_w + lg if self.label else 0.0)
+                bw = self.strip
+                if self.label:
+                    draw_text(
+                        buf, self.label,
+                        x,
+                        y + g.h / 2 + fs / 3,
+                        font_size=fs, weight=self.weight, fill=self.label_color or stroke,
+                    )
+            d = _brace_path_vertical(bx0, y, bw, g.h, open_left=(self.side == "left"), style=self.style)
+        else:
+            label_h = fs if self.label else 0.0
+            if (self.side == "top") == (self.label_at == "open"):
+                by0 = y
+                bh = self.strip
+                if self.label:
+                    tw, _ = measure_text(self.label, fs, weight=self.weight)
+                    draw_text(
+                        buf, self.label,
+                        x + (g.w - tw) / 2,
+                        y + bh + lg + fs,
+                        font_size=fs, weight=self.weight, fill=self.label_color or stroke,
+                    )
+            else:
+                by0 = y + (label_h + lg if self.label else 0.0)
+                bh = self.strip
+                if self.label:
+                    tw, _ = measure_text(self.label, fs, weight=self.weight)
+                    draw_text(
+                        buf, self.label,
+                        x + (g.w - tw) / 2,
+                        y + fs,
+                        font_size=fs, weight=self.weight, fill=self.label_color or stroke,
+                    )
+            d = _brace_path_horizontal(x, by0, g.w, bh, open_up=(self.side == "top"), style=self.style)
+        draw_path(buf, d, stroke=stroke, stroke_width=sw, fill="none")
+
+
+def _brace_path_vertical(
+    x: float, y: float, w: float, h: float, *, open_left: bool, style: str
+) -> str:
+    """SVG path for a vertical brace in box (x,y,w,h)."""
+    mid = y + h / 2
+    if style == "square":
+        if open_left:
+            # ] shape but mirrored: tip at left mid, spine on right
+            return (
+                f"M {x + w:.2f},{y:.2f} L {x:.2f},{y:.2f} "
+                f"L {x:.2f},{mid:.2f} L {x + w * 0.15:.2f},{mid:.2f} "
+                f"M {x:.2f},{mid:.2f} L {x:.2f},{y + h:.2f} L {x + w:.2f},{y + h:.2f}"
+            )
+        return (
+            f"M {x:.2f},{y:.2f} L {x + w:.2f},{y:.2f} "
+            f"L {x + w:.2f},{mid:.2f} L {x + w * 0.85:.2f},{mid:.2f} "
+            f"M {x + w:.2f},{mid:.2f} L {x + w:.2f},{y + h:.2f} L {x:.2f},{y + h:.2f}"
+        )
+    if style == "round":
+        # simple round paren via cubic
+        if open_left:
+            return (
+                f"M {x + w:.2f},{y:.2f} "
+                f"C {x:.2f},{y:.2f} {x:.2f},{mid:.2f} {x + w * 0.2:.2f},{mid:.2f} "
+                f"C {x:.2f},{mid:.2f} {x:.2f},{y + h:.2f} {x + w:.2f},{y + h:.2f}"
+            )
+        return (
+            f"M {x:.2f},{y:.2f} "
+            f"C {x + w:.2f},{y:.2f} {x + w:.2f},{mid:.2f} {x + w * 0.8:.2f},{mid:.2f} "
+            f"C {x + w:.2f},{mid:.2f} {x + w:.2f},{y + h:.2f} {x:.2f},{y + h:.2f}"
+        )
+    # curly (default) — classic typographic brace
+    tip = x + (0.05 * w if open_left else 0.95 * w)
+    spine = x + (0.75 * w if open_left else 0.25 * w)
+    outer = x + (0.95 * w if open_left else 0.05 * w)
+    # two curls meeting at tip
+    return (
+        f"M {outer:.2f},{y:.2f} "
+        f"C {spine:.2f},{y:.2f} {spine:.2f},{mid:.2f} {tip:.2f},{mid:.2f} "
+        f"C {spine:.2f},{mid:.2f} {spine:.2f},{y + h:.2f} {outer:.2f},{y + h:.2f}"
+    )
+
+
+def _brace_path_horizontal(
+    x: float, y: float, w: float, h: float, *, open_up: bool, style: str
+) -> str:
+    mid = x + w / 2
+    if style == "square":
+        if open_up:
+            return (
+                f"M {x:.2f},{y + h:.2f} L {x:.2f},{y:.2f} "
+                f"L {mid:.2f},{y:.2f} L {mid:.2f},{y + h * 0.15:.2f} "
+                f"M {mid:.2f},{y:.2f} L {x + w:.2f},{y:.2f} L {x + w:.2f},{y + h:.2f}"
+            )
+        return (
+            f"M {x:.2f},{y:.2f} L {x:.2f},{y + h:.2f} "
+            f"L {mid:.2f},{y + h:.2f} L {mid:.2f},{y + h * 0.85:.2f} "
+            f"M {mid:.2f},{y + h:.2f} L {x + w:.2f},{y + h:.2f} L {x + w:.2f},{y:.2f}"
+        )
+    tip = y + (0.05 * h if open_up else 0.95 * h)
+    spine = y + (0.75 * h if open_up else 0.25 * h)
+    outer = y + (0.95 * h if open_up else 0.05 * h)
+    return (
+        f"M {x:.2f},{outer:.2f} "
+        f"C {x:.2f},{spine:.2f} {mid:.2f},{spine:.2f} {mid:.2f},{tip:.2f} "
+        f"C {mid:.2f},{spine:.2f} {x + w:.2f},{spine:.2f} {x + w:.2f},{outer:.2f}"
+    )
+
+
+class CircleHighlight(Node):
+    """
+    Circle / oval / rounded-rect callout drawn around a child node.
+
+    Use to emphasize a box or a single probability line (paper panel (b)).
+    Alias: Callout.
+
+    v0.7.0: ``ellipse`` / ``circle`` are sized to *enclose* the child's corners (a box
+    framed by the ellipse no longer pokes through it); ``pad`` is the clearance.
+    """
+
+    hl_pad = themed(6.0)
+    hl_sw = theme_default(lambda th: 2.0 if th.unit == 1.0 else th.emph_stroke)
+
+    def __init__(
+        self,
+        child: Node,
+        *,
+        shape: str = "ellipse",  # ellipse|circle|rect
+        pad: Optional[float] = None,
+        stroke: str = "#d4a017",
+        stroke_width: Optional[float] = None,
+        fill: str = "none",
+        opacity: float = 1.0,
+        dasharray: Optional[str] = None,
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.child = child
+        child.parent = self
+        self.shape = shape
+        self.hl_pad = pad
+        self.hl_stroke = stroke
+        self.hl_sw = stroke_width
+        self.hl_fill = fill
+        self.hl_opacity = float(opacity)
+        self.hl_dash = dasharray
+
+    def children(self) -> Sequence[Node]:
+        return (self.child,)
+
+    def _axes(self, cw: float, ch: float) -> Tuple[float, float]:
+        """Half-axes (rx, ry) of the outline around a ``cw`` × ``ch`` child."""
+        import math
+
+        p = self.hl_pad
+        if self.shape == "rect":
+            return cw / 2 + p, ch / 2 + p
+        if self.shape == "circle":
+            r = math.hypot(cw / 2, ch / 2) + p * 0.5
+            return r, r
+        a = cw / 2 + max(p, 0.12 * cw)
+        k = max(1e-3, 1.0 - (cw / 2 / a) ** 2)
+        b = max(ch / 2 + p, (ch / 2) / math.sqrt(k) + p * 0.5)
+        return a, b
+
+    def _measure(self) -> Tuple[float, float]:
+        cw, ch = self.child.measure()
+        rx, ry = self._axes(cw, ch)
+        return 2 * rx, 2 * ry
+
+    def _layout_children(self) -> None:
+        g = self.geom
+        cw, ch = self.child.measure()
+        # center child inside the outline box
+        self.child.layout(g.x + (g.w - cw) / 2, g.y + (g.h - ch) / 2, cw, ch)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_ellipse, draw_rect
+
+        self.child.draw(buf, ox, oy)
+        cg = self.child.geom
+        # highlight around the child's laid-out box (+ pad)
+        rx0, ry0 = self._axes(cg.w, cg.h)
+        x = cg.x + ox + cg.w / 2 - rx0
+        y = cg.y + oy + cg.h / 2 - ry0
+        w = 2 * rx0
+        h = 2 * ry0
+        if self.shape == "rect":
+            draw_rect(
+                buf, x, y, w, h,
+                fill=self.hl_fill, stroke=self.hl_stroke,
+                stroke_width=self.hl_sw, radius=min(w, h) * 0.2,
+                opacity=self.hl_opacity, dasharray=self.hl_dash or self._dash(self.hl_sw),
+            )
+        else:
+            cx, cy = x + w / 2, y + h / 2
+            rx, ry = w / 2, h / 2
+            draw_ellipse(
+                buf, cx, cy, rx, ry,
+                fill=self.hl_fill, stroke=self.hl_stroke,
+                stroke_width=self.hl_sw, opacity=self.hl_opacity,
+                dasharray=self.hl_dash or self._dash(self.hl_sw),
+            )
+
+
+# Public alias
+Callout = CircleHighlight