codefig 0.17.0__py3-none-any.whl

codefig/code.py

@@ -0,0 +1,602 @@
+"""CodeBlock: monospace source listing with light syntax colouring and line ports.
+
+A built-in regex tokenizer (no Pygments) colours keywords, strings, comments,
+numbers, function / method names, decorators and builtins for ``python`` and
+``sql``; ``text`` is shown verbatim (useful for traces, prompts, logs).
+
+The source is rendered literally — ``*``, ``[`` and backticks in code are never
+treated as codefig rich-text markup. Per-line *annotations* (shown to the right of
+a line) do use rich text (``**bold**``, ``[color=#c00]…[/]``).
+"""
+
+from __future__ import annotations
+
+import keyword
+import re
+import textwrap
+from typing import Any, Dict, Iterable, List, Mapping, Optional, Sequence, Tuple, Union
+
+from .node import Node
+from .styles import Theme, themed
+
+CODE_LANGS = ("python", "sql", "text")
+TOKEN_TYPES = ("plain", "keyword", "builtin", "string", "comment", "number", "function",
+               "decorator", "operator")
+
+# ---------------------------------------------------------------------------- palettes
+
+#: Built-in syntax palettes for ``CodeBlock(theme=...)``. Keys: token types plus
+#: ``bg`` (background), ``border``, ``gutter`` (line-number colour), ``highlight``
+#: (highlighted-line band), ``title_bg`` / ``title`` (optional header bar).
+CODE_THEMES: Dict[str, Dict[str, str]] = {
+    "light": {
+        "bg": "#f6f8fa", "border": "#c9d1d9", "plain": "#24292f", "keyword": "#cf222e",
+        "builtin": "#953800", "string": "#0a3069", "comment": "#6e7781", "number": "#0550ae",
+        "function": "#8250df", "decorator": "#8250df", "operator": "#24292f",
+        "gutter": "#8c959f", "highlight": "#fff3b0", "title_bg": "#eaeef2", "title": "#24292f",
+    },
+    "dark": {
+        "bg": "#282c34", "border": "#3b4048", "plain": "#abb2bf", "keyword": "#c678dd",
+        "builtin": "#e5c07b", "string": "#98c379", "comment": "#7f848e", "number": "#d19a66",
+        "function": "#61afef", "decorator": "#e5c07b", "operator": "#abb2bf",
+        "gutter": "#636d83", "highlight": "#3e4451", "title_bg": "#21252b", "title": "#d7dae0",
+    },
+    "paper": {  # print-friendly, few colours (keywords bold blue, strings green)
+        "bg": "#ffffff", "border": "#888888", "plain": "#111111", "keyword": "#1f4e9c",
+        "builtin": "#1f4e9c", "string": "#2e7d32", "comment": "#777777", "number": "#b35900",
+        "function": "#111111", "decorator": "#7a3e9d", "operator": "#111111",
+        "gutter": "#999999", "highlight": "#fff2a8", "title_bg": "#eeeeee", "title": "#111111",
+    },
+    "mono": {  # black & white: structure via weight / italics only
+        "bg": "#ffffff", "border": "#555555", "plain": "#111111", "keyword": "#111111",
+        "builtin": "#111111", "string": "#444444", "comment": "#777777", "number": "#111111",
+        "function": "#111111", "decorator": "#111111", "operator": "#111111",
+        "gutter": "#999999", "highlight": "#e6e6e6", "title_bg": "#eeeeee", "title": "#111111",
+    },
+}
+_BOLD = {"light": {"keyword"}, "dark": set(), "paper": {"keyword"}, "mono": {"keyword"}}
+_ITALIC = {"comment"}
+
+# ---------------------------------------------------------------------------- tokenizer
+
+_PY_KW = set(keyword.kwlist) | {"match", "case", "self"}
+_PY_BUILTINS = {
+    "print", "len", "range", "enumerate", "zip", "map", "filter", "sorted", "sum", "min",
+    "max", "abs", "int", "float", "str", "list", "dict", "set", "tuple", "bool", "open",
+    "isinstance", "super", "type", "any", "all", "iter", "next", "round", "object",
+}
+_SQL_KW = {
+    "select", "from", "where", "join", "inner", "left", "right", "full", "outer", "cross",
+    "on", "group", "by", "order", "limit", "offset", "as", "and", "or", "not", "in", "is",
+    "null", "insert", "into", "values", "update", "set", "delete", "create", "table", "view",
+    "index", "drop", "alter", "with", "case", "when", "then", "else", "end", "distinct",
+    "having", "union", "all", "asc", "desc", "like", "between", "exists", "cast", "over",
+    "partition", "primary", "key", "foreign", "references", "using", "natural", "true",
+    "false", "if", "returns", "return", "begin", "commit", "intersect", "except", "top",
+}
+_SQL_FUNCS = {"count", "sum", "avg", "min", "max", "coalesce", "lower", "upper", "substr",
+              "round", "abs", "length", "date", "now", "row_number", "rank"}
+
+_PY_RE = re.compile(
+    r"""
+    (?P<comment>\#[^\n]*)
+  | (?P<string>(?:[rRbBuUfF]{1,2})?(?:\"\"\"[\s\S]*?(?:\"\"\"|\Z)|'''[\s\S]*?(?:'''|\Z)
+        |"(?:\\.|[^"\\\n])*"?|'(?:\\.|[^'\\\n])*'?))
+  | (?P<decorator>@[A-Za-z_][\w.]*)
+  | (?P<number>\b(?:0[xX][0-9a-fA-F_]+|\d[\d_]*\.?\d*(?:[eE][+-]?\d+)?j?|\.\d+)\b)
+  | (?P<name>[A-Za-z_]\w*)
+  | (?P<space>[ \t]+)
+  | (?P<newline>\n)
+  | (?P<operator>[^\w\s])
+    """,
+    re.VERBOSE,
+)
+_SQL_RE = re.compile(
+    r"""
+    (?P<comment>--[^\n]*|/\*[\s\S]*?(?:\*/|\Z))
+  | (?P<string>'(?:''|[^'])*'?|"(?:[^"])*"?|`[^`]*`?)
+  | (?P<number>\b\d+(?:\.\d+)?\b)
+  | (?P<name>[A-Za-z_][\w$]*)
+  | (?P<space>[ \t]+)
+  | (?P<newline>\n)
+  | (?P<operator>[^\w\s])
+    """,
+    re.VERBOSE,
+)
+
+Token = Tuple[str, str]  # (type, text)
+
+
+def tokenize(source: str, lang: str = "python") -> List[List[Token]]:
+    """Split ``source`` into lines of ``(token_type, text)`` pairs.
+
+    ``token_type`` is one of :data:`TOKEN_TYPES`. Multi-line strings / comments are
+    split at newlines (each piece keeps its type). ``lang`` ∈ :data:`CODE_LANGS`.
+
+    Example:
+        >>> tokenize("x = len(s)  # n", "python")[0][-1]
+        ('comment', '# n')
+    """
+    if lang not in CODE_LANGS:
+        raise ValueError(f"lang must be one of {CODE_LANGS}, got {lang!r}")
+    lines: List[List[Token]] = [[]]
+
+    def emit(kind: str, text: str) -> None:
+        parts = text.split("\n")
+        for i, part in enumerate(parts):
+            if i:
+                lines.append([])
+            if part:
+                lines[-1].append((kind, part))
+
+    if lang == "text":
+        emit("plain", source)
+        return lines
+    rx = _PY_RE if lang == "python" else _SQL_RE
+    toks = [(m.lastgroup or "plain", m.group()) for m in rx.finditer(source)]
+    prev_sig = ""  # previous significant token text (for def / class / .attr)
+    for i, (kind, text) in enumerate(toks):
+        if kind == "newline":
+            lines.append([])
+            continue
+        if kind == "space":
+            emit("plain", text)
+            continue
+        if kind == "name":
+            nxt = ""
+            for k2, t2 in toks[i + 1:]:
+                if k2 != "space":
+                    nxt = t2
+                    break
+            if lang == "python":
+                if text in _PY_KW:
+                    kind = "keyword"
+                elif prev_sig in ("def", "class"):
+                    kind = "function"
+                elif nxt == "(":
+                    kind = "builtin" if (text in _PY_BUILTINS and prev_sig != ".") else "function"
+                else:
+                    kind = "plain"
+            else:
+                low = text.lower()
+                if nxt == "(" and (low in _SQL_FUNCS or low not in _SQL_KW):
+                    kind = "function"
+                elif low in _SQL_KW:
+                    kind = "keyword"
+                else:
+                    kind = "plain"
+        emit(kind, text)
+        prev_sig = text
+    return lines
+
+
+# ---------------------------------------------------------------------------- node
+
+class CodeLineRef:
+    """Anchors of one CodeBlock line (``top`` / ``bottom`` / ``cy`` of the line band,
+    ``left`` / ``right`` / ``cx`` of the block) — use with constraints / ``align=``."""
+
+    def __init__(self, block: "CodeBlock", line: int) -> None:
+        self.node, self.line = block, int(line)
+
+    def _anchor(self, axis: str, which: str):
+        from .constraints import Anchor, _WHICH_FRAC
+
+        b, ln, f = self.node, self.line, _WHICH_FRAC[which]
+        if axis == "y":
+            def get() -> float:
+                y0, h = b._line_band(ln)
+                return y0 + h * f
+        else:
+            def get() -> float:
+                g = b.geom
+                return g.x + g.w * f
+        name = {"start": "top" if axis == "y" else "left", "end": "bottom" if axis == "y" else "right",
+                "center": "cy" if axis == "y" else "cx"}[which]
+        return Anchor(b, axis, getter=get, label=f"line[{ln}].{name}")
+
+    left = property(lambda self: self._anchor("x", "start"))
+    right = property(lambda self: self._anchor("x", "end"))
+    top = property(lambda self: self._anchor("y", "start"))
+    bottom = property(lambda self: self._anchor("y", "end"))
+    cx = property(lambda self: self._anchor("x", "center"))
+    cy = property(lambda self: self._anchor("y", "center"))
+
+
+class CodeBlock(Node):
+    """Source-code / SQL / trace listing in a monospace font with syntax colours.
+
+    Layering role: **hard** (edges route around it and may end on its border; use
+    :meth:`line_port` to point an arrow at one line).
+
+    Args:
+        source: The code. Common leading indentation and leading / trailing blank
+            lines are removed (``dedent=True``); tabs expand to ``tab_size`` spaces.
+        lang: ``"python"`` (default), ``"sql"`` or ``"text"`` (no colouring).
+        token_colors: Mapping of literal keys or ``re:`` regex keys to token types,
+            CSS colours, or dicts with color/bold/italic. Literals require Unicode
+            word boundaries (Model excludes Models and _Model). Longest overlapping
+            match wins; insertion order breaks ties. Matches may span lines.
+        line_numbers: Show a line-number gutter (default ``False``).
+        start_line: Number of the first line (default 1). Line numbers used by
+            ``highlight_lines``, ``annotations``, :meth:`line_port` are these numbers.
+        highlight_lines: Lines to mark with a background band — an iterable of line
+            numbers, or a ``{line: colour}`` mapping for per-line colours.
+        font_size: Code size in pt (default ``0.85 × theme.font_size`` ≈ 6 pt on the paper theme; a number is pt at final size, like every other font_size).
+        theme: Syntax palette — ``"light"`` (default), ``"dark"``, ``"paper"``,
+            ``"mono"``, or a dict overriding palette keys (see :data:`CODE_THEMES`;
+            ``"base"`` picks the palette it starts from; unknown keys are rejected). A :class:`~codefig.styles.Theme` instance is
+            accepted too and sets the node's figure theme instead.
+        title: Optional header bar text (e.g. a file name or ``"SQL"``), drawn
+            literally (no rich-text / subscript markup).
+        annotations: ``{line: rich_text}`` notes drawn right of those lines in the
+            sans font (rich markup allowed: ``"← **join** key"``).
+        annotation_color: Colour of annotations (default ``theme.highlight``).
+        fill: Background override (default: palette ``bg``).
+        stroke: Border colour override (default: palette ``border``); ``border=``
+            (``"dashed"``, ``"none"`` …) styles the outline as for any node.
+        stroke_width: Border width (default: the theme's thin stroke; 1 px classic).
+        rounded: Rounded corners (default ``True``, radius 4 pt).
+        pad: Inner padding in pt around the code (default 8).
+        line_height: Line pitch as a multiple of ``font_size`` (default 1.4).
+        tab_size: Spaces per tab (default 4).
+        dedent: Strip common indentation / blank edge lines (default ``True``).
+        **kwargs: Common :class:`~codefig.node.Node` options (``id``, ``w``, ``min_w``,
+            ``obstacle``, ``legend`` …).
+
+    Example:
+        >>> from codefig import Figure, CodeBlock, Box, Row, Diagram, Edge
+        >>> code = CodeBlock('''
+        ... def digest(df):
+        ...     out = df.sem_map("summarise {abstract}")
+        ...     return out.sem_agg("merge")
+        ... ''', line_numbers=True, highlight_lines=[2])
+        >>> custom = CodeBlock("Model", lang="text", token_colors={"Model": "function"})
+        >>> llm = Box("LLM")
+        >>> d = Diagram(Row([code, llm], gap=40), [Edge(code.line_port(2, "right"), llm)])
+        >>> fig = Figure(size="auto", cols=1)
+        >>> fig.panel("a").set(d)  # doctest: +ELLIPSIS
+        <codefig.figure.Panel object at ...>
+        >>> svg = fig.to_svg()
+    """
+
+    stroke_width = themed(1.0, "SW")
+    pad = themed(8.0)
+
+    def __init__(
+        self,
+        source: str,
+        *,
+        lang: str = "python",
+        token_colors: Optional[Mapping[str, Any]] = None,
+        line_numbers: bool = False,
+        start_line: int = 1,
+        highlight_lines: Optional[Union[Iterable[int], Mapping[int, str]]] = None,
+        font_size: Optional[float] = None,
+        theme: Optional[Union[str, Mapping[str, str], Theme]] = None,
+        title: Optional[str] = None,
+        annotations: Optional[Mapping[int, str]] = None,
+        annotation_color: Optional[str] = None,
+        fill: Optional[str] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        rounded: bool = True,
+        pad: Optional[float] = None,
+        line_height: float = 1.4,
+        tab_size: int = 4,
+        dedent: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        palette_spec: Union[str, Mapping[str, str]] = "light"
+        if isinstance(theme, Theme):
+            kwargs["theme"] = theme
+        elif theme is not None:
+            palette_spec = theme
+        super().__init__(**kwargs)
+        if lang not in CODE_LANGS:
+            raise ValueError(f"lang must be one of {CODE_LANGS}, got {lang!r}")
+        self.lang = lang
+        if isinstance(palette_spec, str):
+            if palette_spec not in CODE_THEMES:
+                raise ValueError(f"CodeBlock theme must be one of {tuple(CODE_THEMES)} or a dict")
+            self.palette_name = palette_spec
+            self.palette = dict(CODE_THEMES[palette_spec])
+        else:
+            bad = set(palette_spec) - set(CODE_THEMES["light"]) - {"base"}
+            if bad:
+                raise ValueError(f"unknown CodeBlock palette keys {sorted(bad)}; "
+                                 f"valid: {sorted(CODE_THEMES['light'])}")
+            base = str(palette_spec.get("base", "light"))
+            if base not in CODE_THEMES:
+                raise ValueError(f"palette base must be one of {tuple(CODE_THEMES)}")
+            self.palette_name = base
+            self.palette = dict(CODE_THEMES[base])
+            self.palette.update({k: v for k, v in palette_spec.items() if k != "base"})
+        src = source.expandtabs(int(tab_size))
+        if dedent:
+            src = textwrap.dedent(src).strip("\n")
+        self.source = src
+        self.lines: List[List[Token]] = tokenize(src, lang)
+        self._token_styles = {}
+        self._apply_token_colors(token_colors)
+        self.line_numbers = bool(line_numbers)
+        self.start_line = int(start_line)
+        if highlight_lines is None:
+            hl: Dict[int, str] = {}
+        elif isinstance(highlight_lines, Mapping):
+            hl = {int(k): str(v) for k, v in highlight_lines.items()}
+        else:
+            hl = {int(k): "" for k in highlight_lines}
+        for ln in hl:
+            self._check_line(ln)
+        self.highlight_lines = hl
+        self.font_size = font_size
+        self.title = title
+        self.annotations = {int(k): str(v) for k, v in (annotations or {}).items()}
+        for ln in self.annotations:
+            self._check_line(ln)
+        self.annotation_color = annotation_color
+        self.fill = fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.rounded = bool(rounded)
+        self.pad = pad
+        self.line_height = float(line_height)
+
+    def _style(self, kind):
+        return self._token_styles.get(kind, (
+            self.palette.get(kind, self.palette["plain"]),
+            kind in _BOLD.get(self.palette_name, set()), kind in _ITALIC))
+
+    def _apply_token_colors(self, spec):
+        from PIL import ImageColor
+
+        def is_color_like(color):
+            try:
+                ImageColor.getrgb(color)
+                return True
+            except ValueError:
+                return False
+
+        if spec is None:
+            return
+        if not isinstance(spec, Mapping):
+            raise ValueError("token_colors must be a mapping")
+        matches = []
+        for order, (key, value) in enumerate(spec.items()):
+            if not isinstance(key, str) or not key:
+                raise ValueError("token_colors keys must be nonempty strings")
+            options = value if isinstance(value, dict) else {"color": value}
+            if (not options or set(options) - {"color", "bold", "italic"}
+                    or any(type(options[k]) is not bool for k in ("bold", "italic") if k in options)):
+                raise ValueError(f"invalid token_colors value for {key!r}: {value!r}")
+            color = options.get("color", "plain")
+            if not isinstance(color, str):
+                raise ValueError(f"token_colors color for {key!r} must be a token type or colour")
+            if color in TOKEN_TYPES:
+                style = self._style(color)
+            elif is_color_like(color):
+                style = (color, False, False)
+            else:
+                raise ValueError(f"unknown token type or invalid colour {color!r} for {key!r}; token types: {TOKEN_TYPES}")
+            kind = f"override:{order}"
+            self._token_styles[kind] = (style[0], options.get("bold", style[1]), options.get("italic", style[2]))
+            try:
+                pattern = re.compile(key[3:] if key.startswith("re:") else r"(?<!\w)" + re.escape(key) + r"(?!\w)")
+            except re.error as exc:
+                raise ValueError(f"invalid token_colors regex {key!r}: {exc}") from exc
+            for start in range(len(self.source)):
+                m = pattern.match(self.source, start)
+                if m and m.end() > start:
+                    matches.append((start, m.end(), order, kind))
+        owners = [None] * len(self.source)
+        for start, end, order, kind in sorted(matches, key=lambda m: (-(m[1]-m[0]), m[2], m[0])):
+            if all(owner is None for owner in owners[start:end]):
+                owners[start:end] = [kind] * (end-start)
+        offset = 0
+        result = []
+        for line in self.lines:
+            pieces = []
+            for kind, text in line:
+                for char in text:
+                    actual = owners[offset] or kind
+                    if pieces and pieces[-1][0] == actual:
+                        pieces[-1] = (actual, pieces[-1][1] + char)
+                    else:
+                        pieces.append((actual, char))
+                    offset += 1
+            result.append(pieces)
+            offset += 1
+        self.lines = result
+
+    # ---- public helpers ------------------------------------------------------------
+    @property
+    def line_count(self) -> int:
+        """Number of source lines shown."""
+        return len(self.lines)
+
+    @property
+    def last_line(self) -> int:
+        """Number of the last line (``start_line + line_count - 1``)."""
+        return self.start_line + len(self.lines) - 1
+
+    def _check_line(self, n: int) -> int:
+        lo, hi = self.start_line, self.start_line + len(self.lines) - 1
+        if not lo <= int(n) <= hi:
+            raise IndexError(f"CodeBlock line {n} out of range {lo}..{hi}")
+        return int(n) - lo
+
+    def line_port(self, n: int, side: str = "right") -> Any:
+        """Port at line ``n`` (a displayed line number) for an :class:`~codefig.edges.Edge`.
+
+        ``side``: ``"right"`` / ``"left"`` — on the block border, vertically centred
+        on the line; ``"end"`` — just after the last character of the line (inside the
+        block; for short lines with arrows coming from the right).
+
+        Example: ``Edge(code.line_port(3), llm.port("left"))``.
+        """
+        from .edges import Port
+
+        if side not in ("left", "right", "end"):
+            raise ValueError("line_port side must be left|right|end")
+        self._check_line(n)
+        return Port(self, kind="row", side=side, index=int(n))
+
+    def line(self, n: int) -> CodeLineRef:
+        """Anchors of line ``n`` for constraints (``same_y(box, code.line(3))``)."""
+        self._check_line(n)
+        return CodeLineRef(self, n)
+
+    # ---- metrics --------------------------------------------------------------------
+    def _fs(self) -> float:
+        if self.font_size is not None:
+            return self.font_size
+        th = self.theme
+        if th.unit == 1.0:
+            return round(th.font_size * 0.85, 2)
+        return max(th.small_size, round(th.font_size * 0.85, 2))
+
+    def _tfs(self) -> float:
+        return self._fs() * 0.95 if self.theme.unit == 1.0 else self._fs()
+
+    def _lh(self) -> float:
+        return self._fs() * self.line_height
+
+    def _w(self, text: str, kind: str = "plain") -> float:
+        from .textutil import _plain_line_width
+
+        return _plain_line_width(text, self._fs(), True, *self._style(kind)[1:])
+
+    def _title_h(self) -> float:
+        return self._fs() * 1.9 if self.title else 0.0
+
+    def _gutter_w(self) -> float:
+        if not self.line_numbers:
+            return 0.0
+        digits = len(str(self.last_line))
+        return self._w("0" * digits) + self._fs() * 1.2
+
+    def _code_w(self) -> float:
+        return max((sum(self._w(t, _k) for _k, t in ln) for ln in self.lines), default=0.0)
+
+    def _ann_fs(self) -> float:
+        return self._tfs()
+
+    def _ann_w(self) -> float:
+        from .textutil import measure_text
+
+        if not self.annotations:
+            return 0.0
+        return max(measure_text(a, self._ann_fs())[0] for a in self.annotations.values()) + self._fs() * 1.2
+
+    def _measure(self) -> Tuple[float, float]:
+        w = self.pad * 2 + self._gutter_w() + self._code_w() + self._ann_w()
+        if self.title:
+            from .textutil import _plain_line_width
+
+            w = max(w, _plain_line_width(self.title, self._tfs(), False, True) + 2 * self.pad)
+        h = self._title_h() + self.pad * 2 + self._lh() * max(1, len(self.lines))
+        return w, h
+
+    def _line_band(self, n: int) -> Tuple[float, float]:
+        """(top y, height) of displayed line ``n`` in page coordinates."""
+        i = self._check_line(n)
+        g = self.geom
+        return g.y + self._title_h() + self.pad + i * self._lh(), self._lh()
+
+    def _line_end_x(self, n: int) -> float:
+        i = self._check_line(n)
+        g = self.geom
+        return g.x + self.pad + self._gutter_w() + sum(self._w(t, _k) for _k, t in self.lines[i])
+
+    def resolve_row_port(self, index: int, side: str) -> Tuple[float, float, str]:
+        y0, h = self._line_band(index)
+        cy = y0 + h / 2
+        g = self.geom
+        if side == "left":
+            return g.x, cy, "left"
+        if side == "end":
+            return self._line_end_x(index) + self._fs() * 0.4, cy, "right"
+        return g.right, cy, "right"
+
+    # ---- drawing -------------------------------------------------------------------
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_line, draw_rect, draw_text
+        from .textutil import xml_escape
+
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        pal = self.palette
+        fs = self._fs()
+        lh = self._lh()
+        r = self.theme.L(4.0) if self.rounded else 0.0
+        stroke = self._border_stroke(self.stroke or pal["border"])
+        draw_rect(buf, x, y, g.w, g.h, fill=self.fill or pal["bg"], stroke=stroke,
+                  stroke_width=self.stroke_width, radius=r, dasharray=self._dash(self.stroke_width))
+        th = self._title_h()
+        if self.title:
+            tfs = self._tfs()
+            draw_rect(buf, x + self.stroke_width / 2, y + self.stroke_width / 2,
+                      g.w - self.stroke_width, th - self.stroke_width / 2, fill=pal["title_bg"],
+                      stroke="none", stroke_width=0, radius=max(0.0, r - 1))
+            draw_line(buf, x, y + th, x + g.w, y + th, stroke=pal["border"], stroke_width=self.theme.SW(0.8))
+            # literal text (file names such as ``lotus_query.py`` keep their underscores)
+            from .textutil import latin_font_family_css
+
+            buf.append(f'<text x="{x + self.pad:.2f}" y="{y + th / 2 + tfs * 0.36:.2f}" '
+                       f'font-family="{xml_escape(latin_font_family_css(False))}" '
+                       f'font-size="{tfs:.2f}" font-weight="bold" fill="{pal["title"]}">'
+                       f'{xml_escape(self.title)}</text>')
+        top = y + th + self.pad
+        gw = self._gutter_w()
+        code_x = x + self.pad + gw
+        # highlighted-line bands (full inner width)
+        for ln, col in sorted(self.highlight_lines.items()):
+            i = ln - self.start_line
+            draw_rect(buf, x + self.stroke_width / 2, top + i * lh, g.w - self.stroke_width, lh,
+                      fill=col or pal["highlight"], stroke="none", stroke_width=0)
+        fam = self.theme.mono_family
+        bold = _BOLD.get(self.palette_name, set())
+        base = fs * 0.36  # baseline below the line centre
+        if self.line_numbers:
+            sep_x = x + self.pad + gw - fs * 0.6
+            draw_line(buf, sep_x, top, sep_x, top + lh * len(self.lines), stroke=pal["border"],
+                      stroke_width=self.theme.SW(0.6))
+            for i in range(len(self.lines)):
+                label = str(self.start_line + i)
+                tw = self._w(label)
+                buf.append(
+                    f'<text x="{sep_x - fs * 0.5 - tw:.2f}" y="{top + i * lh + lh / 2 + base:.2f}" '
+                    f'font-family="{fam}" font-size="{fs:.2f}" fill="{pal["gutter"]}">'
+                    f"{label}</text>")
+        for i, line in enumerate(self.lines):
+            if not line:
+                continue
+            cy = top + i * lh + lh / 2 + base
+            cx = code_x
+            spans: List[str] = []
+            for kind, text in line:
+                color, weight, italic = self._style(kind)
+                for m in re.finditer(r"\S+|\s+", text):
+                    chunk = m.group()
+                    if not chunk.isspace():
+                        attrs = f'x="{cx + self._w(text[:m.start()], kind):.2f}" fill="{color}"'
+                        if weight:
+                            attrs += ' font-weight="bold"'
+                        if italic:
+                            attrs += ' font-style="italic"'
+                        spans.append(f"<tspan {attrs}>{xml_escape(chunk)}</tspan>")
+                cx += self._w(text, kind)
+            buf.append(f'<text y="{cy:.2f}" font-family="{fam}" font-size="{fs:.2f}">'
+                       + "".join(spans) + "</text>")
+        if self.annotations:
+            ax = code_x + self._code_w() + fs * 1.2
+            afs = self._ann_fs()
+            col = self.annotation_color or self.theme.highlight
+            for ln, text in sorted(self.annotations.items()):
+                i = ln - self.start_line
+                draw_text(buf, text, ax, top + i * lh + lh / 2 + afs * 0.36, font_size=afs,
+                          fill=col)
+
+
+__all__ = ["CodeBlock", "CodeLineRef", "tokenize", "CODE_THEMES", "CODE_LANGS", "TOKEN_TYPES"]