@the-forge-flow/visual-explainer-pi 0.2.0 → 0.2.1

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AA+JlE;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAAC,EAAE,EAAE,YAAY,QAiJhE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAgKlE;;GAEG;AACH,MAAM,CAAC,OAAO,UAAU,wBAAwB,CAAC,EAAE,EAAE,YAAY,QAiJhE"}

package/dist/index.js

@@ -7,7 +7,7 @@
  * Based on nicobailon/visual-explainer design principles.
  */
 import { StringEnum } from "@mariozechner/pi-ai";
-import { defineTool, truncateHead } from "@mariozechner/pi-coding-agent";
+import { defineTool } from "@mariozechner/pi-coding-agent";
 import { Type } from "@sinclair/typebox";
 import { generateArchitectureTemplate } from "./templates/architecture.js";
 import { generateTableTemplate } from "./templates/data-table.js";
@@ -81,14 +81,16 @@ async function generateVisual(params, pi) {
         default:
             throw new Error(`Unsupported visual type: ${params.type}`);
     }
-    // Safety check: truncate if too large
-    const truncated = truncateHead(html, { maxBytes: 50000, maxLines: 2000 });
     // Generate filename
     const filename = params.filename
         ? sanitizeFilename(params.filename)
         : generateDefaultFilename(params.title);
-    // Write file
-    const filePath = await writeHtmlFile(filename, truncated.content, state);
+    // Write the full HTML to disk. We intentionally do NOT run the pi
+    // truncateHead helper here — that utility clips LLM-facing tool output,
+    // not files on disk. Cutting the HTML at an arbitrary byte boundary would
+    // leave unclosed tags/scripts and silently corrupt every non-trivial
+    // diagram. See bug report: "mermaid graphs are always bugged".
+    const filePath = await writeHtmlFile(filename, html, state);
     // Open in browser
     await openInBrowser(filePath, pi);
     // Generate preview snippet (first 500 chars of content summary)

package/dist/templates/mermaid.d.ts

@@ -1,6 +1,20 @@
 /**
  * Mermaid template for flowcharts, sequence diagrams, ER diagrams, etc.
- * Based on nicobailon/visual-explainer mermaid-flowchart.html
+ * Based on nicobailon/visual-explainer mermaid-flowchart.html.
+ *
+ * Key invariants (each one exists because it was a real bug):
+ *   1. Mermaid source is placed inside `<script type="text/plain" class="diagram-source">`
+ *      — the HTML parser treats this as opaque data, so `<br/>`, `<`, `>`,
+ *      `&` in the source survive untouched. Never use `<pre class="mermaid">`.
+ *   2. Rendering is explicit via `mermaid.render(id, code)` with
+ *      `startOnLoad: false`. This avoids the timing race between "mermaid
+ *      finished mutating the DOM" and "our zoom/pan handlers bind".
+ *   3. `themeVariables.fontFamily` uses a concrete font stack, not a CSS
+ *      custom property. Mermaid bakes the value into SVG inline styles and
+ *      CSS vars don't resolve when the SVG is exported to a new tab.
+ *   4. The new-tab export reads the page background from a `data-bg`
+ *      attribute on `.mermaid-wrap` so the exported view matches the
+ *      baked-in SVG colors.
  */
 import type { Aesthetic } from "../types.js";
 export interface MermaidContent {
@@ -8,4 +22,12 @@ export interface MermaidContent {
     caption?: string;
 }
 export declare function generateMermaidTemplate(title: string, content: MermaidContent, aesthetic: Aesthetic, isDark: boolean): string;
+/**
+ * Escape mermaid source for safe inclusion in a `<script type="text/plain">`.
+ * Browsers parse a script element's contents only looking for `</script>` —
+ * so we only need to neutralize the literal sequence `</script` anywhere in
+ * the source. Everything else (HTML entities, `<br/>`, `<`, `>`, `&`) passes
+ * through untouched, which is exactly what Mermaid wants.
+ */
+export declare function escapeMermaidSource(source: string): string;
 //# sourceMappingURL=mermaid.d.ts.map

package/dist/templates/mermaid.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../src/templates/mermaid.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAW7C,MAAM,WAAW,cAAc;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAgBR"}
+{"version":3,"file":"mermaid.d.ts","sourceRoot":"","sources":["../../src/templates/mermaid.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAW7C,MAAM,WAAW,cAAc;IAC9B,aAAa,EAAE,MAAM,CAAC;IACtB,OAAO,CAAC,EAAE,MAAM,CAAC;CACjB;AAED,wBAAgB,uBAAuB,CACtC,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,cAAc,EACvB,SAAS,EAAE,SAAS,EACpB,MAAM,EAAE,OAAO,GACb,MAAM,CAgBR;AAoCD;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAE1D"}

package/dist/templates/mermaid.js

@@ -1,64 +1,102 @@
 /**
  * Mermaid template for flowcharts, sequence diagrams, ER diagrams, etc.
- * Based on nicobailon/visual-explainer mermaid-flowchart.html
+ * Based on nicobailon/visual-explainer mermaid-flowchart.html.
+ *
+ * Key invariants (each one exists because it was a real bug):
+ *   1. Mermaid source is placed inside `<script type="text/plain" class="diagram-source">`
+ *      — the HTML parser treats this as opaque data, so `<br/>`, `<`, `>`,
+ *      `&` in the source survive untouched. Never use `<pre class="mermaid">`.
+ *   2. Rendering is explicit via `mermaid.render(id, code)` with
+ *      `startOnLoad: false`. This avoids the timing race between "mermaid
+ *      finished mutating the DOM" and "our zoom/pan handlers bind".
+ *   3. `themeVariables.fontFamily` uses a concrete font stack, not a CSS
+ *      custom property. Mermaid bakes the value into SVG inline styles and
+ *      CSS vars don't resolve when the SVG is exported to a new tab.
+ *   4. The new-tab export reads the page background from a `data-bg`
+ *      attribute on `.mermaid-wrap` so the exported view matches the
+ *      baked-in SVG colors.
  */
 import { FONT_PAIRINGS, MERMAID_SHELL_CSS, MERMAID_SHELL_JS, PALETTES, escapeHtml, generateCSSVariables, generateHtmlShell, } from "./shared.js";
 export function generateMermaidTemplate(title, content, aesthetic, isDark) {
     const palette = isDark ? PALETTES[aesthetic].dark : PALETTES[aesthetic].light;
     const fonts = FONT_PAIRINGS[aesthetic];
     const cssVars = generateCSSVariables(palette, fonts, isDark);
-    const mermaidTheme = generateMermaidThemeVariables(palette);
-    const bodyContent = generateBody(title, content);
-    return generateHtmlShell(title, bodyContent, aesthetic, cssVars, `${MERMAID_SHELL_CSS}${getExtraCSS()}`, getMermaidScript(mermaidTheme, content.mermaidSyntax));
+    const themeConfig = generateMermaidThemeConfig(palette, fonts);
+    const bodyContent = generateBody(title, content, palette.bg);
+    return generateHtmlShell(title, bodyContent, aesthetic, cssVars, `${MERMAID_SHELL_CSS}${getExtraCSS()}`, getMermaidScript(themeConfig));
 }
-function generateMermaidThemeVariables(palette) {
-    // Convert palette to Mermaid themeVariables format
+function generateMermaidThemeConfig(palette, fonts) {
+    // IMPORTANT: use concrete font strings — not `var(--font-body)` — because
+    // Mermaid bakes the value into SVG attributes, and CSS custom properties
+    // don't resolve inside an extracted SVG (see openInNewTab).
+    const fontFamily = fonts.body.replace(/'/g, "\\'");
     return `
     theme: 'base',
+    look: 'classic',
+    layout: 'elk',
     themeVariables: {
+      fontFamily: '${fontFamily}',
+      fontSize: '16px',
       primaryColor: '${palette.surface}',
       primaryTextColor: '${palette.text}',
       primaryBorderColor: '${palette.accent}',
       lineColor: '${palette.textDim}',
       secondaryColor: '${palette.surface2}',
+      secondaryBorderColor: '${palette.teal ?? palette.accent}',
+      secondaryTextColor: '${palette.text}',
       tertiaryColor: '${palette.surfaceElevated}',
-      fontFamily: 'var(--font-mono)',
-      fontSize: '14px'
+      tertiaryBorderColor: '${palette.orange ?? palette.accent}',
+      tertiaryTextColor: '${palette.text}',
+      noteBkgColor: '${palette.surfaceElevated}',
+      noteTextColor: '${palette.text}',
+      noteBorderColor: '${palette.accent}'
     },
-    flowchart: {
-      useMaxWidth: true,
-      htmlLabels: true,
-      curve: 'basis'
-    },
-    sequence: {
-      useMaxWidth: true,
-      diagramMarginX: 50,
-      diagramMarginY: 10
-    }
+    flowchart: { useMaxWidth: false, htmlLabels: true, curve: 'basis' },
+    sequence: { useMaxWidth: false, diagramMarginX: 50, diagramMarginY: 10 }
   `;
 }
-function generateBody(title, content) {
+/**
+ * Escape mermaid source for safe inclusion in a `<script type="text/plain">`.
+ * Browsers parse a script element's contents only looking for `</script>` —
+ * so we only need to neutralize the literal sequence `</script` anywhere in
+ * the source. Everything else (HTML entities, `<br/>`, `<`, `>`, `&`) passes
+ * through untouched, which is exactly what Mermaid wants.
+ */
+export function escapeMermaidSource(source) {
+    return source.replace(/<\/script/gi, "<\\/script");
+}
+function generateBody(title, content, bg) {
     const captionHtml = content.caption
         ? `<p class="caption">${escapeHtml(content.caption)}</p>`
         : "";
+    const safeSource = escapeMermaidSource(content.mermaidSyntax);
+    // Escape `"` in the bg value for the attribute — palette values are
+    // hex/rgba, but belt-and-braces.
+    const bgAttr = bg.replace(/"/g, "&quot;");
     return `
 <div class="container">
   <h1>${escapeHtml(title)}</h1>
-  <div class="diagram-shell" style="--i:0">
-    <div class="mermaid-wrap">
+  <section class="diagram-shell">
+    <p class="diagram-shell__hint">
+      Ctrl/Cmd + wheel to zoom. Drag to pan when zoomed. Double-click to fit.
+    </p>
+    <div class="mermaid-wrap" data-bg="${bgAttr}">
       <div class="zoom-controls">
-        <button class="zoom-btn" data-zoom="in" title="Zoom in">+</button>
-        <button class="zoom-btn" data-zoom="out" title="Zoom out">−</button>
-        <button class="zoom-btn" data-zoom="reset" title="Reset">⟲</button>
-        <button class="zoom-btn" data-zoom="expand" title="Open in new tab">⛶</button>
+        <button type="button" data-action="zoom-in" title="Zoom in">+</button>
+        <button type="button" data-action="zoom-out" title="Zoom out">&minus;</button>
+        <button type="button" data-action="zoom-fit" title="Smart fit">&#8634;</button>
+        <button type="button" data-action="zoom-one" title="1:1 zoom">1:1</button>
+        <button type="button" data-action="zoom-expand" title="Open full size">&#x26F6;</button>
+        <span class="zoom-label">Loading…</span>
       </div>
       <div class="mermaid-viewport">
-        <div class="mermaid-canvas">
-          <pre class="mermaid">${content.mermaidSyntax}</pre>
-        </div>
+        <div class="mermaid mermaid-canvas"></div>
       </div>
     </div>
-  </div>
+    <script type="text/plain" class="diagram-source">
+${safeSource}
+    </script>
+  </section>
   ${captionHtml}
 </div>
 `;
@@ -93,57 +131,31 @@ h1 {
   text-align: center;
 }
 
-/* Mermaid overrides for theming */
-.mermaid .node rect,
-.mermaid .node circle,
-.mermaid .node ellipse,
-.mermaid .node polygon {
-  fill: var(--surface) !important;
-  stroke: var(--accent) !important;
-  stroke-width: 2px !important;
-}
-
-.mermaid .node .label {
-  color: var(--text) !important;
-  font-family: var(--font-mono) !important;
-}
-
-.mermaid .edgePath .path {
-  stroke: var(--text-dim) !important;
-  stroke-width: 2px !important;
-}
-
-.mermaid .edgeLabel {
-  background: var(--surface) !important;
-  color: var(--text) !important;
-}
-
-/* Responsive */
 @media (max-width: 768px) {
   body { padding: 20px; }
   h1 { font-size: 24px; }
 }
 `;
 }
-function getMermaidScript(themeConfig, mermaidSyntax) {
+function getMermaidScript(themeConfig) {
     return `
 <script type="module">
-  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@10/dist/mermaid.esm.min.mjs';
-  
+  import mermaid from 'https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs';
+  import elkLayouts from 'https://cdn.jsdelivr.net/npm/@mermaid-js/layout-elk/dist/mermaid-layout-elk.esm.min.mjs';
+
+  mermaid.registerLayoutLoaders(elkLayouts);
   mermaid.initialize({
-    startOnLoad: true,
+    startOnLoad: false,
     securityLevel: 'loose',
     ${themeConfig}
   });
 
-  ${MERMAID_SHELL_JS}
-
-  // Initialize controls after Mermaid renders
-  setTimeout(() => {
-    document.querySelectorAll('.mermaid-wrap').forEach(wrap => {
-      initMermaidControls(wrap);
-    });
-  }, 500);
+  // Expose on window so the shell JS (classic script, IIFE) can await it.
+  window.mermaid = mermaid;
+  window.dispatchEvent(new Event('mermaid-ready'));
+</script>
+<script>
+${MERMAID_SHELL_JS}
 </script>
 `;
 }

package/dist/templates/shared.d.ts

@@ -9,8 +9,8 @@ export declare const PALETTES: Record<Aesthetic, {
     dark: Palette;
 }>;
 export declare const SHARED_CSS = "\n/* Reset */\n* { margin: 0; padding: 0; box-sizing: border-box; }\n\n/* Animation keyframes */\n@keyframes fadeUp {\n  from { opacity: 0; transform: translateY(12px); }\n  to { opacity: 1; transform: translateY(0); }\n}\n\n@keyframes fadeScale {\n  from { opacity: 0; transform: scale(0.95); }\n  to { opacity: 1; transform: scale(1); }\n}\n\n/* Reduced motion */\n@media (prefers-reduced-motion: reduce) {\n  *, *::before, *::after {\n    animation-duration: 0.01ms !important;\n    animation-delay: 0ms !important;\n    transition-duration: 0.01ms !important;\n  }\n}\n\n/* Base styles */\nbody {\n  min-height: 100vh;\n  line-height: 1.6;\n}\n\n/* Section card base */\n.section {\n  background: var(--surface);\n  border: 1px solid var(--border);\n  border-radius: 12px;\n  padding: 20px 24px;\n  animation: fadeUp 0.4s ease-out both;\n  animation-delay: calc(var(--i, 0) * 0.06s);\n}\n\n.section--hero {\n  background: var(--surface-elevated);\n  border-color: color-mix(in srgb, var(--border) 50%, var(--accent) 50%);\n  box-shadow: 0 4px 20px rgba(0,0,0,0.06);\n  padding: 28px 32px;\n}\n\n.section--recessed {\n  background: var(--surface2);\n  box-shadow: inset 0 1px 3px rgba(0,0,0,0.04);\n}\n\n/* Section labels with dot indicators */\n.section-label {\n  font-family: var(--font-mono);\n  font-size: 11px;\n  font-weight: 600;\n  text-transform: uppercase;\n  letter-spacing: 1.5px;\n  margin-bottom: 16px;\n  display: flex;\n  align-items: center;\n  gap: 8px;\n}\n\n.section-label .dot {\n  width: 8px;\n  height: 8px;\n  border-radius: 50%;\n  display: inline-block;\n}\n\n/* Flow arrows */\n.flow-arrow {\n  display: flex;\n  justify-content: center;\n  align-items: center;\n  gap: 8px;\n  color: var(--text-dim);\n  font-family: var(--font-mono);\n  font-size: 12px;\n  padding: 4px 0;\n  animation: fadeUp 0.4s ease-out both;\n  animation-delay: calc(var(--i, 0) * 0.06s);\n}\n\n.flow-arrow svg {\n  width: 20px;\n  height: 20px;\n  fill: none;\n  stroke: var(--border-bright);\n  stroke-width: 2;\n  stroke-linecap: round;\n  stroke-linejoin: round;\n}\n\n/* Code styling */\ncode {\n  font-family: var(--font-mono);\n  font-size: 0.9em;\n  background: var(--accent-dim);\n  color: var(--accent);\n  padding: 2px 6px;\n  border-radius: 4px;\n}\n\n/* Responsive */\n@media (max-width: 768px) {\n  body { padding: 20px; }\n  .section { padding: 16px 20px; }\n  .section--hero { padding: 20px 24px; }\n}\n";
-export declare const MERMAID_SHELL_CSS = "\n.diagram-shell {\n  background: var(--surface);\n  border: 1px solid var(--border);\n  border-radius: 12px;\n  overflow: hidden;\n}\n\n.mermaid-wrap {\n  position: relative;\n  display: flex;\n  justify-content: center;\n  padding: 24px;\n}\n\n.mermaid-viewport {\n  overflow: hidden;\n  cursor: grab;\n}\n\n.mermaid-viewport:active {\n  cursor: grabbing;\n}\n\n.mermaid-canvas {\n  transform-origin: center center;\n  transition: transform 0.1s ease-out;\n}\n\n.zoom-controls {\n  position: absolute;\n  top: 12px;\n  right: 12px;\n  display: flex;\n  gap: 6px;\n  z-index: 10;\n}\n\n.zoom-btn {\n  width: 32px;\n  height: 32px;\n  border: 1px solid var(--border);\n  border-radius: 6px;\n  background: var(--surface);\n  color: var(--text);\n  font-size: 16px;\n  cursor: pointer;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: all 0.2s;\n}\n\n.zoom-btn:hover {\n  background: var(--surface2);\n  border-color: var(--border-bright);\n}\n";
-export declare const MERMAID_SHELL_JS = "\nfunction initMermaidControls(wrap) {\n  const viewport = wrap.querySelector('.mermaid-viewport');\n  const canvas = wrap.querySelector('.mermaid-canvas');\n  let scale = 1;\n  let isDragging = false;\n  let startX, startY, translateX = 0, translateY = 0;\n\n  function updateTransform() {\n    canvas.style.transform = `translate(${translateX}px, ${translateY}px) scale(${scale})`;\n  }\n\n  wrap.querySelector('[data-zoom=\"in\"]').onclick = () => { scale *= 1.2; updateTransform(); };\n  wrap.querySelector('[data-zoom=\"out\"]').onclick = () => { scale /= 1.2; updateTransform(); };\n  wrap.querySelector('[data-zoom=\"reset\"]').onclick = () => { scale = 1; translateX = 0; translateY = 0; updateTransform(); };\n  wrap.querySelector('[data-zoom=\"expand\"]').onclick = () => openMermaidInNewTab(wrap);\n\n  viewport.addEventListener('mousedown', (e) => {\n    isDragging = true;\n    startX = e.clientX - translateX;\n    startY = e.clientY - translateY;\n    viewport.style.cursor = 'grabbing';\n  });\n\n  window.addEventListener('mousemove', (e) => {\n    if (!isDragging) return;\n    translateX = e.clientX - startX;\n    translateY = e.clientY - startY;\n    updateTransform();\n  });\n\n  window.addEventListener('mouseup', () => {\n    isDragging = false;\n    viewport.style.cursor = 'grab';\n  });\n\n  viewport.addEventListener('wheel', (e) => {\n    if (e.ctrlKey || e.metaKey) {\n      e.preventDefault();\n      scale *= e.deltaY > 0 ? 0.9 : 1.1;\n      updateTransform();\n    }\n  }, { passive: false });\n}\n\nfunction openMermaidInNewTab(wrap) {\n  const svg = wrap.querySelector('svg');\n  if (!svg) return;\n  const blob = new Blob([svg.outerHTML], { type: 'image/svg+xml' });\n  const url = URL.createObjectURL(blob);\n  window.open(url, '_blank');\n}\n";
+export declare const MERMAID_SHELL_CSS = "\n.diagram-shell {\n  position: relative;\n  margin-bottom: 24px;\n}\n\n.diagram-shell__hint {\n  font-family: var(--font-mono);\n  font-size: 11px;\n  color: var(--text-dim);\n  margin-bottom: 8px;\n  opacity: 0.7;\n}\n\n.mermaid-wrap {\n  position: relative;\n  background: var(--surface);\n  border: 1px solid var(--border);\n  border-radius: 12px;\n  overflow: hidden;\n  min-height: 360px;\n}\n\n.mermaid-viewport {\n  position: relative;\n  overflow: hidden;\n  width: 100%;\n  height: 100%;\n  min-height: 300px;\n  cursor: grab;\n}\n\n.mermaid-wrap.is-panning .mermaid-viewport {\n  cursor: grabbing;\n  user-select: none;\n}\n\n.mermaid-canvas {\n  position: absolute;\n  top: 0;\n  left: 0;\n  transform-origin: 0 0;\n}\n\n.mermaid-canvas svg {\n  display: block;\n  max-width: none;\n}\n\n.zoom-controls {\n  position: absolute;\n  top: 8px;\n  right: 8px;\n  display: flex;\n  align-items: center;\n  gap: 2px;\n  z-index: 10;\n  background: var(--surface);\n  border: 1px solid var(--border);\n  border-radius: 6px;\n  padding: 2px 4px;\n}\n\n.zoom-controls button {\n  width: 28px;\n  height: 28px;\n  border: none;\n  background: transparent;\n  color: var(--text-dim);\n  font-family: var(--font-mono);\n  font-size: 14px;\n  cursor: pointer;\n  border-radius: 4px;\n  display: flex;\n  align-items: center;\n  justify-content: center;\n  transition: background 0.15s ease, color 0.15s ease;\n}\n\n.zoom-controls button:hover {\n  background: var(--border);\n  color: var(--text);\n}\n\n.zoom-label {\n  font-family: var(--font-mono);\n  font-size: 10px;\n  color: var(--text-dim);\n  padding: 0 6px;\n  white-space: nowrap;\n}\n\n.mermaid .nodeLabel {\n  font-family: var(--font-body) !important;\n}\n\n.mermaid .edgeLabel {\n  font-family: var(--font-mono) !important;\n}\n";
+export declare const MERMAID_SHELL_JS = "\n(function initAllDiagrams() {\n  const config = {\n    fitPadding: 24,\n    minHeight: 360,\n    maxHeightPx: 960,\n    maxHeightVh: 0.84,\n    maxInitialZoom: 1.8,\n    minZoom: 0.08,\n    maxZoom: 6.5,\n    zoomStep: 0.14,\n    readabilityFloor: 0.58\n  };\n\n  const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));\n  let activeDrag = null;\n\n  addEventListener('mousemove', (e) => activeDrag && activeDrag.onMove(e));\n  addEventListener('mouseup', () => {\n    if (activeDrag) activeDrag.onEnd();\n    activeDrag = null;\n  });\n\n  function initDiagram(shell) {\n    const wrap = shell.querySelector('.mermaid-wrap');\n    const viewport = shell.querySelector('.mermaid-viewport');\n    const canvas = shell.querySelector('.mermaid-canvas');\n    const source = shell.querySelector('.diagram-source');\n    const label = shell.querySelector('.zoom-label');\n    if (!wrap || !viewport || !canvas || !source || !label) {\n      console.error('visual-explainer: missing required elements in', shell);\n      return;\n    }\n\n    let zoom = 1;\n    let fitMode = 'contain';\n    let panX = 0;\n    let panY = 0;\n    let svgW = 0;\n    let svgH = 0;\n    let sx = 0;\n    let sy = 0;\n    let spx = 0;\n    let spy = 0;\n    let touchDist = 0;\n    let touchCx = 0;\n    let touchCy = 0;\n\n    function constrainPan() {\n      const vpW = viewport.clientWidth;\n      const vpH = viewport.clientHeight;\n      const rW = svgW * zoom;\n      const rH = svgH * zoom;\n      const pad = config.fitPadding;\n      panX = (rW + pad * 2 <= vpW) ? (vpW - rW) / 2 : clamp(panX, vpW - rW - pad, pad);\n      panY = (rH + pad * 2 <= vpH) ? (vpH - rH) / 2 : clamp(panY, vpH - rH - pad, pad);\n    }\n\n    function applyTransform() {\n      const svg = canvas.querySelector('svg');\n      if (!svg || !svgW) return;\n      constrainPan();\n      svg.style.width = (svgW * zoom) + 'px';\n      svg.style.height = (svgH * zoom) + 'px';\n      canvas.style.transform = 'translate(' + panX + 'px, ' + panY + 'px)';\n      label.textContent = Math.round(zoom * 100) + '% \u2014 ' + fitMode;\n    }\n\n    function canPan() {\n      const rW = svgW * zoom;\n      const rH = svgH * zoom;\n      return rW + config.fitPadding * 2 > viewport.clientWidth\n          || rH + config.fitPadding * 2 > viewport.clientHeight;\n    }\n\n    function computeSmartFit() {\n      const vpW = viewport.clientWidth;\n      const vpH = viewport.clientHeight;\n      const aW = Math.max(80, vpW - config.fitPadding * 2);\n      const aH = Math.max(80, vpH - config.fitPadding * 2);\n      const contain = Math.min(aW / svgW, aH / svgH);\n      let z = contain;\n      let mode = 'contain';\n      if (contain < config.readabilityFloor) {\n        const chartR = svgH / svgW;\n        const vpR = vpH / Math.max(vpW, 1);\n        if (chartR >= vpR) { z = aW / svgW; mode = 'width-priority'; }\n        else { z = aH / svgH; mode = 'height-priority'; }\n      }\n      return { zoom: clamp(z, config.minZoom, config.maxInitialZoom), mode };\n    }\n\n    function fitDiagram() {\n      if (!svgW) return;\n      const fit = computeSmartFit();\n      zoom = fit.zoom;\n      fitMode = fit.mode;\n      panX = (viewport.clientWidth - svgW * zoom) / 2;\n      panY = (viewport.clientHeight - svgH * zoom) / 2;\n      applyTransform();\n    }\n\n    function setOneToOne() {\n      zoom = clamp(1, config.minZoom, config.maxZoom);\n      fitMode = '1:1';\n      panX = (viewport.clientWidth - svgW * zoom) / 2;\n      panY = (viewport.clientHeight - svgH * zoom) / 2;\n      applyTransform();\n    }\n\n    function zoomAround(factor, cx, cy) {\n      const next = clamp(zoom * factor, config.minZoom, config.maxZoom);\n      const ratio = next / zoom;\n      panX = cx - ratio * (cx - panX);\n      panY = cy - ratio * (cy - panY);\n      zoom = next;\n      fitMode = 'custom';\n      applyTransform();\n    }\n\n    function readSvgNaturalSize(svg) {\n      let w = 0;\n      let h = 0;\n      if (svg.viewBox && svg.viewBox.baseVal && svg.viewBox.baseVal.width > 0) {\n        w = svg.viewBox.baseVal.width;\n        h = svg.viewBox.baseVal.height;\n      }\n      if (!w) {\n        w = parseFloat(svg.getAttribute('width')) || 0;\n        h = parseFloat(svg.getAttribute('height')) || 0;\n      }\n      if (!w) {\n        try { const b = svg.getBBox(); w = b.width; h = b.height; } catch {}\n      }\n      if (!w) {\n        const r = svg.getBoundingClientRect();\n        w = r.width || 1000;\n        h = r.height || 700;\n      }\n      if (!svg.getAttribute('viewBox')) {\n        svg.setAttribute('viewBox', '0 0 ' + w + ' ' + h);\n      }\n      return { w, h };\n    }\n\n    function setAdaptiveHeight() {\n      if (!svgW) return;\n      const usableW = Math.max(280, wrap.getBoundingClientRect().width - 2);\n      const idealH = (svgH / svgW) * usableW + config.fitPadding * 2;\n      const maxVp = Math.floor(innerHeight * config.maxHeightVh);\n      const hardMax = Math.min(config.maxHeightPx, Math.max(config.minHeight + 40, maxVp));\n      wrap.style.height = Math.round(clamp(idealH, config.minHeight, hardMax)) + 'px';\n    }\n\n    function openInNewTab() {\n      const svg = canvas.querySelector('svg');\n      if (!svg) return;\n      const clone = svg.cloneNode(true);\n      clone.style.width = '';\n      clone.style.height = '';\n      // Read the page background from the wrap's data-bg attribute (written\n      // server-side from the current palette). This guarantees the new tab\n      // matches the diagram's baked-in theme.\n      const bg = wrap.getAttribute('data-bg') || '#ffffff';\n      const html = '<!DOCTYPE html><html lang=\"en\"><head><meta charset=\"UTF-8\">'\n        + '<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">'\n        + '<title>Diagram</title><style>'\n        + 'body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;'\n        + 'background:' + bg + ';padding:40px;box-sizing:border-box}'\n        + 'svg{max-width:100%;max-height:90vh;height:auto}'\n        + '</style></head><body>' + clone.outerHTML + '</body></html>';\n      open(URL.createObjectURL(new Blob([html], { type: 'text/html' })), '_blank');\n    }\n\n    function waitForMermaid() {\n      return new Promise((resolve, reject) => {\n        if (window.mermaid && typeof window.mermaid.render === 'function') {\n          resolve(window.mermaid);\n          return;\n        }\n        const started = Date.now();\n        const timer = setInterval(() => {\n          if (window.mermaid && typeof window.mermaid.render === 'function') {\n            clearInterval(timer);\n            resolve(window.mermaid);\n          } else if (Date.now() - started > 10000) {\n            clearInterval(timer);\n            reject(new Error('Mermaid failed to load from CDN (10s timeout)'));\n          }\n        }, 50);\n      });\n    }\n\n    async function render() {\n      try {\n        const code = (source.textContent || '').trim();\n        if (!code) {\n          label.textContent = 'Error: empty source';\n          return;\n        }\n        const mermaid = await waitForMermaid();\n        const id = 'diagram-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);\n        const { svg } = await mermaid.render(id, code);\n        canvas.innerHTML = svg;\n        const svgNode = canvas.querySelector('svg');\n        if (!svgNode) {\n          label.textContent = 'Error: no SVG';\n          return;\n        }\n        const size = readSvgNaturalSize(svgNode);\n        svgW = size.w;\n        svgH = size.h;\n        svgNode.removeAttribute('width');\n        svgNode.removeAttribute('height');\n        svgNode.style.maxWidth = 'none';\n        svgNode.style.display = 'block';\n        setAdaptiveHeight();\n        fitDiagram();\n      } catch (err) {\n        console.error('visual-explainer mermaid render failed:', err);\n        label.textContent = 'Error: ' + (err && err.message ? err.message : 'render failed');\n        canvas.innerHTML = '<pre style=\"padding:20px;color:#b00020;white-space:pre-wrap;font-family:monospace;font-size:12px\">'\n          + String(err && err.message ? err.message : err).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]))\n          + '</pre>';\n      }\n    }\n\n    const actions = {\n      'zoom-in':     () => zoomAround(1 + config.zoomStep, viewport.clientWidth / 2, viewport.clientHeight / 2),\n      'zoom-out':    () => zoomAround(1 / (1 + config.zoomStep), viewport.clientWidth / 2, viewport.clientHeight / 2),\n      'zoom-fit':    fitDiagram,\n      'zoom-one':    setOneToOne,\n      'zoom-expand': openInNewTab\n    };\n    Object.keys(actions).forEach((action) => {\n      const btn = wrap.querySelector('[data-action=\"' + action + '\"]');\n      if (btn) btn.addEventListener('click', actions[action]);\n    });\n\n    viewport.addEventListener('dblclick', fitDiagram);\n\n    viewport.addEventListener('wheel', (e) => {\n      if (e.ctrlKey || e.metaKey) {\n        e.preventDefault();\n        const rect = viewport.getBoundingClientRect();\n        const factor = e.deltaY < 0 ? 1 + config.zoomStep : 1 / (1 + config.zoomStep);\n        zoomAround(factor, e.clientX - rect.left, e.clientY - rect.top);\n        return;\n      }\n      if (canPan()) {\n        e.preventDefault();\n        panX -= e.deltaX;\n        panY -= e.deltaY;\n        applyTransform();\n      }\n    }, { passive: false });\n\n    viewport.addEventListener('mousedown', (e) => {\n      if (e.target.closest('.zoom-controls') || !canPan()) return;\n      wrap.classList.add('is-panning');\n      sx = e.clientX;\n      sy = e.clientY;\n      spx = panX;\n      spy = panY;\n      e.preventDefault();\n      activeDrag = {\n        onMove: (ev) => {\n          panX = spx + (ev.clientX - sx);\n          panY = spy + (ev.clientY - sy);\n          applyTransform();\n        },\n        onEnd: () => { wrap.classList.remove('is-panning'); }\n      };\n    });\n\n    viewport.addEventListener('touchstart', (e) => {\n      if (e.touches.length === 1) {\n        sx = e.touches[0].clientX;\n        sy = e.touches[0].clientY;\n        spx = panX;\n        spy = panY;\n      } else if (e.touches.length === 2) {\n        const dx = e.touches[0].clientX - e.touches[1].clientX;\n        const dy = e.touches[0].clientY - e.touches[1].clientY;\n        touchDist = Math.sqrt(dx * dx + dy * dy);\n        const r = viewport.getBoundingClientRect();\n        touchCx = (e.touches[0].clientX + e.touches[1].clientX) / 2 - r.left;\n        touchCy = (e.touches[0].clientY + e.touches[1].clientY) / 2 - r.top;\n      }\n    }, { passive: true });\n\n    viewport.addEventListener('touchmove', (e) => {\n      if (e.touches.length === 1 && canPan()) {\n        if (touchDist > 0) {\n          sx = e.touches[0].clientX;\n          sy = e.touches[0].clientY;\n          spx = panX;\n          spy = panY;\n          touchDist = 0;\n        }\n        e.preventDefault();\n        panX = spx + (e.touches[0].clientX - sx);\n        panY = spy + (e.touches[0].clientY - sy);\n        applyTransform();\n      } else if (e.touches.length === 2 && touchDist > 0) {\n        e.preventDefault();\n        const dx = e.touches[0].clientX - e.touches[1].clientX;\n        const dy = e.touches[0].clientY - e.touches[1].clientY;\n        const d = Math.sqrt(dx * dx + dy * dy);\n        zoomAround(d / touchDist, touchCx, touchCy);\n        touchDist = d;\n      }\n    }, { passive: false });\n\n    new ResizeObserver(() => {\n      if (svgW) { setAdaptiveHeight(); fitDiagram(); }\n    }).observe(wrap);\n\n    render();\n  }\n\n  function bootstrap() {\n    document.querySelectorAll('.diagram-shell').forEach(initDiagram);\n  }\n\n  if (document.readyState === 'loading') {\n    document.addEventListener('DOMContentLoaded', bootstrap);\n  } else {\n    bootstrap();\n  }\n})();\n";
 export declare function generateCSSVariables(palette: Palette, fonts: FontPairing, isDark: boolean): string;
 export declare function generateHtmlShell(title: string, bodyContent: string, aesthetic: string, cssVariables: string, extraHead?: string, extraScripts?: string): string;
 export declare function escapeHtml(str: string): string;

package/dist/templates/shared.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/templates/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGnE,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAiCxD,CAAC;AAGF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,SAAS,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAiVzE,CAAC;AAGF,eAAO,MAAM,UAAU,63EAgHtB,CAAC;AAGF,eAAO,MAAM,iBAAiB,w9BAyD7B,CAAC;AAEF,eAAO,MAAM,gBAAgB,0vDAoD5B,CAAC;AAGF,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,OAAO,GACb,MAAM,CA0BR;AAGD,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAK,EACd,YAAY,SAAK,GACf,MAAM,CAqBR;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C"}
+{"version":3,"file":"shared.d.ts","sourceRoot":"","sources":["../../src/templates/shared.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,OAAO,EAAE,MAAM,aAAa,CAAC;AAGnE,eAAO,MAAM,aAAa,EAAE,MAAM,CAAC,SAAS,EAAE,WAAW,CAiCxD,CAAC;AAGF,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,SAAS,EAAE;IAAE,KAAK,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,OAAO,CAAA;CAAE,CAiVzE,CAAC;AAGF,eAAO,MAAM,UAAU,63EAgHtB,CAAC;AAkBF,eAAO,MAAM,iBAAiB,owDAmG7B,CAAC;AAKF,eAAO,MAAM,gBAAgB,+nXA2U5B,CAAC;AAGF,wBAAgB,oBAAoB,CACnC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,OAAO,GACb,MAAM,CA0BR;AAGD,wBAAgB,iBAAiB,CAChC,KAAK,EAAE,MAAM,EACb,WAAW,EAAE,MAAM,EACnB,SAAS,EAAE,MAAM,EACjB,YAAY,EAAE,MAAM,EACpB,SAAS,SAAK,EACd,YAAY,SAAK,GACf,MAAM,CAqBR;AAGD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAO9C"}

package/dist/templates/shared.js

@@ -490,117 +490,456 @@ code {
   .section--hero { padding: 20px 24px; }
 }
 `;
-// Mermaid zoom/pan CSS and JS
+// Mermaid zoom/pan CSS and JS.
+//
+// This is the proven pattern from nicobailon/visual-explainer's reference
+// mermaid-flowchart.html. The earlier implementation had several subtle bugs:
+//   - mermaid source lived in <pre class="mermaid"> so the HTML parser would
+//     mangle `<br/>`, `<`, `>`, `&` before Mermaid ever saw the text
+//   - `startOnLoad: true` + a 500ms setTimeout to bind zoom controls is a
+//     race — on large diagrams the controls would never bind
+//   - the viewport had no height, so pan and fit were meaningless
+//   - new-tab export produced a blank page (bare SVG blob, no background)
+//
+// Now the source lives in a `<script type="text/plain" class="diagram-source">`
+// which the HTML parser treats as opaque data; we render explicitly via
+// `mermaid.render(id, code)` and await it before binding handlers. Adaptive
+// height is computed from the SVG's intrinsic aspect ratio. The new-tab
+// export wraps the SVG in a minimal HTML shell with the page background.
 export const MERMAID_SHELL_CSS = `
 .diagram-shell {
-  background: var(--surface);
-  border: 1px solid var(--border);
-  border-radius: 12px;
-  overflow: hidden;
+  position: relative;
+  margin-bottom: 24px;
+}
+
+.diagram-shell__hint {
+  font-family: var(--font-mono);
+  font-size: 11px;
+  color: var(--text-dim);
+  margin-bottom: 8px;
+  opacity: 0.7;
 }
 
 .mermaid-wrap {
   position: relative;
-  display: flex;
-  justify-content: center;
-  padding: 24px;
+  background: var(--surface);
+  border: 1px solid var(--border);
+  border-radius: 12px;
+  overflow: hidden;
+  min-height: 360px;
 }
 
 .mermaid-viewport {
+  position: relative;
   overflow: hidden;
+  width: 100%;
+  height: 100%;
+  min-height: 300px;
   cursor: grab;
 }
 
-.mermaid-viewport:active {
+.mermaid-wrap.is-panning .mermaid-viewport {
   cursor: grabbing;
+  user-select: none;
 }
 
 .mermaid-canvas {
-  transform-origin: center center;
-  transition: transform 0.1s ease-out;
+  position: absolute;
+  top: 0;
+  left: 0;
+  transform-origin: 0 0;
+}
+
+.mermaid-canvas svg {
+  display: block;
+  max-width: none;
 }
 
 .zoom-controls {
   position: absolute;
-  top: 12px;
-  right: 12px;
+  top: 8px;
+  right: 8px;
   display: flex;
-  gap: 6px;
+  align-items: center;
+  gap: 2px;
   z-index: 10;
-}
-
-.zoom-btn {
-  width: 32px;
-  height: 32px;
+  background: var(--surface);
   border: 1px solid var(--border);
   border-radius: 6px;
-  background: var(--surface);
-  color: var(--text);
-  font-size: 16px;
+  padding: 2px 4px;
+}
+
+.zoom-controls button {
+  width: 28px;
+  height: 28px;
+  border: none;
+  background: transparent;
+  color: var(--text-dim);
+  font-family: var(--font-mono);
+  font-size: 14px;
   cursor: pointer;
+  border-radius: 4px;
   display: flex;
   align-items: center;
   justify-content: center;
-  transition: all 0.2s;
+  transition: background 0.15s ease, color 0.15s ease;
 }
 
-.zoom-btn:hover {
-  background: var(--surface2);
-  border-color: var(--border-bright);
+.zoom-controls button:hover {
+  background: var(--border);
+  color: var(--text);
+}
+
+.zoom-label {
+  font-family: var(--font-mono);
+  font-size: 10px;
+  color: var(--text-dim);
+  padding: 0 6px;
+  white-space: nowrap;
+}
+
+.mermaid .nodeLabel {
+  font-family: var(--font-body) !important;
+}
+
+.mermaid .edgeLabel {
+  font-family: var(--font-mono) !important;
 }
 `;
+// Vanilla IIFE — no module scope needed. Handles multiple `.diagram-shell`
+// instances on the same page. Each instance has its own `<script
+// type="text/plain" class="diagram-source">` holding the raw mermaid source.
 export const MERMAID_SHELL_JS = `
-function initMermaidControls(wrap) {
-  const viewport = wrap.querySelector('.mermaid-viewport');
-  const canvas = wrap.querySelector('.mermaid-canvas');
-  let scale = 1;
-  let isDragging = false;
-  let startX, startY, translateX = 0, translateY = 0;
-
-  function updateTransform() {
-    canvas.style.transform = \`translate(\${translateX}px, \${translateY}px) scale(\${scale})\`;
-  }
+(function initAllDiagrams() {
+  const config = {
+    fitPadding: 24,
+    minHeight: 360,
+    maxHeightPx: 960,
+    maxHeightVh: 0.84,
+    maxInitialZoom: 1.8,
+    minZoom: 0.08,
+    maxZoom: 6.5,
+    zoomStep: 0.14,
+    readabilityFloor: 0.58
+  };
 
-  wrap.querySelector('[data-zoom="in"]').onclick = () => { scale *= 1.2; updateTransform(); };
-  wrap.querySelector('[data-zoom="out"]').onclick = () => { scale /= 1.2; updateTransform(); };
-  wrap.querySelector('[data-zoom="reset"]').onclick = () => { scale = 1; translateX = 0; translateY = 0; updateTransform(); };
-  wrap.querySelector('[data-zoom="expand"]').onclick = () => openMermaidInNewTab(wrap);
+  const clamp = (n, lo, hi) => Math.max(lo, Math.min(hi, n));
+  let activeDrag = null;
 
-  viewport.addEventListener('mousedown', (e) => {
-    isDragging = true;
-    startX = e.clientX - translateX;
-    startY = e.clientY - translateY;
-    viewport.style.cursor = 'grabbing';
+  addEventListener('mousemove', (e) => activeDrag && activeDrag.onMove(e));
+  addEventListener('mouseup', () => {
+    if (activeDrag) activeDrag.onEnd();
+    activeDrag = null;
   });
 
-  window.addEventListener('mousemove', (e) => {
-    if (!isDragging) return;
-    translateX = e.clientX - startX;
-    translateY = e.clientY - startY;
-    updateTransform();
-  });
+  function initDiagram(shell) {
+    const wrap = shell.querySelector('.mermaid-wrap');
+    const viewport = shell.querySelector('.mermaid-viewport');
+    const canvas = shell.querySelector('.mermaid-canvas');
+    const source = shell.querySelector('.diagram-source');
+    const label = shell.querySelector('.zoom-label');
+    if (!wrap || !viewport || !canvas || !source || !label) {
+      console.error('visual-explainer: missing required elements in', shell);
+      return;
+    }
 
-  window.addEventListener('mouseup', () => {
-    isDragging = false;
-    viewport.style.cursor = 'grab';
-  });
+    let zoom = 1;
+    let fitMode = 'contain';
+    let panX = 0;
+    let panY = 0;
+    let svgW = 0;
+    let svgH = 0;
+    let sx = 0;
+    let sy = 0;
+    let spx = 0;
+    let spy = 0;
+    let touchDist = 0;
+    let touchCx = 0;
+    let touchCy = 0;
 
-  viewport.addEventListener('wheel', (e) => {
-    if (e.ctrlKey || e.metaKey) {
-      e.preventDefault();
-      scale *= e.deltaY > 0 ? 0.9 : 1.1;
-      updateTransform();
+    function constrainPan() {
+      const vpW = viewport.clientWidth;
+      const vpH = viewport.clientHeight;
+      const rW = svgW * zoom;
+      const rH = svgH * zoom;
+      const pad = config.fitPadding;
+      panX = (rW + pad * 2 <= vpW) ? (vpW - rW) / 2 : clamp(panX, vpW - rW - pad, pad);
+      panY = (rH + pad * 2 <= vpH) ? (vpH - rH) / 2 : clamp(panY, vpH - rH - pad, pad);
     }
-  }, { passive: false });
-}
 
-function openMermaidInNewTab(wrap) {
-  const svg = wrap.querySelector('svg');
-  if (!svg) return;
-  const blob = new Blob([svg.outerHTML], { type: 'image/svg+xml' });
-  const url = URL.createObjectURL(blob);
-  window.open(url, '_blank');
-}
+    function applyTransform() {
+      const svg = canvas.querySelector('svg');
+      if (!svg || !svgW) return;
+      constrainPan();
+      svg.style.width = (svgW * zoom) + 'px';
+      svg.style.height = (svgH * zoom) + 'px';
+      canvas.style.transform = 'translate(' + panX + 'px, ' + panY + 'px)';
+      label.textContent = Math.round(zoom * 100) + '% \u2014 ' + fitMode;
+    }
+
+    function canPan() {
+      const rW = svgW * zoom;
+      const rH = svgH * zoom;
+      return rW + config.fitPadding * 2 > viewport.clientWidth
+          || rH + config.fitPadding * 2 > viewport.clientHeight;
+    }
+
+    function computeSmartFit() {
+      const vpW = viewport.clientWidth;
+      const vpH = viewport.clientHeight;
+      const aW = Math.max(80, vpW - config.fitPadding * 2);
+      const aH = Math.max(80, vpH - config.fitPadding * 2);
+      const contain = Math.min(aW / svgW, aH / svgH);
+      let z = contain;
+      let mode = 'contain';
+      if (contain < config.readabilityFloor) {
+        const chartR = svgH / svgW;
+        const vpR = vpH / Math.max(vpW, 1);
+        if (chartR >= vpR) { z = aW / svgW; mode = 'width-priority'; }
+        else { z = aH / svgH; mode = 'height-priority'; }
+      }
+      return { zoom: clamp(z, config.minZoom, config.maxInitialZoom), mode };
+    }
+
+    function fitDiagram() {
+      if (!svgW) return;
+      const fit = computeSmartFit();
+      zoom = fit.zoom;
+      fitMode = fit.mode;
+      panX = (viewport.clientWidth - svgW * zoom) / 2;
+      panY = (viewport.clientHeight - svgH * zoom) / 2;
+      applyTransform();
+    }
+
+    function setOneToOne() {
+      zoom = clamp(1, config.minZoom, config.maxZoom);
+      fitMode = '1:1';
+      panX = (viewport.clientWidth - svgW * zoom) / 2;
+      panY = (viewport.clientHeight - svgH * zoom) / 2;
+      applyTransform();
+    }
+
+    function zoomAround(factor, cx, cy) {
+      const next = clamp(zoom * factor, config.minZoom, config.maxZoom);
+      const ratio = next / zoom;
+      panX = cx - ratio * (cx - panX);
+      panY = cy - ratio * (cy - panY);
+      zoom = next;
+      fitMode = 'custom';
+      applyTransform();
+    }
+
+    function readSvgNaturalSize(svg) {
+      let w = 0;
+      let h = 0;
+      if (svg.viewBox && svg.viewBox.baseVal && svg.viewBox.baseVal.width > 0) {
+        w = svg.viewBox.baseVal.width;
+        h = svg.viewBox.baseVal.height;
+      }
+      if (!w) {
+        w = parseFloat(svg.getAttribute('width')) || 0;
+        h = parseFloat(svg.getAttribute('height')) || 0;
+      }
+      if (!w) {
+        try { const b = svg.getBBox(); w = b.width; h = b.height; } catch {}
+      }
+      if (!w) {
+        const r = svg.getBoundingClientRect();
+        w = r.width || 1000;
+        h = r.height || 700;
+      }
+      if (!svg.getAttribute('viewBox')) {
+        svg.setAttribute('viewBox', '0 0 ' + w + ' ' + h);
+      }
+      return { w, h };
+    }
+
+    function setAdaptiveHeight() {
+      if (!svgW) return;
+      const usableW = Math.max(280, wrap.getBoundingClientRect().width - 2);
+      const idealH = (svgH / svgW) * usableW + config.fitPadding * 2;
+      const maxVp = Math.floor(innerHeight * config.maxHeightVh);
+      const hardMax = Math.min(config.maxHeightPx, Math.max(config.minHeight + 40, maxVp));
+      wrap.style.height = Math.round(clamp(idealH, config.minHeight, hardMax)) + 'px';
+    }
+
+    function openInNewTab() {
+      const svg = canvas.querySelector('svg');
+      if (!svg) return;
+      const clone = svg.cloneNode(true);
+      clone.style.width = '';
+      clone.style.height = '';
+      // Read the page background from the wrap's data-bg attribute (written
+      // server-side from the current palette). This guarantees the new tab
+      // matches the diagram's baked-in theme.
+      const bg = wrap.getAttribute('data-bg') || '#ffffff';
+      const html = '<!DOCTYPE html><html lang="en"><head><meta charset="UTF-8">'
+        + '<meta name="viewport" content="width=device-width, initial-scale=1.0">'
+        + '<title>Diagram</title><style>'
+        + 'body{margin:0;min-height:100vh;display:flex;align-items:center;justify-content:center;'
+        + 'background:' + bg + ';padding:40px;box-sizing:border-box}'
+        + 'svg{max-width:100%;max-height:90vh;height:auto}'
+        + '</style></head><body>' + clone.outerHTML + '</body></html>';
+      open(URL.createObjectURL(new Blob([html], { type: 'text/html' })), '_blank');
+    }
+
+    function waitForMermaid() {
+      return new Promise((resolve, reject) => {
+        if (window.mermaid && typeof window.mermaid.render === 'function') {
+          resolve(window.mermaid);
+          return;
+        }
+        const started = Date.now();
+        const timer = setInterval(() => {
+          if (window.mermaid && typeof window.mermaid.render === 'function') {
+            clearInterval(timer);
+            resolve(window.mermaid);
+          } else if (Date.now() - started > 10000) {
+            clearInterval(timer);
+            reject(new Error('Mermaid failed to load from CDN (10s timeout)'));
+          }
+        }, 50);
+      });
+    }
+
+    async function render() {
+      try {
+        const code = (source.textContent || '').trim();
+        if (!code) {
+          label.textContent = 'Error: empty source';
+          return;
+        }
+        const mermaid = await waitForMermaid();
+        const id = 'diagram-' + Date.now() + '-' + Math.random().toString(36).slice(2, 8);
+        const { svg } = await mermaid.render(id, code);
+        canvas.innerHTML = svg;
+        const svgNode = canvas.querySelector('svg');
+        if (!svgNode) {
+          label.textContent = 'Error: no SVG';
+          return;
+        }
+        const size = readSvgNaturalSize(svgNode);
+        svgW = size.w;
+        svgH = size.h;
+        svgNode.removeAttribute('width');
+        svgNode.removeAttribute('height');
+        svgNode.style.maxWidth = 'none';
+        svgNode.style.display = 'block';
+        setAdaptiveHeight();
+        fitDiagram();
+      } catch (err) {
+        console.error('visual-explainer mermaid render failed:', err);
+        label.textContent = 'Error: ' + (err && err.message ? err.message : 'render failed');
+        canvas.innerHTML = '<pre style="padding:20px;color:#b00020;white-space:pre-wrap;font-family:monospace;font-size:12px">'
+          + String(err && err.message ? err.message : err).replace(/[&<>]/g, (c) => ({'&':'&amp;','<':'&lt;','>':'&gt;'}[c]))
+          + '</pre>';
+      }
+    }
+
+    const actions = {
+      'zoom-in':     () => zoomAround(1 + config.zoomStep, viewport.clientWidth / 2, viewport.clientHeight / 2),
+      'zoom-out':    () => zoomAround(1 / (1 + config.zoomStep), viewport.clientWidth / 2, viewport.clientHeight / 2),
+      'zoom-fit':    fitDiagram,
+      'zoom-one':    setOneToOne,
+      'zoom-expand': openInNewTab
+    };
+    Object.keys(actions).forEach((action) => {
+      const btn = wrap.querySelector('[data-action="' + action + '"]');
+      if (btn) btn.addEventListener('click', actions[action]);
+    });
+
+    viewport.addEventListener('dblclick', fitDiagram);
+
+    viewport.addEventListener('wheel', (e) => {
+      if (e.ctrlKey || e.metaKey) {
+        e.preventDefault();
+        const rect = viewport.getBoundingClientRect();
+        const factor = e.deltaY < 0 ? 1 + config.zoomStep : 1 / (1 + config.zoomStep);
+        zoomAround(factor, e.clientX - rect.left, e.clientY - rect.top);
+        return;
+      }
+      if (canPan()) {
+        e.preventDefault();
+        panX -= e.deltaX;
+        panY -= e.deltaY;
+        applyTransform();
+      }
+    }, { passive: false });
+
+    viewport.addEventListener('mousedown', (e) => {
+      if (e.target.closest('.zoom-controls') || !canPan()) return;
+      wrap.classList.add('is-panning');
+      sx = e.clientX;
+      sy = e.clientY;
+      spx = panX;
+      spy = panY;
+      e.preventDefault();
+      activeDrag = {
+        onMove: (ev) => {
+          panX = spx + (ev.clientX - sx);
+          panY = spy + (ev.clientY - sy);
+          applyTransform();
+        },
+        onEnd: () => { wrap.classList.remove('is-panning'); }
+      };
+    });
+
+    viewport.addEventListener('touchstart', (e) => {
+      if (e.touches.length === 1) {
+        sx = e.touches[0].clientX;
+        sy = e.touches[0].clientY;
+        spx = panX;
+        spy = panY;
+      } else if (e.touches.length === 2) {
+        const dx = e.touches[0].clientX - e.touches[1].clientX;
+        const dy = e.touches[0].clientY - e.touches[1].clientY;
+        touchDist = Math.sqrt(dx * dx + dy * dy);
+        const r = viewport.getBoundingClientRect();
+        touchCx = (e.touches[0].clientX + e.touches[1].clientX) / 2 - r.left;
+        touchCy = (e.touches[0].clientY + e.touches[1].clientY) / 2 - r.top;
+      }
+    }, { passive: true });
+
+    viewport.addEventListener('touchmove', (e) => {
+      if (e.touches.length === 1 && canPan()) {
+        if (touchDist > 0) {
+          sx = e.touches[0].clientX;
+          sy = e.touches[0].clientY;
+          spx = panX;
+          spy = panY;
+          touchDist = 0;
+        }
+        e.preventDefault();
+        panX = spx + (e.touches[0].clientX - sx);
+        panY = spy + (e.touches[0].clientY - sy);
+        applyTransform();
+      } else if (e.touches.length === 2 && touchDist > 0) {
+        e.preventDefault();
+        const dx = e.touches[0].clientX - e.touches[1].clientX;
+        const dy = e.touches[0].clientY - e.touches[1].clientY;
+        const d = Math.sqrt(dx * dx + dy * dy);
+        zoomAround(d / touchDist, touchCx, touchCy);
+        touchDist = d;
+      }
+    }, { passive: false });
+
+    new ResizeObserver(() => {
+      if (svgW) { setAdaptiveHeight(); fitDiagram(); }
+    }).observe(wrap);
+
+    render();
+  }
+
+  function bootstrap() {
+    document.querySelectorAll('.diagram-shell').forEach(initDiagram);
+  }
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', bootstrap);
+  } else {
+    bootstrap();
+  }
+})();
 `;
 // Helper to generate CSS variables from palette
 export function generateCSSVariables(palette, fonts, isDark) {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@the-forge-flow/visual-explainer-pi",
-	"version": "0.2.0",
+	"version": "0.2.1",
 	"description": "PI extension for generating beautiful HTML visualizations of diagrams, architecture, and data",
 	"type": "module",
 	"main": "dist/index.js",