fix: address review feedback - per-message Y stacking, deterministic ordering, clean test comment

Co-authored-by: jongalloway <68539+jongalloway@users.noreply.github.com>

Author: Copilot

src/DiagramForge/Layout/DefaultLayoutEngine.cs

@@ -58,7 +58,7 @@ public void Layout(Diagram diagram, Theme theme)
 
         if (string.Equals(diagram.DiagramType, "sequencediagram", StringComparison.OrdinalIgnoreCase))
         {
-            LayoutSequenceDiagram(diagram, theme, minW, nodeH, hGap, pad);
+            LayoutSequenceDiagram(diagram, theme, minW, nodeH, hGap, vGap, pad);
             return;
         }
 
@@ -225,6 +225,7 @@ private static void LayoutSequenceDiagram(
         double minW,
         double nodeH,
         double hGap,
+        double vGap,
         double pad)
     {
         // Size each participant node from its label.
@@ -237,10 +238,13 @@ private static void LayoutSequenceDiagram(
         }
 
         // Order participants by their declared index (stored during parsing).
+        // ThenBy ensures deterministic output when the index is missing or two
+        // participants share the same value (e.g., programmatically-built diagrams).
         var ordered = diagram.Nodes.Values
             .OrderBy(n => n.Metadata.TryGetValue("sequence:participantIndex", out var v)
                 ? Convert.ToInt32(v, System.Globalization.CultureInfo.InvariantCulture)
                 : int.MaxValue)
+            .ThenBy(n => n.Id, StringComparer.Ordinal)
             .ToList();
 
         // Place participants in a single row across the top of the diagram.
@@ -251,6 +255,25 @@ private static void LayoutSequenceDiagram(
             node.Y = pad;
             runX += node.Width + hGap;
         }
+
+        // Assign each message edge its own Y row below the participant strip.
+        // Each row is vGap tall, giving space for the arrow line and any label above it.
+        double firstMessageY = pad + nodeH + vGap / 2;
+        double messageRowHeight = vGap;
+
+        foreach (var edge in diagram.Edges)
+        {
+            int msgIdx = edge.Metadata.TryGetValue("sequence:messageIndex", out var idxObj)
+                ? Convert.ToInt32(idxObj, System.Globalization.CultureInfo.InvariantCulture)
+                : 0;
+            edge.Metadata["sequence:messageY"] = firstMessageY + msgIdx * messageRowHeight;
+        }
+
+        // Store the canvas height needed to fit all message rows so the renderer
+        // can size the SVG correctly (node Y extents alone would clip the messages).
+        int edgeCount = diagram.Edges.Count;
+        double canvasHeight = firstMessageY + Math.Max(0, edgeCount) * messageRowHeight + pad;
+        diagram.Metadata["sequence:canvasHeight"] = canvasHeight;
     }
 
     private static void LayoutBlockDiagram(

src/DiagramForge/Models/Edge.cs

@@ -31,6 +31,9 @@ public Edge(string sourceId, string targetId)
 
     /// <summary>Override stroke color (null = inherit from theme).</summary>
     public string? Color { get; set; }
+
+    /// <summary>Arbitrary parser-specific metadata shared with layout and rendering.</summary>
+    public Dictionary<string, object> Metadata { get; } = new();
 }
 
 public enum EdgeLineStyle

src/DiagramForge/Parsers/Mermaid/MermaidSequenceParser.cs

@@ -26,6 +26,7 @@ public Diagram Parse(MermaidDocument document)
 
         var participants = new Dictionary<string, Node>(StringComparer.Ordinal);
         int participantIndex = 0;
+        int messageIndex = 0;
 
         Node GetOrCreateParticipant(string id)
         {
@@ -82,6 +83,7 @@ Node GetOrCreateParticipant(string id)
                     LineStyle = lineStyle,
                     ArrowHead = arrowHead,
                 };
+                edge.Metadata["sequence:messageIndex"] = messageIndex++;
 
                 if (!string.IsNullOrEmpty(msgLabel))
                     edge.Label = new Label(msgLabel!);

src/DiagramForge/Rendering/SvgRenderer.cs

@@ -193,6 +193,21 @@ private static void AppendEdge(StringBuilder sb, Edge edge, Node source, Node ta
             cp2 = $"{F(x2)},{F(y2 - (dy >= 0 ? cpOffset : -cpOffset))}";
         }
 
+        // Per-message Y override: sequence diagrams store an explicit Y position for each
+        // message arrow so that multiple messages between the same participants are stacked
+        // vertically rather than all drawn on top of each other at the node center.
+        if (edge.Metadata.TryGetValue("sequence:messageY", out var msgYObj))
+        {
+            double msgY = Convert.ToDouble(msgYObj, System.Globalization.CultureInfo.InvariantCulture);
+            x1 = sourceCenterX;
+            y1 = msgY;
+            x2 = targetCenterX;
+            y2 = msgY;
+            cpOffset = Math.Abs(x2 - x1) * 0.4;
+            cp1 = $"{F(x1 + (x2 >= x1 ? cpOffset : -cpOffset))},{F(y1)}";
+            cp2 = $"{F(x2 - (x2 >= x1 ? cpOffset : -cpOffset))},{F(y2)}";
+        }
+
         string strokeColor = Escape(edge.Color ?? theme.EdgeColor);
         string strokeDash = edge.LineStyle == EdgeLineStyle.Dashed ? """ stroke-dasharray="6,3" """ :
                             edge.LineStyle == EdgeLineStyle.Dotted ? """ stroke-dasharray="2,3" """ : " ";
@@ -257,6 +272,11 @@ private static double ComputeHeight(Diagram diagram, Theme theme)
         if (diagram.Nodes.Count == 0)
             return 100;
 
+        // Sequence diagrams extend below the participant nodes with per-message rows;
+        // the layout engine stores the required height so node extents don't clip messages.
+        if (diagram.Metadata.TryGetValue("sequence:canvasHeight", out var seqH))
+            return Convert.ToDouble(seqH, System.Globalization.CultureInfo.InvariantCulture);
+
         double maxY = diagram.Nodes.Values.Max(n => n.Y + n.Height);
         if (diagram.Groups.Count > 0)
             maxY = Math.Max(maxY, diagram.Groups.Max(g => g.Y + g.Height));

tests/DiagramForge.E2ETests/Fixtures/mermaid-sequence.expected.svg

@@ -113,7 +113,7 @@ public void Parse_ArrowOperator_MapsToCorrectStyles(
     [Fact]
     public void Parse_LongerOperatorPreferred_DashedArrow()
     {
-        // "-->>‌" must win over "-->‌" on the same position
+        // "-->>" must win over "-->" on the same position
         var diagram = _parser.Parse("sequenceDiagram\n    A-->>B: hi");
 
         var edge = Assert.Single(diagram.Edges);
@@ -188,4 +188,38 @@ public void Parse_LayoutDirection_IsLeftToRight()
 
         Assert.Equal(LayoutDirection.LeftToRight, diagram.LayoutHints.Direction);
     }
+
+    // ── Message index metadata ────────────────────────────────────────────────
+
+    [Fact]
+    public void Parse_MessageIndex_StoredOnEdge()
+    {
+        var diagram = _parser.Parse("sequenceDiagram\n    A->>B: First");
+
+        var edge = Assert.Single(diagram.Edges);
+        Assert.True(edge.Metadata.ContainsKey("sequence:messageIndex"));
+        Assert.Equal(0, Convert.ToInt32(edge.Metadata["sequence:messageIndex"],
+            System.Globalization.CultureInfo.InvariantCulture));
+    }
+
+    [Fact]
+    public void Parse_MultipleMessages_IndexesAreSequential()
+    {
+        const string text = """
+            sequenceDiagram
+                A->>B: First
+                B-->>A: Second
+                A->>B: Third
+            """;
+
+        var diagram = _parser.Parse(text);
+
+        Assert.Equal(3, diagram.Edges.Count);
+        for (int i = 0; i < diagram.Edges.Count; i++)
+        {
+            int idx = Convert.ToInt32(diagram.Edges[i].Metadata["sequence:messageIndex"],
+                System.Globalization.CultureInfo.InvariantCulture);
+            Assert.Equal(i, idx);
+        }
+    }
 }