@flare-engine/input 0.3.0 → 0.4.0

package/README.md

@@ -1,6 +1,8 @@
 # @flare-engine/input
 
-Pointer / touch / gesture / virtual-control / gamepad / keyboard input. `InputManager` polls per frame; `Pointer` exposes primary touch with `isDown` / `justPressed` / `delta`; `GestureDetector` emits tap / swipe / pinch / long-press; data-only `VirtualJoystick` + `VirtualButton` state (RN components live in `@flare-engine/react`); `GamepadSource` + `RemapTable` cover gamepad polling and persistent rebinds; `createKeyboard` provides buffered `isDown` / `wasPressed` / `wasReleased` edges per `KeyboardEvent.code` with blur-clears-held semantics.
+Pointer / touch / gesture / virtual-control / gamepad / keyboard input. `InputManager` polls per frame; `Pointer` exposes the primary touch (the finger that started the current gesture) with `isDown` / `justPressed` / `delta` — other simultaneous touches reach only `touches[]`, never `pointer`, and when the primary lifts it does not transfer to a remaining finger: `pointer` stays unset until every touch is up and a fresh press starts a new primary; `GestureDetector` emits tap / swipe / pinch / long-press; data-only `VirtualJoystick` + `VirtualButton` state (RN components live in `@flare-engine/react`); `GamepadSource` + `RemapTable` cover gamepad polling and persistent rebinds; `createKeyboard` provides buffered `isDown` / `wasPressed` / `wasReleased` edges per `KeyboardEvent.code` with blur-clears-held semantics.
+
+Per-frame edge flags come in two deliberate shapes: per-thing boolean fields (`Pointer.justPressed/justReleased`, `VirtualButtonState.justPressed/justReleased`, `GamepadButtonState.justPressed/justReleased`) for state you already hold a reference to, and keyed query functions (`KeyboardState.wasPressed/wasReleased(code)`, `wasButtonPressed/wasButtonReleased(state, button)`) for state addressed by an id.
 
 ## Install
 

package/dist/index.d.mts

@@ -41,9 +41,9 @@ interface GamepadButtonState {
   pressed: boolean;
   value: number;
   /** True for exactly one frame after a press. */
-  pressedThisFrame: boolean;
+  justPressed: boolean;
   /** True for exactly one frame after a release. */
-  releasedThisFrame: boolean;
+  justReleased: boolean;
 }
 interface GamepadState {
   connected: boolean;
@@ -68,7 +68,7 @@ interface GamepadSnapshot {
 declare function createGamepadState(index?: number, buttonCount?: number, axisCount?: number): GamepadState;
 /**
  * Apply a fresh snapshot to an existing `GamepadState` in place. Derived
- * `pressedThisFrame` / `releasedThisFrame` flags are recomputed from the
+ * `justPressed` / `justReleased` flags are recomputed from the
  * previous `pressed` value.
  *
  * `deadZone` in [0, 1). Values at or below are treated as 0.
@@ -91,6 +91,11 @@ declare function getAxis(state: GamepadState, axis: number): number;
  * - `createWebGamepadSource()` wraps the W3C `navigator.getGamepads` API.
  * - Native implementations (e.g., `react-native-gamepad`) inject their own
  *   via the `GamepadSource` interface — the package itself ships no native deps.
+ *
+ * **Freshness contract:** each call returns fresh objects. An implementation
+ * must not reuse or mutate a snapshot (or its `buttons`/`axes` arrays) that a
+ * previous `poll()` call returned. A caller may therefore retain a returned
+ * snapshot across frames without it changing out from under them.
  */
 interface GamepadSource {
   poll(): (GamepadSnapshot | null)[];
@@ -159,7 +164,8 @@ declare class GestureDetector {
   private swipeMinDistance;
   private swipeMaxDuration;
   private _startPos;
-  private _startTime;
+  /** Elapsed time (seconds) since `pointerDown` for the in-progress press. */
+  private _elapsed;
   private _isTracking;
   private _longPressFired;
   private _pinchStartDistance;
@@ -167,8 +173,18 @@ declare class GestureDetector {
   constructor(config?: GestureConfig);
   /** Feed a pointer-down event. */
   pointerDown(x: number, y: number): void;
-  /** Feed a pointer-up event. */
-  pointerUp(x: number, y: number, elapsedSinceDown: number): void;
+  /**
+   * Feed a pointer-up event.
+   *
+   * `elapsedSinceDown` is optional: pass it when the host tracks its own
+   * timestamps (e.g. event-driven, no per-frame `update()` calls); omit it
+   * to use the elapsed time already accumulated via `update(dt, ...)`. Either
+   * way there is one clock per press — passing it here re-syncs the same
+   * accumulator `update()` advances, rather than racing it. If a long press
+   * already fired for this press, tap/swipe are suppressed so one press
+   * yields exactly one gesture.
+   */
+  pointerUp(x: number, y: number, elapsedSinceDown?: number): void;
   /**
    * Update gesture tracking. Call each frame with dt.
    * @param dt Delta time in seconds.
@@ -225,8 +241,6 @@ interface KeyboardState {
 }
 /** Create a fresh keyboard state. */
 declare function createKeyboard(): KeyboardState;
-/** Free-function parity with `resetPointerFrame`. Delegates to `kb.reset()`. */
-declare function resetKeyboardFrame(kb: KeyboardState): void;
 /**
  * Web turnkey adapter: registers `keydown`, `keyup`, and `blur` listeners on
  * `target`. `blur` calls `kb.clear()` (stuck-key guard). Returns a detach fn.
@@ -336,13 +350,26 @@ declare function loadRemap(store: RemapStore, key: string): Promise<RemapTable |
  * Feed events from the platform (RN touch/gesture handlers) via the on* methods.
  */
 declare class InputManager {
-  /** Primary pointer (first touch or mouse). */
+  /**
+   * Primary pointer — the touch that started the current gesture (first
+   * `onPointerDown` while no touch was active), or the mouse.
+   *
+   * Once assigned, the primary id stays fixed to that touch until it lifts;
+   * it does NOT transfer to a remaining finger. While a second finger is
+   * down, its events reach only `touches` — `pointer` neither moves nor
+   * releases because of it. When the primary lifts, `pointer.isDown` goes
+   * false even if other fingers remain down, and a new primary is assigned
+   * only once every touch has lifted and a fresh `onPointerDown` arrives.
+   * This keeps `pointer` a single continuous stream with no mid-gesture
+   * teleport; read `touches` for anything beyond one finger.
+   */
   readonly pointer: Pointer;
   /** Buffered keyboard state. Feed via `attachKeyboardListeners` (web) or `keyboard.keyDown`/`keyUp` (mobile/RN). */
   readonly keyboard: KeyboardState;
   /** All active touch points. */
   readonly touches: TouchPoint[];
   private _touchMap;
+  private _primaryTouchId;
   private _gamepads;
   private _gamepadDeadZone;
   private _gamepadRemaps;
@@ -420,5 +447,5 @@ declare function updateJoystick(state: VirtualJoystickState, centerX: number, ce
 /** Reset joystick state when touch is released. */
 declare function releaseJoystick(state: VirtualJoystickState): void;
 //#endregion
-export { type AxisMap, GamepadAxis, type GamepadAxisId, GamepadButton, type GamepadButtonId, type GamepadButtonState, type GamepadSnapshot, type GamepadSource, type GamepadState, type GestureConfig, GestureDetector, InputManager, type KeyBindings, type KeyboardEventLike, type KeyboardEventTargetLike, type KeyboardState, type PinchEvent, type Pointer, type RemapStore, type RemapTable, type SwipeDirection, type SwipeEvent, type TouchPoint, type VirtualButtonState, type VirtualJoystickConfig, type VirtualJoystickState, applyRemap, attachKeyboardListeners, createButtonState, createGamepadState, createIdentityRemap, createJoystickState, createKeyboard, createPointer, createWebGamepadSource, getAxis, isActionDown, isButtonDown, loadRemap, pointerDown, pointerMove, pointerUp, pressButton, releaseButton, releaseJoystick, resetButtonFrame, resetGamepadFrame, resetKeyboardFrame, resetPointerFrame, saveRemap, updateGamepadFromSnapshot, updateJoystick, wasActionPressed, wasActionReleased, wasButtonPressed, wasButtonReleased };
+export { type AxisMap, GamepadAxis, type GamepadAxisId, GamepadButton, type GamepadButtonId, type GamepadButtonState, type GamepadSnapshot, type GamepadSource, type GamepadState, type GestureConfig, GestureDetector, InputManager, type KeyBindings, type KeyboardEventLike, type KeyboardEventTargetLike, type KeyboardState, type PinchEvent, type Pointer, type RemapStore, type RemapTable, type SwipeDirection, type SwipeEvent, type TouchPoint, type VirtualButtonState, type VirtualJoystickConfig, type VirtualJoystickState, applyRemap, attachKeyboardListeners, createButtonState, createGamepadState, createIdentityRemap, createJoystickState, createKeyboard, createPointer, createWebGamepadSource, getAxis, isActionDown, isButtonDown, loadRemap, pointerDown, pointerMove, pointerUp, pressButton, releaseButton, releaseJoystick, resetButtonFrame, resetGamepadFrame, resetPointerFrame, saveRemap, updateGamepadFromSnapshot, updateJoystick, wasActionPressed, wasActionReleased, wasButtonPressed, wasButtonReleased };
 //# sourceMappingURL=index.d.mts.map

package/dist/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","names":[],"sources":["../src/gamepad.ts","../src/gamepad-source.ts","../src/gestures.ts","../src/keyboard.ts","../src/pointer.ts","../src/remap.ts","../src/input-manager.ts","../src/virtual-button.ts","../src/virtual-joystick.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.mts","names":[],"sources":["../src/gamepad.ts","../src/gamepad-source.ts","../src/gestures.ts","../src/keyboard.ts","../src/pointer.ts","../src/remap.ts","../src/input-manager.ts","../src/virtual-button.ts","../src/virtual-joystick.ts"],"mappings":"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"}

package/dist/index.d.ts

@@ -41,9 +41,9 @@ interface GamepadButtonState {
   pressed: boolean;
   value: number;
   /** True for exactly one frame after a press. */
-  pressedThisFrame: boolean;
+  justPressed: boolean;
   /** True for exactly one frame after a release. */
-  releasedThisFrame: boolean;
+  justReleased: boolean;
 }
 interface GamepadState {
   connected: boolean;
@@ -68,7 +68,7 @@ interface GamepadSnapshot {
 declare function createGamepadState(index?: number, buttonCount?: number, axisCount?: number): GamepadState;
 /**
  * Apply a fresh snapshot to an existing `GamepadState` in place. Derived
- * `pressedThisFrame` / `releasedThisFrame` flags are recomputed from the
+ * `justPressed` / `justReleased` flags are recomputed from the
  * previous `pressed` value.
  *
  * `deadZone` in [0, 1). Values at or below are treated as 0.
@@ -91,6 +91,11 @@ declare function getAxis(state: GamepadState, axis: number): number;
  * - `createWebGamepadSource()` wraps the W3C `navigator.getGamepads` API.
  * - Native implementations (e.g., `react-native-gamepad`) inject their own
  *   via the `GamepadSource` interface — the package itself ships no native deps.
+ *
+ * **Freshness contract:** each call returns fresh objects. An implementation
+ * must not reuse or mutate a snapshot (or its `buttons`/`axes` arrays) that a
+ * previous `poll()` call returned. A caller may therefore retain a returned
+ * snapshot across frames without it changing out from under them.
  */
 interface GamepadSource {
   poll(): (GamepadSnapshot | null)[];
@@ -159,7 +164,8 @@ declare class GestureDetector {
   private swipeMinDistance;
   private swipeMaxDuration;
   private _startPos;
-  private _startTime;
+  /** Elapsed time (seconds) since `pointerDown` for the in-progress press. */
+  private _elapsed;
   private _isTracking;
   private _longPressFired;
   private _pinchStartDistance;
@@ -167,8 +173,18 @@ declare class GestureDetector {
   constructor(config?: GestureConfig);
   /** Feed a pointer-down event. */
   pointerDown(x: number, y: number): void;
-  /** Feed a pointer-up event. */
-  pointerUp(x: number, y: number, elapsedSinceDown: number): void;
+  /**
+   * Feed a pointer-up event.
+   *
+   * `elapsedSinceDown` is optional: pass it when the host tracks its own
+   * timestamps (e.g. event-driven, no per-frame `update()` calls); omit it
+   * to use the elapsed time already accumulated via `update(dt, ...)`. Either
+   * way there is one clock per press — passing it here re-syncs the same
+   * accumulator `update()` advances, rather than racing it. If a long press
+   * already fired for this press, tap/swipe are suppressed so one press
+   * yields exactly one gesture.
+   */
+  pointerUp(x: number, y: number, elapsedSinceDown?: number): void;
   /**
    * Update gesture tracking. Call each frame with dt.
    * @param dt Delta time in seconds.
@@ -225,8 +241,6 @@ interface KeyboardState {
 }
 /** Create a fresh keyboard state. */
 declare function createKeyboard(): KeyboardState;
-/** Free-function parity with `resetPointerFrame`. Delegates to `kb.reset()`. */
-declare function resetKeyboardFrame(kb: KeyboardState): void;
 /**
  * Web turnkey adapter: registers `keydown`, `keyup`, and `blur` listeners on
  * `target`. `blur` calls `kb.clear()` (stuck-key guard). Returns a detach fn.
@@ -336,13 +350,26 @@ declare function loadRemap(store: RemapStore, key: string): Promise<RemapTable |
  * Feed events from the platform (RN touch/gesture handlers) via the on* methods.
  */
 declare class InputManager {
-  /** Primary pointer (first touch or mouse). */
+  /**
+   * Primary pointer — the touch that started the current gesture (first
+   * `onPointerDown` while no touch was active), or the mouse.
+   *
+   * Once assigned, the primary id stays fixed to that touch until it lifts;
+   * it does NOT transfer to a remaining finger. While a second finger is
+   * down, its events reach only `touches` — `pointer` neither moves nor
+   * releases because of it. When the primary lifts, `pointer.isDown` goes
+   * false even if other fingers remain down, and a new primary is assigned
+   * only once every touch has lifted and a fresh `onPointerDown` arrives.
+   * This keeps `pointer` a single continuous stream with no mid-gesture
+   * teleport; read `touches` for anything beyond one finger.
+   */
   readonly pointer: Pointer;
   /** Buffered keyboard state. Feed via `attachKeyboardListeners` (web) or `keyboard.keyDown`/`keyUp` (mobile/RN). */
   readonly keyboard: KeyboardState;
   /** All active touch points. */
   readonly touches: TouchPoint[];
   private _touchMap;
+  private _primaryTouchId;
   private _gamepads;
   private _gamepadDeadZone;
   private _gamepadRemaps;
@@ -420,5 +447,5 @@ declare function updateJoystick(state: VirtualJoystickState, centerX: number, ce
 /** Reset joystick state when touch is released. */
 declare function releaseJoystick(state: VirtualJoystickState): void;
 //#endregion
-export { type AxisMap, GamepadAxis, type GamepadAxisId, GamepadButton, type GamepadButtonId, type GamepadButtonState, type GamepadSnapshot, type GamepadSource, type GamepadState, type GestureConfig, GestureDetector, InputManager, type KeyBindings, type KeyboardEventLike, type KeyboardEventTargetLike, type KeyboardState, type PinchEvent, type Pointer, type RemapStore, type RemapTable, type SwipeDirection, type SwipeEvent, type TouchPoint, type VirtualButtonState, type VirtualJoystickConfig, type VirtualJoystickState, applyRemap, attachKeyboardListeners, createButtonState, createGamepadState, createIdentityRemap, createJoystickState, createKeyboard, createPointer, createWebGamepadSource, getAxis, isActionDown, isButtonDown, loadRemap, pointerDown, pointerMove, pointerUp, pressButton, releaseButton, releaseJoystick, resetButtonFrame, resetGamepadFrame, resetKeyboardFrame, resetPointerFrame, saveRemap, updateGamepadFromSnapshot, updateJoystick, wasActionPressed, wasActionReleased, wasButtonPressed, wasButtonReleased };
+export { type AxisMap, GamepadAxis, type GamepadAxisId, GamepadButton, type GamepadButtonId, type GamepadButtonState, type GamepadSnapshot, type GamepadSource, type GamepadState, type GestureConfig, GestureDetector, InputManager, type KeyBindings, type KeyboardEventLike, type KeyboardEventTargetLike, type KeyboardState, type PinchEvent, type Pointer, type RemapStore, type RemapTable, type SwipeDirection, type SwipeEvent, type TouchPoint, type VirtualButtonState, type VirtualJoystickConfig, type VirtualJoystickState, applyRemap, attachKeyboardListeners, createButtonState, createGamepadState, createIdentityRemap, createJoystickState, createKeyboard, createPointer, createWebGamepadSource, getAxis, isActionDown, isButtonDown, loadRemap, pointerDown, pointerMove, pointerUp, pressButton, releaseButton, releaseJoystick, resetButtonFrame, resetGamepadFrame, resetPointerFrame, saveRemap, updateGamepadFromSnapshot, updateJoystick, wasActionPressed, wasActionReleased, wasButtonPressed, wasButtonReleased };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/gamepad.ts","../src/gamepad-source.ts","../src/gestures.ts","../src/keyboard.ts","../src/pointer.ts","../src/remap.ts","../src/input-manager.ts","../src/virtual-button.ts","../src/virtual-joystick.ts"],"mappings":"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"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/gamepad.ts","../src/gamepad-source.ts","../src/gestures.ts","../src/keyboard.ts","../src/pointer.ts","../src/remap.ts","../src/input-manager.ts","../src/virtual-button.ts","../src/virtual-joystick.ts"],"mappings":"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"}

package/dist/index.js

@@ -8,6 +8,16 @@ let _flare_engine_events = require("@flare-engine/events");
 * default. Callers can translate raw indices via `remap.ts` before feeding
 * snapshots into `updateGamepadFromSnapshot`.
 */
+/**
+* Dev-flag access for the dead-zone guard, which runs per axis per frame. Read
+* as a `globalThis` property rather than a bare `__DEV__` identifier for the
+* reason measured in PERF-10 (~0.46 ns vs ~270 ns on JSC).
+*/
+const G$1 = globalThis;
+/** Warn at most once per process; a bad dead zone repeats every frame. */
+let _warnedDeadZone = false;
+/** Largest dead zone that still leaves the rescale well-defined. */
+const MAX_DEAD_ZONE = .99;
 /** W3C Standard Gamepad button indices. */
 const GamepadButton = {
 	A: 0,
@@ -40,8 +50,8 @@ function createGamepadState(index = 0, buttonCount = 17, axisCount = 4) {
 	for (let i = 0; i < buttonCount; i++) buttons[i] = {
 		pressed: false,
 		value: 0,
-		pressedThisFrame: false,
-		releasedThisFrame: false
+		justPressed: false,
+		justReleased: false
 	};
 	return {
 		connected: false,
@@ -53,13 +63,21 @@ function createGamepadState(index = 0, buttonCount = 17, axisCount = 4) {
 	};
 }
 function applyDeadZone(value, deadZone) {
+	let dz = deadZone;
+	if (!(dz >= 0 && dz < 1)) {
+		if (G$1.__DEV__ && !_warnedDeadZone) {
+			_warnedDeadZone = true;
+			console.warn(`[flare-engine/input] deadZone=${deadZone} is outside [0, 1); clamping. Values at or above 1 would suppress the axis entirely.`);
+		}
+		dz = dz >= 1 ? MAX_DEAD_ZONE : 0;
+	}
 	const abs = Math.abs(value);
-	if (abs <= deadZone) return 0;
-	return (value < 0 ? -1 : 1) * ((abs - deadZone) / (1 - deadZone));
+	if (!(abs > dz)) return 0;
+	return (value < 0 ? -1 : 1) * ((abs - dz) / (1 - dz));
 }
 /**
 * Apply a fresh snapshot to an existing `GamepadState` in place. Derived
-* `pressedThisFrame` / `releasedThisFrame` flags are recomputed from the
+* `justPressed` / `justReleased` flags are recomputed from the
 * previous `pressed` value.
 *
 * `deadZone` in [0, 1). Values at or below are treated as 0.
@@ -73,8 +91,8 @@ function updateGamepadFromSnapshot(state, snapshot, deadZone = 0) {
 		for (let i = 0; i < state.buttons.length; i++) {
 			const b = state.buttons[i];
 			if (!b) continue;
-			b.pressedThisFrame = false;
-			b.releasedThisFrame = b.pressed;
+			b.justPressed = false;
+			b.justReleased = b.pressed;
 			b.pressed = false;
 			b.value = 0;
 		}
@@ -93,17 +111,17 @@ function updateGamepadFromSnapshot(state, snapshot, deadZone = 0) {
 		const prev = state.buttons[i];
 		const src = srcButtons[i];
 		if (!prev || !src) continue;
-		const wasPressed = prev.pressed;
+		const wasDown = prev.pressed;
 		prev.pressed = src.pressed;
 		prev.value = src.value;
-		prev.pressedThisFrame = src.pressed && !wasPressed;
-		prev.releasedThisFrame = !src.pressed && wasPressed;
+		prev.justPressed = src.pressed && !wasDown;
+		prev.justReleased = !src.pressed && wasDown;
 	}
 	for (let i = bLen; i < state.buttons.length; i++) {
 		const b = state.buttons[i];
 		if (!b) continue;
-		b.pressedThisFrame = false;
-		b.releasedThisFrame = b.pressed;
+		b.justPressed = false;
+		b.justReleased = b.pressed;
 		b.pressed = false;
 		b.value = 0;
 	}
@@ -119,8 +137,8 @@ function clearFrameFlags(state) {
 	for (let i = 0; i < state.buttons.length; i++) {
 		const b = state.buttons[i];
 		if (!b) continue;
-		b.pressedThisFrame = false;
-		b.releasedThisFrame = false;
+		b.justPressed = false;
+		b.justReleased = false;
 	}
 }
 function anyButtonDown(state) {
@@ -131,10 +149,10 @@ function isButtonDown(state, button) {
 	return state.buttons[button]?.pressed ?? false;
 }
 function wasButtonPressed(state, button) {
-	return state.buttons[button]?.pressedThisFrame ?? false;
+	return state.buttons[button]?.justPressed ?? false;
 }
 function wasButtonReleased(state, button) {
-	return state.buttons[button]?.releasedThisFrame ?? false;
+	return state.buttons[button]?.justReleased ?? false;
 }
 function getAxis(state, axis) {
 	return state.axes[axis] ?? 0;
@@ -206,7 +224,8 @@ var GestureDetector = class {
 		x: 0,
 		y: 0
 	};
-	_startTime = 0;
+	/** Elapsed time (seconds) since `pointerDown` for the in-progress press. */
+	_elapsed = 0;
 	_isTracking = false;
 	_longPressFired = false;
 	_pinchStartDistance = 0;
@@ -224,18 +243,30 @@ var GestureDetector = class {
 			x,
 			y
 		};
-		this._startTime = 0;
+		this._elapsed = 0;
 		this._isTracking = true;
 		this._longPressFired = false;
 	}
-	/** Feed a pointer-up event. */
+	/**
+	* Feed a pointer-up event.
+	*
+	* `elapsedSinceDown` is optional: pass it when the host tracks its own
+	* timestamps (e.g. event-driven, no per-frame `update()` calls); omit it
+	* to use the elapsed time already accumulated via `update(dt, ...)`. Either
+	* way there is one clock per press — passing it here re-syncs the same
+	* accumulator `update()` advances, rather than racing it. If a long press
+	* already fired for this press, tap/swipe are suppressed so one press
+	* yields exactly one gesture.
+	*/
 	pointerUp(x, y, elapsedSinceDown) {
 		if (!this._isTracking) return;
 		this._isTracking = false;
+		if (elapsedSinceDown !== void 0) this._elapsed = elapsedSinceDown;
+		if (this._longPressFired) return;
 		const dx = x - this._startPos.x;
 		const dy = y - this._startPos.y;
 		const dist = Math.sqrt(dx * dx + dy * dy);
-		const duration = elapsedSinceDown;
+		const duration = this._elapsed;
 		if (dist >= this.swipeMinDistance && duration <= this.swipeMaxDuration) {
 			const absDx = Math.abs(dx);
 			const absDy = Math.abs(dy);
@@ -265,8 +296,8 @@ var GestureDetector = class {
 	*/
 	update(dt, currentX, currentY) {
 		if (!this._isTracking) return;
-		this._startTime += dt;
-		if (!this._longPressFired && this._startTime >= this.longPressMinDuration) {
+		this._elapsed += dt;
+		if (!this._longPressFired && this._elapsed >= this.longPressMinDuration) {
 			const dx = currentX - this._startPos.x;
 			const dy = currentY - this._startPos.y;
 			if (Math.sqrt(dx * dx + dy * dy) <= this.tapMaxDistance) {
@@ -383,10 +414,6 @@ function createKeyboard() {
 		}
 	};
 }
-/** Free-function parity with `resetPointerFrame`. Delegates to `kb.reset()`. */
-function resetKeyboardFrame(kb) {
-	kb.reset();
-}
 /**
 * Web turnkey adapter: registers `keydown`, `keyup`, and `blur` listeners on
 * `target`. `blur` calls `kb.clear()` (stuck-key guard). Returns a detach fn.
@@ -581,20 +608,33 @@ function isRemapTable(value) {
 * Feed events from the platform (RN touch/gesture handlers) via the on* methods.
 */
 var InputManager = class {
-	/** Primary pointer (first touch or mouse). */
+	/**
+	* Primary pointer — the touch that started the current gesture (first
+	* `onPointerDown` while no touch was active), or the mouse.
+	*
+	* Once assigned, the primary id stays fixed to that touch until it lifts;
+	* it does NOT transfer to a remaining finger. While a second finger is
+	* down, its events reach only `touches` — `pointer` neither moves nor
+	* releases because of it. When the primary lifts, `pointer.isDown` goes
+	* false even if other fingers remain down, and a new primary is assigned
+	* only once every touch has lifted and a fresh `onPointerDown` arrives.
+	* This keeps `pointer` a single continuous stream with no mid-gesture
+	* teleport; read `touches` for anything beyond one finger.
+	*/
 	pointer = createPointer();
 	/** Buffered keyboard state. Feed via `attachKeyboardListeners` (web) or `keyboard.keyDown`/`keyUp` (mobile/RN). */
 	keyboard = createKeyboard();
 	/** All active touch points. */
 	touches = [];
 	_touchMap = /* @__PURE__ */ new Map();
+	_primaryTouchId = null;
 	_gamepads = [];
 	_gamepadDeadZone = .15;
 	_gamepadRemaps = /* @__PURE__ */ new Map();
 	/** Call once per frame to reset per-frame flags. */
 	update() {
 		resetPointerFrame(this.pointer);
-		resetKeyboardFrame(this.keyboard);
+		this.keyboard.reset();
 		for (let i = 0; i < this._gamepads.length; i++) {
 			const pad = this._gamepads[i];
 			if (pad) resetGamepadFrame(pad);
@@ -602,17 +642,21 @@ var InputManager = class {
 	}
 	/** Feed a touch/pointer begin event. */
 	onPointerDown(id, x, y) {
-		pointerDown(this.pointer, x, y);
+		if (this._touchMap.size === 0) this._primaryTouchId = id;
+		if (id === this._primaryTouchId) pointerDown(this.pointer, x, y);
 		this._addOrUpdateTouch(id, x, y, true);
 	}
 	/** Feed a touch/pointer move event. */
 	onPointerMove(id, x, y) {
-		pointerMove(this.pointer, x, y);
+		if (id === this._primaryTouchId) pointerMove(this.pointer, x, y);
 		this._addOrUpdateTouch(id, x, y, true);
 	}
 	/** Feed a touch/pointer end event. */
 	onPointerUp(id, x, y) {
-		pointerUp(this.pointer, x, y);
+		if (id === this._primaryTouchId) {
+			pointerUp(this.pointer, x, y);
+			this._primaryTouchId = null;
+		}
 		this._removeTouch(id);
 	}
 	/** Access the gamepad state at `index`. Allocates on first access. */
@@ -671,6 +715,16 @@ var InputManager = class {
 };
 //#endregion
 //#region src/virtual-joystick.ts
+/**
+* Dev-flag access for the config guard in `updateJoystick`, which runs once per
+* frame while a stick is held. Read as a `globalThis` property, not as a bare
+* `__DEV__` identifier: on JSC an unresolvable global costs ~270 ns per
+* evaluation where a property miss is inline-cached at ~0.46 ns. Same reasoning
+* as `@flare-engine/core`'s `Pool` — see PERF-10.
+*/
+const G = globalThis;
+/** Warn at most once per process; a bad config repeats every frame. */
+let _warnedConfig = false;
 const DEFAULT_DEAD_ZONE = 10;
 const DEFAULT_MAX_RADIUS = 50;
 /** Create a default joystick state. */
@@ -699,27 +753,36 @@ function createJoystickState() {
 * @param config Joystick configuration.
 */
 function updateJoystick(state, centerX, centerY, touchX, touchY, config) {
-	const deadZone = config?.deadZone ?? DEFAULT_DEAD_ZONE;
-	const maxRadius = config?.maxRadius ?? DEFAULT_MAX_RADIUS;
+	let deadZone = config?.deadZone ?? DEFAULT_DEAD_ZONE;
+	let maxRadius = config?.maxRadius ?? DEFAULT_MAX_RADIUS;
+	if (!(deadZone >= 0 && maxRadius > deadZone)) {
+		if (G.__DEV__ && !_warnedConfig) {
+			_warnedConfig = true;
+			console.warn(`[flare-engine/input] updateJoystick: invalid config (deadZone=${deadZone}, maxRadius=${maxRadius}); expected 0 <= deadZone < maxRadius. Falling back to defaults for this call.`);
+		}
+		if (!(deadZone >= 0)) deadZone = DEFAULT_DEAD_ZONE;
+		if (!(maxRadius > deadZone)) maxRadius = deadZone + DEFAULT_MAX_RADIUS;
+	}
 	const dx = touchX - centerX;
 	const dy = touchY - centerY;
 	const dist = Math.sqrt(dx * dx + dy * dy);
 	state.active = true;
-	if (dist < deadZone) {
+	if (!(dist >= deadZone)) {
 		state.direction.x = 0;
 		state.direction.y = 0;
 		state.magnitude = 0;
-		state.offset.x = dx;
-		state.offset.y = dy;
+		const centred = dist === 0 || !Number.isFinite(dist);
+		state.offset.x = centred ? 0 : dx;
+		state.offset.y = centred ? 0 : dy;
 		return;
 	}
 	const clampedDist = Math.min(dist, maxRadius);
 	const normalizedDist = (clampedDist - deadZone) / (maxRadius - deadZone);
-	const invDist = 1 / dist;
+	const invDist = dist > 0 ? 1 / dist : 0;
 	state.direction.x = dx * invDist;
 	state.direction.y = dy * invDist;
 	state.magnitude = Math.min(normalizedDist, 1);
-	const scale = clampedDist / dist;
+	const scale = dist > 0 ? clampedDist / dist : 0;
 	state.offset.x = dx * scale;
 	state.offset.y = dy * scale;
 }
@@ -758,7 +821,6 @@ exports.releaseButton = releaseButton;
 exports.releaseJoystick = releaseJoystick;
 exports.resetButtonFrame = resetButtonFrame;
 exports.resetGamepadFrame = resetGamepadFrame;
-exports.resetKeyboardFrame = resetKeyboardFrame;
 exports.resetPointerFrame = resetPointerFrame;
 exports.saveRemap = saveRemap;
 exports.updateGamepadFromSnapshot = updateGamepadFromSnapshot;