simple-circuit-engine 0.0.2 → 0.0.8

package/AGENTS.md

@@ -0,0 +1,151 @@
+# simple-circuit-engine
+
+Educational electronic / computer circuit Build & Simulation engine with THREE.js 3D visualization.
+
+- **Install**: `npm install simple-circuit-engine three lil-gui`
+- **Imports**: `simple-circuit-engine/core` (model/simulation) | `simple-circuit-engine/scene` (Three.js visuals)
+- **TypeScript**: Full type support, strict mode compatible
+
+## Quick Start
+
+```typescript
+import { WebGLRenderer } from 'three';
+import {
+  Circuit,
+  BehaviorRegistry,
+  registerBasicComponentsBehaviors,
+} from 'simple-circuit-engine/core';
+import {
+  CircuitEngine,
+  engineOptions,
+  FactoryRegistry,
+  DefaultVisualFactory,
+  registerBasicComponentsFactories,
+} from 'simple-circuit-engine/scene';
+
+// Create component factory registry and behavior registry with basic components
+const componentsFactoryRegistry = registerBasicComponentsFactories(
+  new FactoryRegistry(new DefaultVisualFactory())
+);
+const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
+
+// 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());
+
+// Rendering
+const renderer = new WebGLRenderer();
+const width = window.innerWidth,
+  height = window.innerHeight;
+renderer.setSize(container.clientWidth, container.clientHeight);
+renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
+// Append renderer to DOM
+container.appendChild(renderer.domElement);
+// Animation loop to animate the circuit scene in the canvas container
+function animate() {
+  requestAnimationFrame(animate);
+  engine.getControls().update();
+  renderer.render(engine.getScene(), engine.getCamera());
+}
+animate();
+```
+
+## Core Module (`simple-circuit-engine/core`)
+
+### Domain Model
+
+- `Circuit` - Central container: components, enodes, wires
+- `Component` - Electrical component (battery, switch, LED, etc.)
+- `ENode` - Connection point (Component Pin or BranchingPoint)
+- `Wire` - Connection between two ENodes
+- `Position` - 2D grid coordinates
+- `Rotation` - Discrete rotation enum
+
+### Simulation
+
+- `CircuitRunner` - Tick-based simulation orchestrator
+- `SimulationState` - Circuit state at a given tick
+- `BehaviorRegistry` - Maps ComponentType → behavior logic
+- `registerBasicComponentsBehaviors()` - Registers built-in behaviors
+
+### Types
+
+- `ComponentType` - Enum: Battery, Switch, Transistor, etc.
+- `UUID` - String type alias for identifiers
+
+## Scene Module (`simple-circuit-engine/scene`)
+
+### Main Classes
+
+- `CircuitEngine` - Unified facade with edit/simulation mode switching
+- `CircuitController` - Edit mode: component placement, wiring, selection
+- `CircuitRunnerController` - Simulation mode: animation, interaction
+
+### Visual Factories
+
+- `FactoryRegistry` - Maps ComponentType → visual factory
+- `DefaultVisualFactory` - Fallback factory for unknown types
+- `registerBasicComponentsFactories()` - Registers built-in factories
+
+### Tools (Edit Mode)
+
+- `BuildTool` - Primary editing tool
+- `AddComponentTool` - Component placement
+- `MultiSelectTool` - Rectangle selection + bulk ops
+
+### Managers
+
+- `HoverManager` - Raycasting hover detection
+- `SelectionManager` - Tracks selected elements
+- `WireVisualManager` - Wire Line2 visuals
+
+## Common Patterns
+
+### Initialize Engine
+
+```typescript
+const engine = new CircuitEngine(factoryRegistry, behaviorRegistry);
+engine.initialize(container, engineOptions());
+engine.setCircuit(new Circuit());
+
+// Add Component Programmatically
+const battery = circuit.addComponent(ComponentType.Battery, new Position(0, 0));
+const led = circuit.addComponent(ComponentType.SmallLED, new Position(2, 0));
+
+// Connect Components
+const wire = circuit.addWire(battery.pins[0], led.pins[1]);
+
+// Switch Modes
+engine.setMode('simulation'); // Start simulation
+engine.setMode('edit');       // Back to editing
+
+// Listen to Events
+engine.on('componentAdded', (component) => { ... });
+engine.on('simulationTick', (state) => { ... });
+```
+
+## Non-Goals / Limitations
+
+### Non-Goals
+
+- **NOT realistic physics**: This is a discrete graph model, not SPICE
+- **NOT for production circuits**: Educational purposes only
+- **Circuit states are boolean**: Tension/current are on/off, not continuous values
+- **No analog simulation**: No voltage drops, current limiting, etc.  
+
+
+### Do NOT
+
+- Attempt to add analog physics simulation
+- Expect continuous voltage/current values
+- Use for real circuit design validation
+
+## Required Peer Dependencies
+
+```json
+{
+  "three": "^0.181.0",
+  "lil-gui": "^0.21.0"
+}
+```

package/CLAUDE.md

@@ -0,0 +1,140 @@
+# simple-circuit-engine Development Guidelines
+
+Provide a simple and easy-to-use electronic circuit simulation library for educational purposes.
+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
+
+## Active Technologies
+
+- TypeScript 5.9+ (strict mode), targeting ES2022
+- Three.js 0.181+ (scene, camera, controls, 3D objects, Line2)
+- lil-gui as helper for small interactive modal forms
+- in-memory circuit model, optional loading/saving from/to a JSON file
+
+## Project Structure
+
+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/`)
+
+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
+```
+
+### 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
+```
+
+## Testing strategy
+
+Unit tests are divided between core `tests/core` and scene `tests/scene`.
+Coverage goals are :
+
+- 80% on `core`: this module is the foundation of the model and simulation logic, hence it must be thoroughly tested
+- 60% on `scene`: coverage goal deliberately less strict to allow for more visualization tinkering
+
+## Commands
+
+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

@@ -2,7 +2,7 @@
 
 [![NPM Package][npm]][npm-url]
 
-#### JavaScript Educational Electronic circuit library
+## TypeScript Educational Electronic circuit library
 
 The aim of the project is to provide a simple and easy to use electronic circuit simulation engine for educational purposes.
 It allows users to create, edit and simulate electronic circuits in a web environment using [three.js](https://threejs.org/) for 3D rendering.
@@ -11,6 +11,24 @@ It allows users to create, edit and simulate electronic circuits in a web enviro
 
 Visit the [Demo page](https://demo.beyondtheswitch.net/) to see the library in action.
 
+### Use Cases
+
+The goal of this project is to vulgarize the bridge between **electronics**, the physical world and **informatic**, the abstract world that runs upon the former.
+The electrical model is deliberately simplified to the bare minimum needed to vulgarize circuits automation:
+
+- Electric states in nodes / wires are just two booleans : if there is tension or not and if there is current or not.
+- Components react to changes of inputs discretely with transitional state lasting N ticks (step) before their outputs change.
+- Changes in components states affect conductivity (let pass or not) between their pins.
+- Changes in electrical states throughout the circuit are then propagated using BFS (Breadth First Search) graph algorithm.
+
+There are some technicalities about initial simulation state computation (to prevent illegal initial states in feedback loop circuits) but that's pretty much all the simulation model does.
+It's not a realistic physical model but a **discrete graph model** and for the current scope of this project that's enough.
+
+However if you're searching for an open-source real electrical simulation model, you might want to check:
+
+- [circuitjs](https://github.com/sharpie7/circuitjs1) for a web implementation
+- The very complete [ngspice](https://ngspice.sourceforge.io/) (desktop) which is [SPICE](https://en.wikipedia.org/wiki/SPICE) compatible.
+
 ### Usage
 
 In addition to `simple-circuit-engine` you must import the `three` and `lil-gui` libraries in your project to use Simple Circuit Engine.
@@ -18,50 +36,33 @@ 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,
-    BehaviorRegistry,
-    registerBasicComponentsBehaviors,
-} from 'simple-circuit-engine/core';
-import {
-    CircuitEngine,
-    FactoryRegistry,
-    DefaultVisualFactory,
-    registerBasicComponentsFactories,
-} 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)
+const behaviorRegistry = registerBasicComponentsBehaviors(new BehaviorRegistry());
 
 // Initialize CircuitEngine
 // It creates THREE.js scene, camera, controls, lights, etc
 // and the interactive controllers (edit and simulation) of simple-circuit-engine
-const width = window.innerWidth, height = window.innerHeight;
-
-// Create component factory registry with all basic visual factories (for scene objects creation - rendering
-const componentsFactoryRegistry = new FactoryRegistry(new DefaultVisualFactory());
-registerBasicComponentsFactories(componentsFactoryRegistry);
-// Create behavior registry with all basic component behaviors (for simulation)
-const behaviorRegistry = new BehaviorRegistry();
-registerBasicComponentsBehaviors(behaviorRegistry);
-// Initialize CircuitEngine
 const container = document.getElementById('canva-container')!;
 const engine = new CircuitEngine(componentsFactoryRegistry, behaviorRegistry);
-engine.initialize(container, {
-    initialMode: 'edit',
-    controllerOptions: {},
-});
-// set engine circuit to a new empty circuit
+engine.initialize(container, engineOptions());
+// set engine circuit to a new empty circuit (which it does by default)
 engine.setCircuit(new Circuit());
 
-// THREE.js/WebGL standard rendering setup
-// Create WebGL renderer
+// Create and setup WebGL renderer
 const renderer = new WebGLRenderer({ antialias: true, alpha: false });
 renderer.setClearColor(0x1a1a2e);
-// Setup WebGL renderer
+const width = window.innerWidth, height = window.innerHeight;
 renderer.setSize(container.clientWidth, container.clientHeight);
 renderer.setPixelRatio(Math.min(window.devicePixelRatio, 2));
 // Append renderer to DOM
 container.appendChild(renderer.domElement);
-// Animation loop
+
+// Animation loop to animate the circuit scene in the canvas container
 function animate() {
     requestAnimationFrame(animate);
     engine.getControls().update();

package/dist/{CircuitRunner-CAeE31M5.js → CircuitRunner-FXM_s5ll.js}

@@ -1052,7 +1052,7 @@ const U = {
   /**
    * Default simulation speed in ticks per second
    */
-  DEFAULT_TPS: 2,
+  DEFAULT_TPS: 3,
   /**
    * Default tick interval in milliseconds (1000 / DEFAULT_TPS)
    */
@@ -1474,4 +1474,4 @@ export {
   x as m,
   L as s
 };
-//# sourceMappingURL=CircuitRunner-CAeE31M5.js.map
+//# sourceMappingURL=CircuitRunner-FXM_s5ll.js.map