deep learning neural network architectures, Neuralnet diagram

[seongwoochikin-dev]

🚀 Feature: Add neuralnet diagram type for deep-learning architecture visualisation

Adds a new neuralnet diagram type for visualising deep learning neural network architectures.

💡 Diagram Examples

1. Sequential (auto-wired):

neuralnet sequential
title LeNet-5
Input[28, 28, 1]
Conv2D[6, 5x5, tanh]
AvgPool2D[2x2]
Flatten
Dense[10, softmax]

2. Graph (skip connections):

neuralnet
inp: Input[64]
conv: Conv2D[64, 3x3, relu]
add: Add
inp --> conv
conv --> add
inp --> add

3. Neuron view:

neuralnet sequential neuron
Input[3]
Dense[8, relu]
Dense[1, sigmoid]

---

📑 Summary

• Introduces neuralnet keyword with layout modes (sequential / graph) and an optional neuron rendering mode.
• 22 layer types supported: Dense, Conv1D/2D/3D, MaxPool1D/2D, AvgPool1D/2D, LSTM, GRU, RNN, Flatten, Reshape, BatchNorm, Dropout, Embedding, Attention, MultiHeadAttention, Add, Concatenate, Input, Output.
• Block mode: Renders color-coded SVG rectangles with tensor shape auto-propagation on edges.
• Neuron mode: Renders per-neuron circles with all-to-all connections (auto-truncates when >8 neurons using 1, 2, 3, ⋮, n-1, n).
• Theme support: Full darkMode compatibility using themeVariables (no hard-coded hex values).
• Comprehensive implementation: Includes Langium grammar, DB, renderer, styles, config schema, Cypress e2e tests, unit tests, and docs.

---

📏 Design Decisions

• Sequential vs Graph: Sequential covers standard architectures with zero boilerplate. Graph mode unlocks skip connections and encoder-decoder patterns via named nodes and explicit --> edges.
• Single Token (NN_WORD): Unifies node IDs and parameter values into one terminal to avoid lexer priority conflicts between IDs and activation names (like relu).
• Shape Propagation: Computed layer-by-layer for sequential networks and displayed on edges (e.g., (28,28,1) → (24,24,6)).
• Neuron Truncation: Set MAX_SHOW = 8 to neatly display large layers.
• Standalone Diagram Type: A new diagram type was chosen over a flowchart preset because tensor shape propagation requires parameter-based computation, neuron-view needs a dedicated render pass, and sequential auto-wiring cannot be achieved through flowchart styling alone.

---

📂 Files Changed

packages/mermaid/src/diagrams/neuralnet/
├── parser/
│   ├── neuralnet.langium            # Langium grammar
│   └── neuralnet.spec.ts            # 26 unit tests
├── neuralnetDb.ts                   # layer / edge state management
├── neuralnetDiagram.ts              # diagram registration
├── neuralnetDetector.ts             # "neuralnet" keyword detector
├── neuralnetRenderer.ts             # SVG renderer (D3)
├── neuralnetShapes.ts               # per-layer SVG shape helpers
├── styles.ts                        # CSS (theme-variable-based)
└── types.ts                         # shared TypeScript interfaces

packages/mermaid/src/docs/syntax/neuralnet.md    # user-facing docs
cypress/integration/rendering/neuralnet.spec.ts  # Cypress e2e tests
.changeset/neuralnet-diagram.md                  # minor changeset (feat:)

---

🧪 Testing

Test Type	Count	Location
Unit (parser + DB)	26	parser/neuralnet.spec.ts
Cypress e2e	8	cypress/integration/rendering/neuralnet.spec.ts

---

📋 Tasks

• 📖 I have read the contribution guidelines.
• 💻 I have added necessary unit/e2e tests.
• 📓 I have added documentation. (MERMAID_RELEASE_VERSION is used for all new features).
• 🦋 I have generated a changeset by running pnpm changeset (Changeset messages prefixed with feat:).

[changeset-bot]

🦋 Changeset detected

Latest commit: 4ce44a7

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
mermaid	Minor
@mermaid-js/parser	Minor

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[netlify]

✅ Deploy Preview for mermaid-js ready!

Name	Link
🔨 Latest commit	4ce44a7
🔍 Latest deploy log	https://app.netlify.com/projects/mermaid-js/deploys/6a1fdc5ac16121000830f7d2
😎 Deploy Preview	https://deploy-preview-7795--mermaid-js.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.
🤖 Make changes	Run an agent on this branch

---

To edit notification comments on pull requests, go to your Netlify project configuration.

[pkg-pr-new]

Open in StackBlitz

@mermaid-js/examples

npm i https://pkg.pr.new/@mermaid-js/examples@7795

mermaid

npm i https://pkg.pr.new/mermaid@7795

@mermaid-js/layout-elk

npm i https://pkg.pr.new/@mermaid-js/layout-elk@7795

@mermaid-js/layout-tidy-tree

npm i https://pkg.pr.new/@mermaid-js/layout-tidy-tree@7795

@mermaid-js/mermaid-zenuml

npm i https://pkg.pr.new/@mermaid-js/mermaid-zenuml@7795

@mermaid-js/parser

npm i https://pkg.pr.new/@mermaid-js/parser@7795

@mermaid-js/tiny

npm i https://pkg.pr.new/@mermaid-js/tiny@7795

commit: 4ce44a7

[argos-ci]

The latest updates on your projects. Learn more about Argos notifications ↗︎

Build	Status	Details	Updated (UTC)
default (Inspect)	⚠️ Changes detected (Review)	2 added	Jun 3, 2026, 8:16 AM

[codecov]

Codecov Report

❌ Patch coverage is 6.69014% with 795 lines in your changes missing coverage. Please review.
✅ Project coverage is 2.87%. Comparing base (9bae92c) to head (4ce44a7).
⚠️ Report is 253 commits behind head on develop.

Files with missing lines	Patch %	Lines
...ermaid/src/diagrams/neuralnet/neuralnetRenderer.ts	0.00%	594 Missing ⚠️
...ages/mermaid/src/diagrams/neuralnet/neuralnetDb.ts	0.00%	53 Missing ⚠️
.../mermaid/src/diagrams/neuralnet/neuralnetParser.ts	3.03%	32 Missing ⚠️
.../mermaid/src/diagrams/neuralnet/neuralnetStyles.ts	4.00%	24 Missing ⚠️
packages/parser/src/language/neuralnet/module.ts	4.54%	21 Missing ⚠️
...ages/parser/src/language/neuralnet/tokenBuilder.ts	5.00%	19 Missing ⚠️
...ermaid/src/diagrams/neuralnet/neuralnetDetector.ts	7.69%	12 Missing ⚠️
packages/mermaid/src/themes/theme-dark.js	9.09%	10 Missing ⚠️
packages/examples/src/examples/neuralnet.ts	10.00%	9 Missing ⚠️
...mermaid/src/diagrams/neuralnet/neuralnetDiagram.ts	10.00%	9 Missing ⚠️
... and 5 more

Additional details and impacted files

@@            Coverage Diff             @@
##           develop   #7795      +/-   ##
==========================================
- Coverage     3.27%   2.87%   -0.40%     
==========================================
  Files          599     679      +80     
  Lines        60986   73122   +12136     
  Branches       921    1011      +90     
==========================================
+ Hits          1997    2102     +105     
- Misses       58989   71020   +12031     

Flag	Coverage Δ
unit	2.87% <6.69%> (-0.40%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

Files with missing lines	Coverage Δ
...s/mermaid/src/diagrams/neuralnet/neuralnetTypes.ts	100.00% <100.00%> (ø)
packages/mermaid/src/themes/theme-default.js	95.96% <100.00%> (+0.08%)	⬆️
packages/mermaid/src/themes/theme-helpers.js	100.00% <100.00%> (ø)
packages/parser/src/language/index.ts	0.00% <0.00%> (ø)
packages/parser/src/language/neuralnet/index.ts	0.00% <0.00%> (ø)
packages/examples/src/index.ts	1.47% <0.00%> (-0.05%)	⬇️
...s/mermaid/src/diagram-api/diagram-orchestration.ts	0.00% <0.00%> (ø)
packages/parser/src/parse.ts	0.80% <0.00%> (-0.04%)	⬇️
packages/examples/src/examples/neuralnet.ts	10.00% <10.00%> (ø)
...mermaid/src/diagrams/neuralnet/neuralnetDiagram.ts	10.00% <10.00%> (ø)
... and 8 more

... and 93 files with indirect coverage changes

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[knsv-bot]

Hi @seongwoochikin-dev — thanks for putting this together, and for going the distance with grammar, renderer, styles, docs, tests, and a changeset all in one pass. That's a lot of work, and it's clear you care about the ML visualisation use case.

Before we dig into a code review, I'd like to raise a higher-level design question that I think is worth resolving first — because the answer changes what the right shape of this contribution is.

Is this a new diagram type, or is it a flowchart preset?

Looking at the Argos previews, both modes are essentially boxes-and-arrows:

• Block mode — coloured rectangles labelled Conv2D[6, 5x5, tanh] etc., wired top-to-bottom with arrows, with tensor shapes printed on edges. Visually, this is flowchart TB + a classDef palette + edge labels.
• Neuron mode — columns of circles with all-to-all line connections, truncated above 8 with an ellipsis row. Visually distinctive, but it's a stylistic preset of a flowchart with ((circle)) nodes and many edges.

I can almost certainly reproduce the block-mode screenshots today with stock flowchart TB, a small classDef palette for the 12 layer categories, and -->|shape| edge labels. The neuron view is harder, but it's not algorithmically novel — it's a layout convention.

Where the PR does add something genuinely new is:

1. sequential auto-wiring — list layers, get them chained vertically. This is a real DX win.
2. Tensor-shape propagation — Input[28,28,1] → Conv2D[6,5x5] → AvgPool2D[2x2] computes (28,28,1) → (24,24,6) → (12,12,6) and prints those on edges. That's the only piece that needs domain logic.

Everything else — 700-line renderer with hardcoded #82c46e-style category colours, 22 layer-type enum values in the grammar, custom Langium parser, custom DB interface, separate styles file — is duplicated machinery for output that the flowchart pipeline already produces.

The concerns this raises for me:

• Syntax fragmentation. Mermaid already has a lot of diagram keywords. Each new one is a discovery cost for users ("do I write flowchart or neuralnet?") and a coordination cost for us (every theming, accessibility, or shape change has to be re-considered for each diagram). I want to make sure we only spend that budget when a diagram is structurally different — graphs, sequences, timelines, gantt charts. A coloured-boxes-with-shape-labels graph isn't structurally different from a flowchart.
• Maintenance drift. The current neuralnetRenderer.ts bypasses the shared rendering pipeline (insertNode, insertEdge, clusters, theming variables in themeVariables). That means future improvements to flowchart rendering — new shape variants, the handdrawn look, theme overhauls, ELK layout, accessibility — won't reach this diagram automatically. We'd be signing up to keep two renderers in step.
• Theme support. Colours like '#82c46e' are hardcoded in NEURON_FILL rather than read from themeVariables. The NeuralnetStyleOptions interface defines nn*Fill knobs but the renderer doesn't actually use them — so the diagram won't follow the active theme today.
• Layer-type catalogue churn. Hard-coding 22 specific layer types (Conv2D, LSTM, Attention, …) into the grammar means every new architectural primitive (Mamba blocks, MoE routers, fresh transformer variants) requires a grammar change. A community-extensible approach holds up better over time.

What I'd be enthusiastic about instead (any one of these alone would be a great PR):

1. A "neural network" preset for flowcharts — ship the layer-category palette and classDef styles as a documented snippet (or as a theme: 'ml' / look: 'neuralnet'). Users opt in; we don't add syntax.
2. A small neuralnet sugar that desugars to flowchart syntax before parsing — keep the nice Conv2D[6,5x5,tanh] shorthand and the sequential auto-wiring, but emit flowchart text and reuse the entire flowchart renderer. The tensor-shape propagation lives as a pre-processor that emits edge labels. This gives you the DX win without the maintenance fork.
3. A new flowchart shape for "layer box with shape annotation" — generalise enough that other domains (signal-processing pipelines, data-engineering DAGs) can reuse it.

None of this is a "no" — it's a request to talk about the shape of the contribution before we ask you to polish a renderer, parser, and grammar that I'm worried we'll have to maintain in parallel forever. The tensor-shape propagation in particular feels like something Mermaid genuinely lacks, and I'd love to see that land.

Would you be open to exploring option (2) — keeping your sugar syntax and shape-propagation but routing through the flowchart renderer? I'm happy to point at the relevant entry points and pair on the design if that's useful.

Either way — thank you again for the contribution and the care you've taken. The neuron view is genuinely delightful.

[seongwoochikin-dev]

Hi @seongwoochikin-dev — thanks for putting this together, and for going the distance with grammar, renderer, styles, docs, tests, and a changeset all in one pass. That's a lot of work, and it's clear you care about the ML visualisation use case.

Before we dig into a code review, I'd like to raise a higher-level design question that I think is worth resolving first — because the answer changes what the right shape of this contribution is.

Is this a new diagram type, or is it a flowchart preset?

Looking at the Argos previews, both modes are essentially boxes-and-arrows:

• Block mode — coloured rectangles labelled Conv2D[6, 5x5, tanh] etc., wired top-to-bottom with arrows, with tensor shapes printed on edges. Visually, this is flowchart TB + a classDef palette + edge labels.
• Neuron mode — columns of circles with all-to-all line connections, truncated above 8 with an ellipsis row. Visually distinctive, but it's a stylistic preset of a flowchart with ((circle)) nodes and many edges.

I can almost certainly reproduce the block-mode screenshots today with stock flowchart TB, a small classDef palette for the 12 layer categories, and -->|shape| edge labels. The neuron view is harder, but it's not algorithmically novel — it's a layout convention.

Where the PR does add something genuinely new is:

1. sequential auto-wiring — list layers, get them chained vertically. This is a real DX win.
2. Tensor-shape propagation — Input[28,28,1] → Conv2D[6,5x5] → AvgPool2D[2x2] computes (28,28,1) → (24,24,6) → (12,12,6) and prints those on edges. That's the only piece that needs domain logic.

Everything else — 700-line renderer with hardcoded #82c46e-style category colours, 22 layer-type enum values in the grammar, custom Langium parser, custom DB interface, separate styles file — is duplicated machinery for output that the flowchart pipeline already produces.

The concerns this raises for me:

• Syntax fragmentation. Mermaid already has a lot of diagram keywords. Each new one is a discovery cost for users ("do I write flowchart or neuralnet?") and a coordination cost for us (every theming, accessibility, or shape change has to be re-considered for each diagram). I want to make sure we only spend that budget when a diagram is structurally different — graphs, sequences, timelines, gantt charts. A coloured-boxes-with-shape-labels graph isn't structurally different from a flowchart.
• Maintenance drift. The current neuralnetRenderer.ts bypasses the shared rendering pipeline (insertNode, insertEdge, clusters, theming variables in themeVariables). That means future improvements to flowchart rendering — new shape variants, the handdrawn look, theme overhauls, ELK layout, accessibility — won't reach this diagram automatically. We'd be signing up to keep two renderers in step.
• Theme support. Colours like '#82c46e' are hardcoded in NEURON_FILL rather than read from themeVariables. The NeuralnetStyleOptions interface defines nn*Fill knobs but the renderer doesn't actually use them — so the diagram won't follow the active theme today.
• Layer-type catalogue churn. Hard-coding 22 specific layer types (Conv2D, LSTM, Attention, …) into the grammar means every new architectural primitive (Mamba blocks, MoE routers, fresh transformer variants) requires a grammar change. A community-extensible approach holds up better over time.

What I'd be enthusiastic about instead (any one of these alone would be a great PR):

1. A "neural network" preset for flowcharts — ship the layer-category palette and classDef styles as a documented snippet (or as a theme: 'ml' / look: 'neuralnet'). Users opt in; we don't add syntax.
2. A small neuralnet sugar that desugars to flowchart syntax before parsing — keep the nice Conv2D[6,5x5,tanh] shorthand and the sequential auto-wiring, but emit flowchart text and reuse the entire flowchart renderer. The tensor-shape propagation lives as a pre-processor that emits edge labels. This gives you the DX win without the maintenance fork.
3. A new flowchart shape for "layer box with shape annotation" — generalise enough that other domains (signal-processing pipelines, data-engineering DAGs) can reuse it.

None of this is a "no" — it's a request to talk about the shape of the contribution before we ask you to polish a renderer, parser, and grammar that I'm worried we'll have to maintain in parallel forever. The tensor-shape propagation in particular feels like something Mermaid genuinely lacks, and I'd love to see that land.

Would you be open to exploring option (2) — keeping your sugar syntax and shape-propagation but routing through the flowchart renderer? I'm happy to point at the relevant entry points and pair on the design if that's useful.

Either way — thank you again for the contribution and the care you've taken. The neuron view is genuinely delightful.

Thanks so much for the thoughtful review — this is exactly the kind of design conversation I was hoping for, and you've clearly engaged deeply with the actual output rather than just the diff.

You're right on the most important technical point, and I've fixed it. Let me address the concerns concretely and then make the case for where I'd like to land.

✅ Theme support — fixed (you were right)
This was a real bug, not a design disagreement. The renderer was painting hardcoded inline colours (#82c46e et al.), which is why the diagram ignored the theme. I've reworked it so colours flow from theme variables:

Added getNeuralnetPalette(darkMode) in theme-helpers.js
Registered nnFill / nnStroke / nnTextColor / nnEdgeColor as theme variables in theme-default.js and theme-dark.js
The renderer now reads getConfig().themeVariables via resolveCategoryColors(); the built-in palette is a fallback only
Removed both hardcoded colour tables
Here's the same diagram under the default and dark themes — the palette, the Flatten (structural) box, edges, and shape labels all follow the theme now. Users can also override any single category via themeVariables: { nnConvFill: '#...' }.

Layer-type catalogue churn is also addressed: unknown layer types already fall through to the structural category rather than erroring, so a Mamba or MoE block renders today without a grammar change. I'm happy to document that explicitly.

🎯 Where I'd love to keep the dedicated diagram
On "is this a flowchart preset?" — I'd gently push back on the block view, and more firmly on the neuron view:

The two things you flagged as genuinely new (sequential auto-wiring + tensor-shape propagation) are exactly why a flowchart preset doesn't get us there. Shape propagation isn't styling — it's a forward pass over the graph: Conv2D[6,5x5] on (28,28,1) has to compute (24,24,6), which needs the layer semantics (kernel, stride, pooling factor). That logic has to live somewhere stateful that understands layers. Once we have a layer-aware DB and a shape-propagation pass, emitting flowchart text underneath is an implementation detail — and it's one I'm genuinely torn on, because:

The neuron view is not expressible as a flowchart. A Dense[128] → Dense[64] pair is 8,192 edges; the value is precisely the truncation convention (1,2,3,⋮,127,128) and the all-to-all visual. There's no classDef that produces this. So at minimum the diagram needs its own renderer for neuron mode — which means the "just desugar to flowchart" path still leaves us maintaining a bespoke renderer for half the feature.

A concrete proposal
I think your option (2) and keeping the diagram aren't actually far apart. What if we:

Keep the layer-aware DB + shape-propagation pass (the domain logic you said Mermaid lacks) — this is the irreducible core.
For block mode, I'm very open to routing through the flowchart rendering pipeline so it inherits ELK, look: handdrawn, and future shape work — exactly your maintenance-drift concern. I'd need a pointer to the cleanest internal entry point (is flowRenderer-v3-unified + the insertNode/insertEdge path the one you'd want, or is there a layout-data API I should target?).
Keep neuron mode as a small dedicated renderer, since it has no flowchart equivalent.
That gives you: no parallel block renderer to maintain, theme/ELK/handdrawn for free on block mode, and the genuinely-novel pieces (shape propagation, neuron view) preserved.

Would that split work for you? If so, I'll refactor block mode onto the shared pipeline in a follow-up commit on this PR. And thank you again — the push on theme variables already made this materially better.

[pbrolin47]

Hi @seongwoochikin-dev,
Thanks for all the effort you put into this PR. You have an ongoing dialogue with @knsv-bot, but sometimes we share the work of reviewing PRs, responding to community members. I discussed this PR with @knsv-bot about next step for this PR, and we think your proposal to keep neuron mode as a small dedicated renderer, and some refactoring of the block mode as next step is a good suggestion. So, please go ahead with that and we look forward to your contributions.