@omnipad/core 0.2.0-alpha.3 → 0.4.0

package/dist/index.d.ts

@@ -1,773 +1,5 @@
-/**
- * Interface defining the structure of a keyboard key mapping.
- * Ensures compatibility between modern web standards and legacy Flash requirements.
- */
-interface KeyMapping {
-    /**
-     * The key value, corresponding to `KeyboardEvent.key`.
-     * Represented as a string (e.g., " ", "Enter", "a").
-     */
-    key: string;
-    /**
-     * The physical key code, corresponding to `KeyboardEvent.code`.
-     * Describes the physical location of the key (e.g., "Space", "Enter", "KeyA").
-     */
-    code: string;
-    /**
-     * The legacy numerical key code, corresponding to `KeyboardEvent.keyCode`.
-     * Essential for Flash engines (AS2/AS3) running via Ruffle.
-     * e.g., 32 for Space, 13 for Enter.
-     */
-    keyCode: number;
-}
-/**
- * Standard collection of key mappings.
- * Allows developers to quickly retrieve mapping data using physical key codes as keys.
- */
-declare const KEYS: {
-    readonly Backspace: {
-        readonly key: "Backspace";
-        readonly code: "Backspace";
-        readonly keyCode: 8;
-    };
-    readonly Tab: {
-        readonly key: "Tab";
-        readonly code: "Tab";
-        readonly keyCode: 9;
-    };
-    readonly Enter: {
-        readonly key: "Enter";
-        readonly code: "Enter";
-        readonly keyCode: 13;
-    };
-    readonly ShiftLeft: {
-        readonly key: "Shift";
-        readonly code: "ShiftLeft";
-        readonly keyCode: 16;
-    };
-    readonly ControlLeft: {
-        readonly key: "Control";
-        readonly code: "ControlLeft";
-        readonly keyCode: 17;
-    };
-    readonly AltLeft: {
-        readonly key: "Alt";
-        readonly code: "AltLeft";
-        readonly keyCode: 18;
-    };
-    readonly Pause: {
-        readonly key: "Pause";
-        readonly code: "Pause";
-        readonly keyCode: 19;
-    };
-    readonly CapsLock: {
-        readonly key: "CapsLock";
-        readonly code: "CapsLock";
-        readonly keyCode: 20;
-    };
-    readonly Escape: {
-        readonly key: "Escape";
-        readonly code: "Escape";
-        readonly keyCode: 27;
-    };
-    readonly Space: {
-        readonly key: " ";
-        readonly code: "Space";
-        readonly keyCode: 32;
-    };
-    readonly PageUp: {
-        readonly key: "PageUp";
-        readonly code: "PageUp";
-        readonly keyCode: 33;
-    };
-    readonly PageDown: {
-        readonly key: "PageDown";
-        readonly code: "PageDown";
-        readonly keyCode: 34;
-    };
-    readonly End: {
-        readonly key: "End";
-        readonly code: "End";
-        readonly keyCode: 35;
-    };
-    readonly Home: {
-        readonly key: "Home";
-        readonly code: "Home";
-        readonly keyCode: 36;
-    };
-    readonly ArrowLeft: {
-        readonly key: "ArrowLeft";
-        readonly code: "ArrowLeft";
-        readonly keyCode: 37;
-    };
-    readonly ArrowUp: {
-        readonly key: "ArrowUp";
-        readonly code: "ArrowUp";
-        readonly keyCode: 38;
-    };
-    readonly ArrowRight: {
-        readonly key: "ArrowRight";
-        readonly code: "ArrowRight";
-        readonly keyCode: 39;
-    };
-    readonly ArrowDown: {
-        readonly key: "ArrowDown";
-        readonly code: "ArrowDown";
-        readonly keyCode: 40;
-    };
-    readonly PrintScreen: {
-        readonly key: "PrintScreen";
-        readonly code: "PrintScreen";
-        readonly keyCode: 44;
-    };
-    readonly Insert: {
-        readonly key: "Insert";
-        readonly code: "Insert";
-        readonly keyCode: 45;
-    };
-    readonly Delete: {
-        readonly key: "Delete";
-        readonly code: "Delete";
-        readonly keyCode: 46;
-    };
-    readonly Digit0: {
-        readonly key: "0";
-        readonly code: "Digit0";
-        readonly keyCode: 48;
-    };
-    readonly Digit1: {
-        readonly key: "1";
-        readonly code: "Digit1";
-        readonly keyCode: 49;
-    };
-    readonly Digit2: {
-        readonly key: "2";
-        readonly code: "Digit2";
-        readonly keyCode: 50;
-    };
-    readonly Digit3: {
-        readonly key: "3";
-        readonly code: "Digit3";
-        readonly keyCode: 51;
-    };
-    readonly Digit4: {
-        readonly key: "4";
-        readonly code: "Digit4";
-        readonly keyCode: 52;
-    };
-    readonly Digit5: {
-        readonly key: "5";
-        readonly code: "Digit5";
-        readonly keyCode: 53;
-    };
-    readonly Digit6: {
-        readonly key: "6";
-        readonly code: "Digit6";
-        readonly keyCode: 54;
-    };
-    readonly Digit7: {
-        readonly key: "7";
-        readonly code: "Digit7";
-        readonly keyCode: 55;
-    };
-    readonly Digit8: {
-        readonly key: "8";
-        readonly code: "Digit8";
-        readonly keyCode: 56;
-    };
-    readonly Digit9: {
-        readonly key: "9";
-        readonly code: "Digit9";
-        readonly keyCode: 57;
-    };
-    readonly KeyA: {
-        readonly key: "a";
-        readonly code: "KeyA";
-        readonly keyCode: 65;
-    };
-    readonly KeyB: {
-        readonly key: "b";
-        readonly code: "KeyB";
-        readonly keyCode: 66;
-    };
-    readonly KeyC: {
-        readonly key: "c";
-        readonly code: "KeyC";
-        readonly keyCode: 67;
-    };
-    readonly KeyD: {
-        readonly key: "d";
-        readonly code: "KeyD";
-        readonly keyCode: 68;
-    };
-    readonly KeyE: {
-        readonly key: "e";
-        readonly code: "KeyE";
-        readonly keyCode: 69;
-    };
-    readonly KeyF: {
-        readonly key: "f";
-        readonly code: "KeyF";
-        readonly keyCode: 70;
-    };
-    readonly KeyG: {
-        readonly key: "g";
-        readonly code: "KeyG";
-        readonly keyCode: 71;
-    };
-    readonly KeyH: {
-        readonly key: "h";
-        readonly code: "KeyH";
-        readonly keyCode: 72;
-    };
-    readonly KeyI: {
-        readonly key: "i";
-        readonly code: "KeyI";
-        readonly keyCode: 73;
-    };
-    readonly KeyJ: {
-        readonly key: "j";
-        readonly code: "KeyJ";
-        readonly keyCode: 74;
-    };
-    readonly KeyK: {
-        readonly key: "k";
-        readonly code: "KeyK";
-        readonly keyCode: 75;
-    };
-    readonly KeyL: {
-        readonly key: "l";
-        readonly code: "KeyL";
-        readonly keyCode: 76;
-    };
-    readonly KeyM: {
-        readonly key: "m";
-        readonly code: "KeyM";
-        readonly keyCode: 77;
-    };
-    readonly KeyN: {
-        readonly key: "n";
-        readonly code: "KeyN";
-        readonly keyCode: 78;
-    };
-    readonly KeyO: {
-        readonly key: "o";
-        readonly code: "KeyO";
-        readonly keyCode: 79;
-    };
-    readonly KeyP: {
-        readonly key: "p";
-        readonly code: "KeyP";
-        readonly keyCode: 80;
-    };
-    readonly KeyQ: {
-        readonly key: "q";
-        readonly code: "KeyQ";
-        readonly keyCode: 81;
-    };
-    readonly KeyR: {
-        readonly key: "r";
-        readonly code: "KeyR";
-        readonly keyCode: 82;
-    };
-    readonly KeyS: {
-        readonly key: "s";
-        readonly code: "KeyS";
-        readonly keyCode: 83;
-    };
-    readonly KeyT: {
-        readonly key: "t";
-        readonly code: "KeyT";
-        readonly keyCode: 84;
-    };
-    readonly KeyU: {
-        readonly key: "u";
-        readonly code: "KeyU";
-        readonly keyCode: 85;
-    };
-    readonly KeyV: {
-        readonly key: "v";
-        readonly code: "KeyV";
-        readonly keyCode: 86;
-    };
-    readonly KeyW: {
-        readonly key: "w";
-        readonly code: "KeyW";
-        readonly keyCode: 87;
-    };
-    readonly KeyX: {
-        readonly key: "x";
-        readonly code: "KeyX";
-        readonly keyCode: 88;
-    };
-    readonly KeyY: {
-        readonly key: "y";
-        readonly code: "KeyY";
-        readonly keyCode: 89;
-    };
-    readonly KeyZ: {
-        readonly key: "z";
-        readonly code: "KeyZ";
-        readonly keyCode: 90;
-    };
-    readonly MetaLeft: {
-        readonly key: "Meta";
-        readonly code: "MetaLeft";
-        readonly keyCode: 91;
-    };
-    readonly ContextMenu: {
-        readonly key: "ContextMenu";
-        readonly code: "ContextMenu";
-        readonly keyCode: 93;
-    };
-    readonly Numpad0: {
-        readonly key: "0";
-        readonly code: "Numpad0";
-        readonly keyCode: 96;
-    };
-    readonly Numpad1: {
-        readonly key: "1";
-        readonly code: "Numpad1";
-        readonly keyCode: 97;
-    };
-    readonly Numpad2: {
-        readonly key: "2";
-        readonly code: "Numpad2";
-        readonly keyCode: 98;
-    };
-    readonly Numpad3: {
-        readonly key: "3";
-        readonly code: "Numpad3";
-        readonly keyCode: 99;
-    };
-    readonly Numpad4: {
-        readonly key: "4";
-        readonly code: "Numpad4";
-        readonly keyCode: 100;
-    };
-    readonly Numpad5: {
-        readonly key: "5";
-        readonly code: "Numpad5";
-        readonly keyCode: 101;
-    };
-    readonly Numpad6: {
-        readonly key: "6";
-        readonly code: "Numpad6";
-        readonly keyCode: 102;
-    };
-    readonly Numpad7: {
-        readonly key: "7";
-        readonly code: "Numpad7";
-        readonly keyCode: 103;
-    };
-    readonly Numpad8: {
-        readonly key: "8";
-        readonly code: "Numpad8";
-        readonly keyCode: 104;
-    };
-    readonly Numpad9: {
-        readonly key: "9";
-        readonly code: "Numpad9";
-        readonly keyCode: 105;
-    };
-    readonly NumpadMultiply: {
-        readonly key: "*";
-        readonly code: "NumpadMultiply";
-        readonly keyCode: 106;
-    };
-    readonly NumpadAdd: {
-        readonly key: "+";
-        readonly code: "NumpadAdd";
-        readonly keyCode: 107;
-    };
-    readonly NumpadSubtract: {
-        readonly key: "-";
-        readonly code: "NumpadSubtract";
-        readonly keyCode: 109;
-    };
-    readonly NumpadDecimal: {
-        readonly key: ".";
-        readonly code: "NumpadDecimal";
-        readonly keyCode: 110;
-    };
-    readonly NumpadDivide: {
-        readonly key: "/";
-        readonly code: "NumpadDivide";
-        readonly keyCode: 111;
-    };
-    readonly F1: {
-        readonly key: "F1";
-        readonly code: "F1";
-        readonly keyCode: 112;
-    };
-    readonly F2: {
-        readonly key: "F2";
-        readonly code: "F2";
-        readonly keyCode: 113;
-    };
-    readonly F3: {
-        readonly key: "F3";
-        readonly code: "F3";
-        readonly keyCode: 114;
-    };
-    readonly F4: {
-        readonly key: "F4";
-        readonly code: "F4";
-        readonly keyCode: 115;
-    };
-    readonly F5: {
-        readonly key: "F5";
-        readonly code: "F5";
-        readonly keyCode: 116;
-    };
-    readonly F6: {
-        readonly key: "F6";
-        readonly code: "F6";
-        readonly keyCode: 117;
-    };
-    readonly F7: {
-        readonly key: "F7";
-        readonly code: "F7";
-        readonly keyCode: 118;
-    };
-    readonly F8: {
-        readonly key: "F8";
-        readonly code: "F8";
-        readonly keyCode: 119;
-    };
-    readonly F9: {
-        readonly key: "F9";
-        readonly code: "F9";
-        readonly keyCode: 120;
-    };
-    readonly F10: {
-        readonly key: "F10";
-        readonly code: "F10";
-        readonly keyCode: 121;
-    };
-    readonly F11: {
-        readonly key: "F11";
-        readonly code: "F11";
-        readonly keyCode: 122;
-    };
-    readonly F12: {
-        readonly key: "F12";
-        readonly code: "F12";
-        readonly keyCode: 123;
-    };
-    readonly NumLock: {
-        readonly key: "NumLock";
-        readonly code: "NumLock";
-        readonly keyCode: 144;
-    };
-    readonly ScrollLock: {
-        readonly key: "ScrollLock";
-        readonly code: "ScrollLock";
-        readonly keyCode: 145;
-    };
-    readonly Semicolon: {
-        readonly key: ";";
-        readonly code: "Semicolon";
-        readonly keyCode: 186;
-    };
-    readonly Equal: {
-        readonly key: "=";
-        readonly code: "Equal";
-        readonly keyCode: 187;
-    };
-    readonly Comma: {
-        readonly key: ",";
-        readonly code: "Comma";
-        readonly keyCode: 188;
-    };
-    readonly Minus: {
-        readonly key: "-";
-        readonly code: "Minus";
-        readonly keyCode: 189;
-    };
-    readonly Period: {
-        readonly key: ".";
-        readonly code: "Period";
-        readonly keyCode: 190;
-    };
-    readonly Slash: {
-        readonly key: "/";
-        readonly code: "Slash";
-        readonly keyCode: 191;
-    };
-    readonly Backquote: {
-        readonly key: "`";
-        readonly code: "Backquote";
-        readonly keyCode: 192;
-    };
-    readonly BracketLeft: {
-        readonly key: "[";
-        readonly code: "BracketLeft";
-        readonly keyCode: 219;
-    };
-    readonly Backslash: {
-        readonly key: "\\";
-        readonly code: "Backslash";
-        readonly keyCode: 220;
-    };
-    readonly BracketRight: {
-        readonly key: "]";
-        readonly code: "BracketRight";
-        readonly keyCode: 221;
-    };
-    readonly Quote: {
-        readonly key: "'";
-        readonly code: "Quote";
-        readonly keyCode: 222;
-    };
-};
-
-/**
- * Defines the spatial properties of a component.
- * Supports various CSS units (px, %, vh, vw) via FlexibleLength.
- */
-interface LayoutBox {
-    /** Offset from the left edge of the parent container. */
-    left?: FlexibleLength;
-    /** Offset from the top edge of the parent container. */
-    top?: FlexibleLength;
-    /** Offset from the right edge of the parent container. */
-    right?: FlexibleLength;
-    /** Offset from the bottom edge of the parent container. */
-    bottom?: FlexibleLength;
-    /** Width of the component. */
-    width?: FlexibleLength;
-    /** Height of the component. */
-    height?: FlexibleLength;
-    /**
-     * The alignment point of the component relative to its (left, top) coordinates.
-     * @example 'center' will center the component on its position.
-     */
-    anchor?: AnchorPoint;
-    /** Rotation angle in degrees. */
-    /** Z-index for layering control. */
-    zIndex?: number;
-}
-/**
- * Base configuration interface for all components.
- */
-interface BaseConfig {
-    /**
-     * Config ID (CID) used in persistent storage.
-     * If omitted, a random UID will be generated during parsing.
-     * If starts with '$', it points to a global static entity. (UID = CID)
-     */
-    id?: string;
-    /** The unique type identifier for the component. */
-    type: string;
-    /** CID of the parent component. Root components have no parentId. */
-    parentId?: string;
-    /** Spatial layout settings. */
-    layout: LayoutBox;
-}
-/**
- * Configuration for a virtual keyboard button.
- */
-interface KeyboardButtonConfig extends BaseConfig {
-    type: typeof CMP_TYPES.KEYBOARD_BUTTON;
-    /** Visual text displayed on the button. */
-    label: string;
-    /** Keyboard event metadata to be emitted when triggered. */
-    mapping: KeyMapping;
-    /**
-     * CID of the TargetZone where signals should be dispatched.
-     */
-    targetStageId?: string;
-}
-/**
- * Mouse Button Configuration
- */
-interface MouseButtonConfig extends BaseConfig {
-    type: typeof CMP_TYPES.MOUSE_BUTTON;
-    /** Label displayed on the button */
-    label: string;
-    /**
-     * 0: Left (Main), 1: Middle, 2: Right (Context)
-     * @default 0
-     */
-    button: 0 | 1 | 2;
-    /** CID of the target Stage to receive clicks */
-    targetStageId?: string;
-    /**
-     * Fixed coordinate to click on (0-100 percentage).
-     * If provided, the click always hits this spot regardless of cursor position.
-     */
-    fixedPoint?: Vec2;
-}
-interface TrackpadConfig extends BaseConfig {
-    type: typeof CMP_TYPES.TRACKPAD;
-    /** Label displayed on the trackpad */
-    label: string;
-    /** Simulation sensitivity, e.g. 0.5 - 2.0 */
-    sensitivity: number;
-    /** CID of the target Stage to receive clicks */
-    targetStageId?: string;
-}
-/**
- * Configuration for an Input Zone.
- * Input Zones act as containers and can handle dynamic (floating) widgets.
- */
-interface InputZoneConfig extends BaseConfig {
-    type: typeof CMP_TYPES.INPUT_ZONE;
-    /** If true, attempts to regain focus for the target stage when touched. */
-    preventFocusLoss?: boolean;
-    /**
-     * The CID of a child component intended to be used as a dynamic (floating) widget.
-     */
-    dynamicWidgetId?: string;
-}
-/**
- * Configuration for a Target Focus Zone.
- * Acts as the bridge between virtual signals and the actual game/app DOM.
- */
-interface TargetZoneConfig extends BaseConfig {
-    type: typeof CMP_TYPES.TARGET_ZONE;
-    /** Whether to render a visual virtual cursor. */
-    cursorEnabled?: boolean;
-    /** Time in milliseconds before the cursor auto-hides after inactivity. 0 to disable. */
-    cursorAutoDelay?: number;
-}
-/**
- * Union type representing any valid component configuration.
- */
-type AnyConfig = KeyboardButtonConfig | InputZoneConfig | TargetZoneConfig | any;
-/**
- * Representation of a single item in a flattened configuration profile.
- * Ideal for database storage and flat-list editing.
- */
-interface FlatConfigItem {
-    /** Unique identifier (CID) in the scope of the profile. */
-    id: string;
-    /** Component type string. */
-    type: string;
-    /** Parent CID. Empty if this is the root node. */
-    parentId?: string;
-    /** Flattened business logic and layout properties. */
-    config?: Record<string, any>;
-}
-/**
- * The root structure of a Gamepad configuration file.
- */
-interface GamepadProfile {
-    /** Metadata about the profile creator and version. */
-    meta: {
-        name: string;
-        version: string;
-        author?: string;
-    };
-    /** The CID of the entry-point component (usually a root layer or zone, or widget for individual widget config). */
-    rootId: string;
-    /** List of all components in the profile. Hierarchies are defined via parentId. */
-    items: FlatConfigItem[];
-}
-/**
- * A recursive tree structure representing the runtime hierarchy of components.
- * Used by the adapter layer (e.g., Vue) to render components recursively.
- */
-interface ConfigTreeNode {
-    /** Runtime Unique Entity ID (UID), unique across the entire application. */
-    uid: string;
-    /** Component type string. */
-    type: string;
-    /** Component properties (layout, mapping, etc.), stripped of hierarchy data. */
-    config?: Record<string, any>;
-    /** Nested children tree nodes. */
-    children?: ConfigTreeNode[];
-}
-
-/**
- * Trait: Provides identity with a unique ID and specific entity type.
- */
-interface IIdentifiable {
-    readonly uid: string;
-    readonly type: EntityType;
-}
-/**
- * Trait: Provides lifecycle management hooks.
- */
-interface ILifecycle {
-    /**
-     * Performs cleanup, unregisters the entity, and releases resources.
-     */
-    destroy(): void;
-}
-/**
- * The core contract for any object that can be managed by the Registry.
- * Only objects implementing this interface are eligible for registration.
- */
-interface ICoreEntity extends IIdentifiable, ILifecycle {
-}
-/**
- * Trait: Enables spatial awareness for DOM/UI-related components.
- */
-interface ISpatial {
-    /**
-     * Dynamically obtain dimensions and position to ensure the most precise real-time screen coordinates are obtained during each interaction.
-     */
-    bindRectProvider(provider: () => DOMRect): void;
-}
-/**
- * Trait: Provides configuration management.
- */
-interface IConfigurable<TConfig> {
-    /**
-     * Dynamically updates the current configuration.
-     * @param config - Partial configuration object to merge.
-     */
-    updateConfig(config: Partial<TConfig>): void;
-    /**
-     * Retrieves a snapshot of the current configuration.
-     */
-    getConfig(): TConfig;
-}
-/**
- * Trait: Enables state subscription for the adapter layer (e.g., Vue/React).
- */
-interface IObservable<TState> {
-    /**
-     * Subscribes to state changes.
-     * @param cb - Callback function triggered on state updates.
-     * @returns An unsubscribe function.
-     */
-    subscribe(cb: (state: TState) => void): () => void;
-    /**
-     * Retrieves the current state snapshot.
-     */
-    getState(): TState;
-}
-/**
- * Trait: Allows resetting the entity to its idle/safe state.
- */
-interface IResettable {
-    /**
-     * Forcefully clears active states and cuts off outgoing signals.
-     */
-    reset(): void;
-}
-/**
- * Trait: Handles raw pointer input (Touch/Mouse).
- */
-interface IPointerHandler {
-    onPointerDown(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
-}
-/**
- * Trait: Receives and processes input signals (e.g., TargetZone).
- */
-interface ISignalReceiver {
-    /**
-     * Handles incoming signals from widgets.
-     * @param signal - The signal data containing action type and payload.
-     */
-    handleSignal(signal: InputActionSignal): void;
-}
+import { I as ICoreEntity, V as Vec2, G as GamepadMappingConfig, a as ISpatial, b as IResettable, c as IConfigurable, d as IObservable, E as EntityType, A as AbstractRect, B as ButtonConfig, e as IPointerHandler, f as IProgrammatic, g as AbstractPointerEvent, D as DPadConfig, h as InputZoneConfig, i as IDependencyBindable, j as AnyFunction, J as JoystickConfig, k as BaseConfig, T as TargetZoneConfig, l as ISignalReceiver, m as InputActionSignal, n as TrackpadConfig } from './index-DRA1rw5_.js';
+export { o as ACTION_TYPES, p as ActionMapping, q as AnchorPoint, r as AnyConfig, s as AnyEntityType, t as BuiltInActionType, C as CMP_TYPES, u as CONTEXT, v as ConfigTreeNode, F as FlatConfigItem, w as FlexibleLength, x as GamepadProfile, y as IIdentifiable, z as ILifecycle, H as InputActionType, K as KEYS, L as KeyMapping, M as LayoutBox, S as StageId, N as StandardButton, U as Unit, W as WidgetId, O as WidgetType, Z as ZoneId, P as ZoneType } from './index-DRA1rw5_.js';
 
 /**
  * Interface for the global Registry singleton.
@@ -851,17 +83,15 @@ interface ButtonLogicState {
     value: number;
 }
 /**
- * Logic-level state for joystick-type widgets.
- * Provides directional data calculated from the stick movement.
+ * Logic-level state for axis-type or joystick widgets.
+ * Represents the normalized directional input.
  */
-interface JoystickLogicState {
+interface AxisLogicState {
     /** Normalized direction vector where x and y range from -1.0 to 1.0. */
     vector: {
         x: number;
         y: number;
     };
-    /** The current angle of the stick in radians. */
-    angle: number;
 }
 /**
  * Runtime state for the Virtual Cursor within a TargetZone.
@@ -894,6 +124,11 @@ interface LayerState {
     /** Visual hint for layout debugging or active selection. */
     isHighlighted: boolean;
 }
+/**
+ * Combined state for Button components.
+ */
+interface ButtonState extends InteractionState, ButtonLogicState {
+}
 /**
  * Combined state for Keyboard Button components.
  */
@@ -910,409 +145,77 @@ interface MouseButtonState extends InteractionState, ButtonLogicState {
 interface TrackpadState extends InteractionState, ButtonLogicState {
 }
 /**
- * Combined state for Analog Stick components.
- */
-interface JoystickState extends InteractionState, JoystickLogicState {
-}
-
-/**
- * =================================================================
- * 1. Constants Definition
- * Used for runtime logic and as a baseline for type definitions.
- * =================================================================
+ * Combined state for D-pad components.
  */
-/**
- * Core entity types supported by the library.
- */
-declare const CMP_TYPES: {
-    /** Area responsible for capturing touches and spawning dynamic widgets */
-    readonly INPUT_ZONE: "input-zone";
-    /** Area responsible for receiving signals and simulating DOM events */
-    readonly TARGET_ZONE: "target-zone";
-    /** Simulates a physical keyboard key press */
-    readonly KEYBOARD_BUTTON: "keyboard-button";
-    /** Simulates a mouse button click/hold */
-    readonly MOUSE_BUTTON: "mouse-button";
-    /** A joystick that outputs 360-degree or locked direction vectors */
-    readonly ANALOG_STICK: "analog-stick";
-    /** Classic 4/8-way directional pad */
-    readonly D_PAD: "d-pad";
-    /** Trackpad-style relative movement area */
-    readonly TRACKPAD: "trackpad";
-    /** Logic for the on-screen visual cursor */
-    readonly VIRTUAL_CURSOR: "virtual-cursor";
-    /** The top-level managed container */
-    readonly ROOT_LAYER: "root-layer";
-};
-/**
- * Standardized input action types for the signal protocol.
- */
-declare const ACTION_TYPES: {
-    readonly KEYDOWN: "keydown";
-    readonly KEYUP: "keyup";
-    readonly POINTER: "pointer";
-    readonly POINTERMOVE: "pointermove";
-    readonly POINTERDOWN: "pointerdown";
-    readonly POINTERUP: "pointerup";
-    readonly MOUSE: "mouse";
-    readonly MOUSEMOVE: "mousemove";
-    readonly MOUSEDOWN: "mousedown";
-    readonly MOUSEUP: "mouseup";
-    readonly CLICK: "click";
-};
-/**
- * =================================================================
- * 2. Type Definitions
- * =================================================================
- */
-/**
- * Represents a 2D coordinate or vector.
- * Typically used for percentage-based positioning (0-100).
- */
-interface Vec2 {
-    x: number;
-    y: number;
+interface DPadState extends InteractionState, AxisLogicState {
 }
-/** Unique identifier for a Stage (TargetZone) */
-type StageId = string;
-/** Unique identifier for an Input Widget */
-type WidgetId = string;
-/** Unique identifier for a Zone container (InputZone) */
-type ZoneId = string;
-/** Union type of all built-in entity values */
-type AnyEntityType = (typeof CMP_TYPES)[keyof typeof CMP_TYPES];
-/** Supported Widget type strings, allowing for custom string extensions */
-type WidgetType = typeof CMP_TYPES.KEYBOARD_BUTTON | typeof CMP_TYPES.MOUSE_BUTTON | typeof CMP_TYPES.ANALOG_STICK | typeof CMP_TYPES.D_PAD | typeof CMP_TYPES.TRACKPAD | (string & {});
-/** Supported Zone type strings, allowing for custom string extensions */
-type ZoneType = typeof CMP_TYPES.INPUT_ZONE | typeof CMP_TYPES.TARGET_ZONE | (string & {});
-/** General node type identifier for ConfigTreeNode or Registry lookups */
-type EntityType = AnyEntityType | (string & {});
-/** Built-in input action identifiers */
-type BuiltInActionType = (typeof ACTION_TYPES)[keyof typeof ACTION_TYPES];
-/** Input action type strings, allowing for custom action extensions */
-type InputActionType = BuiltInActionType | (string & {});
-/** Supported CSS units for layout calculation */
-type Unit = 'px' | '%' | 'vh' | 'vw' | 'rem';
-/**
- * Flexible length input.
- * Supports numbers (interpreted as px) or strings (e.g., '50%', '10vh').
- */
-type FlexibleLength = string | number;
-/**
- * Anchor position used to determine the alignment of an element relative to its coordinates.
- */
-type AnchorPoint = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
 /**
- * =================================================================
- * 3. Signal Protocol
- * Data structure for communication between Widgets and Stages.
- * =================================================================
+ * Combined state for Joystick components.
  */
-/**
- * Represents a signal emitted by an input widget to be processed by a target zone.
- */
-interface InputActionSignal {
-    /** The unique identifier of the destination TargetZone */
-    targetStageId: StageId;
-    /** The action type to perform (e.g., keydown, mousemove) */
-    type: InputActionType;
-    /** The payload containing specific input details */
-    payload: {
-        /** Character value of the key (e.g., ' ') */
-        key?: string;
-        /** Physical key code (e.g., 'Space') */
-        code?: string;
-        /** Legacy numeric key code (e.g., 32) */
-        keyCode?: number;
-        /** Coordinate point in percentage (0-100) */
-        point?: Vec2;
-        /** Relative displacement in percentage (0-100) */
-        delta?: Vec2;
-        /** Mouse button index (0: Left, 1: Middle, 2: Right) */
-        button?: 0 | 1 | 2;
-        /** Input pressure or force (0.0 to 1.0) */
-        pressure?: number;
-        /** Allows for arbitrary custom data to support widget extensions */
-        [key: string]: any;
-    };
+interface JoystickState extends InteractionState, AxisLogicState, ButtonLogicState {
 }
-/**
- * Cross-framework context keys for dependency injection (e.g., Provide/Inject).
- */
-declare const CONTEXT: {
-    /** The key used to propagate Parent IDs through the component tree */
-    readonly PARENT_ID_KEY: "omnipad-parent-id-link";
-};
 
 /**
- * Subtracts vector v2 from v1.
- * @param v1 - The source vector.
- * @param v2 - The vector to subtract.
- */
-declare const subVec: (v1: Vec2, v2: Vec2) => Vec2;
-/**
- * Adds vector v2 to v1.
- */
-declare const addVec: (v1: Vec2, v2: Vec2) => Vec2;
-/**
- * Scales a vector by a scalar value.
- * Useful for mapping normalized vectors back to specific pixel magnitudes.
- */
-declare const scaleVec: (v: Vec2, s: number) => Vec2;
-/**
- * Clamps a numeric value between a minimum and maximum range.
- */
-declare const clamp: (val: number, min: number, max: number) => number;
-/**
- * Linearly interpolates between two values.
- */
-declare const lerp: (start: number, end: number, t: number) => number;
-/**
- * Rounds a number to a specific decimal precision.
- * Solves floating-point precision issues in pixel calculations.
- */
-declare const roundTo: (val: number, precision?: number) => number;
-/**
- * Calculates the Euclidean distance between two points.
- */
-declare const getDistance: (p1: Vec2, p2: Vec2) => number;
-/**
- * Calculates the angle in radians from point p1 to p2.
- * Range: -PI to PI.
- */
-declare const getAngle: (p1: Vec2, p2: Vec2) => number;
-/**
- * Converts radians to degrees.
- */
-declare const radToDeg: (rad: number) => number;
-/**
- * Converts degrees to radians.
- */
-declare const degToRad: (deg: number) => number;
-/**
- * Constrains a target point within a circular radius relative to an origin.
- * Commonly used for joystick physical displacement limits.
- */
-declare const clampVector: (origin: Vec2, target: Vec2, radius: number) => Vec2;
-/**
- * Snaps a radian angle to the nearest of 8 directions (45-degree steps).
- */
-declare const lockTo8Directions: (rad: number) => number;
-/**
- * Snaps a radian angle to the nearest of 4 directions (90-degree steps).
- */
-declare const lockTo4Directions: (rad: number) => number;
-/**
- * Converts percentage (0-100) to pixel values (px).
- */
-declare const percentToPx: (percent: number, totalPx: number) => number;
-/**
- * Converts pixel values (px) to percentage (0-100).
- */
-declare const pxToPercent: (px: number, totalPx: number) => number;
-/**
- * Normalizes a vector to a length of 1.
- * Returns {0, 0} if the vector magnitude is 0.
- */
-declare const normalizeVec: (v: Vec2) => Vec2;
-/**
- * Converts a radian angle to a unit vector.
- */
-declare const radToVec: (rad: number) => Vec2;
-/**
- * Linearly remaps a value from one range [inMin, inMax] to another [outMin, outMax].
- */
-declare const remap: (val: number, inMin: number, inMax: number, outMin: number, outMax: number) => number;
-/**
- * Performs a dirty check to see if two Vec2 points are different within an epsilon.
- */
-declare const isVec2Equal: (v1: Vec2, v2: Vec2, epsilon?: number) => boolean;
-/**
- * Core deadzone logic.
- * Maps a value from [threshold, max] to a normalized scale [0, 1].
- * @returns A scalar value between 0 and 1.
- */
-declare const getDeadzoneScalar: (magnitude: number, threshold: number, max: number) => number;
-/**
- * Applies a radial deadzone to a vector.
- * Suitable for analog sticks to ensure a smooth transition from center.
- * @param v - Input vector.
- * @param radius - The total radius of the joystick base.
- * @param deadzonePercent - Deadzone threshold (0.0 to 1.0).
- */
-declare const applyRadialDeadzone: (v: Vec2, radius: number, deadzonePercent: number) => Vec2;
-/**
- * Applies an axial deadzone to a vector.
- * Independently processes X and Y axes. Useful for D-Pads or precision directional inputs.
- * @param v - Input vector.
- * @param threshold - The deadzone threshold value.
- * @param max - Maximum value for the axis.
- */
-declare const applyAxialDeadzone: (v: Vec2, threshold: number, max: number) => Vec2;
-
-/**
- * Recursively penetrates Shadow DOM boundaries to find the deepest element at the
- * specified viewport coordinates.
+ * GamepadManager
  *
- * @param x - Viewport X coordinate (px)
- * @param y - Viewport Y coordinate (px)
- * @param ignoreClass - Style class of DOM elements to be ignored
- * @returns The deepmost Element or null if none found at the position.
- */
-declare const getDeepElement: (x: number, y: number, ignoreClass?: string) => Element | null;
-/**
- * Recursively finds the truly focused element by traversing Shadow DOM boundaries.
+ * A singleton service that polls the browser Gamepad API via requestAnimationFrame.
+ * It translates physical hardware inputs into programmatic signals sent to
+ * virtual entities registered in the system.
  *
- * @returns The deepmost active Element in focus or null.
- */
-declare const getDeepActiveElement: () => Element | null;
-/**
- * Forcefully focuses an element.
- * Automatically handles the 'tabindex' attribute to ensure non-focusable elements (like Canvas)
- * can receive focus.
- *
- * @param el - The target HTMLElement to focus.
- */
-declare const focusElement: (el: HTMLElement) => void;
-/**
- * Dispatches a synthetic KeyboardEvent to the window object.
- *
- * @param type - The event type, e.g., 'keydown' or 'keyup'.
- * @param payload - Key mapping data including key, code, and legacy keyCode.
- */
-declare const dispatchKeyboardEvent: (type: string, payload: {
-    key: string;
-    code: string;
-    keyCode: number;
-}) => void;
-/**
- * Dispatches a high-fidelity sequence of Pointer and Mouse events at specific pixel coordinates.
- * Finds the target element dynamically at the moment of dispatch.
- *
- * @param type - The event type (should start with 'pointer' for best compatibility).
- * @param x - Viewport X coordinate (px).
- * @param y - Viewport Y coordinate (px).
- * @param opts - Additional PointerEvent options (button, pressure, etc.).
- */
-declare const dispatchPointerEventAtPos: (type: string, x: number, y: number, opts?: PointerEventInit) => void;
-/**
- * Calculates the pixel coordinate of an anchor point within a given DOMRect.
- * Used to translate relative layout definitions into screen-space pixels.
- *
- * @param rect - The bounding box of the container.
- * @param anchor - The defined anchor point (e.g., 'center', 'top-left').
- * @returns The absolute viewport coordinates {x, y}.
- */
-declare const getAnchorPosition: (rect: DOMRect, anchor: AnchorPoint) => Vec2;
-
-/**
- * Generates a globally unique identifier (UID) for runtime entity management and DOM keys.
- *
- * The generated ID follows the format: `[prefix]-[timestamp_base36]-[random_string]`.
- * This ensures that components generated at different times or across multiple sessions
- * remain unique within the current page instance.
- *
- * @param prefix - A string prefix for the ID, typically the component type (e.g., 'btn', 'joy'). Defaults to 'omnipad'.
- * @returns A unique string identifier.
- *
- * @example
- * generateUID('button') // returns "button-m7x8k1p2-f4k2"
- */
-declare const generateUID: (prefix?: string) => string;
-/**
- * Checks if the provided ID is a reserved global identifier.
- *
- * In OmniPad, IDs starting with the `$` symbol are considered "Global IDs".
- * These identifiers are treated as static references and are not transformed
- * into dynamic UIDs during configuration parsing.
- *
- * @param id - The identifier string to check.
- * @returns `true` if the ID starts with `$`, otherwise `false`.
- *
- * @example
- * isGlobalID('$root-layer') // returns true
- * isGlobalID('btn-up')      // returns false
- */
-declare function isGlobalID(id: string): boolean;
-
-/**
- * Converts a LayoutBox configuration into a CSS style object suitable for Vue/React.
- *
- * This utility handles:
- * 1. Unit normalization: Converts numeric values to 'px' strings while preserving unit strings (vh, %, etc.).
- * 2. Positioning: Sets 'absolute' positioning by default.
- * 3. Anchoring: Maps AnchorPoint values to CSS 'transform' translations to ensure
- *    the component's origin matches its defined coordinates.
- *
- * @param layout - The LayoutBox configuration object.
- * @returns A CSS style record object.
- *
- * @example
- * // returns { position: 'absolute', left: '50%', top: '50%', transform: 'translate(-50%, -50%)' }
- * resolveLayoutStyle({ left: '50%', top: '50%', anchor: 'center' });
- */
-declare const resolveLayoutStyle: (layout: LayoutBox) => Record<string, string | number>;
-
-/**
- * Validates and normalizes raw JSON data into a standard GamepadProfile.
- * Performs structural checks and injects default metadata.
- *
- * @param raw - The raw JSON object from disk or network.
- * @returns A validated GamepadProfile object.
- * @throws Error if the core structure is invalid.
- */
-declare function parseProfileJson(raw: any): GamepadProfile;
-/**
- * Converts a flat GamepadProfile into a hierarchical ConfigTreeNode tree for runtime rendering.
- * Handles CID (Config ID) to UID (Entity ID) mapping and reference resolution.
- *
- * @param profile - The normalized profile data.
- * @returns The root node of the configuration tree.
- */
-declare function parseProfileTree(profile: GamepadProfile): ConfigTreeNode;
-/**
- * Serializes the current runtime entities from the Registry back into a flat GamepadProfile.
- * Generates fresh Config IDs (CIDs) for all nodes except global IDs.
- *
- * @param meta - Metadata for the exported profile.
- * @param rootUid - The Entity ID of the node to be treated as the root.
- * @returns A flat GamepadProfile ready for storage.
- */
-declare function exportProfile(meta: GamepadProfile['meta'], rootUid: string): GamepadProfile;
-
-/**
- * Represents a callback function for the emitter.
- * @template T - The type of data being broadcasted.
- */
-type Listener<T> = (data: T) => void;
-/**
- * A lightweight implementation of the Observer pattern.
- * Used primarily within Core Entities to notify the Adapter layer of state changes.
- *
- * @template T - The state or data object type.
- */
-declare class SimpleEmitter<T> {
-    private listeners;
+ * Handles:
+ * 1. Button edge detection (Down/Up).
+ * 2. D-Pad to vector conversion.
+ * 3. Analog stick deadzone processing.
+ */
+declare class GamepadManager {
+    private isRunning;
+    private config;
+    private lastButtonStates;
+    private constructor();
     /**
-     * Registers a callback function to be executed whenever data is emitted.
-     *
-     * @param fn - The callback function.
-     * @returns A function that, when called, unsubscribes the listener.
+     * Retrieves the global singleton instance of the GamepadManager.
      */
-    subscribe(fn: Listener<T>): () => void;
+    static getInstance(): GamepadManager;
     /**
-     * Broadcasts the provided data to all registered listeners.
-     * Each listener is executed within a try-catch block to ensure that
-     * an error in one subscriber doesn't prevent others from receiving the signal.
+     * Updates the current gamepad mapping configuration.
      *
-     * @param data - The payload to be sent to all subscribers.
+     * @param config - The mapping of physical inputs to virtual component IDs (UID).
      */
-    emit(data: T): void;
+    setConfig(config: GamepadMappingConfig[]): void;
+    /** Return the current gamepad mapping configuration. */
+    getConfig(): Readonly<GamepadMappingConfig[] | null>;
     /**
-     * Removes all listeners and clears the subscription set.
-     * Essential for preventing memory leaks when an Entity is destroyed.
+     * Starts the polling loop and listens for gamepad connection events.
      */
-    clear(): void;
+    start(): void;
+    /**
+     * Stops the polling loop.
+     */
+    stop(): void;
+    /**
+     * The core polling loop executing at the browser's refresh rate.
+     */
+    private loop;
+    /**
+     * Process binary button inputs with edge detection.
+     */
+    private processButtons;
+    /**
+     * Translates physical D-Pad buttons into a normalized vector.
+     */
+    private processDPad;
+    /**
+     * Process analog stick movements with deadzone logic.
+     */
+    private processAxes;
+    /**
+     * Locates a virtual entity and triggers its programmatic interface.
+     *
+     * @param uid - The Entity ID (UID) of the target.
+     * @param action - The type of trigger ('down', 'up', or 'vector').
+     * @param payload - Optional data for vector movements.
+     */
+    private triggerVirtualEntity;
 }
 
 /**
@@ -1389,6 +292,41 @@ declare class Registry implements IRegistry {
     debugGetSnapshot(): Map<string, ICoreEntity>;
 }
 
+/**
+ * Represents a callback function for the emitter.
+ * @template T - The type of data being broadcasted.
+ */
+type Listener<T> = (data: T) => void;
+/**
+ * A lightweight implementation of the Observer pattern.
+ * Used primarily within Core Entities to notify the Adapter layer of state changes.
+ *
+ * @template T - The state or data object type.
+ */
+declare class SimpleEmitter<T> {
+    private listeners;
+    /**
+     * Registers a callback function to be executed whenever data is emitted.
+     *
+     * @param fn - The callback function.
+     * @returns A function that, when called, unsubscribes the listener.
+     */
+    subscribe(fn: Listener<T>): () => void;
+    /**
+     * Broadcasts the provided data to all registered listeners.
+     * Each listener is executed within a try-catch block to ensure that
+     * an error in one subscriber doesn't prevent others from receiving the signal.
+     *
+     * @param data - The payload to be sent to all subscribers.
+     */
+    emit(data: T): void;
+    /**
+     * Removes all listeners and clears the subscription set.
+     * Essential for preventing memory leaks when an Entity is destroyed.
+     */
+    clear(): void;
+}
+
 /**
  * Base abstract class for all logic entities in the system.
  * Provides fundamental identity management, state subscription, and spatial awareness.
@@ -1398,7 +336,7 @@ declare abstract class BaseEntity<TConfig, TState> implements ICoreEntity, ISpat
     readonly type: EntityType;
     protected config: TConfig;
     protected state: TState;
-    protected rectProvider: (() => DOMRect) | null;
+    protected rectProvider: (() => AbstractRect) | null;
     protected stateEmitter: SimpleEmitter<TState>;
     constructor(uid: string, type: EntityType, initialConfig: TConfig, initialState: TState);
     subscribe(cb: (state: TState) => void): () => void;
@@ -1410,32 +348,85 @@ declare abstract class BaseEntity<TConfig, TState> implements ICoreEntity, ISpat
     protected setState(partialState: Partial<TState>): void;
     destroy(): void;
     abstract reset(): void;
-    bindRectProvider(provider: () => DOMRect): void;
-    /**
-     * Called when triggering interactions, this subclass fetches the latest boundaries in real time.
-     */
-    getRect(): DOMRect | null;
+    get rect(): AbstractRect | null;
+    bindRectProvider(provider: () => AbstractRect): void;
     updateConfig(newConfig: Partial<TConfig>): void;
     getState(): Readonly<TState>;
     getConfig(): Readonly<TConfig>;
 }
 
+/**
+ * Core logic implementation for a button widget.
+ * Handles pointer interactions and translates them into keyboard signals for a target stage.
+ */
+declare class ButtonCore extends BaseEntity<ButtonConfig, ButtonState> implements IPointerHandler, IProgrammatic {
+    private emitter;
+    /**
+     * Creates an instance of KeyboardButtonCore.
+     *
+     * @param uid - The unique entity ID.
+     * @param config - The flat configuration object for the button.
+     */
+    constructor(uid: string, config: ButtonConfig);
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(): void;
+    onPointerMove(): void;
+    reset(): void;
+    updateConfig(newConfig: Partial<ButtonConfig>): void;
+    /**
+     * Clean up pointer capture and reset interaction state.
+     */
+    private handleRelease;
+    triggerDown(): void;
+    triggerUp(): void;
+}
+
+/**
+ * Core logic for a virtual D-Pad widget.
+ *
+ * Acts as a spatial distributor that maps a single touch point to 4 independent ActionEmitters.
+ * Supports 8-way input by allowing simultaneous activation of orthogonal directions.
+ */
+declare class DPadCore extends BaseEntity<DPadConfig, DPadState> implements IPointerHandler, IProgrammatic {
+    private emitters;
+    private throttledPointerMove;
+    constructor(uid: string, config: DPadConfig);
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(): void;
+    /**
+     * Evaluates the touch position and updates the 4 emitters accordingly.
+     * 使用轴向分割逻辑处理 8 方向输入
+     */
+    private processInput;
+    /**
+     * 将摇杆位置转换为 4/8 方向按键信号
+     */
+    private handleDigitalKeys;
+    reset(): void;
+    updateConfig(newConfig: Partial<DPadConfig>): void;
+    triggerVector(x: number, y: number): void;
+}
+
 /**
  * Logic core for InputZone.
  *
  * Manages a container for input widgets and handles the lifecycle of
  * dynamic (floating) widgets when interacting with empty space.
  */
-declare class InputZoneCore extends BaseEntity<InputZoneConfig, InputZoneState> implements IPointerHandler {
+declare class InputZoneCore extends BaseEntity<InputZoneConfig, InputZoneState> implements IPointerHandler, IDependencyBindable {
+    private delegates;
     constructor(uid: string, config: InputZoneConfig);
-    onPointerDown(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
-    /**
-     * Internal helper to handle pointer release and cleanup.
-     */
-    private handleRelease;
+    bindDelegate(key: string, delegate: AnyFunction): void;
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(e: AbstractPointerEvent): void;
     /**
      * Converts viewport pixels to percentage coordinates relative to the zone.
      */
@@ -1448,60 +439,46 @@ declare class InputZoneCore extends BaseEntity<InputZoneConfig, InputZoneState>
 }
 
 /**
- * Core logic implementation for a keyboard button widget.
- * Handles pointer interactions and translates them into keyboard signals for a target stage.
- */
-declare class KeyboardButtonCore extends BaseEntity<KeyboardButtonConfig, KeyboardButtonState> implements IPointerHandler {
-    /**
-     * Creates an instance of KeyboardButtonCore.
-     *
-     * @param uid - The unique entity ID.
-     * @param config - The flat configuration object for the button.
-     */
-    constructor(uid: string, config: KeyboardButtonConfig);
-    onPointerDown(e: PointerEvent): void;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
+ * Joystick Core Implementation.
+ *
+ * Supports dual-mode output:
+ * 1. Digital: Maps angles to 4/8-way key signals.
+ * 2. Analog/Cursor: Maps vector to continuous cursor movement via Tick mechanism.
+ */
+declare class JoystickCore extends BaseEntity<JoystickConfig, JoystickState> implements IPointerHandler, IProgrammatic {
+    private emitters;
+    private stickEmitter;
+    private cursorEmitter;
+    private gesture;
+    private ticker;
+    private throttledUpdate;
+    constructor(uid: string, config: JoystickConfig);
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(): void;
     /**
-     * Common logic for releasing the button state.
-     *
-     * @param e - The pointer event that triggered the release.
+     * Clean up pointer capture and reset interaction state.
      */
     private handleRelease;
     /**
-     * Dispatches input signals to the registered target stage.
-     *
-     * @param type - The action type (keydown or keyup).
+     * 计算位移向量并驱动按键逻辑 / Calculate vector and drive key logic
      */
-    private sendInputSignal;
-    reset(): void;
-}
-
-/**
- * Core logic implementation for a mouse button widget.
- * Handles pointer interactions and translates them into mouse signals (down, up, click) for a target stage.
- */
-declare class MouseButtonCore extends BaseEntity<MouseButtonConfig, MouseButtonState> implements IPointerHandler {
-    constructor(uid: string, config: MouseButtonConfig);
-    onPointerDown(e: PointerEvent): void;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
+    private processInput;
     /**
-     * Handles the release of the button.
-     *
-     * @param e - The pointer event.
-     * @param isNormalRelease - If true, a 'click' event will also be dispatched.
+     * Ticker 回调：处理每帧的光标位移输出
      */
-    private handleRelease;
+    private handleCursorTick;
     /**
-     * Dispatches input signals to the registered target stage.
-     *
-     * @param type - The action type (mousedown, mouseup, or click).
+     * 将摇杆位置转换为 4/8 方向按键信号
      */
-    private sendInputSignal;
+    private handleDigitalKeys;
     reset(): void;
+    updateConfig(newConfig: Partial<JoystickConfig>): void;
+    triggerDown(): void;
+    triggerUp(): void;
+    triggerVector(x: number, y: number): void;
 }
 
 /**
@@ -1521,15 +498,18 @@ declare class RootLayerCore extends BaseEntity<BaseConfig, LayerState> {
  * It acts as a receiver that translates abstract input signals into native browser events,
  * while maintaining virtual cursor positioning and ensuring the game maintains focus.
  */
-declare class TargetZoneCore extends BaseEntity<TargetZoneConfig, CursorState> implements IPointerHandler, ISignalReceiver {
+declare class TargetZoneCore extends BaseEntity<TargetZoneConfig, CursorState> implements IPointerHandler, ISignalReceiver, IDependencyBindable {
     private hideTimer;
     private focusFeedbackTimer;
     private throttledPointerMove;
+    private delegates;
     constructor(uid: string, config: TargetZoneConfig);
-    onPointerDown(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
+    bindDelegate(key: string, delegate: AnyFunction): void;
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(e: AbstractPointerEvent): void;
     /**
      * Convert physical DOM events into internal signals
      */
@@ -1567,16 +547,19 @@ declare class TargetZoneCore extends BaseEntity<TargetZoneConfig, CursorState> i
 
 /**
  * Core logic implementation for a trackpad widget.
+ *
  * Translates pointer gestures into relative mouse movements and click actions.
- * Supports tap-to-click and double-tap-to-drag scenarios.
+ * Supports:
+ * - Single Tap: Dispatches a 'click' signal.
+ * - Swipe: Dispatches incremental 'mousemove' signals.
+ * - Double-tap and Hold: Enters drag mode (mousedown + mousemove).
  */
 declare class TrackpadCore extends BaseEntity<TrackpadConfig, TrackpadState> implements IPointerHandler {
+    /** Stores the last processed client coordinates to calculate delta / 存储上次处理的客户端坐标以计算增量 */
     private lastPointerPos;
-    private startTime;
-    private startPos;
-    private lastClickTime;
-    private isDragMode;
     private throttledPointerMove;
+    private gesture;
+    private emitter;
     /**
      * Creates an instance of TrackpadCore.
      *
@@ -1584,8 +567,9 @@ declare class TrackpadCore extends BaseEntity<TrackpadConfig, TrackpadState> imp
      * @param config - Configuration for the trackpad.
      */
     constructor(uid: string, config: TrackpadConfig);
-    onPointerDown(e: PointerEvent): void;
-    onPointerMove(e: PointerEvent): void;
+    get activePointerId(): number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
     /**
      * Internal logic for processing pointer movement.
      * Calculates displacement and emits relative move signals.
@@ -1593,20 +577,14 @@ declare class TrackpadCore extends BaseEntity<TrackpadConfig, TrackpadState> imp
      * @param e - The pointer event.
      */
     private processPointerMove;
-    onPointerUp(e: PointerEvent): void;
-    onPointerCancel(e: PointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(): void;
     reset(): void;
+    updateConfig(newConfig: Partial<TrackpadConfig>): void;
     /**
      * Clean up pointer capture and reset interaction state.
      */
     private handleRelease;
-    /**
-     * Helper to send signals to the target stage via Registry.
-     *
-     * @param type - Signal action type.
-     * @param extraPayload - Additional data like delta or point.
-     */
-    private sendSignal;
 }
 
 declare const OmniPad: {
@@ -2126,9 +1104,10 @@ declare const OmniPad: {
     Types: {
         readonly INPUT_ZONE: "input-zone";
         readonly TARGET_ZONE: "target-zone";
+        readonly BUTTON: "button";
         readonly KEYBOARD_BUTTON: "keyboard-button";
         readonly MOUSE_BUTTON: "mouse-button";
-        readonly ANALOG_STICK: "analog-stick";
+        readonly JOYSTICK: "joystick";
         readonly D_PAD: "d-pad";
         readonly TRACKPAD: "trackpad";
         readonly VIRTUAL_CURSOR: "virtual-cursor";
@@ -2136,4 +1115,4 @@ declare const OmniPad: {
     };
 };
 
-export { ACTION_TYPES, type AnchorPoint, type AnyConfig, type AnyEntityType, type BaseConfig, BaseEntity, type BuiltInActionType, type ButtonLogicState, CMP_TYPES, CONTEXT, type ConfigTreeNode, type CursorState, type EntityType, type FlatConfigItem, type FlexibleLength, type GamepadProfile, type IConfigurable, type ICoreEntity, type IIdentifiable, type ILifecycle, type IObservable, type IPointerHandler, type IRegistry, type IResettable, type ISignalReceiver, type ISpatial, type InputActionSignal, type InputActionType, InputManager, type InputZoneConfig, InputZoneCore, type InputZoneState, type InteractionState, type JoystickLogicState, type JoystickState, KEYS, type KeyMapping, type KeyboardButtonConfig, KeyboardButtonCore, type KeyboardButtonState, type LayerState, type LayoutBox, type Listener, type MouseButtonConfig, MouseButtonCore, type MouseButtonState, OmniPad, Registry, RootLayerCore, SimpleEmitter, type StageId, type TargetZoneConfig, TargetZoneCore, type TrackpadConfig, TrackpadCore, type TrackpadState, type Unit, type Vec2, type WidgetId, type WidgetType, type ZoneId, type ZoneType, addVec, applyAxialDeadzone, applyRadialDeadzone, clamp, clampVector, degToRad, dispatchKeyboardEvent, dispatchPointerEventAtPos, exportProfile, focusElement, generateUID, getAnchorPosition, getAngle, getDeadzoneScalar, getDeepActiveElement, getDeepElement, getDistance, isGlobalID, isVec2Equal, lerp, lockTo4Directions, lockTo8Directions, normalizeVec, parseProfileJson, parseProfileTree, percentToPx, pxToPercent, radToDeg, radToVec, remap, resolveLayoutStyle, roundTo, scaleVec, subVec };
+export { AbstractPointerEvent, AbstractRect, AnyFunction, type AxisLogicState, BaseConfig, BaseEntity, ButtonConfig, ButtonCore, type ButtonLogicState, type ButtonState, type CursorState, DPadConfig, DPadCore, type DPadState, EntityType, GamepadManager, GamepadMappingConfig, IConfigurable, ICoreEntity, IDependencyBindable, IObservable, IPointerHandler, IProgrammatic, type IRegistry, IResettable, ISignalReceiver, ISpatial, InputActionSignal, InputManager, InputZoneConfig, InputZoneCore, type InputZoneState, type InteractionState, JoystickConfig, JoystickCore, type JoystickState, type KeyboardButtonState, type LayerState, type MouseButtonState, OmniPad, Registry, RootLayerCore, TargetZoneConfig, TargetZoneCore, TrackpadConfig, TrackpadCore, type TrackpadState, Vec2 };