simple-circuit-engine 0.0.9 → 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);
     /**
@@ -139,7 +140,7 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
     /**
      * Get the current cursor position on the ground plane (y=0) in world coordinates
      * The position is clamped within the circuit grid boundaries but not snapped to grid
-     * @param bound - Whether to constrain position within grid boundaries
+     * @param bound - Whether to constrain position within grid boundaries, default false
      */
     cursorGroundPlanePosition(bound?: boolean): THREE.Vector3;
     /**
@@ -201,138 +202,6 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
     protected onResize(_width: number, _height: number): void;
 }
 
-/**
- * Tool for adding new components to the circuit
- * Provides ghost preview, grid snapping, and placement validation
- */
-export declare class AddComponentTool implements IEditingTool {
-    readonly type: ToolType;
-    private _controller;
-    private _componentType;
-    private _ghostPreview;
-    private _previewPosition;
-    private _previewRotation;
-    private _hasOverlap;
-    private _gridPositionMoveHandler;
-    private _pointerDownHandler;
-    private _wheelHandler;
-    private _keyDownHandler;
-    constructor(controller: CircuitController);
-    /**
-     * Called when tool becomes active (T010)
-     * Attaches event listeners for hover and click interactions
-     */
-    onActivate(): void;
-    /**
-     * Called when tool is deactivated (T011)
-     * Removes event listeners and cleans up preview objects
-     */
-    onDeactivate(): void;
-    /**
-     * Set the component type to place (T012)
-     * Creates a new ghost preview for the selected component type
-     *
-     * @param type - Component type to place
-     */
-    setComponentType(type: ComponentType | null): void;
-    /**
-     * Cycle through available component types (for ctrl+scroll)
-     * @param forward
-     * @private
-     */
-    private cycleComponentTypes;
-    /**
-     * Create ghost preview for the current component type (T013)
-     * Uses FactoryRegistry to create visual representation
-     * @private
-     */
-    private _createGhostPreview;
-    /**
-     * Apply ghost effect to preview object (T014)
-     * Makes the preview semi-transparent to indicate it's not yet placed
-     *
-     * @param object - Object3D to apply ghost effect to
-     * @private
-     */
-    private _applyGhostEffect;
-    /**
-     * Dispose ghost preview and cleanup resources
-     * @private
-     */
-    private _disposeGhostPreview;
-    /**
-     * Get preview objects to render in the scene (T015)
-     * Returns the ghost preview if available
-     *
-     * @returns Array containing ghost preview object
-     */
-    getPreviewObjects(): THREE.Object3D[];
-    /**
-     * Check if preview overlaps with existing components (T021)
-     * Uses THREE.Box3 bounding box collision detection
-     *
-     * @returns true if overlap detected, false otherwise
-     * @private
-     */
-    private _checkOverlap;
-    /**
-     * Apply invalid placement visual effect (T022)
-     * Sets red emissive color to indicate invalid placement
-     *
-     * @param object - Object3D to apply effect to
-     * @private
-     */
-    private _applyInvalidEffect;
-    /**
-     * Remove invalid placement visual effect (T023)
-     * Restores normal emissive values
-     *
-     * @param object - Object3D to restore
-     * @private
-     */
-    private _removeInvalidEffect;
-    /**
-     * Handle gridPosition move events (T016, T024)
-     * Updates preview position with grid snapping and checks for overlap
-     *
-     * @param worldPosition - Current cursor position in world coordinates (already grid-snapped)
-     */
-    handleGridPositionMove(worldPosition: THREE.Vector3): void;
-    /**
-     * Handle pointer down events for component placement or selection (T017, T019, T026, T027, T042)
-     * - If clicking on existing component: select it
-     * - If clicking empty space: place component at preview position
-     *
-     * @param worldPosition - Click position in world coordinates
-     */
-    handlePointerDown(worldPosition: THREE.Vector3): void;
-    /**
-     * Handle scroll events for rotation (User Story 3 - Phase 5)
-     * Rotates preview by 90 degrees per scroll
-     *
-     * @param delta - Scroll delta (positive = scroll down, negative = scroll up)
-     * @param ctrlKey
-     */
-    handleScroll(delta: number, ctrlKey: boolean): void;
-    /**
-     * Handle keyboard events for component deletion (T035-T039)
-     * Deletes selected component when Delete or Backspace key is pressed
-     *
-     * @param event - Keyboard event
-     */
-    handleKeyDown(event: KeyboardEvent): void;
-    /**
-     * Get current cursor type based on tool state (T018, T043)
-     * Returns cursor based on hover state:
-     * - 'pointer' when hovering existing component
-     * - 'not-allowed' when hovering over occupied space for placement
-     * - 'crosshair' otherwise
-     *
-     * @returns Current cursor style
-     */
-    getCursorType(): CursorType;
-}
-
 /**
  * Visual factory for Battery components
  *
@@ -343,7 +212,8 @@ export declare class AddComponentTool implements IEditingTool {
  * - Component hitbox for raycasting
  */
 export declare class BatteryVisualFactory extends ComponentVisualFactoryBase {
-    createVisual(component: Component): THREE.Object3D;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
 }
 
 /**
@@ -369,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.
      *
@@ -417,26 +287,10 @@ declare class BehaviorRegistry {
 }
 
 /**
- * Result returned by component behavior evaluation.
- * Describes state changes and future events to schedule.
- *
- * @public
+ * Sentinel value representing the "Branching Point" pseudo-component entry.
+ * When selected, BuildTool creates a branching point instead of a component.
  */
-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>;
-}
+export declare const BRANCHING_POINT_SENTINEL: "__branching_point__";
 
 /**
  * Factory for creating branching point visuals.
@@ -507,11 +361,16 @@ export declare class BuildTool implements IEditingTool {
     private _controller;
     private mode;
     private lastCancelledOp;
+    private lastOperationCompletedTs;
     private wireCreationState;
     private wireDragState;
     private componentDragState;
     private bpDragState;
     private clipboard;
+    private pickerWidget;
+    private ghostPreview;
+    private hasOverlap;
+    private pickerSelection;
     /**
      * Construct a new BuildTool instance
      * @param controller - The circuit scene controllerType instance
@@ -715,6 +574,52 @@ export declare class BuildTool implements IEditingTool {
      * @param event - Mouse event for screen position
      */
     private openConfigPanel;
+    /**
+     * Enter add_component mode: open the picker widget and listen for cursor movement
+     * @param event - Mouse event (used for widget positioning)
+     */
+    private enterAddComponentMode;
+    /**
+     * Exit add_component mode: close widget, dispose ghost, return to idle
+     */
+    private exitAddComponentMode;
+    /**
+     * Called when user selects or deselects an item in the picker widget
+     */
+    private onPickerSelectionChange;
+    /**
+     * Place the currently selected item (component or branching point) at cursor position
+     */
+    private placeSelectedItem;
+    /**
+     * Update ghost preview position and overlap check during add_component mode
+     */
+    private updateAddComponentPreview;
+    /**
+     * Create ghost preview for the selected item
+     * @param selection - Component type or branching point sentinel
+     */
+    private createGhostPreview;
+    /**
+     * Dispose ghost preview and cleanup resources
+     */
+    private disposeGhostPreview;
+    /**
+     * Apply semi-transparent ghost effect to preview object
+     */
+    private applyGhostEffect;
+    /**
+     * Check if ghost preview overlaps with existing components
+     */
+    private checkGhostOverlap;
+    /**
+     * Apply red emissive to indicate invalid placement
+     */
+    private applyInvalidEffect;
+    /**
+     * Remove red emissive invalid placement effect
+     */
+    private removeInvalidEffect;
 }
 
 /**
@@ -861,7 +766,7 @@ declare class Circuit {
     /**
      * Create a new empty circuit.
      */
-    constructor(name?: string);
+    constructor(options: CircuitOptions);
     get name(): string;
     set name(value: string);
     /**
@@ -892,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.
      *
@@ -1174,6 +1086,7 @@ declare class Circuit {
      * iterate through all components, enodes and wires positions to get the size that allows to enclose all elements.
      * @param margin - optional margin to add to the size
      * @returns size that allows to enclose all elements plus margin
+     * @todo if calls to this method at each build operation ends causes slowness see to optimize by restricting checked elements
      */
     getEnclosingSize(margin?: number): number;
     /**
@@ -1187,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.
      *
@@ -1207,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;
 }
 
 /**
@@ -1297,15 +1200,6 @@ export declare class CircuitController extends AbstractCircuitController {
      */
     toggleTool(toolType: ToolType): void;
     deactivateTool(toolType: ToolType): void;
-    /**
-     * Get the list of available component types for the AddComponent tool
-     */
-    getAvailableComponentTypes(): ComponentType[];
-    /**
-     * Set the component type for the AddComponent tool
-     * @param componentType
-     */
-    setAddComponentType(componentType: ComponentType | null): void;
     /**
      * Get the currently active tool (FR-028)
      *
@@ -1380,12 +1274,12 @@ export declare class CircuitController extends AbstractCircuitController {
      *
      * @param type - Component type to add
      * @param worldPosition - Position in 3D world coordinates (x, z)
-     * @param rotation - 3D world rotation
+     * @param rotation - 3D world rotation, if left null the default componentType rotation is applied
      * @param config - Optional configuration map for the component
      * @param pinSources - Optional array of source types for the component pins
      * @returns The created Component
      */
-    addComponent(type: ComponentType, worldPosition: THREE.Vector3, rotation: Euler, config?: Map<string, string> | undefined, pinSources?: Array<ENodeSourceType | undefined | null> | undefined): Component;
+    addComponent(type: ComponentType, worldPosition: THREE.Vector3, rotation: Euler | null, config?: Map<string, string> | undefined, pinSources?: Array<ENodeSourceType | undefined | null> | undefined): Component;
     /**
      * edit component config and update visuals if necessary
      *
@@ -1690,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
  *
@@ -2138,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.
      *
@@ -2154,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:
@@ -2172,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;
@@ -2218,117 +2120,23 @@ 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;
+    static fromJSON(json: IComponent): 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
+ * Describes a named group of component types
  */
-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;
+export declare interface ComponentGroup {
+    readonly id: string;
+    readonly label: string;
 }
 
 /**
@@ -2340,6 +2148,79 @@ export declare interface ComponentHitboxUserData {
     componentType: ComponentType;
 }
 
+/**
+ * Persisted widget state (survives open/close cycles within a session).
+ */
+export declare interface ComponentPickerState {
+    selectedGroupId: string;
+    selectedItem: PickerSelection | null;
+    widgetWidth: number;
+    widgetHeight: number;
+}
+
+/**
+ * DOM overlay widget for selecting components from grouped registry.
+ *
+ * Features:
+ * - Group dropdown for filtering component types
+ * - Scrollable item list with selection highlight
+ * - Draggable header bar
+ * - Resizable via CSS resize
+ * - State persistence across open/close (group, selection, size)
+ */
+export declare class ComponentPickerWidget {
+    private readonly registry;
+    private container;
+    private groupDropdown;
+    private itemList;
+    private state;
+    private readonly onSelectionChange;
+    private readonly onClose;
+    private escapeHandler;
+    private dragOffset;
+    private dragMoveHandler;
+    private dragEndHandler;
+    /**
+     * @param registry - Grouped factory registry providing groups and component types
+     * @param onSelectionChange - Called when user selects or deselects an item
+     * @param onClose - Called when user closes the widget (close button or Escape)
+     */
+    constructor(registry: IGroupedFactoryRegistry, onSelectionChange: (selection: PickerSelection | null) => void, onClose: () => void);
+    /** Whether the widget is currently open and visible */
+    get isOpen(): boolean;
+    /** The currently selected item (persists across open/close) */
+    get currentSelection(): PickerSelection | null;
+    /**
+     * Open the widget at the given screen position.
+     * If already open, repositions to the new location.
+     *
+     * @param screenPosition - Screen coordinates (typically from mouse event)
+     */
+    open(screenPosition: {
+        x: number;
+        y: number;
+    }): void;
+    /**
+     * Close the widget and remove DOM.
+     * Preserves state (group, selection, size) for next open.
+     */
+    close(): void;
+    /**
+     * Full cleanup including state reset.
+     */
+    dispose(): void;
+    private createDOM;
+    private renderItemList;
+    private createItemElement;
+    private selectItem;
+    private positionContainer;
+    private startDrag;
+    private onDragMove;
+    private endDrag;
+    private registerEventListeners;
+    private removeEventListeners;
+}
+
 /**
  * Base class for component simulation state.
  * Extended by specific component types (BatteryState, LEDState, etc.)
@@ -2374,29 +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",
     SmallLED = "smallLED",
     RectangleLED = "rectangleLED",
-    Cube = "cube",// no pins component for testing purposes mainly
-    Label = "label"
+    Inverter = "inverter",
+    NandGate = "nandGate",
+    Nand4Gate = "nand4Gate",
+    Nand8Gate = "nand8Gate",
+    NorGate = "norGate",
+    Nor4Gate = "nor4Gate",
+    Nor8Gate = "nor8Gate",
+    XorGate = "xorGate",
+    Xor4Gate = "xor4Gate",
+    Xor8Gate = "xor8Gate"
 }
 
 /**
@@ -2420,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;
@@ -2438,11 +2321,12 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
     protected static readonly DEFAULT_SELECTION_COLOR = 16746496;
     /** Default selection emissive intensity (higher than hover) */
     protected static readonly DEFAULT_SELECTION_INTENSITY = 0.8;
+    defaultRotation(): number;
     /**
      * 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
      */
@@ -2479,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
      *
@@ -2487,19 +2375,36 @@ 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): 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
+     * @param label
+     */
+    findPinVisual(object3D: THREE.Object3D, label: string): THREE.Mesh | null;
     /**
      * Create component hitbox mesh
      *
@@ -2517,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;
@@ -2554,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)
      *
@@ -2592,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;
 }
 
 /**
@@ -2610,7 +2517,7 @@ export declare type ControllerCallback<T = any> = (payload: T) => void;
 /**
  * Supported scene controllerType event types (includes tool system events)
  */
-export declare type ControllerEvent = 'ready' | 'error' | 'circuitLoaded' | 'circuitCleared' | 'gridPositionMove' | 'hover' | 'unhover' | 'select' | 'deselect' | 'toolActivated' | 'toolDeactivated' | 'toolOperationStarted' | 'toolOperationCompleted' | 'toolOperationCancelled' | 'toolValidationError' | 'addComponentTypeChanged' | 'cursorChangeRequested' | 'circuitElementAction' | 'circuitMetadataEdition' | 'selectionChange' | 'simulationPlayed' | 'simulationPaused' | 'simulationStepped' | 'simulationTick' | 'simulationUserCommand' | 'simulationStopped' | 'simulationSpeedChanged';
+export declare type ControllerEvent = 'ready' | 'error' | 'circuitLoaded' | 'circuitCleared' | 'gridPositionMove' | 'hover' | 'unhover' | 'select' | 'deselect' | 'toolActivated' | 'toolDeactivated' | 'toolOperationStarted' | 'toolOperationCompleted' | 'toolOperationCancelled' | 'toolValidationError' | 'cursorChangeRequested' | 'circuitElementAction' | 'circuitMetadataEdition' | 'selectionChange' | 'simulationPlayed' | 'simulationPaused' | 'simulationStepped' | 'simulationTick' | 'simulationUserCommand' | 'simulationStopped' | 'simulationSpeedChanged';
 
 /**
  * Event payload map for type-safe event emission
@@ -2688,9 +2595,6 @@ export declare interface ControllerEventMap {
         mode: unknown;
         errorMessage: string;
     };
-    addComponentTypeChanged: {
-        componentType: ComponentType | null;
-    };
     cursorChangeRequested: {
         cursorType: CursorType;
     };
@@ -2719,7 +2623,7 @@ export declare interface ControllerEventMap {
         tick: number;
         dirty: unknown;
     };
-    simulationUserCommand: UserCommand;
+    simulationUserCommand: IUserCommand;
     simulationStopped: {
         tick: number;
     };
@@ -2809,30 +2713,103 @@ export declare class DefaultVisualFactory extends ComponentVisualFactoryBase {
 }
 
 /**
- * Operating mode of the CircuitEngine
- * - 'edit': Static circuit editing mode (tools, selection, manipulation)
- * - 'simulation': Live simulation mode (playback, animation, user commands)
+ * convenience to control standard rotations of meshes on X-Z plan
  */
-export declare type EngineMode = 'edit' | 'simulation';
+declare type Direction2D = 'right' | 'bottom' | 'left' | 'top';
 
 /**
- * Configuration options for CircuitEngine initialization
+ * 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 interface EngineOptions {
-    /**
-     * Initial operating mode
-     * @default 'edit'
-     */
-    initialMode?: EngineMode;
-    /**
-     * Controller options
+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
      */
-    controllerOptions?: ControllerOptions;
+    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)
+ * - 'simulation': Live simulation mode (playback, animation, user commands)
+ */
+export declare type EngineMode = 'edit' | 'simulation';
+
+/**
+ * Configuration options for CircuitEngine initialization
+ */
+export declare interface EngineOptions {
+    /**
+     * Initial operating mode
+     * @default 'edit'
+     */
+    initialMode?: EngineMode;
+    /**
+     * Controller options
+     */
+    controllerOptions?: ControllerOptions;
     /**
      * Options passed to CircuitRunner when created
      * @default { enableHistory: false }
      */
-    runnerOptions?: RunnerOptions;
+    runnerOptions?: IRunnerOptions;
 }
 
 /**
@@ -2911,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.
      *
@@ -2923,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)
@@ -2944,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.
      *
@@ -3011,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.
      *
@@ -3040,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;
 }
 
 /**
@@ -3063,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
@@ -3113,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 {
     /**
@@ -3321,6 +3246,114 @@ export declare class FactoryRegistry implements IFactoryRegistry {
     getRegisteredTypes(): ComponentType[];
 }
 
+/**
+ * Factory registry with named group support.
+ *
+ * Implements both IFactoryRegistry (backward compat) and IGroupedFactoryRegistry.
+ * Components may only be registered inside a group context via addGroup().
+ *
+ * Group insertion order is preserved (Map maintains insertion order).
+ * Duplicate group ids merge their components; the label from the first
+ * registration is preserved.
+ *
+ * @example
+ * ```typescript
+ * const registry = new GroupedFactoryRegistry(new DefaultVisualFactory())
+ *   .addGroup('basic', 'Basic Components', group => group
+ *     .add(ComponentType.Battery, new BatteryVisualFactory())
+ *     .add(ComponentType.Switch, new SwitchVisualFactory())
+ *   )
+ *   .addGroup('outputs', 'Output Components', group => group
+ *     .add(ComponentType.Lightbulb, new LightbulbVisualFactory())
+ *   );
+ *
+ * registry.getGroups();                        // [{ id: 'basic', ... }, { id: 'outputs', ... }]
+ * registry.getGroupOf(ComponentType.Battery);  // { id: 'basic', label: 'Basic Components' }
+ * registry.getRegisteredTypes('basic');        // [ComponentType.Battery, ComponentType.Switch]
+ * registry.get(ComponentType.Battery);         // BatteryVisualFactory instance
+ * ```
+ */
+export declare class GroupedFactoryRegistry implements IFactoryRegistry, IGroupedFactoryRegistry {
+    private readonly _factories;
+    private readonly _fallbackFactory;
+    private readonly _groups;
+    private readonly _typeToGroupId;
+    /**
+     * Create a new grouped factory registry.
+     *
+     * @param fallbackFactory - Factory to use for unregistered component types
+     * @throws {TypeError} If fallbackFactory is null or undefined
+     */
+    constructor(fallbackFactory: IComponentVisualFactory);
+    /**
+     * Add a named group and register component factories within it.
+     *
+     * If a group with the same id already exists, the new components are merged
+     * into it and the original label is preserved.
+     *
+     * @param id - Unique group identifier
+     * @param label - Human-readable group display name
+     * @param builderCallback - Callback receiving a builder for adding components
+     * @throws {TypeError} If id or label is empty/whitespace
+     * @returns this (for chaining)
+     */
+    addGroup(id: string, label: string, builderCallback: (group: IComponentGroupBuilder) => void): this;
+    /**
+     * Retrieve the factory for a component type.
+     *
+     * @returns Factory, or the fallback factory if type not registered.
+     * Never returns null or undefined.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type.
+     *
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered types.
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Get all defined groups in insertion order.
+     *
+     * @returns New array of ComponentGroup objects (safe to mutate)
+     */
+    getGroups(): ComponentGroup[];
+    /**
+     * Get the group a component type belongs to.
+     *
+     * @param type - Component type to look up
+     * @returns ComponentGroup, or undefined if type is not registered
+     */
+    getGroupOf(type: ComponentType): ComponentGroup | undefined;
+    /**
+     * Get registered component types, optionally filtered by group.
+     *
+     * @param groupId - If provided, returns only types in that group
+     * @returns New array of ComponentType values (safe to mutate).
+     *          Returns empty array if groupId is unknown.
+     */
+    getRegisteredTypes(groupId?: string): ComponentType[];
+    /**
+     * Unregister a factory for a component type.
+     *
+     * The type is removed from its group's list and from the reverse lookup.
+     * The group record itself is preserved even if it becomes empty.
+     *
+     * @param type - Component type to remove
+     * @returns true if factory was registered and removed, false otherwise
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Not supported. Use addGroup() to register components within a named group.
+     *
+     * @throws {Error} Always throws
+     */
+    register(_type: ComponentType, _factory: IComponentVisualFactory): IFactoryRegistry;
+}
+
 /**
  * Three.js layer assignments for hitbox meshes and rendering
  *
@@ -3533,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;
@@ -3541,13 +3604,125 @@ 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().
+ *
+ * @example
+ * ```typescript
+ * registry.addGroup('basic', 'Basic Components', (group: IComponentGroupBuilder) => {
+ *   group
+ *     .add(ComponentType.Battery, new BatteryVisualFactory())
+ *     .add(ComponentType.Switch, new SwitchVisualFactory());
+ * });
+ * ```
+ */
+export declare interface IComponentGroupBuilder {
+    add(type: ComponentType, factory: IComponentVisualFactory): IComponentGroupBuilder;
+}
+
 /**
  * Interface for component visual factories
  *
@@ -3560,7 +3735,7 @@ declare type ICircuitMetadata = {
  * @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;
@@ -3571,10 +3746,15 @@ declare type ICircuitMetadata = {
  * ```
  */
 export declare interface IComponentVisualFactory {
+    /**
+     * @returns nominal rotation along the Y axis when component added (angle in radian)
+     */
+    defaultRotation(): number;
     /**
      * 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
@@ -3585,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
      *
@@ -3673,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)
      *
@@ -3764,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
  *
@@ -3785,15 +3979,6 @@ export declare interface IEditingTool {
  * ```
  */
 export declare interface IFactoryRegistry {
-    /**
-     * Register a visual factory for a specific component type
-     *
-     * @param type - Component type identifier
-     * @param factory - Factory (class instance or function) to create visuals for this type
-     * @throws {TypeError} If factory is null or undefined
-     * @returns This IFactoryRegistry instance (for chaining)
-     */
-    register(type: ComponentType, factory: IComponentVisualFactory): IFactoryRegistry;
     /**
      * Retrieve the factory for a component type
      *
@@ -3835,19 +4020,241 @@ export declare interface IFactoryRegistry {
 }
 
 /**
- * 3D Position Type
- *
- * Represents a 3D position. Used for:
- * - Camera placement
+ * Extended registry interface with grouping support.
  *
- * @module core/types/Position3D
+ * Adds group management on top of the basic factory retrieval,
+ * allowing client UIs to build organized component palettes.
  */
-declare type IPosition3D = {
-    x: number;
+export declare interface IGroupedFactoryRegistry {
+    addGroup(id: string, label: string, builderCallback: (group: IComponentGroupBuilder) => void): IGroupedFactoryRegistry;
+    get(type: ComponentType): IComponentVisualFactory;
+    has(type: ComponentType): boolean;
+    getFallbackFactory(): IComponentVisualFactory;
+    getGroups(): ComponentGroup[];
+    getGroupOf(type: ComponentType): ComponentGroup | undefined;
+    getRegisteredTypes(groupId?: string): ComponentType[];
+    unregister(type: ComponentType): boolean;
+}
+
+/**
+ * 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
+ *
+ * Creates:
+ * - Inverter triangle or Buffer trapezoid 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 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;
     y: number;
     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
  *
@@ -3886,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
      *
@@ -4015,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
      *
@@ -4060,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
  **/
@@ -4289,37 +4700,291 @@ export declare class MultiSelectTool implements IEditingTool {
      * 2. Selected components (cascades to connected wires)
      * 3. Selected branching points
      */
-    deleteSelection(): boolean;
-}
-
-/**
- * Operating modes for the MultiSelectTool
- */
-export declare type MultiSelectToolMode = 'idle' | 'selecting' | 'dragging';
-
-/**
- * Binary electrical state for wires and enodes (connection points)
- * @module core/simulation/states
- */
-declare interface NodeElectricalState {
+    deleteSelection(): boolean;
+}
+
+/**
+ * Operating modes for the MultiSelectTool
+ */
+export declare type MultiSelectToolMode = 'idle' | 'selecting' | 'dragging';
+
+/**
+ * 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 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;
+    /**
+     * 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
+     */
+    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 NOR 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 Nor4GateVisualFactory extends NorGateVisualFactory {
+    /** 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 NOR 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 Nor8GateVisualFactory extends NorGateVisualFactory {
+    /** 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 NOR 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 NorGateVisualFactory 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;
+    /**
+     * 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;
     /**
-     * True if voltage is present at this node (potential > 0V).
-     * False if node is at ground potential or floating.
+     * 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;
 }
 
+/**
+ * Union of actual component types and the branching point sentinel.
+ */
+export declare type PickerSelection = ComponentType | typeof BRANCHING_POINT_SENTINEL;
+
 /**
  * Position Type for 2D Discrete Grid
  *
@@ -4328,7 +4993,7 @@ declare interface NodeElectricalState {
  * - Branching point ENode positions
  * - Wire intermediate waypoints
  *
- * @module core/types/Position
+ * @module core/utils
  */
 /**
  * Position on a 2D discrete grid with integer coordinates.
@@ -4510,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)
      *
@@ -4568,37 +5234,58 @@ export declare class RectangleLEDVisualFactory extends ComponentVisualFactoryBas
 }
 
 /**
- * Register all basic component visual factories in the given registry
- * Basic components are : Battery, Lightbulb, RectangleLED, Relay, SmallLED, Switch, Transistor
+ * Register all basic components visual factories in the basic group
+ * 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
+ */
+export declare function registerBasicComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
+
+/**
+ * Register all logic gates components visual factories in the gates group
+ * 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
- * @return the input factory registry for chaining
+ * @param registry - A grouped factory registry to populate
+ * @returns The input registry for chaining
  */
-export declare function registerBasicComponentsFactories(registry: IFactoryRegistry): IFactoryRegistry;
+export declare function registerGatesComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
 
 /**
  * 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)
      *
@@ -4643,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
@@ -4651,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.
@@ -4739,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
  *
@@ -4999,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)
      *
@@ -5072,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)
      *
@@ -5131,128 +5765,27 @@ export declare class SwitchVisualFactory extends ComponentVisualFactoryBase {
  *
  * Note: 'build' replaces the previous tools: 'position', 'wire', 'delete', 'branchingPoint'
  */
-export declare type ToolType = 'build' | 'addComponent' | 'multiSelect';
+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 lit (based on simulation state)
+ * core utilities types definitions
+ * @module core/utils
  */
-export declare class TransistorVisualFactory extends ComponentVisualFactoryBase {
-    /** Transistor lit color (yellow glow) */
-    private static readonly TRANSISTOR_CLOSED_COLOR;
-    /** Transistor lit 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;
-    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;
-}
-
 /**
- * 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
+ * Lightweight context passed to visual factories so they can access
+ * ENode data (subtype, source, wires…) when creating pin visuals.
  *
- * 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
- *
- * @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.
@@ -5361,15 +5894,7 @@ declare class Wire {
      * // }
      * ```
      */
-    toJSON(): {
-        id: UUID;
-        node1: UUID;
-        node2: UUID;
-        intermediatePositions: {
-            x: number;
-            y: number;
-        }[];
-    };
+    toJSON(): IWire;
     /**
      * Deserialize wire from JSON.
      *
@@ -5388,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;
 }
 
 /**
@@ -5644,4 +6161,146 @@ export declare class WireVisualManager {
     private clientToContainerCoords;
 }
 
+/**
+ * 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 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:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class XorGateVisualFactory extends ComponentVisualFactoryBase {
+    /** Gate high color */
+    protected static readonly HIGH_COLOR = 16777215;
+    /** Gate high emissive intensity */
+    protected static readonly HIGH_INTENSITY = 0.3;
+    /** 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 material for negative marker **/
+    protected readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    defaultRotation(): number;
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    /**
+     * Get config form definition for XOR/XNOR Gate
+     *
+     * @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
+     */
+    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;
+}
+
 export { }