/* key_router.h — launcher-UI 页物理键统一路由（KEY_ROUTER_UNIFY，P1：音量键）。
 *
 * 设计（devdocs/plan/KEY_ROUTER_UNIFY.md §2.5 方案 C / §3 P1）：
 *   - 进程内**唯一**的 kd_*（防抖态）+ m_prev_*（边沿基线）+ kp_*（事件设备 poll 态），
 *     把「读边沿 + 防抖 + 长按 held + ramp 推进」这层从 5 个会话（run_menu /
 *     run_settings_page / run_notif_center / run_now_playing / meow_subpage_run）
 *     收敛到一处。
 *   - 每个 launcher-UI 页在其 for(;;) 每圈调一次 key_router_pump()，得到「防抖后的
 *     音量边沿 + 原始 held + ramp 状态」；**真正的动作**（音量边沿 →
 *     settings_volume_adj(±step)，还是光标导航）由调用页决定 —— 这样 run_menu 的
 *     meow_mode 分支（HibyOS overlay：音量=导航；MeowOS：音量=调音量）得以保留。
 *   - 非导航页可经 key_router_default_volume()（内含 settings_volume_adj + vol_ramp_tick +
 *     last_input 复位）直接用；run_menu 走自己的 meow_mode 分支。
 *
 * 范围与边界（§3 P1，勿越界）：
 *   - 本模块只收敛**音量键**（KEY_VOLUMEDOWN/KEY_VOLUMEUP）。播放键/电源键 P1 不路由，
 *     维持各页现状（播放键严禁改成 cmd=6；电源键单击/菜单/8s 状态机不动）。
 *   - App 前台 volume_page 武装时（meow_volpage_armed()）音量边沿被抑制（防御闸）。
 *   - 锁屏层（EVIOCGRAB）/App 会话层从不调用 key_router_pump，天然退出本路由。
 */
#ifndef MEOW_KEY_ROUTER_H
#define MEOW_KEY_ROUTER_H

/* 一框音量边沿/held/ramp 输出。P1 只填音量；播放/电源字段后续期（P2/P3）再扩展。
 * 字段语义：
 *   vol_dn_edge / vol_up_edge —— 防抖后**稳定按下边沿**（= stable ∧ ¬上一 stable；
 *       1=本圈新按下）。这是「音量边沿」的唯一权威判定。
 *   vol_held_dn / vol_held_up —— **原始（未防抖）**按住态，ramp 长按 held 用
 *       （松开立即停止，同 run_menu/now_playing 现状）。
 *   vol_st_dn / vol_st_up   —— **防抖稳定**按住态（wake_suppress「全键抬起」判定用）。
 *   ramping                   —— vol_ramp_dir != 0（线性渐变是否在跑；repaint 用）。
 */
typedef struct {
    int vol_dn_edge;
    int vol_up_edge;
    int vol_held_dn;
    int vol_held_up;
    int vol_st_dn;
    int vol_st_up;
    int ramping;
} key_evt_t;

/* 进程级单开 kp_*（事件设备）+ 初始化防抖态/基线（幂等，可安全重复调用）。 */
void key_router_init(void);

/* 每页 for(;;) 每圈调用一次：poll 两设备 → 防抖音量键 → 产边沿/held/ramp。
 * 不做 settings_volume_adj、不驱动 vol_ramp_tick、不复位 last_input —— 皆由调用页决定
 * （见 key_router_default_volume 与各页自己的分支）。 */
key_evt_t key_router_pump(void);

/* 模态/菜单/嵌套会话返回/唤醒后重播基线：kd_* 清零 + m_prev_* 对齐当前 raw
 * （对齐现状各页「memset(kd_*) + kp_poll + m_prev_*=当前 raw」的语义，防假边沿）。
 * 各页在原本做该重播处调用。 */
void key_router_rebase(void);

/* 页进入/退出登记（记录当前哨兵；与 sdk meow_ui_activity_active 交叉校验）。 */
void key_router_page_enter(int sentinel);
void key_router_page_exit(int sentinel);

/* 默认「音量键=调音量」页回调（非导航页直接用）：音量边沿 → settings_volume_adj(±step)；
 * 若有 ramp 在爬 → vol_ramp_tick(held)；边沿 → 复位 *last_input。
 * run_menu 不走本函数（自行 meow_mode 分支）。 */
void key_router_default_volume(const key_evt_t *ev, unsigned long long *last_input);

#endif /* MEOW_KEY_ROUTER_H */