/**
 * Copyright (c) 2026 Dominic Masters
 *
 * This software is released under the MIT License.
 * https://opensource.org/licenses/MIT
 */

/**
 * Opaque type alias for input action identifiers.
 * Use the `INPUT_ACTION_*` constants rather than raw numbers.
 */
type InputAction = number;

/**
 * Polling-based input queries and button rebinding.
 */
interface InputNamespace {
  /**
   * Returns `true` while the given action is held down this frame.
   *
   * @param action - An `INPUT_ACTION_*` constant.
   *
   * @example
   * if (Input.isDown(INPUT_ACTION_UP)) { player.moveUp(); }
   */
  isDown(action: InputAction): boolean;

  /**
   * Returns `true` if the given action was held down in the previous frame.
   *
   * @param action - An `INPUT_ACTION_*` constant.
   */
  wasDown(action: InputAction): boolean;

  /**
   * Returns `true` on the first frame the action transitions from up → down.
   *
   * @param action - An `INPUT_ACTION_*` constant.
   *
   * @example
   * if (Input.pressed(INPUT_ACTION_ACCEPT)) { confirmSelection(); }
   */
  pressed(action: InputAction): boolean;

  /**
   * Returns `true` on the first frame the action transitions from down → up.
   *
   * @param action - An `INPUT_ACTION_*` constant.
   */
  released(action: InputAction): boolean;

  /**
   * Returns the continuous (analog) value of an action in the range `0.0–1.0`.
   * Digital buttons return either `0` or `1`.
   *
   * @param action - An `INPUT_ACTION_*` constant.
   *
   * @example
   * const speed = Input.getValue(INPUT_ACTION_UP) * MAX_SPEED;
   */
  getValue(action: InputAction): number;

  /**
   * Returns a signed axis value in the range `-1.0–1.0`, derived from two
   * opposing actions: `getValue(pos) - getValue(neg)`.
   *
   * @param neg - Action mapped to the negative direction.
   * @param pos - Action mapped to the positive direction.
   *
   * @example
   * const moveX = Input.axis(INPUT_ACTION_LEFT, INPUT_ACTION_RIGHT);
   */
  axis(neg: InputAction, pos: InputAction): number;

  /**
   * Rebinds a physical button (by name) to a logical input action at runtime.
   * Throws if `buttonName` is unknown or `action` is out of range.
   *
   * @param buttonName - Platform-specific button identifier string (e.g. `"A"`, `"START"`).
   * @param action     - Target `INPUT_ACTION_*` constant.
   *
   * @example
   * Input.bind("A", INPUT_ACTION_ACCEPT);
   */
  bind(buttonName: string, action: InputAction): void;
}

/** Polling-based input system. */
declare var Input: InputNamespace;

// ---------------------------------------------------------------------------
// Input action constants.
// Injected as plain global variables by the engine at startup.
// ---------------------------------------------------------------------------

/** Move / navigate upward. */
declare var INPUT_ACTION_UP: InputAction;
/** Move / navigate downward. */
declare var INPUT_ACTION_DOWN: InputAction;
/** Move / navigate left. */
declare var INPUT_ACTION_LEFT: InputAction;
/** Move / navigate right. */
declare var INPUT_ACTION_RIGHT: InputAction;
/** Confirm / accept the current selection. */
declare var INPUT_ACTION_ACCEPT: InputAction;
/** Cancel / go back. */
declare var INPUT_ACTION_CANCEL: InputAction;
/** Emergency quit (e.g. hold-to-exit on embedded platforms). */
declare var INPUT_ACTION_RAGEQUIT: InputAction;
/** Toggle the developer console overlay. */
declare var INPUT_ACTION_CONSOLE: InputAction;
/** Pointer / cursor horizontal position (analog). */
declare var INPUT_ACTION_POINTERX: InputAction;
/** Pointer / cursor vertical position (analog). */
declare var INPUT_ACTION_POINTERY: InputAction;