simple-circuit-engine 0.0.12 → 0.0.14

package/dist/core/simulation/behaviors/interface/LightBehaviorMixin.d.ts

@@ -0,0 +1,60 @@
+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 { IScheduledEvent } from '../../types';
+import { IBehaviorResult } from '../types';
+import { ComponentBehaviorMixin } from '../ComponentBehavior';
+import { LightState } from '../../states/interface/LightState';
+/**
+ * Factorises the plumbing shared by `OneLight`, `TwoLight`, `FourLight` and
+ * `EightLight` behaviors.
+ *
+ * These components mirror their `input-i` pins onto matching `output-i` pins
+ * with a per-light `transitionSpan` delay. The state encodes the current
+ * outputs as a hex value (e.g. `'5'` = `0101` for FourLight); while at least
+ * one light is moving the state literal is `'moving'` and a parameter map
+ * tracks each pending light (`${index}` → `${target}-${startTick}-${endTick}`)
+ * plus the actual driving value in `prevState`.
+ *
+ * Guards (run first in `onPinsChange`):
+ * - Vcc loss collapses the state to `allLowState` and clears all pending.
+ * - Any ill-defined logic input switches the state to `'indeterminate'`.
+ *
+ * Concurrency model (per-light, independent transitions):
+ * - When an input changes, the target output bit is recomputed; if it differs
+ *   from the currently-driving (or already-pending) target a `lightChanged`
+ *   event is scheduled with a per-light span.
+ * - If the same input toggles while its light is still moving, the symmetric
+ *   transition pattern shortens the new span to `Math.max(prevEnd - prevStart, 1)`
+ *   and the in-flight event becomes a no-op (its readyAtTick no longer matches
+ *   the pending entry).
+ * - `shouldCancelPending: false` outside guards — other lights' transitions
+ *   keep their schedule.
+ *
+ * @public
+ */
+export declare abstract class LightBehaviorMixin extends ComponentBehaviorMixin {
+    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: drop all outputs low immediately and clear any pending
+     * transitions. Returns `null` when vcc is present so callers can proceed.
+     */
+    protected vccGuardBehavior(state: LightState, 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 and clear any pending
+     * transitions. Otherwise returns `null` so the caller can proceed.
+     */
+    protected nonLogicInputGuardBehavior(state: LightState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult | null;
+    /**
+     * For each logic input, compute the desired output bit and schedule a
+     * per-light `lightChanged` event whenever that bit differs from the current
+     * effective (or already-pending) target.
+     */
+    protected scheduleInputTransitions(component: Component, state: LightState, pinStates: Map<string, INodeElectricalState>, targetTick: number): IBehaviorResult;
+    protected noChange(state: ComponentState): IBehaviorResult;
+}

package/dist/core/simulation/behaviors/interface/OneInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Single-switch user input. See {@link InputBehaviorMixin}. */
+export declare class OneInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/OneLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Single-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class OneLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/TwoInputBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { InputBehaviorMixin } from './InputBehaviorMixin';
+/** Two-switch user input. See {@link InputBehaviorMixin}. */
+export declare class TwoInputBehavior extends InputBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

package/dist/core/simulation/behaviors/interface/TwoLightBehavior.d.ts

@@ -0,0 +1,9 @@
+import { Component } from '../../../topology/Component';
+import { ComponentState } from '../../states/ComponentState';
+import { IComponentBehavior } from '../types';
+import { LightBehaviorMixin } from './LightBehaviorMixin';
+/** Two-light input mirror. See {@link LightBehaviorMixin}. */
+export declare class TwoLightBehavior extends LightBehaviorMixin implements IComponentBehavior {
+    constructor();
+    createInitialState(component: Component): ComponentState;
+}

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,18 @@ 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';
+export { InputState } from './interface/InputState';
+export { OneInputState } from './interface/OneInputState';
+export { TwoInputState } from './interface/TwoInputState';
+export { FourInputState } from './interface/FourInputState';
+export { EightInputState } from './interface/EightInputState';
+export { LightState } from './interface/LightState';
+export { OneLightState } from './interface/OneLightState';
+export { TwoLightState } from './interface/TwoLightState';
+export { FourLightState } from './interface/FourLightState';
+export { EightLightState } from './interface/EightLightState';

package/dist/core/simulation/states/interface/EightInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Eight-switch user input. Stable states `'00'`..`'ff'`. */
+export declare class EightInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/EightLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Eight-light input mirror. Stable states `'00'`–`'ff'`. */
+export declare class EightLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/FourInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Four-switch user input. Stable states `'0'`..`'f'`. */
+export declare class FourInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/FourLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Four-light input mirror. Stable states `'0'`–`'f'`. */
+export declare class FourLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/InputState.d.ts

@@ -0,0 +1,45 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for user-controlled input components (OneInput,
+ * TwoInput, FourInput, EightInput).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output (bit `i` ↔ `output-i`).
+ *
+ * While at least one switch is moving, the state value is the literal
+ * `'moving'` and the `parameters` map carries:
+ * - `prevState`: the stable hex value the outputs are still energizing
+ * - one entry per pending switch keyed by its index, encoded as
+ *   `${target}-${startTick}-${endTick}` (target ∈ {0,1}).
+ *
+ * @public
+ */
+export declare abstract class InputState extends ComponentState {
+    /** Number of logic outputs (1, 2, 4 or 8). */
+    readonly outputCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 1–4 outputs, `'00'` for 8). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, outputCount: number, initialState: string);
+    /** True while at least one switch is mid-transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable state → returns that state
+     * - `'moving'` → returns the previous stable kept in `parameters.prevState`
+     */
+    get effectiveState(): string;
+    /** Whether output `index` is high in the current effective state. */
+    isOutputHigh(index: number): boolean;
+    /**
+     * Pending move descriptor for switch `index`, parsed from the parameter map,
+     * or `null` when no transition is in flight for that switch.
+     */
+    getPendingMove(index: number): {
+        target: 0 | 1;
+        startTick: number;
+        endTick: number;
+    } | null;
+}

package/dist/core/simulation/states/interface/LightState.d.ts

@@ -0,0 +1,54 @@
+import { UUID } from '../../../utils/types';
+import { ComponentState } from '../ComponentState';
+/**
+ * Base simulation state for input-driven multi-light components (OneLight,
+ * TwoLight, FourLight, EightLight).
+ *
+ * Stable states are encoded as a zero-padded hexadecimal string where each
+ * bit position maps to one logic output (bit `i` ↔ `output-i`). Outputs
+ * mirror their corresponding `input-i` after `transitionSpan` ticks so the
+ * component can be cascaded.
+ *
+ * While at least one light is moving, the state value is the literal
+ * `'moving'` and the `parameters` map carries:
+ * - `prevState`: the stable hex value the outputs are still energizing
+ * - one entry per pending light keyed by its index, encoded as
+ *   `${target}-${startTick}-${endTick}` (target ∈ {0,1}).
+ *
+ * A special `'indeterminate'` state is used when any logic input is
+ * ill-defined (set immediately by the non-logic-input guard).
+ *
+ * @public
+ */
+export declare abstract class LightState extends ComponentState {
+    /** Number of lights / logic outputs (1, 2, 4 or 8). */
+    readonly lightCount: number;
+    /** Number of hex digits needed to encode all outputs. */
+    readonly hexDigitCount: number;
+    /** All-outputs-low state string (e.g. `'0'` for 1–4 lights, `'00'` for 8). */
+    readonly allLowState: string;
+    protected constructor(componentId: UUID, lightCount: number, initialState: string);
+    /** True while at least one light is mid-transition. */
+    get isInTransition(): boolean;
+    /**
+     * Stable state that effectively drives the outputs right now:
+     * - stable hex state → returns that state
+     * - `'moving'` → returns the previous stable kept in `parameters.prevState`
+     * - `'indeterminate'` → returns `'indeterminate'`
+     */
+    get effectiveState(): string;
+    /**
+     * Whether output `index` is high in the current effective state.
+     * Returns `false` when effective state is `'indeterminate'`.
+     */
+    isOutputHigh(index: number): boolean;
+    /**
+     * Pending move descriptor for light `index`, parsed from the parameter map,
+     * or `null` when no transition is in flight for that light.
+     */
+    getPendingMove(index: number): {
+        target: 0 | 1;
+        startTick: number;
+        endTick: number;
+    } | null;
+}

package/dist/core/simulation/states/interface/OneInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Single-switch user input. Stable states `'0'` and `'1'`. */
+export declare class OneInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/OneLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Single-light input mirror. Stable states `'0'` and `'1'`. */
+export declare class OneLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/TwoInputState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { InputState } from './InputState';
+/** Two-switch user input. Stable states `'0'`..`'3'`. */
+export declare class TwoInputState extends InputState {
+    constructor(componentId: UUID, initialState?: string);
+}

package/dist/core/simulation/states/interface/TwoLightState.d.ts

@@ -0,0 +1,6 @@
+import { UUID } from '../../../utils/types';
+import { LightState } from './LightState';
+/** Two-light input mirror. Stable states `'0'`–`'3'`. */
+export declare class TwoLightState extends LightState {
+    constructor(componentId: UUID, initialState?: string);
+}

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
      */
@@ -44,8 +44,13 @@ export declare const TRANSITION_DEFAULTS: {
 export interface IUserCommand {
     /**
      * Type of command.
+     *
+     * - `toggle_switch`: flip a (double-throw) switch component.
+     * - `toggle_input`: flip one switch of a multi-switch input component
+     *   (OneInput, TwoInput, FourInput, EightInput); `parameters` MUST carry
+     *   `index` identifying which switch was toggled.
      */
-    readonly type: 'toggle_switch';
+    readonly type: 'toggle_switch' | 'toggle_input';
     /**
      * UUID of target component.
      */
@@ -61,6 +66,9 @@ export interface IUserCommand {
      * - `tickCount`: Number of ticks for the switch transition. Computed at toggle time
      *   using the formula: `ceil(transitionUserSpan × simulationSpeed / 1000)` with minimum of 1.
      *   If not provided, behavior uses default transition timing.
+     *
+     * For `toggle_input` commands:
+     * - `index`: index of the toggled switch within the multi-switch component.
      */
     readonly parameters?: Map<string, string> | null;
 }

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,11 @@ 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;
+    /** Resolve the ENode UUID of the logic pin at `index` within `interfaceName`, or undefined. */
+    getPinIdByInterface(interfaceName: string, index: number): UUID | undefined;
+    /** Largest index found across pins of the given logic interface, or -1 if none. */
+    getInterfaceMaxIndex(interfaceName: string): number;
     setAllParameters(config: Map<string, string>): void;
     setParameter(key: string, value: string): void;
     /**

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

@@ -1,5 +1,5 @@
 import { UUID, Position } from '../utils';
-import { ENodeSourceType, ENodeType, IENode } from './types';
+import { ENodeSourceType, ENodeType, IENode, ILogicPinMetadata } from './types';
 import { Circuit } from './Circuit';
 /**
  * Electrical connection point (component pin or wire branching point).
@@ -76,6 +76,10 @@ export declare class ENode {
      * @readonly
      */
     readonly subtype: string;
+    /**
+     * logic pin metadata for logicInput / logicOutput pins
+     */
+    readonly logicMetadata: ILogicPinMetadata | undefined;
     /**
      * Create a new electrical node.
      *
@@ -89,6 +93,7 @@ export declare class ENode {
      * @param source - Source type (Voltage/Current) or undefined
      *
      * @param subtype
+     * @param logicMetadata
      * @example
      * ```typescript
      * // Pin node (internal to Circuit)
@@ -110,7 +115,7 @@ export declare class ENode {
      * );
      * ```
      */
-    constructor(type: ENodeType, component: UUID | undefined, pinLabel: string | undefined, position: Position | undefined, source?: ENodeSourceType | undefined, subtype?: string);
+    constructor(type: ENodeType, component: UUID | undefined, pinLabel: string | undefined, position: Position | undefined, source: ENodeSourceType | undefined, subtype: string | undefined, logicMetadata: ILogicPinMetadata | undefined);
     /**
      * Get the position of this electrical node.
      *

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

@@ -12,3 +12,5 @@ export { CircuitOptions } from './CircuitOptions.js';
 export { CircuitMetadata } from './CircuitMetadata.js';
 export { Circuit } from './Circuit.js';
 export { computeTransitionSpan, classifyGate, computeGateDelay } from './delays.js';
+export { findPinsReachableFromBp, findBpsAtLogicDistance, findPinsReachableFromBpWithPath, findBpsAtLogicDistanceWithPath, } from './networkTraversal.js';
+export type { IPinReach, IBpAtDistance } from './networkTraversal.js';

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

@@ -0,0 +1,50 @@
+import { Circuit } from './Circuit';
+import { UUID } from '../utils';
+/** Reach record returned by `findPinsReachableFromBpWithPath`. */
+export interface IPinReach {
+    /** Logic distance — number of wire edges from the start BP to this pin. */
+    Dl: number;
+    /** ENode immediately preceding the pin on the shortest BFS path back to the
+     *  start BP. For Dl=1 this is the start BP itself. */
+    predecessor: UUID;
+}
+/** Sibling record returned by `findBpsAtLogicDistanceWithPath`. */
+export interface IBpAtDistance {
+    /** Branching-point UUID at exactly the requested logic distance. */
+    id: UUID;
+    /** ENode immediately preceding this BP on the shortest BFS path back to
+     *  the start pin. For Dl=1 this is the start pin itself. */
+    predecessor: UUID;
+}
+/** BFS the BP-only sub-graph from a start branching point and report every
+ * pin reached as a terminal endpoint, with its logic distance Dl.
+ *
+ * Pins are NEVER traversed through. If two paths reach the same pin, the
+ * smallest Dl wins.
+ *
+ * @returns A map of `pinId → Dl`. Empty if no pin is reachable.
+ */
+export declare function findPinsReachableFromBp(circuit: Circuit, startBpId: UUID): Map<UUID, number>;
+/** Same as `findPinsReachableFromBp` but each entry also carries the BFS
+ * predecessor (the ENode one step closer to the start BP on the shortest
+ * path). Used by rule 4 to identify which of newBP's two wires leads back
+ * to the anchor pin.
+ *
+ * Map insertion order matches BFS visit order, so iterating it yields ties
+ * in BFS-first order.
+ */
+export declare function findPinsReachableFromBpWithPath(circuit: Circuit, startBpId: UUID): Map<UUID, IPinReach>;
+/** BFS the BP-only sub-graph from a start pin and return every BP reached at
+ * exactly logic distance `Dl` (i.e. path-edge count = `Dl`).
+ *
+ * Branches that hit any pin before reaching the target depth are cut. The
+ * start pin itself is never returned.
+ *
+ * @returns Array of branching-point UUIDs at logic distance Dl from the pin.
+ */
+export declare function findBpsAtLogicDistance(circuit: Circuit, startPinId: UUID, Dl: number): UUID[];
+/** Same as `findBpsAtLogicDistance` but each entry carries the BFS
+ * predecessor (one step closer to the start pin). Used by rule 4 to identify
+ * which wire of each sibling to split.
+ */
+export declare function findBpsAtLogicDistanceWithPath(circuit: Circuit, startPinId: UUID, Dl: number): IBpAtDistance[];