codefig 0.17.0__py3-none-any.whl

codefig/textutil.py

@@ -0,0 +1,889 @@
+"""Text helpers: math markup, CJK-aware measure, XML escape."""
+
+from __future__ import annotations
+
+import os
+import re
+from typing import List, Optional, Sequence, Tuple
+
+# Approximate fallbacks when no font file is available
+_AVG_RATIO = 0.56
+_MONO_RATIO = 0.60
+_CJK_RATIO = 1.0  # full em for CJK ideographs in heuristic mode
+
+# Unicode subscript / superscript maps (used when collapsing to plain string)
+_SUB_MAP = str.maketrans(
+    {
+        "0": "₀", "1": "₁", "2": "₂", "3": "₃", "4": "₄",
+        "5": "₅", "6": "₆", "7": "₇", "8": "₈", "9": "₉",
+        "+": "₊", "-": "₋", "=": "₌", "(": "₍", ")": "₎",
+        "a": "ₐ", "e": "ₑ", "h": "ₕ", "i": "ᵢ", "j": "ⱼ",
+        "k": "ₖ", "l": "ₗ", "m": "ₘ", "n": "ₙ", "o": "ₒ",
+        "p": "ₚ", "r": "ᵣ", "s": "ₛ", "t": "ₜ", "u": "ᵤ",
+        "v": "ᵥ", "x": "ₓ",
+    }
+)
+_SUPER_MAP = str.maketrans(
+    {
+        "0": "⁰", "1": "¹", "2": "²", "3": "³", "4": "⁴",
+        "5": "⁵", "6": "⁶", "7": "⁷", "8": "⁸", "9": "⁹",
+        "+": "⁺", "-": "⁻", "=": "⁼", "(": "⁽", ")": "⁾",
+        "i": "ⁱ", "n": "ⁿ",
+    }
+)
+
+# q_{i1}, z_{ii}, x^{2}, a_i (single token), also ^{...}
+_MATH_TOKEN_RE = re.compile(
+    r"(\^\{([^}]+)\}|\^([A-Za-z0-9]+|[+\-−∗′″†‡])|_\{([^}]+)\}|_([A-Za-z0-9]+|[+\-−])|[^_^\n]+|\n)"
+)
+
+# CJK Unified Ideographs + Ext A/B common + fullwidth + kana/hangul
+_CJK_RE = re.compile(
+    r"[\u3000-\u303F\u3040-\u309F\u30A0-\u30FF\u3400-\u4DBF"
+    r"\u4E00-\u9FFF\uF900-\uFAFF\uFF00-\uFFEF"
+    r"\U00020000-\U0002A6DF\uAC00-\uD7AF]"
+)
+
+MathSeg = Tuple[str, str]  # (kind, text) kind in text|sub|super|nl
+
+
+def contains_cjk(text: str) -> bool:
+    return bool(_CJK_RE.search(text))
+
+
+def _is_cjk_char(ch: str) -> bool:
+    return bool(_CJK_RE.match(ch))
+
+
+# Symbols (arrows, math operators, enclosed alphanumerics ①, shapes, dingbats)
+# that serif text faces usually lack; under the serif typeface they are routed
+# to the sans face (DejaVu Sans) for both measurement and SVG output.
+_SYM_RE = re.compile(r"[\u2190-\u2BFF]")
+
+
+_glyph_cache: dict = {}
+
+
+def _lacks_glyph(ch: str) -> bool:
+    """True when the theme's resolved sans face (e.g. Liberation Sans for the paper theme)
+    has no glyph for ``ch`` — such characters (⋯, ⋮, ⊕ …) fall back to DejaVu Sans for
+    both measurement and SVG output instead of rendering as a missing-glyph box."""
+    if ord(ch) < 0x0370 or _TYPEFACE[-1] != "sans":
+        return False
+    stack = _active_stack()
+    if not stack:
+        return False
+    key = (stack, ch)
+    hit = _glyph_cache.get(key)
+    if hit is not None:
+        return hit
+    lacks = False
+    r = resolve_font_stack(stack)
+    if r is not None:
+        f = _latin_font(False, False)
+        if f is not None:
+            try:
+                def sig(c):
+                    m = f.getmask(c)
+                    return m.size, bytes(m)
+                lacks = sig(ch) == sig("\U0010FFFD")
+            except Exception:
+                lacks = False
+    _glyph_cache[key] = lacks
+    return lacks
+
+
+def _char_script(ch: str) -> str:
+    if _is_cjk_char(ch):
+        return "cjk"
+    if _TYPEFACE[-1] == "serif" and _SYM_RE.match(ch):
+        return "sym"
+    if _lacks_glyph(ch):
+        return "sym"
+    return "latin"
+
+
+def needs_script_split(text: str) -> bool:
+    """True when ``text`` mixes faces (CJK, symbols under the serif typeface, or glyphs
+    the theme's sans face lacks)."""
+    if contains_cjk(text):
+        return True
+    if _TYPEFACE[-1] == "serif":
+        return bool(_SYM_RE.search(text))
+    return any(_lacks_glyph(c) for c in text if ord(c) >= 0x0370)
+
+
+def script_runs(text: str) -> List[Tuple[str, str]]:
+    """
+    Split into contiguous (script, substring) runs.
+
+    script is "cjk", "sym" (symbols under the serif typeface) or "latin"
+    (everything else, including digits/punct). Empty text → [].
+    """
+    if not text:
+        return []
+    runs: List[Tuple[str, str]] = []
+    cur_script = _char_script(text[0])
+    buf = [text[0]]
+    for ch in text[1:]:
+        sc = _char_script(ch)
+        if sc == cur_script:
+            buf.append(ch)
+        else:
+            runs.append((cur_script, "".join(buf)))
+            cur_script = sc
+            buf = [ch]
+    runs.append((cur_script, "".join(buf)))
+    return runs
+
+
+# ---- typeface (sans | serif) ------------------------------------------------
+# The active typeface drives both measurement (Pillow face) and the CSS family
+# emitted into SVG, so layout and rendering always agree. Figure enters
+# ``use_typeface(theme.typeface)`` around layout + render.
+TYPEFACES = ("sans", "serif")
+_TYPEFACE = ["sans"]
+
+_SERIF_FILES = {
+    False: ("NimbusRoman-Regular.otf", "DejaVuSerif.ttf", "Times New Roman.ttf"),
+    True: ("NimbusRoman-Bold.otf", "DejaVuSerif-Bold.ttf", "Times New Roman Bold.ttf"),
+    (False, True): ("NimbusRoman-Italic.otf", "DejaVuSerif-Italic.ttf", "Times New Roman Italic.ttf"),
+    (True, True): ("NimbusRoman-BoldItalic.otf", "DejaVuSerif-BoldItalic.ttf",
+                   "Times New Roman Bold Italic.ttf"),
+}
+_SERIF_DIRS = (
+    "/usr/share/fonts/opentype/urw-base35",
+    "/usr/share/fonts/truetype/dejavu",
+    "/usr/share/fonts/dejavu",
+    "/Library/Fonts",
+    "/System/Library/Fonts/Supplemental",
+)
+
+
+def active_typeface() -> str:
+    return _TYPEFACE[-1]
+
+
+class use_typeface:
+    """Context manager: ``with use_typeface("serif"): ...`` (nests; restores on exit)."""
+
+    def __init__(self, name: str = "sans") -> None:
+        name = str(name or "sans").lower()
+        if name not in TYPEFACES:
+            raise ValueError(f"typeface must be one of {TYPEFACES}, got {name!r}")
+        self.name = name
+
+    def __enter__(self):
+        _TYPEFACE.append(self.name)
+        return self
+
+    def __exit__(self, *exc):
+        _TYPEFACE.pop()
+        return False
+
+
+# ---- theme font stack (0.6.0) ---------------------------------------------------
+# ``Theme.font_stack`` lists preferred sans families; the first one installed is used
+# for measurement (Pillow) and written *first* into SVG font-family (cairosvg only
+# honours the first family), so measured and rendered glyphs always agree.
+_FONT_EXTS = (".ttf", ".otf", ".ttc")
+_fc_index: Optional[dict] = None
+
+
+def _style_key(style: str) -> Optional[Tuple[bool, bool]]:
+    st = style.lower()
+    bold = "bold" in st
+    italic = "italic" in st or "oblique" in st
+    if any(k in st for k in ("light", "thin", "medium", "black", "condensed", "narrow",
+                             "semi", "demi", "extra", "heavy")):
+        return None
+    return bold, italic
+
+
+def _font_index() -> dict:
+    """family → {(bold, italic): path} for installed TrueType/OpenType fonts."""
+    global _fc_index
+    if _fc_index is not None:
+        return _fc_index
+    idx: dict = {}
+    try:
+        import subprocess
+
+        out = subprocess.run(["fc-list", ":", "family", "style", "file"], capture_output=True,
+                             text=True, timeout=10).stdout
+    except Exception:
+        out = ""
+    for line in out.splitlines():
+        try:
+            path, rest = line.split(": ", 1)
+        except ValueError:
+            continue
+        if not path.lower().endswith(_FONT_EXTS):
+            continue
+        fams, _, style = rest.partition(":style=")
+        key = _style_key(style.split(",")[0])
+        if key is None:
+            continue
+        for fam in fams.split(","):
+            idx.setdefault(fam.strip(), {}).setdefault(key, path.strip())
+    # no fontconfig (e.g. macOS without fc-list): probe well-known files
+    known = {
+        "Liberation Sans": ("/usr/share/fonts/truetype/liberation/LiberationSans-%s.ttf",
+                            {(False, False): "Regular", (True, False): "Bold",
+                             (False, True): "Italic", (True, True): "BoldItalic"}),
+        "Arial": ("/Library/Fonts/Arial%s.ttf", {(False, False): "", (True, False): " Bold",
+                                                  (False, True): " Italic",
+                                                  (True, True): " Bold Italic"}),
+    }
+    for fam, (pat, styles) in known.items():
+        if fam in idx:
+            continue
+        for key, suf in styles.items():
+            path = pat % suf
+            if os.path.exists(path):
+                idx.setdefault(fam, {})[key] = path
+    _fc_index = idx
+    return idx
+
+
+def resolve_font_stack(stack: Sequence[str]) -> Optional[Tuple[str, dict]]:
+    """First installed family of ``stack`` → (family, {(bold, italic): path})."""
+    if not stack:
+        return None
+    idx = _font_index()
+    for fam in stack:
+        files = idx.get(fam)
+        if files and (False, False) in files:
+            return fam, files
+    return None
+
+
+def _active_stack() -> Tuple[str, ...]:
+    from .styles import current_theme
+
+    return tuple(current_theme().font_stack)
+
+
+def resolved_sans_family() -> Optional[str]:
+    """The sans family actually used under the active theme (None → legacy DejaVu)."""
+    r = resolve_font_stack(_active_stack())
+    return r[0] if r else None
+
+
+def latin_font_family_css(mono: bool = False) -> str:
+    if mono:
+        return "'DejaVu Sans Mono', Menlo, Consolas, monospace"
+    if active_typeface() == "serif":
+        return "'Nimbus Roman', 'Times New Roman', Times, 'DejaVu Serif', serif"
+    stack = _active_stack()
+    r = resolve_font_stack(stack)
+    if r is not None:
+        rest = [f for f in stack if f != r[0]]
+        return ", ".join([f"'{r[0]}'"] + [f"'{f}'" if " " in f else f for f in rest]
+                         + ["sans-serif"])
+    return "'DejaVu Sans', Helvetica, Arial, sans-serif"
+
+
+_US = "\uE05F"  # placeholder for a literal underscore while tokenising math markup
+_IDENT_US = re.compile(r"(?<=[A-Za-z]{3})_(?=[A-Za-z0-9])")
+
+
+def _protect_identifier_underscores(text: str) -> str:
+    text = text.replace("\\_", _US)
+    return _IDENT_US.sub(_US, text)
+
+
+def parse_math_markup(text: str) -> List[MathSeg]:
+    """
+    Parse simple math markup into segments.
+
+    Supports: `q_{i}`, `z_{i1}`, `a_ii`, `x^{2}`, `x^2`, and (v0.13.0) one sign or
+    prime without braces: `H_1^+`, `x^′`, `P^∗`, `y_-` (any Unicode inside braces).
+    Newlines become ('nl', '').
+
+    Identifiers stay literal: an underscore after a word of three or more letters
+    (``same_y``, ``kv_cache``, ``lint_ignore``) is not a subscript, nor is ``\\_``.
+    Braces always subscript (``attn_{i}``).
+    """
+    if not text:
+        return []
+    text = _protect_identifier_underscores(text)
+    segs: List[MathSeg] = []
+    for m in _MATH_TOKEN_RE.finditer(text):
+        tok = m.group(0).replace(_US, "_")
+        if tok == "\n":
+            segs.append(("nl", ""))
+        elif m.group(2) is not None:
+            segs.append(("super", m.group(2)))
+        elif m.group(3) is not None:
+            segs.append(("super", m.group(3)))
+        elif m.group(4) is not None:
+            segs.append(("sub", m.group(4)))
+        elif m.group(5) is not None:
+            segs.append(("sub", m.group(5)))
+        else:
+            segs.append(("text", tok))
+    return segs
+
+
+def expand_subscripts(text: str) -> str:
+    """Collapse markup to a plain unicode string (for measure fallback / plain SVG)."""
+    parts: List[str] = []
+    for kind, body in parse_math_markup(text):
+        if kind == "nl":
+            parts.append("\n")
+        elif kind == "sub":
+            parts.append(body.translate(_SUB_MAP))
+        elif kind == "super":
+            parts.append(body.translate(_SUPER_MAP))
+        else:
+            parts.append(body)
+    return "".join(parts)
+
+
+def has_math_markup(text: str) -> bool:
+    return bool(re.search(r"[_^]", text))
+
+
+# ---- fonts -----------------------------------------------------------------
+
+_LATIN_FILES = {
+    (False, False): "DejaVuSans.ttf",
+    (False, True): "DejaVuSans-Bold.ttf",
+    (True, False): "DejaVuSansMono.ttf",
+    (True, True): "DejaVuSansMono-Bold.ttf",
+    (False, False, True): "DejaVuSans-Oblique.ttf",
+    (False, True, True): "DejaVuSans-BoldOblique.ttf",
+    (True, False, True): "DejaVuSansMono-Oblique.ttf",
+    (True, True, True): "DejaVuSansMono-BoldOblique.ttf",
+}
+_LATIN_DIRS = (
+    "/usr/share/fonts/truetype/dejavu",
+    "/usr/share/fonts/dejavu",
+    "/Library/Fonts",
+)
+
+# (path, face_index) for SC Regular / Bold
+_CJK_CANDIDATES = (
+    ("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", 2),  # SC
+    ("/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc", 2),
+    ("/usr/share/fonts/opentype/noto/NotoSerifCJK-Regular.ttc", 2),
+)
+_CJK_BOLD_CANDIDATES = (
+    ("/usr/share/fonts/opentype/noto/NotoSansCJK-Bold.ttc", 2),
+    ("/usr/share/fonts/opentype/noto/NotoSerifCJK-Bold.ttc", 2),
+    ("/usr/share/fonts/opentype/noto/NotoSansCJK-Regular.ttc", 2),
+)
+
+_font_cache: dict = {}
+
+
+def _load_truetype(path: str, size: int, index: int = 0):
+    from PIL import ImageFont
+
+    try:
+        return ImageFont.truetype(path, size, index=index)
+    except TypeError:
+        # older Pillow without index=
+        return ImageFont.truetype(path, size)
+    except Exception:
+        return None
+
+
+def _latin_font(mono: bool, bold: bool, italic: bool = False):
+    face = "sans" if mono else active_typeface()
+    stack = _active_stack() if (face == "sans" and not mono) else ()
+    key = ("latin", mono, bold, face, italic, stack)
+    if key in _font_cache:
+        return _font_cache[key]
+    f = None
+    if stack:
+        r = resolve_font_stack(stack)
+        if r is not None:
+            files = r[1]
+            path = files.get((bold, italic)) or files.get((bold, False)) or files[(False, False)]
+            f = _load_truetype(path, 100, 0)
+            if f is not None:
+                _font_cache[key] = f
+                return f
+    if face == "serif":
+        names = _SERIF_FILES[(bold, True)] if italic else _SERIF_FILES[bold]
+        for name in names:
+            for d in _SERIF_DIRS:
+                path = os.path.join(d, name)
+                if os.path.exists(path):
+                    f = _load_truetype(path, 100, 0)
+                    if f is not None:
+                        break
+            if f is not None:
+                break
+        if f is None and italic:
+            f = _latin_font(mono, bold, False)
+        _font_cache[key] = f
+        return f
+    try:
+        fname = _LATIN_FILES[(mono, bold, True)] if italic else _LATIN_FILES[(mono, bold)]
+        for d in _LATIN_DIRS:
+            path = os.path.join(d, fname)
+            if os.path.exists(path):
+                f = _load_truetype(path, 100, 0)
+                break
+    except Exception:
+        f = None
+    if f is None and italic:
+        f = _latin_font(mono, bold, False)
+    _font_cache[key] = f
+    return f
+
+
+def _cjk_font(bold: bool = False):
+    key = ("cjk", bold)
+    if key in _font_cache:
+        return _font_cache[key]
+    f = None
+    cands = _CJK_BOLD_CANDIDATES if bold else _CJK_CANDIDATES
+    for path, idx in cands:
+        if os.path.exists(path):
+            f = _load_truetype(path, 100, idx)
+            if f is not None:
+                break
+    _font_cache[key] = f
+    return f
+
+
+def cjk_font_family_css() -> str:
+    """CSS font-family stack that includes a CJK face when available on the box."""
+    if _cjk_font(False) is not None:
+        return (
+            "'Noto Sans CJK SC', 'Noto Sans CJK JP', 'Source Han Sans SC', "
+            "DejaVu Sans, Helvetica, Arial, sans-serif"
+        )
+    return "DejaVu Sans, Helvetica, Arial, sans-serif"
+
+
+def sym_font_family_css() -> str:
+    return "'DejaVu Sans', sans-serif"
+
+
+def _sym_font(bold: bool):
+    with use_typeface("sans"):
+        return _latin_font(False, bold)
+
+
+def _font_for_script(script: str, mono: bool, bold: bool, italic: bool = False):
+    if script == "sym":
+        return _sym_font(bold)
+    if script == "cjk":
+        f = _cjk_font(bold)
+        if f is not None:
+            return f
+    return _latin_font(mono, bold, italic)
+
+
+def _run_width(run: str, script: str, font_size: float, mono: bool, bold: bool,
+               italic: bool = False) -> float:
+    f = _font_for_script(script, mono, bold, italic)
+    if f is not None:
+        return f.getlength(run) * font_size / 100.0
+    ratio = _MONO_RATIO if mono else _AVG_RATIO
+    if script == "cjk":
+        return len(run) * font_size * _CJK_RATIO
+    return len(run) * font_size * ratio * (1.08 if bold else 1.0)
+
+
+def _plain_line_width(line: str, font_size: float, mono: bool, bold: bool,
+                      italic: bool = False) -> float:
+    """Sum per-script run widths (Latin face for Latin, Noto CJK for CJK)."""
+    if not line:
+        return 0.0
+    if not needs_script_split(line):
+        return _run_width(line, "latin", font_size, mono, bold, italic)
+    return sum(
+        _run_width(run, script, font_size, mono, bold, italic)
+        for script, run in script_runs(line)
+    )
+
+
+def measure_text(
+    text: str,
+    font_size: float,
+    *,
+    mono: bool = False,
+    weight: str = "normal",
+    line_height: float = 1.25,
+    italic: bool = False,
+) -> Tuple[float, float]:
+    """
+    Text block size in px.
+
+    Rich-text markup (``**bold**``, ``*italic*``, ```code```, ``[color=#c00]…[/]``,
+    ``[bg=#ffe08a]…[/]``; see :func:`parse_rich`) is measured run by run with the
+    matching bold / italic / mono faces.
+
+    Uses Pillow with per-run Latin (DejaVu) ↔ CJK (Noto Sans CJK SC) switching for
+    mixed strings; falls back to a per-script glyph-ratio heuristic. Math markup
+    (`q_{i1}`, `x^{2}`) is measured with sub/super at 0.75× size.
+    """
+    from .styles import current_theme
+
+    font_size = current_theme().snap(font_size)
+    if not text:
+        return 0.0, font_size * line_height
+    bold = str(weight) in ("bold", "600", "700", "800", "900")
+    if has_rich_markup(text):
+        lines = parse_rich(text)
+        w = max((rich_line_width(ln, font_size, mono=mono, bold=bold, italic=italic)
+                 for ln in lines), default=0.0)
+        return w, max(1, len(lines)) * font_size * line_height
+    # Measure line by line with markup awareness
+    lines_segs: List[List[MathSeg]] = [[]]
+    for kind, body in parse_math_markup(text):
+        if kind == "nl":
+            lines_segs.append([])
+        else:
+            lines_segs[-1].append((kind, body))
+
+    max_w = 0.0
+    for segs in lines_segs:
+        if not segs:
+            max_w = max(max_w, 0.0)
+            continue
+        # If no sub/super, measure whole plain line (better kerning)
+        if all(k == "text" for k, _ in segs):
+            plain = "".join(b for _, b in segs)
+            max_w = max(max_w, _plain_line_width(plain, font_size, mono, bold, italic))
+            continue
+        w = _segs_width(segs, font_size, mono, bold, italic)
+        max_w = max(max_w, w)
+
+    height = max(1, len(lines_segs)) * font_size * line_height
+    return max_w, height
+
+
+def _segs_width(segs, font_size: float, mono: bool, bold: bool, italic: bool = False) -> float:
+    """Width of one line of math segments (text / sub / super)."""
+    from .styles import current_theme
+
+    th = current_theme()
+    sfs = th.script_size(font_size)
+    if th.font_sizes:  # paper-style themes: measure exactly what draw_text renders
+        ws = [_plain_line_width(body, sfs if kind in ("sub", "super") else font_size,
+                                mono, bold, italic if kind == "text" else False)
+              for kind, body in segs]
+        return sum(stack_script_advances([k for k, _ in segs], ws))
+    if True:
+        w = 0.0
+        for kind, body in segs:
+            fs = sfs if kind in ("sub", "super") else font_size
+            # Prefer unicode-collapsed form for font getlength on sub/super
+            if kind == "sub":
+                body_m = body.translate(_SUB_MAP)
+                # If translation left ASCII (unknown glyphs), measure at 0.75 with original
+                if body_m == body:
+                    w += _plain_line_width(body, fs, mono, bold)
+                else:
+                    w += _plain_line_width(body_m, font_size, mono, bold) * max(0.85, sfs / font_size)
+            elif kind == "super":
+                body_m = body.translate(_SUPER_MAP)
+                if body_m == body:
+                    w += _plain_line_width(body, fs, mono, bold)
+                else:
+                    w += _plain_line_width(body_m, font_size, mono, bold) * max(0.85, sfs / font_size)
+            else:
+                w += _plain_line_width(body, fs, mono, bold, italic)
+        return w
+
+
+def xml_escape(s: str) -> str:
+    return (
+        s.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def split_lines(text: str) -> List[str]:
+    """Plain (unicode-expanded) lines — for simple Text layout loops."""
+    return expand_subscripts(text).split("\n")
+
+
+def math_lines(text: str) -> List[List[MathSeg]]:
+    """Segment lists per visual line (for SVG tspan rendering)."""
+    lines: List[List[MathSeg]] = [[]]
+    for kind, body in parse_math_markup(text):
+        if kind == "nl":
+            lines.append([])
+        else:
+            lines[-1].append((kind, body))
+    return lines
+
+
+# ---- rich text (inline spans) ----------------------------------------------
+#
+# A deliberately tiny markup usable in *every* label (Text, Box text / subtitle,
+# Group titles, edge labels, Matrix cells, Badges, Legend keys):
+#
+#   **bold**   *italic*   `mono`   [color=#c00]red[/]   [bg=#ffe08a]highlight[/]
+#   [b]…[/]  [i]…[/]  [u]underline[/]  [mono]…[/]  [#c00]…[/] (colour shorthand)
+#   tags combine:  [color=#c00 bg=#fee b]…[/]      escapes:  \*  \`  \[  \\
+#
+# Existing math markup (_{…} / ^{…}) keeps working inside any span. Unknown
+# bracket text such as "[...]" is literal.
+
+from dataclasses import dataclass as _dataclass, replace as _dc_replace
+
+
+@_dataclass(frozen=True)
+class Run:
+    """One styled run of text (no newlines)."""
+
+    text: str
+    bold: bool = False
+    italic: bool = False
+    mono: bool = False
+    color: Optional[str] = None
+    bg: Optional[str] = None
+    underline: bool = False
+    kind: str = "text"  # text | sub | super
+
+
+_TAG_RE = re.compile(r"\[(/|[#a-zA-Z][^\[\]\n]{0,60})\]")
+_COLOR_RE = re.compile(r"^(#[0-9a-fA-F]{3,8}|[a-zA-Z]+|rgb\([0-9., %]+\))$")
+_RICH_HINT_RE = re.compile(r"\*\*|(?<![\\\w*])\*(?=[^\s*])|`|\\[*`\[\\]|\[(?:/|#|b\]|i\]|u\]|mono\]|color=|bg=)")
+
+
+def _parse_tag(body: str) -> Optional[dict]:
+    """``color=#c00 bg=#fee b`` → style dict, or None when not a valid tag."""
+    out: dict = {}
+    for tok in body.replace(",", " ").split():
+        if "=" in tok:
+            k, v = tok.split("=", 1)
+            k = k.lower()
+            if k in ("color", "c", "fg") and _COLOR_RE.match(v):
+                out["color"] = v
+            elif k in ("bg", "highlight", "hl") and _COLOR_RE.match(v):
+                out["bg"] = v
+            else:
+                return None
+        elif tok.startswith("#") and _COLOR_RE.match(tok):
+            out["color"] = tok
+        elif tok.lower() in ("b", "bold"):
+            out["bold"] = True
+        elif tok.lower() in ("i", "italic", "em"):
+            out["italic"] = True
+        elif tok.lower() in ("u", "underline"):
+            out["underline"] = True
+        elif tok.lower() in ("mono", "code", "tt"):
+            out["mono"] = True
+        else:
+            return None
+    return out or None
+
+
+def has_rich_markup(text: str) -> bool:
+    """Cheap test: does ``text`` contain inline span markup?"""
+    if not text or not _RICH_HINT_RE.search(text):
+        return False
+    lines = parse_rich(text)
+    flat = [r for ln in lines for r in ln]
+    return any(r.bold or r.italic or r.mono or r.color or r.bg or r.underline for r in flat) or \
+        "".join(r.text for r in flat if r.kind == "text") != _strip_math_free(text)
+
+
+def _strip_math_free(text: str) -> str:
+    return "".join(b for k, b in parse_math_markup(text) if k == "text")
+
+
+def parse_rich(text: str) -> List[List[Run]]:
+    """Parse inline markup into lines of :class:`Run` (math sub/super split out)."""
+    lines: List[List[Run]] = [[]]
+    stack: List[Run] = [Run("")]  # style stack (text unused)
+    bold_on = italic_on = mono_on = False
+    buf: List[str] = []
+
+    def style() -> Run:
+        st = stack[-1]
+        return _dc_replace(st, bold=st.bold or bold_on, italic=st.italic or italic_on,
+                           mono=st.mono or mono_on)
+
+    def flush() -> None:
+        if not buf:
+            return
+        chunk = "".join(buf)
+        buf.clear()
+        st = style()
+        for kind, body in parse_math_markup(chunk) if not st.mono else [("text", chunk)]:
+            if kind == "nl":
+                lines.append([])
+            elif body:
+                lines[-1].append(_dc_replace(st, text=body, kind=kind))
+
+    i, n = 0, len(text)
+    while i < n:
+        ch = text[i]
+        if ch == "\\" and i + 1 < n and text[i + 1] in "*`[\\_^":
+            buf.append(text[i + 1] if text[i + 1] not in "_^" else text[i + 1])
+            i += 2
+            continue
+        if mono_on and ch != "`":
+            if ch == "\n":
+                flush()
+                lines.append([])
+            else:
+                buf.append(ch)
+            i += 1
+            continue
+        if ch == "`":
+            flush()
+            mono_on = not mono_on
+            i += 1
+            continue
+        if text.startswith("**", i) and (bold_on or (i + 2 < n and not text[i + 2].isspace())):
+            flush()
+            bold_on = not bold_on
+            i += 2
+            continue
+        if ch == "*":
+            prev = text[i - 1] if i > 0 else " "
+            nxt = text[i + 1] if i + 1 < n else " "
+            opening = (not italic_on) and not nxt.isspace() and not (prev.isalnum())
+            closing = italic_on and not prev.isspace()
+            if opening or closing:
+                flush()
+                italic_on = not italic_on
+                i += 1
+                continue
+        if ch == "[":
+            m = _TAG_RE.match(text, i)
+            if m:
+                body = m.group(1)
+                if body == "/":
+                    if len(stack) > 1:
+                        flush()
+                        stack.pop()
+                        i = m.end()
+                        continue
+                else:
+                    spec = _parse_tag(body)
+                    if spec is not None:
+                        flush()
+                        cur = stack[-1]
+                        stack.append(_dc_replace(
+                            cur,
+                            bold=cur.bold or spec.get("bold", False),
+                            italic=cur.italic or spec.get("italic", False),
+                            mono=cur.mono or spec.get("mono", False),
+                            underline=cur.underline or spec.get("underline", False),
+                            color=spec.get("color", cur.color),
+                            bg=spec.get("bg", cur.bg),
+                        ))
+                        i = m.end()
+                        continue
+        if ch == "\n":
+            flush()
+            lines.append([])
+            i += 1
+            continue
+        buf.append(ch)
+        i += 1
+    flush()
+    return lines
+
+
+def strip_markup(text: str) -> str:
+    """Plain text of a (possibly marked-up) label (math markup kept)."""
+    if not has_rich_markup(text):
+        return text
+    out = []
+    for ln in parse_rich(text):
+        parts = []
+        for r in ln:
+            parts.append(r.text if r.kind == "text" else ("_{" if r.kind == "sub" else "^{") + r.text + "}")
+        out.append("".join(parts))
+    return "\n".join(out)
+
+
+def run_width(r: Run, font_size: float, *, mono: bool = False, bold: bool = False,
+              italic: bool = False) -> float:
+    b, it, mo = (bold or r.bold), (italic or r.italic), (mono or r.mono)
+    if r.kind in ("sub", "super"):
+        return _segs_width([(r.kind, r.text)], font_size, mo, b, it)
+    return _plain_line_width(r.text, font_size, mo, b, it)
+
+
+def stack_script_advances(kinds: Sequence[str], ws: Sequence[float]) -> List[float]:
+    """v0.13.0: a subscript directly followed by a superscript (or the reverse) is
+    stacked — ``H_1^+`` draws ⁺ above ₁ — so the first script advances 0 and the
+    second advances the wider of the two."""
+    out = list(ws)
+    i = 0
+    while i < len(kinds) - 1:
+        if {kinds[i], kinds[i + 1]} == {"sub", "super"}:
+            out[i + 1] = max(out[i], out[i + 1])
+            out[i] = 0.0
+            i += 2
+        else:
+            i += 1
+    return out
+
+
+def run_widths(runs: Sequence[Run], font_size: float, *, mono: bool = False,
+               bold: bool = False, italic: bool = False) -> List[float]:
+    """Advance of each run, with a v0.12.0 italic correction: an upright run that
+    ends in a space before an italic run (and an italic run before an upright one)
+    gets ~0.12 em extra, so ``"gate *G*"`` keeps a visible space (slanted glyphs
+    otherwise eat it)."""
+    ws = stack_script_advances([r.kind for r in runs],
+                               [run_width(r, font_size, mono=mono, bold=bold, italic=italic)
+                                for r in runs])
+    if italic:
+        return ws
+    for i in range(len(runs) - 1):
+        a, b = runs[i], runs[i + 1]
+        if b.italic and not a.italic and a.text.endswith(" "):
+            ws[i] += 0.12 * font_size
+        elif a.italic and not b.italic and b.text.startswith(" "):
+            ws[i] += 0.08 * font_size
+    return ws
+
+
+def rich_line_width(runs: Sequence[Run], font_size: float, *, mono: bool = False,
+                    bold: bool = False, italic: bool = False) -> float:
+    return sum(run_widths(runs, font_size, mono=mono, bold=bold, italic=italic))
+
+
+def _escape_markup(s: str) -> str:
+    return s.replace("\\", "\\\\").replace("*", "\\*").replace("`", "\\`").replace("[", "\\[")
+
+
+def markup_lines(text: str) -> List[str]:
+    """Split ``text`` into visual lines, each a self-contained markup string
+    (spans that cross a newline are re-opened on the next line)."""
+    if not has_rich_markup(text):
+        return text.split("\n")
+    out = []
+    for ln in parse_rich(text):
+        parts = []
+        for r in ln:
+            body = _escape_markup(r.text)
+            if r.kind == "sub":
+                body = "_{" + body + "}"
+            elif r.kind == "super":
+                body = "^{" + body + "}"
+            tags = []
+            if r.bold:
+                tags.append("b")
+            if r.italic:
+                tags.append("i")
+            if r.mono:
+                tags.append("mono")
+            if r.underline:
+                tags.append("u")
+            if r.color:
+                tags.append(f"color={r.color}")
+            if r.bg:
+                tags.append(f"bg={r.bg}")
+            parts.append(f"[{' '.join(tags)}]{body}[/]" if tags else body)
+        out.append("".join(parts))
+    return out