feat(react): render ```dot code blocks as Graphviz diagrams

When the optional `@hpcc-js/wasm-graphviz` dependency is installed, ```dot code blocks become inline SVG diagrams. Colors written as `${light|dark}` render a diagram per color scheme.

Assisted-by: Claude Opus 5.5 <noreply@anthropic.com>

Author: ovflowd

packages/react/package.json

@@ -59,6 +59,15 @@
     "vite": "~8.2.2"
   },
   "devDependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.22.0",
     "dedent": "^1.7.2"
+  },
+  "peerDependencies": {
+    "@hpcc-js/wasm-graphviz": "^1.22.0"
+  },
+  "peerDependenciesMeta": {
+    "@hpcc-js/wasm-graphviz": {
+      "optional": true
+    }
   }
 }

packages/react/src/jsx-ast/utils/plugins/diagrams.mjs

@@ -0,0 +1,76 @@
+'use strict';
+
+import { visit } from 'unist-util-visit';
+
+/**
+ * Graphviz, when the optional `@hpcc-js/wasm-graphviz` dependency is
+ * installed. Loaded up front, as the Markdown pipeline runs synchronously.
+ *
+ * @type {import('@hpcc-js/wasm-graphviz').Graphviz | undefined}
+ */
+const graphviz = await import('@hpcc-js/wasm-graphviz')
+  .then(({ Graphviz }) => Graphviz.load())
+  .catch(() => undefined);
+
+/** A color for each color scheme: `${#3c3c43|#dfdfd6}` */
+const THEMED_COLOR = /\$\{([^|}]*)\|([^}]*)\}/g;
+
+/**
+ * Renders DOT source as an inline SVG.
+ *
+ * @param {string} dot
+ */
+const render = dot =>
+  graphviz
+    .dot(dot, 'svg_inline')
+    // A blank line would end the HTML block the SVG is embedded in
+    .replace(/\n\s*\n/g, '\n')
+    .trim();
+
+/**
+ * Renders a diagram. One using colors for each color scheme renders twice,
+ * one SVG per scheme, the page's styles showing the one of the current
+ * scheme.
+ *
+ * @param {string} dot
+ */
+export const renderDiagram = dot => {
+  if (!dot.includes('${')) {
+    return `<div class="diagram">${render(dot)}</div>`;
+  }
+
+  return ['light', 'dark']
+    .map(scheme => {
+      const colors = dot.replace(THEMED_COLOR, (_, light, dark) =>
+        scheme === 'light' ? light : dark
+      );
+
+      return `<div class="diagram diagram-${scheme}">${render(colors)}</div>`;
+    })
+    .join('\n');
+};
+
+/**
+ * Renders ```dot code blocks as Graphviz diagrams, when Graphviz is
+ * installed; otherwise, they stay code blocks.
+ *
+ * @param {import('mdast').Root} tree
+ */
+const transformer = tree => {
+  if (!graphviz) {
+    return;
+  }
+
+  visit(tree, 'code', (node, index, parent) => {
+    if (node.lang !== 'dot') {
+      return;
+    }
+
+    parent.children[index] = { type: 'html', value: renderDiagram(node.value) };
+  });
+};
+
+/**
+ * The remark plugin rendering Graphviz diagrams.
+ */
+export default () => transformer;

packages/react/src/jsx-ast/utils/remark.mjs

@@ -15,6 +15,7 @@ import { visit } from 'unist-util-visit';
 
 import { AST_NODE_TYPES } from '../constants.mjs';
 import transformAlerts from './plugins/alerts.mjs';
+import transformDiagrams from './plugins/diagrams.mjs';
 import transformElements from './plugins/transformer.mjs';
 
 const passThrough = ['element', ...Object.values(AST_NODE_TYPES.MDX)];
@@ -58,6 +59,7 @@ export const getRemarkRecma = lazy(() =>
   unified()
     .use(remarkParse)
     .use(transformAlerts)
+    .use(transformDiagrams)
     // We make Rehype ignore existing HTML nodes, and JSX nodes
     // as these are nodes we manually created during the generation process
     // We also allow dangerous HTML to be passed through, since we have HTML within our Markdown