@synergenius/flow-weaver 0.10.3 → 0.10.4

package/dist/cli/flow-weaver.mjs

@@ -53974,7 +53974,7 @@ function buildCoerceSuggestion(quoted, targetType) {
   if (portRefs.length < 2) return null;
   const coerceType = COERCE_TARGET_TYPES[targetType.toUpperCase()] || targetType.toLowerCase();
   if (!["string", "number", "boolean", "json", "object"].includes(coerceType)) return null;
-  return `@coerce c1 ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
+  return `@connect ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
 }
 function extractCyclePath(message) {
   const match2 = message.match(/:\s*(.+ -> .+)/);
@@ -54083,7 +54083,7 @@ var errorMappers = {
     return {
       title: "Type Mismatch",
       explanation: `Type mismatch: you're connecting a ${source} to a ${target}. The value will be automatically converted, but this might cause unexpected behavior.`,
-      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or use @strictTypes to turn this into an error.` : `Add a @coerce annotation between the two ports, change one of the port types, or use @strictTypes to turn this into an error.`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or use @strictTypes to turn this into an error.` : `Add \`as <type>\` to the @connect annotation (e.g. \`as string\`), change one of the port types, or use @strictTypes to turn this into an error.`,
       code: error2.code
     };
   },
@@ -54182,7 +54182,7 @@ var errorMappers = {
     return {
       title: "Type Incompatible",
       explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
-      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or remove @strictTypes to allow implicit coercions.` : `Add a @coerce annotation between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or remove @strictTypes to allow implicit coercions.` : `Add \`as <type>\` to the @connect annotation (e.g. \`as number\`), change one of the port types, or remove @strictTypes to allow implicit coercions.`,
       code: error2.code
     };
   },
@@ -54195,7 +54195,7 @@ var errorMappers = {
     return {
       title: "Unusual Type Coercion",
       explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
-      fix: coerceSuggestion ? `If intentional, add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.` : `If intentional, add an explicit @coerce annotation, or use @strictTypes to enforce type safety.`,
+      fix: coerceSuggestion ? `If intentional, use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.` : `If intentional, add \`as <type>\` to the @connect annotation, or use @strictTypes to enforce type safety.`,
       code: error2.code
     };
   },
@@ -54464,7 +54464,7 @@ var errorMappers = {
     return {
       title: "Lossy Type Conversion",
       explanation: `Converting ${source} to ${target} may lose data or produce unexpected results (e.g., NaN, truncation).`,
-      fix: coerceSuggestion ? `Add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.` : `Add an explicit conversion with @coerce, or use @strictTypes to enforce type safety.`,
+      fix: coerceSuggestion ? `Use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.` : `Add \`as <type>\` to the @connect annotation for explicit conversion, or use @strictTypes to enforce type safety.`,
       code: error2.code
     };
   },
@@ -61588,24 +61588,46 @@ path[data-source].port-hover { opacity: 1; }
 /* Info panel */
 #info-panel {
   position: fixed; bottom: 52px; left: 16px;
-  max-width: 320px; min-width: 200px;
+  max-width: 480px; min-width: 260px;
   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;
+  max-height: calc(100vh - 120px); overflow-y: auto;
 }
 #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 .node-desc { color: ${textMed}; font-size: 12px; margin-bottom: 8px; font-style: italic; }
 #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}; }
+#info-panel .port-type { color: ${textLow}; font-size: 11px; margin-left: 4px; font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace; }
+#info-panel pre {
+  background: ${isDark ? "#161625" : "#f0f1fa"}; border: 1px solid ${borderSubtle};
+  border-radius: 6px; padding: 10px; overflow-x: auto;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 12px; line-height: 1.6; white-space: pre;
+  max-height: 300px; overflow-y: auto; margin: 6px 0 0;
+  color: ${isDark ? "#e6edf3" : "#1a2340"};
+}
+.hl-kw { color: ${isDark ? "#8e9eff" : "#4040bf"}; }
+.hl-str { color: ${isDark ? "#ff7b72" : "#c4432b"}; }
+.hl-num { color: ${isDark ? "#f0a050" : "#b35e14"}; }
+.hl-cm { color: #6a737d; font-style: italic; }
+.hl-fn { color: ${isDark ? "#d2a8ff" : "#7c3aed"}; }
+.hl-ty { color: ${isDark ? "#d2a8ff" : "#7c3aed"}; }
+.hl-pn { color: ${isDark ? "#b8bdd0" : "#4a5578"}; }
+.hl-ann { color: ${isDark ? "#8e9eff" : "#4040bf"}; font-weight: 600; font-style: normal; }
+.hl-arr { color: ${isDark ? "#79c0ff" : "#0969da"}; font-weight: 600; font-style: normal; }
+.hl-id { color: ${isDark ? "#e6edf3" : "#1a2340"}; font-style: normal; }
+.hl-sc { color: ${isDark ? "#d2a8ff" : "#7c3aed"}; font-style: italic; }
 
 /* Branding badge */
 #branding {
@@ -61660,8 +61682,8 @@ path[data-source].port-hover { opacity: 1; }
       <circle cx="10" cy="10" r="1.5" fill="${dotColor}" opacity="0.6"/>
     </pattern>
   </defs>
-  <rect x="-100000" y="-100000" width="200000" height="200000" fill="${bg}"/>
-  <rect x="-100000" y="-100000" width="200000" height="200000" fill="url(#viewer-dots)"/>
+  <rect x="-100000" y="-100000" width="200000" height="200000" fill="${bg}" pointer-events="none"/>
+  <rect x="-100000" y="-100000" width="200000" height="200000" fill="url(#viewer-dots)" pointer-events="none"/>
   <g id="diagram">${inner}</g>
 </svg>
 <div id="controls">
@@ -61691,6 +61713,7 @@ path[data-source].port-hover { opacity: 1; }
 </a>
 <div id="scroll-hint">Use <kbd id="mod-key">Ctrl</kbd> + scroll to zoom</div>
 <div id="studio-hint">Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.</div>
+<script>var nodeSources = ${JSON.stringify(options.nodeSources ?? {})};</script>
 <script>
 (function() {
   'use strict';
@@ -61775,6 +61798,7 @@ path[data-source].port-hover { opacity: 1; }
 
   // ---- Pan (drag) + Node drag ----
   var draggedNodeId = null, dragNodeStart = null, didDragNode = false;
+  var clickTarget = null; // stash the real target before setPointerCapture steals it
   var dragCount = 0, nudgeIndex = 0, nudgeTimer = null;
   var nudgeMessages = [
     'Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.',
@@ -61789,6 +61813,8 @@ path[data-source].port-hover { opacity: 1; }
 
   canvas.addEventListener('pointerdown', function(e) {
     if (e.button !== 0) return;
+    clickTarget = e.target; // stash before setPointerCapture redirects events
+    didDrag = false;
     // Check if clicking on a node body (walk up to detect data-node-id)
     var t = e.target;
     while (t && t !== canvas) {
@@ -61805,7 +61831,6 @@ path[data-source].port-hover { opacity: 1; }
     }
     // Canvas pan
     pointerDown = true;
-    didDrag = false;
     dragLast = { x: e.clientX, y: e.clientY };
     canvas.setPointerCapture(e.pointerId);
   });
@@ -62258,14 +62283,28 @@ path[data-source].port-hover { opacity: 1; }
     // Build info panel
     infoTitle.textContent = labelText;
     var html = '';
+    var src = nodeSources[nodeId];
+    if (src && src.description) {
+      html += '<div class="node-desc">' + escapeH(src.description) + '</div>';
+    }
+    var portInfo = (src && src.ports) ? src.ports : {};
+    function portLabel(name) {
+      var p = portInfo[name];
+      var label = escapeH(name);
+      if (p) {
+        var typeStr = p.tsType || p.type;
+        if (typeStr) label += ' <span class="port-type">' + escapeH(typeStr) + '</span>';
+      }
+      return label;
+    }
     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>'; });
+      inputs.forEach(function(n) { html += '<li>' + portLabel(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>'; });
+      outputs.forEach(function(n) { html += '<li>' + portLabel(n) + '</li>'; });
       html += '</ul></div>';
     }
     if (connectedNodes.size) {
@@ -62273,6 +62312,10 @@ path[data-source].port-hover { opacity: 1; }
       html += Array.from(connectedNodes).map(escapeH).join(', ');
       html += '</div></div>';
     }
+    if (src && src.source) {
+      html += '<div class="info-section"><div class="info-label">Source</div>';
+      html += '<pre><code>' + highlightTS(src.source) + '</code></pre></div>';
+    }
     infoBody.innerHTML = html;
     infoPanel.classList.add('visible');
   }
@@ -62281,10 +62324,130 @@ path[data-source].port-hover { opacity: 1; }
     return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
   }
 
+  var fwAnnotations = 'flowWeaver,input,output,step,node,connect,param,returns,fwImport,label,scope,position,color,icon,tag,map,path,name,description,expression,executeWhen,pullExecution,strictTypes,autoConnect,port,trigger,cancelOn,retries,timeout,throttle';
+
+  function highlightJSDoc(block) {
+    var annSet = fwAnnotations.split(',');
+    var out = '';
+    var re = /(@[a-zA-Z]+)|(-&gt;)|(\\.[a-zA-Z_][a-zA-Z0-9_]*)|("[^"]*")|('\\''[^'\\'']*'\\'')|(-?[0-9]+(?:\\.[0-9]+)?)|([a-zA-Z_][a-zA-Z0-9_]*)|([^@a-zA-Z0-9"'\\-.]+)/g;
+    var m;
+    while ((m = re.exec(block)) !== null) {
+      if (m[1]) {
+        var tag = m[1].slice(1);
+        if (annSet.indexOf(tag) >= 0) {
+          out += '<span class="hl-ann">' + m[0] + '</span>';
+        } else {
+          out += '<span class="hl-ann">' + m[0] + '</span>';
+        }
+      } else if (m[2]) {
+        out += '<span class="hl-arr">' + m[2] + '</span>';
+      } else if (m[3]) {
+        // .portName scope reference
+        out += '<span class="hl-sc">' + m[3] + '</span>';
+      } else if (m[4] || m[5]) {
+        out += '<span class="hl-str">' + (m[4] || m[5]) + '</span>';
+      } else if (m[6]) {
+        out += '<span class="hl-num">' + m[6] + '</span>';
+      } else if (m[7]) {
+        var tys = 'string,number,boolean,any,void,never,unknown,STEP,STRING,NUMBER,BOOLEAN,ARRAY,OBJECT,FUNCTION,ANY';
+        if (tys.split(',').indexOf(m[7]) >= 0) {
+          out += '<span class="hl-ty">' + m[7] + '</span>';
+        } else {
+          out += '<span class="hl-id">' + m[7] + '</span>';
+        }
+      } else {
+        out += m[0];
+      }
+    }
+    return out;
+  }
+
+  function highlightTS(code) {
+    var tokens = [];
+    var i = 0;
+    while (i < code.length) {
+      // Line comments
+      if (code[i] === '/' && code[i+1] === '/') {
+        var end = code.indexOf('\\n', i);
+        if (end === -1) end = code.length;
+        tokens.push({ t: 'cm', v: code.slice(i, end) });
+        i = end;
+        continue;
+      }
+      // Block comments (detect JSDoc for annotation highlighting)
+      if (code[i] === '/' && code[i+1] === '*') {
+        var end = code.indexOf('*/', i + 2);
+        if (end === -1) end = code.length; else end += 2;
+        var block = code.slice(i, end);
+        var hasFW = /@(flowWeaver|input|output|step|node|connect|param|returns)/.test(block);
+        if (hasFW) {
+          tokens.push({ t: 'jsdoc', v: block });
+        } else {
+          tokens.push({ t: 'cm', v: block });
+        }
+        i = end;
+        continue;
+      }
+      // Strings
+      if (code[i] === "'" || code[i] === '"' || code[i] === '\`') {
+        var q = code[i], j = i + 1;
+        while (j < code.length && code[j] !== q) { if (code[j] === '\\\\') j++; j++; }
+        tokens.push({ t: 'str', v: code.slice(i, j + 1) });
+        i = j + 1;
+        continue;
+      }
+      // Numbers
+      if (/[0-9]/.test(code[i]) && (i === 0 || /[^a-zA-Z_$]/.test(code[i-1]))) {
+        var j = i;
+        while (j < code.length && /[0-9a-fA-FxX._]/.test(code[j])) j++;
+        tokens.push({ t: 'num', v: code.slice(i, j) });
+        i = j;
+        continue;
+      }
+      // Words
+      if (/[a-zA-Z_$]/.test(code[i])) {
+        var j = i;
+        while (j < code.length && /[a-zA-Z0-9_$]/.test(code[j])) j++;
+        var w = code.slice(i, j);
+        var kws = 'async,await,break,case,catch,class,const,continue,default,delete,do,else,export,extends,finally,for,from,function,if,import,in,instanceof,let,new,of,return,switch,throw,try,typeof,var,void,while,yield';
+        var tys = 'string,number,boolean,any,void,never,unknown,null,undefined,true,false,Promise,Record,Map,Set,Array,Partial,Required,Omit,Pick';
+        if (kws.split(',').indexOf(w) >= 0) {
+          tokens.push({ t: 'kw', v: w });
+        } else if (tys.split(',').indexOf(w) >= 0) {
+          tokens.push({ t: 'ty', v: w });
+        } else if (j < code.length && code[j] === '(') {
+          tokens.push({ t: 'fn', v: w });
+        } else {
+          tokens.push({ t: '', v: w });
+        }
+        i = j;
+        continue;
+      }
+      // Punctuation
+      if (/[{}()\\[\\];:.,<>=!&|?+\\-*/%^~@]/.test(code[i])) {
+        tokens.push({ t: 'pn', v: code[i] });
+        i++;
+        continue;
+      }
+      // Whitespace and other
+      tokens.push({ t: '', v: code[i] });
+      i++;
+    }
+    return tokens.map(function(tk) {
+      if (tk.t === 'jsdoc') {
+        return '<span class="hl-cm">' + highlightJSDoc(escapeH(tk.v)) + '</span>';
+      }
+      var v = escapeH(tk.v);
+      return tk.t ? '<span class="hl-' + tk.t + '">' + v + '</span>' : v;
+    }).join('');
+  }
+
   // Delegate click: port click > node click > background
+  // Use clickTarget (stashed from pointerdown) because setPointerCapture redirects click to canvas
   canvas.addEventListener('click', function(e) {
     if (didDrag || didDragNode) { didDragNode = false; return; }
-    var target = e.target;
+    var target = clickTarget || e.target;
+    clickTarget = null;
     while (target && target !== canvas) {
       if (target.hasAttribute && target.hasAttribute('data-port-id')) {
         e.stopPropagation();
@@ -62325,24 +62488,57 @@ function fileToSVG(filePath, options = {}) {
   return pickAndRender(result.workflows, options);
 }
 function fileToHTML(filePath, options = {}) {
-  const svg = fileToSVG(filePath, options);
-  return wrapSVGInHTML(svg, { title: options.workflowName, theme: options.theme });
+  const result = parser.parse(filePath);
+  const ast = pickWorkflow(result.workflows, options);
+  const svg = workflowToSVG(ast, options);
+  return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme, nodeSources: buildNodeSourceMap(ast) });
 }
-function pickAndRender(workflows, options) {
+function buildNodeSourceMap(ast) {
+  const typeMap = new Map(ast.nodeTypes.map((nt) => [nt.functionName, nt]));
+  const map3 = {};
+  for (const inst of ast.instances) {
+    const nt = typeMap.get(inst.nodeType);
+    if (!nt) continue;
+    const ports = {};
+    for (const [name, def] of Object.entries(nt.inputs ?? {})) {
+      ports[name] = { type: def.dataType, tsType: def.tsType };
+    }
+    for (const [name, def] of Object.entries(nt.outputs ?? {})) {
+      ports[name] = { type: def.dataType, tsType: def.tsType };
+    }
+    map3[inst.id] = { description: nt.description, source: nt.functionText, ports };
+  }
+  const startPorts = {};
+  for (const [name, def] of Object.entries(ast.startPorts ?? {})) {
+    startPorts[name] = { type: def.dataType, tsType: def.tsType };
+  }
+  if (Object.keys(startPorts).length) {
+    map3["Start"] = { description: ast.description, ports: startPorts };
+  }
+  const exitPorts = {};
+  for (const [name, def] of Object.entries(ast.exitPorts ?? {})) {
+    exitPorts[name] = { type: def.dataType, tsType: def.tsType };
+  }
+  if (Object.keys(exitPorts).length) {
+    map3["Exit"] = { ports: exitPorts };
+  }
+  return map3;
+}
+function pickWorkflow(workflows, options) {
   if (workflows.length === 0) {
     throw new Error("No workflows found in source code");
   }
-  let workflow;
   if (options.workflowName) {
     const found = workflows.find((w) => w.name === options.workflowName);
     if (!found) {
       throw new Error(`Workflow "${options.workflowName}" not found. Available: ${workflows.map((w) => w.name).join(", ")}`);
     }
-    workflow = found;
-  } else {
-    workflow = workflows[0];
+    return found;
   }
-  return workflowToSVG(workflow, options);
+  return workflows[0];
+}
+function pickAndRender(workflows, options) {
+  return workflowToSVG(pickWorkflow(workflows, options), options);
 }
 
 // src/cli/commands/diagram.ts
@@ -96900,7 +97096,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.3" : "0.0.0-dev";
+var version2 = true ? "0.10.4" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").version(version2, "-v, --version", "Output the current version");
 program2.configureOutput({

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

@@ -8,6 +8,14 @@
 export interface HtmlViewerOptions {
     title?: string;
     theme?: 'dark' | 'light';
+    nodeSources?: Record<string, {
+        description?: string;
+        source?: string;
+        ports?: Record<string, {
+            type: string;
+            tsType?: string;
+        }>;
+    }>;
 }
 export declare function wrapSVGInHTML(svgContent: string, options?: HtmlViewerOptions): string;
 //# sourceMappingURL=html-viewer.d.ts.map

package/dist/diagram/html-viewer.js

@@ -122,24 +122,46 @@ path[data-source].port-hover { opacity: 1; }
 /* Info panel */
 #info-panel {
   position: fixed; bottom: 52px; left: 16px;
-  max-width: 320px; min-width: 200px;
+  max-width: 480px; min-width: 260px;
   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;
+  max-height: calc(100vh - 120px); overflow-y: auto;
 }
 #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 .node-desc { color: ${textMed}; font-size: 12px; margin-bottom: 8px; font-style: italic; }
 #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}; }
+#info-panel .port-type { color: ${textLow}; font-size: 11px; margin-left: 4px; font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace; }
+#info-panel pre {
+  background: ${isDark ? '#161625' : '#f0f1fa'}; border: 1px solid ${borderSubtle};
+  border-radius: 6px; padding: 10px; overflow-x: auto;
+  font-family: 'SF Mono', 'Fira Code', 'Consolas', monospace;
+  font-size: 12px; line-height: 1.6; white-space: pre;
+  max-height: 300px; overflow-y: auto; margin: 6px 0 0;
+  color: ${isDark ? '#e6edf3' : '#1a2340'};
+}
+.hl-kw { color: ${isDark ? '#8e9eff' : '#4040bf'}; }
+.hl-str { color: ${isDark ? '#ff7b72' : '#c4432b'}; }
+.hl-num { color: ${isDark ? '#f0a050' : '#b35e14'}; }
+.hl-cm { color: #6a737d; font-style: italic; }
+.hl-fn { color: ${isDark ? '#d2a8ff' : '#7c3aed'}; }
+.hl-ty { color: ${isDark ? '#d2a8ff' : '#7c3aed'}; }
+.hl-pn { color: ${isDark ? '#b8bdd0' : '#4a5578'}; }
+.hl-ann { color: ${isDark ? '#8e9eff' : '#4040bf'}; font-weight: 600; font-style: normal; }
+.hl-arr { color: ${isDark ? '#79c0ff' : '#0969da'}; font-weight: 600; font-style: normal; }
+.hl-id { color: ${isDark ? '#e6edf3' : '#1a2340'}; font-style: normal; }
+.hl-sc { color: ${isDark ? '#d2a8ff' : '#7c3aed'}; font-style: italic; }
 
 /* Branding badge */
 #branding {
@@ -194,8 +216,8 @@ path[data-source].port-hover { opacity: 1; }
       <circle cx="10" cy="10" r="1.5" fill="${dotColor}" opacity="0.6"/>
     </pattern>
   </defs>
-  <rect x="-100000" y="-100000" width="200000" height="200000" fill="${bg}"/>
-  <rect x="-100000" y="-100000" width="200000" height="200000" fill="url(#viewer-dots)"/>
+  <rect x="-100000" y="-100000" width="200000" height="200000" fill="${bg}" pointer-events="none"/>
+  <rect x="-100000" y="-100000" width="200000" height="200000" fill="url(#viewer-dots)" pointer-events="none"/>
   <g id="diagram">${inner}</g>
 </svg>
 <div id="controls">
@@ -225,6 +247,7 @@ path[data-source].port-hover { opacity: 1; }
 </a>
 <div id="scroll-hint">Use <kbd id="mod-key">Ctrl</kbd> + scroll to zoom</div>
 <div id="studio-hint">Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.</div>
+<script>var nodeSources = ${JSON.stringify(options.nodeSources ?? {})};</script>
 <script>
 (function() {
   'use strict';
@@ -309,6 +332,7 @@ path[data-source].port-hover { opacity: 1; }
 
   // ---- Pan (drag) + Node drag ----
   var draggedNodeId = null, dragNodeStart = null, didDragNode = false;
+  var clickTarget = null; // stash the real target before setPointerCapture steals it
   var dragCount = 0, nudgeIndex = 0, nudgeTimer = null;
   var nudgeMessages = [
     'Like rearranging? <a href="https://flowweaver.ai" target="_blank" rel="noopener">Flow Weaver Studio</a> saves your layouts.',
@@ -323,6 +347,8 @@ path[data-source].port-hover { opacity: 1; }
 
   canvas.addEventListener('pointerdown', function(e) {
     if (e.button !== 0) return;
+    clickTarget = e.target; // stash before setPointerCapture redirects events
+    didDrag = false;
     // Check if clicking on a node body (walk up to detect data-node-id)
     var t = e.target;
     while (t && t !== canvas) {
@@ -339,7 +365,6 @@ path[data-source].port-hover { opacity: 1; }
     }
     // Canvas pan
     pointerDown = true;
-    didDrag = false;
     dragLast = { x: e.clientX, y: e.clientY };
     canvas.setPointerCapture(e.pointerId);
   });
@@ -792,14 +817,28 @@ path[data-source].port-hover { opacity: 1; }
     // Build info panel
     infoTitle.textContent = labelText;
     var html = '';
+    var src = nodeSources[nodeId];
+    if (src && src.description) {
+      html += '<div class="node-desc">' + escapeH(src.description) + '</div>';
+    }
+    var portInfo = (src && src.ports) ? src.ports : {};
+    function portLabel(name) {
+      var p = portInfo[name];
+      var label = escapeH(name);
+      if (p) {
+        var typeStr = p.tsType || p.type;
+        if (typeStr) label += ' <span class="port-type">' + escapeH(typeStr) + '</span>';
+      }
+      return label;
+    }
     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>'; });
+      inputs.forEach(function(n) { html += '<li>' + portLabel(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>'; });
+      outputs.forEach(function(n) { html += '<li>' + portLabel(n) + '</li>'; });
       html += '</ul></div>';
     }
     if (connectedNodes.size) {
@@ -807,6 +846,10 @@ path[data-source].port-hover { opacity: 1; }
       html += Array.from(connectedNodes).map(escapeH).join(', ');
       html += '</div></div>';
     }
+    if (src && src.source) {
+      html += '<div class="info-section"><div class="info-label">Source</div>';
+      html += '<pre><code>' + highlightTS(src.source) + '</code></pre></div>';
+    }
     infoBody.innerHTML = html;
     infoPanel.classList.add('visible');
   }
@@ -815,10 +858,130 @@ path[data-source].port-hover { opacity: 1; }
     return s.replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;');
   }
 
+  var fwAnnotations = 'flowWeaver,input,output,step,node,connect,param,returns,fwImport,label,scope,position,color,icon,tag,map,path,name,description,expression,executeWhen,pullExecution,strictTypes,autoConnect,port,trigger,cancelOn,retries,timeout,throttle';
+
+  function highlightJSDoc(block) {
+    var annSet = fwAnnotations.split(',');
+    var out = '';
+    var re = /(@[a-zA-Z]+)|(-&gt;)|(\\.[a-zA-Z_][a-zA-Z0-9_]*)|("[^"]*")|('\\''[^'\\'']*'\\'')|(-?[0-9]+(?:\\.[0-9]+)?)|([a-zA-Z_][a-zA-Z0-9_]*)|([^@a-zA-Z0-9"'\\-.]+)/g;
+    var m;
+    while ((m = re.exec(block)) !== null) {
+      if (m[1]) {
+        var tag = m[1].slice(1);
+        if (annSet.indexOf(tag) >= 0) {
+          out += '<span class="hl-ann">' + m[0] + '</span>';
+        } else {
+          out += '<span class="hl-ann">' + m[0] + '</span>';
+        }
+      } else if (m[2]) {
+        out += '<span class="hl-arr">' + m[2] + '</span>';
+      } else if (m[3]) {
+        // .portName scope reference
+        out += '<span class="hl-sc">' + m[3] + '</span>';
+      } else if (m[4] || m[5]) {
+        out += '<span class="hl-str">' + (m[4] || m[5]) + '</span>';
+      } else if (m[6]) {
+        out += '<span class="hl-num">' + m[6] + '</span>';
+      } else if (m[7]) {
+        var tys = 'string,number,boolean,any,void,never,unknown,STEP,STRING,NUMBER,BOOLEAN,ARRAY,OBJECT,FUNCTION,ANY';
+        if (tys.split(',').indexOf(m[7]) >= 0) {
+          out += '<span class="hl-ty">' + m[7] + '</span>';
+        } else {
+          out += '<span class="hl-id">' + m[7] + '</span>';
+        }
+      } else {
+        out += m[0];
+      }
+    }
+    return out;
+  }
+
+  function highlightTS(code) {
+    var tokens = [];
+    var i = 0;
+    while (i < code.length) {
+      // Line comments
+      if (code[i] === '/' && code[i+1] === '/') {
+        var end = code.indexOf('\\n', i);
+        if (end === -1) end = code.length;
+        tokens.push({ t: 'cm', v: code.slice(i, end) });
+        i = end;
+        continue;
+      }
+      // Block comments (detect JSDoc for annotation highlighting)
+      if (code[i] === '/' && code[i+1] === '*') {
+        var end = code.indexOf('*/', i + 2);
+        if (end === -1) end = code.length; else end += 2;
+        var block = code.slice(i, end);
+        var hasFW = /@(flowWeaver|input|output|step|node|connect|param|returns)/.test(block);
+        if (hasFW) {
+          tokens.push({ t: 'jsdoc', v: block });
+        } else {
+          tokens.push({ t: 'cm', v: block });
+        }
+        i = end;
+        continue;
+      }
+      // Strings
+      if (code[i] === "'" || code[i] === '"' || code[i] === '\`') {
+        var q = code[i], j = i + 1;
+        while (j < code.length && code[j] !== q) { if (code[j] === '\\\\') j++; j++; }
+        tokens.push({ t: 'str', v: code.slice(i, j + 1) });
+        i = j + 1;
+        continue;
+      }
+      // Numbers
+      if (/[0-9]/.test(code[i]) && (i === 0 || /[^a-zA-Z_$]/.test(code[i-1]))) {
+        var j = i;
+        while (j < code.length && /[0-9a-fA-FxX._]/.test(code[j])) j++;
+        tokens.push({ t: 'num', v: code.slice(i, j) });
+        i = j;
+        continue;
+      }
+      // Words
+      if (/[a-zA-Z_$]/.test(code[i])) {
+        var j = i;
+        while (j < code.length && /[a-zA-Z0-9_$]/.test(code[j])) j++;
+        var w = code.slice(i, j);
+        var kws = 'async,await,break,case,catch,class,const,continue,default,delete,do,else,export,extends,finally,for,from,function,if,import,in,instanceof,let,new,of,return,switch,throw,try,typeof,var,void,while,yield';
+        var tys = 'string,number,boolean,any,void,never,unknown,null,undefined,true,false,Promise,Record,Map,Set,Array,Partial,Required,Omit,Pick';
+        if (kws.split(',').indexOf(w) >= 0) {
+          tokens.push({ t: 'kw', v: w });
+        } else if (tys.split(',').indexOf(w) >= 0) {
+          tokens.push({ t: 'ty', v: w });
+        } else if (j < code.length && code[j] === '(') {
+          tokens.push({ t: 'fn', v: w });
+        } else {
+          tokens.push({ t: '', v: w });
+        }
+        i = j;
+        continue;
+      }
+      // Punctuation
+      if (/[{}()\\[\\];:.,<>=!&|?+\\-*/%^~@]/.test(code[i])) {
+        tokens.push({ t: 'pn', v: code[i] });
+        i++;
+        continue;
+      }
+      // Whitespace and other
+      tokens.push({ t: '', v: code[i] });
+      i++;
+    }
+    return tokens.map(function(tk) {
+      if (tk.t === 'jsdoc') {
+        return '<span class="hl-cm">' + highlightJSDoc(escapeH(tk.v)) + '</span>';
+      }
+      var v = escapeH(tk.v);
+      return tk.t ? '<span class="hl-' + tk.t + '">' + v + '</span>' : v;
+    }).join('');
+  }
+
   // Delegate click: port click > node click > background
+  // Use clickTarget (stashed from pointerdown) because setPointerCapture redirects click to canvas
   canvas.addEventListener('click', function(e) {
     if (didDrag || didDragNode) { didDragNode = false; return; }
-    var target = e.target;
+    var target = clickTarget || e.target;
+    clickTarget = null;
     while (target && target !== canvas) {
       if (target.hasAttribute && target.hasAttribute('data-port-id')) {
         e.stopPropagation();

package/dist/diagram/index.js

@@ -28,37 +28,73 @@ export function fileToSVG(filePath, options = {}) {
  */
 export function workflowToHTML(ast, options = {}) {
     const svg = workflowToSVG(ast, options);
-    return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme });
+    return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme, nodeSources: buildNodeSourceMap(ast) });
 }
 /**
  * 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 });
+    const result = parser.parseFromString(code);
+    const ast = pickWorkflow(result.workflows, options);
+    const svg = workflowToSVG(ast, options);
+    return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme, nodeSources: buildNodeSourceMap(ast) });
 }
 /**
  * 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 });
+    const result = parser.parse(filePath);
+    const ast = pickWorkflow(result.workflows, options);
+    const svg = workflowToSVG(ast, options);
+    return wrapSVGInHTML(svg, { title: options.workflowName ?? ast.name, theme: options.theme, nodeSources: buildNodeSourceMap(ast) });
 }
-function pickAndRender(workflows, options) {
+function buildNodeSourceMap(ast) {
+    const typeMap = new Map(ast.nodeTypes.map(nt => [nt.functionName, nt]));
+    const map = {};
+    for (const inst of ast.instances) {
+        const nt = typeMap.get(inst.nodeType);
+        if (!nt)
+            continue;
+        const ports = {};
+        for (const [name, def] of Object.entries(nt.inputs ?? {})) {
+            ports[name] = { type: def.dataType, tsType: def.tsType };
+        }
+        for (const [name, def] of Object.entries(nt.outputs ?? {})) {
+            ports[name] = { type: def.dataType, tsType: def.tsType };
+        }
+        map[inst.id] = { description: nt.description, source: nt.functionText, ports };
+    }
+    // Virtual Start/Exit nodes get their port types from the workflow definition
+    const startPorts = {};
+    for (const [name, def] of Object.entries(ast.startPorts ?? {})) {
+        startPorts[name] = { type: def.dataType, tsType: def.tsType };
+    }
+    if (Object.keys(startPorts).length) {
+        map['Start'] = { description: ast.description, ports: startPorts };
+    }
+    const exitPorts = {};
+    for (const [name, def] of Object.entries(ast.exitPorts ?? {})) {
+        exitPorts[name] = { type: def.dataType, tsType: def.tsType };
+    }
+    if (Object.keys(exitPorts).length) {
+        map['Exit'] = { ports: exitPorts };
+    }
+    return map;
+}
+function pickWorkflow(workflows, options) {
     if (workflows.length === 0) {
         throw new Error('No workflows found in source code');
     }
-    let workflow;
     if (options.workflowName) {
         const found = workflows.find(w => w.name === options.workflowName);
         if (!found) {
             throw new Error(`Workflow "${options.workflowName}" not found. Available: ${workflows.map(w => w.name).join(', ')}`);
         }
-        workflow = found;
-    }
-    else {
-        workflow = workflows[0];
+        return found;
     }
-    return workflowToSVG(workflow, options);
+    return workflows[0];
+}
+function pickAndRender(workflows, options) {
+    return workflowToSVG(pickWorkflow(workflows, options), options);
 }
 //# sourceMappingURL=index.js.map

package/dist/friendly-errors.js

@@ -35,7 +35,7 @@ const COERCE_TARGET_TYPES = {
     OBJECT: 'object',
 };
 /**
- * Build a concrete @coerce suggestion from error message context.
+ * Build a concrete `@connect ... as <type>` coercion suggestion from error context.
  * Returns null if not enough info is available.
  */
 function buildCoerceSuggestion(quoted, targetType) {
@@ -51,7 +51,7 @@ function buildCoerceSuggestion(quoted, targetType) {
     const coerceType = COERCE_TARGET_TYPES[targetType.toUpperCase()] || targetType.toLowerCase();
     if (!['string', 'number', 'boolean', 'json', 'object'].includes(coerceType))
         return null;
-    return `@coerce c1 ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
+    return `@connect ${portRefs[0]} -> ${portRefs[1]} as ${coerceType}`;
 }
 function extractCyclePath(message) {
     const match = message.match(/:\s*(.+ -> .+)/);
@@ -163,8 +163,8 @@ const errorMappers = {
             title: 'Type Mismatch',
             explanation: `Type mismatch: you're connecting a ${source} to a ${target}. The value will be automatically converted, but this might cause unexpected behavior.`,
             fix: coerceSuggestion
-                ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or use @strictTypes to turn this into an error.`
-                : `Add a @coerce annotation between the two ports, change one of the port types, or use @strictTypes to turn this into an error.`,
+                ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or use @strictTypes to turn this into an error.`
+                : `Add \`as <type>\` to the @connect annotation (e.g. \`as string\`), change one of the port types, or use @strictTypes to turn this into an error.`,
             code: error.code,
         };
     },
@@ -264,8 +264,8 @@ const errorMappers = {
             title: 'Type Incompatible',
             explanation: `Type mismatch: ${source} to ${target}. With @strictTypes enabled, this is an error instead of a warning.`,
             fix: coerceSuggestion
-                ? `Add an explicit coercion: \`${coerceSuggestion}\`, change one of the port types, or remove @strictTypes to allow implicit coercions.`
-                : `Add a @coerce annotation between the ports, change one of the port types, or remove @strictTypes to allow implicit coercions.`,
+                ? `Use \`${coerceSuggestion}\` for explicit coercion, change one of the port types, or remove @strictTypes to allow implicit coercions.`
+                : `Add \`as <type>\` to the @connect annotation (e.g. \`as number\`), change one of the port types, or remove @strictTypes to allow implicit coercions.`,
             code: error.code,
         };
     },
@@ -279,8 +279,8 @@ const errorMappers = {
             title: 'Unusual Type Coercion',
             explanation: `Converting ${source} to ${target} is technically valid but semantically unusual and may produce unexpected behavior.`,
             fix: coerceSuggestion
-                ? `If intentional, add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.`
-                : `If intentional, add an explicit @coerce annotation, or use @strictTypes to enforce type safety.`,
+                ? `If intentional, use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.`
+                : `If intentional, add \`as <type>\` to the @connect annotation, or use @strictTypes to enforce type safety.`,
             code: error.code,
         };
     },
@@ -550,8 +550,8 @@ const errorMappers = {
             title: 'Lossy Type Conversion',
             explanation: `Converting ${source} to ${target} may lose data or produce unexpected results (e.g., NaN, truncation).`,
             fix: coerceSuggestion
-                ? `Add an explicit coercion: \`${coerceSuggestion}\`, or use @strictTypes to enforce type safety.`
-                : `Add an explicit conversion with @coerce, or use @strictTypes to enforce type safety.`,
+                ? `Use \`${coerceSuggestion}\` for explicit coercion, or use @strictTypes to enforce type safety.`
+                : `Add \`as <type>\` to the @connect annotation for explicit conversion, or use @strictTypes to enforce type safety.`,
             code: error.code,
         };
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.10.3",
+  "version": "0.10.4",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",