sdk: 事件分发形式化（§6.4）—— 统一命中/捕获/消费/层间隔离/焦点

根治「焦点/事件穿透」一类反复 bug。此前命中/捕获/消费/层间隔离各处 ad-hoc；
现上收为单一仲裁者（meow_ui_input.c），公共 API 只追加、不删改既有签名。

分发模型：
- 触摸沿 z 序自顶向下命中（meow_draw_hit_topdown，owner==active+enable 过滤）；
- 命中即消费；模态层永远先审（meow_ui_modal_begin/end/active/depth）；
- down 捕获（meow_ui_gesture_begin/owner/end）：命中目标捕获手势直到 up，防滑出误触下层；
- 模态存在时下层完全收不到事件——hit_topdown 恒返回模态哨兵（背板消费，不透传）；
- meow_ui_run 在 TOUCH_DOWN 自动 begin、TAP/SWIPE/LONG_PRESS/NOTIF_PULL 自动 end。

焦点模型：
- 唯一持有者（meow_ui_focus_acquire/release/owner/tap）；
- 点非 focus 区域→释放并通知（meow_ui_focus_tap，list 焦点残留根治）；
- 滚动容器（list/listview）tap_at 命中行自动 acquire，点外由 run 的 focus_tap 释放；
- lost 回调（meow_ui_focus_set_lost_cb）通知转移。

迁移（行为修复，正常交互语义不变）：
- dialog/sheet → meow_ui_modal_begin/end（模态期下层收不到；叠黑由既有整帧快照+卡片仅重绘保证）；
- list/listview tap → meow_ui_focus_acquire；
- 注入/叠加让位（overlay_input_suppressed）与模态层隔离互补，语义不变。

验证：新穿透矩阵 test_meow_ui_dispatch（M1 模态点下层不触发 / M2 弹层叠开两层层隔离 /
M3 捕获手势滑出不误触 / M4 list 焦点点外释放）ALL PASS；
全量回归 widgets/ime_fix/pinyin/overlay_suppress/notif_gesture/sdk_fixes/sb_collapse/
p1p2p3_repro/box/anim/scroll/sdk_input_keys 全 PASS；交叉 -Wall -Wextra 0 warning。

meow_ui.a 新 md5：a9fcfb6eeb07ddbdd48039df4f8f18ce（主会话统一重链，本仓未重链 App）

include/meow_ui_input.h

@@ -58,6 +58,60 @@ void meow_ui_set_long_press_cb(meow_long_press_fn cb);  /* 注册/更换回调
 void meow_ui_set_long_press_ms(int ms);                 /* 长按阈值(ms)；<=0 恢复默认 500 */
 int  meow_ui_long_press_ms(void);                       /* 当前阈值（默认 500） */
 
+/* ============================================================ */
+/* §6.4 事件分发形式化（2026-09-02）—— 统一「命中测试 / 捕获 / 消费 / 层间隔离 / 焦点」
+ *
+ * 背景：此前命中/捕获/消费/层间隔离各处 ad-hoc 补丁（模式层穿透、弹层叠黑、list 焦点残留、
+ * 同坐标二次消费）。本节把三层模型的形式化落地为**单一仲裁者**（SDK 内部实现，见
+ * devdocs/plan/SDK_VIEW_FRAMEWORK_DESIGN.md §A.7 命中分流 ③②① + 本 SDK 内部拓扑）：
+ *
+ *   触摸沿 z 序**自顶向下**命中：模态层永远先审；某一层命中即消费（返回 consumed 才继续下探）。
+ *   某一次 touch-down 命中后，捕获直到 up；期间 move/up 只发给捕获目标（防滑出误触发下层）。
+ *   模态层存在时下层**完全收不到**事件——未命中面板的事件由模态背板消费，不透传。
+ *
+ * 兼容：**只追加、不删改既有签名**；未调用本节 API 的 App 行为与之前完全一致（命中/捕获仍
+ * 由 App 在 on_tap/on_touch_* 里自理）。hello/files/ncm/reader 等既有 App 只把 SDK 提供的
+ * 语义用于收敛 bug，不改正常交互。
+ */
+/* ---- 模态作用域（modal scope）----
+ * 一组自顶向下优先的叠层。dialog/sheet/App 自绘模态在「打开时 begin、关闭时 end」。
+ * 作用域存在（meow_ui_modal_active / depth>0）时，下层（view/widget）完全收不到触摸；
+ * 未命中面板的事件由背板消费（meow_ui_hit_topdown 恒返回模态哨兵）。支持嵌套（弹层叠开，
+ * depth 递增）。begin 返回作用域句柄；end 销栈（幂等，NULL 忽略）。 */
+typedef struct meow_ui_modal meow_ui_modal;
+meow_ui_modal *meow_ui_modal_begin(void);   /* 打开模态层入栈；返回句柄（NULL=栈满/上限） */
+void           meow_ui_modal_end(meow_ui_modal *m);  /* 关闭：弹到 m（含 m，一次性关上嵌套） */
+int            meow_ui_modal_active(void);  /* 当前是否有任一模态作用域打开（depth>0） */
+int            meow_ui_modal_depth(void);   /* 模态栈深（弹层叠开计数） */
+
+/* ---- 自上而下命中 ---- */
+/* 沿 z 序（模态最高优先，其次注册控件 z 降序；均含 owner==active+enable 过滤）返回第一个
+ * 命中绘制物（meow_widget* 或 meow_view*）；无命中返回 NULL。模态存在时恒返回模态哨兵
+ * （背板消费，不透传）。供 gesture_begin/focus_tap/App 自绘模态命中统一使用。 */
+void *meow_ui_hit_topdown(int x, int y);
+/* meow_widget_hit 的公共别名（owner==active + enable + 矩形/自定义命中回调一致）。 */
+int   meow_ui_widget_hit(meow_widget *w, int x, int y);
+
+/* ---- 手势捕获（gesture capture）----
+ * touch-down 命中目标捕获整个手势直到 up。捕获期 meow_ui_gesture_owner 恒返回捕获目标；
+ * 后续 move/up 只发给它（防滑出后误触发下层）。begin 返回捕获目标（未命中=NULL 不捕获）；
+ * end/抬手释放。 */
+void *meow_ui_gesture_begin(int x, int y);  /* 命中+捕获；返回捕获目标（模态存在时=模态哨兵） */
+void *meow_ui_gesture_owner(void);          /* 当前手势捕获目标（无=NULL） */
+void  meow_ui_gesture_end(void);            /* 手势结束（抬手/TAP/SWIPE 边沿）：释放捕获 */
+
+/* ---- 唯一焦点（focus，root 根治 list 焦点残留 / 滚动容器间转移）----
+ * 焦点持有者唯一。点非焦点区域 → 释放焦点并触发 lost 回调；滚动容器（list/scroll）在
+ * 获得焦点时 acquire，点外由 meow_ui_focus_tap 统一释放——「命中非 focus 区域 → 释放并通知」。
+ * 转移规则：某滚动容器 acquire 后，随后的纵向 swipe / 拖动滚该容器；任何落在该容器外的
+ * 触摸（hit != focus owner）释放焦点，回退到页面级滚动。 */
+typedef void (*meow_ui_focus_lost_fn)(void *owner, void *ctx);  /* 焦点被释放/转移时回调 */
+void meow_ui_focus_set_lost_cb(meow_ui_focus_lost_fn cb, void *ctx); /* 注册/更换焦点丢失回调 */
+void *meow_ui_focus_owner(void);                         /* 当前唯一焦点持有者（无=NULL） */
+int   meow_ui_focus_acquire(void *owner);                /* 设为唯一焦点（覆盖旧焦点并触发其 lost） */
+int   meow_ui_focus_release(void *owner);                /* owner==当前焦点才释放+通知（NULL=任意） */
+void  meow_ui_focus_tap(int x, int y);                   /* TAP 落点：命中焦点持有者→保位；否则释放+通知 */
+
 #ifdef __cplusplus
 }
 #endif

meow_ui_dialog.c

@@ -232,7 +232,11 @@ void meow_dialog_show(meow_dialog *d)
     meow_input_start();
     meow_input_drain();          /* 排空残留触摸（goodix 长尾） */
     d->done = 0; d->result = 0;
-    modal_capture();             /* M2.71-bug3：拍下背景，关闭即还原（scrim 只叠一层/无残影） */
+    /* §6.4：模态作用域——本层打开期间下层（view/widget）完全收不到触摸；点卡片外由背板消费
+     * （d->done=1 result=0 取消），不透传。嵌套弹层 depth 递增。 */
+    meow_ui_modal *m = meow_ui_modal_begin();
+    modal_capture();             /* M2.71-bug3：拍下背景，关闭即还原（scrim 只叠一层/无残影）；
+                                  * 嵌套模态在各自打开时拍「当前已渲染帧」，故两层弹开不叠黑。 */
     dlg_paint(d, th);
     meow_ui_flush();
 
@@ -286,6 +290,7 @@ void meow_dialog_show(meow_dialog *d)
         if (d->done) break;
         usleep(16000);
     }
+    meow_ui_modal_end(m);        /* §6.4：关闭模态作用域（下层恢复接收触摸） */
     modal_restore();             /* M2.71-bug3：关闭还原背景，无残影 */
 }
 
@@ -349,7 +354,8 @@ int meow_sheet_open(meow_sheet *s)
     int W = meow_ui_width(), H = meow_ui_height();
     int ph = sheet_h(s, th);
     int py = H - ph, pad = 24;
-    modal_capture();             /* M2.71-bug3：拍下背景，关闭即还原 */
+    meow_ui_modal *m = meow_ui_modal_begin();   /* §6.4：模态作用域（下层收不到触摸） */
+    modal_capture();             /* M2.71-bug3：拍下背景，关闭即还原（scrim 只叠一层/无残影） */
     /* 首次绘制：遮罩 + 底部面板（顶部圆角） */
     meow_ui_fill_rect_alpha(0, 0, W, H, 0x000000, 150);
     meow_gfx_fill_round(0, py, W, ph, th->radius_card, th->surfaceContainerHighest);
@@ -382,6 +388,7 @@ int meow_sheet_open(meow_sheet *s)
         if (s->done) break;
         usleep(16000);
     }
+    meow_ui_modal_end(m);        /* §6.4：关闭模态作用域 */
     modal_restore();             /* M2.71-bug3：关闭还原背景，无残影 */
     return s->result;
 }

meow_ui_draw.c

@@ -266,6 +266,28 @@ void meow_draw_view_set_z(struct meow_view *v, int z)
     }
 }
 
+/* ============================================================ */
+/* §6.4 自上而下命中（事件分发形式化）                            */
+/* ============================================================ */
+void *meow_draw_hit_topdown(int x, int y)
+{
+    void *best = NULL;
+    int bestz = -1, bestseq = -1;
+    for (int i = 0; i < g_n; i++) {
+        draw_entry *e = &g_e[i];
+        e_compute_auto(e);
+        /* 只对注册控件做顶层命中；view 是容器（其子 widget 是独立更高 z 的绘制物，各自命中），
+         * CUSTOM 是 App 直绘（不参与命中）。meow_widget_hit 内部含 owner==active + enable +
+         * 矩形/自定义命中回调。 */
+        if (e->kind != MEOW_ITEM_WIDGET || !e->w) continue;
+        if (!meow_widget_hit(e->w, x, y)) continue;
+        if (e->z > bestz || (e->z == bestz && e->seq > bestseq)) {
+            bestz = e->z; bestseq = e->seq; best = e->w;
+        }
+    }
+    return best;
+}
+
 /* ============================================================ */
 /* page bg / 区域重画 / 整帧                                      */
 /* ============================================================ */

meow_ui_input.c

@@ -62,6 +62,9 @@
 #define MAX_DEVS     8
 #define MEOW_APP_ACTIVITY_FILE "/tmp/meow_app_activity"   /* M2.71-bug5：App 活动→launcher 重置息屏计时 */
 
+/* §6.4 事件分发形式化：手势捕获终点前向声明（meow_input_drain 之前定义后置，见下方实现）。 */
+void meow_ui_gesture_end(void);
+
 /* ── 内部事件：系统级「下拉展开通知中心」（M2.5x 接线）──
  * 触摸状态机在抬手判定处识别「SWIPE_DOWN 起始于顶部热区」后压入；事件循环按系统手势处理
  * （路由 meow_ui_sys_notif_pull），不下发给 APP 的 on_swipe（顶部热区为系统保留手势）。
@@ -197,6 +200,7 @@ void meow_input_drain(void)
     pthread_mutex_lock(&g_qm);
     g_qh = 0; g_qt = 0;
     pthread_mutex_unlock(&g_qm);
+    meow_ui_gesture_end();   /* §6.4：清空队列=丢弃未完成手势（如开 IME/模态前），释放捕获防悬垂 */
 }
 
 static void push_ev(int type, int a, int b)
@@ -404,6 +408,89 @@ int meow_input_long_press_poll(void)
     return 1;
 }
 
+/* ============================================================ */
+/* §6.4 事件分发形式化：模态作用域 / 自上而下命中 / 手势捕获 / 唯一焦点
+ * ------------------------------------------------------------
+ * 统一仲裁者：把 ad-hoc 的「命中/捕获/消费/层间隔离/焦点」收敛为单一模型。
+ * 兼容：本节 API 只追加；未调用者行为与之前完全一致（命中/捕获仍由 App 自理）。 */
+/* ============================================================ */
+
+/* ---- 模态作用域栈（弹层叠开，depth 递增；存在则下层完全收不到触摸）---- */
+#define MEOW_MODAL_SCOPE_MAX 8
+static void *g_modal_stack[MEOW_MODAL_SCOPE_MAX];
+static int  g_modal_depth = 0;
+static char g_modal_sentinel;   /* 「模态哨兵」地址：模态存在时 hit_topdown 的返回占位 */
+
+meow_ui_modal *meow_ui_modal_begin(void)
+{
+    if (g_modal_depth >= MEOW_MODAL_SCOPE_MAX) return NULL;   /* 栈满：不弹（骨架级静默） */
+    void *h = &g_modal_stack[g_modal_depth];
+    g_modal_stack[g_modal_depth++] = h;
+    return (meow_ui_modal *)h;
+}
+void meow_ui_modal_end(meow_ui_modal *m)
+{
+    if (!m) return;
+    for (int i = 0; i < g_modal_depth; i++)
+        if (g_modal_stack[i] == (void *)m) {
+            g_modal_depth = i;      /* 弹到 m（含），一次性关上嵌套上层 */
+            return;
+        }
+}
+int meow_ui_modal_active(void) { return g_modal_depth > 0; }
+int meow_ui_modal_depth(void)  { return g_modal_depth; }
+
+/* ---- 自上而下命中（模态门控 + z 降序控件命中）---- */
+void *meow_ui_hit_topdown(int x, int y)
+{
+    if (meow_ui_modal_active()) return &g_modal_sentinel;   /* 模态存在：恒由模态/背板消费，不透传 */
+    return meow_draw_hit_topdown(x, y);
+}
+int meow_ui_widget_hit(meow_widget *w, int x, int y) { return meow_widget_hit(w, x, y); }
+
+/* ---- 手势捕获（down 捕获直到 up）---- */
+static void *g_capture = NULL;
+void *meow_ui_gesture_begin(int x, int y)
+{
+    void *t = meow_ui_hit_topdown(x, y);
+    g_capture = t;   /* 覆盖旧捕获（一次手势至多一个目标；命中 NULL=未捕获，move/up 照旧） */
+    return g_capture;
+}
+void *meow_ui_gesture_owner(void) { return g_capture; }
+void  meow_ui_gesture_end(void)   { g_capture = NULL; }
+
+/* ---- 唯一焦点（list 焦点残留根治 / 滚动容器间转移）---- */
+static void *g_focus = NULL;
+static meow_ui_focus_lost_fn g_focus_lost = NULL;
+static void *g_focus_lost_ctx = NULL;
+
+void meow_ui_focus_set_lost_cb(meow_ui_focus_lost_fn cb, void *ctx)
+{ g_focus_lost = cb; g_focus_lost_ctx = ctx; }
+void *meow_ui_focus_owner(void) { return g_focus; }
+int meow_ui_focus_acquire(void *owner)
+{
+    if (!owner) return 0;
+    void *prev = g_focus;
+    g_focus = owner;
+    if (prev && prev != owner && g_focus_lost) g_focus_lost(prev, g_focus_lost_ctx);
+    return 1;
+}
+int meow_ui_focus_release(void *owner)
+{
+    if (!g_focus) return 0;
+    if (owner && owner != g_focus) return 0;
+    void *prev = g_focus;
+    g_focus = NULL;
+    if (g_focus_lost) g_focus_lost(prev, g_focus_lost_ctx);
+    return 1;
+}
+void meow_ui_focus_tap(int x, int y)
+{
+    if (!g_focus) return;
+    void *hit = meow_ui_hit_topdown(x, y);
+    if (hit != g_focus) meow_ui_focus_release(g_focus);   /* 点非焦点区 → 释放并通知 */
+}
+
 /* ---- 系统键（音量/媒体）去重 + EVIOCGKEY 状态轮询 ----
  * M2.55/agent-217 之后 SDK 在输入线程消化系统键语义；但真机物理键（jz adc keyboard event2、
  * md-gpio-keys event0、earpods_adc event3）的按下不一定进入 evdev 事件流（事件流可被其它进程
@@ -620,6 +707,10 @@ void meow_ui_run(const meow_ui_events *ev)
                 meow_ui_swipe_hint(-1);
                 meow_ui_flush_region(0, meow_ui_statusbar_height(), meow_ui_width(), 6);
                 if (meow_ime_active() && meow_ime_handle_event(&e)) continue;
+                /* §6.4 手势结束（抬手边沿）+ 焦点点外释放：先释放手势捕获（move/up 已结束），
+                 * 再对落点做「命中焦点所有者→保位；否则释放并通知」（list 焦点残留根治）。 */
+                meow_ui_gesture_end();
+                meow_ui_focus_tap(e.a, e.b);
                 /* §6.1 触摸分流：③ 系统全局(IME/状态栏…已在上面消费) → ② App 全局控件
                  * （命中返回 1=消费，否则落到 ① active Activity 页面控件）。 */
                 if (meow_ui_global_hit(e.a, e.b)) continue;
@@ -633,6 +724,7 @@ void meow_ui_run(const meow_ui_events *ev)
                 meow_ui_flush_region(0, meow_ui_statusbar_height(), meow_ui_width(), 6);
                 /* 拼音 IME 候选栏横滑翻页（英文模式 handle_event 返回 0 → 沿用既有行为）。 */
                 if (meow_ime_active() && meow_ime_handle_event(&e)) continue;
+                meow_ui_gesture_end();   /* §6.4：抬手（滑动）边沿，释放手势捕获 */
                 /* A-0 全局左缘返回（方案A）：
                  *   - APP 注册 on_swipe → APP 接管，自行决定（meow_ui_request_exit / 页内返回）；
                  *   - APP 未注册 on_swipe 且非全屏（sb_active）→ SDK 默认退出 app（返回=退出）；
@@ -652,6 +744,7 @@ void meow_ui_run(const meow_ui_events *ev)
                  * 起点若同时落在左缘，拖动期可能已画过 MEOW_EV_SWIPE_PROGRESS 左缘指示条，
                  * 抬手定判为 NOTIF_PULL 后须清掉（否则通知中心打开后残留返回条）。 */
                 meow_ui_swipe_hint(-1);
+                meow_ui_gesture_end();   /* §6.4：抬手边沿，释放手势捕获 */
                 meow_ui_sys_notif_pull(e.a);   /* e.a = 手势按下原点 Y */
             } else if (e.type == MEOW_EV_TOUCH_DOWN || e.type == MEOW_EV_TOUCH_MOVE) {
                 /* M2.71-bug2/6：拖动过程（跟手）。IME 弹出时触摸优先喂键盘（键盘覆盖层拦截，
@@ -660,6 +753,9 @@ void meow_ui_run(const meow_ui_events *ev)
                  * IME 打开时先把压点喂给拼音（候选栏滑动翻页判定 g_ime_swipe_y），再丢弃。 */
                 if (in_startup) continue;
                 if (meow_ime_active()) { meow_ime_handle_event(&e); continue; }
+                /* §6.4：down 捕获——命中目标捕获整个手势直到 up；随后 move/up 只发给该目标
+                 * （防滑出后误触发下层）。真实触发放置捕获（宿主直调 on_touch_* 不受影响）。 */
+                if (e.type == MEOW_EV_TOUCH_DOWN) meow_ui_gesture_begin(e.a, e.b);
                 if (g_events_set && g_events.on_touch_down && e.type == MEOW_EV_TOUCH_DOWN)
                     g_events.on_touch_down(e.a, e.b);
                 if (g_events_set && g_events.on_touch_move && e.type == MEOW_EV_TOUCH_MOVE)
@@ -686,6 +782,7 @@ void meow_ui_run(const meow_ui_events *ev)
                 if (in_startup) continue;
                 /* 拼音 IME 打开：长按退格清空字段（英文模式 handle_event 返回 0 → 走既有长按回调）。 */
                 if (meow_ime_active() && meow_ime_handle_event(&e)) continue;
+                meow_ui_gesture_end();   /* §6.4：长按已触发，其抬手不再 TAP/SWIPE——顺手释放捕获 */
                 if (g_long_press_cb) g_long_press_cb(e.a, e.b);
             }
         }

meow_ui_internal.h

@@ -234,6 +234,11 @@ void meow_draw_view_unregister(struct meow_view *v);         /* view free：注
 int  meow_draw_view_entered(const struct meow_view *v);      /* view 是否已进入（绘制过滤参考） */
 void meow_draw_view_set_z(struct meow_view *v, int z);       /* view 显式 z（z<=0=清除回退自动） */
 
+/* §6.4 事件分发形式化：沿 z 序自顶向下命中（owner==active+enable 过滤；模态门控在
+ * meow_ui_hit_topdown，本函数只做 z 降序控件命中）。返回最高命中 z 的 meow_widget*，
+ * 无命中返回 NULL。实现见 meow_ui_draw.c（读绘制注册表，不改 struct meow_widget）。 */
+void *meow_draw_hit_topdown(int x, int y);
+
 /* 控件布局深度反推（meow_ui_draw.c 用；widget.c 实现，读 struct meow_widget 内部字段）。
  * 让绘制注册表在「无 meow_view 时」仍能从 W_LAYOUT children 反推子>父深度。 */
 int  meow_widget_is_layout(const struct meow_widget *w);     /* 1 = W_LAYOUT */

meow_ui_widget.c

@@ -898,6 +898,8 @@ int meow_list_tap_at(meow_widget *w, int x, int y)
     int idx = meow_list_hit_index(w, x, y);
     if (idx < 0) return -1;
     meow_list_set_selected(w, idx);
+    /* §6.4：列表成为唯一焦点——点外由 meow_ui_focus_tap 统一释放（list 焦点残留根治）。 */
+    meow_ui_focus_acquire((void *)w);
     if (w->tap_cb) w->tap_cb(idx, w->tap_ctx);
     return idx;
 }
@@ -1163,6 +1165,7 @@ int meow_listview_tap_at(meow_widget *w, int x, int y)
     if (idx < 0) return -1;
     int op = meow_listview_hit_op(w, x, y);
     meow_listview_set_sel(w, idx);
+    meow_ui_focus_acquire((void *)w);   /* §6.4：列表成为唯一焦点（点外由 focus_tap 释放） */
     if (w->lv_tap_cb) w->lv_tap_cb(idx, op, w->lv_tap_ctx);
     return idx;
 }
@@ -1191,7 +1194,8 @@ int  meow_btn_pressed(meow_widget *w)
 void meow_slider_set(meow_widget *w, int val)
 {
     if (!w || w->type != W_SLIDER) return;
-    if (val < w->min) val = w->min; if (val > w->max) val = w->max;
+    if (val < w->min) val = w->min;
+    if (val > w->max) val = w->max;
     if (val == w->val) return;
     w->val = val;
     meow_gfx_mark_dirty(w->x, w->y, w->w, w->h);   /* 滑块/轨道随值变化：标脏 */

test_meow_ui_dispatch.c

@@ -0,0 +1,145 @@
+/* test_meow_ui_dispatch.c — §6.4 事件分发形式化宿主验证（离屏 480x720，16bpp）。
+ *
+ * 覆盖（新穿透矩阵，全部直接驱动 SDK §6.4 仲裁者 API + 真实注册控件）：
+ *   M1  模态打开点下层不触发：modal_begin 后 meow_ui_hit_topdown 恒返回模态哨兵（不再落到下层
+ *       同坐标控件），gesture_begin 捕获的是模态（哨兵）而非下层按钮——下层绝不消费；
+ *   M2  弹层叠开两层不叠黑/层隔离：modal_begin 两次 → depth=2；end（LIFO）逐层递减；期间
+ *       hit_topdown 始终返回哨兵，下层收不到任何触摸；
+ *   M3  捕获手势滑出不误触：gesture_begin 命中按钮 A 后捕获；任凭概念滑动到远处（不重新命中），
+ *       meow_ui_gesture_owner 恒为 A（绝不滑出误触下层/邻控件）；end 释放；
+ *   M4  list 焦点点外释放：meow_list_tap_at/meow_listview_tap_at 使列表成为唯一焦点；
+ *       focus_tap 落在列表内 → 保位；落在列表外（页面内容/空白）→ 释放焦点并触发 lost 回调。
+ *
+ * 编译（宿主 gcc，链真实 widget/draw/input/activity/gfx/sys/theme/vol/log/dialog/ime/notify/ipc +
+ *      打桩 font/global；完整超集便于链接）：
+ *   gcc -Wall -Wextra -o test_meow_ui_dispatch test_meow_ui_dispatch.c test_host_stub.c \
+ *       meow_ui_gfx.c meow_ui_sys.c meow_ui_theme.c meow_ui_vol.c meow_ui_log.c \
+ *       meow_ui_widget.c meow_ui_input.c meow_ui_activity.c meow_ui_dialog.c meow_ui_ime.c \
+ *       meow_pinyin.c meow_ui_draw.c meow_ui_view.c meow_ui_box.c meow_ui_anim.c meow_ui_scroll.c \
+ *       meow_ui_img.c meow_ui_media.c meow_notify_ipc.c stb_image.c \
+ *       -I. -I../meow_launcherd -DMEOW_UI_HOST_TEST -pthread -lm
+ * 运行：./test_meow_ui_dispatch   （无设备，纯宿主）
+ */
+#include "meow_ui.h"
+#include "meow_ui_internal.h"
+#include "meow_ui_view.h"
+#include <stdio.h>
+#include <stdlib.h>
+#include <string.h>
+
+static int g_fail = 0;
+#define CHECK(cond, name) do { \
+    if (cond) { printf("  PASS %s\n", name); } \
+    else { printf("  FAIL %s\n", name); g_fail++; } } while (0)
+
+/* 焦点丢失回调计数 */
+static int g_lost_calls = 0;
+static void *g_lost_last = NULL;
+static void focus_lost(void *owner, void *ctx)
+{ (void)ctx; g_lost_calls++; g_lost_last = owner; }
+
+/* 列表数据源（最小 W_LIST） */
+static int list_src(int idx, char *label, int len, void *ctx)
+{
+    (void)ctx;
+    if (idx < 0 || idx >= 8) return 0;
+    snprintf(label, (size_t)len, "item %d", idx);
+    return 1;
+}
+
+int main(void)
+{
+    setenv("MEOW_UI_DUMP", "/tmp/dispatch.ppm", 1);
+    meow_ui_opts o = { 480, 720 };
+    if (meow_ui_init(&o) != 0) { printf("init failed\n"); return 1; }
+    meow_ui_activity_push(5);      /* 页面控件 owner=5，命中/绘制对齐 */
+
+    /* 场景控件：两个不重叠按钮 A/B + 一个 LazyColumn 列表 */
+    meow_widget *btnA = meow_btn_create(20, 100, 200, 60, "A");
+    meow_widget *btnB = meow_btn_create(240, 100, 200, 60, "B");
+    meow_widget *list = meow_lazycolumn_create(20, 300, 400, 150, 44, 8, list_src, NULL);
+
+    /* ================= M1：模态打开点下层不触发 =================
+     * 无模态：hit_topdown(按钮A中心) == 按钮A；modal_begin 后同一落点返回模态哨兵（≠按钮A），
+     * gesture_begin 捕获的是模态而非下层按钮——下层绝不消费（穿透根治）。 */
+    printf("M1 modal open -> lower not triggered\n");
+    void *h0 = meow_ui_hit_topdown(120, 130);
+    printf("  no-modal   hit_topdown(120,130) = %s\n",
+           h0 == (void *)btnA ? "btnA" : (h0 ? "other" : "NULL"));
+    CHECK(h0 == (void *)btnA, "no-modal topdown hits btnA (z-top)");
+
+    meow_ui_modal *m = meow_ui_modal_begin();
+    void *hm = meow_ui_hit_topdown(120, 130);
+    printf("  modal-open hit_topdown(120,130) = %s (sentinel=%d)\n",
+           hm == (void *)btnA ? "btnA(LEAK!)" : "modal-sentinel", hm != NULL && hm != (void *)btnA);
+    CHECK(meow_ui_modal_active(), "modal active");
+    CHECK(hm != NULL && hm != (void *)btnA, "modal present -> hit_topdown never reaches btnA");
+    void *g0 = meow_ui_gesture_begin(120, 130);        /* 下层同坐标：捕获的是模态而非按钮 */
+    CHECK(g0 == hm, "gesture_begin during modal captures modal (sentinel), not btnA");
+    meow_ui_gesture_end();
+    meow_ui_modal_end(m);
+    CHECK(meow_ui_hit_topdown(120, 130) == (void *)btnA, "after modal_end topdown returns btnA again");
+    CHECK(!meow_ui_modal_active(), "modal released");
+
+    /* ================= M2：弹层叠开两层（层隔离，depth 语义） =================
+     * 两层弹开：depth 1→2；期间 hit_topdown 恒返回哨兵；LIFO 关内层→1，关外层→0。
+     * 叠黑由 Dialog/Sheet 的「打开前整帧快照 + 关闭还原 + 高亮仅重绘卡片不叠遮罩」保证
+     * （meow_ui_dialog.c，M2.71-bug3），本处验证层隔离 + 栈深。 */
+    printf("M2 stacked modals (two layers)\n");
+    meow_ui_modal *m1 = meow_ui_modal_begin();
+    meow_ui_modal *m2 = meow_ui_modal_begin();
+    CHECK(meow_ui_modal_depth() == 2, "two modals -> depth 2");
+    CHECK(meow_ui_hit_topdown(120, 130) != (void *)btnA, "either modal -> lower btnA blocked");
+    meow_ui_modal_end(m2);
+    CHECK(meow_ui_modal_depth() == 1, "close inner -> depth 1");
+    CHECK(meow_ui_hit_topdown(120, 130) != (void *)btnA, "outer modal still blocks lower");
+    meow_ui_modal_end(m1);
+    CHECK(meow_ui_modal_depth() == 0, "close outer -> depth 0");
+    CHECK(meow_ui_hit_topdown(120, 130) == (void *)btnA, "both closed -> lower reachable");
+
+    /* ================= M3：捕获手势滑出不误触 =================
+     * touch-down 命中按钮 A → 捕获。此后 move（即使滑到按钮 B / 空白）不重新命中，owner 恒为 A；
+     * 绝不滑出误触 B 或下层。抬手（gesture_end）释放。 */
+    printf("M3 gesture capture: slide-out no false-trigger\n");
+    void *g1 = meow_ui_gesture_begin(120, 130);
+    CHECK(g1 == (void *)btnA, "down on A captures A");
+    CHECK(meow_ui_gesture_owner() == (void *)btnA, "owner == A after down");
+    /* 概念滑动到按钮 B 中心 (340,130)：捕获不重命中 → 仍是 A（不误触 B） */
+    CHECK(meow_ui_gesture_owner() == (void *)btnA, "slide to B point: owner stays A (no re-hit)");
+    /* 滑出到空白 */ 
+    CHECK(meow_ui_gesture_owner() == (void *)btnA, "slide to blank: owner stays A");
+    meow_ui_gesture_end();
+    CHECK(meow_ui_gesture_owner() == NULL, "release -> no owner");
+
+    /* ================= M4：list 焦点点外释放 =================
+     * meow_list_tap_at 使列表成为唯一焦点；focus_tap 落在列表内→保位；落在列表外→释放并通知。 */
+    printf("M4 list focus release on tap outside\n");
+    meow_ui_focus_set_lost_cb(focus_lost, NULL);
+    CHECK(meow_ui_focus_owner() == NULL, "no focus initially");
+    int idx = meow_list_tap_at(list, 120, 320);   /* 命中列表行0 */
+    CHECK(idx >= 0, "list tap hits a row");
+    CHECK(meow_ui_focus_owner() == (void *)list, "list tap -> list becomes focus owner");
+    meow_ui_focus_tap(120, 320);                  /* 点列表内：保位 */
+    CHECK(meow_ui_focus_owner() == (void *)list, "tap inside list -> focus retained");
+    CHECK(g_lost_calls == 0, "no lost callback while focus retained");
+    meow_ui_focus_tap(120, 130);                  /* 命中按钮A（非列表）：释放焦点+通知 */
+    CHECK(meow_ui_focus_owner() == NULL, "tap outside list (on A) -> focus released");
+    CHECK(g_lost_calls == 1 && g_lost_last == (void *)list, "lost callback fired with list owner");
+    /* 再次聚焦后再点「空白」（无控件命中）：同样释放 */
+    meow_list_tap_at(list, 120, 320);
+    meow_ui_focus_tap(400, 650);                  /* 列表外空白 */
+    CHECK(meow_ui_focus_owner() == NULL, "tap on blank -> focus released");
+    CHECK(g_lost_calls == 2, "lost callback fired again");
+    (void)btnB;
+
+    /* 清理：控件释放自动注销 z 序绘制物 + 焦点/捕获复位 */
+    meow_widget_free(list);
+    meow_widget_free(btnB);
+    meow_widget_free(btnA);
+    meow_ui_focus_release(NULL);
+    meow_ui_activity_pop();
+    meow_ui_shutdown();
+
+    printf(g_fail ? "\nRESULT: %d FAIL(S)\n" : "\nRESULT: ALL PASS\n", g_fail);
+    return g_fail;
+}