@helping-ai-workflow/md2doc 2.2.0 → 2.3.0

package/README.md

@@ -8,6 +8,8 @@ A single global CLI (`md2doc`) you can call from any directory.
 
 Requires Node.js 18 or higher. The first install pulls puppeteer (≈ 170 MB Chromium download); subsequent installs reuse it.
 
+Chromium is only needed for **PDF export** and the optional `--bake-svg` flag. HTML diagram rendering needs nothing extra — Graphviz runs in-process via WebAssembly, and Mermaid / WaveDrom are bundled and inlined, so diagrams render **offline with no system Graphviz and no CDN**.
+
 ### Recommended: install via nvm
 
 If you do not yet have Node.js — or your system Node lives under `/usr/local` and `npm install -g` fails with `EACCES` — install Node through [nvm](https://github.com/nvm-sh/nvm) first. nvm puts Node under `~/.nvm`, so global packages never need `sudo`.
@@ -69,6 +71,7 @@ also pass `--open`.
 | `--open` | Launch the platform viewer (`xdg-open` / `open` / `start`) after render. Default when `--out` is absent. |
 | `--no-open` | Skip the viewer launch. |
 | `--quiet` | Suppress per-file progress messages. |
+| `--bake-svg` | Pre-render Mermaid / WaveDrom to inert SVG at generation time (HTML output only; needs Chromium). The output then contains no diagram JavaScript. |
 | `--version`, `-v` | Print version. |
 | `--help`, `-h` | Print help. |
 
@@ -101,7 +104,9 @@ digraph G { A -> B }
 ```
 ````
 
-Diagrams render directly in the output (HTML or PDF).
+All three render directly in the output (HTML or PDF), **offline and with no system dependencies**: Graphviz `dot` runs in-process via WebAssembly (no system `dot` binary required), and Mermaid / WaveDrom are bundled and inlined (no CDN). Each engine's runtime is embedded only when the document actually uses that diagram type.
+
+By default, Mermaid and WaveDrom render in the browser when the HTML is opened; pass `--bake-svg` to pre-render them to inert SVG at generation time instead (Graphviz is always pre-rendered to SVG).
 
 ## Why a global CLI
 

package/bin/md2doc.js

@@ -32,6 +32,7 @@ function printHelp() {
         '  --open              Launch the platform viewer after render (default when --out is absent).',
         '  --no-open           Skip the viewer launch.',
         '  --quiet             Suppress per-file progress messages.',
+        '  --bake-svg          Pre-render mermaid/wavedrom to inert SVG (HTML output only; needs Chromium).',
         '  --version, -v       Print version.',
         '  --help, -h          Print this help.',
         ''
@@ -45,6 +46,7 @@ function parseArgs(argv) {
     let out = null;
     let openExplicit = null; // null = unset; true/false = user-specified
     let quiet = false;
+    let bakeSvg = false;
 
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
@@ -61,6 +63,7 @@ function parseArgs(argv) {
         if (a === '--open') { openExplicit = true; continue; }
         if (a === '--no-open') { openExplicit = false; continue; }
         if (a === '--quiet') { quiet = true; continue; }
+        if (a === '--bake-svg') { bakeSvg = true; continue; }
         if (a === '--out') {
             if (out !== null) {
                 process.stderr.write('error: --out specified more than once\n');
@@ -102,7 +105,7 @@ function parseArgs(argv) {
         open = (out === null);
     }
 
-    return { inputs, formats, formatsExplicit, out, open, quiet };
+    return { inputs, formats, formatsExplicit, out, open, quiet, bakeSvg };
 }
 
 function shortHash(absPath) {
@@ -244,7 +247,9 @@ function main() {
     const outputs = [];
     for (const { input, output } of pairs) {
         const stdio = args.quiet ? ['inherit', 'ignore', 'inherit'] : 'inherit';
-        const r = spawnSync(process.execPath, [LIB, input, output], { stdio });
+        const childArgs = [LIB, input, output];
+        if (args.bakeSvg) childArgs.push('--bake-svg');
+        const r = spawnSync(process.execPath, childArgs, { stdio });
         if (r.status !== 0) {
             process.stderr.write('error: render failed for ' + input + ' (exit ' + r.status + ')\n');
             process.exit(r.status || 1);

package/lib/md2doc.js

@@ -20,9 +20,13 @@
 
 const fs            = require('fs');
 const path          = require('path');
-const { spawnSync } = require('child_process');
 
 const [,, src, dst] = process.argv;
+const BAKE_SVG = process.argv.slice(4).includes('--bake-svg');
+
+// How long to let client-side WaveDrom / Mermaid scripts render before we
+// snapshot the DOM (PDF print, or --bake-svg inert-SVG bake).
+const DIAGRAM_RENDER_WAIT_MS = 2500;
 if (!src || !dst) {
   console.error('Usage: node md2doc.js <input.md> <output.html|pdf>');
   process.exit(1);
@@ -55,56 +59,57 @@ function safeResolve(modulePath) {
   }
 }
 
-function inlineScriptTag(sourcePath) {
+function inlineScriptTag(sourcePath, engine) {
   if (!sourcePath) {
     return null;
   }
-  return `<script type="text/javascript">\n${fs.readFileSync(sourcePath, 'utf8')}\n</script>`;
+  const marker = engine ? ` data-md2doc-diagram-engine="${engine}"` : '';
+  return `<script type="text/javascript"${marker}>\n${fs.readFileSync(sourcePath, 'utf8')}\n</script>`;
 }
 
+// wavedrom is pinned to 3.5.0 in package.json: 3.6.1+ adds an `exports` map
+// that no longer exposes the `wavedrom/wavedrom.min.js` / `wavedrom/skins/default.js`
+// subpaths resolved below, so a bump past 3.5.x must switch to an exports-blessed
+// entry (or a vendored copy) or these safeResolve() calls return null and the
+// hard guard further down exits 1.
 const localWaveDromSkin = firstExistingPath([
   process.env.WAVEDROM_SKIN_JS,
   safeResolve('wavedrom/skins/default.js'),
-  '/home/user/.vscode-server/extensions/shd101wyy.markdown-preview-enhanced-0.8.22/crossnote/dependencies/wavedrom/skins/default.js',
 ]);
 
 const localWaveDromJs = firstExistingPath([
   process.env.WAVEDROM_JS,
   safeResolve('wavedrom/wavedrom.min.js'),
-  '/home/user/.vscode-server/extensions/shd101wyy.markdown-preview-enhanced-0.8.22/crossnote/dependencies/wavedrom/wavedrom.min.js',
 ]);
 
 const localMermaidJs = firstExistingPath([
   process.env.MERMAID_JS,
   safeResolve('mermaid/dist/mermaid.min.js'),
-  '/home/user/.vscode-server/extensions/shd101wyy.markdown-preview-enhanced-0.8.22/crossnote/dependencies/mermaid/mermaid.min.js',
 ]);
 
-const waveDromSkinTag = inlineScriptTag(localWaveDromSkin)
-  || '<script src="https://cdn.jsdelivr.net/npm/wavedrom/skins/default.js" type="text/javascript"></script>';
-
-const waveDromTag = inlineScriptTag(localWaveDromJs)
-  || '<script src="https://cdn.jsdelivr.net/npm/wavedrom/wavedrom.min.js" type="text/javascript"></script>';
+if (!localMermaidJs || !localWaveDromJs || !localWaveDromSkin) {
+  console.error('[ERROR] bundled diagram runtime missing — reinstall dependencies with `npm install`');
+  process.exit(1);
+}
 
-const mermaidScriptTag = inlineScriptTag(localMermaidJs)
-  || `<script type="module">
-  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
-  mermaid.initialize({ startOnLoad: true, theme: 'default' });
-</script>`;
+const waveDromSkinTag = inlineScriptTag(localWaveDromSkin, 'wavedrom');
+const waveDromTag     = inlineScriptTag(localWaveDromJs, 'wavedrom');
+const mermaidScriptTag = inlineScriptTag(localMermaidJs, 'mermaid');
 
-const mermaidInitTag = localMermaidJs
-  ? `<script type="text/javascript">
+const mermaidInitTag = `<script type="text/javascript" data-md2doc-diagram-engine="mermaid">
   if (typeof mermaid !== 'undefined') {
     mermaid.initialize({ startOnLoad: true, theme: 'default' });
   }
-</script>`
-  : '';
+</script>`;
 
 // ── Markdown → HTML body ─────────────────────────────────────────────────────
 // Use a custom renderer to intercept fenced code blocks before marked escapes
 // their content. This is the correct approach — pre-processing the raw markdown
 // string causes marked to re-parse the injected HTML and mangle indented lines.
 
+let usesMermaid = false;
+let usesWaveDrom = false;
+
 let bodyHtml;
 let tocHtml = '';
 let serializedSections = '[]';
@@ -306,9 +311,11 @@ ${itemsHtml}
     const code = (typeof token === 'object') ? token.text : token;
 
     if (lang === 'wavedrom') {
+      usesWaveDrom = true;
       return `\n<script type="WaveDrom">\n${code}\n</script>\n`;
     }
     if (lang === 'mermaid') {
+      usesMermaid = true;
       // Escape so the browser delivers the literal source to mermaid. Raw
       // injection lets the HTML parser consume entities and tags first —
       // an author's &lt;IP&gt; became an <IP> element mermaid sanitized
@@ -316,19 +323,12 @@ ${itemsHtml}
       return `\n<div class="mermaid">\n${escapeHtml(code)}\n</div>\n`;
     }
     if (lang === 'dot' || lang === 'graphviz') {
-      const r = spawnSync('dot', ['-Tsvg'], { input: code, encoding: 'utf8', timeout: 10000 });
-      if (r.status === 0) {
-        // Strip XML declaration / DOCTYPE; keep only the <svg> element.
-        // Keep intrinsic width/height so small diagrams render at their natural
-        // size; max-width:100% in CSS still shrinks oversized ones to container.
-        const svg = r.stdout
-          .replace(/<\?xml[^>]*\?>/g, '')
-          .replace(/<!DOCTYPE[^>]*>/g, '')
-          .trim();
-        return `\n<div class="graphviz">${svg}</div>\n`;
-      }
-      console.error('[WARN] dot render failed:', r.stderr);
-      // Fall through to default code block
+      // Defer rendering to the async bakeGraphviz() post-pass so the
+      // synchronous marked() pass stays sync. The dot source is carried as
+      // base64 in a data attribute — safe for arbitrary dot syntax (quotes,
+      // angle brackets, newlines) inside an HTML attribute.
+      const b64 = Buffer.from(code, 'utf8').toString('base64');
+      return `\n<div class="graphviz" data-graphviz-src="${b64}"></div>\n`;
     }
     // Default: syntax-highlighted code block
     const escaped = code.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
@@ -1054,9 +1054,9 @@ ${bodyHtml}
 </div>
 
 <!-- WaveDrom -->
-${waveDromSkinTag}
+${usesWaveDrom ? `${waveDromSkinTag}
 ${waveDromTag}
-<script type="text/javascript">
+<script type="text/javascript" data-md2doc-diagram-engine="wavedrom">
   function renderWaveDrom() {
     if (typeof WaveDrom !== 'undefined') {
       WaveDrom.ProcessAll();
@@ -1066,11 +1066,11 @@ ${waveDromTag}
   window.addEventListener('load', renderWaveDrom);
   setTimeout(renderWaveDrom, 250);
   setTimeout(renderWaveDrom, 1000);
-</script>
+</script>` : ''}
 
 <!-- Mermaid -->
-${mermaidScriptTag}
-${mermaidInitTag}
+${usesMermaid ? `${mermaidScriptTag}
+${mermaidInitTag}` : ''}
 
 <!-- Reader runtime -->
 <script id="reader-section-data" type="application/json">${serializedSections}</script>
@@ -1540,13 +1540,90 @@ ${mermaidInitTag}
 </body>
 </html>`;
 
+// Render every deferred dot/graphviz placeholder to inline SVG using the
+// in-process WASM engine. Loads the WASM module only when at least one dot
+// block exists, so text-only docs pay nothing.
+async function bakeGraphviz(htmlStr) {
+  if (!/data-graphviz-src=/.test(htmlStr)) return htmlStr;
+  let Graphviz;
+  try {
+    ({ Graphviz } = require('@hpcc-js/wasm-graphviz'));
+  } catch (e) {
+    console.error('[ERROR] @hpcc-js/wasm-graphviz not installed — run `npm install`:', e.message);
+    return htmlStr;
+  }
+  const gv = await Graphviz.load();
+  return htmlStr.replace(/<div class="graphviz" data-graphviz-src="([^"]*)"><\/div>/g, (m, b64) => {
+    const dotSrc = Buffer.from(b64, 'base64').toString('utf8');
+    try {
+      const svg = gv.dot(dotSrc)
+        .replace(/<\?xml[^>]*\?>/g, '')
+        .replace(/<!DOCTYPE[\s\S]*?>/g, '')
+        // drop graphviz's "Generated by graphviz" banner comment so the div and <svg> are adjacent
+        .replace(/<!--[\s\S]*?-->/g, '')
+        .trim();
+      return `<div class="graphviz">${svg}</div>`;
+    } catch (e) {
+      console.error('[WARN] graphviz render failed:', e.message);
+      const escaped = dotSrc.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+      return `<pre><code class="language-dot">${escaped}</code></pre>\n`;
+    }
+  });
+}
+
+function launchBrowser(puppeteer) {
+  return puppeteer.launch({
+    headless: 'new',
+    args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-crash-reporter', '--disable-dev-shm-usage'],
+  });
+}
+
+// Pre-render mermaid/wavedrom to inert SVG using headless Chromium, then strip
+// the diagram-engine runtime scripts so the output HTML carries no diagram JS.
+async function bakeDiagrams(htmlStr) {
+  if (!/data-md2doc-diagram-engine/.test(htmlStr)) return htmlStr;
+  let puppeteer;
+  try {
+    puppeteer = require('puppeteer');
+  } catch (e) {
+    console.error('[ERROR] --bake-svg requires puppeteer/Chromium — install it, or drop --bake-svg:', e.message);
+    process.exit(1);
+  }
+  const tmp = dst.replace(/\.html$/i, '._bake.html');
+  fs.writeFileSync(tmp, htmlStr, 'utf8');
+  let browser;
+  try {
+    browser = await launchBrowser(puppeteer);
+  } catch (e) {
+    fs.unlinkSync(tmp);
+    console.error('[ERROR] --bake-svg requires Chromium but it failed to launch — drop --bake-svg or install Chromium:', e.message);
+    process.exit(1);
+  }
+  try {
+    const page = await browser.newPage();
+    await page.goto('file://' + path.resolve(tmp), { waitUntil: 'load' });
+    await new Promise(r => setTimeout(r, DIAGRAM_RENDER_WAIT_MS));
+    await page.evaluate(() => {
+      document.querySelectorAll('script[data-md2doc-diagram-engine]').forEach((s) => s.remove());
+    });
+    return await page.content();
+  } finally {
+    await browser.close();
+    fs.unlinkSync(tmp);
+  }
+}
+
 // ── Output ───────────────────────────────────────────────────────────────────
-if (ext === '.html') {
-  fs.writeFileSync(dst, html, 'utf8');
-  console.log(`[HTML] ${src} → ${dst}`);
+(async () => {
+  let finalHtml = await bakeGraphviz(html);
 
-} else if (ext === '.pdf') {
-  (async () => {
+  if (ext === '.html') {
+    if (BAKE_SVG) finalHtml = await bakeDiagrams(finalHtml);
+    fs.writeFileSync(dst, finalHtml, 'utf8');
+    console.log(`[HTML] ${src} → ${dst}`);
+
+  } else if (ext === '.pdf') {
+    if (BAKE_SVG) console.log('[INFO] --bake-svg is redundant for PDF output (already static); ignoring');
     let puppeteer;
     try {
       puppeteer = require('puppeteer');
@@ -1555,26 +1632,25 @@ if (ext === '.html') {
       process.exit(1);
     }
 
-    // Write temporary HTML, launch headless Chromium, export PDF
+    // Write temporary HTML, launch headless Chromium, export PDF.
     // Case-insensitive: an uppercase .PDF dst must not make tmp === dst, or the
     // unlinkSync below deletes the freshly written PDF.
     const tmp = dst.replace(/\.pdf$/i, '._tmp.html');
-    fs.writeFileSync(tmp, html, 'utf8');
+    fs.writeFileSync(tmp, finalHtml, 'utf8');
 
-    const browser = await puppeteer.launch({
-      headless: 'new',
-      args: ['--no-sandbox', '--disable-setuid-sandbox', '--disable-crash-reporter', '--disable-dev-shm-usage'],
-    });
-    const page    = await browser.newPage();
+    const browser = await launchBrowser(puppeteer);
+    const page = await browser.newPage();
 
     await page.goto('file://' + path.resolve(tmp), { waitUntil: 'load' });
 
-    // Allow WaveDrom / Mermaid scripts time to render diagrams
-    await new Promise(r => setTimeout(r, 2500));
+    // Allow WaveDrom / Mermaid scripts time to render diagrams.
+    // NOTE: this sleep is load-bearing for the DEFAULT (view-time) render path.
+    // It is only safe to drop under --bake-svg, where the DOM is already final SVG.
+    await new Promise(r => setTimeout(r, DIAGRAM_RENDER_WAIT_MS));
 
     await page.pdf({
-      path:           dst,
-      format:         'A4',
+      path:            dst,
+      format:          'A4',
       printBackground: true,
       outline:         true,
       tagged:          true,
@@ -1584,9 +1660,12 @@ if (ext === '.html') {
     await browser.close();
     fs.unlinkSync(tmp);
     console.log(`[PDF]  ${src} → ${dst}`);
-  })();
 
-} else {
-  console.error('[ERROR] Output extension must be .html or .pdf');
+  } else {
+    console.error('[ERROR] Output extension must be .html or .pdf');
+    process.exit(1);
+  }
+})().catch((e) => {
+  console.error('[ERROR]', (e && e.stack) || e);
   process.exit(1);
-}
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@helping-ai-workflow/md2doc",
-  "version": "2.2.0",
+  "version": "2.3.0",
   "description": "Markdown → HTML / PDF renderer with WaveDrom, Mermaid, and Graphviz support",
   "keywords": [
     "markdown",
@@ -26,8 +26,11 @@
     "node": ">=18"
   },
   "dependencies": {
+    "@hpcc-js/wasm-graphviz": "1.22.0",
     "marked": "^14.1.0",
-    "puppeteer": "^24.15.0"
+    "mermaid": "11.15.0",
+    "puppeteer": "^24.15.0",
+    "wavedrom": "3.5.0"
   },
   "scripts": {
     "preinstall": "node scripts/preinstall.js",