feat: add Subtitle property to Diagram model with sequence diagram support

Agent-Logs-Url: https://github.com/jongalloway/DiagramForge/sessions/e40e4541-4e5f-4722-9ac9-3fe1f49faa8e

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

Author: Copilot

doc/frontmatter.md

@@ -27,6 +27,8 @@ After the closing fence, the remaining content is parsed normally as Mermaid or
 | Key | Accepted forms | Notes |
 | --- | --- | --- |
 | `theme` | Built-in theme name | Uses `Theme.GetByName(...)`; unknown names throw. |
+| `title` | `title` | Sets `Diagram.Title`; inline parser directives take precedence. |
+| `subtitle` | `subtitle` | Sets `Diagram.Subtitle`; rendered below the title in a smaller, muted font. Inline parser directives take precedence. |
 | `palette` | Single-line JSON array of hex strings | Example: `["#FF0000", "#00FF00"]` |
 | `borderStyle` | `borderStyle`, `border-style` | Values: `solid`, `subtle`, `rainbow` |
 | `fillStyle` | `fillStyle`, `fill-style` | Values: `flat`, `subtle`, `diagonal-strong` |

doc/rendering-pipeline.md

@@ -120,7 +120,8 @@ in this order:
 2. **`<defs>`** — arrow markers for edge arrowheads.
 3. **Background `<rect>`** — full-canvas fill with rounded corners.
 4. **Title `<text>`** — centered at the top, if `Diagram.Title` is set.
-5. **Groups** — `<rect>` + optional `<text>` label for each group. Rendered
+5. **Subtitle `<text>`** — centered below the title in a smaller, muted font, if `Diagram.Subtitle` is set.
+6. **Groups** — `<rect>` + optional `<text>` label for each group. Rendered
    first so they appear behind nodes.
 6. **Edges** — cubic Bézier `<path>` elements with anchor points on node edges.
    Rendered behind nodes. Optional edge labels at the midpoint.

doc/semantic-model.md

@@ -20,6 +20,7 @@ All model types live in `DiagramForge.Models`.
 ```
 Diagram
  ├── Title              string?
+ ├── Subtitle           string?
  ├── SourceSyntax       string?
  ├── DiagramType        string?
  ├── LayoutHints        LayoutHints
@@ -60,7 +61,8 @@ The root container. One `Diagram` instance represents one rendered image.
 
 | Property | Type | Set by | Description |
 |----------|------|--------|-------------|
-| `Title` | `string?` | Parser | Optional human-readable title displayed above the diagram. |
+| `Title` | `string?` | Parser / Frontmatter | Optional human-readable title displayed above the diagram. |
+| `Subtitle` | `string?` | Parser / Frontmatter | Optional subtitle displayed below the title in a smaller, muted font. |
 | `SourceSyntax` | `string?` | Parser | Identifies the parser that produced this model (e.g., `"mermaid"`, `"conceptual"`). |
 | `DiagramType` | `string?` | Parser | Specific diagram variant (e.g., `"flowchart"`, `"venn"`, `"mindmap"`). |
 | `Nodes` | `Dictionary<string, Node>` | Parser | All nodes, keyed by unique ID. |

src/DiagramForge/Abstractions/IDiagramSemanticModelBuilder.cs

@@ -12,6 +12,9 @@ public interface IDiagramSemanticModelBuilder
     /// <summary>Sets the optional diagram title.</summary>
     IDiagramSemanticModelBuilder WithTitle(string title);
 
+    /// <summary>Sets the optional diagram subtitle displayed below the title.</summary>
+    IDiagramSemanticModelBuilder WithSubtitle(string subtitle);
+
     /// <summary>Specifies the source syntax identifier (e.g., "mermaid").</summary>
     IDiagramSemanticModelBuilder WithSourceSyntax(string syntaxId);
 

src/DiagramForge/DiagramRenderer.cs

@@ -198,6 +198,14 @@ public string Render(string diagramText, Theme? theme, string? paletteJson, bool
             diagram.LayoutHints.EdgeRouting = frontmatter.EdgeRouting.Value;
         }
 
+        // Frontmatter title/subtitle override the parser-supplied values only when the parser
+        // did not already set them (inline directives take precedence over frontmatter).
+        if (frontmatter.Title is not null && string.IsNullOrWhiteSpace(diagram.Title))
+            diagram.Title = frontmatter.Title;
+
+        if (frontmatter.Subtitle is not null && string.IsNullOrWhiteSpace(diagram.Subtitle))
+            diagram.Subtitle = frontmatter.Subtitle;
+
         ResolveIcons(diagram);
         _layoutEngine.Layout(diagram, effectiveTheme);
         return _svgRenderer.Render(diagram, effectiveTheme);
@@ -407,6 +415,8 @@ private static FrontmatterOptions ParseFrontmatter(string raw)
         string? parsedShadowStyle = null;
         bool? parsedTransparentBackground = null;
         EdgeRouting? parsedEdgeRouting = null;
+        string? parsedTitle = null;
+        string? parsedSubtitle = null;
 
         foreach (string rawLine in frontmatter.Split('\n'))
         {
@@ -468,9 +478,17 @@ private static FrontmatterOptions ParseFrontmatter(string raw)
             {
                 parsedEdgeRouting = ParseEdgeRouting(Unquote(line["edge-routing:".Length..].Trim()), raw);
             }
+            else if (line.StartsWith("title:", StringComparison.OrdinalIgnoreCase))
+            {
+                parsedTitle = Unquote(line["title:".Length..].Trim());
+            }
+            else if (line.StartsWith("subtitle:", StringComparison.OrdinalIgnoreCase))
+            {
+                parsedSubtitle = Unquote(line["subtitle:".Length..].Trim());
+            }
         }
 
-        return new FrontmatterOptions(diagramText, parsedTheme, parsedPaletteJson, parsedBorderStyle, parsedFillStyle, parsedShadowStyle, parsedTransparentBackground, parsedEdgeRouting);
+        return new FrontmatterOptions(diagramText, parsedTheme, parsedPaletteJson, parsedBorderStyle, parsedFillStyle, parsedShadowStyle, parsedTransparentBackground, parsedEdgeRouting, parsedTitle, parsedSubtitle);
     }
 
     private static void ApplyBorderStyle(Theme theme, string borderStyle)
@@ -607,7 +625,7 @@ private static bool ParseBoolean(string rawValue, string raw, string fieldName)
         };
     }
 
-    private sealed record FrontmatterOptions(string DiagramText, Theme? Theme, string? PaletteJson, string? BorderStyle, string? FillStyle, string? ShadowStyle, bool? TransparentBackground, EdgeRouting? EdgeRouting = null);
+    private sealed record FrontmatterOptions(string DiagramText, Theme? Theme, string? PaletteJson, string? BorderStyle, string? FillStyle, string? ShadowStyle, bool? TransparentBackground, EdgeRouting? EdgeRouting = null, string? Title = null, string? Subtitle = null);
 }
 
 [System.Text.Json.Serialization.JsonSerializable(typeof(List<string>))]

src/DiagramForge/DiagramSemanticModelBuilder.cs

@@ -16,6 +16,12 @@ public IDiagramSemanticModelBuilder WithTitle(string title)
         return this;
     }
 
+    public IDiagramSemanticModelBuilder WithSubtitle(string subtitle)
+    {
+        _diagram.Subtitle = subtitle;
+        return this;
+    }
+
     public IDiagramSemanticModelBuilder WithSourceSyntax(string syntaxId)
     {
         _diagram.SourceSyntax = syntaxId;

src/DiagramForge/Layout/DefaultLayoutEngine.Sequence.cs

@@ -23,16 +23,25 @@ private static void LayoutSequenceDiagram(
             .ThenBy(n => n.Id, StringComparer.Ordinal)
             .ToList();
 
+        // Reserve vertical space for the title and/or subtitle so they don't overlap participants.
+        bool hasTitle = !string.IsNullOrWhiteSpace(diagram.Title);
+        bool hasSubtitle = !string.IsNullOrWhiteSpace(diagram.Subtitle);
+        double headingOffset = 0;
+        if (hasTitle || hasSubtitle)
+            headingOffset += theme.TitleFontSize + 8;
+        if (hasTitle && hasSubtitle)
+            headingOffset += theme.FontSize + 4;
+
         double runX = pad;
         double participantStripHeight = ordered.Max(node => node.Height);
         foreach (var node in ordered)
         {
             node.X = runX;
-            node.Y = pad + (participantStripHeight - node.Height);
+            node.Y = pad + headingOffset + (participantStripHeight - node.Height);
             runX += node.Width + hGap;
         }
 
-        double firstMessageY = pad + participantStripHeight + vGap / 2;
+        double firstMessageY = pad + headingOffset + participantStripHeight + vGap / 2;
         double messageRowHeight = vGap;
 
         foreach (var edge in diagram.Edges)

src/DiagramForge/Models/Diagram.cs

@@ -9,6 +9,9 @@ public class Diagram
     /// <summary>Optional human-readable title of the diagram.</summary>
     public string? Title { get; set; }
 
+    /// <summary>Optional subtitle displayed below the title in a smaller, muted font.</summary>
+    public string? Subtitle { get; set; }
+
     /// <summary>Identifies the source syntax that produced this model (e.g., "mermaid", "conceptual").</summary>
     public string? SourceSyntax { get; set; }
 

src/DiagramForge/Parsers/Mermaid/MermaidSequenceParser.cs

@@ -44,6 +44,24 @@ Node GetOrCreateParticipant(string id)
         {
             var line = document.Lines[i];
 
+            // title: <text>  — diagram title directive
+            if (line.StartsWith("title:", StringComparison.OrdinalIgnoreCase))
+            {
+                var titleText = line["title:".Length..].Trim().Trim('"');
+                if (!string.IsNullOrEmpty(titleText))
+                    builder.WithTitle(titleText);
+                continue;
+            }
+
+            // subtitle: <text>  — diagram subtitle directive
+            if (line.StartsWith("subtitle:", StringComparison.OrdinalIgnoreCase))
+            {
+                var subtitleText = line["subtitle:".Length..].Trim().Trim('"');
+                if (!string.IsNullOrEmpty(subtitleText))
+                    builder.WithSubtitle(subtitleText);
+                continue;
+            }
+
             // participant ID
             // participant ID as Alias
             if (line.StartsWith("participant ", StringComparison.OrdinalIgnoreCase))

src/DiagramForge/Rendering/SvgRenderer.cs

@@ -39,6 +39,8 @@ public string Render(Diagram diagram, Theme theme)
         // Title — diagram-type layouts may override font size / position via metadata.
         // Prefer the namespaced "diagram:titleFontSize" / "diagram:titleY" keys; fall back
         // to the legacy un-namespaced keys for backward compatibility.
+        double renderedTitleFontSize = 0;
+        double renderedTitleY = 0;
         if (!string.IsNullOrWhiteSpace(diagram.Title))
         {
             double titleFontSize;
@@ -55,6 +57,18 @@ public string Render(Diagram diagram, Theme theme)
             else
                 titleY = theme.DiagramPadding - 4;
             sb.AppendLine($"""  <text x="{SvgRenderSupport.F(width / 2)}" y="{SvgRenderSupport.F(titleY)}" text-anchor="middle" font-family="{SvgRenderSupport.Escape(theme.FontFamily)}" font-size="{SvgRenderSupport.F(titleFontSize)}" font-weight="bold" fill="{SvgRenderSupport.Escape(theme.TitleTextColor)}">{SvgRenderSupport.Escape(diagram.Title)}</text>""");
+            renderedTitleFontSize = titleFontSize;
+            renderedTitleY = titleY;
+        }
+
+        // Subtitle — rendered below the title in a smaller, muted font.
+        if (!string.IsNullOrWhiteSpace(diagram.Subtitle))
+        {
+            double subtitleFontSize = theme.FontSize;
+            double subtitleY = !string.IsNullOrWhiteSpace(diagram.Title)
+                ? renderedTitleY + renderedTitleFontSize + 4
+                : theme.DiagramPadding - 4;
+            sb.AppendLine($"""  <text x="{SvgRenderSupport.F(width / 2)}" y="{SvgRenderSupport.F(subtitleY)}" text-anchor="middle" font-family="{SvgRenderSupport.Escape(theme.FontFamily)}" font-size="{SvgRenderSupport.F(subtitleFontSize)}" fill="{SvgRenderSupport.Escape(theme.SubtleTextColor)}">{SvgRenderSupport.Escape(diagram.Subtitle)}</text>""");
         }
 
         // Groups (render behind nodes). Parents render first so nested child groups
@@ -207,7 +221,8 @@ private static double ComputeHeight(Diagram diagram, Theme theme)
         if (TryGetCycleArcBounds(diagram, out _, out _, out _, out var cycleMaxY))
             maxY = Math.Max(maxY, cycleMaxY);
         double titleOffset = !string.IsNullOrWhiteSpace(diagram.Title) ? theme.TitleFontSize + 8 : 0;
-        return maxY + theme.DiagramPadding + titleOffset;
+        double subtitleOffset = !string.IsNullOrWhiteSpace(diagram.Subtitle) ? theme.FontSize + 4 : 0;
+        return maxY + theme.DiagramPadding + titleOffset + subtitleOffset;
     }
 
     private static bool TryGetCycleArcBounds(Diagram diagram, out double minX, out double maxX, out double minY, out double maxY)