termrender 4.2.0__tar.gz → 4.3.1__tar.gz

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

@@ -1,6 +1,89 @@
 # CHANGELOG
 
 
+## v4.3.1 (2026-07-06)
+
+### Bug Fixes
+
+- **mermaid-gantt**: Close remaining overflow and includes gaps from review
+  ([`73a1354`](https://github.com/crouton-labs/termrender/commit/73a135465644073d58e293ed69e6ca968d4f5a05))
+
+- _skip_excluded() and the implicit +1-day default end could still raise OverflowError past
+  datetime.max; both call sites now catch it and degrade the whole diagram to source instead of
+  crashing. - includes weekends was accepted but silently no-op'd (excludes weekends + includes
+  weekends still rendered the excluded schedule); includes now only supports explicit YYYY-MM-DD
+  dates and rejects weekends as _Unsupported rather than pretending to cancel the exclusion.
+
+fix(mermaid-pie): reject invalid trailing header grammar
+
+pie bogus (anything after pie/pie showData that isn't a valid inline title) was silently accepted
+  and rendered a plausible chart; it now degrades the whole diagram to source, matching the
+  strictness already applied to other invalid pie lines.
+
+- **mermaid-gantt**: Implement excludes/includes, milestone, until; never-crash on bad
+  dateFormat/overflow
+  ([`e182ae1`](https://github.com/crouton-labs/termrender/commit/e182ae1346af7fa4a531ad0014878e06caf5304e))
+
+Several valid Mermaid gantt constructs rendered false schedules, and malformed input could crash:
+
+- A malformed dateFormat (e.g. YYYY-YYYY, whose translated strptime pattern has a duplicate capture
+  group) raised re.error instead of being caught; the format is now validated by round-tripping a
+  sample date and an invalid format degrades the whole diagram to source. - Huge numeric durations
+  (e.g. 1000000000d) overflowed timedelta/datetime arithmetic; overflow is now caught and degrades
+  the whole diagram. - excludes weekends / excludes <YYYY-MM-DD> and includes <YYYY-MM-DD> are now
+  applied when resolving durations and auto-anchored start dates, instead of being ignored as
+  decorative metadata. An excludes/includes form we don't implement (e.g. day names) degrades the
+  whole diagram rather than rendering a false schedule. - milestone tasks are now tracked as
+  point-in-time markers (rendered as a single diamond marker) instead of ordinary duration spans. -
+  until <taskId> is now resolved to the referenced task's start date; an unknown reference degrades
+  the whole diagram. - %% comments (whole-line and trailing inline) are stripped before
+  tokenization, so a comment containing a colon can no longer be misparsed as a task.
+
+- **mermaid-pie**: Degrade to source on invalid grammar, negative or overflowing values
+  ([`765f613`](https://github.com/crouton-labs/termrender/commit/765f613d9e1b72ff79e8f0c32ac8d9f9cdceef69))
+
+Native pie parsing previously treated any non-matching line as a silent ignorable and accepted
+  negative slice values, so malformed input rendered a plausible-but-wrong partial chart instead of
+  falling back to source. Arbitrarily long numeric literals could also reach charts._format_value()
+  as float('inf') and raise OverflowError.
+
+- Invalid grammar (anything beyond header/title/accTitle/accDescr/%% comments/slice lines) now
+  discards the whole diagram and falls back to raw source, matching Mermaid's actual pie grammar. -
+  Negative slice values are rejected the same way (Mermaid disallows them). - Non-finite values
+  (from huge numeric literals) are rejected in parse_pie, and the summed total is re-checked in
+  render() as a second guard, both falling back to source instead of crashing. - Slice labels now
+  also accept single-quoted strings and escaped quotes inside double-quoted strings, per Mermaid's
+  real string grammar.
+
+
+## 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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.2.0
+Version: 4.3.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

{termrender-4.2.0 → termrender-4.3.1}/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.1}/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.1/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)