Files
codex/codex-rs/mermaid
Eric Traut dba22f2acc Support flat subgraphs in native Mermaid flowcharts (#61878)
## What changed

Parse `subgraph title` and `subgraph ID[title]` blocks and render labeled frames around their nodes and internal edges. Support edges between nodes in different groups in all four flowchart directions.

Keep nested subgraphs, edges to subgraph IDs, and subgraph-local directions unsupported, preserving source fallback for unsupported input. Document the expanded syntax subset.

## Testing

Add snapshot and regression coverage for group rendering, cross-group edges, all four directions, width limits, and invalid or unsupported subgraphs. Extend TUI native-renderer coverage to include grouped flowcharts.

GitOrigin-RevId: 5bed535bcd4991b53143e3a591eef04f46ef4bd1
2026-11-16 20:53:56 +00:00
..

codex-mermaid

Standalone, bounded Mermaid text renderer. It uses the existing unicode-width dependency; no Mermaid runtime or new external production dependency is needed.

Supported subsets

Family Supported syntax
flowchart, graph TD/TB (default), BT, LR, RL; rectangle [label], decision {label}, and stadium ([label]) nodes; solid -->/---/<--> and dashed -.->/-.-/<-.-> edges; pipe labels and spaced directed infix labels (-- text -->, -. text .->); & fan-out/fan-in, chains, branches, merges, loops; flat named subgraph title or subgraph ID[title] blocks closed by end, including edges between nodes in different groups
sequenceDiagram Implicit participants, participant/actor, aliases, ->, ->>, -->, -->>, -x, --x, self-messages, Note over A[,B], nested loop/alt/opt/critical/break, one labeled else per alt
stateDiagram-v2, stateDiagram Flat states, state "label" as ID, descriptions, directed transitions with optional labels, initial/final [*], direction declarations
classDiagram class ID, multiline member bodies, ID : member, solid/dashed links, association, inheritance, composition, aggregation, dependency, realization, quoted endpoint cardinalities, relationship labels, direction declarations
erDiagram Entities, multiline attribute bodies, type name [PK, FK, UK] ["comment"], all four endpoint cardinalities, identifying/non-identifying relationships, relationship labels, direction declarations

Identifiers are ASCII letters followed by letters, digits, or underscores. Text supports ordinary Unicode and CJK. Full-line %% comments and semicolon-separated statements are supported outside flowchart labels, quoted tokens, and class bodies. Sequence quotes are literal text; use newlines between class members, whose semicolons remain text. Member/attribute bodies need a separate statement for each opening brace, member, and closing brace (for example class Order { followed by member lines and a final }). Class member text is retained in one compartment, including visibility, signatures, and return types. ER attribute types and names use the identifier grammar above.

Flowchart node and edge labels may be enclosed in double quotes. Literal ampersands are supported in labels, as is printable punctuation after parsing. Quotes protect flowchart label delimiters such as brackets, pipes, and semicolons. Flowchart node labels support <br>, <br/>, and <br /> as line breaks. Other HTML and entity escapes remain unsupported.

These are explicit subsets, not complete Mermaid compatibility. Compound states, nested flowchart subgraphs, edges to subgraph IDs, subgraph-local directions, other shapes, sequence activation and parallel fragments, styling, front matter, directives, other HTML, escapes, combining/zero-width characters, and ligatures with non-additive widths return errors. Callers should retain source on any error; the library never returns a partial diagram.

Layout and notation

Graph nodes appear in declaration/first-reference order, in the requested direction. Each edge gets its own lane and endpoint positions. Crossings use ╪ and never join routes. Decisions use ◇ inside a box; stadiums use rounded box corners. Horizontal layouts reserve a text gutter for every endpoint, which can make connected graphs wide; the caller receives TooWide if the complete output does not fit.

Class links use arrows into the referenced class, ◁/△ for inheritance/realization, ◆ for composition, and ◇ for aggregation. Endpoint cardinalities appear in parentheses next to the appropriate class or entity. ER cardinalities are written as 1, 0..1, 1..many, or 0..many. Solid ER links are identifying; dashed links are non-identifying. Class members and ER keys/comments appear verbatim as readable text, rather than renderer metadata.

Sequence messages retain chronological order. ->>/-->> use ▶/◀ arrowheads, ->/--> have no arrowhead, and -x/--x use a cross endpoint. Solid and dashed strokes remain distinct. Lifelines crossed by a message use ┼; this is not a recipient. Control fragments have nested frames and explicit branch labels. Notes span their named participants. States use separate ● initial and ◎ final nodes.

Limits and evaluation

All inputs are limited to 16 KiB. Graphs allow 16 nodes, 24 edges (after expanding & groups), and 16 members per node. Each & group allows at most 24 node references. Sequences allow 8 participants, 64 events (including fragment boundaries), and 4 fragment levels. Labels are limited to 40 display cells per line; identifiers are limited to 40 ASCII bytes. Rendered canvases are capped at 65,536 cells, independent of the caller's maximum width. The library performs no I/O.

From codex-rs, preview a file, optionally specifying the available width:

cargo run -p codex-mermaid --example render -- 180 < diagram.mmd

Run just test -p codex-mermaid --lib. Coverage includes complex snapshots for every family, relationship endpoints, all ER cardinalities, width/error bounds, truncated input, and reconstruction of every edge in all 512 directed three-node graphs in each of the four layout directions.

render_spans returns the same layout as lines of semantic Node, Edge, and Text spans. Callers apply their own theme; the crate never emits ANSI escapes.