simple-circuit-engine 0.0.11 → 0.0.13

package/dist/core/simulation/behaviors/arithmetic/EightBitAdderBehavior.d.ts

@@ -0,0 +1,51 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior, IBehaviorResult } from '../types';
+import { IScheduledEvent } from '../../types';
+import { UUID } from '../../../utils/types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the 8-bit ripple carry adder (8 full adders in series).
+ *
+ * Unlike the single full adder whose output settles in one transition, the
+ * 8-bit adder models **carry propagation**: when inputs change, only stage 0
+ * recomputes immediately (with its own propagation delay); the carry then
+ * ripples through stages 1–7, one `transitionSpan` per stage.
+ *
+ * ### State encoding
+ *
+ * 16 interleaved bits `C7S7 C6S6 … C1S1 C0S0` stored as a 4-digit hex
+ * string. Sum at bit `2*i`, carry at bit `2*i+1`.
+ * See {@link EightBitAdderState}.
+ *
+ * ### Ripple algorithm
+ *
+ * - **`onPinsChange`**: computes ALL 8 stages with new inputs but **old
+ *   carries** from the current effective state, producing an intermediate
+ *   state. Schedules one event for carry propagation starting at stage 1.
+ *   Uses `shouldCancelPending: true` to restart the ripple cleanly when
+ *   inputs change mid-propagation.
+ *
+ * - **`onEventFiring`**: lands on the intermediate, then checks whether the
+ *   next stage's carry-in changed. If so, recomputes that stage, builds the
+ *   next intermediate, and schedules the following stage. If not, the carry
+ *   has stopped and the state is stable. Uses `shouldCancelPending: false`.
+ *
+ * - **Initialization shortcut**: at `targetTick === 0` the full stable state
+ *   is computed directly via {@link computeTargetStableState} to avoid the
+ *   init-loop limitation where chained events are dropped.
+ *
+ * @public
+ */
+export declare class EightBitAdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    /**
+     * Compute the fully-settled stable state by propagating the carry chain
+     * through all 8 stages. Used at initialization and for test verification.
+     */
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/EightBitOnesComplementBehavior.d.ts

@@ -0,0 +1,29 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ENodeSourceType } from '../../../topology/types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the 8-bit one's complement (8 parallel XOR gates with shared
+ * `invert` input).
+ *
+ * When `invert` is high every output is the bitwise NOT of its input; when low
+ * outputs pass through unchanged. All 8 gates fire in parallel — a single
+ * `transitionSpan` covers the whole transition (no ripple).
+ *
+ * State encoding: 9 bits as a 3-hex-char string. Bits 0–7 are outputs,
+ * bit 8 is the invert flag. See {@link EightBitOnesComplementState}.
+ *
+ * The mixin's default `onPinsChange` / `onEventFiring` / `scheduleTransition`
+ * handle everything — only `computeTargetStableState` and
+ * `allowConductivity` need implementation.
+ *
+ * @public
+ */
+export declare class EightBitOnesComplementBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/HalfAdderBehavior.d.ts

@@ -0,0 +1,22 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the Half Adder component (XOR + AND in one block).
+ *
+ * - `sum = A XOR B`
+ * - `carry = A AND B`
+ *
+ * State encoding follows `${sumBit}${carryBit}` — see {@link HalfAdderState}.
+ * Because `sum` and `carry` can never both be high, only three stable states
+ * are reachable: `'00' | '10' | '01'`.
+ *
+ * @public
+ */
+export declare class HalfAdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

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

@@ -0,0 +1,7 @@
+/**
+ * Arithmetic components behaviors
+ * @module core/simulation/behaviors
+ */
+export { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+export { HalfAdderBehavior } from './HalfAdderBehavior';
+export { AdderBehavior } from './AdderBehavior';

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

@@ -0,0 +1,14 @@
+import { Component } from '../../../topology/Component';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+export declare class BatteryBehavior extends ComponentBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a battery.
+     *
+     * @param component - The Battery component
+     * @returns Battery Initial state (always active and delivering voltage)
+     */
+    createInitialState(component: Component): ComponentState;
+}

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

@@ -0,0 +1,24 @@
+import { Component } from '../../../topology/Component';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior, IBehaviorResult } from '../types';
+import { ENodeSourceType } from '../../../topology/types';
+import { IScheduledEvent } from '../../types';
+export declare class ClockBehavior extends ComponentBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a Clock.
+     *
+     * @param component - The Clock component
+     * @returns Clock Initial state (needle rotation)
+     */
+    createInitialState(component: Component): ComponentState;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * Clock onStart allows to bootstrap cycling
+     * @param component
+     * @param state
+     */
+    onStart(component: Component, state: ComponentState): IBehaviorResult | null;
+    onEventFiring(component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/basic/DoubleThrowSwitchBehavior.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 DoubleThrowSwitchBehavior extends ComponentBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a double throw switch (SPDT).
+     *
+     * @param component - The double Switch component
+     * @returns double Switch Initial state (input1 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/LightbulbBehavior.d.ts

@@ -0,0 +1,23 @@
+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 LightbulbBehavior extends BipolarLightEmitterBehaviorMixin implements IComponentBehavior {
+    constructor();
+    /**
+     * Create initial state for a lightbulb.
+     *
+     * @param component - The lightbulb component
+     * @returns lightbulbInitial state (always active and delivering voltage)
+     */
+    createInitialState(component: Component): ComponentState;
+    /**
+     * @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/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,28 @@
+/**
+ * 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';
+export { HalfAdderBehavior } from './arithmetic/HalfAdderBehavior';
+export { AdderBehavior } from './arithmetic/AdderBehavior';
+export { EightBitAdderBehavior } from './arithmetic/EightBitAdderBehavior';
+export { EightBitOnesComplementBehavior } from './arithmetic/EightBitOnesComplementBehavior';