MeshTerm/meshterm/ui/pathgraph.py

"""THE route-graph widget: hop sequences drawn as a left-to-right flow of paths.

Extracted from the Message paths dialog so every screen that draws walked (or planned)
routes draws them the same way. A *layer* is one path — its relay hops, an edge colour,
and a draw priority — and the widget lays every distinct path out between a shared left
and right endpoint marker.

Every path shares its two endpoints (an origin on the left, us on the right) and is walked
left to right, so the picture is a *flow*: routes that **diverge** out of the origin, run
their own course, and **converge** back into us, sharing a relay wherever their walks agree.
Earlier drawings tried a vertical *bus* the lanes tapped at right angles (a metro map you
wander around, the bare 90° turns hiding that A flows to B), then oblique branches straight
off each marker (which left every off-lane relay a pointed *peak* or *valley*). The widget
now draws the fan as a **multilane highway**: a node sits level in its lane, and a route changes
lane only *between* nodes, easing across on a single gentle shift the way a car drifts one lane
over and then settles. Concretely:

* **lanes** — the highest-*priority* path (the spine, e.g. the best-evidence route) holds the
  flow's centre, its relays in a straight run, and the alternatives fan above and below it a
  fixed pitch of text rows apart. Priority fixes the geometry; a separate *emphasis* rank picks
  which route is drawn highlighted (on top, winning any shared cell) without moving a marker, so
  a caller can light a different route without the picture reflowing. Rather than give every
  route a full-width lane of its own —
  which stacks the band as tall as the route count even where the routes barely overlap — the
  lanes are *packed by column*: the spine keeps its own relays, and each other node slides to the
  innermost free row above or below the spine *in its own column*, so a column with one off-spine
  node claims a single flanking row however many routes cross the graph, and only a column where
  routes genuinely stack pays the deeper rows. Which flank an alternative takes is then *balanced*
  so column-sharing routes split above and below rather than piling one flank two deep while the
  other sits empty (the band is only as tall as its deepest flank plus the other's): a five-route
  fan through at most two nodes per column draws three lanes deep — spine plus one flank each side
  — not five. The two endpoints sit at the vertical centre of the packed band, so the spine runs
  through them — dead straight when the flanks come out even and the lanes are odd, leaning gently
  to the centre otherwise (and where the lanes are even, one extra padding row is opened between
  the two central lanes so the endpoints land on an exact centred row between them);
* **columns** (x) place each node by *balanced* rank — its distance from the origin over its
  distance-plus-remaining-distance to us — so a path's relays spread evenly between the two
  ends however long the other paths are, and a shared relay lands in one place;
* **level seating** — every node is entered and left on a *level tangent*, so a relay that sits
  off its neighbours' lane reads as a gentle rise-and-settle, never a pointed peak or valley.
  Between two nodes on different lanes the shift leaves the first level, drifts across, and
  arrives level into the second — the only bends are the soft level→curve→level eases, never a
  bare right angle in open canvas. The curve spans the whole gap rather than a centred stretch
  flanked by flat platforms: a platform-to-curve corner draws a heavy braille *knee*, so the
  stroke runs continuously node to node and stays an even, thin arc (see :data:`_CURVE_SPAN`);
* **shared relays** draw as a single marker (a route re-using a hop is not a new node): the
  marker sits on its highest-priority path's lane, and a lower path that also rides it leans
  off its lane to meet the marker and back — which reads as the alternative *branching
  through the shared node*, exactly the story the evidence tells;
* **diverge / converge** — the fan at each end is flow, not a switchboard: routes leave the
  origin overlapping on the centre line and peel off one by one to their lanes (the
  divergence), and mirror that back into us on the right (the convergence). Every edge draws
  exactly once, however many routes share it; the one edge drawn as a bare vertical is a pair
  of nodes walked in *both* directions — a genuine two-way hop, the sole place a straight
  up-and-down line tells the truth;
* **labels** sit straight above or below their marker — pushed to the side away from the
  graph's middle, a spot clear of the drawn lines preferred — and endpoints slide their
  label inward from the canvas edge so a long name still lands by its marker. A caller that
  wants a node unlabelled returns ``None`` for it.

Everything renders onto a :class:`~meshterm.ui.mapcanvas.MapCanvas`; the caller supplies
the per-node glyph/label/colour callbacks, so the widget stays free of contact-list and
theme concerns.
"""

from __future__ import annotations

from dataclasses import dataclass
from itertools import permutations, product
from math import ceil
from typing import Callable, Optional, Sequence

from .mapcanvas import RGB, MapCanvas, parse_hex

#: Sentinel node ids for the graph's endpoints (NUL never collides with hex hops).
#: Callers key their glyph/label callbacks on these for the two ends of every path.
SRC_NODE = "\x00src"
DST_NODE = "\x00dst"

#: Text rows between adjacent lane markers — the pitch one lane maps to. At the default there
#: are two blank rows padding each gap (room for a lane's label and its neighbour's), and an
#: *even* lane count opens one extra row between the two central lanes so the endpoints land on
#: an exact centred row (see the vertical-sizing block). A graph with more lanes than fit the
#: row budget scales the pitch down to fit, and a graph with few lanes never stretches *past* it
#: (spreading the lanes apart would only reintroduce the empty space the layout exists to
#: avoid), so a sparse graph draws compact rather than splayed.
_LANE_PITCH_ROWS = 3

#: Dots reserved beyond the outermost lane at each end of the graph — a label row for that
#: lane's markers, plus a little air.
_GRAPH_END_DOTS = 8

#: The dot row within a character cell a horizontal edge line is aimed at — the upper-middle
#: of the cell's 2×4 pixel grid (rows 0..3 top-down), where a one-dot line reads as running
#: through the glyph rather than hugging its bottom edge. Every lane's y is snapped onto this
#: row (see :func:`_mid_row`) so a level run stays level and same-column markers align.
_CELL_MID_DOT = 2

#: Dot-space margin the endpoint markers keep from the canvas edges.
_GRAPH_PAD_DOTS = 6

#: The share of a lane change's horizontal column gap spent on the eased curve itself — the rest
#: would split into two flat platforms flanking it. Set to the whole gap: the curve runs
#: continuously from one node to the next with *no* separate flat segment. A shorter curve leaves
#: flat platforms but reintroduces a **corner** where a platform (slope 0) meets the climbing
#: curve, and that corner piles a heavy braille *knee* (a cell filled 3–4 dots) that reads thick —
#: the more so the shallower the curve's end tangent. Spanning the whole gap removes the corner,
#: so the stroke stays an even, thin arc end to end; the nodes still seat level because the curve's
#: end tangents are kept horizontal (see :data:`_BEND_K`), giving each marker a flat point to sit on
#: without a platform run. (In a very tight column a full-lane shift is unavoidably steep right up to
#: the node, so its marker sits on a gentle slope rather than dead level — the honest cost of keeping
#: the stroke thin there.)
_CURVE_SPAN = 1.0

#: The shortest horizontal run a lane change is given even for a one-lane hop, so a tight
#: column gap still bends across a few dots rather than snapping over in one abrupt step.
_MIN_SHIFT_DOTS = 4

#: How far (as a fraction of the shift's horizontal span) the bezier control points sit in from
#: each end — both placed level with their own end, so the curve leaves and enters each node
#: horizontally. This flat end tangent is what seats a node level now that the curve spans the
#: whole gap (:data:`_CURVE_SPAN`) with no separate platform. It trades against thinness: a higher
#: value holds the tangent flatter for longer (a better-seated node) but steepens the curve's
#: middle to compensate (a thicker centre), while a lower value spreads the drop more evenly
#: (thinner) but tilts the node's tangent (a marker on a slope). Tuned to the balance that keeps
#: the marker's seating close to level while the stroke stays an even, thin arc between nodes.
_BEND_K = 0.4

#: Dots left of our marker the flow arrow sits — one cell, so it embeds in the trunk as ``▶★``
#: and marks the node → us direction without crowding the endpoint.
_ARROW_GAP_DOTS = 2

#: Most distinct paths the lane order is optimised over by exhaustive search. Beyond it the
#: search space (``(n-1)!`` orders of the non-central lanes) is too large, so a barycentre
#: heuristic seats the lanes instead. The widget's real inputs sit far under this.
_MAX_EXACT_LANES = 8

#: Sweeps of the barycentre lane-ordering heuristic used past :data:`_MAX_EXACT_LANES`.
_ORDER_SWEEPS = 8

#: Most non-best routes the side-balancer weighs by exhaustive 2-colouring (see
#: :func:`_balance_sides`). Past it the ``2**m`` side assignments grow too many, so the routes
#: keep the side the jog order handed them. The widget's real inputs sit far under this.
_MAX_BALANCE_ROUTES = 16

#: The glyph used for the flow arrow embedded in the trunk just before us,
#: so the whole flow reads better as a directed run node → us (not a map you wander).
#_ARROW_GLYPH = "▶"
_ARROW_GLYPH = ""

#: How far a layer's emphasis outranks its layout priority when edges compete for a cell.
#: Emphasis is the draw-time highlight — the selected path drawn on top and winning any shared
#: cell — and must beat any spread of priority values, so it is scaled well past the small
#: priorities the widget ever sees. Layout geometry ignores emphasis entirely; only the colour
#: and z-order of the drawn edges follow it (see :func:`_draw_rank`), so re-emphasising a
#: different path repaints the same picture in new colours rather than relaying it.
_EMPHASIS_BOOST = 1_000_000


#: A node's graph marker: the glyph and its ``#rrggbb`` colour (the shared node-glyph
#: tuples from :mod:`~meshterm.ui.map_render` / :mod:`~meshterm.ui.widgets` fit as-is).
GlyphOf = Callable[[str], tuple[str, str]]

#: A node's graph label, or ``None``/``""`` to leave the marker bare.
LabelOf = Callable[[str], Optional[str]]

#: The colour a node's label is drawn in (usually the node's name hue).
LabelRgbOf = Callable[[str], RGB]


@dataclass(frozen=True)
class PathLayer:
    """One path drawn on the route graph.

    Attributes:
        hops: The relay node ids between the endpoints, in walk order (empty = the
            path runs endpoint to endpoint straight across).
        color: The edge colour the path draws in.
        priority: **Layout** rank — which path is the spine. The highest-priority path takes
            the straight centre lane and owns any relay it shares (weaker paths jog to meet it),
            so it fixes every node's column and lane. Geometry depends on this alone, never on
            :attr:`emphasis`: a caller that wants the drawn picture to hold still while it
            re-highlights keeps each path's priority constant.
        emphasis: **Draw** rank — the highlight, layered over the fixed geometry. Where edges
            share a cell (or cross), the higher-emphasis path wins the colour and draws on top;
            it moves no marker. Defaults to ``0`` (all paths equal, so the colour falls to
            :attr:`priority` as before). A caller that highlights by selection varies *this*,
            not priority, so the layout stays put and only the colours change.
    """

    hops: tuple[str, ...]
    color: RGB
    priority: int
    emphasis: int = 0


def _mid_row(y_dot: float) -> int:
    """Snap a dot row onto the upper-middle dot of its character cell.

    A braille cell is four dot rows tall; a horizontal line drawn on the top or bottom row
    hugs the glyph's edge and reads as sitting too high or too low. Snapping every lane's y
    to :data:`_CELL_MID_DOT` keeps markers — and the level runs along a lane — centred in the
    cell's pixel space.
    """
    return round((y_dot - _CELL_MID_DOT) / 4) * 4 + _CELL_MID_DOT


def _collapse(layers: Sequence[PathLayer]) -> list[PathLayer]:
    """Fold layers with identical hop sequences onto one drawn path.

    Re-walking a known route highlights it rather than doubling it. Geometry keeps the
    strongest ``priority`` of the folded copies (so a shared route seats where its best
    instance would), while the highlight — the drawn colour and its on-top order — follows the
    most-*emphasised* copy, and the emphasis carries across. So two routes that only differ in
    a cluster-internal order the caller has contracted away land on one line, and selecting
    either lights it, even when a higher-priority copy owns the layout.
    """
    drawn: list[PathLayer] = []
    by_hops: dict[tuple[str, ...], int] = {}
    for layer in layers:
        at = by_hops.get(layer.hops)
        if at is None:
            by_hops[layer.hops] = len(drawn)
            drawn.append(layer)
        else:
            cur = drawn[at]
            top = layer if _draw_rank(layer) > _draw_rank(cur) else cur
            drawn[at] = PathLayer(
                cur.hops,
                top.color,
                max(layer.priority, cur.priority),
                max(layer.emphasis, cur.emphasis),
            )
    return drawn


_HEX_DIGITS = frozenset("0123456789abcdef")


def _coalesce_prefixes(layers: Sequence[PathLayer]) -> list[PathLayer]:
    """Fold an under-specified hop into the longer id it can only be, across the layers.

    A relay reaches the graph at different hash widths across the paths — a 1-byte trace
    hop (``be``) beside the same node's wider id (``be1d1c1dbc4b``). Drawn as-is they double
    the node: two markers a column apart, often carrying the same resolved name. The
    observed-topology graph coalesces what it can, but only where a hash is unambiguous
    against the *whole* contact list; a hash that opens two contacts (``be`` also begins
    ``bedd2b``) survives to here, even though among *these* paths it can only be the one wide
    node present. So the widget closes the gap locally: using only the ids the layers hold,
    a short id is rewritten to the longer id it strictly prefixes when exactly one such id is
    present (following a chain to its longest end); a short id that prefixes two distinct
    present nodes is genuinely ambiguous and left as itself. The per-node callbacks then see
    one id per node, and any paths made identical by the rewrite collapse together downstream.
    """
    ids = {hop for layer in layers for hop in layer.hops}
    remap: dict[str, str] = {}
    remaining = set(ids)
    while True:
        pair = _prefix_merge(remaining)
        if pair is None:
            break
        short, long = pair
        remap[short] = long
        remaining.discard(short)
    if not remap:
        return list(layers)

    def resolved(hop: str) -> str:
        for _ in range(len(remap) + 1):  # follow a rewrite chain, guarded against cycles
            if hop not in remap:
                break
            hop = remap[hop]
        return hop

    return [
        PathLayer(
            tuple(resolved(hop) for hop in layer.hops),
            layer.color, layer.priority, layer.emphasis,
        )
        for layer in layers
    ]


def _prefix_merge(nodes: set[str]) -> Optional[tuple[str, str]]:
    """The next ``(short, long)`` id pair to fold among ``nodes``, or ``None`` when none.

    A short hex id (under a full 6-byte width) folds when the longer present ids that
    extend it all lie on one prefix chain — the longest starts with every other — so it can
    only name that one node. Shortest ids are offered first, collapsing a chain from its end.
    """
    for short in sorted(nodes, key=len):
        if len(short) >= 12 or not _is_hex(short):
            continue
        exts = [
            other
            for other in nodes
            if other != short and len(other) > len(short)
            and _is_hex(other) and other.startswith(short)
        ]
        if not exts:
            continue
        longest = max(exts, key=len)
        if all(longest.startswith(ext) for ext in exts):
            return short, longest
    return None


def _is_hex(value: str) -> bool:
    """Whether every character of ``value`` is a hex digit (endpoint sentinels are not)."""
    return bool(value) and all(char in _HEX_DIGITS for char in value)


def _draw_rank(layer: PathLayer) -> int:
    """A layer's edge draw rank: emphasis dominates, layout priority breaks ties.

    Governs only which colour wins a shared cell and which edge draws on top — never node
    placement (that is :attr:`PathLayer.priority` alone). So a caller can re-emphasise a
    different path (bump its :attr:`~PathLayer.emphasis`) and the graph repaints in new colours
    over the very same layout, rather than reflowing because the spine changed.
    """
    return layer.priority + layer.emphasis * _EMPHASIS_BOOST


def render_path_graph(
    layers: Sequence[PathLayer],
    width: int,
    *,
    glyph_of: GlyphOf,
    label_of: LabelOf,
    label_rgb_of: LabelRgbOf,
    min_rows: int = 5,
    max_rows: int = 15,
    lane_pitch: int = _LANE_PITCH_ROWS,
) -> list[str]:
    """Draw the diverge/converge route-flow graph and return its ANSI lines.

    Args:
        layers: The paths to draw. The highest ``priority`` takes the straight centre lane and
            fixes the geometry; a separate ``emphasis`` (default ``0``) decides which path is
            drawn highlighted — on top, winning any shared cell — without moving a marker, so
            re-emphasising a path repaints the same layout in new colours. Layers with identical
            hop sequences collapse to one drawn path owned by the highest priority among them.
        width: Canvas width in character cells.
        glyph_of: Marker glyph + colour per node id (endpoints keyed by
            :data:`SRC_NODE` / :data:`DST_NODE`).
        label_of: Label text per node id (``None``/``""`` = bare marker). A label is
            kept whole unless it is wider than the canvas, when it is ellipsized to fit.
        label_rgb_of: Label colour per node id.
        min_rows: The fewest canvas rows to draw, however few the lanes.
        max_rows: The most canvas rows to spend; a graph with more lanes than fit
            compresses its lane spacing rather than growing past this.
        lane_pitch: Text rows between adjacent lane markers (so ``lane_pitch - 1`` blank rows
            pad each gap). An even lane count opens one extra row between the two central lanes
            so the endpoints land on an exact centred row. The row budget compresses the pitch
            when there are many lanes, and never stretches it when there are few. Defaults to
            :data:`_LANE_PITCH_ROWS`.

    Returns:
        One ANSI string per canvas row (empty when there are no layers to draw).
    """
    if not layers:
        return []

    drawn = _collapse(_coalesce_prefixes(layers))
    seqs = [(SRC_NODE, *layer.hops, DST_NODE) for layer in drawn]

    # First-appearance order for every node, so the layout is identical on every repaint: a
    # set of hash-seeded string ids would iterate in a run-varying order and let the passes
    # settle differently each time, making the graph jump between frames.
    ordered_nodes: list[str] = []
    seen: set[str] = set()
    edges: set[tuple[str, str]] = set()
    for seq in seqs:
        for node in seq:
            if node not in seen:
                seen.add(node)
                ordered_nodes.append(node)
        edges.update(zip(seq, seq[1:]))

    xfrac = _balanced_x(ordered_nodes, edges)

    # A node draws on its highest-priority owning path — the first (by priority, then
    # appearance) to carry it — so a shared relay sits once, on the strongest route through it,
    # and weaker routes jog to meet it. A path that introduces no node of its own (every hop
    # already owned by a stronger route) is *subsumed*: it earns no lane and simply threads the
    # markers others placed, so it costs no empty band.
    best = max(range(len(drawn)), key=lambda j: drawn[j].priority)
    owner: dict[str, int] = {}
    for i in sorted(range(len(drawn)), key=lambda j: -drawn[j].priority):
        for node in seqs[i]:
            owner.setdefault(node, i)
    # A path that is only a detour off a sibling (that sibling's route with an extra relay
    # inserted) is subsumed too: its relay is re-owned onto the sibling's lane so it costs no
    # band and needs no crossing to rejoin the shared node. See :func:`_fold_detours`.
    _fold_detours(drawn, seqs, owner, xfrac, width)
    lane_of_path = _assign_lanes(drawn, seqs, owner, best)

    # Compress the per-path lanes onto the fewest rows the picture actually needs. A lane per
    # path stacks the whole graph as tall as it has routes, even where the routes barely overlap
    # — five routes through at most two nodes per column drew five lanes deep. So each off-spine
    # node is slid to the innermost free lane *in its own column*, and the alternatives' flanks
    # are balanced above/below so no flank stacks deep while the other sits empty: a column
    # holding one off-spine node needs one off-spine row however many paths cross the graph, and
    # only a column where several routes genuinely stack pays for the extra rows.
    span = width * 2 - 2 * _GRAPH_PAD_DOTS

    def col_of(node: str) -> int:
        return (_GRAPH_PAD_DOTS + round(xfrac[node] * span)) >> 1

    signed = _compress_lanes(ordered_nodes, lane_of_path, owner, best, col_of)

    # The endpoints sit at the vertical centre of the compressed lane band, where the strongest
    # route runs through them as the graph's spine; the alternatives fan above and below. When the
    # flanks balance out evenly the spine's own lane *is* that centre and it runs dead straight;
    # when the band is lopsided (or even-numbered) the centre falls between lanes, and the best
    # path eases gently to reach the endpoints rather than seating the whole graph off-centre —
    # a lean the balancer keeps small by flattening the flanks first.
    low = min(signed.values(), default=0)
    high = max(signed.values(), default=0)
    max_lane = high - low
    centre_lane = max_lane / 2.0
    node_lane: dict[str, float] = {
        node: (centre_lane if node in (SRC_NODE, DST_NODE) else float(signed[node] - low))
        for node in ordered_nodes
    }

    # -- Vertical sizing. Each lane sits on its own text row, ``lane_pitch`` rows apart (so
    # ``lane_pitch - 1`` blank rows pad each gap). On an *even* lane count the two central lanes
    # are opened one extra row apart, so the endpoints — pinned to the band's centre — land on
    # the exact middle row between them rather than on a fractional row that would snap off it;
    # an *odd* count already seats a central lane there for them to ride. A graph too tall for
    # ``max_rows`` scales every row down proportionally (never up), so it stays compact.
    even_lanes = max_lane % 2 == 1  # N = max_lane + 1 lanes; even ⟺ max_lane odd
    lower_centre = max_lane // 2 + 1  # first lane below the centre (only meaningful when even)

    def slot(lane: float) -> float:
        """The text row (pre-scaling) a lane index maps to, with the even-count centre gap."""
        rows_out = lane * lane_pitch
        if even_lanes and lane > lower_centre - 1:
            # the lower-central lane and everything below it are pushed one row down; the
            # endpoints' half-lane takes half of it, landing them on the widened gap's middle.
            rows_out += min(1.0, lane - (lower_centre - 1))
        return rows_out

    if max_lane <= 0:
        rows = min_rows
        lane_rows = 0.0
        scale = 0.0
    else:
        lane_rows = slot(float(max_lane))  # total lane span, in rows
        ideal = lane_rows * 4 + 2 * _GRAPH_END_DOTS
        rows = max(min_rows, min(max_rows, ceil(ideal / 4)))
        avail = rows * 4 - 2 * _GRAPH_END_DOTS
        scale = min(1.0, avail / (lane_rows * 4)) if lane_rows else 0.0

    canvas = MapCanvas(width, rows)
    band = lane_rows * 4 * scale
    # Centre the band, anchored on a cell-mid row so the (unscaled) integer lane rows land dead
    # on their cells — no per-lane snap drift that would nudge a centred endpoint off its middle.
    top = float(_mid_row((rows * 4 - band) / 2))

    def x_of(node: str) -> int:
        return _GRAPH_PAD_DOTS + round(xfrac[node] * span)

    pos: dict[str, tuple[int, int]] = {
        node: (x_of(node), _mid_row(top + slot(node_lane[node]) * 4 * scale))
        for node in ordered_nodes
    }
    # -- Edges. Collect every edge once, keyed by its unordered node pair: an edge two routes
    # share — or a pair walked in *both* directions — must draw a single time, else it silts up
    # as a doubled line a dot off itself (two routes' Bresenham runs never land on the exact
    # same dots). Each pair keeps the colour and draw rank of the strongest route through it —
    # by draw rank, so the *emphasised* (highlighted) route wins a shared edge over a merely
    # higher-priority spine, and the highlight paints the whole selected route rather than
    # dropping out where it overlaps another. A two-way pair is flagged so it draws as the one
    # honest vertical rather than a lane change.
    bidir = {frozenset((u, v)) for (u, v) in edges if (v, u) in edges}
    edge_style: dict[frozenset[str], tuple[int, RGB]] = {}
    for layer, seq in sorted(zip(drawn, seqs), key=lambda ls: _draw_rank(ls[0])):
        rank = _draw_rank(layer)
        for u, v in zip(seq, seq[1:]):
            key = frozenset((u, v))
            prev = edge_style.get(key)
            if prev is None or rank > prev[0]:
                edge_style[key] = (rank, layer.color)
    # Draw ascending by draw rank so the strongest/most-emphasised route's colour wins any cell
    # two edges share and sits on top.
    for key, (rank, color) in sorted(edge_style.items(), key=lambda kv: kv[1][0]):
        u, v = tuple(key)
        canvas.draw_line(_route(u, v, pos, key in bidir), color, rank)

    # -- An arrow embedded in the trunk just before us, so the whole flow reads as a directed
    # run node → us (not a map you wander). A single glyph in the spine's own colour: it reserves
    # its cell, so the endpoint label routes around it rather than colliding with stray dots.
    ax, ay = pos[DST_NODE]
    canvas.marker(ax - _ARROW_GAP_DOTS, ay, _ARROW_GLYPH, drawn[best].color)

    # -- Markers for every node (endpoints and relays alike each draw once).
    for node in ordered_nodes:
        glyph, color_hex = glyph_of(node)
        canvas.marker(*pos[node], glyph, parse_hex(color_hex))

    _place_labels(canvas, ordered_nodes, pos, node_lane, width, rows * 2, label_of, label_rgb_of)
    return canvas.to_ansi_lines()


def _route(
    u: str,
    v: str,
    pos: dict[str, tuple[int, int]],
    bidir: bool,
) -> list[tuple[float, float]]:
    """The point chain for one edge (dot coordinates), drawn as multilane-highway flow.

    Two nodes on the same lane join with a level run; two on different lanes join with one smooth
    **shift** — a bezier S that leaves the first marker level, drifts across the intervening lanes,
    and settles level into the second (see :func:`_sbend`), so there is no corner anywhere, only
    the eased level→curve→level of the shift. The shift spans the whole column gap
    (:data:`_CURVE_SPAN`) rather than a centred stretch flanked by flat platforms: a platform would
    meet the climbing curve at a corner, and that corner draws a heavy braille *knee*, so the curve
    runs continuously node to node instead and the marker seats on the curve's own level end tangent.
    The endpoints, sitting at the centre of the lane band, make the origin's diverging peels and
    us's converging merges fall out of this one rule — no endpoint special case. The lone exception
    is ``bidir``: a pair walked both ways draws as a single straight segment between the markers (a
    near-vertical when the layout stacks them), the one place an up-and-down line is the honest
    picture.
    """
    (xu, yu), (xv, yv) = pos[u], pos[v]
    if bidir:
        return [(xu, yu), (xv, yv)]
    if xu > xv:  # orient the trapezium left→right; balanced rank only ties, never inverts
        (xu, yu), (xv, yv) = (xv, yv), (xu, yu)
    if yu == yv:
        return [(xu, yu), (xv, yv)]
    dx = xv - xu
    shift = min(dx, max(_MIN_SHIFT_DOTS, round(dx * _CURVE_SPAN)))
    stub = (dx - shift) // 2
    # A bezier S across the whole gap (level tangents at both ends, so it eases out of and back
    # into each marker with no corner — and no platform corner to pile a heavy knee).
    return [(xu, yu), *_sbend(xu + stub, yu, xv - stub, yv), (xv, yv)]


def _sbend(
    x0: float, y0: float, x1: float, y1: float
) -> list[tuple[float, float]]:
    """Sample a cubic-bezier S-curve from ``(x0, y0)`` to ``(x1, y1)``, level at both ends.

    Both control points sit level with their own endpoint (:data:`_BEND_K` of the span in from
    each side), so the curve's tangent is horizontal where it meets the platforms — the smooth
    lane change that drifts across and settles rather than cutting a hard diagonal. Sampled
    densely enough that the polyline rasterizes as a continuous curve; the convex hull keeps it
    inside the ``(x0, y0)–(x1, y1)`` box, so it never overshoots its lane or column.
    """
    cx0 = x0 + _BEND_K * (x1 - x0)
    cx1 = x1 - _BEND_K * (x1 - x0)
    samples = max(4, int(abs(x1 - x0) + abs(y1 - y0)))
    pts: list[tuple[float, float]] = []
    for i in range(samples + 1):
        t = i / samples
        mt = 1.0 - t
        a, b, c, d = mt * mt * mt, 3 * mt * mt * t, 3 * mt * t * t, t * t * t
        pts.append((a * x0 + b * cx0 + c * cx1 + d * x1, a * y0 + b * y0 + c * y1 + d * y1))
    return pts


def _balanced_x(ordered_nodes: list[str], edges: set[tuple[str, str]]) -> dict[str, float]:
    """Each node's horizontal position in ``0..1`` — balanced rank from origin toward us.

    A node's fraction is its longest-path distance from the origin over that distance plus
    its longest remaining distance to us: the origin lands at ``0``, us at ``1``, and every
    other node between them in proportion to how far along its route it sits. So a path's
    relays spread *evenly* between the two ends however many hops the other paths take — a
    lone relay on a one-hop route lands mid-canvas rather than jammed against the origin with
    a long edge arcing across to us — and a relay shared by routes of different lengths still
    resolves to one x. Because every edge steps the from-origin distance up and the
    to-us distance down, the fraction rises strictly along each path: edges only ever run
    left to right.

    A pair walked in *both* directions is a 2-cycle in the edge set, and the longest-path
    relaxation would loop through it, inflating every downstream depth toward the node-count
    cap and jamming other relays hard against the ends. So the rank runs over the graph with
    each such pair (transitively) merged to one representative — the acyclic flow the picture
    really is; the pair, drawn as a single vertical, rightly shares an x anyway.
    """
    rep = _merge_bidir_pairs(ordered_nodes, edges)
    reps: list[str] = []
    seen: set[str] = set()
    for node in ordered_nodes:
        if rep[node] not in seen:
            seen.add(rep[node])
            reps.append(rep[node])
    rep_edges = {(rep[u], rep[v]) for u, v in edges if rep[u] != rep[v]}
    up = _longest_paths(reps, rep_edges)
    down = _longest_paths(reps, {(v, u) for u, v in rep_edges})
    frac = {
        r: (up[r] / (up[r] + down[r])) if (up[r] + down[r]) else 0.0 for r in reps
    }
    return {node: frac[rep[node]] for node in ordered_nodes}


def _merge_bidir_pairs(
    ordered_nodes: list[str], edges: set[tuple[str, str]]
) -> dict[str, str]:
    """Map each node to a representative, uniting any two joined by a both-ways edge.

    Two nodes walked in both directions form a 2-cycle; uniting them — transitively, so a
    chain of such pairs folds into one group — lets the balanced rank treat the flow as the
    acyclic run it otherwise is. A node in no such pair maps to itself. The choice of which
    member is the representative doesn't matter: every member is assigned the group's one
    fraction, and the group's rank is structural.
    """
    parent = {node: node for node in ordered_nodes}

    def find(node: str) -> str:
        root = node
        while parent[root] != root:
            root = parent[root]
        while parent[node] != root:  # path-compress
            parent[node], node = root, parent[node]
        return root

    for u, v in edges:
        if (v, u) in edges:
            ru, rv = find(u), find(v)
            if ru != rv:
                parent[ru] = rv
    return {node: find(node) for node in ordered_nodes}


def bidir_clusters(sequences: Sequence[tuple[str, ...]]) -> list[tuple[str, ...]]:
    """The groups of three or more nodes that form a bidirectional cluster (a flow SCC).

    Two nodes walked in both directions are a 2-cycle the graph draws as one tidy vertical
    pair — fine on its own. Three or more mutually linked that way are a strongly-connected
    knot the left-to-right flow cannot order: :func:`_merge_bidir_pairs` collapses them all
    onto one column, where their markers and labels pile up illegibly. A caller can pass its
    path sequences (endpoints included) here to find those knots and contract each to a single
    super-node *before* drawing, so the cluster reads as one marker rather than a jam — the one
    honest way to seat a cycle in a DAG layout.

    Returns each cluster's member ids in first-appearance order (endpoints excluded); a lone
    node or the tidy two-node pair is not a cluster and is not returned.
    """
    edges = {pair for seq in sequences for pair in zip(seq, seq[1:])}
    ordered = list(dict.fromkeys(node for seq in sequences for node in seq))
    rep = _merge_bidir_pairs(ordered, edges)
    groups: dict[str, list[str]] = {}
    for node in ordered:
        if node in (SRC_NODE, DST_NODE):
            continue
        groups.setdefault(rep[node], []).append(node)
    return [tuple(members) for members in groups.values() if len(members) >= 3]


def _longest_paths(ordered_nodes: list[str], edges: set[tuple[str, str]]) -> dict[str, int]:
    """Longest-path depth of each node over ``edges`` (relaxed to a fixed point).

    Capped at the node count so a pathological cycle in the id set can't spin it forever;
    the graphs are acyclic fans, so it settles in a couple of passes.
    """
    depth = {node: 0 for node in ordered_nodes}
    for _ in range(len(ordered_nodes)):
        changed = False
        for u, v in edges:
            if depth[v] < depth[u] + 1:
                depth[v] = depth[u] + 1
                changed = True
        if not changed:
            break
    return depth


def _fold_detours(
    drawn: Sequence[PathLayer],
    seqs: Sequence[tuple[str, ...]],
    owner: dict[str, int],
    xfrac: dict[str, float],
    width: int,
) -> None:
    """Re-own a *detour* path's extra relays onto the sibling lane it converges into.

    A route heard as another route *plus* an inserted relay or two — same convergence into us,
    one extra hop on the way — shouldn't cost a whole extra lane. Given its own lane it would
    sit on the far side of the best-centred spine from the sibling it rejoins, dragging its
    inserted relay clear across the graph to meet the shared node (an avoidable crossing).

    So when a bearing path's relays, minus the ones it alone owns, exactly match a
    higher-or-equal-priority sibling's relays — and that sibling truly owns them (is their
    lane) — the path is that sibling with a detour. Its owned relays are re-owned to the
    sibling, riding its lane as waypoints the branch dips through, provided none shares a cell
    column with a node *already on that lane* — including a detour folded there earlier, so two
    siblings that insert a relay at the same column don't overprint (the second keeps its own
    lane). The detour path then owns nothing, earns no lane, and reads as a branch *off* its
    sibling instead of a track that crosses the graph to reach it. Mutates ``owner`` in place.
    """
    span = width * 2 - 2 * _GRAPH_PAD_DOTS

    def col(node: str) -> int:
        return (_GRAPH_PAD_DOTS + round(xfrac[node] * span)) >> 1

    relays = [
        frozenset(n for n in seq if n not in (SRC_NODE, DST_NODE)) for seq in seqs
    ]
    # Weakest first, so a marginal detour folds onto its stronger sibling, never the reverse.
    for i in sorted(range(len(drawn)), key=lambda j: drawn[j].priority):
        own_i = {n for n in seqs[i] if owner[n] == i}
        residual = relays[i] - own_i
        if not own_i or not residual:
            continue
        for q in range(len(drawn)):
            if q == i or drawn[q].priority < drawn[i].priority or relays[q] != residual:
                continue
            if not all(owner[n] == q for n in relays[q]):  # q must own (be the lane of) them
                continue
            # Columns already committed on q's lane (its own relays plus any earlier fold).
            q_cols = {
                col(n) for n, o in owner.items() if o == q and n not in (SRC_NODE, DST_NODE)
            }
            new_cols = {col(n) for n in own_i}
            if len(new_cols) == len(own_i) and q_cols.isdisjoint(new_cols):
                for n in own_i:
                    owner[n] = q
            break


def _assign_lanes(
    drawn: Sequence[PathLayer],
    seqs: Sequence[tuple[str, ...]],
    owner: dict[str, int],
    best: int,
) -> dict[int, int]:
    """Seat each lane-bearing path on a horizontal lane, best centred, sharing routes close.

    Returns ``{path_index: lane}`` — only for the paths that own at least one node (a subsumed
    path threads others' markers and needs no lane of its own) — with lanes ``0`` (top) up. The
    best path is pinned to the centre lane, where it runs straight through the two endpoints as
    the graph's spine; the rest are ordered to minimise the total *jog* — the vertical distance
    a path travels to reach a relay another path owns — so routes that share hops sit near each
    other and a shared relay costs the shortest detour. Small graphs
    (``≤`` :data:`_MAX_EXACT_LANES` lanes) get the exact best order by search; larger ones fall
    back to a barycentre heuristic.
    """
    bearing = [i for i in range(len(drawn)) if any(owner[node] == i for node in seqs[i])]
    n = len(bearing)
    if n == 1:
        return {bearing[0]: 0}

    # Each bearing path's jog partners: the owning lanes of the hops it borrows from others.
    shared_owners = {
        i: [owner[node] for node in seqs[i] if owner[node] != i] for i in bearing
    }

    def jog(lane: dict[int, int]) -> int:
        return sum(abs(lane[i] - lane[o]) for i in bearing for o in shared_owners[i])

    centre_slot = (n - 1) // 2
    others = [i for i in bearing if i != best]

    if n - 1 <= _MAX_EXACT_LANES:
        best_order: Optional[tuple[int, ...]] = None
        best_cost: Optional[int] = None
        for perm in permutations(others):
            slots = list(perm)
            slots.insert(centre_slot, best)
            cost = jog({p: k for k, p in enumerate(slots)})
            if best_cost is None or cost < best_cost:
                best_cost, best_order = cost, tuple(slots)
        assert best_order is not None
        return {p: k for k, p in enumerate(best_order)}

    return _barycentre_lanes(bearing, best, centre_slot, shared_owners)


def _barycentre_lanes(
    bearing: list[int],
    best: int,
    centre_slot: int,
    shared_owners: dict[int, list[int]],
) -> dict[int, int]:
    """Heuristic lane order for a graph too large to search: barycentre sweeps.

    Each path is repeatedly re-seated at the average lane of the paths it shares relays with,
    with the best path pinned to the centre lane. A handful of sweeps settles sharing routes
    next to each other — the cheap crossing-minimiser, at the coarser grain of whole lanes.
    """
    lane = {p: float(k) for k, p in enumerate(bearing)}
    lane[best] = float(centre_slot)
    others = [i for i in bearing if i != best]
    for _ in range(_ORDER_SWEEPS):
        for i in others:
            if shared_owners[i]:
                lane[i] = sum(lane[o] for o in shared_owners[i]) / len(shared_owners[i])
        order = sorted(others, key=lambda i: lane[i])
        order.insert(centre_slot, best)
        lane = {p: float(k) for k, p in enumerate(order)}
    return {p: int(lane[p]) for p in order}


def _compress_lanes(
    ordered_nodes: list[str],
    lane_of_path: dict[int, int],
    owner: dict[str, int],
    best: int,
    col_of: Callable[[str], int],
) -> dict[str, int]:
    """Squeeze the per-path lanes onto the fewest rows, one node at a time within each column.

    :func:`_assign_lanes` seats each path on a lane of its own, so the band is as tall as the
    graph has routes — even where the routes only ever run one or two abreast. But a lane is a
    whole-width row: two routes need distinct rows only in the *columns* where they both carry a
    node, and endpoint-to-endpoint every route already shares the origin and us. So this pass
    keeps the best path's relays on the spine (offset ``0``) and slides every other node to the
    innermost free lane *above or below* it *in its own column*: a column with one node above
    the spine uses the first row above however many routes fan past it, and only a column where
    several routes truly stack claims the deeper rows.

    Which **side** each alternative takes is not inherited from its jog-order lane — that seats
    routes sharing a relay *adjacent*, which piles column-sharing routes onto the *same* flank
    and leaves the band as tall as one flank's deepest stack plus the other's, even when no
    single column holds more than two nodes. Instead :func:`_balance_sides` 2-colours the
    alternatives to flatten the deeper flank (the spine may lean off dead-centre to reach the
    band's middle, which is fine), so a five-route fan through at most two nodes per column draws
    three lanes — spine plus one flank each side — not five. The best path's relays still hold
    the straight spine; the returned lanes are signed offsets from it (``<0`` above, ``>0``
    below), which the caller shifts to a ``0``-based band.

    Returns ``{node: signed_lane}`` for every relay (endpoints are placed on the band centre by
    the caller, not here). A node a column holds alone off the spine always lands on ``±1``, so
    a sparse multi-route graph collapses to the three-lane spine-and-two-flanks it really is.
    """
    best_lane = lane_of_path[best]
    relays = [node for node in ordered_nodes if node not in (SRC_NODE, DST_NODE)]
    spine = {node for node in relays if owner[node] == best}
    off_spine = [node for node in relays if node not in spine]
    # The non-best bearing routes, in the jog-order _assign_lanes settled (each route keyed by
    # its signed lane relative to best), so ties fall to the arrangement that already reads clean.
    routes = sorted(
        {owner[node] for node in off_spine},
        key=lambda r: (lane_of_path[r] - best_lane, r),
    )
    cols_of_route = {
        r: {col_of(node) for node in off_spine if owner[node] == r} for r in routes
    }
    orig_side = {r: (1 if lane_of_path[r] - best_lane > 0 else -1) for r in routes}
    side = _balance_sides(routes, cols_of_route, orig_side)

    rank = {r: i for i, r in enumerate(routes)}  # nearest-to-spine order within a flank
    columns: dict[int, list[str]] = {}
    for node in off_spine:
        columns.setdefault(col_of(node), []).append(node)

    signed: dict[str, int] = {node: 0 for node in spine}
    for members in columns.values():
        above = sorted((n for n in members if side[owner[n]] < 0), key=lambda n: rank[owner[n]])
        below = sorted((n for n in members if side[owner[n]] > 0), key=lambda n: rank[owner[n]])
        for depth, node in enumerate(above, start=1):
            signed[node] = -depth
        for depth, node in enumerate(below, start=1):
            signed[node] = depth
    return signed


def _balance_sides(
    routes: list[int],
    cols_of_route: dict[int, set[int]],
    orig_side: dict[int, int],
) -> dict[int, int]:
    """Choose a flank (``-1`` above / ``+1`` below the spine) for each alternative route.

    The band a :func:`_compress_lanes` pack draws is ``(deepest stack above) + (deepest stack
    below) + 1``: two alternatives need distinct rows only where they share a column, so a flank
    is only as deep as its most-crowded column. The jog order that seats sharing routes adjacent
    puts them on the *same* flank, which can stack one flank two deep while the other sits empty
    — a needlessly tall band. So the routes are 2-coloured, exhaustively while they are few
    (:data:`_MAX_BALANCE_ROUTES`; past it the jog-order sides stand):

    * never above the **ceiling** the jog order itself draws — balancing may flatten a band, never
      grow one. A column that genuinely stacks three nodes forces one flank two deep whatever the
      colouring, and filling the other flank to match it (prettier, but taller) is refused;
    * under that ceiling, **flatten the deeper flank**, so a fan piled two deep on one side while
      the other is empty splits across both and the band shrinks;
    * then even the two flanks, then keep the jog-order side. So a graph the jog order already
      draws flat is left exactly as it is — its lower-band one-sided alternative has the *same*
      deepest flank, so the balance tie-break holds it airy rather than lopsiding it a row shorter
      — while a graph with a needlessly deep flank is the one that actually moves.

    Returns ``{route_index: side}``.
    """
    if not routes:
        return {}
    if len(routes) > _MAX_BALANCE_ROUTES:
        return dict(orig_side)

    def flanks(assign: dict[int, int]) -> tuple[int, int]:
        above: dict[int, int] = {}
        below: dict[int, int] = {}
        for r in routes:
            stack = above if assign[r] < 0 else below
            for col in cols_of_route[r]:
                stack[col] = stack.get(col, 0) + 1
        return max(above.values(), default=0), max(below.values(), default=0)

    orig_above, orig_below = flanks(orig_side)
    ceiling = orig_above + orig_below  # the jog order's band height − 1; never draw taller

    best_assign: Optional[dict[int, int]] = None
    best_key: Optional[tuple[int, int, int]] = None
    for combo in product((-1, 1), repeat=len(routes)):
        assign = dict(zip(routes, combo))
        deep_above, deep_below = flanks(assign)
        if deep_above + deep_below > ceiling:  # taller than the jog order would draw — reject
            continue
        agree = sum(1 for r in routes if assign[r] == orig_side[r])
        key = (max(deep_above, deep_below), abs(deep_above - deep_below), -agree)
        if best_key is None or key < best_key:
            best_key, best_assign = key, assign
    assert best_assign is not None  # orig_side always meets its own ceiling
    return best_assign


def _place_labels(
    canvas: MapCanvas,
    ordered_nodes: list[str],
    pos: dict[str, tuple[int, int]],
    node_lane: dict[str, float],
    width: int,
    mid_y: int,
    label_of: LabelOf,
    label_rgb_of: LabelRgbOf,
) -> None:
    """Write each node's label above or below its marker, clear of the lines if it can.

    Endpoints first, then relays down the lanes, so the named ends win any contest for a
    cell. Each label is tried on the side away from the graph's middle first (spreading the
    text outward off the busy centre), preferring a row the drawn lines don't already occupy.
    Any node hard against a canvas edge — an endpoint by construction, or a relay a balanced
    rank pins near the origin or us — slides its centre anchor inward far enough for the whole
    name to land, since a centred label overhanging the edge places nothing and would leave the
    marker silently unlabelled. When both stacked rows are blocked the label falls back to
    sitting beside its marker. A name is only ever shortened when it is wider than the entire
    canvas.
    """
    endpoints = [n for n in (DST_NODE, SRC_NODE) if n in pos]
    relays = sorted(
        (n for n in ordered_nodes if n not in (SRC_NODE, DST_NODE)),
        key=lambda n: (node_lane[n], pos[n][0]),
    )
    for node in [*endpoints, *relays]:
        label = label_of(node)
        if not label:
            continue
        if len(label) > width:
            label = label[: max(1, width - 1)] + "…"
        rgb = label_rgb_of(node)
        x, y = pos[node]
        # Clamp the centre cell so the whole label fits between the canvas edges: a marker near
        # an edge would otherwise centre its name off-canvas, place nothing, and be dropped. A
        # marker with room to spare keeps its true centre (the clamp is a no-op there).
        half = len(label) // 2
        cx = min(max(x >> 1, half), max(half, width - (len(label) - half)))
        anchor_x = cx * 2
        rows_out = (y - 4, y + 4) if y <= mid_y else (y + 4, y - 4)
        if any(
            canvas.place_label(anchor_x, sy, label, rgb, bold=True, avoid_dots=True)
            for sy in rows_out
        ):
            continue
        if any(
            canvas.place_label(anchor_x, sy, label, rgb, bold=True) for sy in rows_out
        ):
            continue
        # Both rows blocked: sit the label beside the marker (clear of the drawn lines if it
        # can, else over them) rather than drop it.
        if not canvas.marker_label(x, y, label, rgb, avoid_dots=True):
            canvas.marker_label(x, y, label, rgb)