release: bump version to 0.51.0

docs/technical/zh/earth-frontend-context.md

@@ -105,6 +105,18 @@ React 路由入口：
 
 动捕调试面板由 [motion-debug-panel.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-debug-panel.js) 负责。它监听 `earth:motion-debug-frame`，用 canvas 绘制归一化骨架点和连线；Browser Camera provider 会额外通过 `earth:motion-debug-video-source` 提供本机 `<video>` 作为调试预览底图，`shared.motionDebugSkeletonOnly` 可切换为只显示骨骼。`停止匹配动作` 通过 `earth:motion-recognition-pause` 暂停 gesture 执行，但继续显示视频和骨架。未匹配动作为红色，匹配后变绿并显示动作名。设置项持久化在 `planet.earth.settings.v2` 的 `shared.motionDebugEnabled`、`shared.motionProvider` 与 `shared.motionDebugSkeletonOnly`，switch 和输入源控件都预留 `data-gatekeeper-permission="earth.motion_debug"`。
 
+Browser Camera provider 的手势识别管线在 [motion-browser-provider.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/motion-browser-provider.js) 的 `recognizeGesture()`，按以下顺序匹配，前者命中即返回：
+
+1. **`getZoomTrend`（趋势 zoom）**：基于上一帧到当前帧两腕 x 间距的变化量（`Math.abs(rightWrist.x - leftWrist.x)` 的 delta）。两腕都越过噪声地板（`ZOOM_TREND_MIN_WRIST_DELTA = 0.010`）且高度差不超过 `ZOOM_TREND_HEIGHT_TOLERANCE`，spread 增加 → `zoom_in`，spread 减少 → `zoom_out`。趋势优先级最高，避免中间帧被 layer/focus/rotate 抢先误判。
+2. **`getZoomHoldPose`（姿态 zoom）**：动作停止后，只要两腕仍保持在胸口及以上、且 span > `ZOOM_HOLD_SPREAD_FACTOR × shoulderWidth`（默认 1.30）就持续派发 `zoom_in`；两肘明显外展且 span < `ZOOM_HOLD_CLOSE_FACTOR × shoulderWidth`（默认 0.85）就持续派发 `zoom_out`。
+3. **layer / focus**：左手抬起 + 上下移动派发 `layer_prev/next`；头部左右倾斜派发 `focus_prev/next`。
+4. **`getRightArmPattern`（单臂 rotate）**：仅当 `!isZoomCandidatePose(...) && isLeftArmAtRest(...)` 同时成立时才考虑。`isLeftArmAtRest` 要求左腕明显垂在肩下 13% 以下且左肘/左腕都不外伸，把「张臂中间帧」「单手举起」「左手扶在胸前」等所有模糊状态都判为非静止 —— 单臂 rotate 严格要求另一只手处于静止。
+
+两个关键设计：
+
+- **mirror-safe**：所有 zoom 检测都基于 `Math.abs(rightWrist.x - leftWrist.x)`，不依赖单侧 x 方向。无论摄像头是否做镜像翻转（浏览器默认不翻转，`getUserMedia` 返回的就是原始帧），张臂始终 → zoom_in，合手始终 → zoom_out。早期基于「左腕往左 + 右腕往右」的判定会在非镜像视图里把方向判反。
+- **连续 vs 离散**：rotate / layer / focus / confirm 都过 `applyPoseLatch`，同一手势只发一次，必须先回到中性位才能再发（挥一下转一格）。zoom 故意 bypass latch，每帧匹配都返回 → 下游 `GESTURE_POLICIES.zoom_in/out.cooldownMs = 120` 节流到 ~8 次/秒，张臂保持就一直放大直到姿势变化。这是 zoom 跟其它手势在交互语义上的本质区别，不要复用 latch 给 zoom。
+
 [presentation-controller.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/presentation-controller.js) 是新的 Presentation 层。第一阶段只接入 Motion：`motion-cruise-adapter.js` 通过 persistent presentation 复用巡航固定卡片位置和 connector，但不会让鼠标移动触发自动隐藏；connector 每帧重算 source/target anchor，让卡片拖动、地球旋转和目标移动时端点继续跟随。BGP/News 仍保持原有 `CruiseSequencer` 自动轮播路径，避免改变既有巡航体验。
 
 ### 6. 地球与地形
@@ -330,6 +342,10 @@ AISStream 的 `PositionReport` 常带实时位置和 `MetaData.ShipName`，但
 
 详情卡里的坐标候选状态由 [info-card.js](/home/ray/dev/linkong/planet/frontend/public/earth/js/info-card.js) 按 `entityType:entityId` 缓存在模块内存中。用户关闭详情卡或待定位列表后再次打开同一个算力中心 / BGP 观测站，已经采集到的候选和状态文案会恢复；`一键采用` 会优先使用缓存候选，避免重复调用在线地理编码或 LLM factcheck。保存成功后该实体的候选列表会清空为“正在刷新图层”状态，避免旧候选在刷新后继续误导用户。
 
+候选行的 `预览 / 保存` 按钮采用单一的事件委托模型：每个候选根（详情卡里的 `[data-collect-cache-key]` 块，或待定位列表里的 `[data-unresolved-item]`）只挂一个 `click` 监听，由 `data-candidate-actions-bound` 幂等标记，不再混用 `pointerup` / `click` 直绑或重复委托。候选对象不再以 JSON 字符串塞进 HTML 属性后再 `JSON.parse`，按钮只携带 `data-candidate-index`，handler 通过 cache-key 在模块内存的 `Map` 里取出原对象，避开 HTML 实体转义对 `&` / `<` / `"` 的破坏。点击 `预览` 会派发 `earth:preview-location-candidate`，由 `main.js` 的 `previewLocationCandidate()` 调用 `showComputeCenterLocationPreview()`：在候选经纬度上挂双层空心呼吸 sprite（视觉参考 BGP 事件 ring），并把视角聚焦到候选坐标；切换到另一个候选会替换为新呼吸圈，保存时立即清除并由 `spawnSavedComputeCenterLocation()` 即时生成正式算力中心交互图标。注意 `main.js` 没有模块级 `earth` 变量，所有 location-save / preview 处理函数必须先 `const earth = getEarth();`，否则会在事件 handler 里抛 `ReferenceError` 被 `.catch` 静默掉，外观上等同于按钮“没有反应”。
+
+`earth:compute-center-location-saved` 之后的图层校准链路对后台刷新失败保持沉默：`spawnComputeCenterAfterLocationSave()` 已经把 toast 和 locked 状态都给了用户，`refreshComputeCentersAfterLocationSave()` 只在场景就绪时重新拉取后端数据，本身不再吐 `已保存` toast；`handleComputeCenterLocationSaved()` 在 spawn 成功路径让 refresh 静默后台运行，只在 spawn 返回 `null`（场景未就绪）或抛错时才让 refresh 接管成功 toast，refresh 自身报错只走 `console.warn`，绝不冒泡成 `保存失败` 文案——保存请求本身已经成功，刷新失败属于后续同步问题。
+
 asset 图标大小由 `Interactable` 的 `icon.fitSize` 控制。SVG / 图片文件应尽量保持原始 viewBox 和路径，不要为了在地球上显示成 60x60 而手写 `transform`；`drawAssetIcon()` 会把资源等比 contain 到指定尺寸并居中绘制到 atlas canvas。
 
 `Interactable` 默认使用固定屏幕像素尺寸，适合船只、BGP 事件、BGP 观测站、算力中心这类需要稳定识别的图标。如果某类图标需要跟随相机距离缩放，可以把 `sizeMode` 设为非 `"fixed"`，并用 `sizeScale.min / max / referenceFov` 控制缩放范围；单个 marker 的业务尺寸差异可以通过 `getPointSizeMultiplier()` 表达，例如 BGP 事件按严重级别调整点大小，BGP 观测站按活跃度调整点大小。