simple-circuit-engine 0.0.10 → 0.0.12

package/dist/scene/shared/AbstractCircuitController.d.ts

@@ -0,0 +1,211 @@
+import { MapControls } from 'three/addons/controls/MapControls.js';
+import { UUID, Circuit } from '../../core/index.ts';
+import { EventEmitter } from './EventEmitter';
+import { IFactoryRegistry } from './components/ComponentVisualFactory';
+import { ControllerEventMap, ControllerOptions, HoveredElement, HoverableType, SharedResources, VisualContext } from './types';
+import { HoverManager } from './HoverManager';
+import { Line2 } from 'three/examples/jsm/lines/Line2.js';
+import { BranchingPointVisualFactory } from './BranchingPointVisualFactory';
+import { WireVisualManager } from './WireVisualManager';
+/**
+ * Abstract Circuit Controller
+ * @module scene/shared/AbstractCircuitController
+ *
+ * Base class for circuit visualization controllers.
+ * Provides common Three.js scene management, camera controls, and hover detection.
+ */
+import * as THREE from 'three';
+/**
+ * Abstract base class for circuit controllers.
+ *
+ * Provides common functionality for both static editing (CircuitController)
+ * and live simulation (CircuitRunnerController) modes:
+ * - Three.js scene, camera, and MapControls management
+ * - Container lifecycle (initialize/dispose)
+ * - Hover detection via HoverManager
+ * - Visual object tracking maps
+ *
+ * Subclasses must implement:
+ * - Circuit/CircuitRunner specific logic
+ * - Visual creation and update methods
+ * - Mode-specific features (editing tools or simulation interpolation)
+ */
+export declare abstract class AbstractCircuitController extends EventEmitter<ControllerEventMap> {
+    protected _container: HTMLElement | null;
+    protected _scene: THREE.Scene | null;
+    protected _grid: THREE.GridHelper | null;
+    protected _camera: THREE.PerspectiveCamera | null;
+    protected _mapControls: MapControls | null;
+    protected _circuit: Circuit | null;
+    readonly wireVisualManager: WireVisualManager;
+    protected _initialized: boolean;
+    protected _options: ControllerOptions | null;
+    protected _active: boolean;
+    protected _disposed: boolean;
+    protected _gridHalfSize: number;
+    readonly factoryRegistry: IFactoryRegistry;
+    readonly branchingPointVisualFactory: BranchingPointVisualFactory;
+    protected _componentObject3Ds: Map<UUID, THREE.Object3D>;
+    protected _enodeObject3Ds: Map<UUID, THREE.Object3D>;
+    protected _wireObject3Ds: Map<UUID, Line2>;
+    protected _hoverManager: HoverManager | null;
+    protected _mouseMoveHandler: ((event: MouseEvent) => void) | null;
+    protected _mouseLeaveHandler: ((event: MouseEvent) => void) | null;
+    protected _mapControlsChangeHandler: (() => void) | null;
+    protected _sharedResources: SharedResources | null;
+    protected _useSharedResources: boolean;
+    /**
+     * Create a new circuit controller
+     *
+     * @param factoryRegistry - Component visual factory registry
+     * @param sharedResources - Optional shared resources for facade pattern (CircuitEngine)
+     * @throws {TypeError} If factoryRegistry is null/undefined
+     */
+    constructor(factoryRegistry: IFactoryRegistry, sharedResources?: SharedResources);
+    get componentObject3Ds(): Map<UUID, THREE.Object3D>;
+    get enodeObject3Ds(): Map<UUID, THREE.Object3D>;
+    get wireObject3Ds(): Map<UUID, Line2>;
+    get visualContext(): VisualContext;
+    protected get grid(): THREE.GridHelper | null;
+    protected set grid(grid: THREE.GridHelper);
+    /**
+     * Initialize the controller with a DOM container.
+     * Creates scene, camera, lights, MapControls, and HoverManager.
+     *
+     * When sharedResources were provided in constructor, uses those instead
+     * of creating new resources. This enables the CircuitEngine facade pattern.
+     *
+     * @param container - HTMLElement to attach scene to
+     * @param options - Optional configuration
+     * @throws {TypeError} If container is not a valid HTMLElement
+     * @throws {Error} If already initialized
+     */
+    initialize(container: HTMLElement, options?: ControllerOptions): void;
+    /**
+     * Hook for subclasses to perform additional initialization.
+     * Called after base initialization but before emitting 'ready'.
+     *
+     * @param options - Controller options passed to initialize()
+     */
+    protected abstract onInitialize(options?: ControllerOptions): void;
+    /**
+     * Emit the ready event with controller-specific data.
+     */
+    protected abstract emitReady(): void;
+    /**
+     * Emit an error event.
+     */
+    protected emitError(error: Error): void;
+    /**
+     * Check that controller is initialized and not disposed.
+     * @throws {Error} If not initialized or already disposed
+     */
+    protected _checkInitialized(): void;
+    /**
+     * Clean up all WebGL resources.
+     * Disposes geometries, materials, controls, and clears event listeners.
+     *
+     * When using shared resources, does not dispose scene, camera, controls, or hover manager
+     * as those are owned by the CircuitEngine facade.
+     */
+    dispose(): void;
+    /**
+     * Hook for subclasses to perform cleanup before base dispose.
+     */
+    protected abstract onDispose(): void;
+    /**
+     * Remove all visual objects from scene.
+     * Subclasses must implement to handle their specific wire types.
+     */
+    protected abstract _removeAllVisuals(): void;
+    setActive(active: boolean): void;
+    protected abstract onSetActive(active: boolean): void;
+    /**
+     * Set the current circuit to visualize or null to clear the scene
+     * @param circuit
+     */
+    abstract setCircuit(circuit: Circuit | null): void;
+    /**
+     * Get the current circuit being visualized
+     */
+    getCircuit(): Circuit | null;
+    protected abstract onSetCircuit(): void;
+    /**
+     * Loads a new circuit to visualize or null for clearing the scene
+     * @param circuit
+     */
+    protected _setCircuit(circuit: Circuit | null): void;
+    /**
+     * get the object3D (Group for components and enodes, Line2 for wires) by hoverable type and id
+     * @param type
+     * @param id
+     */
+    getObject3D(type: HoverableType, id: UUID): THREE.Object3D | undefined;
+    /**
+     * Get the MapControls instance for direct manipulation.
+     */
+    getControls(): MapControls | null;
+    /**
+     * 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, default false
+     */
+    cursorGroundPlanePosition(bound?: boolean): THREE.Vector3;
+    /**
+     * Initialize HoverManager for hover detection
+     *
+     * @private
+     */
+    private _initializeHoverManager;
+    protected _setupMouseCallbacks(): void;
+    /**
+     * Get the currently hovered element.
+     */
+    getHoveredElement(): HoveredElement | null;
+    /**
+     * Enable or disable hover detection.
+     */
+    setHoverEnabled(enabled: boolean): void;
+    /**
+     * Check if hover detection is enabled.
+     */
+    isHoverEnabled(): boolean;
+    /**
+     * Get the Three.js scene for rendering.
+     * @throws {Error} If not initialized
+     */
+    getScene(): THREE.Scene;
+    /**
+     * Get the Three.js camera for rendering.
+     * @throws {Error} If not initialized
+     */
+    getCamera(): THREE.PerspectiveCamera;
+    /**
+     * Get the HTML container element.
+     * @throws {Error} If not initialized
+     */
+    getContainer(): HTMLElement;
+    /**
+     * Check if controller is initialized.
+     */
+    get isInitialized(): boolean;
+    /**
+     * Check if controller is disposed.
+     */
+    get isDisposed(): boolean;
+    /**
+     * event handler when the container size changes
+     * Can override the container boundingClientRect size by providing width and height
+     * - Update camera projection matrix
+     * - Update viewport size for Line2 material resolution
+     * Should be called when the container size changes (e.g., window resize)
+     *
+     * @param width - New width (optional, uses container size if not provided)
+     * @param height - New height (optional, uses container size if not provided)
+     */
+    onContainerResize(width?: number, height?: number): void;
+    /**
+     * Hook for subclasses to handle container resize.
+     */
+    protected onResize(_width: number, _height: number): void;
+}

package/dist/scene/shared/BranchingPointVisualFactory.d.ts

@@ -0,0 +1,70 @@
+import { ENodeSourceType, ENode } from '../../core/index.ts';
+/**
+ * Branching Point Visual Factory
+ * @module scene/shared/components/BranchingPointVisualFactory
+ *
+ * Creates cone-shaped visuals for branching point enodes with:
+ * - SourceType-based color coding (white/red/blue)
+ * - Hover/selection feedback via brightness shift
+ * - Hitbox for raycasting on ENODE layer
+ */
+import * as THREE from 'three';
+/**
+ * Factory for creating branching point visuals.
+ *
+ * Branching points are rendered as cones with colors indicating their sourceType:
+ * - White (0xffffff): No source (null)
+ * - Red (0xff0000): Voltage source
+ * - Blue (0x0000ff): Current source
+ *
+ * Hover and selection states use brightness shift of the base color.
+ */
+export declare class BranchingPointVisualFactory {
+    private static readonly COLORS;
+    private static readonly DEFAULT_HOVER_COLOR;
+    private static readonly HOVER_EMISSIVE;
+    private static readonly SELECTED_EMISSIVE;
+    private static readonly CONE_RADIUS;
+    private static readonly CONE_HEIGHT;
+    private static readonly CONE_SEGMENTS;
+    private static readonly HITBOX_SQUARE;
+    /**
+     * Create visual representation for a branching point.
+     * @param enode - The branching point ENode
+     * @returns THREE.Group containing cone mesh and hitbox
+     */
+    createVisual(enode: ENode): THREE.Group;
+    /**
+     * Update branching point object3D's visual to reflect sourceType change.
+     * @param object3D - The branching point basis object3D (group)
+     * @param sourceType - New source type
+     */
+    updateSourceType(object3D: THREE.Object3D, sourceType: ENodeSourceType | null): void;
+    protected colorForElectricalState(state: 'current' | 'voltage' | 'vc' | 'idle'): number;
+    /**
+     * Apply hover object3D feedback.
+     * @param object3D - The branching point basis object3D (group)
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover object3D feedback.
+     * @param object3D - The branching point basis object3D (group)
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection object3D feedback.
+     * @param object3D - The branching point basis object3D (group)
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection object3D feedback.
+     * @param object3D - The branching point basis object3D (group)
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * Get the base color for a sourceType.
+     * @param sourceType - Source type (null, 'Voltage', or 'Current')
+     * @returns Color hex value
+     */
+    private getColorForSourceType;
+}

package/dist/scene/shared/EventEmitter.d.ts

@@ -0,0 +1,92 @@
+/**
+ * Type-safe Event Emitter
+ * @module scene/shared/EventEmitter
+ *
+ * Provides type-safe event handling without external dependencies.
+ * Generic EventMap type ensures compile-time type safety for event payloads.
+ */
+/**
+ * Generic event emitter with type-safe event emission and subscription
+ *
+ * @template EventMap - Map of event names to their payload types
+ *
+ * @example
+ * ```typescript
+ * interface MyEvents {
+ *   click: { x: number; y: number };
+ *   error: { message: string };
+ * }
+ *
+ * const emitter = new EventEmitter<MyEvents>();
+ * emitter.on('click', ({ x, y }) => console.log(x, y)); // Type-safe!
+ * emitter.emit('click', { x: 10, y: 20 });
+ * ```
+ */
+export declare class EventEmitter<EventMap extends Record<string, any>> {
+    private listeners;
+    /**
+     * Register an event listener
+     *
+     * @param event - Event name to listen for
+     * @param callback - Function to call when event occurs
+     *
+     * @remarks
+     * Same callback can be registered multiple times (will be called multiple times).
+     * Callbacks are wrapped in try-catch to prevent errors from breaking emission.
+     */
+    on<K extends keyof EventMap>(event: K, callback: (payload: EventMap[K]) => void): void;
+    /**
+     * Unregister an event listener
+     *
+     * @param event - Event name
+     * @param callback - Function to remove (must be same reference used in on())
+     *
+     * @remarks
+     * If callback was registered multiple times, only removes one registration.
+     */
+    off<K extends keyof EventMap>(event: K, callback: (payload: EventMap[K]) => void): void;
+    /**
+     * Emit an event to all registered listeners
+     * This method is public so that tools may emit events directly on behalf of the EventEmitter owner (controller).
+     *
+     * @param event - Event name to emit
+     * @param payload - Event-specific payload
+     *
+     * @remarks
+     * Listeners are called in registration order.
+     * Errors in callbacks are caught and logged but do not stop other callbacks.
+     */
+    emit<K extends keyof EventMap>(event: K, payload: EventMap[K]): void;
+    /**
+     * Remove all listeners for a specific event or all events
+     *
+     * @param event - Optional event name. If omitted, removes all listeners for all events.
+     */
+    removeAllListeners<K extends keyof EventMap>(event?: K): void;
+    /**
+     * Get count of listeners for a specific event
+     *
+     * @param event - Event name
+     * @returns Number of registered listeners
+     */
+    listenerCount<K extends keyof EventMap>(event: K): number;
+    /**
+     * Register a listener that receives all events
+     *
+     * @param callback - Function called with event name and payload for every event
+     * @returns Cleanup function to remove the listener
+     *
+     * @remarks
+     * Useful for event forwarding/delegation patterns where you want to
+     * re-emit all events from one emitter to another.
+     *
+     * @example
+     * ```typescript
+     * const cleanup = source.onAny((event, payload) => {
+     *   target.emit(event, payload);
+     * });
+     * // Later: cleanup();
+     * ```
+     */
+    onAny(callback: <K extends keyof EventMap>(event: K, payload: EventMap[K]) => void): () => void;
+}

package/dist/scene/shared/HoverManager.d.ts

@@ -0,0 +1,151 @@
+import { HoveredElement } from './types';
+/**
+ * HoverManager Implementation
+ * @module scene/shared/HoverManager
+ *
+ * Handles priority-based hover detection using Three.js Raycaster and Layers.
+ * Implements priority: enode > component > wire
+ */
+import * as THREE from 'three';
+/**
+ * Callback type for hover state changes
+ */
+export type HoverCallback = (element: HoveredElement | null, previousElement: HoveredElement | null) => void;
+/**
+ * HoverManager Class
+ *
+ * Manages hover detection using Three.js Raycaster against hitbox layers.
+ * Implements priority-based detection: enode > component > wire.
+ */
+export declare class HoverManager {
+    private scene;
+    private camera;
+    private raycaster;
+    private readonly groundPlane;
+    private readonly groundPlanePosition;
+    private currentlyHovered;
+    private callbacks;
+    private enabled;
+    private initialized;
+    private lastMouseX;
+    private lastMouseY;
+    private lastUpdateTime;
+    private throttleMs;
+    /**
+     * Create a new HoverManager
+     *
+     * @param scene - Three.js scene containing hitbox meshes
+     * @param camera - Three.js camera for raycasting
+     */
+    constructor(scene: THREE.Scene, camera: THREE.Camera);
+    /**
+     * Get the last computed ground plane position under the mouse
+     *
+     * @returns THREE.Vector3 position on ground plane
+     */
+    getGroundPlanePosition(): THREE.Vector3;
+    /**
+     * Update hover state based on normalized mouse coordinates
+     * Also update the VERY IMPORTANT ground plane position used for CircuitManager cursorGroundPlanePosition
+     *
+     * Performs priority-based raycasting against hitbox layers.
+     * If hover state changes, triggers onHoverChange callback.
+     *
+     * @param normalizedX - Mouse X in normalized HTML container coordinates [-1, 1]
+     * @param normalizedY - Mouse Y in normalized HTML container coordinates [-1, 1]
+     */
+    updateFromMouse(normalizedX: number, normalizedY: number): void;
+    /**
+     * Force update hover state at current mouse position
+     *
+     * Useful after camera changes or scene updates to refresh hover state
+     * without requiring a new mouse event.
+     */
+    refresh(): void;
+    /**
+     * Clear current hover state
+     *
+     * Triggers unhover callback if an element was hovered.
+     * Call this when mouse leaves the container.
+     */
+    clear(): void;
+    /**
+     * Get the currently hovered element
+     *
+     * @returns HoveredElement if something is hovered, null otherwise
+     */
+    getHoveredElement(): HoveredElement | null;
+    /**
+     * Register callback for hover state changes
+     *
+     * Callback is invoked when:
+     * - Hover starts (element becomes non-null)
+     * - Hover changes to different element
+     * - Hover ends (element becomes null)
+     *
+     * @param callback - Function to call on hover state change
+     */
+    onHoverChange(callback: HoverCallback): void;
+    /**
+     * Remove previously registered hover change callback
+     *
+     * @param callback - Same function reference passed to onHoverChange
+     */
+    offHoverChange(callback: HoverCallback): void;
+    /**
+     * Enable or disable hover detection
+     *
+     * When disabled, updateFromMouse() becomes a no-op.
+     * Useful for temporarily disabling hover during drag operations.
+     *
+     * @param enabled - Whether to enable hover detection
+     */
+    setEnabled(enabled: boolean): void;
+    /**
+     * Check if hover detection is enabled
+     *
+     * @returns true if enabled
+     */
+    isEnabled(): boolean;
+    /**
+     * Set initialization state (to prevent double init)
+     * @param initialized
+     */
+    setInitialized(initialized: boolean): void;
+    /**
+     * Check if HoverManager is initialized (to prevent double init)
+     */
+    isInitialized(): boolean;
+    /**
+     * Clean up resources
+     *
+     * Removes all callbacks and clears state.
+     * Call when disposing the scene controllerType.
+     */
+    dispose(): void;
+    /**
+     * Perform raycasting on a specific layer and extract hit information
+     *
+     * @param layer - Hitbox layer number to raycast against
+     * @param hoverableType - Type for HoveredElement
+     * @param objectType - CircuitSceneObjectType for event payload
+     * @returns HoveredElement if hit found, null otherwise
+     */
+    private _raycastLayer;
+    /**
+     * Update hover state and trigger callbacks if changed
+     *
+     * Compares new hit with currentlyHovered and only triggers callbacks on change.
+     *
+     * @param newHit - New hover element or null
+     */
+    private _updateHoverState;
+    /**
+     * Compare two hover elements for equality
+     *
+     * @param a - First element
+     * @param b - Second element
+     * @returns true if both represent the same hover state
+     */
+    private _isSameHover;
+}

package/dist/scene/shared/SelectionManager.d.ts

@@ -0,0 +1,159 @@
+import { UUID } from '../../core/index.ts';
+import { HoverableType, SelectionData } from './types';
+/**
+ * Callback invoked when selection changes
+ *
+ * @param newSelection - The new selection, or null if deselected
+ * @param previousSelection - The previous selection, or null if none was selected
+ */
+export type SelectionCallback = (newSelection: SelectionData | null, previousSelection: SelectionData | null) => void;
+/**
+ * Manages selected components, enodes or wires for the circuit scene.
+ * Multi-selection is planned (notably with the use of a flexible SelectionData) but still to implement.
+ *
+ * Key current responsibilities:
+ * - Track -currently single object- selection state
+ * - Notify listeners of selection changes (observer pattern)
+ *
+ * @example
+ * ```typescript
+ * const selectionManager = new SelectionManager();
+ *
+ *
+ * // Select a single object
+ * selectionManager.selectOne('component', 'component-uuid-1234');
+ * selectionManager.selectOne('enode', 'enode-uuid-1234');
+ * selectionManager.selectOne('wire', 'wire-uuid-1234');
+ *
+ * // Deselect
+ * selectionManager.deselect();
+ * ```
+ */
+export declare class SelectionManager {
+    /** Current selection */
+    private selection;
+    /** Timestamp when selection occurred (for double-click detection) */
+    private selectedAt;
+    /** Registered selection change callbacks */
+    private callbacks;
+    /**
+     * Create a new SelectionManager
+     */
+    constructor();
+    /**
+     * Get the current selection
+     *
+     * @returns The SelectionData, or null if nothing is selected
+     */
+    getSelection(): SelectionData | null;
+    /**
+     * Get the timestamp when selection occurred
+     *
+     * @returns Timestamp in milliseconds, or null if nothing is selected
+     */
+    getSelectedAt(): number | null;
+    /**
+     * Check if a specific object is selected
+     *
+     * @param type - The type of hoverable object
+     * @param objectId - The object ID to check
+     * @returns true if the object is currently selected
+     */
+    isSelected(type: HoverableType, objectId: UUID): boolean;
+    /**
+     * Check if anything is selected
+     *
+     * @returns true if one object is currently selected or several objects are currently selected
+     */
+    hasSelection(): boolean;
+    private _selectionsEqual;
+    /**
+     * Select one object
+     *
+     * If another object was previously selected or a multi selection existed, they will be deselected first.
+     *
+     * @param type - The type of hoverable object to select
+     * @param objectId - The object ID to select
+     * @param userData - Optional userData of the 3D object being selected
+     */
+    selectOne(type: HoverableType, objectId: UUID, userData?: object | undefined): void;
+    /**
+     * Deselect the current selection
+     */
+    deselect(): void;
+    /**
+     * Select multiple elements at once, replacing any existing selection
+     *
+     * Creates a MultiSelectionData with the provided element maps.
+     * Empty maps are allowed; passing all empty maps clears the selection.
+     *
+     * @param components - Map of component IDs to optional metadata
+     * @param enodes - Map of enode IDs to optional metadata
+     * @param wires - Map of wire IDs to optional metadata
+     */
+    selectMultiple(components?: Map<UUID, string | null>, enodes?: Map<UUID, string | null>, wires?: Map<UUID, string | null>): void;
+    /**
+     * Add a single element to the current selection
+     *
+     * If current selection is null, creates a mono selection.
+     * If current selection is mono, converts to multi and adds element.
+     * If current selection is multi, adds element to appropriate map.
+     *
+     * No-op if element is already selected.
+     *
+     * @param type - Type of element to add
+     * @param objectId - UUID of element to add
+     * @param userData - Optional metadata for the element
+     */
+    addToSelection(type: HoverableType, objectId: UUID, userData?: object): void;
+    /**
+     * Remove a single element from the current selection
+     *
+     * If element is in a mono selection, clears the selection.
+     * If element is in a multi selection, removes from appropriate map.
+     * If multi selection becomes single element, converts to mono.
+     *
+     * No-op if element is not selected.
+     *
+     * @param type - Type of element to remove
+     * @param objectId - UUID of element to remove
+     */
+    removeFromSelection(type: HoverableType, objectId: UUID): void;
+    /**
+     * Get the total count of selected elements across all types
+     *
+     * @returns Number of selected elements (0 if no selection)
+     */
+    getSelectionCount(): number;
+    /**
+     * Get all selected element IDs grouped by type
+     *
+     * Returns empty arrays if no selection.
+     * For mono selection, returns single-element array in appropriate category.
+     *
+     * @returns Object with arrays of selected IDs by type
+     */
+    getSelectedIds(): {
+        components: UUID[];
+        enodes: UUID[];
+        wires: UUID[];
+    };
+    /**
+     * Register a callback for selection changes
+     *
+     * @param callback - Function to call when selection changes
+     * @returns Unsubscribe function
+     */
+    onSelectionChange(callback: SelectionCallback): () => void;
+    /**
+     * Notify all registered callbacks of selection change
+     *
+     * @param newSelection - New selection
+     * @param previousSelection - Previous selection
+     */
+    private notifyCallbacks;
+    /**
+     * Clean up resources
+     */
+    dispose(): void;
+}