Start with setup or examples; keep reading for the typed-edit guide. Op shapes and warning codes are pinned by capabilities.json.

Start here

First run
- Getting started
- Examples
Use locally
Appearance
- Styles and palettes
- Custom styles
Debug

Guide: editing a diagram without regenerating it

A render-only tool makes an agent rebuild the whole diagram to move one node. Agentic Mermaid keeps the diagram structured, so an edit is five small steps, and verify gates the last one.

Most diagram tools render and stop. You hand them source, they hand back a picture, and to change one node you send the whole source again. That is fine for a person editing by hand and wasteful for an agent editing in a loop, where every regeneration risks moving nodes that were already correct.

The fix is to treat an existing diagram as structured data, not a string. A typed surface exposes the parts an agent can name and change, and refuses edits it cannot make safely. The loop has five steps.

1 · Parse

Read the source into a typed model. Anything the model does not understand round-trips through preserved source, so an unusual block is carried verbatim rather than dropped.An unusual block – a raw journey body, say – is carried verbatim as a string and re-emitted untouched, so parsing never silently drops what it cannot model.

2 · Narrow

Select the one node or edge the edit touches. Narrowing keeps the change local, which is what protects the rest of the layout from drifting.Locality is the whole game: touch one node and the other forty keep their coordinates, so a one-line edit can’t reflow the diagram.

The five-step loop. verify sits between mutate and serialize; a warning sends the work back to narrow.

3 · Mutate

Apply a named operation to the narrowed selection. The operation returns a new typed model; it does not rewrite the source by hand.

mutate(diagram, { kind: "add_edge", from: "V", to: "R", label: "ok" })
// returns { ok: true, value: ValidDiagram } or a structured error

4 · Verify

Check the result before trusting it. verify returns warnings in three tiers – structural, geometric, and lint – each with a severity of error or warning. Tiers say what kind of problem it is; severity says whether it blocks. An agent reads both and decides whether to fix, re-narrow, or stop and ask a human.Tier 1, structural – graph-shape problems: an edge to a node that isn’t there (EDGE_MISANCHORED, an error) or a label past the character cap (LABEL_OVERFLOW, a warning). Errors block; warnings return with ok: true for you to judge.Tier 2, geometric – valid but ugly: overlapping nodes, an off-canvas box, a route with an unexplained bend. Advisory, not fatal.Tier 3, lint – style and lossiness: a duplicate edge, an unreachable node, or a dropped comment. Cosmetic.Layout quality is scored separately by the deterministic rubric in layout-rubric.ts (the repo’s bun run track tooling), not returned by verify. The same diagram always scores the same, so a metric diff means a real change.

am verify loop.mmd --json
{ "ok": true,
  "warnings": [ { "code": "COMMENT_DROPPED", "count": 1, "lines": [4] } ] }

That is the real output for the diagram above with an inline %% comment on line 4: ok: true, one lint, nothing blocking – ship it or fix the comment first, your call.COMMENT_DROPPED, line 4. The inline %% comment isn’t representable in the typed model – keep the essential text in a label or title, or make a source-level edit instead.

5 · Serialize

Write the typed model back to Mermaid source, then render to SVG, PNG, ASCII, or Unicode. Because layout is deterministic, the same model produces the same geometry every run.Same input, same bytes – no RNG, no clock. A CI snapshot of the SVG is stable, so a diff means a real geometry change, not noise.

Stop rule. Never return a diagram you have not verified, and never fabricate a passing result. If a structural warning will not clear after two attempts, serialize what you have and ask a human to look.

The loop is the product: parse, narrow, mutate, verify, serialize. The picture is only the last step, and the only one a render-first tool ever gives you.

Docs