codefig 0.17.0__py3-none-any.whl

codefig/figure.py

@@ -0,0 +1,1923 @@
+"""Figure and Panel — top-level composition API."""
+
+from __future__ import annotations
+
+from pathlib import Path
+import os as _os
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from .constraints import (
+    ConstraintScope,
+    apply_size_constraints,
+    invalidate_tree,
+    solve_constraints,
+    translate_tree,
+    walk,
+)
+from .node import BoxGeom, Col, Grid, Node, Row, Stack
+from .primitives import Arrow, Box, Ellipsis, Group, LoopArrow, Matrix, Spacer, Text
+from .render_svg import draw_rect, draw_text, svg_footer, svg_header
+from .styles import (
+    Theme,
+    ThemeLike,
+    current_theme,
+    get_theme,
+    use_theme,
+    apply_edge_overrides,
+    apply_spacing_overrides,
+    normalize_justify,
+    normalize_pad,
+)
+from .textutil import measure_text
+
+
+class LayoutError(ValueError):
+    """A physical layout cannot preserve the requested minimum font size."""
+
+
+class Panel(ConstraintScope):
+    """One lettered panel inside a Figure. Use as context manager or += content.
+
+    ``panel.constrain(...)`` adds relational constraints (see codefig.constraints);
+    constraints registered on the Figure or on any Diagram inside this panel are
+    solved here too, after flex layout and before edge routing.
+    """
+
+    def __init__(
+        self,
+        letter: str,
+        title: str = "",
+        *,
+        theme: Optional[Theme] = None,
+        caption: Optional[str] = "bottom",  # bottom | top | none
+        frame: Union[bool, str] = True,
+        fit: Optional[bool] = None,
+        fit_mode: Optional[str] = None,  # scale|none  (reflow → falls back to scale; documented)
+        max_scale: Optional[float] = None,
+        align: str = "center",  # horizontal placement of fitted content
+        justify: Optional[str] = None,  # vertical placement: start|center|end (None → auto)
+        pack: str = "center",  # start|center|end — leftover space when not scaling
+        pad: Optional[object] = None,
+        padding: Optional[object] = None,
+        overlap: Optional[str] = None,  # resolve|warn|error|ignore (None → "resolve")
+        align_edges: Optional[bool] = None,  # v0.11.0 node-nudging edge alignment
+        subtitle: Optional[str] = None,  # v0.12.0 second, smaller caption line
+        frame_color: Optional[str] = None,  # v0.13.0
+        letters: bool = True,  # v0.14.0: False drops the "(a)" tag, keeps the title
+    ) -> None:
+        from .overlaps import check_policy
+
+        self.frame_color = frame_color
+        self.letters = bool(letters)
+        self.subtitle = subtitle
+
+        self.overlap = check_policy(overlap) or "resolve"
+        self.align_edges = True if align_edges is None else bool(align_edges)
+        self._auto_cons: list = []
+        self.letter = letter
+        self.title = title
+        self.theme = theme or current_theme()
+        self.content: Optional[Node] = None
+        self.geom = BoxGeom()
+        # caption: "bottom" (paper style, centered below content) or "top"
+        cap = "none" if caption in (None, False) else str(caption).lower()
+        if cap not in ("bottom", "top", "none"):
+            raise ValueError(f"caption must be 'bottom', 'top' or 'none', got {caption!r}")
+        self.caption = cap
+        # v0.13.0: frame="solid" | "dashed" | "dotted" (True = "solid")
+        if isinstance(frame, str):
+            fs_ = frame.lower()
+            if fs_ not in ("solid", "dashed", "dotted", "none"):
+                raise ValueError("panel frame must be True/False or 'solid'|'dashed'|'dotted'|'none'")
+            self.frame_style = None if fs_ == "none" else fs_
+        else:
+            self.frame_style = "solid" if frame else None
+        self.frame = self.frame_style is not None
+        # fit_mode: "scale" uniform zoom (default when fit=True); "none" content-size + pack;
+        # "reflow" is not implemented — falls back to scale (see README).
+        mode = fit_mode
+        if mode is None:
+            if fit is None:  # physical themes keep content at print size (no zoom)
+                fit = not self.theme.physical
+            mode = "scale" if fit else "none"
+        mode = str(mode).lower()
+        if mode == "reflow":
+            mode = "scale"  # honest fallback
+        self.fit_mode = mode
+        self.fit = mode == "scale"  # BC
+        self.max_scale = float(self.theme.max_panel_scale if max_scale is None else max_scale)
+        self._force_scale: Optional[float] = None  # Figure(panel_scale="uniform")
+        self.align = align  # start|center|end
+        # v0.7.0: a top caption keeps its content right under it (leftover height goes
+        # below, where it separates the panel from the next row); otherwise centre.
+        if justify is None:
+            justify = "start" if (cap == "top" and self.theme.physical) else "center"
+        self.justify = normalize_justify(justify)  # start|center|end
+        self.pack = pack if pack in ("start", "center", "end") else "center"
+        raw = padding if padding is not None else pad
+        self.padding = (
+            normalize_pad(raw) if raw is not None else normalize_pad(self.theme.panel_pad)
+        )
+        self._scale = 1.0
+        self._offset = (0.0, 0.0)
+        self._fig_constraints: list = []  # routed from Figure.constrain
+        self._overlays: list = []
+        self._bbox = (0.0, 0.0, 0.0, 0.0)
+
+    # ---- constraints ---------------------------------------------------------
+    def all_constraints(self) -> list:
+        """Panel + Figure-routed + Diagram-scoped constraints for this panel."""
+        out = list(self._cf_constraints()) + list(self._fig_constraints)
+        if self.content is not None:
+            for n in walk(self.content):
+                lst = n.__dict__.get("_constraints") if hasattr(n, "__dict__") else None
+                if lst:
+                    out.extend(lst)
+        return out
+
+    def _flex_and_solve(self, w: float, h: float, *, warn: bool = True, cons: Optional[list] = None):
+        """Flex-layout content at the local origin, then solve constraints.
+
+        Returns the content bbox (x, y, w, h) in local (pre-scale) units.
+        """
+        if cons is None:
+            cons = self.all_constraints() + list(self._auto_cons)
+        self.content.layout(0.0, 0.0, w, h)
+        res = solve_constraints(self.content, cons, warn=warn)
+        self._overlays = res.overlays
+        self._last_grow = res.growth
+        return res.bbox
+
+    def _solve_tolerant(self, w: float, h: float, user: list, auto: list, warn: bool):
+        """Solve user + auto constraints; auto no_overlap constraints that clash with
+        required ones are downgraded to strong instead of raising."""
+        from .constraints import ConstraintConflictError
+
+        try:
+            return self._flex_and_solve(w, h, warn=warn, cons=user + auto)
+        except ConstraintConflictError:
+            for c in auto:
+                if c.kind != "align_edge":
+                    c.strength = "strong"
+            return self._flex_and_solve(w, h, warn=warn, cons=user + auto)
+
+    def _resolve_overlaps(self, w: float, h: float,
+                          room: Optional[Tuple[float, float]] = None) -> list:
+        """overlap='resolve': iteratively add no_overlap constraints (≤ 6 rounds)."""
+        from .overlaps import find_overlaps, resolution_for
+
+        self._auto_cons = []
+        if self.content is None:
+            return []
+        user = self.all_constraints()
+        auto: list = []
+        seen: set = set()
+        for _round in range(6 if self.overlap == "resolve" else 0):
+            if user or auto:
+                self._solve_tolerant(w, h, user, auto, warn=False)
+            else:
+                self.content.layout(0.0, 0.0, w, h)
+                self._overlays = []
+            found = find_overlaps(self.content, self._overlays, user)
+            new = []
+            for o in found:
+                key = frozenset((id(o.a), id(o.b)))
+                if key in seen:
+                    continue
+                seen.add(key)
+                new.append(resolution_for(o, self._overlays))
+            if not new:
+                break
+            auto.extend(new)
+        auto = self._push_regions(w, h, user, auto)
+        auto = self._align_edges(w, h, user, auto, room)
+        self._auto_cons = auto
+        return auto
+
+    def _align_edges(self, w: float, h: float, user: list, auto: list,
+                     room: Optional[Tuple[float, float]] = None) -> list:
+        """v0.11.0: nudge connected nodes so facing ports line up (see codefig.edge_align).
+
+        ``room`` is the panel's inner size during the final layout: containers may then
+        grow into space the panel has anyway (never during measuring, so a nudge never
+        makes a panel ask for more space)."""
+        from .constraints import invalidate_tree
+        from .edge_align import (breaks_flush, broken_sibling_pairs, candidates, flush_pairs,
+                                 flush_repairs, snapshot, visible_jogs)
+        from .overlaps import find_overlaps
+
+        if not self.align_edges or self.content is None:
+            return auto
+        key = (round(w, 1), round(h, 1), len(auto), len(user),
+               None if room is None else (round(room[0], 1), round(room[1], 1)))
+        cache = self.__dict__.setdefault("_align_cache", {})
+        if key in cache:
+            return auto + cache[key]
+
+        def solve(cons: list) -> Tuple[float, float, float, float]:
+            invalidate_tree(self.content)
+            self._last_grow = {}
+            if user or cons:
+                return self._solve_tolerant(w, h, user, cons, warn=False)
+            self.content.layout(0.0, 0.0, w, h)
+            self._overlays = []
+            g = self.content.geom
+            return (g.x, g.y, g.w, g.h)
+
+        bbox0 = solve(auto)
+        cands = candidates(self.content)
+        kept: list = []
+        if cands:
+            th = self.theme
+            max_shift = th.L(float(getattr(th, "align_max_shift", 24.0)))
+            if room is None:  # measuring: a small, bounded growth budget
+                grow_max = th.L(float(getattr(th, "align_max_grow", 12.0)))
+                lim_w, lim_h = bbox0[2] + grow_max, bbox0[3] + grow_max
+            else:  # final layout: only the space the panel already has
+                lim_w, lim_h = max(bbox0[2], room[0]), max(bbox0[3], room[1])
+            snap0 = snapshot(self.content)
+            flush0 = flush_pairs(self.content, snap0)
+            # v0.12.0 (A15): user constraints win — a nudge may not worsen any user
+            # relation, and nodes the user tied with an equality (same_x / same_y /
+            # align / place …) keep their position on that axis.
+            def _ures() -> List[float]:
+                out = []
+                for uc in user:
+                    try:
+                        out.append(max((r.residual() for r in uc.rels), default=0.0))
+                    except Exception:  # pragma: no cover - unresolvable custom anchor
+                        out.append(0.0)
+                return out
+
+            ures0 = _ures()
+            pins: Dict[int, set] = {}
+            partners: Dict[Tuple[int, str], set] = {}  # v0.13.0: nodes tied together
+            for uc in user:
+                for r in uc.rels:
+                    if getattr(r, "op", "==") != "==":
+                        continue
+                    ids = [(id(a.node), a.axis) for a in r.anchors()
+                           if getattr(a, "node", None) is not None]
+                    for nid, ax in ids:
+                        pins.setdefault(nid, set()).add(ax)
+                        partners.setdefault((nid, ax), set()).update(
+                            m for m, ax2 in ids if ax2 == ax and m != nid)
+            jogs = visible_jogs(self.content)
+            ov0 = len(find_overlaps(self.content, self._overlays, user))
+
+            dirty = False
+            dbg = _os.environ.get("CF_ALIGN_DEBUG")
+            for _prio, _e, c in cands:
+                if dirty:
+                    solve(auto + kept)
+                    dirty = False
+                if c.rels[0].residual() <= 0.05:
+                    continue  # already straight after earlier nudges
+                def check(extra: list) -> str:
+                    bb = solve(auto + kept + extra)
+                    if c.rels[0].residual() > 0.05:
+                        return "unsat %.2f" % c.rels[0].residual()
+                    if bb[2] > lim_w + 0.05 or bb[3] > lim_h + 0.05:
+                        return "bbox"
+                    if any(r1 > r0 + 0.05 for r0, r1 in zip(ures0, _ures())):
+                        return "user"
+                    grown = {k for k, g in (self._last_grow or {}).items()
+                             if any(abs(v) > 0.05 for v in g)}
+                    snap = snapshot(self.content)
+                    # v0.13.0: a uniform shift of the whole content (re-centring in a
+                    # roomier panel) moves nothing relative to anything else
+                    tx, ty = bb[0] - bbox0[0], bb[1] - bbox0[1]
+
+                    def _moved(nid: int, ax: str) -> float:
+                        i = 0 if ax == "x" else 1
+                        return snap[nid][i] - snap0.get(nid, snap[nid])[i] if nid in snap else 0.0
+
+                    def _pin_broken(nid: int, ax: str) -> bool:
+                        """A tied node may move only together with everything it is tied to
+                        (the user relation keeps its shape); alone it stays put."""
+                        d = _moved(nid, ax)
+                        t = tx if ax == "x" else ty
+                        if min(abs(d), abs(d - t)) <= 0.05:
+                            return False
+                        ps = partners.get((nid, ax), set())
+                        return not ps or any(abs(_moved(m, ax) - d) > 0.05 for m in ps)
+
+                    for nid, (x, y, gw, gh) in snap.items():
+                        x0, y0, w0, h0 = snap0.get(nid, (x, y, gw, gh))
+                        if (abs(gw - w0) > 0.05 or abs(gh - h0) > 0.05) and nid not in grown:
+                            return "size"
+                        if abs(x - x0) > max_shift or abs(y - y0) > max_shift:
+                            return "shift %.1f" % max(abs(x - x0), abs(y - y0))
+                        pa = pins.get(nid)
+                        if pa and any(_pin_broken(nid, ax) for ax in pa):
+                            return "pinned"
+                    if breaks_flush(flush0, snap, snap0):
+                        return "flush"
+                    return ""
+
+                extra = [c]
+                dirty = True
+                why = check(extra)
+                # v0.11.0: a nudge that only breaks sibling flush lines may take those
+                # siblings along (two rounds, so short chains follow too)
+                for _round in range(2):
+                    if why != "flush":
+                        break
+                    broken = broken_sibling_pairs(flush0, snapshot(self.content))
+                    if not broken:
+                        break
+                    extra = extra + flush_repairs(self.content, broken)
+                    why = check(extra)
+                if not why:
+                    j = visible_jogs(self.content)
+                    if j >= jogs:
+                        why = "jogs %d>=%d" % (j, jogs)
+                    elif len(find_overlaps(self.content, self._overlays, user)) > ov0:
+                        why = "overlap"
+                if dbg:
+                    print("ALIGN", key[:2], c.desc, why or "OK")
+                    if not why and dbg == "2":
+                        from .constraints import node_name as _nn, walk as _walk
+                        snap = snapshot(self.content)
+                        for n in _walk(self.content):
+                            x, y, gw, gh = snap[id(n)]
+                            x0, y0, w0, h0 = snap0[id(n)]
+                            if max(abs(x - x0), abs(y - y0), abs(gw - w0), abs(gh - h0)) > 0.05:
+                                print("   moved", _nn(n), round(x - x0, 1), round(y - y0, 1),
+                                      round(gw - w0, 1), round(gh - h0, 1))
+                if not why:
+                    kept.extend(extra)
+                    jogs = j
+                    dirty = False
+            solve(auto + kept)
+        cache[key] = kept
+        return auto + kept
+
+    def _push_regions(self, w: float, h: float, user: list, auto: list) -> list:
+        """Move non-member boxes out of Diagram regions (``Region(exclude=)``).
+
+        v0.9.0: for every intruder two kinds of candidates are scored —
+
+        * *reorder*: move the intruder's flex unit (its ancestor that is a direct
+          child of the lowest container holding the members) just before / after the
+          members' span, so it leaves the region without changing the container shape;
+        * *push*: the four sides as strong no_overlap constraints against all members
+          (the v0.8.0 greedy push).
+
+        A candidate is valid when the intruder clears the region and the total
+        intrusion count drops; the cheapest valid one wins by
+        :meth:`_layout_cost` (intrusions ≫ edge-box hits ≫ crossings ≫ edge length ≫
+        footprint). Nothing valid → the carved outline handles it at draw time.
+        """
+        from .edges import Diagram
+        from .regions import nest_pads, push_constraints, push_sides, region_intruders
+
+        regs = [(d, r) for d in walk(self.content) if isinstance(d, Diagram)
+                for r in d.regions if r.exclude in ("auto", "push")]
+        if not regs:
+            return auto
+        diagrams = []
+        for d, _r in regs:
+            if all(d is not x for x in diagrams):
+                diagrams.append(d)
+
+        def solve(cons: list) -> None:
+            invalidate_tree(self.content)
+            if user or cons:
+                self._solve_tolerant(w, h, user, cons, warn=False)
+            else:
+                self.content.layout(0.0, 0.0, w, h)
+                self._overlays = []
+
+        def intrusions() -> int:
+            for d, _r in regs:
+                nest_pads(d.regions)
+            return sum(len(region_intruders(d, r)) for d, r in regs)
+
+        solve(auto)
+        tried: set = set()
+        moves = self.__dict__.setdefault("_region_moves", [])
+        for _round in range(8):
+            progress = False
+            before = intrusions()
+            if not before:
+                break
+            for d, r in regs:
+                for intr in region_intruders(d, r):
+                    key = (id(r), id(intr))
+                    if key in tried:
+                        continue
+                    tried.add(key)
+                    margin = r._pad() + r.theme.L(3.0)
+                    cands: list = ([("order", mv) for mv in _reorder_moves(self.content, r, intr)]
+                                   if r.exclude == "auto" else [])
+                    cands += [("push", push_constraints(r, intr, side, margin), side)
+                              for _disp, side in push_sides(r, intr)]
+                    best = None
+                    for cand in cands:
+                        if cand[0] == "order":
+                            cand[1].apply()
+                            solve(auto)
+                        else:
+                            solve(auto + cand[1])
+                        g = intr.geom
+                        n_in = intrusions()
+                        if not r.intrudes((g.x, g.y, g.w, g.h)) and n_in < before:
+                            cost = self._layout_cost(diagrams, n_in)
+                            if best is None or cost < best[0]:
+                                best = (cost, cand)
+                        if cand[0] == "order":
+                            cand[1].undo()
+                    if best is not None:
+                        cand = best[1]
+                        if cand[0] == "order":
+                            cand[1].apply()
+                            rec = ("reorder", intr, cand[1].where)
+                        else:
+                            auto = auto + cand[1]
+                            rec = ("push", intr, cand[2])
+                        # layout runs several passes: record each move once
+                        if not any(m[0] == rec[0] and m[1] is rec[1] and m[2] == rec[2]
+                                   for m in moves):
+                            moves.append(rec)
+                        progress = True
+                    solve(auto)
+                    if progress:
+                        break
+                if progress:
+                    break
+            if not progress:
+                break
+        return auto
+
+    def _layout_cost(self, diagrams: list, n_intrusions: int) -> Tuple[float, ...]:
+        """Lexicographic cost of the current layout (see _push_regions)."""
+        from .regions import diagram_boxes
+        from .routing import count_crossings
+
+        length = 0.0
+        cross = 0
+        hits = 0
+        x0 = y0 = float("inf")
+        x1 = y1 = float("-inf")
+        for d in diagrams:
+            try:
+                routed = d._routed()[0]
+            except Exception:  # pragma: no cover - routing failure: ignore edges
+                routed = []
+            paths = [pts for _e, pts in routed]
+            boxes, _parent = diagram_boxes(d)
+            leaves = [(n, rc) for n, rc in boxes if not list(n.children())]
+            for e, pts in routed:
+                for k in range(len(pts) - 1):
+                    (ax, ay), (bx, by) = pts[k], pts[k + 1]
+                    length += abs(bx - ax) + abs(by - ay)
+                    for n, (rx, ry, rw, rh) in leaves:
+                        if n is getattr(e.src, "node", e.src) or n is getattr(e.dst, "node", e.dst):
+                            continue
+                        if _seg_hits_rect(ax, ay, bx, by, rx, ry, rw, rh):
+                            hits += 1
+            cross += count_crossings(paths)
+            for _n, (rx, ry, rw, rh) in boxes:
+                x0, y0 = min(x0, rx), min(y0, ry)
+                x1, y1 = max(x1, rx + rw), max(y1, ry + rh)
+        foot = (x1 - x0) + (y1 - y0) if x1 > x0 else 0.0
+        # edge length and footprint are compared in units of ~4 pt so tiny solver
+        # jitter does not decide between otherwise equal candidates
+        return (n_intrusions, hits, cross, round((length + foot) / 4.0))
+
+    def check_overlaps(self) -> list:
+        """Overlaps among visible nodes in the laid-out panel (see codefig.overlaps)."""
+        from .overlaps import find_overlaps
+
+        if self.content is None:
+            return []
+        from .edges import Diagram
+        from .overlaps import find_edge_issues
+
+        cons = self.all_constraints()
+        out = find_overlaps(self.content, self._overlays, cons)
+        self._publish_overlay_obstacles()
+        for n in walk(self.content):
+            if isinstance(n, Diagram):
+                out.extend(find_edge_issues(n, self._overlays, cons))
+        for o in out:
+            o.panel = self.letter
+        return out
+
+    def _publish_overlay_obstacles(self) -> None:
+        """Hand place() annotations to every Diagram so its edges route around them."""
+        from .edges import Diagram
+
+        obs = [o for o in self._overlays if getattr(o, "_cf_obstacle", True)]
+        for n in walk(self.content):
+            if isinstance(n, Diagram):
+                n._cf_overlay_obstacles = obs
+                n._cf_overlays_all = list(self._overlays)
+                n._placed_labels = None
+
+    def _after_layout(self) -> None:
+        from .overlaps import emit
+
+        self._publish_overlay_obstacles()
+        if self.overlap == "ignore":
+            return
+        found = self.check_overlaps()
+        emit(found, "warn" if self.overlap == "resolve" else self.overlap)
+
+    def _prepare_sizes(self) -> None:
+        if self.content is not None:
+            from .legend import Legend
+
+            corners = self.__dict__.setdefault("_corner_legends", [])
+            for parent in list(walk(self.content)):
+                if hasattr(parent, "_kids"):
+                    for child in list(parent._kids):
+                        if isinstance(child, Legend) and child.corner is not None and child.overlay:
+                            parent._kids.remove(child)
+                            corners.append(child)
+                            parent.invalidate()
+            for legend in corners:
+                legend.collect(self.content)
+            cons = self.all_constraints()
+            trees = [self.content] + [c.overlay for c in cons if getattr(c, "overlay", None) is not None]
+            for t in trees:
+                for n in walk(t):
+                    if isinstance(n, Legend):
+                        if isinstance(n.source, str) and n.source == "figure":
+                            fig = self.__dict__.get("_fig")
+                            roots = ([q.content for q in (fig._panels[k] for k in fig._order)
+                                      if q.content is not None] if fig is not None
+                                     else [self.content])
+                            n.collect(roots)
+                        else:
+                            n.collect(self.content)
+            apply_size_constraints(self.content, cons)
+
+    def __enter__(self) -> "Panel":
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        return None
+
+    def __iadd__(self, node: Node) -> "Panel":
+        if self.content is None:
+            self.content = node
+        elif isinstance(self.content, Stack):
+            self.content.add(node)
+        else:
+            self.content = Stack([self.content, node], gap=self.theme.gap, align="center")
+        return self
+
+    def set(self, node: Node) -> "Panel":
+        self.content = node
+        return self
+
+    def _sub_fs(self) -> float:
+        return self.theme.panel_title_size * 0.85
+
+    def _sub_lines(self) -> List[str]:
+        """Subtitle lines: explicit ``\n`` breaks, plus (v0.13.0) automatic wrapping
+        to the panel width computed in :meth:`measure_content`."""
+        if not self.subtitle:
+            return []
+        cached = self.__dict__.get("_sub_cache")
+        if cached is not None and cached[0] == self.subtitle:
+            return list(cached[1])
+        return str(self.subtitle).split("\n")
+
+    def _wrap_sub(self, width: float) -> List[str]:
+        fs = self._sub_fs()
+        out: List[str] = []
+        for para in str(self.subtitle).split("\n"):
+            if measure_text(para, fs)[0] <= width + 0.5 or " " not in para:
+                out.append(para)
+                continue
+            cur = ""
+            for word in para.split(" "):
+                cand = (cur + " " + word) if cur else word
+                if cur and measure_text(cand, fs)[0] > width + 0.5:
+                    out.append(cur)
+                    cur = word
+                else:
+                    cur = cand
+            if cur:
+                out.append(cur)
+        self.__dict__["_sub_cache"] = (self.subtitle, list(out))
+        return out
+
+    def _title_lines(self) -> List[str]:
+        """v0.13.0: a ``\n`` in a panel title gives a multi-line caption."""
+        return self.caption_text().split("\n")
+
+    def _sub_h(self) -> float:
+        """Height of the optional subtitle line(s) under the caption (v0.12.0)."""
+        if not self.subtitle or self.caption == "none":
+            return 0.0
+        return self._sub_fs() * 1.25 * len(self._sub_lines())
+
+    def _caption_h(self, k: float) -> float:
+        if self._no_caption():
+            return 0.0
+        th = self.theme
+        if th.physical:  # one exact value for measure and layout
+            n = len(self._title_lines())
+            return th.panel_title_size * 1.2 * n + th.title_gap + self._sub_h()
+        return th.panel_title_size * k + self._sub_h()
+
+    def measure_content(self) -> Tuple[float, float]:
+        th = self.theme
+        if self.content is None:
+            return 120.0, 80.0 + self._caption_h(1.6)
+        self._prepare_sizes()
+        cw, ch = self.content.measure()
+        auto = self._resolve_overlaps(cw, ch)
+        user = self.all_constraints()
+        if user or auto:
+            _bx, _by, cw, ch = self._solve_tolerant(cw, ch, user, auto, warn=False)
+        # letter + title row needs space on the left/top; caption must fit too
+        label = self.caption_text()
+        if th.physical:
+            pt, pr, pb, pl = self.padding
+            lw = 0.0 if self._no_caption() else max(
+                measure_text(t, th.panel_title_size, weight="bold")[0] for t in self._title_lines())
+            if self.subtitle and self.caption != "none":
+                # v0.13.0: the subtitle wraps to the panel width instead of widening it
+                sfs = self._sub_fs()
+                widest = max(measure_text(t, sfs)[0] for t in str(self.subtitle).split("\n"))
+                wrap_w = max(cw, lw, min(widest, sfs * 14))
+                lw = max([lw] + [measure_text(t, sfs)[0] for t in self._wrap_sub(wrap_w)])
+            title_h = self._caption_h(1.6)
+            # v0.13.0: width parts for the CF-EXP-001 width budget
+            self._wparts = {"content": cw, "caption": lw, "pad": pl + pr}
+            return max(cw, lw) + pl + pr, ch + title_h + pt + pb
+        title_h = self._caption_h(1.6)
+        lw = 0.0 if self._no_caption() else measure_text(label, th.panel_title_size * 1.15)[0]
+        return max(cw, lw) + 2 * th.panel_pad, ch + title_h + 2 * th.panel_pad
+
+    def caption_text(self) -> str:
+        """``"(a) title"`` — the panel tag plus title as drawn (just the title with
+        ``letters=False`` / ``Figure(panel_letters=False)``)."""
+        if not self.letters:
+            return str(self.title or "")
+        return f"({self.letter}) {self.title}" if self.title else f"({self.letter})"
+
+    def _no_caption(self) -> bool:
+        return self.caption == "none" or (not self.caption_text() and not self.subtitle)
+
+    def _inner(self) -> Tuple[float, float, float, float]:
+        th = self.theme
+        g = self.geom
+        title_h = self._caption_h(1.8)
+        pt, pr, pb, pl = self.padding
+        if th.physical:
+            top = title_h if self.caption == "top" else 0.0
+            return g.x + pl, g.y + pt + top, g.w - pl - pr, g.h - title_h - pt - pb
+        if self.caption == "top":
+            return (
+                g.x + pl,
+                g.y + title_h + pt * 0.5,
+                g.w - pl - pr,
+                g.h - title_h - pt * 0.5 - pb,
+            )
+        return g.x + pl, g.y + pt, g.w - pl - pr, g.h - title_h - pt - pb
+
+    def _pack_offset(
+        self, ix: float, iy: float, iw: float, ih: float, sw: float, sh: float
+    ) -> Tuple[float, float]:
+        """Place content box in leftover panel space (pack / align / justify)."""
+        # Horizontal: prefer align; pack only applies when align is center-ish default
+        if self.align == "start":
+            ox = ix
+        elif self.align == "end":
+            ox = ix + (iw - sw)
+        else:
+            ox = ix + (iw - sw) / 2
+        # Vertical: pack is the leftover-space knob (distinct from fit-scale)
+        pack = self.pack
+        if self.justify == "start" or pack == "start":
+            # justify wins when explicitly start/end; pack used when justify=center
+            if self.justify == "start":
+                oy = iy
+            elif self.justify == "end":
+                oy = iy + (ih - sh)
+            elif pack == "start":
+                oy = iy
+            elif pack == "end":
+                oy = iy + (ih - sh)
+            else:
+                oy = iy + (ih - sh) / 2
+        elif self.justify == "end":
+            oy = iy + (ih - sh)
+        else:
+            if pack == "start":
+                oy = iy
+            elif pack == "end":
+                oy = iy + (ih - sh)
+            else:
+                oy = iy + (ih - sh) / 2
+        return ox, oy
+
+    def layout(self, x: float, y: float, w: float, h: float) -> None:
+        self.geom = BoxGeom(x, y, w, h)
+        if self.content is None:
+            return
+        ix, iy, iw, ih = self._inner()
+        self._prepare_sizes()
+        cw, ch = self.content.measure()
+        cw, ch = max(cw, 1.0), max(ch, 1.0)
+        self._overlays = []
+        self._bbox = (0.0, 0.0, cw, ch)
+        lw = cw if self.fit_mode == "scale" else max(cw, iw)
+        auto = self._resolve_overlaps(lw, ch, None if self.fit_mode == "scale" else (iw, ih))
+        user = self.all_constraints()
+        self._overlays = []
+        if user or auto:
+            # flex → constraint solve → fit the *solved* bbox
+            bx, by, bw, bh = self._solve_tolerant(lw, ch, user, auto, warn=True)
+            bw, bh = max(bw, 1.0), max(bh, 1.0)
+            self._bbox = (bx, by, bw, bh)
+            if self.fit_mode == "scale":
+                s = min(iw / bw, ih / bh, self.max_scale) * 0.95
+                if self._force_scale is not None:
+                    s = min(s, self._force_scale)
+                self._scale = s
+                self._offset = self._pack_offset(ix, iy, iw, ih, bw * s, bh * s)
+            else:
+                self._scale = 1.0
+                ox, oy = self._pack_offset(ix, iy, iw, ih, bw, bh)
+                translate_tree(self.content, ox - bx, oy - by)
+                for o in self._overlays:
+                    translate_tree(o, ox - bx, oy - by)
+                self._bbox = (ox, oy, bw, bh)
+                self._offset = (0.0, 0.0)
+            self._after_layout()
+            return
+        if self.fit_mode == "scale":
+            s = min(iw / cw, ih / ch, self.max_scale) * 0.95
+            if self._force_scale is not None:
+                s = min(s, self._force_scale)
+            self.content.layout(0.0, 0.0, cw, ch)
+            self._scale = s
+            sw, sh = cw * s, ch * s
+            self._offset = self._pack_offset(ix, iy, iw, ih, sw, sh)
+        else:
+            # fit_mode == "none": content-sized, pack leftover (no uniform scale)
+            self._scale = 1.0
+            # Give content at least its measure; allow fill children to use panel width
+            lw = cw if self.theme.physical else max(cw, iw)
+            self.content.layout(0.0, 0.0, lw, ch)
+            # Re-measure after layout? keep cw,ch natural for packing
+            sw, sh = cw, ch
+            ox, oy = self._pack_offset(ix, iy, iw, ih, sw, sh)
+            # Re-layout at absolute origin so draw needs no scale transform
+            self.content.layout(ox, oy, lw, ch)
+            self._offset = (0.0, 0.0)
+        self._after_layout()
+
+    def draw(self, buf: List[str]) -> None:
+        th = self.theme
+        g = self.geom
+        # Panel frame
+        if self.frame:
+            draw_rect(
+                buf,
+                g.x,
+                g.y,
+                g.w,
+                g.h,
+                fill="#ffffff",
+                stroke=self.frame_color or th.stroke,
+                stroke_width=th.frame_stroke,
+                radius=0,
+                dasharray={"dashed": "3,2", "dotted": "1,1.5"}.get(self.frame_style or ""),
+            )
+        # Caption: (a) title
+        label = self.caption_text()
+        pt, pr, pb, pl = self.padding
+        if self._no_caption():
+            pass
+        elif th.physical:
+            fs = th.panel_title_size
+            sh = self._sub_h()
+            tls = self._title_lines()
+            if self.caption == "top":
+                ty = g.y + pt + fs * 0.9
+            else:
+                ty = g.y + g.h - pb - fs * 0.25 - sh - fs * 1.2 * (len(tls) - 1)
+            for i, t in enumerate(tls):
+                draw_text(buf, t, g.x + pl, ty + fs * 1.2 * i, font_size=fs, weight="bold")
+            ty += fs * 1.2 * (len(tls) - 1)
+            if sh:
+                sfs = self._sub_fs()
+                for i, t in enumerate(self._sub_lines()):
+                    draw_text(buf, t, g.x + pl, ty + fs * 0.3 + sfs * (1.0 + 1.25 * i),
+                              font_size=sfs, fill=th.muted_color)
+        elif self.caption == "top":
+            draw_text(
+                buf,
+                label,
+                g.x + th.panel_pad,
+                g.y + th.panel_pad + th.panel_title_size,
+                font_size=th.panel_title_size,
+                weight="bold",
+            )
+        else:
+            fs = th.panel_title_size * 1.15
+            lw, _ = measure_text(label, fs)
+            draw_text(
+                buf,
+                label,
+                g.x + (g.w - lw) / 2,
+                g.y + g.h - th.panel_pad * 0.8,
+                font_size=fs,
+            )
+        if self.content is not None:
+            if self.fit_mode == "scale":
+                ox, oy = self._offset
+                bx, by = self._bbox[0], self._bbox[1]
+                tr = f"translate({ox:.2f},{oy:.2f}) scale({self._scale:.4f})"
+                if abs(bx) > 1e-6 or abs(by) > 1e-6:
+                    tr += f" translate({-bx:.2f},{-by:.2f})"
+                buf.append(f'<g transform="{tr}">')
+                self.content.draw(buf)
+                for o in self._overlays + self.__dict__.get("_corner_legends", []):
+                    o.draw(buf)
+                buf.append("</g>")
+            else:
+                self.content.draw(buf)
+                for o in self._overlays + self.__dict__.get("_corner_legends", []):
+                    o.draw(buf)
+
+
+def _grid_rects(rows: List[List[str]]) -> Dict[str, Tuple[int, int, int, int]]:
+    """letter → (row, col, rowspan, colspan) from a ``Figure(grid=...)`` spec."""
+    cells: Dict[str, List[Tuple[int, int]]] = {}
+    for r, row in enumerate(rows):
+        for c, k in enumerate(row):
+            if k not in (".", " ", ""):
+                cells.setdefault(k, []).append((r, c))
+    out: Dict[str, Tuple[int, int, int, int]] = {}
+    for k, cs in cells.items():
+        r0, r1 = min(r for r, _ in cs), max(r for r, _ in cs)
+        c0, c1 = min(c for _, c in cs), max(c for _, c in cs)
+        if len(cs) != (r1 - r0 + 1) * (c1 - c0 + 1):
+            raise ValueError(f"Figure grid: panel {k!r} does not form a rectangle")
+        out[k] = (r0, c0, r1 - r0 + 1, c1 - c0 + 1)
+    return out
+
+
+class Figure(ConstraintScope):
+    """
+    Top-level figure canvas.
+
+    Physical height fitting parameters:
+
+    | Parameter | Default | Meaning |
+    | --- | --- | --- |
+    | aspect | None | Target width/height; mutually exclusive with height. |
+    | height | None | Target height in pt. |
+    | max_height | None | Height cap; never adds padding. |
+    | fit | "compact" | none, compact, scale or pad; active only with a target. |
+    | min_font | 5.0 | Minimum printed font size in pt for scale. |
+
+    Targets must be positive and finite. Compact compresses automatic spacing
+    only (down to 0.6); explicit gaps and padding stay unchanged. Scale then
+    shrinks uniformly or raises LayoutError at the font floor. Pad centers
+    shorter content vertically. layout_report() exposes fitting diagnostics.
+
+
+    Panels are arranged in a grid (default 2 columns, filled row-major). Layout is
+    constraint/flex based — the public API does not take absolute author coordinates.
+
+    v0.5.0 spans: ``fig.panel("c", colspan=2)`` makes a panel span several grid
+    columns (``rowspan=`` rows); auto placement takes the first free slot that fits,
+    row-major. Or give the whole arrangement as ``grid=["aab", "ccb"]`` (one string or
+    list per row, one panel letter per cell, ``"."`` for an empty cell; each letter
+    must form a rectangle) — ``cols`` then follows the grid.
+
+    Args (layout-related):
+        title: Figure title.
+        size: ``(w, h)`` in px or ``"auto"`` (canvas cropped to the content).
+        cols: Grid columns for auto placement (default 2; ignored with ``grid``).
+        grid: Explicit panel arrangement (see above). Default ``None``.
+        equal_heights: ``"row"`` (default — panels in one grid row share its height),
+            ``"all"`` (every row as tall as the tallest) or ``False`` (each panel
+            keeps its natural height, top-aligned in its row).
+        widths / heights (v0.12.0): column / row size ratios. ``widths`` is a
+            spare-room hint, not a strict ratio under a fixed venue width. For example,
+            ``Figure(grid=["ab"], widths=[5, 4])``: the venue width (minus panel gaps
+            and margins) is shared 5 : 4.  Leave it out unless you want *unequal
+            spare room*: by default every column already gets its content's natural
+            width plus an equal part of the spare room.  v0.13.0: a share narrower
+            than a column's content no longer inflates the figure — that column keeps
+            its natural width and the others split the rest; only when the natural
+            widths alone exceed the slot does everything shrink (CF-EXP-001 lists the
+            width budget).  Without a fixed width (``size="auto"``) the shares are
+            exact and the figure grows until every column fits.
+        panel_dividers (v0.12.0): ``"solid"`` (or ``True``) / ``"dashed"`` /
+            ``"dotted"`` rule lines in the gaps between neighbouring panels;
+            ``None``/``False`` (default) draws none.
+
+    ``fig.panel("a", "title", subtitle="one-line detail")`` adds a smaller second caption
+    line (v0.12.0).
+
+    Example:
+        >>> from codefig import Figure, Box
+        >>> fig = Figure(size="auto", grid=["ab", "cc"])
+        >>> for k in "abc":
+        ...     _ = fig.panel(k, f"panel {k}").set(Box(k))
+        >>> svg = fig.to_svg()
+    """
+
+    def __init__(
+        self,
+        title: str = "",
+        size: Union[Tuple[float, float], str, None] = None,
+        *,
+        venue: Optional[str] = None,
+        width: Union[str, float, None] = None,
+        cols: int = 2,
+        theme: ThemeLike = None,
+        edge: Optional[dict] = None,
+        spacing: Optional[dict] = None,
+        title_pos: str = "bottom",
+        panel_caption: Optional[str] = "inherit",
+        panel_frame: Optional[bool] = None,
+        panel_scale: str = "fit",
+        panel_align: str = "center",
+        panel_justify: Optional[str] = None,
+        canvas_pad: Optional[float] = None,
+        overlap: str = "resolve",
+        roles: Optional[Dict[str, Any]] = None,
+        knockout: Optional[bool] = None,
+        grid: Optional[Sequence[Union[str, Sequence[str]]]] = None,
+        equal_heights: Union[str, bool] = "row",
+        align_edges: bool = True,
+        widths: Optional[Sequence[float]] = None,
+        heights: Optional[Sequence[float]] = None,
+        panel_dividers: Union[str, bool, None] = None,
+        panel_letters: bool = True,
+        auto_wrap: bool = True,
+        font_size: Optional[float] = None,
+        categories: Optional[Sequence[str]] = None,
+        aspect: Optional[float] = None,
+        height: Optional[float] = None,
+        max_height: Optional[float] = None,
+        fit: str = "compact",
+        min_font: float = 5.0,
+    ) -> None:
+        if aspect is not None and height is not None:
+            raise ValueError("aspect= and height= are mutually exclusive; pass one")
+        import math
+        for name, value in (("aspect", aspect), ("height", height),
+                            ("max_height", max_height), ("min_font", min_font)):
+            if value is not None and (not math.isfinite(value) or value <= 0):
+                raise ValueError(f"{name} must be positive and finite; received {value!r}")
+        if fit not in ("none", "compact", "scale", "pad"):
+            raise ValueError("fit must be none | compact | scale | pad")
+        self.target_aspect = aspect
+        self.target_height = height
+        self.max_height = max_height
+        self.fit = fit
+        self.min_font = min_font
+        from .overlaps import check_policy
+        from .policy import normalize_role
+
+        self.panel_letters = bool(panel_letters)
+        self.auto_wrap = bool(auto_wrap)
+        # v0.14.0: declared category order (palette index) — fig.color(name) appends
+        self._cat_order: List[str] = []
+        for c in categories or ():
+            if str(c) not in self._cat_order:
+                self._cat_order.append(str(c))
+
+        if panel_dividers is True:  # v0.13.0: bool alias (True = "solid")
+            panel_dividers = "solid"
+        elif panel_dividers is False:
+            panel_dividers = None
+        if panel_dividers not in (None, "none", "solid", "dashed", "dotted"):
+            raise ValueError("panel_dividers must be None/False, True/'solid', 'dashed' or 'dotted'")
+        self.panel_dividers = None if panel_dividers == "none" else panel_dividers
+        self.widths = [float(v) for v in widths] if widths is not None else None
+        self.heights = [float(v) for v in heights] if heights is not None else None
+        for nm, v in (("widths", self.widths), ("heights", self.heights)):
+            if v is not None and (not v or any(x <= 0 for x in v)):
+                raise ValueError(f"{nm} must be positive ratios, e.g. {nm}=[2, 1]")
+        self.overlap = check_policy(overlap) or "resolve"
+        self.align_edges = bool(align_edges)
+        # figure-level layering defaults: {"Text": "hard", "Group": "none", …}
+        self.roles = {str(k): normalize_role(v) for k, v in (roles or {}).items()}
+        self.knockout = knockout
+        from .venues import get_venue, resolve_width_pt
+
+        if theme is None:
+            th = current_theme()
+            if venue is not None and not th.physical:
+                th = get_theme("paper")  # a venue implies print units
+        else:
+            th = get_theme(theme)
+        th = apply_spacing_overrides(th, spacing)
+        th = apply_edge_overrides(th, edge)
+        if font_size is not None:  # v0.14.0 (C10): figure-wide base text size
+            from dataclasses import replace as _replace
+
+            fsz = float(font_size)
+            if th.font_sizes and fsz not in th.font_sizes:
+                raise ValueError(f"font_size={font_size!r}: the {th.name} theme uses the size roles "
+                                 f"{tuple(th.font_sizes)} pt (lint CF-TXT-002); pick one of them")
+            th = _replace(th, font_size=fsz)
+        self.theme = th
+        self.venue = get_venue(venue)
+        self.venue_width = width if width is not None else ("text" if venue else None)
+        # physical: units are pt at final print size (paper theme, venue= or width=)
+        self.physical = size is None and (th.physical or venue is not None or width is not None)
+        self.target_width: Optional[float] = (
+            resolve_width_pt(venue, self.venue_width) if self.physical else None)
+        self.global_scale = 1.0  # < 1 when content had to shrink to fit the venue width
+        if panel_scale not in ("fit", "uniform"):
+            raise ValueError("panel_scale must be 'fit' or 'uniform'")
+        self.panel_scale = panel_scale
+        self.title = title
+        self.title_pos = title_pos
+        self.panel_caption = th.panel_caption if panel_caption == "inherit" else panel_caption
+        self.panel_frame = th.panel_frame if panel_frame is None else bool(panel_frame)
+        self.panel_align = panel_align
+        self.panel_justify = panel_justify
+        if size is None:
+            size = "auto" if self.physical else (1600, 1200)
+        self._auto_size = isinstance(size, str) and str(size).lower() == "auto"
+        if self._auto_size:
+            # Placeholder; layout() computes from content + pad (paper crop)
+            self.width, self.height = 800.0, 600.0
+        else:
+            self.width, self.height = float(size[0]), float(size[1])  # type: ignore[index]
+        if equal_heights not in ("row", "all", False):
+            raise ValueError("equal_heights must be 'row', 'all' or False")
+        self.equal_heights = equal_heights
+        self.grid: Optional[List[List[str]]] = None
+        if grid is not None:
+            rows_ = [list(r) for r in grid]
+            if not rows_ or any(len(r) != len(rows_[0]) for r in rows_) or not rows_[0]:
+                raise ValueError("Figure grid rows must be non-empty and equally long")
+            self.grid = rows_
+            cols = len(rows_[0])
+            self._grid_rects = _grid_rects(rows_)
+        self.cols = cols
+        if self.widths is not None and len(self.widths) != cols:
+            raise ValueError(f"widths needs one ratio per grid column ({cols}), got {len(self.widths)}")
+        self.canvas_pad = canvas_pad  # None → theme.panel_gap (physical: 1 pt crop margin)
+        self._panels: Dict[str, Panel] = {}
+        self._order: List[str] = []
+
+    def panel(
+        self,
+        letter: str,
+        title: str = "",
+        *,
+        align: Optional[str] = None,
+        justify: Optional[str] = None,
+        pack: str = "center",
+        fit: Optional[bool] = None,
+        fit_mode: Optional[str] = None,
+        pad: Optional[object] = None,
+        overlap: Optional[str] = None,
+        frame: Union[bool, str, None] = None,
+        caption: Optional[str] = "inherit",
+        colspan: int = 1,
+        rowspan: int = 1,
+        max_scale: Optional[float] = None,
+        align_edges: Optional[bool] = None,
+        subtitle: Optional[str] = None,
+        frame_color: Optional[str] = None,
+        letters: Optional[bool] = None,
+    ) -> Panel:
+        """Create (or replace) panel ``letter``.
+
+        Args:
+            letter: Panel letter, shown as ``(a)`` in the caption.
+            title: Caption text.
+            colspan: Grid columns the panel spans (default 1; v0.5.0).
+            rowspan: Grid rows the panel spans (default 1; v0.5.0).
+            align_edges: Nudge nodes so connected ports line up (v0.11.0;
+                default: the figure's ``align_edges``, itself True).
+            max_scale: Largest zoom ``fit_mode="scale"`` may apply (default: the
+                theme's ``max_panel_scale`` — 1.8 classic, 1.0 paper).
+                Use ``1.0`` to keep a wide spanning panel's text at the same size as
+                its neighbours (v0.5.0).
+            align / justify / pack / fit / fit_mode / pad / overlap / frame / caption:
+                Per-panel layout options (see :class:`Panel`).
+            frame: ``True`` / ``"solid"``, ``"dashed"``, ``"dotted"`` or ``False`` — a
+                frame around the whole panel, caption included (v0.13.0 styles);
+                ``frame_color=`` colours it, e.g. ``frame="dashed",
+                frame_color=theme.accent("vermillion")``.
+            subtitle: smaller second caption line; wraps to the panel width
+                (v0.13.0). A ``"\n"`` in ``title`` gives a two-line caption.
+            letters: ``False`` drops the ``(a)`` tag but keeps the title (default:
+                ``Figure(panel_letters=)``, itself True). ``caption="none"`` hides the
+                whole caption — tag *and* title (a title given then warns).
+
+        With ``Figure(grid=...)`` the span comes from the grid and ``colspan`` /
+        ``rowspan`` must be left at 1.
+        """
+        if int(colspan) < 1 or int(rowspan) < 1:
+            raise ValueError("colspan / rowspan must be >= 1")
+        if self.grid is not None:
+            if (colspan, rowspan) != (1, 1):
+                raise ValueError("with Figure(grid=...) the grid defines spans; drop colspan/rowspan")
+            if letter not in self._grid_rects:
+                raise ValueError(f"panel {letter!r} is not in the figure grid")
+        elif int(colspan) > self.cols:
+            raise ValueError(f"colspan={colspan} exceeds cols={self.cols}")
+        cap = self.panel_caption if caption == "inherit" else caption
+        if title and (cap in (None, False) or str(cap).lower() == "none"):
+            import warnings as _w
+
+            from .lint import CaptionWarning
+
+            _w.warn(f"panel {letter!r}: title {str(title)[:40]!r} is not drawn because the caption "
+                    f"is 'none' (it hides the (a) tag AND the title); use "
+                    f"Figure(panel_letters=False) / fig.panel(..., letters=False) to drop only the "
+                    f"letters, or caption='top'/'bottom'", CaptionWarning, stacklevel=2)
+        p = Panel(
+            letter,
+            title,
+            theme=self.theme,
+            letters=self.panel_letters if letters is None else letters,
+            caption=cap,
+            frame=self.panel_frame if frame is None else frame,
+            align=align or self.panel_align,
+            justify=justify or self.panel_justify,
+            pack=pack,
+            fit=fit,
+            fit_mode=fit_mode,
+            pad=pad,
+            overlap=overlap or self.overlap,
+            max_scale=max_scale,
+            align_edges=self.align_edges if align_edges is None else align_edges,
+            subtitle=subtitle,
+            frame_color=frame_color,
+        )
+        p.colspan, p.rowspan = int(colspan), int(rowspan)
+        p.__dict__["_fig"] = self  # Legend(source="figure") collects across panels
+        if letter in self._panels:
+            self._order.remove(letter)
+        self._panels[letter] = p
+        self._order.append(letter)
+        return p
+
+    def _placements(self) -> Tuple[Dict[str, Tuple[int, int, int, int]], int]:
+        """letter → (row, col, rowspan, colspan); and the number of grid rows."""
+        if self.grid is not None:
+            out = {k: self._grid_rects[k] for k in self._order}
+            return out, len(self.grid)
+        cols = self.cols
+        occ: Dict[Tuple[int, int], str] = {}
+        out = {}
+        for k in self._order:
+            p = self._panels[k]
+            cs, rs = getattr(p, "colspan", 1), getattr(p, "rowspan", 1)
+            r = 0
+            placed = False
+            while not placed:
+                for c in range(cols - cs + 1):
+                    if all((r + i, c + j) not in occ for i in range(rs) for j in range(cs)):
+                        for i in range(rs):
+                            for j in range(cs):
+                                occ[(r + i, c + j)] = k
+                        out[k] = (r, c, rs, cs)
+                        placed = True
+                        break
+                r += 1
+        rows = max([r + rs for r, _c, rs, _cs in out.values()] + [1])
+        return out, rows
+
+    def add_panel(self, letter: str, title: str = "", content: Optional[Node] = None) -> Panel:
+        p = self.panel(letter, title)
+        if content is not None:
+            p.set(content)
+        return p
+
+    def _title_h(self) -> float:
+        if self.physical:
+            return self.theme.title_size * 1.25 + self.theme.title_gap if self.title else 0.0
+        return self.theme.title_size * 2.0 if self.title else 12.0
+
+    def _route_constraints(self) -> None:
+        """Assign Figure-level constraints to the panel whose tree holds their nodes."""
+        for letter in self._order:
+            self._panels[letter]._fig_constraints = []
+        trees = {}
+        for letter in self._order:
+            p = self._panels[letter]
+            ids = {id(n) for n in walk(p.content)} if p.content is not None else set()
+            # place() annotations registered on the panel / its Diagrams belong here too
+            for c in p.all_constraints():
+                if c.overlay is not None:
+                    ids |= {id(n) for n in walk(c.overlay)}
+            trees[letter] = ids
+        # place() first so later constraints (e.g. allow_overlap(note)) can name the
+        # annotation it creates
+        fig_cs = list(self._cf_constraints())
+        homes: Dict[int, str] = {}
+        for c in sorted(fig_cs, key=lambda c: c.overlay is None):
+            nodes = [n for n in c.nodes() if c.overlay is None or n is not c.overlay]
+            home = None
+            for letter, ids in trees.items():
+                if nodes and all(id(n) in ids for n in nodes):
+                    home = letter
+                    break
+            if home is None:
+                from .constraints import ConstraintConflictError, node_name
+
+                raise ConstraintConflictError(
+                    f"{c.describe()}: nodes {', '.join(node_name(n) for n in nodes)} are not all "
+                    "inside one panel (panels are scaled independently; constraints are per panel)"
+                )
+            if c.overlay is not None:
+                trees[home] |= {id(n) for n in walk(c.overlay)}
+            homes[id(c)] = home
+        for c in fig_cs:  # keep the author's order inside each panel
+            self._panels[homes[id(c)]]._fig_constraints.append(c)
+
+    def _policy(self):
+        from .policy import use_policy
+
+        return use_policy(self.roles, self.knockout)
+
+    def categories(self) -> List[str]:
+        """Distinct ``category=`` values (→ palette index): the ones declared with
+        ``Figure(categories=[...])`` or asked for with :meth:`color` first, then the rest in
+        panel order."""
+        out: List[str] = list(self.__dict__.get("_cat_order", []))
+        for letter in self._order:
+            p = self._panels[letter]
+            if p.content is None:
+                continue
+            for n in walk(p.content):
+                c = getattr(n, "category", None)
+                if c is not None and str(c) not in out:
+                    out.append(str(c))
+        return out
+
+    def color(self, category: str) -> str:
+        """The fill colour of ``category`` in this figure (v0.14.0): the same colour a
+        ``Box(category=...)`` / ``Circle(category=...)`` gets, so a chart series, an edge
+        or a hand-drawn swatch can share it across panels::
+
+            fig = Figure(venue="osdi", categories=["gate", "baseline"])
+            ... Circle("G", category="gate") ...            # panel (a)
+            LineChart(..., colors=[fig.color("baseline"), fig.color("gate")])  # panel (b)
+
+        The palette index is fixed on first use (``Figure(categories=)`` order, then calls
+        to ``color()``, then ``category=`` in panel order), so it does not change when
+        later panels add categories. Past the palette (6 paper fills) categories cycle the
+        fills with a hatch; ``color()`` returns the fill only."""
+        name = str(category)
+        if name not in self._cat_order:
+            # keep the indices of categories already used by content stable
+            for c in self.categories():
+                if c not in self._cat_order:
+                    self._cat_order.append(c)
+            if name not in self._cat_order:
+                self._cat_order.append(name)
+        from .styles import category_style, use_categories
+        with use_categories(self._cat_order):
+            return category_style(name, self.theme)[0]
+
+    def _ctx(self):
+        """Theme + typeface + layering policy for everything this figure does."""
+        from contextlib import ExitStack
+
+        from .textutil import use_typeface
+
+        from .styles import use_categories
+
+        st = ExitStack()
+        st.enter_context(use_theme(getattr(self, "_fitted_theme", self.theme)))
+        st.enter_context(use_categories(self.categories()))
+        st.enter_context(use_typeface(self.theme.typeface))
+        st.enter_context(self._policy())
+        from .styles import use_output_scale
+
+        st.enter_context(use_output_scale(self.__dict__.get("_script_k", 1.0)))
+        return st
+
+    def layout(self) -> None:
+        from .constraints import invalidate_tree
+        # Recompute row budgets when a figure is reused at a different width.
+        for panel in self._panels.values():
+            if panel.content is not None:
+                changed = False
+                for node in walk(panel.content):
+                    if node.__dict__.pop("_slot_width", None) is not None:
+                        changed = True
+                if changed:
+                    invalidate_tree(panel.content)
+        self._layout_once()
+        # v0.14.0: wrap long labels that set the width before anything shrinks
+        kept = self.__dict__.setdefault("_autowrapped", [])
+        if self.physical and self.auto_wrap and self.target_width is not None \
+                and self.global_scale < 0.9995:
+            from .autowrap import auto_wrap
+
+            kept.extend(auto_wrap(self, self._layout_once))
+        if self.physical and self.target_width is not None and self.global_scale < 0.9995:
+            self._compress_width_gaps = True
+            self._layout_once()
+        if self.physical and self.auto_wrap and self.global_scale < 0.9:
+            # Use each panel's share of the available slot. Reflow only rows that
+            # exceed that budget; fixed child dimensions remain authoritative.
+            from .constraints import invalidate_tree
+            from .node import Container
+            def reflow(node, budget):
+                if isinstance(node, Container):
+                    pt, pr, pb, pl = node.padding
+                    budget = max(1.0, budget - pl - pr)
+                    if node.direction == "row" and node.measure()[0] > budget + pl + pr:
+                        node._slot_width = budget
+                    if node.direction == "row" and not node.__dict__.get("_slot_width"):
+                        return
+                for child in node.children():
+                    reflow(child, budget)
+            for panel in self._panels.values():
+                if panel.content is not None:
+                    budget = panel.content.measure()[0] * self.global_scale
+                    reflow(panel.content, budget)
+                    invalidate_tree(panel.content)
+            self._layout_once()
+        # v0.12.0 (A14): a physical figure shrunk to fit keeps its sub/superscripts at
+        # the theme's printed floor — lay out once more with the scale known
+        for _it in range(3):
+            if not (self.physical and self.theme.script_min > 0):
+                break
+            k = min(1.0, float(self.global_scale))
+            if abs(k - self.__dict__.get("_script_k", 1.0)) <= 0.005:
+                break
+            from .constraints import invalidate_tree
+
+            # a growing script widens the content and lowers the scale: start from
+            # the smaller of the two so the loop settles from below
+            self._script_k = min(k, self.__dict__.get("_script_k", 1.0)) if _it else k
+            for p in self._panels.values():
+                if p.content is not None:
+                    invalidate_tree(p.content)
+            self._layout_once()
+
+    def _layout_once(self) -> None:
+        from dataclasses import replace
+        from .constraints import invalidate_tree
+        self.__dict__.pop("_fitted_theme", None)
+        original = self.theme
+        requested_fit = self.fit
+        width_search = self.physical and self.__dict__.get("_compress_width_gaps", False)
+        search = self.physical and (requested_fit in ("compact", "scale") or width_search)
+        def solve(factor):
+            self.theme = replace(original, gap_scale=original.gap_scale * factor,
+                                 pad_scale=original.pad_scale * factor,
+                                 box_pad=tuple(v * factor for v in original.box_pad) if original.box_pad else None,
+                                 corner_radius=original.corner_radius * factor)
+            for panel in self._panels.values():
+                if panel.content is not None:
+                    invalidate_tree(panel.content)
+            self._layout_unfitted()
+        if search:
+            self.fit = "compact"
+        try:
+            self._layout_unfitted()
+            if not search:
+                return
+            natural = self._layout_report["natural_size"]
+            target = self.width / self.target_aspect if self.target_aspect else self.target_height
+            if self.max_height is not None:
+                target = min(target, self.max_height) if target is not None else self.max_height
+            chosen = 1.0
+            if width_search and self.global_scale < 0.9995:
+                low, high = 0.6, 1.0
+                solve(low)
+                chosen = low
+                if self.global_scale >= 0.9995:
+                    for _ in range(8):
+                        mid = (low + high) / 2
+                        solve(mid)
+                        if self.global_scale >= 0.9995:
+                            low = mid
+                        else:
+                            high = mid
+                    chosen = low
+            if target is not None and natural[1] > target:
+                low, high = 0.6, 1.0
+                solve(low)
+                chosen = low
+                if self.height <= target:
+                    for _ in range(8):
+                        mid = (low + high) / 2
+                        solve(mid)
+                        if self.height <= target:
+                            low = mid
+                        else:
+                            high = mid
+                    chosen = low
+            self.fit = requested_fit
+            solve(chosen)
+            self._layout_report["natural_size"] = natural
+            self._layout_report["gap_scale_used"] = chosen
+            self._fitted_theme = replace(self.theme, fit_font_scale=self.global_scale) if requested_fit == "scale" and self._layout_report["scale_used"] < 1 else self.theme
+        finally:
+            self.fit = requested_fit
+            self.theme = original
+
+    def _layout_unfitted(self) -> None:
+        with self._ctx():
+            self._layout_impl()
+            if self._fit_edge_margins():
+                self._layout_impl()
+            if self.panel_scale == "uniform" and not self.physical:
+                scaled = [p for p in self._panels.values()
+                          if p.content is not None and p.fit_mode == "scale"]
+                if scaled:
+                    s = min(p._scale for p in scaled)
+                    for p in scaled:
+                        p._force_scale = s
+                    self._layout_impl()
+                    for p in scaled:
+                        p._force_scale = None
+
+        self._position_corner_legends()
+
+    def _position_corner_legends(self) -> None:
+        from .legend import position_corners
+        for panel in self._panels.values():
+            position_corners(panel)
+
+    def _fit_edge_margins(self) -> bool:
+        """Size every Diagram's edge margin to what its routed edges / labels really
+        need (instead of the loop-clearance estimate). True if anything changed."""
+        from .constraints import invalidate_tree
+        from .edges import Diagram
+
+        changed = False
+        for letter in self._order:
+            p = self._panels[letter]
+            if p.content is None:
+                continue
+            for n in walk(p.content):
+                if isinstance(n, Diagram) and getattr(n, "_fit_margins", None) is None:
+                    cur = n._margins()
+                    need = n.edge_overflow()
+                    fit = tuple(max(0.0, x) for x in need)
+                    if any(abs(a - b) > 1.0 for a, b in zip(cur, fit)):
+                        n._fit_margins = fit
+                        changed = True
+            if changed:
+                invalidate_tree(p.content)
+        return changed
+
+    def _layout_impl(self) -> None:
+        th = self.theme
+        title_h = self._title_h()
+        cols = self.cols
+        place, rows = self._placements()
+        gap = float(self.canvas_pad if self.canvas_pad is not None else th.panel_gap)
+        self._route_constraints()
+
+        # Natural content sizes per panel
+        needs = {k: self._panels[k].measure_content() for k in self._order}
+
+        def spread(sizes: List[float], start: int, n: int, need: float) -> None:
+            have = sum(sizes[start:start + n]) + gap * (n - 1)
+            if need > have:
+                extra = (need - have) / n
+                for i in range(start, start + n):
+                    sizes[i] += extra
+
+        top = 0.0
+        if self.physical:
+            self._layout_physical(needs, place, rows, spread)
+            return
+        if self._auto_size:
+            # Paper crop: size canvas to content + gaps + title.
+            col_w = [0.0] * cols
+            row_h = [0.0] * rows
+            # single-cell panels first, then spans claim what they still lack
+            for multi in (False, True):
+                for k in self._order:
+                    r, c, rs, cs = place[k]
+                    cw, ch = needs[k]
+                    if (cs > 1) == multi:
+                        spread(col_w, c, cs, cw)
+                    if (rs > 1) == multi:
+                        spread(row_h, r, rs, max(ch, 80.0))
+            if self.equal_heights == "all":
+                row_h = [max(row_h)] * rows
+            self.width = sum(col_w) + gap * (cols + 1)
+            title_h = title_h if self.title else 0.0
+            self.height = sum(row_h) + title_h + gap * (rows + 1)
+            top = title_h if self.title_pos == "top" else 0.0
+        else:
+            avail_w = self.width - gap * (cols + 1)
+            avail_h = self.height - title_h - gap * (rows + 1)
+            col_w = [avail_w / cols] * cols
+            # Content-driven row heights: weight each row by max natural content height
+            # so empty air shrinks when some panels are shorter.
+            row_need = [1.0] * rows
+            for multi in (False, True):
+                for k in self._order:
+                    r, _c, rs, _cs = place[k]
+                    if (rs > 1) == multi:
+                        spread(row_need, r, rs, max(needs[k][1], 80.0))
+            equal = avail_h / rows
+            weights = [max(need, equal * 0.35) for need in row_need]
+            if self.equal_heights == "all":
+                weights = [1.0] * rows
+            total = sum(weights) or 1.0
+            row_h = [avail_h * w / total for w in weights]
+            top = title_h if self.title_pos == "top" else 0.0
+
+        col_x = [gap + sum(col_w[:c]) + gap * c for c in range(cols)]
+        row_y = [top + gap + sum(row_h[:r]) + gap * r for r in range(rows)]
+        for k in self._order:
+            r, c, rs, cs = place[k]
+            w = sum(col_w[c:c + cs]) + gap * (cs - 1)
+            h = sum(row_h[r:r + rs]) + gap * (rs - 1)
+            if self.equal_heights is False:
+                h = min(h, needs[k][1])
+            self._panels[k].layout(col_x[c], row_y[r], w, h)
+
+    def _layout_physical(self, needs, place, rows, spread) -> None:
+        """Print-size layout: panels at natural size (no per-panel zoom). Extra venue
+        width is shared by the columns; if content is wider than the venue, ONE
+        figure-wide scale < 1 shrinks everything uniformly (lint reports it)."""
+        th = self.theme
+        cols = self.cols
+        gap = float(th.panel_gap)
+        margin = float(self.canvas_pad) if self.canvas_pad is not None else 1.0
+        col_w = [0.0] * cols
+        row_h = [0.0] * rows
+
+        def spread_prop(sizes: List[float], start: int, n: int, need: float) -> None:
+            """v0.7.0: a span's missing size goes to its tracks in proportion to what
+            they already hold, so a short panel beside a tall spanning one stays
+            compact (equal shares when the tracks are still empty)."""
+            have = sum(sizes[start:start + n]) + gap * (n - 1)
+            if need <= have:
+                return
+            extra = need - have
+            cur = sizes[start:start + n]
+            tot = sum(cur)
+            for i in range(n):
+                sizes[start + i] += extra * (cur[i] / tot if tot > 1e-9 else 1.0 / n)
+
+        for multi in (False, True):
+            for k in self._order:
+                r, c, rs, cs = place[k]
+                cw, ch = needs[k]
+                if (cs > 1) == multi:
+                    spread_prop(col_w, c, cs, cw)
+                if (rs > 1) == multi:
+                    spread_prop(row_h, r, rs, ch)
+        if self.equal_heights == "all":
+            row_h = [max(row_h)] * rows
+        if self.heights is not None and len(self.heights) == rows:
+            k = max(h / r for h, r in zip(row_h, self.heights))
+            row_h = [r * k for r in self.heights]
+        used = [c for c in range(cols) if col_w[c] > 0] or list(range(cols))
+        nat_cols = list(col_w)
+        if self.widths is not None:
+            used = list(range(cols))
+            self._widths_clamped = []
+            if self.target_width is not None:
+                # v0.13.0: widths= are shares of the *slot*.  A column whose share is
+                # narrower than its content keeps its natural width and the rest of the
+                # slot is shared among the other columns (CSS-flex style) — the shares
+                # never inflate the figure past the slot and force a global shrink.
+                avail = self.target_width - 2 * margin - gap * (cols - 1)
+                if sum(col_w) >= avail - 1e-6:
+                    self._widths_clamped = list(range(cols))
+                else:
+                    fixed: dict = {}
+                    while True:
+                        rest = avail - sum(fixed.values())
+                        free = [c for c in range(cols) if c not in fixed]
+                        tot = sum(self.widths[c] for c in free) or 1.0
+                        bad = [c for c in free if self.widths[c] / tot * rest < col_w[c] - 1e-6]
+                        if not bad:
+                            break
+                        for c in bad:
+                            fixed[c] = col_w[c]
+                    self._widths_clamped = sorted(fixed)
+                    col_w = [fixed[c] if c in fixed else self.widths[c] / tot * rest
+                             for c in range(cols)]
+            else:
+                k = max(w / r for w, r in zip(col_w, self.widths))  # every column fits its content
+                col_w = [r * k for r in self.widths]
+        natural_w = sum(col_w) + gap * (len(used) - 1) + 2 * margin
+        self.natural_width = natural_w
+        # v0.13.0: what the natural width is made of (CF-EXP-001 width budget)
+        self._wbudget = {"col_w": list(col_w), "col_nat": list(nat_cols), "gap": gap,
+                         "margin": margin, "used": list(used), "needs": dict(needs),
+                         "place": dict(place)}
+        s = 1.0
+        if self.target_width is not None:
+            if natural_w <= self.target_width + 1e-6:
+                extra = (self.target_width - natural_w) / max(1, len(used))
+                for c in used:
+                    col_w[c] += extra
+            else:
+                s = self.target_width / natural_w
+        self.global_scale = s
+        title_h = self._title_h()
+        top = title_h if (self.title and self.title_pos == "top") else 0.0
+        inner_w = sum(col_w) + gap * (len(used) - 1)
+        col_x = []
+        x = margin
+        for c in range(cols):
+            col_x.append(x)
+            if c in used:
+                x += col_w[c] + gap
+        row_y = [margin + top + sum(row_h[:r]) + gap * r for r in range(rows)]
+        for k in self._order:
+            r, c, rs, cs = place[k]
+            w = sum(col_w[c:c + cs]) + gap * (cs - 1)
+            h = sum(row_h[r:r + rs]) + gap * (rs - 1)
+            if self.equal_heights is False:
+                h = min(h, needs[k][1])
+            self._panels[k].layout(col_x[c], row_y[r], w, h)
+        self._content_w = inner_w + 2 * margin
+        self._content_h = sum(row_h) + gap * (rows - 1) + 2 * margin + title_h
+        self._grid_geom = (col_x, col_w, row_y, row_h, gap, used)
+        self.width = self._content_w * s
+        self.height = self._content_h * s
+        self._layout_report = dict(natural_size=(self.width, self.height),
+                                   final_size=(self.width, self.height),
+                                   target_aspect=self.target_aspect,
+                                   gap_scale_used=1.0, scale_used=1.0)
+        target = self.width / self.target_aspect if self.target_aspect else self.target_height
+        if self.max_height is not None:
+            target = min(target, self.max_height) if target is not None else self.max_height
+        self._height_offset = 0.0
+        if target is not None and self.fit != "none":
+            if self.height > target and self.fit == "scale":
+                factor = target / self.height
+                smallest = min(self.theme.font_sizes or (self.theme.font_size,)) * self.global_scale * factor
+                if smallest < self.min_font:
+                    raise LayoutError(f"required scale {factor:.1%}; minimum font {smallest:.2f} pt is below min_font={self.min_font}")
+                self.global_scale *= factor
+                self.height = target
+                self._layout_report["scale_used"] = factor
+            elif self.height < target and self.fit == "pad" and self.max_height is None:
+                self._height_offset = (target - self.height) / (2 * self.global_scale)
+                self.height = target
+        self._layout_report["final_size"] = (self.width, self.height)
+
+    def layout_report(self) -> dict:
+        """Return a copy of natural and final physical layout diagnostics."""
+        self.layout()
+        return dict(self._layout_report)
+
+    def _draw_dividers(self, buf: List[str]) -> None:
+        """``panel_dividers=``: a rule centred in each gap between neighbouring panels,
+        as long as the panels on both sides of it."""
+        if not self.panel_dividers or getattr(self, "_grid_geom", None) is None:
+            return
+        from .render_svg import draw_line
+
+        th = self.theme
+        da = {"solid": None, "dashed": "3,2", "dotted": "1,1.5"}[self.panel_dividers]
+        place, _rows = self._placements()
+        col_x, col_w, row_y, row_h, gap, used = self._grid_geom
+        sw = max(th.stroke_width * 0.75, 0.5)
+        for k in self._order:
+            r, c, rs, cs = place[k]
+            g = self._panels[k].geom
+            right = [o for o in self._order if place[o][1] == c + cs and
+                     place[o][0] < r + rs and r < place[o][0] + place[o][2]]
+            if right:
+                x = g.x + g.w + gap / 2
+                y0 = max([g.y] + [self._panels[o].geom.y for o in right])
+                y1 = min([g.y + g.h] + [self._panels[o].geom.y + self._panels[o].geom.h for o in right])
+                if y1 > y0:
+                    draw_line(buf, x, y0, x, y1, stroke=th.muted_color, stroke_width=sw, dasharray=da)
+            below = [o for o in self._order if place[o][0] == r + rs and
+                     place[o][1] < c + cs and c < place[o][1] + place[o][3]]
+            if below:
+                y = g.y + g.h + gap / 2
+                x0 = max([g.x] + [self._panels[o].geom.x for o in below])
+                x1 = min([g.x + g.w] + [self._panels[o].geom.x + self._panels[o].geom.w for o in below])
+                if x1 > x0:
+                    draw_line(buf, x0, y, x1, y, stroke=th.muted_color, stroke_width=sw, dasharray=da)
+
+    def check_overlaps(self) -> list:
+        """Lay out (if needed) and return every remaining overlap, all panels.
+        Each item names the two nodes, the panel and the penetration in px."""
+        import warnings
+
+        from .overlaps import OverlapWarning
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore", OverlapWarning)
+            self.layout()
+        out = []
+        with self._ctx():
+            for letter in self._order:
+                out.extend(self._panels[letter].check_overlaps())
+        return out
+
+    def to_svg(self, *, alt: Optional[str] = None) -> str:
+        """SVG text. Physical figures carry ``width="…pt"`` (1 user unit = 1 pt)."""
+        with self._ctx():
+            return self._to_svg_impl(alt=alt)
+
+    def _to_svg_impl(self, alt: Optional[str] = None) -> str:
+        self.layout()
+        th = self.theme
+        buf = svg_header(self.width, self.height, th, units="pt" if self.physical else "",
+                         title=alt)
+        if self.physical:
+            if self.global_scale < 0.9999:
+                buf.append(f'<g transform="scale({self.global_scale:.5f})">')
+            if getattr(self, "_height_offset", 0):
+                buf.append(f'<g transform="translate(0,{self._height_offset:.5f})">')
+            if self.title:
+                tw, _ = measure_text(self.title, th.title_size, weight="bold")
+                cw, ch = self._content_w, self._content_h
+                ty = (1.0 + th.title_size) if self.title_pos == "top" else ch - 1.0 - th.title_size * 0.3
+                draw_text(buf, self.title, (cw - tw) / 2, ty, font_size=th.title_size,
+                          weight="bold")
+            self._draw_dividers(buf)
+            for letter in self._order:
+                self._panels[letter].draw(buf)
+            if getattr(self, "_height_offset", 0):
+                buf.append("</g>")
+            if self.global_scale < 0.9999:
+                buf.append("</g>")
+            buf.extend(svg_footer())
+            return "\n".join(buf)
+        if self.title:
+            tw, _ = measure_text(self.title, th.title_size)
+            ty = th.title_size + 8 if self.title_pos == "top" else self.height - th.title_size * 0.7
+            draw_text(
+                buf,
+                self.title,
+                (self.width - tw) / 2,
+                ty,
+                font_size=th.title_size,
+                weight="bold",
+            )
+        for letter in self._order:
+            self._panels[letter].draw(buf)
+        buf.extend(svg_footer())
+        return "\n".join(buf)
+
+    def save(
+        self,
+        path: Union[str, Path],
+        *,
+        scale: Optional[float] = None,
+        dpi: Optional[float] = None,
+        lint: Optional[str] = "auto",
+        alt: Optional[str] = None,
+        venue: Optional[str] = None,
+    ) -> Path:
+        """Save as ``.svg``, ``.png`` or ``.pdf``.
+
+        Args:
+            scale: PNG pixel density for px figures (2 → 2×).
+            dpi: PNG resolution for physical (pt) figures (default 300).
+            lint: ``"error"`` refuses to write when :meth:`lint` finds errors (the
+                LintError's last line summarises each error with its fix and the preview
+                path), ``"warn"`` writes anyway, emits a :class:`~codefig.lint.LintWarning`
+                per finding and writes ``<stem>.lint_preview.png`` when there are errors
+                (the iteration mode; see also :meth:`preview`),
+                ``None`` / ``"off"`` skips it; ``"auto"`` (default) = ``"error"`` for
+                physical figures, off for legacy px figures.
+            alt: Alt text: written as the SVG ``<title>`` and to ``<path>.alt.txt``.
+            venue: Venue for the save-time lint (default: the figure's venue).
+        """
+        from .export import save_figure
+
+        return save_figure(self, path, scale=scale, dpi=dpi, lint=lint, alt=alt, venue=venue)
+
+    def preview(
+        self,
+        path: Union[str, Path] = "fig.png",
+        *,
+        alt: Optional[str] = None,
+        venue: Optional[str] = None,
+        scale: Optional[float] = None,
+        dpi: Optional[float] = None,
+    ) -> "Any":
+        """Iteration helper: lint, **always** write the figure, never raise.
+
+        Writes ``path`` (``.png`` / ``.svg`` / ``.pdf``) even when lint finds errors, plus
+        ``<stem>.lint_preview.png`` with every error / warning outlined when there are any
+        (a stale preview is removed when the figure is clean). Returns the
+        :class:`~codefig.lint.LintReport` (``report.image`` / ``report.preview`` are the
+        paths), so ``print(fig.preview("fig.png"))`` shows every finding with its fix.
+        Use it while iterating; make the final call ``fig.save(path, alt=...)``, which
+        refuses on errors.
+        """
+        from .export import save_figure, write_lint_preview
+
+        path = Path(path)
+        rep = self.lint(venue=venue, alt=alt)
+        save_figure(self, path, scale=scale, dpi=dpi, lint=None, alt=alt, venue=venue)
+        rep.image = str(path)
+        if any(f.severity in ("error", "warn") for f in rep.findings):
+            prev = write_lint_preview(self, rep, path, alt)
+            rep.preview = str(prev) if prev is not None else None
+        return rep
+
+    def lint(
+        self,
+        venue: Optional[str] = None,
+        width: Union[str, float, None] = None,
+        scale: float = 1.0,
+        ignore: Optional[Sequence[str]] = None,
+        thresholds: Optional[Dict[str, Dict[str, float]]] = None,
+        *,
+        pdf: Optional[Union[str, Path]] = None,
+        alt: Optional[str] = None,
+    ) -> "Any":
+        """Check the figure against the publication style rules → :class:`~codefig.lint.LintReport`.
+
+        ``venue`` / ``width`` default to the figure's own; ``scale`` is the LaTeX
+        ``\\includegraphics`` scale (e.g. 0.8). See ``docs/lint-rules.md``.
+        """
+        from .lint import lint_figure
+
+        return lint_figure(self, venue=venue, width=width, scale=scale, ignore=ignore,
+                           thresholds=thresholds, pdf=pdf, alt=alt)
+
+
+def _seg_hits_rect(ax: float, ay: float, bx: float, by: float,
+                   rx: float, ry: float, rw: float, rh: float, inset: float = 1.0) -> bool:
+    """Axis-aligned segment passes through the (inset) rectangle interior."""
+    x0, x1 = sorted((ax, bx))
+    y0, y1 = sorted((ay, by))
+    return (x0 < rx + rw - inset and x1 > rx + inset and
+            y0 < ry + rh - inset and y1 > ry + inset)
+
+
+class _Reorder:
+    """Move one child of a container to index ``to`` (undoable)."""
+
+    def __init__(self, cont: Any, unit: Any, to: int, where: str) -> None:
+        self.cont, self.unit, self.to, self.where = cont, unit, to, where
+        self._old: Optional[list] = None
+
+    def apply(self) -> None:
+        kids = self.cont._kids
+        self._old = list(kids)
+        kids.remove(self.unit)
+        kids.insert(self.to, self.unit)
+        self.cont.invalidate()
+
+    def undo(self) -> None:
+        if self._old is not None:
+            self.cont._kids[:] = self._old
+            self._old = None
+            self.cont.invalidate()
+
+
+def _reorder_moves(root: Any, region: Any, intruder: Any) -> list:
+    """Candidate sibling reorders that take ``intruder`` out of ``region``'s span."""
+    from .node import Container
+
+    parent: dict = {}
+    for n in walk(root):
+        for k in n.children():
+            parent[id(k)] = n
+
+    def chain(n: Any) -> list:
+        out = [n]
+        while id(out[-1]) in parent:
+            out.append(parent[id(out[-1])])
+        return out
+
+    members = list(region.members)
+    if not members:
+        return []
+    ichain = chain(intruder)
+    mchains = [chain(m) for m in members]
+    for depth in range(1, len(ichain)):
+        cont = ichain[depth]
+        if not all(any(a is cont for a in mc) for mc in mchains):
+            continue
+        if not isinstance(cont, Container) or not hasattr(cont, "_kids"):
+            return []
+        unit = ichain[depth - 1]
+        kids = list(cont._kids)
+        mpos = []
+        for mc in mchains:
+            i = next(j for j, a in enumerate(mc) if a is cont)
+            mpos.append(kids.index(mc[i - 1]) if i > 0 else -1)
+        if -1 in mpos or any(kids[p] is unit for p in mpos):
+            return []  # a member *is* the container, or shares the intruder's unit
+        cur = kids.index(unit)
+        lo, hi = min(mpos), max(mpos)
+        if not lo < cur < hi:
+            return []
+        moves = [_Reorder(cont, unit, lo, "before"), _Reorder(cont, unit, hi, "after")]
+        return moves
+    return []