@2112-lab/central-plant 0.2.3 → 0.2.4

package/dist/bundle/index.js

@@ -37214,7 +37214,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.3
+   * @version 0.2.4
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -38248,6 +38248,69 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       bm.triggerState(attachmentId, stateId, value, parentUuid);
     }
 
+    /**
+     * Set the state of an I/O device instance in the Three.js scene.
+     *
+     * This is the primary public API for driving IO device state changes from
+     * external code (real-time data feeds, AI agents, automated tests, etc.).
+     * It performs three coordinated actions in order:
+     *   1. Persists the new value through the state adapter (Vuex in sandbox,
+     *      or any custom adapter injected via componentTooltipManager.configure())
+     *      so that the host application's store stays consistent.
+     *   2. Evaluates all behaviors whose input matches this (attachmentId, stateId)
+     *      pair and applies the resulting property changes to Three.js meshes.
+     *   3. Emits an 'io-device-state-changed' event on the sceneViewer so that
+     *      host applications without a Vuex store (e.g. cp3d-viewer) can react.
+     *
+     * @param {string} attachmentId - The attachment ID of the IO device (matches
+     *   the `attachmentId` stored in the Three.js object's userData)
+     * @param {string} stateId - The data-point / state ID on the device (e.g. 'power', 'level')
+     * @param {*} value - The new state value (boolean, number, string, etc.)
+     * @param {string} [parentUuid] - UUID of the parent component instance.
+     *   Required when multiple instances of the same smart component share the
+     *   same attachmentId — prevents cross-instance state bleed.
+     * @returns {boolean} True if the behavior system was reached; false if unavailable.
+     * @example
+     * // Toggle a push-button on a specific pump instance
+     * centralPlant.setIoDeviceState('pump-push-button-01', 'power', true, pumpUuid)
+     *
+     * // Drive an analog level sensor (no parentUuid needed when only one instance)
+     * centralPlant.setIoDeviceState('chiller-level-sensor-01', 'level', 0.75)
+     */
+  }, {
+    key: "setIoDeviceState",
+    value: function setIoDeviceState(attachmentId, stateId, value, parentUuid) {
+      var _this$sceneViewer0, _this$sceneViewer1, _this$sceneViewer10;
+      var bm = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 || (_this$sceneViewer0 = _this$sceneViewer0.managers) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.behaviorManager;
+      if (!bm) {
+        console.warn('⚠️ setIoDeviceState(): BehaviorManager not available');
+        return false;
+      }
+
+      // 1. Persist via state adapter if one has been configured
+      var stateAdapter = (_this$sceneViewer1 = this.sceneViewer) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.managers) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.componentTooltipManager) === null || _this$sceneViewer1 === void 0 ? void 0 : _this$sceneViewer1._stateAdapter;
+      if (stateAdapter !== null && stateAdapter !== void 0 && stateAdapter.setState) {
+        var scopedKey = parentUuid ? "".concat(parentUuid, "::").concat(attachmentId) : attachmentId;
+        try {
+          stateAdapter.setState(scopedKey, stateId, value);
+        } catch (err) {
+          console.warn('⚠️ setIoDeviceState(): stateAdapter.setState() threw:', err);
+        }
+      }
+
+      // 2. Apply Three.js behavior changes
+      bm.triggerState(attachmentId, stateId, value, parentUuid);
+
+      // 3. Emit event for host apps that don't use the state adapter (e.g. cp3d-viewer)
+      (_this$sceneViewer10 = this.sceneViewer) === null || _this$sceneViewer10 === void 0 || _this$sceneViewer10.emit('io-device-state-changed', {
+        attachmentId: attachmentId,
+        stateId: stateId,
+        value: value,
+        parentUuid: parentUuid || null
+      });
+      return true;
+    }
+
     /**
      * Return all io-device attachments present in the current Three.js scene.
      * Each entry carries the attachmentId, an optional label, and the parent
@@ -38261,8 +38324,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "getSceneAttachments",
     value: function getSceneAttachments() {
-      var _this$sceneViewer0;
-      var scene = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.scene;
+      var _this$sceneViewer11;
+      var scene = (_this$sceneViewer11 = this.sceneViewer) === null || _this$sceneViewer11 === void 0 ? void 0 : _this$sceneViewer11.scene;
       if (!scene) return [];
       var results = [];
       scene.traverse(function (obj) {

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

@@ -19,7 +19,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.3
+   * @version 0.2.4
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -1053,6 +1053,69 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       bm.triggerState(attachmentId, stateId, value, parentUuid);
     }
 
+    /**
+     * Set the state of an I/O device instance in the Three.js scene.
+     *
+     * This is the primary public API for driving IO device state changes from
+     * external code (real-time data feeds, AI agents, automated tests, etc.).
+     * It performs three coordinated actions in order:
+     *   1. Persists the new value through the state adapter (Vuex in sandbox,
+     *      or any custom adapter injected via componentTooltipManager.configure())
+     *      so that the host application's store stays consistent.
+     *   2. Evaluates all behaviors whose input matches this (attachmentId, stateId)
+     *      pair and applies the resulting property changes to Three.js meshes.
+     *   3. Emits an 'io-device-state-changed' event on the sceneViewer so that
+     *      host applications without a Vuex store (e.g. cp3d-viewer) can react.
+     *
+     * @param {string} attachmentId - The attachment ID of the IO device (matches
+     *   the `attachmentId` stored in the Three.js object's userData)
+     * @param {string} stateId - The data-point / state ID on the device (e.g. 'power', 'level')
+     * @param {*} value - The new state value (boolean, number, string, etc.)
+     * @param {string} [parentUuid] - UUID of the parent component instance.
+     *   Required when multiple instances of the same smart component share the
+     *   same attachmentId — prevents cross-instance state bleed.
+     * @returns {boolean} True if the behavior system was reached; false if unavailable.
+     * @example
+     * // Toggle a push-button on a specific pump instance
+     * centralPlant.setIoDeviceState('pump-push-button-01', 'power', true, pumpUuid)
+     *
+     * // Drive an analog level sensor (no parentUuid needed when only one instance)
+     * centralPlant.setIoDeviceState('chiller-level-sensor-01', 'level', 0.75)
+     */
+  }, {
+    key: "setIoDeviceState",
+    value: function setIoDeviceState(attachmentId, stateId, value, parentUuid) {
+      var _this$sceneViewer0, _this$sceneViewer1, _this$sceneViewer10;
+      var bm = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 || (_this$sceneViewer0 = _this$sceneViewer0.managers) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.behaviorManager;
+      if (!bm) {
+        console.warn('⚠️ setIoDeviceState(): BehaviorManager not available');
+        return false;
+      }
+
+      // 1. Persist via state adapter if one has been configured
+      var stateAdapter = (_this$sceneViewer1 = this.sceneViewer) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.managers) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.componentTooltipManager) === null || _this$sceneViewer1 === void 0 ? void 0 : _this$sceneViewer1._stateAdapter;
+      if (stateAdapter !== null && stateAdapter !== void 0 && stateAdapter.setState) {
+        var scopedKey = parentUuid ? "".concat(parentUuid, "::").concat(attachmentId) : attachmentId;
+        try {
+          stateAdapter.setState(scopedKey, stateId, value);
+        } catch (err) {
+          console.warn('⚠️ setIoDeviceState(): stateAdapter.setState() threw:', err);
+        }
+      }
+
+      // 2. Apply Three.js behavior changes
+      bm.triggerState(attachmentId, stateId, value, parentUuid);
+
+      // 3. Emit event for host apps that don't use the state adapter (e.g. cp3d-viewer)
+      (_this$sceneViewer10 = this.sceneViewer) === null || _this$sceneViewer10 === void 0 || _this$sceneViewer10.emit('io-device-state-changed', {
+        attachmentId: attachmentId,
+        stateId: stateId,
+        value: value,
+        parentUuid: parentUuid || null
+      });
+      return true;
+    }
+
     /**
      * Return all io-device attachments present in the current Three.js scene.
      * Each entry carries the attachmentId, an optional label, and the parent
@@ -1066,8 +1129,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "getSceneAttachments",
     value: function getSceneAttachments() {
-      var _this$sceneViewer0;
-      var scene = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.scene;
+      var _this$sceneViewer11;
+      var scene = (_this$sceneViewer11 = this.sceneViewer) === null || _this$sceneViewer11 === void 0 ? void 0 : _this$sceneViewer11.scene;
       if (!scene) return [];
       var results = [];
       scene.traverse(function (obj) {

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

@@ -15,7 +15,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.2.3
+   * @version 0.2.4
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -1049,6 +1049,69 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       bm.triggerState(attachmentId, stateId, value, parentUuid);
     }
 
+    /**
+     * Set the state of an I/O device instance in the Three.js scene.
+     *
+     * This is the primary public API for driving IO device state changes from
+     * external code (real-time data feeds, AI agents, automated tests, etc.).
+     * It performs three coordinated actions in order:
+     *   1. Persists the new value through the state adapter (Vuex in sandbox,
+     *      or any custom adapter injected via componentTooltipManager.configure())
+     *      so that the host application's store stays consistent.
+     *   2. Evaluates all behaviors whose input matches this (attachmentId, stateId)
+     *      pair and applies the resulting property changes to Three.js meshes.
+     *   3. Emits an 'io-device-state-changed' event on the sceneViewer so that
+     *      host applications without a Vuex store (e.g. cp3d-viewer) can react.
+     *
+     * @param {string} attachmentId - The attachment ID of the IO device (matches
+     *   the `attachmentId` stored in the Three.js object's userData)
+     * @param {string} stateId - The data-point / state ID on the device (e.g. 'power', 'level')
+     * @param {*} value - The new state value (boolean, number, string, etc.)
+     * @param {string} [parentUuid] - UUID of the parent component instance.
+     *   Required when multiple instances of the same smart component share the
+     *   same attachmentId — prevents cross-instance state bleed.
+     * @returns {boolean} True if the behavior system was reached; false if unavailable.
+     * @example
+     * // Toggle a push-button on a specific pump instance
+     * centralPlant.setIoDeviceState('pump-push-button-01', 'power', true, pumpUuid)
+     *
+     * // Drive an analog level sensor (no parentUuid needed when only one instance)
+     * centralPlant.setIoDeviceState('chiller-level-sensor-01', 'level', 0.75)
+     */
+  }, {
+    key: "setIoDeviceState",
+    value: function setIoDeviceState(attachmentId, stateId, value, parentUuid) {
+      var _this$sceneViewer0, _this$sceneViewer1, _this$sceneViewer10;
+      var bm = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 || (_this$sceneViewer0 = _this$sceneViewer0.managers) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.behaviorManager;
+      if (!bm) {
+        console.warn('⚠️ setIoDeviceState(): BehaviorManager not available');
+        return false;
+      }
+
+      // 1. Persist via state adapter if one has been configured
+      var stateAdapter = (_this$sceneViewer1 = this.sceneViewer) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.managers) === null || _this$sceneViewer1 === void 0 || (_this$sceneViewer1 = _this$sceneViewer1.componentTooltipManager) === null || _this$sceneViewer1 === void 0 ? void 0 : _this$sceneViewer1._stateAdapter;
+      if (stateAdapter !== null && stateAdapter !== void 0 && stateAdapter.setState) {
+        var scopedKey = parentUuid ? "".concat(parentUuid, "::").concat(attachmentId) : attachmentId;
+        try {
+          stateAdapter.setState(scopedKey, stateId, value);
+        } catch (err) {
+          console.warn('⚠️ setIoDeviceState(): stateAdapter.setState() threw:', err);
+        }
+      }
+
+      // 2. Apply Three.js behavior changes
+      bm.triggerState(attachmentId, stateId, value, parentUuid);
+
+      // 3. Emit event for host apps that don't use the state adapter (e.g. cp3d-viewer)
+      (_this$sceneViewer10 = this.sceneViewer) === null || _this$sceneViewer10 === void 0 || _this$sceneViewer10.emit('io-device-state-changed', {
+        attachmentId: attachmentId,
+        stateId: stateId,
+        value: value,
+        parentUuid: parentUuid || null
+      });
+      return true;
+    }
+
     /**
      * Return all io-device attachments present in the current Three.js scene.
      * Each entry carries the attachmentId, an optional label, and the parent
@@ -1062,8 +1125,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "getSceneAttachments",
     value: function getSceneAttachments() {
-      var _this$sceneViewer0;
-      var scene = (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.scene;
+      var _this$sceneViewer11;
+      var scene = (_this$sceneViewer11 = this.sceneViewer) === null || _this$sceneViewer11 === void 0 ? void 0 : _this$sceneViewer11.scene;
       if (!scene) return [];
       var results = [];
       scene.traverse(function (obj) {

package/package.json

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