feat(sdk): 通用长按事件 (agent-191, 用户定案) — MEOW_EV_LONG_PRESS 坐标式事件+meow_ui_set_long_press_cb/ms(opt-in,默认500ms,移动>12px取消,长按后抬手抑制TAP/SWIPE); 按钮按住视觉阈值同源; files 长按从App层迁入 SDK

meow_ui.a 4335c33a→6de89c27; hello→72fb20da; files→b1c4f58f
宿主 widgets(含6条长按断言)/p1p2p3/ime_fix/test_fsx 全 PASS; 未改 meow_ui_events 结构(防 -Wmissing-field-initializers 破坏既有App)

patch_v2/sdk/meow_ui.h

@@ -173,6 +173,28 @@ void meow_ui_request_exit(void);              /* 请求退出（相当于返回/
  * x<=0 时清掉此前画的条（填回背景色）。不发 flush，由调用方 meow_ui_flush_region 上屏。 */
 void meow_ui_swipe_hint(int x);
 
+/* ============================================================ */
+/* §6.3 通用长按（2026-08-31）                                    */
+/* ============================================================ */
+/* 控件按下 ≥ 阈值（默认 500ms，可配）未抬手、且按下后位移 ≤ 容忍（超移动/抬手取消）
+ * → 触发一次长按回调；坐标 = 触发时刻的按下点（App 据此 meow_widget_hit / meow_listview_hit
+ * 判定命中哪个控件/行，与 on_tap 同一套命中流程）。
+ *
+ * **opt-in**：注册回调（meow_ui_set_long_press_cb）才启用长按判定；未注册时行为与之前完全一致
+ * （按压不触发长按、抬手照常 TAP/SWIPE）——hello 等不使用长按的 App 零回归。
+ *
+ * 与 pressed 状态机共存：按压视觉态（MEOW_WS_PRESSED / 按住加深）不变；短按（未达阈值或
+ * 抬手先于阈值）仍正常触发 on_tap 点击；长按已触发后其抬手**不再产生 TAP/SWIPE**（SDK 抑制
+ * 点击，App 无需自行吞掉后续 tap）。
+ *
+ * 注册经独立 set 接口：**不做进 meow_ui_events**——避免给既有 App（hello/files）按位置初始化
+ * meow_ui_events 的写法在 -Wextra 下引入「缺省成员」告警（_missing-field-initializers），
+ * 保持 SDK 头向后兼容。 */
+typedef void (*meow_long_press_fn)(int x, int y);
+void meow_ui_set_long_press_cb(meow_long_press_fn cb);  /* 注册/更换回调；NULL=取消 */
+void meow_ui_set_long_press_ms(int ms);                 /* 长按阈值(ms)；<=0 恢复默认 500 */
+int  meow_ui_long_press_ms(void);                       /* 当前阈值（默认 500） */
+
 /* ============================================================ */
 /* §6.1 控件生命周期与归属（Activity 栈 + 三层控件模型） [源:2026-08-30] */
 /* ============================================================ */

patch_v2/sdk/meow_ui_input.c

@@ -35,6 +35,8 @@
 
 #define SWIPE_THRESH 65        /* px：抬起位移超过视为滑动（GESTURE_BACK: 90→65，用户实测 90 偏多，65 更顺手） */
 #define EDGE_W       24        /* 左滑返回的「左缘起点」宽度（t_dx < EDGE_W 才认返回手势） */
+#define MEOW_LONG_PRESS_MS   500u   /* §6.3 通用长按默认阈值（ms；meow_ui_set_long_press_ms 可配） */
+#define MEOW_LONG_PRESS_SLOP 12     /* §6.3 按下后「仍算按住」的最大位移（px）；超此取消长按 */
 #define QUEUE_N      128
 #define MAX_DEVS     8
 #define MEOW_APP_ACTIVITY_FILE "/tmp/meow_app_activity"   /* M2.71-bug5：App 活动→launcher 重置息屏计时 */
@@ -129,6 +131,13 @@ static int t_origin_valid = 0;     /* 原点是否已锁定 */
 static uint64_t t_down_ms = 0;     /* 按下时刻（monotonic ms），供实时按住时长用 */
 /* M2.71-bug2/6：拖动过程事件上次上报坐标（坐标变化才入队 MEOW_EV_TOUCH_MOVE，防刷屏）。 */
 static int t_mv_x = -1, t_mv_y = -1;
+/* §6.3 通用长按：本次按压是否已触发过长按（触发后抬手不再产生 TAP/SWIPE）。 */
+static int t_long_fired = 0;
+
+/* §6.3 通用长按：阈值（默认 MEOW_LONG_PRESS_MS；App 可经 meow_ui_set_long_press_ms 配）。 */
+static int g_long_press_ms = MEOW_LONG_PRESS_MS;
+/* §6.3 注册的长按回调（NULL=未注册；触发时以 (x,y) 调用，坐标=触发时刻按下点）。 */
+static meow_long_press_fn g_long_press_cb = NULL;
 
 /* 按下边沿：只标记按下，绝不用传入坐标立即锁原点（避免用上一手势残留坐标当原点）。
  * t_cx/t_cy 归 -1 —— 本次手势以「无坐标」起步，只接受随后到来的有效 ABS。 */
@@ -142,6 +151,7 @@ static void touch_press(int x, int y)
     t_dx = 0; t_dy = 0;
     t_down_ms = now_ms();   /* 记按下时刻：供实时按住时长/按住视觉 */
     t_mv_x = -1; t_mv_y = -1;   /* M2.71：拖动过程起点未定 */
+    t_long_fired = 0;       /* §6.3：每次新按压复位长按触发标记 */
 }
 /* 由 ABS_X/ABS_Y 驱动：若本次按下且原点未锁且坐标有效 → 锁原点；再更新当前坐标。
  * M2.71-bug2/6：原点锁定即报 MEOW_EV_TOUCH_DOWN（拖动起点）；随后坐标变化报 MEOW_EV_TOUCH_MOVE
@@ -165,11 +175,18 @@ static void touch_release(void)
 {
     if (!t_down) return;
     t_down = 0; t_press_valid = 0;
+    int was_long = t_long_fired;   /* §6.3：本次按压是否已触发过长按（抬手不再产生点击/滑动） */
+    t_long_fired = 0;
     /* 本次按下从未锁到有效坐标（幽灵触摸/坐标未就绪）：丢弃，且清空全部轨迹。 */
     if (!t_origin_valid) { t_cx = t_cy = -1; t_dx = t_dy = 0; t_down_ms = 0; t_mv_x = t_mv_y = -1; return; }
     t_origin_valid = 0;
     int mdx = t_cx - t_dx, mdy = t_cy - t_dy;
     int adx = mdx < 0 ? -mdx : mdx, ady = mdy < 0 ? -mdy : mdy;
+    /* 长按已触发：本次手势由长按消费，抬手不再产生 TAP/SWIPE/NOTIF_PULL（抑制点击，§6.3）。 */
+    if (was_long) {
+        t_cx = t_cy = -1; t_dx = t_dy = 0; t_down_ms = 0; t_mv_x = t_mv_y = -1;
+        return;
+    }
     /* 手势判定只在「抬手(release)边沿」做：按下/移动过程不触发 SWIPE，仅报 PROGRESS。
      *
      * 返回手势（"左滑"语义）：原点确实在左缘 + 向右移动 ≥SWIPE_THRESH。设备实际为
@@ -227,17 +244,52 @@ unsigned int meow_input_touch_hold_ms(void)
 void meow_input_touch_set(int down, int x, int y, unsigned hold_ms)
 {
     if (down) {
-        t_down = 1; t_press_valid = 1; t_origin_valid = 1;
+        t_down = 1; t_press_valid = 1; t_origin_valid = 1; t_long_fired = 0;
         t_cx = x; t_cy = y; t_dx = x; t_dy = y;
         uint64_t now = now_ms();
         t_down_ms = (now > (uint64_t)hold_ms) ? (now - (uint64_t)hold_ms) : 0;
     } else {
-        t_down = 0; t_press_valid = 0; t_origin_valid = 0;
+        t_down = 0; t_press_valid = 0; t_origin_valid = 0; t_long_fired = 0;
         t_cx = -1; t_cy = -1; t_dx = 0; t_dy = 0; t_down_ms = 0;
         t_mv_x = -1; t_mv_y = -1;
     }
 }
 
+/* 宿主单测/内部注入：模拟按下后移动到 (x,y)（保原点、更新当前坐标；位移超长按容忍即取消）。
+ * 对应输入线程 touch_update 的位移分支（这里不产生语义事件，仅更新坐标状态）。 */
+void meow_input_touch_move(int x, int y)
+{
+    if (!t_down || !t_origin_valid) return;
+    t_cx = x; t_cy = y;
+    t_mv_x = x; t_mv_y = y;
+}
+
+/* 宿主单测/内部注入：模拟一次抬手（真实 touch_release；含长按后抑制 TAP/SWIPE）。 */
+void meow_input_touch_release(void) { touch_release(); }
+
+/* ---- §6.3 通用长按公共 API + 阈值跨越检测 ----
+ * meow_input_long_press_poll：主循环（meow_ui_run 每帧）与宿主单测调用。读触摸状态机：
+ *   按下、原点/坐标已就绪、未触发过长按、位移 ≤ 容忍、按住时长 ≥ 阈值 → 置 t_long_fired，
+ *   入队 MEOW_EV_LONG_PRESS（a=x,b=y=当前按下点），返回 1；否则返回 0。幂等（一次按压一次）。 */
+void meow_ui_set_long_press_cb(meow_long_press_fn cb) { g_long_press_cb = cb; }
+void meow_ui_set_long_press_ms(int ms)
+{ g_long_press_ms = (ms > 0) ? ms : (int)MEOW_LONG_PRESS_MS; }
+int  meow_ui_long_press_ms(void) { return g_long_press_ms; }
+
+int meow_input_long_press_poll(void)
+{
+    if (!g_long_press_cb) return 0;   /* 未注册回调：长按整体关闭，保持旧点击语义（短按/长按都 TAP） */
+    if (!t_down || t_long_fired || !t_origin_valid || t_cx < 0 || t_cy < 0) return 0;
+    int mdx = t_cx - t_dx, mdy = t_cy - t_dy;
+    int amx = mdx < 0 ? -mdx : mdx, amy = mdy < 0 ? -mdy : mdy;
+    int move = amx > amy ? amx : amy;
+    if (move > MEOW_LONG_PRESS_SLOP) return 0;                         /* 位移超容忍：取消 */
+    if (meow_input_touch_hold_ms() < (unsigned)g_long_press_ms) return 0; /* 未达阈值 */
+    t_long_fired = 1;
+    push_ev(MEOW_EV_LONG_PRESS, t_cx, t_cy);
+    return 1;
+}
+
 /* ---- 输入线程：poll 所有 event 设备 + 解析 ---- */
 static void *input_thread(void *arg)
 {
@@ -338,8 +390,12 @@ void meow_ui_run(const meow_ui_events *ev)
 
     while (!g_exit) {
         /* agent-119：实时触摸按压/按住/释放 → 即时重绘命中按钮区（不等 app 重绘）。
-         * IME 打开时软键盘为覆盖层且拦截触摸，不驱动背后按钮视觉，跳过。 */
-        if (!meow_ime_active()) meow_widget_touch_refresh();
+         * IME 打开时软键盘为覆盖层且拦截触摸，不驱动背后按钮视觉，跳过。
+         * §6.3 通用长按：每帧检测「按下 ≥ 阈值且位移 ≤ 容忍」跨越（IME 打开不驱动；启动窗口不触发）。 */
+        if (!meow_ime_active()) {
+            meow_widget_touch_refresh();
+            if (now_ms() >= startup_cooldown_until) meow_input_long_press_poll();
+        }
 
         meow_input_ev e;
         int got = 0;
@@ -407,6 +463,12 @@ void meow_ui_run(const meow_ui_events *ev)
                 if (g_events_set && g_events.on_swipe_progress)
                     g_events.on_swipe_progress(x0, dx);
                 meow_ui_flush_region(0, meow_ui_statusbar_height(), meow_ui_width(), 6);
+            } else if (e.type == MEOW_EV_LONG_PRESS) {
+                /* §6.3 通用长按：按下 ≥ 阈值未抬手触发。坐标=触发时刻按下点（App 用
+                 * meow_widget_hit/meow_listview_hit 判定命中控件/行）。已注册回调则分发；
+                 * 其抬手已被 touch_release 抑制（不再产生 TAP/SWIPE），此处无需吞后续 tap。 */
+                if (in_startup) continue;
+                if (g_long_press_cb) g_long_press_cb(e.a, e.b);
             }
         }
 

patch_v2/sdk/meow_ui_internal.h

@@ -142,6 +142,7 @@ int  meow_gfx_mfont_ready(void);
 #define MEOW_EV_SWIPE_PROGRESS 4   /* a=按下X(t_dx), b=当前X(t_cx)；dx=b-a（>0=左缘向内划=返回手势） */
 #define MEOW_EV_TOUCH_DOWN     6   /* a=x, b=y：按下后首个有效坐标（拖动起点，M2.71-bug2/6） */
 #define MEOW_EV_TOUCH_MOVE     7   /* a=x, b=y：拖动过程坐标变化（坐标变才入队；跟手用） */
+#define MEOW_EV_LONG_PRESS     8   /* a=x, b=y：按下 ≥ 阈值未抬手（长按触发；其抬手不再产生 TAP/SWIPE） */
 
 typedef struct meow_input_ev {
     uint8_t type;
@@ -175,6 +176,15 @@ unsigned int meow_input_touch_hold_ms(void);           /* 按下已持续毫秒
  * （把按下时刻回拨），便于测按住态；down=0 复位。设备运行时无调用方。 */
 void meow_input_touch_set(int down, int x, int y, unsigned hold_ms);
 
+/* ---- 通用长按（§6.3，2026-08-31）----
+ * 主循环/宿主调用：检测「按下 ≥ 阈值且位移 ≤ 容忍」的跨越；触发则入队 MEOW_EV_LONG_PRESS
+ * 并返回 1（幂等：一次按压只触发一次）。供 meow_ui_run 每帧调用与宿主单测模拟时序。 */
+int  meow_input_long_press_poll(void);
+/* 宿主单测/内部注入：模拟一次抬手（真实 touch_release；含长按后抑制 TAP/SWIPE）。设备运行时无调用方。 */
+void meow_input_touch_release(void);
+/* 宿主单测/内部注入：模拟按下后移动到 (x,y)（保原点、更新当前坐标；位移超长按容忍即取消）。设备运行时无调用方。 */
+void meow_input_touch_move(int x, int y);
+
 /* ---- 控件层实时刷新（meow_ui_widget.c）----
  * 每帧由 meow_ui_run 调用（主线程）：实时触摸按下/释放/按住达阈值时，重绘命中的按钮区
  * 并局部上屏，让按压/按住/释放视觉即时反映，无需 app 在 on_tick/on_tap 重绘（agent-119）。

patch_v2/sdk/meow_ui_widget.c

@@ -23,9 +23,9 @@ enum { W_BTN = 0, W_SLIDER = 1, W_SWITCH = 2, W_LIST = 3,
 /* 容器（TopAppBar 动作 / NavigationBar 项 / TabBar 页签）子项上限。 */
 #define MEOW_CONTAINER_MAX 8
 
-/* 按钮「按住」（长按）判定阈值（ms）：超过即进入更强态（更深状态层）。
- * 视觉区分「短按按下」与「按住」；触发语义不变（on_tap 仍按抬手判定）。 */
-#define MEOW_BTN_HOLD_MS 500u
+/* 按钮「按住」判定阈值：视觉上区分「短按按下」与「按住」（更深状态层）。
+ * 阈值取 meow_ui_long_press_ms()（§6.3 通用长按默认 500ms，App 可配）——与长按事件同源，
+ * 避免「长按已触发但视觉未加深」的不一致。触发语义不变（on_tap 仍按抬手判定）。 */
 
 /* 圆形 ProgressBar 环带厚 / 外扩边距（bgg 修复 M2.71-bug1：控件几何必须覆盖真实像素）。
  * 实际像素范围 = 中心 ± (r + thk/2)；margin = thk/2 + 1 保证外接框覆盖环带外缘与圆帽。 */
@@ -249,7 +249,7 @@ void meow_widget_touch_refresh(void)
     }
     int down = meow_input_touch_down();
     meow_widget *hit = down ? live_btn_hit(meow_input_touch_x(), meow_input_touch_y()) : NULL;
-    int hold = down && hit && meow_input_touch_hold_ms() >= MEOW_BTN_HOLD_MS;
+    int hold = down && hit && meow_input_touch_hold_ms() >= (unsigned)meow_ui_long_press_ms();
 
     if (!down) {
         /* 释放：把最近按压按钮恢复为常态 */
@@ -1218,7 +1218,7 @@ void meow_widget_draw(meow_widget *w)
                    meow_input_touch_x() >= w->x && meow_input_touch_x() < w->x + w->w &&
                    meow_input_touch_y() >= w->y && meow_input_touch_y() < w->y + w->h;
         int press = (w->state & MEOW_WS_PRESSED) || w->pressed || live;
-        int hold  = live && meow_input_touch_hold_ms() >= MEOW_BTN_HOLD_MS;
+        int hold  = live && meow_input_touch_hold_ms() >= (unsigned)meow_ui_long_press_ms();
         if (disabled) press = 0;
         /* §5.8.6 五型：filled=primary/onPrimary；tonal=secondaryContainer/onSecondaryContainer；
          * outlined=透明底+primary 文+outline 描边；text=透明底+primary 文；elevated=surfaceContainerLow+primary 文。

patch_v2/sdk/test_meow_ui_widgets.c

@@ -92,6 +92,9 @@ static void free_all(void)
     g_wn = 0;
 }
 
+/* §6.3 通用长按测试回调（开闸长按判定用；事件本身经 meow_input_pop 断言）。 */
+static void lp_recv(int x, int y) { (void)x; (void)y; }
+
 int main(void)
 {
     setenv("MEOW_UI_DUMP", "/tmp/b2.ppm", 1);
@@ -301,6 +304,63 @@ int main(void)
     meow_sheet_free(sh);
     printf("PASS dialog/sheet: create/set_items/add_item (blocking show skipped)\n");
 
+    /* ---------- §6.3 通用长按：触发/取消/短按不受影响（模拟时序） ----------
+     * 用 meow_input_touch_set（按下+已按住时长回拨）驱动 SDK 触摸状态机，meow_input_long_press_poll
+     * 检测阈值跨越；meow_input_touch_release 走真实 touch_release（含长按后抑制 TAP/SWIPE）。
+     * 断言：① 长按触发（poll=1 + 入队 LONG_PRESS）；② 长按后抬手不再产生 TAP；③ 短按不受影响；
+     * ④ 移动超容忍取消长按；⑤ 阈值可配；⑥ 未注册回调 = 长按关闭（opt-in，hello 等零回归）。 */
+    {
+        meow_input_ev e;
+        meow_input_drain();
+        meow_input_touch_set(0, 0, 0, 0);          /* 复位（清任何残留按住态） */
+        meow_ui_set_long_press_ms(500);            /* 显式回默认，防其它段干扰 */
+
+        /* ⑥ opt-in：未注册回调 → 长按判定关闭：poll=0（即使 hold≥阈值），抬手照常 TAP。 */
+        assert(meow_input_long_press_poll() == 0);
+        meow_input_touch_set(1, 130, 310, 700);
+        assert(meow_input_long_press_poll() == 0);           /* 未注册回调：不触发 */
+        meow_input_touch_release();
+        assert(meow_input_pop(&e) == 1 && e.type == MEOW_EV_TAP);
+        meow_ui_set_long_press_cb(lp_recv);
+
+        /* ① 长按触发：hold=700ms（≥500）→ poll=1，LONG_PRESS 入队且坐标=按下点。 */
+        meow_input_touch_set(1, 120, 300, 700);
+        assert(meow_input_long_press_poll() == 1);
+        assert(meow_input_pop(&e) == 1 && e.type == MEOW_EV_LONG_PRESS && e.a == 120 && e.b == 300);
+
+        /* ② 长按后抬手：点击被抑制（不再产生 TAP）。 */
+        meow_input_touch_release();
+        assert(meow_input_pop(&e) == 0);
+
+        /* ③ 短按不受影响：hold=100ms（<500）→ poll=0（不触发）；抬手 → TAP 正常。 */
+        meow_input_touch_set(1, 200, 400, 100);
+        assert(meow_input_long_press_poll() == 0);
+        meow_input_touch_release();
+        assert(meow_input_pop(&e) == 1 && e.type == MEOW_EV_TAP && e.a == 200 && e.b == 400);
+
+        /* ④ 长按取消（移动超容忍）：hold=700ms 但按下后位移 30px（>12）→ poll=0；抬手仍 TAP
+         *    （位移 < SWIPE_THRESH 65，手势判定为点击）。 */
+        meow_input_touch_set(1, 300, 500, 700);
+        meow_input_touch_move(300 + 30, 500);
+        assert(meow_input_long_press_poll() == 0);
+        meow_input_touch_release();
+        assert(meow_input_pop(&e) == 1 && e.type == MEOW_EV_TAP);
+
+        /* ⑤ 阈值可配：设 200ms → hold=250ms 也触发；恢复默认。 */
+        meow_ui_set_long_press_ms(200);
+        assert(meow_ui_long_press_ms() == 200);
+        meow_input_touch_set(1, 180, 260, 250);
+        assert(meow_input_long_press_poll() == 1);
+        meow_input_touch_release();
+        meow_ui_set_long_press_ms(500);
+        assert(meow_ui_long_press_ms() == 500);
+
+        meow_ui_set_long_press_cb(NULL);           /* 复位，避免影响其它段 */
+        meow_input_touch_set(0, 0, 0, 0);          /* 复位，避免影响后续绘制 */
+        meow_input_drain();
+        printf("PASS long-press: trigger/suppress-tap/short-tap/cancel-move/configurable/opt-in\n");
+    }
+
     /* ---------- 绘制所有控件到 back_buf（5x7 兜底），flush 出屏幕 ---------- */
     const meow_theme *th = meow_theme_get();
     meow_ui_clear(th->bg);