simple-circuit-engine 0.0.11 → 0.0.13

package/dist/scene/simulation/CircuitRunnerController.d.ts

@@ -0,0 +1,227 @@
+import { Circuit, BehaviorRegistry } from '../../core/index.ts';
+import { IFactoryRegistry } from '../shared/components/ComponentVisualFactory';
+import { SharedResources, ControllerOptions } from '../shared/types';
+import { AbstractCircuitController } from '../shared/AbstractCircuitController';
+/**
+ * Simulation Circuit Runner Controller Implementation
+ *
+ * Manages Three.js scene for live circuit simulation visualization.
+ * Provides smooth interpolation between simulation ticks for 60fps rendering.
+ * Animates current flow through wires and component state changes.
+ */
+export declare class CircuitRunnerController extends AbstractCircuitController {
+    private _runner;
+    private _behaviorRegistry;
+    private _animationContext;
+    private _autoPlay;
+    private _isPlaying;
+    private _tickIntervalMs;
+    private _simulationLoopId;
+    private _clickHandler;
+    /**
+     * Create a new Simulation Circuit Controller
+     *
+     * @param factoryRegistry - Component visual factory registry
+     * @param behaviorRegistry - Component behavior registry
+     * @param sharedResources - Optional shared resources for facade pattern (CircuitEngine)
+     * @throws {TypeError} If factoryRegistry is null/undefined
+     */
+    constructor(factoryRegistry: IFactoryRegistry, behaviorRegistry: BehaviorRegistry, sharedResources?: SharedResources);
+    /**
+     * Check if simulation is currently playing (auto-advancing ticks)
+     * Returns false if paused or no circuit loaded
+     */
+    get isPlaying(): boolean;
+    /**
+     * Get current tick interval in milliseconds
+     * Default is 500ms (2 ticks per second)
+     */
+    get tickInterval(): number;
+    /**
+     * Set tick interval in milliseconds (50-2000ms)
+     * If simulation is playing, restarts the interval with new value
+     *
+     * @param value - Interval in milliseconds, must be between 50-2000ms
+     * @throws {RangeError} If value is outside valid range
+     */
+    set tickInterval(value: number);
+    /**
+     * Get current simulation speed in ticks per second.
+     * Range: 1-20 TPS
+     */
+    get simulationSpeed(): number;
+    /**
+     * Set simulation speed in ticks per second.
+     * Value is clamped to range 1-20 TPS.
+     * If simulation is playing, restarts the interval with new value.
+     * Emits 'simulationSpeedChanged' event when speed changes.
+     *
+     * @param tps - Ticks per second (1-20)
+     */
+    set simulationSpeed(tps: number);
+    /**
+     * Minimum allowed simulation speed in ticks per second.
+     */
+    get minSimulationSpeed(): number;
+    /**
+     * Maximum allowed simulation speed in ticks per second.
+     */
+    get maxSimulationSpeed(): number;
+    /**
+     * Compute the number of ticks required for a transition given its duration in milliseconds.
+     * Formula: ceil(transitionUserSpanMs × simulationSpeed / 1000), minimum 1.
+     *
+     * @param transitionUserSpanMs - Transition duration in milliseconds
+     * @returns Number of ticks for the transition (minimum 1)
+     */
+    computeTickCount(transitionUserSpanMs: number): number;
+    /**
+     * Get the transition duration from component config for user-driven transitions.
+     * @param config - Component config map
+     * @returns Transition duration in milliseconds (defaults to TRANSITION_USER_SPAN_MS)
+     */
+    private _getTransitionUserSpan;
+    /**
+     * Get current simulation tick number
+     * Returns 0 if no circuit runner is loaded
+     */
+    get currentTick(): number;
+    /**
+     * Specific Initialization logic, performed after AbstractCircuitController initialization
+     * @private
+     *
+     * @param options - Controller options passed to initialize()
+     */
+    protected onInitialize(options?: ControllerOptions): void;
+    protected emitReady(): 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;
+    /**
+     * Play automatic simulation playback
+     * Simulation will advance at the configured tick interval until paused
+     *
+     * Requires a circuit runner to be loaded via setCircuitRunner()
+     * Emits 'simulationPlayed' event on play
+     * Emits 'simulationTick' event on each tick
+     */
+    play(): void;
+    /**
+     * Pause automatic simulation playback
+     * Safe to call even if already paused or no circuit loaded
+     *
+     * Emits 'simulationPaused' event
+     */
+    pause(): void;
+    /**
+     * Execute a single simulation tick
+     * Simulation remains paused after step, useful for debugging
+     *
+     * If currently playing, pauses first then steps
+     * Requires a circuit runner to be loaded via setCircuitRunner()
+     * Emits 'simulationStepped' event with tick result
+     */
+    step(): void;
+    /**
+     * Stop the simulation, reset visual to initial state
+     * Simulation remains paused after step, useful for debugging
+     *
+     * If currently playing, pauses first then steps
+     * Requires a circuit runner to be loaded via setCircuitRunner()
+     * Emits 'simulationStopped' event with tick result (0)
+     */
+    stop(): void;
+    /**
+     * Execute one simulation tick and update visuals
+     * @private
+     */
+    private _executeTick;
+    /**
+     * Update component animations for dirty components
+     * @private
+     */
+    private _updateDirtyComponents;
+    /**
+     * Update all active AnimationMixers.
+     * Called per frame from the render loop via CircuitEngine.update(delta).
+     *
+     * @param delta - Time in seconds since last frame
+     */
+    updateAnimations(delta: number): void;
+    /**
+     * Recompute animation timescales when simulation speed changes mid-animation.
+     * Updates ticksPerSecond on userData and adjusts active action timeScales.
+     */
+    private _updateAnimationTimescales;
+    /**
+     * Update wire visual state based on electrical state
+     * @private
+     */
+    private _updateDirtyWires;
+    /**
+     * Update enode visual state based on electrical state
+     * Applies emissive glow to pins and branching points
+     * @private
+     */
+    private _updateDirtyEnodes;
+    /**
+     * rollback wires/enodes/components visuals to edition state (no simulation state)
+     */
+    _removeSimulationStateVisuals(): void;
+    /**
+     * Handle click events for component interaction
+     * @param event
+     * @private
+     */
+    private _handleClick;
+    /**
+     * Handle regular click events : emit user commands to the runner
+     * @param clickedElement
+     * @private
+     */
+    private _handleRegularClick;
+    private _handleCtrlClick;
+    /**
+     * recreate all visuals based on circuit data
+     * Should be called on an already cleared scene
+     *
+     * When using shared resources (CircuitEngine facade), skips visual creation
+     * if visuals already exist in the shared maps (created by edit controller).
+     * @private
+     */
+    private _fullUpdate;
+    /**
+     * Consider all elements as dirty to update all visual state according to simulation state
+     * @private
+     */
+    private _visualUpdateFromSimulationState;
+    private _createComponentObject3D;
+    /**
+     * Index component mesh and its pins meshes for interaction (hover, selection)
+     * @param componentId
+     * @param object3D
+     * @private
+     */
+    private _indexComponentObject3D;
+    /**
+     * 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 _createWireObject3D;
+    private _removeComponentObject3D;
+    private _removeEnodeObject3D;
+    private _removeWireObject3D;
+    protected _removeAllVisuals(): void;
+}

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

@@ -0,0 +1,228 @@
+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);
+    setLanguage(lng: string): void;
+    /**
+     * 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,31 @@
+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;
+    /**
+     * Signal a language change — hides any open tooltip so the next hover
+     * recreates it with updated translations.
+     */
+    setLanguage(_lng: string): void;
+    dispose(): void;
+    private _position;
+}