feat(render): update renderers to support new flow and phase features

Mermaid renderer:
- Render conditions using opt blocks
- Render alternatives using alt/else blocks
- Render notes using note right of
- Render annotations as prefixed notes
- Render nested phases as colored rect blocks

PlantUML renderer:
- Render conditions using opt blocks
- Render alternatives using alt/else blocks
- Render notes using note right
- Render annotations with OpenIconic icons
- Render nested phases as colored box containers

D2 renderer:
- Render conditions as label prefixes
- Render alternatives as grouped flows
- Render notes as tooltips
- Render annotations as separate note messages
- Render nested phases as nested groups

DOT renderer:
- Render conditions as edge label prefixes
- Render alternatives as separate colored edges
- Add ShowConditions and ShowAnnotations options

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

Author: grokify

render/d2.go

@@ -33,6 +33,18 @@ type D2Renderer struct {
 
 	// Direction sets the diagram direction (down, right, left, up).
 	Direction string
+
+	// ShowNotes renders flow notes as D2 notes/labels.
+	ShowNotes bool
+
+	// ShowAnnotations renders flow annotations.
+	ShowAnnotations bool
+
+	// ShowConditions indicates conditional flows.
+	ShowConditions bool
+
+	// ShowAlternatives renders alternative paths.
+	ShowAlternatives bool
 }
 
 // NewD2 creates a new D2 renderer with default options (sequence diagram).
@@ -42,6 +54,10 @@ func NewD2() *D2Renderer {
 		Title:            true,
 		ShowDescriptions: false,
 		Direction:        "right",
+		ShowNotes:        true,
+		ShowAnnotations:  true,
+		ShowConditions:   true,
+		ShowAlternatives: true,
 	}
 }
 
@@ -52,6 +68,10 @@ func NewD2Flow() *D2Renderer {
 		Title:            true,
 		ShowDescriptions: false,
 		Direction:        "right",
+		ShowNotes:        true,
+		ShowAnnotations:  true,
+		ShowConditions:   true,
+		ShowAlternatives: true,
 	}
 }
 
@@ -62,6 +82,10 @@ func NewD2Arch() *D2Renderer {
 		Title:            true,
 		ShowDescriptions: false,
 		Direction:        "right",
+		ShowNotes:        true,
+		ShowAnnotations:  true,
+		ShowConditions:   true,
+		ShowAlternatives: true,
 	}
 }
 
@@ -122,46 +146,40 @@ func (r *D2Renderer) renderSequence(p *pidl.Protocol) string {
 	// Track sequence number for ordering
 	seq := 1
 
-	// Track current phase for grouping
+	// Track current phase for grouping and nesting
 	currentPhase := ""
-	inPhaseGroup := false
+	phaseStack := []string{}
 
 	for _, f := range p.Flows {
-		// Handle phase changes
-		if f.Phase != "" && f.Phase != currentPhase {
-			if inPhaseGroup {
+		// Handle phase changes with nesting support
+		if f.Phase != currentPhase {
+			// Close previous phase groups
+			for range phaseStack {
 				sb.WriteString("  }\n\n")
 			}
-			phase := p.PhaseByID(f.Phase)
-			if phase != nil {
-				fmt.Fprintf(&sb, "  %s: %s {\n", r.sanitizeID(f.Phase), phase.Name)
-				inPhaseGroup = true
+			phaseStack = nil
+
+			// Open new phase groups (including parent hierarchy)
+			if f.Phase != "" {
+				phase := p.PhaseByID(f.Phase)
+				if phase != nil {
+					phaseStack = r.openPhaseGroups(&sb, p, phase)
+				}
 			}
 			currentPhase = f.Phase
 		}
 
 		// Render the flow
 		indent := "  "
-		if inPhaseGroup {
-			indent = "    "
+		for range phaseStack {
+			indent += "  "
 		}
 
-		from := r.sanitizeID(f.From)
-		to := r.sanitizeID(f.To)
-		label := f.DisplayLabel()
-
-		// Add mode annotation
-		if ann := r.modeAnnotation(f.EffectiveMode()); ann != "" {
-			label = fmt.Sprintf("%s (%s)", label, ann)
-		}
-
-		// D2 sequence diagram message syntax
-		arrow := r.modeToArrow(f.EffectiveMode())
-		fmt.Fprintf(&sb, "%sseq%d: %s %s %s: %s\n", indent, seq, from, arrow, to, label)
-		seq++
+		seq = r.renderSequenceFlow(&sb, p, f, indent, seq)
 	}
 
-	if inPhaseGroup {
+	// Close remaining phase groups
+	for range phaseStack {
 		sb.WriteString("  }\n")
 	}
 
@@ -170,6 +188,104 @@ func (r *D2Renderer) renderSequence(p *pidl.Protocol) string {
 	return sb.String()
 }
 
+// openPhaseGroups opens D2 groups for a phase and its parent hierarchy, returns the stack.
+func (r *D2Renderer) openPhaseGroups(sb *strings.Builder, p *pidl.Protocol, phase *pidl.Phase) []string {
+	// Build the hierarchy from root to current phase
+	var hierarchy []*pidl.Phase
+	current := phase
+	for current != nil {
+		hierarchy = append([]*pidl.Phase{current}, hierarchy...)
+		if current.Parent == "" {
+			break
+		}
+		current = p.PhaseByID(current.Parent)
+	}
+
+	// Open groups from root to leaf
+	var stack []string
+	for i, ph := range hierarchy {
+		indent := "  "
+		for j := 0; j < i; j++ {
+			indent += "  "
+		}
+		fmt.Fprintf(sb, "%s%s: %s {\n", indent, r.sanitizeID(ph.ID), ph.Name)
+		stack = append(stack, ph.ID)
+	}
+
+	return stack
+}
+
+// renderSequenceFlow renders a single flow in a D2 sequence diagram.
+func (r *D2Renderer) renderSequenceFlow(sb *strings.Builder, _ *pidl.Protocol, f pidl.Flow, indent string, seq int) int {
+	from := r.sanitizeID(f.From)
+	to := r.sanitizeID(f.To)
+	label := f.DisplayLabel()
+
+	// Add condition to label if present
+	if r.ShowConditions && f.HasCondition() {
+		label = fmt.Sprintf("[%s] %s", f.Condition, label)
+	}
+
+	// Add mode annotation
+	if ann := r.modeAnnotation(f.EffectiveMode()); ann != "" {
+		label = fmt.Sprintf("%s (%s)", label, ann)
+	}
+
+	// D2 sequence diagram message syntax
+	arrow := r.modeToArrow(f.EffectiveMode())
+	fmt.Fprintf(sb, "%sseq%d: %s %s %s: %s", indent, seq, from, arrow, to, label)
+
+	// Add note as tooltip if present
+	if r.ShowNotes && f.HasNote() {
+		fmt.Fprintf(sb, " {\n%s  tooltip: %s\n%s}", indent, f.Note, indent)
+	}
+
+	sb.WriteString("\n")
+	seq++
+
+	// Render annotations as separate note messages
+	if r.ShowAnnotations && f.HasAnnotations() {
+		for _, ann := range f.Annotations {
+			prefix := r.annotationPrefix(ann.Type)
+			fmt.Fprintf(sb, "%snote%d: %s -> %s: %s%s\n", indent, seq, to, to, prefix, ann.Text)
+			seq++
+		}
+	}
+
+	// Render alternatives as additional flows
+	if r.ShowAlternatives && f.HasAlternatives() {
+		for _, alt := range f.Alternatives {
+			fmt.Fprintf(sb, "%salt%d: [%s] {\n", indent, seq, alt.Condition)
+			altIndent := indent + "  "
+			for _, altFlow := range alt.Flows {
+				seq = r.renderSequenceFlow(sb, nil, altFlow, altIndent, seq)
+			}
+			fmt.Fprintf(sb, "%s}\n", indent)
+			seq++
+		}
+	}
+
+	return seq
+}
+
+// annotationPrefix returns a visual prefix for annotation types.
+func (r *D2Renderer) annotationPrefix(t pidl.AnnotationType) string {
+	switch t {
+	case pidl.AnnotationTypeSecurity:
+		return "⚠️ SECURITY: "
+	case pidl.AnnotationTypePerformance:
+		return "⏱️ PERF: "
+	case pidl.AnnotationTypeDeprecated:
+		return "🚫 DEPRECATED: "
+	case pidl.AnnotationTypeWarning:
+		return "⚠️ WARNING: "
+	case pidl.AnnotationTypeError:
+		return "❌ ERROR: "
+	default:
+		return ""
+	}
+}
+
 // renderFlow renders a D2 data flow diagram.
 func (r *D2Renderer) renderFlow(p *pidl.Protocol) string {
 	var sb strings.Builder

render/dot.go

@@ -21,15 +21,23 @@ type DOTRenderer struct {
 
 	// ShowPhases groups nodes by phase using subgraphs.
 	ShowPhases bool
+
+	// ShowConditions includes condition text in edge labels.
+	ShowConditions bool
+
+	// ShowAnnotations includes annotation counts in edge labels.
+	ShowAnnotations bool
 }
 
 // NewDOT creates a new DOT renderer with default options.
 func NewDOT() *DOTRenderer {
 	return &DOTRenderer{
-		Title:      true,
-		RankDir:    "LR",
-		MergeEdges: true,
-		ShowPhases: false,
+		Title:           true,
+		RankDir:         "LR",
+		MergeEdges:      true,
+		ShowPhases:      false,
+		ShowConditions:  true,
+		ShowAnnotations: false,
 	}
 }
 
@@ -129,8 +137,32 @@ func (r *DOTRenderer) renderAllEdges(sb *strings.Builder, p *pidl.Protocol) {
 	for i, f := range p.Flows {
 		style := r.modeToStyle(f.EffectiveMode())
 		label := r.escapeString(f.DisplayLabel())
+
+		// Add condition prefix if present and enabled
+		if r.ShowConditions && f.HasCondition() {
+			label = fmt.Sprintf("[%s]\\n%s", r.escapeString(f.Condition), label)
+		}
+
+		// Add annotation indicator if present and enabled
+		if r.ShowAnnotations && f.HasAnnotations() {
+			label = fmt.Sprintf("%s\\n(%d annotations)", label, len(f.Annotations))
+		}
+
 		fmt.Fprintf(sb, "    %s -> %s [label=\"%d. %s\"%s];\n",
 			f.From, f.To, i+1, label, style)
+
+		// Render alternative edges if present
+		for _, alt := range f.Alternatives {
+			for j, altFlow := range alt.Flows {
+				altStyle := r.modeToStyle(altFlow.EffectiveMode())
+				altLabel := r.escapeString(altFlow.DisplayLabel())
+				if r.ShowConditions {
+					altLabel = fmt.Sprintf("[ALT: %s]\\n%s", r.escapeString(alt.Condition), altLabel)
+				}
+				fmt.Fprintf(sb, "    %s -> %s [label=\"%d.%d. %s\"%s, color=gray];\n",
+					altFlow.From, altFlow.To, i+1, j+1, altLabel, altStyle)
+			}
+		}
 	}
 }