@synergenius/flow-weaver 0.10.2 → 0.10.4

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,
         };
     },
@@ -505,6 +505,41 @@ const errorMappers = {
             code: error.code,
         };
     },
+    COERCE_TYPE_MISMATCH(error) {
+        const coerceMatch = error.message.match(/`as (\w+)`/);
+        const coerceType = coerceMatch?.[1] || 'unknown';
+        const expectsMatch = error.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: error.code,
+        };
+    },
+    REDUNDANT_COERCE(error) {
+        const coerceMatch = error.message.match(/`as (\w+)`/);
+        const coerceType = coerceMatch?.[1] || 'unknown';
+        const bothMatch = error.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 — no coercion is needed.`,
+            code: error.code,
+        };
+    },
+    COERCE_ON_FUNCTION_PORT(error) {
+        const coerceMatch = error.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: error.code,
+        };
+    },
     LOSSY_TYPE_COERCION(error) {
         const types = extractTypes(error.message);
         const source = types?.source || 'unknown';
@@ -515,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/dist/generator/code-utils.d.ts

@@ -1,4 +1,15 @@
-import type { TNodeTypeAST, TWorkflowAST, TMergeStrategy } from '../ast/index.js';
+import type { TNodeTypeAST, TWorkflowAST, TMergeStrategy, TConnectionAST, TDataType } from '../ast/index.js';
+/**
+ * Get the coercion expression to wrap a value, if coercion is needed.
+ * Returns null if no coercion needed.
+ *
+ * Priority:
+ * 1. Explicit coerce on the connection (from `as <type>` annotation)
+ * 2. Auto-coercion for safe pairs:
+ *    - anything -> STRING (String() never fails)
+ *    - BOOLEAN -> NUMBER (well-defined: false->0, true->1)
+ */
+export declare function getCoercionWrapper(connection: TConnectionAST, sourceDataType: TDataType | undefined, targetDataType: TDataType | undefined): string | null;
 /**
  * Sanitize a node ID to be a valid JavaScript identifier.
  * Replaces non-alphanumeric characters (except _ and $) with underscores.

package/dist/generator/code-utils.js

@@ -1,6 +1,72 @@
 import { RESERVED_PORT_NAMES, isStartNode, isExitNode, isExecutePort, isSuccessPort, isFailurePort, } from '../constants.js';
 import { generateScopeFunctionClosure } from './scope-function-generator.js';
 import { mapToTypeScript } from '../type-mappings.js';
+/** Map coercion target type to inline JS expression */
+const COERCION_EXPRESSIONS = {
+    string: 'String',
+    number: 'Number',
+    boolean: 'Boolean',
+    json: 'JSON.stringify',
+    object: 'JSON.parse',
+};
+/** Map TDataType to TCoerceTargetType for auto-coercion */
+const DATATYPE_TO_COERCE = {
+    STRING: 'string',
+    NUMBER: 'number',
+    BOOLEAN: 'boolean',
+    OBJECT: 'object',
+};
+/**
+ * Resolve the dataType of a source port by looking up the node instance -> node type -> outputs.
+ */
+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 undefined;
+    const nodeType = workflow.nodeTypes.find((nt) => nt.name === instance.nodeType || nt.functionName === instance.nodeType);
+    if (!nodeType)
+        return undefined;
+    return nodeType.outputs?.[sourcePort]?.dataType;
+}
+/**
+ * Get the coercion expression to wrap a value, if coercion is needed.
+ * Returns null if no coercion needed.
+ *
+ * Priority:
+ * 1. Explicit coerce on the connection (from `as <type>` annotation)
+ * 2. Auto-coercion for safe pairs:
+ *    - anything -> STRING (String() never fails)
+ *    - BOOLEAN -> NUMBER (well-defined: false->0, true->1)
+ */
+export function getCoercionWrapper(connection, sourceDataType, targetDataType) {
+    // Explicit coerce on connection
+    if (connection.coerce) {
+        return COERCION_EXPRESSIONS[connection.coerce];
+    }
+    // No auto-coercion if types are unknown or same
+    if (!sourceDataType || !targetDataType || sourceDataType === targetDataType)
+        return null;
+    // Skip STEP and ANY ports — no coercion needed
+    if (sourceDataType === 'STEP' || targetDataType === 'STEP')
+        return null;
+    if (sourceDataType === 'ANY' || targetDataType === 'ANY')
+        return null;
+    // Auto-coerce: anything -> STRING
+    if (targetDataType === 'STRING' && sourceDataType !== 'STRING') {
+        return 'String';
+    }
+    // Auto-coerce: BOOLEAN -> NUMBER
+    if (sourceDataType === 'BOOLEAN' && targetDataType === 'NUMBER') {
+        return 'Number';
+    }
+    return null;
+}
 /**
  * Sanitize a node ID to be a valid JavaScript identifier.
  * Replaces non-alphanumeric characters (except _ and $) with underscores.
@@ -197,7 +263,16 @@ export function buildNodeArgumentsWithContext(opts) {
                     lines.push(`${indent}const ${varName} = ${varName}_resolved.fn as ${portType};`);
                 }
                 else {
-                    lines.push(`${indent}const ${varName} = ${getCall}({ id: '${sourceNode}', portName: '${sourcePort}', executionIndex: ${sourceIdx}${nonNullAssert} }) as ${portType};`);
+                    // Check for coercion (explicit or auto)
+                    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 {
@@ -214,11 +289,21 @@ export 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} })`;
+                    // Per-connection coercion: each source gets its own coercion wrapper
+                    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);

package/dist/jsdoc-parser.js

@@ -889,7 +889,7 @@ export class JSDocParser {
             warnings.push(`Invalid @connect tag format: @connect ${comment}`);
             return;
         }
-        const { source, target } = result;
+        const { source, target, coerce } = result;
         // Capture source location from tag
         const line = tag.getStartLineNumber();
         config.connections.push({
@@ -904,6 +904,7 @@ export class JSDocParser {
                 ...(target.scope && { scope: target.scope }),
             },
             sourceLocation: { line, column: 0 },
+            ...(coerce && { coerce }),
         });
     }
     /**