codefig 0.17.0__py3-none-any.whl

codefig/routing.py

@@ -0,0 +1,932 @@
+"""Obstacle-aware ortho routing and edge bundling helpers."""
+
+from __future__ import annotations
+
+import heapq
+import math as _math
+from collections import defaultdict
+from typing import Dict, List, Optional, Sequence, Tuple
+
+from .node import Node
+
+Pt = Tuple[float, float]
+Rect = Tuple[float, float, float, float]  # x, y, w, h
+
+class ORect(tuple):
+    """(x, y, w, h) obstacle rectangle carrying its layering ``role``."""
+
+    role: str = "hard"
+    pad: float = 0.0
+
+    def __new__(cls, x: float, y: float, w: float, h: float, role: str = "hard",
+                pad: float = 0.0) -> "ORect":
+        obj = super().__new__(cls, (x, y, w, h))
+        obj.role = role
+        obj.pad = pad
+        return obj
+
+
+# routing cost of crossing a non-hard obstacle (px-equivalents per crossing):
+# soft text / background regions are *preferred* to be avoided but may be crossed.
+SOFT_COST = {"hard": 10000.0, "soft": 45.0, "background": 12.0}
+
+
+def _role(r) -> str:
+    return getattr(r, "role", "hard")
+
+
+def hard_only(obstacles):
+    return [r for r in obstacles if _role(r) == "hard"]
+
+
+# Node class names treated as obstacles (visual boxes) — roles from codefig.policy
+_SOLID_TYPES = {
+    "Legend",
+    "TokenStrip",
+    "Table",
+    "Box",
+    "Matrix",
+    "Group",
+    "Brace",
+    "CircleHighlight",
+    "Callout",
+    "Text",
+    "DotGrid",
+    "Strip",
+    "Badge",
+    "BarChart",
+    "VectorFan",
+    "Swatch",
+}
+
+
+def collect_obstacles(
+    root: Node,
+    *,
+    exclude: Optional[Sequence[Node]] = None,
+    pad: float = 4.0,
+    transparent: Optional[Sequence[Node]] = None,
+) -> List[Rect]:
+    """Walk the scene graph; return inflated bboxes of solid leaf-ish nodes.
+
+    ``exclude``: whole subtrees skipped (the edge's own endpoints).
+    ``transparent``: nodes whose own box is skipped but whose children are still
+    obstacles (the endpoints' ancestors — an edge must be able to leave the
+    region it starts in). Nodes built with ``obstacle=False`` are transparent too.
+    """
+    from .policy import role_of
+
+    skip = set(id(n) for n in (exclude or ()))
+    clear = set(id(n) for n in (transparent or ()))
+    out: List[Rect] = []
+
+    def walk(n: Node) -> None:
+        if id(n) in skip:
+            # still walk children? no — whole subtree excluded (src/dst)
+            return
+        kids = list(n.children())
+        role = role_of(n)
+        see_through = id(n) in clear or role in (None, "none")
+        if not see_through:
+            g = n.geom
+            if g.w > 1 and g.h > 1:
+                out.append(ORect(g.x - pad, g.y - pad, g.w + 2 * pad, g.h + 2 * pad, role, pad))
+        for k in kids:
+            walk(k)
+
+    walk(root)
+    return out
+
+
+def ancestors_in(root: Node, targets: Sequence[Node]) -> List[Node]:
+    """All proper ancestors (within ``root``) of any node in ``targets``."""
+    want = set(id(t) for t in targets if t is not None)
+    found: List[Node] = []
+    seen: set = set()
+
+    def walk(n: Node, path: List[Node]) -> None:
+        if id(n) in want:
+            for a in path:
+                if id(a) not in seen:
+                    seen.add(id(a))
+                    found.append(a)
+        path.append(n)
+        for k in n.children():
+            walk(k, path)
+        path.pop()
+
+    walk(root, [])
+    return found
+
+
+def _v_hits_rect(mx: float, y0: float, y1: float, r: Rect) -> bool:
+    rx, ry, rw, rh = r
+    if mx < rx or mx > rx + rw:
+        return False
+    lo, hi = min(y0, y1), max(y0, y1)
+    return not (hi < ry or lo > ry + rh)
+
+
+def _h_hits_rect(my: float, x0: float, x1: float, r: Rect) -> bool:
+    rx, ry, rw, rh = r
+    if my < ry or my > ry + rh:
+        return False
+    lo, hi = min(x0, x1), max(x0, x1)
+    return not (hi < rx or lo > rx + rw)
+
+
+def _seg_hits(x1: float, y1: float, x2: float, y2: float, r: Rect) -> bool:
+    if abs(x1 - x2) < 0.51:
+        return _v_hits_rect(x1, y1, y2, r)
+    if abs(y1 - y2) < 0.51:
+        return _h_hits_rect(y1, x1, x2, r)
+    return seg_rect_intersect((x1, y1), (x2, y2), r)
+
+
+# cost of only grazing an obstacle's clearance ring (padding), not the node itself
+PAD_GRAZE_COST = 30.0
+
+
+def _core(r: Rect) -> Rect:
+    p = getattr(r, "pad", 0.0)
+    x, y, w, h = r
+    return (x + p, y + p, max(0.0, w - 2 * p), max(0.0, h - 2 * p))
+
+
+def _legs_cost(pts: List[Pt], obstacles: List[Rect]) -> float:
+    """Per-obstacle crossing cost of a polyline; padding-only grazes are cheap."""
+    c = 0.0
+    for r in obstacles:
+        segs = [(pts[i][0], pts[i][1], pts[i + 1][0], pts[i + 1][1]) for i in range(len(pts) - 1)]
+        if not any(_seg_hits(*sg, r) for sg in segs):
+            continue
+        w = SOFT_COST.get(_role(r), 10000.0)
+        if getattr(r, "pad", 0.0) > 0 and not any(_seg_hits(*sg, _core(r)) for sg in segs):
+            w = min(w, PAD_GRAZE_COST)
+        c += w
+    return c
+
+
+def seg_rect_intersect(p: Pt, q: Pt, r: Rect) -> bool:
+    """Liang–Barsky: does segment p→q touch rect r = (x, y, w, h)?"""
+    rx, ry, rw, rh = r
+    x0, y0 = p
+    dx, dy = q[0] - x0, q[1] - y0
+    t0, t1 = 0.0, 1.0
+    for pp, qq in ((-dx, x0 - rx), (dx, rx + rw - x0), (-dy, y0 - ry), (dy, ry + rh - y0)):
+        if abs(pp) < 1e-12:
+            if qq < 0:
+                return False
+            continue
+        t = qq / pp
+        if pp < 0:
+            t0 = max(t0, t)
+        else:
+            t1 = min(t1, t)
+        if t0 > t1:
+            return False
+    return True
+
+
+def _path_hits(pts: List[Pt], obstacles: List[Rect], roles: Tuple[str, ...] = ("hard",)) -> int:
+    """Number of (segment, obstacle) crossings, counting obstacles with ``roles``."""
+    hits = 0
+    for i in range(len(pts) - 1):
+        x1, y1 = pts[i]
+        x2, y2 = pts[i + 1]
+        for r in obstacles:
+            if _role(r) in roles and _seg_hits(x1, y1, x2, y2, r):
+                hits += 1
+    return hits
+
+
+def path_cost(pts: List[Pt], obstacles: List[Rect]) -> float:
+    """Weighted crossings: hard ≫ soft text > background region (see SOFT_COST)."""
+    c = 0.0
+    for r in obstacles:
+        w = SOFT_COST.get(_role(r), 10000.0)
+        if any(_seg_hits(pts[i][0], pts[i][1], pts[i + 1][0], pts[i + 1][1], r)
+               for i in range(len(pts) - 1)):
+            c += w
+    return c
+
+
+def choose_clear_mid_x(
+    ax: float,
+    ay: float,
+    bx: float,
+    by: float,
+    prefer: float,
+    obstacles: List[Rect],
+) -> float:
+    """Pick a vertical-trunk x that clears obstacles between ay..by."""
+    y0, y1 = min(ay, by), max(ay, by)
+    lo, hi = min(ax, bx), max(ax, bx)
+    cands = [prefer, (ax + bx) / 2.0, lo - 8.0, hi + 8.0]
+    for rx, ry, rw, rh in obstacles:
+        if ry + rh < y0 or ry > y1:
+            continue
+        cands.append(rx - 2.0)
+        cands.append(rx + rw + 2.0)
+    # de-dupe roughly
+    uniq = []
+    for c in cands:
+        if not any(abs(c - u) < 0.5 for u in uniq):
+            uniq.append(c)
+
+    def cost(mx: float) -> float:
+        # whole path (stub legs included), not just the trunk (v0.7.0)
+        return _legs_cost([(ax, ay), (mx, ay), (mx, by), (bx, by)], obstacles) + abs(mx - prefer)
+
+    return min(uniq, key=cost)
+
+
+def choose_clear_mid_y(
+    ax: float,
+    ay: float,
+    bx: float,
+    by: float,
+    prefer: float,
+    obstacles: List[Rect],
+) -> float:
+    x0, x1 = min(ax, bx), max(ax, bx)
+    lo, hi = min(ay, by), max(ay, by)
+    cands = [prefer, (ay + by) / 2.0, lo - 8.0, hi + 8.0]
+    for rx, ry, rw, rh in obstacles:
+        if rx + rw < x0 or rx > x1:
+            continue
+        cands.append(ry - 2.0)
+        cands.append(ry + rh + 2.0)
+    uniq = []
+    for c in cands:
+        if not any(abs(c - u) < 0.5 for u in uniq):
+            uniq.append(c)
+
+    def cost(my: float) -> float:
+        # whole path (stub legs included), not just the trunk (v0.7.0)
+        return _legs_cost([(ax, ay), (ax, my), (bx, my), (bx, by)], obstacles) + abs(my - prefer)
+
+    return min(uniq, key=cost)
+
+
+def _visibility_route(a, b, obstacles):
+    """Exact rectilinear fallback when a sampled grid misses narrow blockers."""
+    from .styles import current_theme
+    clearance = current_theme().L(2)
+    boxes = [_core(o) for o in hard_only(obstacles)]
+    xs = sorted({a[0], b[0]} | {v for x, y, w, h in boxes for v in (x-clearance, x+w+clearance)})
+    ys = sorted({a[1], b[1]} | {v for x, y, w, h in boxes for v in (y-clearance, y+h+clearance)})
+    start, goal = (xs.index(a[0]), ys.index(a[1])), (xs.index(b[0]), ys.index(b[1]))
+    queue, costs, previous = [(0.0, start)], {start: 0.0}, {}
+    while queue:
+        cost, point = heapq.heappop(queue)
+        if cost != costs[point]:
+            continue
+        if point == goal:
+            path = [b]
+            while point != start:
+                point = previous[point]
+                path.append((xs[point[0]], ys[point[1]]))
+            return _simplify_ortho(list(reversed(path)))
+        i, j = point
+        p = (xs[i], ys[j])
+        for ni, nj in ((i-1,j), (i+1,j), (i,j-1), (i,j+1)):
+            if not (0 <= ni < len(xs) and 0 <= nj < len(ys)):
+                continue
+            q = (xs[ni], ys[nj])
+            if any(seg_rect_intersect(p, q, r) for r in boxes):
+                continue
+            value = cost + abs(q[0]-p[0]) + abs(q[1]-p[1])
+            if value < costs.get((ni,nj), float("inf")):
+                costs[ni,nj] = value
+                previous[ni,nj] = point
+                heapq.heappush(queue, (value, (ni,nj)))
+    return None
+
+
+def route_ortho_avoid(
+    x1: float,
+    y1: float,
+    d1: str,
+    x2: float,
+    y2: float,
+    d2: str,
+    *,
+    stub: float = 12.0,
+    mid_bias: float = 0.0,
+    obstacles: Optional[List[Rect]] = None,
+    route_ortho_fn=None,
+    stub_fn=None,
+    use_astar: bool = True,
+    astar_cell: float = 10.0,
+) -> List[Pt]:
+    """
+    Obstacle-aware Manhattan route.
+
+    1. Mid-shift: stub→mid→stub with mid chosen to clear boxes (lane mid_bias).
+    2. If the mid-shift path still hits obstacles and use_astar, run 4-connected
+       grid A* between stubs (bend penalty), simplify collinear points.
+    3. Fall back to mid-shift if A* fails or finds no improvement.
+    """
+    from .edges import _dedupe, _facing_stub, _stub, _trunk0, route_ortho
+
+    obstacles = obstacles or []
+    facing = {("down", "up"): y2 - y1, ("up", "down"): y1 - y2,
+              ("right", "left"): x2 - x1,
+              ("left", "right"): x1 - x2}.get((d1, d2), 0.0) > 0.0
+    stub = _facing_stub(x1, y1, d1, x2, y2, d2, stub)
+    base = route_ortho(x1, y1, d1, x2, y2, d2, stub=stub, mid_bias=mid_bias)
+    if not obstacles:
+        return base
+
+    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:
+        prefer = _trunk0(ax, bx, d1, d2) + mid_bias
+        mx = choose_clear_mid_x(ax, ay, bx, by, prefer, obstacles)
+        mid_pts = _dedupe([(x1, y1), (ax, ay), (mx, ay), (mx, by), (bx, by), (x2, y2)])
+    elif (not horiz_src) and (not horiz_dst):
+        prefer = _trunk0(ay, by, d1, d2) + mid_bias
+        my = choose_clear_mid_y(ax, ay, bx, by, prefer, obstacles)
+        mid_pts = _dedupe([(x1, y1), (ax, ay), (ax, my), (bx, my), (bx, by), (x2, y2)])
+    else:
+        mid_pts = base
+
+    mid_hits = _path_hits(mid_pts, obstacles)
+    if mid_hits == 0 or not use_astar:
+        return mid_pts
+    if facing and _legs_cost(mid_pts, obstacles) < PAD_GRAZE_COST * 8:
+        # Facing ports across a gap narrower than the clearance padding (e.g. a
+        # WrapFlow z-mode row change): the in-gap trunk only grazes padding, whereas
+        # the grid A* detour loops around the whole row. Keep the gap (v0.7.0).
+        return mid_pts
+
+    astar_core = route_ortho_astar(ax, ay, bx, by, hard_only(obstacles), cell=astar_cell)
+    astar_pts = _dedupe([(x1, y1)] + list(astar_core or []) + [(x2, y2)])
+    if not astar_core or _path_hits(astar_pts, [_core(o) for o in hard_only(obstacles)]):
+        exact = _visibility_route((ax, ay), (bx, by), obstacles)
+        if exact:
+            astar_pts = _dedupe([(x1, y1)] + exact + [(x2, y2)])
+        elif not astar_core:
+            return mid_pts
+    cores = [_core(o) for o in hard_only(obstacles)]
+    if _path_hits(astar_pts, cores) < _path_hits(mid_pts, cores):
+        return astar_pts
+    if _path_hits(astar_pts, obstacles) < mid_hits:
+        return astar_pts
+    # Prefer A* if equal hits but more corners cleared a blocking box
+    if _path_hits(astar_pts, obstacles) == 0:
+        return astar_pts
+    return mid_pts
+
+
+def route_loop_avoid(
+    x1: float,
+    y1: float,
+    d1: str,
+    x2: float,
+    y2: float,
+    d2: str,
+    *,
+    stub: float = 12.0,
+    side: str = "auto",
+    clearance: float = 40.0,
+    obstacles: Optional[List[Rect]] = None,
+) -> List[Pt]:
+    """Loop route; push clearance outward until the trunk clears obstacles."""
+    from .edges import route_loop, _stub, _dedupe
+
+    obstacles = obstacles or []
+    pts = route_loop(
+        x1, y1, d1, x2, y2, d2, stub=stub, side=side, clearance=clearance
+    )
+    if not obstacles:
+        return pts
+
+    # Resolve effective side
+    eff = side
+    if eff == "auto":
+        if d1 == d2 and d1 in ("left", "right", "up", "down"):
+            eff = {"right": "right", "left": "left", "up": "top", "down": "bottom"}[d1]
+        else:
+            eff = "right"
+
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+    clear = clearance
+    for _ in range(8):
+        if eff == "right":
+            trunk = max(ax, bx, x1, x2) + clear
+            cand = [(x1, y1), (ax, ay), (trunk, ay), (trunk, by), (bx, by), (x2, y2)]
+        elif eff == "left":
+            trunk = min(ax, bx, x1, x2) - clear
+            cand = [(x1, y1), (ax, ay), (trunk, ay), (trunk, by), (bx, by), (x2, y2)]
+        elif eff == "bottom":
+            trunk = max(ay, by, y1, y2) + clear
+            cand = [(x1, y1), (ax, ay), (ax, trunk), (bx, trunk), (bx, by), (x2, y2)]
+        else:
+            trunk = min(ay, by, y1, y2) - clear
+            cand = [(x1, y1), (ax, ay), (ax, trunk), (bx, trunk), (bx, by), (x2, y2)]
+        cand = _dedupe(cand)
+        # a feedback loop goes *around* the content, so framed groups count too
+        if _path_hits(cand, obstacles, ("hard", "background")) == 0:
+            return cand
+        clear += 14.0
+    return cand
+
+
+
+# ---- A* / maze-style ortho routing ----------------------------------------
+
+
+def _point_in_rect(x: float, y: float, r: Rect, inset: float = 0.0) -> bool:
+    rx, ry, rw, rh = r
+    return (rx + inset) <= x <= (rx + rw - inset) and (ry + inset) <= y <= (ry + rh - inset)
+
+
+def _cell_blocked(cx: float, cy: float, obstacles: List[Rect], cell: float) -> bool:
+    # Treat cell center as blocked if inside any obstacle
+    for r in obstacles:
+        if _point_in_rect(cx, cy, r, inset=0.0):
+            return True
+    return False
+
+
+def _simplify_ortho(pts: List[Pt]) -> List[Pt]:
+    """Drop collinear intermediate points on an ortho polyline."""
+    if len(pts) <= 2:
+        return list(pts)
+    out: List[Pt] = [pts[0]]
+    for i in range(1, len(pts) - 1):
+        x0, y0 = out[-1]
+        x1, y1 = pts[i]
+        x2, y2 = pts[i + 1]
+        if abs(x1 - x0) < 0.01 and abs(y1 - y0) < 0.01:
+            continue
+        same_h = abs(y0 - y1) < 0.01 and abs(y1 - y2) < 0.01
+        same_v = abs(x0 - x1) < 0.01 and abs(x1 - x2) < 0.01
+        if same_h or same_v:
+            continue
+        out.append(pts[i])
+    last = pts[-1]
+    if abs(out[-1][0] - last[0]) > 0.01 or abs(out[-1][1] - last[1]) > 0.01:
+        out.append(last)
+    return out
+
+
+def _absorb_jogs(path: List[Pt], tol: float) -> List[Pt]:
+    """Propose a terminal jog collapse; caller validates endpoint movement.
+
+    Returns a fresh path. Port permissions and collision checks require the
+    diagram context and must be checked before accepting this proposal.
+    """
+    pts = _simplify_ortho(path)
+    for i in range(1, len(pts) - 3):
+        a, b, c, d, end = pts[i - 1:i + 4]
+        for k in (0, 1):
+            n = 1 - k
+            if (a[k] == b[k] == end[k] and c[k] == d[k]
+                    and b[n] == c[n] and d[n] == end[n]
+                    and 0 < abs(c[k] - b[k]) < tol
+                    and (b[n] - a[n]) * (d[n] - c[n]) > 0):
+                return _absorb_jogs(pts[:i] + [end] + pts[i + 4:], tol)
+    if len(pts) == 4:
+        a, b, c, d = pts
+        for k in (0, 1):
+            n = 1 - k
+            jog = abs(c[k] - b[k])
+            if (a[k] == b[k] and c[k] == d[k] and b[n] == c[n]
+                    and 0 < jog < tol
+                    and min(abs(b[n] - a[n]), abs(d[n] - c[n])) > jog
+                    and (b[n] - a[n]) * (d[n] - c[n]) > 0):
+                q = list(a)
+                q[k] = d[k]
+                return [tuple(q), d]
+    return pts
+
+
+def _snap_ortho_ends(pts: List[Pt], a: Pt, b: Pt) -> List[Pt]:
+    """Move the first/last grid runs onto the exact stub coordinates so every
+    segment stays axis-aligned (snapping only the endpoints made diagonals)."""
+    pts = [tuple(p) for p in pts]
+    if len(pts) < 2:
+        return [a, b] if (abs(a[0] - b[0]) < 0.01 or abs(a[1] - b[1]) < 0.01) else [a, (b[0], a[1]), b]
+    # start run
+    if abs(pts[0][1] - pts[1][1]) < 0.01:  # horizontal
+        pts[1] = (pts[1][0], a[1])
+    else:
+        pts[1] = (a[0], pts[1][1])
+    pts[0] = a
+    # end run
+    if len(pts) >= 3:
+        if abs(pts[-1][1] - pts[-2][1]) < 0.01:
+            pts[-2] = (pts[-2][0], b[1])
+        else:
+            pts[-2] = (b[0], pts[-2][1])
+    pts[-1] = b
+    # safety: insert elbows for any remaining diagonal pair
+    out: List[Pt] = [pts[0]]
+    for p in pts[1:]:
+        q = out[-1]
+        if abs(p[0] - q[0]) > 0.01 and abs(p[1] - q[1]) > 0.01:
+            out.append((p[0], q[1]))
+        out.append(p)
+    return _simplify_ortho(out)
+
+
+def route_ortho_astar(
+    ax: float,
+    ay: float,
+    bx: float,
+    by: float,
+    obstacles: List[Rect],
+    *,
+    cell: float = 10.0,
+    max_cells: int = 10000,
+) -> Optional[List[Pt]]:
+    """
+    4-connected grid A* from (ax,ay) to (bx,by), avoiding obstacle rects.
+
+    Returns polyline of cell centers (including start/end snapped), or None.
+    """
+    if cell < 4.0:
+        cell = 4.0
+    # Bounding box with margin
+    xs = [ax, bx]
+    ys = [ay, by]
+    for rx, ry, rw, rh in obstacles:
+        xs.extend([rx, rx + rw])
+        ys.extend([ry, ry + rh])
+    margin = cell * 3
+    min_x, max_x = min(xs) - margin, max(xs) + margin
+    min_y, max_y = min(ys) - margin, max(ys) + margin
+    cols = int(_math.ceil((max_x - min_x) / cell)) + 1
+    rows = int(_math.ceil((max_y - min_y) / cell)) + 1
+    if cols * rows > max_cells:
+        # coarsen
+        scale = _math.sqrt((cols * rows) / max_cells)
+        cell = cell * scale
+        cols = int(_math.ceil((max_x - min_x) / cell)) + 1
+        rows = int(_math.ceil((max_y - min_y) / cell)) + 1
+        if cols * rows > max_cells * 1.5:
+            return None
+
+    def to_ij(x: float, y: float) -> Tuple[int, int]:
+        return (
+            int(round((x - min_x) / cell)),
+            int(round((y - min_y) / cell)),
+        )
+
+    def to_xy(i: int, j: int) -> Pt:
+        return min_x + i * cell, min_y + j * cell
+
+    si, sj = to_ij(ax, ay)
+    gi, gj = to_ij(bx, by)
+    si = max(0, min(cols - 1, si))
+    sj = max(0, min(rows - 1, sj))
+    gi = max(0, min(cols - 1, gi))
+    gj = max(0, min(rows - 1, gj))
+
+    blocked = set()
+    for i in range(cols):
+        for j in range(rows):
+            cx, cy = to_xy(i, j)
+            if _cell_blocked(cx, cy, obstacles, cell):
+                blocked.add((i, j))
+    # Never block start/goal
+    blocked.discard((si, sj))
+    blocked.discard((gi, gj))
+
+    def h(i: int, j: int) -> float:
+        return abs(i - gi) + abs(j - gj)
+
+    open_h: List[Tuple[float, int, int, int]] = []  # f, tie, i, j
+    heapq.heappush(open_h, (h(si, sj), 0, si, sj))
+    came: Dict[Tuple[int, int], Tuple[int, int]] = {}
+    gscore = {(si, sj): 0.0}
+    closed = set()
+    tie = 0
+    dirs = ((1, 0), (-1, 0), (0, 1), (0, -1))
+
+    while open_h:
+        _f, _, i, j = heapq.heappop(open_h)
+        if (i, j) in closed:
+            continue
+        closed.add((i, j))
+        if i == gi and j == gj:
+            # reconstruct
+            path_ij = [(i, j)]
+            while (i, j) in came:
+                i, j = came[(i, j)]
+                path_ij.append((i, j))
+            path_ij.reverse()
+            pts = _simplify_ortho([to_xy(ii, jj) for ii, jj in path_ij])
+            return _snap_ortho_ends(pts, (ax, ay), (bx, by))
+        for di, dj in dirs:
+            ni, nj = i + di, j + dj
+            if ni < 0 or nj < 0 or ni >= cols or nj >= rows:
+                continue
+            if (ni, nj) in blocked or (ni, nj) in closed:
+                continue
+            # bend penalty: prefer straight
+            ng = gscore[(i, j)] + 1.0
+            if (i, j) in came:
+                pi, pj = came[(i, j)]
+                if (i - pi, j - pj) != (di, dj):
+                    ng += 0.15
+            if ng < gscore.get((ni, nj), 1e18):
+                gscore[(ni, nj)] = ng
+                came[(ni, nj)] = (i, j)
+                tie += 1
+                heapq.heappush(open_h, (ng + h(ni, nj), tie, ni, nj))
+    return None
+
+
+
+def _seg_cross(p1: Pt, p2: Pt, q1: Pt, q2: Pt) -> bool:
+    """Proper crossing of two axis-aligned segments (touching ends / collinear = no)."""
+    ph = abs(p1[1] - p2[1]) < 1e-6
+    qh = abs(q1[1] - q2[1]) < 1e-6
+    if ph == qh:
+        return False
+    if not ph:
+        p1, p2, q1, q2 = q1, q2, p1, p2  # p horizontal, q vertical
+    y = p1[1]
+    x = q1[0]
+    x0, x1 = sorted((p1[0], p2[0]))
+    y0, y1 = sorted((q1[1], q2[1]))
+    e = 0.3
+    return x0 + e < x < x1 - e and y0 + e < y < y1 - e
+
+
+def count_crossings(paths: Sequence[Sequence[Pt]]) -> int:
+    """Number of proper crossings between axis-aligned polylines (pairs of paths)."""
+    segs = [[(pts[k], pts[k + 1]) for k in range(len(pts) - 1)] for pts in paths]
+    c = 0
+    for i in range(len(segs)):
+        for j in range(i + 1, len(segs)):
+            for a in segs[i]:
+                for b in segs[j]:
+                    if _seg_cross(a[0], a[1], b[0], b[1]):
+                        c += 1
+    return c
+
+
+def _lane_order(items: List[Tuple[float, float, float, float]], lanes: List[float],
+                build) -> List[int]:
+    """Assign lanes (positions ``lanes``) to edges minimising pairwise crossings.
+
+    ``items`` = (u_src, v_src, u_dst, v_dst) in the bundle frame; ``build(i, lane)``
+    returns edge i's polyline. Brute force up to 7 edges, else sort + 2-opt."""
+    import itertools
+
+    n = len(items)
+    if n <= 1:
+        return list(range(n))
+
+    def cost(perm: Sequence[int]) -> Tuple[int, float]:
+        paths = [build(i, lanes[perm[i]]) for i in range(n)]
+        # tie-break: keep lanes in source order (stable, predictable)
+        disorder = sum(abs(perm[i] - i) for i in range(n))
+        return count_crossings(paths), disorder
+
+    base = sorted(range(n), key=lambda i: (items[i][1], items[i][3]))
+    if n <= 7:
+        best = None
+        best_c = None
+        for perm_l in itertools.permutations(range(n)):
+            perm = [0] * n
+            for rank, e in enumerate(base):
+                perm[e] = perm_l[rank]
+            c = cost(perm)
+            if best_c is None or c < best_c:
+                best, best_c = perm, c
+                if c[0] == 0 and c[1] == 0:
+                    break
+        return list(best or range(n))
+    perm = [0] * n
+    for rank, e in enumerate(base):
+        perm[e] = rank
+    cur = cost(perm)
+    improved = True
+    while improved:
+        improved = False
+        for a in range(n):
+            for b in range(a + 1, n):
+                perm[a], perm[b] = perm[b], perm[a]
+                c = cost(perm)
+                if c < cur:
+                    cur, improved = c, True
+                else:
+                    perm[a], perm[b] = perm[b], perm[a]
+    return perm
+
+
+def apply_bundling(
+    edges_meta: List[dict],
+    *,
+    lane_gap: float = 7.0,
+    style: str = "lanes",
+) -> Tuple[List[Optional[List[Pt]]], List[dict]]:
+    """
+    Group edges that share the same ``bundle`` id.
+
+    Styles (per edge ``bundle_style=`` or the theme ``edge_bundle_style``):
+
+    * ``"lanes"`` (default, v0.7.0): the edges run as parallel, evenly spaced trunks
+      (``edge_lane_gap`` apart) centred on the median natural mid; the lane order is
+      chosen to minimise edge–edge crossings. No underlay.
+    * ``"merge"``: every edge uses one shared trunk (overlapping), no underlay.
+    * ``"bus"``: the shared trunk plus a thick semi-transparent underlay (pre-0.7 look).
+
+    Returns (pts_or_None per meta index, list of bus underlay descriptors).
+    """
+    from .edges import _stub, _dedupe
+
+    n = len(edges_meta)
+    pts_out: List[Optional[List[Pt]]] = [None] * n
+    buses: List[dict] = []
+
+    groups: Dict[str, List[int]] = defaultdict(list)
+    for i, m in enumerate(edges_meta):
+        key = m.get("bundle")
+        if key:
+            groups[str(key)].append(i)
+
+    for key, idxs in groups.items():
+        if len(idxs) < 2:
+            continue
+        sample = edges_meta[idxs[0]]
+        d1, d2 = sample["d1"], sample["d2"]
+        horiz = d1 in ("left", "right") and d2 in ("left", "right")
+        vert = d1 in ("up", "down") and d2 in ("up", "down")
+        if not (horiz or vert):
+            continue
+        gstyle = next((edges_meta[i].get("bundle_style") for i in idxs
+                       if edges_meta[i].get("bundle_style")), None) or style
+        if gstyle not in ("lanes", "merge", "bus"):
+            raise ValueError(f"bundle_style must be lanes|merge|bus, got {gstyle!r}")
+
+        # bundle frame: u = along the flow (x for horizontal), v = across
+        def fr(x: float, y: float) -> Tuple[float, float]:
+            return (x, y) if horiz else (y, x)
+
+        def to(u: float, v: float) -> Pt:
+            return (u, v) if horiz else (v, u)
+
+        items = []
+        for i in idxs:
+            m = edges_meta[i]
+            e = m["edge"]
+            ax, ay = _stub(m["x1"], m["y1"], m["d1"], e.stub)
+            bx, by = _stub(m["x2"], m["y2"], m["d2"], e.stub)
+            au, av = fr(ax, ay)
+            bu, bv = fr(bx, by)
+            items.append((au, av, bu, bv))
+        mids = sorted((au + bu) / 2.0 for au, _av, bu, _bv in items)
+        trunk = mids[len(mids) // 2]
+        color = None
+        width = 1.5
+        for i in idxs:
+            st = edges_meta[i]["st"]
+            color = color or st.color
+            width = max(width, st.width)
+
+        def path(k: int, lane: float) -> List[Pt]:
+            m = edges_meta[idxs[k]]
+            au, av, bu, bv = items[k]
+            p1 = (m["x1"], m["y1"])
+            p2 = (m["x2"], m["y2"])
+            if abs(av - bv) < 0.5:  # already in line: one straight run
+                return _dedupe([p1, to(au, av), to(bu, bv), p2])
+            return _dedupe([p1, to(au, av), to(lane, av), to(lane, bv), to(bu, bv), p2])
+
+        if gstyle == "lanes":
+            bent = [k for k in range(len(idxs)) if abs(items[k][1] - items[k][3]) >= 0.5]
+            nb = len(bent)
+            gap = float(lane_gap)
+            lo = max(it[0] for it in items) if items else trunk
+            hi = min(it[2] for it in items) if items else trunk
+            if lo > hi:
+                lo, hi = hi, lo
+            span = gap * max(0, nb - 1)
+            if hi - lo >= span:  # keep every lane between the stubs when there is room
+                trunk = min(max(trunk, lo + span / 2), hi - span / 2)
+            elif nb > 1:
+                gap = max((hi - lo) / (nb - 1), 0.5 * float(lane_gap))
+                span = gap * (nb - 1)
+                trunk = (lo + hi) / 2
+            lanes = [trunk - span / 2 + gap * r for r in range(nb)]
+            sub = [items[k] for k in bent]
+            perm = _lane_order(sub, lanes, lambda j, lane: path(bent[j], lane)) if nb else []
+            lane_of = {bent[j]: lanes[perm[j]] for j in range(nb)}
+            for k, i in enumerate(idxs):
+                pts_out[i] = path(k, lane_of.get(k, trunk))
+            continue
+
+        for k, i in enumerate(idxs):
+            pts_out[i] = path(k, trunk)
+        if gstyle != "bus":
+            continue
+        vs = [v for it in items for v in (it[1], it[3])]
+        if horiz:
+            buses.append({"kind": "v", "x": trunk, "y0": min(vs), "y1": max(vs),
+                          "color": color or "#111", "width": width * 2.8, "opacity": 0.3,
+                          "bundle": key})
+        else:
+            buses.append({"kind": "h", "y": trunk, "x0": min(vs), "x1": max(vs),
+                          "color": color or "#111", "width": width * 2.8, "opacity": 0.3,
+                          "bundle": key})
+
+    return pts_out, buses
+
+
+def route_channel(x1: float, y1: float, d1: str, x2: float, y2: float, d2: str, *,
+                  stub: float = 12.0, over: bool = True,
+                  obstacles: Optional[List[Rect]] = None) -> List[Pt]:
+    """v0.14.0: ``Edge(route="over" | "under")`` — leave the source, rise (or drop) to one
+    horizontal trunk just clear of every hard obstacle between the two ends, run across
+    and come down (up) into the target. Readers see one bracket instead of a detour
+    that winds between boxes."""
+    from .edges import _dedupe, _stub
+
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+    hard = hard_only(obstacles or [])
+    level = min(ay, by) if over else max(ay, by)
+    for _ in range(40):
+        segs = [((ax, ay), (ax, level)), ((ax, level), (bx, level)), ((bx, level), (bx, by))]
+        hit = [r for r in hard for (p, q) in segs if _seg_hits(p[0], p[1], q[0], q[1], r)]
+        if not hit:
+            break
+        level = (min(r[1] for r in hit) - 0.5) if over else (max(r[1] + r[3] for r in hit) + 0.5)
+    pts = _dedupe([(x1, y1), (ax, ay), (ax, level), (bx, level), (bx, by), (x2, y2)])
+    return _simplify_ortho(pts)
+
+
+def route_back(x1, y1, d1, x2, y2, d2, *, stub, side="auto", clearance=6.0,
+               obstacles=None, bounds=None, container_bounds=None):
+    """Choose a feedback corridor, penalizing collisions and boundary expansion."""
+    from .edges import _stub, _dedupe
+    obstacles = obstacles or []
+    sides = ("top", "bottom", "left", "right")
+    if side not in ("auto", *sides):
+        raise ValueError("loop_side must be auto, top, bottom, left, right")
+    def expansion(path, box):
+        if box is None:
+            return 0.0
+        return (max(0, box.x-min(x for x,y in path)) +
+                max(0, max(x for x,y in path)-box.x-box.w) +
+                max(0, box.y-min(y for x,y in path)) +
+                max(0, max(y for x,y in path)-box.y-box.h))
+    candidates = []
+    ax, ay = _stub(x1, y1, d1, stub)
+    bx, by = _stub(x2, y2, d2, stub)
+    for rank, chosen in enumerate(sides):
+        if side != "auto" and chosen != side:
+            continue
+        axis = 1 if chosen in ("top", "bottom") else 0
+        intervals = sorted((r[axis], r[axis]+r[axis+2]) for r in obstacles
+                           if _role(r) == "hard")
+        merged = []
+        for lo, hi in intervals:
+            if merged and lo <= merged[-1][1]:
+                merged[-1][1] = max(merged[-1][1], hi)
+            else:
+                merged.append([lo, hi])
+        channels = [(a[1]+b[0])/2 for a,b in zip(merged, merged[1:])
+                    if b[0]-a[1] >= 2*clearance]
+        if bounds is not None:
+            low = bounds.y if axis else bounds.x
+            high = low + (bounds.h if axis else bounds.w)
+            channels += [low+clearance, high-clearance]
+        for t in sorted(set(channels)):
+            reference = (ay, by) if axis else (ax, bx)
+            if chosen in ("top", "left") and t > min(reference):
+                continue
+            if chosen in ("bottom", "right") and t < max(reference):
+                continue
+            if axis:
+                core = [(ax,t),(bx,t)]
+            else:
+                core = [(t,ay),(t,by)]
+            path = _dedupe([(x1,y1),(ax,ay)]+core+[(bx,by),(x2,y2)])
+            candidates.append((rank,path))
+        candidates.append((rank, route_loop_avoid(x1,y1,d1,x2,y2,d2,
+                          stub=stub,side=chosen,clearance=clearance,obstacles=obstacles)))
+    internal = [(r,p) for r,p in candidates if bounds is not None
+                and expansion(p,bounds) == 0
+                and _path_hits(p,obstacles,("hard", "background")) == 0]
+    if internal:
+        candidates = internal
+    def cost(item):
+        rank, path = item
+        length = sum(abs(a[0]-b[0])+abs(a[1]-b[1]) for a,b in zip(path,path[1:]))
+        bends = sum((b[0]-a[0])*(c[1]-b[1]) != (b[1]-a[1])*(c[0]-b[0])
+                    for a,b,c in zip(path,path[1:],path[2:]))
+        return (length + 8*bends + 1000*_path_hits(path,obstacles,("hard",))
+                + 10*expansion(path,bounds) + 50*expansion(path,container_bounds), rank)
+    return min(candidates,key=cost)[1]