@synergenius/flow-weaver 0.9.2 → 0.9.4

package/dist/constants.d.ts

@@ -97,4 +97,10 @@ export declare function isScopedPort(portDef: {
     dataType: string;
     scope?: string;
 }): boolean;
+export declare const VALID_NODE_COLORS: readonly ["blue", "purple", "cyan", "orange", "pink", "green", "red", "yellow", "teal"];
+export type ValidNodeColor = (typeof VALID_NODE_COLORS)[number];
+export declare const KNOWN_NODETYPE_TAGS: Set<string>;
+export declare const KNOWN_WORKFLOW_TAGS: Set<string>;
+export declare const KNOWN_PATTERN_TAGS: Set<string>;
+export declare const STANDARD_JSDOC_TAGS: Set<string>;
 //# sourceMappingURL=constants.d.ts.map

package/dist/constants.js

@@ -122,4 +122,26 @@ export function isControlFlowPort(portName) {
 export function isScopedPort(portDef) {
     return portDef.dataType === "FUNCTION" && portDef.scope !== undefined;
 }
+// ── Valid annotation values ───────────────────────────────────────────
+export const VALID_NODE_COLORS = [
+    'blue', 'purple', 'cyan', 'orange', 'pink', 'green', 'red', 'yellow', 'teal',
+];
+// ── Known annotation tags per block type ──────────────────────────────
+export const KNOWN_NODETYPE_TAGS = new Set([
+    'flowWeaver', 'name', 'label', 'description', 'color', 'icon', 'tag',
+    'executeWhen', 'scope', 'expression', 'pullExecution', 'input', 'output', 'step',
+]);
+export const KNOWN_WORKFLOW_TAGS = new Set([
+    'flowWeaver', 'name', 'fwImport', 'description', 'strictTypes', 'autoConnect',
+    'node', 'position', 'connect', 'scope', 'map', 'path', 'fanOut', 'fanIn',
+    'coerce', 'trigger', 'cancelOn', 'retries', 'timeout', 'throttle', 'param',
+    'return', 'returns',
+]);
+export const KNOWN_PATTERN_TAGS = new Set([
+    'flowWeaver', 'name', 'description', 'node', 'position', 'connect', 'port',
+]);
+export const STANDARD_JSDOC_TAGS = new Set([
+    'example', 'see', 'deprecated', 'type', 'typedef', 'template',
+    'link', 'since', 'version', 'author',
+]);
 //# sourceMappingURL=constants.js.map

package/dist/diagram/geometry.js

@@ -744,7 +744,8 @@ export function buildDiagramGraph(ast, options = {}) {
     const allPositioned = [...diagramNodes.keys()].every(id => explicitPositions.has(id));
     const nonePositioned = ![...diagramNodes.keys()].some(id => explicitPositions.has(id));
     if (allPositioned) {
-        // All nodes have explicit positions — apply them as-is
+        // All nodes have explicit positions — apply them, then fix overlaps
+        // caused by scope expansion making nodes wider than the author anticipated.
         for (const [id, pos] of explicitPositions) {
             const node = diagramNodes.get(id);
             if (node) {
@@ -752,6 +753,7 @@ export function buildDiagramGraph(ast, options = {}) {
                 node.y = pos.y;
             }
         }
+        resolveHorizontalOverlaps(diagramNodes);
     }
     else if (nonePositioned) {
         // No positions — full auto-layout (original behavior)
@@ -762,6 +764,7 @@ export function buildDiagramGraph(ast, options = {}) {
         // Mixed — explicit positions + auto-layout for remaining nodes
         const { layers } = layoutWorkflow(ast);
         assignUnpositionedNodes(layers, diagramNodes, explicitPositions);
+        resolveHorizontalOverlaps(diagramNodes);
     }
     // Compute external port positions
     for (const node of diagramNodes.values()) {

package/dist/diagram/html-viewer.js

@@ -67,10 +67,10 @@ body {
 .nodes > g:hover ~ .show-port-labels .port-label,
 .nodes > g:hover ~ .show-port-labels .port-type-label { opacity: 1; }
 
-/* Connection hover & dimming */
-.connections path { transition: opacity 0.2s ease, stroke-width 0.15s ease; }
-.connections path:hover { stroke-width: 4; cursor: pointer; }
-body.node-active .connections path.dimmed { opacity: 0.15; }
+/* Connection hover & dimming (attribute selector covers both main and scope connections) */
+path[data-source] { transition: opacity 0.2s ease, stroke-width 0.15s ease; }
+path[data-source]:hover { stroke-width: 4; cursor: pointer; }
+body.node-active path[data-source].dimmed { opacity: 0.15; }
 
 /* Node hover glow */
 .nodes g[data-node-id]:hover > rect:first-of-type { filter: brightness(1.08); }
@@ -274,7 +274,7 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
 
   // Build adjacency: portId → array of connected portIds
   var portConnections = {};
-  content.querySelectorAll('.connections path').forEach(function(p) {
+  content.querySelectorAll('path[data-source]').forEach(function(p) {
     var src = p.getAttribute('data-source');
     var tgt = p.getAttribute('data-target');
     if (!src || !tgt) return;
@@ -371,7 +371,7 @@ body.node-active .connections path.dimmed { opacity: 0.15; }
     });
 
     // Connected paths
-    var allPaths = content.querySelectorAll('.connections path');
+    var allPaths = content.querySelectorAll('path[data-source]');
     var connectedPaths = [];
     var connectedNodes = new Set();
     allPaths.forEach(function(p) {

package/dist/diagram/theme.d.ts

@@ -17,4 +17,6 @@ export declare const TYPE_ABBREVIATIONS: Record<string, string>;
  * Icon names match the original React editor's TIconNameType keys.
  */
 export declare const NODE_ICON_PATHS: Record<string, string>;
+/** All valid icon names (keys of NODE_ICON_PATHS) */
+export declare const VALID_NODE_ICONS: ReadonlyArray<string>;
 //# sourceMappingURL=theme.d.ts.map

package/dist/diagram/theme.js

@@ -33,6 +33,9 @@ export const NODE_VARIANT_COLORS = {
     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 = {
@@ -176,6 +179,8 @@ export const NODE_ICON_PATHS = {
     description: 'M319-249.52h322v-62.63H319v62.63Zm0-170h322v-62.63H319v62.63Zm-96.85 345.5q-27.6 0-47.86-20.27-20.27-20.26-20.27-47.86v-675.7q0-27.7 20.27-48.03 20.26-20.34 47.86-20.34h361.48l222.59 222.59v521.48q0 27.6-20.34 47.86-20.33 20.27-48.03 20.27h-515.7Zm326.7-557.83v-186h-326.7v675.7h515.7v-489.7h-189Zm-326.7-186v186-186 675.7-675.7Z',
     attachFile: 'M737.33-324.39q0 105.46-74.69 177.91-74.69 72.46-180.26 72.46-105.58 0-180.35-72.46-74.77-72.45-74.77-177.85v-383.82q0-74.63 53.41-126.35 53.42-51.72 127.75-51.72 74.34 0 127.69 51.72 53.35 51.72 53.35 126.35v363.82q0 43.66-31.56 74.62-31.55 30.97-75.81 30.97-44.26 0-75.61-30.64t-31.35-74.95v-370h66.46v370q0 16.05 11.97 27.59t29.2 11.54q17.24 0 28.74-11.5 11.5-11.51 11.5-27.63v-363.58q.24-47.35-33.38-79.6-33.62-32.25-81.35-32.25-47.74 0-81.14 32.19-33.41 32.19-33.41 79.42v383.82q.24 77.83 55.57 130.96 55.33 53.13 133.62 53.13 77.86 0 133.03-53.16 55.17-53.17 54.93-130.93v-396.93h66.46v396.87Z',
 };
+/** All valid icon names (keys of NODE_ICON_PATHS) */
+export const VALID_NODE_ICONS = Object.keys(NODE_ICON_PATHS);
 // ---- Helpers ----
 function darkenHex(hex, amount) {
     const r = parseInt(hex.slice(1, 3), 16);

package/dist/editor-completions/annotationValues.js

@@ -122,6 +122,14 @@ const ANNOTATION_VALUES = {
             kind: 'value',
             sortOrder: 7,
         },
+        {
+            label: 'cyan',
+            detail: 'Cyan node color',
+            insertText: 'cyan',
+            insertTextFormat: 'plain',
+            kind: 'value',
+            sortOrder: 8,
+        },
     ],
 };
 /**

package/dist/friendly-errors.js

@@ -530,6 +530,98 @@ const errorMappers = {
             code: error.code,
         };
     },
+    // ── Annotation validation rules ──────────────────────────────────────
+    DUPLICATE_INSTANCE_ID(error) {
+        const quoted = extractQuoted(error.message);
+        const instanceId = quoted[0] || error.node || 'unknown';
+        return {
+            title: 'Duplicate Instance ID',
+            explanation: `Two @node declarations use the same ID '${instanceId}'. Each node instance needs a unique ID within its workflow.`,
+            fix: `Rename one of the '${instanceId}' instances to give it a unique ID.`,
+            code: error.code,
+        };
+    },
+    DUPLICATE_CONNECTION(error) {
+        return {
+            title: 'Duplicate Connection',
+            explanation: `The same connection is declared twice. ${error.message}`,
+            fix: `Remove the duplicate @connect annotation.`,
+            code: error.code,
+        };
+    },
+    INVALID_COLOR(error) {
+        const quoted = extractQuoted(error.message);
+        const color = quoted[1] || quoted[0] || 'unknown';
+        return {
+            title: 'Invalid Color',
+            explanation: `Color '${color}' is not a recognized node color. Check the spelling or use a valid color name.`,
+            fix: `Use one of the valid colors: blue, purple, cyan, orange, pink, green, red, yellow, teal.`,
+            code: error.code,
+        };
+    },
+    INVALID_ICON(error) {
+        const quoted = extractQuoted(error.message);
+        const icon = quoted[1] || quoted[0] || 'unknown';
+        return {
+            title: 'Invalid Icon',
+            explanation: `Icon '${icon}' is not a recognized node icon. Check the spelling.`,
+            fix: `Use a valid icon name from the icon set (e.g., database, code, flow, psychology, send).`,
+            code: error.code,
+        };
+    },
+    INVALID_PORT_TYPE(error) {
+        const quoted = extractQuoted(error.message);
+        const portName = quoted[0] || 'unknown';
+        const typeName = quoted[2] || quoted[1] || 'unknown';
+        return {
+            title: 'Invalid Port Type',
+            explanation: `Port '${portName}' has an unrecognized type '${typeName}'.`,
+            fix: `Use a valid port type: STRING, NUMBER, BOOLEAN, ARRAY, OBJECT, FUNCTION, ANY, or STEP.`,
+            code: error.code,
+        };
+    },
+    INVALID_PORT_CONFIG_REF(error) {
+        const quoted = extractQuoted(error.message);
+        const instanceId = quoted[0] || error.node || 'unknown';
+        const portName = quoted[1] || 'unknown';
+        return {
+            title: 'Invalid Port Config Reference',
+            explanation: `Instance '${instanceId}' references port '${portName}' in a portOrder or portLabel annotation, but this port doesn't exist on the node type.`,
+            fix: `Check the port name spelling, or remove the port configuration if the port was renamed or removed.`,
+            code: error.code,
+        };
+    },
+    INVALID_EXECUTE_WHEN(error) {
+        const quoted = extractQuoted(error.message);
+        const value = quoted[1] || quoted[0] || 'unknown';
+        return {
+            title: 'Invalid Execution Strategy',
+            explanation: `@executeWhen value '${value}' is not recognized.`,
+            fix: `Use one of: CONJUNCTION (all inputs), DISJUNCTION (any input), or CUSTOM (custom logic).`,
+            code: error.code,
+        };
+    },
+    SCOPE_EMPTY(error) {
+        const quoted = extractQuoted(error.message);
+        const scopeName = quoted[0] || 'unknown';
+        const nodeName = quoted[1] || error.node || 'unknown';
+        return {
+            title: 'Empty Scope',
+            explanation: `Scope '${scopeName}' on node '${nodeName}' has no child nodes declared inside it. The scope won't iterate over anything.`,
+            fix: `Add child nodes to the scope with @scope ${scopeName} [childId1, childId2], or remove the scope if it's not needed.`,
+            code: error.code,
+        };
+    },
+    SCOPE_INCONSISTENT(error) {
+        const quoted = extractQuoted(error.message);
+        const instanceId = quoted[0] || error.node || 'unknown';
+        return {
+            title: 'Scope Conflict',
+            explanation: `Instance '${instanceId}' is assigned to multiple scopes. A node can only belong to one scope at a time.`,
+            fix: `Remove '${instanceId}' from one of the conflicting @scope declarations.`,
+            code: error.code,
+        };
+    },
 };
 // ── Public API ─────────────────────────────────────────────────────────
 /**

package/dist/jsdoc-parser.js

@@ -3,8 +3,9 @@
  *
  * Parses @flowWeaver annotations from JSDoc comments.
  */
-import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort } from './constants.js';
+import { isExecutePort, isSuccessPort, isFailurePort, isScopedMandatoryPort, KNOWN_NODETYPE_TAGS, KNOWN_WORKFLOW_TAGS, KNOWN_PATTERN_TAGS, STANDARD_JSDOC_TAGS, } from './constants.js';
 import { inferDataTypeFromTS } from './type-mappings.js';
+import { findClosestMatches } from './utils/string-distance.js';
 import { parsePortLine, parseNodeLine, parseConnectLine, parsePositionLine, parseScopeLine, parseMapLine, parsePathLine, parseFanOutLine, parseFanInLine, parseCoerceLine, parseTriggerLine, parseCancelOnLine, parseThrottleLine, } from './chevrotain-parser/index.js';
 /**
  * Extract the type of a field from a callback's return type using ts-morph Type API.
@@ -154,10 +155,10 @@ export class JSDocParser {
                     config.description = comment.trim();
                     break;
                 case 'color':
-                    config.color = comment.trim();
+                    config.color = comment.trim().replace(/^["']|["']$/g, '');
                     break;
                 case 'icon':
-                    config.icon = comment.trim();
+                    config.icon = comment.trim().replace(/^["']|["']$/g, '');
                     break;
                 case 'tag':
                     config.tags = config.tags || [];
@@ -194,6 +195,18 @@ export class JSDocParser {
                 case 'step':
                     this.parseStepTag(tag, config, func, warnings);
                     break;
+                default:
+                    // D: Context validation - tags that belong to other block types
+                    if (tagName === 'param' || tagName === 'returns' || tagName === 'return') {
+                        warnings.push(`@${tagName} is for workflows, not node types. Use @input/@output instead.`);
+                    }
+                    else if (!KNOWN_NODETYPE_TAGS.has(tagName) && !STANDARD_JSDOC_TAGS.has(tagName)) {
+                        // C: Unknown tag detection with suggestions
+                        const suggestions = findClosestMatches(tagName, [...KNOWN_NODETYPE_TAGS]);
+                        const hint = suggestions.length > 0 ? ` Did you mean @${suggestions[0]}?` : '';
+                        warnings.push(`Unknown annotation @${tagName} in nodeType block.${hint}`);
+                    }
+                    break;
             }
         });
         return config;
@@ -310,6 +323,21 @@ export class JSDocParser {
                 case 'returns':
                     this.parseReturnTag(tag, config, func, warnings);
                     break;
+                default:
+                    // D: Context validation - tags that belong to other block types
+                    if (tagName === 'color' || tagName === 'icon' || tagName === 'tag') {
+                        warnings.push(`@${tagName} is for node types, not workflows. Use it on @flowWeaver nodeType instead.`);
+                    }
+                    else if (tagName === 'input' || tagName === 'output' || tagName === 'step') {
+                        warnings.push(`@${tagName} is for node types, not workflows. Use @param/@returns for workflows.`);
+                    }
+                    else if (!KNOWN_WORKFLOW_TAGS.has(tagName) && !STANDARD_JSDOC_TAGS.has(tagName)) {
+                        // C: Unknown tag detection with suggestions
+                        const suggestions = findClosestMatches(tagName, [...KNOWN_WORKFLOW_TAGS]);
+                        const hint = suggestions.length > 0 ? ` Did you mean @${suggestions[0]}?` : '';
+                        warnings.push(`Unknown annotation @${tagName} in workflow block.${hint}`);
+                    }
+                    break;
             }
         });
         return config;
@@ -365,6 +393,13 @@ export class JSDocParser {
                 case 'port':
                     this.parsePatternPortTag(tag, config, warnings);
                     break;
+                default:
+                    if (!KNOWN_PATTERN_TAGS.has(tagName) && !STANDARD_JSDOC_TAGS.has(tagName)) {
+                        const suggestions = findClosestMatches(tagName, [...KNOWN_PATTERN_TAGS]);
+                        const hint = suggestions.length > 0 ? ` Did you mean @${suggestions[0]}?` : '';
+                        warnings.push(`Unknown annotation @${tagName} in pattern block.${hint}`);
+                    }
+                    break;
             }
         });
         // Apply positions to instances
@@ -465,6 +500,10 @@ export class JSDocParser {
         // Check for STEP ports: execute OR scoped mandatory ports (success, failure with scope)
         const isScopedStepInput = scope && isScopedMandatoryPort(name);
         if (isExecutePort(name) || isScopedStepInput) {
+            // E: Warn if user explicitly specified a non-STEP type on a reserved port
+            if (result.dataType && result.dataType !== 'STEP') {
+                warnings.push(`Port "${name}" is a reserved control port; type will always be STEP.`);
+            }
             type = 'STEP';
         }
         else if (scope) {
@@ -518,6 +557,10 @@ export class JSDocParser {
             expression = label.substring('Expression:'.length).trim();
             label = undefined;
         }
+        // B: Duplicate port detection
+        if (config.inputs.hasOwnProperty(name)) {
+            warnings.push(`Duplicate @input "${name}". The second declaration will overwrite the first.`);
+        }
         config.inputs[name] = {
             type,
             defaultValue: defaultValue ? this.parseDefaultValue(defaultValue) : undefined,
@@ -547,6 +590,10 @@ export class JSDocParser {
         // Check for STEP ports: onSuccess/onFailure OR scoped mandatory ports (start with scope)
         const isScopedStepOutput = scope && isScopedMandatoryPort(name);
         if (isSuccessPort(name) || isFailurePort(name) || isScopedStepOutput) {
+            // E: Warn if user explicitly specified a non-STEP type on a reserved port
+            if (result.dataType && result.dataType !== 'STEP') {
+                warnings.push(`Port "${name}" is a reserved control port; type will always be STEP.`);
+            }
             type = 'STEP';
         }
         else if (scope) {
@@ -597,6 +644,10 @@ export class JSDocParser {
                 type = 'ANY';
             }
         }
+        // B: Duplicate port detection
+        if (config.outputs.hasOwnProperty(name)) {
+            warnings.push(`Duplicate @output "${name}". The second declaration will overwrite the first.`);
+        }
         config.outputs[name] = {
             type,
             label: description?.trim(),
@@ -658,8 +709,16 @@ export class JSDocParser {
             if (fieldMatch) {
                 type = inferDataTypeFromTS(fieldMatch[1].trim());
             }
+            else {
+                // G: Type inference fallback to ANY
+                warnings.push(`Could not infer type for @returns "${name}", defaulting to ANY.`);
+            }
         }
         config.returnPorts = config.returnPorts || {};
+        // B: Duplicate port detection
+        if (config.returnPorts.hasOwnProperty(name)) {
+            warnings.push(`Duplicate @returns "${name}". The second declaration will overwrite the first.`);
+        }
         config.returnPorts[name] = {
             dataType: type,
             label: description?.trim(),
@@ -698,9 +757,18 @@ export class JSDocParser {
                 if (fieldMatch) {
                     type = inferDataTypeFromTS(fieldMatch[1].trim());
                 }
+                else {
+                    // F: @param doesn't match any field in the params object
+                    // G: Type inference fallback to ANY
+                    warnings.push(`@param "${name}" does not match any field in the params object. Type defaults to ANY.`);
+                }
             }
         }
         config.startPorts = config.startPorts || {};
+        // B: Duplicate port detection
+        if (config.startPorts.hasOwnProperty(name)) {
+            warnings.push(`Duplicate @param "${name}". The second declaration will overwrite the first.`);
+        }
         config.startPorts[name] = {
             dataType: type,
             label: description?.trim(),

package/dist/validator.d.ts

@@ -96,6 +96,12 @@ export declare class WorkflowValidator {
      * 2. Scoped input ports (callback returns) have connections from inner nodes
      */
     private validateScopeTopology;
+    private validateDuplicateInstanceIds;
+    private validateDuplicateConnections;
+    private validateVisualAnnotations;
+    private validatePortTypes;
+    private validatePortConfigReferences;
+    private validateExecuteWhen;
     /**
      * Format a type for display in error messages.
      * Prefers the structural TypeScript type when available, falling back to the enum name.

package/dist/validator.js

@@ -1,7 +1,9 @@
-import { RESERVED_NODE_NAMES, isStartNode, isExitNode, isExecutePort, isReservedNodeName, } from './constants.js';
+import { RESERVED_NODE_NAMES, isStartNode, isExitNode, isExecutePort, isReservedNodeName, VALID_NODE_COLORS, EXECUTION_STRATEGIES, } from './constants.js';
 import { findClosestMatches } from './utils/string-distance.js';
 import { parseFunctionSignature } from './jsdoc-port-sync/signature-parser.js';
 import { checkTypeCompatibilityFromStrings } from './type-checker.js';
+import { isValidPortType } from './type-mappings.js';
+import { VALID_NODE_ICONS } from './diagram/theme.js';
 const DOCS_BASE = 'https://docs.flowweaver.dev/reference';
 /** Map error codes to the documentation page that explains how to fix them. */
 const ERROR_DOC_URLS = {
@@ -135,10 +137,12 @@ export class WorkflowValidator {
         // Structural validation
         this.validateStructure(workflow);
         this.validateDuplicateNodeNames(workflow);
+        this.validateDuplicateInstanceIds(workflow);
         this.validateMutableBindings(workflow);
         // Connection and node validation
         this.validateReservedNames(workflow, nodeTypeMap);
         this.validateConnections(workflow, instanceMap);
+        this.validateDuplicateConnections(workflow);
         this.validateNodeReferences(workflow, instanceMap);
         this.validateTypeCompatibility(workflow, instanceMap);
         this.validateRequiredInputs(workflow, instanceMap);
@@ -148,6 +152,10 @@ export class WorkflowValidator {
         this.validateCycles(workflow);
         this.validateMultipleInputConnections(workflow, instanceMap);
         this.validateAnnotationSignatureConsistency(workflow);
+        this.validateVisualAnnotations(workflow, instanceMap);
+        this.validatePortTypes(workflow);
+        this.validatePortConfigReferences(workflow, instanceMap);
+        this.validateExecuteWhen(workflow);
         this.validateScopeTopology(workflow, instanceMap);
         // Deduplicate cascading errors: if a node has UNKNOWN_NODE_TYPE,
         // suppress UNKNOWN_SOURCE_NODE, UNKNOWN_TARGET_NODE, and UNDEFINED_NODE
@@ -1029,6 +1037,25 @@ export class WorkflowValidator {
      * 2. Scoped input ports (callback returns) have connections from inner nodes
      */
     validateScopeTopology(workflow, instanceMap) {
+        // P: Scope consistency - check if any instance appears in multiple scope arrays
+        if (workflow.scopes) {
+            const instanceToScope = new Map();
+            for (const [scopeKey, childIds] of Object.entries(workflow.scopes)) {
+                for (const childId of childIds) {
+                    const existing = instanceToScope.get(childId);
+                    if (existing && existing !== scopeKey) {
+                        this.errors.push({
+                            type: 'error',
+                            code: 'SCOPE_INCONSISTENT',
+                            message: `Instance "${childId}" appears in multiple scopes: "${existing}" and "${scopeKey}". A node can only belong to one scope.`,
+                            node: childId,
+                            location: this.getInstanceLocation(workflow, childId),
+                        });
+                    }
+                    instanceToScope.set(childId, scopeKey);
+                }
+            }
+        }
         // Find all instances that have scoped ports
         for (const instance of workflow.instances) {
             const nodeType = instanceMap.get(instance.id);
@@ -1081,8 +1108,17 @@ export class WorkflowValidator {
                         childIds.push(child.id);
                     }
                 }
-                if (childIds.length === 0)
+                // O: Empty scope warning
+                if (childIds.length === 0) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'SCOPE_EMPTY',
+                        message: `Scope "${scopeName}" on node "${instance.id}" has no child nodes.`,
+                        node: instance.id,
+                        location: this.getInstanceLocation(workflow, instance.id),
+                    });
                     continue;
+                }
                 // Collect scoped connections (connections with scope tags)
                 const scopedConnections = workflow.connections.filter((conn) => (conn.from.scope === scopeName && conn.from.node === instance.id) ||
                     (conn.to.scope === scopeName && conn.to.node === instance.id) ||
@@ -1268,6 +1304,168 @@ export class WorkflowValidator {
             }
         }
     }
+    // ── H: Duplicate instance IDs ──────────────────────────────────────────
+    validateDuplicateInstanceIds(workflow) {
+        const seen = new Set();
+        for (const instance of workflow.instances) {
+            if (seen.has(instance.id)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'DUPLICATE_INSTANCE_ID',
+                    message: `Duplicate instance ID "${instance.id}" in workflow. Each @node must have a unique ID.`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+            seen.add(instance.id);
+        }
+    }
+    // ── I: Duplicate connections ──────────────────────────────────────────
+    validateDuplicateConnections(workflow) {
+        const seen = new Set();
+        for (const conn of workflow.connections) {
+            const key = `${conn.from.node}.${conn.from.port}->${conn.to.node}.${conn.to.port}`;
+            if (seen.has(key)) {
+                this.errors.push({
+                    type: 'error',
+                    code: 'DUPLICATE_CONNECTION',
+                    message: `Duplicate connection: ${key}`,
+                    connection: conn,
+                    location: this.getConnectionLocation(conn),
+                });
+            }
+            seen.add(key);
+        }
+    }
+    // ── J+K: Visual annotation validation ────────────────────────────────
+    validateVisualAnnotations(workflow, instanceMap) {
+        const validColors = VALID_NODE_COLORS;
+        const validIcons = VALID_NODE_ICONS;
+        // Check node type colors and icons (stored in visuals)
+        for (const nodeType of workflow.nodeTypes) {
+            const color = nodeType.visuals?.color;
+            const icon = nodeType.visuals?.icon;
+            if (color && !validColors.includes(color)) {
+                const suggestions = findClosestMatches(color, [...validColors]);
+                const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INVALID_COLOR',
+                    message: `Node type "${nodeType.functionName}" has invalid color "${color}".${hint} Valid colors: ${validColors.join(', ')}.`,
+                    node: nodeType.functionName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+            if (icon && !validIcons.includes(icon)) {
+                const suggestions = findClosestMatches(icon, [...validIcons]);
+                const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INVALID_ICON',
+                    message: `Node type "${nodeType.functionName}" has invalid icon "${icon}".${hint}`,
+                    node: nodeType.functionName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+        }
+        // Check instance-level color and icon overrides
+        for (const instance of workflow.instances) {
+            if (instance.config?.color && !validColors.includes(instance.config.color)) {
+                const suggestions = findClosestMatches(instance.config.color, [...validColors]);
+                const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INVALID_COLOR',
+                    message: `Instance "${instance.id}" has invalid color "${instance.config.color}".${hint} Valid colors: ${validColors.join(', ')}.`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+            if (instance.config?.icon && !validIcons.includes(instance.config.icon)) {
+                const suggestions = findClosestMatches(instance.config.icon, [...validIcons]);
+                const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INVALID_ICON',
+                    message: `Instance "${instance.id}" has invalid icon "${instance.config.icon}".${hint}`,
+                    node: instance.id,
+                    location: instance.sourceLocation,
+                });
+            }
+        }
+    }
+    // ── L: Port type validation ──────────────────────────────────────────
+    validatePortTypes(workflow) {
+        for (const nodeType of workflow.nodeTypes) {
+            for (const [portName, portDef] of Object.entries(nodeType.inputs)) {
+                if (!isValidPortType(portDef.dataType)) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'INVALID_PORT_TYPE',
+                        message: `Port "${portName}" on node type "${nodeType.functionName}" has invalid type "${portDef.dataType}".`,
+                        node: nodeType.functionName,
+                        location: nodeType.sourceLocation,
+                    });
+                }
+            }
+            for (const [portName, portDef] of Object.entries(nodeType.outputs)) {
+                if (!isValidPortType(portDef.dataType)) {
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'INVALID_PORT_TYPE',
+                        message: `Port "${portName}" on node type "${nodeType.functionName}" has invalid type "${portDef.dataType}".`,
+                        node: nodeType.functionName,
+                        location: nodeType.sourceLocation,
+                    });
+                }
+            }
+        }
+    }
+    // ── M: portOrder/portLabel reference validation ──────────────────────
+    validatePortConfigReferences(workflow, instanceMap) {
+        for (const instance of workflow.instances) {
+            const portConfigs = instance.config?.portConfigs;
+            if (!portConfigs)
+                continue;
+            const nodeType = instanceMap.get(instance.id);
+            if (!nodeType)
+                continue;
+            const allPorts = new Set([
+                ...Object.keys(nodeType.inputs),
+                ...Object.keys(nodeType.outputs),
+            ]);
+            for (const pc of portConfigs) {
+                if (!allPorts.has(pc.portName)) {
+                    const suggestions = findClosestMatches(pc.portName, [...allPorts]);
+                    const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                    this.warnings.push({
+                        type: 'warning',
+                        code: 'INVALID_PORT_CONFIG_REF',
+                        message: `Instance "${instance.id}" references port "${pc.portName}" in portConfig, but this port does not exist on node type "${instance.nodeType}".${hint}`,
+                        node: instance.id,
+                        location: instance.sourceLocation,
+                    });
+                }
+            }
+        }
+    }
+    // ── N: @executeWhen value validation ─────────────────────────────────
+    validateExecuteWhen(workflow) {
+        const validStrategies = Object.values(EXECUTION_STRATEGIES);
+        for (const nodeType of workflow.nodeTypes) {
+            if (nodeType.executeWhen && !validStrategies.includes(nodeType.executeWhen)) {
+                const suggestions = findClosestMatches(nodeType.executeWhen, validStrategies);
+                const hint = suggestions.length > 0 ? ` Did you mean "${suggestions[0]}"?` : '';
+                this.warnings.push({
+                    type: 'warning',
+                    code: 'INVALID_EXECUTE_WHEN',
+                    message: `Node type "${nodeType.functionName}" has invalid @executeWhen value "${nodeType.executeWhen}".${hint} Valid values: ${validStrategies.join(', ')}.`,
+                    node: nodeType.functionName,
+                    location: nodeType.sourceLocation,
+                });
+            }
+        }
+    }
     /**
      * Format a type for display in error messages.
      * Prefers the structural TypeScript type when available, falling back to the enum name.