termrender 4.2.0__tar.gz → 4.3.0__tar.gz

{termrender-4.2.0 → termrender-4.3.0}/CHANGELOG.md

@@ -1,6 +1,34 @@
 # CHANGELOG
 
 
+## v4.3.0 (2026-07-06)
+
+### Features
+
+- Add flowchart renderer data model
+  ([`cf3caef`](https://github.com/crouton-labs/termrender/commit/cf3caef28411d2ace3f71c63f218af52ba460da0))
+
+- Wire sequence renderer and add native mindmap/journey/timeline renderers
+  ([`120b51c`](https://github.com/crouton-labs/termrender/commit/120b51cddf58cd91ee948706c143c84ca42c7e9f))
+
+- mermaid.py dispatch now routes sequenceDiagram to the finished mermaid_sequence.render_sequence,
+  and mindmap/journey/timeline to new native renderers, leaving flowchart/graph/class/state/ER on
+  the vendored Go binary path unchanged. - New shared mermaid_prelude.strip_prelude_lines skips
+  leading %% comments, %%{init}%% directives, and --- YAML frontmatter before sniffing a diagram's
+  type keyword, fixing valid diagrams with those preludes mis-routing to the binary fallback.
+  mermaid_sequence.py's own header guard uses the same helper. - mermaid_mindmap.py:
+  indentation-based mindmap source maps directly onto tree.py's shape; strips the mindmap header,
+  ::icon()/:::class decoration, and node-shape delimiters down to label text. - mermaid_journey.py:
+  section/task outline mapped onto tree.py, tasks rendered as depth-1 children with a star rating
+  and actor list. - mermaid_timeline.py: sections rendered as separate timeline.py sub-timelines,
+  with period-less continuation lines correctly attaching to the previous row instead of repeating
+  the date. - Dispatch integration tests for every new route plus all three prelude forms; parse +
+  golden-output render tests per new module. - CLAUDE.md updated to describe the current
+  dispatch/prelude state.
+
+Full suite: 230 -> 292 tests, all green.
+
+
 ## v4.2.0 (2026-07-06)
 
 ### Bug Fixes

{termrender-4.2.0 → termrender-4.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.2.0
+Version: 4.3.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.2.0 → termrender-4.3.0}/src/termrender/renderers/CLAUDE.md

@@ -43,11 +43,13 @@ 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 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.
+**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.
 
-**`_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.
+**`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.
 
-**`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.
+**`_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.
 
 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).
 
@@ -66,3 +68,19 @@ A text pie chart is worse than a labeled bar chart at the same information densi
 **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.
+
+## `mermaid_sequence.py` — deterministic column layout, no graph-layout search
+
+The one native renderer not built by reusing another primitive (there's no existing "sequence diagram" shape in termrender to reuse) — `render_sequence(source, width)` is a standalone module with its own parser (`_parse`, producing `Arrow`/`NoteEvent`/`BlockBoundary`/`PlainLabel` events) and its own column-layout pass (`_layout_columns`, a 1D constraint solve: message order already fixes the vertical axis, declaration order fixes the column axis, so gaps between adjacent columns are widened only enough for whatever message text crosses them). `width` is advisory-only and never wraps/truncates — sequence diagrams have intrinsic width and may overflow, same contract as the flowchart binary path. Parsing never raises except when the source isn't a sequence diagram at all (checked via `mermaid_prelude.strip_prelude_lines` against the first real line); every malformed/unrecognized construct within a real sequence diagram (a stray `else`/`end`, an unsupported arrow punctuation, a flowchart-only `-.->`) degrades to a plain text line instead. See the module's own docstring for the full grammar supported and known degradations (CJK column misalignment, `Note` multi-participant simplification, etc.).
+
+## `mermaid_mindmap.py` — mindmap source is already `tree.py`'s shape
+
+Mindmap is indentation-based exactly like `tree.py`'s input format, so `parse_mindmap` does no layout of its own: it drops the `mindmap` header line and `::icon(...)`/`:::className` decoration lines, strips each node's shape delimiters (`(())`, `{{}}`, `))((`, `)(`, `[]`, `()`, checked most-specific-first the same way `mermaid.py`'s `_FLOWCHART_SHAPE_SUBS` is ordered) down to label text, and preserves each surviving line's original leading whitespace verbatim — depth then falls out of `tree.py`'s own indentation auto-detection for free. `render` hands the transformed text to `tree.py::render` via a synthetic `Block(type=BlockType.TREE, ...)`, always `color=False`. A diagram with nothing left after stripping (blank, or header-only) degrades to the raw source lines.
+
+## `mermaid_journey.py` — section/task outline mapped onto `tree.py`
+
+A journey is a two-level outline (`section` → tasks), so `parse_journey` splits `name: score: actors` task lines (tolerating a missing/non-numeric score as `None` and missing actors as `[]`, never raising) into section buckets — a task before any `section` line lands in a leading unnamed bucket, matching `mermaid_gantt.py`'s same convention. `render` builds one synthetic indented-tree source string (section names at depth 0, `_format_task` output — `name  ★★★☆☆  (actors)`, stars clamped to the 0–5 range — as depth-1 children under a two-space indent) and renders it through `tree.py::render` via a synthetic `Block`, same pattern as mindmap. The diagram title (if any) is a plain line prepended above the tree, not part of it. Sections with no tasks are dropped; zero surviving sections degrades to the raw source lines.
+
+## `mermaid_timeline.py` — sections rendered as separate `timeline.py` sub-timelines
+
+`parse_timeline` handles `title`, `section`, and `period : event[ : event ...]` lines; a period-less line (blank before the first `:`) continues the *previous* row's period rather than introducing a new one — tracked via a `shows_date` flag so only the row that actually introduces a period (same-line or most recent prior line) prints it, everything else in that group prints a blank date column for alignment. `render` calls `timeline.py::render` once per section (each section's `entries` in a synthetic `Block(type=BlockType.TIMELINE, ...)`), inserting the section name as its own plain row above each sub-timeline and a blank separator row between sections — reuses the existing bullet/connector rendering rather than a bespoke one. A diagram with zero resolved entries degrades to the raw source lines.

{termrender-4.2.0 → termrender-4.3.0}/src/termrender/renderers/mermaid.py

@@ -7,7 +7,15 @@ 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.renderers import (
+    mermaid_gantt,
+    mermaid_journey,
+    mermaid_mindmap,
+    mermaid_pie,
+    mermaid_sequence,
+    mermaid_timeline,
+)
+from termrender.renderers.mermaid_prelude import strip_prelude_lines
 from termrender.style import visual_ljust
 
 
@@ -118,13 +126,16 @@ def preprocess_mermaid_for_ascii(source: str) -> str:
 
 
 def _first_line_type(source: str) -> str:
-    """Return the lowercased first non-blank line's leading keyword.
+    """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``, …). Returns ``""`` for an empty/blank source.
+    ``classDiagram``, …), 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.
     """
-    first = next((l.strip() for l in source.splitlines() if l.strip()), "")
+    lines = strip_prelude_lines(source.splitlines())
+    first = next((l.strip() for l in lines if l.strip()), "")
     return first.lower()
 
 
@@ -156,17 +167,26 @@ def _render_via_binary(source: str) -> str:
 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.
+    ``pie``, ``gantt``, ``sequenceDiagram``, ``mindmap``, ``journey``, and
+    ``timeline`` get dedicated native Python renderers. Every other type
+    (flowchart/graph, class, state, ER, …) 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)
+    if diagram_type.startswith("sequencediagram"):
+        return mermaid_sequence.render_sequence(source, width)
+    if diagram_type.startswith("mindmap"):
+        return mermaid_mindmap.render(source, width)
+    if diagram_type.startswith("journey"):
+        return mermaid_journey.render(source, width)
+    if diagram_type.startswith("timeline"):
+        return mermaid_timeline.render(source, width)
     return _render_via_binary(source).split("\n")
 
 

termrender-4.3.0/src/termrender/renderers/mermaid_flow_model.py

@@ -0,0 +1,127 @@
+"""Data model for the native mermaid flowchart/graph renderer.
+
+Pure dataclasses + enums, zero logic — the contract between the parser
+(``mermaid_flow_parser.py``, source → :class:`FlowGraph`) and the layout
+engine (``mermaid_flow_layout.py``, :class:`FlowGraph` → char grid). Neither
+side imports the other; both import this module. Nothing here has behavior.
+
+Model shape
+-----------
+A :class:`FlowGraph` carries a :class:`Direction`, a declaration-ordered
+list of unique :class:`FlowNode` (id is the graph key, label is the drawn
+text), a declaration-ordered list of :class:`FlowEdge` with ``&`` fan-out
+already expanded to individual edges, and the top-level :class:`Subgraph`
+blocks (nesting via ``Subgraph.children``). Arrowheads are two per-endpoint
+booleans (``dst_arrow``/``src_arrow``) independent of the line
+:class:`EdgeStyle`. Ignored source directives (class/classDef/style/click/
+linkStyle) leave no trace in the model — the parser drops them.
+
+See ``flow-design.md`` (this node's orchestrator context dir) for the full
+architecture and the decisions baked into these shapes.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+
+__all__ = [
+    "Direction",
+    "NodeShape",
+    "EdgeStyle",
+    "FlowNode",
+    "FlowEdge",
+    "Subgraph",
+    "FlowGraph",
+]
+
+
+class Direction(Enum):
+    """Rank-flow direction. ``TD`` is a mermaid alias for ``TB`` and is
+    normalized to ``TB`` by the parser (never stored as a separate member)."""
+
+    TB = "TB"  # top → bottom
+    LR = "LR"  # left → right
+    RL = "RL"  # right → left
+    BT = "BT"  # bottom → top
+
+
+class NodeShape(Enum):
+    """Declared node shape. The engine renders ``DIAMOND``, ``ROUND``/
+    ``STADIUM`` (rounded corners) and ``CIRCLE`` distinctly where cheap; every
+    other shape falls back to a rectangle border. Only the shape class + label
+    text are load-bearing."""
+
+    RECT = "rect"                    # [text]
+    ROUND = "round"                  # (text)
+    STADIUM = "stadium"              # ([text])
+    SUBROUTINE = "subroutine"        # [[text]]
+    CYLINDER = "cylinder"            # [(text)]
+    CIRCLE = "circle"                # ((text))
+    DIAMOND = "diamond"              # {text}
+    HEXAGON = "hexagon"              # {{text}}
+    PARALLELOGRAM = "parallelogram"  # [/text/]
+
+
+class EdgeStyle(Enum):
+    """Edge line style. Arrowheads are orthogonal to style (see
+    :class:`FlowEdge`)."""
+
+    SOLID = "solid"    # --- / -->
+    THICK = "thick"    # === / ==>
+    DOTTED = "dotted"  # -.- / -.->
+
+
+@dataclass
+class FlowNode:
+    """A graph node. ``id`` is the graph key (dedup + edge endpoints);
+    ``label`` is the drawn text. Bare ``A`` yields ``id == label == "A"``.
+    Re-declaring an id keeps the first-seen node; a later declaration that
+    carries a shape/label updates it in place (parser policy)."""
+
+    id: str
+    label: str
+    shape: NodeShape = NodeShape.RECT
+
+
+@dataclass
+class FlowEdge:
+    """A directed edge between node ids. ``dst_arrow``/``src_arrow`` are the
+    drawn arrowheads: ``-->`` → dst_arrow=True, src_arrow=False; ``---`` → both
+    False (plain line); ``<-->`` → both True. ``label`` is the optional edge
+    label (``|text|`` or the ``-- text -->`` inline form); ``None`` when absent
+    (empty-string labels are stored as ``None``)."""
+
+    src: str
+    dst: str
+    style: EdgeStyle = EdgeStyle.SOLID
+    label: str | None = None
+    dst_arrow: bool = True
+    src_arrow: bool = False
+
+
+@dataclass
+class Subgraph:
+    """A ``subgraph id [title] ... end`` block. ``node_ids`` are the ids
+    declared directly inside this block (NOT those inside nested children).
+    ``children`` are nested subgraphs. ``title`` is the display title (defaults
+    to id when the block has no explicit title)."""
+
+    id: str
+    title: str
+    node_ids: list[str] = field(default_factory=list)
+    children: list["Subgraph"] = field(default_factory=list)
+
+
+@dataclass
+class FlowGraph:
+    """Parsed flowchart. ``nodes`` is in first-seen declaration order, unique
+    by id. ``edges`` is in declaration order, with ``&`` fan-out already
+    expanded to individual edges. ``subgraphs`` are the top-level blocks
+    (nesting via ``Subgraph.children``). Ignored lines (class/classDef/style/
+    click/linkStyle) leave no trace."""
+
+    direction: Direction
+    nodes: list[FlowNode] = field(default_factory=list)
+    edges: list[FlowEdge] = field(default_factory=list)
+    subgraphs: list[Subgraph] = field(default_factory=list)

termrender-4.3.0/src/termrender/renderers/mermaid_journey.py

@@ -0,0 +1,121 @@
+"""Native renderer for mermaid ``journey`` diagrams.
+
+Mermaid journey grammar (subset)::
+
+    journey
+        title My working day
+        section Go to work
+          Make tea: 5: Me
+          Go upstairs: 3: Me
+          Do work: 1: Me, Cat
+        section Go home
+          Go downstairs: 5: Me
+
+Each section is a group of tasks; each task is ``name: score: actors``
+(``actors`` a comma-separated list, ``score`` a 1-5 satisfaction rating).
+A journey is a two-level outline (section -> tasks) — the same shape
+``tree.py`` renders — so sections become depth-0 tree labels and tasks
+become their depth-1 children, reusing ``tree.py``'s guide-line rendering
+via a synthetic ``Block`` rather than duplicating it (mirrors how
+``mermaid_pie.py`` reuses ``charts.py``'s ``render_bar``).
+"""
+
+from __future__ import annotations
+
+import re
+
+from termrender.blocks import Block, BlockType
+from termrender.renderers.tree import render as render_tree
+from termrender.style import visual_ljust
+
+_HEADER_RE = re.compile(r"^\s*journey\b", re.IGNORECASE)
+_TITLE_RE = re.compile(r"^\s*title\s+(.*\S)\s*$", re.IGNORECASE)
+_SECTION_RE = re.compile(r"^\s*section\s+(.*\S)\s*$", re.IGNORECASE)
+
+
+def parse_journey(source: str) -> dict:
+    """Parse mermaid journey syntax into a title + section/task tree.
+
+    Task lines with fewer than two ``:``-separated fields (no score) are
+    still captured with ``score=None``; a non-numeric score is likewise
+    tolerated (``score=None``) rather than raising. A task line before any
+    ``section`` header lands in an unnamed leading section. Sections with
+    no tasks are dropped.
+
+    Returns ``{"title": str | None, "sections": [{"name": str | None,
+    "tasks": [{"name": str, "score": int | None, "actors": list[str]}]}]}``.
+    """
+    title: str | None = None
+    sections: list[dict] = [{"name": None, "tasks": []}]
+
+    for line in source.splitlines():
+        if not line.strip() or _HEADER_RE.match(line):
+            continue
+
+        m = _TITLE_RE.match(line)
+        if m:
+            title = m.group(1)
+            continue
+
+        m = _SECTION_RE.match(line)
+        if m:
+            sections.append({"name": m.group(1), "tasks": []})
+            continue
+
+        if ":" not in line:
+            continue
+        parts = line.split(":", 2)
+        name = parts[0].strip()
+        if not name:
+            continue
+        score: int | None = None
+        actors: list[str] = []
+        if len(parts) >= 2:
+            score_str = parts[1].strip()
+            if score_str.lstrip("-").isdigit():
+                score = int(score_str)
+        if len(parts) >= 3:
+            actors = [a.strip() for a in parts[2].split(",") if a.strip()]
+        sections[-1]["tasks"].append({"name": name, "score": score, "actors": actors})
+
+    sections = [s for s in sections if s["tasks"]]
+    return {"title": title, "sections": sections}
+
+
+def _format_task(task: dict) -> str:
+    """Render one task as ``name  \u2605\u2605\u2605\u2606\u2606  (actor, actor)``."""
+    label = task["name"]
+    if task["score"] is not None:
+        filled = max(0, min(5, task["score"]))
+        stars = "\u2605" * filled + "\u2606" * (5 - filled)
+        label = f"{label}  {stars}"
+    if task["actors"]:
+        label = f"{label}  ({', '.join(task['actors'])})"
+    return label
+
+
+def render(source: str, width: int) -> list[str]:
+    """Render mermaid journey syntax as a section/task guide-line tree.
+
+    A diagram with no parseable tasks degrades to the raw source text.
+    """
+    parsed = parse_journey(source)
+    sections = parsed["sections"]
+    if not sections:
+        return source.splitlines() or [""]
+
+    lines: list[str] = []
+    if parsed["title"]:
+        lines.append(visual_ljust(parsed["title"], width))
+
+    tree_lines: list[str] = []
+    for section in sections:
+        if section["name"]:
+            tree_lines.append(section["name"])
+            tree_lines.extend(f"  {_format_task(t)}" for t in section["tasks"])
+        else:
+            tree_lines.extend(_format_task(t) for t in section["tasks"])
+
+    block = Block(type=BlockType.TREE, attrs={"source": "\n".join(tree_lines)}, width=width)
+    lines.extend(render_tree(block, color=False))
+    return lines

termrender-4.3.0/src/termrender/renderers/mermaid_mindmap.py

@@ -0,0 +1,99 @@
+"""Native renderer for mermaid ``mindmap`` diagrams.
+
+Mermaid mindmap grammar (subset)::
+
+    mindmap
+      root((mindmap))
+        Origins
+          Long history
+          ::icon(fa fa-book)
+        Research
+          On effectiveness<br/>and features
+        Tools
+          Pen and paper
+
+Mindmap source is *already* an indentation-based tree — the same shape
+``tree.py`` renders — so this module does no layout of its own: it strips
+mermaid-only decoration (the ``mindmap`` header, node-shape delimiters,
+``::icon(...)`` and ``:::className`` lines) down to plain indented labels
+and hands the result to ``tree.py`` via a synthetic ``Block``, reusing its
+guide-line rendering rather than duplicating it (mirrors how
+``mermaid_pie.py`` reuses ``charts.py``'s ``render_bar``).
+"""
+
+from __future__ import annotations
+
+import re
+
+from termrender.blocks import Block, BlockType
+from termrender.renderers.tree import render as render_tree
+
+_HEADER_RE = re.compile(r"^\s*mindmap\b", re.IGNORECASE)
+_ICON_RE = re.compile(r"^::icon\(", re.IGNORECASE)
+_CLASS_RE = re.compile(r"^:::")
+_BR_RE = re.compile(r"<br\s*/?>", re.IGNORECASE)
+
+# Node-shape wrappers, most-specific delimiter pair first so a greedy
+# shorter pattern doesn't bite off half of a longer one (mirrors the
+# ordering discipline in mermaid.py's ``_FLOWCHART_SHAPE_SUBS``). The
+# leading ``\w*`` is an optional node id, discarded — only ever the label
+# text is displayed.
+_NODE_SHAPE_RES: list[re.Pattern[str]] = [
+    re.compile(r"^(\w*)\)\)(.+)\(\($"),  # bang: id))text((
+    re.compile(r"^(\w*)\(\((.+)\)\)$"),  # circle: id((text))
+    re.compile(r"^(\w*)\{\{(.+)\}\}$"),  # hexagon: id{{text}}
+    re.compile(r"^(\w*)\[(.+)\]$"),  # square: id[text]
+    re.compile(r"^(\w*)\((.+)\)$"),  # rounded: id(text)
+    re.compile(r"^(\w*)\)(.+)\($"),  # cloud: id)text(
+]
+
+
+def _node_label(text: str) -> str:
+    """Strip a mindmap node's shape delimiters, keeping only its label.
+
+    A bare word with no shape (the common case) matches nothing and is
+    returned unchanged.
+    """
+    for pattern in _NODE_SHAPE_RES:
+        m = pattern.match(text)
+        if m:
+            return _BR_RE.sub(" / ", m.group(2).strip())
+    return _BR_RE.sub(" / ", text)
+
+
+def parse_mindmap(source: str) -> str:
+    """Parse mermaid mindmap syntax into ``tree.py``'s plain indented format.
+
+    Drops the ``mindmap`` header line and any ``::icon(...)``/``:::class``
+    decoration lines (termrender's tree has no icon/class concept); every
+    other line's original indentation is preserved (depth comes from
+    indentation, exactly as ``tree.py`` already expects) with its node-shape
+    delimiters stripped down to label text. Returns the transformed
+    multi-line indented string, empty if nothing survived.
+    """
+    out_lines: list[str] = []
+    for raw_line in source.splitlines():
+        if not raw_line.strip():
+            continue
+        if _HEADER_RE.match(raw_line):
+            continue
+        stripped = raw_line.strip()
+        if _ICON_RE.match(stripped) or _CLASS_RE.match(stripped):
+            continue
+        indent = raw_line[: len(raw_line) - len(raw_line.lstrip(" "))]
+        out_lines.append(f"{indent}{_node_label(stripped)}")
+    return "\n".join(out_lines)
+
+
+def render(source: str, width: int) -> list[str]:
+    """Render mermaid mindmap syntax as a guide-line tree.
+
+    A diagram with no survivable content (only a header, or blank)
+    degrades to the raw source text.
+    """
+    tree_source = parse_mindmap(source)
+    if not tree_source.strip():
+        return source.splitlines() or [""]
+
+    block = Block(type=BlockType.TREE, attrs={"source": tree_source}, width=width)
+    return render_tree(block, color=False)

termrender-4.3.0/src/termrender/renderers/mermaid_prelude.py

@@ -0,0 +1,55 @@
+"""Shared handling for mermaid's optional prelude before the type keyword.
+
+Mermaid tolerates three forms of preamble before a diagram's type line
+(``pie``, ``gantt``, ``sequenceDiagram``, …): ``%%`` line comments,
+``%%{init: ...}%%`` directives (mermaid's config-block syntax), and
+``---``-delimited YAML frontmatter (used for e.g. a top-level ``title:``
+key). :func:`strip_prelude_lines` skips all three so callers that sniff or
+validate "what type is this diagram" see the real type line, not a
+directive or frontmatter key.
+
+Used by ``mermaid.py`` (dispatch sniffing) and ``mermaid_sequence.py`` (its
+own "is this actually a sequence diagram" header check) — kept here rather
+than in either so neither has to import the other's private helpers.
+"""
+
+from __future__ import annotations
+
+
+def strip_prelude_lines(lines: list[str]) -> list[str]:
+    """Return ``lines`` with leading blank/comment/directive/frontmatter lines dropped.
+
+    Skipping is permissive: an unterminated frontmatter block (opening
+    ``---`` with no closing ``---``) or an unterminated ``%%{`` directive
+    (never reaches a line ending in ``%%``) is left untouched rather than
+    consumed — better to sniff a directive/frontmatter line as the "type"
+    than to silently discard real content.
+    """
+    i = 0
+    n = len(lines)
+    while i < n:
+        stripped = lines[i].strip()
+        if not stripped:
+            i += 1
+            continue
+        if stripped == "---":
+            j = i + 1
+            while j < n and lines[j].strip() != "---":
+                j += 1
+            if j >= n:
+                break  # unterminated frontmatter
+            i = j + 1
+            continue
+        if stripped.startswith("%%"):
+            if stripped.startswith("%%{") and not stripped.endswith("%%"):
+                j = i + 1
+                while j < n and not lines[j].strip().endswith("%%"):
+                    j += 1
+                if j >= n:
+                    break  # unterminated directive
+                i = j + 1
+                continue
+            i += 1
+            continue
+        break
+    return lines[i:]

{termrender-4.2.0 → termrender-4.3.0}/src/termrender/renderers/mermaid_sequence.py

@@ -1,9 +1,10 @@
 """Native ASCII renderer for mermaid ``sequenceDiagram`` sources.
 
-Standalone module: exposes a single pure function, ``render_sequence``.
-Not wired into the ``mermaid.py`` dispatcher yet (a later integration
-phase owns that); this module has no dependency on ``Block`` or the
-rest of the renderer pipeline, and nothing here is imported elsewhere.
+Standalone module: exposes a single pure function, ``render_sequence``,
+wired into ``mermaid.py``'s dispatcher for any source whose first
+non-blank (post-prelude) line starts with ``sequenceDiagram``. This
+module has no dependency on ``Block`` or the rest of the renderer
+pipeline beyond the shared prelude-skipping helper.
 
 Layout model
 ------------
@@ -57,6 +58,7 @@ from __future__ import annotations
 import re
 from dataclasses import dataclass
 
+from termrender.renderers.mermaid_prelude import strip_prelude_lines
 from termrender.style import visual_center, visual_len
 
 __all__ = ["render_sequence", "SequenceDiagramError"]
@@ -567,7 +569,8 @@ def render_sequence(source: str, width: int) -> list[str]:
     del width  # advisory only; diagrams have intrinsic width (see docstring)
 
     lines = source.splitlines()
-    first = next((line.strip() for line in lines if line.strip()), "")
+    sniff_lines = strip_prelude_lines(lines)
+    first = next((line.strip() for line in sniff_lines if line.strip()), "")
     if not first.lower().startswith("sequencediagram"):
         raise SequenceDiagramError(
             "not a mermaid sequence diagram: source must start with 'sequenceDiagram'"