Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(studio): render Mermaid in Markdown previews (#4459)

Oneflye0cc39808a25
diff --git a/web-studio/package-lock.json b/web-studio/package-lock.json
index a9cda3d0f..98c9e829b 100644
--- a/web-studio/package-lock.json
+++ b/web-studio/package-lock.json
@@ -31,6 +31,7 @@
"@microsoft/fetch-event-source": "^2.0.1",
"@streamdown/cjk": "^1.0.3",
"@streamdown/code": "^1.1.1",
+ "@streamdown/mermaid": "^1.0.2",
"@tailwindcss/vite": "^4.1.18",
"@tanstack/react-devtools": "latest",
"@tanstack/react-form": "^1.28.6",
@@ -710,41 +711,10 @@
"specificity": "bin/cli.js"
}
},
- "node_modules/@chevrotain/cst-dts-gen": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/@chevrotain/cst-dts-gen/-/cst-dts-gen-12.0.0.tgz",
- "integrity": "sha512-fSL4KXjTl7cDgf0B5Rip9Q05BOrYvkJV/RrBTE/bKDN096E4hN/ySpcBK5B24T76dlQ2i32Zc3PAE27jFnFrKg==",
- "license": "Apache-2.0",
- "dependencies": {
- "@chevrotain/gast": "12.0.0",
- "@chevrotain/types": "12.0.0"
- }
- },
- "node_modules/@chevrotain/gast": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/@chevrotain/gast/-/gast-12.0.0.tgz",
- "integrity": "sha512-1ne/m3XsIT8aEdrvT33so0GUC+wkctpUPK6zU9IlOyJLUbR0rg4G7ZiApiJbggpgPir9ERy3FRjT6T7lpgetnQ==",
- "license": "Apache-2.0",
- "dependencies": {
- "@chevrotain/types": "12.0.0"
- }
- },
- "node_modules/@chevrotain/regexp-to-ast": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/@chevrotain/regexp-to-ast/-/regexp-to-ast-12.0.0.tgz",
- "integrity": "sha512-p+EW9MaJwgaHguhoqwOtx/FwuGr+DnNn857sXWOi/mClXIkPGl3rn7hGNWvo31HA3vyeQxjqe+H36yZJwYU8cA==",
- "license": "Apache-2.0"
- },
"node_modules/@chevrotain/types": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-12.0.0.tgz",
- "integrity": "sha512-S+04vjFQKeuYw0/eW3U52LkAHQsB1ASxsPGsLPUyQgrZ2iNNibQrsidruDzjEX2JYfespXMG0eZmXlhA6z7nWA==",
- "license": "Apache-2.0"
- },
- "node_modules/@chevrotain/utils": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/@chevrotain/utils/-/utils-12.0.0.tgz",
- "integrity": "sha512-lB59uJoaGIfOOL9knQqQRfhl9g7x8/wqFkp13zTdkRu1huG9kg6IJs1O8hqj9rs6h7orGxHJUKb+mX3rPbWGhA==",
+ "version": "11.1.2",
+ "resolved": "https://registry.npmjs.org/@chevrotain/types/-/types-11.1.2.tgz",
+ "integrity": "sha512-U+HFai5+zmJCkK86QsaJtoITlboZHBqrVketcO2ROv865xfCMSFpELQoz1GkX5GzME8pTa+3kbKrZHQtI0gdbw==",
"license": "Apache-2.0"
},
"node_modules/@codemirror/autocomplete": {
@@ -1315,6 +1285,7 @@
"version": "1.9.2",
"resolved": "https://registry.npmjs.org/@emnapi/core/-/core-1.9.2.tgz",
"integrity": "sha512-UC+ZhH3XtczQYfOlu3lNEkdW/p4dsJ1r/bP7H8+rhao3TTTMO1ATq/4DdIi23XuGoFY+Cz0JmCbdVl0hz9jZcA==",
+ "dev": true,
"license": "MIT",
"optional": true,
"dependencies": {
@@ -1326,6 +1297,7 @@
"version": "1.9.2",
"resolved": "https://registry.npmjs.org/@emnapi/runtime/-/runtime-1.9.2.tgz",
"integrity": "sha512-3U4+MIWHImeyu1wnmVygh5WlgfYDtyf0k8AbLhMFxOipihf6nrWC4syIm/SwEeec0mNSafiiNnMJwbza/Is6Lw==",
+ "dev": true,
"license": "MIT",
"optional": true,
"dependencies": {
@@ -1336,6 +1308,7 @@
"version": "1.2.1",
"resolved": "https://registry.npmjs.org/@emnapi/wasi-threads/-/wasi-threads-1.2.1.tgz",
"integrity": "sha512-uTII7OYF+/Mes/MrcIOYp5yOtSMLBWSIoLPpcgwipoiKbli6k322tcoFsxoIIxPDqW01SQGAgko4EzZi2BNv2w==",
+ "dev": true,
"license": "MIT",
"optional": true,
"dependencies": {
@@ -2545,12 +2518,12 @@
"license": "MIT"
},
"node_modules/@mermaid-js/parser": {
- "version": "1.1.0",
- "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.1.0.tgz",
- "integrity": "sha512-gxK9ZX2+Fex5zu8LhRQoMeMPEHbc73UKZ0FQ54YrQtUxE1VVhMwzeNtKRPAu5aXks4FasbMe4xB4bWrmq6Jlxw==",
+ "version": "1.2.1",
+ "resolved": "https://registry.npmjs.org/@mermaid-js/parser/-/parser-1.2.1.tgz",
+ "integrity": "sha512-n12NohV3mrUyUL2o93IgG/ifeW9FTyeJn3zDxkhwa8MJ9Fxg3HQMlA3RiGmD/3UnJvheztkjjQAjA2T4LmUcpw==",
"license": "MIT",
"dependencies": {
- "langium": "^4.0.0"
+ "@chevrotain/types": "~11.1.2"
}
},
"node_modules/@microsoft/fetch-event-source": {
@@ -2642,6 +2615,7 @@
"version": "0.2.12",
"resolved": "https://registry.npmjs.org/@napi-rs/wasm-runtime/-/wasm-runtime-0.2.12.tgz",
"integrity": "sha512-ZVWUcfwY4E/yPitQJl481FjFo3K22D6qF0DuFH6Y/nbnE11GY5uguDxZMGXPQ8WQ0128MXQD7TnfHyK4oWoIJQ==",
+ "dev": true,
"license": "MIT",
"optional": true,
"dependencies": {
@@ -3365,6 +3339,18 @@
"react": "^18.0.0 || ^19.0.0"
}
},
+ "node_modules/@streamdown/mermaid": {
+ "version": "1.0.2",
+ "resolved": "https://registry.npmjs.org/@streamdown/mermaid/-/mermaid-1.0.2.tgz",
+ "integrity": "sha512-Fr/4sBWnAeSnxM3PcrV/+DiZe5oPMq9gOkUIAH7ZauJeuwrZ/DVzD4g0zlav6AH0axh2m/sOfrfLtY5aLT7niw==",
+ "license": "Apache-2.0",
+ "dependencies": {
+ "mermaid": "^11.12.2"
+ },
+ "peerDependencies": {
+ "react": "^18.0.0 || ^19.0.0"
+ }
+ },
"node_modules/@stylistic/eslint-plugin": {
"version": "5.10.0",
"resolved": "https://registry.npmjs.org/@stylistic/eslint-plugin/-/eslint-plugin-5.10.0.tgz",
@@ -4392,6 +4378,7 @@
"version": "0.10.1",
"resolved": "https://registry.npmjs.org/@tybys/wasm-util/-/wasm-util-0.10.1.tgz",
"integrity": "sha512-9tTaPJLSiejZKx+Bmog4uSubteqTvFrVrURwkmHixBo0G4seD0zUxp98E1DzUBJxLQ3NPwXrGKDiVjwx/DpPsg==",
+ "dev": true,
"license": "MIT",
"optional": true,
"dependencies": {
@@ -6223,34 +6210,6 @@
"node": ">= 16"
}
},
- "node_modules/chevrotain": {
- "version": "12.0.0",
- "resolved": "https://registry.npmjs.org/chevrotain/-/chevrotain-12.0.0.tgz",
- "integrity": "sha512-csJvb+6kEiQaqo1woTdSAuOWdN0WTLIydkKrBnS+V5gZz0oqBrp4kQ35519QgK6TpBThiG3V1vNSHlIkv4AglQ==",
- "license": "Apache-2.0",
- "dependencies": {
- "@chevrotain/cst-dts-gen": "12.0.0",
- "@chevrotain/gast": "12.0.0",
- "@chevrotain/regexp-to-ast": "12.0.0",
- "@chevrotain/types": "12.0.0",
- "@chevrotain/utils": "12.0.0"
- },
- "engines": {
- "node": ">=22.0.0"
- }
- },
- "node_modules/chevrotain-allstar": {
- "version": "0.4.1",
- "resolved": "https://registry.npmjs.org/chevrotain-allstar/-/chevrotain-allstar-0.4.1.tgz",
- "integrity": "sha512-PvVJm3oGqrveUVW2Vt/eZGeiAIsJszYweUcYwcskg9e+IubNYKKD+rHHem7A6XVO22eDAL+inxNIGAzZ/VIWlA==",
- "license": "MIT",
- "dependencies": {
- "lodash-es": "^4.17.21"
- },
- "peerDependencies": {
- "chevrotain": "^12.0.0"
- }
- },
"node_modules/chokidar": {
"version": "3.6.0",
"resolved": "https://registry.npmjs.org/chokidar/-/chokidar-3.6.0.tgz",
@@ -6703,9 +6662,9 @@
"license": "MIT"
},
"node_modules/cytoscape": {
- "version": "3.33.2",
- "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.33.2.tgz",
- "integrity": "sha512-sj4HXd3DokGhzZAdjDejGvTPLqlt84vNFN8m7bGsOzDY5DyVcxIb2ejIXat2Iy7HxWhdT/N1oKyheJ5YdpsGuw==",
+ "version": "3.34.3",
+ "resolved": "https://registry.npmjs.org/cytoscape/-/cytoscape-3.34.3.tgz",
+ "integrity": "sha512-yfYGhRcGAntq6YBD583j4n0Eg3jIxvWmZtz/5uz9UYkeIStSlMxuUja+ec5j3iBD8nv1rwaOAYMW09tBdkSeaQ==",
"license": "MIT",
"engines": {
"node": ">=0.10"
@@ -7246,9 +7205,9 @@
}
},
"node_modules/dayjs": {
- "version": "1.11.20",
- "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.20.tgz",
- "integrity": "sha512-YbwwqR/uYpeoP4pu043q+LTDLFBLApUP6VxRihdfNTqu4ubqMlGDLd6ErXhEgsyvY0K6nCs7nggYumAN+9uEuQ==",
+ "version": "1.11.23",
+ "resolved": "https://registry.npmjs.org/dayjs/-/dayjs-1.11.23.tgz",
+ "integrity": "sha512-QDTCU0M0MxR3hQfnlDJfwekQiaanm1ubOD231u73WBckQ/fsamwRLiE2GBz6D3a/xF1NgfiDLJjXBa1hYOYTtQ==",
"license": "MIT"
},
"node_modules/debug": {
@@ -8390,6 +8349,15 @@
],
"license": "BSD-3-Clause"
},
+ "node_modules/fastdom": {
+ "version": "1.0.12",
+ "resolved": "https://registry.npmjs.org/fastdom/-/fastdom-1.0.12.tgz",
+ "integrity": "sha512-LB+xjSTEbjHE1cWsxu+tN2Xqr1kpi+V9aADI7sVM5ZMaXyYGPHULQMzpJMYqOTULK/73pUkWVzzObFRBkPr+hg==",
+ "license": "MIT",
+ "dependencies": {
+ "strictdom": "^1.0.1"
+ }
+ },
"node_modules/fastq": {
"version": "1.20.1",
"resolved": "https://registry.npmjs.org/fastq/-/fastq-1.20.1.tgz",
@@ -9861,9 +9829,9 @@
}
},
"node_modules/katex": {
- "version": "0.16.45",
- "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.45.tgz",
- "integrity": "sha512-pQpZbdBu7wCTmQUh7ufPmLr0pFoObnGUoL/yhtwJDgmmQpbkg/0HSVti25Fu4rmd1oCR6NGWe9vqTWuWv3GcNA==",
+ "version": "0.16.47",
+ "resolved": "https://registry.npmjs.org/katex/-/katex-0.16.47.tgz",
+ "integrity": "sha512-Eeo8Ys1doU1z+x8AZsPpQu+p/QcZBI5PeOo7QGQdy2x2m0MU/hYagBbGOmXwr5KVbEfVuWv9LpnQWeehogurjg==",
"funding": [
"https://opencollective.com/katex",
"https://github.com/sponsors/katex"
@@ -9909,24 +9877,6 @@
"node": ">=6"
}
},
- "node_modules/langium": {
- "version": "4.2.2",
- "resolved": "https://registry.npmjs.org/langium/-/langium-4.2.2.tgz",
- "integrity": "sha512-JUshTRAfHI4/MF9dH2WupvjSXyn8JBuUEWazB8ZVJUtXutT0doDlAv1XKbZ1Pb5sMexa8FF4CFBc0iiul7gbUQ==",
- "license": "MIT",
- "dependencies": {
- "@chevrotain/regexp-to-ast": "~12.0.0",
- "chevrotain": "~12.0.0",
- "chevrotain-allstar": "~0.4.1",
- "vscode-languageserver": "~9.0.1",
- "vscode-languageserver-textdocument": "~1.0.11",
- "vscode-uri": "~3.1.0"
- },
- "engines": {
- "node": ">=20.10.0",
- "npm": ">=10.2.3"
- }
- },
"node_modules/launch-editor": {
"version": "2.13.2",
"resolved": "https://registry.npmjs.org/launch-editor/-/launch-editor-2.13.2.tgz",
@@ -10714,32 +10664,33 @@
}
},
"node_modules/mermaid": {
- "version": "11.14.0",
- "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.14.0.tgz",
- "integrity": "sha512-GSGloRsBs+JINmmhl0JDwjpuezCsHB4WGI4NASHxL3fHo3o/BRXTxhDLKnln8/Q0lRFRyDdEjmk1/d5Sn1Xz8g==",
+ "version": "11.17.2",
+ "resolved": "https://registry.npmjs.org/mermaid/-/mermaid-11.17.2.tgz",
+ "integrity": "sha512-V6K3C8EBdEsPFZXSKMJe6ppQOENxuHARr9GvHX4hh47lAbhMRD9qf4oEK7LoaRQxULMa80/qt5gHO73aCleBBg==",
"license": "MIT",
"dependencies": {
- "@braintree/sanitize-url": "^7.1.1",
+ "@braintree/sanitize-url": "^7.1.2",
"@iconify/utils": "^3.0.2",
- "@mermaid-js/parser": "^1.1.0",
+ "@mermaid-js/parser": "^1.2.1",
"@types/d3": "^7.4.3",
"@upsetjs/venn.js": "^2.0.0",
- "cytoscape": "^3.33.1",
+ "cytoscape": "^3.34.0",
"cytoscape-cose-bilkent": "^4.1.0",
"cytoscape-fcose": "^2.2.0",
"d3": "^7.9.0",
"d3-sankey": "^0.12.3",
"dagre-d3-es": "7.0.14",
- "dayjs": "^1.11.19",
- "dompurify": "^3.3.1",
- "katex": "^0.16.25",
+ "dayjs": "^1.11.21",
+ "dompurify": "^3.3.3",
+ "es-toolkit": "^1.45.1",
+ "fastdom": "1.0.12",
+ "katex": "^0.16.47",
"khroma": "^2.1.0",
- "lodash-es": "^4.17.23",
"marked": "^16.3.0",
"roughjs": "^4.6.6",
"stylis": "^4.3.6",
"ts-dedent": "^2.2.0",
- "uuid": "^11.1.0"
+ "uuid": "^11.1.0 || ^12 || ^13 || ^14.0.0"
}
},
"node_modules/mermaid/node_modules/marked": {
@@ -13555,6 +13506,12 @@
"integrity": "sha512-vMgjE/GGEPEFnhFub6pa4FmJBRBVOLpIII2hvCZ8Kzb7K0hlHo7mQv6xYrBvCL2LtAIBwFUK8wvuJgTVSQ5MFQ==",
"license": "MIT"
},
+ "node_modules/strictdom": {
+ "version": "1.0.1",
+ "resolved": "https://registry.npmjs.org/strictdom/-/strictdom-1.0.1.tgz",
+ "integrity": "sha512-cEmp9QeXXRmjj/rVp9oyiqcvyocWab/HaoN4+bwFeZ7QzykJD6L3yD4v12K1x0tHpqRqVpJevN3gW7kyM39Bqg==",
+ "license": "MIT"
+ },
"node_modules/string-width": {
"version": "7.2.0",
"resolved": "https://registry.npmjs.org/string-width/-/string-width-7.2.0.tgz",
@@ -14747,55 +14704,6 @@
"node": ">=0.10.0"
}
},
- "node_modules/vscode-jsonrpc": {
- "version": "8.2.0",
- "resolved": "https://registry.npmjs.org/vscode-jsonrpc/-/vscode-jsonrpc-8.2.0.tgz",
- "integrity": "sha512-C+r0eKJUIfiDIfwJhria30+TYWPtuHJXHtI7J0YlOmKAo7ogxP20T0zxB7HZQIFhIyvoBPwWskjxrvAtfjyZfA==",
- "license": "MIT",
- "engines": {
- "node": ">=14.0.0"
- }
- },
- "node_modules/vscode-languageserver": {
- "version": "9.0.1",
- "resolved": "https://registry.npmjs.org/vscode-languageserver/-/vscode-languageserver-9.0.1.tgz",
- "integrity": "sha512-woByF3PDpkHFUreUa7Hos7+pUWdeWMXRd26+ZX2A8cFx6v/JPTtd4/uN0/jB6XQHYaOlHbio03NTHCqrgG5n7g==",
- "license": "MIT",
- "dependencies": {
- "vscode-languageserver-protocol": "3.17.5"
- },
- "bin": {
- "installServerIntoExtension": "bin/installServerIntoExtension"
- }
- },
- "node_modules/vscode-languageserver-protocol": {
- "version": "3.17.5",
- "resolved": "https://registry.npmjs.org/vscode-languageserver-protocol/-/vscode-languageserver-protocol-3.17.5.tgz",
- "integrity": "sha512-mb1bvRJN8SVznADSGWM9u/b07H7Ecg0I3OgXDuLdn307rl/J3A9YD6/eYOssqhecL27hK1IPZAsaqh00i/Jljg==",
- "license": "MIT",
- "dependencies": {
- "vscode-jsonrpc": "8.2.0",
- "vscode-languageserver-types": "3.17.5"
- }
- },
- "node_modules/vscode-languageserver-textdocument": {
- "version": "1.0.12",
- "resolved": "https://registry.npmjs.org/vscode-languageserver-textdocument/-/vscode-languageserver-textdocument-1.0.12.tgz",
- "integrity": "sha512-cxWNPesCnQCcMPeenjKKsOCKQZ/L6Tv19DTRIGuLWe32lyzWhihGVJ/rcckZXJxfdKCFvRLS3fpBIsV/ZGX4zA==",
- "license": "MIT"
- },
- "node_modules/vscode-languageserver-types": {
- "version": "3.17.5",
- "resolved": "https://registry.npmjs.org/vscode-languageserver-types/-/vscode-languageserver-types-3.17.5.tgz",
- "integrity": "sha512-Ld1VelNuX9pdF39h2Hgaeb5hEZM2Z3jUrrMgWQAu82jMtZp7p3vJT3BzToKtZI7NgQssZje5o0zryOrhQvzQAg==",
- "license": "MIT"
- },
- "node_modules/vscode-uri": {
- "version": "3.1.0",
- "resolved": "https://registry.npmjs.org/vscode-uri/-/vscode-uri-3.1.0.tgz",
- "integrity": "sha512-/BpdSx+yCQGnCvecbyXdxHDkuk55/G3xwnC0GqY4gmQ3j+A+g8kzzgB4Nk/SINjqn6+waqw3EgbVF2QKExkRxQ==",
- "license": "MIT"
- },
"node_modules/vue-eslint-parser": {
"version": "10.4.0",
"resolved": "https://registry.npmjs.org/vue-eslint-parser/-/vue-eslint-parser-10.4.0.tgz",
diff --git a/web-studio/package.json b/web-studio/package.json
index 247325924..7da667e94 100644
--- a/web-studio/package.json
+++ b/web-studio/package.json
@@ -41,6 +41,7 @@
"@microsoft/fetch-event-source": "^2.0.1",
"@streamdown/cjk": "^1.0.3",
"@streamdown/code": "^1.1.1",
+ "@streamdown/mermaid": "^1.0.2",
"@tailwindcss/vite": "^4.1.18",
"@tanstack/react-devtools": "latest",
"@tanstack/react-form": "^1.28.6",
@@ -103,5 +104,8 @@
"vite": "^7.3.1",
"vite-tsconfig-paths": "^5.1.4",
"vitest": "^3.0.5"
+ },
+ "overrides": {
+ "mermaid": "^11.16.1"
}
}
diff --git a/web-studio/src/i18n/locales/en/resources.ts b/web-studio/src/i18n/locales/en/resources.ts
index 50f059a4d..69e5a4aee 100644
--- a/web-studio/src/i18n/locales/en/resources.ts
+++ b/web-studio/src/i18n/locales/en/resources.ts
@@ -439,6 +439,14 @@ const resources = {
loadingEditor: 'Loading editor...',
markdownPreview: 'Preview',
markdownSource: 'Source',
+ mermaid: {
+ diagramLabel: 'Mermaid diagram',
+ errorDetails: 'Error details',
+ loading: 'Rendering Mermaid diagram...',
+ renderFailed: 'Unable to render Mermaid diagram.',
+ showSource: 'Show Mermaid source',
+ unknownError: 'Unknown Mermaid rendering error.',
+ },
noDirectoryContext: 'No abstract or overview available for this folder.',
save: 'Save',
selectDirectoryContext: 'Select a chip to show folder context.',
diff --git a/web-studio/src/i18n/locales/zh-CN/resources.ts b/web-studio/src/i18n/locales/zh-CN/resources.ts
index 72b91f959..c026a4a33 100644
--- a/web-studio/src/i18n/locales/zh-CN/resources.ts
+++ b/web-studio/src/i18n/locales/zh-CN/resources.ts
@@ -418,6 +418,14 @@ const resources = {
loadingEditor: '加载编辑器...',
markdownPreview: '预览',
markdownSource: '源码',
+ mermaid: {
+ diagramLabel: 'Mermaid 图表',
+ errorDetails: '错误详情',
+ loading: '正在渲染 Mermaid 图表...',
+ renderFailed: '无法渲染 Mermaid 图表。',
+ showSource: '查看 Mermaid 源码',
+ unknownError: '未知的 Mermaid 渲染错误。',
+ },
noDirectoryContext: '这个目录暂无摘要或概览。',
save: '保存',
selectDirectoryContext: '选择一个标签查看目录上下文。',
diff --git a/web-studio/src/routes/resources/-components/file-preview.test.tsx b/web-studio/src/routes/resources/-components/file-preview.test.tsx
index 07f225fef..f8e9447c9 100644
--- a/web-studio/src/routes/resources/-components/file-preview.test.tsx
+++ b/web-studio/src/routes/resources/-components/file-preview.test.tsx
@@ -1,7 +1,13 @@
// @vitest-environment jsdom
import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
-import { cleanup, fireEvent, render, screen } from '@testing-library/react'
+import {
+ cleanup,
+ fireEvent,
+ render,
+ screen,
+ waitFor,
+} from '@testing-library/react'
import type { PropsWithChildren } from 'react'
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
@@ -17,8 +23,40 @@ const previewState = vi.hoisted(() => ({
override: null as { content: string; fileType: string } | null,
}))
+const previewMocks = vi.hoisted(() => ({
+ renderMermaid: vi.fn(async (_id: string, _source: string) => ({
+ svg: '<svg viewBox="0 0 120 40"><text>Client to server</text></svg>',
+ })),
+}))
+
+vi.mock('@streamdown/mermaid', () => ({
+ mermaid: {
+ getMermaid: () => ({
+ initialize: vi.fn(),
+ render: previewMocks.renderMermaid,
+ }),
+ language: 'mermaid',
+ name: 'mermaid',
+ type: 'diagram',
+ },
+}))
+
+vi.mock('next-themes', () => ({
+ useTheme: () => ({ resolvedTheme: 'light' }),
+}))
+
vi.mock('react-i18next', () => ({
- useTranslation: () => ({ t: (key: string) => key }),
+ useTranslation: () => ({
+ t: (key: string) =>
+ ({
+ 'filePreview.mermaid.diagramLabel': 'Mermaid diagram',
+ 'filePreview.mermaid.errorDetails': 'Error details',
+ 'filePreview.mermaid.loading': 'Rendering Mermaid diagram...',
+ 'filePreview.mermaid.renderFailed': 'Unable to render Mermaid diagram.',
+ 'filePreview.mermaid.showSource': 'Show Mermaid source',
+ 'filePreview.mermaid.unknownError': 'Unknown Mermaid rendering error.',
+ })[key] ?? key,
+ }),
}))
vi.mock('#/gen/ov-client/client.gen', () => ({
@@ -112,8 +150,11 @@ function renderPreview(
)
}
-describe('FilePreview Markdown links', () => {
- beforeEach(() => cleanup())
+describe('FilePreview Markdown rendering', () => {
+ beforeEach(() => {
+ cleanup()
+ previewMocks.renderMermaid.mockClear()
+ })
afterEach(() => {
previewState.override = null
})
@@ -129,6 +170,7 @@ describe('FilePreview Markdown links', () => {
expect(onNavigate).toHaveBeenCalledOnce()
expect(onNavigate).toHaveBeenCalledWith('viking://resources/wiki/target.md')
+ expect(previewMocks.renderMermaid).not.toHaveBeenCalled()
})
it('opens viking links from a directory overview', () => {
@@ -231,6 +273,48 @@ describe('FilePreview Markdown links', () => {
expect(onNavigate).not.toHaveBeenCalled()
})
+ it('renders Mermaid fences as diagrams', async () => {
+ previewState.override = {
+ content: [
+ '```mermaid',
+ 'graph TD',
+ ' A[Client] --> B[Server]',
+ '```',
+ ].join('\n'),
+ fileType: 'markdown',
+ }
+
+ const { container } = renderPreview(file, vi.fn())
+
+ const diagram = await screen.findByRole('img', {
+ name: 'Mermaid diagram',
+ })
+ await waitFor(() => {
+ expect(diagram.innerHTML).toContain('<svg')
+ expect(diagram.textContent).toContain('Client to server')
+ })
+ expect(previewMocks.renderMermaid).toHaveBeenCalledWith(
+ expect.stringMatching(/^mermaid-/),
+ expect.stringContaining('graph TD\n A[Client] --> B[Server]'),
+ )
+ expect(diagram.parentElement?.style.width).toBe('120px')
+ expect(container.querySelector('code.language-mermaid')).toBeNull()
+ })
+
+ it('shows Mermaid errors with the original source', async () => {
+ previewState.override = {
+ content: ['```mermaid', 'this is not a diagram', '```'].join('\n'),
+ fileType: 'markdown',
+ }
+ previewMocks.renderMermaid.mockRejectedValueOnce(new Error('parse error'))
+ const { container } = renderPreview(file, vi.fn())
+
+ await screen.findByText('Unable to render Mermaid diagram.')
+ expect(container.textContent).toContain('parse error')
+ expect(container.textContent).toContain('Show Mermaid source')
+ expect(container.textContent).toContain('this is not a diagram')
+ })
+
it('renders directory L0 and L1 frontmatter as independent metadata panels', () => {
const sidecar = (
filename: '.abstract.md' | '.overview.md',
diff --git a/web-studio/src/routes/resources/-components/file-preview.tsx b/web-studio/src/routes/resources/-components/file-preview.tsx
index b3be422e9..e9ab94328 100644
--- a/web-studio/src/routes/resources/-components/file-preview.tsx
+++ b/web-studio/src/routes/resources/-components/file-preview.tsx
@@ -1,6 +1,12 @@
-import { YamlMetadata } from './yaml-metadata'
-import { splitMarkdownFrontmatter } from '#/lib/markdown-frontmatter'
-import { useEffect, useMemo, useRef, useState, lazy, Suspense } from 'react'
+import {
+ isValidElement,
+ useEffect,
+ useMemo,
+ useRef,
+ useState,
+ lazy,
+ Suspense,
+} from 'react'
import type { ComponentProps, ReactNode } from 'react'
import { useQuery } from '@tanstack/react-query'
import hljs from 'highlight.js/lib/core'
@@ -16,6 +22,7 @@ import { Button } from '#/components/ui/button'
import { ScrollArea } from '#/components/ui/scroll-area'
import { client } from '#/gen/ov-client/client.gen'
import { getContentDownload, ovClient } from '#/lib/ov-client'
+import { splitMarkdownFrontmatter } from '#/lib/markdown-frontmatter'
import { parseOkfSidecarMarkdown } from '#/lib/okf-markdown'
import { fileNameFromUri } from '#/lib/viking-uri'
import type { GetContentDownloadData } from '#/gen/ov-client/types.gen'
@@ -36,10 +43,14 @@ import { useJsonFormat } from '../-hooks/use-json-format'
import type { VikingFsEntry } from '../-types/viking-fm'
import type { CodeEditorHandle } from './code-editor'
import { OkfMetadataPanel } from './okf-metadata-panel'
+import { YamlMetadata } from './yaml-metadata'
const LazyCodeEditor = lazy(() =>
import('./code-editor').then((m) => ({ default: m.CodeEditor })),
)
+const LazyMermaidDiagram = lazy(() =>
+ import('./mermaid-diagram').then((m) => ({ default: m.MermaidDiagram })),
+)
const languageLoaders: Partial<
Record<
@@ -722,6 +733,26 @@ function MarkdownCode({
}
function MarkdownPre({ children }: ComponentProps<'pre'>) {
+ const child =
+ Array.isArray(children) && children.length === 1 ? children[0] : children
+ if (
+ isValidElement<{ className?: string; children?: ReactNode }>(child) &&
+ normalizeMarkdownLanguage(child.props.className) === 'mermaid'
+ ) {
+ const chart = textFromReactNode(child.props.children).replace(/\n$/, '')
+ return (
+ <Suspense
+ fallback={
+ <pre className="overflow-x-auto rounded-md border bg-muted/30 p-3 text-xs leading-6 text-foreground dark:bg-muted-foreground/20">
+ <code className="hljs block whitespace-pre font-mono">{chart}</code>
+ </pre>
+ }
+ >
+ <LazyMermaidDiagram chart={chart} />
+ </Suspense>
+ )
+ }
+
return (
<pre className="overflow-x-auto rounded-md border bg-muted/30 p-3 text-xs leading-6 text-foreground dark:bg-muted-foreground/20">
{children}
diff --git a/web-studio/src/routes/resources/-components/mermaid-diagram.test.tsx b/web-studio/src/routes/resources/-components/mermaid-diagram.test.tsx
new file mode 100644
index 000000000..d23901c88
--- /dev/null
+++ b/web-studio/src/routes/resources/-components/mermaid-diagram.test.tsx
@@ -0,0 +1,144 @@
+// @vitest-environment jsdom
+
+import { mermaid } from '@streamdown/mermaid'
+import { cleanup, render, screen, waitFor } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+
+import { MermaidDiagram } from './mermaid-diagram'
+
+const testContext = vi.hoisted(() => ({
+ locale: 'en' as 'en' | 'zh-CN',
+ theme: 'light',
+ translations: {
+ en: {
+ 'filePreview.mermaid.diagramLabel': 'Mermaid diagram',
+ 'filePreview.mermaid.errorDetails': 'Error details',
+ 'filePreview.mermaid.loading': 'Rendering Mermaid diagram...',
+ 'filePreview.mermaid.renderFailed': 'Unable to render Mermaid diagram.',
+ 'filePreview.mermaid.showSource': 'Show Mermaid source',
+ 'filePreview.mermaid.unknownError': 'Unknown Mermaid rendering error.',
+ },
+ 'zh-CN': {
+ 'filePreview.mermaid.diagramLabel': 'Mermaid 图表',
+ 'filePreview.mermaid.errorDetails': '错误详情',
+ 'filePreview.mermaid.loading': '正在渲染 Mermaid 图表...',
+ 'filePreview.mermaid.renderFailed': '无法渲染 Mermaid 图表。',
+ 'filePreview.mermaid.showSource': '查看 Mermaid 源码',
+ 'filePreview.mermaid.unknownError': '未知的 Mermaid 渲染错误。',
+ },
+ } as Record<'en' | 'zh-CN', Record<string, string>>,
+}))
+
+vi.mock('next-themes', () => ({
+ useTheme: () => ({ resolvedTheme: testContext.theme }),
+}))
+
+vi.mock('react-i18next', () => ({
+ useTranslation: () => ({
+ t: (key: string) =>
+ testContext.translations[testContext.locale][key] ?? key,
+ }),
+}))
+
+describe('MermaidDiagram', () => {
+ beforeEach(() => {
+ testContext.locale = 'en'
+ testContext.theme = 'light'
+ Object.defineProperty(SVGElement.prototype, 'getBBox', {
+ configurable: true,
+ value: () => ({
+ bottom: 20,
+ height: 20,
+ left: 0,
+ right: 100,
+ top: 0,
+ width: 100,
+ x: 0,
+ y: 0,
+ }),
+ })
+ })
+
+ afterEach(() => {
+ cleanup()
+ vi.restoreAllMocks()
+ Reflect.deleteProperty(SVGElement.prototype, 'getBBox')
+ })
+
+ it('renders a real flowchart while keeping its styles inside the diagram', async () => {
+ const outsideLabel = 'Outside diagram'
+ render(
+ <>
+ <button>{outsideLabel}</button>
+ <MermaidDiagram
+ chart={[
+ // GHSA-87f9-hvmw-gh4p: :not(&) must not escape the SVG scope.
+ '%%{init: {"fontFamily": "x;a{b} :not(&){background:green !important} c{d}"}}%%',
+ 'graph TD',
+ ' A[Client] --> B[Server]',
+ ].join('\n')}
+ />
+ </>,
+ )
+
+ expect(screen.getByRole('status').textContent).toContain(
+ 'Rendering Mermaid diagram...',
+ )
+ const diagram = await screen.findByRole('img', {
+ name: 'Mermaid diagram',
+ })
+ const svg = diagram.querySelector('svg')
+ expect(svg).not.toBeNull()
+ expect(diagram.textContent).toContain('Client')
+ expect(diagram.textContent).toContain('Server')
+ expect(diagram.parentElement?.style.width).toMatch(/^\d+px$/)
+ expect(svg?.style.maxWidth).toBe('none')
+ const stylesheet = new CSSStyleSheet()
+ stylesheet.replaceSync(
+ [...diagram.querySelectorAll('style')]
+ .map((style) => style.textContent)
+ .join('\n'),
+ )
+ expect(stylesheet.cssRules.length).toBeGreaterThan(0)
+ const outside = screen.getByRole('button', { name: outsideLabel })
+ for (const rule of stylesheet.cssRules) {
+ if (rule instanceof CSSStyleRule) {
+ expect(outside.matches(rule.selectorText)).toBe(false)
+ }
+ }
+ })
+
+ it('rerenders with Mermaid dark theme when the app theme changes', async () => {
+ const getMermaid = vi.spyOn(mermaid, 'getMermaid')
+ const { rerender } = render(
+ <MermaidDiagram chart={'graph TD\n A[Client] --> B[Server]'} />,
+ )
+
+ await screen.findByRole('img', { name: 'Mermaid diagram' })
+ testContext.theme = 'dark'
+ rerender(<MermaidDiagram chart={'graph TD\n A[Client] --> B[Server]'} />)
+
+ await waitFor(() => {
+ expect(
+ screen
+ .getByRole('img', { name: 'Mermaid diagram' })
+ .getAttribute('data-mermaid-theme'),
+ ).toBe('dark')
+ })
+ expect(getMermaid).toHaveBeenCalledWith({ theme: 'dark' })
+ })
+
+ it('localizes an error while preserving its diagnostic and source', async () => {
+ testContext.locale = 'zh-CN'
+
+ render(<MermaidDiagram chart="this is not a diagram" />)
+
+ const alert = await screen.findByRole('alert')
+ expect(alert.textContent).toContain('无法渲染 Mermaid 图表。')
+ expect(alert.textContent).toContain(
+ 'No diagram type detected matching given configuration',
+ )
+ expect(alert.textContent).toContain('查看 Mermaid 源码')
+ expect(alert.textContent).toContain('this is not a diagram')
+ })
+})
diff --git a/web-studio/src/routes/resources/-components/mermaid-diagram.tsx b/web-studio/src/routes/resources/-components/mermaid-diagram.tsx
new file mode 100644
index 000000000..d60ea0a1e
--- /dev/null
+++ b/web-studio/src/routes/resources/-components/mermaid-diagram.tsx
@@ -0,0 +1,139 @@
+import { mermaid } from '@streamdown/mermaid'
+import { Loader2, TriangleAlert } from 'lucide-react'
+import { useEffect, useId, useRef, useState } from 'react'
+import { useTranslation } from 'react-i18next'
+import { useTheme } from 'next-themes'
+
+type RenderState =
+ | { status: 'loading' }
+ | { message: string; status: 'error' }
+ | { status: 'ready'; svg: string; width: number }
+
+function prepareSvg(svg: string): { svg: string; width: number } {
+ const document = new DOMParser().parseFromString(svg, 'image/svg+xml')
+ const root = document.documentElement
+ if (root.localName !== 'svg') {
+ throw new Error('Mermaid returned invalid SVG markup.')
+ }
+
+ const viewBox = root
+ .getAttribute('viewBox')
+ ?.trim()
+ .split(/[\s,]+/)
+ .map(Number)
+ const viewBoxWidth = viewBox?.length === 4 ? viewBox[2] : undefined
+ const width =
+ typeof viewBoxWidth === 'number' &&
+ Number.isFinite(viewBoxWidth) &&
+ viewBoxWidth > 0
+ ? Math.ceil(viewBoxWidth)
+ : 640
+
+ root.setAttribute('aria-hidden', 'true')
+ root.setAttribute('focusable', 'false')
+ root.setAttribute(
+ 'style',
+ `${root.getAttribute('style') ?? ''}; width: 100%; height: auto; max-width: none; display: block;`,
+ )
+
+ return {
+ svg: new XMLSerializer().serializeToString(root),
+ width,
+ }
+}
+
+export function MermaidDiagram({ chart }: { chart: string }) {
+ const { t } = useTranslation('resources')
+ const { resolvedTheme } = useTheme()
+ const reactId = useId().replace(/[^a-zA-Z0-9_-]/g, '') || 'diagram'
+ const renderCount = useRef(0)
+ const [state, setState] = useState<RenderState>({ status: 'loading' })
+ const theme = resolvedTheme === 'dark' ? 'dark' : 'default'
+ const unknownError = t('filePreview.mermaid.unknownError')
+
+ useEffect(() => {
+ let active = true
+ const renderId = `mermaid-${reactId}-${++renderCount.current}`
+ setState({ status: 'loading' })
+
+ void mermaid
+ .getMermaid({ theme })
+ .render(renderId, chart)
+ .then(({ svg }) => {
+ if (active) {
+ setState({ status: 'ready', ...prepareSvg(svg) })
+ }
+ })
+ .catch((error: unknown) => {
+ if (!active) return
+ const message =
+ error instanceof Error && error.message ? error.message : unknownError
+ setState({ message, status: 'error' })
+ })
+
+ return () => {
+ active = false
+ }
+ }, [chart, reactId, theme, unknownError])
+
+ if (state.status === 'loading') {
+ return (
+ <div
+ aria-live="polite"
+ className="my-4 flex min-h-28 items-center justify-center gap-2 rounded-md border bg-background p-4 text-sm text-muted-foreground"
+ role="status"
+ >
+ <Loader2 aria-hidden="true" className="size-4 animate-spin" />
+ <span>{t('filePreview.mermaid.loading')}</span>
+ </div>
+ )
+ }
+
+ if (state.status === 'error') {
+ return (
+ <div
+ className="my-4 rounded-md border border-destructive/30 bg-destructive/5 p-4 text-sm"
+ role="alert"
+ >
+ <div className="flex items-start gap-2 text-destructive">
+ <TriangleAlert
+ aria-hidden="true"
+ className="mt-0.5 size-4 shrink-0"
+ />
+ <div className="min-w-0 flex-1">
+ <p className="font-medium">
+ {t('filePreview.mermaid.renderFailed')}
+ </p>
+ <p className="mt-1 break-words font-mono text-xs">
+ <span className="sr-only">
+ {t('filePreview.mermaid.errorDetails')}:{' '}
+ </span>
+ {state.message}
+ </p>
+ </div>
+ </div>
+ <details className="mt-3">
+ <summary className="cursor-pointer text-xs font-medium text-muted-foreground hover:text-foreground">
+ {t('filePreview.mermaid.showSource')}
+ </summary>
+ <pre className="mt-2 overflow-x-auto rounded-md bg-muted/60 p-3 text-xs text-foreground">
+ {chart}
+ </pre>
+ </details>
+ </div>
+ )
+ }
+
+ return (
+ <div className="my-4 min-w-0 max-w-full overflow-x-auto rounded-md border bg-background p-4">
+ <div className="mx-auto" style={{ width: `${state.width}px` }}>
+ <div
+ aria-label={t('filePreview.mermaid.diagramLabel')}
+ data-mermaid-theme={theme}
+ dangerouslySetInnerHTML={{ __html: state.svg }}
+ role="img"
+ />
+ </div>
+ </div>
+ )
+}