@2112-lab/central-plant 0.3.28 → 0.3.30

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

@@ -0,0 +1,648 @@
+import { inherits as _inherits, createClass as _createClass, createForOfIteratorHelper as _createForOfIteratorHelper, slicedToArray as _slicedToArray, toConsumableArray as _toConsumableArray, superPropGet as _superPropGet, classCallCheck as _classCallCheck, callSuper as _callSuper } from '../../../_virtual/_rollupPluginBabelHelpers.js';
+import * as THREE from 'three';
+import { BaseDisposable } from '../../core/baseDisposable.js';
+
+var IoBehaviorManager = /*#__PURE__*/function (_BaseDisposable) {
+  function IoBehaviorManager(sceneViewer) {
+    var _this;
+    _classCallCheck(this, IoBehaviorManager);
+    _this = _callSuper(this, IoBehaviorManager);
+    _this.sceneViewer = sceneViewer;
+
+    /**
+     * Map: `${parentUuid}::${attachmentId}` → Array<{
+     *   anim: Object,
+     *   mesh: THREE.Object3D,
+     *   origPos: THREE.Vector3,
+     *   origRot: THREE.Euler
+     * }>
+     */
+    _this._entries = new Map();
+    return _this;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────
+  // PUBLIC API
+  // ─────────────────────────────────────────────────────────────────────────
+
+  /**
+   * Register animation entries for one attached I/O device.
+   * Should be called after the device GLB has been merged into the scene
+   * so that mesh references are live.
+   *
+   * @param {string} attachmentId - The attachment key (e.g. 'attch-switch-01')
+   * @param {Object|Array} behaviorConfig - Serialized config; either the full object
+   *   { behaviors: [...] } or a plain array of behavior entries.
+   * @param {THREE.Object3D} deviceModelRoot - The device's root Object3D as added to the scene
+   * @param {string} parentUuid - UUID of the host component Object3D
+   */
+  _inherits(IoBehaviorManager, _BaseDisposable);
+  return _createClass(IoBehaviorManager, [{
+    key: "loadBehaviors",
+    value: function loadBehaviors(attachmentId, behaviorConfig, deviceModelRoot, parentUuid) {
+      var _behaviorConfig$behav;
+      if (!behaviorConfig || !deviceModelRoot) return;
+      var anims = Array.isArray(behaviorConfig) ? behaviorConfig : (_behaviorConfig$behav = behaviorConfig.behaviors) !== null && _behaviorConfig$behav !== void 0 ? _behaviorConfig$behav : [];
+      if (!anims.length) return;
+      var key = this._key(parentUuid, attachmentId);
+      var entries = [];
+
+      // Capture the device root's world orientation once so each entry can
+      // convert the configured axis from device-local space to world space.
+      var deviceWorldQuat = new THREE.Quaternion();
+      deviceModelRoot.getWorldQuaternion(deviceWorldQuat);
+
+      // Compute the model's native max dimension so rotAxisOffset values (stored
+      // in dialog-viewer-world units, where the model is normalised to 1 unit)
+      // can be scaled to runtime-world units.  viewerMaxDim = 1 / ns_viewer.
+      var _deviceBox = new THREE.Box3().setFromObject(deviceModelRoot);
+      var _deviceSize = new THREE.Vector3();
+      _deviceBox.getSize(_deviceSize);
+      var viewerMaxDim = Math.max(_deviceSize.x, _deviceSize.y, _deviceSize.z) || 1;
+      var _iterator = _createForOfIteratorHelper(anims),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var anim = _step.value;
+          var mesh = this._resolveMesh(anim, deviceModelRoot);
+          if (!mesh) {
+            console.warn("[IoBehaviorManager] Could not find mesh for animation \"".concat(anim.name || anim.stateVariable, "\" (uuid: ").concat(anim.meshUuid, ", name: \"").concat(anim.meshName, "\")"));
+            continue;
+          }
+          var worldPos = new THREE.Vector3();
+          mesh.getWorldPosition(worldPos);
+          var worldQuat = new THREE.Quaternion();
+          mesh.getWorldQuaternion(worldQuat);
+          var box = new THREE.Box3().setFromObject(mesh);
+          var worldCenter = new THREE.Vector3();
+          if (!box.isEmpty()) box.getCenter(worldCenter);else worldCenter.copy(worldPos);
+          entries.push({
+            anim: anim,
+            mesh: mesh,
+            origPos: mesh.position.clone(),
+            origRot: mesh.rotation.clone(),
+            origWorldPos: worldPos,
+            origWorldQuat: worldQuat,
+            origWorldCenter: worldCenter,
+            deviceWorldQuat: deviceWorldQuat.clone(),
+            viewerMaxDim: viewerMaxDim
+          });
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      if (entries.length) {
+        this._entries.set(key, entries);
+        console.log("[IoBehaviorManager] Loaded ".concat(entries.length, " animation(s) for attachment \"").concat(attachmentId, "\" (parent: ").concat(parentUuid, ") \u2014 stateVariables: ").concat(entries.map(function (e) {
+          return e.anim.stateVariable;
+        }).join(', ')));
+      } else {
+        console.warn("[IoBehaviorManager] No mesh entries resolved for attachment \"".concat(attachmentId, "\" \u2014 behaviorConfig had ").concat(anims.length, " entries but none matched a mesh"));
+      }
+    }
+
+    /**
+     * Apply animations triggered by an IO device state change.
+     * Should be called in parallel with BehaviorManager.triggerState().
+     *
+     * @param {string} attachmentId - Raw attachment key (not scoped)
+     * @param {string} dataPointId  - The data point / state variable id that changed
+     * @param {*}      value        - New state value
+     * @param {string} parentUuid   - UUID of the host component
+     */
+  }, {
+    key: "triggerState",
+    value: function triggerState(attachmentId, dataPointId, value, parentUuid) {
+      var key = this._key(parentUuid, attachmentId);
+      var entries = this._entries.get(key);
+      if (!(entries !== null && entries !== void 0 && entries.length)) return;
+      var _iterator2 = _createForOfIteratorHelper(entries),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var entry = _step2.value;
+          if (entry.anim.stateVariable !== dataPointId) continue;
+          this._applyAnimation(entry, value);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+    }
+
+    /**
+     * Return tooltip-compatible data point definitions derived from the loaded
+     * animation entries for a given attachment.  Used by componentTooltipManager
+     * to replace the static ioConfig.states[] snapshot with the richer animation
+     * state definitions created in the Animate window.
+     *
+     * One dp object is emitted per unique stateVariable; multiple mesh entries
+     * that share the same stateVariable are collapsed into one.
+     *
+     * Returned dp shape (matches what _buildDataPointRow / _buildInputControl expect):
+     * {
+     *   id: string,          // stateVariable name
+     *   name: string,        // human-readable label (anim.name or stateVariable)
+     *   stateType: string,   // normalised to 'binary' | 'enum' | 'number'
+     *   stateConfig: Object, // { onLabel?, offLabel?, options?, min?, max?, unit? }
+     *   defaultValue: any,   // sensible default for the stateType
+     *   direction: 'input'   // all animation-driven states are interactive
+     * }
+     *
+     * @param {string} parentUuid
+     * @param {string} attachmentId
+     * @returns {Object[]} Array of dp objects, or empty array if none loaded.
+     */
+  }, {
+    key: "getAnimationDataPoints",
+    value: function getAnimationDataPoints(parentUuid, attachmentId) {
+      var _this2 = this;
+      var hitMesh = arguments.length > 2 && arguments[2] !== undefined ? arguments[2] : null;
+      var key = this._key(parentUuid, attachmentId);
+      var entries = this._entries.get(key);
+      if (!(entries !== null && entries !== void 0 && entries.length)) return [];
+
+      // When a specific mesh was clicked, filter to only animations whose target
+      // mesh is the clicked mesh or an ancestor of it (e.g. the clicked primitive
+      // is inside a group that is the animation target).
+      var filtered = entries;
+      if (hitMesh) {
+        var matching = entries.filter(function (e) {
+          return _this2._isMeshOrDescendant(hitMesh, e.mesh);
+        });
+        if (matching.length > 0) filtered = matching;
+      }
+
+      // Collapse multiple mesh entries that share the same stateVariable
+      var seen = new Map(); // stateVariable → anim
+      var _iterator3 = _createForOfIteratorHelper(filtered),
+        _step3;
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var anim = _step3.value.anim;
+          if (!seen.has(anim.stateVariable)) {
+            seen.set(anim.stateVariable, anim);
+          }
+        }
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+      var dps = [];
+      var _iterator4 = _createForOfIteratorHelper(seen),
+        _step4;
+      try {
+        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+          var _step4$value = _slicedToArray(_step4.value, 2),
+            stateVar = _step4$value[0],
+            _anim = _step4$value[1];
+          // Normalise stateType from AnimateDevicesDialog variants
+          var stateType = void 0;
+          var raw = (_anim.stateType || '').toLowerCase();
+          if (raw === 'binary' || raw === 'boolean') {
+            stateType = 'binary';
+          } else if (raw === 'enum') {
+            stateType = 'enum';
+          } else {
+            // 'continuous', 'range', 'number', or anything else → numeric slider
+            stateType = 'number';
+          }
+
+          // Derive stateConfig from mappings
+          var stateConfig = {};
+          var mappingValues = (_anim.mappings || []).map(function (m) {
+            return m.stateValue;
+          });
+          if (stateType === 'enum') {
+            stateConfig.options = _toConsumableArray(new Set(mappingValues.map(String)));
+          } else if (stateType === 'number') {
+            var nums = mappingValues.map(Number).filter(function (n) {
+              return !isNaN(n);
+            });
+            if (nums.length) {
+              stateConfig.min = Math.min.apply(Math, _toConsumableArray(nums));
+              stateConfig.max = Math.max.apply(Math, _toConsumableArray(nums));
+            }
+          }
+
+          // Sensible default values
+          var defaultValue = void 0;
+          if (stateType === 'binary') {
+            defaultValue = 0;
+          } else if (stateType === 'enum') {
+            var _stateConfig$options$, _stateConfig$options;
+            defaultValue = (_stateConfig$options$ = (_stateConfig$options = stateConfig.options) === null || _stateConfig$options === void 0 ? void 0 : _stateConfig$options[0]) !== null && _stateConfig$options$ !== void 0 ? _stateConfig$options$ : '';
+          } else {
+            var _stateConfig$min;
+            defaultValue = (_stateConfig$min = stateConfig.min) !== null && _stateConfig$min !== void 0 ? _stateConfig$min : 0;
+          }
+          dps.push({
+            id: stateVar,
+            name: _anim.name || stateVar,
+            stateType: stateType,
+            stateConfig: stateConfig,
+            defaultValue: defaultValue,
+            direction: 'input'
+          });
+        }
+      } catch (err) {
+        _iterator4.e(err);
+      } finally {
+        _iterator4.f();
+      }
+      return dps;
+    }
+
+    /**
+     * Return the Three.js mesh objects that are animated for a given attachment.
+     * Used by IoOutlineManager to include animated meshes in the outline.
+     *
+     * @param {string} parentUuid
+     * @param {string} attachmentId
+     * @returns {THREE.Object3D[]}
+     */
+  }, {
+    key: "getAnimatedMeshes",
+    value: function getAnimatedMeshes(parentUuid, attachmentId) {
+      var key = this._key(parentUuid, attachmentId);
+      var entries = this._entries.get(key);
+      if (!(entries !== null && entries !== void 0 && entries.length)) return [];
+      // Deduplicate — multiple animations can target the same mesh
+      return _toConsumableArray(new Set(entries.map(function (e) {
+        return e.mesh;
+      })));
+    }
+
+    /**
+     * Remove all animation entries associated with a given host component.
+     * Call when a component is removed from the scene.
+     *
+     * @param {string} parentUuid
+     */
+  }, {
+    key: "unloadForComponent",
+    value: function unloadForComponent(parentUuid) {
+      var prefix = "".concat(parentUuid, "::");
+      var _iterator5 = _createForOfIteratorHelper(this._entries.keys()),
+        _step5;
+      try {
+        for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+          var key = _step5.value;
+          if (key.startsWith(prefix)) {
+            this._entries.delete(key);
+          }
+        }
+      } catch (err) {
+        _iterator5.e(err);
+      } finally {
+        _iterator5.f();
+      }
+    }
+  }, {
+    key: "dispose",
+    value: function dispose() {
+      this._entries.clear();
+      _superPropGet(IoBehaviorManager, "dispose", this, 3)([]);
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // PRIVATE HELPERS
+    // ─────────────────────────────────────────────────────────────────────────
+  }, {
+    key: "_key",
+    value: function _key(parentUuid, attachmentId) {
+      return "".concat(parentUuid, "::").concat(attachmentId);
+    }
+
+    /**
+     * Returns true if `candidate` is `ancestor` or any descendant of `ancestor`.
+     * @param {THREE.Object3D} candidate
+     * @param {THREE.Object3D} ancestor
+     */
+  }, {
+    key: "_isMeshOrDescendant",
+    value: function _isMeshOrDescendant(candidate, ancestor) {
+      var obj = candidate;
+      while (obj) {
+        if (obj === ancestor) return true;
+        obj = obj.parent;
+      }
+      return false;
+    }
+
+    /**
+     * Find the mesh inside `root` using UUID first, then name as fallback.
+     * GLTFLoader assigns fresh UUIDs on every load, so name is the reliable key.
+     * @param {Object} anim
+     * @param {THREE.Object3D} root
+     * @returns {THREE.Object3D|null}
+     */
+  }, {
+    key: "_resolveMesh",
+    value: function _resolveMesh(anim, root) {
+      var found = null;
+      root.traverse(function (obj) {
+        if (found) return;
+
+        // Prefer UUID match (works when the device was cloned from a cached instance
+        // whose UUIDs were preserved)
+        if (anim.meshUuid && obj.uuid === anim.meshUuid) {
+          found = obj;
+          return;
+        }
+
+        // Reliable fallback: mesh name
+        if (anim.meshName && obj.name === anim.meshName) {
+          found = obj;
+        }
+      });
+      return found;
+    }
+
+    /**
+     * Resolve which mapping row to use and apply all declared transform types.
+     * @param {{ anim, mesh, origPos, origRot }} entry
+     * @param {*} value - Current state value
+     */
+  }, {
+    key: "_applyAnimation",
+    value: function _applyAnimation(entry, value) {
+      var anim = entry.anim,
+        mesh = entry.mesh,
+        origPos = entry.origPos,
+        origRot = entry.origRot,
+        origWorldPos = entry.origWorldPos,
+        origWorldQuat = entry.origWorldQuat,
+        origWorldCenter = entry.origWorldCenter,
+        deviceWorldQuat = entry.deviceWorldQuat,
+        viewerMaxDim = entry.viewerMaxDim;
+      var mapping = this._resolveMapping(anim, value);
+      if (!mapping) return;
+      var types = anim.transformTypes || [];
+      var _iterator6 = _createForOfIteratorHelper(types),
+        _step6;
+      try {
+        for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
+          var type = _step6.value;
+          if (type === 'translation') {
+            this._applyTranslation(mesh, origPos, mapping.transform);
+          } else if (type === 'rotation') {
+            this._applyRotation(mesh, origPos, origRot, anim, mapping.rotationTransform, origWorldPos, origWorldQuat, origWorldCenter, deviceWorldQuat, viewerMaxDim);
+          } else if (type === 'color') {
+            this._applyColor(mesh, mapping.colorTransform);
+          }
+        }
+      } catch (err) {
+        _iterator6.e(err);
+      } finally {
+        _iterator6.f();
+      }
+    }
+
+    /**
+     * Find the mapping row that matches `value` for the given animation entry.
+     *
+     * - binary / enum: find where mapping.stateValue == value (loose equality so
+     *   JSON-deserialised "true" matches boolean true)
+     * - continuous: linear interpolation between ordered anchor points
+     *
+     * @returns {Object|null} The matched/interpolated mapping row, or null.
+     */
+  }, {
+    key: "_resolveMapping",
+    value: function _resolveMapping(anim, value) {
+      var mappings = anim.mappings;
+      if (!(mappings !== null && mappings !== void 0 && mappings.length)) return null;
+
+      // Normalise stateType variants saved by AnimateDevicesDialog
+      // ('boolean' → 'binary', 'range' → 'continuous')
+      var raw = (anim.stateType || '').toLowerCase();
+      var stateType;
+      if (raw === 'binary' || raw === 'boolean') {
+        stateType = 'binary';
+      } else if (raw === 'continuous' || raw === 'range') {
+        stateType = 'continuous';
+      } else {
+        stateType = raw;
+      }
+      if (stateType === 'binary' || stateType === 'enum') {
+        var _mappings$find;
+        // eslint-disable-next-line eqeqeq
+        return (_mappings$find = mappings.find(function (m) {
+          return m.stateValue == value;
+        })) !== null && _mappings$find !== void 0 ? _mappings$find : null;
+      }
+      if (stateType === 'continuous') {
+        var num = Number(value);
+        if (isNaN(num)) return null;
+
+        // Sort anchors by numeric stateValue
+        var sorted = _toConsumableArray(mappings).filter(function (m) {
+          return m.stateValue != null && !isNaN(Number(m.stateValue));
+        }).sort(function (a, b) {
+          return Number(a.stateValue) - Number(b.stateValue);
+        });
+        if (!sorted.length) return null;
+        if (sorted.length === 1) return sorted[0];
+
+        // Clamp to range
+        if (num <= Number(sorted[0].stateValue)) return sorted[0];
+        if (num >= Number(sorted[sorted.length - 1].stateValue)) return sorted[sorted.length - 1];
+
+        // Find surrounding anchors and interpolate
+        for (var i = 0; i < sorted.length - 1; i++) {
+          var lo = sorted[i];
+          var hi = sorted[i + 1];
+          var loVal = Number(lo.stateValue);
+          var hiVal = Number(hi.stateValue);
+          if (num >= loVal && num <= hiVal) {
+            var t = (num - loVal) / (hiVal - loVal);
+            return this._lerpMapping(lo, hi, t);
+          }
+        }
+      }
+      return null;
+    }
+
+    /**
+     * Linear-interpolate between two mapping rows.
+     * @param {Object} lo - lower anchor mapping
+     * @param {Object} hi - upper anchor mapping
+     * @param {number} t  - 0..1
+     */
+  }, {
+    key: "_lerpMapping",
+    value: function _lerpMapping(lo, hi, t) {
+      var _lo$transform$x, _lo$transform, _hi$transform$x, _hi$transform, _lo$transform$y, _lo$transform2, _hi$transform$y, _hi$transform2, _lo$transform$z, _lo$transform3, _hi$transform$z, _hi$transform3;
+      var lerp = function lerp(a, b) {
+        return a + (b - a) * t;
+      };
+      var transform = {
+        x: lerp((_lo$transform$x = (_lo$transform = lo.transform) === null || _lo$transform === void 0 ? void 0 : _lo$transform.x) !== null && _lo$transform$x !== void 0 ? _lo$transform$x : 0, (_hi$transform$x = (_hi$transform = hi.transform) === null || _hi$transform === void 0 ? void 0 : _hi$transform.x) !== null && _hi$transform$x !== void 0 ? _hi$transform$x : 0),
+        y: lerp((_lo$transform$y = (_lo$transform2 = lo.transform) === null || _lo$transform2 === void 0 ? void 0 : _lo$transform2.y) !== null && _lo$transform$y !== void 0 ? _lo$transform$y : 0, (_hi$transform$y = (_hi$transform2 = hi.transform) === null || _hi$transform2 === void 0 ? void 0 : _hi$transform2.y) !== null && _hi$transform$y !== void 0 ? _hi$transform$y : 0),
+        z: lerp((_lo$transform$z = (_lo$transform3 = lo.transform) === null || _lo$transform3 === void 0 ? void 0 : _lo$transform3.z) !== null && _lo$transform$z !== void 0 ? _lo$transform$z : 0, (_hi$transform$z = (_hi$transform3 = hi.transform) === null || _hi$transform3 === void 0 ? void 0 : _hi$transform3.z) !== null && _hi$transform$z !== void 0 ? _hi$transform$z : 0)
+      };
+      var rotationTransform = lerp(typeof lo.rotationTransform === 'number' ? lo.rotationTransform : 0, typeof hi.rotationTransform === 'number' ? hi.rotationTransform : 0);
+
+      // Color interpolation: convert hex → RGB components → lerp → back to hex
+      var colorTransform = this._lerpHex(lo.colorTransform, hi.colorTransform, t);
+      return {
+        stateValue: null,
+        transform: transform,
+        rotationTransform: rotationTransform,
+        colorTransform: colorTransform
+      };
+    }
+
+    /**
+     * Interpolate between two hex colour strings.
+     */
+  }, {
+    key: "_lerpHex",
+    value: function _lerpHex(hexA, hexB, t) {
+      try {
+        var ca = new THREE.Color(hexA);
+        var cb = new THREE.Color(hexB);
+        ca.lerp(cb, t);
+        return "#".concat(ca.getHexString());
+      } catch (_unused) {
+        return hexA !== null && hexA !== void 0 ? hexA : '#ffffff';
+      }
+    }
+
+    // ─────────────────────────────────────────────────────────────────────────
+    // TRANSFORM APPLIERS
+    // ─────────────────────────────────────────────────────────────────────────
+
+    /**
+     * Apply a position delta relative to the mesh's original position.
+     * @param {THREE.Object3D} mesh
+     * @param {THREE.Vector3} origPos
+     * @param {{ x, y, z }} transform - Deltas
+     */
+  }, {
+    key: "_applyTranslation",
+    value: function _applyTranslation(mesh, origPos, transform) {
+      var _transform$x, _transform$y, _transform$z;
+      if (!transform) return;
+      // X and Y are negated to match the sign convention used in the AnimateDevicesDialog
+      // preview (_syncViewerTransform negates x and y before calling setMeshPreviewOffset).
+      // Z is added directly (no negation) — matching the dialog's z handling.
+      mesh.position.set(origPos.x - ((_transform$x = transform.x) !== null && _transform$x !== void 0 ? _transform$x : 0), origPos.y - ((_transform$y = transform.y) !== null && _transform$y !== void 0 ? _transform$y : 0), origPos.z + ((_transform$z = transform.z) !== null && _transform$z !== void 0 ? _transform$z : 0));
+    }
+
+    /**
+     * Apply a rotation around an arbitrary pivot point using world-space quaternion
+     * math matching the ReconstructionViewer's setMeshPreviewRotationAxis approach.
+     * This ensures the runtime axis/pivot matches what the user configured in the
+     * animation dialog, regardless of the device's parent transform in the scene.
+     *
+     * @param {THREE.Object3D} mesh
+     * @param {THREE.Vector3}  origPos        - local position at load time (unused, kept for signature compat)
+     * @param {THREE.Euler}    origRot        - local rotation at load time (unused)
+     * @param {Object}         anim
+     * @param {number}         angleDeg       - Degrees
+     * @param {THREE.Vector3}  origWorldPos   - world position at load time
+     * @param {THREE.Quaternion} origWorldQuat - world quaternion at load time
+     * @param {THREE.Vector3}  origWorldCenter - world bounding-box center at load time
+     */
+  }, {
+    key: "_applyRotation",
+    value: function _applyRotation(mesh, origPos, origRot, anim, angleDeg, origWorldPos, origWorldQuat, origWorldCenter, deviceWorldQuat, viewerMaxDim) {
+      var _anim$rotAxis, _anim$rotAxisOffset;
+      var angle = THREE.MathUtils.degToRad(typeof angleDeg === 'number' ? angleDeg : 0);
+      var axis = ((_anim$rotAxis = anim.rotAxis) !== null && _anim$rotAxis !== void 0 ? _anim$rotAxis : 'x').toLowerCase();
+      var off = (_anim$rotAxisOffset = anim.rotAxisOffset) !== null && _anim$rotAxisOffset !== void 0 ? _anim$rotAxisOffset : {
+        x: 0,
+        y: 0,
+        z: 0
+      };
+
+      // Local axis in the device's coordinate system
+      var localAxisVec = new THREE.Vector3(axis === 'x' ? 1 : 0, axis === 'y' ? 1 : 0, axis === 'z' ? 1 : 0);
+      if (origWorldPos && origWorldQuat && origWorldCenter) {
+        // Transform the configured axis from device-local space into world space
+        // so that 'X' means the device's local X, not the world X.
+        var worldAxisVec = localAxisVec.clone().applyQuaternion(deviceWorldQuat || new THREE.Quaternion());
+
+        // rotAxisOffset is stored in dialog-viewer-world space where the model root
+        // has been rotated Rot_Z(π) by default (ReconstructionViewer's else branch).
+        // Translation uses the same convention and negates X/Y to compensate.
+        // For rotation offset we apply the same compensation mathematically:
+        //   offset_runtime = deviceWorldQuat × Rot_Z(π) × offset_dialog × scale
+        // This maps from dialog world space (post Z+180° flip) → model local → world.
+        var scale = viewerMaxDim || 1;
+        var rotZ180 = new THREE.Quaternion().setFromAxisAngle(new THREE.Vector3(0, 0, 1), Math.PI);
+        var qCombined = (deviceWorldQuat || new THREE.Quaternion()).clone().multiply(rotZ180);
+        var offWorld = new THREE.Vector3((off.x || 0) * scale, (off.y || 0) * scale, (off.z || 0) * scale).applyQuaternion(qCombined);
+        var pivot = origWorldCenter.clone().add(offWorld);
+        var deltaQuat = new THREE.Quaternion().setFromAxisAngle(worldAxisVec, angle);
+
+        // Rotate world position around pivot
+        var offsetVec = origWorldPos.clone().sub(pivot);
+        offsetVec.applyQuaternion(deltaQuat);
+        var newWorldPos = pivot.clone().add(offsetVec);
+
+        // Compose world quaternion
+        var newWorldQuat = deltaQuat.clone().multiply(origWorldQuat);
+
+        // Convert world position → parent local space
+        if (mesh.parent) {
+          mesh.parent.worldToLocal(newWorldPos);
+        }
+        mesh.position.copy(newWorldPos);
+
+        // Convert quaternion → parent local space
+        if (mesh.parent) {
+          var parentWorldQuat = new THREE.Quaternion();
+          mesh.parent.getWorldQuaternion(parentWorldQuat);
+          parentWorldQuat.invert();
+          newWorldQuat.premultiply(parentWorldQuat);
+        }
+        mesh.quaternion.copy(newWorldQuat);
+      } else {
+        var _off$x, _off$y, _off$z;
+        // Fallback for entries loaded without world data
+        var _pivot = new THREE.Vector3((_off$x = off.x) !== null && _off$x !== void 0 ? _off$x : 0, (_off$y = off.y) !== null && _off$y !== void 0 ? _off$y : 0, (_off$z = off.z) !== null && _off$z !== void 0 ? _off$z : 0);
+        var delta = origPos.clone().sub(_pivot);
+        delta.applyAxisAngle(localAxisVec, angle);
+        mesh.position.copy(_pivot).add(delta);
+        mesh.rotation[axis] = origRot[axis] + angle;
+      }
+    }
+
+    /**
+     * Apply a colour to all Mesh descendants of `mesh`.
+     * Creates a cloned material per mesh on first call to avoid shared-material
+     * cross-contamination between different device instances.
+     *
+     * @param {THREE.Object3D} mesh
+     * @param {string} colorHex - e.g. '#ff0000'
+     */
+  }, {
+    key: "_applyColor",
+    value: function _applyColor(mesh, colorHex) {
+      if (!colorHex) return;
+      mesh.traverse(function (obj) {
+        if (!obj.isMesh || !obj.material) return;
+
+        // Ensure this mesh has its own material instance
+        if (!obj.userData._materialCloned) {
+          obj.material = obj.material.clone();
+          obj.userData._materialCloned = true;
+        }
+        try {
+          obj.material.color.set(colorHex);
+        } catch (e) {
+          // Material may not have a color property (e.g. MeshDepthMaterial)
+        }
+      });
+    }
+  }]);
+}(BaseDisposable);
+
+export { IoBehaviorManager };

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

@@ -445,6 +445,7 @@ var TransformControlsManager = /*#__PURE__*/function () {
         raycaster.setFromCamera(mouse, _this4.camera);
         var allIntersects = raycaster.intersectObjects(_this4.scene.children, true);
         var ioDeviceObject = null;
+        var hitMesh = null;
         var _iterator = _createForOfIteratorHelper(allIntersects),
           _step;
         try {
@@ -459,7 +460,10 @@ var TransformControlsManager = /*#__PURE__*/function () {
               }
               obj = obj.parent;
             }
-            if (ioDeviceObject) break;
+            if (ioDeviceObject) {
+              hitMesh = hit.object;
+              break;
+            }
           }
         } catch (err) {
           _iterator.e(err);
@@ -474,7 +478,7 @@ var TransformControlsManager = /*#__PURE__*/function () {
         _this4._ioDragStartY = event.clientY;
         _this4._ioDragMoved = false;
         if (_this4.orbitControls) _this4.orbitControls.enabled = false;
-        _this4.callbacks.onIODeviceDrag(ioDeviceObject, 0, true);
+        _this4.callbacks.onIODeviceDrag(ioDeviceObject, 0, true, hitMesh);
         var onMove = function onMove(e) {
           var dx = e.clientX - _this4._ioDragStartX;
           var dy = e.clientY - _this4._ioDragStartY;