simple-circuit-engine 0.0.11 → 0.0.12

package/dist/core/simulation/behaviors/basic/RectangleLEDBehavior.d.ts

@@ -0,0 +1,24 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states';
+import { BipolarLightEmitterBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { UUID } from '../../../utils/types';
+export declare class RectangleLEDBehavior extends BipolarLightEmitterBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a RectangleLED.
+     *
+     * @param component - The smallLED component
+     * @returns LED Initial state (always active and delivering voltage)
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * only symmetrical behavior of LEDS is handled for now
+     * @param component
+     * @param state
+     * @param nodeStates
+     * @param targetTick
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/basic/RelayBehavior.d.ts

@@ -0,0 +1,33 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IScheduledEvent } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+import { ENodeSourceType } from '../../../topology/types';
+/**
+ * Behavior implementation for relays components.
+ *
+ * @public
+ */
+export declare class RelayBehavior extends ComponentBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a relay.
+     *
+     * @param component - The Relay component
+     * @returns Relay Initial state (open by default)
+     */
+    createInitialState(component: Component): ComponentState;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * Relay cmd pins need to have voltage and current so that relay contactor stays closed
+     * @param component
+     * @param state
+     * @param nodeStates
+     * @param targetTick
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/basic/SmallLEDBehavior.d.ts

@@ -0,0 +1,24 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { BipolarLightEmitterBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+export declare class SmallLEDBehavior extends BipolarLightEmitterBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a smallLED.
+     *
+     * @param component - The smallLED component
+     * @returns LED Initial state (always active and delivering voltage)
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * only symmetrical behavior of LEDS is handled for now
+     * @param component
+     * @param state
+     * @param nodeStates
+     * @param targetTick
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/basic/SwitchBehavior.d.ts

@@ -0,0 +1,33 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState, INodeElectricalState } from '../../states';
+import { IScheduledEvent, IUserCommand } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { ENodeSourceType } from '../../../topology/types';
+import { UUID } from '../../../utils';
+/**
+ * Behavior implementation for switches components.
+ *
+ * @public
+ */
+export declare class SwitchBehavior extends ComponentBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a switch.
+     *
+     * @param component - The Switch component
+     * @returns Switch Initial state (open by default)
+     */
+    createInitialState(component: Component): ComponentState;
+    allowConductivity(_component: Component, _state: ComponentState, _conductivityType: ENodeSourceType, _pinId: string, _otherPinId: string): boolean;
+    /**
+     * used for contactor color change
+     * @param component
+     * @param state
+     * @param nodeStates
+     * @param _targetTick
+     */
+    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;
+}

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

@@ -0,0 +1,20 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState.js';
+import { IScheduledEvent } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { ENodeSourceType } from '../../../topology/types';
+import { IBehaviorResult } from '../types';
+/**
+ * to factorize behaviors of bipolar components emitting light (lightbulb/ LEDs even if it's a big simplification...)
+ */
+export declare abstract class BipolarLightEmitterBehaviorMixin extends ComponentBehaviorMixin {
+    protected getBehavior(component: Component, state: ComponentState, activationCondition: boolean, targetTick: number): IBehaviorResult;
+    allowConductivity(_component: Component, _state: ComponentState, _conductivityType: ENodeSourceType, _pinId: string, _otherPinId: string): boolean;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+}
+/**
+ * Get the tick count from command parameters.
+ * @param parameters - Command parameters map
+ * @returns Number of ticks for transition (minimum 1)
+ */
+export declare function getTickCount(parameters: Map<string, string> | null | undefined): number;

package/dist/core/simulation/behaviors/gates/InverterBehavior.d.ts

@@ -0,0 +1,29 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for Inverters components.
+ *
+ * @public
+ */
+export declare class InverterBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a Inverter.
+     *
+     * @param component - The Inverter component
+     * @returns Inverter Initial state (HIGH if input LOW, LOW if input LOW for positive activation logic)
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * Inverter needs LOW on input to drive the output HIGH, and on the contrary Buffer needs HIGH on input to output HIGH
+     * @param component
+     * @param state
+     * @param nodeStates
+     * @param targetTick
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Nand4GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NAND4 Gate components (4 inputs).
+ * With negative (default) activationLogic: NAND gate (output high when ANY input is low).
+ * With positive activationLogic: AND gate (output high when ALL 4 inputs are high).
+ *
+ * @public
+ */
+export declare class Nand4GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Nand8GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NAND8 Gate components (8 inputs).
+ * With negative (default) activationLogic: NAND gate (output high when ANY input is low).
+ * With positive activationLogic: AND gate (output high when ALL 8 inputs are high).
+ *
+ * @public
+ */
+export declare class Nand8GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/NandGateBehavior.d.ts

@@ -0,0 +1,28 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NAND Gate components.
+ * With negative (default) activationLogic: NAND gate (output high when ANY input is low).
+ * With positive activationLogic: AND gate (output high when ALL inputs are high).
+ *
+ * @public
+ */
+export declare class NandGateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for an NAND Gate.
+     *
+     * @param component - The NAND Gate component
+     * @returns Initial state (low by default, high for negative activation logic)
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * NAND gate output goes high when ANY inputs LACK voltage.
+     * With positive activationLogic (AND), output goes high when ALL inputs HAS voltage.
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Nor4GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NOR4 Gate components (4 inputs).
+ * With negative (default) activationLogic: NOR gate (output high when ALL 4 inputs are low).
+ * With positive activationLogic: OR gate (output high when ANY of 4 inputs is high).
+ *
+ * @public
+ */
+export declare class Nor4GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Nor8GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NOR8 Gate components (8 inputs).
+ * With negative (default) activationLogic: NOR gate (output high when ALL 8 inputs are low).
+ * With positive activationLogic: OR gate (output high when ANY of 8 inputs is high).
+ *
+ * @public
+ */
+export declare class Nor8GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/NorGateBehavior.d.ts

@@ -0,0 +1,22 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for NOR Gate components.
+ * With negative (default) activationLogic: NOR gate (output high when ALL inputs are low).
+ * With positive activationLogic: OR gate (output high when ANY input is high).
+ *
+ * @public
+ */
+export declare class NorGateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    /**
+     * NOR gate output goes high when ALL inputs LACK voltage.
+     * With positive activationLogic (OR), output goes high when ANY inputs HAS voltage.
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Xor4GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for XOR4 Gate components (4 inputs).
+ * With positive activationLogic: XOR gate (output high when odd number of inputs are high).
+ * With negative activationLogic: XNOR gate (output high when even number of inputs are high).
+ *
+ * @public
+ */
+export declare class Xor4GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/Xor8GateBehavior.d.ts

@@ -0,0 +1,18 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for XOR8 Gate components (8 inputs).
+ * With positive activationLogic: XOR gate (output high when odd number of inputs are high).
+ * With negative activationLogic: XNOR gate (output high when even number of inputs are high).
+ *
+ * @public
+ */
+export declare class Xor8GateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/gates/XorGateBehavior.d.ts

@@ -0,0 +1,22 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { LogicGateBehaviorMixin } from './index';
+import { IBehaviorResult, IComponentBehavior } from '../types';
+import { INodeElectricalState } from '../../states';
+import { UUID } from '../../../utils/types';
+/**
+ * Behavior implementation for XOR Gate components.
+ * With positive activationLogic: XOR gate (output high when inputs differ / odd parity).
+ * With negative activationLogic: XNOR gate (output high when inputs are equal / even parity).
+ *
+ * @public
+ */
+export declare class XorGateBehavior extends LogicGateBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    /**
+     * XOR gate output goes high when inputs differ (odd parity).
+     * With negative activationLogic (XNOR), output goes high when inputs are equal (even parity).
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+}

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

@@ -0,0 +1,34 @@
+import { ENodeSourceType } from '../../../topology/types';
+import { Component } from '../../../topology/Component';
+import { INodeElectricalState } from '../../states/types';
+import { ComponentState } from '../../states/ComponentState.js';
+import { IScheduledEvent } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { IBehaviorResult } from '../types';
+/**
+ * to factorize default implementations in logic gates behaviors
+ */
+export declare abstract class LogicGateBehaviorMixin extends ComponentBehaviorMixin {
+    /**
+     * default return for all logic gates when vcc fails -> go low immediately
+     * @param state
+     * @param pinStates
+     * @protected
+     */
+    protected vccGuardBehavior(state: ComponentState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * guard scanning all inputs of logic gates to detect if Any has:
+     * - both voltage and ground hence with established flowing current
+     * - neither voltage nor ground
+     * it makes a not well-defined input between LOW and HIGH
+     * in that case gate goes to state indeterminate and output nothing too
+     * @param state
+     * @param pinStates
+     * @param targetTick
+     * @protected
+     */
+    protected nonLogicInputGuardBehavior(state: ComponentState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    protected getBehavior(component: Component, state: ComponentState, activationCondition: boolean, targetTick: number): IBehaviorResult;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+}

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

@@ -0,0 +1,24 @@
+/**
+ * Component behavior implementations
+ * @module core/simulation/behaviors
+ */
+export type { IComponentBehavior, IBehaviorResult } from './types';
+export { BehaviorRegistry } from './BehaviorRegistry.js';
+export { BatteryBehavior } from './basic/BatteryBehavior';
+export { LightbulbBehavior } from './basic/LightbulbBehavior';
+export { RectangleLEDBehavior } from './basic/RectangleLEDBehavior';
+export { RelayBehavior } from './basic/RelayBehavior';
+export { SmallLEDBehavior } from './basic/SmallLEDBehavior';
+export { SwitchBehavior } from './basic/SwitchBehavior';
+export { DoubleThrowSwitchBehavior } from './basic/DoubleThrowSwitchBehavior';
+export { ClockBehavior } from './basic/ClockBehavior';
+export { InverterBehavior } from './gates/InverterBehavior';
+export { NandGateBehavior } from './gates/NandGateBehavior';
+export { Nand4GateBehavior } from './gates/Nand4GateBehavior';
+export { Nand8GateBehavior } from './gates/Nand8GateBehavior';
+export { NorGateBehavior } from './gates/NorGateBehavior';
+export { Nor4GateBehavior } from './gates/Nor4GateBehavior';
+export { Nor8GateBehavior } from './gates/Nor8GateBehavior';
+export { XorGateBehavior } from './gates/XorGateBehavior';
+export { Xor4GateBehavior } from './gates/Xor4GateBehavior';
+export { Xor8GateBehavior } from './gates/Xor8GateBehavior';

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

@@ -0,0 +1,101 @@
+import { UUID } from '../../utils';
+import { ComponentType, ENodeSourceType, Component } from '../../topology';
+import { ComponentState, INodeElectricalState } from '../states';
+import { IScheduledEvent, IUserCommand } from '../types';
+/**
+ * Result returned by component behavior evaluation.
+ * Describes state changes and future events to schedule.
+ *
+ * @public
+ */
+export interface IBehaviorResult {
+    /**
+     * Updated component state
+     */
+    readonly componentState: ComponentState;
+    /**
+     * boolean indicating
+     * if the component state has changed (or events scheduled ?)
+     */
+    hasChanged: boolean;
+    /**
+     * boolean indicating that all pending events on this component should be cancelled
+     * (example change of input during the rising/falling state of a gate)
+     */
+    shouldCancelPending: boolean;
+    /**
+     * Events to schedule for future ticks (e.g., delayed transitions).
+     */
+    readonly scheduledEvents: ReadonlyArray<IScheduledEvent>;
+}
+/**
+ * Component behavior interface for registry-based extensibility.
+ * Each component type (Battery, LED, Switch, etc.) implements this interface.
+ *
+ * Behaviors are stateless - all state is stored in ComponentState and SimulationState.
+ * The behavior's job is to compute new states based on current inputs and component state.
+ *
+ * @public
+ */
+export interface IComponentBehavior {
+    /**
+     * Component type this behavior handles (e.g., "battery", "led", "switch").
+     * Used as the key in BehaviorRegistry.
+     */
+    componentType: ComponentType;
+    /**
+     * Create initial state for a component instance.
+     * Called when simulation is initialized.
+     * Initial state may use component satic configuration (e.g., initial switch position).
+     *
+     * @param component - The component to initialize
+     * @returns Initial ComponentState for this component
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * Determine if conductivity is allowed between two pins of the component.
+     * Called during simulation when evaluating electrical connectivity.
+     * @param component
+     * @param state current component state
+     * @param conductivityType
+     * @param pinId
+     * @param otherPinId
+     */
+    allowConductivity(component: Component, state: ComponentState, conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * Define custom component behavior at simulation start
+     * For most components it's a no-op but some components to bootstrap their cycling
+     * Warning: if this methods return non null behavior it preempts normal initialization at tick 0
+     * @param component
+     * @param componentState
+     */
+    onStart(component: Component, componentState: ComponentState): IBehaviorResult | null;
+    /**
+     * Define component state change in response to its pins state change (after propagateConductivity)
+     *
+     * @param component - The component being evaluated
+     * @param state - component state prior to this evaluation
+     * @param nodeStates - Current electrical states of all ENodes in the simulation
+     * @param targetTick - target tick
+     * @returns Result containing updated state and scheduled events
+     */
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    /**
+     * Define component state change in response to a User command being received
+     *
+     * @param component - The component being evaluated
+     * @param state - component state prior to this evaluation
+     * @param command - IUserCommand to process
+     * @returns Result containing updated state and scheduled events
+     */
+    onUserCommand(component: Component, state: ComponentState, command: IUserCommand): IBehaviorResult;
+    /**
+     * Define component state change in response to a IScheduledEvent firing at ready
+     *
+     * @param component - The component being evaluated
+     * @param state - component state prior to this evaluation
+     * @param event - firing IScheduledEvent to process
+     * @returns Result containing updated state and scheduled events
+     */
+    onEventFiring(component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+}

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

@@ -0,0 +1,18 @@
+/**
+ * Simulation Engine Module
+ *
+ * Provides discrete-time boolean circuit simulation with state propagation,
+ * event scheduling, and component behavior management.
+ *
+ * @module core/simulation
+ * @public
+ */
+export { TRANSITION_DEFAULTS, SIMULATION_SPEED } from './types.js';
+export type { IUserCommand, IRunnerOptions, IScheduledEvent, IDirtyElements } from './types.js';
+export * from './states';
+export * from './behaviors';
+export { EventQueue } from './EventQueue.js';
+export { DirtyTracker } from './DirtyTracker.js';
+export { StateManager } from './StateManager.js';
+export { CircuitRunner } from './CircuitRunner.js';
+export { getTransitionSpan } from './behaviors/ComponentBehavior';

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

@@ -0,0 +1,57 @@
+import { UUID } from '../../utils/types';
+import { INodeElectricalState } from './types';
+/**
+ * Base class for component simulation state.
+ * Extended by specific component types (BatteryState, LEDState, etc.)
+ * One instance per component throughout simulation that will be mutated in place.
+ *
+ * @abstract
+ * @public
+ */
+export declare abstract class ComponentState {
+    /**
+     * Component UUID this state belongs to.
+     * @readonly
+     */
+    readonly componentId: UUID;
+    /**
+     * Current operational state (varies by component type).
+     * Examples: "on", "off", "open", "closed", "activating", "active"
+     */
+    protected _state: string;
+    /**
+     * Tick when this state started.
+     */
+    protected _startTick: number;
+    /**
+     * until when this state should last (-1 for no previsional expiration)
+     */
+    protected _expirationTick: number;
+    /**
+     * previsional nextState (null if current state has no expiration tick)
+     */
+    protected _nextState: string | null;
+    /**
+     * extra state parameters
+     */
+    parameters: Map<string, string>;
+    /**
+     * Pin electrical states, keyed by pin label (e.g. 'cmd_in', 'power_out').
+     * Composite keys use '*' separator for unions (e.g. 'cmd_in*cmd_out').
+     */
+    pinStates: Map<string, INodeElectricalState>;
+    /**
+     * Create a new component state.
+     *
+     * @param componentId - UUID of the component
+     * @param initialState - Initial operational state
+     */
+    protected constructor(componentId: UUID, initialState: string);
+    get state(): string;
+    setState(state: string, startTick: number): void;
+    get startTick(): number;
+    get expirationTick(): number;
+    get nextState(): string | null;
+    get hasExpiration(): boolean;
+    setNextState(nextState: string, expirationTick: number): void;
+}

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

@@ -0,0 +1,46 @@
+import { ComponentState, INodeElectricalState } from './index';
+import { UUID } from '../../utils';
+/**
+ * Represents the complete electrical state of the circuit at a specific time step.
+ * Immutable snapshot that can be stored in history.
+ *
+ * @public
+ */
+export declare class SimulationState {
+    /**
+     * Current simulation step number (starts at 0).
+     * @readonly
+     */
+    tick: number;
+    /**
+     * Electrical state for each ENode (component pins and branching points).
+     * Key: ENode UUID, Value: INodeElectricalState
+     * @readonly
+     */
+    readonly nodeStates: ReadonlyMap<UUID, INodeElectricalState>;
+    /**
+     * Electrical state for each Wire connecting ENodes.
+     * Key: Wire UUID, Value: INodeElectricalState
+     * @readonly
+     */
+    readonly wireStates: ReadonlyMap<UUID, INodeElectricalState>;
+    /**
+     * Component-specific state for each component.
+     * Key: Component UUID, Value: ComponentState subclass
+     * @readonly
+     */
+    readonly componentStates: ReadonlyMap<UUID, ComponentState>;
+    /**
+     * Create a new simulation state snapshot.
+     *
+     * @param tick - Current simulation step number
+     */
+    constructor(tick: number);
+    setTick(tick: number): void;
+    /**
+     * Create a deep copy of this state for historical storage.
+     *
+     * @returns Cloned SimulationState
+     */
+    clone(): SimulationState;
+}