fix: work around Mermaid crash for transitions inside parallel regions

Mermaid's stateDiagram-v2 crashes when a transition targets or originates
from a compound state inside a parallel region (mermaid-js/mermaid#4052).
The MermaidRenderer now redirects such endpoints to the compound's initial
child state.

Also filter dot-form event aliases (e.g. done.invoke.X) from diagram
output — the fix lives in the extractor so all renderers benefit.

Closes #594

Author: fgmacedo

docs/diagram.md

@@ -95,12 +95,22 @@ the command line.
 
 | Format | Aliases | Description | Dependencies |
 |--------|---------|-------------|--------------|
-| `mermaid` | | [Mermaid stateDiagram-v2](https://mermaid.js.org/syntax/stateDiagram.html) source | None |
+| `mermaid` | | [Mermaid stateDiagram-v2](https://mermaid.js.org/syntax/stateDiagram.html) source | None [^mermaid] |
 | `md` | `markdown` | Transition table (pipe-delimited Markdown) | None |
 | `rst` | | Transition table (RST grid table) | None |
 | `dot` | | [Graphviz DOT](https://graphviz.org/doc/info/lang.html) language source | pydot |
 | `svg` | | SVG markup (generated via DOT) | pydot, Graphviz |
 
+[^mermaid]: Mermaid has a known rendering bug
+    ([mermaid-js/mermaid#4052](https://github.com/mermaid-js/mermaid/issues/4052))
+    where transitions targeting or originating from a compound state inside a
+    parallel region crash the renderer.  As a workaround, the `MermaidRenderer`
+    redirects such transitions to the compound's initial child state.  The
+    visual result is equivalent — Mermaid draws the arrow crossing into the
+    compound boundary — but the arrow points to the child rather than the
+    compound border.  This workaround will be revisited when the upstream bug
+    is resolved.
+
 
 ### Using `format()`
 

statemachine/contrib/diagram/extract.py

@@ -13,6 +13,7 @@
 if TYPE_CHECKING:
     from statemachine.state import State
     from statemachine.statemachine import StateChart
+    from statemachine.transition import Transition
 
     # A StateChart class or instance — both expose the same structural metadata.
     MachineRef = Union["StateChart", "type[StateChart]"]
@@ -101,6 +102,33 @@ def _extract_state(
     )
 
 
+def _format_event_names(transition: "Transition") -> str:
+    """Build a display string for the events that trigger a transition.
+
+    ``_expand_event_id`` registers both the Python attribute name
+    (``done_invoke_X``) and the SCXML dot form (``done.invoke.X``) under the
+    same transition.  For diagram display we only want unique *semantic* events,
+    keeping the Python attribute name when an alias pair exists.
+    """
+    events = list(transition.events)
+    if not events:
+        return ""
+
+    all_ids = {str(e) for e in events}
+
+    display: List[str] = []
+    for event in events:
+        eid = str(event)
+        # Skip dot-form aliases (e.g. "done.invoke.X") when the underscore
+        # form ("done_invoke_X") is also registered on this transition.
+        if "." in eid and eid.replace(".", "_") in all_ids:
+            continue
+        if eid not in display:
+            display.append(eid)
+
+    return " ".join(display)
+
+
 def _extract_transitions_from_state(state: "State") -> List[DiagramTransition]:
     """Extract transitions from a single state (non-recursive)."""
     result: List[DiagramTransition] = []
@@ -114,7 +142,7 @@ def _extract_transitions_from_state(state: "State") -> List[DiagramTransition]:
             DiagramTransition(
                 source=transition.source.id,
                 targets=target_ids,
-                event=transition.event,
+                event=_format_event_names(transition),
                 guards=cond_strs,
                 is_internal=transition.internal,
             )

statemachine/contrib/diagram/renderers/mermaid.py

@@ -1,4 +1,5 @@
 from dataclasses import dataclass
+from typing import Dict
 from typing import List
 from typing import Optional
 from typing import Set
@@ -21,17 +22,34 @@ class MermaidRendererConfig:
 
 
 class MermaidRenderer:
-    """Renders a DiagramGraph into a Mermaid stateDiagram-v2 source string."""
+    """Renders a DiagramGraph into a Mermaid stateDiagram-v2 source string.
+
+    Mermaid's stateDiagram-v2 has a rendering bug where transitions whose source
+    or target is a compound state (``state X { ... }``) inside a parallel region
+    crash with ``Cannot set properties of undefined (setting 'rank')``.  To work
+    around this, the renderer rewrites compound-state endpoints to cross the
+    boundary:
+
+    - Transition **to** a compound → redirected to its initial child.
+    - Transition **from** a compound → redirected from its initial child.
+
+    This is applied universally (not only inside parallel regions) for simplicity
+    and consistency — the visual effect is equivalent.
+    """
 
     def __init__(self, config: Optional[MermaidRendererConfig] = None):
         self.config = config or MermaidRendererConfig()
         self._active_ids: List[str] = []
         self._rendered_transitions: Set[tuple] = set()
+        self._compound_ids: Set[str] = set()
+        self._initial_child_map: Dict[str, str] = {}
 
     def render(self, graph: DiagramGraph) -> str:
         """Render a DiagramGraph to a Mermaid stateDiagram-v2 string."""
         self._active_ids = []
         self._rendered_transitions = set()
+        self._compound_ids = graph.compound_state_ids
+        self._initial_child_map = self._build_initial_child_map(graph.states)
 
         lines: List[str] = []
         lines.append("stateDiagram-v2")
@@ -51,6 +69,23 @@ def render(self, graph: DiagramGraph) -> str:
 
         return "\n".join(lines) + "\n"
 
+    def _build_initial_child_map(self, states: List[DiagramState]) -> Dict[str, str]:
+        """Build a map from compound state ID to its initial child ID (recursive)."""
+        result: Dict[str, str] = {}
+        for state in states:
+            if state.children:
+                initial = next((c for c in state.children if c.is_initial), None)
+                if initial:
+                    result[state.id] = initial.id
+                result.update(self._build_initial_child_map(state.children))
+        return result
+
+    def _resolve_endpoint(self, state_id: str) -> str:
+        """Resolve a transition endpoint, redirecting compound states to their initial child."""
+        if state_id in self._compound_ids and state_id in self._initial_child_map:
+            return self._initial_child_map[state_id]
+        return state_id
+
     def _render_states(
         self,
         states: List[DiagramState],
@@ -162,29 +197,42 @@ def _render_scope_transitions(
         lines: List[str],
         indent: int,
     ) -> None:
-        """Render transitions where both source and all targets are in scope_ids."""
+        """Render transitions where both source and all targets are in scope_ids.
+
+        Mermaid does not support transitions where the source or target is a
+        compound state rendered with ``state X { ... }`` inside a parallel region.
+        To work around this, endpoints that reference compound states are
+        redirected to the compound's initial child.  Scope membership is checked
+        on the **original** IDs (which belong to this scope level), while the
+        rendered arrow uses the **resolved** (possibly redirected) IDs.
+        """
         for t in transitions:
             if t.is_initial or t.is_internal:
                 continue
 
             targets = t.targets if t.targets else [t.source]
-            # Only render if source is in scope
+
+            # Check scope membership with original IDs
             if t.source not in scope_ids:
                 continue
-            # Only render if all targets are in scope
             if not all(target in scope_ids for target in targets):
                 continue
 
-            for target in targets:
-                key = (t.source, target, t.event)
+            # Resolve endpoints for rendering (redirect compound → initial child)
+            source = self._resolve_endpoint(t.source)
+            resolved_targets = [self._resolve_endpoint(tid) for tid in targets]
+
+            for target in resolved_targets:
+                key = (source, target, t.event)
                 if key in self._rendered_transitions:
                     continue
                 self._rendered_transitions.add(key)
-                self._render_single_transition(t, target, lines, indent)
+                self._render_single_transition(t, source, target, lines, indent)
 
     def _render_single_transition(
         self,
         transition: DiagramTransition,
+        source: str,
         target: str,
         lines: List[str],
         indent: int,
@@ -198,9 +246,9 @@ def _render_single_transition(
 
         label = " ".join(label_parts)
         if label:
-            lines.append(f"{pad}{transition.source} --> {target} : {label}")
+            lines.append(f"{pad}{source} --> {target} : {label}")
         else:
-            lines.append(f"{pad}{transition.source} --> {target}")
+            lines.append(f"{pad}{source} --> {target}")
 
     @staticmethod
     def _format_action(action: DiagramAction) -> str:

tests/test_contrib_diagram.py

@@ -8,6 +8,7 @@
 from statemachine.contrib.diagram import DotGraphMachine
 from statemachine.contrib.diagram import main
 from statemachine.contrib.diagram import quickchart_write_svg
+from statemachine.contrib.diagram.extract import _format_event_names
 from statemachine.contrib.diagram.model import ActionType
 from statemachine.contrib.diagram.model import StateType
 from statemachine.contrib.diagram.renderers.dot import DotRenderer
@@ -698,6 +699,108 @@ def test_resolve_initial_fallback(self):
         assert states[0].is_initial is True
 
 
+class TestFormatEventNames:
+    """Tests for _format_event_names — alias filtering for diagram display."""
+
+    def test_simple_event_unchanged(self):
+        """A plain event with no aliases is returned as-is."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            go = s1.to(s2)
+
+        t = SM.s1.transitions[0]
+        assert _format_event_names(t) == "go"
+
+    def test_done_state_alias_filtered(self):
+        """done_state_X registers both underscore and dot forms; only underscore is shown."""
+
+        class SM(StateChart):
+            class parent(State.Compound):
+                child = State(initial=True)
+                done = State(final=True)
+                finish = child.to(done)
+
+            end = State(final=True)
+            done_state_parent = parent.to(end)
+
+        t = next(t for t in SM.parent.transitions if t.event and "done_state" in t.event)
+        result = _format_event_names(t)
+        assert result == "done_state_parent"
+        assert "done.state" not in result
+
+    def test_done_invoke_alias_filtered(self):
+        """done_invoke_X alias filtering works the same as done_state_X."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            done_invoke_child = s1.to(s2)
+
+        t = SM.s1.transitions[0]
+        result = _format_event_names(t)
+        assert result == "done_invoke_child"
+        assert "done.invoke" not in result
+
+    def test_error_alias_filtered(self):
+        """error_X registers both error_X and error.X; only underscore is shown."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            error_execution = s1.to(s2)
+
+        t = SM.s1.transitions[0]
+        result = _format_event_names(t)
+        assert result == "error_execution"
+        assert "error.execution" not in result
+
+    def test_multiple_distinct_events_preserved(self):
+        """Multiple distinct events on one transition are all preserved."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            go = s1.to(s2)
+            also = s1.to(s2)
+
+        # Add a second event to the first transition
+        t = SM.s1.transitions[0]
+        t.add_event("also")
+        result = _format_event_names(t)
+        assert "go" in result
+        assert "also" in result
+
+    def test_eventless_transition_returns_empty(self):
+        """A transition with no events returns an empty string."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            s1.to(s2, cond="always_true")
+
+            def always_true(self):
+                return True
+
+        # Find the eventless transition
+        t = next(t for t in SM.s1.transitions if not list(t.events))
+        assert _format_event_names(t) == ""
+
+    def test_dot_only_event_preserved(self):
+        """An event whose ID contains dots but has no underscore alias is preserved."""
+
+        class SM(StateChart):
+            s1 = State(initial=True)
+            s2 = State(final=True)
+            go = s1.to(s2)
+
+        from statemachine.transition import Transition
+
+        t = Transition(source=SM.s1, target=SM.s2, event="custom.event")
+        assert _format_event_names(t) == "custom.event"
+
+
 class TestDotRendererEdgeCases:
     """Tests for dot.py edge cases."""
 

tests/test_mermaid_renderer.py

@@ -249,8 +249,9 @@ class parent(State.Compound, name="Parent"):
         assert "[*] --> child1" in result
         assert "child1 --> child2 : go" in result
         assert "child2 --> [*]" in result
-        assert "start --> parent : enter" in result
-        assert "parent --> end : finish" in result
+        # Compound endpoints are redirected to the initial child (Mermaid workaround)
+        assert "start --> child1 : enter" in result
+        assert "child1 --> end : finish" in result
 
     def test_compound_no_duplicate_transitions(self):
         """Transitions inside compound states must not also appear at top level."""