codefig 0.17.0__py3-none-any.whl

codefig/timeline.py

@@ -0,0 +1,1288 @@
+"""Timelines (Gantt / pipeline schedules) and swimlanes.
+
+* :class:`Timeline` — named lanes with tasks placed in *data units* (time, steps,
+  iterations …): ``tl.task("GPU0", 0, 2.5, "A_p")``. Idle bubbles, dependency arrows,
+  vertical markers, braces / brackets / dimension spans over a time range and an
+  optional time axis with ticks. One unit = ``unit`` pt. Covers Sarathi-Serve style
+  stall diagrams, 1F1B / GPipe pipeline schedules, Llumnix migration timelines,
+  FlexGen schedules.
+* :class:`Lanes` / :class:`Lane` — swimlane container for arbitrary nodes with lane
+  headers (horizontal or vertical). Put it in a :class:`~codefig.edges.Diagram` to
+  draw edges that cross lanes.
+
+No author coordinates: lanes are referenced by name and tasks by their start / dur
+in data units; everything else is laid out automatically.
+"""
+
+from __future__ import annotations
+
+import math
+import warnings
+from typing import Any, Dict, Iterable, List, Optional, Sequence, Tuple, Union
+
+from .constraints import Anchor
+from .edges import Diagram, Edge, Port
+from .node import BoxGeom, Node
+from .primitives import Box, Text, _brace_path_horizontal
+from .styles import Theme, current_theme, themed
+from .textutil import measure_text
+
+SPAN_STYLES = ("brace", "bracket", "dim")
+MARKER_STYLES = ("dashed", "dotted", "solid")
+TASK_KINDS = ("task", "idle", "gap")
+
+_DASH = {"dashed": "5 3", "dotted": "1.5 2.5", "solid": None}
+
+
+class TimelineWarning(UserWarning):
+    """A task label could not be fitted inside its bar, even at the minimum size."""
+
+
+# ============================================================================ Task
+class Task(Box):
+    """A bar on one :class:`Timeline` lane — created by :meth:`Timeline.task` /
+    :meth:`Timeline.idle`, not directly.
+
+    It is a :class:`~codefig.primitives.Box` (role **hard**) whose geometry comes
+    from ``start`` / ``dur`` (data units) and the lane; ``port()``, ``legend=``,
+    ``pattern=``, ``step=`` and constraints work as on any Box. The label font shrinks
+    (down to 60 %) to fit the bar; a label that still does not fit emits
+    :class:`TimelineWarning`.
+
+    Attributes:
+        lane: Lane name.
+        start: Start time (data units).
+        dur: Duration (data units).
+        end: ``start + dur``.
+        kind: ``"task"``, ``"idle"`` or ``"gap"`` (an elided stretch, :meth:`Timeline.elide`).
+    """
+
+    def __init__(self, label: str = "", *, lane: str, start: float, dur: float,
+                 kind: str = "task", **box_kw: Any) -> None:
+        if dur <= 0:
+            raise ValueError(f"task duration must be > 0, got {dur!r}")
+        if kind not in TASK_KINDS:
+            raise ValueError(f"kind must be one of {TASK_KINDS}")
+        box_kw.setdefault("pad", 0)
+        super().__init__(label, **box_kw)
+        self.lane = lane
+        self.start = float(start)
+        self.dur = float(dur)
+        self.kind = kind
+        self._fit_fs: Optional[float] = None
+
+    @property
+    def end(self) -> float:
+        return self.start + self.dur
+
+    def _fs(self) -> float:
+        return self._fit_fs if self._fit_fs is not None else super()._fs()
+
+    def __repr__(self) -> str:
+        return f"Task({self.text!r}, lane={self.lane!r}, start={self.start:g}, dur={self.dur:g})"
+
+
+# ===================================================================== guide parts
+class _Guide(Node):
+    """Invisible-to-check_overlaps scenery (lane bands, plot area, axis line)."""
+
+    _cf_guide = True
+
+    def __init__(self, **kw: Any) -> None:
+        kw.setdefault("obstacle", "background")
+        super().__init__(**kw)
+
+    def _measure(self) -> Tuple[float, float]:
+        return (self.geom.w, self.geom.h)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        pass
+
+
+class LaneBand(_Guide):
+    """Background band of one Timeline lane (``timeline.lane("GPU0")``).
+
+    Role **background** and a *guide*: check_overlaps() ignores it (its tasks sit
+    on it by design); edges may cross it. Use it as a reference for ports / Dim /
+    constraints, e.g. ``Dim(tl.lane("GPU0"), side="left")``.
+    """
+
+    def __init__(self, name: str, *, fill: Optional[str] = None, **kw: Any) -> None:
+        super().__init__(**kw)
+        self.name = name
+        self.fill = fill
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect
+
+        if self.fill:
+            g = self.geom
+            draw_rect(buf, g.x + ox, g.y + oy, g.w, g.h, fill=self.fill, stroke="none",
+                      stroke_width=0)
+
+
+class Marker(_Guide):
+    """Vertical guide line at time ``t`` across all lanes (``timeline.marker(...)``).
+
+    The line is a background *guide* (ignored by check_overlaps(), crossable by
+    edges); its label is a **soft** Text child placed in the band above (or below)
+    the lanes and packed so it never collides with span labels.
+    """
+
+    width = themed(1.0, "SW")
+
+    def __init__(self, t: float, label: str = "", *, style: str = "dashed",
+                 color: str = "#555555", width: Optional[float] = None, label_pos: str = "top",
+                 font_size: float = 11.0, label_color: Optional[str] = None,
+                 theme: Optional[Theme] = None) -> None:
+        if style not in MARKER_STYLES:
+            raise ValueError(f"marker style must be one of {MARKER_STYLES}")
+        if label_pos not in ("top", "bottom"):
+            raise ValueError("marker label_pos must be top|bottom")
+        super().__init__(theme=theme)
+        self.t = float(t)
+        self.style = style
+        self.color = color
+        self.width = width
+        self.label_pos = label_pos
+        self.label = Text(label, font_size=font_size, color=label_color or color,
+                          theme=theme) if label else None
+        if self.label is not None:
+            self.label.parent = self
+        self._line: Tuple[float, float, float] = (0.0, 0.0, 0.0)  # x, y0, y1 (relative)
+
+    def children(self) -> Sequence[Node]:
+        return (self.label,) if self.label is not None else ()
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_line
+
+        # v0.12.0: draw from the (possibly translated) geom, not the layout-time
+        # snapshot — post-layout passes that move the timeline moved tasks but left
+        # marker lines ~5 pt behind (t4 eval).
+        g = self.geom
+        x, y0, y1 = g.x + g.w / 2, g.y, g.y + g.h
+        draw_line(buf, x + ox, y0 + oy, x + ox, y1 + oy, stroke=self.color,
+                  stroke_width=self.width, dasharray=_DASH[self.style])
+        if self.label is not None:
+            self.label.draw(buf, ox, oy)
+
+
+class TimeSpan(Node):
+    """Brace / bracket / dimension line over a time range (``timeline.span(...)``).
+
+    Role **hard** (the drawn strip); its label is a **soft** Text child above
+    (``side="top"``) or below the strip — on the line for ``style="dim"``, where the
+    line is cut around it (knockout). Spans and marker labels are packed into levels
+    automatically so they never collide.
+    """
+
+    width = themed(1.2, "SW")
+
+    def __init__(self, start: float, end: float, label: str = "", *, style: str = "brace",
+                 side: str = "top", color: str = "#333333", width: Optional[float] = None,
+                 font_size: float = 11.0, weight: str = "normal",
+                 label_color: Optional[str] = None, theme: Optional[Theme] = None) -> None:
+        if style not in SPAN_STYLES:
+            raise ValueError(f"span style must be one of {SPAN_STYLES}")
+        if side not in ("top", "bottom"):
+            raise ValueError("span side must be top|bottom")
+        if end <= start:
+            raise ValueError("span end must be > start")
+        super().__init__(theme=theme)
+        self.start, self.end = float(start), float(end)
+        self.style, self.side = style, side
+        self.color, self.width = color, width
+        self.label = Text(label, font_size=font_size, weight=weight,
+                          color=label_color or color, theme=theme) if label else None
+        if self.label is not None:
+            self.label.parent = self
+
+    def strip_h(self) -> float:
+        return {"brace": 9.0, "bracket": 6.0, "dim": 10.0}[self.style]
+
+    def children(self) -> Sequence[Node]:
+        return (self.label,) if self.label is not None else ()
+
+    def _measure(self) -> Tuple[float, float]:
+        return (self.geom.w, self.geom.h)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_arrowhead, draw_line, draw_path
+
+        g = self.geom
+        x, y, w, h = g.x + ox, g.y + oy, g.w, g.h
+        if self.style in ("brace", "bracket"):
+            d = _brace_path_horizontal(x, y, w, h, open_up=self.side == "top",
+                                       style="curly" if self.style == "brace" else "square")
+            draw_path(buf, d, stroke=self.color, stroke_width=self.width)
+        else:
+            cy = y + h / 2
+            segs = [(x, x + w)]
+            if self.label is not None:
+                lg = self.label.geom
+                L = self.theme.L
+                a, b = lg.x + ox - L(3), lg.x + ox + lg.w + L(3)
+                segs = [(x, a), (b, x + w)] if a > x + L(8) and b < x + w - L(8) else segs
+            for s0, s1 in segs:
+                draw_line(buf, s0, cy, s1, cy, stroke=self.color, stroke_width=self.width)
+            for xx in (x, x + w):
+                draw_line(buf, xx, y, xx, y + h, stroke=self.color, stroke_width=self.width)
+            hl, hw = self.theme.head_dims(5, 4)
+            draw_arrowhead(buf, x, cy, math.pi, size=hl, length=hl, width=hw, color=self.color)
+            draw_arrowhead(buf, x + w, cy, 0.0, size=hl, length=hl, width=hw, color=self.color)
+        if self.label is not None:
+            self.label.draw(buf, ox, oy)
+
+
+class _Axis(_Guide):
+    """Time axis: line + ticks + arrow (guide); tick labels / title are soft Text kids."""
+
+    def __init__(self, *, color: str, title: Optional[Text], tick_labels: List[Text],
+                 theme: Optional[Theme] = None) -> None:
+        super().__init__(theme=theme)
+        self.color = color
+        self.title = title
+        self.tick_labels = tick_labels
+        for t in self.children():
+            t.parent = self
+        self._line: Tuple[float, float, float] = (0.0, 0.0, 0.0)  # x0, x1, y (relative)
+        self._ticks: List[float] = []
+
+    def children(self) -> Sequence[Node]:
+        return list(self.tick_labels) + ([self.title] if self.title is not None else [])
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_arrowhead, draw_line
+
+        th = self.theme
+        g = self.geom
+        lx0, lx1, ly = self._line
+        dx, dy = g.x - self.__dict__.get("_lay_x", g.x), g.y - self.__dict__.get("_lay_y", g.y)
+        x0, x1, y = lx0 + dx, lx1 + dx, ly + dy
+        draw_line(buf, x0 + ox, y + oy, x1 + ox - th.L(2), y + oy, stroke=self.color,
+                  stroke_width=th.SW(1.2))
+        hl, hw = th.head_dims(7, 6)
+        draw_arrowhead(buf, x1 + ox, y + oy, 0.0, size=hl, length=hl, width=hw, color=self.color)
+        for tx in self._ticks:
+            tx += dx
+            draw_line(buf, tx + ox, y + oy, tx + ox, y + oy + th.L(4), stroke=self.color,
+                      stroke_width=th.SW(1.0))
+        for t in self.children():
+            t.draw(buf, ox, oy)
+
+
+class Event(_Guide):
+    """v0.12.0: a point event on the time axis — a small ▲ under the lanes (on the
+    axis line, below its tick labels, when there is an axis) with a label under it.
+    Created by :meth:`Timeline.event`. The glyph is a guide; the label is **soft**
+    Text, packed on levels so neighbouring event labels never collide.
+    """
+
+    def __init__(self, t: float, label: str = "", *, color: str = "#333333",
+                 font_size: float = 11.0, theme: Optional[Theme] = None) -> None:
+        super().__init__(theme=theme)
+        self.t = float(t)
+        self.color = color
+        self.label = Text(label, font_size=font_size, color=color, theme=theme) if label else None
+        if self.label is not None:
+            self.label.parent = self
+
+    def children(self) -> Sequence[Node]:
+        return (self.label,) if self.label is not None else ()
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_path
+
+        g = self.geom
+        cx, y0, y1 = g.x + g.w / 2 + ox, g.y + oy, g.y + g.h + oy
+        d = f"M{cx:.2f},{y0:.2f} L{g.x + g.w + ox:.2f},{y1:.2f} L{g.x + ox:.2f},{y1:.2f} Z"
+        draw_path(buf, d, fill=self.color, stroke="none", stroke_width=0)
+        if self.label is not None:
+            self.label.draw(buf, ox, oy)
+
+
+# ============================================================================ body
+class _TimelineBody(Node):
+    """Layout-only content of a Timeline (places lanes, tasks, spans, markers, axis)."""
+
+    def __init__(self, tl: "Timeline", theme: Theme) -> None:
+        super().__init__(theme=theme)
+        self.tl = tl
+        self._plan: Optional[Dict[str, Any]] = None
+
+    def children(self) -> Sequence[Node]:
+        tl = self.tl
+        out: List[Node] = [tl._plot]
+        out += [tl._bands[n] for n in tl.lanes]
+        out += [tl._headers[n] for n in tl.lanes if tl._headers[n] is not None]
+        out += tl.tasks
+        out += tl.spans
+        out += tl.markers
+        out += tl.events
+        if tl._axis is not None:
+            out.append(tl._axis)
+        return out
+
+    def invalidate(self) -> None:
+        super().invalidate()
+        self._plan = None
+        for n in self.children():
+            n.invalidate()
+
+    # ---- planning (relative coordinates, origin = body top-left) -------------
+    def _make_plan(self) -> Dict[str, Any]:
+        _L = self.theme.L
+        tl = self.tl
+        fs = tl._fs()
+        lh = fs * 1.25
+        heads = [tl._headers[n] for n in tl.lanes]
+        hw = tl.header_w if tl.header_w is not None else max(
+            [h.measure()[0] for h in heads if h is not None], default=0.0)
+        hgap = _L(8.0) if hw > 0 else 0.0
+        t0 = tl.start
+        cands = [t.end for t in tl.tasks] + [m.t for m in tl.markers] + [s.end for s in tl.spans]
+        cands += [e.t for e in tl.events]
+        if tl._ticks_explicit:
+            cands += list(tl._ticks_explicit)
+        t1 = tl.end if tl.end is not None else max(cands + [t0 + 1.0])
+        if t1 <= t0:
+            raise ValueError("Timeline end must be after start")
+        upx = (tl.width / (t1 - t0)) if tl.width is not None else tl.unit
+        px0 = hw + hgap
+
+        def X(t: float) -> float:
+            return px0 + (t - t0) * upx
+
+        # --- level packing for top / bottom annotation bands ---
+        def pack(items: List[Tuple[float, float, float, Any]]) -> List[Tuple[float, List[Any]]]:
+            levels: List[Tuple[float, List[Any], float]] = []  # (height, objs, right edge)
+            out: List[List[Any]] = []
+            hs: List[float] = []
+            rights: List[float] = []
+            last: List[Any] = []
+
+            def snug(o: Any, x0: float, x1: float) -> bool:
+                # a span whose label fits inside its own range: neighbours may touch it
+                return (isinstance(o, TimeSpan) and abs(x0 - X(o.start)) < 1e-6
+                        and abs(x1 - X(o.end)) < 1e-6)
+
+            for x0, x1, h, obj in items:
+                for i in range(len(out)):
+                    px0, px1, _ph, pobj = out[i][-1]
+                    gap = -1e-6 if snug(obj, x0, x1) and snug(pobj, px0, px1) else _L(6.0)
+                    if x0 >= rights[i] + gap:
+                        out[i].append((x0, x1, h, obj))
+                        hs[i] = max(hs[i], h)
+                        rights[i] = x1
+                        break
+                else:
+                    out.append([(x0, x1, h, obj)])
+                    hs.append(h)
+                    rights.append(x1)
+            return [(hs[i], out[i]) for i in range(len(out))]
+
+        def _dim_fits(s: TimeSpan, a: float, b: float, lw: float) -> bool:
+            # v0.12 (B6): a dim label sits on the line only when the line keeps ≥ 8 pt
+            # each side of it; otherwise it moves off the line like a brace label
+            return s.label is None or lw + _L(6.0) < (b - a) - _L(16.0)
+
+        self._dim_fits = _dim_fits
+
+        def span_item(s: TimeSpan) -> Tuple[float, float, float, Any]:
+            a, b = X(s.start), X(s.end)
+            lw, lhh = s.label.measure() if s.label is not None else (0.0, 0.0)
+            c = (a + b) / 2
+            x0, x1 = min(a, c - lw / 2), max(b, c + lw / 2)
+            if s.style == "dim" and _dim_fits(s, a, b, lw):
+                h = max(lhh, s.strip_h())
+            else:
+                h = s.strip_h() + (_L(2.0) + lhh if s.label is not None else 0.0)
+            return (x0, x1, h, s)
+
+        def marker_item(m: Marker) -> Tuple[float, float, float, Any]:
+            lw, lhh = m.label.measure()
+            c = X(m.t)
+            return (c - lw / 2, c + lw / 2, lhh, m)
+
+        top_items = [marker_item(m) for m in tl.markers if m.label is not None and m.label_pos == "top"]
+        bot_items = [marker_item(m) for m in tl.markers if m.label is not None and m.label_pos == "bottom"]
+        top_items.sort(key=lambda it: it[0])
+        bot_items.sort(key=lambda it: it[0])
+        top_levels = pack(top_items) if top_items else []
+        bot_levels = pack(bot_items) if bot_items else []
+        # spans pack *outside* the marker-label levels
+        sp_top = sorted((span_item(s) for s in tl.spans if s.side == "top"), key=lambda i: i[0])
+        sp_bot = sorted((span_item(s) for s in tl.spans if s.side == "bottom"), key=lambda i: i[0])
+        top_levels += pack(sp_top) if sp_top else []
+        bot_levels += pack(sp_bot) if sp_bot else []
+        lgap = _L(5.0)
+        top_h = sum(h + lgap for h, _ in top_levels)
+        n = len(tl.lanes)
+        lanes_top = top_h + (_L(2.0) if top_levels else 0.0)
+        lg = tl.lane_gap if not tl._cross_deps else max(tl.lane_gap, _L(12.0))
+        lane_y = {name: lanes_top + i * (tl.lane_h + lg) for i, name in enumerate(tl.lanes)}
+        lanes_bot = lanes_top + n * tl.lane_h + max(n - 1, 0) * lg
+        place: Dict[int, Tuple[float, float, float, float]] = {}  # id(obj) → x0,x1,y,h (level slot)
+        y = lanes_top - _L(2.0)
+        for h, objs in top_levels:
+            y -= lgap + h
+            for x0, x1, _h, obj in objs:
+                place[id(obj)] = (x0, x1, y, h)
+        y = lanes_bot + _L(2.0)
+        for h, objs in bot_levels:
+            y += lgap
+            for x0, x1, _h, obj in objs:
+                place[id(obj)] = (x0, x1, y, h)
+            y += h
+        bottom = y if bot_levels else lanes_bot
+        axis_y = None
+        x_right = X(t1)
+        if tl._axis is not None:
+            axis_y = bottom + _L(8.0)
+            bottom = axis_y + _L(4.0) + (_L(2.0) + lh if tl._axis.tick_labels else 0.0)
+            x_right = X(t1) + _L(14.0)
+            if tl._axis.title is not None:
+                tw, th = tl._axis.title.measure()
+                x_right += _L(4.0) + tw
+                bottom = max(bottom, axis_y + th / 2)
+        # v0.12.0 (C8): point events — ▲ under the lanes / on the axis, labels packed
+        ev_y = None
+        ev_tri = _L(5.0)
+        if tl.events:
+            if axis_y is not None:
+                ev_y = axis_y + (_L(5.0) + lh + _L(2.0) if tl._ticks is not None else _L(1.5))
+            else:
+                ev_y = bottom + _L(4.0)
+            ev_items = []
+            for e in tl.events:
+                c = X(e.t)
+                lw, lhh = e.label.measure() if e.label is not None else (0.0, 0.0)
+                ev_items.append((c - max(lw / 2, ev_tri * 0.6), c + max(lw / 2, ev_tri * 0.6), lhh, e))
+            ev_items.sort(key=lambda it: it[0])
+            yy = ev_y + ev_tri + _L(1.5)
+            for h, objs in pack(ev_items):
+                for x0, x1, _h, obj in objs:
+                    place[id(obj)] = (x0, x1, yy, h)
+                yy += h + _L(1.0)
+            bottom = max(bottom, yy)
+        lefts = [0.0] + [p[0] for p in place.values()]
+        rights = [x_right] + [p[1] for p in place.values()]
+        tick_x = [X(t) for t in tl._tick_values(t0, t1)]
+        if tl._axis is not None and tl._axis.tick_labels:
+            for tx, lab in zip(tick_x, tl._axis.tick_labels):
+                w = lab.measure()[0]
+                lefts.append(tx - w / 2)
+                rights.append(tx + w / 2)
+        shift = -min(lefts)
+        width = max(rights) + shift
+        return dict(X=X, shift=shift, width=width, height=bottom, hw=hw, px0=px0, t0=t0,
+                    t1=t1, upx=upx, lane_y=lane_y, lanes_top=lanes_top, lanes_bot=lanes_bot,
+                    place=place, axis_y=axis_y, tick_x=tick_x, lh=lh, ev_y=ev_y, ev_tri=ev_tri)
+
+    def plan(self) -> Dict[str, Any]:
+        if self._plan is None:
+            self._plan = self._make_plan()
+        return self._plan
+
+    def _measure(self) -> Tuple[float, float]:
+        p = self.plan()
+        return (p["width"], p["height"])
+
+    def x_of(self, t: float) -> float:
+        p = self.plan()
+        return self.geom.x + p["shift"] + p["X"](t)
+
+    def _layout_children(self) -> None:
+        _L = self.theme.L
+        tl = self.tl
+        p = self.plan()
+        ox, oy = self.geom.x + p["shift"], self.geom.y
+        X = p["X"]
+        x0, x1 = X(p["t0"]) + ox, X(p["t1"]) + ox
+        top, bot = p["lanes_top"] + oy, p["lanes_bot"] + oy
+        tl._plot.layout(x0, top, x1 - x0, bot - top)
+        for name in tl.lanes:
+            ly = p["lane_y"][name] + oy
+            tl._bands[name].layout(x0, ly, x1 - x0, tl.lane_h)
+            h = tl._headers[name]
+            if h is not None:
+                hw_, hh = h.measure()
+                h.layout(ox + p["hw"] - hw_, ly + (tl.lane_h - hh) / 2, hw_, hh)
+        for t in tl.tasks:
+            a, b = X(t.start) + ox, X(t.end) + ox
+            t.layout(a, p["lane_y"][t.lane] + oy, b - a, tl.lane_h)
+            self._fit_label(t, b - a)
+            if t.step is not None:
+                t._layout_children()
+        lane_tops = [p["lane_y"][n] + oy for n in tl.lanes]
+        for m in tl.markers:
+            mx = X(m.t) + ox
+            y0, y1 = top - _L(3.0), bot + _L(3.0)
+            if m.label is not None:
+                _x0, _x1, ly, lh_ = p["place"][id(m)]
+                lw, lhh = m.label.measure()
+                m.label.layout(mx - lw / 2, ly + oy + (lh_ - lhh) / 2, lw, lhh)
+                if m.label_pos == "top":
+                    y0 = m.label.geom.bottom + _L(1.0)
+                else:
+                    y1 = m.label.geom.y - _L(1.0)
+            m.layout(mx - 0.5, y0, 1.0, y1 - y0)
+            m._line = (mx, y0, y1)
+        for s in tl.spans:
+            a, b = X(s.start) + ox, X(s.end) + ox
+            _x0, _x1, ly, lvl_h = p["place"][id(s)]
+            # v0.12 (B5): spans that touch on one level keep a hairline gap
+            for o in tl.spans:
+                if o is s or o.side != s.side or p["place"][id(o)][2] != p["place"][id(s)][2]:
+                    continue
+                if abs(o.end - s.start) < 1e-9:
+                    a += _L(1.0)
+                if abs(o.start - s.end) < 1e-9:
+                    b -= _L(1.0)
+            ly += oy
+            sh = s.strip_h()
+            lw, lhh = s.label.measure() if s.label is not None else (0.0, 0.0)
+            if s.style == "dim" and not self._dim_fits(s, X(s.start), X(s.end), lw):
+                if s.side == "top":
+                    sy = ly + lvl_h - sh
+                    s.layout(a, sy, b - a, sh)
+                    s.label.layout((a + b) / 2 - lw / 2, sy - _L(1.0) - lhh, lw, lhh)
+                else:
+                    s.layout(a, ly, b - a, sh)
+                    s.label.layout((a + b) / 2 - lw / 2, ly + sh + _L(1.0), lw, lhh)
+            elif s.style == "dim":
+                cy = ly + lvl_h / 2 if s.side == "top" else ly + lvl_h / 2
+                s.layout(a, cy - sh / 2, b - a, sh)
+                if s.label is not None:
+                    s.label.layout((a + b) / 2 - lw / 2, cy - lhh / 2, lw, lhh)
+            elif s.side == "top":  # strip nearest the lanes, label above it
+                sy = ly + lvl_h - sh
+                s.layout(a, sy, b - a, sh)
+                if s.label is not None:
+                    s.label.layout((a + b) / 2 - lw / 2, sy - _L(2.0) - lhh, lw, lhh)
+            else:
+                s.layout(a, ly, b - a, sh)
+                if s.label is not None:
+                    s.label.layout((a + b) / 2 - lw / 2, ly + sh + _L(2.0), lw, lhh)
+        for e in tl.events:
+            ex = X(e.t) + ox
+            tri = p["ev_tri"]
+            e.layout(ex - tri * 0.6, p["ev_y"] + oy, tri * 1.2, tri)
+            if e.label is not None:
+                _x0, _x1, ly, _h = p["place"][id(e)]
+                lw, lhh = e.label.measure()
+                e.label.layout(ex - lw / 2, ly + oy, lw, lhh)
+        ax = tl._axis
+        if ax is not None:
+            ay = p["axis_y"] + oy
+            xe = X(p["t1"]) + ox + _L(14.0)
+            ax._line = (X(p["t0"]) + ox, xe, ay)
+            ax._ticks = [tx + ox for tx in p["tick_x"]] if tl._ticks is not None else []
+            ax.layout(x0, ay - 1, xe - x0, 2)
+            ax.__dict__["_lay_x"], ax.__dict__["_lay_y"] = ax.geom.x, ax.geom.y
+            for tx, lab in zip(p["tick_x"], ax.tick_labels):
+                w, h = lab.measure()
+                lab.layout(tx + ox - w / 2, ay + _L(5.0), w, h)
+            if ax.title is not None:
+                w, h = ax.title.measure()
+                ax.title.layout(xe + _L(4.0), ay - h / 2, w, h)
+        del lane_tops
+
+    def _fit_label(self, t: Task, w: float) -> None:
+        _L = self.theme.L
+        t._fit_fs = None
+        if not t.text:
+            return
+        fs0 = t._fs()
+        lw, lh = measure_text(t.text, fs0, weight=t.weight)
+        avail_w = w - _L(4.0)
+        avail_h = self.tl.lane_h - _L(2.0)
+        k = min(1.0, avail_w / lw if lw > 0 else 1.0, avail_h / lh if lh > 0 else 1.0)
+        if k < 1.0:
+            th = self.theme
+            floor = fs0 * 0.6 if th.unit == 1.0 else min(fs0, th.small_size)
+            fs = max(floor, fs0 * k)
+            t._fit_fs = fs
+            if fs0 * k < floor - 1e-6:
+                warnings.warn(TimelineWarning(
+                    f"task label {t.text!r} ({t.dur:g} units on lane {t.lane!r}) does not "
+                    f"fit its {w:.1f}-wide bar; shorten it, use a larger unit, or put it in "
+                    f"a legend"), stacklevel=2)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        for n in self.children():
+            n.draw(buf, ox, oy)
+
+
+# ======================================================================== Timeline
+class Timeline(Diagram):
+    """Gantt-style schedule: named lanes, tasks in data units, bubbles, dependencies,
+    markers, spans and an optional time axis.
+
+    The Timeline is a :class:`~codefig.edges.Diagram` — dependency arrows
+    (:meth:`depend`) and any extra :class:`~codefig.edges.Edge` /
+    :class:`~codefig.dim.Dim` added with ``tl.add_edge(...)`` are routed over it.
+
+    Layering: tasks are **hard** Boxes; lane headers, marker / span / tick labels are
+    **soft** Text; spans are **hard**; lane bands, marker lines and the axis line are
+    background *guides* that check_overlaps() ignores.
+
+    Args:
+        lanes: Lane names, top to bottom (also the header texts; ``""`` hides one).
+        unit: pt per data unit (default 36). Ignored when ``width`` is set.
+        width: Plot width in pt for the whole ``start``..``end`` range (overrides ``unit``);
+            the lane-header column comes on top of it.
+        start: First visible time (default 0).
+        end: Last visible time (default: the latest task / marker / span end).
+        axis: ``False`` (default, no axis), ``True`` (arrow axis below the lanes) or a
+            title string drawn at the arrow tip (e.g. ``"Time"``).
+        ticks: ``None`` (no ticks), a step in data units (``1`` → every unit) or an
+            explicit list of tick times. Ticks imply ``axis=True``.
+        tick_format: ``str.format`` pattern or callable for tick labels (default ``"{:g}"``).
+        lane_h: Lane (bar) height in pt (default 24).
+        lane_gap: Gap between lanes in pt (default 4; at least 12 while a cross-lane
+            :meth:`depend` arrow exists).
+        lane_fill: Band colour behind each lane — one colour, a list cycled over lanes,
+            or ``None`` (default, no bands).
+        header_w: Width of the lane-header column in pt (default: widest header).
+        header_weight: Header font weight (default ``"bold"``).
+        font_size: Base font size in pt (default ``0.92 × theme.font_size``); task
+            labels use 0.92 × that and shrink to fit their bar.
+        task_fill: Default task fill (default ``"#dbe8f6"``).
+        idle_fill: Default fill of :meth:`idle` bubbles (default ``"#d9d9d9"``).
+        stroke: Task outline colour (default ``"#333333"``).
+        stroke_width: Task outline width in pt (default 1.0).
+        theme: Theme.
+
+    Example:
+        >>> from codefig import Figure, Timeline
+        >>> tl = Timeline(["GPU0", "GPU1"], unit=30, axis="Time")
+        >>> a = tl.task("GPU0", 0, 2, "A_p", fill="#9ecae1")
+        >>> b = tl.task("GPU1", 2, 2, "A_p", fill="#9ecae1")
+        >>> _ = tl.idle("GPU1", 0, 2)
+        >>> _ = tl.depend(a, b)
+        >>> _ = tl.span(0, 2, "**bubble**", side="bottom")
+        >>> fig = Figure(size="auto", cols=1)
+        >>> _ = fig.panel("a").set(tl)
+        >>> svg = fig.to_svg()
+    """
+
+    def __init__(
+        self,
+        lanes: Sequence[str],
+        *,
+        unit: Optional[float] = None,
+        width: Optional[float] = None,
+        start: float = 0.0,
+        end: Optional[float] = None,
+        axis: Union[bool, str] = False,
+        ticks: Union[None, float, Sequence[float]] = None,
+        tick_format: Any = "{:g}",
+        lane_h: Optional[float] = None,
+        lane_gap: Optional[float] = None,
+        lane_fill: Union[None, str, Sequence[str]] = None,
+        header_w: Optional[float] = None,
+        header_weight: str = "bold",
+        font_size: Optional[float] = None,
+        task_fill: str = "#dbe8f6",
+        idle_fill: str = "#d9d9d9",
+        stroke: str = "#333333",
+        stroke_width: Optional[float] = None,
+        theme: Optional[Theme] = None,
+        **kwargs: Any,
+    ) -> None:
+        lanes = [str(l) for l in lanes]
+        if not lanes:
+            raise ValueError("Timeline needs at least one lane")
+        if len(set(lanes)) != len(lanes):
+            raise ValueError("Timeline lane names must be unique")
+        if (unit is not None and unit <= 0) or (lane_h is not None and lane_h <= 0):
+            raise ValueError("unit and lane_h must be > 0")
+        th = theme
+        self.lanes: List[str] = lanes
+        self.unit = unit
+        self.width = float(width) if width is not None else None
+        self.start = float(start)
+        self.end = float(end) if end is not None else None
+        self.lane_h = lane_h
+        self.lane_gap = lane_gap
+        self._cross_deps = 0
+        self.header_w = float(header_w) if header_w is not None else None
+        self.font_size = font_size
+        self.task_fill = task_fill
+        self.idle_fill = idle_fill
+        self.stroke = stroke
+        self.stroke_width = stroke_width
+        self.tick_format = tick_format
+        if ticks is not None and not isinstance(ticks, (int, float)):
+            self._ticks_explicit: Optional[List[float]] = [float(t) for t in ticks]
+        else:
+            self._ticks_explicit = None
+        self._ticks = ticks
+        if ticks is not None and isinstance(ticks, (int, float)) and ticks <= 0:
+            raise ValueError("ticks step must be > 0")
+        fills: List[Optional[str]]
+        if lane_fill is None or isinstance(lane_fill, str):
+            fills = [lane_fill] * len(lanes)
+        else:
+            lf = list(lane_fill)
+            fills = [lf[i % len(lf)] for i in range(len(lanes))]
+        self.tasks: List[Task] = []
+        self.markers: List[Marker] = []
+        self.spans: List[TimeSpan] = []
+        self.events: List[Event] = []
+        self._plot = _Guide(theme=th)
+        self._bands: Dict[str, LaneBand] = {n: LaneBand(n, fill=f, theme=th)
+                                            for n, f in zip(lanes, fills)}
+        self._headers: Dict[str, Optional[Text]] = {
+            n: (Text(n, font_size=self._fs_spec(), weight=header_weight, align="right", theme=th)
+                if n else None) for n in lanes}
+        self._axis: Optional[_Axis] = None
+        self._want_axis = axis
+        body = _TimelineBody(self, th)
+        super().__init__(body, [], theme=theme, **kwargs)
+        self.body = body
+        self._build_axis()
+        for n in body.children():
+            n.parent = body
+
+    # ---- helpers ------------------------------------------------------------
+    unit = themed(36.0)
+    lane_h = themed(24.0)
+    lane_gap = themed(4.0)
+    stroke_width = themed(1.0, "SW")
+
+    @property
+    def _theme_(self) -> Theme:
+        return self.theme
+
+    def _fs_spec(self, k: float = 1.0) -> Any:
+        """Font size for child Text: a number, or lazy ``theme -> size``."""
+        if self.font_size is not None:
+            return float(self.font_size) * k
+        return lambda th: th.font_size * 0.92 * k
+
+    def _fs(self) -> float:
+        return float(self.font_size) if self.font_size is not None else self._theme_.font_size * 0.92
+
+    def _adopt(self, n: Node) -> None:
+        n.parent = self.body
+        self.body._plan = None
+        self.body.invalidate()
+        Node.invalidate(self)
+
+    def _tick_values(self, t0: float, t1: float) -> List[float]:
+        if self._ticks is None:
+            return []
+        if self._ticks_explicit is not None:
+            return list(self._ticks_explicit)
+        step = float(self._ticks)  # type: ignore[arg-type]
+        n = int(math.floor((t1 - t0) / step + 1e-9))
+        return [t0 + i * step for i in range(n + 1)]
+
+    def _fmt(self, t: float) -> str:
+        f = self.tick_format
+        return f(t) if callable(f) else str(f).format(t)
+
+    def _build_axis(self) -> None:
+        if not self._want_axis and self._ticks is None:
+            self._axis = None
+            return
+        title = None
+        if isinstance(self._want_axis, str) and self._want_axis:
+            title = Text(self._want_axis, font_size=self._fs_spec(), theme=self._theme)
+        # tick labels need the final range — built lazily in _refresh_ticks()
+        self._axis = _Axis(color=self.stroke, title=title, tick_labels=[], theme=self._theme)
+        self._axis.parent = self.body
+
+    def _refresh_ticks(self) -> None:
+        if self._axis is None or self._ticks is None:
+            return
+        cands = [t.end for t in self.tasks] + [m.t for m in self.markers] + [s.end for s in self.spans]
+        cands += [e.t for e in self.events]
+        t1 = self.end if self.end is not None else max(cands + [self.start + 1.0])
+        vals = self._tick_values(self.start, t1)
+        fs = self._fs_spec(0.9)
+        self._axis.tick_labels = [Text(self._fmt(v), font_size=fs, color="#333333",
+                                       theme=self._theme) for v in vals]
+        for t in self._axis.tick_labels:
+            t.parent = self._axis
+
+    def measure(self) -> Tuple[float, float]:
+        if self._measured is None:
+            self._refresh_ticks()
+            self.body._plan = None
+        return super().measure()
+
+    def _lane_check(self, lane: str) -> None:
+        if lane not in self._bands:
+            raise KeyError(f"unknown lane {lane!r}; lanes are {self.lanes}")
+
+    # ---- public API -----------------------------------------------------------
+    def task(self, lane: str, start: float, dur: float, label: str = "", *,
+             fill: Optional[Any] = None, hatch: Any = None, text_color: Optional[str] = None,
+             font_size: Optional[float] = None, weight: str = "normal",
+             stroke: Optional[str] = None, stroke_width: Optional[float] = None,
+             legend: Optional[str] = None, id: Optional[str] = None,
+             kind: str = "task", **box_kw: Any) -> Task:
+        """Add a bar on ``lane`` from ``start`` for ``dur`` data units.
+
+        Args:
+            lane: Lane name (must be one of ``lanes``).
+            start: Start time in data units.
+            dur: Duration in data units (> 0).
+            label: Text centred in the bar (rich text / ``A_p`` subscripts allowed);
+                shrinks down to 60 % to fit.
+            fill: Bar colour (default ``task_fill``; white when ``hatch`` is set).
+            hatch: ``True`` (grey 45° hatching), a colour string (hatching in that
+                colour) or a :class:`~codefig.legend.Hatch`.
+            text_color: Label colour (default ``"#111111"``).
+            font_size: Label size in pt (default ``0.92 × font_size``).
+            weight: Label weight.
+            stroke / stroke_width: Outline (defaults: the Timeline's).
+            legend: Legend entry for an auto :class:`~codefig.legend.Legend`.
+            id: Node id (for ``check_overlaps()`` messages).
+            kind: ``"task"`` or ``"idle"`` (used by :meth:`idle`).
+            **box_kw: Further :class:`~codefig.primitives.Box` options (``border=``,
+                ``rounded=``, ``step=`` …).
+
+        Returns:
+            The :class:`Task` node (use it for :meth:`depend`, ports, constraints).
+        """
+        from .legend import Hatch
+
+        self._lane_check(lane)
+        pattern = None
+        if hatch is not None and hatch is not False:
+            if isinstance(hatch, Hatch):
+                pattern = hatch
+            elif isinstance(hatch, str):
+                pattern = Hatch(color=hatch, spacing=4.0, width=1.0)
+            else:
+                pattern = Hatch(spacing=4.0, width=0.9)
+            if fill is None:
+                fill = "#ffffff"
+        if fill is None:
+            fill = self.task_fill if kind == "task" else self.idle_fill
+        t = Task(label, lane=lane, start=start, dur=dur, kind=kind, fill=fill, pattern=pattern,
+                 text_color=text_color or ("#444444" if kind == "idle" else "#111111"),
+                 font_size=font_size if font_size is not None else self._fs() * 0.92,
+                 weight=weight, stroke=stroke or self.stroke,
+                 stroke_width=stroke_width if stroke_width is not None else self.stroke_width,
+                 legend=legend, id=id, theme=self._theme, **box_kw)
+        self.tasks.append(t)
+        self._adopt(t)
+        return t
+
+    def idle(self, lane: str, start: float, dur: float, label: str = "", **kw: Any) -> Task:
+        """Add an idle period / pipeline bubble (same args as :meth:`task`).
+
+        Drawn hatched (grey 45° lines on white) by default; ``hatch=False`` gives a
+        plain ``idle_fill`` grey bar, ``hatch="#c0392b"`` / a :class:`~codefig.legend.Hatch`
+        other hatchings. Example: ``tl.idle("GPU1", 0, 2, legend="bubble")``.
+        """
+        kw.setdefault("kind", "idle")
+        kw.setdefault("hatch", True)
+        return self.task(lane, start, dur, label, **kw)
+
+    def seq(self, lane: str, start: float, items: Iterable[Any], *, gap: float = 0.0) -> List[Task]:
+        """Add back-to-back tasks on one lane starting at ``start``.
+
+        Args:
+            lane: Lane name.
+            start: Start of the first task (data units).
+            items: Each a ``(dur, label)`` / ``(dur, label, fill)`` tuple or a dict of
+                :meth:`task` keyword args with ``dur`` (``{"dur": 1, "label": "F1",
+                "kind": "idle"}``).
+            gap: Idle gap between consecutive items (data units, default 0).
+
+        Returns:
+            The created tasks in order.
+        """
+        out: List[Task] = []
+        t = float(start)
+        for it in items:
+            if isinstance(it, dict):
+                kw = dict(it)
+                dur = float(kw.pop("dur"))
+                label = kw.pop("label", "")
+            else:
+                dur, label = float(it[0]), (it[1] if len(it) > 1 else "")
+                kw = {"fill": it[2]} if len(it) > 2 else {}
+            out.append(self.task(lane, t, dur, label, **kw))
+            t += dur + gap
+        return out
+
+    def depend(self, a: Task, b: Task, **edge_kw: Any) -> Edge:
+        """Dependency arrow from task ``a`` to task ``b`` (added to this Timeline).
+
+        Same lane: ``a.right → b.left``. Different lanes: from ``a``'s bottom (top)
+        edge just before its end to ``b``'s top (bottom) edge just after its start
+        (inset ``min(15 % of the bar, 6 pt)``). Straight by default; pass any
+        :class:`~codefig.edges.Edge` keyword (``route="ortho"``, ``style="dashed"``,
+        ``label=`` …) to override. While a cross-lane dependency exists the gap between
+        lanes is at least 12 px (``lane_gap`` is raised) so the arrow stays visible.
+
+        Returns:
+            The created Edge.
+        """
+        ia, ib = self.lanes.index(a.lane), self.lanes.index(b.lane)
+        if ia == ib:
+            src, dst = a.port("right"), b.port("left")
+        else:
+            upx = self.unit if self.width is None else None
+
+            def inset(t: Task) -> float:
+                f = 0.15
+                if upx:
+                    f = min(f, 6.0 / max(t.dur * upx, 1e-6))
+                return f
+
+            fa, fb = 1.0 - inset(a), inset(b)
+            if ia < ib:
+                src, dst = a.port("bottom", at=fa), b.port("top", at=fb)
+            else:
+                src, dst = a.port("top", at=fa), b.port("bottom", at=fb)
+            self._cross_deps += 1
+            self.body.invalidate()
+        kw: Dict[str, Any] = dict(route="straight", color="#333333", stub=0.0, overlap="allow")
+        if self.theme.unit == 1.0:  # classic px look
+            kw.update(width=1.2, head_size=7)
+        kw.update(edge_kw)
+        e = Edge(src, dst, **kw)
+        self.edges.append(e)
+        return e
+
+    def marker(self, t: float, label: str = "", *, style: str = "dashed",
+               color: Optional[str] = None, width: Optional[float] = None, label_pos: str = "top",
+               font_size: Optional[float] = None, label_color: Optional[str] = None) -> Marker:
+        """Vertical guide line at time ``t`` across all lanes (iteration boundaries,
+        deadlines, "migration starts" …).
+
+        Args:
+            t: Time in data units.
+            label: Optional label above (``label_pos="top"``) or below the lanes.
+            style: ``"dashed"`` (default), ``"dotted"`` or ``"solid"``.
+            color: Line / label colour (default ``"#555555"``).
+            width: Line width (default: the theme thin stroke; 1 px classic).
+            label_pos: ``"top"`` or ``"bottom"``.
+            font_size: Label size (default ``0.85 × font_size``).
+            label_color: Label colour (default: ``color``).
+        """
+        m = Marker(t, label, style=style, color=color or "#555555", width=width,
+                   label_pos=label_pos, font_size=font_size or self._fs() * 0.85,
+                   label_color=label_color, theme=self._theme)
+        self.markers.append(m)
+        self._adopt(m)
+        return m
+
+    def span(self, start: float, end: float, label: str = "", *, style: str = "brace",
+             side: str = "top", color: Optional[str] = None, width: Optional[float] = None,
+             font_size: Optional[float] = None, weight: str = "normal",
+             label_color: Optional[str] = None) -> TimeSpan:
+        """Brace / bracket / dimension line over ``start``..``end`` (data units).
+
+        Args:
+            start / end: Time range in data units.
+            label: Text beside the span (rich text, e.g. ``"**Bubble** due to …"``).
+            style: ``"brace"`` (default, curly), ``"bracket"`` (square) or ``"dim"``
+                (``|←— label —→|``).
+            side: ``"top"`` (above the lanes, default) or ``"bottom"``.
+            color: Stroke colour (default ``"#333333"``).
+            width: Stroke width (default: the theme edge width; 1.2 px classic).
+            font_size: Label size (default ``0.85 × font_size``).
+            weight: Label weight.
+            label_color: Label colour (default: ``color``).
+        """
+        s = TimeSpan(start, end, label, style=style, side=side, color=color or "#333333",
+                     width=width, font_size=font_size or self._fs() * 0.85, weight=weight,
+                     label_color=label_color, theme=self._theme)
+        self.spans.append(s)
+        self._adopt(s)
+        return s
+
+    def elide(self, lane: str, start: float, end: float, label: str = "…", **kw: Any) -> Task:
+        """v0.12.0: elide ``start``..``end`` on ``lane`` — no bar, just a centred
+        ``"…"`` (or ``label``) where the schedule continues off-page, e.g. the long
+        middle of a migration. Returns the (borderless, unfilled) :class:`Task`.
+
+        Named ``elide`` (not ``gap``) because ``gap`` means spacing everywhere else.
+
+        Example: ``tl.elide("GPU0", 4, 6)``.
+        """
+        if end <= start:
+            raise ValueError("elide end must be after start")
+        kw.setdefault("fill", "none")
+        kw.setdefault("stroke", "none")
+        kw.setdefault("text_color", "#444444")
+        kw["kind"] = "gap"
+        return self.task(lane, start, end - start, label, **kw)
+
+    def event(self, t: float, label: str = "", *, color: Optional[str] = None,
+              font_size: Optional[float] = None) -> Event:
+        """v0.12.0: point event at time ``t`` — a small ▲ on the time axis (below
+        its tick labels; under the lanes when there is no axis) with ``label`` under
+        it. Labels of nearby events stack on levels instead of colliding.
+
+        Example: ``tl.event(3, "migration triggered")``.
+        """
+        e = Event(t, label, color=color or "#333333",
+                  font_size=font_size or self._fs() * 0.85, theme=self._theme)
+        self.events.append(e)
+        self._adopt(e)
+        return e
+
+    def time_anchor(self, t: float, side: str = "bottom") -> Port:
+        """v0.12.0: a port at time ``t`` on the lane area's ``side`` (``"top"`` /
+        ``"bottom"``) — the end point for a :class:`~codefig.edges.Guide` that links
+        the same instant on two Timelines, e.g.
+        ``Guide(tl1.time_anchor(3), tl2.time_anchor(3, "top"))``.
+        Same as :meth:`port_at` with a bottom default.
+        """
+        return self.port_at(t, side)
+
+    def lane(self, name: str) -> LaneBand:
+        """The background band node of lane ``name`` (for ports / Dim / constraints)."""
+        self._lane_check(name)
+        return self._bands[name]
+
+    def at(self, t: float) -> Anchor:
+        """x anchor at time ``t`` (for constraints, ``Dim`` and ``port(align=...)``)."""
+        return Anchor(self._plot, "x", getter=lambda: self.body.x_of(t), label=f"t={t:g}")
+
+    def port_at(self, t: float, side: str = "top") -> Port:
+        """Port on the top / bottom edge of the lane area at time ``t``."""
+        if side not in ("top", "bottom"):
+            raise ValueError("port_at side must be top|bottom")
+        return self._plot.port(side, align=self.at(t))
+
+
+# =========================================================================== Lanes
+class Lane(Node):
+    """One swimlane of a :class:`Lanes` container: a header and its content.
+
+    Role **background** (content nodes sit on it; edges may cross it). The header is a
+    **soft** Text child.
+
+    Args:
+        title: Header text (rich text allowed).
+        content: The node in the lane (use a Row / Col / Diagram for several).
+        fill: Lane background (default: the container's alternating ``lane_fill``).
+        header_fill: Header cell colour (default: the container's ``header_fill``).
+
+    Example:
+        >>> from codefig import Lane, Box
+        >>> lane = Lane("Client", Box("send request"))
+    """
+
+    def __init__(self, title: str, content: Optional[Node] = None, *,
+                 fill: Optional[str] = None, header_fill: Optional[str] = None,
+                 **kw: Any) -> None:
+        kw.setdefault("obstacle", "background")
+        super().__init__(**kw)
+        self.title = title
+        self.content = content
+        self.fill = fill
+        self.header_fill = header_fill
+        self.header: Optional[Text] = None
+        if content is not None:
+            content.parent = self
+        self._hdr_box = BoxGeom()
+
+    def children(self) -> Sequence[Node]:
+        out: List[Node] = []
+        if self.header is not None:
+            out.append(self.header)
+        if self.content is not None:
+            out.append(self.content)
+        return out
+
+    def _measure(self) -> Tuple[float, float]:
+        return self.content.measure() if self.content is not None else (0.0, 0.0)
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        if self.content is not None:
+            self.content.draw(buf, ox, oy)
+
+
+class Lanes(Node):
+    """Swimlane container: lanes with headers, stacked (``"horizontal"`` lanes, header
+    on the left) or side by side (``"vertical"`` lanes, header on top).
+
+    Role **background** (as is each :class:`Lane`); lane contents are ordinary nodes
+    and keep their own roles. Lanes share one extent (all horizontal lanes are equally
+    wide; vertical lanes equally tall). Wrap the container in a
+    :class:`~codefig.edges.Diagram` to draw edges between nodes in different lanes.
+
+    Args:
+        lanes: :class:`Lane` objects or ``(title, node)`` tuples.
+        direction: ``"horizontal"`` (default) or ``"vertical"``.
+        header_size: Header thickness in pt (default: fits the titles; horizontal
+            headers are rotated −90° when that is narrower, see ``header_rotate``).
+        header_rotate: ``True`` / ``False`` / ``None`` (default: rotate horizontal-lane
+            titles when any is wider than 1.6 × the lane height would allow).
+        lane_fill: Lane background colour or list cycled over lanes
+            (default ``("#f5f7fa", "#ffffff")``).
+        header_fill: Header cell colour (default ``"#e6ebf1"``).
+        stroke: Lane border colour (default ``"#8a96a3"``).
+        stroke_width: Border width in pt (default 1.0).
+        pad: Padding around each lane's content in pt (default 12).
+        align: Content placement along the lane: ``"start"`` (default), ``"center"``
+            or ``"end"``.
+        font_size: Header size (default ``theme.font_size``).
+        weight: Header weight (default ``"bold"``).
+        min_extent: Minimum lane length in pt along the lane direction (default 0).
+
+    Example:
+        >>> from codefig import Figure, Lanes, Lane, Box, Diagram, Edge
+        >>> a, b = Box("submit"), Box("schedule")
+        >>> lanes = Lanes([Lane("User", a), ("Scheduler", b)])
+        >>> d = Diagram(lanes, [Edge(a, b)])
+        >>> fig = Figure(size="auto", cols=1)
+        >>> _ = fig.panel("a").set(d)
+        >>> svg = fig.to_svg()
+    """
+
+    stroke_width = themed(1.0, "SW")
+    pad = themed(12.0)
+
+
+    def __init__(self, lanes: Sequence[Union[Lane, Tuple[str, Node]]], *,
+                 direction: str = "horizontal", header_size: Optional[float] = None,
+                 header_rotate: Optional[bool] = None,
+                 lane_fill: Union[str, Sequence[str], None] = ("#f5f7fa", "#ffffff"),
+                 header_fill: str = "#e6ebf1", stroke: str = "#8a96a3",
+                 stroke_width: Optional[float] = None, pad: Optional[float] = None,
+                 align: str = "start",
+                 font_size: Optional[float] = None, weight: str = "bold",
+                 min_extent: float = 0.0, **kw: Any) -> None:
+        if direction not in ("horizontal", "vertical"):
+            raise ValueError("Lanes direction must be horizontal|vertical")
+        if align not in ("start", "center", "end"):
+            raise ValueError("Lanes align must be start|center|end")
+        kw.setdefault("obstacle", "background")
+        super().__init__(**kw)
+        self.lanes: List[Lane] = [l if isinstance(l, Lane) else Lane(l[0], l[1], theme=self._theme)
+                                  for l in lanes]
+        if not self.lanes:
+            raise ValueError("Lanes needs at least one lane")
+        self.direction = direction
+        self.header_size = header_size
+        self.header_rotate = header_rotate
+        if lane_fill is None or isinstance(lane_fill, str):
+            fills = [lane_fill] * len(self.lanes)
+        else:
+            lf = list(lane_fill)
+            fills = [lf[i % len(lf)] for i in range(len(self.lanes))]
+        self.stroke, self.stroke_width = stroke, stroke_width
+        self.pad, self.align, self.min_extent = pad, align, float(min_extent)
+        self.weight = weight
+        fs = font_size
+        self.font_size = fs
+        for l, f in zip(self.lanes, fills):
+            l.parent = self
+            if l.fill is None:
+                l.fill = f
+            if l.header_fill is None:
+                l.header_fill = header_fill
+            l.header = Text(l.title, font_size=fs, weight=weight, theme=self._theme)
+            l.header.parent = l
+        self._rot = False
+        self._hs = 0.0
+
+    def children(self) -> Sequence[Node]:
+        return self.lanes
+
+    def invalidate(self) -> None:
+        super().invalidate()
+        for l in self.lanes:
+            l.invalidate()
+            if l.header is not None:
+                l.header.invalidate()
+
+    def _sizes(self) -> Tuple[List[Tuple[float, float]], float, float, bool]:
+        cs = [l.measure() for l in self.lanes]
+        hs = [l.header.measure() for l in self.lanes]  # type: ignore[union-attr]
+        p = self.pad
+        if self.direction == "horizontal":
+            lane_hs = [ch + 2 * p for _cw, ch in cs]
+            rot = self.header_rotate
+            if rot is None:
+                rot = any(hw > 1.6 * max(lh, 1.0) for (hw, _hh), lh in zip(hs, lane_hs)) or False
+                rot = bool(rot) and max(hw for hw, _ in hs) > 60
+            if rot:
+                for l in self.lanes:
+                    l.header.rotate = -90.0  # type: ignore[union-attr]
+                    l.header.invalidate()  # type: ignore[union-attr]
+                hs = [l.header.measure() for l in self.lanes]  # type: ignore[union-attr]
+            size = self.header_size if self.header_size is not None else (
+                max(hw for hw, _ in hs) + 14.0)
+            return cs, size, 0.0, bool(rot)
+        size = self.header_size if self.header_size is not None else (
+            max(hh for _, hh in hs) + 10.0)
+        return cs, size, 0.0, False
+
+    def _measure(self) -> Tuple[float, float]:
+        cs, hsz, _x, rot = self._sizes()
+        self._rot, self._hs = rot, hsz
+        p = self.pad
+        if self.direction == "horizontal":
+            ext = max([cw for cw, _ in cs] + [self.min_extent - 2 * p]) + 2 * p
+            hs = [l.header.measure()[1] for l in self.lanes]  # type: ignore[union-attr]
+            heights = [max(ch + 2 * p, hh + 10.0) for (_cw, ch), hh in zip(cs, hs)]
+            self._lens = heights
+            return (hsz + ext, sum(heights))
+        ext = max([ch for _, ch in cs] + [self.min_extent - 2 * p]) + 2 * p
+        ws = [l.header.measure()[0] for l in self.lanes]  # type: ignore[union-attr]
+        widths = [max(cw + 2 * p, hw + 16.0) for (cw, _ch), hw in zip(cs, ws)]
+        self._lens = widths
+        return (sum(widths), hsz + ext)
+
+    def _layout_children(self) -> None:
+        g = self.geom
+        self.measure()
+        p, hs = self.pad, self._hs
+        pos = g.x if self.direction == "vertical" else g.y
+        for l, ln in zip(self.lanes, self._lens):
+            cw, ch = l.content.measure() if l.content is not None else (0.0, 0.0)
+            hdr = l.header
+            assert hdr is not None
+            hw, hh = hdr.measure()
+            if self.direction == "horizontal":
+                l.layout(g.x, pos, g.w, ln)
+                l._hdr_box = BoxGeom(g.x, pos, hs, ln)
+                hdr.layout(g.x + (hs - hw) / 2, pos + (ln - hh) / 2, hw, hh)
+                body_x, body_w = g.x + hs + p, g.w - hs - 2 * p
+                fx = {"start": 0.0, "center": 0.5, "end": 1.0}[self.align]
+                if l.content is not None:
+                    l.content.layout(body_x + (body_w - cw) * fx, pos + (ln - ch) / 2, cw, ch)
+            else:
+                l.layout(pos, g.y, ln, g.h)
+                l._hdr_box = BoxGeom(pos, g.y, ln, hs)
+                hdr.layout(pos + (ln - hw) / 2, g.y + (hs - hh) / 2, hw, hh)
+                body_y, body_h = g.y + hs + p, g.h - hs - 2 * p
+                fy = {"start": 0.0, "center": 0.5, "end": 1.0}[self.align]
+                if l.content is not None:
+                    l.content.layout(pos + (ln - cw) / 2, body_y + (body_h - ch) * fy, cw, ch)
+            pos += ln
+
+    def draw(self, buf: List[str], ox: float = 0.0, oy: float = 0.0) -> None:
+        from .render_svg import draw_rect
+
+        sw = self.stroke_width
+        for l in self.lanes:
+            lg, hg = l.geom, l._hdr_box
+            if l.fill:
+                draw_rect(buf, lg.x + ox, lg.y + oy, lg.w, lg.h, fill=l.fill, stroke="none",
+                          stroke_width=0)
+            draw_rect(buf, hg.x + ox, hg.y + oy, hg.w, hg.h, fill=l.header_fill or "none",
+                      stroke="none", stroke_width=0)
+            draw_rect(buf, lg.x + ox, lg.y + oy, lg.w, lg.h, fill="none", stroke=self.stroke,
+                      stroke_width=sw)
+            l.header.draw(buf, ox, oy)  # type: ignore[union-attr]
+            l.draw(buf, ox, oy)
+
+
+__all__ = ["Timeline", "Task", "TimeSpan", "Marker", "LaneBand", "Lanes", "Lane",
+           "TimelineWarning", "SPAN_STYLES", "MARKER_STYLES", "TASK_KINDS"]