simple-circuit-engine 0.0.10 → 0.0.12

package/AGENTS.md

@@ -9,9 +9,10 @@ Educational electronic / computer circuit Build & Simulation engine with THREE.j
 ## Quick Start
 
 ```typescript
-import { WebGLRenderer } from 'three';
+import { WebGLRenderer, Clock } from 'three';
 import {
   Circuit,
+  CircuitOptions,
   BehaviorRegistry,
   registerBasicComponentsBehaviors,
   registerGatesComponentsBehaviors,
@@ -38,6 +39,8 @@ registerGatesComponentsBehaviors(behaviorRegistry); //... other groupsof compone
 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();
@@ -47,11 +50,15 @@ 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
+
+// Animation loop
+const clock = new Clock();
 function animate() {
-  requestAnimationFrame(animate);
-  engine.getControls().update();
-  renderer.render(engine.getScene(), engine.getCamera());
+    requestAnimationFrame(animate);
+    const delta = clock.getDelta();
+    engine.update(delta);
+    engine.getControls().update();
+    renderer.render(engine.getScene(), engine.getCamera());
 }
 animate();
 ```
@@ -153,7 +160,6 @@ engine.on('simulationTick', (state) => { ... });
 
 ```json
 {
-  "three": "^0.181.0",
-  "lil-gui": "^0.21.0"
+  "three": "^0.183.2"
 }
 ```

package/CLAUDE.md

@@ -4,12 +4,19 @@ 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
 
-- TypeScript 5.9+ (strict mode), targeting ES2022
-- Three.js 0.181+ (scene, camera, controls, 3D objects, Line2)
+- TypeScript 6.0+ (strict mode), targeting ES2022
+- Three.js 0.183+ (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
 
@@ -17,78 +24,18 @@ 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 build tool (state machine)
-  |           +-- ComponentPickerWidget.ts # Widget for selecting component to add in BuildTool
-  |           +-- ConfigPanelWidget.ts # Widget for changing components configuration
-  |           +-- MultiSelectTool.ts # Rectangle selection + bulk operations
-  +-- 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
-  |     |     +-- GroupedFactoryRegistry.ts  # Register groups of components referencing types and their visual 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
 
@@ -105,37 +52,3 @@ 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

@@ -35,8 +35,8 @@ In addition to `simple-circuit-engine` you must import the `three` and `lil-gui`
 This code set up the main CircuitEngine instance in edit mode on a new Circuit, handles THREE.js objects creation and rendering/animation in the canva-container HTML element.
 
 ```javascript
-import { WebGLRenderer } from 'three';
-import { Circuit, BehaviorRegistry, registerBasicComponentsBehaviors } from 'simple-circuit-engine/core';
+import { WebGLRenderer, Clock } from 'three';
+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 basic components visual factories (for scene objects creation - rendering)
@@ -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 });
@@ -62,9 +62,12 @@ 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
+// Animation loop
+const clock = new Clock();
 function animate() {
     requestAnimationFrame(animate);
+    const delta = clock.getDelta();
+    engine.update(delta);
     engine.getControls().update();
     renderer.render(engine.getScene(), engine.getCamera());
 }

package/dist/core/index.d.ts

@@ -20,28 +20,7 @@
  *
  * @packageDocumentation
  */
-export { CameraOptions } from './types/CameraOptions.js';
-export type { ICameraOptions } from './types/CameraOptions.js';
-export type { ComponentTypeMetadata } from './types/ComponentType.js';
-export { ComponentType, COMPONENT_TYPE_METADATA, getAllComponentTypes, getComponentTypeMetadata, } from './types/ComponentType.js';
-export { ENodeSourceType } from './types/ENodeSourceType.js';
-export { ENodeType } from './types/ENodeType.js';
-export type { UUID } from './types/Identifier.js';
-export { generateUUID } from './types/Identifier.js';
-export { Position, findPositionBestIndex, simplifyPositions } from './types/Position.js';
-export { Position3D } from './types/Position3D.js';
-export type { IPosition3D } from './types/Position3D.js';
-export { Rotation } from './types/Rotation.js';
-export { Circuit, CircuitMetadata } from './Circuit.js';
-export type { ICircuitMetadata } from './Circuit.js';
-export { Component } from './Component.js';
-export { ENode } from './ENode.js';
-export { Wire } from './Wire.js';
-export type * from './simulation/index.js';
+export * from './utils/index.js';
+export * from './topology/index.js';
 export * from './simulation/index.js';
-export type * from './simulation/states/index.js';
-export * from './simulation/states/index.js';
-export type * from './simulation/behaviors/index.js';
-export * from './simulation/behaviors/index.js';
 export * from './setup.js';
-//# sourceMappingURL=index.d.ts.map