@synergenius/flow-weaver 0.10.2 → 0.10.4

package/dist/cli/flow-weaver.mjs

@@ -12263,7 +12263,21 @@ var init_theme = __esm({
 });
 
 // src/validator.ts
-var DOCS_BASE, ERROR_DOC_URLS, WorkflowValidator, validator;
+function suggestCoerceType(targetType) {
+  switch (targetType) {
+    case "STRING":
+      return "string";
+    case "NUMBER":
+      return "number";
+    case "BOOLEAN":
+      return "boolean";
+    case "OBJECT":
+      return "object";
+    default:
+      return "<type>";
+  }
+}
+var DOCS_BASE, ERROR_DOC_URLS, COERCE_OUTPUT_TYPE, WorkflowValidator, validator;
 var init_validator = __esm({
   "src/validator.ts"() {
     "use strict";
@@ -12284,7 +12298,17 @@ var init_validator = __esm({
       MISSING_EXIT_CONNECTION: `${DOCS_BASE}/concepts#start-and-exit`,
       INFERRED_NODE_TYPE: `${DOCS_BASE}/node-conversion`,
       DUPLICATE_CONNECTION: `${DOCS_BASE}/concepts#connections`,
-      STUB_NODE: `${DOCS_BASE}/model-driven#stub-nodes`
+      STUB_NODE: `${DOCS_BASE}/model-driven#stub-nodes`,
+      COERCE_TYPE_MISMATCH: `${DOCS_BASE}/compilation#type-coercion`,
+      REDUNDANT_COERCE: `${DOCS_BASE}/compilation#type-coercion`,
+      COERCE_ON_FUNCTION_PORT: `${DOCS_BASE}/compilation#type-coercion`
+    };
+    COERCE_OUTPUT_TYPE = {
+      string: "STRING",
+      number: "NUMBER",
+      boolean: "BOOLEAN",
+      json: "STRING",
+      object: "OBJECT"
     };
     WorkflowValidator = class {
       errors = [];
@@ -12710,7 +12734,27 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           if (sourceType === "STEP" && targetType === "STEP") {
             return;
           }
+          if (conn.coerce && (sourceType === "FUNCTION" || targetType === "FUNCTION")) {
+            this.errors.push({
+              type: "error",
+              code: "COERCE_ON_FUNCTION_PORT",
+              message: `Coercion \`as ${conn.coerce}\` cannot be used on FUNCTION ports in connection "${fromNode}.${fromPort}" \u2192 "${toNode}.${toPort}". FUNCTION values cannot be meaningfully coerced.`,
+              connection: conn,
+              location: connLocation
+            });
+            return;
+          }
           if (sourceType === targetType) {
+            if (conn.coerce) {
+              this.warnings.push({
+                type: "warning",
+                code: "REDUNDANT_COERCE",
+                message: `Coercion \`as ${conn.coerce}\` on connection "${fromNode}.${fromPort}" \u2192 "${toNode}.${toPort}" is redundant \u2014 source and target are both ${sourceType}.`,
+                connection: conn,
+                location: connLocation
+              });
+              return;
+            }
             if (sourceType === "OBJECT" && sourcePortDef.tsType && targetPortDef.tsType) {
               const normalizedSource = this.normalizeTypeString(sourcePortDef.tsType);
               const normalizedTarget = this.normalizeTypeString(targetPortDef.tsType);
@@ -12732,6 +12776,23 @@ Add '@param ${fromPort}' to the workflow JSDoc and include it in the params obje
           if (sourceType === "ANY" || targetType === "ANY") {
             return;
           }
+          if (conn.coerce) {
+            const producedType = COERCE_OUTPUT_TYPE[conn.coerce];
+            if (producedType === targetType) {
+              return;
+            }
+            pushTypeIssue(
+              {
+                type: "warning",
+                code: "COERCE_TYPE_MISMATCH",
+                message: `Coercion \`as ${conn.coerce}\` produces ${producedType} but target port "${toPort}" on "${toNode}" expects ${targetType}. Use \`as ${suggestCoerceType(targetType)}\` instead.`,
+                connection: conn,
+                location: connLocation
+              },
+              true
+            );
+            return;
+          }
           const safeCoercions = [
             ["NUMBER", "STRING"],
             ["BOOLEAN", "STRING"]
@@ -28164,6 +28225,43 @@ function generateScopeFunctionClosure(scopeName, parentNodeId, parentNodeType, w
 
 // src/generator/code-utils.ts
 init_type_mappings();
+var COERCION_EXPRESSIONS = {
+  string: "String",
+  number: "Number",
+  boolean: "Boolean",
+  json: "JSON.stringify",
+  object: "JSON.parse"
+};
+function resolveSourcePortDataType(workflow, sourceNodeId, sourcePort) {
+  if (isStartNode(sourceNodeId)) {
+    return workflow.startPorts?.[sourcePort]?.dataType;
+  }
+  if (isExitNode(sourceNodeId)) {
+    return workflow.exitPorts?.[sourcePort]?.dataType;
+  }
+  const instance = workflow.instances.find((i) => i.id === sourceNodeId);
+  if (!instance) return void 0;
+  const nodeType = workflow.nodeTypes.find(
+    (nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType
+  );
+  if (!nodeType) return void 0;
+  return nodeType.outputs?.[sourcePort]?.dataType;
+}
+function getCoercionWrapper(connection, sourceDataType, targetDataType) {
+  if (connection.coerce) {
+    return COERCION_EXPRESSIONS[connection.coerce];
+  }
+  if (!sourceDataType || !targetDataType || sourceDataType === targetDataType) return null;
+  if (sourceDataType === "STEP" || targetDataType === "STEP") return null;
+  if (sourceDataType === "ANY" || targetDataType === "ANY") return null;
+  if (targetDataType === "STRING" && sourceDataType !== "STRING") {
+    return "String";
+  }
+  if (sourceDataType === "BOOLEAN" && targetDataType === "NUMBER") {
+    return "Number";
+  }
+  return null;
+}
 function toValidIdentifier(nodeId) {
   let sanitized = nodeId.replace(/[^a-zA-Z0-9_$]/g, "_");
   if (/^[0-9]/.test(sanitized)) {
@@ -28293,9 +28391,18 @@ function buildNodeArgumentsWithContext(opts) {
             `${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`
           );
         } else {
-          lines.push(
-            `${indent}const ${varName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} }) as ${portType};`
-          );
+          const sourceDataType = resolveSourcePortDataType(workflow, sourceNode, sourcePort);
+          const coerceExpr = getCoercionWrapper(connection, sourceDataType, portConfig.dataType);
+          const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} })`;
+          if (coerceExpr) {
+            lines.push(
+              `${indent}const ${varName} = ${coerceExpr}(${getExpr}) as ${portType};`
+            );
+          } else {
+            lines.push(
+              `${indent}const ${varName} = ${getExpr} as ${portType};`
+            );
+          }
         }
       } else {
         const validConnections = connections.filter((conn) => {
@@ -28309,13 +28416,19 @@ function buildNodeArgumentsWithContext(opts) {
           return;
         }
         const attempts = [];
-        validConnections.forEach((conn, _idx) => {
+        validConnections.forEach((conn) => {
           const sourceNode = conn.from.node;
           const sourcePort = conn.from.port;
           const sourceIdx = isStartNode(sourceNode) ? "startIdx" : `${toValidIdentifier(sourceNode)}Idx`;
-          attempts.push(
-            `(${sourceIdx} !== undefined ? ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} }) : undefined)`
-          );
+          const getExpr = `${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx} })`;
+          if (portConfig.dataType !== "FUNCTION") {
+            const sourceDataType = resolveSourcePortDataType(workflow, sourceNode, sourcePort);
+            const coerceExpr = getCoercionWrapper(conn, sourceDataType, portConfig.dataType);
+            const wrapped = coerceExpr ? `${coerceExpr}(${getExpr})` : getExpr;
+            attempts.push(`(${sourceIdx} !== undefined ? ${wrapped} : undefined)`);
+          } else {
+            attempts.push(`(${sourceIdx} !== undefined ? ${getExpr} : undefined)`);
+          }
         });
         const ternary = attempts.join(" ?? ");
         const portType = mapToTypeScript(portConfig.dataType, portConfig.tsType);
@@ -43545,12 +43658,16 @@ var ConnectParser = class extends CstParser {
     super(allTokens);
     this.performSelfAnalysis();
   }
-  // Entry rule for connect line
+  // Entry rule for connect line: @connect A.port -> B.port [as type]
   connectLine = this.RULE("connectLine", () => {
     this.CONSUME(ConnectTag);
     this.SUBRULE(this.portRef, { LABEL: "sourceRef" });
     this.CONSUME(Arrow);
     this.SUBRULE2(this.portRef, { LABEL: "targetRef" });
+    this.OPTION(() => {
+      this.CONSUME(AsKeyword);
+      this.CONSUME(Identifier, { LABEL: "coerceType" });
+    });
   });
   // node.port or node.port:scope
   portRef = this.RULE("portRef", () => {
@@ -43573,7 +43690,17 @@ var ConnectVisitor = class extends BaseVisitor3 {
   connectLine(ctx) {
     const source = this.visit(ctx.sourceRef);
     const target = this.visit(ctx.targetRef);
-    return { source, target };
+    const result = { source, target };
+    if (ctx.coerceType?.[0]) {
+      const validTypes = /* @__PURE__ */ new Set(["string", "number", "boolean", "json", "object"]);
+      const raw = ctx.coerceType[0].image;
+      if (validTypes.has(raw)) {
+        result.coerce = raw;
+      } else {
+        result.invalidCoerceType = raw;
+      }
+    }
+    return result;
   }
   portRef(ctx) {
     const nodeId = ctx.nodeId[0].image;
@@ -43607,7 +43734,14 @@ function parseConnectLine(input, warnings) {
     );
     return null;
   }
-  return visitorInstance3.visit(cst);
+  const result = visitorInstance3.visit(cst);
+  if (result.invalidCoerceType) {
+    warnings.push(
+      `Invalid coerce type "${result.invalidCoerceType}" in @connect. Valid types: string, number, boolean, json, object`
+    );
+    delete result.invalidCoerceType;
+  }
+  return result;
 }
 function getConnectGrammar() {
   return parserInstance3.getSerializedGastProductions();
@@ -45307,7 +45441,7 @@ var JSDocParser = class {
       warnings.push(`Invalid @connect tag format: @connect ${comment}`);
       return;
     }
-    const { source, target } = result;
+    const { source, target, coerce: coerce2 } = result;
     const line = tag.getStartLineNumber();
     config2.connections.push({
       from: {
@@ -45320,7 +45454,8 @@ var JSDocParser = class {
         port: target.portName,
         ...target.scope && { scope: target.scope }
       },
-      sourceLocation: { line, column: 0 }
+      sourceLocation: { line, column: 0 },
+      ...coerce2 && { coerce: coerce2 }
     });
   }
   /**
@@ -53839,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*(.+ -> .+)/);
@@ -53948,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
     };
   },
@@ -54047,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
     };
   },
@@ -54060,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
     };
   },
@@ -54285,6 +54420,41 @@ var errorMappers = {
       code: error2.code
     };
   },
+  COERCE_TYPE_MISMATCH(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    const expectsMatch = error2.message.match(/expects (\w+)/);
+    const expectedType = expectsMatch?.[1] || "unknown";
+    const suggestedType = COERCE_TARGET_TYPES[expectedType.toUpperCase()] || expectedType.toLowerCase();
+    return {
+      title: "Wrong Coercion Type",
+      explanation: `The \`as ${coerceType}\` coercion produces the wrong type for the target port. The target expects ${expectedType}.`,
+      fix: `Change \`as ${coerceType}\` to \`as ${suggestedType}\` in the @connect annotation.`,
+      code: error2.code
+    };
+  },
+  REDUNDANT_COERCE(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    const bothMatch = error2.message.match(/both (\w+)/);
+    const dataType = bothMatch?.[1] || "the same type";
+    return {
+      title: "Redundant Coercion",
+      explanation: `The \`as ${coerceType}\` coercion is unnecessary because both the source and target ports are already ${dataType}.`,
+      fix: `Remove \`as ${coerceType}\` from the @connect annotation \u2014 no coercion is needed.`,
+      code: error2.code
+    };
+  },
+  COERCE_ON_FUNCTION_PORT(error2) {
+    const coerceMatch = error2.message.match(/`as (\w+)`/);
+    const coerceType = coerceMatch?.[1] || "unknown";
+    return {
+      title: "Coercion on Function Port",
+      explanation: `The \`as ${coerceType}\` coercion cannot be applied to FUNCTION ports. Function values are callable references and cannot be meaningfully converted to other types.`,
+      fix: `Remove \`as ${coerceType}\` from the @connect annotation. If you need to convert the function's return value, add a transformation node.`,
+      code: error2.code
+    };
+  },
   LOSSY_TYPE_COERCION(error2) {
     const types2 = extractTypes(error2.message);
     const source = types2?.source || "unknown";
@@ -54294,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
     };
   },
@@ -61418,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 {
@@ -61490,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">
@@ -61521,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';
@@ -61605,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.',
@@ -61619,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) {
@@ -61635,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);
   });
@@ -62088,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) {
@@ -62103,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');
   }
@@ -62111,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();
@@ -62155,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
@@ -96730,7 +97096,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.10.2" : "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({