@2112-lab/central-plant 0.3.57 → 0.3.59

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.57",
+  "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"
   }
 }