@synergenius/flow-weaver 0.9.0 → 0.9.2

package/README.md

@@ -4,36 +4,30 @@
 [![License: Flow Weaver Library License](https://img.shields.io/badge/License-Flow%20Weaver%20Library-blue.svg)](./LICENSE)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18-green.svg)](https://nodejs.org)
 
-**Workflow compiler for AI agents.** LLMs create, validate, iterate, and test workflows programmatically. Humans review them visually. Compiled output is standalone TypeScript with no runtime dependencies.
+**Build AI agent workflows visually. Ship them as your own code.**
 
-Flow Weaver turns standard TypeScript functions into executable workflow graphs using JSDoc annotations. No YAML. No JSON configs. No drag-and-drop. Just TypeScript with full type safety, IDE autocomplete, and compile-time validation, in a format LLMs can read and write directly. Compiled output runs anywhere with no dependency on Flow Weaver.
+Design agent workflows in the Studio, in TypeScript, or let AI build them for you. Everything compiles to standalone functions you deploy anywhere, no runtime dependency on Flow Weaver.
 
-## Why Flow Weaver?
+## Three Ways to Build
 
-**Agents generate code well. They don't generate reliable systems.**
+**Studio.** Drag, drop, connect. The visual editor renders your workflow as an interactive graph with bidirectional sync: canvas changes write code, code changes update the canvas. 80+ plugins handle rendering, state, minimap, undo/redo, and more.
 
-With Flow Weaver, an agent builds a typed workflow graph instead of a monolithic script. Every connection is type-checked, every required input is enforced, every error path is explicit.
+**TypeScript.** Annotate plain functions with JSDoc tags. The compiler turns them into executable workflow graphs with full type safety, IDE autocomplete, and compile-time validation. No YAML, no JSON configs.
 
-The development loop (steps 1-4 are fully autonomous):
+**AI Agents.** Connect Claude Code, Cursor, or OpenClaw and they scaffold, validate, and ship workflows using 30+ MCP tools. The agent reads validation errors, fixes issues, and re-validates until the workflow compiles clean. The development loop (steps 1-4 are fully autonomous):
 
-1. **Agent creates**: scaffolds from templates or builds from scratch via 35+ MCP tools
+1. **Agent creates**: scaffolds from templates, builds from a model, or writes from scratch
 2. **Compiler validates**: 15+ validation passes catch missing connections, type mismatches, unreachable paths
-3. **Agent iterates**: validation errors include fix suggestions, the agent corrects and re-validates until clean
+3. **Agent iterates**: validation errors include fix suggestions, the agent corrects and re-validates
 4. **Agent tests**: deterministic mock providers for reproducible testing without real API calls
-5. **Human reviews**: visual editor renders the workflow as an interactive graph for final approval
-
-The compiled code is yours. No runtime lock-in, no framework dependency.
+5. **Human reviews**: visual editor or SVG diagram for final approval
 
 ## Quick Start
 
-### Install
-
 ```bash
 npm install @synergenius/flow-weaver
 ```
 
-### Define a workflow
-
 Workflows are plain TypeScript. Annotations declare the graph structure:
 
 ```typescript
@@ -66,8 +60,6 @@ export async function dataPipeline(
 }
 ```
 
-### Compile and run
-
 ```bash
 npx flow-weaver compile data-pipeline.ts    # generates executable code in-place
 npx flow-weaver run data-pipeline.ts --params '{"rawData": "Hello World"}'
@@ -77,26 +69,36 @@ The compiler fills in the function body while preserving your code outside the g
 
 ## AI-Native Development with MCP
 
-Flow Weaver includes an MCP server with 35+ tools for Claude Code (or any MCP-compatible agent):
+Flow Weaver includes an MCP server for Claude Code, Cursor, OpenClaw, or any MCP-compatible agent:
 
 ```bash
 npx flow-weaver mcp-server    # auto-registers with Claude Code
 ```
 
-What an AI agent can do:
-
 | Capability | MCP Tools |
 |-----------|-----------|
 | **Build** | `fw_scaffold`, `fw_modify`, `fw_modify_batch`, `fw_add_node`, `fw_connect` |
+| **Model** | `fw_create_model`, `fw_workflow_status`, `fw_implement_node` |
 | **Validate** | `fw_validate` (with friendly error hints), `fw_doctor` |
 | **Understand** | `fw_describe` (json/text/mermaid), `fw_query` (10 query types), `fw_diff` |
 | **Test** | `fw_execute_workflow` (with trace), `fw_compile` |
-| **Visualize** | `fw_diagram` (SVG), `fw_get_state`, `fw_focus_node` |
+| **Visualize** | `fw_diagram` (SVG/HTML), `fw_get_state`, `fw_focus_node` |
 | **Deploy** | `fw_export` (Lambda, Vercel, Cloudflare, Inngest), `fw_compile --target inngest` |
 | **Reuse** | `fw_list_patterns`, `fw_apply_pattern`, `fw_extract_pattern` |
 | **Extend** | `fw_market_search`, `fw_market_install` |
 
-The agent reads validation errors, fixes issues, and re-validates until the workflow compiles clean.
+## Model-Driven Workflows
+
+Design first, implement later. Describe the workflow shape (nodes, ports, execution path) and the compiler generates a valid skeleton with `declare function` stubs:
+
+```bash
+# Via MCP: fw_create_model with nodes, inputs/outputs, and execution path
+# Via CLI:
+npx flow-weaver status my-workflow.ts      # shows stub vs implemented progress
+npx flow-weaver implement my-workflow.ts processData   # scaffolds a node body
+```
+
+The graph is valid before any node has a real implementation. Fill in node bodies incrementally, check `status` to track progress. Architecture and implementation stay separate: the architect defines the shape, developers fill in the logic.
 
 ## Agent Workflow Templates
 
@@ -140,14 +142,14 @@ npx flow-weaver create workflow ai-agent-durable durable-agent.ts
 The validator understands AI agent patterns and enforces safety rules:
 
 ```
-AGENT_LLM_MISSING_ERROR_HANDLER    LLM node's onFailure is unconnected — add error handling
-AGENT_UNGUARDED_TOOL_EXECUTOR      Tool executor has no human-approval upstream — add a gate
-AGENT_MISSING_MEMORY_IN_LOOP       Agent loop has LLM but no memory — conversations will be stateless
-AGENT_LLM_NO_FALLBACK              LLM failure goes directly to Exit — add retry or fallback logic
-AGENT_TOOL_NO_OUTPUT_HANDLING      Tool executor outputs are all unconnected — results are discarded
+AGENT_LLM_MISSING_ERROR_HANDLER    LLM node's onFailure is unconnected, add error handling
+AGENT_UNGUARDED_TOOL_EXECUTOR      Tool executor has no human-approval upstream, add a gate
+AGENT_MISSING_MEMORY_IN_LOOP       Agent loop has LLM but no memory, conversations will be stateless
+AGENT_LLM_NO_FALLBACK              LLM failure goes directly to Exit, add retry or fallback logic
+AGENT_TOOL_NO_OUTPUT_HANDLING      Tool executor outputs are all unconnected, results are discarded
 ```
 
-Not generic lint rules. The validator identifies LLM, tool-executor, human-approval, and memory nodes by port signatures, annotations, and naming patterns, then applies agent-specific checks.
+These aren't generic lint rules. The validator identifies LLM, tool-executor, human-approval, and memory nodes by port signatures, annotations, and naming patterns, then applies agent-specific checks.
 
 ## Deterministic Agent Testing
 
@@ -190,13 +192,30 @@ Most workflow engines either ban loops (DAG-only) or allow arbitrary cycles (har
  */
 ```
 
-The scope's output ports become callback parameters, and input ports become return values. This enables:
-- Agent reasoning loops (LLM -> tools -> memory -> LLM)
-- ForEach over collections
-- Map/reduce patterns
-- Nested sub-workflows
+The scope's output ports become callback parameters, and input ports become return values. Agent reasoning loops, ForEach over collections, map/reduce patterns, nested sub-workflows: all work while keeping the graph acyclic and statically analyzable.
 
-All while keeping the graph acyclic and statically analyzable.
+## Diagram Generation
+
+Generate SVG or interactive HTML diagrams from any workflow:
+
+```bash
+flow-weaver diagram workflow.ts -o workflow.svg --theme dark
+flow-weaver diagram workflow.ts -o workflow.html --format html
+```
+
+Customize node appearance with annotations:
+
+```typescript
+/**
+ * @flowWeaver nodeType
+ * @color blue
+ * @icon database
+ */
+```
+
+Named colors: `blue`, `purple`, `green`, `cyan`, `orange`, `pink`, `red`, `yellow`. Icons include `api`, `database`, `shield`, `brain`, `cloud`, `search`, `code`, and 60+ more from Material Design 3.
+
+The interactive HTML viewer supports zoom/pan, click-to-inspect nodes, port-level hover with connection tracing, and works standalone or embedded in an iframe.
 
 ## Multi-Target Compilation
 
@@ -220,23 +239,6 @@ flow-weaver serve ./workflows --port 3000 --swagger
 
 Both the default TypeScript target and Inngest target parallelize independent nodes with `Promise.all()`. Inngest additionally wraps each node in `step.run()` for individual durability and generates typed Zod event schemas.
 
-## Visual Human-in-the-Loop
-
-Workflows compile from code, but humans review them visually:
-
-```bash
-# Generate SVG diagram
-flow-weaver diagram workflow.ts -o workflow.svg --theme dark
-
-# Describe structure for quick review
-flow-weaver describe workflow.ts --format text
-
-# Semantic diff between versions
-flow-weaver diff workflow-v1.ts workflow-v2.ts
-```
-
-Flow Weaver Studio is a visual editor with bidirectional sync: code changes update the canvas, canvas changes update the code. 80+ plugins handle rendering, state, minimap, undo/redo, and more.
-
 ## API
 
 ```typescript
@@ -263,8 +265,16 @@ const code = generateCode(ast);
 |-------------|---------|
 | `@synergenius/flow-weaver` | Parse, validate, compile, generate, AST types, builders, diff, patterns |
 | `@synergenius/flow-weaver/runtime` | Execution context, errors, function registry for generated code |
-| `@synergenius/flow-weaver/built-in-nodes` | delay, waitForEvent, invokeWorkflow |
-| `@synergenius/flow-weaver/diagram` | SVG diagram layout and rendering |
+| `@synergenius/flow-weaver/testing` | Mock LLM/approval providers, recording/replay, assertions, token tracking |
+| `@synergenius/flow-weaver/built-in-nodes` | delay, waitForEvent, waitForAgent, invokeWorkflow |
+| `@synergenius/flow-weaver/diagram` | SVG/HTML diagram layout and rendering |
+| `@synergenius/flow-weaver/ast` | AST types and utilities |
+| `@synergenius/flow-weaver/api` | Programmatic workflow manipulation API |
+| `@synergenius/flow-weaver/diff` | Semantic workflow diffing |
+| `@synergenius/flow-weaver/deployment` | Multi-target deployment generators |
+| `@synergenius/flow-weaver/marketplace` | Marketplace package utilities |
+| `@synergenius/flow-weaver/editor` | Editor completions and suggestions |
+| `@synergenius/flow-weaver/browser` | JSDoc port sync for browser environments |
 | `@synergenius/flow-weaver/describe` | Programmatic workflow description |
 | `@synergenius/flow-weaver/doc-metadata` | Documentation metadata extractors |
 
@@ -276,11 +286,16 @@ flow-weaver compile <file>           # Compile to TypeScript or Inngest
 flow-weaver validate <file>          # Validate without compiling
 flow-weaver run <file>               # Execute a workflow
 flow-weaver dev <file>               # Watch + compile + run
+flow-weaver strip <file>             # Remove generated code sections
 flow-weaver describe <file>          # Structure output (json/text/mermaid)
-flow-weaver diagram <file>           # Generate SVG diagram
+flow-weaver diagram <file>           # Generate SVG or interactive HTML diagram
 flow-weaver diff <f1> <f2>           # Semantic workflow comparison
 
-# Setup
+# Model-driven
+flow-weaver status <file>            # Show stub vs implemented progress
+flow-weaver implement <file> <node>  # Scaffold a node body from its stub
+
+# Scaffolding
 flow-weaver init [directory]         # Create new project
 flow-weaver create workflow <t> <f>  # Scaffold from template
 flow-weaver create node <name> <f>   # Scaffold node type
@@ -307,10 +322,16 @@ flow-weaver docs search <query>      # Search documentation
 flow-weaver market search [query]    # Search npm for packages
 flow-weaver market install <pkg>     # Install a package
 flow-weaver market list              # List installed packages
+flow-weaver market init <name>       # Scaffold a marketplace package
+flow-weaver market pack              # Validate and generate manifest
+flow-weaver market publish           # Publish to npm
 
-# IDE
+# Editor / IDE
 flow-weaver mcp-server               # Start MCP server for Claude Code
 flow-weaver listen                   # Stream editor events
+flow-weaver changelog                # Generate changelog from git history
+flow-weaver migrate <glob>           # Run migration transforms on workflow files
+flow-weaver plugin init <name>       # Scaffold an external plugin
 ```
 
 ## Built-in Nodes
@@ -339,17 +360,6 @@ function nodeName(
 
 Expression nodes (`@expression`) skip the control flow boilerplate. Inputs and outputs map directly to the TypeScript signature.
 
-## Marketplace
-
-Distribute node types, workflows, and patterns as npm packages:
-
-```bash
-flow-weaver market init my-nodes          # Scaffold a package
-flow-weaver market pack                   # Validate and generate manifest
-flow-weaver market publish                # Publish to npm
-flow-weaver market install flowweaver-pack-openai   # Install
-```
-
 ## Testing
 
 ```bash

package/dist/cli/flow-weaver.mjs

@@ -44825,38 +44825,39 @@ function assignImplicitPortOrders(ports) {
     scopeGroups.get(scopeKey).push([portName, portDef]);
   }
   for (const [scope, portsInScope] of scopeGroups.entries()) {
+    let nextSlot2 = function(from) {
+      while (occupied.has(from)) from++;
+      occupied.add(from);
+      return from;
+    };
+    var nextSlot = nextSlot2;
     const isScoped = scope !== void 0;
-    const mandatoryPorts = portsInScope.filter(([name]) => isMandatoryPort(name, isScoped));
-    const regularPorts = portsInScope.filter(([name]) => !isMandatoryPort(name, isScoped));
-    let minRegularExplicitOrder = Infinity;
-    for (const [, portDef] of regularPorts) {
+    const occupied = /* @__PURE__ */ new Set();
+    for (const [, portDef] of portsInScope) {
       const order = portDef.metadata?.order;
       if (typeof order === "number") {
-        minRegularExplicitOrder = Math.min(minRegularExplicitOrder, order);
+        occupied.add(order);
       }
     }
-    let mandatoryStartOrder = 0;
-    if (minRegularExplicitOrder !== Infinity && minRegularExplicitOrder === 0) {
-      const regularPortsWithOrder0 = regularPorts.filter(([, p]) => p.metadata?.order === 0);
-      mandatoryStartOrder = regularPortsWithOrder0.length;
-    }
-    let currentMandatoryOrder = mandatoryStartOrder;
-    for (const [, portDef] of mandatoryPorts) {
-      if (portDef.metadata?.order === void 0) {
-        if (!portDef.metadata) {
-          portDef.metadata = {};
-        }
-        portDef.metadata.order = currentMandatoryOrder++;
-      }
+    const mandatoryNeedOrder = portsInScope.filter(
+      ([name, def]) => isMandatoryPort(name, isScoped) && def.metadata?.order === void 0
+    );
+    const regularNeedOrder = portsInScope.filter(
+      ([name, def]) => !isMandatoryPort(name, isScoped) && def.metadata?.order === void 0
+    );
+    let slot = -mandatoryNeedOrder.length;
+    for (const [, portDef] of mandatoryNeedOrder) {
+      if (!portDef.metadata) portDef.metadata = {};
+      slot = nextSlot2(slot);
+      portDef.metadata.order = slot;
+      slot++;
     }
-    let currentRegularOrder = currentMandatoryOrder;
-    for (const [, portDef] of regularPorts) {
-      if (portDef.metadata?.order === void 0) {
-        if (!portDef.metadata) {
-          portDef.metadata = {};
-        }
-        portDef.metadata.order = currentRegularOrder++;
-      }
+    slot = Math.max(slot, 0);
+    for (const [, portDef] of regularNeedOrder) {
+      if (!portDef.metadata) portDef.metadata = {};
+      slot = nextSlot2(slot);
+      portDef.metadata.order = slot;
+      slot++;
     }
   }
 }
@@ -60592,7 +60593,7 @@ function renderSVG(graph, options = {}) {
 function renderConnection(parts2, conn, gradIndex) {
   const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`
+    `  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
   );
 }
 function renderScopeConnection(parts2, conn, allConnections) {
@@ -60600,7 +60601,7 @@ function renderScopeConnection(parts2, conn, allConnections) {
   if (gradIndex < 0) return;
   const dashAttr = conn.isStepConnection ? "" : ' stroke-dasharray="8 4"';
   parts2.push(
-    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`
+    `    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`
   );
 }
 function renderNodeBody(parts2, node, theme, indent) {
@@ -60681,7 +60682,7 @@ function renderPortDots(parts2, nodeId, inputs, outputs, themeName) {
     const color = getPortColor(port.dataType, port.isFailure, themeName);
     const ringColor = getPortRingColor(port.dataType, port.isFailure, themeName);
     const dir = port.direction === "INPUT" ? "input" : "output";
-    parts2.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}" data-direction="${dir}"/>`);
+    parts2.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}" data-direction="${dir}"/>`);
   }
 }
 function renderPortLabels(parts2, nodeId, inputs, outputs, theme, themeName) {
@@ -60689,7 +60690,8 @@ function renderPortLabels(parts2, nodeId, inputs, outputs, theme, themeName) {
     const color = getPortColor(port.dataType, port.isFailure, themeName);
     const isInput = port.direction === "INPUT";
     const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
-    const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}`;
+    const dir = isInput ? "input" : "output";
+    const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}`;
     const portLabel = port.label;
     const typeWidth = measureText(abbrev);
     const labelWidth = measureText(portLabel);
@@ -60983,43 +60985,79 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     else if (e.key === 'Escape') deselectNode();
   });
 
-  // ---- Port label visibility via JS (since CSS sibling selectors can't reach .labels group) ----
-  var labelEls = content.querySelectorAll('.labels g[data-port-label]');
-  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
+  // ---- Port label visibility ----
+  var labelMap = {};
+  content.querySelectorAll('.labels g[data-port-label]').forEach(function(lbl) {
+    labelMap[lbl.getAttribute('data-port-label')] = lbl;
+  });
 
-  function showLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '1';
-        lbl.style.pointerEvents = 'auto';
-      }
+  // Build adjacency: portId \u2192 array of connected portIds
+  var portConnections = {};
+  content.querySelectorAll('.connections path').forEach(function(p) {
+    var src = p.getAttribute('data-source');
+    var tgt = p.getAttribute('data-target');
+    if (!src || !tgt) return;
+    if (!portConnections[src]) portConnections[src] = [];
+    if (!portConnections[tgt]) portConnections[tgt] = [];
+    portConnections[src].push(tgt);
+    portConnections[tgt].push(src);
+  });
+
+  var allLabelIds = Object.keys(labelMap);
+  var hoveredPort = null;
+
+  function showLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '1'; l.style.pointerEvents = 'auto'; } }
+  function hideLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '0'; l.style.pointerEvents = 'none'; } }
+
+  function showLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) showLabel(id);
     });
   }
-  function hideLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '0';
-        lbl.style.pointerEvents = 'none';
-      }
+  function hideLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) hideLabel(id);
     });
   }
 
+  // Node hover: show all port labels for the hovered node
+  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
   nodeEls.forEach(function(nodeG) {
     var nodeId = nodeG.getAttribute('data-node-id');
     var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('g[data-node-id]') : null;
     var parentId = parentNodeG ? parentNodeG.getAttribute('data-node-id') : null;
     nodeG.addEventListener('mouseenter', function() {
+      if (hoveredPort) return; // port hover takes priority
       if (parentId) hideLabelsFor(parentId);
       showLabelsFor(nodeId);
     });
     nodeG.addEventListener('mouseleave', function() {
+      if (hoveredPort) return;
       hideLabelsFor(nodeId);
       if (parentId) showLabelsFor(parentId);
     });
   });
 
+  // Port hover: show this port's label + all connected port labels
+  content.querySelectorAll('[data-port-id]').forEach(function(portEl) {
+    var portId = portEl.getAttribute('data-port-id');
+    var nodeId = portId.split('.')[0];
+    var peers = (portConnections[portId] || []).concat(portId);
+
+    portEl.addEventListener('mouseenter', function() {
+      hoveredPort = portId;
+      // Hide all labels for this node first, then show only the relevant ones
+      hideLabelsFor(nodeId);
+      peers.forEach(showLabel);
+    });
+    portEl.addEventListener('mouseleave', function() {
+      hoveredPort = null;
+      peers.forEach(hideLabel);
+      // Restore all labels for the node since we're still inside it
+      showLabelsFor(nodeId);
+    });
+  });
+
   // ---- Click to inspect node ----
   function deselectNode() {
     selectedNodeId = null;
@@ -61046,7 +61084,7 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     ports.forEach(function(p) {
       var id = p.getAttribute('data-port-id');
       var dir = p.getAttribute('data-direction');
-      var name = id.split('.').slice(1).join('.');
+      var name = id.split('.').slice(1).join('.').replace(/:(?:input|output)$/, '');
       if (dir === 'input') inputs.push(name);
       else outputs.push(name);
     });
@@ -95710,7 +95748,7 @@ function displayInstalledPackage(pkg) {
 }
 
 // src/cli/index.ts
-var version2 = true ? "0.9.0" : "0.0.0-dev";
+var version2 = true ? "0.9.2" : "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.js

@@ -266,43 +266,79 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     else if (e.key === 'Escape') deselectNode();
   });
 
-  // ---- Port label visibility via JS (since CSS sibling selectors can't reach .labels group) ----
-  var labelEls = content.querySelectorAll('.labels g[data-port-label]');
-  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
+  // ---- Port label visibility ----
+  var labelMap = {};
+  content.querySelectorAll('.labels g[data-port-label]').forEach(function(lbl) {
+    labelMap[lbl.getAttribute('data-port-label')] = lbl;
+  });
 
-  function showLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '1';
-        lbl.style.pointerEvents = 'auto';
-      }
+  // Build adjacency: portId → array of connected portIds
+  var portConnections = {};
+  content.querySelectorAll('.connections path').forEach(function(p) {
+    var src = p.getAttribute('data-source');
+    var tgt = p.getAttribute('data-target');
+    if (!src || !tgt) return;
+    if (!portConnections[src]) portConnections[src] = [];
+    if (!portConnections[tgt]) portConnections[tgt] = [];
+    portConnections[src].push(tgt);
+    portConnections[tgt].push(src);
+  });
+
+  var allLabelIds = Object.keys(labelMap);
+  var hoveredPort = null;
+
+  function showLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '1'; l.style.pointerEvents = 'auto'; } }
+  function hideLabel(id) { var l = labelMap[id]; if (l) { l.style.opacity = '0'; l.style.pointerEvents = 'none'; } }
+
+  function showLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) showLabel(id);
     });
   }
-  function hideLabelsFor(id) {
-    labelEls.forEach(function(lbl) {
-      var portId = lbl.getAttribute('data-port-label') || '';
-      if (portId.indexOf(id + '.') === 0) {
-        lbl.style.opacity = '0';
-        lbl.style.pointerEvents = 'none';
-      }
+  function hideLabelsFor(nodeId) {
+    allLabelIds.forEach(function(id) {
+      if (id.indexOf(nodeId + '.') === 0) hideLabel(id);
     });
   }
 
+  // Node hover: show all port labels for the hovered node
+  var nodeEls = content.querySelectorAll('.nodes g[data-node-id]');
   nodeEls.forEach(function(nodeG) {
     var nodeId = nodeG.getAttribute('data-node-id');
     var parentNodeG = nodeG.parentElement ? nodeG.parentElement.closest('g[data-node-id]') : null;
     var parentId = parentNodeG ? parentNodeG.getAttribute('data-node-id') : null;
     nodeG.addEventListener('mouseenter', function() {
+      if (hoveredPort) return; // port hover takes priority
       if (parentId) hideLabelsFor(parentId);
       showLabelsFor(nodeId);
     });
     nodeG.addEventListener('mouseleave', function() {
+      if (hoveredPort) return;
       hideLabelsFor(nodeId);
       if (parentId) showLabelsFor(parentId);
     });
   });
 
+  // Port hover: show this port's label + all connected port labels
+  content.querySelectorAll('[data-port-id]').forEach(function(portEl) {
+    var portId = portEl.getAttribute('data-port-id');
+    var nodeId = portId.split('.')[0];
+    var peers = (portConnections[portId] || []).concat(portId);
+
+    portEl.addEventListener('mouseenter', function() {
+      hoveredPort = portId;
+      // Hide all labels for this node first, then show only the relevant ones
+      hideLabelsFor(nodeId);
+      peers.forEach(showLabel);
+    });
+    portEl.addEventListener('mouseleave', function() {
+      hoveredPort = null;
+      peers.forEach(hideLabel);
+      // Restore all labels for the node since we're still inside it
+      showLabelsFor(nodeId);
+    });
+  });
+
   // ---- Click to inspect node ----
   function deselectNode() {
     selectedNodeId = null;
@@ -329,7 +365,7 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     ports.forEach(function(p) {
       var id = p.getAttribute('data-port-id');
       var dir = p.getAttribute('data-direction');
-      var name = id.split('.').slice(1).join('.');
+      var name = id.split('.').slice(1).join('.').replace(/:(?:input|output)$/, '');
       if (dir === 'input') inputs.push(name);
       else outputs.push(name);
     });

package/dist/diagram/renderer.js

@@ -90,14 +90,14 @@ export function renderSVG(graph, options = {}) {
 // ---- Connection rendering ----
 function renderConnection(parts, conn, gradIndex) {
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`);
+    parts.push(`  <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="3"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
 function renderScopeConnection(parts, conn, allConnections) {
     const gradIndex = allConnections.indexOf(conn);
     if (gradIndex < 0)
         return;
     const dashAttr = conn.isStepConnection ? '' : ' stroke-dasharray="8 4"';
-    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}"/>`);
+    parts.push(`    <path d="${conn.path}" fill="none" stroke="url(#conn-grad-${gradIndex})" stroke-width="2.5"${dashAttr} stroke-linecap="round" data-source="${escapeXml(conn.fromNode)}.${escapeXml(conn.fromPort)}:output" data-target="${escapeXml(conn.toNode)}.${escapeXml(conn.toPort)}:input"/>`);
 }
 // ---- Node rendering ----
 /** Render node body rect + icon */
@@ -183,7 +183,7 @@ function renderPortDots(parts, nodeId, inputs, outputs, themeName) {
         const color = getPortColor(port.dataType, port.isFailure, themeName);
         const ringColor = getPortRingColor(port.dataType, port.isFailure, themeName);
         const dir = port.direction === 'INPUT' ? 'input' : 'output';
-        parts.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}" data-direction="${dir}"/>`);
+        parts.push(`    <circle cx="${port.cx}" cy="${port.cy}" r="${PORT_RADIUS}" fill="${color}" stroke="${ringColor}" stroke-width="2" data-port-id="${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}" data-direction="${dir}"/>`);
     }
 }
 /** Render only port label badges (no dots) */
@@ -192,7 +192,8 @@ function renderPortLabels(parts, nodeId, inputs, outputs, theme, themeName) {
         const color = getPortColor(port.dataType, port.isFailure, themeName);
         const isInput = port.direction === 'INPUT';
         const abbrev = TYPE_ABBREVIATIONS[port.dataType] ?? port.dataType;
-        const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}`;
+        const dir = isInput ? 'input' : 'output';
+        const portId = `${escapeXml(nodeId)}.${escapeXml(port.name)}:${dir}`;
         const portLabel = port.label;
         const typeWidth = measureText(abbrev);
         const labelWidth = measureText(portLabel);

package/dist/utils/port-ordering.d.ts

@@ -14,11 +14,11 @@ export declare function isMandatoryPort(portName: string, isScoped: boolean): bo
  *
  * Rules:
  * 1. Ports are grouped by scope (undefined = external, string = scoped)
- * 2. Within each scope group:
- *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
- *    - Regular ports get higher order values
- * 3. Explicit order metadata is always preserved
- * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ * 2. Explicit order metadata is always preserved
+ * 3. Mandatory ports without explicit orders get negative slots (-N, ..., -1)
+ *    so they always sort before any user-specified [order:0] data port
+ * 4. Regular ports without explicit orders fill non-negative slots (0+),
+ *    skipping any slots already occupied by explicit orders
  *
  * @param ports - Record of port definitions to process (mutated in place)
  */

package/dist/utils/port-ordering.js

@@ -19,11 +19,11 @@ export function isMandatoryPort(portName, isScoped) {
  *
  * Rules:
  * 1. Ports are grouped by scope (undefined = external, string = scoped)
- * 2. Within each scope group:
- *    - Mandatory ports (execute, onSuccess, onFailure) get lower order values
- *    - Regular ports get higher order values
- * 3. Explicit order metadata is always preserved
- * 4. If a regular port has explicit order 0, mandatory ports are pushed to order >= 1
+ * 2. Explicit order metadata is always preserved
+ * 3. Mandatory ports without explicit orders get negative slots (-N, ..., -1)
+ *    so they always sort before any user-specified [order:0] data port
+ * 4. Regular ports without explicit orders fill non-negative slots (0+),
+ *    skipping any slots already occupied by explicit orders
  *
  * @param ports - Record of port definitions to process (mutated in place)
  */
@@ -40,48 +40,41 @@ export function assignImplicitPortOrders(ports) {
     // Process each scope group independently
     for (const [scope, portsInScope] of scopeGroups.entries()) {
         const isScoped = scope !== undefined;
-        // Separate mandatory from regular ports
-        const mandatoryPorts = portsInScope.filter(([name]) => isMandatoryPort(name, isScoped));
-        const regularPorts = portsInScope.filter(([name]) => !isMandatoryPort(name, isScoped));
-        // Find minimum explicit order among regular ports (if any)
-        let minRegularExplicitOrder = Infinity;
-        for (const [, portDef] of regularPorts) {
+        // Collect all explicitly occupied order slots
+        const occupied = new Set();
+        for (const [, portDef] of portsInScope) {
             const order = portDef.metadata?.order;
             if (typeof order === "number") {
-                minRegularExplicitOrder = Math.min(minRegularExplicitOrder, order);
+                occupied.add(order);
             }
         }
-        // Determine starting order for mandatory ports
-        let mandatoryStartOrder = 0;
-        // If a regular port has explicit order 0 (or any low value),
-        // mandatory ports should be pushed after it
-        if (minRegularExplicitOrder !== Infinity && minRegularExplicitOrder === 0) {
-            // Count how many regular ports have explicit order 0
-            const regularPortsWithOrder0 = regularPorts.filter(([, p]) => p.metadata?.order === 0);
-            mandatoryStartOrder = regularPortsWithOrder0.length;
+        // Helper: find next available slot starting from `from`
+        function nextSlot(from) {
+            while (occupied.has(from))
+                from++;
+            occupied.add(from);
+            return from;
         }
-        // Assign orders to mandatory ports (if they don't have explicit order)
-        let currentMandatoryOrder = mandatoryStartOrder;
-        for (const [, portDef] of mandatoryPorts) {
-            if (portDef.metadata?.order === undefined) {
-                // Assign implicit order
-                if (!portDef.metadata) {
-                    portDef.metadata = {};
-                }
-                portDef.metadata.order = currentMandatoryOrder++;
-            }
+        // Separate mandatory from regular ports (only those needing implicit orders)
+        const mandatoryNeedOrder = portsInScope.filter(([name, def]) => isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
+        const regularNeedOrder = portsInScope.filter(([name, def]) => !isMandatoryPort(name, isScoped) && def.metadata?.order === undefined);
+        // Mandatory ports fill negative slots so they always sort before [order:0] data ports
+        let slot = -mandatoryNeedOrder.length;
+        for (const [, portDef] of mandatoryNeedOrder) {
+            if (!portDef.metadata)
+                portDef.metadata = {};
+            slot = nextSlot(slot);
+            portDef.metadata.order = slot;
+            slot++;
         }
-        // Assign orders to regular ports (if they don't have explicit order)
-        // Regular ports start after mandatory ports
-        let currentRegularOrder = currentMandatoryOrder;
-        for (const [, portDef] of regularPorts) {
-            if (portDef.metadata?.order === undefined) {
-                // Assign implicit order
-                if (!portDef.metadata) {
-                    portDef.metadata = {};
-                }
-                portDef.metadata.order = currentRegularOrder++;
-            }
+        // Regular ports fill non-negative slots, skipping occupied ones
+        slot = Math.max(slot, 0);
+        for (const [, portDef] of regularNeedOrder) {
+            if (!portDef.metadata)
+                portDef.metadata = {};
+            slot = nextSlot(slot);
+            portDef.metadata.order = slot;
+            slot++;
         }
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@synergenius/flow-weaver",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Deterministic workflow compiler for AI agents. Compiles to standalone TypeScript, no runtime dependencies.",
   "private": false,
   "type": "module",
@@ -66,6 +66,10 @@
     "./marketplace": {
       "types": "./dist/marketplace/index.d.ts",
       "default": "./dist/marketplace/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "default": "./dist/testing/index.js"
     }
   },
   "bin": {