simple-circuit-engine 0.0.11 → 0.0.12

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

@@ -0,0 +1,242 @@
+import { Line2 } from 'three/examples/jsm/lines/Line2.js';
+import { UUID, Wire, Circuit } from '../../core/index.ts';
+/**
+ * Wire Visual Manager
+ * @module scene/shared/WireVisualManager
+ *
+ * Manages wire visual rendering with:
+ * - Pin-accurate endpoints (derived from component visuals)
+ * - Multi-segment rendering via intermediate positions
+ * - Dynamic updates during component movement
+ */
+import * as THREE from 'three';
+/**
+ * Wire path representation for rendering
+ */
+export interface WirePath {
+    /** Wire ID */
+    wireId: UUID;
+    /** Ordered points in world space (Three.js coordinates) */
+    points: THREE.Vector3[];
+}
+/**
+ * Delegation of CircuitController which handles wire visual rendering with proper pin targeting and dynamic updates.
+ *
+ * Key responsibilities:
+ * - Create wire visuals with endpoints at actual pin positions
+ * - Support multi-segment wires via intermediatePositions
+ * - Update wires dynamically when components move/rotate
+ * - Update wire materials for hover/selection states
+ * - may add and remove wire and branching point object3Ds in the scene directly
+ *
+ * @example
+ * ```typescript
+ * const wireManager = new WireVisualManager();
+ *
+ * // Create wire visual
+ * const line = wireManager.createOrUpdateWire(wire, circuit, scene, componentGroups);
+ *
+ * // Update wires when component moves
+ * wireManager.updateWiresForComponent(componentId, circuit, componentGroups);
+ * ```
+ */
+export declare class WireVisualManager {
+    private containerWidth;
+    private containerHeight;
+    private _scene;
+    private _camera;
+    private _componentObject3Ds;
+    private _wireObject3Ds;
+    private _container;
+    private _circuit;
+    /** Shared LineMaterials for all wires (memory efficient, consistent styling) */
+    private wireMaterials;
+    /** Preview wire for wire creation mode */
+    private previewWire;
+    constructor(componentObject3Ds: Map<UUID, THREE.Object3D>, wireObject3Ds: Map<UUID, Line2>);
+    setContainer(container: HTMLElement | null): void;
+    setSceneAndCamera(scene: THREE.Scene, camera: THREE.Camera): void;
+    setCircuit(circuit: Circuit | null): void;
+    /**
+     * Set the resolution for LineMaterial rendering
+     *
+     * MUST be called after initialization and on window/container resize
+     * for Line2 to render correctly.
+     *
+     * @param width - Viewport width in pixels
+     * @param height - Viewport height in pixels
+     *
+     * @example
+     * ```typescript
+     * wireManager.setResolution(window.innerWidth, window.innerHeight);
+     *
+     * window.addEventListener('resize', () => {
+     *   wireManager.setResolution(window.innerWidth, window.innerHeight);
+     * });
+     * ```
+     */
+    setResolution(width: number, height: number): void;
+    /**
+     * Get the Line2 object for a wire
+     *
+     * @param wireId - Wire ID
+     * @returns Line2 or undefined if not found or disposed
+     */
+    getWireLine(wireId: UUID): Line2 | undefined;
+    /**
+     * Check if a wire visual exists
+     *
+     * @param wireId - Wire ID
+     * @returns true if wire visual exists, false if not found or disposed
+     */
+    hasWire(wireId: UUID): boolean;
+    /**
+     * Get all wire IDs managed by this controllerType
+     *
+     * @returns Array of wire UUIDs, empty if disposed
+     */
+    getWireIds(): UUID[];
+    /**
+     * Create or update the visual for a wire using model wire positions
+     *
+     * @param wire - Wire to render
+     * @returns The created/updated Line2 object
+     */
+    createOrUpdateWire(wire: Wire): Line2;
+    /**
+     * Update a specific wire's geometry
+     *
+     * @param wireId - Wire ID to update
+     */
+    updateWireById(wireId: UUID): void;
+    /**
+     * Update all wires connected to a component
+     *
+     * Called when a component is moved or rotated to update wire endpoints.
+     *
+     * @param componentId - Component that moved
+     */
+    updateWiresForComponent(componentId: UUID): void;
+    /**
+     * visual hover and selection effects
+     */
+    /**
+     * Apply hovered visual effect to a wire
+     * @param wireId
+     */
+    applyHoveredVisual(wireId: UUID): void;
+    removeHoveredVisual(wireId: UUID): void;
+    applySelectedVisual(wireId: UUID): void;
+    removeSelectedVisual(wireId: UUID): void;
+    /**
+     * Apply electrical state material to a wire
+     * Used during simulation to visualize voltage/current flow
+     *
+     * @param wireId - Wire ID to update
+     * @param state - Material state: 'current', 'voltage', 'vc' (voltage and current) or 'idle'
+     */
+    applyElectricalState(wireId: UUID, state: 'current' | 'voltage' | 'vc' | 'idle'): void;
+    /**
+     * removal and dispose
+     */
+    /**
+     * Remove a wire visual from the scene
+     *
+     * @param wireId - Wire ID to remove
+     */
+    removeWire(wireId: UUID): void;
+    /**
+     * Clean up all managed wire visuals
+     */
+    dispose(): void;
+    /**
+     * Preview wire helpers
+     */
+    /**
+     * Create a preview wire for wire creation mode.
+     * @param startPosition - World position of wire start
+     * @returns Line2 object for preview
+     */
+    createPreviewWire(startPosition: THREE.Vector3): Line2;
+    /**
+     * Update preview wire endpoint.
+     * @param endPosition - World position of wire end
+     */
+    updatePreviewWire(endPosition: THREE.Vector3): void;
+    /**
+     * Remove preview wire from scene.
+     */
+    removePreviewWire(): void;
+    /**
+     * Intermediate points and position helpers
+     */
+    /**
+     * Get pin world position by traversing component group
+     *
+     * @param enodeId - The pin's ENode ID
+     * @param componentGroup - The component's Three.js group
+     * @returns World position of the pin, or null if not found
+     */
+    getPinWorldPositionFromGroup(enodeId: UUID, componentGroup: THREE.Object3D): THREE.Vector3 | null;
+    /**
+     * Get insertion index for a new intermediate point on a wire (T058)
+     * @param wireId - Wire ID
+     * @param worldPosition - Position where user clicked
+     * @returns Index where new point should be inserted
+     */
+    getInsertIndexForPosition(wireId: UUID, worldPosition: THREE.Vector3): number;
+    /**
+     * Find nearest intermediate point on a wire within proximity threshold (T057)
+     * @param wireId - Wire ID to search
+     * @param clientPos - Client position (event.clientX/Y) to test - will be converted to container-relative
+     * @param thresholdPx - Proximity threshold in pixels (default: 10)
+     * @returns Object with pointIndex and distance, or null if none found
+     */
+    findNearestIntermediatePoint(wireId: UUID, clientPos: THREE.Vector2, thresholdPx?: number): {
+        pointIndex: number;
+        distance: number;
+    } | null;
+    /**
+     * Compute the full path for a wire including intermediate positions
+     *
+     * @param wire - Wire to compute path for
+     * @returns WirePath with array of Vector3 points from start to end
+     */
+    computeWirePath(wire: Wire): WirePath;
+    /**
+     * private helpers
+     */
+    /**
+     * Get the world position of an ENode (pin or branching point)
+     *
+     * For pins: Traverses component group to find pin visual and gets world position
+     * For branching points: Converts grid position to world coordinates
+     *
+     * @param enodeId - The ENode ID
+     * @param enodeType - Type of the ENode (Pin or BranchingPoint)
+     * @param componentId - Parent component ID (for pins)
+     * @param circuit - Circuit for position lookup
+     * @param componentGroups - Map of component ID to Three.js objects
+     * @returns World position as Vector3
+     */
+    private _getENodeWorldPosition;
+    /**
+     * Convert 3D world position to 2D screen position (T056)
+     * @param worldPosition - World position as Vector3
+     * @returns Screen position as Vector2
+     */
+    private worldToScreen;
+    /**
+     * Calculate distance between two 2D screen positions (T056)
+     * @param screenPos1 - First screen position
+     * @param screenPos2 - Second screen position
+     * @returns Distance in pixels
+     */
+    private screenDistance;
+    /**
+     * Convert client coordinates (event.clientX/Y) to container-relative coordinates
+     * @param clientPos - Position in client/viewport coordinates
+     * @returns Position relative to the container's top-left corner
+     */
+    private clientToContainerCoords;
+}

package/dist/scene/shared/components/ComponentVisualFactory.d.ts

@@ -0,0 +1,438 @@
+import { Component, ComponentType, ComponentState, ENode, ENodeSourceType } from '../../../core/index.ts';
+import { AnimationContext, ConfigFormDefinition, VisualContext } from '../types';
+import { Direction2D } from '../utils/GeometryUtils';
+import { MeshLambertMaterial } from 'three';
+import { CmpMatCategory, CmpMatVariant } from './types';
+import * as THREE from 'three';
+/**
+ * Interface for component visual factories
+ *
+ * Implementations provide methods for:
+ * - Creating the 3D visual representation
+ * - Applying/removing hover effects
+ * - Applying/removing selection effects
+ * - Updating animation based on simulation state
+ *
+ * @example
+ * ```typescript
+ * class MyComponentFactory extends ComponentVisualFactoryBase {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
+ *     const group = new THREE.Group();
+ *     // ... create visual elements
+ *     group.userData.componentId = component.id;
+ *     group.userData.componentType = component.type;
+ *     return group;
+ *   }
+ * }
+ * ```
+ */
+export interface IComponentVisualFactory {
+    /**
+     * @returns nominal rotation along the Y axis when component added (angle in radian)
+     */
+    defaultRotation(): number;
+    /**
+     * Create the Three.js visual representation for a component
+     *
+     * @param component - The circuit component to visualize
+     * @param context - Optional visual context providing access to ENode data
+     * @returns THREE.Object3D (typically a Group) containing the visual
+     *
+     * @remarks
+     * Implementations MUST:
+     * - Set `object.userData.componentId = component.id`
+     * - Set `object.userData.componentType = component.type`
+     * - Create component hitbox on HitboxLayers.COMPONENT layer
+     * - Create pin groups with enodes on HitboxLayers.ENODE layer
+     * - Return objects positioned at origin (scene controllerType handles placement)
+     */
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    /**
+     * Update visual based on component configuration
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param config - The core component configuration Map
+     *
+     */
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Apply hover visual effect to a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Should store original material state in userData for restoration
+     * - Default implementation: emissive glow effect (light blue, 0.5 intensity)
+     * - Called by scene controllerType when component is hovered
+     * - Should be idempotent (safe to call multiple times)
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover visual effect from a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Should restore original material state from userData
+     * - Called by scene controllerType when hover ends
+     * - Should be safe to call even if not currently hovered
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection visual effect to a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Currently a placeholder (no-op) for future implementation
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection visual effect from a component's Object3D
+     *
+     * @param object3D - The Object3D created by createVisual()
+     *
+     * @remarks
+     * - Currently a placeholder (no-op) for future implementation
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * Update pin source type visual (optional method)
+     *
+     * @param pinGroup - The THREE.Group containing the pin visual
+     * @param sourceType - The new source type (null for no source)
+     *
+     * @remarks
+     * - Optional method for component factories that support pin source type visualization
+     * - Changes pin color based on source type (bronze/red/blue)
+     * - Default implementation in ComponentVisualFactoryBase
+     */
+    updatePinSourceType(pinGroup: THREE.Object3D, sourceType: ENodeSourceType | null): void;
+    /**
+     * Apply hover effect on a pin
+     * @param pinGroup
+     */
+    applyPinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Remove hover effect on a pin
+     */
+    removePinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Update animation state based on simulation data
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The component's current simulation state or null to reset to edition mode
+     *
+     * @remarks
+     * - Called by CircuitRunnerController during simulation
+     * - Animation visual updates have priority over hover effects
+     * - Default implementation: no-op (static components)
+     * - Subclasses override for component-specific animation
+     *   (e.g., LED glow, switch contactor rotation)
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Get the config form definition for this component type
+     *
+     * @param config - Optional current component config to compute field states (e.g., disabled)
+     * @returns Form definition with field specifications, or null if no config
+     *
+     * @remarks
+     * Defines the UI controls for editing component configuration.
+     * Return null for components with no configurable options.
+     * When config is provided, implementations may use it to set field.disabled
+     * based on interdependencies (e.g., transitionSpan disabled when defaultLogicFamily != Sandbox).
+     */
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core component config (string values) to form data (typed values)
+     *
+     * @param config - Core config from Component.config
+     * @returns Form data with appropriate types for UI controls
+     *
+     * @remarks
+     * Called when config panel opens to initialize form controls.
+     * Converts core string values to UI-appropriate types (e.g., "open" → true).
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data (typed values) back to core config (string values)
+     *
+     * @param formData - Current form values from UI
+     * @returns Core config ready for Component.setAllParameters()
+     *
+     * @remarks
+     * Called on each value change to update Component.config.
+     * Converts UI values back to core string format (e.g., true → "open").
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Set the shared animation context for simulation-aware factories.
+     * Called by the registry fan-out when entering/leaving simulation.
+     *
+     * @param ctx - Animation context, or null when leaving simulation
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}
+/**
+ * Abstract base class for component visual factories
+ *
+ * Provides default implementations for:
+ * - Hover effect (emissive glow)
+ * - Selection effect (placeholder/no-op)
+ * - Animation update (placeholder/no-op)
+ * - Pin group creation (shared helper)
+ * - Component hitbox creation (shared helper)
+ *
+ * Subclasses must implement:
+ * - createVisual() - component-specific visual creation
+ *
+ * Subclasses may override:
+ * - applyHover() / removeHover() - custom hover effect
+ * - applySelection() / removeSelection() - custom selection effect (future)
+ * - updateAnimation() - component-specific animation
+ *
+ * @example
+ * ```typescript
+ * export class BatteryVisualFactory extends ComponentVisualFactoryBase {
+ *   createVisual(component: Component, context?: VisualContext): THREE.Object3D {
+ *     const group = new THREE.Group();
+ *     // ... create battery-specific visual
+ *     return group;
+ *   }
+ *   // Inherits default hover, selection, and animation
+ * }
+ * ```
+ */
+export declare abstract class ComponentVisualFactoryBase implements IComponentVisualFactory {
+    /** Shared animation context injected by the registry during simulation */
+    protected _animationContext: AnimationContext | null;
+    /** ComponentType handled by this factory, set in each subclass constructor */
+    protected _componentType: ComponentType | null;
+    /** Default hover glow color (light blue) */
+    protected static readonly DEFAULT_HOVER_COLOR = 4491519;
+    /** Default hover emissive intensity */
+    protected static readonly DEFAULT_HOVER_INTENSITY = 0.6;
+    protected getMat(category: CmpMatCategory, variant?: CmpMatVariant): MeshLambertMaterial;
+    defaultRotation(): number;
+    /**
+     * Create the Three.js visual representation for a component
+     * Must be implemented by subclasses
+     */
+    abstract createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    /**
+     * By default no visual configuration-based updates is needed
+     */
+    updateFromConfiguration(_object3D: THREE.Object3D, _config: Map<string, string>): void;
+    /**
+     * Apply hover visual effect using emissive glow
+     *
+     * Default implementation traverses all meshes and applies
+     * an emissive blue glow effect, storing original values in userData.
+     *
+     * Note: If component is selected, selection visual takes precedence
+     * and hover visual is not applied (but isHovered flag is still set).
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover visual effect, restoring original materials
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection visual effect using emissive orange glow
+     *
+     * Selection takes precedence over hover effect.
+     * Stores original material state in userData for restoration.
+     *
+     * @param object3D - The component's root Three.js object
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection visual effect, restoring original or hover state
+     *
+     * If component was hovered before selection, restores hover visual.
+     * Otherwise, restores original material state.
+     *
+     * @param object3D - The component's root Three.js object
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * @private
+     */
+    private pointPinGroupToward;
+    /**
+     * Create a pin group with hitbox and visual sphere
+     *
+     * Creates a THREE.Group containing:
+     * - Hemisphere hitbox (on ENODE layer for raycasting)
+     * - Hemisphere visual (blue sphere)
+     * - Hover callback in userData
+     *
+     * @param node - ENode to create as visual pin
+     * @param pointsTo - rotate pin to make it point the wanted direction
+     * @param visualRotation - if set rotate the visual of the pin to adjust display without affecting hitbox
+     * @returns THREE.Group configured as pin group
+     */
+    protected createPinGroup(node: ENode, pointsTo?: Direction2D, visualRotation?: THREE.Euler | null): THREE.Group;
+    /**
+     * Utility to create semi spheres visually closing pins
+     * @param pinGroup
+     * @param material
+     * @protected
+     */
+    protected createPinCounterpart(pinGroup: THREE.Group, material: THREE.MeshLambertMaterial): THREE.Mesh | null;
+    /**
+     * Find pin group by label within a component Object3D
+     * @param object3D
+     * @param label
+     */
+    findPinGroup(object3D: THREE.Object3D, label: string): THREE.Group | null;
+    /**
+     * fin pin inner visual from within its pin group
+     * @param pinGroup
+     */
+    findPinVisualFromGroup(pinGroup: THREE.Group): THREE.Mesh | null;
+    /**
+     * Find pin group visual by label within a component Object3D
+     * @param object3D
+     * @param label
+     */
+    findPinVisual(object3D: THREE.Object3D, label: string): THREE.Mesh | null;
+    /**
+     * Create component hitbox mesh
+     *
+     * Helper to create standard component hitbox with proper userData and layer.
+     *
+     * @param componentId - UUID of the component
+     * @param groupId - ID of the parent THREE.Group
+     * @param width - Hitbox width
+     * @param height - Hitbox height
+     * @param depth - Hitbox depth
+     * @returns THREE.Mesh configured as component hitbox
+     */
+    protected createComponentHitbox(componentId: string, groupId: number, width: number, height: number, depth: number): THREE.Mesh;
+    protected findHitbox(object3D: THREE.Object3D): THREE.Mesh | null;
+    protected pinColorForSourceType(sourceType: ENodeSourceType | null): number;
+    protected pinColorForElectricalState(state: 'current' | 'voltage' | 'vc' | 'idle'): number;
+    /**
+     * Updates the visual color of a component pin based on its sourceType type.
+     *
+     * This method changes the pin's material color to reflect the sourceType type:
+     * - null/undefined: copper (default pin color)
+     * - Voltage: red
+     * - Current: blue
+     *
+     * @param pinGroup - The THREE.Group containing the pin visual (created by createPinGroup)
+     * @param sourceType - The new sourceType (null for no sourceType)
+     *
+     * @remarks
+     * - Searches for the child mesh with userData.type === 'enode'
+     * - Updates both color and emissive properties for visual consistency
+     * - If sourceType is null/undefined, restores default copper pin color
+     * - Color scheme matches BranchingPointVisualFactory for consistency
+     */
+    updatePinSourceType(pinGroup: THREE.Object3D, sourceType: ENodeSourceType | null): void;
+    /**
+     * Apply hover visual effect on this pin
+     */
+    applyPinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * remove hover visual effect on this pin
+     */
+    removePinHover(pinGroup: THREE.Object3D): void;
+    /**
+     * Update animation state based on simulation data (placeholder)
+     *
+     * Default implementation is a no-op for static components.
+     * Override in subclasses that have animation (LED, Switch).
+     */
+    updateAnimation(_object3D: THREE.Object3D, _state: ComponentState | null): void;
+    /**
+     * Get config form definition (default: null - no config)
+     *
+     * Override in subclasses that have configurable options.
+     */
+    getConfigFormDefinition(_config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (default: identity mapping)
+     *
+     * Override in subclasses that need type conversions.
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (default: convert all to strings)
+     *
+     * Override in subclasses that need type conversions.
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Set the shared animation context for simulation-aware factories.
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}
+/**
+ * Registry interface for managing component visual factories
+ *
+ * Provides type-safe registration and retrieval of component factories.
+ * Falls back to a default factory for unregistered component types.
+ *
+ * @remarks
+ * Updated to support both function-based and class-based factories.
+ * Prefer using IComponentVisualFactory class instances.
+ *
+ * @example
+ * ```typescript
+ * const registry = new FactoryRegistry(new DefaultVisualFactory());
+ * registry.register(ComponentType.Battery, new BatteryVisualFactory());
+ * registry.register(ComponentType.LED, new SmallLEDVisualFactory());
+ *
+ * const factory = registry.get(ComponentType.Battery);
+ * const mesh = factory.createVisual(batteryComponent);
+ * ```
+ */
+export interface IFactoryRegistry {
+    /**
+     * Retrieve the factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns Factory (fallback factory if type not registered)
+     *
+     * @remarks
+     * This method NEVER returns null/undefined. If the type is not registered,
+     * the fallback factory provided in the constructor is returned.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered component types
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Unregister a factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if factory was registered and removed, false otherwise
+     *
+     * @remarks
+     * After unregistering, get() will return the fallback factory for this type.
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Get all registered component types
+     *
+     * @returns Array of ComponentType values that have registered factories
+     */
+    getRegisteredTypes(): ComponentType[];
+    /**
+     * Fan out animation context to all registered factories and the fallback.
+     *
+     * @param ctx - Animation context, or null when leaving simulation
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}