@yagejs/input 0.4.0 → 0.5.0

package/dist/api-BaItBbSe.d.cts

@@ -0,0 +1,685 @@
+import { Vec2, RendererAdapter, ServiceKey } from '@yagejs/core';
+
+/** Central input state manager. Resolved via DI with InputManagerKey. */
+declare class InputManager {
+    private pressedKeys;
+    private justPressedKeys;
+    private justReleasedKeys;
+    private holdStart;
+    private syntheticPressedActions;
+    private syntheticActionStarts;
+    private actionMap;
+    private defaultBindings;
+    private groups;
+    private actionGroups;
+    private disabledGroups;
+    /** Tracked pointers keyed by `pointerId`. Mouse persists; touch/pen removed on up/cancel. */
+    private pointers;
+    /** Id of the pointer the browser last marked `isPrimary`, or `null` when none are tracked. */
+    private primaryPointerId;
+    /**
+     * Aggregate "any pointer has this button held" cache. The action-map codes
+     * `MouseLeft`/`MouseMiddle`/`MouseRight` are driven from edges into/out of this
+     * set so two simultaneous taps holding button 0 do not double-fire.
+     * Consumed pointers are excluded from the aggregate so UI-claimed presses
+     * never propagate to gameplay actions.
+     */
+    private mouseButtonAggregate;
+    /**
+     * Pointers marked as "claimed" via {@link consumePointer} (or auto-claimed by
+     * the renderer's UI hit-test fallback). Lifetime is per-pointer-event-cycle:
+     * cleared when the pointer's last button releases (drained `pointerUp`) or on
+     * `pointercancel`.
+     */
+    private consumedPointers;
+    /** Wheel-edge gate flipped by {@link consumeWheel}. Cleared at end of frame. */
+    private consumedWheelThisFrame;
+    /** Buffered DOM-originated events awaiting drain at `Phase.EarlyUpdate`. */
+    private inputQueue;
+    /**
+     * Renderer reference for the optional `hitTestUI(x, y)` lookup. Stashed by
+     * {@link _setRenderer} during `InputPlugin.install` so the drain step can
+     * read it cheaply each frame.
+     */
+    private renderer;
+    private pointerDownListeners;
+    private pointerUpListeners;
+    private pointerMoveListeners;
+    private keyDownListenersAny;
+    private keyUpListenersAny;
+    private keyDownListeners;
+    private keyUpListeners;
+    private actionListeners;
+    private actionReleasedListeners;
+    private wheelListeners;
+    /** Real-pad axis values keyed by `${padIndex}:${axisKey}`. */
+    private gamepadAxisState;
+    /** Synthetic axis values for fireGamepadAxis injection (test path). */
+    private syntheticAxisState;
+    /** "Any pad" aggregate of currently-pressed gamepad codes. */
+    private lastButtonState;
+    /** Per-pad "anything happening" flag, used to detect rising-edge activity for active-pad promotion. */
+    private lastPadActivity;
+    /** Pads currently known to the engine (populated via events or polling). */
+    private connectedPads;
+    /** Index of the pad whose analog input is read by default. `null` when no pad is connected. */
+    private activePadIndex;
+    private gamepadConnectListeners;
+    private gamepadDisconnectListeners;
+    private activePadListeners;
+    private stickDeadzone;
+    private triggerDeadzone;
+    private triggerThreshold;
+    private pollingEnabled;
+    private camera;
+    private elapsedMs;
+    private listenResolve;
+    /** Whether any key mapped to this action is currently held. */
+    isPressed(action: string): boolean;
+    /** Whether any key mapped to this action was pressed this frame. */
+    isJustPressed(action: string): boolean;
+    /** Whether any key mapped to this action was released this frame. */
+    isJustReleased(action: string): boolean;
+    /** Returns true if any key bound to the action exists in the given set. */
+    private anyKeyInSet;
+    /** Milliseconds the action has been held. Returns 0 if not held. */
+    getHoldDuration(action: string): number;
+    /** Whether the action has been held for at least `minTime` ms. */
+    isHeldFor(action: string, minTime: number): boolean;
+    /** Returns -1, 0, or 1 based on negative/positive action states. */
+    getAxis(negative: string, positive: string): number;
+    /** Returns a Vec2 from four directional actions. Not normalized. */
+    getVector(left: string, right: string, up: string, down: string): Vec2;
+    /**
+     * Primary pointer's position in world coordinates (via Camera), or screen
+     * coords if no camera. Returns `Vec2.ZERO` when no pointer is tracked.
+     *
+     * For multi-pointer access (touch UIs etc.) iterate {@link getPointers} and
+     * convert each `screenPos` via the camera as needed.
+     */
+    getPointerPosition(): Vec2;
+    /** Primary pointer's raw position in screen coordinates, or `Vec2.ZERO` when no pointer is tracked. */
+    getPointerScreenPosition(): Vec2;
+    /** Whether the primary pointer has any button held. */
+    isPointerDown(): boolean;
+    /** All currently-tracked pointers (one per active mouse, pen, or finger). */
+    getPointers(): readonly PointerInfo[];
+    /** Direct lookup by `pointerId`, or `undefined` if no pointer with that id is tracked. */
+    getPointer(id: number): PointerInfo | undefined;
+    /**
+     * Defensive snapshot of a tracked pointer. The runtime `MutablePointerInfo`
+     * holds a real `Set` for `buttons` — even though the `PointerInfo` type
+     * declares `ReadonlySet`, JS doesn't enforce that at runtime, so we copy the
+     * set on every public read. `Vec2` is convention-immutable across YAGE, so
+     * we share the same instance.
+     */
+    private toPointerInfo;
+    /**
+     * Subscribe to pointer-down events (button transitions from up → down on a
+     * tracked pointer). Returns a disposer that detaches the listener.
+     */
+    onPointerDown(fn: (info: PointerInfo) => void): () => void;
+    /**
+     * Subscribe to pointer-up events (button transitions from down → up, plus
+     * touch / pen lifecycle ends and `pointercancel`). Returns a disposer.
+     */
+    onPointerUp(fn: (info: PointerInfo) => void): () => void;
+    /** Subscribe to pointer-move events. Returns a disposer. */
+    onPointerMove(fn: (info: PointerInfo) => void): () => void;
+    /**
+     * Mark a pointer as claimed for the rest of its event cycle (down → up).
+     * Subsequent action-map edges for this pointer (e.g. the `MouseLeft` edge a
+     * `pointerdown` would normally fire) are suppressed; `onPointerDown/Up/Move`
+     * listeners still fire because they are explicit user opt-ins.
+     *
+     * The mark clears automatically when the pointer's last button releases or
+     * on `pointercancel`. Call from a Pixi `pointerdown` handler that wants to
+     * own the event: `manager.consumePointer(e.pointerId)`.
+     */
+    consumePointer(id: number): void;
+    /** Whether the pointer is currently marked consumed. */
+    isPointerConsumed(id: number): boolean;
+    /**
+     * Suppress wheel action-map edges (`WheelUp/Down/Left/Right`) for the rest
+     * of the current frame. `onWheel` listeners still fire.
+     */
+    consumeWheel(): void;
+    /**
+     * Subscribe to key-down events. Pass a code (e.g. `"Space"`, `"GamepadA"`)
+     * to filter, or `"*"` for all keys. The listener fires on the same edge
+     * `isJustPressed` reports — for DOM-originated events that's the next
+     * `Phase.EarlyUpdate` after the browser dispatches; for synthetic injection
+     * (`fireKeyDown`) it's synchronous. Returns a disposer.
+     */
+    onKeyDown(code: string, fn: (code: string) => void): () => void;
+    /** Subscribe to key-up events. See {@link onKeyDown}. */
+    onKeyUp(code: string, fn: (code: string) => void): () => void;
+    /**
+     * Subscribe to action press edges (rising edge of any key bound to the
+     * action). Fires once per press. Returns a disposer.
+     */
+    onAction(name: string, fn: (name: string) => void): () => void;
+    /** Subscribe to action release edges. Returns a disposer. */
+    onActionReleased(name: string, fn: (name: string) => void): () => void;
+    /**
+     * Subscribe to scroll-wheel events. Receives raw `deltaX`/`deltaY` (already
+     * sign-flipped by `InputConfig.wheelInvertY` if set). Fires regardless of
+     * {@link consumeWheel} — it only gates action edges. Returns a disposer.
+     */
+    onWheel(fn: (dx: number, dy: number) => void): () => void;
+    private getPrimaryPointer;
+    /** Replace the entire action map and store it as the default for {@link resetBindings}. */
+    setActionMap(actions: ActionMapDefinition): void;
+    /** Add a key binding to an action. Creates the action if it doesn't exist. */
+    bindKey(action: string, key: string): void;
+    /** Remove a key binding from an action. */
+    unbindKey(action: string, key: string): void;
+    /** Returns the current key bindings for an action, or an empty array if unmapped. */
+    getBindings(action: string): readonly string[];
+    /** Returns all action names that have the given key bound. */
+    getActionsForKey(key: string): string[];
+    /**
+     * Rebind a key to an action with optional conflict detection.
+     * Conflicts are only detected between actions sharing at least one group.
+     */
+    rebind(action: string, key: string, opts?: RebindOptions): RebindResult;
+    /**
+     * Finds the first action that uses the given key AND shares at least one
+     * group with the target action. Ungrouped actions never conflict.
+     */
+    private findConflictInGroups;
+    /** Reset bindings to defaults. If an action name is provided, only reset that action. */
+    resetBindings(action?: string): void;
+    /** Export the current bindings as a plain object for serialization. */
+    exportBindings(): ActionMapDefinition;
+    /** Load bindings from a plain object. Resets to defaults first, then overlays the provided map. */
+    loadBindings(map: ActionMapDefinition): void;
+    /** Configure input groups. Group name -> array of action names. */
+    setGroups(groups: Record<string, string[]>): void;
+    /** Enable a group by name. */
+    enableGroup(name: string): void;
+    /** Disable a group by name. Actions only in disabled groups become inactive. */
+    disableGroup(name: string): void;
+    /** Set exactly these groups as active; all others are disabled. */
+    setActiveGroups(names: string[]): void;
+    /** Whether a group is currently enabled. Returns true for unknown group names. */
+    isGroupEnabled(name: string): boolean;
+    /** Get all configured group names. */
+    getGroups(): string[];
+    /** Get the action names belonging to a group. Returns empty array for unknown groups. */
+    getGroupActions(name: string): readonly string[];
+    /** Returns true if the action is ungrouped or any of its groups is enabled. */
+    private isActionEnabled;
+    /** Returns a promise that resolves with the next key code pressed. Intercepts the key. */
+    listenForNextKey(): Promise<string | null>;
+    /** Cancel an active {@link listenForNextKey}. Resolves the pending promise with `null`. */
+    cancelListen(): void;
+    /** Public wrapper for synthetic key-down injection. Applies sync. */
+    fireKeyDown(code: string): void;
+    /** Public wrapper for synthetic key-up injection. Applies sync. */
+    fireKeyUp(code: string): void;
+    /**
+     * Public wrapper for synthetic pointer movement. Defaults to the primary
+     * mouse pointer (`id: 1`, `type: "mouse"`); pass `opts` to drive a specific
+     * touch / pen pointer.
+     */
+    firePointerMove(screenX: number, screenY: number, opts?: {
+        id?: number;
+        type?: PointerType;
+        isPrimary?: boolean;
+    }): void;
+    /**
+     * Public wrapper for synthetic pointer-button presses. Defaults to button 0
+     * on the primary mouse pointer. Pass `opts` for touch / pen / non-primary
+     * pointers (e.g. `{ id: 5, type: "touch", isPrimary: false }`).
+     */
+    firePointerDown(button?: 0 | 1 | 2, opts?: {
+        id?: number;
+        type?: PointerType;
+        isPrimary?: boolean;
+    }): void;
+    /** Public wrapper for synthetic pointer-button releases. */
+    firePointerUp(button?: 0 | 1 | 2, opts?: {
+        id?: number;
+    }): void;
+    /** Public wrapper for synthetic wheel input. Applies sync, including
+     * action edges and `onWheel` listener notification — matching the DOM path
+     * so tests and inspector probes drive the full surface. */
+    fireWheel(dx: number, dy: number): void;
+    private makeSyntheticInfo;
+    /**
+     * Inject a synthetic gamepad button edge. Routes through the same internal
+     * path as real polling, so action queries (`isPressed`, `isJustPressed`),
+     * `listenForNextKey`, and rebinding all see the synthetic input.
+     *
+     * `code` should be a gamepad code string (e.g. `"GamepadA"`, `"GamepadLT"`).
+     * Used by inspector probes / deterministic tests in lieu of real polling.
+     */
+    fireGamepadButton(code: string, pressed: boolean): void;
+    /**
+     * Inject a synthetic gamepad axis value. Stored separately from real-pad
+     * axis state and consulted by `getStick` / `getTrigger` only when no real
+     * pad is active — matching how a test fixture would use the API.
+     *
+     * Trigger axes additionally emit `GamepadLT`/`GamepadRT` button edges when
+     * crossing `triggerThreshold`, mirroring real-pad polling so synthetic
+     * inspector probes drive `isPressed` the same way as physical hardware.
+     */
+    fireGamepadAxis(side: GamepadAxisKey, value: number): void;
+    /**
+     * Returns the deadzoned, magnitude-clamped stick vector for the given side.
+     *
+     * By default reads from the active pad (the most recently used controller,
+     * or the first connected one if nothing has been used yet). Pass
+     * `{ pad: index }` to read from a specific pad — useful for couch-co-op
+     * where each player's controller is addressed explicitly.
+     *
+     * Falls back to synthetic injection (`fireGamepadAxis`) when no pad is
+     * active — that's the test/probe path.
+     */
+    getStick(side: "left" | "right", opts?: {
+        pad?: number;
+    }): Vec2;
+    /**
+     * Returns the deadzoned trigger value (0..1) for the given side.
+     * Reads from the active pad by default; use `{ pad: index }` for explicit
+     * per-pad reads. Falls back to synthetic state when no pad is active.
+     */
+    getTrigger(side: "left" | "right", opts?: {
+        pad?: number;
+    }): number;
+    /**
+     * Synchronously poll `navigator.getGamepads()` for currently-connected pads.
+     * Use this rather than the cached event-driven list when you need ground
+     * truth — `gamepadconnected` doesn't fire until the user presses a button.
+     */
+    gamepads(): readonly GamepadInfo[];
+    /**
+     * Subscribe to gamepad-connected events. Replays currently-known pads
+     * synchronously so callers don't need a separate `gamepads()` call.
+     * Returns a disposer.
+     */
+    onGamepadConnected(fn: (info: GamepadInfo) => void): () => void;
+    /** Subscribe to gamepad-disconnected events. Returns a disposer. */
+    onGamepadDisconnected(fn: (info: GamepadInfo) => void): () => void;
+    /**
+     * The pad whose analog input is read by default. Auto-promotes on input
+     * activity (button press or stick/trigger above deadzone) and on first
+     * connect. Returns `null` when no pad is connected.
+     */
+    getActivePad(): GamepadInfo | null;
+    /**
+     * Manually set the active pad. Index must match a currently connected pad
+     * — pass an unknown index and the call is a no-op. Pass `null` to clear
+     * (analog reads will fall back to synthetic state if any).
+     */
+    setActivePad(index: number | null): void;
+    /**
+     * Subscribe to active-pad changes. Replays the current active pad
+     * synchronously on subscribe so callers get the present state without a
+     * separate `getActivePad()` call. Returns a disposer.
+     */
+    onActivePadChanged(fn: (info: GamepadInfo | null) => void): () => void;
+    private setActivePadInternal;
+    /** Enable or disable real gamepad polling. Synthetic injection still works when disabled. */
+    setPollingEnabled(enabled: boolean): void;
+    /** Whether real gamepad polling is currently enabled. */
+    isPollingEnabled(): boolean;
+    /**
+     * Update analog deadzones at runtime. Either field may be omitted.
+     * Values are clamped to `[0, 0.999]` — capping below 1 keeps the rescaling
+     * denominator non-zero. Non-finite values are ignored.
+     */
+    setDeadzones(opts: {
+        stick?: number;
+        trigger?: number;
+    }): void;
+    /**
+     * Set the trigger button-edge threshold (default 0.5). Clamped to `[0, 1]`;
+     * non-finite values are ignored.
+     */
+    setTriggerThreshold(value: number): void;
+    /**
+     * @internal Force-release held gamepad buttons and clear real-pad analog
+     * snapshots. Used on tab-hide (where `navigator.getGamepads()` returns
+     * stale data) and on disconnect when polling is paused. Synthetic axes
+     * live in their own field, so they're untouched.
+     */
+    _releaseAllGamepadState(): void;
+    /** @internal Called by InputPlugin from `gamepadconnected` event or by
+     * polling when discovering a previously-unknown pad. Idempotent. */
+    _onGamepadConnected(info: GamepadInfo): void;
+    /** @internal Called by InputPlugin from `gamepaddisconnected` event or by
+     * polling when a pad vanishes silently. Idempotent. */
+    _onGamepadDisconnected(info: GamepadInfo): void;
+    /**
+     * @internal Poll real gamepads via `navigator.getGamepads()` and emit
+     * key-down/key-up edges for any aggregate state changes. Called by
+     * `InputPollSystem` once per frame.
+     */
+    _pollGamepads(): void;
+    /** Whether a pad has any input that should claim active-pad ownership. */
+    private padHasActivity;
+    /**
+     * Aggregate "any pad pressed" per code across the supplied pad list and
+     * emit `_applyKeyDown`/`_applyKeyUp` edges. `lastButtonState` is updated
+     * unconditionally so listen-mode interception doesn't cause held-button
+     * re-fires on subsequent frames.
+     */
+    private reconcileButtonStateAcrossPads;
+    /** Inject a one-frame synthetic action pulse. */
+    fireAction(name: string): void;
+    /** Release all synthetic and physical input state. */
+    clearAll(): void;
+    /**
+     * Drop all tracked pointers and release the aggregate `MouseLeft/Middle/Right`
+     * codes without touching keyboard or gamepad state. Useful for window-blur
+     * / page-hide handling.
+     */
+    clearPointerButtons(): void;
+    /** Snapshot of current held input state for inspector tooling. */
+    snapshotState(): {
+        keys: string[];
+        actions: string[];
+        mouse: {
+            x: number;
+            y: number;
+            buttons: number[];
+            down: boolean;
+        };
+        pointers: Array<{
+            id: number;
+            x: number;
+            y: number;
+            type: PointerType;
+            isPrimary: boolean;
+            buttons: number[];
+            down: boolean;
+        }>;
+        gamepad: {
+            buttons: string[];
+            axes: Array<{
+                key: string;
+                value: number;
+            }>;
+        };
+    };
+    /**
+     * @internal Stash the renderer adapter so the drain step can call its
+     * optional `hitTestUI(x, y)` for the auto-consume fallback. Called by
+     * `InputPlugin.install`.
+     */
+    _setRenderer(renderer: RendererAdapter | null): void;
+    /** @internal */
+    _enqueueKeyDown(code: string): void;
+    /** @internal */
+    _enqueueKeyUp(code: string): void;
+    /**
+     * @internal Sync portion: upsert the pointer entry (existence, screenPos,
+     * type, isPrimary, primaryPointerId) and notify pointerMoveListeners so
+     * pointer-tracking UIs see live cursor positions. Move events do not carry
+     * action-map edges, so they are not queued.
+     */
+    _enqueuePointerMove(info: PointerEventInfo): void;
+    /**
+     * @internal Sync portion: upsert pointer (existence, screenPos, type,
+     * isPrimary, primaryPointerId) and notify pointerDownListeners. Button
+     * mutation, action-map edges, and mouse-aggregate emit are deferred to the
+     * next drain at `Phase.EarlyUpdate` so {@link consumePointer} (or the
+     * renderer's UI hit-test) can suppress them, AND so a same-frame
+     * down+up that arrives before drain still produces the correct
+     * `MouseLeft` press/release edges (recomputing aggregate from live state
+     * after sync mutation would silently drop the transient transition).
+     *
+     * Listeners therefore observe `pointer.buttons` BEFORE this event's edge is
+     * applied. That's a documented tradeoff: the canonical event-button info
+     * is in the `FederatedPointerEvent` / `PointerEvent` the user's Pixi
+     * handler already receives, so the lossy `info.buttons` view rarely
+     * matters in practice.
+     */
+    _enqueuePointerDown(info: PointerEventInfo): void;
+    /** @internal */
+    _enqueuePointerUp(info: PointerEventInfo): void;
+    /** @internal */
+    _enqueuePointerCancel(id: number): void;
+    /** @internal */
+    _enqueueWheel(dx: number, dy: number): void;
+    /**
+     * @internal Drain queued DOM events at `Phase.EarlyUpdate`. Each event
+     * applies its deferred state (button mutations, action-map edges,
+     * mouse-aggregate transitions). Consumed pointers are excluded from the
+     * mouse aggregate so UI-claimed presses do not propagate to gameplay
+     * actions. The renderer's optional `hitTestUI(x, y)` auto-claims a pointer
+     * whose `pointerdown` lands on a UI-marked container.
+     */
+    _drainInputQueue(): void;
+    private drainPointerDown;
+    private drainPointerUp;
+    private drainPointerCancel;
+    private applyWheelEdges;
+    /**
+     * Add a code to `justPressedKeys` without entering `pressedKeys`. Used for
+     * discrete edges (wheel ticks) that are never "held". Listeners and
+     * `listenForNextKey` still fire as usual.
+     */
+    private fireOneFrameEdge;
+    /**
+     * @internal Synthetic key-down. DOM-originated events must use
+     * {@link _enqueueKeyDown} so `consumePointer` and the UI hit-test fallback
+     * have a chance to run before action edges fire.
+     */
+    _applyKeyDown(code: string): void;
+    /**
+     * @internal Synthetic key-up. DOM-originated events must use
+     * {@link _enqueueKeyUp}.
+     */
+    _applyKeyUp(code: string): void;
+    /**
+     * @internal Synthetic pointer move. DOM-originated events must use
+     * {@link _enqueuePointerMove}.
+     */
+    _applyPointerMove(info: PointerEventInfo): void;
+    /**
+     * @internal Synthetic pointer down. DOM-originated events must use
+     * {@link _enqueuePointerDown}. This applies all state (button mutation,
+     * mouse-aggregate emit, listener notify) synchronously.
+     */
+    _applyPointerDown(info: PointerEventInfo): void;
+    /**
+     * @internal Synthetic pointer up. DOM-originated events must use
+     * {@link _enqueuePointerUp}.
+     */
+    _applyPointerUp(info: PointerEventInfo): void;
+    /**
+     * @internal Synthetic pointer cancel. Clears all buttons on the pointer,
+     * fires up-listeners, and drops the entry (unless it's a mouse). Mirrors
+     * the drain-time {@link drainPointerCancel} logic.
+     */
+    _applyPointerCancel(id: number): void;
+    private upsertPointer;
+    private removePointer;
+    /**
+     * Recompute the `MouseLeft/Middle/Right` aggregate edge for `button`.
+     * Consumed pointers are excluded so a UI-claimed press never propagates to
+     * gameplay actions, even if a second non-UI pointer simultaneously holds
+     * the same button.
+     */
+    private recomputeMouseAggregate;
+    private notifyPointerListeners;
+    private notifyKeyListeners;
+    private notifyActionListeners;
+    /**
+     * Action names that include `code` in their bindings AND whose group is
+     * currently enabled. Used for `onAction` / `onActionReleased` listener
+     * fan-out so disabled-group suppression matches `isPressed` behavior.
+     */
+    private actionsForCode;
+    /** @internal Clear per-frame justPressed/justReleased flags. */
+    _clearFrameState(): void;
+    /** Set camera for pointer world-coord conversion. */
+    setCamera(camera: CameraLike): void;
+    /** Clear the camera reference (e.g. on scene exit). */
+    clearCamera(): void;
+    /** Get all configured action names. */
+    getActionNames(): string[];
+    /** @internal Advance the elapsed game-time clock. Called by InputPollSystem. */
+    _advanceTime(dtMs: number): void;
+    /** @internal Sync alias — see {@link _applyKeyDown}. */
+    _onKeyDown(code: string): void;
+    /** @internal Sync alias — see {@link _applyKeyUp}. */
+    _onKeyUp(code: string): void;
+    /** @internal Sync alias — see {@link _applyPointerMove}. */
+    _onPointerMove(info: PointerEventInfo): void;
+    /** @internal Sync alias — see {@link _applyPointerDown}. */
+    _onPointerDown(info: PointerEventInfo): void;
+    /** @internal Sync alias — see {@link _applyPointerUp}. */
+    _onPointerUp(info: PointerEventInfo): void;
+    /** @internal Sync alias — see {@link _applyPointerCancel}. */
+    _onPointerCancel(id: number): void;
+}
+
+/** Service key for the InputManager. */
+declare const InputManagerKey: ServiceKey<InputManager>;
+/** Minimal camera surface needed by InputManager for pointer world-coord conversion. */
+interface CameraLike {
+    screenToWorld(screenX: number, screenY: number): {
+        x: number;
+        y: number;
+    };
+}
+/**
+ * Minimal renderer surface needed by InputPlugin for canvas access and
+ * coordinate mapping. Alias of the cross-package `RendererAdapter` contract.
+ */
+type RendererLike = RendererAdapter;
+/** Configuration for the InputPlugin. */
+interface InputConfig {
+    /** Target element for pointer events (default: canvas from renderer, or document). */
+    target?: HTMLElement;
+    /** Action map: action name -> array of physical key codes. */
+    actions?: ActionMapDefinition;
+    /** Input groups: group name -> array of action names belonging to it. */
+    groups?: Record<string, string[]>;
+    /** Key codes to call preventDefault() on (default: none). */
+    preventDefaultKeys?: string[];
+    /**
+     * Optional override for the renderer service key. When omitted, InputPlugin
+     * auto-resolves `RendererAdapterKey` — the canonical `@yagejs/renderer`
+     * plugin registers itself under that key, so pointer events target its
+     * canvas and coordinates route through `canvasToVirtual` out of the box.
+     * Set this only if you ship a custom renderer registered under a different
+     * key.
+     */
+    rendererKey?: ServiceKey<RendererAdapter>;
+    /** Deadzone thresholds for analog inputs. */
+    deadzones?: {
+        /** Radial deadzone applied to stick magnitude (default 0.15). */
+        stick?: number;
+        /** Lower deadzone for trigger analog values (default 0.05). */
+        trigger?: number;
+    };
+    /**
+     * Trigger value at which `GamepadLT`/`GamepadRT` fire as button edges in the
+     * action map (default 0.5). Below this, the trigger remains "released" for
+     * `isPressed` purposes; the analog `getTrigger` value is unaffected.
+     */
+    triggerThreshold?: number;
+    /**
+     * Whether to poll `navigator.getGamepads()` each frame (default `true`).
+     * Disable to use only synthetic input via `fireGamepadButton`/`fireGamepadAxis`
+     * — useful for inspector probes that want deterministic state.
+     */
+    pollGamepads?: boolean;
+    /**
+     * Invert vertical scroll so positive `dy` means up (default `false`,
+     * matching the W3C convention where positive `deltaY` is "scroll content
+     * down"). Affects both `onWheel` callbacks and `WheelUp/Down` action edges.
+     */
+    wheelInvertY?: boolean;
+    /**
+     * Call `preventDefault()` on incoming wheel events so the page does not
+     * scroll. Default `false` — opt in only if your game canvas should swallow
+     * scroll. The listener is attached as `{ passive: false }` when this is
+     * enabled so `preventDefault()` actually takes effect.
+     */
+    preventDefaultWheel?: boolean;
+}
+/** Information about a connected gamepad. */
+interface GamepadInfo {
+    /** Index in `navigator.getGamepads()`. May change if pads are hot-swapped. */
+    index: number;
+    /** Browser-reported gamepad identifier (vendor + product). */
+    id: string;
+}
+/**
+ * Named gamepad analog axis. Sticks are exposed per axis (`leftX`/`leftY`,
+ * etc.); triggers (`leftTrigger`/`rightTrigger`) carry the W3C
+ * `GamepadButton.value` for buttons 6/7 under standard mapping.
+ */
+type GamepadAxisKey = "leftX" | "leftY" | "rightX" | "rightY" | "leftTrigger" | "rightTrigger";
+/**
+ * Class of physical pointer device. Sourced from `PointerEvent.pointerType` on
+ * real input; defaults to `"mouse"` for synthetic injection.
+ */
+type PointerType = "mouse" | "pen" | "touch";
+/**
+ * Read-only view of a tracked pointer. Returned from {@link InputManager.getPointers}
+ * and the per-pointer event hooks. Treat as immutable — fields reflect the
+ * pointer's state at query time and are not retained between frames.
+ */
+interface PointerInfo {
+    /** Browser-assigned `PointerEvent.pointerId`, or the synthetic id passed via `firePointer*`. */
+    readonly id: number;
+    /** Position in screen-space pixels (already routed through `canvasToVirtual` if available). */
+    readonly screenPos: Vec2;
+    /** Source device class. */
+    readonly type: PointerType;
+    /** Whether the browser flagged this as the primary pointer (`PointerEvent.isPrimary`). */
+    readonly isPrimary: boolean;
+    /** Currently-held button indices (0=left/primary, 1=middle, 2=right). */
+    readonly buttons: ReadonlySet<number>;
+    /** Convenience mirror of `buttons.size > 0`. */
+    readonly isDown: boolean;
+}
+/**
+ * Per-event payload assembled by {@link InputPlugin} from each `PointerEvent`
+ * (or by `firePointer*` for synthetic injection) and forwarded to the manager's
+ * internal pointer handlers.
+ *
+ * @internal
+ */
+interface PointerEventInfo {
+    id: number;
+    screenX: number;
+    screenY: number;
+    type: PointerType;
+    isPrimary: boolean;
+    /**
+     * The button whose state changed for this event. `-1` for events that don't
+     * change button state (move-only). Down/up handlers ignore `-1`.
+     */
+    button: number;
+}
+/** Maps action names to arrays of physical key codes. */
+type ActionMapDefinition = Record<string, string[]>;
+/** How to handle a conflict when rebinding a key already used by another action in the same group. */
+type InputConflictPolicy = "replace" | "keep-both" | "reject";
+/** Options for {@link InputManager.rebind}. */
+interface RebindOptions {
+    /** Index of the binding slot to replace. Appends if the slot does not exist. */
+    slot?: number;
+    /** How to resolve conflicts with other actions in the same group(s). Default: `"reject"`. */
+    conflict?: InputConflictPolicy;
+}
+/** Result of a {@link InputManager.rebind} call. */
+interface RebindResult {
+    /** Whether the rebind succeeded. */
+    ok: boolean;
+    /** Present when `ok` is false due to a conflict with `conflict: "reject"`. */
+    conflict?: {
+        action: string;
+        key: string;
+    };
+}
+
+export { type ActionMapDefinition as A, type CameraLike as C, type GamepadAxisKey as G, type InputConfig as I, type PointerInfo as P, type RebindOptions as R, type GamepadInfo as a, type InputConflictPolicy as b, InputManager as c, InputManagerKey as d, type PointerType as e, type RebindResult as f, type RendererLike as g };