simple-circuit-engine 0.0.12 → 0.0.14

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

@@ -0,0 +1,50 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Shared visual factory for the OneInput, TwoInput, FourInput and EightInput
+ * components.
+ *
+ * Builds an `IceBoxGeometry` envelope with `bitCount` rectangular holes laid
+ * out along the z-axis. Each hole houses a switch button mesh that animates:
+ *
+ * - **Position (y)**: snaps/slides between `SWITCH_Y_OFF` (logic 0) and
+ *   `SWITCH_Y_ON` (logic 1) when the switch is moving.
+ * - **Color**: dark-gray when no simulation context, blue (low) ↔ red (high)
+ *   during simulation.
+ *
+ * Animations follow the per-switch parameters in {@link InputState}: while a
+ * switch is mid-transition, only its mesh is animated; settled switches stay
+ * snapped to the colour/position dictated by the current driving state.
+ */
+export declare abstract class InputVisualFactoryBase extends ComponentVisualFactoryBase {
+    /** Number of switches/outputs (1, 2, 4 or 8). */
+    protected abstract readonly bitCount: number;
+    /** Number of switches/outputs (1, 2, 4 or 8). */
+    protected abstract readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Total z-axis length of the envelope. */
+    protected abstract readonly envelopeHeight: number;
+    private _envelopeGeom;
+    private _switchGeom;
+    protected createVisualBase(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    protected getDefaultInitialState(): string;
+    protected getInitialStateOptions(): {
+        [key: string]: string;
+    };
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    private _snapSwitch;
+    private _setSwitchColor;
+    private _ensureClonedMaterial;
+    private _restoreSharedMaterial;
+    private _cleanupMixer;
+    private _findSwitches;
+}

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

@@ -0,0 +1,46 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Shared visual factory for the OneLight, TwoLight, FourLight and EightLight
+ * components.
+ *
+ * Builds a `RoundIceBoxGeometry` envelope with `bitCount` circular holes laid
+ * out along the z-axis. Each hole houses a glass cylinder + half-sphere
+ * representing a light:
+ *
+ * - **Stable state**: each light glows (yellow emissive) or is dim (low
+ *   opacity, no emissive) according to the corresponding hex bit.
+ * - **Moving state**: settled lights snap to the driving (prevState) bit;
+ *   pending lights smoothly animate emissive intensity / opacity / color over
+ *   their per-light span.
+ * - **Indeterminate state**: every light is restored to the neutral glass.
+ */
+export declare abstract class LightVisualFactoryBase extends ComponentVisualFactoryBase {
+    /** Number of lights / outputs (1, 2, 4 or 8). */
+    protected abstract readonly bitCount: number;
+    /** Centre (x,y) of each hole in envelope-local 2D space. */
+    protected abstract readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    /** Total z-axis length of the envelope. */
+    protected abstract readonly envelopeHeight: number;
+    private _envelopeGeom;
+    private _baseGeom;
+    private _bulbGeom;
+    protected createVisualBase(component: Component, context: VisualContext): THREE.Object3D;
+    protected createPinsVisual(component: Component, context: VisualContext, group: THREE.Group): void;
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    private _snapLight;
+    private _setLightMaterial;
+    private _ensureClonedMaterial;
+    private _restoreSharedMaterial;
+    private _cleanupMixer;
+    private _findLights;
+}

package/dist/scene/shared/components/interface/OneInputVisualFactory.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 OneInput component (single-switch user input). */
+export declare class OneInputVisualFactory extends InputVisualFactoryBase {
+    protected readonly bitCount = 1;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 1.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/OneLightVisualFactory.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 OneLight component (single-light input mirror). */
+export declare class OneLightVisualFactory extends LightVisualFactoryBase {
+    protected readonly bitCount = 1;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 1.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/TwoInputVisualFactory.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 TwoInput component (two-switch user input). */
+export declare class TwoInputVisualFactory extends InputVisualFactoryBase {
+    protected readonly bitCount = 2;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 2.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

package/dist/scene/shared/components/interface/TwoLightVisualFactory.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 TwoLight component (two-light input mirror). */
+export declare class TwoLightVisualFactory extends LightVisualFactoryBase {
+    protected readonly bitCount = 2;
+    protected readonly holePositions: Array<{
+        x: number;
+        y: number;
+    }>;
+    protected readonly envelopeHeight = 2.4;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+}

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

@@ -7,6 +7,7 @@ import { IFactoryRegistry } from './components/ComponentVisualFactory';
 import { BranchingPointVisualFactory } from './BranchingPointVisualFactory';
 import { WireVisualManager } from './WireVisualManager';
 import { HoverManager } from './HoverManager';
+import { ILogicPinMetadata } from '../../core/topology/types';
 /**
  * Shared types for 3D Circuit Renderers
  * @module scene/shared/types
@@ -48,7 +49,7 @@ export type ModelEditAction = 'edit' | 'add' | 'delete';
 /**
  * Supported scene controllerType event types (includes tool system events)
  */
-export type ControllerEvent = 'ready' | 'error' | 'circuitLoaded' | 'circuitCleared' | 'gridPositionMove' | 'hover' | 'unhover' | 'select' | 'deselect' | 'toolActivated' | 'toolDeactivated' | 'toolOperationStarted' | 'toolOperationCompleted' | 'toolOperationCancelled' | 'toolValidationError' | 'cursorChangeRequested' | 'circuitElementAction' | 'circuitMetadataEdition' | 'selectionChange' | 'simulationPlayed' | 'simulationPaused' | 'simulationStepped' | 'simulationTick' | 'simulationUserCommand' | 'simulationStopped' | 'simulationSpeedChanged' | 'componentHelpRequested';
+export type ControllerEvent = 'ready' | 'error' | 'circuitLoaded' | 'circuitCleared' | 'gridPositionMove' | 'hover' | 'unhover' | 'select' | 'deselect' | 'toolActivated' | 'toolDeactivated' | 'toolOperationStarted' | 'toolOperationCompleted' | 'toolOperationCancelled' | 'toolValidationError' | 'cursorChangeRequested' | 'circuitElementAction' | 'circuitMetadataEdition' | 'selectionChange' | 'simulationPlayed' | 'simulationPaused' | 'simulationStepped' | 'simulationTick' | 'simulationUserCommand' | 'simulationStopped' | 'simulationSpeedChanged' | 'multiWiringChanged' | 'componentHelpRequested';
 /**
  * Event payload map for type-safe event emission
  */
@@ -161,6 +162,10 @@ export interface ControllerEventMap {
         previousSpeed: number;
         newSpeed: number;
     };
+    /** Emitted when the multi-wiring flag toggles (engine + edit-controller scope) */
+    multiWiringChanged: {
+        multiWiring: boolean;
+    };
     /** Emitted when user clicks a pin tooltip to request component help */
     componentHelpRequested: {
         componentType: ComponentType;
@@ -200,6 +205,7 @@ export interface EnodeHitboxUserData {
     componentId: string | null;
     label: string | null;
     componentType: ComponentType | null;
+    logicMetadata: ILogicPinMetadata | null;
 }
 /**
  * UserData structure for component hitbox meshes
@@ -326,6 +332,8 @@ export interface SharedResources {
     scene: THREE.Scene;
     /** Perspective camera for rendering */
     camera: THREE.PerspectiveCamera;
+    /** WebGL renderer owned by the consumer and passed in at `initialize()`. Exposed here so factories/managers can access `renderer.domElement`, `getPixelRatio()`, and `capabilities` without another bump. */
+    renderer: THREE.WebGLRenderer;
     /** MapControls for pan/zoom/rotate interaction */
     mapControls: MapControls;
     /** Grid helper */
@@ -354,6 +362,14 @@ export interface ModeChangedEvent {
     /** Previous mode before transition */
     previousMode?: EngineMode;
 }
+/**
+ * Event emitted when the user requests help via the in-scene HelpWidget.
+ * Library-neutral: consumers decide how to render help (modal, sidebar, etc.).
+ */
+export interface HelpRequestedEvent {
+    /** Mode the engine was in when help was requested */
+    mode: EngineMode;
+}
 /**
  * Combined event map for CircuitEngine.
  * Includes all controller events plus controller-specific events.
@@ -361,6 +377,8 @@ export interface ModeChangedEvent {
 export interface CircuitEngineEventMap extends ControllerEventMap {
     /** Emitted after mode transition completes */
     modeChanged: ModeChangedEvent;
+    /** Emitted when the user clicks the help button in the integrated HelpWidget */
+    helpRequested: HelpRequestedEvent;
 }
 /**
  * Configuration options for Controllers and Engine
@@ -372,7 +390,7 @@ export interface CircuitEngineEventMap extends ControllerEventMap {
  *
  * @example
  * ```typescript
- * controllerType.initialize(container, {
+ * controllerType.initialize(container, renderer, {
  *   mapControls: {
  *     enableRotate: false,  // Disable rotation for 2D-only view
  *     maxDistance: 50,      // Limit zoom out
@@ -422,6 +440,15 @@ export interface ControllerOptions {
     simulationSpeed?: number;
     /** If CircuitRunnerController plays automatically at activation */
     simulationAutoPlay?: boolean;
+    /** Initial multi-wiring flag (default: false) */
+    multiWiring?: boolean;
+}
+/**
+ * Configuration options for the integrated widgets overlay
+ */
+export interface WidgetsOptions {
+    /** Disable the bundled overlay widgets (default: true = enabled) */
+    enabled?: boolean;
 }
 /**
  * Configuration options for CircuitEngine initialization
@@ -441,6 +468,11 @@ export interface EngineOptions {
      * @default { enableHistory: false }
      */
     runnerOptions?: IRunnerOptions;
+    /**
+     * Integrated widgets overlay configuration
+     * @default { enabled: true }
+     */
+    widgets?: WidgetsOptions;
 }
 /**
  * Control type for config form fields
@@ -452,8 +484,6 @@ export type ConfigControlType = 'dropdown' | 'color' | 'number' | 'text' | 'bool
 export interface ConfigFieldDefinition {
     /** Config map key (e.g., "activeColor", "initialState") */
     key: string;
-    /** Human-readable label for the form field */
-    label: string;
     /** Control type to render */
     type: ConfigControlType;
     /** Options for dropdown type (array or label-value object) */

package/dist/scene/shared/utils/ControlsUtils.d.ts

@@ -5,4 +5,4 @@ import { MapControlsOptions } from '../types';
  * @module scene/shared/utils/ControlsUtils
  */
 import * as THREE from 'three';
-export declare function createMapControls(camera: THREE.PerspectiveCamera, container: HTMLElement, options: MapControlsOptions): MapControls;
+export declare function createMapControls(camera: THREE.PerspectiveCamera, canvas: HTMLCanvasElement, options: MapControlsOptions): MapControls;

package/dist/scene/shared/utils/GeometryUtils.d.ts

@@ -247,6 +247,36 @@ export declare function XorGateTailGeometry(orWidth: number, orHeight: number, t
  */
 export declare function LGeometry(width: number, height: number, thickness: number, angle: number, invert: boolean, junctionRadius: number, depth: number, steps?: number): ExtrudeGeometry;
 export declare function CyclicTrapezoidGeometry(width: number, tailHeight: number, headHeight: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like an empty rectangle (frame/border).
+ * Shape is centered at origin. The inner hole is a smaller rectangle inset
+ * by `thickness` on all four sides.
+ *
+ * @param width     - Total width of the outer rectangle
+ * @param height    - Total height of the outer rectangle
+ * @param thickness - Wall thickness of the frame (inset on each side)
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function EmptyRectangleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like a rectangle with a rectangular "nail"
+ * (intrusion or protrusion)
+ * The main rectangle is centered at origin; the nail hangs inside or outside it.
+ *
+ * @param width      - Total width of the rectangle
+ * @param height     - Height of the main rectangle body
+ * @param nailWidth  - Width of the nail intrusion
+ * @param nailHeight - Height of the nail
+ * @param nailX      - Horizontal center of the nail, measured from the rectangle's left edge
+ * @param protusion  - if false nail will enter inside the rectangle (intrusion), else outside (protusion)
+ * @param depth      - Extrusion depth
+ * @param steps      - Number of extrusion steps
+ * @throws Error if nail dimensions or position are geometrically invalid
+ * @constructor
+ */
+export declare function RectangleWithNailGeometry(width: number, height: number, nailWidth: number, nailHeight: number, nailX: number, protusion: boolean, depth: number, steps?: number): ExtrudeGeometry;
 /**
  * Create an ExtrudeGeometry for the inner hole of a cyclic trapezoid.
  * Returns null when the geometry should be solid (no hole).
@@ -259,3 +289,84 @@ export declare function CyclicTrapezoidGeometry(width: number, tailHeight: numbe
  * @param steps      - Number of extrusion steps
  */
 export declare function CyclicTrapezoidHoleGeometry(width: number, tailHeight: number, headHeight: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry for a drip (teardrop) shape.
+ * The shape has a sharp pointed tip at the top and a rounded bottom.
+ * Shape is centered at origin.
+ *
+ * Construction: the rounded bottom is a circle of radius width/2 centered at
+ * y = -height/2 + width/2. Two straight tangent lines connect the circle to the
+ * tip at (0, +height/2). This requires height > width so the tip sits above the
+ * circle and the tangent lines exist.
+ *
+ * @param width     - Total width
+ * @param height    - Total height (must be > width)
+ * @param thickness - Wall thickness of the shell
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @throws Error if height <= width (tip too low for tangent construction)
+ * @constructor
+ */
+export declare function DripGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry for the inner hole of a drip shape.
+ * Returns null when thickness is large enough that the drip has no hole.
+ *
+ * @param width     - Total width
+ * @param height    - Total height (must be > width)
+ * @param thickness - Wall thickness
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @throws Error if height <= width
+ */
+export declare function DripHoleGeometry(width: number, height: number, thickness: number, depth: number, steps?: number): ExtrudeGeometry | null;
+/**
+ * Create an ExtrudeGeometry shaped like japanese hiragana Ku and katakana Ko (くコ)
+ * Shape is centered horizontally at the junction between the two and vertically at the middle height
+ * by `kuThickness` on all four sides.
+ *
+ * @param kuWidth     - width of the left ku part (outer)
+ * @param koWidth     - width of the right ko part (outer)
+ * @param height    - Total height of the outer geometry
+ * @param kuThickness - Wall kuThickness of the frame (inset on ku side)
+ * @param koThickness - Wall koThickness of the frame (inset on ko side)
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function KuKoGeometry(kuWidth: number, koWidth: number, height: number, kuThickness: number, koThickness: number, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like a rectangle (frame/border) with rectangular holes in it
+ * Shape is centered at origin.
+ * by `thickness` on all four sides.
+ *
+ * @param width     - Total width of the outer rectangle
+ * @param height    - Total height of the outer rectangle
+ * @param holeWidth - width of a rectangular hole
+ * @param holeHeight - height of a rectangular hole
+ * @param holePositions - array of xy positions of the center of holes
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function IceBoxGeometry(width: number, height: number, holeWidth: number, holeHeight: number, holePositions: Array<{
+    x: number;
+    y: number;
+}>, depth: number, steps?: number): ExtrudeGeometry;
+/**
+ * Create an ExtrudeGeometry shaped like a rectangle (frame/border) with circular holes in it
+ * Shape is centered at origin.
+ * by `thickness` on all four sides.
+ *
+ * @param width     - Total width of the outer rectangle
+ * @param height    - Total height of the outer rectangle
+ * @param holeRadius - radius of a hole
+ * @param holePositions - array of xy positions of the center of holes
+ * @param depth     - Extrusion depth
+ * @param steps     - Number of extrusion steps
+ * @constructor
+ */
+export declare function RoundIceBoxGeometry(width: number, height: number, holeRadius: number, holePositions: Array<{
+    x: number;
+    y: number;
+}>, depth: number, steps?: number): ExtrudeGeometry;

package/dist/scene/static/CircuitController.d.ts

@@ -30,6 +30,7 @@ export declare class CircuitController extends AbstractCircuitController {
     private _tooltipMouseMoveHandler;
     private _tools;
     private _activeTool;
+    private _multiWiring;
     /**
      * Constructor and initialization
      */
@@ -41,11 +42,12 @@ export declare class CircuitController extends AbstractCircuitController {
      * @throws {TypeError} factoryRegistry is null/undefined
      */
     constructor(factoryRegistry: IFactoryRegistry, sharedResources?: SharedResources);
+    setLanguage(lng: string): void;
     /**
      * Specific Initialization logic, performed after AbstractCircuitController initialization
      * @private
      */
-    protected onInitialize(_options?: ControllerOptions): void;
+    protected onInitialize(options?: ControllerOptions): void;
     protected emitReady(): void;
     /**
      * Enable or disable edit mode (FR-006, FR-027)
@@ -106,6 +108,16 @@ export declare class CircuitController extends AbstractCircuitController {
      * @returns Current tool type or null if no tool is active
      */
     getActiveTool(): ToolType | null;
+    /**
+     * Whether the multi-wiring flag is currently enabled.
+     * Wiring tools may use it to create several wires per pull (semantics handled
+     * elsewhere; this controller only owns the flag and emits its changes).
+     */
+    get multiWiring(): boolean;
+    /**
+     * Toggle the multi-wiring flag and emit `multiWiringChanged` on transition.
+     */
+    setMultiWiring(value: boolean): void;
     /**
      * Set the active editing tool (FR-026, FR-028, FR-034)
      * Only one tool can be active at a time

package/dist/scene/static/tools/BuildTool.d.ts

@@ -49,6 +49,10 @@ export declare class BuildTool implements IEditingTool {
      * Cancels any active operations and removes all event handlers
      */
     onDeactivate(): void;
+    /**
+     * Forward a language change to the component picker.
+     */
+    setLanguage(lng: string): void;
     /**
      * Cancel current ongoing operation : can be called from outside if needed
      */
@@ -119,6 +123,83 @@ export declare class BuildTool implements IEditingTool {
      * @param hoveredElement - Currently hovered element at wire creation end
      */
     private completeWireCreation;
+    /**
+     * If multi-wiring is enabled and both endpoints are logic pins on distinct
+     * interfaces, fan out follow-up wires at matching offsets. Best-effort: any
+     * per-index failure is logged and skipped.
+     */
+    private createMultiWiringFollowUpWires;
+    /**
+     * If multi-wiring is enabled and the wire ended on empty space (i.e. created
+     * a fresh standalone branching point) from a logic pin, fan out follow-up
+     * branching points and follow-up wires for the remaining indices of the
+     * source interface. Best-effort: any per-step failure is logged and skipped.
+     */
+    private createMultiWiringRule2Followups;
+    /**
+     * If multi-wiring is enabled, the source is a branching point logically
+     * rooted on a single logic pin at distance Dl > 0, and the target is a
+     * fresh standalone branching point, fan out follow-up BPs through the
+     * existing BP-network: for each interface index `i + j` find a sibling
+     * BP at the same logic distance Dl and place a new target BP near it
+     * (rule-2-style growth/shrink). Stops at the first index whose sibling
+     * candidate count within the proximity threshold is not exactly 1.
+     */
+    private createMultiWiringRule3AFollowups;
+    /**
+     * Compute `4 × |pin_(i+1) − pin_i|` in XZ for a logic interface, used as the
+     * proximity threshold by rules 3A/3B/3C/4. Returns null if any look-up fails
+     * or the spacing is degenerate.
+     */
+    private computeAaPinSpacingThreshold;
+    /** Internal: index of a pin within its logic interface. Throws on missing
+     *  metadata (caller must have already checked). */
+    private indexOfPin;
+    /**
+     * Per-`j` sibling picker shared by rules 3A, 3B, 3C: forward-explore at
+     * logic distance `Dl` from `followUpPinId`, filter candidates by XZ
+     * proximity to `prevRefXZ` (≤ `threshold`), and require a singleton.
+     *
+     * @returns the chosen sibling, or a sentinel describing why we stopped.
+     */
+    private selectSiblingWithThreshold;
+    /**
+     * Backward-explore the BP-network from `bpId` and return the closest pin of biggest interface  (with non-null logicMetadata) by size
+     * Optionally if wantedLogicType is specified it filters out interfaces whose subtype differs from `wantedLogicType`
+     * Tie on `Dl` → first BFS encounter (Map insertion order).
+     */
+    private findBestAnchor;
+    /**
+     * World position of any ENode (Pin or BranchingPoint). Pins resolve via
+     * the component group + WireVisualManager; BPs via gridToWorldPosition.
+     * Returns null if the lookup chain breaks.
+     */
+    private getEnodeWorldPosition;
+    /**
+     * If multi-wiring is enabled, the source is an existing BP and the target
+     * is an existing logic pin, search the source-BP network for an
+     * opposite-type anchor pin BB-jBB; then for each follow-up index pair, wire
+     * a sibling BP on BB's interface side to the corresponding AA follow-up
+     * pin. No new BPs are created.
+     */
+    private createMultiWiringRule3BFollowups;
+    /**
+     * Mirror of 3B: source is the logic pin (= AA-i), target is the existing
+     * BP whose network is searched for an opposite-type anchor BB-jBB. The
+     * just-created src→tgt wire makes `src` reachable at Dl=1 from `tgt`, but
+     * the opposite-type filter excludes it (same subtype as itself). No new
+     * BPs are created.
+     */
+    private createMultiWiringRule3CFollowups;
+    /**
+     * Triggered after a dbl-click split creates a new BP. Backward-explore the
+     * new BP for the closest logic pin AA-i; identify the AA-side and beyond
+     * wires; for each follow-up pin AA-(i+j), find a sibling BP at the same
+     * Dl, compute candidate position via the `v3Delta` mirror, and split the
+     * sibling's wire to its BFS predecessor at that position. Iteration stops
+     * on threshold break or empty candidate set.
+     */
+    private createMultiWiringRule4Followups;
     /**
      * Start wire dragging operation
      * @param wireId - Wire being dragged

package/dist/scene/static/tools/ComponentPickerWidget.d.ts

@@ -31,6 +31,7 @@ export interface ComponentPickerState {
 export declare class ComponentPickerWidget {
     private readonly registry;
     private container;
+    private titleEl;
     private groupDropdown;
     private itemList;
     private state;
@@ -69,6 +70,12 @@ export declare class ComponentPickerWidget {
      * Full cleanup including state reset.
      */
     dispose(): void;
+    /**
+     * Refresh all user-visible text in place after a language change.
+     * No-op if the widget is not currently open.
+     * Preserves drag position, scroll, resize dimensions, and current selection.
+     */
+    setLanguage(_lng: string): void;
     private createDOM;
     private renderItemList;
     private createItemElement;

package/dist/scene/static/tools/ConfigPanelWidget.d.ts

@@ -16,6 +16,8 @@ export declare class ConfigPanelWidget {
     private readonly editComponentConfig;
     private _isOpen;
     private _currentComponentId;
+    private _currentComponent;
+    private _currentFactory;
     private gui;
     private container;
     private formDataObject;
@@ -77,6 +79,18 @@ export declare class ConfigPanelWidget {
      * @param factory - Visual factory for the component
      */
     private onValueChange;
+    /**
+     * Resolve a form field label via i18n, falling back to a humanised form
+     * of the field key when no translation is available (e.g. "transitionSpan" →
+     * "Transition Span"). The fallback covers two cases: (a) the consumer never
+     * called registerSceTranslations, (b) the key is not yet in the locale file.
+     */
+    private _resolveFieldLabel;
+    /**
+     * Refresh the panel to display strings in the current language.
+     * No-op if the panel is not open.
+     */
+    setLanguage(_lng: string): void;
     /**
      * Rebuild the GUI in place, re-reading the updated component config.
      * Used after interdependent field changes (defaultLogicFamily, activationLogic).

package/dist/scene/static/tools/MultiWiringPlacement.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Pure geometry helpers for the multi-wiring rule 2 fan-out (direct injection
+ * from a logic interface to a branching point).
+ *
+ * Kept free of Three.js so it can be unit-tested without jsdom or a renderer.
+ * Operates on the XZ plane only (Y is dropped because branching points persist
+ * as 2-D grid cells via `worldToGridPosition`).
+ *
+ * @module scene/static/tools/MultiWiringPlacement
+ */
+export interface XZ {
+    x: number;
+    z: number;
+}
+/** Compute follow-up branching point positions for rule 2.
+ *
+ * Algorithm (linear step in wire direction):
+ *   W      = bp0 - pinPositions[0]
+ *   u      = W / |W|
+ *   bp_j   = pinPositions[j] + W + sign * j * |s_j| * u   (s_j = pin spacing j-1 -> j)
+ *
+ * For `sign === -1` (logicOutput) the cumulative offset is clamped so the BP
+ * never reaches or passes its pin (a residual 1-cell wire is preserved).
+ *
+ * @param pinPositions Pin world XZ positions in interface-index order
+ *   (length = count + 1; index 0 is the source pin).
+ * @param bp0          User-clicked BP world position.
+ * @param sign         +1 for logicInput (extend), -1 for logicOutput (shrink).
+ * @returns Array of `count` follow-up BP positions (XZ), or `[]` if the wire
+ *   vector is degenerate.
+ */
+export declare function computeRule2BpPositions(pinPositions: XZ[], bp0: XZ, sign: 1 | -1): XZ[];
+/** If the float BP would round to the same integer grid cell as the parallel
+ * placement (i.e. step rounds away), nudge it by 1 unit along `u` so the
+ * fan-out remains visually perceptible at 1-cell pin spacings.
+ *
+ * Snapping uses the same convention as `worldToGridPosition`:
+ * `(round(x), round(-z))`.
+ */
+export declare function nudgeIfSameGridCell(bp: XZ, parallelBp: XZ, u: XZ): XZ;

package/dist/scene/widgets/HelpWidget.d.ts

@@ -0,0 +1,13 @@
+import { EngineMode } from '../shared/types';
+export declare class HelpWidget {
+    private readonly _button;
+    private readonly _onClick;
+    constructor(initialMode: EngineMode, onClick: () => void);
+    mount(parent: HTMLElement): void;
+    setMode(mode: EngineMode): void;
+    setVisible(visible: boolean): void;
+    setLanguage(_lng: string): void;
+    dispose(): void;
+    /** Test/debug accessor. */
+    get element(): HTMLButtonElement;
+}

package/dist/scene/widgets/ModeWidget.d.ts

@@ -0,0 +1,16 @@
+import { EngineMode } from '../shared/types';
+export declare class ModeWidget {
+    private readonly _button;
+    private readonly _onToggle;
+    private _mode;
+    constructor(initialMode: EngineMode, onToggle: () => void);
+    mount(parent: HTMLElement): void;
+    setMode(mode: EngineMode): void;
+    setLanguage(_lng: string): void;
+    /** Always visible — kept for symmetry with other widgets. */
+    setVisible(visible: boolean): void;
+    dispose(): void;
+    /** Test/debug accessor. */
+    get element(): HTMLButtonElement;
+    private _render;
+}