feat: add edutainment drawing and visual package flows

docs/technical/CHILD_MOTION_DEMO_WARMUP_IMPLEMENTATION_SPEC_2026-05-09.md

@@ -170,6 +170,9 @@
 3. 位置类状态必须满足“到达绿色圆环并保持 2 秒”。
 4. 动作类状态没有最长等待时间。
 5. 动作类状态等待 3 秒后可以播放对应引导动画。
+6. 每个步骤进入时需要先展示本步骤文字字幕和语音播报入口，约 1 秒后再进入可交互阶段并展示绿色圆环、手势引导等检测提示。
+7. 步骤完成后需要先进入完成停顿阶段，当前停顿约 0.8 秒；停顿期间保留完成反馈位置，后续可在该阶段补充完成特效或音效，再切换到下一步骤。
+8. 入场等待和完成停顿阶段不消费动作完成判定，避免用户上一步残留动作直接触发下一步。
 
 ### 6.3 开发者调试输入
 
@@ -368,6 +371,17 @@
 
 用户完成挥动左手。
 
+当前本地 mocap 的 handedness 按摄像头视角输出，热身关内需要先换算成用户身体视角再判断：摄像头右侧手对应用户左手。挥动左手不是普通横向轨迹检测，而是用于确认现实环境中用户左侧手臂打开空间足够和安全。
+
+完成条件必须同时满足：
+
+1. 使用用户身体左手轨迹。
+2. 手腕在左肩外侧达到最小外展距离。
+3. 手腕不能处于自然下垂低位。
+4. 最近连续有效帧中，手臂存在足够上下摆动幅度。
+5. 最近连续有效帧中，肩膀到手腕向量的角度变化达到阈值。
+6. 至少出现一次上下摆动方向变化。
+
 #### 完成反馈
 
 ```text
@@ -376,7 +390,7 @@
 
 #### 数据记录
 
-记录用户挥动左手的空间，保存为该用户对应的行为坐标。
+记录用户挥动左手的轨迹、空间包络、角度范围和最大外展距离，保存为该用户对应的行为坐标。
 
 ---
 
@@ -398,6 +412,17 @@
 
 用户完成挥动右手。
 
+当前本地 mocap 的 handedness 按摄像头视角输出，热身关内需要先换算成用户身体视角再判断：摄像头左侧手对应用户右手。挥动右手不是普通横向轨迹检测，而是用于确认现实环境中用户右侧手臂打开空间足够和安全。
+
+完成条件必须同时满足：
+
+1. 使用用户身体右手轨迹。
+2. 手腕在右肩外侧达到最小外展距离。
+3. 手腕不能处于自然下垂低位。
+4. 最近连续有效帧中，手臂存在足够上下摆动幅度。
+5. 最近连续有效帧中，肩膀到手腕向量的角度变化达到阈值。
+6. 至少出现一次上下摆动方向变化。
+
 #### 完成反馈
 
 ```text
@@ -406,7 +431,7 @@
 
 #### 数据记录
 
-记录用户挥动右手的空间，保存为该用户对应的行为坐标。
+记录用户挥动右手的轨迹、空间包络、角度范围和最大外展距离，保存为该用户对应的行为坐标。
 
 ---
 
@@ -653,18 +678,21 @@
 3. 鼠标左键按下并拖动映射左手轨迹。
 4. 鼠标右键按下并拖动映射右手轨迹。
 5. 空格键映射原地跳跃。
+6. 调试输入只在步骤可交互阶段触发步骤完成；步骤入场字幕阶段和完成停顿阶段会忽略完成判定，便于观察节奏和后续补充特效。
 
 当前硬件和动作检测接口接入：
 
 1. 浏览器摄像头视频流已接入舞台背景。
 2. 热身关全流程已通过 `src/services/useMocapInput.ts` 接入本地 mocap WebSocket `/stream`；动作数据源状态优先于浏览器背景摄像头状态展示。
 3. mocap 包支持从 `general.body.center_norm` 读取身体中心，位置类步骤使用该身体中心更新角色剪影横向位置并完成圆环保持检测。
-4. mocap 包支持从 `actions/action/gesture/gestures/event/name/type` 读取动作名，并支持 `hands[]`、`leftHand/rightHand`、`left_hand/right_hand` 读取左右手坐标。
-5. `hands[].landmarks` 存在时优先用手腕和 MCP 点计算掌心中心；掌心点不足时退回 wrist landmark，再退回 hand 直出坐标。
-6. `wave_greeting` 可由 `wave/wave_greeting/hand_wave/open_palm` 等动作或 open palm 手势完成。
-7. `wave_left_hand` 和 `wave_right_hand` 优先消费对应左右手动作名；当硬件只持续输出手部坐标时，也可以根据连续手部横向轨迹完成挥手检测。
-8. `jump_once` 消费 `jump/jump_once/hop` 等跳跃动作事件完成。
-9. 键盘 `A/D/Space` 与鼠标左右键拖拽仍保留为本地 Demo 调试兜底，不代表正式硬件口径。
+4. 身体中心横向坐标进入角色剪影前必须做输入稳定化处理：先 clamp 到 `0..1`，再使用小幅死区、低通阻尼和单包最大步长限制，避免硬件噪声造成角色左右误判、画面抽搐或视觉上的忽大忽小。当前实现参数为死区 `0.012`、阻尼系数 `0.28`、单包最大步长 `0.035`；位置保持检测使用稳定化后的角色坐标。
+5. 角色剪影渲染需要把水平位移和跳跃表现拆开：外层只负责横向定位，内层资源只负责轮廓图和跳跃位移，避免 `left` 与 `transform` 同时抢占导致半透明资源重采样抖动。
+6. mocap 包支持从 `actions/action/gesture/gestures/event/name/type` 读取动作名，并支持 `hands[]`、`leftHand/rightHand`、`left_hand/right_hand` 读取左右手坐标。
+7. `hands[].landmarks` 存在时优先用手腕和 MCP 点计算掌心中心；掌心点不足时退回 wrist landmark，再退回 hand 直出坐标。
+8. `wave_greeting` 只消费左手、右手或未知单手的连续横向挥手轨迹，不再使用 `wave`、`hand_wave`、`open_palm`、张手状态或动作名直接完成判定；进入轨迹判定前必须先满足抬手有效区：优先使用 `hands[].landmarks.wrist` 与 `general.limb_nodes` 的同侧 `*_elbow` / `*_shoulder` 判断，当前阈值为 `wrist.y <= elbow.y + 0.04`，缺少肘部时使用 `wrist.y <= shoulder.y + 0.08`；缺少同侧肘部和肩膀参考时不允许招呼通过，不再使用身体中心兜底判断抬手。轨迹阈值为至少 5 个连续抬手点，横向 `x` 范围差值不小于 `0.075`，且至少出现 1 次横向方向变化，避免“手刚露出画面”或“手自然下垂抖动”被误判为招手。
+9. `wave_left_hand` 和 `wave_right_hand` 只消费用户身体侧对应手的连续坐标轨迹，不再使用动作名、张手状态或 primary hand 兜底完成判定；本地 mocap handedness 当前按摄像头视角输出，因此用户左手使用 camera-right，用户右手使用 camera-left。完成判定必须同时满足对应肩肘腕外展、手腕非自然下垂、连续有效帧、横向范围、上下摆动范围、肩腕角度范围和上下方向变化，当前阈值为连续外展点不少于 5 个、横向 `x` 范围不小于 `0.055`、垂直 `y` 范围不小于 `0.08`、肩腕角度范围不小于 `28°`、外展距离不小于 `0.12`、手腕相对肩膀外侧距离不小于 `0.1`；后续以真实体验结果继续调参。
+10. `jump_once` 消费 `jump/jump_once/hop` 等跳跃动作事件完成。
+11. 键盘 `A/D/Space` 与鼠标左右键拖拽仍保留为本地 Demo 调试兜底，不代表正式硬件口径。
 
 当前未接入但已保留边界：
 
@@ -682,14 +710,17 @@
 5. 当前已生成并接入以下正式 Demo 资源：
    - `public/child-motion-demo/picture-book-grass-stage.png`：默认草地舞台背景。
    - `public/child-motion-demo/picture-book-foreground-grass-v2.png`：底部前景草坪条，只覆盖舞台下沿，不作为整块地板拉伸。
-   - `public/child-motion-demo/picture-book-ground-ring-v2.png`：已按透视绘制的地面椭圆指示环，CSS 只等比缩放。
+   - `public/child-motion-demo/picture-book-ground-ring-v3.png`：已按透视绘制的浅蓝与暖黄色地面椭圆指示环，和草地材质做明显区分，CSS 只等比缩放。
    - `public/child-motion-demo/picture-book-character-outline-v2.png`：半透明用户角色轮廓，使用独立去背后处理避免内部填充被误删。
    - `public/child-motion-demo/picture-book-hud-strip-v2.png`：顶部 HUD 细长软纸条。
    - `public/child-motion-demo/picture-book-calibration-strip-v2.png`：右下角五格热身状态条。
    - `public/child-motion-demo/picture-book-start-panel-v2.png`：开始按钮背后的轻盈托盘。
    - `public/child-motion-demo/picture-book-ui-button-v2.png`：开始按钮绘本风按钮底图。
+   - `public/child-motion-demo/picture-book-wave-cat-body-guide-v6.png`：招手阶段中央猫咪身体底座资源，按可动纸偶结构只包含猫头、短身体和肩部连接点，不再和旧猫头、胸口或猫爪资源叠加。
+   - `public/child-motion-demo/picture-book-wave-cat-arm-guide-v6.png`：招手阶段左右独立手臂资源，也用于左右手阶段单手提示；网页用同一拆件镜像复用，并围绕肩部挂点做挥手摆动动画。
 6. v2 资源按最终用途拆分，CSS 必须按资源原始比例、`aspect-ratio` 或 `background-size: contain / auto` 等方式等比使用；禁止把方形面板强行拉伸为 HUD、状态条或地板，也禁止把底部草坪扩展成覆盖角色脚下的大色块。
-7. 若后续补充或重绘资源，应先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt 和输出路径，再使用 `--live --only <asset-id>` 小批量生成；仅调整透明去背、裁切、画布归一或品红边缘时，可用 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用 `tmp/child-motion-demo-assets/` 中的源图，不额外请求 image-2；不得把 `VECTOR_ENGINE_API_KEY`、源图或中间预览图提交到仓库。
+7. 猫咪招手引导资源使用 `cat-guide` 透明后处理：先由 image-2 生成品红底源图，再通过边缘背景连通区域去背，避免把浅粉、淡橘和暖棕主体误删。源图只保存在 `tmp/child-motion-demo-assets/`，正式页面只引用 `public/child-motion-demo/` 下的最终 PNG。
+8. 若后续补充或重绘资源，应先运行 `npm run assets:child-motion-demo -- --dry-run` 核对 prompt 和输出路径，再使用 `--live --only <asset-id>` 小批量生成；仅调整透明去背、裁切、画布归一或品红边缘时，可用 `npm run assets:child-motion-demo -- --live --postprocess-only --force --only <asset-id>` 复用 `tmp/child-motion-demo-assets/` 中的源图，不额外请求 image-2；不得把 `VECTOR_ENGINE_API_KEY`、源图或中间预览图提交到仓库。
 
 已执行的定向验证命令：