01 · What it is
What Mermaid is, and why it matters
Mermaid is an open-source JavaScript library that turns plain-text definitions into diagrams: flowcharts, sequence diagrams, class diagrams, state diagrams, Gantt charts, entity-relationship diagrams. You write a fenced mermaid block in Markdown, and the diagram renders itself. No drawing tool, no exported PNG, no binary asset rotting in the repo.
It matters because of where it lives. Mermaid renders natively inside the platforms where documentation is written. GitHub renders mermaid code blocks in place, and so do GitLab, Notion, and the major docs-site generators. Diagrams sit in version control as text: they diff in pull requests, they get reviewed like code, and when the flow changes you edit text instead of hunting for a source file. That embedding is structural. Nobody chose Mermaid on benchmark tables; they chose it because it was already there.
A Rust reimplementation is, on its face, a strange thing to build. The diagram-rendering lane is owned by distribution, not by performance. Which makes the maintainer's case worth stating carefully.
02 · Why build it
Why rewrite it in Rust?
The case is documented in the project's own README and evidence files, and it has three legs.
First, determinism. "Deterministic output is an explicit design goal": same input plus same config produces byte-identical SVG. The concrete machinery is ordered data structures, stable node ordering, IEEE-754 discipline, and FNV-1a-hashed golden snapshots. The purpose is plain: diagrams become CI (continuous integration: automated checks that run on every change) artifacts. "Safe to commit and diff in CI like any artifact" — diagram drift fails the build the same way any other regression does.
Second, the scaling wall. "From 2,000 nodes upward, mermaid-js 11.15.0 does not render the diagram at all." It throws RangeError: Maximum call stack size exceeded. The crash landed on a 2,000-node flowchart after 6.5 seconds, and on a 10,000-node schema after 625. FrankenMermaid renders every one of these workloads, in milliseconds. A browser DOM engine does CSS layout on every node; a native pipeline does not pay that tax. That is the sharpest edge the project can demonstrate: it renders the diagrams where the incumbent crashes.
Third, contexts with no browser. Four render backends (SVG, terminal, Canvas2D, WASM) from one intermediate representation. The terminal renderer draws diagrams in braille, block, and half-block modes with a diff engine and a minimap, for SSH sessions and CI logs where mermaid-js cannot run at all.
Underneath all three sits the engineering case: Rust's compiler rules out memory-safety bug classes without a garbage collector, and the ecosystem (mimalloc, rayon for batch work, wasm-bindgen) is mature enough to ship a native tool.
The counter-argument, which the packet keeps labeled: mermaid-js owns the lane through platform embedding, and nobody migrates a diagram renderer on speed numbers. Worse, the headline number the project is famous for — about 871× faster on a 13-diagram corpus — compares native batch Rust against a browser DOM renderer. That is incumbent-in-browser vs challenger-native, not layout-algorithm superiority. And the comparison that matters (is the layout better, judged by humans) is proxied by a structural-equivalence check that deliberately ignores the visual differences users actually see.
03 · What was built
What the project actually built
Nine crates, 258,093 lines of first-party Rust: parser, layout engine, four render backends, a CLI, and a WASM crate. Twenty-seven diagram types and 18 layout algorithms plus an Auto selector, all as compiler-checked enums. 2,520 unit tests, 53 golden snapshot pairs, 3 fuzz targets. A tagged v0.2.0 release (source-only, July 2026) and a live, working WASM demo.
Three findings matter. First, the zero-unsafe posture is unusually thorough. All nine crate roots carry #![forbid(unsafe_code)], and a token census found zero unsafe tokens in 258,000 lines. The forbid gate matters more than the census: it makes the compiler reject unsafe introduced by macro expansion, closing the hole a token count alone would leave.
Second, the crash table is the empirical anchor. Seven large-graph workloads where mermaid-js throws RangeError; the README records them as CANNOT and refuses to derive a speedup ratio from a wall-clock budget. A crash is the least gameable number in the packet, and the project treats it that way.
Third, the evidence machinery audits itself. A 726-row negative-evidence perf ledger with mandatory A/A nulls and ELF-SHA-256 provenance. And a claim-coverage audit that counts 225 KEEP claims and reports that 96.4% of them carry no same-invocation incumbent ratio. The repository publishes an audit of its own unmeasured claims. That is unusual anywhere.
Evidence · CI status
What the project’s own CI said at the pin
the pin = the commit the assessment was pinned to.
- !No test workflows exist. There is no
.github/workflows directory; the Actions page shows only pages-build-deployment runs. - !Either way, CI greenness is not publicly verifiable.
The uncomfortable findings
Uncomfortable finding
The 11 declared quality gates in .ci/quality-gates.toml have no visible enforcement point. Either they run on private infrastructure or the "gated" claim is aspirational. One README sentence is disproven: the claim that the layout and parser crates contain zero HashMap/HashSet usage is false. One real std::collections::HashSet sits in the e-graph crossing path (used for dedup, likely benign, but the sentence is wrong). The README chronically lags the tree: 15 vs 18+Auto algorithms, 23 vs 52 node shapes, ~114,000 vs 258,093 lines, a stale checked-in WASM bundle. source Nothing is published to crates.io or npm. And the license is MIT plus an OpenAI/Anthropic rider: named-party discrimination covering even benchmarking and analyzing, which is not OSI open source and legally excludes the AI labs whose agent tooling would be the natural embedding vector.