# Earth Motion Gesture Interaction V2 Plan

**状态**：已实现主体交互，并按实测调整。当前浏览器识别保留右手导航、头部切目标、左手上下切动捕图层、双手张开/收拢缩放；双手上举确认暂时关闭。Motion 目标展示已改为 `CruiseSequencer` + `PresentationController` 的 persistent 展示。

## Summary

把动捕从“几个单点手势触发函数”升级为一套更像大屏遥控器的交互层：右手负责地球导航，头部负责候选切换，左手上下切换动捕候选图层，双手负责缩放，调试面板支持“只显示骨骼”和暂停匹配。进入动捕模式后，Earth 自动软选中屏幕中心附近的正面可交互目标；确认动作预留为把目标升级为锁定，并用巡航/引导线式详情打开，不再模拟鼠标点击。

## Key Changes

- 手势语义 v1 固定为稳健小集：
  - 修正当前左右挥手语义反向问题：手势名以用户感知方向为准，provider 层输出正确 `rotate_left` / `rotate_right`。
  - 右手左/右/上/下挥控制地球水平/垂直旋转，新增 `rotate_up`、`rotate_down`。
  - 双手张开/靠近明确映射为 `zoom_in` / `zoom_out`。
  - 头往左/右歪新增 `focus_prev` / `focus_next`，在当前自动候选目标之间切换。
  - 左手上/下挥新增 `layer_prev` / `layer_next`，切换当前动捕候选图层并聚焦该图层最近目标。
  - 双手确认手势暂时关闭，避免与缩放和站姿误触混淆；协议仍保留 `confirm`。

- Motion Provider / Protocol：
  - 扩展 `MOTION_GESTURES`，新增 `rotate_up`、`rotate_down`、`focus_prev`、`focus_next`、`layer_prev`、`layer_next`。
  - Browser Camera provider 扩展 pose joints，保留肩/肘/腕，增加头部关键点，用于判断头歪。
  - 右手作为导航手；左手独立控制动捕候选图层。
  - 每类手势使用独立阈值和 cooldown，避免缩放/确认/旋转互相误触。

- Earth 交互层：
  - Motion adapter 支持水平/垂直旋转和 focus 切换 callback。
  - 进入动捕模式后，周期性从可交互对象中选出屏幕中心最近、位于地球正面的候选。
  - 软选中目标独立于 `lockedObject`，用 hover/linked 视觉态展示，不立即打开详情。
  - `focus_prev` / `focus_next` 在候选列表中切换；列表按屏幕中心距离、正面可见性、当前图层可见性排序。
  - `confirm` 预留为将软选中目标升级为 locked，并打开引导线详情；若没有候选，显示状态提示。

- 调试面板：
  - 在动捕 HUD / drawer 内增加“只显示骨骼”开关。
  - 增加“停止匹配动作”开关：暂停 gesture 执行，但不关闭摄像头预览或骨架绘制。
  - 设置持久化到 `planet.earth.settings.v2.shared.motionDebugSkeletonOnly`。
  - 开启后 canvas 不绘制视频帧，只绘制深色背景 + 红/绿骨骼线；摄像头仍继续用于识别。

## Test Plan

- Browser provider 单元测试：
  - 右手左/右挥输出的 `rotate_left` / `rotate_right` 与用户语义一致。
  - 右手上/下挥输出 `rotate_up` / `rotate_down`。
  - 双手张开输出 `zoom_in`，双手靠近输出 `zoom_out`。
  - 头部左右倾斜输出 `focus_prev` / `focus_next`。
  - 双手确认动作暂时不会触发。

- Motion adapter 测试：
  - 新增 gesture 能通过 `normalizeGestureMessage`。
  - `rotate_up/down` 调用垂直旋转逻辑。
  - `focus_prev/focus_next` 调用候选切换 callback。
  - `confirm` 在协议层保持兼容；浏览器 provider 当前不主动发出。

- Earth 前端验证：
  - 开启动捕模式后，屏幕中心附近正面目标自动软选中。
  - 头歪能在候选之间切换。
  - 左手上下切换图层后会在新图层中选择最近目标并展示 persistent 引导线详情。
  - 右手上下挥能旋转到南北方向目标。
  - “只显示骨骼”开关持久化，刷新后状态保持。
  - `bun --check` 覆盖新增/修改 Earth JS 模块，现有 motion tests 全绿。

## Assumptions

- v1 采用“右手导航、头部切候选、左手切图层、双手缩放”的交互模型；确认手势保留协议但暂时关闭浏览器识别。
- 自动选中是 soft focus，不覆盖现有 mouse locked selection；只有 `confirm` 才真正锁定目标。
- 骨骼-only 只影响调试画面，不关闭摄像头、不影响识别。
- Motion Agent 协议可以接收新增 gesture 名；旧 agent 只发旧 gesture 时仍兼容。