[epic] Native flowchart parity — gaps vs Mermaid/BPMN/UML/ER (external survey)

[ivanmkc]

Native flowchart parity — gaps vs Mermaid / BPMN / UML / ER / Graphviz

Audit of external flowchart tools (Mermaid, PlantUML, BPMN 2.0, UML, Graphviz, draw.io/Lucidchart, plus VSM/fishbone/mindmap/C4) vs. what the termchart flow engine can render natively today. Goal: decide what should be native flow (so agents emit it and inherit our layout/tones/SGCR proofs) vs. left to the mermaid escape hatch (which bypasses all of that).

Framing: distinguish viewer can't render it (node shapes, markers, glyphs) from SGCR can't lay it out (dagre often still handles it). Most gaps below are viewer gaps.

Prioritized, actionable (filed)

• feat(flow): semantic node shapes — decision diamond, terminator, cylinder, document, parallelogram, hexagon #200 — Semantic node shapes (decision diamond, terminator, cylinder, document, parallelogram, hexagon). S–M. The fix(er): render full ER relationship labels (patch + bundle beautiful-mermaid) #1 "looks like a real flowchart" gap.
• feat(flow): edge marker/decoration library — crow's-foot, UML arrowheads, dashed message-flow, end labels #201 — Edge marker/decoration library (crow's-foot ER, UML aggregation/composition/generalization, dashed BPMN message-flow, end labels). M. Unlocks ER + UML class + BPMN natively.
• feat(viewer): wire the SGCR annotation placer into the viewer (overlay layer + addAnnotation patch op) #202 — Wire the annotation placer into the viewer (overlay + addAnnotation patch op). S–M. Highest ROI — the engine (feat(sgcr): layered annotation placement + P10 overlap proof #197) is already done.
• feat(flow): BPMN-flavored swimlanes — pools + nested lanes + message-flow-crosses-pool lint #203 — BPMN swimlanes (pools + nested lanes + message-flow-crosses-pool lint). M.

Next tier (not yet filed — capture here)

• Fork/join bars + composite/nested states — unlocks native UML activity + state-machine (<<fork>>/<<join>>, [*], <<choice>>). Node-type + an SGCR fanout-alignment rule. M.
• C4 conventions + cloud-icon pack (AWS/GCP/Azure/K8s/iconify) — mostly a tone/icon/recipe pack; "architecture" is the most-requested family after "flowchart". M.
• Off-page / on-page connector primitive + auto-suggest lint — paired circle/pentagon nodes; lint suggests a connector when SGCR routes a long crossing or dagre wraps wide. S.
• rank=same / alignment groups (align:[["a","b","c"]]) — tiny SGCR knob that removes a recurring "off by one slot" class of complaints. S.
• Sequence-diagram auto-layout for the existing lifeline/point nodes (uniform lifeline spacing, monotonic-Y messages, activation boxes, fragments). M.
• Radial mindmap layout (center-out branching tree; distinct from SGCR layout:"ring" which is cycle-only). M.
• Junction node (small dot, 4-way edge merge — Mermaid architecture-beta). S.
• Graphviz HTML-like / record labels, icon-pack registry for change. M.

Lower priority / escape-hatch is fine

Sankey (use vegalite), gitgraph, Gantt (use mermaid/vegalite), fishbone/Ishikawa, value-stream maps, BPMN choreography — distinctive symbol sets, niche; keep on the mermaid escape hatch unless demand appears.

Already addressed

• SGCR silent no-op on grouped graphs + viewport overflow → observable warnings shipped in SGCR: silently no-ops on grouped graphs + no viewport-fit guarantee (off-canvas on large graphs) #195/fix(sgcr): warn on grouped silent-fallback + viewport-fit overflow (#195) #196 (sgcr-skipped-grouped, sgcr-overflow). Full grouped-graph SGCR support (two-level layout) is still deferred (design in fix(sgcr): warn on grouped silent-fallback + viewport-fit overflow (#195) #196).

What's already strong (don't lose in marketing)

ER entity field tables, status tones + colorblind glyphs, sparklines, swimlanes (flat), all 4 directions, and provable overlap-free layout + crossing minimization (SGCR, P1–P10) — verified by a 40k-layout stress harness (#199).

Source: external survey across Mermaid/PlantUML/BPMN/UML/ER/Graphviz/draw.io/Lucidchart docs.