@2112-lab/central-plant 0.3.58 → 0.3.59

package/dist/bundle/index.js

@@ -2143,20 +2143,24 @@ var CentralPlantValidator = /*#__PURE__*/function () {
     key: "validateImportedSceneData",
     value: function validateImportedSceneData(sceneData) {
       var results = [];
-      var hardcodedVersion = "2.3";
 
-      // Version validation - MUST be the value of hardcodedVersion
-      if (!sceneData.version || sceneData.version !== hardcodedVersion) {
+      // Supported scene formats: 2.3 (legacy I/O behaviors) and 3.0 (State Engine:
+      // adds plant/groups/chains/stateRegistry). Both load; older scenes keep working.
+      var supportedVersions = ["2.3", "3.0"];
+
+      // Version validation - MUST be one of the supported versions
+      if (!sceneData.version || !supportedVersions.includes(sceneData.version)) {
         var providedVersion = sceneData.version || 'unknown';
-        alert("The central-plant requires the input file to be version ".concat(hardcodedVersion));
+        var supportedList = supportedVersions.join(' or ');
+        alert("The central-plant requires the input file to be version ".concat(supportedList));
         results.push({
           isValid: false,
           severity: ValidationSeverity.ERROR,
-          message: "Invalid version: \"".concat(providedVersion, "\". Required version is \"").concat(hardcodedVersion, "\""),
+          message: "Invalid version: \"".concat(providedVersion, "\". Supported versions are ").concat(supportedList),
           code: 'INVALID_VERSION',
           metadata: {
             providedVersion: providedVersion,
-            requiredVersion: hardcodedVersion
+            supportedVersions: supportedVersions
           }
         });
         return this._combineValidationResults(results, 'scene_import_validation');
@@ -12114,6 +12118,813 @@ function generateUniqueComponentId(libraryId, scene) {
   return id;
 }
 
+/**
+ * @file stateEngine.js
+ * @description Portable State Engine core — registry, desired/effective resolution,
+ * plant (and later group) gates, change notifications. No Vue/Three.js.
+ *
+ * Phase 1 scaffold per STATE_ENGINE_FRAMEWORK_0.3.md / milestones doc.
+ */
+
+/**
+ * @typedef {'desired' | 'effective'} StateLayer
+ */
+
+/**
+ * Build a scoped registry address.
+ * @param {string} scope - e.g. "plant", "group:chiller-loop-a", "pump-001"
+ * @param {string} attribute
+ * @returns {string}
+ */
+function makeAddress(scope, attribute) {
+  return "".concat(scope, "::").concat(attribute);
+}
+
+/**
+ * Shallow equality for registry values (boolean, number, string, null).
+ * @param {*} a
+ * @param {*} b
+ * @returns {boolean}
+ */
+function valuesEqual(a, b) {
+  return Object.is(a, b);
+}
+
+/**
+ * Safe-off value for a gated operational attribute: 0 for numbers, false for
+ * booleans, otherwise the value unchanged.
+ * @param {*} desired
+ * @returns {*}
+ */
+function offValue(desired) {
+  if (typeof desired === 'number') return 0;
+  if (typeof desired === 'boolean') return false;
+  return desired;
+}
+
+/**
+ * Central Plant State Engine (logic only).
+ *
+ * Desired values are stored in the registry. Effective values are computed
+ * from gates (plant / groups / object) without erasing desired.
+ */
+var StateEngine = /*#__PURE__*/function () {
+  /**
+   * @param {object} [options]
+   * @param {number} [options.maxChainDepth=8] - Ripple hop limit (Phase 3)
+   */
+  function StateEngine() {
+    var _options$maxChainDept, _options$gatedOperati;
+    var options = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+    _classCallCheck(this, StateEngine);
+    /** @type {Map<string, *>} address → desired value */
+    this._desired = new Map();
+
+    /** @type {Map<string, Set<string>>} groupId → member object ids */
+    this._groupMembers = new Map();
+
+    /** @type {Map<string, *>} groupId → group desired power (and later other attrs) */
+    this._groupDesired = new Map();
+
+    /** @type {boolean} */
+    this._plantPowerDesired = true;
+
+    /** @type {Set<(change: { address: string, desired: *, effective: * }) => void>} */
+    this._listeners = new Set();
+
+    /** @type {number} */
+    this.maxChainDepth = (_options$maxChainDept = options.maxChainDepth) !== null && _options$maxChainDept !== void 0 ? _options$maxChainDept : 8;
+
+    /**
+     * Operational attributes that read a safe-off value when their object's
+     * power is not effectively on (Framework §6/§10: fan level 5 + plant off → 0).
+     * Passive/meta attributes stay ungated.
+     * @type {Set<string>}
+     */
+    this._gatedOperationalAttributes = new Set((_options$gatedOperati = options.gatedOperationalAttributes) !== null && _options$gatedOperati !== void 0 ? _options$gatedOperati : ['fan-level', 'rpm', 'level', 'speed']);
+
+    /** @type {Array<object>} declared chains (Phase 3) */
+    this._chains = [];
+
+    /** @type {boolean} */
+    this._batching = false;
+
+    /** @type {Map<string, { address: string, desired: *, effective: * }>} */
+    this._pendingNotifications = new Map();
+  }
+
+  // ─── Load / reset ─────────────────────────────────────────────────────────
+
+  /**
+   * Load plant, groups, and initial desired values from a scene-like declaration.
+   * @param {object} declaration
+   * @param {object} [declaration.plant]
+   * @param {object} [declaration.groups]
+   * @param {object} [declaration.stateRegistry]
+   * @param {Array<object>} [declaration.chains]
+   */
+  return _createClass(StateEngine, [{
+    key: "load",
+    value: function load() {
+      var _declaration$plant;
+      var declaration = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+      this._desired.clear();
+      this._groupMembers.clear();
+      this._groupDesired.clear();
+      this._chains = Array.isArray(declaration.chains) ? _toConsumableArray(declaration.chains) : [];
+      var plantDefault = ((_declaration$plant = declaration.plant) === null || _declaration$plant === void 0 || (_declaration$plant = _declaration$plant.states) === null || _declaration$plant === void 0 || (_declaration$plant = _declaration$plant.power) === null || _declaration$plant === void 0 ? void 0 : _declaration$plant.default) !== undefined ? declaration.plant.states.power.default : true;
+      this._plantPowerDesired = Boolean(plantDefault);
+      this._desired.set(makeAddress('plant', 'power'), this._plantPowerDesired);
+      var groups = declaration.groups || {};
+      for (var _i = 0, _Object$entries = Object.entries(groups); _i < _Object$entries.length; _i++) {
+        var _group$states;
+        var _Object$entries$_i = _slicedToArray(_Object$entries[_i], 2),
+          groupId = _Object$entries$_i[0],
+          group = _Object$entries$_i[1];
+        var members = Array.isArray(group.members) ? group.members : [];
+        this._groupMembers.set(groupId, new Set(members));
+        var groupPower = ((_group$states = group.states) === null || _group$states === void 0 || (_group$states = _group$states.power) === null || _group$states === void 0 ? void 0 : _group$states.default) !== undefined ? group.states.power.default : true;
+        this._groupDesired.set(groupId, Boolean(groupPower));
+        this._desired.set(makeAddress("group:".concat(groupId), 'power'), Boolean(groupPower));
+      }
+      var registry = declaration.stateRegistry || {};
+      for (var _i2 = 0, _Object$entries2 = Object.entries(registry); _i2 < _Object$entries2.length; _i2++) {
+        var _Object$entries2$_i = _slicedToArray(_Object$entries2[_i2], 2),
+          address = _Object$entries2$_i[0],
+          value = _Object$entries2$_i[1];
+        this._desired.set(address, value);
+        if (address === makeAddress('plant', 'power')) {
+          this._plantPowerDesired = Boolean(value);
+        }
+        var groupMatch = /^group:([^:]+)::power$/.exec(address);
+        if (groupMatch) {
+          this._groupDesired.set(groupMatch[1], Boolean(value));
+        }
+      }
+    }
+  }, {
+    key: "reset",
+    value: function reset() {
+      this._desired.clear();
+      this._groupMembers.clear();
+      this._groupDesired.clear();
+      this._chains = [];
+      this._plantPowerDesired = true;
+      this._pendingNotifications.clear();
+      this._batching = false;
+    }
+
+    // ─── Desired / effective ──────────────────────────────────────────────────
+
+    /**
+     * @param {string} address
+     * @returns {*}
+     */
+  }, {
+    key: "getDesired",
+    value: function getDesired(address) {
+      return this._desired.has(address) ? this._desired.get(address) : undefined;
+    }
+
+    /**
+     * Compute effective value for an address.
+     * Power-style gates: plant AND all containing groups AND object desired.
+     * Non-power attributes: return desired when power gates allow, else a safe off value.
+     *
+     * @param {string} address
+     * @returns {*}
+     */
+  }, {
+    key: "getEffective",
+    value: function getEffective(address) {
+      var desired = this.getDesired(address);
+      if (desired === undefined) return undefined;
+      if (address === makeAddress('plant', 'power')) {
+        return Boolean(desired);
+      }
+      var groupPowerMatch = /^group:([^:]+)::power$/.exec(address);
+      if (groupPowerMatch) {
+        return this._plantPowerDesired && Boolean(desired);
+      }
+      var objectPowerMatch = /^([^:]+)::power$/.exec(address);
+      if (objectPowerMatch && !address.startsWith('group:') && !address.startsWith('plant::')) {
+        var objectId = objectPowerMatch[1];
+        // Skip nested I/O addresses like pump-001::start-switch::mode
+        if (address.split('::').length !== 2) {
+          return desired;
+        }
+        return this._isPowerAllowedForObject(objectId) && Boolean(desired);
+      }
+
+      // Flow and other attrs: when tied to an object id prefix, gate on that object's power path
+      var parts = address.split('::');
+      if (parts.length === 2) {
+        var _parts = _slicedToArray(parts, 2),
+          _objectId = _parts[0],
+          attribute = _parts[1];
+        if (attribute === 'flow') {
+          var powerAllowed = this._isPowerAllowedForObject(_objectId);
+          if (!powerAllowed) return false;
+          return Boolean(desired);
+        }
+        // Operational values (fan level, rpm, …) collapse to a safe-off value when
+        // the object's power is not effectively on; restored when power returns (§6, §10).
+        if (this._gatedOperationalAttributes.has(attribute)) {
+          if (!this._isPowerAllowedForObject(_objectId)) return offValue(desired);
+          return desired;
+        }
+      }
+      return desired;
+    }
+
+    /**
+     * @param {string} objectId
+     * @returns {boolean}
+     */
+  }, {
+    key: "_isPowerAllowedForObject",
+    value: function _isPowerAllowedForObject(objectId) {
+      if (!this._plantPowerDesired) return false;
+      var _iterator = _createForOfIteratorHelper(this._groupMembers),
+        _step;
+      try {
+        for (_iterator.s(); !(_step = _iterator.n()).done;) {
+          var _step$value = _slicedToArray(_step.value, 2),
+            groupId = _step$value[0],
+            members = _step$value[1];
+          if (members.has(objectId)) {
+            var groupOn = this._groupDesired.get(groupId);
+            if (!groupOn) return false;
+          }
+        }
+      } catch (err) {
+        _iterator.e(err);
+      } finally {
+        _iterator.f();
+      }
+      return true;
+    }
+
+    /**
+     * Groups that contain an object.
+     * @param {string} objectId
+     * @returns {string[]}
+     */
+  }, {
+    key: "getGroupsForObject",
+    value: function getGroupsForObject(objectId) {
+      var result = [];
+      var _iterator2 = _createForOfIteratorHelper(this._groupMembers),
+        _step2;
+      try {
+        for (_iterator2.s(); !(_step2 = _iterator2.n()).done;) {
+          var _step2$value = _slicedToArray(_step2.value, 2),
+            groupId = _step2$value[0],
+            members = _step2$value[1];
+          if (members.has(objectId)) result.push(groupId);
+        }
+      } catch (err) {
+        _iterator2.e(err);
+      } finally {
+        _iterator2.f();
+      }
+      return result;
+    }
+
+    // ─── Writes ───────────────────────────────────────────────────────────────
+
+    /**
+     * Set a desired value through the single write door and run one bounded
+     * propagation pass: no-op stop, gate recompute, declared chains with depth
+     * and visited-set guards, then batched notifications (Framework §11, §12).
+     *
+     * @param {string} address
+     * @param {*} value
+     * @returns {boolean} true if the desired value changed
+     */
+  }, {
+    key: "setDesired",
+    value: function setDesired(address, value) {
+      this._beginBatch();
+      var ctx = {
+        visited: new Map()
+      };
+      var changed = this._writeHop(address, value, 0, ctx);
+      this._endBatch();
+      return changed;
+    }
+
+    /**
+     * One hop of a propagation pass: apply the write, then walk declared chains.
+     * @param {string} address
+     * @param {*} value
+     * @param {number} depth
+     * @param {{ visited: Map<string, *> }} ctx
+     * @returns {boolean} whether this hop changed the desired value
+     */
+  }, {
+    key: "_writeHop",
+    value: function _writeHop(address, value, depth, ctx) {
+      var result = this._applyWrite(address, value, ctx);
+      if (!result.changed) return false;
+      this._walkChains(result, depth, ctx);
+      return true;
+    }
+
+    /**
+     * Atomic write door: no-op stop (§11.1), visited-set cycle guard (§11.5),
+     * store desired, update gate mirrors, compute which effectives changed, and
+     * queue notifications for changed addresses only.
+     *
+     * @param {string} address
+     * @param {*} value
+     * @param {{ visited: Map<string, *> }} ctx
+     * @returns {{ changed: boolean, desiredChanged?: string, effectiveChanged?: Set<string> }}
+     */
+  }, {
+    key: "_applyWrite",
+    value: function _applyWrite(address, value, ctx) {
+      var previous = this.getDesired(address);
+      if (previous !== undefined && valuesEqual(previous, value)) {
+        return {
+          changed: false
+        }; // §11.1 no-op stop
+      }
+
+      // §11.5 visited-set: writing the same pair a different value this pass = cycle conflict
+      if (ctx.visited.has(address) && !valuesEqual(ctx.visited.get(address), value)) {
+        console.warn("[StateEngine] cycle conflict: ".concat(address, " rewritten to a different value in one pass; stopping branch"));
+        return {
+          changed: false
+        };
+      }
+      ctx.visited.set(address, value);
+
+      // Snapshot effective for every address this write might gate, before mutating.
+      var affected = this._affectedByWrite(address);
+      var before = new Map();
+      var _iterator3 = _createForOfIteratorHelper(affected),
+        _step3;
+      try {
+        for (_iterator3.s(); !(_step3 = _iterator3.n()).done;) {
+          var a = _step3.value;
+          before.set(a, this.getEffective(a));
+        }
+
+        // Store desired + keep plant/group gate mirrors in sync.
+      } catch (err) {
+        _iterator3.e(err);
+      } finally {
+        _iterator3.f();
+      }
+      this._desired.set(address, value);
+      if (address === makeAddress('plant', 'power')) {
+        this._plantPowerDesired = Boolean(value);
+      }
+      var groupMatch = /^group:([^:]+)::power$/.exec(address);
+      if (groupMatch) {
+        this._groupDesired.set(groupMatch[1], Boolean(value));
+      }
+
+      // Which effectives actually changed (§11.4 dedupe: notify once, changed only).
+      var effectiveChanged = new Set();
+      var _iterator4 = _createForOfIteratorHelper(affected),
+        _step4;
+      try {
+        for (_iterator4.s(); !(_step4 = _iterator4.n()).done;) {
+          var _a = _step4.value;
+          if (!valuesEqual(before.get(_a), this.getEffective(_a))) effectiveChanged.add(_a);
+        }
+      } catch (err) {
+        _iterator4.e(err);
+      } finally {
+        _iterator4.f();
+      }
+      this._queueNotification(address); // desired changed
+      var _iterator5 = _createForOfIteratorHelper(effectiveChanged),
+        _step5;
+      try {
+        for (_iterator5.s(); !(_step5 = _iterator5.n()).done;) {
+          var _a2 = _step5.value;
+          if (_a2 !== address) this._queueNotification(_a2);
+        }
+      } catch (err) {
+        _iterator5.e(err);
+      } finally {
+        _iterator5.f();
+      }
+      return {
+        changed: true,
+        desiredChanged: address,
+        effectiveChanged: effectiveChanged
+      };
+    }
+
+    /**
+     * Addresses whose effective value a write to `address` could change: the
+     * address itself, plus gate dependents (all keys for plant power, member
+     * keys for group power).
+     * @param {string} address
+     * @returns {string[]}
+     */
+  }, {
+    key: "_affectedByWrite",
+    value: function _affectedByWrite(address) {
+      var affected = new Set([address]);
+      if (address === makeAddress('plant', 'power')) {
+        var _iterator6 = _createForOfIteratorHelper(this._desired.keys()),
+          _step6;
+        try {
+          for (_iterator6.s(); !(_step6 = _iterator6.n()).done;) {
+            var key = _step6.value;
+            affected.add(key);
+          }
+        } catch (err) {
+          _iterator6.e(err);
+        } finally {
+          _iterator6.f();
+        }
+        return _toConsumableArray(affected);
+      }
+      var groupMatch = /^group:([^:]+)::power$/.exec(address);
+      if (groupMatch) {
+        var members = this._groupMembers.get(groupMatch[1]);
+        if (members) {
+          var _iterator7 = _createForOfIteratorHelper(members),
+            _step7;
+          try {
+            for (_iterator7.s(); !(_step7 = _iterator7.n()).done;) {
+              var memberId = _step7.value;
+              var _iterator8 = _createForOfIteratorHelper(this._desired.keys()),
+                _step8;
+              try {
+                for (_iterator8.s(); !(_step8 = _iterator8.n()).done;) {
+                  var _key = _step8.value;
+                  if (_key.startsWith("".concat(memberId, "::"))) affected.add(_key);
+                }
+              } catch (err) {
+                _iterator8.e(err);
+              } finally {
+                _iterator8.f();
+              }
+            }
+          } catch (err) {
+            _iterator7.e(err);
+          } finally {
+            _iterator7.f();
+          }
+        }
+      }
+      return _toConsumableArray(affected);
+    }
+
+    /**
+     * Walk declared chains triggered by this write (§10, §11.3). Desired-source
+     * chains fire when the trigger's desired changed; effective-source chains fire
+     * when the trigger's effective changed (so plant/group-off ripples through
+     * `pump effective → pipe flow`, §17). Only `copy` is supported.
+     *
+     * @param {{ desiredChanged?: string, effectiveChanged?: Set<string> }} result
+     * @param {number} depth
+     * @param {{ visited: Map<string, *> }} ctx
+     */
+  }, {
+    key: "_walkChains",
+    value: function _walkChains(result, depth, ctx) {
+      if (this._chains.length === 0) return;
+      var _iterator9 = _createForOfIteratorHelper(this._chains),
+        _step9;
+      try {
+        for (_iterator9.s(); !(_step9 = _iterator9.n()).done;) {
+          var _result$effectiveChan;
+          var chain = _step9.value;
+          if (chain.action && chain.action !== 'copy') continue;
+          var trigger = makeAddress(chain.when.address, chain.when.attribute);
+          var useEffective = chain.when.source === 'effective';
+          var fires = useEffective ? (_result$effectiveChan = result.effectiveChanged) === null || _result$effectiveChan === void 0 ? void 0 : _result$effectiveChan.has(trigger) : result.desiredChanged === trigger;
+          if (!fires) continue;
+          if (depth + 1 > this.maxChainDepth) {
+            var _chain$id;
+            console.warn("[StateEngine] ripple depth limit (".concat(this.maxChainDepth, ") reached at chain ") + "\"".concat((_chain$id = chain.id) !== null && _chain$id !== void 0 ? _chain$id : '<unnamed>', "\" (").concat(trigger, " \u2192 ").concat(makeAddress(chain.set.address, chain.set.attribute), "); stopping path"));
+            continue;
+          }
+          var nextValue = useEffective ? this.getEffective(trigger) : this.getDesired(trigger);
+          var target = makeAddress(chain.set.address, chain.set.attribute);
+          this._writeHop(target, nextValue, depth + 1, ctx);
+        }
+      } catch (err) {
+        _iterator9.e(err);
+      } finally {
+        _iterator9.f();
+      }
+    }
+
+    // ─── Pipe lifecycle (Framework §9, §15) ─────────────────────────────────────
+
+    /**
+     * Register a pipe/path in the registry so its flow state exists and is tied to
+     * pipe lifecycle (no orphan keys). Keyed on the pipe/path id, never on segment
+     * declared/computed status (§9). No-op if already registered.
+     * @param {string} pipeId
+     * @param {object} [options]
+     * @param {boolean} [options.defaultFlow=false]
+     * @returns {string} the flow address
+     */
+  }, {
+    key: "registerPipe",
+    value: function registerPipe(pipeId) {
+      var options = arguments.length > 1 && arguments[1] !== undefined ? arguments[1] : {};
+      var address = makeAddress(pipeId, 'flow');
+      if (!this._desired.has(address)) {
+        var _options$defaultFlow;
+        this._beginBatch();
+        this._desired.set(address, Boolean((_options$defaultFlow = options.defaultFlow) !== null && _options$defaultFlow !== void 0 ? _options$defaultFlow : false));
+        this._queueNotification(address);
+        this._endBatch();
+      }
+      return address;
+    }
+
+    /**
+     * Remove a pipe and all of its registry entries when the pipe is destroyed, so
+     * keys do not linger (§15). Emits a final notification (desired/effective
+     * undefined) per removed key.
+     * @param {string} pipeId
+     * @returns {number} number of registry keys removed
+     */
+  }, {
+    key: "unregisterPipe",
+    value: function unregisterPipe(pipeId) {
+      var prefix = "".concat(pipeId, "::");
+      var removed = _toConsumableArray(this._desired.keys()).filter(function (k) {
+        return k.startsWith(prefix);
+      });
+      if (removed.length === 0) return 0;
+      this._beginBatch();
+      var _iterator0 = _createForOfIteratorHelper(removed),
+        _step0;
+      try {
+        for (_iterator0.s(); !(_step0 = _iterator0.n()).done;) {
+          var key = _step0.value;
+          this._desired.delete(key);
+        }
+      } catch (err) {
+        _iterator0.e(err);
+      } finally {
+        _iterator0.f();
+      }
+      var _iterator1 = _createForOfIteratorHelper(removed),
+        _step1;
+      try {
+        for (_iterator1.s(); !(_step1 = _iterator1.n()).done;) {
+          var _key2 = _step1.value;
+          this._queueNotification(_key2);
+        }
+      } catch (err) {
+        _iterator1.e(err);
+      } finally {
+        _iterator1.f();
+      }
+      this._endBatch();
+      return removed.length;
+    }
+  }, {
+    key: "_beginBatch",
+    value: function _beginBatch() {
+      this._batching = true;
+      this._pendingNotifications.clear();
+    }
+  }, {
+    key: "_queueNotification",
+    value: function _queueNotification(address) {
+      var change = {
+        address: address,
+        desired: this.getDesired(address),
+        effective: this.getEffective(address)
+      };
+      if (this._batching) {
+        this._pendingNotifications.set(address, change);
+      } else {
+        this._emit(change);
+      }
+    }
+  }, {
+    key: "_endBatch",
+    value: function _endBatch() {
+      this._batching = false;
+      var changes = _toConsumableArray(this._pendingNotifications.values());
+      this._pendingNotifications.clear();
+      var _iterator10 = _createForOfIteratorHelper(changes),
+        _step10;
+      try {
+        for (_iterator10.s(); !(_step10 = _iterator10.n()).done;) {
+          var change = _step10.value;
+          this._emit(change);
+        }
+      } catch (err) {
+        _iterator10.e(err);
+      } finally {
+        _iterator10.f();
+      }
+    }
+  }, {
+    key: "_emit",
+    value: function _emit(change) {
+      var _iterator11 = _createForOfIteratorHelper(this._listeners),
+        _step11;
+      try {
+        for (_iterator11.s(); !(_step11 = _iterator11.n()).done;) {
+          var listener = _step11.value;
+          try {
+            listener(change);
+          } catch (err) {
+            console.error('[StateEngine] listener error:', err);
+          }
+        }
+      } catch (err) {
+        _iterator11.e(err);
+      } finally {
+        _iterator11.f();
+      }
+    }
+
+    /**
+     * @param {(change: { address: string, desired: *, effective: * }) => void} listener
+     * @returns {() => void} unsubscribe
+     */
+  }, {
+    key: "subscribe",
+    value: function subscribe(listener) {
+      var _this = this;
+      this._listeners.add(listener);
+      return function () {
+        return _this._listeners.delete(listener);
+      };
+    }
+
+    /**
+     * Snapshot of all desired values (for save / debug).
+     * @returns {Record<string, *>}
+     */
+  }, {
+    key: "toRegistry",
+    value: function toRegistry() {
+      var out = {};
+      var _iterator12 = _createForOfIteratorHelper(this._desired),
+        _step12;
+      try {
+        for (_iterator12.s(); !(_step12 = _iterator12.n()).done;) {
+          var _step12$value = _slicedToArray(_step12.value, 2),
+            k = _step12$value[0],
+            v = _step12$value[1];
+          out[k] = v;
+        }
+      } catch (err) {
+        _iterator12.e(err);
+      } finally {
+        _iterator12.f();
+      }
+      return out;
+    }
+
+    /**
+     * Reconstruct the §17 scene declaration (plant / groups / chains /
+     * stateRegistry) from current engine state, for scene save. Round-trips with
+     * {@link StateEngine#load}.
+     * @returns {{ version: string, plant: object, groups: object, chains: object[], stateRegistry: Record<string, *> }}
+     */
+  }, {
+    key: "toDeclaration",
+    value: function toDeclaration() {
+      var groups = {};
+      var _iterator13 = _createForOfIteratorHelper(this._groupMembers),
+        _step13;
+      try {
+        for (_iterator13.s(); !(_step13 = _iterator13.n()).done;) {
+          var _this$_groupDesired$g;
+          var _step13$value = _slicedToArray(_step13.value, 2),
+            groupId = _step13$value[0],
+            members = _step13$value[1];
+          groups[groupId] = {
+            members: _toConsumableArray(members),
+            states: {
+              power: {
+                type: 'Boolean',
+                default: (_this$_groupDesired$g = this._groupDesired.get(groupId)) !== null && _this$_groupDesired$g !== void 0 ? _this$_groupDesired$g : true,
+                gate: true
+              }
+            }
+          };
+        }
+      } catch (err) {
+        _iterator13.e(err);
+      } finally {
+        _iterator13.f();
+      }
+      return {
+        version: '3.0',
+        plant: {
+          states: {
+            power: {
+              type: 'Boolean',
+              default: this._plantPowerDesired,
+              gate: true
+            }
+          }
+        },
+        groups: groups,
+        chains: _toConsumableArray(this._chains),
+        stateRegistry: this.toRegistry()
+      };
+    }
+  }]);
+}();
+
+/**
+ * Registry address for an I/O device data point.
+ * Shape: `${parentUuid}::${attachmentId}::${stateId}` (matches §17
+ * `pump-001::start-switch::mode`). The scoped key is `${parentUuid}::${attachmentId}`.
+ *
+ * @param {string} attachmentId
+ * @param {string} stateId
+ * @param {string} [parentUuid]
+ * @returns {string}
+ */
+function ioAddress(attachmentId, stateId, parentUuid) {
+  return makeAddress(getScopedAttachmentKey(attachmentId, parentUuid), stateId);
+}
+
+/**
+ * Parse an I/O device address back into its parts. Returns null for
+ * plant/group/object/pipe addresses (2-part) — I/O device data points are 3-part
+ * because a device always has a parent component (§8; free-floating I/O rejected).
+ *
+ * @param {string} address
+ * @returns {{ parentUuid: string, attachmentId: string, stateId: string, scopedKey: string } | null}
+ */
+function parseIoAddress(address) {
+  if (typeof address !== 'string') return null;
+  var parts = address.split('::');
+  if (parts.length !== 3) return null;
+  var _parts = _slicedToArray(parts, 3),
+    parentUuid = _parts[0],
+    attachmentId = _parts[1],
+    stateId = _parts[2];
+  return {
+    parentUuid: parentUuid,
+    attachmentId: attachmentId,
+    stateId: stateId,
+    scopedKey: "".concat(parentUuid, "::").concat(attachmentId)
+  };
+}
+
+/**
+ * Read a State Engine declaration out of scene data, tolerating legacy scenes.
+ * v3.0 scenes carry `plant` / `groups` / `chains` / `stateRegistry`; older v2.3
+ * scenes have none of these and load with safe defaults (plant power on, no
+ * groups, no chains) so nothing crashes on unknown/missing fields (§15).
+ *
+ * @param {object} [sceneData]
+ * @returns {{ plant: object, groups: object, chains: object[], stateRegistry: object }}
+ */
+function extractDeclaration() {
+  var sceneData = arguments.length > 0 && arguments[0] !== undefined ? arguments[0] : {};
+  return {
+    plant: sceneData.plant || {
+      states: {
+        power: {
+          type: 'Boolean',
+          default: true,
+          gate: true
+        }
+      }
+    },
+    groups: sceneData.groups || {},
+    chains: Array.isArray(sceneData.chains) ? sceneData.chains : [],
+    stateRegistry: sceneData.stateRegistry || {}
+  };
+}
+
+/**
+ * Merge a State Engine's current declaration (plant / groups / chains /
+ * stateRegistry) into an export object, bumping it to version 3.0. Mutates and
+ * returns `exportData`.
+ *
+ * @param {object} exportData - the scene export object being assembled
+ * @param {{ toDeclaration: () => object }} engine
+ * @returns {object} exportData
+ */
+function applyDeclarationToExport(exportData, engine) {
+  if (!exportData || !engine || typeof engine.toDeclaration !== 'function') return exportData;
+  var declaration = engine.toDeclaration();
+  exportData.version = '3.0';
+  exportData.plant = declaration.plant;
+  exportData.groups = declaration.groups;
+  if (declaration.chains.length > 0) exportData.chains = declaration.chains;
+  exportData.stateRegistry = declaration.stateRegistry;
+  return exportData;
+}
+
 var SceneExportManager = /*#__PURE__*/function () {
   function SceneExportManager(sceneViewer) {
     _classCallCheck(this, SceneExportManager);
@@ -12167,7 +12978,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');
@@ -12400,6 +13212,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;
@@ -28239,6 +29058,21 @@ var PathRenderingManager = /*#__PURE__*/function (_BaseDisposable) {
       }
     }
 
+    /**
+     * Read the current color of a path's shared material as a `#rrggbb` string,
+     * or null if the path has no material. Used to snapshot a pipe's baseline
+     * colour before it is temporarily overpainted (e.g. flow gating).
+     *
+     * @param {string} pathId - "${from}-->${to}"
+     * @returns {string|null}
+     */
+  }, {
+    key: "getPathColorHex",
+    value: function getPathColorHex(pathId) {
+      var mat = this._pathMaterials.get(pathId);
+      return mat ? "#".concat(mat.color.getHexString()) : null;
+    }
+
     /**
      * Get path colors for visual distinction
      * @param {number} index - Path index
@@ -30770,6 +31604,9 @@ var TEMP_MIN = 0;
 /** Maximum temperature in the colour ramp (maps to pure red). */
 var TEMP_MAX = 100;
 
+/** Colour a pipe is painted when its effective flow is gated off (§6.1). */
+var PIPE_OFF_GRAY = '#3a3a3a';
+
 /**
  * Convert a temperature value to a CSS hex colour string using a blue→red HSL
  * ramp.  Values are clamped to [TEMP_MIN, TEMP_MAX].
@@ -30807,22 +31644,78 @@ var PathFlowManager = /*#__PURE__*/function (_BaseDisposable) {
      * @type {Map<string, Record<string, any>>}
      */
     _this._derivedStore = new Map();
+
+    /**
+     * Paths whose effective flow is gated off (State Engine §6.1). While a path
+     * is in this set it is painted {@link PIPE_OFF_GRAY} and temperature updates
+     * are suppressed so they don't override the off-look.
+     * @type {Set<string>}
+     */
+    _this._flowGatedOff = new Set();
+
+    /**
+     * Baseline (on-state) colour snapshotted the moment a path is gated off, so
+     * it can be restored exactly when flow returns — including pipes with no
+     * declared flowTemperature, whose colour is the base pipe material.
+     * @type {Map<string, string>}
+     */
+    _this._flowBaseColor = new Map();
     return _this;
   }
 
-  // ── Public API — attribute write ──────────────────────────────────────────
+  // ── Flow gating (State Engine effective → 3D bridge, §6.1) ─────────────────
 
   /**
-   * Set a declared (persistent) flow attribute on a path.
-   * The value is stored in PathData and will be serialised with the scene.
-   * Triggers a visual update.
+   * Gate a path's flow visual on/off from the State Engine's effective `flow`.
+   * Off → paint the shared per-path material gray; on → restore the temperature
+   * colour. The off state is sticky (see {@link _flowGatedOff}).
    *
-   * @param {string} pathId - e.g. "PUMP-1-CONN-1-->CHILLER-1-CONN-2"
-   * @param {string} key    - One of FLOW_ATTRIBUTE_KEYS
-   * @param {any}    value
+   * @param {string} pathId  - `${from}-->${to}`
+   * @param {boolean} enabled - Effective flow
    */
   _inherits(PathFlowManager, _BaseDisposable);
   return _createClass(PathFlowManager, [{
+    key: "setFlowEnabled",
+    value: function setFlowEnabled(pathId, enabled) {
+      var split = this._splitPathId(pathId);
+      if (!split) return;
+      var renderingManager = this._getRenderingManager();
+      if (enabled) {
+        this._flowGatedOff.delete(pathId);
+        // Prefer a temperature-derived colour if one is declared; otherwise
+        // restore the baseline snapshotted when the pipe was gated off (this is
+        // what fixes plain, non-temperature pipes getting stuck gray).
+        var temp = this.resolve(pathId, 'flowTemperature');
+        if (temp !== null && temp !== undefined) {
+          this.applyVisualizationForPath(pathId);
+        } else if (this._flowBaseColor.has(pathId)) {
+          renderingManager === null || renderingManager === void 0 || renderingManager.updatePathColor(split.from, split.to, this._flowBaseColor.get(pathId));
+        }
+        this._flowBaseColor.delete(pathId);
+      } else {
+        // Snapshot the current (on-state) colour once, before overpainting gray.
+        if (!this._flowGatedOff.has(pathId) && renderingManager) {
+          var _renderingManager$get;
+          var base = (_renderingManager$get = renderingManager.getPathColorHex) === null || _renderingManager$get === void 0 ? void 0 : _renderingManager$get.call(renderingManager, pathId);
+          if (base) this._flowBaseColor.set(pathId, base);
+        }
+        this._flowGatedOff.add(pathId);
+        renderingManager === null || renderingManager === void 0 || renderingManager.updatePathColor(split.from, split.to, PIPE_OFF_GRAY);
+      }
+    }
+
+    // ── Public API — attribute write ──────────────────────────────────────────
+
+    /**
+     * Set a declared (persistent) flow attribute on a path.
+     * The value is stored in PathData and will be serialised with the scene.
+     * Triggers a visual update.
+     *
+     * @param {string} pathId - e.g. "PUMP-1-CONN-1-->CHILLER-1-CONN-2"
+     * @param {string} key    - One of FLOW_ATTRIBUTE_KEYS
+     * @param {any}    value
+     */
+  }, {
     key: "setDeclared",
     value: function setDeclared(pathId, key, value) {
       var pd = this._getPathData(pathId);
@@ -30928,6 +31821,13 @@ var PathFlowManager = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "applyVisualizationForPath",
     value: function applyVisualizationForPath(pathId) {
+      // Effective flow gated off (§6.1) — keep the off-look, ignore temperature.
+      if (this._flowGatedOff.has(pathId)) {
+        var _this$_getRenderingMa;
+        var _split = this._splitPathId(pathId);
+        if (_split) (_this$_getRenderingMa = this._getRenderingManager()) === null || _this$_getRenderingMa === void 0 || _this$_getRenderingMa.updatePathColor(_split.from, _split.to, PIPE_OFF_GRAY);
+        return;
+      }
       var temp = this.resolve(pathId, 'flowTemperature');
       if (temp === null || temp === undefined) {
         return; // No temperature declared — leave default pipe color
@@ -30935,17 +31835,30 @@ var PathFlowManager = /*#__PURE__*/function (_BaseDisposable) {
       var color = temperatureToColor(temp);
       var renderingManager = this._getRenderingManager();
       if (!renderingManager) return;
+      var split = this._splitPathId(pathId);
+      if (!split) return;
+      renderingManager.updatePathColor(split.from, split.to, color);
+      console.log("\uD83C\uDF21\uFE0F PathFlowManager: \"".concat(pathId, "\" \u2192 flowTemperature ").concat(temp, " \u2192 ").concat(color));
+    }
 
-      // pathId = "from-->to"; extract the two halves
+    /**
+     * Split a `${from}-->${to}` pathId into its two connector halves.
+     * @param {string} pathId
+     * @returns {{ from: string, to: string }|null} null if malformed
+     * @private
+     */
+  }, {
+    key: "_splitPathId",
+    value: function _splitPathId(pathId) {
       var sepIdx = pathId.indexOf('-->');
       if (sepIdx === -1) {
         console.warn("PathFlowManager: malformed pathId \"".concat(pathId, "\""));
-        return;
+        return null;
       }
-      var from = pathId.slice(0, sepIdx);
-      var to = pathId.slice(sepIdx + 3);
-      renderingManager.updatePathColor(from, to, color);
-      console.log("\uD83C\uDF21\uFE0F PathFlowManager: \"".concat(pathId, "\" \u2192 flowTemperature ").concat(temp, " \u2192 ").concat(color));
+      return {
+        from: pathId.slice(0, sepIdx),
+        to: pathId.slice(sepIdx + 3)
+      };
     }
 
     /**
@@ -30977,6 +31890,8 @@ var PathFlowManager = /*#__PURE__*/function (_BaseDisposable) {
     key: "dispose",
     value: function dispose() {
       this._derivedStore.clear();
+      this._flowGatedOff.clear();
+      this._flowBaseColor.clear();
       this.sceneViewer = null;
       _superPropGet(PathFlowManager, "dispose", this, 3)([]);
     }
@@ -37899,7 +38814,6 @@ var ComponentTooltipManager = /*#__PURE__*/function (_BaseDisposable) {
       if (!ioDeviceObject || !this._stateAdapter) return;
       var ud = ioDeviceObject.userData;
       var attachmentId = ud === null || ud === void 0 ? void 0 : ud.attachmentId;
-      var dataPoints = (ud === null || ud === void 0 ? void 0 : ud.dataPoints) || [];
       if (!attachmentId) return;
 
       // Walk up to find parent component UUID for scoped state/behavior handling
@@ -37914,6 +38828,13 @@ var ComponentTooltipManager = /*#__PURE__*/function (_BaseDisposable) {
         obj = obj.parent;
       }
 
+      // Derive the device's data points from its behaviorConfig (same resolver the
+      // drag path uses). `userData.dataPoints` is not populated for attached
+      // devices, so reading it directly would find nothing — resolve instead, and
+      // keep the legacy field only as a fallback.
+      var resolved = resolveDataPoints(parentUuid, attachmentId, ud, getIoBehaviorManager(this.sceneViewer), null);
+      var dataPoints = resolved !== null && resolved !== void 0 && resolved.length ? resolved : (ud === null || ud === void 0 ? void 0 : ud.dataPoints) || [];
+
       // Create a scoped attachment key to prevent state sharing between instances
       // of the same smart component that share the same attachmentId
       var scopedAttachmentId = getScopedAttachmentKey(attachmentId, parentUuid);
@@ -40328,6 +41249,611 @@ var IoOutlineManager = /*#__PURE__*/function (_BaseDisposable) {
   }]);
 }(BaseDisposable);
 
+/** 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);
+
+/**
+ * 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__namespace.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__namespace.Group();
+              top.position.set(0, 0, deskHeight);
+              top.rotation.set(tilt, 0, 0, 'XYZ');
+              panel.add(top);
+              board = new THREE__namespace.Mesh(new THREE__namespace.BoxGeometry(width, depth, thickness), new THREE__namespace.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__namespace.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__namespace.Mesh(new THREE__namespace.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__namespace.CanvasTexture(canvas);
+      texture.minFilter = THREE__namespace.LinearFilter;
+      texture.anisotropy = 4;
+      var material = new THREE__namespace.SpriteMaterial({
+        map: texture,
+        transparent: true,
+        depthTest: false,
+        // always readable, never occluded by the board/switch
+        depthWrite: false
+      });
+      var sprite = new THREE__namespace.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);
+
 // ─────────────────────────────────────────────────────────────────────────────
 // Flow-direction helpers (module-level)
 // ─────────────────────────────────────────────────────────────────────────────
@@ -40451,6 +41977,8 @@ var CentralPlantInternals = /*#__PURE__*/function () {
       this.centralPlant.managers.viewport2DManager = new Viewport2DManager(this.centralPlant.sceneViewer);
       this.centralPlant.managers.ioBehaviorManager = new IoBehaviorManager(this.centralPlant.sceneViewer);
       this.centralPlant.managers.ioOutlineManager = new IoOutlineManager(this.centralPlant.sceneViewer);
+      this.centralPlant.managers.effectiveVisualManager = new EffectiveVisualManager(this.centralPlant.sceneViewer);
+      this.centralPlant.managers.controlPanelManager = new ControlPanelManager(this.centralPlant.sceneViewer);
 
       // All managers are now stored in the managers collection and will be attached via attachToComponent()
     }
@@ -41884,7 +43412,7 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
    * Initialize the CentralPlant manager
    * 
    * @constructor
-   * @version 0.3.58
+   * @version 0.3.59
    * @updated 2025-10-22
    * 
    * @description Creates a new CentralPlant instance and initializes internal managers and utilities.
@@ -41923,6 +43451,14 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
     // Initialize internals handler
     _this.internals = new CentralPlantInternals(_this);
 
+    // Portable State Engine: single source of truth for desired/effective state
+    // (plant/group/object/pipe). Owned here; the write door and scene load/save
+    // route through it. The 3D layer/store mirror its output (Framework §12–§13).
+    _this.stateEngine = new StateEngine();
+    _this._unsubscribeStateEngine = _this.stateEngine.subscribe(function (change) {
+      return _this._onEngineStateChange(change);
+    });
+
     // Optional cache primer function (dependency injection)
     _this.cachePrimer = null;
 
@@ -42099,6 +43635,16 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
                 timestamp: new Date().toISOString()
               });
 
+              // Load plant / groups / chains / stateRegistry into the State Engine. v3.0
+              // scenes carry these; legacy v2.3 scenes load with safe defaults (§15).
+              if (this.stateEngine) {
+                try {
+                  this.stateEngine.load(extractDeclaration(sceneData));
+                } catch (err) {
+                  console.warn('⚠️ setImportedSceneData(): stateEngine.load() failed:', err);
+                }
+              }
+
               // Scene behaviors loaded
 
               // Cross-component behaviors are registered by sceneOperationsManager.loadSceneData()
@@ -43047,12 +44593,32 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
     }
 
     /**
-     * Internal single path for I/O state changes: persist, animate, link, emit.
+     * Internal single path for I/O state changes. Routes the write through the
+     * State Engine (the one write door, Framework §12); the engine subscription
+     * ({@link CentralPlant#_onEngineStateChange}) mirrors to the state adapter,
+     * animates meshes, and emits. Falls back to a direct write only if the engine
+     * is unavailable.
      * @private
      */
   }, {
     key: "_dispatchIoState",
     value: function _dispatchIoState(attachmentId, stateId, value, parentUuid) {
+      if (this.stateEngine) {
+        this.stateEngine.setDesired(ioAddress(attachmentId, stateId, parentUuid), value);
+        return;
+      }
+      this._dispatchIoStateDirect(attachmentId, stateId, value, parentUuid);
+    }
+
+    /**
+     * Persist to the state adapter, animate meshes, and emit for one I/O data
+     * point. This is the mirror side of the engine (driven from desired, since I/O
+     * data points are ungated) and the legacy fallback when no engine is present.
+     * @private
+     */
+  }, {
+    key: "_dispatchIoStateDirect",
+    value: function _dispatchIoStateDirect(attachmentId, stateId, value, parentUuid) {
       var _this$managers, _this$sceneViewer5, _this$sceneViewer6, _this$managers2, _this$sceneViewer7, _this$sceneViewer8, _this$sceneViewer9;
       var tooltipMgr = ((_this$managers = this.managers) === null || _this$managers === void 0 ? void 0 : _this$managers.componentTooltipManager) || ((_this$sceneViewer5 = this.sceneViewer) === null || _this$sceneViewer5 === void 0 ? void 0 : _this$sceneViewer5.componentTooltipManager) || ((_this$sceneViewer6 = this.sceneViewer) === null || _this$sceneViewer6 === void 0 || (_this$sceneViewer6 = _this$sceneViewer6.managers) === null || _this$sceneViewer6 === void 0 ? void 0 : _this$sceneViewer6.componentTooltipManager);
       var stateAdapter = tooltipMgr === null || tooltipMgr === void 0 ? void 0 : tooltipMgr._stateAdapter;
@@ -43076,6 +44642,25 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
       });
     }
 
+    /**
+     * State Engine subscriber: fan a committed registry change out to the 3D/store
+     * layer. I/O device data points (3-part addresses) mirror to the adapter and
+     * animate; every change (incl. plant/group/object/pipe effective) is surfaced
+     * as `engine-state-changed` for gating-aware visual subscribers (§13).
+     * @private
+     * @param {{ address: string, desired: *, effective: * }} change
+     */
+  }, {
+    key: "_onEngineStateChange",
+    value: function _onEngineStateChange(change) {
+      var _this$sceneViewer0;
+      var io = parseIoAddress(change.address);
+      if (io) {
+        this._dispatchIoStateDirect(io.attachmentId, io.stateId, change.desired, io.parentUuid);
+      }
+      (_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 || _this$sceneViewer0.emit('engine-state-changed', change);
+    }
+
     /**
      * Configure the state adapter on both tooltip and behavior managers.
      * @param {{ getState: Function, setState: Function }} stateAdapter
@@ -43083,16 +44668,16 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "configureStateAdapter",
     value: function configureStateAdapter(stateAdapter) {
-      var _this$managers3, _this$sceneViewer0, _this$managers4, _this$sceneViewer10, _this$sceneViewer11;
-      var tooltipMgr = ((_this$managers3 = this.managers) === null || _this$managers3 === void 0 ? void 0 : _this$managers3.componentTooltipManager) || ((_this$sceneViewer0 = this.sceneViewer) === null || _this$sceneViewer0 === void 0 ? void 0 : _this$sceneViewer0.componentTooltipManager);
+      var _this$managers3, _this$sceneViewer1, _this$managers4, _this$sceneViewer11, _this$sceneViewer12;
+      var tooltipMgr = ((_this$managers3 = this.managers) === null || _this$managers3 === void 0 ? void 0 : _this$managers3.componentTooltipManager) || ((_this$sceneViewer1 = this.sceneViewer) === null || _this$sceneViewer1 === void 0 ? void 0 : _this$sceneViewer1.componentTooltipManager);
       if (tooltipMgr !== null && tooltipMgr !== void 0 && tooltipMgr.configure) {
-        var _this$sceneViewer1;
+        var _this$sceneViewer10;
         tooltipMgr.configure(stateAdapter);
-        if ((_this$sceneViewer1 = this.sceneViewer) !== null && _this$sceneViewer1 !== void 0 && _this$sceneViewer1.managers) {
+        if ((_this$sceneViewer10 = this.sceneViewer) !== null && _this$sceneViewer10 !== void 0 && _this$sceneViewer10.managers) {
           this.sceneViewer.managers.componentTooltipManager = tooltipMgr;
         }
       }
-      var ioBehavMgr = ((_this$managers4 = this.managers) === null || _this$managers4 === void 0 ? void 0 : _this$managers4.ioBehaviorManager) || ((_this$sceneViewer10 = this.sceneViewer) === null || _this$sceneViewer10 === void 0 || (_this$sceneViewer10 = _this$sceneViewer10.managers) === null || _this$sceneViewer10 === void 0 ? void 0 : _this$sceneViewer10.ioBehaviorManager) || ((_this$sceneViewer11 = this.sceneViewer) === null || _this$sceneViewer11 === void 0 ? void 0 : _this$sceneViewer11.ioBehaviorManager);
+      var ioBehavMgr = ((_this$managers4 = this.managers) === null || _this$managers4 === void 0 ? void 0 : _this$managers4.ioBehaviorManager) || ((_this$sceneViewer11 = this.sceneViewer) === null || _this$sceneViewer11 === void 0 || (_this$sceneViewer11 = _this$sceneViewer11.managers) === null || _this$sceneViewer11 === void 0 ? void 0 : _this$sceneViewer11.ioBehaviorManager) || ((_this$sceneViewer12 = this.sceneViewer) === null || _this$sceneViewer12 === void 0 ? void 0 : _this$sceneViewer12.ioBehaviorManager);
       if (ioBehavMgr !== null && ioBehavMgr !== void 0 && ioBehavMgr.configure) {
         ioBehavMgr.configure(stateAdapter);
       }
@@ -43127,8 +44712,8 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "getSceneAttachments",
     value: function getSceneAttachments() {
-      var _this$sceneViewer12;
-      var scene = (_this$sceneViewer12 = this.sceneViewer) === null || _this$sceneViewer12 === void 0 ? void 0 : _this$sceneViewer12.scene;
+      var _this$sceneViewer13;
+      var scene = (_this$sceneViewer13 = this.sceneViewer) === null || _this$sceneViewer13 === void 0 ? void 0 : _this$sceneViewer13.scene;
       if (!scene) return [];
       var results = [];
       scene.traverse(function (obj) {
@@ -44909,12 +46494,14 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "clearScene",
     value: function clearScene() {
-      var _this$sceneViewer13;
+      var _this$sceneViewer14, _this$stateEngine;
       this.importedSceneData = null;
-      var ioBehavMgr = (_this$sceneViewer13 = this.sceneViewer) === null || _this$sceneViewer13 === void 0 || (_this$sceneViewer13 = _this$sceneViewer13.managers) === null || _this$sceneViewer13 === void 0 ? void 0 : _this$sceneViewer13.ioBehaviorManager;
+      var ioBehavMgr = (_this$sceneViewer14 = this.sceneViewer) === null || _this$sceneViewer14 === void 0 || (_this$sceneViewer14 = _this$sceneViewer14.managers) === null || _this$sceneViewer14 === void 0 ? void 0 : _this$sceneViewer14.ioBehaviorManager;
       if (ioBehavMgr) {
         ioBehavMgr.setCrossComponentBehaviors([]);
       }
+      // Reset the registry so pipe/object keys from the old scene don't linger (§15).
+      (_this$stateEngine = this.stateEngine) === null || _this$stateEngine === void 0 || _this$stateEngine.reset();
       if (this.sceneViewer && this.sceneViewer.scene) {
         this.sceneViewer.scene.clear();
       }
@@ -44965,8 +46552,16 @@ var CentralPlant = /*#__PURE__*/function (_BaseDisposable) {
   }, {
     key: "_doDispose",
     value: function _doDispose() {
+      var _this$stateEngine2;
       console.log('🧹 Disposing CentralPlant using enhanced disposal patterns...');
 
+      // Tear down the State Engine subscription and registry.
+      if (this._unsubscribeStateEngine) {
+        this._unsubscribeStateEngine();
+        this._unsubscribeStateEngine = null;
+      }
+      (_this$stateEngine2 = this.stateEngine) === null || _this$stateEngine2 === void 0 || _this$stateEngine2.reset();
+
       // Use batch disposal for all managers
       var managers = Object.values(this.managers).filter(function (manager) {
         return manager && typeof manager.dispose === 'function';
@@ -50840,8 +52435,10 @@ exports.SceneInitializationManager = SceneInitializationManager;
 exports.SceneOperationsManager = SceneOperationsManager;
 exports.SceneTooltipsManager = SceneTooltipsManager;
 exports.SnapshotManager = SnapshotManager;
+exports.StateEngine = StateEngine;
 exports.ThreeJSResourceManager = ThreeJSResourceManager;
 exports.applyCrossComponentBehaviors = applyCrossComponentBehaviors;
+exports.applyDeclarationToExport = applyDeclarationToExport;
 exports.applyDefaultIoDeviceStates = applyDefaultIoDeviceStates;
 exports.applyModelRootTranslation = applyModelRootTranslation;
 exports.applyModelRootTranslationFromWorldBase = applyModelRootTranslationFromWorldBase;
@@ -50855,6 +52452,7 @@ exports.clearS3Cache = clearS3Cache;
 exports.collectSceneLibraryIds = collectSceneLibraryIds;
 exports.createPathfindingRequest = createPathfindingRequest;
 exports.createTransformControls = createTransformControls;
+exports.extractDeclaration = extractDeclaration;
 exports.findObjectByHardcodedUuid = findObjectByHardcodedUuid;
 exports.formatCacheExpiry = formatCacheExpiry;
 exports.generateUniqueComponentId = generateUniqueComponentId;
@@ -50880,6 +52478,7 @@ exports.getObjectsByType = getObjectsByType;
 exports.getScopedAttachmentKey = getScopedAttachmentKey;
 exports.getThumbnailKey = getThumbnailKey;
 exports.getUserOnlyCacheStats = getUserOnlyCacheStats;
+exports.ioAddress = ioAddress;
 exports.isCached = isCached;
 exports.isComponent = isComponent;
 exports.isComputed = isComputed;
@@ -50891,14 +52490,17 @@ exports.isSegment = isSegment;
 exports.isThumbnailCached = isThumbnailCached;
 exports.loadCrossComponentBehaviors = loadCrossComponentBehaviors;
 exports.loadTextureSetAndCreateMaterial = loadTextureSetAndCreateMaterial;
+exports.makeAddress = makeAddress;
 exports.markAsComputed = markAsComputed;
 exports.markAsDeclared = markAsDeclared;
 exports.measureS3Transfer = measureS3Transfer;
 exports.modelOffsetToWorldDelta = modelOffsetToWorldDelta;
 exports.modelPreloader = modelPreloader;
 exports.normalizeBehavior = normalizeBehavior;
+exports.offValue = offValue;
 exports.parseCrossBehavior = parseCrossBehavior;
 exports.parseIntraBehavior = parseIntraBehavior;
+exports.parseIoAddress = parseIoAddress;
 exports.preloadLocalFiles = preloadLocalFiles;
 exports.preloadS3Objects = preloadS3Objects;
 exports.refreshSceneIntraBehaviors = refreshSceneIntraBehaviors;
@@ -50915,3 +52517,4 @@ exports.scanSceneIoEndpoints = scanSceneIoEndpoints;
 exports.sceneViewer = sceneViewer;
 exports.shouldRemoveOnRegeneration = shouldRemoveOnRegeneration;
 exports.switchCachePartition = switchCachePartition;
+exports.valuesEqual = valuesEqual;