#ifndef HW_BUTTON_H
#define HW_BUTTON_H

#include <stdint.h>
#include <stdbool.h>

/*
 * hw_button — hardware button debounce + gesture detection (Issue #682).
 *
 * Debounce FSM:
 *   IDLE       → (raw press detected)                   → DEBOUNCING
 *   DEBOUNCING → (still pressed after BTN_DEBOUNCE_MS)  → HELD
 *   HELD       → (released)                             → classify press type, back to IDLE
 *
 * Press types:
 *   SHORT  held < BTN_LONG_MIN_MS from confirmed start
 *   LONG   held >= BTN_LONG_MIN_MS
 *
 * Sequence detection:
 *   [SHORT, SHORT, LONG]  ->  BTN_EVENT_REARM_COMBO  (fires on LONG release)
 *   [SHORT] + BTN_COMMIT_MS quiet timeout  ->  BTN_EVENT_PARK
 *
 * Config constants (can be overridden in config.h):
 *   BTN_DEBOUNCE_MS    20   ms debounce window
 *   BTN_LONG_MIN_MS    1500 ms threshold for LONG press
 *   BTN_COMMIT_MS      500  ms quiet after lone SHORT -> PARK
 *   BTN_SEQ_TIMEOUT_MS 3000 ms sequence window; expired sequence is abandoned
 *   BTN_PORT           GPIOC
 *   BTN_PIN            GPIO_PIN_2
 */

typedef enum {
    BTN_EVENT_NONE        = 0,
    BTN_EVENT_PARK        = 1,   /* single short press + quiet */
    BTN_EVENT_REARM_COMBO = 2,   /* SHORT + SHORT + LONG */
} hw_btn_event_t;

/*
 * hw_button_init() — configure GPIO (active-low pull-up), zero FSM state.
 * Call once at startup.
 */
void hw_button_init(void);

/*
 * hw_button_tick(now_ms) — advance debounce FSM and sequence detector.
 * Call every ms from the main loop.  Returns BTN_EVENT_NONE unless a
 * complete gesture was recognised this tick.
 */
hw_btn_event_t hw_button_tick(uint32_t now_ms);

/*
 * hw_button_is_pressed() — true while button is confirmed held (post-debounce).
 */
bool hw_button_is_pressed(void);

#ifdef TEST_HOST
/* Inject a simulated raw pin state for host-side unit tests. */
void hw_button_inject(bool pressed);
#endif

#endif /* HW_BUTTON_H */