MeowOS-For-R3P2/GESTURE_BACK_DESIGN.md

MeowOS 应用返回手势与物理按键语义 —— 专项方案

状态：设计稿（2026-08-29）。目标：修三件事——① 去掉 APP 内的虚拟返回键（watchdog 顶部 48×48）；② 左滑返回抬手才触发；③ 左滑过程加视觉反馈条（顶部横条，长度=手指距左边缘）。并落实「物理按键语义系统统一管理、APP 禁映射」规范（见 APPS.md §3.4.1）。

---

0. 背景与问题定位

用户实测 SDK 版 hello（B1）反馈 3 个问题：

1. 左上角返回键太丑——由 meow_watchdog 的 paint_button()（meow_watchdog.c）绘制，仅在 非沉浸模式（/tmp/meowapp_state != "1"）时每 100ms 重画。
2. 左滑返回"没松手就触发"——实际看代码，watchdog 手势（handle_touch release edge 判 SWIPE_DX）与 SDK 手势（meow_ui_input.c touch_release 判 SWIPE_THRESH）都是抬手触发。但 hello 的 on_swipe(LEFT)→request_exit() 无条件处理左滑，加上 SDK 的 SWIPE_THRESH=60px 偏小 → 用户在"准备滑动"时 SDK 提前判成 swipe 发出 → 显得没抬手就返回。
3. 左滑无视觉反馈——手势过程中没有任何可视化。

根因链：当前 hello 走「watchdog 非沉浸模式」（画返回键、watchdog 管手势）；但应用现在用 SDK（B1），SDK 有自己的手势。两套手势/返回键并存是乱象来源。正确方向：应用返回/手势统一由 SDK 负责，watchdog 只留安全退出兜底，虚拟返回键删除。

---

1. 核心设计：返回手势统一收到 SDK

明确分工：

组件	职责	改什么
SDK（meow_ui）	APP 内返回手势（左滑）、视觉反馈条、触摸语义事件	手势抬手判定、新增 on_swipe_progress 回调、画顶部反馈条
watchdog（meow_watchdog）	仅安全兜底（卡死强杀）、沉浸前后台切换	删除返回键绘制（或仅保留"无返回键"）；APP 手势不再走 SIGUSR1
launcher	app.json immersive → 写 /tmp/meowapp_state	解析 immersive 字段写入状态文件
hello（示例）	删除 on_key(KEY_POWER)→request_exit()	遵守 §3.4.1：物理键不映射

沉浸模式：APP 声明 immersive:1 → launcher 写 /tmp/meowapp_state=1 → watchdog 不画返回键 → 手势归 SDK。

---

2. 具体改动

2.1 虚拟返回键：删除（watchdog）

• meow_watchdog.c：删除 paint_button() 的调用与返回键绘制逻辑（顶部 48×48 按钮、draw_arrow、按钮区命中逻辑——211-217 行）。
• watchdog 保留：app 卡死兜底强杀（音量减×3 已存在）、app 存活检测（kill(pid,0)）。
• 删除后 watchdog 不再画任何 UI；APP 返回 100% 由 SDK 负责。注意：非沉浸模式下也从"画返回键+SIGTERM"退化为"无按钮"，仅触摸左滑返回（与沉浸统一）。若担心某些 APP 不用 SDK，它们仍走原 SIGUSR1/SIGTERM 兜底，但helloS DK 版走 SDK 手势。

2.2 左滑返回：抬手触发（SDK）

• meow_ui_input.c 的 touch_release()：手势判定逻辑保持抬手触发，但调优阈值与判定：
  • SWIPE_THRESH 从 60 → 80~100（更大容错，防止"摸索滑动"被误判）。
  • 增加方向限定：左滑返回只认「以左边 24px 边缘为起点」（t_dx < 24 且 mdx < -SWIPE_THRESH），避免屏幕任意处左滑都退出。
  • 抬手才 push_ev(MEOW_EV_SWIPE)（已是）；补注释明确"release edge 才触发，按下/移动过程不触发"。
• hello.c：on_swipe(LEFT) 保留 request_exit()（这是 SDK 语义，不违反规范）；但判定由 SDK 收紧（左缘起点+大阈值）。
• 删除 on_key(KEY_POWER)→request_exit()（违反 §3.4.1）：hello 不再因电源键退出；电源键在 APP 内=纯息屏（系统处理）。APP 退出走左滑/SDK 返回。

2.3 视觉反馈条（SDK 新增）

• 新增 SDK API：void (*on_swipe_progress)(int x_start, int dx);（触摸按下后移动过程实时回调，x_start=按下 X，dx=当前相对位移）。
• 输入线程在 BTN_TOUCH 按下后、且 ABS_X 更新时，若满足"t_dx < EDGE_W(24) 且当前 t_cx < t_dx（右滑/左滑方向）"→ 实时 push_ev(MEOW_EV_SWIPE_PROGRESS, t_dx, t_cx)。
• SDK 绘制层新增 meow_ui_swipe_hint(int x)：在屏幕顶部画一个「N 像素高的横条，从最左边缘向内延伸，长度 = 手指当前 X」：
  • 形状：fill_rect(0, 0, x, several_px, accent_color)，高约 4~6px，用主题 accent 色（夜间高对比）。
  • 实时联动：每次 on_swipe_progress 更新画条（flush_region 只刷顶部条区域），抬手达标触发返回时条消失（触发行消失，回到 APP）。
• 视觉约束：条仅"滑动过程中"可见；手指回到原点/抬手未达标 → 条消失。不做复杂动画（CPU 软渲），就是实时长度的横条。

2.4 app.json immersive 传递（launcher）

• launcher 解析 app.json 的 immersive 字段（布尔），应用启动时写 /tmp/meowapp_state = 1/0；退出时清理。
• 当前 launcher 源码 grep immersive 无实现 → 新增。SDK 应用默认声明 immersive:1（hello）。

---

3. 验收（宿主已验证项 + 真机待验证项）

本次为宿主验证（2026-08-29），未重启/刷真机。宿主验证通过项打 ✅；需真机确认的标「待真机」。

已实现（宿主验证 ✅）：SDK meow_ui.a 重编译通过；hello 链 meow_ui.a 重编译通过（MIPS32r2 静态）；launcher 编译+链接通过。 宿主 demo（device_test/gesture_host_test.c）验证：

• ✅ 视觉条：meow_ui_swipe_hint(x) 在屏幕顶部画 5px、从 0 到 x 的 accent 横条；左滑过程 MEOW_EV_SWIPE_PROGRESS 实时上报 → SDK 自动画条（长度=当前 X），抬手达标清条。
• ✅ 抬手才返回：MEOW_EV_SWIPE（release 边沿才 push）才触发 on_swipe(LEFT)；MEOW_EV_SWIPE_PROGRESS 只报进度不触发返回。
• ✅ hello 不再因电源键退出：on_key(KEY_POWER) 不再映射 request_exit()；宿主注入 POWER 键 → 仅 on_key 被调、app 未退出（随后注入左滑才退出）。

待真机确认：

1. 无返回键：SDK hello（app.json immersive:1）左上角不再有 48×48 返回按钮 —— 待真机。
2. 抬手才返回（真机手感）：左縁向内滑 ≥90px、松手后退出 —— 待真机。
3. 视觉条（真机观感）：左滑过程中顶部横条随手指增长、抬手达标消失 —— 待真机。
4. 电源键息屏：SDK hello 内按电源键=息屏（不退出 APP、不触发 OK）；再按=亮屏 —— 待真机。
5. 音量键：SDK hello 内音量键=调音量（不选中/不返回）—— 待真机。
6. 触摸点按钮计数正常（回归）—— 待真机。

⚠️ 实现期定案（与设计稿 §2.2 的偏差，需知悉）

设计稿 §2.2 写「t_dx < 24 且 mdx < -SWIPE_THRESH（左滑）」。该组合物理上不可达：手指若从 ≤24px 的左缘启动，向左最多再走 ~24px 就到 x=0 边缘，位移永远达不到 90px。故实际采用 「左縁起点 + 向右(向内)划 ≥90px」（与 meow_watchdog.c immersive 兜底——左縁 rightward movement >50px——方向一致，二者才判定一致）：

• 事件上报：该左缘返回手势由 SDK 统一报为 MEOW_SWIPE_LEFT（on_swipe 的 dir=LEFT，hello 用 on_swipe(LEFT) 退出；「左滑=返回」契约保持）。
• 进度回调：on_swipe_progress(x_start, dx)，dx = 当前X - 按下X（dx>0=向内划，为返回手势方向）；SDK 自动画条长度=当前 X。
• 屏幕中部左/右滑不是返回手势（中部右滑→MEOW_SWIPE_RIGHT，中部左滑→落 TAP），避免任意处滑动误退出。

若真机实测发现手势方向相反（应为向左划），只需翻转 touch_release() 的 mdx 符号并同步 on_swipe_progress 说明即可，其余逻辑不变。

---

4. 关键约束（代理必读）

• 绝不把 APP 内的物理键（电源/音量/播放）映射成任何"确认/exit/返回/翻页"。物理键语义看 APPS.md §3.4.1：电源=息屏/亮屏、音量=调音量、播放=媒体。只有 MeowOS 界面（launcher 菜单）允许处理物理键语义。
• 渲染走 back_buf + meow_present（SDK 现有机制），无闪烁；视觉条用 fill_rect + flush_region 刷顶部一小条即可，不做全屏重绘。
• 不碰 launcher 主循环的物理键处理（那是 MeowOS 界面，允许）；只改 SDK 的手势 + watchdog 返回键绘制 + launcher 的 app.json immersive 解析。
• meow_watchdog 是独立进程，改它不影响 SDK；但确认删除返回键后它仍能兜底（app 卡死强杀）。

---

5. 涉及文件

文件	改动
patch_v2/sdk/meow_ui_input.c	抬手触发收紧（左缘起点+阈值 80-100）、新增 on_swipe_progress 上报
patch_v2/sdk/meow_ui.h	新增 MEOW_SWIPE_PROGRESS 事件 + on_swipe_progress 回调签名
patch_v2/sdk/meow_ui_gfx.c	新增 meow_ui_swipe_hint(x) 顶部横条绘制
patch_v2/sdk/meow_ui_widget.c（如有输入/绘制分发）	分发 on_swipe_progress
patch_v2/meow_watchdog/meow_watchdog.c	删除 paint_button() 返回键绘制/按钮命中；保留兜底
patch_v2/meow_launcherd/app_launcher.c（meow_write_app_state/launch_app）	解析 app.json immersive → 写 /tmp/meowapp_state
patch_v2/hello_app/hello.c	删 on_key(KEY_POWER)→exit；声明 immersive；处理 on_swipe_progress 画条
patch_v2/apps_assets/apps/os.meow.hello/app.json	加 "immersive":1
APPS.md / MEOW_APP_SDK.md	已写 §3.4.1 规范；SDK 文档补 on_swipe_progress/meow_ui_swipe_hint