simple-circuit-engine 0.0.12 → 0.0.14

package/dist/scene/CircuitEngine.d.ts

@@ -25,8 +25,10 @@ import * as THREE from 'three';
  *
  * @example
  * ```typescript
+ * const renderer = new THREE.WebGLRenderer({ antialias: true });
  * const engine = new CircuitEngine(factoryRegistry, behaviorRegistry);
- * engine.initialize(container);
+ * engine.initialize(container, renderer);
+ * container.appendChild(renderer.domElement);
  * engine.setCircuit(circuit);
  *
  * // Edit mode (default)
@@ -49,11 +51,13 @@ export declare class CircuitEngine extends EventEmitter<CircuitEngineEventMap> {
     private _editController;
     private _simulationController;
     private _mode;
+    private _multiWiring;
     private _initialized;
     private _options;
     private _disposed;
     private _editControllerCleanup;
     private _simulationControllerCleanup;
+    private _widgetsManager;
     /**
      * Create a new CircuitEngine instance.
      *
@@ -71,15 +75,20 @@ export declare class CircuitEngine extends EventEmitter<CircuitEngineEventMap> {
      */
     get isDisposed(): boolean;
     /**
-     * Initialize the engine with a DOM container.
+     * Initialize the engine with a DOM container and a WebGLRenderer.
      * Creates shared Three.js resources and both controllers.
      *
-     * @param container - HTMLElement to mount the scene
+     * The caller owns the renderer and its canvas; the engine binds MapControls
+     * to `renderer.domElement` (not the container) so DOM overlays such as the
+     * integrated widgets can receive pointer events normally.
+     *
+     * @param container - HTMLElement to mount the scene (used for bounds, mouse tracking, widget overlay)
+     * @param renderer - WebGLRenderer owned by the consumer. Its canvas (`renderer.domElement`) is used for pointer input.
      * @param options - Configuration options
      * @throws {TypeError} If container is not a valid HTMLElement
      * @throws {Error} If already initialized
      */
-    initialize(container: HTMLElement, options?: EngineOptions): void;
+    initialize(container: HTMLElement, renderer: THREE.WebGLRenderer, options?: EngineOptions): void;
     /**
      * Create shared resources for both controllers.
      */
@@ -102,6 +111,19 @@ export declare class CircuitEngine extends EventEmitter<CircuitEngineEventMap> {
      * Current operating mode
      */
     get mode(): EngineMode;
+    /**
+     * Refresh all scene widgets to display strings in the given language.
+     *
+     * Does NOT change the consumer's i18next instance — the caller must have
+     * already called `i18next.changeLanguage(lng)` before invoking this. This
+     * method only signals the scene to re-read translations for currently-open
+     * widgets (pin tooltip, component picker, config panel).
+     *
+     * Safe to call at any point in the engine lifecycle after `initialize()`.
+     *
+     * @param lng - Target language code (e.g., 'en', 'fr')
+     */
+    setLanguage(lng: string): void;
     /**
      * Switch between edit and simulation modes.
      *
@@ -161,6 +183,17 @@ export declare class CircuitEngine extends EventEmitter<CircuitEngineEventMap> {
      * @throws {Error} If not in edit mode
      */
     setEditModeEnabled(enabled: boolean): void;
+    /**
+     * Whether the multi-wiring flag is currently enabled.
+     * Wiring tools may use it to create several wires per pull (semantics handled
+     * by the tools; the engine only owns the flag and forwards changes).
+     */
+    get multiWiring(): boolean;
+    /**
+     * Toggle the multi-wiring flag and forward to the edit controller.
+     * Emits `multiWiringChanged` once on transition.
+     */
+    setMultiWiring(value: boolean): void;
     /**
      * Start automatic simulation playback.
      *
@@ -185,6 +218,18 @@ export declare class CircuitEngine extends EventEmitter<CircuitEngineEventMap> {
      * @throws {Error} If not in simulation mode
      */
     stop(): void;
+    /**
+     * Request help for the current mode. Emits `helpRequested` with the active
+     * mode as payload; consumers decide how to render help (modal, sidebar, etc.).
+     *
+     * @example
+     * ```typescript
+     * engine.on('helpRequested', ({ mode }) => {
+     *   openHelpDialog(mode);
+     * });
+     * ```
+     */
+    requestHelp(): void;
     /**
      * Check if simulation is currently playing
      */

package/dist/scene/index.d.ts

@@ -11,9 +11,11 @@
  * ```typescript
  * import { CircuitController, FactoryRegistry } from 'simple-circuit-controller/scene';
  *
+ * const renderer = new THREE.WebGLRenderer({ antialias: true });
  * const registry = new FactoryRegistry(defaultFactory);
  * const controller = new CircuitController(registry);
- * controller.initialize(container);
+ * controller.initialize(container, renderer);
+ * container.appendChild(renderer.domElement);
  * controller.setCircuit(circuit);
  * ```
  */
@@ -21,6 +23,8 @@ export { CircuitEngine } from './CircuitEngine';
 export { CircuitController } from './static/CircuitController';
 export { CircuitRunnerController } from './simulation/CircuitRunnerController';
 export type { AbstractCircuitController } from './shared/AbstractCircuitController';
+export { WidgetsManager } from './widgets';
+export type { IEngineForWidgets } from './widgets';
 export { BuildTool } from './static/tools/BuildTool';
 export { MultiSelectTool } from './static/tools/MultiSelectTool';
 export { ComponentPickerWidget, BRANCHING_POINT_SENTINEL, } from './static/tools/ComponentPickerWidget';
@@ -40,4 +44,4 @@ export * from './shared/types';
 export { HitboxLayers } from './shared/utils/LayerConstants';
 export type { HitboxLayerValue } from './shared/utils/LayerConstants';
 export * from './shared/utils/Options';
-export { registerBasicComponentsFactories, registerGatesComponentsFactories } from './setup';
+export { registerBasicComponentsFactories, registerGatesComponentsFactories, registerArithmeticComponentsFactories, registerInterfaceComponentsFactories } from './setup';

package/dist/scene/index.js

@@ -1,47 +1,64 @@
-import { A as s, B as t, C as r, D as o, E as i, F as e, H as l, I as c, L as u, M as n, N as y, O as F, P as V, R as C, S as g, T as p, U as G, V as N, W as m, _ as M, a as L, b as R, c as S, d as T, f as d, g as E, h as b, i as h, j as B, k as I, l as D, m as O, n as P, o as w, p as A, r as H, s as W, t as _, u as f, v as k, w as v, x, y as X, z as j } from "../scene-CVsDdySt.js";
+import { $ as t, A as s, B as r, C as i, D as o, E as e, F as l, G as c, H as u, I as n, J as y, K as F, L as V, M as g, N as p, O as C, P as h, Q as m, R as d, S as G, T as L, U as I, V as N, W as E, X as M, Y as B, Z as T, _ as A, a as O, at as R, b as S, c as b, d as w, et as f, f as D, g as H, h as P, i as W, it as X, j as _, k, l as v, m as x, n as j, nt as q, o as z, ot as J, p as K, q as Q, r as U, rt as Y, s as Z, st as $, t as aa, tt as ta, u as sa, v as ra, w as ia, x as oa, y as ea, z as la } from "../scene-C1xhdw_B.js";
 export {
-  G as BRANCHING_POINT_SENTINEL,
-  x as BatteryVisualFactory,
-  c as BranchingPointVisualFactory,
-  l as BuildTool,
-  p as CMP_MATERIALS,
-  B as CircuitController,
-  I as CircuitEngine,
-  s as CircuitRunnerController,
-  j as CircuitWriter,
-  A as ClockVisualFactory,
-  i as CmpMatCategory,
-  o as CmpMatType,
-  F as CmpMatVariant,
-  m as ComponentPickerWidget,
-  r as DefaultVisualFactory,
-  O as DoubleThrowSwitchVisualFactory,
-  v as FactoryRegistry,
-  g as GroupedFactoryRegistry,
-  C as HitboxLayers,
-  u as HoverManager,
-  d as InverterVisualFactory,
-  R as LabelVisualFactory,
-  X as LightbulbVisualFactory,
-  N as MultiSelectTool,
-  f as Nand4GateVisualFactory,
-  D as Nand8GateVisualFactory,
-  T as NandGateVisualFactory,
-  W as Nor4GateVisualFactory,
-  w as Nor8GateVisualFactory,
-  S as NorGateVisualFactory,
-  k as RectangleLEDVisualFactory,
-  M as RelayVisualFactory,
-  t as SelectionManager,
-  E as SmallLEDVisualFactory,
-  b as SwitchVisualFactory,
-  e as WireVisualManager,
-  h as Xor4GateVisualFactory,
-  H as Xor8GateVisualFactory,
-  L as XorGateVisualFactory,
-  n as controllerOptions,
-  y as engineOptions,
-  V as mapControlsOptions,
-  _ as registerBasicComponentsFactories,
-  P as registerGatesComponentsFactories
+  A as AdderVisualFactory,
+  J as BRANCHING_POINT_SENTINEL,
+  V as BatteryVisualFactory,
+  t as BranchingPointVisualFactory,
+  R as BuildTool,
+  N as CMP_MATERIALS,
+  y as CircuitController,
+  c as CircuitEngine,
+  Q as CircuitRunnerController,
+  q as CircuitWriter,
+  k as ClockVisualFactory,
+  u as CmpMatCategory,
+  I as CmpMatType,
+  E as CmpMatVariant,
+  $ as ComponentPickerWidget,
+  la as DefaultVisualFactory,
+  s as DoubleThrowSwitchVisualFactory,
+  H as EightBitAdderVisualFactory,
+  P as EightBitOnesComplementVisualFactory,
+  sa as EightInputVisualFactory,
+  O as EightLightVisualFactory,
+  r as FactoryRegistry,
+  w as FourInputVisualFactory,
+  z as FourLightVisualFactory,
+  d as GroupedFactoryRegistry,
+  ra as HalfAdderVisualFactory,
+  ta as HitboxLayers,
+  f as HoverManager,
+  x as InputVisualFactoryBase,
+  C as InverterVisualFactory,
+  n as LabelVisualFactory,
+  v as LightVisualFactoryBase,
+  l as LightbulbVisualFactory,
+  X as MultiSelectTool,
+  e as Nand4GateVisualFactory,
+  L as Nand8GateVisualFactory,
+  o as NandGateVisualFactory,
+  i as Nor4GateVisualFactory,
+  G as Nor8GateVisualFactory,
+  ia as NorGateVisualFactory,
+  K as OneInputVisualFactory,
+  b as OneLightVisualFactory,
+  h as RectangleLEDVisualFactory,
+  p as RelayVisualFactory,
+  Y as SelectionManager,
+  g as SmallLEDVisualFactory,
+  _ as SwitchVisualFactory,
+  D as TwoInputVisualFactory,
+  Z as TwoLightVisualFactory,
+  F as WidgetsManager,
+  m as WireVisualManager,
+  S as Xor4GateVisualFactory,
+  ea as Xor8GateVisualFactory,
+  oa as XorGateVisualFactory,
+  B as controllerOptions,
+  M as engineOptions,
+  T as mapControlsOptions,
+  aa as registerArithmeticComponentsFactories,
+  j as registerBasicComponentsFactories,
+  U as registerGatesComponentsFactories,
+  W as registerInterfaceComponentsFactories
 };

package/dist/scene/setup.d.ts

@@ -16,3 +16,21 @@ export declare function registerBasicComponentsFactories(registry: IGroupedFacto
  * @returns The input registry for chaining
  */
 export declare function registerGatesComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
+/**
+ * Register all arithmetic components visual factories in the arithmetic group
+ * Arithmetic components are : HalfAdder
+ * @public
+ * @param registry - A grouped factory registry to populate
+ * @returns The input registry for chaining
+ */
+export declare function registerArithmeticComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;
+/**
+ * Register all interface components visual factories in the interface group.
+ * Interface components are:
+ *  - inputs: OneInput, TwoInput, FourInput, EightInput
+ *  - lights: OneLight, TwoLight, FourLight, EightLight
+ * @public
+ * @param registry - A grouped factory registry to populate
+ * @returns The input registry for chaining
+ */
+export declare function registerInterfaceComponentsFactories(registry: IGroupedFactoryRegistry): IGroupedFactoryRegistry;

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

@@ -32,6 +32,7 @@ import * as THREE from 'three';
  */
 export declare abstract class AbstractCircuitController extends EventEmitter<ControllerEventMap> {
     protected _container: HTMLElement | null;
+    protected _renderer: THREE.WebGLRenderer | null;
     protected _scene: THREE.Scene | null;
     protected _grid: THREE.GridHelper | null;
     protected _camera: THREE.PerspectiveCamera | null;
@@ -69,18 +70,19 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
     protected get grid(): THREE.GridHelper | null;
     protected set grid(grid: THREE.GridHelper);
     /**
-     * Initialize the controller with a DOM container.
+     * Initialize the controller with a DOM container and a WebGLRenderer.
      * 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 container - HTMLElement to attach scene to (bounds, hover, mouse tracking)
+     * @param renderer - WebGLRenderer owned by the consumer; `renderer.domElement` is what MapControls binds 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;
+    initialize(container: HTMLElement, renderer: THREE.WebGLRenderer, options?: ControllerOptions): void;
     /**
      * Hook for subclasses to perform additional initialization.
      * Called after base initialization but before emitting 'ready'.
@@ -129,6 +131,12 @@ export declare abstract class AbstractCircuitController extends EventEmitter<Con
      * Get the current circuit being visualized
      */
     getCircuit(): Circuit | null;
+    /**
+     * Refresh any user-visible strings in owned widgets after the consumer has
+     * switched i18next to a new language. Default is a no-op for controllers
+     * that own no translated widgets.
+     */
+    setLanguage(_lng: string): void;
     protected abstract onSetCircuit(): void;
     /**
      * Loads a new circuit to visualize or null for clearing the scene

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

@@ -55,6 +55,21 @@ export declare class HoverManager {
      * @param normalizedY - Mouse Y in normalized HTML container coordinates [-1, 1]
      */
     updateFromMouse(normalizedX: number, normalizedY: number): void;
+    /**
+     * Raycast against the descendants of the given component object3D at the
+     * last known mouse position and return all `userData.part` strings that
+     * are currently hit.
+     *
+     * Useful when a click on a component hitbox needs to be refined to a
+     * specific sub-part (e.g. one switch among many in a multi-input
+     * component). Unlike priority hover detection this method ignores hitbox
+     * layers and walks the full sub-tree.
+     *
+     * @param componentObject3D - Root object of the component to introspect
+     * @returns De-duplicated `part` strings hit, in raycast order. Empty if
+     *          no annotated mesh is under the cursor.
+     */
+    getHoveredComponentParts(componentObject3D: THREE.Object3D): string[];
     /**
      * Force update hover state at current mouse position
      *

package/dist/scene/shared/components/arithmetic/AdderVisualFactory.d.ts

@@ -0,0 +1,54 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Adder components.
+ *
+ * Creates:
+ * - An `envelope` rectangular frame (EmptyRectangleGeometry)
+ * - A horizontal `separator` box dividing upper/lower chambers
+ * - A `sumFiller` (RectangleWithNailGeometry) in the upper chamber;
+ *   its material is animated blue↔red following the sum output state
+ * - A `plus` box inside the sumFiller (visual cue)
+ * - A `carryFiller` (RectangleWithNailGeometry) box in the lower chamber; its material is animated
+ *   blue↔red following the carry output state
+ * - pin groups for vcc, inputA, inputB, sum, carry, gnd
+ *
+ * Animation:
+ * - sumFiller ↔ blue/red based on sum output (current/next state)
+ * - carryFiller ↔ blue/red based on carry output (current/next state)
+ */
+export declare class AdderVisualFactory extends ComponentVisualFactoryBase {
+    private readonly ENVELOPE_GEOM;
+    /** Horizontal separator splitting upper/lower chambers at Z=0 */
+    private readonly SEPARATOR_GEOM;
+    private readonly SEPARATOR_SIDE_GEOM;
+    private readonly CELL_FILLER_GEOM;
+    /** Small box inside sumFiller (visual cue for the XOR "+") */
+    private readonly PLUS_GEOM;
+    protected readonly FILLER_COLOR_HIGH: THREE.Color;
+    protected readonly FILLER_COLOR_LOW: THREE.Color;
+    protected readonly FILLER_EMISSIVE_HIGH_INTENSITY = 0.5;
+    protected readonly FILLER_EMISSIVE_LOW_INTENSITY = 0.2;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    private _setFillerColor;
+    private _ensureClonedFillerMaterial;
+    private _restoreSharedFillerMaterial;
+    private _cleanupMixer;
+    /**
+     * Animate sumFiller and carryFiller fill colors over the transition span.
+     * Builds a single AnimationClip with up to two target tracks per filler
+     * (color, emissive, emissiveIntensity) — only for fillers whose value changes.
+     */
+    private _animateFillers;
+    private _pushFillerTracks;
+    /** Find a child mesh by its userData.part name */
+    protected findPartMesh(object3D: THREE.Object3D, part: string): THREE.Mesh | null;
+}

package/dist/scene/shared/components/arithmetic/EightBitAdderVisualFactory.d.ts

@@ -0,0 +1,45 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for EightBitAdder components.
+ *
+ * Creates:
+ * - An `envelope` frame (KuKoGeometry)
+ * - A vertical `separator` dividing carry/sum cells
+ * - 7 horizontal separators dividing ith cells
+ * - 16 cells carry i / sum i representing state
+ *   cells materials are animated blue↔red following the component state
+ * - pin groups for vcc, 2*8 inputs, 8*sums, carryIn, carryOut and gnd
+ *
+ */
+export declare class EightBitAdderVisualFactory extends ComponentVisualFactoryBase {
+    private readonly ENVELOPE_GEOM;
+    private readonly VERTICAL_SEPARATOR_GEOM;
+    private readonly HORIZONTAL_SEPARATOR_GEOM;
+    private readonly CELL_FILLER_GEOM;
+    protected readonly FILLER_COLOR_HIGH: THREE.Color;
+    protected readonly FILLER_COLOR_LOW: THREE.Color;
+    protected readonly FILLER_EMISSIVE_HIGH_INTENSITY = 0.5;
+    protected readonly FILLER_EMISSIVE_LOW_INTENSITY = 0.2;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    private _setCellColor;
+    private _ensureClonedMaterial;
+    private _restoreSharedMaterial;
+    private _cleanupMixer;
+    /** Collect all 16 cell meshes with their state bit position. */
+    private _findCellMeshes;
+    /**
+     * Animate the 16 cells over the transition span.
+     * Builds a single AnimationClip with tracks only for cells whose bit changes.
+     */
+    private _animateCells;
+    private _pushCellTracks;
+}

package/dist/scene/shared/components/arithmetic/EightBitOnesComplementVisualFactory.d.ts

@@ -0,0 +1,63 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for EightBitOnesComplement components.
+ *
+ * Creates:
+ * - An `envelope` frame (EmptyRectangleGeometry)
+ * - A vertical `separator` dividing flag area / outputs cells
+ * - 7 horizontal separators dividing ith cells
+ * - 2 rectangles with nail filler, 3 animated box geometry and 2 filler boxes for flag area
+ * - 8 cells outputs i representing output state
+ *   cells materials are animated blue↔red following the component state
+ * - pin groups for vcc, 8 inputs, 8*outputs and gnd
+ *
+ */
+export declare class EightBitOnesComplementVisualFactory extends ComponentVisualFactoryBase {
+    private readonly ENVELOPE_GEOM;
+    private readonly VERTICAL_SEPARATOR_GEOM;
+    private readonly HORIZONTAL_SEPARATOR_GEOM;
+    private readonly CELL_FILLER_GEOM;
+    private readonly INDICATOR_MINUS_GEOM;
+    private readonly INDICATOR_PLUS_GEOM;
+    private readonly INDICATOR_FILLER_GEOM;
+    protected readonly FILLER_COLOR_HIGH: THREE.Color;
+    protected readonly FILLER_COLOR_LOW: THREE.Color;
+    protected readonly FILLER_COLOR_NEUTRAL: THREE.Color;
+    protected readonly FILLER_EMISSIVE_BLACK: THREE.Color;
+    protected readonly FILLER_EMISSIVE_HIGH_INTENSITY = 0.5;
+    protected readonly FILLER_EMISSIVE_LOW_INTENSITY = 0.2;
+    protected readonly FILLER_EMISSIVE_NEUTRAL_INTENSITY = 0;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Resolve the target color state for a cell given its kind and the bit value:
+     * - `output`: high→red, low→blue
+     * - `minus`:  high→blue, low→red (inverted vs output — blue minus = complement active)
+     * - `plus`:   high→white (blends with envelope, hiding the +), low→red
+     */
+    private _cellTarget;
+    private _setCellColor;
+    private _ensureClonedMaterial;
+    private _restoreSharedMaterial;
+    private _cleanupMixer;
+    /**
+     * Collect all animated cells (8 outputs + minus + 2 plus parts).
+     * Output cells read bits 0–7; the three indicator cells all read bit 8
+     * (the invert flag) but render it with different color rules.
+     */
+    private _findCellMeshes;
+    /**
+     * Animate all cells over the transition span.
+     * Builds a single AnimationClip with tracks only for cells whose bit changes.
+     */
+    private _animateCells;
+    private _pushCellTracks;
+}

package/dist/scene/shared/components/arithmetic/HalfAdderVisualFactory.d.ts

@@ -0,0 +1,55 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Half Adder components.
+ *
+ * Creates:
+ * - An `envelope` rectangular frame (EmptyRectangleGeometry)
+ * - A horizontal `separator` box dividing upper/lower chambers
+ * - A `sumFiller` (RectangleWithNailGeometry) in the upper chamber;
+ *   its material is animated blue↔red following the sum output state
+ * - A `halfPlus` small box inside the sumFiller (visual cue)
+ * - A `carryFiller` box in the lower chamber; its material is animated
+ *   blue↔red following the carry output state
+ * - pin groups for vcc, inputA, inputB, sum, carry, gnd
+ *
+ * Animation:
+ * - sumFiller ↔ blue/red based on sum output (current/next state)
+ * - carryFiller ↔ blue/red based on carry output (current/next state)
+ */
+export declare class HalfAdderVisualFactory extends ComponentVisualFactoryBase {
+    private readonly ENVELOPE_GEOM;
+    /** Horizontal separator splitting upper/lower chambers at Z=0 */
+    private readonly SEPARATOR_GEOM;
+    private readonly SEPARATOR_SIDE_GEOM;
+    private readonly SUM_FILLER_GEOM;
+    /** Small box inside sumFiller (visual cue for the XOR "+") */
+    private readonly HALF_PLUS_GEOM;
+    private readonly CARRY_FILLER_GEOM;
+    protected readonly FILLER_COLOR_HIGH: THREE.Color;
+    protected readonly FILLER_COLOR_LOW: THREE.Color;
+    protected readonly FILLER_EMISSIVE_HIGH_INTENSITY = 0.5;
+    protected readonly FILLER_EMISSIVE_LOW_INTENSITY = 0.2;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    getConfigFormDefinition(config?: Map<string, string>): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    private _setFillerColor;
+    private _ensureClonedFillerMaterial;
+    private _restoreSharedFillerMaterial;
+    private _cleanupMixer;
+    /**
+     * Animate sumFiller and carryFiller fill colors over the transition span.
+     * Builds a single AnimationClip with up to two target tracks per filler
+     * (color, emissive, emissiveIntensity) — only for fillers whose value changes.
+     */
+    private _animateFillers;
+    private _pushFillerTracks;
+    /** Find a child mesh by its userData.part name */
+    protected findPartMesh(object3D: THREE.Object3D, part: string): THREE.Mesh | null;
+}

package/dist/scene/shared/components/arithmetic/index.d.ts

@@ -0,0 +1,4 @@
+export { AdderVisualFactory } from './AdderVisualFactory';
+export { HalfAdderVisualFactory } from './HalfAdderVisualFactory';
+export { EightBitAdderVisualFactory } from './EightBitAdderVisualFactory';
+export { EightBitOnesComplementVisualFactory } from './EightBitOnesComplementVisualFactory';

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

@@ -27,3 +27,17 @@ export { Nor8GateVisualFactory } from './gates/Nor8GateVisualFactory';
 export { XorGateVisualFactory } from './gates/XorGateVisualFactory';
 export { Xor4GateVisualFactory } from './gates/Xor4GateVisualFactory';
 export { Xor8GateVisualFactory } from './gates/Xor8GateVisualFactory';
+export { HalfAdderVisualFactory } from './arithmetic/HalfAdderVisualFactory';
+export { AdderVisualFactory } from './arithmetic/AdderVisualFactory';
+export { EightBitAdderVisualFactory } from './arithmetic/EightBitAdderVisualFactory';
+export { EightBitOnesComplementVisualFactory } from './arithmetic/EightBitOnesComplementVisualFactory';
+export { InputVisualFactoryBase } from './interface/InputVisualFactoryBase';
+export { OneInputVisualFactory } from './interface/OneInputVisualFactory';
+export { TwoInputVisualFactory } from './interface/TwoInputVisualFactory';
+export { FourInputVisualFactory } from './interface/FourInputVisualFactory';
+export { EightInputVisualFactory } from './interface/EightInputVisualFactory';
+export { LightVisualFactoryBase } from './interface/LightVisualFactoryBase';
+export { OneLightVisualFactory } from './interface/OneLightVisualFactory';
+export { TwoLightVisualFactory } from './interface/TwoLightVisualFactory';
+export { FourLightVisualFactory } from './interface/FourLightVisualFactory';
+export { EightLightVisualFactory } from './interface/EightLightVisualFactory';

package/dist/scene/shared/components/interface/EightInputVisualFactory.d.ts

@@ -0,0 +1,15 @@
+import { Component } from '../../../../core/index.ts';
+import { VisualContext } from '../../types';
+import { InputVisualFactoryBase } from './InputVisualFactoryBase';
+import * as THREE from 'three';
+/** Visual factory for the EightInput component (eight-switch user input). */
+export declare class EightInputVisualFactory extends InputVisualFactoryBase {
+    protected readonly bitCount = 8;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 8.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/EightLightVisualFactory.d.ts

@@ -0,0 +1,15 @@
+import { Component } from '../../../../core/index.ts';
+import { VisualContext } from '../../types';
+import { LightVisualFactoryBase } from './LightVisualFactoryBase';
+import * as THREE from 'three';
+/** Visual factory for the EightLight component (eight-light input mirror). */
+export declare class EightLightVisualFactory extends LightVisualFactoryBase {
+    protected readonly bitCount = 8;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 8.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/FourInputVisualFactory.d.ts

@@ -0,0 +1,15 @@
+import { Component } from '../../../../core/index.ts';
+import { VisualContext } from '../../types';
+import { InputVisualFactoryBase } from './InputVisualFactoryBase';
+import * as THREE from 'three';
+/** Visual factory for the FourInput component (four-switch user input). */
+export declare class FourInputVisualFactory extends InputVisualFactoryBase {
+    protected readonly bitCount = 4;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 4.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/FourLightVisualFactory.d.ts

@@ -0,0 +1,15 @@
+import { Component } from '../../../../core/index.ts';
+import { VisualContext } from '../../types';
+import { LightVisualFactoryBase } from './LightVisualFactoryBase';
+import * as THREE from 'three';
+/** Visual factory for the FourLight component (four-light input mirror). */
+export declare class FourLightVisualFactory extends LightVisualFactoryBase {
+    protected readonly bitCount = 4;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 4.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}