codefig 0.17.0__py3-none-any.whl

codefig/lint.py

@@ -0,0 +1,1737 @@
+"""Publication-style lint: check a laid-out Figure against the codefig figure rules.
+
+The rules (``RULES``) were derived from measuring ~100 figures of well-regarded
+systems / ML papers plus the NeurIPS, ICLR, ICML, MLSys, ACM and USENIX templates
+(see ``docs/lint-rules.md``). Use::
+
+    report = fig.lint(venue="icml", width="column")
+    print(report)            # human table
+    report.ok                # no errors?
+    report.to_json()         # for agents / CI
+    report.raise_for_errors()
+
+Everything is measured at **final print size**: a physical (pt) figure is checked as
+is; a legacy px figure is checked as if scaled to the venue width; ``scale=`` is the
+LaTeX ``\\includegraphics[scale=…]`` factor on top.
+
+Suppress per element with ``Box(..., lint_ignore=["CF-TXT-006"])`` (applies to the
+node and everything drawn inside it), per call with ``ignore=[...]``, or globally
+with ``codefig.lint_config.disable = [...]``.
+"""
+
+from __future__ import annotations
+
+import json
+import math
+import re
+import xml.etree.ElementTree as ET
+from dataclasses import asdict, dataclass, field
+from typing import Union, Any, Dict, Iterable, List, Optional, Sequence, Tuple
+
+SEVERITIES = ("error", "warn", "info")
+
+
+@dataclass(frozen=True)
+class Rule:
+    id: str
+    title: str
+    severity: str  # strongest severity the rule can emit
+    threshold: str
+    fix: str
+    implemented: bool = True
+
+
+def _r(id, title, sev, thr, fix, impl=True):
+    return Rule(id, title, sev, thr, fix, impl)
+
+
+RULES: Dict[str, Rule] = {r.id: r for r in [
+    _r("CF-TXT-001", "Minimum font size at final width", "error", "warn < 6 pt, error < 5 pt",
+       "use the theme size roles (6/7/8 pt); widen the figure (width='text') or shorten labels"),
+    _r("CF-TXT-002", "At most three font sizes", "warn", "> 3 sizes (0.5 pt bins) or max/median > 1.6",
+       "drop free font_size= values; let sizes snap to the theme roles"),
+    _r("CF-TXT-003", "Figure text no larger than body text", "info", "> body + 1 pt",
+       "use the 7 pt label role; body text is 9–10 pt"),
+    _r("CF-TXT-004", "One text family", "warn", "> 1 family (mono for code allowed)",
+       "remove family=/typeface overrides; use mono=True only for code"),
+    _r("CF-TXT-005", "No text overlap / text crossed by edges", "error",
+       "any text–text, text–edge, label–box overlap",
+       "increase gap=, move the label (label_side=, label_at=) or allow_overlap() if intended"),
+    _r("CF-TXT-006", "Short labels", "warn", "> 4 words/line, > 2 lines, > 24 chars/line in a "
+       "Box / shape label (Text, edge labels, titles and notes are not checked)",
+       "shorten the label; move detail into the LaTeX caption"),
+    _r("CF-TXT-007", "Text padding inside boxes", "error",
+       "overflow = error; pad < 0.4 em (h) or < 0.2 em (v) = warn",
+       "drop fixed w=/h= or enlarge the box; keep the theme box padding"),
+    _r("CF-TXT-008", "Emphasis discipline", "info", "> 2 text colours; bold outside titles",
+       "black text plus one accent colour; bold only for titles and panel tags"),
+    _r("CF-TXT-010", "Drawn text is not covered, struck through or overlapped", "error",
+       "opaque fill painted over ≥ 12 % of a text run, a stroke through its middle band, "
+       "or two text runs overlapping = error; a stroke grazing the glyph box = warn",
+       "give the label room (gap=, pad=, label_side=), move the covering box, or route the "
+       "line around it; allow with lint_ignore=['CF-TXT-010'] on the owner if intended"),
+    _r("CF-ANN-001", "Guides avoid captions", "warn", "guide segment touches a panel or group caption",
+       "move the caption or guide endpoint; use Guide(avoid_text=True) for automatic detours"),
+    _r("CF-TXT-011", "No silently dropped or truncated labels", "warn",
+       "a label the engine shortened (…) or did not draw because it had no room",
+       "widen the element / figure, shorten the text, or pass the documented fallback "
+       "(e.g. value_pos='outside')"),
+    _r("CF-COL-001", "Hue budget", "warn", "5 hues = info, > 5 = warn",
+       "merge categories; use category= (the 6 palette fills) plus neutral grey"),
+    _r("CF-COL-002", "Colour-vision-deficiency safety", "error",
+       "deutan/protan ΔE < 10 warn, < 5 error (Machado 2009, CIE76)",
+       "use category= (theme palette, 6 CVD-safe fills) instead of hand-picked fills, with "
+       "fig.color(name) for chart series / edges keyed to the same thing and one "
+       "Legend(source='figure') as the key"),
+    _r("CF-COL-003", "Grey-scale distinguishable", "warn", "ΔL* < 8 without hatch/dash cue",
+       "use the paper palette (lightness-staggered) or add pattern=Hatch()"),
+    _r("CF-COL-004", "Meaningful colour needs a key", "warn",
+       "≥ 2 categories without a Legend (or direct labels)",
+       "add Legend() to the panel, or label categories directly"),
+    _r("CF-COL-005", "Pastel fills, dark text", "info", "text/background ΔL* < 50",
+       "lighter fill (L* ≥ 62) behind black text, or white text on dark fills"),
+    _r("CF-COL-006", "No red–green-only contrast", "warn", "normal ΔE > 30 but deutan ΔE < 10",
+       "replace the red/green pair with vermilion/blue (Okabe-Ito)"),
+    _r("CF-STR-001", "Minimum stroke width", "error", "warn < 0.5 pt, error < 0.25 pt",
+       "use theme stroke roles (0.6 / 0.75 / 1.2 pt); avoid shrinking the figure"),
+    _r("CF-STR-002", "At most 3 stroke widths, 2 dash patterns", "warn",
+       "> 3 widths (0.1 pt bins) or > 2 dash patterns", "drop free stroke_width=/dash values"),
+    _r("CF-STR-003", "Dashes mean something", "info", "dashed edge without legend",
+       "give the dashed edge legend='control' (and add a Legend) or make it solid"),
+    _r("CF-ARR-001", "Arrow consistency", "warn", "> 2 arrowhead styles or > 1 head size",
+       "use the theme head (stealth 4×3 pt) everywhere"),
+    _r("CF-ARR-002", "Edge routing", "warn", "edge passes through a box; crossings (info)",
+       "re-order nodes, use ports (a.right → b.left) or route='ortho'"),
+    _r("CF-ARR-003", "Edges attach to visible elements", "warn",
+       "endpoint on an invisible Row / Col / Stack / Grid holding ≥ 2 boxes: warn on blank "
+       "space, info when it touches a child (name that child's port)",
+       "use the port of the box the reader sees (e.g. top_prob.port('right'), not "
+       "Col([top_prob, rest]).port('right'))"),
+    _r("CF-ARR-004", "No small interior edge jogs", "warn", "interior segment < 4 pt",
+       "use jog_tol or align the endpoint nodes"),
+    _r("CF-ARR-005", "Return edges stay near the diagram", "warn", "return edge expands bounds > 24 pt",
+       "use loop_side or leave a routing channel"),
+    _r("CF-REG-001", "Regions contain only their members", "warn",
+       "a non-member box has > 15 % of its area inside a Region outline",
+       "keep Region(exclude='auto') (push / carve), add the box to members=, or move it"),
+    _r("CF-LAY-001", "Alignment grid", "warn", "aligned fraction < 0.8 info, < 0.5 warn (1 pt)",
+       "build with Row/Col/Grid; same_width()/align() constraints"),
+    _r("CF-LAY-002", "Consistent gaps", "warn", "sibling-gap CV > 0.25",
+       "use one gap= per Row/Col (theme default)"),
+    _r("CF-LAY-003", "One corner radius", "warn", "> 1 radius among boxes",
+       "drop per-box radius=; use the theme radius"),
+    _r("CF-LAY-004", "Aspect ratio for the slot", "info", "text width 2–4.5, column 1.1–2.5",
+       "re-arrange panels (cols=, grid=) for the slot"),
+    _r("CF-LAY-005", "No unintended box overlap", "error", "partial overlap of boxes",
+       "increase gap= or mark allow_overlap()"),
+    _r("CF-LAY-009", "Legend obscures content", "warn", "corner legend overlaps content",
+       "try a clear corner or external placement"),
+    _r("CF-LAY-008", "Requested aspect ratio", "warn", "target aspect differs by more than 8%",
+       "Remove a row, use fit='scale', or relax aspect."),
+    _r("CF-LAY-007", "Panels use their cell", "warn",
+       "content covers < 55 % of the panel's inner area = info, < 40 % = warn",
+       "rebalance Figure(grid=...) so short panels share a row, or lay the content out "
+       "horizontally (Row) to match the cell"),
+    _r("CF-EXP-001", "Designed at venue width, scale 1", "warn",
+       "width ≠ venue ±2 %, or shrink pushes fonts below the minimum",
+       "Figure(venue=..., width='column'|'text') and \\includegraphics at scale 1; see docs/cookbook/30_compact_column.py"),
+    _r("CF-EXP-002", "Vector output, embedded fonts", "error", "Type 3 / unembedded fonts",
+       "save as .pdf or .svg (cairosvg embeds TrueType subsets)"),
+    _r("CF-EXP-003", "Raster resolution", "warn", "embedded image < 300 dpi at final size",
+       "use a higher-resolution or vector image"),
+    _r("CF-EXP-004", "No in-figure title", "info", "Figure(title=...) set",
+       "put the title in the LaTeX caption"),
+    _r("CF-EXP-005", "Alt text", "info", "no alt text", "fig.save(..., alt='...')"),
+]}
+
+
+class LintError(Exception):
+    """Raised by :meth:`LintReport.raise_for_errors` / ``save(lint="error")``.
+
+    The message lists every error with its elements and fix hint; its **last line** is a
+    one-line summary (each error: rule, element, fix) plus the preview path and how to
+    keep iterating without raising (``fig.preview()`` or ``fig.save(path, lint="warn")``).
+    Attributes: ``report`` (the :class:`LintReport`), ``preview`` (path or ``None``).
+    """
+
+    def __init__(self, report: "Union[LintReport, str]", *, preview: Any = None,
+                 target: Any = None) -> None:
+        self.preview = preview
+        if isinstance(report, str):
+            self.report = None
+            super().__init__(report)
+            return
+        self.report = report
+        super().__init__(self._message(report, preview, target))
+
+    @staticmethod
+    def _short_el(f: "Finding") -> str:
+        if not f.elements:
+            return ""
+        el = ", ".join(f.elements[:2]) + (" …" if len(f.elements) > 2 else "")
+        return f" [{el}]"
+
+    @classmethod
+    def _message(cls, report: "LintReport", preview: Any, target: Any) -> str:
+        errs = [f for f in report.findings if f.severity == "error"]
+        warns = [f for f in report.findings if f.severity == "warn"]
+        name = getattr(target, "name", None) or (str(target) if target else None)
+        head = (f"{len(errs)} lint error(s), {len(warns)} warning(s)"
+                + (f": nothing was written to {name}" if name else "") + ":")
+        rows = [head]
+        for f in errs + warns:
+            rows.append("  " + f.line())
+            if f.fix:
+                rows.append("        fix: " + f.fix)
+        if preview is not None:
+            rows.append(f"  preview: {preview} (errors outlined in red, warnings in orange)")
+        summ = "; ".join(f"{f.rule_id}{cls._short_el(f)}: {f.message[:90]}"
+                         + (f" -> fix: {f.fix[:110]}" if f.fix else "") for f in errs)
+        tail = f"LINT REFUSED SAVE ({len(errs)} error(s)): {summ}"
+        if preview is not None:
+            tail += f" | preview: {preview}"
+        tail += (" | keep iterating without raising: fig.preview() or "
+                 "fig.save(path, lint=\"warn\")")
+        rows.append(tail)
+        return "\n".join(rows)
+
+
+class LintWarning(UserWarning):
+    """Emitted per finding by ``save(lint="warn")``."""
+
+
+class CaptionWarning(UserWarning):
+    """v0.14.0: a panel title that will not be drawn (``caption="none"``)."""
+
+
+@dataclass
+class LintConfig:
+    """Global settings: ``codefig.lint_config.disable = ["CF-EXP-005"]``;
+    ``thresholds = {"CF-TXT-001": {"warn": 6.5}}``."""
+
+    disable: List[str] = field(default_factory=list)
+    thresholds: Dict[str, Dict[str, float]] = field(default_factory=dict)
+
+
+lint_config = LintConfig()
+
+
+@dataclass
+class Finding:
+    rule_id: str
+    severity: str
+    message: str
+    elements: List[str] = field(default_factory=list)
+    measured: Optional[float] = None
+    threshold: Optional[float] = None
+    fix: str = ""
+    boxes: List[List[float]] = field(default_factory=list)  # v0.12: SVG-root bboxes
+
+    def line(self) -> str:
+        el = f" [{', '.join(self.elements[:3])}{' …' if len(self.elements) > 3 else ''}]" if self.elements else ""
+        return f"{self.severity.upper():5s} {self.rule_id} {self.message}{el}"
+
+
+@dataclass
+class LintReport:
+    findings: List[Finding]
+    venue: Optional[str] = None
+    width_pt: Optional[float] = None
+    factor: float = 1.0  # authoring unit → printed pt
+    checked: List[str] = field(default_factory=list)
+    image: Optional[str] = None    # set by Figure.preview(): the figure written
+    preview: Optional[str] = None  # set by Figure.preview(): the outlined lint preview
+
+    @property
+    def ok(self) -> bool:
+        """True when there are no ``error`` findings."""
+        return not any(f.severity == "error" for f in self.findings)
+
+    def by_severity(self, sev: str) -> List[Finding]:
+        return [f for f in self.findings if f.severity == sev]
+
+    @property
+    def errors(self) -> List[Finding]:
+        return self.by_severity("error")
+
+    @property
+    def warnings(self) -> List[Finding]:
+        return self.by_severity("warn")
+
+    def to_dict(self) -> dict:
+        return {"ok": self.ok, "venue": self.venue, "width_pt": self.width_pt,
+                "factor": self.factor, "checked": self.checked,
+                "findings": [asdict(f) for f in self.findings]}
+
+    def to_json(self, **kw: Any) -> str:
+        """JSON for agents / CI: ``{"ok", "venue", "width_pt", "findings": [...]}``."""
+        kw.setdefault("indent", 1)
+        return json.dumps(self.to_dict(), ensure_ascii=False, **kw)
+
+    def raise_for_errors(self) -> "LintReport":
+        if not self.ok:
+            raise LintError(self)
+        return self
+
+    def __str__(self) -> str:
+        n = {s: len(self.by_severity(s)) for s in SEVERITIES}
+        head = (f"codefig lint ({self.venue or 'no venue'}"
+                f"{f', {self.width_pt:.0f} pt' if self.width_pt else ''}): "
+                f"{n['error']} error(s), {n['warn']} warning(s), {n['info']} info")
+        rows = [head] + ["  " + f.line() + (f"\n        fix: {f.fix}" if f.fix and f.severity != "info" else "")
+                         for f in self.findings]
+        if self.image:
+            rows.append(f"  wrote {self.image}"
+                        + (f"; findings outlined in {self.preview}" if self.preview else ""))
+        return "\n".join(rows)
+
+    __repr__ = __str__
+
+
+# ---- colour science (pure python) --------------------------------------------------
+_DEUT = ((0.367322, 0.860646, -0.227968), (0.280085, 0.672501, 0.047413), (-0.011820, 0.042940, 0.968881))
+_PROT = ((0.152286, 1.052583, -0.204868), (0.114503, 0.786281, 0.099216), (-0.003882, -0.048116, 1.051998))
+_NAMED = {"white": "#ffffff", "black": "#000000", "red": "#ff0000", "green": "#008000",
+          "blue": "#0000ff", "gray": "#808080", "grey": "#808080", "yellow": "#ffff00",
+          "orange": "#ffa500", "purple": "#800080", "none": None, "transparent": None}
+
+
+def parse_color(c: Any) -> Optional[Tuple[float, float, float]]:
+    """``#rgb`` / ``#rrggbb`` / ``rgb(r,g,b)`` / a few names → sRGB 0..1 (None if not a colour)."""
+    if c is None or not isinstance(c, str):
+        return None
+    c = c.strip().lower()
+    if c in _NAMED:
+        c = _NAMED[c]
+        if c is None:
+            return None
+    if c.startswith("url("):
+        return None
+    m = re.fullmatch(r"#([0-9a-f]{3}|[0-9a-f]{6})", c)
+    if m:
+        h = m.group(1)
+        if len(h) == 3:
+            h = "".join(ch * 2 for ch in h)
+        return tuple(int(h[i:i + 2], 16) / 255.0 for i in (0, 2, 4))  # type: ignore[return-value]
+    m = re.fullmatch(r"rgb\(\s*(\d+)\s*,\s*(\d+)\s*,\s*(\d+)\s*\)", c)
+    if m:
+        return tuple(int(m.group(i)) / 255.0 for i in (1, 2, 3))  # type: ignore[return-value]
+    return None
+
+
+def _lin(v: float) -> float:
+    return v / 12.92 if v <= 0.04045 else ((v + 0.055) / 1.055) ** 2.4
+
+
+def _lab_from_lin(r: float, g: float, b: float) -> Tuple[float, float, float]:
+    x = (0.4124 * r + 0.3576 * g + 0.1805 * b) / 0.95047
+    y = 0.2126 * r + 0.7152 * g + 0.0722 * b
+    z = (0.0193 * r + 0.1192 * g + 0.9505 * b) / 1.08883
+
+    def f(t: float) -> float:
+        return t ** (1 / 3) if t > 216 / 24389 else (24389 / 27 * t + 16) / 116
+
+    fx, fy, fz = f(x), f(y), f(z)
+    return 116 * fy - 16, 500 * (fx - fy), 200 * (fy - fz)
+
+
+def lab(rgb: Tuple[float, float, float]) -> Tuple[float, float, float]:
+    """sRGB (0..1) → CIELAB (D65)."""
+    return _lab_from_lin(*(_lin(v) for v in rgb))
+
+
+def cvd_lab(rgb: Tuple[float, float, float], kind: str = "deutan") -> Tuple[float, float, float]:
+    """CIELAB of ``rgb`` as seen with deuteranopia / protanopia (Machado 2009, severity 1)."""
+    M = _DEUT if kind == "deutan" else _PROT
+    lr = [_lin(v) for v in rgb]
+    sim = [min(1.0, max(0.0, sum(M[i][j] * lr[j] for j in range(3)))) for i in range(3)]
+    return _lab_from_lin(*sim)
+
+
+def delta_e(a: Sequence[float], b: Sequence[float]) -> float:
+    return math.sqrt(sum((x - y) ** 2 for x, y in zip(a, b)))
+
+
+def _hex(rgb: Tuple[float, float, float]) -> str:
+    return "#%02X%02X%02X" % tuple(round(v * 255) for v in rgb)
+
+
+# ---- SVG scan ----------------------------------------------------------------------
+_MARK = "cf-node:"
+
+
+def _affine(tr: str) -> Tuple[float, float, float, float, float, float]:
+    """Parse an SVG transform list → affine (a, b, c, d, e, f)."""
+    m = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)
+
+    def mul(p, q):
+        a1, b1, c1, d1, e1, f1 = p
+        a2, b2, c2, d2, e2, f2 = q
+        return (a1 * a2 + c1 * b2, b1 * a2 + d1 * b2, a1 * c2 + c1 * d2, b1 * c2 + d1 * d2,
+                a1 * e2 + c1 * f2 + e1, b1 * e2 + d1 * f2 + f1)
+
+    for name, args in re.findall(r"(\w+)\s*\(([^)]*)\)", tr or ""):
+        v = [float(x) for x in re.split(r"[\s,]+", args.strip()) if x]
+        if name == "translate":
+            q = (1, 0, 0, 1, v[0], v[1] if len(v) > 1 else 0.0)
+        elif name == "scale":
+            q = (v[0], 0, 0, v[1] if len(v) > 1 else v[0], 0, 0)
+        elif name == "rotate":
+            a = math.radians(v[0])
+            ca, sa = math.cos(a), math.sin(a)
+            if len(v) == 3:
+                cx, cy = v[1], v[2]
+                q = (ca, sa, -sa, ca, cx - ca * cx + sa * cy, cy - sa * cx - ca * cy)
+            else:
+                q = (ca, sa, -sa, ca, 0, 0)
+        elif name == "matrix" and len(v) == 6:
+            q = tuple(v)  # type: ignore[assignment]
+        else:
+            continue
+        m = mul(m, q)  # type: ignore[arg-type]
+    return m
+
+
+def _scale_of(m) -> float:
+    return math.sqrt(abs(m[0] * m[3] - m[1] * m[2]))
+
+
+@dataclass
+class _Prim:
+    tag: str
+    owner: Any  # innermost codefig node (or None)
+    chain: Tuple[Any, ...]
+    scale: float
+    attrs: Dict[str, str]
+    text: str = ""
+    font_size: float = 0.0
+    family: str = ""
+    weight: str = ""
+    in_defs: bool = False
+    script: bool = False  # sub/superscript run (allowed down to theme.script_min)
+    m: Tuple[float, ...] = (1.0, 0.0, 0.0, 1.0, 0.0, 0.0)  # v0.12: full affine to root
+    text_id: int = -1  # v0.12: enclosing <text> element (runs of one line share it)
+    clip: str = ""  # v0.12: enclosing clip-path id (knockout holes)
+
+
+def _style_attrs(el: ET.Element) -> Dict[str, str]:
+    d = dict(el.attrib)
+    st = d.pop("style", "")
+    for part in st.split(";"):
+        if ":" in part:
+            k, v = part.split(":", 1)
+            d[k.strip()] = v.strip()
+    return d
+
+
+def _scan_svg(svg: str, id_map: Dict[str, Any]) -> List[_Prim]:
+    parser = ET.XMLParser(target=ET.TreeBuilder(insert_comments=True))
+    root = ET.fromstring(svg, parser=parser)
+    prims: List[_Prim] = []
+    stack: List[Any] = []
+    inherit_keys = ("data-cf-icon", "data-cf-glyph", "font-size", "font-family", "font-weight", "fill", "stroke", "stroke-width",
+                    "stroke-dasharray", "y", "text-anchor", "font-style", "opacity", "fill-opacity")
+    text_seq = [0]
+    pen_y = [0.0]
+
+    def _num(v: Any) -> float:
+        try:
+            return float(re.sub(r"[a-z%]+$", "", str(v or "0")) or 0)
+        except ValueError:
+            return 0.0
+
+    cur_text = [-1]
+    text_fs = [0.0]  # font size of the enclosing <text> (scripts nest fallback-font tspans)
+    cur_clip = [""]
+
+    def local(tag: Any) -> str:
+        return tag.split("}", 1)[-1] if isinstance(tag, str) else ""
+
+    def visit(el: ET.Element, m, inh: Dict[str, str], in_defs: bool) -> None:
+        if el.tag is ET.Comment:
+            txt = (el.text or "").strip()
+            if txt.startswith(_MARK + "push "):
+                stack.append(id_map.get(txt.split()[-1]))
+            elif txt.startswith(_MARK + "pop") and stack:
+                stack.pop()
+            return
+        tag = local(el.tag)
+        a = _style_attrs(el)
+        if "transform" in a:
+            m2 = _affine(a["transform"])
+            a1, b1, c1, d1, e1, f1 = m
+            a2, b2, c2, d2, e2, f2 = m2
+            m = (a1 * a2 + c1 * b2, b1 * a2 + d1 * b2, a1 * c2 + c1 * d2, b1 * c2 + d1 * d2,
+                 a1 * e2 + c1 * f2 + e1, b1 * e2 + d1 * f2 + f1)
+        merged = dict(inh)
+        for k in inherit_keys:
+            if k in a:
+                merged[k] = a[k]
+        if tag == "text":
+            text_seq[0] += 1
+            cur_text[0] = text_seq[0]
+            pen_y[0] = _num(a.get("y"))
+            try:
+                text_fs[0] = float(re.sub(r"[a-z]+$", "", merged.get("font-size", "0")) or 0)
+            except ValueError:
+                text_fs[0] = 0.0
+        if tag in ("text", "tspan"):
+            # v0.13.0: track the SVG pen (absolute y, relative dy) so script runs
+            # positioned with dy are measured where they are drawn
+            if tag == "tspan" and "y" in a:
+                pen_y[0] = _num(a.get("y"))
+            if "dy" in a:
+                pen_y[0] += _num(a.get("dy"))
+            merged["y"] = f"{pen_y[0]:.3f}"
+        prev_clip = cur_clip[0]
+        if "clip-path" in a:
+            mm = re.search(r"#([^)]+)", a["clip-path"])
+            if mm:
+                cur_clip[0] = mm.group(1)
+        defs = in_defs or tag in ("defs", "clipPath", "marker", "pattern", "mask")
+        if tag in ("text", "tspan"):
+            own = "".join(t for t in [el.text] if t) .strip()
+            if tag == "text" and not own:
+                own = ""
+            if own:
+                try:
+                    fs = float(re.sub(r"[a-z]+$", "", merged.get("font-size", "0")) or 0)
+                except ValueError:
+                    fs = 0.0
+                try:
+                    pfs = float(re.sub(r"[a-z]+$", "", inh.get("font-size", "0")) or 0)
+                except ValueError:
+                    pfs = 0.0
+                script = tag == "tspan" and 0 < fs and (fs < pfs - 1e-6 or fs < text_fs[0] - 1e-6)
+                prims.append(_Prim("text", stack[-1] if stack else None, tuple(stack), _scale_of(m),
+                                   {**a, **{k: merged[k] for k in merged if k not in ("x",)},
+                                    **({"x": a["x"]} if "x" in a else {})}, own, fs,
+                                   merged.get("font-family", ""), merged.get("font-weight", ""),
+                                   defs, script, m, cur_text[0], cur_clip[0]))
+        elif tag in ("rect", "line", "path", "polyline", "polygon", "circle", "ellipse", "image"):
+            prims.append(_Prim(tag, stack[-1] if stack else None, tuple(stack), _scale_of(m),
+                               {**{k: merged[k] for k in merged}, **a}, in_defs=defs, m=m,
+                               clip=cur_clip[0]))
+        for ch in list(el):
+            visit(ch, m, merged, defs)
+            # tspan tails belong to the parent text run
+            if local(ch.tag) == "tspan" and ch.tail and ch.tail.strip() and tag == "text":
+                try:
+                    fs = float(re.sub(r"[a-z]+$", "", merged.get("font-size", "0")) or 0)
+                except ValueError:
+                    fs = 0.0
+                prims.append(_Prim("text", stack[-1] if stack else None, tuple(stack), _scale_of(m),
+                                   {**merged, "y": f"{pen_y[0]:.3f}"}, ch.tail.strip(), fs, merged.get("font-family", ""),
+                                   merged.get("font-weight", ""), defs, False, m, cur_text[0],
+                                   cur_clip[0]))
+        cur_clip[0] = prev_clip
+
+    visit(root, (1.0, 0.0, 0.0, 1.0, 0.0, 0.0), {}, False)
+    return prims
+
+
+def _instrumented_svg(fig: Any) -> Tuple[str, Dict[str, Any]]:
+    """Render with ``<!--cf-node:push N-->`` markers around every node / edge draw."""
+    from .constraints import walk
+    from .edges import Diagram
+
+    id_map: Dict[str, Any] = {}
+    patched: List[Any] = []
+
+    def wrap(obj: Any) -> None:
+        if "draw" in obj.__dict__ or not hasattr(obj, "draw"):
+            return
+        key = str(len(id_map))
+        id_map[key] = obj
+        orig = obj.draw
+
+        def draw(buf, *a, **kw):
+            buf.append(f"<!--{_MARK}push {key}-->")
+            try:
+                return orig(buf, *a, **kw)
+            finally:
+                buf.append(f"<!--{_MARK}pop-->")
+
+        obj.__dict__["draw"] = draw
+        patched.append(obj)
+
+    fig.layout()
+    for p in fig._panels.values():
+        trees = [p.content] if p.content is not None else []
+        trees += list(p._overlays)
+        for t in trees:
+            for n in walk(t):
+                wrap(n)
+                if isinstance(n, Diagram):
+                    for e in n.edges:
+                        wrap(e)
+    from . import notices
+
+    notices.reset()
+    try:
+        svg = fig.to_svg()
+    finally:
+        for o in patched:
+            o.__dict__.pop("draw", None)
+    return svg, id_map
+
+
+# ---- helpers -----------------------------------------------------------------------
+def _name(n: Any) -> str:
+    from .overlaps import edge_name
+    from .constraints import node_name
+
+    if n is None:
+        return "figure"
+    if hasattr(n, "src") and hasattr(n, "dst"):
+        return edge_name(n)
+    return node_name(n)
+
+
+def _ignored(chain: Iterable[Any], rule: str) -> bool:
+    for n in chain:
+        ig = getattr(n, "lint_ignore", None) or ()
+        if isinstance(ig, str):
+            ig = (ig,)
+        # exact id, a prefix ("CF-TXT" silences every text rule) or "all" / "*"
+        if any(x in ("all", "*") or rule == x or rule.startswith(str(x).rstrip("-") + "-") for x in ig):
+            return True
+    return False
+
+
+def _ancestors(n: Any) -> List[Any]:
+    out = []
+    while n is not None:
+        out.append(n)
+        n = getattr(n, "parent", None)
+    return out
+
+
+def _bins(vals: Iterable[float], step: float) -> List[float]:
+    return sorted({round(v / step) * step for v in vals})
+
+
+# ---- the linter --------------------------------------------------------------------
+class _Ctx:
+    def __init__(self, fig, venue, width, scale, ignore, thresholds, pdf, alt):
+        from .venues import get_venue
+
+        self.fig = fig
+        self.venue = get_venue(venue) if venue is not None else fig.venue
+        vw = width if width is not None else (fig.venue_width if venue is None else None)
+        self.width_arg = vw or "text"
+        self.target = self.venue.width_pt(self.width_arg) if self.venue else None
+        self.scale = float(scale)
+        self.ignore = set(ignore or ()) | set(lint_config.disable)
+        self.th = {k: dict(v) for k, v in lint_config.thresholds.items()}
+        for k, v in (thresholds or {}).items():
+            self.th.setdefault(k, {}).update(v)
+        self.pdf = pdf
+        self.alt = alt
+        self.findings: List[Finding] = []
+
+    def t(self, rule: str, key: str, default: float) -> float:
+        return float(self.th.get(rule, {}).get(key, default))
+
+    def add(self, rule: str, sev: str, msg: str, elements: Sequence[str] = (),
+            measured: Optional[float] = None, threshold: Optional[float] = None,
+            boxes: Sequence[Sequence[float]] = ()) -> None:
+        if rule in self.ignore:
+            return
+        self.findings.append(Finding(rule, sev, msg, list(elements),
+                                     None if measured is None else round(float(measured), 3),
+                                     None if threshold is None else round(float(threshold), 3),
+                                     RULES[rule].fix,
+                                     [[round(float(v), 2) for v in b] for b in boxes]))
+
+
+def lint_figure(fig: Any, venue: Optional[str] = None, width: Any = None, scale: float = 1.0,
+                ignore: Optional[Sequence[str]] = None,
+                thresholds: Optional[Dict[str, Dict[str, float]]] = None,
+                pdf: Any = None, alt: Optional[str] = None) -> LintReport:
+    """Implementation of :meth:`codefig.Figure.lint` (see module docstring)."""
+    import warnings
+
+    from .overlaps import OverlapWarning
+
+    for r in list(ignore or ()):
+        if r not in RULES:
+            raise ValueError(f"unknown lint rule {r!r}")
+    cx = _Ctx(fig, venue, width, scale, ignore, thresholds, pdf, alt)
+    with warnings.catch_warnings():
+        warnings.simplefilter("ignore", OverlapWarning)
+        with fig._ctx():
+            svg, id_map = _instrumented_svg(fig)
+            overlaps = []
+            for letter in fig._order:
+                overlaps.extend(fig._panels[letter].check_overlaps())
+            prims = _scan_svg(svg, id_map)
+            cx.prims = prims
+            # authoring unit → printed pt
+            if cx.target is not None:
+                cx.factor = cx.target / fig.width * cx.scale
+            else:
+                cx.factor = cx.scale
+            _check_text(cx, prims)
+            _check_text_geometry(cx, prims, svg)
+            _check_strokes(cx, prims)
+            _check_colour(cx, prims)
+            _check_overlaps(cx, overlaps)
+            for panel in fig._panels.values():
+                for legend in panel.__dict__.get('_corner_legends', []):
+                    if getattr(legend, '_corner_conflict', 0) > 0:
+                        clear = ', '.join(legend._clear_corners) or 'none; use external placement'
+                        cx.add('CF-LAY-009', 'warn', f'Legend obscures content; clear corners: {clear}')
+            _check_scene(cx)
+            _check_export(cx, prims)
+    order = {s: i for i, s in enumerate(SEVERITIES)}
+    cx.findings.sort(key=lambda f: (order[f.severity], f.rule_id))
+    return LintReport(cx.findings, cx.venue.name if cx.venue else None,
+                      cx.target, round(cx.factor, 4),
+                      [r for r in RULES if r not in cx.ignore and RULES[r].implemented])
+
+
+# ---- text --------------------------------------------------------------------------
+def _short(t: str, n: int = 22) -> str:
+    t = " ".join((t or "").split())
+    return t if len(t) <= n else t[: n - 1] + "…"
+
+
+def _check_text_geometry(cx: _Ctx, prims: List[_Prim], svg: str) -> None:
+    """CF-TXT-010 (drawn text covered / struck / overlapping) and CF-TXT-011 (dropped)."""
+    from .lint_geom import check_text_geometry
+
+    if "CF-TXT-010" not in cx.ignore:
+        res = check_text_geometry(prims, svg, _ignored)
+
+        def who(p: Any) -> str:
+            return _name(p.owner) if getattr(p, "owner", None) is not None else "figure"
+
+        groups = (("covered", "error", "painted over by"), ("struck", "error", "struck through by"),
+                  ("text", "error", "overlaps text"), ("grazed", "warn", "touched by a line of"),
+                  ("gapped", "warn", "crossed (gap cut behind the text) by"))
+        for key, sev, verb in groups:
+            items = res[key]
+            if not items:
+                continue
+            descs, els, boxes = [], [], []
+            for r, other, box in items:
+                if key == "text":
+                    d = f"'{_short(r.text)}' {verb} '{_short(other.text)}'"
+                    els.append(who(r.p))
+                else:
+                    d = f"'{_short(r.text)}' ({who(r.p)}) {verb} {who(other)}"
+                    els.append(who(r.p))
+                descs.append(d)
+                boxes.append(r.core)
+            more = f" (+{len(descs) - 3} more)" if len(descs) > 3 else ""
+            cx.add("CF-TXT-010", sev, f"{len(descs)} drawn label(s) {verb.split(' by')[0]}: "
+                   + "; ".join(descs[:3]) + more, list(dict.fromkeys(els)), len(descs), 0, boxes)
+    if "CF-TXT-011" not in cx.ignore:
+        from .notices import drained
+
+        notes = [d for d in drained() if not _ignored(_ancestors(d[0]), "CF-TXT-011")]
+        for lvl, head in (("warn", "shortened or not drawn"), ("info", "moved to a fallback spot")):
+            items = [d for d in notes if d[3] == lvl]
+            if not items:
+                continue
+            descs = [f"{_name(o)}: '{_short(t)}' {why}" for o, t, why, _l in items]
+            more = f" (+{len(descs) - 3} more)" if len(descs) > 3 else ""
+            cx.add("CF-TXT-011", lvl, f"{len(descs)} label(s) {head}: " + "; ".join(descs[:3]) + more,
+                   list(dict.fromkeys(_name(o) for o, _t, _w, _l in items)), len(descs), 0)
+
+
+def _is_panel_tag(p: _Prim) -> bool:
+    return p.owner is None and re.match(r"^\([a-z0-9]+\)", p.text or "") is not None
+
+
+def _check_text(cx: _Ctx, prims: List[_Prim]) -> None:
+    texts = [p for p in prims if p.tag == "text" and not p.in_defs and p.font_size > 0]
+    if not texts:
+        return
+    sizes = []
+    worst: Dict[str, Tuple[float, List[str]]] = {}
+    warn_t, err_t = cx.t("CF-TXT-001", "warn", 6.0), cx.t("CF-TXT-001", "error", 5.0)
+    if cx.venue is not None:
+        warn_t = max(warn_t, cx.venue.min_font_pt) if "warn" not in cx.th.get("CF-TXT-001", {}) else warn_t
+    small_err, small_warn = [], []
+    script_t = min(warn_t, cx.t("CF-TXT-001", "script", 5.5))
+    for p in texts:
+        eff = p.font_size * p.scale * cx.factor
+        if not p.script:
+            sizes.append((eff, p))
+        if _ignored(p.chain, "CF-TXT-001"):
+            continue
+        if eff < err_t - 0.03:
+            small_err.append((eff, p))
+        elif eff < (script_t if p.script else warn_t) - 0.03:
+            small_warn.append((eff, p))
+    from .lint_geom import text_runs
+
+    run_box = {id(r.p): r.core for r in text_runs(texts)}
+    for lst, sev, thr in ((small_err, "error", err_t), (small_warn, "warn", warn_t)):
+        if lst:
+            mn = min(e for e, _ in lst)
+            els = sorted({f"text:{p.text[:20]!r}" for _, p in lst})
+            cx.add("CF-TXT-001", sev, f"{len(lst)} text run(s) below {thr:g} pt at final size "
+                   f"(smallest {mn:.2f} pt)", els, mn, thr,
+                   [run_box[id(p)] for _, p in lst if id(p) in run_box])
+    # distinct sizes (panel tags excluded)
+    body = [(e, p) for e, p in sizes if not _is_panel_tag(p) and not _ignored(p.chain, "CF-TXT-002")]
+    if body:
+        bins = _bins([e for e, _ in body], 0.5)
+        vals = sorted(e for e, _ in body)
+        med = vals[len(vals) // 2]
+        ratio = max(vals) / med if med else 1.0
+        max_n = cx.t("CF-TXT-002", "max_sizes", 3)
+        max_r = cx.t("CF-TXT-002", "max_ratio", 1.6)
+        if len(bins) > max_n:
+            cx.add("CF-TXT-002", "warn", f"{len(bins)} distinct font sizes "
+                   f"({', '.join(f'{b:g}' for b in bins)} pt)", [], len(bins), max_n)
+        elif ratio > max_r:
+            cx.add("CF-TXT-002", "warn", f"largest/median font size = {ratio:.2f}", [], ratio, max_r)
+    # vs body text
+    if cx.venue is not None:
+        lim = cx.venue.body_pt + cx.t("CF-TXT-003", "margin", 1.0)
+        big = [(e, p) for e, p in body if e > lim + 1e-6]
+        if big:
+            cx.add("CF-TXT-003", "info", f"{len(big)} text run(s) larger than body text + 1 pt "
+                   f"(max {max(e for e, _ in big):.1f} pt)",
+                   sorted({f"text:{p.text[:20]!r}" for _, p in big}), max(e for e, _ in big), lim)
+    # families
+    fams = set()
+    for p in texts:
+        fam = (p.family.split(",")[0].strip().strip("'\"") if p.family else "")
+        if not fam or "mono" in fam.lower() or "courier" in fam.lower() or "consol" in fam.lower():
+            continue
+        if _ignored(p.chain, "CF-TXT-004"):
+            continue
+        if p.text and _all_fallback_glyphs(p.text):
+            continue  # per-glyph fallback (⋯, ⊕, ✓) for glyphs the theme face lacks
+        fams.add(fam)
+    if len(fams) > 1:
+        cx.add("CF-TXT-004", "warn", f"{len(fams)} text families: {', '.join(sorted(fams))}",
+               sorted(fams), len(fams), 1)
+    # emphasis: colours and bold
+    cols = set()
+    for p in texts:
+        c = parse_color(p.attrs.get("fill", "#000000"))
+        if c is None or _ignored(p.chain, "CF-TXT-008") or type(p.owner).__name__ == "CodeBlock":
+            continue
+        L = lab(c)[0]
+        if L > 90:  # white text on dark fills is a contrast device, not emphasis
+            continue
+        if L < 30 and max(c) - min(c) < 0.08:  # near-black / dark grey = one "black"
+            continue
+        cols.add(_hex(c))
+    if len(cols) + 1 > cx.t("CF-TXT-008", "max_colors", 2):
+        cx.add("CF-TXT-008", "info", f"{len(cols) + 1} text colours (black + {', '.join(sorted(cols))})",
+               sorted(cols), len(cols) + 1, 2)
+    bold = [p for p in texts if str(p.weight) in ("bold", "700", "800", "900")
+            and not _is_panel_tag(p) and p.owner is not None and not _ignored(p.chain, "CF-TXT-008")
+            and "data-cf-glyph" not in p.attrs  # step badges ①②③
+            and type(p.owner).__name__ not in ("Group", "Lanes", "Lane", "Legend", "Text", "Timeline",
+                                               "Container", "Row", "Col", "Stack", "Grid", "Table",
+                                               "Matrix", "Brace", "TokenStrip", "CodeBlock")]
+    if bold:
+        cx.add("CF-TXT-008", "info", f"{len(bold)} bold label(s) outside titles",
+               sorted({f"text:{p.text[:20]!r}" for p in bold})[:6], len(bold), 0)
+
+
+# ---- strokes -----------------------------------------------------------------------
+def _all_fallback_glyphs(text: str) -> bool:
+    from .textutil import _lacks_glyph
+
+    chars = [c for c in text if not c.isspace()]
+    return bool(chars) and all(_lacks_glyph(c) for c in chars)
+
+
+def _check_strokes(cx: _Ctx, prims: List[_Prim]) -> None:
+    widths: List[float] = []
+    owners_by_w: Dict[float, set] = {}
+    dashes = set()
+    thin_err, thin_warn = [], []
+    warn_t, err_t = cx.t("CF-STR-001", "warn", 0.5), cx.t("CF-STR-001", "error", 0.25)
+    for p in prims:
+        if p.tag in ("text", "image") or p.in_defs:
+            continue
+        stroke = p.attrs.get("stroke")
+        if stroke in (None, "none") or parse_color(stroke) is None and not str(stroke).startswith("url"):
+            continue
+        if float(p.attrs.get("stroke-opacity", "1") or 1) == 0:
+            continue
+        try:
+            sw = float(re.sub(r"[a-z]+$", "", p.attrs.get("stroke-width", "1")) or 1)
+        except ValueError:
+            continue
+        if sw <= 0:
+            continue
+        eff = sw * p.scale * cx.factor
+        if _is_hatch(p):
+            continue
+        try:
+            op = float(p.attrs.get("opacity", p.attrs.get("stroke-opacity", "1")) or 1)
+        except ValueError:
+            op = 1.0
+        # pictogram strokes (Icon glyphs, icon badges) scale with the icon like text does,
+        # so they are not part of the figure's line-weight vocabulary
+        icon_glyph = "data-cf-icon" in p.attrs
+        if op >= 0.6 and not icon_glyph:  # translucent underlays (bundle buses) are not weights
+            widths.append(eff)
+            owners_by_w.setdefault(round(eff, 1), set()).add(_name(p.owner))
+        da = p.attrs.get("stroke-dasharray")
+        if da and da != "none":
+            dashes.add(tuple(round(float(x) * p.scale * cx.factor * 2) / 2
+                             for x in re.split(r"[\s,]+", da.strip()) if x))
+        if _ignored(p.chain, "CF-STR-001"):
+            continue
+        if eff < err_t - 1e-6:
+            thin_err.append((eff, p))
+        elif eff < warn_t - 1e-6:
+            thin_warn.append((eff, p))
+    for lst, sev, thr in ((thin_err, "error", err_t), (thin_warn, "warn", warn_t)):
+        if lst:
+            mn = min(e for e, _ in lst)
+            els = sorted({_name(p.owner) for _, p in lst})
+            cx.add("CF-STR-001", sev, f"{len(lst)} stroke(s) thinner than {thr:g} pt "
+                   f"(thinnest {mn:.2f} pt)", els[:8], mn, thr)
+    if widths:
+        bins = _bins(widths, 0.1)
+        # merge bins within 0.15 pt (rounding noise)
+        merged: List[float] = []
+        for b in bins:
+            if not merged or b - merged[-1] > 0.15:
+                merged.append(b)
+        if len(merged) > cx.t("CF-STR-002", "max_widths", 3):
+            rare = sorted(owners_by_w, key=lambda w: len(owners_by_w[w]))[:2]
+            els = [f"{w:g} pt: " + ", ".join(sorted(owners_by_w[w])[:3]) for w in rare]
+            cx.add("CF-STR-002", "warn", f"{len(merged)} stroke widths "
+                   f"({', '.join(f'{b:.1f}' for b in merged)} pt)", els, len(merged), 3)
+    if len(dashes) > cx.t("CF-STR-002", "max_dashes", 2):
+        cx.add("CF-STR-002", "warn", f"{len(dashes)} dash patterns", [str(d) for d in sorted(dashes)][:5],
+               len(dashes), 2)
+
+
+def _is_hatch(p: _Prim) -> bool:
+    # hatch / pattern strokes live in a clip group painted by Hatch.paint
+    return p.tag == "path" and "clip-path" in p.attrs and p.attrs.get("fill") in (None, "none")
+
+
+# ---- colour ------------------------------------------------------------------------
+def _category_fills(cx: _Ctx) -> Dict[str, Tuple[Tuple[float, float, float], List[Any]]]:
+    """Distinct fills of box-like leaf nodes (categorical colour), hex → (rgb, nodes)."""
+    from .constraints import walk
+    from .primitives import Box
+
+    out: Dict[str, Tuple[Tuple[float, float, float], List[Any]]] = {}
+    for p in cx.fig._panels.values():
+        if p.content is None:
+            continue
+        for n in walk(p.content):
+            if not isinstance(n, Box):
+                continue
+            rgb = parse_color(n.fill if isinstance(n.fill, str) else None)
+            if rgb is None:
+                continue
+            L, a, b = lab(rgb)
+            if L > 97.5 and math.hypot(a, b) < 4:  # white-ish = no colour
+                continue
+            out.setdefault(_hex(rgb), (rgb, []))[1].append(n)
+    return out
+
+
+def _hue_family(rgb) -> Optional[int]:
+    L, a, b = lab(rgb)
+    if math.hypot(a, b) < 8:
+        return None  # neutral grey
+    return int(((math.degrees(math.atan2(b, a)) + 360 + 22.5) % 360) // 45)
+
+
+def _check_colour(cx: _Ctx, prims: List[_Prim]) -> None:
+    fills = _category_fills(cx)
+    items = [(h, rgb, nodes) for h, (rgb, nodes) in fills.items()
+             if not all(_ignored(_ancestors(n), "CF-COL-002") for n in nodes)]
+    fams = {f for _, rgb, _ in items for f in [_hue_family(rgb)] if f is not None}
+    if len(fams) > cx.t("CF-COL-001", "warn", 5):
+        cx.add("CF-COL-001", "warn", f"{len(fams)} categorical hue families", [h for h, _, _ in items][:8],
+               len(fams), 5)
+    elif len(fams) >= cx.t("CF-COL-001", "info", 5):
+        cx.add("CF-COL-001", "info", f"{len(fams)} categorical hue families", [h for h, _, _ in items][:8],
+               len(fams), 5)
+    # pairwise CVD / grey / red-green
+    warn_t, err_t = cx.t("CF-COL-002", "warn", 10.0), cx.t("CF-COL-002", "error", 5.0)
+    gl_t = cx.t("CF-COL-003", "warn", 8.0)
+    for i in range(len(items)):
+        for j in range(i + 1, len(items)):
+            h1, c1, n1 = items[i]
+            h2, c2, n2 = items[j]
+            normal = delta_e(lab(c1), lab(c2))
+            if normal < 3:  # same colour by eye
+                continue
+            d = min(delta_e(cvd_lab(c1, "deutan"), cvd_lab(c2, "deutan")),
+                    delta_e(cvd_lab(c1, "protan"), cvd_lab(c2, "protan")))
+            pair = [h1, h2]
+            if d < err_t:
+                cx.add("CF-COL-002", "error", f"fills {h1} / {h2} are near-identical with CVD "
+                       f"(ΔE {d:.1f})", pair, d, err_t)
+            elif d < warn_t:
+                cx.add("CF-COL-002", "warn", f"fills {h1} / {h2} hard to tell apart with CVD "
+                       f"(ΔE {d:.1f})", pair, d, warn_t)
+            if normal > 30 and d < warn_t:
+                cx.add("CF-COL-006", "warn", f"{h1} / {h2} differ mainly on the red–green axis", pair,
+                       d, warn_t)
+            dl = abs(lab(c1)[0] - lab(c2)[0])
+            if dl < gl_t and not _has_cue(n1, n2) and not all(
+                    _ignored(_ancestors(n), "CF-COL-003") for n in n1 + n2):
+                cx.add("CF-COL-003", "warn", f"fills {h1} / {h2} have the same grey level "
+                       f"(ΔL* {dl:.1f}) and no hatch/border cue", pair, dl, gl_t)
+    # key for meaning
+    cats = cx.fig.categories()
+    has_legend = _has_legend(cx)
+    if len(cats) >= 2 and not has_legend:
+        cx.add("CF-COL-004", "warn", f"{len(cats)} categories ({', '.join(cats[:5])}) but no Legend",
+               cats[:6], len(cats), 2)
+    elif not cats and len(items) >= 3 and not has_legend:
+        cx.add("CF-COL-004", "info", f"{len(items)} fill colours without category= or a legend — "
+               "if colour carries meaning add a key; if decorative, consider neutral grey",
+               [h for h, _, _ in items][:6], len(items), 3)
+    # text contrast on its background
+    _check_contrast(cx)
+
+
+def _has_cue(n1: List[Any], n2: List[Any]) -> bool:
+    def cue(ns):
+        n = ns[0]
+        return (getattr(n, "pattern", None) is not None, str(getattr(n, "border", None) or "solid"))
+
+    return cue(n1) != cue(n2)
+
+
+def _has_legend(cx: _Ctx) -> bool:
+    from .constraints import walk
+    from .legend import Legend
+
+    for p in cx.fig._panels.values():
+        trees = ([p.content] if p.content is not None else []) + list(p._overlays)
+        for t in trees:
+            if any(isinstance(n, Legend) for n in walk(t)):
+                return True
+    return False
+
+
+def _check_contrast(cx: _Ctx) -> None:
+    from .constraints import walk
+    from .primitives import Box
+
+    bad = []
+    lim = cx.t("CF-COL-005", "min_dL", 50.0)
+    for p in cx.fig._panels.values():
+        if p.content is None:
+            continue
+        for n in walk(p.content):
+            if not isinstance(n, Box) or not (n.text or getattr(n, "subtitle", None)):
+                continue
+            bg = parse_color(n.fill if isinstance(n.fill, str) else None)
+            fg = parse_color(n.text_color if isinstance(n.text_color, str) else None)
+            if bg is None or fg is None or _ignored(_ancestors(n), "CF-COL-005"):
+                continue
+            dl = abs(lab(bg)[0] - lab(fg)[0])
+            if dl < lim:
+                bad.append((dl, n))
+    if bad:
+        sev = "warn" if (cx.venue is not None and cx.venue.no_gray_text_bg) else "info"
+        mn = min(d for d, _ in bad)
+        cx.add("CF-COL-005", sev, f"{len(bad)} label(s) with low text/background contrast "
+               f"(ΔL* {mn:.0f})", [_name(n) for _, n in bad][:6], mn, lim)
+
+
+# ---- overlaps ----------------------------------------------------------------------
+def _check_overlaps(cx: _Ctx, overlaps: List[Any]) -> None:
+    from .primitives import Text
+
+    txt, box, route = [], [], []
+    for o in overlaps:
+        a, b = o.a, o.b
+        chain = _ancestors(a) + _ancestors(b) if not hasattr(a, "src") else [a] + _ancestors(b)
+        if o.kind == "node":
+            is_text = isinstance(a, Text) or isinstance(b, Text)
+            rule = "CF-TXT-005" if is_text else "CF-LAY-005"
+            if _ignored(chain, rule):
+                continue
+            (txt if is_text else box).append(o)
+        elif o.kind == "edge-node":
+            rule = "CF-TXT-005" if isinstance(b, Text) else "CF-ARR-002"
+            if _ignored(chain, rule):
+                continue
+            (txt if rule == "CF-TXT-005" else route).append(o)
+        else:
+            if _ignored(chain, "CF-TXT-005"):
+                continue
+            txt.append(o)
+    for lst, rule, sev in ((txt, "CF-TXT-005", "error"), (box, "CF-LAY-005", "error"),
+                           (route, "CF-ARR-002", "warn")):
+        if lst:
+            worst = max((min(o.dx, o.dy) for o in lst), default=0.0)
+            cx.add(rule, sev, f"{len(lst)} overlap(s): " + "; ".join(str(o) for o in lst[:3])
+                   + (" …" if len(lst) > 3 else ""),
+                   [f"{_name(o.a)} | {_name(o.b)}" for o in lst[:6]],
+                   worst * cx.factor, 0.0,
+                   _node_boxes(cx, [n for o in lst for n in (o.a, o.b)]))
+
+
+# ---- scene graph -------------------------------------------------------------------
+def _check_scene(cx: _Ctx) -> None:
+    from .constraints import walk
+    from .edges import Diagram, Edge
+    from .compose import Stacked
+    from .node import Col, Container, Grid, Row, Stack
+    from .primitives import Box, CircleHighlight, Group
+
+    fig = cx.fig
+    invisible_ends: List[Any] = []
+    sparse_panels: List[Tuple[float, str]] = []
+    region_cover: List[Tuple[Any, list, str]] = []
+    long_lab, many_lines, sentence = [], [], []
+    pad_err, pad_warn = [], []
+    radii: Dict[str, set] = {}
+    dashed_no_legend = []
+    heads = set()
+    head_sizes = set()
+    align_frac = []
+    gap_bad = []
+    crossings = 0
+    has_legend = _has_legend(cx)
+    for letter in fig._order:
+        p = fig._panels[letter]
+        if p.content is None:
+            continue
+        scale = getattr(p, "_scale", 1.0) or 1.0
+        boxes = []
+        # children placed by relational constraints have intentional, solved gaps
+        pinned = set()
+        for n in walk(p.content):
+            cs = getattr(n, "constraints", None)
+            if isinstance(cs, list):
+                try:
+                    for c in cs:
+                        pinned.update(id(x) for x in c.nodes())
+                except Exception:  # pragma: no cover
+                    pass
+        for n in walk(p.content):
+            if isinstance(n, Box):
+                boxes.append(n)
+                _label_checks(cx, n, long_lab, many_lines, sentence)
+                _pad_check(cx, n, pad_err, pad_warn, scale)
+                if n.rounded if hasattr(n, "rounded") else False:
+                    r = n.radius if getattr(n, "radius", None) is not None else n.theme.corner_radius
+                    if type(n).__name__ == "Box" and not _ignored(_ancestors(n), "CF-LAY-003"):
+                        radii.setdefault("Box", set()).add(round(r * scale * cx.factor, 1))
+            if (isinstance(n, Container) and len(n.children()) >= 3
+                    # v0.12.0 (B7): a constraint on any descendant (not only a direct
+                    # child) can stretch the gaps, so those containers are skipped too
+                    and not any(id(d) in pinned for ch in n.children() for d in walk(ch))
+                    and not _ignored(_ancestors(n), "CF-LAY-002")):
+                g = _gap_cv(n)
+                if g is not None and g[0] > cx.t("CF-LAY-002", "max_cv", 0.25):
+                    gap_bad.append((g[0], n, g[1]))
+            if isinstance(n, Diagram) and getattr(n, "regions", None):
+                from .regions import diagram_boxes, region_others
+
+                n._layout_regions()
+                pre = diagram_boxes(n)
+                for r in n.regions:
+                    if _ignored([n], "CF-REG-001"):
+                        break
+                    bad = [o for o, rect in region_others(n, r, pre)
+                           if r.covers(rect)]
+                    if bad:
+                        region_cover.append((r, bad, letter))
+            if isinstance(n, Diagram):
+                segs = []
+                for e in n.edges:
+                    if not isinstance(e, Edge):
+                        continue
+                    try:
+                        st = e.resolved()
+                    except Exception:  # pragma: no cover
+                        continue
+                    for hd in (st.end_head, st.start_head):
+                        if hd is not None and getattr(hd, "visible", True) and hd.shape != "none":
+                            heads.add(hd.shape)
+                            head_sizes.add((round(hd.length * scale * cx.factor, 1),
+                                            round(hd.width * scale * cx.factor, 1)))
+                    if (st.dash or st.style not in (None, "solid")) and not e.legend and not has_legend \
+                            and not _ignored([e], "CF-STR-003"):
+                        dashed_no_legend.append(e)
+                    for pt_ in (e.src, e.dst):
+                        nd_ = getattr(pt_, "node", None)
+                        if (isinstance(nd_, (Row, Grid)) or type(nd_) in (Col, Stack)) \
+                                and not _ignored([e], "CF-ARR-003"):
+                            invisible_ends.append((e, nd_, _lands_on_child(pt_, nd_)))
+                    pts = e._cached_pts or []
+                    _check_route_geometry(cx, n, e, pts, scale * cx.factor)
+                    if getattr(e, "_cf_guide_edge", False):
+                        _check_guide_captions(cx, p, n, e, pts)
+                    segs.append([(pts[i], pts[i + 1]) for i in range(len(pts) - 1)])
+                crossings += _count_crossings(segs)
+        frac = _alignment(boxes)
+        if frac is not None:
+            align_frac.append((frac, letter, len(boxes)))
+        if len(fig._order) > 1 and not _ignored([p], "CF-LAY-007"):
+            try:
+                ix, iy, iw, ih = p._inner()
+                bw, bh = p._bbox[2], p._bbox[3]
+                s_ = getattr(p, "_scale", 1.0) or 1.0
+                if iw > 1 and ih > 1 and bw > 1 and bh > 1:
+                    sparse_panels.append((min(1.0, bw * s_ * bh * s_ / (iw * ih)), letter))
+            except Exception:  # pragma: no cover
+                pass
+    # labels
+    if long_lab:
+        cx.add("CF-TXT-006", "warn", f"{len(long_lab)} label line(s) longer than 4 words / 24 chars",
+               [f"{s!r}" for s in long_lab[:6]], None, None)
+    if many_lines:
+        cx.add("CF-TXT-006", "warn", f"{len(many_lines)} label(s) with more than 2 lines",
+               [f"{s!r}" for s in many_lines[:6]], None, 2)
+    if sentence:
+        cx.add("CF-TXT-006", "info", f"{len(sentence)} sentence-like label(s) (> 8 words) — "
+               "move to the caption", [f"{s!r}" for s in sentence[:4]], None, 8)
+    if pad_err:
+        cx.add("CF-TXT-007", "error", f"{len(pad_err)} label(s) overflow their box",
+               [_name(n) for _, n in pad_err][:6], min(v for v, _ in pad_err), 0.0)
+    if pad_warn:
+        cx.add("CF-TXT-007", "warn", f"{len(pad_warn)} label(s) with tight padding "
+               f"(< 0.4 em horizontal / 0.2 em vertical)", [_name(n) for _, n in pad_warn][:6],
+               min(v for v, _ in pad_warn), 0.2)
+    for role, rs in radii.items():
+        if len(rs) > 1:
+            cx.add("CF-LAY-003", "warn", f"{len(rs)} corner radii among {role}es "
+                   f"({', '.join(f'{r:g}' for r in sorted(rs))} pt)", [role], len(rs), 1)
+    if len(heads) > cx.t("CF-ARR-001", "max_styles", 2):
+        cx.add("CF-ARR-001", "warn", f"{len(heads)} arrowhead styles ({', '.join(sorted(heads))})",
+               sorted(heads), len(heads), 2)
+    if len(head_sizes) > cx.t("CF-ARR-001", "max_sizes", 1):
+        cx.add("CF-ARR-001", "warn", f"{len(head_sizes)} arrowhead sizes "
+               f"({', '.join(f'{a:g}×{b:g}' for a, b in sorted(head_sizes))} pt)", [], len(head_sizes), 1)
+    if dashed_no_legend:
+        cx.add("CF-STR-003", "info", f"{len(dashed_no_legend)} dashed edge(s) without a legend entry",
+               [_name(e) for e in dashed_no_legend][:6], len(dashed_no_legend), 0)
+    if crossings:
+        cx.add("CF-ARR-002", "info", f"{crossings} edge–edge crossing(s)", [], crossings, 0)
+    for e, nd_, child in invisible_ends:
+        if child is None:
+            cx.add("CF-ARR-003", "warn", f"{_name(e)} ends on an invisible {type(nd_).__name__} — "
+                   "the arrow lands on the container's bounding box, not on a drawn element",
+                   [_name(e)], None, None)
+        else:  # it touches a child: fine if that child is the intended end, say so explicitly
+            cx.add("CF-ARR-003", "info", f"{_name(e)} uses a {type(nd_).__name__} port that lands on "
+                   f"{_name(child)} — use that element's port if it is the intended end",
+                   [_name(e)], None, None)
+    for r, bad, letter in region_cover:
+        cx.add("CF-REG-001", "warn", f"panel ({letter}): Region {r.label or ''!r} covers "
+               f"non-member(s) {', '.join(_name(o) for o in bad[:4])}",
+               [_name(o) for o in bad[:6]], len(bad), 0)
+    for fill, letter in sparse_panels:
+        if fill < cx.t("CF-LAY-007", "warn", 0.40):
+            cx.add("CF-LAY-007", "warn", f"panel ({letter}): content covers only {fill:.0%} of its "
+                   "cell", [f"panel:{letter}"], fill, 0.40)
+        elif fill < cx.t("CF-LAY-007", "info", 0.55):
+            cx.add("CF-LAY-007", "info", f"panel ({letter}): content covers {fill:.0%} of its cell",
+                   [f"panel:{letter}"], fill, 0.55)
+    for frac, letter, nb in align_frac:
+        if frac < cx.t("CF-LAY-001", "warn", 0.5):
+            cx.add("CF-LAY-001", "warn", f"panel ({letter}): only {frac:.0%} of {nb} boxes share an "
+                   "edge/centre line", [f"panel:{letter}"], frac, 0.5)
+        elif frac < cx.t("CF-LAY-001", "info", 0.8):
+            cx.add("CF-LAY-001", "info", f"panel ({letter}): {frac:.0%} of {nb} boxes aligned",
+                   [f"panel:{letter}"], frac, 0.8)
+    for cv, n, gaps in gap_bad:
+        cx.add("CF-LAY-002", "warn", f"uneven gaps in {_name(n)} (CV {cv:.2f}: "
+               f"{', '.join(f'{g * cx.factor:.1f}' for g in gaps[:6])} pt)", [_name(n)], cv, 0.25)
+
+
+def _check_guide_captions(cx, panel, diagram, edge, pts):
+    """Check continuous guide paths against group titles and panel captions."""
+    from .edges import _poly_hits_rect
+    from .textutil import measure_text
+    if not pts:
+        pts = dict(diagram.layout_edges()["routed"]).get(edge, [])
+    boxes = diagram._title_boxes()
+    if not panel._no_caption():
+        g, th = panel.geom, panel.theme
+        pt, pr, pb, pl = panel.padding
+        fs = th.panel_title_size
+        lines = panel._title_lines()
+        y = (g.y + pt + fs * .9 if panel.caption == "top" else
+             g.y + g.h - pb - fs * .25 - panel._sub_h() - fs * 1.2 * (len(lines) - 1))
+        ox, oy = panel._offset
+        k = panel._scale
+        for i, text in enumerate(lines):
+            w, h = measure_text(text, fs, weight="bold")
+            boxes.append(((g.x + pl - ox) / k, (y + fs * 1.2 * i - fs - oy) / k, w / k, h / k))
+    if any(_poly_hits_rect(pts, box) for box in boxes) and not _ignored([edge, diagram], "CF-ANN-001"):
+        cx.add("CF-ANN-001", "warn", "guide touches a caption", [_name(edge)], None, None)
+
+
+def _check_route_geometry(cx, diagram, edge, pts, factor):
+    """Check routed interior segments and feedback excursions in printed points."""
+    lengths = [math.hypot(b[0] - a[0], b[1] - a[1]) * factor
+               for a, b in zip(pts, pts[1:])]
+    short = [v for v in lengths[1:-1] if 0 < v < 4]
+    if short and not _ignored([edge, diagram], "CF-ARR-004"):
+        cx.add("CF-ARR-004", "warn",
+               "Edge has a small interior jog; use jog_tol or align the endpoint nodes",
+               [_name(edge)], min(short), 4)
+    if pts and diagram._is_back_edge(edge):
+        g = diagram.content.geom
+        spill = max(0, g.x - min(x for x, y in pts),
+                    max(x for x, y in pts) - (g.x + g.w),
+                    g.y - min(y for x, y in pts),
+                    max(y for x, y in pts) - (g.y + g.h)) * factor
+        if spill > 24 and not _ignored([edge, diagram], "CF-ARR-005"):
+            cx.add("CF-ARR-005", "warn",
+                   "Return edge expands diagram bounds; use loop_side or leave a routing channel",
+                   [_name(edge)], spill, 24)
+
+
+def _lands_on_child(port: Any, container: Any, tol: float = 1.0) -> Any:
+    """The drawn child a container port's point touches (e.g. the top of a stretched Col
+    is the top edge of its first box), or None when it lands on blank space."""
+    from .compose import Stacked
+    from .primitives import Box, CircleHighlight, Group
+
+    try:
+        x, y, _d = port.resolve()
+    except Exception:  # pragma: no cover
+        return None
+    for k in container.children():
+        if not isinstance(k, (Box, Group, CircleHighlight, Stacked)):
+            continue
+        g = k.geom
+        if g.x - tol <= x <= g.x + g.w + tol and g.y - tol <= y <= g.y + g.h + tol:
+            return k
+    return None
+
+
+_WORD = re.compile(r"[^\s]*\w[^\s]*")  # tokens with a letter/digit: "↔", "·", "+" are not words
+
+
+def _plain(s: str) -> str:
+    from .textutil import parse_rich
+
+    try:
+        lines = parse_rich(s)
+        return "\n".join("".join(r.text for r in ln) for ln in lines)
+    except Exception:  # pragma: no cover
+        return s
+
+
+def _label_checks(cx, n, long_lab, many_lines, sentence) -> None:
+    if not isinstance(getattr(n, "text", None), str) or not n.text:
+        return
+    chain = _ancestors(n)
+    if _ignored(chain, "CF-TXT-006"):
+        return
+    txt = re.sub(r"[_^]\{([^}]*)\}", r"\1", _plain(n.text))
+    lines = [ln for ln in txt.split("\n")]
+    words = len(_WORD.findall(txt))
+    mw = cx.t("CF-TXT-006", "max_words", 4)
+    mc = cx.t("CF-TXT-006", "max_chars", 24)
+    if any(len(_WORD.findall(ln)) > mw or len(ln) > mc for ln in lines):
+        long_lab.append(txt.replace("\n", " / ")[:40])
+    if len(lines) > cx.t("CF-TXT-006", "max_lines", 2):
+        many_lines.append(txt.replace("\n", " / ")[:40])
+    if words > 8:
+        sentence.append(txt.replace("\n", " ")[:40])
+
+
+def _pad_check(cx, n, pad_err, pad_warn, scale) -> None:
+    if not (getattr(n, "text", None) or getattr(n, "subtitle", None)):
+        return
+    if _ignored(_ancestors(n), "CF-TXT-007"):
+        return
+    g = n.geom
+    if g.w <= 0 or g.h <= 0:
+        return
+    try:
+        tw, th_ = n._content_size()
+        tx, ty, tW, tH = n._text_rect(g.x, g.y, g.w, g.h)
+    except Exception:  # pragma: no cover
+        return
+    fs = n._fs()
+    ph, pv = (tW - tw) / 2.0, (tH - th_) / 2.0
+    tol = 0.5 / max(1e-6, scale * cx.factor)
+    if ph < -tol or pv < -tol:
+        pad_err.append((min(ph, pv) / fs, n))
+        return
+    if type(n).__name__ != "Box":  # shapes use their own inscribed text rect
+        return
+    hmin = cx.t("CF-TXT-007", "min_h_em", 0.4)
+    vmin = cx.t("CF-TXT-007", "min_v_em", 0.2)
+    if ph < hmin * fs - 1e-6 or pv < vmin * fs - 1e-6:
+        pad_warn.append((min(ph / fs, pv / fs), n))
+
+
+def _node_boxes(cx: Any, nodes: Sequence[Any]) -> List[Tuple[float, float, float, float]]:
+    """v0.12.0 (A7): SVG-root bounding boxes of what ``nodes`` drew (for the lint
+    preview). Edges are boxed by their drawn path; nodes by their shapes and text."""
+    from .lint_geom import _apply, _geometry, text_runs
+
+    prims = getattr(cx, "prims", None) or []
+    want = {id(n): n for n in nodes if n is not None}
+    acc: Dict[int, List[float]] = {}
+
+    def grow(k: int, x0: float, y0: float, x1: float, y1: float) -> None:
+        b = acc.setdefault(k, [x0, y0, x1, y1])
+        b[0], b[1], b[2], b[3] = min(b[0], x0), min(b[1], y0), max(b[2], x1), max(b[3], y1)
+
+    def owner_key(p: Any) -> Optional[int]:
+        for n in (p.owner,) + tuple(p.chain or ()):
+            if n is not None and id(n) in want:
+                return id(n)
+        return None
+
+    for p in prims:
+        if p.in_defs or p.tag == "text":
+            continue
+        k = owner_key(p)
+        if k is None:
+            continue
+        try:
+            for pts, _closed in _geometry(p.tag, p.attrs):
+                for x, y in pts:
+                    X, Y = _apply(p.m, x, y)
+                    grow(k, X, Y, X, Y)
+        except Exception:  # pragma: no cover
+            continue
+    for r in text_runs(prims):
+        k = owner_key(r.p)
+        if k is not None:
+            grow(k, *r.core)
+    return [tuple(b) for b in acc.values()]
+
+
+def _edge_spill(content: Any) -> List[str]:
+    """v0.13.0: Diagrams whose edges / edge labels stick out sideways past their
+    nodes (that margin is part of the panel width but no node 'owns' it)."""
+    from .constraints import walk
+    from .edges import Diagram
+
+    out = []
+    for d in walk(content):
+        if not isinstance(d, Diagram):
+            continue
+        try:
+            l, _t, r, _b = d._margins()
+        except Exception:  # pragma: no cover
+            continue
+        if l + r < 4.0:
+            continue
+        g = d.content.geom
+        worst = None
+        try:
+            for e, _p, ((x, _y, w, _h), _r, _a) in d.layout_edges()["labels"]:
+                sp = max(g.x - x, x + w - g.right)
+                if sp > 1.0 and (worst is None or sp > worst[0]):
+                    worst = (sp, e, "right" if x + w - g.right >= g.x - x else "left")
+        except Exception:  # pragma: no cover
+            pass
+        msg = f"{_name(d)} edges/labels stick out {l:.0f} pt left + {r:.0f} pt right of its nodes"
+        if worst is not None:
+            lab = str(getattr(worst[1], "label", "") or "").replace("\n", " ")
+            msg += (f" (widest: label '{lab[:28]}' of {_name(worst[1])}, {worst[0]:.0f} pt past the "
+                    f"{worst[2]} side — try label_side= / label_pos= or a shorter label)")
+        out.append(msg)
+    return out
+
+
+def _width_budget(fig: Any) -> str:
+    """v0.13.0: break the natural width into panels, fixed overhead (gaps, margins,
+    pads), captions / subtitles, widths= stretching and edge-label spill."""
+    b = getattr(fig, "_wbudget", None)
+    if not b:
+        return ""
+    try:
+        place, needs, used = b["place"], b["needs"], b["used"]
+        gap, margin = b["gap"], b["margin"]
+        col_nat, col_w = b["col_nat"], b["col_w"]
+        nat_sum = sum(col_nat[c] for c in used)
+        fixed = gap * (len(used) - 1) + 2 * margin
+        parts = []
+        for k in fig._order:
+            pn = fig._panels[k]
+            wp = getattr(pn, "_wparts", None)
+            if wp is None:
+                continue
+            item = f"({k}) {needs[k][0]:.0f}"
+            if wp["caption"] > wp["content"] + 0.5:
+                item += f" [title/subtitle {wp['caption']:.0f} > content {wp['content']:.0f}]"
+            parts.append(item)
+        out = (f"; width budget: panels {' + '.join(parts)} pt (each = content + pad"
+               f"), columns sum {nat_sum:.0f} pt + fixed {fixed:.0f} pt "
+               f"({len(used) - 1} panel gap(s) × {gap:g} + 2 × {margin:g} margin)")
+        if getattr(fig, "widths", None):
+            stretched = sum(col_w[c] for c in used)
+            cl = getattr(fig, "_widths_clamped", [])
+            if stretched > nat_sum + 0.5:
+                ws = fig.widths
+                worst = max(range(len(ws)), key=lambda c: col_nat[c] / ws[c] if ws[c] else 0)
+                out += (f"; widths={[round(w, 2) for w in ws]} stretches the columns to "
+                        f"{stretched:.0f} pt because column {worst + 1} needs {col_nat[worst]:.0f} pt "
+                        f"but gets only a {ws[worst] / sum(ws):.0%} share")
+            elif cl:
+                out += (f"; widths= spare-room hint cannot be applied: the natural column widths alone exceed the slot"
+                        f" (widths= only shares spare room, it cannot make content narrower)")
+        for k in fig._order:
+            pn = fig._panels[k]
+            if pn.content is not None:
+                for sp in _edge_spill(pn.content):
+                    out += f"; panel ({k}): {sp}"
+        return out
+    except Exception:  # pragma: no cover - diagnostics must never break lint
+        return ""
+
+
+def _wrap_hint(fig: Any) -> str:
+    """v0.14.0: the labels that still set the width (after the auto-wrap pass)."""
+    try:
+        from .autowrap import width_setters
+
+        ws = width_setters(fig)
+    except Exception:  # pragma: no cover
+        return ""
+    if not ws:
+        return ""
+    return ("; labels setting the width (shorten them, break them with \"\\n\" or stack them in "
+            "a Col): " + ", ".join(ws))
+
+
+def _widest_chain(fig: Any) -> str:
+    """v0.12.0 (A6): name what makes a shrunk figure wide — the widest panel, then
+    down through its widest child until a Row (whose widest members are listed)."""
+    try:
+        from .node import Container
+
+        widths = getattr(fig, "widths", None)
+        grid = getattr(fig, "grid", None)
+
+        def share(k: str) -> float:  # the panel's share of the width under Figure(widths=)
+            if not widths or not grid:
+                return 1.0
+            for row in grid:
+                cols = [i for i, ch in enumerate(row) if ch == k]
+                if cols:
+                    return sum(widths[i] for i in cols if i < len(widths)) / sum(widths)
+            return 1.0
+
+        best = None
+        for k in getattr(fig, "_order", []):
+            p = fig._panels[k]
+            if p.content is None:
+                continue
+            m = p.content.geom.w / max(share(k), 1e-6)
+            if best is None or m > best[2]:
+                best = (k, p.content, m)
+        if best is None:
+            return ""
+        sh = share(best[0])
+        parts = [f"panel ({best[0]}) {best[1].geom.w:.0f} pt"
+                 + (f" in a {sh:.0%} widths= share" if sh < 0.999 else "")]
+        n = best[1]
+        for _depth in range(12):
+            kids = [c for c in n.children() if getattr(c, "geom", None) is not None
+                    and not getattr(c, "_cf_guide", False)] if hasattr(n, "children") else []
+            if not kids:
+                break
+            if isinstance(n, Container) and getattr(n, "direction", "") == "row" and len(kids) > 1:
+                top = sorted(kids, key=lambda c: -c.geom.w)[:3]
+                gap = float(getattr(n, "gap", 0.0) or 0.0) if not callable(getattr(n, "gap", None)) else 0.0
+                if parts and parts[-1].startswith(_name(n) + " "):
+                    parts.pop()
+                parts.append(f"{_name(n)} of {len(kids)} side by side (gap {gap:g}; widest: "
+                             + ", ".join(f"{_name(c)} {c.geom.w:.0f}" for c in top) + ")")
+                break
+            w = max(kids, key=lambda c: c.geom.w)
+            if w.geom.w < 0.6 * n.geom.w and len(kids) > 1:
+                parts.append(f"{_name(n)} {n.geom.w:.0f} pt")
+                break
+            n = w
+            parts.append(f"{_name(n)} {n.geom.w:.0f} pt")
+        return "; widest chain: " + " → ".join(parts)
+    except Exception:  # pragma: no cover - diagnostics must never break lint
+        return ""
+
+
+def _gap_cv(n) -> Optional[Tuple[float, List[float]]]:
+    kids = [k for k in n.children() if k.geom.w > 0 and k.geom.h > 0]
+    if len(kids) < 3 or getattr(n, "justify", "start") not in ("start", "center", "end"):
+        return None
+    horiz = getattr(n, "direction", "column") == "row"
+    ks = sorted(kids, key=lambda k: k.geom.x if horiz else k.geom.y)
+    gaps = []
+    for a, b in zip(ks, ks[1:]):
+        g = (b.geom.x - a.geom.right) if horiz else (b.geom.y - a.geom.bottom)
+        gaps.append(g)
+    if any(g < -0.5 for g in gaps):
+        return None
+    mean = sum(gaps) / len(gaps)
+    if mean <= 1.0:
+        return None
+    sd = math.sqrt(sum((g - mean) ** 2 for g in gaps) / len(gaps))
+    return sd / mean, gaps
+
+
+def _alignment(boxes: List[Any]) -> Optional[float]:
+    bs = [b for b in boxes if b.geom.w > 0 and b.geom.h > 0]
+    if len(bs) < 3:
+        return None
+    tol = 1.0
+    ok = 0
+    for b in bs:
+        g = b.geom
+        xs = (g.x, g.cx, g.right)
+        ys = (g.y, g.cy, g.bottom)
+        hit = False
+        for o in bs:
+            if o is b:
+                continue
+            h = o.geom
+            if any(abs(a - c) <= tol for a, c in zip(xs, (h.x, h.cx, h.right))) or \
+               any(abs(a - c) <= tol for a, c in zip(ys, (h.y, h.cy, h.bottom))):
+                hit = True
+                break
+        ok += hit
+    return ok / len(bs)
+
+
+def _count_crossings(edges: List[List[Tuple[Tuple[float, float], Tuple[float, float]]]]) -> int:
+    def cross(p1, p2, p3, p4) -> bool:
+        def o(a, b, c):
+            return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+
+        d1, d2 = o(p3, p4, p1), o(p3, p4, p2)
+        d3, d4 = o(p1, p2, p3), o(p1, p2, p4)
+        return (d1 * d2 < -1e-6) and (d3 * d4 < -1e-6)
+
+    n = 0
+    for i in range(len(edges)):
+        for j in range(i + 1, len(edges)):
+            if any(cross(a, b, c, d) for a, b in edges[i] for c, d in edges[j]):
+                n += 1
+    return n
+
+
+# ---- export ------------------------------------------------------------------------
+def _check_export(cx: _Ctx, prims: List[_Prim]) -> None:
+    from .constraints import walk
+    fig = cx.fig
+    W, H = fig.width, fig.height
+    if cx.venue is not None and cx.target is not None:
+        if fig.physical:
+            if abs(W - cx.target) > 0.02 * cx.target:
+                cx.add("CF-EXP-001", "warn", f"figure is {W:.0f} pt wide, {cx.venue.name} "
+                       f"{cx.width_arg} width is {cx.target:.0f} pt (LaTeX will rescale it ×"
+                       f"{cx.target / W:.2f})", [], W, cx.target)
+        else:
+            cx.add("CF-EXP-001", "info", f"px figure ({W:.0f} px) checked as scaled ×{cx.factor:.3f} "
+                   f"to {cx.target:.0f} pt; Figure(venue=...) lays out at print size", [], cx.factor, 1.0)
+    if getattr(fig, "global_scale", 1.0) < 0.999:
+        nat = getattr(fig, "natural_width", W)
+        cx.add("CF-EXP-001", "warn" if fig.global_scale < 0.98 else "info", f"content is {nat:.0f} pt wide but the slot is {W:.0f} pt: "
+               f"everything shrinks ×{fig.global_scale:.2f} (fonts {fig.theme.small_size * fig.global_scale:.1f}"
+               f"–{fig.theme.title_size * fig.global_scale:.1f} pt) — use width='text', cols=, or fewer/shorter boxes"
+               + f"; attempted autowrap ({len(getattr(fig, '_autowrapped', []))} labels), gap scale {fig._layout_report.get('gap_scale_used', 1.0):.3f}"
+               + _width_budget(fig) + _widest_chain(fig) + _wrap_hint(fig)
+               + " (docs/guides/fit-a-column.md; docs/cookbook/30_compact_column.py)",
+               [], fig.global_scale, 1.0)
+    if any(n.__dict__.get("_slot_width") for p in fig._panels.values()
+           if p.content is not None for n in walk(p.content)):
+        cx.add("CF-EXP-001", "info", "reflowed overflowing rows before shrinking" + _widest_chain(fig)
+               + " (docs/guides/fit-a-column.md; docs/cookbook/30_compact_column.py)", [], None, None)
+    aw = getattr(fig, "_autowrapped", None) or []
+    if aw:
+        cx.add("CF-EXP-001", "info", f"auto-wrapped {len(aw)} label(s) onto two lines to fit the "
+               f"{W:.0f} pt slot instead of shrinking: "
+               + ", ".join(f"{n} → '{new.replace(chr(10), '⏎')}'" for n, _old, new in aw[:6])
+               + (" …" if len(aw) > 6 else "")
+               + " (put your own \\n in a label to choose the break; Figure(auto_wrap=False) "
+               "or auto_wrap=False on a node / Edge to keep one line)", [], len(aw), None)
+    if cx.scale != 1.0:
+        cx.add("CF-EXP-001", "warn", f"LaTeX scale {cx.scale:g} ≠ 1 (sizes checked after scaling)",
+               [], cx.scale, 1.0)
+    if cx.venue is None and not fig.physical:
+        cx.add("CF-EXP-001", "info", "no venue: px figure checked as 1 px = 1 pt; pass venue= for a "
+               "real check", [], None, None)
+    # aspect
+    if cx.venue is not None and H > 0:
+        asp = W / H
+        lo, hi = (1.1, 2.5) if cx.width_arg == "column" else (2.0, 4.5)
+        if not (lo <= asp <= hi) and "CF-LAY-004" not in cx.ignore:
+            cx.add("CF-LAY-004", "info", f"aspect {asp:.2f} outside {lo}–{hi} for a "
+                   f"{cx.width_arg}-width figure", [], asp, lo if asp < lo else hi)
+    target_aspect = getattr(fig, "target_aspect", None)
+    if target_aspect and H > 0 and getattr(fig, "fit", "none") != "none":
+        actual = W / H
+        if abs(actual / target_aspect - 1) > 0.08 and "CF-LAY-008" not in cx.ignore:
+            cx.add("CF-LAY-008", "warn",
+                   f"aspect {actual:.2f} misses target {target_aspect:g}; remove a row, "
+                   "use fit='scale', or relax aspect", [], actual, target_aspect)
+    # fonts (PDF)
+    if cx.pdf is not None:
+        from .export import pdf_fonts
+
+        rows = pdf_fonts(cx.pdf)
+        bad = [r for r in rows if r["type"].startswith("Type 3") or r["type"] == "Type3" or not r["embedded"]]
+        if bad:
+            cx.add("CF-EXP-002", "error", f"{len(bad)} Type 3 / unembedded font(s) in {cx.pdf}",
+                   [r["name"] for r in bad], len(bad), 0)
+        elif cx.venue is not None and cx.venue.font_rule == "type1" and rows:
+            cx.add("CF-EXP-002", "info", f"{cx.venue.name} asks for Type 1 fonts; the PDF embeds "
+                   "TrueType subsets (accepted by the template checkers in practice)",
+                   [r["name"] for r in rows][:4], None, None)
+    # raster images
+    for p in prims:
+        if p.tag != "image" or p.in_defs:
+            continue
+        dpi = _image_dpi(p, cx.factor)
+        if dpi is not None and dpi < cx.t("CF-EXP-003", "min_dpi", 300) and not _ignored(p.chain, "CF-EXP-003"):
+            cx.add("CF-EXP-003", "warn", f"embedded image at {dpi:.0f} dpi", [_name(p.owner)], dpi, 300)
+    if fig.title:
+        sev = "info"
+        extra = f" ({cx.venue.name}: no title inside the figure)" if cx.venue is not None and cx.venue.no_title else ""
+        cx.add("CF-EXP-004", sev, "figure has an in-figure title" + extra, [fig.title[:30]], None, None)
+    if not cx.alt:
+        cx.add("CF-EXP-005", "info", "no alt text (save(..., alt='...'))", [], None, None)
+
+
+def _image_dpi(p: _Prim, factor: float) -> Optional[float]:
+    import base64
+    import io
+
+    href = p.attrs.get("{http://www.w3.org/1999/xlink}href") or p.attrs.get("href") or ""
+    try:
+        w = float(p.attrs.get("width", "0"))
+    except ValueError:
+        return None
+    if not href.startswith("data:image/") or w <= 0:
+        return None
+    if "svg" in href.split(";")[0]:
+        return None
+    try:
+        from PIL import Image as _PIL
+
+        data = base64.b64decode(href.split(",", 1)[1])
+        px = _PIL.open(io.BytesIO(data)).size[0]
+    except Exception:
+        return None
+    inches = w * p.scale * factor / 72.0
+    return px / inches if inches > 0 else None
+
+
+def rule_table_markdown() -> str:
+    """The rule table as Markdown (used to generate ``docs/lint-rules.md``)."""
+    rows = ["| id | rule | max severity | threshold | fix | status |", "|---|---|---|---|---|---|"]
+    for r in RULES.values():
+        rows.append(f"| `{r.id}` | {r.title} | {r.severity} | {r.threshold} | {r.fix} | "
+                    f"{'implemented' if r.implemented else 'deferred'} |")
+    return "\n".join(rows)