codefig 0.17.0__py3-none-any.whl

codefig/edges.py

@@ -0,0 +1,2824 @@
+"""Port anchors, styled Edges, Diagram overlay: lanes, obstacles, bundling."""
+
+from __future__ import annotations
+
+from collections import defaultdict
+from dataclasses import dataclass
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from .constraints import ConstraintScope
+from .node import BoxGeom, Node
+from .styles import (
+    DEFAULT_THEME,
+    current_theme,
+    themed,
+    ResolvedEdgeStyle,
+    Theme,
+    resolve_edge_style,
+)
+from .textutil import measure_text
+
+Side = str  # left|right|top|bottom|center
+Pt = Tuple[float, float]
+
+
+def _stub(x: float, y: float, direction: str, length: float) -> Pt:
+    if direction == "right":
+        return x + length, y
+    if direction == "left":
+        return x - length, y
+    if direction == "down":
+        return x, y + length
+    if direction == "up":
+        return x, y - length
+    return x + length, y
+
+
+@dataclass
+class Port:
+    """Symbolic anchor on a laid-out node (no absolute author coordinates)."""
+
+    node: Node
+    kind: str  # side | row | col | cell | cell_range | custom
+    side: Side = "right"
+    index: int = 0
+    col_index: int = 0
+    end_index: int = 0
+    at: float = 0.5
+    align_ref: Any = None
+    snap: bool = False
+    offset: float = 0.0
+    slide: float = 0.0  # v0.11.0: an explicit at= may move by up to this much
+    # v0.13.0: Edge(parallel=N) — leg i of n, spread across the overlap with ``peer``
+    peer: Any = None
+    par_i: int = 0
+    par_n: int = 1
+    par_gap: Optional[float] = None
+
+    def resolve(self) -> Tuple[float, float, str]:
+        x, y, d = self._resolve()
+        if self.offset and self.kind in ("side", "custom"):
+            # v0.13.0: offset= shifts a side port along its side (pt), e.g. three
+            # parallel arrows port("top", offset=-6/0/6)
+            if d in ("up", "down"):
+                x += self.offset
+            else:
+                y += self.offset
+        return x, y, d
+
+    def _resolve(self) -> Tuple[float, float, str]:
+        node = self.node
+        if self.kind == "parallel":
+            return resolve_parallel_port(self)
+        if self.kind == "aligned":
+            return on_outline(node, self.side, resolve_aligned_port(self))
+        if self.kind == "side":
+            if self.side == "auto":  # resolved against the other end by Edge.endpoints
+                g = node.geom
+                return g.cx, g.cy, "right"
+            custom = getattr(node, "resolve_port_side", None)
+            if custom is not None:  # e.g. Stacked: in line with the front card
+                return custom(self.side, self.at)
+            return on_outline(node, self.side, resolve_side_port(node, self.side, self.at))
+        if self.kind == "row" and hasattr(node, "resolve_row_port"):
+            return node.resolve_row_port(self.index, self.side)  # type: ignore[attr-defined]
+        if self.kind == "col" and hasattr(node, "resolve_col_port"):
+            return node.resolve_col_port(self.index, self.side)  # type: ignore[attr-defined]
+        if self.kind == "cell" and hasattr(node, "resolve_cell_port"):
+            return node.resolve_cell_port(self.index, self.col_index, self.side)  # type: ignore[attr-defined]
+        if self.kind == "custom" and hasattr(node, "resolve_custom_port"):
+            # v0.7.0: node-defined anchors (Cuboid faces, Pyramid levels, …); the
+            # name travels in ``side`` and an optional integer in ``index``.
+            return node.resolve_custom_port(self.side, self.index, self.at)  # type: ignore[attr-defined]
+        if self.kind == "cell_range" and hasattr(node, "resolve_cell_range_port"):
+            return node.resolve_cell_range_port(self.index, self.end_index, self.side)  # type: ignore[attr-defined]
+        return resolve_side_port(node, self.side, self.at)
+
+
+def _side_towards(g: Any, x: float, y: float, wside: str = "top") -> str:
+    """Side of box ``g`` that faces the waypoint (x, y) on side ``wside`` of its node
+    (v0.14.0): a route passing over / under a node leaves vertically when it can, one
+    passing beside a node leaves sideways."""
+    vert = ("bottom" if y >= g.bottom else "top" if y <= g.y else None)
+    horiz = ("right" if x >= g.right else "left" if x <= g.x else None)
+    if wside in ("top", "bottom"):
+        return vert or horiz or "right"
+    return horiz or vert or "bottom"
+
+
+def _facing_side(node: Node, other: Node) -> str:
+    g, o = node.geom, other.geom
+    hgap = max(o.x - g.right, g.x - o.right)
+    vgap = max(o.y - g.bottom, g.y - o.bottom)
+    if vgap >= hgap:
+        return "bottom" if o.cy >= g.cy else "top"
+    return "right" if o.cx >= g.cx else "left"
+
+
+def resolve_parallel_port(port: "Port") -> Tuple[float, float, str]:
+    """v0.13.0: end ``par_i`` of ``par_n`` parallel arrows between two nodes.
+
+    The arrows are spread evenly (``par_gap`` pt apart, default ≈ 6 pt, tighter when the
+    sides are short) around the middle of the range the two facing sides share, so they
+    run straight; without such an overlap each end spreads around its own side centre.
+    """
+    node, other = port.node, port.peer
+    side = port.side if port.side in ("left", "right", "top", "bottom") else _facing_side(node, other)
+    oside = {"left": "right", "right": "left", "top": "bottom", "bottom": "top"}[side]
+    x, y, w, h = _side_extent(node, side)
+    ox, oy, ow, oh = _side_extent(other, oside)
+    horiz = side in ("top", "bottom")
+    lo, hi = (x, x + w) if horiz else (y, y + h)
+    olo, ohi = (ox, ox + ow) if horiz else (oy, oy + oh)
+    n = max(1, int(port.par_n))
+    th = getattr(node, "theme", None)
+    L = th.L if th is not None else (lambda v: v)
+    m = L(2.0)
+    span = min(hi - lo, ohi - olo)
+    a, b = max(lo, olo), min(hi, ohi)
+    if port.par_gap is not None:
+        gap = port.par_gap
+    else:  # spread over the shared range, 4–10 pt apart
+        gap = min(L(10.0), max(L(4.0), (max(b - a, 0.0) if b - a > 2 * m else span) / (n + 1)))
+    if n > 1:
+        gap = min(gap, max(0.5, (span - 2 * m) / (n - 1)))
+    need = gap * (n - 1)
+    centre = (a + b) / 2 if b - a >= need + 2 * m else (lo + hi) / 2
+    v = centre + (port.par_i - (n - 1) / 2) * gap
+    v = min(max(v, lo), hi)
+    if side == "top":
+        pt = (v, y, "up")
+    elif side == "bottom":
+        pt = (v, y + h, "down")
+    elif side == "left":
+        pt = (x, v, "left")
+    else:
+        pt = (x + w, v, "right")
+    return on_outline(node, side, pt)
+
+
+def resolve_side_port(node: Node, side: Side, at: float = 0.5) -> Tuple[float, float, str]:
+    g = node.geom
+    at = max(0.0, min(1.0, at))
+    if side == "right":
+        return g.right, g.y + g.h * at, "right"
+    if side == "left":
+        return g.x, g.y + g.h * at, "left"
+    if side == "top":
+        return g.x + g.w * at, g.y, "up"
+    if side == "bottom":
+        return g.x + g.w * at, g.bottom, "down"
+    return g.cx, g.cy, "right"
+
+
+def on_outline(node: Node, side: str, pt: Tuple[float, float, str]) -> Tuple[float, float, str]:
+    """Move a bounding-box port onto a shape's true outline (shapes.Shape)."""
+    if side in ("top", "bottom", "left", "right") and hasattr(node, "outline_point"):
+        x, y = node.outline_point(side, pt[0], pt[1])  # type: ignore[attr-defined]
+        return x, y, pt[2]
+    return pt
+
+
+def auto_port(node: Node, tx: float, ty: float) -> Tuple[float, float, str]:
+    """Point on ``node``'s outline facing (tx, ty); direction = dominant axis."""
+    g = node.geom
+    if hasattr(node, "ray_point"):
+        tr = node._text_rect(g.x, g.y, g.w, g.h)  # type: ignore[attr-defined]
+        cx, cy = tr[0] + tr[2] / 2, tr[1] + tr[3] / 2
+    else:
+        cx, cy = g.cx, g.cy
+    dx, dy = tx - cx, ty - cy
+    if abs(dx) < 1e-9 and abs(dy) < 1e-9:
+        return g.right, g.cy, "right"
+    if hasattr(node, "ray_point"):
+        x, y = node.ray_point(dx, dy)  # type: ignore[attr-defined]
+    else:
+        from .shapes import ray_hit
+
+        x, y = ray_hit([(g.x, g.y), (g.right, g.y), (g.right, g.bottom), (g.x, g.bottom)],
+                       cx, cy, dx, dy)
+    if abs(dx) >= abs(dy):
+        d = "right" if dx > 0 else "left"
+    else:
+        d = "down" if dy > 0 else "up"
+    return x, y, d
+
+
+def _auto_in_line(node: Node, other: Tuple[float, float, str]) -> Optional[Tuple[float, float, str]]:
+    """v0.13.0: an ``auto`` end facing a fixed side port lines up with it when it can.
+
+    When the fixed end points straight at a rectangular ``node`` and its x (or y) falls
+    inside the node's extent, the auto end sits on the facing side *in line* with it, so
+    the connector is one straight segment instead of a ray-to-centre jog (e.g. several
+    ``Edge(p_i, gpu_i, via=loader)`` through one tall box stay straight).
+    """
+    if hasattr(node, "ray_point"):
+        return None
+    g = node.geom
+    x, y, d = other
+    m = 1.0
+    if d == "right" and x <= g.x + 1e-6 and g.y + m <= y <= g.bottom - m:
+        return g.x, y, "left"
+    if d == "left" and x >= g.right - 1e-6 and g.y + m <= y <= g.bottom - m:
+        return g.right, y, "right"
+    if d == "down" and y <= g.y + 1e-6 and g.x + m <= x <= g.right - m:
+        return x, g.y, "up"
+    if d == "up" and y >= g.bottom - 1e-6 and g.x + m <= x <= g.right - m:
+        return x, g.bottom, "down"
+    return None
+
+
+def _side_extent(node: Node, side: Side) -> Tuple[float, float, float, float]:
+    """Box (x, y, w, h) whose side a port sits on — a Matrix uses its cell grid."""
+    if hasattr(node, "_grid_origin") and hasattr(node, "_grid_size"):
+        gx, gy = node._grid_origin()  # type: ignore[attr-defined]
+        gw, gh = node._grid_size()  # type: ignore[attr-defined]
+        return gx, gy, gw, gh
+    g = node.geom
+    return g.x, g.y, g.w, g.h
+
+
+def resolve_aligned_port(port: "Port") -> Tuple[float, float, str]:
+    """Port on ``port.side`` of its node, in line with ``port.align_ref``."""
+    from .constraints import as_anchor
+
+    node, side = port.node, port.side
+    x, y, w, h = _side_extent(node, side)
+    horizontal_side = side in ("top", "bottom")
+    axis = "x" if horizontal_side else "y"
+    ref = port.align_ref
+    v = as_anchor(ref, axis, "center").value() + port.offset
+    if horizontal_side:
+        v = min(max(v, x), x + w)
+        if port.snap and hasattr(node, "col_at"):
+            c = node.col_at(v)  # type: ignore[attr-defined]
+            v = node._col_center_x(c)  # type: ignore[attr-defined]
+        elif port.snap and hasattr(node, "bar_at"):
+            v = node._bar_cx(node.bar_at(v))  # type: ignore[attr-defined]
+        if side == "top":
+            return v, y, "up"
+        return v, y + h, "down"
+    v = min(max(v, y), y + h)
+    if port.snap and hasattr(node, "row_at"):
+        v = node._row_center_y(node.row_at(v))  # type: ignore[attr-defined]
+    if side == "left":
+        return x, v, "left"
+    if side in ("right", "center"):
+        return x + w, v, "right"
+    return x + w, v, "right"
+
+
+def _end_rects(e: "Edge", x1: float, y1: float, d1: str, x2: float, y2: float,
+               d2: str) -> list:
+    """v0.8.0: an edge's own end nodes as obstacles for its trunk.
+
+    Endpoint nodes are excluded from the obstacle set so the stubs can leave them; without
+    this a detour could still cut back through the source or target box. A node is added
+    (inset 0.5 pt, no padding) only when its port and stub point both lie outside it.
+    """
+    from .routing import ORect
+
+    out = []
+    stub = _facing_stub(x1, y1, d1, x2, y2, d2, e.stub)
+    for node, (x, y, d) in ((e.src.node, (x1, y1, d1)), (e.dst.node, (x2, y2, d2))):
+        g = getattr(node, "geom", None)
+        if g is None or g.w < 2 or g.h < 2:
+            continue
+        r = (g.x + 0.5, g.y + 0.5, g.w - 1.0, g.h - 1.0)
+        sx, sy = _stub(x, y, d, stub)
+
+        def inside(px: float, py: float) -> bool:
+            return r[0] < px < r[0] + r[2] and r[1] < py < r[1] + r[3]
+
+        if not inside(x, y) and not inside(sx, sy):
+            out.append(ORect(*r, role="hard", pad=0.0))
+    return out
+
+
+def route_straight(
+    x1: float, y1: float, d1: str, x2: float, y2: float, d2: str, stub: float = 0.0
+) -> List[Pt]:
+    if stub <= 0:
+        return [(x1, y1), (x2, y2)]
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+    return [(x1, y1), (ax, ay), (bx, by), (x2, y2)]
+
+
+def _facing_stub(x1: float, y1: float, d1: str, x2: float, y2: float, d2: str,
+                 stub: float) -> float:
+    """Stub length clamped to half the gap between two facing ports."""
+    gap = {("down", "up"): y2 - y1, ("up", "down"): y1 - y2,
+           ("right", "left"): x2 - x1, ("left", "right"): x1 - x2}.get((d1, d2))
+    if gap is not None and 0.0 < gap < 2.0 * stub:
+        return gap / 2.0
+    return stub
+
+
+def _trunk0(a: float, b: float, d1: str, d2: str) -> float:
+    """Natural trunk coordinate between two stub ends ``a`` and ``b``.
+
+    Opposite or facing ports meet half way. Two ports facing the *same* way (both
+    ``left``, a C-shaped route) need the trunk outside both stubs: half way would make
+    the nearer stub double back on itself (v0.11.0)."""
+    if d1 == d2 and d1 in ("left", "up"):
+        return min(a, b)
+    if d1 == d2 and d1 in ("right", "down"):
+        return max(a, b)
+    return (a + b) / 2.0
+
+
+def route_ortho(
+    x1: float,
+    y1: float,
+    d1: str,
+    x2: float,
+    y2: float,
+    d2: str,
+    stub: float = 12.0,
+    mid_bias: float = 0.0,
+) -> List[Pt]:
+    """Manhattan route; mid_bias shifts the shared trunk for lane separation.
+
+    Facing ports closer than two stubs (a narrow row / column gap) get shorter stubs so
+    the trunk stays inside the gap instead of doubling back through the nodes (v0.7.0).
+    """
+    stub = _facing_stub(x1, y1, d1, x2, y2, d2, stub)
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+
+    horiz_src = d1 in ("left", "right")
+    horiz_dst = d2 in ("left", "right")
+
+    if horiz_src and horiz_dst:
+        mid_x = _trunk0(ax, bx, d1, d2) + mid_bias
+        pts = [(x1, y1), (ax, ay), (mid_x, ay), (mid_x, by), (bx, by), (x2, y2)]
+    elif (not horiz_src) and (not horiz_dst):
+        mid_y = _trunk0(ay, by, d1, d2) + mid_bias
+        pts = [(x1, y1), (ax, ay), (ax, mid_y), (bx, mid_y), (bx, by), (x2, y2)]
+    elif horiz_src:
+        pts = [(x1, y1), (ax, ay), (bx + mid_bias, ay), (bx + mid_bias, by), (x2, y2)]
+    else:
+        pts = [(x1, y1), (ax, ay), (ax, by + mid_bias), (bx, by + mid_bias), (x2, y2)]
+
+    return _dedupe(pts)
+
+
+
+def route_loop(
+    x1: float,
+    y1: float,
+    d1: str,
+    x2: float,
+    y2: float,
+    d2: str,
+    *,
+    stub: float = 12.0,
+    side: str = "auto",
+    clearance: float = 40.0,
+) -> List[Pt]:
+    """
+    Port-based feedback path that goes around content.
+
+    Both endpoints typically face the same outer side (e.g. both "right").
+    `side`: right|left|top|bottom|auto — which side of the content the loop hugs.
+    `clearance`: how far outside the farther port the trunk runs.
+    """
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+
+    if side == "auto":
+        # Prefer the shared outward direction of the ports.
+        if d1 == d2 and d1 in ("left", "right", "up", "down"):
+            side = {"right": "right", "left": "left", "up": "top", "down": "bottom"}[d1]
+        elif abs(x1 - x2) >= abs(y1 - y2):
+            side = "right" if (x1 + x2) / 2 >= 0 else "left"
+        else:
+            side = "right"
+
+    if side == "right":
+        trunk_x = max(ax, bx, x1, x2) + clearance
+        pts = [(x1, y1), (ax, ay), (trunk_x, ay), (trunk_x, by), (bx, by), (x2, y2)]
+    elif side == "left":
+        trunk_x = min(ax, bx, x1, x2) - clearance
+        pts = [(x1, y1), (ax, ay), (trunk_x, ay), (trunk_x, by), (bx, by), (x2, y2)]
+    elif side == "bottom":
+        trunk_y = max(ay, by, y1, y2) + clearance
+        pts = [(x1, y1), (ax, ay), (ax, trunk_y), (bx, trunk_y), (bx, by), (x2, y2)]
+    else:  # top
+        trunk_y = min(ay, by, y1, y2) - clearance
+        pts = [(x1, y1), (ax, ay), (ax, trunk_y), (bx, trunk_y), (bx, by), (x2, y2)]
+    return _dedupe(pts)
+
+
+def route_loop_around(x1, y1, d1, x2, y2, d2, edge: "Edge") -> List[Pt]:
+    """Loop whose trunk runs ``clearance`` outside ``edge.around``'s box."""
+    g = edge.around.geom
+    side = edge.loop_side if edge.loop_side != "auto" else "right"
+    c = edge.clearance
+    ax, ay = _stub(x1, y1, d1, edge.stub)
+    bx, by = _stub(x2, y2, d2, edge.stub)
+    if side == "top":
+        t = min(g.y - c, ay, by)
+        pts = [(x1, y1), (ax, ay), (ax, t), (bx, t), (bx, by), (x2, y2)]
+    elif side == "bottom":
+        t = max(g.y + g.h + c, ay, by)
+        pts = [(x1, y1), (ax, ay), (ax, t), (bx, t), (bx, by), (x2, y2)]
+    elif side == "left":
+        t = min(g.x - c, ax, bx)
+        pts = [(x1, y1), (ax, ay), (t, ay), (t, by), (bx, by), (x2, y2)]
+    else:
+        t = max(g.x + g.w + c, ax, bx)
+        pts = [(x1, y1), (ax, ay), (t, ay), (t, by), (bx, by), (x2, y2)]
+    return _dedupe(pts)
+
+
+def _dedupe(pts: List[Pt]) -> List[Pt]:
+    out: List[Pt] = []
+    for p in pts:
+        if not out or abs(out[-1][0] - p[0]) > 0.01 or abs(out[-1][1] - p[1]) > 0.01:
+            out.append(p)
+    return out
+
+
+def _simplify_ortho(pts: List[Pt], backtracks_only: bool = False) -> List[Pt]:
+    """Drop duplicate / collinear vertices of a polyline (keeps both ends). Collinear
+    backtracks shorter than 0.5 are folded too; longer ones are kept. With
+    ``backtracks_only`` plain collinear vertices stay (label placement reads them)."""
+    out = _dedupe(list(pts))
+    changed = True
+    while changed and len(out) > 2:
+        changed = False
+        for i in range(1, len(out) - 1):
+            a, b, c = out[i - 1], out[i], out[i + 1]
+            col_x = abs(a[0] - b[0]) < 1e-6 and abs(b[0] - c[0]) < 1e-6
+            col_y = abs(a[1] - b[1]) < 1e-6 and abs(b[1] - c[1]) < 1e-6
+            if not (col_x or col_y):
+                continue
+            k = 1 if col_x else 0
+            back = (b[k] - a[k]) * (c[k] - b[k]) < 0
+            if back and min(abs(b[k] - a[k]), abs(c[k] - b[k])) >= 0.5:
+                continue
+            if backtracks_only and not back:
+                continue
+            del out[i]
+            changed = True
+            break
+    return out
+
+
+def _as_port(ref: Union[Port, Node], default_side: Side) -> Port:
+    if isinstance(ref, Port):
+        return ref
+    if isinstance(ref, Node):
+        return ref.port(default_side)
+    raise TypeError(f"Edge endpoint must be Port or Node, got {type(ref)!r}")
+
+
+# ---- overlap avoidance -------------------------------------------------
+
+def _vertical_trunks(pts: List[Pt]) -> List[Tuple[int, float, float, float]]:
+    """Return (seg_index, x, y_min, y_max) for vertical segments longer than epsilon."""
+    out = []
+    for i in range(len(pts) - 1):
+        x1, y1 = pts[i]
+        x2, y2 = pts[i + 1]
+        if abs(x1 - x2) < 0.51 and abs(y1 - y2) > 1.0:
+            out.append((i, (x1 + x2) / 2.0, min(y1, y2), max(y1, y2)))
+    return out
+
+
+def _horizontal_trunks(pts: List[Pt]) -> List[Tuple[int, float, float, float]]:
+    out = []
+    for i in range(len(pts) - 1):
+        x1, y1 = pts[i]
+        x2, y2 = pts[i + 1]
+        if abs(y1 - y2) < 0.51 and abs(x1 - x2) > 1.0:
+            out.append((i, (y1 + y2) / 2.0, min(x1, x2), max(x1, x2)))
+    return out
+
+
+def _ranges_overlap(a0: float, a1: float, b0: float, b1: float, pad: float = 2.0) -> bool:
+    return not (a1 + pad < b0 or b1 + pad < a0)
+
+
+def _offset_segment_x(pts: List[Pt], seg_i: int, dx: float) -> List[Pt]:
+    pts = list(pts)
+    x1, y1 = pts[seg_i]
+    x2, y2 = pts[seg_i + 1]
+    pts[seg_i] = (x1 + dx, y1)
+    pts[seg_i + 1] = (x2 + dx, y2)
+    return pts
+
+
+def _offset_segment_y(pts: List[Pt], seg_i: int, dy: float) -> List[Pt]:
+    pts = list(pts)
+    x1, y1 = pts[seg_i]
+    x2, y2 = pts[seg_i + 1]
+    pts[seg_i] = (x1, y1 + dy)
+    pts[seg_i + 1] = (x2, y2 + dy)
+    return pts
+
+
+
+_OUT = {"left": -1.0, "up": -1.0, "right": 1.0, "down": 1.0}
+
+
+def _merge_shared_port_trunks(meta: List[dict], biases: List[float]) -> None:
+    """v0.11.0: edges that share one port merge into one trunk, whatever side or
+    corridor they come from.
+
+    Lane buckets group edges by their natural trunk, so a fan-in whose sources sit on
+    opposite sides of the port (one above, one below a ``left`` port) or at different
+    distances lands in different buckets and gets two trunks a few points apart — two
+    vertical runs and a doubled stub next to the arrowhead. For every port shared by
+    two or more two-bend routes, all of them take one common trunk: the member trunk
+    closest to the port that no member has to double back to reach."""
+    def stub_end(m: dict, which: str) -> float:
+        d = m["d" + which]
+        stub = m["edge"].stub
+        k = "x" if d in ("left", "right") else "y"
+        return m[k + which] + _OUT[d] * stub
+
+    done: set = set()
+    for which, other in (("2", "1"), ("1", "2")):
+        groups: Dict[Tuple[int, int, str], List[int]] = defaultdict(list)
+        for i, m in enumerate(meta):
+            if m["kind"] not in ("h", "v") or m["edge"].route != "ortho" or \
+                    m["st"].overlap != "avoid" or getattr(m["edge"], "bundle", None) or \
+                    not getattr(m["edge"], "trunk", True):
+                continue
+            groups[(round(m["x" + which] * 10), round(m["y" + which] * 10), m["d" + which])].append(i)
+        for (_gx, _gy, d), idxs in groups.items():
+            idxs = [i for i in idxs if i not in done]
+            if len(idxs) < 2:
+                continue
+            trunks = {i: meta[i]["mid"] + biases[i] for i in idxs}
+            if max(trunks.values()) - min(trunks.values()) < 0.05:
+                continue
+            p, s_ = stub_end(meta[idxs[0]], which), _OUT[d]
+
+            def ok(c: float) -> bool:
+                if s_ * (c - p) < -0.01:
+                    return False
+                for i in idxs:
+                    m = meta[i]
+                    if _OUT[m["d" + other]] * (c - stub_end(m, other)) < -0.01:
+                        return False
+                return True
+
+            feas = [c for c in set(trunks.values()) if ok(c)]
+            if not feas:
+                continue
+            c = min(feas, key=lambda v: s_ * (v - p))
+            for i in idxs:
+                biases[i] = c - meta[i]["mid"]
+                done.add(i)
+
+
+def apply_overlap_avoidance(
+    routes: List[Tuple["Edge", List[Pt]]],
+    *,
+    lane_gap: float = 7.0,
+    theme: Optional[Theme] = None,
+) -> List[Tuple["Edge", List[Pt]]]:
+    """
+    Re-route avoid-edges with per-lane mid_bias so parallel ortho corridors separate.
+
+    Algorithm:
+    1. Resolve endpoints for every edge; compute the natural ortho mid coordinate
+       (mid_x for left↔right flows, mid_y for top↔bottom).
+    2. Bucket avoid/ortho edges by rounded mid coordinate.
+    3. Within each bucket, sort by source cross-axis position; assign centered lanes
+       …,-1,0,1,… and re-route with mid_bias = lane * lane_gap.
+    4. overlap='allow' (and straight edges) keep the base route unchanged.
+
+    This avoids post-hoc segment surgery (which used to bend stubs) and still
+    separates edges that share a corridor even when their spans do not overlap.
+    """
+    if not routes:
+        return []
+
+    # Resolve once
+    meta = []
+    for edge, base_pts in routes:
+        (x1, y1, d1), (x2, y2, d2) = edge.endpoints()
+        st = edge.resolved(theme=theme)
+        horiz = d1 in ("left", "right") and d2 in ("left", "right")
+        vert = d1 in ("up", "down") and d2 in ("up", "down")
+        ax, ay = _stub(x1, y1, d1, edge.stub)
+        bx, by = _stub(x2, y2, d2, edge.stub)
+        if horiz:
+            mid = _trunk0(ax, bx, d1, d2)
+            sort_key = (y1 + y2) / 2.0
+            kind = "h"
+        elif vert:
+            mid = _trunk0(ay, by, d1, d2)
+            sort_key = (x1 + x2) / 2.0
+            kind = "v"
+        else:
+            mid = (ax + bx) / 2.0
+            sort_key = (y1 + y2) / 2.0
+            kind = "m"
+        meta.append(
+            {
+                "edge": edge,
+                "base": base_pts,
+                "st": st,
+                "x1": x1, "y1": y1, "d1": d1,
+                "x2": x2, "y2": y2, "d2": d2,
+                "mid": mid,
+                "sort_key": sort_key,
+                "kind": kind,
+            }
+        )
+
+    biases = [0.0] * len(meta)
+    buckets: Dict[Tuple[str, float], List[int]] = defaultdict(list)
+    gap = max(lane_gap, 1.0)
+    for i, m in enumerate(meta):
+        if m["st"].overlap != "avoid" or m["edge"].route != "ortho":
+            continue
+        key = (m["kind"], round(m["mid"] / gap) * gap)
+        buckets[key].append(i)
+
+    def _end(i: int, which: str) -> Tuple[int, int]:
+        m = meta[i]
+        return (round(m["x" + which] * 10), round(m["y" + which] * 10))
+
+    for _key, idxs in buckets.items():
+        if len(idxs) < 2:
+            continue
+        # v0.10.0: a fan-in (edges ending on one point) or fan-out (starting from
+        # one point) shares a lane, so the edges merge into one clean trunk
+        # instead of splitting into parallel stubs next to the shared port
+        parent = {i: i for i in idxs}
+
+        def find(i: int) -> int:
+            while parent[i] != i:
+                parent[i] = parent[parent[i]]
+                i = parent[i]
+            return i
+
+        for which in ("1", "2"):
+            seen: Dict[Tuple[int, int], int] = {}
+            for i in idxs:
+                k = _end(i, which)
+                if k in seen:
+                    parent[find(i)] = find(seen[k])
+                else:
+                    seen[k] = i
+        groups: Dict[int, List[int]] = defaultdict(list)
+        for i in idxs:
+            groups[find(i)].append(i)
+        if len(groups) < 2:
+            continue
+        order = sorted(groups.values(),
+                       key=lambda g: sum(meta[i]["sort_key"] for i in g) / len(g))
+        n = len(order)
+        for lane, g in enumerate(order):
+            for i in g:
+                biases[i] = (lane - (n - 1) / 2.0) * lane_gap
+
+    _merge_shared_port_trunks(meta, biases)
+
+    out: List[Tuple[Edge, List[Pt]]] = []
+    for i, m in enumerate(meta):
+        edge = m["edge"]
+        if abs(biases[i]) < 0.01 or edge.route != "ortho":
+            out.append((edge, list(m["base"])))
+            continue
+        pts = route_ortho(
+            m["x1"], m["y1"], m["d1"], m["x2"], m["y2"], m["d2"],
+            stub=edge.stub, mid_bias=biases[i],
+        )
+        out.append((edge, pts))
+    return out
+
+
+
+_LABEL_SIDES = ("auto", "above", "below", "left", "right", "on")
+_LABEL_ATS = ("mid", "longest", "start", "end")
+_ROUTES = ("auto", "ortho", "straight", "curve", "loop", "over", "under", "back")
+
+_DIRV = {"right": (1.0, 0.0), "left": (-1.0, 0.0), "up": (0.0, -1.0), "down": (0.0, 1.0)}
+
+
+def bezier_point(ctrl: Sequence[Pt], t: float) -> Pt:
+    (x0, y0), (x1, y1), (x2, y2), (x3, y3) = ctrl
+    u = 1.0 - t
+    a, b, c, d = u * u * u, 3 * u * u * t, 3 * u * t * t, t * t * t
+    return (a * x0 + b * x1 + c * x2 + d * x3, a * y0 + b * y1 + c * y2 + d * y3)
+
+
+def bezier_sample(ctrl: Sequence[Pt], n: int = 32) -> List[Pt]:
+    return [bezier_point(ctrl, i / n) for i in range(n + 1)]
+
+
+def curve_controls(x1: float, y1: float, d1: str, x2: float, y2: float, d2: str,
+                   bend: Optional[float] = None, tension: float = 0.45) -> Tuple[Pt, Pt, Pt, Pt]:
+    """Cubic control polygon for ``route='curve'``.
+
+    ``bend=None`` leaves each end along its port's outward direction (a smooth
+    S/C curve, like draw.io's curved connector); ``bend=θ`` (degrees, TikZ
+    ``bend left=θ``; negative bends right) uses a symmetric arc leaving at θ to
+    the chord.  Control arms scale with the end-to-end distance.
+    """
+    import math
+
+    L = math.hypot(x2 - x1, y2 - y1) or 1.0
+    k = max(14.0, tension * L)
+    if bend is not None:
+        a = math.atan2(y2 - y1, x2 - x1)
+        th = math.radians(bend)
+        k = L * 0.39 / max(0.35, math.cos(th))
+        c1 = (x1 + k * math.cos(a - th), y1 + k * math.sin(a - th))
+        c2 = (x2 - k * math.cos(a + th), y2 - k * math.sin(a + th))
+        return (x1, y1), c1, c2, (x2, y2)
+    v1 = _DIRV.get(d1)
+    v2 = _DIRV.get(d2)
+    ux, uy = (x2 - x1) / L, (y2 - y1) / L
+    if v1 is None:
+        v1 = (ux, uy)
+    if v2 is None:
+        v2 = (-ux, -uy)
+    c1 = (x1 + k * v1[0], y1 + k * v1[1])
+    c2 = (x2 + k * v2[0], y2 + k * v2[1])
+    return (x1, y1), c1, c2, (x2, y2)
+
+
+def _trim_bezier(ctrl: Sequence[Pt], start: float, end: float) -> Tuple[Pt, Pt, Pt, Pt]:
+    """Pull the curve ends back by ``start`` / ``end`` px along their tangents."""
+    import math
+
+    p0, c1, c2, p3 = [tuple(p) for p in ctrl]
+
+    def unit(a: Pt, b: Pt) -> Pt:
+        dx, dy = b[0] - a[0], b[1] - a[1]
+        n = math.hypot(dx, dy) or 1.0
+        return dx / n, dy / n
+
+    if end > 0:
+        ux, uy = unit(c2 if c2 != p3 else c1, p3)
+        p3 = (p3[0] - ux * end, p3[1] - uy * end)
+        c2 = (c2[0] - ux * end, c2[1] - uy * end)
+    if start > 0:
+        ux, uy = unit(c1 if c1 != p0 else c2, p0)
+        p0 = (p0[0] - ux * start, p0[1] - uy * start)
+        c1 = (c1[0] - ux * start, c1[1] - uy * start)
+    return p0, c1, c2, p3  # type: ignore[return-value]
+
+
+def _trim_polyline(pts: List[Pt], start: float, end: float) -> List[Pt]:
+    import math
+
+    out = list(pts)
+    if end > 0 and len(out) >= 2:
+        (ax, ay), (bx, by) = out[-2], out[-1]
+        n = math.hypot(bx - ax, by - ay) or 1.0
+        e = min(end, n * 0.95)
+        out[-1] = (bx - (bx - ax) / n * e, by - (by - ay) / n * e)
+    if start > 0 and len(out) >= 2:
+        (ax, ay), (bx, by) = out[0], out[1]
+        n = math.hypot(bx - ax, by - ay) or 1.0
+        s = min(start, n * 0.95)
+        out[0] = (ax + (bx - ax) / n * s, ay + (by - ay) / n * s)
+    return out
+
+
+def _merge_collinear(pts: Sequence[Pt], eps: float = 0.5) -> List[Pt]:
+    """Drop duplicate and straight-through vertices (a run of collinear segments
+    is one segment for label placement)."""
+    out: List[Pt] = []
+    for p in pts:
+        if out and abs(p[0] - out[-1][0]) < eps and abs(p[1] - out[-1][1]) < eps:
+            continue
+        if len(out) >= 2:
+            a, b = out[-2], out[-1]
+            cross = (b[0] - a[0]) * (p[1] - b[1]) - (b[1] - a[1]) * (p[0] - b[0])
+            dot = (b[0] - a[0]) * (p[0] - b[0]) + (b[1] - a[1]) * (p[1] - b[1])
+            if abs(cross) < eps * max(1.0, abs(dot) ** 0.5) and dot > 0:
+                out[-1] = p
+                continue
+        out.append(p)
+    return out if len(out) >= 2 else list(pts)
+
+
+def knockout_clip(buf: List[str], holes: Sequence[Tuple[float, float, float, float]]) -> str:
+    """Emit a clipPath that keeps everything *except* ``holes``; return its id.
+
+    The holes are drawn with reversed winding (nonzero rule), which every SVG
+    renderer — cairosvg included — honours, unlike ``clip-rule=evenodd``.
+    """
+    global _CLIP_SEQ
+    _CLIP_SEQ += 1
+    cid = f"cf-ko-{_CLIP_SEQ}"
+    big = 1.0e5
+    d = [f"M {-big},{-big} H {big} V {big} H {-big} Z"]
+    for x, y, w, h in holes:
+        d.append(f"M {x:.2f},{y:.2f} V {y + h:.2f} H {x + w:.2f} V {y:.2f} Z")
+    buf.append(f'<defs><clipPath id="{cid}"><path d="{" ".join(d)}"/></clipPath></defs>')
+    return cid
+
+
+_CLIP_SEQ = 0
+
+
+def _poly_hits_rect(pts: Sequence[Pt], r: Tuple[float, float, float, float]) -> bool:
+    from .routing import seg_rect_intersect
+
+    return any(seg_rect_intersect(pts[i], pts[i + 1], r) for i in range(len(pts) - 1))
+
+
+class Edge:
+    """
+    Connector between two Ports (or Nodes).
+
+    route: ortho | straight | curve | loop (feedback around content).
+    Styling knobs (aliases accepted): color/stroke, opacity/alpha, width/stroke_width,
+    style (solid|dashed|dotted|dashdot|custom dash such as ``(6, 2)``), overlap (allow|avoid).
+
+    Arrowheads (each end independently): ``head=`` (end) / ``tail=`` (start) take a
+    shape name — triangle | stealth | vee | open | circle | diamond | bar | square | none —
+    or a :class:`~codefig.styles.Head` (shape, size, length, width, hollow, fill).
+    ``head_size`` scales both, ``head_length``/``head_width`` set them exactly,
+    ``hollow=True`` draws outlined heads. Theme defaults: ``edge_head``, ``edge_tail``…
+
+    ``route='curve'``: smooth cubic Bézier; ``bend=`` degrees (TikZ ``bend left``),
+    otherwise the ends leave along the port directions. Heads follow the tangent.
+
+    ``knockout`` (default from the theme / figure policy): soft text that the edge
+    passes under (free Text, edge labels) cuts a small gap in the line so the text
+    stays readable instead of forcing a detour.
+    loop_side / clearance control route="loop". ``bundle="id"`` groups parallel edges:
+    ``bundle_style="lanes"`` (theme default since v0.7.0) draws them as evenly spaced
+    parallel trunks in a crossing-minimising order; ``"merge"`` shares one trunk;
+    ``"bus"`` adds the old translucent underlay. ``bus=`` is an alias of ``bundle=``.
+
+    ``step=`` (v0.5.0; int, str or :class:`~codefig.steps.Step`) draws a numbered
+    step badge (①) on the path; ``step_at`` = fraction 0..1 of the path length or
+    ``"start" | "mid" | "end"`` (default ``"mid"``). The badge slides along the path
+    away from nodes / labels and is checked like an edge label by check_overlaps().
+    Example: ``Edge(a, b, step=2)`` or ``Edge(a, b, step=steps.next(), step_at="start")``.
+
+    ``via=node`` (v0.12.0) passes the arrow *through* any node — an ``OpCircle`` /
+    ``Op``, a router ``Box``, a bus — as two drawn legs (``a → node`` without a head,
+    ``node → b`` with the head and label); both legs meet ``node`` on the sides facing
+    their other ends and, since v0.13.0, stay level with a facing side port, so several
+    ``Edge(p_i, q_i, via=loader)`` through one tall box are straight lines.
+    ``trunk=False`` (v0.12.0) opts this edge out of shared-port trunk merging (edges
+    that share a port merge into one trunk by default — fan-in / fan-out), so two
+    edges into one box arrive as two separate arrows.
+    ``parallel=N`` (v0.13.0) draws N straight arrows side by side between the two nodes
+    (multi-head attention inputs, k/v pairs); ``parallel_gap=`` sets their pitch in pt
+    (default ≈ the shared overlap / (N + 1), 4–10 pt); explicit side ports keep their
+    side. ``port(side, offset=pt)`` shifts one port along its side.
+    A legend entry for a line style: ``Legend([Key("PCIe", kind="arrow", style="dashed")])``
+    or ``Key.from_edge(edge, "label")``.
+    Public API takes no absolute coordinates.
+    """
+
+    stub = themed(12.0)
+    clearance = themed(20.0)  # v0.7.0: was 40 (loops hugged the panel edge)
+
+
+    def __init__(
+        self,
+        src: Union[Port, Node],
+        dst: Union[Port, Node],
+        *,
+        route: str = "ortho",
+        label: Optional[str] = None,
+        marker_end: bool = True,
+        marker_start: bool = False,
+        # style
+        color: Optional[str] = None,
+        stroke: Optional[str] = None,
+        opacity: Optional[float] = None,
+        alpha: Optional[float] = None,
+        width: Optional[float] = None,
+        stroke_width: Optional[float] = None,
+        head_size: Optional[float] = None,
+        style: Any = None,
+        overlap: Optional[str] = None,
+        head: Any = None,
+        tail: Any = None,
+        head_length: Optional[float] = None,
+        head_width: Optional[float] = None,
+        hollow: Optional[bool] = None,
+        head_fill: Optional[str] = None,
+        bend: Optional[float] = None,
+        knockout: Optional[bool] = None,
+        legend: Optional[str] = None,
+        stub: Optional[float] = None,
+        loop_side: str = "auto",  # right|left|top|bottom|auto — for route="loop"
+        loop_gap: Optional[float] = None,
+        jog_tol: Optional[float] = None,
+        clearance: Optional[float] = None,  # how far the loop trunk sits outside ports
+        bundle: Optional[str] = None,  # shared bus id — parallel edges share a trunk
+        bus: Optional[str] = None,  # alias of bundle
+        bundle_style: Optional[str] = None,  # v0.7.0: lanes | merge | bus (theme default)
+        theme: Optional[Theme] = None,
+        # label placement (all optional; defaults keep the legacy "above the
+        # middle point" behaviour)
+        label_at: Optional[Union[float, str]] = None,  # 0..1 | mid | longest | start | end
+        label_side: Optional[str] = None,  # auto | above | below | left | right | on
+        label_rotate: Union[bool, str] = False,  # True/"along": follow vertical segments
+        label_bg: Optional[str] = None,  # halo colour behind the label ("on" → white)
+        label_size: Optional[float] = None,
+        label_color: Optional[str] = None,
+        label_gap: Optional[float] = None,
+        around: Optional[Node] = None,  # route="loop": trunk clears this node's box
+        snap: bool = False,  # straight connector when facing side ports overlap
+        step: Any = None,  # v0.5.0: numbered badge (int | str | Step) on the path
+        step_at: Union[float, str] = "mid",  # 0..1 | start | mid | end
+        align: bool = True,  # v0.11.0: may the layout nudge nodes to straighten me?
+        via: Any = None,  # v0.12.0: node to pass through; v0.14.0: (node, side) waypoints
+        trunk: bool = True,  # v0.12.0: False → never merge my trunk with shared-port edges
+        parallel: int = 1,  # v0.13.0: draw N side-by-side arrows (multi-head, fan of copies)
+        parallel_gap: Optional[float] = None,  # v0.13.0: their spacing (pt; default ≈ 6)
+        auto_wrap: bool = True,  # v0.14.0: may the wrap-before-shrink pass break my label?
+    ) -> None:
+        _init_kw = {k: v for k, v in locals().items()
+                    if k not in ("self", "src", "dst", "via", "__class__", "parallel",
+                                 "parallel_gap")}
+        if int(parallel) < 1:
+            raise ValueError("Edge(parallel=) must be >= 1")
+        if int(parallel) > 1 and via is not None:
+            raise ValueError("Edge(parallel=) cannot be combined with via=")
+        self.parallel = int(parallel)
+        self.parallel_gap = None if parallel_gap is None else float(parallel_gap)
+        from ._validate import check_enum
+        loop_side = check_enum("edges(loop_side)", loop_side, ("auto", "top", "bottom", "left", "right"))
+        for name, value in (("loop_gap", loop_gap), ("jog_tol", jog_tol)):
+            if value is not None and value < 0:
+                raise ValueError(f"{name} must be nonnegative, got {value}")
+        self.loop_gap = loop_gap
+        self.jog_tol = jog_tol
+        from ._validate import check_enum
+        route = check_enum("edges(route)", route, _ROUTES)
+        # bare nodes (no explicit Port): sides follow the layout — right→left when
+        # dst is to the right (the classic default), bottom→top when stacked, …
+        self._bare_ends = not isinstance(src, Port) and not isinstance(dst, Port)
+        # v0.14.0: via=(node, side) / [(node, side), ...] are waypoints *beside* nodes
+        self.waypoints: List[Tuple[Node, str]] = []
+        if via is not None and not isinstance(via, Node):
+            wps = [via] if (isinstance(via, tuple) and len(via) == 2
+                            and isinstance(via[1], str)) else list(via)
+            for w in wps:
+                if not (isinstance(w, tuple) and len(w) == 2 and isinstance(w[0], Node)
+                        and w[1] in ("top", "bottom", "left", "right")):
+                    raise TypeError("Edge(via=) takes a node to pass through, or (node, side) "
+                                    "waypoints with side top|bottom|left|right, e.g. "
+                                    "via=(enc, 'top') or via=[(a, 'top'), (b, 'bottom')]")
+                self.waypoints.append((w[0], w[1]))
+            via = None
+            if route not in ("ortho", "over", "under"):
+                raise ValueError("Edge(via=(node, side)) waypoints need route='ortho'")
+            route = "ortho"
+        if route in ("over", "under") and self._bare_ends:
+            side = "top" if route == "over" else "bottom"
+            src, dst = src.port(side), dst.port(side)
+            self._bare_ends = False
+        self.src = _as_port(src, "right")
+        self.dst = _as_port(dst, "left")
+        self.route = route
+        self.align = bool(align)
+        self.auto_wrap = bool(auto_wrap)
+        self.label = label
+        self.marker_end = marker_end
+        self.marker_start = marker_start
+        self.color = color
+        self.stroke = stroke
+        self.opacity = opacity
+        self.alpha = alpha
+        self.width = width
+        self.stroke_width = stroke_width
+        self.head_size = head_size
+        self.style = style
+        self.overlap = overlap
+        self.head = head
+        self.tail = tail
+        self.head_length = head_length
+        self.head_width = head_width
+        self.hollow = hollow
+        self.head_fill = head_fill
+        self.bend = bend
+        self.knockout = knockout
+        self.legend = legend
+        self.stub = stub
+        self.loop_side = loop_side
+        self.clearance = clearance
+        self.bundle = bundle if bundle is not None else bus
+        if bundle_style is not None and bundle_style not in ("lanes", "merge", "bus"):
+            from ._validate import check_enum
+            check_enum("Edge(bundle_style)", bundle_style, ("lanes", "merge", "bus"))
+        self.bundle_style = bundle_style
+        self._theme = theme
+        if label_side is not None and label_side not in _LABEL_SIDES:
+            from ._validate import check_enum
+            check_enum("Edge(label_side)", label_side, _LABEL_SIDES)
+        if isinstance(label_at, str) and label_at not in _LABEL_ATS:
+            from ._validate import check_enum
+            check_enum("Edge(label_at)", label_at, _LABEL_ATS)
+        if isinstance(label_at, (int, float)) and not 0.0 <= float(label_at) <= 1.0:
+            raise ValueError(f"label_at fraction must be within 0..1, got {label_at!r}")
+        self.label_at = label_at
+        self.label_side = label_side
+        self.label_rotate = label_rotate
+        self.label_bg = label_bg
+        self.label_size = label_size
+        self.label_color = label_color
+        self.label_gap = label_gap
+        self.around = around
+        self.snap = bool(snap)
+        from .steps import as_step
+
+        self.step = as_step(step, theme=self._theme)
+        if isinstance(step_at, str) and step_at not in ("start", "mid", "end"):
+            from ._validate import check_enum
+            check_enum("Edge(step_at)", step_at, ("start", "mid", "end"))
+        if isinstance(step_at, (int, float)) and not 0.0 <= float(step_at) <= 1.0:
+            raise ValueError(f"step_at fraction must be within 0..1, got {step_at!r}")
+        self.step_at = step_at
+        self.trunk = bool(trunk)
+        if self.waypoints or route in ("over", "under"):
+            # the author fixed the path: no trunk merging, no nudging nodes to straighten it
+            self.trunk, self.align = False, False
+        self.via = via
+        self._init_kw = _init_kw
+        self._src_raw, self._dst_raw = src, dst
+        self._legs: Optional[List["Edge"]] = None
+        self._cached_pts: Optional[List[Pt]] = None
+        self._bezier: Optional[Tuple[Pt, Pt, Pt, Pt]] = None
+        self.resolved()  # validate style / heads early
+
+    def legs(self) -> List["Edge"]:
+        """v0.12.0: the drawn parts of this edge.
+
+        A plain edge is its own single leg. ``Edge(a, b, via=n)`` becomes two legs —
+        ``a → n`` (no arrowhead) and ``n → b`` (the head, label and step) — so one
+        logical arrow can pass *through* a node (a ⊕ / ⊙ operator, a router, a bus
+        tap) without the author splitting it by hand. Both legs enter / leave ``n``
+        on the sides facing their other end (``port("auto")``). Diagrams expand a
+        ``via`` edge into its legs when it is added.
+        """
+        if self.via is None and self.parallel > 1:
+            if self._legs is None:
+                self._legs = self._parallel_legs()
+            return self._legs
+        if self.via is None:
+            return [self]
+        if self._legs is None:
+            kw = dict(self._init_kw)
+            k1 = dict(kw, label=None, step=None, head="none", marker_end=False, legend=None)
+            k2 = dict(kw, tail=None, marker_start=False)
+            a = Edge(self._src_raw, self.via.port("auto"), **k1)
+            b = Edge(self.via.port("auto"), self._dst_raw, **k2)
+            for leg in (a, b):
+                leg.lint_ignore = getattr(self, "lint_ignore", None)
+            self._legs = [a, b]
+        return self._legs
+
+    def _parallel_legs(self) -> List["Edge"]:
+        """v0.13.0: ``Edge(a, b, parallel=3)`` → three straight arrows side by side.
+
+        Explicit side ports keep their side (``Edge(a.port("bottom"), b.port("top"),
+        parallel=3)``); bare nodes use the sides facing each other. The label (and step
+        badge) go on the middle arrow; the legs never share a trunk or nudge nodes.
+        """
+        n = self.parallel
+        sn, dn = self.src.node, self.dst.node
+        ss = self.src.side if (self.src.kind == "side" and not self._bare_ends) else "auto"
+        ds = self.dst.side if (self.dst.kind == "side" and not self._bare_ends) else "auto"
+        mid = n // 2
+        out = []
+        for i in range(n):
+            kw = dict(self._init_kw, trunk=False, align=False, snap=False)
+            if i != mid:
+                kw.update(label=None, step=None, legend=None)
+            sp = Port(sn, kind="parallel", side=ss, peer=dn, par_i=i, par_n=n, par_gap=self.parallel_gap)
+            dp = Port(dn, kind="parallel", side=ds, peer=sn, par_i=i, par_n=n, par_gap=self.parallel_gap)
+            leg = Edge(sp, dp, **kw)
+            leg.lint_ignore = getattr(self, "lint_ignore", None)
+            out.append(leg)
+        for leg in out:
+            leg._par_group = out
+            leg._par_label = (self.label, self.label_side, self.step)
+        return out
+
+    def _par_assign_label(self) -> None:
+        """Put a parallel group's label on its outermost arrow (right of vertical
+        arrows, above horizontal ones) once the direction is known."""
+        group = getattr(self, "_par_group", None)
+        if not group or group[0] is not self:
+            return
+        label, side, step = self._par_label
+        if label is None and step is None:
+            return
+        try:
+            (x1, y1, d1), _b = self.endpoints()
+        except Exception:  # pragma: no cover
+            return
+        vertical = d1 in ("up", "down")
+        owner = max(group, key=lambda e: e.endpoints()[0][0]) if vertical else \
+            min(group, key=lambda e: e.endpoints()[0][1])
+        for e in group:
+            e.label = label if e is owner else None
+            e.step = step if e is owner else None
+            if e is owner and side is None:
+                e.label_side = "right" if vertical else "above"
+
+    @property
+    def theme(self) -> Theme:
+        """Explicit ``theme=`` or the active theme (Figure / ``use_theme``)."""
+        return self._theme if self._theme is not None else current_theme()
+
+    @theme.setter
+    def theme(self, value: Optional[Theme]) -> None:
+        self._theme = value
+
+    def _theme_for_resolve(self) -> Theme:
+        return self.theme
+
+    def resolved(self, theme: Optional[Theme] = None) -> ResolvedEdgeStyle:
+        th = theme or self.theme
+        tail = self.tail
+        if tail is None and self.marker_start:
+            tail = self.head if self.head is not None else th.edge_head
+        head = self.head
+        if not self.marker_end:
+            head = "none"
+        return resolve_edge_style(
+            th,
+            color=self.color,
+            stroke=self.stroke,
+            opacity=self.opacity,
+            alpha=self.alpha,
+            width=self.width,
+            stroke_width=self.stroke_width,
+            head_size=self.head_size,
+            style=self.style,
+            overlap=self.overlap,
+            head=head,
+            tail=tail,
+            head_length=self.head_length,
+            head_width=self.head_width,
+            hollow=self.hollow,
+            head_fill=self.head_fill,
+        )
+
+    def curve_ctrl(self, obstacles: Optional[Sequence[Any]] = None) -> Tuple[Pt, Pt, Pt, Pt]:
+        """Control polygon for route='curve' (tries alternative bends around hard obstacles)."""
+        (x1, y1, d1), (x2, y2, d2) = self.endpoints()
+        ctrl = curve_controls(x1, y1, d1, x2, y2, d2, bend=self.bend)
+        if self.bend is None and obstacles:
+            from .routing import path_cost
+
+            def cost(c):
+                return path_cost(bezier_sample(c, 24), obstacles)
+
+            best, bc = ctrl, cost(ctrl)
+            if bc >= 10000:
+                for cand in ([curve_controls(x1, y1, d1, x2, y2, d2, tension=t) for t in (0.25, 0.7)]
+                             + [curve_controls(x1, y1, d1, x2, y2, d2, bend=b)
+                                for b in (25, -25, 40, -40, 55, -55)]):
+                    c = cost(cand) + 1.0
+                    if c < bc:
+                        best, bc = cand, c
+            ctrl = best
+        return ctrl
+
+    def points(self) -> List[Pt]:
+        if self._cached_pts is not None:
+            return self._cached_pts
+        (x1, y1, d1), (x2, y2, d2) = self.endpoints()
+        if self.route == "straight":
+            # v0.12.0: a straight route is one segment unless ``stub=`` is given
+            explicit = self.__dict__.get("_th_stub")
+            return route_straight(x1, y1, d1, x2, y2, d2, stub=explicit or 0.0)
+        if self._tiny_jog():
+            return [(x1, y1), (x2, y2)]
+        if self.route == "curve":
+            self._bezier = self.curve_ctrl()
+            return bezier_sample(self._bezier)
+        if self.route in ("loop", "back"):
+            return route_loop(
+                x1, y1, d1, x2, y2, d2,
+                stub=self.stub, side=self.loop_side, clearance=self.clearance,
+            )
+        return route_ortho(x1, y1, d1, x2, y2, d2, stub=self.stub)
+
+    def knockout_enabled(self, theme: Optional[Theme] = None) -> bool:
+        from .policy import knockout_enabled
+
+        if self.knockout is not None:
+            return bool(self.knockout)
+        return knockout_enabled(theme or self.theme)
+
+    def draw(
+        self,
+        buf: List[str],
+        ox: float = 0.0,
+        oy: float = 0.0,
+        *,
+        theme: Optional[Theme] = None,
+        points: Optional[List[Pt]] = None,
+        obstacles: Optional[List[Tuple[float, float, float, float]]] = None,
+        defer_label: bool = False,
+        curve: Optional[Sequence[Pt]] = None,
+        holes: Optional[Sequence[Tuple[float, float, float, float]]] = None,
+    ) -> None:
+        from .render_svg import angle_of, draw_head, draw_path
+
+        th = theme or self.theme
+        st = self.resolved(th)
+        if points is None:
+            pts = self.points()
+            if self.route == "curve" and curve is None:
+                curve = self._bezier
+        else:
+            pts = points
+        if len(pts) < 2:
+            return
+        pts = [(x + ox, y + oy) for x, y in pts]
+        eh, sh = st.end_head, st.start_head
+        sb_end = eh.setback(st.width) if eh is not None and eh.visible else 0.0
+        sb_start = sh.setback(st.width) if sh is not None and sh.visible else 0.0
+
+        if holes:
+            cid = knockout_clip(buf, holes)
+            buf.append(f'<g clip-path="url(#{cid})">')
+        if curve is not None:
+            ctrl = [(x + ox, y + oy) for x, y in curve]
+            p0, c1, c2, p3 = _trim_bezier(ctrl, sb_start, sb_end)
+            d = (f"M {p0[0]:.2f},{p0[1]:.2f} C {c1[0]:.2f},{c1[1]:.2f} "
+                 f"{c2[0]:.2f},{c2[1]:.2f} {p3[0]:.2f},{p3[1]:.2f}")
+            end_from = ctrl[2] if ctrl[2] != ctrl[3] else ctrl[1]
+            start_from = ctrl[1] if ctrl[1] != ctrl[0] else ctrl[2]
+            end_ang = angle_of(end_from[0], end_from[1], ctrl[3][0], ctrl[3][1])
+            start_ang = angle_of(start_from[0], start_from[1], ctrl[0][0], ctrl[0][1])
+            tip_end, tip_start = ctrl[3], ctrl[0]
+        else:
+            dp = _trim_polyline(pts, sb_start, sb_end)
+            d = f"M {dp[0][0]:.2f},{dp[0][1]:.2f} " + " ".join(f"L {x:.2f},{y:.2f}" for x, y in dp[1:])
+            end_ang = angle_of(pts[-2][0], pts[-2][1], pts[-1][0], pts[-1][1])
+            start_ang = angle_of(pts[1][0], pts[1][1], pts[0][0], pts[0][1])
+            tip_end, tip_start = pts[-1], pts[0]
+        draw_path(buf, d, stroke=st.color, stroke_width=st.width, opacity=st.opacity,
+                  dasharray=st.dasharray(), marker_end=False, marker_start=False)
+        if holes:  # heads are never knocked out (check_overlaps flags a head on text)
+            buf.append("</g>")
+        draw_head(buf, tip_end[0], tip_end[1], end_ang, eh, color=st.color, opacity=st.opacity,
+                  stroke_width=st.width)
+        draw_head(buf, tip_start[0], tip_start[1], start_ang, sh, color=st.color,
+                  opacity=st.opacity, stroke_width=st.width)
+        if self.label and not defer_label:
+            self._draw_label(buf, pts, th, st, obstacles or [])
+
+    def endpoints(self) -> Tuple[Tuple[float, float, str], Tuple[float, float, str]]:
+        """Resolved (x, y, dir) of both ends; ``snap`` straightens facing side ports.
+
+        With ``snap=True`` and two plain side ports facing each other (bottom→top,
+        right→left, …) whose nodes overlap on the cross axis, both ends move to the
+        centre of that overlap so the connector is one straight segment.
+        """
+        if getattr(self, "_bare_ends", False):
+            self._pick_bare_sides()
+        a = self.src.resolve()
+        b = self.dst.resolve()
+        sa = self.src.kind == "side" and self.src.side == "auto"
+        sb = self.dst.kind == "side" and self.dst.side == "auto"
+        if sa or sb:
+            if sa and sb:
+                ga, gb = self.src.node.geom, self.dst.node.geom
+                a = auto_port(self.src.node, gb.cx, gb.cy)
+                b = auto_port(self.dst.node, ga.cx, ga.cy)
+            elif sa:
+                a = _auto_in_line(self.src.node, b) or auto_port(self.src.node, b[0], b[1])
+            else:
+                b = _auto_in_line(self.dst.node, a) or auto_port(self.dst.node, a[0], a[1])
+            return a, b
+        if not self.snap:
+            al = self._align_small_offset(a, b)
+            if al is not None:
+                return al
+        if not self.snap or self.src.kind != "side" or self.dst.kind != "side":
+            return a, b
+        ga, gb = self.src.node.geom, self.dst.node.geom
+        vert = {a[2], b[2]} == {"up", "down"}
+        horiz = {a[2], b[2]} == {"left", "right"}
+        if vert:
+            lo, hi = max(ga.x, gb.x), min(ga.x + ga.w, gb.x + gb.w)
+            if hi - lo > 2:
+                x = min(max((a[0] + b[0]) / 2, lo + 1), hi - 1)
+                return (on_outline(self.src.node, self.src.side, (x, a[1], a[2])),
+                        on_outline(self.dst.node, self.dst.side, (x, b[1], b[2])))
+        elif horiz:
+            lo, hi = max(ga.y, gb.y), min(ga.y + ga.h, gb.y + gb.h)
+            if hi - lo > 2:
+                y = min(max((a[1] + b[1]) / 2, lo + 1), hi - 1)
+                return (on_outline(self.src.node, self.src.side, (a[0], y, a[2])),
+                        on_outline(self.dst.node, self.dst.side, (b[0], y, b[2])))
+        return a, b
+
+    @staticmethod
+    def _facing(a: Tuple[float, float, str], b: Tuple[float, float, str]) -> Optional[str]:
+        """``"h"`` / ``"v"`` when the two ends point at each other, else None."""
+        if (a[2], b[2]) == ("right", "left") and b[0] > a[0] or \
+                (a[2], b[2]) == ("left", "right") and b[0] < a[0]:
+            return "h"
+        if (a[2], b[2]) == ("down", "up") and b[1] > a[1] or \
+                (a[2], b[2]) == ("up", "down") and b[1] < a[1]:
+            return "v"
+        return None
+
+    def _align_small_offset(self, a, b):
+        """v0.8.0: remove a tiny ortho jog between two facing ends.
+
+        A fixed anchor (a Cuboid face, a slab edge, …) facing a plain side port a few pt
+        off-line slides the side port into line with it, so the connector is one straight
+        segment; two plain facing side ports a few pt apart snap to their overlap.
+        """
+        if self.route != "ortho":
+            return None
+        f = self._facing(a, b)
+        if f is None:
+            return None
+        k = 1 if f == "h" else 0
+        off = b[k] - a[k]
+        if abs(off) < 0.05 or abs(off) > self.theme.L(10.0):
+            return None
+
+        def slidable(p: Port) -> bool:
+            return p.kind == "side" and p.side in ("left", "right", "top", "bottom") and \
+                abs(p.at - 0.5) < 1e-9 and p.offset == 0
+
+        sa, sb = slidable(self.src), slidable(self.dst)
+        if sa and sb:
+            (a0, a1), (b0, b1) = self._span(self.src, k), self._span(self.dst, k)
+            lo, hi = max(a0, b0), min(a1, b1)
+            m = self.theme.L(2.0)
+            if hi - lo <= 2 * m or abs(off) > self.theme.L(8.0):
+                return None
+            t = min(max((a[k] + b[k]) / 2, lo + m), hi - m)
+            return self._slide(self.src, t, k), self._slide(self.dst, t, k)
+        if sa != sb and (self.src.kind == "custom" if sb else self.dst.kind == "custom"):
+            mov, fixed = (self.dst, a) if sb else (self.src, b)
+            lo, hi = self._span(mov, k)
+            span = hi - lo
+            m = max(self.theme.L(2.0), 0.15 * span)
+            if not (lo + m <= fixed[k] <= lo + span - m):
+                return None
+            p = self._slide(mov, fixed[k], k)
+            return (a, p) if sb else (p, b)
+        return None
+
+    @staticmethod
+    def _span(p: Port, k: int) -> Tuple[float, float]:
+        """Extent of side port ``p`` along axis ``k`` (``at`` 0 → 1), as resolved."""
+        u = Port(p.node, kind="side", side=p.side, at=0.0).resolve()[k]
+        v = Port(p.node, kind="side", side=p.side, at=1.0).resolve()[k]
+        return min(u, v), max(u, v)
+
+    @classmethod
+    def _slide(cls, p: Port, t: float, k: int) -> Tuple[float, float, str]:
+        lo, hi = cls._span(p, k)
+        at = 0.5 if hi - lo < 1e-9 else (t - lo) / (hi - lo)
+        q = Port(p.node, kind="side", side=p.side, at=at).resolve()
+        # shapes whose side is not parametrised linearly (cylinder caps …): a few
+        # secant steps so the slid point really lands on ``t``
+        a0, v0 = 0.5, Port(p.node, kind="side", side=p.side, at=0.5).resolve()[k]
+        for _ in range(6):
+            if abs(q[k] - t) <= 0.01 or abs(q[k] - v0) < 1e-9:
+                break
+            a1 = at + (t - q[k]) * (at - a0) / (q[k] - v0)
+            a0, v0 = at, q[k]
+            at = min(1.0, max(0.0, a1))
+            q = Port(p.node, kind="side", side=p.side, at=at).resolve()
+        return q
+
+    def _tiny_jog(self) -> bool:
+        """Two fixed facing anchors a few pt off-line: one short slope beats a jog."""
+        if self.route != "ortho":
+            return False
+        a, b = self.endpoints()
+        f = self._facing(a, b)
+        if f is None:
+            return False
+        k = 1 if f == "h" else 0
+        off, along = abs(b[k] - a[k]), abs(b[1 - k] - a[1 - k])
+        return 0.05 < off <= self.theme.L(4.0) and along >= 3.0 * off
+
+    def _pick_bare_sides(self) -> None:
+        """Facing sides for an Edge built from two bare nodes (v0.5.0)."""
+        na, nb = self.src.node, self.dst.node
+        ga, gb = na.geom, nb.geom
+        if self.waypoints:  # v0.14.0: face the first / last waypoint
+            wp = self.waypoint_pts()
+            sides = (_side_towards(ga, *wp[0]), _side_towards(gb, *wp[-1]))
+            if (self.src.side, self.dst.side) != sides:
+                self.src = Port(na, kind="side", side=sides[0])
+                self.dst = Port(nb, kind="side", side=sides[1])
+            return
+        if gb.x >= ga.right - 0.5:
+            sides = ("right", "left")
+        elif gb.right <= ga.x + 0.5:
+            sides = ("left", "right")
+        elif gb.y >= ga.bottom - 0.5:
+            sides = ("bottom", "top")
+        elif gb.bottom <= ga.y + 0.5:
+            sides = ("top", "bottom")
+        else:
+            sides = ("right", "left")
+        if (self.src.side, self.dst.side) != sides:
+            self.src = Port(na, kind="side", side=sides[0])
+            self.dst = Port(nb, kind="side", side=sides[1])
+
+    def waypoint_pts(self) -> List[Tuple[float, float, str]]:
+        """v0.14.0: ``(x, y, side)`` of each ``via=(node, side)`` waypoint — just outside
+        that side of the node (clear of its routing padding), at the side's centre."""
+        out = []
+        for node, side in self.waypoints:
+            g = node.geom
+            gap = 5.0 + self.theme.L(3.0)
+            x, y = {"top": (g.cx, g.y - gap), "bottom": (g.cx, g.bottom + gap),
+                    "left": (g.x - gap, g.cy), "right": (g.right + gap, g.cy)}[side]
+            out.append((x, y, side))
+        return out
+
+    # ---- label placement ------------------------------------------------------
+    def _custom_label(self) -> bool:
+        return any(
+            v not in (None, False)
+            for v in (self.label_at, self.label_side, self.label_bg, self.label_size,
+                      self.label_color, self.label_gap)
+        ) or bool(self.label_rotate) or self.route == "curve" or self.step is not None
+
+    def _label_fs(self, th: Theme) -> float:
+        return self.label_size if self.label_size is not None else th.font_size * 0.85
+
+    def label_geometry(
+        self,
+        pts: List[Pt],
+        theme: Optional[Theme] = None,
+        obstacles: Optional[List[Tuple[float, float, float, float]]] = None,
+        paths: Optional[Sequence[Sequence[Pt]]] = None,
+    ) -> Tuple[Tuple[float, float, float, float], float, str]:
+        """(bbox x, y, w, h), rotation, text align of the label on routed ``pts``.
+
+        ``obstacles`` (boxes) and ``paths`` (other edges) steer ``label_side='auto'``.
+        """
+        import math
+
+        th = theme or self.theme
+        fs = self._label_fs(th)
+        gap = self.label_gap if self.label_gap is not None else th.edge_label_gap * 0.6
+        if (self._custom_label() or getattr(self, "_label_unlegacy", False)) and self.route != "curve":
+            pts = _merge_collinear(pts)
+        segs = [(pts[i], pts[i + 1]) for i in range(len(pts) - 1)]
+        lens = [math.hypot(b[0] - a[0], b[1] - a[1]) for a, b in segs]
+        total = sum(lens) or 1.0
+        legacy = not self._custom_label() and not getattr(self, "_label_unlegacy", False)
+        at = self.label_at if self.label_at is not None else "mid"
+        if legacy:
+            k = min(len(pts) // 2, len(segs) - 1)
+            a, b = segs[k]
+            px, py = pts[len(pts) // 2]
+        elif isinstance(at, (int, float)) or (at == "mid" and self.route == "curve"):
+            frac = 0.5 if isinstance(at, str) else float(at)
+            target, acc, k = frac * total, 0.0, 0
+            for k, L in enumerate(lens):
+                if acc + L >= target or k == len(lens) - 1:
+                    break
+                acc += L
+            a, b = segs[k]
+            t = 0.0 if lens[k] == 0 else min(1.0, max(0.0, (target - acc) / lens[k]))
+            px, py = a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t
+        else:
+            idx = list(range(len(segs)))
+            longish = [i for i in idx if lens[i] > max(self.stub + 1.0, 0.15 * max(lens))]
+            if at == "longest":
+                k = max(idx, key=lambda i: lens[i])
+            elif at == "start":
+                k = (longish or idx)[0]
+            elif at == "end":
+                k = (longish or idx)[-1]
+            else:  # mid: middle of the path by length
+                target, acc, k = total / 2, 0.0, 0
+                for k, L in enumerate(lens):
+                    if acc + L >= target:
+                        break
+                    acc += L
+            a, b = segs[k]
+            if at == "mid":
+                t = 0.0 if lens[k] == 0 else min(1.0, max(0.0, (total / 2 - acc) / lens[k]))
+            else:
+                t = 0.5
+            px, py = a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t
+        vertical = abs(b[0] - a[0]) < abs(b[1] - a[1])
+        rot = -90.0 if (vertical and self.label_rotate) else 0.0
+        tw, tht = measure_text(self.label or "", fs)
+        bw, bh = (tht, tw) if rot else (tw, tht)
+        # a curve bulges away from its chord: push the label off the local tangent
+        # direction by the box half-extent so it never sits on the stroke
+        dx, dy = b[0] - a[0], b[1] - a[1]
+        dn = math.hypot(dx, dy) or 1.0
+        diag = self.route == "curve" and min(abs(dx), abs(dy)) / dn > 0.3
+
+        def box(side: str, px: float = px, py: float = py) -> Tuple[float, float, float, float]:
+            if side == "on":
+                return (px - bw / 2, py - bh / 2, bw, bh)
+            if diag:
+                # offset along the normal so the nearest box corner clears the curve
+                nx, ny = -dy / dn, dx / dn
+                if (side in ("above", "left") and ny > 0) or (side in ("below", "right") and ny < 0):
+                    nx, ny = -nx, -ny
+                reach = abs(nx) * bw / 2 + abs(ny) * bh / 2 + gap
+                cx, cy = px + nx * reach, py + ny * reach
+                return (cx - bw / 2, cy - bh / 2, bw, bh)
+            if side == "above":
+                return (px - bw / 2, py - gap - bh, bw, bh)
+            if side == "below":
+                return (px - bw / 2, py + gap, bw, bh)
+            if side == "left":
+                return (px - gap - bw, py - bh / 2, bw, bh)
+            return (px + gap, py - bh / 2, bw, bh)  # right
+
+        obs = obstacles or []
+        others = paths or []
+
+        def cost(bx_: Tuple[float, float, float, float]) -> float:
+            x, y, w, h = bx_
+            c = 0.0
+            for ox_, oy_, ow, oh in obs:
+                ix = min(x + w, ox_ + ow) - max(x, ox_)
+                iy = min(y + h, oy_ + oh) - max(y, oy_)
+                if ix > 0 and iy > 0:
+                    c += ix * iy
+            for p in others:
+                if len(p) >= 2 and _poly_hits_rect(p, (x - 1, y - 1, w + 2, h + 2)):
+                    c += 60.0
+            # v0.12: the label must not sit on another segment of its own edge (a
+            # label beside a short jog used to be struck by the next leg)
+            if own_check and len(pts) >= 2 and side != "on" and \
+                    _poly_hits_rect(pts, (x + 0.5, y + 0.5, max(0.0, w - 1), max(0.0, h - 1))):
+                c += 80.0
+            return c
+
+        side = "above" if legacy else (self.label_side or "auto")
+        own_check = not legacy and self.route != "curve"
+        sides = ([side] if side != "auto" else
+                 (["right", "left"] if vertical else ["above", "below"]))
+        # candidate anchor points: the requested one, then (for named label_at
+        # positions) slides along the same segment while the label still fits on it
+        anchors = [(px, py, 0.0)]
+        slide = (not legacy and not isinstance(at, (int, float)) and self.route != "curve"
+                 and self.label_side != "on")
+        if slide and (obs or others or (own_check and any(
+                cost(box(sd)) > 0 for sd in sides))):
+            seg_len = math.hypot(b[0] - a[0], b[1] - a[1])
+            along = bh if vertical else bw
+            room = (seg_len - along) / 2 - 2.0
+            if room > 2.0:
+                ux, uy = (b[0] - a[0]) / seg_len, (b[1] - a[1]) / seg_len
+                mx, my = (a[0] + b[0]) / 2, (a[1] + b[1]) / 2
+                for f in (0.25, -0.25, 0.5, -0.5, 0.75, -0.75, 1.0, -1.0):
+                    q = f * room
+                    anchors.append((mx + ux * q, my + uy * q, abs(q)))
+        best = None
+        for (ax_, ay_, shift) in anchors:
+            for sd in sides:
+                bb = box(sd, ax_, ay_)
+                c = cost(bb) + 0.05 * shift
+                if best is None or c < best[0] - 1e-9:
+                    best = (c, sd, bb)
+            if best is not None and best[0] < 1e-6:
+                break
+        if own_check and best is not None and best[0] >= 80.0 and len(segs) >= 2 and not rot:
+            # v0.12: every spot on the chosen leg sits on another leg of this edge —
+            # try the middle of the other legs (nearest first)
+            for j in sorted(range(len(segs)), key=lambda j: abs(j - k)):
+                if j == k or lens[j] < 1.0:
+                    continue
+                (qa, qb) = segs[j]
+                qv = abs(qb[0] - qa[0]) < abs(qb[1] - qa[1])
+                mx, my = (qa[0] + qb[0]) / 2, (qa[1] + qb[1]) / 2
+                ux, uy = (qb[0] - qa[0]) / lens[j], (qb[1] - qa[1]) / lens[j]
+                room = max(0.0, (lens[j] - (bh if qv else bw)) / 2 - 2.0)
+                for f in (0.0, 0.25, -0.25, 0.5, -0.5, 0.75, -0.75, 1.0, -1.0):
+                    if f and room <= 2.0:
+                        break
+                    ax_, ay_ = mx + ux * f * room, my + uy * f * room
+                    for sd in (["right", "left"] if qv else ["above", "below"]):
+                        if self.label_side not in (None, "auto") and sd != self.label_side:
+                            continue
+                        bb = box(sd, ax_, ay_)
+                        c = cost(bb) + 0.02 * abs(j - k) + 0.05 * abs(f * room)
+                        if c < best[0] - 1e-9:
+                            best = (c, sd, bb)
+                if best[0] < 1.0:
+                    break
+        _c, side, bbox = best  # type: ignore[misc]
+        if legacy and len(pts) >= 2 and _c >= 1.0 and not rot:
+            # v0.12.0: the classic mid-point label sits on a frame, another edge or a
+            # box — let it slide along its leg like an explicit label_at='mid'
+            self._label_unlegacy = True
+            try:
+                return self.label_geometry(pts, theme, obstacles, paths)
+            finally:
+                self._label_unlegacy = False
+        if legacy and len(pts) >= 2:  # v0.12.0: also a 2-point (vertical) edge
+            x, y, w, h = bbox
+            if _poly_hits_rect(pts, (x + 0.5, y + 0.5, max(0.0, w - 1), max(0.0, h - 1))):
+                # v0.12: the classic mid-point label would sit on its own edge's next
+                # leg — place it like an explicit label_at='mid' instead
+                self._label_unlegacy = True
+                try:
+                    return self.label_geometry(pts, theme, obstacles, paths)
+                finally:
+                    self._label_unlegacy = False
+        align = "center"
+        if side == "left" and not rot and not diag:
+            align = "right"
+        elif side == "right" and not rot and not diag:
+            align = "left"
+        return bbox, rot, align
+
+    def step_geometry(
+        self,
+        pts: List[Pt],
+        obstacles: Optional[Sequence[Tuple[float, float, float, float]]] = None,
+    ) -> Optional[Tuple[float, float, float]]:
+        """Centre (x, y) and diameter of this edge's step badge on routed ``pts``.
+
+        ``step_at`` picks the nominal spot (fraction of the path length, or
+        start / mid / end); if that spot covers an obstacle box the badge slides
+        along the path to the nearest free spot. None when the edge has no step.
+        """
+        import math
+
+        if self.step is None or len(pts) < 2:
+            return None
+        d = self.step.diameter()
+        lens = [math.hypot(pts[i + 1][0] - pts[i][0], pts[i + 1][1] - pts[i][1])
+                for i in range(len(pts) - 1)]
+        total = sum(lens) or 1.0
+
+        def at(dist: float) -> Pt:
+            dist = min(max(dist, 0.0), total)
+            acc = 0.0
+            for i, L in enumerate(lens):
+                if acc + L >= dist or i == len(lens) - 1:
+                    t = 0.0 if L == 0 else (dist - acc) / L
+                    a, b = pts[i], pts[i + 1]
+                    return a[0] + (b[0] - a[0]) * t, a[1] + (b[1] - a[1]) * t
+                acc += L
+            return pts[-1]
+
+        margin = d / 2 + 4.0
+        lo, hi = margin, max(margin, total - margin - 6.0)  # keep clear of the head
+        sa = self.step_at
+        if sa == "start":
+            nominal = lo + d * 0.3
+        elif sa == "end":
+            nominal = hi - d * 0.3
+        elif sa == "mid":
+            nominal = total / 2
+        else:
+            nominal = float(sa) * total
+        nominal = min(max(nominal, lo), hi)
+        obs = list(obstacles or [])
+
+        def cost(dist: float) -> float:
+            x, y = at(dist)
+            c = 0.0
+            for ox_, oy_, ow, oh in obs:
+                ix = min(x + d / 2, ox_ + ow) - max(x - d / 2, ox_)
+                iy = min(y + d / 2, oy_ + oh) - max(y - d / 2, oy_)
+                if ix > 0 and iy > 0:
+                    c += ix * iy
+            return c
+
+        best, bc = nominal, cost(nominal)
+        if bc > 0 and hi > lo:
+            n = 24
+            for k in range(1, n + 1):
+                for sgn in (1, -1):
+                    dist = nominal + sgn * (hi - lo) * k / n
+                    if lo <= dist <= hi:
+                        c = cost(dist) + 0.01 * abs(dist - nominal)
+                        if c < bc:
+                            best, bc = dist, c
+                if bc < 1.0:
+                    break
+        x, y = at(best)
+        return x, y, d
+
+    def _draw_label(self, buf, pts, th, st, obstacles, geometry=None) -> None:
+        from .primitives import Text
+        from .render_svg import draw_rect
+
+        (x, y, w, h), rot, align = geometry or self.label_geometry(pts, th, obstacles)
+        fs = self._label_fs(th)
+        bg = self.label_bg if self.label_bg is not None else None
+        if bg and bg != "none":
+            draw_rect(buf, x - 3, y - 1, w + 6, h + 2, fill=bg, stroke="none", stroke_width=0,
+                      radius=2)
+        t = Text(self.label, font_size=fs, color=self.label_color or st.color, align=align,
+                 rotate=rot, theme=th)
+        t.geom = BoxGeom(x, y, w, h)
+        t.draw(buf)
+
+
+class Fork:
+    """
+    Fan-out (``Fork(src, [dst, …])``) or fan-in (``Join([src, …], dst)``) as one
+    orthogonal tree: a trunk, a shared bus at a branch point and one branch per
+    target — the TikZ "|-" / draw.io tree look without hand-placed waypoints.
+
+    ``at`` — where the bus sits between the source side and the nearest target
+    (fraction 0..1); the router shifts it if the bus would cross a hard node.
+    ``dot=True`` marks the branch point. Style kwargs (color, width, style, head,
+    tail, head_size, hollow, …) are the same as :class:`Edge`; heads are drawn only
+    where the tree meets its targets (fork) or its single destination (join).
+    ``leaf_styles`` — optional per-leaf style overrides (one dict or None per leaf)
+    applied to that leaf's branch only, e.g. a dashed / coloured "evicted" branch.
+    """
+
+    def __init__(self, src: Union[Port, Node, Sequence[Union[Port, Node]]],
+                 dsts: Union[Port, Node, Sequence[Union[Port, Node]]], *, at: float = 0.5,
+                 dot: bool = False, dot_size: Optional[float] = None, join: bool = False,
+                 label: Optional[str] = None, labels: Optional[Sequence[Optional[str]]] = None,
+                 flow: Optional[str] = None,
+                 leaf_styles: Optional[Sequence[Optional[Dict[str, Any]]]] = None,
+                 **style: Any) -> None:
+        many_src = isinstance(src, (list, tuple))
+        many_dst = isinstance(dsts, (list, tuple))
+        if join:
+            srcs = list(src) if many_src else [src]
+            dst_list = [dsts] if not many_dst else list(dsts)
+            if len(dst_list) != 1:
+                raise ValueError("Join(srcs, dst): exactly one destination")
+            self.hub, self.leaves = dst_list[0], srcs
+        else:
+            if many_src:
+                raise ValueError("Fork(src, dsts): exactly one source")
+            self.hub, self.leaves = src, (list(dsts) if many_dst else [dsts])
+        if not self.leaves:
+            raise ValueError("Fork/Join needs at least one leaf")
+        self.join = bool(join)
+        self.at = float(at)
+        self.dot = bool(dot)
+        self.dot_size = dot_size
+        self.label = label
+        self.labels = list(labels) if labels is not None else None
+        self.flow = flow
+        self.leaf_styles = [dict(d or {}) for d in leaf_styles] if leaf_styles else None
+        if self.leaf_styles and len(self.leaf_styles) != len(self.leaves):
+            raise ValueError("leaf_styles needs one entry (dict or None) per leaf")
+        style.pop("route", None)
+        self.style = style
+        self.legend = style.pop("legend", None)
+        self._edges: List[Edge] = []
+        self._dot_at: Optional[Pt] = None
+        # style probe (validates kwargs early)
+        Edge(self._node(self.hub), self._node(self.leaves[0]), **self._style_kw())
+
+    @staticmethod
+    def _node(ref: Union[Port, Node]) -> Node:
+        return ref.node if isinstance(ref, Port) else ref
+
+    def _style_kw(self) -> Dict[str, Any]:
+        return dict(self.style)
+
+    def _flow(self) -> str:
+        """down|up|right|left from the hub towards the leaves."""
+        if self.flow:
+            return self.flow
+        if isinstance(self.hub, Port) and self.hub.kind in ("side", "aligned"):
+            d = self.hub.resolve()[2]
+            if d in _DIRV:
+                return d if not self.join else {"up": "down", "down": "up", "left": "right",
+                                                "right": "left"}[d]
+        hg = self._node(self.hub).geom
+        cx = sum(self._node(l).geom.cx for l in self.leaves) / len(self.leaves)
+        cy = sum(self._node(l).geom.cy for l in self.leaves) / len(self.leaves)
+        dx, dy = cx - hg.cx, cy - hg.cy
+        if self.join:
+            dx, dy = -dx, -dy
+        if abs(dy) >= abs(dx):
+            return "down" if dy > 0 else "up"
+        return "right" if dx > 0 else "left"
+
+    def build(self, obstacles: Sequence[Any] = ()) -> List[Tuple[Edge, List[Pt]]]:
+        """Expand into internal (Edge, points) pieces (trunk, bus, branches)."""
+        from .routing import path_cost
+
+        flow = self._flow()  # direction of travel source → targets
+        # frame: v along the flow away from the hub, u across
+        out_dir = flow if not self.join else {"up": "down", "down": "up", "left": "right",
+                                              "right": "left"}[flow]
+        # out_dir: direction from the hub towards the leaves
+        if out_dir in ("down", "up"):
+            sgn = 1.0 if out_dir == "down" else -1.0
+
+            def to_f(p: Pt) -> Pt:
+                return p[0], sgn * p[1]
+
+            def from_f(u: float, v: float) -> Pt:
+                return u, sgn * v
+            hub_side, leaf_side = ("bottom", "top") if out_dir == "down" else ("top", "bottom")
+        else:
+            sgn = 1.0 if out_dir == "right" else -1.0
+
+            def to_f(p: Pt) -> Pt:
+                return p[1], sgn * p[0]
+
+            def from_f(u: float, v: float) -> Pt:
+                return sgn * v, u
+            hub_side, leaf_side = ("right", "left") if out_dir == "right" else ("left", "right")
+        hub = _as_port(self.hub, hub_side) if isinstance(self.hub, Port) else \
+            Port(self.hub, kind="side", side=hub_side)
+        leaves = [l if isinstance(l, Port) else Port(l, kind="side", side=leaf_side)
+                  for l in self.leaves]
+        hx, hy, _ = hub.resolve()
+        hu, hv = to_f((hx, hy))
+        lr = [l.resolve() for l in leaves]
+        lf = [to_f((x, y)) for x, y, _d in lr]
+        stub = 10.0
+        near = min(v for _u, v in lf)
+        lo, hi = hv + stub, near - stub
+        if hi < lo:
+            lo = hi = (hv + near) / 2
+        us = [u for u, _v in lf] + [hu]
+        u0, u1 = min(us), max(us)
+
+        def bus_pts(vj: float) -> List[Pt]:
+            return [from_f(u0, vj), from_f(u1, vj)]
+
+        best_v, best_c = None, None
+        for f in (self.at, 0.5, 0.35, 0.65, 0.2, 0.8, 0.1, 0.9):
+            vj = lo + (hi - lo) * max(0.0, min(1.0, f))
+            pts = [from_f(hu, hv), from_f(hu, vj)] + bus_pts(vj)
+            c = path_cost(pts[:2], obstacles) + path_cost(pts[2:], obstacles) if obstacles else 0.0
+            if best_c is None or c < best_c - 1e-6:
+                best_v, best_c = vj, c
+            if c == 0:
+                break
+        vj = float(best_v)
+        kw = self._style_kw()
+        hub_node = self._node(self.hub)
+        pieces: List[Tuple[Edge, List[Pt]]] = []
+
+        def piece(a: Any, b: Any, pts: List[Pt], head: bool, label: Optional[str] = None,
+                  extra: Optional[Dict[str, Any]] = None) -> None:
+            k2 = dict(kw, **(extra or {}))
+            e = Edge(a, b, label=label, **{k: v for k, v in k2.items()
+                                           if k not in ("head", "tail", "marker_end", "marker_start")},
+                     head=k2.get("head") if head else "none", tail="none")
+            pieces.append((e, _dedupe(pts)))
+
+        trunk = [from_f(hu, hv), from_f(hu, vj)]
+        if self.join:
+            trunk = trunk[::-1]
+        bus = bus_pts(vj)
+        branches = []
+        for (lx, ly, ld), (lu, lv), leaf in zip(lr, lf, leaves):
+            dv = _DIRV.get(ld, (0.0, 0.0))
+            du_, dvv = to_f(dv)
+            if abs(du_) > 0.5:  # leaf port faces sideways: go along the bus past it, then in
+                bu = lu + (stub if du_ > 0 else -stub)
+                pts = [from_f(bu, vj), from_f(bu, lv), from_f(lu, lv)]
+            else:
+                pts = [from_f(lu, vj), from_f(lu, lv)]
+            branches.append((leaf, pts))
+        # extend the bus to sideways branch columns
+        allu = [to_f(p[0])[0] for _l, p in branches] + [hu]
+        bus = [from_f(min(allu), vj), from_f(max(allu), vj)]
+        leaf_labels = self.labels or [None] * len(branches)
+        leaf_kw = self.leaf_styles or [None] * len(branches)
+        if self.join:
+            for (leaf, pts), lab, xk in zip(branches, leaf_labels, leaf_kw):
+                piece(leaf.node, hub_node, pts[::-1], head=False, label=lab, extra=xk)
+            if abs(bus[0][0] - bus[1][0]) + abs(bus[0][1] - bus[1][1]) > 0.5:
+                piece(hub_node, hub_node, bus, head=False)
+            piece(hub_node, hub_node, trunk, head=True, label=self.label)
+        else:
+            piece(hub_node, hub_node, trunk, head=False, label=self.label)
+            if abs(bus[0][0] - bus[1][0]) + abs(bus[0][1] - bus[1][1]) > 0.5:
+                piece(hub_node, hub_node, bus, head=False)
+            for (leaf, pts), lab, xk in zip(branches, leaf_labels, leaf_kw):
+                piece(hub_node, leaf.node, pts, head=True, label=lab, extra=xk)
+        for e, _p in pieces:
+            e._fork = self  # type: ignore[attr-defined]
+        self._edges = [e for e, _p in pieces]
+        self._dot_at = from_f(hu, vj) if self.dot else None
+        return pieces
+
+
+def Join(srcs: Sequence[Union[Port, Node]], dst: Union[Port, Node], **kw: Any) -> Fork:
+    """Fan-in: several sources merge on a shared bus, one arrow into ``dst``."""
+    return Fork(srcs, dst, join=True, **kw)
+
+
+def _legs_of(e: Any) -> List[Any]:
+    legs = getattr(e, "legs", None)
+    return legs() if callable(legs) else [e]
+
+
+@dataclass
+class _CornerPort(Port):
+    """A side-corner port pushed ``zpad`` outwards on both axes (zoom outline corners)."""
+
+    zpad: float = 0.0
+
+    def resolve(self) -> Tuple[float, float, str]:
+        x, y, d = Port.resolve(self)
+        p, t = self.zpad, (self.at - 0.5) * 2 * self.zpad
+        if self.side in ("left", "right"):
+            return x + (p if self.side == "right" else -p), y + t, d
+        return x + t, y + (p if self.side == "bottom" else -p), d
+
+
+class Guide(Edge):
+    """v0.12.0: a plain helper line between two ports — zoom-in guides, "same token"
+    links, alignment hints, cross-panel correspondences.
+
+    A Guide is straight when clear and detours around text and hard nodes.
+    It has **no arrowheads** and is exempt from CF-ARR-002 (it is meant to pass over things) and
+    CF-STR-003 (its dash is a drawing convention, not a legend category).
+    Its labels are still checked like any text. Use :class:`Edge` for arrows.
+
+    Args:
+        src / dst: Ports or nodes (``node.port("right", at=0)`` for a corner).
+        style: ``"dotted"`` (default), ``"dashed"`` or ``"solid"``.
+        color: Line colour (default: the theme muted colour).
+        width: Line width (default: the theme thin stroke).
+        avoid_text: Detour around text and nodes (default True); False pins a straight guide.
+        **kw: Further :class:`Edge` options (``label=``, ``opacity=`` …).
+
+    Example:
+        >>> from codefig import Box, Guide
+        >>> a, b = Box("a"), Box("b")
+        >>> g = Guide(a.port("right", at=0), b.port("left", at=0), style="dashed")
+    """
+
+    def __init__(self, src: Any, dst: Any, *, style: str = "dotted", color: Optional[str] = None,
+                 width: Optional[float] = None, avoid_text: bool = True, **kw: Any) -> None:
+        self.avoid_text = bool(avoid_text)
+        from ._validate import check_enum
+        style = check_enum("edges(style)", style, ("dotted", "dashed", "solid"))
+        kw.setdefault("route", "straight")
+        if kw["route"] != "straight":
+            raise ValueError("a Guide is always straight; use Edge for routed connectors")
+        kw.setdefault("head", "none")
+        kw.setdefault("tail", "none")
+        kw.setdefault("marker_end", False)
+        kw.setdefault("overlap", "allow")
+        kw.setdefault("stub", 0.0)
+        kw.setdefault("align", False)
+        kw.setdefault("trunk", False)
+        kw.setdefault("knockout", False)
+        super().__init__(src, dst, style=style, color=color, width=width, **kw)
+        self.lint_ignore = ["CF-ARR-002", "CF-ARR-003", "CF-STR-003"]
+        self._cf_guide_edge = True
+
+    def resolved(self, theme: Optional[Theme] = None) -> ResolvedEdgeStyle:
+        th = theme or self.theme
+        if self.color is None and self.stroke is None:
+            self.color = getattr(th, "muted_color", "#777777")
+            try:
+                return super().resolved(theme)
+            finally:
+                self.color = None
+        return super().resolved(theme)
+
+
+class Diagram(ConstraintScope, Node):
+    """
+    Content + overlay edges. After layout: bundling → lane offsets → obstacle-aware
+    ortho/loop routing. overlap='avoid' (theme default) separates parallel trunks.
+
+    ``diagram.constrain(...)`` registers relational constraints; they are solved by
+    the enclosing Panel after flex layout and *before* edges are routed.
+
+    v0.7.0: ``regions=[Region([a, b], label="pool"), …]`` draws translucent / dashed
+    areas behind arbitrary members (they may overlap each other); see
+    :class:`~codefig.regions.Region`. ``diagram.region(members, label, **kw)`` adds one.
+    """
+
+    def __init__(
+        self,
+        content: Node,
+        edges: Optional[Sequence[Edge]] = None,
+        *,
+        regions: Optional[Sequence[Any]] = None,
+        theme: Optional[Theme] = None,
+        **kwargs: Any,
+    ) -> None:
+        if theme is not None:
+            kwargs.setdefault("theme", theme)
+        super().__init__(**kwargs)
+        self.content = content
+        content.parent = self
+        self.edges: List[Edge] = []
+        for edge in edges or []:
+            self.add_edge(edge)
+        self.regions: List[Any] = list(regions or [])
+
+    def region(self, members: Sequence[Node], label: Optional[str] = None, **kw: Any) -> Any:
+        """Add and return a :class:`~codefig.regions.Region` around ``members``."""
+        from .regions import Region
+
+        r = Region(members, label, **kw)
+        self.regions.append(r)
+        return r
+
+    def _layout_regions(self) -> None:
+        if self.regions:
+            from .regions import layout_regions
+
+            layout_regions(self, self.regions)
+
+    def add_edge(self, edge: Edge) -> "Diagram":
+        """Add an Edge/Fork, or place a spanned Brace beside its referenced node.
+
+        A Brace without a span belongs in the Row/Col content instead.
+        """
+        from .primitives import Brace
+        from .constraints import place
+        if isinstance(edge, Brace):
+            if edge.span is None:
+                raise TypeError("Diagram edges: Brace requires span=; otherwise place it in Row/Col content")
+            self.constrain(place(edge, edge.span[0], side=edge.side, offset=self.theme.L(2)))
+            return self
+        if not isinstance(edge, (Edge, Fork)):
+            raise TypeError("Diagram edges expects Edge, Fork, or Brace(span=...)")
+        self.edges.extend(_legs_of(edge))
+        return self
+
+    def zoom(self, src: Node, dst: Node, *, side: str = "right", style: str = "dashed",
+             color: Optional[str] = None, outline: bool = True,
+             pad: Optional[float] = None) -> Tuple[Any, "Guide", "Guide"]:
+        """v0.12.0: "zoom-in" callout — outline ``src`` and draw two guide lines from
+        its corners to the facing corners of ``dst`` (the enlarged detail view).
+
+        Args:
+            src: The node being magnified (a cell, a block, a group).
+            dst: The node that shows it enlarged.
+            side: Where ``dst`` sits relative to ``src``: ``"right"`` (default),
+                ``"left"``, ``"below"`` or ``"above"``.
+            style: Outline and guide dash: ``"dashed"`` (default), ``"dotted"``, ``"solid"``.
+            color: Outline / guide colour (default: the theme muted colour).
+            outline: Draw the outline around ``src`` (default True; ``False`` when
+                ``src`` already has a visible border).
+            pad: Gap between ``src`` and its outline, in pt (default: 2 design units
+                with an outline, 0 without); the guides start at the outline corners.
+
+        Returns:
+            ``(region_or_None, guide1, guide2)`` — all already added to this Diagram.
+
+        Example:
+            >>> from codefig import Box, Row, Diagram
+            >>> a, b = Box("x"), Box("detail")
+            >>> d = Diagram(Row([a, b], gap=30))
+            >>> r, g1, g2 = d.zoom(a, b)
+        """
+        from ._validate import check_enum
+        side = check_enum("edges(side)", side, ("right", "left", "below", "above"))
+        rs = {"dashed": "dashed", "dotted": "dotted", "solid": "outline"}
+        if style not in rs:
+            raise ValueError("zoom style must be dashed|dotted|solid")
+        r = None
+        pd = float(pad) if pad is not None else (self.theme.L(2.0) if outline else 0.0)
+        if outline:
+            col = color or getattr(self.theme, "muted_color", "#777777")
+            r = self.region([src], None, style=rs[style], pad=pd, radius=0.0, color=col,
+                            exclude="none")
+        out, inn = {"right": ("right", "left"), "left": ("left", "right"),
+                    "below": ("bottom", "top"), "above": ("top", "bottom")}[side]
+        g1 = Guide(_CornerPort(src, "side", out, at=0.0, zpad=pd), dst.port(inn, at=0.0),
+                   style=style, color=color)
+        g2 = Guide(_CornerPort(src, "side", out, at=1.0, zpad=pd), dst.port(inn, at=1.0),
+                   style=style, color=color)
+        self.edges += [g1, g2]
+        return r, g1, g2
+
+    def __iadd__(self, other: Union[Edge, Node]) -> "Diagram":
+        if isinstance(other, Edge):
+            self.edges.extend(_legs_of(other))
+            return self
+        raise TypeError("Diagram += expects an Edge; set content in the constructor")
+
+    def children(self) -> Sequence[Node]:
+        return (self.content,)
+
+    def _loop_margins(self) -> Tuple[float, float, float, float]:
+        """Extra space so route='loop' trunks are not clipped.
+
+        Uses loop_side (auto → right) — no port resolve during measure/layout.
+        """
+        l = t = r = b = 0.0
+        for e in self._plain_edges():
+            if e.route != "loop":
+                continue
+            pad = e.clearance + e.stub + 12.0
+            side = e.loop_side if e.loop_side != "auto" else "right"
+            if side == "right":
+                r = max(r, pad)
+            elif side == "left":
+                l = max(l, pad)
+            elif side == "bottom":
+                b = max(b, pad)
+            else:
+                t = max(t, pad)
+        return l, t, r, b
+
+    def _margins(self) -> Tuple[float, float, float, float]:
+        fit = getattr(self, "_fit_margins", None)
+        return fit if fit is not None else self._loop_margins()
+
+    def edge_overflow(self, pad: float = 3.0) -> Tuple[float, float, float, float]:
+        """How far routed edges / labels stick out of the content box (l, t, r, b)."""
+        lay = self.layout_edges()
+        xs: List[float] = []
+        ys: List[float] = []
+        for _e, pts in lay["routed"]:
+            xs += [p[0] for p in pts]
+            ys += [p[1] for p in pts]
+        for _e, _p, ((x, y, w, h), _r, _a) in lay["labels"]:
+            xs += [x, x + w]
+            ys += [y, y + h]
+        for _e, (x, y, w, h) in lay.get("steps", []):
+            xs += [x, x + w]
+            ys += [y, y + h]
+        if self.regions:
+            self._layout_regions()
+            for r in self.regions:
+                bb = r.bbox
+                if bb is not None:
+                    xs += [bb[0], bb[0] + bb[2]]
+                    ys += [bb[1], bb[1] + bb[3]]
+        g = self.content.geom
+        if not xs:
+            return 0.0, 0.0, 0.0, 0.0
+        return (max(0.0, g.x - min(xs) + pad), max(0.0, g.y - min(ys) + pad),
+                max(0.0, max(xs) - g.right + pad), max(0.0, max(ys) - g.bottom + pad))
+
+    def _measure(self) -> Tuple[float, float]:
+        w, h = self.content.measure()
+        l, t, r, b = self._margins()
+        return w + l + r, h + t + b
+
+    def _layout_children(self) -> None:
+        g = self.geom
+        l, t, r, b = self._margins()
+        self.content.layout(g.x + l, g.y + t, max(1.0, g.w - l - r), max(1.0, g.h - t - b))
+
+    def _edge_meta(self) -> List[dict]:
+        meta = []
+        for edge in self._plain_edges():
+            (x1, y1, d1), (x2, y2, d2) = edge.endpoints()
+            st = edge.resolved(theme=self.theme)
+            meta.append(
+                {
+                    "edge": edge,
+                    "x1": x1, "y1": y1, "d1": d1,
+                    "x2": x2, "y2": y2, "d2": d2,
+                    "st": st,
+                    "bundle": edge.bundle,
+                    "bundle_style": edge.bundle_style,
+                }
+            )
+        return meta
+
+    def _obstacles_for(self, edge: "Edge"):
+        from .routing import ancestors_in, collect_obstacles
+
+        exclude = []
+        try:
+            exclude.append(edge.src.node)
+            exclude.append(edge.dst.node)
+        except Exception:
+            pass
+        transparent = ancestors_in(self.content, exclude)
+        obs = collect_obstacles(self.content, exclude=exclude, pad=5.0, transparent=transparent)
+        from .policy import role_of
+        from .routing import ORect
+
+        pad = 4.0
+        for o in getattr(self, "_cf_overlay_obstacles", None) or []:
+            if any(o is x for x in exclude):
+                continue
+            g = o.geom
+            role = role_of(o) or "hard"
+            if g.w > 1 and g.h > 1 and role != "none":
+                obs.append(ORect(g.x - pad, g.y - pad, g.w + 2 * pad, g.h + 2 * pad, role))
+        return obs
+
+    def _is_back_edge(self, edge):
+        """Return whether an automatic edge travels upstream in its shared layout."""
+        if edge.route != "auto":
+            return False
+        src, dst = edge.src.node, edge.dst.node
+        ancestors = []
+        node = src.parent
+        while node is not None:
+            ancestors.append(node)
+            node = node.parent
+        node = dst.parent
+        while node is not None and node not in ancestors:
+            node = node.parent
+        a, b = src.geom, dst.geom
+        # Cross-axis siblings occupy parallel lanes even if alignment shifts
+        # their centres slightly along the main axis.
+        if src.parent is dst.parent and src.parent is not None:
+            horizontal = getattr(src.parent, "direction", "row") == "row"
+            if horizontal and min(a.y+a.h, b.y+b.h) <= max(a.y,b.y):
+                return False
+            if not horizontal and min(a.x+a.w,b.x+b.w) <= max(a.x,b.x):
+                return False
+        if getattr(node, "direction", "row") == "row":
+            return b.cx < a.cx - 1e-6
+        return b.cy < a.cy - 1e-6
+
+    def _routed(self) -> Tuple[List[Tuple[Edge, List[Pt]]], List[dict]]:
+        """Return (edge, pts) list plus bus underlay descriptors."""
+        from .routing import apply_bundling, route_channel, route_loop_avoid, route_ortho_avoid
+
+        gap = self.theme.edge_lane_gap
+        meta = self._edge_meta()
+
+        # 1) Bundling first — shared trunk for same bus id
+        bundled_pts, buses = apply_bundling(
+            meta, lane_gap=gap, style=getattr(self.theme, "edge_bundle_style", "lanes"))
+
+        # 2) Lane offsets for non-bundled avoid/ortho edges
+        base_for_lanes = []
+        for i, m in enumerate(meta):
+            e = m["edge"]
+            if bundled_pts[i] is not None:
+                base_for_lanes.append((e, bundled_pts[i]))
+            else:
+                base_for_lanes.append((e, e.points()))
+        # Only apply lane avoidance to unbundled edges
+        unbundled = [(e, p) for (e, p), bp in zip(base_for_lanes, bundled_pts) if bp is None]
+        bundled_only = [(e, p) for (e, p), bp in zip(base_for_lanes, bundled_pts) if bp is not None]
+        lanened = apply_overlap_avoidance(unbundled, lane_gap=gap, theme=self.theme)
+
+        # Rebuild in original order
+        lane_map = {id(e): pts for e, pts in lanened}
+        bundle_map = {id(e): pts for e, pts in bundled_only}
+        ordered: List[Tuple[Edge, List[Pt]]] = []
+        for m in meta:
+            e = m["edge"]
+            if id(e) in bundle_map:
+                ordered.append((e, bundle_map[id(e)]))
+            else:
+                ordered.append((e, lane_map.get(id(e), e.points())))
+
+        # 3) Obstacle-aware adjust for ortho + loop
+        final: List[Tuple[Edge, List[Pt]]] = []
+        self._curves: Dict[int, Tuple[Pt, Pt, Pt, Pt]] = {}
+        for e, pts in ordered:
+            obstacles = self._obstacles_for(e)
+            if getattr(e, "_cf_guide_edge", False) and e.avoid_text:
+                from .routing import ORect
+                # Guide geometry must remain continuous: route around text rather
+                # than cutting holes out of the guide at draw time.
+                obstacles = [ORect(*o) for o in obstacles if getattr(o, "role", "hard") != "background"]
+                obstacles += [ORect(x - self.theme.L(2), y - self.theme.L(2),
+                                    w + self.theme.L(4), h + self.theme.L(4))
+                              for x, y, w, h in self._title_boxes()]
+                if any(_poly_hits_rect(pts, o) for o in obstacles):
+                    (x1, y1, d1), (x2, y2, d2) = e.endpoints()
+                    pts = route_ortho_avoid(x1, y1, d1, x2, y2, d2,
+                                           stub=e.stub, obstacles=obstacles)
+                final.append((e, pts))
+                continue
+            from .routing import _core
+            blocked = any(getattr(o, "role", "hard") == "hard" and
+                          _poly_hits_rect(pts, _core(o)) for o in obstacles)
+            if e.route == "straight" or (e._tiny_jog() and not blocked and e.route != "back" and not self._is_back_edge(e)):
+                final.append((e, pts))
+                continue
+            if e.route == "curve":
+                ctrl = e.curve_ctrl(self._obstacles_for(e))
+                self._curves[id(e)] = ctrl
+                final.append((e, bezier_sample(ctrl)))
+                continue
+            obstacles = self._obstacles_for(e)
+            (x1, y1, d1), (x2, y2, d2) = e.endpoints()
+            if e.route == "back" or self._is_back_edge(e):
+                from .routing import route_back
+                final.append((e, route_back(x1, y1, d1, x2, y2, d2,
+                    stub=e.stub, side=e.loop_side,
+                    clearance=e.loop_gap if e.loop_gap is not None else e.theme.gap * 0.6,
+                    obstacles=obstacles, bounds=self.content.geom,
+                    container_bounds=(e.src.node.parent.geom
+                        if e.src.node.parent is e.dst.node.parent and e.src.node.parent is not None
+                        else self.content.geom))))
+                continue
+            if e.route in ("over", "under"):
+                final.append((e, route_channel(x1, y1, d1, x2, y2, d2, stub=e.stub,
+                                               over=e.route == "over", obstacles=obstacles)))
+                continue
+            if e.waypoints:
+                final.append((e, self._route_waypoints(e, (x1, y1, d1), (x2, y2, d2), obstacles)))
+                continue
+            if e.route == "loop" and e.around is not None:
+                pts2 = route_loop_around(x1, y1, d1, x2, y2, d2, e)
+                final.append((e, pts2))
+            elif e.route == "loop":
+                pts2 = route_loop_avoid(
+                    x1, y1, d1, x2, y2, d2,
+                    stub=e.stub, side=e.loop_side, clearance=e.clearance,
+                    obstacles=obstacles,
+                )
+                final.append((e, pts2))
+            elif e.route in ("ortho", "auto"):
+                from .routing import choose_clear_mid_x
+
+                if (
+                    e.bundle
+                    and len(pts) >= 4
+                    and d1 in ("left", "right")
+                    and d2 in ("left", "right")
+                ):
+                    trunk_x = pts[2][0]
+                    ax, ay = _stub(x1, y1, d1, e.stub)
+                    bx, by = _stub(x2, y2, d2, e.stub)
+                    mx = choose_clear_mid_x(ax, ay, bx, by, trunk_x, obstacles)
+                    pts2 = _dedupe(
+                        [(x1, y1), (ax, ay), (mx, ay), (mx, by), (bx, by), (x2, y2)]
+                    )
+                elif (e.bundle and len(pts) >= 4 and d1 in ("up", "down")
+                      and d2 in ("up", "down")):
+                    from .routing import choose_clear_mid_y
+
+                    trunk_y = pts[2][1]
+                    ax, ay = _stub(x1, y1, d1, e.stub)
+                    bx, by = _stub(x2, y2, d2, e.stub)
+                    my = choose_clear_mid_y(ax, ay, bx, by, trunk_y, obstacles)
+                    pts2 = _dedupe(
+                        [(x1, y1), (ax, ay), (ax, my), (bx, my), (bx, by), (x2, y2)]
+                    )
+                elif e.bundle:
+                    pts2 = route_ortho_avoid(
+                        x1, y1, d1, x2, y2, d2,
+                        stub=e.stub, mid_bias=0.0, obstacles=obstacles,
+                    )
+                else:
+                    mid_bias = 0.0
+                    if (
+                        len(pts) >= 4
+                        and d1 in ("left", "right")
+                        and d2 in ("left", "right")
+                    ):
+                        ax, _ay = _stub(x1, y1, d1, e.stub)
+                        bx, _by = _stub(x2, y2, d2, e.stub)
+                        natural = _trunk0(ax, bx, d1, d2)
+                        mid_bias = pts[2][0] - natural
+                    elif len(pts) >= 4 and d1 in ("up", "down") and d2 in ("up", "down"):
+                        _ax, ay = _stub(x1, y1, d1, e.stub)
+                        _bx, by = _stub(x2, y2, d2, e.stub)
+                        mid_bias = pts[2][1] - _trunk0(ay, by, d1, d2)
+                    pts2 = route_ortho_avoid(
+                        x1, y1, d1, x2, y2, d2,
+                        stub=e.stub, mid_bias=mid_bias,
+                        obstacles=obstacles + _end_rects(e, x1, y1, d1, x2, y2, d2),
+                    )
+                final.append((e, pts2))
+            else:
+                final.append((e, pts))
+        final = self._dejog_all(final)
+        for fork in self._forks():
+            final.extend(fork.build(self._fork_obstacles(fork)))
+        return final, buses
+
+    def _route_waypoints(self, e: "Edge", a: Tuple[float, float, str], b: Tuple[float, float, str],
+                         obstacles: list) -> List[Pt]:
+        """v0.14.0: ``Edge(via=(node, side))`` — an ortho route through points just
+        outside the named sides; the route passes the node there (over / under /
+        beside it) instead of finding its own way round."""
+        from .routing import _simplify_ortho, route_ortho_avoid
+
+        wps = e.waypoint_pts()
+        pts: List[Pt] = []
+        cur = a
+        for i, (wx, wy, side) in enumerate(wps):
+            px, py = cur[0], cur[1]
+            nx, ny = (wps[i + 1][:2] if i + 1 < len(wps) else (b[0], b[1]))
+            if side in ("top", "bottom"):  # the route crosses the waypoint horizontally
+                d_in = "left" if px <= wx else "right"
+                d_out = "right" if nx >= wx else "left"
+            else:
+                d_in = "up" if py <= wy else "down"
+                d_out = "down" if ny >= wy else "up"
+            seg = route_ortho_avoid(cur[0], cur[1], cur[2], wx, wy, d_in, stub=e.stub,
+                                    obstacles=obstacles)
+            pts.extend(seg if not pts else seg[1:])
+            cur = (wx, wy, d_out)
+        last = route_ortho_avoid(cur[0], cur[1], cur[2], b[0], b[1], b[2], stub=e.stub,
+                                 obstacles=obstacles + _end_rects(e, a[0], a[1], a[2], *b))
+        pts.extend(last[1:] if pts else last)
+        return _simplify_ortho(_dedupe(pts))
+
+    def _dejog_all(self, routed: List[Tuple[Edge, List[Pt]]]) -> List[Tuple[Edge, List[Pt]]]:
+        """v0.9.0: tidy every orthogonal route after lanes / obstacle avoidance.
+
+        1. drop duplicate and collinear vertices, folding sub-point backtracks that
+           lane shifts can leave next to a stub;
+        2. a Z route whose only cross segment is tiny (≤ L(8)) — whatever the port
+           sides — becomes one straight segment by sliding a *plain* side port (no
+           ``at=`` / ``offset=``) along its side, if the slid point stays on the side
+           (≥ L(2) from its corners), the straight segment misses every hard obstacle
+           and it does not run on top of another edge. v0.10.0: larger jogs and
+           staircase (multi-jog) routes too, while the slid port stays in the middle
+           half of its side.
+        """
+        out: List[Tuple[Edge, List[Pt]]] = []
+        paths = [pts for _e, pts in routed]
+        for i, (e, pts) in enumerate(routed):
+            if (e.route != "ortho" or getattr(e, "bundle", None) or len(pts) < 3
+                    or getattr(e, "waypoints", None)):
+                out.append((e, pts))
+                continue
+            from .routing import _absorb_jogs
+
+            tol = e.jog_tol if e.jog_tol is not None else min(6, 0.35 * self.theme.gap)
+            candidate = _absorb_jogs(pts, tol)
+            p3 = None
+            if (candidate != _simplify_ortho(pts) and candidate
+                    and candidate[0] == pts[0] and candidate[-1] == pts[-1]
+                    and not any(self._seg_blocked(e, a, b, paths[:i] + paths[i + 1:])
+                                for a, b in zip(candidate, candidate[1:]))):
+                p3 = candidate
+            if p3 is None and (candidate != _simplify_ortho(pts) or e.jog_tol is None):
+                p3 = self._straighten_z(e, _simplify_ortho(pts), paths[:i] + paths[i + 1:])
+            p2 = p3 if p3 is not None else _simplify_ortho(pts, backtracks_only=True)
+            paths[i] = p2
+            out.append((e, p2))
+        return out
+
+    def _straighten_z(self, e: "Edge", pts: List[Pt], others: List[List[Pt]]) -> Optional[List[Pt]]:
+        """One straight segment for a Z (or, v0.10.0, multi-jog) route, if safe.
+
+        The first and last runs must be parallel and head the same way, and the
+        whole route must make monotonic progress along them. A plain side port is
+        slid along its side so the two ends line up: always for a jog ≤ L(8); for a
+        larger one (v0.10.0) only when the slid point stays in the middle half of
+        the side (``0.25 ≤ at ≤ 0.75``), so the arrow still reads as attached to
+        the node's face rather than to a corner. A port with an explicit ``at=`` and
+        ``slide=s`` (v0.11.0) may move by up to ``s`` instead.
+        """
+        if len(pts) < 4:
+            return None
+        th = self.theme
+        (x0, y0), (x1, y1) = pts[0], pts[1]
+        (x2, y2), (x3, y3) = pts[-2], pts[-1]
+        h_run = abs(y0 - y1) < 1e-6 and abs(y2 - y3) < 1e-6
+        v_run = abs(x0 - x1) < 1e-6 and abs(x2 - x3) < 1e-6
+        if not (h_run or v_run):
+            return None
+        k = 1 if h_run else 0  # coordinate that the jog changes
+        jog = pts[-1][k] - pts[0][k]
+        if abs(jog) <= 0.05:
+            return None
+        # both runs must head the same way (a real Z, not a U-turn), and every
+        # run along that axis must too (no detour back)
+        d01 = pts[1][1 - k] - pts[0][1 - k]
+        d23 = pts[-1][1 - k] - pts[-2][1 - k]
+        if d01 * d23 <= 0:
+            return None
+        for u, v in zip(pts, pts[1:]):
+            if (v[1 - k] - u[1 - k]) * d01 < -1e-6:
+                return None
+        if len(pts) > 4:
+            # multi-jog: every cross run must move the same way (a staircase)
+            steps = [v[k] - u[k] for u, v in zip(pts, pts[1:]) if abs(v[k] - u[k]) > 1e-6]
+            if any(st * jog < 0 for st in steps):
+                return None
+
+        def slidable(p: Port) -> bool:
+            return p.kind == "side" and p.side in ("left", "right", "top", "bottom") and \
+                (abs(p.at - 0.5) < 1e-9 or p.slide > 0) and p.offset == 0
+
+        normal_k = 1 - k
+        cands = []
+        for port, end, t in ((e.src, 0, pts[-1][k]), (e.dst, -1, pts[0][k])):
+            if not slidable(port):
+                continue
+            # the port's side must be perpendicular to the run
+            if (port.side in ("left", "right")) != (k == 1):
+                continue
+            lo, hi = Edge._span(port, k)
+            m = th.L(2.0)
+            if not lo + m <= t <= hi - m:
+                continue
+            at = 0.5 if hi - lo < 1e-9 else (t - lo) / (hi - lo)
+            if port.slide > 0:  # explicit at= with a slide tolerance (v0.11.0)
+                if abs(at - port.at) > port.slide + 1e-9:
+                    continue
+            elif abs(jog) > th.L(8.0) and not 0.25 <= at <= 0.75:
+                continue
+            cands.append((abs(at - port.at), port, end, t))
+        for _d, port, end, t in sorted(cands, key=lambda c: c[0]):
+            q = Edge._slide(port, t, k)
+            if abs(q[k] - t) > 0.05 or abs(q[normal_k] - pts[end][normal_k]) > 0.3:
+                continue
+            new = [(q[0], q[1]), pts[-1]] if end == 0 else [pts[0], (q[0], q[1])]
+            if any(abs(q[0] - p[0]) < 0.8 and abs(q[1] - p[1]) < 0.8
+                   for path in others if path for p in (path[0], path[-1])):
+                continue
+            if self._seg_blocked(e, new[0], new[1], others):
+                continue
+            if e.label and self._label_hits(e, new, others) > self._label_hits(e, pts, others) + 0.5:
+                continue  # the straight segment leaves the label no room
+            return new
+        return None
+
+    def _label_hits(self, e: "Edge", pts: List[Pt], others: List[List[Pt]]) -> float:
+        """Area of ``e``'s label (placed on ``pts``) over leaf boxes of the diagram."""
+        from .policy import role_of
+
+        leaves: List[Tuple[float, float, float, float]] = []
+
+        def rec(n: Node) -> None:
+            kids = list(n.children())
+            if not kids and role_of(n) in ("hard", "soft"):
+                g = n.geom
+                if g.w > 0.5 and g.h > 0.5:
+                    leaves.append((g.x, g.y, g.w, g.h))
+            for k in kids:
+                rec(k)
+
+        rec(self.content)
+        try:
+            box = e.label_geometry(pts, self.theme, list(leaves), paths=others)[0]
+        except Exception:  # pragma: no cover
+            return 0.0
+        bx, by, bw, bh = box
+        tot = 0.0
+        for rx, ry, rw, rh in leaves:
+            w = min(bx + bw, rx + rw) - max(bx, rx)
+            h = min(by + bh, ry + rh) - max(by, ry)
+            if w > 0 and h > 0:
+                tot += w * h
+        return tot
+
+    def _seg_blocked(self, e: "Edge", a: Pt, b: Pt, others: List[List[Pt]]) -> bool:
+        x0, x1 = sorted((a[0], b[0]))
+        y0, y1 = sorted((a[1], b[1]))
+        ins = 0.5
+        for o in self._obstacles_for(e):
+            if getattr(o, "role", "hard") != "hard":
+                continue
+            rx, ry, rw, rh = o[0], o[1], o[2], o[3]
+            if x0 < rx + rw - ins and x1 > rx + ins and y0 < ry + rh - ins and y1 > ry + ins:
+                return True
+        tol = 0.8
+        for pts in others:
+            for (u, v) in zip(pts, pts[1:]):
+                if abs(a[1] - b[1]) < 1e-6 and abs(u[1] - v[1]) < 1e-6 and abs(u[1] - a[1]) < tol:
+                    if min(max(u[0], v[0]), x1) - max(min(u[0], v[0]), x0) > tol:
+                        return True
+                if abs(a[0] - b[0]) < 1e-6 and abs(u[0] - v[0]) < 1e-6 and abs(u[0] - a[0]) < tol:
+                    if min(max(u[1], v[1]), y1) - max(min(u[1], v[1]), y0) > tol:
+                        return True
+        return False
+
+    # ---- forks ------------------------------------------------------------------
+    def _plain_edges(self) -> List[Edge]:
+        return [e for e in self.edges if isinstance(e, Edge)]
+
+    def _forks(self) -> List[Fork]:
+        return [e for e in self.edges if isinstance(e, Fork)]
+
+    def _fork_obstacles(self, fork: Fork):
+        from .routing import ancestors_in, collect_obstacles
+
+        nodes = [fork._node(fork.hub)] + [fork._node(l) for l in fork.leaves]
+        transparent = ancestors_in(self.content, nodes)
+        return collect_obstacles(self.content, exclude=nodes, pad=5.0, transparent=transparent)
+
+    # ---- layering: knockout holes + label layout --------------------------------
+    def _soft_text_boxes(self) -> List[Tuple[Any, Tuple[float, float, float, float]]]:
+        """(node, ink box) of every soft, knockout-enabled text in content + overlays."""
+        from .policy import knockout_of, role_of
+
+        out: List[Tuple[Any, Tuple[float, float, float, float]]] = []
+
+        def add(n: Node) -> None:
+            if role_of(n) == "soft" and knockout_of(n):
+                g = n.geom
+                if g.w > 0.5 and g.h > 0.5:
+                    box = n.ink_box() if hasattr(n, "ink_box") else (g.x, g.y, g.w, g.h)
+                    out.append((n, box))
+
+        def walk(n: Node) -> None:
+            add(n)
+            for k in n.children():
+                walk(k)
+
+        walk(self.content)
+        for o in getattr(self, "_cf_overlays_all", None) or []:
+            walk(o)
+        return out
+
+    def layout_edges(self) -> Dict[str, Any]:
+        """Route every edge and place every label (no drawing). Cached per draw."""
+        for e in self._plain_edges():
+            if getattr(e, "_par_group", None):
+                e._par_assign_label()
+        routed, buses = self._routed()
+        obs = self._label_obstacles()
+        paths = [pts for _e, pts in routed]
+        steps: List[Tuple[Edge, Tuple[float, float, float, float]]] = []
+        for edge, pts in routed:
+            if getattr(edge, "step", None) is None:
+                continue
+            sg = edge.step_geometry(pts, obs)
+            if sg is not None:
+                x, y, d = sg
+                box = (x - d / 2, y - d / 2, d, d)
+                steps.append((edge, box))
+                obs.append(box)
+        labels: List[Tuple[Edge, List[Pt], Any]] = []
+        for i, (edge, pts) in enumerate(routed):
+            if edge.label:
+                others = paths[:i] + paths[i + 1:] + list(getattr(self, "_label_frames", []))
+                geo = edge.label_geometry(pts, self.theme, obs, paths=others)
+                labels.append((edge, pts, geo))
+                obs.append(geo[0])
+        from .routing import ORect, route_ortho_avoid
+        for i, (edge, pts) in enumerate(routed):
+            if getattr(edge, "_cf_guide_edge", False) and edge.avoid_text:
+                boxes = [geo[0] for owner, _, geo in labels if owner is not edge]
+                if any(_poly_hits_rect(pts, box) for box in boxes):
+                    obstacles = [ORect(*o) for o in self._obstacles_for(edge)
+                                 if getattr(o, "role", "hard") != "background"]
+                    obstacles += [ORect(*box) for box in boxes + self._title_boxes()]
+                    a, b = edge.endpoints()
+                    routed[i] = (edge, route_ortho_avoid(*a, *b, stub=edge.stub, obstacles=obstacles))
+        return {"routed": routed, "buses": buses, "labels": labels, "steps": steps}
+
+    def _holes_for(self, edge: Edge, pts: List[Pt], soft: Sequence[Any],
+                   label_boxes: Sequence[Tuple[Edge, Tuple[float, float, float, float]]]
+                   ) -> List[Tuple[float, float, float, float]]:
+        if not edge.knockout_enabled(self.theme):
+            return []
+        from .policy import knockout_enabled  # noqa: F401  (figure-level default)
+
+        pad = float(getattr(self.theme, "knockout_pad", 1.5))
+        ends = {id(edge.src.node), id(edge.dst.node)}
+        holes = []
+        for n, (x, y, w, h) in soft:
+            if id(n) in ends:
+                continue
+            r = (x - pad, y - pad, w + 2 * pad, h + 2 * pad)
+            if _poly_hits_rect(pts, r):
+                holes.append(r)
+        for owner, (x, y, w, h) in label_boxes:
+            if owner is edge and edge.label_side != "on":
+                continue
+            r = (x - pad, y - pad, w + 2 * pad, h + 2 * pad)
+            if _poly_hits_rect(pts, r):
+                holes.append(r)
+        # v0.12: an edge leaving a titled Group through its title is cut around the
+        # title text instead of striking it through
+        for (x, y, w, h) in self._title_boxes():
+            r = (x - pad, y - pad, w + 2 * pad, h + 2 * pad)
+            if _poly_hits_rect(pts, r):
+                holes.append(r)
+        return holes
+
+    def _title_boxes(self) -> List[Tuple[float, float, float, float]]:
+        from .constraints import walk
+
+        out: List[Tuple[float, float, float, float]] = []
+        trees = [self.content] + list(getattr(self, "_cf_overlays_all", None) or [])
+        for t in trees:
+            for n in walk(t):
+                tb = getattr(n, "title_boxes", None)
+                if tb is not None and getattr(n, "title", None):
+                    try:
+                        out.extend(tb())
+                    except Exception:  # pragma: no cover
+                        pass
+        return out
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_circle, draw_line
+
+        if self.regions:  # behind everything; labels after the content
+            self._layout_regions()
+            for i, r in enumerate(self.regions):
+                r.draw(buf, ox, oy, index=i)
+            for i, r in enumerate(self.regions):
+                r.draw_label(buf, ox, oy, index=i)
+        self.content.draw(buf, ox, oy)
+        lay = self.layout_edges()
+        routed, buses = lay["routed"], lay["buses"]
+        soft = self._soft_text_boxes()
+        label_boxes = [(e, geo[0]) for e, _p, geo in lay["labels"]]
+        label_boxes += [(e, box) for e, box in lay.get("steps", [])]
+        # Bus underlays first (behind individual edges)
+        for bus in buses:
+            if bus["kind"] == "v":
+                draw_line(
+                    buf,
+                    bus["x"] + ox, bus["y0"] + oy,
+                    bus["x"] + ox, bus["y1"] + oy,
+                    stroke=bus["color"],
+                    stroke_width=bus["width"],
+                    opacity=bus["opacity"],
+                )
+            else:
+                draw_line(
+                    buf,
+                    bus["x0"] + ox, bus["y"] + oy,
+                    bus["x1"] + ox, bus["y"] + oy,
+                    stroke=bus["color"],
+                    stroke_width=bus["width"],
+                    opacity=bus["opacity"],
+                )
+        curves = getattr(self, "_curves", {})
+        for edge, pts in routed:
+            holes = self._holes_for(edge, pts, soft, label_boxes)
+            holes = [(x + ox, y + oy, w, h) for x, y, w, h in holes]
+            edge.draw(buf, ox, oy, theme=self.theme, points=pts, defer_label=True,
+                      curve=curves.get(id(edge)), holes=holes)
+        for fork in self._forks():
+            if fork._dot_at is not None and fork._edges:
+                st = fork._edges[0].resolved(self.theme)
+                r = fork.dot_size if fork.dot_size is not None else max(2.2, st.width * 1.8)
+                draw_circle(buf, fork._dot_at[0] + ox, fork._dot_at[1] + oy, r, fill=st.color,
+                            stroke="none", stroke_width=0)
+        # Step badges (①) sit on their own path, above every edge line
+        for edge, (x, y, w, h) in lay.get("steps", []):
+            edge.step.paint(buf, x + w / 2 + ox, y + h / 2 + oy, w)
+        # Labels go on top of every edge path; edges passing under a label are
+        # knocked out around it (soft-text rule), so no halo colour is needed.
+        for edge, pts, geo in lay["labels"]:
+            p2 = [(x + ox, y + oy) for x, y in pts]
+            (x, y, w, h), r_, a_ = geo
+            edge._draw_label(buf, p2, self.theme, edge.resolved(self.theme), [],
+                             geometry=((x + ox, y + oy, w, h), r_, a_))
+        self._placed_labels = [geo[0] for _e, _p, geo in lay["labels"]]
+
+    def _label_obstacles(self) -> List[Tuple[float, float, float, float]]:
+        from .policy import role_of
+
+        out: List[Tuple[float, float, float, float]] = []
+        frames: List[List[Pt]] = []
+
+        def rect_poly(x: float, y: float, w: float, h: float) -> List[Pt]:
+            return [(x, y), (x + w, y), (x + w, y + h), (x, y + h), (x, y)]
+
+        def walk(n: Node) -> None:
+            role = role_of(n)
+            g0 = getattr(n, "geom", None)
+            if g0 is not None and g0.w > 0.5 and g0.h > 0.5 and role not in ("hard", "soft"):
+                # v0.12: visible frames of background containers (Group, Stacked
+                # decks) steer labels too — a label must not sit on an outline
+                st = getattr(n, "stroke", None)
+                if getattr(n, "border", None) != "none" and st and st != "none":
+                    frames.append(rect_poly(g0.x, g0.y, g0.w, g0.h))
+                elif type(n).__name__ == "Divider":
+                    if getattr(n, "orientation", "vertical") == "vertical":
+                        cx_ = g0.x + g0.w / 2
+                        frames.append([(cx_, g0.y), (cx_, g0.y + g0.h)])
+                    else:
+                        cy_ = g0.y + g0.h / 2
+                        frames.append([(g0.x, cy_), (g0.x + g0.w, cy_)])
+                elif type(n).__name__ == "Stacked":
+                    frames.append(rect_poly(g0.x, g0.y, g0.w, g0.h))
+                    fg = n.node.geom
+                    for c in range(1, n.n):
+                        frames.append(rect_poly(fg.x + n.dx * c, fg.y + n.dy * c, fg.w, fg.h))
+            if role in ("hard", "soft"):
+                g = n.geom
+                if g.w > 0.5 and g.h > 0.5:
+                    if role == "soft" and hasattr(n, "ink_box"):
+                        x, y, w, h = n.ink_box()
+                        out.append((x - 1, y - 1, w + 2, h + 2))
+                    else:
+                        out.append((g.x - 1, g.y - 1, g.w + 2, g.h + 2))
+            for k in n.children():
+                walk(k)
+
+        walk(self.content)
+        for o in getattr(self, "_cf_overlays_all", None) or []:
+            walk(o)
+        self._n_label_obs = len(out)
+        self._label_frames = frames
+        return out
+
+    def label_boxes(self) -> List[Tuple[float, float, float, float]]:
+        """Bounding boxes of every edge label (page coordinates) after layout."""
+        if getattr(self, "_placed_labels", None) is None:
+            lay = self.layout_edges()
+            self._placed_labels = [geo[0] for _e, _p, geo in lay["labels"]]
+        return list(self._placed_labels)