simple-circuit-engine 0.0.12 → 0.0.13

package/AGENTS.md

@@ -160,6 +160,7 @@ engine.on('simulationTick', (state) => { ... });
 
 ```json
 {
-  "three": "^0.183.2"
+  "three": "^0.183.2",
+  "i18next": ">=25.0.0 <27.0.0"
 }
 ```

package/CLAUDE.md

@@ -18,6 +18,7 @@ However, it aims to teach real-world electronic design principles so modeling of
 - 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
+- i18next for internationalization (see `src/i18n/CLAUDE.md` for conventions)
 - in-memory circuit model, optional loading/saving from/to a JSON file
 
 ## Project Structure
@@ -26,6 +27,7 @@ Simple Circuit Engine follows a **Model-Controller** architecture with clear sep
 
 - **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**.
+- **i18next Internationalization** (`src/i18n/`) : localization setup and locales
 
 ### Core Module (`src/core/`)
 

package/dist/core/index.js

@@ -1,77 +1,87 @@
-import { $ as t, A as e, B as s, C as o, D as i, E as r, F as n, G as S, H as h, I as v, J as B, K as G, L as c, M as l, N, O as E, P as p, Q as T, R as m, S as u, T as C, U as I, V as L, W as D, X as d, Y as y, Z as g, _, _t as A, a as R, at as M, b as O, bt as b, c as P, ct as w, d as U, dt as X, et as f, f as F, ft as k, g as x, gt as z, h as Y, ht as Q, i as V, it as W, j, k as q, l as H, lt as J, m as K, mt as Z, n as $, nt as aa, o as ta, ot as ea, p as sa, pt as oa, q as ia, r as ra, rt as na, s as Sa, st as ha, t as va, tt as Ba, u as Ga, ut as ca, v as la, vt as Na, w as Ea, x as pa, y as Ta, yt as ma, z as ua } from "../core-Bjta9Y7_.js";
+import { $ as t, A as e, At as s, B as i, C as o, Ct as r, D as n, Dt as S, E as h, Et as B, F as v, G as d, H as l, I as E, J as m, K as c, L as G, M as p, N as C, O as N, Ot as A, P as T, Q as g, R as u, S as I, St as L, T as D, Tt as y, U as O, V as _, W as R, X as M, Y as b, Z as f, _ as w, _t as P, a as U, at as X, b as F, bt as k, c as x, ct as z, d as H, dt as Y, et as Q, f as V, ft as W, g as j, gt as q, h as J, ht as K, i as Z, it as $, j as aa, k as ta, kt as ea, l as sa, lt as ia, m as oa, mt as ra, n as na, nt as Sa, o as ha, ot as Ba, p as va, pt as da, q as la, r as Ea, rt as ma, s as ca, st as Ga, t as pa, tt as Ca, u as Na, ut as Aa, v as Ta, vt as ga, w as ua, wt as Ia, x as La, xt as Da, y as ya, yt as Oa, z as _a } from "../core-b6Q8w2sn.js";
 export {
-  M as ALL_LOGIC_FAMILIES,
-  Ea as BatteryBehavior,
-  D as BatteryState,
-  r as BehaviorRegistry,
-  ea as CIRCUIT_FILE_VERSION,
-  ha as COMPONENT_TYPE_METADATA,
-  A as CameraOptions,
-  d as Circuit,
-  f as CircuitMetadata,
-  Ba as CircuitOptions,
-  ra as CircuitRunner,
-  _ as ClockBehavior,
-  c as ClockState,
-  aa as Component,
-  S as ComponentState,
-  w as ComponentType,
-  J as DEFAULT_LOGIC_FAMILY,
-  R as DirtyTracker,
-  la as DoubleThrowSwitchBehavior,
+  K as ALL_LOGIC_FAMILIES,
+  Na as AdderBehavior,
+  T as AdderState,
+  E as ArithmeticState,
+  ta as BatteryBehavior,
+  Q as BatteryState,
+  aa as BehaviorRegistry,
+  q as CIRCUIT_FILE_VERSION,
+  P as COMPONENT_TYPE_METADATA,
+  S as CameraOptions,
+  Ba as Circuit,
+  Aa as CircuitMetadata,
+  Y as CircuitOptions,
+  Z as CircuitRunner,
+  I as ClockBehavior,
+  la as ClockState,
+  W as Component,
+  Ca as ComponentState,
+  ga as ComponentType,
+  Oa as DEFAULT_LOGIC_FAMILY,
+  ha as DirtyTracker,
+  o as DoubleThrowSwitchBehavior,
   m as DoubleThrowSwitchState,
-  W as ENode,
-  ca as ENodeSourceType,
-  X as ENodeType,
-  ta as EventQueue,
-  x as InverterBehavior,
-  v as InverterState,
-  o as LightbulbBehavior,
-  I as LightbulbState,
-  ma as Memoize,
-  b as MemoizeExpiring,
-  K as Nand4GateBehavior,
-  p as Nand4GateState,
-  sa as Nand8GateBehavior,
-  N as Nand8GateState,
-  Y as NandGateBehavior,
-  n as NandGateState,
-  U as Nor4GateBehavior,
-  j as Nor4GateState,
-  Ga as Nor8GateBehavior,
-  e as Nor8GateState,
-  F as NorGateBehavior,
+  ra as ENode,
+  k as ENodeSourceType,
+  Da as ENodeType,
+  sa as EightBitAdderBehavior,
+  C as EightBitAdderState,
+  x as EightBitOnesComplementBehavior,
+  p as EightBitOnesComplementState,
+  ca as EventQueue,
+  H as HalfAdderBehavior,
+  v as HalfAdderState,
+  La as InverterBehavior,
+  c as InverterState,
+  N as LightbulbBehavior,
+  t as LightbulbState,
+  ea as Memoize,
+  s as MemoizeExpiring,
+  ya as Nand4GateBehavior,
+  R as Nand4GateState,
+  Ta as Nand8GateBehavior,
+  O as Nand8GateState,
+  F as NandGateBehavior,
+  d as NandGateState,
+  j as Nor4GateBehavior,
+  _ as Nor4GateState,
+  J as Nor8GateBehavior,
+  i as Nor8GateState,
+  w as NorGateBehavior,
   l as NorGateState,
-  Z as Position,
-  Na as Position3D,
-  u as RectangleLEDBehavior,
-  L as RectangleLEDState,
-  pa as RelayBehavior,
-  s as RelayState,
-  oa as Rotation,
-  B as SIMULATION_SPEED,
-  G as SimulationState,
-  O as SmallLEDBehavior,
-  h as SmallLEDState,
-  V as StateManager,
-  Ta as SwitchBehavior,
-  ua as SwitchState,
-  y as TRANSITION_DEFAULTS,
-  na as Wire,
-  P as Xor4GateBehavior,
-  E as Xor4GateState,
-  Sa as Xor8GateBehavior,
-  i as Xor8GateState,
-  H as XorGateBehavior,
-  q as XorGateState,
-  g as classifyGate,
-  T as computeGateDelay,
-  t as computeTransitionSpan,
-  Q as findPositionBestIndex,
-  k as generateUUID,
-  C as getTransitionSpan,
-  va as registerBasicComponentsBehaviors,
-  $ as registerGatesComponentsBehaviors,
-  z as simplifyPositions,
-  ia as unionElectricalStates
+  Ia as Position,
+  A as Position3D,
+  n as RectangleLEDBehavior,
+  f as RectangleLEDState,
+  h as RelayBehavior,
+  M as RelayState,
+  r as Rotation,
+  $ as SIMULATION_SPEED,
+  Sa as SimulationState,
+  D as SmallLEDBehavior,
+  g as SmallLEDState,
+  U as StateManager,
+  ua as SwitchBehavior,
+  b as SwitchState,
+  X as TRANSITION_DEFAULTS,
+  da as Wire,
+  va as Xor4GateBehavior,
+  u as Xor4GateState,
+  V as Xor8GateBehavior,
+  G as Xor8GateState,
+  oa as XorGateBehavior,
+  _a as XorGateState,
+  Ga as classifyGate,
+  z as computeGateDelay,
+  ia as computeTransitionSpan,
+  y as findPositionBestIndex,
+  L as generateUUID,
+  e as getTransitionSpan,
+  pa as registerArithmeticComponentsBehaviors,
+  na as registerBasicComponentsBehaviors,
+  Ea as registerGatesComponentsBehaviors,
+  B as simplifyPositions,
+  ma as unionElectricalStates
 };

package/dist/core/setup.d.ts

@@ -15,3 +15,11 @@ export declare function registerBasicComponentsBehaviors(registry: BehaviorRegis
  * @return the input behavior registry for chaining
  */
 export declare function registerGatesComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;
+/**
+ * Register all arithmetic component behaviors in the given registry
+ * Arithmetic components are : HalfAdder, Adder, 8bit adder, 8bit one's complement
+ * @public
+ * @param registry
+ * @return the input behavior registry for chaining
+ */
+export declare function registerArithmeticComponentsBehaviors(registry: BehaviorRegistry): BehaviorRegistry;

package/dist/core/simulation/behaviors/arithmetic/AdderBehavior.d.ts

@@ -0,0 +1,28 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the Full Adder component (two half adders + OR on carries).
+ *
+ * Three logic inputs (`inputA`, `inputB`, `carryIn`) and two logic outputs
+ * (`sum`, `carryOut`):
+ *
+ * - `sum = A XOR B XOR carryIn` (parity of the three inputs)
+ * - `carryOut = majority(A, B, carryIn)` (two or more inputs high)
+ *
+ * State encoding follows `${sumBit}${carryBit}` — see {@link AdderState}. All
+ * four stable states are reachable; `A = B = carryIn = 1` yields `'11'`.
+ *
+ * A single medium `transitionSpan` from config is used for every transition,
+ * since modeling the cumulative XOR/AND/OR delays per input-output pair would
+ * be more complexity than this library's teaching scope warrants.
+ *
+ * @public
+ */
+export declare class AdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/ArithmeticBehaviorMixin.d.ts

@@ -0,0 +1,63 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { UUID } from '../../../utils/types';
+import { ENodeSourceType } from '../../../topology/types';
+import { IBehaviorResult } from '../types';
+import { IScheduledEvent } from '../../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { ArithmeticState } from '../../states/arithmetic/ArithmeticState';
+/**
+ * Factorises the common plumbing of arithmetic component behaviors:
+ *
+ * - `vccGuardBehavior` — on vcc loss, drop all outputs low immediately.
+ * - `nonLogicInputGuardBehavior` — on any ill-defined logic input, go to
+ *   `'indeterminate'` immediately.
+ * - `onPinsChange` is a **template method** that runs the guards then calls
+ *   `computeTargetStableState` (subclass-provided) and schedules the
+ *   transition via `scheduleTransition`.
+ * - `scheduleTransition` — encode the `to${target}` transient state, schedule
+ *   the completion event and preserve the previous stable state in
+ *   `parameters.prevState` so `allowConductivity` keeps the old outputs
+ *   energized until the transition fires.
+ * - `onEventFiring` — land on the target stable state when the scheduled
+ *   transition completes.
+ * - `allowConductivity` — generic per-output lookup driven by
+ *
+ * Subclasses must declare `outputPinLabels` in the **same order** as the
+ * state encoding used by their {@link ArithmeticState} subclass and
+ * implement `computeTargetStableState` to turn the current input pins into
+ * that encoding.
+ */
+export declare abstract class ArithmeticBehaviorMixin extends ComponentBehaviorMixin {
+    /**
+     * Compute the target stable-state encoding from the current pin states.
+     * Called only after vcc / non-logic guards have passed.
+     */
+    protected abstract computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(_component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    /**
+     * On vcc loss: all outputs go low immediately.
+     * Returns `null` when vcc is present so callers can proceed.
+     */
+    protected vccGuardBehavior(state: ArithmeticState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * Scan all logic inputs; if any is ill-defined (both voltage and ground,
+     * or neither), switch to `'indeterminate'` immediately. Otherwise returns
+     * `null` so the caller can proceed.
+     */
+    protected nonLogicInputGuardBehavior(state: ArithmeticState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * Schedule a transition toward the given stable target state. If already
+     * there (or already heading there) returns a no-change result.
+     *
+     * Preserves the currently-driving stable state in `parameters.prevState` so
+     * `allowConductivity` keeps the old outputs energized until the scheduled
+     * event fires. When the previous effective state is `'indeterminate'` the
+     * fallback is all-zeros.
+     */
+    protected scheduleTransition(component: Component, state: ArithmeticState, targetState: string, targetTick: number): IBehaviorResult;
+    protected noChange(state: ComponentState): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/arithmetic/EightBitAdderBehavior.d.ts

@@ -0,0 +1,51 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior, IBehaviorResult } from '../types';
+import { IScheduledEvent } from '../../types';
+import { UUID } from '../../../utils/types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the 8-bit ripple carry adder (8 full adders in series).
+ *
+ * Unlike the single full adder whose output settles in one transition, the
+ * 8-bit adder models **carry propagation**: when inputs change, only stage 0
+ * recomputes immediately (with its own propagation delay); the carry then
+ * ripples through stages 1–7, one `transitionSpan` per stage.
+ *
+ * ### State encoding
+ *
+ * 16 interleaved bits `C7S7 C6S6 … C1S1 C0S0` stored as a 4-digit hex
+ * string. Sum at bit `2*i`, carry at bit `2*i+1`.
+ * See {@link EightBitAdderState}.
+ *
+ * ### Ripple algorithm
+ *
+ * - **`onPinsChange`**: computes ALL 8 stages with new inputs but **old
+ *   carries** from the current effective state, producing an intermediate
+ *   state. Schedules one event for carry propagation starting at stage 1.
+ *   Uses `shouldCancelPending: true` to restart the ripple cleanly when
+ *   inputs change mid-propagation.
+ *
+ * - **`onEventFiring`**: lands on the intermediate, then checks whether the
+ *   next stage's carry-in changed. If so, recomputes that stage, builds the
+ *   next intermediate, and schedules the following stage. If not, the carry
+ *   has stopped and the state is stable. Uses `shouldCancelPending: false`.
+ *
+ * - **Initialization shortcut**: at `targetTick === 0` the full stable state
+ *   is computed directly via {@link computeTargetStableState} to avoid the
+ *   init-loop limitation where chained events are dropped.
+ *
+ * @public
+ */
+export declare class EightBitAdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    onPinsChange(component: Component, state: ComponentState, nodeStates: ReadonlyMap<UUID, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    onEventFiring(component: Component, state: ComponentState, event: IScheduledEvent): IBehaviorResult;
+    /**
+     * Compute the fully-settled stable state by propagating the carry chain
+     * through all 8 stages. Used at initialization and for test verification.
+     */
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/EightBitOnesComplementBehavior.d.ts

@@ -0,0 +1,29 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ENodeSourceType } from '../../../topology/types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the 8-bit one's complement (8 parallel XOR gates with shared
+ * `invert` input).
+ *
+ * When `invert` is high every output is the bitwise NOT of its input; when low
+ * outputs pass through unchanged. All 8 gates fire in parallel — a single
+ * `transitionSpan` covers the whole transition (no ripple).
+ *
+ * State encoding: 9 bits as a 3-hex-char string. Bits 0–7 are outputs,
+ * bit 8 is the invert flag. See {@link EightBitOnesComplementState}.
+ *
+ * The mixin's default `onPinsChange` / `onEventFiring` / `scheduleTransition`
+ * handle everything — only `computeTargetStableState` and
+ * `allowConductivity` need implementation.
+ *
+ * @public
+ */
+export declare class EightBitOnesComplementBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    allowConductivity(component: Component, state: ComponentState, _conductivityType: ENodeSourceType, pinId: string, otherPinId: string): boolean;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/HalfAdderBehavior.d.ts

@@ -0,0 +1,22 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { INodeElectricalState } from '../../states/types';
+import { IComponentBehavior } from '../types';
+import { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+/**
+ * Behavior for the Half Adder component (XOR + AND in one block).
+ *
+ * - `sum = A XOR B`
+ * - `carry = A AND B`
+ *
+ * State encoding follows `${sumBit}${carryBit}` — see {@link HalfAdderState}.
+ * Because `sum` and `carry` can never both be high, only three stable states
+ * are reachable: `'00' | '10' | '01'`.
+ *
+ * @public
+ */
+export declare class HalfAdderBehavior extends ArithmeticBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+    protected computeTargetStableState(pinStates: Map<string, INodeElectricalState>): string;
+}

package/dist/core/simulation/behaviors/arithmetic/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Arithmetic components behaviors
+ * @module core/simulation/behaviors
+ */
+export { ArithmeticBehaviorMixin } from './ArithmeticBehaviorMixin';
+export { HalfAdderBehavior } from './HalfAdderBehavior';
+export { AdderBehavior } from './AdderBehavior';

package/dist/core/simulation/behaviors/index.d.ts

@@ -22,3 +22,7 @@ export { Nor8GateBehavior } from './gates/Nor8GateBehavior';
 export { XorGateBehavior } from './gates/XorGateBehavior';
 export { Xor4GateBehavior } from './gates/Xor4GateBehavior';
 export { Xor8GateBehavior } from './gates/Xor8GateBehavior';
+export { HalfAdderBehavior } from './arithmetic/HalfAdderBehavior';
+export { AdderBehavior } from './arithmetic/AdderBehavior';
+export { EightBitAdderBehavior } from './arithmetic/EightBitAdderBehavior';
+export { EightBitOnesComplementBehavior } from './arithmetic/EightBitOnesComplementBehavior';

package/dist/core/simulation/states/arithmetic/AdderState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for Full Adder components.
+ *
+ * Hex-encoded stable states: `'0'` (both low), `'1'` (sum high),
+ * `'2'` (carry high), `'3'` (both high). All four are reachable;
+ * in particular `A = B = carryIn = 1` yields `'3'`.
+ *
+ * @public
+ */
+export declare class AdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    get sumHigh(): boolean;
+    get carryOutHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/ArithmeticState.d.ts

@@ -0,0 +1,53 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for arithmetic components (half adder, full adder and
+ * future multi-bit adders, multiplexers, ...).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output. Simple components use one bit per
+ * output in declaration order (bit 0 = first logicOutput). For example a
+ * half-adder with sum (bit 0) and carry (bit 1) uses `'0'`..`'3'`.
+ *
+ * Components with internal carry chains (e.g. 8-bit ripple adder) use an
+ * **interleaved** encoding `CiSi` where sum occupies even bits (`2*i`) and
+ * carry occupies odd bits (`2*i + 1`). This stores intermediate carries for
+ * ripple animation, giving `outputCount = 2 * stageCount` (e.g. 16 bits /
+ * 4 hex digits for 8 stages, states `'0000'`..`'ffff'`).
+ *
+ * Transient (in-flight) states follow the `to${nextState}` convention so
+ * animations can be driven generically from `state`/`nextState`. The
+ * previously-held stable state is preserved in `parameters.prevState` so the
+ * behavior's `allowConductivity` keeps the old outputs energized until the
+ * transition fires.
+ *
+ * A special `'indeterminate'` state is used when any logic input is ill-defined.
+ *
+ * @public
+ */
+export declare abstract class ArithmeticState extends ComponentState {
+    /**
+     * Number of logic outputs for this state
+     * (e.g. 2 for half/full adder, 9 for an 8-bit adder: 8 sum bits + carry out).
+     */
+    readonly outputCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 2 outputs, `'000'` for 9). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, outputCount: number, initialState: string);
+    /** True when the current state is a transient `to${stable}` transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable state → returns that state
+     * - transient `to<hex>` → returns the previous stable kept in parameters
+     * - `'indeterminate'` → returns `'indeterminate'`
+     */
+    get effectiveState(): string;
+    /**
+     * Whether the `index`-th output is high in the current effective state.
+     * Returns `false` when effective state is `'indeterminate'`.
+     */
+    isOutputHigh(index: number): boolean;
+}

package/dist/core/simulation/states/arithmetic/EightBitAdderState.d.ts

@@ -0,0 +1,25 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for the 8-bit ripple carry adder.
+ *
+ * Uses an interleaved 16-bit encoding `C7S7 C6S6 … C1S1 C0S0` where each
+ * stage occupies two bits: sum at even position (`2*i`) and carry at odd
+ * position (`2*i + 1`). This stores intermediate carries so the ripple
+ * animation can show carry propagation stage by stage.
+ *
+ * Stable states range from `'0000'` (all low) to `'ffff'` (all high).
+ * The external outputs are `sum-0`..`sum-7` (bits 0,2,4,…,14) and
+ * `carryOut` (bit 15 = C7).
+ *
+ * @public
+ */
+export declare class EightBitAdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    /** Whether stage `i`'s sum output is high in the current effective state. */
+    isSumHigh(stageIndex: number): boolean;
+    /** Whether stage `i`'s internal carry is high in the current effective state. */
+    isStageCarryHigh(stageIndex: number): boolean;
+    /** Whether the final carry out (C7) is high — drives the `carryOut` pin. */
+    isCarryOutHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/EightBitOnesComplementState.d.ts

@@ -0,0 +1,18 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for the 8-bit one's complement (8 parallel XOR gates).
+ *
+ * Uses a 9-bit encoding stored as a 3-digit hex string (`'000'`..`'1ff'`):
+ * - Bits 0–7: output values (`output-i = input-i XOR invert`)
+ * - Bit 8: current invert input value (stored for animation)
+ *
+ * @public
+ */
+export declare class EightBitOnesComplementState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    /** Whether output bit `index` (0–7) is high in the current effective state. */
+    isOutputBitHigh(index: number): boolean;
+    /** Whether the invert flag (bit 8) is high in the current effective state. */
+    isInvertHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/HalfAdderState.d.ts

@@ -0,0 +1,16 @@
+import { UUID } from '../../../utils/types';
+import { ArithmeticState } from './ArithmeticState';
+/**
+ * Simulation state for Half Adder components.
+ *
+ * Hex-encoded stable states: `'0'` (both low), `'1'` (sum high),
+ * `'2'` (carry high). `'3'` is unreachable because `sum = A XOR B`
+ * and `carry = A AND B` can never both be true.
+ *
+ * @public
+ */
+export declare class HalfAdderState extends ArithmeticState {
+    constructor(componentId: UUID, initialState?: string);
+    get sumHigh(): boolean;
+    get carryHigh(): boolean;
+}

package/dist/core/simulation/states/arithmetic/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Arithmetic components simulation states
+ * @module core/simulation/states
+ */
+export { ArithmeticState } from './ArithmeticState';
+export { HalfAdderState } from './HalfAdderState';
+export { AdderState } from './AdderState';

package/dist/core/simulation/states/index.d.ts

@@ -24,3 +24,8 @@ export { Nor8GateState } from './gates/Nor8GateState';
 export { XorGateState } from './gates/XorGateState';
 export { Xor4GateState } from './gates/Xor4GateState';
 export { Xor8GateState } from './gates/Xor8GateState';
+export { ArithmeticState } from './arithmetic/ArithmeticState';
+export { HalfAdderState } from './arithmetic/HalfAdderState';
+export { AdderState } from './arithmetic/AdderState';
+export { EightBitAdderState } from './arithmetic/EightBitAdderState';
+export { EightBitOnesComplementState } from './arithmetic/EightBitOnesComplementState';

package/dist/core/simulation/types.d.ts

@@ -11,7 +11,7 @@ export declare const SIMULATION_SPEED: {
     /**
      * Maximum simulation speed in ticks per second
      */
-    readonly MAX_TPS: 50;
+    readonly MAX_TPS: 100;
     /**
      * Default simulation speed in ticks per second
      */

package/dist/core/topology/Component.d.ts

@@ -1,5 +1,5 @@
 import { UUID, Position, Rotation } from '../utils';
-import { ComponentType, IComponent } from './types';
+import { ComponentType, IComponent, IPinMetadata } from './types';
 /**
  * Electrical component placed on the circuit grid.
  *
@@ -96,6 +96,7 @@ export declare class Component {
      */
     constructor(type: ComponentType, position: Position, rotation: Rotation, pins: ReadonlyArray<UUID>, editable?: boolean);
     getPinLabel(pinId: UUID): string | undefined;
+    getPinMetadata(pinId: UUID): IPinMetadata | undefined;
     setAllParameters(config: Map<string, string>): void;
     setParameter(key: string, value: string): void;
     /**