codefig 0.17.0__py3-none-any.whl

codefig/node.py

@@ -0,0 +1,864 @@
+"""Scene-graph node base and layout boxes."""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Sequence, Tuple, Union
+
+from .styles import Theme, current_theme, normalize_justify, normalize_pad, theme_default
+
+
+@dataclass
+class BoxGeom:
+    x: float = 0.0
+    y: float = 0.0
+    w: float = 0.0
+    h: float = 0.0
+
+    @property
+    def cx(self) -> float:
+        return self.x + self.w / 2
+
+    @property
+    def cy(self) -> float:
+        return self.y + self.h / 2
+
+    @property
+    def right(self) -> float:
+        return self.x + self.w
+
+    @property
+    def bottom(self) -> float:
+        return self.y + self.h
+
+
+SizeSpec = Union[float, int, str, None]  # number | "content" | "fill" | None
+
+
+def _parse_size_spec(spec: SizeSpec, content: float) -> Tuple[float, bool]:
+    """
+    Resolve a size spec against content measure.
+
+    Returns (resolved_size, wants_fill).
+    "content"/None → content; number → that size; "fill" → content + fill flag.
+    """
+    if spec is None or spec == "content":
+        return float(content), False
+    if isinstance(spec, str):
+        s = spec.strip().lower()
+        if s == "content":
+            return float(content), False
+        if s == "fill":
+            return float(content), True
+        try:
+            return float(s), False
+        except ValueError:
+            return float(content), False
+    return float(spec), False
+
+
+def _clamp(v: float, lo: float, hi: Optional[float]) -> float:
+    v = max(float(lo), float(v))
+    if hi is not None:
+        v = min(float(hi), v)
+    return v
+
+
+from .constraints import Anchor, Anchorable, box_anchor
+
+
+class Node(Anchorable, ABC):
+    """Base drawable / layoutable node. Public API never takes absolute coords."""
+
+    def __init__(
+        self,
+        *,
+        min_w: float = 0.0,
+        min_h: float = 0.0,
+        max_w: Optional[float] = None,
+        max_h: Optional[float] = None,
+        w: SizeSpec = None,
+        h: SizeSpec = None,
+        aspect: Optional[float] = None,
+        grow: float = 0.0,
+        shrink: float = 1.0,
+        align_self: Optional[str] = None,
+        id: Optional[str] = None,
+        theme: Optional[Theme] = None,
+        obstacle: Any = None,
+        knockout: Optional[bool] = None,
+        border: Any = None,
+        legend: Optional[Any] = None,
+        category: Optional[str] = None,
+        lint_ignore: Optional[Sequence[str]] = None,
+        auto_wrap: bool = True,
+        **kwargs: Any,
+    ) -> None:
+        if kwargs:
+            import inspect
+            from difflib import get_close_matches
+            valid = sorted({k for cls in type(self).__mro__ for k in inspect.signature(cls.__init__).parameters if k not in {"self", "kwargs"}})
+            key = next(iter(kwargs))
+            semantic = {"style": "border", "padding_x": "padding", "padding_y": "padding"}
+            close = [semantic[key]] if key in semantic and semantic[key] in valid else get_close_matches(key, valid, n=1)
+            hint = f"; did you mean {close[0]!r}?" if close else ""
+            raise TypeError(f"{type(self).__name__}: unexpected keyword {key!r}{hint}; valid parameters: {valid}")
+        # obstacle: layering role — "hard" | "soft" | "background" | "none" (True →
+        # hard, False → none, None → class default; see codefig.policy). With
+        # "none" edges may route across this node's own area (its children are
+        # still obstacles) — for background regions / bands.
+        from .policy import normalize_role
+        from .styles import validate_border
+
+        self.obstacle = normalize_role(obstacle)
+        # knockout: soft text crossed by an edge clips the edge around itself
+        self.knockout = knockout
+        # border: 'solid' | 'dashed' | 'dotted' | 'dashdot' | 'none' | "4 2" | (4, 2)
+        self.border = validate_border(border)
+        # legend: label collected by an auto Legend (fill / hatch / border of this node)
+        self.legend = legend
+        self.min_w = float(min_w)
+        self.min_h = float(min_h)
+        self.max_w = float(max_w) if max_w is not None else None
+        self.max_h = float(max_h) if max_h is not None else None
+        self.size_w = w  # content|fill|number
+        self.size_h = h
+        self.aspect = float(aspect) if aspect is not None else None
+        self.grow = grow
+        self.shrink = shrink
+        self.align_self = align_self  # start|center|end|stretch|baseline|optical|None
+        self.id = id
+        self._theme: Optional[Theme] = theme
+        # category: semantic class → Figure assigns palette fill (+ hatch past the
+        # palette) and an auto legend label (see Figure / lint CF-COL-004)
+        self.category = category
+        # lint_ignore: rule ids (or prefixes like "CF-TXT") this node is exempt from
+        self.lint_ignore = ((lint_ignore,) if isinstance(lint_ignore, str)
+                            else tuple(lint_ignore or ()))
+        # auto_wrap (v0.14.0): False keeps this label on one line in the figure's
+        # wrap-before-shrink pass (codefig.autowrap)
+        self.auto_wrap = bool(auto_wrap)
+        self.geom = BoxGeom()
+        self.parent: Optional[Node] = None
+        self._measured: Optional[Tuple[float, float]] = None
+        self._measured_theme: Optional[Theme] = None
+        # fill flags set during measure — parent grow treats these as flex
+        self._fill_w = False
+        self._fill_h = False
+
+    def __setattr__(self, name, value):
+        if name in {"fill", "stroke", "color", "text_color", "op_color"}:
+            from .styles import resolve_color
+            value = resolve_color(value, self.theme, where=f"{type(self).__name__}({name}=...)")
+        object.__setattr__(self, name, value)
+
+    @property
+    def theme(self) -> Theme:
+        """Explicit ``theme=`` if given, else the active theme (see ``use_theme``)."""
+        t = self.__dict__.get("_theme")
+        return t if t is not None else current_theme()
+
+    @theme.setter
+    def theme(self, value: Optional[Theme]) -> None:
+        self.__dict__["_theme"] = value
+
+    def measure(self) -> Tuple[float, float]:
+        if self._measured is not None and self.__dict__.get("_measured_theme") is not self.theme:
+            self._measured = None
+        if self._measured is None:
+            self._measured_theme = self.theme
+            cw, ch = self._measure()
+            w, fill_w = _parse_size_spec(self.size_w, cw)
+            h, fill_h = _parse_size_spec(self.size_h, ch)
+            self._fill_w = fill_w
+            self._fill_h = fill_h
+            if fill_w and self.grow <= 0:
+                self.grow = max(self.grow, 1.0)
+            if fill_h and self.grow <= 0:
+                self.grow = max(self.grow, 1.0)
+            # aspect lock: width/height = aspect (w/h)
+            if self.aspect is not None and self.aspect > 0:
+                # Prefer locking the unspecified / content axis
+                if self.size_w is not None and self.size_w != "content" and self.size_w != "fill" and (
+                    self.size_h is None or self.size_h == "content"
+                ):
+                    h = w / self.aspect
+                elif self.size_h is not None and self.size_h != "content" and self.size_h != "fill" and (
+                    self.size_w is None or self.size_w == "content"
+                ):
+                    w = h * self.aspect
+                else:
+                    # both content or both set: fit the larger content into aspect
+                    if w / self.aspect >= h:
+                        h = w / self.aspect
+                    else:
+                        w = h * self.aspect
+            w = _clamp(w, self.min_w, self.max_w)
+            h = _clamp(h, self.min_h, self.max_h)
+            # same_width / same_height constraints (resolved before flex)
+            w = max(w, getattr(self, "_cmin_w", 0.0))
+            h = max(h, getattr(self, "_cmin_h", 0.0))
+            self._measured = (w, h)
+        return self._measured
+
+    def baseline_offset(self) -> float:
+        """
+        Distance from the top of this node's measured box to its primary text baseline.
+
+        Used by Row/Col `align="baseline"`. Default ≈ optical mid of the box.
+        Text/Box override with real text metrics.
+        """
+        _w, h = self.measure()
+        return h * 0.65
+
+    def optical_nudge(self) -> float:
+        """
+        Extra cross-axis shift for `align="optical"` (fraction of height).
+
+        Rounded / pill boxes look heavier; nudge them up slightly so visual mass
+        lines up with sharp rectangles. Default 0; Box overrides when rounded.
+        """
+        return 0.0
+
+    def invalidate(self) -> None:
+        self._measured = None
+
+    @abstractmethod
+    def _measure(self) -> Tuple[float, float]:
+        ...
+
+    def layout(self, x: float, y: float, w: float, h: float) -> None:
+        self.geom = BoxGeom(x, y, w, h)
+        self._layout_children()
+
+    def _layout_children(self) -> None:
+        pass
+
+    @abstractmethod
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        ...
+
+    def children(self) -> Sequence[Node]:
+        return ()
+
+    def _dash(self, stroke_width: float = 1.0) -> Optional[str]:
+        """SVG dasharray for this node's ``border=`` (None = solid)."""
+        from .styles import border_dasharray
+
+        return border_dasharray(self.border, stroke_width)
+
+    def _border_stroke(self, stroke: Optional[str]) -> Optional[str]:
+        return "none" if self.border == "none" else stroke
+
+    def _anchor(self, axis: str, which: str) -> Anchor:
+        """Box anchor for constraints (``node.left`` / ``.right`` / ``.cy`` …)."""
+        return box_anchor(self, axis, which)
+
+    def port(self, side: str = "right", *, at: float = 0.5, align: Any = None,
+             snap: bool = False, offset: float = 0.0, slide: float = 0.0) -> "Port":
+        """Side anchor (left|right|top|bottom|center). `at` is fraction along the side.
+
+        ``align=`` another anchor / port / node puts the port on this side *in line
+        with* it (same x for top/bottom ports, same y for left/right) — e.g. the
+        landing point of a vertical drop under a source; ``offset`` (pt) shifts it along
+        the side — also on a plain side port since v0.13.0 (``port("top", offset=-6)``;
+        an offset port never slides). For N side-by-side arrows between two nodes
+        prefer ``Edge(a, b, parallel=N)``. ``snap=True`` snaps to the nearest cell /
+        bar centre of a Matrix / BarChart so connectors land on a cell instead of a
+        hand-picked index.
+
+        ``slide`` (v0.11.0) lets an explicit ``at=`` move by up to that fraction of the
+        side when that straightens the edge (``port("right", at=0.3, slide=0.1)`` may
+        land anywhere in 0.2–0.4). Plain centre ports already slide by default.
+        """
+        if not 0.0 <= float(slide) <= 1.0:
+            raise ValueError(f"port(): slide={slide!r} must be in [0, 1]")
+        from .edges import Port
+
+        if align is not None:
+            return Port(self, kind="aligned", side=side, at=at, align_ref=align, snap=snap,
+                        offset=float(offset))
+        return Port(self, kind="side", side=side, at=at, slide=float(slide), offset=float(offset))
+
+
+def _align_cross(
+    align: str,
+    container_cross: float,
+    child_cross: float,
+    start: float,
+    *,
+    child: Optional["Node"] = None,
+    container_baseline: Optional[float] = None,
+) -> float:
+    """
+    Cross-axis placement.
+
+    align:
+      start|center|end|stretch — box edges
+      baseline — match text baselines (Row); needs child + container_baseline
+      optical — center, then apply child.optical_nudge()
+    """
+    if align == "baseline" and child is not None and container_baseline is not None:
+        return start + container_baseline - child.baseline_offset()
+    if align == "optical":
+        y = start + (container_cross - child_cross) / 2
+        if child is not None:
+            y -= child.optical_nudge()
+        return y
+    if align == "center":
+        return start + (container_cross - child_cross) / 2
+    if align == "end":
+        return start + (container_cross - child_cross)
+    # start / stretch
+    return start
+
+
+class Container(Node):
+    """Flex-like container: direction row or column.
+
+    font_size sets the title size, snapped to the theme roles (6/7/8 pt for paper).
+    text_color sets the title colour; children retain their own typography."""
+
+    gap = theme_default("gap")
+    title_gap = theme_default("title_gap")
+
+    def _title_font(self):
+        return self.theme.snap(self.title_font_size) if self.title_font_size is not None else self.theme.font_size
+
+    def __init__(
+        self,
+        kids: Optional[Sequence[Node]] = None,
+        *,
+        direction: str = "column",  # row | column
+        gap: Optional[float] = None,
+        pad: Union[float, int, Sequence[float]] = 0.0,
+        padding: Optional[Union[float, int, Sequence[float]]] = None,
+        align: str = "center",  # cross-axis: start|center|end|stretch|baseline|optical
+        justify: str = "start",  # start|center|end|space_between|space_around|space_evenly
+        equal: bool = False,  # children share main-axis size (= max content)
+        wrap: bool = False,
+        fill: Optional[str] = None,
+        stroke: Optional[str] = None,
+        stroke_width: Optional[float] = None,
+        rounded: bool = False,
+        radius: Optional[float] = None,
+        title: Optional[str] = None,
+        title_pos: str = "top",  # top | bottom | inside-top (v0.13: "-left"/"-right" suffix)
+        title_gap: Optional[float] = None,
+        pattern: Optional[Any] = None,
+        title_align: str = "center",  # v0.12: left|center|right (start/end aliases)
+        font_size: Optional[float] = None,
+        text_color: Optional[str] = None,
+        title_wrap: bool = True,  # v0.12: wrap a title wider than the content
+        **kwargs: Any,
+    ) -> None:
+        super().__init__(**kwargs)
+        self.title_font_size = font_size
+        self.title_color = text_color
+        # v0.13.0: title_pos="top-left" / "bottom-right" … = title_pos + title_align
+        if isinstance(title_pos, str) and "-" in title_pos and title_pos != "inside-top":
+            tp, _, al = title_pos.rpartition("-")
+            if tp in ("top", "bottom", "inside-top") and al in ("left", "center", "right", "start", "end"):
+                title_pos = tp
+                title_align = al
+        from ._validate import check_enum
+        title_pos = check_enum("Container(title_pos)", title_pos, ("top", "bottom", "inside-top"))
+        ta = {"start": "left", "end": "right", "middle": "center"}.get(title_align, title_align)
+        from ._validate import check_enum
+        ta = check_enum("node(ta)", ta, ("left", "center", "right"))
+        self.title_align = ta
+        self.title_wrap = bool(title_wrap)
+        self.direction = direction
+        # gap defaults to theme.gap when omitted (resolved lazily)
+        self.gap = None if gap is None else float(gap)
+        raw_pad = padding if padding is not None else pad
+        self.padding = normalize_pad(raw_pad)  # (t, r, b, l)
+        self.pad = sum(self.padding) / 4.0  # scalar average (BC)
+        self.align = align
+        self.justify = normalize_justify(justify)
+        self.equal = bool(equal)
+        self.wrap = wrap
+        self.fill = fill
+        if stroke is None and self.border not in (None, "none", "solid"):
+            stroke = "#555555"  # border= alone gives a visible (dashed/dotted) frame
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.rounded = rounded
+        self.radius = radius
+        self.title = title
+        self.title_pos = title_pos
+        self.title_gap = None if title_gap is None else float(title_gap)
+        self.pattern = pattern
+        self._kids: List[Node] = []
+        if kids:
+            for k in kids:
+                self.add(k)
+
+    def add(self, node: Node) -> Node:
+        node.parent = self
+        self._kids.append(node)
+        self.invalidate()
+        return node
+
+    def __iadd__(self, node: Node) -> "Container":
+        self.add(node)
+        return self
+
+    def children(self) -> Sequence[Node]:
+        return self._kids
+
+    def _title_lines(self) -> List[str]:
+        """v0.12.0: the title's drawn lines — explicit ``\n`` breaks, plus greedy word
+        wrapping when ``title_wrap`` and the title is wider than the content (set by
+        ``_measure``), so a long title neither widens the row nor overlaps a child."""
+        if not self.title:
+            return []
+        cached = self.__dict__.get("_tl_cache")
+        if cached is not None and cached[0] == self.title:
+            return list(cached[1])
+        return str(self.title).split("\n")
+
+    def _wrap_title(self, content_w: float) -> List[str]:
+        from .textutil import measure_text
+
+        fs = self._title_font()
+        lines = str(self.title).split("\n")
+        widest = max((measure_text(ln, fs, weight="bold")[0] for ln in lines), default=0.0)
+        # wrap only when the title would widen the container noticeably
+        if self.title_wrap and content_w > 0 and widest > content_w * 1.15 + fs:
+            out: List[str] = []
+            content_w = max(content_w, widest / 2.0 + fs)  # at most ~2 lines per break
+            for ln in lines:
+                if measure_text(ln, fs, weight="bold")[0] <= content_w + 0.5 or " " not in ln:
+                    out.append(ln)
+                    continue
+                cur = ""
+                for word in ln.split(" "):
+                    cand = (cur + " " + word) if cur else word
+                    if cur and measure_text(cand, fs, weight="bold")[0] > content_w + 0.5:
+                        out.append(cur)
+                        cur = word
+                    else:
+                        cur = cand
+                if cur:
+                    out.append(cur)
+            lines = out
+        self.__dict__["_tl_cache"] = (self.title, list(lines))
+        return lines
+
+    def _title_line_h(self) -> float:
+        return self._title_font() * 1.2
+
+    def _title_h(self) -> float:
+        """Space reserved for title band (font + title_gap); v0.12.0: one line per
+        title line (multi-line titles no longer overlap the first child)."""
+        if not self.title:
+            return 0.0
+        n = max(1, len(self._title_lines()))
+        return self._title_font() * 1.35 + (n - 1) * self._title_line_h() + self.title_gap
+
+    def _slot_lines(self):
+        """Pack an automatically constrained row without changing child order."""
+        limit = self.__dict__.get("_slot_width")
+        if self.direction != "row" or limit is None:
+            return None
+        lines, line, used = [], [], 0.0
+        for kid in self._kids:
+            w, _ = kid.measure()
+            if line and used + self.gap + w > limit:
+                lines.append(line)
+                line, used = [], 0.0
+            used += (self.gap if line else 0.0) + w
+            line.append(kid)
+        if line:
+            lines.append(line)
+        return lines if len(lines) > 1 else None
+
+    def _measure(self) -> Tuple[float, float]:
+        pt, pr, pb, pl = self.padding
+        if self.title:
+            if self._kids:
+                kw = [k.measure()[0] for k in self._kids]
+                if self.direction == "row":
+                    cw = sum(kw) + self._gaps_total(len(self._kids))
+                else:
+                    cw = max(kw)
+            else:
+                cw = 0.0
+            self._wrap_title(cw)
+        th = self._title_h() if self.title_pos != "inside-top" else 0.0
+        if not self._kids:
+            return pl + pr, pt + pb + th
+
+        sizes = [list(k.measure()) for k in self._kids]
+        if self.equal and sizes:
+            if self.direction == "row":
+                mw = max(s[0] for s in sizes)
+                for s in sizes:
+                    s[0] = mw
+            else:
+                mh = max(s[1] for s in sizes)
+                for s in sizes:
+                    s[1] = mh
+        gap_total = self._gaps_total(len(self._kids))
+        if self.direction == "row":
+            w = sum(s[0] for s in sizes) + gap_total + pl + pr
+            h = (max(s[1] for s in sizes) if sizes else 0) + pt + pb + th
+        else:
+            w = (max(s[0] for s in sizes) if sizes else 0) + pl + pr
+            h = sum(s[1] for s in sizes) + gap_total + pt + pb + th
+        lines = self._slot_lines()
+        if lines:
+            w = max(sum(k.measure()[0] for k in line) + self.gap * (len(line) - 1)
+                    for line in lines) + pl + pr
+            h = sum(max(k.measure()[1] for k in line) for line in lines) + self.gap * (len(lines) - 1) + pt + pb + th
+        if self.title:
+            from .textutil import measure_text
+
+            tw = max((measure_text(ln, self._title_font(), weight="bold")[0]
+                      for ln in self._title_lines()), default=0.0)
+            w = max(w, tw + pl + pr)
+        return w, h
+
+    def _layout_children(self) -> None:
+        g = self.geom
+        pt, pr, pb, pl = self.padding
+        th = self._title_h()
+        title_top = th if self.title and self.title_pos == "top" else 0.0
+        title_bot = th if self.title and self.title_pos == "bottom" else 0.0
+        # inside-top title still sits in the pad band; kids start below title_gap
+        inside_extra = (
+            self._title_font() + self.title_gap
+            + (max(1, len(self._title_lines())) - 1) * self._title_line_h()
+            if self.title and self.title_pos == "inside-top"
+            else 0.0
+        )
+        inner_x = g.x + pl
+        inner_y = g.y + pt + title_top + inside_extra
+        inner_w = max(0.0, g.w - pl - pr)
+        inner_h = max(0.0, g.h - pt - pb - title_top - title_bot - inside_extra)
+
+        if not self._kids:
+            return
+
+        lines = self._slot_lines()
+        if lines:
+            cy = inner_y
+            for line in lines:
+                height = max(k.measure()[1] for k in line)
+                width = sum(k.measure()[0] for k in line) + self.gap * (len(line) - 1)
+                cx = inner_x + max(0.0, (inner_w - width) / 2)
+                for kid in line:
+                    kw, kh = kid.measure()
+                    kid.layout(cx, cy + (height - kh) / 2, kw, kh)
+                    cx += kw + self.gap
+                cy += height + self.gap
+            return
+        sizes = [list(k.measure()) for k in self._kids]
+        n = len(self._kids)
+        main_axis = "row" if self.direction == "row" else "col"
+        if self.equal and sizes:
+            if main_axis == "row":
+                mw = max(s[0] for s in sizes)
+                for s in sizes:
+                    s[0] = mw
+            else:
+                mh = max(s[1] for s in sizes)
+                for s in sizes:
+                    s[1] = mh
+        main_sizes = [s[0] if main_axis == "row" else s[1] for s in sizes]
+        inner_main = inner_w if main_axis == "row" else inner_h
+
+        # grow/shrink first (ignore justify spacing for space_* modes)
+        free_for_grow = inner_main - sum(main_sizes) - self._gaps_total(n)
+        self._distribute(free_for_grow, main_sizes, self._kids)
+
+        # justify → offset + per-step gap
+        step_gap, offset = self._justify_spacing(inner_main, main_sizes)
+        pair = self._pair_gaps() if self.justify in ("start", "center", "end") else {}
+
+        # Shared baseline for align=baseline (Row: cross is vertical)
+        container_baseline = None
+        if self.align == "baseline" and main_axis == "row":
+            container_baseline = max(
+                (kid.baseline_offset() for kid in self._kids), default=0.0
+            )
+
+        if main_axis == "row":
+            cx = inner_x + offset
+            for i, kid in enumerate(self._kids):
+                mw = main_sizes[i]
+                ch = sizes[i][1]
+                align = kid.align_self or self.align
+                if align == "stretch":
+                    ch = inner_h
+                cy = _align_cross(
+                    align, inner_h, ch, inner_y,
+                    child=kid, container_baseline=container_baseline,
+                )
+                # Clamp into inner band when baseline would overflow
+                if align == "baseline":
+                    cy = min(max(cy, inner_y), inner_y + max(0.0, inner_h - ch))
+                kid.layout(cx, cy, mw, ch)
+                cx += mw + pair.get(i, step_gap)
+        else:
+            cy = inner_y + offset
+            for i, kid in enumerate(self._kids):
+                mh = main_sizes[i]
+                cw = sizes[i][0]
+                align = kid.align_self or self.align
+                if align == "stretch":
+                    cw = inner_w
+                cx = _align_cross(
+                    align, inner_w, cw, inner_x, child=kid,
+                )
+                kid.layout(cx, cy, cw, mh)
+                cy += mh + pair.get(i, step_gap)
+
+    def _justify_spacing(
+        self, inner_main: float, main_sizes: List[float]
+    ) -> Tuple[float, float]:
+        """Return (gap_between_children, start_offset)."""
+        n = len(main_sizes)
+        total = sum(main_sizes)
+        j = self.justify
+        if j in ("space_between",) and n > 1:
+            free = inner_main - total
+            return max(0.0, free / (n - 1)), 0.0
+        if j in ("space_around",) and n > 0:
+            free = inner_main - total
+            gap = max(0.0, free / n)
+            return gap, gap / 2.0
+        if j in ("space_evenly",) and n > 0:
+            free = inner_main - total
+            gap = max(0.0, free / (n + 1))
+            return gap, gap
+        # start | center | end — use declared gap
+        used = total + self._gaps_total(n)
+        offset = 0.0
+        if j == "center":
+            offset = (inner_main - used) / 2
+        elif j == "end":
+            offset = inner_main - used
+        return self.gap, max(0.0, offset)
+
+    def _pair_gaps(self) -> Dict[int, float]:
+        """v0.10.0: per-pair gap overrides ``{i: gap between child i and i + 1}``, set by
+        layout helpers (e.g. ``align_columns`` tightens the gap inside an aligned stack)
+        only when the container's own ``gap=`` was not given."""
+        if self.__dict__.get("_td_gap") is not None and not self.__dict__.get("_pair_gap_force"):
+            return {}
+        return {i: g for i, g in (self.__dict__.get("_pair_gap") or {}).items()
+                if 0 <= i < len(self._kids) - 1}
+
+    def _gaps_total(self, n: int) -> float:
+        pair = self._pair_gaps() if self.justify in ("start", "center", "end") else {}
+        return sum(pair.get(i, self.gap) for i in range(max(0, n - 1)))
+
+    def _distribute(self, free: float, mains: List[float], kids: List[Node]) -> None:
+        # space_* justify handles leftover free itself — skip grow when those are set
+        if self.justify in ("space_between", "space_around", "space_evenly"):
+            if free < 0:
+                shrinks = [k.shrink * mains[i] for i, k in enumerate(kids)]
+                total = sum(shrinks)
+                if total > 0:
+                    for i, s in enumerate(shrinks):
+                        mains[i] = max(0.0, mains[i] + free * (s / total))
+            return
+        if free > 0:
+            grows = [k.grow for k in kids]
+            total = sum(grows)
+            if total > 0:
+                for i, g in enumerate(grows):
+                    mains[i] += free * (g / total)
+        elif free < 0:
+            shrinks = [k.shrink * mains[i] for i, k in enumerate(kids)]
+            total = sum(shrinks)
+            if total > 0:
+                for i, s in enumerate(shrinks):
+                    mains[i] = max(0.0, mains[i] + free * (s / total))
+
+    def _title_layout(self, ox: float = 0.0, oy: float = 0.0) -> List[Tuple[str, float, float, float]]:
+        """``[(line, x, baseline_y, width)]`` of the drawn title lines."""
+        from .textutil import measure_text
+
+        if not self.title:
+            return []
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        th = self.theme
+        pt, pr, pb, pl = self.padding
+        lines = self._title_lines()
+        lh = self._title_line_h()
+        n = len(lines)
+        # title baseline: pad + font, with title_gap separating title from kids/border
+        if self.title_pos == "bottom":
+            ty0 = y + g.h - pb - self.title_gap * 0.25 - (n - 1) * lh
+        else:
+            ty0 = y + pt + self._title_font()
+        inset = max(pl, self._title_font() * 0.5) if (self.stroke or self.fill) else pl
+        out = []
+        for i, ln in enumerate(lines):
+            tw, _ = measure_text(ln, self._title_font(), weight="bold")
+            if self.title_align == "left":
+                tx = x + inset
+            elif self.title_align == "right":
+                tx = x + g.w - inset - tw
+            else:
+                tx = x + (g.w - tw) / 2
+            out.append((ln, tx, ty0 + i * lh, tw))
+        return out
+
+    def title_boxes(self) -> List[Tuple[float, float, float, float]]:
+        """v0.12: page boxes ``(x, y, w, h)`` of the title lines (empty without a title)."""
+        fs = self._title_font()
+        return [(tx, tyb - fs * 0.8, tw, fs) for _ln, tx, tyb, tw in self._title_layout()]
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect, draw_text
+
+        g = self.geom
+        x, y = g.x + ox, g.y + oy
+        th = self.theme
+        sw = self.stroke_width if self.stroke_width is not None else th.stroke_width
+        r = (
+            (self.radius if self.radius is not None else th.corner_radius)
+            if self.rounded
+            else 0.0
+        )
+        stroke = self._border_stroke(self.stroke) if self.stroke else None
+        has_stroke = bool(stroke and stroke != "none")
+        # v0.12.0: fill (and pattern) first, children next, the frame stroke LAST —
+        # child boxes no longer paint over a Col(stroke=) / Group(pad=0) outline.
+        if self.fill:
+            draw_rect(buf, x, y, g.w, g.h, fill=self.fill, stroke="none",
+                      stroke_width=0, radius=r)
+        if getattr(self, "pattern", None) is not None:
+            from .primitives import _paint_node_pattern
+
+            _paint_node_pattern(buf, self.pattern, x, y, g.w, g.h)
+        if self.title:
+            for ln, tx, tyb, _tw in self._title_layout(ox, oy):
+                draw_text(buf, ln, tx, tyb, font_size=self._title_font(), weight="bold",
+                          fill=getattr(self, "title_color", None) or "#111111")
+
+        for kid in self._kids:
+            kid.draw(buf, ox, oy)
+        if has_stroke:
+            draw_rect(
+                buf, x, y, g.w, g.h, fill="none", stroke=stroke, stroke_width=sw,
+                radius=r, dasharray=self._dash(sw),
+            )
+
+
+class Row(Container):
+    """Lay children out left → right: ``Row([a, b, c], gap=6, align="center")``.
+
+    Keywords (all optional): ``gap`` (pt, default ``theme.gap``), ``pad``,
+    ``align`` (cross axis: start|center|end|stretch|baseline|optical),
+    ``justify`` (start|center|end|space_between|…), ``equal`` (children share the widest
+    width), ``fill``/``stroke``/``rounded``/``title`` (draw the row as a titled frame).
+    """
+
+    def __init__(self, kids: Optional[Sequence[Node]] = None, **kwargs: Any) -> None:
+        kwargs.setdefault("direction", "row")
+        super().__init__(kids, **kwargs)
+
+
+class Col(Container):
+    """Lay children out top → bottom: ``Col([a, b], gap=4)``. Same keywords as :class:`Row`."""
+
+    def __init__(self, kids: Optional[Sequence[Node]] = None, **kwargs: Any) -> None:
+        kwargs.setdefault("direction", "column")
+        super().__init__(kids, **kwargs)
+
+
+class Stack(Col):
+    """Vertical stack — Col with align=center by default. Accepts align/justify/gap/pad."""
+
+    def __init__(self, kids: Optional[Sequence[Node]] = None, **kwargs: Any) -> None:
+        kwargs.setdefault("align", "center")
+        super().__init__(kids, **kwargs)
+
+
+class Grid(Container):
+    """Simple fixed-column grid; ``row_gap`` / ``col_gap`` override ``gap`` per axis."""
+
+    def __init__(
+        self,
+        kids: Optional[Sequence[Node]] = None,
+        *,
+        cols: int = 2,
+        gap: Optional[float] = None,
+        pad: Union[float, int, Sequence[float]] = 0.0,
+        align: str = "stretch",
+        justify: str = "start",
+        equal_cols: bool = False,
+        equal_rows: bool = False,
+        row_gap: Optional[float] = None,
+        col_gap: Optional[float] = None,
+        **kwargs: Any,
+    ) -> None:
+        # Grid overrides Container layout; still stores kids via Container.
+        super().__init__(
+            kids, direction="row", gap=gap, pad=pad, align=align, justify=justify, **kwargs
+        )
+        self.cols = max(1, cols)
+        # v0.8.0: separate spacing between rows / columns (default: ``gap``)
+        self.row_gap = None if row_gap is None else float(row_gap)
+        self.col_gap = None if col_gap is None else float(col_gap)
+        self.equal_cols = bool(equal_cols)
+        self.equal_rows = bool(equal_rows)
+
+    def _rg(self) -> float:
+        return float(self.gap) if self.row_gap is None else self.row_gap
+
+    def _cg(self) -> float:
+        return float(self.gap) if self.col_gap is None else self.col_gap
+
+    def _measure(self) -> Tuple[float, float]:
+        pt, pr, pb, pl = self.padding
+        if not self._kids:
+            return pl + pr, pt + pb
+        sizes = [k.measure() for k in self._kids]
+        cols = self.cols
+        rows = (len(sizes) + cols - 1) // cols
+        col_w = [0.0] * cols
+        row_h = [0.0] * rows
+        for i, (w, h) in enumerate(sizes):
+            r, c = divmod(i, cols)
+            col_w[c] = max(col_w[c], w)
+            row_h[r] = max(row_h[r], h)
+        if self.equal_cols and col_w:
+            mw = max(col_w)
+            col_w = [mw] * cols
+        if self.equal_rows and row_h:
+            mh = max(row_h)
+            row_h = [mh] * rows
+        w = sum(col_w) + self._cg() * (cols - 1) + pl + pr
+        h = sum(row_h) + self._rg() * (rows - 1) + pt + pb
+        self._col_w = col_w
+        self._row_h = row_h
+        return w, h
+
+    def _layout_children(self) -> None:
+        self.measure()  # ensure _col_w/_row_h
+        g = self.geom
+        pt, pr, pb, pl = self.padding
+        cols = self.cols
+        x0 = g.x + pl
+        y0 = g.y + pt
+        for i, kid in enumerate(self._kids):
+            r, c = divmod(i, cols)
+            cx = x0 + sum(self._col_w[:c]) + self._cg() * c
+            cy = y0 + sum(self._row_h[:r]) + self._rg() * r
+            cw, ch = self._col_w[c], self._row_h[r]
+            mw, mh = kid.measure()
+            align = kid.align_self or self.align
+            if align == "stretch":
+                kid.layout(cx, cy, cw, ch)
+            else:
+                lx = _align_cross(align if align != "stretch" else "start", cw, mw, cx)
+                ly = _align_cross("center", ch, mh, cy)
+                kid.layout(lx, ly, mw, mh)