simple-circuit-engine 0.0.11 → 0.0.12

package/dist/scene/static/CircuitController.d.ts

@@ -0,0 +1,227 @@
+import { Euler } from 'three';
+import { Component, Wire, ENode, UUID, ComponentType, ENodeSourceType, Circuit } from '../../core/index.ts';
+import { IFactoryRegistry } from '../shared/components/ComponentVisualFactory';
+import { ToolType, SharedResources, ControllerOptions } from '../shared/types';
+import { SelectionManager } from '../shared/SelectionManager';
+import { CircuitWriter } from './CircuitWriter';
+import { AbstractCircuitController } from '../shared/AbstractCircuitController';
+/**
+ * Static Circuit Controller for editing circuits
+ * @module scene/static/CircuitController
+ *
+ * Manages static circuit THREE.js scene with support for editing tools.
+ */
+import * as THREE from 'three';
+/**
+ * Static Circuit Controller Implementation
+ *
+ * Manager providing a bidirectional interface between a Circuit and a Three.js scene/camera ready to be rendered.
+ * Supports view manipulation and editing via integrated tool system.
+ * Provides event hooks for error handling and state changes.
+ */
+export declare class CircuitController extends AbstractCircuitController {
+    private _editMode;
+    readonly circuitWriter: CircuitWriter;
+    private _selectionManager;
+    private _configPanelManager;
+    private _pinTooltipWidget;
+    private _lastClientX;
+    private _lastClientY;
+    private _tooltipMouseMoveHandler;
+    private _tools;
+    private _activeTool;
+    /**
+     * Constructor and initialization
+     */
+    /**
+     * Create a new Static Circuit Controller
+     *
+     * @param factoryRegistry - Component visual factory registry
+     * @param sharedResources - Optional shared resources for facade pattern (CircuitEngine)
+     * @throws {TypeError} factoryRegistry is null/undefined
+     */
+    constructor(factoryRegistry: IFactoryRegistry, sharedResources?: SharedResources);
+    /**
+     * Specific Initialization logic, performed after AbstractCircuitController initialization
+     * @private
+     */
+    protected onInitialize(_options?: ControllerOptions): void;
+    protected emitReady(): void;
+    /**
+     * Enable or disable edit mode (FR-006, FR-027)
+     * When disabled, deactivates any active tool and resets tool state
+     *
+     * @param enabled - True to enable edit mode, false to disable
+     */
+    setEditMode(enabled: boolean): void;
+    /**
+     * specific disposal prepended at the beginning of dispose process
+     */
+    protected onDispose(): void;
+    onSetActive(active: boolean): void;
+    setCircuit(circuit: Circuit | null): void;
+    /**
+     * specific logic when to render a new set circuit
+     * @protected
+     */
+    protected onSetCircuit(): void;
+    /**
+     * Get the SelectionManager instance for direct manipulation
+     * @returns SelectionManager
+     */
+    getSelectionManager(): SelectionManager;
+    private handlePointerDown;
+    private _applySelectionVisual;
+    private _initializeSelectionManager;
+    /**
+     * Initialize ConfigPanelManager (T013)
+     * @private
+     */
+    private _initializeConfigPanelManager;
+    private _initializePinTooltip;
+    private _disposePinTooltip;
+    /**
+     * Open the config panel for a component (T014)
+     *
+     * @param componentId - UUID of the component to edit
+     * @param screenPosition - Screen coordinates for panel positioning
+     * @returns true if panel opened, false if component has no config
+     */
+    openConfigPanel(componentId: UUID, screenPosition: {
+        x: number;
+        y: number;
+    }): boolean;
+    /**
+     * Tool System Methods
+     */
+    /**
+     * Convenience method that toggle a tool on if it is off (possibly deactivating previous tool), or off if it is on
+     * @param toolType
+     */
+    toggleTool(toolType: ToolType): void;
+    deactivateTool(toolType: ToolType): void;
+    /**
+     * Get the currently active tool (FR-028)
+     *
+     * @returns Current tool type or null if no tool is active
+     */
+    getActiveTool(): ToolType | null;
+    /**
+     * Set the active editing tool (FR-026, FR-028, FR-034)
+     * Only one tool can be active at a time
+     * Switching tools will deactivate the previous tool
+     *
+     * @param toolType - Type of tool to activate
+     * @throws {Error} If edit mode is not enabled
+     */
+    setActiveTool(toolType: ToolType): void;
+    /**
+     * Initialize editing tools
+     * @private
+     */
+    private _initializeTools;
+    /**
+     * recreate all visuals based on circuit data
+     * Should be called on an already cleared scene
+     * @private
+     */
+    private _fullUpdate;
+    private _createComponentObject3D;
+    /**
+     * Index component mesh and its pins meshes for interaction (hover, selection)
+     * @param componentId
+     * @param object3D
+     * @private
+     */
+    private _indexComponentObject3D;
+    private _removeComponentObject3D;
+    /**
+     * Create enode (branching point ONLY) visual object and add to scene
+     * pin enodes are created and attache to their components by createComponentObject3D()
+     *
+     * @param enode
+     * @private
+     */
+    private _createEnodeObject3D;
+    private _removeEnodeObject3D;
+    addBranchingPoint(worldPosition: THREE.Vector3, sourceType?: ENodeSourceType | undefined): ENode;
+    /**
+     * Split wire either :
+     * - at a position, inserting a new branching point and two new wires replacing the deleted ones
+     * - at an existing target enode, replacing the wire by two new wires connected to this enode
+     * @param wireId
+     * @param worldPosition - world Position for the new branching point : no effect if targetEnodeId provided
+     * @param targetEnodeId - if provided, the existing enode to split the wire at
+     */
+    splitWire(wireId: UUID, worldPosition: THREE.Vector3, targetEnodeId?: UUID | null): {
+        branchingPoint: ENode;
+        wires: Wire[];
+    };
+    /**
+     * Remove branching point enode visual and update the circuit and visuals
+     * @param enodeId
+     */
+    removeBranchingPoint(enodeId: UUID): void;
+    private _createWireObject3D;
+    /**
+     * add a wire between two enodes : update the circuit and add visuals
+     * @param sourceEnodeId
+     * @param targetEnodeId
+     */
+    addWire(sourceEnodeId: UUID, targetEnodeId: UUID): Wire;
+    /**
+     * Add a component to the circuit and scene
+     *
+     * @param type - Component type to add
+     * @param worldPosition - Position in 3D world coordinates (x, z)
+     * @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 | null, config?: Map<string, string> | undefined, pinSources?: Array<ENodeSourceType | undefined | null> | undefined): Component;
+    /**
+     * edit component config and update visuals if necessary
+     *
+     * @param componentId
+     * @param newConfig - map of parameters to be merged into the current config
+     */
+    editComponentConfig(componentId: UUID, newConfig: Map<string, string>): void;
+    /**
+     * cycle component config and update visuals if necessary
+     * have effect only on components that supports fast config cycle (used to invert logic or initial state of switches)
+     * else use editComponentConfig
+     *
+     * @returns if the component has changed config
+     * @param componentId
+     */
+    cycleComponentConfig(componentId: UUID): boolean;
+    /**
+     * Remove a component from the circuit and scene
+     *
+     * @param componentId - UUID of the component to remove
+     */
+    removeComponent(componentId: UUID): void;
+    /**
+     * Update an enode based to a new source type.
+     * @param enodeId - UUID of the enode
+     * @param sourceType - New source type (null for no source)
+     */
+    updateEnodeSourceType(enodeId: UUID, sourceType: ENodeSourceType | null): void;
+    /**
+     * Remove wire visual and update the circuit
+     * @param wireId
+     */
+    removeWire(wireId: UUID): void;
+    /**
+     * Automatically adjust the circuit grid size and divisions based on positions of all core circuit elements.
+     */
+    autoAdjustCircuitGridSize(): void;
+    /**
+     * Hook called before exporting the circuit visualization.
+     * Saves world informations such as camera position, in the circuit metadata.
+     */
+    beforeExport(): void;
+    private _removeWireObject3D;
+    protected _removeAllVisuals(): void;
+}

package/dist/scene/static/CircuitWriter.d.ts

@@ -0,0 +1,146 @@
+import { Euler, Object3D, Vector3 } from 'three';
+import { ENodeSourceType, UUID, ENode, Wire, Component, ComponentType } from '../../core/index.ts';
+import { CircuitController } from './CircuitController';
+/**
+ * Manages editing operations of 3D models from the circuit scene into the core circuit model.
+ */
+export declare class CircuitWriter {
+    private _controller;
+    constructor(controller: CircuitController);
+    /**
+     * add branching point to the core circuit model and emits the appropriate event.
+     * @param position - the world position to add the branching point at
+     * @param sourceType - optional source type for the branching point
+     * @throws Error
+     * @return The circuit enode
+     */
+    saveAddBranchingPoint(position: Vector3, sourceType?: ENodeSourceType | undefined): ENode;
+    /**
+     * edit branching point to the core circuit model and emits the appropriate event.
+     * @param branchingPoint - the branching point Object3D
+     * @param emit - should the event be emitted if commit OK (error event will always be)
+     * @throws Error
+     * @return The circuit enode
+     */
+    saveEditBranchingPoint(branchingPoint: Object3D, emit?: boolean): ENode;
+    /**
+     * delete branching point in the core circuit model and emits the appropriate event.
+     * @param enodeId - the branching point id
+     * @throws Error
+     * @return The circuit enode
+     */
+    saveDeleteBranchingPoint(enodeId: UUID): {
+        deletedWires?: UUID[] | undefined;
+        mergedWires?: UUID[] | undefined;
+        newWire?: Wire | undefined;
+    };
+    /**
+     * add wire to the core circuit model and emits the appropriate event.
+     * @param sourceEnodeId - the source enode ID
+     * @param targetEnodeId - the target enode ID
+     * @throws Error
+     * @return The circuit wire
+     */
+    saveAddWire(sourceEnodeId: UUID, targetEnodeId: UUID): Wire;
+    /**
+     * Save wire split operation to circuit model. Either :
+     * - at a position, inserting a new branching point and two new wires replacing the deleted ones
+     * - at an existing target enode, replacing the wire by two new wires connected to this enode
+     * @param wireId - Wire to split
+     * @param worldPosition - world Position for the new branching point : no effect if targetEnodeId provided
+     * @param targetEnodeId - if provided, the existing enode to split the wire at
+     * @returns Object containing the new branching point and two wires
+     */
+    saveSplitWire(wireId: UUID, worldPosition: Vector3, targetEnodeId?: UUID | null): {
+        branchingPoint: ENode;
+        wires: Wire[];
+    };
+    /**
+     * delete wire to the core circuit model and emits the appropriate event.
+     * @param wireId - the wire ID
+     * @throws Error
+     * @return The circuit wire
+     */
+    saveDeleteWire(wireId: UUID): void;
+    /**
+     * Used to commit wire edits (intermediate positions) to the core circuit model and emits the appropriate event.
+     * If emit positions are also simplified before committing.
+     * @param wireId - the wire ID
+     * @param positions
+     * @param emit
+     * @return The circuit wire
+     */
+    saveEditWirePositions(wireId: UUID, positions: Array<{
+        x: number;
+        y: number;
+    }>, emit?: boolean): Wire | undefined;
+    /**
+     * Used to simplify wire path in the core circuit model and emits the appropriate event.
+     * Notably used when end enodes move is committed.
+     * @param wireId - the wire ID
+     * @return The circuit wire
+     */
+    saveSimplifyWirePositions(wireId: UUID): Wire | undefined;
+    /**
+     * Save ENode sourceType update (T011)
+     * @param enodeId - ENode to update
+     * @param sourceType - New sourceType value
+     */
+    saveEditENodeSourceType(enodeId: UUID, sourceType: ENodeSourceType | null): void;
+    /**
+     * Add a component to the circuit model and emit the appropriate event
+     * handles conversion of world position and rotation to circuit model values
+     * @param type - Component type to add
+     * @param position - world Position
+     * @param rotation - world Rotation
+     * @param config - optional initial component configuration
+     * @param pinSources - optional array of ENode source types for each component pin
+     * @returns The created Component
+     * @throws Error if circuit is not available or component creation fails
+     */
+    saveAddComponent(type: ComponentType, position: Vector3, rotation: Euler, config?: Map<string, string> | undefined, pinSources?: Array<ENodeSourceType | undefined | null> | undefined): Component;
+    /**
+     * Save edits made to a component in the circuit model and emit the appropriate event
+     * @param componentId
+     * @param visual
+     * @param emit - should the event be emitted if commit OK (error event will always be)
+     */
+    saveEditComponent(componentId: UUID, visual: Object3D, emit?: boolean): Component;
+    /**
+     * Save edits made to a component configuration in the circuit model and emit the appropriate event
+     * @param componentId
+     * @param parameters - updated configuration parameters
+     */
+    saveEditComponentConfig(componentId: UUID, parameters: Map<string, string>): Component;
+    /**
+     * cycle component config and update visuals if necessary
+     * have effect only on components that supports fast config cycle (used to invert logic or initial state of switches)
+     * if component supports it, update the supported config item to the next value in the cycle
+     * @param componentId
+     * @returns object with hasChanged boolean and updated component
+     * @throws Error if circuit is not available or component not found
+     */
+    cycleComponentConfig(componentId: UUID): {
+        hasChanged: boolean;
+        component: Component;
+    };
+    /**
+     * Delete a component from the circuit model and emit the appropriate event
+     * @param componentId - UUID of the component to delete
+     * @returns Information about removed wires and enodes
+     * @throws Error if circuit is not available or component not found
+     */
+    saveDeleteComponent(componentId: UUID): {
+        deletedWires: UUID[];
+        deletedENodes: UUID[];
+    };
+    /**
+     * Automatically adjust the circuit size and divisions based on positions of all core circuit elements.
+     * @return if the size/division has been updated or not
+     */
+    saveAutoAdjustCircuitSize(): boolean;
+    /**
+     * Save current camera parameters, position and target into circuit metadata
+     */
+    saveCameraOptions(): void;
+}

package/dist/scene/static/PinTooltipWidget.d.ts

@@ -0,0 +1,26 @@
+import { ComponentType } from '../../core/index.ts';
+/**
+ * Manages a transient HTML tooltip displayed when hovering a component pin.
+ *
+ * Lifecycle: created by CircuitController on init, disposed on deactivation/disposal.
+ * Positioning: fixed, follows the raw client mouse coordinates.
+ */
+export declare class PinTooltipWidget {
+    private _element;
+    private _currentComponentType;
+    private _clickHandler;
+    private readonly _onHelpRequested;
+    constructor(onHelpRequested: (componentType: ComponentType) => void);
+    /**
+     * Show tooltip at the given client coordinates for the specified pin.
+     * If already showing for the same component type, only repositions.
+     */
+    show(pinLabel: string, componentType: ComponentType, clientX: number, clientY: number): void;
+    /** Hide and remove the tooltip element */
+    hide(): void;
+    /** Update cursor position without recreating the tooltip */
+    updatePosition(clientX: number, clientY: number): void;
+    get isVisible(): boolean;
+    dispose(): void;
+    private _position;
+}

package/dist/scene/static/tools/BuildTool.d.ts

@@ -0,0 +1,286 @@
+import { IEditingTool, ToolType, CursorType } from '../../shared/types';
+import { CircuitController } from '../CircuitController';
+/**
+ * Build Tool Implementation
+ * @module scene/static/tools/BuildTool
+ *
+ * Unified tool for all circuit editing operations:
+ * - Wire creation between endpoints
+ * - Element positioning (components, branching points, wire points)
+ * - Component rotation
+ * - Element deletion
+ * - Branching point creation
+ * - Component placement & addition (add_component mode with picker widget)
+ *
+ * Replaces old: PositionTool, WireTool, DeleteTool, BranchingPointTool, AddComponentTool
+ */
+import * as THREE from 'three';
+/**
+ * Unified tool for building circuits
+ * Implements all circuit editing functionality in a single tool
+ */
+export declare class BuildTool implements IEditingTool {
+    readonly type: ToolType;
+    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
+     */
+    constructor(controller: CircuitController);
+    /**
+     * Activate build tool and set up event listeners
+     * Resets all tool state and attaches DOM event handlers
+     */
+    onActivate(): void;
+    /**
+     * Deactivate build tool and clean up event listeners
+     * Cancels any active operations and removes all event handlers
+     */
+    onDeactivate(): void;
+    /**
+     * Cancel current ongoing operation : can be called from outside if needed
+     */
+    cancelOperation(): void;
+    /**
+     * Get the current cursor type for this tool
+     * Returns cursor based on current mode and hover state
+     */
+    getCursorType(): CursorType;
+    /**
+     * Get preview objects to render in the scene
+     * Returns array of preview objects currently visible
+     */
+    getPreviewObjects(): THREE.Object3D[];
+    /**
+     * Handle pointer down event
+     * Routes to appropriate operation based on hover target and state
+     */
+    private handlePointerDown;
+    /**
+     * Handle pointer up event
+     *
+     * Ends current operation, commits final positions to the circuit model,
+     * and re-enables camera controls.
+     *
+     * Completes current operation based on mode
+     */
+    private handlePointerUp;
+    /**
+     * Handle grid position move event according to ongoing mode
+     * Updates preview or drag position during active operations
+     */
+    private handleGridPositionMove;
+    /**
+     * Handle keyboard events
+     * Supports Escape (cancel), Delete/Backspace (delete), R (rotate), Ctrl+C (copy), Ctrl+V (paste)
+     */
+    private handleKeyDown;
+    /**
+     * Handle double-click events
+     * Routes to rotation (component) or branching point creation (wire/empty)
+     */
+    private handleDblClick;
+    /**
+     * Operations lifecycle methods
+     * (start, update, cancel, complete)
+     */
+    /**
+     * Start wire creation from source enode
+     * @param sourceEnodeId - Source enode ID
+     */
+    private startWireCreation;
+    /**
+     * Update wire creation preview with new target position
+     * @param position
+     * @private
+     */
+    private updateWireCreation;
+    /**
+     * Cancel wire creation and reset state
+     */
+    private cancelWireCreation;
+    /**
+     * Complete wire creation between source enode and :
+     * - existing target enode if it is hovered
+     * - new branching point on wire if target is a wire
+     * - new branching point if target is null
+     * @param hoveredElement - Currently hovered element at wire creation end
+     */
+    private completeWireCreation;
+    /**
+     * Start wire dragging operation
+     * @param wireId - Wire being dragged
+     * @param targetType - Type of drag target
+     * @param pointIndex - Index of intermediate point, or -1 for new/branching
+     * @param worldPosition - Initial position
+     */
+    private startWireDrag;
+    /**
+     * Update drag target position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateWireDrag;
+    /**
+     * Cancel wire drag operation and revert to original positions
+     */
+    private cancelWireDrag;
+    /**
+     * Commit drag operation and persist changes
+     */
+    private completeWireDrag;
+    /**
+     * Start component dragging operation
+     * @param componentId - UUID of the component being dragged
+     * @param worldPosition - Initial position
+     */
+    private startComponentDrag;
+    /**
+     * Update component visual position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateComponentDrag;
+    /**
+     * Cancel component drag operation and revert to original positions
+     */
+    private cancelComponentDrag;
+    /**
+     * complete component drag operation and persist changes
+     */
+    private completeComponentDrag;
+    /**
+     * Start branching point dragging operation
+     * @param enodeId - UUID of the branching point being dragged
+     * @param worldPosition - Initial position
+     */
+    private startBPDrag;
+    /**
+     * Update branching point position during drag
+     * @param worldPosition - Current cursor position in world space
+     */
+    private updateBPDrag;
+    /**
+     * Cancel branching point drag operation and revert to original positions
+     */
+    private cancelBPDrag;
+    /**
+     * Commit branching point drag operation and persist changes
+     */
+    private completeBPDrag;
+    /**
+     * private helpers
+     */
+    /**
+     * Create a standalone branching point at empty grid position (T048)
+     * @param worldPosition - 3D position in world space
+     */
+    private createStandaloneBranchingPoint;
+    /**
+     * Create a branching point on an existing wire, splitting it (T044)
+     * @param wireId - Wire to split
+     * @param worldPosition - 3D position in world space
+     */
+    private createBranchingPointOnWire;
+    /**
+     * Check if hoveredElement is a valid wire target during wire creation
+     * @param hoveredElement - Current hovered element or null
+     * @returns True if target is valid for wire endpoint
+     */
+    private isValidWireTarget;
+    /**
+     * Rotate a component 90° clockwise
+     *
+     * Updates both the circuit model and visual representation.
+     * Emits componentRotated event to notify listeners.
+     * Only works on selected components (not wires or enodes).
+     */
+    private rotateComponent;
+    /**
+     * Check if wire intermediate point should be merged or deleted
+     * Returns updated positions array after merge/delete check
+     * @param wire - Wire being modified
+     * @returns Final intermediate positions array
+     */
+    private checkMergeDelete;
+    /**
+     * Copy component type and rotation to clipboard
+     * @param componentId - UUID of the component to copy
+     */
+    private copyComponent;
+    /**
+     * Paste component from clipboard at hovered position
+     * Creates a new component with the type and rotation from clipboard
+     */
+    private pasteComponent;
+    /**
+     * Cycles the sourceType of an enode: null → Voltage → Current → null
+     * Updates both model and visual immediately.
+     * @param enodeId - UUID of the enode to cycle
+     * @param hitbox - hitbox of the enode being clicked
+     */
+    private cycleEnodeSourceType;
+    /**
+     * Open config panel for component (T014)
+     * Converts component world position to screen coordinates and opens panel
+     * @param componentId - UUID of the component to configure
+     * @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;
+}