simple-circuit-engine 0.0.11 → 0.0.13

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

package/dist/core/simulation/states/arithmetic/AdderState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for Full Adder components.
+ *
+ * Hex-encoded stable states: `'0'` (both low), `'1'` (sum high),
+ * `'2'` (carry high), `'3'` (both high). All four are reachable;
+ * in particular `A = B = carryIn = 1` yields `'3'`.
+ *
+ * @public
+ */
+export declare class AdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    get sumHigh(): boolean;
+    get carryOutHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/ArithmeticState.d.ts

@@ -0,0 +1,53 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for arithmetic components (half adder, full adder and
+ * future multi-bit adders, multiplexers, ...).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output. Simple components use one bit per
+ * output in declaration order (bit 0 = first logicOutput). For example a
+ * half-adder with sum (bit 0) and carry (bit 1) uses `'0'`..`'3'`.
+ *
+ * Components with internal carry chains (e.g. 8-bit ripple adder) use an
+ * **interleaved** encoding `CiSi` where sum occupies even bits (`2*i`) and
+ * carry occupies odd bits (`2*i + 1`). This stores intermediate carries for
+ * ripple animation, giving `outputCount = 2 * stageCount` (e.g. 16 bits /
+ * 4 hex digits for 8 stages, states `'0000'`..`'ffff'`).
+ *
+ * Transient (in-flight) states follow the `to${nextState}` convention so
+ * animations can be driven generically from `state`/`nextState`. The
+ * previously-held stable state is preserved in `parameters.prevState` so the
+ * behavior's `allowConductivity` keeps the old outputs energized until the
+ * transition fires.
+ *
+ * A special `'indeterminate'` state is used when any logic input is ill-defined.
+ *
+ * @public
+ */
+export declare abstract class ArithmeticState extends ComponentState {
+    /**
+     * Number of logic outputs for this state
+     * (e.g. 2 for half/full adder, 9 for an 8-bit adder: 8 sum bits + carry out).
+     */
+    readonly outputCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 2 outputs, `'000'` for 9). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, outputCount: number, initialState: string);
+    /** True when the current state is a transient `to${stable}` transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable state → returns that state
+     * - transient `to<hex>` → returns the previous stable kept in parameters
+     * - `'indeterminate'` → returns `'indeterminate'`
+     */
+    get effectiveState(): string;
+    /**
+     * Whether the `index`-th output is high in the current effective state.
+     * Returns `false` when effective state is `'indeterminate'`.
+     */
+    isOutputHigh(index: number): boolean;
+}

package/dist/core/simulation/states/arithmetic/EightBitAdderState.d.ts

@@ -0,0 +1,25 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for the 8-bit ripple carry adder.
+ *
+ * Uses an interleaved 16-bit encoding `C7S7 C6S6 … C1S1 C0S0` where each
+ * stage occupies two bits: sum at even position (`2*i`) and carry at odd
+ * position (`2*i + 1`). This stores intermediate carries so the ripple
+ * animation can show carry propagation stage by stage.
+ *
+ * Stable states range from `'0000'` (all low) to `'ffff'` (all high).
+ * The external outputs are `sum-0`..`sum-7` (bits 0,2,4,…,14) and
+ * `carryOut` (bit 15 = C7).
+ *
+ * @public
+ */
+export declare class EightBitAdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    /** Whether stage `i`'s sum output is high in the current effective state. */
+    isSumHigh(stageIndex: number): boolean;
+    /** Whether stage `i`'s internal carry is high in the current effective state. */
+    isStageCarryHigh(stageIndex: number): boolean;
+    /** Whether the final carry out (C7) is high — drives the `carryOut` pin. */
+    isCarryOutHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/EightBitOnesComplementState.d.ts

@@ -0,0 +1,18 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for the 8-bit one's complement (8 parallel XOR gates).
+ *
+ * Uses a 9-bit encoding stored as a 3-digit hex string (`'000'`..`'1ff'`):
+ * - Bits 0–7: output values (`output-i = input-i XOR invert`)
+ * - Bit 8: current invert input value (stored for animation)
+ *
+ * @public
+ */
+export declare class EightBitOnesComplementState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    /** Whether output bit `index` (0–7) is high in the current effective state. */
+    isOutputBitHigh(index: number): boolean;
+    /** Whether the invert flag (bit 8) is high in the current effective state. */
+    isInvertHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/HalfAdderState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for Half Adder components.
+ *
+ * Hex-encoded stable states: `'0'` (both low), `'1'` (sum high),
+ * `'2'` (carry high). `'3'` is unreachable because `sum = A XOR B`
+ * and `carry = A AND B` can never both be true.
+ *
+ * @public
+ */
+export declare class HalfAdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    get sumHigh(): boolean;
+    get carryHigh(): boolean;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Arithmetic components simulation states
+ * @module core/simulation/states
+ */
+export { ArithmeticState } from './ArithmeticState';
+export { HalfAdderState } from './HalfAdderState';
+export { AdderState } from './AdderState';

package/dist/core/simulation/states/basic/BatteryState.d.ts

@@ -0,0 +1,16 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Battery components.
+ * Batteries are stateless always-on pinSources.
+ *
+ * @public
+ */
+export declare class BatteryState extends ComponentState {
+    /**
+     * Create a new battery state.
+     *
+     * @param componentId - UUID of the battery component
+     */
+    constructor(componentId: UUID);
+}

package/dist/core/simulation/states/basic/ClockState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils';
+import { ComponentState } from '../ComponentState';
+/**
+ * Simulation state for Clock components.
+ * Clock output either voltage (LOGIC HIGH) or LOGIC LOW switching periodically
+ *
+ * @public
+ */
+export declare class ClockState extends ComponentState {
+    /**
+     * Create a new Clock state, either gnd or vcc
+     *
+     * @param componentId - UUID of the Clock component
+     */
+    constructor(componentId: UUID);
+}

package/dist/core/simulation/states/basic/DoubleThrowSwitchState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for DoubleSwitch (SPDT - Single-Pole Double-Throw - switch) components.
+ * These switches can be "input1", "1to2", "input2" or "2to1"
+ *
+ * @public
+ */
+export declare class DoubleThrowSwitchState extends ComponentState {
+    /**
+     * Create a new double Switch state.
+     *
+     * @param componentId - UUID of the double Switch component
+     * @param initialState - Initial operational state (default: "input1")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if switch is in 1to2 or 2to1 state
+     */
+    get isInTransition(): boolean;
+}

package/dist/core/simulation/states/basic/LightbulbState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Lightbulb components.
+ * Lightbulbs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class LightbulbState extends ComponentState {
+    /**
+     * Create a new Lightbulb state.
+     *
+     * @param componentId - UUID of the Lightbulb component
+     * @param initialState - Initial operational state (default: "off")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if Lightbulb is in lit state (on or going_on)
+     */
+    get isLit(): boolean;
+}

package/dist/core/simulation/states/basic/RectangleLEDState.d.ts

@@ -0,0 +1,9 @@
+import { SmallLEDState } from './SmallLEDState';
+/**
+ * Simulation state for RectangleLED components. Same as SmallLEDState.
+ * LEDs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class RectangleLEDState extends SmallLEDState {
+}

package/dist/core/simulation/states/basic/RelayState.d.ts

@@ -0,0 +1,25 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for mechanical Relay components.
+ * Relays can be "open", "closing", "closed", or "opening".
+ *
+ * @public
+ */
+export declare class RelayState extends ComponentState {
+    /**
+     * Create a new Relay state.
+     *
+     * @param componentId - UUID of the Relay component
+     * @param initialState - Initial operational state (default: "open")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if relay is in opening or closing state
+     */
+    get isInTransition(): boolean;
+    /**
+     * Check if relay is in closed or closing state
+     */
+    get isClosed(): boolean;
+}

package/dist/core/simulation/states/basic/SmallLEDState.d.ts

@@ -0,0 +1,21 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for SmallLED components.
+ * LEDs can be "on" (emitting light) or "off".
+ *
+ * @public
+ */
+export declare class SmallLEDState extends ComponentState {
+    /**
+     * Create a new SmallLED state.
+     *
+     * @param componentId - UUID of the LED component
+     * @param initialState - Initial operational state (default: "off")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if LED is in lit state (on or going_on)
+     */
+    get isLit(): boolean;
+}

package/dist/core/simulation/states/basic/SwitchState.d.ts

@@ -0,0 +1,25 @@
+import { ComponentState } from '../ComponentState';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Switch components.
+ * Switches can be "open", "closing", "closed", or "opening".
+ *
+ * @public
+ */
+export declare class SwitchState extends ComponentState {
+    /**
+     * Create a new Switch state.
+     *
+     * @param componentId - UUID of the Switch component
+     * @param initialState - Initial operational state (default: "open")
+     */
+    constructor(componentId: UUID, initialState?: string);
+    /**
+     * Check if switch is in opening or closing state
+     */
+    get isInTransition(): boolean;
+    /**
+     * Check if switch is in closed or closing state
+     */
+    get isClosed(): boolean;
+}

package/dist/core/simulation/states/gates/InverterState.d.ts

@@ -0,0 +1,17 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for Inverter components
+ * Inverters can be "low", "rising", "high", or "falling".
+ *
+ * @public
+ */
+export declare class InverterState extends LogicGateState {
+    /**
+     * Create a new Inverter state.
+     *
+     * @param componentId - UUID of the Inverter component
+     * @param initialState - Initial operational state (default: "low")
+     */
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Nand4GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Nand4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Nand8GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Nand8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/NandGateState.d.ts

@@ -0,0 +1,16 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NAND Gate components.
+ *
+ * @public
+ */
+export declare class NandGateState extends LogicGateState {
+    /**
+     * Create a new NAND Gate state.
+     *
+     * @param componentId - UUID of the NAND Gate component
+     * @param initialState - Initial operational state (default: "low")
+     */
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Nor4GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Nor4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Nor8GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Nor8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/NorGateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for NOR Gate components.
+ *
+ * @public
+ */
+export declare class NorGateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Xor4GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR4 Gate components (4 inputs).
+ *
+ * @public
+ */
+export declare class Xor4GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/Xor8GateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR8 Gate components (8 inputs).
+ *
+ * @public
+ */
+export declare class Xor8GateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/gates/XorGateState.d.ts

@@ -0,0 +1,10 @@
+import { LogicGateState } from './index';
+import { UUID } from '../../../utils/types';
+/**
+ * Simulation state for XOR Gate components.
+ *
+ * @public
+ */
+export declare class XorGateState extends LogicGateState {
+    constructor(componentId: UUID, initialState?: string);
+}