termrender 4.9.1__tar.gz → 4.10.1__tar.gz

{termrender-4.9.1 → termrender-4.10.1}/CHANGELOG.md

@@ -1,6 +1,62 @@
 # CHANGELOG
 
 
+## v4.10.1 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid-flow**: Constant inter-layer gap regardless of node height
+  ([`eb1726f`](https://github.com/crouton-labs/termrender/commit/eb1726fa4bd05a57d29026b10715edc067ac4113))
+
+The rank-band gap override that widens spacing to fit a labeled edge scaled with visual_len(label)
+  (the label's *text width*) even on TB/BT diagrams, where the label is drawn horizontally across a
+  vertical connector and only ever needs one clear row, not one row per character. Since ER/class
+  diagrams route almost every edge through a label (relationship text, cardinality), this made
+  compartmented-node TB layouts burn ~15-17 blank connector rows per edge hop while 1-line-node
+  flowcharts stayed compact — node height was a red herring; the real driver was label width feeding
+  a row count.
+
+_rank_gap_overrides is now direction-aware: LR/RL keeps the width-scaled gap (the transpose turns
+  that native row-band into the final horizontal run the label reads along, so it genuinely needs
+  the width). TB/BT gets a small constant, _LABELED_ROW_GAP=3, regardless of label length.
+
+Updates the two TB labeled-edge goldens in test_mermaid_flow_corpus.py to the new compact spacing,
+  and adds a regression test in test_mermaid_er.py pinning a row budget for compartmented entities
+  so this doesn't regress.
+
+
+## v4.10.0 (2026-07-07)
+
+### Features
+
+- **mermaid**: Native dispatch for flowchart/class/state/er, drop vendored Go binary
+  ([`6935f30`](https://github.com/crouton-labs/termrender/commit/6935f30a1dccfefcc34344de02191f8481d53668))
+
+Wire the four previously-unwired native renderers into mermaid.py's first-line dispatcher:
+  flowchart/graph -> mermaid_flow.render_flowchart, classDiagram -> mermaid_class.render_class,
+  stateDiagram/-v2 -> mermaid_state.render_state, erDiagram -> mermaid_er.render_er. Every mermaid
+  type termrender renders is now native Python; no diagram type shells out anymore.
+
+Unrecognized/exotic types (sankey, C4, gitgraph, block, packet, kanban, quadrantChart, ...) degrade
+  in the dispatcher itself to a raw echo of the source with box-drawing/geometric glyphs stripped,
+  preserving the contract the crouter attach viewer relies on to detect render failure by glyph
+  absence.
+
+Delete the vendored Go path entirely: src/termrender/_bin/ (binary), src/termrender/_mermaid_bin.py,
+  scripts/build-mermaid-ascii.sh, the mermaid-ascii runtime dependency and hatch artifacts stanza in
+  pyproject.toml (relocked via uv.lock), and scripts/mermaid_flow_parity.py (a standalone dev-only
+  harness comparing native output against the now-deleted binary).
+
+tests/test_mermaid_compat.py pinned Go-era preprocessing (preprocess_mermaid_for_ascii) that no
+  longer exists; deleted wholesale since dispatch/prelude contracts it also touched already live in
+  test_mermaid_dispatch.py. That file's routing tests are updated for the four newly-wired types and
+  gain dispatch tests for the exotic raw-echo path (including a no-native-renderer-called assertion
+  and a glyph-range sweep pinning the no-box-glyph contract).
+
+Swept src/termrender/renderers/CLAUDE.md and README.md to current-state only; no remaining
+  references to mermaid-ascii/_mermaid_bin/the Go binary anywhere in the tree.
+
+
 ## v4.9.1 (2026-07-07)
 
 ### Bug Fixes

{termrender-4.9.1 → termrender-4.10.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.9.1
+Version: 4.10.1
 Summary: Rich terminal rendering of directive-flavored markdown
 Project-URL: Homepage, https://github.com/CaptainCrouton89/termrender
 Project-URL: Repository, https://github.com/CaptainCrouton89/termrender
@@ -22,7 +22,6 @@ Classifier: Topic :: Terminals
 Classifier: Topic :: Text Processing :: Markup :: Markdown
 Requires-Python: >=3.10
 Requires-Dist: grandalf>=0.8
-Requires-Dist: mermaid-ascii>=1.2
 Requires-Dist: mistune>=3.0
 Requires-Dist: pygments>=2.0
 Description-Content-Type: text/markdown
@@ -163,7 +162,7 @@ That entire output — the nested borders, the tree guide lines, the side-by-sid
 pip install termrender
 ```
 
-Python 3.10+. Three dependencies: [mistune](https://github.com/lepture/mistune) (markdown parsing), [pygments](https://pygments.org/) (syntax highlighting), [mermaid-ascii](https://github.com/mermaid-js/mermaid-ascii) (diagram rendering).
+Python 3.10+. Three dependencies: [mistune](https://github.com/lepture/mistune) (markdown parsing), [pygments](https://pygments.org/) (syntax highlighting), [grandalf](https://github.com/bdcht/grandalf) (mermaid diagram layout).
 
 
 ## Usage
@@ -409,7 +408,7 @@ Horizontal rules with optional centered labels.
 
 ### Mermaid diagrams
 
-Renders mermaid flowcharts as ASCII art via [mermaid-ascii](https://github.com/mermaid-js/mermaid-ascii). Use the `:::mermaid` directive, or a standard GFM ` ```mermaid ` fenced code block — both render the same diagram.
+Renders mermaid diagrams (flowcharts, class/state/ER diagrams, pie/gantt/sequence/mindmap/journey/timeline charts) natively as ASCII/unicode art. Use the `:::mermaid` directive, or a standard GFM ` ```mermaid ` fenced code block — both render the same diagram.
 
 **Input:**
 ```markdown
@@ -421,7 +420,7 @@ graph LR
 :::
 ```
 
-The diagram gets rendered as ASCII art inline in the terminal output. Requires `mermaid-ascii` to be installed (it's a dependency, so it should be).
+The diagram gets rendered as ASCII art inline in the terminal output, no external binary required.
 
 
 ### Nesting

{termrender-4.9.1 → termrender-4.10.1}/README.md

@@ -134,7 +134,7 @@ That entire output — the nested borders, the tree guide lines, the side-by-sid
 pip install termrender
 ```
 
-Python 3.10+. Three dependencies: [mistune](https://github.com/lepture/mistune) (markdown parsing), [pygments](https://pygments.org/) (syntax highlighting), [mermaid-ascii](https://github.com/mermaid-js/mermaid-ascii) (diagram rendering).
+Python 3.10+. Three dependencies: [mistune](https://github.com/lepture/mistune) (markdown parsing), [pygments](https://pygments.org/) (syntax highlighting), [grandalf](https://github.com/bdcht/grandalf) (mermaid diagram layout).
 
 
 ## Usage
@@ -380,7 +380,7 @@ Horizontal rules with optional centered labels.
 
 ### Mermaid diagrams
 
-Renders mermaid flowcharts as ASCII art via [mermaid-ascii](https://github.com/mermaid-js/mermaid-ascii). Use the `:::mermaid` directive, or a standard GFM ` ```mermaid ` fenced code block — both render the same diagram.
+Renders mermaid diagrams (flowcharts, class/state/ER diagrams, pie/gantt/sequence/mindmap/journey/timeline charts) natively as ASCII/unicode art. Use the `:::mermaid` directive, or a standard GFM ` ```mermaid ` fenced code block — both render the same diagram.
 
 **Input:**
 ```markdown
@@ -392,7 +392,7 @@ graph LR
 :::
 ```
 
-The diagram gets rendered as ASCII art inline in the terminal output. Requires `mermaid-ascii` to be installed (it's a dependency, so it should be).
+The diagram gets rendered as ASCII art inline in the terminal output, no external binary required.
 
 
 ### Nesting

{termrender-4.9.1 → termrender-4.10.1}/pyproject.toml

@@ -28,7 +28,6 @@ classifiers = [
 ]
 dependencies = [
     "mistune>=3.0",
-    "mermaid-ascii>=1.2",
     "pygments>=2.0",
     "grandalf>=0.8",
 ]
@@ -46,11 +45,6 @@ source = "vcs"
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/termrender"]
-# Ship the vendored mermaid-ascii binary (built from pinned upstream master;
-# see scripts/build-mermaid-ascii.sh). It lives inside the package dir so the
-# default file selection includes it; artifacts ensures it survives even if
-# VCS-ignored, and hatchling preserves its 0o755 exec bit.
-artifacts = ["src/termrender/_bin/*"]
 
 [tool.semantic_release]
 version_toml = []

{termrender-4.9.1 → termrender-4.10.1}/src/termrender/renderers/CLAUDE.md

@@ -43,20 +43,14 @@ Attribution line is rendered for `block.attrs["author"]` **or** `block.attrs["by
 
 `mermaid.py`'s `render(block, color)` (leaf signature, no `render_child` — the parent `CLAUDE.md` incorrectly lists mermaid as a Container renderer) is a thin wrapper: it reads `block.attrs["_rendered"]` if layout already precomputed it, else calls `render_mermaid_lines(source, width)`, then pads every line to `block.width` with `visual_ljust`. All the type-routing logic lives in `render_mermaid_lines`, shared with `layout.py`'s height pass (see below) so there is exactly one dispatch path, not two.
 
-**Dispatch is by first real line, case-insensitive** (`_first_line_type`), after skipping any prelude via `mermaid_prelude.strip_prelude_lines` (see below): `pie`, `gantt`, `sequenceDiagram`, `mindmap`, `journey`, and `timeline` route to native Python renderers (`mermaid_pie.py`, `mermaid_gantt.py`, `mermaid_sequence.py`, `mermaid_mindmap.py`, `mermaid_journey.py`, `mermaid_timeline.py`). Every other type — `graph`/`flowchart`, `classDiagram`, `stateDiagram`, `erDiagram`, … — routes to `_render_via_binary`, the pre-existing single path through the vendored Go `mermaid-ascii` binary. **Only the six listed types have native renderers; every other type's degradation is byte-for-byte what it was before this dispatcher existed** — do not add a bordered fallback panel for them, since crouter's attach viewer detects render failure by the *absence* of box-drawing glyphs in the output, and a decorative border would defeat that.
+**Dispatch is by first real line, case-insensitive** (`_first_line_type`), after skipping any prelude via `mermaid_prelude.strip_prelude_lines` (see below): `pie`, `gantt`, `sequenceDiagram`, `mindmap`, `journey`, `timeline`, `graph`/`flowchart`, `classDiagram`, `stateDiagram`/`stateDiagram-v2`, and `erDiagram` all route to dedicated native Python renderers (`mermaid_pie.py`, `mermaid_gantt.py`, `mermaid_sequence.py`, `mermaid_mindmap.py`, `mermaid_journey.py`, `mermaid_timeline.py`, `mermaid_flow.py::render_flowchart`, `mermaid_class.py::render_class`, `mermaid_state.py::render_state`, `mermaid_er.py::render_er`). Every other type (sankey, C4, gitgraph, block, packet, kanban, quadrantChart, …, and anything unrecognized) has no renderer at all and degrades in the dispatcher itself, via `_raw_echo`: the source lines verbatim, `.rstrip()`-ed, with any box-drawing/geometric glyph (`\u2500-\u259f`/`\u25a0-\u25ff`) replaced by `?`. **Do not add a bordered fallback panel for the exotic path** — crouter's attach viewer detects render failure by the *absence* of box-drawing glyphs in the output, and a decorative border would defeat that; the four flowchart-model-backed native renderers (flow/class/state/ER) uphold the identical no-glyph guarantee on their own internal degradation paths (malformed input, wrong header, zero nodes/classes/states/entities parsed, or an unexpected exception escaping layout) — see each module's own docstring.
 
-**`mermaid_prelude.py`** — a tiny shared module (no dependency on `Block` or the rest of the pipeline) implementing `strip_prelude_lines(lines)`, used by both `mermaid.py`'s dispatch sniff and `mermaid_sequence.py`'s own header check. It skips leading blank lines, `%%` line comments, `%%{init: ...}%%` directives, and `---`-delimited YAML frontmatter, permissively: an unterminated frontmatter block or directive is left alone rather than eating real content. Prelude stripping is for *sniffing/validating the type line only* — the per-type body parsers still receive the full untouched source; `mermaid_sequence.py`'s `_parse` already tolerates arbitrary prelude lines before its header (they fail every line pattern and are skipped via its `seen_header` gate), and `mermaid_pie.py`/`mermaid_gantt.py`/the mindmap/journey/timeline parsers likewise just skip lines that don't match their grammar — a frontmatter `title: X` line could in principle collide with a `title` grammar rule, but this is accepted as the same class of pragmatic-parsing tradeoff as any other unrecognized line, not something the prelude skip needs to prevent.
+**`mermaid_prelude.py`** — a tiny shared module (no dependency on `Block` or the rest of the pipeline) implementing `strip_prelude_lines(lines)`, used by `mermaid.py`'s dispatch sniff and by every native renderer's own header check (`mermaid_sequence.py`, `mermaid_flow_parser.py`, `mermaid_class.py`, `mermaid_state.py`, `mermaid_er.py`). It skips leading blank lines, `%%` line comments, `%%{init: ...}%%` directives, and `---`-delimited YAML frontmatter, permissively: an unterminated frontmatter block or directive is left alone rather than eating real content. Prelude stripping is for *sniffing/validating the type line only* — most per-type body parsers receive the full untouched source and do their own prelude-aware header check internally (flow/class/state/ER/sequence); `mindmap`/`journey`/`timeline` are the exception, called with `mermaid.py::_stripped(source)` since those parsers don't skip prelude themselves. `mermaid_pie.py`/`mermaid_gantt.py` just skip lines that don't match their grammar — a frontmatter `title: X` line could in principle collide with a `title` grammar rule, but this is accepted as the same class of pragmatic-parsing tradeoff as any other unrecognized line.
 
-**`_render_via_binary`** (used for flowchart/graph/class/state/ER/everything-without-a-native-renderer): normalizes via `preprocess_mermaid_for_ascii`, shells out with `check=True`, and undoes the Latin-1 double-encoding via `fix_mermaid_encoding` (`mermaid-ascii` misreads UTF-8 input as Latin-1 and re-encodes, corrupting multi-byte characters — e.g. `→` becomes `â\x86\x92`; `text.encode("latin-1").decode("utf-8")` reverses it, and on failure silently returns the corrupted string). Any failure — `CalledProcessError` (including a non-zero exit, now actually checked via `check=True`), missing binary, or timeout — degrades to the raw source text. A labeled back-edge (`X -->|lbl| Y` in `graph LR`) panics the binary on both the PyPI 1.2.0 wheel and vendored master; the resulting non-zero exit degrades the same way. Note `preprocess_mermaid_for_ascii` has its own independent first-line sniff (not `mermaid_prelude`-aware) to decide sequence-vs-flowchart-vs-other normalization — a prelude ahead of `graph`/`flowchart`/`sequenceDiagram` here means no shape/arrow normalization runs, an existing (unfixed) limitation of the binary path, orthogonal to dispatch routing.
-
-**`visual_ljust` pads but never truncates**: every output line (from any type — binary or native) is padded to `block.width` in the outer `render()`. Lines wider than `block.width` overflow without clipping. `mermaid-ascii` has no width-control flag (`--maxWidth`/`-w` do not exist — the call passes only `-f - -y 1`), so wide flowchart output silently exceeds the layout boundary; the native renderers respect `width` by construction (pie/gantt/timeline size their own bars to it; sequence/mindmap/journey have intrinsic width and may overflow, matching the binary path's contract) — see each renderer's own note below.
+**`visual_ljust` pads but never truncates**: every output line (from any type) is padded to `block.width` in the outer `render()`. Lines wider than `block.width` overflow without clipping — pie/gantt/timeline size their own bars to `width`; sequence/mindmap/journey and the four flowchart-model-backed renderers (flow/class/state/ER) have intrinsic content-driven width and may overflow, `width` there is advisory only.
 
 Layout (`layout.py::resolve_height`, `BlockType.MERMAID` branch) precomputes `block.attrs["_rendered"]` by calling the same `render_mermaid_lines`, so `mermaid.py`'s `render()` only recomputes when that key is absent (e.g. calling `render()` on a block that skipped the layout pass).
 
-**Flowchart node shapes are normalized to rectangles**: `preprocess_mermaid_for_ascii` rewrites every non-rectangle flowchart node shape (`{rhombus}`, `[(cylinder)]`, `((circle))`, `([stadium])`, `{{hexagon}}`, `[[subroutine]]`, `[/parallelogram/]`) to the `id[label]` form via `_FLOWCHART_SHAPE_SUBS`, because mermaid-ascii's `parseNode` only recognizes `[text]` rectangles — other shapes otherwise leak raw delimiters or the bare node id into the box. This is a permanent workaround: node shapes are unsupported on current upstream master (pin `6fffb8e`) and the 6 newer master commits are arrow-parsing only, so don't expect a pin bump to remove the need. The backend draws a rectangle regardless, so only the label text matters.
-
-**Binary resolution**: the executable comes from `_mermaid_bin.mermaid_ascii_bin()` — the vendored `_bin/mermaid-ascii-<os>-<arch>` (pinned upstream master `6fffb8e`, built via `scripts/build-mermaid-ascii.sh`) if present for the platform, else `mermaid-ascii` on PATH (the PyPI wheel, capped at 1.2.0).
-
 ## `mermaid_pie.py` — re-expressed as a bar chart, not a text circle
 
 A text pie chart is worse than a labeled bar chart at the same information density (per the ratified plan), so `parse_pie` extracts `(title, items)` from the `pie [showData]` / `title …` / `"label" : value` grammar and `render` hands the items to `charts.py::render_bar` via a synthetic `Block(type=BlockType.BAR, ...)` — no duplicated bar-drawing logic. Each item's `unit` attr is set to the pre-formatted percentage string (e.g. `" (40.0%)"`) so `render_bar`'s existing value-formatting appends it for free. Called with `color=False` always — mermaid output is monochrome by design (the attach viewer relies on `--color on == --color off`). Unparseable/empty input degrades to the raw source lines, same contract as the binary path.

{termrender-4.9.1 → termrender-4.10.1}/src/termrender/renderers/borders.py

@@ -31,9 +31,10 @@ def render_box(
     corner_v = visual_len("┌")  # same as ┐, └, ┘
 
     # Grow the box if any content line (or the title) won't fit at the
-    # requested width. mermaid-ascii has no width-control flag, so a child
-    # mermaid block can return lines wider than its allocated content area.
-    # Truncating would corrupt the diagram; growing keeps the box's top,
+    # requested width. Several mermaid renderers size to content rather than
+    # to width (flowchart/class/state/ER/sequence/mindmap/journey), so a
+    # child mermaid block can return lines wider than its allocated content
+    # area. Truncating would corrupt the diagram; growing keeps the box's top,
     # bottom, and side borders aligned at the same column even if it
     # overflows the parent's allocation.
     content_max = visual_len("")

termrender-4.10.1/src/termrender/renderers/mermaid.py

@@ -0,0 +1,117 @@
+"""Mermaid diagram renderer for termrender."""
+
+from __future__ import annotations
+
+import re
+
+from termrender.blocks import Block
+from termrender.renderers import (
+    mermaid_class,
+    mermaid_er,
+    mermaid_flow,
+    mermaid_gantt,
+    mermaid_journey,
+    mermaid_mindmap,
+    mermaid_pie,
+    mermaid_sequence,
+    mermaid_state,
+    mermaid_timeline,
+)
+from termrender.renderers.mermaid_prelude import strip_prelude_lines
+from termrender.style import visual_ljust
+
+# Same box-drawing/geometric glyph ranges the native renderers (mermaid_flow,
+# mermaid_class, mermaid_state, mermaid_er) guard their own raw-echo paths
+# with, and the same ranges the downstream crouter viewer keys on to detect
+# render *success*. An exotic/unrecognized diagram type has no renderer at
+# all, so its degradation lives here rather than in a shared renderer module;
+# it must uphold the identical contract — no such glyph survives the echo,
+# even one present verbatim in the source itself.
+_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
+
+
+def _first_line_type(source: str) -> str:
+    """Return the lowercased first real line's leading keyword.
+
+    This is the dispatch key: mermaid identifies a diagram's type from its
+    first line (``graph``/``flowchart``, ``pie``, ``gantt``, ``sequenceDiagram``,
+    ``classDiagram``, ``stateDiagram``, ``erDiagram``, …), after skipping any
+    prelude (blank lines, ``%%`` comments/directives, ``---`` YAML
+    frontmatter — see ``mermaid_prelude.py``). Returns ``""`` for a source
+    with no real content past its prelude.
+    """
+    lines = strip_prelude_lines(source.splitlines())
+    first = next((l.strip() for l in lines if l.strip()), "")
+    return first.lower()
+
+
+def _stripped(source: str) -> str:
+    """Return ``source`` with its leading prelude (comments/directives/
+    frontmatter) removed, for native renderers that don't otherwise skip it.
+    """
+    return "\n".join(strip_prelude_lines(source.splitlines()))
+
+
+def _raw_echo(source: str) -> list[str]:
+    """Degrade an exotic/unrecognized diagram type to its raw source lines.
+
+    No renderer exists for these types (sankey, C4, gitgraph, block, packet,
+    kanban, quadrantChart, …, and anything unrecognized): the source is
+    echoed back verbatim, with box-drawing/geometric glyphs neutralized so
+    the crouter viewer's "no glyphs survived" success check can't be fooled
+    by one present in the raw source itself — the same guarantee every
+    native renderer's own raw-echo path upholds.
+    """
+    return [
+        _GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()
+    ]
+
+
+def render_mermaid_lines(source: str, width: int) -> list[str]:
+    """Dispatch a mermaid source to its type's renderer and return raw lines.
+
+    Every diagram type mermaid supports that termrender renders has a
+    dedicated native Python renderer: ``pie``, ``gantt``, ``sequenceDiagram``,
+    ``mindmap``, ``journey``, ``timeline``, ``graph``/``flowchart``,
+    ``classDiagram``, ``stateDiagram``/``stateDiagram-v2``, and ``erDiagram``.
+    Any other type (sankey, C4, gitgraph, block, packet, kanban, …, or
+    anything unrecognized) degrades to a raw echo of the source with no
+    box-drawing glyphs — see :func:`_raw_echo`. Lines are returned unpadded;
+    callers apply width padding uniformly.
+    """
+    diagram_type = _first_line_type(source)
+    if diagram_type.startswith("pie"):
+        return mermaid_pie.render(source, width)
+    if diagram_type.startswith("gantt"):
+        return mermaid_gantt.render(source, width)
+    if diagram_type.startswith("sequencediagram"):
+        return mermaid_sequence.render_sequence(source, width)
+    if diagram_type.startswith("mindmap"):
+        return mermaid_mindmap.render(_stripped(source), width)
+    if diagram_type.startswith("journey"):
+        return mermaid_journey.render(_stripped(source), width)
+    if diagram_type.startswith("timeline"):
+        return mermaid_timeline.render(_stripped(source), width)
+    if diagram_type.startswith(("graph", "flowchart")):
+        return mermaid_flow.render_flowchart(source, width)
+    if diagram_type.startswith("classdiagram"):
+        return mermaid_class.render_class(source, width)
+    if diagram_type.startswith("statediagram"):
+        return mermaid_state.render_state(source, width)
+    if diagram_type.startswith("erdiagram"):
+        return mermaid_er.render_er(source, width)
+    return _raw_echo(source)
+
+
+def render(block: Block, color: bool) -> list[str]:
+    """Render a mermaid diagram from pre-rendered or on-the-fly ASCII output."""
+    w = block.width
+    rendered = block.attrs.get("_rendered")
+
+    if rendered is None:
+        source = block.attrs.get("source", "")
+        raw_lines = render_mermaid_lines(source, w or 60)
+    else:
+        raw_lines = rendered.split("\n")
+
+    return [visual_ljust(raw_line, w) for raw_line in raw_lines]

{termrender-4.9.1 → termrender-4.10.1}/src/termrender/renderers/mermaid_flow_layout.py

@@ -831,24 +831,45 @@ _GAP_X = 3          # minimum border-to-border gap between boxes in one rank/ban
 _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.
+                     # when it forces a rank-band gap wider than _ROW_GAP
+                     # along the axis the label's text actually runs.
+_LABELED_ROW_GAP = 3  # inter-rank gap when a label sits on that band's vertical
+                      # run in *final* screen space (TB/BT): one blank row, the
+                      # label's own row, one more blank row. A constant, not
+                      # scaled by the label's text length — the label reads
+                      # horizontally on a single row regardless of how many
+                      # characters it has, so the row *count* needed is fixed.
 
 
 def _rank_gap_overrides(
-    edges: list[FlowEdge], rank_of: dict[str, int]
+    edges: list[FlowEdge], rank_of: dict[str, int], direction: Direction
 ) -> 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.
+    this gap.
+
+    The rank axis is native rows here, pre-direction-transform (see the
+    adapter docstring) — whether that ends up as *vertical* or
+    *horizontal* space on screen depends on ``direction``. For LR/RL the
+    transpose turns this band into the final horizontal run the label
+    reads along, so it genuinely needs ``visual_len(label)`` cells of
+    width — at the base ``_ROW_GAP`` a label wider than a couple of cells
+    has nowhere to go but onto the boxes it connects (the short
+    LR/adjacent-rank clipped-label bug this closes). For TB/BT the band
+    stays vertical on screen and the label is drawn horizontally *across*
+    the connector column (:func:`_draw_label_on_segment`'s vertical-segment
+    branch) — it needs a little row headroom to have its own clear row,
+    not a row per character, so it gets the small constant
+    ``_LABELED_ROW_GAP`` regardless of the label's length.
+
     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] = {}
+    horizontal_on_screen = direction in (Direction.LR, Direction.RL)
     for e in edges:
         if e.src == e.dst or not e.label:
             continue
@@ -859,7 +880,10 @@ def _rank_gap_overrides(
         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
+        if horizontal_on_screen:
+            needed = visual_len(e.label) + 2 * _LABEL_GAP_PAD
+        else:
+            needed = _LABELED_ROW_GAP
         overrides[lo_r] = max(overrides.get(lo_r, _ROW_GAP), needed)
     return overrides
 
@@ -922,7 +946,7 @@ def _place_nodes(
             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)
+        gap_overrides = _rank_gap_overrides(edges, rank_of, direction)
 
         band_top_for_rank: dict[int, int] = {}
         cursor = 0