simple-circuit-engine 0.0.10 → 0.0.11

package/dist/index.d.ts

@@ -57,6 +57,7 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
     get componentObject3Ds(): Map<UUID, THREE.Object3D>;
     get enodeObject3Ds(): Map<UUID, THREE.Object3D>;
     get wireObject3Ds(): Map<UUID, Line2>;
+    get visualContext(): VisualContext;
     protected get grid(): THREE.GridHelper | null;
     protected set grid(grid: THREE.GridHelper);
     /**
@@ -201,150 +202,6 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
     protected onResize(_width: number, _height: number): void;
 }
 
-/**
- * Visual factory for AND gates components
- *
- * Creates:
- * - Gate mesh
- * - vcc, inputs and output pin groups
- * - Component hitbox for raycasting
- *
- * Animation:
- * - Emissive glow when Gate is high (based on simulation state)
- */
-export declare class And4GateVisualFactory extends AndGateVisualFactory {
-    /** Shared open envelope geometry */
-    protected readonly lowGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly transientGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly highGeometry: THREE.ExtrudeGeometry;
-    /** Shared geometry for negative marker **/
-    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
-    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
-}
-
-/**
- * Visual factory for AND gates components
- *
- * Creates:
- * - Gate mesh
- * - vcc, inputs and output pin groups
- * - Component hitbox for raycasting
- *
- * Animation:
- * - Emissive glow when Gate is high (based on simulation state)
- */
-export declare class And8GateVisualFactory extends AndGateVisualFactory {
-    /** Shared open envelope geometry */
-    protected readonly lowGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly transientGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly highGeometry: THREE.ExtrudeGeometry;
-    /** Shared geometry for negative marker **/
-    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
-    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
-}
-
-/**
- * Visual factory for AND gates components
- *
- * Creates:
- * - Gate mesh
- * - vcc, inputs and output pin groups
- * - Component hitbox for raycasting
- *
- * Animation:
- * - Emissive glow when Gate is high (based on simulation state)
- */
-export declare class AndGateVisualFactory extends ComponentVisualFactoryBase {
-    /** Gate high color */
-    protected static readonly HIGH_COLOR = 16777215;
-    /** Gate high emissive intensity */
-    protected static readonly HIGH_INTENSITY = 0.3;
-    /** Shared open envelope geometry */
-    protected readonly lowGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly transientGeometry: THREE.ExtrudeGeometry;
-    /** Shared transient envelope geometry */
-    protected readonly highGeometry: THREE.ExtrudeGeometry;
-    /** Shared material for negative marker **/
-    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
-    /** Shared geometry for negative marker **/
-    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    defaultRotation(): number;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
-    /**
-     * Map core config to form data
-     * Converts "positive"/"negative" strings to boolean
-     *
-     * @param config - Core component config
-     * @returns Form data with boolean activationLogic
-     */
-    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
-    /**
-     * Map form data to core config
-     * Converts boolean to "positive"/"negative" strings
-     *
-     * @param formData - Form data with boolean activationLogic
-     * @returns Core config with string activationLogic
-     */
-    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
-    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
-    /**
-     * Update animation based on simulation state
-     *
-     * @param object3D - The Object3D created by createVisual()
-     * @param state - The component current simulation state
-     */
-    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
-    /**
-     * Find the envelope mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The envelope mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'envelope'
-     */
-    protected findEnvelopeMesh(object3D: THREE.Object3D): (THREE.Mesh & {
-        material: THREE.MeshStandardMaterial;
-    }) | null;
-    /**
-     * Find the negative marker mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The negative marker mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'negativeMarker'
-     */
-    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
-        material: THREE.MeshStandardMaterial;
-    }) | null;
-}
-
 /**
  * Visual factory for Battery components
  *
@@ -355,7 +212,8 @@ export declare class AndGateVisualFactory extends ComponentVisualFactoryBase {
  * - Component hitbox for raycasting
  */
 export declare class BatteryVisualFactory extends ComponentVisualFactoryBase {
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
 }
 
 /**
@@ -381,21 +239,21 @@ declare class BehaviorRegistry {
      * @throws TypeError if behavior is null/undefined or componentType is empty
      * @returns The registry instance for chaining
      */
-    register(behavior: ComponentBehavior): BehaviorRegistry;
+    register(behavior: IComponentBehavior): BehaviorRegistry;
     /**
      * Register multiple behaviors at once.
      * Convenience method for bulk registration.
      *
      * @param behaviors - Array of behaviors to register
      */
-    registerAll(behaviors: ComponentBehavior[]): void;
+    registerAll(behaviors: IComponentBehavior[]): void;
     /**
      * Get the behavior for a component type.
      *
      * @param componentType - Type identifier (e.g., "battery", "led")
      * @returns The registered behavior, or undefined if not found
      */
-    get(componentType: string): ComponentBehavior | undefined;
+    get(componentType: string): IComponentBehavior | undefined;
     /**
      * Check if a behavior is registered for a component type.
      *
@@ -428,28 +286,6 @@ declare class BehaviorRegistry {
     size(): number;
 }
 
-/**
- * Result returned by component behavior evaluation.
- * Describes state changes and future events to schedule.
- *
- * @public
- */
-declare interface BehaviorResult {
-    /**
-     * Updated component state
-     */
-    readonly componentState: ComponentState;
-    /**
-     * boolean indicating
-     * if the component state has changed (or events scheduled ?)
-     */
-    hasChanged: boolean;
-    /**
-     * Events to schedule for future ticks (e.g., delayed transitions).
-     */
-    readonly scheduledEvents: ReadonlyArray<ScheduledEvent>;
-}
-
 /**
  * Sentinel value representing the "Branching Point" pseudo-component entry.
  * When selected, BuildTool creates a branching point instead of a component.
@@ -516,92 +352,6 @@ export declare class BranchingPointVisualFactory {
     private getColorForSourceType;
 }
 
-/**
- * Visual factory for Buffer/Inverter components
- *
- * Creates:
- * - Buffer trapezoid or Inverter triangle extrude geom mesh
- * - Vcc, input and output pin group
- * - Component hitbox for raycasting
- *
- * Animation:
- * - Emissive glow when component is high (based on simulation state)
- */
-export declare class BufferVisualFactory extends ComponentVisualFactoryBase {
-    /** Buffer high color (white glow) */
-    private static readonly HIGH_COLOR;
-    /** Buffer high emissive intensity */
-    private static readonly HIGH_INTENSITY;
-    /** Shared low Buffer envelope geometry */
-    private readonly bufferLowGeometry;
-    /** Shared transient Buffer envelope geometry */
-    private readonly bufferTransientGeometry;
-    /** Shared high Buffer envelope geometry */
-    private readonly bufferHighGeometry;
-    /** Shared low Inverter envelope geometry */
-    private readonly inverterLowGeometry;
-    /** Shared transient Inverter envelope geometry */
-    private readonly inverterTransientGeometry;
-    /** Shared high Inverter envelope geometry */
-    private readonly inverterHighGeometry;
-    /** Shared geometry for negative marker **/
-    protected readonly negativeMarkerGeometry: THREE.SphereGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    private replaceEnvelope;
-    /**
-     * Get config form definition for Buffer
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
-    /**
-     * Map core config to form data (T026)
-     * Converts "positive"/"negative" strings to boolean
-     *
-     * @param config - Core component config
-     * @returns Form data with boolean activationLogic
-     */
-    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
-    /**
-     * Map form data to core config (T026)
-     * Converts boolean to "positive"/"negative" strings
-     *
-     * @param formData - Form data with boolean activationLogic
-     * @returns Core config with string activationLogic
-     */
-    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
-    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
-    /**
-     * Update Buffer animation based on simulation state
-     *
-     * @param object3D - The Object3D created by createVisual()
-     * @param state - The Buffer's current simulation state
-     */
-    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
-    /**
-     * Find the envelope mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The envelope mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'envelope'
-     */
-    private findEnvelopeMesh;
-    /**
-     * Find the negative marker mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The negative marker mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'negativeMarker'
-     */
-    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
-        material: THREE.MeshStandardMaterial;
-    }) | null;
-}
-
 /**
  * Unified tool for building circuits
  * Implements all circuit editing functionality in a single tool
@@ -1016,7 +766,7 @@ declare class Circuit {
     /**
      * Create a new empty circuit.
      */
-    constructor(name?: string);
+    constructor(options: CircuitOptions);
     get name(): string;
     set name(value: string);
     /**
@@ -1047,6 +797,13 @@ declare class Circuit {
      * ```
      */
     addComponent(type: ComponentType, position: Position, rotation: Rotation, config?: Map<string, string> | undefined): Component;
+    /**
+     * Resolve and update the transitionSpan config for a component
+     * if automatic resolution returns undefined nothing is done on the component
+     *
+     * @param component - Component to resolve transitionSpan for
+     */
+    resolveTransitionSpan(component: Component): void;
     /**
      * Remove a component from the circuit.
      *
@@ -1343,12 +1100,7 @@ declare class Circuit {
      * localStorage.setItem('my-circuit', JSON.stringify(json));
      * ```
      */
-    toJSON(): {
-        metadata: object;
-        components: object[];
-        enodes: object[];
-        wires: object[];
-    };
+    toJSON(): ICircuit;
     /**
      * Deserialize circuit from JSON.
      *
@@ -1363,12 +1115,7 @@ declare class Circuit {
      * const circuit = Circuit.fromJSON(json);
      * ```
      */
-    static fromJSON(json: {
-        metadata: ICircuitMetadata;
-        components: object[];
-        enodes: object[];
-        wires?: object[];
-    }): Circuit;
+    static fromJSON(json: ICircuit): Circuit;
 }
 
 /**
@@ -1837,39 +1584,42 @@ export declare interface CircuitEngineEventMap extends ControllerEventMap {
     modeChanged: ModeChangedEvent;
 }
 
-/**
- * Circuit metadata placeholder
- */
-declare class CircuitMetadata {
-    name: string;
+declare class CircuitMetadata implements ICircuitMetadata {
+    version: string;
+    options: CircuitOptions;
     size: number;
     divisions: number;
     cameraOptions: CameraOptions;
     /**
      * Create a new CircuitMetadata holding general information about the Circuit.
      *
-     * @param name - Name of the circuit
+     * @param version - Circuit version
+     * @param options - Circuit options
      * @param size - Size of the circuit grid
      * @param divisions - Divisions in the circuit grid
      * @param cameraOptions - Camera Options at startup
      * @throws {TypeError} If size or divisions are not integers
      */
-    constructor(name: string, size: number, divisions: number, cameraOptions: CameraOptions);
-    toJSON(): {
-        name: string;
-        size: number;
-        divisions: number;
-        cameraOptions: ICameraOptions;
-    };
-    static fromJSON(json: {
-        name: string;
-        size: number;
-        divisions: number;
-        cameraOptions: ICameraOptions;
-    }): CircuitMetadata;
+    constructor(version: string, options: CircuitOptions, size: number, divisions: number, cameraOptions: CameraOptions);
+    toJSON(): ICircuitMetadata;
+    static fromJSON(json: ICircuitMetadata): CircuitMetadata;
     toString(): string;
 }
 
+declare class CircuitOptions implements ICircuitOptions {
+    name: string;
+    defaultLogicFamily: LogicFamily;
+    /**
+     * Create new circuit options.
+     *
+     * @param name - Circuit name (default: Untitled Circuit)
+     * @param defaultLogicFamily - Circuit default logic family (default: CMOS1)
+     */
+    constructor(name?: string, defaultLogicFamily?: LogicFamily);
+    toJSON(): ICircuitOptions;
+    static fromJSON(json: ICircuitOptions): CircuitOptions;
+}
+
 /**
  * Simulation Circuit Runner Controller Implementation
  *
@@ -2285,10 +2035,14 @@ declare class Component {
      * Configuration parameters for this component instance.
      *
      * This map holds key-value pairs representing configurable settings
-     * The available configuration keys depend on the component type see ComponentTypeMetadata for details.
+     * The available configuration keys depend on the component type see IComponentTypeMetadata for details.
      *
      */
     config: Map<string, string>;
+    /**
+     * allow to flag a component as non editable (feature to implement)
+     */
+    editable: boolean;
     /**
      * Create a new component.
      *
@@ -2301,6 +2055,7 @@ declare class Component {
      * @param rotation - Orientation angle (integer degrees)
      * @param pins - Array of pin ENode UUIDs
      *
+     * @param editable
      * @example
      * ```typescript
      * // Usually created via Circuit:
@@ -2319,7 +2074,7 @@ declare class Component {
      * );
      * ```
      */
-    constructor(type: ComponentType, position: Position, rotation: Rotation, pins: ReadonlyArray<UUID>);
+    constructor(type: ComponentType, position: Position, rotation: Rotation, pins: ReadonlyArray<UUID>, editable?: boolean);
     getPinLabel(pinId: UUID): string | undefined;
     setAllParameters(config: Map<string, string>): void;
     setParameter(key: string, value: string): void;
@@ -2365,117 +2120,15 @@ declare class Component {
      * // }
      * ```
      */
-    toJSON(): {
-        id: UUID;
-        type: ComponentType;
-        position: {
-            x: number;
-            y: number;
-        };
-        rotation: number;
-        pins: UUID[];
-        config: {
-            [key: string]: string;
-        };
-    };
+    toJSON(): IComponent;
     /**
      * Deserialize component from JSON.
      *
      * @param json - Component data
      * @returns Component instance
      *
-     * @example
-     * ```typescript
-     * const json = {
-     *   id: "550e8400-...",
-     *   type: "battery",
-     *   position: { x: 10, y: 20 },
-     *   rotation: 90,
-     *   pins: ['1b4f6f3c-ce ....', '2c5e7g4d-df ...'],
-     *   config: { "voltage": "5V" }
-     * };
-     *
-     * const component = Component.fromJSON(json);
-     * console.log(component.position.x); // 10
-     * ```
-     */
-    static fromJSON(json: {
-        id: UUID;
-        type: ComponentType;
-        position: {
-            x: number;
-            y: number;
-        };
-        rotation: number;
-        pins: UUID[];
-        config: {
-            [key: string]: string;
-        };
-    }): Component;
-}
-
-/**
- * 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
- */
-declare interface ComponentBehavior {
-    /**
-     * Component type this behavior handles (e.g., "battery", "led", "switch").
-     * Used as the key in BehaviorRegistry.
-     */
-    readonly 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 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, NodeElectricalState>, targetTick: number): BehaviorResult;
-    /**
-     * 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 - UserCommand to process
-     * @returns Result containing updated state and scheduled events
-     */
-    onUserCommand(component: Component, state: ComponentState, command: UserCommand): BehaviorResult;
-    /**
-     * Define component state change in response to a ScheduledEvent firing at ready
-     *
-     * @param component - The component being evaluated
-     * @param state - component state prior to this evaluation
-     * @param event - firing ScheduledEvent to process
-     * @returns Result containing updated state and scheduled events
      */
-    onEventFiring(component: Component, state: ComponentState, event: ScheduledEvent): BehaviorResult;
+    static fromJSON(json: IComponent): Component;
 }
 
 /**
@@ -2602,37 +2255,31 @@ declare abstract class ComponentState {
 }
 
 /**
- * Enumeration of available component types.
+ * Enumeration of ALL available component types.
  *
  * Each component type represents a specific electrical element that can be
  * placed in a circuit (battery, LED, transistor, etc.).
- *
- * @example
- * ```typescript
- * const type = ComponentType.Battery;
- * const metadata = COMPONENT_TYPE_METADATA[type];
- * console.log(metadata.name);      // "Battery"
- * console.log(metadata.pins);  // Map([["cathode", ENodeSourceType.Voltage], ["anode", ENodeSourceType.Current]])
- * ```
  */
 declare enum ComponentType {
     Cube = "cube",// no pins component for testing purposes mainly
     Label = "label",// decorative text label with no pins
     Battery = "battery",
     Switch = "switch",
+    DoubleThrowSwitch = "doubleThrowSwitch",
     Lightbulb = "lightbulb",
     Relay = "relay",
-    Transistor = "transistor",
-    Buffer = "buffer",
     SmallLED = "smallLED",
     RectangleLED = "rectangleLED",
-    AndGate = "andGate",
-    And4Gate = "and4Gate",
-    And8Gate = "and8Gate",
-    OrGate = "orGate",
-    Or4Gate = "or4Gate",
-    Or8Gate = "or8Gate",
-    XorGate = "xorGate"
+    Inverter = "inverter",
+    NandGate = "nandGate",
+    Nand4Gate = "nand4Gate",
+    Nand8Gate = "nand8Gate",
+    NorGate = "norGate",
+    Nor4Gate = "nor4Gate",
+    Nor8Gate = "nor8Gate",
+    XorGate = "xorGate",
+    Xor4Gate = "xor4Gate",
+    Xor8Gate = "xor8Gate"
 }
 
 /**
@@ -2656,7 +2303,7 @@ declare enum ComponentType {
  * @example
  * ```typescript
  * export class BatteryVisualFactory extends ComponentVisualFactoryBase {
- *   createVisual(component: Component): THREE.Object3D {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
  *     const group = new THREE.Group();
  *     // ... create battery-specific visual
  *     return group;
@@ -2679,7 +2326,7 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
      * Create the Three.js visual representation for a component
      * Must be implemented by subclasses
      */
-    abstract createVisual(component: Component): THREE.Object3D;
+    abstract createVisual(component: Component, context: VisualContext): THREE.Object3D;
     /**
      * By default no visual configuration-based updates is needed
      */
@@ -2716,6 +2363,10 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
      * @param object3D - The component's root Three.js object
      */
     removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * @private
+     */
+    private pointPinGroupToward;
     /**
      * Create a pin group with hitbox and visual sphere
      *
@@ -2724,20 +2375,30 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
      * - Hemisphere visual (blue sphere)
      * - Hover callback in userData
      *
-     * @param componentId - UUID of the parent component
-     * @param pinId - UUID of this pin/enode
-     * @param label - Human-readable label (e.g., 'input', 'output', 'cathode')
-     * @param sourceType - Optional source type (voltage/current) : if provided this pin will be locked to that type
+     * @param node - ENode to create as visual pin
+     * @param pointsTo - rotate pin to make it point the wanted direction
      * @param visualRotation - if set rotate the visual of the pin to adjust display without affecting hitbox
      * @returns THREE.Group configured as pin group
      */
-    protected createPinGroup(componentId: string, pinId: string, label: string, sourceType?: ENodeSourceType | null, visualRotation?: THREE.Euler | null): THREE.Group;
+    protected createPinGroup(node: ENode, pointsTo?: Direction2D, visualRotation?: THREE.Euler | null): THREE.Group;
+    /**
+     * Utility to create semi spheres visually closing pins
+     * @param pinGroup
+     * @param material
+     * @protected
+     */
+    protected createPinCounterpart(pinGroup: THREE.Group, material: THREE.MeshStandardMaterial): THREE.Mesh | null;
     /**
      * Find pin group by label within a component Object3D
      * @param object3D
      * @param label
      */
     findPinGroup(object3D: THREE.Object3D, label: string): THREE.Group | null;
+    /**
+     * fin pin inner visual from within its pin group
+     * @param pinGroup
+     */
+    findPinVisualFromGroup(pinGroup: THREE.Group): THREE.Mesh | null;
     /**
      * Find pin group visual by label within a component Object3D
      * @param object3D
@@ -2761,20 +2422,20 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
     protected pinColorForSourceType(sourceType: ENodeSourceType | null): number;
     protected pinColorForElectricalState(state: 'current' | 'voltage' | 'vc' | 'idle'): number;
     /**
-     * Updates the visual color of a component pin based on its source type.
+     * Updates the visual color of a component pin based on its sourceType type.
      *
-     * This method changes the pin's material color to reflect the source type:
-     * - null/undefined: bronze (default pin color)
+     * This method changes the pin's material color to reflect the sourceType type:
+     * - null/undefined: copper (default pin color)
      * - Voltage: red
      * - Current: blue
      *
      * @param pinGroup - The THREE.Group containing the pin visual (created by createPinGroup)
-     * @param sourceType - The new source type (null for no source)
+     * @param sourceType - The new sourceType (null for no sourceType)
      *
      * @remarks
      * - Searches for the child mesh with userData.type === 'enode'
      * - Updates both color and emissive properties for visual consistency
-     * - If sourceType is null/undefined, restores default bronze pin color
+     * - If sourceType is null/undefined, restores default copper pin color
      * - Color scheme matches BranchingPointVisualFactory for consistency
      */
     updatePinSourceType(pinGroup: THREE.Object3D, sourceType: ENodeSourceType | null): void;
@@ -2798,7 +2459,7 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
      *
      * Override in subclasses that have configurable options.
      */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    getConfigFormDefinition(_config?: Map<string, string>): ConfigFormDefinition | null;
     /**
      * Map core config to form data (default: identity mapping)
      *
@@ -2836,6 +2497,8 @@ export declare interface ConfigFieldDefinition {
     max?: number;
     /** Step increment for number type */
     step?: number;
+    /** Whether this field is read-only in the form */
+    disabled?: boolean;
 }
 
 /**
@@ -2960,7 +2623,7 @@ export declare interface ControllerEventMap {
         tick: number;
         dirty: unknown;
     };
-    simulationUserCommand: UserCommand;
+    simulationUserCommand: IUserCommand;
     simulationStopped: {
         tick: number;
     };
@@ -3049,6 +2712,79 @@ export declare class DefaultVisualFactory extends ComponentVisualFactoryBase {
     updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
 }
 
+/**
+ * convenience to control standard rotations of meshes on X-Z plan
+ */
+declare type Direction2D = 'right' | 'bottom' | 'left' | 'top';
+
+/**
+ * Visual factory for Double Switch components
+ *
+ * Creates:
+ * - 2 * Input pole (sphere)
+ * - Output pole (box)
+ * - Contactor (cylinder, rotatable for animation)
+ * - Input pin group
+ * - Output pin group
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Rotates contactor based on open/closed state
+ */
+export declare class DoubleThrowSwitchVisualFactory extends ComponentVisualFactoryBase {
+    /** Rotation for switch to input 1 */
+    private readonly INPUT1_ROTATION;
+    /** Rotation for switch toggling */
+    private readonly INTERMEDIATE_ROTATION;
+    /** Rotation for switch to input 2 */
+    private readonly INPUT2_ROTATION;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    /**
+     * Get config form definition for Double Switch
+     *
+     * @returns Form definition with initialState boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (T024)
+     * Converts "input1"/"input2" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean initialState
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (T024)
+     * Converts boolean to "input1"/"input2" strings
+     *
+     * @param formData - Form data with boolean initialState
+     * @returns Core config with string initialState
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update switch animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The Switch's current simulation state, or null in edition mode
+     *
+     * @remarks
+     * Rotates the contactor group to visually represent input1/2 state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Find the contactor group within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The contactor's parent group if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'contactor' and returns its parent
+     */
+    private findContactorGroup;
+}
+
 /**
  * Operating mode of the CircuitEngine
  * - 'edit': Static circuit editing mode (tools, selection, manipulation)
@@ -3073,7 +2809,7 @@ export declare interface EngineOptions {
      * Options passed to CircuitRunner when created
      * @default { enableHistory: false }
      */
-    runnerOptions?: RunnerOptions;
+    runnerOptions?: IRunnerOptions;
 }
 
 /**
@@ -3152,6 +2888,11 @@ declare class ENode {
      * Is the ENode a source of voltage or current?
      */
     source: ENodeSourceType | undefined;
+    /**
+     * Pin role classification: free, mainVcc, vcc, mainGnd, gnd, logicInput, logicOutput.
+     * @readonly
+     */
+    readonly subtype: string;
     /**
      * Create a new electrical node.
      *
@@ -3164,6 +2905,7 @@ declare class ENode {
      * @param position - Grid position (branching points only)
      * @param source - Source type (Voltage/Current) or undefined
      *
+     * @param subtype
      * @example
      * ```typescript
      * // Pin node (internal to Circuit)
@@ -3185,7 +2927,7 @@ declare class ENode {
      * );
      * ```
      */
-    constructor(type: ENodeType, component: UUID | undefined, pinLabel: string | undefined, position: Position | undefined, source?: ENodeSourceType | undefined);
+    constructor(type: ENodeType, component: UUID | undefined, pinLabel: string | undefined, position: Position | undefined, source?: ENodeSourceType | undefined, subtype?: string);
     /**
      * Get the position of this electrical node.
      *
@@ -3252,17 +2994,7 @@ declare class ENode {
      * // }
      * ```
      */
-    toJSON(): {
-        id: UUID;
-        type: ENodeType;
-        component?: UUID | null;
-        pinLabel?: string | null;
-        position?: {
-            x: number;
-            y: number;
-        } | null;
-        source?: ENodeSourceType | null;
-    };
+    toJSON(): IENode;
     /**
      * Deserialize ENode from JSON.
      *
@@ -3281,17 +3013,7 @@ declare class ENode {
      * const enode = ENode.fromJSON(json);
      * ```
      */
-    static fromJSON(json: {
-        id: UUID;
-        type: ENodeType;
-        component?: UUID;
-        pinLabel?: string;
-        position?: {
-            x: number;
-            y: number;
-        };
-        source?: ENodeSourceType;
-    }): ENode;
+    static fromJSON(json: IENode): ENode;
 }
 
 /**
@@ -3304,48 +3026,23 @@ export declare interface EnodeHitboxUserData {
     label: string | null;
 }
 
-/**
- * ENode Source Type Enumeration
- *
- * Defines the two types of electrical pinSources in the circuit model.
- *
- * @module core/types/ENodeSourceType
- */
 /**
  * Type of electrical pinSources in the circuit.
  *
  * ENodes have a sourceType which can be undefined or one of the following:
- *
  * - **Voltage**: ENode that provides a voltage source to the circuit. All Enodes of this type are considered at the same positive potential.
- *
  * - **Current**: Ground/neutral ENodes that provides a current source to the circuit. All Enodes of this type are considered as points at
- * the same 0V potential and are points from where electrons enters the circuit.
- *
- * playback modules use these properties to determine where to draw voltage/current from.
- *
+ * the same 0V-GROUND potential and are points from where electrons enters the circuit.
  */
 declare enum ENodeSourceType {
-    /**
-     * Voltage pinSources
-     */
     Voltage = "Voltage",
-    /**
-     * Current pinSources
-     */
     Current = "Current"
 }
 
-/**
- * ENode Type Enumeration
- *
- * Defines the two types of electrical connection points in the circuit model.
- *
- * @module core/types/ENodeType
- */
 /**
  * Type of electrical node (ENode) in the circuit.
  *
- * ENodes represent atomic electrical connection points and come in two variants (immutable after node creation):
+ * ENodes represent atomic electrical connection points and come in two variants (immutable after node creation)
  *
  * - **Pin**: Connection point belonging to a Component. Position is derived
  *   from the parent component's position, rotation, and pin index. Automatically
@@ -3354,19 +3051,6 @@ declare enum ENodeSourceType {
  * - **BranchingPoint**: Junction point where wires split. Has an independent
  *   position on the grid. Automatically created when wires are split, deleted
  *   when no wires remain connected (orphaned).
- *
- * @example
- * ```typescript
- * // Pin node (belongs to component)
- * if (node.type === ENodeType.Pin) {
- *   console.log('Component pin with label', node.pinLabel);
- * }
- *
- * // Branching point (wire junction)
- * if (node.type === ENodeType.BranchingPoint) {
- *   console.log('Branch at position', node.position);
- * }
- * ```
  */
 declare enum ENodeType {
     /**
@@ -3882,6 +3566,36 @@ export declare class HoverManager {
     private _isSameHover;
 }
 
+/**
+ * Result returned by component behavior evaluation.
+ * Describes state changes and future events to schedule.
+ *
+ * @public
+ */
+declare 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>;
+}
+
+/**
+ * Circuit camera options (used to position camera at startup)
+ */
 declare type ICameraOptions = {
     position: IPosition3D;
     lookAtPosition: IPosition3D;
@@ -3890,13 +3604,108 @@ declare type ICameraOptions = {
     far: number;
 };
 
+/** circuit type */
+declare type ICircuit = {
+    metadata: ICircuitMetadata;
+    components: Iterable<IComponent>;
+    enodes: Iterable<IENode>;
+    wires: Iterable<IWire>;
+};
+
+/** circuit metadata type — combines user writable options and managed metadata */
 declare type ICircuitMetadata = {
-    name: string;
+    version: string;
+    options: ICircuitOptions;
+    cameraOptions: ICameraOptions;
     size: number;
     divisions: number;
-    cameraOptions: ICameraOptions;
 };
 
+/**
+ * User editable options for a Circuit
+ */
+declare type ICircuitOptions = {
+    name: string;
+    defaultLogicFamily: LogicFamily;
+};
+
+/** Interface defining a Component **/
+declare interface IComponent {
+    id: UUID;
+    type: ComponentType;
+    position: IPosition;
+    rotation: number;
+    pins: UUID[];
+    config: {
+        [key: string]: string;
+    };
+    editable: boolean;
+}
+
+/**
+ * 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
+ */
+declare 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 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;
+}
+
 /**
  * Builder interface for adding components to a group.
  * Used as the callback parameter type in addGroup().
@@ -3926,7 +3735,7 @@ export declare interface IComponentGroupBuilder {
  * @example
  * ```typescript
  * class MyComponentFactory extends ComponentVisualFactoryBase {
- *   createVisual(component: Component): THREE.Object3D {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
  *     const group = new THREE.Group();
  *     // ... create visual elements
  *     group.userData.componentId = component.id;
@@ -3945,6 +3754,7 @@ export declare interface IComponentVisualFactory {
      * Create the Three.js visual representation for a component
      *
      * @param component - The circuit component to visualize
+     * @param context - Optional visual context providing access to ENode data
      * @returns THREE.Object3D (typically a Group) containing the visual
      *
      * @remarks
@@ -3955,7 +3765,7 @@ export declare interface IComponentVisualFactory {
      * - Create pin groups with enodes on HitboxLayers.ENODE layer
      * - Return objects positioned at origin (scene controllerType handles placement)
      */
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
     /**
      * Update visual based on component configuration
      *
@@ -4043,13 +3853,16 @@ export declare interface IComponentVisualFactory {
     /**
      * Get the config form definition for this component type
      *
+     * @param config - Optional current component config to compute field states (e.g., disabled)
      * @returns Form definition with field specifications, or null if no config
      *
      * @remarks
      * Defines the UI controls for editing component configuration.
      * Return null for components with no configurable options.
+     * When config is provided, implementations may use it to set field.disabled
+     * based on interdependencies (e.g., transitionSpan disabled when defaultLogicFamily != Sandbox).
      */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
     /**
      * Map core component config (string values) to form data (typed values)
      *
@@ -4134,6 +3947,17 @@ export declare interface IEditingTool {
     getPreviewObjects(): THREE.Object3D[];
 }
 
+/** Interface defining an ElectricalNode **/
+declare interface IENode {
+    id: UUID;
+    type: ENodeType;
+    component?: UUID | null;
+    pinLabel?: string | null;
+    position?: IPosition | null;
+    source?: ENodeSourceType | null;
+    subtype: string;
+}
+
 /**
  * Registry interface for managing component visual factories
  *
@@ -4213,12 +4037,127 @@ export declare interface IGroupedFactoryRegistry {
 }
 
 /**
- * 3D Position Type
+ * Binary electrical state for wires and enodes (connection points)
+ * @module core/simulation/states
+ * @public
+ */
+declare interface INodeElectricalState {
+    /**
+     * True if voltage is present at this node (potential > 0V).
+     * False if node is at ground potential or floating.
+     */
+    hasVoltage: boolean;
+    /**
+     * True if current is actively flowing through this node.
+     * False if no current flow (open circuit or equilibrium).
+     */
+    hasCurrent: boolean;
+    /**
+     * True only if the node is locked from state changes at circuit build time (ex: battery pins or other fixed-voltage/current pinSources).
+     * Important: Those nodes should never have their electrical state modified by the simulation controller!
+     * Always false for wires
+     */
+    locked: boolean;
+}
+
+/**
+ * Visual factory for Inverter/Buffer components
  *
- * Represents a 3D position. Used for:
- * - Camera placement
+ * Creates:
+ * - Inverter triangle or Buffer trapezoid extrude geom mesh
+ * - Vcc, input and output pin group
+ * - Component hitbox for raycasting
  *
- * @module core/types/Position3D
+ * Animation:
+ * - Emissive glow when component is high (based on simulation state)
+ */
+export declare class InverterVisualFactory extends ComponentVisualFactoryBase {
+    /** Inverter high color (white glow) */
+    private static readonly HIGH_COLOR;
+    /** Inverter high emissive intensity */
+    private static readonly HIGH_INTENSITY;
+    /** Shared low Inverter envelope geometry */
+    private readonly inverterLowGeometry;
+    /** Shared transient Inverter envelope geometry */
+    private readonly inverterTransientGeometry;
+    /** Shared high Inverter envelope geometry */
+    private readonly inverterHighGeometry;
+    /** Shared low Buffer envelope geometry */
+    private readonly bufferLowGeometry;
+    /** Shared transient Buffer envelope geometry */
+    private readonly bufferTransientGeometry;
+    /** Shared high Buffer envelope geometry */
+    private readonly bufferHighGeometry;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    private replaceEnvelope;
+    /**
+     * Get config form definition for Inverter
+     *
+     * @param config - Optional current config to determine disabled state of transitionSpan
+     * @returns Form definition with defaultLogicFamily dropdown, activationLogic boolean, and transitionSpan number
+     */
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     * Converts "positive"/"negative" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     * Converts boolean to "positive"/"negative" strings
+     *
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update Inverter animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The Inverter's current simulation state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Find the envelope mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
+     */
+    private findEnvelopeMesh;
+    /**
+     * Find the negative marker mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
+     */
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+}
+
+/**
+ * 2D Position Type
+ * Represents a 2D position on the circuit grid
+ */
+declare type IPosition = {
+    x: number;
+    y: number;
+};
+
+/**
+ * 3D Position Type
+ * Represents a 3D position. Used for Camera placement
  */
 declare type IPosition3D = {
     x: number;
@@ -4226,6 +4165,96 @@ declare type IPosition3D = {
     z: number;
 };
 
+/**
+ * Configuration options for CircuitRunner
+ */
+declare interface IRunnerOptions {
+    /**
+     * Enable historical state tracking.
+     * When true, past simulation states are preserved up to historyLimit.
+     * When false (default), only current state is retained for better performance.
+     * @default false
+     */
+    enableHistory?: boolean;
+    /**
+     * Maximum number of historical states to retain when enableHistory is true.
+     * Uses circular buffer—oldest states are overwritten when limit is reached.
+     * Must be a positive integer.
+     * @default 1000
+     */
+    historyLimit?: number;
+}
+
+/**
+ * Scheduled event for delayed component transitions.
+ * Events are ordered by readyAtTick in a min-heap priority queue.
+ * Events with same readyAtTick are processed in FIFO order (by scheduledAtTick).
+ *
+ * @public
+ */
+declare interface IScheduledEvent {
+    /**
+     * UUID of target component.
+     */
+    readonly targetId: UUID;
+    /**
+     * Tick when this event was scheduled (for FIFO ordering).
+     * @readonly
+     */
+    readonly scheduledAtTick: number;
+    /**
+     * Tick when this event should be processed.
+     * @readonly
+     */
+    readonly readyAtTick: number;
+    /**
+     * Indicates the type of this event, eg 'ClosingEnd', 'OpeningEnd', etc.
+     */
+    readonly type: string;
+    /**
+     * extra parameters associated with this event.
+     */
+    readonly parameters?: Map<string, string> | undefined;
+}
+
+/**
+ * User command to be executed during simulation.
+ * Commands can be queued for future ticks or executed immediately.
+ *
+ * @public
+ */
+declare interface IUserCommand {
+    /**
+     * Type of command.
+     */
+    readonly type: 'toggle_switch';
+    /**
+     * UUID of target component.
+     */
+    readonly targetId: UUID;
+    /**
+     * tick when this command was scheduled.
+     */
+    scheduledAtTick: number;
+    /**
+     * Extra parameters associated with this command.
+     *
+     * For `toggle_switch` commands:
+     * - `tickCount`: Number of ticks for the switch transition. Computed at toggle time
+     *   using the formula: `ceil(transitionUserSpan × simulationSpeed / 1000)` with minimum of 1.
+     *   If not provided, behavior uses default transition timing.
+     */
+    readonly parameters?: Map<string, string> | null;
+}
+
+/** Interface defining a Wire (link between 2 ENodes supporting intermediate position to tune its path) **/
+declare interface IWire {
+    id: UUID;
+    node1: UUID;
+    node2: UUID;
+    intermediatePositions: IPosition[];
+}
+
 /**
  * Visual factory for Label components
  *
@@ -4264,13 +4293,7 @@ export declare class LabelVisualFactory extends ComponentVisualFactoryBase {
     private static readonly BASE_FONT_SIZE;
     /** Padding around text in pixels */
     private static readonly PADDING;
-    /**
-     * Create the Three.js visual representation for a Label component
-     *
-     * @param component - The Label component to visualize
-     * @returns THREE.Group containing hitbox and text mesh
-     */
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, _context: VisualContext): THREE.Object3D;
     /**
      * Create a canvas with rendered text
      *
@@ -4393,7 +4416,8 @@ export declare class LightbulbVisualFactory extends ComponentVisualFactoryBase {
     private static readonly BULB_LIT_COLOR;
     /** Lightbulb lit emissive intensity */
     private static readonly BULB_LIT_INTENSITY;
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
     /**
      * Get config form definition for Lightbulb
      *
@@ -4438,6 +4462,15 @@ export { LineGeometry }
 
 export { LineMaterial }
 
+/**
+ * Available logic families
+ *
+ * - `CMOS1`: CMOS technology, base unit 1 inverter = 1 tick
+ * - `TTL1`: TTL technology, base unit 1 NAND2 = 1 tick
+ * - `Sandbox`: User-defined delays, no technology constraints
+ */
+declare type LogicFamily = 'CMOS1' | 'TTL1' | 'Sandbox';
+
 /**
  * Configuration options for Controllers and Engine
  **/
@@ -4676,40 +4709,153 @@ export declare class MultiSelectTool implements IEditingTool {
 export declare type MultiSelectToolMode = 'idle' | 'selecting' | 'dragging';
 
 /**
- * Binary electrical state for wires and enodes (connection points)
- * @module core/simulation/states
+ * Visual factory for NAND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, gnd, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
  */
-declare interface NodeElectricalState {
+export declare class Nand4GateVisualFactory extends NandGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for NAND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, gnd, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class Nand8GateVisualFactory extends NandGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for NAND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, gnd, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class NandGateVisualFactory extends ComponentVisualFactoryBase {
+    /** Gate high color */
+    protected static readonly HIGH_COLOR = 16777215;
+    /** Gate high emissive intensity */
+    protected static readonly HIGH_INTENSITY = 0.3;
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared material for negative marker **/
+    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    defaultRotation(): number;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
     /**
-     * True if voltage is present at this node (potential > 0V).
-     * False if node is at ground potential or floating.
+     * Get config form definition
+     *
+     * @param config - Optional current config to determine disabled state of transitionSpan
+     * @returns Form definition with defaultLogicFamily dropdown, activationLogic boolean, and transitionSpan number
+     */
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     * Converts "positive"/"negative" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     * Converts boolean to "positive"/"negative" strings
+     *
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component current simulation state
      */
-    hasVoltage: boolean;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
     /**
-     * True if current is actively flowing through this node.
-     * False if no current flow (open circuit or equilibrium).
+     * Find the envelope mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
      */
-    hasCurrent: boolean;
+    protected findEnvelopeMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
     /**
-     * True only if the node is locked from state changes at circuit build time (ex: battery pins or other fixed-voltage/current pinSources).
-     * Important: Those nodes should never have their electrical state modified by the simulation controller!
-     * Always false for wires
+     * Find the negative marker mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
      */
-    locked: boolean;
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
 }
 
 /**
- * Visual factory for OR gates components
+ * Visual factory for NOR gates components
  *
  * Creates:
  * - Gate mesh
- * - vcc, inputs and output pin groups
+ * - vcc, gnd, inputs and output pin groups
  * - Component hitbox for raycasting
  *
  * Animation:
  * - Emissive glow when Gate is high (based on simulation state)
  */
-export declare class Or4GateVisualFactory extends OrGateVisualFactory {
+export declare class Nor4GateVisualFactory extends NorGateVisualFactory {
     /** Shared open envelope geometry */
     protected readonly lowGeometry: THREE.ExtrudeGeometry;
     /** Shared transient envelope geometry */
@@ -4718,28 +4864,23 @@ export declare class Or4GateVisualFactory extends OrGateVisualFactory {
     protected readonly highGeometry: THREE.ExtrudeGeometry;
     /** Shared geometry for negative marker **/
     protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
     updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
 }
 
 /**
- * Visual factory for OR gates components
+ * Visual factory for NOR gates components
  *
  * Creates:
  * - Gate mesh
- * - vcc, inputs and output pin groups
+ * - vcc, gnd, inputs and output pin groups
  * - Component hitbox for raycasting
  *
  * Animation:
  * - Emissive glow when Gate is high (based on simulation state)
  */
-export declare class Or8GateVisualFactory extends OrGateVisualFactory {
+export declare class Nor8GateVisualFactory extends NorGateVisualFactory {
     /** Shared open envelope geometry */
     protected readonly lowGeometry: THREE.ExtrudeGeometry;
     /** Shared transient envelope geometry */
@@ -4748,28 +4889,23 @@ export declare class Or8GateVisualFactory extends OrGateVisualFactory {
     protected readonly highGeometry: THREE.ExtrudeGeometry;
     /** Shared geometry for negative marker **/
     protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
     updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
 }
 
 /**
- * Visual factory for OR gates components
+ * Visual factory for NOR gates components
  *
  * Creates:
  * - Gate mesh
- * - vcc, inputs and output pin groups
+ * - vcc, gnd, inputs and output pin groups
  * - Component hitbox for raycasting
  *
  * Animation:
  * - Emissive glow when Gate is high (based on simulation state)
  */
-export declare class OrGateVisualFactory extends ComponentVisualFactoryBase {
+export declare class NorGateVisualFactory extends ComponentVisualFactoryBase {
     /** Gate high color */
     protected static readonly HIGH_COLOR = 16777215;
     /** Gate high emissive intensity */
@@ -4785,13 +4921,15 @@ export declare class OrGateVisualFactory extends ComponentVisualFactoryBase {
     /** Shared geometry for negative marker **/
     protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
     defaultRotation(): number;
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
     /**
-     * Get config form definition for OR Gate
+     * Get config form definition
      *
-     * @returns Form definition with activationLogic boolean field
+     * @param config - Optional current config to determine disabled state of transitionSpan
+     * @returns Form definition with defaultLogicFamily dropdown, activationLogic boolean, and transitionSpan number
      */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
     /**
      * Map core config to form data
      * Converts "positive"/"negative" strings to boolean
@@ -4855,7 +4993,7 @@ export declare type PickerSelection = ComponentType | typeof BRANCHING_POINT_SEN
  * - Branching point ENode positions
  * - Wire intermediate waypoints
  *
- * @module core/types/Position
+ * @module core/utils
  */
 /**
  * Position on a 2D discrete grid with integer coordinates.
@@ -5037,7 +5175,8 @@ export declare class RectangleLEDVisualFactory extends ComponentVisualFactoryBas
     private static readonly LED_LIT_COLOR;
     /** LED lit emissive intensity */
     private static readonly LED_LIT_INTENSITY;
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
     /**
      * Get config form definition for SmallLED (T027)
      *
@@ -5096,7 +5235,7 @@ export declare class RectangleLEDVisualFactory extends ComponentVisualFactoryBas
 
 /**
  * Register all basic components visual factories in the basic group
- * Basic components are : Battery, Label, Switch, Lightbulb, RectangleLED, Relay, SmallLED, Transistor
+ * Basic components are : Battery, Label, Switches, Lightbulb, RectangleLED, Relay, SmallLED
  * @public
  * @param registry - A grouped factory registry to populate
  * @returns The input registry for chaining
@@ -5105,8 +5244,8 @@ export declare function registerBasicComponentsFactories(registry: IGroupedFacto
 
 /**
  * Register all logic gates components visual factories in the gates group
- * gates are : AND (2,4,8,16 inputs), OR (2,4,8,16 inputs) and XOR
- * NAND and NOR are gotten by changing the activationLogic of AND and OR
+ * gates are : Inverter, NAND (2,4,8 inputs), NOR (2,4,8 inputs) and XOR (2,4,8 inputs)
+ * AND/OR are gotten by changing the activationLogic of NAND/NOR
  * @public
  * @param registry - A grouped factory registry to populate
  * @returns The input registry for chaining
@@ -5116,26 +5255,37 @@ export declare function registerGatesComponentsFactories(registry: IGroupedFacto
 /**
  * Visual factory for Relay components
  *
- * Creates:
- * - Component hitbox for raycasting
- * - Cylinder representing the coil with two poles
- * - Output commanded switch with contactor
- * - Contactor (cylinder, rotatable for animation)
  * Animation:
  * - Rotates contactor based on open/closed state
  */
 export declare class RelayVisualFactory extends ComponentVisualFactoryBase {
+    /** Coil ring geometry */
+    private readonly COIL_GEOM;
+    /** Coil bar geometry */
+    private readonly COIL_BAR_GEOM;
+    private readonly COIL_BAR_Z_OPEN;
+    private readonly COIL_BAR_Z_INTERMEDIATE;
+    private readonly COIL_BAR_Z_CLOSED;
+    private readonly COIL_BAR_Z_INV_INTERMEDIATE;
+    private readonly COIL_BAR_Z_INV_OPEN;
+    /** Power In bar geometry */
+    private readonly PWIN_BAR_GEOM;
+    /** normal contactor geom */
+    private CONTACTOR_GEOM;
     /** Rotation for open relay (contactor misaligned) */
-    private static readonly OPEN_ROTATION;
+    private readonly OPEN_ROTATION;
     /** Rotation for opening/closing relay */
-    private static readonly INTERMEDIATE_ROTATION;
+    private readonly INTERMEDIATE_ROTATION;
     /** Rotation for closed relay (contactor aligned) */
-    private static readonly CLOSED_ROTATION;
+    private readonly CLOSED_ROTATION;
     /** Rotation for opening/closing negative activation logic relay */
-    private static readonly INVERTED_INTERMEDIATE_ROTATION;
+    private readonly INVERTED_INTERMEDIATE_ROTATION;
     /** Rotation for open negative activation logic relay (contactor misaligned toward the coil) */
-    private static readonly INVERTED_OPEN_ROTATION;
-    createVisual(component: Component): THREE.Object3D;
+    private readonly INVERTED_OPEN_ROTATION;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    private createContactorGroup;
+    private createCoilGroup;
     /**
      * Get config form definition for Relay (T025)
      *
@@ -5180,7 +5330,7 @@ export declare class RelayVisualFactory extends ComponentVisualFactoryBase {
      */
     private findContactorGroup;
     /**
-     * Find the coil within the component group
+     * Find the coil bar within the component group
      *
      * @param object3D - The Object3D group created by createVisual()
      * @returns The contactor's parent group if found, null otherwise
@@ -5188,16 +5338,14 @@ export declare class RelayVisualFactory extends ComponentVisualFactoryBase {
      * @remarks
      * Searches for a mesh with userData.part === 'coil' and returns its parent
      */
-    private findCoil;
+    private findCoilBar;
 }
 
 /**
  * Rotation Type for Component Orientation
- *
  * Represents orientation angle for components on the 2D grid.
  * Uses integer degrees for discrete rotation values.
- *
- * @module core/types/Rotation
+ * @module core/utils
  */
 /**
  * Rotation angle for component orientation.
@@ -5276,59 +5424,6 @@ declare class Rotation {
     toString(): string;
 }
 
-/**
- * Configuration options for CircuitRunner
- * @module core/simulation/types
- */
-declare interface RunnerOptions {
-    /**
-     * Enable historical state tracking.
-     * When true, past simulation states are preserved up to historyLimit.
-     * When false (default), only current state is retained for better performance.
-     * @default false
-     */
-    enableHistory?: boolean;
-    /**
-     * Maximum number of historical states to retain when enableHistory is true.
-     * Uses circular buffer—oldest states are overwritten when limit is reached.
-     * Must be a positive integer.
-     * @default 1000
-     */
-    historyLimit?: number;
-}
-
-/**
- * Scheduled event for delayed component transitions.
- * Events are ordered by readyAtTick in a min-heap priority queue.
- * Events with same readyAtTick are processed in FIFO order (by scheduledAtTick).
- *
- * @public
- */
-declare interface ScheduledEvent {
-    /**
-     * UUID of target component.
-     */
-    readonly targetId: UUID;
-    /**
-     * Tick when this event was scheduled (for FIFO ordering).
-     * @readonly
-     */
-    readonly scheduledAtTick: number;
-    /**
-     * Tick when this event should be processed.
-     * @readonly
-     */
-    readonly readyAtTick: number;
-    /**
-     * Indicates the type of this event, eg 'ClosingEnd', 'OpeningEnd', etc.
-     */
-    readonly type: string;
-    /**
-     * extra parameters associated with this event.
-     */
-    readonly parameters?: Map<string, string> | undefined;
-}
-
 /**
  * Callback invoked when selection changes
  *
@@ -5536,7 +5631,8 @@ export declare class SmallLEDVisualFactory extends ComponentVisualFactoryBase {
     private static readonly LED_LIT_COLOR;
     /** LED lit emissive intensity */
     private static readonly LED_LIT_INTENSITY;
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
     /**
      * Get config form definition for SmallLED (T027)
      *
@@ -5609,12 +5705,13 @@ export declare class SmallLEDVisualFactory extends ComponentVisualFactoryBase {
  */
 export declare class SwitchVisualFactory extends ComponentVisualFactoryBase {
     /** Rotation for closed switch (contactor aligned) */
-    private static readonly CLOSED_ROTATION;
+    private readonly CLOSED_ROTATION;
     /** Rotation for opening/closing switch */
-    private static readonly INTERMEDIATE_ROTATION;
+    private readonly INTERMEDIATE_ROTATION;
     /** Rotation for open switch (contactor misaligned) */
-    private static readonly OPEN_ROTATION;
-    createVisual(component: Component): THREE.Object3D;
+    private readonly OPEN_ROTATION;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
     /**
      * Get config form definition for Switch (T024)
      *
@@ -5671,141 +5768,24 @@ export declare class SwitchVisualFactory extends ComponentVisualFactoryBase {
 export declare type ToolType = 'build' | 'multiSelect';
 
 /**
- * Visual factory for Transistor components
- *
- * Creates:
- * - Transistor Ring mesh
- * - Collector, Base and Emitter pin group
- * - Component hitbox for raycasting
- *
- * Animation:
- * - Emissive glow when Transistor is closed (based on simulation state)
+ * core utilities types definitions
+ * @module core/utils
  */
-export declare class TransistorVisualFactory extends ComponentVisualFactoryBase {
-    /** Transistor closed color (white glow) */
-    private static readonly TRANSISTOR_CLOSED_COLOR;
-    /** Transistor closed emissive intensity */
-    private static readonly TRANSISTOR_CLOSED_INTENSITY;
-    /** Shared open Transistor envelope geometry */
-    private readonly openGeometry;
-    /** Shared transient Transistor envelope geometry */
-    private readonly transientGeometry;
-    /** Shared transient Transistor envelope geometry */
-    private readonly closedGeometry;
-    /** Shared material for negative marker **/
-    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
-    /** Shared geometry for negative marker **/
-    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
-    createVisual(component: Component): THREE.Object3D;
-    /**
-     * Get config form definition for Transistor (T026)
-     *
-     * @returns Form definition with activationLogic boolean field
-     */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
-    /**
-     * Map core config to form data (T026)
-     * Converts "positive"/"negative" strings to boolean
-     *
-     * @param config - Core component config
-     * @returns Form data with boolean activationLogic
-     */
-    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
-    /**
-     * Map form data to core config (T026)
-     * Converts boolean to "positive"/"negative" strings
-     *
-     * @param formData - Form data with boolean activationLogic
-     * @returns Core config with string activationLogic
-     */
-    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
-    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
-    /**
-     * Update Transistor animation based on simulation state
-     *
-     * @param object3D - The Object3D created by createVisual()
-     * @param state - The Transistor's current simulation state
-     */
-    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
-    /**
-     * Find the envelope mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The envelope mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'envelope'
-     */
-    private findEnvelopeMesh;
-    /**
-     * Find the negative marker mesh within the component group
-     *
-     * @param object3D - The Object3D group created by createVisual()
-     * @returns The negative marker mesh if found, null otherwise
-     *
-     * @remarks
-     * Searches for a mesh with userData.part === 'negativeMarker'
-     */
-    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
-        material: THREE.MeshStandardMaterial;
-    }) | null;
-}
-
 /**
- * User command to be executed during simulation.
- * Commands can be queued for future ticks or executed immediately.
- *
- * @public
+ * Universally Unique Identifier (RFC 4122 UUID v4).
  */
-declare interface UserCommand {
-    /**
-     * Type of command.
-     */
-    readonly type: 'toggle_switch';
-    /**
-     * UUID of target component.
-     */
-    readonly targetId: UUID;
-    /**
-     * tick when this command was scheduled.
-     */
-    scheduledAtTick: number;
-    /**
-     * Extra parameters associated with this command.
-     *
-     * For `toggle_switch` commands:
-     * - `tickCount`: Number of ticks for the switch transition. Computed at toggle time
-     *   using the formula: `ceil(transitionUserSpan × simulationSpeed / 1000)` with minimum of 1.
-     *   If not provided, behavior uses default transition timing.
-     */
-    readonly parameters?: Map<string, string> | null;
-}
+declare type UUID = string;
 
 /**
- * UUID Type and Generation Utilities
- *
- * Provides RFC 4122 UUID v4 identifiers for all entities in the circuit model.
- * Uses native crypto.randomUUID() when available (modern browsers, Node 19+),
- * with fallback for older environments.
- *
- * @module core/types/Identifier
- */
-/**
- * Universally Unique Identifier (RFC 4122 UUID v4).
- *
- * Used as the primary identifier for all circuit entities:
- * - Circuit
- * - Component
- * - ENode (electrical nodes)
- * - Wire
+ * Lightweight context passed to visual factories so they can access
+ * ENode data (subtype, source, wires…) when creating pin visuals.
  *
- * @example
- * ```typescript
- * const id: UUID = generateUUID();
- * console.log(id); // "550e8400-e29b-41d4-a716-446655440000"
- * ```
+ * Circuit satisfies this interface structurally — controllers can pass
+ * `this._circuit` directly without a wrapper.
  */
-declare type UUID = string;
+export declare interface VisualContext {
+    getENode(id: UUID): ENode | undefined;
+}
 
 /**
  * Electrical connection between two ENodes.
@@ -5914,15 +5894,7 @@ declare class Wire {
      * // }
      * ```
      */
-    toJSON(): {
-        id: UUID;
-        node1: UUID;
-        node2: UUID;
-        intermediatePositions: {
-            x: number;
-            y: number;
-        }[];
-    };
+    toJSON(): IWire;
     /**
      * Deserialize wire from JSON.
      *
@@ -5941,15 +5913,7 @@ declare class Wire {
      * const wire = Wire.fromJSON(json);
      * ```
      */
-    static fromJSON(json: {
-        id: UUID;
-        node1: UUID;
-        node2: UUID;
-        intermediatePositions: {
-            x: number;
-            y: number;
-        }[];
-    }): Wire;
+    static fromJSON(json: IWire): Wire;
 }
 
 /**
@@ -6202,7 +6166,61 @@ export declare class WireVisualManager {
  *
  * Creates:
  * - Gate mesh
- * - vcc, inputs and output pin groups
+ * - vcc, gnd, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class Xor4GateVisualFactory extends XorGateVisualFactory {
+    /** XOR tail geometry */
+    protected readonly tailGeometry: THREE.ExtrudeGeometry;
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for XOR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, gnd, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class Xor8GateVisualFactory extends XorGateVisualFactory {
+    /** XOR tail geometry */
+    protected readonly tailGeometry: THREE.ExtrudeGeometry;
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for XOR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, gnd, inputs and output pin groups
  * - Component hitbox for raycasting
  *
  * Animation:
@@ -6214,7 +6232,7 @@ export declare class XorGateVisualFactory extends ComponentVisualFactoryBase {
     /** Gate high emissive intensity */
     protected static readonly HIGH_INTENSITY = 0.3;
     /** XOR tail geometry */
-    protected static readonly tailGeometry: THREE.ExtrudeGeometry;
+    protected readonly tailGeometry: THREE.ExtrudeGeometry;
     /** Shared open envelope geometry */
     protected readonly lowGeometry: THREE.ExtrudeGeometry;
     /** Shared transient envelope geometry */
@@ -6222,17 +6240,19 @@ export declare class XorGateVisualFactory extends ComponentVisualFactoryBase {
     /** Shared transient envelope geometry */
     protected readonly highGeometry: THREE.ExtrudeGeometry;
     /** Shared material for negative marker **/
-    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    protected readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
     /** Shared geometry for negative marker **/
-    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    protected readonly negativeMarkerGeometry: THREE.CylinderGeometry;
     defaultRotation(): number;
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
     /**
-     * Get config form definition for OR Gate
+     * Get config form definition for XOR/XNOR Gate
      *
-     * @returns Form definition with activationLogic boolean field
+     * @param config - Optional current config to determine disabled state of transitionSpan
+     * @returns Form definition with defaultLogicFamily dropdown, activationLogic boolean, and transitionSpan number
      */
-    getConfigFormDefinition(): ConfigFormDefinition | null;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
     /**
      * Map core config to form data
      * Converts "positive"/"negative" strings to boolean