simple-circuit-engine 0.0.9 → 0.0.10

package/dist/index.d.ts

@@ -139,7 +139,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;
     /**
@@ -202,135 +202,147 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
 }
 
 /**
- * Tool for adding new components to the circuit
- * Provides ghost preview, grid snapping, and placement validation
+ * Visual factory for AND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
  */
-export declare class 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;
+export declare class And4GateVisualFactory extends AndGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component): THREE.Object3D;
     /**
-     * Apply ghost effect to preview object (T014)
-     * Makes the preview semi-transparent to indicate it's not yet placed
+     * Get config form definition for Transistor (T026)
      *
-     * @param object - Object3D to apply ghost effect to
-     * @private
-     */
-    private _applyGhostEffect;
-    /**
-     * Dispose ghost preview and cleanup resources
-     * @private
+     * @returns Form definition with activationLogic boolean field
      */
-    private _disposeGhostPreview;
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for AND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class And8GateVisualFactory extends AndGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component): THREE.Object3D;
     /**
-     * Get preview objects to render in the scene (T015)
-     * Returns the ghost preview if available
+     * Get config form definition for Transistor (T026)
      *
-     * @returns Array containing ghost preview object
+     * @returns Form definition with activationLogic boolean field
      */
-    getPreviewObjects(): THREE.Object3D[];
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for AND gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class AndGateVisualFactory extends ComponentVisualFactoryBase {
+    /** Gate high color */
+    protected static readonly HIGH_COLOR = 16777215;
+    /** Gate high emissive intensity */
+    protected static readonly HIGH_INTENSITY = 0.3;
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared material for negative marker **/
+    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    defaultRotation(): number;
+    createVisual(component: Component): THREE.Object3D;
     /**
-     * Check if preview overlaps with existing components (T021)
-     * Uses THREE.Box3 bounding box collision detection
+     * Get config form definition for Transistor (T026)
      *
-     * @returns true if overlap detected, false otherwise
-     * @private
+     * @returns Form definition with activationLogic boolean field
      */
-    private _checkOverlap;
+    getConfigFormDefinition(): ConfigFormDefinition | null;
     /**
-     * Apply invalid placement visual effect (T022)
-     * Sets red emissive color to indicate invalid placement
+     * Map core config to form data
+     * Converts "positive"/"negative" strings to boolean
      *
-     * @param object - Object3D to apply effect to
-     * @private
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
      */
-    private _applyInvalidEffect;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
     /**
-     * Remove invalid placement visual effect (T023)
-     * Restores normal emissive values
+     * Map form data to core config
+     * Converts boolean to "positive"/"negative" strings
      *
-     * @param object - Object3D to restore
-     * @private
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
      */
-    private _removeInvalidEffect;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
     /**
-     * Handle gridPosition move events (T016, T024)
-     * Updates preview position with grid snapping and checks for overlap
+     * Update animation based on simulation state
      *
-     * @param worldPosition - Current cursor position in world coordinates (already grid-snapped)
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component current simulation state
      */
-    handleGridPositionMove(worldPosition: THREE.Vector3): void;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): 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
+     * Find the envelope mesh within the component group
      *
-     * @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 object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
      *
-     * @param delta - Scroll delta (positive = scroll down, negative = scroll up)
-     * @param ctrlKey
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
      */
-    handleScroll(delta: number, ctrlKey: boolean): void;
+    protected findEnvelopeMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
     /**
-     * Handle keyboard events for component deletion (T035-T039)
-     * Deletes selected component when Delete or Backspace key is pressed
+     * Find the negative marker mesh within the component group
      *
-     * @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
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
      *
-     * @returns Current cursor style
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
      */
-    getCursorType(): CursorType;
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
 }
 
 /**
@@ -438,6 +450,12 @@ declare interface BehaviorResult {
     readonly scheduledEvents: ReadonlyArray<ScheduledEvent>;
 }
 
+/**
+ * Sentinel value representing the "Branching Point" pseudo-component entry.
+ * When selected, BuildTool creates a branching point instead of a component.
+ */
+export declare const BRANCHING_POINT_SENTINEL: "__branching_point__";
+
 /**
  * Factory for creating branching point visuals.
  *
@@ -498,6 +516,92 @@ export declare class BranchingPointVisualFactory {
     private getColorForSourceType;
 }
 
+/**
+ * Visual factory for Buffer/Inverter components
+ *
+ * Creates:
+ * - Buffer trapezoid or Inverter triangle extrude geom mesh
+ * - Vcc, input and output pin group
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when component is high (based on simulation state)
+ */
+export declare class BufferVisualFactory extends ComponentVisualFactoryBase {
+    /** Buffer high color (white glow) */
+    private static readonly HIGH_COLOR;
+    /** Buffer high emissive intensity */
+    private static readonly HIGH_INTENSITY;
+    /** Shared low Buffer envelope geometry */
+    private readonly bufferLowGeometry;
+    /** Shared transient Buffer envelope geometry */
+    private readonly bufferTransientGeometry;
+    /** Shared high Buffer envelope geometry */
+    private readonly bufferHighGeometry;
+    /** Shared low Inverter envelope geometry */
+    private readonly inverterLowGeometry;
+    /** Shared transient Inverter envelope geometry */
+    private readonly inverterTransientGeometry;
+    /** Shared high Inverter envelope geometry */
+    private readonly inverterHighGeometry;
+    /** Shared geometry for negative marker **/
+    protected readonly negativeMarkerGeometry: THREE.SphereGeometry;
+    createVisual(component: Component): THREE.Object3D;
+    private replaceEnvelope;
+    /**
+     * Get config form definition for Buffer
+     *
+     * @returns Form definition with activationLogic boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (T026)
+     * Converts "positive"/"negative" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (T026)
+     * Converts boolean to "positive"/"negative" strings
+     *
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update Buffer animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The Buffer's current simulation state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Find the envelope mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
+     */
+    private findEnvelopeMesh;
+    /**
+     * Find the negative marker mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
+     */
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+}
+
 /**
  * Unified tool for building circuits
  * Implements all circuit editing functionality in a single tool
@@ -507,11 +611,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 +824,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;
 }
 
 /**
@@ -1174,6 +1329,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;
     /**
@@ -1297,15 +1453,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 +1527,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
      *
@@ -2331,6 +2478,14 @@ declare interface ComponentBehavior {
     onEventFiring(component: Component, state: ComponentState, event: ScheduledEvent): BehaviorResult;
 }
 
+/**
+ * Describes a named group of component types
+ */
+export declare interface ComponentGroup {
+    readonly id: string;
+    readonly label: string;
+}
+
 /**
  * UserData structure for component hitbox meshes
  */
@@ -2340,6 +2495,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.)
@@ -2388,15 +2616,23 @@ declare abstract class ComponentState {
  * ```
  */
 declare enum ComponentType {
+    Cube = "cube",// no pins component for testing purposes mainly
+    Label = "label",// decorative text label with no pins
     Battery = "battery",
     Switch = "switch",
     Lightbulb = "lightbulb",
     Relay = "relay",
     Transistor = "transistor",
+    Buffer = "buffer",
     SmallLED = "smallLED",
     RectangleLED = "rectangleLED",
-    Cube = "cube",// no pins component for testing purposes mainly
-    Label = "label"
+    AndGate = "andGate",
+    And4Gate = "and4Gate",
+    And8Gate = "and8Gate",
+    OrGate = "orGate",
+    Or4Gate = "or4Gate",
+    Or8Gate = "or8Gate",
+    XorGate = "xorGate"
 }
 
 /**
@@ -2438,6 +2674,7 @@ 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
@@ -2491,15 +2728,22 @@ declare abstract class ComponentVisualFactoryBase implements IComponentVisualFac
      * @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 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(componentId: string, pinId: string, label: string, sourceType?: ENodeSourceType | null, visualRotation?: THREE.Euler | null): THREE.Group;
     /**
      * Find pin group by label within a component Object3D
      * @param object3D
      * @param label
      */
     findPinGroup(object3D: THREE.Object3D, label: string): THREE.Group | 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
      *
@@ -2610,7 +2854,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 +2932,6 @@ export declare interface ControllerEventMap {
         mode: unknown;
         errorMessage: string;
     };
-    addComponentTypeChanged: {
-        componentType: ComponentType | null;
-    };
     cursorChangeRequested: {
         cursorType: CursorType;
     };
@@ -3321,6 +3562,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
  *
@@ -3548,6 +3897,23 @@ declare type ICircuitMetadata = {
     cameraOptions: ICameraOptions;
 };
 
+/**
+ * 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
  *
@@ -3571,6 +3937,10 @@ 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
      *
@@ -3785,15 +4155,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
      *
@@ -3834,6 +4195,23 @@ export declare interface IFactoryRegistry {
     getRegisteredTypes(): ComponentType[];
 }
 
+/**
+ * Extended registry interface with grouping support.
+ *
+ * Adds group management on top of the basic factory retrieval,
+ * allowing client UIs to build organized component palettes.
+ */
+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;
+}
+
 /**
  * 3D Position Type
  *
@@ -4320,6 +4698,155 @@ declare interface NodeElectricalState {
     locked: boolean;
 }
 
+/**
+ * Visual factory for OR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class Or4GateVisualFactory extends OrGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition for Transistor (T026)
+     *
+     * @returns Form definition with activationLogic boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for OR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class Or8GateVisualFactory extends OrGateVisualFactory {
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition for Transistor (T026)
+     *
+     * @returns Form definition with activationLogic boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}
+
+/**
+ * Visual factory for OR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class OrGateVisualFactory extends ComponentVisualFactoryBase {
+    /** Gate high color */
+    protected static readonly HIGH_COLOR = 16777215;
+    /** Gate high emissive intensity */
+    protected static readonly HIGH_INTENSITY = 0.3;
+    /** Shared open envelope geometry */
+    protected readonly lowGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly transientGeometry: THREE.ExtrudeGeometry;
+    /** Shared transient envelope geometry */
+    protected readonly highGeometry: THREE.ExtrudeGeometry;
+    /** Shared material for negative marker **/
+    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    defaultRotation(): number;
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition for OR Gate
+     *
+     * @returns Form definition with activationLogic boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     * Converts "positive"/"negative" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     * Converts boolean to "positive"/"negative" strings
+     *
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component current simulation state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Find the envelope mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
+     */
+    protected findEnvelopeMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+    /**
+     * Find the negative marker mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
+     */
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+}
+
+/**
+ * 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
  *
@@ -4568,13 +5095,23 @@ 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, Switch, Lightbulb, RectangleLED, Relay, SmallLED, Transistor
  * @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 registerBasicComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
+
+/**
+ * Register all logic gates components visual factories in the gates group
+ * gates are : AND (2,4,8,16 inputs), OR (2,4,8,16 inputs) and XOR
+ * NAND and NOR are gotten by changing the activationLogic of AND and OR
+ * @public
+ * @param registry - A grouped factory registry to populate
+ * @returns The input registry for chaining
+ */
+export declare function registerGatesComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
 
 /**
  * Visual factory for Relay components
@@ -5131,7 +5668,7 @@ 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
@@ -5142,12 +5679,12 @@ export declare type ToolType = 'build' | 'addComponent' | 'multiSelect';
  * - Component hitbox for raycasting
  *
  * Animation:
- * - Emissive glow when Transistor is lit (based on simulation state)
+ * - Emissive glow when Transistor is closed (based on simulation state)
  */
 export declare class TransistorVisualFactory extends ComponentVisualFactoryBase {
-    /** Transistor lit color (yellow glow) */
+    /** Transistor closed color (white glow) */
     private static readonly TRANSISTOR_CLOSED_COLOR;
-    /** Transistor lit emissive intensity */
+    /** Transistor closed emissive intensity */
     private static readonly TRANSISTOR_CLOSED_INTENSITY;
     /** Shared open Transistor envelope geometry */
     private readonly openGeometry;
@@ -5155,6 +5692,10 @@ export declare class TransistorVisualFactory extends ComponentVisualFactoryBase
     private readonly transientGeometry;
     /** Shared transient Transistor envelope geometry */
     private readonly closedGeometry;
+    /** Shared material for negative marker **/
+    protected static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
     createVisual(component: Component): THREE.Object3D;
     /**
      * Get config form definition for Transistor (T026)
@@ -5196,6 +5737,18 @@ export declare class TransistorVisualFactory extends ComponentVisualFactoryBase
      * 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;
 }
 
 /**
@@ -5644,4 +6197,90 @@ export declare class WireVisualManager {
     private clientToContainerCoords;
 }
 
+/**
+ * Visual factory for XOR gates components
+ *
+ * Creates:
+ * - Gate mesh
+ * - vcc, inputs and output pin groups
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Emissive glow when Gate is high (based on simulation state)
+ */
+export declare class 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 static 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 static readonly negativeMarkerMaterial: THREE.MeshStandardMaterial;
+    /** Shared geometry for negative marker **/
+    protected static readonly negativeMarkerGeometry: THREE.CylinderGeometry;
+    defaultRotation(): number;
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition for OR Gate
+     *
+     * @returns Form definition with activationLogic boolean field
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     * Converts "positive"/"negative" strings to boolean
+     *
+     * @param config - Core component config
+     * @returns Form data with boolean activationLogic
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     * Converts boolean to "positive"/"negative" strings
+     *
+     * @param formData - Form data with boolean activationLogic
+     * @returns Core config with string activationLogic
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update animation based on simulation state
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component current simulation state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Find the envelope mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The envelope mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'envelope'
+     */
+    protected findEnvelopeMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+    /**
+     * Find the negative marker mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The negative marker mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'negativeMarker'
+     */
+    protected findNegativeMarkerMesh(object3D: THREE.Object3D): (THREE.Mesh & {
+        material: THREE.MeshStandardMaterial;
+    }) | null;
+}
+
 export { }