termrender 4.10.2__tar.gz → 4.10.3__tar.gz

{termrender-4.10.2 → termrender-4.10.3}/CHANGELOG.md

@@ -1,6 +1,31 @@
 # CHANGELOG
 
 
+## v4.10.3 (2026-07-07)
+
+### Bug Fixes
+
+- **mermaid**: Strict degradation — unrecognized syntax raw-echoes instead of half-rendering
+  ([`904d1cc`](https://github.com/crouton-labs/termrender/commit/904d1ccaa5c012bbeefdc8f351fb25164b0c3778))
+
+Enforce the native Mermaid degradation contract across flowchart, classDiagram, stateDiagram-v2, and
+  erDiagram renderers: only well-formed presentational/accessibility directives are skipped, while
+  unsupported statements, dangling connectors, stray closers, and unterminated structural blocks now
+  fail parsing and raw-echo the entire original source.
+
+Consolidate raw-echo glyph scrubbing in mermaid_degradation.py and update the dispatcher/renderers
+  to import the shared helper so every degradation path removes box/geometric glyphs consistently.
+
+Flip the parser-level tests that previously pinned best-effort recovery for malformed flowcharts to
+  expect FlowchartError, and flip the state stray-close-brace render test to expect raw echo. Add
+  regression coverage for the review repros, malformed directive-shaped lines, valid accessibility
+  colon forms, and native rendering of valid presentational directives.
+
+Refresh renderer docs and architecture metadata away from the removed Go/mermaid-ascii path, and add
+  minimal pytest project config so the required exact 'uv run pytest' gate imports the src package
+  in this repository.
+
+
 ## v4.10.2 (2026-07-07)
 
 ### Bug Fixes

{termrender-4.10.2 → termrender-4.10.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: termrender
-Version: 4.10.2
+Version: 4.10.3
 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.10.2 → termrender-4.10.3}/design.json

@@ -99,8 +99,8 @@
           "id": "DES-005",
           "title": "Mermaid block detection",
           "description": "How mermaid code blocks are identified and stored in the AST",
-          "content": "Mermaid blocks are standard fenced code blocks with the 'mermaid' language tag:\n\n  ```mermaid\n  graph TD\n      A[Build] --> B[Test]\n  ```\n\nThe markdown parser already handles fenced code blocks. We just need to:\n\n1. Detect code blocks where language == 'mermaid'\n2. Store the raw mermaid source in the Block's attrs\n3. At render time, pass the source to mermaid-ascii for rendering\n\nThe Block node:\n\n  Block(\n      type=BlockType.MERMAID,\n      children=[],\n      text=[],\n      attrs={\"source\": \"graph TD\\n    A[Build] --> B[Test]\"}\n  )\n\nNo special parsing of the mermaid syntax itself — that's mermaid-ascii's job.",
-          "agentNotes": "We deliberately don't parse mermaid syntax ourselves. mermaid-ascii handles it. We just detect it, store it, and render it at emit time. The only thing we need from the mermaid output is its dimensions (width x height in characters) for the layout engine.",
+          "content": "Mermaid blocks are standard fenced code blocks with the 'mermaid' language tag:\n\n  ```mermaid\n  graph TD\n      A[Build] --> B[Test]\n  ```\n\nThe markdown parser already handles fenced code blocks. We just need to:\n\n1. Detect code blocks where language == 'mermaid'\n2. Store the raw mermaid source in the Block's attrs\n3. At render time, dispatch the source to the native renderer for its diagram type\n\nThe Block node:\n\n  Block(\n      type=BlockType.MERMAID,\n      children=[],\n      text=[],\n      attrs={\"source\": \"graph TD\\n    A[Build] --> B[Test]\"}\n  )\n\nMermaid syntax is parsed by termrender's own native Python parsers, one per diagram type (renderers/mermaid_flow_parser.py, mermaid_class.py, mermaid_state.py, mermaid_er.py, and dedicated modules for pie/gantt/sequence/mindmap/journey/timeline) — there is no external mermaid rendering dependency.",
+          "agentNotes": "We parse mermaid syntax ourselves with a native Python parser per diagram type; the flowchart/class/state/ER parsers share one grandalf-based layout engine (mermaid_flow_layout.py) via a common FlowGraph model. We still only need the rendered output's dimensions (width x height in characters) for the layout engine.",
           "status": "draft",
           "userNotes": "",
           "reviewAction": null,
@@ -219,8 +219,8 @@
         {
           "id": "DES-012",
           "title": "Mermaid renderer",
-          "description": "How mermaid diagrams are rendered via mermaid-ascii",
-          "content": "Mermaid blocks delegate to the mermaid-ascii library:\n\n  from mermaid_ascii import render as mermaid_render\n\n  def render_mermaid(block: Block) -> list[str]:\n      source = block.attrs['source']\n      output = mermaid_render(source)  # returns rendered ASCII string\n      lines = output.split('\\n')\n\n      # clip to available width (hard wrap per REQ-008)\n      return [line[:block.width] for line in lines]\n\nThe mermaid output is treated as a pre-rendered block — no further word wrapping or layout. If it exceeds the available width, lines are clipped at the boundary.\n\nDuring the layout pass, we render the mermaid once and cache the output on the block to avoid double-rendering:\n\n  block.attrs['_rendered'] = mermaid_render(source)\n  block.height = block.attrs['_rendered'].count('\\n') + 1",
+          "description": "How mermaid diagrams are rendered by termrender's native per-type renderers",
+          "content": "Mermaid blocks dispatch by diagram type to a native Python renderer:\n\n  from termrender.renderers.mermaid import render_mermaid_lines\n\n  def render_mermaid(block: Block) -> list[str]:\n      source = block.attrs['source']\n      lines = render_mermaid_lines(source, block.width)\n      return [visual_ljust(line, block.width) for line in lines]\n\nrender_mermaid_lines reads the diagram's first real line to pick its renderer (flowchart/class/state/ER share a grandalf-based Sugiyama layout engine; pie/gantt/sequence/mindmap/journey/timeline each have their own dedicated renderer). Any unrecognized type, or any input a renderer can't parse under its supported grammar, degrades to a raw echo of the source lines rather than a half-rendered diagram — see renderers/CLAUDE.md's degradation contract.\n\nDuring the layout pass, we render the mermaid once and cache the output on the block to avoid double-rendering:\n\n  block.attrs['_rendered'] = '\\n'.join(render_mermaid_lines(source, width))\n  block.height = block.attrs['_rendered'].count('\\n') + 1",
           "decision": {
             "proposal": {
               "title": "Pre-render during layout",
@@ -238,7 +238,7 @@
               "simplicity": "Pre-render is actually simpler — no estimation heuristics to maintain"
             }
           },
-          "agentNotes": "This also answers OQ1 from the parser section — pre-render is the way to go. The cached output is stored as a private _rendered attr.",
+          "agentNotes": "This also answers OQ1 from the parser section — pre-render is the way to go. The cached output is stored as a private _rendered attr. No external mermaid rendering dependency: every diagram type is a native Python parser in renderers/.",
           "status": "draft",
           "userNotes": "",
           "reviewAction": "agree",
@@ -362,7 +362,7 @@
           "id": "DES-018",
           "title": "Project structure",
           "description": "Directory layout and module organization",
-          "content": "  termrender/\n  ├── pyproject.toml\n  ├── src/\n  │   └── termrender/\n  │       ├── __init__.py          # render() — the public API\n  │       ├── __main__.py          # CLI entry point\n  │       ├── parser.py            # markdown + directive parsing\n  │       ├── layout.py            # width/height resolution\n  │       ├── emit.py              # ANSI string generation\n  │       ├── style.py             # ANSI color/style helpers\n  │       ├── blocks.py            # Block, InlineSpan dataclasses\n  │       ├── renderers/\n  │       │   ├── __init__.py\n  │       │   ├── panel.py         # panel + callout\n  │       │   ├── columns.py       # columns + col\n  │       │   ├── tree.py          # tree rendering\n  │       │   ├── mermaid.py       # mermaid-ascii integration\n  │       │   ├── code.py          # syntax-highlighted code\n  │       │   ├── quote.py         # blockquote with attribution\n  │       │   ├── divider.py       # horizontal rule with label\n  │       │   └── text.py          # paragraphs, headings, lists\n  │       └── py.typed             # PEP 561 type hint marker\n  └── tests/\n      ├── test_parser.py\n      ├── test_layout.py\n      ├── test_emit.py\n      └── fixtures/                # .md input + expected output pairs\n\nUsing src/ layout (PEP 517) for clean packaging. Each renderer is a separate module for isolation — they can be tested independently.",
+          "content": "  termrender/\n  ├── pyproject.toml\n  ├── src/\n  │   └── termrender/\n  │       ├── __init__.py          # render() — the public API\n  │       ├── __main__.py          # CLI entry point\n  │       ├── parser.py            # markdown + directive parsing\n  │       ├── layout.py            # width/height resolution\n  │       ├── emit.py              # ANSI string generation\n  │       ├── style.py             # ANSI color/style helpers\n  │       ├── blocks.py            # Block, InlineSpan dataclasses\n  │       ├── renderers/\n  │       │   ├── __init__.py\n  │       │   ├── panel.py         # panel + callout\n  │       │   ├── columns.py       # columns + col\n  │       │   ├── tree.py          # tree rendering\n  │       │   ├── mermaid.py       # mermaid dispatch + native per-type renderers\n  │       │   ├── code.py          # syntax-highlighted code\n  │       │   ├── quote.py         # blockquote with attribution\n  │       │   ├── divider.py       # horizontal rule with label\n  │       │   └── text.py          # paragraphs, headings, lists\n  │       └── py.typed             # PEP 561 type hint marker\n  └── tests/\n      ├── test_parser.py\n      ├── test_layout.py\n      ├── test_emit.py\n      └── fixtures/                # .md input + expected output pairs\n\nUsing src/ layout (PEP 517) for clean packaging. Each renderer is a separate module for isolation — they can be tested independently.",
           "agentNotes": "The renderer-per-file structure means adding a new directive type is: add a file in renderers/, add the BlockType enum value, register it in the emit dispatcher. No existing code needs to change.",
           "status": "draft",
           "userNotes": "",
@@ -374,8 +374,8 @@
           "id": "DES-019",
           "title": "Dependencies",
           "description": "Runtime and dev dependencies",
-          "content": "Runtime dependencies:\n\n  Dependency       Purpose                    Size\n  ──────────       ───────                    ────\n  mistune >=3.0    Markdown parsing           ~2k lines\n  mermaid-ascii    Mermaid diagram rendering  ~5k lines\n  pygments         Syntax highlighting        large but ubiquitous\n\nDev dependencies:\n\n  pytest           Testing\n  ruff             Linting + formatting\n  mypy             Type checking\n  build            Package building\n\nTotal runtime deps: 3. All pure Python, no native extensions, no subprocess calls.\n\npyproject.toml:\n\n  [project]\n  name = \"termrender\"\n  requires-python = \">=3.10\"\n  dependencies = [\n      \"mistune>=3.0\",\n      \"mermaid-ascii>=1.0\",\n      \"pygments>=2.0\",\n  ]\n\n  [project.scripts]\n  termrender = \"termrender.__main__:main\"\n\n  [build-system]\n  requires = [\"hatchling\"]\n  build-backend = \"hatchling.build\"",
-          "agentNotes": "Three deps is lean for what this does. Pygments is the heaviest but it's already installed in most Python environments (IPython, Jupyter, Sphinx all depend on it). Could be made optional with a graceful fallback to plain text, but that's over-engineering for v1.",
+          "content": "Runtime dependencies:\n\n  Dependency       Purpose                    Size\n  ──────────       ───────                    ────\n  mistune >=3.0    Markdown parsing           ~2k lines\n  grandalf >=0.8   Graph layout (mermaid)     small, pure Python\n  pygments         Syntax highlighting        large but ubiquitous\n\nDev dependencies:\n\n  pytest           Testing\n  ruff             Linting + formatting\n  mypy             Type checking\n  build            Package building\n\nTotal runtime deps: 3. All pure Python, no native extensions, no subprocess calls.\n\npyproject.toml:\n\n  [project]\n  name = \"termrender\"\n  requires-python = \">=3.10\"\n  dependencies = [\n      \"mistune>=3.0\",\n      \"pygments>=2.0\",\n      \"grandalf>=0.8\",\n  ]\n\n  [project.scripts]\n  termrender = \"termrender.__main__:main\"\n\n  [build-system]\n  requires = [\"hatchling\"]\n  build-backend = \"hatchling.build\"",
+          "agentNotes": "Three deps is lean for what this does. Pygments is the heaviest but it's already installed in most Python environments (IPython, Jupyter, Sphinx all depend on it). grandalf is a small pure-Python graph layout library used only by the mermaid flowchart-model renderers (flow/class/state/ER).",
           "status": "draft",
           "userNotes": "",
           "reviewAction": null,

{termrender-4.10.2 → termrender-4.10.3}/pyproject.toml

@@ -37,12 +37,18 @@ Homepage = "https://github.com/CaptainCrouton89/termrender"
 Repository = "https://github.com/CaptainCrouton89/termrender"
 Issues = "https://github.com/CaptainCrouton89/termrender/issues"
 
+[dependency-groups]
+dev = ["pytest>=9.0"]
+
 [project.scripts]
 termrender = "termrender.__main__:main"
 
 [tool.hatch.version]
 source = "vcs"
 
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+
 [tool.hatch.build.targets.wheel]
 packages = ["src/termrender"]
 

{termrender-4.10.2 → termrender-4.10.3}/requirements.json

@@ -112,7 +112,7 @@
           "title": "Mermaid code blocks",
           "ears": {
             "when": "When the input contains a fenced code block with language 'mermaid'",
-            "shall": "the system shall parse the mermaid syntax and render it as an ASCII/Unicode flowchart inline with surrounding content, using mermaid-ascii as the rendering backend"
+            "shall": "the system shall parse the mermaid syntax and render it as an ASCII/Unicode flowchart inline with surrounding content, using termrender's own native Python parsers (no external mermaid rendering dependency)"
           },
           "criteria": [
             {
@@ -136,12 +136,12 @@
               "checked": false
             },
             {
-              "text": "mermaid-ascii is used as a Python dependency, not shelled out to",
+              "text": "diagrams are parsed and rendered in-process by native Python parsers, with no subprocess or vendored binary dependency",
               "checked": false
             }
           ],
           "status": "draft",
-          "agentNotes": "Revised per review — since this is a Python package, we use mermaid-ascii directly as a library dependency. No subprocess overhead, no Python runtime concern. Sequence diagram support depends on what mermaid-ascii supports.",
+          "agentNotes": "Each mermaid diagram type has its own native Python parser in renderers/ (mermaid_flow_parser.py, mermaid_class.py, mermaid_state.py, mermaid_er.py, plus dedicated pie/gantt/sequence/mindmap/journey/timeline modules); the flowchart/class/state/ER parsers share one grandalf-based Sugiyama layout engine via a common FlowGraph model.",
           "userNotes": "User: 'We're going to make this a python package, so it's okay if it has python deps'",
           "questions": [],
           "startedAt": "2026-04-05T03:25:14.714Z",
@@ -479,7 +479,7 @@
           "title": "Standalone Python package",
           "ears": {
             "while": "While the package is distributed",
-            "shall": "the system shall be a standalone Python package on PyPI, installable independently of sisyphus, with mermaid-ascii and a markdown parser as its primary dependencies"
+            "shall": "the system shall be a standalone Python package on PyPI, installable independently of sisyphus, with mistune (markdown) and grandalf (graph layout for native mermaid rendering) as its primary dependencies"
           },
           "criteria": [
             {
@@ -491,7 +491,7 @@
               "checked": false
             },
             {
-              "text": "Dependencies: mermaid-ascii, markdown parser (mistune or markdown-it-py), Rich (for ANSI primitives)",
+              "text": "Dependencies: mistune (markdown parsing), grandalf (graph layout), pygments (syntax highlighting)",
               "checked": false
             },
             {
@@ -500,7 +500,7 @@
             }
           ],
           "status": "draft",
-          "agentNotes": "Revised per review — Python package on PyPI instead of npm. mermaid-ascii is a direct dependency. Rich can be used for low-level ANSI output (colors, styles) without using its layout/panel system — we build our own layout engine on top.",
+          "agentNotes": "Python package on PyPI. Mermaid diagrams render via termrender's own native parsers plus grandalf for graph layout — no external mermaid rendering dependency.",
           "userNotes": "User: 'It can be python — it doesn't need to be ts'",
           "questions": [
             {

{termrender-4.10.2 → termrender-4.10.3}/src/termrender/renderers/CLAUDE.md

@@ -53,7 +53,7 @@ Layout (`layout.py::resolve_height`, `BlockType.MERMAID` branch) precomputes `bl
 
 ## `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.
+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 degradation contract every other mermaid renderer in this package upholds.
 
 ## `mermaid_gantt.py` — dates resolved via a running `last_end` cursor, not a strict grammar
 
@@ -65,7 +65,7 @@ A text pie chart is worse than a labeled bar chart at the same information densi
 
 ## `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.).
+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/class/state/ER renderers. 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
 

{termrender-4.10.2 → termrender-4.10.3}/src/termrender/renderers/mermaid.py

@@ -2,8 +2,6 @@
 
 from __future__ import annotations
 
-import re
-
 from termrender.blocks import Block
 from termrender.renderers import (
     mermaid_class,
@@ -17,18 +15,10 @@ from termrender.renderers import (
     mermaid_state,
     mermaid_timeline,
 )
+from termrender.renderers.mermaid_degradation import raw_echo
 from termrender.renderers.mermaid_prelude import strip_prelude_lines
 from termrender.style import visual_ljust
 
-# Same box-drawing/geometric glyph ranges the native renderers (mermaid_flow,
-# mermaid_class, mermaid_state, mermaid_er) guard their own raw-echo paths
-# with, and the same ranges the downstream crouter viewer keys on to detect
-# render *success*. An exotic/unrecognized diagram type has no renderer at
-# all, so its degradation lives here rather than in a shared renderer module;
-# it must uphold the identical contract — no such glyph survives the echo,
-# even one present verbatim in the source itself.
-_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
-
 
 def _first_line_type(source: str) -> str:
     """Return the lowercased first real line's leading keyword.
@@ -52,21 +42,6 @@ def _stripped(source: str) -> str:
     return "\n".join(strip_prelude_lines(source.splitlines()))
 
 
-def _raw_echo(source: str) -> list[str]:
-    """Degrade an exotic/unrecognized diagram type to its raw source lines.
-
-    No renderer exists for these types (sankey, C4, gitgraph, block, packet,
-    kanban, quadrantChart, …, and anything unrecognized): the source is
-    echoed back verbatim, with box-drawing/geometric glyphs neutralized so
-    the crouter viewer's "no glyphs survived" success check can't be fooled
-    by one present in the raw source itself — the same guarantee every
-    native renderer's own raw-echo path upholds.
-    """
-    return [
-        _GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()
-    ]
-
-
 def render_mermaid_lines(source: str, width: int) -> list[str]:
     """Dispatch a mermaid source to its type's renderer and return raw lines.
 
@@ -76,8 +51,9 @@ def render_mermaid_lines(source: str, width: int) -> list[str]:
     ``classDiagram``, ``stateDiagram``/``stateDiagram-v2``, and ``erDiagram``.
     Any other type (sankey, C4, gitgraph, block, packet, kanban, …, or
     anything unrecognized) degrades to a raw echo of the source with no
-    box-drawing glyphs — see :func:`_raw_echo`. Lines are returned unpadded;
-    callers apply width padding uniformly.
+    box-drawing glyphs — see :func:`~termrender.renderers.mermaid_degradation.
+    raw_echo`. Lines are returned unpadded; callers apply width padding
+    uniformly.
     """
     diagram_type = _first_line_type(source)
     if diagram_type.startswith("pie"):
@@ -100,7 +76,7 @@ def render_mermaid_lines(source: str, width: int) -> list[str]:
         return mermaid_state.render_state(source, width)
     if diagram_type.startswith("erdiagram"):
         return mermaid_er.render_er(source, width)
-    return _raw_echo(source)
+    return raw_echo(source)
 
 
 def render(block: Block, color: bool) -> list[str]:

{termrender-4.10.2 → termrender-4.10.3}/src/termrender/renderers/mermaid_class.py

@@ -1,10 +1,9 @@
 """Native renderer for mermaid ``classDiagram`` sources.
 
-Standalone module: exposes a single pure function, :func:`render_class`.
-Not wired into ``mermaid.py``'s dispatcher (a later, orchestrator-owned
-phase) — nothing in this package imports it. Own parser, own tests, no
-dependency on ``Block`` or the render pipeline, matching the shape of
-``mermaid_sequence.py`` and ``mermaid_flow.py``.
+Wired into ``mermaid.py``'s dispatcher: exposes a single pure function,
+:func:`render_class`. Own parser, own tests, no dependency on ``Block``
+or the render pipeline, matching the shape of ``mermaid_sequence.py``
+and ``mermaid_flow.py``.
 
 This module does no layout or rasterization of its own. It parses mermaid
 ``classDiagram`` source into the *same* :class:`~termrender.renderers.
@@ -53,7 +52,8 @@ Grammar supported
   centers this single combined label on the edge's longest straight run;
   the UML convention of a cardinality glyph pinned at each endpoint
   separately isn't supported (see *Known degradations*).
-- ``%%`` comments are dropped.
+- ``%%`` comments and well-formed presentational directives (``classDef``/
+  ``style``/``cssClass``/``accTitle``/``accDescr``) are dropped.
 
 Never crashes: any unparseable input (missing header, or a parse/layout
 exception) degrades to a **raw echo** of the source lines with no
@@ -68,8 +68,9 @@ Known degradations (by design, not bugs)
   (per-endpoint cardinality glyphs, common in dedicated UML tools) — the
   underlying engine places one label per edge.
 - ``note`` statements, `<<...>>` generic constraints beyond the ``~T~``
-  substitution, and class-diagram namespaces are not recognized — lines
-  using them are silently dropped (best-effort parsing, never raised).
+  substitution, and class-diagram namespaces are not recognized; they
+  raise ``ClassDiagramError`` and the public renderer raw-echoes instead
+  of half-rendering the diagram.
 - See ``mermaid_flow_layout.py``'s docstring for the inherited engine
   degradations (dense-graph crossings, CJK wrap width, minimum-box-size
   cosmetics) — this renderer's output goes through the same rasterizer and
@@ -80,6 +81,7 @@ from __future__ import annotations
 
 import re
 
+from termrender.renderers.mermaid_degradation import raw_echo
 from termrender.renderers.mermaid_flow_layout import layout_flowgraph
 from termrender.renderers.mermaid_flow_model import (
     Direction,
@@ -105,6 +107,21 @@ class ClassDiagramError(Exception):
 _HEADER_RE = re.compile(r"^classDiagram(?:-v2)?\b", re.IGNORECASE)
 _DIRECTION_RE = re.compile(r"^direction\s+(TB|TD|LR|RL|BT)\b", re.IGNORECASE)
 _COMMENT_RE = re.compile(r"^%%")
+_CLASSDEF_RE = re.compile(r"^classDef\b\s+\S+\s+\S.*$", re.IGNORECASE)
+_STYLE_RE = re.compile(r"^style\b\s+\S+\s+\S.*$", re.IGNORECASE)
+_CSSCLASS_RE = re.compile(
+    r'^cssClass\b\s+(?:"[^"]+"|\S+)(?:\s*,\s*(?:"[^"]+"|\S+))*\s+\S+\s*$',
+    re.IGNORECASE,
+)
+_ACCTITLE_RE = re.compile(r"^accTitle\b\s*:?\s+\S.*$", re.IGNORECASE)
+_ACCDESCR_RE = re.compile(r"^accDescr\b\s*:?\s+\S.*$", re.IGNORECASE)
+_CLASS_ASSIGN_RE = re.compile(
+    r"^class\b\s+(?:\S+(?:\s*,\s*\S+)*)\s+(?!\{)\S+\s*$", re.IGNORECASE
+)
+_CLASS_SHORTHAND_RE = re.compile(r"^class\b\s+\S+:::\S+\s*$", re.IGNORECASE)
+_BODY_DIRECTIVE_RE = re.compile(
+    r"^(?:classDef|class|style|cssClass|accTitle|accDescr)\b", re.IGNORECASE
+)
 
 _CLASS_OPEN_RE = re.compile(r"^class\s+(\S+)\s*\{(.*)$")
 _CLASS_BARE_RE = re.compile(r"^class\s+(\S+)\s*$")
@@ -124,8 +141,6 @@ _REL_RIGHT_RE = re.compile(
     r'^\s*(?:"(?P<card>[^"]*)")?\s*(?P<id>[^\s":]+)\s*(?::\s*(?P<label>.*))?$'
 )
 
-_GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
-
 
 class _ClassDef:
     """Mutable parse-time record for one UML class — converted to a
@@ -173,6 +188,31 @@ def _get_or_create(classes: dict[str, _ClassDef], token: str) -> _ClassDef:
     return cls
 
 
+def _is_presentational_line(line: str) -> bool:
+    return any(
+        regex.match(line)
+        for regex in (
+            _CLASSDEF_RE,
+            _STYLE_RE,
+            _CSSCLASS_RE,
+            _ACCTITLE_RE,
+            _ACCDESCR_RE,
+            _CLASS_ASSIGN_RE,
+            _CLASS_SHORTHAND_RE,
+        )
+    )
+
+
+def _consume_block_text(cls: _ClassDef, text: str) -> None:
+    for part in text.split(";"):
+        part = part.strip()
+        if part and _BODY_DIRECTIVE_RE.match(part):
+            raise ClassDiagramError(
+                f"unrecognized class diagram statement: {part!r}"
+            )
+    _consume_members(cls, text)
+
+
 def _consume_members(cls: _ClassDef, text: str) -> None:
     """Split ``text`` (one physical line, or the inline body of a
     ``class Name { ... }`` opener/closer) on ``;`` into individual member/
@@ -271,11 +311,15 @@ def _build_graph(source: str) -> FlowGraph:
             continue
 
         if block_cls is not None:
+            if _COMMENT_RE.match(line):
+                continue
             if line.endswith("}"):
-                _consume_members(block_cls, line[:-1])
+                body = line[:-1].rstrip()
+                if body:
+                    _consume_block_text(block_cls, body)
                 block_cls = None
             else:
-                _consume_members(block_cls, line)
+                _consume_block_text(block_cls, line)
             continue
 
         if not seen_header:
@@ -283,7 +327,7 @@ def _build_graph(source: str) -> FlowGraph:
                 seen_header = True
             continue
 
-        if _COMMENT_RE.match(line):
+        if _COMMENT_RE.match(line) or _is_presentational_line(line):
             continue
 
         dm = _DIRECTION_RE.match(line)
@@ -299,9 +343,9 @@ def _build_graph(source: str) -> FlowGraph:
             cls.has_block = True
             body = inline_body.rstrip()
             if body.endswith("}"):
-                _consume_members(cls, body[:-1])
+                _consume_block_text(cls, body[:-1])
             else:
-                _consume_members(cls, body)
+                _consume_block_text(cls, body)
                 block_cls = cls
             continue
 
@@ -326,7 +370,13 @@ def _build_graph(source: str) -> FlowGraph:
             _consume_members(cls, mm.group("member"))
             continue
 
-        # Unrecognized line: consumed silently, best-effort.
+        if _CLASS_ASSIGN_RE.match(line) or _CLASS_SHORTHAND_RE.match(line):
+            continue
+
+        raise ClassDiagramError(f"unrecognized class diagram statement: {line!r}")
+
+    if block_cls is not None:
+        raise ClassDiagramError("unterminated class body")
 
     if not seen_header:
         raise ClassDiagramError(
@@ -354,12 +404,6 @@ def _build_graph(source: str) -> FlowGraph:
     return FlowGraph(direction=direction, nodes=nodes, edges=edges, subgraphs=[])
 
 
-def _raw_echo(source: str) -> list[str]:
-    return [
-        _GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()
-    ]
-
-
 def render_class(source: str, width: int) -> list[str]:
     """Render a mermaid ``classDiagram`` source to unicode lines.
 
@@ -381,17 +425,17 @@ def render_class(source: str, width: int) -> list[str]:
     try:
         graph = _build_graph(source)
     except ClassDiagramError:
-        return _raw_echo(source)
+        return raw_echo(source)
 
     if not graph.nodes:
-        return _raw_echo(source)
+        return raw_echo(source)
 
     try:
         lines = layout_flowgraph(graph, width)
     except Exception:
-        return _raw_echo(source)
+        return raw_echo(source)
 
     if not lines:
-        return _raw_echo(source)
+        return raw_echo(source)
 
     return lines

termrender-4.10.3/src/termrender/renderers/mermaid_degradation.py

@@ -0,0 +1,34 @@
+"""Shared raw-echo degradation contract for the native mermaid renderers.
+
+Every native mermaid renderer in this package (``mermaid.py``'s exotic-type
+fallback, and the flowchart-model-backed ``mermaid_flow.py``,
+``mermaid_class.py``, ``mermaid_state.py``, ``mermaid_er.py``) must degrade
+identically on any input it cannot fully render under its supported
+grammar: echo the source lines verbatim (``.rstrip()``-ed), with every
+box-drawing/geometric glyph replaced by ``?``. The downstream crouter
+attach viewer keys on the *presence* of one of these glyphs to decide
+whether a native render succeeded and the original mermaid fence can be
+dropped — so the echo path must never contain one, even when malformed or
+degenerate source happens to contain a literal glyph of its own (e.g. a
+hand-typed ``"\u250c"`` in otherwise-non-mermaid text).
+
+:func:`raw_echo` is the one shared implementation of that contract; every
+renderer module imports it rather than keeping its own copy of the glyph
+regex and echo function.
+"""
+
+from __future__ import annotations
+
+import re
+
+__all__ = ["GLYPH_RANGE_RE", "raw_echo"]
+
+GLYPH_RANGE_RE = re.compile("[\u2500-\u259f\u25a0-\u25ff]")
+
+
+def raw_echo(source: str) -> list[str]:
+    """Echo ``source``'s lines verbatim, minus trailing whitespace, with
+    every box-drawing/geometric glyph (:data:`GLYPH_RANGE_RE`) replaced by
+    ``?`` so the echo can never be mistaken for a successful native
+    render."""
+    return [GLYPH_RANGE_RE.sub("?", line.rstrip()) for line in source.splitlines()]