termrender 4.6.0__tar.gz → 4.6.2__tar.gz

{termrender-4.6.0 → termrender-4.6.2}/CHANGELOG.md

@@ -1,6 +1,70 @@
 # CHANGELOG
 
 
+## v4.6.2 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid-flow**: Preserve edge labels, render self-loops, sanitize degraded echo
+  ([`263100f`](https://github.com/crouton-labs/termrender/commit/263100f16e1a7f0044497f2dedd0fd10f0831626))
+
+- Router now draws all edge polylines+arrowheads first, then all edge labels last (reserving each
+  label's cells, plus a margin), so a later edge's line can never silently erase an earlier edge's
+  label and two labels sharing a lane render with visible separation instead of concatenating. -
+  Rank-band gaps widen to fit an adjacent-rank edge's label in full (_rank_gap_overrides), fixing
+  short LR/forward-adjacent labeled edges (e.g. "hello") that were previously clipped to a couple of
+  characters. - Raw-echo degradation now strips any box-drawing/geometric glyph (\u2500-\u259f,
+  \u25a0-\u25ff) present in the malformed source itself, so a degraded echo can never be misdetected
+  as a successful render. - Hardened green-theatre tests: self-loop tests now assert real loop
+  geometry (arrowhead + glyphs past the box border) instead of "non-empty output"; the
+  edge-visibility test now inspects the guaranteed-clear inter-box gap instead of accepting
+  box-border glyphs; cycle/labeled-back-edge/direction/never-raises tests gained genuine
+  topology/degradation assertions in place of crash-only checks. - Updated the two corpus goldens
+  (pipe-label, inline-label) whose rendered height changed under the new label-aware gap widening.
+
+
+## v4.6.1 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid-flow**: Parse chained edges and bracket-aware tokenization
+  ([`5040b96`](https://github.com/crouton-labs/termrender/commit/5040b967bbe75c70c6d03d57930742ba020e3333))
+
+- Unify edge parsing behind one bracket-depth-aware connector scanner (_scan_connectors) shared with
+  & fan-out splitting and ; statement splitting, replacing the single-connector _EDGE_RE. -
+  CRITICAL: chained edge statements (A-->B-->C) now parse as a sequence of node groups separated by
+  connectors, emitting one edge per adjacent triple instead of dropping the tail after the first
+  connector. - MAJOR: connector-looking text inside [], (), {} labels (A[Go --> Fast]) is no longer
+  mistaken for an edge connector. - MINOR: semicolons inside labels (A[Check; validate]) no longer
+  split the statement.
+
+Adds structural tests for 2/3-link chains, mixed-style chains, chain with inline label,
+  connector-in-label for all three connector families, and semicolon-in-label. Adds a chained-form
+  golden for the labeled back-edge cycle proving identical render to the separate-line form.
+
+### Testing
+
+- Add flowchart golden corpus and go-binary parity harness
+  ([`2a5a00a`](https://github.com/crouton-labs/termrender/commit/2a5a00aba18195eac987bc8c202a80724d6e43c9))
+
+- tests/test_mermaid_flow_corpus.py: 26 golden-output tests pinning exact render_flowchart() lines
+  across all 9 node shapes, every edge style (solid/dotted/thick/headless/bidirectional), both label
+  forms, & fan-out, a multi-parent DAG, a labeled-back-edge cycle (the case the vendored Go binary
+  panics/mis-parses on), LR vs TD, subgraph + nested subgraph, a long label vs a tight width budget,
+  and the two degradation paths. - scripts/mermaid_flow_parity.py: standalone parity harness (not a
+  pytest dependency) that invokes the vendored Go binary the way termrender's real dispatch path
+  does (preprocess_mermaid_for_ascii + fix_mermaid_encoding) and the native renderer side by side
+  across 14 representative inputs, writing the comparison to the orchestrator's shared context dir.
+  Confirms parity-or-better plus two Go failure modes the native renderer avoids: a self-loop panic
+  (index out of range) and labeled-back-edge mis-parsing (label text swallowed into a phantom node
+  instead of a back-edge). - fix: mermaid_flow.py's module docstring described a stale prior phase
+  ("every shape renders as a plain rectangle", "subgraphs parse but aren't drawn as frames") — both
+  are false now; corrected to describe actual current behavior (distinct shape borders, framed
+  subgraphs with contiguous-membership flattening).
+
+463 tests green (437 pre-existing + 26 new corpus).
+
+
 ## v4.6.0 (2026-07-06)
 
 ### Features

{termrender-4.6.0 → termrender-4.6.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.6.0
+Version: 4.6.2
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender

termrender-4.6.2/scripts/mermaid_flow_parity.py

@@ -0,0 +1,168 @@
+#!/usr/bin/env python3
+"""Standalone parity harness: native flowchart renderer vs. the vendored Go
+binary, for a curated set of representative mermaid flowchart sources.
+
+Not a pytest test and not imported by the test suite — the corpus tests must
+not depend on the vendored ``mermaid-ascii`` binary being present on disk.
+Run this once (locally, wherever the vendored binary for the host platform
+exists) to (re)generate the side-by-side comparison artifact:
+
+    .venv/bin/python scripts/mermaid_flow_parity.py
+
+Invokes the Go binary exactly the way termrender's real dispatch path does
+(``mermaid.py::_render_via_binary``): run ``preprocess_mermaid_for_ascii``
+(flowchart shape normalization) on the source, shell out to
+``mermaid_ascii_bin()`` with ``-f - -y 1``, and undo its Latin-1
+double-encoding via ``fix_mermaid_encoding`` — so the comparison is fair
+(same preprocessing termrender actually applies before falling back to the
+binary today).
+"""
+
+from __future__ import annotations
+
+import subprocess
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parent.parent / "src"))
+
+from termrender._mermaid_bin import mermaid_ascii_bin
+from termrender.renderers.mermaid import fix_mermaid_encoding, preprocess_mermaid_for_ascii
+from termrender.renderers.mermaid_flow import render_flowchart
+
+OUTPUT_PATH = Path(
+    "/Users/silasrhyneer/.crouter/canvas/nodes/mr9swads-0f62d05c/context/flow-parity-sample.md"
+)
+
+WIDTH = 60
+
+CASES: list[tuple[str, str]] = [
+    (
+        "Simple forward DAG",
+        "graph TD\nA-->B\nA-->C\n",
+    ),
+    (
+        "Multi-parent DAG",
+        "graph TD\nA-->C\nB-->C\n",
+    ),
+    (
+        "Headless edge (`---`)",
+        "graph TD\nA---B\n",
+    ),
+    (
+        "Pipe-labeled edge",
+        "graph TD\nA-->|hi|B\n",
+    ),
+    (
+        "Inline-labeled edge",
+        "graph TD\nA -- go now --> B\n",
+    ),
+    (
+        "`&` fan-out",
+        "graph TD\nA & B --> C & D\n",
+    ),
+    (
+        "Non-rect shapes (diamond, circle, cylinder)",
+        "graph TD\nA{Decision}-->B((Circle))\nB-->C[(DB)]\n",
+    ),
+    (
+        "LR direction",
+        "graph LR\nA-->B\nA-->C\n",
+    ),
+    (
+        "Subgraph frame",
+        "graph TD\nsubgraph zone[Zone]\nA-->B\nend\n",
+    ),
+    (
+        "Plain 3-cycle (no label)",
+        "graph TD\nA-->B\nB-->C\nC-->A\n",
+    ),
+    (
+        "Self-loop (Go binary PANICS: index out of range in drawLine)",
+        "graph TD\nA-->A\n",
+    ),
+    (
+        "Cycle with a LABELED back-edge (Go binary mis-parses the label as "
+        "a phantom node — wrong topology; this is the case the requirements "
+        "doc calls out as the one the Go binary cannot handle)",
+        "graph TD\nA-->B\nB-->C\nC-->|retry|A\n",
+    ),
+    (
+        "Same labeled-back-edge cycle, spaced arrows (Go binary still "
+        "fabricates a phantom 4th node '|retry| A' instead of a back-edge "
+        "into A — the label-parsing bug is not a whitespace quirk)",
+        "graph TD\nA --> B\nB --> C\nC --> |retry| A\n",
+    ),
+    (
+        "Simple forward DAG, spaced arrows (Go binary's own preferred "
+        "form — included so the unspaced cases above are judged fairly "
+        "against Go's best case, not just its worst case)",
+        "graph TD\nA --> B\nA --> C\n",
+    ),
+]
+
+
+def render_via_go_binary(source: str) -> tuple[str, bool]:
+    """Return (rendered_text, panicked). Mirrors mermaid.py::_render_via_binary
+    but surfaces panic/failure explicitly instead of silently echoing source
+    (the harness wants to *show* the failure, not hide it)."""
+    try:
+        result = subprocess.run(
+            [mermaid_ascii_bin(), "-f", "-", "-y", "1"],
+            input=preprocess_mermaid_for_ascii(source),
+            capture_output=True,
+            text=True,
+            timeout=30,
+        )
+    except (FileNotFoundError, subprocess.TimeoutExpired, OSError) as exc:
+        return f"[harness error invoking binary: {exc}]", True
+
+    if result.returncode != 0:
+        stderr_tail = "\n".join(result.stderr.strip().splitlines()[:4])
+        return f"PANIC (exit {result.returncode}):\n{stderr_tail}", True
+
+    return fix_mermaid_encoding(result.stdout), False
+
+
+def main() -> None:
+    sections: list[str] = [
+        "# Native flowchart renderer vs. Go `mermaid-ascii` — parity sample",
+        "",
+        "Generated by `scripts/mermaid_flow_parity.py`. The Go binary is",
+        "invoked exactly the way termrender's real dispatch path does today",
+        "(`mermaid.py::_render_via_binary`): flowchart shape normalization via",
+        "`preprocess_mermaid_for_ascii`, then `mermaid-ascii -f - -y 1`, then",
+        "`fix_mermaid_encoding` on the output.",
+        "",
+    ]
+
+    for title, source in CASES:
+        go_text, panicked = render_via_go_binary(source)
+        our_lines = render_flowchart(source, WIDTH)
+        our_text = "\n".join(our_lines)
+
+        sections.append(f"## {title}")
+        sections.append("")
+        sections.append("Mermaid source:")
+        sections.append("```")
+        sections.append(source.rstrip("\n"))
+        sections.append("```")
+        sections.append("")
+        sections.append(f"Go binary output{' (PANIC/failure)' if panicked else ''}:")
+        sections.append("```")
+        sections.append(go_text if go_text.strip() else "(empty)")
+        sections.append("```")
+        sections.append("")
+        sections.append("Native `render_flowchart` output:")
+        sections.append("```")
+        sections.append(our_text if our_text.strip() else "(empty)")
+        sections.append("```")
+        sections.append("")
+
+    OUTPUT_PATH.parent.mkdir(parents=True, exist_ok=True)
+    OUTPUT_PATH.write_text("\n".join(sections) + "\n")
+    print(f"wrote {OUTPUT_PATH}")
+
+
+if __name__ == "__main__":
+    main()

{termrender-4.6.0 → termrender-4.6.2}/src/termrender/renderers/mermaid_flow.py

@@ -25,19 +25,25 @@ Grammar supported
 Header: ``graph``/``flowchart`` + direction (``TD``/``TB``/``LR``/``RL``/
 ``BT``). Node shapes: ``[rect]``, ``(round)``, ``([stadium])``,
 ``[(cylinder)]``, ``((circle))``, ``{diamond}``, ``{{hexagon}}``,
-``[[subroutine]]``, ``[/parallelogram/]`` — this phase renders every shape
-as a plain rectangle (distinct shape borders are a later phase; only the
-label text is load-bearing here). Edges: ``-->``, ``---``, ``-.->``, ``==>``
-(and bidirectional forms), with ``|label|`` and inline ``A -- text --> B``
-labels, and ``&`` fan-out. ``subgraph ... end`` blocks parse but are not yet
-rendered as frames (nodes inside them still place and render normally).
-``class``/``classDef``/``style``/``click``/``linkStyle`` lines are ignored.
+``[[subroutine]]``, ``[/parallelogram/]`` — each renders with a distinct
+shape-specific border (diamond/parallelogram slant tapers, round/stadium/
+circle rounded corners, a cylinder's rounded cap over a square base, a
+hexagon's cut corners, a subroutine's double-bar sides); only a shape whose
+box is too small for its own drawer falls back to the plain rectangle
+border. Edges: ``-->``, ``---``, ``-.->``, ``==>`` (and bidirectional
+forms), with ``|label|`` and inline ``A -- text --> B`` labels, and ``&``
+fan-out. ``subgraph ... end`` blocks (including nested subgraphs) render as
+enclosing frames with a left-anchored title when their members place
+contiguously enough for a clean rect; otherwise a block flattens (no frame,
+members still placed and drawn) rather than draw a frame that would
+visually claim a non-member node. ``class``/``classDef``/``style``/
+``click``/``linkStyle`` lines are ignored.
 
 Known degradations (by design, not bugs)
 -----------------------------------------
-- Node shapes other than a plain rectangle border are not yet visually
-  distinct (Phase 4 of this renderer's build).
-- Subgraph blocks parse but are not yet drawn as enclosing frames (Phase 4).
+- A subgraph whose members aren't placed contiguously enough for a clean
+  enclosing rect flattens (drops its frame and title) rather than draw a
+  frame that visually claims a non-member node.
 - See ``mermaid_flow_layout.py``'s module docstring for the edge-routing
   degradations (dense-graph crossings, label-lane overlap, CJK wrapping,
   minimum-box-size self-loop cosmetics).
@@ -48,11 +54,21 @@ Known degradations (by design, not bugs)
 
 from __future__ import annotations
 
+import re
+
 from termrender.renderers.mermaid_flow_layout import layout_flowgraph
 from termrender.renderers.mermaid_flow_parser import FlowchartError, parse
 
 __all__ = ["render_flowchart"]
 
+# Same ranges the downstream attach viewer uses to detect render *success*
+# (see the module docstring's "Degradation contract"). The raw-echo path
+# must never contain one of these, even when the malformed/degenerate
+# source itself happens to contain a literal box-drawing or geometric
+# glyph (e.g. hand-typed "\u250c" in otherwise-non-flowchart text) — otherwise a
+# failed render could be misdetected as a successful one.
+_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
+
 
 def render_flowchart(source: str, width: int) -> list[str]:
     """Render a mermaid ``graph``/``flowchart`` source to unicode lines.
@@ -107,4 +123,12 @@ def render_flowchart(source: str, width: int) -> list[str]:
 
 
 def _raw_echo(source: str) -> list[str]:
-    return [line.rstrip() for line in source.splitlines()]
+    """Plain echo of ``source``'s lines, with any box-drawing/geometric
+    glyph (the same ``\\u2500-\\u259f``/``\\u25a0-\\u25ff`` ranges the
+    downstream viewer checks for) replaced by ``?`` — the degradation
+    contract requires NO such glyph survive, even one present verbatim in
+    malformed/degenerate source, not just glyphs this renderer would have
+    drawn itself."""
+    return [
+        _GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()
+    ]

{termrender-4.6.0 → termrender-4.6.2}/src/termrender/renderers/mermaid_flow_layout.py

@@ -721,6 +721,38 @@ def _box_dims(label: str, shape: NodeShape = NodeShape.RECT) -> tuple[int, int]:
 _GAP_X = 3          # minimum border-to-border gap between boxes in one rank/band
 _ROW_GAP = 2         # minimum gap between rank bands
 _COMPONENT_GUTTER = 4  # gap between independently-laid-out components
+_LABEL_GAP_PAD = 1   # cells of breathing room either side of a label's own text
+                     # when it forces a rank-band gap wider than _ROW_GAP.
+
+
+def _rank_gap_overrides(
+    edges: list[FlowEdge], rank_of: dict[str, int]
+) -> dict[int, int]:
+    """Minimum inter-rank-band gap keyed by the *lower* rank of each
+    adjacent-rank transition, widened past ``_ROW_GAP`` wherever a labeled
+    edge directly connects that transition's two ranks. A forward edge
+    between adjacent ranks routes as a single straight run (or a Z path
+    that still crosses the same inter-rank band) whose only clear space is
+    this gap — at the base ``_ROW_GAP`` a label wider than a couple of
+    cells has nowhere to go but onto the boxes it connects, which is
+    exactly the short LR/adjacent-rank clipped-label bug this closes.
+    Non-adjacent-rank edges (back-edges, multi-rank spans) don't constrain
+    the gap here — they route through their own side lane, not this band.
+    """
+    overrides: dict[int, int] = {}
+    for e in edges:
+        if e.src == e.dst or not e.label:
+            continue
+        r_src = rank_of.get(e.src)
+        r_dst = rank_of.get(e.dst)
+        if r_src is None or r_dst is None:
+            continue
+        lo_r, hi_r = (r_src, r_dst) if r_src <= r_dst else (r_dst, r_src)
+        if hi_r - lo_r != 1:
+            continue
+        needed = visual_len(e.label) + 2 * _LABEL_GAP_PAD
+        overrides[lo_r] = max(overrides.get(lo_r, _ROW_GAP), needed)
+    return overrides
 
 
 def _native_extents(
@@ -780,12 +812,15 @@ def _place_nodes(
         for v in comp_vertices:
             ranks[sug.grx[v].rank].append(v)
 
+        rank_of = {v.data: sug.grx[v].rank for v in comp_vertices}
+        gap_overrides = _rank_gap_overrides(edges, rank_of)
+
         band_top_for_rank: dict[int, int] = {}
         cursor = 0
         for r in sorted(ranks):
             band_top_for_rank[r] = cursor
             max_h = max(native[v.data][1] for v in ranks[r])
-            cursor += max_h + _ROW_GAP
+            cursor += max_h + gap_overrides.get(r, _ROW_GAP)
 
         min_x = min(v.view.xy[0] for v in comp_vertices)
         provisional = {v: round(v.view.xy[0] - min_x) for v in comp_vertices}
@@ -1214,6 +1249,17 @@ def _label_positions(length: int, center: int, lo: int, hi: int) -> list[int]:
     return order
 
 
+def _reserve_label_margin(canvas: Canvas, x: int, y: int) -> None:
+    """Mark one cell just past a label's edge as reserved, without
+    altering whatever character (if any) already occupies it — a one-cell
+    buffer so a second label placed on an adjacent/overlapping segment
+    (e.g. two back-edge labels sharing a row) lands with visible separation
+    instead of butting directly up against the first label's text."""
+    if x < 0 or y < 0:
+        return
+    canvas.set_char(x, y, canvas.get_char(x, y), reserve=True)
+
+
 def _draw_label_on_segment(
     canvas: Canvas, a: tuple[int, int], b: tuple[int, int], label: str
 ) -> None:
@@ -1226,7 +1272,12 @@ def _draw_label_on_segment(
     self-loop label placement. Shifts along the search axis to the nearest
     span/row fully clear of a reserved (box) cell; if none exists, writes
     at the ideal placement anyway (overflow tolerated) but skips individual
-    reserved cells — a label never corrupts a box.
+    reserved cells — a label never corrupts a box. Every written label cell
+    is itself marked reserved (see :func:`layout_flowgraph`'s two-pass draw
+    order): labels draw only after every edge's line+arrowheads are already
+    on the canvas, so nothing draws over a label afterwards, and a *later*
+    label's own clear-run search treats an earlier label's cells the same
+    as a box's — skip, don't overwrite.
     """
     length = visual_len(label)
     if length <= 0:
@@ -1246,12 +1297,14 @@ def _draw_label_on_segment(
             run = cells(start)
             if not any(canvas.is_reserved(x, y) for x, y in run):
                 for (px, py), ch in zip(run, label):
-                    canvas.draw_glyph(px, py, ch)
+                    canvas.set_char(px, py, ch, reserve=True)
+                _reserve_label_margin(canvas, start - 1, row)
+                _reserve_label_margin(canvas, start + length, row)
                 return
         start = max(lo, min(center - length // 2, hi - length + 1))
         for (px, py), ch in zip(cells(start), label):
             if not canvas.is_reserved(px, py):
-                canvas.draw_glyph(px, py, ch)
+                canvas.set_char(px, py, ch, reserve=True)
         return
 
     # Vertical segment: the label still reads horizontally, centered on
@@ -1272,11 +1325,13 @@ def _draw_label_on_segment(
         run = row_cells(row)
         if not any(canvas.is_reserved(x, y) for x, y in run):
             for (px, py), ch in zip(run, label):
-                canvas.draw_glyph(px, py, ch)
+                canvas.set_char(px, py, ch, reserve=True)
+            _reserve_label_margin(canvas, start_x - 1, row)
+            _reserve_label_margin(canvas, start_x + length, row)
             return
     for (px, py), ch in zip(row_cells(center_row), label):
         if not canvas.is_reserved(px, py):
-            canvas.draw_glyph(px, py, ch)
+            canvas.set_char(px, py, ch, reserve=True)
 
 
 def _draw_polyline(canvas: Canvas, points: list[tuple[int, int]], style: EdgeStyle) -> None:
@@ -1322,67 +1377,61 @@ def _self_loop_points(
     return [(ax, lo), (far, lo), (far, hi), (ax, hi)]
 
 
-def _route_edge(
-    canvas: Canvas,
+def _route_edge_path(
     rects: dict[str, BoxRect],
     direction: Direction,
     edge: FlowEdge,
     lane_counter: list[int],
     self_loop_counter: dict[str, int],
-) -> None:
-    """Draw one edge's full orthogonal path: anchors chosen by relative
-    rank position, an L/Z/C path shape, arrowheads, and an edge label.
-    Dangling node-id references are a defensive no-op (the parser
-    guarantees valid endpoints; this module never crashes on one).
+) -> list[tuple[int, int]] | None:
+    """Compute one edge's polyline points: anchors chosen by relative rank
+    position, an L/Z/C path shape. Pure path computation only — drawing is
+    the caller's job, split into two passes across *all* edges (see
+    :func:`layout_flowgraph`) so that no edge's line ever overwrites
+    another edge's already-placed label. Dangling node-id references
+    return ``None`` (defensive no-op — the parser guarantees valid
+    endpoints; this module never crashes on one).
     """
     src_rect = rects.get(edge.src)
     dst_rect = rects.get(edge.dst)
     if src_rect is None or dst_rect is None:
-        return
+        return None
 
     if edge.src == edge.dst:
         lane = self_loop_counter.get(edge.src, 0)
         self_loop_counter[edge.src] = lane + 1
-        points = _self_loop_points(direction, src_rect, lane)
-    else:
-        src_extent = _rank_extent(direction, src_rect)
-        dst_extent = _rank_extent(direction, dst_rect)
-        same_rank = not (dst_extent[1] < src_extent[0] or src_extent[1] < dst_extent[0])
+        return _self_loop_points(direction, src_rect, lane)
+
+    src_extent = _rank_extent(direction, src_rect)
+    dst_extent = _rank_extent(direction, dst_rect)
+    same_rank = not (dst_extent[1] < src_extent[0] or src_extent[1] < dst_extent[0])
+
+    if same_rank:
+        return [_facing_anchor(src_rect, dst_rect), _facing_anchor(dst_rect, src_rect)]
+
+    src_center = (src_extent[0] + src_extent[1]) / 2
+    dst_center = (dst_extent[0] + dst_extent[1]) / 2
+    forward = (dst_center > src_center) == _forward_increasing(direction)
+    if forward:
+        return _z_path(
+            direction,
+            _forward_exit(direction, src_rect),
+            _forward_entry(direction, dst_rect),
+        )
 
-        if same_rank:
-            points = [_facing_anchor(src_rect, dst_rect), _facing_anchor(dst_rect, src_rect)]
-        else:
-            src_center = (src_extent[0] + src_extent[1]) / 2
-            dst_center = (dst_extent[0] + dst_extent[1]) / 2
-            forward = (dst_center > src_center) == _forward_increasing(direction)
-            if forward:
-                points = _z_path(
-                    direction,
-                    _forward_exit(direction, src_rect),
-                    _forward_entry(direction, dst_rect),
-                )
-            else:
-                lane = lane_counter[0]
-                lane_counter[0] += 1
-                lane_secondary = (
-                    _lane_secondary_base(direction, src_rect, dst_rect)
-                    + _LANE_MARGIN
-                    + lane * _LANE_GAP
-                )
-                points = _lane_path(
-                    direction,
-                    _lane_anchor(direction, src_rect),
-                    _lane_anchor(direction, dst_rect),
-                    lane_secondary,
-                )
-
-    _draw_polyline(canvas, points, edge.style)
-    _draw_arrowheads(canvas, points, edge)
-
-    if edge.label:
-        seg = _longest_segment(points)
-        if seg is not None:
-            _draw_label_on_segment(canvas, *seg, edge.label)
+    lane = lane_counter[0]
+    lane_counter[0] += 1
+    lane_secondary = (
+        _lane_secondary_base(direction, src_rect, dst_rect)
+        + _LANE_MARGIN
+        + lane * _LANE_GAP
+    )
+    return _lane_path(
+        direction,
+        _lane_anchor(direction, src_rect),
+        _lane_anchor(direction, dst_rect),
+        lane_secondary,
+    )
 
 
 # --------------------------------------------------------------------------
@@ -1451,10 +1500,27 @@ def layout_flowgraph(g: FlowGraph, width: int) -> list[str]:
             rect = rects.get(n.id)
             if rect is not None:
                 canvas.draw_box(rect, n.shape, n.label)
+        # Two passes across *all* edges, not one pass per edge: every
+        # edge's line + arrowheads draw first, then every edge's label
+        # draws last (see design doc). Interleaving line-then-label per
+        # edge (the old order) let a later edge's line silently erase an
+        # earlier edge's already-placed label whenever their paths shared
+        # a cell — labels are only ever safe once no more lines are coming.
         lane_counter = [0]
         self_loop_counter: dict[str, int] = {}
+        edge_paths: list[tuple[FlowEdge, list[tuple[int, int]]]] = []
         for e in g.edges:
-            _route_edge(canvas, rects, g.direction, e, lane_counter, self_loop_counter)
+            points = _route_edge_path(rects, g.direction, e, lane_counter, self_loop_counter)
+            if points is not None:
+                edge_paths.append((e, points))
+        for e, points in edge_paths:
+            _draw_polyline(canvas, points, e.style)
+            _draw_arrowheads(canvas, points, e)
+        for e, points in edge_paths:
+            if e.label:
+                seg = _longest_segment(points)
+                if seg is not None:
+                    _draw_label_on_segment(canvas, *seg, e.label)
         return canvas.to_lines()
     except Exception:
         return []