@synergenius/flow-weaver 0.17.9 → 0.17.11

package/dist/ast/types.d.ts

@@ -786,7 +786,7 @@ export type TNodeTagAST = {
 };
 /** Visual customization for node types */
 export type TNodeVisualsAST = {
-    /** Theme color: blue, purple, teal, orange, pink, green */
+    /** Theme color: blue, purple, cyan, orange, pink, green, red, yellow (teal is an alias for cyan) */
     color?: string;
     /** Icon preset name */
     icon?: string;

package/dist/chevrotain-parser/port-parser.d.ts

@@ -15,6 +15,7 @@ export interface PortParseResult {
     mergeStrategy?: string;
     hidden?: boolean;
     description?: string;
+    customMetadata?: Record<string, string | boolean | number>;
 }
 /**
  * Parse a port line (@input/@output/@step) and return structured result.

package/dist/chevrotain-parser/port-parser.js

@@ -98,6 +98,7 @@ class PortParser extends CstParser {
                     { ALT: () => this.SUBRULE(this.typeAttr) },
                     { ALT: () => this.SUBRULE(this.mergeStrategyAttr) },
                     { ALT: () => this.SUBRULE(this.hiddenAttr) },
+                    { ALT: () => this.SUBRULE(this.customAttr) },
                 ]);
             },
         });
@@ -131,6 +132,18 @@ class PortParser extends CstParser {
     hiddenAttr = this.RULE('hiddenAttr', () => {
         this.CONSUME(HiddenKeyword);
     });
+    // customAttr: key:value pairs for arbitrary metadata (e.g., artifactPath:"dist/")
+    customAttr = this.RULE('customAttr', () => {
+        this.CONSUME(Identifier, { LABEL: 'customKey' });
+        this.CONSUME(Colon);
+        this.OR([
+            { ALT: () => this.CONSUME(StringLiteral, { LABEL: 'customStrVal' }) },
+            { ALT: () => this.CONSUME(TrueKeyword, { LABEL: 'customTrue' }) },
+            { ALT: () => this.CONSUME(FalseKeyword, { LABEL: 'customFalse' }) },
+            { ALT: () => this.CONSUME2(Identifier, { LABEL: 'customIdVal' }) },
+            { ALT: () => this.CONSUME(Integer, { LABEL: 'customIntVal' }) },
+        ]);
+    });
     // - description text
     // Note: We just consume the dash here. The actual description text is extracted
     // from the raw input in parsePortLine() to handle special characters like &, :, etc.
@@ -232,6 +245,7 @@ class PortVisitor extends BaseVisitor {
             scope = this.visit(ctx.scopeClause);
         }
         let hidden;
+        let customMetadata;
         if (ctx.metadataBracket) {
             // Handle multiple metadata brackets (e.g., [order:1] [placement:TOP])
             for (const bracket of ctx.metadataBracket) {
@@ -246,6 +260,9 @@ class PortVisitor extends BaseVisitor {
                     mergeStrategy = metadata.mergeStrategy;
                 if (metadata.hidden)
                     hidden = true;
+                if (metadata.customMetadata) {
+                    customMetadata = { ...customMetadata, ...metadata.customMetadata };
+                }
             }
         }
         if (ctx.descriptionClause) {
@@ -263,6 +280,7 @@ class PortVisitor extends BaseVisitor {
             ...(mergeStrategy && { mergeStrategy }),
             ...(hidden && { hidden }),
             ...(description && { description }),
+            ...(customMetadata && { customMetadata }),
         };
     }
     outputPort(ctx) {
@@ -276,6 +294,7 @@ class PortVisitor extends BaseVisitor {
             scope = this.visit(ctx.scopeClause);
         }
         let hidden;
+        let customMetadata;
         if (ctx.metadataBracket) {
             // Handle multiple metadata brackets (e.g., [order:1] [placement:TOP])
             for (const bracket of ctx.metadataBracket) {
@@ -288,6 +307,9 @@ class PortVisitor extends BaseVisitor {
                     dataType = metadata.dataType;
                 if (metadata.hidden)
                     hidden = true;
+                if (metadata.customMetadata) {
+                    customMetadata = { ...customMetadata, ...metadata.customMetadata };
+                }
             }
         }
         if (ctx.descriptionClause) {
@@ -302,6 +324,7 @@ class PortVisitor extends BaseVisitor {
             ...(dataType && { dataType }),
             ...(hidden && { hidden }),
             ...(description && { description }),
+            ...(customMetadata && { customMetadata }),
         };
     }
     stepPort(ctx) {
@@ -325,6 +348,7 @@ class PortVisitor extends BaseVisitor {
         let dataType;
         let mergeStrategy;
         let hidden;
+        let customMetadata;
         if (ctx.orderAttr) {
             for (const attr of ctx.orderAttr) {
                 order = this.visit(attr);
@@ -348,7 +372,14 @@ class PortVisitor extends BaseVisitor {
         if (ctx.hiddenAttr) {
             hidden = true;
         }
-        return { order, placement, dataType, mergeStrategy, hidden };
+        if (ctx.customAttr) {
+            customMetadata = customMetadata || {};
+            for (const attr of ctx.customAttr) {
+                const { key, value } = this.visit(attr);
+                customMetadata[key] = value;
+            }
+        }
+        return { order, placement, dataType, mergeStrategy, hidden, customMetadata };
     }
     orderAttr(ctx) {
         return parseInt(ctx.orderValue[0].image, 10);
@@ -365,6 +396,31 @@ class PortVisitor extends BaseVisitor {
     mergeStrategyAttr(ctx) {
         return ctx.mergeStrategyValue[0].image;
     }
+    customAttr(ctx) {
+        const key = ctx.customKey[0].image;
+        let value;
+        if (ctx.customStrVal) {
+            // Remove quotes from string literal
+            const raw = ctx.customStrVal[0].image;
+            value = raw.slice(1, -1);
+        }
+        else if (ctx.customTrue) {
+            value = true;
+        }
+        else if (ctx.customFalse) {
+            value = false;
+        }
+        else if (ctx.customIntVal) {
+            value = parseInt(ctx.customIntVal[0].image, 10);
+        }
+        else if (ctx.customIdVal) {
+            value = ctx.customIdVal[0].image;
+        }
+        else {
+            value = '';
+        }
+        return { key, value };
+    }
     descriptionClause(ctx) {
         if (ctx.Identifier) {
             return ctx.Identifier.map((token) => token.image).join(' ');

package/dist/cli/flow-weaver.mjs

@@ -9671,7 +9671,7 @@ var VERSION;
 var init_generated_version = __esm({
   "src/generated-version.ts"() {
     "use strict";
-    VERSION = "0.17.9";
+    VERSION = "0.17.11";
   }
 });
 
@@ -31902,7 +31902,8 @@ var init_port_parser = __esm({
               { ALT: () => this.SUBRULE(this.placementAttr) },
               { ALT: () => this.SUBRULE(this.typeAttr) },
               { ALT: () => this.SUBRULE(this.mergeStrategyAttr) },
-              { ALT: () => this.SUBRULE(this.hiddenAttr) }
+              { ALT: () => this.SUBRULE(this.hiddenAttr) },
+              { ALT: () => this.SUBRULE(this.customAttr) }
             ]);
           }
         });
@@ -31936,6 +31937,18 @@ var init_port_parser = __esm({
       hiddenAttr = this.RULE("hiddenAttr", () => {
         this.CONSUME(HiddenKeyword);
       });
+      // customAttr: key:value pairs for arbitrary metadata (e.g., artifactPath:"dist/")
+      customAttr = this.RULE("customAttr", () => {
+        this.CONSUME(Identifier, { LABEL: "customKey" });
+        this.CONSUME(Colon);
+        this.OR([
+          { ALT: () => this.CONSUME(StringLiteral, { LABEL: "customStrVal" }) },
+          { ALT: () => this.CONSUME(TrueKeyword, { LABEL: "customTrue" }) },
+          { ALT: () => this.CONSUME(FalseKeyword, { LABEL: "customFalse" }) },
+          { ALT: () => this.CONSUME2(Identifier, { LABEL: "customIdVal" }) },
+          { ALT: () => this.CONSUME(Integer, { LABEL: "customIntVal" }) }
+        ]);
+      });
       // - description text
       // Note: We just consume the dash here. The actual description text is extracted
       // from the raw input in parsePortLine() to handle special characters like &, :, etc.
@@ -32022,6 +32035,7 @@ var init_port_parser = __esm({
           scope = this.visit(ctx.scopeClause);
         }
         let hidden;
+        let customMetadata;
         if (ctx.metadataBracket) {
           for (const bracket of ctx.metadataBracket) {
             const metadata = this.visit(bracket);
@@ -32030,6 +32044,9 @@ var init_port_parser = __esm({
             if (metadata.dataType !== void 0) dataType = metadata.dataType;
             if (metadata.mergeStrategy !== void 0) mergeStrategy = metadata.mergeStrategy;
             if (metadata.hidden) hidden = true;
+            if (metadata.customMetadata) {
+              customMetadata = { ...customMetadata, ...metadata.customMetadata };
+            }
           }
         }
         if (ctx.descriptionClause) {
@@ -32046,7 +32063,8 @@ var init_port_parser = __esm({
           ...dataType && { dataType },
           ...mergeStrategy && { mergeStrategy },
           ...hidden && { hidden },
-          ...description && { description }
+          ...description && { description },
+          ...customMetadata && { customMetadata }
         };
       }
       outputPort(ctx) {
@@ -32060,6 +32078,7 @@ var init_port_parser = __esm({
           scope = this.visit(ctx.scopeClause);
         }
         let hidden;
+        let customMetadata;
         if (ctx.metadataBracket) {
           for (const bracket of ctx.metadataBracket) {
             const metadata = this.visit(bracket);
@@ -32067,6 +32086,9 @@ var init_port_parser = __esm({
             if (metadata.placement !== void 0) placement = metadata.placement;
             if (metadata.dataType !== void 0) dataType = metadata.dataType;
             if (metadata.hidden) hidden = true;
+            if (metadata.customMetadata) {
+              customMetadata = { ...customMetadata, ...metadata.customMetadata };
+            }
           }
         }
         if (ctx.descriptionClause) {
@@ -32080,7 +32102,8 @@ var init_port_parser = __esm({
           ...placement && { placement },
           ...dataType && { dataType },
           ...hidden && { hidden },
-          ...description && { description }
+          ...description && { description },
+          ...customMetadata && { customMetadata }
         };
       }
       stepPort(ctx) {
@@ -32104,6 +32127,7 @@ var init_port_parser = __esm({
         let dataType;
         let mergeStrategy;
         let hidden;
+        let customMetadata;
         if (ctx.orderAttr) {
           for (const attr of ctx.orderAttr) {
             order = this.visit(attr);
@@ -32127,7 +32151,14 @@ var init_port_parser = __esm({
         if (ctx.hiddenAttr) {
           hidden = true;
         }
-        return { order, placement, dataType, mergeStrategy, hidden };
+        if (ctx.customAttr) {
+          customMetadata = customMetadata || {};
+          for (const attr of ctx.customAttr) {
+            const { key, value: value2 } = this.visit(attr);
+            customMetadata[key] = value2;
+          }
+        }
+        return { order, placement, dataType, mergeStrategy, hidden, customMetadata };
       }
       orderAttr(ctx) {
         return parseInt(ctx.orderValue[0].image, 10);
@@ -32144,6 +32175,25 @@ var init_port_parser = __esm({
       mergeStrategyAttr(ctx) {
         return ctx.mergeStrategyValue[0].image;
       }
+      customAttr(ctx) {
+        const key = ctx.customKey[0].image;
+        let value2;
+        if (ctx.customStrVal) {
+          const raw = ctx.customStrVal[0].image;
+          value2 = raw.slice(1, -1);
+        } else if (ctx.customTrue) {
+          value2 = true;
+        } else if (ctx.customFalse) {
+          value2 = false;
+        } else if (ctx.customIntVal) {
+          value2 = parseInt(ctx.customIntVal[0].image, 10);
+        } else if (ctx.customIdVal) {
+          value2 = ctx.customIdVal[0].image;
+        } else {
+          value2 = "";
+        }
+        return { key, value: value2 };
+      }
       descriptionClause(ctx) {
         if (ctx.Identifier) {
           return ctx.Identifier.map((token) => token.image).join(" ");
@@ -34219,7 +34269,7 @@ var init_jsdoc_parser = __esm({
         if (!result) {
           return;
         }
-        const { name, defaultValue, isOptional, scope, order, mergeStrategy, hidden, description } = result;
+        const { name, defaultValue, isOptional, scope, order, mergeStrategy, hidden, description, customMetadata } = result;
         let type2;
         let tsType;
         const isScopedStepInput = scope && isScopedMandatoryPort(name);
@@ -34280,7 +34330,9 @@ var init_jsdoc_parser = __esm({
           ...scope && { scope },
           ...mergeStrategy && { mergeStrategy },
           ...hidden && { hidden },
-          ...order !== void 0 && { metadata: { order } },
+          ...(order !== void 0 || customMetadata) && {
+            metadata: { ...order !== void 0 && { order }, ...customMetadata }
+          },
           ...tsType && { tsType }
         };
       }
@@ -34294,7 +34346,7 @@ var init_jsdoc_parser = __esm({
         if (!result) {
           return;
         }
-        const { name, scope, order, hidden, description } = result;
+        const { name, scope, order, hidden, description, customMetadata } = result;
         let type2;
         let tsType;
         const isScopedStepOutput = scope && isScopedMandatoryPort(name);
@@ -34348,7 +34400,9 @@ var init_jsdoc_parser = __esm({
           label: description?.trim(),
           ...scope && { scope },
           ...hidden && { hidden },
-          ...order !== void 0 && { metadata: { order } },
+          ...(order !== void 0 || customMetadata) && {
+            metadata: { ...order !== void 0 && { order }, ...customMetadata }
+          },
           ...tsType && { tsType }
         };
       }
@@ -34386,7 +34440,7 @@ var init_jsdoc_parser = __esm({
         if (!result) {
           return;
         }
-        const { name, order, description } = result;
+        const { name, order, description, customMetadata } = result;
         let type2 = "ANY";
         if (isSuccessPort(name) || isFailurePort(name)) {
           type2 = "STEP";
@@ -34407,7 +34461,9 @@ var init_jsdoc_parser = __esm({
         config2.returnPorts[name] = {
           dataType: type2,
           label: description?.trim(),
-          ...order !== void 0 && { metadata: { order } }
+          ...(order !== void 0 || customMetadata) && {
+            metadata: { ...order !== void 0 && { order }, ...customMetadata }
+          }
         };
       }
       /**
@@ -37833,7 +37889,7 @@ function darkenHex(hex, amount) {
   const nb = Math.round(b * (1 - amount));
   return `#${nr.toString(16).padStart(2, "0")}${ng.toString(16).padStart(2, "0")}${nb.toString(16).padStart(2, "0")}`;
 }
-var DARK_PORT_COLORS, LIGHT_PORT_COLORS, DARK_FAILURE_COLOR, LIGHT_FAILURE_COLOR, NODE_VARIANT_COLORS, DARK_PALETTE, LIGHT_PALETTE, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, VALID_NODE_ICONS;
+var DARK_PORT_COLORS, LIGHT_PORT_COLORS, DARK_FAILURE_COLOR, LIGHT_FAILURE_COLOR, NODE_DEFAULT_COLOR, NODE_VARIANT_COLORS, DARK_PALETTE, LIGHT_PALETTE, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, VALID_NODE_ICONS;
 var init_theme = __esm({
   "src/diagram/theme.ts"() {
     "use strict";
@@ -37875,6 +37931,7 @@ var init_theme = __esm({
     };
     DARK_FAILURE_COLOR = "#ff4f4f";
     LIGHT_FAILURE_COLOR = "#e34646";
+    NODE_DEFAULT_COLOR = "#334155";
     NODE_VARIANT_COLORS = {
       blue: { border: "#548ce3", darkBorder: "#5e9eff" },
       // blue-shade-2 / blue-dark-shade-1
@@ -37882,6 +37939,8 @@ var init_theme = __esm({
       // purple-shade-2 / purple-dark-shade-1
       cyan: { border: "#63ccc4", darkBorder: "#6fe5dc" },
       // cyan-shade-2 / cyan-dark-shade-1
+      teal: { border: "#63ccc4", darkBorder: "#6fe5dc" },
+      // alias for cyan
       orange: { border: "#e3732d", darkBorder: "#ff8133" },
       // orange-shade-2 / orange-dark-shade-1
       pink: { border: "#e349c2", darkBorder: "#ff52da" },
@@ -37890,10 +37949,8 @@ var init_theme = __esm({
       // green-shade-2 / green-dark-shade-1
       red: { border: "#e34646", darkBorder: "#ff4f4f" },
       // red-shade-2 / red-dark-shade-1
-      yellow: { border: "#e3a82b", darkBorder: "#ffbd30" },
+      yellow: { border: "#e3a82b", darkBorder: "#ffbd30" }
       // yellow-shade-2 / yellow-dark-shade-1
-      teal: { border: "#3db0a8", darkBorder: "#4dc7be" }
-      // teal-shade-2 / teal-dark-shade-1
     };
     DARK_PALETTE = {
       background: "#202139",
@@ -50796,7 +50853,7 @@ function buildDiagramGraph(ast, options = {}) {
   diagramNodes.set("Start", {
     id: "Start",
     label: "Start",
-    color: "#334155",
+    color: NODE_DEFAULT_COLOR,
     icon: "startNode",
     isVirtual: true,
     inputs: [],
@@ -50819,7 +50876,7 @@ function buildDiagramGraph(ast, options = {}) {
   diagramNodes.set("Exit", {
     id: "Exit",
     label: "Exit",
-    color: "#334155",
+    color: NODE_DEFAULT_COLOR,
     icon: "exitNode",
     isVirtual: true,
     inputs: exitInputs,
@@ -51125,7 +51182,7 @@ function filterNonScopedPorts(ports) {
   return result;
 }
 function resolveNodeColor(color, theme = "dark") {
-  if (!color) return "#334155";
+  if (!color) return NODE_DEFAULT_COLOR;
   const variant = NODE_VARIANT_COLORS[color];
   if (variant) return theme === "dark" ? variant.darkBorder : variant.border;
   return color;
@@ -51834,12 +51891,12 @@ function renderScopeConnection(parts2, conn, allConnections, parentNodeId) {
   );
 }
 function renderNodeBody(parts2, node, theme, indent) {
-  const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+  const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
   parts2.push(
     `${indent}<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`
   );
   const iconPath = NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
-  const iconColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+  const iconColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
   const iconSize = 40;
   const iconX = node.x + (node.width - iconSize) / 2;
   const iconY = node.y + (node.height - iconSize) / 2;
@@ -51851,7 +51908,7 @@ function renderNode(node, theme, themeName, allConnections) {
   const parts2 = [];
   parts2.push(`  <g data-node-id="${escapeXml(node.id)}">`);
   if (node.scopeChildren && node.scopeChildren.length > 0) {
-    const strokeColor = node.color !== "#334155" ? node.color : theme.nodeIconColor;
+    const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     parts2.push(
       `    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`
     );
@@ -51898,7 +51955,7 @@ function renderNodeLabel(parts2, node, theme) {
   const labelAnchor = isScoped ? "start" : "middle";
   parts2.push(`    <g data-label-for="${escapeXml(node.id)}">`);
   parts2.push(`      <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`);
-  parts2.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== "#334155" ? node.color : theme.labelColor}">${labelText}</text>`);
+  parts2.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== NODE_DEFAULT_COLOR ? node.color : theme.labelColor}">${labelText}</text>`);
   parts2.push(`    </g>`);
 }
 function renderPortLabelsForNode(parts2, node, theme, themeName, showPortLabels) {
@@ -105820,7 +105877,7 @@ function displayInstalledPackage(pkg) {
 // src/cli/index.ts
 init_logger();
 init_error_utils();
-var version2 = true ? "0.17.9" : "0.0.0-dev";
+var version2 = true ? "0.17.11" : "0.0.0-dev";
 var program2 = new Command();
 program2.name("flow-weaver").description("Flow Weaver Annotations - Compile and validate workflow files").option("-v, --version", "Output the current version").option("--no-color", "Disable colors").option("--color", "Force colors").on("option:version", () => {
   logger.banner(version2);

package/dist/diagram/geometry.js

@@ -1,6 +1,6 @@
 import { isExecutePort, isSuccessPort, isFailurePort, SCOPED_PORT_NAMES, isScopedStartPort, isScopedSuccessPort, isScopedFailurePort } from '../constants.js';
 import { assignImplicitPortOrders } from '../utils/port-ordering.js';
-import { getPortColor, NODE_VARIANT_COLORS, TYPE_ABBREVIATIONS } from './theme.js';
+import { getPortColor, NODE_VARIANT_COLORS, NODE_DEFAULT_COLOR, TYPE_ABBREVIATIONS } from './theme.js';
 import { layoutWorkflow } from './layout.js';
 import { calculateOrthogonalPathSafe, TrackAllocator } from './orthogonal-router.js';
 // ---- Constants (matching React component-node) ----
@@ -707,7 +707,7 @@ export function buildDiagramGraph(ast, options = {}) {
     diagramNodes.set('Start', {
         id: 'Start',
         label: 'Start',
-        color: '#334155',
+        color: NODE_DEFAULT_COLOR,
         icon: 'startNode',
         isVirtual: true,
         inputs: [],
@@ -731,7 +731,7 @@ export function buildDiagramGraph(ast, options = {}) {
     diagramNodes.set('Exit', {
         id: 'Exit',
         label: 'Exit',
-        color: '#334155',
+        color: NODE_DEFAULT_COLOR,
         icon: 'exitNode',
         isVirtual: true,
         inputs: exitInputs,
@@ -1098,7 +1098,7 @@ function filterNonScopedPorts(ports) {
 }
 function resolveNodeColor(color, theme = 'dark') {
     if (!color)
-        return '#334155';
+        return NODE_DEFAULT_COLOR;
     const variant = NODE_VARIANT_COLORS[color];
     if (variant)
         return theme === 'dark' ? variant.darkBorder : variant.border;

package/dist/diagram/renderer.js

@@ -1,4 +1,4 @@
-import { getTheme, getPortColor, getPortRingColor, TYPE_ABBREVIATIONS, NODE_ICON_PATHS } from './theme.js';
+import { getTheme, getPortColor, getPortRingColor, TYPE_ABBREVIATIONS, NODE_ICON_PATHS, NODE_DEFAULT_COLOR } from './theme.js';
 import { PORT_RADIUS, BORDER_RADIUS, LABEL_HEIGHT, LABEL_GAP, SCOPE_PORT_COLUMN, measureText } from './geometry.js';
 function escapeXml(str) {
     return str.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
@@ -113,10 +113,10 @@ function renderScopeConnection(parts, conn, allConnections, parentNodeId) {
 // ---- Node rendering ----
 /** Render node body rect + icon */
 function renderNodeBody(parts, node, theme, indent) {
-    const strokeColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+    const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     parts.push(`${indent}<rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`);
     const iconPath = NODE_ICON_PATHS[node.icon] ?? NODE_ICON_PATHS.code;
-    const iconColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+    const iconColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
     const iconSize = 40;
     const iconX = node.x + (node.width - iconSize) / 2;
     const iconY = node.y + (node.height - iconSize) / 2;
@@ -126,8 +126,8 @@ function renderNode(node, theme, themeName, allConnections) {
     const parts = [];
     parts.push(`  <g data-node-id="${escapeXml(node.id)}">`);
     if (node.scopeChildren && node.scopeChildren.length > 0) {
-        // Scoped node: body rect only (no icon), then scope internals
-        const strokeColor = node.color !== '#334155' ? node.color : theme.nodeIconColor;
+        // Scoped node: body rect only (icon omitted — children occupy the inner area)
+        const strokeColor = node.color !== NODE_DEFAULT_COLOR ? node.color : theme.nodeIconColor;
         parts.push(`    <rect x="${node.x}" y="${node.y}" width="${node.width}" height="${node.height}" rx="${BORDER_RADIUS}" fill="${theme.nodeFill}" stroke="${strokeColor}" stroke-width="2" filter="url(#node-shadow)"/>`);
         renderScopedContent(parts, node, theme, themeName, allConnections);
     }
@@ -178,7 +178,7 @@ function renderNodeLabel(parts, node, theme) {
     const labelAnchor = isScoped ? 'start' : 'middle';
     parts.push(`    <g data-label-for="${escapeXml(node.id)}">`);
     parts.push(`      <rect x="${labelBgX}" y="${labelBgY}" width="${labelBgWidth}" height="${labelBgHeight}" rx="6" fill="${theme.labelBadgeFill}" opacity="0.8"/>`);
-    parts.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== '#334155' ? node.color : theme.labelColor}">${labelText}</text>`);
+    parts.push(`      <text class="node-label" x="${labelTextX}" y="${labelBgY + labelBgHeight / 2 + 6}" text-anchor="${labelAnchor}" fill="${node.color !== NODE_DEFAULT_COLOR ? node.color : theme.labelColor}">${labelText}</text>`);
     parts.push(`    </g>`);
 }
 /** Render port labels for a node if showPortLabels is enabled */

package/dist/diagram/theme.d.ts

@@ -1,5 +1,6 @@
 import type { TDataType } from '../ast/types.js';
 import type { ThemePalette } from './types.js';
+export declare const NODE_DEFAULT_COLOR = "#334155";
 export declare const NODE_VARIANT_COLORS: Record<string, {
     border: string;
     darkBorder: string;

package/dist/diagram/theme.js

@@ -26,16 +26,17 @@ const LIGHT_FAILURE_COLOR = '#e34646'; // red-shade-2
 // ---- Node theme variant colors ----
 // Dark: border = X-dark-shade-1 (base), icon = X-dark-shade-3
 // Light: border = X-shade-2
+export const NODE_DEFAULT_COLOR = '#334155';
 export const NODE_VARIANT_COLORS = {
     blue: { border: '#548ce3', darkBorder: '#5e9eff' }, // blue-shade-2 / blue-dark-shade-1
     purple: { border: '#9f5fe3', darkBorder: '#b36bff' }, // purple-shade-2 / purple-dark-shade-1
     cyan: { border: '#63ccc4', darkBorder: '#6fe5dc' }, // cyan-shade-2 / cyan-dark-shade-1
+    teal: { border: '#63ccc4', darkBorder: '#6fe5dc' }, // alias for cyan
     orange: { border: '#e3732d', darkBorder: '#ff8133' }, // orange-shade-2 / orange-dark-shade-1
     pink: { border: '#e349c2', darkBorder: '#ff52da' }, // pink-shade-2 / pink-dark-shade-1
     green: { border: '#0ec850', darkBorder: '#10e15a' }, // green-shade-2 / green-dark-shade-1
     red: { border: '#e34646', darkBorder: '#ff4f4f' }, // red-shade-2 / red-dark-shade-1
     yellow: { border: '#e3a82b', darkBorder: '#ffbd30' }, // yellow-shade-2 / yellow-dark-shade-1
-    teal: { border: '#3db0a8', darkBorder: '#4dc7be' }, // teal-shade-2 / teal-dark-shade-1
 };
 // ---- Theme palettes (exact values from token system) ----
 const DARK_PALETTE = {

package/dist/editor-completions/annotationValues.js

@@ -100,7 +100,7 @@ const ANNOTATION_VALUES = {
         },
         {
             label: 'teal',
-            detail: 'Teal node color',
+            detail: 'Teal node color (alias for cyan)',
             insertText: 'teal',
             insertTextFormat: 'plain',
             kind: 'value',

package/dist/generated-version.d.ts

@@ -1,2 +1,2 @@
-export declare const VERSION = "0.17.9";
+export declare const VERSION = "0.17.11";
 //# sourceMappingURL=generated-version.d.ts.map

package/dist/generated-version.js

@@ -1,3 +1,3 @@
 // Auto-generated by scripts/generate-version.ts — do not edit manually
-export const VERSION = '0.17.9';
+export const VERSION = '0.17.11';
 //# sourceMappingURL=generated-version.js.map

package/dist/jsdoc-parser.js

@@ -522,7 +522,7 @@ export class JSDocParser {
         if (!result) {
             return;
         }
-        const { name, defaultValue, isOptional, scope, order, mergeStrategy, hidden, description } = result;
+        const { name, defaultValue, isOptional, scope, order, mergeStrategy, hidden, description, customMetadata } = result;
         // Infer type from signature or scope callback return type
         let type;
         let tsType;
@@ -599,7 +599,9 @@ export class JSDocParser {
             ...(scope && { scope }),
             ...(mergeStrategy && { mergeStrategy: mergeStrategy }),
             ...(hidden && { hidden }),
-            ...(order !== undefined && { metadata: { order } }),
+            ...((order !== undefined || customMetadata) && {
+                metadata: { ...(order !== undefined && { order }), ...customMetadata },
+            }),
             ...(tsType && { tsType }),
         };
     }
@@ -613,7 +615,7 @@ export class JSDocParser {
         if (!result) {
             return;
         }
-        const { name, scope, order, hidden, description } = result;
+        const { name, scope, order, hidden, description, customMetadata } = result;
         // Infer type from return type or scope callback parameter
         let type;
         let tsType;
@@ -683,7 +685,9 @@ export class JSDocParser {
             label: description?.trim(),
             ...(scope && { scope }),
             ...(hidden && { hidden }),
-            ...(order !== undefined && { metadata: { order } }),
+            ...((order !== undefined || customMetadata) && {
+                metadata: { ...(order !== undefined && { order }), ...customMetadata },
+            }),
             ...(tsType && { tsType }),
         };
     }
@@ -727,7 +731,7 @@ export class JSDocParser {
         if (!result) {
             return;
         }
-        const { name, order, description } = result;
+        const { name, order, description, customMetadata } = result;
         // Infer type from return type signature
         let type = 'ANY';
         if (isSuccessPort(name) || isFailurePort(name)) {
@@ -753,7 +757,9 @@ export class JSDocParser {
         config.returnPorts[name] = {
             dataType: type,
             label: description?.trim(),
-            ...(order !== undefined && { metadata: { order } }),
+            ...((order !== undefined || customMetadata) && {
+                metadata: { ...(order !== undefined && { order }), ...customMetadata },
+            }),
         };
     }
     /**

package/docs/reference/advanced-annotations.md

@@ -481,7 +481,7 @@ These annotations go on `@flowWeaver nodeType` blocks:
 | `@name` | Override display name | `@name MyCustomName` |
 | `@label` | Human-readable label | `@label Fetch with Timeout` |
 | `@description` | Node description | `@description Validates expense data` |
-| `@color` | Custom color | `@color "#ff6b35"` |
+| `@color` | Custom color | `@color purple` or `@color "#ff6b35"` |
 | `@icon` | Custom icon | `@icon "database"` |
 | `@tag` | Visual tag/badge | `@tag async` or `@tag beta "Experimental"` |
 | `@scope` | Provides a named scope | `@scope processItem` |
@@ -491,6 +491,42 @@ These annotations go on `@flowWeaver nodeType` blocks:
 
 ---
 
+## Available Colors
+
+Named colors adapt to the diagram theme (dark/light). You can also pass any hex color directly (e.g. `@color "#ff6b35"`).
+
+`blue` · `purple` · `cyan` · `orange` · `pink` · `green` · `red` · `yellow` · `teal` (alias for cyan)
+
+## Available Icons
+
+Icons render inside the node body in SVG diagrams. Names correspond to Material Symbols (outlined, weight 500).
+
+**AI & ML:** `psychology` · `smartToy` · `autoAwesome` · `modelTraining` · `science` · `biotech`
+
+**Data & storage:** `database` · `dataObject` · `tableChart` · `token` · `storage` · `memory`
+
+**Cloud & network:** `api` · `webhook` · `cloudSync` · `cloudUpload` · `cloudDownload` · `dns` · `router` · `http` · `link`
+
+**Security & auth:** `key` · `shield` · `vpnKey` · `verified` · `security` · `policy` · `adminPanelSettings`
+
+**Logic & flow:** `altRoute` · `callSplit` · `callMerge` · `rule` · `filterAlt` · `repeat` · `sort`
+
+**Actions & status:** `bolt` · `build` · `rocketLaunch` · `send` · `sync` · `refresh`
+
+**Communication:** `notifications` · `email` · `campaign`
+
+**Scheduling:** `event` · `schedule` · `timer`
+
+**General tools:** `terminal` · `settings` · `tune` · `search` · `save` · `upload` · `download` · `edit` · `delete`
+
+**Status:** `checkCircle` · `error` · `warning` · `info` · `help` · `visibility`
+
+**Files:** `folder` · `description` · `attachFile`
+
+**Structural:** `code` (default) · `flow` (workflow nodes) · `startNode` · `exitNode`
+
+---
+
 ## Related Topics
 
 - [Concepts](concepts) — Core workflow fundamentals

package/docs/reference/concepts.md

@@ -137,6 +137,7 @@ Expression nodes are pure functions where:
   - Primitive/array return -> single output port
   - Object return `{ a, b }` -> one port per property
 - Best for: transformers, math, utilities, data mapping, async fetchers, API calls
+- Optional `@color` and `@icon` annotations customize the node's appearance in SVG diagrams (see `advanced-annotations` for available values)
 
 > **Start with expression mode.** Only switch to normal mode when you need to return data alongside a failure (error-with-data patterns) or for void side-effect functions. Expression nodes handle success/failure branching automatically — throw to trigger the `onFailure` path.
 

package/docs/reference/jsdoc-grammar.md

@@ -244,7 +244,7 @@ Multiple attribute brackets are allowed (zero or more). Attributes can be split
 @node myAdd Add [minimized, label: "Compact"]
 @node myAdd Add [pullExecution: trigger]
 @node myAdd Add [size: 200 150]
-@node myAdd Add [color: "#ff0000", icon: "math-plus"]
+@node myAdd Add [color: "red", icon: "database"]
 @node myAdd Add [tags: "math" "Math operation", "transform"]
 @node myAdd Add [position: 180 0]
 @node myAdd Add [label: "hi"] [color: "#f00"] [position: 360 0]

package/package.json

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