simple-circuit-engine 0.0.9 → 0.0.11

package/AGENTS.md

@@ -12,27 +12,35 @@ Educational electronic / computer circuit Build & Simulation engine with THREE.j
 import { WebGLRenderer } from 'three';
 import {
   Circuit,
+  CircuitOptions,
   BehaviorRegistry,
   registerBasicComponentsBehaviors,
+  registerGatesComponentsBehaviors,
 } from 'simple-circuit-engine/core';
 import {
   CircuitEngine,
   engineOptions,
-  FactoryRegistry,
+  GroupedFactoryRegistry,
   DefaultVisualFactory,
   registerBasicComponentsFactories,
+  registerGatesComponentsFactories,
 } from 'simple-circuit-engine/scene';
 
 // Create component factory registry and behavior registry with basic components
 const componentsFactoryRegistry = registerBasicComponentsFactories(
-  new FactoryRegistry(new DefaultVisualFactory())
+  new GroupedFactoryRegistry(new DefaultVisualFactory())
 );
+registerGatesComponentsFactories(componentsFactoryRegistry); //... other groups of components if needed
+
 const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
+registerGatesComponentsBehaviors(behaviorRegistry); //... other groupsof components  if needed
 
 // Instanciate and Initialize CircuitEngine (it creates and uses a new Circuit by default)
 const engine = new CircuitEngine(componentsFactoryRegistry, behaviorRegistry);
 const container = document.getElementById('canvas-container')!;
 engine.initialize(container, engineOptions());
+// set engine circuit to a new empty circuit
+engine.setCircuit(new Circuit(new CircuitOptions()));
 
 // Rendering
 const renderer = new WebGLRenderer();
@@ -67,7 +75,7 @@ animate();
 - `CircuitRunner` - Tick-based simulation orchestrator
 - `SimulationState` - Circuit state at a given tick
 - `BehaviorRegistry` - Maps ComponentType → behavior logic
-- `registerBasicComponentsBehaviors()` - Registers built-in behaviors
+- `registerBasicComponentsBehaviors()` - Registers basic components built-in behaviors
 
 ### Types
 
@@ -84,15 +92,19 @@ animate();
 
 ### Visual Factories
 
-- `FactoryRegistry` - Maps ComponentType → visual factory
+- `GroupedFactoryRegistry` - Register groups of components referencing types and their visual factories
 - `DefaultVisualFactory` - Fallback factory for unknown types
-- `registerBasicComponentsFactories()` - Registers built-in factories
+- `registerBasicComponentsFactories()` - Registers basic components built-in factories
 
 ### Tools (Edit Mode)
 
-- `BuildTool` - Primary editing tool
-- `AddComponentTool` - Component placement
-- `MultiSelectTool` - Rectangle selection + bulk ops
+- `BuildTool` - Primary unified editing tool (add/drag/move/rotate/remove/wire/copy-cut/paste one element)
+- `MultiSelectTool` - Rectangle selection + bulk ops (drag, copy-cut/paste, remove multiple elements)
+
+### Widgets
+
+- `ComponentPicketWidget` - Widget for selecting component to add in BuildTool (edit mode)
+- `ConfigPanelWidget.ts` - Widget for editing components configuration (edit mode)
 
 ### Managers
 
@@ -130,10 +142,9 @@ engine.on('simulationTick', (state) => { ... });
 ### Non-Goals
 
 - **NOT realistic physics**: This is a discrete graph model, not SPICE
-- **NOT for production circuits**: Educational purposes only
+- **No analog simulation**: No voltage drops, current limiting, etc.
 - **Circuit states are boolean**: Tension/current are on/off, not continuous values
-- **No analog simulation**: No voltage drops, current limiting, etc.  
-
+- **NOT for production circuits**: Educational purposes only
 
 ### Do NOT
 

package/CLAUDE.md

@@ -4,7 +4,14 @@ Provide a simple and easy-to-use electronic circuit simulation library for educa
 It allows users to create, edit and simulate electronic circuits in a web environment.
 The library should be easily importable and usable in client applications and follow open-source typeScript libraries good practices.
 
-Last updated: 2026-01-18
+Last updated: 2026-03-14
+
+## Goals and principles
+
+To provide a vulgarization library that teaches the frontier between electronics and low level coding. 
+The electrical model is very simplified (no level of voltage/current, resistance, capacitance or inductance, type or frequency of current)
+and reduced to a logic state (has voltage/electrons sink true or false, has ground/electrons source true or false)/event engine. 
+However, it aims to teach real-world electronic design principles so modeling of components propagation delay and logic families is emphasized.
 
 ## Active Technologies
 
@@ -17,77 +24,19 @@ Last updated: 2026-01-18
 
 Simple Circuit Engine follows a **Model-Controller** architecture with clear separation between:
 
-- **Core module** (`src/core/`): Pure TypeScript domain **Model** and simulation engine (no dependencies)
-- **Scene module** (`src/scene/`): Three.js visualization layer with editing **Controllers** and tools
+- **Core module** (`src/core/`): Pure TypeScript domain **Model** and simulation engine (no dependencies).
+- **Scene module** (`src/scene/`): Three.js visualization layer with editing **Controller** and its tools and the simulation animated **Controller**.
 
 ### Core Module (`src/core/`)
 
-The core module is **dependency-free** and contains all domain logic:
-
-```
-src/core/
-  +-- Circuit.ts           # Central model: manages the three elements of the circuit : components, enodes, and wires
-  +-- Component.ts         # Electrical component (battery, switch, LED, etc.)
-  +-- ENode.ts             # Electrical node (Pin or BranchingPoint)
-  +-- Wire.ts              # Connection between two enodes
-  +-- Position.ts          # 2D grid position
-  +-- Rotation.ts          # Discrete rotation
-  +--  types/
-  |     +-- ComponentType.ts      # Component type enum and metadata
-  |     +-- ENodeSourceType.ts    # Voltage/Current source types
-  |     +-- ENodeType.ts          # Pin vs BranchingPoint
-  |     +-- Identifier.ts         # UUID type alias
-  +-- simulation/
-  |     +-- CircuitRunner.ts      # Tick-based simulation orchestrator
-  |     +-- DirtyTracker.ts       # Utility used by CircuitRunner to keep tracks of simulation changed components (optimization)
-  |     +-- EventQueue.ts         # Used by CircuitRunner to queue simulation delayed transitions events
-  |     +-- SimulationState.ts    # Data Class representing the simulation state of entire circuit at a given time
-  |     +-- StateManager.ts       # Utility used by CircuitRunner to manage SimulationState updates
-  |     +-- states/
-  |           +-- ComponentState.ts  # Abstract class for component state
-  |           +-- ...                # Components states
-  |     +-- behaviors/
-  |           +-- BehaviorRegistry.ts   # Maps component types to behaviors
-  |           +-- ComponentBehavior.ts  # Interface for component logic
-  |           +-- SwitchBehavior.ts     # Switch toggle logic
-  |           +-- ...                   # Other components behaviors
-  |     +-- types/  # Various enums, data classes ...
-  +-- setup.ts             # Helper to register behaviors
-  +-- index.ts             # Public API exports
-```
+The core module is **dependency-free** and contains all domain logic.
+Refer to its [CLAUDE.md](src/core/CLAUDE.md) for more details.
+
 
 ### Scene Module (`src/scene/`)
 
-The scene module handles Three.js visualization and user interaction:
-
-```
-src/scene/
-  +-- CircuitEngine.ts           # Unified facade with mode switching
-  +-- static/
-  |     +-- CircuitController.ts # Edit mode controller
-  |     +-- CircuitWriter.ts     # Writes scene changes to core model
-  |     +-- SelectionManager.ts  # Tracks selected elements
-  |     +-- tools/
-  |           +-- BuildTool.ts       # Unified edit tool (state machine)
-  |           +-- MultiSelectTool.ts # Rectangle selection + bulk operations
-  |           +-- AddComponentTool.ts # Component placement tool
-  +-- simulation/
-  |     +-- CircuitRunnerController.ts  # Simulation mode controller
-  +-- shared/
-  |     +-- AbstractCircuitController.ts # Base controller class
-  |     +-- EventEmitter.ts              # Type-safe event system
-  |     +-- HoverManager.ts              # Raycasting hover detection
-  |     +-- WireVisualManager.ts         # Wire Line2 visuals
-  |     +-- BranchingPointVisualFactory.ts # BP visuals
-  |     +-- components/
-  |     |     +-- ComponentVisualFactory.ts  # Interface + base class
-  |     |     +-- FactoryRegistry.ts         # Maps types to factories
-  |     |     +-- ...                        # Components factories
-  |     +-- types.ts             # Shared type definitions
-  |     +-- utils/               # Geometry, camera, lighting utilities
-  +-- setup.ts                   # Helper to register factories
-  +-- index.ts                   # Public API exports
-```
+The scene module handles Three.js visualization, user interaction and simulation animation.
+Refer to its [CLAUDE.md](src/scene/CLAUDE.md) for more details.
 
 ## Testing strategy
 
@@ -104,37 +53,4 @@ npm test && npm run lint
 ## Code Style
 
 TypeScript (strict mode), targeting ES2022: Follow standard conventions
-When possible level of nested conditional structures should be minimized by using guard clauses and early returns. Examples below:
-
-```typescript
-/**
- * GOOD practice for minimizing nested conditionals
- * DO that because clearer, reduced learning/debugging overhead
- * @param input
- */
-function goodExample(input: number | null): string {
-  if (input === null) {
-    // early return in this case
-    return 'No input provided';
-  }
-  // process securized input
-  // Main logic (possibly big) continues here without additional nesting
-  let output = input * 2;
-
-  return `Output is ${output}`;
-}
-/**
- * BAD practice that increases nested conditionals
- * DON'T do that because less clear, increased learning/debugging overhead
- * @param input
- */
-function badExample(input: number | null): string {
-  if (input !== null) {
-    // Main logic (possibly big) embedded under an if :
-    let output = input * 2;
-    return `Output is ${output}`;
-  } else {
-    return 'No input provided';
-  }
-}
-```
+

package/README.md

@@ -36,12 +36,12 @@ This code set up the main CircuitEngine instance in edit mode on a new Circuit,
 
 ```javascript
 import { WebGLRenderer } from 'three';
-import { Circuit, BehaviorRegistry, registerBasicComponentsBehaviors } from 'simple-circuit-engine/core';
-import { CircuitEngine, engineOptions, FactoryRegistry, DefaultVisualFactory, registerBasicComponentsFactories } from 'simple-circuit-engine/scene';
+import { Circuit, CircuitOptions, BehaviorRegistry, registerBasicComponentsBehaviors } from 'simple-circuit-engine/core';
+import { CircuitEngine, engineOptions, GroupedFactoryRegistry, DefaultVisualFactory, registerBasicComponentsBehaviors } from 'simple-circuit-engine/scene';
 
-// Create component factory registry with all basic visual factories (for scene objects creation - rendering
-const componentsFactoryRegistry = registerBasicComponentsFactories(new FactoryRegistry(new DefaultVisualFactory()));
-// Create behavior registry with all basic component behaviors (for simulation)
+// Create component factory registry with basic components visual factories (for scene objects creation - rendering)
+const componentsFactoryRegistry = registerBasicComponentsFactories(new GroupedFactoryRegistry(new DefaultVisualFactory()));
+// Create behavior registry with basic components behaviors (for simulation)
 const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
 
 // Initialize CircuitEngine
@@ -50,8 +50,8 @@ const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry()
 const container = document.getElementById('canva-container')!;
 const engine = new CircuitEngine(componentsFactoryRegistry, behaviorRegistry);
 engine.initialize(container, engineOptions());
-// set engine circuit to a new empty circuit (which it does by default)
-engine.setCircuit(new Circuit());
+// set engine circuit to a new empty circuit
+engine.setCircuit(new Circuit(new CircuitOptions()));
 
 // Create and setup WebGL renderer
 const renderer = new WebGLRenderer({ antialias: true, alpha: false });