@2112-lab/central-plant 0.2.4 → 0.2.8

package/dist/bundle/index.js

@@ -28480,7 +28480,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         if (_this4._testCondition(condition.when, value)) {
           if (Array.isArray(condition.actions)) {
             condition.actions.forEach(function (action) {
-              _this4._applyAction(output, action.set, action.value);
+              _this4._applyAction(output, action.set, action.value, action.relative === true);
             });
           }
         }
@@ -28558,6 +28558,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "_applyAction",
     value: function _applyAction(object, propertyPath, value) {
+      var relative = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
       if (!object || typeof propertyPath !== 'string') return;
       var parts = propertyPath.split('.');
 
@@ -28583,6 +28584,15 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         return;
       }
 
+      // If relative, capture the mesh's original value on first execution and offset from it.
+      if (relative) {
+        var baselineKey = "_baseline_".concat(propertyPath.replace(/\./g, '_'));
+        if (!(baselineKey in object.userData)) {
+          object.userData[baselineKey] = target[lastKey];
+        }
+        value = object.userData[baselineKey] + parseFloat(value);
+      }
+
       // THREE.Color objects must be mutated via .set() rather than replaced
       var existing = target[lastKey];
       if (existing && existing.isColor && typeof value === 'string') {
@@ -28635,7 +28645,7 @@ function attachIODevicesToComponent(_x, _x2, _x3, _x4) {
 }
 function _attachIODevicesToComponent() {
   _attachIODevicesToComponent = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(componentModel, componentData, modelPreloader, parentComponentId) {
-    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t, _t2;
+    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t, _t2;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.n) {
         case 0:
@@ -28736,6 +28746,13 @@ function _attachIODevicesToComponent() {
             deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
           }
 
+          // Apply face-based rotation (stored in degrees, XYZ Euler order)
+          if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+            rot = attachment.attachmentPoint.rotation;
+            deg2rad = Math.PI / 180;
+            deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+          }
+
           // IO device models are authored at the same real-world unit scale
           // as the host component, so keep them at their natural (1:1) size.
           // Note: attachmentPoint.scale is the connector marker sphere size,
@@ -32575,7 +32592,7 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
     key: "_attachIODeviceModelsToPreview",
     value: (function () {
       var _attachIODeviceModelsToPreview2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(parentObject, componentData, modelPreloader) {
-        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t3;
+        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t3;
         return _regenerator().w(function (_context3) {
           while (1) switch (_context3.n) {
             case 0:
@@ -32650,6 +32667,13 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
                 deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
               }
 
+              // Apply face-based rotation (stored in degrees, XYZ Euler order)
+              if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+                rot = attachment.attachmentPoint.rotation;
+                deg2rad = Math.PI / 180;
+                deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+              }
+
               // IO device models use their natural (1:1) scale — the stored
               // attachmentPoint.scale value is for the connector marker sphere.
               deviceModel.scale.setScalar(1);
@@ -36018,6 +36042,59 @@ var Viewport2DManager = /*#__PURE__*/function (_BaseDisposable2) {
   }]);
 }(BaseDisposable);
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction helpers (module-level)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the flow direction of a connector from the current scene data.
+ * @param {Object} sceneData - currentSceneData object
+ * @param {string} connectorId
+ * @returns {'in'|'out'|'bi'} Defaults to 'bi' if not set.
+ */
+function _getConnectorFlow(sceneData, connectorId) {
+  var _sceneData$scene;
+  var children = (sceneData === null || sceneData === void 0 || (_sceneData$scene = sceneData.scene) === null || _sceneData$scene === void 0 ? void 0 : _sceneData$scene.children) || [];
+  var _iterator = _createForOfIteratorHelper(children),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var component = _step.value;
+      var _iterator2 = _createForOfIteratorHelper(component.children || []),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _child$userData;
+          var child = _step2.value;
+          if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'connector' && child.uuid === connectorId) {
+            return child.userData.flow || 'bi';
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return 'bi';
+}
+
+/**
+ * Returns true if fromFlow → toFlow is a valid connection.
+ * @param {'in'|'out'|'bi'} fromFlow
+ * @param {'in'|'out'|'bi'} toFlow
+ * @returns {boolean}
+ */
+function _areFlowsCompatible$1(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlantInternals class containing internal methods and functionality
  */
@@ -36469,12 +36546,12 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       console.log("\uD83D\uDD27 Translating ".concat(selectedObjects.length, " selected object(s) on ").concat(axis, " axis by ").concat(value));
 
       // Translate each selected object using the appropriate method
-      var _iterator = _createForOfIteratorHelper(selectedObjects),
-        _step;
+      var _iterator3 = _createForOfIteratorHelper(selectedObjects),
+        _step3;
       try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
           var _obj$userData;
-          var obj = _step.value;
+          var obj = _step3.value;
           var objectType = (_obj$userData = obj.userData) === null || _obj$userData === void 0 ? void 0 : _obj$userData.objectType;
           var objectId = obj.uuid;
           var success = false;
@@ -36501,9 +36578,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
           }
         }
       } catch (err) {
-        _iterator.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator.f();
+        _iterator3.f();
       }
       result.success = result.translatedCount === result.totalCount;
       if (result.success) {
@@ -36687,7 +36764,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addConnection",
     value: function addConnection(fromConnectorId, toConnectorId) {
-      var _this$centralPlant$sc4;
+      var _this$centralPlant$sc4, _this$centralPlant$sc5;
       // Use centralized validation for connection parameters
       var existingConnections = ((_this$centralPlant$sc4 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc4 === void 0 || (_this$centralPlant$sc4 = _this$centralPlant$sc4.currentSceneData) === null || _this$centralPlant$sc4 === void 0 ? void 0 : _this$centralPlant$sc4.connections) || [];
       var validation = this.validator.validateConnectionParams(fromConnectorId, toConnectorId, existingConnections);
@@ -36695,6 +36772,17 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false; // Validator already logged the error
       }
 
+      // Validate flow direction compatibility
+      var sceneData = (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.currentSceneData;
+      if (sceneData) {
+        var fromFlow = _getConnectorFlow(sceneData, fromConnectorId);
+        var toFlow = _getConnectorFlow(sceneData, toConnectorId);
+        if (!_areFlowsCompatible$1(fromFlow, toFlow)) {
+          console.error("\u274C addConnection(): Incompatible flow directions \u2014 '".concat(fromConnectorId, "' is '").concat(fromFlow, "' and '").concat(toConnectorId, "' is '").concat(toFlow, "'. ") + "'".concat(fromFlow, "' \u2192 '").concat(toFlow, "' connections are not allowed."));
+          return false;
+        }
+      }
+
       // Validate scene availability
       var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer);
       if (!sceneValidation.isValid) {
@@ -36815,7 +36903,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addComponent",
     value: function addComponent(libraryId) {
-      var _this$centralPlant$sc5;
+      var _this$centralPlant$sc6;
       var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
       // Use centralized validation for component addition parameters
       var existingIds = this.getComponentIds();
@@ -36825,7 +36913,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
 
       // Validate scene availability
-      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.scene);
+      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.scene);
       if (!sceneValidation.isValid) {
         return false;
       }
@@ -36844,7 +36932,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false;
       }
       try {
-        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc6, _componentData$childr3, _componentData$defaul;
+        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc7, _componentData$childr3, _componentData$defaul;
         // Generate a unique component ID if not provided
         var componentId = options.customId || this.generateUniqueComponentId(libraryId);
 
@@ -36956,7 +37044,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         componentModel.updateMatrixWorld(true);
 
         // Check if component is underground and fix if needed (based on settings)
-        var checkUnderground = (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.managers) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.settingsManager) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.getSetting('scene', 'checkUnderground');
+        var checkUnderground = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.managers) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.settingsManager) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.getSetting('scene', 'checkUnderground');
         if (checkUnderground) {
           var wasFixed = this.fixUndergroundComponent(componentModel);
           if (wasFixed) {
@@ -37054,8 +37142,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         // responds to tooltip-driven state changes immediately after drop.
         // (The scene-load path uses _processBehaviors instead, which runs on loadSceneData.)
         if ((_componentData$defaul = componentData.defaultBehaviors) !== null && _componentData$defaul !== void 0 && _componentData$defaul.length) {
-          var _this$centralPlant$sc7, _som$registerBehavior;
-          var som = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.sceneOperationsManager;
+          var _this$centralPlant$sc8, _som$registerBehavior;
+          var som = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.sceneOperationsManager;
           som === null || som === void 0 || (_som$registerBehavior = som.registerBehaviorsForComponentInstance) === null || _som$registerBehavior === void 0 || _som$registerBehavior.call(som, componentData, componentId);
         }
 
@@ -37117,9 +37205,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "deleteComponent",
     value: function deleteComponent(componentId) {
-      var _this$centralPlant$sc8;
+      var _this$centralPlant$sc9;
       // Check if component manager is available
-      var componentManager = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.componentManager;
+      var componentManager = (_this$centralPlant$sc9 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc9 === void 0 ? void 0 : _this$centralPlant$sc9.componentManager;
       if (!componentManager) {
         console.error('❌ deleteComponent(): Component manager not available');
         return false;
@@ -37194,8 +37282,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
       var componentIds = [];
       this.centralPlant.sceneViewer.scene.traverse(function (child) {
-        var _child$userData;
-        if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'component') {
+        var _child$userData2;
+        if (((_child$userData2 = child.userData) === null || _child$userData2 === void 0 ? void 0 : _child$userData2.objectType) === 'component') {
           componentIds.push(child.uuid || child.userData.originalUuid);
         }
       });
@@ -37204,6 +37292,22 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }]);
 }();
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction compatibility helper (module-level, no class dependency)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the two flow directions are compatible for a connection.
+ * @param {string} fromFlow - 'in' | 'out' | 'bi'
+ * @param {string} toFlow   - 'in' | 'out' | 'bi'
+ * @returns {boolean}
+ */
+function _areFlowsCompatible(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  // in ↔ out are compatible; in → in and out → out are not
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlant class that manages all scene utility instances and provides public API
  * 
@@ -37214,7 +37318,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.4
+   * @version 0.2.8
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -38147,6 +38251,107 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       return availableConnectorIds;
     }
 
+    /**
+     * Get available connectors with their flow direction metadata.
+     * Same filtering logic as getAvailableConnections() but returns objects instead of strings.
+     * @returns {Array<{id: string, flow: string}>} Array of connector info objects.
+     *   flow is one of 'in', 'out', 'bi'. Defaults to 'bi' if not set in userData.
+     * @example
+     * const infos = centralPlant.getAvailableConnectionsInfo()
+     * // [{ id: 'PUMP-1-CONNECTOR-1', flow: 'out' }, ...]
+     */
+  }, {
+    key: "getAvailableConnectionsInfo",
+    value: function getAvailableConnectionsInfo() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Scene viewer or current scene data not available');
+        return [];
+      }
+      var sceneData = this.sceneViewer.currentSceneData;
+      if (!sceneData.scene || !sceneData.scene.children) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Invalid scene data structure');
+        return [];
+      }
+      var allConnectorInfos = [];
+      sceneData.scene.children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              allConnectorInfos.push({
+                id: child.uuid,
+                flow: child.userData.flow || 'bi'
+              });
+            }
+          });
+        }
+      });
+      var existingConnections = this.getConnections();
+      var usedConnectorIds = new Set();
+      existingConnections.forEach(function (connection) {
+        if (connection.from) usedConnectorIds.add(connection.from);
+        if (connection.to) usedConnectorIds.add(connection.to);
+      });
+      return allConnectorInfos.filter(function (info) {
+        return !usedConnectorIds.has(info.id);
+      });
+    }
+
+    /**
+     * Validate all connections in the current scene for flow direction compatibility.
+     * @returns {{ valid: Array<Object>, invalid: Array<{connection: Object, reason: string}> }}
+     * @example
+     * const result = centralPlant.validateConnections()
+     * result.invalid.forEach(({ connection, reason }) => console.warn(reason, connection))
+     */
+  }, {
+    key: "validateConnections",
+    value: function validateConnections() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ validateConnections(): Scene viewer or current scene data not available');
+        return {
+          valid: [],
+          invalid: []
+        };
+      }
+      var connections = this.getConnections();
+      var sceneData = this.sceneViewer.currentSceneData;
+
+      // Build lookup map: connectorId → flow
+      var flowMap = {};
+      var scene = sceneData.scene || {};
+      var children = scene.children || [];
+      children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              flowMap[child.uuid] = child.userData.flow || 'bi';
+            }
+          });
+        }
+      });
+      var valid = [];
+      var invalid = [];
+      connections.forEach(function (connection) {
+        var fromFlow = flowMap[connection.from] || 'bi';
+        var toFlow = flowMap[connection.to] || 'bi';
+        if (_areFlowsCompatible(fromFlow, toFlow)) {
+          valid.push(connection);
+        } else {
+          var reason = "Incompatible flow directions: connector '".concat(connection.from, "' is '").concat(fromFlow, "' and connector '").concat(connection.to, "' is '").concat(toFlow, "' \u2014 ").concat(fromFlow, " \u2192 ").concat(toFlow, " is not allowed");
+          console.warn("\u26A0\uFE0F validateConnections(): ".concat(reason));
+          invalid.push({
+            connection: connection,
+            reason: reason
+          });
+        }
+      });
+      console.log("\u2705 validateConnections(): ".concat(valid.length, " valid, ").concat(invalid.length, " invalid connections"));
+      return {
+        valid: valid,
+        invalid: invalid
+      };
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // BEHAVIORS API
     // ─────────────────────────────────────────────────────────────────────────

package/dist/cjs/src/core/centralPlant.js

@@ -9,6 +9,22 @@ var DisposalUtilities = require('../utils/DisposalUtilities.js');
 var centralPlantInternals = require('./centralPlantInternals.js');
 require('../rendering/modelPreloader.js');
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction compatibility helper (module-level, no class dependency)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the two flow directions are compatible for a connection.
+ * @param {string} fromFlow - 'in' | 'out' | 'bi'
+ * @param {string} toFlow   - 'in' | 'out' | 'bi'
+ * @returns {boolean}
+ */
+function _areFlowsCompatible(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  // in ↔ out are compatible; in → in and out → out are not
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlant class that manages all scene utility instances and provides public API
  * 
@@ -19,7 +35,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.4
+   * @version 0.2.8
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -952,6 +968,107 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       return availableConnectorIds;
     }
 
+    /**
+     * Get available connectors with their flow direction metadata.
+     * Same filtering logic as getAvailableConnections() but returns objects instead of strings.
+     * @returns {Array<{id: string, flow: string}>} Array of connector info objects.
+     *   flow is one of 'in', 'out', 'bi'. Defaults to 'bi' if not set in userData.
+     * @example
+     * const infos = centralPlant.getAvailableConnectionsInfo()
+     * // [{ id: 'PUMP-1-CONNECTOR-1', flow: 'out' }, ...]
+     */
+  }, {
+    key: "getAvailableConnectionsInfo",
+    value: function getAvailableConnectionsInfo() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Scene viewer or current scene data not available');
+        return [];
+      }
+      var sceneData = this.sceneViewer.currentSceneData;
+      if (!sceneData.scene || !sceneData.scene.children) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Invalid scene data structure');
+        return [];
+      }
+      var allConnectorInfos = [];
+      sceneData.scene.children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              allConnectorInfos.push({
+                id: child.uuid,
+                flow: child.userData.flow || 'bi'
+              });
+            }
+          });
+        }
+      });
+      var existingConnections = this.getConnections();
+      var usedConnectorIds = new Set();
+      existingConnections.forEach(function (connection) {
+        if (connection.from) usedConnectorIds.add(connection.from);
+        if (connection.to) usedConnectorIds.add(connection.to);
+      });
+      return allConnectorInfos.filter(function (info) {
+        return !usedConnectorIds.has(info.id);
+      });
+    }
+
+    /**
+     * Validate all connections in the current scene for flow direction compatibility.
+     * @returns {{ valid: Array<Object>, invalid: Array<{connection: Object, reason: string}> }}
+     * @example
+     * const result = centralPlant.validateConnections()
+     * result.invalid.forEach(({ connection, reason }) => console.warn(reason, connection))
+     */
+  }, {
+    key: "validateConnections",
+    value: function validateConnections() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ validateConnections(): Scene viewer or current scene data not available');
+        return {
+          valid: [],
+          invalid: []
+        };
+      }
+      var connections = this.getConnections();
+      var sceneData = this.sceneViewer.currentSceneData;
+
+      // Build lookup map: connectorId → flow
+      var flowMap = {};
+      var scene = sceneData.scene || {};
+      var children = scene.children || [];
+      children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              flowMap[child.uuid] = child.userData.flow || 'bi';
+            }
+          });
+        }
+      });
+      var valid = [];
+      var invalid = [];
+      connections.forEach(function (connection) {
+        var fromFlow = flowMap[connection.from] || 'bi';
+        var toFlow = flowMap[connection.to] || 'bi';
+        if (_areFlowsCompatible(fromFlow, toFlow)) {
+          valid.push(connection);
+        } else {
+          var reason = "Incompatible flow directions: connector '".concat(connection.from, "' is '").concat(fromFlow, "' and connector '").concat(connection.to, "' is '").concat(toFlow, "' \u2014 ").concat(fromFlow, " \u2192 ").concat(toFlow, " is not allowed");
+          console.warn("\u26A0\uFE0F validateConnections(): ".concat(reason));
+          invalid.push({
+            connection: connection,
+            reason: reason
+          });
+        }
+      });
+      console.log("\u2705 validateConnections(): ".concat(valid.length, " valid, ").concat(invalid.length, " invalid connections"));
+      return {
+        valid: valid,
+        invalid: invalid
+      };
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // BEHAVIORS API
     // ─────────────────────────────────────────────────────────────────────────

package/dist/cjs/src/core/centralPlantInternals.js

@@ -50,6 +50,59 @@ function _interopNamespace(e) {
 
 var THREE__namespace = /*#__PURE__*/_interopNamespace(THREE);
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction helpers (module-level)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the flow direction of a connector from the current scene data.
+ * @param {Object} sceneData - currentSceneData object
+ * @param {string} connectorId
+ * @returns {'in'|'out'|'bi'} Defaults to 'bi' if not set.
+ */
+function _getConnectorFlow(sceneData, connectorId) {
+  var _sceneData$scene;
+  var children = (sceneData === null || sceneData === void 0 || (_sceneData$scene = sceneData.scene) === null || _sceneData$scene === void 0 ? void 0 : _sceneData$scene.children) || [];
+  var _iterator = _rollupPluginBabelHelpers.createForOfIteratorHelper(children),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var component = _step.value;
+      var _iterator2 = _rollupPluginBabelHelpers.createForOfIteratorHelper(component.children || []),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _child$userData;
+          var child = _step2.value;
+          if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'connector' && child.uuid === connectorId) {
+            return child.userData.flow || 'bi';
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return 'bi';
+}
+
+/**
+ * Returns true if fromFlow → toFlow is a valid connection.
+ * @param {'in'|'out'|'bi'} fromFlow
+ * @param {'in'|'out'|'bi'} toFlow
+ * @returns {boolean}
+ */
+function _areFlowsCompatible(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlantInternals class containing internal methods and functionality
  */
@@ -501,12 +554,12 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       console.log("\uD83D\uDD27 Translating ".concat(selectedObjects.length, " selected object(s) on ").concat(axis, " axis by ").concat(value));
 
       // Translate each selected object using the appropriate method
-      var _iterator = _rollupPluginBabelHelpers.createForOfIteratorHelper(selectedObjects),
-        _step;
+      var _iterator3 = _rollupPluginBabelHelpers.createForOfIteratorHelper(selectedObjects),
+        _step3;
       try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
           var _obj$userData;
-          var obj = _step.value;
+          var obj = _step3.value;
           var objectType = (_obj$userData = obj.userData) === null || _obj$userData === void 0 ? void 0 : _obj$userData.objectType;
           var objectId = obj.uuid;
           var success = false;
@@ -533,9 +586,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
           }
         }
       } catch (err) {
-        _iterator.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator.f();
+        _iterator3.f();
       }
       result.success = result.translatedCount === result.totalCount;
       if (result.success) {
@@ -719,7 +772,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addConnection",
     value: function addConnection(fromConnectorId, toConnectorId) {
-      var _this$centralPlant$sc4;
+      var _this$centralPlant$sc4, _this$centralPlant$sc5;
       // Use centralized validation for connection parameters
       var existingConnections = ((_this$centralPlant$sc4 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc4 === void 0 || (_this$centralPlant$sc4 = _this$centralPlant$sc4.currentSceneData) === null || _this$centralPlant$sc4 === void 0 ? void 0 : _this$centralPlant$sc4.connections) || [];
       var validation = this.validator.validateConnectionParams(fromConnectorId, toConnectorId, existingConnections);
@@ -727,6 +780,17 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false; // Validator already logged the error
       }
 
+      // Validate flow direction compatibility
+      var sceneData = (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.currentSceneData;
+      if (sceneData) {
+        var fromFlow = _getConnectorFlow(sceneData, fromConnectorId);
+        var toFlow = _getConnectorFlow(sceneData, toConnectorId);
+        if (!_areFlowsCompatible(fromFlow, toFlow)) {
+          console.error("\u274C addConnection(): Incompatible flow directions \u2014 '".concat(fromConnectorId, "' is '").concat(fromFlow, "' and '").concat(toConnectorId, "' is '").concat(toFlow, "'. ") + "'".concat(fromFlow, "' \u2192 '").concat(toFlow, "' connections are not allowed."));
+          return false;
+        }
+      }
+
       // Validate scene availability
       var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer);
       if (!sceneValidation.isValid) {
@@ -847,7 +911,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addComponent",
     value: function addComponent(libraryId) {
-      var _this$centralPlant$sc5;
+      var _this$centralPlant$sc6;
       var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
       // Use centralized validation for component addition parameters
       var existingIds = this.getComponentIds();
@@ -857,7 +921,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
 
       // Validate scene availability
-      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.scene);
+      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.scene);
       if (!sceneValidation.isValid) {
         return false;
       }
@@ -876,7 +940,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false;
       }
       try {
-        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc6, _componentData$childr3, _componentData$defaul;
+        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc7, _componentData$childr3, _componentData$defaul;
         // Generate a unique component ID if not provided
         var componentId = options.customId || this.generateUniqueComponentId(libraryId);
 
@@ -988,7 +1052,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         componentModel.updateMatrixWorld(true);
 
         // Check if component is underground and fix if needed (based on settings)
-        var checkUnderground = (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.managers) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.settingsManager) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.getSetting('scene', 'checkUnderground');
+        var checkUnderground = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.managers) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.settingsManager) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.getSetting('scene', 'checkUnderground');
         if (checkUnderground) {
           var wasFixed = this.fixUndergroundComponent(componentModel);
           if (wasFixed) {
@@ -1086,8 +1150,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         // responds to tooltip-driven state changes immediately after drop.
         // (The scene-load path uses _processBehaviors instead, which runs on loadSceneData.)
         if ((_componentData$defaul = componentData.defaultBehaviors) !== null && _componentData$defaul !== void 0 && _componentData$defaul.length) {
-          var _this$centralPlant$sc7, _som$registerBehavior;
-          var som = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.sceneOperationsManager;
+          var _this$centralPlant$sc8, _som$registerBehavior;
+          var som = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.sceneOperationsManager;
           som === null || som === void 0 || (_som$registerBehavior = som.registerBehaviorsForComponentInstance) === null || _som$registerBehavior === void 0 || _som$registerBehavior.call(som, componentData, componentId);
         }
 
@@ -1149,9 +1213,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "deleteComponent",
     value: function deleteComponent(componentId) {
-      var _this$centralPlant$sc8;
+      var _this$centralPlant$sc9;
       // Check if component manager is available
-      var componentManager = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.componentManager;
+      var componentManager = (_this$centralPlant$sc9 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc9 === void 0 ? void 0 : _this$centralPlant$sc9.componentManager;
       if (!componentManager) {
         console.error('❌ deleteComponent(): Component manager not available');
         return false;
@@ -1226,8 +1290,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
       var componentIds = [];
       this.centralPlant.sceneViewer.scene.traverse(function (child) {
-        var _child$userData;
-        if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'component') {
+        var _child$userData2;
+        if (((_child$userData2 = child.userData) === null || _child$userData2 === void 0 ? void 0 : _child$userData2.objectType) === 'component') {
           componentIds.push(child.uuid || child.userData.originalUuid);
         }
       });

package/dist/cjs/src/managers/behaviors/BehaviorManager.js

@@ -264,7 +264,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         if (_this4._testCondition(condition.when, value)) {
           if (Array.isArray(condition.actions)) {
             condition.actions.forEach(function (action) {
-              _this4._applyAction(output, action.set, action.value);
+              _this4._applyAction(output, action.set, action.value, action.relative === true);
             });
           }
         }
@@ -342,6 +342,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "_applyAction",
     value: function _applyAction(object, propertyPath, value) {
+      var relative = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
       if (!object || typeof propertyPath !== 'string') return;
       var parts = propertyPath.split('.');
 
@@ -367,6 +368,15 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         return;
       }
 
+      // If relative, capture the mesh's original value on first execution and offset from it.
+      if (relative) {
+        var baselineKey = "_baseline_".concat(propertyPath.replace(/\./g, '_'));
+        if (!(baselineKey in object.userData)) {
+          object.userData[baselineKey] = target[lastKey];
+        }
+        value = object.userData[baselineKey] + parseFloat(value);
+      }
+
       // THREE.Color objects must be mutated via .set() rather than replaced
       var existing = target[lastKey];
       if (existing && existing.isColor && typeof value === 'string') {

package/dist/cjs/src/managers/controls/componentDragManager.js

@@ -345,7 +345,7 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
     key: "_attachIODeviceModelsToPreview",
     value: (function () {
       var _attachIODeviceModelsToPreview2 = _rollupPluginBabelHelpers.asyncToGenerator(/*#__PURE__*/_rollupPluginBabelHelpers.regenerator().m(function _callee3(parentObject, componentData, modelPreloader) {
-        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t3;
+        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t3;
         return _rollupPluginBabelHelpers.regenerator().w(function (_context3) {
           while (1) switch (_context3.n) {
             case 0:
@@ -420,6 +420,13 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
                 deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
               }
 
+              // Apply face-based rotation (stored in degrees, XYZ Euler order)
+              if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+                rot = attachment.attachmentPoint.rotation;
+                deg2rad = Math.PI / 180;
+                deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+              }
+
               // IO device models use their natural (1:1) scale — the stored
               // attachmentPoint.scale value is for the connector marker sphere.
               deviceModel.scale.setScalar(1);

package/dist/cjs/src/utils/ioDeviceUtils.js

@@ -27,7 +27,7 @@ function attachIODevicesToComponent(_x, _x2, _x3, _x4) {
 }
 function _attachIODevicesToComponent() {
   _attachIODevicesToComponent = _rollupPluginBabelHelpers.asyncToGenerator(/*#__PURE__*/_rollupPluginBabelHelpers.regenerator().m(function _callee(componentModel, componentData, modelPreloader, parentComponentId) {
-    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t, _t2;
+    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t, _t2;
     return _rollupPluginBabelHelpers.regenerator().w(function (_context) {
       while (1) switch (_context.n) {
         case 0:
@@ -128,6 +128,13 @@ function _attachIODevicesToComponent() {
             deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
           }
 
+          // Apply face-based rotation (stored in degrees, XYZ Euler order)
+          if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+            rot = attachment.attachmentPoint.rotation;
+            deg2rad = Math.PI / 180;
+            deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+          }
+
           // IO device models are authored at the same real-world unit scale
           // as the host component, so keep them at their natural (1:1) size.
           // Note: attachmentPoint.scale is the connector marker sphere size,

package/dist/esm/src/core/centralPlant.js

@@ -5,6 +5,22 @@ import { DisposalUtilities } from '../utils/DisposalUtilities.js';
 import { CentralPlantInternals } from './centralPlantInternals.js';
 import '../rendering/modelPreloader.js';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction compatibility helper (module-level, no class dependency)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns true if the two flow directions are compatible for a connection.
+ * @param {string} fromFlow - 'in' | 'out' | 'bi'
+ * @param {string} toFlow   - 'in' | 'out' | 'bi'
+ * @returns {boolean}
+ */
+function _areFlowsCompatible(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  // in ↔ out are compatible; in → in and out → out are not
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlant class that manages all scene utility instances and provides public API
  * 
@@ -15,7 +31,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.4
+   * @version 0.2.8
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -948,6 +964,107 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       return availableConnectorIds;
     }
 
+    /**
+     * Get available connectors with their flow direction metadata.
+     * Same filtering logic as getAvailableConnections() but returns objects instead of strings.
+     * @returns {Array<{id: string, flow: string}>} Array of connector info objects.
+     *   flow is one of 'in', 'out', 'bi'. Defaults to 'bi' if not set in userData.
+     * @example
+     * const infos = centralPlant.getAvailableConnectionsInfo()
+     * // [{ id: 'PUMP-1-CONNECTOR-1', flow: 'out' }, ...]
+     */
+  }, {
+    key: "getAvailableConnectionsInfo",
+    value: function getAvailableConnectionsInfo() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Scene viewer or current scene data not available');
+        return [];
+      }
+      var sceneData = this.sceneViewer.currentSceneData;
+      if (!sceneData.scene || !sceneData.scene.children) {
+        console.warn('⚠️ getAvailableConnectionsInfo(): Invalid scene data structure');
+        return [];
+      }
+      var allConnectorInfos = [];
+      sceneData.scene.children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              allConnectorInfos.push({
+                id: child.uuid,
+                flow: child.userData.flow || 'bi'
+              });
+            }
+          });
+        }
+      });
+      var existingConnections = this.getConnections();
+      var usedConnectorIds = new Set();
+      existingConnections.forEach(function (connection) {
+        if (connection.from) usedConnectorIds.add(connection.from);
+        if (connection.to) usedConnectorIds.add(connection.to);
+      });
+      return allConnectorInfos.filter(function (info) {
+        return !usedConnectorIds.has(info.id);
+      });
+    }
+
+    /**
+     * Validate all connections in the current scene for flow direction compatibility.
+     * @returns {{ valid: Array<Object>, invalid: Array<{connection: Object, reason: string}> }}
+     * @example
+     * const result = centralPlant.validateConnections()
+     * result.invalid.forEach(({ connection, reason }) => console.warn(reason, connection))
+     */
+  }, {
+    key: "validateConnections",
+    value: function validateConnections() {
+      if (!this.sceneViewer || !this.sceneViewer.currentSceneData) {
+        console.warn('⚠️ validateConnections(): Scene viewer or current scene data not available');
+        return {
+          valid: [],
+          invalid: []
+        };
+      }
+      var connections = this.getConnections();
+      var sceneData = this.sceneViewer.currentSceneData;
+
+      // Build lookup map: connectorId → flow
+      var flowMap = {};
+      var scene = sceneData.scene || {};
+      var children = scene.children || [];
+      children.forEach(function (component) {
+        if (component.children && Array.isArray(component.children)) {
+          component.children.forEach(function (child) {
+            if (child.userData && child.userData.objectType === 'connector' && child.uuid) {
+              flowMap[child.uuid] = child.userData.flow || 'bi';
+            }
+          });
+        }
+      });
+      var valid = [];
+      var invalid = [];
+      connections.forEach(function (connection) {
+        var fromFlow = flowMap[connection.from] || 'bi';
+        var toFlow = flowMap[connection.to] || 'bi';
+        if (_areFlowsCompatible(fromFlow, toFlow)) {
+          valid.push(connection);
+        } else {
+          var reason = "Incompatible flow directions: connector '".concat(connection.from, "' is '").concat(fromFlow, "' and connector '").concat(connection.to, "' is '").concat(toFlow, "' \u2014 ").concat(fromFlow, " \u2192 ").concat(toFlow, " is not allowed");
+          console.warn("\u26A0\uFE0F validateConnections(): ".concat(reason));
+          invalid.push({
+            connection: connection,
+            reason: reason
+          });
+        }
+      });
+      console.log("\u2705 validateConnections(): ".concat(valid.length, " valid, ").concat(invalid.length, " invalid connections"));
+      return {
+        valid: valid,
+        invalid: invalid
+      };
+    }
+
     // ─────────────────────────────────────────────────────────────────────────
     // BEHAVIORS API
     // ─────────────────────────────────────────────────────────────────────────

package/dist/esm/src/core/centralPlantInternals.js

@@ -26,6 +26,59 @@ import { generateUuidFromName, getHardcodedUuid, findObjectByHardcodedUuid, gene
 import { attachIODevicesToComponent } from '../utils/ioDeviceUtils.js';
 import modelPreloader from '../rendering/modelPreloader.js';
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Flow-direction helpers (module-level)
+// ─────────────────────────────────────────────────────────────────────────────
+
+/**
+ * Returns the flow direction of a connector from the current scene data.
+ * @param {Object} sceneData - currentSceneData object
+ * @param {string} connectorId
+ * @returns {'in'|'out'|'bi'} Defaults to 'bi' if not set.
+ */
+function _getConnectorFlow(sceneData, connectorId) {
+  var _sceneData$scene;
+  var children = (sceneData === null || sceneData === void 0 || (_sceneData$scene = sceneData.scene) === null || _sceneData$scene === void 0 ? void 0 : _sceneData$scene.children) || [];
+  var _iterator = _createForOfIteratorHelper(children),
+    _step;
+  try {
+    for (_iterator.s(); !(_step = _iterator.n()).done;) {
+      var component = _step.value;
+      var _iterator2 = _createForOfIteratorHelper(component.children || []),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _child$userData;
+          var child = _step2.value;
+          if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'connector' && child.uuid === connectorId) {
+            return child.userData.flow || 'bi';
+          }
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+  } catch (err) {
+    _iterator.e(err);
+  } finally {
+    _iterator.f();
+  }
+  return 'bi';
+}
+
+/**
+ * Returns true if fromFlow → toFlow is a valid connection.
+ * @param {'in'|'out'|'bi'} fromFlow
+ * @param {'in'|'out'|'bi'} toFlow
+ * @returns {boolean}
+ */
+function _areFlowsCompatible(fromFlow, toFlow) {
+  if (fromFlow === 'bi' || toFlow === 'bi') return true;
+  return fromFlow !== toFlow;
+}
+
 /**
  * CentralPlantInternals class containing internal methods and functionality
  */
@@ -477,12 +530,12 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       console.log("\uD83D\uDD27 Translating ".concat(selectedObjects.length, " selected object(s) on ").concat(axis, " axis by ").concat(value));
 
       // Translate each selected object using the appropriate method
-      var _iterator = _createForOfIteratorHelper(selectedObjects),
-        _step;
+      var _iterator3 = _createForOfIteratorHelper(selectedObjects),
+        _step3;
       try {
-        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
           var _obj$userData;
-          var obj = _step.value;
+          var obj = _step3.value;
           var objectType = (_obj$userData = obj.userData) === null || _obj$userData === void 0 ? void 0 : _obj$userData.objectType;
           var objectId = obj.uuid;
           var success = false;
@@ -509,9 +562,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
           }
         }
       } catch (err) {
-        _iterator.e(err);
+        _iterator3.e(err);
       } finally {
-        _iterator.f();
+        _iterator3.f();
       }
       result.success = result.translatedCount === result.totalCount;
       if (result.success) {
@@ -695,7 +748,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addConnection",
     value: function addConnection(fromConnectorId, toConnectorId) {
-      var _this$centralPlant$sc4;
+      var _this$centralPlant$sc4, _this$centralPlant$sc5;
       // Use centralized validation for connection parameters
       var existingConnections = ((_this$centralPlant$sc4 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc4 === void 0 || (_this$centralPlant$sc4 = _this$centralPlant$sc4.currentSceneData) === null || _this$centralPlant$sc4 === void 0 ? void 0 : _this$centralPlant$sc4.connections) || [];
       var validation = this.validator.validateConnectionParams(fromConnectorId, toConnectorId, existingConnections);
@@ -703,6 +756,17 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false; // Validator already logged the error
       }
 
+      // Validate flow direction compatibility
+      var sceneData = (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.currentSceneData;
+      if (sceneData) {
+        var fromFlow = _getConnectorFlow(sceneData, fromConnectorId);
+        var toFlow = _getConnectorFlow(sceneData, toConnectorId);
+        if (!_areFlowsCompatible(fromFlow, toFlow)) {
+          console.error("\u274C addConnection(): Incompatible flow directions \u2014 '".concat(fromConnectorId, "' is '").concat(fromFlow, "' and '").concat(toConnectorId, "' is '").concat(toFlow, "'. ") + "'".concat(fromFlow, "' \u2192 '").concat(toFlow, "' connections are not allowed."));
+          return false;
+        }
+      }
+
       // Validate scene availability
       var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer);
       if (!sceneValidation.isValid) {
@@ -823,7 +887,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "addComponent",
     value: function addComponent(libraryId) {
-      var _this$centralPlant$sc5;
+      var _this$centralPlant$sc6;
       var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
       // Use centralized validation for component addition parameters
       var existingIds = this.getComponentIds();
@@ -833,7 +897,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
 
       // Validate scene availability
-      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc5 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc5 === void 0 ? void 0 : _this$centralPlant$sc5.scene);
+      var sceneValidation = this.validator.validateSceneViewer(this.centralPlant.sceneViewer, (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.scene);
       if (!sceneValidation.isValid) {
         return false;
       }
@@ -852,7 +916,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         return false;
       }
       try {
-        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc6, _componentData$childr3, _componentData$defaul;
+        var _componentData$childr, _componentData$childr2, _this$centralPlant$sc7, _componentData$childr3, _componentData$defaul;
         // Generate a unique component ID if not provided
         var componentId = options.customId || this.generateUniqueComponentId(libraryId);
 
@@ -964,7 +1028,7 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         componentModel.updateMatrixWorld(true);
 
         // Check if component is underground and fix if needed (based on settings)
-        var checkUnderground = (_this$centralPlant$sc6 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.managers) === null || _this$centralPlant$sc6 === void 0 || (_this$centralPlant$sc6 = _this$centralPlant$sc6.settingsManager) === null || _this$centralPlant$sc6 === void 0 ? void 0 : _this$centralPlant$sc6.getSetting('scene', 'checkUnderground');
+        var checkUnderground = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.managers) === null || _this$centralPlant$sc7 === void 0 || (_this$centralPlant$sc7 = _this$centralPlant$sc7.settingsManager) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.getSetting('scene', 'checkUnderground');
         if (checkUnderground) {
           var wasFixed = this.fixUndergroundComponent(componentModel);
           if (wasFixed) {
@@ -1062,8 +1126,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
         // responds to tooltip-driven state changes immediately after drop.
         // (The scene-load path uses _processBehaviors instead, which runs on loadSceneData.)
         if ((_componentData$defaul = componentData.defaultBehaviors) !== null && _componentData$defaul !== void 0 && _componentData$defaul.length) {
-          var _this$centralPlant$sc7, _som$registerBehavior;
-          var som = (_this$centralPlant$sc7 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc7 === void 0 ? void 0 : _this$centralPlant$sc7.sceneOperationsManager;
+          var _this$centralPlant$sc8, _som$registerBehavior;
+          var som = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.sceneOperationsManager;
           som === null || som === void 0 || (_som$registerBehavior = som.registerBehaviorsForComponentInstance) === null || _som$registerBehavior === void 0 || _som$registerBehavior.call(som, componentData, componentId);
         }
 
@@ -1125,9 +1189,9 @@ var CentralPlantInternals = /*#__PURE__*/function () {
   }, {
     key: "deleteComponent",
     value: function deleteComponent(componentId) {
-      var _this$centralPlant$sc8;
+      var _this$centralPlant$sc9;
       // Check if component manager is available
-      var componentManager = (_this$centralPlant$sc8 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc8 === void 0 ? void 0 : _this$centralPlant$sc8.componentManager;
+      var componentManager = (_this$centralPlant$sc9 = this.centralPlant.sceneViewer) === null || _this$centralPlant$sc9 === void 0 ? void 0 : _this$centralPlant$sc9.componentManager;
       if (!componentManager) {
         console.error('❌ deleteComponent(): Component manager not available');
         return false;
@@ -1202,8 +1266,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       }
       var componentIds = [];
       this.centralPlant.sceneViewer.scene.traverse(function (child) {
-        var _child$userData;
-        if (((_child$userData = child.userData) === null || _child$userData === void 0 ? void 0 : _child$userData.objectType) === 'component') {
+        var _child$userData2;
+        if (((_child$userData2 = child.userData) === null || _child$userData2 === void 0 ? void 0 : _child$userData2.objectType) === 'component') {
           componentIds.push(child.uuid || child.userData.originalUuid);
         }
       });

package/dist/esm/src/managers/behaviors/BehaviorManager.js

@@ -260,7 +260,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         if (_this4._testCondition(condition.when, value)) {
           if (Array.isArray(condition.actions)) {
             condition.actions.forEach(function (action) {
-              _this4._applyAction(output, action.set, action.value);
+              _this4._applyAction(output, action.set, action.value, action.relative === true);
             });
           }
         }
@@ -338,6 +338,7 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "_applyAction",
     value: function _applyAction(object, propertyPath, value) {
+      var relative = arguments.length > 3 && arguments[3] !== undefined ? arguments[3] : false;
       if (!object || typeof propertyPath !== 'string') return;
       var parts = propertyPath.split('.');
 
@@ -363,6 +364,15 @@ var BehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
         return;
       }
 
+      // If relative, capture the mesh's original value on first execution and offset from it.
+      if (relative) {
+        var baselineKey = "_baseline_".concat(propertyPath.replace(/\./g, '_'));
+        if (!(baselineKey in object.userData)) {
+          object.userData[baselineKey] = target[lastKey];
+        }
+        value = object.userData[baselineKey] + parseFloat(value);
+      }
+
       // THREE.Color objects must be mutated via .set() rather than replaced
       var existing = target[lastKey];
       if (existing && existing.isColor && typeof value === 'string') {

package/dist/esm/src/managers/controls/componentDragManager.js

@@ -321,7 +321,7 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
     key: "_attachIODeviceModelsToPreview",
     value: (function () {
       var _attachIODeviceModelsToPreview2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee3(parentObject, componentData, modelPreloader) {
-        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t3;
+        var _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t3;
         return _regenerator().w(function (_context3) {
           while (1) switch (_context3.n) {
             case 0:
@@ -396,6 +396,13 @@ var ComponentDragManager = /*#__PURE__*/function (_BaseDisposable) {
                 deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
               }
 
+              // Apply face-based rotation (stored in degrees, XYZ Euler order)
+              if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+                rot = attachment.attachmentPoint.rotation;
+                deg2rad = Math.PI / 180;
+                deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+              }
+
               // IO device models use their natural (1:1) scale — the stored
               // attachmentPoint.scale value is for the connector marker sphere.
               deviceModel.scale.setScalar(1);

package/dist/esm/src/utils/ioDeviceUtils.js

@@ -23,7 +23,7 @@ function attachIODevicesToComponent(_x, _x2, _x3, _x4) {
 }
 function _attachIODevicesToComponent() {
   _attachIODevicesToComponent = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee(componentModel, componentData, modelPreloader, parentComponentId) {
-    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, _t, _t2;
+    var attachedDevices, _i, _Object$entries, _Object$entries$_i, attachmentId, attachment, _modelPreloader$compo, _deviceData$ioConfig, _deviceData$ioConfig2, _deviceData$ioConfig3, _attachment$attachmen, _attachment$attachmen2, deviceData, cachedDevice, _modelPreloader$loadi, deviceModel, pos, rot, deg2rad, _t, _t2;
     return _regenerator().w(function (_context) {
       while (1) switch (_context.n) {
         case 0:
@@ -124,6 +124,13 @@ function _attachIODevicesToComponent() {
             deviceModel.position.set(pos.x || 0, pos.y || 0, pos.z || 0);
           }
 
+          // Apply face-based rotation (stored in degrees, XYZ Euler order)
+          if ((_attachment$attachmen2 = attachment.attachmentPoint) !== null && _attachment$attachmen2 !== void 0 && _attachment$attachmen2.rotation) {
+            rot = attachment.attachmentPoint.rotation;
+            deg2rad = Math.PI / 180;
+            deviceModel.rotation.set((rot.x || 0) * deg2rad, (rot.y || 0) * deg2rad, (rot.z || 0) * deg2rad, 'XYZ');
+          }
+
           // IO device models are authored at the same real-world unit scale
           // as the host component, so keep them at their natural (1:1) size.
           // Note: attachmentPoint.scale is the connector marker sphere size,

package/dist/index.d.ts

@@ -5,6 +5,25 @@
  * organized by their functional categories.
  */
 
+// ─── Connector flow types ─────────────────────────────────────────────────────
+
+/** The flow direction of a connector port. */
+export type FlowDirection = 'in' | 'out' | 'bi'
+
+/** Connector descriptor returned by getAvailableConnectionsInfo(). */
+export interface ConnectorInfo {
+  /** The connector's UUID as it appears in the scene JSON. */
+  id: string
+  /** Flow direction. Defaults to 'bi' for connectors that do not declare one. */
+  flow: FlowDirection
+}
+
+/** Result of validateConnections(). */
+export interface ConnectionValidationResult {
+  valid: Array<{ from: string; to: string }>
+  invalid: Array<{ connection: { from: string; to: string }; reason: string }>
+}
+
 // ─── I/O Device types ────────────────────────────────────────────────────────
 
 export interface IoDeviceState {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2112-lab/central-plant",
-  "version": "0.2.4",
+  "version": "0.2.8",
   "description": "Utility modules for the Central Plant Application",
   "main": "dist/bundle/index.js",
   "module": "dist/esm/src/index.js",