simple-circuit-engine 0.0.11 → 0.0.12

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

@@ -0,0 +1,51 @@
+import { ComponentVisualFactoryBase } from './ComponentVisualFactory';
+import { Component } from '../../../core/index.ts';
+import { ConfigFormDefinition } from '../types';
+import * as THREE from 'three';
+/**
+ * Default Visual factory for not yet defined components
+ *
+ * Creates:
+ * - Box squared mesh (white)
+ * - Component hitbox for raycasting
+ *
+ * This default visual is pinless no matter the component definition.
+ */
+export declare class DefaultVisualFactory extends ComponentVisualFactoryBase {
+    createVisual(component: Component): THREE.Object3D;
+    /**
+     * Get config form definition (T028)
+     * Returns form for Cube (color) - RectangleLED uses SmallLEDVisualFactory
+     *
+     * @returns Form definition with color field for Cube
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data (T028)
+     * Converts hex/preset strings to hex values for color picker
+     *
+     * @param config - Core component config
+     * @returns Form data with hex color string
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config (T028)
+     * Converts hex colors to preset names if they match, otherwise keeps hex
+     *
+     * @param formData - Form data with hex color string
+     * @returns Core config with hex or preset name string
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Update visual from configuration (T023)
+     * Updates Cube/RectangleLED color based on color config
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param config - Component configuration map
+     *
+     * @remarks
+     * Updates the box mesh color if 'color' config exists
+     * Supports both hex colors and color presets
+     */
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+}

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

@@ -0,0 +1,84 @@
+import { ComponentType } from '../../../core/index.ts';
+import { AnimationContext } from '../types';
+import { IComponentVisualFactory, IFactoryRegistry } from './ComponentVisualFactory';
+/**
+ * Registry mapping ComponentType to ComponentVisualFactory
+ *
+ * Provides type-safe registration and retrieval with automatic fallback.
+ * Supports both function-based (legacy) and class-based (new) factories.
+ * Thread-safe for read operations (get/has), write operations should be
+ * performed during initialization.
+ *
+ * @example
+ * ```typescript
+ * const registry = new FactoryRegistry(new DefaultVisualFactory());
+ * registry.register(ComponentType.Battery, new BatteryVisualFactory());
+ * registry.register(ComponentType.LED, new SmallLEDVisualFactory());
+ *
+ * const factory = registry.get(ComponentType.Battery); // Returns BatteryVisualFactory
+ * const unknown = registry.get(ComponentType.Unknown); // Returns fallback
+ * const mesh = factory.createVisual(component);
+ * ```
+ */
+export declare class FactoryRegistry implements IFactoryRegistry {
+    private factories;
+    private fallbackFactory;
+    /**
+     * Create a new factory registry
+     *
+     * @param fallbackFactory - Factory to use for unregistered component types
+     * @throws {TypeError} If fallbackFactory is null or undefined
+     */
+    constructor(fallbackFactory: IComponentVisualFactory);
+    /**
+     * Register a visual factory for a specific component type
+     *
+     * @param type - Component type identifier
+     * @param factory - Factory (class instance or function) to create visuals for this type
+     * @throws {TypeError} If type is empty/whitespace or factory is null/undefined
+     * @returns This FactoryRegistry instance (for chaining)
+     */
+    register(type: ComponentType, factory: IComponentVisualFactory): FactoryRegistry;
+    /**
+     * Retrieve the factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns Factory (fallback factory if type not registered)
+     *
+     * @remarks
+     * This method NEVER returns null/undefined. If the type is not registered,
+     * the fallback factory provided in the constructor is returned.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered types
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Unregister a factory for a component type
+     *
+     * @param type - Component type identifier
+     * @returns true if factory was registered and removed, false otherwise
+     *
+     * @remarks
+     * After unregistering, get() will return the fallback factory for this type.
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Get all registered component types
+     *
+     * @returns Array of ComponentType values that have registered factories
+     */
+    getRegisteredTypes(): ComponentType[];
+    /**
+     * Fan out animation context to all registered factories and the fallback.
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+}

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

@@ -0,0 +1,153 @@
+import { ComponentType } from '../../../core/index.ts';
+import { AnimationContext } from '../types.js';
+import { IComponentVisualFactory, IFactoryRegistry } from './ComponentVisualFactory.js';
+/**
+ * Describes a named group of component types
+ */
+export interface ComponentGroup {
+    readonly id: string;
+    readonly label: string;
+}
+/**
+ * Builder interface for adding components to a group.
+ * Used as the callback parameter type in addGroup().
+ *
+ * @example
+ * ```typescript
+ * registry.addGroup('basic', 'Basic Components', (group: IComponentGroupBuilder) => {
+ *   group
+ *     .add(ComponentType.Battery, new BatteryVisualFactory())
+ *     .add(ComponentType.Switch, new SwitchVisualFactory());
+ * });
+ * ```
+ */
+export interface IComponentGroupBuilder {
+    add(type: ComponentType, factory: IComponentVisualFactory): IComponentGroupBuilder;
+}
+/**
+ * Extended registry interface with grouping support.
+ *
+ * Adds group management on top of the basic factory retrieval,
+ * allowing client UIs to build organized component palettes.
+ */
+export interface IGroupedFactoryRegistry {
+    addGroup(id: string, label: string, builderCallback: (group: IComponentGroupBuilder) => void): IGroupedFactoryRegistry;
+    get(type: ComponentType): IComponentVisualFactory;
+    has(type: ComponentType): boolean;
+    getFallbackFactory(): IComponentVisualFactory;
+    getGroups(): ComponentGroup[];
+    getGroupOf(type: ComponentType): ComponentGroup | undefined;
+    getRegisteredTypes(groupId?: string): ComponentType[];
+    unregister(type: ComponentType): boolean;
+}
+/**
+ * Factory registry with named group support.
+ *
+ * Implements both IFactoryRegistry (backward compat) and IGroupedFactoryRegistry.
+ * Components may only be registered inside a group context via addGroup().
+ *
+ * Group insertion order is preserved (Map maintains insertion order).
+ * Duplicate group ids merge their components; the label from the first
+ * registration is preserved.
+ *
+ * @example
+ * ```typescript
+ * const registry = new GroupedFactoryRegistry(new DefaultVisualFactory())
+ *   .addGroup('basic', 'Basic Components', group => group
+ *     .add(ComponentType.Battery, new BatteryVisualFactory())
+ *     .add(ComponentType.Switch, new SwitchVisualFactory())
+ *   )
+ *   .addGroup('outputs', 'Output Components', group => group
+ *     .add(ComponentType.Lightbulb, new LightbulbVisualFactory())
+ *   );
+ *
+ * registry.getGroups();                        // [{ id: 'basic', ... }, { id: 'outputs', ... }]
+ * registry.getGroupOf(ComponentType.Battery);  // { id: 'basic', label: 'Basic Components' }
+ * registry.getRegisteredTypes('basic');        // [ComponentType.Battery, ComponentType.Switch]
+ * registry.get(ComponentType.Battery);         // BatteryVisualFactory instance
+ * ```
+ */
+export declare class GroupedFactoryRegistry implements IFactoryRegistry, IGroupedFactoryRegistry {
+    private readonly _factories;
+    private readonly _fallbackFactory;
+    private readonly _groups;
+    private readonly _typeToGroupId;
+    /**
+     * Create a new grouped factory registry.
+     *
+     * @param fallbackFactory - Factory to use for unregistered component types
+     * @throws {TypeError} If fallbackFactory is null or undefined
+     */
+    constructor(fallbackFactory: IComponentVisualFactory);
+    /**
+     * Add a named group and register component factories within it.
+     *
+     * If a group with the same id already exists, the new components are merged
+     * into it and the original label is preserved.
+     *
+     * @param id - Unique group identifier
+     * @param label - Human-readable group display name
+     * @param builderCallback - Callback receiving a builder for adding components
+     * @throws {TypeError} If id or label is empty/whitespace
+     * @returns this (for chaining)
+     */
+    addGroup(id: string, label: string, builderCallback: (group: IComponentGroupBuilder) => void): this;
+    /**
+     * Retrieve the factory for a component type.
+     *
+     * @returns Factory, or the fallback factory if type not registered.
+     * Never returns null or undefined.
+     */
+    get(type: ComponentType): IComponentVisualFactory;
+    /**
+     * Check if a factory is registered for a component type.
+     *
+     * @returns true if explicitly registered, false if would use fallback
+     */
+    has(type: ComponentType): boolean;
+    /**
+     * Get the fallback factory used for unregistered types.
+     */
+    getFallbackFactory(): IComponentVisualFactory;
+    /**
+     * Get all defined groups in insertion order.
+     *
+     * @returns New array of ComponentGroup objects (safe to mutate)
+     */
+    getGroups(): ComponentGroup[];
+    /**
+     * Get the group a component type belongs to.
+     *
+     * @param type - Component type to look up
+     * @returns ComponentGroup, or undefined if type is not registered
+     */
+    getGroupOf(type: ComponentType): ComponentGroup | undefined;
+    /**
+     * Get registered component types, optionally filtered by group.
+     *
+     * @param groupId - If provided, returns only types in that group
+     * @returns New array of ComponentType values (safe to mutate).
+     *          Returns empty array if groupId is unknown.
+     */
+    getRegisteredTypes(groupId?: string): ComponentType[];
+    /**
+     * Unregister a factory for a component type.
+     *
+     * The type is removed from its group's list and from the reverse lookup.
+     * The group record itself is preserved even if it becomes empty.
+     *
+     * @param type - Component type to remove
+     * @returns true if factory was registered and removed, false otherwise
+     */
+    unregister(type: ComponentType): boolean;
+    /**
+     * Fan out animation context to all registered factories and the fallback.
+     */
+    setAnimationContext(ctx: AnimationContext | null): void;
+    /**
+     * Not supported. Use addGroup() to register components within a named group.
+     *
+     * @throws {Error} Always throws
+     */
+    register(_type: ComponentType, _factory: IComponentVisualFactory): IFactoryRegistry;
+}

package/dist/scene/shared/components/basic/BatteryVisualFactory.d.ts

@@ -0,0 +1,13 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component } from '../../../../core/index.ts';
+import { VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Battery components
+ */
+export declare class BatteryVisualFactory extends ComponentVisualFactoryBase {
+    private readonly BATTERY_GEOMETRY;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+}

package/dist/scene/shared/components/basic/ClockVisualFactory.d.ts

@@ -0,0 +1,79 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Clock
+ */
+export declare class ClockVisualFactory extends ComponentVisualFactoryBase {
+    /** Shared Clock envelope geometry */
+    private readonly ENVELOPE_GEOMETRY;
+    /** Shared Clock hand geometry */
+    private readonly HAND_GEOMETRY;
+    /** Shared Clock area geometry */
+    private readonly AREA_GEOMETRY;
+    private readonly RED_AREA_MAT;
+    private readonly BLUE_AREA_MAT;
+    private readonly HIGH_TICK_ROTATION;
+    private readonly LOW_TICK_ROTATION;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    private createHandGroup;
+    /**
+     * Get config form definition for Clock
+     *
+     * @param config - config
+     * @returns Form definition
+     */
+    getConfigFormDefinition(_config?: Map<string, string>): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     *
+     * @param config - Core component config
+     * @returns Form data
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     *
+     * @param formData - Form data
+     * @returns Core config
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update Clock animation based on simulation state.
+     *
+     * When state is non-null: animates hand rotation toward the current state's target.
+     * If the state has a planned transition (hasExpiration), creates a smooth animation
+     * from the current visual rotation to the target using Three.js AnimationMixer.
+     * Otherwise snaps to the target position.
+     *
+     * When state is null (leaving simulation): stops all animations, cleans up mixer,
+     * and resets hand to config-based default rotation.
+     *
+     * @param object3D - The Object3D created by createVisual()
+     * @param state - The Clock's current simulation state, or null to reset
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Create a smooth animation from current hand rotation to targetRotation
+     */
+    private _animateHand;
+    /**
+     * Stop all animations, clean up mixer, and reset hand to config-based default rotation.
+     */
+    private _cleanupMixer;
+    private getStateRotation;
+    /**
+     * Find the hand group mesh within the component group
+     *
+     * @param object3D - The Object3D group created by createVisual()
+     * @returns The hand mesh if found, null otherwise
+     *
+     * @remarks
+     * Searches for a mesh with userData.part === 'hand'
+     */
+    private findHandGroup;
+}

package/dist/scene/shared/components/basic/DoubleThrowSwitchVisualFactory.d.ts

@@ -0,0 +1,87 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for DoubleThrowSwitch (SPDT) components
+ *
+ * Creates:
+ * - Input1 pin group
+ * - Input2 pin group
+ * - Output pin group
+ * - Contactor (box, rotatable for animation)
+ * - Component hitbox for raycasting
+ *
+ * Animation:
+ * - Smooth rotation of contactor between input1/input2 via AnimationMixer
+ * - Contactor material color reflects output pin state (voltage/current)
+ * - Supports mid-transition interruption (re-toggle during transition)
+ */
+export declare class DoubleThrowSwitchVisualFactory extends ComponentVisualFactoryBase {
+    /** Rotation for switch connected to input1 */
+    private readonly INPUT1_ROTATION;
+    /** Rotation for switch connected to input2 */
+    private readonly INPUT2_ROTATION;
+    private readonly CONTACTOR_GEOMETRY;
+    /** Contactor color when output has both voltage and current */
+    private readonly COLOR_VOLTAGE_CURRENT;
+    /** Contactor color when output has current only */
+    private readonly COLOR_CURRENT;
+    /** Contactor color when output has voltage only */
+    private readonly COLOR_VOLTAGE;
+    /** Contactor color when output has neither */
+    private readonly COLOR_NONE;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    /**
+     * Get config form definition for DoubleThrowSwitch
+     *
+     * @returns Form definition with initialState, transitionSpan and size
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    /**
+     * Map core config to form data
+     * Converts "input1"/"input2" strings to boolean
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     * Converts boolean to "input1"/"input2" strings
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update switch animation based on simulation state.
+     *
+     * - null state / no context: cleanup mixer, reset to config default
+     * - paused/initial + transitional: snap to start rotation
+     * - paused/initial + stable: snap to state rotation
+     * - playing + transitional: smooth rotation animation
+     * - playing + stable: snap to final rotation, cleanup mixer
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /** Maps stable state → target rotation */
+    private _getStateRotation;
+    /** Maps transitional state → the rotation it came FROM */
+    private _getStartRotation;
+    /**
+     * Create smooth rotation + color animations for transitional states.
+     * Rotation clip: current → target state rotation (persists across updateAnimation calls)
+     * Color clip: current contactor color → white (stopped on next updateAnimation so pin state takes over)
+     */
+    private _animateContactor;
+    /**
+     * Stop the color fade animation so _updateContactorColor can set color from pin state.
+     */
+    private _stopColorAnimation;
+    /**
+     * Stop all animations, clean up mixer, reset to config default rotation.
+     */
+    private _cleanupMixer;
+    private _ensureClonedMaterial;
+    private _restoreSharedMaterial;
+    private _updateContactorColor;
+    private findContactorGroup;
+    private _findContactorMesh;
+}

package/dist/scene/shared/components/basic/LabelVisualFactory.d.ts

@@ -0,0 +1,148 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Label components
+ *
+ * Creates:
+ * - Text mesh using CanvasTexture for stencil/technical font styling
+ * - Component hitbox for raycasting
+ * - No pin groups (Label has zero pins)
+ *
+ * Configuration:
+ * - text: Display text content (max 64 characters, default "Label")
+ * - size: Scale multiplier (1-10, default 1)
+ *
+ * @example
+ * ```typescript
+ * const factory = new LabelVisualFactory();
+ * const visual = factory.createVisual(labelComponent);
+ * scene.add(visual);
+ *
+ * // Update text
+ * const newConfig = new Map([['text', 'Power Supply'], ['size', '2']]);
+ * factory.updateFromConfiguration(visual, newConfig);
+ * ```
+ */
+export declare class LabelVisualFactory extends ComponentVisualFactoryBase {
+    /** Maximum text length in characters */
+    private static readonly MAX_TEXT_LENGTH;
+    /** Font family for technical/stencil aesthetic */
+    private static readonly FONT_FAMILY;
+    /** Text color (dark gray for readability) */
+    private static readonly TEXT_COLOR;
+    /** Hover text color (blue tint matching other components) */
+    private static readonly HOVER_COLOR;
+    /** Selection text color (orange tint matching other components) */
+    private static readonly SELECTION_COLOR;
+    /** Base font size in pixels */
+    private static readonly BASE_FONT_SIZE;
+    /** Padding around text in pixels */
+    private static readonly PADDING;
+    constructor();
+    createVisual(component: Component, _context: VisualContext): THREE.Object3D;
+    /**
+     * Create a canvas with rendered text
+     *
+     * @param text - Text to render (truncated to MAX_TEXT_LENGTH)
+     * @returns HTMLCanvasElement with rendered text
+     */
+    private createTextCanvas;
+    /**
+     * Create a text mesh using CanvasTexture
+     *
+     * @param text - Text to display
+     * @returns THREE.Mesh with text texture
+     */
+    private createTextMesh;
+    /**
+     * Find the text mesh within the component group
+     *
+     * @param object3D - The component group
+     * @returns The text mesh or null if not found
+     */
+    private findTextMesh;
+    /**
+     * Normalize display text by truncating and providing default
+     * @param text
+     * @private
+     */
+    private normalizeDisplayText;
+    /**
+     * Update the text mesh with new text content
+     *
+     * Resizes canvas and geometry to fit the new text, then redraws.
+     *
+     * @param mesh - The text mesh to update
+     * @param text - New text content
+     * @param group - The parent group containing the hitbox to update
+     */
+    private updateTextMesh;
+    /**
+     * Update visual based on Label configuration
+     *
+     * @param object3D - The component group
+     * @param config - Configuration map with text and size
+     */
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Get config form definition for Label component
+     *
+     * @returns Form definition with text and size fields
+     */
+    getConfigFormDefinition(): ConfigFormDefinition;
+    /**
+     * Map core config to form data
+     *
+     * @param config - Core config from Component.config
+     * @returns Form data with appropriate types
+     */
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data back to core config
+     *
+     * @param formData - Form data from UI
+     * @returns Core config with string values
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    /**
+     * Apply hover visual effect to the Label
+     *
+     * Changes text color to hover color (blue) by redrawing the canvas.
+     *
+     * @param object3D - The component group
+     */
+    applyHover(object3D: THREE.Object3D): void;
+    /**
+     * Remove hover visual effect from the Label
+     *
+     * Restores text color to default by redrawing the canvas.
+     *
+     * @param object3D - The component group
+     */
+    removeHover(object3D: THREE.Object3D): void;
+    /**
+     * Apply selection visual effect to the Label
+     *
+     * Changes text color to selection color (orange) by redrawing the canvas.
+     *
+     * @param object3D - The component group
+     */
+    applySelection(object3D: THREE.Object3D): void;
+    /**
+     * Remove selection visual effect from the Label
+     *
+     * Restores text color based on hover state.
+     *
+     * @param object3D - The component group
+     */
+    removeSelection(object3D: THREE.Object3D): void;
+    /**
+     * Redraw the text canvas with a specific color
+     *
+     * @param object3D - The component group
+     * @param color - The CSS color string to use
+     */
+    private redrawTextWithColor;
+}

package/dist/scene/shared/components/basic/LightbulbVisualFactory.d.ts

@@ -0,0 +1,72 @@
+import { ComponentVisualFactoryBase } from '../ComponentVisualFactory';
+import { Component, ComponentState } from '../../../../core/index.ts';
+import { ConfigFormDefinition, VisualContext } from '../../types';
+import * as THREE from 'three';
+/**
+ * Visual factory for Lightbulb components
+ * Animation:
+ * - Smooth emissive glow transition when Lightbulb lights up or turns off
+ * - Uses AnimationMixer with material property tracks (emissive, opacity)
+ * - Clones shared GLASS material per-instance during simulation for independent animation
+ */
+export declare class LightbulbVisualFactory extends ComponentVisualFactoryBase {
+    /** Lightbulb lit color (yellow glow) */
+    private readonly BULB_LIT_COLOR;
+    /** Lightbulb lit emissive intensity */
+    private readonly BULB_LIT_INTENSITY;
+    /** Lightbulb unlit opacity */
+    private readonly BULB_UNLIT_OPACITY;
+    private readonly BASE_GEOMETRY;
+    private readonly BULB_GEOMETRY;
+    /** Yellow in normalized RGB for ColorKeyframeTrack */
+    private readonly LIT_RGB;
+    /** Black in normalized RGB for ColorKeyframeTrack */
+    private readonly UNLIT_RGB;
+    constructor();
+    createVisual(component: Component, context: VisualContext): THREE.Object3D;
+    private createPinsVisual;
+    /**
+     * Get config form definition for Lightbulb
+     *
+     * @returns Form definition with size
+     */
+    getConfigFormDefinition(): ConfigFormDefinition | null;
+    mapCoreConfigToForm(config: Map<string, string>): Map<string, any>;
+    /**
+     * Map form data to core config
+     *
+     * @param formData - Form data with size
+     * @returns Core config with string size
+     */
+    mapFormToCoreConfig(formData: Map<string, any>): Map<string, string>;
+    updateFromConfiguration(object3D: THREE.Object3D, config: Map<string, string>): void;
+    /**
+     * Update Lightbulb animation based on simulation state.
+     *
+     * - null state / no context: restore shared material, cleanup mixer
+     * - paused/initial: snap to target state
+     * - playing + transitional (goingOn/goingOff): smooth material animation
+     * - playing + stable (on/off): snap to final state
+     */
+    updateAnimation(object3D: THREE.Object3D, state: ComponentState | null): void;
+    /**
+     * Clone the shared GLASS material for independent per-instance animation.
+     * No-op if already cloned.
+     */
+    private _ensureClonedMaterial;
+    /**
+     * Dispose the per-instance clone and restore the shared GLASS.NORMAL material.
+     * No-op if not cloned.
+     */
+    private _restoreSharedMaterial;
+    private _snapToState;
+    /**
+     * Create a smooth material animation for goingOn / goingOff transitions.
+     */
+    private _animateBulb;
+    /**
+     * Stop all animations, clean up mixer.
+     */
+    private _cleanupMixer;
+    private findBulbMesh;
+}