Repository navigation
Mermaid: comment on parts of the rendered diagram #862
Description
Context
User request: comment on parts of a rendered Mermaid diagram (not only the fence as a whole).
Today:
- A Mermaid fence is one line-block covering the entire fence (
crit-line-blocks.js/document-renderer.js:cssClass: "mermaid-block"). - Reviewers can already leave a line-range comment on that block (or on source if they switch mental model), but there is no way to click a node/edge in the SVG and attach feedback to that part.
- Product copy already positions “comment on Mermaid source” as the intended loop — agents need source lines, not pixel coordinates.
Ask
From the rendered diagram, click a meaningful part (node, participant, edge/label where practical) and open a normal Crit comment that points the agent at the right Mermaid source.
Ideal UX:
- Hover highlights the target element in the SVG.
- Click opens the standard comment form.
- Comment stores a durable pointer back to source (line range + quote of the Mermaid token).
- Optional: small marker on diagram elements that already have comments.
Feasibility
Yes, with a scoped approach — do not invent freeform diagram pins.
| Approach | Verdict |
|---|---|
| A. Map SVG element → source lines (recommended) | Feasible. Mermaid SVG nodes carry ids/labels derived from source (flowchart-Foo-…, edge labels, etc.). Resolve clicked element → node/edge id or label text → search within the fence’s data-mermaid-src / source lines → set start_line/end_line + quote like a normal comment. Agent sees actionable Mermaid syntax. |
| B. Freeform x/y pin on the SVG | Fragile. Re-layout on theme, zoom, viewport, or Mermaid version breaks anchors. Avoid as primary model. |
C. New DOMAnchor-like diagram schema |
Possible later, but overkill for v1 and weaker for agents than source lines. |
Live-mode DOMAnchor is a precedent for non-line pins, but Mermaid review comments should stay source-anchored so crit comment / agent fix loops keep working.
Hard parts (call out in design)
- Diagram-type coverage differs: flowcharts / state / class are easiest; sequence (participants + messages), ER, Gantt need per-type mapping.
- Mermaid’s generated SVG ids are not a stable public API — prefer matching on node id / label text from source, with SVG id as a hint.
- Whole-block click vs part-click: don’t break “comment on entire diagram”; use element hit-testing and fall back to whole-block when click is on background.
- Re-render / live reload: remount markers from comments whose
quote/anchorstill match source.
Proposed v1
- Flowcharts first (highest traffic for architecture reviews).
- Click node → find source line(s) containing that node id → open comment with
quote= that line (or node declaration). - Show hover outline on commentable SVG elements; cursor affordance.
- If mapping fails → fall back to whole-fence comment (current behavior) rather than failing silently.
- Parity in
crit/webandcrit-web.
Stretch / later
- Edges and edge labels
- Sequence diagram messages / participants
- Markers on diagram for existing threads
- Combine with fullscreen zoom overlay (see sibling issue) so part-comment works while zoomed
Acceptance
- Clicking a flowchart node opens a comment anchored to the corresponding Mermaid source line(s), with
quoteset - Agent-facing output includes those line numbers / quote (same as normal comments)
- Background / unmapped click still allows whole-block comment
- Theme change / re-render does not orphan comments that still match source
- Local + hosted parity
Related
- Sibling: Mermaid fullscreen pan/zoom (GitHub-style)
- Existing: whole-block Mermaid commenting + feature page copy under
/features/mermaid-diagrams
Activity
tomasz-tomczyk commentedon Aug 26, 2026
Sibling (fullscreen pan/zoom): #861
bewa1t commentedon Sep 5, 2026
I beilive it's worth adding comments over selected text rather than by line also falls in the same bucket, can these 2 review improvements go together as one MR?