@flowuent-org/diagramming-core 1.4.2 → 1.4.3

package/apps/diagramming/src/AutomationDiagramData.ts

@@ -276,6 +276,42 @@ export const automationDefaultNodes = [
     height: 150,
     measured: { width: 336, height: 150 },
   },
+  // =====================================
+  // Loop Node
+  // =====================================
+  {
+    id: 'loop-node',
+    type: 'AutomationLoopNode',
+    position: { x: 1100, y: 200 },
+    data: {
+      label: 'For Each Item',
+      description: 'Iterate over array items and run body steps for each',
+      headerText: 'For-each loop over array',
+      status: 'Ready',
+      parameters: {
+        arraySource: { type: 'previousStep' },
+        maxIterations: 100,
+        currentItemVariable: 'currentItem',
+        loopIndexVariable: 'loopIndex',
+      },
+      formData: {
+        nodeId: 'loop-node',
+        title: 'For Each Item',
+        type: 'loop',
+        arraySource: { type: 'previousStep' },
+        maxIterations: 100,
+        currentItemVariable: 'currentItem',
+        loopIndexVariable: 'loopIndex',
+      },
+      lastRun: 'Never',
+      backgroundColor: '#181C25',
+      textColor: '#ffffff',
+      borderColor: '#1e293b',
+    },
+    width: 336,
+    height: 150,
+    measured: { width: 336, height: 150 },
+  },
   {
     id: 'end-node',
     type: 'AutomationEndNode',
@@ -695,11 +731,11 @@ export const automationDefaultEdges = [
     },
   },
   {
-    id: 'edge-formatting-to-end',
+    id: 'edge-formatting-to-loop',
     source: 'data-formatting-node',
-    target: 'end-node',
-    sourceHandle: 'right',
-    targetHandle: 'left',
+    target: 'loop-node',
+    sourceHandle: 'right-source',
+    targetHandle: 'left-target',
     data: {
       label: '',
       type: 'flow',
@@ -713,6 +749,64 @@ export const automationDefaultEdges = [
       color: '#ffffff',
     },
   },
+  {
+    id: 'edge-loop-to-slack',
+    source: 'loop-node',
+    target: 'slack-node',
+    sourceHandle: 'loop',
+    targetHandle: 'left-target',
+    data: {
+      label: 'Loop body',
+      type: 'flow',
+    },
+    style: {
+      stroke: '#86EFAC',
+      strokeWidth: 2,
+    },
+    markerEnd: {
+      type: MarkerType.ArrowClosed,
+      color: '#86EFAC',
+    },
+  },
+  {
+    id: 'edge-slack-back-to-loop',
+    source: 'slack-node',
+    target: 'loop-node',
+    sourceHandle: 'right-source',
+    targetHandle: 'left-target',
+    data: {
+      label: 'Back to loop',
+      type: 'flow',
+    },
+    style: {
+      stroke: '#86EFAC',
+      strokeWidth: 2,
+      strokeDasharray: '5 5',
+    },
+    markerEnd: {
+      type: MarkerType.ArrowClosed,
+      color: '#86EFAC',
+    },
+  },
+  {
+    id: 'edge-loop-done-to-end',
+    source: 'loop-node',
+    target: 'end-node',
+    sourceHandle: 'done',
+    targetHandle: 'left-target',
+    data: {
+      label: 'Done',
+      type: 'flow',
+    },
+    style: {
+      stroke: '#9CA3AF',
+      strokeWidth: 2,
+    },
+    markerEnd: {
+      type: MarkerType.ArrowClosed,
+      color: '#9CA3AF',
+    },
+  },
   // =====================================
   // Slack Node Edge
   // =====================================

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowuent-org/diagramming-core",
-  "version": "1.4.2",
+  "version": "1.4.3",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/packages/diagrams/src/lib/components/automation/AutomationLoopNode.tsx

@@ -0,0 +1,105 @@
+import React from 'react';
+import { Box, Typography, Chip } from '@mui/material';
+import { LoopNodeIcon } from '../../icons';
+import {
+  AutomationNodeCard,
+  AutomationNodeCardData,
+} from './AutomationNodeCard';
+import { AutomationLoopNodeForm } from '../../types/automation-node-data-types';
+
+export interface AutomationLoopNodeData extends AutomationNodeCardData {
+  parameters?: {
+    arraySource?: AutomationLoopNodeForm['arraySource'];
+    maxIterations?: number;
+    currentItemVariable?: string;
+    loopIndexVariable?: string;
+    [key: string]: unknown;
+  };
+}
+
+export interface AutomationLoopNodeProps {
+  data: AutomationLoopNodeData;
+  selected?: boolean;
+}
+
+export const AutomationLoopNode: React.FC<AutomationLoopNodeProps> = ({
+  data,
+  selected,
+}) => {
+  const formData = (data.formData ?? {}) as Partial<AutomationLoopNodeForm>;
+  const arraySource =
+    data.parameters?.arraySource ?? formData.arraySource;
+  const maxIterations =
+    data.parameters?.maxIterations ?? formData.maxIterations ?? 100;
+  const currentItemVariable =
+    data.parameters?.currentItemVariable ??
+    formData.currentItemVariable ??
+    'currentItem';
+  const loopIndexVariable =
+    data.parameters?.loopIndexVariable ??
+    formData.loopIndexVariable ??
+    'loopIndex';
+
+  const sourceLabel =
+    arraySource?.type === 'variable'
+      ? arraySource.variableName ?? 'Unnamed variable'
+      : arraySource?.type === 'previousStep'
+        ? 'Previous step'
+        : 'Not configured';
+
+  return (
+    <AutomationNodeCard
+      data={data}
+      selected={selected}
+      icon={<LoopNodeIcon />}
+      aiAssistantTitle="Loop Node"
+      loopHandles
+      descriptionContent={
+        <Box sx={{ width: '100%' }}>
+          <Box sx={{ display: 'flex', alignItems: 'center', gap: 0.75, mb: 1 }}>
+            <Chip
+              size="small"
+              label={sourceLabel.toUpperCase()}
+              sx={{
+                height: 20,
+                fontSize: '10px',
+                fontWeight: 600,
+                color: '#86EFAC',
+                bgcolor: 'rgba(134, 239, 172, 0.12)',
+              }}
+            />
+            <Chip
+              size="small"
+              label={`MAX ${maxIterations}`}
+              sx={{
+                height: 20,
+                fontSize: '10px',
+                fontWeight: 600,
+                color: '#9CA3AF',
+                bgcolor: 'rgba(156, 163, 175, 0.12)',
+              }}
+            />
+          </Box>
+          <Typography
+            variant="body2"
+            sx={{ color: '#9CA3AF', fontSize: '12px', lineHeight: 1.4, mb: 0.5 }}
+          >
+            {arraySource
+              ? `For each item → ${currentItemVariable}, index → ${loopIndexVariable}`
+              : data.description}
+          </Typography>
+          <Box sx={{ display: 'flex', justifyContent: 'space-between', mt: 1.5, px: 0.5 }}>
+            <Typography variant="caption" sx={{ color: '#86EFAC', fontSize: '10px', fontWeight: 600 }}>
+              LOOP →
+            </Typography>
+            <Typography variant="caption" sx={{ color: '#9CA3AF', fontSize: '10px', fontWeight: 600 }}>
+              DONE →
+            </Typography>
+          </Box>
+        </Box>
+      }
+    />
+  );
+};
+
+export default AutomationLoopNode;

package/packages/diagrams/src/lib/components/automation/AutomationNodeCard.tsx

@@ -30,6 +30,7 @@ export interface AutomationNodeCardProps {
   headerText?: string;
   aiAssistantTitle?: string;
   branchHandles?: boolean;
+  loopHandles?: boolean;
   descriptionContent?: React.ReactNode;
 }
 
@@ -64,6 +65,7 @@ export const AutomationNodeCard: React.FC<AutomationNodeCardProps> = ({
   headerText,
   aiAssistantTitle,
   branchHandles = false,
+  loopHandles = false,
   descriptionContent,
 }) => {
   const { t } = useTranslation();
@@ -248,6 +250,29 @@ export const AutomationNodeCard: React.FC<AutomationNodeCardProps> = ({
             style={handleTargetStyle('right', selected)}
           />
         </>
+      ) : loopHandles ? (
+        <>
+          <Handle
+            type="source"
+            position={Position.Right}
+            id="loop"
+            className="connection-handle"
+            style={{ ...handleSourceStyle(selected), right: '-8px', top: '35%' }}
+          />
+          <Handle
+            type="source"
+            position={Position.Right}
+            id="done"
+            className="connection-handle"
+            style={{ ...handleSourceStyle(selected), right: '-8px', top: '65%' }}
+          />
+          <Handle
+            type="target"
+            position={Position.Right}
+            id="right-target"
+            style={handleTargetStyle('right', selected)}
+          />
+        </>
       ) : (
         <>
           <Handle

package/packages/diagrams/src/lib/components/automation/index.ts

@@ -51,6 +51,12 @@ export type {
   AutomationDecisionNodeData,
   AutomationDecisionNodeProps,
 } from './AutomationDecisionNode';
+// Loop / for-each node
+export { AutomationLoopNode } from './AutomationLoopNode';
+export type {
+  AutomationLoopNodeData,
+  AutomationLoopNodeProps,
+} from './AutomationLoopNode';
 // SMS node
 export { AutomationSmsNode } from './AutomationSmsNode';
 export type {

package/packages/diagrams/src/lib/icons/icons.tsx

@@ -299,6 +299,16 @@ export const DecisionNodeIcon: React.FC<SvgIconProps> = ({ size, color, style })
   </svg>
 );
 
+export const LoopNodeIcon: React.FC<SvgIconProps> = ({ size, color, style }) => (
+  <svg width="35" height="35" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg" style={style}>
+    <path d="M0 14C0 6.26801 6.26801 0 14 0C21.732 0 28 6.26801 28 14C28 21.732 21.732 28 14 28C6.26801 28 0 21.732 0 14Z" fill="#1E3A8A"/>
+    <path d="M17.5 9.5H11.5C10.3954 9.5 9.5 10.3954 9.5 11.5V13.5" stroke="#86EFAC" strokeLinecap="round" strokeLinejoin="round"/>
+    <path d="M10.5 18.5H16.5C17.6046 18.5 18.5 17.6046 18.5 16.5V14.5" stroke="#86EFAC" strokeLinecap="round" strokeLinejoin="round"/>
+    <path d="M9.5 13.5L7.5 11.5L9.5 9.5" stroke="#86EFAC" strokeLinecap="round" strokeLinejoin="round"/>
+    <path d="M18.5 14.5L20.5 16.5L18.5 18.5" stroke="#86EFAC" strokeLinecap="round" strokeLinejoin="round"/>
+  </svg>
+);
+
 export const SmsNodeIcon: React.FC<SvgIconProps> = ({ size, color, style }) => (
   <svg width="35" height="35" viewBox="0 0 28 28" fill="none" xmlns="http://www.w3.org/2000/svg" style={style}>
     <path d="M0 14C0 6.26801 6.26801 0 14 0C21.732 0 28 6.26801 28 14C28 21.732 21.732 28 14 28C6.26801 28 0 21.732 0 14Z" fill="#1E3A8A"/>

package/packages/diagrams/src/lib/icons/index.ts

@@ -23,6 +23,7 @@ export {
   FormattingNodeIcon,
   ApiNodeIcon,
   DecisionNodeIcon,
+  LoopNodeIcon,
   SmsNodeIcon,
   VoiceCallNodeIcon,
   SubWorkflowNodeIcon,

package/packages/diagrams/src/lib/types/automation-node-data-types.ts

@@ -3,7 +3,7 @@ export interface AutomationNodeFormData {
   nodeId: string;
   title: string;
   headerText?: string;
-  type: 'start' | 'api' | 'formatting' | 'end' | 'navigation' | 'decision' | 'sms' | 'voice-call' | 'workflow';
+  type: 'start' | 'api' | 'formatting' | 'end' | 'navigation' | 'decision' | 'loop' | 'sms' | 'voice-call' | 'workflow';
   isPinned?: boolean;
   isBlock?: boolean;
   blocks?: Array<{
@@ -203,6 +203,17 @@ export interface AutomationDecisionNodeForm extends AutomationNodeFormData {
   defaultBranch?: string;
 }
 
+export interface AutomationLoopNodeForm extends AutomationNodeFormData {
+  type: 'loop';
+  arraySource: {
+    type: 'previousStep' | 'variable';
+    variableName?: string;
+  };
+  maxIterations?: number;
+  currentItemVariable?: string;
+  loopIndexVariable?: string;
+}
+
 export interface AutomationSmsNodeForm extends AutomationNodeFormData {
   type: 'sms';
   recipientPhone: string;
@@ -256,6 +267,7 @@ export type AutomationNodeForm =
   | AutomationEndNodeForm
   | AutomationNavigationNodeForm
   | AutomationDecisionNodeForm
+  | AutomationLoopNodeForm
   | AutomationSmsNodeForm
   | AutomationVoiceCallNodeForm
   | AutomationWorkflowNodeForm;

package/packages/diagrams/src/lib/types/node-types.ts

@@ -15,6 +15,7 @@ import {
   AutomationInteractionNode,
   AutomationMonitoringNode,
   AutomationDecisionNode,
+  AutomationLoopNode,
   AutomationSmsNode,
   AutomationVoiceCallNode,
   AutomationWorkflowNode,
@@ -36,6 +37,7 @@ const nodeTypes = {
   AutomationInteractionNode,
   AutomationMonitoringNode,
   AutomationDecisionNode,
+  AutomationLoopNode,
   AutomationSmsNode,
   AutomationVoiceCallNode,
   AutomationWorkflowNode,

package/packages/diagrams/src/lib/utils/AutomationExecutionEngine.ts

@@ -5,7 +5,9 @@ import {
   AutomationApiNodeForm,
   AutomationFormattingNodeForm,
   AutomationEndNodeForm,
+  AutomationLoopNodeForm,
 } from '../types/automation-node-data-types';
+import { assertAutomationLoopNodeValid } from './validateAutomationLoopNode';
 
 export interface AutomationContext {
   runId: string;
@@ -128,6 +130,192 @@ export class AutomationExecutionEngine {
     return this.nodes.filter((node) => nextNodeIds.includes(node.id));
   }
 
+  private getOutgoingEdge(
+    nodeId: string,
+    sourceHandle: string,
+  ): Edge | undefined {
+    return this.edges.find(
+      (edge) => edge.source === nodeId && edge.sourceHandle === sourceHandle,
+    );
+  }
+
+  private getTargetNode(edge: Edge): Node | undefined {
+    return this.nodes.find((node) => node.id === edge.target);
+  }
+
+  private getFirstOutgoingEdge(nodeId: string): Edge | undefined {
+    return this.edges.find((edge) => edge.source === nodeId);
+  }
+
+  private resolveArraySource(
+    formData: AutomationLoopNodeForm,
+    inputData: string | number | boolean | object | null,
+  ): unknown[] {
+    if (formData.arraySource.type === 'variable') {
+      const variableName = formData.arraySource.variableName;
+      if (!variableName) {
+        throw new Error('Loop node variable name is not configured');
+      }
+      const value = this.context.variables[variableName];
+      if (!Array.isArray(value)) {
+        throw new Error(
+          `Loop variable "${variableName}" must be an array, got ${typeof value}`,
+        );
+      }
+      return value;
+    }
+
+    if (inputData === null || inputData === undefined) {
+      throw new Error('Loop node previous step output is empty');
+    }
+    if (Array.isArray(inputData)) {
+      return inputData;
+    }
+    return [inputData];
+  }
+
+  private async runNodeWithStatus(
+    node: Node,
+    inputData?: string | number | boolean | object | null,
+  ): Promise<string | number | boolean | object | null> {
+    this.log(
+      'info',
+      node.id,
+      String(node.type || 'node'),
+      'Executing node...',
+    );
+
+    (node.data as Record<string, unknown>).status = 'Running';
+    if (this.onNodeUpdate) {
+      this.onNodeUpdate(node.id, { ...node.data });
+    }
+
+    try {
+      const result = await this.executeNode(node, inputData);
+      (node.data as Record<string, unknown>).status = 'Completed';
+      (node.data as Record<string, unknown>).lastRun = new Date().toISOString();
+      if (this.onNodeUpdate) {
+        this.onNodeUpdate(node.id, { ...node.data });
+      }
+      return result;
+    } catch (error) {
+      (node.data as Record<string, unknown>).status = 'Error';
+      (node.data as Record<string, unknown>).lastRun = new Date().toISOString();
+      if (this.onNodeUpdate) {
+        this.onNodeUpdate(node.id, { ...node.data });
+      }
+      throw error;
+    }
+  }
+
+  private async executeBodySubgraph(
+    startNode: Node,
+    loopNodeId: string,
+    inputData: string | number | boolean | object | null,
+  ): Promise<string | number | boolean | object | null> {
+    let currentNode: Node | null = startNode;
+    let currentData = inputData;
+    const visitedInBody = new Set<string>();
+
+    while (currentNode && currentNode.id !== loopNodeId) {
+      if (visitedInBody.has(currentNode.id)) {
+        throw new Error(
+          `Infinite loop detected in loop body at node ${currentNode.id}`,
+        );
+      }
+      visitedInBody.add(currentNode.id);
+
+      currentData = await this.runNodeWithStatus(currentNode, currentData);
+
+      const nextEdge = this.getFirstOutgoingEdge(currentNode.id);
+      if (!nextEdge) {
+        throw new Error(
+          `Loop body node ${currentNode.id} has no outgoing edge back to the loop node`,
+        );
+      }
+
+      const nextNode = this.getTargetNode(nextEdge);
+      if (!nextNode) {
+        throw new Error(`Loop body target node not found for edge ${nextEdge.id}`);
+      }
+
+      currentNode = nextNode;
+    }
+
+    return currentData;
+  }
+
+  private async executeLoopNode(
+    node: Node,
+    inputData: string | number | boolean | object | null,
+  ): Promise<{ doneNextNode: Node | null; result: object }> {
+    assertAutomationLoopNodeValid(node, this.edges);
+
+    const formData = (node.data.formData || node.data) as AutomationLoopNodeForm;
+    const maxIterations = formData.maxIterations ?? 100;
+    const currentItemVariable = formData.currentItemVariable ?? 'currentItem';
+    const loopIndexVariable = formData.loopIndexVariable ?? 'loopIndex';
+
+    const array = this.resolveArraySource(formData, inputData);
+    const iterationCount = Math.min(array.length, maxIterations);
+
+    this.log(
+      'info',
+      node.id,
+      'AutomationLoopNode',
+      `Starting loop over ${iterationCount} item(s)`,
+      { totalItems: array.length, maxIterations },
+    );
+
+    const loopEdge = this.getOutgoingEdge(node.id, 'loop');
+    if (!loopEdge) {
+      throw new Error('Loop node is missing the "loop" handle edge');
+    }
+
+    const bodyStartNode = this.getTargetNode(loopEdge);
+    if (!bodyStartNode) {
+      throw new Error('Loop body entry node not found');
+    }
+
+    for (let i = 0; i < iterationCount; i++) {
+      this.context.variables[currentItemVariable] = array[i] as
+        | string
+        | number
+        | boolean
+        | object
+        | null;
+      this.context.variables[loopIndexVariable] = i;
+
+      this.log(
+        'info',
+        node.id,
+        'AutomationLoopNode',
+        `Loop iteration ${i + 1}/${iterationCount}`,
+        { [currentItemVariable]: array[i], [loopIndexVariable]: i },
+      );
+
+      await this.executeBodySubgraph(bodyStartNode, node.id, array[i] as
+        | string
+        | number
+        | boolean
+        | object
+        | null);
+    }
+
+    const result = {
+      iterationsRun: iterationCount,
+      totalItems: array.length,
+      maxIterations,
+    };
+
+    this.storeExecutionResult(node.id, result, true);
+
+    const doneEdge = this.getOutgoingEdge(node.id, 'done');
+    const doneNextNode = doneEdge ? this.getTargetNode(doneEdge) ?? null : null;
+
+    return { doneNextNode, result };
+  }
+
   private async executeStartNode(
     node: Node,
   ): Promise<{ runId: string; startTime: string }> {
@@ -522,6 +710,21 @@ export class AutomationExecutionEngine {
     return inputData;
   }
 
+  private async executeStubNode(
+    node: Node,
+    inputData: string | number | boolean | object | null,
+  ): Promise<string | number | boolean | object | null> {
+    this.log(
+      'info',
+      node.id,
+      String(node.type || 'node'),
+      'Node executed (stub — full runtime not yet implemented)',
+      inputData,
+    );
+    this.storeExecutionResult(node.id, inputData, true);
+    return inputData;
+  }
+
   private async executeNode(
     node: Node,
     inputData?: string | number | boolean | object | null,
@@ -537,7 +740,14 @@ export class AutomationExecutionEngine {
         return await this.executeFormattingNode(node, inputData || null);
       case 'AutomationEndNode':
         return await this.executeEndNode(node, inputData || null);
+      case 'AutomationLoopNode':
+        throw new Error(
+          'Loop nodes must be executed via executeLoopNode from the workflow runner',
+        );
       default:
+        if (typeof nodeType === 'string' && nodeType.startsWith('Automation')) {
+          return await this.executeStubNode(node, inputData || null);
+        }
         throw new Error(`Unknown node type: ${nodeType}`);
     }
   }
@@ -560,60 +770,77 @@ export class AutomationExecutionEngine {
       const visitedNodes = new Set<string>();
 
       while (currentNode) {
-        if (visitedNodes.has(currentNode.id)) {
+        if (
+          currentNode.type !== 'AutomationLoopNode' &&
+          visitedNodes.has(currentNode.id)
+        ) {
           throw new Error(
             `Circular dependency detected: node ${currentNode.id} already visited`,
           );
         }
 
-        visitedNodes.add(currentNode.id);
-
-        // Announce node execution start
-        this.log(
-          'info',
-          currentNode.id,
-          String(currentNode.type || 'node'),
-          'Executing node...',
-        );
-
-        // Update node status to running
-        (currentNode.data as Record<string, unknown>).status = 'Running';
-        if (this.onNodeUpdate) {
-          // Create new object reference so React detects the change
-          this.onNodeUpdate(currentNode.id, { ...currentNode.data });
+        if (currentNode.type !== 'AutomationLoopNode') {
+          visitedNodes.add(currentNode.id);
         }
 
-        try {
-          currentData = await this.executeNode(currentNode, currentData);
-          (currentNode.data as Record<string, unknown>).status = 'Completed';
-          (currentNode.data as Record<string, unknown>).lastRun =
-            new Date().toISOString();
+        if (currentNode.type === 'AutomationLoopNode') {
+          (currentNode.data as Record<string, unknown>).status = 'Running';
           if (this.onNodeUpdate) {
-            // Create new object reference so React detects the change
             this.onNodeUpdate(currentNode.id, { ...currentNode.data });
           }
-        } catch (error) {
-          (currentNode.data as Record<string, unknown>).status = 'Error';
-          (currentNode.data as Record<string, unknown>).lastRun =
-            new Date().toISOString();
-          if (this.onNodeUpdate) {
-            // Create new object reference so React detects the change
-            this.onNodeUpdate(currentNode.id, { ...currentNode.data });
+
+          try {
+            const { doneNextNode, result } = await this.executeLoopNode(
+              currentNode,
+              currentData,
+            );
+            currentData = result;
+            (currentNode.data as Record<string, unknown>).status = 'Completed';
+            (currentNode.data as Record<string, unknown>).lastRun =
+              new Date().toISOString();
+            if (this.onNodeUpdate) {
+              this.onNodeUpdate(currentNode.id, { ...currentNode.data });
+            }
+
+            if (doneNextNode) {
+              this.log(
+                'info',
+                doneNextNode.id,
+                String(doneNextNode.type || 'node'),
+                'Moving to done path after loop',
+              );
+              currentNode = doneNextNode;
+            } else {
+              currentNode = null;
+            }
+          } catch (error) {
+            (currentNode.data as Record<string, unknown>).status = 'Error';
+            (currentNode.data as Record<string, unknown>).lastRun =
+              new Date().toISOString();
+            if (this.onNodeUpdate) {
+              this.onNodeUpdate(currentNode.id, { ...currentNode.data });
+            }
+            throw error;
           }
-          throw error;
+          continue;
         }
 
-        // Find next node
-        const nextNodes = this.getNextNodes(currentNode.id);
-        if (nextNodes.length > 0) {
-          const next = nextNodes[0];
-          this.log(
-            'info',
-            next.id,
-            String(next.type || 'node'),
-            'Moving to next node',
-          );
-          currentNode = next;
+        currentData = await this.runNodeWithStatus(currentNode, currentData);
+
+        const nextEdge = this.getFirstOutgoingEdge(currentNode.id);
+        if (nextEdge) {
+          const next = this.getTargetNode(nextEdge);
+          if (next) {
+            this.log(
+              'info',
+              next.id,
+              String(next.type || 'node'),
+              'Moving to next node',
+            );
+            currentNode = next;
+          } else {
+            currentNode = null;
+          }
         } else {
           this.log('info', 'workflow', 'engine', 'No next node. Ending.');
           currentNode = null;

package/packages/diagrams/src/lib/utils/automation-flow-processor.ts

@@ -5,6 +5,7 @@ import {
   AutomationApiNodeForm,
   AutomationFormattingNodeForm,
   AutomationEndNodeForm,
+  AutomationLoopNodeForm,
 } from '../types/automation-node-data-types';
 import { Node, Edge } from '@xyflow/react';
 
@@ -165,6 +166,22 @@ export class AutomationFlowProcessor {
       case 'end':
         // End node doesn't create new variables
         break;
+
+      case 'loop': {
+        const currentItemVar = formData.currentItemVariable ?? 'currentItem';
+        const loopIndexVar = formData.loopIndexVariable ?? 'loopIndex';
+        for (const varName of [currentItemVar, loopIndexVar]) {
+          if (!variables.find((v) => v.name === varName)) {
+            variables.push({
+              name: varName,
+              type: varName === loopIndexVar ? 'number' : 'object',
+              defaultValue: null,
+              description: `Loop iteration variable from ${formData.title}`,
+            });
+          }
+        }
+        break;
+      }
     }
   }
 
@@ -252,6 +269,12 @@ module.exports = { executeAutomationWorkflow };
       case 'end':
         code += this.generateEndNodeCode(formData as AutomationEndNodeForm);
         break;
+      case 'loop':
+        code += this.generateLoopNodeCode(
+          formData as AutomationLoopNodeForm,
+          this.edges,
+        );
+        break;
     }
 
     return code;
@@ -539,6 +562,53 @@ module.exports = { executeAutomationWorkflow };
 `;
   }
 
+  private generateLoopNodeCode(
+    formData: AutomationLoopNodeForm,
+    edges: Edge[],
+  ): string {
+    const maxIterations = formData.maxIterations ?? 100;
+    const currentItemVariable = formData.currentItemVariable ?? 'currentItem';
+    const loopIndexVariable = formData.loopIndexVariable ?? 'loopIndex';
+
+    const arrayExpr =
+      formData.arraySource.type === 'variable'
+        ? `context.variables['${formData.arraySource.variableName}']`
+        : '/* previous step output */ context.variables.__previousStepOutput';
+
+    const loopEdge = edges.find(
+      (edge) => edge.source === formData.nodeId && edge.sourceHandle === 'loop',
+    );
+    const doneEdge = edges.find(
+      (edge) => edge.source === formData.nodeId && edge.sourceHandle === 'done',
+    );
+
+    const bodyComment = loopEdge
+      ? `// Body starts at node: ${loopEdge.target}`
+      : '// Body entry not connected';
+    const doneComment = doneEdge
+      ? `// Continue on done path at node: ${doneEdge.target}`
+      : '// Done path not connected';
+
+    return `    // Loop Node: ${formData.title}
+    context.logs.push({
+      timestamp: new Date().toISOString(),
+      level: 'info',
+      nodeId: '${formData.nodeId}',
+      message: 'Starting for-each loop',
+    });
+
+    const __loopArray = Array.isArray(${arrayExpr}) ? ${arrayExpr} : [${arrayExpr}];
+    const __maxIter = ${maxIterations};
+    for (let __i = 0; __i < Math.min(__loopArray.length, __maxIter); __i++) {
+      context.variables['${currentItemVariable}'] = __loopArray[__i];
+      context.variables['${loopIndexVariable}'] = __i;
+      ${bodyComment}
+      // Execute loop body nodes here (back-edge returns to loop node)
+    }
+    ${doneComment}
+`;
+  }
+
   /**
    * Export workflow data as JSON
    */

package/packages/diagrams/src/lib/utils/validateAutomationLoopNode.ts

@@ -0,0 +1,104 @@
+import { Edge, Node } from '@xyflow/react';
+import { AutomationLoopNodeForm } from '../types/automation-node-data-types';
+
+export interface LoopNodeValidationResult {
+  valid: boolean;
+  errors: string[];
+}
+
+function getFormData(node: Node): Partial<AutomationLoopNodeForm> {
+  return (node.data?.formData ?? node.data ?? {}) as Partial<AutomationLoopNodeForm>;
+}
+
+function getOutgoingEdges(nodeId: string, edges: Edge[], sourceHandle?: string): Edge[] {
+  return edges.filter(
+    (edge) =>
+      edge.source === nodeId &&
+      (sourceHandle === undefined || edge.sourceHandle === sourceHandle),
+  );
+}
+
+function getReachableBodyNodeIds(
+  startNodeId: string,
+  loopNodeId: string,
+  edges: Edge[],
+): Set<string> {
+  const reachable = new Set<string>();
+  const queue = [startNodeId];
+
+  while (queue.length > 0) {
+    const currentId = queue.shift()!;
+    if (currentId === loopNodeId || reachable.has(currentId)) {
+      continue;
+    }
+    reachable.add(currentId);
+
+    const outgoing = edges.filter((edge) => edge.source === currentId);
+    for (const edge of outgoing) {
+      if (edge.target !== loopNodeId && !reachable.has(edge.target)) {
+        queue.push(edge.target);
+      }
+    }
+  }
+
+  return reachable;
+}
+
+export function validateAutomationLoopNode(
+  node: Node,
+  edges: Edge[],
+): LoopNodeValidationResult {
+  const errors: string[] = [];
+  const formData = getFormData(node);
+  const nodeId = node.id;
+
+  if (!formData.arraySource?.type) {
+    errors.push('Array data source is not configured');
+  } else if (
+    formData.arraySource.type === 'variable' &&
+    !formData.arraySource.variableName?.trim()
+  ) {
+    errors.push('Variable name is required when array source type is "variable"');
+  }
+
+  const loopEdges = getOutgoingEdges(nodeId, edges, 'loop');
+  const doneEdges = getOutgoingEdges(nodeId, edges, 'done');
+
+  if (loopEdges.length === 0) {
+    errors.push('Loop node must have exactly one outgoing edge on the "loop" handle');
+  } else if (loopEdges.length > 1) {
+    errors.push('Loop node must have only one outgoing edge on the "loop" handle');
+  }
+
+  if (doneEdges.length === 0) {
+    errors.push('Loop node must have exactly one outgoing edge on the "done" handle');
+  } else if (doneEdges.length > 1) {
+    errors.push('Loop node must have only one outgoing edge on the "done" handle');
+  }
+
+  if (loopEdges.length === 1) {
+    const bodyStartId = loopEdges[0].target;
+    const bodyNodeIds = getReachableBodyNodeIds(bodyStartId, nodeId, edges);
+    const hasBackEdge = edges.some(
+      (edge) => edge.target === nodeId && bodyNodeIds.has(edge.source),
+    );
+
+    if (!hasBackEdge) {
+      errors.push(
+        'Loop body must connect back to the Loop node to advance iterations',
+      );
+    }
+  }
+
+  return {
+    valid: errors.length === 0,
+    errors,
+  };
+}
+
+export function assertAutomationLoopNodeValid(node: Node, edges: Edge[]): void {
+  const result = validateAutomationLoopNode(node, edges);
+  if (!result.valid) {
+    throw new Error(result.errors.join('; '));
+  }
+}