codefig 0.17.0__py3-none-any.whl

codefig/constraints.py

@@ -0,0 +1,1571 @@
+"""Relational layout constraints on top of the flex model (Cassowary via kiwisolver).
+
+Authors never write coordinates. They state relations between *anchors* of nodes
+that already exist in the flex tree::
+
+    fig.constrain(
+        align(a.right, b.left),                       # a's right edge == b's left edge
+        same_y(q.row_anchor(5), k.row_anchor(5)),     # matrix rows on one line
+        below(note, box, gap=8, align="center"),      # TikZ ``below=of``
+        place(Text("hot"), near=k.row_anchor(3), side="right", offset=6),
+        nudge(label, dy=-2),
+    )
+
+Pipeline (see ``solve_constraints``):
+
+1. Flex layout runs first and fixes every node's size and an initial position.
+2. Every constrained node, all of its ancestors, and the direct children of those
+   ancestors get translation variables ``dx, dy``; containers additionally get
+   growth variables ``gl, gr, gt, gb >= 0``. A node's absolute position is its flex
+   position plus the sum of its ancestors' translations (shifts propagate to
+   descendants).
+3. Layout invariants are *required*: children stay inside their (possibly grown)
+   parent's padding band, and Row/Col/Grid siblings never overlap along the main
+   axis (gaps may shrink down to the container ``gap``, never below).
+4. Every variable has a weak "stay" at 0 (the flex result); user constraints are
+   ``required`` | ``strong`` (default) | ``medium`` | ``weak`` and override the
+   stays softly. The first node of a relation is the *subject* (the one that moves);
+   later nodes are references and get a stiffer stay.
+5. Required conflicts raise :class:`ConstraintConflictError` naming the nodes;
+   soft constraints that could not be met within 0.5px emit a
+   :class:`ConstraintWarning`.
+"""
+
+from __future__ import annotations
+
+import warnings
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+try:  # pragma: no cover - import guard
+    import kiwisolver as _kiwi
+except Exception:  # pragma: no cover
+    _kiwi = None
+
+
+class ConstraintConflictError(ValueError):
+    """Raised when required constraints (or layout invariants) cannot all hold."""
+
+
+class ConstraintWarning(UserWarning):
+    """A soft (strong/medium/weak) constraint could not be satisfied exactly."""
+
+
+# --------------------------------------------------------------------------- naming
+
+def node_name(node: Any) -> str:
+    """Human readable node label for error messages (id > text > label > class)."""
+    if node is None:
+        return "<None>"
+    nid = getattr(node, "id", None)
+    cls = type(node).__name__
+    if nid:
+        return f"{cls}#{nid}"
+    for attr in ("text", "label", "title"):
+        v = getattr(node, attr, None)
+        if isinstance(v, str) and v.strip():
+            s = v.replace("\n", " ").strip()
+            if len(s) > 24:
+                s = s[:23] + "…"
+            return f"{cls}({s!r})"
+    return f"{cls}@{id(node) & 0xFFFF:04x}"
+
+
+# --------------------------------------------------------------------------- anchors
+
+_WHICH_FRAC = {"start": 0.0, "center": 0.5, "end": 1.0}
+
+
+class Anchor:
+    """
+    One coordinate (x or y) attached to a node. No absolute numbers: its value is
+    whatever the layout puts there. ``anchor + 4`` adds a constant offset.
+
+    Box anchors (``frac`` set) follow container growth; internal anchors (matrix
+    rows/cells, ports) are read through ``getter`` from the node's geometry.
+    """
+
+    __slots__ = ("node", "axis", "frac", "getter", "offset", "label")
+
+    def __init__(
+        self,
+        node: Any,
+        axis: str,
+        *,
+        frac: Optional[float] = None,
+        getter: Optional[Callable[[], float]] = None,
+        offset: float = 0.0,
+        label: str = "",
+    ) -> None:
+        if axis not in ("x", "y"):
+            raise ValueError("axis must be 'x' or 'y'")
+        self.node = node
+        self.axis = axis
+        self.frac = frac
+        self.getter = getter
+        self.offset = float(offset)
+        self.label = label
+
+    def _copy(self, offset: float) -> "Anchor":
+        return Anchor(self.node, self.axis, frac=self.frac, getter=self.getter,
+                      offset=offset, label=self.label)
+
+    def __add__(self, k: float) -> "Anchor":
+        return self._copy(self.offset + float(k))
+
+    def __radd__(self, k: float) -> "Anchor":
+        return self.__add__(k)
+
+    def __sub__(self, k: float) -> "Anchor":
+        return self._copy(self.offset - float(k))
+
+    def base_value(self) -> float:
+        """Current geometric value without the constant offset."""
+        if self.getter is not None:
+            return float(self.getter())
+        g = self.node.geom
+        if self.axis == "x":
+            return g.x + g.w * float(self.frac or 0.0)
+        return g.y + g.h * float(self.frac or 0.0)
+
+    def value(self) -> float:
+        """Current value (after layout / solve) including offset."""
+        return self.base_value() + self.offset
+
+    def describe(self) -> str:
+        s = f"{node_name(self.node)}.{self.label or self.axis}"
+        if abs(self.offset) > 1e-9:
+            s += f"{self.offset:+g}"
+        return s
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"Anchor({self.describe()})"
+
+
+class Anchorable:
+    """Mixin: ``left/right/top/bottom/cx/cy`` anchors from ``_anchor(axis, which)``."""
+
+    def _anchor(self, axis: str, which: str) -> Anchor:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+    @property
+    def left(self) -> Anchor:
+        return self._anchor("x", "start")
+
+    @property
+    def right(self) -> Anchor:
+        return self._anchor("x", "end")
+
+    @property
+    def top(self) -> Anchor:
+        return self._anchor("y", "start")
+
+    @property
+    def bottom(self) -> Anchor:
+        return self._anchor("y", "end")
+
+    @property
+    def cx(self) -> Anchor:
+        return self._anchor("x", "center")
+
+    @property
+    def cy(self) -> Anchor:
+        return self._anchor("y", "center")
+
+    center_x = cx
+    center_y = cy
+
+    def anchor(self, name: str) -> Anchor:
+        """Named anchor: left|right|top|bottom|cx|cy|center_x|center_y."""
+        name = name.lower().replace("-", "_")
+        table = {
+            "left": ("x", "start"), "right": ("x", "end"),
+            "top": ("y", "start"), "bottom": ("y", "end"),
+            "cx": ("x", "center"), "center_x": ("x", "center"),
+            "cy": ("y", "center"), "center_y": ("y", "center"),
+        }
+        if name not in table:
+            raise ValueError(f"unknown anchor {name!r}")
+        return self._anchor(*table[name])
+
+
+_LABELS = {("x", "start"): "left", ("x", "end"): "right", ("x", "center"): "cx",
+           ("y", "start"): "top", ("y", "end"): "bottom", ("y", "center"): "cy"}
+
+
+def box_anchor(node: Any, axis: str, which: str) -> Anchor:
+    return Anchor(node, axis, frac=_WHICH_FRAC[which], label=_LABELS[(axis, which)])
+
+
+class _RefBase(Anchorable):
+    node: Any
+
+    def _anchor(self, axis: str, which: str) -> Anchor:
+        lo, hi = self._span(axis)
+        f = _WHICH_FRAC[which]
+        return Anchor(
+            self.node, axis,
+            getter=lambda lo=lo, hi=hi, f=f: lo() + (hi() - lo()) * f,
+            label=f"{self._name()}.{_LABELS[(axis, which)]}",
+        )
+
+    def _span(self, axis: str) -> Tuple[Callable[[], float], Callable[[], float]]:  # pragma: no cover
+        raise NotImplementedError
+
+    def _name(self) -> str:  # pragma: no cover
+        return ""
+
+
+class MatrixRowRef(_RefBase):
+    """Anchor set for one matrix row: ``cy``/``top``/``bottom`` of the row strip,
+    ``left``/``right``/``cx`` of the cell grid."""
+
+    def __init__(self, m: Any, row: int) -> None:
+        self.node, self.row = m, int(row)
+
+    def _name(self) -> str:
+        return f"row[{self.row}]"
+
+    def _span(self, axis: str):
+        m, r = self.node, self.row
+        if axis == "y":
+            return (lambda: m._row_center_y(r) - m._row_h(r) / 2, lambda: m._row_center_y(r) + m._row_h(r) / 2)
+        return (lambda: m._grid_origin()[0], lambda: m._grid_origin()[0] + m._grid_size()[0])
+
+
+class MatrixColRef(_RefBase):
+    def __init__(self, m: Any, col: int) -> None:
+        self.node, self.col = m, int(col)
+
+    def _name(self) -> str:
+        return f"col[{self.col}]"
+
+    def _span(self, axis: str):
+        m, c = self.node, self.col
+        if axis == "x":
+            return (lambda: m._col_center_x(c) - m._col_w(c) / 2, lambda: m._col_center_x(c) + m._col_w(c) / 2)
+        return (lambda: m._grid_origin()[1], lambda: m._grid_origin()[1] + m._grid_size()[1])
+
+
+class MatrixCellRef(_RefBase):
+    def __init__(self, m: Any, row: int, col: int) -> None:
+        self.node, self.row, self.col = m, int(row), int(col)
+
+    def _name(self) -> str:
+        return f"cell[{self.row},{self.col}]"
+
+    def _span(self, axis: str):
+        m, r, c = self.node, self.row, self.col
+        if axis == "x":
+            return (lambda: m._col_center_x(c) - m._col_w(c) / 2, lambda: m._col_center_x(c) + m._col_w(c) / 2)
+        return (lambda: m._row_center_y(r) - m._row_h(r) / 2, lambda: m._row_center_y(r) + m._row_h(r) / 2)
+
+
+def port_anchor(port: Any, axis: str) -> Anchor:
+    idx = 0 if axis == "x" else 1
+    return Anchor(port.node, axis, getter=lambda: port.resolve()[idx],
+                  label=f"port({port.kind}:{port.side}).{axis}")
+
+
+AnchorLike = Any  # Anchor | Node | MatrixRowRef | ... | Port
+
+
+def as_anchor(obj: AnchorLike, axis: str, which: str = "center") -> Anchor:
+    """Coerce ``obj`` to an Anchor on ``axis`` (nodes/refs use ``which``)."""
+    if isinstance(obj, Anchor):
+        if obj.axis != axis:
+            raise ValueError(f"{obj.describe()} is an {obj.axis}-anchor; expected {axis}")
+        return obj
+    from .edges import Port
+
+    if isinstance(obj, Port):
+        return port_anchor(obj, axis)
+    if hasattr(obj, "_anchor"):
+        return obj._anchor(axis, which)
+    raise TypeError(f"cannot use {type(obj).__name__} as an anchor")
+
+
+def _subject_node(obj: AnchorLike) -> Any:
+    return obj.node if hasattr(obj, "node") and not hasattr(obj, "geom") else obj
+
+
+# --------------------------------------------------------------------------- constraints
+
+_STRENGTH_NAMES = ("required", "strong", "medium", "weak")
+
+
+def _kiwi_strength(s: Union[str, float]) -> float:
+    if _kiwi is None:  # pragma: no cover
+        raise ImportError("codefig constraints need kiwisolver (pip install kiwisolver)")
+    if isinstance(s, (int, float)):
+        return float(s)
+    s = str(s).lower()
+    if s == "required":
+        return _kiwi.strength.required
+    if s == "strong":
+        return _kiwi.strength.strong
+    if s == "medium":
+        return _kiwi.strength.medium
+    if s == "weak":
+        # above every flex "stay" (≤10) but below medium
+        return _kiwi.strength.create(0, 0, 500)
+    raise ValueError(f"strength must be one of {_STRENGTH_NAMES} or a number, got {s!r}")
+
+
+@dataclass
+class Rel:
+    a: Anchor
+    op: str  # == | >= | <=
+    b: Anchor
+    const: float = 0.0  # a op b + const
+
+    def residual(self) -> float:
+        d = self.a.value() - (self.b.value() + self.const)
+        if self.op == "==":
+            return abs(d)
+        if self.op == ">=":
+            return max(0.0, -d)
+        return max(0.0, d)
+
+    def describe(self) -> str:
+        c = f" {self.const:+g}" if abs(self.const) > 1e-9 else ""
+        return f"{self.a.describe()} {self.op} {self.b.describe()}{c}"
+
+    def anchors(self) -> List[Anchor]:
+        return [self.a, self.b]
+
+
+@dataclass
+class LinRel:
+    """Linear relation ``sum(coef * anchor) op const`` (used by distribute())."""
+
+    terms: List[Tuple[float, Anchor]]
+    op: str = "=="
+    const: float = 0.0
+
+    def residual(self) -> float:
+        d = sum(k * a.value() for k, a in self.terms) - self.const
+        if self.op == "==":
+            return abs(d)
+        if self.op == ">=":
+            return max(0.0, -d)
+        return max(0.0, d)
+
+    def describe(self) -> str:
+        parts = " ".join(f"{k:+g}*{a.describe()}" for k, a in self.terms)
+        return f"{parts} {self.op} {self.const:g}"
+
+    def anchors(self) -> List[Anchor]:
+        return [a for _k, a in self.terms]
+
+
+@dataclass
+class Constraint:
+    """A relational layout constraint. Build with the helper functions below."""
+
+    kind: str
+    rels: List[Any] = field(default_factory=list)  # Rel | LinRel
+    strength: Union[str, float] = "strong"
+    subjects: List[Any] = field(default_factory=list)
+    refs: List[Any] = field(default_factory=list)
+    overlay: Optional[Any] = None  # place(): node drawn on top of the flex tree
+    place_spec: Optional[dict] = None
+    tracks: Optional[dict] = None  # align_columns(): shared column tracks
+    nudge: Tuple[float, float] = (0.0, 0.0)
+    size_axis: Optional[str] = None  # same_width / same_height
+    size_nodes: List[Any] = field(default_factory=list)
+    desc: str = ""
+
+    def nodes(self) -> List[Any]:
+        out: List[Any] = []
+        for n in list(self.subjects) + list(self.refs) + list(self.size_nodes):
+            if n is not None and all(n is not m for m in out):
+                out.append(n)
+        for r in self.rels:
+            for n in (a.node for a in r.anchors()):
+                if all(n is not m for m in out):
+                    out.append(n)
+        return out
+
+    def describe(self) -> str:
+        if self.desc:
+            return self.desc
+        return f"{self.kind}(" + "; ".join(r.describe() for r in self.rels) + ")"
+
+    def is_required(self) -> bool:
+        return isinstance(self.strength, str) and self.strength.lower() == "required"
+
+    def __repr__(self) -> str:  # pragma: no cover
+        return f"<Constraint {self.describe()} [{self.strength}]>"
+
+
+def _mk(kind: str, rels: List[Rel], strength: Any, subjects: List[Any], refs: List[Any],
+        desc: str = "") -> Constraint:
+    return Constraint(kind=kind, rels=rels, strength=strength, subjects=subjects,
+                      refs=refs, desc=desc)
+
+
+def align(*anchors: Anchor, offset: float = 0.0, strength: Any = "strong") -> Constraint:
+    """Make anchors coincide: ``align(a.right, b.left)``; ``offset`` adds a gap
+    between consecutive anchors (``anchors[i] == anchors[i+1] + offset``).
+    The first anchor's node is the subject (moves)."""
+    if len(anchors) < 2:
+        raise ValueError("align() needs at least two anchors")
+    if not all(isinstance(a, Anchor) for a in anchors):
+        raise TypeError("align() takes anchors, e.g. align(a.right, b.left)")
+    axis = anchors[0].axis
+    for a in anchors[1:]:
+        if a.axis != axis:
+            raise ValueError(f"align(): mixed axes ({anchors[0].describe()} vs {a.describe()})")
+    rels = [Rel(anchors[i], "==", anchors[i + 1], float(offset)) for i in range(len(anchors) - 1)]
+    return _mk("align", rels, strength, [anchors[0].node], [a.node for a in anchors[1:]])
+
+
+def _same(axis: str, items: Sequence[AnchorLike], anchor: str, strength: Any, kind: str) -> Constraint:
+    if len(items) < 2:
+        raise ValueError(f"{kind}() needs at least two items")
+    which = {"center": "center", "middle": "center", "cx": "center", "cy": "center",
+             "left": "start", "top": "start", "start": "start",
+             "right": "end", "bottom": "end", "end": "end"}.get(anchor)
+    if which is None:
+        raise ValueError(f"{kind}(): unknown anchor {anchor!r}")
+    anchors = [as_anchor(it, axis, which) for it in items]
+    # first item is the subject; reverse the relation so rel.a is the mover
+    rels = [Rel(anchors[0], "==", anchors[i]) for i in range(1, len(anchors))]
+    return _mk(kind, rels, strength, [anchors[0].node], [a.node for a in anchors[1:]])
+
+
+def same_x(*items: AnchorLike, anchor: str = "center", strength: Any = "strong") -> Constraint:
+    """Same x for nodes / anchor refs. ``anchor``: center|left|right."""
+    return _same("x", items, anchor, strength, "same_x")
+
+
+def same_y(*items: AnchorLike, anchor: str = "center", strength: Any = "strong") -> Constraint:
+    """Same y (horizontal alignment) for nodes / matrix rows / cells / ports.
+    ``anchor``: center|top|bottom."""
+    return _same("y", items, anchor, strength, "same_y")
+
+
+def _size_targets(nodes: Any) -> List[Any]:
+    """Nodes whose size a same_width / same_height sets (a deck → its front card)."""
+    return [getattr(n, "_size_proxy", None) or n for n in nodes]
+
+
+def same_width(*nodes: Any) -> Constraint:
+    """All nodes get the widest member's width (resolved before flex layout).
+
+    A widened node stays where its parent's cross-axis ``align`` puts it: in a
+    ``Col(align="center")`` (the default) it grows about its centre, so left edges no longer
+    line up; use ``Col(..., align="start")`` to keep them flush.
+    A :class:`~codefig.compose.Stacked` deck takes part through its **front card**
+    (v0.13.0) — the card the reader sees and the one its ports land on — so
+    ``same_width(deck, row)`` makes the visible card as wide as ``row``.
+    """
+    return Constraint(kind="same_width", size_axis="w", size_nodes=_size_targets(nodes),
+                      strength="required",
+                      desc="same_width(" + ", ".join(node_name(n) for n in nodes) + ")")
+
+
+def same_height(*nodes: Any) -> Constraint:
+    """All nodes get the tallest member's height (resolved before flex layout).
+
+    A :class:`~codefig.compose.Stacked` deck takes part through its front card."""
+    return Constraint(kind="same_height", size_axis="h", size_nodes=_size_targets(nodes),
+                      strength="required",
+                      desc="same_height(" + ", ".join(node_name(n) for n in nodes) + ")")
+
+
+def _relative(kind: str, a: AnchorLike, b: AnchorLike, gap: float, align_: Optional[str],
+              strength: Any, exact: bool) -> Constraint:
+    op = "==" if exact else ">="
+    if kind == "below":
+        rels = [Rel(as_anchor(a, "y", "start"), op, as_anchor(b, "y", "end"), gap)]
+        cross = "x"
+    elif kind == "above":
+        rels = [Rel(as_anchor(a, "y", "end"), "==" if exact else "<=", as_anchor(b, "y", "start"), -gap)]
+        cross = "x"
+    elif kind == "right_of":
+        rels = [Rel(as_anchor(a, "x", "start"), op, as_anchor(b, "x", "end"), gap)]
+        cross = "y"
+    else:  # left_of
+        rels = [Rel(as_anchor(a, "x", "end"), "==" if exact else "<=", as_anchor(b, "x", "start"), -gap)]
+        cross = "y"
+    if align_:
+        which = {"center": "center", "middle": "center", "left": "start", "top": "start",
+                 "start": "start", "right": "end", "bottom": "end", "end": "end"}[align_]
+        rels.append(Rel(as_anchor(a, cross, which), "==", as_anchor(b, cross, which)))
+    return _mk(kind, rels, strength, [_subject_node(a)], [_subject_node(b)])
+
+
+def below(a: AnchorLike, b: AnchorLike, gap: float = 8.0, *, align: Optional[str] = None,
+          strength: Any = "strong", exact: bool = True) -> Constraint:
+    """``a`` sits ``gap`` below ``b`` (TikZ ``below=gap of b``). ``exact=False`` → at least."""
+    return _relative("below", a, b, gap, align, strength, exact)
+
+
+def above(a: AnchorLike, b: AnchorLike, gap: float = 8.0, *, align: Optional[str] = None,
+          strength: Any = "strong", exact: bool = True) -> Constraint:
+    """``a`` sits ``gap`` above ``b`` (TikZ ``above=gap of b``). ``exact=False`` → at least."""
+    return _relative("above", a, b, gap, align, strength, exact)
+
+
+def right_of(a: AnchorLike, b: AnchorLike, gap: float = 8.0, *, align: Optional[str] = None,
+             strength: Any = "strong", exact: bool = True) -> Constraint:
+    """``a`` sits ``gap`` right of ``b`` (TikZ ``right=gap of b``)."""
+    return _relative("right_of", a, b, gap, align, strength, exact)
+
+
+def left_of(a: AnchorLike, b: AnchorLike, gap: float = 8.0, *, align: Optional[str] = None,
+            strength: Any = "strong", exact: bool = True) -> Constraint:
+    """``a`` sits ``gap`` left of ``b`` (TikZ ``left=gap of b``)."""
+    return _relative("left_of", a, b, gap, align, strength, exact)
+
+
+_SIDES = {
+    "right": (1, 0), "left": (-1, 0), "top": (0, -1), "bottom": (0, 1), "above": (0, -1),
+    "below": (0, 1), "top-right": (1, -1), "top-left": (-1, -1),
+    "bottom-right": (1, 1), "bottom-left": (-1, 1),
+}
+
+
+def place(node: Any, near: AnchorLike, side: str = "right", offset: float = 6.0, *,
+          align: Optional[str] = "center", within: Any = "parent",
+          strength: Any = "strong", obstacle: Any = None, inside: bool = False) -> Constraint:
+    """
+    Relative placement of ``node`` next to ``near`` (a node, matrix row/cell ref or port).
+
+    If ``node`` is not part of any layout tree it becomes an *overlay* (annotation)
+    drawn above the flex content of the scope; otherwise it is moved like
+    ``right_of``/``below``. ``side``: right|left|top|bottom|top-right|... ;
+    ``align`` (start|center|end) applies on the non-offset axis; ``align=None``
+    leaves that axis free (combine with e.g. ``same_y``).
+
+    ``within`` decides which container hosts an overlay: ``"parent"`` (default) —
+    the container holding ``near``, which grows so the annotation never spills
+    over its border; ``"scope"`` — the panel/diagram root; or an explicit node.
+
+    ``obstacle`` — the annotation's layering role (see :mod:`codefig.policy`):
+    ``None`` (default) keeps the class default (text annotations are *soft*:
+    edges may pass under them and are knocked out); ``True`` / ``"hard"`` makes
+    edges route around it; ``False`` / ``"none"`` lets edges and nodes pass under
+    it unchecked. Every role except ``"none"`` takes part in overlap resolution.
+    """
+    side_n = side.lower().replace("_", "-").replace(" ", "-")
+    if side_n not in _SIDES:
+        raise ValueError(f"place(): unknown side {side!r}")
+    sx, sy = _SIDES[side_n]
+    if inside and not (sx and sy):
+        raise ValueError("place(): inside=True requires top-right|top-left|bottom-right|bottom-left")
+    free_cross = align is None
+    which = {"center": "center", "middle": "center", "start": "start", "left": "start",
+             "top": "start", "end": "end", "right": "end", "bottom": "end"}[align or "center"]
+    rels: List[Rel] = []
+    if inside:
+        for ax, sign in (("x", sx), ("y", sy)):
+            edge = "end" if sign > 0 else "start"
+            rels.append(Rel(as_anchor(node, ax, edge), "==", as_anchor(near, ax, edge), -offset if sign > 0 else offset))
+    elif sx > 0:
+        rels.append(Rel(as_anchor(node, "x", "start"), "==", as_anchor(near, "x", "end"), offset))
+    elif sx < 0:
+        rels.append(Rel(as_anchor(node, "x", "end"), "==", as_anchor(near, "x", "start"), -offset))
+    elif not free_cross:
+        rels.append(Rel(as_anchor(node, "x", which), "==", as_anchor(near, "x", which)))
+    if inside:
+        pass
+    elif sy > 0:
+        rels.append(Rel(as_anchor(node, "y", "start"), "==", as_anchor(near, "y", "end"), offset))
+    elif sy < 0:
+        rels.append(Rel(as_anchor(node, "y", "end"), "==", as_anchor(near, "y", "start"), -offset))
+    elif not free_cross:
+        rels.append(Rel(as_anchor(node, "y", which), "==", as_anchor(near, "y", which)))
+    c = _mk("place", rels, strength, [node], [_subject_node(near)],
+            desc=f"place({node_name(node)}, near={node_name(_subject_node(near))}, side={side_n})")
+    c.overlay = node
+    c.place_spec = dict(near=near, sx=sx, sy=sy, offset=float(offset), which=which,
+                        within=within, obstacle=obstacle, inside=inside)
+    from .policy import normalize_role
+
+    role = normalize_role(obstacle)
+    try:
+        node._cf_obstacle_role = role
+        node._cf_obstacle = role != "none"
+    except Exception:  # pragma: no cover
+        pass
+    return c
+
+
+_ANCHOR_WHICH = {"center": "center", "middle": "center", "cx": "center", "cy": "center",
+                 "left": "start", "top": "start", "start": "start",
+                 "right": "end", "bottom": "end", "end": "end"}
+
+
+def distribute(*items: AnchorLike, axis: str = "x", gap: Optional[float] = None,
+               anchor: Optional[str] = None, between: Optional[Tuple[AnchorLike, AnchorLike]] = None,
+               strength: Any = "strong") -> Constraint:
+    """
+    Equal spacing of ``items`` along ``axis`` (in the given order), across
+    containers inside one panel.
+
+    * ``anchor=None`` (default): equal *gaps* edge-to-edge (draw.io "distribute
+      horizontally"); ``anchor="center"|"left"|...``: equal spacing of that anchor
+      (TikZ ``node distance`` measured between centers).
+    * ``gap=8``: every gap / spacing is exactly 8 instead of merely equal.
+    * ``between=(start, end)``: also spread from the ``start`` anchor/node to the
+      ``end`` one (gaps before the first and after the last item are equal too).
+
+    The inner items move; the first/last items (or the ``between`` refs) stay put.
+    """
+    ax = {"x": "x", "h": "x", "horizontal": "x", "y": "y", "v": "y", "vertical": "y"}.get(str(axis).lower())
+    if ax is None:
+        raise ValueError(f"distribute(): axis must be 'x' or 'y', got {axis!r}")
+    n = len(items)
+    if n < (2 if between is not None else 3) and gap is None:
+        raise ValueError("distribute() needs ≥3 items (or ≥2 with between=, or an explicit gap=)")
+    if n < 2:
+        raise ValueError("distribute() needs at least two items")
+    if anchor is not None and anchor not in _ANCHOR_WHICH:
+        raise ValueError(f"distribute(): unknown anchor {anchor!r}")
+
+    def lo(it: AnchorLike) -> Anchor:
+        return as_anchor(it, ax, _ANCHOR_WHICH[anchor] if anchor else "start")
+
+    def hi(it: AnchorLike) -> Anchor:
+        return as_anchor(it, ax, _ANCHOR_WHICH[anchor] if anchor else "end")
+
+    gaps: List[List[Tuple[float, Anchor]]] = []
+    if between is not None:
+        s0 = as_anchor(between[0], ax, "end") if not isinstance(between[0], Anchor) else between[0]
+        gaps.append([(1.0, lo(items[0])), (-1.0, s0)])
+    for i in range(n - 1):
+        gaps.append([(1.0, lo(items[i + 1])), (-1.0, hi(items[i]))])
+    if between is not None:
+        e0 = as_anchor(between[1], ax, "start") if not isinstance(between[1], Anchor) else between[1]
+        gaps.append([(1.0, e0), (-1.0, hi(items[-1]))])
+
+    rels: List[Any] = []
+    if gap is not None:
+        for g in gaps:
+            rels.append(LinRel(g, "==", float(gap)))
+    else:
+        for i in range(len(gaps) - 1):
+            rels.append(LinRel(gaps[i] + [(-k, a) for k, a in gaps[i + 1]], "==", 0.0))
+    nodes = [_subject_node(it) for it in items]
+    if between is not None:
+        subjects, refs = nodes, [_subject_node(between[0]), _subject_node(between[1])]
+    elif gap is not None:
+        subjects, refs = nodes[1:], nodes[:1]
+    else:
+        subjects, refs = nodes[1:-1], [nodes[0], nodes[-1]]
+    what = f"gap={gap:g}" if gap is not None else ("equal " + (f"{anchor} spacing" if anchor else "gaps"))
+    return _mk("distribute", rels, strength, subjects, refs,
+               desc=f"distribute({', '.join(node_name(x) for x in nodes)}, axis={ax}, {what})")
+
+
+def allow_overlap(*nodes: Any) -> Constraint:
+    """Mark nodes whose overlap is intentional (e.g. a label laid over a strip).
+    With one node it may overlap anything; with several, only each other."""
+    if not nodes:
+        raise ValueError("allow_overlap() needs at least one node")
+    return Constraint(kind="allow_overlap", subjects=list(nodes), strength="weak",
+                      desc="allow_overlap(" + ", ".join(node_name(n) for n in nodes) + ")")
+
+
+def no_overlap(a: Any, b: Any, axis: str, margin: float = 2.0, strength: Any = "required") -> Constraint:
+    """Keep ``b`` after ``a`` along ``axis`` (used by overlap resolution)."""
+    rel = Rel(as_anchor(b, axis, "start"), ">=", as_anchor(a, axis, "end"), float(margin))
+    return _mk("no_overlap", [rel], strength, [b], [a],
+               desc=f"no_overlap({node_name(a)} | {node_name(b)}, axis={axis})")
+
+
+def nudge(node: Any, dx: float = 0.0, dy: float = 0.0) -> Constraint:
+    """Small relative offset of ``node`` (and its subtree) on top of whatever the
+    flex layout and the other constraints decide. Parents still grow and siblings
+    are still pushed so the nudge never causes overlap/overflow."""
+    return Constraint(kind="nudge", subjects=[node], nudge=(float(dx), float(dy)),
+                      strength="required", desc=f"nudge({node_name(node)}, dx={dx:g}, dy={dy:g})")
+
+
+# --------------------------------------------------------------------------- scope mixin
+
+class ConstraintScope:
+    """Mixin for Figure / Panel / Diagram: ``scope.constrain(c1, c2, ...)``."""
+
+    def _cf_constraints(self) -> List[Constraint]:
+        lst = self.__dict__.get("_constraints")
+        if lst is None:
+            lst = []
+            self.__dict__["_constraints"] = lst
+        return lst
+
+    def constrain(self, *cs: Union[Constraint, Iterable[Constraint]]) -> List[Constraint]:
+        out: List[Constraint] = []
+        for c in cs:
+            if isinstance(c, Constraint):
+                out.append(c)
+            else:
+                for cc in c:
+                    if not isinstance(cc, Constraint):
+                        raise TypeError(f"constrain() expects Constraint objects, got {type(cc).__name__}")
+                    out.append(cc)
+        self._cf_constraints().extend(out)
+        return out
+
+    @property
+    def constraints(self) -> List[Constraint]:
+        return list(self._cf_constraints())
+
+
+# --------------------------------------------------------------------------- tree helpers
+
+def walk(node: Any) -> Iterable[Any]:
+    yield node
+    for k in node.children():
+        yield from walk(k)
+
+
+def _track_spec(item: Any) -> Tuple[Any, int]:
+    if isinstance(item, tuple):
+        m, off = item
+        return m, int(off)
+    return item, 0
+
+
+def align_columns(*items: Any, widths: str = "auto", square: Any = "auto",
+                  fit: str = "auto", strength: Any = "strong") -> Constraint:
+    """Share column tracks between stacked Matrix-like nodes (Matrix, heatmaps,
+    TokenStrip, Table): cell *i* of every member sits exactly above / below cell
+    *i* of the others, whatever container they live in.
+
+    ``align_columns(attn, strip)`` — pass ``(node, k)`` to start a member at track
+    *k* (``align_columns(table, (strip, 1))`` skips the table's header column).
+    Members also accept ``(node, offset, span)``, integer ``span >= 1``.
+    For example, ``align_columns(fine, (coarse, 0, 2))`` covers two reference
+    columns and their internal gap per coarse column. Offsets use reference tracks;
+    blocks must fit within the reference. Coarse gaps follow the reference gap.
+    Before layout every member's columns get a common pitch (``widths="auto"``: one
+    uniform pitch if any member has fixed-width cells, else per column; ``"uniform"`` /
+    ``"per_column"`` force it). Members' gaps are kept (pitch = cell width + gap) and
+    column *centres* coincide. ``square="auto"`` keeps square-cell matrices square.
+    Then a ``strength`` relation lines the first shared column up horizontally.
+
+    ``fit`` (v0.10.0, uniform pitch with fixed-width members such as heatmaps):
+    ``"auto"`` (default) lets content-sized members (token strips) give up their cell
+    padding first and grows the fixed cells by at most theme ``track_grow_max``
+    (1.4 ×), truncating longer labels with "…"; ``"shrink"`` never grows the fixed
+    cells; ``"grow"`` is the v0.9.0 behaviour (fixed cells grow to the widest label).
+    When members are consecutive children of one ``Col`` without an explicit ``gap=``,
+    the gap between them tightens to theme ``stack_gap`` so the stack reads as one
+    grid.
+    """
+    return _align_tracks("cols", items, widths, square, fit, strength)
+
+
+def align_rows(*items: Any, heights: str = "auto", square: Any = "auto",
+               fit: str = "auto", strength: Any = "strong") -> Constraint:
+    """Row counterpart of :func:`align_columns` (v0.10.0): side-by-side Matrix-like
+    nodes share row tracks, so row *i* of every member sits level with row *i* of the
+    others (``align_rows(heat_a, heat_b)``, ``align_rows(table, (heat, 1))`` to skip a
+    header row). ``heights`` is ``"auto"`` | ``"uniform"`` | ``"per_row"``; ``square``
+    and ``fit`` work as in ``align_columns``; consecutive members of one ``Row``
+    without an explicit ``gap=`` get theme ``stack_gap`` between them.
+
+    Members also accept ``(node, offset, span)``, integer ``span >= 1``.
+    ``align_rows(fine, (coarse, 0, 4))`` covers four reference rows and their
+    internal gaps per coarse row. Offsets use reference tracks; blocks must fit
+    within the reference. Coarse gaps follow the reference gap.
+    """
+    h = {"per_row": "per_column"}.get(heights, heights)
+    if heights not in ("auto", "uniform", "per_row"):
+        raise ValueError(f"align_rows(): heights={heights!r} (auto | uniform | per_row)")
+    return _align_tracks("rows", items, h, square, fit, strength)
+
+
+def _align_tracks(axis: str, items: Sequence[Any], widths: str, square: Any, fit: str,
+                  strength: Any) -> Constraint:
+    fname = "align_columns" if axis == "cols" else "align_rows"
+    spans = [it[2] if isinstance(it, tuple) and len(it) == 3 else 1 for it in items]
+    if any(type(v) is not int or v < 1 for v in spans):
+        raise ValueError(f"{fname}(): span must be an integer >= 1")
+    specs = [_track_spec(it[:2] if isinstance(it, tuple) and len(it) == 3 else it) for it in items]
+    if len(specs) < 2:
+        raise ValueError(f"{fname}() needs at least two matrices")
+    for m, off in specs:
+        if not hasattr(m, "_col_ws"):
+            raise TypeError(f"{fname}(): {node_name(m)} has no {'columns' if axis == 'cols' else 'rows'} "
+                            "(Matrix / TokenStrip / Table)")
+        if off < 0:
+            raise ValueError(f"{fname}(): track offsets must be >= 0")
+    if widths not in ("auto", "uniform", "per_column"):
+        raise ValueError(f"{fname}(): widths={widths!r} (auto | uniform | per_column)")
+    if fit not in ("auto", "grow", "shrink"):
+        raise ValueError(f"{fname}(): fit={fit!r} (auto | grow | shrink)")
+    m0, o0 = specs[0]
+
+    def count(m: Any) -> int:
+        return m.cols if axis == "cols" else m.rows
+
+    if spans[0] != 1:
+        raise ValueError(f"{fname}(): reference span must be 1")
+    for (m, off), span in zip(specs, spans):
+        if span > 1 and (off < o0 or off - o0 + count(m) * span > count(m0)):
+            raise ValueError(f"{fname}(): coarse member runs past reference tracks")
+    rels = []
+    for (m, off), span in zip(specs[1:], spans[1:]):
+        t = max(o0, off)  # first track both members cover
+        if t - off >= count(m) or t - o0 >= count(m0):
+            raise ValueError(f"{fname}(): {node_name(m)} shares no track with {node_name(m0)}")
+        if axis == "cols":
+            a = as_anchor(MatrixColRef(m, t - off), "x", "center")
+            b = as_anchor(MatrixColRef(m0, t - o0), "x", "center")
+        else:
+            a = as_anchor(MatrixRowRef(m, t - off), "y", "center")
+            b = as_anchor(MatrixRowRef(m0, t - o0), "y", "center")
+        if span > 1:
+            ref = MatrixColRef if axis == "cols" else MatrixRowRef
+            coord = "x" if axis == "cols" else "y"
+            a = as_anchor(ref(m, 0), coord, "start")
+            b = as_anchor(ref(m0, off - o0), coord, "start")
+        rels.append(Rel(a, "==", b))
+    c = Constraint(kind=fname, rels=rels, strength=strength,
+                   subjects=[m for m, _ in specs[1:]], refs=[m0], size_axis=axis,
+                   size_nodes=[m for m, _ in specs],
+                   desc=fname + "(" + ", ".join(node_name(m) for m, _ in specs) + ")")
+    c.tracks = {"tracks": specs, "widths": widths, "square": square, "fit": fit, "axis": axis, "spans": spans}
+    return c
+
+
+def _content_sized(m: Any, axis: str) -> bool:
+    if axis == "cols":
+        return m.cell_w == "content"
+    return m.cell_h == "content" or (m.cell_h is None and m.cell_w == "content")
+
+
+def _apply_tracks(c: Constraint) -> None:
+    spec = c.tracks or {}
+    tracks = spec.get("tracks", [])
+    mode, square = spec.get("widths", "auto"), spec.get("square", "auto")
+    fit, axis = spec.get("fit", "grow"), spec.get("axis", "cols")
+    key = "_track" if axis == "cols" else "_track_r"
+    spans = spec.get("spans", [1] * len(tracks))
+    if any(v > 1 for v in spans):
+        fine = [t for t, v in zip(tracks, spans) if v == 1]
+        _apply_tracks(Constraint(kind=c.kind, tracks={**spec, "tracks": fine, "spans": [1] * len(fine)}))
+        reference, origin = tracks[0]
+        sizes = reference._col_ws() if axis == "cols" else reference._row_hs()
+        for (m, off), span in zip(tracks, spans):
+            if span == 1:
+                continue
+            m.gap = reference.gap
+            n = m.cols if axis == "cols" else m.rows
+            own = [sum(sizes[off-origin+j*span:off-origin+(j+1)*span])
+                   + (span-1)*reference.gap for j in range(n)]
+            m.__dict__[key] = {"ws": own, "h": None, "fit": True}
+            m.__dict__.pop("_cw_cache", None)
+            m._measured = None
+        _tighten_stack(tracks, axis)
+        return
+    nat = []
+    for m, off in tracks:
+        m.__dict__.pop(key, None)
+        m.__dict__.pop("_cw_cache", None)
+        m._measured = None
+        if axis == "cols":
+            nat.append([w + m.gap for w in m._col_ws()])
+        else:
+            nat.append([h + m.gap for h in m._row_hs()])
+        m.__dict__.pop("_cw_cache", None)
+    if mode == "auto":
+        fixed = any(not _content_sized(m, axis) for m, _ in tracks)
+        mode = "uniform" if fixed else "per_column"
+    count = [(m.cols if axis == "cols" else m.rows) for m, _ in tracks]
+    n_tr = max(off + k for (m, off), k in zip(tracks, count))
+    pads: Dict[int, bool] = {}
+    if mode == "uniform":
+        p = max(max(ws) for ws in nat if ws)
+        fixed_p = [max(ws) for (m, _), ws in zip(tracks, nat) if ws and not _content_sized(m, axis)]
+        if fit != "grow" and fixed_p:
+            pf = max(fixed_p)
+            th = tracks[0][0].theme
+            cap = pf if fit == "shrink" else pf * float(getattr(th, "track_grow_max", 1.5))
+            p = max(pf, min(p, cap))  # keep natural padding while it fits the cap
+            for i, ((m, _), ws) in enumerate(zip(tracks, nat)):
+                if _content_sized(m, axis) and ws and max(ws) > p + 1e-6:
+                    pads[i] = True  # gives up padding / truncates
+        pitch = [p] * n_tr
+    else:
+        pitch = [0.0] * n_tr
+        for (m, off), ws in zip(tracks, nat):
+            for i, w in enumerate(ws):
+                pitch[off + i] = max(pitch[off + i], w)
+    for i, ((m, off), ws) in enumerate(zip(tracks, nat)):
+        k = count[i]
+        own = [max(0.0, pitch[off + j] - m.gap) for j in range(k)]
+        other = None
+        is_sq = m.cell_w is None and m.cell_h is None
+        if (square is True or (square == "auto" and is_sq)) and own and len(set(own)) == 1:
+            other = max(own[0], max(m._row_hs() if axis == "cols" else m._col_ws()))
+            if axis == "rows" and hasattr(m, "_label_w"):
+                # v0.11.0: square cells that follow a row pitch stay wide enough for
+                # their labels (at most theme track_grow_max wider than tall)
+                need = max((m._label_w(r, c_) for r in range(m.rows) for c_ in range(m.cols)),
+                           default=0.0) + m.theme.L(2.0)
+                cap = other * float(getattr(m.theme, "track_grow_max", 1.4))
+                other = max(other, min(need, cap))
+        prev = m.__dict__.get(key)
+        if prev is not None:  # member of several groups on this axis
+            own = [max(a, b) for a, b in zip(own, prev["ws"])]
+            other = max(other or 0.0, prev["h"] or 0.0) or None
+        m.__dict__[key] = {"ws": own, "h": other, "fit": bool(pads.get(i)) or (prev or {}).get("fit", False)}
+        m._measured = None
+    _tighten_stack(tracks, axis)
+
+
+def _tighten_stack(tracks: Sequence[Tuple[Any, int]], axis: str) -> None:
+    """Consecutive members inside one Col (columns) / Row (rows) whose ``gap=`` was not
+    given: the gap between them becomes theme ``stack_gap``."""
+    from .node import Container
+
+    want = "column" if axis == "cols" else "row"
+    members = {id(m) for m, _ in tracks}
+    seen = set()
+    for m, _ in tracks:
+        par = getattr(m, "parent", None)
+        if not isinstance(par, Container) or par.direction != want or id(par) in seen:
+            continue
+        seen.add(id(par))
+        kids = list(par._kids)
+        g = float(getattr(m.theme, "stack_gap", m.theme.L(6.0)))
+        pair = par.__dict__.setdefault("_pair_gap", {})
+        for j in range(len(kids) - 1):
+            if id(kids[j]) in members and id(kids[j + 1]) in members:
+                pair[j] = min(g, float(par.gap))
+
+
+def invalidate_tree(root: Any) -> None:
+    for n in walk(root):
+        n._measured = None
+
+
+def apply_size_constraints(root: Any, constraints: Sequence[Constraint]) -> None:
+    """Resolve same_width / same_height before flex: every member gets the max size."""
+    for n in walk(root):
+        n._cmin_w = 0.0
+        n._cmin_h = 0.0
+        n.__dict__.pop("_track", None)
+        n.__dict__.pop("_track_r", None)
+    track_cs = [c for c in constraints if c.size_axis in ("cols", "rows")]
+    for c in track_cs:
+        _apply_tracks(c)
+    if track_cs:
+        invalidate_tree(root)
+    size_cs = [c for c in constraints if c.size_axis in ("w", "h")]
+    if not size_cs:
+        return
+    invalidate_tree(root)
+    for c in size_cs:
+        sizes = [n.measure() for n in c.size_nodes]
+        if c.size_axis == "w":
+            m = max(s[0] for s in sizes)
+            for n in c.size_nodes:
+                n._cmin_w = max(getattr(n, "_cmin_w", 0.0), m)
+        else:
+            m = max(s[1] for s in sizes)
+            for n in c.size_nodes:
+                n._cmin_h = max(getattr(n, "_cmin_h", 0.0), m)
+        invalidate_tree(root)
+
+
+def translate_tree(node: Any, dx: float, dy: float) -> None:
+    for n in walk(node):
+        n.geom.x += dx
+        n.geom.y += dy
+
+
+def _bands(node: Any) -> Tuple[float, float, float, float]:
+    """Inner padding band (left, top, right, bottom) a child must stay inside."""
+    from .edges import Diagram
+    from .node import Container
+    from .primitives import CircleHighlight
+
+    if isinstance(node, Container):
+        pt, pr, pb, pl = node.padding
+        th = node._title_h() if node.title else 0.0
+        top = pt + (th if node.title and node.title_pos == "top" else 0.0)
+        if node.title and node.title_pos == "inside-top":
+            top += node.theme.font_size + node.title_gap
+        bot = pb + (th if node.title and node.title_pos == "bottom" else 0.0)
+        return pl, top, pr, bot
+    if isinstance(node, Diagram):
+        l, t, r, b = node._loop_margins()
+        return l, t, r, b
+    if isinstance(node, CircleHighlight):
+        p = node.hl_pad
+        return p, p, p, p
+    return 0.0, 0.0, 0.0, 0.0
+
+
+# --------------------------------------------------------------------------- solver
+
+@dataclass
+class SolveResult:
+    overlays: List[Any]
+    shifts: Dict[int, Tuple[float, float]]
+    growth: Dict[int, Tuple[float, float, float, float]]
+    bbox: Tuple[float, float, float, float]
+
+
+def _layout_overlay(c: Constraint) -> None:
+    node = c.overlay
+    spec = c.place_spec or {}
+    w, h = node.measure()
+    near = spec["near"]
+    off = spec["offset"]
+    which = spec["which"]
+    f = _WHICH_FRAC[which]
+    nl, nr = as_anchor(near, "x", "start").value(), as_anchor(near, "x", "end").value()
+    nt, nb = as_anchor(near, "y", "start").value(), as_anchor(near, "y", "end").value()
+    sx, sy = spec["sx"], spec["sy"]
+    if spec.get("inside"):
+        x = nr - off - w if sx > 0 else nl + off
+        y = nb - off - h if sy > 0 else nt + off
+        node.layout(x, y, w, h)
+        return
+    if sx > 0:
+        x = nr + off
+    elif sx < 0:
+        x = nl - off - w
+    else:
+        x = nl + (nr - nl) * f - w * f
+    if sy > 0:
+        y = nb + off
+    elif sy < 0:
+        y = nt - off - h
+    else:
+        y = nt + (nb - nt) * f - h * f
+    node.layout(x, y, w, h)
+
+
+def _unit() -> str:
+    from .styles import length_unit
+
+    return length_unit()
+
+
+def solve_constraints(root: Any, constraints: Sequence[Constraint], *, warn: bool = True) -> SolveResult:
+    """
+    Apply relational constraints to an already flex-laid-out tree rooted at ``root``.
+    Mutates geometry in place (translations + container growth) and returns the
+    overlays and the final content bbox. See module docstring for the model.
+    """
+    from .node import Container, Grid
+
+    if _kiwi is None:  # pragma: no cover
+        raise ImportError("codefig constraints need kiwisolver: pip install kiwisolver")
+
+    cons = [c for c in constraints
+            if (not c.size_axis or c.rels) and c.kind != "allow_overlap"]
+    g0 = root.geom
+    if not cons:
+        return SolveResult([], {}, {}, (g0.x, g0.y, g0.w, g0.h))
+
+    # -- tree maps -----------------------------------------------------------
+    parent: Dict[int, Any] = {}
+    in_tree: Dict[int, Any] = {}
+    for n in walk(root):
+        in_tree[id(n)] = n
+        for k in n.children():
+            parent[id(k)] = n
+
+    overlays: List[Any] = []
+    for c in cons:
+        if c.overlay is not None and id(c.overlay) not in in_tree:
+            if all(c.overlay is not o for o in overlays):
+                overlays.append(c.overlay)
+                _layout_overlay(c)
+            else:
+                _layout_overlay(c)
+    hosted: Dict[int, List[Any]] = {}
+    for o in overlays:
+        for n in walk(o):
+            in_tree[id(n)] = n
+        for n in walk(o):
+            for k in n.children():
+                parent[id(k)] = n
+        spec = next(c.place_spec for c in cons if c.overlay is o)
+        within = spec.get("within", "parent")
+        if within == "scope" or within is None:
+            host = root
+        elif within == "parent":
+            nn = _subject_node(spec["near"])
+            host = parent.get(id(nn), root) if nn is not root else root
+            while host is not root and not list(host.children()):
+                host = parent.get(id(host), root)
+        else:
+            host = within
+            if id(host) not in in_tree:
+                raise ConstraintConflictError(f"place(within={node_name(host)}): not in this panel")
+        parent[id(o)] = host
+        hosted.setdefault(id(host), []).append(o)
+
+    # -- referenced nodes ---------------------------------------------------
+    referenced: List[Any] = []
+    for c in cons:
+        for n in c.nodes():
+            if id(n) not in in_tree:
+                raise ConstraintConflictError(
+                    f"{c.describe()}: node {node_name(n)} is not part of this panel/diagram "
+                    f"(constraints cannot span panels; overlays must be placed with place())"
+                )
+            referenced.append(n)
+
+    involved: Dict[int, Any] = {}
+
+    def add_chain(n: Any) -> None:
+        while n is not None and id(n) not in involved:
+            involved[id(n)] = n
+            n = parent.get(id(n))
+
+    add_chain(root)
+    for n in referenced:
+        add_chain(n)
+    # containers on a referenced chain get containment / sibling invariants;
+    # their direct children are involved (movable as rigid blocks) but a child
+    # container off the chain is not opened up (its kids have no variables).
+    chain_ids = set(involved)
+    for n in list(involved.values()):
+        kids = list(n.children()) + hosted.get(id(n), [])
+        for k in kids:
+            involved[id(k)] = k
+
+    nudges: Dict[int, Tuple[float, float]] = {}
+    for c in cons:
+        if c.kind == "nudge":
+            n = c.subjects[0]
+            ox, oy = nudges.get(id(n), (0.0, 0.0))
+            nudges[id(n)] = (ox + c.nudge[0], oy + c.nudge[1])
+
+    ref_ids = {id(n) for c in cons for n in c.refs}
+    subj_ids = {id(n) for c in cons if c.kind != "nudge" for n in c.subjects}
+
+    # -- variables & flex snapshot -------------------------------------------
+    V: Dict[int, Dict[str, Any]] = {}
+    flex: Dict[int, Tuple[float, float, float, float]] = {}
+    for nid, n in involved.items():
+        nm = node_name(n)
+        d = {"dx": _kiwi.Variable(f"{nm}.dx"), "dy": _kiwi.Variable(f"{nm}.dy")}
+        has_kids = nid in chain_ids and (bool(list(n.children())) or n is root or id(n) in hosted)
+        if has_kids:
+            for gname in ("gl", "gr", "gt", "gb"):
+                d[gname] = _kiwi.Variable(f"{nm}.{gname}")
+        V[nid] = d
+        g = n.geom
+        flex[nid] = (g.x, g.y, g.w, g.h)
+
+    def chain(n: Any) -> List[Any]:
+        out = []
+        while n is not None:
+            out.append(n)
+            if n is root:
+                break
+            n = parent.get(id(n))
+        return out
+
+    def T(n: Any, axis: str):
+        key = "dx" if axis == "x" else "dy"
+        terms = [V[id(a)][key] for a in chain(n) if id(a) in V]
+        expr = 0.0
+        for t in terms:
+            expr = expr + t
+        return expr
+
+    def nud(n: Any, axis: str, inclusive: bool) -> float:
+        idx = 0 if axis == "x" else 1
+        tot = 0.0
+        for a in chain(n):
+            if a is n and not inclusive:
+                continue
+            tot += nudges.get(id(a), (0.0, 0.0))[idx]
+        return tot
+
+    def growth(n: Any, axis: str, side: str):
+        d = V.get(id(n), {})
+        key = {("x", "lo"): "gl", ("x", "hi"): "gr", ("y", "lo"): "gt", ("y", "hi"): "gb"}[(axis, side)]
+        return d.get(key)
+
+    def full_lo(n: Any, axis: str):
+        x, y, w, h = flex[id(n)]
+        base = x if axis == "x" else y
+        e = T(n, axis) + base + nud(n, axis, True)
+        gv = growth(n, axis, "lo")
+        return e - gv if gv is not None else e
+
+    def full_hi(n: Any, axis: str):
+        x, y, w, h = flex[id(n)]
+        base = (x + w) if axis == "x" else (y + h)
+        e = T(n, axis) + base + nud(n, axis, True)
+        gv = growth(n, axis, "hi")
+        return e + gv if gv is not None else e
+
+    def anchor_expr(a: Anchor, final: bool = False):
+        # user relations see positions *before* the node's own nudge; no_overlap
+        # (final=True) must see where the node really ends up
+        n = a.node
+        e = T(n, a.axis) + (a.base_value() + a.offset) + nud(n, a.axis, final)
+        if a.frac is not None and a.getter is None:
+            lo, hi = growth(n, a.axis, "lo"), growth(n, a.axis, "hi")
+            if lo is not None:
+                e = e - lo * (1.0 - a.frac) + hi * a.frac
+        return e
+
+    # -- structural (required) -------------------------------------------------
+    structural: List[Tuple[Any, str]] = []
+    smeta: Dict[int, Tuple[str, Any, Any]] = {}  # v0.13.0: why-dropped diagnostics
+    REQ = _kiwi.strength.required
+    rv = V[id(root)]
+    structural.append(((rv["dx"] + 0.0 == 0.0) | REQ, f"{node_name(root)} (scope root) is fixed"))
+    structural.append(((rv["dy"] + 0.0 == 0.0) | REQ, f"{node_name(root)} (scope root) is fixed"))
+    for nid, d in V.items():
+        for gname in ("gl", "gr", "gt", "gb"):
+            if gname in d:
+                structural.append(((d[gname] + 0.0 >= 0.0) | REQ, f"{node_name(involved[nid])} cannot shrink"))
+
+    for nid, p in involved.items():
+        if nid not in chain_ids:
+            continue
+        kids = list(p.children())
+        kids_all = kids + hosted.get(nid, [])
+        if not kids_all:
+            continue
+        bl, bt, br, bb = _bands(p)
+        px, py, pw, ph = flex[nid]
+        pname = node_name(p)
+        for k in kids_all:
+            kx, ky, kw, kh = flex[id(k)]
+            is_ov = any(k is o for o in overlays)
+            dl = bl if is_ov else min(kx - px, bl)
+            dt = bt if is_ov else min(ky - py, bt)
+            dr = br if is_ov else min((px + pw) - (kx + kw), br)
+            db = bb if is_ov else min((py + ph) - (ky + kh), bb)
+            kname = node_name(k)
+            inside = [
+                ((full_lo(k, "x") - full_lo(p, "x") >= dl) | REQ, f"{kname} stays inside {pname} (left)"),
+                ((full_lo(k, "y") - full_lo(p, "y") >= dt) | REQ, f"{kname} stays inside {pname} (top)"),
+                ((full_hi(p, "x") - full_hi(k, "x") >= dr) | REQ, f"{kname} stays inside {pname} (right)"),
+                ((full_hi(p, "y") - full_hi(k, "y") >= db) | REQ, f"{kname} stays inside {pname} (bottom)"),
+            ]
+            for kk, _d in inside:
+                smeta[id(kk)] = ("inside", p, k)
+            structural += inside
+        # sibling non-overlap along main axis
+        pairs: List[Tuple[Any, Any, str]] = []
+        if isinstance(p, Grid):
+            cols = p.cols
+            for i, k in enumerate(kids):
+                r, cidx = divmod(i, cols)
+                if cidx + 1 < cols and i + 1 < len(kids):
+                    pairs.append((k, kids[i + 1], "x"))
+                if i + cols < len(kids):
+                    pairs.append((k, kids[i + cols], "y"))
+        elif isinstance(p, Container):
+            axis = "x" if p.direction == "row" else "y"
+            for i in range(len(kids) - 1):
+                pairs.append((kids[i], kids[i + 1], axis))
+        gap = float(getattr(p, "gap", 0.0) or 0.0)
+        for a, b, axis in pairs:
+            ax, ay, aw, ah = flex[id(a)]
+            bx, by, bw, bh = flex[id(b)]
+            d0 = (bx - (ax + aw)) if axis == "x" else (by - (ay + ah))
+            kk = (full_lo(b, axis) - full_hi(a, axis) >= min(d0, gap)) | REQ
+            smeta[id(kk)] = ("order", p, (a, b, axis, min(d0, gap)))
+            structural.append((
+                kk, f"{pname} keeps {node_name(a)} before {node_name(b)} (no sibling overlap)",
+            ))
+
+    # -- stays (flex result) ---------------------------------------------------
+    stays: List[Any] = []
+    for nid, d in V.items():
+        if nid in ref_ids and nid not in subj_ids:
+            w_move = 10.0
+        elif nid in subj_ids:
+            w_move = 1.0
+        else:
+            w_move = 2.0
+        st = _kiwi.strength.create(0, 0, w_move)
+        # a nudged node must not "cancel" its nudge to save sibling moves:
+        # its own stay on the nudged axis is medium (user strong/medium still win)
+        nx, ny = nudges.get(nid, (0.0, 0.0))
+        stays.append((d["dx"] + 0.0 == 0.0) | (_kiwi.strength.medium if nx else st))
+        stays.append((d["dy"] + 0.0 == 0.0) | (_kiwi.strength.medium if ny else st))
+        for gname in ("gl", "gr", "gt", "gb"):
+            if gname in d:
+                stays.append((d[gname] + 0.0 == 0.0) | _kiwi.strength.create(0, 0, 1.5))
+
+    # -- user constraints --------------------------------------------------------
+    def rel_kiwi(r: Any, strength: float, final: bool = False):
+        if isinstance(r, LinRel):
+            lhs = 0.0
+            for coef, a in r.terms:
+                lhs = lhs + anchor_expr(a, final) * coef
+            lhs = lhs + 0.0
+            if r.op == "==":
+                k = lhs == r.const
+            elif r.op == ">=":
+                k = lhs >= r.const
+            else:
+                k = lhs <= r.const
+            return k | strength
+        lhs = anchor_expr(r.a, final)
+        rhs = anchor_expr(r.b, final) + r.const
+        if r.op == "==":
+            k = lhs == rhs
+        elif r.op == ">=":
+            k = lhs >= rhs
+        else:
+            k = lhs <= rhs
+        return k | strength
+
+    user_req: List[Tuple[Constraint, List[Any]]] = []
+    user_soft: List[Tuple[Constraint, List[Any]]] = []
+    for c in cons:
+        if not c.rels:
+            continue
+        s = _kiwi_strength(c.strength)
+        ks = [rel_kiwi(r, s, c.kind == "no_overlap") for r in c.rels]
+        (user_req if s >= _kiwi.strength.required else user_soft).append((c, ks))
+
+    solver = _kiwi.Solver()
+    for k, _desc in structural:
+        solver.addConstraint(k)
+    added_req: List[Tuple[Constraint, List[Any]]] = []
+    for c, ks in user_req:
+        try:
+            for k in ks:
+                solver.addConstraint(k)
+        except _kiwi.UnsatisfiableConstraint:
+            raise ConstraintConflictError(_explain_conflict(c, ks, added_req, structural)) from None
+        added_req.append((c, ks))
+    for c, ks in user_soft:
+        for k in ks:
+            solver.addConstraint(k)
+    for k in stays:
+        solver.addConstraint(k)
+    solver.updateVariables()
+
+    # -- apply -----------------------------------------------------------------
+    shifts: Dict[int, Tuple[float, float]] = {}
+    grow: Dict[int, Tuple[float, float, float, float]] = {}
+
+    def val(v: Any) -> float:
+        x = float(v.value())
+        return 0.0 if abs(x) < 1e-7 else x
+
+    def apply(n: Any, ax: float, ay: float) -> None:
+        nid = id(n)
+        if nid in V:
+            nx, ny = nudges.get(nid, (0.0, 0.0))
+            ax += val(V[nid]["dx"]) + nx
+            ay += val(V[nid]["dy"]) + ny
+        g = n.geom
+        g.x += ax
+        g.y += ay
+        if nid in V and "gl" in V[nid]:
+            gl, gr, gt, gb = (val(V[nid][k]) for k in ("gl", "gr", "gt", "gb"))
+            if gl or gr or gt or gb:
+                g.x -= gl
+                g.w += gl + gr
+                g.y -= gt
+                g.h += gt + gb
+                grow[nid] = (gl, gr, gt, gb)
+        if abs(ax) > 1e-7 or abs(ay) > 1e-7:
+            shifts[nid] = (ax, ay)
+        for k in list(n.children()) + hosted.get(nid, []):
+            apply(k, ax, ay)
+
+    apply(root, 0.0, 0.0)
+    # composites whose decoration depends on a child's position (Repeat frames …)
+    # re-sync after their children moved
+    for n in involved.values():
+        hook = getattr(n, "_after_solve", None)
+        if hook is not None:
+            hook()
+
+    # -- verify soft constraints --------------------------------------------------
+    def own_nudge(a: Anchor) -> float:
+        return nudges.get(id(a.node), (0.0, 0.0))[0 if a.axis == "x" else 1]
+
+    def residual(r: Any) -> float:
+        # relations see positions *before* the subject's own nudge
+        if isinstance(r, LinRel):
+            d = sum(k * (a.value() - own_nudge(a)) for k, a in r.terms) - r.const
+            if r.op == "==":
+                return abs(d)
+            return max(0.0, -d) if r.op == ">=" else max(0.0, d)
+        d = (r.a.value() - own_nudge(r.a)) - (r.b.value() - own_nudge(r.b) + r.const)
+        if r.op == "==":
+            return abs(d)
+        return max(0.0, -d) if r.op == ">=" else max(0.0, d)
+
+    for c, _ks in (user_soft if warn else []):
+        if c.kind == "no_overlap":
+            continue
+        worst = max((residual(r) for r in c.rels), default=0.0)
+        if worst > 0.5:
+            # v0.13.0: say *what* blocked it and how to fix it; warn once per constraint
+            # (lint lays a figure out several times)
+            if getattr(c, "_cf_warned", False):
+                continue
+            c._cf_warned = True
+            why = _why_dropped(c, [rel_kiwi(r, REQ) for r in c.rels], structural, smeta,
+                               [(o, [rel_kiwi(r, REQ) for r in o.rels]) for o, _oks in user_req + user_soft
+                                if o is not c and o.kind != "no_overlap"])
+            warnings.warn(
+                f"constraint {c.describe()} [{c.strength}] dropped: off by {worst:.1f}{_unit()} — {why}",
+                ConstraintWarning,
+                stacklevel=3,
+            )
+    if warn:
+        _warn_left_behind(cons, parent, shifts)
+
+    g = root.geom
+    bx0, by0, bx1, by1 = g.x, g.y, g.x + g.w, g.y + g.h
+    for o in overlays:
+        og = o.geom
+        bx0, by0 = min(bx0, og.x), min(by0, og.y)
+        bx1, by1 = max(bx1, og.x + og.w), max(by1, og.y + og.h)
+    return SolveResult(overlays, shifts, grow, (bx0, by0, bx1 - bx0, by1 - by0))
+
+
+def _satisfiable(ks: Sequence[Any]) -> bool:
+    s = _kiwi.Solver()
+    try:
+        for k in ks:
+            s.addConstraint(k)
+    except _kiwi.UnsatisfiableConstraint:
+        return False
+    return True
+
+
+def _why_dropped(c: Constraint, req_ks: List[Any], structural: List[Tuple[Any, str]],
+                 smeta: Dict[int, Tuple[str, Any, Any]],
+                 others: List[Tuple[Constraint, List[Any]]]) -> str:
+    """v0.13.0: explain which layout invariant / other constraint beat a soft
+    constraint, naming the container and the usual fix."""
+    from .node import Container, Grid as _G
+
+    struct_ks = [k for k, _ in structural]
+    pre = ""
+    if _satisfiable(struct_ks + req_ks):
+        for oc, oks in others:
+            if not _satisfiable(struct_ks + req_ks + oks):
+                pre = f"together with {oc.describe()} [{oc.strength}] it is impossible; "
+                req_ks = req_ks + oks
+                break
+        else:
+            return "overridden by stronger constraints (no single culprit found)"
+        if not _satisfiable(req_ks):
+            return pre + "drop one of them or make them agree"
+    hints: List[str] = []
+    for i, (k, desc) in enumerate(structural):
+        rest = struct_ks[:i] + struct_ks[i + 1:]
+        if not _satisfiable(rest + req_ks):
+            continue
+        meta = smeta.get(id(k))
+        if meta is None:
+            hints.append(f"{desc} — constrain nodes inside it, not the scope root")
+        elif meta[0] == "order":
+            p, (a, b, axis, gap) = meta[1], meta[2]
+            kind = "Grid" if isinstance(p, _G) else ("Row" if axis == "x" else "Col")
+            other = "Row" if axis == "y" else "Col"
+            g = f" with gap {gap:g}{_unit()}" if gap > 0.5 else ""
+            hints.append(
+                f"{node_name(p)} stacks {node_name(a)} and {node_name(b)} along {axis}{g}, so they cannot "
+                f"share that {axis} or overlap — put them in a {other} (or a Diagram) instead"
+                + (f" (if they only need to come closer, lower the {kind}'s gap=)" if gap > 0.5 else "")
+                if kind != "Grid" else
+                f"{node_name(p)} keeps {node_name(a)} and {node_name(b)} in grid order along {axis} — "
+                f"constrain the whole Grid, or build the rows as Rows")
+        else:
+            p, child = meta[1], meta[2]
+            al = getattr(p, "align", None)
+            al_s = f" and its align={al!r} places {node_name(child)}" if al not in (None, "start") else ""
+            hints.append(
+                f"{node_name(child)} must stay inside {node_name(p)}{al_s} — constrain {node_name(p)} "
+                f"itself" + (", or give it align='start'" if al_s else "")
+                + " (a container does not grow to follow a constrained child)")
+        if len(hints) >= 2:
+            break
+    if not hints:
+        hints.append("container containment / sibling order (several invariants together)")
+    return pre + "blocked by layout invariant: " + "; ".join(dict.fromkeys(hints))
+
+
+def _warn_left_behind(cons: Sequence[Constraint], parent: Dict[int, Any],
+                      shifts: Dict[int, Tuple[float, float]]) -> None:
+    """v0.13.0: a constraint that moves one *cell* of a Grid leaves its row (or
+    column) neighbours — typically its label — behind.  Warn once."""
+    from .node import Grid as _G
+
+    for c in cons:
+        if c.kind in ("nudge", "no_overlap") or getattr(c, "_cf_left_warned", False):
+            continue
+        for n in c.subjects + c.refs:
+            p = parent.get(id(n))
+            if not isinstance(p, _G):
+                continue
+            kids = list(p.children())
+            if n not in kids:
+                continue
+            i = kids.index(n)
+            sx, sy = shifts.get(id(n), (0.0, 0.0))
+            ps = shifts.get(id(p), (0.0, 0.0))
+            r, col = divmod(i, p.cols)
+            for axis, own, mates in (("y", sy - ps[1], [k for j, k in enumerate(kids) if j // p.cols == r and j != i]),
+                                     ("x", sx - ps[0], [k for j, k in enumerate(kids) if j % p.cols == col and j != i])):
+                if abs(own) <= 1.0 or not mates:
+                    continue
+                left = [m for m in mates if abs(shifts.get(id(m), (0.0, 0.0))[0 if axis == "x" else 1]
+                                                - (ps[0] if axis == "x" else ps[1]) - own) > 1.0]
+                if left:
+                    c._cf_left_warned = True
+                    warnings.warn(
+                        f"constraint {c.describe()} moved {node_name(n)} {own:+.1f}{_unit()} in {axis} out of its "
+                        f"{node_name(p)} {'row' if axis == 'y' else 'column'}; its neighbour(s) "
+                        f"{', '.join(node_name(m) for m in left[:3])} stayed behind — constrain them too "
+                        f"(e.g. same_{axis}({node_name(left[0])}, {node_name(n)})) or group the label and "
+                        f"the node in a {'Row' if axis == 'y' else 'Col'}",
+                        ConstraintWarning, stacklevel=4)
+                    break
+            if getattr(c, "_cf_left_warned", False):
+                break
+
+
+def _explain_conflict(c: Constraint, ks: List[Any], earlier: List[Tuple[Constraint, List[Any]]],
+                      structural: List[Tuple[Any, str]]) -> str:
+    names = ", ".join(node_name(n) for n in c.nodes())
+    head = f"unsatisfiable required constraint {c.describe()} (nodes: {names})"
+    struct_ks = [k for k, _ in structural]
+    if not _satisfiable(struct_ks + ks):
+        culprits = []
+        for i, (_k, desc) in enumerate(structural):
+            rest = struct_ks[:i] + struct_ks[i + 1:]
+            if _satisfiable(rest + ks):
+                culprits.append(desc)
+            if len(culprits) >= 3:
+                break
+        why = "; ".join(dict.fromkeys(culprits)) or "container containment / sibling order"
+        return f"{head}: conflicts with layout invariant(s): {why}"
+    for pc, pks in earlier:
+        if not _satisfiable(struct_ks + pks + ks):
+            pn = ", ".join(node_name(n) for n in pc.nodes())
+            return f"{head}: conflicts with required constraint {pc.describe()} (nodes: {pn})"
+    return f"{head}: conflicts with the combination of earlier required constraints"
+
+
+__all__ = [
+    "Anchor", "Anchorable", "Constraint", "ConstraintConflictError", "ConstraintWarning",
+    "ConstraintScope", "MatrixRowRef", "MatrixColRef", "MatrixCellRef",
+    "align", "same_x", "same_y", "same_width", "same_height",
+    "below", "above", "right_of", "left_of", "place", "nudge", "distribute",
+    "allow_overlap", "no_overlap", "LinRel",
+    "solve_constraints", "apply_size_constraints", "node_name", "align_columns", "align_rows",
+]