chore(docs): add npm run docs:render-diagrams and export SVGs

Add scripts/docs/render-diagrams.mjs as a thin wrapper around
@mermaid-js/mermaid-cli (mmdc):

- Renders every docs/diagrams/*.mmd into docs/diagrams/exported/*.svg
- Writes a Puppeteer config with --no-sandbox for Ubuntu 23.10+/WSL
- Exits non-zero on first failure so CI can gate on rendering

Expose it as `npm run docs:render-diagrams` and commit the initial
8 rendered SVGs so reviewers see the diagrams without having to install
the renderer locally.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

package.json

@@ -87,6 +87,7 @@
     "check:docs-counts": "node scripts/check-docs-counts-sync.mjs",
     "check:deprecated-versions": "node scripts/check-deprecated-versions.mjs",
     "check:docs-all": "npm run check:docs-sync && npm run check:docs-counts && npm run check:env-doc-sync && npm run check:deprecated-versions",
+    "docs:render-diagrams": "node scripts/docs/render-diagrams.mjs",
     "check:node-runtime": "node --import tsx/esm scripts/check-supported-node-runtime.ts",
     "check:pack-artifact": "node --import tsx/esm scripts/validate-pack-artifact.ts",
     "audit:deps": "npm audit --audit-level=moderate && npm run audit:electron",
@@ -128,7 +129,7 @@
     "express": "^5.2.1",
     "fetch-socks": "^1.3.3",
     "fuse.js": "^7.3.0",
-"gray-matter": "^4.0.3",
+    "gray-matter": "^4.0.3",
     "http-proxy-middleware": "^4.0.0",
     "https-proxy-agent": "^9.0.0",
     "ioredis": "^5.10.1",

scripts/docs/render-diagrams.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+/**
+ * Render every Mermaid source in docs/diagrams/*.mmd into docs/diagrams/exported/*.svg
+ *
+ * Usage:
+ *   npm run docs:render-diagrams
+ *
+ * Requirements:
+ *   - @mermaid-js/mermaid-cli (`mmdc`) on PATH or installed globally.
+ *     `npm install -g @mermaid-js/mermaid-cli` if missing.
+ *
+ * Notes:
+ *   - Puppeteer needs `--no-sandbox` on Ubuntu 23.10+ / WSL. A temp config file
+ *     is written automatically.
+ *   - Each diagram is rendered with `--backgroundColor white` so the SVG works
+ *     against both light and dark themes.
+ *   - The script exits non-zero on first failure so CI / pre-commit hooks can
+ *     gate on it.
+ */
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = resolve(__dirname, "..", "..");
+const srcDir = resolve(repoRoot, "docs", "diagrams");
+const outDir = resolve(srcDir, "exported");
+
+if (!existsSync(srcDir)) {
+  console.error(`[render-diagrams] missing source dir: ${srcDir}`);
+  process.exit(1);
+}
+if (!existsSync(outDir)) {
+  mkdirSync(outDir, { recursive: true });
+}
+
+// Puppeteer needs --no-sandbox on many Linux distros (Ubuntu 23.10+, WSL).
+const puppeteerConfigPath = join(tmpdir(), "omniroute-mmdc-puppeteer.json");
+writeFileSync(
+  puppeteerConfigPath,
+  JSON.stringify({ args: ["--no-sandbox", "--disable-setuid-sandbox"] }, null, 2)
+);
+
+const sources = readdirSync(srcDir)
+  .filter((f) => f.endsWith(".mmd"))
+  .sort();
+
+if (sources.length === 0) {
+  console.error(`[render-diagrams] no .mmd files in ${srcDir}`);
+  process.exit(1);
+}
+
+console.log(`[render-diagrams] rendering ${sources.length} diagram(s)`);
+let failures = 0;
+for (const src of sources) {
+  const input = join(srcDir, src);
+  const output = join(outDir, src.replace(/\.mmd$/, ".svg"));
+  console.log(`  - ${src} -> ${output.replace(repoRoot + "/", "")}`);
+  const result = spawnSync(
+    "mmdc",
+    [
+      "-i",
+      input,
+      "-o",
+      output,
+      "--backgroundColor",
+      "white",
+      "--puppeteerConfigFile",
+      puppeteerConfigPath,
+    ],
+    { stdio: "inherit" }
+  );
+  if (result.status !== 0) {
+    console.error(`    [FAIL] ${src} (exit ${result.status})`);
+    failures += 1;
+  }
+}
+
+if (failures > 0) {
+  console.error(`[render-diagrams] ${failures} failure(s)`);
+  process.exit(1);
+}
+console.log(`[render-diagrams] all ${sources.length} diagram(s) rendered.`);