fix: prevent participant box overlap in sequence diagrams

[searleser97]

Problem

When sequence diagrams have many participants with long names but few direct messages between adjacent pairs, participant boxes overlap in the header row.

Example input:

sequenceDiagram
    participant A as AuthenticationService
    participant B as UserSessionManager
    participant C as TokenValidationMiddleware
    participant D as PermissionsEvaluator
    participant E as AuditLogService
    participant F as NotificationDispatcher
    A->>B: createSession(credentials)
    B->>C: validateToken()

Loading

Why --width N doesn't help

The --width flag and auto-fit logic only compact a diagram (reduce gap/padding) when it exceeds the target width. They don't expand the initial layout. The overlap occurs because _MIN_GAP = 16 (the floor for gap between participant centers) is smaller than the combined half-widths of adjacent boxes. This means boxes overlap in the initial layout calculation, before any compaction is applied.

Tested with --width 500 --no-auto-fit — the overlap persists because the layout algorithm never ensures gaps are wide enough for the actual box sizes.

Fix

1. Prevent participant box overlap (commit dfef9be)

Added a constraint in _compute_layout() that ensures the gap between adjacent participant centers is at least the sum of their half-box-widths plus 2 characters of spacing.

# Ensure gaps are wide enough that participant boxes don't overlap
for i in range(n - 1):
    box_gap_need = (box_widths[i] + box_widths[i + 1]) // 2 + 2
    gap_mins[i] = max(gap_mins[i], box_gap_need)

2. Remove unnecessary minimum box size constraints (commit dd7f546)

• sequence.py: Removed hardcoded minimum box width of 12. Box width is now exactly label + padding_x + 2 (borders), so boxes are only as wide as needed.
• placement.py: Lowered minimum content_height from 3 to 1. When --padding-y 0 is passed, flowchart nodes no longer have extra blank lines above/below the label.

Users can now get tight boxes with --padding-x 2 --padding-y 0. Default behavior (padding_x=4, padding_y=2) is unchanged.

3. Expand canvas width for 'over' notes on rightmost participants (commit 1b25b6b)

Notes with position == "over" on the rightmost participant (or spanning to it) were not accounted for in the canvas width calculation. This caused the right border of such note boxes to be clipped. The fix adds width calculation for "over" notes in max_right.

if ev.position == "over":
    lines = _note_lines(ev)
    note_width = max(display_width(line) for line in lines) + 4
    if len(ev.participants) == 2:
        ...
        needed = note_x + note_width + 1
        max_right = max(max_right, needed)
    elif len(ev.participants) == 1:
        ...
        needed = note_x + note_width + 1
        max_right = max(max_right, needed)

Visual comparison — Sequence diagram

Before (default --padding-x 4, min box width 12):

 ┌─────────┐      ┌───────┐
 │  Alice  │      │  Bob  │
 └─────────┘      └───────┘
      ┆ Hello Bob     ┆
      ────────────────►
      ┆ Hi Alice      ┆
      ◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
      ┆               ┆

After (--padding-x 2, no min width floor):

 ┌───────┐        ┌─────┐
 │ Alice │        │ Bob │
 └───────┘        └─────┘
     ┆ Hello Bob     ┆
     ────────────────►
     ┆ Hi Alice      ┆
     ◄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
     ┆               ┆

Visual comparison — Flowchart

Before (default --padding-x 4 --padding-y 2):

┌────────────┐
│            │
│   Start    │
│            │
└──────┬─────┘
       │
       ▼
┌──────◇─────┐
│            │
│  Decision  │
│            │
└──────◇─────┘
       │
       ├─────────────────╮No
    Yes│                 │
       ▼                 ▼
┌────────────┐    ┌────────────┐
│            │    │            │
│  Process   │    │    End     │
│            │    │            │
└────────────┘    └────────────┘

After (--padding-x 2 --padding-y 0):

┌──────────┐
│  Start   │
└─────┬────┘
      │
      ▼
┌─────◇────┐
│ Decision │
└─────◇────┘
      │
      ├───────────────╮No
   Yes│               │
      ▼               ▼
┌──────────┐    ┌──────────┐
│ Process  │    │   End    │
└──────────┘    └──────────┘

Tests

All existing sequence diagram tests pass. The snapshot failures are pre-existing (statediagram) and unrelated to these changes.

[searleser97]

@fasouto please take a look at this PR

[searleser97]

@fasouto , friendly ping...

[fasouto]

Sorry, im on vacation right now. Will taka a look at this in 2 weeks. Thanks for submitting a PR El El mar, 19 may 2026 a las 2:55, Sergio ***@***.***> escribió:

…

*searleser97* left a comment (fasouto/termaid#5) <#5?email_source=notifications&email_token=AABPNGCG6733GQWL4NRZMYT43NMCTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINBYGA4TCNBRGEYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJNLQOJPWG33NNVSW45C7N5YGK3S7MNWGSY3L#issuecomment-4480914110> @fasouto <https://github.com/fasouto> , friendly ping... — Reply to this email directly, view it on GitHub <#5?email_source=notifications&email_token=AABPNGCG6733GQWL4NRZMYT43NMCTA5CNFSNUABFM5UWIORPF5TWS5BNNB2WEL2JONZXKZKDN5WW2ZLOOQXTINBYGA4TCNBRGEYKM4TFMFZW63VHNVSW45DJN5XKKZLWMVXHJNLQOJPWG33NNVSW45C7N5YGK3S7MNWGSY3L#issuecomment-4480914110>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AABPNGDOT2OYKFEX3LZSQH343NMCTAVCNFSM6AAAAACY42DOZGVHI2DSMVQWIX3LMV43OSLTON2WKQ3PNVWWK3TUHM2DIOBQHEYTIMJRGA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>. You are receiving this because you were mentioned.Message ID: ***@***.***>

[fasouto]

(back from holidays, thanks for your patience)

I checked it and the overlap fix is an improvement, and sizing the participant boxes to their labels actually matches how Mermaid renders them, so I'm happy to move it in that direction. Aesthetically I like them all with the same size, but it's less practical so we will do that.

I went ahead and pushed a follow-up commit (8d910ed) instead of sending it back and forth. Two things to flag:

• Tests: main is fully green for me (1101 passed). The 8 failures on this branch were all sequence snapshots (not statediagram), caused by the box-width change
• Three small regressions the tighter boxes exposed (the old min-width-12 boxes had been hiding them), all fixed in the follow-up:

1. Note over on a left-positioned actor clipped on the right (the layout reserved width from the unclamped note_x, but _draw_note clamps it to >= 0).
2. Nested loop/alt/opt block frames clipped on the right (the canvas-width calc never accounted for block frames).
3. Nested block frames lost their left indent and collapsed onto column 0 (the per-depth indent was inside the max(0, …) clamp).

Snapshots are regenerated and the full suite is green. Thanks for your PR @searleser97 !!