simple-circuit-engine 0.0.13 → 0.0.14

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;
+}

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

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

@@ -335,3 +335,38 @@ export declare function DripHoleGeometry(width: number, height: number, thicknes
  * @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
      */
@@ -46,7 +47,7 @@ export declare class CircuitController extends AbstractCircuitController {
      * 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)
@@ -107,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

@@ -123,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/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;
+}

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

@@ -0,0 +1,21 @@
+/**
+ * Multi-Wiring Widget
+ * @module scene/widgets/MultiWiringWidget
+ *
+ * Single toggle button (verr-maj style) that flips the engine's multi-wiring
+ * flag. Visible only in edit mode.
+ */
+export declare class MultiWiringWidget {
+    private readonly _button;
+    private readonly _onToggle;
+    private _active;
+    constructor(initialActive: boolean, onToggle: () => void);
+    mount(parent: HTMLElement): void;
+    setVisible(visible: boolean): void;
+    setActive(active: boolean): void;
+    setLanguage(_lng: string): void;
+    dispose(): void;
+    /** Test/debug accessor. */
+    get element(): HTMLButtonElement;
+    private _render;
+}

package/dist/scene/{static → widgets}/PinTooltipWidget.d.ts

@@ -1,4 +1,5 @@
 import { ComponentType } from '../../core/index.ts';
+import { ILogicPinMetadata } from '../../core/topology/types';
 /**
  * Manages a transient HTML tooltip displayed when hovering a component pin.
  *
@@ -15,7 +16,7 @@ export declare class PinTooltipWidget {
      * Show tooltip at the given client coordinates for the specified pin.
      * If already showing for the same component type, only repositions.
      */
-    show(pinLabel: string, componentType: ComponentType, clientX: number, clientY: number): void;
+    show(pinLabel: string, componentType: ComponentType, logicMetadata: ILogicPinMetadata | null, clientX: number, clientY: number): void;
     /** Hide and remove the tooltip element */
     hide(): void;
     /** Update cursor position without recreating the tooltip */

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

@@ -0,0 +1,62 @@
+/**
+ * Simulation Player Widget
+ * @module scene/widgets/SimulationPlayerWidget
+ *
+ * Horizontal control strip: stop | (spacer) | play/pause | speed slider |
+ * TPS indicator | step. Visible only in simulation mode.
+ *
+ * Play/pause button icon reflects current state: `pauseIcon` while playing,
+ * `playIcon` while paused. The step button relies on the engine pausing
+ * automatically when stepping while playing.
+ */
+export interface SimulationPlayerCallbacks {
+    onTogglePlay: () => void;
+    onSpeedChange: (tps: number) => void;
+    onStep: () => void;
+    onStopReset: () => void;
+}
+export declare class SimulationPlayerWidget {
+    private readonly _root;
+    private readonly _stopBtn;
+    private readonly _playPauseBtn;
+    private readonly _stepBtn;
+    private readonly _slider;
+    private readonly _speedLabel;
+    private readonly _callbacks;
+    private _isPlaying;
+    private _currentTick;
+    constructor(minSpeed: number, maxSpeed: number, initialSpeed: number, initialPlaying: boolean, callbacks: SimulationPlayerCallbacks);
+    mount(parent: HTMLElement): void;
+    setVisible(visible: boolean): void;
+    setPosition(top: number, left: number): void;
+    setSpeed(tps: number): void;
+    setTick(tick: number): void;
+    setPlaying(playing: boolean): void;
+    setLanguage(_lng: string): void;
+    dispose(): void;
+    /** Test/debug accessor. */
+    get element(): HTMLDivElement;
+    /** Test/debug accessor. */
+    get sliderElement(): HTMLInputElement;
+    /** Test/debug accessor. */
+    get stopButton(): HTMLButtonElement;
+    /** Test/debug accessor. */
+    get playPauseButton(): HTMLButtonElement;
+    /** Test/debug accessor. */
+    get stepButton(): HTMLButtonElement;
+    private _makeStopButton;
+    private _makePlayPauseButton;
+    private _makeStepButton;
+    private _makeSlider;
+    private _makeSpeedLabel;
+    private _renderLabel;
+    private _renderPlayPauseIcon;
+    private _playPauseTitle;
+    private _renderThumbColor;
+    /**
+     * Inject a one-shot stylesheet for the slider thumb so it visually matches
+     * `slider.png` (orange round thumb on a grey track) on browsers that ignore
+     * `accent-color`. Idempotent across multiple widget instances.
+     */
+    private _injectThumbStyles;
+}