codefig 0.17.0__py3-none-any.whl

codefig/regions.py

@@ -0,0 +1,727 @@
+"""Regions over arbitrary members (v0.7.0) — overlapping / non-contiguous groupings.
+
+A :class:`Region` is drawn *behind* a :class:`~codefig.edges.Diagram`'s content around
+any set of member nodes, wherever the layout put them: ``Region([prefill_cpu,
+decode_cpu, xfer], label="KVCache pool", style="dashed")``. Unlike a
+:class:`~codefig.primitives.Group` it does not own or move its members, so two regions
+may share members and overlap (Mooncake / S-LoRA "pool spanning two instances").
+
+* ``shape="rect"`` (rounded bounding box) or ``"hull"`` (rounded convex hull — hugs an
+  L-shaped or diagonal member set without swallowing non-members).
+* ``style="filled"`` (translucent tint + thin outline, default), ``"dashed"`` /
+  ``"dotted"`` (outline only), or ``"outline"``.
+* The label is placed at the candidate spot that collides least with boxes, edges and
+  other regions' labels: a top / bottom *strip* (left, centre or right; the outline
+  grows to include it) or *on the border* (``"border-top-left"`` …, a legend-style
+  label sitting on the outline with a knockout). ``label_pos=`` forces a spot.
+* Non-members never sit inside a region (v0.8.0, ``exclude="auto"``): the panel layout
+  first *pushes* an intruding box out of the region along its cheapest axis (relational
+  constraints, see :mod:`codefig.constraints`); if that is impossible (the box is
+  pinned between members by a Row / Grid) the outline is *carved* — an orthogonal,
+  possibly non-contiguous outline that notches around the intruder.
+  ``exclude="push"`` / ``"carve"`` pick one mechanism, ``"none"`` disables both (lint
+  CF-REG-001 then warns).
+* v0.9.0: ``exclude="auto"`` also considers *reordering* the intruder within its flex
+  container (just before / after the members' span) and keeps whichever candidate —
+  reorder or one of the four push sides — scores best on intrusions, edges through
+  boxes, edge crossings, then total edge length + footprint. ``"push"`` never
+  reorders. Reordering mutates the container's child order (see
+  ``Panel._region_moves`` for what was done). Carved outlines keep the full corner
+  radius outside and use a tighter one in the notches.
+* Nested regions (members ⊂ another region's members) get extra padding automatically
+  so their outlines never coincide.
+
+Regions are layout-neutral: the Diagram grows its margin when a region or its label
+sticks out of the content box. They are not obstacles for edge routing.
+"""
+
+from __future__ import annotations
+
+import math
+from typing import Any, Dict, List, Optional, Sequence, Tuple
+
+from .node import Node
+from .styles import themed
+from .textutil import measure_text
+
+Rect = Tuple[float, float, float, float]
+Pt = Tuple[float, float]
+
+_CORNERS = ("top-left", "top-right", "bottom-left", "bottom-right")
+_STRIP = ("top-left", "top-right", "bottom-left", "bottom-right", "top-center", "bottom-center")
+_SPOTS = _STRIP + tuple("border-" + c for c in _STRIP)
+_EXCLUDE = ("auto", "push", "carve", "none")
+
+
+def _hull(pts: Sequence[Pt]) -> List[Pt]:
+    """Convex hull (monotone chain), counter-clockwise in SVG coordinates."""
+    p = sorted(set((round(x, 3), round(y, 3)) for x, y in pts))
+    if len(p) <= 2:
+        return list(p)
+
+    def cross(o, a, b):
+        return (a[0] - o[0]) * (b[1] - o[1]) - (a[1] - o[1]) * (b[0] - o[0])
+
+    lo: List[Pt] = []
+    for q in p:
+        while len(lo) >= 2 and cross(lo[-2], lo[-1], q) <= 0:
+            lo.pop()
+        lo.append(q)
+    up: List[Pt] = []
+    for q in reversed(p):
+        while len(up) >= 2 and cross(up[-2], up[-1], q) <= 0:
+            up.pop()
+        up.append(q)
+    return lo[:-1] + up[:-1]
+
+
+def _signed_area(poly: Sequence[Pt]) -> float:
+    return 0.5 * sum(poly[i - 1][0] * poly[i][1] - poly[i][0] * poly[i - 1][1]
+                     for i in range(len(poly)))
+
+
+def _rounded_path(poly: Sequence[Pt], r: float, r_concave: Optional[float] = None) -> str:
+    """Closed path through ``poly`` with corners rounded by up to ``r``.
+
+    ``r_concave`` (v0.9.0) caps the radius of reflex (inward) corners — the notches
+    of a carved outline — so outer corners keep the full radius while a notch hugs
+    the excluded box without cutting into its clearance."""
+    n = len(poly)
+    if n < 3:
+        return ""
+    orient = 1.0 if _signed_area(poly) >= 0 else -1.0
+    out = []
+    for i in range(n):
+        p0, p1, p2 = poly[i - 1], poly[i], poly[(i + 1) % n]
+        v1 = (p0[0] - p1[0], p0[1] - p1[1])
+        v2 = (p2[0] - p1[0], p2[1] - p1[1])
+        l1, l2 = math.hypot(*v1), math.hypot(*v2)
+        rc = r
+        if r_concave is not None:
+            turn = (p1[0] - p0[0]) * (p2[1] - p1[1]) - (p1[1] - p0[1]) * (p2[0] - p1[0])
+            if turn * orient < 0:
+                rc = min(r, r_concave)
+        rr = min(rc, l1 / 2, l2 / 2)
+        a = (p1[0] + v1[0] / max(l1, 1e-9) * rr, p1[1] + v1[1] / max(l1, 1e-9) * rr)
+        b = (p1[0] + v2[0] / max(l2, 1e-9) * rr, p1[1] + v2[1] / max(l2, 1e-9) * rr)
+        out.append(("L" if out else "M") + f" {a[0]:.2f},{a[1]:.2f}")
+        out.append(f"Q {p1[0]:.2f},{p1[1]:.2f} {b[0]:.2f},{b[1]:.2f}")
+    return " ".join(out) + " Z"
+
+
+def _overlap(a: Rect, b: Rect) -> float:
+    w = min(a[0] + a[2], b[0] + b[2]) - max(a[0], b[0])
+    h = min(a[1] + a[3], b[1] + b[3]) - max(a[1], b[1])
+    return w * h if w > 0 and h > 0 else 0.0
+
+
+def _seg_hits(r: Rect, p: Pt, q: Pt) -> bool:
+    x, y, w, h = r
+    if max(p[0], q[0]) < x or min(p[0], q[0]) > x + w or max(p[1], q[1]) < y or min(p[1], q[1]) > y + h:
+        return False
+    if abs(p[0] - q[0]) < 1e-6 or abs(p[1] - q[1]) < 1e-6:
+        return True  # axis-aligned segment whose bbox meets the rect
+    for t in (i / 12 for i in range(13)):
+        sx, sy = p[0] + (q[0] - p[0]) * t, p[1] + (q[1] - p[1]) * t
+        if x <= sx <= x + w and y <= sy <= y + h:
+            return True
+    return False
+
+
+def _pip(x: float, y: float, poly: Sequence[Pt]) -> bool:
+    """Point in polygon (even-odd ray cast)."""
+    inside = False
+    n = len(poly)
+    for i in range(n):
+        ax, ay = poly[i]
+        bx, by = poly[(i + 1) % n]
+        if (ay > y) != (by > y):
+            xc = ax + (y - ay) * (bx - ax) / (by - ay)
+            if xc > x:
+                inside = not inside
+    return inside
+
+
+def _poly_rect_area(poly: Sequence[Pt], r: Rect) -> float:
+    """Area of a convex polygon ∩ rect (Sutherland–Hodgman clip + shoelace)."""
+    if len(poly) < 3:
+        return 0.0
+    x0, y0, x1, y1 = r[0], r[1], r[0] + r[2], r[1] + r[3]
+    pts = list(poly)
+    for inside, inter in (
+        (lambda p: p[0] >= x0, lambda p, q: (x0, p[1] + (q[1] - p[1]) * (x0 - p[0]) / (q[0] - p[0]))),
+        (lambda p: p[0] <= x1, lambda p, q: (x1, p[1] + (q[1] - p[1]) * (x1 - p[0]) / (q[0] - p[0]))),
+        (lambda p: p[1] >= y0, lambda p, q: (p[0] + (q[0] - p[0]) * (y0 - p[1]) / (q[1] - p[1]), y0)),
+        (lambda p: p[1] <= y1, lambda p, q: (p[0] + (q[0] - p[0]) * (y1 - p[1]) / (q[1] - p[1]), y1)),
+    ):
+        out: List[Pt] = []
+        for i in range(len(pts)):
+            p, q = pts[i - 1], pts[i]
+            if inside(q):
+                if not inside(p):
+                    out.append(inter(p, q))
+                out.append(q)
+            elif inside(p):
+                out.append(inter(p, q))
+        pts = out
+        if not pts:
+            return 0.0
+    a = 0.0
+    for i in range(len(pts)):
+        a += pts[i - 1][0] * pts[i][1] - pts[i][0] * pts[i - 1][1]
+    return abs(a) / 2.0
+
+
+def _in_any(x: float, y: float, rects: Sequence[Rect]) -> bool:
+    return any(r[0] <= x <= r[0] + r[2] and r[1] <= y <= r[1] + r[3] for r in rects)
+
+
+def _open_cut(c: Rect, bb: Tuple[float, float, float, float], keep: Sequence[Rect]) -> Rect:
+    """Extend an interior cut to the nearest outline side that no kept rect blocks, so an
+    intruder becomes a notch (or splits the region) instead of a framed hole."""
+    x, y, w, h = c
+    bx0, by0, bx1, by1 = bb
+    e = 1.0
+    opts = [(x - bx0, (bx0 - e, y, x + w - bx0 + e, h)),
+            (bx1 - x - w, (x, y, bx1 - x + e, h)),
+            (y - by0, (x, by0 - e, w, y + h - by0 + e)),
+            (by1 - y - h, (x, y, w, by1 - y + e))]
+    if min(d for d, _ in opts) <= 0:
+        return c  # already reaches the outline
+    for _d, r in sorted(opts, key=lambda t: t[0]):
+        if not any(_overlap(r, k) > 0.0 for k in keep):
+            return r
+    return c
+
+
+def _orth_carve(base: Sequence[Rect], keep: Sequence[Rect], cut: Sequence[Rect],
+                bridge: bool = False) -> List[List[Pt]]:
+    """Orthogonal outline(s) of (∪base − ∪cut) ∪ ∪keep, as closed loops (holes included).
+
+    ``bridge=True`` closes the area orthogonally (a cell between two inside cells of the
+    same row / column is inside unless cut) — the rectilinear analogue of a convex hull.
+    """
+    xs = sorted({v for r in list(base) + list(keep) + list(cut) for v in (r[0], r[0] + r[2])})
+    ys = sorted({v for r in list(base) + list(keep) + list(cut) for v in (r[1], r[1] + r[3])})
+    nx, ny = len(xs) - 1, len(ys) - 1
+    if nx < 1 or ny < 1:
+        return []
+    cx = [(xs[i] + xs[i + 1]) / 2 for i in range(nx)]
+    cy = [(ys[j] + ys[j + 1]) / 2 for j in range(ny)]
+    kept = [[_in_any(cx[i], cy[j], keep) for j in range(ny)] for i in range(nx)]
+    cutc = [[_in_any(cx[i], cy[j], cut) and not kept[i][j] for j in range(ny)] for i in range(nx)]
+    ins = [[(kept[i][j] or (_in_any(cx[i], cy[j], base) and not cutc[i][j]))
+            for j in range(ny)] for i in range(nx)]
+    if bridge:
+        for _ in range(4):
+            changed = False
+            for j in range(ny):
+                idx = [i for i in range(nx) if ins[i][j]]
+                if idx:
+                    for i in range(idx[0], idx[-1] + 1):
+                        if not ins[i][j] and not cutc[i][j]:
+                            ins[i][j] = changed = True
+            for i in range(nx):
+                idx = [j for j in range(ny) if ins[i][j]]
+                if idx:
+                    for j in range(idx[0], idx[-1] + 1):
+                        if not ins[i][j] and not cutc[i][j]:
+                            ins[i][j] = changed = True
+            if not changed:
+                break
+
+    def inside(i: int, j: int) -> bool:
+        return 0 <= i < nx and 0 <= j < ny and ins[i][j]
+
+    out_edges: Dict[Tuple[int, int], List[Tuple[int, int]]] = {}
+
+    def add(a, b):
+        out_edges.setdefault(a, []).append(b)
+
+    for i in range(nx):
+        for j in range(ny):
+            if not ins[i][j]:
+                continue
+            if not inside(i, j - 1):
+                add((i, j), (i + 1, j))
+            if not inside(i + 1, j):
+                add((i + 1, j), (i + 1, j + 1))
+            if not inside(i, j + 1):
+                add((i + 1, j + 1), (i, j + 1))
+            if not inside(i - 1, j):
+                add((i, j + 1), (i, j))
+    loops: List[List[Pt]] = []
+    while out_edges:
+        start = next(iter(out_edges))
+        loop = [start]
+        cur = start
+        prev_dir = None
+        while True:
+            nxt_list = out_edges.get(cur)
+            if not nxt_list:
+                break
+            if len(nxt_list) > 1 and prev_dir is not None:
+                # saddle: take the right turn (keeps diagonal cells apart)
+                def turn(b):
+                    d = (b[0] - cur[0], b[1] - cur[1])
+                    return -(prev_dir[0] * d[1] - prev_dir[1] * d[0])
+                nxt_list.sort(key=turn)
+            nxt = nxt_list.pop(0)
+            if not nxt_list:
+                del out_edges[cur]
+            prev_dir = (nxt[0] - cur[0], nxt[1] - cur[1])
+            cur = nxt
+            if cur == start:
+                break
+            loop.append(cur)
+        pts = [(xs[i], ys[j]) for i, j in loop]
+        # drop collinear vertices
+        simp: List[Pt] = []
+        n = len(pts)
+        for k in range(n):
+            a, b, c = pts[k - 1], pts[k], pts[(k + 1) % n]
+            if abs((b[0] - a[0]) * (c[1] - b[1]) - (b[1] - a[1]) * (c[0] - b[0])) > 1e-9:
+                simp.append(b)
+        if len(simp) >= 4:
+            loops.append(simp)
+    # outer loops (largest |area|) first
+    def area(lp):
+        return abs(sum(lp[k - 1][0] * lp[k][1] - lp[k][0] * lp[k - 1][1] for k in range(len(lp)))) / 2
+    loops.sort(key=lambda lp: -area(lp))
+    return loops
+
+
+class Region:
+    """Translucent / dashed area around arbitrary member nodes (see module docs).
+
+    members: nodes (or anything with ``.geom``) inside one Diagram.
+    label: text in a strip or on the border (``label_pos`` auto | top-left | top-center |
+    top-right | bottom-… | border-top-left | …); ``label_color`` defaults to the region colour.
+    exclude: auto | push | carve | none — how non-members are kept out (module docs).
+    color: outline / tint colour (default: the theme's accents, cycled per region).
+    style: ``"filled"`` (tint + thin outline, default) | ``"dashed"`` | ``"dotted"`` |
+    ``"outline"`` (the last three: outline only, no tint).
+    fill_opacity: tint strength for ``style="filled"`` (default 0.10).
+    pad: clearance around members (theme length); ``radius``: corner rounding.
+    """
+
+    reg_pad = themed(7.0)
+    reg_nest = themed(6.0)
+
+    def __init__(self, members: Sequence[Any], label: Optional[str] = None, *,
+                 shape: str = "rect", style: str = "filled", color: Optional[str] = None,
+                 fill_opacity: float = 0.10, pad: Optional[float] = None,
+                 radius: Optional[float] = None, label_pos: str = "auto",
+                 label_color: Optional[str] = None, stroke_width: Optional[float] = None,
+                 exclude: str = "auto", theme: Any = None) -> None:
+        if not members:
+            raise ValueError("Region needs at least one member")
+        from ._validate import check_enum
+        shape = check_enum("Region(shape)", shape, ("rect", "hull"))
+        style = check_enum("Region(style)", style, ("filled", "dashed", "dotted", "outline"))
+        label_pos = check_enum("Region(label_pos)", label_pos, ("auto",) + _SPOTS,
+                               {"top": "top-center", "bottom": "bottom-center",
+                                "left": "top-left", "right": "top-right"})
+        exclude = check_enum("Region(exclude)", exclude, _EXCLUDE)
+        self.exclude = exclude
+        self.members = list(members)
+        self.label = label
+        self.shape = shape
+        self.style = style
+        self.color = color
+        self.fill_opacity = float(fill_opacity)
+        self.reg_pad = pad
+        self.radius = radius
+        self.label_pos = label_pos
+        self.label_color = label_color
+        self.stroke_width = stroke_width
+        self._theme = theme
+        self._extra_pad = 0.0
+        self._geo: Optional[Dict[str, Any]] = None
+
+    # themed() looks for .theme
+    @property
+    def theme(self):
+        from .styles import current_theme
+
+        if self._theme is not None:
+            return self._theme
+        for m in self.members:
+            th = getattr(m, "theme", None)
+            if th is not None:
+                return th
+        return current_theme()
+
+    def _rects(self) -> List[Rect]:
+        out = []
+        for m in self.members:
+            g = getattr(m, "geom", None)
+            if g is not None and g.w > 0 and g.h > 0:
+                out.append((g.x, g.y, g.w, g.h))
+        return out
+
+    def _label_size(self) -> Tuple[float, float]:
+        if not self.label:
+            return 0.0, 0.0
+        th = self.theme
+        return measure_text(self.label, th.small_size, weight="bold")
+
+    def _member_ids(self) -> set:
+        ids = set()
+
+        def add(n):
+            ids.add(id(n))
+            for k in getattr(n, "children", lambda: ())():
+                add(k)
+
+        for m in self.members:
+            add(m)
+        return ids
+
+    # ---- geometry ---------------------------------------------------------------
+    def _pad(self) -> float:
+        return float(self.reg_pad) + self._extra_pad
+
+    def base_rect(self) -> Rect:
+        """Padded bounding box of the members (no label) in layout coordinates."""
+        rects = self._rects()
+        pad = self._pad()
+        x0 = min(r[0] for r in rects) - pad
+        y0 = min(r[1] for r in rects) - pad
+        x1 = max(r[0] + r[2] for r in rects) + pad
+        y1 = max(r[1] + r[3] for r in rects) + pad
+        return (x0, y0, x1 - x0, y1 - y0)
+
+    def _hull_poly(self, extra: Sequence[Rect] = ()) -> List[Pt]:
+        pad = self._pad()
+        pts: List[Pt] = []
+        for r in self._rects():
+            pts += [(r[0] - pad, r[1] - pad), (r[0] + r[2] + pad, r[1] - pad),
+                    (r[0] + r[2] + pad, r[1] + r[3] + pad), (r[0] - pad, r[1] + r[3] + pad)]
+        for r in extra:
+            pts += [(r[0], r[1]), (r[0] + r[2], r[1]), (r[0] + r[2], r[1] + r[3]),
+                    (r[0], r[1] + r[3])]
+        return _hull(pts)
+
+    def intrudes(self, rect: Rect, *, min_area: float = 0.5) -> bool:
+        """Would ``rect`` sit inside this region's *un-carved* area (padded bbox / hull)?"""
+        if self.shape == "hull":
+            return _poly_rect_area(self._hull_poly(), rect) > min_area
+        return _overlap(self.base_rect(), rect) > min_area
+
+    def solve(self, boxes: Sequence[Tuple[Any, Rect]], segs: Sequence[Tuple[Pt, Pt]],
+              taken: Sequence[Rect]) -> Dict[str, Any]:
+        """Pick the label spot and outline. ``boxes``: (node, rect) of drawn non-ancestor nodes."""
+        th = self.theme
+        rects = self._rects()
+        x0, y0, bw, bh = self.base_rect()
+        x1, y1 = x0 + bw, y0 + bh
+        lw, lh = self._label_size()
+        mine = self._member_ids()
+        others = [r for n, r in boxes if id(n) not in mine]
+        lp = th.L(3.0)
+        best = None
+        cands = _SPOTS if self.label_pos == "auto" else (self.label_pos,)
+        for k, c in enumerate(cands):
+            if not self.label:
+                break
+            border = c.startswith("border-")
+            cc = c[7:] if border else c
+            if cc.endswith("left"):
+                lx = x0 + lp + (th.L(3.0) if border else 0.0)
+            elif cc.endswith("right"):
+                lx = x1 - lp - lw - (th.L(3.0) if border else 0.0)
+            else:
+                lx = (x0 + x1) / 2 - lw / 2
+            top = cc.startswith("top")
+            if border:
+                ly = (y0 if top else y1) - lh / 2
+                ext = (min(x0, lx - lp), y0, max(x1, lx + lw + lp), y1)
+                strip = (lx - lp * 0.5, ly, lw + lp, lh)
+            else:
+                ly = y0 - lh - th.L(1.0) if top else y1 + th.L(1.0)
+                ext = (min(x0, lx - lp), min(y0, ly - lp * 0.6), max(x1, lx + lw + lp),
+                       max(y1, ly + lh + lp * 0.6))
+                # the label pulls the outline outwards: what does that strip newly cover?
+                strip = (ext[0], ly - lp * 0.6, ext[2] - ext[0], lh + lp * 1.2)
+            lab = (lx, ly, lw, lh)
+            score = sum(_overlap(lab, r) for r in others) * 4.0
+            score += sum(_overlap(strip, r) for r in others)
+            score += sum(_overlap(lab, r) for r in taken) * 4.0
+            score += sum(1 for p, q in segs if _seg_hits(lab, p, q)) * lh * lw * 0.5
+            # mild preferences: strip before border, corners before centres, stable order
+            score += (lh * lw * 0.02 if border else 0.0) + k * 1e-3
+            if best is None or score < best[0]:
+                best = (score, c, lab, ext, border)
+        if best is not None:
+            _s, corner, lab, ext, border = best
+            ex0, ey0, ex1, ey1 = ext
+        else:
+            corner, lab, border = None, None, False
+            ex0, ey0, ex1, ey1 = x0, y0, x1, y1
+        lab_box = None
+        if lab is not None and not border:
+            lx, ly, lw_, lh_ = lab
+            lab_box = (lx - lp, ly - lp * 0.6, lw_ + 2 * lp, lh_ + lp * 1.2)
+        # non-members still inside the outline (push failed / exclude="carve")
+        if self.shape == "hull":
+            hull = self._hull_poly([lab_box] if lab_box else [])
+            inside = [r for r in others if _poly_rect_area(hull, r) > 0.5]
+        else:
+            ext_r = (ex0, ey0, ex1 - ex0, ey1 - ey0)
+            inside = [r for r in others if _overlap(ext_r, r) > 0.5]
+        loops: List[List[Pt]]
+        carved = bool(inside) and self.exclude in ("auto", "carve")
+        if carved:
+            gap = th.L(3.0)
+            keep = [(r[0] - 0.5, r[1] - 0.5, r[2] + 1.0, r[3] + 1.0) for r in rects]
+            if lab is not None:
+                keep.append((lab[0] - 0.5, lab[1] - 0.5, lab[2] + 1.0, lab[3] + 1.0))
+            cut = [(r[0] - gap, r[1] - gap, r[2] + 2 * gap, r[3] + 2 * gap) for r in inside]
+            if self.shape == "hull":
+                bb = (min(r[0] for r in rects) - self._pad(), min(r[1] for r in rects) - self._pad(),
+                      max(r[0] + r[2] for r in rects) + self._pad(),
+                      max(r[1] + r[3] for r in rects) + self._pad())
+            else:
+                bb = (ex0, ey0, ex1, ey1)
+            cut = [_open_cut(c, bb, keep) for c in cut]
+            if self.shape == "hull":
+                pad = self._pad()
+                base = [(r[0] - pad, r[1] - pad, r[2] + 2 * pad, r[3] + 2 * pad) for r in rects]
+                if lab_box:
+                    base.append(lab_box)
+                loops = _orth_carve(base, keep, cut, bridge=True)
+            else:
+                loops = _orth_carve([(ex0, ey0, ex1 - ex0, ey1 - ey0)], keep, cut)
+        elif self.shape == "hull":
+            loops = [hull]
+        else:
+            loops = [[(ex0, ey0), (ex1, ey0), (ex1, ey1), (ex0, ey1)]]
+        xs = [p[0] for lp_ in loops for p in lp_]
+        ys = [p[1] for lp_ in loops for p in lp_]
+        self._geo = {"poly": loops[0], "loops": loops, "label": lab, "corner": corner,
+                     "border": border, "carved": carved,
+                     "bbox": (min(xs), min(ys), max(xs) - min(xs), max(ys) - min(ys))}
+        return self._geo
+
+    def covers(self, rect: Rect, frac: float = 0.15) -> bool:
+        """Does the *drawn* outline cover more than ``frac`` of ``rect``? (lint CF-REG-001)"""
+        if self._geo is None:
+            return False
+        x, y, w, h = rect
+        if w <= 0 or h <= 0:
+            return False
+        n = 7
+        hit = 0
+        for i in range(n):
+            for j in range(n):
+                px = x + w * (i + 0.5) / n
+                py = y + h * (j + 0.5) / n
+                inside = False
+                for loop in self._geo["loops"]:
+                    if _pip(px, py, loop):
+                        inside = not inside
+                hit += inside
+        return hit / (n * n) > frac
+
+    @property
+    def label_rect(self) -> Optional[Rect]:
+        """(x, y, w, h) of the placed label after layout (None if unlabeled / not laid out)."""
+        geo = getattr(self, "_geo", None)
+        return geo["label"] if geo else None
+
+    @property
+    def bbox(self) -> Optional[Rect]:
+        """Outline bounding box after the Diagram laid it out (None before)."""
+        return None if self._geo is None else self._geo["bbox"]
+
+    def _color(self, index: int) -> str:
+        if self.color:
+            return self.color
+        acc = list(self.theme.accents) or ["#555555"]
+        return acc[index % len(acc)]
+
+    def draw(self, buf: List[str], ox: float, oy: float, index: int = 0) -> None:
+        from .render_svg import draw_path
+
+        if self._geo is None:
+            return
+        th = self.theme
+        col = self._color(index)
+        r = self.radius if self.radius is not None else th.L(8.0)
+        loops = self._geo["loops"]
+        if self._geo.get("carved"):
+            # v0.9.0: outer corners keep the full radius; reflex notch corners and
+            # hole loops get a tighter one so they hug the excluded box
+            rn = min(r, th.L(4.0))
+            big = max(range(len(loops)), key=lambda i: abs(_signed_area(loops[i]))) if loops else 0
+            d = " ".join(_rounded_path([(x + ox, y + oy) for x, y in lp_],
+                                       r if i == big else rn, rn)
+                         for i, lp_ in enumerate(loops))
+        else:
+            d = " ".join(_rounded_path([(x + ox, y + oy) for x, y in lp_], r) for lp_ in loops)
+        sw = self.stroke_width if self.stroke_width is not None else th.stroke_width
+        dash = None
+        if self.style == "dashed":
+            dash = " ".join(f"{v:g}" for v in th.dash) if getattr(th, "dash", None) else "4 3"
+        elif self.style == "dotted":
+            dash = " ".join(f"{v:g}" for v in th.dot) if getattr(th, "dot", None) else "1 2"
+        if self.style == "filled":
+            draw_path(buf, d, fill=col, stroke="none", stroke_width=0, opacity=self.fill_opacity,
+                      fill_rule="evenodd")
+        draw_path(buf, d, fill="none", stroke=col, stroke_width=sw, dasharray=dash)
+
+    def draw_label(self, buf: List[str], ox: float, oy: float, index: int = 0) -> None:
+        from .render_svg import draw_text
+
+        if self._geo is None or self._geo["label"] is None:
+            return
+        th = self.theme
+        lx, ly, lw, lh = self._geo["label"]
+        fs = th.small_size
+        col = self.label_color or self._color(index)
+        if self._geo.get("border"):  # legend-style: knock the outline out behind the text
+            from .render_svg import draw_rect
+
+            kp = th.L(1.5)
+            draw_rect(buf, lx + ox - kp, ly + oy, lw + 2 * kp, lh, fill="#ffffff",
+                      stroke="none", stroke_width=0)
+        draw_text(buf, self.label, lx + ox, ly + oy + lh / 2 + fs * 0.35, font_size=fs,
+                  weight="bold", fill=col)
+
+
+def diagram_boxes(diagram: Any) -> Tuple[List[Tuple[Any, Rect]], Dict[int, Any]]:
+    """(node, rect) of every drawn box inside ``diagram`` + a child-id → parent map."""
+    from .policy import role_of
+
+    parent: Dict[int, Any] = {}
+    boxes: List[Tuple[Any, Rect]] = []
+
+    def rec(n: Any) -> None:
+        kids = list(n.children())
+        for k in kids:
+            parent[id(k)] = n
+        if n is not diagram.content:
+            role = role_of(n)
+            if (role in ("hard", "soft") and not kids) or role == "hard":
+                g = n.geom
+                if g.w > 0 and g.h > 0:
+                    boxes.append((n, (g.x, g.y, g.w, g.h)))
+        for k in kids:
+            rec(k)
+
+    rec(diagram.content)
+    return boxes, parent
+
+
+def _ancestors(region: Region, parent: Dict[int, Any]) -> set:
+    out = set()
+    for m in region.members:
+        p = parent.get(id(m))
+        while p is not None and id(p) not in out:
+            out.add(id(p))
+            p = parent.get(id(p))
+    return out
+
+
+def region_others(diagram: Any, region: Region,
+                  pre: Optional[Tuple[List[Tuple[Any, Rect]], Dict[int, Any]]] = None
+                  ) -> List[Tuple[Any, Rect]]:
+    """Drawn boxes that are neither members (nor inside one) nor ancestors of members."""
+    boxes, parent = pre or diagram_boxes(diagram)
+    skip = region._member_ids() | _ancestors(region, parent)
+    return [(n, r) for n, r in boxes if id(n) not in skip]
+
+
+def region_intruders(diagram: Any, region: Region) -> List[Any]:
+    """Non-member boxes inside the region's un-carved area (targets of the layout push)."""
+    if not region._rects():
+        return []
+    out = []
+    for n, r in region_others(diagram, region):
+        if region.intrudes(r):
+            out.append(n)
+    # keep only outermost intruders (a Group intruding implies its children do)
+    ids = {id(n) for n in out}
+    _b, parent = diagram_boxes(diagram)
+
+    def has_intruding_ancestor(n):
+        p = parent.get(id(n))
+        while p is not None:
+            if id(p) in ids:
+                return True
+            p = parent.get(id(p))
+        return False
+
+    return [n for n in out if not has_intruding_ancestor(n)]
+
+
+def push_constraints(region: Region, intruder: Any, side: str, margin: float) -> list:
+    """no_overlap constraints that move ``intruder`` to ``side`` of all members."""
+    from .constraints import no_overlap
+
+    axis = "x" if side in ("left", "right") else "y"
+    out = []
+    for m in region.members:
+        if side in ("right", "bottom"):
+            c = no_overlap(m, intruder, axis, margin=margin, strength="strong")
+        else:
+            c = no_overlap(intruder, m, axis, margin=margin, strength="strong")
+            c.subjects, c.refs = [intruder], [m]
+        out.append(c)
+    return out
+
+
+def push_sides(region: Region, intruder: Any) -> List[Tuple[float, str]]:
+    """Candidate push directions for ``intruder``, cheapest displacement first."""
+    x0, y0, w, h = region.base_rect()
+    g = intruder.geom
+    moves = [(x0 + w - g.x, "right"), (g.x + g.w - x0, "left"),
+             (y0 + h - g.y, "bottom"), (g.y + g.h - y0, "top")]
+    return sorted(moves)
+
+
+def nest_pads(regions: Sequence[Region]) -> None:
+    """Regions that strictly contain another region's members get extra padding."""
+    sets = [r._member_ids() for r in regions]
+    for i, r in enumerate(regions):
+        inner = sum(1 for j, s in enumerate(sets) if j != i and s < sets[i])
+        r._extra_pad = inner * float(r.reg_nest)
+
+
+def layout_regions(diagram: Any, regions: Sequence[Region]) -> None:
+    """Solve every region of ``diagram`` (nest padding, label corners)."""
+    if not regions:
+        return
+    nest_pads(regions)
+    pre = diagram_boxes(diagram)
+    segs: List[Tuple[Pt, Pt]] = []
+    try:
+        for _e, pts in diagram._routed()[0]:
+            segs += [(pts[k], pts[k + 1]) for k in range(len(pts) - 1)]
+    except Exception:  # pragma: no cover - routing failures are reported elsewhere
+        pass
+    taken: List[Rect] = []
+    # outer (bigger) regions first so inner labels avoid them
+    order = sorted(regions, key=lambda rr: -len(rr._member_ids()))
+    for r in order:
+        geo = r.solve(region_others(diagram, r, pre), segs, taken)
+        if geo["label"] is not None:
+            taken.append(geo["label"])
+    if len(order) > 1 and any(r.label for r in order):
+        # v0.12: second pass — each label also avoids the *outlines* of the other
+        # regions (an overlapping region's border used to run through a label)
+        def outline(rr: Region) -> List[Tuple[Pt, Pt]]:
+            g = rr._geo or {}
+            out = []
+            for lp_ in g.get("loops", []):
+                out += [(lp_[k], lp_[(k + 1) % len(lp_)]) for k in range(len(lp_))]
+            return out
+
+        for r in order:
+            if not r.label:
+                continue
+            others_segs = [sg for o in order if o is not r for sg in outline(o)]
+            others_lab = [o._geo["label"] for o in order
+                          if o is not r and o._geo and o._geo["label"] is not None]
+            r.solve(region_others(diagram, r, pre), segs + others_segs, others_lab)