termrender 4.0.0__tar.gz → 4.1.0__tar.gz

{termrender-4.0.0 → termrender-4.1.0}/CHANGELOG.md

@@ -1,6 +1,29 @@
 # CHANGELOG
 
 
+## v4.1.0 (2026-07-06)
+
+### Features
+
+- **renderers**: Dispatch mermaid by type; native pie and gantt renderers
+  ([`08decd1`](https://github.com/crouton-labs/termrender/commit/08decd191c7b17680a8785037b87807d18959de5))
+
+mermaid.py becomes a first-line type dispatcher: pie and gantt now get dedicated native Python
+  renderers instead of falling through to the vendored Go mermaid-ascii binary (which just echoed
+  them as plaintext). Every other type's degradation is unchanged byte-for-byte, including
+  flowchart/graph routing to the Go binary.
+
+- mermaid_pie.py: parses the pie grammar and renders a labeled horizontal bar chart with
+  percentages, reusing charts.py's render_bar. - mermaid_gantt.py: parses the core gantt grammar
+  (dateFormat, sections, tasks with dates/durations/after-deps) and renders section-grouped rows
+  with time-span bars scaled to the overall date range. Malformed lines and unresolvable tasks
+  degrade gracefully instead of crashing. - layout.py's height pass now shares the same
+  render_mermaid_lines dispatch mermaid.py uses, removing a duplicated subprocess call.
+
+Tests: parser/layout coverage for both new renderers plus dispatcher routing tests
+  (test_mermaid_pie.py, test_mermaid_gantt.py, test_mermaid_dispatch.py).
+
+
 ## v4.0.0 (2026-07-06)
 
 ### Features

{termrender-4.0.0 → termrender-4.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.0.0
+Version: 4.1.0
 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.0.0 → termrender-4.1.0}/src/termrender/layout.py

@@ -2,11 +2,8 @@
 
 from __future__ import annotations
 
-import subprocess
-
-from termrender._mermaid_bin import mermaid_ascii_bin
 from termrender.blocks import Block, BlockType
-from termrender.renderers.mermaid import fix_mermaid_encoding, preprocess_mermaid_for_ascii
+from termrender.renderers.mermaid import render_mermaid_lines
 from termrender.style import wrap_text, visual_len
 
 
@@ -145,21 +142,9 @@ def resolve_height(block: Block) -> None:
 
     elif bt == BlockType.MERMAID:
         source = block.attrs.get("source", "") or _plain_text(block.text)
-        rendered = source  # fallback
-        try:
-            result = subprocess.run(
-                [mermaid_ascii_bin(), "-f", "-", "-y", "1"],
-                input=preprocess_mermaid_for_ascii(source),
-                capture_output=True,
-                text=True,
-                check=True,
-                timeout=30,
-            )
-            rendered = fix_mermaid_encoding(result.stdout)
-        except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired):
-            pass
-        block.attrs["_rendered"] = rendered
-        block.height = len(rendered.split("\n")) if rendered else 1
+        lines = render_mermaid_lines(source, width)
+        block.attrs["_rendered"] = "\n".join(lines)
+        block.height = len(lines) if lines else 1
 
     elif bt == BlockType.QUOTE:
         block.height = sum(c.height or 0 for c in block.children) + (1 if block.attrs.get("author") or block.attrs.get("by") else 0)

termrender-4.1.0/src/termrender/renderers/CLAUDE.md

@@ -0,0 +1,68 @@
+# Renderers
+
+## Renderer signature convention
+Two signatures exist — not enforced by typing, but the dispatcher expects them:
+- **Leaf renderers** (`divider.py`, `tree.py`): `render(block, color) -> list[str]`
+- **Container renderers** (`panel.py`, `quote.py`, `code.py`, `columns.py`): `render(block, color, render_child) -> list[str]`
+
+`render_child` is the engine's dispatch function; call it to recurse into child blocks rather than calling sibling renderers directly.
+
+## `render_box` — width is total, not content
+`borders.py:render_box(content_lines, width, ...)` — `width` is the **full** box width including the two `│` border columns. Content width is `width - 2*border_v - 2` (border + 1-space padding each side). Passing inner/content width here produces double-shrinkage.
+
+Used by `panel.py` and `code.py` (with `dim=True`).
+
+If `content_lines` is empty, `render_box` inserts one blank interior line — output is always ≥ 3 lines (top border + 1 blank + bottom border). Callers computing expected height from content line count must add 3, not 2.
+
+When `title` is provided, it is **left-anchored**, not centered: `┌─ TITLE ───┐`. The format is `"─ " + title + " "` flush-left, then fill dashes to `┐`. There is no API for a right-anchored or centered title.
+
+## EAW-dynamic guide characters in `tree.py`
+`_guide_chars()` is called at render time (not module init) because `visual_len("├── ")` differs under East Asian Width ambiguous=2 mode. Under that setting `"│"` is width 2 while `"─"` is width 1, so the four guide prefixes have inconsistent visual widths. `_guide_chars()` normalizes all four to the visual width of `"├── "` at runtime, picking up whatever EAW setting is active. The same EAW issue drives the dynamic `border_v`/`dash_v` math in `render_box`.
+
+## `tree.py` — source goes in `attrs["source"]`, indent is auto-detected
+Tree content comes from `block.attrs["source"]` (a raw multi-line string), not `block.text` or `block.children`. `_detect_indent` sniffs the first indented line: returns 2 for ≤2 spaces, the raw value for 3–4 spaces, and clamps to 4 for anything larger. A tree where the first sniffed indent is 5 or 6 spaces gets clamped to 4 — subsequent lines compute `depth = spaces // 4`, skipping depth levels silently (e.g. 6-space children land at depth 1, but 12-space grandchildren land at depth 3, not 2). `[x]` and `[!]` status markers in labels are replaced with styled Unicode symbols; `**bold**` and `*italic*` inline markdown is also parsed.
+
+Depth-0 items (no leading spaces) render with no guide prefix at all — a flat source is a plain list, no tree lines.
+
+`block.attrs["color"]` sets the guide-line color (the `├──` connectors); it is distinct from the `color: bool` render parameter and only styles guides, not labels.
+
+## `divider.py` — always dim, no color path
+`render()` hardcodes `dim=True`; there is no way to pass a custom color through the leaf signature. A colored divider requires a different renderer or direct `render_box` usage.
+
+Optional centered label comes from `block.attrs["label"]` (not `block.text`). `visual_center(inner, w, "─")` handles the fill — the label is padded as `" {label} "` before centering, so the label always has at least one space of breathing room from the surrounding dashes.
+
+## `quote.py` — dual attribution keys; EAW-sensitive bar width
+Attribution line is rendered for `block.attrs["author"]` **or** `block.attrs["by"]`; `"author"` takes precedence. Missing both suppresses the attribution line entirely.
+
+`bar_width = visual_len("│") + 1` — under EAW ambiguous=2, `"│"` is width 2 so `bar_width` becomes 3, shrinking `inner_w` by one extra column relative to default EAW. The bar itself is correct visually, but layout that pre-computes quote inner width assuming `bar_width == 2` will be off by 1 under EAW=2.
+
+## `panel.py` — callouts delegate through a proxy Block
+`render_callout` patches `title`, `color`, and `type=BlockType.PANEL` into a new `Block` instance and calls `render()` on it. The original block is not mutated. The callout type string (`"info"`, `"warning"`, `"error"`, `"success"`) is only used to look up `_CALLOUT_MAP`; an unknown type falls back to blue `ℹ`.
+
+## `mermaid.py` — first-line type dispatcher, not a single renderer
+
+`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 non-blank line, case-insensitive** (`_first_line_type`): `pie` and `gantt` route to the native Python renderers in `mermaid_pie.py` / `mermaid_gantt.py`. Every other type — `graph`/`flowchart`, `sequenceDiagram`, `classDiagram`, `stateDiagram`, `erDiagram`, `journey`, `mindmap`, … — routes to `_render_via_binary`, the pre-existing single path through the vendored Go `mermaid-ascii` binary. **Only `pie` and `gantt` 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.
+
+**`_render_via_binary`** (used for flowchart/graph/sequence/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.
+
+**`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/sequence output silently exceeds the layout boundary; the native pie/gantt renderers respect `width` by construction (they size their own bars to it) and don't have this problem.
+
+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.
+
+## `mermaid_gantt.py` — dates resolved via a running `last_end` cursor, not a strict grammar
+
+`parse_gantt` handles `dateFormat` (translated to a `strptime` pattern via a token map: `YYYY`→`%Y`, `MM`→`%m`, etc.), `title`, `section`, and task lines split on the first `:` into a comma-separated token list. Each token is classified in order — status keyword (`done`/`active`/`crit`/`milestone`, ignored) → `after <id...>` dependency → duration (`\d+[dwhms]`) → date (via the resolved `strptime` format) → bare identifier — so token order in the source doesn't matter, only which shape each token matches.
+
+**Missing start dates fall back to `last_end`**, a running cursor updated after every successfully-placed task (mirroring mermaid's own default-start-follows-previous-task semantics): a bare `Task2 :5d` with no date and no `after` picks up where the previous task left off; an `after <id>` referencing an id that was never seen falls back the same way rather than dropping the task. A task with no start anchor at all (first task in the diagram, no date, no `after`) is skipped — degrade, don't crash.
+
+`render` scales every task's `(start, end)` into a ratio over the full `[min_start, max_end]` span and draws a `░`/`█` track via `_draw_span`; section names are their own row, un-indented, with all task rows below sharing one global label-column width for alignment across sections. Diagrams with zero resolved tasks (parse produced no sections) degrade to the raw source lines.

{termrender-4.0.0 → termrender-4.1.0}/src/termrender/renderers/mermaid.py

@@ -7,6 +7,7 @@ import subprocess
 
 from termrender._mermaid_bin import mermaid_ascii_bin
 from termrender.blocks import Block
+from termrender.renderers import mermaid_gantt, mermaid_pie
 from termrender.style import visual_ljust
 
 
@@ -116,6 +117,59 @@ def preprocess_mermaid_for_ascii(source: str) -> str:
     return "\n".join(out)
 
 
+def _first_line_type(source: str) -> str:
+    """Return the lowercased first non-blank 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``, …). Returns ``""`` for an empty/blank source.
+    """
+    first = next((l.strip() for l in source.splitlines() if l.strip()), "")
+    return first.lower()
+
+
+def _render_via_binary(source: str) -> str:
+    """Render via the vendored mermaid-ascii binary, falling back to source.
+
+    This is the pre-existing path for every type without a native Python
+    renderer (flowchart/graph, sequence, class, state, ER, …): normalize
+    what mermaid-ascii can parse, shell out, and undo its Latin-1
+    double-encoding. Any failure (missing binary, timeout, non-zero exit,
+    a parser panic on unsupported input) degrades to the raw source text —
+    mermaid-ascii has no notion of "partial" output, so there is no middle
+    ground between a full render and falling back.
+    """
+    try:
+        result = subprocess.run(
+            [mermaid_ascii_bin(), "-f", "-", "-y", "1"],
+            input=preprocess_mermaid_for_ascii(source),
+            capture_output=True,
+            text=True,
+            check=True,
+            timeout=30,
+        )
+        return fix_mermaid_encoding(result.stdout)
+    except (subprocess.CalledProcessError, FileNotFoundError, subprocess.TimeoutExpired, OSError):
+        return source
+
+
+def render_mermaid_lines(source: str, width: int) -> list[str]:
+    """Dispatch a mermaid source to its type's renderer and return raw lines.
+
+    ``pie`` and ``gantt`` get dedicated native Python renderers. Every other
+    type (flowchart/graph, sequence, class, state, ER, journey, mindmap, …)
+    keeps today's exact path: the vendored Go mermaid-ascii binary, which
+    echoes unparseable/unsupported source back verbatim. 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)
+    return _render_via_binary(source).split("\n")
+
+
 def render(block: Block, color: bool) -> list[str]:
     """Render a mermaid diagram from pre-rendered or on-the-fly ASCII output."""
     w = block.width
@@ -123,20 +177,8 @@ def render(block: Block, color: bool) -> list[str]:
 
     if rendered is None:
         source = block.attrs.get("source", "")
-        try:
-            result = subprocess.run(
-                [mermaid_ascii_bin(), "-f", "-", "-y", "1"],
-                input=preprocess_mermaid_for_ascii(source),
-                capture_output=True,
-                text=True,
-                timeout=30,
-            )
-            rendered = fix_mermaid_encoding(result.stdout)
-        except Exception:
-            rendered = source
-
-    lines: list[str] = []
-    for raw_line in rendered.split("\n"):
-        lines.append(visual_ljust(raw_line, w))
-
-    return lines
+        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.1.0/src/termrender/renderers/mermaid_gantt.py

@@ -0,0 +1,222 @@
+"""Native renderer for mermaid ``gantt`` diagrams.
+
+Mermaid gantt grammar (core subset)::
+
+    gantt
+        title A Gantt Diagram
+        dateFormat YYYY-MM-DD
+        section Section A
+        Task1 :a1, 2024-01-01, 30d
+        Task2 :after a1, 20d
+        section Section B
+        Task3 : 2024-02-01, 2024-02-10
+
+Rendered as section-grouped rows with a horizontal time-span bar per task,
+scaled to the overall date range — the gantt analogue of a timeline, per the
+ratified plan in ``mermaid-inline-rendering.md``.
+"""
+
+from __future__ import annotations
+
+import re
+from datetime import datetime, timedelta
+
+from termrender.style import visual_len, visual_ljust
+
+_HEADER_RE = re.compile(r"^\s*gantt\b", re.IGNORECASE)
+_TITLE_RE = re.compile(r"^\s*title\s+(.*\S)\s*$", re.IGNORECASE)
+_DATEFORMAT_RE = re.compile(r"^\s*dateFormat\s+(\S+)\s*$", re.IGNORECASE)
+_SECTION_RE = re.compile(r"^\s*section\s+(.*\S)\s*$", re.IGNORECASE)
+_SKIP_RE = re.compile(
+    r"^\s*(?:excludes|includes|axisFormat|todayMarker|weekend|tickInterval)\b",
+    re.IGNORECASE,
+)
+_STATUS_TOKENS = {"done", "active", "crit", "milestone", "vert"}
+_DURATION_RE = re.compile(r"^(\d+(?:\.\d+)?)\s*(d|w|h|m|s)$", re.IGNORECASE)
+_ID_RE = re.compile(r"^[A-Za-z_][\w-]*$")
+_UNIT_SECONDS = {"s": 1, "m": 60, "h": 3600, "d": 86400, "w": 604800}
+
+# Mermaid dateFormat tokens, longest-first so e.g. "YYYY" isn't partially
+# consumed by a "YY" replacement first.
+_DATE_TOKEN_MAP = [
+    ("YYYY", "%Y"),
+    ("YY", "%y"),
+    ("MM", "%m"),
+    ("DD", "%d"),
+    ("HH", "%H"),
+    ("mm", "%M"),
+    ("ss", "%S"),
+]
+
+
+def _strptime_format(date_format: str) -> str:
+    """Translate a mermaid ``dateFormat`` token string to a strptime pattern."""
+    out = date_format
+    for token, code in _DATE_TOKEN_MAP:
+        out = out.replace(token, code)
+    return out
+
+
+def _parse_date(token: str, fmt: str) -> datetime | None:
+    try:
+        return datetime.strptime(token, fmt)
+    except ValueError:
+        return None
+
+
+def parse_gantt(source: str) -> dict:
+    """Parse the core mermaid gantt grammar into a title + section/task tree.
+
+    Handles ``dateFormat``, ``title``, ``section``, and task lines of the
+    form ``name : [status,] [id,] [start-date|after id,] duration-or-end``.
+    Lines that don't match a recognized shape (``excludes``, ``axisFormat``,
+    a task with no resolvable start anchor, …) are skipped rather than
+    raising — agents emit a wide variety of gantt dialects and an unparseable
+    line must degrade, not crash.
+
+    Returns ``{"title": str | None, "sections": [{"name": str | None,
+    "tasks": [{"label": str, "start": datetime, "end": datetime}]}]}``.
+    Sections with no successfully parsed tasks are dropped.
+    """
+    fmt = "%Y-%m-%d"
+    title: str | None = None
+    sections: list[dict] = [{"name": None, "tasks": []}]
+    ids: dict[str, datetime] = {}
+    last_end: datetime | None = None
+
+    for line in source.splitlines():
+        if not line.strip() or _HEADER_RE.match(line) or _SKIP_RE.match(line):
+            continue
+
+        m = _TITLE_RE.match(line)
+        if m:
+            title = m.group(1)
+            continue
+
+        m = _DATEFORMAT_RE.match(line)
+        if m:
+            fmt = _strptime_format(m.group(1))
+            continue
+
+        m = _SECTION_RE.match(line)
+        if m:
+            sections.append({"name": m.group(1), "tasks": []})
+            continue
+
+        if ":" not in line:
+            continue
+        label, _, spec = line.partition(":")
+        label = label.strip()
+        if not label:
+            continue
+
+        task_id: str | None = None
+        start: datetime | None = None
+        end: datetime | None = None
+        duration: timedelta | None = None
+        after_ids: list[str] = []
+
+        for raw_tok in spec.split(","):
+            tok = raw_tok.strip()
+            if not tok:
+                continue
+            low = tok.lower()
+            if low in _STATUS_TOKENS:
+                continue
+            if low.startswith("after "):
+                after_ids.extend(tok[len("after "):].split())
+                continue
+            dm = _DURATION_RE.match(tok)
+            if dm:
+                amount, unit = float(dm.group(1)), dm.group(2).lower()
+                duration = timedelta(seconds=amount * _UNIT_SECONDS[unit])
+                continue
+            dt = _parse_date(tok, fmt)
+            if dt is not None:
+                if start is None:
+                    start = dt
+                else:
+                    end = dt
+                continue
+            if task_id is None and _ID_RE.match(tok):
+                task_id = tok
+                continue
+            # Unrecognized token (e.g. an unmapped status keyword): ignore
+            # and keep scanning the remaining tokens on this line.
+
+        if start is None:
+            if after_ids:
+                resolved = [ids[i] for i in after_ids if i in ids]
+                start = max(resolved) if resolved else last_end
+            else:
+                start = last_end
+
+        if start is None:
+            # No date, no "after" dependency, no prior task to anchor to —
+            # this task can't be placed on the timeline. Skip it.
+            continue
+
+        if end is None:
+            end = start + duration if duration is not None else start + timedelta(days=1)
+        if end < start:
+            end = start
+
+        sections[-1]["tasks"].append({"label": label, "start": start, "end": end})
+        last_end = end
+        if task_id:
+            ids[task_id] = end
+
+    sections = [s for s in sections if s["tasks"]]
+    return {"title": title, "sections": sections}
+
+
+def _draw_span(width: int, start_ratio: float, end_ratio: float) -> str:
+    """Draw a ``width``-wide track with a filled span from start to end ratio."""
+    if width <= 0:
+        return ""
+    start_col = max(0, min(int(round(start_ratio * width)), width))
+    end_col = max(start_col + 1, min(int(round(end_ratio * width)), width))
+    return "░" * start_col + "█" * (end_col - start_col) + "░" * (width - end_col)
+
+
+def _fmt_range(task: dict) -> str:
+    start, end = task["start"], task["end"]
+    if start.date() == end.date():
+        return start.strftime("%Y-%m-%d")
+    return f"{start:%Y-%m-%d}\u2192{end:%Y-%m-%d}"
+
+
+def render(source: str, width: int) -> list[str]:
+    """Render mermaid gantt syntax as section-grouped rows with time-span bars.
+
+    Diagrams with no parseable tasks degrade to the raw source text.
+    """
+    parsed = parse_gantt(source)
+    tasks = [t for s in parsed["sections"] for t in s["tasks"]]
+    if not tasks:
+        return source.splitlines() or [""]
+
+    min_start = min(t["start"] for t in tasks)
+    max_end = max(t["end"] for t in tasks)
+    span = (max_end - min_start).total_seconds() or 1.0
+
+    label_w = max(visual_len(t["label"]) for t in tasks)
+    date_w = max(visual_len(_fmt_range(t)) for t in tasks)
+    bar_w = max(width - label_w - date_w - 4, 5)
+
+    lines: list[str] = []
+    if parsed["title"]:
+        lines.append(visual_ljust(parsed["title"], width))
+
+    for section in parsed["sections"]:
+        if section["name"]:
+            lines.append(visual_ljust(section["name"], width))
+        for t in section["tasks"]:
+            start_ratio = (t["start"] - min_start).total_seconds() / span
+            end_ratio = (t["end"] - min_start).total_seconds() / span
+            bar = _draw_span(bar_w, start_ratio, end_ratio)
+            label = visual_ljust(t["label"], label_w)
+            date_str = _fmt_range(t).rjust(date_w)
+            lines.append(visual_ljust(f"{label}  {bar}  {date_str}", width))
+
+    return lines

termrender-4.1.0/src/termrender/renderers/mermaid_pie.py

@@ -0,0 +1,78 @@
+"""Native renderer for mermaid ``pie`` diagrams.
+
+Mermaid pie grammar (subset)::
+
+    pie [showData]
+        title An Optional Title
+        "Label A" : 40
+        "Label B" : 60
+
+A text pie chart is worse than a labeled bar chart at the same information
+density, so pie diagrams are re-expressed as a horizontal bar chart (see the
+ratified plan in ``mermaid-inline-rendering.md``), reusing ``charts.py``'s
+``render_bar`` so the visual style matches the rest of termrender's charts.
+"""
+
+from __future__ import annotations
+
+import re
+
+from termrender.blocks import Block, BlockType
+from termrender.renderers.charts import render_bar
+
+_TITLE_RE = re.compile(r"^\s*title\s+(.*\S)\s*$", re.IGNORECASE)
+_DATA_RE = re.compile(r'^\s*"([^"]*)"\s*:\s*(-?\d+(?:\.\d+)?)\s*$')
+_HEADER_RE = re.compile(r"^\s*pie\b", re.IGNORECASE)
+
+
+def parse_pie(source: str) -> tuple[str | None, list[dict]]:
+    """Parse mermaid pie syntax into ``(title, items)``.
+
+    ``items`` is a list of ``{"label": str, "value": float}`` dicts, in
+    source order. Lines that match neither the header, ``title``, nor a
+    ``"label" : value`` data line are silently skipped — pragmatic parsing
+    per the "never crash" contract, not a full grammar.
+    """
+    title: str | None = None
+    items: list[dict] = []
+    for line in source.splitlines():
+        if not line.strip():
+            continue
+        if _HEADER_RE.match(line):
+            continue
+        m = _TITLE_RE.match(line)
+        if m:
+            title = m.group(1)
+            continue
+        m = _DATA_RE.match(line)
+        if m:
+            items.append({"label": m.group(1), "value": float(m.group(2))})
+    return title, items
+
+
+def render(source: str, width: int) -> list[str]:
+    """Render mermaid pie syntax as a labeled horizontal bar chart.
+
+    Each bar's value is annotated with its percentage share of the total.
+    Diagrams with no parseable data lines degrade to the raw source text.
+    """
+    title, items = parse_pie(source)
+    if not items:
+        return source.splitlines() or [""]
+
+    total = sum(it["value"] for it in items) or 1.0
+    bar_items = [
+        {
+            "label": it["label"],
+            "value": it["value"],
+            "unit": f" ({it['value'] / total * 100:.1f}%)",
+        }
+        for it in items
+    ]
+
+    block = Block(
+        type=BlockType.BAR,
+        attrs={"items": bar_items, "title": title, "color": "cyan"},
+        width=width,
+    )
+    return render_bar(block, color=False)

termrender-4.1.0/tests/test_mermaid_dispatch.py

@@ -0,0 +1,89 @@
+import unittest
+from unittest import mock
+
+from termrender.renderers import mermaid
+
+
+class TestMermaidDispatch(unittest.TestCase):
+    """Routing tests for mermaid.py's first-line type dispatcher.
+
+    These mock the per-type renderers/binary call so they verify *routing*
+    only, independent of the actual rendering logic (covered by
+    test_mermaid_pie.py, test_mermaid_gantt.py, and test_mermaid_compat.py).
+    """
+
+    def test_pie_routes_to_native_pie_renderer(self):
+        with mock.patch(
+            "termrender.renderers.mermaid.mermaid_pie.render", return_value=["PIE"]
+        ) as pie_mock, mock.patch(
+            "termrender.renderers.mermaid._render_via_binary"
+        ) as binary_mock:
+            lines = mermaid.render_mermaid_lines('pie\n    "A" : 1', 40)
+            self.assertEqual(lines, ["PIE"])
+            pie_mock.assert_called_once()
+            binary_mock.assert_not_called()
+
+    def test_gantt_routes_to_native_gantt_renderer(self):
+        with mock.patch(
+            "termrender.renderers.mermaid.mermaid_gantt.render", return_value=["GANTT"]
+        ) as gantt_mock, mock.patch(
+            "termrender.renderers.mermaid._render_via_binary"
+        ) as binary_mock:
+            lines = mermaid.render_mermaid_lines("gantt\n    dateFormat YYYY-MM-DD", 40)
+            self.assertEqual(lines, ["GANTT"])
+            gantt_mock.assert_called_once()
+            binary_mock.assert_not_called()
+
+    def test_graph_routes_to_binary_fallback(self):
+        with mock.patch(
+            "termrender.renderers.mermaid._render_via_binary", return_value="RENDERED"
+        ) as binary_mock:
+            lines = mermaid.render_mermaid_lines("graph LR\nA-->B", 40)
+            self.assertEqual(lines, ["RENDERED"])
+            binary_mock.assert_called_once()
+
+    def test_flowchart_routes_to_binary_fallback(self):
+        with mock.patch(
+            "termrender.renderers.mermaid._render_via_binary", return_value="RENDERED"
+        ) as binary_mock:
+            mermaid.render_mermaid_lines("flowchart TD\nA-->B", 40)
+            binary_mock.assert_called_once()
+
+    def test_sequence_routes_to_binary_fallback(self):
+        with mock.patch(
+            "termrender.renderers.mermaid._render_via_binary", return_value="RENDERED"
+        ) as binary_mock:
+            mermaid.render_mermaid_lines("sequenceDiagram\n    A->>B: hi", 40)
+            binary_mock.assert_called_once()
+
+    def test_unsupported_type_routes_to_binary_fallback(self):
+        for source in (
+            "classDiagram\n    Animal <|-- Duck",
+            "stateDiagram-v2\n    [*] --> Idle",
+            "erDiagram\n    A ||--o{ B : has",
+            "journey\n    title My journey",
+            "mindmap\n  root",
+        ):
+            with mock.patch(
+                "termrender.renderers.mermaid._render_via_binary", return_value="X"
+            ) as binary_mock:
+                mermaid.render_mermaid_lines(source, 40)
+                binary_mock.assert_called_once()
+
+    def test_type_sniff_is_case_insensitive(self):
+        with mock.patch(
+            "termrender.renderers.mermaid.mermaid_pie.render", return_value=["PIE"]
+        ) as pie_mock:
+            mermaid.render_mermaid_lines('PIE\n    "A" : 1', 40)
+            pie_mock.assert_called_once()
+
+    def test_type_sniff_skips_leading_blank_lines(self):
+        with mock.patch(
+            "termrender.renderers.mermaid.mermaid_gantt.render", return_value=["G"]
+        ) as gantt_mock:
+            mermaid.render_mermaid_lines("\n\n   gantt\n    dateFormat YYYY-MM-DD", 40)
+            gantt_mock.assert_called_once()
+
+
+if __name__ == "__main__":
+    unittest.main()

termrender-4.1.0/tests/test_mermaid_gantt.py

@@ -0,0 +1,154 @@
+import unittest
+from datetime import datetime
+
+from termrender import render
+from termrender.renderers.mermaid_gantt import parse_gantt, render as render_gantt
+from termrender.style import visual_len
+
+
+class TestParseGantt(unittest.TestCase):
+
+    def test_parses_title_and_dateformat(self):
+        src = "gantt\n    title Release Plan\n    dateFormat YYYY-MM-DD\n    Task1 :2024-01-01, 5d"
+        parsed = parse_gantt(src)
+        self.assertEqual(parsed["title"], "Release Plan")
+
+    def test_start_date_plus_duration(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    Task1 :2024-01-01, 5d"
+        parsed = parse_gantt(src)
+        task = parsed["sections"][0]["tasks"][0]
+        self.assertEqual(task["start"], datetime(2024, 1, 1))
+        self.assertEqual(task["end"], datetime(2024, 1, 6))
+
+    def test_two_explicit_dates(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    Task1 :2024-01-01, 2024-01-10"
+        parsed = parse_gantt(src)
+        task = parsed["sections"][0]["tasks"][0]
+        self.assertEqual(task["start"], datetime(2024, 1, 1))
+        self.assertEqual(task["end"], datetime(2024, 1, 10))
+
+    def test_after_dependency_chains_from_prior_task(self):
+        src = (
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    Task1 :a1, 2024-01-01, 5d\n"
+            "    Task2 :after a1, 3d\n"
+        )
+        parsed = parse_gantt(src)
+        tasks = parsed["sections"][0]["tasks"]
+        self.assertEqual(tasks[1]["start"], datetime(2024, 1, 6))
+        self.assertEqual(tasks[1]["end"], datetime(2024, 1, 9))
+
+    def test_sections_grouped(self):
+        src = (
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    section Design\n"
+            "    Spec :2024-01-01, 5d\n"
+            "    section Build\n"
+            "    Implement :2024-01-10, 5d\n"
+        )
+        parsed = parse_gantt(src)
+        names = [s["name"] for s in parsed["sections"]]
+        self.assertEqual(names, ["Design", "Build"])
+
+    def test_status_tokens_ignored(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    Task1 :done, crit, 2024-01-01, 5d"
+        parsed = parse_gantt(src)
+        task = parsed["sections"][0]["tasks"][0]
+        self.assertEqual(task["start"], datetime(2024, 1, 1))
+
+    def test_unresolvable_task_skipped_not_crashed(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    NoAnchor :after nonexistent, 5d"
+        parsed = parse_gantt(src)
+        self.assertEqual(parsed["sections"], [])
+
+    def test_excludes_and_axisformat_ignored(self):
+        src = (
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    excludes weekends\n"
+            "    axisFormat %m/%d\n"
+            "    Task1 :2024-01-01, 5d\n"
+        )
+        parsed = parse_gantt(src)
+        self.assertEqual(len(parsed["sections"][0]["tasks"]), 1)
+
+    def test_garbage_line_does_not_crash(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    this has no colon\n    Task1 :2024-01-01, 5d"
+        parsed = parse_gantt(src)
+        self.assertEqual(len(parsed["sections"][0]["tasks"]), 1)
+
+    def test_custom_dateformat(self):
+        src = "gantt\n    dateFormat DD/MM/YYYY\n    Task1 :01/02/2024, 5d"
+        parsed = parse_gantt(src)
+        task = parsed["sections"][0]["tasks"][0]
+        self.assertEqual(task["start"], datetime(2024, 2, 1))
+
+
+class TestRenderGantt(unittest.TestCase):
+
+    def test_renders_bars_for_each_task(self):
+        src = (
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    Task1 :2024-01-01, 5d\n"
+            "    Task2 :2024-01-06, 5d\n"
+        )
+        lines = render_gantt(src, width=70)
+        joined = "\n".join(lines)
+        self.assertIn("Task1", joined)
+        self.assertIn("Task2", joined)
+        self.assertIn("█", joined)
+        self.assertIn("░", joined)
+
+    def test_section_headers_appear(self):
+        src = (
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    section Design\n"
+            "    Spec :2024-01-01, 5d\n"
+        )
+        lines = render_gantt(src, width=70)
+        self.assertTrue(any("Design" in ln for ln in lines))
+
+    def test_no_tasks_degrades_to_source(self):
+        src = "gantt\n    title nothing here\n"
+        lines = render_gantt(src, width=40)
+        self.assertEqual(lines, src.splitlines())
+
+    def test_no_ansi_when_monochrome(self):
+        src = "gantt\n    dateFormat YYYY-MM-DD\n    Task1 :2024-01-01, 5d"
+        lines = render_gantt(src, width=40)
+        self.assertNotIn("\x1b[", "\n".join(lines))
+
+    def test_full_pipeline_renders_gantt(self):
+        src = (
+            "```mermaid\n"
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    section Build\n"
+            "    Implement :2024-01-01, 10d\n"
+            "```"
+        )
+        out = render(src, width=60, color=False)
+        self.assertIn("Build", out)
+        self.assertIn("Implement", out)
+        self.assertIn("█", out)
+
+    def test_full_pipeline_widths_match(self):
+        src = (
+            "```mermaid\n"
+            "gantt\n"
+            "    dateFormat YYYY-MM-DD\n"
+            "    Task1 :2024-01-01, 5d\n"
+            "```"
+        )
+        out = render(src, width=55, color=False)
+        for ln in out.split("\n"):
+            if ln:
+                self.assertEqual(visual_len(ln), 55)
+
+
+if __name__ == "__main__":
+    unittest.main()

termrender-4.1.0/tests/test_mermaid_pie.py

@@ -0,0 +1,92 @@
+import unittest
+
+from termrender import render
+from termrender.renderers.mermaid_pie import parse_pie, render as render_pie
+from termrender.style import visual_len
+
+
+class TestParsePie(unittest.TestCase):
+
+    def test_parses_labels_and_values(self):
+        src = 'pie\n    "Bugs" : 40\n    "Features" : 60'
+        title, items = parse_pie(src)
+        self.assertIsNone(title)
+        self.assertEqual(items, [
+            {"label": "Bugs", "value": 40.0},
+            {"label": "Features", "value": 60.0},
+        ])
+
+    def test_parses_title(self):
+        src = "pie\n    title Key Findings\n"
+        title, items = parse_pie(src)
+        self.assertEqual(title, "Key Findings")
+
+    def test_show_data_flag_ignored(self):
+        src = 'pie showData\n    "A" : 1\n    "B" : 2'
+        title, items = parse_pie(src)
+        self.assertEqual(len(items), 2)
+
+    def test_float_values(self):
+        src = 'pie\n    "A" : 12.5\n    "B" : 87.5'
+        _, items = parse_pie(src)
+        self.assertEqual(items[0]["value"], 12.5)
+
+    def test_unparseable_lines_skipped(self):
+        src = 'pie\n    this is not a data line\n    "A" : 5'
+        _, items = parse_pie(src)
+        self.assertEqual(items, [{"label": "A", "value": 5.0}])
+
+    def test_empty_pie_yields_no_items(self):
+        _, items = parse_pie("pie\n")
+        self.assertEqual(items, [])
+
+
+class TestRenderPie(unittest.TestCase):
+
+    def test_renders_bars_with_percentages(self):
+        src = 'pie\n    "Bugs" : 40\n    "Features" : 60'
+        lines = render_pie(src, width=60)
+        joined = "\n".join(lines)
+        self.assertIn("Bugs", joined)
+        self.assertIn("Features", joined)
+        self.assertIn("40.0%", joined)
+        self.assertIn("60.0%", joined)
+        self.assertIn("█", joined)
+
+    def test_largest_value_gets_full_bar(self):
+        src = 'pie\n    "A" : 100\n    "B" : 50'
+        lines = render_pie(src, width=60)
+        self.assertIn("█" * 10, lines[0])  # line for A should be mostly full
+
+    def test_title_rendered_above_bars(self):
+        src = 'pie\n    title My Title\n    "A" : 1'
+        lines = render_pie(src, width=40)
+        self.assertIn("My Title", lines[0])
+
+    def test_no_data_degrades_to_source(self):
+        src = "pie\n"
+        lines = render_pie(src, width=40)
+        self.assertEqual(lines, ["pie"])
+
+    def test_no_ansi_when_monochrome(self):
+        src = 'pie\n    "A" : 1\n    "B" : 2'
+        lines = render_pie(src, width=40)
+        self.assertNotIn("\x1b[", "\n".join(lines))
+
+    def test_full_pipeline_renders_pie(self):
+        src = '```mermaid\npie\n    title Findings\n    "Bugs" : 40\n    "Docs" : 60\n```'
+        out = render(src, width=60, color=False)
+        self.assertIn("Findings", out)
+        self.assertIn("Bugs", out)
+        self.assertIn("█", out)
+
+    def test_full_pipeline_widths_match(self):
+        src = '```mermaid\npie\n    "A" : 1\n    "B" : 2\n```'
+        out = render(src, width=50, color=False)
+        for ln in out.split("\n"):
+            if ln:
+                self.assertEqual(visual_len(ln), 50)
+
+
+if __name__ == "__main__":
+    unittest.main()

termrender-4.0.0/src/termrender/renderers/CLAUDE.md

@@ -1,58 +0,0 @@
-# Renderers
-
-## Renderer signature convention
-Two signatures exist — not enforced by typing, but the dispatcher expects them:
-- **Leaf renderers** (`divider.py`, `tree.py`): `render(block, color) -> list[str]`
-- **Container renderers** (`panel.py`, `quote.py`, `code.py`, `columns.py`): `render(block, color, render_child) -> list[str]`
-
-`render_child` is the engine's dispatch function; call it to recurse into child blocks rather than calling sibling renderers directly.
-
-## `render_box` — width is total, not content
-`borders.py:render_box(content_lines, width, ...)` — `width` is the **full** box width including the two `│` border columns. Content width is `width - 2*border_v - 2` (border + 1-space padding each side). Passing inner/content width here produces double-shrinkage.
-
-Used by `panel.py` and `code.py` (with `dim=True`).
-
-If `content_lines` is empty, `render_box` inserts one blank interior line — output is always ≥ 3 lines (top border + 1 blank + bottom border). Callers computing expected height from content line count must add 3, not 2.
-
-When `title` is provided, it is **left-anchored**, not centered: `┌─ TITLE ───┐`. The format is `"─ " + title + " "` flush-left, then fill dashes to `┐`. There is no API for a right-anchored or centered title.
-
-## EAW-dynamic guide characters in `tree.py`
-`_guide_chars()` is called at render time (not module init) because `visual_len("├── ")` differs under East Asian Width ambiguous=2 mode. Under that setting `"│"` is width 2 while `"─"` is width 1, so the four guide prefixes have inconsistent visual widths. `_guide_chars()` normalizes all four to the visual width of `"├── "` at runtime, picking up whatever EAW setting is active. The same EAW issue drives the dynamic `border_v`/`dash_v` math in `render_box`.
-
-## `tree.py` — source goes in `attrs["source"]`, indent is auto-detected
-Tree content comes from `block.attrs["source"]` (a raw multi-line string), not `block.text` or `block.children`. `_detect_indent` sniffs the first indented line: returns 2 for ≤2 spaces, the raw value for 3–4 spaces, and clamps to 4 for anything larger. A tree where the first sniffed indent is 5 or 6 spaces gets clamped to 4 — subsequent lines compute `depth = spaces // 4`, skipping depth levels silently (e.g. 6-space children land at depth 1, but 12-space grandchildren land at depth 3, not 2). `[x]` and `[!]` status markers in labels are replaced with styled Unicode symbols; `**bold**` and `*italic*` inline markdown is also parsed.
-
-Depth-0 items (no leading spaces) render with no guide prefix at all — a flat source is a plain list, no tree lines.
-
-`block.attrs["color"]` sets the guide-line color (the `├──` connectors); it is distinct from the `color: bool` render parameter and only styles guides, not labels.
-
-## `divider.py` — always dim, no color path
-`render()` hardcodes `dim=True`; there is no way to pass a custom color through the leaf signature. A colored divider requires a different renderer or direct `render_box` usage.
-
-Optional centered label comes from `block.attrs["label"]` (not `block.text`). `visual_center(inner, w, "─")` handles the fill — the label is padded as `" {label} "` before centering, so the label always has at least one space of breathing room from the surrounding dashes.
-
-## `quote.py` — dual attribution keys; EAW-sensitive bar width
-Attribution line is rendered for `block.attrs["author"]` **or** `block.attrs["by"]`; `"author"` takes precedence. Missing both suppresses the attribution line entirely.
-
-`bar_width = visual_len("│") + 1` — under EAW ambiguous=2, `"│"` is width 2 so `bar_width` becomes 3, shrinking `inner_w` by one extra column relative to default EAW. The bar itself is correct visually, but layout that pre-computes quote inner width assuming `bar_width == 2` will be off by 1 under EAW=2.
-
-## `panel.py` — callouts delegate through a proxy Block
-`render_callout` patches `title`, `color`, and `type=BlockType.PANEL` into a new `Block` instance and calls `render()` on it. The original block is not mutated. The callout type string (`"info"`, `"warning"`, `"error"`, `"success"`) is only used to look up `_CALLOUT_MAP`; an unknown type falls back to blue `ℹ`.
-
-## `mermaid.py` — leaf signature (not container), encoding fix, no returncode check, no truncation
-
-**Leaf signature, not container**: `render(block, color)` — no `render_child`. The parent `CLAUDE.md` incorrectly lists mermaid as a Container renderer.
-
-**`fix_mermaid_encoding`**: `mermaid-ascii` misreads UTF-8 input as Latin-1 and re-encodes, corrupting multi-byte characters (e.g. `→` becomes `â\x86\x92`). The fix is `text.encode("latin-1").decode("utf-8")`; on failure it silently returns the corrupted string — callers cannot distinguish fixed vs. corrupt output.
-
-**`except Exception` swallows everything**: timeout, missing tool, `MemoryError` — all fall back to `rendered = source` (the raw mermaid source text) silently. Returncode is also never checked; a non-zero exit still reads `result.stdout`, producing a blank-line block if stdout was empty. If both `_rendered` and `source` are absent, empty string is sent to `mermaid-ascii`.
-
-**`visual_ljust` pads but never truncates**: every output line is padded to `block.width`. Lines wider than `block.width` overflow without clipping. If `mermaid-ascii` emits a diagram wider than the allocated block, it silently exceeds the layout boundary.
-
-**Trailing blank line**: `rendered.split("\n")` on output ending with `\n` (typical subprocess output) produces a trailing empty string, which becomes a `block.width`-wide blank line appended to every mermaid block.
-
-Layout pre-renders into `block.attrs["_rendered"]` (see `src/termrender/CLAUDE.md`); this renderer re-runs the subprocess only when that key is absent.
-
-**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 & no width flag**: 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-ascii` has no width-control flag** (never has — `--maxWidth`/`-w` do not exist); the call passes only `-f - -y 1`, so `block.width` does not constrain the diagram and wide output overflows (compounding the no-truncation gotcha above). A labeled back-edge (`X -->|lbl| Y` in `graph LR`) panics the binary on **both** 1.2.0 and master; the non-zero exit is caught and the block degrades to raw source.