@2112-lab/central-plant 0.3.57 → 0.3.59

package/dist/esm/src/managers/scene/controlPanelManager.js

@@ -0,0 +1,352 @@
+import { inherits as _inherits, createClass as _createClass, classCallCheck as _classCallCheck, callSuper as _callSuper, asyncToGenerator as _asyncToGenerator, regenerator as _regenerator, createForOfIteratorHelper as _createForOfIteratorHelper } from '../../../_virtual/_rollupPluginBabelHelpers.js';
+import * as THREE from 'three';
+import { BaseDisposable } from '../../core/baseDisposable.js';
+import modelPreloader from '../../rendering/modelPreloader.js';
+import { attachIODevicesToComponent } from '../../utils/ioDeviceUtils.js';
+import { registerBehaviorsForComponent } from '../../utils/behaviorRegistration.js';
+
+/**
+ * X offsets for `count` switches evenly spaced and centered on 0.
+ * @param {number} count
+ * @param {number} spacing
+ * @returns {number[]}
+ */
+function computeSwitchRowX(count, spacing) {
+  var start = -((count - 1) * spacing) / 2;
+  return Array.from({
+    length: count
+  }, function (_, i) {
+    return start + i * spacing;
+  });
+}
+var ControlPanelManager = /*#__PURE__*/function (_BaseDisposable) {
+  /**
+   * @param {Object} sceneViewer - The central sceneViewer hub
+   */
+  function ControlPanelManager(sceneViewer) {
+    var _this;
+    _classCallCheck(this, ControlPanelManager);
+    _this = _callSuper(this, ControlPanelManager);
+    _this.sceneViewer = sceneViewer;
+    _this._panel = null;
+    _this._labels = [];
+    _this._panelId = null;
+    _this._build = _this._build.bind(_this);
+    if (sceneViewer !== null && sceneViewer !== void 0 && sceneViewer.on) {
+      sceneViewer.on('scene-loaded', _this._build);
+    }
+    return _this;
+  }
+
+  /**
+   * Build (or rebuild) the panel from the current scene's `controlPanel` spec.
+   * @private
+   */
+  _inherits(ControlPanelManager, _BaseDisposable);
+  return _createClass(ControlPanelManager, [{
+    key: "_build",
+    value: (function () {
+      var _build2 = _asyncToGenerator(/*#__PURE__*/_regenerator().m(function _callee() {
+        var _this$sceneViewer,
+          _centralPlant$importe,
+          _this$sceneViewer2,
+          _b$width,
+          _b$height,
+          _b$thickness,
+          _desk$tilt,
+          _desk$height,
+          _desk$legThickness,
+          _desk$legInset,
+          _spec$switchSpacing,
+          _this$sceneViewer3,
+          _spec$labelSize,
+          _this2 = this;
+        var centralPlant, spec, scene, panelId, panel, p, r, d2r, scale, b, width, depth, thickness, desk, tilt, deskHeight, legThickness, legInset, legColor, top, board, legMat, halfW, halfD, _i, _arr, ly, cornerZ, legH, yPos, _i2, _arr2, lx, leg, switches, spacing, xs, topZ, attachedDevices, componentData, switchScale, ioBehavMgr, engine, _iterator, _step, sw, current, lo, labelSize;
+        return _regenerator().w(function (_context) {
+          while (1) switch (_context.n) {
+            case 0:
+              this._teardown();
+              centralPlant = (_this$sceneViewer = this.sceneViewer) === null || _this$sceneViewer === void 0 ? void 0 : _this$sceneViewer.centralPlant;
+              spec = centralPlant === null || centralPlant === void 0 || (_centralPlant$importe = centralPlant.importedSceneData) === null || _centralPlant$importe === void 0 ? void 0 : _centralPlant$importe.controlPanel;
+              scene = (_this$sceneViewer2 = this.sceneViewer) === null || _this$sceneViewer2 === void 0 ? void 0 : _this$sceneViewer2.scene;
+              if (!(!spec || !scene)) {
+                _context.n = 1;
+                break;
+              }
+              return _context.a(2);
+            case 1:
+              panelId = spec.id || 'CONTROL-PANEL-1';
+              this._panelId = panelId;
+              panel = new THREE.Group();
+              panel.name = 'Control Panel';
+              panel.uuid = panelId;
+              panel.userData = {
+                objectType: 'component',
+                isControlPanel: true
+              };
+              p = spec.position || {};
+              panel.position.set(p.x || 0, p.y || 0, p.z || 0);
+              r = spec.rotation || {};
+              d2r = Math.PI / 180;
+              panel.rotation.set((r.x || 0) * d2r, (r.y || 0) * d2r, (r.z || 0) * d2r, 'XYZ');
+              scale = Number.isFinite(spec.scale) && spec.scale > 0 ? spec.scale : 1;
+              panel.scale.setScalar(scale);
+
+              // ── Drawing-desk geometry (Z-up scene) ───────────────────────────────────
+              // A tilted top surface (the drafting board) raised on legs. Switches +
+              // labels live on the tilted `top` group so they sit on the angled surface.
+              b = spec.board || {};
+              width = (_b$width = b.width) !== null && _b$width !== void 0 ? _b$width : 7; // x-extent of the top
+              depth = (_b$height = b.height) !== null && _b$height !== void 0 ? _b$height : 2; // y-extent of the top (spec key kept as `height`)
+              thickness = (_b$thickness = b.thickness) !== null && _b$thickness !== void 0 ? _b$thickness : 0.15;
+              desk = spec.desk || {};
+              tilt = ((_desk$tilt = desk.tilt) !== null && _desk$tilt !== void 0 ? _desk$tilt : 30) * d2r; // surface tilt; +raises the back (+y) edge
+              deskHeight = (_desk$height = desk.height) !== null && _desk$height !== void 0 ? _desk$height : 1.3; // world height of the top's center
+              legThickness = (_desk$legThickness = desk.legThickness) !== null && _desk$legThickness !== void 0 ? _desk$legThickness : 0.18;
+              legInset = (_desk$legInset = desk.legInset) !== null && _desk$legInset !== void 0 ? _desk$legInset : 0.35;
+              legColor = desk.legColor || '#22303c'; // Tilted top group: raised to deskHeight, rotated about X.
+              top = new THREE.Group();
+              top.position.set(0, 0, deskHeight);
+              top.rotation.set(tilt, 0, 0, 'XYZ');
+              panel.add(top);
+              board = new THREE.Mesh(new THREE.BoxGeometry(width, depth, thickness), new THREE.MeshStandardMaterial({
+                color: b.color || '#2c3e50',
+                roughness: 0.6,
+                metalness: 0.2
+              }));
+              board.userData = {
+                objectType: 'control-panel-board'
+              };
+              top.add(board);
+
+              // Legs: one per corner, from the ground up to the tilted top's underside.
+              legMat = new THREE.MeshStandardMaterial({
+                color: legColor,
+                roughness: 0.7,
+                metalness: 0.1
+              });
+              halfW = Math.max(0.1, width / 2 - legInset);
+              halfD = Math.max(0.1, depth / 2 - legInset);
+              for (_i = 0, _arr = [halfD, -halfD]; _i < _arr.length; _i++) {
+                ly = _arr[_i];
+                // Underside height at this front/back row after the tilt.
+                cornerZ = deskHeight + ly * Math.sin(tilt) - thickness / 2 * Math.cos(tilt);
+                legH = Math.max(0.1, cornerZ);
+                yPos = ly * Math.cos(tilt); // corner's y in panel space after tilt
+                for (_i2 = 0, _arr2 = [halfW, -halfW]; _i2 < _arr2.length; _i2++) {
+                  lx = _arr2[_i2];
+                  leg = new THREE.Mesh(new THREE.BoxGeometry(legThickness, legThickness, legH), legMat);
+                  leg.position.set(lx, yPos, legH / 2);
+                  panel.add(leg);
+                }
+              }
+
+              // ── Switch layout: a row along X on the top face (+Z) of the board ───────
+              switches = Array.isArray(spec.switches) ? spec.switches : [];
+              spacing = (_spec$switchSpacing = spec.switchSpacing) !== null && _spec$switchSpacing !== void 0 ? _spec$switchSpacing : 1.3;
+              xs = computeSwitchRowX(switches.length, spacing);
+              topZ = thickness / 2;
+              attachedDevices = {};
+              switches.forEach(function (sw, i) {
+                attachedDevices[sw.attachmentId] = {
+                  deviceId: spec.deviceId,
+                  attachmentLabel: sw.label || sw.attachmentId,
+                  attachmentPoint: {
+                    position: {
+                      x: xs[i],
+                      y: 0,
+                      z: topZ
+                    },
+                    rotation: spec.switchRotation || {
+                      x: 0,
+                      y: 0,
+                      z: 0
+                    }
+                  }
+                };
+              });
+              componentData = {
+                isSmart: true,
+                attachedDevices: attachedDevices
+              }; // Clone + tag the switch devices onto the tilted top (reuses smart-component path).
+              _context.n = 2;
+              return attachIODevicesToComponent(top, componentData, modelPreloader, panelId);
+            case 2:
+              // Optional switch-only scale (attach path always leaves devices at 1:1).
+              switchScale = Number.isFinite(spec.switchScale) && spec.switchScale > 0 ? spec.switchScale : 1;
+              if (switchScale !== 1) {
+                top.traverse(function (obj) {
+                  var _obj$userData;
+                  if (((_obj$userData = obj.userData) === null || _obj$userData === void 0 ? void 0 : _obj$userData.objectType) === 'io-device') {
+                    obj.scale.setScalar(switchScale);
+                  }
+                });
+              }
+
+              // Panel must be in the scene before behaviors register (default-state seeding
+              // scans the live scene graph for io-devices).
+              scene.add(panel);
+              this._panel = panel;
+              ioBehavMgr = (_this$sceneViewer3 = this.sceneViewer) === null || _this$sceneViewer3 === void 0 || (_this$sceneViewer3 = _this$sceneViewer3.managers) === null || _this$sceneViewer3 === void 0 ? void 0 : _this$sceneViewer3.ioBehaviorManager;
+              if (ioBehavMgr) {
+                registerBehaviorsForComponent(ioBehavMgr, panelId, componentData, panel, modelPreloader.componentDictionary, centralPlant);
+
+                // Drive each switch's mesh to its current engine value so the initial
+                // pose/colour reflects the state. `registerBehaviorsForComponent`'s
+                // default-seeding writes through the engine, which no-ops when the value
+                // already matches the seeded `stateRegistry` — leaving the button at its
+                // neutral GLB rest pose. Trigger the animation directly to avoid that.
+                engine = centralPlant === null || centralPlant === void 0 ? void 0 : centralPlant.stateEngine;
+                _iterator = _createForOfIteratorHelper(switches);
+                try {
+                  for (_iterator.s(); !(_step = _iterator.n()).done;) {
+                    sw = _step.value;
+                    current = engine === null || engine === void 0 ? void 0 : engine.getDesired("".concat(panelId, "::").concat(sw.attachmentId, "::mode"));
+                    ioBehavMgr.triggerState(sw.attachmentId, 'mode', current !== null && current !== void 0 ? current : true, panelId);
+                  }
+                } catch (err) {
+                  _iterator.e(err);
+                } finally {
+                  _iterator.f();
+                }
+              }
+
+              // ── Floating labels above each switch (on the tilted top) ────────────────
+              lo = spec.labelOffset || {
+                x: 0,
+                y: 0,
+                z: 0.7
+              };
+              labelSize = (_spec$labelSize = spec.labelSize) !== null && _spec$labelSize !== void 0 ? _spec$labelSize : 0.5;
+              switches.forEach(function (sw, i) {
+                var _lo$z;
+                var label = _this2._makeLabel(sw.label || sw.attachmentId, labelSize);
+                if (!label) return;
+                label.position.set(xs[i] + (lo.x || 0), lo.y || 0, topZ + ((_lo$z = lo.z) !== null && _lo$z !== void 0 ? _lo$z : 0.7));
+                top.add(label);
+                _this2._labels.push(label);
+              });
+            case 3:
+              return _context.a(2);
+          }
+        }, _callee, this);
+      }));
+      function _build() {
+        return _build2.apply(this, arguments);
+      }
+      return _build;
+    }()
+    /**
+     * Build one text label as a camera-facing `THREE.Sprite` (canvas texture),
+     * drawn by the main WebGL renderer alongside the scene — no dependency on the
+     * tooltip CSS2D renderer. Returns null when there is no DOM (headless tests).
+     * @param {string} text
+     * @param {number} worldHeight - label height in world units
+     * @returns {THREE.Sprite|null}
+     * @private
+     */
+    )
+  }, {
+    key: "_makeLabel",
+    value: function _makeLabel(text, worldHeight) {
+      if (typeof document === 'undefined') return null;
+      var dpr = 4; // supersample for crisp text
+      var fontPx = 40;
+      var padX = 14;
+      var padY = 8;
+      var font = "600 ".concat(fontPx, "px -apple-system, \"Segoe UI\", Roboto, sans-serif");
+      var canvas = document.createElement('canvas');
+      var ctx = canvas.getContext('2d');
+      ctx.font = font;
+      var textW = ctx.measureText(text).width;
+      canvas.width = Math.ceil((textW + padX * 2) * dpr);
+      canvas.height = Math.ceil((fontPx + padY * 2) * dpr);
+
+      // Re-apply after the resize (which clears the canvas), scaled by dpr.
+      ctx.scale(dpr, dpr);
+      ctx.font = font;
+      var wCss = canvas.width / dpr;
+      var hCss = canvas.height / dpr;
+      ctx.fillStyle = 'rgba(20,28,38,0.86)';
+      this._roundRect(ctx, 0, 0, wCss, hCss, 8);
+      ctx.fill();
+      ctx.fillStyle = '#eaf2f8';
+      ctx.textAlign = 'center';
+      ctx.textBaseline = 'middle';
+      ctx.fillText(text, wCss / 2, hCss / 2);
+      var texture = new THREE.CanvasTexture(canvas);
+      texture.minFilter = THREE.LinearFilter;
+      texture.anisotropy = 4;
+      var material = new THREE.SpriteMaterial({
+        map: texture,
+        transparent: true,
+        depthTest: false,
+        // always readable, never occluded by the board/switch
+        depthWrite: false
+      });
+      var sprite = new THREE.Sprite(material);
+      var aspect = canvas.width / canvas.height;
+      sprite.scale.set(worldHeight * aspect, worldHeight, 1);
+      sprite.renderOrder = 999;
+      return sprite;
+    }
+
+    /** Trace a rounded-rect path (fill applied by caller). @private */
+  }, {
+    key: "_roundRect",
+    value: function _roundRect(ctx, x, y, w, h, r) {
+      var rr = Math.min(r, w / 2, h / 2);
+      ctx.beginPath();
+      ctx.moveTo(x + rr, y);
+      ctx.arcTo(x + w, y, x + w, y + h, rr);
+      ctx.arcTo(x + w, y + h, x, y + h, rr);
+      ctx.arcTo(x, y + h, x, y, rr);
+      ctx.arcTo(x, y, x + w, y, rr);
+      ctx.closePath();
+    }
+
+    /**
+     * Remove the panel, its labels, and its registered behaviors (scene reload).
+     * @private
+     */
+  }, {
+    key: "_teardown",
+    value: function _teardown() {
+      this._labels = [];
+      if (this._panelId) {
+        var _this$sceneViewer4;
+        (_this$sceneViewer4 = this.sceneViewer) === null || _this$sceneViewer4 === void 0 || (_this$sceneViewer4 = _this$sceneViewer4.managers) === null || _this$sceneViewer4 === void 0 || (_this$sceneViewer4 = _this$sceneViewer4.ioBehaviorManager) === null || _this$sceneViewer4 === void 0 || _this$sceneViewer4.unloadForComponent(this._panelId);
+      }
+      if (this._panel) {
+        var _this$sceneViewer5;
+        (_this$sceneViewer5 = this.sceneViewer) === null || _this$sceneViewer5 === void 0 || (_this$sceneViewer5 = _this$sceneViewer5.scene) === null || _this$sceneViewer5 === void 0 || _this$sceneViewer5.remove(this._panel);
+        this._panel.traverse(function (obj) {
+          if (obj.isMesh || obj.isSprite) {
+            var _obj$geometry, _obj$geometry$dispose;
+            (_obj$geometry = obj.geometry) === null || _obj$geometry === void 0 || (_obj$geometry$dispose = _obj$geometry.dispose) === null || _obj$geometry$dispose === void 0 || _obj$geometry$dispose.call(_obj$geometry);
+            var mats = Array.isArray(obj.material) ? obj.material : [obj.material];
+            mats.forEach(function (m) {
+              var _m$map, _m$map$dispose, _m$dispose;
+              m === null || m === void 0 || (_m$map = m.map) === null || _m$map === void 0 || (_m$map$dispose = _m$map.dispose) === null || _m$map$dispose === void 0 || _m$map$dispose.call(_m$map); // sprite canvas texture
+              m === null || m === void 0 || (_m$dispose = m.dispose) === null || _m$dispose === void 0 || _m$dispose.call(m);
+            });
+          }
+        });
+        this._panel = null;
+      }
+      this._panelId = null;
+    }
+  }, {
+    key: "_doDispose",
+    value: function _doDispose() {
+      var _this$sceneViewer6;
+      if ((_this$sceneViewer6 = this.sceneViewer) !== null && _this$sceneViewer6 !== void 0 && _this$sceneViewer6.off) {
+        this.sceneViewer.off('scene-loaded', this._build);
+      }
+      this._teardown();
+      this.sceneViewer = null;
+    }
+  }]);
+}(BaseDisposable);
+
+export { ControlPanelManager, computeSwitchRowX };

package/dist/esm/src/managers/scene/sceneExportManager.js

@@ -2,6 +2,7 @@ import { createClass as _createClass, classCallCheck as _classCallCheck, toConsu
 import 'three';
 import { GLTFExporter } from '../../../node_modules/three/examples/jsm/exporters/GLTFExporter.js';
 import { getHardcodedUuid } from '../../utils/nameUtils.js';
+import { applyDeclarationToExport } from '../../core/stateEngineScene.js';
 
 var SceneExportManager = /*#__PURE__*/function () {
   function SceneExportManager(sceneViewer) {
@@ -56,7 +57,8 @@ var SceneExportManager = /*#__PURE__*/function () {
     key: "exportSceneData",
     value: function exportSceneData() {
       var _this = this,
-        _this$sceneViewer$cur2;
+        _this$sceneViewer$cur2,
+        _this$sceneViewer$cen;
       console.log('📤 Starting scene export...');
       if (!this.sceneViewer.scene) {
         console.warn('⚠️ No scene available for export');
@@ -289,6 +291,13 @@ var SceneExportManager = /*#__PURE__*/function () {
       if (sceneBehaviors && sceneBehaviors.length > 0) {
         exportData.behaviors = sceneBehaviors;
       }
+
+      // Persist plant / groups / chains / stateRegistry from the State Engine and
+      // bump the format to 3.0 (Framework §12; no-op if no engine present).
+      var stateEngine = (_this$sceneViewer$cen = this.sceneViewer.centralPlant) === null || _this$sceneViewer$cen === void 0 ? void 0 : _this$sceneViewer$cen.stateEngine;
+      if (stateEngine) {
+        applyDeclarationToExport(exportData, stateEngine);
+      }
       console.log('✅ Scene export completed:', exportData);
       console.log("\uD83D\uDCCA Exported ".concat(sceneChildren.length, " components and ").concat(exportData.connections.length, " connections"));
       return exportData;

package/dist/esm/src/managers/state/EffectiveVisualManager.js

@@ -0,0 +1,266 @@
+import { inherits as _inherits, createClass as _createClass, slicedToArray as _slicedToArray, createForOfIteratorHelper as _createForOfIteratorHelper, classCallCheck as _classCallCheck, callSuper as _callSuper } from '../../../_virtual/_rollupPluginBabelHelpers.js';
+import { BaseDisposable } from '../../core/baseDisposable.js';
+import { findObjectByHardcodedUuid } from '../../utils/nameUtils.js';
+
+/** How far the albedo is pulled toward black for a gated-off mesh. */
+var OFF_COLOR_SCALE = 0.2;
+var EffectiveVisualManager = /*#__PURE__*/function (_BaseDisposable) {
+  /**
+   * @param {Object} sceneViewer - The central sceneViewer hub
+   */
+  function EffectiveVisualManager(sceneViewer) {
+    var _this;
+    _classCallCheck(this, EffectiveVisualManager);
+    _this = _callSuper(this, EffectiveVisualManager);
+    _this.sceneViewer = sceneViewer;
+
+    /**
+     * Materials this manager has gated (cloned + cached), for restore on dispose.
+     * @type {Set<THREE.Material>}
+     */
+    _this._gatedMaterials = new Set();
+
+    // Bound handlers so we can unsubscribe in _doDispose().
+    _this._onChange = _this._onChange.bind(_this);
+    _this._regateAll = _this._regateAll.bind(_this);
+    if (sceneViewer !== null && sceneViewer !== void 0 && sceneViewer.on) {
+      sceneViewer.on('engine-state-changed', _this._onChange);
+      sceneViewer.on('scene-loaded', _this._regateAll);
+    }
+    return _this;
+  }
+
+  // ── Engine change handling ──────────────────────────────────────────────────
+
+  /**
+   * React to one committed registry change. Only 2-part object / pipe addresses
+   * are gated; everything else is ignored.
+   * @param {{ address: string, desired: *, effective: * }} change
+   * @private
+   */
+  _inherits(EffectiveVisualManager, _BaseDisposable);
+  return _createClass(EffectiveVisualManager, [{
+    key: "_onChange",
+    value: function _onChange(change) {
+      if (!change || typeof change.address !== 'string') return;
+      var parts = change.address.split('::');
+      if (parts.length !== 2) return; // 3-part I/O is desired-driven; skip
+
+      var _parts = _slicedToArray(parts, 2),
+        scope = _parts[0],
+        attr = _parts[1];
+      if (scope === 'plant' || scope.startsWith('group:')) return; // members self-report
+
+      if (attr === 'power') {
+        this._gateEquipment(scope, change.effective);
+      } else if (attr === 'flow') {
+        this._gatePipe(scope, change.effective);
+      }
+    }
+
+    /**
+     * Re-gate the whole scene from current effective state. Used after scene load,
+     * where StateEngine.load() populates the registry without emitting per-address
+     * events (and the meshes have just been (re)built).
+     * @private
+     */
+  }, {
+    key: "_regateAll",
+    value: function _regateAll() {
+      var _this$sceneViewer;
+      var engine = (_this$sceneViewer = this.sceneViewer) === null || _this$sceneViewer === void 0 || (_this$sceneViewer = _this$sceneViewer.centralPlant) === null || _this$sceneViewer === void 0 ? void 0 : _this$sceneViewer.stateEngine;
+      if (!engine) return;
+      var registry = engine.toRegistry();
+      for (var _i = 0, _Object$keys = Object.keys(registry); _i < _Object$keys.length; _i++) {
+        var address = _Object$keys[_i];
+        var parts = address.split('::');
+        if (parts.length !== 2) continue;
+        var _parts2 = _slicedToArray(parts, 2),
+          scope = _parts2[0],
+          attr = _parts2[1];
+        if (scope === 'plant' || scope.startsWith('group:')) continue;
+        if (attr === 'power') {
+          this._gateEquipment(scope, engine.getEffective(address));
+        } else if (attr === 'flow') {
+          this._gatePipe(scope, engine.getEffective(address));
+        }
+      }
+    }
+
+    // ── Equipment gating ────────────────────────────────────────────────────────
+
+    /**
+     * Darken (off) or restore (on) every mesh of an equipment object.
+     * @param {string} objectId - Hardcoded object id (address scope)
+     * @param {boolean} on - Effective power
+     * @private
+     */
+  }, {
+    key: "_gateEquipment",
+    value: function _gateEquipment(objectId, on) {
+      var _this$sceneViewer2,
+        _this2 = this;
+      var scene = (_this$sceneViewer2 = this.sceneViewer) === null || _this$sceneViewer2 === void 0 ? void 0 : _this$sceneViewer2.scene;
+      if (!scene) return;
+      var obj = findObjectByHardcodedUuid(scene, objectId);
+      if (!obj || typeof obj.traverse !== 'function') return;
+      obj.traverse(function (mesh) {
+        if (!mesh.isMesh && !mesh.material) return;
+        // Leave attached I/O control panels (switches) lit and operable even when
+        // their host is powered off — you must be able to see and click the switch
+        // that turns it back on. (traverse can't prune, so guard per mesh.)
+        if (_this2._isUnderIoDevice(mesh, obj)) return;
+        var materials = _this2._prepareMeshMaterials(mesh);
+        var _iterator = _createForOfIteratorHelper(materials),
+          _step;
+        try {
+          for (_iterator.s(); !(_step = _iterator.n()).done;) {
+            var material = _step.value;
+            _this2._applyGate(material, on);
+          }
+        } catch (err) {
+          _iterator.e(err);
+        } finally {
+          _iterator.f();
+        }
+      });
+    }
+
+    /**
+     * True if `mesh` is an io-device or nested under one, walking up to (but not
+     * past) the equipment root `stopAt`.
+     * @param {THREE.Object3D} mesh
+     * @param {THREE.Object3D} stopAt - equipment root to stop the upward walk at
+     * @returns {boolean}
+     * @private
+     */
+  }, {
+    key: "_isUnderIoDevice",
+    value: function _isUnderIoDevice(mesh, stopAt) {
+      var node = mesh;
+      while (node) {
+        var _node$userData;
+        if (((_node$userData = node.userData) === null || _node$userData === void 0 ? void 0 : _node$userData.objectType) === 'io-device') return true;
+        if (node === stopAt) break;
+        node = node.parent;
+      }
+      return false;
+    }
+
+    /**
+     * Ensure a mesh's material(s) are cloned-on-write and have their baseline
+     * cached, then return the material list to gate.
+     * @param {THREE.Mesh} mesh
+     * @returns {THREE.Material[]}
+     * @private
+     */
+  }, {
+    key: "_prepareMeshMaterials",
+    value: function _prepareMeshMaterials(mesh) {
+      if (!mesh.material) return [];
+
+      // Clone-on-write once per mesh so shared library materials aren't shared.
+      if (!mesh.userData._effectiveGateCloned) {
+        if (Array.isArray(mesh.material)) {
+          mesh.material = mesh.material.map(function (m) {
+            return m !== null && m !== void 0 && m.clone ? m.clone() : m;
+          });
+        } else if (mesh.material.clone) {
+          mesh.material = mesh.material.clone();
+        }
+        mesh.userData._effectiveGateCloned = true;
+      }
+      var materials = Array.isArray(mesh.material) ? mesh.material : [mesh.material];
+      var _iterator2 = _createForOfIteratorHelper(materials),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _material$userData, _material$color$clone, _material$color, _material$color$clone2, _material$emissive$cl, _material$emissive, _material$emissive$cl2;
+          var material = _step2.value;
+          if (!material || (_material$userData = material.userData) !== null && _material$userData !== void 0 && _material$userData._effectiveGate) continue;
+          material.userData = material.userData || {};
+          material.userData._effectiveGate = {
+            color: (_material$color$clone = (_material$color = material.color) === null || _material$color === void 0 || (_material$color$clone2 = _material$color.clone) === null || _material$color$clone2 === void 0 ? void 0 : _material$color$clone2.call(_material$color)) !== null && _material$color$clone !== void 0 ? _material$color$clone : null,
+            emissive: (_material$emissive$cl = (_material$emissive = material.emissive) === null || _material$emissive === void 0 || (_material$emissive$cl2 = _material$emissive.clone) === null || _material$emissive$cl2 === void 0 ? void 0 : _material$emissive$cl2.call(_material$emissive)) !== null && _material$emissive$cl !== void 0 ? _material$emissive$cl : null,
+            emissiveIntensity: typeof material.emissiveIntensity === 'number' ? material.emissiveIntensity : null
+          };
+          this._gatedMaterials.add(material);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      return materials.filter(Boolean);
+    }
+
+    /**
+     * Darken or restore a single material from its cached baseline.
+     * @param {THREE.Material} material
+     * @param {boolean} on
+     * @private
+     */
+  }, {
+    key: "_applyGate",
+    value: function _applyGate(material, on) {
+      var _material$userData2;
+      var base = (_material$userData2 = material.userData) === null || _material$userData2 === void 0 ? void 0 : _material$userData2._effectiveGate;
+      if (!base) return;
+      if (on) {
+        if (base.color && material.color) material.color.copy(base.color);
+        if (base.emissive && material.emissive) material.emissive.copy(base.emissive);
+        if (base.emissiveIntensity !== null) material.emissiveIntensity = base.emissiveIntensity;
+      } else {
+        if (base.color && material.color) material.color.copy(base.color).multiplyScalar(OFF_COLOR_SCALE);
+        if (material.emissive) material.emissive.setScalar(0);
+        if (typeof material.emissiveIntensity === 'number') material.emissiveIntensity = 0;
+      }
+      material.needsUpdate = true;
+    }
+
+    // ── Pipe flow gating ────────────────────────────────────────────────────────
+
+    /**
+     * Delegate pipe-flow gating to PathFlowManager (grays the shared per-path
+     * material when off, restores the temperature colour when on).
+     * @param {string} pathId - `${from}-->${to}`
+     * @param {boolean} on - Effective flow
+     * @private
+     */
+  }, {
+    key: "_gatePipe",
+    value: function _gatePipe(pathId, on) {
+      var _this$sceneViewer3, _pathFlowManager$setF;
+      var pathFlowManager = (_this$sceneViewer3 = this.sceneViewer) === null || _this$sceneViewer3 === void 0 || (_this$sceneViewer3 = _this$sceneViewer3.managers) === null || _this$sceneViewer3 === void 0 ? void 0 : _this$sceneViewer3.pathFlowManager;
+      pathFlowManager === null || pathFlowManager === void 0 || (_pathFlowManager$setF = pathFlowManager.setFlowEnabled) === null || _pathFlowManager$setF === void 0 || _pathFlowManager$setF.call(pathFlowManager, pathId, on);
+    }
+
+    // ── Lifecycle ───────────────────────────────────────────────────────────────
+  }, {
+    key: "_doDispose",
+    value: function _doDispose() {
+      var _this$sceneViewer4;
+      if ((_this$sceneViewer4 = this.sceneViewer) !== null && _this$sceneViewer4 !== void 0 && _this$sceneViewer4.off) {
+        this.sceneViewer.off('engine-state-changed', this._onChange);
+        this.sceneViewer.off('scene-loaded', this._regateAll);
+      }
+      // Restore any still-gated materials to their cached baseline.
+      var _iterator3 = _createForOfIteratorHelper(this._gatedMaterials),
+        _step3;
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var material = _step3.value;
+          this._applyGate(material, true);
+        }
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+      this._gatedMaterials.clear();
+      this.sceneViewer = null;
+    }
+  }]);
+}(BaseDisposable);
+
+export { EffectiveVisualManager };