@2112-lab/central-plant 0.3.58 → 0.3.59

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 };

package/dist/index.d.ts

@@ -5,6 +5,91 @@
  * organized by their functional categories.
  */
 
+// ─── State Engine ─────────────────────────────────────────────────────────────
+
+export function makeAddress(scope: string, attribute: string): string
+export function valuesEqual(a: unknown, b: unknown): boolean
+export function offValue(desired: unknown): unknown
+
+export interface StateChange {
+  address: string
+  desired: unknown
+  effective: unknown
+}
+
+/** One endpoint of a declared chain (scope + attribute). */
+export interface ChainEndpoint {
+  /** Object/scope id, e.g. "pump-001" or "pump-001::start-switch". */
+  address: string
+  /** Attribute name, e.g. "power", "mode", "flow". */
+  attribute: string
+}
+
+/** The chain trigger; `source` selects which layer of the trigger to read. */
+export interface ChainWhen extends ChainEndpoint {
+  /** Read the trigger's desired (default) or effective value. */
+  source?: 'desired' | 'effective'
+}
+
+/** A declared chain: when the trigger changes, copy its value to the target. */
+export interface Chain {
+  /** Unique id within the scene. */
+  id?: string
+  /** Only 'copy' is supported today. */
+  action?: 'copy'
+  when: ChainWhen
+  set: ChainEndpoint
+}
+
+export interface StateEngineOptions {
+  /** Ripple hop limit per initiating change (Framework §11.2). Default 8. */
+  maxChainDepth?: number
+  /** Operational attributes gated to a safe-off value when power is off (§6/§10). */
+  gatedOperationalAttributes?: string[]
+}
+
+export declare class StateEngine {
+  constructor(options?: StateEngineOptions)
+  maxChainDepth: number
+  load(declaration?: Record<string, unknown>): void
+  reset(): void
+  getDesired(address: string): unknown
+  getEffective(address: string): unknown
+  getGroupsForObject(objectId: string): string[]
+  setDesired(address: string, value: unknown): boolean
+  /** Register a pipe/path so its `<pipeId>::flow` state exists (tied to lifecycle). */
+  registerPipe(pipeId: string, options?: { defaultFlow?: boolean }): string
+  /** Remove a pipe and all of its registry keys; returns the number removed. */
+  unregisterPipe(pipeId: string): number
+  subscribe(listener: (change: StateChange) => void): () => void
+  toRegistry(): Record<string, unknown>
+  /** Reconstruct the §17 scene declaration (round-trips with load). */
+  toDeclaration(): {
+    version: string
+    plant: Record<string, unknown>
+    groups: Record<string, unknown>
+    chains: Chain[]
+    stateRegistry: Record<string, unknown>
+  }
+}
+
+// ─── State Engine ⇄ scene glue (stateEngineScene.js) ────────────────────────
+
+export function ioAddress(attachmentId: string, stateId: string, parentUuid?: string): string
+export function parseIoAddress(
+  address: string
+): { parentUuid: string; attachmentId: string; stateId: string; scopedKey: string } | null
+export function extractDeclaration(sceneData?: Record<string, unknown>): {
+  plant: Record<string, unknown>
+  groups: Record<string, unknown>
+  chains: Chain[]
+  stateRegistry: Record<string, unknown>
+}
+export function applyDeclarationToExport<T extends Record<string, unknown>>(
+  exportData: T,
+  engine: { toDeclaration: () => Record<string, unknown> }
+): T
+
 // ─── Connector flow types ─────────────────────────────────────────────────────
 
 /** The flow direction of a connector port. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@2112-lab/central-plant",
-  "version": "0.3.58",
+  "version": "0.3.59",
   "description": "Utility modules for the Central Plant Application",
   "main": "dist/bundle/index.js",
   "module": "dist/esm/src/index.js",
@@ -18,6 +18,8 @@
     "build": "rollup -c && npm run build:types",
     "build:types": "node -e \"require('fs').copyFileSync('src/index.d.ts', 'dist/index.d.ts')\"",
     "dev": "rollup -c -w",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build",
     "docs": "jsdoc -c jsdoc.json",
     "release": "npm install @2112-lab/pathfinder@latest && npm version patch && npm publish"
@@ -46,6 +48,7 @@
     "regenerator-runtime": "^0.14.1",
     "rollup": "^2.79.1",
     "rollup-plugin-copy": "^3.5.0",
-    "rollup-plugin-terser": "^7.0.2"
+    "rollup-plugin-terser": "^7.0.2",
+    "vitest": "^2.1.9"
   }
 }