feat(spatial): enhance port handling and node hit-testing

- Introduce `PortType.both` for bidirectional ports.
- Adjust `_isPointCoveredByOtherNode` to exclude GroupNode member nodes.
- Replace logical `position` with `visualPosition` for precise hit-testing.
- Refactor connection validation to use port type (`isInput`/`isOutput`) directly.
- Ensure GroupNode preservation behavior is customizable when empty.
- Update rendering for node and group colors to use 15% opacity for subtle styling.
- Enhance visual position initialization in test factories.

Author: pavanpodila

packages/vyuh_node_flow/lib/src/editor/controller/connection_api.dart

@@ -800,18 +800,6 @@ extension ConnectionApi<T, C> on NodeFlowController<T, C> {
       );
     }
 
-    // Cannot connect same direction ports
-    final targetIsOutput = targetNode.outputPorts.any(
-      (p) => p.id == targetPortId,
-    );
-    if (temp.isStartFromOutput == targetIsOutput) {
-      return ConnectionValidationResult.deny(
-        reason: targetIsOutput
-            ? 'Cannot connect output to output'
-            : 'Cannot connect input to input',
-      );
-    }
-
     // Get source node and port
     final sourceNode = _nodes[temp.startNodeId];
     if (sourceNode == null) {
@@ -838,6 +826,25 @@ extension ConnectionApi<T, C> on NodeFlowController<T, C> {
       );
     }
 
+    // Cannot connect same direction ports
+    // Use the port's actual type (isInput/isOutput) rather than which list it's in,
+    // because PortType.both ports can act as either input or output.
+    if (temp.isStartFromOutput) {
+      // Connecting from output - target must accept input
+      if (!targetPort.isInput) {
+        return const ConnectionValidationResult.deny(
+          reason: 'Cannot connect output to output',
+        );
+      }
+    } else {
+      // Connecting from input - target must accept output
+      if (!targetPort.isOutput) {
+        return const ConnectionValidationResult.deny(
+          reason: 'Cannot connect input to input',
+        );
+      }
+    }
+
     // Both ports must be connectable
     if (!sourcePort.isConnectable) {
       return const ConnectionValidationResult.deny(
@@ -850,20 +857,8 @@ extension ConnectionApi<T, C> on NodeFlowController<T, C> {
       );
     }
 
-    // Direction compatibility
-    if (temp.isStartFromOutput) {
-      if (!targetPort.isInput) {
-        return const ConnectionValidationResult.deny(
-          reason: 'Target port cannot receive connections',
-        );
-      }
-    } else {
-      if (!targetPort.isOutput) {
-        return const ConnectionValidationResult.deny(
-          reason: 'Target port cannot emit connections',
-        );
-      }
-    }
+    // Note: Direction compatibility is already checked above using port.isInput/isOutput
+    // which correctly handles PortType.both ports.
 
     // Determine actual source/target
     final Node<T> actualSourceNode;

packages/vyuh_node_flow/lib/src/editor/controller/group_api.dart

@@ -113,34 +113,50 @@ extension GroupApi<T, C> on NodeFlowController<T, C> {
   // ============================================================================
 
   /// Moves nodes by a given delta, handling position and visual position with snapping.
+  ///
+  /// If any of the nodes being moved is a GroupNode, its children are also
+  /// moved recursively. This ensures nested groups work correctly - moving a
+  /// parent group moves all descendants.
   void _moveNodesByDelta(Set<String> nodeIds, Offset delta) {
-    // Check if already moving to prevent nested calls
-    if (_isMovingGroupNodes) {
-      return;
-    }
-
     if (nodeIds.isEmpty) return;
 
-    // Temporarily disable updates to prevent cycles
+    // Set flag to prevent MobX reactions during movement
     _isMovingGroupNodes = true;
 
-    try {
-      runInAction(() {
-        for (final nodeId in nodeIds) {
-          final node = _nodes[nodeId];
-          if (node != null) {
-            final newPosition = node.position.value + delta;
-
-            // Update both position and visual position
-            node.position.value = newPosition;
-            final snappedPosition = snapToGrid(newPosition);
-            node.setVisualPosition(snappedPosition);
+    // Track nodes we've already moved to prevent infinite loops
+    final movedNodes = <String>{};
+
+    void moveRecursively(Set<String> ids) {
+      for (final nodeId in ids) {
+        // Skip if already moved
+        if (movedNodes.contains(nodeId)) continue;
+        movedNodes.add(nodeId);
+
+        final node = _nodes[nodeId];
+        if (node == null) continue;
+
+        // Move this node
+        final newPosition = node.position.value + delta;
+        node.position.value = newPosition;
+        final snappedPosition = snapToGrid(newPosition);
+        node.setVisualPosition(snappedPosition);
+
+        // If this node is a GroupNode, recursively move its children
+        if (node is GroupableMixin<T>) {
+          if (node.isGroupable && node.groupedNodeIds.isNotEmpty) {
+            moveRecursively(node.groupedNodeIds);
           }
         }
+      }
+    }
+
+    try {
+      runInAction(() {
+        moveRecursively(nodeIds);
       });
 
       // Mark nodes dirty (deferred during drag)
-      _markNodesDirty(nodeIds);
+      _markNodesDirty(movedNodes);
     } finally {
       _isMovingGroupNodes = false;
     }

packages/vyuh_node_flow/lib/src/nodes/comment_node.dart

@@ -118,8 +118,8 @@ class CommentNode<T> extends Node<T> with ResizableMixin<T> {
     Color? selectedBorderColor,
     double borderRadius = 4.0,
   }) {
-    // Use the comment's own color with 25% opacity, filled, no outline
-    final commentColor = this.color.withValues(alpha: 0.25);
+    // Use the comment's own color (not the parameter) with 15% opacity
+    final commentColor = this.color.withValues(alpha: 0.15);
     final rrect = RRect.fromRectAndRadius(
       bounds,
       Radius.circular(borderRadius),
@@ -138,8 +138,8 @@ class CommentNode<T> extends Node<T> with ResizableMixin<T> {
     required Color defaultColor,
     double borderRadius = 2.0,
   }) {
-    // Use the comment's own color with 25% opacity, filled, no outline
-    final commentColor = color.withValues(alpha: 0.25);
+    // Use the comment's own color with 15% opacity for subtle appearance
+    final commentColor = color.withValues(alpha: 0.15);
     final rrect = RRect.fromRectAndRadius(
       bounds,
       Radius.circular(borderRadius),

packages/vyuh_node_flow/lib/src/nodes/group_node.dart

@@ -131,10 +131,15 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
     // Optional ports for subflow patterns
     super.inputPorts,
     super.outputPorts,
+    // Custom widget builder for subclass rendering (e.g., LoopNode)
+    super.widgetBuilder,
+    // Override default auto-delete behavior when group becomes empty
+    bool preserveWhenEmpty = false,
   }) : _nodeIds = ObservableSet.of(nodeIds ?? {}),
        _observableBehavior = Observable(behavior),
        _observableTitle = Observable(title),
        _observableColor = Observable(color),
+       _preserveWhenEmpty = preserveWhenEmpty,
        super(
          type: 'group',
          layer: NodeRenderLayer.background,
@@ -143,6 +148,13 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
          selectable: true,
        );
 
+  /// Whether to preserve this group when it becomes empty.
+  ///
+  /// By default, groups with [GroupBehavior.explicit] are auto-deleted when
+  /// all member nodes are removed. Set this to `true` to prevent auto-deletion.
+  /// Useful for loop containers that should persist even without body nodes.
+  final bool _preserveWhenEmpty;
+
   final Observable<String> _observableTitle;
   final Observable<Color> _observableColor;
   final Observable<GroupBehavior> _observableBehavior;
@@ -321,7 +333,8 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
   bool get isEmpty => behavior != GroupBehavior.bounds && _nodeIds.isEmpty;
 
   @override
-  bool get shouldRemoveWhenEmpty => behavior == GroupBehavior.explicit;
+  bool get shouldRemoveWhenEmpty =>
+      behavior == GroupBehavior.explicit && !_preserveWhenEmpty;
 
   @override
   void onChildMoved(String nodeId, Offset newPosition) {
@@ -487,8 +500,8 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
     Color? selectedBorderColor,
     double borderRadius = 4.0,
   }) {
-    // Use the group's own color with 25% opacity, filled, no outline
-    final groupColor = currentColor.withValues(alpha: 0.25);
+    // Use the group's own color with 15% opacity for subtle appearance
+    final groupColor = currentColor.withValues(alpha: 0.15);
     final rrect = RRect.fromRectAndRadius(
       bounds,
       Radius.circular(borderRadius),
@@ -507,8 +520,8 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
     required Color defaultColor,
     double borderRadius = 2.0,
   }) {
-    // Use the group's own color with 25% opacity, filled, no outline
-    final groupColor = currentColor.withValues(alpha: 0.25);
+    // Use the group's own color with 15% opacity for subtle appearance
+    final groupColor = currentColor.withValues(alpha: 0.15);
     final rrect = RRect.fromRectAndRadius(
       bounds,
       Radius.circular(borderRadius),
@@ -539,6 +552,7 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
     bool? locked,
     List<Port>? inputPorts,
     List<Port>? outputPorts,
+    NodeWidgetBuilder<T>? widgetBuilder,
   }) {
     return GroupNode<T>(
       id: id ?? this.id,
@@ -555,6 +569,7 @@ class GroupNode<T> extends Node<T> with ResizableMixin<T>, GroupableMixin<T> {
       locked: locked ?? this.locked,
       inputPorts: inputPorts ?? List.from(this.inputPorts),
       outputPorts: outputPorts ?? List.from(this.outputPorts),
+      widgetBuilder: widgetBuilder ?? this.widgetBuilder,
     );
   }
 

packages/vyuh_node_flow/lib/src/nodes/node.dart

@@ -407,20 +407,26 @@ class Node<T> {
   // ===========================================================================
 
   /// Checks if a point is within the node's rectangular bounds.
+  ///
+  /// Uses [visualPosition] for accurate hit testing against where the node
+  /// is actually rendered (which may differ from [position] due to grid snapping).
   bool containsPoint(Offset point) {
     return Rect.fromLTWH(
-      position.value.dx,
-      position.value.dy,
+      visualPosition.value.dx,
+      visualPosition.value.dy,
       size.value.width,
       size.value.height,
     ).contains(point);
   }
 
   /// Gets the node's bounding rectangle.
+  ///
+  /// Uses [visualPosition] for accurate bounds that match where the node
+  /// is actually rendered (which may differ from [position] due to grid snapping).
   Rect getBounds() {
     return Rect.fromLTWH(
-      position.value.dx,
-      position.value.dy,
+      visualPosition.value.dx,
+      visualPosition.value.dy,
       size.value.width,
       size.value.height,
     );

packages/vyuh_node_flow/lib/src/nodes/node_container.dart

@@ -187,15 +187,19 @@ class NodeContainer<T> extends StatelessWidget {
                 ),
 
                 // Input ports (only when LOD allows and ports exist)
+                // Use port.isOutput to respect PortType (input, output, both)
+                // rather than list membership
                 if (lodVisibility.showPorts && node.inputPorts.isNotEmpty)
                   ...node.inputPorts.map(
-                    (port) => _buildPort(context, port, false),
+                    (port) => _buildPort(context, port, port.isOutput),
                   ),
 
                 // Output ports (only when LOD allows and ports exist)
+                // Use port.isOutput to respect PortType (input, output, both)
+                // rather than list membership
                 if (lodVisibility.showPorts && node.outputPorts.isNotEmpty)
                   ...node.outputPorts.map(
-                    (port) => _buildPort(context, port, true),
+                    (port) => _buildPort(context, port, port.isOutput),
                   ),
 
                 // Resize handles (shown when selected and resizable)
@@ -227,7 +231,7 @@ class NodeContainer<T> extends StatelessWidget {
   Widget _buildPort(BuildContext context, Port port, bool isOutput) {
     final theme = controller.theme ?? NodeFlowTheme.light;
     final portTheme = theme.portTheme;
-    final isConnected = _isPortConnected(port.id, isOutput);
+    final isConnected = _isPortConnected(port);
 
     // Get the visual position from the Node model
     final effectivePortSize = port.size ?? portTheme.size;
@@ -281,15 +285,26 @@ class NodeContainer<T> extends StatelessWidget {
   }
 
   /// Checks if a port is connected by examining the connections list.
-  bool _isPortConnected(String portId, bool isOutput) {
+  ///
+  /// For [PortType.both] ports, checks both source and target connections
+  /// since these ports can act as either input or output.
+  bool _isPortConnected(Port port) {
     return connections.any((connection) {
-      if (isOutput) {
+      // For bidirectional ports (PortType.both), check both directions
+      if (port.isInput && port.isOutput) {
+        return (connection.sourceNodeId == node.id &&
+                connection.sourcePortId == port.id) ||
+            (connection.targetNodeId == node.id &&
+                connection.targetPortId == port.id);
+      }
+      // For output-only ports, check as source
+      if (port.isOutput) {
         return connection.sourceNodeId == node.id &&
-            connection.sourcePortId == portId;
-      } else {
-        return connection.targetNodeId == node.id &&
-            connection.targetPortId == portId;
+            connection.sourcePortId == port.id;
       }
+      // For input-only ports, check as target
+      return connection.targetNodeId == node.id &&
+          connection.targetPortId == port.id;
     });
   }
 }