Migrate grok-mermaid -> lovely-mermaid

[xl0]

What do you want to change?

Migrate grok-mermaid -> lovely-mermaid

Why?

grok-mermaid was a 1:1port of the grok build mermaid render with ~0 human intervention. I inherites a crapton of corner cases and limitations from the original.

lovely-mermad got a lot more effort, the parseers have been reworked completely to be more robust and expand the number of supported diagrams, and the existing ones got some nice features. Too many small things to list really. Here is an incomplete 1:1 comparison: https://xl0.github.io/lovely-mermaid-comparison/

Also he's a lovely-mermaid demo page with many examples, and you can put your own diagrams there to test and share: https://xl0.github.io/lovely-mermaid

Besides all the fixes, it also supports styles and OSC 8 links:

I had concerns that it would look crappy with the light theme, but seems to be ok actually.

How? (optional)

PR

[mitsuhiko]

One thing I keep running into is that very large charts just fall back to … not rendering. I wonder if we can do better here?

[xl0]

You mean when they don't fit horizontally? Yeah, the current layout engine has no concept of how wide it can render.

I will look into it, bit in the end, even with better width aware layout and reflow, we won't be able to fit all diagrams, it will always be best effort.

Another idea - when we don't fit, gzip and base64 the diagram, emit an osc 8 that points you to pi.dev/mermaid/ that renders the full diagram in your browser, where you can scroll/zoom.

This one would work for very large diagrams, as long as they fit into the url.

[xl0]

@mitsuhiko

So, something like this:

Peek.2026-08-15.22-21.mp4

except it of course points to your viewer on pi.dev, or to my renderer

I have been playing with larger more complex diagrams. Looks like ELK is the onle sane layout engine. Mermaid.js also has it as an option.

Check out this experimental branch with this chonker: Pi coding agent

I'm honestly not sure how useful such large diagrams are in practice, and ELK is definitely heavier than the current layout engine. I would say, maybe don't use it in lovely-mermaid, and for the web app, render large flow charts (or all flow charts) as as mermaid.js with ELK? You can select [mermaid] in the demo to see how it renders. Anyway, would love to hear your feedback before I spend more time on this.

[midastruth]

I hope to use it in the terminal, why, because when I use remote, starting the web is a very troublesome thing.

[xl0]

@midastruth This works just fine on remote.

[0xroko]

lovely-mermaid looks lovely! @mitsuhiko has a fair point regarding sizing of diagrams, which I also encountered. I don't think solution here is forcing way diagrams are rendered, but rather models should be prompted with visualisation sizing constraints in mind.

Great example is Anthropics claude.ai built-in visualize 'tool':

Layout: Prefer single-direction flows (all top-down or all left-right). Keep diagrams simple — max 4-5 nodes per diagram. The widget is narrow (~680px) so complex layouts break.

I'm not saying this should be added to system prompt, but making model aware of output visualisations 'limitations' definitely makes sense.

[xl0]

You should add custom mermaid instructions to the context (I have a skill in the repo), but I would not rely on it entirely. You can't really control way the diagram will be rendered from mermaid. Keep diagrams simple also is a nudge that you might not want for all your diagrams. For example here is what 5.6-sol thinks of how Pi works: https://xl0.github.io/lovely-mermaid/previews/elk-state/examples

If I had a "keep it simple" in the skill, I imagine it would default to much less detailed diagrams.

[mitsuhiko]

I think moving to lovely-marmaid is in scope, the web stuff I don't think should be in the core.

[xl0]

@mitsuhiko If you don't want the web link option, you can merge my current PR.

I am working on a better layout engine that both gives better layouts (similar to [elk] in my demos, but without depending on elkjs, which is a transpiled port of the eclipse Java ELK code, ouch), and takes a max width hint, but this should be a separate PR at a later time.

@iggykimi Please stop.

[xl0]

@mitsuhiko Rebased over main an force-pushed the lovely-mermaid one (without the web stuff).

Any chance you'd reconsider the web link idea? I feel it's just a few lines, and IDK if it could be done with an extension. Here's a stand-alone commit you can try: 58c3e19#diff-40c883c573448b2099c3c42ed623dd5d27dee536091a2d8adb7f77a5c7a3447b