feat(sequence): central connections (mermaid 11.16)

Renders mermaid's central-connection markers — "()" on either side of
any message arrow (A ()->>() B) — as a circle where the message meets
that lifeline: o────►o. Composes with all ten arrow types and
self-messages. Grammar grounded in sequenceDiagram.jison (the "()"
lexer token + three signal rules: forward, reverse, dual).

Unquoted participant names now exclude "(" so the marker binds to the
arrow rather than the name — mermaid's ACTOR token excludes parentheses
too, so this is parity-positive. Golden files hand-authored first as
the output spec; malformed near-miss forms stay loud errors.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: cgreeno

README.md

@@ -596,6 +596,7 @@ Note that with `--coords` enabled, the grid-coords shown show the starting locat
 - [x] Basic message syntax (`A->>B: message`)
 - [x] Solid and dotted arrows, with or without an arrowhead (`->>`, `-->>`, `->`, `-->`)
 - [x] Cross (`-x`, `--x`), async point (`-)`, `--)`) and bidirectional (`<<->>`, `<<-->>`) arrows
+- [x] Central connections (`A ()->>() B`) on any arrow type
 - [x] Self-messages (`A->>A: think`)
 - [x] Participant declarations (`participant Alice`)
 - [x] Participant aliases (`participant A as Alice`)

cmd/testdata/sequence-ascii/central_connection_self.txt

@@ -0,0 +1,13 @@
+sequenceDiagram
+    participant A
+    A ()->>() A: t1
+---
++---+
+| A |
++-+-+
+  |
+  | t1
+  o--+
+  |  |
+  o<-+
+  |

cmd/testdata/sequence-ascii/central_connections.txt

@@ -0,0 +1,28 @@
+sequenceDiagram
+    participant A
+    participant B
+    A ->>() B: t1
+    A ()->> B: t2
+    A ()->>() B: t3
+    B ()--x() A: t4
+    A ()<<->>() B: t5
+---
++---+     +---+
+| A |     | B |
++-+-+     +-+-+
+  |         |
+  | t1      |
+  +-------->o
+  |         |
+  | t2      |
+  o-------->|
+  |         |
+  | t3      |
+  o-------->o
+  |         |
+  | t4      |
+  ox........o
+  |         |
+  | t5      |
+  o<------->o
+  |         |

cmd/testdata/sequence/central_connection_self.txt

@@ -0,0 +1,13 @@
+sequenceDiagram
+    participant A
+    A ()->>() A: t1
+---
+┌───┐
+│ A │
+└─┬─┘
+  │
+  │ t1
+  o──┐
+  │  │
+  o◄─┘
+  │

cmd/testdata/sequence/central_connections.txt

@@ -0,0 +1,28 @@
+sequenceDiagram
+    participant A
+    participant B
+    A ->>() B: t1
+    A ()->> B: t2
+    A ()->>() B: t3
+    B ()--x() A: t4
+    A ()<<->>() B: t5
+---
+┌───┐     ┌───┐
+│ A │     │ B │
+└─┬─┘     └─┬─┘
+  │         │
+  │ t1      │
+  ├────────►o
+  │         │
+  │ t2      │
+  o────────►│
+  │         │
+  │ t3      │
+  o────────►o
+  │         │
+  │ t4      │
+  o×┈┈┈┈┈┈┈┈o
+  │         │
+  │ t5      │
+  o◄───────►o
+  │         │

pkg/sequence/arrows_test.go

@@ -71,20 +71,50 @@ func TestArrowSpecParityForms(t *testing.T) {
 	}
 }
 
-// TestCentralConnectionsRejected documents that mermaid's central-connection
-// syntax (circle markers at the lifeline: "A ()->>() B", released in mermaid
-// 11.16) is rejected loudly rather than silently mis-parsed. It composes with
-// every arrow type, so supporting it is its own follow-up.
-func TestCentralConnectionsRejected(t *testing.T) {
+// TestCentralConnections checks mermaid's central-connection syntax (circle
+// markers at the lifeline, mermaid 11.16): "()" on either side of any arrow.
+// The "()" is its own token in mermaid's lexer, so spaces around it are legal.
+func TestCentralConnections(t *testing.T) {
+	tests := []struct {
+		in       string
+		arrow    ArrowType
+		from, to bool
+	}{
+		{"sequenceDiagram\n Alice ()->>() Bob: dual", SolidArrow, true, true},
+		{"sequenceDiagram\n Alice ()-x() Bob: cross dual", SolidCross, true, true},
+		{"sequenceDiagram\n Alice ()<<->>() Bob: bidirectional dual", BidirectionalSolid, true, true},
+		{"sequenceDiagram\n Alice ->>() Bob: forward", SolidArrow, false, true},
+		{"sequenceDiagram\n Alice ()->> Bob: reverse", SolidArrow, true, false},
+		{"sequenceDiagram\n Alice () -->> () Bob: spaced dual", DottedArrow, true, true},
+		{"sequenceDiagram\n Alice ()--)() Bob: point dual", DottedPoint, true, true},
+	}
+	for _, tt := range tests {
+		sd, err := Parse(tt.in)
+		if err != nil {
+			t.Errorf("Parse(%q): %v", tt.in, err)
+			continue
+		}
+		if len(sd.Messages) != 1 {
+			t.Errorf("Parse(%q): expected 1 message, got %d", tt.in, len(sd.Messages))
+			continue
+		}
+		m := sd.Messages[0]
+		if m.ArrowType != tt.arrow || m.CentralFrom != tt.from || m.CentralTo != tt.to {
+			t.Errorf("Parse(%q): got arrow=%v centralFrom=%v centralTo=%v, want %v/%v/%v",
+				tt.in, m.ArrowType, m.CentralFrom, m.CentralTo, tt.arrow, tt.from, tt.to)
+		}
+	}
+}
+
+// TestMalformedCentralConnectionsRejected keeps near-miss circle forms loud.
+func TestMalformedCentralConnectionsRejected(t *testing.T) {
 	for _, in := range []string{
-		"sequenceDiagram\n Alice ()->>() Bob: dual",
-		"sequenceDiagram\n Alice ()-x() Bob: cross dual",
-		"sequenceDiagram\n Alice ()<<->>() Bob: bidirectional dual",
-		"sequenceDiagram\n Alice ->>() Bob: forward",
-		"sequenceDiagram\n Alice ()->> Bob: reverse",
+		"sequenceDiagram\n Alice (->>) Bob: parens around arrow",
+		"sequenceDiagram\n Alice ( )->> Bob: space inside circle",
+		"sequenceDiagram\n Alice (()->> Bob: unbalanced",
 	} {
 		if _, err := Parse(in); err == nil {
-			t.Errorf("expected error for central-connection syntax %q, got none", in)
+			t.Errorf("expected error for malformed central connection %q, got none", in)
 		}
 	}
 }

pkg/sequence/charset.go

@@ -17,6 +17,7 @@ type BoxChars struct {
 	CrossHead    rune // head of -x / --x (lost/failed message)
 	PointRight   rune // head of -) / --) (async message)
 	PointLeft    rune
+	Circle       rune // central-connection marker ("()") on a lifeline
 	SolidLine    rune
 	DottedLine   rune
 	SelfTopRight rune
@@ -39,28 +40,32 @@ var ASCII = BoxChars{
 	CrossHead:    'x',
 	PointRight:   ')',
 	PointLeft:    '(',
+	Circle:       'o',
 	SolidLine:    '-',
 	DottedLine:   '.',
 	SelfTopRight: '+',
 	SelfBottom:   '+',
 }
 
 var Unicode = BoxChars{
-	TopLeft:      '┌',
-	TopRight:     '┐',
-	BottomLeft:   '└',
-	BottomRight:  '┘',
-	Horizontal:   '─',
-	Vertical:     '│',
-	TeeDown:      '┬',
-	TeeRight:     '├',
-	TeeLeft:      '┤',
-	Cross:        '┼',
-	ArrowRight:   '►',
-	ArrowLeft:    '◄',
-	CrossHead:    '×',
-	PointRight:   ')',
-	PointLeft:    '(',
+	TopLeft:     '┌',
+	TopRight:    '┐',
+	BottomLeft:  '└',
+	BottomRight: '┘',
+	Horizontal:  '─',
+	Vertical:    '│',
+	TeeDown:     '┬',
+	TeeRight:    '├',
+	TeeLeft:     '┤',
+	Cross:       '┼',
+	ArrowRight:  '►',
+	ArrowLeft:   '◄',
+	CrossHead:   '×',
+	PointRight:  ')',
+	PointLeft:   '(',
+	// 'o' rather than '○': the latter is East-Asian-ambiguous width and
+	// would break column alignment in CJK-capable terminals.
+	Circle:       'o',
 	SolidLine:    '─',
 	DottedLine:   '┈',
 	SelfTopRight: '┐',

pkg/sequence/parser.go

@@ -18,15 +18,19 @@ var (
 	// participantRegex matches participant declarations: participant [ID] [as Label]
 	participantRegex = regexp.MustCompile(`(?i)^\s*participant\s+(?:"([^"]+)"|(\S+))(?:\s+as\s+(.+))?$`)
 
-	// messageRegex matches messages: [From][arrow][To]: [Label]. The arrow is
-	// one of mermaid's ten message types: ->> / -->> (arrowhead), -> / -->
-	// (open), -x / --x (cross), -) / --) (async point), <<->> / <<-->>
-	// (bidirectional). Longer alternatives come first so e.g. "-->>" is never
-	// consumed as "-->". Unquoted participant names exclude the arrow
-	// characters (- > <) so a malformed arrow cannot be silently absorbed into
-	// a name — it fails to match and is reported as invalid syntax rather than
-	// rendered wrongly.
-	messageRegex = regexp.MustCompile(`^\s*(?:"([^"]+)"|([^\s<>-]+))\s*(<<-->>|<<->>|-->>|--[x)]|-->|->>|-[x)]|->)\s*(?:"([^"]+)"|([^\s<>-]+))\s*:\s*(.*)$`)
+	// messageRegex matches messages: [From][()][arrow][()][To]: [Label]. The
+	// arrow is one of mermaid's ten message types: ->> / -->> (arrowhead),
+	// -> / --> (open), -x / --x (cross), -) / --) (async point), <<->> /
+	// <<-->> (bidirectional). Longer alternatives come first so e.g. "-->>"
+	// is never consumed as "-->". An optional "()" on either side of the
+	// arrow marks a central connection (mermaid 11.16): a circle where the
+	// message meets that lifeline. Unquoted participant names exclude the
+	// arrow characters (- > <) so a malformed arrow cannot be silently
+	// absorbed into a name — it fails to match and is reported as invalid
+	// syntax rather than rendered wrongly — and "(" so a central-connection
+	// marker binds to the arrow, not the name (mermaid's ACTOR token excludes
+	// parentheses too).
+	messageRegex = regexp.MustCompile(`^\s*(?:"([^"]+)"|([^\s<>(-]+))\s*(\(\))?\s*(<<-->>|<<->>|-->>|--[x)]|-->|->>|-[x)]|->)\s*(\(\))?\s*(?:"([^"]+)"|([^\s<>(-]+))\s*:\s*(.*)$`)
 
 	// autonumberRegex matches the autonumber directive
 	autonumberRegex = regexp.MustCompile(`(?i)^\s*autonumber\s*$`)
@@ -189,7 +193,12 @@ type Message struct {
 	To        *Participant
 	Label     string
 	ArrowType ArrowType
-	Number    int // Message number when autonumber is enabled (0 means no number)
+	// CentralFrom / CentralTo mark central connections (mermaid's "()" on
+	// either side of the arrow): a circle drawn where the message meets that
+	// participant's lifeline.
+	CentralFrom bool
+	CentralTo   bool
+	Number      int // Message number when autonumber is enabled (0 means no number)
 }
 
 type ArrowType int
@@ -485,14 +494,16 @@ func (sd *SequenceDiagram) parseMessage(line string, participants map[string]*Pa
 		fromID = match[1]
 	}
 
-	arrow := match[3]
+	centralFrom := match[3] != ""
+	arrow := match[4]
+	centralTo := match[5] != ""
 
-	toID := match[5]
-	if match[4] != "" {
-		toID = match[4]
+	toID := match[7]
+	if match[6] != "" {
+		toID = match[6]
 	}
 
-	label := strings.TrimSpace(match[6])
+	label := strings.TrimSpace(match[8])
 
 	from := sd.getParticipant(fromID, participants)
 	to := sd.getParticipant(toID, participants)
@@ -527,11 +538,13 @@ func (sd *SequenceDiagram) parseMessage(line string, participants map[string]*Pa
 	}
 
 	msg := &Message{
-		From:      from,
-		To:        to,
-		Label:     label,
-		ArrowType: aType,
-		Number:    msgNumber,
+		From:        from,
+		To:          to,
+		Label:       label,
+		ArrowType:   aType,
+		CentralFrom: centralFrom,
+		CentralTo:   centralTo,
+		Number:      msgNumber,
 	}
 	sd.Messages = append(sd.Messages, msg)
 	sd.Events = append(sd.Events, Event{Kind: EventMessage, Message: msg})

pkg/sequence/renderer.go

@@ -671,6 +671,13 @@ func renderMessage(msg *Message, layout *diagramLayout, chars BoxChars) []string
 		}
 		line[from] = chars.TeeLeft
 	}
+	// Central connections replace the lifeline attachment with a circle.
+	if msg.CentralFrom {
+		line[from] = chars.Circle
+	}
+	if msg.CentralTo {
+		line[to] = chars.Circle
+	}
 	lines = append(lines, strings.TrimRight(string(line), " "))
 	return lines
 }
@@ -730,6 +737,9 @@ func renderSelfMessage(msg *Message, layout *diagramLayout, chars BoxChars) []st
 
 	l1 := ensureWidth(buildLifeline(layout, chars))
 	l1[center] = chars.TeeRight
+	if msg.CentralFrom {
+		l1[center] = chars.Circle
+	}
 	for i := 1; i < width; i++ {
 		l1[center+i] = style
 	}
@@ -742,6 +752,9 @@ func renderSelfMessage(msg *Message, layout *diagramLayout, chars BoxChars) []st
 
 	l3 := ensureWidth(buildLifeline(layout, chars))
 	l3[center] = chars.Vertical
+	if msg.CentralTo {
+		l3[center] = chars.Circle
+	}
 	// Open arrows have no head. A bidirectional self-message collapses to a
 	// single head: both of its ends sit on the same lifeline, and the return
 	// head is where they coincide.

pkg/sequence/renderer_test.go

@@ -32,6 +32,8 @@ func TestSequenceDiagramRendering(t *testing.T) {
 		"critical_basic.txt",
 		"break_rect.txt",
 		"arrow_types.txt",
+		"central_connections.txt",
+		"central_connection_self.txt",
 		"cross_arrows.txt",
 		"async_point_arrows.txt",
 		"bidirectional_arrows.txt",
@@ -75,6 +77,8 @@ func TestSequenceDiagramRendering_ASCII(t *testing.T) {
 		"par_basic.txt",
 		"note_over_single.txt",
 		"arrow_types.txt",
+		"central_connections.txt",
+		"central_connection_self.txt",
 		"cross_arrows.txt",
 		"async_point_arrows.txt",
 		"bidirectional_arrows.txt",
@@ -109,6 +113,8 @@ func TestSequenceDiagramRendering_ASCIISmokeTest(t *testing.T) {
 		"critical_basic.txt",
 		"break_rect.txt",
 		"arrow_types.txt",
+		"central_connections.txt",
+		"central_connection_self.txt",
 		"cross_arrows.txt",
 		"async_point_arrows.txt",
 		"bidirectional_arrows.txt",