simple-circuit-engine 0.0.13 → 0.0.14

package/AGENTS.md

@@ -35,15 +35,15 @@ registerGatesComponentsFactories(componentsFactoryRegistry); //... other groups
 const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
 registerGatesComponentsBehaviors(behaviorRegistry); //... other groupsof components  if needed
 
+// Rendering (must exist before engine.initialize — it binds MapControls to the canvas)
+const renderer = new WebGLRenderer();
+
 // Instanciate and Initialize CircuitEngine (it creates and uses a new Circuit by default)
 const engine = new CircuitEngine(componentsFactoryRegistry, behaviorRegistry);
 const container = document.getElementById('canvas-container')!;
-engine.initialize(container, engineOptions());
+engine.initialize(container, renderer, engineOptions());
 // set engine circuit to a new empty circuit
 engine.setCircuit(new Circuit(new CircuitOptions()));
-
-// Rendering
-const renderer = new WebGLRenderer();
 const width = window.innerWidth,
   height = window.innerHeight;
 renderer.setSize(container.clientWidth, container.clientHeight);
@@ -121,8 +121,10 @@ animate();
 ### Initialize Engine
 
 ```typescript
+const renderer = new WebGLRenderer();
 const engine = new CircuitEngine(factoryRegistry, behaviorRegistry);
-engine.initialize(container, engineOptions());
+engine.initialize(container, renderer, engineOptions());
+container.appendChild(renderer.domElement);
 engine.setCircuit(new Circuit());
 
 // Add Component Programmatically

package/README.md

@@ -44,21 +44,21 @@ const componentsFactoryRegistry = registerBasicComponentsFactories(new GroupedFa
 // Create behavior registry with basic components behaviors (for simulation)
 const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
 
+// Create and setup WebGL renderer (must exist before engine.initialize — it binds MapControls to the canvas)
+const renderer = new WebGLRenderer({ antialias: true, alpha: false });
+renderer.setClearColor(0x1a1a2e);
+const container = document.getElementById('canva-container')!;
+renderer.setSize(container.clientWidth, container.clientHeight);
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+
 // Initialize CircuitEngine
 // It creates THREE.js scene, camera, controls, lights, etc
 // and the interactive controllers (edit and simulation) of simple-circuit-engine
-const container = document.getElementById('canva-container')!;
 const engine = new CircuitEngine(componentsFactoryRegistry, behaviorRegistry);
-engine.initialize(container, engineOptions());
+engine.initialize(container, renderer, engineOptions());
 // set engine circuit to a new empty circuit
 engine.setCircuit(new Circuit(new CircuitOptions()));
 
-// Create and setup WebGL renderer
-const renderer = new WebGLRenderer({ antialias: true, alpha: false });
-renderer.setClearColor(0x1a1a2e);
-const width = window.innerWidth, height = window.innerHeight;
-renderer.setSize(container.clientWidth, container.clientHeight);
-renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
 // Append renderer to DOM
 container.appendChild(renderer.domElement);
 

package/dist/core/index.js

@@ -1,87 +1,112 @@
-import { $ as t, A as e, At as s, B as i, C as o, Ct as r, D as n, Dt as S, E as h, Et as B, F as v, G as d, H as l, I as E, J as m, K as c, L as G, M as p, N as C, O as N, Ot as A, P as T, Q as g, R as u, S as I, St as L, T as D, Tt as y, U as O, V as _, W as R, X as M, Y as b, Z as f, _ as w, _t as P, a as U, at as X, b as F, bt as k, c as x, ct as z, d as H, dt as Y, et as Q, f as V, ft as W, g as j, gt as q, h as J, ht as K, i as Z, it as $, j as aa, k as ta, kt as ea, l as sa, lt as ia, m as oa, mt as ra, n as na, nt as Sa, o as ha, ot as Ba, p as va, pt as da, q as la, r as Ea, rt as ma, s as ca, st as Ga, t as pa, tt as Ca, u as Na, ut as Aa, v as Ta, vt as ga, w as ua, wt as Ia, x as La, xt as Da, y as ya, yt as Oa, z as _a } from "../core-b6Q8w2sn.js";
+import { $ as a, $t as e, A as s, At as i, B as o, Bt as r, C as n, Ct as h, D as S, Dt as B, E as v, Et as p, F as g, Ft as u, G as c, Gt as d, H as E, Ht as I, I as L, It as l, J as m, Jt as G, K as T, Kt as C, L as N, Lt as A, M as D, Mt as O, N as y, Nt as R, O as f, Ot as F, P as M, Pt as P, Q as w, Qt as _, R as b, Rt as U, S as X, St as x, T as k, Tt as W, U as z, Ut as H, V as Y, Vt as Q, W as V, Wt as j, X as q, Xt as J, Y as K, Yt as Z, Z as $, Zt as tt, _ as at, _t as et, a as st, at as it, b as ot, bt as rt, c as nt, ct as ht, d as St, dt as Bt, en as vt, et as pt, f as gt, ft as ut, g as ct, gt as dt, h as Et, ht as It, i as Lt, it as lt, j as mt, jt as Gt, k as Tt, kt as Ct, l as Nt, lt as At, m as Dt, mt as Ot, n as yt, nt as Rt, o as ft, ot as Ft, p as Mt, pt as Pt, q as wt, qt as _t, r as bt, rt as Ut, s as Xt, st as xt, t as kt, tn as Wt, tt as zt, u as Ht, ut as Yt, v as Qt, vt as Vt, w as jt, wt as qt, x as Jt, xt as Kt, y as Zt, yt as $t, z as ta, zt as aa } from "../core-HH6iRWtB.js";
 export {
-  K as ALL_LOGIC_FAMILIES,
-  Na as AdderBehavior,
-  T as AdderState,
-  E as ArithmeticState,
-  ta as BatteryBehavior,
-  Q as BatteryState,
-  aa as BehaviorRegistry,
-  q as CIRCUIT_FILE_VERSION,
-  P as COMPONENT_TYPE_METADATA,
-  S as CameraOptions,
-  Ba as Circuit,
-  Aa as CircuitMetadata,
-  Y as CircuitOptions,
-  Z as CircuitRunner,
-  I as ClockBehavior,
-  la as ClockState,
-  W as Component,
-  Ca as ComponentState,
-  ga as ComponentType,
-  Oa as DEFAULT_LOGIC_FAMILY,
-  ha as DirtyTracker,
-  o as DoubleThrowSwitchBehavior,
-  m as DoubleThrowSwitchState,
-  ra as ENode,
-  k as ENodeSourceType,
-  Da as ENodeType,
-  sa as EightBitAdderBehavior,
-  C as EightBitAdderState,
-  x as EightBitOnesComplementBehavior,
-  p as EightBitOnesComplementState,
-  ca as EventQueue,
-  H as HalfAdderBehavior,
-  v as HalfAdderState,
-  La as InverterBehavior,
-  c as InverterState,
-  N as LightbulbBehavior,
-  t as LightbulbState,
-  ea as Memoize,
-  s as MemoizeExpiring,
-  ya as Nand4GateBehavior,
-  R as Nand4GateState,
-  Ta as Nand8GateBehavior,
-  O as Nand8GateState,
-  F as NandGateBehavior,
-  d as NandGateState,
-  j as Nor4GateBehavior,
-  _ as Nor4GateState,
-  J as Nor8GateBehavior,
-  i as Nor8GateState,
-  w as NorGateBehavior,
-  l as NorGateState,
-  Ia as Position,
-  A as Position3D,
-  n as RectangleLEDBehavior,
-  f as RectangleLEDState,
-  h as RelayBehavior,
-  M as RelayState,
-  r as Rotation,
-  $ as SIMULATION_SPEED,
-  Sa as SimulationState,
-  D as SmallLEDBehavior,
-  g as SmallLEDState,
-  U as StateManager,
-  ua as SwitchBehavior,
-  b as SwitchState,
-  X as TRANSITION_DEFAULTS,
-  da as Wire,
-  va as Xor4GateBehavior,
-  u as Xor4GateState,
-  V as Xor8GateBehavior,
-  G as Xor8GateState,
-  oa as XorGateBehavior,
-  _a as XorGateState,
-  Ga as classifyGate,
-  z as computeGateDelay,
-  ia as computeTransitionSpan,
-  y as findPositionBestIndex,
-  L as generateUUID,
-  e as getTransitionSpan,
-  pa as registerArithmeticComponentsBehaviors,
-  na as registerBasicComponentsBehaviors,
-  Ea as registerGatesComponentsBehaviors,
-  B as simplifyPositions,
-  ma as unionElectricalStates
+  r as ALL_LOGIC_FAMILIES,
+  Jt as AdderBehavior,
+  zt as AdderState,
+  Ut as ArithmeticState,
+  o as BatteryBehavior,
+  Kt as BatteryState,
+  E as BehaviorRegistry,
+  Q as CIRCUIT_FILE_VERSION,
+  I as COMPONENT_TYPE_METADATA,
+  _ as CameraOptions,
+  Gt as Circuit,
+  u as CircuitMetadata,
+  l as CircuitOptions,
+  st as CircuitRunner,
+  y as ClockBehavior,
+  Ot as ClockState,
+  A as Component,
+  x as ComponentState,
+  H as ComponentType,
+  j as DEFAULT_LOGIC_FAMILY,
+  Xt as DirtyTracker,
+  M as DoubleThrowSwitchBehavior,
+  It as DoubleThrowSwitchState,
+  aa as ENode,
+  d as ENodeSourceType,
+  C as ENodeType,
+  ot as EightBitAdderBehavior,
+  pt as EightBitAdderState,
+  Zt as EightBitOnesComplementBehavior,
+  a as EightBitOnesComplementState,
+  Dt as EightInputBehavior,
+  m as EightInputState,
+  Nt as EightLightBehavior,
+  z as EightLightState,
+  nt as EventQueue,
+  Et as FourInputBehavior,
+  K as FourInputState,
+  Ht as FourLightBehavior,
+  V as FourLightState,
+  X as HalfAdderBehavior,
+  Rt as HalfAdderState,
+  Qt as InputBehaviorMixin,
+  w as InputState,
+  D as InverterBehavior,
+  Pt as InverterState,
+  Mt as LightBehaviorMixin,
+  wt as LightState,
+  ta as LightbulbBehavior,
+  rt as LightbulbState,
+  vt as Memoize,
+  Wt as MemoizeExpiring,
+  s as Nand4GateBehavior,
+  Bt as Nand4GateState,
+  Tt as Nand8GateBehavior,
+  Yt as Nand8GateState,
+  mt as NandGateBehavior,
+  ut as NandGateState,
+  S as Nor4GateBehavior,
+  ht as Nor4GateState,
+  v as Nor8GateBehavior,
+  xt as Nor8GateState,
+  f as NorGateBehavior,
+  At as NorGateState,
+  at as OneInputBehavior,
+  $ as OneInputState,
+  gt as OneLightBehavior,
+  T as OneLightState,
+  Z as Position,
+  e as Position3D,
+  b as RectangleLEDBehavior,
+  Vt as RectangleLEDState,
+  N as RelayBehavior,
+  et as RelayState,
+  G as Rotation,
+  W as SIMULATION_SPEED,
+  h as SimulationState,
+  L as SmallLEDBehavior,
+  $t as SmallLEDState,
+  ft as StateManager,
+  g as SwitchBehavior,
+  dt as SwitchState,
+  p as TRANSITION_DEFAULTS,
+  ct as TwoInputBehavior,
+  q as TwoInputState,
+  St as TwoLightBehavior,
+  c as TwoLightState,
+  U as Wire,
+  jt as Xor4GateBehavior,
+  it as Xor4GateState,
+  n as Xor8GateBehavior,
+  lt as Xor8GateState,
+  k as XorGateBehavior,
+  Ft as XorGateState,
+  O as classifyGate,
+  R as computeGateDelay,
+  P as computeTransitionSpan,
+  B as findBpsAtLogicDistance,
+  F as findBpsAtLogicDistanceWithPath,
+  Ct as findPinsReachableFromBp,
+  i as findPinsReachableFromBpWithPath,
+  J as findPositionBestIndex,
+  _t as generateUUID,
+  Y as getTransitionSpan,
+  kt as registerArithmeticComponentsBehaviors,
+  yt as registerBasicComponentsBehaviors,
+  bt as registerGatesComponentsBehaviors,
+  Lt as registerInterfaceComponentsBehaviors,
+  tt as simplifyPositions,
+  qt as unionElectricalStates
 };

package/dist/core/setup.d.ts

@@ -23,3 +23,13 @@ export declare function registerGatesComponentsBehaviors(registry: BehaviorRegis
  * @return the input behavior registry for chaining
  */
 export declare function registerArithmeticComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;
+/**
+ * Register all interface component behaviors in the given registry.
+ * Interface components are:
+ *  - inputs: OneInput, TwoInput, FourInput, EightInput
+ *  - lights: OneLight, TwoLight, FourLight, EightLight
+ * @public
+ * @param registry
+ * @return the input behavior registry for chaining
+ */
+export declare function registerInterfaceComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;

package/dist/core/simulation/behaviors/index.d.ts

@@ -26,3 +26,13 @@ export { HalfAdderBehavior } from './arithmetic/HalfAdderBehavior';
 export { AdderBehavior } from './arithmetic/AdderBehavior';
 export { EightBitAdderBehavior } from './arithmetic/EightBitAdderBehavior';
 export { EightBitOnesComplementBehavior } from './arithmetic/EightBitOnesComplementBehavior';
+export { InputBehaviorMixin } from './interface/InputBehaviorMixin';
+export { OneInputBehavior } from './interface/OneInputBehavior';
+export { TwoInputBehavior } from './interface/TwoInputBehavior';
+export { FourInputBehavior } from './interface/FourInputBehavior';
+export { EightInputBehavior } from './interface/EightInputBehavior';
+export { LightBehaviorMixin } from './interface/LightBehaviorMixin';
+export { OneLightBehavior } from './interface/OneLightBehavior';
+export { TwoLightBehavior } from './interface/TwoLightBehavior';
+export { FourLightBehavior } from './interface/FourLightBehavior';
+export { EightLightBehavior } from './interface/EightLightBehavior';

package/dist/core/simulation/behaviors/interface/EightInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Eight-switch user input. See {@link InputBehaviorMixin}. */
+export declare class EightInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/EightLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Eight-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class EightLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/FourInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Four-switch user input. See {@link InputBehaviorMixin}. */
+export declare class FourInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/FourLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Four-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class FourLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/InputBehaviorMixin.d.ts

@@ -0,0 +1,37 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+import { ENodeSourceType } from '../../../topology/types';
+import { IScheduledEvent, IUserCommand } from '../../types';
+import { IBehaviorResult } from '../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+/**
+ * Factorises the plumbing shared by `OneInput`, `TwoInput`, `FourInput` and
+ * `EightInput` behaviors.
+ *
+ * These components only react to user actions (`toggle_input` commands) — they
+ * have no logic inputs. The state encodes the current outputs as a hex value
+ * (e.g. `'5'` = `0101` for FourInput); while at least one switch is moving the
+ * state literal is `'moving'` and a parameter map tracks each pending switch
+ * (`${index}` → `${target}-${startTick}-${endTick}`) plus the actual driving
+ * value in `prevState`.
+ *
+ * Concurrency model:
+ * - Toggling a different switch while another is still moving simply adds a
+ *   new pending entry — both transitions resolve independently. No
+ *   `shouldCancelPending`.
+ * - Toggling the *same* switch a second time is debounced (the second command
+ *   is silently ignored).
+ * - Vcc loss collapses the state to `allLowState` and clears all pending
+ *   transitions.
+ *
+ * @public
+ */
+export declare abstract class InputBehaviorMixin extends ComponentBehaviorMixin {
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onUserCommand(component: Component, state: ComponentState, command: IUserCommand): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    protected noChange(state: ComponentState): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/interface/LightBehaviorMixin.d.ts

@@ -0,0 +1,60 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+import { ENodeSourceType } from '../../../topology/types';
+import { IScheduledEvent } from '../../types';
+import { IBehaviorResult } from '../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { LightState } from '../../states/interface/LightState';
+/**
+ * Factorises the plumbing shared by `OneLight`, `TwoLight`, `FourLight` and
+ * `EightLight` behaviors.
+ *
+ * These components mirror their `input-i` pins onto matching `output-i` pins
+ * with a per-light `transitionSpan` delay. The state encodes the current
+ * outputs as a hex value (e.g. `'5'` = `0101` for FourLight); while at least
+ * one light is moving the state literal is `'moving'` and a parameter map
+ * tracks each pending light (`${index}` → `${target}-${startTick}-${endTick}`)
+ * plus the actual driving value in `prevState`.
+ *
+ * Guards (run first in `onPinsChange`):
+ * - Vcc loss collapses the state to `allLowState` and clears all pending.
+ * - Any ill-defined logic input switches the state to `'indeterminate'`.
+ *
+ * Concurrency model (per-light, independent transitions):
+ * - When an input changes, the target output bit is recomputed; if it differs
+ *   from the currently-driving (or already-pending) target a `lightChanged`
+ *   event is scheduled with a per-light span.
+ * - If the same input toggles while its light is still moving, the symmetric
+ *   transition pattern shortens the new span to `Math.max(prevEnd - prevStart, 1)`
+ *   and the in-flight event becomes a no-op (its readyAtTick no longer matches
+ *   the pending entry).
+ * - `shouldCancelPending: false` outside guards — other lights' transitions
+ *   keep their schedule.
+ *
+ * @public
+ */
+export declare abstract class LightBehaviorMixin extends ComponentBehaviorMixin {
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * On vcc loss: drop all outputs low immediately and clear any pending
+     * transitions. Returns `null` when vcc is present so callers can proceed.
+     */
+    protected vccGuardBehavior(state: LightState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * Scan all logic inputs; if any is ill-defined (both voltage and ground, or
+     * neither), switch to `'indeterminate'` immediately and clear any pending
+     * transitions. Otherwise returns `null` so the caller can proceed.
+     */
+    protected nonLogicInputGuardBehavior(state: LightState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * For each logic input, compute the desired output bit and schedule a
+     * per-light `lightChanged` event whenever that bit differs from the current
+     * effective (or already-pending) target.
+     */
+    protected scheduleInputTransitions(component: Component, state: LightState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    protected noChange(state: ComponentState): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/interface/OneInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Single-switch user input. See {@link InputBehaviorMixin}. */
+export declare class OneInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/OneLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Single-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class OneLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/TwoInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Two-switch user input. See {@link InputBehaviorMixin}. */
+export declare class TwoInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/TwoLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Two-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class TwoLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/states/index.d.ts

@@ -29,3 +29,13 @@ export { HalfAdderState } from './arithmetic/HalfAdderState';
 export { AdderState } from './arithmetic/AdderState';
 export { EightBitAdderState } from './arithmetic/EightBitAdderState';
 export { EightBitOnesComplementState } from './arithmetic/EightBitOnesComplementState';
+export { InputState } from './interface/InputState';
+export { OneInputState } from './interface/OneInputState';
+export { TwoInputState } from './interface/TwoInputState';
+export { FourInputState } from './interface/FourInputState';
+export { EightInputState } from './interface/EightInputState';
+export { LightState } from './interface/LightState';
+export { OneLightState } from './interface/OneLightState';
+export { TwoLightState } from './interface/TwoLightState';
+export { FourLightState } from './interface/FourLightState';
+export { EightLightState } from './interface/EightLightState';

package/dist/core/simulation/states/interface/EightInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Eight-switch user input. Stable states `'00'`..`'ff'`. */
+export declare class EightInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/EightLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Eight-light input mirror. Stable states `'00'`–`'ff'`. */
+export declare class EightLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/FourInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Four-switch user input. Stable states `'0'`..`'f'`. */
+export declare class FourInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/FourLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Four-light input mirror. Stable states `'0'`–`'f'`. */
+export declare class FourLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/InputState.d.ts

@@ -0,0 +1,45 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for user-controlled input components (OneInput,
+ * TwoInput, FourInput, EightInput).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output (bit `i` ↔ `output-i`).
+ *
+ * While at least one switch is moving, the state value is the literal
+ * `'moving'` and the `parameters` map carries:
+ * - `prevState`: the stable hex value the outputs are still energizing
+ * - one entry per pending switch keyed by its index, encoded as
+ *   `${target}-${startTick}-${endTick}` (target ∈ {0,1}).
+ *
+ * @public
+ */
+export declare abstract class InputState extends ComponentState {
+    /** Number of logic outputs (1, 2, 4 or 8). */
+    readonly outputCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 1–4 outputs, `'00'` for 8). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, outputCount: number, initialState: string);
+    /** True while at least one switch is mid-transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable state → returns that state
+     * - `'moving'` → returns the previous stable kept in `parameters.prevState`
+     */
+    get effectiveState(): string;
+    /** Whether output `index` is high in the current effective state. */
+    isOutputHigh(index: number): boolean;
+    /**
+     * Pending move descriptor for switch `index`, parsed from the parameter map,
+     * or `null` when no transition is in flight for that switch.
+     */
+    getPendingMove(index: number): {
+        target: 0 | 1;
+        startTick: number;
+        endTick: number;
+    } | null;
+}

package/dist/core/simulation/states/interface/LightState.d.ts

@@ -0,0 +1,54 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for input-driven multi-light components (OneLight,
+ * TwoLight, FourLight, EightLight).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output (bit `i` ↔ `output-i`). Outputs
+ * mirror their corresponding `input-i` after `transitionSpan` ticks so the
+ * component can be cascaded.
+ *
+ * While at least one light is moving, the state value is the literal
+ * `'moving'` and the `parameters` map carries:
+ * - `prevState`: the stable hex value the outputs are still energizing
+ * - one entry per pending light keyed by its index, encoded as
+ *   `${target}-${startTick}-${endTick}` (target ∈ {0,1}).
+ *
+ * A special `'indeterminate'` state is used when any logic input is
+ * ill-defined (set immediately by the non-logic-input guard).
+ *
+ * @public
+ */
+export declare abstract class LightState extends ComponentState {
+    /** Number of lights / logic outputs (1, 2, 4 or 8). */
+    readonly lightCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 1–4 lights, `'00'` for 8). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, lightCount: number, initialState: string);
+    /** True while at least one light is mid-transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable hex state → returns that state
+     * - `'moving'` → returns the previous stable kept in `parameters.prevState`
+     * - `'indeterminate'` → returns `'indeterminate'`
+     */
+    get effectiveState(): string;
+    /**
+     * Whether output `index` is high in the current effective state.
+     * Returns `false` when effective state is `'indeterminate'`.
+     */
+    isOutputHigh(index: number): boolean;
+    /**
+     * Pending move descriptor for light `index`, parsed from the parameter map,
+     * or `null` when no transition is in flight for that light.
+     */
+    getPendingMove(index: number): {
+        target: 0 | 1;
+        startTick: number;
+        endTick: number;
+    } | null;
+}

package/dist/core/simulation/states/interface/OneInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Single-switch user input. Stable states `'0'` and `'1'`. */
+export declare class OneInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}