@synergenius/flow-weaver 0.3.0 → 0.4.1

package/dist/cli/index.js

@@ -99,13 +99,14 @@ program
 // Diagram command
 program
     .command('diagram <input>')
-    .description('Generate SVG diagram of a workflow')
+    .description('Generate SVG or interactive HTML diagram of a workflow')
     .option('-t, --theme <theme>', 'Color theme: dark (default), light', 'dark')
     .option('-w, --width <pixels>', 'SVG width in pixels')
     .option('-p, --padding <pixels>', 'Canvas padding in pixels')
     .option('--no-port-labels', 'Hide data type labels on ports')
     .option('--workflow-name <name>', 'Specific workflow to render')
-    .option('-o, --output <file>', 'Write SVG to file instead of stdout')
+    .option('-f, --format <format>', 'Output format: svg (default), html (interactive viewer)', 'svg')
+    .option('-o, --output <file>', 'Write output to file instead of stdout')
     .action(async (input, options) => {
     try {
         if (options.width)
@@ -586,43 +587,28 @@ program
         process.exit(1);
     }
 });
-// Docs command group
-const docsCmd = program.command('docs').description('Browse reference documentation');
-docsCmd
-    .command('list', { isDefault: true })
-    .description('List available documentation topics')
-    .option('--json', 'Output as JSON', false)
-    .option('--compact', 'Compact output', false)
-    .action(async (options) => {
-    try {
-        await docsListCommand(options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
-docsCmd
-    .command('read <topic>')
-    .description('Read a documentation topic')
+// Docs command: flow-weaver docs [topic] | flow-weaver docs search <query>
+program
+    .command('docs [args...]')
+    .description('Browse reference documentation')
     .option('--json', 'Output as JSON', false)
     .option('--compact', 'Return compact LLM-friendly version', false)
-    .action(async (topic, options) => {
-    try {
-        await docsReadCommand(topic, options);
-    }
-    catch (error) {
-        logger.error(`Command failed: ${getErrorMessage(error)}`);
-        process.exit(1);
-    }
-});
-docsCmd
-    .command('search <query>')
-    .description('Search across all documentation')
-    .option('--json', 'Output as JSON', false)
-    .action(async (query, options) => {
+    .action(async (args, options) => {
     try {
-        await docsSearchCommand(query, options);
+        if (args.length === 0) {
+            await docsListCommand(options);
+        }
+        else if (args[0] === 'search') {
+            const query = args.slice(1).join(' ');
+            if (!query) {
+                logger.error('Usage: flow-weaver docs search <query>');
+                process.exit(1);
+            }
+            await docsSearchCommand(query, options);
+        }
+        else {
+            await docsReadCommand(args[0], options);
+        }
     }
     catch (error) {
         logger.error(`Command failed: ${getErrorMessage(error)}`);
@@ -727,6 +713,7 @@ program.on('--help', () => {
     logger.log('  $ flow-weaver describe workflow.ts --node validator');
     logger.log('  $ flow-weaver diagram workflow.ts');
     logger.log('  $ flow-weaver diagram workflow.ts --theme light -o diagram.svg');
+    logger.log('  $ flow-weaver diagram workflow.ts --format html -o diagram.html');
     logger.log('  $ flow-weaver diff workflow-v1.ts workflow-v2.ts');
     logger.log('  $ flow-weaver diff workflow-v1.ts workflow-v2.ts --format json');
     logger.log("  $ flow-weaver validate '**/*.ts'");

package/dist/diagram/geometry.js

@@ -508,6 +508,11 @@ function layerInputExtent(layerNodes, diagramNodes) {
  * Gap between layers adapts to port label extents so labels never overlap,
  * while using LAYER_GAP_X as the target center-to-center distance.
  */
+function adaptiveGapY(layerSize) {
+    if (layerSize <= 2)
+        return NODE_GAP_Y;
+    return Math.max(24, Math.round(NODE_GAP_Y * 2 / layerSize));
+}
 function assignLayerCoordinates(layers, diagramNodes) {
     // Pre-compute filtered layers
     const filtered = layers.map(l => l.filter(id => diagramNodes.has(id)));
@@ -519,17 +524,18 @@ function assignLayerCoordinates(layers, diagramNodes) {
             continue;
         }
         const maxWidth = Math.max(...layerNodes.map(id => diagramNodes.get(id).width));
+        const gapY = adaptiveGapY(layerNodes.length);
         const totalHeight = layerNodes.reduce((sum, id) => {
             const n = diagramNodes.get(id);
             return sum + n.height + LABEL_HEIGHT + LABEL_GAP;
-        }, 0) + (layerNodes.length - 1) * NODE_GAP_Y;
+        }, 0) + (layerNodes.length - 1) * gapY;
         let currentY = -totalHeight / 2;
         for (const id of layerNodes) {
             const node = diagramNodes.get(id);
             currentY += LABEL_HEIGHT + LABEL_GAP;
             node.x = currentX + (maxWidth - node.width) / 2;
             node.y = currentY;
-            currentY += node.height + NODE_GAP_Y;
+            currentY += node.height + gapY;
         }
         // Compute label-aware edge gap to the next layer
         const nextLayerNodes = filtered[i + 1];
@@ -570,17 +576,18 @@ function assignUnpositionedNodes(layers, diagramNodes, explicitPositions) {
         const unpositioned = layerNodes.filter(id => !explicitPositions.has(id));
         const maxWidth = Math.max(...layerNodes.map(id => diagramNodes.get(id).width));
         if (unpositioned.length > 0) {
+            const gapY = adaptiveGapY(unpositioned.length);
             const totalHeight = unpositioned.reduce((sum, id) => {
                 const n = diagramNodes.get(id);
                 return sum + n.height + LABEL_HEIGHT + LABEL_GAP;
-            }, 0) + (unpositioned.length - 1) * NODE_GAP_Y;
+            }, 0) + (unpositioned.length - 1) * gapY;
             let currentY = -totalHeight / 2;
             for (const id of unpositioned) {
                 const node = diagramNodes.get(id);
                 currentY += LABEL_HEIGHT + LABEL_GAP;
                 node.x = currentX + (maxWidth - node.width) / 2;
                 node.y = currentY;
-                currentY += node.height + NODE_GAP_Y;
+                currentY += node.height + gapY;
             }
         }
         // Label-aware edge gap
@@ -896,6 +903,40 @@ export function buildDiagramGraph(ast, options = {}) {
     });
     // Create a single TrackAllocator for deterministic batch routing
     const allocator = new TrackAllocator();
+    // Pre-compute routing mode consistency for fan-out and fan-in:
+    // When multiple connections share the same source port (fan-out), target
+    // port (fan-in), or target node (multi-port fan-in), use the same routing
+    // mode for visual consistency. If ANY connection in the group would use
+    // curves, force ALL connections in the group to curves.
+    const srcPortKey = (pc) => `srcPort:${pc.fromNodeId}.${pc.fromPortName}`;
+    const tgtPortKey = (pc) => `tgtPort:${pc.toNodeId}.${pc.toPortName}`;
+    const tgtNodeKey = (pc) => `tgtNode:${pc.toNodeId}`;
+    const routingGroups = new Map();
+    for (const pc of pendingConnections) {
+        for (const key of [srcPortKey(pc), tgtPortKey(pc), tgtNodeKey(pc)]) {
+            if (!routingGroups.has(key))
+                routingGroups.set(key, []);
+            routingGroups.get(key).push(pc);
+        }
+    }
+    const forceCurveKeys = new Set();
+    for (const [key, group] of routingGroups) {
+        if (group.length < 2)
+            continue;
+        const anyShort = group.some(pc => {
+            const dx = pc.targetPort.cx - pc.sourcePort.cx;
+            const dy = pc.targetPort.cy - pc.sourcePort.cy;
+            return Math.sqrt(dx * dx + dy * dy) <= ORTHOGONAL_DISTANCE_THRESHOLD;
+        });
+        if (anyShort)
+            forceCurveKeys.add(key);
+    }
+    const forceCurveSet = new Set();
+    for (const pc of pendingConnections) {
+        if (forceCurveKeys.has(srcPortKey(pc)) || forceCurveKeys.has(tgtPortKey(pc)) || forceCurveKeys.has(tgtNodeKey(pc))) {
+            forceCurveSet.add(pc);
+        }
+    }
     // Compute all connection paths with routing mode selection
     const connections = [];
     for (const pc of pendingConnections) {
@@ -906,8 +947,9 @@ export function buildDiagramGraph(ast, options = {}) {
         const dx = tx - sx;
         const dy = ty - sy;
         const distance = Math.sqrt(dx * dx + dy * dy);
+        const useCurve = forceCurveSet.has(pc);
         let path;
-        if (distance > ORTHOGONAL_DISTANCE_THRESHOLD) {
+        if (!useCurve && distance > ORTHOGONAL_DISTANCE_THRESHOLD) {
             // Try orthogonal routing for long-distance connections
             const orthoPath = calculateOrthogonalPathSafe([sx, sy], [tx, ty], nodeBoxes, pc.fromNodeId, pc.toNodeId, { fromPortIndex: pc.fromPortIndex, toPortIndex: pc.toPortIndex }, allocator);
             path = orthoPath ?? computeConnectionPath(sx, sy, tx, ty);

package/dist/diagram/html-viewer.d.ts

@@ -0,0 +1,12 @@
+/**
+ * HTML Viewer — wraps an SVG diagram in a self-contained interactive HTML page.
+ *
+ * Provides zoom/pan, fit-to-view, hover effects, click-to-inspect, and connection tracing.
+ * No external dependencies — works standalone or inside an iframe.
+ */
+export interface HtmlViewerOptions {
+    title?: string;
+    theme?: 'dark' | 'light';
+}
+export declare function wrapSVGInHTML(svgContent: string, options?: HtmlViewerOptions): string;
+//# sourceMappingURL=html-viewer.d.ts.map

package/dist/diagram/html-viewer.js

@@ -0,0 +1,399 @@
+/**
+ * HTML Viewer — wraps an SVG diagram in a self-contained interactive HTML page.
+ *
+ * Provides zoom/pan, fit-to-view, hover effects, click-to-inspect, and connection tracing.
+ * No external dependencies — works standalone or inside an iframe.
+ */
+/** Strip the SVG background rects so the HTML page controls the background. */
+function stripSvgBackground(svg) {
+    let result = svg.replace(/<pattern\s+id="dot-grid"[^>]*>[\s\S]*?<\/pattern>/g, '');
+    result = result.replace(/<rect[^>]*fill="url\(#dot-grid\)"[^>]*\/>/g, '');
+    // Remove the solid background rect (first rect after </defs>)
+    result = result.replace(/(<\/defs>\n)<rect[^>]*\/>\n/, '$1');
+    return result;
+}
+export function wrapSVGInHTML(svgContent, options = {}) {
+    const title = options.title ?? 'Workflow Diagram';
+    const theme = options.theme ?? 'dark';
+    const svg = stripSvgBackground(svgContent);
+    const isDark = theme === 'dark';
+    const bg = isDark ? '#202139' : '#f6f7ff';
+    const dotColor = isDark ? 'rgba(142, 158, 255, 0.6)' : 'rgba(84, 104, 255, 0.6)';
+    const surfaceMain = isDark ? '#1a1a2e' : '#ffffff';
+    const borderSubtle = isDark ? '#313143' : '#e6e6e6';
+    const textHigh = isDark ? '#e8e8ee' : '#1a1a2e';
+    const textMed = isDark ? '#babac0' : '#606060';
+    const textLow = isDark ? '#767682' : '#999999';
+    const surfaceHigh = isDark ? '#313143' : '#f0f0f5';
+    return `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>${escapeHtml(title)} — Flow Weaver</title>
+<style>
+*, *::before, *::after { margin: 0; padding: 0; box-sizing: border-box; }
+
+body {
+  width: 100vw; height: 100vh; overflow: hidden;
+  background: ${bg};
+  font-family: Montserrat, 'Segoe UI', Roboto, sans-serif;
+  color: ${textHigh};
+}
+
+#viewport {
+  width: 100%; height: 100%;
+  overflow: hidden; cursor: grab;
+  touch-action: none; user-select: none;
+  background-image: radial-gradient(circle, ${dotColor} 7.5%, transparent 7.5%);
+  background-size: 20px 20px;
+}
+#viewport.dragging { cursor: grabbing; }
+
+#content {
+  transform-origin: 0 0;
+  will-change: transform;
+}
+#content svg { display: block; width: auto; height: auto; }
+
+/* Port labels: hidden by default, shown on node hover */
+.nodes > g .port-label,
+.nodes > g .port-type-label,
+.labels g[data-port-label] {
+  opacity: 0; pointer-events: none;
+  transition: opacity 0.15s ease-in-out;
+}
+/* Show port labels for hovered node */
+.nodes > g:hover ~ .show-port-labels .port-label,
+.nodes > g:hover ~ .show-port-labels .port-type-label { opacity: 1; }
+
+/* Connection hover & dimming */
+.connections path { transition: opacity 0.2s ease, stroke-width 0.15s ease; }
+.connections path:hover { stroke-width: 4; cursor: pointer; }
+body.node-active .connections path.dimmed { opacity: 0.15; }
+
+/* Node hover glow */
+.nodes > g:hover rect:first-of-type { filter: brightness(1.08); }
+
+/* Zoom controls */
+#controls {
+  position: fixed; bottom: 16px; right: 16px;
+  display: flex; align-items: center; gap: 2px;
+  background: ${surfaceMain}; border: 1px solid ${borderSubtle};
+  border-radius: 8px; padding: 4px; z-index: 10;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+}
+.ctrl-btn {
+  display: flex; align-items: center; justify-content: center;
+  width: 28px; height: 28px; border: none; border-radius: 6px;
+  background: transparent; color: ${textMed};
+  font-size: 16px; font-weight: 600; cursor: pointer;
+  transition: background 0.15s, color 0.15s;
+}
+.ctrl-btn:hover { background: ${surfaceHigh}; color: ${textHigh}; }
+#zoom-label {
+  font-size: 11px; font-family: 'SF Mono', 'Fira Code', monospace;
+  color: ${textLow}; min-width: 36px; text-align: center;
+}
+
+/* Info panel */
+#info-panel {
+  position: fixed; bottom: 16px; left: 16px;
+  max-width: 320px; min-width: 200px;
+  background: ${surfaceMain}; border: 1px solid ${borderSubtle};
+  border-radius: 8px; padding: 12px 16px;
+  font-size: 13px; line-height: 1.5;
+  box-shadow: 0 2px 8px rgba(0,0,0,0.2);
+  z-index: 10; display: none;
+}
+#info-panel.visible { display: block; }
+#info-panel h3 {
+  font-size: 14px; font-weight: 700; margin-bottom: 6px;
+  white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
+}
+#info-panel .info-section { margin-bottom: 6px; }
+#info-panel .info-label { font-size: 11px; font-weight: 600; color: ${textLow}; text-transform: uppercase; letter-spacing: 0.5px; }
+#info-panel .info-value { color: ${textMed}; }
+#info-panel .port-list { list-style: none; padding: 0; }
+#info-panel .port-list li { padding: 1px 0; }
+#info-panel .port-list li::before { content: '\\2022'; margin-right: 6px; color: ${textLow}; }
+
+/* Scroll hint */
+#scroll-hint {
+  position: fixed; top: 50%; left: 50%;
+  transform: translate(-50%, -50%);
+  background: rgba(0,0,0,0.75); color: #fff;
+  padding: 6px 14px; border-radius: 8px;
+  font-size: 13px; pointer-events: none;
+  z-index: 20; opacity: 0; transition: opacity 0.3s;
+}
+#scroll-hint.visible { opacity: 1; }
+#scroll-hint kbd {
+  display: inline-block; padding: 1px 5px;
+  border: 1px solid rgba(255,255,255,0.3);
+  border-radius: 3px; font-family: 'SF Mono', 'Fira Code', monospace;
+  font-size: 12px; background: rgba(255,255,255,0.1);
+}
+</style>
+</head>
+<body>
+<div id="viewport">
+  <div id="content">${svg}</div>
+</div>
+<div id="controls">
+  <button class="ctrl-btn" id="btn-in" title="Zoom in" aria-label="Zoom in">+</button>
+  <span id="zoom-label">100%</span>
+  <button class="ctrl-btn" id="btn-out" title="Zoom out" aria-label="Zoom out">&minus;</button>
+  <button class="ctrl-btn" id="btn-fit" title="Fit to view" aria-label="Fit to view">
+    <svg width="14" height="14" viewBox="0 0 14 14" fill="none" stroke="currentColor" stroke-width="1.5">
+      <rect x="1" y="1" width="12" height="12" rx="2"/>
+      <path d="M1 5h12M1 9h12M5 1v12M9 1v12" opacity="0.4"/>
+    </svg>
+  </button>
+</div>
+<div id="info-panel">
+  <h3 id="info-title"></h3>
+  <div id="info-body"></div>
+</div>
+<div id="scroll-hint">Use <kbd id="mod-key">Ctrl</kbd> + scroll to zoom</div>
+<script>
+(function() {
+  'use strict';
+
+  var MIN_ZOOM = 0.25, MAX_ZOOM = 3, GRID_SIZE = 20;
+  var viewport = document.getElementById('viewport');
+  var content = document.getElementById('content');
+  var zoomLabel = document.getElementById('zoom-label');
+  var infoPanel = document.getElementById('info-panel');
+  var infoTitle = document.getElementById('info-title');
+  var infoBody = document.getElementById('info-body');
+  var scrollHint = document.getElementById('scroll-hint');
+
+  var scale = 1, tx = 0, ty = 0;
+  var dragging = false, dragLast = { x: 0, y: 0 };
+  var selectedNodeId = null;
+  var hintTimer = null;
+
+  // Detect Mac for modifier key
+  var isMac = /Mac/.test(navigator.userAgent);
+  document.getElementById('mod-key').textContent = isMac ? '\\u2318' : 'Ctrl';
+
+  function clamp(v, min, max) { return Math.min(max, Math.max(min, v)); }
+
+  function applyTransform() {
+    content.style.transform = 'translate(' + tx + 'px,' + ty + 'px) scale(' + scale + ')';
+    viewport.style.backgroundSize = (GRID_SIZE * scale) + 'px ' + (GRID_SIZE * scale) + 'px';
+    viewport.style.backgroundPosition = tx + 'px ' + ty + 'px';
+    zoomLabel.textContent = Math.round(scale * 100) + '%';
+  }
+
+  function fitToView() {
+    var svgEl = content.querySelector('svg');
+    if (!svgEl) { scale = 1; tx = 0; ty = 0; applyTransform(); return; }
+    var ww = viewport.clientWidth, wh = viewport.clientHeight;
+    var sw = svgEl.width.baseVal.value || svgEl.getBoundingClientRect().width;
+    var sh = svgEl.height.baseVal.value || svgEl.getBoundingClientRect().height;
+    var padding = 60;
+    var fitScale = Math.min((ww - padding) / sw, (wh - padding) / sh, 1);
+    scale = fitScale;
+    tx = (ww - sw * fitScale) / 2;
+    ty = (wh - sh * fitScale) / 2;
+    applyTransform();
+  }
+
+  // ---- Zoom (Ctrl/Cmd + scroll) ----
+  viewport.addEventListener('wheel', function(e) {
+    if (!e.ctrlKey && !e.metaKey) {
+      scrollHint.classList.add('visible');
+      clearTimeout(hintTimer);
+      hintTimer = setTimeout(function() { scrollHint.classList.remove('visible'); }, 1500);
+      return;
+    }
+    e.preventDefault();
+    var rect = viewport.getBoundingClientRect();
+    var cx = e.clientX - rect.left, cy = e.clientY - rect.top;
+    var oldScale = scale;
+    var delta = clamp(e.deltaY, -10, 10);
+    var newScale = clamp(oldScale - delta * 0.005, MIN_ZOOM, MAX_ZOOM);
+    var contentX = (cx - tx) / oldScale, contentY = (cy - ty) / oldScale;
+    tx = cx - contentX * newScale;
+    ty = cy - contentY * newScale;
+    scale = newScale;
+    applyTransform();
+  }, { passive: false });
+
+  // ---- Pan (drag) ----
+  viewport.addEventListener('pointerdown', function(e) {
+    if (e.button !== 0) return;
+    dragging = true;
+    dragLast = { x: e.clientX, y: e.clientY };
+    viewport.setPointerCapture(e.pointerId);
+    viewport.classList.add('dragging');
+  });
+  viewport.addEventListener('pointermove', function(e) {
+    if (!dragging) return;
+    tx += e.clientX - dragLast.x;
+    ty += e.clientY - dragLast.y;
+    dragLast = { x: e.clientX, y: e.clientY };
+    applyTransform();
+  });
+  function endDrag() { dragging = false; viewport.classList.remove('dragging'); }
+  viewport.addEventListener('pointerup', endDrag);
+  viewport.addEventListener('pointercancel', endDrag);
+
+  // ---- Zoom buttons ----
+  function zoomBy(dir) {
+    var rect = viewport.getBoundingClientRect();
+    var cx = rect.width / 2, cy = rect.height / 2;
+    var oldScale = scale;
+    var newScale = clamp(oldScale + dir * 0.15 * oldScale, MIN_ZOOM, MAX_ZOOM);
+    var contentX = (cx - tx) / oldScale, contentY = (cy - ty) / oldScale;
+    tx = cx - contentX * newScale;
+    ty = cy - contentY * newScale;
+    scale = newScale;
+    applyTransform();
+  }
+  document.getElementById('btn-in').addEventListener('click', function() { zoomBy(1); });
+  document.getElementById('btn-out').addEventListener('click', function() { zoomBy(-1); });
+  document.getElementById('btn-fit').addEventListener('click', fitToView);
+
+  // ---- Keyboard shortcuts ----
+  document.addEventListener('keydown', function(e) {
+    if (e.target.tagName === 'INPUT' || e.target.tagName === 'TEXTAREA') return;
+    if (e.key === '+' || e.key === '=') zoomBy(1);
+    else if (e.key === '-') zoomBy(-1);
+    else if (e.key === '0') fitToView();
+    else if (e.key === 'Escape') deselectNode();
+  });
+
+  // ---- Port label visibility via JS (since CSS sibling selectors can't reach .labels group) ----
+  var labelEls = content.querySelectorAll('.labels g[data-port-label]');
+  var nodeEls = content.querySelectorAll('.nodes > g[data-node-id]');
+
+  nodeEls.forEach(function(nodeG) {
+    var nodeId = nodeG.getAttribute('data-node-id');
+    nodeG.addEventListener('mouseenter', function() {
+      labelEls.forEach(function(lbl) {
+        var portId = lbl.getAttribute('data-port-label') || '';
+        if (portId.indexOf(nodeId + '.') === 0) {
+          lbl.style.opacity = '1';
+          lbl.style.pointerEvents = 'auto';
+        }
+      });
+    });
+    nodeG.addEventListener('mouseleave', function() {
+      labelEls.forEach(function(lbl) {
+        var portId = lbl.getAttribute('data-port-label') || '';
+        if (portId.indexOf(nodeId + '.') === 0) {
+          lbl.style.opacity = '0';
+          lbl.style.pointerEvents = 'none';
+        }
+      });
+    });
+  });
+
+  // ---- Click to inspect node ----
+  function deselectNode() {
+    selectedNodeId = null;
+    document.body.classList.remove('node-active');
+    infoPanel.classList.remove('visible');
+    content.querySelectorAll('.connections path.dimmed').forEach(function(p) {
+      p.classList.remove('dimmed');
+    });
+  }
+
+  function selectNode(nodeId) {
+    if (selectedNodeId === nodeId) { deselectNode(); return; }
+    selectedNodeId = nodeId;
+    document.body.classList.add('node-active');
+
+    // Gather info
+    var nodeG = content.querySelector('[data-node-id="' + CSS.escape(nodeId) + '"]');
+    var labelG = content.querySelector('[data-label-for="' + CSS.escape(nodeId) + '"]');
+    var labelText = labelG ? (labelG.querySelector('.node-label') || {}).textContent || nodeId : nodeId;
+
+    // Ports
+    var ports = content.querySelectorAll('[data-port-id^="' + CSS.escape(nodeId) + '."]');
+    var inputs = [], outputs = [];
+    ports.forEach(function(p) {
+      var id = p.getAttribute('data-port-id');
+      var dir = p.getAttribute('data-direction');
+      var name = id.split('.').slice(1).join('.');
+      if (dir === 'input') inputs.push(name);
+      else outputs.push(name);
+    });
+
+    // Connected paths
+    var allPaths = content.querySelectorAll('.connections path');
+    var connectedPaths = [];
+    var connectedNodes = new Set();
+    allPaths.forEach(function(p) {
+      var src = p.getAttribute('data-source') || '';
+      var tgt = p.getAttribute('data-target') || '';
+      var srcNode = src.split('.')[0];
+      var tgtNode = tgt.split('.')[0];
+      if (srcNode === nodeId || tgtNode === nodeId) {
+        connectedPaths.push(p);
+        if (srcNode !== nodeId) connectedNodes.add(srcNode);
+        if (tgtNode !== nodeId) connectedNodes.add(tgtNode);
+        p.classList.remove('dimmed');
+      } else {
+        p.classList.add('dimmed');
+      }
+    });
+
+    // Build info panel
+    infoTitle.textContent = labelText;
+    var html = '';
+    if (inputs.length) {
+      html += '<div class="info-section"><div class="info-label">Inputs</div><ul class="port-list">';
+      inputs.forEach(function(n) { html += '<li>' + escapeH(n) + '</li>'; });
+      html += '</ul></div>';
+    }
+    if (outputs.length) {
+      html += '<div class="info-section"><div class="info-label">Outputs</div><ul class="port-list">';
+      outputs.forEach(function(n) { html += '<li>' + escapeH(n) + '</li>'; });
+      html += '</ul></div>';
+    }
+    if (connectedNodes.size) {
+      html += '<div class="info-section"><div class="info-label">Connected to</div><div class="info-value">';
+      html += Array.from(connectedNodes).map(escapeH).join(', ');
+      html += '</div></div>';
+    }
+    infoBody.innerHTML = html;
+    infoPanel.classList.add('visible');
+  }
+
+  function escapeH(s) {
+    return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
+  }
+
+  // Delegate click on node groups
+  viewport.addEventListener('click', function(e) {
+    if (dragging) return;
+    var target = e.target;
+    // Walk up to find a [data-node-id] ancestor within #content
+    while (target && target !== viewport) {
+      if (target.hasAttribute && target.hasAttribute('data-node-id')) {
+        e.stopPropagation();
+        selectNode(target.getAttribute('data-node-id'));
+        return;
+      }
+      target = target.parentElement;
+    }
+    // Clicked on background
+    deselectNode();
+  });
+
+  // ---- Init ----
+  requestAnimationFrame(fitToView);
+  window.addEventListener('resize', fitToView);
+})();
+</script>
+</body>
+</html>`;
+}
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=html-viewer.js.map

package/dist/diagram/index.d.ts

@@ -13,4 +13,16 @@ export declare function sourceToSVG(code: string, options?: DiagramOptions): str
  * Parse a workflow file (resolves imports) and render the first (or named) workflow to SVG.
  */
 export declare function fileToSVG(filePath: string, options?: DiagramOptions): string;
+/**
+ * Render a workflow AST to a self-contained interactive HTML page.
+ */
+export declare function workflowToHTML(ast: TWorkflowAST, options?: DiagramOptions): string;
+/**
+ * Parse TypeScript source code and render the first (or named) workflow to interactive HTML.
+ */
+export declare function sourceToHTML(code: string, options?: DiagramOptions): string;
+/**
+ * Parse a workflow file and render the first (or named) workflow to interactive HTML.
+ */
+export declare function fileToHTML(filePath: string, options?: DiagramOptions): string;
 //# sourceMappingURL=index.d.ts.map

package/dist/diagram/index.js

@@ -1,6 +1,7 @@
 import { parser } from '../parser.js';
 import { buildDiagramGraph } from './geometry.js';
 import { renderSVG } from './renderer.js';
+import { wrapSVGInHTML } from './html-viewer.js';
 /**
  * Render a workflow AST to an SVG string.
  */
@@ -22,6 +23,27 @@ export function fileToSVG(filePath, options = {}) {
     const result = parser.parse(filePath);
     return pickAndRender(result.workflows, options);
 }
+/**
+ * Render a workflow AST to a self-contained interactive HTML page.
+ */
+export function workflowToHTML(ast, options = {}) {
+    const svg = workflowToSVG(ast, options);
+    return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme });
+}
+/**
+ * Parse TypeScript source code and render the first (or named) workflow to interactive HTML.
+ */
+export function sourceToHTML(code, options = {}) {
+    const svg = sourceToSVG(code, options);
+    return wrapSVGInHTML(svg, { title: options.workflowName, theme: options.theme });
+}
+/**
+ * Parse a workflow file and render the first (or named) workflow to interactive HTML.
+ */
+export function fileToHTML(filePath, options = {}) {
+    const svg = fileToSVG(filePath, options);
+    return wrapSVGInHTML(svg, { title: options.workflowName, theme: options.theme });
+}
 function pickAndRender(workflows, options) {
     if (workflows.length === 0) {
         throw new Error('No workflows found in source code');

package/dist/diagram/types.d.ts

@@ -5,6 +5,7 @@ export interface DiagramOptions {
     padding?: number;
     showPortLabels?: boolean;
     workflowName?: string;
+    format?: 'svg' | 'html';
 }
 export interface DiagramPort {
     name: string;