@omnipad/core 0.2.0-alpha.3 → 0.4.0

package/dist/index-DRA1rw5_.d.ts

@@ -0,0 +1,1047 @@
+/** Standard buttons for Gamepad API */
+type StandardButton = 'A' | 'B' | 'X' | 'Y' | 'LB' | 'RB' | 'LT' | 'RT' | 'Select' | 'Start' | 'L3' | 'R3' | 'Up' | 'Down' | 'Left' | 'Right';
+interface GamepadMappingConfig {
+    /**
+     * Mapping of standard gamepad buttons to virtual component CIDs.
+     * Key: Standard button name (e.g., 'A', 'X', 'RT').
+     * Value: Configuration ID (CID) of the target virtual widget.
+     */
+    buttons?: Partial<Record<StandardButton, string>>;
+    /**
+     * CID of the virtual widget (D-Pad) to be driven by the physical d-pad.
+     */
+    dpad?: string;
+    /**
+     * CID of the virtual widget (Joystick or D-Pad) to be driven by the physical left stick.
+     */
+    leftStick?: string;
+    /**
+     * CID of the virtual widget (Joystick or D-Pad) to be driven by the physical right stick.
+     */
+    rightStick?: string;
+    /**
+     * Minimum axial displacement required to trigger input (0.0 to 1.0).
+     * Prevents drift issues on older controllers.
+     * @default 0.1
+     */
+    deadzone?: number;
+}
+
+/**
+ * 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;
+}
+/**
+ * Unified action definition.
+ * Discriminated by the 'type' field, but shares a common structure for ease of use.
+ */
+interface ActionMapping {
+    /** 指定动作类型：'keyboard' | 'mouse' */
+    type: 'keyboard' | 'mouse';
+    key?: string;
+    code?: string;
+    keyCode?: number;
+    /** 0: Left, 1: Middle, 2: Right */
+    button?: 0 | 1 | 2;
+    /** Fixed coordinate (0-100 percentage) */
+    fixedPoint?: Vec2;
+}
+/**
+ * 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;
+    /** Whether equal width and length. (aspect-ratio: 1/1) */
+    isSquare?: boolean;
+    /**
+     * 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. */
+    baseType: string;
+    /** CID of the parent component. Root components have no parentId. */
+    parentId?: string;
+    /** Spatial layout configuration relative to its parent zone. */
+    layout: LayoutBox;
+    /**
+     * Custom CSS class names or style tags.
+     * For visual decoration only; must not include layout attributes such as top/left/width/height.
+     */
+    cssClasses?: string | string[];
+}
+/**
+ * Configuration for a virtual keyboard/mouse button.
+ */
+interface ButtonConfig extends BaseConfig {
+    baseType: typeof CMP_TYPES.BUTTON;
+    /** The text or symbol displayed on the button surface. */
+    label?: string;
+    /** CID of the TargetZone where signals should be dispatched. */
+    targetStageId?: string;
+    /** Keyboard or mouse event metadata to be emitted when triggered. */
+    mapping?: ActionMapping;
+}
+/**
+ * Configuration for a virtual trackpad.
+ */
+interface TrackpadConfig extends BaseConfig {
+    baseType: typeof CMP_TYPES.TRACKPAD;
+    /** The text or symbol displayed on the trackpad surface. */
+    label?: string;
+    /** Determines the mapping ratio between the physical displacement of the trackpad and the movement of the screen cursor. */
+    sensitivity?: number;
+    /** CID of the TargetZone where signals should be dispatched. */
+    targetStageId?: string;
+    /** Optional: Mouse or keyboard event metadata to be emitted when triggered. */
+    mapping?: ActionMapping;
+}
+/**
+ * Configuration for a virtual d-pad.
+ */
+interface DPadConfig extends BaseConfig {
+    baseType: typeof CMP_TYPES.D_PAD;
+    /** CID of the TargetZone where signals should be dispatched. */
+    targetStageId?: string;
+    /** Defines the specific actions or key signals emitted for each cardinal direction. */
+    mapping?: {
+        up: ActionMapping;
+        down: ActionMapping;
+        left: ActionMapping;
+        right: ActionMapping;
+    };
+    /** Determines the minimum travel distance required to trigger a direction. */
+    threshold?: number;
+    showStick?: boolean;
+}
+interface JoystickConfig extends BaseConfig {
+    baseType: typeof CMP_TYPES.JOYSTICK;
+    /** The text or symbol displayed on the stick button surface. */
+    label?: string;
+    /** CID of the TargetZone where signals should be dispatched. */
+    targetStageId?: string;
+    /** Determines the minimum travel distance required to trigger a direction. */
+    threshold?: number;
+    /** Whether enable cursor displacement simulation. */
+    cursorMode?: boolean;
+    /** Determines the mapping velocity between the physical displacement of the joystick and the movement of the screen cursor. */
+    cursorSensitivity?: number;
+    /** Defines the specific actions or key signals emitted for each cardinal direction and stick button. */
+    mapping?: {
+        up?: ActionMapping;
+        down?: ActionMapping;
+        left?: ActionMapping;
+        right?: ActionMapping;
+        stick?: ActionMapping;
+    };
+}
+/**
+ * Configuration for an Input Zone.
+ * Input Zones act as containers and can handle dynamic (floating) widgets.
+ */
+interface InputZoneConfig extends BaseConfig {
+    baseType: typeof CMP_TYPES.INPUT_ZONE;
+    /** If true, prevents the browser focus from leaving the game area when touching this zone. */
+    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 {
+    baseType: typeof CMP_TYPES.TARGET_ZONE;
+    /** Whether to render a visual virtual cursor. */
+    cursorEnabled?: boolean;
+    /** Delay in milliseconds before the virtual cursor auto-hides after inactivity (0 to disable). */
+    cursorAutoDelay?: number;
+}
+/**
+ * Union type representing any valid component configuration.
+ */
+type AnyConfig = ButtonConfig | InputZoneConfig | TargetZoneConfig | TrackpadConfig | DPadConfig | JoystickConfig | 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;
+        description?: string;
+    };
+    /** List of all components in the profile. Hierarchies are defined via parentId. */
+    items: FlatConfigItem[];
+    /**
+     * Global mapping configuration for physical gamepad hardware.
+     * Defines how hardware inputs interact with the virtual components listed in 'items'.
+     */
+    gamepadMappings?: GamepadMappingConfig[];
+}
+/**
+ * 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 {
+    readonly rect: AbstractRect | null;
+    /**
+     * Dynamically obtain dimensions and position to ensure the most precise real-time screen coordinates are obtained during each interaction.
+     */
+    bindRectProvider(provider: () => AbstractRect): 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 {
+    readonly activePointerId: number | null;
+    onPointerDown(e: AbstractPointerEvent): void;
+    onPointerMove(e: AbstractPointerEvent): void;
+    onPointerUp(e: AbstractPointerEvent): void;
+    onPointerCancel(e: AbstractPointerEvent): 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;
+}
+/**
+ * Capability for an entity to receive and store external functional dependencies.
+ *
+ * This enables Runtime Dependency Injection (DI), allowing core logic to invoke
+ * host-specific methods (such as DOM event dispatchers or custom triggers)
+ * without being tightly coupled to the environment.
+ */
+interface IDependencyBindable {
+    /**
+     * Binds a functional delegate by a specific identifier key.
+     *
+     * @param key - The unique lookup identifier for the dependency (e.g., 'domDispatcher').
+     * @param delegate - The function implementation provided by the adapter layer.
+     */
+    bindDelegate(key: string, delegate: AnyFunction): void;
+}
+/**
+ * Contract for widgets that support programmatic control.
+ *
+ * This interface allows external systems—such as a Physical Gamepad Manager or
+ * automation scripts—to directly drive the state and behavior of a widget,
+ * bypassing native DOM pointer events.
+ */
+interface IProgrammatic {
+    /**
+     * Manually triggers the 'down' (pressed) state of the widget.
+     * Primarily used for Button-type components to simulate a physical press.
+     */
+    triggerDown?(): void;
+    /**
+     * Manually triggers the 'up' (released) state of the widget.
+     * Primarily used for Button-type components to simulate a physical release.
+     */
+    triggerUp?(): void;
+    /**
+     * Manually updates the directional input vector of the widget.
+     * Primarily used for Joystick or D-Pad components.
+     *
+     * @param x - The horizontal component, normalized between -1.0 and 1.0.
+     * @param y - The vertical component, normalized between -1.0 and 1.0.
+     */
+    triggerVector?(x: number, y: number): void;
+}
+
+/**
+ * =================================================================
+ * 1. Constants Definition
+ * Used for runtime logic and as a baseline for type definitions.
+ * =================================================================
+ */
+/**
+ * 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";
+    readonly BUTTON: "button";
+    /** 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 JOYSTICK: "joystick";
+    /** 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 an abstract bounding box, typically used as a
+ * lightweight alternative to the DOMRect interface.
+ */
+interface AbstractRect {
+    left: number;
+    top: number;
+    width: number;
+    height: number;
+}
+/** * Represents abstract pointer data, providing a platform-agnostic
+ * alternative to the native PointerEvent.
+ */
+interface AbstractPointerEvent {
+    pointerId: number;
+    clientX: number;
+    clientY: number;
+    button: number;
+}
+/**
+ * Represents a 2D coordinate or vector.
+ * Typically used for percentage-based positioning (0-100).
+ */
+interface Vec2 {
+    x: number;
+    y: number;
+}
+/** 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.BUTTON | typeof CMP_TYPES.KEYBOARD_BUTTON | typeof CMP_TYPES.MOUSE_BUTTON | typeof CMP_TYPES.JOYSTICK | 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.
+ * =================================================================
+ */
+/**
+ * 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;
+    };
+}
+/**
+ * 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";
+};
+/**
+ * A safe alternative to the global 'Function' type.
+ * Represents any callable function with any arguments.
+ */
+type AnyFunction = (...args: any[]) => void;
+
+export { type AbstractRect as A, type ButtonConfig as B, CMP_TYPES as C, type DPadConfig as D, type EntityType as E, type FlatConfigItem as F, type GamepadMappingConfig as G, type InputActionType as H, type ICoreEntity as I, type JoystickConfig as J, KEYS as K, type KeyMapping as L, type LayoutBox as M, type StandardButton as N, type WidgetType as O, type ZoneType as P, type StageId as S, type TargetZoneConfig as T, type Unit as U, type Vec2 as V, type WidgetId as W, type ZoneId as Z, type ISpatial as a, type IResettable as b, type IConfigurable as c, type IObservable as d, type IPointerHandler as e, type IProgrammatic as f, type AbstractPointerEvent as g, type InputZoneConfig as h, type IDependencyBindable as i, type AnyFunction as j, type BaseConfig as k, type ISignalReceiver as l, type InputActionSignal as m, type TrackpadConfig as n, ACTION_TYPES as o, type ActionMapping as p, type AnchorPoint as q, type AnyConfig as r, type AnyEntityType as s, type BuiltInActionType as t, CONTEXT as u, type ConfigTreeNode as v, type FlexibleLength as w, type GamepadProfile as x, type IIdentifiable as y, type ILifecycle as z };